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
+1 -1
View File
@@ -252,7 +252,7 @@ docs/
| 文档 | 内容 |
|---|---|
| [`项目部署环境要求.md`](环境与部署/项目部署环境要求.md) | 开发机软件环境、目标板资源预算、现场部署与验收步骤 |
| [`并行任务工作树方案.md`](环境与部署/并行任务工作树方案.md) | **多任务并行开发机制**:`git worktree` 隔离、目录与共享/独占分配(junction 规则)、`task-worktree`(`@task`)SKILL 命令面、单写者文档与合并残留审计、台架锁;**已落地并端到端实测**(见其 §11) |
| [`并行任务工作树方案.md`](环境与部署/并行任务工作树方案.md) | **多任务并行开发机制**:`git worktree` 隔离、目录与共享/独占分配(junction 规则)、`task-worktree` SKILL 命令面(`@task` 仅为文档别名,显式调用 `/task-worktree`)、单写者文档与合并残留审计、台架锁;**已落地并端到端实测**(见其 §11) |
| [`CI/README.md`](CI/README.md) | **远程 CI(Gitea Actions)唯一入口**:服务端开关 / runner 部署与保活 / workflow / 排障。**只涉及本机一台 runner `win-stm32-ci`,其他机器与项目都不涉及**;日常改代码用本地门禁 `scripts/ci_local.py`,不必读这里 |
### 9.3 台账与外部资料
@@ -100,7 +100,7 @@ D:/Code/DTU Code/
本仓现在有**两套**隔离空间并存,这是**有意接受**的现状,不是待清理的重复建设:
| 维度 | 本方案(`@task` skill) | DSH 插件 `dsh-task-worktree` |
| 维度 | 本方案(`task-worktree` skill) | DSH 插件 `dsh-task-worktree` |
|---|---|---|
| 树的位置 | 仓库外 `../_wt/`(§3.1) | 仓库内 `.dsh-worktrees/worktree/`(插件写死,不可配置) |
| 面向的粒度 | 任务(周级、要合并回主干、要过门禁) | 会话(一次对话一个空间,零命令起步) |
@@ -110,7 +110,7 @@ D:/Code/DTU Code/
两条**并发红线由本方案单方守住**(插件不感知):`build`(UV4 单实例)与 `bench`(COM6 / ST-LINK /
设备 IP 唯一)这两把锁的位置与 TTL 口径见 §7.1 / §7.2——插件树里跑 `@build` 时,`keil_build.py`
会照旧自持自释,持有者名从 cwd 反推为 `pw:<name>`;`bench` 仍须手工占同一个名。共享联接(§3.3)
插件不会建,由 `@task plugin adopt <name>` 补。
插件不会建,由本 skill 的 `plugin adopt <name>` 补(执行体命令行见 §8)。
**为什么允许它在仓内破例**(与 §10「绝不在仓库内部」的口径冲突处):路径根写死在插件里,且暴露给
模型的工具只有 create/list/status 三个。兜法是把该目录登记进**全库扫描**的排除面(`check_doc_links`
@@ -264,7 +264,7 @@ D:/Code/DTU Code/
## 8. SKILL 设计
**名称**:`task-worktree` **短命令**:`@task`(沿用本仓库 `@build` / `@test` 的 `@` 惯例)
**名称**:`task-worktree` **文档别名**:`@task`——**只是沿用 `@build` / `@test` 惯例的文档记号,没有任何执行机制**:shell 里敲 `@task` 直接 command not found,`dsh task` 会被当 profile 名报错(2026-10-30 实测);DSH 会话里的显式调用是 `/task-worktree`,可执行形态只有下面的执行体命令行。
**执行体**:`.dsh/skills/task-worktree/scripts/task_worktree.py`(纯标准库,
照 `keil_build.py` 的写法,整目录可拷到别的项目复用)。**已落地并端到端实测**(见 §11)。