module-finish

Module Finish — 生成模块配置手册

当一个模块完成阶段性开发后，执行本 Skill 为其生成 handbook.md。 handbook 的核心价值：策划或新成员打开这个文件，5 分钟内就能知道这个系统实现了什么、每个功能怎么用、有哪些坑。

---

与现有文档的定位区别

文档	面向	侧重	handbook 是否重复
spec.md	AI 技术速查	接口速查、架构概览、数据格式、JS↔UE 协议	不重复
design.md	人类深度阅读	实现原理、数据流	不重复
changelog.md	历史归档	改动记录、踩坑修复（时序）	提取踩坑到"常见问题"
handbook.md	策划 / 新成员 / AI 快速上手	功能清单 + 配置使用说明 + 常见问题	—

核心原则：先说"实现了什么"，再说"怎么配置"。

• 一、功能总览：列出所有已实现/未实现功能，用 ✅/⚠️/⬜ 标注状态
• 二、功能配置：每个功能独立小节，说明"是什么"→"怎么用"→"可以改什么"→"有什么坑"
• 三、运行全链路：关键流程的步骤追踪（含 Mermaid）
• 四、常见问题：从 changelog 踩坑提炼，用问题现象描述

不写的内容（spec 负责）： 接口速查表、架构概览、代码结构索引、蓝图资产清单、JS↔UE 协议

---

执行步骤

第一步：确定模块名

从用户话语中提取模块名，对应项目的模块路径映射找到路径。 若无法确定，用 AskQuestion 工具请用户选择。

---

第二步：Discovery subagent（只读，精细扫描）

用 Task 工具启动 explore subagent：

subagent_type: explore
readonly: true
model: fast

Prompt 模板（将 <MODULE>、<SRC_PATH>、<CONTENT_PATH> 替换为实际值）：

你是 <MODULE> 模块的精细扫描员，目标是提取出所有配置相关的精确信息供后续生成文档使用。

## 任务 1：扫描所有 .h 文件

扫描 `<SRC_PATH>` 下所有 .h 文件，对每个 UPROPERTY 属性提取以下所有信息：

格式要求（每个属性一行）：
  类名.属性名 | 类型 | UPROPERTY说明符 | meta值 | 头文件行内默认值 | 含义（来自注释）

特别关注以下信息（必须提取，不能省略）：
- `meta=(ClampMin="X", ClampMax="Y")` — 值的硬限制范围
- `meta=(UIMin="X", UIMax="Y")` — 编辑器 UI 显示范围
- `= X` 或 `{X}` 的内联初始化默认值
- `UPROPERTY` 说明符中的 `EditAnywhere` / `EditDefaultsOnly` / `EditInstanceOnly`
- 属性上方或右侧的注释（`//` 或 `/* */`）作为"含义"
- 枚举类型属性：必须同时提取该枚举的全部可选值和各值的注释

对 .cpp 构造函数中的赋值也要提取（如 `MyProp = 100.f`），作为默认值补充。

同时提取：
- 所有 `IConsoleVariable` CVar 声明及默认值
- 所有 `UFUNCTION(Exec)` 函数（控制台可调用命令）
- 所有 `static constexpr` 常量

## 任务 2：扫描 JSON 配置文件

扫描 `<CONTENT_PATH>` 下所有 *.json 文件。
对每个文件：
- 读取完整内容
- 列出每个顶层字段名、类型、是否在数组中出现过
- 如有嵌套对象，也要列出嵌套字段

## 任务 3：DataTable 路径搜索

用 Glob 搜索 `Content/**/DT_*.uasset` 找出与 <MODULE> 相关的 DataTable。
同时搜索 `Source/**/*.h` 中以 `USTRUCT` 且文件名含 <MODULE> 或与配置相关的结构体。
对每个找到的 USTRUCT 行结构，提取所有字段名、类型、注释。

## 任务 4：文档状态检查

检查以下文件是否存在并读取摘要：
- `AI_Docs/<MODULE>/spec.md`（读取前 30 行，了解 spec 已覆盖哪些内容）
- `AI_Docs/<MODULE>/design.md`
- `AI_Docs/<MODULE>/changelog.md`（读取最近 80 行，提取踩坑记录）

## 输出格式

### 1. UPROPERTY 精细清单
格式：类名.属性名 | C++类型 | 编辑位置 | 默认值 | 范围 | 含义

### 2. 枚举值详细表
格式：枚举名 → 值名 : 数值 | 含义

### 3. JSON 字段清单
（若无 JSON 文件则写"无"）

### 4. DataTable 行结构体字段
格式：结构体名（对应DT路径） → 字段名 | 类型 | 含义

### 5. 文档文件状态 + spec 已覆盖内容摘要
spec.md: 存在/缺失（已覆盖：...） | design.md: 存在/缺失 | changelog.md: 存在/缺失（踩坑记录摘要：...）