# Unity Module Detail

> 对用户指定的子模块/子系统进行分析，产出"项目根目录/AboutMe/<一级模块名>/<子模块名>.md"，内容包含该模块的职责、功能、边界，以及按职责功能划分的所有核心逻辑（枚举清单）。若需对其中某条核心逻辑做全链路详细解析，由 unitygame-core-flow-doc 承接。侧重点：模块级职责/功能/边界 + 按职责功能归类的核心逻辑清单。

- Skill: `eighthoursleep/unity-module-detail` (Agent Skill)
- Install (CLI): `npx skillmds@latest add eighthoursleep/unity-module-detail`
- Raw SKILL.md: https://api.skillmd.com/api/skills/eighthoursleep/unity-module-detail/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: eighthoursleep (https://skillmd.com/u/eighthoursleep)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/eighthoursleep/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. 核心逻辑清单（按职责功能划分，**最重要章节**）
把该模块的**所有核心逻辑**按"职责/功能"归类成若干组（分组要能覆盖该模块全部逻辑，无遗漏），每组下列出核心逻辑点。

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

| 编号 | 所属功能 | 核心逻辑 | 负责类/方法 | 关键数据/状态 | 输入→输出 |
|------|------|------|------|------|------|
| L1 | 战斗·结算 | 伤害计算 | `BattleCalc.CalcDamage` | `BattleContext` | 攻击方/目标 → 扣血结果 |
| L2 | 战斗·流程 | 回合流转 | `BattleMgr.NextTurn` | `turnState` | 玩家动作 → 新回合 |
| ... | ... | ... | ... | ... | ... |

每条核心逻辑的清单项需给出：功能职责一句话、负责类与方法、涉及的关键数据/状态、输入与产出。核心逻辑的**详细解析/全链路深挖**由 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 字"要求一致，全文档表述均适用。