fix: smooth hwpod harness commands

docs/reference/spec-hwpod-harness.md

@@ -105,7 +105,7 @@ spec:
 - `spec.nodeBinding.nodeId` 必须存在。
 - `spec.workspace.path` 必须存在。
 
-Keil MDK 装配规则：当 `spec.workspace.toolchain` 为 `keil-mdk`、`keil`、`mdk` 或 `uv4` 时，`hwpod-compiler-cli` 可以直接从 `hwpod-spec` 生成 `debug.build` / `debug.download` 的 node-side command。`spec.workspace.keilProject` 或 `spec.workspace.projectPath` 指向 `.uvprojx`，相对路径按 `spec.workspace.path` 解析；`spec.workspace.keilTarget` 或 `spec.workspace.targetName` 指向 Keil target。`spec.debugProbe.probeUid` 用于固定 DAP-Link/CMSIS-DAP 选择，`spec.debugProbe.programBackend` 默认按 Keil UV4 工程链路下载。下载前若存在 `probeUid`，compiler 会先生成 Keil probe-binding 写回命令，再生成 `program --program-backend keil` 命令，以保持旧 host profile 中 probe 绑定与 Keil 下载语义在新 hwpod 概念系统内收敛。自动生成的 Keil 下载计划必须拆成独立 `cmd.run` 步骤，并使用 `command` + `argv` 传递参数；`probeName`、Windows 路径和 target 名称必须作为独立 argv 元素，不得依赖 `cmd.exe /c`、PowerShell 或 `&&` 拼接来保真带空格参数。
+Keil MDK 装配规则：当 `spec.workspace.toolchain` 为 `keil-mdk`、`keil`、`mdk` 或 `uv4` 时，`hwpod-compiler-cli` 可以直接从 `hwpod-spec` 生成 `debug.build` / `debug.download` 的 node-side command。`spec.workspace.keilProject` 或 `spec.workspace.projectPath` 指向 `.uvprojx`，相对路径按 `spec.workspace.path` 解析；`spec.workspace.keilTarget` 或 `spec.workspace.targetName` 指向 Keil target。`spec.debugProbe.probeUid` 用于固定 DAP-Link/CMSIS-DAP 选择，`spec.debugProbe.programBackend` 默认按 Keil UV4 工程链路下载。标准下载语义必须由 compiler 生成 Keil `flash` 命令，让 build+program 留在同一个 Keil 异步 job 中；不得依赖预先存在的 artifact、手工 uvoptx 状态或旧 profile 副作用。只有 `spec.debugProbe.autoBindUvoptx` / `autoBindProbe` 显式打开时，compiler 才生成 probe-binding 写回步骤。自动生成的 Keil 计划必须使用已有 `cmd.run` op，并用 `command` + `argv` 传递参数；`probeName`、Windows 路径和 target 名称必须作为独立 argv 元素，不得依赖 `cmd.exe /c`、PowerShell 或 `&&` 拼接来保真带空格参数。Keil 长任务默认异步启动，后续用 `hwpod-cli job status <jobId>` 查询；该入口仍编译为 `cmd.run` 调已有 Keil CLI，不新增 node op。
 
 `spec.workspace.buildCommand`、`spec.debugProbe.downloadCommand` 和 `spec.debugProbe.resetCommand` 仍是调试覆盖出口；标准 case 和 Code Agent runner 不应依赖这些字段长期手写 Keil 主流程。旧 `device-host-cli` / device pod profile 不再作为 compiler 输入权威，相关工程、target、probe 和下载 backend 信息必须迁入 `hwpod-spec`。
 
@@ -133,11 +133,11 @@ Keil MDK 装配规则：当 `spec.workspace.toolchain` 为 `keil-mdk`、`keil`
 | `io.uart.jsonrpc` | 通过 UART 做 JSON-RPC |
 | `cmd.run` | 临时维护命令透传，仅用于 `hwpod-ctl` 或早期薄 node 调试 |
 
-`hwpod-node` 是 HWPOD 的唯一受控节点执行器。`cmd.run` 的命令解析、PATH 稳定性和跨平台差异必须在 `hwpod-node` 本体内处理；当 Windows service、后台进程或 D601 host 的环境变量与交互 shell 不一致时，不得用 gateway shell、手工 PowerShell、预先手工创建 worktree 或其他旁路代替 `hwpod-node-ops -> hwpod-node`。D601/Windows 实地调试应使用 UniDesk SSH 透传 `D601:win` 观察进程、PATH、工具安装位置和日志，但修复必须回到 `hwpod-node` 源码、配置或启动入口，并用 `/v1/hwpod-node-ops` 原链路复测。
+`hwpod-node` 是 HWPOD 的唯一受控节点执行器。第一阶段的业务扩展优先落在 `hwpod-compiler-cli` / `hwpod-cli`，通过已有文件读写 op 和 `cmd.run` 组合 Keil、serial-monitor 等成熟工具；不要因为某个 case 需要 build、job status、download、UART 或临时维护动作就新增专用 node op。`cmd.run` 的命令解析、PATH 稳定性和跨平台差异必须在 `hwpod-node` 本体内处理；当 Windows service、后台进程或 D601 host 的环境变量与交互 shell 不一致时，不得用 gateway shell、手工 PowerShell、预先手工创建 worktree 或其他旁路代替 `hwpod-node-ops -> hwpod-node`。D601/Windows 实地调试应使用 UniDesk SSH 透传 `D601:win` 观察进程、PATH、工具安装位置和日志，但修复必须回到 `hwpod-node` 源码、配置或启动入口，并用 `/v1/hwpod-node-ops` 原链路复测。
 
 Windows subject worktree 文本修改优先使用 `workspace.apply-patch`、`workspace.replace`、`workspace.insert-after` 或 `workspace.write`，不要把 `cmd.run` 的 PowerShell/cmd quoting 当成标准编辑路径。文本编辑结果必须返回编辑前后 SHA、文件字节数、换行类型、diff 摘要和 dry-run 状态；`apply-patch` 匹配失败时必须返回 normalized preview、候选行号、CRLF/LF 统计、文件 SHA/bytes 和 hwpod-node implementation version，便于判断是上下文不匹配、CRLF 问题还是远端实现版本问题。`workspace.apply-patch` 应保留原文件换行风格，尤其不能把 CRLF subject 文件静默改写成 LF。
 
-UART read 由薄 `hwpod-node` 绑定节点本地 `serial-monitor` CLI 执行。默认绑定路径是 `~/.agents/skills/serial-monitor`，也可通过 `HWPOD_SERIAL_MONITOR_DIR` / `HWPOD_SERIAL_MONITOR_COMMAND` 或 plan args 覆盖；`spec.ioProbe.uart.port` 和 `spec.ioProbe.uart.baudrate` 是物理串口和波特率权威。`io.uart.read` 只能在 `serial-monitor monitor status` 显示正在监控同一 COM/baud 时返回数据；未监控、串口不匹配或工具失败时必须返回结构化 blocker details，至少包含请求 port、解析出的物理 port/baud、workspacePath、平台、node version、monitor status、可用 ports 和启动建议。不得静默伪造空读数，也不得要求 Agent 改走手写 PowerShell/串口脚本旁路。
+UART read 默认由 compiler 把 `hwpod-cli uart read` 编译为已有 `cmd.run` 内的一段短序列，调用节点本地 `serial-monitor` CLI 的 `monitor start` 和 `fetch --session-only`。两步必须在同一个 `cmd.run` 内顺序执行：`monitor start` 的 JSON 若返回 `success:false`，该 `cmd.run` 必须以非 0 退出并停止，不得继续 fetch 旧会话数据。默认绑定路径是 `C:\Users\liang\.agents\skills\serial-monitor`，也可通过 `spec.tooling.serialMonitorDir`、`spec.ioProbe.serialMonitorDir` 或 CLI 参数覆盖；`spec.ioProbe.uart.port` 和 `spec.ioProbe.uart.baudrate` 是物理串口和波特率权威。串口采集失败时必须把 serial-monitor 的 stdout/stderr、exit code 和 command argv 原样留在 `cmd.run` result 中；不得静默伪造空读数，也不得要求 Agent 改走手写 PowerShell/串口脚本旁路。
 
 标准 plan 形态：
 
@@ -179,8 +179,12 @@ bun tools/hwpod-ctl.ts spec init --spec .hwlab/hwpod-spec.yaml
 bun tools/hwpod-ctl.ts spec validate --spec .hwlab/hwpod-spec.yaml
 bun tools/hwpod-compiler-cli.ts compile --spec .hwlab/hwpod-spec.yaml --intent workspace.ls --args '{"path":"."}'
 bun tools/hwpod-cli.ts inspect --spec .hwlab/hwpod-spec.yaml --dry-run
+bun tools/hwpod-cli.ts workspace read --spec .hwlab/hwpod-spec.yaml projects/01_baseline/User/main.c
 bun tools/hwpod-cli.ts workspace replace --spec .hwlab/hwpod-spec.yaml --path projects/01_baseline/User/main.c --find "old text" --replace "new text" --expected-sha <sha>
 bun tools/hwpod-cli.ts workspace insert-after --spec .hwlab/hwpod-spec.yaml --path projects/01_baseline/User/main.c --anchor "while (1)" --line "  /* marker */"
+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
 bun tools/hwpod-node.ts serve --host 127.0.0.1 --port 19678
 ```