编写功能文档（行为说明书）

Overview

功能文档 = 玩家/用户视角的行为说明书：只写「进行什么操作，出现什么效果」，严禁任何 API/实现细节。流程：规范先行 → 代码挖行为 → 并行编写 → 缺陷排队 → 状态标注。适用于从已有代码库反向产出 QA/策划/新成员可读的功能参考。

边界：本技能管功能文档的内容与生产流程；Markdown 排版格式（序号、wikilink、callout、frontmatter）由 dev-docs 技能管——写功能文档时两者同载。写需求文档、技术清单、设计文档等其他文档不用本技能，直接用 dev-docs。

When to Use

• 为已有项目补写功能/行为文档，"分析现有功能写文档"
• 需要 QA 不看代码就能逐项验证的验证基准
• 设计图/需求与实现需要对齐盘点（差异→缺陷清单）

不适用：需求文档（写"应该怎样"）、技术清单（写代码资产在哪）、API 参考。

流程

0. 规范先行（必须先做）

先产出一份《功能文档编写规范》让用户改，定稿后才动手写。规范核心条款（直接复用）：

1. 一个系统一个目录 功能/<系统名>/；每篇文档只写一个功能点，文件名=功能名；禁止合并长文档
2. 每目录一份 _概述.md：系统简介 + 术语表 + 按键速查 + 功能清单（wikilink）+ 共用前提
3. 单篇字段：操作 / 条件 / 效果 / 他人视角 / 边界 / 数值 / 状态（操作、条件、效果、状态必选；无条件写「无」）
4. 玩家语言：写「右手扣扳机」「飞轮脱离环绕飞出」，不写「触发发射」「对象池取出」
5. 禁 API：类名、函数名、文件/资产路径、变量名、配置项名、RPC/网络机制、实现机制（对象池/定时器/Tick/状态机）——出现即不合格
6. 只写可观察行为，每条必须能在游戏内操作复现；写现状不修饰，疑似缺陷如实描述现象不猜原因
7. 状态三值：已验证 / 待验证 / 疑似缺陷（可扩「待实现」给已定设计未实施项）

1. 行为挖掘（只读代码）

| 要挖的 | 方法 | 陷阱 | |---|---|---| | 输入→行为映射 | 输入绑定代码 + 按键映射资产 | 二进制映射资产（UE IMC 等 uasset）：rg --text 只能提取出现的名字，丢失 动作↔按键 关联（导入表排序）。必须结构化 dump——UE 用无头 UnrealEditor-Cmd -run=pythonscript 读 mappings 写文本再读回 | | 配置真值 | 蓝图/资产 CDO dump，不能只信代码默认值 | 代码默认 1，资产可能覆盖成别的；反之改代码默认值未必生效（资产有覆盖） | | 可观察行为 | 读 overlap/委托/Tick/定时器逻辑，逐条翻译成玩家语言 | 定时器冷却=「约0.5秒内重复扫过只算一次」；对象池回收=「飞回后重新出现」 | | 加速度 | 项目既有技术清单/检查文档 | 旧文档结论可能过时（门控已删、占位已实现），以当前代码为准并回报过时点 |

按键名翻译表：引擎键名 → 玩家语言（如 PICOTouch_Right_A_Click → 「右手 A 键」），写进共享上下文。

2. 编写

• 效果写全感官通道：视觉 / 听觉 / 触觉（震动强度、时长）
• 多人游戏必写他人视角（本人看到 ≠ 其他玩家看到）
• 数值区分来源：代码确认的写准确值，目测标「约」；给出推导（如「血量 200，4 次击杀 → 伤害 50」）
• 交叉引用用 wikilink；引用其他系统只作前提（「能量模式激活（见能量系统文档）」），不展开
• 自查：grep 禁词（类名正则、.cpp、Source/、/Game/、RPC、对象池、Tick、蓝图）零命中

3. 缺陷排队（不边写边修）

发现现状与设计/直觉不符 → 记入集中 缺陷.md，不在文档阶段修代码。每条：

### 缺陷 N：标题 ⬜
- 现象 / 影响 / 证据（文件:行号 或 dump 产物，可复验）/ 可选方向

状态机：⬜待决定 → 📌方案已定待实施 → 🔧修复中 → ✅已修复 / ❌不修。设计图优先级高于代码现状：冲突时按设计写文档并 ⚠️ 标注「当前版本与设计不一致」+ 缺陷条目。用户最后统一回复修复方案。

4. 并行分派（多系统时）

每系统一个子 agent，一次批处理全发。共享上下文必须含：规范路径、1-2 个范例文件、按键翻译表与已知占用、设计原文相关段、缺陷上报 JSON 格式（标题/现象/影响/证据/建议）、输出契约 {system, docs[], defects[], uncovered}。缺陷由主会话统一汇总，agent 不写缺陷.md。明令：只读代码、跳过构建测试、禁 git。

5. 验证与交付

无法上机（VR/设备）→ 全部「待验证」，如实声明，交付用户/QA 逐条核对后改状态。禁止把未亲验的条目标「已验证」。

Common Mistakes

• 用 rg 扫二进制输入资产后猜按键映射 → 关联已丢失，必须 dump
• 边写文档边修缺陷 → 范围爆炸；全部排队统一决定
• 把设计目标当现状写（无 ⚠️ 标注）→ 文档撒谎
• 术语漂移（同一个东西两个名字）→ 术语表收口，用户定的名字优先（用户会口误，确认后统一）
• 文件夹拆分意图不明时直接猜 → 问一次比返工便宜
• 旧技术文档的 WARNING 直接抄 → 先对当前代码复核

项目特定配置

位置 <ProjectRoot>（如 UE5 VR 项目），文档落 Docs/功能/。

规范与台账位置

• 规范：Docs/规范/功能文档编写规范.md——先读，格式/字段模板/禁止事项以它为准
• 缺陷台账：Docs/功能/缺陷.md——连续编号，状态机 ⬜待决定 / 📌方案已定待实施 / 🔧修复中 / ✅已修复 / ❌不修
• 范例：Docs/功能/武器系统/（_概述.md + 飞轮/发射飞轮.md）
• 分析源：Docs/检查/<系统>.md（若有）——已有代码资产分析，只取「玩家可观察行为」，不照抄技术细节

术语与易错点

• 近战武器叫「剑」（用户曾口误说斧子，已纠正）；飞轮 = 斧（Axe），同一个东西
• 跳跃触发 = 双侧键（握把）+ 上抬手势，不是扳机（用户纠正过设计图解读）
• 战斗/游览模式切换入口：用户曾删左手 Y 方案，后续确认以菜单 UI 切换（引用前先看 Docs/功能/缺陷.md 最新状态）

实证工具（Saved/Temp/，不进 git）

• DumpImcAdmin.py——IMC 映射 dump（Admin 路径已配）→ ImcDump.txt；DumpBp.py——BP CDO 属性 dump（Sx 路径，用前 sed 改 Admin）
• 无头跑法：UnrealEditor-Cmd.exe <uproject> -run=pythonscript -script=<py> -unattended -nop4 -nullrhi（~15s）。⚠️ rg --text 扫 IMC uasset 只能拿按键名列表，IA↔按键配对因 import 表排序丢失，必须无头 dump
• 引擎：C:/Users/Admin/Project/UnrealEngine（源码版，Launcher 版缺 PICOOpenXR）
• PICO 按键翻译表（ImcDump → 玩家语言）：Left/Right_X/Y/A/B_Click→左/右手 X/Y/A/B 键；Trigger_Click/Axis→扳机；Grip_Axis→握把（腰部键/侧键）；Thumbstick_2D/X/Y→摇杆推动/左右/上下；Thumbstick_Click→摇杆按下

批量编写模式（已验证：12 系统 76 篇一次完成）

1. 主会话先做共享上下文：IMC dump、按键占用表、设计图相关段落、规范/范例路径
2. 每系统一个子 agent，一次批处理全发（prompt 含：规范路径、范例路径、调研源文件、设计图相关段落、按键表、缺陷上报 JSON 格式）
3. 子 agent 结果 JSON：{system, docs[], defects[{标题,现象,影响,证据,建议}], uncovered}
4. 主会话统一：合并缺陷进 缺陷.md（跨系统去重、连续编号）、grep 自查 API 泄漏（UV?R[A-Z]\w+|\.cpp|Source/|/Game/|RPC|蓝图|对象池，仅缺陷.md 与旧模块文档允许命中）、更新 MOCs/功能索引.md

状态诚实（本机约束）

本机无 VR 头显，无法上机验证——所有篇目标「待验证」，交付时明确告知用户需 QA 核对后改状态。禁止把未上机的条目标「已验证」。

Real-World Impact

UE5 VR 实战：1 天产出武器系统 7 篇 + 规范 + 缺陷 7 条；发现 3 个输入无键位映射的隐藏缺陷（rg 扫资产误判为已映射，无头 dump 才实证）；9 系统并行 agent 单批分派。后验证批量模式：12 系统 76 篇一次完成。