docs: document hwpod cli debug entrypoints

docs/reference/spec-hwpod-harness.md

@@ -188,6 +188,50 @@ bun tools/hwpod-node.ts serve --host 127.0.0.1 --port 19678
 
 `hwpod-cli` 的正常任务路径是：读取 spec、调用 compiler、把 node-ops plan 交给 `hwlab-api`，最后输出 closeout/result。`hwpod-ctl` 的管理路径可以在本地直接修改 spec，也可以生成 smoke plan 交给 `hwlab-api` 验证 node 链路。
 
+## HWPOD CLI 调试入口分层
+
+HWPOD 调试固定保留两种入口，二者必须调用同一套 `hwpod-cli` / `hwpod-ctl` / `hwpod-compiler-cli` 组合层，并最终走 `/v1/hwpod-node-ops` 到目标 `hwpod-node`。不要因为入口不同而复制下载、编译、串口或 job status 逻辑，也不要为 build、download、UART 或 job status 新增 node 专用 op。
+
+### 人工单步直调 hwpod-cli
+
+人工或维护 agent 定位 CaseRun 卡点时，优先在 G14 v0.2 workspace 直接调用 `hwpod-cli` 的单步命令。调用前必须加载 v0.2 CLI API key 和 runtime endpoint，并显式选择 run-local spec 或 case registry spec；spec 是 DAPLink、Keil target、COM 口、波特率和 subject worktree 的唯一输入权威。
+
+```bash
+. /root/.config/hwlab-v02/master-server-admin-api-key.env
+export HWLAB_RUNTIME_API_URL=http://74.48.78.17:19667
+export HWLAB_RUNTIME_WEB_URL=http://74.48.78.17:19666
+export HWLAB_RUNTIME_ENDPOINT_LOCKED=1
+
+bun tools/hwpod-ctl.ts spec validate --spec .hwlab/hwpod-spec.yaml
+bun tools/hwpod-cli.ts inspect --spec .hwlab/hwpod-spec.yaml
+bun tools/hwpod-cli.ts workspace cat --spec .hwlab/hwpod-spec.yaml --path projects/01_baseline/User/main.c
+bun tools/hwpod-cli.ts build --spec .hwlab/hwpod-spec.yaml
+bun tools/hwpod-cli.ts download --spec .hwlab/hwpod-spec.yaml
+bun tools/hwpod-cli.ts job status <jobId> --spec .hwlab/hwpod-spec.yaml
+bun tools/hwpod-cli.ts uart read --spec .hwlab/hwpod-spec.yaml --port uart1 --max-bytes 4096
+```
+
+直调入口只用于单步定位和原链路复测：`build` / `download` 返回 Keil async job accepted 只能证明命令已投递，不能等同于编译或下载成功；必须继续用 `hwpod-cli job status <jobId>` 轮询终态，并结合 `uart read`、Keil result 或目标串口日志解释结果。串口被人工工具占用时，应先释放 COM 口或读取已有 serial-monitor 数据解释现象，不得把 COM 口占用误判成 DAPLink、目标板或 API 不可用。
+
+### CaseRun 让 code agent 调 hwpod-cli
+
+CaseRun 验证 code agent 能力时，runner 的职责是布置舞台，而不是代替 agent 完成源码修改或硬件动作。标准流程是：CaseRun 从 case registry 读取 `case.json` 和 `hwpod-spec.yaml`，创建 subject 隔离 worktree，生成 run-local `.hwlab/hwpod-spec.yaml` 并把 `spec.workspace.path` 改写到该 worktree，再把当前 HWPOD CLI/skill 文件随 AgentRun workspace 一起提供给 code agent。
+
+code agent 必须在自己的 AgentRun workspace 内调用同一套入口，例如：
+
+```bash
+hwpod-ctl spec validate --spec .hwlab/hwpod-spec.yaml
+hwpod inspect --spec .hwlab/hwpod-spec.yaml
+hwpod workspace cat --spec .hwlab/hwpod-spec.yaml --path projects/01_baseline/User/main.c
+hwpod workspace replace --spec .hwlab/hwpod-spec.yaml --path projects/01_baseline/User/main.c --find <old> --replace <new> --expected-sha <sha>
+hwpod build --spec .hwlab/hwpod-spec.yaml
+hwpod download --spec .hwlab/hwpod-spec.yaml
+hwpod job status <jobId> --spec .hwlab/hwpod-spec.yaml
+hwpod uart read --spec .hwlab/hwpod-spec.yaml --port uart1 --max-bytes 4096
+```
+
+CaseRun prompt 只能描述任务、边界、允许修改的文件、必须尝试的 HWPOD 命令和需要回报的 raw output/job id/串口尾部；不得把具体源码补丁、预期答案或自动评价逻辑写成 prompt。CaseRun result 负责归档 agent session id、trace id、agent message、final response、workspace diff、HWPOD command trace 和 registry run 产物；不做 evidence 自动评价、不做门禁、不把 runner 后置命令伪装成 agent 命令。若某个步骤卡住，先用人工单步直调入口复测同一 spec 和同一 subject worktree，确认是 HWPOD CLI/Keil/serial-monitor/hwpod-node 业务问题后再修复对应组合层或 node 本体。
+
 ## CaseRun 无服务阶段
 
 第一阶段 CaseRun 不引入常驻调度服务，由 `hwlab-cli case` 组合 case registry repo、本地 `.state`、`hwpod-cli`、`hwpod-compiler-cli`、`hwlab-api` 和在线 `hwpod-node` 完成单次运行。标准 case registry repo 是 `pikasTech/hwlab-case-registry`，本地默认 checkout 路径是 `/root/hwlab-case-registry`；历史 `pikasTech/hwpod-cases` 只作为迁移前来源。case registry repo 提供 `cases/<caseId>/case.json` 与同目录 `hwpod-spec.yaml`；每次运行会先在 subject repo 本地 checkout 下创建隔离 Git worktree，再把 spec 复制到 `.state/hwlab-cli/caserun/<runId>/.hwlab/hwpod-spec.yaml` 并把 `spec.workspace.path` 改写到该隔离 worktree，形成 run-local spec。