construct — 將產品構想轉化為可執行的 SRD 套件

construct — 將產品構想轉化為可執行的 SRD

construct 將一個產品構想轉化為一份軟體需求文件套件，其需求和決策奠基於真實研究，而非模型自身的記憶。確定性引擎（scripts/construct.mjs，零依賴 Node.js）負責搜尋、彙整報告、渲染 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] — 「哪些地方不足？」報告：列出所有在渲染時會被標記為無依據的功能、競爭對手、技術、種子，並印出修補每個缺口所需的 drill 指令。僅供參考，不會阻擋流程。
• web|oss|tech|so --out <run> [--q "<焦點>"] [--url ...] [--seeds ...] [--docs-url <u,...>] — 針對一個角度進行深度挖掘（輸出至 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 不完整時 exit code ≠ 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 會在一個「必須有」的功能已建置完成但沒有對應的測試時失敗。
• status --out <run> [--json] — 顯示執行過程中已存在的內容；--json 會加入建置前線資訊（哪些 BUILD-PLAN 任務現在可建置，哪些被阻塞）。
• 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
   

   這會在網路上發現競爭對手、挖掘可比較的開源軟體專案（以及它們的 issue/PR 以了解實際陷阱），並拉取候選技術文件 + StackOverflow。閱讀 <run>/evidence/EVIDENCE.md。

3. 深入挖掘——直到 analyze 報告乾淨或用戶喊停。 執行：

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

   它會明確指出哪些地方不足——沒有匹配證據的功能、競爭對手、候選技術和開源軟體種子——並印出修補每個缺口所需的 drill 指令。分散處理： 如果你能產生並行的子代理，為每個缺口分配一個；每個子代理會獲得一句話的簡報、缺口說明、其 drill 指令以及自己的網路搜尋能力，並返回一個 ≤5 行的摘要加上值得作為依據的 URL。子代理不得直接寫入執行資料夾——drill 指令輸出至 stdout；只有 construct research 會寫入檔案，且只有你能執行它。將發現結果依序整合：construct web --url <u,...> --out <run> → 重新執行 research → 重新執行 analyze。（沒有子代理？自己逐一處理缺口。）告訴用戶你發現了什麼，並讓他們引導方向——優先處理「必須有」的功能和關鍵決策，當他們說足夠了就停止。參閱 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/）：用產品真實的品牌價值取代預先植入的設計 Token，驗證元件與畫面/流程清單，並將無障礙標準銳化至目標標準（從簡報推導，預設為 WCAG 2.2 AA）。參閱 references/design-system-authoring.md。

5. 對抗性審查——讓新的眼光來破壞它。 產生一個審查子代理，只給它執行資料夾路徑和 references/adversarial-review.md（沒有子代理？自己以敵意讀者的心態嚴格按照那份檢查清單進行審查）。它必須嘗試破壞 SRD——模稜兩可、不可測試的標準、遺漏的失敗路徑、引用洗白、矛盾——並返回帶有標籤的發現。修復每個 [blocker]，自行判斷 [advisory]，然後重新執行 check。當沒有新的阻塞點出現時停止循環（上限：3 輪，然後將剩餘問題提交給使用者）。對於 complex 等級中真正有爭議、難以推翻的 ADR，還要執行 references/orchestration.md 中的 3 人評審小組。

6. 驗證（三層）。

   • 結構性（強制）： node scripts/construct.mjs check --out <run>。它會在任何未解決的 🧠、完全沒有功能需求、FR 沒有驗收標準、掛空的實體/介面/非功能性需求引用、缺少必要的非功能性需求類別、或格式錯誤的 ADR 上失敗。修復直到通過為止。
   • 基礎依據（建議）： 同一個指令會印出覆蓋率——多少比例的需求/決策引用了證據。在重要的地方（關鍵決策）提高它；參閱 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 一個任務，必須 → 應該 → 可以，具備實體感知的依賴關係），其 acceptance 項目指向 SRD.json。你撰寫所有應用程式程式碼；引擎擔任裁判。 遵循 references/build-playbook.md：

   • 執行 T-000（建立 scaffolding、測試框架、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 worktree；只有你負責將結果合併回 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  (ADR)
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 ↔ 實體 ↔ 介面 ↔ 元件 ↔ 畫面)
evidence/      EVIDENCE.md · evidence.json · meta.json   ·   brief.json · SRD.json

light 等級保持精簡；complex 等級則加入完整的非功能性需求集合、第二份 ADR、失敗路徑的驗收標準、完整的可追溯性矩陣，以及一個設計系統子目錄（design/：原則、Token、元件、畫面/流程、無障礙合約——使用 --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 — 解決 🧠 提示、撰寫可測試的需求和 ADR。
• references/design-system-authoring.md — 豐富 complex 設計系統：Token、元件、畫面/流程和無障礙合約。
• 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 — 如何按主機、無需金鑰地獲取開源軟體 issue/PR。
• references/web-discovery.md — 分層的、無需金鑰的網路搜尋。
• references/semantic-setup.md — 可選的本地 Docker 堆疊。