construct

construct — 将产品构想落地为可构建的 SRD

关于引擎证据和覆盖范围限制，请阅读 engine-evidence。

construct 会将产品构想转化为一套软件需求文档（SRD），其中的需求和决策都以真实研究为依据，而非来自模型的记忆。确定性引擎（scripts/construct.mjs，零依赖 Node）会通过代码完成搜索、资料汇编、SRD 渲染和验证；你的工作是进行访谈、推动研究，并将渲染后的框架充实为精确且依据充分的 SRD。

核心原则： 优先采用有依据的需求，而不是猜测的需求。使用引擎检索到的研究（竞品、开源软件先例、技术文档、StackOverflow）为范围、NFR 和架构决策提供依据，并使用 [E#] 引用证据。默认情况下，依据检查是建议性的：construct check 会报告引用覆盖率。传入 --min-grounding <0-100> 可在覆盖率低于所需阈值时使检查失败。覆盖率统计的是引用数量；请使用 review 和 check --semantic 验证引用的证据是否确实支持相关主张。

一句话说明整个流程

[brainstorm] → interview → research → analyze → drill → render → enrich → red-team → check → present → [build]

construct status --out <run> 会打印现有内容以及确切的下一条命令。 每次恢复运行或忘记进度时，都请使用它。

哪些情况下不要运行 construct

在第 1 个问题之前确认是否适用；选错会浪费整个流程。

• 已有代码库。 construct 用于规划从零开始的产品。若要记录或改进已有仓库，请改用 reconstruct。
• 一次提出多个产品。 一次运行对应一个产品。说明如何拆分，建议优先编写哪个产品的规格，并将其余产品暂时搁置。
• 没有清晰可表达的构想。 init 需要一句话描述。如果用户无法用一句话说明问题，请运行 construct brainstorm，不断发散探索，直到构想成形——不要围绕“一个 AI 的东西”启动流程。
• 用户只想要图表、名称或估算。 直接回答；SRD 套件不是他们要求的交付物。

根据情况选择流程

用户……	从这里开始	阅读
有初步构想，想进一步探索	第 0 步，brainstorm	references/brainstorm-playbook.md
构想明确	第 1 步，访谈	references/interview-playbook.md
已有 brief.json	第 2 步，research	references/research-playbook.md
已有渲染好的 SRD，想进一步完善	第 4 步，补充，然后第 5 步	references/srd-authoring.md
已有通过验证的 SRD，想构建应用	第 8 步，将 verify 用作裁判	references/build-playbook.md
提到的功能超过 6 项或采用模块化布局	第 1 步 + 模块拆分	references/srd-authoring.md
希望强制要求依据，而非仅提供建议	check --min-grounding N，然后 review	references/grounding-coverage.md
只想要一次性规格，而非用于构建	render --level light	references/srd-authoring.md

首次运行按 1 → 2 → 3 → 4 → 5 → 6 → 7 的顺序进行。恢复运行时，通常先执行 status，再从它指出的位置继续。

八条命令走完理想流程

node scripts/construct.mjs init     --idea "<one-liner>" --out ./my-idea   # then interview → brief.json
node scripts/construct.mjs research --out ./my-idea --angles market,oss,tech
node scripts/construct.mjs analyze  --out ./my-idea                        # what is thin + the drill for each gap
node scripts/construct.mjs research --out ./my-idea --angles market,oss,tech --url <proven,urls>
node scripts/construct.mjs render   --out ./my-idea --level complex
#   … enrich SRD.json, then:
node scripts/construct.mjs render   --out ./my-idea --from-srd
node scripts/construct.mjs check    --out ./my-idea
node scripts/construct.mjs review   --out ./my-idea                        # adjudicate → check --semantic

脚本

一个已提交、无依赖的工具包：node scripts/construct.mjs <command>。 无需 npm install，也无需 API 密钥。完整命令列表请查看 --help；这里是流程概览。

命令	功能
init --idea "<s>" --out <run>	创建运行文件夹和 brief.json
brainstorm --out <run> [--merge]	可选的发散式讨论板；--merge 会将保留的想法并入简报，将暂存的想法并入 openQuestions（会阻塞关卡 🧠）
research --out <run> [--angles …] [--url …] [--docs-url …]	将证据收集到 <run>/evidence/。这是唯一会为内容提供依据的命令。
analyze --out <run>	找出薄弱之处——列出所有会渲染为 UNGROUNDED 的声明，以及修复它们的深入调查。永远不会阻塞关卡。
web | oss | tech | so --out <run>	深入调查一个角度。输出到 stdout；不会持久化任何内容，包括 --url/--docs-url。
render --out <run> [--level light|complex]	渲染 SRD 树和 SRD.json。--level 默认为 light——只要有可能进行构建，就传入 complex。
render --out <run> --from-srd	根据**已编辑的 SRD.json**重新生成树。这是持久化补充内容的方式。
check --out <run>	严格的结构关卡检查 + 建议性的依据报告
review --out <run> [--apply <f>]	生成声明↔证据工作清单，然后生成 check --semantic 依据其进行关卡检查的判定记录
verify --out <run> [--app <dir>] [--acceptance] [--run-tests] [--strict]	默认执行静态一致性检查；--acceptance --run-tests 会执行当前与验收标准绑定的命令（--app 默认为 conventions.appDir）
status --out <run> [--json]	显示已有内容和下一条命令；--json 会额外显示构建前沿
orchestrate --out <run> [--phase …] [--eco]	输出此运行的扇出任务（见下文）
semantic up|down|status	可选的本地 Docker 栈
firecrawl up|down|status	可选的本地 Firecrawl 栈——无需密钥即可提取正文。运行期间，每个页面都会通过它清理，而非使用内置 HTML 剥离器；未运行时则不会有任何变化。
cache status|clean [--all]	页面缓存，可让 research 几乎无需成本地重新运行

以下三种行为值得提前了解，以免遇到时措手不及：

• --prd 会持续生效。 后续省略该选项的 render 会拒绝运行，而不是删除 requirements/prd/——请重新传入 --prd，或传入 --no-prd 主动删除。
• check --semantic 采用失败即关闭策略。 缺失、无法读取或尚未完成裁定的 VERIFY.json 都会导致 FAIL；与其他渲染结果进行裁定的文件也会导致 FAIL。--allow-unverified 会将其降级为警告——使用时请说明。
• check 在 complex 级别遇到渲染器脚手架内容会直接失败。 此级别用于认证构建就绪状态；未编写的验收标准不具备任何认证作用。 （references/requirements-rubric.md。）

约定。 --out <run>（别名 --run）；--q <focus>（别名 --question）。--refresh 会忽略页面缓存并重新克隆 OSS 仓库； --offline 仅使用缓存，并如实报告缓存未命中。 --web-engine auto|searxng|ddg|claude|firecrawl 用于指定发现引擎（firecrawl 只能显式指定——auto 不会探测它）；--firecrawl <url|off> 用于将提取层指向其他位置，或强制使用内置提取器。--concurrency <n> （默认为 4）限制每个角度的并发抓取数；--max-tech <n>（默认为 3）限制 tech 为其提供依据的候选技术数量；--per-source <n>（默认为 6）限制每个来源保留的证据数量；--source <kind> 用于重新分类 web --url 页面。大多数命令都支持 --json——根据结果进行分支判断时优先使用它。

退出代码。 0 正常 · 1 关卡失败、用法错误或运行时错误 · 2 编排前置条件失败，包括工作清单尚不存在的阶段（消息会指出生成该清单的命令）。analyze 永远不会阻塞关卡。 语义裁定绑定到完整声明及引用的证据内容，包括展示摘录之外的文本。裁定时请保留生成的 VERIFY.todo.json：只有引擎确认其仍与当前 SRD 和证据匹配后，最简裁定行才会继承其中的指纹。请在自包含裁定中保留指纹。旧版或缺失的工作清单无法绑定旧的未绑定行；check --semantic 会拒绝这些行。内容发生变化时，请重新运行 review 并重新裁定。--allow-unverified 会明确将绑定失败降级为警告。

工作流

系统会调用你一次，并期望你返回完整且有依据的 SRD。请推动整个流程完成；只有在需要用户做出实际决策时才暂停提问。

0. 头脑风暴——可选、发散，且在访谈之前进行。 当用户还无法清晰表达想法，或希望先探索选项时，运行 construct brainstorm --out <run>（在 init 之后），与用户围绕六个角度生成候选想法，然后通过 --merge 将保留的想法合并到 brief.json。如果用户已经清楚自己的需求，则跳过此步骤。请遵循 references/brainstorm-playbook.md。

1. 访谈用户——每次只问一个问题。 先明确产品，再开展调研。遵循 references/interview-playbook.md（以及 references/brief-example.md，其中包含填写好的 brief 和形成其中最难填写字段的交流记录）：问题、目标用户、核心价值、必须具备／应该具备／可以具备的功能、限制条件（预算、时间线、团队、合规）、候选技术，以及任何竞品／开源项目线索。每个问题都提供一个建议答案；不要一次性抛出整份问卷。将答案写入 brief.json（先运行 construct init 创建该文件）。 模块拆分： 当产品天然适合模块化（功能大约超过 6 个，或用户提出 src/modules/… 这类模块化架构）时，提出模块拆分方案并记录下来——在 brief.modules 中记录模块（id/name/description/dependsOn），并为每项功能指定一个 module。随后，Render 会为每个模块生成一份 PRD，而 check 会强制执行分区要求（必须全部分配：每项功能都必须归属某个模块）。模块 id 会成为文件夹名——请使用类似 slug 的格式，并确保不同模块中的功能标题不重复（BUILD-PLAN 进度按标题索引）。

2. 调研——为想法提供依据。 运行：

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

   此步骤会在网上发现竞品、挖掘可比的开源项目（以及其中真实反映问题的 issues/PR），并获取候选技术文档和 StackOverflow 内容。请阅读 <run>/evidence/EVIDENCE.md。

3. 深入研究——直到 analyze 没有问题，或用户让你停下。 运行：

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

   它会准确指出哪些方面薄弱——功能、竞争对手、候选技术，以及缺乏可匹配证据的开源种子项目——并打印出弥补每个缺口的深入调查命令。并行展开：如果可以启动并行子 Agent，就为每个缺口分派一个（引擎会生成可直接启动的命令： node scripts/construct.mjs orchestrate --out <run> --phase research）； 每个子 Agent 都会收到简短项目简介、缺口说明、对应的深入调查命令和独立的 WebSearch，并返回不超过 5 行的摘要及值得用作依据的 URL。子 Agent 不得写入运行文件夹——深入调查命令只会向 stdout 输出内容；只有 construct research 会写入研究档案，而且只能由你运行。通过一次研究重新运行纳入调查结果，并固定已证实的 URL： construct research --out <run> --angles market,oss,tech --url <u,...> [--docs-url <d,...>] → 重新运行 analyze。每次研究运行都会仅根据所提供的角度和 URL 重建研究档案——务必传入所有角度，否则之前运行中的证据会丢失。固定的 URL 不会被预算删掉，任何预算削减都会在研究档案的备注中说明。重新运行时，[E#] ID 保持不变，因此已写入 SRD 的引用仍会指向同一来源。（如果没有子 Agent，就自己逐个深入调查缺口。）告诉用户你的发现，并让他们决定方向——优先处理必需功能和关键决策，在用户表示足够时停止。参见 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 文件树（见下文）。数据模型和接口会根据项目简介通过推断预先填充——务必核实，切勿盲目信任。 然后完善内容：处理每一项 🧠 Decide: 提示，细化模板生成的验收标准和 NFR 指标，将其改为可测试且有明确边界的陈述（遵循 references/acceptance-criteria.md——在 complex 级别，残留的渲染器模板化标准属于严重错误，而非警告：该级别用于认证项目已做好构建准备）；修正或扩展数据模型和接口，并从研究档案中为其依据的需求和决策添加 [E#] 引用。通过编辑 SRD.json 并使用 render --out <run> --from-srd 重新生成，持久化完善后的内容——这样可以使 Markdown 与受控清单保持同步；只手动编辑已渲染的 .md 文件，会在下次生成时被覆盖。参见 references/srd-authoring.md 和 references/citation-format.md。 在 complex 级别，还要完善设计系统（design/）：将预填的设计令牌替换为产品真实的品牌值，核实组件和屏幕/流程清单，并按照目标标准细化无障碍标准（根据项目简介确定，默认为 WCAG 2.2 AA）。参见 references/design-system-authoring.md。

5. 对抗性审查——让新视角来找茬。 启动一名审查子 Agent，除了运行文件夹路径和 references/adversarial-review.md 外，不提供任何上下文（如果不能启动子 Agent，就自己 执行审查，并严格遵循该清单，以敌对读者的视角进行）。它必须尝试找出 SRD 的问题—— 歧义、无法测试的标准、缺失的失败路径、引用洗白、矛盾——并返回带标签的发现。修复所有 [blocker]，酌情处理 [advisory]，然后重新运行 check。持续循环，直到没有新问题—— 当某一轮没有发现新的阻塞项时就停止（只需一轮无新问题的审查；不要默认进行三轮）。 兜底方案：如果 3 轮后仍发现阻塞项，就停止并把剩余问题交给用户——3 轮后仍无法清除 阻塞项的 SRD 存在值得人工处理的结构性问题。 对于 complex 级别、确实存在争议且难以撤销的 ADR，还要运行 references/orchestration.md 中的 3 名评审者小组（发出该流程： orchestrate --out <run> --phase adr-judges --adr <id>）。

6. 验证（三个层面）。

   • 结构验证（硬性）： node scripts/construct.mjs check --out <run>。遇到任何尚未解决的 🧠、完全没有功能需求、某个 FR 没有验收标准、实体/接口/NFR 引用悬空、缺少必需的 NFR 类别，或 ADR 格式错误时，都会失败。持续修复，直到通过。
   • 依据验证（建议）： 同一命令会输出覆盖率——有多少比例的需求/决策引用了证据。在关键 之处（即承重决策）提高覆盖率；参见 references/grounding-coverage.md。默认情况下， 它永远不会导致构建失败，因此请自行判断。用户要求强制执行依据验证时，添加可选门槛： check --out <run> --min-grounding 70。
   • 主张支持验证（可选门槛，启用后失败即关闭）： 覆盖率只统计引用数量，不检查引用内容 是否成立。construct review --out <run> 会生成主张↔证据工作清单；逐对裁定（按照 references/orchestration.md 中的模式 4 分派——通过 orchestrate --out <run> --phase claim-review 发出），整理出 verdicts.json， 执行 review --apply verdicts.json，然后运行 check --out <run> --semantic。 只有在运行 review --apply 后才运行 --semantic： 它会断言支持门槛确实已启用， 因此缺失/不完整的 VERIFY.json——或针对较早版本的渲染结果作出的裁定——会导致检查 失败，而不是悄然通过。在提交前，值得对承重 FR/ADR 做一轮检查。 循环执行步骤 3–6，直到 check 通过结构验证、审查者未发现新的阻塞项，且依据覆盖率真实可信。

7. 呈现结果。 先讲决策，而不是产出物：研究带来了哪些改变、承重 ADR 及其代价和对应的 [E#]、范围边界，以及仍有哪些未知事项——明确标出，不要刻意淡化。诚实报告各项门槛： check 通过表示结构完整，不代表内容良好；覆盖率统计的是引用数量，并不验证引用内容 是否成立。然后询问用户接下来想做什么；未经提示不要开始构建。遵循 references/presenting.md。

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；并行分派：orchestrate --out <run> --phase build）。
   • 每个里程碑完成后：运行 verify --out <run> --run-tests --strict，然后进行一次里程碑对抗性审查——以全新视角查找是否有验收标准未被任何测试实际覆盖（参见 playbook；references/verify.md 说明了 verify 能证明和不能证明的内容）。
   • 如果构建过程中发现某个 FR 不正确，修改需求简报、重新渲染（进度会按功能标题合并）、重新标记调整过的 FR id，然后重新运行 check。
   • 在声称应用已实现之前，遵循 references/verify.md 中的标准绑定协议，并运行 verify --out <run> --strict --acceptance --run-tests --json。当前每项标准都必须为 passed；failed 或 not-tested 都会阻止你作出此声明。检查专门的断言：退出码为 0 只能证明命令成功，不能证明被跳过、为空或被弱化的测试满足业务要求。

出现问题时

症状	处理方法
check 因 🧠 提示框失败	作出决定。将其纳入 ADR、需求或范围，或从 brief.openQuestions 中移除，然后重新渲染。这是一个门槛，因为延迟决定就是规格中的缺陷。
check 失败并指出是渲染器搭建的脚手架	这些标准/契约从未经过编写。重写它们（references/requirements-rubric.md），如果这只是一次性规格，也可以降至 --level light。
render 拒绝执行并提示“requirements/prd exists”	上次渲染使用了 --prd。再次传入 --prd 以重新生成，或传入 --no-prd 有意删除它。
check --semantic 因未知原因以状态码 1 退出	它采用失败关闭策略。运行 review，裁定每一对，再运行 review --apply，然后运行 --semantic。如果审查后又重新渲染，审查结果也会失效。
orchestrate --phase <p> 以状态码 2 退出	该阶段的任务列表尚不存在；提示信息会指出生成它的命令。
研究没有返回结果	明确具体地描述含糊的 candidateTech/competitors，然后重新运行。接着使用你自己的 WebSearch 并固定页面：research --url <u,...>。连续两次尝试都无结果后就停止——记录一项假设或 openQuestion，然后继续。内容精简但诚实的 SRD，胜过捏造的引用。
测试引用了 SRD 中已不存在的 FR id	重新渲染时 FR 编号变了。重新标记测试；verify 会列出过时的 id。
一次运行意外耗时过长	执行 construct cache status。冷缓存需要为每个页面完整抓取一次；--offline 仅使用缓存运行。每个角度的成本记录在 evidence/meta.json 和 EVIDENCE.md 末尾。

常见错误

• 把检索当成依据。 web/oss/tech/so 会打印结果。只有 research --url / research --docs-url 会保存可供引用的证据。
• 减少检索角度后重新运行 research。 它会完全根据你提供的内容重新构建档案——务必传入所有角度，否则先前的证据会丢失。
• 明明可以构建，却仍用默认的 light 模式渲染。 之后再切换会重新编号 FR id，并使测试标签失效。
• 编辑渲染后的 .md 文件，然后就此收工。 下次渲染会覆盖这些修改。 编辑 SRD.json，然后运行 render --from-srd。
• 让子 Agent 写入运行目录。 只能有一个写入者——就是你。子 Agent 只返回文本。
• 尚未通过 check 就开始展示。 覆盖率百分比不是门槛；未解决的 🧠 才是。

如何判断已完成

只有满足以下所有条件，SRD 才算完成——请逐项明确检查，不要想当然：

1. construct check 以状态码 0 退出。
2. 每项 must 需求都有一条故障路径验收标准，描述具体行为，而不是“显示错误”。
3. 每项关键决策（技术栈、数据存储、构建还是购买、差异化优势）都引用了确实支持相应论点的证据——你至少抽查了三项。
4. 数据模型和接口经过了验证，而不是留给渲染器推断。
5. 红队评审没有发现新的阻碍。
6. 所有仍未知的内容都记录为假设或 openQuestion，而不是悄悄猜测。

**自测：**一个从未与你交流过的开发者，能否仅凭这份 SRD 实现所有必需项，并正确实现各项约定，而不只是把握大意？ 如果有任何问题需要通过交流才能回答，SRD 就还没有完成。

编排——按执行环境选择方式

四个阶段基于按单元划分、由文件支撑的状态并行展开：research（每个 analyze 缺口对应一名研究者）、claim-review（每对 VERIFY.todo.json 对应一名质疑者）、adr-judges （针对一个有争议的 ADR 组成固定的三视角评审小组）和 build（每项就绪任务对应一名在独立 worktree 中工作的构建者）。orchestrate 会根据运行目录的当前状态生成这些任务，并预先填入绝对路径和实际的工作清单单元：

node scripts/construct.mjs orchestrate --out <run> [--phase research|claim-review|adr-judges|build] [--adr <id>] [--eco] [--list]

你的执行环境	各阶段的运行方式
有 Workflow 工具	orchestrate --phase <p>，然后运行 Workflow({ scriptPath: "<run>/orchestration/<p>.workflow.mjs" })
有子 Agent，但没有 Workflow 工具	同样运行 orchestrate；按批次为每个 <run>/orchestration/agents/<role>.md 派发一个子 Agent
Eco 模式，或没有子 Agent	orchestrate --eco → 按 <run>/orchestration/RUNBOOK.md 顺序执行

两个规则在所有层级都适用。 子 Agent 绝不写入运行目录——它们只返回片段，由你将其整合进来（构建者只在自己的 git worktree 中写代码）。并且，并行展开只是优化手段，绝非必要条件：每个阶段都有产出相同制品的顺序执行方案，因此门槛与执行环境无关。模式、输出约定和预算指南：references/orchestration.md。

生成内容（--out 下的 SRD 目录树）

00-overview/   VISION.md · SCOPE.md (+ 🧠 open decisions)
requirements/  FUNCTIONAL.md (FR-NNN · priority · Given/When/Then · [E#];
               an index linking each FR to its module PRD in modules mode)
               NON-FUNCTIONAL.md (NFR-NNN by category · metric · [E#])
               prd/PRD-FR-NNN-*.md (+ README index — only with --prd)
prd/           README.md · <module>/PRD.md   (modules mode only: one PRD per
               module — full FR blocks, NFR refs, data/interface slices, deps)
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 only; --no-design to skip)
competitive/   LANDSCAPE.md (competitors + OSS prior art)
BUILD-PLAN.md · BUILD-PLAN.json (task DAG for the build phase; tasks carry their
               module in modules mode)
TRACEABILITY.md (FR ↔ module ↔ NFR ↔ ADR ↔ entity ↔ interface ↔ component ↔ screen)
evidence/      EVIDENCE.md · evidence.json · meta.json · ids.json (the [E#]
               ledger — do not hand-edit; it is what keeps citations stable)
VERIFY.md · VERIFY.todo.json · VERIFY.json   (the claim-support worklist and its
               adjudicated ledger — written by `review` / `review --apply`)
orchestration/ <phase>.workflow.mjs · agents/<role>.md · RUNBOOK.md
               (written by `orchestrate`; `out/` is where subagents may return)
brief.json · SRD.json

evidence/、VERIFY.md 和 orchestration/ 是检索或生成的文本—— check 特意不会扫描其中的 🧠/TODO，因此证据片段可以引用任何内容，不会触发门槛。

light 模式保持精简；complex 会增加完整的 NFR 集、第二个 ADR、故障路径验收标准、完整的可追溯性矩阵，以及设计系统子目录（design/：设计原则、令牌、组件、界面/流程、无障碍约定——可通过 --no-design 选择不包含）。添加 --merge 可生成单文件 SRD.md（即使在 modules 模式下也始终包含完整的 FR 区块）。

可选本地栈（完全本地运行，无需 API 密钥）

construct semantic up 会启动本地 Docker 栈（Qdrant + Ollama + SearXNG）；然后运行 research --angles market,oss,tech,semantic --semantic，即可按嵌入相关性对收集到的证据重新排序。任何数据都不会离开本机；如果栈未运行，--semantic 会记录提示并继续使用词法排序。

construct firecrawl up 会启动第二个、占用资源更多的栈（约 3 GB，使用独立的 extract 配置文件——不会由 semantic up 启动）。运行期间，研究流水线抓取的每个页面都会使用 Firecrawl 的正文 Markdown 进行清理，而不是使用内置的 HTML 提取器，因此即使页面由 JS 渲染，也能提取到证据。同样无需密钥。所有失败路径都会回退到内置提取器，并在档案备注中注明这一点，因此即使栈已停止，最坏的情况也只是恢复到之前的行为。 请参阅 references/semantic-setup.md。

参考资料

• references/brainstorm-playbook.md — 可选的发散步骤：从六个角度生成候选创意，并将保留的创意整合到简报中。
• references/interview-playbook.md — 如何一次提出一个问题来引导完成简报。
• references/brief-example.md — 填写完整的 brief.json、产生其中最难填写字段的对话，以及它奏效的原因。
• references/research-playbook.md — 选择角度并深入研究，直到达到“足够好”的程度。
• references/orchestration.md — 三层动态工作流模型及子 Agent 模式：研究扇出、红队、评审小组、论据支持审查扇出、构建扇出（以及单一写入者规则）。construct orchestrate 会生成可直接启动的扇出模式。
• references/adversarial-review.md — 红队检查清单及其发现项规范。
• references/srd-authoring.md — 处理 🧠 提示框、编写可测试需求和 ADR。
• references/design-system-authoring.md — 扩展 complex 设计系统：令牌、组件、屏幕/流程和无障碍规范。
• references/requirements-rubric.md — ISO/IEC/IEEE 29148:2018 的特性，check 会据此评估需求；还介绍两种严重级别，以及绿色门禁的含义与局限。
• references/acceptance-criteria.md — 不佳→良好的 Given/When/Then 改写示例，以及可量化的 NFR 指标模式。
• references/forbidden-patterns.md — 审查中绝不会通过的措辞，以及对应的替代写法。
• references/citation-format.md — [E#] 溯源规范。
• references/grounding-coverage.md — 说明建议性覆盖率报告的含义及如何提高覆盖率。
• references/build-playbook.md — 构建循环：任务 TDD、FR 标签规范、里程碑门禁和里程碑审查。
• references/verify.md — 说明每项 verify 检查能证明什么，以及哪些内容仍需人工检查。
• references/presenting.md — 第 7 步：交付 SRD 时该说什么，以及如何如实报告门禁结果。
• references/provider-apis.md — 如何按主机抓取 OSS issue/PR，无需密钥。
• references/web-discovery.md — 分层、免密钥的网页搜索。
• references/semantic-setup.md — 可选的本地 Docker 栈。