chore(全仓): @build/@test 旧文档别名清退为技能调用名
现状口径：/keil-build 与 /serial-boot-test 是 DSH 会话的技能调用名， 不是 shell 命令；「名 + 命令行参数」的命令形态改为可执行体 run_boot_test.py 的真实调用。 - AGENTS.md：别名说明重写为「技能调用名不是 shell 命令」，两条目改 「编译（/keil-build）」「串口回归（/serial-boot-test）」 - keil-build / serial-boot-test 两 skill 调用名与示例同步；task-worktree 方案文档去掉 @build/@test 惯例从句；@task 保留（不在点名范围） - 123 文件现状陈述全改；台架捕获、变更记录/时间线、rename 映射输入 等 41 行历史证据保留旧名 - gen_memory_svg.py 6 处措辞随改，3 张 SVG 产物同批重跑 - 顺手补并行方案同行漏网计数 51→52 钩子 验证：提交期快钩子对 123 文件实跑全 Passed；check_doc_links --all rc=0（3038 处、无法判定 0）；check_mermaid --all rc=0；YAML 解析 52 钩子不变；skill-size rc=0；py_compile 全过；字节卫生零漂移。
This commit is contained in:
+10
-10
@@ -14,7 +14,7 @@
|
||||
|
||||
| # | 缺陷 | 影响 |
|
||||
|---|---|---|
|
||||
| F1 | 二进制绑定**用户档案**：`opencode.json` 的 `mcp.serial` 指向 `C:\Users\16241\AppData\Local\serial-mcp-server\*.exe`，本机实际用户为 **Administrator**（该档案不存在，二进制缺失） | serial MCP 工具不可用、@test 采集步骤断裂；换机器/换用户无法复现 |
|
||||
| F1 | 二进制绑定**用户档案**：`opencode.json` 的 `mcp.serial` 指向 `C:\Users\16241\AppData\Local\serial-mcp-server\*.exe`，本机实际用户为 **Administrator**（该档案不存在，二进制缺失） | serial MCP 工具不可用、/serial-boot-test 采集步骤断裂；换机器/换用户无法复现 |
|
||||
| F2 | **无历史缓冲**：`read` 只能读调用**之后**到达的字节 | 抓开机日志被迫走"采集窗口 + first-byte 触发 + EOF 重试"仪式（6 个参数 + JSON 解析 + CH340 释放后重开陷阱特判） |
|
||||
|
||||
Python 重写一并解决：依赖收敛到仓库 `.venv + pyserial`（任意机器/用户可复现）；常驻 daemon 把**全量** RX/TX 持续写入日志文件，历史 = 日志文件本身，采集窗口仪式整体消失。
|
||||
@@ -28,7 +28,7 @@ Python 重写一并解决：依赖收敛到仓库 `.venv + pyserial`（任意机
|
||||
| G3 | Agent 一切操作 = 带硬超时（5s）的短命令；串口所有权归常驻 daemon |
|
||||
| G4 | 一条 `status` 命令看全状态（daemon/端口/计数/最后 RX/日志文件/错误） |
|
||||
| G5 | 随时清空日志（原子 + 代际号，新旧内容可区分） |
|
||||
| G6 | @test 一键流程切换新工具：open → clear → 烧录 → 读文件 → verify，无采集窗口 |
|
||||
| G6 | /serial-boot-test 一键流程切换新工具：open → clear → 烧录 → 读文件 → verify，无采集窗口 |
|
||||
| G7 | 全流程**不关端口**（ST-Link 烧录不占 COM），从根上规避 CH340 释放/重开陷阱 |
|
||||
|
||||
## 2. 需求清单
|
||||
@@ -45,7 +45,7 @@ Python 重写一并解决：依赖收敛到仓库 `.venv + pyserial`（任意机
|
||||
| R8 | 日志 20MB 上限，超限**原地截头**保留尾部 10MB（不重开端口/不 rename） | P0 | 补充（用户确认） |
|
||||
| R9 | 开端口不翻转 DTR/RTS（防 STM32 自动复位电路误复位），可配置 | P0 | 补充 |
|
||||
| R10 | 串口读错/拔线 → daemon 存活，state=error，可重开；daemon 被杀可自恢复 | P0 | 补充 |
|
||||
| R11 | @test 集成：`run_boot_test.py` 采集步改写 + `verify_log.py` 兼容 + 旧文档/配置迁移 | P0 | 用户场景 |
|
||||
| R11 | /serial-boot-test 集成：`run_boot_test.py` 采集步改写 + `verify_log.py` 兼容 + 旧文档/配置迁移 | P0 | 用户场景 |
|
||||
| R12 | `send`（TX 进日志）、`log --tail/--grep`、`start/stop/restart`、`selftest` 无头自检 | P1 | 补充 |
|
||||
|
||||
## 3. 总体方案
|
||||
@@ -84,7 +84,7 @@ flowchart LR
|
||||
| `send` | 发 TX 字节（进日志）；默认**精确字节**不加换行 | 位置参数文本（UTF-8）或 `--hex 0D0A`；`--nl` 追加 CRLF | `{"ok":true,"bytes":12}` |
|
||||
| `status` | 全状态（见 §4.2） | — | 见 §4.2 |
|
||||
| `log` | 读日志（**先过滤后截尾**，2026-10-10） | `--tail N`（默认 50；`0` = 全部）`--grep P` `-i` `--regex` | `{"ok":true,"gen":8,"lines":["…"],"scanned":N,"matched":M}` |
|
||||
| `wait-idle` | 等 RX 静默（@test 收尾判据） | `--settle-ms`（默认 8000）`--max-ms`（默认 30000）`--first-timeout-ms`（默认同 max） | `{"ok":true,"rx_bytes":本次增量,"idle":bool,"waited_ms":N,"reason":"idle\|no_data\|timeout"}` |
|
||||
| `wait-idle` | 等 RX 静默（/serial-boot-test 收尾判据） | `--settle-ms`（默认 8000）`--max-ms`（默认 30000）`--first-timeout-ms`（默认同 max） | `{"ok":true,"rx_bytes":本次增量,"idle":bool,"waited_ms":N,"reason":"idle\|no_data\|timeout"}` |
|
||||
| `clear` | 清空日志：原地截断 + 写 `[SYS] log cleared (gen=N+1)` | — | `{"ok":true,"gen":8}` |
|
||||
| `start` / `stop` / `restart` | daemon 生命周期 | — | `{"ok":true,"pid":…}` / stop 后 `{"ok":true,"stopped":true}` |
|
||||
| `selftest` | 无头自检（行拆分器/解码回退/截头算法 单测回环，无需硬件） | — | 0=PASS |
|
||||
@@ -175,13 +175,13 @@ flowchart LR
|
||||
| 重开退避 | 错误恢复路径重开端口前 ≥1.5s 退避（CH340 特性）；正常流程不重开 |
|
||||
| `stop` | 关端口（flush 尾行）→ 写 `[SYS] port closed` → 退出 |
|
||||
| 进程被强杀 | Windows 进程退出自动释放 COM 端口；下次命令自动拉起新实例（`open` 幂等路径） |
|
||||
| `wait-idle` 判据（2026-10-10 修） | `no_data` = **本次等待期间零字节**（旧实现比的是 daemon 累计 `rx_bytes` 是否为 0 → 常驻 daemon 下永不触发，板子全程静默也误报 `idle:true`，@test 的 no_data 拦截形同虚设）；**首字节到达前不启动 settle 计时**（`first_timeout_ms` 兜底，默认 = `max_ms`）；返回 `rx_bytes` = 本次增量 |
|
||||
| `wait-idle` 判据（2026-10-10 修） | `no_data` = **本次等待期间零字节**（旧实现比的是 daemon 累计 `rx_bytes` 是否为 0 → 常驻 daemon 下永不触发，板子全程静默也误报 `idle:true`，/serial-boot-test 的 no_data 拦截形同虚设）；**首字节到达前不启动 settle 计时**（`first_timeout_ms` 兜底，默认 = `max_ms`）；返回 `rx_bytes` = 本次增量 |
|
||||
| CLI 超时与断连噪声（2026-10-10） | `wait-idle` 未显式带 `--timeout` 时按 `max_ms/1000 + 5` 自动推导（旧版固定 5s 会在 daemon 还在等时掐断连接）；handler 侧 `ConnectionError`（客户端已断开）不再往 daemon.log 打 traceback（本机曾累积 16 次）；`daemon.log` 超 1MB 在拉起新实例前原地保尾 256KB |
|
||||
| 配置读取（2026-10-10） | 按 `utf-8-sig` 读（容忍 BOM，与 `run_boot_test.py` 同口径）；文件缺失 / JSON 语法错 / `baudRate`·`httpPort` 非整数不再静默回退成"没配端口"，错误文本进 `configError`，由 `status` / `ports` / `open` 显式回显 |
|
||||
|
||||
## 7. 集成与迁移（@test 切换）
|
||||
## 7. 集成与迁移（/serial-boot-test 切换）
|
||||
|
||||
### 7.1 新 @test 流程（`run_boot_test.py` 采集步改写，退出码约定不变：0/1/2/3）
|
||||
### 7.1 新 /serial-boot-test 流程（`run_boot_test.py` 采集步改写，退出码约定不变：0/1/2/3）
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@@ -193,7 +193,7 @@ flowchart LR
|
||||
```
|
||||
|
||||
- 对比旧流程：6 个采集窗口参数 + JSON 解析 + EOF 重试 **全部删除**；采集 = 端口常开 + 读文件
|
||||
- `verify_log.py` 与纯文本日志契约一致（2026-09-20 随 @test 迁移 Python，判定语义不变）
|
||||
- `verify_log.py` 与纯文本日志契约一致（2026-09-20 随 /serial-boot-test 迁移 Python，判定语义不变）
|
||||
- 参数保留：`-Port` `-BaudRate` `-FlashCmd` `-Required` `-Forbidden` `-OutDir`；删除 `-DurationMs` 等窗口参数，新增 `-SettleMs`（静默判据，**默认 8000**——boot 任务间有 3~4s 自然静默间隙，2000 会截断）`-MaxWaitMs`（默认 30000）
|
||||
|
||||
### 7.2 配套变更清单
|
||||
@@ -230,7 +230,7 @@ flowchart LR
|
||||
| A4 | `stop` 后强杀 daemon（taskkill）→ 再发任意命令 | 自动拉起成功，`open` 幂等路径无 CH340 EOF 错误 |
|
||||
| A5 | 日志灌至 >20MB | 自动截头至 ~10MB，写入连续、无重开端口，`[SYS] truncated` 行存在 |
|
||||
| A6 | 运行中拔 CH340 → `status` | daemon 存活，`state=error`；重插 + `open` 恢复 |
|
||||
| A7 | **@test E2E ×3**（含一轮"上轮端口未关"场景） | 三轮全 PASS（Required 标记齐、无 Forbidden），boot 日志完整 |
|
||||
| A7 | **/serial-boot-test E2E ×3**（含一轮"上轮端口未关"场景） | 三轮全 PASS（Required 标记齐、无 Forbidden），boot 日志完整 |
|
||||
| A8 | `selftest` | 0=PASS |
|
||||
|
||||
## 10. 实施步骤（按序执行）
|
||||
@@ -241,7 +241,7 @@ flowchart LR
|
||||
| 步骤 2 | daemon 核心：HTTP 服务 + 串口读线程 + 行日志写（含 clear/截头/DTR 策略） | `.dsh/skills/serial-assistant/scripts/serial_tool.py`（daemon 部分） | `start→status→send→stop` 手动走通 ✅ |
|
||||
| 步骤 3 | CLI 全子命令 + 自动拉起 + 超时契约 + `selftest` | serial_tool.py（CLI 部分） | `selftest` 0=PASS + 命令走查 ✅ |
|
||||
| 步骤 4 | 验收 A1–A6、A8 | 测试通过记录 | A1–A5/A8 PASS ✅（本机无 CH340，A6 待硬件） |
|
||||
| 步骤 5 | @test 集成：`run_boot_test.py` 采集步改写 + 参数收敛 | run_boot_test.py | 负路径（端口缺失→exit 2）+ 假烧录全链路 + verify 正/负判定 ✅；**A7 正路径待 CH340 接入** |
|
||||
| 步骤 5 | /serial-boot-test 集成：`run_boot_test.py` 采集步改写 + 参数收敛 | run_boot_test.py | 负路径（端口缺失→exit 2）+ 假烧录全链路 + verify 正/负判定 ✅；**A7 正路径待 CH340 接入** |
|
||||
| 步骤 6 | 文档/配置迁移（§7.2 全清单） | docs + 配置 | 全库 grep 无 serial-mcp-server 残留引用（本文 §12 工具历史除外） ✅ |
|
||||
|
||||
提交：全部完成后单提交（pre-commit 门禁；纯宿主侧 Python，不涉及 Keil 构建）。
|
||||
|
||||
Reference in New Issue
Block a user