construct - 产品构思转化为可构建的SRD套件

construct — 将产品构思转化为可构建的 SRD

construct 将产品创意转化为软件需求文档（SRD）套件，其需求和决策基于真实研究，而非模型的记忆。确定性引擎（scripts/construct.mjs，零依赖 Node）负责执行搜索、报告汇编、SRD 渲染和验证通过代码；你的职责是进行访谈、驱动研究，并丰富渲染出的框架，形成精确且有充分依据的 SRD。

核心原则： 优先选择有根据的需求，而非猜测的需求。使用引擎检索到的研究（竞争对手、开源先例、技术文档、StackOverflow）来证明范围、非功能性需求和架构决策的合理性，并用 [E#] 引用证据。在此，依据是建议性的——construct check 会报告覆盖率，但绝不会因此失败——因此严谨程度由你把握。

脚本

一个已提交、无依赖的脚本：node scripts/construct.mjs <command>。无需 npm install，无需 API 密钥。运行 --help 查看完整功能。关键命令：

• init --idea "<一句话描述>" --out <run> — 创建运行文件夹 + brief.json。
• research --out <run> [--angles market,oss,tech,semantic] [--q "<焦点>"] [--semantic] — 从多个角度收集证据到 <run>/evidence/（一个包含 [E#] ID 的 EVIDENCE.md + evidence.json 报告）。默认角度：market,oss,tech。
• analyze --out <run> [--json] — “什么薄弱？”报告：列出所有当前渲染为 UNGROUNDED 的特征/竞争对手/技术/种子，并打印修复每个差距的 drill 命令。信息性，绝不阻塞。
• web|oss|tech|so --out <run> [--q "<焦点>"] [--url ...] [--seeds ...] [--docs-url <u,...>] — 深挖 ONE 个角度（输出到 stdout，不写入报告）。使用这些命令深入探索薄弱环节；--docs-url 直接引用已知文档页面。
• render --out <run> [--level light|complex] [--merge] — 根据 brief.json + 报告渲染 SRD 树 + SRD.json。
• check --out <run> [--min-grounding <0-100>] [--semantic] [--json] — 硬性结构检查（SRD 不完整时退出码非0）加上建议性的依据覆盖率报告。--min-grounding N 选择性地添加第二个检查，当依据覆盖率低于 N% 时失败；--semantic 引入 VERIFY.json（参见 review），并在任何声明被驳斥/不支持时失败。（与 research --semantic 不同，后者仅通过嵌入相关性对证据进行重新排序。）
• review --out <run> [--apply <verdicts.json>] [--max-review N] [--json] — 声明支持工具。没有 --apply 时，它会创建一个声明↔证据的工作列表（VERIFY.todo.json + VERIFY.md）：每个有依据的声明与引用的每个 [E#] 片段配对以待裁决。--apply <verdicts.json> 将你的裁决（supported|partial|refuted|unsupported）归约为 VERIFY.json，随后 check --semantic 会对其进行门控。可按 references/orchestration.md 进行分发。
• verify --out <run> [--app <dir>] [--run-tests] [--strict] [--json] — 构建裁判：BUILD-PLAN.json 格式良好且无环，每个任务引用都能解析到 SRD.json，已完成任务的文件存在，每个需求都被测试引用。--run-tests 还会执行声明的测试命令；--strict 对没有引用测试的已构建 must-have 需求失败。
• status --out <run> [--json] — 当前运行文件夹中已有的内容；--json 添加构建前沿信息（哪些 BUILD-PLAN 任务当前可构建 vs. 被阻塞）。
• semantic up|down|status — 可选的本地 Docker 堆栈（Qdrant + Ollama + SearXNG）。

工作流程

你被调用一次，期望返回一个完整且有依据的 SRD。驱动循环直至完成；仅在需要向用户确认真实决策时暂停。

1. 访谈用户——一次一个问题。 在研究之前确定产品。遵循 references/interview-playbook.md：问题、目标用户、核心价值、必须/应该/可以功能、约束（预算、时间线、团队、合规性）、候选技术以及任何竞争对手/开源种子。每问一个问题时推荐一个答案；不要抛出一整份问卷。将答案写入 brief.json（使用 construct init 创建）。

2. 研究——为创意提供依据。 运行：

   node scripts/construct.mjs research --out <run> --angles market,oss,tech
   

   这会在网络上发现竞争对手，挖掘相似的开源项目（及其议题/PR以了解真实陷阱），并拉取候选技术文档 + StackOverflow 内容。阅读 <run>/evidence/EVIDENCE.md。

3. 深入挖掘——直到 analyze 结果干净或用户叫停。 运行：

   node scripts/construct.mjs analyze --out <run>
   

   它会命名出具体薄弱的地方——没有可匹配证据的特征、竞争对手、候选技术和开源种子——并打印修复每个差距的 drill 命令。分发： 如果你能生成并行子代理，每个差距分配一个；每个代理获得一句话简介、差距、其 drill 命令和自身的 WebSearch，并返回一个 ≤5 行的摘要加上值得引用的 URL。子代理绝对不能写入运行文件夹——drill 命令输出到 stdout；只有 construct research 写入报告，且只有你来运行。按顺序汇总发现：construct web --url <u,...> --out <run> → 重新运行 research → 重新运行 analyze。（没有子代理？你自己逐个处理差距。）告知用户你的发现，让他们引导——优先处理 must-have 功能和关键决策，当他们表示足够时停止。参见 references/orchestration.md 和 references/research-playbook.md。

4. 渲染 SRD。 当简介坚实且报告丰富时：

   node scripts/construct.mjs render --out <run> --level complex
   

   只要可能构建，就选择 complex；稍后切换级别会重新编号 FR ID（参见 references/srd-authoring.md）。 这会写入 SRD 树（见下文）。数据模型和接口是通过推断从简介中预填充的——验证它们，不要信任它们。然后丰富它：解决每个 🧠 决定： 标记，将模板化的验收标准和非功能性需求指标打磨成可测试、有边界的陈述（遵循 references/acceptance-criteria.md —— check 在存在任何模板化项时会发出警告），修正/扩展数据模型和接口，并从报告中的 [E#] 引用添加到其所依据的需求和决策中。参见 references/srd-authoring.md 和 references/citation-format.md。 对于 complex 级别，还要丰富设计系统（design/）：用产品的真实品牌价值替换预填充的设计令牌，验证组件和屏幕/流程清单，并将可访问性标准打磨到目标标准（从简介衍生，默认 WCAG 2.2 AA）。参见 references/design-system-authoring.md。

5. 对抗性审查——用新视角来打破它。 生成一个审查者子代理，除了运行文件夹路径和 references/adversarial-review.md 外没有任何上下文（没有子代理？你自己来做这次检查，严格遵循该清单作为敌意读者）。它必须尝试打破 SRD —— 歧义、不可测试的标准、缺失的失败路径、引用清洗、矛盾 —— 并返回带标签的发现。修复所有 [blocker]，自行判断 [advisory]，然后重新运行 check。当出现新的阻塞项时循环（上限：3 轮，然后将剩余问题呈现给用户）。对于 complex 级别中真正存在争议且难以撤销的架构决策记录，还要运行 references/orchestration.md 中的 3 人评审小组。

6. 验证（三层）。

   • 结构性（硬性）： node scripts/construct.mjs check --out <run>。如果存在未解决的 🧠、完全没有功能需求、FR 没有验收标准、悬空的实体/接口/非功能性需求引用、缺少必需的非功能性需求类别或格式错误的架构决策记录，则会失败。修复直到通过。
   • 依据性（建议性）： 同一命令会打印覆盖率——需求/决策引用证据的比例。在重要的地方（关键决策）提高覆盖率；参见 references/grounding-coverage.md。默认情况下它不会导致构建失败，因此运用你的判断。当用户希望强制执行依据性时，添加可选的门控：check --out <run> --min-grounding 70。
   • 声明支持（建议性 → 可选门控）： 覆盖率计算引用次数；它不检查引用是否成立。construct review --out <run> 构建一个声明↔证据工作列表；裁决每一对（按 references/orchestration.md 模式 4 分发），组装 verdicts.json，review --apply verdicts.json，然后 check --out <run> --semantic 来门控被驳斥/不被支持的声明。在展示前对关键 FR/ADR 做一次检查是值得的。 循环步骤 3–6，直到 check 在结构上通过，审查者没有发现新的阻塞项，并且依据性是诚实的。

7. 呈现。 向用户提供 SRD 套件：愿景、竞争格局、有依据的需求和关键决策（附有 [E#] 证据和链接）。明确标注任何未知项，而不是猜测。

8. 构建（当用户想要应用程序，而不仅仅是 SRD 时）。 渲染还生成了 BUILD-PLAN.json——一个机器可读的任务 DAG（T-000 骨架 + 每个 FR 一个任务，must → should → could，实体感知依赖关系），其 acceptance 条目指向 SRD.json。你编写所有应用程序代码；引擎担任裁判。 遵循 references/build-playbook.md：

   • 执行 T-000（脚手架、测试框架、CI）；在 BUILD-PLAN.json 中设置 conventions.appDir 和 conventions.testCommand。
   • 对于每个任务，按拓扑顺序：从 SRD.json 读取验收标准；以 TDD 方式实现它们——每个测试都应命名其 FR id（例如 describe("FR-001 …")；这就是 verify 搜索的内容）；记录 artifacts + tests；设置 status: "done"；运行 node scripts/construct.mjs verify --out <run> 并在进入下一个任务前修复任何错误。
   • 同一里程碑的任务之间没有边，因此它们就绪的前沿（status --out <run> --json）可以并行构建——每个任务一个独立的 git 工作树；你独自将结果合并到 BUILD-PLAN.json 中（references/orchestration.md 中的模式 5）。
   • 每个里程碑：verify --out <run> --run-tests --strict，然后进行一次里程碑对抗性审查——用新视角寻找那些没有测试实际执行的验收标准（参见 playbook；references/verify.md 解释了 verify 能证明什么和不能证明什么）。
   • 如果某个 FR 在构建过程中被证明是错误的，修改简介，重新渲染（进度按特征标题合并），重新标记变化的 FR id，重新运行 check。

产出物（SRD 树，位于 --out 下）

00-overview/   VISION.md · SCOPE.md (+ 🧠 待定决策)
requirements/  FUNCTIONAL.md (FR-NNN · 优先级 · Given/When/Then · [E#])
               NON-FUNCTIONAL.md (NFR-NNN 按类别 · 指标 · [E#])
architecture/  SYSTEM-CONTEXT.md · DATA-MODEL.md · INTERFACES.md
               decisions/NNNN-*.md  (ADRs)
design/        PRINCIPLES.md · DESIGN-TOKENS.md (+ design-tokens.json) · COMPONENTS.md
               SCREENS.md · ACCESSIBILITY.md      (仅 complex；--no-design 跳过)
competitive/   LANDSCAPE.md (竞争对手 + 开源先例)
BUILD-PLAN.md · BUILD-PLAN.json (构建阶段的任务 DAG)
TRACEABILITY.md (FR ↔ NFR ↔ ADR ↔ entity ↔ interface ↔ component ↔ screen)
evidence/      EVIDENCE.md · evidence.json · meta.json   ·   brief.json · SRD.json

light 保持精简；complex 添加完整的非功能性需求集合、第二个架构决策记录、包含失败路径的验收标准、完整的可追溯性矩阵以及设计系统子树（design/：原则、令牌、组件、屏幕/流程、可访问性契约——--no-design 可选择排除）。添加 --merge 以生成单个文件 SRD.md。

可选的语义模式（完全本地，无需 API 密钥）

市场/开源/技术角度只需要网络访问。为了对收集到的证据进行相关性处理，你可以启用本地嵌入模型：

node scripts/construct.mjs semantic up        # docker: Qdrant + Ollama + SearXNG
node scripts/construct.mjs research --out <run> --angles market,oss,tech,semantic --semantic

一切都在本地 Docker 容器中运行——无需密钥，数据不会离开机器。如果堆栈未启动，--semantic 会记录一条通知并保留词汇排名。参见 references/semantic-setup.md。

参考文献

• references/interview-playbook.md — 如何一次一个问题地获取简介。
• references/research-playbook.md — 选择角度并深入挖掘至“足够好”。
• references/orchestration.md — 三层动态工作流模型和子代理模式：研究分发、红队、评审小组、声明支持审查分发、构建分发（以及单一写入者规则）。
• references/adversarial-review.md — 红队清单及其发现契约。
• references/srd-authoring.md — 解决 🧠 标记、编写可测试需求和架构决策记录。
• references/design-system-authoring.md — 丰富 complex 设计系统：令牌、组件、屏幕/流程以及可访问性契约。
• references/acceptance-criteria.md — 差→好 Given/When/Then 重写和可度量的非功能性需求指标模式。
• references/citation-format.md — [E#] 依据约定。
• references/grounding-coverage.md — 建议性覆盖率报告的含义以及如何提高。
• references/build-playbook.md — 构建循环：任务 TDD、FR 标签约定、里程碑门控、里程碑审查。
• references/verify.md — 每个 verify 检查证明了什么，以及哪些仍需要人工审查。
• references/provider-apis.md — 如何按主机、无密钥地获取开源议题/PR。
• references/web-discovery.md — 分层的无密钥网络搜索。
• references/semantic-setup.md — 可选的本地 Docker 堆栈。