From d31b49221e0ceabc2870a51d6ec674eae5dab8d8 Mon Sep 17 00:00:00 2001
From: lms <573220649@qq.com>
Date: Wed, 15 Jul 2026 14:40:38 +0800
Subject: [PATCH] =?UTF-8?q?[docs][fix]:=20=E8=A1=A5=E9=BD=90=E5=8D=95?=
 =?UTF-8?q?=E6=96=87=E4=BB=B6=E6=A8=A1=E5=9D=97=E7=8A=B6=E6=80=81=E5=AD=97?=
 =?UTF-8?q?=E6=AE=B5=E4=B8=8E=20MCP=20=E7=BB=B4=E6=8A=A4=20checklist?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 场景系统/数据配置框架/网络系统/Hotfix启动增加验证与当前状态
- 数据配置变更清单补充具体菜单/路径/命令
- 模块登记规则增加 README/使用指南/注意事项量化标准
- 模块文档模板明确 README 与使用指南分工
- MCP 使用规则维护要求改为 checklist

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 modules/frameworks/Hotfix启动.md              | 12 +++++++++
 modules/frameworks/场景系统.md                | 10 +++++++
 modules/frameworks/数据配置框架.md            | 26 ++++++++++++++-----
 .../CrystalBattle_Codex_Unity_MCP使用规则.md  |  8 +++---
 modules/frameworks/网络系统.md                | 19 +++++++++++---
 modules/模块文档模板.md                       | 13 +++++++++-
 rules/30-模块登记规则.md                      | 12 +++++++++
 7 files changed, 85 insertions(+), 15 deletions(-)

diff --git a/modules/frameworks/Hotfix启动.md b/modules/frameworks/Hotfix启动.md
index d384b4b..dc759a4 100644
--- a/modules/frameworks/Hotfix启动.md
+++ b/modules/frameworks/Hotfix启动.md
@@ -43,6 +43,18 @@ Bootstrap 阶段是普通资源的硬门禁。远端清单、代码下载、MD5
 
 启动顺序变化必须同时检查非热更层、V2 门禁、普通资源和 UI 首屏，不能只修改热更入口一侧。
 
+## 验证
+
+- 构建 `GameMono`（`SFMono.csproj`）与非热更入口相关程序集。
+- 构建 `GameHF.csproj`。
+- 在目标平台或 Editor 中验证 Bootstrap 阶段：清单获取、MD5 校验、AOT/HotUpdate 加载顺序。
+- 模拟 Bootstrap 失败（如断网、错误 MD5），确认重试与回调行为。
+- 验证普通资源更新后 `HFGameStart` 正常进入配置/场景加载。
+
+## 当前状态
+
+- 待验证
+
 ## 文档关联
 
 | 文档 | 关联原因 |
diff --git a/modules/frameworks/场景系统.md b/modules/frameworks/场景系统.md
index 3fa6a42..56435e7 100644
--- a/modules/frameworks/场景系统.md
+++ b/modules/frameworks/场景系统.md
@@ -76,6 +76,16 @@ HFFunCatalogue.Asset.LoadAsset(levelId, ...)
 - 不要在场景里堆放运行时动态加载的资源。
 - 切场景时注意 UI 窗口的自动关闭/销毁配置。
 
+## 验证
+
+- 构建 `GameHF.csproj` 与 `SFMono.csproj`。
+- 在 Unity Editor 中切换场景，确认加载回调、资源引用和 UI 自动关闭行为正确。
+- 检查 `enHFSceneName` 与资源配置表的主键一致性。
+
+## 当前状态
+
+- 待验证
+
 ---
 
 ## 相关模块
diff --git a/modules/frameworks/数据配置框架.md b/modules/frameworks/数据配置框架.md
index f1b8420..7699bfb 100644
--- a/modules/frameworks/数据配置框架.md
+++ b/modules/frameworks/数据配置框架.md
@@ -79,13 +79,25 @@ HFFunCatalogue.NDB.ds_xxx.ReadTableDeterminant();
 
 ## 变更清单
 
-1. 修改源表。
-2. 确认 settings / resolve 配置。
-3. 重新生成。
-4. 检查输出。
-5. 编译验证。
-6. 运行时验证。
-7. 更新文档。
+1. 修改源表（`XLSX_SRC/CN/`、`XLSX_SRC/EN/`）。
+2. 确认 `ProjectSettings/ZYF/ZYXlsx/ZYXlsxProjectSettings.asset` 与 Resolve 配置。
+3. 通过 Unity 菜单 `StrayFog → XLSX → Generate Runtime Data`（或对应 MCP 白名单命令）重新生成。
+4. 检查输出数据目录 `Assets/AutoBuildAsset/{Editor,Hotfix}/AutoFrame/Google.Protobuf/XLSX_SRC/<语言>/`。
+5. 检查输出代码目录 `Assets/AutoBuildScript/{Editor,General,Hotfix}/AutoFrame/Google.Protobuf/XLSX_Script/`。
+6. 编译 `GameGeneral`、`GameHF`、`SFMono` 等受影响程序集。
+7. 运行时验证：确认 `HFGameStart.LoadDB()` 成功且读取 API 返回预期。
+8. 更新本文档与 [模块索引](../模块索引.md)。
+
+## 验证
+
+- 生成器执行无 Error。
+- 受影响程序集编译通过。
+- 运行时 `LoadAllXlsx` 回调正常触发。
+- 关键表（如 `EntityConfig`、`SkillGroup`）按主键读取结果正确。
+
+## 当前状态
+
+- 待验证
 
 ---
 
diff --git a/modules/frameworks/编辑器工具/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md b/modules/frameworks/编辑器工具/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md
index 82f2b3e..0c41eab 100644
--- a/modules/frameworks/编辑器工具/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md
+++ b/modules/frameworks/编辑器工具/MCP工具/CrystalBattle_Codex_Unity_MCP使用规则.md
@@ -96,9 +96,11 @@ UI 任务必须先从 [UnityAI README](../../../../README.md) 进入 UI 文档
 
 新增 MCP tool 时同步更新：
 
-- `Tools/CodexUnityMcp/src/server.mjs`
-- Unity Bridge 对应命令
-- 本文档工具列表和验证步骤
+- [ ] `Tools/CodexUnityMcp/src/server.mjs`
+- [ ] Unity Bridge 对应命令
+- [ ] 本文档工具列表和验证步骤
+- [ ] 对应测试用例或示例调用
+- [ ] Bridge 白名单（如适用）
 
 Bridge 返回统一结构：
 
diff --git a/modules/frameworks/网络系统.md b/modules/frameworks/网络系统.md
index 01e5f5a..363a2e5 100644
--- a/modules/frameworks/网络系统.md
+++ b/modules/frameworks/网络系统.md
@@ -93,11 +93,22 @@ WSSession.ReceiveMessages(PacketType.Data)
 ## 协议变更清单
 
 1. 修改 `.proto` 和 `msg.proto`。
-2. 登记 msgId / route。
-3. 重新生成 C# 代码。
-4. 检查 `HFNetWorkMsgIdMap.cs` / `HFWebSocket_Manager_AutoMsgMap.cs`。
+2. 登记 msgId / route（如 `route.txt` 或对应生成配置）。
+3. 通过生成器重新生成 C# 代码到 `Assets/Game/GameHFScripte/CopyToHF/Network/`。
+4. 检查 `HFNetWorkMsgIdMap.cs` / `HFWebSocket_Manager_AutoMsgMap.cs` 是否同步。
 5. 更新业务入口和监听。
-6. 验证。
+6. 编译 `GameHF` 并运行连接/收发测试。
+
+## 验证
+
+- 构建 `GameHF.csproj`。
+- 在支持服务器的运行环境中登录、收发 C2S/S2C 消息。
+- 确认 `HFEvent_STC_*` 正确派发并在 `OnClose` 时移除监听。
+- 验证错误码事件 `HFEvent_ErrorCode` 触发路径。
+
+## 当前状态
+
+- 待验证
 
 ---
 
diff --git a/modules/模块文档模板.md b/modules/模块文档模板.md
index 4440628..263d570 100644
--- a/modules/模块文档模板.md
+++ b/modules/模块文档模板.md
@@ -50,4 +50,15 @@ TODO：入口 -> 处理 -> 输出
 | [模块登记规则](../rules/30-模块登记规则.md) | 文档分类和结构 |
 | [架构说明](../rules/10-架构说明.md) | 代码分层和依赖方向 |
 
-轻量模块只保留 README。公共 API 较多时增加 `使用指南.md` 或 `开发指南.md`，特殊限制较多时增加 `注意事项.md`；一次性任务文档规则见 [工作流清单](../rules/40-工作流清单.md)。
+## 文档结构
+
+- 轻量模块只保留 README。
+- 公共 API 较多时增加 `使用指南.md` 或 `开发指南.md`，具体判断标准见 [模块登记规则](../rules/30-模块登记规则.md)。
+- 特殊限制较多时增加 `注意事项.md`；一次性任务文档规则见 [工作流清单](../rules/40-工作流清单.md)。
+
+### README 与使用指南的分工
+
+| 文档 | 内容 |
+|---|---|
+| `README.md` | 模块定位、核心组成、使用规则、边界、导航链接 |
+| `使用指南.md` | 详细 API、调用示例、数据流、架构图、最佳实践、边界场景 |
diff --git a/rules/30-模块登记规则.md b/rules/30-模块登记规则.md
index 0288f11..682d631 100644
--- a/rules/30-模块登记规则.md
+++ b/rules/30-模块登记规则.md
@@ -25,6 +25,18 @@
 - 模块发生大改时，讨论保留在对话中；实现后的稳定结论直接更新现有文档。
 - 模块新增、删除、重命名或状态变化时更新模块索引。
 
+### 量化标准
+
+| 维度 | 使用一个 README | 增加使用/开发指南 | 增加注意事项 |
+|---|---|---|---|
+| 核心类/接口数 | ≤3 个 | ≥5 个公共方法或 ≥3 个配置项 | — |
+| 状态机/生命周期复杂度 | 无复杂状态机 | 存在多阶段调用顺序 | — |
+| 公共 API 数量 | ≤5 个 | >5 个 | — |
+| 必须遵守的禁忌/性能约束 | ≤1 条 | — | ≥2 条 |
+| 典型使用示例必要性 | 一句话可描述 | 需要完整调用链示例 | 存在特殊边界场景 |
+
+`README.md` 只保留模块定位、核心组成、使用规则和导航链接；具体 API、调用链、架构图、最佳实践写入 `使用指南.md` 或 `开发指南.md`。
+
 ## 登记规则
 
 - 框架模块放入 `modules/frameworks/`。