From b5846011748f324f28d56e38b3ef3e0c3bf24fd7 Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Wed, 18 Nov 2026 11:31:07 +0800 Subject: [PATCH] =?UTF-8?q?docs(skills):=20=E6=8C=89=E6=8A=80=E8=83=BD?= =?UTF-8?q?=E5=AE=A1=E6=A0=B8=E6=8A=A5=E5=91=8A=E6=8B=86=E5=88=86=208=20?= =?UTF-8?q?=E4=B8=AA=E5=A4=A7=E4=B8=BB=E6=96=87=E4=BB=B6=E5=B9=B6=E5=BD=92?= =?UTF-8?q?=E6=A1=A3=20IEC104=20=E6=8E=A2=E9=92=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 技能主文件只留默认路径、成功输出样例、失败索引表与禁令;长尾规程逐字 搬进各技能 reference/,索引键与 reference 小节标题一一对应。 拆分结果(改前 -> 改后,字节): - keil-build 21779 -> 5837,新建 3 篇 reference - task-worktree 24163 -> 11448,新建 4 篇 reference,A-G/C2 节号保号 - draw-diagram 18907 -> 6496,新建 5 篇 reference - mem-budget 13046 -> 8020,新建 4 篇 reference - id-family-semantic-migration 11509 -> 8077,新建 2 篇 reference - stale-doc-count-sweep 8156 -> 6371,新建 1 篇 reference - serial-boot-test 8464 -> 6663,新建 2 篇 reference - board-ui-nav 5350 -> 4364,新建 1 篇 reference 其余 9 个技能补真实成功输出样例(判据串取自本轮实跑或文档原文)。 check_skill_size.py rc=0,17 个主文件无悬空指针。 IEC104 探针入库:ci-artifacts/ 里可复用的三个验收脚本迁入 test/host/iec104_dtu/(纯标准库、argparse、ASCII 输出、exit 0/1/2), 协议逻辑逐字保留,含三处探针自身缺陷修复(GI 漏 3 字节 IOA、I 帧 过滤判反、MEAS 键用 source_addr 而非 IOA)。一次性设计度量按 PROBE_INDEX.md 登记不迁入,运行方法见 PROBE_RUNBOOK.md。 --- .dsh/skills/board-test-suite/SKILL.md | 8 + .dsh/skills/board-ui-nav/SKILL.md | 27 +-- .../skills/board-ui-nav/reference/recovery.md | 41 ++++ .dsh/skills/cubemx-regen/SKILL.md | 8 + .dsh/skills/draw-diagram/SKILL.md | 219 +++--------------- .../draw-diagram/reference/collision-audit.md | 54 +++++ .../draw-diagram/reference/generated-fresh.md | 45 ++++ .dsh/skills/draw-diagram/reference/traps.md | 30 +++ .../reference/verify-checklist.md | 28 +++ .../draw-diagram/reference/visual-inspect.md | 58 +++++ .dsh/skills/font-regen/SKILL.md | 7 + .../id-family-semantic-migration/SKILL.md | 24 +- .../reference/attribution.md | 20 ++ .../reference/verification.md | 24 ++ .dsh/skills/keil-build/SKILL.md | 212 ++++------------- .../keil-build/reference/build-env-error.md | 73 ++++++ .../skills/keil-build/reference/build-lock.md | 48 ++++ .../reference/executor-shell-forms.md | 18 +- .../skills/keil-build/reference/iron-rules.md | 67 ++++++ .../reference/systemdrive-junk-dir.md | 18 +- .dsh/skills/lvgl-simulator/SKILL.md | 8 + .dsh/skills/mem-budget/SKILL.md | 183 +++++---------- .../mem-budget/reference/backfill-flags.md | 41 ++++ .../mem-budget/reference/backfill-order.md | 46 ++++ .../mem-budget/reference/backfill-pitfalls.md | 18 ++ .../reference/measurement-identity.md | 18 ++ .../mem-budget/reference/runtime-jitter.md | 28 +++ .../reference/shared-frame-attribution.md | 18 ++ .../mem-budget/reference/verification.md | 31 +++ .dsh/skills/new-machine-setup/SKILL.md | 7 + .dsh/skills/new-source-file/SKILL.md | 8 + .dsh/skills/serial-assistant/SKILL.md | 7 + .dsh/skills/serial-boot-test/SKILL.md | 51 ++-- .../reference/config-schema.md | 31 +++ .../reference/troubleshooting.md | 37 +++ .dsh/skills/stale-doc-count-sweep/SKILL.md | 15 +- .../reference/verification.md | 23 ++ .dsh/skills/stlink-flash/SKILL.md | 10 + .dsh/skills/task-worktree/SKILL.md | 198 +++++----------- .../reference/clean-room-measure.md | 18 ++ .../reference/concurrency-limit.md | 28 +++ .../reference/dsh-plugin-bridge.md | 18 ++ .../task-worktree/reference/gates-in-tree.md | 18 ++ .../task-worktree/reference/iron-rules.md | 31 +++ .../reference/merge-dirty-main-tree.md | 18 ++ .../reference/merge-point-done.md | 44 ++++ .../task-worktree/reference/pitfalls.md | 18 ++ .../reference/reclaim-unregistered.md | 18 ++ .../reference/unregistered-lock-holder.md | 29 +++ .../task-worktree/reference/verification.md | 18 ++ .dsh/skills/ui-verify/SKILL.md | 7 + test/host/README.md | 3 + test/host/iec104_dtu/PROBE_INDEX.md | 92 ++++++++ test/host/iec104_dtu/PROBE_RUNBOOK.md | 55 +++++ .../iec104_dtu/verify_board_acceptance.py | 164 +++++++++++++ .../verify_simulator_duration_evidence.py | 120 ++++++++++ .../iec104_dtu/verify_simulator_lan_bind.py | 113 +++++++++ 57 files changed, 1918 insertions(+), 701 deletions(-) create mode 100644 .dsh/skills/board-ui-nav/reference/recovery.md create mode 100644 .dsh/skills/draw-diagram/reference/collision-audit.md create mode 100644 .dsh/skills/draw-diagram/reference/generated-fresh.md create mode 100644 .dsh/skills/draw-diagram/reference/traps.md create mode 100644 .dsh/skills/draw-diagram/reference/verify-checklist.md create mode 100644 .dsh/skills/draw-diagram/reference/visual-inspect.md create mode 100644 .dsh/skills/id-family-semantic-migration/reference/attribution.md create mode 100644 .dsh/skills/id-family-semantic-migration/reference/verification.md create mode 100644 .dsh/skills/keil-build/reference/build-env-error.md create mode 100644 .dsh/skills/keil-build/reference/build-lock.md create mode 100644 .dsh/skills/keil-build/reference/iron-rules.md create mode 100644 .dsh/skills/mem-budget/reference/backfill-flags.md create mode 100644 .dsh/skills/mem-budget/reference/backfill-order.md create mode 100644 .dsh/skills/mem-budget/reference/runtime-jitter.md create mode 100644 .dsh/skills/mem-budget/reference/verification.md create mode 100644 .dsh/skills/serial-boot-test/reference/config-schema.md create mode 100644 .dsh/skills/serial-boot-test/reference/troubleshooting.md create mode 100644 .dsh/skills/stale-doc-count-sweep/reference/verification.md create mode 100644 .dsh/skills/task-worktree/reference/concurrency-limit.md create mode 100644 .dsh/skills/task-worktree/reference/iron-rules.md create mode 100644 .dsh/skills/task-worktree/reference/merge-point-done.md create mode 100644 .dsh/skills/task-worktree/reference/unregistered-lock-holder.md create mode 100644 test/host/iec104_dtu/PROBE_INDEX.md create mode 100644 test/host/iec104_dtu/PROBE_RUNBOOK.md create mode 100644 test/host/iec104_dtu/verify_board_acceptance.py create mode 100644 test/host/iec104_dtu/verify_simulator_duration_evidence.py create mode 100644 test/host/iec104_dtu/verify_simulator_lan_bind.py diff --git a/.dsh/skills/board-test-suite/SKILL.md b/.dsh/skills/board-test-suite/SKILL.md index a3627f1e..cd85e627 100644 --- a/.dsh/skills/board-test-suite/SKILL.md +++ b/.dsh/skills/board-test-suite/SKILL.md @@ -25,6 +25,14 @@ whenToUse: 要跑板级测试套件(CH395F/STORAGE/GD5F/RTC)回归、要开/ & '.venv\Scripts\python.exe' test/run_all_suites.py --dry-run # 只看计划 ``` +**成功输出样例**(出处:`docs/测试说明/板级测试/实机测试实施指南.md` §实测记录里的 GD5F 套件回归片段,及本轮 `--check-build` 实跑的还原行):看到 `=== GD5F2GQ5UE Tests: 16/16 PASSED (failed=0) ===` + `[GD5F] -> PASS` 就是通了,不用再往下看。 + +```text +=== GD5F2GQ5UE Tests: 16/16 PASSED (failed=0) === +[GD5F] -> PASS +[OK] 已还原 test_config.h 为产品构建(全部 TEST_SUITE_* 注释) +``` + - 脚本 try/finally **无条件还原 `test_config.h`**(含 Ctrl-C 路径)——这是它存在的核心 理由:跑完忘还原 = 测试固件进库。`--keep-config` 仅调试用。 - 退出码 0=全 PASS / 1=有 FAIL / 2=环境错误;4 套件真机一轮数分钟起,**仅回归窗口用,绝不挂 pre-commit**。 diff --git a/.dsh/skills/board-ui-nav/SKILL.md b/.dsh/skills/board-ui-nav/SKILL.md index d69302aa..b4d13fac 100644 --- a/.dsh/skills/board-ui-nav/SKILL.md +++ b/.dsh/skills/board-ui-nav/SKILL.md @@ -11,17 +11,6 @@ whenToUse: 需要上真机/台架进某页面看图(如故障录波、回放 `board_walk*.py` 盲按 `d*9`——而闭环导航器 2026-10-25 起就已存在(10-25 盲走事故 9 个目标只有 3 个落对,`docs/UI设计/UI_自动化测试流程.md` §7.1)。 -## 为什么不能自己搓(#69 复盘四类根因,全部有实证) - -1. **协议旧版零身份反馈**:KEY 的 ACK 是空帧,"发了 5 个键"≠"到了第 5 层"。(已修: - 7003 新增 STATUS 命令,固件直读 `s_depth/s_path/s_sel` + 当前内容页 id,见下) -2. **N−1 屏坑**:KEY ACK 与 LCDMEM 推流共用同一条 TCP,`sleep(0.30)` 就抓帧拿到的是 - 上一屏(规则①:排空到帧流静默 ≥900 ms;现在 `key()` 代码已真正执行排空+双帧比对)。 -3. **物理陷阱**:待机态按 `e` 是**重开最近页**不是进菜单;级联列光标记忆上次行不归零; - 根列最后两行的子列弹框被 160×160 屏裁掉(selftest/runlog 因此"读不到选带")。 -4. **认屏误判**:菜单子列标签与页标题同字(记录查询子列里的 事故记录/操作记录…), - 像素分类器会把级联菜单判成 PAGE——**有 STATUS 时以 STATUS 为准**,trace 留痕不一致。 - ## 命令(python 一律 .venv;真机动作必须已持 bench 锁并加 --i-hold-bench-lock) ```powershell @@ -53,16 +42,14 @@ whenToUse: 需要上真机/台架进某页面看图(如故障录波、回放 - 执行类页面 `clear`/`reset`(第二次 ENTER 即真执行)主机与固件**双侧**默认拒绝, `--allow-exec-pages` 才放行,放行 = 接受后果。 -## 走错页 / 未知屏恢复配方(按序,不跳步) +## 失败处置索引(退出码 / 报错 → 查哪一节) -1. `--where` 先看 STATUS:`PAGE` → 按 `s` 关页(导航器 `--to` 自动做); - `STANDBY` → 按 `e` 唤醒(注意规则②:home 上 `e` 可能重开最近页); - `MENU depth>0` → 按 `s` 或 `l` 都收一级(台架复核 2026-11-02:菜单态 `s` 与 `l` 同走 - `menu_back`,父列选中留在原地;旧说法"`s` 不收列"系把待机态 `s` 无效误读成菜单行为)。 -2. STATUS 无应答(老固件)才吃退避键序(默认 `esl`,`--backoff-keys sl` 可去 ENTER); - ENTER 上限 1 次是硬闸(BACKOFF_MAX_E),报停机就 dump 帧人眼看,不许连按。 -3. 反复落错页且 trace 里出现"像素与 STATUS 不一致" → 分类器或固件有账要记, - 把留痕帧 `--dump-fail` 存下交 Lead,**不要**改判据迁就现状。 +执行体 `scripts/board_ui_nav.py` 在仓库根 `scripts/`、不在本技能目录,脚本无法打印技能内指针——**本表由主文件显式维护**。退出码:`0` 成功 / `1` 分类或导航失败 / `2` 环境错误 / `3` 拒动(未持锁确认位等)。失败时按索引键到 [recovery.md](reference/recovery.md) 读**同名小节**(每节 = 判据 / 处置 / 证据边界);正常路径不展开。 + +| 索引键(退出码 / 现象) | 何时读(触发条件) | 去哪 | +|---|---|---| +| `classification-failure` | 退出码 1、落错页、trace 里像素与 STATUS 不一致 | `recovery.md` 的 `classification-failure` 节 | +| `navigation-recovery` | 停在未知屏 / STANDBY / 级联列收不回 / 老固件无 STATUS | `recovery.md` 的 `navigation-recovery` 节 | ## 边界 diff --git a/.dsh/skills/board-ui-nav/reference/recovery.md b/.dsh/skills/board-ui-nav/reference/recovery.md new file mode 100644 index 00000000..ab59cd2c --- /dev/null +++ b/.dsh/skills/board-ui-nav/reference/recovery.md @@ -0,0 +1,41 @@ +# 走错页 / 未知屏恢复与根因(自 SKILL.md 两节逐字外置) + +> 何时读:导航失败(退出码 1)、`--where` 与像素不一致、或要追"为什么不能自己搓注键脚本"时。 +> 本技能的执行体 `scripts/board_ui_nav.py` 在仓库根 `scripts/`,无法由脚本打印技能内 reference 指针, +> 因此主文件用**显式**「报错码 / 退出码 → 查哪一节」表指向这里;两个小节的键就是下面的 `##` 标题。 + +## classification-failure + +> 对应主文件索引键:`classification-failure`(退出码 1 = 分类或导航失败;像素与 STATUS 不一致;落错页)。 +> 原文标题「## 为什么不能自己搓(#69 复盘四类根因,全部有实证)」,逐字外置、未改写。 + +1. **协议旧版零身份反馈**:KEY 的 ACK 是空帧,"发了 5 个键"≠"到了第 5 层"。(已修: + 7003 新增 STATUS 命令,固件直读 `s_depth/s_path/s_sel` + 当前内容页 id,见下) +2. **N−1 屏坑**:KEY ACK 与 LCDMEM 推流共用同一条 TCP,`sleep(0.30)` 就抓帧拿到的是 + 上一屏(规则①:排空到帧流静默 ≥900 ms;现在 `key()` 代码已真正执行排空+双帧比对)。 +3. **物理陷阱**:待机态按 `e` 是**重开最近页**不是进菜单;级联列光标记忆上次行不归零; + 根列最后两行的子列弹框被 160×160 屏裁掉(selftest/runlog 因此"读不到选带")。 +4. **认屏误判**:菜单子列标签与页标题同字(记录查询子列里的 事故记录/操作记录…), + 像素分类器会把级联菜单判成 PAGE——**有 STATUS 时以 STATUS 为准**,trace 留痕不一致。 + +**判据**:落错页 / 退出码 1 / trace 里"像素与 STATUS 不一致" → 命中本节。 +**处置**:STATUS 在场时一律以固件身份为准,像素只作佐证;不要改判据迁就现状。 +**证据边界**:四类根因来自 #69 / #38 复盘(2026-10-25~11-02),已经修复的项以正文标注为准;本节解释"为什么",不替代下面的恢复动作。 + +## navigation-recovery + +> 对应主文件索引键:`navigation-recovery`(走错页 / 未知屏 / STANDBY 唤醒 / 老固件退避键序)。 +> 原文标题「## 走错页 / 未知屏恢复配方(按序,不跳步)」,逐字外置、未改写。 + +1. `--where` 先看 STATUS:`PAGE` → 按 `s` 关页(导航器 `--to` 自动做); + `STANDBY` → 按 `e` 唤醒(注意规则②:home 上 `e` 可能重开最近页); + `MENU depth>0` → 按 `s` 或 `l` 都收一级(台架复核 2026-11-02:菜单态 `s` 与 `l` 同走 + `menu_back`,父列选中留在原地;旧说法"`s` 不收列"系把待机态 `s` 无效误读成菜单行为)。 +2. STATUS 无应答(老固件)才吃退避键序(默认 `esl`,`--backoff-keys sl` 可去 ENTER); + ENTER 上限 1 次是硬闸(BACKOFF_MAX_E),报停机就 dump 帧人眼看,不许连按。 +3. 反复落错页且 trace 里出现"像素与 STATUS 不一致" → 分类器或固件有账要记, + 把留痕帧 `--dump-fail` 存下交 Lead,**不要**改判据迁就现状。 + +**判据**:停在未知屏 / STANDBY / 级联列收不回 / 老固件无 STATUS → 命中本节。 +**处置**:按 1→2→3 顺序做,不跳步;ENTER 只按一次,报停机就 `--dump-fail` 留证。 +**证据边界**:退避键序默认 `esl` 来自 2026-10-26 task-24 台架实测;菜单态 `s`/`l` 同收一级是 2026-11-02 台架复核结论,与旧说法冲突时以本节为准。 diff --git a/.dsh/skills/cubemx-regen/SKILL.md b/.dsh/skills/cubemx-regen/SKILL.md index ecdf4689..b7cb209a 100644 --- a/.dsh/skills/cubemx-regen/SKILL.md +++ b/.dsh/skills/cubemx-regen/SKILL.md @@ -39,6 +39,14 @@ whenToUse: 要用 CubeMX 重新生成工程(改 .ioc / 外设配置)、改 & '.venv\Scripts\python.exe' scripts/check_cubemx_survival.py --write ``` +**成功输出样例**(本轮实跑 `scripts/check_cubemx_survival.py --check`,`PYTHONIOENCODING=utf-8`):看到 `通过 30 / 警告 1 / 失败 0` + `通过:重生成易失清单全部就位。` 就是通了(警告是已知提示项,不算 FAIL),不用再往下看。 + +```text + 通过 30 / 警告 1 / 失败 0 + +通过:重生成易失清单全部就位。 +``` + - 退出码 0=通过 / 1=有 FAIL 项;已挂 pre-commit `cubemx-survival` 钩子 (改 `.ioc`/`Src/`/`Inc/`/`.uvprojx` 触发)。 - **审计清单已清空 = 重生成应当零 diff**;仍有 diff 就是被覆盖了,直接跑脚本定位。 diff --git a/.dsh/skills/draw-diagram/SKILL.md b/.dsh/skills/draw-diagram/SKILL.md index dd8167ed..0fbdfd40 100644 --- a/.dsh/skills/draw-diagram/SKILL.md +++ b/.dsh/skills/draw-diagram/SKILL.md @@ -6,206 +6,57 @@ whenToUse: 需要新增/修改 docs/ 文档的技术配图(协议帧、分层 # 文档配图绘制(SVG / Mermaid) -`docs/` 文档技术配图的统一流程;完整选型依据 / 约定 / 检查清单见 `docs/架构设计/图形绘制流程.md`。**产物统一放 `docs/images/`**(专门配图目录,`.svg` 入库;PNG 预览属本地派生物、不入库,`.gitignore` 已含 `docs/images/*.png` 与 `ci-artifacts/`)。 +`docs/` 文档技术配图的执行侧流程;规范归属见 `docs/架构设计/图形绘制流程.md`(同一事实只在一处详述,改渲染命令两处一起改)。**产物统一放 `docs/images/`**(`.svg` 入库;PNG 属本地派生物、不入库,`.gitignore` 已含 `docs/images/*.png` 与 `ci-artifacts/`)。 -> 本窗实测(2026-10-29,新建 2 张图):**"浏览器打开 SVG 目检"这一步在 Windows 上不可直接执行**——没有现成 SVG 栅格化工具,只能走 headless Chrome/Edge 截图 + 图片回读;且 `generated-fresh` 是**逐字节**门禁,生成器自己的控制台打印也会成为失败源(见 §五)。 - -## 工具选型 - -| 图形类型 | 工具 | -|---|---| -| 协议帧 / 字节布局(字段宽 ∝ 字节数、偏移标尺) | SVG:`tools/arch_diagram/gen_frame_svg.py` | -| 分层架构 / 模块依赖 | SVG:`tools/arch_diagram/gen_arch_svg.py` | -| 就绪屏障 / 生产者-消费者 | SVG:`tools/arch_diagram/gen_barrier_svg.py` | -| 台阶 / 泳道对照 / 刻度尺等"高度差、并列对照"类 | SVG:**新写一个** `tools/arch_diagram/gen_<主题>_svg.py`(照抄最近生成器的骨架,见 §二) | -| 其他精确布局图 | **复制**最接近的生成器改顶部数据(`build()` 与数据解耦,通用) | -| 流程 / 时序 / 状态机 / ER(只表达拓扑关系) | Markdown 内嵌 ```mermaid 代码块(`flowchart` / `sequenceDiagram` / `stateDiagram-v2` / `erDiagram`),无需生成图片 | - -> Mermaid 盒子按文本自适应宽、自动加有向边,**只适合"关系"类图**;凡需精确像素 / 比例 / 高度差的布局图一律走 SVG 生成器(实测教训:五级"台阶"用 Mermaid 会被压成同一高度,"还差一级"就看不出来了)。 - -## 一、改既有图(最短路线) - -1. 改**顶部数据 / 常量区**(字段、节点、标题、配色),不改 `build()` 结构。配色沿用既有调色板(主色 / 底色): - - | 语义 | 主色 | 底色 | - |---|---|---| - | 蓝 | `#2563eb` | `#eff6ff` | - | 青 | `#0d9488` | `#f0fdfa` | - | 绿 | `#16a34a` | `#f0fdf4` | - | 琥珀 | `#d97706` | `#fffbeb` | - | 紫 | `#7c3aed` | `#f5f3ff` | - | 灰 | `#475569` | `#f1f5f9` | - | 玫红 | `#e11d48` | `#fff1f2` | +## 默认路径:一条命令跑通(改既有图最短路线) +1. 改**顶部数据/常量区**(字段、节点、标题、配色),不改 `build()` 结构;配色沿用调色板(蓝 `#2563eb`/`#eff6ff`、青 `#0d9488`/`#f0fdfa`、绿 `#16a34a`/`#f0fdf4`、琥珀 `#d97706`/`#fffbeb`、紫 `#7c3aed`/`#f5f3ff`、灰 `#475569`/`#f1f5f9`、玫红 `#e11d48`/`#fff1f2`)。 2. 重跑(仓库根;脚本内置 `ET.fromstring` 自检,XML 不合法直接抛错): - ```powershell - & '.venv\Scripts\python.exe' tools/arch_diagram/gen_xxx.py - # 期望:OK <字节> bytes, canvas x -> <路径>,且没有 OVERFLOW WARN / overflow warnings 行 - ``` - -3. 目检(§三)→ 引用(§四)→ 幂等与门禁(§五)→ 提交(§六)。 - -## 二、从零新写生成器(先抄骨架,别裸写) - -1. **先读同目录 1~2 个最近的脚本**(如 `tools/arch_diagram/gen_adc_frontend_svg.py`、`gen_adc_code_scale_svg.py`),抄它们的三条约定: - - **文件头 docstring** 写清四件事:产物路径 + 这张图回答什么问题 + **「为什么不用 Mermaid」** + 用法("仓库根目录,任意 python3")与"改内容 vs 调坐标"的边界; - - **顶部集中常量块**:画布与几何(`W` / `H` / `PAD` / `RIGHT`)→ `FONT` → 各级字号 → 调色板 → 文案(`TITLE` / `SUB*` / 逐条目 / `FOOTNOTE`);坐标一律由常量推导,别在 `build()` 里塞魔法数; - - **纯标准库**:`import html / os / sys / xml.etree.ElementTree as ET`,helpers 只有 `esc` / `text_w` / `txt` / `line` / `rect` / `wrap` / `check_fit` / `emit` / `build`。 -2. **照抄预检三件套**(`gen_adc_frontend_svg.py` 里还没有;从 `tools/arch_diagram/gen_data_trust_ladder_svg.py` 抄):`OVERFLOW = []` + `check_fit(s, fs, avail, where)` + `wrap(s, fs, avail, max_lines, where)`,标题 / 副标题 / 盒内标题走 `check_fit`,盒内正文与脚注走 `wrap`(`wrap` 按估宽折行、超行数用 `…` 收尾并记一条 OVERFLOW)。`build()` 末尾:`emit("OK ...")` 之后 `if OVERFLOW: emit("!! %d overflow warnings" % len(OVERFLOW))`。估宽口径不变:CJK / 全角 / 圈码 / 箭头 ≈ `1.0em`,其余 ≈ `0.58em`(宁大勿小)。 -3. **照抄 `emit()`**(幂等门禁的地基,见 §五): - - ```python - def emit(s): - """控制台打印按目标编码替换,绝不因 GBK 终端遇上 ²/− 之类字符而崩 - (generated-fresh 钩子会把本脚本拷进临时目录重跑,崩了就是一片假红)。""" - enc = getattr(sys.stdout, "encoding", None) or "ascii" - sys.stdout.write(s.encode(enc, "replace").decode(enc, "replace") + "\n") - ``` - -4. 路径锚在脚本自身位置,别用 cwd(临时目录重跑才不会漂): - - ```python - ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) - OUT = os.path.join(ROOT, "docs", "images", "<主题>.svg") - ``` - -5. 跑 `& '.venv\Scripts\python.exe' tools/arch_diagram/gen_<主题>_svg.py`,**把 OVERFLOW 告警打到 0 再进目检**——预检能在渲染前就报出 `foot: 974 > 968` 这类溢出(本窗实测两张图首跑各报一条脚注超宽),比靠眼睛反复量便宜一个数量级。 -6. 新脚本落库时**同批**把行加进 `tools/arch_diagram/README.md` 的「**产物清单**」——那张表按图逐行,列 = - 图 / 生成器 / 这张图答什么 / 顶部数据区 / 挂在(`文档:行号`)。**全仓只此一张逐脚本清单**: - `docs/架构设计/图形绘制流程.md` 曾另立一张三列表,结果两张各漏各的(2026-10-30 实测 README 漏 5 个、 - 那张漏 9 个),现已换成指针。所以新图只加一行,别在第二篇文档再起一张表。 - -## 三b、大图(几十框几十边)加一道碰撞审计,别只靠眼睛 - -边数一多,像素回读就查不全(本窗实测:42 框 37 边的端到端链路图,缩略 PNG 看着干净, -审计器一眼报出 23 条:边标签压节点、走线穿框、标签出画布)。做法是**解析自己生成的 SVG** -而不是解析渲染结果——`ET.parse` 产物,按 `font-size`/`fill` 分诊文字,估宽口径直接复用生成器的 -`text_w()`(两边同一把尺子才不会假绿),然后判三件事: - -1. **边标签的「文字盒」vs 节点框**(不是白片盒):交集 > 6 px² 就算问题——节点在边之后画, - 压上去的**文字**会被节点白底吃掉半个字(本窗症状:「串行执行」渲染成「行执行」)。 - 白片本身压到框边角是**无害**的(白片先画、节点后画,只是盖住一点白底,不改字)。 - 除「有没有压上」,还要打印**文字与最近框的最小水平余量**并按 < 3px 报问题: - 本窗「TRGO 触发」余量 0.7px、「帧 B 下发」1.5px,都没压上却随时会被真实字宽吃笔画, - 缩短标签后升到 3.5px 以上才算安全。 -2. **走线段 vs 节点框**(内缩 2px 再判,排除贴边端点):线穿框是硬伤,改边的出入框方位或独占通道。 -3. **标签互压 / 出画布**:白片两两求交;`box[3] > H-2` 查脚注贴底。 -4. **零余量复扫(生成器侧,别只跑 SVG 侧那一遍)**:SVG 反推不出哪两个框是本边端点, - 走线只能内缩着查 → 1~3px 的切边照不到。用生成器自己的 `Box` / `route()` / `label_at()` - 真值再扫一遍:框不膨胀不内缩、只跳本边两端。跑 SVG 侧与真值侧两遍都归零才算收工。 - -脚本骨架与判据见 `reference/svg-collision-audit.py`(可直接拷进 `ci-artifacts/` 当一次性工具用, -**别放 `tools/arch_diagram/`**——那里只放生成器,非 `gen_*.py` 的脚本混进去会让人以为在册)。 - -配套的两条几何纪律(都是本窗踩出来的): - -- **同轴直连不要插退化折点**:同行两框若按「同轴 → 加一段 gx 走廊」的通用规则生成,会产出 - `[(195,176),(219,176),(219,176),(243,176)]` 这种点集——线还是直的,但**标签落点算成第一半的中点**, - 整格偏移半个通道 → 压框。正解:出框轴与入框轴同轴且已对齐时直接返回两点线。 -- **标签落点用弧长中点,不用「最长段中点」**:多段折线里最长段可能有多条(对称 Z 字), - 取第一条会把标签推到拐角上;沿总弧长取 50% 再定位,配合 `seg`/`t` 旋钮微调。 - -**先验审计器本身,再信它的「0 条」**:本窗把 `hi > y0` 复制粘贴成 `hi > x0`,零余量那一遍 -凭空报出 3 条「穿框」,差点为此重排三条边的走线。判据脚本的假阳性比漏报更贵——它会让你 -去改一张本来没问题的图。规矩:写完后挑一条**已知干净**的边(例如两框正对的直连边)单独跑一遍, -确认它不报,再跑全量。 - -## 三、目检(Windows:本机没有任何现成 SVG 渲染器) - -**先探测,别照抄 cairosvg 命令**:本仓 `.venv` 无 `cairosvg`(`ModuleNotFoundError: No module named 'cairosvg'`),`rsvg-convert` 不存在,只有 Edge / Chrome: - -```bash -# ops_bash(git-bash)里探测;哪个存在用哪个 -ls -1 "/c/Program Files/Google/Chrome/Application/chrome.exe" \ - "/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe" 2>/dev/null -command -v rsvg-convert inkscape magick convert 2>/dev/null || echo "no CLI rasterizer" -``` - ```powershell -Test-Path "C:\Program Files\Google\Chrome\Application\chrome.exe" -Test-Path "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" +& '.venv\Scripts\python.exe' tools/arch_diagram/gen_xxx.py ``` -截图(**`--screenshot=` 必须给绝对 Windows 路径 + 绝对 `file:///` 输入**,并且**固定用 -`--headless=new`**:本窗用旧 `--headless` 同一套命令时成时不成——一次写出了 168 KB, -下一次静默不写文件;也别把 stderr 丢进 `/dev/null`,成功标志就是它自己打印的那行字数): +3. 目检 → 引用 → 幂等门禁 → 提交(各步键见下表,命中才展开 reference)。 -```bash -mkdir -p ci-artifacts # Chrome 没有建目录的参数,先自己建 -OUT="D:\\Code\\DTU Code\\<工作树名>\\ci-artifacts\\<主题>.png" # 绝对路径、反斜杠 -"/c/Program Files/Google/Chrome/Application/chrome.exe" \ - --headless=new --disable-gpu --hide-scrollbars --force-device-scale-factor=1 \ - --window-size=1060,712 \ - --screenshot="$OUT" \ - "file:///D:/Code/DTU Code/<工作树名>/docs/images/<主题>.svg" 2>&1 | tail -2 +**工具选型**(关系类走 Mermaid,精确布局走 SVG 生成器):协议帧/字节布局 → `gen_frame_svg.py`;分层架构/模块依赖 → `gen_arch_svg.py`;就绪屏障/生产者-消费者 → `gen_barrier_svg.py`;台阶/泳道/刻度尺等高度差、并列对照 → **新写** `gen_<主题>_svg.py`;流程/时序/状态机/ER → Markdown 内嵌 ```mermaid(`flowchart`/`sequenceDiagram`/`stateDiagram-v2`/`erDiagram`)。Mermaid 盒子按文本自适应宽、只适合"关系"类;凡需精确像素/比例/高度差一律 SVG 生成器(五级台阶用 Mermaid 会压成同高,"还差一级"看不出来)。 + +## 成功输出(默认路径跑通的样子) + +``` +OK 12345 bytes, canvas 1060x712 -> docs/images/<主题>.svg ``` -成功标志是 Chrome 自己打印的 ` bytes written to file D:\...`。**回读 PNG 才算目检完成**: +即:console 打印 `OK <字节> bytes, canvas x -> <路径>`,且**没有** `OVERFLOW WARN` / `!! N overflow warnings` 行(有 = 文案超宽,回改顶部常量)。 -```ts -const r = await tools.read_image({ file_path: "D:\\Code\\DTU Code\\<工作树名>\\ci-artifacts\\<主题>.png" }); -console.log(r.image.width + "x" + r.image.height, "bytes=" + r.image.bytes); // 应等于 --window-size / 画布 -``` +## 失败了 → 去哪读(索引表) -看什么:文字压框 / 溢出盒外、标签互撞(本窗实测两轮才干净:台阶图首轮"文字压到盒下方 + 标签互撞",第二、三轮才修完)、`wrap` 收尾的省略号 `…`(有 = 文案超长)、虚线与盒边线重叠、配色是否还在调色板里。发现问题**回改生成器常量并重跑预检**,然后**重新截图**(PNG 是派生物,不会自己更新),`--window-size` 跟着 `canvas WxH` 改。 +失败信息自带稳定键;命中才读对应小节(每节 = 判据 / 处置 / 证据边界 + 逐字原文): -## 四、md 引用(相对路径) +| 键(阶段名 / 报错串) | 什么条件下读 | 去处 | +|---|---|---| +| `COLLISION_AUDIT` | 大图(几十框几十边)缩略目检看着干净但要查标签压框/走线穿框 | [collision-audit.md](reference/collision-audit.md) → `## COLLISION_AUDIT`;脚本骨架 `reference/svg-collision-audit.py` | +| `VISUAL_INSPECT` | Windows 上要"目检"SVG;`--screenshot` 报路径错或无 PNG 落盘 | [visual-inspect.md](reference/visual-inspect.md) → `## VISUAL_INSPECT` | +| `GENERATED_FRESH` | `check_generated_fresh.py` 报 DIFF / NEW / 生成器报错 | [generated-fresh.md](reference/generated-fresh.md) → `## GENERATED_FRESH` | +| `TRAPS` | 想装渲染器转 PNG、相对路径截图、只预检不回读、手改 SVG、批量 edit 半成品 | [traps.md](reference/traps.md) → `## TRAPS` | +| `VERIFY_CHECKLIST` | 提交前逐条勾核 | [verify-checklist.md](reference/verify-checklist.md) → `## VERIFY_CHECKLIST` | -`docs/` 根的 md:`![标题](images/xxx.svg)`;`docs/任务规划/`、`docs/UI设计/` 等子目录 md:`![…](../images/xxx.svg)`(本窗实例:`docs/硬件平台/ADC通道映射说明.md` §9.1 写 `![数据可信是五级台阶,现在踩在第 3 级](../images/数据可信台阶.svg)`)。alt 文本写成"这张图的结论是什么",别只重复文件名。 +## 从零新写生成器(先抄骨架,别裸写) -## 五、generated-fresh:逐字节幂等门禁(新图长期不假红的前提) +1. 先读同目录 1~2 个最近脚本(如 `gen_adc_frontend_svg.py`、`gen_adc_code_scale_svg.py`),抄三条约定:文件头 docstring 写清产物路径 + 图回答什么 + **为什么不用 Mermaid** + 用法;顶部集中常量块(画布/几何 → FONT → 字号 → 调色板 → 文案,坐标由常量推导);纯标准库 helpers(`esc`/`text_w`/`txt`/`line`/`rect`/`wrap`/`check_fit`/`emit`/`build`)。 +2. 照抄预检三件套 `OVERFLOW=[]` + `check_fit` + `wrap`(估宽:CJK/全角/圈码/箭头 ≈1.0em,其余 ≈0.58em,宁大勿小),标题/盒内标题走 `check_fit`、盒内正文/脚注走 `wrap`;`build()` 末尾 `emit("OK …")` 后 `if OVERFLOW: emit("!! %d overflow warnings" % len(OVERFLOW))`。 +3. 照抄 `emit()`(GBK 终端不崩的打印地基,见 `GENERATED_FRESH`);路径锚脚本自身位置(临时目录重跑不漂):`ROOT = dirname(dirname(dirname(abspath(__file__))))`,`OUT = os.path.join(ROOT, "docs", "images", "<主题>.svg")`。 +4. 跑生成把 OVERFLOW 打到 0 再进目检;新脚本落库时**同批**把行加进 `tools/arch_diagram/README.md`「产物清单」(全仓只此一张逐脚本清单,别在第二篇文档另起表)。 -`generated-fresh` 把 `tools/arch_diagram/gen_*.py`(`docs-svg` 项:`per_script: true`、`pattern: gen_*.py`、`mode: exact`)**逐个拷进系统临时目录重跑**,与工作区产物**逐字节**比对:内容不同 = `DIFF`(生成物比生成器旧)、临时目录多出一个工作区没有的文件 = `NEW`、`rc≠0` = 「生成器报错」。由此推出四条硬约束: +## 禁令(看着合理但致命,留在主文件) -1. **生成器只能写那一个 `.svg`**:绝不在脚本里顺手导出 PNG 预览(预览写 `ci-artifacts/`,不进 `docs/images/`)。 -2. **stdout 不许崩**:GBK 终端遇上 `²` / `−` / CJK 路径会 `UnicodeEncodeError` → 钩子 `rc≠0`,一片假红。所以打印一律走 `emit()`,脚本里不留裸 `print()`(本窗实测:两份新生成器只改了一份,另一份照旧崩)。 -3. **产物内容零不确定**:SVG 里不写时间戳 / 绝对路径 / 主机名;浮点坐标一律 `%g` / `%.1f` 定形;字典与 `os.listdir` 结果参与布局时先 `sorted()`。 -4. **`gen_*.py` 命名即自动在册**(pattern 就是 `gen_*.py`)——故意不叫这个名字等于躲开门禁,门禁最大盲区正是"未登记的生成器",别利用它。 +- **手改 SVG 成品 = 制造"不是我改的"diff**,`generated-fresh` 立刻 DIFF;一切修改落在生成器常量上再重跑,也别退化成 ASCII 框图。 +- **`docs/images/` 下不许手写 `.svg`、不许放 PNG 预览**(前者没生成器躲过门禁,后者污染"临时目录多文件"判定)。 +- **别跑不带 `--files`/`--all-files` 的裸 `pre_commit run`**(会 stash 别人在飞的改动)。 +- **没真渲染出 PNG 不要声称"已目检"**;`wrap` 收尾带 `…` = 文案超长,不是完成。 +- 生成器**只能写那一个 `.svg`**(别顺手导出 PNG 到 docs/);`gen_*.py` 命名即自动在册,**故意不叫这名字 = 躲门禁,别利用**。 +- 批量 `edit` 生成器前先 `read` 精确原文逐条改、末尾统一复验——中途抛错时**前面的编辑已落盘**,会留半成品。 -自查(仓库根): +## 提交 -```bash -.venv/Scripts/python.exe tools/arch_diagram/gen_<主题>_svg.py -sha1sum docs/images/<主题>.svg -.venv/Scripts/python.exe tools/arch_diagram/gen_<主题>_svg.py # 重跑后 sha1 必须不变 -.venv/Scripts/python.exe scripts/check_generated_fresh.py # 期望 rc=0,无 DIFF/NEW,[BASELINE] 不增 -``` - -```powershell -& '.venv\Scripts\python.exe' scripts/check_generated_fresh.py # 单独跑(不 stash 别人在飞的改动) -& '.venv\Scripts\python.exe' scripts/check_generated_fresh.py --list # 只看在册声明 -& '.venv\Scripts\python.exe' -m pre_commit run generated-fresh --files tools/arch_diagram/gen_<主题>_svg.py docs/images/<主题>.svg -``` - -⚠ **别跑不带 `--files` 也不带 `--all-files` 的裸 `pre_commit run`**(会 stash 掉别人在飞的改动);判读口径 → `docs/门禁说明/generated-fresh.md` §4。 - -## 六、提交 - -生成器脚本(源)+ `docs/images/<主题>.svg`(产物)+ 引用它的 `.md` + `tools/arch_diagram/README.md`「产物清单」那一行**同一笔**提交;PNG 预览不入库。 - -```powershell -& '.venv\Scripts\python.exe' -m pre_commit run --files <脚本> -``` - -## 陷阱(本窗实测) - -- **想装渲染器再转 PNG**:`cairosvg` 不在 `.venv`(`ModuleNotFoundError`)、`requirements.txt` 里也没有,`rsvg-convert` / `inkscape` / `magick` 这台机器上都不存在 → 用 §三 的 headless Chrome/Edge(权威命令在 `docs/架构设计/图形绘制流程.md` §四,2026-10-30 已同步成这套,别再往回写)。**没真渲染出 PNG 的情况下不要声称"已目检"。** -- **`--screenshot=ci-artifacts/ladder.png`(相对路径)** → `EXIT 2` + `Failed to write file ci-artifacts/ladder.png: 系统找不到指定的路径。 (0x3)`,PNG 压根没落盘;换绝对 Windows 路径后写出 95549 bytes。这条报错**不区分**"相对路径"与"目录不存在"两种成因(实测 `mkdir -p ci-artifacts` 已先跑过、仍报同一句),排查时两条都排。 -- **只做预检 + 缩略目检就收工(大图)**:`check_fit` 归零、PNG 看着干净,仍可能有二十来条标签压框——节点白底后画会吃掉压上去的标签;大图必须走 §三b 的解析式审计。 -- **只做预检就收工**:`check_fit` / `OVERFLOW` 归零也不代表干净——本窗实测"门标签压第 5 级盒、蓝底标签挤、多余虚线"三类碰撞只有 PNG 回读看得见;反过来只目检不预检,脚注溢出就得靠眼睛反复量。**两者都要 0**。 -- **手改 SVG 成品**:等于制造「不是我改的」diff,且 `generated-fresh` 立刻 DIFF;也**不要退化成 ASCII 框图**(图形一律走生成器 / Mermaid,本条是判据)。一切修改都落在生成器常量上再重跑。 -- **批量改生成器时 `old_string` 不匹配**:一批 `edit` 会在中途抛错,但**前面的编辑已经落盘** → 半成品生成器(本窗实测:`emit` helper 缺失却仍打印 OK,几轮之后才查出)。正解:改前先 `read` 出精确原文,逐条改,末尾统一复验(`grep -n "def emit"`、`grep -c print`、再重跑看 rc 与 OK 行)。 -- **PNG 尺寸 ≠ 画布**:`--window-size` 忘了跟着 `W`/`H` 改 → 截出来带大片空白或裁掉底部脚注;回读 `r.image.width/height` 与 `canvas WxH` 对一下再判定。 -- **`docs/images/` 下手写 `.svg` 或放 PNG 预览**:前者没有生成器(NEW / 躲过门禁),后者污染"临时目录多了文件"判定。 - -## 验证清单 - -- [ ] 生成器输出 `OK … bytes, canvas WxH`,**无** `OVERFLOW WARN` / `!! N overflow warnings`;`grep -n "def emit"` 命中、`grep -c print` = 0。 -- [ ] 绝对路径 PNG 存在、尺寸 = 画布,`read_image` 回读确认:无文字压框 / 溢出、无标签互撞、无 `…` 截断收尾、配色在调色板内。 -- [ ] 连跑两次产物 sha1 不变;`scripts/check_generated_fresh.py` rc=0(无 DIFF / NEW,`[BASELINE]` 未增加)。 -- [ ] 大图(≥20 边):跑一遍 §三b 的碰撞审计,报数归零(标签压框 / 走线穿框 / 标签出画布)。 -- [ ] 引用它的 `.md` 相对路径正确(根目录 `images/`,子目录 `../images/`);`tools/arch_diagram/README.md`「产物清单」已加行,「挂在」列的 `文档:行号` 用 `grep -rn "<图名>.svg" docs/ --include=*.md` 现扫核对(**别抄旧行号**,行号一漂整列就废)。 -- [ ] 脚本 + 产物 `.svg` + `.md` + README 行一并暂存;`pre-commit run --files …` 全过(无乱码 / 行尾空白 / 编码 OK)。 - -> **与规范文档的分工(2026-10-30 已对齐)**:`docs/架构设计/图形绘制流程.md` 是规范归属(`docs/文档规范.md` §7 的「同一事实只在一处详述」),本 skill 是执行侧。该文档 §3.1 第 4 步与 §四 原先写的「浏览器打开 SVG / 给 `.venv` 装 cairosvg 转 PNG」在本机走不通,已同步成 headless Edge/Chrome 那套(命令只在 §四 详述,本 skill §三 留判据指针);**改渲染命令时两处一起改**——做图判据以本 skill 为准,规范条文以该文档为归属。 +生成器脚本(源)+ `docs/images/<主题>.svg`(产物)+ 引用它的 `.md` + `tools/arch_diagram/README.md`「产物清单」那一行**同一笔**提交;PNG 预览不入库。提交前 `& '.venv\Scripts\python.exe' -m pre_commit run --files <脚本> `,逐条勾核见 `VERIFY_CHECKLIST`。 diff --git a/.dsh/skills/draw-diagram/reference/collision-audit.md b/.dsh/skills/draw-diagram/reference/collision-audit.md new file mode 100644 index 00000000..a369a5fc --- /dev/null +++ b/.dsh/skills/draw-diagram/reference/collision-audit.md @@ -0,0 +1,54 @@ +# 大图碰撞审计(自 SKILL.md 逐字外置,2026-11-18) + +## COLLISION_AUDIT + +> 路由:主文件失败索引表 `COLLISION_AUDIT` → 本节。原节 `## 三b、大图碰撞审计`(L79–112)逐字搬移。 + +### 判据 + +大图(几十框几十边)仅靠 PNG 缩略目检查不全,需解析式审计。 + +### 处置 + +解析自己生成的 SVG,按边标签压节点/走线穿框/标签出画布三类判;SVG 侧与生成器真值侧两遍都归零;先验审计器本身(拿已知干净的边试),再信它的 0 条。 + +### 证据边界 + +42 框 37 边链路图报 23 条为本窗实测;判据脚本假阳性比漏报更贵。脚本骨架在 reference/svg-collision-audit.py。 + +### 逐字原文(未改写) + +## 三b、大图(几十框几十边)加一道碰撞审计,别只靠眼睛 + +边数一多,像素回读就查不全(本窗实测:42 框 37 边的端到端链路图,缩略 PNG 看着干净, +审计器一眼报出 23 条:边标签压节点、走线穿框、标签出画布)。做法是**解析自己生成的 SVG** +而不是解析渲染结果——`ET.parse` 产物,按 `font-size`/`fill` 分诊文字,估宽口径直接复用生成器的 +`text_w()`(两边同一把尺子才不会假绿),然后判三件事: + +1. **边标签的「文字盒」vs 节点框**(不是白片盒):交集 > 6 px² 就算问题——节点在边之后画, + 压上去的**文字**会被节点白底吃掉半个字(本窗症状:「串行执行」渲染成「行执行」)。 + 白片本身压到框边角是**无害**的(白片先画、节点后画,只是盖住一点白底,不改字)。 + 除「有没有压上」,还要打印**文字与最近框的最小水平余量**并按 < 3px 报问题: + 本窗「TRGO 触发」余量 0.7px、「帧 B 下发」1.5px,都没压上却随时会被真实字宽吃笔画, + 缩短标签后升到 3.5px 以上才算安全。 +2. **走线段 vs 节点框**(内缩 2px 再判,排除贴边端点):线穿框是硬伤,改边的出入框方位或独占通道。 +3. **标签互压 / 出画布**:白片两两求交;`box[3] > H-2` 查脚注贴底。 +4. **零余量复扫(生成器侧,别只跑 SVG 侧那一遍)**:SVG 反推不出哪两个框是本边端点, + 走线只能内缩着查 → 1~3px 的切边照不到。用生成器自己的 `Box` / `route()` / `label_at()` + 真值再扫一遍:框不膨胀不内缩、只跳本边两端。跑 SVG 侧与真值侧两遍都归零才算收工。 + +脚本骨架与判据见 `reference/svg-collision-audit.py`(可直接拷进 `ci-artifacts/` 当一次性工具用, +**别放 `tools/arch_diagram/`**——那里只放生成器,非 `gen_*.py` 的脚本混进去会让人以为在册)。 + +配套的两条几何纪律(都是本窗踩出来的): + +- **同轴直连不要插退化折点**:同行两框若按「同轴 → 加一段 gx 走廊」的通用规则生成,会产出 + `[(195,176),(219,176),(219,176),(243,176)]` 这种点集——线还是直的,但**标签落点算成第一半的中点**, + 整格偏移半个通道 → 压框。正解:出框轴与入框轴同轴且已对齐时直接返回两点线。 +- **标签落点用弧长中点,不用「最长段中点」**:多段折线里最长段可能有多条(对称 Z 字), + 取第一条会把标签推到拐角上;沿总弧长取 50% 再定位,配合 `seg`/`t` 旋钮微调。 + +**先验审计器本身,再信它的「0 条」**:本窗把 `hi > y0` 复制粘贴成 `hi > x0`,零余量那一遍 +凭空报出 3 条「穿框」,差点为此重排三条边的走线。判据脚本的假阳性比漏报更贵——它会让你 +去改一张本来没问题的图。规矩:写完后挑一条**已知干净**的边(例如两框正对的直连边)单独跑一遍, +确认它不报,再跑全量。 diff --git a/.dsh/skills/draw-diagram/reference/generated-fresh.md b/.dsh/skills/draw-diagram/reference/generated-fresh.md new file mode 100644 index 00000000..ad312af2 --- /dev/null +++ b/.dsh/skills/draw-diagram/reference/generated-fresh.md @@ -0,0 +1,45 @@ +# generated-fresh 逐字节幂等门禁(自 SKILL.md 逐字外置,2026-11-18) + +## GENERATED_FRESH + +> 路由:主文件失败索引表 `GENERATED_FRESH` → 本节。原节 `## 五、generated-fresh`(L157–181)逐字搬移。 + +### 判据 + +`check_generated_fresh.py` 报 DIFF / NEW / 生成器报错 = 产物与生成器不同步。 + +### 处置 + +生成器只写一个 .svg;打印一律走 emit()(防 GBK 崩);产物零不确定(时间戳/绝对路径/主机名不写,浮点定形,字典排序);连跑两次 sha1 不变。 + +### 证据边界 + +gen_*.py 命名即自动在册(门禁最大盲区是未登记生成器);裸 pre_commit run 会 stash 别人改动,判读见 docs/门禁说明/generated-fresh.md §4。 + +### 逐字原文(未改写) + +## 五、generated-fresh:逐字节幂等门禁(新图长期不假红的前提) + +`generated-fresh` 把 `tools/arch_diagram/gen_*.py`(`docs-svg` 项:`per_script: true`、`pattern: gen_*.py`、`mode: exact`)**逐个拷进系统临时目录重跑**,与工作区产物**逐字节**比对:内容不同 = `DIFF`(生成物比生成器旧)、临时目录多出一个工作区没有的文件 = `NEW`、`rc≠0` = 「生成器报错」。由此推出四条硬约束: + +1. **生成器只能写那一个 `.svg`**:绝不在脚本里顺手导出 PNG 预览(预览写 `ci-artifacts/`,不进 `docs/images/`)。 +2. **stdout 不许崩**:GBK 终端遇上 `²` / `−` / CJK 路径会 `UnicodeEncodeError` → 钩子 `rc≠0`,一片假红。所以打印一律走 `emit()`,脚本里不留裸 `print()`(本窗实测:两份新生成器只改了一份,另一份照旧崩)。 +3. **产物内容零不确定**:SVG 里不写时间戳 / 绝对路径 / 主机名;浮点坐标一律 `%g` / `%.1f` 定形;字典与 `os.listdir` 结果参与布局时先 `sorted()`。 +4. **`gen_*.py` 命名即自动在册**(pattern 就是 `gen_*.py`)——故意不叫这个名字等于躲开门禁,门禁最大盲区正是"未登记的生成器",别利用它。 + +自查(仓库根): + +```bash +.venv/Scripts/python.exe tools/arch_diagram/gen_<主题>_svg.py +sha1sum docs/images/<主题>.svg +.venv/Scripts/python.exe tools/arch_diagram/gen_<主题>_svg.py # 重跑后 sha1 必须不变 +.venv/Scripts/python.exe scripts/check_generated_fresh.py # 期望 rc=0,无 DIFF/NEW,[BASELINE] 不增 +``` + +```powershell +& '.venv\Scripts\python.exe' scripts/check_generated_fresh.py # 单独跑(不 stash 别人在飞的改动) +& '.venv\Scripts\python.exe' scripts/check_generated_fresh.py --list # 只看在册声明 +& '.venv\Scripts\python.exe' -m pre_commit run generated-fresh --files tools/arch_diagram/gen_<主题>_svg.py docs/images/<主题>.svg +``` + +⚠ **别跑不带 `--files` 也不带 `--all-files` 的裸 `pre_commit run`**(会 stash 掉别人在飞的改动);判读口径 → `docs/门禁说明/generated-fresh.md` §4。 diff --git a/.dsh/skills/draw-diagram/reference/traps.md b/.dsh/skills/draw-diagram/reference/traps.md new file mode 100644 index 00000000..2c5c41d7 --- /dev/null +++ b/.dsh/skills/draw-diagram/reference/traps.md @@ -0,0 +1,30 @@ +# 陷阱(本窗实测,自 SKILL.md 逐字外置,2026-11-18) + +## TRAPS + +> 路由:主文件失败索引表 `TRAPS` → 本节。原节 `## 陷阱(本窗实测)`(L191–200)逐字搬移。 + +### 判据 + +命中具体症状(装渲染器/相对路径截图/只预检不回读/手改 SVG/批量 edit 半成品/PNG 尺寸错)时读本节。 + +### 处置 + +逐条按原文处置。 + +### 证据边界 + +全部为本窗实测(2026-10-29/30),换机器须重验。 + +### 逐字原文(未改写) + +## 陷阱(本窗实测) + +- **想装渲染器再转 PNG**:`cairosvg` 不在 `.venv`(`ModuleNotFoundError`)、`requirements.txt` 里也没有,`rsvg-convert` / `inkscape` / `magick` 这台机器上都不存在 → 用 §三 的 headless Chrome/Edge(权威命令在 `docs/架构设计/图形绘制流程.md` §四,2026-10-30 已同步成这套,别再往回写)。**没真渲染出 PNG 的情况下不要声称"已目检"。** +- **`--screenshot=ci-artifacts/ladder.png`(相对路径)** → `EXIT 2` + `Failed to write file ci-artifacts/ladder.png: 系统找不到指定的路径。 (0x3)`,PNG 压根没落盘;换绝对 Windows 路径后写出 95549 bytes。这条报错**不区分**"相对路径"与"目录不存在"两种成因(实测 `mkdir -p ci-artifacts` 已先跑过、仍报同一句),排查时两条都排。 +- **只做预检 + 缩略目检就收工(大图)**:`check_fit` 归零、PNG 看着干净,仍可能有二十来条标签压框——节点白底后画会吃掉压上去的标签;大图必须走 §三b 的解析式审计。 +- **只做预检就收工**:`check_fit` / `OVERFLOW` 归零也不代表干净——本窗实测"门标签压第 5 级盒、蓝底标签挤、多余虚线"三类碰撞只有 PNG 回读看得见;反过来只目检不预检,脚注溢出就得靠眼睛反复量。**两者都要 0**。 +- **手改 SVG 成品**:等于制造「不是我改的」diff,且 `generated-fresh` 立刻 DIFF;也**不要退化成 ASCII 框图**(图形一律走生成器 / Mermaid,本条是判据)。一切修改都落在生成器常量上再重跑。 +- **批量改生成器时 `old_string` 不匹配**:一批 `edit` 会在中途抛错,但**前面的编辑已经落盘** → 半成品生成器(本窗实测:`emit` helper 缺失却仍打印 OK,几轮之后才查出)。正解:改前先 `read` 出精确原文,逐条改,末尾统一复验(`grep -n "def emit"`、`grep -c print`、再重跑看 rc 与 OK 行)。 +- **PNG 尺寸 ≠ 画布**:`--window-size` 忘了跟着 `W`/`H` 改 → 截出来带大片空白或裁掉底部脚注;回读 `r.image.width/height` 与 `canvas WxH` 对一下再判定。 +- **`docs/images/` 下手写 `.svg` 或放 PNG 预览**:前者没有生成器(NEW / 躲过门禁),后者污染"临时目录多了文件"判定。 diff --git a/.dsh/skills/draw-diagram/reference/verify-checklist.md b/.dsh/skills/draw-diagram/reference/verify-checklist.md new file mode 100644 index 00000000..ef09244a --- /dev/null +++ b/.dsh/skills/draw-diagram/reference/verify-checklist.md @@ -0,0 +1,28 @@ +# 验证清单(自 SKILL.md 逐字外置,2026-11-18) + +## VERIFY_CHECKLIST + +> 路由:主文件失败索引表 `VERIFY_CHECKLIST` → 本节。原节 `## 验证清单`(L202–209)逐字搬移。 + +### 判据 + +提交前逐条勾核完方可收工。 + +### 处置 + +按原文清单六条逐项比对。 + +### 证据边界 + +「挂在」列行号须现扫不抄旧(行号一漂整列就废)。 + +### 逐字原文(未改写) + +## 验证清单 + +- [ ] 生成器输出 `OK … bytes, canvas WxH`,**无** `OVERFLOW WARN` / `!! N overflow warnings`;`grep -n "def emit"` 命中、`grep -c print` = 0。 +- [ ] 绝对路径 PNG 存在、尺寸 = 画布,`read_image` 回读确认:无文字压框 / 溢出、无标签互撞、无 `…` 截断收尾、配色在调色板内。 +- [ ] 连跑两次产物 sha1 不变;`scripts/check_generated_fresh.py` rc=0(无 DIFF / NEW,`[BASELINE]` 未增加)。 +- [ ] 大图(≥20 边):跑一遍 §三b 的碰撞审计,报数归零(标签压框 / 走线穿框 / 标签出画布)。 +- [ ] 引用它的 `.md` 相对路径正确(根目录 `images/`,子目录 `../images/`);`tools/arch_diagram/README.md`「产物清单」已加行,「挂在」列的 `文档:行号` 用 `grep -rn "<图名>.svg" docs/ --include=*.md` 现扫核对(**别抄旧行号**,行号一漂整列就废)。 +- [ ] 脚本 + 产物 `.svg` + `.md` + README 行一并暂存;`pre-commit run --files …` 全过(无乱码 / 行尾空白 / 编码 OK)。 diff --git a/.dsh/skills/draw-diagram/reference/visual-inspect.md b/.dsh/skills/draw-diagram/reference/visual-inspect.md new file mode 100644 index 00000000..54a05807 --- /dev/null +++ b/.dsh/skills/draw-diagram/reference/visual-inspect.md @@ -0,0 +1,58 @@ +# 目检(Windows SVG 渲染,自 SKILL.md 逐字外置,2026-11-18) + +## VISUAL_INSPECT + +> 路由:主文件失败索引表 `VISUAL_INSPECT` → 本节。原节 `## 三、目检`(L114–151)逐字搬移。 + +### 判据 + +需回读 PNG 才算目检完成;无 PNG 不得声称已目检。 + +### 处置 + +headless Chrome/Edge `--headless=new` + 绝对 Windows 路径截图 → `read_image` 回读,看文字压框/标签互撞/`…` 截断/配色。 + +### 证据边界 + +本仓 .venv 无 cairosvg、无 rsvg-convert/inkscape;旧 `--headless` 成时不成(2026-10-29 实测),固定用 `--headless=new`。 + +### 逐字原文(未改写) + +## 三、目检(Windows:本机没有任何现成 SVG 渲染器) + +**先探测,别照抄 cairosvg 命令**:本仓 `.venv` 无 `cairosvg`(`ModuleNotFoundError: No module named 'cairosvg'`),`rsvg-convert` 不存在,只有 Edge / Chrome: + +```bash +# ops_bash(git-bash)里探测;哪个存在用哪个 +ls -1 "/c/Program Files/Google/Chrome/Application/chrome.exe" \ + "/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe" 2>/dev/null +command -v rsvg-convert inkscape magick convert 2>/dev/null || echo "no CLI rasterizer" +``` + +```powershell +Test-Path "C:\Program Files\Google\Chrome\Application\chrome.exe" +Test-Path "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" +``` + +截图(**`--screenshot=` 必须给绝对 Windows 路径 + 绝对 `file:///` 输入**,并且**固定用 +`--headless=new`**:本窗用旧 `--headless` 同一套命令时成时不成——一次写出了 168 KB, +下一次静默不写文件;也别把 stderr 丢进 `/dev/null`,成功标志就是它自己打印的那行字数): + +```bash +mkdir -p ci-artifacts # Chrome 没有建目录的参数,先自己建 +OUT="D:\\Code\\DTU Code\\<工作树名>\\ci-artifacts\\<主题>.png" # 绝对路径、反斜杠 +"/c/Program Files/Google/Chrome/Application/chrome.exe" \ + --headless=new --disable-gpu --hide-scrollbars --force-device-scale-factor=1 \ + --window-size=1060,712 \ + --screenshot="$OUT" \ + "file:///D:/Code/DTU Code/<工作树名>/docs/images/<主题>.svg" 2>&1 | tail -2 +``` + +成功标志是 Chrome 自己打印的 ` bytes written to file D:\...`。**回读 PNG 才算目检完成**: + +```ts +const r = await tools.read_image({ file_path: "D:\\Code\\DTU Code\\<工作树名>\\ci-artifacts\\<主题>.png" }); +console.log(r.image.width + "x" + r.image.height, "bytes=" + r.image.bytes); // 应等于 --window-size / 画布 +``` + +看什么:文字压框 / 溢出盒外、标签互撞(本窗实测两轮才干净:台阶图首轮"文字压到盒下方 + 标签互撞",第二、三轮才修完)、`wrap` 收尾的省略号 `…`(有 = 文案超长)、虚线与盒边线重叠、配色是否还在调色板里。发现问题**回改生成器常量并重跑预检**,然后**重新截图**(PNG 是派生物,不会自己更新),`--window-size` 跟着 `canvas WxH` 改。 diff --git a/.dsh/skills/font-regen/SKILL.md b/.dsh/skills/font-regen/SKILL.md index 2d8748c8..9b906c31 100644 --- a/.dsh/skills/font-regen/SKILL.md +++ b/.dsh/skills/font-regen/SKILL.md @@ -24,6 +24,13 @@ python tools/font_gen/extract_cn.py # 扫描 UI 源码字符串 → # 4. diff 检查:新增字在位、旧字不变、生成物 Opts 行字符集与预期一致 ``` +**成功输出样例**(本轮实跑 `scripts/check_font_charset.py`,`PYTHONIOENCODING=utf-8`):看到 `coverage OK: 230 个字符全部进字体` + `结果: PASS` 就是通了,不用再往下看。 + +```text +coverage OK: 230 个字符全部进字体 +结果: PASS(必需字符(源码在用 ∪ 保留清单)全部在字体子集内;10 个保留字在位) +``` + ## 提交清单 `ui_cn_chars.txt`(仓库根)+ `Drivers/BSP/UI/ui_font_cn_12.c` **随代码一起提交**,缺一个都会让另一端/下次构建字体与字集不一致。 diff --git a/.dsh/skills/id-family-semantic-migration/SKILL.md b/.dsh/skills/id-family-semantic-migration/SKILL.md index 48bd51ef..df470977 100644 --- a/.dsh/skills/id-family-semantic-migration/SKILL.md +++ b/.dsh/skills/id-family-semantic-migration/SKILL.md @@ -64,15 +64,9 @@ version: 1.1.0 9. 收尾复跑 + 清中间产物 > 本节全文(逐字搬移、未改写,含命令与实测数字)→ [steps-chinese-prefix-family.md](reference/steps-chinese-prefix-family.md)。动手前先读那篇。 -## 不可判定引用绝对数涨点的净室归因 +## 涨点归因(只在不可判定引用绝对数涨点时读) -「不可判定引用绝对数」比今日低点涨了 N 处时: - -1. **禁止**用「对提交新增行 grep 字母+数字形态」归因:`git diff -U0` 的加行里绝大多数文本是从旧行搬来的**存量上下文**(注释整段重写、表格加一列、Markdown 重新折行),形态匹配数出来的是「哪段文字最近被搬动」,不是「哪里涨了 N 处」——用它归因必然把老引用算成增量。`diff -U0` 只在**已定位到文件之后**用来绑笔次与行号。 -2. **正解 A(首选,同一计数器相减)**:在**仓外 detached worktree 跑 HEAD 版**(`task-worktree` skill 的净室测量仪;不 stash、不碰在飞工作区),两边都用同一个 `check_ids.py` 计数器导出 `(rel, literal)` 多重集(`ck.findings` 或 `err_groups(ck)`),做**逐文件集合差**,落差的 N 处直接指向具体文件与字面量。 -3. **正解 B(逐文件注入)**:一次只把一个文件换成在飞版跑计数器——涨点在哪个文件上,就只在注入它时出现;文件多时按 `git diff --name-only` 折半。 -4. **当轮跑不完就如实说**:本轮未跑净室归因时,只报「现值需要重新实测」并说明**需要跑净室归因**,**不得**给出候选归因对象,**不得**把上一轮的现值或余量当本回合实测值报出(每个数标明来源与时刻)。 -5. 与其它交付口径冲突的差值**登记为待查项**(两套计数可能都对),不当场判谁对谁错。 +- [ ] **attribution** → 涨了 N 处要定位落在哪个文件时,读 [attribution.md](reference/attribution.md) 的 `attribution` 节;禁止拿 diff 新增行 grep 形态归因。 ## Pitfalls @@ -104,16 +98,6 @@ version: 1.1.0 - *.uvprojx 抖动不入库 > 本节全文(逐字搬移、未改写,含命令与实测数字)→ [pitfalls.md](reference/pitfalls.md)。动手前先读那篇。 -## Verification +## 收口验收(只在收口/回报验收清单时读) -1. `scripts/archive/id_gate/check_ids.py --strict` 与 plain **均 rc=0**(`[OK] 校验 1~6 无错误`),悬空引用为 0。 -2. 编号字面量与**不可判定引用绝对数**只降不升、不超 `undecidable_total_ceiling`;可判定比例不低于 `id_registry.json` 基线(86.0%)。 -3. 本族剩余站点复扫归零:有识别面族从 `ck.refs` 按族正则过滤字面量逐条打印;除冻结历史/原始证据行外无残留。 -4. `pre-commit run generated-fresh --all-files` PASS + 目检 svg diff 只有文案与框宽自适应(只在动过生成器时适用);`check_doc_links.py --all` 通过。 -5. `/keil-build`:`BUILD=0`、0 错 0 警、`Program Size` 与改前同数(零行为改动证据,**本回合真跑**);相关主机组(如 `net_socket 457/457`)全绿。 -6. 真实 pre-commit 钩子全绿(如 `passed=33 failed=0`);提交笔内不含他道文件。 -7. 规范与台账已回写并复跑核数:自己先前写进规范的清点数字要么按最终实测改对,要么标明为动手前基线;「等你裁定」残留 = 0;「不做」裁定已在 §4.1.1 + §9.1 + 批次结论段落三处落地(原「变更记录」那一处已随 2026-10-28 清流水退场)。 -8. **无识别面族**:`git grep -nE '卡[ ]*[0-9]' -- .` 无输出(裸跑读 rc);自建扫描器的站点/文件数与提交正文一致;交付里明写「本族不在 check_ids 语料内、门禁判不到」与「刻意不进 `id_aliases.json`」的理由;§4.1.1 停发行 + §9.3 换算表 + 批次结论段落三处齐全,换算表行数 = 该族字面量数(实测 14),且写明旧号永久作废、不得重新取走。 -9. **二次清洗三道各有实测数**:同句重复短语 0 行、各空格形态先计数后归一(复扫 0)、固定正则残留 0;被代码头注释引用的设计约束章节仍在(`git diff` 里没被动过)。 -10. **叙述同步**:`docs/README.md` / `docs/任务规划/README.md` / `docs/任务规划/登记簿.md`(已删除)里旧口径(「三项」「卡 N」类)实测归零;`ci-artifacts/` 里本次 spec 与中间产物已删。 -11. 门禁复跑清单齐:`check_ids.py` plain + `--strict`、`check_doc_links.py --all`、`bom-guard`、`no-mojibake`、`git diff --check`、`/keil-build` 或受影响单测——**每个数字标明是本回合实测**。 +- [ ] **verification** → 逐条打勾的 11 项验收清单(门禁 rc、残留归零、零行为改动、叙述同步等)→ 读 [verification.md](reference/verification.md) 的 `verification` 节。 diff --git a/.dsh/skills/id-family-semantic-migration/reference/attribution.md b/.dsh/skills/id-family-semantic-migration/reference/attribution.md new file mode 100644 index 00000000..0eb97bf7 --- /dev/null +++ b/.dsh/skills/id-family-semantic-migration/reference/attribution.md @@ -0,0 +1,20 @@ +# 不可判定引用绝对数涨点的净室归因(自 SKILL.md 同名节逐字外置) + +> 何时读:仅当「不可判定引用绝对数」比基线低点涨了 N 处、需要定位涨在哪个文件时。正常清退流程不展开本篇。 +> 主文件 frontmatter 提到的「涨点归因一节会用到净室 worktree」指的就是这里。 + +## attribution + +**判据(逐字保留原文,未改写)**: + +「不可判定引用绝对数」比今日低点涨了 N 处时: + +1. **禁止**用「对提交新增行 grep 字母+数字形态」归因:`git diff -U0` 的加行里绝大多数文本是从旧行搬来的**存量上下文**(注释整段重写、表格加一列、Markdown 重新折行),形态匹配数出来的是「哪段文字最近被搬动」,不是「哪里涨了 N 处」——用它归因必然把老引用算成增量。`diff -U0` 只在**已定位到文件之后**用来绑笔次与行号。 +2. **正解 A(首选,同一计数器相减)**:在**仓外 detached worktree 跑 HEAD 版**(`task-worktree` skill 的净室测量仪;不 stash、不碰在飞工作区),两边都用同一个 `check_ids.py` 计数器导出 `(rel, literal)` 多重集(`ck.findings` 或 `err_groups(ck)`),做**逐文件集合差**,落差的 N 处直接指向具体文件与字面量。 +3. **正解 B(逐文件注入)**:一次只把一个文件换成在飞版跑计数器——涨点在哪个文件上,就只在注入它时出现;文件多时按 `git diff --name-only` 折半。 +4. **当轮跑不完就如实说**:本轮未跑净室归因时,只报「现值需要重新实测」并说明**需要跑净室归因**,**不得**给出候选归因对象,**不得**把上一轮的现值或余量当本回合实测值报出(每个数标明来源与时刻)。 +5. 与其它交付口径冲突的差值**登记为待查项**(两套计数可能都对),不当场判谁对谁错。 + +**处置**:按正解 A 首选、正解 B 兜底;跑不完就如实说,不猜归因对象。 + +**证据边界**:本篇只解决「涨点落在哪个文件」,不解决「该文件该不该改」——后者按主文件「动手前先判有没有机器识别面」与 steps 两篇的分类口径处理。 diff --git a/.dsh/skills/id-family-semantic-migration/reference/verification.md b/.dsh/skills/id-family-semantic-migration/reference/verification.md new file mode 100644 index 00000000..1313eb46 --- /dev/null +++ b/.dsh/skills/id-family-semantic-migration/reference/verification.md @@ -0,0 +1,24 @@ +# 收口验收清单(自 SKILL.md「Verification」一节逐字外置) + +> 何时读:收口、回报验收清单、分笔提交前。主文件只留一行索引;动手过程中不要展开本篇。 +> 本篇只讲「怎么算做完了」,逐处替换时的命中数断言仍以 steps 两篇为准。 + +## verification + +**判据(逐条打勾)**:下面 11 条来自原 SKILL.md「Verification」节,逐字保留、未改写。 + +1. `scripts/archive/id_gate/check_ids.py --strict` 与 plain **均 rc=0**(`[OK] 校验 1~6 无错误`),悬空引用为 0。 +2. 编号字面量与**不可判定引用绝对数**只降不升、不超 `undecidable_total_ceiling`;可判定比例不低于 `id_registry.json` 基线(86.0%)。 +3. 本族剩余站点复扫归零:有识别面族从 `ck.refs` 按族正则过滤字面量逐条打印;除冻结历史/原始证据行外无残留。 +4. `pre-commit run generated-fresh --all-files` PASS + 目检 svg diff 只有文案与框宽自适应(只在动过生成器时适用);`check_doc_links.py --all` 通过。 +5. `/keil-build`:`BUILD=0`、0 错 0 警、`Program Size` 与改前同数(零行为改动证据,**本回合真跑**);相关主机组(如 `net_socket 457/457`)全绿。 +6. 真实 pre-commit 钩子全绿(如 `passed=33 failed=0`);提交笔内不含他道文件。 +7. 规范与台账已回写并复跑核数:自己先前写进规范的清点数字要么按最终实测改对,要么标明为动手前基线;「等你裁定」残留 = 0;「不做」裁定已在 §4.1.1 + §9.1 + 批次结论段落三处落地(原「变更记录」那一处已随 2026-10-28 清流水退场)。 +8. **无识别面族**:`git grep -nE '卡[ ]*[0-9]' -- .` 无输出(裸跑读 rc);自建扫描器的站点/文件数与提交正文一致;交付里明写「本族不在 check_ids 语料内、门禁判不到」与「刻意不进 `id_aliases.json`」的理由;§4.1.1 停发行 + §9.3 换算表 + 批次结论段落三处齐全,换算表行数 = 该族字面量数(实测 14),且写明旧号永久作废、不得重新取走。 +9. **二次清洗三道各有实测数**:同句重复短语 0 行、各空格形态先计数后归一(复扫 0)、固定正则残留 0;被代码头注释引用的设计约束章节仍在(`git diff` 里没被动过)。 +10. **叙述同步**:`docs/README.md` / `docs/任务规划/README.md` / `docs/任务规划/登记簿.md`(已删除)里旧口径(「三项」「卡 N」类)实测归零;`ci-artifacts/` 里本次 spec 与中间产物已删。 +11. 门禁复跑清单齐:`check_ids.py` plain + `--strict`、`check_doc_links.py --all`、`bom-guard`、`no-mojibake`、`git diff --check`、`/keil-build` 或受影响单测——**每个数字标明是本回合实测**。 + +**处置**:任一条不通过就退回补证,不要带着未打勾项进下一批;回报时逐处列「文件 + 命中数断言」,不要笼统说「已全部更新」。 + +**证据边界**:本清单是**收口判据**,不替代每一步替换时的命中数断言;第 2 条的「不可判定引用绝对数」涨点若本轮未跑净室归因(见主文件「不可判定引用绝对数涨点的净室归因」节),只报「现值需重新实测」,不得给出候选归因对象。 diff --git a/.dsh/skills/keil-build/SKILL.md b/.dsh/skills/keil-build/SKILL.md index aad9acb0..6be00a52 100644 --- a/.dsh/skills/keil-build/SKILL.md +++ b/.dsh/skills/keil-build/SKILL.md @@ -6,191 +6,65 @@ whenToUse: "需要编译 Keil MDK 工程、跑 /keil-build 验证代码改动( # keil-build — Keil 命令行编译(独立可运行 skill) -**执行体 = 本 skill 自带脚本** `.dsh/skills/keil-build/scripts/keil_build.py` -(纯标准库,任意 python3;拷整个 skill 目录到别的 Keil 项目即可用,不依赖仓库脚本)。 +执行体 = 本 skill 自带脚本 `.dsh/skills/keil-build/scripts/keil_build.py`(纯标准库,任意 python3;拷整个 skill 目录到别的 Keil 项目即用,不依赖仓库脚本)。 + +## 默认路径:一条命令跑通 + +仓库根目录,PowerShell 形态(本 skill 的编译入口): ```powershell -# cwd = 项目根目录;PowerShell 形态(本 skill 的编译入口) -& $PY ".dsh\skills\keil-build\scripts\keil_build.py" -# 覆盖:--project X.uvprojx --uv4 UV4.exe --target 名字 --log 路径 --timeout 600 +& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py ``` -⚠ **改本文件 frontmatter 要么整值加双引号,要么一个 ASCII 冒号都别写**(2026-10-30 这份就因此整份加载失败)。 -DSH 用 `yaml` 包的 `parse()` 读 frontmatter(`@deepseek-ai/dsh-skill-filesystem` 的 `parseFrontmatter()`), -plain scalar 里出现 **ASCII「冒号 + 空格」**(例如把报错原文 `BUILD_ENV_ERROR: UV4.exe not found` 或 -`pw: 前缀` 直接写进 description)就报 `Nested mappings are not allowed in compact mappings at line 2, -column 14` → **技能整份不加载**(`skill()` 读不到、也不进技能目录)。**`js-yaml` 能吃下去** —— -拿它自检会假绿,必须用 DSH 自带的那个解析器验。另 — 值首字符不能是 `%`(directive indicator)或 `&` -(anchor),双引号里的 `%SystemDrive%` 之类不受影响。落盘后**让 DSH 真加载一次**再收口。 +bash / `ops_bash` 形态(去掉前导 `&`、路径改正斜杠,退出码归 python): -## 调用形态:先认执行器是哪个 shell(2026-10-26 实测) +```bash +'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py; echo BUILD_RC=$? +``` -- 同一条编译命令,PowerShell 与 bash 是两种写法:bash 侧要去掉前导 & 并把路径改正斜杠(照抄本文末「PowerShell 形态」整段进 ops_bash 会语法错秒退 exit 2) -- ⚠ 那个 exit 2 不是脚本的环境错误 2:stderr 含 syntax error near unexpected token = 写法问题,换 bash 形态重跑,别去查 DTU_KEIL_UV4、别当环境错误排障 -- 后台跑(run_in_background: true)要自己收码,且别把脚本接进管道:实测 $? 取到的是 tail 的码(恒 0);要看报错行就单独 grep MDK-ARM/build_log.txt -- 解析顺序:命令行 > 项目档案 .serialtest/config.json > 环境 > 探测;UV4 显式设了但路径无效 = 立即报错,不静默回退 -- 退出码 0=PASS(0错0警) / 1=构建失败 / 2=环境错误 / 3=用法 / 4=build 锁被占用;2026-10-12 修正过 2 与 3 的归属,该篇末尾记了前后口径 -- **bash / `ops_bash` 侧「构建到底过没过」的一次自查**(2026-10-26 实测口径):先 `cd` 到仓库根(或该 worktree 根),跑 `.venv/Scripts/python.exe .dsh/skills/keil-build/scripts/keil_build.py; echo BUILD_RC=$?` —— 正斜杠、**无前导 `&`**,退出码归 python、不归 bash;再单独读日志计数 `grep -a -E "Error\(s\)|error:|Warning\(s\)" MDK-ARM/build_log.txt`。报结论要三样齐 —— **`BUILD_RC=0` + `UV4_RC: 0` + `BUILD_OK: 0 errors, 0 warnings`**(脚本自己判「无 `error:` 行 且 尾行含 `0 Error(s), 0 Warning(s)`」);bash 吐的 `syntax error near unexpected token` **既不是构建通过也不是构建失败**,那是写法问题,别拿它当构建结论报。 -> 本节全文(逐字搬移、未改写,含命令与实测数字)→ [executor-shell-forms.md](reference/executor-shell-forms.md)。动手前先读那篇。 +「技能调用名 `/keil-build`」不是 shell 命令——原样敲进终端是 command not found;可执行形态永远是上面这条命令行。判定口径(与原 `MDK-ARM/build.bat` 同款,该文件 2026-10-10 已删):先删旧日志 → `-b -j0 -o` → 无 `error:` 且含 `0 Error(s), 0 Warning(s)`。解析顺序 = 命令行 > 项目档案 `.serialtest/config.json` > 环境 > 探测;UV4 显式设了但路径无效立即报错,不静默回退。 -## exit 2 实战闭环:`UV4.exe not found` 的探测 → 注入 → 复核(2026-10-30 实测) +退出码:`0`=PASS(0 错 0 警)/ `1`=构建失败 / `2`=环境错误或 bash 写法错(先看 stderr)/ `3`=用法 / `4`=build 锁占用。警告也算失败,PASS 只认退出码 0。 -**先定性,别动源码**:脚本报 -`BUILD_ENV_ERROR: UV4.exe not found (--uv4 / config 'uv4' / $DSH_KEIL_UV4 / $DTU_KEIL_UV4 / PATH)` -且**退出码 2** = **环境错,不是构建失败**——本次 **UV4 根本没启动、`MDK-ARM/build_log.txt` 也没被改写**, -日志里看到的是上一次的。此时去改 `.c`/`.h` 或怀疑代码,就是把环境问题当编译问题排。 -(会话为什么看不见:DSH 会话的 shell 由常驻服务派生,**服务启动之后**设的用户级变量不会自动进来; -`run_code` 起的 Node 进程 `process.env` 干脆是空的(同一机制另见 `new-machine-setup` skill「实测坑」)。 -所以**变量"已设但本会话看不见"是常态**,不是用户没设。) +## 成功输出(三样齐 + 外层退出码 0 才算构建通过) -1. **探测候选安装路径**(逐个 `fs.existsSync` / `test -f`,命中即取绝对路径)—— - `C:/Keil_v5/UV4/UV4.exe`、`C:/Keil/UV4/UV4.exe`、`D:/Keil_v5/UV4/UV4.exe`、`D:/Keil/UV4/UV4.exe`、 - `C:/Program Files/Keil_v5/UV4/UV4.exe`、`D:/Program Files/Keil_v5/UV4/UV4.exe` - (2026-10-30 实测只命中 `C:/Keil_v5/UV4/UV4.exe`,其余五个都不存在)。 - ```bash - for p in 'C:/Keil_v5/UV4/UV4.exe' 'C:/Keil/UV4/UV4.exe' 'D:/Keil_v5/UV4/UV4.exe' \ - 'D:/Keil/UV4/UV4.exe' 'C:/Program Files/Keil_v5/UV4/UV4.exe' 'D:/Program Files/Keil_v5/UV4/UV4.exe'; do - [ -f "$p" ] && echo "HIT $p"; done - ``` -2. **读用户级来源确认"值本来就对"**(同一轮里顺手做掉,别只靠猜路径): - bash / Node 侧 `reg query HKCU\Environment`(整表打出来再找 `DTU_KEIL_UV4` / `DSH_KEIL_UV4`), - PowerShell 侧 `[Environment]::GetEnvironmentVariable('DTU_KEIL_UV4','User')`。 - 有值 → 直接用它;没值/值指向旧目录 → 用第 1 步的命中路径。 - ⚠ **不替用户改全局**:不要 `setx`、不要 `SetEnvironmentVariable(...,'User')`——那是用户自己在真终端里 - 做的事(`docs/环境与部署/本地工具路径环境变量方案.md`);本闭环只解决"这一次构建怎么跑起来", - 报告里也必须这么写。 -3. **只给这一次调用注入**再重跑(两种等价形态,二选一): - ```js - // run_code:options.env 是**整体替换**,所以要连 SystemRoot / Path / USERPROFILE 一起给 - const { execSync } = await import('node:child_process'); - execSync('".venv/Scripts/python.exe" .dsh/skills/keil-build/scripts/keil_build.py', { - cwd: MAIN, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, - env: { SystemRoot: 'C:\\Windows', Path: 'C:\\Windows;C:\\Windows\\System32', - USERPROFILE: 'C:\\Users\\<你>', DTU_KEIL_UV4: 'C:\\Keil_v5\\UV4\\UV4.exe' } }); - ``` - - bash / `ops_bash` 侧的等价写法 = 显式参数 `--uv4 'C:\Keil_v5\UV4\UV4.exe'`(值含空格要整体加引号)。 - - `run_code` 的 `timeoutMs` 给足:注入后这次构建实测 **10 s** 跑完,但首次冷构建更长(我给的 500000)。 - - **别顺手加 `--no-lock`**:注入重跑时锁链照旧(`LOCK: 已获取 build 锁(task=build-cli)` → `已释放锁`)。 -4. **复核口径**(三样齐了才算真跑过,缺一样就是没构建):脚本回显 - `UV4: <绝对路径> (<来源>)`(来源随注入方式变:`$DTU_KEIL_UV4` 或 `--uv4`)→ - `UV4_RC: 0` → `BUILD_OK: 0 errors, 0 warnings`,且**外层退出码 0**(自己包 execSync 就显式把码打出来, - 别接管道,见「调用形态」)。报告里写清"本次注入 + 来源",**不得声称已永久设置系统/用户环境变量**。 +``` +UV4: C:\Keil_v5\UV4\UV4.exe ($DTU_KEIL_UV4) +UV4_RC: 0 +BUILD_OK: 0 errors, 0 warnings +BUILD_RC=0 +``` -- ⚠ 注入的若是**注册表里那个陈旧值**,会撞同族的另一种 2: - `BUILD_ENV_ERROR: $DTU_KEIL_UV4 is set but not a file: … (fix the value; no silent fallback)` - —— 值在但指向旧盘符/旧目录名(本仓踩过 `D:\Code\DTU 程序\…` 搬迁)。脚本**刻意不静默回退**, - 回到第 1 步用探测命中的路径覆盖它,别去猜目录、更别改脚本让它"猜 C 盘"(设计上明确禁止从旧路径猜)。 -- ⚠ 本闭环只回答"UV4 在哪儿",**不回答"调用写法对不对"**:从 bash 侧照抄 PowerShell 的 `&` 也是 exit 2, - 但 stderr 是 `syntax error near unexpected token`(见「调用形态」)。**先看 stderr 再决定排障方向**, - 两种 2 的处置完全不同。 -- **改 `.c` 注释(哪怕只改一行中文注释)也必须跑完这道构建验证**:2026-10-30 的实测就是 - 「改注释 → `/keil-build` → 吃 rc=2 → 探测+注入 → 10 s 通过」。注释类坑(BOM 被剥 → `#870-D`、 - 注释里写 `**` 路径 → 9-D)只在**重编译那个 TU 时**才暴露,"以前 0 警告"不代表安全。 +## 失败了 → 去哪读(索引表) -## build 锁:脚本自持自释(2026-10-12) +失败信息自带稳定键;按该键读对应小节的「判据 / 处置 / 证据边界」: -**UV4 不能两个实例同时 `-b`,但构建锁不该由调用方"记得释放"**——那正是泄漏源: -Agent 手工 `lock acquire build` 后忘了 `release`,锁要挂到 TTL 才被接管。 -故本脚本**自己**管:进入 acquire → `try` 构建 → `finally` **无条件** release -(构建失败、异常、`SystemExit` 都会释放)。 +| 键(脚本真实输出 / 阶段名) | 什么条件下读 | 去处 | +|---|---|---| +| `BUILD_ENV_ERROR` | 退出码 2,UV4.exe not found / is set but not a file;先分型别动源码 | [build-env-error.md](reference/build-env-error.md) → `## BUILD_ENV_ERROR` | +| `BUILD_LOCK_BUSY` | 退出码 4,build 锁被占、持有者名带 `pw:` 插件树 | [build-lock.md](reference/build-lock.md) → `## BUILD_LOCK_BUSY` | +| `SHELL_FORM` | stderr 含 `syntax error near unexpected token`(bash 里误用 PowerShell 形态) | [executor-shell-forms.md](reference/executor-shell-forms.md) → `## SHELL_FORM` | +| `JUNK_DIR` | 构建后仓库根冒出 `%SystemDrive%/`;`WARN: ENV_SPARSE:` / `WARN: JUNK_DIR:` | [systemdrive-junk-dir.md](reference/systemdrive-junk-dir.md) → `## JUNK_DIR` | +| `IRON_RULES` | exit 2 三型分型、编码报错根因、uvprojx churn、字节模式写文件、行尾验收 | [iron-rules.md](reference/iron-rules.md) → `## IRON_RULES` | -| 开关 | 作用 | -|---|---| -| `--lock-task ` | 持有者名。默认 `$DTU_TASK_ID` → 从 cwd 反推:`_wt/-/` → ``(`@task` 那批);`.agents/worktrees//` 或旧 `.dsh-worktrees/worktree//` → `pw:`(DSH worktree **插件**建的树,`plugin_tree_owner()`)→ 都没有才落 `build-cli` | -| `--lock-wait ` | 锁被占时等待 N 秒(默认 0 = 立即失败,退出码 4) | -| `--no-lock` | 完全不加锁(危险:并发 `-b` 互相干扰) | -| `DTU_LOCK_HELD=build` | 环境变量:**调用方已持锁**时设它,本脚本跳过自持自释(`task-worktree done` 的门禁即如此用) | +## 常用参数 -- **TTL 自报**(2026-10-12):acquire 时按 `--timeout` 声明陈旧窗口 - = `timeout/3600 + 15min`,下限 0.5h(默认 600s → **0.5h**)。这样崩溃/强杀留下的锁, - 其自动接管窗口与本次构建上限同量级,而不再是全局 6h —— 编译很快,兜底窗口也该短。 -- 锁工具 = 兄弟 skill `task-worktree/scripts/task_worktree.py`;**找不到则降级为不加锁 - 并告警**(保持本 skill 可独立搬运)。 -- ⚠ 从 `_wt/-/` 反推持有者名,意味着"手工 `lock acquire build --task ` - 后再跑 `/keil-build`"仍**幂等**(同名即视为自己持有),不会自我死锁。 -- **退出码 4 的持有者名带 `pw:`(如 `pw:refactor-logging`)= 插件在 `.agents/worktrees//`(或旧 `.dsh-worktrees/worktree//`)里跑的构建占着 UV4,不是某个 `@task` 任务 ID**: - 插件树**没有台账**,别拿它去 `lock release `(释放不掉别人的锁)、更别去杀 UV4 进程。正解 = - 等那次构建自己 `finally` 释放(自持自释;崩溃则按自报 TTL 兜底),或本次加 `--lock-wait ` 排队; - 想知道是哪棵树的谁:`"$PY" "$TW" plugin list`(缺联接再 `plugin adopt `)→ 细节归 - `task-worktree` skill F 节(插件桥)。 -- **只 build 锁自动;`bench` 锁仍须 Agent 手工持**(它是**会话作用域**,跨 - 烧录→`/serial-boot-test`→探针多条命令,逐命令自动释放会让别的任务插进来扰动设备)。 +- `--project X.uvprojx` / `--uv4 UV4.exe` / `--target 名字` / `--log 路径` / `--timeout 600`(其余见脚本 `--help`) +- `--lock-wait N`:锁被占时等 N 秒;`--no-lock`:完全不加锁(并发 `-b` 会互相干扰) +- `DTU_KEIL_UV4`(用户级,指向 UV4.exe):设了不等于本会话能看见,仍报退出码 2 走 `BUILD_ENV_ERROR` -## 构建副产物:`%SystemDrive%` 字面量垃圾目录(2026-10-26 两次复发 → 2026-10-28 定性并加守卫) +## 禁令(看着合理但致命,留在主文件) -- 症状:/keil-build(或 check_font_charset.py 这类 fontTools 工具)跑完,仓库根冒出未跟踪的 %SystemDrive%/ProgramData/…/Caches/(几个 .db,约 1 MB)= 本机缓存被按字面量原地复刻 -- 根因(2026-10-28 实测):run_code 的 Node 进程 process.env 是空的 → known-folder 可展开串展不开变成相对路径 → 按当前目录建在仓库根;同族还会冒出 %USERPROFILE%/AppData/Local/Temp -- 清理有安全阀:⚠ 绝不用 cmd / PowerShell 直接删(rd /s /q %SystemDrive% 会被展开成 C:);只用 bash 引号形态,先 find '%SystemDrive%' -type l 预检再 rm -rf --。它是工具副产物,直接删、别 stash、更别提交 -- 两层防线均已落地可核验:.gitignore:167 挡入库 + 脚本 harden_windows_env() 回填环境变量、check_percent_literal_junk() 只告警不自动删;守卫是兜底不是许可,/keil-build 仍要走 ops_bash / PowerShell -- **取证在前,处置在后**(2026-10-28 实测,别一上来 `rm -rf`):`ls -laR -- "%SystemDrive%"` + `du -sh "%SystemDrive%"` 枚举内容与体积,再 `find "%SystemDrive%" -printf "%T@ %p\n" | sort -rn | head -3` 看**最新 mtime** —— 最近几分钟还在被重建 = 环境仍残缺(脚本会打 `WARN: ENV_SPARSE:`),先断源头(换 `ops_bash`/PowerShell 跑,或按「UV4.exe not found」一节把 `env` 传全)再删,否则删完立刻长回来;顺带确认仓库里只有这一个该名字的东西(`find . -maxdepth 1 -name "*SystemDrive*"`) -- **要留证据就搬走、别就地删** —— ⚠ **shell 的 `mv` 搬不动它**:`mv "%SystemDrive%/..."` 报 `cannot stat`(含 `%` 的目录名被当变量展开 / 吃掉,路径根本对不上)。改用 Python 遍历搬到**仓库外**的临时目录 —— `os.walk` + `shutil.move`(或 `glob.glob("%SystemDrive%/*")` 逐个 `shutil.move` 到 `os.environ["TEMP"]` 下);确认是纯工具副产物(几个 `.db` 缓存)才 `rm -rf --` -- **入库排除要落成条目并核验**:补 `.gitignore` 前先 `grep -n "SystemDrive" .gitignore` 定位精确原文行再 Edit(凭记忆写 `old_string` 必不匹配,2026-10-28 踩过)。本仓条目 = `.gitignore:167` 的 `%SystemDrive%/`,上面那段注释就是复发证据(新增条目也照此**写明第几次复发、谁造的**)。收尾核验 —— `git status --porcelain` 里该目录零命中(且别的未跟踪产物一个没少)、`git check-ignore -v` 落在那一行、`git add -A --dry-run` 零命中;**绝不提交**(把本机缓存塞进历史) -> 本节全文(逐字搬移、未改写,含命令与实测数字)→ [systemdrive-junk-dir.md](reference/systemdrive-junk-dir.md)。动手前先读那篇。 - -## 本仓库 - -**本 skill 的调用名 = `/keil-build`**(**技能调用名不是 shell 命令**——原样敲进终端是 command not found / syntax error,可执行形态永远是下面这条命令行):在仓库根目录跑 -`& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py`—— -**bash / `ops_bash` 下要写成 `'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py`** -(原因见「调用形态」)。 -判定口径(与原 `MDK-ARM/build.bat` 同款;该文件已于 2026-10-10 删除,本 skill 即编译入口): -先删旧日志 → `-b -j0 -o` → 无 `error:` 且含 `0 Error(s), 0 Warning(s)`。 -本 skill 另有超时保护、UV4 多级解析链(含 PATH 兜底)、失败只打报错行。 -环境变量 `DTU_KEIL_UV4`(用户级,指向 UV4.exe)——注意**它设了不等于本会话能看见**,仍报退出码 2 时走「exit 2 实战闭环」那一节,别先去找用户。 - -## 铁律与陷阱(实测教训) - -- **任何代码改动后必须先编译验证(0 错误 0 警告)再谈烧录/提交**——编译不过就进 - 硬件闭环只会把编译错误伪装成运行问题。**只改 `.c` 里一行中文注释也算改动**(2026-10-30 实测: - 改注释 → `/keil-build` → 环境错 → 探测注入 → 10 s 通过):BOM/嵌套注释这类坑只在重编译那个 TU 时才暴露。 -- **警告也算失败**:判 PASS 只认退出码 0,别只看"有没有 error:"(取退出码的管道陷阱见「调用形态」)。 -- **`MDK-ARM/*.uvprojx` 每次构建后被 UV4 自动改写,改动一律不入库**:UV4 会把工程 - XML 归一化成本机风格(`` → ``、XML 声明加 `standalone="no"`)并把 - `PackID` 降到**本机装的 DFP 版本**(属降级——提交后会把别人的 Pack 版本一起改掉)。 - 判断:`git diff` 里只见 XML 格式/`PackID` 差异而**无源文件挂载增删** → - `git checkout -- ` 丢弃;只有真的增删了源文件(grep 文件名计数变化)才提交。 - 同目录的 `*.uvoptx` / `*.uvguix.*` 是 IDE 个人设置,已在 `.gitignore` 里,不会露出来。 -- **构建后仓库根冒出 `%SystemDrive%/`** = UV4 / 字体工具在残缺环境(缺 `SystemDrive`、`ProgramData`) - 里按**未展开的 known-folder 字面量**建出来的**相对路径**目录,不是任何人在飞的改动: - `rm -rf -- '%SystemDrive%'`(bash 引号形态)删掉即可,**严禁 `rd /s /q %SystemDrive%`——cmd 会把它 - 展开成 `C:`**;`.gitignore` 已兜住 + 脚本已加 `ENV_SPARSE`/`JUNK_DIR` 守卫 → 见「构建副产物」一节。 -- 报错定位读日志别只看终端回显:本仓库 = `MDK-ARM\build_log.txt`。 -- **批量改注释/文档脚本必须用字节模式(2026-11-16 一天内三个会话各踩一次)**:`open(p,'w')` / - `Path.write_text()` 在 Windows 上把 `\n` 翻成 `\r\n`,结果是**只改了 1 行、`git diff` 却显示整文件**, - 且提交时易触发「stashed changes conflicted with hook auto-fixes → Rolling back fixes」(提交不生成)。 - 铁律:读 `open(p,'rb')` / `Path.read_bytes()`,写 `open(p,'wb')` / `Path.write_bytes()`;非用文本模式 - 必须带 `newline=''`。改完用 `grep -c $'\r' <文件>` 或逐文件比对 `HEAD` 的 CRLF 计数验收—— - `.gitattributes` 的 `eol=lf` 只在提交时归一化,**工作区里被翻过的行尾不会自己变回来**。 -- **字节模式也不会救你:`replace` 会原样保留既有行尾(同一坑的另一面)**。字节层写入保证的是 - 「**忠实地坏**」——它不引入 CRLF,也不修复别人留下的 CRLF。所以「BOM 保住了」与「行尾被翻了」 - 是同一机制的两面:一次 `str.replace` 改动,带 BOM 的文件 BOM 仍在,带 CRLF 的文件 CRLF 仍在, - 两者都不报错、都要单独验收。改前加一道前置断言最省事:`assert b'\r\n' not in data`(或按 HEAD - 形态决定是否归一化),把问题挡在写之前而不是提交前。 -- **行尾验收判据是「相对 HEAD 不变」,不是「绝对 LF」**(这是本坑的判据,别用 `CRLF == 0`): - 对每个被改文件比 `work_CRLF > 0` 与 `HEAD_CRLF > 0` **是否一致**——两边都 0(LF 文件)→ OK; - 两边都 >0(CRLF 文件)→ OK;**一边 0 一边 >0 → 污染**。理由:`MDK-ARM/*.uvprojx` 这类文件在 HEAD - 里本来就是 CRLF 且有正当来源(UV4 改写),无差别归一化成 LF 反而制造假改动。批量脚本的自检就照这条 - 写(`git status --porcelain -z` 取路径,NUL 分隔避免非 ASCII 路径被 quoted 转义丢掉,再逐个 - `open(...,'rb')` 数 `\r\n`),别用 `git status --porcelain` 的默认 quoted 输出做路径解析。 -- **exit 2 先分三种再动手**(2026-10-10 / 2026-10-26 / 2026-10-30 实测):① **bash 语法错**——stderr 有 - `syntax error near unexpected token`,是把 PowerShell 形态丢进了 `ops_bash`,换写法即可; - ② **真没设** `DTU_KEIL_UV4`;③ **已设但本会话看不见**(agent 的 shell 由常驻服务派生,服务启动**之后** - 设的用户级变量不会进来;`run_code` 的 `process.env` 直接是空的)。 - ②③ 一律走 **「exit 2 实战闭环」** 那一节:探测候选路径 + 读 `HKCU\Environment`, - 再**只往那一次调用**的 env / `--uv4` 里注入命中路径重跑——别急着让用户去设,也别替他改全局。 -- 编码类报错(`#870-D: invalid multibyte character sequence` 等)先怀疑源文件 - BOM/编码被改写,而不是代码本身(C 源码带 BOM 名单与理由 → `docs/文档规范.md` §2)。 -- **退出码数值口径**(本 skill 是唯一事实源,其它文档一律指这里):`0` 成功 / `1` 构建失败(有 error)/ - `2` **脚本判定的环境错误**(`BuildEnvError`:UV4 找不到、uvprojx 缺失等——但见上条,bash 语法错也打 2, - 须先看 stderr 分型)/ `3` 用法错误(argparse)/ `4` build 锁被占用(并发 `-b` 不可行)。 - ⚠ **"exit 2" 本身不等于环境问题**——它是 ①bash 写法错 ②真没设 `DTU_KEIL_UV4` ③已设但本会话看不见 - 三者共用的码位,故一律先按上面「exit 2 先分三种」分型再动手。 +- **任何代码改动后必须先编译 0 错 0 警再谈烧录/提交**;只改 `.c` 里一行中文注释也算改动。 +- 报错定位读 `MDK-ARM/build_log.txt`,别只看终端回显;**别把脚本接进管道**(`| tail` 后 `$?` 恒 0)。 +- bash / `ops_bash` 里**不要照抄 PowerShell 的 `&` 形态**——那既不是构建通过也不是失败,是写法错。 +- **不要 `setx`、不要替用户改全局环境变量**;本 skill 只解决"这一次构建怎么跑起来"。 +- 构建后清理垃圾目录**绝不** `rd /s /q %SystemDrive%`(cmd 会展开成 `C:`);只用 bash 引号形态。 +- `MDK-ARM/*.uvprojx` 每次构建被 UV4 改写,**改动一律不入库**:只见 XML 格式/`PackID` 差异 → `git checkout -- ` 丢弃;只有真增删源文件才提交。 +- 批量改注释/文档脚本**只用字节模式**(`read_bytes` / `write_bytes`);文本模式在 Windows 把 `\n` 翻成 `\r\n`,造成整文件假 diff 与提交回滚。 ## 与其它 skill 的衔接 -- **build 锁的对面是谁**(`BUILD_LOCK_BUSY`、退出码 4、`pw:` 插件树、`@task plugin list` / `plugin adopt`、`_wt/` 台账与合并回收)归 `task-worktree` skill(F 节 = DSH worktree 插件桥);换机/新克隆时 `DTU_*` 工具路径变量的设立与「会话不继承」坑 = `new-machine-setup` skill。 -- 烧录/回读 = `stlink-flash` skill;串口闭环 = `serial-boot-test` skill - (其档案 `flash_cmd`/`readback_cmd` 即 stlink-flash 的入口命令)。 -- 收尾固定链(2026-10-26 实证):`/keil-build` → `scripts/ram_baseline.py --update` → - 体积门禁盖戳 → 内存数字回填与 `--scan` → 复跑 `ci_local` 静态段, - 直到钩子全绿且 0 错误 0 警告(RAM/栈口径见 `mem-budget` skill)。 +build 锁对面(`pw:` 插件树)→ `task-worktree` F 节;换机与工具路径 → `new-machine-setup`;烧录 → `stlink-flash`;串口闭环 → `serial-boot-test`;内存数字回填 → `mem-budget`。 + +⚠ **改本文件 frontmatter 要么整值加双引号,要么一个 ASCII 冒号都别写**:plain scalar 里出现「冒号 + 空格」会让 DSH 自带 `yaml` 解析器报 `Nested mappings are not allowed in compact mappings` → 技能整份不加载(`js-yaml` 能吃下去,自检会假绿)。值首字符不能是 `%` 或 `&`(双引号里的 `%SystemDrive%` 无碍)。落盘后让 DSH 真加载一次再收口。 diff --git a/.dsh/skills/keil-build/reference/build-env-error.md b/.dsh/skills/keil-build/reference/build-env-error.md new file mode 100644 index 00000000..96db1f4f --- /dev/null +++ b/.dsh/skills/keil-build/reference/build-env-error.md @@ -0,0 +1,73 @@ +# BUILD_ENV_ERROR — exit 2 实战闭环(自 SKILL.md 逐字外置,2026-11-18) + +## BUILD_ENV_ERROR + +> 路由:主文件失败索引表 `BUILD_ENV_ERROR` → 本节。原节 `## exit 2 实战闭环…`(L36–89)逐字搬移,未改写。 + +### 判据 + +脚本报 `BUILD_ENV_ERROR: UV4.exe not found …` 且退出码 2 = 环境错(UV4 未启动、build_log 未改写);先看 stderr 区分 bash 语法错/真没设/已设但本会话看不见三型。 + +### 处置 + +探测候选安装路径 → 读 HKCU\\Environment 确认值 → 只给这一次调用注入 env/`--uv4` 重跑 → 三样齐(UV4 行 + UV4_RC: 0 + BUILD_OK)复核。不替用户改全局。 + +### 证据边界 + +候选路径清单与 10 s 耗时为 2026-10-30 实测;"`setx`" 类全局改动属用户自己的事,本闭环未验证跨会话持久化。 + +### 逐字原文(未改写) + +## exit 2 实战闭环:`UV4.exe not found` 的探测 → 注入 → 复核(2026-10-30 实测) + +**先定性,别动源码**:脚本报 +`BUILD_ENV_ERROR: UV4.exe not found (--uv4 / config 'uv4' / $DSH_KEIL_UV4 / $DTU_KEIL_UV4 / PATH)` +且**退出码 2** = **环境错,不是构建失败**——本次 **UV4 根本没启动、`MDK-ARM/build_log.txt` 也没被改写**, +日志里看到的是上一次的。此时去改 `.c`/`.h` 或怀疑代码,就是把环境问题当编译问题排。 +(会话为什么看不见:DSH 会话的 shell 由常驻服务派生,**服务启动之后**设的用户级变量不会自动进来; +`run_code` 起的 Node 进程 `process.env` 干脆是空的(同一机制另见 `new-machine-setup` skill「实测坑」)。 +所以**变量"已设但本会话看不见"是常态**,不是用户没设。) + +1. **探测候选安装路径**(逐个 `fs.existsSync` / `test -f`,命中即取绝对路径)—— + `C:/Keil_v5/UV4/UV4.exe`、`C:/Keil/UV4/UV4.exe`、`D:/Keil_v5/UV4/UV4.exe`、`D:/Keil/UV4/UV4.exe`、 + `C:/Program Files/Keil_v5/UV4/UV4.exe`、`D:/Program Files/Keil_v5/UV4/UV4.exe` + (2026-10-30 实测只命中 `C:/Keil_v5/UV4/UV4.exe`,其余五个都不存在)。 + ```bash + for p in 'C:/Keil_v5/UV4/UV4.exe' 'C:/Keil/UV4/UV4.exe' 'D:/Keil_v5/UV4/UV4.exe' \ + 'D:/Keil/UV4/UV4.exe' 'C:/Program Files/Keil_v5/UV4/UV4.exe' 'D:/Program Files/Keil_v5/UV4/UV4.exe'; do + [ -f "$p" ] && echo "HIT $p"; done + ``` +2. **读用户级来源确认"值本来就对"**(同一轮里顺手做掉,别只靠猜路径): + bash / Node 侧 `reg query HKCU\Environment`(整表打出来再找 `DTU_KEIL_UV4` / `DSH_KEIL_UV4`), + PowerShell 侧 `[Environment]::GetEnvironmentVariable('DTU_KEIL_UV4','User')`。 + 有值 → 直接用它;没值/值指向旧目录 → 用第 1 步的命中路径。 + ⚠ **不替用户改全局**:不要 `setx`、不要 `SetEnvironmentVariable(...,'User')`——那是用户自己在真终端里 + 做的事(`docs/环境与部署/本地工具路径环境变量方案.md`);本闭环只解决"这一次构建怎么跑起来", + 报告里也必须这么写。 +3. **只给这一次调用注入**再重跑(两种等价形态,二选一): + ```js + // run_code:options.env 是**整体替换**,所以要连 SystemRoot / Path / USERPROFILE 一起给 + const { execSync } = await import('node:child_process'); + execSync('".venv/Scripts/python.exe" .dsh/skills/keil-build/scripts/keil_build.py', { + cwd: MAIN, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, + env: { SystemRoot: 'C:\\Windows', Path: 'C:\\Windows;C:\\Windows\\System32', + USERPROFILE: 'C:\\Users\\<你>', DTU_KEIL_UV4: 'C:\\Keil_v5\\UV4\\UV4.exe' } }); + ``` + - bash / `ops_bash` 侧的等价写法 = 显式参数 `--uv4 'C:\Keil_v5\UV4\UV4.exe'`(值含空格要整体加引号)。 + - `run_code` 的 `timeoutMs` 给足:注入后这次构建实测 **10 s** 跑完,但首次冷构建更长(我给的 500000)。 + - **别顺手加 `--no-lock`**:注入重跑时锁链照旧(`LOCK: 已获取 build 锁(task=build-cli)` → `已释放锁`)。 +4. **复核口径**(三样齐了才算真跑过,缺一样就是没构建):脚本回显 + `UV4: <绝对路径> (<来源>)`(来源随注入方式变:`$DTU_KEIL_UV4` 或 `--uv4`)→ + `UV4_RC: 0` → `BUILD_OK: 0 errors, 0 warnings`,且**外层退出码 0**(自己包 execSync 就显式把码打出来, + 别接管道,见「调用形态」)。报告里写清"本次注入 + 来源",**不得声称已永久设置系统/用户环境变量**。 + +- ⚠ 注入的若是**注册表里那个陈旧值**,会撞同族的另一种 2: + `BUILD_ENV_ERROR: $DTU_KEIL_UV4 is set but not a file: … (fix the value; no silent fallback)` + —— 值在但指向旧盘符/旧目录名(本仓踩过 `D:\Code\DTU 程序\…` 搬迁)。脚本**刻意不静默回退**, + 回到第 1 步用探测命中的路径覆盖它,别去猜目录、更别改脚本让它"猜 C 盘"(设计上明确禁止从旧路径猜)。 +- ⚠ 本闭环只回答"UV4 在哪儿",**不回答"调用写法对不对"**:从 bash 侧照抄 PowerShell 的 `&` 也是 exit 2, + 但 stderr 是 `syntax error near unexpected token`(见「调用形态」)。**先看 stderr 再决定排障方向**, + 两种 2 的处置完全不同。 +- **改 `.c` 注释(哪怕只改一行中文注释)也必须跑完这道构建验证**:2026-10-30 的实测就是 + 「改注释 → `/keil-build` → 吃 rc=2 → 探测+注入 → 10 s 通过」。注释类坑(BOM 被剥 → `#870-D`、 + 注释里写 `**` 路径 → 9-D)只在**重编译那个 TU 时**才暴露,"以前 0 警告"不代表安全。 diff --git a/.dsh/skills/keil-build/reference/build-lock.md b/.dsh/skills/keil-build/reference/build-lock.md new file mode 100644 index 00000000..ed888ee5 --- /dev/null +++ b/.dsh/skills/keil-build/reference/build-lock.md @@ -0,0 +1,48 @@ +# BUILD_LOCK_BUSY — build 锁自持自释(自 SKILL.md 逐字外置,2026-11-18) + +## BUILD_LOCK_BUSY + +> 路由:主文件失败索引表 `BUILD_LOCK_BUSY` → 本节。原节 `## build 锁…`(L90–118)逐字搬移,未改写。 + +### 判据 + +退出码 4 / `BUILD_LOCK_BUSY:` = build 锁被占用;持有者名带 `pw:` = DSH 插件树的构建占着 UV4。 + +### 处置 + +等对方 `finally` 自动释放,或本次加 `--lock-wait N` 排队;**绝不** `lock release ` 或杀 UV4 进程。 + +### 证据边界 + +TTL 自报口径(timeout/3600 + 15min,下限 0.5h)为 2026-10-12 实测;`bench` 锁仍须会话作用域手工持有,不在本节范围。 + +### 逐字原文(未改写) + +## build 锁:脚本自持自释(2026-10-12) + +**UV4 不能两个实例同时 `-b`,但构建锁不该由调用方"记得释放"**——那正是泄漏源: +Agent 手工 `lock acquire build` 后忘了 `release`,锁要挂到 TTL 才被接管。 +故本脚本**自己**管:进入 acquire → `try` 构建 → `finally` **无条件** release +(构建失败、异常、`SystemExit` 都会释放)。 + +| 开关 | 作用 | +|---|---| +| `--lock-task ` | 持有者名。默认 `$DTU_TASK_ID` → 从 cwd 反推:`_wt/-/` → ``(`@task` 那批);`.agents/worktrees//` 或旧 `.dsh-worktrees/worktree//` → `pw:`(DSH worktree **插件**建的树,`plugin_tree_owner()`)→ 都没有才落 `build-cli` | +| `--lock-wait ` | 锁被占时等待 N 秒(默认 0 = 立即失败,退出码 4) | +| `--no-lock` | 完全不加锁(危险:并发 `-b` 互相干扰) | +| `DTU_LOCK_HELD=build` | 环境变量:**调用方已持锁**时设它,本脚本跳过自持自释(`task-worktree done` 的门禁即如此用) | + +- **TTL 自报**(2026-10-12):acquire 时按 `--timeout` 声明陈旧窗口 + = `timeout/3600 + 15min`,下限 0.5h(默认 600s → **0.5h**)。这样崩溃/强杀留下的锁, + 其自动接管窗口与本次构建上限同量级,而不再是全局 6h —— 编译很快,兜底窗口也该短。 +- 锁工具 = 兄弟 skill `task-worktree/scripts/task_worktree.py`;**找不到则降级为不加锁 + 并告警**(保持本 skill 可独立搬运)。 +- ⚠ 从 `_wt/-/` 反推持有者名,意味着"手工 `lock acquire build --task ` + 后再跑 `/keil-build`"仍**幂等**(同名即视为自己持有),不会自我死锁。 +- **退出码 4 的持有者名带 `pw:`(如 `pw:refactor-logging`)= 插件在 `.agents/worktrees//`(或旧 `.dsh-worktrees/worktree//`)里跑的构建占着 UV4,不是某个 `@task` 任务 ID**: + 插件树**没有台账**,别拿它去 `lock release `(释放不掉别人的锁)、更别去杀 UV4 进程。正解 = + 等那次构建自己 `finally` 释放(自持自释;崩溃则按自报 TTL 兜底),或本次加 `--lock-wait ` 排队; + 想知道是哪棵树的谁:`"$PY" "$TW" plugin list`(缺联接再 `plugin adopt `)→ 细节归 + `task-worktree` skill F 节(插件桥)。 +- **只 build 锁自动;`bench` 锁仍须 Agent 手工持**(它是**会话作用域**,跨 + 烧录→`/serial-boot-test`→探针多条命令,逐命令自动释放会让别的任务插进来扰动设备)。 diff --git a/.dsh/skills/keil-build/reference/executor-shell-forms.md b/.dsh/skills/keil-build/reference/executor-shell-forms.md index e85c9bd0..4bff658a 100644 --- a/.dsh/skills/keil-build/reference/executor-shell-forms.md +++ b/.dsh/skills/keil-build/reference/executor-shell-forms.md @@ -1,6 +1,22 @@ # 调用形态:先认执行器是哪个 shell(2026-10-26 实测)(自 SKILL.md 外置) -> 本文由 keil-build 的 SKILL.md「调用形态:先认执行器是哪个 shell(2026-10-26 实测)」一节逐字外置而来(渐进展开:主文件只留索引与指针)。步骤号沿用原文,未重编。 +## SHELL_FORM + +> 路由:主文件失败索引表 `SHELL_FORM` → 本节。原节 `## 调用形态…`(自 SKILL.md 外置)逐字保留于下。 + +### 判据 + +stderr 含 `syntax error near unexpected token` = PowerShell 形态被丢进 bash/ops_bash,exit 2 是写法错,不是环境错、不是构建失败。 + +### 处置 + +bash / `ops_bash` 侧去掉前导 `&`、路径改正斜杠;`BUILD_RC=0` + `UV4_RC: 0` + `BUILD_OK: 0 errors, 0 warnings` 三样齐才算构建通过。 + +### 证据边界 + +2026-10-26 实测口径;`$?` 取到管道尾码属 Bash 行为,换 shell 需重验。 + +### 逐字原文(未改写) 同一条编译命令,**PowerShell 与 bash 是两种写法**;`ops_bash` / `run_code` 起的是 `/usr/bin/bash -c`,**不认 PowerShell 形态**,照抄 skill 正文的 PowerShell 段会直接语法错退出。 diff --git a/.dsh/skills/keil-build/reference/iron-rules.md b/.dsh/skills/keil-build/reference/iron-rules.md new file mode 100644 index 00000000..f7d36217 --- /dev/null +++ b/.dsh/skills/keil-build/reference/iron-rules.md @@ -0,0 +1,67 @@ +# 铁律与陷阱(长尾,自 SKILL.md 逐字外置,2026-11-18) + +## IRON_RULES + +> 路由:主文件失败索引表 `IRON_RULES` → 本节。原节 `## 铁律与陷阱…`(L141–188)逐字搬移,未改写;致命禁令的短句仍留在主文件。 + +### 判据 + +退出码数值口径、exit 2 三型分型、编码类报错的根因方向均在本节给全;正常路径不必读。 + +### 处置 + +按节内对应条目处置(字节模式写文件、exit 2 分型后路由、uvprojx churn 丢弃等)。 + +### 证据边界 + +各条均标注实测日期(2026-10-10 / 10-26 / 10-30 / 11-16),属特定环境结论;换 Keil 版本或工具链须重验。 + +### 逐字原文(未改写) + +## 铁律与陷阱(实测教训) + +- **任何代码改动后必须先编译验证(0 错误 0 警告)再谈烧录/提交**——编译不过就进 + 硬件闭环只会把编译错误伪装成运行问题。**只改 `.c` 里一行中文注释也算改动**(2026-10-30 实测: + 改注释 → `/keil-build` → 环境错 → 探测注入 → 10 s 通过):BOM/嵌套注释这类坑只在重编译那个 TU 时才暴露。 +- **警告也算失败**:判 PASS 只认退出码 0,别只看"有没有 error:"(取退出码的管道陷阱见「调用形态」)。 +- **`MDK-ARM/*.uvprojx` 每次构建后被 UV4 自动改写,改动一律不入库**:UV4 会把工程 + XML 归一化成本机风格(`` → ``、XML 声明加 `standalone="no"`)并把 + `PackID` 降到**本机装的 DFP 版本**(属降级——提交后会把别人的 Pack 版本一起改掉)。 + 判断:`git diff` 里只见 XML 格式/`PackID` 差异而**无源文件挂载增删** → + `git checkout -- ` 丢弃;只有真的增删了源文件(grep 文件名计数变化)才提交。 + 同目录的 `*.uvoptx` / `*.uvguix.*` 是 IDE 个人设置,已在 `.gitignore` 里,不会露出来。 +- **构建后仓库根冒出 `%SystemDrive%/`** = UV4 / 字体工具在残缺环境(缺 `SystemDrive`、`ProgramData`) + 里按**未展开的 known-folder 字面量**建出来的**相对路径**目录,不是任何人在飞的改动: + `rm -rf -- '%SystemDrive%'`(bash 引号形态)删掉即可,**严禁 `rd /s /q %SystemDrive%`——cmd 会把它 + 展开成 `C:`**;`.gitignore` 已兜住 + 脚本已加 `ENV_SPARSE`/`JUNK_DIR` 守卫 → 见「构建副产物」一节。 +- 报错定位读日志别只看终端回显:本仓库 = `MDK-ARM\build_log.txt`。 +- **批量改注释/文档脚本必须用字节模式(2026-11-16 一天内三个会话各踩一次)**:`open(p,'w')` / + `Path.write_text()` 在 Windows 上把 `\n` 翻成 `\r\n`,结果是**只改了 1 行、`git diff` 却显示整文件**, + 且提交时易触发「stashed changes conflicted with hook auto-fixes → Rolling back fixes」(提交不生成)。 + 铁律:读 `open(p,'rb')` / `Path.read_bytes()`,写 `open(p,'wb')` / `Path.write_bytes()`;非用文本模式 + 必须带 `newline=''`。改完用 `grep -c $'\r' <文件>` 或逐文件比对 `HEAD` 的 CRLF 计数验收—— + `.gitattributes` 的 `eol=lf` 只在提交时归一化,**工作区里被翻过的行尾不会自己变回来**。 +- **字节模式也不会救你:`replace` 会原样保留既有行尾(同一坑的另一面)**。字节层写入保证的是 + 「**忠实地坏**」——它不引入 CRLF,也不修复别人留下的 CRLF。所以「BOM 保住了」与「行尾被翻了」 + 是同一机制的两面:一次 `str.replace` 改动,带 BOM 的文件 BOM 仍在,带 CRLF 的文件 CRLF 仍在, + 两者都不报错、都要单独验收。改前加一道前置断言最省事:`assert b'\r\n' not in data`(或按 HEAD + 形态决定是否归一化),把问题挡在写之前而不是提交前。 +- **行尾验收判据是「相对 HEAD 不变」,不是「绝对 LF」**(这是本坑的判据,别用 `CRLF == 0`): + 对每个被改文件比 `work_CRLF > 0` 与 `HEAD_CRLF > 0` **是否一致**——两边都 0(LF 文件)→ OK; + 两边都 >0(CRLF 文件)→ OK;**一边 0 一边 >0 → 污染**。理由:`MDK-ARM/*.uvprojx` 这类文件在 HEAD + 里本来就是 CRLF 且有正当来源(UV4 改写),无差别归一化成 LF 反而制造假改动。批量脚本的自检就照这条 + 写(`git status --porcelain -z` 取路径,NUL 分隔避免非 ASCII 路径被 quoted 转义丢掉,再逐个 + `open(...,'rb')` 数 `\r\n`),别用 `git status --porcelain` 的默认 quoted 输出做路径解析。 +- **exit 2 先分三种再动手**(2026-10-10 / 2026-10-26 / 2026-10-30 实测):① **bash 语法错**——stderr 有 + `syntax error near unexpected token`,是把 PowerShell 形态丢进了 `ops_bash`,换写法即可; + ② **真没设** `DTU_KEIL_UV4`;③ **已设但本会话看不见**(agent 的 shell 由常驻服务派生,服务启动**之后** + 设的用户级变量不会进来;`run_code` 的 `process.env` 直接是空的)。 + ②③ 一律走 **「exit 2 实战闭环」** 那一节:探测候选路径 + 读 `HKCU\Environment`, + 再**只往那一次调用**的 env / `--uv4` 里注入命中路径重跑——别急着让用户去设,也别替他改全局。 +- 编码类报错(`#870-D: invalid multibyte character sequence` 等)先怀疑源文件 + BOM/编码被改写,而不是代码本身(C 源码带 BOM 名单与理由 → `docs/文档规范.md` §2)。 +- **退出码数值口径**(本 skill 是唯一事实源,其它文档一律指这里):`0` 成功 / `1` 构建失败(有 error)/ + `2` **脚本判定的环境错误**(`BuildEnvError`:UV4 找不到、uvprojx 缺失等——但见上条,bash 语法错也打 2, + 须先看 stderr 分型)/ `3` 用法错误(argparse)/ `4` build 锁被占用(并发 `-b` 不可行)。 + ⚠ **"exit 2" 本身不等于环境问题**——它是 ①bash 写法错 ②真没设 `DTU_KEIL_UV4` ③已设但本会话看不见 + 三者共用的码位,故一律先按上面「exit 2 先分三种」分型再动手。 diff --git a/.dsh/skills/keil-build/reference/systemdrive-junk-dir.md b/.dsh/skills/keil-build/reference/systemdrive-junk-dir.md index 940be1ba..b58501d9 100644 --- a/.dsh/skills/keil-build/reference/systemdrive-junk-dir.md +++ b/.dsh/skills/keil-build/reference/systemdrive-junk-dir.md @@ -1,6 +1,22 @@ # 构建副产物:`%SystemDrive%` 字面量垃圾目录(2026-10-26 两次复发 → 2026-10-28 定性并加守卫)(自 SKILL.md 外置) -> 本文由 keil-build 的 SKILL.md「构建副产物:`%SystemDrive%` 字面量垃圾目录(2026-10-26 两次复发 → 2026-10-28 定性并加守卫)」一节逐字外置而来(渐进展开:主文件只留索引与指针)。步骤号沿用原文,未重编。 +## JUNK_DIR + +> 路由:主文件失败索引表 `JUNK_DIR` → 本节。原节 `## 构建副产物…`(自 SKILL.md 外置)逐字保留于下。 + +### 判据 + +构建后仓库根冒出 `%SystemDrive%/ProgramData/...` 未跟踪目录(伴随 `WARN: ENV_SPARSE:` / `WARN: JUNK_DIR:`)= 残缺环境按字面量建出的工具副产物,不是任何人在飞的改动。 + +### 处置 + +先取证(枚举 + mtime)再处置:源头未断会删完立刻长回来;只用 bash 引号形态 `rm -rf -- '%SystemDrive%'`,**绝不** `rd /s /q %SystemDrive%`;要留证用 Python `os.walk`+`shutil.move` 搬到仓库外,别用 shell `mv`。 + +### 证据边界 + +两次复发(2026-10-26 / 10-28)为本机实测;`.gitignore:167` 条目与 `harden_windows_env()` 守卫是代码事实,换仓需核行号。 + +### 逐字原文(未改写) **症状**:`/keil-build`(或 `scripts/check_font_charset.py` 这类 fontTools 字体工具)跑完,仓库根 冒出未跟踪目录 `%SystemDrive%/ProgramData/Microsoft/Windows/Caches/`,里面是几个 `.db` diff --git a/.dsh/skills/lvgl-simulator/SKILL.md b/.dsh/skills/lvgl-simulator/SKILL.md index 47efd766..9bbc97ac 100644 --- a/.dsh/skills/lvgl-simulator/SKILL.md +++ b/.dsh/skills/lvgl-simulator/SKILL.md @@ -19,6 +19,14 @@ PC 上编译运行与 MCU **同一份** UI 源码(CMake + MSVC + SDL2,x64, ⚠ 窗口模式默认 **60 s 空闲自动退出**(防挂后台),`--idle <秒>` 覆盖。 +**成功输出样例**(本轮实跑 `lvgl_sim.exe --screenshot`,无头截图):看到 `screenshot: ... (3200 bytes, 160x160 I1)` 且退出码 0 就是出图通了,不用再往下看。 + +```text +[UI_STANDBY] standby: ready (idle=60000ms) +pool after keys: used=5368 free=8488 +screenshot: <路径>/skill_probe.bin (3200 bytes, 160x160 I1) +``` + ## 无头自检(退出码 0=PASS / 非 0=FAIL) | 命令(在 `simulator\build\Debug\` 下或用全路径) | 用途 | diff --git a/.dsh/skills/mem-budget/SKILL.md b/.dsh/skills/mem-budget/SKILL.md index 6b1bee04..6e0edd58 100644 --- a/.dsh/skills/mem-budget/SKILL.md +++ b/.dsh/skills/mem-budget/SKILL.md @@ -6,151 +6,82 @@ whenToUse: 新增任务/加大缓冲/改栈/接入日志之前之后、链接报 # mem-budget — RAM/栈预算核算 -## 固定动作(改前、改后各跑一次) +## 默认路径:一条命令跑通(改前、改后各跑一次) + +仓库根,先 `/keil-build` 保证 `.htm`/`.map` 最新(产物按脚本自身位置定位),再: ```powershell -# cwd = 项目根;先 /keil-build 保证 .htm/.map 是最新的(产物按脚本自身位置定位,见下节) & '.venv\Scripts\python.exe' ".dsh\skills\mem-budget\scripts\mem_check.py" -# 等价于分别跑: -# scripts/ram_report.py (.map → RAM/Flash 分区与按文件占用表) -# scripts/stack_report.py (.htm 静态调用图 → 每任务最坏链 vs 配置栈) -# 报告落盘留档(改前/改后各一份,供逐帧差分): +``` + +等价于 `scripts/ram_report.py`(.map → RAM/Flash 分区与按文件占用)+ `scripts/stack_report.py`(.htm 静态调用图 → 每任务最坏链 vs 配置栈)。留档各一份供逐帧差分,有真机日志叠加运行时水位: + +```powershell & '.venv\Scripts\python.exe' scripts/stack_report.py -o ci-artifacts/sr_before.md -# 叠加运行时水位(有真机日志时): & '.venv\Scripts\python.exe' scripts/stack_report.py -s .dsh\skills\serial-assistant\scripts\state\serial.log ``` -退出码:0=全部通过 / 1=有任务不达标 / 2=解析错误(.htm/.map 缺失先重跑构建)。 -别整篇读输出,抓关键行:`grep -aE 'iec104|margin|FAIL|ISR|Rule' ci-artifacts/sr_before.md`。 +「改前/改后」必须是**两次不同的 Linker run**——同一份 .htm/.map 跑两遍只是复述,不构成复验。退出码:`0`=全过 / `1`=有任务不达标 / `2`=解析错误(.htm/.map 缺失先重跑构建)。别整篇读输出,抓关键行:`grep -aE 'iec104|margin|FAIL|ISR|Rule' ci-artifacts/sr_before.md`。 -**「改前 / 改后」必须是两次不同的 Linker run**(两个不同的产物身份):同一份 .htm/.map 上跑两遍 -只是把同一个数字复述两遍,不构成"改后已复验"。 +## 成功输出(默认路径跑通的样子) -## 测量身份口径(先钉树与时刻,再看数字) - -1. 脚本按 __file__ 定位产物,不按 cwd —— 跨树必须换脚本(在主树跑脚本量任务树 = 拿旧 .map 当真值) -2. 重跑报告脚本不算新测量(复述 ≠ 复验):只有新的 Linker run 才算一次新测量 -3. 钉身份的取数法:.htm/.map 按约定不入库 → 把时刻写进正文/台账;记录最小格式 = tree/commit + Linker run 时刻 + 产物来源(本次构建 / 盘上既有) -> 本节全文(逐字搬移、未改写,含命令与实测数字)→ [measurement-identity.md](reference/measurement-identity.md)。动手前先读那篇。 - -## 静态最坏链回归的归因(同涨同一数值 = 共享帧,不是调用方) - -- 多条任务链分毫不差同涨/同降同一个数值 ⇒ 加深在这些任务共用的被调帧 / 共享尾段上,不在任何一个调用方(别先猜「新增了大局部缓冲」,实测猜错过一次) -- 逐棵树逐帧比 frame size、不只比总数:stack_report.py 的 own-frame 表锁链尾公共段;grep -ac 'In Cycle' 在 .htm 里找环(实测 17 处)—— 链接器幻影环能在无人改栈配置时让全仓链齐涨 -- Maximum Stack Usage 里的 + Unknown(Cycles, Untraceable Function Pointers) 说明静态数是估计值,别当精确值上报;不采信口头结论,用目标树的脚本 + .venv 解释器自己复算 -- 处置后的下一步:抬栈(Src/freertos.c 的 USER CODE 区,属 Ask-first)或收紧共享缓冲 / 断环;改前改后各跑一次 stack_report.py + ram_report.py,且「改后」那次必须落在一次新的 Linker run 上 -> 本节全文(逐字搬移、未改写,含命令与实测数字)→ [shared-frame-attribution.md](reference/shared-frame-attribution.md)。动手前先读那篇。 - -## 判读口径 - -- **静态**:`stack_report.py` 的 Max Depth(最坏调用链累计)vs `Src/freertos.c` 配置栈; - 默认要求余量 ≥30%(`--min-free-pct`),ISR 另留 `--isr-margin`(默认 1024B)。 - 判定式 `margin = cfg - max(static_max_depth, runtime_peak)` 须 ≥ `max(isr_margin, 30% of cfg)`。 -- **运行时**:开机日志 `[STACK] peak_used=…/… free_min=…` 与静态值对照—— - **静态最坏链是上界(硬线)、运行时峰值是下界证据(趋势)**,两者都要看;余量 <1KB 底线要上报。 -- **RAM 总量**:`ram_report.py` 对 Grand Totals 与 `docs/内存管理/` 预算表核对; - 链接错 `L6406E` = 已经溢出,用按文件表找大头。 -- 任务表一致性由 pre-commit `task-table` 钩子保证;`mem-budget` 钩子拦 RW_IRAM1/RW_CCM >92%, - **并核台账受管区是否与 .map 同源**;`mem-numbers` 钩子核文档里的内存数字—— - 数字与树/时刻脱钩、或**构建后只跑了 `--update` 没回填受管区**时,响的就是这两条(回填见下一节)。 - -## 权威构建后的台账回填(三个旗标,别混) - -`.map` 是内存/Flash 数字的**唯一事实源**;台账与文档里的数字由脚本从它生成——**不手抄、不手改** -(`docs/内存管理/RAM预算台账.md` 首段就写着"数字不手抄")。三份落点 = 三个旗标,一条命令只干其中一件: -`ram_baseline.py` 的 `--gate/--write/--update/--trend` 是 `add_mutually_exclusive_group()` -(`scripts/ram_baseline.py:415-419`),想干两件就得调两次。 - -| 落点 | 旗标 | 实际改了什么 | -|---|---|---| -| `scripts/ram_baseline.tsv` 趋势基线(顺带刷 `scripts/size_attestation.json` 同码凭证) | `ram_baseline.py --update` | **只**追加/覆盖当日那一行趋势(Code/RO/RW/ZI + 三区水位 + Top-10 RW+ZI)。**不碰台账正文** | -| `docs/内存管理/RAM预算台账.md` 的 `` 受管区 | `ram_baseline.py --write` | 从 .map 重渲染区域水位 + 子系统配额对照(打印「已同步台账受管区。」或「台账受管区已是最新。」) | -| `docs/内存管理/RAM使用分析与优化方案.md` 的 `` 快照区 | `check_mem_numbers.py --write` | 从**同一份** .map 重渲染内存/Flash 快照表(打印「已更新内存快照:…」) | - -**台账 §4 那句「每次 `/keil-build` 后跑 `scripts/ram_baseline.py --update`」只喂趋势行,不等于回填受管区。** -实测代价:照那句跑完 `--update` 就提交 → `mem-budget`、`mem-numbers` 两条钩子当场红。 -`mem-budget` 的 entry 是 `python scripts/ram_baseline.py --gate`(`.pre-commit-config.yaml:571`)——它在 92% 阈值之外 -还核**台账受管区与 .map 的一致性**,漂移即 `[FAIL] 台账受管区与 .map 不一致(区域水位或子系统配额表漂移)` -并打印 `修复:python scripts/ram_baseline.py --write`(`scripts/ram_baseline.py:221-224`); -`mem-numbers` 的 entry 是 `python scripts/check_mem_numbers.py --scan`(同文件 :193),不一致时打印 -`修复:运行 python scripts/check_mem_numbers.py --write`(`scripts/check_mem_numbers.py:416`)。 -改用两个 `--write` 后重提,同一笔提交触发的 26 条钩子全 Passed。 - -### 提交前固定顺序(构建 → 回填 → 真钩子提交) - -```powershell -# cwd = 项目根,一律 .venv 解释器 -# 0) 权威构建先行(0 错 0 警):回填读的是**盘上那份 .map**,构建没落定就 --write = 把旧数字写进台账,钩子照样红 -& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py - -# 1) 趋势行(纪律项,不是回填):覆盖 tsv 当日行 + 顺带刷体积同码凭证 -& '.venv\Scripts\python.exe' scripts/ram_baseline.py --update - -# 2) 回填台账受管区(mem-budget 钩子核的就是这一段) -& '.venv\Scripts\python.exe' scripts/ram_baseline.py --write - -# 3) 回填文档快照区(mem-numbers 钩子核的就是这一张表) -& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --write - -# 4) 逐字自跑提交时会跑的这两条 entry(比事后翻 pre-commit 输出快) -& '.venv\Scripts\python.exe' scripts/ram_baseline.py --gate # 0 = 阈值 + 受管区都过 -& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --scan # 0 = 快照区与 .map 一致 - -# 5) 把刚落盘的落点一并 add,然后**真钩子**提交(绝不 --no-verify、绝不手改数字) -git add docs/内存管理/RAM预算台账.md docs/内存管理/RAM使用分析与优化方案.md scripts/ram_baseline.tsv scripts/size_attestation.json +``` +MEM_CHECK: ram=0 stack=0 -> PASS ``` -退出码:`ram_baseline.py` 0=通过或跳过 / **1=阈值超限或受管区漂移** / 2=.map 解析失败; -`check_mem_numbers.py` 0=一致 / 1=不一致、缺受管锚点或找不到事实源。 +即 `mem_check.py` 打印 `MEM_CHECK: ram=<码> stack=<码> -> PASS|FAIL|ERROR`,两码均 0 时尾部为 `PASS`;报告脚本落出 `OK <路径>` 且每任务 `margin` 达标(静态 Max Depth vs 配置栈,余量 ≥30% `--min-free-pct`、ISR 另留 `--isr-margin` 默认 1024B)。 -### 回填链上的坑(实测) +## 失败了 → 去哪读(索引表) -- --write 说「已是最新」而钩子还红 -- tsv 落后只 WARN、不拦 -- --gate 无 .map → SKIP,而脚本自己写明「SKIP 不等于 PASS」 -- --map 只换读、不换写 -- --scan 的散句告警 --write 不替你改 -- --update 的盖戳排在索引后面 -- 改写型钩子当场改文件是流程不是故障 -- mem-budget 触发面很宽 -> 本节全文(逐字搬移、未改写,含命令与实测数字)→ [backfill-pitfalls.md](reference/backfill-pitfalls.md)。动手前先读那篇。 +失败信息自带稳定键;命中才读对应小节(每节 = 判据 / 处置 / 证据边界 + 逐字原文): -## 运行时峰值抖动与"算不算劣化" +| 键(脚本真实输出 / 阶段名) | 什么条件下读 | 去处 | +|---|---|---| +| `BACKFILL_FLAGS` | mem-budget / mem-numbers 报「与 .map 不一致」;纠结 --update / --write | [backfill-flags.md](reference/backfill-flags.md) → `## BACKFILL_FLAGS` | +| `BACKFILL_ORDER` | 需要完整回填命令序列与退出码口径 | [backfill-order.md](reference/backfill-order.md) → `## BACKFILL_ORDER` | +| `BACKFILL_PITFALLS` | `--write` 说最新钩子还红、tsv 只 WARN、`--gate` SKIP 等边界 | [backfill-pitfalls.md](reference/backfill-pitfalls.md) → `## BACKFILL_PITFALLS` | +| `MEASUREMENT_IDENTITY` | 跨树测量、重跑报告当新测量、数字与树/时刻脱钩 | [measurement-identity.md](reference/measurement-identity.md) → `## MEASUREMENT_IDENTITY` | +| `SHARED_FRAME` | 多条链同涨同一数值、链接器幻影环 | [shared-frame-attribution.md](reference/shared-frame-attribution.md) → `## SHARED_FRAME` | +| `RUNTIME_JITTER` | 跨启动峰值抖动、「不劣于上一轮」判据假红 | [runtime-jitter.md](reference/runtime-jitter.md) → `## RUNTIME_JITTER` | +| `VERIFICATION` | 提交前核对这轮测量/数字入库是否算数 | [verification.md](reference/verification.md) → `## VERIFICATION` | -- 同一份镜像连续启动 5 次,`uiTask` 峰值实测在 4116~4188 之间摆 **72 B** ⇒ 跨启动本身就有几十 B 抖动, - "相对上一轮 +100 B"**不可归因**于被测改动。判据写成"栈水位不劣于上一轮"必然假红。 -- 可执行修法(二选一,别都留着): - 1. 同一份像**≥3 次启动取最大值**互比,并加容差(**±128 B 量级**); - 2. 硬线改用 `stack_report.py` 的**静态最坏链**,运行时峰值降级为趋势参考。 -- 判据一改要同步**所有落点**:判据正文、跑判据的脚本、记录判据的文档三处一起改,只改一处等于各说各话。 +## 判读口径(改前改后都要看) + +- **静态**:`stack_report.py` Max Depth(最坏链累计)vs `Src/freertos.c` 配置栈;判定式 `margin = cfg - max(static_max_depth, runtime_peak)` 须 ≥ `max(isr_margin, 30% of cfg)`。 +- **运行时**:开机日志 `[STACK] peak_used=…/… free_min=…` 与静态对照——**静态最坏链是上界(硬线)、运行时峰值是下界证据(趋势)**,两者都要看,余量 <1KB 底线要上报。 +- **RAM 总量**:`ram_report.py` 对 Grand Totals 与 `docs/内存管理/` 预算表核对;`L6406E` = 已溢出,用按文件表找大头。 +- `task-table` 钩子保证任务表一致;`mem-budget` 钩子拦 RW_IRAM1/RW_CCM >92% 且核台账受管区与 .map 同源;`mem-numbers` 核文档内存数字。 + +## 权威构建后回填(默认命令块) + +`.map` 是唯一事实源,台账/文档数字由脚本生成——**不手抄、不手改**。三旗标互斥(`add_mutually_exclusive_group()`),一次一件。权威构建(0 错 0 警)后依次: + +```powershell +& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py # 0) 权威构建先行 +& '.venv\Scripts\python.exe' scripts/ram_baseline.py --update # 1) 趋势行(纪律项,非回填) +& '.venv\Scripts\python.exe' scripts/ram_baseline.py --write # 2) 回填台账受管区 +& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --write # 3) 回填文档快照区 +& '.venv\Scripts\python.exe' scripts/ram_baseline.py --gate # 4) 0=阈值+受管区都过 +& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --scan # 0=快照区与 .map 一致 +``` + +`ram_baseline.py` 0=通过或跳过 / 1=阈值超限或受管区漂移 / 2=.map 解析失败;`check_mem_numbers.py` 0=一致 / 1=不一致或缺锚点。旗标语义与完整序列见 `BACKFILL_FLAGS` / `BACKFILL_ORDER`。 ## 成本模型(实测,估算用) -- **`DBG_*` 日志不是免费的**:每条调用点约 **90 B Flash**(字符串常量另计)+ 深链上 - 每帧一份行缓冲进最坏栈(实测一条链 9 帧 ≈ 1.5 KB 纯日志缓冲)。 - 已覆盖步骤勿加重复锚点,只在原先静默返回的黑洞处补。 -- **深调用链模块收紧行缓冲**:`#define DBG_LINE_BUF_MAX 128U` 写在 `#include "dbg_log.h"` - 之前;取值必须 ≥ 该模块最长日志行(时间戳 20 + 标签 + 正文),否则截断。 -- **加大局部缓冲的替代方案是静态化**(实测 lftpd 9 处大局部缓冲静态化:BSS +4.6 KB, - 任务峰值 3480B→1184B)——栈紧张时先找大局部变量。 -- **自研代码禁 C 库堆**(MicroLIB 堆仅 512B):只用 `pvPortMalloc/vPortFree`(FreeRTOS 堆), - 模拟器 CRT 堆照不出 MCU 堆分配失败。 +- **`DBG_*` 不免费**:每调用点约 90 B Flash(字符串常量另计)+ 深链每帧一份行缓冲(实测一条链 9 帧 ≈1.5 KB)。 +- **深链模块收紧行缓冲**:`#define DBG_LINE_BUF_MAX 128U` 写在 `#include "dbg_log.h"` 前,≥ 该模块最长日志行否则截断。 +- **加大局部缓冲的替代是静态化**(实测 lftpd 9 处静态化:BSS +4.6 KB,任务峰值 3480B→1184B)——栈紧张先找大局部变量。 +- **自研代码禁 C 库堆**(MicroLIB 堆仅 512B):只用 `pvPortMalloc/vPortFree`。 -## 验证(这轮测量算数了吗) +## 禁令(看着合理但致命,留在主文件) -1. 报告头 `- Source:` 的相对路径落在**我要量的那棵树**下(不是裸文件名,更不是别的树); -2. `- Linker run:`(或 .htm 的 `Last Updated:` / mtime)与本轮那次构建对得上,且**不同于**上一轮那次的时刻 - ——相同就是复述,回去先做一次构建再比; -3. 树身份已按 `tree/commit + 时刻 + 产物来源` 写进提交正文/台账,而不是只留在终端输出里; -4. 结论里互比的数字必须来自**同一棵树同一次链接**;跨树比较要各自给出树与时刻; -5. 涉及劣化判定时注明依据的是静态最坏链(硬线)还是运行时峰值(趋势),并已计入跨启动抖动。 -6. 要入库的数字:本轮已按「`/keil-build` → `ram_baseline.py --update` → `ram_baseline.py --write` → - `check_mem_numbers.py --write`」回填,并逐字自跑 `ram_baseline.py --gate` 与 `check_mem_numbers.py --scan` 各返 0; - 台账 / 文档 / tsv 的改动与代码同一笔入库,**未手改数字、未用 `--no-verify`**。 +- 改前/改后必须是**两次不同 Linker run**,重跑报告脚本不算新测量 → `MEASUREMENT_IDENTITY`。 +- **不手抄、不手改**台账/文档数字;**绝不 `--no-verify`**;台账/文档/tsv 改动与代码同一笔入库。 +- 只跑 `ram_baseline.py --update` 不回填受管区 = 钩子当场红——**`--update` 只喂趋势行,不等于回填**。 +- 回填读的是**盘上那份 .map**,构建没落定就 `--write` = 把旧数字写进台账。 +- 判据涉及劣化时区分静态最坏链(硬线)还是运行时峰值(趋势),并计入跨启动抖动 → `RUNTIME_JITTER`。 -## 其它项目怎么套 +## 其它项目怎么套 / 衔接 -模式通用:链接器 map + 调用图 htm 是**免硬件**的栈可观测源;固定"改前改后各跑一次 -报告 + 运行时水位叠加 + 余量阈值"三件套,**外加一条身份口径——脚本按自身位置定位产物, -跨树比的是"两棵树各自的脚本 + 各自的链接时刻",重跑同一份产物永远只是复述**。 -本仓库两个报告脚本按 Keil 输出格式解析,换工具链(GCC newlib + `-fstack-usage`)需替换解析层,工作流不变。 +模式通用:链接器 map + 调用图 htm 是免硬件栈可观测源;固定"改前改后各跑一次报告 + 运行时水位叠加 + 余量阈值"三件套,外加身份口径(跨树比的是两棵树各自的脚本 + 各自链接时刻)。本仓两脚本按 Keil 格式解析,换工具链(GCC newlib + `-fstack-usage`)替换解析层、工作流不变。衔接:构建 `keil-build`(收尾固定链 `/keil-build` → 本 skill 回填 → 体积门禁 → `ci_local` 静态段);并行树身份 `task-worktree`。 diff --git a/.dsh/skills/mem-budget/reference/backfill-flags.md b/.dsh/skills/mem-budget/reference/backfill-flags.md new file mode 100644 index 00000000..0cb9edad --- /dev/null +++ b/.dsh/skills/mem-budget/reference/backfill-flags.md @@ -0,0 +1,41 @@ +# 权威构建后的台账回填:三个旗标(自 SKILL.md 逐字外置,2026-11-18) + +## BACKFILL_FLAGS + +> 路由:主文件失败索引表 `BACKFILL_FLAGS` → 本节。原节 `## 权威构建后的台账回填`(L57–78)逐字搬移。 + +### 判据 + +mem-budget / mem-numbers 钩子报「与 .map 不一致」= 构建后只跑 `--update` 没回填受管区/快照区。 + +### 处置 + +三份落点 = 三个旗标(互斥组,一次一件):`ram_baseline.py --update` 只喂趋势行 / `--write` 回填台账受管区 / `check_mem_numbers.py --write` 回填文档快照区。改完逐字自跑 `--gate` 与 `--scan` 各返 0。 + +### 证据边界 + +旗标互斥组代码事实 `scripts/ram_baseline.py:415-419`;钩子 entry 行号见逐字原文(换仓须核)。 + +### 逐字原文(未改写) + +## 权威构建后的台账回填(三个旗标,别混) + +`.map` 是内存/Flash 数字的**唯一事实源**;台账与文档里的数字由脚本从它生成——**不手抄、不手改** +(`docs/内存管理/RAM预算台账.md` 首段就写着"数字不手抄")。三份落点 = 三个旗标,一条命令只干其中一件: +`ram_baseline.py` 的 `--gate/--write/--update/--trend` 是 `add_mutually_exclusive_group()` +(`scripts/ram_baseline.py:415-419`),想干两件就得调两次。 + +| 落点 | 旗标 | 实际改了什么 | +|---|---|---| +| `scripts/ram_baseline.tsv` 趋势基线(顺带刷 `scripts/size_attestation.json` 同码凭证) | `ram_baseline.py --update` | **只**追加/覆盖当日那一行趋势(Code/RO/RW/ZI + 三区水位 + Top-10 RW+ZI)。**不碰台账正文** | +| `docs/内存管理/RAM预算台账.md` 的 `` 受管区 | `ram_baseline.py --write` | 从 .map 重渲染区域水位 + 子系统配额对照(打印「已同步台账受管区。」或「台账受管区已是最新。」) | +| `docs/内存管理/RAM使用分析与优化方案.md` 的 `` 快照区 | `check_mem_numbers.py --write` | 从**同一份** .map 重渲染内存/Flash 快照表(打印「已更新内存快照:…」) | + +**台账 §4 那句「每次 `/keil-build` 后跑 `scripts/ram_baseline.py --update`」只喂趋势行,不等于回填受管区。** +实测代价:照那句跑完 `--update` 就提交 → `mem-budget`、`mem-numbers` 两条钩子当场红。 +`mem-budget` 的 entry 是 `python scripts/ram_baseline.py --gate`(`.pre-commit-config.yaml:571`)——它在 92% 阈值之外 +还核**台账受管区与 .map 的一致性**,漂移即 `[FAIL] 台账受管区与 .map 不一致(区域水位或子系统配额表漂移)` +并打印 `修复:python scripts/ram_baseline.py --write`(`scripts/ram_baseline.py:221-224`); +`mem-numbers` 的 entry 是 `python scripts/check_mem_numbers.py --scan`(同文件 :193),不一致时打印 +`修复:运行 python scripts/check_mem_numbers.py --write`(`scripts/check_mem_numbers.py:416`)。 +改用两个 `--write` 后重提,同一笔提交触发的 26 条钩子全 Passed。 diff --git a/.dsh/skills/mem-budget/reference/backfill-order.md b/.dsh/skills/mem-budget/reference/backfill-order.md new file mode 100644 index 00000000..618c2012 --- /dev/null +++ b/.dsh/skills/mem-budget/reference/backfill-order.md @@ -0,0 +1,46 @@ +# 提交前固定顺序(自 SKILL.md 逐字外置,2026-11-18) + +## BACKFILL_ORDER + +> 路由:主文件失败索引表 `BACKFILL_ORDER` → 本节。原节 `### 提交前固定顺序`(L79–105)逐字搬移;主文件保留精简默认命令块。 + +### 判据 + +需要完整回填命令序列与退出码口径时读本节。 + +### 处置 + +按 构建 → --update → --write → check_mem_numbers --write → --gate/--scan → git add 的固定顺序执行。 + +### 证据边界 + +回填读的是盘上那份 .map,构建没落定就 --write = 写旧数字;2026-10 实测 26 条钩子全 Passed。 + +### 逐字原文(未改写) + +### 提交前固定顺序(构建 → 回填 → 真钩子提交) + +```powershell +# cwd = 项目根,一律 .venv 解释器 +# 0) 权威构建先行(0 错 0 警):回填读的是**盘上那份 .map**,构建没落定就 --write = 把旧数字写进台账,钩子照样红 +& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py + +# 1) 趋势行(纪律项,不是回填):覆盖 tsv 当日行 + 顺带刷体积同码凭证 +& '.venv\Scripts\python.exe' scripts/ram_baseline.py --update + +# 2) 回填台账受管区(mem-budget 钩子核的就是这一段) +& '.venv\Scripts\python.exe' scripts/ram_baseline.py --write + +# 3) 回填文档快照区(mem-numbers 钩子核的就是这一张表) +& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --write + +# 4) 逐字自跑提交时会跑的这两条 entry(比事后翻 pre-commit 输出快) +& '.venv\Scripts\python.exe' scripts/ram_baseline.py --gate # 0 = 阈值 + 受管区都过 +& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --scan # 0 = 快照区与 .map 一致 + +# 5) 把刚落盘的落点一并 add,然后**真钩子**提交(绝不 --no-verify、绝不手改数字) +git add docs/内存管理/RAM预算台账.md docs/内存管理/RAM使用分析与优化方案.md scripts/ram_baseline.tsv scripts/size_attestation.json +``` + +退出码:`ram_baseline.py` 0=通过或跳过 / **1=阈值超限或受管区漂移** / 2=.map 解析失败; +`check_mem_numbers.py` 0=一致 / 1=不一致、缺受管锚点或找不到事实源。 diff --git a/.dsh/skills/mem-budget/reference/backfill-pitfalls.md b/.dsh/skills/mem-budget/reference/backfill-pitfalls.md index 9089a27e..9df9ca4a 100644 --- a/.dsh/skills/mem-budget/reference/backfill-pitfalls.md +++ b/.dsh/skills/mem-budget/reference/backfill-pitfalls.md @@ -1,5 +1,23 @@ # 回填链上的坑(实测)(自 SKILL.md 外置) +## BACKFILL_PITFALLS + +> 路由:主文件失败索引表 `BACKFILL_PITFALLS` → 本节。原节(自 SKILL.md 外置)逐字保留于下。 + +### 判据 + +`--write` 说「已是最新」钩子还红、tsv 落后只 WARN、`--gate` 无 .map 却 SKIP 等回填链边界症状时读本节。 + +### 处置 + +按逐条原文处置(落点找对、SKIP≠PASS、`--map` 只换读不换写等)。 + +### 证据边界 + +均为实测(节内标注);改写型钩子当场改文件是流程不是故障。 + +### 逐字原文(未改写) + > 本文由 mem-budget 的 SKILL.md「回填链上的坑(实测)」一节逐字外置而来(渐进展开:主文件只留索引与指针)。步骤号沿用原文,未重编。 - **`--write` 说「已是最新」而钩子还红** ≠ 钩子坏了,是**落点找错了**:tsv / 台账受管区 / 文档快照区 diff --git a/.dsh/skills/mem-budget/reference/measurement-identity.md b/.dsh/skills/mem-budget/reference/measurement-identity.md index 4f991fab..c77f62c5 100644 --- a/.dsh/skills/mem-budget/reference/measurement-identity.md +++ b/.dsh/skills/mem-budget/reference/measurement-identity.md @@ -1,5 +1,23 @@ # 测量身份口径(先钉树与时刻,再看数字)(自 SKILL.md 外置) +## MEASUREMENT_IDENTITY + +> 路由:主文件失败索引表 `MEASUREMENT_IDENTITY` → 本节。原节(自 SKILL.md 外置)逐字保留于下。 + +### 判据 + +在主树跑脚本量任务树、重跑报告脚本当新测量、或 .htm/.map 与树/时刻脱钩时读本节。 + +### 处置 + +脚本按 `__file__` 定位产物(跨树换脚本);只有新 Linker run 才算新测量;身份最小格式 = tree/commit + Linker run 时刻 + 产物来源。 + +### 证据边界 + +2026-10 实测;`.htm/.map` 按约定不入库,故须把时刻写进正文/台账。 + +### 逐字原文(未改写) + > 本文由 mem-budget 的 SKILL.md「测量身份口径(先钉树与时刻,再看数字)」一节逐字外置而来(渐进展开:主文件只留索引与指针)。步骤号沿用原文,未重编。 ### 1. 脚本按 `__file__` 定位产物,不按 cwd —— 跨树必须换脚本 diff --git a/.dsh/skills/mem-budget/reference/runtime-jitter.md b/.dsh/skills/mem-budget/reference/runtime-jitter.md new file mode 100644 index 00000000..fc4422e5 --- /dev/null +++ b/.dsh/skills/mem-budget/reference/runtime-jitter.md @@ -0,0 +1,28 @@ +# 运行时峰值抖动与劣化判据(自 SKILL.md 逐字外置,2026-11-18) + +## RUNTIME_JITTER + +> 路由:主文件失败索引表 `RUNTIME_JITTER` → 本节。原节 `## 运行时峰值抖动`(L118–126)逐字搬移。 + +### 判据 + +跨启动几十 B 抖动下,「栈水位不劣于上一轮」这类判据会假红。 + +### 处置 + +二选一:≥3 次启动取最大值 + ±128 B 容差互比,或硬线改用静态最坏链、运行时峰值降趋势参考;判据一改同步正文/脚本/文档三处。 + +### 证据边界 + +uTask 连续 5 次启动 4116~4188 摆 72 B 为 2026 实测;容差量级须按本仓重测。 + +### 逐字原文(未改写) + +## 运行时峰值抖动与"算不算劣化" + +- 同一份镜像连续启动 5 次,`uiTask` 峰值实测在 4116~4188 之间摆 **72 B** ⇒ 跨启动本身就有几十 B 抖动, + "相对上一轮 +100 B"**不可归因**于被测改动。判据写成"栈水位不劣于上一轮"必然假红。 +- 可执行修法(二选一,别都留着): + 1. 同一份像**≥3 次启动取最大值**互比,并加容差(**±128 B 量级**); + 2. 硬线改用 `stack_report.py` 的**静态最坏链**,运行时峰值降级为趋势参考。 +- 判据一改要同步**所有落点**:判据正文、跑判据的脚本、记录判据的文档三处一起改,只改一处等于各说各话。 diff --git a/.dsh/skills/mem-budget/reference/shared-frame-attribution.md b/.dsh/skills/mem-budget/reference/shared-frame-attribution.md index ec6c9b12..6ca9db16 100644 --- a/.dsh/skills/mem-budget/reference/shared-frame-attribution.md +++ b/.dsh/skills/mem-budget/reference/shared-frame-attribution.md @@ -1,5 +1,23 @@ # 静态最坏链回归的归因(同涨同一数值 = 共享帧,不是调用方)(自 SKILL.md 外置) +## SHARED_FRAME + +> 路由:主文件失败索引表 `SHARED_FRAME` → 本节。原节(自 SKILL.md 外置)逐字保留于下。 + +### 判据 + +多条任务链分毫不差同涨/同降同一数值 = 共用被调帧/链接器幻影环,不在任何调用方。 + +### 处置 + +逐树逐帧比 frame size(`stack_report.py` own-frame 表锁尾段);`grep -ac 'In Cycle'` 找环;处置后抬栈或断环,改前改后各跑一次报告且「改后」落在新的 Linker run。 + +### 证据边界 + +default/net/iec104 三条 +80 B、断环后九条 −80 B 为实测;静态数是估计值(+Unknown Cycles),别当精确值上报。 + +### 逐字原文(未改写) + > 本文由 mem-budget 的 SKILL.md「静态最坏链回归的归因(同涨同一数值 = 共享帧,不是调用方)」一节逐字外置而来(渐进展开:主文件只留索引与指针)。步骤号沿用原文,未重编。 - **多条任务链分毫不差同涨/同降同一个数值**(实测 default/net/iec104 三条 +80 B;断环后九条链各 −80 B) diff --git a/.dsh/skills/mem-budget/reference/verification.md b/.dsh/skills/mem-budget/reference/verification.md new file mode 100644 index 00000000..ad207fdf --- /dev/null +++ b/.dsh/skills/mem-budget/reference/verification.md @@ -0,0 +1,31 @@ +# 验证:这轮测量算数了吗(自 SKILL.md 逐字外置,2026-11-18) + +## VERIFICATION + +> 路由:主文件失败索引表 `VERIFICATION` → 本节。原节 `## 验证`(L139–150)逐字搬移。 + +### 判据 + +提交前逐条确认报告头 Source 路径、Linker run 时刻、树身份、数字同源。 + +### 处置 + +按原文六条逐项核对;入库数字须走完整回填链且逐字自跑 --gate/--scan 各返 0。 + +### 证据边界 + +「相同时刻 = 复述」判据见逐字原文。 + +### 逐字原文(未改写) + +## 验证(这轮测量算数了吗) + +1. 报告头 `- Source:` 的相对路径落在**我要量的那棵树**下(不是裸文件名,更不是别的树); +2. `- Linker run:`(或 .htm 的 `Last Updated:` / mtime)与本轮那次构建对得上,且**不同于**上一轮那次的时刻 + ——相同就是复述,回去先做一次构建再比; +3. 树身份已按 `tree/commit + 时刻 + 产物来源` 写进提交正文/台账,而不是只留在终端输出里; +4. 结论里互比的数字必须来自**同一棵树同一次链接**;跨树比较要各自给出树与时刻; +5. 涉及劣化判定时注明依据的是静态最坏链(硬线)还是运行时峰值(趋势),并已计入跨启动抖动。 +6. 要入库的数字:本轮已按「`/keil-build` → `ram_baseline.py --update` → `ram_baseline.py --write` → + `check_mem_numbers.py --write`」回填,并逐字自跑 `ram_baseline.py --gate` 与 `check_mem_numbers.py --scan` 各返 0; + 台账 / 文档 / tsv 的改动与代码同一笔入库,**未手改数字、未用 `--no-verify`**。 diff --git a/.dsh/skills/new-machine-setup/SKILL.md b/.dsh/skills/new-machine-setup/SKILL.md index 72f28007..5922c4a5 100644 --- a/.dsh/skills/new-machine-setup/SKILL.md +++ b/.dsh/skills/new-machine-setup/SKILL.md @@ -15,6 +15,13 @@ whenToUse: 换新机器/新克隆要把环境搭起来、构建或烧录报"环 逐项 PASS/WARN/FAIL + 缺件时打印**可直接执行的修复命令**;退出码 0=可用 / 1=有 FAIL。 +**成功输出样例**(本轮实跑 `env_check.py`,`PYTHONIOENCODING=utf-8`):看到末行 `SUMMARY: OK - 环境可用` 就是环境就绪,不用再往下看。 + +```text +PASS 串口配置档案 <项目根>/.serialtest/config.json +SUMMARY: OK - 环境可用(WARN 项按提示处理) +``` + ## 搭建顺序(自检 FAIL 时的完整路径) 1. **venv**:`& <任一 python ≥3.10> -m venv .venv` → diff --git a/.dsh/skills/new-source-file/SKILL.md b/.dsh/skills/new-source-file/SKILL.md index 8f5cbf03..2282ad75 100644 --- a/.dsh/skills/new-source-file/SKILL.md +++ b/.dsh/skills/new-source-file/SKILL.md @@ -31,6 +31,14 @@ cmake --build simulator/build --config Debug # 0 警告 & '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py # BUILD_OK,0 错 0 警 ``` +**成功输出样例**(Keil 端判据串出处:`.dsh/skills/keil-build/scripts/keil_build.py` 的成功打印 `BUILD_OK: 0 errors, 0 warnings`;模拟器端为本轮实跑 `cmake --build simulator/build --config Debug` 的末行):看到 `BUILD_OK: 0 errors, 0 warnings` + `lvgl_sim.vcxproj -> ...\lvgl_sim.exe` 就是双端都通了,不用再往下看。 + +```text +UV4_RC: 0 +BUILD_OK: 0 errors, 0 warnings + lvgl_sim.vcxproj -> ...\simulator\build\Debug\lvgl_sim.exe +``` + ## 注意 - **禁止**把源文件复制进 `simulator/`——两端共用 `Drivers/BSP/` 原件(UI_界面制作流程.md C7) diff --git a/.dsh/skills/serial-assistant/SKILL.md b/.dsh/skills/serial-assistant/SKILL.md index 0e2b68a1..b61cc967 100644 --- a/.dsh/skills/serial-assistant/SKILL.md +++ b/.dsh/skills/serial-assistant/SKILL.md @@ -38,6 +38,13 @@ python -m venv ".dsh\skills\serial-assistant\venv" & $PY $TOOL selftest # 无头自检(行拆分/解码/截头/wait 判据,无需硬件) ``` +**成功输出样例**(本轮实跑 `serial_tool.py selftest`):看到 `selftest: 45/45 passed` + `SELFTEST PASS` 就是采集层自检通了,不用再往下看。 + +```text +selftest: 45/45 passed +SELFTEST PASS +``` + **抓开机日志铁律**:`open` → `clear` → 烧录/复位 → `wait-idle` → 读日志校验标记 (采集必须先于烧录,否则错过开机头几行)。 diff --git a/.dsh/skills/serial-boot-test/SKILL.md b/.dsh/skills/serial-boot-test/SKILL.md index 92f8fe34..2a8d54f5 100644 --- a/.dsh/skills/serial-boot-test/SKILL.md +++ b/.dsh/skills/serial-boot-test/SKILL.md @@ -34,26 +34,9 @@ whenToUse: 需要向目标板烧录或复位后,用串口日志自动判定运 配置解析顺序:`$DSH_SERIAL_CONFIG` > `/.serialtest/config.json` > `/.opencode/serial_config.json`(旧位置,仅串口字段)。 -若项目没有 `.serialtest/config.json`:**先从项目文档(入口文件/README/测试文档)推断各字段,推断不了的问用户**,然后按 `config.example.json` 写一份。字段含义: +若项目没有 `.serialtest/config.json`:**先从项目文档(入口文件/README/测试文档)推断各字段,推断不了的问用户**,然后按 `config.example.json` 写一份。 -| 键 | 含义 | 缺省行为 | -|---|---|---| -| `portName` / `baudRate` | 串口 | 无 portName 直接 exit 3 | -| `flash_cmd` | 烧录命令(**必须含复位运行**,如 `-Rst -Run`;可带参数) | 空 = 不烧录,脚本提示人工复位板子 | -| `hex` | 刚构建的镜像(Intel HEX),供身份戳 + 回读比对 | 空 = 两项都跳过(WARN) | -| `fw_marker` | 固件身份戳前缀(固件里打印 `"<前缀>" __DATE__ " " __TIME__`) | 默认 `fw build: `;hex 里无此串只 WARN 不假判 | -| `readback_cmd` | 回读校验命令模板,`{hex}` = 镜像路径(引号自动加) | 空 = 跳过 | -| `readback_ok` | 回读成功判据(按行首匹配,大小写不敏感) | `no difference found` | -| `required` | 必须出现的标记(`;` 分隔,大小写敏感) | **空 = exit 3**(必须给) | -| `forbidden` | 禁止出现的模式(`;` 分隔,大小写不敏感) | `FAIL;ERROR;HardFault` | -| `boot_marker` | 一轮启动的锚点子串(如 `reset cause:`) | 空 = 锚点计数关闭 | -| `max_boot_count` | 锚点出现 0 次或 >N 次 = FAIL | 1(仅 boot_marker 非空时生效) | -| `done_marker` + `max_boot_ms` | 开机耗时口径与上限 | 空/0 = 只报告不判 | -| `settle_ms` / `max_wait_ms` / `first_wait_ms` | RX 静默判据 / 总超时 / 首字节超时 | 8000 / 30000 / 12000 | -| `require_order` / `expect_reset_cause` / `require_suite_summary` | 顺序校验 / 复位原因白名单 / 套件汇总行 | 空 = 关闭 | -| `selftest_scope` | 自检台账判定口径:`this-run`(烧录前取基线,只判新增)/ `all`(累计,任一记录即 FAIL) | `this-run` | -| `ftp_user` / `ftp_pass` | 抓 `/log/selftest.log` 用的 FTP 账号(设备无匿名通道) | `admin` / `admin` | -| `require_selftest_pass` + `device_ip` | 设备侧自检台账联合判定(FTP 抓取;**默认只判本次启动新增**,抓取失败/无数据源一律 FAIL) | 关闭 | +- [ ] **config-schema** → 字段含义与缺省行为全表(`portName`/`flash_cmd`/`required`/`settle_ms`… 共 16 行),只在**首次配置或调参**时读 → [config-schema.md](reference/config-schema.md) 的 `config-schema` 节。 **先跑项目的构建**(本仓库 = `keil-build` skill,其它 Keil 项目照该 skill 套; 非 Keil 项目用项目自己的构建入口),确认 0 错误 0 警告后再进闭环。 @@ -70,25 +53,33 @@ whenToUse: 需要向目标板烧录或复位后,用串口日志自动判定运 退出码:`0=PASS` / `1=FAIL`(标记缺失或命中)/ `2=采集或烧录错误`(含回读不一致,本次运行作废)/ `3=用法/预检错误`。 +**成功输出样例**(真实产物 `docs/测试说明/测试数据/boot_log_data/20261012_B9_prod_boot_log.txt` 尾两行,本次实跑 `verify_log.py --selftest` 同为 `VERDICT: PASS`):看到 `VERDICT: PASS` + `RUN_TEST_RC=0` 就是通了,不用再往下看。 + +```text +VERDICT: PASS +RUN_TEST_RC=0 +``` + +失败时脚本打印 `RUN_TEST_ERROR` / `RUN_TEST_FAIL` / `RUN_TEST_VERDICT` 三类稳定键 → 按「失败处置索引」读同名小节。 + 产物:boot log(每行带 `[+Nms]` 相对时基)写到 `%TEMP%\serial-boot-test\boot_log_<时间戳>.txt`(`--out-dir` 改,保留最近 20 份)。 ## 第三步:判读与迭代 -- **PASS** → 报告命中的标记与开机耗时。 -- **FAIL** → `[MISS]`/`[HIT]` 行(Forbidden 命中带行号+内容)+ 日志尾部已给出;需要更多上下文直接 Read/Grep boot log 文件或 `status` 里 `log.path` 指向的 serial.log。修代码 → 重新构建 → 重跑闭环。 -- **exit 2 `no_data`** → 板子全程零字节:查端口在位(`ports`)、板电、烧录命令是否真的复位了目标。 +- **PASS** → 报告命中的标记与开机耗时(看到 `VERDICT: PASS` + `RUN_TEST_RC=0` 就是通了,不用再往下看)。 +- **FAIL / exit 2** → `[MISS]`/`[HIT]` 行(Forbidden 命中带行号+内容)+ 日志尾部已给出;需要更多上下文直接 Read/Grep boot log 文件或 `status` 里 `log.path` 指向的 serial.log。脚本会打印 `RUN_TEST_*` 索引键 → 按下表读对应小节再修代码 → 重新构建 → 重跑闭环。 ## 交互式串口调试(不跑闭环时) 用 **`serial-assistant` skill**(`ports/open/send/log/clear/wait-idle/status` 全套命令、 抓开机日志铁律、daemon 陷阱都在那边)。本 skill 不重复采集层用法。 -## 陷阱(都是实测教训) +## 失败处置索引(退出码 / 脚本输出前缀 → 同名小节) -- **daemon 一台机只有一个**(HTTP 口 18765 独占绑定,由采集层 serial-assistant 管理)。改配置后必须 `restart`(daemon 启动时缓存配置)。若机器上还有旧 daemon,先 `status` 看 `daemon.version`(serial-assistant 版 = `1.1.0-skill`)确认归属,必要时 `stop` 后重开。 -- **回读校验排在日志采集之后**:部分烧录工具(如 ST-LINK `-CmpFile`)连接时会复位目标,提前跑会截断开机日志。脚本已按此顺序,勿手工调换。 -- **烧录命令必须让目标复位运行**(裸 `-P` 类写入在目标核死循环时不落地);写完镜像后 `fw build` 身份戳校验会揭穿"芯片还是旧镜像"。 -- **`settle_ms` 必须大于固件的自然静默间隙**(常见 3~4s),默认 8000;日志被截断先调大它。 -- **Required 标记宁少勿多**:先用启动锚点 + 少数里程碑标记;按用例临时覆盖 `--forbidden`(预期出现的 `[ERR]` 负路径用例)。 -- **烧录与串口采集不冲突**:SWD 下载走探针、调试日志走 USB-serial(CH340 类),互不占用;烧录期间串口侧静默几秒属正常,不算 `no_data`(首字节门会兜住)。 -- 中文/编码:脚本全程字节级处理,不受控制台代码页影响;配置文件存 UTF-8(BOM 容忍)。 +闭环失败时脚本会自己打印稳定索引键;按该键到 [troubleshooting.md](reference/troubleshooting.md) 读**同名小节**(每节 = 判据 / 处置 / 证据边界)。正常路径不展开。 + +| 失败信息自带索引键 | 何时读(触发条件) | 去哪 | +|---|---|---| +| `RUN_TEST_ERROR` | 打印 `RUN_TEST_ERROR:` 前缀 = 环境/采集/用法错,本次运行作废 | `troubleshooting.md` 的 `RUN_TEST_ERROR` 节 | +| `RUN_TEST_FAIL` | 打印 `RUN_TEST_FAIL:` 前缀 = 采到了但标记判定失败 | `troubleshooting.md` 的 `RUN_TEST_FAIL` 节 | +| `RUN_TEST_VERDICT` | 汇总行 `RUN_TEST_VERDICT: FAIL` 或 `RUN_TEST_RC=` 非 0 | `troubleshooting.md` 的 `RUN_TEST_VERDICT` 节 | diff --git a/.dsh/skills/serial-boot-test/reference/config-schema.md b/.dsh/skills/serial-boot-test/reference/config-schema.md new file mode 100644 index 00000000..f11a0a6c --- /dev/null +++ b/.dsh/skills/serial-boot-test/reference/config-schema.md @@ -0,0 +1,31 @@ +# 项目档案字段表(自 SKILL.md「第一步:项目档案」逐字外置) + +> 何时读:**每个项目只配一次** `.serialtest/config.json` 时读它;日常跑闭环不需要展开。 +> 主文件保留配置解析顺序与"先构建、字段推断不了问用户"的约束;本节只有字段含义表。 + +## config-schema + +**判据(字段齐全)**:配置解析顺序:`$DSH_SERIAL_CONFIG` > `/.serialtest/config.json` > `/.opencode/serial_config.json`(旧位置,仅串口字段)。若项目没有 `.serialtest/config.json`:先从项目文档(入口文件/README/测试文档)推断各字段,推断不了的问用户,然后按 `config.example.json` 写一份。字段含义(逐字来自原表): + +| 键 | 含义 | 缺省行为 | +|---|---|---| +| `portName` / `baudRate` | 串口 | 无 portName 直接 exit 3 | +| `flash_cmd` | 烧录命令(**必须含复位运行**,如 `-Rst -Run`;可带参数) | 空 = 不烧录,脚本提示人工复位板子 | +| `hex` | 刚构建的镜像(Intel HEX),供身份戳 + 回读比对 | 空 = 两项都跳过(WARN) | +| `fw_marker` | 固件身份戳前缀(固件里打印 `"<前缀>" __DATE__ " " __TIME__`) | 默认 `fw build: `;hex 里无此串只 WARN 不假判 | +| `readback_cmd` | 回读校验命令模板,`{hex}` = 镜像路径(引号自动加) | 空 = 跳过 | +| `readback_ok` | 回读成功判据(按行首匹配,大小写不敏感) | `no difference found` | +| `required` | 必须出现的标记(`;` 分隔,大小写敏感) | **空 = exit 3**(必须给) | +| `forbidden` | 禁止出现的模式(`;` 分隔,大小写不敏感) | `FAIL;ERROR;HardFault` | +| `boot_marker` | 一轮启动的锚点子串(如 `reset cause:`) | 空 = 锚点计数关闭 | +| `max_boot_count` | 锚点出现 0 次或 >N 次 = FAIL | 1(仅 boot_marker 非空时生效) | +| `done_marker` + `max_boot_ms` | 开机耗时口径与上限 | 空/0 = 只报告不判 | +| `settle_ms` / `max_wait_ms` / `first_wait_ms` | RX 静默判据 / 总超时 / 首字节超时 | 8000 / 30000 / 12000 | +| `require_order` / `expect_reset_cause` / `require_suite_summary` | 顺序校验 / 复位原因白名单 / 套件汇总行 | 空 = 关闭 | +| `selftest_scope` | 自检台账判定口径:`this-run`(烧录前取基线,只判新增)/ `all`(累计,任一记录即 FAIL) | `this-run` | +| `ftp_user` / `ftp_pass` | 抓 `/log/selftest.log` 用的 FTP 账号(设备无匿名通道) | `admin` / `admin` | +| `require_selftest_pass` + `device_ip` | 设备侧自检台账联合判定(FTP 抓取;**默认只判本次启动新增**,抓取失败/无数据源一律 FAIL) | 关闭 | + +**处置**:按表逐字段填好,再回主文件「先跑项目的构建」→「跑闭环」。字段缺省行为已经写全,不要凭印象另设默认。 + +**证据边界**:本表逐字外置自原 SKILL.md,缺省值是脚本当时的行为;脚本若改了默认,以脚本为准(本表不自动同步脚本语义)。 diff --git a/.dsh/skills/serial-boot-test/reference/troubleshooting.md b/.dsh/skills/serial-boot-test/reference/troubleshooting.md new file mode 100644 index 00000000..8bd7ed83 --- /dev/null +++ b/.dsh/skills/serial-boot-test/reference/troubleshooting.md @@ -0,0 +1,37 @@ +# 串口闭环失败处置(自 SKILL.md「陷阱」一节逐字外置) + +> 何时读:闭环退出码非 0,或脚本打印 `RUN_TEST_ERROR` / `RUN_TEST_FAIL` / `RUN_TEST_VERDICT: FAIL` 时。 +> 主文件的失败索引表按这三个稳定前缀指向这里;正常路径不要展开本篇。 + +## RUN_TEST_ERROR + +**判据**:`run_boot_test.py` 打印 `RUN_TEST_ERROR:` 前缀(配置解析失败、无 `--port`/无 `required`、open/clear/wait-idle/log 采集失败、`no_data`、回读不一致等)。这些是**环境/采集/用法错**,本次运行作废,不是标记判定结果。 + +**处置**:逐条对照原「陷阱」清单: + +- **daemon 一台机只有一个**(HTTP 口 18765 独占绑定,由采集层 serial-assistant 管理)。改配置后必须 `restart`(daemon 启动时缓存配置)。若机器上还有旧 daemon,先 `status` 看 `daemon.version`(serial-assistant 版 = `1.1.0-skill`)确认归属,必要时 `stop` 后重开。 +- **回读校验排在日志采集之后**:部分烧录工具(如 ST-LINK `-CmpFile`)连接时会复位目标,提前跑会截断开机日志。脚本已按此顺序,勿手工调换。 +- **烧录命令必须让目标复位运行**(裸 `-P` 类写入在目标核死循环时不落地);写完镜像后 `fw build` 身份戳校验会揭穿"芯片还是旧镜像"。 +- **`settle_ms` 必须大于固件的自然静默间隙**(常见 3~4s),默认 8000;日志被截断先调大它。 +- **烧录与串口采集不冲突**:SWD 下载走探针、调试日志走 USB-serial(CH340 类),互不占用;烧录期间串口侧静默几秒属正常,不算 `no_data`(首字节门会兜住)。 + +**证据边界**:以上为实测教训,不替代 `RUN_TEST_ERROR:` 行本身给出的具体原因;端口/板电问题须先查 `ports`、板电、烧录命令是否真的复位目标。`no_data`(板子全程零字节)按采集层排查。 + +## RUN_TEST_FAIL + +**判据**:`run_boot_test.py` 打印 `RUN_TEST_FAIL:` 前缀——标记判定侧的失败(如要求自检台账判定却无 `device_ip` 也无 `--selftest-log`、自检台账抓取失败)。此时日志已采到,判定结果为 FAIL。 + +**处置**:按失败行补齐数据源(提供 `device_ip` 或 `--selftest-log`)或修正标记配置;修完重新闭环。`RUN_TEST_FAIL` 与 `RUN_TEST_ERROR` 的区别:前者是"采到了但判失败",后者是"没采成、运行作废"。对应主文件索引键 `RUN_TEST_FAIL`。 + +**证据边界**:自检台账默认按 `this-run`(只判本次启动新增)口径;抓取失败或缺数据源一律 FAIL 而非 PASS,不要把"没数据"当"设备干净"。 + +## RUN_TEST_VERDICT + +**判据**:闭环汇总行 `RUN_TEST_VERDICT: FAIL` 或 `RUN_TEST_RC=`(非 0)——整轮判定收口。配套原「陷阱」条目: + +- **Required 标记宁少勿多**:先用启动锚点 + 少数里程碑标记;按用例临时覆盖 `--forbidden`(预期出现的 `[ERR]` 负路径用例)。 +- 中文/编码:脚本全程字节级处理,不受控制台代码页影响;配置文件存 UTF-8(BOM 容忍)。 + +**处置**:`RUN_TEST_RC=1` 时看上方 `[MISS]`/`[HIT]` 行(Forbidden 命中带行号+内容)+ 日志尾部定位;`RUN_TEST_VERDICT: FAIL —— 自检台账判定未能执行` 时按 `run_test_fail` 处置。`RUN_TEST_RC=0` 且 `VERDICT: PASS` 才算通。 + +**证据边界**:`RUN_TEST_VERDICT: FAIL` 只是汇总,根因在上面各 `[MISS]`/`[HIT]`/`RUN_TEST_*` 行;本节点不重复标记校验判据(那在 `verify_log.py` 侧)。 diff --git a/.dsh/skills/stale-doc-count-sweep/SKILL.md b/.dsh/skills/stale-doc-count-sweep/SKILL.md index c577889b..7ed5086e 100644 --- a/.dsh/skills/stale-doc-count-sweep/SKILL.md +++ b/.dsh/skills/stale-doc-count-sweep/SKILL.md @@ -57,17 +57,6 @@ whenToUse: 某个计数/数字变了要跨 md/yaml/py/txt 同步、用户说「 - 新写文本撞编号门禁 > 本节全文(逐字搬移、未改写,含命令与实测数字)→ [pitfalls.md](reference/pitfalls.md)。动手前先读那篇。 -## Verification +## 收口验收(只在提交前打勾/回报时读) -提交前逐条打勾;回报时**逐处列文件 + 命中数断言**,不要笼统说「已全部更新」。 - -- [ ] 每个数都写了**两个独立来源**且数值一致(`ref/shot_*.bin` 实数 = `PAGES` 条目数;`UI_PAGE_MAP_COUNT` = 剔伪命中后的 `#page=` 计数),并在结论里贴出该数字与伪命中取舍理由 -- [ ] 字形数说明**是否剔除 notdef**并给出条目数→字形数的换算(条目数 − 1 = 字形数,2026-10-29 现值 320 − 1 = 319);字数说明**是否含 ASCII**,且该口径句与实测一致 -- [ ] 分类表逐条列出:改了哪些当前态、哪些历史行保留、哪些误报不动(附理由)、哪些只加「当时」、哪些属**口径错**并已另起一笔 -- [ ] 替换脚本打印了每处 `old -> new xN` 且每处 `assert` 通过(无半落地;报错时已 `git diff --stat` 确认零写入) -- [ ] 命中面覆盖 `.pre-commit-config.yaml` 钩子 `name:`、`AGENTS.md`(钩子数等入口级计数)、`docs/**`、`scripts/**`、`.dsh/skills/*/SKILL.md`,逐条在改动清单里出现 -- [ ] 被改文件已全文通读,同文档各小节与配套 README/清单的顺序、计数、完成状态一致;口径闭合(如 `未绑 = 待做 + 不做`) -- [ ] 变更记录:**保留的 5 篇真台账**(清单 → `docs/文档规范.md` §5.1)历史行原文未动;其余文档本轮**零新增流水行**(当前态改完即止);钩子一增一减这类过程细节写进提交正文,不写进文档 -- [ ] **提交后**又按全部旧形态复扫一次,当前态残留 = **0**,每条剩余命中都能归类(历史行 / 误报 / 已加「当时」);发现的漏网当前态已单独补一笔 -- [ ] `check_doc_links.py --all --sections-strict` 打印「文档路径检查通过(N 个文档)」;`ci_local.py` / `pre-commit` 全绿(RC=0、`failed=0`);BOM 与原文件一致、无 `EF BF BD` -- [ ] 分笔提交完成,回报 commit 号 + 每笔改了哪些文件 + 没动的那几类及理由 +- [ ] **verification** → 提交前逐条打勾的 10 项验收清单 + 回报口径(逐处列文件 + 命中数断言)→ 读 [verification.md](reference/verification.md) 的 `verification` 节。 diff --git a/.dsh/skills/stale-doc-count-sweep/reference/verification.md b/.dsh/skills/stale-doc-count-sweep/reference/verification.md new file mode 100644 index 00000000..0958b06e --- /dev/null +++ b/.dsh/skills/stale-doc-count-sweep/reference/verification.md @@ -0,0 +1,23 @@ +# 收口验收清单(自 SKILL.md「Verification」一节逐字外置) + +> 何时读:提交前逐条打勾、回报验收时。主文件只留一行索引;动手扫描/替换过程中不要展开本篇。 +> 「各计数的权威口径速查」大表留在主文件——每次动手都要对表,不属于长尾。 + +## verification + +**判据(逐条打勾)**:以下 10 条来自原 SKILL.md「Verification」节,逐字保留、未改写。回报时**逐处列文件 + 命中数断言**,不要笼统说「已全部更新」。 + +- [ ] 每个数都写了**两个独立来源**且数值一致(`ref/shot_*.bin` 实数 = `PAGES` 条目数;`UI_PAGE_MAP_COUNT` = 剔伪命中后的 `#page=` 计数),并在结论里贴出该数字与伪命中取舍理由 +- [ ] 字形数说明**是否剔除 notdef**并给出条目数→字形数的换算(条目数 − 1 = 字形数,2026-10-29 现值 320 − 1 = 319);字数说明**是否含 ASCII**,且该口径句与实测一致 +- [ ] 分类表逐条列出:改了哪些当前态、哪些历史行保留、哪些误报不动(附理由)、哪些只加「当时」、哪些属**口径错**并已另起一笔 +- [ ] 替换脚本打印了每处 `old -> new xN` 且每处 `assert` 通过(无半落地;报错时已 `git diff --stat` 确认零写入) +- [ ] 命中面覆盖 `.pre-commit-config.yaml` 钩子 `name:`、`AGENTS.md`(钩子数等入口级计数)、`docs/**`、`scripts/**`、`.dsh/skills/*/SKILL.md`,逐条在改动清单里出现 +- [ ] 被改文件已全文通读,同文档各小节与配套 README/清单的顺序、计数、完成状态一致;口径闭合(如 `未绑 = 待做 + 不做`) +- [ ] 变更记录:**保留的 5 篇真台账**(清单 → `docs/文档规范.md` §5.1)历史行原文未动;其余文档本轮**零新增流水行**(当前态改完即止);钩子一增一减这类过程细节写进提交正文,不写进文档 +- [ ] **提交后**又按全部旧形态复扫一次,当前态残留 = **0**,每条剩余命中都能归类(历史行 / 误报 / 已加「当时」);发现的漏网当前态已单独补一笔 +- [ ] `check_doc_links.py --all --sections-strict` 打印「文档路径检查通过(N 个文档)」;`ci_local.py` / `pre-commit` 全绿(RC=0、`failed=0`);BOM 与原文件一致、无 `EF BF BD` +- [ ] 分笔提交完成,回报 commit 号 + 每笔改了哪些文件 + 没动的那几类及理由 + +**处置**:任一条未打勾就补齐证据或修正后再回报;不要带着未闭环项声称「已全部更新」。 + +**证据边界**:本篇是**收口判据**,真值来源与伪命中换算以主文件「各计数的权威口径速查」表为准;表中数字是 2026-10-29 / 2026-11-16 实测快照,新一轮动手要先按 steps 篇重测,不可照抄。 diff --git a/.dsh/skills/stlink-flash/SKILL.md b/.dsh/skills/stlink-flash/SKILL.md index 09ed4c2c..49c847b4 100644 --- a/.dsh/skills/stlink-flash/SKILL.md +++ b/.dsh/skills/stlink-flash/SKILL.md @@ -21,6 +21,16 @@ whenToUse: 需要向 STM32 目标烧录 .hex/.bin、只复位重启目标、校 镜像缺省取项目档案 `hex`;ST-LINK_CLI 解析:`--cli` > 档案 `stlink_cli` > `$DSH_STLINK_CLI` > `$DTU_STLINK_CLI` > PATH(**显式设了但无效 = 立即报错,不回退**)。 退出码:`0`=OK / `1`=探针或目标错误 / `2`=CLI 未找到 / `3`=用法。 + +**成功输出样例**(本轮实跑 `stlink_flash.py list`;flash/cmp 判据串来自脚本内置判据与 `docs/子系统设计/故障录波设计说明.md` 实测记录):看到探针 `SN:` 行即 `list` 通;烧录看 `Programming Complete`、回读看 `No difference found` 即为真写入,不用再往下看。 + +```text +--- Available ST-LINK Probes List --- +ST-LINK Probe 0: + SN: 0B250D12A218303030303032 + FW: V2J37S7 +``` + 成功判据内置:flash = rc0 + `Programming Complete`;cmp = 行首 `No difference found` (输出原样透传,serial-boot-test 的 `readback_ok` 默认值直接可用)。 diff --git a/.dsh/skills/task-worktree/SKILL.md b/.dsh/skills/task-worktree/SKILL.md index ecc36568..ac2b6d87 100644 --- a/.dsh/skills/task-worktree/SKILL.md +++ b/.dsh/skills/task-worktree/SKILL.md @@ -8,175 +8,99 @@ whenToUse: >- # task-worktree — 多任务并行开发空间(`@task` 仅为文档别名;DSH 显式调用 `/task-worktree`;可执行形态见「固定命令」) - **执行体** = `.dsh/skills/task-worktree/scripts/task_worktree.py`(纯标准库;拷整个 skill 目录即可换项目用)。 -- **深规程全文在 reference/ 下:做 C2 / D / E / F / G 任何一条之前先把对应那篇读完**——本文只留判得出来「要不要读」的判据。 -- 为什么这么拆:本文件受 dsh-mnemon 写侧上限 **65536 字节**(`skill-size` 钩子 49152 告警;实测 72,601 字节的技能照常可读可提交,只是自进化每次「生成草案」被拒、永久卡在「生成中」)→ **新增深规程进 reference/,本文只加判据**。瘦身前 frontmatter 原文 → [frontmatter-history.md](reference/frontmatter-history.md)。 +- **深规程全文在 reference/ 下**:命中「失败了 → 去哪读」表的键才去读对应那篇,正常路径不必展开。 +- 本文件受 dsh-mnemon 写侧上限 65536 字节(`skill-size` 钩子 49152 告警)→ 新增深规程进 reference/,本文只加判据与索引。瘦身前 frontmatter 原文 → [frontmatter-history.md](reference/frontmatter-history.md)。 -## 症状 → 去哪一节 - -| 现场 / 目标 | 去 | -|---|---| -| 开新树 / 看全景 / 追平主干 / 放弃任务 | 固定命令、典型流程 | -| `new` 报「已有 8 个活跃任务(上限 8)」 | **A** | -| `lock release` 报「任务 X 不存在(缺台账)」,锁照旧挂着 | **B** | -| `done` 做了什么、红了怎么补绿、能不能反悔、怎么算「真完成」 | **C** | -| `done` 报「主工作树不干净」,而那份脏是别的会话/插件留的 | **C2** → [merge-dirty-main-tree.md](reference/merge-dirty-main-tree.md) | -| 门禁指标异常增长要逐文件归因(主树全程只读) | **D** → [clean-room-measure.md](reference/clean-room-measure.md) | -| `list` 台账里没有的树要回收 / detached / 有在飞内容 / 悬挂台账 | **E** → [reclaim-unregistered.md](reference/reclaim-unregistered.md) | -| 插件树缺联接、锁归属 `pw:`、「有插件为何还自持生命周期」 | **F** → [dsh-plugin-bridge.md](reference/dsh-plugin-bridge.md) | -| 树内写门禁输出 ENOENT、`--all` 假红、写提交/合并信息、字节体检 | **G** → [gates-in-tree.md](reference/gates-in-tree.md) | -| 收工前树内自查、或合并后体积凭证/台账红了想一条命令补绿 | `precheck` / `postmerge`(固定命令表 + C 节第 5~6 步) | -| 退出码读到 0 其实是 2、`tail` 之后误判「有冲突」 | 读输出 | -| 谁不许跑 `done`/`abort`、清场前必做什么、任务期哪些文件不许改 | 铁律 1–9 | -| 收工前最后一遍自查(各节该留什么证据)/全部实测坑 | [verification.md](reference/verification.md) / [pitfalls.md](reference/pitfalls.md) | - -## 固定命令 +## 默认路径:一条命令跑通 ```bash PY=".venv/Scripts/python.exe"; TW=".dsh/skills/task-worktree/scripts/task_worktree.py" -"$PY" "$TW" <子命令> [参数] # PowerShell:& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" <子命令>(cwd = 仓库根或任意子目录) +"$PY" "$TW" <子命令> [参数] # PowerShell:& $PY ".dsh\\skills\\task-worktree\\scripts\\task_worktree.py" <子命令>(cwd = 仓库根或任意子目录) ``` | 命令 | 作用 | |---|---| -| `bench-gate ` | 检查指定分支是否有 bench-pass 记录(存储于 `.agents/worktrees/.bench-pass-log`) | -| `merge ` | 在主树执行编排式合并:bench-gate → 预演 → 合并(`--skip-bench` 跳过台架检查) | +| `bench-gate ` | 检查指定分支是否有 bench-pass 记录(存于 `.agents/worktrees/.bench-pass-log`) | +| `merge ` | 主树编排式合并:bench-gate → 预演 → 合并(`--skip-bench` 跳过台架检查) | | `list` | 分支 / 落后领先 / 脏文件数 / 台架状态 + 两把锁归属。**只遍历台账** → 非登记树看不见(E 节) | | `status ` | 未提交清单、相对基线漂移、台架记录、已建联接 | | `sync ` | 在任务树里 `rebase` 追平主干,把冲突留在任务分支上 | -| `lock acquire|release|status ` | 独占资源锁(→ 铁律 3、B 节) | -| `plugin list|adopt|unadopt [插件树名]` | 插件桥:看清单 / 补共享联接 / 摘联接(**不删树**)→ F 节 | +| `lock acquire\|release\|status ` | 独占资源锁(→ 铁律 3、B 节) | +| `plugin list\|adopt\|unadopt [插件树名]` | 插件桥:看清单 / 补共享联接 / 摘联接(**不删树**)→ F 节 | | `done ` | **[DEPRECATED]** 已废弃,请用 `merge`。预演 → 合入主干 → 审计 → 重生成 → 门禁 → 清场 | -| `precheck` | 树内自查(**只读**):BOM 漂移 / CR / U+FFFD + docs 逐档门禁 + `--msgfile --ban` 消息检查;顺手补 `ci-artifacts/`(G 节机械项) | -| `postmerge` | 主树合并后补绿:体积凭证**自动诊断**(新鲜跳过;红→先短链 `--update`,只读复检真漂了才升全链)+ `check_doc_links --all` + 列待提交文件,**不代提交** | +| `precheck` | 树内自查(**只读**):BOM 漂移 / CR / U+FFFD + docs 逐档门禁 + `--msgfile --ban` 消息检查;顺手补 `ci-artifacts/`(G 节) | +| `postmerge` | 主树合并后补绿:体积凭证**自动诊断**(新鲜跳过;红→短链 `--update`,只读复检真漂了才全链)+ `check_doc_links --all` + 列待提交文件,**不代提交** | -- **退出码** `0` 成功 / `1` 操作失败 / `2` 前置或环境错误 / `3` 用法——**只有不接管道才读得到**(→ 读输出)。 -- `bench-gate`:无参数选项。检查 `.agents/worktrees/.bench-pass-log` 中是否有该分支的记录。 -- `merge`:`--skip-bench`(跳过 bench-gate 检查)。合并后不自动删除任务分支和目录。 -- `done` **[DEPRECATED]**:`--dry-run` · `--skip-build` · `--skip-gates` · `--force`。⚠ 已废弃,请用 `merge`。 -- `lock`:`--task`(acquire 必填)· `--wait <秒>` · `--ttl <小时>`(默认 `build`=1h / `bench`=6h,超期视为陈旧、下次 acquire 自动接管)· `--note` · `--bench-pass` · `--force`。⚠ `--note` 只在 **acquire** 写进 payload,**release 时被忽略** → 验收证据写主干提交说明或文档。`--bench-pass` 现在同时写入 `.agents/worktrees/.bench-pass-log`。 -- 环境变量:`DTU_WT_ROOT`(默认仓库同级 `_wt/`)· `DTU_TASK_BASE`(默认基线)· `DTU_INTEGRATION_WORKTREE`(集成点,用于隔离演练)。 - -## 典型流程 +**典型流程**(新模型:DSH 插件 `create_worktree` 建树,再用 bench-gate + merge 收口): ```bash -# 新模型:使用 DSH 插件 create_worktree 建树,然后用 bench-gate + merge 收口 -# (create_worktree 由 DSH 插件提供,不在本脚本内) - -# 台架验证后记录 bench-pass(lock release --bench-pass 自动写入 .bench-pass-log) "$PY" "$TW" lock acquire bench --task pw:my-task -"$PY" "$TW" lock release bench --task pw:my-task --bench-pass - -# 合并前检查台架验收 +"$PY" "$TW" lock release bench --task pw:my-task --bench-pass # 自动写 .bench-pass-log "$PY" "$TW" bench-gate task/my-task # 有记录返回 0,无记录返回 1 - -# 在主树执行合并(自动检查 bench-gate,--skip-bench 可跳过) -"$PY" "$TW" merge task/my-task # 必须在主工作树执行 +"$PY" "$TW" merge task/my-task # 必须在主工作树执行(自动检查 bench-gate) ``` -## 读输出:管道与截断(两起误判的共同根因) +## 成功输出(默认路径跑通的样子) -1. **`| tail -N` 之后的退出码是 `tail` 的,恒 0** → 脚本的 1/2 全被吞(实测三条「rc=0」真码都是 2)。判据先看文本(`[ok]` / `!!` / `前置/环境错误:` / `失败:`),要真码就**不接管道**或取 `${PIPESTATUS[0]}`。 -2. **`done` 的输出别 `tail -2`**:管道下 python stdout 块缓冲、git 子进程 stderr 不缓冲,两股流错位 → 只剩尾部那句「--dry-run:到此为止…」加带 `conflict` 字样的 stderr 片段,据此误判「有冲突」。dry-run 全文 5~8 行,**读全量**。 - -## 分步操作(节号 A–G/C2、各节步骤号与铁律编号被 reference/ 与 docs 引用,**不许重排**) - -### A. `new` 撞并发上限 → 腾位 - -1. 认原文 `前置/环境错误:已有 8 个活跃任务(上限 8);先 done/abort,或加 --force`(exit 2)。「活跃」= `_wt/.state/.json` 在且台账 `path` 目录还在 → **手工删目录不占名额、但留悬挂台账**(E 第 6 步)。 -2. `$TW list` 定谁让位:**已完成的先 `done`**(合并回收一步不省)。 -3. 无人认领、零提交、未 claim 的空闲树 → `abort `;有未提交或有提交时脚本会拒,确认可弃才 `--force`。 -4. 真要第 9 棵才 `--force`:并行度上去,**冲突面与台架排队一起上去**(每棵磁盘代价见铁律 6)。 -5. **别用手工 `git worktree remove` 给登记任务腾位**:台账不删(同 ID 报「任务已存在」)、又绕过「先摘联接」(铁律 5),有让 git 递归进联接删掉主树 `.venv` 的风险。要回收的是**非登记树**(`list` 里没有它)→ **E 节**。 -6. 复验:`list` 条目数 == `ls _wt` 目录数,再 `new`。 - -### B. 非登记持有者的锁放不掉 - -症状:`lock release bench --task acceptwin --bench-pass`(带 `--force` 同)报 `前置/环境错误:任务 acceptwin 不存在(缺台账 _wt/.state/acceptwin.json)`,**锁照旧挂着**。根因:`release` 带 `--bench-pass` 就先 `load_state(task)`,而 `acquire` 侧不查台账 → 「释放」被「记账」挡死;锁没放,`done` 的 `release_stale_locks()` 对未到 TTL 的活锁判失败 → **一个没登记的名字挡住所有任务收口**。 - -**2026-10-29 已修**:无台账降级为 `[warn] …跳过 PASS 记录,仅释放锁`,**不再需要手写占位台账**。 -1. `$TW lock status` 认现场(持有者 / pid / 已持有 / TTL)——别对同一句报错反复重试。 -2. `$TW lock release --task [--bench-pass]` 直接放;PASS 记不上会 warn,锁照放。 -3. **PASS 后面还要用**(`done` 只认台账 `bench_pass`)→ 从一开始就用已 `new` 的 ID 占锁,或把结论写进主干提交/文档。插件树 `pw:` 天然无台账 → F 节。 -4. 最后手段:锁 = `_wt/.state/locks/.lock` 的单行 JSON(`name/task/pid/host/epoch/at/note/ttl`),`release` 就是 unlink 它——手工删 = 不记 PASS 的强制释放,前面各步都不可用才做。**早期为绕坑手写的占位台账现在有害**(既占上限名额又被 `list` 当任务)→ E 第 6 步备份后删。 - -### C. `done `:它是合并点,不是查看器 - -1. **合并前确认属主提交完**:`$TW status ` 看未提交与领先数,跨会话再问属主一句。实测教训:属主还剩「2/2」没提交就 `done` → 只含 1/2 的分支进了主干,只能另开一棵树补后半(自己的时序错,不是分支问题)。 -2. 先 `--dry-run` 且**读全量**。判据两行:`[ok] 前置检查通过(领先 共 N 个提交)` + `[ok] 无冲突,预演结果树 `;**N 必须等于属主应交的提交数**,对不上回第 1 步。 -3. 正式 `$TW done `——**必须在主工作树**(铁律 1)。 -4. 见 `!! 门禁未全绿` 时,`done` 现在会**自动调 `postmerge` 补绿**(体积凭证 + RAM 台账 + 文档全库)。补绿成功且有回填文件时列出待提交清单;补绿失败才保留工作树等你手动排查。紧跟的 `主干已含合并提交 ` 说明**合并已落主干**。 - - ✅ 自动补绿成功后按提示提交回填文件,再重跑 `done` 完成清场。 - - ❌ **绝不用 `reset --hard `**——那是丢弃已入库的合并提交,且 `reset --hard` 是项目级 Never(连未提交工作一起丢)。 -5. **`done` 现在自动完成整条补绿链**:regen(任务表 + 内存快照 + RAM 台账)→ build → ci → postmerge(凭证诊断 + 文档全库)。门禁通过后若 postmerge 产生回填文件,会列出待提交清单等你确认后再清场。 - 手工补绿链仍保留为权威兜底(`postmerge` 内部逻辑等价于下面的步骤): - -```bash -"$PY" scripts/check_mem_numbers.py --write # 台账受管区 ↔ 新 .map 对齐 -"$PY" scripts/ram_baseline.py --update # 趋势基线追加一行 -"$PY" scripts/ram_baseline.py --write # RAM 快照 / 92% 预算台账 -"$PY" scripts/check_test_coverage.py --update-baseline # 覆盖率基线(新单测 / 新套件时必刷) -"$PY" scripts/check_doc_links.py --all # 文档链接与章节引用 -git add <上面刷出来的基线/快照文件> # 显式列文件,别 -A 把别人在飞的改动一起提交 -git commit -F # 提交属 Ask first(入口文件「边界」节) +``` +[ok] 分支 task/my-task 有 bench-pass 记录 +[ok] bench-gate 通过(2026-11-18T…) +=== 合并预演(git merge --no-ff --no-commit)=== +[ok] 合并完成() ``` - **`--dry-run` 新增台账碰撞预检**:双方都改过的已知生成文件(`ram_baseline.tsv` / `size_attestation.json` / RAM 台账 md)会在预演阶段提前警告,让你知道合并后需要 postmerge 重算。 -6. **重跑 `done` 前主树必须干净**,否则 `失败:主工作树不干净(…)——合并会把未提交改动卷进来` → 第 5 步产物先提交。分支已并时重跑打印 `[i] task/- 已合入 ,跳过合并,直接清场`——**该路径在门禁之前就返回,不会替你复绿**:上一次门禁没跑到的尾巴(主树 `ci_local.py` + `check_doc_links.py --all`;体积/文档那半可 `postmerge` 一把跑)必须自己补。主树脏且那份脏不是你的 → **C2**。 -7. 清场后再敲一次 `done ` 得 `前置/环境错误:任务 不存在(缺台账 …json)`(exit 2)——**不是失败**:清场最后一步 unlink 了台账。**判完成以 `git log` 为准**。 +`merge` 预演阶段的 `done` 对应输出为 `[ok] 前置检查通过(领先 共 N 个提交)` + `[ok] 无冲突,预演结果树 `——`N` 必须等于属主应交提交数。 -### C2. `done` 被「主工作树不干净」挡住,而那份脏是**别的并发会话**留的 +## 失败了 → 去哪读(索引表) -- **不许**对它做 stash / checkout / reset / 提交 / 删除(项目级 Never,你不知它写没写完)。`done` 要求主树干净 → 合并与回收一起被挡,**那是保护不是工具坏了**。 -- 正解六步,编号与 [reference/merge-dirty-main-tree.md](reference/merge-dirty-main-tree.md) 第 1~6 步一一对应(每步的确切命令与判据在那篇):**取证**(mtime + diff 定性有无交集,顺带 `worktree list` 看有无别人中途新建的树)→ **预演** `git merge-tree --write-tree `(打出结果树 sha 且 RC=0)→ **主树手工合并** `git merge --no-ff --no-edit -F ci-artifacts/merge-msg-.txt ` → **对账**(合并后 blob id 与 stat 同合并前存值逐项一致)→ **备份台账** `cp .json .json.state-bak` 后让 `done` 自己摘联接拆树 → **复验** `worktree list` + `lock status`。 -- **blob id 变了 = stash pop 半冲突**:立刻停止收工,把两份 blob id 与 diff 交给该文件属主,绝不 `checkout` 抹平。 -- **报告要点名**:绕开 `done` 的理由 + 补回它的证据(预演 sha 与 RC、blob 对账、主树全库 `check_doc_links.py --all`、两把锁空闲)+ 那份外部脏文件与中途冒出来的第二棵树(谁的、你没动它的证据)。合并信息也过 G 的禁词自检;「这份脏通常是谁」见陷阱清单。 +失败信息自带稳定键;命中才读对应小节(每节 = 判据 / 处置 / 证据边界 + 逐字原文): -### D. 门禁指标异常增长 → 净室逐文件归因(主树全程只读) +| 键(脚本真实输出 / 阶段名) | 什么条件下读 | 去处 | +|---|---|---| +| `MAX_CONCURRENT` | `new` 报「已有 8 个活跃任务(上限 8)」 | [concurrency-limit.md](reference/concurrency-limit.md) → `## MAX_CONCURRENT`(A 节) | +| `LOCK_NO_STATE` | `lock release` 报「任务 X 不存在(缺台账)」锁照挂 | [unregistered-lock-holder.md](reference/unregistered-lock-holder.md) → `## LOCK_NO_STATE`(B 节) | +| `DONE_GATE` | `done` 报「门禁未全绿」/ 补绿链 / dry-run 判据 | [merge-point-done.md](reference/merge-point-done.md) → `## DONE_GATE`(C 节) | +| `DIRTY_MAIN` | `done` 报「主工作树不干净」,脏是别的会话留的 | [merge-dirty-main-tree.md](reference/merge-dirty-main-tree.md) → `## DIRTY_MAIN`(C2 节) | +| `METRIC_SUSPECT` | 门禁指标异常增长查不出哪个文件造成 | [clean-room-measure.md](reference/clean-room-measure.md) → `## METRIC_SUSPECT`(D 节) | +| `RECLAIM_UNREGISTERED` | `list` 看不到的树 / detached / 悬挂台账要回收 | [reclaim-unregistered.md](reference/reclaim-unregistered.md) → `## RECLAIM_UNREGISTERED`(E 节) | +| `PLUGIN_BRIDGE` | 插件树缺联接、锁 `pw:`、联接分级 | [dsh-plugin-bridge.md](reference/dsh-plugin-bridge.md) → `## PLUGIN_BRIDGE`(F 节) | +| `GATES_IN_TREE` | 树内写输出 ENOENT、`--all` 假红、消息禁词 | [gates-in-tree.md](reference/gates-in-tree.md) → `## GATES_IN_TREE`(G 节) | +| `IRON_RULES` | 九条铁律的逐条判据、ttl/上限数值口径 | [iron-rules.md](reference/iron-rules.md) → `## IRON_RULES` | +| `PITFALLS` | 收工前扫全部实测坑清单 | [pitfalls.md](reference/pitfalls.md) → `## PITFALLS` | +| `VERIFICATION` | 收工前自查各节该留什么证据 | [verification.md](reference/verification.md) → `## VERIFICATION` | -三条判据:仓外 detached 树当净室、**一次只注入一份在飞文件**、与 HEAD 基线逐文件差分;主树前后 `git status --porcelain` 逐行一致才算「全程只读」。全文 → [reference/clean-room-measure.md](reference/clean-room-measure.md)。 +## 分步操作索引(节号 A–G/C2 与铁律编号被 reference/ 与 docs 引用,不许重排/改名) -### E. 回收**非登记**工作树(`list` 为空 / detached / 树里有在飞或未跟踪内容) +正文已搬进上表对应 reference;下列同名索引行只给判据与路由: -三条不可跳过:① 逐文件内容**三桶归类**(与主线工作区/HEAD 比对;「很久没动」不是判据)② 动手前跑**只读 reparse 预扫**,拿到 `REPARSE: none` 才许 `git worktree remove`(铁律 5)③ 唯一未合并残留先备份再 `--force`,拆完复验 + 清悬挂台账。**绝不跑 `done`/`abort`**(铁律 9)。全文(第 1~6 步 + 两份探针脚本)→ [reference/reclaim-unregistered.md](reference/reclaim-unregistered.md)。 +- **A. `new` 撞并发上限 → 腾位**(原 `### A.`)→ `MAX_CONCURRENT`。「活跃」= 台账在且目录还在;先 `done` 已完成树 → 空闲 `abort` → 真要第 9 棵才 `--force`;别手工 `git worktree remove` 给登记任务腾位。 +- **B. 非登记持有者的锁放不掉**(原 `### B.`)→ `LOCK_NO_STATE`。2026-10-29 已修为 warn 跳过 PASS 记录、锁照放,无需手写占位台账;占位台账现在有害。 +- **C. `done `:它是合并点,不是查看器**(原 `### C.`)→ `DONE_GATE`。先确认属主提交完 → `--dry-run` 读全量 → 主树正式 `done`;门禁红会自动补绿。**绝不 `reset --hard`**。 +- **C2. `done` 被「主工作树不干净」挡住,而那份脏是别的并发会话留的**(原 `### C2.`)→ `DIRTY_MAIN`。不许 stash/checkout/reset/提交/删除别人的改动;六步手工合并 + blob 对账,详见 reference。 +- **D. 门禁指标异常增长 → 净室逐文件归因(主树全程只读)**(原 `### D.`)→ `METRIC_SUSPECT`。仓外 detached 树当净室、一次注入一份在飞文件、主树全程只读。 +- **E. 回收非登记工作树(`list` 为空 / detached / 树里有在飞或未跟踪内容)**(原 `### E.`)→ `RECLAIM_UNREGISTERED`。三桶归类 → 只读 reparse 预扫拿 `REPARSE: none` → 才许 remove;绝不跑 `done`/`abort`。 +- **F. 与现役 DSH worktree 插件(`create_worktree`)共存**(原 `### F.`)→ `PLUGIN_BRIDGE`。`simulator/SDL2` 硬需求、`.venv` 软需求;插件树占锁记 `pw:`;回收先 `plugin unadopt` 再按 E 节。 +- **G. 任务树内跑门禁:落点、`--all` 假红、消息禁词**(原 `### G.`)→ `GATES_IN_TREE`。落盘前 `mkdir -p ci-artifacts`;文档门禁树内单文件跑、`--all` 留主树;提交信息 `-F` + 禁词自检。 -### F. 与现役 DSH worktree 插件(`create_worktree`)共存 +## 常用参数 / 环境变量 -| 联接 | 级别 | 依据 | 缺了会怎样 | 逃生门 | -|---|---|---|---|---| -| `simulator/SDL2` | **硬需求** | `simulator/CMakeLists.txt:12` 的 `set(SDL2_DIR …)` **非 `CACHE`**,include / `lib/x64` / `SDL2.dll` 全从它派生 | `build_sim.bat` 当场失败 | **无** | -| `.venv` | 软需求 | `scripts/ci_local.py` 有 `DTU_PRECOMMIT_PYTHON` + 五级解释器候选 | **静默**落机器级解释器(缺 fontTools → `generated-fresh` 假红) | 环境变量 | +- `done` **[DEPRECATED]**:`--dry-run` · `--skip-build` · `--skip-gates` · `--force`;`merge`:`--skip-bench`。 +- `lock`:`--task`(acquire 必填)· `--wait <秒>` · `--ttl <小时>`(默认 build=1h / bench=6h)· `--note`(**只在 acquire 写入 payload,release 忽略**)· `--bench-pass` · `--force`。 +- `DTU_WT_ROOT`(默认同级 `_wt/`)· `DTU_TASK_BASE` · `DTU_INTEGRATION_WORKTREE`。 +- 退出码 `0` 成功 / `1` 操作失败 / `2` 前置或环境错误 / `3` 用法——**只有不接管道才读得到**(`| tail` 后 `$?` 恒 0,见下禁令)。 -- `plugin adopt` 两条都补只是因为便宜,不代表两条都硬。插件树占锁记 `pw:`。现役插件只负责 create/restore,**保留目录与分支,不自动回收**;本 skill 不代删。确需回收先 `plugin unadopt ` 摘联接,再按 **E 节非登记树安全回收规程**处理。「有插件为何还自持生命周期」=先读插件包再 grep 三个概念名报命中数,插件侧零命中就是理由——取证姿势与答案边界 → [reference/dsh-plugin-bridge.md](reference/dsh-plugin-bridge.md) F-2。 +## 禁令(看着合理但致命,留在主文件) -### G. 任务树内跑门禁:落点、`--all` 假红、消息禁词 - -- **新树没有 `ci-artifacts/`**(被 ignore → 不检出):重定向/写文件直接 `ENOENT` 且**整段程序零执行** → 落盘前先单独一条 `mkdir -p ci-artifacts`;树内输出一律树内相对路径(`cd` 进树后 `../_wt/x.txt` 落到 `_wt/_wt/`)。一次性产物**不进仓库根**。 -- **文档门禁树内按单文件跑;全库 `--all` 留到合并后在主树跑**——树内 `simulator/SDL2` 是同一份仓库的联接,`--all` 把它一起扫成假红(实测 RC=1 而问题全在联接下、要改的文档一条没有)。非要树内跑:① 主树同命令拿基线 ② 过滤联接下的问题行 ③ 剩下的逐行比。**只做一步就是误判。** -- **合并提交期 pre-commit 只查冲突文件**(日志首行 `[INFO] Checking merge-conflict files only.`,其余全 `(no files to check) Skipped`)→ 合并落主干后**必须另跑全量** `scripts/ci_local.py`。 -- **跨层改动拆不成「按层分笔」**:钩子看到的世界 = HEAD + 本笔 staged(未暂存被 stash;未跟踪文件不被 stash 但会拖红同一棵树上别人的提交)→ 登记文件 / 生成物 / 互锁引用的文档分到他笔,本笔必被整仓门禁拦(`doc-links`/`registration-check`/`generated-fresh`/`mem-numbers`)。判据:**一笔提交必须自洽**。 -- **跑门禁前字节体检**:`lines / bytes / BOM / CR / U+FFFD / 三连续空行 / 行尾空格 / 末行单个 LF` + Markdown 表格每行列数一致性(单元格内竖线写成反斜杠竖线,否则被当分隔符断列)。坏行**未必是本次改动**,先定归属。`doc-links`/`no-mojibake` 只覆盖编码那半。机械项已命令化:`"$TW" precheck`(BOM 漂移 / CR / U+FFFD + docs 逐档门禁,只读);列数一致性与归属判定仍人做。 -- **提交/合并信息一律 `-F` 读文件**(UTF-8 无 BOM、标题 ≤100、正文每行 ≤80,放 `ci-artifacts/`);清退类任务加**禁词自检**:`git log -1 --pretty=%B | grep -c '<关键词>'` 必须是 **0**。未推送前发现消息写错 → `--amend -F` 就地修,别追加「更正」提交(等于把禁词写回历史)。BOM/CRLF/行长/禁词一次查:`"$TW" precheck --msgfile <文件> --ban <词1> --ban <词2>…`。 -- 全文(第 1~7 条,含 stash 机制与四道整仓门禁现场)→ [reference/gates-in-tree.md](reference/gates-in-tree.md)。 - -## 铁律 - -1. **`done` 只能在主工作树执行**——主干分支检出在主树,git 不允许同一分支两处检出。 -2. **`done` 不 push**:它结束于本地合入 + 门禁全绿;推送需用户明确许可。 -3. **`build` 与 `bench` 都必须串行**(UV4 不能两个实例同时 `-b`;COM6、ST-LINK、设备 IP `192.168.1.100` 各一份)。`build` 锁由 **/keil-build 自持自释**(`keil_build.py`)→ 调用方**不要**手工 acquire/release;`bench` 锁**必须手工** acquire → 烧录 / `/serial-boot-test` → release `--bench-pass`。非登记持有者怎么放 → B 节;插件树 → F 节。 -4. **单写者文档**:`docs/任务规划/`(整个文件夹)、`AGENTS.md` 的任务表生成块(`TASK_TABLE`)、`MDK-ARM/*.uvprojx`、`.pre-commit-config.yaml`、内存快照 —— 任务期**不在任务树里改**,留到 `done` 统一处理;用户显式豁免时(在任务树写、由 done 合回)要在交付报告里点名这条例外。 -5. **清场必须先摘联接**:脚本先 `os.rmdir` 掉 `.venv` / `simulator/SDL2` 联接再 `git worktree remove`。手工拆树前必跑 **E 第 3 步**预扫拿到 `REPARSE: none`——否则 git 可能递归进联接把主树 `.venv` 一起删掉。 -6. **活跃任务硬上限 8 = 脚本常量 `MAX_CONCURRENT`(`task_worktree.py:30`)——唯一事实源**:报错文案与 `new` 的插件树提示都插值它,AGENTS.md / 方案文档 / frontmatter / A 节的数字全是引用同步。改这个数字 → 全形态扫描走 `stale-doc-count-sweep` skill + 隔离小仓验证上限真生效;每棵磁盘代价按实测口径重述、别照抄旧数(细节 → 验证清单末条)。满了 exit 2 → A;悬挂台账 → E 第 6 步。 -7. **工作树放仓库同级 `_wt/`,绝不在仓库内部**(否则污染 `git status`、`--all-files` 与全库搜索)。唯一例外 = 插件写死的仓内 `.agents/worktrees/`(现役)与 `.dsh-worktrees/`(旧版);现役目录池自写 `.gitignore`,旧路径由根 `.gitignore` 预置,两处均已纳入三个全库扫描排除面(→ F 节)。 -8. **`done` 是合并点**:属主没提交完就别跑;合并提交进了主干就只用「主树补提交」收尾,**不用 `reset --hard`** 反悔 → C 节。 -9. **非登记 / detached 的树绝不跑 `done` / `abort`**:两者都以台账为前置(无台账 exit 2),带残留台账时 `abort --force` 会绕过内容保全把别人在飞的改动连树一起删 → E 节。 - -## 陷阱与验证(收工前各扫一遍) - -- [reference/pitfalls.md](reference/pitfalls.md):全部实测坑逐条(含 `--dry-run` 不保护清场段、门禁跑在 `/keil-build` 之前、未跟踪文件在 `git log` 与合并里都不留痕、并集合并残留、新树从未构建 → 体积类门禁必然红、注释-only 也刷红体积凭证、「已合入」快路径在门禁前返回不替你复绿、`--force` 只覆盖四类检查、联接不是 symlink(`core.symlinks=false`)、锁不绑进程存活、文件工具先读后改按绝对路径记账、中文门禁回显乱码但 rc 可信)。收工前扫一眼。 -- [reference/verification.md](reference/verification.md):每节要留的证据(预演 sha + `MT_RC=0`、blob id 对账、两把锁空闲、禁词计数 0、`REPARSE: none`、改上限数字后的全形态扫描)。 +- **`done`/`merge` 只能在主工作树执行**;**不 push**(需用户明确许可)。 +- **`build` 与 `bench` 都串行**:`build` 锁由 `/keil-build` 自持自释,**调用方不要手工 acquire/release**;`bench` 锁必须手工 acquire → 烧录 → release `--bench-pass`。 +- **主树脏且不是你的改动**(别的会话/插件留的)→ 绝不 stash/checkout/reset/提交/删除,也绝不 `reset --hard` 反悔合并 → `DIRTY_MAIN`。 +- **非登记 / detached 树绝不跑 `done`/`abort`**(会绕过内容保全删掉别人在飞的改动)→ `RECLAIM_UNREGISTERED`。 +- **清场必须先摘联接**:手工拆树前跑 reparse 预扫拿 `REPARSE: none`,否则 git 可能递归进联接把主树 `.venv` 一起删。 +- **工作树放仓库同级 `_wt/`,绝不在仓库内部**(唯一例外 = 插件写死的 `.agents/worktrees/` 与旧 `.dsh-worktrees/`)。 +- **读输出别接管道**:`| tail -N` 后退出码恒 0;`done` 输出别 `tail -2`(python stdout 块缓冲 + git stderr 不缓冲会错位,误判「有冲突」)——读全量。 +- **单写者文档**(`docs/任务规划/`、`AGENTS.md` 任务表块、`*.uvprojx`、`.pre-commit-config.yaml`、内存快照)任务期不在任务树里改,留到 `done` 统一处理。 +- **一笔提交必须自洽**:登记文件/生成物/互锁引用的文档不能拆到不同笔,否则被整仓门禁拦。 ## 与其它 skill 的衔接 -- 构建 = `keil-build`· 烧录/回读 = `stlink-flash` · 串口闭环 = `serial-boot-test`(真实 hex 路径以 `.serialtest/config.json` 的 hex 键为准——实测 `MDK-ARM/Objects/STM32F407-Demo.hex` 不存在,拷错 = 烧旧镜像) -- 新 `.c` 双端注册 = `new-source-file` · RAM/.map 台账 = `mem-budget` · UI 回归 = `ui-verify` · 计数同步 = `stale-doc-count-sweep` · 卡死的技能台账行 = `mnemon-skill-ledger-stuck-repair` -- 现役 DSH worktree 插件(`create_worktree`,仓内 `.agents/worktrees/`,兼容旧 `.dsh-worktrees/`)与本 skill 的分工、桥接命令、锁归属、非登记树安全回收 → F 节 · 完整机制与目录分配 → `docs/环境与部署/并行任务工作树方案.md` +构建 = `keil-build` · 烧录 = `stlink-flash` · 串口闭环 = `serial-boot-test` · 新 `.c` 双端注册 = `new-source-file` · RAM/.map 台账 = `mem-budget` · UI 回归 = `ui-verify` · 计数同步 = `stale-doc-count-sweep` · 卡死的技能台账行 = `mnemon-skill-ledger-stuck-repair`。现役 DSH worktree 插件(`.agents/worktrees/`)分工与桥接 → F 节;完整机制 → `docs/环境与部署/并行任务工作树方案.md`。 diff --git a/.dsh/skills/task-worktree/reference/clean-room-measure.md b/.dsh/skills/task-worktree/reference/clean-room-measure.md index 86b30691..d326be46 100644 --- a/.dsh/skills/task-worktree/reference/clean-room-measure.md +++ b/.dsh/skills/task-worktree/reference/clean-room-measure.md @@ -1,3 +1,21 @@ +## METRIC_SUSPECT + +> 路由:主文件失败索引表 `METRIC_SUSPECT` → 本节。原节 `### D.`(主文件已留同名索引行)逐字保留于下。 + +### 判据 + +门禁指标异常增长(如 `id-check` 超限)却查不出哪个文件造成,主树同时压着多条在飞改动。 + +### 处置 + +仓外 detached 树当净室、一次只注入一份在飞文件、与 HEAD 基线逐文件差分;主树前后 `git status --porcelain` 逐行一致才算全程只读。 + +### 证据边界 + +不许 stash/checkout/reset、不许改门禁脚本;2026-10-27 实测 +16 的归因过程,换仓库须重建基线。 + +### 逐字原文(未改写) + ### D. 门禁指标异常增长 → 逐文件归因(把净室工作树当**测量仪**,主树全程只读) **场景**(2026-10-27 实测):`id-check` 突然 FAIL「不可判定 1,178 > 上限 1,166」——比上一轮量到的 1,162 又涨了 **+16**, diff --git a/.dsh/skills/task-worktree/reference/concurrency-limit.md b/.dsh/skills/task-worktree/reference/concurrency-limit.md new file mode 100644 index 00000000..7a1875aa --- /dev/null +++ b/.dsh/skills/task-worktree/reference/concurrency-limit.md @@ -0,0 +1,28 @@ +# 并发上限腾位(自 SKILL.md 逐字外置,2026-11-18) + +## MAX_CONCURRENT + +> 路由:主文件失败索引表 `MAX_CONCURRENT` → 本节。原节 `### A.`(L83–91)逐字搬移。 + +### 判据 + +`new` 报「已有 8 个活跃任务(上限 8)」exit 2;活跃 = 台账在且目录还在。 + +### 处置 + +先 `done` 已完成树 → 空闲树 `abort` → 真要第 9 棵才 `--force`;别手工 `git worktree remove` 给登记任务腾位。 + +### 证据边界 + +上限 8 = 脚本常量 `MAX_CONCURRENT`(`task_worktree.py:30`);改数字须走 `stale-doc-count-sweep` 全形态扫描。 + +### 逐字原文(未改写) + +### A. `new` 撞并发上限 → 腾位 + +1. 认原文 `前置/环境错误:已有 8 个活跃任务(上限 8);先 done/abort,或加 --force`(exit 2)。「活跃」= `_wt/.state/.json` 在且台账 `path` 目录还在 → **手工删目录不占名额、但留悬挂台账**(E 第 6 步)。 +2. `$TW list` 定谁让位:**已完成的先 `done`**(合并回收一步不省)。 +3. 无人认领、零提交、未 claim 的空闲树 → `abort `;有未提交或有提交时脚本会拒,确认可弃才 `--force`。 +4. 真要第 9 棵才 `--force`:并行度上去,**冲突面与台架排队一起上去**(每棵磁盘代价见铁律 6)。 +5. **别用手工 `git worktree remove` 给登记任务腾位**:台账不删(同 ID 报「任务已存在」)、又绕过「先摘联接」(铁律 5),有让 git 递归进联接删掉主树 `.venv` 的风险。要回收的是**非登记树**(`list` 里没有它)→ **E 节**。 +6. 复验:`list` 条目数 == `ls _wt` 目录数,再 `new`。 diff --git a/.dsh/skills/task-worktree/reference/dsh-plugin-bridge.md b/.dsh/skills/task-worktree/reference/dsh-plugin-bridge.md index 3665290c..3ffed19c 100644 --- a/.dsh/skills/task-worktree/reference/dsh-plugin-bridge.md +++ b/.dsh/skills/task-worktree/reference/dsh-plugin-bridge.md @@ -1,3 +1,21 @@ +## PLUGIN_BRIDGE + +> 路由:主文件失败索引表 `PLUGIN_BRIDGE` → 本节。原节 `### F.`(主文件已留同名索引行)逐字保留于下。 + +### 判据 + +插件树缺联接、锁归属 `pw:`、`plugin adopt` 报联接失败、或问「有插件为何还自持生命周期」。 + +### 处置 + +`simulator/SDL2` 是硬需求(缺了 build_sim.bat 当场失败),`.venv` 是软需求可用环境变量逃生;`plugin adopt ` 补缺失联接(不删树);确需回收先 `plugin unadopt` 再按 E 节。 + +### 证据边界 + +联接级别按 `simulator/CMakeLists.txt:12` 非 CACHE 的 `set(SDL2_DIR …)` 这一代码事实;F-2 的插件侧零命中是取证结论,换插件版本须重验。 + +### 逐字原文(未改写) + ### F. 与 DSH worktree 插件(`/worktree`、模型工具 `worktree_create`)共存 本仓现在有**两套**隔离空间。别混用,也别互相回收: diff --git a/.dsh/skills/task-worktree/reference/gates-in-tree.md b/.dsh/skills/task-worktree/reference/gates-in-tree.md index c7b20721..d1f8e4bc 100644 --- a/.dsh/skills/task-worktree/reference/gates-in-tree.md +++ b/.dsh/skills/task-worktree/reference/gates-in-tree.md @@ -1,3 +1,21 @@ +## GATES_IN_TREE + +> 路由:主文件失败索引表 `GATES_IN_TREE` → 本节。原节 `### G.`(主文件已留同名索引行)逐字保留于下。 + +### 判据 + +树内写门禁输出报 ENOENT、`--all` 假红(问题全在 `simulator/SDL2` 联接下)、或提交/合并信息踩禁词。 + +### 处置 + +落盘前 `mkdir -p ci-artifacts`,树内输出走树内相对路径;文档门禁树内按单文件跑、`--all` 留合并后主树;提交信息 `-F` 读文件并过禁词自检(`grep -c` 必须 0)。 + +### 证据边界 + +`-F` 与禁词自检 2026-10-29 实测;合并提交期 pre-commit 只查冲突文件、必须另跑全量 `ci_local.py`。 + +### 逐字原文(未改写) + ### G. 任务树内跑门禁与审计:输出落点(ci-artifacts)与 SDL2 联接假红 三条硬规矩,全是 2026-10-29 实测付过失败成本的(两起 ENOENT + 一次假红误判): diff --git a/.dsh/skills/task-worktree/reference/iron-rules.md b/.dsh/skills/task-worktree/reference/iron-rules.md new file mode 100644 index 00000000..1d8d4862 --- /dev/null +++ b/.dsh/skills/task-worktree/reference/iron-rules.md @@ -0,0 +1,31 @@ +# 铁律 1–9(长尾,自 SKILL.md 逐字外置,2026-11-18) + +## IRON_RULES + +> 路由:主文件失败索引表 `IRON_RULES` → 本节。原节 `## 铁律`(L161–172)逐字搬移;致命禁令短句仍留在主文件。 + +### 判据 + +九条铁律覆盖 done 属主/不 push、build 与 bench 串行、单写者文档、摘联接、上限、工作树位置等;正常路径不必读。 + +### 处置 + +按对应条处置;违反任一条是操作错误而非工具故障。 + +### 证据边界 + +上限 8、TTL 数值均为脚本常量实测口径;换项目须重核。 + +### 逐字原文(未改写) + +## 铁律 + +1. **`done` 只能在主工作树执行**——主干分支检出在主树,git 不允许同一分支两处检出。 +2. **`done` 不 push**:它结束于本地合入 + 门禁全绿;推送需用户明确许可。 +3. **`build` 与 `bench` 都必须串行**(UV4 不能两个实例同时 `-b`;COM6、ST-LINK、设备 IP `192.168.1.100` 各一份)。`build` 锁由 **/keil-build 自持自释**(`keil_build.py`)→ 调用方**不要**手工 acquire/release;`bench` 锁**必须手工** acquire → 烧录 / `/serial-boot-test` → release `--bench-pass`。非登记持有者怎么放 → B 节;插件树 → F 节。 +4. **单写者文档**:`docs/任务规划/`(整个文件夹)、`AGENTS.md` 的任务表生成块(`TASK_TABLE`)、`MDK-ARM/*.uvprojx`、`.pre-commit-config.yaml`、内存快照 —— 任务期**不在任务树里改**,留到 `done` 统一处理;用户显式豁免时(在任务树写、由 done 合回)要在交付报告里点名这条例外。 +5. **清场必须先摘联接**:脚本先 `os.rmdir` 掉 `.venv` / `simulator/SDL2` 联接再 `git worktree remove`。手工拆树前必跑 **E 第 3 步**预扫拿到 `REPARSE: none`——否则 git 可能递归进联接把主树 `.venv` 一起删掉。 +6. **活跃任务硬上限 8 = 脚本常量 `MAX_CONCURRENT`(`task_worktree.py:30`)——唯一事实源**:报错文案与 `new` 的插件树提示都插值它,AGENTS.md / 方案文档 / frontmatter / A 节的数字全是引用同步。改这个数字 → 全形态扫描走 `stale-doc-count-sweep` skill + 隔离小仓验证上限真生效;每棵磁盘代价按实测口径重述、别照抄旧数(细节 → 验证清单末条)。满了 exit 2 → A;悬挂台账 → E 第 6 步。 +7. **工作树放仓库同级 `_wt/`,绝不在仓库内部**(否则污染 `git status`、`--all-files` 与全库搜索)。唯一例外 = 插件写死的仓内 `.agents/worktrees/`(现役)与 `.dsh-worktrees/`(旧版);现役目录池自写 `.gitignore`,旧路径由根 `.gitignore` 预置,两处均已纳入三个全库扫描排除面(→ F 节)。 +8. **`done` 是合并点**:属主没提交完就别跑;合并提交进了主干就只用「主树补提交」收尾,**不用 `reset --hard`** 反悔 → C 节。 +9. **非登记 / detached 的树绝不跑 `done` / `abort`**:两者都以台账为前置(无台账 exit 2),带残留台账时 `abort --force` 会绕过内容保全把别人在飞的改动连树一起删 → E 节。 diff --git a/.dsh/skills/task-worktree/reference/merge-dirty-main-tree.md b/.dsh/skills/task-worktree/reference/merge-dirty-main-tree.md index 27ecfe14..cf3585be 100644 --- a/.dsh/skills/task-worktree/reference/merge-dirty-main-tree.md +++ b/.dsh/skills/task-worktree/reference/merge-dirty-main-tree.md @@ -1,3 +1,21 @@ +## DIRTY_MAIN + +> 路由:主文件失败索引表 `DIRTY_MAIN` → 本节。原节 `### C2.`(主文件 L127–133 已留同名索引行)逐字保留于下。 + +### 判据 + +`done` 报「主工作树不干净」,而那份脏是别的会话/插件留的(你从没碰过)。 + +### 处置 + +绝不 stash/checkout/reset/提交/删除别人的改动;按六步走:取证 → 预演 `git merge-tree --write-tree` → 主树手工 `git merge --no-ff --no-edit -F` → blob 对账 → 备份台账后让 `done` 摘联接拆树 → 复验。 + +### 证据边界 + +blob id 变了 = stash pop 半冲突,立即停手交属主;2026-10-29 同日两遍实测,换场景须重新取证。 + +### 逐字原文(未改写) + ### C2. `done` 被「主工作树不干净」挡住,而那份脏改动是**别的并发会话**留下的 **场景**(2026-10-29 同一套流程在同一天跑了两遍,两遍都撞上它):任务树里的文档改完、准备合回 `v2-on-ui`, diff --git a/.dsh/skills/task-worktree/reference/merge-point-done.md b/.dsh/skills/task-worktree/reference/merge-point-done.md new file mode 100644 index 00000000..170872fe --- /dev/null +++ b/.dsh/skills/task-worktree/reference/merge-point-done.md @@ -0,0 +1,44 @@ +# done 合并点与补绿链(自 SKILL.md 逐字外置,2026-11-18) + +## DONE_GATE + +> 路由:主文件失败索引表 `DONE_GATE` → 本节。原节 `### C.`(L102–126)逐字搬移。 + +### 判据 + +`done` 报「门禁未全绿」/「主工作树不干净」,或 dry-run 的 N 与属主应交提交数不符。 + +### 处置 + +先 `status` 确认属主提交完 → `--dry-run` 读全量 → 主树正式 `done`;门禁红时自动补绿,按提示提交回填文件再重跑。 + +### 证据边界 + +绝不用 `reset --hard`(项目级 Never);「已合入」快路径在门禁前返回、不替你复绿,尾巴要自己补。 + +### 逐字原文(未改写) + +### C. `done `:它是合并点,不是查看器 + +1. **合并前确认属主提交完**:`$TW status ` 看未提交与领先数,跨会话再问属主一句。实测教训:属主还剩「2/2」没提交就 `done` → 只含 1/2 的分支进了主干,只能另开一棵树补后半(自己的时序错,不是分支问题)。 +2. 先 `--dry-run` 且**读全量**。判据两行:`[ok] 前置检查通过(领先 共 N 个提交)` + `[ok] 无冲突,预演结果树 `;**N 必须等于属主应交的提交数**,对不上回第 1 步。 +3. 正式 `$TW done `——**必须在主工作树**(铁律 1)。 +4. 见 `!! 门禁未全绿` 时,`done` 现在会**自动调 `postmerge` 补绿**(体积凭证 + RAM 台账 + 文档全库)。补绿成功且有回填文件时列出待提交清单;补绿失败才保留工作树等你手动排查。紧跟的 `主干已含合并提交 ` 说明**合并已落主干**。 + - ✅ 自动补绿成功后按提示提交回填文件,再重跑 `done` 完成清场。 + - ❌ **绝不用 `reset --hard `**——那是丢弃已入库的合并提交,且 `reset --hard` 是项目级 Never(连未提交工作一起丢)。 +5. **`done` 现在自动完成整条补绿链**:regen(任务表 + 内存快照 + RAM 台账)→ build → ci → postmerge(凭证诊断 + 文档全库)。门禁通过后若 postmerge 产生回填文件,会列出待提交清单等你确认后再清场。 + 手工补绿链仍保留为权威兜底(`postmerge` 内部逻辑等价于下面的步骤): + +```bash +"$PY" scripts/check_mem_numbers.py --write # 台账受管区 ↔ 新 .map 对齐 +"$PY" scripts/ram_baseline.py --update # 趋势基线追加一行 +"$PY" scripts/ram_baseline.py --write # RAM 快照 / 92% 预算台账 +"$PY" scripts/check_test_coverage.py --update-baseline # 覆盖率基线(新单测 / 新套件时必刷) +"$PY" scripts/check_doc_links.py --all # 文档链接与章节引用 +git add <上面刷出来的基线/快照文件> # 显式列文件,别 -A 把别人在飞的改动一起提交 +git commit -F # 提交属 Ask first(入口文件「边界」节) +``` + + **`--dry-run` 新增台账碰撞预检**:双方都改过的已知生成文件(`ram_baseline.tsv` / `size_attestation.json` / RAM 台账 md)会在预演阶段提前警告,让你知道合并后需要 postmerge 重算。 +6. **重跑 `done` 前主树必须干净**,否则 `失败:主工作树不干净(…)——合并会把未提交改动卷进来` → 第 5 步产物先提交。分支已并时重跑打印 `[i] task/- 已合入 ,跳过合并,直接清场`——**该路径在门禁之前就返回,不会替你复绿**:上一次门禁没跑到的尾巴(主树 `ci_local.py` + `check_doc_links.py --all`;体积/文档那半可 `postmerge` 一把跑)必须自己补。主树脏且那份脏不是你的 → **C2**。 +7. 清场后再敲一次 `done ` 得 `前置/环境错误:任务 不存在(缺台账 …json)`(exit 2)——**不是失败**:清场最后一步 unlink 了台账。**判完成以 `git log` 为准**。 diff --git a/.dsh/skills/task-worktree/reference/pitfalls.md b/.dsh/skills/task-worktree/reference/pitfalls.md index 6ab6275f..d01ef01c 100644 --- a/.dsh/skills/task-worktree/reference/pitfalls.md +++ b/.dsh/skills/task-worktree/reference/pitfalls.md @@ -1,3 +1,21 @@ +## PITFALLS + +> 路由:主文件失败索引表 `PITFALLS` → 本节。原节 `## 陷阱(实测)` 逐字保留于下。 + +### 判据 + +收工前扫一眼全部实测坑清单时读本节。 + +### 处置 + +按命中条目逐条处置;每条坑的成因与逃生门见逐字原文。 + +### 证据边界 + +全部为特定日期实测(节内标注);换树/换插件版本须重验。 + +### 逐字原文(未改写) + ## 陷阱(实测) - **`--force` 不是万能钥匙**:它只覆盖四类检查——并发上限、持有者与 `--task` 不符、陈旧锁接管、 diff --git a/.dsh/skills/task-worktree/reference/reclaim-unregistered.md b/.dsh/skills/task-worktree/reference/reclaim-unregistered.md index 9b4a36a7..5d352664 100644 --- a/.dsh/skills/task-worktree/reference/reclaim-unregistered.md +++ b/.dsh/skills/task-worktree/reference/reclaim-unregistered.md @@ -1,3 +1,21 @@ +## RECLAIM_UNREGISTERED + +> 路由:主文件失败索引表 `RECLAIM_UNREGISTERED` → 本节。原节 `### E.`(主文件已留同名索引行)逐字保留于下。 + +### 判据 + +`git worktree list` 里有树但 `_wt/.state/.json` 台账不存在;或 HEAD detached;或树里有不属于本会话的在飞内容。 + +### 处置 + +三桶归类中内容 → 只读 reparse 预扫拿 `REPARSE: none` → 才许 `git worktree remove` → 唯一未合并残留先备份再 `--force` → 拆完复验 + 清悬挂台账。绝不跑 `done`/`abort`。 + +### 证据边界 + +reparse 预扫是 Windows 目录联接实测必需(否则 git 递归删主树 `.venv`);探针脚本与步骤 1–6 见逐字原文。 + +### 逐字原文(未改写) + ### E. 回收**非登记**工作树(`$TW list` 为空 / detached HEAD / 树里有在飞或未跟踪内容) **这类树的判定特征**(命中任意一条就适用本节):`git worktree list` 里有它、但 `_wt/.state/.json` 台账不存在; diff --git a/.dsh/skills/task-worktree/reference/unregistered-lock-holder.md b/.dsh/skills/task-worktree/reference/unregistered-lock-holder.md new file mode 100644 index 00000000..b4c26523 --- /dev/null +++ b/.dsh/skills/task-worktree/reference/unregistered-lock-holder.md @@ -0,0 +1,29 @@ +# 非登记持有者的锁(自 SKILL.md 逐字外置,2026-11-18) + +## LOCK_NO_STATE + +> 路由:主文件失败索引表 `LOCK_NO_STATE` → 本节。原节 `### B.`(L92–101)逐字搬移。 + +### 判据 + +`lock release ... --bench-pass` 报「任务 X 不存在(缺台账)」但锁照旧挂着。 + +### 处置 + +2026-10-29 已修:无台账降级为 warn 跳过 PASS 记录、锁照放,无需手写占位台账。 + +### 证据边界 + +占位台账现在有害(占上限名额 + 被 `list` 当任务);最后一手段手工删锁文件仅前面都不可用时做。 + +### 逐字原文(未改写) + +### B. 非登记持有者的锁放不掉 + +症状:`lock release bench --task acceptwin --bench-pass`(带 `--force` 同)报 `前置/环境错误:任务 acceptwin 不存在(缺台账 _wt/.state/acceptwin.json)`,**锁照旧挂着**。根因:`release` 带 `--bench-pass` 就先 `load_state(task)`,而 `acquire` 侧不查台账 → 「释放」被「记账」挡死;锁没放,`done` 的 `release_stale_locks()` 对未到 TTL 的活锁判失败 → **一个没登记的名字挡住所有任务收口**。 + +**2026-10-29 已修**:无台账降级为 `[warn] …跳过 PASS 记录,仅释放锁`,**不再需要手写占位台账**。 +1. `$TW lock status` 认现场(持有者 / pid / 已持有 / TTL)——别对同一句报错反复重试。 +2. `$TW lock release --task [--bench-pass]` 直接放;PASS 记不上会 warn,锁照放。 +3. **PASS 后面还要用**(`done` 只认台账 `bench_pass`)→ 从一开始就用已 `new` 的 ID 占锁,或把结论写进主干提交/文档。插件树 `pw:` 天然无台账 → F 节。 +4. 最后手段:锁 = `_wt/.state/locks/.lock` 的单行 JSON(`name/task/pid/host/epoch/at/note/ttl`),`release` 就是 unlink 它——手工删 = 不记 PASS 的强制释放,前面各步都不可用才做。**早期为绕坑手写的占位台账现在有害**(既占上限名额又被 `list` 当任务)→ E 第 6 步备份后删。 diff --git a/.dsh/skills/task-worktree/reference/verification.md b/.dsh/skills/task-worktree/reference/verification.md index d37b052e..dfac5582 100644 --- a/.dsh/skills/task-worktree/reference/verification.md +++ b/.dsh/skills/task-worktree/reference/verification.md @@ -1,3 +1,21 @@ +## VERIFICATION + +> 路由:主文件失败索引表 `VERIFICATION` → 本节。原节 `## 验证` 逐字保留于下。 + +### 判据 + +收工前自查各节该留什么证据时读本节。 + +### 处置 + +逐条对照证据清单(预演 sha、`MT_RC=0`、blob 对账、两把锁空闲、禁词计数 0、`REPARSE: none`)。 + +### 证据边界 + +证据口径与实测日期绑定,换场景须重新取证。 + +### 逐字原文(未改写) + ## 验证 - `$TW list`:台账段条目数 = `ls _wt` 的目录数且 ≤ 8(`MAX_CONCURRENT`);刚回收的任务与历史占位条目都不再出现 diff --git a/.dsh/skills/ui-verify/SKILL.md b/.dsh/skills/ui-verify/SKILL.md index 97a54dc7..44345e98 100644 --- a/.dsh/skills/ui-verify/SKILL.md +++ b/.dsh/skills/ui-verify/SKILL.md @@ -25,6 +25,13 @@ cmake --build simulator/build --config Debug # 0) 构建模拟器(须 0 警 退出码:0=PASS / 1=断言失败 / 2=环境错误(exe 缺失等,先按 `new-machine-setup` skill 重建对应环境再重跑)。 +**成功输出样例**(本轮实跑 `check_menu_rows.py` / `check_content_pages.py`,`PYTHONIOENCODING=utf-8`;判据串亦见 `docs/UI设计/UI_自动化测试流程.md` 验收表):看到两条 `PASS: ...` 汇总行(8 状态全过 + 76 内容页全过)就是像素回归通了,再叠 Keil `BUILD_OK: 0 errors, 0 warnings` 即 5 门禁全绿,不用再往下看。 + +```text +PASS: 8 状态全部断言通过(8 图,池基线 5368 B) +PASS: 76 内容页 + 往返池水位 + rtlive 全部通过 +``` + ## 失败处置决策 | 现象 | 判定 | 处置 | diff --git a/test/host/README.md b/test/host/README.md index c0291c8a..facf7831 100644 --- a/test/host/README.md +++ b/test/host/README.md @@ -33,6 +33,9 @@ | `iec104_master.py` | **IEC 60870-5-104 主站客户端(台架复测/保护定值持久化)**:连设备 :2404(工厂默认,`--port` 可指别的)跑 STARTDT → 总召(actcon/四组背景扫描/actterm)→ 经 C_SE 两段写临时压低 OC1 定值确定性触发 YX16 变位(COT=3)→ 恢复 → YK11 两段式 → C_RD 读回;**保护定值持久化模式 `--b7-pre/--b7-post/--b7-mark/--b7-check`**(中间 ST-LINK 复位):YK12 两段投退→保护退出/联动、定值与压板态跨复位保持(含非默认 7.5 往返);纯标准库,输出纯 ASCII 可直接重定向归档为台架证据(判据 exit 0/1/2) | | `cal_fit.py` | **N 点最小二乘标定参数求解(全仓唯一实现,v2.2 起固件侧拟合已删除)**(**3~8 点**,推荐 5 点):`--selftest` 跑金标向量回归(原 C 侧 `r_q16=39322000 / b=12` + 4 条拒绝路径,exit 0 全过 / 1 有失败,改动算法后必跑);`--from-doc` 直接读执行卡 §3 `CALDATA` 长表(每行一个点:路 \| 序号 \| 屏上读数 \| 注入已知量)按路分组拟合,输出合并 `WRITE-ALL` 命令;单路 `--sem/--x/--y` 亦可(`--x` = `meas:` 行 mV/mA 原样、`--y` = V/A 内部 ×1000,`--r-old/--b-old` 指读数采集时的设备参数);执行卡 `docs/测试说明/专项验证/ADC多点标定执行流程.md` §3;exit 0 可写 / 2 拒绝(入参越界 `bad argument`、点数越界、点位没拉开、单调性反转、斜率非正、r/b 越带、残差 >2%、表还是旧 6 列)或未填 | | `cal_write.py` | **标定参数写入器**(库层复用 `iec104_master.py`):C_SE 两段写下发定值段 `0x8050~`(变比 r)/`0x8048~`(零点 b,落笔置 VALID),C_RD 读回复核;每路先 r 后 b,输出纯 ASCII 可归档;执行卡 `docs/测试说明/专项验证/ADC多点标定执行流程.md` §4;exit 0 全过 / 1 有失败 / 2 连接或协议错误 | +| `iec104_dtu/verify_board_acceptance.py` | **真板 104 只读验收**(STARTDT→总召→逐点核对 10 个映射遥测 + 59 SP + 16 DP →命令拒绝→对时确认):固件/点表变更后连板跑;`--host/--port` 默认 `192.168.31.100:2404`,纯标准库、ASCII 输出;exit 0 全过 / 1 检查失败 / 2 连接或协议错误;用法见 `iec104_dtu/PROBE_RUNBOOK.md` | +| `iec104_dtu/verify_simulator_lan_bind.py` | **模拟器 104 任意地址绑定与局域网可达性验证**(启动 `lvgl_sim` 后查 `0.0.0.0:port` 监听 + 本机 IPv4 STARTDT 握手):模拟器绑定/CLI 变更后跑;`--exe/--output/--duration/--lan-ip` 可覆盖,纯标准库、ASCII 输出;exit 0 通过 / 1 断言失败 / 2 环境错误;同机验证,不证明防火墙放行 | +| `iec104_dtu/verify_simulator_duration_evidence.py` | **模拟器自然退出证据探针**(拒绝 select/execute→对时→无 COT10/11→`--iec104-duration` 自然退出打印 STOP 汇总):引用 `simulated_actions` 前跑;`--exe/--host/--port/--duration/--output` 可覆盖,纯标准库、ASCII 输出;exit 0 全过 / 1 行为失败 / 2 启动或读取错误 | ### 时间 / 时延 diff --git a/test/host/iec104_dtu/PROBE_INDEX.md b/test/host/iec104_dtu/PROBE_INDEX.md new file mode 100644 index 00000000..0a055d40 --- /dev/null +++ b/test/host/iec104_dtu/PROBE_INDEX.md @@ -0,0 +1,92 @@ +# IEC104 probe triage and migration index + +This is the tracked index for the temporary IEC104 probes that previously lived +under ignored `ci-artifacts/`. Only reusable protocol-correctness acceptance +probes (A) were normalized into `test/host/iec104_dtu/`. One-off design +measurements (B) stay out of the test tree. Scripts already covered by tracked +assets (C) were not migrated. The source paths below are historical: +`ci-artifacts/` is gitignored and may not exist in a fresh clone. + +## A - reusable protocol acceptance (migrated) + +| Source | Class | Disposition | One-line verdict | +|---|---|---|---| +| `ci-artifacts/iec104-bench/board_probe.py` | A | Migrated to `test/host/iec104_dtu/verify_board_acceptance.py` | Real-board read-only acceptance: STARTDT, GI, 10 mapped measurements, 59 SP + 16 DP, command refusal, clock confirmation. Exit 0 = all checks pass, 1 = a check fails, 2 = connection/protocol error. | +| `ci-artifacts/iec104-lan/verify_lan.py` | A | Migrated to `test/host/iec104_dtu/verify_simulator_lan_bind.py` | Simulator wildcard bind and local-IPv4 STARTDT check. Exit 0 = wildcard listener and handshakes pass, 1 = assertion fails, 2 = missing exe/tooling error. Same-host only. | +| `ci-artifacts/iec104-tests/duration-evidence/duration_refusal_probe.py` | A | Migrated to `test/host/iec104_dtu/verify_simulator_duration_evidence.py` | Simulator finite-duration evidence for refused commands, clock sync, no completion frames and clean STOP. Exit 0 = all checks pass, 1 = behaviour fails, 2 = startup/read error. | + +## B - one-off design-time measurement (not migrated) + +| Source | Class | Disposition | One-line verdict | +|---|---|---|---| +| `ci-artifacts/iec104-cutover/probe_nostore_effect.py` | B | Keep as one-off evidence; not in `test/host/` | Compares `iec104_source.o` ZI with/without `IEC104_SOURCE_NO_VALUE_STORE`; answers a macro-cost question, not future protocol correctness. | +| `ci-artifacts/iec104-cutover/ac5_probe_32.py` | B | Keep as one-off evidence; not in `test/host/` | AC5 warning-surface probe driven by the historical registration manifest; design-time compiler evidence. | +| `ci-artifacts/iec104-cutover/gen_source_ranks.py` | B | Keep as one-off evidence; not in `test/host/` | Generates a dense rank header from a frozen profile; a code generator, not a test. | +| `ci-artifacts/iec104-cutover/recompute_reach_budget.py` | B | Keep as one-off evidence; not in `test/host/` | Recomputes RAM budget from one-off link logs; design accounting only. | +| `ci-artifacts/iec104-cutover/register_mdk.py` | B | Keep as one-off evidence; not in `test/host/` | One-time MDK registration script driven by a manifest; host tests must never register product files. | +| `ci-artifacts/iec104-cutover/verify-slot-equivalence.py` | B | Keep as one-off evidence; not in `test/host/` | Proves old/new storage mappings equivalent for a specific redesign; not a reusable 104 acceptance probe. | +| `ci-artifacts/iec104-cutover/serv-attrib/serv_surface_probe.py` | B | Keep as one-off evidence; not in `test/host/` | Reports stack frames of one frozen task build; design measurement. | +| `ci-artifacts/iec104-build/verify_vendor.py` | B | Keep as one-off evidence; not in `test/host/` | Pins 17 controlled vendor diffs and hashes a frozen release; design drift evidence. | +| `ci-artifacts/iec104-build/capacity_boundaries.py` | B | Keep as one-off evidence; not in `test/host/` | Compiles vendor TcpServer.c at guessed capacity limits; capacity design, not protocol acceptance. | +| `ci-artifacts/iec104-build/link_resource_probe.py` | B | Keep as one-off evidence; not in `test/host/` | Isolated armlink resource probe with hard-coded Keil paths and historical object inventory. | +| `ci-artifacts/iec104-build/summarize_matrix.py` | B | Keep as one-off evidence; not in `test/host/` | Reformats `vendor-ac5-results.json` into a matrix; depends on a one-off artifact tree. | +| `ci-artifacts/iec104-build/vendor_style_scan.py` | B | Keep as one-off evidence; not in `test/host/` | Wrapper around the coding-standard hook for a frozen vendor file list. | +| `ci-artifacts/iec104-build/final_static_scan.py` | B | Keep as one-off evidence; not in `test/host/` | Freezes explicit vendor/simulator source lists and hashes for a past review. | +| `ci-artifacts/iec104-build/tiny_resource_probe.py` | B | Keep as one-off evidence; not in `test/host/` | Compiles/links a hypothetical tiny-capacity variant; not a product configuration test. | +| `ci-artifacts/iec104-review/verify_vendor.py` | B | Keep as one-off evidence; not in `test/host/` | Asserts 84 upstream hashes, 43 static assertions and controlled diffs of a historical review tree. | +| `ci-artifacts/iec104-review/any_bind_review.py` | B | Keep as one-off evidence; reusable part migrated | Reviews one frozen simulator SHA256 and writes review-only JSON; wildcard bind check migrated to A. | +| `ci-artifacts/iec104-review/boundaries.py` | B | Keep as one-off evidence; not in `test/host/` | Re-checks capacity compile boundaries at a hard-coded Keil path; duplicate of `iec104-build/capacity_boundaries.py`. | +| `ci-artifacts/iec104-review/mcu_closure_review.py` | B | Keep as one-off evidence; not in `test/host/` | Rebuilds a historic MCU closure map and checks a 3336-byte symbol; not a protocol test. | +| `ci-artifacts/iec104-review/run_masks.py` | B | Keep as one-off evidence; not in `test/host/` | Compiles a one-off `masks.c` with MSVC; depends on a review-tree fixture. | +| `ci-artifacts/iec104-review/ramprobe/cap_sweep.py` | B | Keep as one-off evidence; not in `test/host/` | Sweeps TCP capacities through ARMCC and fromelf for RAM sizing. | +| `ci-artifacts/iec104-review/ramprobe/dump.py` | B | Keep as one-off evidence; not in `test/host/` | Dumps section data of one historical object through fromelf. | +| `ci-artifacts/iec104-review/ramprobe/objs.py` | B | Keep as one-off evidence; not in `test/host/` | Parses a historical Keil map's object summary by RW+ZI. | +| `ci-artifacts/iec104-review/ramprobe/objsyms.py` | B | Keep as one-off evidence; not in `test/host/` | Lists data symbols of one named object from a historical Keil map. | +| `ci-artifacts/iec104-review/ramprobe/region.py` | B | Keep as one-off evidence; not in `test/host/` | Aggregates execution-region rows from a historical Keil map. | +| `ci-artifacts/iec104-review/ramprobe/region2.py` | B | Keep as one-off evidence; not in `test/host/` | Refined Keil map region/section aggregation for the same one-off review. | +| `ci-artifacts/iec104-review/ramprobe/secsum.py` | B | Keep as one-off evidence; not in `test/host/` | Converts fromelf section sizes into a RO/RAM table for historical objects. | +| `ci-artifacts/iec104-review/ramprobe/sweep2.py` | B | Keep as one-off evidence; not in `test/host/` | Compiles a single vendor TU under alternate capacity defines and reports RO/RAM. | +| `ci-artifacts/iec104-review/ramprobe/sweep3.py` | B | Keep as one-off evidence; not in `test/host/` | Measures .bss of one vendor TU under a fixed set of capacity overrides. | +| `ci-artifacts/iec104-review/ramprobe/syms.py` | B | Keep as one-off evidence; not in `test/host/` | Greps named symbols from a historical Keil map. | +| `ci-artifacts/hash_iec104_sim_release.py` | B | Keep as one-off evidence; not in `test/host/` | Rewrites a release source hash list from a historical vcxproj; snapshot tool, not a test. | +| `ci-artifacts/iec104-mcu-skeleton/capacity-candidates.py` | B | Keep as one-off evidence; not in `test/host/` | Enumerates hypothetical capacity pools for the skeleton design. | +| `ci-artifacts/iec104-mcu-skeleton/compile_real_serv_exact.py` | B | Keep as one-off evidence; not in `test/host/` | Recreates the historical product compile surface for one serv TU. | +| `ci-artifacts/iec104-mcu-skeleton/link_skeleton.py` | B | Keep as one-off evidence; not in `test/host/` | Measures skeleton closure RO/RW+ZI with isolated armlink objects. | +| `ci-artifacts/iec104-mcu-skeleton/link_whole_image.py` | B | Keep as one-off evidence; not in `test/host/` | Measures whole-image reachability with a draft Net backend. | +| `ci-artifacts/iec104-mcu-skeleton/link_whole_with_business.py` | B | Keep as one-off evidence; not in `test/host/` | Adds business TUs to the isolated link for a three-tier RAM comparison. | +| `ci-artifacts/iec104-mcu-skeleton/measure_skeleton.py` | B | Keep as one-off evidence; not in `test/host/` | Compiles/links the skeleton TU set and records ARMCC/fromelf sizes. | +| `ci-artifacts/iec104-mcu-skeleton/pool_parts_report.py` | B | Keep as one-off evidence; not in `test/host/` | Parses pool-size constants from historical fromelf output. | +| `ci-artifacts/iec104-mcu-skeleton/summarize_matrix.py` | B | Keep as one-off evidence; not in `test/host/` | Summarizes skeleton link maps against a fixed RAM floor. | +| `ci-artifacts/iec104-mcu-skeleton/summarize_skeleton.py` | B | Keep as one-off evidence; not in `test/host/` | Aggregates per-TU ROM/RAM from a historical measurement JSON. | +| `ci-artifacts/iec104-mcu-skeleton/summarize_whole_image.py` | B | Keep as one-off evidence; not in `test/host/` | Summarizes whole-image link maps against a fixed RAM floor. | +| `ci-artifacts/iec104-mcu-skeleton/tu_closure.py` | B | Keep as one-off evidence; not in `test/host/` | Explains skeleton/business TU split from one historical .xref map. | +| `ci-artifacts/iec104-mcu-skeleton/core-trim/candidate_a_delta.py` | B | Keep as one-off evidence; not in `test/host/` | Measures code-trim delta against a git-HEAD baseline copy. | +| `ci-artifacts/iec104-mcu-skeleton/core-trim/link_core_trim.py` | B | Keep as one-off evidence; not in `test/host/` | Links two core-trim variants and subtracts library RAM from map totals. | +| `ci-artifacts/iec104-mcu-skeleton/core-trim/link_reach_fixed.py` | B | Keep as one-off evidence; not in `test/host/` | Re-links with a corrected core/source reach root across four tiers. | +| `ci-artifacts/iec104-mcu-skeleton/core-trim/measure_business_tu.py` | B | Keep as one-off evidence; not in `test/host/` | Compiles business TUs in two tiers and extracts RAM with fromelf. | +| `ci-artifacts/iec104-mcu-skeleton/core-trim/ram_by_object.py` | B | Keep as one-off evidence; not in `test/host/` | Lists per-object RAM from historical core-trim objects. | +| `ci-artifacts/iec104-mcu-skeleton/core-trim/summarize_core_trim.py` | B | Keep as one-off evidence; not in `test/host/` | Parses size symbols produced by the one-off core-trim probe. | +| `ci-artifacts/iec104-mcu-skeleton/core-trim/simcheck/gen_probes.py` | B | Keep as one-off evidence; not in `test/host/` | Generates probe C files for the one-off skeleton simulation check. | +| `ci-artifacts/iec104-mcu-plan/files/capture_evidence.py` | B | Keep as one-off evidence; not in `test/host/` | Captures selected source ranges into a historical evidence text file. | +| `ci-artifacts/iec104-mcu-plan/persistence/audit_parameters.py` | B | Keep as one-off evidence; not in `test/host/` | Audits a frozen writable-parameter predicate and writes CSV to stdout. | +| `ci-artifacts/iec104-mcu-plan/resources/link_closure.py` | B | Keep as one-off evidence; not in `test/host/` | Links a conservative file-domain closure from historical objects. | +| `ci-artifacts/iec104-mcu-plan/resources/measure_closure.py` | B | Keep as one-off evidence; not in `test/host/` | Copies upstream sources and compiles them in isolation for sizing. | +| `ci-artifacts/iec104-mcu-plan/resources/seal_evidence.py` | B | Keep as one-off evidence; not in `test/host/` | Hashes all evidence files in one design directory into a manifest. | +| `ci-artifacts/iec104-mcu-feasibility/files/run.py` | B | Keep as one-off evidence; not in `test/host/` | Isolated MSVC host run of file-domain feasibility fixtures. | +| `ci-artifacts/iec104-mcu-feasibility/independent-tests/run_checks.py` | B | Keep as one-off evidence; not in `test/host/` | Runs artifact-only persistence feasibility probes and mutants. | +| `ci-artifacts/iec104-mcu-feasibility/independent-tests/run_layout.py` | B | Keep as one-off evidence; not in `test/host/` | Checks a frozen candidate layout oracle with MSVC fixtures. | +| `ci-artifacts/iec104-mcu-feasibility/persistence/run_model.py` | B | Keep as one-off evidence; not in `test/host/` | Runs an isolated persistence-state-machine model with injected faults. | +| `ci-artifacts/iec104-mcu-feasibility/resources/measure_layout.py` | B | Keep as one-off evidence; not in `test/host/` | Compiles/links a frozen layout candidate for RAM comparison. | + +## C - already covered by tracked assets (not migrated) + +| Source | Class | Disposition | One-line verdict | +|---|---|---|---| +| `ci-artifacts/iec104-review/cli_final.py` | C | Not migrated | Covered by `test/host/iec104_dtu/run_tcp_test.py` and the simulator CLI contract in `test/host/iec104_dtu/MATRIX.md`; this file additionally pinned one historical SHA256. | +| `ci-artifacts/iec104-build/baseline-f84855a5/**/*.py` | C | Not migrated | Frozen baseline copy of already tracked repository scripts; no new probe logic. | + +## Files added under `test/host/iec104_dtu/` + +- `verify_board_acceptance.py`, `verify_simulator_lan_bind.py`, `verify_simulator_duration_evidence.py`: normalized A-class probes. +- `PROBE_INDEX.md`: this classification index. +- `PROBE_RUNBOOK.md`: how and when to run the three normalized probes. diff --git a/test/host/iec104_dtu/PROBE_RUNBOOK.md b/test/host/iec104_dtu/PROBE_RUNBOOK.md new file mode 100644 index 00000000..098b561a --- /dev/null +++ b/test/host/iec104_dtu/PROBE_RUNBOOK.md @@ -0,0 +1,55 @@ +# IEC104 probe runbook (tracked acceptance assets) + +## 什么时候跑 + +| Script | When | Exit codes | +|---|---|---| +| `verify_board_acceptance.py` | After DTU firmware/point-table changes, against a real board | 0 all checks pass, 1 a check fails, 2 connection/protocol error | +| `verify_simulator_lan_bind.py` | After simulator bind-address/CLI change or before a LAN bench session | 0 wildcard listener and local handshake pass, 1 assertion fails, 2 missing exe/tooling error | +| `verify_simulator_duration_evidence.py` | Before quoting STOP-summary counters, when a clean finite-duration run is needed | 0 refusals/clock/completion and exit status pass, 1 behaviour fails, 2 startup/read error | + +## 前置条件 + +- Real board: powered, reachable at `192.168.31.100`, firmware IEC104 listener on `2404`, + profile table matching `App/protocol/iec60870/examples/iec104_dtu_profile.h`. +- Simulator: `simulator/build/Debug/lvgl_sim.exe` built with IEC104 headless CLI, + chosen port free, Windows `Get-NetTCPConnection` available for the LAN bind probe. +- All three scripts are Python 3 standard library only. They print ASCII only and + use exit codes as their verdict; redirect stdout/stderr to a log file for evidence. +- `verify_board_acceptance.py` imports `wire.py` beside itself; run from anywhere with + `python /test/host/iec104_dtu/verify_board_acceptance.py ...`. + +## 怎么跑 + +From repository root: + +```bash +python -B test/host/iec104_dtu/verify_board_acceptance.py --help +python -B test/host/iec104_dtu/verify_board_acceptance.py --host 192.168.31.100 --port 2404 + +python -B test/host/iec104_dtu/verify_simulator_lan_bind.py --help +python -B test/host/iec104_dtu/verify_simulator_lan_bind.py --duration 12 + +python -B test/host/iec104_dtu/verify_simulator_duration_evidence.py --help +python -B test/host/iec104_dtu/verify_simulator_duration_evidence.py \ + --exe simulator/build/Debug/lvgl_sim.exe --port 24040 --duration 10 \ + --output ci-artifacts/iec104-tests/duration-evidence +``` + +## 判据 + +- Board: GI terminates; all mapped measurements present; `SP 59/59` and `DP 16/16`; + command `C_SC_NA_1` is refused with COT 7 and P/N=1; `C_CS_NA_1` is confirmed. +- LAN bind: OS listener is `0.0.0.0` owned by the simulator PID; STARTDT handshake replies + `68040b000000`; process exits 0 and the listener disappears. This is same-host evidence + only, not proof that another LAN device can pass through a firewall. +- Duration evidence: two refused `C_SC_NA_1` commands produce only COT 7/P/N=1; no COT 10 + or COT 11 follows; clock read replies; simulator exits 0 and `simulator.log` contains + its STOP summary line with `simulated_actions=`. + +## 分类与历史来源 + +`PROBE_INDEX.md` lists every rescued script and its A/B/C disposition. One-off design +measurements were intentionally not placed in `test/host/`; their original paths under +`ci-artifacts/` are ignored by git and may disappear, but they are not needed to repeat +protocol acceptance. diff --git a/test/host/iec104_dtu/verify_board_acceptance.py b/test/host/iec104_dtu/verify_board_acceptance.py new file mode 100644 index 00000000..05e6cbc9 --- /dev/null +++ b/test/host/iec104_dtu/verify_board_acceptance.py @@ -0,0 +1,164 @@ +"""Board-side IEC 60870-5-104 acceptance probe (read-only, no state changes). + +Run this when a real DTU board at 192.168.31.100:2404 must be re-accepted after +a firmware or point-table change. It performs STARTDT, a station general +interrogation, checks every mapped measurement and DTU signal is reported, then +proves command refusal and clock confirmation. +Prerequisites: the board is powered, its 104 listener is reachable, and the +point table matches iec104_dtu_profile.h. An unreachable board, a non-104 +listener or bad frame sequence exits 2; a missing point or an unexpected +command reply exits 1. +""" +import argparse +import socket +import struct +import sys +import time +from pathlib import Path + +HERE = Path(__file__).resolve().parent +sys.path.insert(0, str(HERE)) +import wire # noqa: E402 + +HOST = "192.168.31.100" +PORT = 2404 + +# IOA -> label, from the DTU profile table (iec104_dtu_profile.h). +# NOTE: s_meas_map[] in iec104_serv.c is keyed by source address (0x9605 etc.), +# NOT by IOA. The wire carries IOA, so the probe must look up 0x400C.. here. +MEAS = { + 0x400C: "UA", 0x400D: "UB", 0x400E: "UC", 0x400F: "UN", + 0x4015: "IA", 0x4016: "IB", 0x4017: "IC", 0x4018: "IN", + 0x4007: "freq", 0x4003: "temp", +} +YX_SP = 0x0001 # singles start here, 59 points +YX_DP = 0x1001 # doubles start here, 16 points + + +def parse_args(): + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument("--host", default=HOST, help="board IPv4 address") + parser.add_argument("--port", type=int, default=PORT, help="board IEC104 TCP port") + return parser.parse_args() + + +def main(host, port): + problems = [] + gi_done = False + trace = [] + t0 = time.monotonic() + c = wire.Client(host, port, trace, timeout=8) + print("connected to %s:%d in %.0f ms" % (host, port, (time.monotonic() - t0) * 1000)) + c.start() + print("STARTDT confirmed (%.0f ms)" % ((time.monotonic() - t0) * 1000)) + + # General interrogation, QOI=20 (station), COT=6 ACT. + # Type 100 的载荷是 IOA(3) + QOI(1):漏掉 IOA 会让 ASDU 只有 1 字节, + # vendor IEC60870_Parse_ASDU_Header 判载荷不足 -> FRAME_ERROR -> 断链。 + c.request(wire.asdu(100, wire.u24(0) + bytes((20,)), cot=6)) + end = time.monotonic() + 25 + seen = {} + while time.monotonic() < end: + try: + frame = c.frame(time.monotonic() + 2.0) + except (TimeoutError, socket.timeout): + break + if frame[2] & 1: + continue # S/U 帧:control 域最低位为 1;只有最低位为 0 才是 I 帧 + data = frame[6:] + h = wire.header(data) + if h["type"] == 100 and h["cot"] == 10: + print("GI activation terminated") + gi_done = True + break + if h["type"] not in (1, 3, 9, 13, 30, 31, 34, 35, 36, 37): + continue + try: + for row in wire.objects(data): + seen.setdefault(row["ioa"], row) + except AssertionError as exc: + print(" decode issue:", exc) + problems.append("decode issue") + if not gi_done: + problems.append("GI not terminated") + + print("\n=== measurements (mapped by iec104_serv.c s_meas_map) ===") + for ioa, name in sorted(MEAS.items()): + row = seen.get(ioa) + if row is None: + print(" %-5s IOA 0x%04X : ABSENT" % (name, ioa)) + problems.append("measurement absent %s" % name) + else: + iv = "IV" if row.get("quality", 0) & 0x80 else "valid" + if row["type"] in (13, 36, 112, 206, 207): + shown = "%.4f" % row["value"] + else: + shown = str(row["value"]) + print(" %-5s IOA 0x%04X : type=%d value=%-10s quality=0x%02X %s" + % (name, ioa, row["type"], shown, row.get("quality", 0), iv)) + + print("\n=== DTU signals 59 SP + 16 DP ===") + sp_present = sum(1 for i in range(YX_SP, YX_SP + 59) if i in seen) + dp_present = sum(1 for i in range(YX_DP, YX_DP + 16) if i in seen) + print(" SP 0x%04X..0x%04X present %d/59" % (YX_SP, YX_SP + 58, sp_present)) + print(" DP 0x%04X..0x%04X present %d/16" % (YX_DP, YX_DP + 15, dp_present)) + if sp_present != 59: + problems.append("SP present %d/59" % sp_present) + if dp_present != 16: + problems.append("DP present %d/16" % dp_present) + iv_sp = sum(1 for i in range(YX_SP, YX_SP + 59) + if i in seen and seen[i].get("quality", 0) & 0x80) + iv_dp = sum(1 for i in range(YX_DP, YX_DP + 16) + if i in seen and seen[i].get("quality", 0) & 0x80) + print(" SP carrying IV: %d, DP carrying IV: %d" % (iv_sp, iv_dp)) + + print("\n=== totals ===") + by_type = {} + for row in seen.values(): + by_type[row["type"]] = by_type.get(row["type"], 0) + 1 + print(" distinct IOA reported:", len(seen), " by type:", dict(sorted(by_type.items()))) + print(" frames: tx=%d rx=%d" % (sum(1 for x in trace if x["direction"] == "tx"), + sum(1 for x in trace if x["direction"] == "rx"))) + + # Negative-path probes: commands must be refused, never confirmed. + print("\n=== command refusal (must not be confirmed) ===") + payload = wire.u24(0x6001) + bytes((0x01, 0x00)) + c.request(wire.asdu(45, payload, cot=6)) + try: + data = c.response(45, cot=7, pn=True) + print(" C_SC_NA_1 0x6001 -> COT 7 P/N=1 refusal (correct)") + except (TimeoutError, AssertionError) as exc: + print(" C_SC_NA_1 0x6001 -> UNEXPECTED:", exc) + problems.append("C_SC refusal unexpected") + + print("\n=== clock synchronisation (C_CS_NA_1) ===") + now = time.localtime() + cp56 = struct.pack(" COT 7 confirmed:", data.hex()) + except (TimeoutError, AssertionError) as exc: + print(" C_CS_NA_1 -> UNEXPECTED:", exc) + problems.append("C_CS confirmation unexpected") + + c.close() + + print("\n=== verdict ===") + print("FAILURES: %d" % len(problems)) + for item in problems: + print(" " + item) + return 1 if problems else 0 + + +if __name__ == "__main__": + parsed = parse_args() + try: + rc = main(parsed.host, parsed.port) + except (OSError, socket.timeout, TimeoutError, AssertionError) as exc: + print("PROTOCOL_ERROR %s" % type(exc).__name__) + rc = 2 + raise SystemExit(rc) diff --git a/test/host/iec104_dtu/verify_simulator_duration_evidence.py b/test/host/iec104_dtu/verify_simulator_duration_evidence.py new file mode 100644 index 00000000..672d4c91 --- /dev/null +++ b/test/host/iec104_dtu/verify_simulator_duration_evidence.py @@ -0,0 +1,120 @@ +"""Simulator duration-mode evidence: refused command, clock sync, clean STOP. + +Run when IEC104 simulator STOP-summary evidence is needed, especially because +run_tcp_test.py terminates the process before it prints simulated_actions. +This probe uses --iec104-duration so the headless loop exits on its own. +Prerequisites: a simulator binary supporting --iec104-headless and +--iec104-duration is available and the chosen port is free. +Exit 0 = refusals/completion/clock checks passed and simulator exited 0; +1 = a behavioural check failed; 2 = simulator could not be started or read. +""" +import argparse +import pathlib +import socket +import struct +import subprocess +import sys +import time + +ROOT = pathlib.Path(__file__).resolve().parents[2] +sys.path.insert(0, str(ROOT / "test" / "host" / "iec104_dtu")) + +from wire import Client, asdu, cp56, header, u24 # noqa: E402 + + +def wait_listen(host, port, deadline_s=15.0): + deadline = time.monotonic() + deadline_s + while time.monotonic() < deadline: + try: + with socket.create_connection((host, port), 0.2): + return + except OSError: + time.sleep(0.05) + raise TimeoutError("simulator did not listen") + + +def main(): + parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) + parser.add_argument("--exe", type=pathlib.Path, required=True) + parser.add_argument("--host", default="127.0.0.1") + parser.add_argument("--port", type=int, default=24040) + parser.add_argument("--duration", type=int, default=10) + parser.add_argument("--output", type=pathlib.Path, + default=ROOT / "ci-artifacts/iec104-tests/duration-evidence") + args = parser.parse_args() + + args.output.mkdir(parents=True, exist_ok=True) + log_path = args.output / "simulator.log" + trace = [] + problems = [] + + try: + with log_path.open("w", encoding="utf-8") as log: + process = subprocess.Popen( + [str(args.exe), "--iec104", "--iec104-headless", + "--iec104-port", str(args.port), "--iec104-duration", str(args.duration)], + cwd=str(args.output), stdout=log, stderr=subprocess.STDOUT) + try: + wait_listen(args.host, args.port) + client = Client(args.host, args.port, trace) + client.start() + + # 1) SELECT then EXECUTE on a command point: both must be refused. + client.request(asdu(46, u24(0x6002) + bytes((2 | 128,)))) + data = client.response(46, 7, pn=True) + assert header(data)["cot"] == 7, data.hex() + print("REFUSED select ioa=0x6002 cot=%d pn=%s" % + (header(data)["cot"], header(data)["pn"])) + + client.request(asdu(46, u24(0x6002) + bytes((2,)))) + data = client.response(46, 7, pn=True) + assert header(data)["cot"] == 7, data.hex() + print("REFUSED execute ioa=0x6002 cot=%d pn=%s" % + (header(data)["cot"], header(data)["pn"])) + + # 2) One clock sync so clock_sets is exercised (device-only, no OS clock). + stamp = struct.pack("