Kemerd/hardware-in-the-loop

硬件在环

您正在设置（或运行）一个硬件项目，其中智能体执行工程任务，并通过关卡进行验证。在操作之前请完整阅读此文件。该方法在仓库的 docs/ 目录中有详细描述（包括 METHOD、PCB、CAD、FIRMWARE、SIM、SWARM、TOOLS、LESSONS）；此文件是操作流程。

0. 首先说明成本

在执行任何其他操作之前，向用户直白地说明：

使用集群代理运行此方法成本高昂。在它来源的项目中，一个集群日消耗了 400-500 万个 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、slot / detach / watch / merge lock / merge-to-dev / promote / WIP backup / handoff hook / status line 脚本）和 .claude/settings.local.json（包含 status line 和 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 <用户配置文件之外的文件夹> [-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 虚拟环境。它会写入 <ToolsRoot>/hil_tools.env，包含 HIL_FREEROUTING_JAR、HIL_JAVA、HIL_KICAD_CLI、HIL_CQ_PYTHON。在安装任何机器全局软件之前要询问；首先运行 -VerifyOnly 并向用户显示缺少的内容。任何内容都不应放入用户配置文件。

4. Git：main 和 dev

在目标仓库中（如果仓库已有历史记录，请先询问再运行 git）：

git init -b main            # 如果还不是一个仓库
git add -A && git commit -m "Project skeleton (hardware-in-the-loop method)"
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 <kind> <you> "<job>" <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_<area>.md。
2. 第 2 波，计划：PLAN.md（references/plan-template.md），包含通道、每个文件一个所有者（跨通道更改作为补丁文件放在 harness/swarm/handoff/ 中）、接口添加、验收数值；briefs.md，每个通道一个简报（references/brief-template.md）。
3. 第 3 波，工作树 swarm/<name> 中的通道：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 合并到 dev（始终执行，包括红色状态，在 MERGE_LOCK 下）；在 dev 上执行完整 CI，使用 -Compare <main 报告> -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.py）；将配合和碰撞 PNG 图（cad/render.py）放入 docs/cad_decisions/<date>/<topic>/。
• 固件：树外构建、使用 hil_check.h 的主机测试套件、通过真实接口的场景、种子扫描、确定性检查；列出待硬件验证的项目。
• 未完成的工作不能显示为已完成；仅限 bench 的常量获得 BENCH B-xx-nn ID。
• 机器：使用槽、低于正常的优先级、超时、绝不杀死非自己启动的进程、绝不从根目录执行 find、先检查磁盘、一次只能运行一个 Unreal / GPU 任务、当所有者正在使用机器时不得启动 Unreal。

9. 切换和过夜

• 当出现 HANDOFF_NOW（钩子会通知您）时，停止开始新工作并遵循其指令：提交、推送、释放、写入 harness/swarm/resume_<date>/RESUME_<date_time>_<lane>.md（references/resume-doc.md）。
• 在所有者为晚上离开前：设置一个分离的夜间链和第二天早上的问题（references/overnight-questions.md）。夜间任务使用默认值运行；记录每个采用的默认值。