【整合】框架使用规则

2026-07-10 17:50:20 +08:00
parent db0143be83
commit 001d9e5ef5
45 changed files with 1716 additions and 4062 deletions
--- a/rules/00-项目概览.md
+++ b/rules/00-项目概览.md
@@ -1,119 +1,57 @@
 # 项目概览

-> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
+## 定位

-## 摘要
+`UnityAI` 是 StrayFog 框架的通用知识库和工作流标准，服务 AI 工具、业务开发人员与框架维护人员。本仓库不保存完整游戏业务代码，具体结论必须结合接入的 Unity 项目验证。

-`UnityAI` 是 **StrayFog 框架文档中心**，用于沉淀 StrayFog 框架的架构设计、核心功能使用规范、开发流程和项目管理规则。
-
-本仓库本身不包含游戏业务代码，而是一个**面向 AI 工具与人工开发者的知识库**。AI 工具通过 ai/rules/modules/ 下的规则与模块文档快速理解框架；人工开发者可以通过 `modules/frameworks/` 下的框架模块文档和 `rules/` 下的规则文档学习使用。
-
- **项目名**：UnityAI
- **副标题**：StrayFog 框架文档中心
- **目标读者**：AI 工具、业务开发人员、框架维护人员
+- **通用标准仓库**：`UnityAI`
+- **当前主要验证对象**：`CrystalBattle_Client`
 - **文档语言**：中文
- **适用项目**：GiftGameX、OnlineGame 等使用 StrayFog 框架的项目
+- **适用范围**：使用 StrayFog 框架的 Unity 项目

---
+CrystalBattle_Client 用于验证目录、接口、生成流程和平台行为，但项目专有实现不应被写成所有项目都必须遵守的框架规则。

-## 重要目录
+## 目录

 | 目录 | 用途 |
-|------|------|
-| `modules/frameworks/` | 核心框架模块文档：实体、UI、事件、资源、对象池等。 |
-| `rules/` | 项目长期规则：工作方式、扫描范围、任务流程、归档规则。 |
-| `modules/` | 项目知识总入口：框架模块、核心功能、编辑器工具。 |
-| `hooks/` | 共享 hook：归档检查、提交检查、文档关联同步。 |
-| `specs/` | 大需求 / 新模块的 OpenSpec 归档。 |
-| `modules/frameworks/编辑器工具/UI工具/` | UI 预制体 JSON 转换工具脚本。 |
-| `business-reference/` | 外部实际项目业务参考，与框架核心分离。 |
+|---|---|
+| `ai/` | AI 工具统一接入入口 |
+| `rules/` | 架构、开发、工作流、文档同步和扫描规则 |
+| `modules/frameworks/` | StrayFog 模块架构与使用文档 |
+| `business-reference/` | 外部项目业务案例，只作参考 |
+| `hooks/` | 只读工作流检查和提交检查 |
+| `Tools/` | MCP Server 等可执行工具 |

---
-
-## 核心子系统
-
-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. 读取 [AI 接入入口](../ai/AI接入入口.md)。
+2. 读取 [项目规则入口](项目规则入口.md) 和 [工作流清单](40-工作流清单.md)。
+3. 从 [模块索引](../modules/模块索引.md) 读取任务相关模块。
+4. 读取目标 Unity 项目的真实代码、Prefab、配置和日志后再得出结论。

 ### 人工开发者

-1. 新成员从 [开发规则](20-开发规则.md) 开始。
-2. 了解架构看 [架构说明](10-架构说明.md) 和 [通用框架/框架架构](../modules/frameworks/通用框架/框架架构.md)。
-3. 使用具体系统看 `modules/frameworks/` 下对应框架模块。
-4. 遇到问题看 [开发规则/常见问题](20-开发规则.md#常见问题)。
+1. 从 [架构说明](10-架构说明.md) 了解源码和生成代码边界。
+2. 从 [开发规则](20-开发规则.md) 了解编码、资源和生成约束。
+3. 从具体模块 README 和使用指南查找接口与数据流。

---
+## 文档原则

-## 关键约束
-
- `ai/rules/modules/` 是 StrayFog 框架知识的唯一事实来源；旧中文教程内容已迁移合并至此。
- 修改 `modules/` 中模块文档后，必须同步更新 `modules/模块索引.md` 和相关规则文件。
- `business-reference/` 中的内容来自外部实际项目，仅作参考，不作为 StrayFog 框架规范。
- 不要把项目规则复制进系统提示或 AI 工具私有目录。
-
---
+- `rules/` 保存跨模块标准。
+- `modules/` 保存模块长期知识。
+- 一个事实只在一处完整定义，其他文档通过链接引用。
+- `business-reference/` 不能反向定义框架规范。
+- 当前工程的临时排错过程不进入长期文档。

 ## 文档关联

-> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
-
 | 文档 | 关联原因 |
 |---|---|
-| [rules/项目规则入口.md](项目规则入口.md) | 项目概览是项目规则入口引用的核心信息 |
-| [rules/10-架构说明.md](10-架构说明.md) | 重要顶层目录与总体分层、程序集边界相关 |
-| [rules/20-开发规则.md](20-开发规则.md) | 生成内容约束与开发规则互相引用 |
-| [rules/70-项目设置.md](70-项目设置.md) | 扫描范围、跳过目录与项目概况中的目录说明相关 |
-| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是项目知识总入口 |
+| [项目规则入口](项目规则入口.md) | 项目规则总入口 |
+| [架构说明](10-架构说明.md) | 代码分层和项目边界 |
+| [模块索引](../modules/模块索引.md) | 框架知识总入口 |
+| [项目设置](70-项目设置.md) | 扫描范围和忽略目录 |
--- a/rules/10-架构说明.md
+++ b/rules/10-架构说明.md
@@ -1,144 +1,67 @@
 # 架构说明

-> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
-
-项目文档按三类组织：**核心运行时**、**编辑器工具**、**业务参考**。详细模块索引见 [模块索引](../modules/模块索引.md)。
-
---
-
-## 分类口径
-
- **核心运行时**：支撑游戏运行的内部系统，例如实体、UI、网络、资源、事件、场景、对象池。
- **编辑器工具**：Unity Editor 内使用的生成器、Inspector、菜单、配置工具。
- **业务参考**：外部实际项目的业务实现示例，仅作参考，不作为框架规范。
-
---
+本文档定义 StrayFog 项目的代码分层、真实源码位置与生成边界。具体项目路径不同的时候，以项目配置和生成器实现为准。

 ## 总体分层

 ```text
-┌─────────────────────────────────────────────────────────────┐
-│                     StrayFog Framework                      │
-├─────────────────────────────────────────────────────────────┤
-│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────┐  │
-│  │   GameGeneral    │  │     GameHF       │  │    Core   │  │
-│  │   通用工具层     │  │   业务核心层     │  │  基础框架 │  │
-│  └────────┬─────────┘  └────────┬─────────┘  └─────┬─────┘  │
-├───────────┼─────────────────────┼──────────────────┼─────────┤
-│           │                     │                  │         │
-│           ▼                     ▼                  ▼         │
-│  ┌─────────────────────────────────────────────────────┐    │
-│  │                   Unity Engine                      │    │
-│  └─────────────────────────────────────────────────────┘    │
-└─────────────────────────────────────────────────────────────┘
+游戏业务（GameFunction / GameMono / GameHFResource）
+                    |
+                    v
+生成后的运行时框架（CopyToHF / GameGeneral）
+                    |
+                    v
+StrayFog Core / Unity Engine / 第三方插件
+
+StrayFog Editor / CopyToX --------------> 生成运行时代码与资源
 ```

-### 各层职责
+## 源码与生成结果

-| 层级 | 路径 | 职责描述 |
-|------|------|---------|
-| **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 桥接 |
+| `Assets/StrayFog/Core` | 直接维护的框架运行时源码 | 按框架需求直接修改并构建 `StrayFogCore` |
+| `Assets/StrayFog/Editor` | Editor 工具与生成器源码 | 直接修改；运行时代码不得反向依赖 |
+| `Assets/StrayFog/Editor/CopyToX/CopyToHF` | `ESF_` 热更框架源码 | 框架修改的主要源头，修改后执行 CopyToX |
+| `Assets/StrayFog/Editor/CopyToX/CopyToGeneral` | General 层生成源码 | 修改后执行 CopyToX |
+| `Assets/Game/GameHFScripte/CopyToHF` | CopyToX 生成的 `HF_` 运行时代码 | 禁止手改，只检查生成差异 |
+| `Assets/Game/GameGeneralScripte/CopyToGeneral` | CopyToX 生成的 General 代码 | 禁止手改，只检查生成差异 |
+| `Assets/Game/GameHFScripte/GameFunction` | 项目热更业务代码 | 业务需求直接修改 |
+| `Assets/Game/GameMono` | 项目 Mono 桥接和组件代码 | 直接修改并构建 `SFMono` |
+| `Assets/Game/GameHFResource` | Prefab、图集、配置和 AssetBundle 资源 | 通过 Unity 或已有工具修改并验证序列化结果 |
+| `Assets/Editor/Command` | 项目 Editor/MCP 工具 | 直接修改，在 Unity 主线程验证 Editor API |

---
+CopyToX 会删除并重新生成目标子目录，同时把 `ESF_` 标记转换为 `HF_`。因此目标目录中的手工改动会丢失，也不能作为下一次生成的源码。
+
+## 程序集
+
+| 程序集 | 主要职责 |
+|---|---|
+| `StrayFogCore` | StrayFog 基础运行时 |
+| `SFEditor` | StrayFog Editor 工具 |
+| `GameGeneral` | 生成后的通用运行时层 |
+| `GameHF` | 热更框架与业务代码 |
+| `SFMono` | MonoBehaviour、UIMono 和桥接层 |
+
+项目接入第三方插件时，以 asmdef 依赖为准，不把第三方源码复制为框架规则。

 ## 依赖方向

-```text
-业务功能（PVE、PVP、背包、商店等，放在外部业务参考层）
-        |
-        v
-核心运行时（GameRoot、GameEntity、UIWindowMgr、SceneManager、Network、AssetBundle、Event 等）
-        |
-        v
-通用框架 / 第三方插件（StrayFog Core、Spine、DOTween 等）
-        |
-        v
-Unity Engine / .NET Runtime
+- 业务代码可以依赖公开框架入口和通用层。
+- 业务调用优先通过 `HFFunCatalogue` 等项目统一入口，不绕过封装直接依赖内部单例。
+- Core 和生成后的框架运行时不能依赖具体业务模块。
+- 运行时代码不能依赖 Editor 程序集。
+- Editor 工具可以读取或生成运行时代码和资源，但生成结果不能成为生成器的反向依赖。

-编辑器工具 -----------------> 读取/生成 核心运行时代码
-```
+## 当前验证基线

-### 依赖规则
-
-| 上层 | 可以依赖 | 禁止依赖 |
-|---|---|---|
-| 业务功能 | 核心运行时、通用框架 | 编辑器工具、第三方插件源码 |
-| 核心运行时 | 通用框架、第三方插件 | 具体业务功能、编辑器工具 |
-| 编辑器工具 | 核心运行时源码、生成模板 | 被运行时代码反向引用 |
-
-### 说明
-
- 运行时代码不要依赖 Editor 程序集。
- 第三方插件不应反向依赖具体玩法模块。
- 业务功能代码按业务命名，代码目录可以仍然按框架/实现组织。
-
---
-
-## 文档与代码分层对应
-
-| 文档层 | 对应代码层 | 示例 |
-|--------|-----------|------|
-| `modules/frameworks/` | 核心运行时 | 实体系统、UI 系统、事件系统等 |
-| `modules/frameworks/通用框架/框架架构.md` | 核心运行时 + 规范 | StrayFog 整体架构分析 |
-| `rules/` | 规范与流程 | 开发规则、工作流清单、架构说明 |
-
---
-
-## 待确认
-
- 各项目实际使用的 StrayFog 版本与目录可能略有差异，文档中路径以当前仓库描述的 `Assets/StrayFog/` 和 `Assets/Game/` 结构为准。
- 网络系统、配置生成系统是否为所有使用 StrayFog 的项目标配，需按具体项目确认。
-
---
+AI 每次都应读取目标项目的 `ProjectSettings/ProjectVersion.txt`，不把文档中的版本当作永久值。当前 CrystalBattle_Client 的验证基线为 Unity `2022.3.29f1`。

 ## 文档关联

-> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
-
 | 文档 | 关联原因 |
 |---|---|
-| [modules/frameworks/通用框架/框架架构.md](../modules/frameworks/通用框架/框架架构.md) | 实现视角的框架架构分析 |
-| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是架构说明的落地入口，分类口径需一致 |
-| [rules/30-模块登记规则.md](30-模块登记规则.md) | 模块登记口径、状态定义与架构分层互相影响 |
-| [rules/20-开发规则.md](20-开发规则.md) | 程序集边界、依赖方向与开发规则互相引用 |
-| [rules/项目规则入口.md](项目规则入口.md) | 架构说明是项目规则入口索引的关键规则 |
+| [开发规则](20-开发规则.md) | 源码边界对应具体修改规则 |
+| [工作流清单](40-工作流清单.md) | 生成和验证步骤引用本架构 |
+| [模块索引](../modules/模块索引.md) | 模块职责和入口 |
+| [通用框架](../modules/frameworks/通用框架/框架架构.md) | StrayFog 实现视角的架构说明 |
--- a/rules/20-开发规则.md
+++ b/rules/20-开发规则.md
@@ -1,269 +1,87 @@
 # 开发规则

-> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
-
 ## 基本原则

- 优先遵循项目已有模式。
- 修改范围保持在当前功能或模块内。
- 不手动修改生成代码，除非生成器不可用且已记录原因。
- 不直接修改 `Assets/ThirdPlugins/` 或 embedded package，除非必须且记录原因。
- 正常分析项目时忽略 Unity/IDE 本地状态目录。
- 运行时代码不引用 Editor 程序集。
- **一处定义，多处引用**：如果一个事实出现在多个文档中，修改时必须同步所有地方。
-
---
+- 先读取附近代码和模块文档，再决定实现方式。
+- 修改范围保持聚焦，优先复用项目已有模式和公开入口。
+- 真实源码、生成代码、业务代码和资源必须按 [架构说明](10-架构说明.md) 区分。
+- 不回退任务开始前已有的修改，不顺带格式化或重序列化无关文件。
+- 一个长期事实只在一处完整定义，其他文档使用链接。

 ## 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`。
+- 类型、属性和方法使用 PascalCase。
+- 私有字段沿用项目 `m_` 前缀，例如 `m_UserName`。
+- 方法参数沿用项目 `_` 前缀，例如 `_userName`。
+- 一个文件原则上只放一个主要类型；partial 和小型辅助类型遵循附近实现。
+- public API 添加简洁中文 XML 注释，说明用途、参数和返回值。
+- 日志包含方法、资源路径、PackageId 或平台等关键上下文，不只输出“失败”。

-### 代码组织
+### 语言兼容性

- 一个 `.cs` 文件原则上只放一个主要类型；小枚举可多个共存。
- 类型可见性排序按项目已有风格；如无风格，按 public → protected → internal → private。
- 公共 API 添加中文 XML 文档注释或行内注释，说明用途、参数、返回值。
- 只在解释非显然意图时添加注释，不写无意义注释。
+- 先读取 Unity 版本、asmdef 和附近代码风格，不默认使用最新 C# 语法。
+- 优先使用项目已有的显式类型、普通属性、传统 `switch` 和清晰的回调/协程写法。
+- 非必要时不引入 record、init-only、范围索引、复杂模式匹配、目标类型推断等较新语法。
+- 新语法只有在目标 Unity/编译器已验证且确实降低复杂度时使用。
+- 避免超长方法、深层嵌套和为了封装而封装的辅助层。

-### 日志与异常
+## 框架与业务边界

- 异常只用于异常情况，不用于正常流程控制。
- 错误日志包含方法名和关键上下文，不包含敏感信息。
- 写日志时保持附近文件风格；优先使用项目统一的日志封装（如有）。
+- 业务代码通过 `HFFunCatalogue` 等统一入口访问资源、UI、场景和其他框架能力。
+- 业务功能直接修改 `GameFunction`、`GameMono` 和对应资源。
+- 框架维护任务可以修改 `Assets/StrayFog/Core`、`Assets/StrayFog/Editor` 和 CopyToX 源码，不套用“业务不得改框架”的限制。
+- CopyToX 生成目录禁止手改；生成结果有问题时修正 ESF/General 源码或生成器。
+- 修改 ESF 后必须执行 CopyToX，并检查生成后的 HF 差异。

-### 其他
+## Unity 与异步规则

- 优先遵循附近文件风格。同一文件/同一目录下风格应保持一致。
- 保持 public API 小而明确。
- 避免超长方法和深层嵌套。
+- Unity API 只在 Unity 主线程调用；后台线程只做不触碰 UnityEngine 对象的工作。
+- StreamingAssets、UnityWebRequest、CDN 和 WebGL 下载使用协程或回调。
+- 禁止在主线程用阻塞式 `while`、忙等或同步等待网络与文件结果。
+- 下载进度只在单文件完整写入并通过 MD5/完整性校验后计数。
+- 平台路径、只读 StreamingAssets、PersistentData 和外部存储回调分别验证。

---
+## UI 与 Prefab

-## 核心库访问规则
+- 修改前同时读取窗口脚本、UIMono、Prefab 层级和相关资源。
+- 单列虚拟列表使用 `SetLoopListViewItemPrefabs`、`InitListView`、`RefreshDataTotalCount`。
+- 多列虚拟列表使用 `SetLoopGridViewItemPrefabs`、`InitGridView`、`RefreshGridDataTotalCount`。
+- 模板节点保持禁用，由列表运行时创建实例；不要依赖旧 LayoutGroup 或 ContentSizeFitter 驱动虚拟列表。
+- Prefab 修改检查锚点、pivot、sizeDelta、组件启用状态、序列化引用和实际显示。
+- 避免文本方式大范围重写 Prefab；优先使用 Unity Editor、MCP 或结构化序列化工具。

-### 核心库范围
+详细规则见 [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md)。

-以下目录属于核心库，业务代码应只读访问，修改需走框架团队 Issue 流程：
+## 资源与生成规则

-| 路径 | 说明 |
-|------|------|
-| `Assets/StrayFog/Core` | 基础框架核心 |
-| `Assets/Game/GameHFScripte/CopyToHF` | 游戏核心业务框架 |
-| `Assets/Game/GameGeneralScripte` | 通用工具层 |
+- Prefab、图集、配置、AssetBundle 和代码生成优先修改源资源或生成配置。
+- SpriteAtlas 按模块组织；打图集设置以项目生成器为准。
+- 网络消息以 proto/schema 为源头，生成输出只用于检查。
+- 资源加载、分包、MD5、下载和卸载规则见 [资源管理](../modules/frameworks/资源管理/README.md)。
+- 生成操作后检查 Git 差异，确认没有删除或覆盖用户维护的非生成文件。

-### 访问方式
+## 验证与 Git

-业务代码必须通过 `HFFunCatalogue` 统一入口访问核心库：
+- 验证范围随改动范围扩大，最低要求见 [工作流清单](40-工作流清单.md)。
+- 编译通过后仍需检查 Unity Console；UI 和平台逻辑继续做实际运行验证。
+- UnityAI 与目标 Unity 项目分别检查 Git 状态。
+- 只有用户明确要求时才提交或推送，提交格式统一为 `[模块][类型]: 描述`。

-```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 工具中均可点击。
- 代码示例必须可编译（或明确标注为伪代码）。
-
---
+- 长期文档只记录稳定架构、公共 API、生成流程和使用规则。
+- 重大变更的讨论和文档落盘方式遵循 [工作流清单](40-工作流清单.md)。
+- 文档使用相对链接；代码示例必须可编译或明确标注伪代码。
+- 模块入口或状态变化时更新 [模块索引](../modules/模块索引.md)。

 ## 文档关联

-> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
-
 | 文档 | 关联原因 |
 |---|---|
-| [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) | 对象池最佳实践落地 |
+| [架构说明](10-架构说明.md) | 源码与生成目录边界 |
+| [工作流清单](40-工作流清单.md) | 实施与验证流程 |
+| [文档同步规则](50-文档同步规则.md) | 长期文档更新条件 |
+| [UI 窗口系统](../modules/frameworks/UI窗口系统/README.md) | UI 专项规范 |
+| [资源管理](../modules/frameworks/资源管理/README.md) | 资源专项规范 |
--- a/rules/30-模块登记规则.md
+++ b/rules/30-模块登记规则.md
@@ -1,81 +1,43 @@
 # 模块登记规则

-> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
+模块入口、分类和状态统一维护在 [模块索引](../modules/模块索引.md)，其他文档不复制模块清单。

-这里定义模块登记口径、状态含义和拆分规则。项目模块总入口统一维护在 [模块索引](../modules/模块索引.md)，本文件不重复维护模块清单。
+## 分类

---
+- **核心框架**：运行时系统，例如 UI、资源、事件、实体、对象池和场景。
+- **编辑器工具**：Unity Editor 内的生成器、窗口、菜单和 MCP Bridge。
+- **业务参考**：外部项目案例，仅用于说明框架如何被使用。

-## 口径
+## 状态

- **核心框架**：支撑游戏运行的内部系统，例如实体系统、UI 窗口系统、事件系统、资源管理、对象池、场景管理、网络、配置生成。
- **编辑器工具**：Unity Editor 内使用的生成器、Inspector、菜单、配置工具。
- **业务参考**：外部实际项目的业务实现示例，仅作参考，不作为框架规范。
+- **未识别**：尚无稳定实现线索。
+- **已识别**：已发现路径或入口，未完成系统梳理。
+- **初步梳理**：职责、路径或基本数据流已记录，仍有待确认项。
+- **待验证**：文档已有结论，尚未通过 Unity、运行时、生成器或日志闭环。
+- **已完成**：当前文档与实现已经验证，后续随代码演进维护。
+- **未发现实现**：按目录和关键词检查后暂未发现实现。

---
+## 文档结构

-## 唯一事实来源
-
-模块清单、模块状态和模块入口统一维护在：
-
-```text
-modules/模块索引.md
-```
-
-其他规则文档只链接到模块索引或具体模块文档，不再复制模块表。
-
---
-
-## 状态定义
-
- **未识别**：还没有稳定线索。
- **已识别**：已发现目录、类、资源或协议线索，但未完成梳理。
- **初步梳理**：已写入核心路径、职责、数据流或使用规则，仍可能有待确认项。
- **待验证**：文档已有结论，但需要通过 Unity、运行时、生成器或日志验证。
- **已完成**：文档和验证都闭环，后续只需随代码演进维护。
- **未发现实现**：按关键词和目录扫描后暂未发现实现，可作为规划占位。
-
-避免使用“已开始”作为状态；它不能说明到底是只建了文件，还是已经完成了一轮梳理。
-
---
+- 轻量模块使用一个 `README.md`。
+- API 和业务调用较多时增加 `使用指南.md` 或 `开发指南.md`。
+- 特殊限制写入 `注意事项.md`，不创建计划、进度或任务文件。
+- 模块发生大改时，讨论保留在对话中；实现后的稳定结论直接更新现有文档。
+- 模块新增、删除、重命名或状态变化时更新模块索引。

 ## 登记规则

- 新增核心框架模块时，登记到 [模块索引](../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/frameworks/`。
+- 编辑器工具放入 `modules/frameworks/编辑器工具/`。
+- 外部业务案例放入 `business-reference/<project>/`，不作为框架规范。
+- 文档路径反映模块职责，不按一次性任务名称建立目录。
+- 一个模块的职责和入口由 README 完整定义，索引只保存摘要和链接。

 ## 文档关联

-> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
-
 | 文档 | 关联原因 |
 |---|---|
-| [modules/模块索引.md](../modules/模块索引.md) | 模块索引是模块登记规则的唯一事实来源 |
-| [rules/10-架构说明.md](10-架构说明.md) | 分类口径、依赖方向与架构说明互相影响 |
-| [rules/项目规则入口.md](项目规则入口.md) | 模块登记规则是项目规则入口索引的关键规则 |
-| [modules/frameworks/*.md](../modules/frameworks/) | 框架模块的状态、拆分规则需与登记规则一致 |
+| [模块索引](../modules/模块索引.md) | 模块清单和状态的唯一事实来源 |
+| [架构说明](10-架构说明.md) | 模块分类与代码分层 |
+| [文档同步规则](50-文档同步规则.md) | 模块变化的同步条件 |
+| [模块文档模板](../modules/模块文档模板.md) | 新模块文档结构 |
--- a/rules/40-工作流清单.md
+++ b/rules/40-工作流清单.md
@@ -1,206 +1,135 @@
 # 工作流清单

-> 本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。
+本文档是 UnityAI 唯一的任务执行流程。其他入口只链接本文件，不复制完整步骤。

---
+## 一、任务分类

-## 任务分类
-
-| 类型 | 特征 | 处理方式 |
+| 类型 | 判断标准 | 处理方式 |
 |---|---|---|
-| **简单修复** | 查询、解释、小范围修改、影响面低、用户已给出明确方式 | 直接处理，完成后验证并归档检查 |
-| **旧模块修复** | 已有框架模块的 bug 修复、逻辑补全、局部优化 | 读取模块文档，分析影响范围后修复，验证并归档 |
-| **Spec 任务** | 新增框架模块、调整架构/目录/依赖、批量修改迁移 | 走 OpenSpec 流程 |
+| 分析检查 | 查询、解释、定位、评审，不要求修改 | 读取真实实现和证据，输出结论与风险 |
+| 局部修复 | 目标明确、影响集中、公开行为基本不变 | 检查上下文后直接修改并验证 |
+| 重大变更 | 公共接口、框架架构、生成流程、跨模块数据、批量资源或平台流程变化 | 先在对话中确认目标、边界、方案和验收条件，再实施 |

---
+重大变更不创建 Spec、Plan、progress 或 tasks 文件。需要长期保存的内容，在实现确认后写入对应模块 README、架构说明或使用指南。

-## 简单修复流程
+## 二、标准执行流程

-1. 确认任务范围。
-2. 读取相关模块文档。
-3. 直接修改。
-4. 验证（如可运行测试、检查链接、预览 Markdown）。
-5. 执行归档检查。
-6. 简短说明结果。
+### 1. 准备与定位

---
+1. 读取 [项目规则入口](项目规则入口.md) 和相关模块文档。
+2. 检查 UnityAI 与目标 Unity 项目的分支、工作树和未跟踪文件。
+3. 读取 `ProjectSettings/ProjectVersion.txt`，确认 Unity 版本。
+4. 搜索调用入口、数据流、Prefab、配置、生成器和测试方式。
+5. 按 [架构说明](10-架构说明.md) 确认修改对象是真实源码还是生成结果。

-## 旧模块修复流程
+无法从仓库发现的信息才向用户确认。已有修改默认属于用户，必须保留并在其基础上工作。

-1. 定位已有模块文档和相关内容。
-2. 简短分析影响范围和风险。
-3. 直接修复。
-4. 验证。
-5. 按 [50-归档规则.md](50-归档规则.md) 同步相关模块文档。
+### 2. 分析与确认

---
+- 分析检查：继续读取直到结论有代码、资源、配置或日志支撑。
+- 局部修复：说明准备修改的位置和行为，然后直接实施。
+- 重大变更：在对话中确认目标、范围、兼容性、数据流、失败行为和验证标准。
+- 存在多个真实取舍时提供备选方案；没有实际取舍时不制造方案数量。

-## Spec 任务流程
+### 3. 实施

-大需求 / 新模块统一走 OpenSpec：
+- 遵循附近文件的结构、命名和语言特性。
+- 修改保持在需求涉及的模块内，不顺带重构无关代码。
+- 使用结构化 API 处理 JSON、XML、Prefab 和配置，不使用脆弱的字符串替换。
+- 修改资源时优先通过 Unity Editor、已有生成器或 MCP 工具，避免无意义的 Prefab 重序列化。
+- 不修改任务无关文件，不回退已有工作树变更。

-1. 分析目标、影响范围、风险和依赖。
-2. 给出 2-3 个方案。
-3. 用户确认后创建 OpenSpec change。
-4. 生成 `proposal.md`、`design.md`、`tasks.md`。
-5. 实现。
-6. 验证。
-7. 归档并同步文档。
+### 4. 生成代码

-详见 [60-新特性工作流.md](60-新特性工作流.md)。
+修改 `Assets/StrayFog/Editor/CopyToX` 下的 `ESF_` 源码后：

---
+1. 通过 Unity 菜单或 MCP 白名单命令执行 CopyToX。
+2. 检查 `Assets/Game/GameHFScripte/CopyToHF` 或对应目标目录的生成差异。
+3. 确认 `ESF_` 到 `HF_` 的类型名、文件名和调用关系转换正确。
+4. 编译目标程序集并读取 Unity Console。

-## 开发流程
+出现“HF 已修改但 ESF 未修改”时，先判断是否误改生成文件；出现“ESF 已修改但 HF 未变化”时，必须补执行 CopyToX。

-### 1. 文档学习
+### 5. 分层验证

-根据任务类型阅读对应模块文档：
+| 改动范围 | 最低验证 |
+|---|---|
+| `Assets/StrayFog/Core` | 构建 `StrayFogCore.csproj`，再检查 Unity Console |
+| `Assets/StrayFog/Editor`、`Assets/Editor` | 构建适用 Editor 程序集或在 Unity 中触发编译，检查 Console 和菜单行为 |
+| `GameGeneralScripte` | 构建 `GameGeneral.csproj` |
+| `GameMono` | 构建 `SFMono.csproj` |
+| `GameHFScripte` | 构建 `GameHF.csproj` |
+| Prefab/UI | 刷新资源，检查层级、RectTransform、组件启用状态、引用和实际显示 |
+| AssetBundle/分包/下载 | 除 Editor 外，验证目标平台路径、协程、MD5、失败回退和日志 |

-| 任务类型 | 必读文档 |
-|---------|---------|
-| 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
+```powershell
+dotnet build SFMono.csproj --no-restore -v:minimal
+dotnet build GameHF.csproj --no-restore -v:minimal
 ```

-类型：`feat`、`fix`、`docs`、`refactor`、`test`、`chore`。
+其他程序集按实际改动替换项目文件。构建结果需区分既有警告和本次新增错误。

-模块名示例：`framework`、`entity`、`ui`、`event`、`resource`、`docs`、`rules`、`hooks`。
+### 6. Unity 与 MCP 验证

-示例：
+需要 Unity 自动化时：

-```text
-[entity][docs]: 补充实体池索引机制说明
+1. 调用 `unity_health`，确认项目路径和 Unity 版本。
+2. 执行白名单菜单、资源刷新、Prefab 生成或导出。
+3. 调用 `unity_get_console_logs` 检查新增 Error 和关键 Warning。
+4. Prefab/UI 任务继续做结构与实际显示验证，不能以“文件已生成”作为完成条件。

- 添加 onlyid -> entity 映射说明
- 补充 HFBasicPool/HFEnemyPool/HFHumanityPool 边界
-```
+连接失败时停止后续 Unity 命令并报告原因，不假设命令已经执行。

-> **历史格式说明**：早期文档使用 `【操作原因】具体操作内容`（如 `【修复】xxx`）。该格式已弃用，新提交统一使用 `[module][type]: description`。
+### 7. 文档同步

-### 分支管理
+按 [文档同步规则](50-文档同步规则.md) 判断是否存在长期知识变化：

-| 分支名称 | 用途 |
-|----------|------|
-| `master` | 主分支，稳定版本 |
-| `develop` | 开发分支，日常开发 |
-| `feature/*` | 功能分支，开发新功能 |
-| `bugfix/*` | Bug 修复分支 |
+- 公共接口、架构边界、生成流程、平台行为或稳定使用规则变化时，同步模块文档。
+- 局部 Bug 修复、临时日志和实现细节不自动写入长期文档。
+- 同一事实只在一个文档完整定义，其他位置链接引用。

-### Git 操作原则
+### 8. Git

- 执行 Git 操作前确认当前操作路径是否正确。
- 遵循项目既定的分支策略。
- 使用语义化提交信息，清晰描述更改内容。
- 重要功能提交前建议先创建分支进行测试。
- 开发完成后及时推送到远程仓库。
+- 只有用户明确要求“提交”“commit”“推送”时才执行 Git 写操作。
+- UnityAI 和目标 Unity 项目是独立仓库，分别检查、暂存、提交和推送。
+- 提交前运行工作流检查、目标测试、`git diff --check` 和提交信息检查。
+- 提交格式：`[模块][类型]: 描述`，类型为 `feat`、`fix`、`docs`、`refactor`、`test`、`chore`。
+- 不把两个仓库的改动描述成一个提交，也不夹带任务开始前的无关修改。

-### 提交前检查项
+## 三、UI 专项流程

- [ ] 文档链接可点击且指向正确。
- [ ] 文档关联表已更新。
- [ ] 模块索引已同步（如新增/拆分了模块）。
- [ ] 无拼写或明显格式错误。
- [ ] 未引入外部项目专属内容。
- [ ] 业务参考内容只出现在 `business-reference/` 下。
+1. 先读 [UI 开发指南](../modules/frameworks/UI窗口系统/开发指南.md) 和 [界面拼接](../modules/frameworks/UI窗口系统/界面拼接.md)。
+2. 同时检查 Prefab 层级、脚本绑定、模板节点、布局组件和数据刷新时机。
+3. 单列列表使用 LoopListView2 接口，多列布局使用 LoopGridView 接口。
+4. 列表初始化放在一次性生命周期，数据数量刷新放在窗口打开或数据变化时。
+5. 完成后验证空数据、少量数据、超出视口、重复打开和回收重用。

---
+## 四、异步与平台规则

-## 新增内容流程
+- UnityWebRequest、StreamingAssets、CDN 和 WebGL 等待流程使用协程或回调。
+- 不在主线程使用阻塞式 `while`、忙等或同步等待网络结果。
+- Editor 可用不代表 Android、iOS、WebGL 或小游戏路径可用；平台路径和存储回调必须分别验证。
+- 下载完成计数只在单个文件完整写入并通过校验后推进。

-### 新增框架模块
+## 五、完成检查

-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，而不是生成输出。
- 生成后检查输出目录，确认变更符合预期。
- 缺失的生成步骤记录到对应模块文档。
-
---
+- [ ] 修改了真实源码，没有误改生成文件。
+- [ ] 必要生成步骤已经执行并检查差异。
+- [ ] 相关程序集编译通过。
+- [ ] Unity Console 无本次新增错误。
+- [ ] UI/Prefab 或平台行为完成实际验证。
+- [ ] 长期文档按影响同步，没有写入流水账。
+- [ ] 两个仓库状态分别检查，未触碰用户无关修改。
+- [ ] 未经明确要求没有提交或推送。

 ## 文档关联

-> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
-
 | 文档 | 关联原因 |
 |---|---|
-| [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) | 提交检查脚本需与本文件格式一致 |
+| [项目规则入口](项目规则入口.md) | 指向本工作流的快速入口 |
+| [架构说明](10-架构说明.md) | 源码与生成代码边界 |
+| [开发规则](20-开发规则.md) | 实施阶段的代码与 Unity 规范 |
+| [文档同步规则](50-文档同步规则.md) | 完成后的长期知识同步 |
+| [共享检查](../hooks/Hook共享层.md) | 工作流和提交检查脚本 |
--- a/rules/50-归档规则.md
+++ b/rules/50-归档规则.md
@@ -1,79 +0,0 @@
-# 归档规则
-
-> 本文档是 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/50-文档同步规则.md
+++ b/rules/50-文档同步规则.md
@@ -0,0 +1,59 @@
+# 文档同步规则
+
+文档同步的目标是保存长期有效的框架知识，不是记录每次任务过程。
+
+## 必须同步的变化
+
+- 公共 API、参数、返回值或调用顺序变化。
+- 框架分层、源码位置、生成目录或依赖方向变化。
+- Prefab、资源、配置或构建产物的稳定结构变化。
+- Editor 工具、CopyToX、AssetBundle、分包、热更新等生成流程变化。
+- 平台路径、下载策略、失败回退或兼容性规则变化。
+- 模块新增、删除、重命名、状态或入口变化。
+
+## 通常不写入长期文档
+
+- 不改变公开行为的局部 Bug 修复。
+- 临时断点、调试日志、截图和排错过程。
+- 一次性测试数据或仅服务当前任务的文件列表。
+- 可以直接从代码读出的私有实现细节。
+- 尚未确认的讨论结论和未来计划。
+
+## 同步位置
+
+| 变化 | 写入位置 |
+|---|---|
+| 跨模块规则和工作方式 | `rules/` 中对应唯一规则 |
+| 模块职责、架构和数据流 | 模块 `README.md` |
+| 业务调用和公共 API | 模块 `使用指南.md` 或开发指南 |
+| 模块入口或状态 | `modules/模块索引.md` |
+| 外部项目案例 | `business-reference/` 对应项目 |
+
+重大变更的讨论和任务过程文档规则以 [工作流清单](40-工作流清单.md) 为准；实现后的稳定结论直接进入上述长期文档。
+
+## 单一事实来源
+
+- 一个事实只在一个文档完整定义。
+- 其他文档只写任务所需的最短摘要并链接到事实来源。
+- 修改事实来源后，检查所有引用是否仍然成立；不要复制整段内容同步维护。
+- 模块索引只保存入口、职责摘要和状态，不承载完整使用说明。
+
+## 检查方式
+
+任务完成后运行：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File hooks/workflow-check.ps1 `
+  -UnityProjectRoot <Unity工程路径>
+```
+
+脚本只输出工作树、源码/生成代码关系、建议验证和可能需要同步的文档，不自动修改文件。最终是否更新文档按本规则判断。
+
+## 文档关联
+
+| 文档 | 关联原因 |
+|---|---|
+| [项目规则入口](项目规则入口.md) | 引用文档同步原则 |
+| [工作流清单](40-工作流清单.md) | 定义同步发生的任务阶段 |
+| [模块登记规则](30-模块登记规则.md) | 模块文档结构和状态口径 |
+| [共享检查](../hooks/Hook共享层.md) | 提供只读检查脚本 |
--- a/rules/60-新特性工作流.md
+++ b/rules/60-新特性工作流.md
@@ -1,138 +0,0 @@
-# 大需求 / 新模块工作流
-
-> 本文档是 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/项目规则入口.md
+++ b/rules/项目规则入口.md
@@ -1,252 +1,62 @@
-# UnityAI - 项目规则入口
+# UnityAI 项目规则入口

-> 本文件是 UnityAI / StrayFog 框架知识库的 **项目规则入口**。
->
-> 所有 AI / IDE 工具先通过 [ai/AI接入入口.md](../ai/AI接入入口.md) 接入项目，再按任务范围读取本文件和下方链接的具体文档。
->
-> 不要把项目规则重复写在你的系统提示里；直接引用本文件和 `rules/` 下的规则文件。
+UnityAI 是 StrayFog 框架的通用工作流与知识标准。具体游戏项目负责提供真实代码、资源和验证环境；当前主要验证对象为 `CrystalBattle_Client`。

---
+## 快速启动

-## AI 快速启动
+处理任务时按顺序执行：

-1. 确认已读取 [AI 工具接入入口](../ai/AI接入入口.md)。
-2. **读取本文件**（`rules/项目规则入口.md`）。
-3. 根据任务范围，从下方的 **规则索引**、**项目知识入口**、**Spec 索引** 中选择相关文档读取。
-4. **简单修复**：直接开始处理，完成后简短说明结果。
-5. **旧模块修复**：定位已有模块文档和相关内容，简短分析后直接修复。
-6. **大需求 / 新模块**：新增框架模块、架构调整、文档重组等，先给出 2-3 个方案，用户确认后走 **OpenSpec 流程**。
-7. **所有任务结束都执行归档 hook / 归档检查**，按影响范围决定是否更新长期文档。
+1. 读取本文件和 [工作流清单](40-工作流清单.md)。
+2. 从 [模块索引](../modules/模块索引.md) 读取相关模块文档。
+3. 检查 UnityAI 与目标 Unity 项目的 Git 状态，保留已有修改。
+4. 根据 [架构说明](10-架构说明.md) 找到真实源码，区分源码、生成代码、业务代码和资源。
+5. 按任务类型分析、修改、生成和验证。
+6. 按 [文档同步规则](50-文档同步规则.md) 判断是否需要更新长期文档。

---
+## 工作方式

-## 项目概况
+- **分析检查**：读取代码、Prefab、配置或日志，给出有证据的结论，不修改文件。
+- **局部修复**：影响范围明确时直接修复并完成针对性验证。
+- **重大变更**：涉及公共接口、框架、生成流程、跨模块数据或批量迁移时，先在对话中确认目标、影响和实现方式，再修改。
+- 重大变更的讨论和长期结论保存方式以 [工作流清单](40-工作流清单.md) 为准。

- **项目名**：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)。
-
---
+完整步骤与验收条件统一维护在 [工作流清单](40-工作流清单.md)，本文件不重复展开。

 ## 关键约束

- **一处定义，多处引用**：如果一个事实出现在多个文档中，修改时必须同步所有地方。
- 优先修改源头文档，不要手动同步复制多份内容。
- 运行时代码不引用 Editor 程序集。
- UI 变更遵循 [UI 框架](../modules/frameworks/UI窗口系统/README.md)。
- 事件变更遵循 [事件框架](../modules/frameworks/事件系统/README.md)。
- 资源变更遵循 [资源管理](../modules/frameworks/资源管理/README.md)。
+- 先定位源码再修改，禁止把生成目录当作源码。
+- `ESF_` 框架修改发生在 `Assets/StrayFog/Editor/CopyToX`，随后通过 CopyToX 生成 `HF_` 代码。
+- 不直接手改 `Assets/Game/GameHFScripte/CopyToHF`。
+- 业务代码通过项目公开入口使用框架；维护框架时修改真实框架源码。
+- Prefab/UI 修改必须同时核对脚本、层级、RectTransform、组件状态和实际显示。
+- Unity、平台和网络相关逻辑不能只凭 Editor 编译结果判断正确。
+- 只在用户明确要求提交或推送时执行 Git 写操作；UnityAI 与游戏项目分别提交。
+- 不覆盖、不回退任务开始前已有的修改或未跟踪文件。

---
+## 规则索引

-## 归档规则摘要
+| 文档 | 用途 |
+|---|---|
+| [项目概览](00-项目概览.md) | UnityAI 定位、目录与读者 |
+| [架构说明](10-架构说明.md) | 代码分层、源码边界和依赖方向 |
+| [开发规则](20-开发规则.md) | C#、Unity、资源和生成代码规范 |
+| [模块登记规则](30-模块登记规则.md) | 模块分类、状态与文档结构 |
+| [工作流清单](40-工作流清单.md) | 唯一的任务执行流程 |
+| [文档同步规则](50-文档同步规则.md) | 长期文档更新条件和方法 |
+| [项目设置](70-项目设置.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` 的薄入口。
-
---
+- [模块索引](../modules/模块索引.md)：框架、编辑器工具和使用文档入口。
+- [共享检查](../hooks/Hook共享层.md)：工作流和提交检查脚本。
+- `business-reference/`：外部业务项目案例，只作参考，不作为框架规范。

 ## 文档关联

-> 当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。
-
 | 文档 | 关联原因 |
 |---|---|
-| [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) | 归档触发机制在本文档中被引用 |
+| [AI 接入入口](../ai/AI接入入口.md) | AI 工具通过该入口进入本规则 |
+| [工作流清单](40-工作流清单.md) | 任务执行流程的唯一事实来源 |
+| [文档同步规则](50-文档同步规则.md) | 任务完成后的长期知识同步规则 |
+| [模块索引](../modules/模块索引.md) | 项目知识入口 |
+| [共享检查](../hooks/Hook共享层.md) | 规则的脚本化检查入口 |