需求文档标准化
目的
把零散材料或旧版需求文档，整理成符合《标准需求文档模板》的需求文档；或对现有文档做结构体检。目标是文档结构规范、可直接评审，且术语、规则、叫法表述清楚——评审、研发与后续系统解析都省事。
边界：不写技术方案（表结构、接口协议、框架选型归研发）；不输出模板之外的附加文档。
三种模式
| 模式 | 识别信号 | 输入 | 产出 |
|---|---|---|---|
| 创建 | 用户给零散材料（聊天记录、会议纪要、旧片段、原型说明），要"写一份需求文档" | 一份或多份材料 | 标准文档 + 未决缺口说明 |
| 优化 | 用户给一份现有需求文档（.docx/.md），要"按模板整理 / 规范化 / 重排" | 一份现有文档 | 标准版 + 变更说明 |
| 审查 | 用户要"检查 / 体检 / 看看有没有问题 / 评审前自查"，明说"先不要改" | 一份待检文档 | 体检报告（问题清单 + 建议追问），不改写文档 |
判断优先级：用户说"别改 / 只看问题"→ 审查；输入是一份完整文档 → 优化；输入是片段材料 → 创建。
标准与轻量：用户说"小需求 / 优化项 / 配置变更 / 改个页面 / 只改一个按钮"这类小改动 → 轻量模式；新模块、新功能、跨系统需求 → 标准模式（默认）。拿不准时问用户一句。
开工前必读
按顺序读取（可随上下文取舍，但标准模板与检查清单每次必读）：
references/标准需求文档模板.md—— 唯一基准，所有产出以它为准；references/写作规范与检查清单.md—— 质量判据（成文自检、审查判据都用它）；references/术语与规则写法.md—— 术语/规则/业务对象/数据流向的处理方式；references/旧文档处理.md—— 读旧文档前必读（三类标题写法、目录行、空容器、"无/暂无"的处理）；references/表达规范.md—— 成文后对 S3 自由文本做表达自检（见第 3 步；表格、规则、提示原话豁免）。
不必通读：assets/空白模板.md（仅用户索取空白模板时使用）、scripts/check_prd.py 源码（直接看脚本输出即可）、与当前模式无关的参考（如创建模式跳过旧文档处理）。技能目录下的 scripts/（docx 转换、Word 导出、体检脚本）按需使用。
输入处理
.docx先转 Markdown：python3 <skill目录>/scripts/docx2md.py "文件.docx"；图片会提取到同名.assets/media/目录，并自动生成.assets/preview/缩略图。旧版.doc请先另存为.docx。- 图片不逐张目检：转换后图片在 Markdown 中的出现位置即对应章节，先按位置完成图-节映射、直接使用；只在文字与原型可能冲突或映射存疑时，查看
preview/缩略图核对。原图仅用于成品嵌入。 - 多份材料全部读入；记录每份材料的来源与时间，冲突信息列入待确认问题（不自行取舍）。
- 如用户提供既有术语表或命名规范，先查重：已有术语沿用其标准叫法，不另造词。
通用工作流（创建 / 优化）
第 1 步 缺口分析，先问清再动笔
读完材料后，先做缺口分析并与用户确认，再动笔。问答规则：
- 问什么：只问真正影响成文的问题（口径、阈值、状态、权限、异常处理），按「影响 × 不确定性」排序；材料齐全时 0 个，直接进第 2 步。
- 一次问完、默认不超过 4 题：把缺口按「影响 × 不确定性」排序，在一条消息里一次列全，每题给 2-4 个选项 + 标注推荐项 + 一句推荐理由。默认取前 4 个——4 是防止一次淹没用户的经验值，不是硬上限：缺口多、彼此独立、或用户愿意多答时，可适当增加；无论问几个，关键缺口优先，其余按「缺口不写入、进交付说明」处理。禁止逐题往返。
- 每批格式：题号带总数（Q1/2），题尾固定提示「可逐条回复；回『全部按推荐』按推荐直接出稿，回『跳过全部』全部缺口进交付说明」。示例：
```markdown
Q1/2：单批次开票数量上限（决定 R 规则取值）
推荐 B —— 沿用现有待开票列表 500 个上限，与既有校验逻辑一致。
| 选项 | 说明 |
|---|---|
| A | 100 个（保守，防误操作） |
| B | 500 个（沿用现有限制） |
| C | 不设上限（数量由后台配置） |
| 自定义 | 给出自己的数值或条件 |
Q2/2：……
可逐条回复（如「Q1-B、Q2 按推荐」）；回「全部按推荐」按推荐直接出稿；回「跳过全部」全部缺口进交付说明。
```
- 用户可回字母（A/B/C）或直接给短答；答案有歧义时追问一句消歧（不计入题数）。收到回复后不复述、不总结已确认答案，直接进入第 2 步。
- 铁律：缺信息不编造。被跳过或未提问的缺口，未确认的实现不写入正文，也不在文档中留未决标记——缺口只在交付说明里列出。
- 「直接出稿」不等于可以编造事实：用户说「直接出稿 / 按合理默认处理」时，放宽的是结构与表达（章节取舍、措辞、聚合），不是事实。提示原话、阈值数值、状态取值、口径仍必须来自材料；材料没给的，正文只写能确定的行为（如「阻断 / 跳过」），文案与数值留白并列入交付说明的缺口。编一句像样的提示文案比留白更糟——它会被研发和测试当成真的。
第 2 步 成文 / 重排
按《标准需求文档模板》逐节生成：
- S1 表格（文档头、功能清单、术语、输入输出、业务规则、评审、变更）：按表头生成，空值留白而不编造；
- S2 骨架（功能说明六要素、验收要点、非功能需求）：按骨架草拟，其中"处理逻辑、异常与提示"只能来自材料，不发明；
- S3 自由文本（背景、痛点、方案取舍）：优先使用材料原话，不代写论证；
- S4 图与素材：转换时已提取到
.assets/的图片，直接用嵌入显示，不再写引用路径文字；对不上号或只有文字说明没有图片文件的，才用【材料名称】占位并写清图名与文件位置。绝不嵌入不存在或对应关系拿不准的图。 - 1.3 业务流程 / 1.4 数据视图：1.3 画跨功能端到端主干——业务流程图原图优先（嵌入
![]()），没有原图用 mermaidflowchart，含状态机时加stateDiagram-v2状态流转图；1.4 有新增/变更业务对象才画概念模型（erDiagram，否则声明「不涉及新业务实体」），并按需给数据流向。节点/实体叫法 = 1.2 术语，只画业务语言，不写接口、表名等实现细节。画法、优先级与要素细则见references/标准需求文档模板.md§3.1.3 / §3.1.4。
篇幅纪律（创建与优化都适用；预算口径与压缩顺序以 references/标准需求文档模板.md §4.8 为准）：
- 优化模式默认把总篇幅控制在源文档的 0.8～1.2 倍（体检带，非硬门槛）；动笔前
wc -m校对源文档字数，偏离时按内容完整度判断并在变更说明里注明理由；创建模式宁短勿长。 - 骨架从简：六要素中多个不适用合并为一行，同一信息只写一次。
- 聚合：同类小改动（加列、加筛选、改文案）合为一节，功能清单同步聚合，不一个字段一节。
- 事实、数值、提示原话永不压缩。
轻量模式纪律：第 1 章以 1.5 功能清单为主，其余节写「本次需求不涉及」；流程/数据有变化的保留最小 1.3/1.4（主干一行 + 变更点）；第 4 章直接声明不涉及；第 2、3、5 章照常完整填写——轻量省的是无关章节，不是功能说明与业务规则的质量。
优化模式额外纪律（改写尺度细则见 references/旧文档处理.md §3）：
- 只做四件事：重排（章节归位）、补齐（六要素缺项与用户确认后补上）、集中（散落的数据层约束按收录门槛汇总到第 3 章业务规则，宁缺毋滥——页面交互约束归 2.x.4 交互细节，不进规则表）、显式化（空转术语节补定义或声明不涉及）。
- 事实、数值、口径、提示原话一个字不改；原文含糊处先与用户确认，不替它拍板；原文没有的信息不添加。
- 原文里的格式掩码与占位模板（如批次号
XXXXXXXX-XXXXXXXX-XXXXXXXX、提示模板中未代入的占位符）按原样保留，逐条登记到变更说明——这类不是「占位残留」，不要清掉或改写。 - 产出后附「变更说明」：重排了哪些、汇总了多少条规则、补了多少术语、缺口有多少。
第 3 步 写法自检
按 references/术语与规则写法.md 第 5 节过一遍：术语定义完整、叫法统一、规则条条过四条门槛（宁缺毋滥）、字段名能对上术语、数据视图（概念模型/数据流向）明确。
表达自检（按 references/表达规范.md）：只对 S3 自由文本（背景、痛点、目标、方案取舍、叙述性处理逻辑）去模板腔与 AI 句式壳、调整段落节奏；S1 表格、S2 骨架、术语表、业务规则表、提示原话、数值与状态名一律豁免，一个字不改。
第 4 步 质量自检
- 运行
python3 <skill目录>/scripts/check_prd.py <产出文档> [--baseline <源文档>] --json "$(mktemp "${TMPDIR:-/tmp}/check_prd.XXXXXX")"（优化模式加--baseline核对篇幅；JSON 写临时文件供本步解析，用完即删，不留在用户目录），处理所有"高"级问题（合法格式掩码脚本会判"低"并提示登记，登记进变更说明即可）；"中"级问题（术语空转、空壳字段、未决标记等）逐项处理； - 定向抽查、不做全文复读：抽查《写作规范与检查清单》第 5 节的高风险项（缺异常、模糊表述、提示无原话、清单与说明不对应、术语空转、占位残留、篇幅膨胀）——重点看术语表、业务规则表、功能清单与第 2 章对应关系、各节「异常与提示」；
- 逐条替换模糊表述（快速、友好、灵活、尽量、必要时……）为具体数值或条件；
- 篇幅核对：
check_prd.py --baseline会给出比例；偏离 0.8～1.2 倍时，压缩顺序与处理口径见references/标准需求文档模板.md§4.8（事实与提示原话不动）。
第 5 步 交付
- 输出 Markdown 到用户指定位置；未指定时：优化模式默认
<原名>-标准版.md，创建模式默认<需求名称>-产品需求说明书.md（与输入同目录）。 - 默认只产出 Markdown，不主动生成 Word。 仅当用户明确要求 Word 时：
bash <skill目录>/scripts/md2docx.sh <文件.md> [--ref 参考模板.docx]。 - 流程图、概念模型等一律保持 mermaid 文本 DSL（md 与 Word 中都是代码块），不转成图片。
- 交付物 = 标准文档 +（优化模式）变更说明 /（创建模式）未决缺口说明（在对话中给出，不写入文档；条目化、不复述文档内容）。
- 结尾用一句话提示：文档已按标准模板整理，可直接进入评审。
审查模式
- 先跑脚本：
python3 <skill目录>/scripts/check_prd.py <文档>拿到确定性结果（结构缺失、占位残留、空转、六要素、模糊词等）。 - 再做语义审查：对照《写作规范与检查清单》第 5 节常见错误清单，逐章读，重点查：
- 口径矛盾（同一字段/状态在不同章节表述不一致）；
- 状态流转（取值全不全、流转条件、终态）；
- 权限与角色（谁能操作、数据可见范围）；
- 异常与边界（超限、空值、重复操作、上游失败）；
- 数据来源与去向（是否说清；1.4 概念模型 / 数据流向是否与 1.2 术语及第 3 章规则字段叫法一致）。 - 输出体检报告，问题格式：
级别（高/中/低） ｜ 位置 ｜ 问题 ｜ 建议追问；结论给三档：通过 / 修改后通过 / 需补充材料。 - 不改写文档。用户看过报告要求修改时，转入优化模式。
体检报告骨架：
# 需求文档体检报告 · <文档名>
> 结论：通过 / 修改后通过 / 需补充材料 ｜ 脚本检查与语义审查综合
## 一、脚本检查结果摘要（check_prd.py）
（总览表 + 高优先级问题）
## 二、语义问题清单
| # | 级别 | 位置 | 问题 | 建议追问 |
## 三、建议动作
（按优先级列出：先补什么、再改什么）
质量原则（为什么这么做）
- 结构稳定优先：AI 在需求文档上的角色是"整理与查漏"，不是"创作"。改写越流畅，越容易把脑补写成事实——所以先问清、事实保真、缺口对话确认。
- 术语一个叫法、规则一条一事：这既是评审读得懂的前提，也是后续能被系统正确解析的前提。
- 语言短句直述：短句 + 编号 + 直述；去掉形容词与副词；不写宣传语（不出现"赋能、闭环、抓手、生态"这类词）。
- 缺口不进文档：不确定的实现与用户对话确认；未确认前不写入正文，也不留未决标记。
- 把时间花在事实上：图片按位置映射、提问批量 ≤4、自检靠脚本 + 定向抽查、篇幅按预算压缩——省下来的时间不牺牲事实、数值与提示原话。
脚本与素材
（参考文档清单见上文「开工前必读」。）
| 文件 | 何时用 |
|---|---|
assets/空白模板.md |
用户要空白模板时直接给 |
scripts/docx2md.py |
.docx 输入（纯标准库，含目检缩略图） |
scripts/md2docx.sh |
需要 Word 产出 |
scripts/check_prd.py |
体检 / 成文后自检（--baseline 核对篇幅） |
常见误区
- 模板之外的内容（额外的模型图、分析文档）不强行要求；流程图、原型图：有原图（已提取文件）就嵌入，没有才用占位与文字说明承载。
- 不要删改原文里的具体数值、状态名、提示文案——它们是要被研发和测试消费的。
- 不要用"建议采用 XXX 方案"替研发做技术决策。
- 不要逐张目检原型图、不要为自检全文复读、不要逐题往返提问——问题批量 ≤4 题一次问完，自检以脚本 + 定向抽查为主。
- 不要因为用户说「直接出稿」就编造提示原话或阈值——「直接出稿」放宽的是结构，不是事实；材料没给的文案与数值进交付说明，不写进正文。
- 不要主动产出 Word：默认交付 Markdown，仅用户明确要 Word 时才生成；流程图、概念模型保持 mermaid 文本 DSL，不转图片。
