[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/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) | 归档触发机制在本文档中被引用 |