Unity Module Detail

Unity 子模块核心逻辑清单（模块级文档）

目标

承接 unity-module-overview 的输出，对用户指定的一个子模块/子系统分析，产出该模块的模块级文档：讲清它的职责、功能、边界，并把该模块的所有核心逻辑按职责功能归类枚举，作为该模块内容的"总目录"。更细的全链路解析由 unitygame-core-flow-doc 技能承接。

本文档边界 = 模块级清单层：一份文档讲清"这个模块是做什么的、有哪些核心逻辑"。不重复模块间依赖全景（那是 module-overview 的职责）；不对单条核心逻辑做超长的全链路深挖（那是 core-flow-doc 的职责）。

前置依赖

• 若提供模块名称，根据上下文（一级模块路径、项目根目录/AboutMe/<一级模块名>.md 子模块清单）定位物理路径。
• 若提供路径，直接使用。
• 该模块在整个一级模块中的定位与依赖，参考 项目根目录/AboutMe/<一级模块名>.md（module-overview 产出）。
• 衔接：本文档产出自每个子模块一份 AboutMe/<一级模块名>/<子模块名>.md；与本文件同处 AboutMe/<一级模块名>/ 内的同名 <子模块名>/ 子目录，即 core-flow-doc 的落盘目录。

一级模块归属判定（决定输出目录）

输出路径为 项目根目录/AboutMe/<一级模块名>/<子模块名>.md，故须先定出 <一级模块名>，再定 <子模块名>。判定顺序：

1. 用户已指名一级模块：直接采用用户给的名称。
2. 用户只给子模块名：依次遍历 项目根目录/AboutMe/ 下除 Overview.md 外的 <一级模块名>.md，在其"子模块清单"表中按子模块名精确匹配；命中文件的主干名即 <一级模块名>。
3. 用户给的是子模块的物理路径：先取 AboutMe/Overview.md 的"一级模块清单"，按"对应目录路径"列做最长前缀匹配，命中行的模块名称即 <一级模块名>；再用 AboutMe/<一级模块名>.md 的子模块表核对 <子模块名>。
4. 以上均未命中：退回代码扫描（图谱 / 目录遍历），定位该子模块的类群归属哪个一级模块目录，取其模块名称。
5. 同名歧义或索引缺失：子模块名在多个一级模块下同名出现（如"建筑"同时属于"城建"与"内政"），或 AboutMe/Overview.md、AboutMe/<一级模块名>.md 缺失时，列出候选并询问用户，不得自行猜测。

两条命名约定（不遵守会导致产出与 Overview.md 的目录树对不齐）：

• <一级模块名> 取文档中的模块名称（如"城建"），不取物理目录名（如 City）；两者不一致时以文档名称为准。
• <子模块名> 取 module-overview 子模块清单中的条目名（如"建筑"），不取目录名。

输出文档结构（必须包含以下章节）

1. 功能定位

用简短篇幅（1 段）说明该模块在整个系统中定位、解决什么问题。

该"模块"是按逻辑职责聚合而成的一个整体——通常由类名前缀相同的一组类（如 Battle 前缀下的 Ctrl / Data / View）共同构成。内置划分规范（随本技能分发，母本存 ClaudeSkills/_shared/module-division-guide.md，复制后母本不可达按本段执行）：按逻辑职责划分、同类前缀归并（Battle* 同属战斗模块）、判定优先级 逻辑职责→前缀/命名空间→目录。解析时注明该模块所属大类（B=底层 / F=框架 / A=应用）及其在"应用→框架→底层"分层中的位置。

2. 职责（Responsibility）

列出该模块承担什么——一句话主职责 + 分点职责，每点简短。职责说明"做什么"。

3. 功能（Features）

列出该模块对外提供的能力/接口——有哪些功能点、关键接口方法、可供谁调用。功能列表与职责对应。

4. 边界（Boundary）

明确该模块刻意不做什么（如"不直发协议""纯数据只读""纯表现、被动接收"），以及它依赖谁 / 被谁依赖（一句话），帮助界定清晰的责任划分。

5. 核心逻辑清单（按职责功能划分，最重要章节）

把该模块的所有核心逻辑按"职责/功能"归类成若干组（分组要能覆盖该模块全部逻辑，无遗漏），每组下列出核心逻辑点。

对每个核心逻辑点，给出清单一项（简洁条目，非全链路深挖）：

每条核心逻辑的清单项需给出：功能职责一句话、负责类与方法、涉及的关键数据/状态、输入与产出。核心逻辑的详细解析/全链路深挖由 core-flow-doc 承接，本处标注衔接入口即可（如"(全链路解析见 core-flow-doc 输出)"）。

6. 技术要点速记

6.1 高频问答

6.2 常见陷阱

6.3 性能优化

与 unitygame-core-flow-doc 的分工

• 本 skill（module-detail）产出的 AboutMe/<一级模块名>/<子模块名>.md，是"包含该模块所有核心逻辑的清单"。
• 当需要对其中某条核心逻辑做逐步骤、带源码证据、跨模块全链路的详细解析时，由 unitygame-core-flow-doc 承接，它从本条核心逻辑出发展开到"入口 → 模块流转 → 网络协议 → 收尾表现"。
• 二者关系：核心逻辑清单（detail）→ 单条核心逻辑详细解析（core-flow-doc）。
• 落盘关系：core-flow-doc 的单条流程文档落于 AboutMe/<一级模块名>/<子模块名>/ 目录下，即本清单文件的同名子目录内。二者同在 AboutMe/<一级模块名>/ 之下，配套使用（清单是索引、流程是展开）。

执行步骤

1. 定位该模块的物理路径，并按上文"一级模块归属判定"定出 <一级模块名> 与 <子模块名>。
2. 通读其核心文件，识别职责、功能、边界。
3. 将模块的所有核心逻辑按职责/功能归类，逐类枚举并填清单表。
4. 提炼技术要点。
5. 输出 Markdown 文档到 项目根目录/AboutMe/<一级模块名>/<子模块名>.md（一份子模块一份文件）。若 <一级模块名> 目录不存在则先创建。

约束

• 本文档边界 = 模块级清单层：产出该模块的职责/功能/边界 + 按职责功能划分的所有核心逻辑清单；不重复模块间依赖全景（module-overview），不做单条核心逻辑的全链路超长深挖（core-flow-doc）。
• 核心逻辑清单必须按职责功能归类且覆盖该模块所有核心逻辑，无遗漏。
• 结果保存为 项目根目录/AboutMe/<一级模块名>/<子模块名>.md。
• 输出层级固定为两级目录，不得落回 项目根目录/AboutMe/<子模块名>.md 的平铺路径。
• 同名共存说明（同名不同物，互不覆盖）：
  • AboutMe/<一级模块名>.md（文件）是 module-overview 的产出；AboutMe/<一级模块名>/（目录）是本 skill 建立的。二者同名共存，不得写入或删除前者。
  • AboutMe/<一级模块名>/<子模块名>.md（文件，本 skill 产出）与 AboutMe/<一级模块名>/<子模块名>/（目录，core-flow-doc 建立）同理同名共存。
  • 路径段须为合法文件名字符串，不得含 \ / : * ? " < > |，不得以 . 或空格结尾。
• 同名冲突防护：生成前检查目标路径 项目根目录/AboutMe/<一级模块名>/<子模块名>.md 是否已存在。若已存在且非本模块产出，先向用户确认再覆盖，不得静默覆盖他人文件。
• 旧路径遗留检测（必须先检测再写入）：写入前检查 项目根目录/AboutMe/<子模块名>.md（旧平铺路径）是否存在。
  • 存在时先暂停写入，向用户说明"检测到旧路径文档 AboutMe/<子模块名>.md"，并给出选项：迁移到新路径后继续 / 保留旧文件、另写新文件 / 本次不写入。
  • 用户未确认前，不得覆盖、不得删除、不得移动旧文件。
  • 旧路径上可能是其他一级模块下的同名子模块文件。命中时先读该文件内容确认归属；归属不明时按"询问用户"处理。
  • 若 <子模块名> 为 Overview，须排除 project-overview 的 AboutMe/Overview.md，不得误判为遗留文件。
  • 迁移后遗留的旧空目录由用户自行清理，本 skill 不代为删除。
• 禁止静默忽略：不得因旧文件存在就直接跳过写入，也不得在未提示用户的情况下另起新文件。
• 中文行文约定：禁止长串的句子，或把几个句子连在一行/一段。必须一句话一行；即使描述一件事用了一个长句，也要拆成多行单句。与核心流程的"每行不超过 20 字"要求一致，全文档表述均适用。