prd-helper

PRD Helper

中文 | English

一句话价值

PRD Helper 是一个 PRD Context Compiler（PRD 上下文编译流程）：把分散在会议、聊天、评审和旧文档里的产品上下文，沉淀成可追溯、可检查、可复用的结构化 PRD 资产和 Agent Context 工程指导文件。

它坚持一条主链路：采集（Collect）→ 精炼（Refine）→ 关联（Relate）→ 生成（Generate）。检查（Check）是横向 Soft Gate（软门禁），不是第五阶段；Soft Gate 不默认阻断用户命令，但会暴露来源缺失、断链和待确认风险。

它解决什么问题

很多团队不是没有需求资料，而是资料散、来源乱、版本多，最后 PRD 变成“谁记得就听谁的”。PRD Helper 的目标是让 Agent 和团队先保存原始材料，再精炼信息、建立关系，最后生成 PRD 和指导人或 Agent 实施的 Agent Context，避免直接让 AI 从碎片聊天里凭感觉写文档。

如果用户跳过前置阶段或检查未通过，/prd-generate 仍可执行，但结果属于 Limited Generate（受限生成）：缺失来源、断链、待确认问题和禁止实施项必须显式标记，不能伪装成完整确定性 PRD。

生成阶段的文档文件是 View，不是 Entity。只有跨阶段流转、需要被引用、需要 ID、需要参与关系链路的对象，才是领域实体。来源追溯也分级：具备 source_id + path + quote/paraphrase + locator 的内容是 Strong Trace；缺少 locator 的内容是 Weak Trace，不能进入确定性要求。

当前指令清单

当前权威指令集合来自 scripts/lib/command_registry.py、根 SKILL.md、skills/prd-*/SKILL.md、commands/*.md 和插件声明。根 SKILL.md 是本地直接下载/克隆后的自然语言兜底入口，不带安装器 frontmatter；npx skills@latest add Wcof/PRDContextEngine 会发现并安装以下 11 个命令 Skill：

指令	阶段/类型	作用	主要产物
/prd-helper	初始化入口	初始化或修复当前项目配置，创建 docs/prd-helper/ 和 Agent 规则	配置、目录、Agent 规则
/prd-start	采集	开启主动采集，后续产品讨论会写入采集区	01-collect/active/、collect-state.md
/prd-stop	采集	停止主动采集，清理采集 Hook，并生成采集摘要和检查结果	collect-summary.md、01-collect/check.md
/prd-status	采集工具	查看当前采集状态、session、写入目录和计数	状态摘要
/prd-scan	采集工具	批量扫描历史 Agent 会话并导入采集池	01-collect/active/historical/、source-index.md
/prd-import	采集工具	导入第三方文件夹作为被动材料，不提前清洗原文	01-collect/passive/、source-index.md
/prd-refine	精炼	从采集材料中提炼事实、背景、目标、决策、约束、冲突、问题和推断	02-refine/
/prd-relate	关联	建立事实、页面、功能、规则、数据、验收之间的上下游关系	03-relate/
/prd-generate	生成	基于精炼与关联产物生成 PRD 文档和 Agent 上下文	04-generate/
/prd-discuss	辅助研讨	在采集和精炼之间追问矛盾、模糊术语和未决问题，每次只追问一个问题	研讨摘要、待确认项
/prd-remove	卸载	清理 PRD Helper 项目配置、命令、Hook 和完整 prd-* Skill 命令包，默认保留已生成文档	清理结果

平台说明：skills/ 目录包含上述 11 个安装器可发现的 Skill。skills/prd-helper/ 还携带运行时脚本，供其它轻量命令 Skill 定位 dispatcher。COMMAND_NAMES 仍只记录除 /prd-helper 外的 10 个后续命令，用于项目级兜底命令和卸载清理。

命令 Skill（prd-start 等）已内置 dispatcher 自定位逻辑：即使你只安装单个命令 Skill，它也会先在本 Skill 目录、prd-helper 目录和 Codex 本地插件目录中定位 scripts/prd-command-dispatch.py，再执行统一运行时。

工程约束

PRD Helper 遵循“Python 执行化，静态提示词约束化”：

• 指令事实来自 scripts/lib/command_registry.py，COMMAND_NAMES、安装脚本和一致性测试都从这里派生。
• 业务规则保留在 skills/prd-helper/SKILL.md、modules/*/guide.md 和 commands/*.md，Python 不承担提示词职责。
• 产物结构和检查清单优先放在 modules/*/templates/，脚本只填入状态、计数、检查结果和来源信息。

运行时规则收敛到一组深 Module，避免脚本之间重复维护隐性契约：

• collect_writer 统一 Active Capture、历史 Session 和 Passive Source 的写入、索引、去重和计数。
• source_anchor 统一 Strong Trace / Weak Trace 判断，最低锚点仍是 source_id + path + quote/paraphrase + locator。
• relation_chain 解析 Relation Chain，并输出可定位断链，而不是只做文本包含检查。
• generate_contract 定义 Generate 应输出的 View 清单、Limited Generate 风险和生成契约；generate_manifest 作为兼容入口保留。
• check_result 统一 Soft Gate 结果模型，便于各阶段检查输出一致语义。
• install_state、command_plan、command_packaging 分别收敛安装状态、命令执行语义和命令包装规则。

快速开始

1. 安装命令 Skills

默认推荐一键安装全部 prd-* Skill：

npx skills@latest add Wcof/PRDContextEngine --all

如果你想按需一个个选择（保留单选能力），使用交互安装：

npx skills@latest add Wcof/PRDContextEngine

安装器会从 skills/ 目录发现 prd-helper、prd-start、prd-stop、prd-status、prd-scan、prd-import、prd-refine、prd-relate、prd-generate、prd-discuss、prd-remove。交互模式里选择这些 Skill，并选择你要安装到的 Agent，例如 Claude Code、Codex 或 Trae。

2. 初始化当前项目

在 Agent 会话中输入：

/prd-helper

初始化会创建默认目录 docs/prd-helper/，并补齐 Agent 规则、项目级兜底命令和 Hook 配置。后续命令已在安装时注册；/prd-helper 不是它们出现的前置条件。

3. 按四阶段推进

/prd-start    # 开启主动采集
/prd-stop     # 停止主动采集并生成采集摘要
/prd-scan     # 扫描历史 Agent 会话
/prd-import   # 导入第三方文件夹作为被动材料
/prd-refine   # 精炼采集材料
/prd-relate   # 建立上下游关系链路
/prd-generate # 生成 PRD 文档和 Agent 上下文

需要查看状态时用 /prd-status，需要研讨模糊点时用 /prd-discuss，需要卸载时用 /prd-remove。

主动采集内容会进入：

docs/prd-helper/01-collect/active/

手动材料放入：

docs/prd-helper/01-collect/passive/

四阶段工作流

阶段	目录	做什么	不做什么
Collect 采集	modules/collect/	保存原始材料、建立索引、记录 hash、维护采集状态	不提前改写事实、不生成规则
Refine 精炼	modules/refine/	区分事实、背景、目标、决策、约束、冲突、问题、推断	不把推断写成事实、不跳到 PRD
Relate 关联	modules/relate/	建立 fact -> page/feature -> rule -> data/acceptance 链路	不让事实、规则、数据、验收断链
Generate 生成	modules/generate/	生成 PRD、验收、数据说明和 Agent 上下文	不新增未来源化、未关联的业务规则

Generate 如何保证一次性生成完整

Generate 现在采用 contract-driven 流程，不再只依赖 Agent 按提示词手动补文件：