需求文档/PRD模板生成

适用场景

• 脑子里有个产品想法，但落到文档就只会写「做一个 XX 平台」，功能、边界、验收全空着
• 写出来的需求被开发打回三次：规则不写死、边界没列、验收标准没有，实现出来和自己想的差一个银河系
• PRD 章节东一块西一块，评审时被问「不做哪些？」「失败了界面怎么表现？」当场卡壳
• 功能一股脑全标 P0，排期时谁都砍不动，等于没有优先级
• 拿到一份需求想先快速判断「能不能拿去评审」，不想到处翻

核心能力

1. 十段式骨架：按「背景 → 问题 → 目标与成功指标 → 非目标 → 用户与场景 → 功能需求 → 约束与非功能需求 → 验收与上线度量 → 里程碑与排期 → 开放问题」生成完整 PRD，缺哪段就原地标⚠️待补充并说明为什么必须写，不会留白装没事。

2. 功能五件套：每条功能自动展开「用户故事 / 功能描述 / 业务规则 / 边界与异常 / 验收标准」。规则建议写成能直接翻译成 if-else 的句子，验收建议用 Given-When-Then 句式——这是 PRD 质量的分水岭，本技能强制提醒。

3. 完整性体检（本技能的核心差异点）：确定性脚本按章节权重打基础分（满分 100：功能需求 20 分最高、目标 14 分、问题 10 分…），再用规则识别质量问题并按「涉及条目占比」缩放扣分（3 条功能里 1 条缺规则，不会按全缺来罚，最低扣 1 分）。最终分 = 基础分 − 扣分，低于 0 按 0 计。≥85 可进评审 / 65-84 建议补齐 / <65 会被打回。

4. 目标可衡量性检查：目标没写清「用什么指标、达到多少」会被单独拉出来，提示补 metric + baseline + target，否则上线后没人说得清做成没有。

5. P0 膨胀检测：功能 ≥4 条且 P0 占比超 50% 即告警「全都是最高优先级等于没有优先级」，建议 P0 控制在三分之一以内。

6. 依赖悬空检测：功能 depends 里引用了本文档未定义的 id 或名称，提示确认是外部系统提供还是漏写了条目（带「外部」字样的不算悬空）。

7. 高频遗漏盲区扫描：用 10 个资深 PM 的隐性 checklist（权限、异常与失败、空态与首次使用、数据迁移与兼容、埋点与度量、灰度与回滚、性能与容量、安全与合规、多端与适配、文案与提示）扫描全文，列出文档里完全没涉及的维度，每项配一句「为什么要想」。这些正是评审现场最容易被问倒、上线后最易出事的地方。

8. 审计模式：--audit-only 只出体检报告不出正文，适合在动笔前或评审前快速过一遍硬伤。

9. 依赖拓扑排序与循环依赖检测（v1.0.2 新增）：根据功能间的 depends 关系给出建议开发顺序（依赖项排在依赖方之前），并检出循环依赖——循环依赖会导致根本无法排期，必须在评审前打破。

10. 优先级分布与范围基线（v1.0.2 新增）：统计 P0-P3 各档条数，P0 占比超三分之一时告警；帮你一眼看出「是不是又全标成最高优先级了」。

输入规范（缺失主动引导）

脚本输入为 JSON（完整字段说明见 references/input_template.json）：

{
  "product": "客户工单系统",
  "module": "工单自动分派",
  "author": "李明",
  "version": "v0.2",
  "date": "2026-08-04",
  "reviewers": ["技术负责人 王磊", "客服中心 赵芳"],
  "background": "客服中心日均工单 3200 条，目前由主管手工点派……",
  "problem": "工单从提交到被接手等待过久，且分派只看谁空闲不看谁擅长……",
  "goals": [
    {"desc": "缩短工单等待时长", "metric": "工单平均等待时长", "baseline": "27 分钟", "target": "3 分钟以内"},
    {"desc": "让主管从点派单里解放出来"}
  ],
  "non_goals": ["不做跨租户工单分派", "不改造工单表单字段"],
  "users": [
    {"role": "客服主管", "scene": "早高峰工单积压时批量处理", "pain": "手工点派点不过来，经常漏派"}
  ],
  "features": [
    {
      "id": "F1",
      "name": "按技能标签自动匹配坐席",
      "priority": "P0",
      "owner": "王磊",
      "user_story": "作为客服主管，我希望系统按工单类型自动匹配坐席，以便我不用逐条点派",
      "desc": "工单创建后按分类标签匹配对应技能坐席……",
      "rules": ["只在坐席在线且未满负荷时参与分配，负荷上限默认 5 条"],
      "edge_cases": ["工单无任何技能标签时降级为按负载轮询"],
      "acceptance": ["给定标签为技术支持的工单，当存在3名在线技术坐席时，则分派给处理条数最少的那位"],
      "depends": ["坐席技能标签数据（外部：HR 系统同步）"]
    }
  ],
  "constraints": {"性能": "P95 < 1 秒；峰值 200 单/分钟"},
  "metrics": ["上线后连续两周监控工单平均等待时长"],
  "milestones": [
    {"phase": "需求评审", "date": "2026-08-08", "owner": "李明"},
    {"phase": "全量上线"}
  ],
  "open_questions": ["VIP 客户名单从 CRM 取还是本地配置？"]
}

• 必填：product 或 module 至少其一（用于文档标题）；features 非空且每条 name 必填
• 可选：author / version（默认 v0.1）/ date（默认今天）/ reviewers / background / problem / goals / non_goals / users / constraints / metrics / milestones / open_questions
• 功能字段：id 不填自动生成 F1/F2…（同文档内必须唯一）；priority 取 P0/P1/P2/P3（小写 p0 自动转 P0，非法值报错）；desc 与 user_story 至少填一个更稳妥；rules/edge_cases/acceptance/depends 可为字符串或数组，不填则体检扣分
• goals：字符串简写（只填 desc）或对象（含 metric/baseline/target，建议都填以过可衡量性检查）
• users：字符串简写（只填 role）或对象（含 scene/pain）
• milestones：字符串简写（只填 phase）或对象（含 date/owner）；date 支持 YYYY-MM-DD、YYYY/MM/DD、YYYY.MM.DD；缺日期会进「里程碑缺日期」扣分
• constraints：支持对象（维度→要求）或数组（各条约束拼接进「其他」维度）

缺失引导：用户只说「帮我写个需求文档」时，先按顺序问清四件事，再整理成上述 JSON：
- 这个需求解决谁的什么问题（对应 background / problem / users）
- 做完之后哪个数字会变好、变成多少（对应 goals 的 metric+baseline+target）
- 要做的功能有哪些、哪个最急、依赖谁（对应 features 与 priority/depends）
- 怎么算做完了、什么时候交（对应 acceptance 与 milestones）

如果用户答不上「做完看什么数字」，直接告诉他这条目标还没法立需求，先想清楚衡量方式——否则写出来的 PRD 季末谁都说不清算不算做成。

处理流程

1. 与用户确认产品/模块、问题与场景、功能清单与优先级、衡量目标，整理为输入 JSON，存为临时文件（如 prd.json）
2. 跑体检看硬伤（可选，适合动笔前）：
   bash python scripts/build_prd.py prd.json --audit-only
3. 生成完整 PRD：
   bash python scripts/build_prd.py prd.json # 或显式指定输入 / 输出 python scripts/build_prd.py --input prd.json --output PRD.md # 也可从 stdin 读入 type prd.json | python scripts/build_prd.py
4. 将 PRD 原样呈现给用户，重点讲解体检报告：哪几条目标不可衡量、哪些功能缺规则/边界/验收、有没有 P0 膨胀或依赖悬空，并结合 2 项盲区（权限、空态等）给针对性补写建议——别只丢分数，要给出「下一版该补什么」

脚本参数

退出码：0 成功 ｜ 2 输入内容非法（JSON 语法错、顶层不是对象、缺 product/module、features 为空、priority 非法等）｜ 3 文件不存在 / 读写失败 / 编码无法识别 ｜ 4 自检失败。

输出格式

默认一份完整 PRD markdown + 体检报告。PRD 主体含九个章节（背景与问题 / 目标与成功指标 / 用户与场景 / 功能需求 / 约束 / 验收与度量 / 里程碑 / 开放问题 / 依赖与开发顺序），功能段落按 P0→P3 排序，逐条展开五件套；空字段原地标⚠️待补充并说明原因。

体检报告含四块：
- 结论：总分 + 等级判定（可进评审 / 建议补齐 / 会被打回）
- 算法说明：「章节完整度 N 分 − 质量问题扣分 M 分 = 实际分」（低于 0 按 0 计），强调章节写全只是及格线
- 缺失章节表：列被扣分的章节、扣分值、为什么必须写
- 质量问题表：列每条问题、涉及条目、扣分、建议（按扣分降序）
- 高频遗漏项自检：列出文档未涉及的盲区维度，每条配可勾选的 checkbox 与提示语

--audit-only 仅输出上述体检报告（不含 PRD 正文）。

（完整示例见 examples/sample_input.json → examples/sample_output.md）

异常处理

• product 与 module 都为空 → 报错，提示至少填一个用于标题
• features 缺失或非数组/为空 → 报错，提示没有功能条目的 PRD 只是背景说明
• 功能条目非对象或字符串 → 报错并指名是第几条
• 功能缺 name / id 重复 → 报错并指名（重复会导致引用错乱）
• priority 不在 P0-P3 → 报错并提示合法取值（小写 p0 自动转 P0）
• goals 对象条目缺 desc / users 缺 role / milestones 缺 phase → 报错并指名
• milestones.date 格式不合法 → 报错并提示应为 YYYY-MM-DD
• constraints 既非对象也非数组 → 报错
• JSON 解析失败 → 报出具体错误信息并退出码 2
• 输入为空 / 顶层不是 JSON 对象 / JSON 语法错 → 中文报错并退出码 2，不产生半截报告
• 输入文件不存在或是 GBK 编码 → 自动按 utf-8-sig → gbk 顺序兜底；均失败时退出码 3 并说明已尝试的编码
• 所有报错走 stderr，报告只走 stdout，便于 > 文件 重定向或管道串联

边缘用例

• 功能名 / 章节文本含竖线 | 或换行 → 渲染时转义为全角「｜」并去换行、超长截断，避免破坏表格列结构
• 功能只写成字符串（如 "按技能标签自动分派"）→ 自动规整为 {name: ...}
• 循环依赖（A 依赖 B、B 依赖 A）→ 不崩，在「依赖与开发顺序」章节标出 🚨 循环依赖
• 非法 priority（如 P9） → 报错退出码 2，指名是哪条功能
• product 与 module 都空 / features 为空 → 报错退出码 2，不会产生空文档

自检

脚本内置 --selftest，覆盖 14 组用例 + 边界断言（基本生成、高分 PRD、依赖拓扑顺序、循环依赖检出、缺失章节扣分、模糊目标标记、盲区扫描、字符串简写功能、非法 priority 报错、超长功能名不破表、空 features 报错、缺标题报错等）。全部通过退出码 0，任一失败退出码 4。

python scripts/build_prd.py --selftest

适用限制与免责声明

• 不连接任何需求/项目管理系统（不读写 TAPD、PingCode、Jira、飞书多维表格、Confluence 等），仅基于用户提供的文本离线生成；如需同步到系统，请自行复制或配合相应平台连接器
• 体检分数只反映「写没写全、写没写清」，不判断需求本身是否合理、值不值得做——一份 100 分的 PRD 可能指向一个完全错误的产品方向，业务与技术判断仍需人工
• 盲区扫描基于关键词匹配，存在误判：正文用近义词表达了某维度时仍可能被判「未涉及」，此时可忽略该项提示
• 扣分按「涉及条目占比」缩放，目的是避免一条瑕疵被罚到毫无意义，但分数本质是粗略信号，不能作为质量终裁
• 生成的是文档骨架与自检清单，不替代需求评审与团队对齐；因需求定义偏差、范围失控导致的返工与后果由使用者自行承担