docs(skills): 明确 @build/@test/@task 为文档别名并新增 precheck/postmerge 命令
CI / 静态门禁 (pre-commit) (push) Failing after 3m45s
CI / 主机侧单测 (MSVC) (push) Failing after 43s

AGENTS.md「构建与验证」新增总口径:@build / @test / @task 都是本仓库的
文档别名、不是 shell 命令(2026-10-30 实测:bash 敲 @task / @build 即
command not found,dsh task 被解析成 profile 名报错);`=` 后的命令行
才是可执行形态,DSH 会话显式调用为 /keil-build、/serial-boot-test、
/task-worktree。

- AGENTS.md / docs/README.md / 并行任务工作树方案.md:@task 三处定义位
  由「短命令」统一改为「文档别名」,并写入两种实测失败形态
- keil-build / serial-boot-test SKILL.md:定义位点破别名性质;@test 在
  skill 内原先没有定义句,补口径 blockquote
- task-worktree SKILL.md 与 reference/:whenToUse、标题、症状表、插件桥
  去 @task 前缀改指 list / 本 skill;frontmatter 能力清单同步
- task_worktree.py 新增 precheck(树内只读自查:BOM 漂移 / CR / U+FFFD、
  docs 逐档门禁、--msgfile 消息 BOM/CRLF/行长/禁词检查,自动补
  ci-artifacts/)与 postmerge(主树体积凭证自动诊断:新鲜跳过、红先短链
  再只读复检裁定是否升全链;check_doc_links --all;列文件不代提交)
- done 快路径打印与门禁拦截提示均指向 postmerge

实测:precheck 对坏消息文件抓到 CRLF、行长 95>80、禁词×3(rc=1);
postmerge 端到端「凭证同码新鲜→跳链→doc --all 绿(2967 章节引用 /
214 文档)→列 dirty 文件」rc=0;check_skill_size.py 与 py_compile 通过;
frontmatter 改动后 DSH 已用新值真加载过一轮。无 .c/.h 改动,不涉及体积。
This commit is contained in:
2026-10-30 10:25:05 +08:00
parent a157b443cb
commit 2be49dc9dd
9 changed files with 176 additions and 148 deletions
+2 -1
View File
@@ -79,6 +79,7 @@
## 构建与验证
- **门禁时机(用户裁定 2026-10-13)**:`@build` / `scripts/ci_local.py` / `check_doc_links.py` **只在准备提交时跑**(用户让 commit 后统一跑一遍),**不是每次中间改动后都跑**——多步改动期间直接改即可,验证集中在提交门禁;`@test` 硬件闭环仍按任务需要跑
- **`@build` / `@test` / `@task` 都是本仓库的文档别名,不是 shell 命令**(2026-10-30 实测:bash 里直接敲 `@task` / `@build` 是 command not found,`dsh task` 会被解析成 profile 名报错)——下面 `=` 后的命令行才是可执行形态(PowerShell 形态,bash 下路径正斜杠);DSH 会话显式调用 skill 用 `/keil-build`、`/serial-boot-test`、`/task-worktree`
- `@build` = `& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py`(仓库根执行)。退出码 **0=PASS / 1=构建失败 / 2=环境错误(UV4/工程/档案)/ 3=用法 / 4=build 锁被占用**;日志 `MDK-ARM/build_log.txt`;换机必设 `DTU_KEIL_UV4` → 细节 **`keil-build` skill** + `docs/环境与部署/本地工具路径环境变量方案.md`
- `@test` = `& '.venv\Scripts\python.exe' .dsh\skills\serial-boot-test\scripts\run_boot_test.py`:开串口+清日志 → 烧录(**固件身份戳**保证烧进去的就是这份构建、**回读校验**)→ wait-idle → 采日志 → 标记校验(含启动锚点计数)。退出码 **0=PASS / 1=FAIL / 2=采集或烧录错误 / 3=用法**;戳提取规则、锚点计数判据与按模块定制标记见 `docs/测试说明/流程与规范/自动化测试流程.md`
- Forbidden 标记含 `[ERR]`:**四个 Fault 的崩溃日志都以 `[ERR]` 开头 → 出现 Fault 即本次不通过**(刻意)
@@ -185,6 +186,6 @@
| 串口助手 | **`serial-assistant` skill**(命令/判据/陷阱,用到自动加载)、`docs/测试说明/测试工具/串口助手使用指南.md`、`串口助手设计说明.md` |
| UI 架构 / 模拟器 / UI 自动化回归 | **`lvgl-simulator` skill**(构建/自检/报错速查,用到自动加载)、`docs/UI设计/UI_设计架构.md`、`LVGL模拟器部署与使用说明.md`、`UI_自动化测试流程.md`;UI 改动回归走 **`ui-verify` skill** |
| 待办与审计发现登记簿 | `docs/任务规划/README.md` |
| 多任务并行开发(开空间 / 合并回收 / 台架与构建排队);**DSH worktree 插件的仓内树怎么接上**(`.dsh-worktrees/` 缺 `.venv`、`plugin adopt`、锁归属 `pw:<name>`) | **`task-worktree` skill**(`@task`,用到自动加载;插件桥 → 其 F 节)、`docs/环境与部署/并行任务工作树方案.md` §3.4 |
| 多任务并行开发(开空间 / 合并回收 / 台架与构建排队);**DSH worktree 插件的仓内树怎么接上**(`.dsh-worktrees/` 缺 `.venv`、`plugin adopt`、锁归属 `pw:<name>`) | **`task-worktree` skill**(`@task` 仅为文档别名非可执行命令,显式调用 `/task-worktree`,用到自动加载;插件桥 → 其 F 节)、`docs/环境与部署/并行任务工作树方案.md` §3.4 |
| 换机 / 工具路径环境变量 | `docs/环境与部署/` |
| 远程 CI(Gitea Actions,**只跑本机一台 runner**) | [`docs/CI/README.md`](docs/CI/README.md) |