[docs][refactor]: 将旧 01~06 中文教程合并整理为 modules/frameworks 文件夹结构

- 删除 01~05 旧中文教程目录 - 将 03 核心功能教程拆分为各 framework 模块的子文档 - 06 工具脚本移入 modules/frameworks/编辑器工具/UI工具/ - 非框架内容合并进 rules/20-开发规则.md 与 rules/40-工作流清单.md - 更新所有交叉链接与文档关联表 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-07 18:36:15 +08:00
parent 5e5b9f8c80
commit ee1ff7f444
77 changed files with 6263 additions and 1133 deletions
--- a/02_开发规范/开发规范指南.md
+++ b/02_开发规范/开发规范指南.md
@@ -1,106 +0,0 @@
-# StrayFog 框架开发规范指南
-
-## 一、开发前准备
-
-### 1.1 核心概念理解
-
-#### 1.1.1 框架层级关系
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     开发层级视图                            │
-├─────────────────────────────────────────────────────────────┤
-│  业务层 (你开发的代码)                                       │
-│  ├── UI界面、业务逻辑、游戏数据                              │
-│  │                                                         │
-│  │   ┌───────────────────────────────────────────────────┐  │
-│  │   │  核心库 (只读，框架团队维护)                        │  │
-│  │   │  ├── Core: 模拟行为、全局数据                      │  │
-│  │   │  ├── HF: 资源管理、事件系统、相机管理              │  │
-│  │   │  └── General: 状态机、工具类                      │  │
-│  │   └───────────────────────────────────────────────────┘  │
-│  │                                                         │
-│  └─────────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-#### 1.1.2 核心库访问原则
-
-| 原则 | 说明 |
-|-----|-----|
-| **只读访问** | 核心库代码只可读取，不可修改 |
-| **接口优先** | 通过接口访问服务，而非直接实例化实现类 |
-| **继承扩展** | 通过继承抽象类实现自定义逻辑 |
-| **依赖注入** | 通过管理器获取实例，而非硬编码 |
-
---
-
-## 二、业务代码结构
-
-### 2.1 目录组织规范
-
-```
-Assets/Game/GameHFScripte/GameFunction/
-├── Event/                       # 消息处理
-│   ├── ServerToClient/          # 服务器到客户端消息
-│   ├── ClientToClient/          # 客户端内部消息
-│   └── Handle/                  # 消息处理器
-
-├── GameRoot/                    # 框架调用入口
-│   ├── HFGameStart.cs           # 热更新进入入口
-│   ├── HFFunCatalogue.cs        # 框架统一调用入口
-│   ├── HFFunCatalogue_Function.cs # 功能调用方法
-│   └── ...
-
-├── HFDownLoadSubPackage/        # 分包下载
-│   ├── HFSubPackageManager.cs   # 分包管理器
-│   ├── HFGameStartAssetsCheckManager.cs # 资源检查
-│   └── ...
-
-├── HFExtends/                   # Class扩展方法
-│   ├── UI/                      # UI扩展
-│   ├── Material/                # 材质扩展
-│   ├── String/                  # 字符串扩展
-│   └── ...
-
-├── Logic/                       # 游戏主要业务逻辑（存放各功能Manager）
-│   ├── User/                    # 用户相关
-│   ├── Login/                   # 登录系统
-│   ├── Fight/                   # 战斗系统
-│   ├── CardDeck/                # 卡组系统
-│   ├── Bag/                     # 背包系统
-│   └── ...
-
-├── UIWindows/                   # UI窗口业务逻辑
-│   ├── Login/                   # 登录窗口
-│   ├── Lobby/                   # 大厅窗口
-│   ├── Fight/                   # 战斗窗口
-│   ├── Shop/                    # 商店窗口
-│   └── ...
-
-├── GameEntity/                  # 游戏实体
-│   ├── Entity/                  # 实体定义
-│   ├── EntityPool/              # 实体对象池
-│   └── ...
-
-├── SoundManagerPro/             # 音效管理
-├── SceneManager/                # 场景管理
-├── SDK/                         # SDK集成
-└── MonoCompent/                 # Mono组件
-```
-
-### 2.2 文件命名规范
-
-| 文件类型 | 命名规则 | 示例 |
-|---------|---------|-----|
-| **窗口类** | `XXXWindow.cs` | `LoginWindow.cs` |
-| **组件类** | `XXXComponent.cs` | `ItemCellComponent.cs` |
-| **管理器类** | `XXXManager.cs` | `UIManager.cs` |
-| **数据类** | `XXXData.cs` | `PlayerData.cs` |
-| **配置类** | `XXXConfig.cs` | `SkillConfig.cs` |
-
---
-
-**版本**: v1.0  
-**生效日期**: 2026年  
-**适用范围**: GiftGameX项目业务开发人员
--- a/03_核心功能/UI/UI界面拼接设计指南.md
+++ b/03_核心功能/UI/UI界面拼接设计指南.md
@@ -1,407 +0,0 @@
-# UI界面拼接设计指南
-
-## 一、界面结构设计原则
-
-### 1.1 模块化拆分
-将界面按功能划分为独立模块：
-
-| 模块类型 | 功能定位 | 示例 |
-|---------|---------|------|
-| **信息展示区** | 显示玩家状态、资源等静态信息 | 顶部信息栏、左侧状态栏 |
-| **功能入口区** | 提供功能按钮入口 | 中央功能区、底部快捷栏 |
-| **交互面板区** | 可展开/收起的功能面板 | 右侧功能面板、顶部按钮区 |
-| **输入输出区** | 用户输入和系统反馈 | 聊天输入框、提示信息 |
-
-### 1.2 经典布局模式
-
-```
-┌─────────────────────────────────────────────────────┐
-│  TopArea          (信息展示 + 可收起功能按钮)        │
-├──────────┬───────────────────────┬──────────────────┤
-│  Left    │                       │  Right           │
-│  Area    │     CenterArea        │  Area            │
-│ (状态)   │   (核心功能入口)       │ (功能面板)       │
-│          │                       │                  │
-├──────────┴───────────────────────┴──────────────────┤
-│  BottomArea       (快捷功能 + 状态信息 + 输入)       │
-└─────────────────────────────────────────────────────┘
-```
-
---
-
-## 二、组件拆分方法
-
-### 2.1 基础组件识别
-
-| 组件类型 | 识别特征 | 处理方式 |
-|---------|---------|---------|
-| **按钮** | 可点击、有交互反馈 | 使用 `SFUI_Button` |
-| **文本** | 静态/动态文字显示 | 使用 `SFUI_TextMeshProUGUI` |
-| **图片** | 图标、背景图 | 使用 `SFUI_Image` |
-| **进度条** | HP、MP、经验等 | 使用 `SFUI_Slider` |
-| **列表** | 可滚动的项目列表 | 使用 `SFUI_ScrollRect` |
-
-### 2.2 复合组件封装
-
-将功能相关的基础组件组合为复合组件，便于复用和维护：
-
-**设计原则**：
- 将同一功能模块的组件封装在一起（如玩家头像+血条+蓝条）
- 提供统一的数据设置接口
- 保持组件之间的逻辑独立性
-
---
-
-## 三、预制体层级规范
-
-### 3.1 标准层级结构
-
-```
-WindowName (RectTransform)
-├── ModuleName (RectTransform)           # 模块容器
-│   ├── ComponentName (SFUI_*)           # 功能组件
-│   ├── SubModule (RectTransform)        # 子模块
-│   └── CollapsibleArea (RectTransform)  # 可收起区域
-└── BtnCollapse (SFUI_Button)            # 收起控制按钮
-```
-
-### 3.2 命名规范
-
-| 类型 | 命名规则 | 示例 |
-|-----|---------|------|
-| 模块容器 | PascalCase + Area | `TopArea` |
-| 功能组件 | PascalCase | `BtnCollapseTop` |
-| 可收起区域 | PascalCase + FuncArea | `TopFuncArea` |
-| 状态变量 | m_ + PascalCase | `m_IsTopCollapsed` |
-
---
-
-## 四、收起/展开功能设计
-
-### 4.1 功能定义
-
-| 按钮 | 控制区域 | 用途 |
-|-----|---------|------|
-| `BtnCollapseTop` | 顶部功能按钮区 | 收起/展开顶部按钮群 |
-| `BtnCollapseRight` | 右侧功能面板区 | 收起/展开右侧功能面板 |
-
-### 4.2 设计要点
-
-**状态管理**：每个可收起区域需要一个布尔状态变量来记录当前收起/展开状态。
-
-**交互逻辑**：
-1. 点击收起按钮时，切换对应区域的显示/隐藏状态
-2. 同时切换按钮图标（收起时显示展开图标，展开时显示收起图标）
-
-**布局要求**：
- 收起按钮应放置在对应区域的边缘位置，便于用户找到
- 收起区域内的所有元素应作为一个整体进行显示/隐藏控制
- 收起状态应在窗口生命周期内保持记忆
-
---
-
-## 五、实际案例：主界面拼接
-
-### 5.1 模块化设计思想
-
-**核心原则**：将界面按功能边界划分为独立模块，模块内可嵌套子模块。
-
-**模块归类方法**：
-
-1. **一级模块**：按空间位置划分（顶部、左侧、中央、右侧、底部）
-2. **二级模块**：按功能类型划分（信息展示区、功能按钮区、输入输出区）
-3. **三级模块**：按具体功能划分（玩家头像、资源显示、功能按钮群）
-
-**层级关系示例**：
-
-```
-Window
-├── TopArea (一级：位置)
-│   ├── InfoPanel (二级：信息展示)
-│   │   └── TxtWelcome (三级：具体组件)
-│   └── FuncButtons (二级：功能按钮)
-│       └── BtnUpload (三级：具体按钮)
-└── LeftArea (一级：位置)
-    └── PlayerPortrait (二级：复合组件)
-        ├── ImgAvatar (三级：头像)
-        └── BarHP (三级：血条)
-```
-
-**设计要点**：
- 同一功能域内的元素归为同一模块（如头像、血条、蓝条归为玩家状态模块）
- 独立交互功能作为独立模块（如收起按钮单独作为控制模块）
- 可收起区域作为独立子模块，便于统一控制显示/隐藏
-
---
-
-## 六、界面拼接流程
-
-### 6.1 设计阶段
-1. **需求分析**：明确界面功能和交互需求
-2. **模块划分**：将界面拆分为独立功能模块
-3. **层级设计**：设计预制体层级结构
-
-### 6.2 开发阶段
-1. **组件创建**：创建基础组件和复合组件
-2. **预制体搭建**：按层级结构搭建预制体
-3. **脚本编写**：实现交互逻辑和收起/展开功能
-
-### 6.3 测试阶段
-1. **功能测试**：验证所有按钮和交互功能
-2. **收起测试**：测试收起/展开功能正常工作
-3. **适配测试**：验证不同分辨率下的显示效果
-
---
-
-## 七、注意事项
-
-1. **组件复用**：相同功能的组件尽量复用，减少冗余
-2. **状态管理**：收起状态需要正确保存和恢复
-3. **图标反馈**：收起按钮图标应随状态变化
-4. **性能优化**：可收起区域使用 `SetActive` 而非销毁重建
-5. **命名规范**：统一的命名规则便于维护和查找
-
---
-
-## 八、JSON配置驱动的UI生成方式
-
-### 8.1 概述
-
-**UI相关人员核心工作流程**：读取设计效果图和碎片图片，生成JSON配置文件，再通过工具自动生成Unity预制体。
-
-本项目支持JSON配置与Unity预制体的双向转换：
- **正向转换**：JSON配置 → UI预制体（核心流程）
- **反向转换**：UI预制体 → JSON配置（开发者调整完预制体后，反向生成用于版本控制或重新生成）
-
-实现UI界面的快速构建、迭代和版本控制。
-
-### 8.2 核心组件
-
-| 组件 | 职责 | 文件路径 |
-|-----|------|---------|
-| **UIPrefabGenerator** | 解析JSON并生成UI预制体 | `Assets/Editor/Command/UIPrefabGenerator.cs` |
-| **UIPrefabToJson** | 从预制体反向导出JSON | `Assets/Editor/Command/UIPrefabToJson.cs` |
-| **RemoteCommand** | 提供外部调用接口 | `Assets/Editor/Command/RemoteCommand.cs` |
-| **ExternalCommandListener** | 监听外部命令触发文件 | `Assets/Editor/Command/ExternalCommandListener.cs` |
-
-### 8.3 JSON配置文件结构
-
-```json
-{
-  "name": "BagWindow",
-  "width": 1024,
-  "height": 768,
-  "elements": [
-    {
-      "type": "Image",
-      "name": "BgPanel",
-      "anchorMin": [0, 0],
-      "anchorMax": [1, 1],
-      "position": [0, 0, 0],
-      "sizeDelta": [0, 0],
-      "sprite": "Assets/Game/GameHFResource/CN/UIWindows/BagWindow/Sprites/Bg.png"
-    },
-    {
-      "type": "Text",
-      "name": "TitleText",
-      "anchorMin": [0.5, 0.9],
-      "anchorMax": [0.5, 0.9],
-      "position": [0, 0, 0],
-      "sizeDelta": [200, 40],
-      "text": "背包",
-      "font": "Assets/Game/GameHFResource/CN/Fonts/FZY4K-M05S SDF.asset",
-      "fontSize": 28,
-      "color": [1, 1, 1, 1]
-    }
-  ]
-}
-```
-
-### 8.4 支持的UI元素类型
-
-| 类型 | 对应Unity组件 | 关键属性 |
-|-----|-------------|---------|
-| **Image** | Image | sprite, color, type, preserveAspect |
-| **TextMeshProUGUI** | TextMeshProUGUI | text, font, fontSize, color, alignment |
-| **Button** | Button | interactable, transition, navigationMode |
-| **Slider** | Slider | minValue, maxValue, value, wholeNumbers, direction |
-| **Toggle** | Toggle | isOn, toggleTransition, transition |
-| **InputField** | InputField | text, placeholder, characterLimit, contentType |
-| **ScrollRect** | ScrollRect | horizontal, vertical, movementType |
-| **GridLayoutGroup** | GridLayoutGroup | cellSize, spacing, constraint, padding |
-| **VerticalLayoutGroup** | VerticalLayoutGroup | spacing, childAlignment, padding |
-| **HorizontalLayoutGroup** | HorizontalLayoutGroup | spacing, childAlignment, padding |
-
-### 8.5 外部命令触发机制
-
-#### 8.5.1 触发方式
-
-通过创建/修改 `Trigger_Command.txt` 文件触发UI生成：
-
-```
-GenerateUIPrefab:Assets/Editor/UI/BagWindow.json
-```
-
-#### 8.5.2 命令格式
-
-```
-<命令名>:<参数1>:<参数2>:...
-```
-
-**支持的命令**：
-
-| 命令 | 参数 | 说明 |
-|-----|------|------|
-| **GenerateUIPrefab** | `jsonPath` [, `prefabPath`] | 根据JSON生成UI预制体 |
-| **ExportPrefabToJson** | `prefabPath` [, `jsonPath`] | 从预制体反向导出JSON |
-| **ReadJson** | [参数列表] | 读取JSON配置（测试用） |
-
-#### 8.5.3 完整执行流程
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│  外部系统写入命令到 Trigger_Command.txt                             │
-└─────────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  ExternalCommandListener (FileSystemWatcher) 检测到文件变化         │
-└─────────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  解析命令格式：GenerateUIPrefab:Assets/Editor/UI/BagWindow.json     │
-└─────────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  通过反射调用 RemoteCommand.GenerateUIPrefab(string[] args)         │
-└─────────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  UIPrefabGenerator.GeneratePrefabFromJson(jsonPath, prefabPath)    │
-└─────────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  生成预制体到指定路径：Assets/Game/GameHFResource/CN/UIWindows/...  │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-### 8.6 使用示例
-
-#### 方式一：外部命令触发
-
-```bash
-# 正向：从JSON生成预制体
-echo "GenerateUIPrefab:Assets/Editor/UI/BagWindow.json" > "F:\JMNet\CrystalBattle_Client\Trigger_Command.txt"
-
-# 反向：从预制体导出JSON
-echo "ExportPrefabToJson:Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab" > "F:\JMNet\CrystalBattle_Client\Trigger_Command.txt"
-```
-
-#### 方式二：Unity编辑器菜单
-
-**正向生成**：
-1. 打开Unity编辑器
-2. 点击菜单 `Tools > External > Test GenerateUIPrefab`
-3. 查看Console窗口日志确认执行结果
-
-**反向导出**：
-1. 打开Unity编辑器
-2. 点击菜单 `Tools > UI > Export Prefab to JSON`
-3. 选择要导出的预制体文件
-
-#### 方式三：代码调用
-
-```csharp
-// 正向：从JSON生成预制体
-UIPrefabGenerator.GeneratePrefabFromJson(
-    "Assets/Editor/UI/BagWindow.json",
-    "Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab"
-);
-
-// 反向：从预制体导出JSON
-UIPrefabToJson.ExportPrefabToJson(
-    "Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab",
-    "Assets/Editor/UI/BagWindow.json"
-);
-```
-
-### 8.8 注意事项
-
-1. **路径格式**：JSON中的资源路径使用 `/` 分隔符，且为Unity项目相对路径
-2. **资源引用**：确保JSON中引用的Sprite、Font等资源已存在于项目中
-3. **编码格式**：JSON文件使用UTF-8编码
-4. **坐标系统**：使用Unity RectTransform的anchorMin/anchorMax/position/sizeDelta四元组
-5. **文件锁定**：生成前确保目标预制体文件未被其他进程占用
-
-### 8.9 工具脚本部署
-
-#### 8.9.1 工具位置
-
-工具脚本位于UnityAI文档库的以下路径：
-
-```
-UnityAI/06_工具脚本/UI工具/
-├── ExternalCommandListener.cs    # 外部命令监听器
-├── RemoteCommand.cs              # 远程命令接口
-├── UIPrefabGenerator.cs          # JSON转预制体生成器
-└── UIPrefabToJson.cs             # 预制体转JSON导出器
-```
-
-#### 8.9.2 部署步骤
-
-**方法一：手动复制**
-
-1. 复制 `06_工具脚本/UI工具/` 目录下的所有文件
-2. 粘贴到目标项目的 `Assets/Editor/Command/` 目录中
-3. 确保目录结构如下：
-   ```
-   Assets/Editor/Command/
-   ├── ExternalCommandListener.cs
-   ├── RemoteCommand.cs
-   ├── UIPrefabGenerator.cs
-   └── UIPrefabToJson.cs
-   ```
-
-**方法二：自动部署脚本**
-
-创建部署脚本 `DeployUITools.bat`：
-
-```batch
-@echo off
-set "SOURCE_DIR=E:\AI\UnityAI\06_工具脚本\UI工具"
-set "TARGET_DIR=%cd%\Assets\Editor\Command"
-
-mkdir "%TARGET_DIR%" 2>nul
-xcopy "%SOURCE_DIR%\*.cs" "%TARGET_DIR%\" /y
-xcopy "%SOURCE_DIR%\*.cs.meta" "%TARGET_DIR%\" /y
-
-echo UI工具部署完成
-pause
-```
-
-#### 8.9.3 部署规则
-
-| 检查项 | 要求 |
-|-------|------|
-| **目标路径** | 必须放置在 `Assets/Editor/Command/` 目录下 |
-| **文件完整性** | 必须包含所有4个cs文件及其meta文件 |
-| **Unity版本** | 支持Unity 2020及以上版本 |
-| **依赖组件** | 需要导入 TextMeshPro 包 |
-
-#### 8.9.4 验证部署
-
-部署完成后，在Unity编辑器中验证：
-
-1. 打开Unity编辑器
-2. 检查菜单 `Tools > UI` 是否存在
-3. 检查菜单 `Tools > External` 是否存在
-4. 在Console窗口确认无编译错误
-
---
-
-**版本**: v1.2  
-**适用**: StrayFog框架UI拼接开发人员
--- a/04_开发流程/常见问题指南.md
+++ b/04_开发流程/常见问题指南.md
@@ -1,46 +0,0 @@
-# StrayFog 框架常见问题指南
-
-## 一、常见问题解答
-
-### 1.1 如何扩展核心库功能？
-
-通过继承抽象类或实现接口来扩展，不要直接修改核心库代码。
-
-### 1.2 核心库有Bug怎么办？
-
-提交Issue到框架团队，由框架团队修复并发布新版本。
-
-### 1.3 如何获取核心库的最新版本？
-
-关注内部通知，定期更新核心库引用。
-
-### 1.4 如何调试核心库代码？
-
-可以设置断点调试，但不允许修改代码。
-
---
-
-## 附录
-
-### A. 常用核心库API
-
-| 类别 | 管理器 | 常用方法 |
-|-----|-------|---------|
-| **对象池** | `HFObjectMemPool` | `GetItem()`, `GiveBack()` |
-| **事件** | `IHFEventHandle` | `AddListener()`, `Dispatch()` |
-| **资源** | `HFABMgr` | `OnStartLoad()` |
-| **相机** | `HFCameraManager` | `AddCamera()`, `GetCamera()` |
-
-### B. 核心库只读目录
-
-```
-Assets/StrayFog/Core/
-Assets/Game/GameHFScripte/CopyToHF/
-Assets/Game/GameGeneralScripte/
-```
-
---
-
-**版本**: v1.0  
-**生效日期**: 2026年  
-**适用范围**: GiftGameX项目业务开发人员
--- a/04_开发流程/开发流程指南.md
+++ b/04_开发流程/开发流程指南.md
@@ -1,108 +0,0 @@
-# StrayFog 框架开发流程指南
-
-## 一、文档学习阶段
-
-### 1.1 必读文档清单
-
-| 优先级 | 文档路径 | 目的 |
-|-------|---------|-----|
-| P0 | `01_框架架构/StrayFog框架架构分析.md` | 理解框架整体架构 |
-| P0 | `02_开发规范/开发规范指南.md` | 掌握编码规范和命名约定 |
-| P1 | `03_核心功能/事件系统使用指南.md` | 理解事件驱动机制 |
-| P1 | `03_核心功能/对象池使用指南.md` | 掌握对象池复用机制 |
-| P1 | `03_核心功能/资源管理使用指南.md` | 理解资源加载流程 |
-
-### 1.2 功能专项文档
-
-根据开发任务类型，必须阅读对应的专项指南：
-
-| 任务类型 | 必读文档 |
-|---------|---------|
-| UI开发 | `03_核心功能/UI/UI开发指南.md` |
-| UI界面设计 | `03_核心功能/UI/UI界面拼接设计指南.md` |
-| 相机控制 | `03_核心功能/相机系统使用指南.md` |
-
-### 1.3 输出要求
-
-完成文档学习后，开发人员必须输出：
-1. **工作流程说明**：详细描述从需求到交付的完整步骤
-2. **技术选型说明**：明确使用的框架组件和API
-3. **风险评估**：识别潜在问题和解决方案
-
---
-
-## 二、需求分析
-
-### 2.1 需求分析步骤
-
-1. **明确需求**：理解业务需求，确定需要实现的功能
-2. **评估复杂度**：判断是否需要核心库支持或扩展
-3. **设计方案**：规划代码结构和调用关系
-
---
-
-## 三、代码编写
-
-### 3.1 代码编写步骤
-
-1. **创建目录**：在`GameBusiness`下创建对应模块目录
-2. **编写代码**：遵循编码规范，使用核心库提供的API
-3. **测试验证**：在Unity中测试功能正确性
-
---
-
-## 四、代码审查
-
-### 4.1 代码审查流程
-
-1. **自我检查**：检查是否符合规范，是否有潜在问题
-2. **团队审查**：提交代码进行团队审查
-3. **修复问题**：根据审查意见修改代码
-
---
-
-## 五、集成测试
-
-### 5.1 测试阶段
-
-1. **模块测试**：测试单个模块功能
-2. **集成测试**：测试模块间交互
-3. **回归测试**：确保不影响现有功能
-
---
-
-## 六、Git提交规范
-
-### 6.1 提交格式要求
-
-所有代码提交必须遵循以下格式：
-
-```
-【操作原因】具体操作内容
-```
-
-### 6.2 操作原因分类
-
-| 分类 | 说明 | 适用场景 |
-|------|------|----------|
-| 【初始化】 | 首次创建或上传 | 新项目初始化、首次上传文档 |
-| 【更新】 | 修改或完善现有内容 | 更新文档、优化代码 |
-| 【新增】 | 添加新文件或功能 | 新增文档、新增代码模块 |
-| 【修复】 | 修复错误或问题 | 修复Bug、修正文档错误 |
-| 【重构】 | 重构代码或文档结构 | 优化架构、重新组织文档 |
-| 【删除】 | 删除文件或功能 | 删除无用文件、移除废弃代码 |
-| 【配置】 | 修改配置文件 | 更新配置、调整参数 |
-
-### 6.3 提交示例
-
-```bash
-git commit -m "【更新】修复UI窗口打开时的空指针异常"
-git commit -m "【新增】添加战斗系统核心模块"
-git commit -m "【修复】修正开发流程指南中的错误描述"
-```
-
---
-
-**版本**: v1.0  
-**生效日期**: 2026年  
-**适用范围**: GiftGameX项目业务开发人员
--- a/04_开发流程/最佳实践指南.md
+++ b/04_开发流程/最佳实践指南.md
@@ -1,49 +0,0 @@
-# StrayFog 框架最佳实践指南
-
-## 一、性能优化
-
-### 1.1 对象池使用
-
- 频繁创建销毁的对象必须使用对象池
- 合理设置对象池初始容量
- 定期清理空闲对象避免内存泄漏
-
-### 1.2 资源管理
-
- 及时释放不再使用的资源
- 使用异步加载避免卡顿
- 合理使用资源缓存
-
---
-
-## 二、代码组织
-
-### 2.1 单一职责
-
- 每个类只负责一个功能
- 避免庞大的God类
-
-### 2.2 依赖管理
-
- 通过管理器获取依赖，而非硬编码
- 使用接口解耦依赖关系
-
---
-
-## 三、错误处理
-
-### 3.1 异常捕获
-
- 在关键路径添加异常处理
- 记录错误日志便于排查
-
-### 3.2 防御性编程
-
- 检查参数合法性
- 处理空引用情况
-
---
-
-**版本**: v1.0  
-**生效日期**: 2026年  
-**适用范围**: GiftGameX项目业务开发人员
--- a/05_项目管理/Git提交注意事项.md
+++ b/05_项目管理/Git提交注意事项.md
@@ -1,21 +0,0 @@
-# Git 提交注意事项
-
-## 默认提交路径
-
- **默认仓库**：上传 Git 时，默认路径为 `E:\AI\UnityAI`
- **路径规则**：除非用户明确指定项目工程路径，否则所有 Git 操作均针对 `E:\AI\UnityAI` 仓库
- **项目区分**：若需操作其他项目（如 `F:\JMNet\GiftGameX`），必须在指令中明确指定
-
-## Git 操作原则
-
- **路径确认**：执行 Git 操作前，确认当前操作路径是否正确
- **分支管理**：遵循项目既定的分支策略
- **提交规范**：使用语义化提交信息，清晰描述更改内容
- **代码审查**：重要功能提交前建议先创建分支进行测试
-
-## 常见操作
-
- 查看状态：`git status`
- 添加更改：`git add .`
- 提交更改：`git commit -m "描述信息"`
- 推送到远程：`git push origin <branch-name>`
--- a/05_项目管理/Git规定指南.md
+++ b/05_项目管理/Git规定指南.md
@@ -1,115 +0,0 @@
-# UnityAI Git 规定指南
-
-## 一、提交日志格式规范
-
-### 1.1 格式要求
-
-所有 Git 提交日志必须遵循以下格式：
-
-```
-【操作原因】具体操作内容
-```
-
-### 1.2 格式说明
-
-| 部分 | 说明 | 示例 |
-|------|------|------|
-| `【操作原因】` | 用中文方括号包裹，描述本次操作的核心目的 | 【初始化】、【更新】、【修复】 |
-| `具体操作内容` | 详细描述本次提交的内容，使用中文 | 上传框架文档、修改配置文件 |
-
-### 1.3 操作原因分类
-
-| 分类 | 说明 | 适用场景 |
-|------|------|----------|
-| **【初始化】** | 首次创建或上传项目/文档 | 新项目初始化、首次上传文档 |
-| **【更新】** | 修改或完善现有内容 | 更新文档内容、优化代码逻辑 |
-| **【新增】** | 添加新的文件或功能 | 新增文档、新增代码模块 |
-| **【修复】** | 修复错误或问题 | 修复文档错误、修复代码Bug |
-| **【重构】** | 重构代码结构或文档结构 | 优化代码架构、重新组织文档 |
-| **【删除】** | 删除文件或功能 | 删除无用文件、移除废弃代码 |
-| **【迁移】** | 迁移文件或项目 | 文件位置调整、项目迁移 |
-| **【配置】** | 修改配置文件 | 更新配置、调整参数 |
-
---
-
-## 二、提交日志示例
-
-### 2.1 文档相关
-
-```
-【初始化】上传UnityAI框架文档，包含StrayFog框架架构分析、业务开发指南、核心库保护规范
-【更新】完善StrayFog框架架构分析中Core层的描述
-【新增】添加Git规定指南文档
-【修复】修正业务开发指南中的代码示例错误
-```
-
-### 2.2 代码相关
-
-```
-【新增】实现AI决策系统核心模块
-【更新】优化对象池性能
-【修复】修复事件系统内存泄漏问题
-【重构】重构技能系统架构
-【删除】移除废弃的测试代码
-```
-
-### 2.3 配置相关
-
-```
-【配置】更新构建脚本参数
-【配置】调整日志输出级别
-```
-
---
-
-## 三、Git 工作流程
-
-### 3.1 提交流程
-
-```
-修改文件
-    │
-    ▼
-git add .          # 暂存所有修改
-    │
-    ▼
-git commit -m "【操作原因】具体操作内容"   # 提交并撰写规范日志
-    │
-    ▼
-git push           # 推送到远程仓库
-```
-
-### 3.2 分支管理
-
-| 分支名称 | 用途 |
-|----------|------|
-| `master` | 主分支，稳定版本 |
-| `develop` | 开发分支，日常开发 |
-| `feature/*` | 功能分支，开发新功能 |
-| `bugfix/*` | Bug修复分支 |
-
-### 3.3 远程仓库信息
-
- **仓库地址**: `https://jinmt.com/Shiliang/UnityAI.git`
- **用户名**: *请在本地配置，不要提交到仓库*
- **密码**: *请在本地配置，不要提交到仓库*
-
-**本地配置方法**：
-1. 使用 `git config credential.helper store` 配置凭证存储
-2. 首次推送时输入用户名密码，系统会自动保存到本地
-
---
-
-## 四、注意事项
-
-1. **日志语言**: 统一使用中文描述
-2. **简洁明了**: 日志应简洁清晰，准确反映提交内容
-3. **分类准确**: 选择合适的操作原因分类
-4. **避免空提交**: 禁止无内容的空提交
-5. **定期推送**: 开发完成后及时推送到远程仓库
-
---
-
-**版本**: v1.0  
-**生效日期**: 2026年5月22日  
-**适用范围**: UnityAI项目团队
--- a/05_项目管理/核心库保护规范.md
+++ b/05_项目管理/核心库保护规范.md
@@ -1,80 +0,0 @@
-# StrayFog 框架核心库保护规范
-
-## 一、核心库定义
-
-### 1.1 核心库范围（只读）
-
-| 路径 | 说明 |
-|------|------|
-| `Assets/StrayFog/Core` | 基础框架核心 |
-| `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架 |
-| `Assets/Game/GameGeneralScripte` | 通用工具层 |
-
---
-
-## 二、保护规则
-
-### 2.1 访问方式
-
-**业务代码必须通过 `HFFunCatalogue` 统一入口访问核心库：**
-
-```csharp
-// ✅ 正确：通过统一入口访问
-HFFunCatalogue.UIManager.OpenWindow<LoginWindow>();
-HFFunCatalogue.Asset.LoadAsset<GameObject>("path");
-HFFunCatalogue.Scene.LoadScene("MainScene");
-
-// ❌ 禁止：直接访问核心库
-HFUIWindowMgr.Instance.OpenWindow<LoginWindow>(); // 禁止
-HFABMgr.Instance.LoadAsset<GameObject>("path");   // 禁止
-```
-
-### 2.2 禁止操作
-
-| 禁止行为 | 后果 |
-|---------|------|
-| 修改核心库源代码 | 破坏框架稳定性 |
-| 删除/重命名核心库文件 | 编译错误 |
-| 直接实例化核心库内部类 | 违反封装原则 |
-| 绕过 `HFFunCatalogue` 直接调用核心库单例 | 难以维护和测试 |
-
---
-
-## 三、修改流程
-
-```
-业务人员发现问题/需求
-        │
-        ▼
- 提交Issue到框架团队
-        │
-        ▼
- 框架团队评估需求
-        │
-   ┌────┴────┐
-   │         │
- 合理      不合理
-   │         │
-   ▼         ▼
- 开发修复   反馈拒绝
-   │
-   ▼
- 代码审查 → 发布新版本 → 业务团队更新引用
-```
-
---
-
-## 四、违规处理
-
-| 等级 | 违规行为 | 处理方式 |
-|-----|---------|---------|
-| **轻微** | 误修改注释、空行 | 警告+恢复 |
-| **一般** | 修改非核心逻辑 | 通报批评+代码回滚 |
-| **严重** | 修改核心逻辑导致Bug | 绩效扣分+修复责任 |
-| **重大** | 删除核心文件导致崩溃 | 追责+修复责任 |
-
---
-
-**版本**: v1.0  
-**生效日期**: 2024年  
-**适用范围**: OnlineGame项目
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -0,0 +1,31 @@
+# UnityAI - Codex 入口
+
+本文件是 Codex 的项目级入口包装。
+
+处理本项目任务时，**先读取 `ai/AI接入入口.md`**，再按其中说明读取项目规则、项目知识和共享 hook 文档。
+
+---
+
+## AI 接入入口
+
+- **[ai/AI接入入口.md](ai/AI接入入口.md)** — 所有 AI / IDE 工具的接入总入口。
+
+## 说明
+
+- 不要把项目规则重复写在你的系统提示里。
+- 所有项目规则维护在 `rules/`。
+- 所有项目模块知识维护在 `modules/`。
+- 共享 hook 规则和检查脚本维护在 `hooks/`。
+- Codex 私有目录只放适配器，不复制项目规则。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [ai/AI接入入口.md](ai/AI接入入口.md) | AGENTS.md 指向 AI 接入入口，入口变更需同步 |
+| [CLAUDE.md](CLAUDE.md) | Claude Code 入口与 AGENTS.md 互为替代入口 |
+| [RULES.md](RULES.md) | 通用兼容入口需与 AGENTS.md 保持一致 |
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,33 @@
+# UnityAI - Claude Code 入口
+
+本文件是 Claude Code 的入口包装。
+
+处理本项目任务时，**先读取 `ai/AI接入入口.md`**，再按其中说明读取项目规则、项目知识和共享 hook 文档。
+
+---
+
+## AI 接入入口
+
+- **[ai/AI接入入口.md](ai/AI接入入口.md)** — 所有 AI / IDE 工具的接入总入口。
+
+## 说明
+
+- 不要把项目规则重复写在你的系统提示里。
+- 所有项目规则维护在 `rules/`。
+- 所有项目模块知识维护在 `modules/`。
+- 共享 hook 规则和检查脚本维护在 `hooks/`。
+- 若已配置 OpenSpec，Claude Code 用户可使用命令：`/opsx:propose`、`/opsx:apply`、`/opsx:archive`。
+- 只有用户明确说“提交”“提交代码”“commit”或使用 `/commit` 时，才触发提交流程。
+- 若已配置自定义提交命令 `/commit` 或 git `prepare-commit-msg` hook，按项目实际配置使用。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [ai/AI接入入口.md](ai/AI接入入口.md) | CLAUDE.md 指向 AI 接入入口，入口变更需同步 |
+| [AGENTS.md](AGENTS.md) | Claude Code 入口与 AGENTS.md 互为替代入口 |
+| [RULES.md](RULES.md) | 通用兼容入口需与 CLAUDE.md 保持一致 |
--- a/README.md
+++ b/README.md
@@ -1,40 +1,73 @@
-# UnityAI - StrayFog框架文档中心
+# UnityAI - StrayFog 框架文档中心

-## 📋 文档索引
+本仓库是 **StrayFog 框架的知识库**，同时服务两类读者：

-### 01_框架架构
- [StrayFog框架架构分析](01_框架架构/StrayFog框架架构分析.md)
+- **人工开发者**：通过 `modules/frameworks/` 下的框架模块文档和 `rules/` 下的规则文档学习使用 StrayFog 框架。
+- **AI 工具**：通过 `ai/`、`rules/`、`modules/`、`hooks/` 下的规则、模块、hook 文档快速理解框架结构和工作方式。

-### 02_开发规范
- [开发规范指南](02_开发规范/开发规范指南.md)
+---

-### 03_核心功能
- [对象池使用指南](03_核心功能/对象池使用指南.md)
- [事件系统使用指南](03_核心功能/事件系统使用指南.md)
- [资源管理使用指南](03_核心功能/资源管理使用指南.md)
- [相机系统使用指南](03_核心功能/相机系统使用指南.md)
+## 🚀 快速入口

-#### Entity相关
- [Entity开发指南](03_核心功能/Entity/Entity开发指南.md) - Entity创建规范、生命周期、System-Model架构、属性系统、对象池
- [UnityEntities注意事项](03_核心功能/Entity/UnityEntities注意事项.md) - 枚举定义、ESM架构、数据表字段映射、动画系统、AI系统、错误处理、架构模式
- [通用技能系统使用指南](03_核心功能/Entity/通用技能系统使用指南.md) - 通用技能系统架构、使用方法、配置管理、事件系统
+| 读者 | 入口 |
+|------|------|
+| AI 工具 | [AGENTS.md](AGENTS.md) / [CLAUDE.md](CLAUDE.md) / [RULES.md](RULES.md) → [ai/AI接入入口.md](ai/AI接入入口.md) |
+| 人工开发者 | 继续阅读下方中文文档索引 |

-#### UI相关
- [UI开发指南](03_核心功能/UI/UI开发指南.md) - 窗口开发、组件使用、事件绑定、对象池、开发规范
- [UI界面拼接设计指南](03_核心功能/UI/UI界面拼接设计指南.md) - 界面模块化设计、布局规划、模块组装
+---

-### 04_开发流程
- [开发流程指南](04_开发流程/开发流程指南.md)
- [最佳实践指南](04_开发流程/最佳实践指南.md)
- [常见问题指南](04_开发流程/常见问题指南.md)
+## 🤖 AI 工具说明

-### 05_项目管理
- [核心库保护规范](05_项目管理/核心库保护规范.md)
- [Git规定指南](05_项目管理/Git规定指南.md)
- [Git提交注意事项](05_项目管理/Git提交注意事项.md)
+处理本仓库任务时，AI 工具应：

-### 06_工具脚本
- [UI工具](06_工具脚本/UI工具/) - UI预制体与JSON双向转换工具
+1. 读取 [ai/AI接入入口.md](ai/AI接入入口.md)
+2. 读取 [rules/项目规则入口.md](rules/项目规则入口.md)
+3. 按需读取 [modules/模块索引.md](modules/模块索引.md) 中的框架模块
+4. 如需了解外部项目业务参考，读取 [business-reference/playballoons/业务框架映射接口.md](business-reference/playballoons/业务框架映射接口.md)
+
+---
+
+## 📋 中文文档索引
+
+### 框架架构
+- [通用框架](modules/frameworks/通用框架/README.md) — General/StrayFog Core 通用能力
+- [框架架构分析](modules/frameworks/通用框架/框架架构.md) — StrayFog 整体架构分析
+
+### 核心框架
+- [实体系统](modules/frameworks/实体系统/README.md)
+  - [Entity 开发指南](modules/frameworks/实体系统/开发指南.md)
+  - [Unity Entities 注意事项](modules/frameworks/实体系统/注意事项.md)
+- [技能系统](modules/frameworks/技能系统/README.md)
+  - [通用技能系统使用指南](modules/frameworks/技能系统/使用指南.md)
+- [UI 窗口系统](modules/frameworks/UI窗口系统/README.md)
+  - [UI 开发指南](modules/frameworks/UI窗口系统/开发指南.md)
+  - [UI 界面拼接设计指南](modules/frameworks/UI窗口系统/界面拼接.md)
+- [事件系统](modules/frameworks/事件系统/README.md)
+  - [事件系统使用指南](modules/frameworks/事件系统/使用指南.md)
+- [对象池与运行时对象管理](modules/frameworks/内存对象管理/README.md)
+  - [对象池使用指南](modules/frameworks/内存对象管理/使用指南.md)
+- [相机系统](modules/frameworks/相机系统/README.md)
+  - [相机系统使用指南](modules/frameworks/相机系统/使用指南.md)
+- [资源管理](modules/frameworks/资源管理/README.md)
+  - [资源管理使用指南](modules/frameworks/资源管理/使用指南.md)
+- [场景系统](modules/frameworks/场景系统.md)
+- [网络系统](modules/frameworks/网络系统.md)
+- [数据配置框架](modules/frameworks/数据配置框架.md)
+- [Hotfix 启动](modules/frameworks/Hotfix启动.md)
+- [第三方插件](modules/frameworks/第三方插件.md)
+
+### 编辑器工具
+- [编辑器工具](modules/frameworks/编辑器工具/README.md)
+  - [UI 拼接工具](modules/frameworks/编辑器工具/UI拼接工具.md)
+
+### 项目规则
+- [项目规则入口](rules/项目规则入口.md)
+- [架构说明](rules/10-架构说明.md)
+- [开发规则](rules/20-开发规则.md)
+- [工作流清单](rules/40-工作流清单.md)
+
+### 编辑器工具脚本
+- [UI 工具](modules/frameworks/编辑器工具/UI工具/) — UI 预制体与 JSON 双向转换工具

 ---

@@ -42,12 +75,32 @@

 | 场景 | 推荐文档 |
 |-----|---------|
-| 新人开发 | `02_开发规范/开发规范指南.md` |
-| 使用对象池 | `03_核心功能/对象池使用指南.md` |
-| 使用事件系统 | `03_核心功能/事件系统使用指南.md` |
-| 遇到问题 | `04_开发流程/常见问题指南.md` |
+| 新人开发 | [开发规则](rules/20-开发规则.md) |
+| 使用对象池 | [对象池与运行时对象管理](modules/frameworks/内存对象管理/README.md) |
+| 使用事件系统 | [事件系统](modules/frameworks/事件系统/README.md) |
+| 遇到问题 | [开发规则/常见问题](rules/20-开发规则.md#常见问题) |
+| AI 工具接入 | [ai/AI接入入口.md](ai/AI接入入口.md) |
+
+---
+
+## 📦 业务参考
+
+- [business-reference/playballoons/](business-reference/playballoons/) — 来自 PlayBalloons 实际项目的业务参考，与 StrayFog 框架核心分离。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [ai/AI接入入口.md](ai/AI接入入口.md) | AI 工具入口说明 |
+| [rules/项目规则入口.md](rules/项目规则入口.md) | 项目规则总入口 |
+| [modules/模块索引.md](modules/模块索引.md) | 框架模块索引 |
+| [rules/00-项目概览.md](rules/00-项目概览.md) | 项目概览中的人工开发者使用方式 |

 ---

 **版本**: v1.0  
-**适用项目**: GiftGameX
+**适用项目**: GiftGameX
--- a/RULES.md
+++ b/RULES.md
@@ -0,0 +1,21 @@
+# UnityAI 通用入口
+
+本文件是给其他 AI、IDE 或人工快速查看的兼容入口。
+
+**请先读取：[ai/AI接入入口.md](ai/AI接入入口.md)**
+
+---
+
+> 本文件仅保留为兼容入口，不重复维护项目规则内容。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [ai/AI接入入口.md](ai/AI接入入口.md) | RULES.md 是 AI 接入入口的兼容重定向 |
+| [AGENTS.md](AGENTS.md) | AI 工具入口之一，需与 RULES.md 保持一致 |
+| [CLAUDE.md](CLAUDE.md) | Claude Code 入口，需与 RULES.md 保持一致 |
--- a/ai/AI接入入口.md
+++ b/ai/AI接入入口.md
@@ -0,0 +1,65 @@
+# AI 工具接入入口
+
+本文件是 UnityAI / StrayFog 框架知识库面向 Codex、Claude Code、Cursor、Windsurf、GitHub Copilot 等 AI / IDE 工具的统一接入说明。
+
+根目录入口文件只做适配和跳转：
+
+- `AGENTS.md`：Codex 默认项目入口。
+- `CLAUDE.md`：Claude Code 默认项目入口。
+- `RULES.md`：通用兼容入口，给其他 AI、IDE 或人工快速查看。
+
+这些入口文件不要复制项目规则；真实内容统一维护在 ai/rules/modules/hooks/ 下。
+
+## 所有 AI 先读
+
+处理本项目任务时，按顺序读取：
+
+1. [项目规则入口](../rules/项目规则入口.md)
+2. [项目知识入口](../modules/模块索引.md)
+3. [共享 hook 入口](../hooks/Hook共享层.md)
+
+然后根据任务范围按需读取具体规则、模块、spec、plan 或 hook 文档。
+
+## 文档分层
+
+| 层级 | 文档 | 用途 |
+|---|---|---|
+| AI 接入层 | `ai/AI接入入口.md` | 说明不同 AI / IDE 工具如何进入项目 |
+| 项目规则层 | `rules/项目规则入口.md` | 工作方式、扫描范围、任务流程、归档规则 |
+| 项目知识层 | `modules/模块索引.md` | 项目框架、核心功能、编辑器工具总入口 |
+| 业务参考层 | `business-reference/` | 外部实际项目业务参考，与框架核心分离 |
+| Hook 共享层 | `hooks/Hook共享层.md` | 共享 hook 原则、检查脚本、触发方式 |
+| Spec / Plan 层 | `specs/Spec索引.md`、`plans/` | 大需求、新模块、跨模块计划和归档 |
+
+## Hook 接入原则
+
+- 共享 hook 规则、脚本和文档关联逻辑统一放在 `hooks/`。
+- 各 AI 工具自己的目录只放适配器，不重复维护 hook 逻辑。
+- 若已配置 Codex，适配器 `.codex/hooks/archive-reminder.ps1` 可调用 `hooks/archive-check.ps1`。
+- Claude Code 可以通过 command / hook 配置调用 `hooks/archive-check.ps1`。
+- 只有用户明确说“提交”“提交代码”“commit”时，才触发提交流程。
+- 若项目配置了自定义提交命令 `/commit` 或 git `prepare-commit-msg` hook，按实际配置使用，默认提交信息格式为 `[模块][feat]:内容描述`。
+- 如需在关联文档中自动留下变更提醒，可调用 `hooks/sync-doc-associations.ps1`（只追加、不覆盖，执行后需 review）。
+- 其他 AI / IDE 如果支持任务结束 hook，也应调用 `hooks/archive-check.ps1`。
+- 如果某个工具不支持自动 hook，任务结束时手动运行或按 `hooks/Hook共享层.md` 执行归档检查。
+
+## 新接入 AI 工具时
+
+1. 确认该工具默认读取什么入口文件。
+2. 如果该工具有默认入口文件，只在入口文件中指向 `ai/AI接入入口.md`。
+3. 如果该工具支持 hook，配置它调用 `hooks/archive-check.ps1`。
+4. 不要把 `rules/`、`modules/`、`hooks/` 的内容复制进工具私有目录。
+5. 如需新增工具专属说明，只写适配方式，不写项目规则副本。
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [AGENTS.md](../AGENTS.md) | Codex 入口应指向本 AI 接入入口 |
+| [CLAUDE.md](../CLAUDE.md) | Claude Code 入口应指向本 AI 接入入口 |
+| [RULES.md](../RULES.md) | 通用兼容入口应指向本 AI 接入入口 |
+| [rules/项目规则入口.md](../rules/项目规则入口.md) | 项目规则入口由本文档引用 |
+| [modules/模块索引.md](../modules/模块索引.md) | 项目知识入口由本文档引用 |
+| [hooks/Hook共享层.md](../hooks/Hook共享层.md) | 共享 hook 入口由本文档引用 |
--- a/business-reference/playballoons/features/GM调试.md
+++ b/business-reference/playballoons/features/GM调试.md
@@ -0,0 +1,134 @@
+# GM/调试功能
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录 GM 面板、调试请求、测试入口和开发验证流程。
+
+## 已知线索
+
+- UI 路径：`Assets/Game/GameHFScripte/GameFunction/UIWindows/GMWindow/`
+- 背包数据：`GMWindow_BagData.cs`
+- 请求配置：`GMWindow_GM.cs`
+- 能看到背包、战斗、商店等调试请求线索。
+
+## 已确认内容
+
+窗口定义：
+
+```text
+GMWindow : AbsHFUIWindow
+  -> [HFAssetBundlePath(..., "UIWindows/GMWindow/GMWindow.prefab")]
+  -> [HFUIWindowLayer(UIWindow, Popup)]
+```
+
+生命周期：
+
+```text
+GMWindow.OnRunAwake()
+  -> OnRunAwake_BagData()
+  -> OnRunAwake_GM()
+
+GMWindow.OnOpen()
+  -> OnOpen_BagData()
+  -> OnOpen_GM()
+
+GMWindow.OnClose()
+  -> OnClose_BagData()
+  -> OnClose_GM()
+```
+
+GM 请求结构：
+
+```text
+GM_Network_MsgId
+  -> msgId : Network_MsgId
+  -> tip
+  -> args : List<GM_Network_MsgId_Arg>
+
+GM_Network_MsgId_Arg
+  -> tip
+  -> contentType
+  -> value
+```
+
+发送链路：
+
+```text
+点击 btnSendGM
+  -> OnSendGM()
+  -> new GMC2S()
+  -> gmC2S.Msgid = (int)selected.msgId
+  -> gmC2S.Args.AddRange(...)
+  -> HFSeverManager.Instance.SendMsg(gmC2S)
+```
+
+当前 GM 覆盖范围：
+
+- 背包：
+  - 请求背包数据：`GetBagItem`
+  - 添加道具：`PlayerResourceChange`
+- 关卡：
+  - `BattleLevelEnter`
+  - `BattleLevelExit`
+  - `BattleLevelWin`
+  - `BattleLevelFail`
+- 用户外围数据：
+  - 设置关卡完成波数：`SetUserRolePeripheryLevelWaveProgress`
+  - 领取用户关卡进度奖励：`UserRolePeripheryClaimedProgressReward1Reward`
+- 时间：
+  - `GetServerTimeStamp`
+- 宝箱：
+  - 添加用户宝箱：`AddUserRolePeripheryTreasureChest`
+  - 删除用户宝箱：`DelUserRolePeripheryTreasureChest`
+  - 获取/开启/领取/结束冷却相关操作存在注释。
+- 商店：
+  - `SetDailyFeaturedTotalRefreshCount` 使用硬编码 `(Network_MsgId)7090`。
+- Tower：
+  - 上阵、下阵、升级、添加 Tower 的 GM 配置块存在，但全部注释。
+
+当前接入状态：
+
+- GMWindow 本身是完整 UI 窗口。
+- GM 请求通过统一 `GMC2S` 包装真实业务 `Network_MsgId` 和参数。
+- 未看到明显的开发环境开关；MainWindow 中 GM 按钮也有编辑器开关注释，当前入口是否开放待确认。
+
+## 梳理任务
+
+- [ ] 梳理 GMWindow 打开入口。
+- [x] 梳理 GM 请求结构和参数配置。
+- [x] 梳理 GM 对背包、PVE、商店等功能的覆盖范围。
+- [ ] 梳理 GM 功能是否只在开发环境启用。
+- [x] 梳理 GM 请求和网络框架的关系。
+
+## 待确认
+
+- GMWindow 的正式打开入口待确认。
+- 是否有权限/环境开关待确认。
+- 是否允许线上包保留 GM 面板待确认。
+- GM 操作通过服务器 GM 协议，有修改服务器数据的能力风险，需要上线前明确禁用策略。
+
+## 相关框架
+
+- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
+- [网络框架](../../../modules/frameworks/网络系统.md)
+- [事件框架](../../../modules/frameworks/事件系统/README.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/事件系统/README.md](../../../modules/frameworks/事件系统/README.md) | 事件框架 |
+| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 |
+| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 |
--- a/business-reference/playballoons/features/PVE关卡战斗.md
+++ b/business-reference/playballoons/features/PVE关卡战斗.md
@@ -0,0 +1,94 @@
+# PVE/关卡战斗
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录 PVE 关卡进入、战斗流程、胜负结算、波次和奖励逻辑。
+
+## 已知线索
+
+- 逻辑路径：`Assets/Game/GameHFScripte/GameFunction/Logic/GameScenes/`
+- 地图路径：`Assets/Game/GameHFScripte/GameFunction/Logic/MapManager/`
+- 伤害路径：`Assets/Game/GameHFScripte/GameFunction/Logic/DamageManager/`
+- 地图资源：`Assets/Game/GameHFResource/CN/Map/`
+- 网络消息线索：`BattleLevelEnter`、`BattleLevelExit`、`BattleLevelWin`、`BattleLevelFail`
+- 配置线索：`XLSX_SRC/CN/Wave.xlsx`
+
+## 已确认内容
+
+当前 PVE/关卡战斗处于“有核心框架和协议线索，但主流程接入不完整或待确认”的状态。
+
+已确认的子系统：
+
+- `HFWaveManager`：从 `HFFunCatalogue.NDB.ds_WaveD0D9AA20TableData.ReadTableList()` 读取波次配置。
+- `WaveInfo`：根据 `WaveTime`、`WaveID`、`WaveHpInc`、`GateFirst` 生成波次信息。
+- `CreateMonsterInfo`：解析 `start_end_delay_monsterId_count` 格式的发怪配置。
+- `HFMapManager.CreateMap(levelid, finish)`：当前会先 `ClearMap()`，再通过 `HFFunCatalogue.Asset.LoadAsset(1501, ...)` 加载地图 prefab。
+- `HFDamageManager`：存在伤害计算、掉落、死亡事件、HUD 飘字逻辑，但大部分实现当前被注释。
+- 网络协议和事件已生成：`BattleLevelEnter`、`BattleLevelExit`、`BattleLevelWin`、`BattleLevelFail`。
+
+`HFWaveManager` 当前有 Editor GUI 调试入口：
+
+```text
+OnRunGUI
+  -> 按钮“游戏开始”
+  -> InitCampWaveInfo(Red/Blue)
+  -> TryCreateMonster
+```
+
+`OnRunFixedUpdate` 每秒尝试发怪：
+
+```text
+OnRunFixedUpdate
+  -> TryCreateMonster
+  -> CampWaveInfo.TryCreateMonster
+  -> WaveInfo.TryCreateMonster
+  -> CreateMonsterInfo.TryCreateMonster
+```
+
+## 梳理任务
+
+- [ ] 找到 PVE 入口：从主界面、地图或 GM 进入关卡的调用点。
+- [ ] 梳理关卡状态：进入、战斗中、胜利、失败、退出。
+- [x] 梳理波次配置和怪物/实体生成关系。
+- [x] 梳理伤害计算和实体框架之间的关系。
+- [ ] 梳理结算奖励如何进入背包和奖励展示。
+- [x] 梳理 PVE 相关网络消息和事件。
+
+## 待确认
+
+- 是否有明确的 PVE manager。
+- 战斗是纯本地模拟、服务器校验，还是服务器主导。
+- `GameScenes`、`MapManager`、`LineManager` 在 PVE 中的边界。
+- `HFMapManager.CreateMap` 的 `levelid` 当前未用于读表，资源 id 固定为 `1501`，是否临时逻辑待确认。
+- `HFWaveManager` 是否只通过 Editor GUI 调试启动，还是存在运行时入口待确认。
+- `HFDamageManager` 大量逻辑被注释，当前战斗伤害是否启用待确认。
+
+## 相关框架
+
+- [实体框架](../../../modules/frameworks/实体系统/README.md)
+- [场景框架](../../../modules/frameworks/场景系统.md)
+- [网络框架](../../../modules/frameworks/网络系统.md)
+- [事件框架](../../../modules/frameworks/事件系统/README.md)
+- [数据/配置框架](../../../modules/frameworks/数据配置框架.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 |
+| [modules/frameworks/实体系统/README.md](../../../modules/frameworks/实体系统/README.md) | 实体框架 |
+| [modules/frameworks/事件系统/README.md](../../../modules/frameworks/事件系统/README.md) | 事件框架 |
+| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 |
+| [modules/frameworks/场景系统.md](../../../modules/frameworks/场景系统.md) | 场景框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 |
--- a/business-reference/playballoons/features/PVP.md
+++ b/business-reference/playballoons/features/PVP.md
@@ -0,0 +1,80 @@
+# PVP
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录 PVP 是否存在、入口、协议、匹配、战斗和结算流程。
+
+## 已知线索
+
+- 当前未在初步扫描中发现明确的 PVP 目录或关键词。
+
+## 已确认内容
+
+已搜索关键词：
+
+- `PVP`
+- `PvP`
+- `pvp`
+- `Arena`
+- `Rank`
+- `Duel`
+- `竞技`
+- `排行`
+- `匹配`
+
+搜索范围：
+
+- `Assets/Game/GameHFScripte/`
+- `Assets/AutoBuildScript/`
+- `XLSX_SRC/`
+- `Assets/Editor/XLSX_SRC/`
+
+结果：
+
+- 未发现明确 PVP / 竞技场 / 排行 / 匹配业务代码。
+- 未发现 PVP 相关 UIWindow。
+- 未发现 PVP 相关配置表。
+- 未发现 PVP 相关 protobuf 消息。
+- 搜到的“匹配”均为正则匹配工具注释，不属于业务功能。
+
+当前判断：
+
+- 当前工程未发现 PVP 实现。
+- 该模块目前只作为规划/占位模块保留。
+
+## 梳理任务
+
+- [x] 全局搜索 PVP、Arena、Match、Rank、Opponent 等关键词。
+- [x] 检查 protobuf 是否有 PVP/匹配/排行相关消息。
+- [x] 检查配置表是否有 PVP、竞技场或排行配置。
+- [x] 检查 UIWindows 是否有隐藏或未接入的 PVP 窗口。
+- [ ] 确认项目当前是否规划 PVP。
+
+## 待确认
+
+- 是否产品规划中存在 PVP。
+- 如果短期不做，可以从模块索引移除，或保持为“规划占位”。
+
+## 相关框架
+
+- [网络框架](../../../modules/frameworks/网络系统.md)
+- [PVE/关卡战斗](PVE关卡战斗.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/features/PVE关卡战斗.md](PVE关卡战斗.md) | PVE/关卡战斗 |
+| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 |
--- a/business-reference/playballoons/features/商店.md
+++ b/business-reference/playballoons/features/商店.md
@@ -0,0 +1,128 @@
+# 商店
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录商店商品、购买、货币消耗、体力/资源购买和商店 UI 入口。
+
+## 已知线索
+
+- GM 线索：`Assets/Game/GameHFScripte/GameFunction/UIWindows/GMWindow/GMWindow_GM.cs` 中有商店模块注释。
+- Tips 线索：`Tips_GetPower` 引用 `ShopGoodsInfo`。
+- 图集线索：`SpriteAtlasAssets/Shop`
+- 代码中可见 `ShopWindow`、`ShopGetCurrency` 注释引用。
+
+## 已确认内容
+
+协议和数据结构已生成：
+
+- `Network_MsgId.GetShop = 2500`
+- `Network_MsgId.ShopBuy = 2501`
+- `Network_MsgId.ShopRefresh = 2502`
+- `HFEvent_STC_GetShopS2C`
+- `HFEvent_STC_ShopBuyS2C`
+- `HFEvent_STC_ShopRefreshS2C`
+
+请求/响应字段：
+
+```text
+GetShopC2S
+  -> ShopId
+GetShopS2C
+  -> repeated ShopInfo
+
+ShopBuyC2S
+  -> GoodsId
+  -> BuyType
+ShopBuyS2C
+  -> ShopId
+  -> Goods
+  -> Item
+
+ShopRefreshC2S
+  -> ShopId
+  -> RefreshType
+ShopRefreshS2C
+  -> Shop
+```
+
+核心数据结构在：
+
+- `Assets/Game/GameHFScripte/CopyToHF/Network/Player.cs`
+- `Assets/Game/GameHFScripte/CopyToHF/Network/Common.cs`
+
+```text
+ShopInfo
+  -> ShopId
+  -> RefreshInfo : Map<int, ShopRefreshInfo>
+  -> Goods : Map<int, ShopGoodsInfo>
+
+ShopGoodsInfo
+  -> GoodsId
+  -> BuyNum : Map<int, GoodsBuyNumInfo>
+  -> Item
+
+ShopRefreshInfo
+  -> RefreshType
+  -> RefreshNum
+
+GoodsBuyNumInfo
+  -> BuyType
+  -> BuyNum
+```
+
+体力购买相关：
+
+- `Tips_GetPower` 是当前能看到的体力购买/领取 UI 线索。
+- `Tips_GetPower` 读取 `Constants.PurchaseStamina`。
+- `Tips_GetPower` 监听 `HFEvent_BagItemUpdate` 刷新展示。
+- `Stamina_QueryC2S` / `Stamina_GetC2S` 协议已生成，但当前未看到实际发送点。
+
+当前接入状态：
+
+- `MainWindow` 中 `OpenWindow<ShopWindow>`、`ShopGetCurrency`、`Tips_GetPower` 入口大多处于注释状态。
+- 未发现 `GetShopC2S`、`ShopBuyC2S`、`ShopRefreshC2S` 在业务代码中的实际发送点。
+- 未发现独立商店 manager。
+- 因此当前判断：商店协议和部分 UI/资源痕迹存在，但客户端业务主流程未完整接入或处于注释/待开发状态。
+
+## 梳理任务
+
+- [x] 查找是否存在独立商店 manager、window 或配置表。
+- [x] 梳理商品数据结构和 `ShopGoodsInfo` 来源。
+- [ ] 梳理购买流程：打开、选择、校验、扣费、到账。
+- [x] 梳理商店与背包、资源、体力之间的关系。
+- [x] 确认当前商店功能是完整实现、部分接入还是已注释/待开发。
+
+## 待确认
+
+- 是否存在未纳入当前工程的 `ShopWindow`、`ShopGetCurrency` 或旧分支代码。
+- 是否存在 `Shop.xlsx`、`Goods.xlsx`、`DailyDeals.xlsx` 等相关配置；当前配置列表未登记这些表，但生成代码里有旧表痕迹。
+- 商店是否区分普通商店、体力购买、礼包、广告等类型。
+- 商店 UI 当前看起来未接入，需要后续确认是否是产品阶段未启用。
+
+## 相关框架
+
+- [背包](背包.md)
+- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
+- [网络框架](../../../modules/frameworks/网络系统.md)
+- [数据/配置框架](../../../modules/frameworks/数据配置框架.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/features/背包.md](背包.md) | 背包 |
+| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 |
+| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 |
+| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 |
--- a/business-reference/playballoons/features/地图进度.md
+++ b/business-reference/playballoons/features/地图进度.md
@@ -0,0 +1,148 @@
+# 地图/关卡进度
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录地图、关卡、波次、进度奖励和关卡状态。
+
+## 已知线索
+
+- 地图逻辑：`Assets/Game/GameHFScripte/GameFunction/Logic/MapManager/`
+- 关卡资源：`Assets/Game/GameHFResource/CN/Map/Level.prefab`
+- 配置线索：`XLSX_SRC/CN/Wave.xlsx`
+- 网络线索：`UserRolePeripheryProgressReward*`
+
+## 已确认内容
+
+地图加载：
+
+```text
+HFMapManager.CreateMap(levelid, finish)
+  -> ClearMap()
+  -> HFFunCatalogue.Asset.LoadAsset(1501)
+  -> GetOrAddComponent<HFM_DLevelSetting>()
+  -> OnSetFinishLoad()
+```
+
+当前 `CreateMap` 传入了 `levelid`，但实际读取关卡配置的代码被注释：
+
+```text
+// MapInfo = HFFunCatalogue.NDB.ds_Level83D033B2TableData.ReadTableByPK(levelid);
+```
+
+地图配置数据：
+
+- `stMapInfo` 使用 `MemoryPack`，包含障碍物/实体位置列表 `ObstaclesPos`。
+- `stMapEntityInfo` 包含 `Postion`、`EntityId`、`CellIndexs`。
+- `HF_MapEditor` 可以保存/读取地图配置文件到 `Assets/Game/GameHFResource/CN/MapInfoData/<Configuration>.txt`，但实体加载/放置代码大多处于注释状态。
+- `HFM_MapSetting` 记录地图出生点、终点、Hero 引用。
+- `HF_WaveInfo` 记录波次中的起止时间、怪物 id、数量和 Boss 卡显示等。
+
+关卡/波次协议：
+
+- `GetLevelInfo = 3004`
+- `GetLevelWaveReward = 3005`
+- `BattleLevelEnter = 3000`
+- `BattleLevelExit = 3001`
+- `BattleLevelWin = 3002`
+- `BattleLevelFail = 3003`
+
+字段线索：
+
+```text
+GetLevelInfoS2C
+  -> Levels
+
+GetLevelWaveRewardC2S
+  -> Id
+  -> Wave
+GetLevelWaveRewardS2C
+  -> Level
+  -> Item
+
+BattleLevelEnterC2S
+  -> Id
+BattleLevelWinC2S
+  -> Id
+  -> ChestType
+  -> KillMons
+  -> MaxWave
+BattleLevelFailC2S
+  -> Id
+  -> MaxWave
+  -> KillMons
+```
+
+外围进度奖励协议：
+
+- `GetUserRolePeripheryProgressReward1Data = 5000`
+- `UserRolePeripheryClaimedProgressReward1Reward = 5001`
+- `SetUserRolePeripheryLevelWaveProgress = 5901`，当前主要在 GM 调试入口看到。
+
+字段线索：
+
+```text
+UserRolePeripheryDataProgressReward1
+  -> LevelId
+  -> MaxWave
+  -> State
+  -> ClaimedWave
+
+GetUserRolePeripheryProgressReward1DataS2C
+  -> ProgressReward1 : repeated UserRolePeripheryDataProgressReward1
+
+UserRolePeripheryClaimedProgressReward1RewardC2S
+  -> LevelId
+UserRolePeripheryClaimedProgressReward1RewardS2C
+  -> Rewards : Map<int, int>
+```
+
+当前接入状态：
+
+- PVE 战斗内波次由 `HFWaveManager` 读取 `Wave.xlsx`，属于战斗流程。
+- 地图/关卡进度协议已生成，但业务 UI 和普通发送链路未确认。
+- `GMWindow_GM.cs` 中有外围进度设置和领取奖励调试入口。
+- 地图编辑器、关卡配置、地图实体摆放等代码保留较多注释，当前更像半接入/调试状态。
+
+## 梳理任务
+
+- [x] 梳理地图/关卡数据结构。
+- [ ] 梳理关卡解锁、当前关卡、已通关状态。
+- [x] 梳理波次和关卡配置的关系。
+- [x] 梳理进度奖励领取条件和网络消息。
+- [ ] 梳理地图进度如何驱动主界面或 PVE 入口。
+
+## 待确认
+
+- 地图是否有章节/大关/小关层级；`ChapterWindow` 有注释入口，但当前未确认实装。
+- `Level` 相关配置表是否为旧表残留或当前未登记源表。
+- 关卡进度是否全部由服务器维护。
+- `GetLevelWaveReward` 与外围进度奖励 `ProgressReward1` 的产品边界。
+- 地图进度如何驱动主界面或 PVE 入口。
+
+## 相关框架
+
+- [PVE/关卡战斗](PVE关卡战斗.md)
+- [数据/配置框架](../../../modules/frameworks/数据配置框架.md)
+- [网络框架](../../../modules/frameworks/网络系统.md)
+- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/features/PVE关卡战斗.md](PVE关卡战斗.md) | PVE/关卡战斗 |
+| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 |
+| [modules/frameworks/网络系统.md](../../../modules/frameworks/网络系统.md) | 网络框架 |
+| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 |
--- a/business-reference/playballoons/features/塔养成.md
+++ b/business-reference/playballoons/features/塔养成.md
@@ -0,0 +1,123 @@
+# 塔/角色养成
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录塔、角色或卡片的升级、升星、技能升级、展示和养成配置。
+
+## 已知线索
+
+- 逻辑路径：`Assets/Game/GameHFScripte/GameFunction/Logic/TowerLevelUpManager/`
+- 逻辑路径：`Assets/Game/GameHFScripte/GameFunction/Logic/TowerSkillUpManager/`
+- UI 路径：`Assets/Game/GameHFScripte/GameFunction/UIWindows/AvatarItem/`
+- 配置线索：`XLSX_SRC/CN/EntityConfig.xlsx`
+- 配置线索：`XLSX_SRC/CN/SkillGroup.xlsx`、`SkillReleaser.xlsx`、`SkillTrigger.xlsx`、`SkillUp.xlsx`
+
+## 已确认内容
+
+启动初始化：
+
+```text
+HFGameStart.InitManager()
+  -> HFTowerStarUpManager.Instance
+  -> HFTowerSkillUpManager.Instance
+```
+
+协议已生成：
+
+- `GetPlayerTower = 4000`
+- `TowerLevelFormation = 4001`
+- `TowerLevelUpLv = 4002`
+- route：
+  - `game.player.getTower`
+  - `game.player.formationTower`
+  - `game.player.levelUpTower`
+
+请求/响应字段：
+
+```text
+GetPlayerTowerC2S
+  -> 无主要字段
+GetPlayerTowerS2C
+  -> Formation : repeated long
+
+TowerLevelFormationC2S
+  -> Formation : repeated long
+TowerLevelFormationS2C
+  -> Formation : repeated long
+
+TowerLevelUpLvC2S
+  -> Id
+TowerLevelUpLvS2C
+  -> Id
+  -> Formation : repeated long
+```
+
+STC 事件：
+
+- `HFEvent_STC_GetPlayerTowerS2C`
+- `HFEvent_STC_TowerLevelFormationS2C`
+- `HFEvent_STC_TowerLevelUpLvS2C`
+
+配置和实体侧线索：
+
+- `Constants` 中有塔相关字段：`BossTowerCardNum`、`BossTowerGetNum`、`TowerRange`、`TowerRectangle`、`NewTowerInitLevel`、`TowerPutEffect*`、`LucySpinSameTower` 等。
+- 实体侧会读取 `EntityConfig`、`Resource`、`SkillGroup`、`SkillReleaser`、`SkillTrigger` 等表来驱动塔实体、模型、AI、技能。
+- 历史/生成代码里存在 `Tower`、`Towerlevel`、`StarUpgrade`、`CardWeight` 等表的读取痕迹，但当前 `ZYXlsxProjectSettings` 登记的 CN 表没有显式列出这些源表，需要确认是否是旧生成残留或表源未纳入当前列表。
+
+当前接入状态：
+
+- `HFTowerStarUpManager` 主体逻辑几乎全部注释，包括选择塔、显示升级 HUD、读取 `StarUpgrade`、修改实体属性等。
+- `HFTowerSkillUpManager` 主体逻辑也处于注释状态，包括监听 `HFEvent_TowerSkillState` 并修改实体技能能力。
+- `AvatarItem` 的资源路径 attribute 被注释，当前更像 MainWindow 内嵌组件；`SetAvatarFrame` 尚未实装。
+- `CardItem` 有卡片 UI 基础绑定，但 `SetData` 为空。
+- 未发现 `GetPlayerTowerC2S`、`TowerLevelFormationC2S`、`TowerLevelUpLvC2S` 在业务代码中的实际发送点。
+
+当前判断：
+
+- “塔/角色养成”协议、配置痕迹、实体战斗联动线索都存在。
+- 客户端养成主流程当前未完整实装，或被注释保留。
+- 运行中的塔更偏战斗实体/技能系统；大厅养成、编队、升级 UI 还需要进一步确认产品接入状态。
+
+## 梳理任务
+
+- [x] 确认“塔”“角色”“卡片”在代码和配置中的对应概念。
+- [x] 梳理塔升级和技能升级的入口。
+- [ ] 梳理升级消耗和背包资源关系。
+- [x] 梳理 Avatar/Card UI 展示数据来源。
+- [x] 梳理养成数据是否同步服务器。
+
+## 待确认
+
+- `TowerLevelUpManager` / `TowerSkillUpManager` 当前初始化但主体逻辑被注释，需确认是否计划恢复。
+- 升级、升星、技能升级是否属于同一产品功能域，需要结合 UI/策划表确认。
+- 升级消耗、卡片碎片、背包资源之间的真实关系待确认。
+- 养成结果如何同步并影响 PVE 实体属性，需要确认服务端返回和客户端应用链路。
+- `Tower`、`Towerlevel`、`StarUpgrade`、`CardWeight` 等表是否是旧表残留或当前缺失源表。
+
+## 相关框架
+
+- [实体框架](../../../modules/frameworks/实体系统/README.md)
+- [背包](背包.md)
+- [数据/配置框架](../../../modules/frameworks/数据配置框架.md)
+- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/features/背包.md](背包.md) | 背包 |
+| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 |
+| [modules/frameworks/实体系统/README.md](../../../modules/frameworks/实体系统/README.md) | 实体框架 |
+| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 |
--- a/business-reference/playballoons/features/奖励道具.md
+++ b/business-reference/playballoons/features/奖励道具.md
@@ -0,0 +1,105 @@
+# 奖励/道具展示
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录通用奖励、道具展示、资源展示、弹窗提示和奖励到账表现。
+
+## 已知线索
+
+- 奖励提示：`Assets/Game/GameHFScripte/GameFunction/UIWindows/Tips/Tips_CommonReward.cs`
+- 资源组件：`Assets/Game/GameHFScripte/GameFunction/UIWindows/Components/ResourceItem.cs`
+- 道具 UI：`Assets/Game/GameHFScripte/GameFunction/UIWindows/Item/`
+- 配置线索：`XLSX_SRC/CN/Gift.xlsx`、`Resource.xlsx`
+
+## 已确认内容
+
+通用入口：
+
+```text
+HFFunCatalogue.Tips.ShowCommonRewardTips(reward, cardReward)
+  -> HFFunCatalogue.UIManager.OpenWindow<Tips_CommonReward>()
+  -> Tips_CommonReward.SetData(reward, cardReward)
+```
+
+定义位置：
+
+- `Assets/Game/GameHFScripte/GameFunction/Logic/UI/HFFunCatalogue_UI_TipsManager.cs`
+- `Assets/Game/GameHFScripte/GameFunction/UIWindows/Tips/Tips_CommonReward.cs`
+
+奖励数据结构：
+
+- `Tips_CommonReward.SetData` 接收 `RepeatedField<BagItem>`。
+- `BagItem` 来自网络 protobuf。
+- 当前代码中把奖励分成 `cards` 和 `items` 的逻辑存在，但核心分类代码被注释：
+  - 原计划通过 `Item` 配置表判断 `enItemType.Tower`。
+  - 当前 `ZYXlsxProjectSettings` 未登记 `Item.xlsx`，但旧代码里有 `ds_Item860D2A9ETableData` 痕迹。
+
+展示组件：
+
+- `Tips_CommonReward`
+  - 标题固定设置为 `REWARDS`。
+  - `ResourceItem` 当前固定调用 `SetData(1)` 展示顶部资源。
+  - 普通道具用 `ItemIcon` 池展示。
+  - 卡片奖励区域逻辑存在，但资源设置代码被注释。
+- `ResourceItem`
+  - 监听 `HFEvent_InitBag`。
+  - 通过 `HFFunCatalogue.Bag.GetGameResourceCount(resourceId)` 展示资源数量。
+  - 资源变化动画和主动刷新事件逻辑存在注释。
+- `Tips_UnlockTower`
+  - 用于解锁塔/卡片提示。
+  - 当前读 `Tower` / `Item` 配置和设置图标的代码被注释。
+
+配置线索：
+
+- `Gift.xlsx` 已登记到 ZYXlsx，生成 `Gift14537B33Sheet1`。
+- `Resource.xlsx` 已登记到 ZYXlsx，生成 `Resource840C5F09TableData`。
+- `Constants.xlsx` 中有奖励相关字段：`LuckyLootRewardTimes`、`LoginUsersItem`、`QuickOfflineReward`、`FreeOfflineReward` 等。
+
+当前接入状态：
+
+- 通用奖励弹窗入口存在。
+- 奖励 UI 框架存在，但道具/卡片配置读取大量注释。
+- 入包逻辑不在奖励弹窗里，当前主要由背包/服务器推送 `PlayerResourceChangeS2C` 更新。
+
+## 梳理任务
+
+- [x] 梳理奖励数据结构和展示入口。
+- [x] 梳理奖励中道具、卡片、资源的分类。
+- [x] 梳理奖励展示和背包更新的先后关系。
+- [x] 梳理通用 Tips 的打开方式和资源加载方式。
+- [ ] 梳理奖励来源：PVE、任务、商店、GM 或其他系统。
+
+## 待确认
+
+- 奖励展示当前看起来只负责表现，不负责入包；仍需结合具体领取协议确认。
+- `Gift.xlsx` 和实际奖励结构的对应关系待确认。
+- `Item.xlsx` / `Tower.xlsx` 是否是旧表残留或当前缺失源表。
+- 飞图事件 `HFEvent_FlyIcon` 存在，但实际调用链待继续确认。
+
+## 相关框架
+
+- [背包](背包.md)
+- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
+- [资源框架](../../../modules/frameworks/资源管理/README.md)
+- [数据/配置框架](../../../modules/frameworks/数据配置框架.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/features/背包.md](背包.md) | 背包 |
+| [modules/frameworks/数据配置框架.md](../../../modules/frameworks/数据配置框架.md) | 数据/配置框架 |
+| [modules/frameworks/资源管理/README.md](../../../modules/frameworks/资源管理/README.md) | 资源框架 |
+| [modules/frameworks/UI窗口系统/README.md](../../../modules/frameworks/UI窗口系统/README.md) | UI 框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖的框架/模块文档 | 如 UI、网络、事件、配置等框架 |
--- a/business-reference/playballoons/features/登录.md
+++ b/business-reference/playballoons/features/登录.md
@@ -0,0 +1,167 @@
+# 登录
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录登录流程、登录窗口、网络交互和进入游戏后的衔接关系。
+
+## 关键文件
+
+| 用途 | 路径 | 说明 |
+|---|---|---|
+| 登录管理器 | `Assets/Game/GameHFScripte/GameFunction/Logic/Login/HFLoginManager.cs` | 单例，负责连接服务器、发送登录协议、处理登录后事件链 |
+| 登录窗口 | `Assets/Game/GameHFScripte/GameFunction/UIWindows/Login/LoginWindow.cs` | 继承 `AbsHFUIWindow`，绑定输入框和登录按钮 |
+| 登录 Prefab | `Assets/Game/GameHFResource/UIWindows/Login/LoginWindow.prefab` | 窗口资源，由 `HFAssetBundlePath` 指定 |
+| 启动入口 | `Assets/Game/GameHFScripte/GameFunction/GameRoot/HFGameStart.cs`（待确认） | 初始化 manager 并打开 `LoginWindow` |
+
+## 数据流
+
+```text
+[启动]
+HFGameStart.InitManager
+  -> OpenWindow<LoginWindow>
+
+[用户点击]
+LoginWindow.OnBtnLogin
+  -> 校验用户名非空
+  -> PlayerPrefs 保存用户名/密码
+  -> HFLoginManager.Instance.Login(InputName.text)
+
+[连接服务器]
+HFLoginManager.Login(account)
+  -> UNITY_EDITOR 下读取 EditorPrefs["IPData"] 覆盖 IP
+  -> HFSeverManager.ReConnect(OnReConnect)
+  -> HFSeverManager.Connect(MainConnect, WebSocket, m_IP, m_Port, m_Token, callback)
+  -> 连接成功后 OnSendLogin
+
+[登录协议]
+OnSendLogin
+  -> LoginAuthC2S
+       ServerId = 10001
+       Token    = m_Token
+       Pid      = "2126001"
+       UserName = m_Account
+       Password = m_Account
+
+[服务端响应链]
+LoginAuthS2C (ErrorCode == 0)
+  -> PlayerSelectC2S
+  -> PlayerSelectS2C
+       有角色：PlayerEnterC2S
+       无角色：PlayerCreateC2S -> PlayerEnterC2S
+  -> PlayerEnterS2C
+  -> PlayerFlushC2S(All = true)
+  -> RequestLoginData 触发后续背包、资源等初始化
+```
+
+## 关键协议
+
+- `LoginAuthC2S` / `LoginAuthS2C`
+- `PlayerSelectC2S` / `PlayerSelectS2C`
+- `PlayerCreateC2S` / `PlayerCreateS2C`
+- `PlayerEnterC2S` / `PlayerEnterS2C`
+- `PlayerFlushC2S` / `PlayerFlushS2C`
+- `ChangeNicknameC2S` / `ChangeNicknameS2C`
+
+## 已确认流程
+
+当前登录入口：
+
+```text
+HFGameStart.InitManager
+  -> OpenWindow<LoginWindow>
+  -> LoginWindow.OnBtnLogin
+  -> HFLoginManager.Login(InputName.text)
+```
+
+`HFLoginManager.Login` 流程：
+
+```text
+Login(account)
+  -> 读取 EditorPrefs["IPData"] 覆盖 IP（仅 UNITY_EDITOR）
+  -> ConnectServer
+  -> HFSeverManager.ReConnect(OnReConnect)
+  -> HFSeverManager.Connect(MainConnect, WebSocket, m_IP, m_Port, m_Token)
+  -> OnSendLogin
+  -> LoginAuthC2S.Dispatch
+```
+
+服务端事件链：
+
+```text
+LoginAuthS2C
+  -> PlayerSelectC2S
+  -> PlayerSelectS2C
+    -> 有角色：PlayerEnterC2S
+    -> 无角色：PlayerCreateC2S -> PlayerEnterC2S
+  -> PlayerEnterS2C
+  -> PlayerFlushC2S(All = true)
+```
+
+`LoginWindow` 会把用户名和密码写入 `PlayerPrefs`，但实际登录请求当前使用用户名作为 account，密码未参与 `LoginAuthC2S`。
+
+## 梳理任务
+
+- [x] 找到登录功能的入口方法和首个调用点。
+- [x] 梳理登录请求、响应和错误处理。
+- [x] 梳理登录成功后初始化了哪些 manager。
+- [x] 梳理登录窗口 prefab 和脚本绑定关系。
+- [ ] 确认登录完成后进入主界面或 PVE 的流程。
+
+## 待确认
+
+- 登录是否区分游客、账号、平台登录。
+- 登录数据是否会初始化背包、关卡、角色/塔数据。
+- 是否存在断线重连或重新登录流程。
+- `PlayerFlushS2C` 收到后由谁打开主界面，目前未确认。
+- 密码输入框当前只保存到 `PlayerPrefs`，是否应参与登录待确认。
+
+## 相关框架
+
+- [网络框架](../../../modules/frameworks/网络系统.md)
+- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
+- [Hotfix 启动/目录](../../../modules/frameworks/Hotfix启动.md)
+
+---
+
+## 文档关联
+
+> **注意**：当本模块发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+### 关联模块
+
+| 模块 | 文档 | 关联原因 |
+|---|---|---|
+| 背包 | [背包](背包.md) | 登录成功后 `RequestLoginData` 触发背包初始化 |
+| 奖励/道具展示 | [奖励/道具展示](奖励道具.md) | 登录流程涉及资源、道具配置 |
+| GM/调试功能 | [GM/调试功能](GM调试.md) | `HFLoginManager` 在 Editor 下读取 `EditorPrefs["IPData"]` 覆盖 IP |
+| PVE/关卡战斗 | [PVE/关卡战斗](PVE关卡战斗.md) | 登录后进入主界面或 PVE 的流程衔接 |
+| 地图/关卡进度 | [地图/关卡进度](地图进度.md) | 登录后角色数据与关卡进度同步 |
+
+### 关联框架文档
+
+| 框架 | 文档 | 关联原因 |
+|---|---|---|
+| 网络框架 | [网络框架](../../../modules/frameworks/网络系统.md) | 登录协议（`LoginAuthC2S/S2C`、`PlayerEnterS2C` 等） |
+| UI 框架 | [UI 框架](../../../modules/frameworks/UI窗口系统/README.md) | `LoginWindow` 继承 `AbsHFUIWindow` |
+| Hotfix 启动/目录 | [Hotfix 启动/目录](../../../modules/frameworks/Hotfix启动.md) | `HFGameStart.InitManager` 为入口 |
+| 事件框架 | [事件框架](../../../modules/frameworks/事件系统/README.md) | `RequestLoginData` 触发后续初始化事件链 |
+| 场景框架 | [场景框架](../../../modules/frameworks/场景系统.md) | 登录后进入主界面涉及场景切换 |
+
+### 关联规则
+
+| 规则 | 文档 | 关联原因 |
+|---|---|---|
+| 模块登记规则 | [30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 登录模块登记与状态 |
+| 归档规则 | [50-归档规则.md](../../../rules/50-归档规则.md) | 变更后需同步归档相关文档 |
+| 架构说明 | [10-架构说明.md](../../../rules/10-架构说明.md) | 登录为游戏入口，涉及整体架构 |
+| 开发规则 | [20-开发规则.md](../../../rules/20-开发规则.md) | 网络协议、UI 窗口开发规范 |
+
+### 关联 Spec / OpenSpec
+
+| Spec | 文档 | 关联原因 |
+|---|---|---|
+| 规则工作流 Spec | [2026-06-11-rules-workflow-v1.md](../../../specs/Spec索引.md) | 项目文档和规则系统建立 |
--- a/business-reference/playballoons/features/背包.md
+++ b/business-reference/playballoons/features/背包.md
@@ -0,0 +1,174 @@
+# 背包
+
+## 分类
+
+- 项目功能
+
+## 目的
+
+记录道具、资源数量、背包数据同步、资源展示和奖励入包逻辑。
+
+## 关键文件
+
+| 用途 | 路径 | 说明 |
+|---|---|---|
+| 背包管理器 | `Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/HFBagManager.cs` | 单例 `AbsHFSingleRunTime`，管理背包页签、道具/资源数量 |
+| 背包数据结构 | `Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/StItem.cs` | 单个道具数据 |
+| 背包数据结构 | `Assets/Game/GameHFScripte/GameFunction/Logic/Bag/BagInfo/stItemInfo.cs` | 道具信息 |
+| 道具类型枚举 | `Assets/Game/GameHFScripte/GameFunction/Logic/Constant/enItemType.cs` | 货币、材料、防御塔、经验、道具等 |
+| 背包窗口 | `Assets/Game/GameHFScripte/GameFunction/UIWindows/ItemWindow/ItemWindow.cs` | 单个道具/资源展示单元 |
+| GM 调试 | `Assets/Game/GameHFScripte/GameFunction/UIWindows/GMWindow/GMWindow_BagData.cs` | GM 修改背包数据入口 |
+| 资源配置 | `XLSX_SRC/CN/Resource.xlsx` | 资源/道具基础配置 |
+
+## 数据流
+
+### 登录初始化
+
+```text
+HFLoginManager.RequestLoginData
+  -> PlayerFlushC2S(All = true)
+  -> 服务端推送 GetBagItemS2C（待确认具体时序）
+  -> HFBagManager.OnPushBagItem
+  -> AddItem(item)
+  -> HFEvent_InitBag.Dispatch
+```
+
+### 增量更新
+
+```text
+PlayerResourceChangeS2C
+  -> ItemChange.Add / Del / Update
+  -> HFBagManager.OnUpdateBagItem
+  -> AddItem / DelItem
+  -> HFEvent_BagItemUpdate.Dispatch
+```
+
+## 关键 API
+
+| 方法 | 用途 |
+|---|---|
+| `Init(int maxpage)` | 初始化背包页签 |
+| `AddItem(Item item)` | 添加/更新道具 |
+| `DelItem(...)` | 删除道具 |
+| `GetGameResourceCount(int resId)` | 按 resid 快速获取资源数量 |
+| `GetItemCount(int resid)` | 遍历具体 item 累加数量 |
+| `BagPageIndex` | 当前背包页签 |
+
+## 内部存储
+
+- `m_BagPage`：按页签保存 `RB_Tree`。
+- `m_DicPageUUid`：按 `resid` 记录 uuid 到 page 的映射。
+- `m_DicItemCount`：按 `resid` 快速记录数量（当前为覆盖值，不是累加值）。
+
+## 关键事件
+
+- `enHFSTCEvent.GetBagItem`：首次推送背包数据。
+- `enHFSTCEvent.PlayerResourceChange`：资源/道具增量变化。
+- `HFEvent_InitBag`：背包初始化完成。
+- `HFEvent_BagItemUpdate`：背包数据更新。
+
+## 已确认内容
+
+背包 manager：
+
+- 主类：`HFBagManager`
+- 基类：`AbsHFSingleRunTime<HFBagManager>`
+- 初始化：`HFGameStart.InitManager` 访问 `HFBagManager.Instance` 时创建。
+
+监听的服务端事件：
+
+- `GetBagItemS2C` -> `OnPushBagItem`
+- `PlayerResourceChangeS2C` -> `OnUpdateBagItem`
+
+首次背包数据：
+
+```text
+HFLoginManager.RequestLoginData
+  -> PlayerFlushC2S(All = true)
+  -> 服务端推送 GetBagItemS2C（待确认具体时序）
+  -> HFBagManager.OnPushBagItem
+  -> AddItem
+  -> HFEvent_InitBag.Dispatch
+```
+
+增删改更新：
+
+```text
+PlayerResourceChangeS2C
+  -> ItemChange.Add / Del / Update
+  -> AddItem / DelItem
+  -> HFEvent_BagItemUpdate.Dispatch
+```
+
+内部存储：
+
+- `m_BagPage`：按页签保存 `RB_Tree`。
+- `m_DicPageUUid`：按 `resid` 记录 uuid 到 page 的映射。
+- `m_DicItemCount`：按 `resid` 快速记录数量。
+- `GetGameResourceCount(resId)`：常用于资源数量展示。
+- `GetItemCount(resid)`：遍历具体 item 累加数量。
+
+## 梳理任务
+
+- [x] 找到 `HFBagManager` 或背包 manager 的入口和生命周期。
+- [x] 梳理背包数据来源：登录初始化、网络消息、GM 请求或本地配置。
+- [x] 梳理道具和资源的查询 API。
+- [x] 梳理背包更新事件如何驱动 UI 刷新。
+- [ ] 梳理奖励入包和奖励展示的关系。
+
+## 待确认
+
+- 背包是否区分道具、资源、卡片。
+- 背包数据是否全部来自服务器。
+- 是否有消耗、添加、合并、排序等本地逻辑。
+- `PlayerFlushS2C` 和 `GetBagItemS2C` 的服务端推送时序需确认。
+- `m_DicItemCount[resid] = count` 当前是覆盖值，不是累加值，是否符合资源类型语义待确认。
+
+## 相关框架
+
+- [事件框架](../../../modules/frameworks/事件系统/README.md)
+- [网络框架](../../../modules/frameworks/网络系统.md)
+- [UI 框架](../../../modules/frameworks/UI窗口系统/README.md)
+- [数据/配置框架](../../../modules/frameworks/数据配置框架.md)
+
+---
+
+## 文档关联
+
+> **注意**：当本模块发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+### 关联模块
+
+| 模块 | 文档 | 关联原因 |
+|---|---|---|
+| 登录 | [登录](登录.md) | `HFLoginManager.RequestLoginData` 触发背包首次初始化 |
+| 商店 | [商店](商店.md) | 商店购买/出售涉及背包道具增减 |
+| 奖励/道具展示 | [奖励/道具展示](奖励道具.md) | 奖励入包展示、道具配置（`Resource.xlsx`、`Gift.xlsx`） |
+| 塔/角色养成 | [塔/角色养成](塔养成.md) | 养成消耗涉及背包资源扣除 |
+| 地图/关卡进度 | [地图/关卡进度](地图进度.md) | 关卡奖励可能涉及背包道具更新 |
+| GM/调试功能 | [GM/调试功能](GM调试.md) | `GMWindow_BagData` 为 GM 修改背包数据入口 |
+
+### 关联框架文档
+
+| 框架 | 文档 | 关联原因 |
+|---|---|---|
+| 事件框架 | [事件框架](../../../modules/frameworks/事件系统/README.md) | `HFEvent_InitBag`、`HFEvent_BagItemUpdate` 事件驱动 |
+| 网络框架 | [网络框架](../../../modules/frameworks/网络系统.md) | `GetBagItemS2C`、`PlayerResourceChangeS2C` 协议 |
+| UI 框架 | [UI 框架](../../../modules/frameworks/UI窗口系统/README.md) | `ItemWindow` 为背包 UI 展示单元 |
+| 数据/配置框架 | [数据/配置框架](../../../modules/frameworks/数据配置框架.md) | `Resource.xlsx` 资源配置源 |
+| 内存/对象管理 | [内存/对象管理](../../../modules/frameworks/内存对象管理/README.md) | `RB_Tree` 存储结构、对象池 |
+
+### 关联规则
+
+| 规则 | 文档 | 关联原因 |
+|---|---|---|
+| 模块登记规则 | [30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 背包模块登记与状态 |
+| 归档规则 | [50-归档规则.md](../../../rules/50-归档规则.md) | 变更后需同步归档相关文档 |
+| 架构说明 | [10-架构说明.md](../../../rules/10-架构说明.md) | 背包为全局数据模块，涉及架构分层 |
+| 开发规则 | [20-开发规则.md](../../../rules/20-开发规则.md) | 数据管理、事件使用规范 |
+
+### 关联 Spec / OpenSpec
+
+| Spec | 文档 | 关联原因 |
+|---|---|---|
+| 规则工作流 Spec | [2026-06-11-rules-workflow-v1.md](../../../specs/Spec索引.md) | 项目文档和规则系统建立 |
--- a/business-reference/playballoons/业务参考总入口.md
+++ b/business-reference/playballoons/业务参考总入口.md
@@ -0,0 +1,40 @@
+# PlayBalloons 业务参考
+
+> 本目录存放来自 **PlayBalloons / CrystalBattle** 实际项目的业务功能文档。
+>
+> 这些内容**不是 StrayFog 框架的一部分**，仅作为“使用 StrayFog 框架如何实现具体业务”的参考示例。
+>
+> AI 和人工开发者应先学习 StrayFog 框架核心文档，再按需查阅本目录。
+
+---
+
+## 入口文档
+
+- [业务功能 → StrayFog 框架能力映射](业务框架映射接口.md)
+- [features/](features/)：原始业务功能文档
+
+---
+
+## 来源说明
+
+这些文档原本位于 `modules/features/`（旧结构），是从 PlayBalloons 项目迁移而来。迁移时已移除与 StrayFog 框架核心无关的占位和未实现模块（如 PVP）。
+
+---
+
+## 使用建议
+
+1. **不要直接套用**其中的具体类名、协议号、配置表字段到其他项目。
+2. **重点关注通用模式**：单例管理器、事件驱动数据流、GM 协议包装、通用弹窗接口等。
+3. **对照框架文档阅读**：看到业务实现时，回溯到 `modules/frameworks/` 下对应框架模块文档，理解底层机制。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [业务框架映射接口.md](业务框架映射接口.md) | 业务参考总入口指向框架能力映射 |
+| [modules/模块索引.md](../../modules/模块索引.md) | 模块索引可链接业务参考区 |
+| [rules/10-架构说明.md](../../rules/10-架构说明.md) | 架构说明定义业务功能与框架层的依赖方向 |
--- a/business-reference/playballoons/业务框架映射接口.md
+++ b/business-reference/playballoons/业务框架映射接口.md
@@ -0,0 +1,105 @@
+# 业务功能 → StrayFog 框架能力映射
+
+> 本文档是 PlayBalloons 业务参考的“接口文档”。>
+> 它不描述业务实现细节，而是说明每个业务功能用到了 StrayFog 框架的哪些能力，以及应该参考哪些框架文档。
+
+---
+
+## 来源说明
+
+以下业务功能来自 PlayBalloons 实际项目，仅作参考，不是 StrayFog 框架本身。
+
+原始业务文档位于 [features/](features/) 目录。
+
+---
+
+## 业务功能映射表
+
+| 业务功能 | 涉及 StrayFog 框架能力 | 参考文档 | 状态 |
+|---|---|---|---|
+| 登录 | 单例管理器、网络协议、UI 窗口、事件链 | 网络框架、UI 框架、Hotfix 启动 | 可提炼示例 |
+| 背包 | 单例、RB_Tree 存储、事件驱动、增量同步 | 事件框架、网络框架、数据/配置框架 | 可提炼示例 |
+| 商店 | 网络协议、Map 数据结构、UI 窗口 | 网络框架、UI 框架、数据/配置框架 | 部分接入 |
+| PVE 战斗 | 场景、实体、波次管理、伤害管理器 | 实体框架、场景框架、网络框架 | 半接入 |
+| 塔养成 | 单例、编队数据、实体属性联动 | 实体框架、数据/配置框架 | 未完整实装 |
+| GM 调试 | GM 协议包装、参数配置、模块化窗口生命周期 | 网络框架、UI 框架 | 可提炼示例 |
+| 奖励展示 | 通用 Tips、事件监听、资源组件 | UI 框架、事件框架、资源框架 | 可提炼示例 |
+| 地图进度 | 地图加载、波次配置、进度奖励 | 场景框架、数据/配置框架 | 半接入 |
+| PVP | — | — | 未发现实现 |
+
+---
+
+## 可复用模式索引
+
+从业务文档中提炼出的通用模式，可作为使用 StrayFog 框架实现类似系统的参考：
+
+### 1. 单例管理器 + 初始化模式
+
+```text
+HFGameStart.InitManager()
+  -> 各业务 Manager.Instance 初始化
+  -> Manager 监听 STC 事件
+```
+
+对应框架能力：
+- [Hotfix 启动](../../modules/frameworks/Hotfix启动.md)
+- [对象池](../../modules/frameworks/内存对象管理/README.md)
+
+### 2. 事件驱动数据流
+
+```text
+服务器消息 S2C
+  -> 反射创建 STC 事件
+  -> 业务 Manager 监听并更新数据
+  -> 派发 CTC 事件通知 UI
+```
+
+对应框架能力：
+- [事件系统](../../modules/frameworks/事件系统/README.md)
+- [网络系统](../../modules/frameworks/网络系统.md)
+
+### 3. GM 命令统一包装
+
+```text
+GM 窗口
+  -> 选择 msgId 和参数
+  -> 包装成 GMC2S
+  -> 发送真实业务 Network_MsgId
+```
+
+对应框架能力：
+- [网络系统](../../modules/frameworks/网络系统.md)
+- [UI 窗口系统](../../modules/frameworks/UI窗口系统/README.md)
+
+### 4. 通用弹窗 / Tips 展示
+
+```text
+业务逻辑调用 HFFunCatalogue.Tips.ShowCommonRewardTips(rewardItems)
+  -> 打开通用奖励窗口
+  -> 窗口内资源组件监听背包事件刷新
+```
+
+对应框架能力：
+- [UI 窗口系统](../../modules/frameworks/UI窗口系统/README.md)
+- [事件系统](../../modules/frameworks/事件系统/README.md)
+- [资源管理](../../modules/frameworks/资源管理/README.md)
+
+---
+
+## 使用说明
+
+1. AI 阅读时应先读框架文档，再读业务参考。
+2. 业务参考中的具体类名、协议号不可直接套用到其他项目。
+3. 如需新增业务参考，放入 `business-reference/<project>/features/`，并在本文件补充映射。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [业务参考总入口.md](业务参考总入口.md) | 业务参考总入口指向本映射文档 |
+| [features/*.md](features/) | 每个业务功能文档都应在映射表中有对应行 |
+| [modules/模块索引.md](../../modules/模块索引.md) | 模块索引可链接到业务参考区 |
--- a/hooks/Hook共享层.md
+++ b/hooks/Hook共享层.md
@@ -0,0 +1,89 @@
+# Hook 共享层
+
+> 本目录存放 UnityAI / StrayFog 框架知识库共享的 hook 脚本和规则。
+>
+> 各 AI 工具自己的私有目录只放适配器，不重复维护 hook 逻辑。
+
+---
+
+## 脚本清单
+
+| 脚本 | 用途 |
+|---|---|
+| [archive-check.ps1](archive-check.ps1) | 读取 git diff 中变更的 `.md` 文件，解析 `## 文档关联` 表，输出需要同步检查的关联文档 |
+| [sync-doc-associations.ps1](sync-doc-associations.ps1) | Python 脚本的 PowerShell 包装器 |
+| [sync_doc_associations.py](sync_doc_associations.py) | 在关联文档中追加变更提醒（只追加、不覆盖，执行后需 review） |
+| [commit-check.ps1](commit-check.ps1) | 提交前检查：推断变更文件所属模块，校验提交信息格式 |
+| [commit-module-mappings.json](commit-module-mappings.json) | `commit-check.ps1` 使用的目录-模块映射配置 |
+
+---
+
+## 归档检查
+
+所有任务结束后都应执行归档检查，判断是否需要同步更新长期文档。
+
+```powershell
+# PowerShell
+.\docs\hooks\archive-check.ps1
+```
+
+该脚本只输出建议，不会自动修改任何文档。最终是否更新关联文档，需要用户确认。
+
+---
+
+## 文档关联同步
+
+如需在关联文档中自动留下变更提醒，可运行：
+
+```powershell
+.\docs\hooks\sync-doc-associations.ps1
+```
+
+该脚本只追加、不覆盖，执行后必须 review。
+
+---
+
+## 提交检查
+
+提交前可运行：
+
+```powershell
+.\docs\hooks\commit-check.ps1 -Message "[entity][docs]: 补充实体池说明"
+```
+
+检查项包括：
+
+- 提交信息是否符合 `[模块][类型]: 描述` 格式
+- 变更文件是否能映射到已知模块
+- 模块映射配置来自 [commit-module-mappings.json](commit-module-mappings.json)
+
+---
+
+## 触发方式
+
+| 触发方式 | 命令/路径 | 说明 |
+|---|---|---|
+| Codex Stop hook | `.codex/hooks/archive-reminder.ps1` | 若已配置，每次任务结束自动调用 `hooks/archive-check.ps1` |
+| Claude Code 手动 | 直接运行脚本 | 任务结束时手动调用 `hooks/archive-check.ps1` |
+| 手动脚本 | `hooks/archive-check.ps1` | 直接运行 PowerShell 脚本 |
+
+---
+
+## 新增 Hook 时
+
+1. 把脚本放入 `hooks/`。
+2. 在本文件中登记。
+3. 在 [ai/AI接入入口.md](../ai/AI接入入口.md) 中说明触发方式。
+4. 如果涉及提交信息格式，同步更新 [rules/40-工作流清单.md](../rules/40-工作流清单.md)。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [ai/AI接入入口.md](../ai/AI接入入口.md) | AI 接入入口引用 hook 共享层 |
+| [rules/项目规则入口.md](../rules/项目规则入口.md) | 规则入口索引归档触发机制 |
+| [rules/40-工作流清单.md](../rules/40-工作流清单.md) | 提交前检查与工作流清单互相引用 |
--- a/hooks/archive-check.ps1
+++ b/hooks/archive-check.ps1
@@ -0,0 +1,181 @@
+# hooks/archive-check.ps1
+# Check changed .md files and suggest related docs to update.
+# This script only outputs suggestions; it does NOT modify any files.
+#
+# Mechanism:
+#   For every changed .md file, parse its "## 文档关联" section and extract
+#   Markdown links. Those links are the documents that may need syncing.
+
+$ErrorActionPreference = "SilentlyContinue"
+
+$scriptPath = $MyInvocation.MyCommand.Path
+if (-not [System.IO.Path]::IsPathRooted($scriptPath)) {
+    $scriptPath = Join-Path (Get-Location) $scriptPath
+}
+$scriptPath = [System.IO.Path]::GetFullPath($scriptPath)
+$scriptDir = Split-Path -Parent $scriptPath
+$projectRoot = [System.IO.Path]::GetFullPath((Join-Path $scriptDir ".."))
+
+Set-Location $projectRoot
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+function Resolve-RelativePath {
+    param(
+        [string]$BaseFile,
+        [string]$LinkPath
+    )
+
+    # Skip anchors, query strings, and external URLs
+    if ($LinkPath -match '^[a-zA-Z][a-zA-Z0-9+.-]*://') { return $null }
+    if ([string]::IsNullOrWhiteSpace($LinkPath)) { return $null }
+
+    # Drop fragment
+    $pathOnly = ($LinkPath -split '#')[0]
+    if ([string]::IsNullOrWhiteSpace($pathOnly)) { return $null }
+
+    $baseDir = Split-Path -Parent $BaseFile
+    $combined = Join-Path $baseDir $pathOnly
+    try {
+        $resolved = [System.IO.Path]::GetFullPath($combined)
+    } catch {
+        return $null
+    }
+
+    # Convert to relative path from project root, normalizing separators
+    $fullProjectRoot = [System.IO.Path]::GetFullPath($projectRoot)
+    if ($resolved.StartsWith($fullProjectRoot, [System.StringComparison]::OrdinalIgnoreCase)) {
+        $relative = $resolved.Substring($fullProjectRoot.Length).TrimStart('\', '/')
+        return $relative -replace '\\', '/'
+    }
+    return $pathOnly -replace '\\', '/'
+}
+
+function Get-DocumentAssociations {
+    param(
+        [string]$MdFile
+    )
+
+    $fullPath = Join-Path $projectRoot $MdFile
+    if (-not (Test-Path $fullPath)) { return @() }
+
+    $lines = [System.IO.File]::ReadAllLines($fullPath, [System.Text.Encoding]::UTF8)
+    $associations = @()
+    $inSection = $false
+    $inCodeBlock = $false
+
+    foreach ($line in $lines) {
+        # Toggle fenced code block state (``` or ~~~)
+        if ($line -match '^\s*```' -or $line -match '^\s*~~~') {
+            $inCodeBlock = -not $inCodeBlock
+            continue
+        }
+        if ($inCodeBlock) { continue }
+
+        # Match exactly '## 文档关联' (not '## 文档关联机制' etc.).
+        if ($line -match "^##\s+文档关联\s*$") {
+            $inSection = $true
+            continue
+        }
+        if ($inSection -and $line -match '^##\s+') {
+            break
+        }
+        if ($inSection) {
+            # Extract markdown links: [text](path)
+            $regex = '\[(?<text>[^\]]*)\]\((?<path>[^\)]+)\)'
+            $matches = [regex]::Matches($line, $regex)
+            foreach ($match in $matches) {
+                $linkPath = $match.Groups['path'].Value.Trim()
+                $resolved = Resolve-RelativePath -BaseFile $MdFile -LinkPath $linkPath
+                if ($resolved) {
+                    $associations += $resolved
+                }
+            }
+        }
+    }
+
+    return $associations | Select-Object -Unique
+}
+
+function Test-WildcardMatch {
+    param(
+        [string]$Pattern,
+        [string]$Path
+    )
+    $regex = "^" + ($Pattern -replace "\.", "\." -replace "\*", ".*" -replace "\?", ".") + "$"
+    return $Path -match $regex
+}
+
+# ---------------------------------------------------------------------------
+# Collect changed .md files (tracked modifications + untracked new files)
+# ---------------------------------------------------------------------------
+
+$changedFiles = @(cmd /c "git diff --name-only 2>nul") | Where-Object { $_ }
+if ($changedFiles.Count -eq 0) {
+    $changedFiles = @(cmd /c "git diff --name-only --cached 2>nul") | Where-Object { $_ }
+}
+
+# Also include untracked .md files so new documents are checked too
+$untrackedFiles = @(cmd /c "git ls-files --others --exclude-standard 2>nul") | Where-Object { $_ }
+$allChangedFiles = @($changedFiles) + @($untrackedFiles) | Where-Object { $_ } | Select-Object -Unique
+
+if (-not $allChangedFiles) {
+    Write-Output "[archive-check] No documentation changes detected (git diff is empty and no untracked .md files)."
+    exit 0
+}
+
+$changedMdFiles = $allChangedFiles | Where-Object { $_ -like "*.md" } | Select-Object -Unique
+
+if ($changedMdFiles.Count -eq 0) {
+    Write-Output "[archive-check] No .md documentation changes detected."
+    exit 0
+}
+
+# ---------------------------------------------------------------------------
+# Build suggestions from each changed file's "## 文档关联" section
+# ---------------------------------------------------------------------------
+
+$suggestions = @{}
+
+foreach ($changed in $changedMdFiles) {
+    $relatedDocs = Get-DocumentAssociations -MdFile $changed
+    foreach ($related in $relatedDocs) {
+        # Normalize related path
+        $relatedNormalized = $related -replace '\\', '/'
+        if (-not $suggestions.ContainsKey($relatedNormalized)) {
+            $suggestions[$relatedNormalized] = @()
+        }
+        if ($suggestions[$relatedNormalized] -notcontains $changed) {
+            $suggestions[$relatedNormalized] += $changed
+        }
+    }
+}
+
+# ---------------------------------------------------------------------------
+# Output results
+# ---------------------------------------------------------------------------
+
+Write-Output "[archive-check] Changed documentation files:"
+foreach ($changed in $changedMdFiles | Sort-Object) {
+    Write-Output "  - $changed"
+}
+
+if ($suggestions.Count -eq 0) {
+    Write-Output ""
+    Write-Output "[archive-check] No associations found in changed files' `"## 文档关联`" sections."
+    exit 0
+}
+
+Write-Output ""
+Write-Output "[archive-check] Related docs that may need updating:"
+foreach ($related in $suggestions.Keys | Sort-Object) {
+    $sources = $suggestions[$related] | Sort-Object
+    $sourceList = $sources -join ", "
+    Write-Output "  - $related (mentioned by: $sourceList)"
+}
+
+Write-Output ""
+Write-Output "[archive-check] Please confirm whether to sync-update the above docs."
+exit 0
--- a/hooks/commit-check.ps1
+++ b/hooks/commit-check.ps1
@@ -0,0 +1,111 @@
+<#
+.SYNOPSIS
+    提交前共享检查：推断变更文件所属模块，校验提交信息格式。
+
+.DESCRIPTION
+    读取 git diff 中变更的文件，根据 hooks/commit-module-mappings.json
+    推断模块，然后校验提交信息是否符合 [模块][类型]: 描述 格式。
+
+.PARAMETER Message
+    待校验的提交信息。
+
+.EXAMPLE
+    .\docs\hooks\commit-check.ps1 -Message "[entity][docs]: 补充实体池说明"
+#>
+
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Message
+)
+
+$ErrorActionPreference = 'Stop'
+
+$mappingFile = Join-Path $PSScriptRoot 'commit-module-mappings.json'
+if (-not (Test-Path $mappingFile)) {
+    Write-Error "Module mapping file not found: $mappingFile"
+    exit 1
+}
+
+$mapping = Get-Content $mappingFile -Raw | ConvertFrom-Json
+
+function Get-ChangedFiles {
+    $staged = (cmd /c "git diff --cached --name-only 2>nul") -split "`r?`n" | Where-Object { $_ }
+    if (-not $staged) { $staged = @() }
+
+    $unstaged = (cmd /c "git diff --name-only 2>nul") -split "`r?`n" | Where-Object { $_ }
+    if (-not $unstaged) { $unstaged = @() }
+
+    $all = @($staged) + @($unstaged) | Select-Object -Unique | Where-Object { $_ }
+    return $all
+}
+
+function Get-ModuleForFile($file) {
+    foreach ($entry in $mapping.mappings) {
+        if ($file -match $entry.pattern) {
+            return $entry.module
+        }
+    }
+    return $null
+}
+
+function Get-ModulesFromChangedFiles($files) {
+    $modules = @()
+    foreach ($file in $files) {
+        $module = Get-ModuleForFile $file
+        if ($module) {
+            $modules += $module
+        }
+    }
+    return $modules | Select-Object -Unique
+}
+
+function Test-CommitMessage($message, $modules) {
+    if ($message -notmatch '^\[([^\]]+)\]\[([^\]]+)\]:\s*(.+)$') {
+        return @{ IsValid = $false; Reason = '提交信息格式应为：[模块][类型]: 描述' }
+    }
+
+    $msgModule = $Matches[1]
+    $msgType = $Matches[2]
+    $msgDesc = $Matches[3]
+
+    if (-not $msgDesc) {
+        return @{ IsValid = $false; Reason = '提交信息缺少描述内容' }
+    }
+
+    if ($mapping.validTypes -notcontains $msgType) {
+        return @{ IsValid = $false; Reason = "无效的类型 '$msgType'。有效类型：$($mapping.validTypes -join ', ')" }
+    }
+
+    if ($modules -and $modules -notcontains $msgModule) {
+        Write-Warning "提交信息中的模块 [$msgModule] 与变更文件推断的模块 [$($modules -join ', ')] 不一致，请确认是否 intentional。"
+    }
+
+    return @{ IsValid = $true; Reason = '' }
+}
+
+$files = Get-ChangedFiles
+if (-not $files) {
+    Write-Host "未检测到变更文件。" -ForegroundColor Yellow
+    exit 0
+}
+
+$modules = Get-ModulesFromChangedFiles $files
+
+Write-Host "变更文件："
+$files | ForEach-Object { Write-Host "  - $_" }
+
+if ($modules) {
+    Write-Host "推断模块：$($modules -join ', ')"
+}
+else {
+    Write-Warning "未能从变更文件推断出模块，请检查提交信息是否手动指定了正确模块。"
+}
+
+$result = Test-CommitMessage $Message $modules
+if (-not $result.IsValid) {
+    Write-Error $result.Reason
+    exit 1
+}
+
+Write-Host "提交信息格式正确。" -ForegroundColor Green
+exit 0
--- a/hooks/commit-module-mappings.json
+++ b/hooks/commit-module-mappings.json
@@ -0,0 +1,88 @@
+{
+  "mappings": [
+    {
+      "pattern": "rules/.*",
+      "module": "rules"
+    },
+    {
+      "pattern": "modules/frameworks/实体系统.*",
+      "module": "entity"
+    },
+    {
+      "pattern": "modules/frameworks/UI窗口系统.*",
+      "module": "ui"
+    },
+    {
+      "pattern": "modules/frameworks/事件系统.*",
+      "module": "event"
+    },
+    {
+      "pattern": "modules/frameworks/资源管理.*|modules/frameworks/通用框架.*",
+      "module": "resource"
+    },
+    {
+      "pattern": "modules/frameworks/内存对象管理.*",
+      "module": "pool"
+    },
+    {
+      "pattern": "modules/frameworks/相机系统.*",
+      "module": "camera"
+    },
+    {
+      "pattern": "modules/frameworks/场景系统.*",
+      "module": "scene"
+    },
+    {
+      "pattern": "modules/frameworks/网络系统.*",
+      "module": "network"
+    },
+    {
+      "pattern": "modules/frameworks/数据配置框架.*",
+      "module": "config"
+    },
+    {
+      "pattern": "modules/frameworks/技能系统.*",
+      "module": "skill"
+    },
+    {
+      "pattern": "modules/frameworks/Hotfix启动.*",
+      "module": "hotfix"
+    },
+    {
+      "pattern": "modules/frameworks/编辑器工具.*|modules/frameworks/第三方插件.*",
+      "module": "editor"
+    },
+    {
+      "pattern": "hooks/.*",
+      "module": "hooks"
+    },
+    {
+      "pattern": "ai/.*|AGENTS\\.md|CLAUDE\\.md|RULES\\.md",
+      "module": "ai"
+    },
+    {
+      "pattern": "specs/.*|plans/.*",
+      "module": "spec"
+    },
+    {
+      "pattern": "modules/frameworks/编辑器工具/UI工具/.*",
+      "module": "tools"
+    },
+    {
+      "pattern": "business-reference/.*",
+      "module": "business-reference"
+    },
+    {
+      "pattern": "README\\.md",
+      "module": "docs"
+    }
+  ],
+  "validTypes": [
+    "feat",
+    "fix",
+    "docs",
+    "refactor",
+    "test",
+    "chore"
+  ]
+}
--- a/hooks/sync-doc-associations.ps1
+++ b/hooks/sync-doc-associations.ps1
@@ -0,0 +1,22 @@
+# hooks/sync-doc-associations.ps1
+# Wrapper for sync_doc_associations.py
+# This script appends change reminders to associated .md files.
+# It only appends to standard sections; it never overwrites existing content.
+
+$ErrorActionPreference = "Stop"
+
+$scriptPath = $MyInvocation.MyCommand.Path
+if (-not [System.IO.Path]::IsPathRooted($scriptPath)) {
+    $scriptPath = Join-Path (Get-Location) $scriptPath
+}
+$scriptPath = [System.IO.Path]::GetFullPath($scriptPath)
+$scriptDir = Split-Path -Parent $scriptPath
+$pythonScript = Join-Path $scriptDir "sync_doc_associations.py"
+
+if (-not (Test-Path $pythonScript)) {
+    Write-Error "Python script not found: $pythonScript"
+    exit 1
+}
+
+python "$pythonScript"
+exit $LASTEXITCODE
--- a/hooks/sync_doc_associations.py
+++ b/hooks/sync_doc_associations.py
@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+# hooks/sync_doc_associations.py
+#
+# 当 md 文件变更时，自动在关联文档的标准位置追加变更提醒：
+#   - 有 ## 变更记录 表格的模块文档：追加一行变更记录
+#   - 有 ## 下一步 清单的 progress/tasks 文档：追加一个待检查项
+#   - 其他文档：追加 ## 最近关联变更 章节
+#
+# 本脚本只追加、不覆盖正文；执行后请通过 git diff 人工确认。
+
+import os
+import re
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+
+EXCLUDED_PREFIXES = (
+    '.claude/', '.codex/', '.git/',
+    'Library/', 'Temp/', 'Logs/', 'UserSettings/',
+    'obj/', 'bin/', 'HybridCLRData/',
+    'Assets/ThirdPlugins/',
+    'Assets/.WX-WASM-SDK-V2/',
+    'Packages/',
+)
+
+
+def run_git(args):
+    result = subprocess.run(
+        ["git"] + args,
+        cwd=PROJECT_ROOT,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+    )
+    return result.stdout.strip(), result.returncode
+
+
+def get_changed_md_files():
+    """获取 tracked 改动 + untracked 新 md 文件。"""
+    changed, code = run_git(["diff", "--name-only"])
+    if code != 0 or not changed:
+        changed = ""
+
+    untracked, code = run_git(["ls-files", "--others", "--exclude-standard"])
+    if code == 0 and untracked:
+        changed = (changed + "\n" + untracked).strip()
+
+    if not changed:
+        return []
+
+    files = [line.strip() for line in changed.splitlines() if line.strip().endswith(".md")]
+    files = [f for f in files if not f.startswith(EXCLUDED_PREFIXES)]
+    return sorted(set(files))
+
+
+def resolve_link(source_file: Path, link: str):
+    """解析相对链接为项目相对路径。"""
+    if re.match(r"^[a-zA-Z][a-zA-Z0-9+.-]*://", link):
+        return None
+    if link.startswith("#"):
+        return None
+    link = link.split("#")[0]
+    if not link:
+        return None
+    target = (source_file.parent / link).resolve()
+    try:
+        target.relative_to(PROJECT_ROOT)
+    except ValueError:
+        return None
+    rel = target.relative_to(PROJECT_ROOT)
+    return str(rel).replace("\\", "/")
+
+
+def extract_associations(md_path: Path):
+    """读取 md 的 ## 文档关联 章节，返回关联文件相对路径列表。"""
+    content = md_path.read_text(encoding="utf-8")
+    in_section = False
+    targets = []
+    for line in content.splitlines():
+        if re.match(r"^##\s+文档关联\s*$", line):
+            in_section = True
+            continue
+        if in_section and re.match(r"^##\s+", line):
+            break
+        if in_section:
+            for _, link in re.findall(r"\[([^\]]*)\]\(([^\)]+)\)", line):
+                resolved = resolve_link(md_path, link)
+                if resolved:
+                    targets.append(resolved)
+    return targets
+
+
+def find_section_range(lines, title_re):
+    """返回 [start, end) 行号，end 为下一个 ## 标题或文件末尾。"""
+    start = None
+    for i, line in enumerate(lines):
+        if re.match(title_re, line):
+            start = i
+            continue
+        if start is not None and re.match(r"^##\s+", line):
+            return start, i
+    if start is not None:
+        return start, len(lines)
+    return None, None
+
+
+def append_changelog(target_path: Path, source_rel: str, date_str: str) -> bool:
+    """在 ## 变更记录 表格追加一行；成功返回 True。"""
+    content = target_path.read_text(encoding="utf-8")
+    lines = content.splitlines()
+    start, end = find_section_range(lines, r"^##\s+变更记录\s*$")
+    if start is None:
+        return False
+
+    # 找到表格最后一行（跳过标题和分隔线）
+    insert_pos = end
+    for i in range(start + 1, end):
+        if lines[i].strip().startswith("|") and not re.match(r"^\|[-:\s|]+\|$", lines[i].strip()):
+            insert_pos = i + 1
+
+    new_line = f"| {date_str} | [{source_rel}](../../{source_rel}) 发生变更 | 待补充影响范围 | 待确认 |"
+    lines.insert(insert_pos, new_line)
+    target_path.write_text("\n".join(lines) + ("\n" if content.endswith("\n") else ""), encoding="utf-8")
+    return True
+
+
+def append_next_step(target_path: Path, source_rel: str) -> bool:
+    """在 ## 下一步 清单追加一个待检查项；成功返回 True。"""
+    content = target_path.read_text(encoding="utf-8")
+    lines = content.splitlines()
+    start, end = find_section_range(lines, r"^##\s+下一步\s*$")
+    if start is None:
+        return False
+
+    new_line = f"- [ ] 检查 [{source_rel}](../../{source_rel}) 的变更是否影响本文档"
+    # 避免重复
+    for line in lines[start:end]:
+        if source_rel in line and "变更是否影响本文档" in line:
+            return True  # 已存在，视为成功但不写入
+
+    lines.insert(end, new_line)
+    target_path.write_text("\n".join(lines) + ("\n" if content.endswith("\n") else ""), encoding="utf-8")
+    return True
+
+
+def append_recent_changes_section(target_path: Path, source_rel: str, date_str: str) -> bool:
+    """在没有 变更记录/下一步 的文档末尾追加 ## 最近关联变更。"""
+    content = target_path.read_text(encoding="utf-8")
+    # 生成从 target 到 source 的相对链接
+    try:
+        link = os.path.relpath(PROJECT_ROOT / source_rel, target_path.parent).replace("\\", "/")
+    except ValueError:
+        link = source_rel
+
+    if "## 最近关联变更" in content:
+        lines = content.splitlines()
+        start, end = find_section_range(lines, r"^##\s+最近关联变更\s*$")
+        if start is not None:
+            new_line = f"- {date_str}：关联文档 [{source_rel}]({link}) 发生变更，需同步检查。"
+            lines.insert(end, new_line)
+            target_path.write_text("\n".join(lines) + ("\n" if content.endswith("\n") else ""), encoding="utf-8")
+            return True
+
+    section = (
+        "\n---\n\n"
+        "## 最近关联变更\n\n"
+        f"- {date_str}：关联文档 [{source_rel}]({link}) 发生变更，需同步检查。\n"
+    )
+    target_path.write_text(content.rstrip() + section, encoding="utf-8")
+    return True
+
+
+def sync_associations():
+    changed_files = get_changed_md_files()
+    if not changed_files:
+        print("[sync-doc-assoc] No .md changes detected.")
+        return 0
+
+    date_str = datetime.now().strftime("%Y-%m-%d")
+    modified = []
+
+    for source_rel in changed_files:
+        source_path = PROJECT_ROOT / source_rel
+        if not source_path.exists():
+            continue
+        targets = extract_associations(source_path)
+        for target_rel in targets:
+            target_path = PROJECT_ROOT / target_rel
+            if not target_path.is_file():
+                # Skip directories, globs, or missing targets
+                continue
+            if target_rel == source_rel:
+                continue
+
+            done = (
+                append_changelog(target_path, source_rel, date_str)
+                or append_next_step(target_path, source_rel)
+                or append_recent_changes_section(target_path, source_rel, date_str)
+            )
+            if done:
+                modified.append((source_rel, target_rel))
+
+    if not modified:
+        print("[sync-doc-assoc] No associated docs need updating.")
+        return 0
+
+    print("[sync-doc-assoc] Updated associated docs:")
+    for source, target in modified:
+        print(f"  - {source} -> {target}")
+    print("\n[sync-doc-assoc] Please review the changes with git diff before committing.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(sync_associations())
--- a/modules/frameworks/Hotfix启动.md
+++ b/modules/frameworks/Hotfix启动.md
@@ -0,0 +1,95 @@
+# Hotfix 启动
+
+## 分类
+
+- 核心框架
+
+## 目的
+
+记录 hotfix 侧根入口和功能目录聚合，梳理游戏启动链路。
+
+---
+
+## 核心路径
+
+- `Assets/Game/GameHFScripte/GameFunction/GameRoot/`
+- 关键文件：`HFGameStart.cs`、`HFFunCatalogue_GameManager.cs`
+- 程序集：`GameHF`
+
+---
+
+## 启动调用链
+
+```text
+HFGameStart.Init(GameSetting)
+  -> HFFunCatalogue.SetGameSetting
+  -> HFFunCatalogue.ChangeLanguage(enHFLanguageClassify.EN)
+  -> HFGameStartAssetsCheckManager.CheckFirstDownLoadWindowAsset
+  -> HFGameStart.LoadDB
+  -> Hotfix_ZYXlsx_GoogleProtobuf_Helper.LoadAllXlsx
+  -> HFFunCatalogue.Scene.LoadScene(enHFSceneName.Game)
+  -> HFGameStart.InitManager
+  -> HFFunCatalogue.UIManager.OpenWindow<登录窗口>
+```
+
+---
+
+## InitManager 初始化单例
+
+`HFGameStart.InitManager()` 负责初始化各业务/框架管理器，例如：
+
+- `HFSeverManager`
+- `HFMapManager`
+- `HFDamageManager`
+- `HFPopupTextManager`
+- 各业务管理器（如背包、登录等，按项目实际）
+
+---
+
+## HFFunCatalogue 聚合入口
+
+`HFFunCatalogue` 提供统一访问入口：
+
+- `UIManager` — UI 窗口
+- `Asset` — 资源加载
+- `Scene` — 场景加载
+- `Sprite` — 图集/精灵
+- `EntityPool` — 实体池
+- `LinePool` / `SoundPool` — 其他对象池
+- `Event` — 事件系统
+- `GameConstant` — 游戏常量
+- `NDB` — 配置表读取
+- `Bag` / `Tips` — 业务相关入口（按项目实际）
+
+---
+
+## 使用规则
+
+- 业务代码通过 `HFFunCatalogue` 访问核心库，禁止直接实例化核心库内部类。
+- `HFGameStart` 是 hotfix 侧启动入口，不要绕过它直接初始化管理器。
+- 启动顺序修改需谨慎，确保配置表、资源、场景按正确顺序加载。
+
+---
+
+## 相关模块
+
+- [UI 窗口系统](UI窗口系统/README.md)
+- [资源管理](资源管理/README.md)
+- [场景系统](场景系统.md)
+- [数据/配置框架](数据配置框架.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/UI窗口系统/README.md](UI窗口系统/README.md) | 启动后打开登录窗口依赖 UI 框架 |
+| [modules/frameworks/资源管理/README.md](资源管理/README.md) | 启动流程涉及资源检查 |
+| [modules/frameworks/场景系统.md](场景系统.md) | 启动流程涉及场景加载 |
+| [modules/frameworks/数据配置框架.md](数据配置框架.md) | 启动流程涉及配置表加载 |
+| [rules/10-架构说明.md](../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/UI窗口系统/README.md
+++ b/modules/frameworks/UI窗口系统/README.md
@@ -0,0 +1,129 @@
+# UI 框架
+
+## 分类
+
+- 项目框架
+
+## 目的
+
+记录 UIWindow 管理、窗口基类、UIMono 桥接、窗口资源加载和 UI 生命周期。
+
+## 已知线索
+
+- 管理路径：`Assets/Game/GameHFScripte/CopyToHF/UIWindowMgr/`
+- 窗口实现：`Assets/Game/GameHFScripte/GameFunction/UIWindows/`
+- Mono 桥接：`Assets/Game/GameMono/Scripts/UIMono/`
+- 资源路径：`Assets/Game/GameHFResource/CN/UIWindows/`
+
+## 已确认链路
+
+UI manager 初始化：
+
+```text
+HFUIWindowMgr.OnAfterCreateInstance()
+  -> OnInitializeCanvasAndCamera()
+  -> 为 enHFUICanvasLayer 创建 Canvas
+  -> 为 ScreenSpaceCamera Canvas 创建 UI Camera
+  -> 创建 CacheSiblingIndex Canvas
+  -> 创建或接管 EventSystem / StandaloneInputModule
+```
+
+打开窗口：
+
+```text
+HFFunCatalogue.UIManager.OpenWindow<T>()
+  -> HFUIWindowMgr.OnOpenWindow<HFUIWindowSetting>()
+  -> 创建 HFDefaultTask / HFUIWindow_RespondTask
+  -> 读取窗口类型上的 HFAssetBundlePathAttribute 和 HFUIWindowLayerAttribute
+  -> OnSettingWindowSiblingIndex()
+  -> 从缓存队列复用窗口实例，或 Activator.CreateInstance 创建窗口逻辑实例
+  -> OnPreloadWindowInMemory()
+  -> HFABMgr.Instance.LoadInMemory(windowPrefabPath)
+  -> win.BindGameObject(prefab)
+  -> OnAttachWindow(win)
+  -> win.SyncWindowState()
+  -> AbsHFUIWindow.OnOpen()
+```
+
+关闭窗口：
+
+```text
+CloseWindow<T>() / AbsHFUIWindow.CloseWindow()
+  -> HFUIWindowMgr.OnCloseWindow()
+  -> siblingIndexLayer.ToggleWindowActive(false)
+  -> 放入 mCacheWindowInstanceMaping
+  -> 处理 backtrack 自动恢复窗口
+  -> win.SyncWindowState()
+  -> AbsHFUIWindow.OnClose()
+```
+
+窗口资源绑定：
+
+- 窗口类通过 `[HFAssetBundlePath(...)]` 标记 prefab 路径。
+- 窗口类通过 `[HFUIWindowLayer(...)]` 标记 Canvas/Layer 和是否允许多开。
+- `AbsHFUIWindowSetting.SetWindowType` 会读取上述 attribute，生成 `winId`、`winTypeId` 和资源路径。
+
+## 使用规则
+
+- 新窗口必须继承 `AbsHFUIWindow`。
+- 新窗口必须配置 `HFAssetBundlePath` 和 `HFUIWindowLayer`。
+- 打开窗口统一走 `HFFunCatalogue.UIManager.OpenWindow<T>()`。
+- 关闭窗口统一走 `CloseWindow()` 或 `HFFunCatalogue.UIManager.CloseWindow<T>()`。
+- 在 `OnOpen` 中注册的事件必须在 `OnClose` 中移除。
+- 不直接 `Instantiate` / `Destroy` UI 窗口 prefab。
+- 不绕过 `HFUIWindowMgr` 手动修改窗口 active、父节点或 siblingIndex。
+- 普通业务窗口默认使用 `Dynamic`，提示类优先使用 `Tooltip`，强交互弹窗优先使用 `Popup`，`Highest` 仅用于明确的顶层兜底。
+- UI prefab 放在 `Assets/Game/GameHFResource/<语言>/UIWindows/<模块>/`，代码中的 `HFAssetBundlePath` 使用相对 `UIWindows/...` 的路径。
+- 优先使用项目已有 UIMono / ZYUGUI 绑定流程，不手写大量 `transform.Find`。
+- 列表、循环列表、网格优先使用已有 ZYUGUI / SuperScrollView 组件和编辑器转换工具。
+- 异步加载或动画结束后再调用完成回调时，必须保证失败/取消路径不会卡住窗口状态。
+
+## 新增 UI 窗口清单
+
+1. 确认窗口所属功能模块。
+2. 创建窗口类，继承 `AbsHFUIWindow`。
+3. 添加 `HFAssetBundlePath` 和 `HFUIWindowLayer`。
+4. 创建或更新 prefab。
+5. 使用 UIMono / ZYUGUI 生成或绑定 UI 引用。
+6. 用 `HFFunCatalogue.UIManager.OpenWindow<T>()` 接入入口。
+7. 在 `OnOpen` / `OnClose` 对称处理事件、计时器、临时数据。
+8. 验证打开、关闭、重复打开、切场景或语言变化时的表现。
+9. 如果新增模块或改变 UI 架构，更新相关模块文档。
+
+## 梳理任务
+
+- [x] 梳理窗口基类和打开/关闭 API。
+- [x] 梳理窗口 prefab 路径绑定方式。
+- [ ] 梳理 UIMono 自动绑定和 partial 生成关系。
+- [x] 梳理窗口生命周期：Open/Close/状态同步。
+- [x] 梳理 UI 事件订阅和释放规范。
+- [x] 梳理功能 UI 和框架 UI 的边界。
+
+## 待确认
+
+- 常规入口已确认是 `HFFunCatalogue.UIManager` / `HFUIWindowMgr`，是否存在绕过路径待继续扫描。
+- UI 资源会经过 `HFAssetBundlePathAttribute` 和语言路径规则，哪些 UI 真正有 CN/EN 差异待确认。
+- UIMono 是否由编辑器工具生成。
+- `OnOpen`/`OnClose` 外是否还有业务窗口统一订阅/释放规范待确认。
+
+## 相关模块
+
+- [资源框架](../资源管理/README.md)
+- [事件框架](../事件系统/README.md)
+- [ZYUGUI Tools](../../模块索引.md#编辑器工具)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../模块索引.md) | ZYUGUI Tools |
+| [modules/frameworks/事件系统/README.md](../事件系统/README.md) | 事件框架 |
+| [modules/frameworks/资源管理/README.md](../资源管理/README.md) | 资源框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 开发规则与框架/生成规则互相引用 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖或使用本框架的模块文档 | 如依赖本框架的功能模块 |
--- a/modules/frameworks/UI窗口系统/开发指南.md
+++ b/modules/frameworks/UI窗口系统/开发指南.md
@@ -1,4 +1,4 @@
-# StrayFog 框架 UI开发指南
+# StrayFog 框架 UI 开发指南

 ## 一、窗口开发

@@ -32,9 +32,9 @@ public class MyWindow : AbsHFUIWindow

 | 方法 | 调用时机 | 推荐操作 |
 |-----|---------|---------|
-| `OnRunAwake` | 创建时一次 | 绑定UI事件、初始化滚动列表 `BindEvent` |
-| `OnOpen` | 每次打开 | 注册TC事件、调用 `ShowView()` 刷新数据 |
-| `OnClose` | 每次关闭 | 取消TC事件 |
+| `OnRunAwake` | 创建时一次 | 绑定 UI 事件、初始化滚动列表 `BindEvent` |
+| `OnOpen` | 每次打开 | 注册 TC 事件、调用 `ShowView()` 刷新数据 |
+| `OnClose` | 每次关闭 | 取消 TC 事件 |

 **关键原则**：
 - **绑定类操作**（如 `BindEvent`）放在 `OnRunAwake`，只需执行一次
@@ -54,8 +54,8 @@ HFFunCatalogue.UIManager.CloseWindow<MyWindow>();

 | 事件类型 | 绑定位置 | 是否需要 `-=` |
 |---------|---------|--------------|
-| UI按钮/拖拽 | `OnRunAwake` | 不需要 |
-| 全局TC事件 | `OnOpen`/`OnClose` | 需要 |
+| UI 按钮/拖拽 | `OnRunAwake` | 不需要 |
+| 全局 TC 事件 | `OnOpen`/`OnClose` | 需要 |

 ---

@@ -176,16 +176,16 @@ public class CardItem : AbsListItem<CardData>
 | 类型 | 路径 | 说明 |
 |-----|------|------|
 | **窗口脚本** | `Assets/Game/GameHFScripte/GameFunction/UIWindows/{WindowName}/` | 窗口逻辑脚本存放目录 |
-| **窗口预制体** | `Assets/Game/GameHFResource/CN/UIWindows/{WindowName}/` | UI窗口预制体存放目录 |
-| **图标图集** | `Assets/Game/GameHFResource/CN/SpriteAtlas/{AtlasName}/` | SpriteAtlas图集资源 |
+| **窗口预制体** | `Assets/Game/GameHFResource/CN/UIWindows/{WindowName}/` | UI 窗口预制体存放目录 |
+| **图标图集** | `Assets/Game/GameHFResource/CN/SpriteAtlas/{AtlasName}/` | SpriteAtlas 图集资源 |
 | **字体资源** | `Assets/Game/GameHFResource/CN/Fonts/` | 字体文件存放目录 |

 #### 6.1.2 工具脚本路径

 | 工具名称 | 路径 | 职责 |
 |---------|------|------|
-| **UIPrefabGenerator** | `Assets/Editor/Command/UIPrefabGenerator.cs` | JSON转UI预制体 |
-| **UIPrefabToJson** | `Assets/Editor/Command/UIPrefabToJson.cs` | 预制体转JSON |
+| **UIPrefabGenerator** | `Assets/Editor/Command/UIPrefabGenerator.cs` | JSON 转 UI 预制体 |
+| **UIPrefabToJson** | `Assets/Editor/Command/UIPrefabToJson.cs` | 预制体转 JSON |
 | **RemoteCommand** | `Assets/Editor/Command/RemoteCommand.cs` | 外部命令接口 |
 | **ExternalCommandListener** | `Assets/Editor/Command/ExternalCommandListener.cs` | 外部命令监听器 |

@@ -193,20 +193,39 @@ public class CardItem : AbsListItem<CardData>

 | 文档名称 | 路径 |
 |---------|------|
-| UI开发指南 | `UnityAI/03_核心功能/UI/UI开发指南.md` |
-| UI界面拼接设计指南 | `UnityAI/03_核心功能/UI/UI界面拼接设计指南.md` |
+| UI 开发指南 | [UI窗口系统/开发指南.md](开发指南.md) |
+| UI 界面拼接设计指南 | [UI窗口系统/界面拼接.md](界面拼接.md) |

 #### 6.1.4 命令触发路径

 - **触发文件**: `{ProjectRoot}/Trigger_Command.txt`
- **JSON配置**: `Assets/Editor/UI/{WindowName}.json`
+- **JSON 配置**: `Assets/Editor/UI/{WindowName}.json`

 ### 6.2 性能优化
- 使用对象池复用UI元素
- 将图标打包到SpriteAtlas
+- 使用对象池复用 UI 元素
+- 将图标打包到 SpriteAtlas
 - 滚动列表用 `SFUI_ScrollRect.BindEvent`

 ---

 **版本**: v1.1  
-**适用**: StrayFog框架UI开发人员
+**适用**: StrayFog 框架 UI 开发人员
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [UI 窗口系统入口](README.md) | 本文件是 UI 窗口系统模块的子文档 |
+| [UI 界面拼接设计指南](界面拼接.md) | 界面拼接是 UI 开发的补充设计指南 |
+| [UI 拼接工具](../编辑器工具/UI拼接工具.md) | JSON 驱动 UI 生成工具说明 |
+| [事件系统](../事件系统/README.md) | UI 事件订阅和释放规范 |
+| [对象池与运行时对象管理](../内存对象管理/README.md) | UI 元素复用相关 |
+| [资源管理](../资源管理/README.md) | UI 资源加载依赖资源管理 |
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | UI 命名与编码规范互相引用 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/UI窗口系统/界面拼接.md
+++ b/modules/frameworks/UI窗口系统/界面拼接.md
@@ -0,0 +1,192 @@
+# UI 界面拼接设计指南
+
+## 一、界面结构设计原则
+
+### 1.1 模块化拆分
+
+将界面按功能划分为独立模块：
+
+| 模块类型 | 功能定位 | 示例 |
+|---------|---------|------|
+| **信息展示区** | 显示玩家状态、资源等静态信息 | 顶部信息栏、左侧状态栏 |
+| **功能入口区** | 提供功能按钮入口 | 中央功能区、底部快捷栏 |
+| **交互面板区** | 可展开/收起的功能面板 | 右侧功能面板、顶部按钮区 |
+| **输入输出区** | 用户输入和系统反馈 | 聊天输入框、提示信息 |
+
+### 1.2 经典布局模式
+
+```
+┌─────────────────────────────────────────────────────┐
+│  TopArea          (信息展示 + 可收起功能按钮)        │
+├──────────┬───────────────────────┬──────────────────┤
+│  Left    │                       │  Right           │
+│  Area    │     CenterArea        │  Area            │
+│ (状态)   │   (核心功能入口)       │ (功能面板)       │
+│          │                       │                  │
+├──────────┴───────────────────────┴──────────────────┤
+│  BottomArea       (快捷功能 + 状态信息 + 输入)       │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## 二、组件拆分方法
+
+### 2.1 基础组件识别
+
+| 组件类型 | 识别特征 | 处理方式 |
+|---------|---------|---------|
+| **按钮** | 可点击、有交互反馈 | 使用 `SFUI_Button` |
+| **文本** | 静态/动态文字显示 | 使用 `SFUI_TextMeshProUGUI` |
+| **图片** | 图标、背景图 | 使用 `SFUI_Image` |
+| **进度条** | HP、MP、经验等 | 使用 `SFUI_Slider` |
+| **列表** | 可滚动的项目列表 | 使用 `SFUI_ScrollRect` |
+
+### 2.2 复合组件封装
+
+将功能相关的基础组件组合为复合组件，便于复用和维护：
+
+**设计原则**：
+- 将同一功能模块的组件封装在一起（如玩家头像+血条+蓝条）
+- 提供统一的数据设置接口
+- 保持组件之间的逻辑独立性
+
+---
+
+## 三、预制体层级规范
+
+### 3.1 标准层级结构
+
+```
+WindowName (RectTransform)
+├── ModuleName (RectTransform)           # 模块容器
+│   ├── ComponentName (SFUI_*)           # 功能组件
+│   ├── SubModule (RectTransform)        # 子模块
+│   └── CollapsibleArea (RectTransform)  # 可收起区域
+└── BtnCollapse (SFUI_Button)            # 收起控制按钮
+```
+
+### 3.2 命名规范
+
+| 类型 | 命名规则 | 示例 |
+|-----|---------|------|
+| 模块容器 | PascalCase + Area | `TopArea` |
+| 功能组件 | PascalCase | `BtnCollapseTop` |
+| 可收起区域 | PascalCase + FuncArea | `TopFuncArea` |
+| 状态变量 | m_ + PascalCase | `m_IsTopCollapsed` |
+
+---
+
+## 四、收起/展开功能设计
+
+### 4.1 功能定义
+
+| 按钮 | 控制区域 | 用途 |
+|-----|---------|------|
+| `BtnCollapseTop` | 顶部功能按钮区 | 收起/展开顶部按钮群 |
+| `BtnCollapseRight` | 右侧功能面板区 | 收起/展开右侧功能面板 |
+
+### 4.2 设计要点
+
+**状态管理**：每个可收起区域需要一个布尔状态变量来记录当前收起/展开状态。
+
+**交互逻辑**：
+1. 点击收起按钮时，切换对应区域的显示/隐藏状态
+2. 同时切换按钮图标（收起时显示展开图标，展开时显示收起图标）
+
+**布局要求**：
+- 收起按钮应放置在对应区域的边缘位置，便于用户找到
+- 收起区域内的所有元素应作为一个整体进行显示/隐藏控制
+- 收起状态应在窗口生命周期内保持记忆
+
+---
+
+## 五、实际案例：主界面拼接
+
+### 5.1 模块化设计思想
+
+**核心原则**：将界面按功能边界划分为独立模块，模块内可嵌套子模块。
+
+**模块归类方法**：
+
+1. **一级模块**：按空间位置划分（顶部、左侧、中央、右侧、底部）
+2. **二级模块**：按功能类型划分（信息展示区、功能按钮区、输入输出区）
+3. **三级模块**：按具体功能划分（玩家头像、资源显示、功能按钮群）
+
+**层级关系示例**：
+
+```
+Window
+├── TopArea (一级：位置)
+│   ├── InfoPanel (二级：信息展示)
+│   │   └── TxtWelcome (三级：具体组件)
+│   └── FuncButtons (二级：功能按钮)
+│       └── BtnUpload (三级：具体按钮)
+└── LeftArea (一级：位置)
+    └── PlayerPortrait (二级：复合组件)
+        ├── ImgAvatar (三级：头像)
+        └── BarHP (三级：血条)
+```
+
+**设计要点**：
+- 同一功能域内的元素归为同一模块（如头像、血条、蓝条归为玩家状态模块）
+- 独立交互功能作为独立模块（如收起按钮单独作为控制模块）
+- 可收起区域作为独立子模块，便于统一控制显示/隐藏
+
+---
+
+## 六、界面拼接流程
+
+### 6.1 设计阶段
+1. **需求分析**：明确界面功能和交互需求
+2. **模块划分**：将界面拆分为独立功能模块
+3. **层级设计**：设计预制体层级结构
+
+### 6.2 开发阶段
+1. **组件创建**：创建基础组件和复合组件
+2. **预制体搭建**：按层级结构搭建预制体
+3. **脚本编写**：实现交互逻辑和收起/展开功能
+
+### 6.3 测试阶段
+1. **功能测试**：验证所有按钮和交互功能
+2. **收起测试**：测试收起/展开功能正常工作
+3. **适配测试**：验证不同分辨率下的显示效果
+
+---
+
+## 七、注意事项
+
+1. **组件复用**：相同功能的组件尽量复用，减少冗余
+2. **状态管理**：收起状态需要正确保存和恢复
+3. **图标反馈**：收起按钮图标应随状态变化
+4. **性能优化**：可收起区域使用 `SetActive` 而非销毁重建
+5. **命名规范**：统一的命名规则便于维护和查找
+
+---
+
+## 八、JSON 配置驱动的 UI 生成方式
+
+本项目支持通过 JSON 配置快速生成 UI 预制体，详细工具说明、命令格式和部署步骤见 [UI 拼接工具](../编辑器工具/UI拼接工具.md)。
+
+UI 相关人员核心工作流程：读取设计效果图和碎片图片，生成 JSON 配置文件，再通过工具自动生成 Unity 预制体。
+
+---
+
+**版本**: v1.2  
+**适用**: StrayFog 框架 UI 拼接开发人员
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [UI 窗口系统入口](README.md) | 本文件是 UI 窗口系统模块的子文档 |
+| [UI 开发指南](开发指南.md) | 窗口开发与界面拼接互相补充 |
+| [UI 拼接工具](../编辑器工具/UI拼接工具.md) | JSON 驱动 UI 生成工具说明 |
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | UI 命名与资源规则互相引用 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/事件系统/README.md
+++ b/modules/frameworks/事件系统/README.md
@@ -0,0 +1,122 @@
+# 事件系统
+
+## 分类
+
+- 核心框架
+
+## 目的
+
+提供客户端内部事件（CTC）和服务器消息事件（STC）的统一派发、监听和释放机制。
+
+---
+
+## 核心路径
+
+- 框架层：`Assets/Game/GameHFScripte/CopyToHF/Event/`
+- 功能层：`Assets/Game/GameHFScripte/GameFunction/Event/`
+- STC 事件参数：`Assets/Game/GameHFScripte/GameFunction/Event/STCEventArg/`
+
+---
+
+## 核心类
+
+| 类 | 职责 |
+|---|---|
+| `HFEventManager` | 事件管理器单例，继承 `AbsHFSingleRunTime<HFEventManager>` |
+| `TCEvent` | CTC 事件句柄 |
+| `STCEvent` | STC 事件句柄 |
+| `CTCHandle` | CTC 事件处理器定义位置 |
+| `AbsHFEventArg<K,T>` | 事件参数基类 |
+
+---
+
+## 事件派发链路
+
+### CTC 事件
+
+```text
+AbsHFEventArg<enHFCTCEvent>.Dispatch()
+  -> HFEventManager.Instance.TCEvent.Dispatch(arg)
+```
+
+CTC 事件来源：
+
+- 功能代码手动创建事件参数对象。
+- 设置字段后调用 `.Dispatch()`。
+- 示例：业务管理器派发初始化事件、背包更新事件。
+
+### STC 事件
+
+```text
+AbsHFEventArg<enHFSTCEvent>.Dispatch()
+  -> HFEventManager.Instance.STCEvent.Dispatch(arg)
+```
+
+STC 事件来源：
+
+```text
+WSSession 收到 protobuf S2C
+  -> 反射创建 HFEvent_STC_{MessageTypeName}
+  -> 写入 Request / ErrorCode
+  -> Dispatch 到 STCEvent
+```
+
+---
+
+## 监听与派发机制
+
+```text
+AddListener<TEventArg>(eventId, callback)
+  -> 按 eventId 分组
+  -> 按事件参数类型 hash 分组
+
+Dispatch(arg)
+  -> 根据 arg.eventId 找事件组
+  -> 根据 arg.GetType() 找具体类型监听
+  -> Invoke callbacks
+  -> arg.Recycle()
+```
+
+---
+
+## 使用规则
+
+- UI 窗口在 `OnOpen` 中注册的事件，必须在 `OnClose` 中移除。
+- 管理器监听 STC 事件通常在初始化时添加，在 `Recycle` 或销毁时移除。
+- 不要直接监听与当前模块无关的事件。
+- 事件参数对象由框架自动回收，业务代码不要重复释放。
+
+---
+
+## 错误响应
+
+当服务器返回错误响应时：
+
+```text
+messagePage.IsError = true
+  -> 解析 ErrorResponse
+  -> 派发 HFEvent_ErrorCode
+  -> 同时仍创建对应 HFEvent_STC_* 并写入 ErrorCode
+```
+
+---
+
+## 相关模块
+
+- [网络系统](../网络系统.md)
+- [UI 窗口系统](../UI窗口系统/README.md)
+- [实体系统](../实体系统/README.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/网络系统.md](../网络系统.md) | S2C 消息是 STC 事件来源 |
+| [modules/frameworks/UI窗口系统/README.md](../UI窗口系统/README.md) | UI 窗口订阅和释放事件 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/事件系统/使用指南.md
+++ b/modules/frameworks/事件系统/使用指南.md
@@ -1,4 +1,4 @@
-# StrayFog 框架事件系统使用指南
+# 事件系统使用指南

 ## 一、事件系统概述

@@ -13,7 +13,7 @@
 ### 2.1 定义事件枚举和参数

 ```csharp
-// 事件ID枚举
+// 事件 ID 枚举
 public enum GameEventId
 {
    PlayerLevelUp,
@@ -44,9 +44,9 @@ public class PlayerLevelUpEventArgs : GameEventArgs

 ---

-## 三、UI窗口事件监听
+## 三、UI 窗口事件监听

-### 3.1 在窗口中注册CTCEvent
+### 3.1 在窗口中注册 CTCEvent

 ```csharp
 [HFAssetBundlePath(enHFLanguageRootFolder.ASSETS_GAME_GAMEHFRESOURCE, "UIWindows/CardDeck/CardDeckWindow.prefab")]
@@ -70,18 +70,18 @@ public class CardDeckWindow : AbsHFUIWindow
    void OnCardUpdate(HFEventArgBase arg)
    {
        HFEvent_CTC_CardUpdate cardArg = arg as HFEvent_CTC_CardUpdate;
-        // 更新卡组UI显示
+        // 更新卡组 UI 显示
    }
 }
 ```

-> **注意**：UI窗口中**不监听服务器事件（STCEvent）**，服务器事件应在Logic层的Manager中监听。
+> **注意**：UI 窗口中**不监听服务器事件（STCEvent）**，服务器事件应在 Logic 层的 Manager 中监听。

 ---

-## 四、Manager事件监听
+## 四、Manager 事件监听

-### 4.1 使用AbsHFSingleMonoBehaviour（需要Update）
+### 4.1 使用 AbsHFSingleMonoBehaviour（需要 Update）

 ```csharp
 public class PlayerManager : AbsHFSingleMonoBehaviour<PlayerManager>
@@ -107,7 +107,7 @@ public class PlayerManager : AbsHFSingleMonoBehaviour<PlayerManager>
    {
        HFEvent_STC_PlayerInfo info = arg as HFEvent_STC_PlayerInfo;
        // 处理服务器返回的玩家信息
-        // 触发客户端事件通知UI更新
+        // 触发客户端事件通知 UI 更新
        HFEvent_CTC_PlayerLevelUp evt = HFFunCatalogue.New<HFEvent_CTC_PlayerLevelUp>();
        evt.playerId = info.playerId;
        evt.newLevel = info.level;
@@ -116,7 +116,7 @@ public class PlayerManager : AbsHFSingleMonoBehaviour<PlayerManager>
 }
 ```

-### 4.2 使用AbsHFSingleRunTime（纯逻辑）
+### 4.2 使用 AbsHFSingleRunTime（纯逻辑）

 ```csharp
 public class ConfigManager : AbsHFSingleRunTime<ConfigManager>
@@ -137,15 +137,32 @@ public class ConfigManager : AbsHFSingleRunTime<ConfigManager>

 ---

-## 五、Manager类型对比
+## 五、Manager 类型对比

 | 类型 | 说明 | 适用场景 |
 |-----|------|---------|
-| `AbsHFSingleMonoBehaviour` | 生成GameObject，可注册MonoBehaviour事件 | 需要Update/FixedUpdate等生命周期 |
-| `AbsHFSingleRunTime` | 纯内存单例，无GameObject | 不需要生命周期事件 |
+| `AbsHFSingleMonoBehaviour` | 生成 GameObject，可注册 MonoBehaviour 事件 | 需要 Update/FixedUpdate 等生命周期 |
+| `AbsHFSingleRunTime` | 纯内存单例，无 GameObject | 不需要生命周期事件 |

 ---

 **版本**: v1.0  
 **生效日期**: 2026年  
-**适用范围**: GiftGameX项目业务开发人员
+**适用范围**: GiftGameX 项目业务开发人员
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [事件系统入口](README.md) | 本文件是事件系统模块的子文档 |
+| [网络系统](../网络系统.md) | STC 事件来源与网络系统相关 |
+| [UI 窗口系统](../UI窗口系统/README.md) | UI 窗口订阅和释放事件 |
+| [实体系统](../实体系统/README.md) | Manager 常与实体系统协作 |
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 事件订阅/释放与开发规则互相引用 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/内存对象管理/README.md
+++ b/modules/frameworks/内存对象管理/README.md
@@ -0,0 +1,110 @@
+# 对象池与运行时对象管理
+
+## 分类
+
+- 核心框架
+
+## 目的
+
+提供类实例池、行为对象池、脚本对象池、实体池和 RT 展示对象的统一复用机制，减少 GC 和实例化开销。
+
+---
+
+## 核心路径
+
+- 内存管理：`Assets/Game/GameHFScripte/CopyToHF/MemoryManager/`
+- 运行时对象：`Assets/Game/GameHFScripte/GameFunction/RTObjectManager/`
+- 调用池：`Assets/Game/GameHFScripte/GameFunction/Logic/CallPoolManager/`
+- 实体池：`Assets/Game/GameHFScripte/GameFunction/GameEntity/EntityPool/`
+
+---
+
+## 池类型
+
+### HFClassEntityManager
+
+类实例池，按类型 hash 维护 `Stack<object>`。
+
+```text
+GetClassEntity<T>()
+  -> 优先从 Stack 弹出复用
+  -> 否则 Activator.CreateInstance<T>()
+```
+
+### HFSimulateBehaviourPool<T>
+
+行为对象池，用于继承 `AbsHFSimulateBehaviour` 的对象。
+
+- 维护未使用队列和使用中列表。
+- `GiveBack()` 隐藏 GameObject 并调用 `Recycle()`。
+
+### HFScriptMemPool<T>
+
+脚本对象池，用于 `IHFRecycle` 的普通对象或 MonoBehaviour。
+
+- 若类型继承 MonoBehaviour，自动创建 GameObject 挂载组件。
+- 若类型为普通类，直接 `Activator.CreateInstance`。
+
+### 实体池
+
+`HFEntityPool` + 各类 `AbsHFEntityPool` 实现，见 [实体系统](../实体系统/README.md)。
+
+---
+
+## 运行时展示对象（RT）
+
+RT 对象用于在独立相机上展示模型、特效等：
+
+- `RTObject`：运行时展示对象基类
+- `RTGameObjectRes`：从资源 id 创建展示对象
+- `RTEntity`：实体展示对象
+- `RTCameraItem`：RT 相机项
+- `RTUIEffectCameraItem`：UI 特效相机项
+
+创建流程：
+
+```text
+RTGameObjectRes
+  -> 从资源 id 创建 GameObject
+  -> 资源加载走 HFABMgr.Instance.LoadAsset
+```
+
+---
+
+## 回收接口
+
+| 接口 | 职责 |
+|---|---|
+| `IHFRecycle` | 基础回收接口，声明 `Recycle()` |
+| `IHFRecycleEventHandler` | 回收事件处理 |
+| `OnAfterRecycleHandler` | 回收到类实例池 |
+
+---
+
+## 使用规则
+
+- 频繁创建/销毁的对象优先使用对象池。
+- 归还对象时确保来源正确，避免泄漏。
+- 对象池内对象在归还后应重置状态。
+- RT 对象注意及时释放相机 seat 和资源引用。
+
+---
+
+## 相关模块
+
+- [实体系统](../实体系统/README.md)
+- [资源管理](../资源管理/README.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/实体系统/README.md](../实体系统/README.md) | 实体池是对象池的一种特化 |
+| [modules/frameworks/资源管理/README.md](../资源管理/README.md) | RT 对象资源加载依赖资源管理 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/内存对象管理/使用指南.md
+++ b/modules/frameworks/内存对象管理/使用指南.md
@@ -1,6 +1,6 @@
-# StrayFog 框架对象池使用指南
+# 对象池使用指南

-## 一、GameObject对象池
+## 一、GameObject 对象池

 ### 1.1 基本用法

@@ -82,11 +82,11 @@ public class EventArgPool : MonoBehaviour
 ### 3.1 对象池设计特点

 | 特性 | 说明 |
-|-----|-----|
+|-----|------|
 | **双池结构** | 空闲池 + 使用池，高效管理对象状态 |
 | **内存泄漏检测** | 归还时校验来源，及时发现问题 |
 | **泛型支持** | `HFScriptMemPool<T>` 提供类型安全 |
-| **Mono支持** | 自动创建GameObject，无缝集成Unity |
+| **Mono 支持** | 自动创建 GameObject，无缝集成 Unity |

 ### 3.2 性能优化建议

@@ -98,4 +98,19 @@ public class EventArgPool : MonoBehaviour

 **版本**: v1.0  
 **生效日期**: 2026年  
-**适用范围**: GiftGameX项目业务开发人员
+**适用范围**: GiftGameX 项目业务开发人员
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [对象池与运行时对象管理入口](README.md) | 本文件是内存对象管理模块的子文档 |
+| [实体系统](../实体系统/README.md) | 实体池是对象池的一种特化 |
+| [资源管理](../资源管理/README.md) | RT 对象资源加载依赖资源管理 |
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/场景系统.md
+++ b/modules/frameworks/场景系统.md
@@ -0,0 +1,98 @@
+# 场景系统
+
+## 分类
+
+- 核心框架
+
+## 目的
+
+管理 Unity 场景的加载、资源配置读取和场景生命周期回调。
+
+---
+
+## 核心路径
+
+- 场景管理器：`Assets/Game/GameHFScripte/GameFunction/SceneManager/`
+- Unity 场景：`Assets/Game/GameMono/Scenes/`
+
+---
+
+## 核心类
+
+| 类 | 职责 |
+|---|---|
+| `HFSceneMgr` | 场景管理器单例，继承 `AbsHFSingleMonoBehaviour<HFSceneMgr>` |
+| `enHFSceneName` | 场景枚举，例如 `Game = 80001` |
+
+---
+
+## 加载流程
+
+```text
+LoadScene(enHFSceneName scene, Action complete)
+  -> 转为资源/关卡 id
+  -> LoadScene(int levelId, Action complete)
+  -> HFFunCatalogue.NDB.ds_Resource840C5F09TableData.ReadTableByPK(levelId)
+  -> 读取资源配置
+```
+
+### Editor 模式
+
+```text
+从配置 Path 取文件名
+  -> SceneManager.LoadScene(scName)
+```
+
+### 非 Editor 模式
+
+```text
+HFFunCatalogue.Asset.LoadAsset(levelId, ...)
+  -> 用结果中的 res.sceneName 调用 SceneManager.LoadScene
+```
+
+`OnLoadScene()` 同步调用 `SceneManager.LoadScene()` 后立即执行完成回调。
+
+---
+
+## 生命周期
+
+`ZYCore` 中存在 `IZYH_ZYCore_Scene` 和 `AbsZYH_ZYCore_Scene` 接口：
+
+- 进入加载场景
+- 加载完成
+- 进入/退出场景前后
+- 切场景释放
+
+`ZYUGUI` 窗口管理器提供：
+
+- `isAutoCloseWhenToggleScene`：切场景时自动关闭
+- `isAutoDestoryWhenToggleScene`：切场景时自动销毁
+
+---
+
+## 使用规则
+
+- 场景切换统一走 `HFFunCatalogue.Scene.LoadScene()`。
+- 不要在场景里堆放运行时动态加载的资源。
+- 切场景时注意 UI 窗口的自动关闭/销毁配置。
+
+---
+
+## 相关模块
+
+- [资源管理](资源管理/README.md)
+- [UI 窗口系统](UI窗口系统/README.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/资源管理/README.md](资源管理/README.md) | 场景资源加载依赖资源管理 |
+| [modules/frameworks/UI窗口系统/README.md](UI窗口系统/README.md) | 切场景影响 UI 窗口生命周期 |
+| [rules/10-架构说明.md](../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/实体系统/README.md
+++ b/modules/frameworks/实体系统/README.md
@@ -0,0 +1,138 @@
+# 实体系统
+
+## 分类
+
+- 核心框架
+
+## 目的
+
+管理游戏实体的创建、生命周期、System-Model 架构、实体池和子系统协作。
+
+---
+
+## 核心路径
+
+- 实体框架：`Assets/Game/GameHFScripte/GameFunction/GameEntity/`
+- 实体数据：`Assets/Game/GameHFScripte/GameFunction/Logic/EntityData/`
+- 子目录：`Core/`、`Entity/`、`EntityPool/`、`RVO/`、`StateMachineBehaviour/`
+
+---
+
+## 核心类
+
+| 类 | 职责 |
+|---|---|
+| `HFAbsEntity` | 实体基类，继承 `AbsHFSimulateBehaviour` |
+| `HFEntity_Basic` | 基础实体标签 |
+| `HFEntity_Enemy` | 敌人类型标签 |
+| `HFEntity_Human` | 人类/玩家类型标签 |
+| `HFEntityPool` | 实体池入口 |
+| `HFBasicPool` / `HFEnemyPool` / `HFHumanityPool` | 按 `enEntityLayer` 分类的实体池实现 |
+| `AbsHFEntityPool` | 实体池抽象基类 |
+| `stEntityInfo` | 实体数据结构 |
+
+---
+
+## System-Model 架构
+
+`HFAbsEntity` 内部维护两个集合：
+
+```text
+m_Models  : IModel[]  // 数据层
+m_Systems : ISystem[] // 表现层/逻辑层
+```
+
+按 `enSystemType` 关联 `IModel` 和 `ISystem`。
+
+添加系统：
+
+```csharp
+AddSystem<T>()
+  -> HFClassEntityManager.Instance.GetClassEntity<T>()  // 创建或复用系统对象
+  -> 生成对应 IModel
+  -> model.Init(this, system.Init)  // 建立实体、模型、系统关系
+```
+
+更新顺序：
+
+```text
+OnSystemUpdate()  // 表现层更新
+OnModelUpdate()   // 数据层更新
+```
+
+---
+
+## 实体池机制
+
+`HFEntityPool` 按 `enEntityLayer` 注册不同的 `AbsHFEntityPool` 实现。
+
+创建实体：
+
+```text
+AbsHFEntityPool.OnCreateEnity<T>()
+  -> 创建 GameObject 根节点
+  -> 维护 onlyid -> entity 索引
+  -> 维护 EntityId -> onlyid 索引
+```
+
+查询实体：
+
+```text
+HFEntityPool.SelectByOnlyid(onlyid)
+  -> 通过 onlyid -> enEntityLayer 找到对应池
+  -> 从具体池取实体
+```
+
+回收实体：
+
+```text
+DelEntityByOnlyid(onlyid)
+  -> 从池索引移除
+  -> 调用 entity.Recycle()
+```
+
+---
+
+## 子系统
+
+实体相关的子系统通常位于：
+
+- `Models/AI`、`Systems/AI` — AI
+- `Models/Animation`、`Systems/Animation` — 动画
+- `Models/Feature`、`Systems/Feature` — 特性/属性
+- `Models/Move`、`Systems/Move` — 移动
+- `Models/Skill`、`Systems/Skill` — 技能
+- `HFSkillTrigger_*` — 技能触发器
+- `HFSkill_*_Releaser` — 技能释放器
+- `GameEntity/RVO/RVOManager.cs` — RVO 避障
+
+---
+
+## 使用规则
+
+- 新实体类型应继承 `HFAbsEntity`。
+- 实体对象统一通过 `HFEntityPool` 创建和回收。
+- 系统通过 `AddSystem<T>()` 添加，避免直接 new。
+- 子系统数据更新放在 `OnModelUpdate()`，表现更新放在 `OnSystemUpdate()`。
+
+---
+
+## 相关模块
+
+- [技能系统](../技能系统/README.md)
+- [对象池](../内存对象管理/README.md)
+- [数据/配置框架](../数据配置框架.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/技能系统/README.md](../技能系统/README.md) | 技能系统是实体系统的子系统 |
+| [modules/frameworks/内存对象管理/README.md](../内存对象管理/README.md) | 实体池与对象池机制相关 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/实体系统/开发指南.md
+++ b/modules/frameworks/实体系统/开发指南.md
@@ -1,12 +1,12 @@
-# StrayFog 框架 Entity开发指南
+# Entity 开发指南

-## 一、Entity概述
+## 一、Entity 概述

-Entity是游戏世界中所有游戏对象的抽象基类，包括玩家、敌人、塔楼、城堡等。Entity系统提供统一的对象管理、生命周期控制和**System-Model架构**。
+Entity 是游戏世界中所有游戏对象的抽象基类，包括玩家、敌人、塔楼、城堡等。Entity 系统提供统一的对象管理、生命周期控制和 **System-Model 架构**。

-### 1.1 Entity分类
+### 1.1 Entity 分类

-Entity分类根据具体业务需求定义，以下为示例分类（项目实际分类以业务为准）：
+Entity 分类根据具体业务需求定义，以下为示例分类（项目实际分类以业务为准）：

 | 类别 | 说明 | 示例 |
 |-----|------|------|
@@ -15,22 +15,22 @@ Entity分类根据具体业务需求定义，以下为示例分类（项目实
 | **Castle** | 城堡/基地实体 | 玩家基地 |
 | **Obstacle** | 障碍物实体 | 墙壁、陷阱 |

-> **说明**：实际项目中需根据业务需求定义Entity类型，继承`HFAbsEntity`基类并实现对应逻辑。
+> **说明**：实际项目中需根据业务需求定义 Entity 类型，继承 `HFAbsEntity` 基类并实现对应逻辑。

 ### 1.2 核心数据结构

 ```csharp
-// Entity唯一标识
+// Entity 唯一标识
 public long onlyid { get; }      // 运行时唯一ID
 public int EntityId { get; }     // 资源配置ID
-public enEntityLayer entityType { get; }  // Entity类型
+public enEntityLayer entityType { get; }  // Entity 类型
 public enEntityCamp entityCamp { get; }   // 阵营
 public bool isDeath { get; }     // 是否死亡
 ```

 ---

-## 二、Entity创建规范
+## 二、Entity 创建规范

 ### 2.1 继承结构

@@ -53,11 +53,11 @@ public abstract partial class HFAbsEntity : AbsHFSimulateBehaviour
    public virtual void OnDeath() { ... } // 子类重写处理表现死亡逻辑
    
    // 逻辑死亡（数据层）
-    protected void Logic_Death() { ... }        // 设置isDeath=true，数据层死亡
+    protected void Logic_Death() { ... }        // 设置 isDeath=true，数据层死亡
    protected virtual void OnLogicDeath() { ... } // 子类重写处理逻辑死亡逻辑
 }

-// 具体Entity示例 - Human类型
+// 具体 Entity 示例 - Human 类型
 public class HFEntity_Human : HFAbsEntity
 {
    protected override void OnRunAwake()
@@ -85,36 +85,36 @@ public class HFEntity_Human : HFAbsEntity

 | 类型 | 命名规则 | 示例 |
 |-----|---------|------|
-| Entity类 | `HFEntity_{TypeName}` | `HFEntity_Human`、`HFEntity_Tower` |
+| Entity 类 | `HFEntity_{TypeName}` | `HFEntity_Human`、`HFEntity_Tower` |
 | 系统类 | `HF{SystemName}System[_TypeName]` | `HFAnimationSystem_Human` |
 | 模型类 | `HF{ModelName}Model[_TypeName]` | `HFAnimationModel_Human` |
 | 数据结构 | `st{DataName}` | `stAbilityData`、`stDamageInfo` |

 ---

-## 三、Entity生命周期
+## 三、Entity 生命周期

 ### 3.1 生命周期方法

 | 方法 | 调用时机 | 职责 | 层级 |
 |-----|---------|------|-----|
-| `OnRunAwake()` | 对象创建时 | 添加System组件 | 表现层 |
-| `Init()` | 初始化时调用 | 重置死亡状态、调用OnInit | - |
-| `OnInit()` | Init内部调用 | 子类重写，初始化配置数据 | 数据层 |
-| `Logic_Death()` | HP归零时调用 | 设置`isDeath=true`，调用OnLogicDeath | 数据层 |
-| `OnLogicDeath()` | Logic_Death内部调用 | 子类重写处理逻辑死亡逻辑 | 数据层 |
-| `Death()` | 逻辑死亡后调用 | 触发死亡事件、调用OnDeath | 表现层 |
-| `OnDeath()` | Death内部调用 | 子类重写，处理表现死亡逻辑（动画、特效等） | 表现层 |
+| `OnRunAwake()` | 对象创建时 | 添加 System 组件 | 表现层 |
+| `Init()` | 初始化时调用 | 重置死亡状态、调用 OnInit | - |
+| `OnInit()` | Init 内部调用 | 子类重写，初始化配置数据 | 数据层 |
+| `Logic_Death()` | HP 归零时调用 | 设置 `isDeath=true`，调用 OnLogicDeath | 数据层 |
+| `OnLogicDeath()` | Logic_Death 内部调用 | 子类重写处理逻辑死亡逻辑 | 数据层 |
+| `Death()` | 逻辑死亡后调用 | 触发死亡事件、调用 OnDeath | 表现层 |
+| `OnDeath()` | Death 内部调用 | 子类重写，处理表现死亡逻辑（动画、特效等） | 表现层 |
 | `OnRecycle()` | 对象回收时 | 清理资源、释放引用 | - |

 > **重要区分**：
-> - **逻辑死亡**：`Logic_Death()` 由伤害计算触发，设置`isDeath=true`，仅影响数据层
+> - **逻辑死亡**：`Logic_Death()` 由伤害计算触发，设置 `isDeath=true`，仅影响数据层
 > - **表现死亡**：`Death()` 在逻辑死亡后调用，触发死亡事件和表现效果（动画、音效等）

 ### 3.2 创建流程

 ```csharp
-// 1. 对象池创建Entity
+// 1. 对象池创建 Entity
 HFEntityPool.Instance.CreateEntity<HFEntity_Human>(onlyid, entityId, 
    () => HFClassEntityManager.Instance.GetClassEntity<HFEntity_Human>(),
    (entity) => {
@@ -127,14 +127,14 @@ HFEntityPool.Instance.CreateEntity<HFEntity_Human>(onlyid, entityId,

 ---

-## 四、System-Model架构
+## 四、System-Model 架构

 ### 4.1 架构设计

-Entity采用**System-Model分离架构**：
+Entity 采用 **System-Model 分离架构**：

- **System层**：处理表现逻辑（Update、状态转换）
- **Model层**：处理数据逻辑（数据存储、计算）
+- **System 层**：处理表现逻辑（Update、状态转换）
+- **Model 层**：处理数据逻辑（数据存储、计算）

 ### 4.2 添加系统

@@ -156,21 +156,21 @@ public class HFEntity_Human : HFAbsEntity

 ### 4.3 常用系统

-| 系统 | 职责 | 适用Entity |
+| 系统 | 职责 | 适用 Entity |
 |-----|------|-----------|
-| `HFFeatureSystem` | 属性管理 | 所有Entity |
+| `HFFeatureSystem` | 属性管理 | 所有 Entity |
 | `HFAnimationSystem` | 动画控制 | Human、Tower |
 | `HFMoveSystem` | 移动控制 | Human |
-| `HFAISystem` | AI行为 | Enemy、Tower |
+| `HFAISystem` | AI 行为 | Enemy、Tower |
 | `HFSkillSystem` | 技能系统 | Human、Tower |

-### 4.4 获取Model
+### 4.4 获取 Model

 ```csharp
-// 通过System类型获取Model
+// 通过 System 类型获取 Model
 HFAnimationModel_Human animModel = GetModel<HFAnimationModel_Human>();

-// 通过System对象获取Model
+// 通过 System 对象获取 Model
 HFSkillSystem skillSystem = ...;
 HFSkillModel skillModel = GetModel<HFSkillModel>(skillSystem);
 ```
@@ -184,7 +184,7 @@ HFSkillModel skillModel = GetModel<HFSkillModel>(skillSystem);
 | 属性类型 | 说明 | 示例 |
 |---------|------|------|
 | **基础属性** | 配置表读取，基础值 | HP、SPD、MoveSpeed |
-| **战斗属性** | 实际战斗中使用，受Buff影响 | Fight_SPD、Fight_ATK |
+| **战斗属性** | 实际战斗中使用，受 Buff 影响 | Fight_SPD、Fight_ATK |

 ### 5.2 属性数据结构

@@ -228,20 +228,20 @@ public void ChangeData(stAbilityData data)
    }
    else
    {
-        // 临时属性变更（存入Buff字典）
+        // 临时属性变更（存入 Buff 字典）
        OnAddEntityAbilityData(data);
    }
    
    // 刷新战斗属性
    OnRefushEntityAbility(data.ChangeTarget);
-    // 通知所有Model属性变更
+    // 通知所有 Model 属性变更
    ChangeAbility(data.ChangeTarget);
 }
 ```

 ---

-## 六、Entity对象池
+## 六、Entity 对象池

 ### 6.1 对象池职责

@@ -250,16 +250,16 @@ public abstract partial class AbsHFEntityPool : IHFObject
 {
    public abstract enEntityLayer entityType { get; }
    
-    // 根据onlyid获取Entity
+    // 根据 onlyid 获取 Entity
    public virtual HFAbsEntity SelectByOnlyid(long onlyid) { ... }
    
-    // 根据资源ID获取所有Entity
+    // 根据资源 ID 获取所有 Entity
    public List<HFAbsEntity> SelectByResId(int resid) { ... }
    
-    // 删除Entity
+    // 删除 Entity
    public virtual bool DelEntityByOnlyid(long onlyid) { ... }
    
-    // 获取所有Entity
+    // 获取所有 Entity
    public List<HFAbsEntity> GetAllEntities() { ... }
 }
 ```
@@ -267,7 +267,7 @@ public abstract partial class AbsHFEntityPool : IHFObject
 ### 6.2 使用示例

 ```csharp
-// 创建Entity
+// 创建 Entity
 HFEntityPool.Instance.CreateEntity<HFEntity_Human>(
    onlyid: 1001,
    entityId: 10001,
@@ -277,11 +277,11 @@ HFEntityPool.Instance.CreateEntity<HFEntity_Human>(
        entity.Init();
    });

-// 获取Entity
+// 获取 Entity
 HFAbsEntity entity = HFEntityPool.Instance.SelectByOnlyid(1001);
 HFEntity_Human human = entity as HFEntity_Human;

-// 删除Entity
+// 删除 Entity
 HFEntityPool.Instance.DelEntityByOnlyid(1001);
 ```

@@ -293,8 +293,8 @@ HFEntityPool.Instance.DelEntityByOnlyid(1001);

 | 类型 | 路径 |
 |-----|------|
-| Entity基类 | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Core/BaseEntity/AbsEntity/` |
-| 具体Entity | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Entity/EntityTag/` |
+| Entity 基类 | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Core/BaseEntity/AbsEntity/` |
+| 具体 Entity | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Entity/EntityTag/` |
 | 系统类 | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Entity/System/` |
 | 模型类 | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Entity/Model/` |
 | 对象池 | `Assets/Game/GameHFScripte/GameFunction/GameEntity/Core/BaseEntity/EntityPool/` |
@@ -302,21 +302,38 @@ HFEntityPool.Instance.DelEntityByOnlyid(1001);
 ### 7.2 编码规范

 1. **必须继承** `HFAbsEntity` 基类
-2. **必须在** `OnRunAwake()` 中添加所需System
+2. **必须在** `OnRunAwake()` 中添加所需 System
 3. **必须重写** `OnInit()` 初始化配置数据
 4. **必须重写** `OnDeath()` 处理死亡逻辑
-5. **禁止**在Entity中直接访问Manager，通过`HFFunCatalogue`访问
-6. **禁止**在Entity中持有场景引用
+5. **禁止** 在 Entity 中直接访问 Manager，通过 `HFFunCatalogue` 访问
+6. **禁止** 在 Entity 中持有场景引用

 ### 7.3 性能优化

- 使用对象池复用Entity实例
+- 使用对象池复用 Entity 实例
 - 使用 `AddSystem<T>()` 延迟初始化系统
- 属性变更通过 `ChangeAbility()` 通知所有Model
- 死亡Entity通过 `OnDeathFinish()` 回调回收
+- 属性变更通过 `ChangeAbility()` 通知所有 Model
+- 死亡 Entity 通过 `OnDeathFinish()` 回调回收

 ---

 **版本**: v1.1  
 **生效日期**: 2026年  
-**适用范围**: StrayFog框架开发人员
+**适用范围**: StrayFog 框架开发人员
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [实体系统入口](README.md) | 本文件是实体系统模块的子文档 |
+| [通用技能系统使用指南](../技能系统/使用指南.md) | 技能系统是 Entity 常用子系统 |
+| [对象池与运行时对象管理](../内存对象管理/README.md) | Entity 池机制相关 |
+| [事件系统](../事件系统/README.md) | Entity 间通信常依赖事件系统 |
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 编码规范与开发规则互相引用 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/03_核心功能/Entity/UnityEntities注意事项.md
+++ b/03_核心功能/Entity/UnityEntities注意事项.md
@@ -4,19 +4,19 @@

 ### enHFCTCEvent 枚举
 - **新增项**：`Custom = 281` - 用于自定义事件
- **用途**：在HFEvent_OnDamage等自定义事件中使用
+- **用途**：在 `HFEvent_OnDamage` 等自定义事件中使用
 - **注意**：添加新事件时，确保数值不与其他事件冲突

 ### enEntityLayer 枚举
 - **现有项**：`None=0`, `Role`, `Monster`, `Max`
- **注意**：没有`Enemy`项，敌人应归类为`Monster`
+- **注意**：没有 `Enemy` 项，敌人应归类为 `Monster`

 ## 2. 实体-系统-模型 (ESM) 架构相关

 ### HFAbsEntity 访问方式
- **Transform访问**：使用 `entity.gameObject.transform.position` 而不是 `entity.transform.position`
+- **Transform 访问**：使用 `entity.gameObject.transform.position` 而不是 `entity.transform.position`
 - **属性访问**：使用公共属性如 `entity.NormalATK` 而不是私有字段 `entity.m_NormalATK`
- **系统获取**：HFAbsEntity 没有 `GetSystem<T>()` 方法，只有 `GetModel<T>()` 方法
+- **系统获取**：`HFAbsEntity` 没有 `GetSystem<T>()` 方法，只有 `GetModel<T>()` 方法
 - **模型获取**：通过 `entity.GetModel<T>()` 获取模型实例

 ### 系统间通信
@@ -25,23 +25,23 @@

 ## 3. 数据表字段映射

-### Role表字段
+### Role 表字段
 - `Lifefold` -> 生命值
 - `Attackfold` -> 攻击力  
 - `Defensefold` -> 防御力
 - `AttackRange` -> 攻击范围
 - `CriticalRate` -> 暴击率
 - `CriticalDamage` -> 暴击伤害
- **注意**：Role表中没有速度字段 (SPD)
+- **注意**：Role 表中没有速度字段 (SPD)

 ## 4. 动画系统相关

 ### FSM (有限状态机) 系统
 - **HFFMSModel** 现在包含 `CurrentSkeletonAnimation` 属性
- **访问方式**：通过 `FSM.CurrentSkeletonAnimation` 访问SkeletonAnimation
+- **访问方式**：通过 `FSM.CurrentSkeletonAnimation` 访问 SkeletonAnimation
 - **动画速度设置**：使用 `skeletonAnimation.timeScale = speed`

-## 5. AI系统相关
+## 5. AI 系统相关

 ### HFAIModel_Enemy
 - **伤害处理**：通过事件系统 (`HFEvent_OnDamage`) 而不是直接获取系统
@@ -52,12 +52,12 @@
 ### 常见错误类型
 - **CS0117**: 枚举中不包含指定定义 - 检查枚举项是否存在
 - **CS1061**: 类型不包含指定定义 - 检查属性/方法名是否正确
- **CS0122**: 成员因保护级别不可访问 - 使用公共API而不是私有字段
+- **CS0122**: 成员因保护级别不可访问 - 使用公共 API 而不是私有字段

 ### 修复策略
 - 优先使用公共属性而不是私有字段
 - 通过事件系统进行组件间通信
- 正确访问GameObject的Transform组件
+- 正确访问 GameObject 的 Transform 组件
 - 使用正确的枚举值

 ## 7. 架构模式
@@ -65,9 +65,25 @@
 ### 系统-模型 (System-Model) 模式
 - **AbsHFMoveSystem<T>** 需要指定泛型参数
 - **AbsHFAIModel** 不能直接获取系统，应通过事件或模型进行通信
- **AbsHFAnimationModel** 需要配合AbsHFFMSModel使用
+- **AbsHFAnimationModel** 需要配合 `AbsHFFMSModel` 使用

 ### 事件驱动架构
 - 自定义事件需继承 `AbsHFEventArg<enHFCTCEvent>`
- 事件ID使用 `enHFCTCEvent.Custom` 或其他预定义事件
- 事件分发使用 `Dispatch()` 方法
+- 事件 ID 使用 `enHFCTCEvent.Custom` 或其他预定义事件
+- 事件分发使用 `Dispatch()` 方法
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [实体系统入口](README.md) | 本文件是实体系统模块的子文档 |
+| [Entity 开发指南](开发指南.md) | 与开发指南中的 System-Model、属性系统互补 |
+| [事件系统](../事件系统/README.md) | 自定义事件派发相关 |
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 公共 API 访问方式与开发规则互相引用 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/技能系统/README.md
+++ b/modules/frameworks/技能系统/README.md
@@ -0,0 +1,134 @@
+# 技能系统
+
+## 分类
+
+- 核心框架
+
+## 目的
+
+为角色、怪物等实体提供统一的技能管理、冷却控制、释放接口和事件通知。
+
+---
+
+## 核心组成
+
+| 类/结构 | 职责 |
+|---------|------|
+| `HFGenericSkillSystem` | 通用技能系统，继承 `AbsHFSkillSystem<HFGenericSkillModel>` |
+| `HFGenericSkillModel` | 通用技能模型，继承 `HFAbsModel` |
+| `HFEvent_OnSkillUsed` | 技能使用事件 |
+| `stSkillConfig` | 技能配置结构 |
+
+---
+
+## 技能管理
+
+```csharp
+// 添加技能
+skillSystem.AddSkill(skillId);
+
+// 移除技能
+skillSystem.RemoveSkill(skillId);
+
+// 检查技能是否就绪
+bool isReady = skillSystem.IsSkillReady(skillId);
+
+// 获取技能冷却时间
+float cooldown = skillSystem.GetSkillCooldown(skillId);
+
+// 是否有技能在冷却
+bool hasCooldown = skillSystem.HasSkillInCooldown();
+
+// 清除所有冷却
+skillSystem.ClearAllCooldowns();
+```
+
+---
+
+## 技能使用
+
+```csharp
+// 对目标使用技能
+skillSystem.UseSkill(skillId, targetEntity);
+
+// 对位置使用技能
+skillSystem.UseSkillAtPosition(skillId, worldPosition);
+```
+
+触发事件：
+
+```csharp
+public class HFEvent_OnSkillUsed : AbsHFEventArg<enHFCTCEvent>
+{
+    public HFAbsEntity Caster { get; set; }
+    public int SkillId { get; set; }
+    public HFAbsEntity Target { get; set; }
+    public Vector3 Position { get; set; }
+}
+```
+
+---
+
+## 自动配置加载
+
+系统会根据实体配置自动加载技能：
+
+```csharp
+var config = HFFunCatalogue.NDB.ds_EntityConfig_Sheet_TableData_1FC4334A.ReadTable(ownerEntity.EntityId);
+if (config != null && config.SkillID > 0)
+{
+    AddSkill(config.SkillID);
+}
+```
+
+---
+
+## 实体中的添加方式
+
+在角色或敌人实体中统一添加：
+
+```csharp
+AddSystem<HFGenericSkillSystem>();
+```
+
+---
+
+## 子系统边界
+
+从实体系统角度看，技能相关子目录通常包括：
+
+- `Models/Skill` — 技能数据模型
+- `Systems/Skill` — 技能系统逻辑
+- `HFSkillTrigger_*` — 技能触发器
+- `HFSkill_*_Releaser` — 技能释放器
+
+---
+
+## 使用规则
+
+- 角色和怪物使用同一套技能系统接口。
+- 技能 ID 在项目中应保持唯一。
+- 技能效果逻辑应在事件处理器中实现，避免直接写在释放器里。
+- 合理设置冷却时间以平衡游戏体验。
+
+---
+
+## 相关模块
+
+- [实体系统](../实体系统/README.md)
+- [事件系统](../事件系统/README.md)
+- [数据/配置框架](../数据配置框架.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/实体系统/README.md](../实体系统/README.md) | 技能系统是实体系统的子系统 |
+| [modules/frameworks/事件系统/README.md](../事件系统/README.md) | 技能使用事件依赖事件系统 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/03_核心功能/Entity/通用技能系统使用指南.md
+++ b/03_核心功能/Entity/通用技能系统使用指南.md
@@ -2,13 +2,13 @@

 ## 概述

-通用技能系统（HFGenericSkillSystem）是一个适用于角色和怪物的统一技能管理系统，提供了一套标准化的技能操作接口。
+通用技能系统（`HFGenericSkillSystem`）是一个适用于角色和怪物的统一技能管理系统，提供了一套标准化的技能操作接口。

 ## 架构设计

 ### 系统组成
- **HFGenericSkillSystem** - 通用技能系统（继承自 AbsHFSkillSystem<HFGenericSkillModel>）
- **HFGenericSkillModel** - 通用技能模型（继承自 HFAbsModel）
+- **HFGenericSkillSystem** - 通用技能系统（继承自 `AbsHFSkillSystem<HFGenericSkillModel>`）
+- **HFGenericSkillModel** - 通用技能模型（继承自 `HFAbsModel`）
 - **HFEvent_OnSkillUsed** - 技能使用事件

 ### 核心功能
@@ -78,7 +78,7 @@ public struct stSkillConfig
 ### 技能加载
 系统会根据实体配置自动加载对应的技能：
 ```csharp
-// 从EntityConfig表加载技能
+// 从 EntityConfig 表加载技能
 var config = HFFunCatalogue.NDB.ds_EntityConfig_Sheet_TableData_1FC4334A.ReadTable(ownerEntity.EntityId);
 if (config != null && config.SkillID > 0)
 {
@@ -102,12 +102,12 @@ public class HFEvent_OnSkillUsed : AbsHFEventArg<enHFCTCEvent>

 ## 扩展接口

-### Buff管理
+### Buff 管理
 ```csharp
-// 添加Buff
+// 添加 Buff
 skillSystem.AddBuff(buffTemplate);

-// 移除Buff
+// 移除 Buff
 skillSystem.RemoveBuff(buffId);
 ```

@@ -123,5 +123,21 @@ skillSystem.RemoveBuff(buffId);

 1. 技能释放器的具体实现需要根据游戏需求进行定制
 2. 技能效果逻辑应在事件处理器中实现
-3. 确保技能ID在项目中唯一
-4. 合理设置技能冷却时间以平衡游戏体验
+3. 确保技能 ID 在项目中唯一
+4. 合理设置技能冷却时间以平衡游戏体验
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [技能系统入口](README.md) | 本文件是技能系统模块的子文档 |
+| [实体系统](../实体系统/README.md) | 技能系统是实体系统的子系统 |
+| [事件系统](../事件系统/README.md) | 技能使用事件依赖事件系统 |
+| [数据/配置框架](../数据配置框架.md) | 技能配置加载依赖配置框架 |
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/数据配置框架.md
+++ b/modules/frameworks/数据配置框架.md
@@ -0,0 +1,111 @@
+# 数据 / 配置框架
+
+## 分类
+
+- 核心框架
+
+## 目的
+
+管理 XLSX 配置表源、解析、生成运行时数据和读取 API。
+
+---
+
+## 核心路径
+
+- 配置源：`XLSX_SRC/CN/`、`XLSX_SRC/EN/`
+- 生成设置：`ProjectSettings/ZYF/ZYXlsx/ZYXlsxProjectSettings.asset`
+- Resolve Asset：`Assets/Editor/XLSX_SRC/Resolve/ZYXlsx/`
+- 输出数据：`Assets/AutoBuildAsset/{Editor,Hotfix}/AutoFrame/Google.Protobuf/XLSX_SRC/<语言>/`
+- 输出代码：`Assets/AutoBuildScript/{Editor,General,Hotfix}/AutoFrame/Google.Protobuf/XLSX_Script/`
+
+---
+
+## 常见配置表
+
+| 表名 | 用途 |
+|---|---|
+| `Constants.xlsx` | 常量配置 |
+| `EntityConfig.xlsx` | 实体配置 |
+| `Gift.xlsx` | 礼包/奖励配置 |
+| `Resource.xlsx` | 资源/道具配置 |
+| `SkillGroup.xlsx` | 技能组配置 |
+| `SkillReleaser.xlsx` | 技能释放器配置 |
+| `SkillTrigger.xlsx` | 技能触发器配置 |
+| `SkillUp.xlsx` | 技能升级配置 |
+| `Sounds.xlsx` | 音效配置 |
+| `Wave.xlsx` | 波次配置（业务示例） |
+
+---
+
+## 运行时加载调用链
+
+```text
+HFGameStart.LoadDB()
+  -> Hotfix_ZYXlsx_GoogleProtobuf_Helper.instance.LoadAllXlsx(OnLoadDbFinish)
+  -> 遍历 enZYXlsxSheet
+  -> GetExistsDataLang / GetSheetMemoryPackBufferFilePath
+  -> HFFunCatalogue.Asset.LoadDBHelper(path.GetHashCode(), path, callback)
+  -> 缓存 sheet bytes 到 mDicLangSheetBytes
+```
+
+---
+
+## 运行时读取 API
+
+```csharp
+// 按主键读取单条
+HFFunCatalogue.NDB.ds_xxx.ReadTableByPK(pk);
+
+// 读取全表
+HFFunCatalogue.NDB.ds_xxx.ReadTableList();
+
+// 读取行列式数据
+HFFunCatalogue.NDB.ds_xxx.ReadTableDeterminant();
+```
+
+---
+
+## 使用规则
+
+- 改表后必须重新生成。
+- 配置读取必须在 `LoadAllXlsx` 完成后。
+- 主键/全表/常量分别用对应 API。
+- 禁止高频全表读取。
+- id 优先来自表/协议/常量，禁止魔法数字。
+- 高频配置在 manager 初始化或窗口打开时缓存。
+- 多语言字段需补齐。
+
+---
+
+## 变更清单
+
+1. 修改源表。
+2. 确认 settings / resolve 配置。
+3. 重新生成。
+4. 检查输出。
+5. 编译验证。
+6. 运行时验证。
+7. 更新文档。
+
+---
+
+## 相关模块
+
+- [实体系统](实体系统/README.md)
+- [技能系统](技能系统/README.md)
+- [资源管理](资源管理/README.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/实体系统/README.md](实体系统/README.md) | 实体配置来自配置表 |
+| [modules/frameworks/技能系统/README.md](技能系统/README.md) | 技能配置来自配置表 |
+| [modules/frameworks/资源管理/README.md](资源管理/README.md) | 配置资源加载依赖资源管理 |
+| [rules/10-架构说明.md](../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/相机系统/README.md
+++ b/modules/frameworks/相机系统/README.md
@@ -0,0 +1,122 @@
+# 相机系统
+
+## 分类
+
+- 核心框架
+
+## 目的
+
+管理多相机注册、相机堆栈排序、渲染顺序控制，为 UI、场景、特效等提供分层渲染能力。
+
+---
+
+## 核心类
+
+| 类 | 职责 |
+|---|---|
+| `HFCameraManager` | 相机管理器单例，维护相机列表和主相机引用 |
+| `HFMainCamera` | 主相机，管理 CameraStack |
+| `AbsHFCameraItem` | 相机项抽象基类，子类实现具体相机逻辑 |
+
+---
+
+## 创建自定义相机
+
+继承 `AbsHFCameraItem`，实现 `CameraItem` 和 `Weight` 属性：
+
+```csharp
+public class UIOverlayCamera : AbsHFCameraItem
+{
+    [SerializeField] private Camera uiCamera;
+    [SerializeField] private int weight = 10;
+    
+    public override Camera CameraItem => uiCamera;
+    public override int Weight => weight;
+    
+    protected override void OnInitialize()
+    {
+        base.OnInitialize();
+        uiCamera.clearFlags = CameraClearFlags.Depth;
+        uiCamera.depth = 100;
+    }
+}
+```
+
+---
+
+## 相机堆栈架构
+
+```text
+HFMainCamera (主相机)
+    │
+    ├── CameraStack (相机堆栈)
+    │       ├── CameraItem1 (Weight=10)
+    │       ├── CameraItem2 (Weight=20)
+    │       └── CameraItem3 (Weight=5)
+    │
+    └── 按 Weight 排序 → 渲染顺序控制
+```
+
+---
+
+## 管理相机
+
+```csharp
+public class CameraController : MonoBehaviour
+{
+    void Start()
+    {
+        HFCameraManager cameraMgr = HFCameraManager.Instance;
+        
+        UIOverlayCamera uiCamera = GetComponent<UIOverlayCamera>();
+        cameraMgr.AddCamera(uiCamera);
+        
+        Camera mainCam = cameraMgr.mainCamera.MainCamera;
+    }
+    
+    void OnDestroy()
+    {
+        UIOverlayCamera uiCamera = GetComponent<UIOverlayCamera>();
+        HFCameraManager.Instance.RemoveCamera(uiCamera);
+    }
+}
+```
+
+---
+
+## 常用 API
+
+| 方法 | 说明 |
+|-----|------|
+| `AddCamera(AbsHFCameraItem)` | 添加相机到堆栈 |
+| `RemoveCamera(AbsHFCameraItem)` | 从堆栈移除相机 |
+| `GetCamera(string cameraName)` | 获取指定名称相机 |
+
+---
+
+## 使用规则
+
+- 相机项必须继承 `AbsHFCameraItem`。
+- `Weight` 决定堆栈内渲染顺序，值越大越靠后渲染。
+- 添加和移除相机需成对出现，避免残留。
+- UI 相机通常使用 `CameraClearFlags.Depth` 和较高 depth。
+
+---
+
+## 相关模块
+
+- [UI 窗口系统](../UI窗口系统/README.md)
+- [资源管理](../资源管理/README.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/UI窗口系统/README.md](../UI窗口系统/README.md) | UI 窗口系统常与相机系统协作 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/相机系统/使用指南.md
+++ b/modules/frameworks/相机系统/使用指南.md
@@ -1,8 +1,8 @@
-# StrayFog 框架相机系统使用指南
+# 相机系统使用指南

 ## 一、创建自定义相机

-### 1.1 继承AbsHFCameraItem
+### 1.1 继承 AbsHFCameraItem

 ```csharp
 public class UIOverlayCamera : AbsHFCameraItem
@@ -64,12 +64,12 @@ HFMainCamera (主相机)
    │       ├── CameraItem2 (Weight=20)
    │       └── CameraItem3 (Weight=5)
    │
-    └── 按Weight排序 → 渲染顺序控制
+    └── 按 Weight 排序 → 渲染顺序控制
 ```

 ---

-## 三、相机管理API
+## 三、相机管理 API

 ### 3.1 常用方法

@@ -83,4 +83,19 @@ HFMainCamera (主相机)

 **版本**: v1.0  
 **生效日期**: 2026年  
-**适用范围**: GiftGameX项目业务开发人员
+**适用范围**: GiftGameX 项目业务开发人员
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [相机系统入口](README.md) | 本文件是相机系统模块的子文档 |
+| [UI 窗口系统](../UI窗口系统/README.md) | UI 窗口系统常与相机系统协作 |
+| [资源管理](../资源管理/README.md) | 相机资源加载依赖资源管理 |
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/第三方插件.md
+++ b/modules/frameworks/第三方插件.md
@@ -0,0 +1,49 @@
+# 第三方插件
+
+## 分类
+
+- 项目框架
+
+## 目的
+
+记录第三方插件和 embedded packages 的用途、边界和修改规则。
+
+## 已知线索
+
+- 插件目录：`Assets/ThirdPlugins/`
+- Package 目录：`Packages/`
+- 已识别插件包括 HybridCLR、Spine、DOTween、SuperScrollView、Astar、UnityWebSocket、SoundManagerPro、SRDebugger 等。
+
+## 梳理任务
+
+- [ ] 梳理主要插件列表和用途。
+- [ ] 标记哪些插件是运行时依赖，哪些是编辑器依赖。
+- [ ] 梳理插件是否有项目本地修改。
+- [ ] 梳理升级插件的风险和验证步骤。
+- [ ] 记录禁止直接修改 vendor 的规则例外。
+
+## 待确认
+
+- 哪些插件来自 Asset Store，哪些来自 package。
+- 是否有插件被项目深度改造。
+- 哪些插件参与 hotfix 或 WebGL 构建。
+
+## 相关模块
+
+- [通用框架](通用框架/README.md)
+- [编辑器工具索引](../模块索引.md#编辑器工具)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../模块索引.md) | 编辑器工具索引 |
+| [modules/frameworks/通用框架/README.md](通用框架/README.md) | 通用框架 |
+| [rules/10-架构说明.md](../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/20-开发规则.md](../../rules/20-开发规则.md) | 开发规则与框架/生成规则互相引用 |
+| [rules/30-模块登记规则.md](../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖或使用本框架的模块文档 | 如依赖本框架的功能模块 |
--- a/modules/frameworks/编辑器工具/README.md
+++ b/modules/frameworks/编辑器工具/README.md
@@ -0,0 +1,54 @@
+# 编辑器工具
+
+## 分类
+
+- 编辑器工具
+
+## 目的
+
+汇总 Unity Editor 内使用的 StrayFog 相关编辑器扩展和项目编辑器资源。
+
+---
+
+## SF Editor
+
+- **路径**：`Assets/StrayFog/Editor/`
+- **程序集**：`SFEditor`
+- **职责**：
+  - StrayFog 编辑器扩展
+  - 打包、UGUI、SpriteAtlas、表格路径选择等编辑器工具
+
+---
+
+## Project Editor Assets
+
+- **路径**：`Assets/Editor/`
+- **职责**：
+  - 项目编辑器资源与脚本
+  - 引导菜单、编辑器插件
+
+---
+
+## 使用规则
+
+- 编辑器工具可以读取/生成核心运行时代码，但运行时代码不要反向依赖 Editor 程序集。
+- 新增 Editor 工具时，优先在 `Assets/StrayFog/Editor/` 或 `Assets/Editor/` 下按功能分类存放。
+
+---
+
+## 相关模块
+
+- [通用框架](../通用框架/README.md)
+- [资源管理](../资源管理/README.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 编辑器工具层的架构说明 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/编辑器工具/UI工具/ExternalCommandListener.cs
+++ b/modules/frameworks/编辑器工具/UI工具/ExternalCommandListener.cs
--- a/modules/frameworks/编辑器工具/UI工具/ExternalCommandListener.cs.meta
+++ b/modules/frameworks/编辑器工具/UI工具/ExternalCommandListener.cs.meta
--- a/modules/frameworks/编辑器工具/UI工具/RemoteCommand.cs
+++ b/modules/frameworks/编辑器工具/UI工具/RemoteCommand.cs
--- a/modules/frameworks/编辑器工具/UI工具/RemoteCommand.cs.meta
+++ b/modules/frameworks/编辑器工具/UI工具/RemoteCommand.cs.meta
--- a/modules/frameworks/编辑器工具/UI工具/UIPrefabGenerator.cs
+++ b/modules/frameworks/编辑器工具/UI工具/UIPrefabGenerator.cs
--- a/modules/frameworks/编辑器工具/UI工具/UIPrefabGenerator.cs.meta
+++ b/modules/frameworks/编辑器工具/UI工具/UIPrefabGenerator.cs.meta
--- a/modules/frameworks/编辑器工具/UI工具/UIPrefabToJson.cs
+++ b/modules/frameworks/编辑器工具/UI工具/UIPrefabToJson.cs
--- a/modules/frameworks/编辑器工具/UI工具/UIPrefabToJson.cs.meta
+++ b/modules/frameworks/编辑器工具/UI工具/UIPrefabToJson.cs.meta
--- a/modules/frameworks/编辑器工具/UI拼接工具.md
+++ b/modules/frameworks/编辑器工具/UI拼接工具.md
@@ -0,0 +1,248 @@
+# UI 拼接工具
+
+## 概述
+
+UI 拼接工具提供 JSON 配置与 Unity 预制体的双向转换，帮助 UI 相关人员通过 JSON 配置文件快速生成 UI 预制体，同时支持从现有预制体反向导出 JSON 用于版本控制或重新生成。
+
+## 核心组件
+
+| 组件 | 职责 | 文件路径 |
+|-----|------|---------|
+| **UIPrefabGenerator** | 解析 JSON 并生成 UI 预制体 | `Assets/Editor/Command/UIPrefabGenerator.cs` |
+| **UIPrefabToJson** | 从预制体反向导出 JSON | `Assets/Editor/Command/UIPrefabToJson.cs` |
+| **RemoteCommand** | 提供外部调用接口 | `Assets/Editor/Command/RemoteCommand.cs` |
+| **ExternalCommandListener** | 监听外部命令触发文件 | `Assets/Editor/Command/ExternalCommandListener.cs` |
+
+工具脚本在文档库中的位置（已并入编辑器工具模块）：
+
+```
+modules/frameworks/编辑器工具/UI工具/
+├── ExternalCommandListener.cs    # 外部命令监听器
+├── RemoteCommand.cs              # 远程命令接口
+├── UIPrefabGenerator.cs          # JSON 转预制体生成器
+└── UIPrefabToJson.cs             # 预制体转 JSON 导出器
+```
+
+## JSON 配置文件结构
+
+```json
+{
+  "name": "BagWindow",
+  "width": 1024,
+  "height": 768,
+  "elements": [
+    {
+      "type": "Image",
+      "name": "BgPanel",
+      "anchorMin": [0, 0],
+      "anchorMax": [1, 1],
+      "position": [0, 0, 0],
+      "sizeDelta": [0, 0],
+      "sprite": "Assets/Game/GameHFResource/CN/UIWindows/BagWindow/Sprites/Bg.png"
+    },
+    {
+      "type": "Text",
+      "name": "TitleText",
+      "anchorMin": [0.5, 0.9],
+      "anchorMax": [0.5, 0.9],
+      "position": [0, 0, 0],
+      "sizeDelta": [200, 40],
+      "text": "背包",
+      "font": "Assets/Game/GameHFResource/CN/Fonts/FZY4K-M05S SDF.asset",
+      "fontSize": 28,
+      "color": [1, 1, 1, 1]
+    }
+  ]
+}
+```
+
+## 支持的 UI 元素类型
+
+| 类型 | 对应 Unity 组件 | 关键属性 |
+|-----|-------------|---------|
+| **Image** | Image | sprite, color, type, preserveAspect |
+| **TextMeshProUGUI** | TextMeshProUGUI | text, font, fontSize, color, alignment |
+| **Button** | Button | interactable, transition, navigationMode |
+| **Slider** | Slider | minValue, maxValue, value, wholeNumbers, direction |
+| **Toggle** | Toggle | isOn, toggleTransition, transition |
+| **InputField** | InputField | text, placeholder, characterLimit, contentType |
+| **ScrollRect** | ScrollRect | horizontal, vertical, movementType |
+| **GridLayoutGroup** | GridLayoutGroup | cellSize, spacing, constraint, padding |
+| **VerticalLayoutGroup** | VerticalLayoutGroup | spacing, childAlignment, padding |
+| **HorizontalLayoutGroup** | HorizontalLayoutGroup | spacing, childAlignment, padding |
+
+## 外部命令触发机制
+
+### 触发方式
+
+通过创建/修改 `Trigger_Command.txt` 文件触发 UI 生成：
+
+```
+GenerateUIPrefab:Assets/Editor/UI/BagWindow.json
+```
+
+### 命令格式
+
+```
+<命令名>:<参数1>:<参数2>:...
+```
+
+**支持的命令**：
+
+| 命令 | 参数 | 说明 |
+|-----|------|------|
+| **GenerateUIPrefab** | `jsonPath` [, `prefabPath`] | 根据 JSON 生成 UI 预制体 |
+| **ExportPrefabToJson** | `prefabPath` [, `jsonPath`] | 从预制体反向导出 JSON |
+| **ReadJson** | [参数列表] | 读取 JSON 配置（测试用） |
+
+### 完整执行流程
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  外部系统写入命令到 Trigger_Command.txt                             │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  ExternalCommandListener (FileSystemWatcher) 检测到文件变化         │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  解析命令格式：GenerateUIPrefab:Assets/Editor/UI/BagWindow.json     │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  通过反射调用 RemoteCommand.GenerateUIPrefab(string[] args)         │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  UIPrefabGenerator.GeneratePrefabFromJson(jsonPath, prefabPath)    │
+└─────────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  生成预制体到指定路径：Assets/Game/GameHFResource/CN/UIWindows/...  │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## 使用示例
+
+### 方式一：外部命令触发
+
+```bash
+# 正向：从 JSON 生成预制体
+echo "GenerateUIPrefab:Assets/Editor/UI/BagWindow.json" > "F:\JMNet\CrystalBattle_Client\Trigger_Command.txt"
+
+# 反向：从预制体导出 JSON
+echo "ExportPrefabToJson:Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab" > "F:\JMNet\CrystalBattle_Client\Trigger_Command.txt"
+```
+
+### 方式二：Unity 编辑器菜单
+
+**正向生成**：
+1. 打开 Unity 编辑器
+2. 点击菜单 `Tools > External > Test GenerateUIPrefab`
+3. 查看 Console 窗口日志确认执行结果
+
+**反向导出**：
+1. 打开 Unity 编辑器
+2. 点击菜单 `Tools > UI > Export Prefab to JSON`
+3. 选择要导出的预制体文件
+
+### 方式三：代码调用
+
+```csharp
+// 正向：从 JSON 生成预制体
+UIPrefabGenerator.GeneratePrefabFromJson(
+    "Assets/Editor/UI/BagWindow.json",
+    "Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab"
+);
+
+// 反向：从预制体导出 JSON
+UIPrefabToJson.ExportPrefabToJson(
+    "Assets/Game/GameHFResource/CN/UIWindows/BagWindow/BagWindow.prefab",
+    "Assets/Editor/UI/BagWindow.json"
+);
+```
+
+## 注意事项
+
+1. **路径格式**：JSON 中的资源路径使用 `/` 分隔符，且为 Unity 项目相对路径
+2. **资源引用**：确保 JSON 中引用的 Sprite、Font 等资源已存在于项目中
+3. **编码格式**：JSON 文件使用 UTF-8 编码
+4. **坐标系统**：使用 Unity RectTransform 的 anchorMin/anchorMax/position/sizeDelta 四元组
+5. **文件锁定**：生成前确保目标预制体文件未被其他进程占用
+
+## 部署步骤
+
+### 方法一：手动复制
+
+1. 复制 `modules/frameworks/编辑器工具/UI工具/` 目录下的所有文件
+2. 粘贴到目标项目的 `Assets/Editor/Command/` 目录中
+3. 确保目录结构如下：
+   ```
+   Assets/Editor/Command/
+   ├── ExternalCommandListener.cs
+   ├── RemoteCommand.cs
+   ├── UIPrefabGenerator.cs
+   └── UIPrefabToJson.cs
+   ```
+
+### 方法二：自动部署脚本
+
+创建部署脚本 `DeployUITools.bat`：
+
+```batch
+@echo off
+set "SOURCE_DIR=E:\AI\UnityAI\modules\frameworks\编辑器工具\UI工具"
+set "TARGET_DIR=%cd%\Assets\Editor\Command"
+
+mkdir "%TARGET_DIR%" 2>nul
+xcopy "%SOURCE_DIR%\*.cs" "%TARGET_DIR%\" /y
+xcopy "%SOURCE_DIR%\*.cs.meta" "%TARGET_DIR%\" /y
+
+echo UI 工具部署完成
+pause
+```
+
+### 部署检查项
+
+| 检查项 | 要求 |
+|-------|------|
+| **目标路径** | 必须放置在 `Assets/Editor/Command/` 目录下 |
+| **文件完整性** | 必须包含所有 4 个 cs 文件及其 meta 文件 |
+| **Unity 版本** | 支持 Unity 2020 及以上版本 |
+| **依赖组件** | 需要导入 TextMeshPro 包 |
+
+### 验证部署
+
+部署完成后，在 Unity 编辑器中验证：
+
+1. 打开 Unity 编辑器
+2. 检查菜单 `Tools > UI` 是否存在
+3. 检查菜单 `Tools > External` 是否存在
+4. 在 Console 窗口确认无编译错误
+
+---
+
+**版本**: v1.2  
+**适用**: StrayFog 框架 UI 拼接开发人员
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [编辑器工具入口](README.md) | 本文件是编辑器工具模块的子文档 |
+| [UI 窗口系统](../UI窗口系统/README.md) | UI 拼接工具服务于 UI 窗口系统 |
+| [UI 界面拼接设计指南](../UI窗口系统/界面拼接.md) | 设计指南说明 JSON 驱动的界面拼接原则 |
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义编辑器工具层与运行时层边界 |
+| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 编辑器工具开发规则互相引用 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/网络系统.md
+++ b/modules/frameworks/网络系统.md
@@ -0,0 +1,121 @@
+# 网络系统
+
+## 分类
+
+- 核心框架
+
+## 目的
+
+提供 WebSocket 连接、protobuf 消息收发、消息 ID / route 映射和错误响应处理。
+
+---
+
+## 核心路径
+
+- protobuf 源：`GoogleProtobufNetwork/`
+- 生成输出：`Assets/Game/GameHFScripte/CopyToHF/Network/`
+- WebSocket：`Assets/Game/GameHFScripte/GameFunction/WebSocket/`
+
+---
+
+## 核心类
+
+| 类 | 职责 |
+|---|---|
+| `HFSeverManager` | 网络管理器单例 |
+| `WSSession` | WebSocket 会话 |
+| `HFM_Socket_WS` | WebSocket 底层连接 |
+| `HFWebSocket_Manager_AutoMsgMap` | 自动生成消息映射 |
+| `HFNetWorkMsgIdMap` | 网络消息 ID 映射 |
+| `MessagePage` | 数据包编解码 |
+
+---
+
+## C2S 发送链路
+
+```text
+IMessage.Dispatch()
+  -> HFSeverManager.Instance.SendMsg(message)
+  -> HFSeverManager.OnAuto_OnGetProtocNo(message)
+  -> HFSeverManager.OnAuto_OnGetRoute(Network_MsgId)
+  -> m_Session.SendMessage(protoNo, route, PacketType.Data, Request, message)
+```
+
+`IMessage.Dispatch()` 定义在 `Assets/Game/GameHFScripte/GameFunction/WebSocket/Extends/HFServer_Extend.cs`。
+
+---
+
+## WebSocket 连接流程
+
+```text
+登录管理器.ConnectServer
+  -> HFSeverManager.Connect(MainConnect, WebSocket, ip, port, token)
+  -> WSSession.Connect
+  -> HFM_Socket_WS.Connect
+  -> Handshake -> HandshakeAck -> 连接成功回调
+```
+
+---
+
+## S2C 收包和派发
+
+```text
+WSSession.ReceiveMessages(PacketType.Data)
+  -> MessagePage.Decode(packet.Body)
+  -> Response.MessageId / Push.Route -> Network_MsgId
+  -> HFSeverManager.OnAuto_OnMergeFrom(msgid, body)
+  -> protobuf Parser.ParseFrom
+  -> 反射创建 HFEvent_STC_{MessageTypeName}
+  -> 写入 Request / ErrorCode
+  -> AbsHFEventArg<enHFSTCEvent>.Dispatch()
+  -> HFEventManager.Instance.STCEvent.Dispatch(arg)
+```
+
+---
+
+## 自动生成映射
+
+- `HFWebSocket_Manager_AutoMsgMap.cs`：提供 `OnAuto_OnGetProtocNo`、`OnAuto_OnGetRoute`、`OnAuto_OnMergeFrom`、`msrDicRouteToMsg`、S2C/C2S 类型字典。
+- `HFNetWorkMsgIdMap.cs`：为 protobuf partial class 标记 `[HFNetworkMsg(...)]`。
+
+---
+
+## 使用规则
+
+- 新增协议先改 `.proto`、`msg.proto`、`route.txt`。
+- 不手动修改生成输出。
+- 不硬编码 route 或数字 msgId。
+- UI 监听 S2C 必须在 `OnClose` 移除。
+- 错误响应会触发 `HFEvent_ErrorCode`。
+
+---
+
+## 协议变更清单
+
+1. 修改 `.proto` 和 `msg.proto`。
+2. 登记 msgId / route。
+3. 重新生成 C# 代码。
+4. 检查 `HFNetWorkMsgIdMap.cs` / `HFWebSocket_Manager_AutoMsgMap.cs`。
+5. 更新业务入口和监听。
+6. 验证。
+
+---
+
+## 相关模块
+
+- [事件系统](事件系统/README.md)
+- [数据/配置框架](数据配置框架.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/事件系统/README.md](事件系统/README.md) | S2C 消息派发为 STC 事件 |
+| [modules/frameworks/数据配置框架.md](数据配置框架.md) | 配置表与网络消息可能联动 |
+| [rules/10-架构说明.md](../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/资源管理/README.md
+++ b/modules/frameworks/资源管理/README.md
@@ -0,0 +1,136 @@
+# 资源管理
+
+## 分类
+
+- 核心框架
+
+## 目的
+
+管理 AssetBundle、语言资源、图集、prefab、DllBytes 等资源的加载、缓存和释放。
+
+---
+
+## 核心路径
+
+- AssetBundle：`Assets/Game/GameHFScripte/CopyToHF/AssetBundle/`
+- 图集：`Assets/Game/GameHFScripte/CopyToHF/SpriteAtlas/`
+- 资源目录：`Assets/Game/GameHFResource/CN/`、`EN/`、`DllBytes/`
+
+---
+
+## 核心类
+
+| 类 | 职责 |
+|---|---|
+| `HFABMgr` | AssetBundle 资源管理器单例 |
+| `HFAssetLoader` | 具体资源加载器 |
+| `HFAssetRequest` | 资源加载请求 |
+| `HFAssetBundlePathAttribute` | 资源路径属性，标记资源根目录、相对路径、语言包规则等 |
+| `HFGlobal_SpriteAtlas` | 图集全局管理 |
+
+---
+
+## 资源路径规则
+
+`HFAssetBundlePathAttribute` 记录：
+
+- 资源根目录
+- 相对路径
+- 是否忽略语言包
+- 是否场景
+- 线程优先级
+
+`ChangeLanguage` 生成：
+
+- `editorPath`
+- `assetBundlePath`
+- `assetBundleKey`
+- `assetName`
+
+`HFABMgr.OnCheckAssetBundlePathAttributeLanguage` 在当前语言无资源时回退默认语言。
+
+---
+
+## 加载流程
+
+```text
+HFABMgr.LoadInMemory(pathAttr)
+  -> OnReadAssetBundleManifest()
+  -> OnCheckAssetBundlePathAttributeLanguage()
+  -> new HFAssetRequest(...)
+  -> OnStartLoad()
+  -> 获取或创建 HFAssetLoader
+  -> HFAssetLoader.LoadAsset()
+```
+
+---
+
+## 加载模式
+
+### Editor 模式
+
+```text
+enHFAbLoadModel.Editor
+  -> SFAssetUtility_Unity.LoadFromFile(editorPath)
+  -> 直接读取编辑器资源
+```
+
+### 非 Editor 模式
+
+```text
+读取 AssetBundleManifest
+  -> 解析依赖
+  -> AssetBundle.LoadFromMemoryAsync 读取主资源
+```
+
+### CDN / 边玩边下
+
+```text
+缺失资源进入 WaitDownload
+  -> HFAssetsDownLoadManager 下载
+  -> HFABMgr.SaveFile 保存到本地
+  -> 加载完成
+```
+
+---
+
+## 图集加载
+
+```text
+SpriteAtlasManager.atlasRequested
+  -> HFGlobal_SpriteAtlas.Instance.GetSpriteAtlasPath(spriteAtlasName)
+  -> HFABMgr.OnLoadInMemory(spriteAtlasAttribute)
+  -> callback(SpriteAtlas)
+```
+
+---
+
+## 使用规则
+
+- 资源路径统一通过 `HFAssetBundlePathAttribute` 配置。
+- 加载资源统一走 `HFFunCatalogue.Asset.LoadAsset()` 或 `HFABMgr.LoadInMemory()`。
+- 语言资源按 `GameHFResource/<lang>/` 分目录存放。
+- 图集按业务或 UI 模块划分。
+
+---
+
+## 相关模块
+
+- [UI 窗口系统](../UI窗口系统/README.md)
+- [实体系统](../实体系统/README.md)
+- [场景系统](../场景系统.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/UI窗口系统/README.md](../UI窗口系统/README.md) | UI 资源加载依赖资源管理 |
+| [modules/frameworks/实体系统/README.md](../实体系统/README.md) | 实体资源加载依赖资源管理 |
+| [modules/frameworks/场景系统.md](../场景系统.md) | 场景资源加载依赖资源管理 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/资源管理/使用指南.md
+++ b/modules/frameworks/资源管理/使用指南.md
@@ -1,6 +1,6 @@
-# StrayFog 框架资源管理使用指南
+# 资源管理使用指南

-## 一、AssetBundle资源加载
+## 一、AssetBundle 资源加载

 ### 1.1 加载资源示例

@@ -9,8 +9,8 @@ public class ResourceLoader : MonoBehaviour
 {
    public void LoadPlayerModel(int resId, Action<GameObject> onLoaded)
    {
-        // 通过HFFunCatalogue统一入口加载资源
-        // resId: 从Res配置表中读取的资源ID
+        // 通过 HFFunCatalogue 统一入口加载资源
+        // resId: 从 Res 配置表中读取的资源 ID
        HFFunCatalogue.Asset.LoadAsset(resId, (res, obj) => 
        {
            if (obj != null)
@@ -30,7 +30,7 @@ public class ResourceLoader : MonoBehaviour
 ### 1.2 实体资源加载示例

 ```csharp
-// 在Entity中加载资源
+// 在 Entity 中加载资源
 HFFunCatalogue.Asset.LoadAsset(data.EntityRes.Id, (res, obj) => {
    if (!entity.isDeath)
    {
@@ -42,7 +42,7 @@ HFFunCatalogue.Asset.LoadAsset(data.EntityRes.Id, (res, obj) => {

 ---

-## 二、资源管理API
+## 二、资源管理 API

 ### 2.1 常用方法

@@ -83,4 +83,20 @@ loader.LoadAsset() → 异步加载

 **版本**: v1.0  
 **生效日期**: 2026年  
-**适用范围**: GiftGameX项目业务开发人员
+**适用范围**: GiftGameX 项目业务开发人员
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [资源管理入口](README.md) | 本文件是资源管理模块的子文档 |
+| [UI 窗口系统](../UI窗口系统/README.md) | UI 资源加载依赖资源管理 |
+| [实体系统](../实体系统/README.md) | 实体资源加载依赖资源管理 |
+| [场景系统](../场景系统.md) | 场景资源加载依赖资源管理 |
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/frameworks/通用框架/README.md
+++ b/modules/frameworks/通用框架/README.md
@@ -0,0 +1,70 @@
+# 通用框架
+
+## 分类
+
+- 项目框架
+
+## 目的
+
+记录 general/shared 代码、生成框架、StrayFog 核心和跨模块通用能力。
+
+## 已知线索
+
+- General：`Assets/Game/GameGeneralScripte/`
+- 生成 General：`Assets/AutoBuildScript/General/`
+- StrayFog Core：`Assets/StrayFog/Core/`
+- 程序集：`GameGeneral`、`ZY.General.ZYCore`、`StrayFogCore`
+
+## 当前结构
+
+- `GameGeneralScripte/`：项目通用运行时代码，包含 `CopyToGeneral`、状态机扩展、`GameGeneral.asmdef`、`SEHFCommon.dll`。
+- `AutoBuildScript/General/`：生成框架的 General 层，包含 `ZYCore`、`ZYXlsx`、`ZYUGUI` 的通用模板和属性。
+- `StrayFog/Core/`：底层核心程序集和模拟行为桥接，包含 `SFCore.dll`、`SFGlobalData`、`SFAssetUtility_Unity`、`SimulateBehaviour`。
+- `GameGeneralScripte/CopyToGeneral/AssetBundle/HFAssetBundleHelper.cs`：资源路径、StreamingAssets、PersistentData、CDNAssets、微信小游戏文件读写适配。
+- `GameGeneralScripte/CopyToGeneral/DllHelper/HFDllHelper.cs`：Hotfix DLL、PDB、HybridCLR AOT DLL bytes 路径和读取。
+- `GameGeneralScripte/CopyToGeneral/Enum/HFEnumForAssetBundle.cs`：AssetBundle 加载/更新模式枚举。
+- `GameGeneralScripte/StateMachineBehaviour/`：Animator 状态机扩展和只读属性 Drawer。
+
+## 边界判断
+
+- `GameGeneralScripte` 更像项目运行时可依赖的通用层。
+- `AutoBuildScript/General` 更像代码生成框架的通用模板层。
+- `StrayFog/Core` 提供更底层的工具、全局路径和模拟行为桥接能力。
+- 资源框架、配置框架、Hotfix 启动都会依赖这里的通用能力；反向依赖 hotfix 业务逻辑应避免。
+
+## 梳理任务
+
+- [x] 梳理 `GameGeneralScripte` 和 `AutoBuildScript/General` 的边界。
+- [x] 梳理 StrayFog Core 提供的基础能力。
+- [x] 梳理通用 attributes、enum、dll helper、asset bundle helper。
+- [x] 梳理哪些功能/框架允许依赖 general/shared。
+- [x] 梳理生成代码和手写代码的边界。
+
+## 待确认
+
+- `StrayFog` 是项目自研框架还是外部框架。
+- `CopyToGeneral` 的复制/生成来源需要继续追 `AutoBuildScript` 配置。
+- General 层建议保持底层通用，不依赖 hotfix 业务层。
+
+## 相关模块
+
+- [Hotfix 启动/目录](../Hotfix启动.md)
+- [资源框架](../资源管理/README.md)
+- [数据/配置框架](../数据配置框架.md)
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [modules/frameworks/数据配置框架.md](../数据配置框架.md) | 数据/配置框架 |
+| [modules/frameworks/Hotfix启动.md](../Hotfix启动.md) | Hotfix 启动/目录 |
+| [modules/frameworks/资源管理/README.md](../资源管理/README.md) | 资源框架 |
+| [rules/10-架构说明.md](../../../rules/10-架构说明.md) | 架构说明定义总体分层和依赖方向 |
+| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 开发规则与框架/生成规则互相引用 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
+| TODO：补充依赖或使用本框架的模块文档 | 如依赖本框架的功能模块 |
--- a/modules/frameworks/通用框架/框架架构.md
+++ b/modules/frameworks/通用框架/框架架构.md
@@ -1,14 +1,16 @@
 # StrayFog 框架架构分析

+> 本文档从实现视角分析 StrayFog 框架的整体架构。高层架构规则与程序集边界见 [rules/10-架构说明.md](../../../rules/10-架构说明.md)。
+
 ## 一、框架整体架构

 ### 1.1 模块划分

 | 模块层级 | 路径 | 职责描述 |
 |---------|------|---------|
-| **Core层** | `Assets/StrayFog/Core` | 核心基础框架，模拟行为系统、全局数据管理 |
-| **HF层** | `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架，资源管理、事件系统、相机管理等 |
-| **General层** | `Assets/Game/GameGeneralScripte` | 通用工具层，状态机、辅助工具等 |
+| **Core 层** | `Assets/StrayFog/Core` | 核心基础框架，模拟行为系统、全局数据管理 |
+| **HF 层** | `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架，资源管理、事件系统、相机管理等 |
+| **General 层** | `Assets/Game/GameGeneralScripte` | 通用工具层，状态机、辅助工具等 |

 ### 1.2 架构图

@@ -31,7 +33,7 @@

 ---

-## 二、Core层架构
+## 二、Core 层架构

 ### 2.1 SimulateBehaviour 模拟行为系统

@@ -40,11 +42,11 @@
 ```csharp
 public interface ISimulateBehaviour
 {
-    long simulateGlobalId { get; }                    // 模拟行为全局ID
-    int bindGameObjectInstanceId { get; }            // 绑定对象实例ID
-    void BindGameObject(GameObject _go);             // 绑定GameObject
-    void UnBindGameObject();                         // 解绑GameObject
-    // ... 完整的MonoBehaviour生命周期方法
+    long simulateGlobalId { get; }                    // 模拟行为全局 ID
+    int bindGameObjectInstanceId { get; }            // 绑定对象实例 ID
+    void BindGameObject(GameObject _go);             // 绑定 GameObject
+    void UnBindGameObject();                         // 解绑 GameObject
+    // ... 完整的 MonoBehaviour 生命周期方法
 }
 ```

@@ -52,8 +54,8 @@ public interface ISimulateBehaviour

 | 设计目标 | 实现方式 |
 |---------|---------|
-| **解耦MonoBehaviour** | 将逻辑从MonoBehaviour中剥离，便于测试和复用 |
-| **生命周期控制** | 完整模拟Unity生命周期，支持自定义调度 |
+| **解耦 MonoBehaviour** | 将逻辑从 MonoBehaviour 中剥离，便于测试和复用 |
+| **生命周期控制** | 完整模拟 Unity 生命周期，支持自定义调度 |
 | **对象池优化** | 配合对象池实现高效对象复用 |

 #### 2.1.3 目录结构
@@ -63,14 +65,14 @@ SimulateBehaviour/
 ├── ISimulateBehaviour.cs                    # 核心接口定义
 ├── Bind/                                    # 绑定实现
 │   ├── IBindSimulateBehaviour.cs
-│   ├── AbsBindSimulateBehaviour_Mono.cs     # Mono绑定基类
-│   ├── AbsBindSimulateBehaviour_UI.cs       # UI绑定基类
+│   ├── AbsBindSimulateBehaviour_Mono.cs     # Mono 绑定基类
+│   ├── AbsBindSimulateBehaviour_UI.cs       # UI 绑定基类
 │   └── BindSimulateBehaviour_Collect.cs     # 收集器
 ├── MonoBehaviour/                            # 各生命周期模拟实现
 │   ├── SimulateMonoBehaviour_Awake__xxx.cs
 │   ├── SimulateMonoBehaviour_Update__xxx.cs
-│   └── ... (40+生命周期方法)
-└── UIBehaviour/                             # UI生命周期模拟
+│   └── ... (40+ 生命周期方法)
+└── UIBehaviour/                             # UI 生命周期模拟
    ├── SimulateUIBehaviour_Awake__xxx.cs
    └── ...
 ```
@@ -82,16 +84,16 @@ SimulateBehaviour/
 ```csharp
 public sealed class SFGlobalData 
 {
-    public static string assetBundleRoot;       // AB包根路径
+    public static string assetBundleRoot;       // AB 包根路径
    public static string streamingAssetsRoot;   // 流式资源根路径
-    public static string cdnassetBundleRoot;    // CDN资源路径
+    public static string cdnassetBundleRoot;    // CDN 资源路径
    public static RuntimePlatform Platform();   // 当前平台判断
 }
 ```

 ---

-## 三、HF层架构
+## 三、HF 层架构

 ### 3.1 接口体系

@@ -116,13 +118,13 @@ IHFObject (基础对象接口)
 | `IHFObject` | 基础对象标识 | 无 |
 | `IHFRecycle` | 对象回收机制 | `Recycle()` |
 | `IHFGlobal` | 全局唯一标识 | `globalId` |
-| `IHFClone` | 对象克隆能力 | 系列Clone方法 |
+| `IHFClone` | 对象克隆能力 | 系列 Clone 方法 |
 | `IHFLanguage` | 多语言支持 | 语言切换 |
 | `IHFScene` | 场景管理 | 场景加载/卸载 |

 ### 3.2 对象池系统

-#### 3.2.1 HFObjectMemPool - GameObject对象池
+#### 3.2.1 HFObjectMemPool - GameObject 对象池

 ```csharp
 public class HFObjectMemPool
@@ -143,7 +145,7 @@ public class HFScriptMemPool<T> : IHFRecycle
 {
    private Queue<T> m_UnoccupiedPool;
    private List<T> m_UsingPool;
-    // 支持MonoBehaviour和普通类的自动创建
+    // 支持 MonoBehaviour 和普通类的自动创建
 }
 ```

@@ -154,7 +156,7 @@ public class HFScriptMemPool<T> : IHFRecycle
 | **双池结构** | 空闲池 + 使用池 | 高效管理对象状态 |
 | **内存泄漏检测** | 归还时校验来源 | 及时发现问题 |
 | **泛型支持** | `HFScriptMemPool<T>` | 类型安全 |
-| **Mono支持** | 自动创建GameObject | 无缝集成Unity |
+| **Mono 支持** | 自动创建 GameObject | 无缝集成 Unity |

 ### 3.3 事件系统

@@ -177,7 +179,7 @@ public abstract class AbsHFEventHandle<K,T> : IHFEventHandle<K,T>
    where K : struct, Enum
    where T : IHFEventArg<K>
 {
-    // 多级索引: EventId -> TypeHashCode -> Action列表
+    // 多级索引: EventId -> TypeHashCode -> Action 列表
    HFMultiKeyDictionary<K, int, IHFCacheEventAction<K,T>> mICacheEventActionMaping;
 }
 ```
@@ -189,10 +191,10 @@ public abstract class AbsHFEventHandle<K,T> : IHFEventHandle<K,T>
 Dispatch(arg)
    │
    ▼
-获取 EventId 对应的 Action字典
+获取 EventId 对应的 Action 字典
    │
    ▼
-获取 参数类型HashCode 对应的 CacheEventAction
+获取 参数类型 HashCode 对应的 CacheEventAction
    │
    ▼
 遍历执行所有 Action<T>
@@ -235,7 +237,7 @@ loader.LoadAsset() → 异步加载

 #### 3.4.3 依赖管理

-通过Manifest文件解析资源依赖关系：
+通过 Manifest 文件解析资源依赖关系：

 ```csharp
 HFAssetBundlePathAttribute OnGetDependencyAbpAttr(string _depManifestName)
@@ -271,12 +273,12 @@ HFMainCamera (主相机)
    │       ├── CameraItem2 (Weight=20)
    │       └── CameraItem3 (Weight=5)
    │
-    └── 按Weight排序 → 渲染顺序控制
+    └── 按 Weight 排序 → 渲染顺序控制
 ```

 ---

-## 四、General层架构
+## 四、General 层架构

 ### 4.1 状态机系统

@@ -296,16 +298,16 @@ IGFStateMachineBehaviour (接口)
 #### 4.1.2 状态机特性

 | 特性 | 说明 |
-|-----|-----|
+|-----|------|
 | **层级化设计** | 支持状态、层、机三个层级的行为绑定 |
 | **参数化驱动** | 通过参数控制状态切换 |
-| **Inspector扩展** | 自定义编辑器支持 |
+| **Inspector 扩展** | 自定义编辑器支持 |

 ### 4.2 工具类

 #### 4.2.1 扩展方法集合

-**HFUGUIExtendEngine.cs** - UGUI扩展方法（40+方法）
+**HFUGUIExtendEngine.cs** - UGUI 扩展方法（40+ 方法）

 | 功能分类 | 方法示例 |
 |---------|---------|
@@ -318,9 +320,9 @@ IGFStateMachineBehaviour (接口)

 | 工具类 | 职责 |
 |-------|-----|
-| `HFAssetBundleHelper` | AB包辅助工具 |
-| `HFDllHelper` | DLL加载辅助 |
-| `HFEnumForAssetBundle` | AB包相关枚举 |
+| `HFAssetBundleHelper` | AB 包辅助工具 |
+| `HFDllHelper` | DLL 加载辅助 |
+| `HFEnumForAssetBundle` | AB 包相关枚举 |
 | `MinGameModel` | 微信小游戏适配 |

 ---
@@ -332,46 +334,65 @@ IGFStateMachineBehaviour (接口)
 | 模式 | 应用场景 | 实现类 |
 |-----|---------|-------|
 | **单例模式** | 全局管理器 | `AbsHFSingleMonoBehaviour`, `AbsHFSingleRunTime` |
-| **工厂模式** | 对象创建 | 对象池的GetItem |
+| **工厂模式** | 对象创建 | 对象池的 GetItem |
 | **观察者模式** | 事件系统 | `IHFEventHandle` |
 | **策略模式** | 多平台适配 | `SFGlobalData.Platform()` |
-| **模板方法** | 生命周期 | `SimulateBehaviour`系列 |
+| **模板方法** | 生命周期 | `SimulateBehaviour` 系列 |

 ### 5.2 架构优势

 | 优势 | 体现 |
-|-----|-----|
-| **解耦性** | 逻辑与MonoBehaviour分离 |
+|-----|------|
+| **解耦性** | 逻辑与 MonoBehaviour 分离 |
 | **可测试性** | 纯逻辑类易于单元测试 |
-| **性能优化** | 对象池减少GC |
+| **性能优化** | 对象池减少 GC |
 | **扩展性** | 接口驱动，易于扩展 |
 | **可维护性** | 清晰的模块划分 |

 ### 5.3 潜在改进点

 | 改进方向 | 说明 |
-|---------|-----|
-| **异步加载优化** | 可引入协程池或Job System |
+|---------|------|
+| **异步加载优化** | 可引入协程池或 Job System |
 | **资源依赖可视化** | 可增加依赖关系图工具 |
 | **性能监控** | 可增加加载时间、内存占用统计 |
-| **热更新支持** | 可考虑集成Lua或ILRuntime |
+| **热更新支持** | 可考虑集成 Lua 或 ILRuntime |

 ---

 ## 六、总结

-StrayFog框架是一个结构清晰、设计完善的Unity游戏框架，核心特点包括：
+StrayFog 框架是一个结构清晰、设计完善的 Unity 游戏框架，核心特点包括：

-1. **模拟行为系统** - 实现了完整的MonoBehaviour生命周期解耦
+1. **模拟行为系统** - 实现了完整的 MonoBehaviour 生命周期解耦
 2. **对象池机制** - 高效的内存管理策略
 3. **事件驱动架构** - 灵活的事件分发系统
-4. **资源管理体系** - 完善的AssetBundle加载和依赖管理
+4. **资源管理体系** - 完善的 AssetBundle 加载和依赖管理
 5. **模块化设计** - 清晰的分层和职责划分

-该框架适合中大型Unity项目使用，具备良好的扩展性和维护性。
+该框架适合中大型 Unity 项目使用，具备良好的扩展性和维护性。

 ---

 **版本**: v1.0  
 **分析日期**: 2024年  
-**适用项目**: OnlineGame
+**适用项目**: OnlineGame
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [通用框架入口](README.md) | 本文件是通用框架模块的子文档 |
+| [架构说明](../../../rules/10-架构说明.md) | 高层架构规则与程序集边界 |
+| [实体系统](../实体系统/README.md) | 实体系统架构在本文件中分析 |
+| [对象池与运行时对象管理](../内存对象管理/README.md) | 对象池架构在本文件中分析 |
+| [事件系统](../事件系统/README.md) | 事件系统架构在本文件中分析 |
+| [资源管理](../资源管理/README.md) | 资源管理架构在本文件中分析 |
+| [相机系统](../相机系统/README.md) | 相机系统架构在本文件中分析 |
+| [modules/模块索引.md](../../模块索引.md) | 模块索引是项目知识总入口 |
+| [rules/20-开发规则.md](../../../rules/20-开发规则.md) | 开发规则与框架架构互相引用 |
+| [rules/30-模块登记规则.md](../../../rules/30-模块登记规则.md) | 模块登记规则定义分类和状态口径 |
--- a/modules/模块文档模板.md
+++ b/modules/模块文档模板.md
@@ -0,0 +1,84 @@
+# 模块名称
+
+## 分类
+
+- 项目功能 / 项目框架 / 编辑器工具
+
+## 目的
+
+TODO：一句话说明这个模块是做什么的，从玩家/产品/技术视角写。
+
+## 主要路径
+
+| 类型 | 路径 | 说明 |
+|---|---|---|
+| 逻辑代码 | `Assets/...` | TODO |
+| UI 代码 | `Assets/...` | TODO |
+| 资源 | `Assets/...` | TODO |
+| 配置 | `XLSX_SRC/...` 或 `GoogleProtobufNetwork/...` | TODO |
+
+## 入口
+
+- 运行入口：TODO
+- 编辑器入口：TODO
+- 资源入口：TODO
+
+## 数据流
+
+```text
+TODO：用箭头图描述关键流程
+```
+
+## 关键类 / API
+
+| 类/方法 | 用途 |
+|---|---|
+| `ClassName` | TODO |
+
+## 依赖
+
+- 依赖的框架模块：TODO
+- 依赖的其他功能模块：TODO
+- 依赖的第三方插件：TODO
+
+## 当前状态
+
+- TODO
+
+## 变更记录
+
+| 日期 | 变更内容 | 关联 spec/change | 影响范围 |
+|---|---|---|---|
+| YYYY-MM-DD | 简要描述 | `[<change-name>]`（对应 `specs/openspec/<change-name>/业务参考总入口.md`） | 相关模块/文件 |
+
+## 文档关联
+
+本模块发生变更时，以下文档必须同步更新：
+
+- [模块索引](模块索引.md) — 如果新增/删除模块，或模块分类/状态改变
+- [模块登记规则](../rules/30-模块登记规则.md) — 如果新增模块、分类口径或依赖关系变化
+- [架构说明](../rules/10-架构说明.md) — 如果涉及架构变化
+- TODO：链接相关功能/框架模块文档（如依赖方或被依赖方）
+- TODO：链接相关 spec 目录（如 `../../specs/openspec/<change-name>/业务参考总入口.md`）
+
+> 注意：本模板位于 `modules/` 根目录。如果复制到 `modules/features/` 或 `modules/frameworks/` 下，请把 `../rules/` 和 `模块索引.md` 调整为 `../../rules/` 和 `../模块索引.md`。
+
+## 下一步
+
+- [ ] TODO
+
+## 相关文档
+
+- [模块索引](模块索引.md)
+- [模块登记规则](../rules/30-模块登记规则.md)
+- [架构说明](../rules/10-架构说明.md)
+- TODO：链接相关功能/框架模块文档
+
+## 是否需要拆分文档
+
+轻量模块可以只保留这个 README。
+
+当模块出现独立计划、持续进度或多项待办时，再增加：
+
+- `progress.md`
+- `tasks.md`
--- a/modules/模块索引.md
+++ b/modules/模块索引.md
@@ -0,0 +1,85 @@
+# 模块索引
+
+这里是 UnityAI / StrayFog 框架知识库的项目知识总入口。
+
+模块清单、模块状态和模块入口以本文件为准；`rules/` 只维护规则和约束，不重复维护模块事实表。
+
+---
+
+## 重要口径
+
+- **核心框架**：支撑游戏运行的内部系统，例如实体系统、UI 窗口系统、事件系统、资源管理、对象池、场景管理。
+- **编辑器工具**：Unity Editor 内使用的生成器、Inspector、菜单、配置工具。
+- **业务参考**：外部实际项目的业务实现示例，仅作参考，不作为框架规范。见 [business-reference](../business-reference/playballoons/业务参考总入口.md)。
+
+轻量模块先在本文件登记；复杂模块再拆独立目录。
+
+---
+
+## 状态口径
+
+见 [模块登记规则](../rules/30-模块登记规则.md#状态定义)。
+
+不要使用“已开始”，优先使用“已识别 / 初步梳理 / 待验证 / 已完成 / 未发现实现”。
+
+---
+
+## 核心框架
+
+| 框架模块 | 主要路径 | 当前判断 | 状态 |
+|---|---|---|---|
+| [模拟行为系统](frameworks/通用框架/README.md) | `Assets/StrayFog/Core/SimulateBehaviour/` | 解耦 MonoBehaviour，模拟完整生命周期 | 已完成 |
+| [对象池](frameworks/内存对象管理/README.md) | `Assets/Game/GameHFScripte/CopyToHF/MemoryManager/` | GameObject 对象池、脚本对象池、类实例池 | 已完成 |
+| [事件系统](frameworks/事件系统/README.md) | `Assets/Game/GameHFScripte/CopyToHF/Event/` | CTC/STC 事件参数和事件派发 | 已完成 |
+| [资源管理](frameworks/资源管理/README.md) | `Assets/Game/GameHFScripte/CopyToHF/AssetBundle/` | AssetBundle、语言资源、图集、加载规则 | 已完成 |
+| [相机系统](frameworks/相机系统/README.md) | `Assets/Game/GameHFScripte/CopyToHF/` | 多相机管理、相机堆栈、渲染顺序 | 初步梳理 |
+| [实体系统](frameworks/实体系统/README.md) | `Assets/Game/GameHFScripte/GameFunction/GameEntity/` | 实体基类、模型/系统、实体池 | 已完成 |
+| [UI 窗口系统](frameworks/UI窗口系统/README.md) | `Assets/Game/GameHFScripte/CopyToHF/UIWindowMgr/` | UI 窗口管理、窗口基类、生命周期 | 已完成 |
+| [技能系统](frameworks/技能系统/README.md) | `Assets/Game/GameHFScripte/GameFunction/GameEntity/` | 技能触发器、释放器、配置联动 | 初步梳理 |
+| [场景系统](frameworks/场景系统.md) | `Assets/Game/GameHFScripte/GameFunction/SceneManager/` | 场景加载、资源配置、生命周期 | 初步梳理 |
+| [网络系统](frameworks/网络系统.md) | `Assets/Game/GameHFScripte/CopyToHF/Network/` | WebSocket、protobuf、消息映射 | 初步梳理 |
+| [配置生成](frameworks/数据配置框架.md) | `XLSX_SRC/`、`Assets/AutoBuildScript/` | 表格配置源、解析、生成代码 | 初步梳理 |
+| [Hotfix 启动](frameworks/Hotfix启动.md) | `Assets/Game/GameHFScripte/GameFunction/GameRoot/` | hotfix 侧根入口和功能目录聚合 | 初步梳理 |
+
+---
+
+## 编辑器工具
+
+| 工具模块 | 主要路径 | 当前判断 | 状态 |
+|---|---|---|---|
+| [SF Editor](frameworks/编辑器工具/README.md#sf-editor) | `Assets/StrayFog/Editor/` | StrayFog 编辑器扩展 | 待验证 |
+| [项目 Editor Assets](frameworks/编辑器工具/README.md#project-editor-assets) | `Assets/Editor/` | 项目编辑器资源与脚本 | 待验证 |
+
+---
+
+## 文档拆分规则
+
+- 核心框架按技术职责命名，可以对应 `GameEntity`、`UIWindowMgr`、`Network`、`AssetBundle`、`Event` 这类内部系统。
+- 轻量模块只在本文件登记。
+- 复杂模块再拆 `modules/<module>/`。
+- `模块索引.md` 写稳定说明。
+- `progress.md` 写阶段状态。
+- `tasks.md` 写下一步待办。
+- 跨模块计划放到 [plans](../plans/)。
+
+---
+
+## 相关文档
+
+- [项目规则入口](../rules/项目规则入口.md)：AI 工作方式、扫描范围、归档规则和规则索引。
+- [模块登记规则](../rules/30-模块登记规则.md)：分类口径、状态定义和新增模块登记规则。
+- [架构说明](../rules/10-架构说明.md)：总体分层、程序集边界和依赖方向。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [rules/30-模块登记规则.md](../rules/30-模块登记规则.md) | 模块索引是模块登记规则的唯一事实来源 |
+| [rules/10-架构说明.md](../rules/10-架构说明.md) | 模块分类、分层与架构说明互相影响 |
+| [rules/项目规则入口.md](../rules/项目规则入口.md) | 模块索引是项目规则入口引用的项目知识总入口 |
+| [ai/AI接入入口.md](../ai/AI接入入口.md) | AI 接入入口引用模块索引作为必读文档 |
+| [modules/frameworks/*](frameworks/) | 框架模块文档新增/拆分时需同步索引 |
--- a/rules/00-项目概览.md
+++ b/rules/00-项目概览.md
@@ -0,0 +1,119 @@
+# 项目概览
+
+> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
+
+## 摘要
+
+`UnityAI` 是 **StrayFog 框架文档中心**，用于沉淀 StrayFog 框架的架构设计、核心功能使用规范、开发流程和项目管理规则。
+
+本仓库本身不包含游戏业务代码，而是一个**面向 AI 工具与人工开发者的知识库**。AI 工具通过 ai/rules/modules/ 下的规则与模块文档快速理解框架；人工开发者可以通过 `modules/frameworks/` 下的框架模块文档和 `rules/` 下的规则文档学习使用。
+
+- **项目名**：UnityAI
+- **副标题**：StrayFog 框架文档中心
+- **目标读者**：AI 工具、业务开发人员、框架维护人员
+- **文档语言**：中文
+- **适用项目**：GiftGameX、OnlineGame 等使用 StrayFog 框架的项目
+
+---
+
+## 重要目录
+
+| 目录 | 用途 |
+|------|------|
+| `modules/frameworks/` | 核心框架模块文档：实体、UI、事件、资源、对象池等。 |
+| `rules/` | 项目长期规则：工作方式、扫描范围、任务流程、归档规则。 |
+| `modules/` | 项目知识总入口：框架模块、核心功能、编辑器工具。 |
+| `hooks/` | 共享 hook：归档检查、提交检查、文档关联同步。 |
+| `specs/` | 大需求 / 新模块的 OpenSpec 归档。 |
+| `modules/frameworks/编辑器工具/UI工具/` | UI 预制体 JSON 转换工具脚本。 |
+| `business-reference/` | 外部实际项目业务参考，与框架核心分离。 |
+
+---
+
+## 核心子系统
+
+StrayFog 框架主要包含以下子系统：
+
+| 子系统 | 主要职责 | 对应文档 |
+|--------|---------|---------|
+| **模拟行为系统** | 解耦 MonoBehaviour，模拟完整生命周期 | [SimulateBehaviour](../modules/frameworks/通用框架/README.md) |
+| **对象池系统** | GameObject 对象池、脚本对象池、类实例池 | [对象池](../modules/frameworks/内存对象管理/README.md) |
+| **事件系统** | CTC/STC 事件派发、监听与释放 | [事件系统](../modules/frameworks/事件系统/README.md) |
+| **资源管理系统** | AssetBundle 加载、依赖管理、语言包、图集 | [资源管理](../modules/frameworks/资源管理/README.md) |
+| **相机管理系统** | 多相机管理、相机堆栈、渲染顺序 | [相机系统](../modules/frameworks/相机系统/README.md) |
+| **实体系统** | 实体创建、System-Model 架构、实体池 | [实体系统](../modules/frameworks/实体系统/README.md) |
+| **UI 窗口系统** | UI 窗口管理、层级、生命周期、事件释放 | [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md) |
+| **技能系统** | 技能触发器、释放器、配置联动 | [技能系统](../modules/frameworks/技能系统/README.md) |
+| **场景系统** | 场景加载、资源配置、生命周期 | [场景系统](../modules/frameworks/场景系统.md) |
+| **网络系统** | WebSocket、protobuf、消息映射（如项目使用） | [网络系统](../modules/frameworks/网络系统.md) |
+| **配置生成系统** | XLSX / protobuf 配置生成（如项目使用） | [配置生成](../modules/frameworks/数据配置框架.md) |
+
+---
+
+## 文档分层
+
+```text
+AI 接入层
+  AGENTS.md / CLAUDE.md / RULES.md / ai/AI接入入口.md
+      |
+      v
+项目规则层
+  rules/项目规则入口.md + 00~70 规则文件
+      |
+      v
+项目知识层
+  modules/模块索引.md
+      |
+      ├── 框架模块（frameworks/）
+      ├── 编辑器工具（editor-tools/）
+      └── 使用示例（examples/）
+      |
+      v
+业务参考层
+  business-reference/playballoons/
+      |
+      v
+Hook / Spec / Plan
+  hooks/ / specs/ / plans/
+```
+
+---
+
+## 使用方式
+
+### AI 工具
+
+1. 读取 `ai/AI接入入口.md`
+2. 读取 `rules/项目规则入口.md`
+3. 按任务范围读取 `modules/` 下具体模块文档
+4. 如需了解外部项目业务参考，读取 `business-reference/playballoons/业务框架映射接口.md`
+
+### 人工开发者
+
+1. 新成员从 [开发规则](20-开发规则.md) 开始。
+2. 了解架构看 [架构说明](10-架构说明.md) 和 [通用框架/框架架构](../modules/frameworks/通用框架/框架架构.md)。
+3. 使用具体系统看 `modules/frameworks/` 下对应框架模块。
+4. 遇到问题看 [开发规则/常见问题](20-开发规则.md#常见问题)。
+
+---
+
+## 关键约束
+
+- `ai/rules/modules/` 是 StrayFog 框架知识的唯一事实来源；旧中文教程内容已迁移合并至此。
+- 修改 `modules/` 中模块文档后，必须同步更新 `modules/模块索引.md` 和相关规则文件。
+- `business-reference/` 中的内容来自外部实际项目，仅作参考，不作为 StrayFog 框架规范。
+- 不要把项目规则复制进系统提示或 AI 工具私有目录。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [rules/项目规则入口.md](项目规则入口.md) | 项目概览是项目规则入口引用的核心信息 |
+| [rules/10-架构说明.md](10-架构说明.md) | 重要顶层目录与总体分层、程序集边界相关 |
+| [rules/20-开发规则.md](20-开发规则.md) | 生成内容约束与开发规则互相引用 |
+| [rules/70-项目设置.md](70-项目设置.md) | 扫描范围、跳过目录与项目概况中的目录说明相关 |
+| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是项目知识总入口 |
--- a/rules/10-架构说明.md
+++ b/rules/10-架构说明.md
@@ -0,0 +1,144 @@
+# 架构说明
+
+> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
+
+项目文档按三类组织：**核心运行时**、**编辑器工具**、**业务参考**。详细模块索引见 [模块索引](../modules/模块索引.md)。
+
+---
+
+## 分类口径
+
+- **核心运行时**：支撑游戏运行的内部系统，例如实体、UI、网络、资源、事件、场景、对象池。
+- **编辑器工具**：Unity Editor 内使用的生成器、Inspector、菜单、配置工具。
+- **业务参考**：外部实际项目的业务实现示例，仅作参考，不作为框架规范。
+
+---
+
+## 总体分层
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                     StrayFog Framework                      │
+├─────────────────────────────────────────────────────────────┤
+│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────┐  │
+│  │   GameGeneral    │  │     GameHF       │  │    Core   │  │
+│  │   通用工具层     │  │   业务核心层     │  │  基础框架 │  │
+│  └────────┬─────────┘  └────────┬─────────┘  └─────┬─────┘  │
+├───────────┼─────────────────────┼──────────────────┼─────────┤
+│           │                     │                  │         │
+│           ▼                     ▼                  ▼         │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │                   Unity Engine                      │    │
+│  └─────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 各层职责
+
+| 层级 | 路径 | 职责描述 |
+|------|------|---------|
+| **Core 层** | `Assets/StrayFog/Core` | 核心基础框架，模拟行为系统、全局数据管理 |
+| **HF 层** | `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架，资源管理、事件系统、相机管理、UI 管理等 |
+| **General 层** | `Assets/Game/GameGeneralScripte` | 通用工具层，状态机、辅助工具、扩展方法等 |
+
+---
+
+## 核心运行时层
+
+核心运行时按技术职责命名，可以对应内部目录。
+
+- **Hotfix 启动/目录**：`GameFunction/GameRoot/`
+- **实体系统**：`GameFunction/GameEntity/`、`Logic/EntityData/`
+- **UI 系统**：`CopyToHF/UIWindowMgr/`、`GameFunction/UIWindows/`、`GameMono/Scripts/UIMono/`
+- **场景系统**：`GameFunction/SceneManager/`、`GameMono/Scenes/`
+- **网络系统**：`CopyToHF/Network/`、`GameFunction/WebSocket/`、`GoogleProtobufNetwork/`（如项目使用）
+- **资源系统**：`CopyToHF/AssetBundle/`、`CopyToHF/SpriteAtlas/`、`GameHFResource/`
+- **事件系统**：`CopyToHF/Event/`、`GameFunction/Event/`
+- **对象池**：`CopyToHF/MemoryManager/`、`GameFunction/GameEntity/EntityPool/`
+- **通用框架**：`GameGeneralScripte/`、`StrayFog/Core/`
+
+---
+
+## 编辑器工具层
+
+- `Assets/StrayFog/Editor/`：StrayFog 编辑器扩展。
+- `Assets/Editor/`：项目编辑器资源与脚本。
+- `Assets/AutoBuildScript/Editor/`：编辑器生成工具（如项目使用）。
+
+---
+
+## 程序集边界
+
+已识别 asmdef：
+
+| 程序集 | 主要路径 | 分类 |
+|---|---|---|
+| `StrayFogCore` | `Assets/StrayFog/Core/` | 核心运行时 |
+| `SFEditor` | `Assets/StrayFog/Editor/` | 编辑器工具 |
+| `GameHF` | `Assets/Game/GameHFScripte/` | 核心运行时 / hotfix 承载 |
+| `GameGeneral` | `Assets/Game/GameGeneralScripte/` | 核心运行时 / general |
+| `SFMono` | `Assets/Game/GameMono/` | 核心运行时 / Mono 桥接 |
+
+---
+
+## 依赖方向
+
+```text
+业务功能（PVE、PVP、背包、商店等，放在外部业务参考层）
+        |
+        v
+核心运行时（GameRoot、GameEntity、UIWindowMgr、SceneManager、Network、AssetBundle、Event 等）
+        |
+        v
+通用框架 / 第三方插件（StrayFog Core、Spine、DOTween 等）
+        |
+        v
+Unity Engine / .NET Runtime
+
+编辑器工具 -----------------> 读取/生成 核心运行时代码
+```
+
+### 依赖规则
+
+| 上层 | 可以依赖 | 禁止依赖 |
+|---|---|---|
+| 业务功能 | 核心运行时、通用框架 | 编辑器工具、第三方插件源码 |
+| 核心运行时 | 通用框架、第三方插件 | 具体业务功能、编辑器工具 |
+| 编辑器工具 | 核心运行时源码、生成模板 | 被运行时代码反向引用 |
+
+### 说明
+
+- 运行时代码不要依赖 Editor 程序集。
+- 第三方插件不应反向依赖具体玩法模块。
+- 业务功能代码按业务命名，代码目录可以仍然按框架/实现组织。
+
+---
+
+## 文档与代码分层对应
+
+| 文档层 | 对应代码层 | 示例 |
+|--------|-----------|------|
+| `modules/frameworks/` | 核心运行时 | 实体系统、UI 系统、事件系统等 |
+| `modules/frameworks/通用框架/框架架构.md` | 核心运行时 + 规范 | StrayFog 整体架构分析 |
+| `rules/` | 规范与流程 | 开发规则、工作流清单、架构说明 |
+
+---
+
+## 待确认
+
+- 各项目实际使用的 StrayFog 版本与目录可能略有差异，文档中路径以当前仓库描述的 `Assets/StrayFog/` 和 `Assets/Game/` 结构为准。
+- 网络系统、配置生成系统是否为所有使用 StrayFog 的项目标配，需按具体项目确认。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/frameworks/通用框架/框架架构.md](../modules/frameworks/通用框架/框架架构.md) | 实现视角的框架架构分析 |
+| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是架构说明的落地入口，分类口径需一致 |
+| [rules/30-模块登记规则.md](30-模块登记规则.md) | 模块登记口径、状态定义与架构分层互相影响 |
+| [rules/20-开发规则.md](20-开发规则.md) | 程序集边界、依赖方向与开发规则互相引用 |
+| [rules/项目规则入口.md](项目规则入口.md) | 架构说明是项目规则入口索引的关键规则 |
--- a/rules/20-开发规则.md
+++ b/rules/20-开发规则.md
@@ -0,0 +1,269 @@
+# 开发规则
+
+> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
+
+## 基本原则
+
+- 优先遵循项目已有模式。
+- 修改范围保持在当前功能或模块内。
+- 不手动修改生成代码，除非生成器不可用且已记录原因。
+- 不直接修改 `Assets/ThirdPlugins/` 或 embedded package，除非必须且记录原因。
+- 正常分析项目时忽略 Unity/IDE 本地状态目录。
+- 运行时代码不引用 Editor 程序集。
+- **一处定义，多处引用**：如果一个事实出现在多个文档中，修改时必须同步所有地方。
+
+---
+
+## C# 规则
+
+### 命名
+
+- 类名、结构体、枚举、属性、方法使用 PascalCase。
+- 私有字段使用 `m_` + PascalCase，例如 `m_UserName`、`m_BagPage`。
+- 方法参数使用 `_` + camelCase，例如 `_username`、`_maxpage`。
+- 局部变量使用 camelCase。
+- 常量：同一文件内保持一致，优先使用全大写 + 下划线（如 `C_FRAME_ROOT_PATH`）或 PascalCase。
+- 抽象类优先加 `Abs` 前缀，例如 `AbsHFSingleMonoBehaviour<T>`、`AbsHFAssetRequest`。
+- 单例管理器优先继承 `AbsHFSingleMonoBehaviour<T>` 或 `AbsHFSingleRunTime<T>`。
+- Hotfix 类名可优先加 `HF` 前缀，例如 `HFLoginManager`、`HFBagManager`。
+- 业务类型枚举可按用途加前缀，例如 `enItemType`、`enCurrencySubItemType`。
+- 事件枚举可按用途加前缀，例如 `enHFSTCEvent`、`enHFCTCEvent`。
+
+### 代码组织
+
+- 一个 `.cs` 文件原则上只放一个主要类型；小枚举可多个共存。
+- 类型可见性排序按项目已有风格；如无风格，按 public → protected → internal → private。
+- 公共 API 添加中文 XML 文档注释或行内注释，说明用途、参数、返回值。
+- 只在解释非显然意图时添加注释，不写无意义注释。
+
+### 日志与异常
+
+- 异常只用于异常情况，不用于正常流程控制。
+- 错误日志包含方法名和关键上下文，不包含敏感信息。
+- 写日志时保持附近文件风格；优先使用项目统一的日志封装（如有）。
+
+### 其他
+
+- 优先遵循附近文件风格。同一文件/同一目录下风格应保持一致。
+- 保持 public API 小而明确。
+- 避免超长方法和深层嵌套。
+
+---
+
+## 核心库访问规则
+
+### 核心库范围
+
+以下目录属于核心库，业务代码应只读访问，修改需走框架团队 Issue 流程：
+
+| 路径 | 说明 |
+|------|------|
+| `Assets/StrayFog/Core` | 基础框架核心 |
+| `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架 |
+| `Assets/Game/GameGeneralScripte` | 通用工具层 |
+
+### 访问方式
+
+业务代码必须通过 `HFFunCatalogue` 统一入口访问核心库：
+
+```csharp
+// ✅ 正确：通过统一入口访问
+HFFunCatalogue.UIManager.OpenWindow<LoginWindow>();
+HFFunCatalogue.Asset.LoadAsset<GameObject>("path");
+HFFunCatalogue.Scene.LoadScene("MainScene");
+
+// ❌ 禁止：直接访问核心库
+HFUIWindowMgr.Instance.OpenWindow<LoginWindow>(); // 禁止
+HFABMgr.Instance.LoadAsset<GameObject>("path");   // 禁止
+```
+
+### 禁止操作
+
+| 禁止行为 | 后果 |
+|---------|------|
+| 修改核心库源代码 | 破坏框架稳定性 |
+| 删除/重命名核心库文件 | 编译错误 |
+| 直接实例化核心库内部类 | 违反封装原则 |
+| 绕过 `HFFunCatalogue` 直接调用核心库单例 | 难以维护和测试 |
+
+### 修改流程
+
+1. 业务人员发现问题/需求 → 提交 Issue 到框架团队
+2. 框架团队评估需求
+3. 合理：开发修复 → 代码审查 → 发布新版本 → 业务团队更新引用
+4. 不合理：反馈拒绝
+
+---
+
+## 业务代码结构
+
+### 目录组织
+
+业务代码主要位于 `Assets/Game/GameHFScripte/GameFunction/`，按职责分目录：
+
+```
+Assets/Game/GameHFScripte/GameFunction/
+├── Event/                       # 消息处理
+│   ├── ServerToClient/          # 服务器到客户端消息
+│   ├── ClientToClient/          # 客户端内部消息
+│   └── Handle/                  # 消息处理器
+├── GameRoot/                    # 框架调用入口
+├── Logic/                       # 游戏主要业务逻辑（存放各功能 Manager）
+├── UIWindows/                   # UI 窗口业务逻辑
+├── GameEntity/                  # 游戏实体
+├── SoundManagerPro/             # 音效管理
+├── SceneManager/                # 场景管理
+└── SDK/                         # SDK 集成
+```
+
+### 文件命名
+
+| 文件类型 | 命名规则 | 示例 |
+|---------|---------|-----|
+| 窗口类 | `XXXWindow.cs` | `LoginWindow.cs` |
+| 组件类 | `XXXComponent.cs` | `ItemCellComponent.cs` |
+| 管理器类 | `XXXManager.cs` | `UIManager.cs` |
+| 数据类 | `XXXData.cs` | `PlayerData.cs` |
+| 配置类 | `XXXConfig.cs` | `SkillConfig.cs` |
+
+---
+
+## 最佳实践
+
+### 性能优化
+
+- 频繁创建销毁的对象必须使用对象池。
+- 合理设置对象池初始容量。
+- 及时释放不再使用的资源。
+- 使用异步加载避免卡顿。
+- 合理使用资源缓存。
+- 将图标打包到 SpriteAtlas。
+- 滚动列表优先使用 `SFUI_ScrollRect.BindEvent`。
+
+### 代码组织
+
+- 每个类只负责一个功能，避免庞大的 God 类。
+- 通过管理器获取依赖，而非硬编码。
+- 使用接口解耦依赖关系。
+- 保持 public API 小而明确。
+- 避免超长方法和深层嵌套。
+
+### 错误处理
+
+- 异常只用于异常情况，不用于正常流程控制。
+- 在关键路径添加异常处理。
+- 记录错误日志便于排查，但不包含敏感信息。
+- 检查参数合法性，处理空引用情况。
+
+---
+
+## 常见问题
+
+### 如何扩展核心库功能？
+
+通过继承抽象类或实现接口来扩展，不要直接修改核心库代码。
+
+### 核心库有 Bug 怎么办？
+
+提交 Issue 到框架团队，由框架团队修复并发布新版本。
+
+### 如何调试核心库代码？
+
+可以设置断点调试，但不允许修改代码。
+
+### 常用核心库 API
+
+| 类别 | 管理器 | 常用方法 |
+|-----|-------|---------|
+| 对象池 | `HFObjectMemPool` | `GetItem()`, `GiveBack()` |
+| 事件 | `IHFEventHandle` | `AddListener()`, `Dispatch()` |
+| 资源 | `HFABMgr` | `OnStartLoad()` |
+| 相机 | `HFCameraManager` | `AddCamera()`, `GetCamera()` |
+
+---
+
+## Unity 资源规则
+
+### Prefab
+
+- Prefab 修改保持聚焦，避免无意义的大范围 reserialize。
+- UI Prefab 命名与窗口/面板对应，例如 `Login.prefab`、`ItemWindow.prefab`。
+- 通用 UI 组件/Item 使用 `Item` 后缀，例如 `AvatarItem.prefab`、`ResourceItem.prefab`。
+- 记录无法从代码复现的手动 Unity Editor 操作。
+
+### Scene
+
+- 场景按用途命名，例如 `LoginScene`、`BattleScene`。
+- 不要直接在场景里堆放运行时动态加载的资源。
+
+### Sprite Atlas
+
+- 按业务或 UI 模块划分图集，例如 `SpriteAtlasAssets/Shop`、`SpriteAtlasAssets/Login`。
+- 图集内图片按功能子目录组织，避免单张图集过大。
+
+### Material / Shader
+
+- 优先使用项目已有 Shader，不随意引入新 Shader。
+- Material 实例在运行时通过代码创建，避免直接修改共享 Material。
+
+### Audio
+
+- 音效、背景音乐分目录存放。
+- 短音效优先使用 AudioClip + AudioSource 池，长音乐注意卸载。
+
+### 本地化资源
+
+- 资源按语言分目录，例如 `GameHFResource/CN/`、`GameHFResource/EN/`。
+- 多语言共用资源放在不带语言后缀的公共目录。
+
+---
+
+## 配置和数据规则
+
+- 优先修改源表、proto 或 schema，而不是生成输出。
+- 数据/schema 修改后，按项目流程重新生成。
+- 缺失的生成步骤记录到 [工作流清单](40-工作流清单.md) 或对应模块文档。
+- 详细规则见 [数据/配置框架](../modules/frameworks/数据配置框架.md)。
+
+---
+
+## 网络和 Protobuf 规则
+
+- `.proto` 是消息结构源头。
+- schema 修改后重新生成 C# 输出。
+- route/message-id 映射变化要和 schema 变化一起记录。
+- 详细规则见 [网络框架](../modules/frameworks/网络系统.md)。
+
+---
+
+## UI 框架规则
+
+UI 窗口、Prefab、层级、生命周期、事件释放和 UIMono 绑定规则见 [UI 框架](../modules/frameworks/UI窗口系统/README.md)。
+
+---
+
+## 文档编写规则
+
+- 每个 `.md` 文件末尾必须包含 **文档关联** 表。
+- 模块文档变更必须同步更新 [模块索引](../modules/模块索引.md)。
+- 不要在多个文档中重复维护同一份事实表。
+- 使用相对路径链接，确保在 GitHub / IDE / AI 工具中均可点击。
+- 代码示例必须可编译（或明确标注为伪代码）。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [rules/项目规则入口.md](项目规则入口.md) | 开发规则是项目规则入口索引的关键规则 |
+| [rules/10-架构说明.md](10-架构说明.md) | 程序集边界、依赖方向与 C# / Unity 规则互相引用 |
+| [modules/模块索引.md](../modules/模块索引.md) | 模块索引中的框架模块文档是开发规则的具体落地 |
+| [UI 框架](../modules/frameworks/UI窗口系统/README.md) | UI 命名、Prefab、层级等规则的具体说明 |
+| [网络框架](../modules/frameworks/网络系统.md) | 网络、Protobuf 规则的具体说明 |
+| [数据/配置框架](../modules/frameworks/数据配置框架.md) | 配置表、生成输出规则的具体说明 |
+| [实体系统](../modules/frameworks/实体系统/README.md) | Entity 编码规范与核心库访问规则落地 |
+| [通用框架](../modules/frameworks/通用框架/README.md) | 核心库范围与通用层规则落地 |
+| [对象池与运行时对象管理](../modules/frameworks/内存对象管理/README.md) | 对象池最佳实践落地 |
--- a/rules/30-模块登记规则.md
+++ b/rules/30-模块登记规则.md
@@ -0,0 +1,81 @@
+# 模块登记规则
+
+> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
+
+这里定义模块登记口径、状态含义和拆分规则。项目模块总入口统一维护在 [模块索引](../modules/模块索引.md)，本文件不重复维护模块清单。
+
+---
+
+## 口径
+
+- **核心框架**：支撑游戏运行的内部系统，例如实体系统、UI 窗口系统、事件系统、资源管理、对象池、场景管理、网络、配置生成。
+- **编辑器工具**：Unity Editor 内使用的生成器、Inspector、菜单、配置工具。
+- **业务参考**：外部实际项目的业务实现示例，仅作参考，不作为框架规范。
+
+---
+
+## 唯一事实来源
+
+模块清单、模块状态和模块入口统一维护在：
+
+```text
+modules/模块索引.md
+```
+
+其他规则文档只链接到模块索引或具体模块文档，不再复制模块表。
+
+---
+
+## 状态定义
+
+- **未识别**：还没有稳定线索。
+- **已识别**：已发现目录、类、资源或协议线索，但未完成梳理。
+- **初步梳理**：已写入核心路径、职责、数据流或使用规则，仍可能有待确认项。
+- **待验证**：文档已有结论，但需要通过 Unity、运行时、生成器或日志验证。
+- **已完成**：文档和验证都闭环，后续只需随代码演进维护。
+- **未发现实现**：按关键词和目录扫描后暂未发现实现，可作为规划占位。
+
+避免使用“已开始”作为状态；它不能说明到底是只建了文件，还是已经完成了一轮梳理。
+
+---
+
+## 登记规则
+
+- 新增核心框架模块时，登记到 [模块索引](../modules/模块索引.md) 的“核心框架”。
+- 新增编辑器工具时，登记到 [模块索引](../modules/模块索引.md) 的“编辑器工具”。
+- 新增业务参考时，登记到 `business-reference/` 下对应项目目录，不进入主模块索引。
+- 框架内部规则优先写进对应框架模块文档，例如 UI 写入 [UI 框架](../modules/frameworks/UI窗口系统/README.md)。
+- 模块开始有独立设计、进度、任务时，再拆 `modules/<module>/`。
+- 新增或拆分模块后，同步检查 [架构说明](10-架构说明.md) 和相关模块文档。
+
+---
+
+## 文档关系
+
+- `modules/模块索引.md`：项目模块总入口和事实表。
+- `modules/frameworks/*`：核心框架职责和框架使用规则。复杂模块拆分为文件夹，入口为 `README.md`。
+- `modules/<module>/业务参考总入口.md`：复杂模块稳定说明。
+- `modules/<module>/progress.md`：复杂模块阶段进度。
+- `modules/<module>/tasks.md`：复杂模块待办事项。
+- `rules/`：跨模块的通用规则、工作流、扫描范围和归档规则。
+- `business-reference/`：外部项目业务参考，不进入主索引。
+
+---
+
+## 相关文档
+
+- [模块索引](../modules/模块索引.md)：按分类整理的模块详细索引。
+- [架构说明](10-架构说明.md)：总体分层、程序集边界和依赖方向。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是模块登记规则的唯一事实来源 |
+| [rules/10-架构说明.md](10-架构说明.md) | 分类口径、依赖方向与架构说明互相影响 |
+| [rules/项目规则入口.md](项目规则入口.md) | 模块登记规则是项目规则入口索引的关键规则 |
+| [modules/frameworks/*.md](../modules/frameworks/) | 框架模块的状态、拆分规则需与登记规则一致 |
--- a/rules/40-工作流清单.md
+++ b/rules/40-工作流清单.md
@@ -0,0 +1,206 @@
+# 工作流清单
+
+> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
+
+---
+
+## 任务分类
+
+| 类型 | 特征 | 处理方式 |
+|---|---|---|
+| **简单修复** | 查询、解释、小范围修改、影响面低、用户已给出明确方式 | 直接处理，完成后验证并归档检查 |
+| **旧模块修复** | 已有框架模块的 bug 修复、逻辑补全、局部优化 | 读取模块文档，分析影响范围后修复，验证并归档 |
+| **Spec 任务** | 新增框架模块、调整架构/目录/依赖、批量修改迁移 | 走 OpenSpec 流程 |
+
+---
+
+## 简单修复流程
+
+1. 确认任务范围。
+2. 读取相关模块文档。
+3. 直接修改。
+4. 验证（如可运行测试、检查链接、预览 Markdown）。
+5. 执行归档检查。
+6. 简短说明结果。
+
+---
+
+## 旧模块修复流程
+
+1. 定位已有模块文档和相关内容。
+2. 简短分析影响范围和风险。
+3. 直接修复。
+4. 验证。
+5. 按 [50-归档规则.md](50-归档规则.md) 同步相关模块文档。
+
+---
+
+## Spec 任务流程
+
+大需求 / 新模块统一走 OpenSpec：
+
+1. 分析目标、影响范围、风险和依赖。
+2. 给出 2-3 个方案。
+3. 用户确认后创建 OpenSpec change。
+4. 生成 `proposal.md`、`design.md`、`tasks.md`。
+5. 实现。
+6. 验证。
+7. 归档并同步文档。
+
+详见 [60-新特性工作流.md](60-新特性工作流.md)。
+
+---
+
+## 开发流程
+
+### 1. 文档学习
+
+根据任务类型阅读对应模块文档：
+
+| 任务类型 | 必读文档 |
+|---------|---------|
+| UI 开发 | [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md) |
+| UI 界面设计 | [UI 界面拼接设计指南](../modules/frameworks/UI窗口系统/界面拼接.md) |
+| 相机控制 | [相机系统](../modules/frameworks/相机系统/README.md) |
+| 实体开发 | [实体系统](../modules/frameworks/实体系统/README.md) |
+| 事件使用 | [事件系统](../modules/frameworks/事件系统/README.md) |
+| 资源加载 | [资源管理](../modules/frameworks/资源管理/README.md) |
+
+### 2. 需求分析
+
+1. 明确需求：理解业务需求，确定需要实现的功能。
+2. 评估复杂度：判断是否需要核心库支持或扩展。
+3. 设计方案：规划代码结构和调用关系。
+
+### 3. 代码编写
+
+1. 在 `GameFunction/` 下按职责创建模块目录。
+2. 遵循编码规范，使用核心库提供的 API。
+3. 在 Unity 中测试功能正确性。
+
+### 4. 代码审查
+
+1. 自我检查：检查是否符合规范，是否有潜在问题。
+2. 团队审查：提交代码进行团队审查。
+3. 修复问题：根据审查意见修改代码。
+
+### 5. 集成测试
+
+1. 模块测试：测试单个模块功能。
+2. 集成测试：测试模块间交互。
+3. 回归测试：确保不影响现有功能。
+
+---
+
+## 文档变更联动检查
+
+修改任何文档前，确认它是否被其他文档引用：
+
+- 模块文档变更 → 同步检查模块索引、模块登记规则、架构说明。
+- 架构/目录变更 → 同步检查模块索引、相关模块 README、架构说明。
+- 规则文件变更 → 同步检查 `rules/项目规则入口.md`、`ai/AI接入入口.md`、`AGENTS.md`、`CLAUDE.md`、`RULES.md`。
+- spec/change 完成 → 同步更新相关模块 progress.md，并建立 `specs/openspec/` 归档。
+
+---
+
+## 提交前检查
+
+### 提交信息格式
+
+推荐格式：
+
+```text
+[模块][类型]: 简短描述
+
+- 详细说明 1
+- 详细说明 2
+```
+
+类型：`feat`、`fix`、`docs`、`refactor`、`test`、`chore`。
+
+模块名示例：`framework`、`entity`、`ui`、`event`、`resource`、`docs`、`rules`、`hooks`。
+
+示例：
+
+```text
+[entity][docs]: 补充实体池索引机制说明
+
+- 添加 onlyid -> entity 映射说明
+- 补充 HFBasicPool/HFEnemyPool/HFHumanityPool 边界
+```
+
+> **历史格式说明**：早期文档使用 `【操作原因】具体操作内容`（如 `【修复】xxx`）。该格式已弃用，新提交统一使用 `[module][type]: description`。
+
+### 分支管理
+
+| 分支名称 | 用途 |
+|----------|------|
+| `master` | 主分支，稳定版本 |
+| `develop` | 开发分支，日常开发 |
+| `feature/*` | 功能分支，开发新功能 |
+| `bugfix/*` | Bug 修复分支 |
+
+### Git 操作原则
+
+- 执行 Git 操作前确认当前操作路径是否正确。
+- 遵循项目既定的分支策略。
+- 使用语义化提交信息，清晰描述更改内容。
+- 重要功能提交前建议先创建分支进行测试。
+- 开发完成后及时推送到远程仓库。
+
+### 提交前检查项
+
+- [ ] 文档链接可点击且指向正确。
+- [ ] 文档关联表已更新。
+- [ ] 模块索引已同步（如新增/拆分了模块）。
+- [ ] 无拼写或明显格式错误。
+- [ ] 未引入外部项目专属内容。
+- [ ] 业务参考内容只出现在 `business-reference/` 下。
+
+---
+
+## 新增内容流程
+
+### 新增框架模块
+
+1. 在 [模块索引](../modules/模块索引.md) 中登记。
+2. 创建 `modules/frameworks/<module>.md`；复杂模块可拆分为 `modules/frameworks/<module>/README.md` 加子文档。
+3. 在 [架构说明](10-架构说明.md) 中补充依赖方向。
+4. 更新相关模块的文档关联表。
+
+### 新增编辑器工具
+
+1. 在 [模块索引](../modules/模块索引.md) 中登记。
+2. 创建 `modules/editor-tools/<tool>.md` 或补充汇总文档。
+3. 说明使用入口、生成输出、依赖项。
+
+### 新增业务参考
+
+1. 放入 `business-reference/<project>/`。
+2. 不进入 `modules/模块索引.md` 主索引。
+3. 在 `business-reference/<project>/业务框架映射接口.md` 中补充映射关系。
+
+---
+
+## 生成/构建流程
+
+若项目使用 StrayFog 框架配套的生成工具：
+
+- 优先修改源表、proto 或 schema，而不是生成输出。
+- 生成后检查输出目录，确认变更符合预期。
+- 缺失的生成步骤记录到对应模块文档。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [rules/项目规则入口.md](项目规则入口.md) | 工作流清单是项目规则入口索引的关键规则 |
+| [rules/50-归档规则.md](50-归档规则.md) | 归档规则与工作流清单互相引用 |
+| [rules/60-新特性工作流.md](60-新特性工作流.md) | 新特性工作流是工作流清单的延伸 |
+| [rules/20-开发规则.md](20-开发规则.md) | 提交格式与开发规则互相引用 |
+| [modules/模块索引.md](../modules/模块索引.md) | 新增模块登记需同步模块索引 |
+| [hooks/commit-check.ps1](../hooks/commit-check.ps1) | 提交检查脚本需与本文件格式一致 |
--- a/rules/50-归档规则.md
+++ b/rules/50-归档规则.md
@@ -0,0 +1,79 @@
+# 归档规则
+
+> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
+
+“归档”是指任务完成后，通过归档 hook / 归档检查判断是否需要把本次任务产生的长期信息同步回项目文档。
+
+归档 hook / 归档检查每个任务都要执行；归档不是写流水账，也不是每次都改所有文档。只更新和本次任务相关的文档。
+
+## 什么时候必须更新文档
+
+- 新增模块、拆分模块、调整模块职责。
+- 修改架构、目录结构、依赖方向。
+- 新增或改变生成流程。
+- 完成一个 spec、计划、功能阶段或里程碑。
+- 修改提交、构建、验证、发布规则。
+- 用户明确要求记录进度。
+- 旧模块修复改变了模块状态、关键流程、后续任务或长期约定。
+
+## 简单修复如何归档
+
+简单修复也必须执行归档 hook / 归档检查。
+
+如果只是查询、解释、无长期影响的小修，可以不改文档，但最终回复中应说明没有长期文档需要更新。
+
+如果简单修复改变了长期规则、模块状态或后续任务，需要补充对应文档。
+
+## 归档内容
+
+按需更新，并保持文档之间的关联关系一致：
+
+| 文档 | 更新时机 | 必须同步更新的关联文档 |
+|---|---|---|
+| `specs/` 或 `specs/openspec/<change>/` | 每个 Spec 任务完成后 | 相关模块 README/progress/tasks、架构说明、模块索引 |
+| `modules/<module>/业务参考总入口.md` | 模块职责/入口/结构变化时 | 模块索引、模块登记规则、架构说明、相关功能/框架模块文档 |
+| `modules/<module>/progress.md` | 阶段状态变化时 | 同一模块的 README、tasks、相关 spec |
+| `modules/<module>/tasks.md` | 下一步任务变化时 | 同一模块的 progress、plans（如涉及跨模块计划） |
+| `rules/10-架构说明.md` | 架构/目录/依赖方向变化时 | 模块索引、相关模块 README |
+| `rules/30-模块登记规则.md` | 新增/拆分/调整模块时 | 架构说明、模块索引、相关模块 README |
+| `rules/项目规则入口.md` | 项目规则入口内容变化时 | `ai/AI接入入口.md`、相关规则文件、`AGENTS.md`/`CLAUDE.md`/`RULES.md` |
+| `RULES.md` | 仅当重定向目标变化时 | 无需单独维护内容，保持指向 `rules/项目规则入口.md` |
+
+### 关联更新原则
+
+- **一处定义，多处引用**：如果一个事实出现在多个文档中，修改时必须同步所有地方。
+- **新增模块必须登记**：新增或拆分模块后，必须更新 `modules/模块索引.md`；如分类、状态定义或登记口径变化，再更新 `rules/30-模块登记规则.md`。
+- **已有模块变更必须留痕**：修改某个模块的入口、数据流或关键类时，同步更新该模块的 progress.md，并在相关 spec/change 中记录。
+- **避免孤儿文档**：不要创建没有从索引/注册表链接过去的模块或 spec 文档。
+
+## 归档格式
+
+建议每次记录：
+
+- 日期。
+- 本次目标。
+- 影响范围。
+- 已完成。
+- 未完成/TODO。
+- 验证情况。
+- 相关代码或文档链接。
+
+## 归档前检查
+
+- 不把临时讨论写成长久事实。
+- 不把所有模块细节写进总入口。
+- 不重复记录已经能从代码直接看出的内容。
+- 不记录密钥、账号、机器私有路径。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [rules/项目规则入口.md](项目规则入口.md) | 归档规则是项目规则入口索引的关键规则 |
+| [rules/40-工作流清单.md](40-工作流清单.md) | 任务分类、提交前检查与归档触发互相引用 |
+| [rules/60-新特性工作流.md](60-新特性工作流.md) | OpenSpec 归档流程与本文件归档规则互相引用 |
+| [specs/openspec/OpenSpec归档.md](../specs/openspec/OpenSpec归档.md) | OpenSpec 归档说明与本文件归档规则互相引用 |
--- a/rules/60-新特性工作流.md
+++ b/rules/60-新特性工作流.md
@@ -0,0 +1,138 @@
+# 大需求 / 新模块工作流
+
+> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
+
+---
+
+## 总体流程
+
+```text
+判断任务类型
+    |
+    ├── 简单修复 ────────────────→ 直接处理 → 归档检查
+    |
+    ├── 旧模块修复 ──────────────→ 分析后修复 → 归档检查
+    |
+    └── Spec 任务 ───────────────→ OpenSpec 流程
+            |
+            v
+    新模块 / 已有模块大改
+            |
+            v
+    实现 → 验证 → archive → 同步文档
+```
+
+---
+
+## 三种任务类型判定
+
+| 类型 | 判定标准 |
+|---|---|
+| **简单修复** | 查询、解释、小范围修改、用户已给出明确实现方式 |
+| **旧模块修复** | 已有框架模块的局部修复，不新增模块、不调整架构 |
+| **Spec 任务** | 新增框架模块、调整架构/目录/依赖、批量迁移、用户未明确方案 |
+
+---
+
+## 创建 OpenSpec Change
+
+当任务被判定为 Spec 任务时：
+
+1. 分析目标、影响范围、风险和依赖。
+2. 给出 2-3 个方案，让用户选择。
+3. 用户确认后创建 OpenSpec change：
+   - Claude Code：`/opsx:propose "需求描述"`
+   - CLI 通用：`openspec new change "change-name"`
+4. 生成 `proposal.md`、`design.md`、`tasks.md`。
+
+---
+
+## 新模块操作清单
+
+适用于在 StrayFog 框架知识库中新增一个框架模块，例如：
+
+- 新增“相机系统”模块文档
+- 新增“配置生成”模块文档
+- 新增“网络系统”模块文档
+
+操作步骤：
+
+1. 在 [模块索引](../modules/模块索引.md) 中登记模块。
+2. 创建模块文档 `modules/frameworks/<module>.md`（简单模块）或 `modules/frameworks/<module>/业务参考总入口.md`（复杂模块）。
+3. 如为复杂模块，创建 `progress.md` 和 `tasks.md`。
+4. 在 [架构说明](../rules/10-架构说明.md) 中补充该模块的分层位置和依赖方向。
+5. 更新相关模块的文档关联表。
+6. 如新增模块影响开发规则，更新 [开发规则](../rules/20-开发规则.md)。
+7. 按 design/tasks 完成内容编写。
+8. 验证文档链接、格式、关联表完整性。
+9. 归档 OpenSpec change。
+10. 同步更新模块索引、架构说明、相关模块文档。
+
+---
+
+## 已有模块大改操作清单
+
+适用于对已有框架模块进行较大调整，例如：
+
+- 重构实体系统文档结构
+- 调整 UI 窗口系统的生命周期描述
+- 合并/拆分对象池相关文档
+
+操作步骤：
+
+1. 读取现有模块文档和模块索引。
+2. 在 OpenSpec `design.md` 中说明变更原因、影响范围、新结构。
+3. 更新模块 `模块索引.md`。
+4. 更新模块 `progress.md`，记录本次变更。
+5. 更新模块 `tasks.md`，记录后续待办。
+6. 同步更新 [模块索引](../modules/模块索引.md)。
+7. 如影响架构或依赖方向，更新 [架构说明](../rules/10-架构说明.md)。
+8. 验证文档关联表一致性。
+9. 归档 OpenSpec change。
+
+---
+
+## 实现与验证
+
+- 按 `tasks.md` 逐项完成。
+- 每完成一项，在 `tasks.md` 中标记。
+- 验证方式包括：
+  - Markdown 链接检查
+  - 文档关联表完整性检查
+  - 人工阅读关键章节
+  - 运行 `hooks/archive-check.ps1` 检查关联文档
+
+---
+
+## 归档与联动更新
+
+归档 OpenSpec change 后，必须同步更新：
+
+- `specs/openspec/<change-name>/`
+- 相关模块 `模块索引.md`、`progress.md`、`tasks.md`
+- `rules/10-架构说明.md`（如涉及架构变化）
+- `modules/模块索引.md`（如新增模块）
+- `rules/30-模块登记规则.md`（如改变模块分类、状态定义或登记规则）
+
+---
+
+## 禁止事项
+
+- 不要在没有 OpenSpec 的情况下进行大模块新增或架构调整。
+- 不要把临时讨论写进长期文档。
+- 不要创建没有从模块索引链接过去的孤儿文档。
+- 不要把外部项目专属内容混入框架核心文档。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [rules/项目规则入口.md](项目规则入口.md) | 新特性工作流是项目规则入口索引的关键规则 |
+| [rules/40-工作流清单.md](40-工作流清单.md) | 工作流清单与新特性工作流互相引用 |
+| [rules/50-归档规则.md](50-归档规则.md) | 归档规则与新特性工作流互相引用 |
+| [specs/openspec/OpenSpec归档.md](../specs/openspec/OpenSpec归档.md) | OpenSpec 归档说明与新特性工作流互相引用 |
+| [modules/模块索引.md](../modules/模块索引.md) | 新增/拆分模块需同步模块索引 |
--- a/rules/70-项目设置.md
+++ b/rules/70-项目设置.md
@@ -0,0 +1,82 @@
+# AI 工具扫描范围
+
+> 本文件定义 AI 工具在正常分析项目时应跳过的目录和文件，以节省 token 并避免误读本地缓存/生成噪音。
+>
+> Codex 和 Claude Code 均遵循此规则。
+>
+> 返回主规则索引：[rules/项目规则入口.md](项目规则入口.md)
+
+---
+
+## 通用跳过模式
+
+| 模式 | 原因 |
+|------|------|
+| `.git/` | Git 版本控制元数据 |
+| `.vs/` | Visual Studio 本地缓存 |
+| `obj/` | .NET 编译中间输出目录 |
+| `bin/` | .NET 编译输出目录 |
+| `node_modules/` | Node.js 依赖目录 |
+| `*.log` | 运行时日志 |
+| `*.tmp` / `*.temp` | 临时文件 |
+| `Thumbs.db` / `.DS_Store` | 系统缩略图/缓存 |
+
+## Unity 项目跳过模式
+
+由于 StrayFog 是 Unity 框架，若知识库关联 Unity 工程，AI 分析时还应跳过：
+
+| 模式 | 原因 |
+|------|------|
+| `Library/` | Unity 本地缓存（资源导入、编译缓存、包缓存等），非项目源码 |
+| `Temp/` | Unity 运行时临时文件 |
+| `Logs/` | Unity 运行时日志 |
+| `UserSettings/` | Unity 用户本地偏好设置 |
+| `*.csproj` | 由 Unity 自动生成的项目文件 |
+| `*.sln` | 由 Unity 自动生成的解决方案文件 |
+| `Library/PackageCache/` | Unity Package Manager 缓存的第三方包源码 |
+| `HybridCLRData/` | HybridCLR 构建生成输出（DLL、桥接文件等） |
+
+## AI 工具本地状态
+
+| 模式 | 原因 |
+|------|------|
+| `.codex/` | Codex 本地 hooks 状态 |
+| `.claude/` | Claude Code 本地命令/技能状态（除 `config` 外） |
+
+## 文档仓库跳过模式
+
+本仓库本身以 Markdown 文档为主，以下文件通常无需 AI 全文读取：
+
+| 模式 | 原因 |
+|------|------|
+| 图片、音频、视频等二进制资源 | 非文本内容 |
+| `.claude/` 中的本地 skill/hook 状态 | 工具私有状态 |
+| `__pycache__/` | Python 缓存 |
+
+## 例外情况
+
+当任务明确要求分析**构建问题**或**生成流程问题**时，可以按需读取以下目录中的特定文件：
+
+- `HybridCLRData/` — 检查 HybridCLR 构建输出、DLL 生成结果或 AOT 桥接错误
+- `Library/PackageCache/` — 检查特定包的版本或源码（仅限调试包相关问题时）
+- `*.csproj` / `*.sln` — 检查项目引用或编译配置问题
+
+> 例外读取后，应在分析结论中说明读取了哪些缓存/生成文件以及原因。
+
+## 相关规则
+
+- [rules/项目规则入口.md](项目规则入口.md) — 项目规则总索引
+- [00-项目概览.md](00-项目概览.md) — 项目概览与重要目录说明
+- [20-开发规则.md](20-开发规则.md) — 开发规则（含生成文件约束）
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [rules/项目规则入口.md](项目规则入口.md) | 项目设置是项目规则入口索引的关键规则 |
+| [rules/00-项目概览.md](00-项目概览.md) | 扫描范围中的目录说明与项目概览互相引用 |
+| [rules/20-开发规则.md](20-开发规则.md) | 生成文件约束、例外读取与扫描范围互相引用 |
--- a/rules/项目规则入口.md
+++ b/rules/项目规则入口.md
@@ -0,0 +1,252 @@
+# UnityAI - 项目规则入口
+
+> 本文件是 UnityAI / StrayFog 框架知识库的 **项目规则入口**。
+>
+> 所有 AI / IDE 工具先通过 [ai/AI接入入口.md](../ai/AI接入入口.md) 接入项目，再按任务范围读取本文件和下方链接的具体文档。
+>
+> 不要把项目规则重复写在你的系统提示里；直接引用本文件和 `rules/` 下的规则文件。
+
+---
+
+## AI 快速启动
+
+1. 确认已读取 [AI 工具接入入口](../ai/AI接入入口.md)。
+2. **读取本文件**（`rules/项目规则入口.md`）。
+3. 根据任务范围，从下方的 **规则索引**、**项目知识入口**、**Spec 索引** 中选择相关文档读取。
+4. **简单修复**：直接开始处理，完成后简短说明结果。
+5. **旧模块修复**：定位已有模块文档和相关内容，简短分析后直接修复。
+6. **大需求 / 新模块**：新增框架模块、架构调整、文档重组等，先给出 2-3 个方案，用户确认后走 **OpenSpec 流程**。
+7. **所有任务结束都执行归档 hook / 归档检查**，按影响范围决定是否更新长期文档。
+
+---
+
+## 项目概况
+
+- **项目名**：UnityAI
+- **副标题**：StrayFog 框架文档中心
+- **目标读者**：使用 StrayFog 框架的 AI 工具、业务开发人员、框架维护人员
+- **核心内容**：StrayFog 框架架构说明、核心功能使用指南、开发规范、开发流程、项目管理规范
+- **仓库结构**：
+  - `ai/` / `rules/` / `modules/` / `hooks/`：AI 规则与项目知识库（AI 优先读取）
+  - `modules/frameworks/`：核心框架模块文档（按模块拆分为文件夹）
+  - `business-reference/`：外部实际项目业务参考（与框架核心分离）
+- **技术栈**：Unity、C#、StrayFog 框架
+- **文档语言**：中文
+
+---
+
+## 语言与工作方式
+
+- **默认使用中文回答用户**。
+- **代码、类名、方法名、路径、命令、API 名称保持英文原文**。
+- 简单修复直接处理，简短说明结果。
+- 旧模块修复先定位已有模块文档和相关内容，简短分析风险后直接修复。
+- 大需求 / 新模块先分析目标、影响范围、风险和依赖，给出 2-3 个方案，用户确认后走 OpenSpec。
+- 如果用户明确说“直接实现”“按你判断来”，采用保守方案继续执行。
+- 所有任务结束都执行归档 hook / 归档检查；不把无长期价值的流水账写入文档。
+
+---
+
+## 规则索引
+
+`rules/` 下的文件是项目长期规则，按以下顺序按需读取：
+
+| 文件 | 用途 |
+|---|---|
+| [00-项目概览.md](00-项目概览.md) | 项目用途、文档结构、核心子系统 |
+| [10-架构说明.md](10-架构说明.md) | 框架结构、目录职责、依赖方向、程序集边界 |
+| [20-开发规则.md](20-开发规则.md) | C# 规范、Unity 资源规则、文档编写规则 |
+| [30-模块登记规则.md](30-模块登记规则.md) | 模块登记口径、状态定义、文档拆分规则 |
+| [40-工作流清单.md](40-工作流清单.md) | 任务分类、修复流程、Spec 流程、提交前检查 |
+| [50-归档规则.md](50-归档规则.md) | 归档时机、归档内容、关联更新原则 |
+| [60-新特性工作流.md](60-新特性工作流.md) | 大需求 / 新模块如何通过 OpenSpec 流程推进 |
+| [70-项目设置.md](70-项目设置.md) | AI 工具扫描范围、跳过目录、例外情况 |
+
+---
+
+## 项目知识入口
+
+项目框架、核心功能、编辑器工具的总入口统一维护在 [modules/模块索引.md](../modules/模块索引.md)。
+
+规则文件不重复维护模块清单；新增、拆分、改名模块时，以 `modules/模块索引.md` 为唯一事实来源，并按 [30-模块登记规则.md](30-模块登记规则.md) 的口径登记。
+
+常用框架规则入口：
+
+- [实体系统](../modules/frameworks/实体系统/README.md)：实体基类、System-Model 架构、实体池、生命周期。
+- [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md)：UIWindow、Prefab、层级、生命周期和事件释放。
+- [事件系统](../modules/frameworks/事件系统/README.md)：CTC/STC 事件、派发链路、监听规范。
+- [资源管理](../modules/frameworks/资源管理/README.md)：AssetBundle、语言资源、图集、加载规则。
+- [对象池](../modules/frameworks/内存对象管理/README.md)：类实例池、行为对象池、实体池、RT 展示对象。
+
+---
+
+## Spec / Plan 索引
+
+| 类型 | 文档 |
+|---|---|
+| Spec 索引 | [specs/Spec索引.md](../specs/Spec索引.md) |
+| OpenSpec 归档 | [specs/openspec/OpenSpec归档.md](../specs/openspec/OpenSpec归档.md) |
+| 计划进度 | [plans/](../plans/) |
+
+---
+
+## 任务流转
+
+### 简单修复
+
+- 查询、解释、定位问题。
+- 小范围、明确、影响面低的修改。
+- 用户已给出明确实现方式。
+
+处理：直接开始修复或回答，完成后验证，并执行归档 hook / 归档检查。
+
+### 旧模块修复
+
+- 项目中已有模块的 bug 修复、逻辑补全、局部优化。
+- 影响范围主要集中在一个已有功能或框架模块。
+- 不新增大模块，不调整总体架构。
+
+处理：读取相关模块文档和代码/内容，简短分析影响范围后直接修复；完成后验证，并按 [50-归档规则.md](50-归档规则.md) 执行归档 hook / 归档检查。
+
+### Spec 任务
+
+- 新增大功能或新模块。
+- 调整架构、目录职责、依赖方向。
+- 调整文档结构、生成流程。
+- 涉及多个系统的批量修改、删除、迁移。
+- 用户没有明确方案，需要先权衡。
+
+处理：按 [40-工作流清单.md](40-工作流清单.md) 和 [60-新特性工作流.md](60-新特性工作流.md) 走 OpenSpec。
+
+---
+
+## OpenSpec 工作流（大需求 / 新模块）
+
+1. 分析目标、影响范围、风险和依赖。
+2. 给出 2-3 个方案，让用户选择。
+3. 用户确认后创建 OpenSpec change：
+   - Claude Code：`/opsx:propose "需求描述"`
+   - CLI 通用：`openspec new change "change-name"`
+4. 生成 `proposal.md`、`design.md`、`tasks.md`。
+5. 判断是 **新模块** 还是 **已有模块的大改**：
+   - 新模块：创建模块文档、登记模块、补充架构。
+   - 已有模块的大改：更新模块 progress.md、tasks.md，记录变更。
+6. 按 design/tasks 实现代码、资源或配置变更。
+7. 验证。
+8. 归档 OpenSpec change：
+   - Claude Code：`/opsx:archive`
+   - CLI 通用：`openspec archive "change-name"`
+9. 按 [50-归档规则.md](50-归档规则.md) 同步到项目文档：
+   - `specs/openspec/<change-name>/`
+   - 相关模块 `模块索引.md`、`progress.md`、`tasks.md`
+   - `10-架构说明.md`（如涉及架构变化）
+   - `modules/模块索引.md`（如新增模块）
+   - `30-模块登记规则.md`（如改变模块分类、状态定义或登记规则）
+
+---
+
+## 扫描范围
+
+正常分析项目时，**默认跳过**以下目录和文件以节省 token：
+
+- `Library/`
+- `Temp/`
+- `Logs/`
+- `UserSettings/`
+- `.vs/`
+- `*.csproj`
+- `*.sln`
+- `.codex/`（本地 hooks 状态）
+- `.claude/`（本地 commands/skills 状态）
+- `Library/PackageCache/`
+- `obj/`
+- `bin/`
+- 图片、音频、模型等二进制资源
+
+详见 [70-项目设置.md](70-项目设置.md)。
+
+---
+
+## 关键约束
+
+- **一处定义，多处引用**：如果一个事实出现在多个文档中，修改时必须同步所有地方。
+- 优先修改源头文档，不要手动同步复制多份内容。
+- 运行时代码不引用 Editor 程序集。
+- UI 变更遵循 [UI 框架](../modules/frameworks/UI窗口系统/README.md)。
+- 事件变更遵循 [事件框架](../modules/frameworks/事件系统/README.md)。
+- 资源变更遵循 [资源管理](../modules/frameworks/资源管理/README.md)。
+
+---
+
+## 归档规则摘要
+
+所有任务完成后都执行归档 hook / 归档检查。归档不是写流水账，只更新和本次任务相关的长期文档。
+
+简单修复如果没有改变长期规则、模块状态、架构或后续任务，可以只在最终回复中说明无需文档更新；旧模块修复和 Spec 任务按影响范围同步相关模块文档。
+
+核心原则：**一处定义，多处引用**。
+
+详见 [50-归档规则.md](50-归档规则.md)。
+
+---
+
+## 文档变更联动原则
+
+修改任何文档前，先确认它是否被其他文档引用：
+
+- 模块文档变更 → 同步检查模块索引、模块登记规则、架构说明。
+- 架构/目录变更 → 同步检查模块索引、相关模块 README、架构说明。
+- 规则文件变更 → 同步检查本文件、`ai/AI接入入口.md`、`AGENTS.md`、`CLAUDE.md`、`RULES.md`。
+- spec/change 完成 → 同步更新相关模块 progress.md，并建立 `specs/openspec/` 归档。
+
+## 归档触发
+
+文档关联和归档触发逻辑统一放在 `hooks/`：
+
+| 触发方式 | 命令/路径 | 说明 |
+|---|---|---|
+| Codex Stop hook | `.codex/hooks/archive-reminder.ps1` | 每次任务结束自动调用 `hooks/archive-check.ps1` 输出建议 |
+| Claude Code 手动 | `/opsx:archive-check` | 手动触发归档检查 |
+| OpenSpec 自动 | `/opsx:archive` | Spec 流程归档完成后自动调用 `hooks/archive-check.ps1` |
+| 手动脚本 | `hooks/archive-check.ps1` | 直接运行 PowerShell 脚本 |
+
+**重要**：以上触发只输出建议，不会自动修改任何文档。最终是否更新关联文档，需要用户确认。
+
+详见 [hooks/Hook共享层.md](../hooks/Hook共享层.md)。
+
+---
+
+## 接入新 AI 工具时
+
+如果你是新接入的 AI 工具，只需要：
+
+1. 读取 [ai/AI接入入口.md](../ai/AI接入入口.md)。
+2. 再读取本文件（`rules/项目规则入口.md`）。
+3. 按任务范围读取本文件索引中的具体规则/模块/spec 文档。
+4. 遵循本文件的工作方式、扫描范围、关键约束和归档规则。
+
+不同 AI / IDE 的默认入口、hook 适配方式统一维护在 `ai/AI接入入口.md`。项目根目录的 `AGENTS.md`、`CLAUDE.md`、`RULES.md` 都是指向 `ai/AI接入入口.md` 的薄入口。
+
+---
+
+## 文档关联
+
+> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
+
+| 文档 | 关联原因 |
+|---|---|
+| [ai/AI接入入口.md](../ai/AI接入入口.md) | AI 接入入口引用本项目规则入口 |
+| [AGENTS.md](../AGENTS.md) | Codex 入口通过 ai/AI接入入口.md 引用本文件 |
+| [CLAUDE.md](../CLAUDE.md) | Claude Code 入口通过 ai/AI接入入口.md 引用本文件 |
+| [RULES.md](../RULES.md) | 兼容重定向入口通过 ai/AI接入入口.md 引用本文件 |
+| [rules/00-项目概览.md](00-项目概览.md) | 项目概况在本文档中被引用 |
+| [rules/10-架构说明.md](10-架构说明.md) | 架构说明在本文档中被引用 |
+| [rules/20-开发规则.md](20-开发规则.md) | 开发规则在本文档中被引用 |
+| [rules/30-模块登记规则.md](30-模块登记规则.md) | 模块登记规则在本文档中被引用 |
+| [rules/40-工作流清单.md](40-工作流清单.md) | 工作流清单在本文档中被引用 |
+| [rules/50-归档规则.md](50-归档规则.md) | 归档规则在本文档中被引用 |
+| [rules/60-新特性工作流.md](60-新特性工作流.md) | 大需求/新模块工作流在本文档中被引用 |
+| [rules/70-项目设置.md](70-项目设置.md) | 扫描范围规则在本文档中被引用 |
+| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是本文档引用的项目知识入口 |
+| [specs/Spec索引.md](../specs/Spec索引.md) | Spec 索引在本文档中被引用 |
+| [hooks/Hook共享层.md](../hooks/Hook共享层.md) | 归档触发机制在本文档中被引用 |
--- a/specs/Spec模板.md
+++ b/specs/Spec模板.md
@@ -0,0 +1,75 @@
+# Spec 标题
+
+## 文档关联
+
+- **相关规则**：
+  - [归档规则](../rules/50-归档规则.md)
+  - [大需求 / 新模块工作流](../rules/60-新特性工作流.md)
+- **相关模块**：
+  - `[<功能模块>]`（示例路径：`../modules/features/<feature-name>.md`）
+  - `[<框架模块>]`（示例路径：`../modules/frameworks/<framework-name>.md`）
+
+> 当本 spec 发生变更时，必须检查并同步更新相关模块文档和规则。
+
+## 背景
+
+TODO：为什么做这件事？当前有什么问题？
+
+## 目标
+
+- TODO
+
+## 非目标
+
+- TODO
+
+## 影响范围
+
+- 代码：
+- 资源：
+- 数据/配置：
+- 文档：
+- 关联模块：
+  - `[<功能模块>]`（示例路径：`../modules/features/<feature-name>.md`）
+  - `[<框架模块>]`（示例路径：`../modules/frameworks/<framework-name>.md`）
+
+## 方案
+
+### 方案 A
+
+- 优点：
+- 缺点：
+
+### 方案 B
+
+- 优点：
+- 缺点：
+
+## 选定方案
+
+TODO
+
+## 任务
+
+- [ ] TODO
+
+## 验证
+
+- [ ] TODO
+
+## 变更记录
+
+| 日期 | 变更内容 | 变更人 |
+|---|---|---|
+| YYYY-MM-DD | 初始版本 | - |
+
+## 归档
+
+完成后必须同步更新（详见 [归档规则](../rules/50-归档规则.md)、[大需求 / 新模块工作流](../rules/60-新特性工作流.md)）：
+
+- [ ] `specs/openspec/<change-name>/`
+- [ ] 相关模块 `模块索引.md`
+- [ ] 相关模块 `progress.md`
+- [ ] 相关模块 `tasks.md`
+- [ ] `rules/10-架构说明.md`（如涉及架构变化）
+- [ ] `rules/30-模块登记规则.md`（如新增模块）
--- a/specs/Spec索引.md
+++ b/specs/Spec索引.md
@@ -0,0 +1,57 @@
+# Spec 索引
+
+大需求、新模块、架构调整、生成流程调整等 Spec 任务在这里沉淀方案和结果。
+
+## 使用规则
+
+- 简单修复和旧模块修复不需要创建 spec，按规则直接处理并执行归档检查。
+- 大需求 / 新模块使用 OpenSpec 流程：
+  - Claude Code 命令 `/opsx:propose "需求描述"` 创建 change。
+  - 生成 `proposal.md`、`design.md`、`tasks.md`。
+  - `/opsx:apply` 执行实现。
+  - `/opsx:archive` 归档到 `openspec/changes/archive/`。
+- OpenSpec 归档后，再按 [归档规则](../rules/50-归档规则.md) 同步到项目既有模块文档：
+  - `specs/openspec/<change-name>/`
+  - `modules/<module>/业务参考总入口.md`、`progress.md`、`tasks.md`
+  - `rules/10-架构说明.md`、`rules/30-模块登记规则.md`
+- 如果不用 OpenSpec，也可复制 [Spec模板.md](Spec模板.md) 创建普通 spec。
+
+## OpenSpec 归档
+
+大需求 / 新模块经 OpenSpec 流程后，长期归档优先放在：
+
+```text
+specs/openspec/
+```
+
+详见 [specs/openspec/OpenSpec归档.md](openspec/OpenSpec归档.md)。
+
+## 命名建议
+
+普通 spec 文件：
+
+```text
+YYYY-MM-DD-feature-name.md
+```
+
+OpenSpec change：
+
+```text
+kebab-case-change-name
+```
+
+## 文档关联
+
+- [工作流清单](../rules/40-工作流清单.md)：任务分类、修复流程、Spec 流程、提交前检查、生成/构建流程。
+- [大需求 / 新模块工作流](../rules/60-新特性工作流.md)：新增/已有功能判断、模块登记、联动更新检查。
+- [归档规则](../rules/50-归档规则.md)：归档时机、内容、格式和关联更新原则。
+- [模块索引](../modules/模块索引.md)：项目功能、框架、编辑器工具模块总览。
+
+## 同步要求
+
+OpenSpec change 完成后，必须将结论同步到项目模块文档：
+
+- `specs/openspec/<change-name>/` — OpenSpec 归档目录
+- `modules/<module>/业务参考总入口.md`、`progress.md`、`tasks.md` — 相关模块文档
+- `rules/10-架构说明.md`（如涉及架构变化）
+- `rules/30-模块登记规则.md`（如新增模块）
--- a/specs/openspec/OpenSpec归档.md
+++ b/specs/openspec/OpenSpec归档.md
@@ -0,0 +1,100 @@
+# OpenSpec 归档目录
+
+本目录用于存放大需求、新模块、架构调整、生成流程调整等 Spec 任务经 OpenSpec 流程沉淀后的长期文档。
+
+## 目录结构
+
+```text
+specs/openspec/
+├── 模块索引.md              # 本文件
+├── <change-name>/         # 单个 Spec 任务的归档
+│   ├── proposal.md        # 需求背景与目标
+│   ├── design.md          # 设计方案
+│   └── tasks.md           # 实现任务与验证
+└── ...
+```
+
+## OpenSpec 工作目录
+
+OpenSpec CLI 的活跃工作目录位于项目根目录：
+
+```text
+openspec/
+├── changes/               # 进行中的 change
+├── changes/archive/       # OpenSpec 自身归档的 change
+└── specs/                 # OpenSpec 管理的 spec
+```
+
+## 工作流
+
+### 简单修复 / 旧模块修复
+
+- 直接修改代码/资源。
+- 简短说明结果。
+- 执行归档检查；没有长期信息变化时，不归档到本目录。
+
+### 大需求 / 新模块
+
+1. 使用 Claude Code 命令 `/opsx:propose "需求描述"` 创建 change。
+2. 按 OpenSpec 流程生成 `proposal.md`、`design.md`、`tasks.md`。
+3. 使用 `/opsx:apply` 执行实现。
+4. 实现完成后使用 `/opsx:archive` 归档。
+5. **同时**把结论同步到本目录和项目既有模块文档：
+   - `specs/openspec/<change-name>/`
+   - `modules/<module>/业务参考总入口.md`
+   - `modules/<module>/progress.md`
+   - `modules/<module>/tasks.md`
+   - `rules/10-架构说明.md`（如涉及架构变化）
+   - `modules/模块索引.md`（如新增模块）
+   - `rules/30-模块登记规则.md`（如改变模块分类、状态定义或登记规则）
+
+## 文档关联
+
+- [工作流清单](../../rules/40-工作流清单.md)：任务分类、修复流程、Spec 流程、提交前检查、生成/构建流程。
+- [大需求 / 新模块工作流](../../rules/60-新特性工作流.md)：新增/已有功能判断、模块登记、联动更新检查。
+- [归档规则](../../rules/50-归档规则.md)：归档时机、内容、格式和关联更新原则。
+- [模块索引](../../modules/模块索引.md)：项目功能、框架、编辑器工具模块总览。
+
+## 同步要求
+
+OpenSpec change 完成后，必须将结论同步到项目模块文档：
+
+- `specs/openspec/<change-name>/` — OpenSpec 归档目录
+- `modules/<module>/业务参考总入口.md`、`progress.md`、`tasks.md` — 相关模块文档
+- `rules/10-架构说明.md`（如涉及架构变化）
+- `modules/模块索引.md`（如新增模块）
+- `rules/30-模块登记规则.md`（如改变模块分类、状态定义或登记规则）
+
+## 与项目既有规则的关系
+
+- 项目既有规则入口：`RULES.md`、`AGENTS.md`、`rules/`
+- OpenSpec 负责大需求 / 新模块的 spec-driven 流程。
+- 项目既有文档负责长期模块知识、架构说明和任务跟踪。
+- 大需求 / 新模块完成后，OpenSpec 归档和项目归档都需要做。
+
+## 命令速查
+
+```bash
+# 查看进行中的 changes
+openspec list
+
+# 查看 specs
+openspec list --specs
+
+# 创建新 change
+openspec new change "change-name"
+
+# 查看 change 状态
+openspec status --change "change-name"
+
+# 归档 change
+openspec archive "change-name"
+```
+
+Claude Code 命令：
+
+- `/opsx:propose "需求描述"` — 创建并生成 change 文档
+- `/opsx:apply` — 按 design/tasks 实现
+- `/opsx:archive` — 归档完成
+- `/opsx:explore` — 探索性分析
+- `/opsx:sync` — 同步 specs