Kemerd/hardware-in-the-loop

硬體迴圈

您正在設定（或執行）一個硬體專案，其中代理負責工程設計，而閘門則負責驗證。請在執行任何動作前閱讀整個檔案。該方法詳述於儲存庫的 docs/ 目錄中（METHOD、PCB、CAD、FIRMWARE、SIM、SWARM、TOOLS、LESSONS）；本檔案為作業程序。

0. 首先告知成本

在任何其他事項之前，請明確告知使用者：

使用群體代理執行此方法成本高昂。在其來源專案中，一個群體工作天消耗了 4-5 百萬個 Token，主要用於喚醒每個攜帶 300-800k Token 上下文的面代理。較便宜的模式是單一工作階段，無子代理，逐步進行，將長時間機器作業分離執行，並從「我在哪裡停止」章節恢復。您想要哪種模式？（建議：單一工作階段）

將答案記錄為 mode（single 或 swarm）。在使用者選擇群體模式之前，請勿產生任何子代理。

1. 入職訪談

透過問題對話執行 references/interview.md 中的訪談：每次最多四個問題，每個問題的建議預設值優先。當某個問題未獲得答案時，採用預設值並在其旁寫上「已採用預設值」。涵蓋範圍：專案目標與完成定義、目標優先順序、預算、數量、預設列印材料（碳纖維尼龍 / PETG / PLA / 機械加工鋁材）、緊固方式（熱熔嵌件 / 自攻螺絲 / 貫穿螺栓）、外殼（密封 / 通風 / 開放）、機械間隙、PCB 製造與組裝供應商、MCU 系列、主電源與最差瞬態、電路板等級與塗層、模擬層級（原生雙胞胎 / Isaac Sim / Unreal）及 GPU、機器限制（CPU 上限預設 90 %、保留給系統的 RAM 預設 4 GB、可用磁碟下限預設 50 GB）、歸檔位置、用量觸發閾值（預設 95 %）、既定決策。

材料、緊固方式、外殼密封與間隙為「專案決策」：絕不擅自選擇；務必詢問、建議、記錄。

將答案寫入目標儲存庫 .tmp/ 目錄下的 answers.json（結構定義於 references/interview.md）。

2. 產生骨架

python -I <skill>/scripts/scaffold.py --answers <repo>/.tmp/answers.json --dest <repo> [--with-examples] [--dry-run]

它會複製 templates/（README_AGENT.md、PROJECT_STRUCTURE.md、REQUIREMENTS.md、README.md、CODING_RULES.md、.gitignore、.gitattributes、windows/ci.ps1 + windows/ci/（群組 audit 與 pcb）、tools/（稽核 + 可攜性，含空追蹤基線與豁免檔案）、pcb/（DESIGN_STANDARDS.md、tools/kicad_env.py、tools/board_pipeline.py、tools/distributor_verify.py）、cad/（cad_plugins.py、render.py、mass_cg_table.py）、firmware/host_tests/hil_check.h、docs/bench/BENCH_REGISTER.md、docs/data/README.md、harness/swarm/（AGENT_RULES、插槽 / 分離 / 監控 / 合併鎖定 / 合併至開發分支 / 提升 / WIP 備份 / 交接鉤子 / 狀態行腳本）以及 .claude/settings.local.json（狀態行 + PostToolUse 鉤子）），填入樣板變數，並為所選模式寫入 harness/swarm/machine.env 與 harness/swarm/PLAN.md。它絕不覆蓋現有檔案；請手動比較保留的檔案，並合併有用的部分。--with-examples 會新增範例電路板（一個 2 層 3.3 V LDO 降壓板，可執行所有管線步驟）與包含兩個插件的範例外殼建構器。

接著根據答案填入 pcb/DESIGN_STANDARDS.md 第 0 節的決策表。

3. 工具

pwsh -File <skill>/scripts/setup_tools.ps1 -ToolsRoot <a folder outside the user profile> [-VerifyOnly]
bash <skill>/scripts/setup_tools.sh --tools-root <dir> [--verify-only]          # Linux

KiCad 10 (winget)、Java 21 (winget)、Freerouting 2.1.0（固定 SHA-256）、OSS CAD Suite 2026-10-24（固定 SHA-256，僅用於 FPGA 專案）、一個 CadQuery 虛擬環境。它會將 HIL_FREEROUTING_JAR、HIL_JAVA、HIL_KICAD_CLI、HIL_CQ_PYTHON 寫入 <ToolsRoot>/hil_tools.env。在進行任何機器全域安裝前請先詢問；首先執行 -VerifyOnly 並向使用者顯示缺少的項目。不會有任何東西寫入使用者設定檔。

4. Git：主要分支與開發分支

在目標儲存庫中（在已有歷史記錄的儲存庫中執行 git 命令前請先詢問）：

git init -b main            # 當它還不是一個儲存庫時
git add -A && git commit -m "專案骨架 (硬體迴圈方法)"
git branch dev
git push -u origin main dev # 當遠端存在時

使用機器已設定的 git 身份。不要加入署名行或共同作者尾綴。絕不強制推送。 然後執行首次 CI 流程，並將其報告作為主要參考保留：

pwsh -File windows/ci.ps1 -Only audit

5. 武裝工具組

• .claude/settings.local.json 會連線 usage_statusline.py（狀態行，HIL_HANDOFF_PCT 的觸發閾值）以及 handoff_hook.sh（PostToolUse）。驗證鉤子：touch harness/swarm/HANDOFF_SELFTEST，執行任何工具，預期看到「鉤子已啟用」上下文，然後刪除該檔案。
• 以分離方式啟動 WIP 備份：bash harness/swarm/detach.sh harness/swarm/wip_backup.sh .tmp/wip_backup.log。
• 檢查 bash harness/swarm/locks/slot.sh status。
• 主工作階段從主要檢出目錄執行（harness/ 所在位置）；編輯在工作樹中進行。

6. 工作：單一工作階段模式（預設）

遵循 harness/swarm/PLAN.md（來自 references/single-session-plan.md）：

1. 一次一個編號步驟，每個步驟都有驗證它的閘門。
2. 在 .claude/worktrees/main-work 中以 swarm/main-work 分支工作；提交、推送、並在每個閘門通過綠色後執行 merge_to_dev.sh。
3. 繁重作業：eval "$(bash harness/swarm/locks/slot.sh take <種類> <你> "<作業>" <GB>)"，完成後釋放。
4. 長時間作業：bash harness/swarm/detach.sh <chain.sh> <log> 並立即以背景任務執行 bash harness/swarm/watch.sh <log>；繼續下一步驟。
5. 擁有者問題：批次處理，建議預設值優先；已採用的預設值寫入計畫。
6. 停止：附加「## 我在哪裡停止」（包含完成的 SHA、正在執行的作業及其 PID 與日誌、確切的下一步驟）。

7. 工作：群體模式

遵循 docs/SWARM.md 與 references/wave-checklist.md：

1. 第 1 波，偵察：唯讀代理將經驗證的事實以檔案:行數錨點形式寫入 harness/swarm/recon_<領域>.md。
2. 第 2 波，規劃：PLAN.md（references/plan-template.md）包含車道，每個檔案有一個擁有者（跨車道變更作為 harness/swarm/handoff/ 中的修補檔案）、介面新增、驗收數字；briefs.md 包含每個車道的一份簡報（references/brief-template.md）。
3. 第 3 波，車道（位於工作樹 swarm/<名稱>）：Sonnet 用於機械工作（連接埠、編解碼器、渲染、測試、文件），Opus 用於細微工作（控制、物理、幾何、訊號完整性）。每個車道回傳結構化報告（references/structured-report.md）。
4. 第 4 波，懷疑者：新的代理僅查看差異與報告；執行 audit_placeholders.py --changed-since origin/dev --fail-on-new、該車道的 CI 群組、三個重新檢查的數字。
5. 第 5 波，整合：每個車道使用 merge_to_dev.sh 合併到開發分支（總是合併，紅色也包含在內，在 MERGE_LOCK 之下）；在開發分支上執行完整 CI，使用 -Compare <主要報告> -FailOn regressions；僅在零回歸時執行 promote_dev.sh。

保持車道數量少且簡報精確；每次喚醒一個大上下文代理都要花費真實金錢。

8. 紀律（兩種模式）

• PCB：生成器優先（docs/PCB.md）。ERC 0/0，DRC 0 違規 / 0 未連接 / 0 在預設嚴重等級下奇偶性一致，每個採購行即時驗證，製造設定 + STEP + 含 SHA-256 的結果 JSON。當自動佈局失敗時，預期您會手動放置。允許更多層數；報告價格差異。放寬規則需要引用依據。
• CAD：建構器 + 插件；每次零件變更時，產生質量/重心表（cad/mass_cg_table.md）；在 docs/cad_decisions/<date>/<topic>/ 中產生配合與干涉 PNG 圖（使用 cad/render.py）。
• 韌體：樹外建構，主機測試套件使用 hil_check.h，透過真實介面的情境測試，種子掃描，確定性；列出待處理的硬體項目。
• 未完成的工作不得標示為完成；僅限測試台的常數需有 BENCH B-xx-nn 識別碼。
• 機器：插槽，低於正常優先級，超時，絕不終止非自己啟動的行程，絕不從根目錄執行 find，先檢查磁碟空間，一次僅一個 Unreal / GPU 作業，擁有者在機器前時不得啟動 Unreal。

9. 交接與過夜

• 當 HANDOFF_NOW 出現時（鉤子會通知您），停止啟動新工作並遵循其指示：提交、推送、釋放、寫入 harness/swarm/resume_<date>/RESUME_<date_time>_<lane>.md（references/resume-doc.md）。
• 在擁有者離開過夜前：一個分離的夜間鏈與早晨的問題清單（references/overnight-questions.md）。夜間執行採用預設值；記錄每個已採用的預設值。