docs(技能渐进展开): 五个技能正文逐字外置到 reference/，主文只留索引与指针
按「主文留头量、深规程外置」重写本仓技能，全部是逐字搬移：
搬移前断言原文每条非空行必须出现在新主文或 reference 文件里，
0 丢失才落盘；步骤编号一律不重排（正文有「第 12 步」交叉引用）；
每个切点保留原小标题 + 索引（加粗引导句与步骤标题）+ 指针行。
主文变化（上限口径 = 插件写侧 65536 字节，见上一笔 skill-size 钩子）：
- id-family-semantic-migration 33392 -> 10968（17%），reference 3 篇
- stale-doc-count-sweep 19811 -> 6945（11%），reference 2 篇
- mem-budget 19963 -> 13042（19%），reference 3 篇
- keil-build 12917 -> 8879（14%），reference 2 篇
- task-worktree 72601 -> 28139（42%），reference 8 篇
task-worktree 本笔同时收录另一会话已写完的 C2/D/G 三节正文——那
三处手改与我的拆分落在同一份文件改动里，不可分离；其内容同样已
随 reference/ 外置，主文只剩标题、索引与指针。
外置语料合计 122211 字节 / 30 篇：围栏数逐篇为偶，无 BOM/CR/U+FFFD。
draw-diagram 与 serial-boot-test 脚本是另一会话的在飞改动，本笔未含。
skill-size 钩子在本笔首次真跑（前一笔无 .dsh/skills 文件可触发）。
gate: pre-commit 全绿（doc-links、id-check-new、check-yaml、
skill-size、check-added-large-files）；30 篇 reference 手工字节
体检 clean；skill() 逐个复载确认加载的是拆分版。
This commit is contained in:
@@ -32,132 +32,34 @@ version: 1.1.0
|
||||
|
||||
## Steps（字母+数字族：门禁看得见的那一路）
|
||||
|
||||
1. **确认范围与定调**：先按开头的表判识别面（无识别面 → 走下一节）；再读 `docs/编号规范.md` §4.1（族总表，穷举）、§4.1.1（已停发栏），存量与批次见 `scripts/archive/id_gate/编号治理历史.md` §9，明确本族属主登记处（`owner_docs_glob`）与判据「有脚本按字面量匹配它」。清退 = 全仓改语义；停发 = 游标冻结、只减不增。
|
||||
2. **按族实测三口径（字面量 / 站点 / 文件），不用 grep 估数**。`Checker.refs` 是 **dict（字面量 → 文件集合）不是方法**，`ck.refs(fam)` 这种写法会 `TypeError`；站点数门禁不直接给，用族正则重扫它自己的语料：
|
||||
```python
|
||||
import sys; sys.path.insert(0, "scripts")
|
||||
import check_ids as ci
|
||||
reg = ci.load_json(ci.REGISTRY_FILE, "r"); al = ci.load_json(ci.ALIASES_FILE, "a")
|
||||
ck = ci.Checker(reg, al); ck.run() # run() 填充 refs / stats / findings
|
||||
for name in ("N", "S-LDG", "TC", "FEAT"): # 族名以 id_registry.json 的 "name" 为准
|
||||
rx = next(f for f in ck.families if f["name"] == name)["_re"]
|
||||
lits = {l for l in ck.refs if rx.fullmatch(l)} # 字面量（属主文档之外）
|
||||
files = {r for l in lits for r in ck.refs[l]} # 文件
|
||||
sites = sum(len(rx.findall(line))
|
||||
for rel in ck.iter_files() # 与门禁同一语料
|
||||
for line in ck.read(rel).splitlines()) # 含属主文档定义行
|
||||
print(name, "literals", len(lits), "sites", sites, "files", len(files))
|
||||
```
|
||||
全库扫一遍不便宜（数十秒量级）：可丢后台 job，不要和别的长活串在同一个 120s 预算里。把活族清单与每族数字记下来作为**动手前基线**（拆批次与派单依据）。新测试套件发号导致 `id-check` 校验 3 报悬空引用时，**先按号前缀聚合**定位是哪个套件/哪个族（`check_ids.py 2>&1 | grep -a '悬空引用' | ...` 前缀计数），别逐条读。
|
||||
3. **逐族先分类再动手**——不是每个命中的裸形都是编号，四类分治（实测 T1/T2/T3 的 41 处里只有部分是编号）：
|
||||
- 真编号 → 语义短语 / 功能名；
|
||||
- 硬件位号（变压器 T1~T3 等）→ 把目录整目录登记进 `check_ids` 的 `excluded_paths`（如 `excluded_paths += tools/netlist_semantics/`），**不逐处改位号名**；
|
||||
- Mermaid 流程图节点名 → 改语义名但**节点数与连线关系不变**，图结构不动；
|
||||
- 数学记号 → 进噪声表；门禁自身的规则名（gitlint `T2 Title has trailing whitespace`）→ 不改。
|
||||
分类前先把剩余每处原文打出来看（`grep -F` 逐文件），否则会把硬件资料改坏。
|
||||
4. **映射表由属主文档生成**：从属主文档取「编号 → 功能名/语义短语」全表（实测 42 个定义 / 28 个在用），改名走 `scripts/rename_ids.py`（映射表驱动 + **显式 scope** + **默认干跑** + 自动往 `scripts/archive/id_gate/id_aliases.json` 写 scoped 旧号→新号条目，状态 `renamed` / `retired-to-phrase` / `void`）。**绝不全局查找替换**：同一裸形字面量可能同时属多个族（实测 `S3` 三义），全局替换等于造新撞号。
|
||||
5. **按写域拆道并行派单**（代码与测试半 / 文档半 / 某功能面各一条道），同笔用 `send_message` 下发**统一改写口径**（措辞、是否动字符串字面量、生成器归属、冻结历史行怎么处理），避免各道自定措辞；口径长就先落成 spec 文件（中文族一节第 5 步的做法同样适用）。看板任务只认 `team_task_update` 的 `task_id` / `expected_revision` / `action=reassign` / `owner` 四个字段。
|
||||
6. **门禁配置注释也是本族写入面**：`.pre-commit-config.yaml` 的注释里会挂着功能号（实测 `7h) ADC 采样有效性校验（语义取数与有效性层）`、`7i) 保护定值模型（P1 / 动作留痕层载体）`、`规划 §3.3 保护判据层`）。配置属 Lead 写域，Lead 自己改（注释不占钩子行为、不影响 51 条钩子口径），但**必须计入批次范围并在提交正文写清是 Lead 改的 config**。
|
||||
7. **每处替换断言命中数**，不做整文件正则批量改写（批量改写会静默漏改）：
|
||||
```python
|
||||
def sub(path, pairs):
|
||||
p = pathlib.Path(path); t = p.read_text(encoding='utf-8')
|
||||
for old, new, want in pairs:
|
||||
got = t.count(old); assert got == want, (path, old, got, want)
|
||||
t = t.replace(old, new)
|
||||
p.write_text(t, encoding='utf-8')
|
||||
```
|
||||
**token 取最小形态**：文档里被反引号/加粗包住的号，替换单位取反引号形（```T4```）而**不含 `**` 标记**（第 225 行是 `**裸形 `T4`**`，按「裸形 `T4`」替就命中 0）。讲编号的文档改成**形态描述**（如「字母 T 紧跟数字 4」）能把不可判定绝对数还回余量：实测 4 处 → 982 降到 978，且 lesson 不丢。
|
||||
8. **同步更新门禁侧配置**：`check_ids` 的 `excluded_paths` 与噪声表按第 3 步的分类结果改，使剩余命中不再是「假编号」；新测试套件发号的悬空引用要先定**定义位**：
|
||||
- 定义位**只能落一处**——注册表族（`scripts/archive/id_gate/id_registry.json`）或该套件说明文档，**两处并存比没有定义位更坏**；文档真写出来了（含判据与上板清单）就以文档为准、**撤族**；
|
||||
- 要建族就照现有同类族克隆（`pattern` / `digit_width` / `owner_docs_glob` / `scope` / `cursor`），别自造字段；
|
||||
- **抬游标前先确认游标是字符串形态**（`'cursor': 'TC-UIDATA-026'`）——整型比较会静默不生效（实测踩坑），用字符串解析或正则取序号再比。
|
||||
9. **生成器文本改动必须同笔重跑产物**：`tools/arch_diagram/gen_*.py` 里的 docstring/文案会进产物，`generated-fresh` 把生成器拷到临时目录重跑逐字节比对，**只改源不改产物必红**。这类站点整包转给生成器属主，「谁改谁跑生成器」，脚本 + 全部 svg 产物同一笔：
|
||||
```bash
|
||||
./.venv/Scripts/python.exe tools/arch_diagram/gen_net_instability_svg.py 2>&1 | tail -3
|
||||
pre-commit run generated-fresh --all-files # 单钩子复跑必须带 --all-files 或 --files
|
||||
```
|
||||
⚠ **不带这两个参数的裸 `pre-commit run` 会进 staged_files_only 上下文并 stash 别道在飞的改动**（`docs/门禁说明/generated-fresh.md` §2）；`pre-commit` 不在 PATH 时改用 `& '.venv\Scripts\python.exe' -m pre_commit run generated-fresh --all-files`。PASS 后再目检 diff：只应文字变长、框宽自适应（526→551、右缘未越界、画布不变）。不把该站点从批次里悄悄丢掉：登记为「待未完成半批」，收口时核对。
|
||||
10. **核队友交付**（按写域并行后必做）：
|
||||
- 文件清单**先展开真实路径再比**：按简称匹配会误报丢失（作者列 `phasor.py`/`adc_health.py` 等 8 个，实为 `test/host/<模块>/run_unit_test.py`）；用 `git -c core.quotepath=false diff --name-only` 取全路径做集合差。
|
||||
- 合并指纹对不上先问口径：作者按**自定义顺序**算的数 Lead 侧复现不了（`d0a289b7` vs 报的 `a45e7e2b`）。改建 **Lead 自有逐文件 16 位基线**存 `ci-artifacts/lead_lane_b_files.json`，并把**跨道文件单列**（实测 `App/algo/README.md`）——autostash 后按逐文件比对，不假称对上别人的合并数。
|
||||
11. **分笔提交走真实 pre-commit 钩子**：`git add` 用显式清单。坑：`git add -- App/algo` 把文档道的 `App/algo/README.md`（26 处）带上车，正文按 48 只文件写就不准了 → 该笔未 push 时 `--amend` 挪到文档笔并补一句归属说明；`git add -A` 会把别道在飞文件卷进来（覆盖率钩子在他编译不过的半成品上报红）→ 撤出他人域后重跑。提交正文每行 ≤80（gitlint B1），别把 ASCII 双引号写成正文首字符。
|
||||
12. **收口只认门禁自身计数**（**仅限语料内的族**；无识别面族见下一节第 8~9 步），并核**只减不增**：
|
||||
```bash
|
||||
./.venv/Scripts/python.exe scripts/archive/id_gate/check_ids.py 2>&1 | grep -aE '扫描|可判定 |不可判定引用' | head -4
|
||||
./.venv/Scripts/python.exe scripts/archive/id_gate/check_ids.py --strict 2>&1 | tail -1 # [OK] 校验 1~6 无错误
|
||||
```
|
||||
报告「字面量 8787→8299→7828」「不可判定绝对数 1161→984→982→978（上限 1166）」「可判定比例 88.14%（基线 86.0%，容差 0.1pp）」。**绝对数与比例两根线都要报**：把可判定引用改成散文会稀释比值，所以另有不可判定绝对数上限。涨点归因见「净室归因」一节。
|
||||
13. **回写 `docs/编号规范.md`**：§4.1 族表（停发/待清栏）、§4.1.1 已停发栏、§9 存量表与批次结果表（只减不增）、§9 清点数字按最终实测同步；表格若保留动手前的清点数，**明确标注「不是当前存量，是动手前基线」**，否则就是拿旧数当现状。**用户裁定原文与理由直接写进对应节**（§4.1.1 停发行 + 该族的批次结论段落）——2026-10-28 起不再往变更记录写流水（`docs/文档规范.md` §5.1）。
|
||||
14. **裁定「不做」也要写成可执行硬口径入档**（不是只划掉一行——「不做」最容易被读成「那还可以继续发号」）：
|
||||
- §4.1.1「已停发」栏新增该族一行：**游标冻结、现存号只减不增、新用例改用语义化测试函数名 + 文档表格行名**，并写清与「允许继续发号」栏为何不打脸；
|
||||
- §9.1 批次段落写明裁定原文与理由（该族是唯一真被脚本按字面量匹配的族：C 断言标签 + 测试函数名 + 文档用例表三处同一号），并给出**将来真要清退的前置条件**：追溯器（`check_test_traceability.py`）先同时认新旧两种形态、并行核对通过，**不许先改文档再改代码**；
|
||||
- 全文核「等你裁定 / 需你裁定」悬空表述残留数归 0；
|
||||
- 无机器识别面的族落地面不同（§4.1.1 一行 + §9.3 换算表 + 叙述同步三处），见下一节第 7 步。
|
||||
1. 确认范围与定调
|
||||
2. 按族实测三口径（字面量 / 站点 / 文件），不用 grep 估数
|
||||
3. 逐族先分类再动手
|
||||
4. 映射表由属主文档生成
|
||||
5. 按写域拆道并行派单
|
||||
6. 门禁配置注释也是本族写入面
|
||||
7. 每处替换断言命中数
|
||||
8. 同步更新门禁侧配置
|
||||
9. 生成器文本改动必须同笔重跑产物
|
||||
10. 核队友交付
|
||||
11. 分笔提交走真实 pre-commit 钩子
|
||||
12. 收口只认门禁自身计数
|
||||
13. 回写 docs/编号规范.md
|
||||
14. 裁定「不做」也要写成可执行硬口径入档
|
||||
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [steps-alpha-numeric-family.md](reference/steps-alpha-numeric-family.md)。动手前先读那篇。
|
||||
|
||||
## Steps（中文前缀族：门禁咬不到的那一路）
|
||||
|
||||
1. **先确认门禁咬不到，并把这句话写进交付**：`scripts/archive/id_gate/check_ids.py` 的族 pattern 是拉丁形态、中文前缀不进语料 → **id-check 的 refs / 可判定比例 / 悬空引用与本族无关**；报告开头写「本族不在 check_ids 语料内，口径 = 自建扫描器」。
|
||||
2. **销项删行前先核证据属主**（这是删行的唯一许可证）：
|
||||
- 先取历史口径：`git log --oneline -20 -- <文档>`、`git show <rev>:<文档> | sed -n '/^## 5/,/^## 6/p'` 找回被删的卡表与当初「完成即销项删行 / 标 ✅ 保留行」的理由；
|
||||
- 核对判据与实测记录**已完整沉淀进属主章节**（实测：「已知电压注入验证」六项判据全 PASS、斜率 6544.2 码/V、偏差 −0.14 % 全在 `docs/硬件平台/ADC通道映射说明.md` §8.1，执行侧在 `docs/测试说明/ADC前端注入验证流程.md`）；
|
||||
- **删的是任务规划侧的行与结论块，不是证据本体**；被代码头注释指称的设计约束章节（§2~§4 那类）**原样保留**，只删已完成记录；
|
||||
- 该行若当初是被「代码头注释按号引用」当例外保住的（实测 `App/task/adc_task.c` 的 v3.3 修订行按卡号当口径出处），必须**先把引用侧改成语义短语**，例外才成立撤销，并在规范里写明撤销理由（上一笔「完成即保留行」的例外就是这么随引用侧改动被撤掉的）；
|
||||
- 删完逐行通读被改小节，报**行数变化**，不留孤立残句（实测 J7 dropped line 234 len=639、J13 闭环结论块 6 行删除并注明证据属主）。
|
||||
3. **自建带标签正则扫描脚本**——四条硬规矩，全是实测返工换来的：
|
||||
- 脚本**落文件**（`ci-artifacts/scan_ka_refs.py`）再跑，**不用 bash heredoc**（heredoc 里的 `\s` 被多层引号咬坏：`SyntaxWarning: invalid escape sequence` + 语法错）；
|
||||
- 正则**一律 raw 字符串**、汉字写 `\uXXXX`：`KA = r"\u5361"`。非 raw 串里 `"\b"` 会先被 Python 解成退格符（0x08）→ 正则**静默失配且不报错**；`"\s"` 只是警告还能跑，`"\b"` 是真错；
|
||||
- **排除 `.git`**（连同 `.venv`、`ci-artifacts`、`__pycache__`、`node_modules`）——实测扫进 `.git/COMMIT_MSG_*.txt`，一堆 GBK 乱码历史被当成残留，越清越多；
|
||||
- 报告**写 UTF-8 文件**（`ci-artifacts/ka_refs.txt`）再本地解析，别靠控制台输出（Windows 控制台按 GBK 渲染中文 = 乱码）；判乱码统计 `EF BF BD` 字节数，别信终端渲染。
|
||||
|
||||
```python
|
||||
# -*- coding: utf-8 -*-
|
||||
"""扫描中文前缀任务卡号与同期形似噪声号；报告写 UTF-8 文件。"""
|
||||
import io, os, re
|
||||
KA = r"\u5361" # 卡
|
||||
PATS = [("CARD_ANY", re.compile(KA + r"\s*[0-9]")),
|
||||
("KA0B", re.compile(KA + r"\s*0b")),
|
||||
("KA12", re.compile(KA + r"\s*12")),
|
||||
("M4", re.compile(r"\bM4\b")),
|
||||
("M5", re.compile(r"\bM5\b")),
|
||||
("M6", re.compile(r"\bM6\b"))]
|
||||
SKIP = {".git", ".venv", "ci-artifacts", "__pycache__", "node_modules"}
|
||||
out = io.open("ci-artifacts/ka_refs.txt", "w", encoding="utf-8")
|
||||
for root, dirs, names in os.walk("."):
|
||||
dirs[:] = [d for d in dirs if d not in SKIP]
|
||||
for n in names:
|
||||
p = os.path.join(root, n)
|
||||
try:
|
||||
txt = io.open(p, encoding="utf-8", errors="ignore").read()
|
||||
except OSError:
|
||||
continue
|
||||
for i, line in enumerate(txt.splitlines(), 1):
|
||||
for tag, rx in PATS:
|
||||
if rx.search(line):
|
||||
out.write("===== %s\n" % p) # 同一行可命中多标签 → 按标签分别计数
|
||||
out.write("%d [%s] %s\n" % (i, tag, line.strip()[:200]))
|
||||
out.close()
|
||||
```
|
||||
末尾打 `TOTAL_SITES / FILES / SCANNED / 各标签计数`；**带标签**才拆得开噪声（同一行可同时命中 `CARD_ANY` 与 `KA12`）。
|
||||
4. **该族与形似噪声号分开计数，各自给分母**：一遍扫描出 `TOTAL_SITES 420 FILES 85 SCANNED 1025`，必须再拆成**卡族 288 处 / 56 文件** 与 **里程碑噪声 132 处 / 44 文件**（`M4/M5/M6` 大片落在 `docs/芯片手册/` 参考手册与料号上下文里）。两套数字各自给分母——**「420 处待改」是错的**：把 132 处噪声算进清退范围就会去改芯片手册原文。噪声侧一律保持原样，是否清退等用户单独裁定，**不要顺手做**。
|
||||
5. **派单前写一份 spec 文件**（`ci-artifacts/card_retire_spec.md`），作为各道唯一口径来源，含五块：① 背景与**用户裁定原文**；② 逐号映射表（旧号形态 → 语义短语 → 属主出处）；③ 措辞规则（补短语时括号怎么降级、动不动字符串字面量、生成器归属、悬空引用怎么判）；④ 硬约束（BOM 原样补回、行尾由 `.gitattributes` 写死、冻结历史行与原始证据不回改、代码头注释引用的设计约束章节保留、带 BOM 文件名单）；⑤ 自检与交付格式（逐文件命中数、删了哪几行、残留数、门禁复跑结果）。`send_message` 只发路径 + 关键裁定，长中文正文不要整段塞进消息（一次串多条长消息会撑爆 120s，发出 1 条后 abort，剩余未发）。
|
||||
6. **逐处替换断言命中数**（同第 7 步的 `rep(tag, old, new, want)`），且 `old` 串**从原文取、不凭记忆敲**：本仓中文引号与 ASCII 双引号混用（实测某文档里的「中文引号」其实是 ASCII `"`），凭印象写 `old` 必 `got=0`；断言抛错后先 `git status --porcelain=v1 -- <文件>` 自证文件未被别道改动，再回读该行真身重跑。删行类改动单独记 tag 并打印删了几行、行号与原行长度。多道并行时同一文件常被别道改过：`edit` 报 `file changed since it was read` → 重新 `read` 再改；报 `ReplaceFileW EIO (Win32 1175)` → 先自证文件字节完好（BOM / CRLF / `EF BF BD` 三项）再重试同一笔，不要顺手改内容。
|
||||
7. **落地位置写死（这一族只有这几条兜）**：
|
||||
- `docs/编号规范.md` **§4.1.1「已停发的族」表加一行**，三列齐全，第三列直写「⚠ **机器面空白**：中文前缀不进 `scripts/archive/id_gate/check_ids.py` 语料 → 门禁咬不到，只有本表 + §9.3 + 评审三条兜；`id_aliases.json` 刻意不登记（登记了机器也看不见，只多一张没人核的表）」；
|
||||
- `docs/编号规范.md` **§9.3 逐号换算表**（旧号形态 → 语义短语 → 现行口径出处；本族实测 14 行 = 0、0b、1~12）+ §9 批次段落（裁定原文与逐号结论都落在正文），**写明旧号永久作废、不得重新取走**；
|
||||
- 表内**把形态写成「卡」+ 数字而不复述字面量**：规范本身是门禁语料，复述字面量会把「讲规则的文档」变成自己的引用站点；
|
||||
- **同步叙述**：`AGENTS.md`「文档与图形」的销项条目、`docs/README.md`（例：`数据可信.md = 三项阻塞任务` → 两项）、`docs/任务规划/README.md`、`docs/任务规划/登记簿.md`——「剩余三项」这类旧口径实测归零；
|
||||
- **与有识别面族的判别写进同一张表**：能被脚本按字面量匹配 → 走 `rename_ids.py` + 别名登记；匹配不到（中文前缀、纯散文号、圈号）→ 走规范换算表，**不登记别名**；
|
||||
- 要机械化怎么办：得先给「中文前缀 + 数字」设计候选形态，属追溯机制改造，按 §7.3 单独开卡，**别夹在清退批里顺手做**。
|
||||
8. **替换后三道二次清洗**（缺一必留疤，全部实测过）：
|
||||
```bash
|
||||
git grep -c -F '端子 / 子板变比确认' -- . ; git grep -c -F '端子/子板变比确认' -- . # 先数各形态再归一
|
||||
git grep -nE '卡[ ]*[0-9]' -- . ; echo "rc=$?" # 裸跑读 rc；1 = 归零
|
||||
```
|
||||
- **同句重复短语**：编号位置补上的语义短语与原句已有短语撞车 → 扫「同一行里同一短语出现 ≥2 次」（实测 12 行，如 `.pre-commit-config.yaml:401`「运行参数段（「数据可信」运行参数段交付）」、`App/algo/README.md:110`「遥测快照发布（L2 发布侧，「数据可信」遥测快照发布）」）→ 改法是**把括号里的引用降级**成不含该短语的写法（「道D 交付项」「波次」「该点 DoD 原句」），逐处断言命中 = 1，别删信息；
|
||||
- **空格与引号形态归一**：同一语义短语可能有 `端子 / 子板变比确认` 与 `端子/子板变比确认` 两种形态 → **先 `git grep -c -F` 分别数**（实测带空格 8 处），再整文件归一，归一后复扫到 0（残留常藏在表格单元格里，逐行打印定位）；引号形态同理；
|
||||
- **固定正则复扫**：`卡[ ]*[0-9]` 全仓无输出。⚠ 判 rc 时**不要把命令接在 `| head` 之后再读 `$?`**（那拿到的是 `head` 的 0，会把「还有残留」读成「已归零」）。
|
||||
9. **收尾复跑 + 清中间产物**：`check_ids.py`（plain 与 `--strict`）、`check_doc_links.py --all`、bom 与乱码两道（`pre-commit run bom-guard --files <改过的文件>`、`pre-commit run no-mojibake --files <改过的文件>`）、`git diff --check`；**纯注释/纯文档改动不算免编译**——仍跑一次 `@build` 取「0 错误 0 警告」且 `Program Size` 与改前同数（**本回合真跑**，引用历史提交正文自报的四个数不算），受影响的主机组单测照跑。最后**删掉 spec 与全部扫描中间产物**，别往 `ci-artifacts/` 再堆 log/txt。
|
||||
1. 先确认门禁咬不到，并把这句话写进交付
|
||||
2. 销项删行前先核证据属主
|
||||
3. 自建带标签正则扫描脚本
|
||||
4. 该族与形似噪声号分开计数，各自给分母
|
||||
5. 派单前写一份 spec 文件
|
||||
6. 逐处替换断言命中数
|
||||
7. 落地位置写死（这一族只有这几条兜）
|
||||
8. 替换后三道二次清洗
|
||||
9. 收尾复跑 + 清中间产物
|
||||
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [steps-chinese-prefix-family.md](reference/steps-chinese-prefix-family.md)。动手前先读那篇。
|
||||
|
||||
## 不可判定引用绝对数涨点的净室归因
|
||||
|
||||
@@ -171,32 +73,33 @@ version: 1.1.0
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **拿门禁计数当中文字面量族的口径** → 得出「0 处待改」的假归零（实测该族真实站点 288 处 / 56 文件）；先跑自建扫描器报「站点 / 文件」，并在交付里写明该族不在语料内、门禁判不到。
|
||||
- **给无机器识别面的族登记 `id_aliases.json`** → 中文前缀不进语料，登记了机器也看不见，只制造「有门禁兜底」的错觉；执行面是 §4.1.1 停发行 + §9.3 换算表 + 评审。反过来，有识别面的族不登记别名 → 门禁把旧号引用判成悬空。
|
||||
- **拿 grep 计数跟人吵口径**：先拿实测三口径，再谈拆单；两套计数不一致不是有人算错（见上表）。**形似噪声号并进总数** → 把 132 处里程碑噪声算进 420 处待改，动手就改坏 `docs/芯片手册/` 原文。
|
||||
- **heredoc 里嵌 Python 正则 / 中文** → `invalid escape sequence` 与语法错；脚本落文件再跑。中文正则用 **raw 串 + `\uXXXX`**：非 raw 串的 `"\b"` 会被解成退格符，正则**静默失配不报错**。
|
||||
- **扫描没排除 `.git`** → `.git/COMMIT_MSG_*.txt` 的 GBK 乱码历史被当残留，越清越多；**靠控制台看中文** → 一律写 UTF-8 报告文件再解析，判乱码统计 `EF BF BD` 字节数。
|
||||
- **凭记忆敲 `old` 串** → 中文引号与 ASCII 双引号形态不同，命中 0；回读原文取真身，断言前先看 `git status` 自证文件未变。
|
||||
- **替换后不做同句重复检测** → 留下「运行参数段（「数据可信」运行参数段交付）」这类句子（实测 12 行）；**同一短语两种空格形态不归一** → 全仓口径漂移（归一前先 `git grep -c -F` 数各形态）。
|
||||
- **换算表里复述字面量** → 讲规则的文档变成自己的引用站点（规范本身在门禁语料里）。
|
||||
- **`| head` 之后读 `$?`** → 永远是 0，把「还有残留」当「已归零」。
|
||||
- **占位符泄漏**：为躲转义把反引号写成 `«` / `»` 再全文替换，落盘后**必须核占位符残留 = 0**（实测 22 行泄漏到本节之外，含不是自己写的行）。
|
||||
- **删行前不核证据属主、不查当初为什么保留** → 要么删掉唯一记录，要么把已撤销的「✅ 保留行」例外当常态。
|
||||
- **涨点归因拿 diff 新增行 grep 形态** → 把存量上下文当增量；**把上一轮现值当本回合实测**、未跑净室归因就报具体归因对象 = 猜测。
|
||||
- **全局查找替换**：跨族撞号（`S3` 三义）。必走 `rename_ids.py` 映射表 + 显式 scope + 干跑；无识别面族则逐处手写 + 断言命中数。
|
||||
- **未分类就动手**：把变压器位号、Mermaid 节点名、数学记号、gitlint 规则名当编号改坏硬件资料；位号目录进 `excluded_paths`，记号进噪声表。
|
||||
- **按简称匹配文件清单** → 误报 8 个文件丢失；比对前展开真实路径。
|
||||
- **复现不了队友的合并指纹就怀疑丢文件**：先问口径（自定义顺序不可复现），改落自有逐文件 16 位基线并把跨道文件单列。
|
||||
- **替换 token 含 `**` 加粗标记** → 命中数断言 0；取反引号最小形态。
|
||||
- **只改生成器文案不重跑产物** → `generated-fresh` 必红（实证 `0f7b5a87` 同类）；「反正就是注释，不影响图」是错的，该文本进产物。
|
||||
- **`grep 'A\|B'` 空返回当文件干净**：交替竖线在多层 bash 引号里被吃掉，是探针坏不是文件干净 → 反证为空的搜索必须换 `grep -F` 复测。
|
||||
- **一次 run_code 串 `5 × wait_agent(118000)` ≈ 590s 整段 abort、进度全丢**；且一次串多条长中文 `send_message` 也撑爆 120s（发出 1 条后 abort，剩余未发）。轮询上限 4×118s，长消息拆开发。
|
||||
- **游标整型比较静默不生效**（字符串形态）；抬完用 `--strict` 与 plain 双验。
|
||||
- **`git add` 目录路径带进别道文件**、`git add -A` 卷进在飞改动；撤销自己的改动只按文件点名 `git restore scripts/archive/id_gate/id_registry.json`，不碰同树其它道文件。
|
||||
- **amend 被 gitlint B1 拦**：正文行 >80，别把 ASCII 双引号写成正文首字符。
|
||||
- **改「只动注释」要拿机器证据**：`@build` 0 错 0 警且 `Program Size` 与改前**逐字节同数**（本回合真跑，引用历史提交正文自报的数字不算证据），别口头承诺。
|
||||
- **冻结历史与原始证据不改**：boot 串口日志等采集现场是冻结证据，改了就是篡改；历史「修改记录」行按裁定保持改名后形态（号已全仓退役，留一个查无此号的引用比留改过名的条目更坏）。
|
||||
- **`*.uvprojx` 抖动不入库**；`ci-artifacts/` 里的 spec 与扫描中间产物收尾删掉，别当交付物留下。
|
||||
- 拿门禁计数当中文字面量族的口径
|
||||
- 给无机器识别面的族登记 id_aliases.json
|
||||
- 拿 grep 计数跟人吵口径
|
||||
- heredoc 里嵌 Python 正则 / 中文
|
||||
- 扫描没排除 .git
|
||||
- 凭记忆敲 old 串
|
||||
- 替换后不做同句重复检测
|
||||
- 换算表里复述字面量
|
||||
- | head 之后读 $?
|
||||
- 占位符泄漏
|
||||
- 删行前不核证据属主、不查当初为什么保留
|
||||
- 涨点归因拿 diff 新增行 grep 形态
|
||||
- 全局查找替换
|
||||
- 未分类就动手
|
||||
- 按简称匹配文件清单
|
||||
- 复现不了队友的合并指纹就怀疑丢文件
|
||||
- 替换 token 含
|
||||
- 只改生成器文案不重跑产物
|
||||
- grep 'A\|B' 空返回当文件干净
|
||||
- 一次 run_code 串 5 × wait_agent(118000) ≈ 590s 整段 abort、进度全丢
|
||||
- 游标整型比较静默不生效
|
||||
- git add 目录路径带进别道文件
|
||||
- amend 被 gitlint B1 拦
|
||||
- 改「只动注释」要拿机器证据
|
||||
- 冻结历史与原始证据不改
|
||||
- *.uvprojx 抖动不入库
|
||||
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [pitfalls.md](reference/pitfalls.md)。动手前先读那篇。
|
||||
|
||||
## Verification
|
||||
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
# Pitfalls（自 SKILL.md 外置）
|
||||
|
||||
> 本文由 id-family-semantic-migration 的 SKILL.md「Pitfalls」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
|
||||
|
||||
- **拿门禁计数当中文字面量族的口径** → 得出「0 处待改」的假归零（实测该族真实站点 288 处 / 56 文件）；先跑自建扫描器报「站点 / 文件」，并在交付里写明该族不在语料内、门禁判不到。
|
||||
- **给无机器识别面的族登记 `id_aliases.json`** → 中文前缀不进语料，登记了机器也看不见，只制造「有门禁兜底」的错觉；执行面是 §4.1.1 停发行 + §9.3 换算表 + 评审。反过来，有识别面的族不登记别名 → 门禁把旧号引用判成悬空。
|
||||
- **拿 grep 计数跟人吵口径**：先拿实测三口径，再谈拆单；两套计数不一致不是有人算错（见上表）。**形似噪声号并进总数** → 把 132 处里程碑噪声算进 420 处待改，动手就改坏 `docs/芯片手册/` 原文。
|
||||
- **heredoc 里嵌 Python 正则 / 中文** → `invalid escape sequence` 与语法错；脚本落文件再跑。中文正则用 **raw 串 + `\uXXXX`**：非 raw 串的 `"\b"` 会被解成退格符，正则**静默失配不报错**。
|
||||
- **扫描没排除 `.git`** → `.git/COMMIT_MSG_*.txt` 的 GBK 乱码历史被当残留，越清越多；**靠控制台看中文** → 一律写 UTF-8 报告文件再解析，判乱码统计 `EF BF BD` 字节数。
|
||||
- **凭记忆敲 `old` 串** → 中文引号与 ASCII 双引号形态不同，命中 0；回读原文取真身，断言前先看 `git status` 自证文件未变。
|
||||
- **替换后不做同句重复检测** → 留下「运行参数段（「数据可信」运行参数段交付）」这类句子（实测 12 行）；**同一短语两种空格形态不归一** → 全仓口径漂移（归一前先 `git grep -c -F` 数各形态）。
|
||||
- **换算表里复述字面量** → 讲规则的文档变成自己的引用站点（规范本身在门禁语料里）。
|
||||
- **`| head` 之后读 `$?`** → 永远是 0，把「还有残留」当「已归零」。
|
||||
- **占位符泄漏**：为躲转义把反引号写成 `«` / `»` 再全文替换，落盘后**必须核占位符残留 = 0**（实测 22 行泄漏到本节之外，含不是自己写的行）。
|
||||
- **删行前不核证据属主、不查当初为什么保留** → 要么删掉唯一记录，要么把已撤销的「✅ 保留行」例外当常态。
|
||||
- **涨点归因拿 diff 新增行 grep 形态** → 把存量上下文当增量；**把上一轮现值当本回合实测**、未跑净室归因就报具体归因对象 = 猜测。
|
||||
- **全局查找替换**：跨族撞号（`S3` 三义）。必走 `rename_ids.py` 映射表 + 显式 scope + 干跑；无识别面族则逐处手写 + 断言命中数。
|
||||
- **未分类就动手**：把变压器位号、Mermaid 节点名、数学记号、gitlint 规则名当编号改坏硬件资料；位号目录进 `excluded_paths`，记号进噪声表。
|
||||
- **按简称匹配文件清单** → 误报 8 个文件丢失；比对前展开真实路径。
|
||||
- **复现不了队友的合并指纹就怀疑丢文件**：先问口径（自定义顺序不可复现），改落自有逐文件 16 位基线并把跨道文件单列。
|
||||
- **替换 token 含 `**` 加粗标记** → 命中数断言 0；取反引号最小形态。
|
||||
- **只改生成器文案不重跑产物** → `generated-fresh` 必红（实证 `0f7b5a87` 同类）；「反正就是注释，不影响图」是错的，该文本进产物。
|
||||
- **`grep 'A\|B'` 空返回当文件干净**：交替竖线在多层 bash 引号里被吃掉，是探针坏不是文件干净 → 反证为空的搜索必须换 `grep -F` 复测。
|
||||
- **一次 run_code 串 `5 × wait_agent(118000)` ≈ 590s 整段 abort、进度全丢**；且一次串多条长中文 `send_message` 也撑爆 120s（发出 1 条后 abort，剩余未发）。轮询上限 4×118s，长消息拆开发。
|
||||
- **游标整型比较静默不生效**（字符串形态）；抬完用 `--strict` 与 plain 双验。
|
||||
- **`git add` 目录路径带进别道文件**、`git add -A` 卷进在飞改动；撤销自己的改动只按文件点名 `git restore scripts/archive/id_gate/id_registry.json`，不碰同树其它道文件。
|
||||
- **amend 被 gitlint B1 拦**：正文行 >80，别把 ASCII 双引号写成正文首字符。
|
||||
- **改「只动注释」要拿机器证据**：`@build` 0 错 0 警且 `Program Size` 与改前**逐字节同数**（本回合真跑，引用历史提交正文自报的数字不算证据），别口头承诺。
|
||||
- **冻结历史与原始证据不改**：boot 串口日志等采集现场是冻结证据，改了就是篡改；历史「修改记录」行按裁定保持改名后形态（号已全仓退役，留一个查无此号的引用比留改过名的条目更坏）。
|
||||
- **`*.uvprojx` 抖动不入库**；`ci-artifacts/` 里的 spec 与扫描中间产物收尾删掉，别当交付物留下。
|
||||
@@ -0,0 +1,66 @@
|
||||
# Steps（字母+数字族：门禁看得见的那一路）（自 SKILL.md 外置）
|
||||
|
||||
> 本文由 id-family-semantic-migration 的 SKILL.md「Steps（字母+数字族：门禁看得见的那一路）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
|
||||
|
||||
1. **确认范围与定调**：先按开头的表判识别面（无识别面 → 走下一节）；再读 `docs/编号规范.md` §4.1（族总表，穷举）、§4.1.1（已停发栏），存量与批次见 `scripts/archive/id_gate/编号治理历史.md` §9，明确本族属主登记处（`owner_docs_glob`）与判据「有脚本按字面量匹配它」。清退 = 全仓改语义；停发 = 游标冻结、只减不增。
|
||||
2. **按族实测三口径（字面量 / 站点 / 文件），不用 grep 估数**。`Checker.refs` 是 **dict（字面量 → 文件集合）不是方法**，`ck.refs(fam)` 这种写法会 `TypeError`；站点数门禁不直接给，用族正则重扫它自己的语料：
|
||||
```python
|
||||
import sys; sys.path.insert(0, "scripts")
|
||||
import check_ids as ci
|
||||
reg = ci.load_json(ci.REGISTRY_FILE, "r"); al = ci.load_json(ci.ALIASES_FILE, "a")
|
||||
ck = ci.Checker(reg, al); ck.run() # run() 填充 refs / stats / findings
|
||||
for name in ("N", "S-LDG", "TC", "FEAT"): # 族名以 id_registry.json 的 "name" 为准
|
||||
rx = next(f for f in ck.families if f["name"] == name)["_re"]
|
||||
lits = {l for l in ck.refs if rx.fullmatch(l)} # 字面量（属主文档之外）
|
||||
files = {r for l in lits for r in ck.refs[l]} # 文件
|
||||
sites = sum(len(rx.findall(line))
|
||||
for rel in ck.iter_files() # 与门禁同一语料
|
||||
for line in ck.read(rel).splitlines()) # 含属主文档定义行
|
||||
print(name, "literals", len(lits), "sites", sites, "files", len(files))
|
||||
```
|
||||
全库扫一遍不便宜（数十秒量级）：可丢后台 job，不要和别的长活串在同一个 120s 预算里。把活族清单与每族数字记下来作为**动手前基线**（拆批次与派单依据）。新测试套件发号导致 `id-check` 校验 3 报悬空引用时，**先按号前缀聚合**定位是哪个套件/哪个族（`check_ids.py 2>&1 | grep -a '悬空引用' | ...` 前缀计数），别逐条读。
|
||||
3. **逐族先分类再动手**——不是每个命中的裸形都是编号，四类分治（实测 T1/T2/T3 的 41 处里只有部分是编号）：
|
||||
- 真编号 → 语义短语 / 功能名；
|
||||
- 硬件位号（变压器 T1~T3 等）→ 把目录整目录登记进 `check_ids` 的 `excluded_paths`（如 `excluded_paths += tools/netlist_semantics/`），**不逐处改位号名**；
|
||||
- Mermaid 流程图节点名 → 改语义名但**节点数与连线关系不变**，图结构不动；
|
||||
- 数学记号 → 进噪声表；门禁自身的规则名（gitlint `T2 Title has trailing whitespace`）→ 不改。
|
||||
分类前先把剩余每处原文打出来看（`grep -F` 逐文件），否则会把硬件资料改坏。
|
||||
4. **映射表由属主文档生成**：从属主文档取「编号 → 功能名/语义短语」全表（实测 42 个定义 / 28 个在用），改名走 `scripts/rename_ids.py`（映射表驱动 + **显式 scope** + **默认干跑** + 自动往 `scripts/archive/id_gate/id_aliases.json` 写 scoped 旧号→新号条目，状态 `renamed` / `retired-to-phrase` / `void`）。**绝不全局查找替换**：同一裸形字面量可能同时属多个族（实测 `S3` 三义），全局替换等于造新撞号。
|
||||
5. **按写域拆道并行派单**（代码与测试半 / 文档半 / 某功能面各一条道），同笔用 `send_message` 下发**统一改写口径**（措辞、是否动字符串字面量、生成器归属、冻结历史行怎么处理），避免各道自定措辞；口径长就先落成 spec 文件（中文族一节第 5 步的做法同样适用）。看板任务只认 `team_task_update` 的 `task_id` / `expected_revision` / `action=reassign` / `owner` 四个字段。
|
||||
6. **门禁配置注释也是本族写入面**：`.pre-commit-config.yaml` 的注释里会挂着功能号（实测 `7h) ADC 采样有效性校验（语义取数与有效性层）`、`7i) 保护定值模型（P1 / 动作留痕层载体）`、`规划 §3.3 保护判据层`）。配置属 Lead 写域，Lead 自己改（注释不占钩子行为、不影响 51 条钩子口径），但**必须计入批次范围并在提交正文写清是 Lead 改的 config**。
|
||||
7. **每处替换断言命中数**，不做整文件正则批量改写（批量改写会静默漏改）：
|
||||
```python
|
||||
def sub(path, pairs):
|
||||
p = pathlib.Path(path); t = p.read_text(encoding='utf-8')
|
||||
for old, new, want in pairs:
|
||||
got = t.count(old); assert got == want, (path, old, got, want)
|
||||
t = t.replace(old, new)
|
||||
p.write_text(t, encoding='utf-8')
|
||||
```
|
||||
**token 取最小形态**：文档里被反引号/加粗包住的号，替换单位取反引号形（```T4```）而**不含 `**` 标记**（第 225 行是 `**裸形 `T4`**`，按「裸形 `T4`」替就命中 0）。讲编号的文档改成**形态描述**（如「字母 T 紧跟数字 4」）能把不可判定绝对数还回余量：实测 4 处 → 982 降到 978，且 lesson 不丢。
|
||||
8. **同步更新门禁侧配置**：`check_ids` 的 `excluded_paths` 与噪声表按第 3 步的分类结果改，使剩余命中不再是「假编号」；新测试套件发号的悬空引用要先定**定义位**：
|
||||
- 定义位**只能落一处**——注册表族（`scripts/archive/id_gate/id_registry.json`）或该套件说明文档，**两处并存比没有定义位更坏**；文档真写出来了（含判据与上板清单）就以文档为准、**撤族**；
|
||||
- 要建族就照现有同类族克隆（`pattern` / `digit_width` / `owner_docs_glob` / `scope` / `cursor`），别自造字段；
|
||||
- **抬游标前先确认游标是字符串形态**（`'cursor': 'TC-UIDATA-026'`）——整型比较会静默不生效（实测踩坑），用字符串解析或正则取序号再比。
|
||||
9. **生成器文本改动必须同笔重跑产物**：`tools/arch_diagram/gen_*.py` 里的 docstring/文案会进产物，`generated-fresh` 把生成器拷到临时目录重跑逐字节比对，**只改源不改产物必红**。这类站点整包转给生成器属主，「谁改谁跑生成器」，脚本 + 全部 svg 产物同一笔：
|
||||
```bash
|
||||
./.venv/Scripts/python.exe tools/arch_diagram/gen_net_instability_svg.py 2>&1 | tail -3
|
||||
pre-commit run generated-fresh --all-files # 单钩子复跑必须带 --all-files 或 --files
|
||||
```
|
||||
⚠ **不带这两个参数的裸 `pre-commit run` 会进 staged_files_only 上下文并 stash 别道在飞的改动**（`docs/门禁说明/generated-fresh.md` §2）；`pre-commit` 不在 PATH 时改用 `& '.venv\Scripts\python.exe' -m pre_commit run generated-fresh --all-files`。PASS 后再目检 diff：只应文字变长、框宽自适应（526→551、右缘未越界、画布不变）。不把该站点从批次里悄悄丢掉：登记为「待未完成半批」，收口时核对。
|
||||
10. **核队友交付**（按写域并行后必做）：
|
||||
- 文件清单**先展开真实路径再比**：按简称匹配会误报丢失（作者列 `phasor.py`/`adc_health.py` 等 8 个，实为 `test/host/<模块>/run_unit_test.py`）；用 `git -c core.quotepath=false diff --name-only` 取全路径做集合差。
|
||||
- 合并指纹对不上先问口径：作者按**自定义顺序**算的数 Lead 侧复现不了（`d0a289b7` vs 报的 `a45e7e2b`）。改建 **Lead 自有逐文件 16 位基线**存 `ci-artifacts/lead_lane_b_files.json`，并把**跨道文件单列**（实测 `App/algo/README.md`）——autostash 后按逐文件比对，不假称对上别人的合并数。
|
||||
11. **分笔提交走真实 pre-commit 钩子**：`git add` 用显式清单。坑：`git add -- App/algo` 把文档道的 `App/algo/README.md`（26 处）带上车，正文按 48 只文件写就不准了 → 该笔未 push 时 `--amend` 挪到文档笔并补一句归属说明；`git add -A` 会把别道在飞文件卷进来（覆盖率钩子在他编译不过的半成品上报红）→ 撤出他人域后重跑。提交正文每行 ≤80（gitlint B1），别把 ASCII 双引号写成正文首字符。
|
||||
12. **收口只认门禁自身计数**（**仅限语料内的族**；无识别面族见下一节第 8~9 步），并核**只减不增**：
|
||||
```bash
|
||||
./.venv/Scripts/python.exe scripts/archive/id_gate/check_ids.py 2>&1 | grep -aE '扫描|可判定 |不可判定引用' | head -4
|
||||
./.venv/Scripts/python.exe scripts/archive/id_gate/check_ids.py --strict 2>&1 | tail -1 # [OK] 校验 1~6 无错误
|
||||
```
|
||||
报告「字面量 8787→8299→7828」「不可判定绝对数 1161→984→982→978（上限 1166）」「可判定比例 88.14%（基线 86.0%，容差 0.1pp）」。**绝对数与比例两根线都要报**：把可判定引用改成散文会稀释比值，所以另有不可判定绝对数上限。涨点归因见「净室归因」一节。
|
||||
13. **回写 `docs/编号规范.md`**：§4.1 族表（停发/待清栏）、§4.1.1 已停发栏、§9 存量表与批次结果表（只减不增）、§9 清点数字按最终实测同步；表格若保留动手前的清点数，**明确标注「不是当前存量，是动手前基线」**，否则就是拿旧数当现状。**用户裁定原文与理由直接写进对应节**（§4.1.1 停发行 + 该族的批次结论段落）——2026-10-28 起不再往变更记录写流水（`docs/文档规范.md` §5.1）。
|
||||
14. **裁定「不做」也要写成可执行硬口径入档**（不是只划掉一行——「不做」最容易被读成「那还可以继续发号」）：
|
||||
- §4.1.1「已停发」栏新增该族一行：**游标冻结、现存号只减不增、新用例改用语义化测试函数名 + 文档表格行名**，并写清与「允许继续发号」栏为何不打脸；
|
||||
- §9.1 批次段落写明裁定原文与理由（该族是唯一真被脚本按字面量匹配的族：C 断言标签 + 测试函数名 + 文档用例表三处同一号），并给出**将来真要清退的前置条件**：追溯器（`check_test_traceability.py`）先同时认新旧两种形态、并行核对通过，**不许先改文档再改代码**；
|
||||
- 全文核「等你裁定 / 需你裁定」悬空表述残留数归 0；
|
||||
- 无机器识别面的族落地面不同（§4.1.1 一行 + §9.3 换算表 + 叙述同步三处），见下一节第 7 步。
|
||||
@@ -0,0 +1,65 @@
|
||||
# Steps（中文前缀族：门禁咬不到的那一路）（自 SKILL.md 外置）
|
||||
|
||||
> 本文由 id-family-semantic-migration 的 SKILL.md「Steps（中文前缀族：门禁咬不到的那一路）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
|
||||
|
||||
1. **先确认门禁咬不到，并把这句话写进交付**：`scripts/archive/id_gate/check_ids.py` 的族 pattern 是拉丁形态、中文前缀不进语料 → **id-check 的 refs / 可判定比例 / 悬空引用与本族无关**；报告开头写「本族不在 check_ids 语料内，口径 = 自建扫描器」。
|
||||
2. **销项删行前先核证据属主**（这是删行的唯一许可证）：
|
||||
- 先取历史口径：`git log --oneline -20 -- <文档>`、`git show <rev>:<文档> | sed -n '/^## 5/,/^## 6/p'` 找回被删的卡表与当初「完成即销项删行 / 标 ✅ 保留行」的理由；
|
||||
- 核对判据与实测记录**已完整沉淀进属主章节**（实测：「已知电压注入验证」六项判据全 PASS、斜率 6544.2 码/V、偏差 −0.14 % 全在 `docs/硬件平台/ADC通道映射说明.md` §8.1，执行侧在 `docs/测试说明/ADC前端注入验证流程.md`）；
|
||||
- **删的是任务规划侧的行与结论块，不是证据本体**；被代码头注释指称的设计约束章节（§2~§4 那类）**原样保留**，只删已完成记录；
|
||||
- 该行若当初是被「代码头注释按号引用」当例外保住的（实测 `App/task/adc_task.c` 的 v3.3 修订行按卡号当口径出处），必须**先把引用侧改成语义短语**，例外才成立撤销，并在规范里写明撤销理由（上一笔「完成即保留行」的例外就是这么随引用侧改动被撤掉的）；
|
||||
- 删完逐行通读被改小节，报**行数变化**，不留孤立残句（实测 J7 dropped line 234 len=639、J13 闭环结论块 6 行删除并注明证据属主）。
|
||||
3. **自建带标签正则扫描脚本**——四条硬规矩，全是实测返工换来的：
|
||||
- 脚本**落文件**（`ci-artifacts/scan_ka_refs.py`）再跑，**不用 bash heredoc**（heredoc 里的 `\s` 被多层引号咬坏：`SyntaxWarning: invalid escape sequence` + 语法错）；
|
||||
- 正则**一律 raw 字符串**、汉字写 `\uXXXX`：`KA = r"\u5361"`。非 raw 串里 `"\b"` 会先被 Python 解成退格符（0x08）→ 正则**静默失配且不报错**；`"\s"` 只是警告还能跑，`"\b"` 是真错；
|
||||
- **排除 `.git`**（连同 `.venv`、`ci-artifacts`、`__pycache__`、`node_modules`）——实测扫进 `.git/COMMIT_MSG_*.txt`，一堆 GBK 乱码历史被当成残留，越清越多；
|
||||
- 报告**写 UTF-8 文件**（`ci-artifacts/ka_refs.txt`）再本地解析，别靠控制台输出（Windows 控制台按 GBK 渲染中文 = 乱码）；判乱码统计 `EF BF BD` 字节数，别信终端渲染。
|
||||
|
||||
```python
|
||||
# -*- coding: utf-8 -*-
|
||||
"""扫描中文前缀任务卡号与同期形似噪声号；报告写 UTF-8 文件。"""
|
||||
import io, os, re
|
||||
KA = r"\u5361" # 卡
|
||||
PATS = [("CARD_ANY", re.compile(KA + r"\s*[0-9]")),
|
||||
("KA0B", re.compile(KA + r"\s*0b")),
|
||||
("KA12", re.compile(KA + r"\s*12")),
|
||||
("M4", re.compile(r"\bM4\b")),
|
||||
("M5", re.compile(r"\bM5\b")),
|
||||
("M6", re.compile(r"\bM6\b"))]
|
||||
SKIP = {".git", ".venv", "ci-artifacts", "__pycache__", "node_modules"}
|
||||
out = io.open("ci-artifacts/ka_refs.txt", "w", encoding="utf-8")
|
||||
for root, dirs, names in os.walk("."):
|
||||
dirs[:] = [d for d in dirs if d not in SKIP]
|
||||
for n in names:
|
||||
p = os.path.join(root, n)
|
||||
try:
|
||||
txt = io.open(p, encoding="utf-8", errors="ignore").read()
|
||||
except OSError:
|
||||
continue
|
||||
for i, line in enumerate(txt.splitlines(), 1):
|
||||
for tag, rx in PATS:
|
||||
if rx.search(line):
|
||||
out.write("===== %s\n" % p) # 同一行可命中多标签 → 按标签分别计数
|
||||
out.write("%d [%s] %s\n" % (i, tag, line.strip()[:200]))
|
||||
out.close()
|
||||
```
|
||||
末尾打 `TOTAL_SITES / FILES / SCANNED / 各标签计数`；**带标签**才拆得开噪声（同一行可同时命中 `CARD_ANY` 与 `KA12`）。
|
||||
4. **该族与形似噪声号分开计数，各自给分母**：一遍扫描出 `TOTAL_SITES 420 FILES 85 SCANNED 1025`，必须再拆成**卡族 288 处 / 56 文件** 与 **里程碑噪声 132 处 / 44 文件**（`M4/M5/M6` 大片落在 `docs/芯片手册/` 参考手册与料号上下文里）。两套数字各自给分母——**「420 处待改」是错的**：把 132 处噪声算进清退范围就会去改芯片手册原文。噪声侧一律保持原样，是否清退等用户单独裁定，**不要顺手做**。
|
||||
5. **派单前写一份 spec 文件**（`ci-artifacts/card_retire_spec.md`），作为各道唯一口径来源，含五块：① 背景与**用户裁定原文**；② 逐号映射表（旧号形态 → 语义短语 → 属主出处）；③ 措辞规则（补短语时括号怎么降级、动不动字符串字面量、生成器归属、悬空引用怎么判）；④ 硬约束（BOM 原样补回、行尾由 `.gitattributes` 写死、冻结历史行与原始证据不回改、代码头注释引用的设计约束章节保留、带 BOM 文件名单）；⑤ 自检与交付格式（逐文件命中数、删了哪几行、残留数、门禁复跑结果）。`send_message` 只发路径 + 关键裁定，长中文正文不要整段塞进消息（一次串多条长消息会撑爆 120s，发出 1 条后 abort，剩余未发）。
|
||||
6. **逐处替换断言命中数**（同第 7 步的 `rep(tag, old, new, want)`），且 `old` 串**从原文取、不凭记忆敲**：本仓中文引号与 ASCII 双引号混用（实测某文档里的「中文引号」其实是 ASCII `"`），凭印象写 `old` 必 `got=0`；断言抛错后先 `git status --porcelain=v1 -- <文件>` 自证文件未被别道改动，再回读该行真身重跑。删行类改动单独记 tag 并打印删了几行、行号与原行长度。多道并行时同一文件常被别道改过：`edit` 报 `file changed since it was read` → 重新 `read` 再改；报 `ReplaceFileW EIO (Win32 1175)` → 先自证文件字节完好（BOM / CRLF / `EF BF BD` 三项）再重试同一笔，不要顺手改内容。
|
||||
7. **落地位置写死（这一族只有这几条兜）**：
|
||||
- `docs/编号规范.md` **§4.1.1「已停发的族」表加一行**，三列齐全，第三列直写「⚠ **机器面空白**：中文前缀不进 `scripts/archive/id_gate/check_ids.py` 语料 → 门禁咬不到，只有本表 + §9.3 + 评审三条兜；`id_aliases.json` 刻意不登记（登记了机器也看不见，只多一张没人核的表）」；
|
||||
- `docs/编号规范.md` **§9.3 逐号换算表**（旧号形态 → 语义短语 → 现行口径出处；本族实测 14 行 = 0、0b、1~12）+ §9 批次段落（裁定原文与逐号结论都落在正文），**写明旧号永久作废、不得重新取走**；
|
||||
- 表内**把形态写成「卡」+ 数字而不复述字面量**：规范本身是门禁语料，复述字面量会把「讲规则的文档」变成自己的引用站点；
|
||||
- **同步叙述**：`AGENTS.md`「文档与图形」的销项条目、`docs/README.md`（例：`数据可信.md = 三项阻塞任务` → 两项）、`docs/任务规划/README.md`、`docs/任务规划/登记簿.md`——「剩余三项」这类旧口径实测归零；
|
||||
- **与有识别面族的判别写进同一张表**：能被脚本按字面量匹配 → 走 `rename_ids.py` + 别名登记；匹配不到（中文前缀、纯散文号、圈号）→ 走规范换算表，**不登记别名**；
|
||||
- 要机械化怎么办：得先给「中文前缀 + 数字」设计候选形态，属追溯机制改造，按 §7.3 单独开卡，**别夹在清退批里顺手做**。
|
||||
8. **替换后三道二次清洗**（缺一必留疤，全部实测过）：
|
||||
```bash
|
||||
git grep -c -F '端子 / 子板变比确认' -- . ; git grep -c -F '端子/子板变比确认' -- . # 先数各形态再归一
|
||||
git grep -nE '卡[ ]*[0-9]' -- . ; echo "rc=$?" # 裸跑读 rc；1 = 归零
|
||||
```
|
||||
- **同句重复短语**：编号位置补上的语义短语与原句已有短语撞车 → 扫「同一行里同一短语出现 ≥2 次」（实测 12 行，如 `.pre-commit-config.yaml:401`「运行参数段（「数据可信」运行参数段交付）」、`App/algo/README.md:110`「遥测快照发布（L2 发布侧，「数据可信」遥测快照发布）」）→ 改法是**把括号里的引用降级**成不含该短语的写法（「道D 交付项」「波次」「该点 DoD 原句」），逐处断言命中 = 1，别删信息；
|
||||
- **空格与引号形态归一**：同一语义短语可能有 `端子 / 子板变比确认` 与 `端子/子板变比确认` 两种形态 → **先 `git grep -c -F` 分别数**（实测带空格 8 处），再整文件归一，归一后复扫到 0（残留常藏在表格单元格里，逐行打印定位）；引号形态同理；
|
||||
- **固定正则复扫**：`卡[ ]*[0-9]` 全仓无输出。⚠ 判 rc 时**不要把命令接在 `| head` 之后再读 `$?`**（那拿到的是 `head` 的 0，会把「还有残留」读成「已归零」）。
|
||||
9. **收尾复跑 + 清中间产物**：`check_ids.py`（plain 与 `--strict`）、`check_doc_links.py --all`、bom 与乱码两道（`pre-commit run bom-guard --files <改过的文件>`、`pre-commit run no-mojibake --files <改过的文件>`）、`git diff --check`；**纯注释/纯文档改动不算免编译**——仍跑一次 `@build` 取「0 错误 0 警告」且 `Program Size` 与改前同数（**本回合真跑**，引用历史提交正文自报的四个数不算），受影响的主机组单测照跑。最后**删掉 spec 与全部扫描中间产物**，别往 `ci-artifacts/` 再堆 log/txt。
|
||||
@@ -17,45 +17,12 @@ whenToUse: 需要编译 Keil MDK 工程、跑 `@build` 验证代码改动是否
|
||||
|
||||
## 调用形态：先认执行器是哪个 shell（2026-10-26 实测）
|
||||
|
||||
同一个 `@build`，**PowerShell 与 bash 是两种写法**；`ops_bash` / `run_code` 起的是
|
||||
`/usr/bin/bash -c`，**不认 PowerShell 形态**，照抄仓库 `AGENTS.md` 会直接语法错退出。
|
||||
|
||||
| 执行器 | 正确写法（cwd = 仓库根） |
|
||||
|---|---|
|
||||
| PowerShell | `& '.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` |
|
||||
|
||||
- bash 侧**去掉前导 `&`**（bash 里 `&` 是"丢后台"，不是调用操作符）、**路径改正斜杠**
|
||||
（`\Scripts\python.exe` 的反斜杠在 bash 是转义，路径根本解析不出来）。
|
||||
- 实测（step 41→42）：把 PowerShell 形态丢进 `ops_bash` 后台任务 → 任务**秒退**、
|
||||
`exit 2`，stderr 只有这一行：
|
||||
|
||||
```text
|
||||
/usr/bin/bash: -c: line 1: syntax error near unexpected token `&'
|
||||
```
|
||||
|
||||
- ⚠ **这个 2 不是脚本的环境错误 2**：脚本自己报环境错误会打出 `BuildEnvError` /
|
||||
中文诊断（UV4 找不到、工程找不到、档案解析失败），而语法错**连解释器都没启动**，
|
||||
`MDK-ARM/build_log.txt` 不会被改写。判据：stderr 含 `syntax error near unexpected token`
|
||||
= 写法问题 → 换 bash 形态重跑，**别去查 `DTU_KEIL_UV4`、别当环境错误排障**。
|
||||
- 后台跑（`run_in_background: true`）时要自己收码，且**别把脚本接进管道**：
|
||||
`'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py; rc=$?; echo RC=$rc`。
|
||||
实测 `脚本 | tail -6; echo RC=$?` 里的 `$?` 是 `tail` 的退出码（恒 0），
|
||||
拿它当 PASS/FAIL 会永远"绿"；`set -o pipefail` 能透出非零码，但尾巴上挂的 `grep`
|
||||
无匹配时同样报 1，也不可信。要看报错行就单独 grep 日志：
|
||||
`grep -a -E 'Error|error:|Warning' MDK-ARM/build_log.txt`。
|
||||
|
||||
解析顺序（命令行 > 项目档案 `.serialtest/config.json` > 环境 > 探测）：
|
||||
工程 `uvprojx`（档案缺省时自动搜 cwd 下唯一 `*.uvprojx`）；UV4 `uv4` >
|
||||
`$DSH_KEIL_UV4` > `$DTU_KEIL_UV4` > PATH（**显式设了但路径无效 = 立即报错，不静默回退**）。
|
||||
退出码：`0`=PASS(0错0警) / `1`=构建失败（打印报错行）/ **`2`=环境错误**（UV4 找不到或
|
||||
路径无效、工程找不到、档案解析失败）/ `3`=用法错误 / `4`=build 锁被占用（并发 `-b` 不可行）。
|
||||
**收到 2 先确认它是脚本打的还是 shell 语法错打的**（见上节），再走"环境错误"排障。
|
||||
|
||||
> 2026-10-12 修正：旧实现把环境错误写成 `raise SystemExit("...")` → 实际退出码是 **1**，
|
||||
> 而用法错误由 argparse 抛 `SystemExit(2)` → 恰好占了"环境错误"的位置。故 `AGENTS.md` /
|
||||
> `new-machine-setup` 里写的"报 exit 2 = 环境问题"当时**不成立**。现按文档口径改正：
|
||||
> 环境错误 → 2（`BuildEnvError`），用法错误 → 3（覆盖 argparse 的 `error()`）。
|
||||
- 同一个 @build，PowerShell 与 bash 是两种写法：bash 侧要去掉前导 & 并把路径改正斜杠（照抄 AGENTS 的 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 的归属，该篇末尾记了前后口径
|
||||
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [executor-shell-forms.md](reference/executor-shell-forms.md)。动手前先读那篇。
|
||||
|
||||
## build 锁：脚本自持自释（2026-10-12）
|
||||
|
||||
@@ -83,46 +50,11 @@ Agent 手工 `lock acquire build` 后忘了 `release`，锁要挂到 TTL 才被
|
||||
|
||||
## 构建副产物：`%SystemDrive%` 字面量垃圾目录（2026-10-26 两次复发 → 2026-10-28 定性并加守卫）
|
||||
|
||||
**症状**：`@build`（或 `scripts/check_font_charset.py` 这类 fontTools 字体工具）跑完，仓库根
|
||||
冒出未跟踪目录 `%SystemDrive%/ProgramData/Microsoft/Windows/Caches/`，里面是几个 `.db`
|
||||
（`cversions.2.db` + `{6AF0698E-…}` 图标缓存 + `{DDF571F2-…}` 字体缓存，合计约 1 MB）——
|
||||
就是本机 `C:\ProgramData\Microsoft\Windows\Caches` 那份缓存被**按字面量原地复刻**了一份。
|
||||
|
||||
**根因（2026-10-28 实测）**：Windows 的 known-folder 路径在注册表里是**可展开串**；展开不了，
|
||||
它就变成一个**相对路径**，于是按「当前目录」（= 仓库根）建出来。三条现场证据：
|
||||
|
||||
```bash
|
||||
reg.exe query HKCU\Environment # 本机 TMP/TEMP = REG_EXPAND_SZ %USERPROFILE%\AppData\Local\Temp
|
||||
env | wc -l # ops_bash 里 = 74（完整环境）
|
||||
node -e "console.log(Object.keys(process.env).length)" # run_code 里 = 0（空环境！）
|
||||
```
|
||||
|
||||
`run_code` 的 Node 进程 `process.env` 是**空的**，从它里面 `spawn` 出去的 UV4 / 字体脚本就拿不到
|
||||
`SystemDrive`/`ProgramData`/`ALLUSERSPROFILE`；实测 `os.path.expandvars("%SystemDrive%\ProgramData")`
|
||||
原样返回、且 `os.path.isabs()` = **False** → 目录就长在工作区里（同族还会冒出
|
||||
`%USERPROFILE%/AppData/Local/Temp`）。**正解不是「让用户去设环境变量」**，是别在残缺环境里跑构建（见第 2 条）。
|
||||
|
||||
**清理（有安全阀）**：
|
||||
|
||||
- ⚠ **绝不用 cmd / PowerShell 直接删**：`rd /s /q %SystemDrive%` 会被 cmd **展开成 `C:`**——
|
||||
等于对整块系统盘下令递归强删且不带确认。
|
||||
- ✅ 只用 bash 引号形态（`%` 在 bash 里没有特殊含义）：先 `find '%SystemDrive%' -type l` 确认不是
|
||||
reparse point / 符号链接，再 `rm -rf -- '%SystemDrive%'`；或 Node
|
||||
`fs.rmSync("%SystemDrive%", { recursive: true, force: true })`。
|
||||
- 它是**工具副产物**，不是谁在飞的改动——直接删，别 stash、更别提交（提交它 = 把本机缓存塞进历史）。
|
||||
|
||||
**让它不再污染工作区（两层，均已落地、可核验）**：
|
||||
|
||||
1. **进不了版本库**：`.gitignore:167` 的 `%SystemDrive%/`（2026-10-26 入库，注释里就写着复发证据）。
|
||||
核验三步（2026-10-28 复跑全绿）：造一份同名目录 + `.db` → `git status --porcelain` 零命中 →
|
||||
`git check-ignore -v <路径>` 落在 `.gitignore:167:%SystemDrive%/` → `git add -A --dry-run` 零暂存。
|
||||
2. **根本别再长出来**：本 skill 脚本 2026-10-28 起在拉起 UV4 前跑 `harden_windows_env()`——回填
|
||||
`SystemDrive`/`SystemRoot`/`windir`/`ComSpec`/`ProgramData`/`ALLUSERSPROFILE`/`ProgramFiles` 与
|
||||
`USERPROFILE`/`APPDATA`/`LOCALAPPDATA`/`TMP`/`TEMP`，就地展开环境里未展开的 `%VAR%` 字面量，
|
||||
并把 `TMP`/`TEMP` 指到真实目录；命中即打 `WARN: ENV_SPARSE:`。构建后再跑
|
||||
`check_percent_literal_junk()`，看到 `%SystemDrive%`/`%USERPROFILE%` 一类字面量目录就打
|
||||
`WARN: JUNK_DIR:`（**只告警不自动删**——删目录不该由构建脚本代劳）。守卫是兜底不是许可：
|
||||
**`@build` 仍要走 `ops_bash` / PowerShell（继承完整环境）**，非在 Node 里 spawn 就把 `env` 传全。
|
||||
- 症状：@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() 只告警不自动删；守卫是兜底不是许可，@build 仍要走 ops_bash / PowerShell
|
||||
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [systemdrive-junk-dir.md](reference/systemdrive-junk-dir.md)。动手前先读那篇。
|
||||
|
||||
## 本仓库
|
||||
|
||||
|
||||
@@ -0,0 +1,43 @@
|
||||
# 调用形态：先认执行器是哪个 shell（2026-10-26 实测）（自 SKILL.md 外置）
|
||||
|
||||
> 本文由 keil-build 的 SKILL.md「调用形态：先认执行器是哪个 shell（2026-10-26 实测）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
|
||||
|
||||
同一个 `@build`，**PowerShell 与 bash 是两种写法**；`ops_bash` / `run_code` 起的是
|
||||
`/usr/bin/bash -c`，**不认 PowerShell 形态**，照抄仓库 `AGENTS.md` 会直接语法错退出。
|
||||
|
||||
| 执行器 | 正确写法（cwd = 仓库根） |
|
||||
|---|---|
|
||||
| PowerShell | `& '.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` |
|
||||
|
||||
- bash 侧**去掉前导 `&`**（bash 里 `&` 是"丢后台"，不是调用操作符）、**路径改正斜杠**
|
||||
（`\Scripts\python.exe` 的反斜杠在 bash 是转义，路径根本解析不出来）。
|
||||
- 实测（step 41→42）：把 PowerShell 形态丢进 `ops_bash` 后台任务 → 任务**秒退**、
|
||||
`exit 2`，stderr 只有这一行：
|
||||
|
||||
```text
|
||||
/usr/bin/bash: -c: line 1: syntax error near unexpected token `&'
|
||||
```
|
||||
|
||||
- ⚠ **这个 2 不是脚本的环境错误 2**：脚本自己报环境错误会打出 `BuildEnvError` /
|
||||
中文诊断（UV4 找不到、工程找不到、档案解析失败），而语法错**连解释器都没启动**，
|
||||
`MDK-ARM/build_log.txt` 不会被改写。判据：stderr 含 `syntax error near unexpected token`
|
||||
= 写法问题 → 换 bash 形态重跑，**别去查 `DTU_KEIL_UV4`、别当环境错误排障**。
|
||||
- 后台跑（`run_in_background: true`）时要自己收码，且**别把脚本接进管道**：
|
||||
`'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py; rc=$?; echo RC=$rc`。
|
||||
实测 `脚本 | tail -6; echo RC=$?` 里的 `$?` 是 `tail` 的退出码（恒 0），
|
||||
拿它当 PASS/FAIL 会永远"绿"；`set -o pipefail` 能透出非零码，但尾巴上挂的 `grep`
|
||||
无匹配时同样报 1，也不可信。要看报错行就单独 grep 日志：
|
||||
`grep -a -E 'Error|error:|Warning' MDK-ARM/build_log.txt`。
|
||||
|
||||
解析顺序（命令行 > 项目档案 `.serialtest/config.json` > 环境 > 探测）：
|
||||
工程 `uvprojx`（档案缺省时自动搜 cwd 下唯一 `*.uvprojx`）；UV4 `uv4` >
|
||||
`$DSH_KEIL_UV4` > `$DTU_KEIL_UV4` > PATH（**显式设了但路径无效 = 立即报错，不静默回退**）。
|
||||
退出码：`0`=PASS(0错0警) / `1`=构建失败（打印报错行）/ **`2`=环境错误**（UV4 找不到或
|
||||
路径无效、工程找不到、档案解析失败）/ `3`=用法错误 / `4`=build 锁被占用（并发 `-b` 不可行）。
|
||||
**收到 2 先确认它是脚本打的还是 shell 语法错打的**（见上节），再走"环境错误"排障。
|
||||
|
||||
> 2026-10-12 修正：旧实现把环境错误写成 `raise SystemExit("...")` → 实际退出码是 **1**，
|
||||
> 而用法错误由 argparse 抛 `SystemExit(2)` → 恰好占了"环境错误"的位置。故 `AGENTS.md` /
|
||||
> `new-machine-setup` 里写的"报 exit 2 = 环境问题"当时**不成立**。现按文档口径改正：
|
||||
> 环境错误 → 2（`BuildEnvError`），用法错误 → 3（覆盖 argparse 的 `error()`）。
|
||||
@@ -0,0 +1,44 @@
|
||||
# 构建副产物：`%SystemDrive%` 字面量垃圾目录（2026-10-26 两次复发 → 2026-10-28 定性并加守卫）（自 SKILL.md 外置）
|
||||
|
||||
> 本文由 keil-build 的 SKILL.md「构建副产物：`%SystemDrive%` 字面量垃圾目录（2026-10-26 两次复发 → 2026-10-28 定性并加守卫）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
|
||||
|
||||
**症状**：`@build`（或 `scripts/check_font_charset.py` 这类 fontTools 字体工具）跑完，仓库根
|
||||
冒出未跟踪目录 `%SystemDrive%/ProgramData/Microsoft/Windows/Caches/`，里面是几个 `.db`
|
||||
（`cversions.2.db` + `{6AF0698E-…}` 图标缓存 + `{DDF571F2-…}` 字体缓存，合计约 1 MB）——
|
||||
就是本机 `C:\ProgramData\Microsoft\Windows\Caches` 那份缓存被**按字面量原地复刻**了一份。
|
||||
|
||||
**根因（2026-10-28 实测）**：Windows 的 known-folder 路径在注册表里是**可展开串**；展开不了，
|
||||
它就变成一个**相对路径**，于是按「当前目录」（= 仓库根）建出来。三条现场证据：
|
||||
|
||||
```bash
|
||||
reg.exe query HKCU\Environment # 本机 TMP/TEMP = REG_EXPAND_SZ %USERPROFILE%\AppData\Local\Temp
|
||||
env | wc -l # ops_bash 里 = 74（完整环境）
|
||||
node -e "console.log(Object.keys(process.env).length)" # run_code 里 = 0（空环境！）
|
||||
```
|
||||
|
||||
`run_code` 的 Node 进程 `process.env` 是**空的**，从它里面 `spawn` 出去的 UV4 / 字体脚本就拿不到
|
||||
`SystemDrive`/`ProgramData`/`ALLUSERSPROFILE`；实测 `os.path.expandvars("%SystemDrive%\ProgramData")`
|
||||
原样返回、且 `os.path.isabs()` = **False** → 目录就长在工作区里（同族还会冒出
|
||||
`%USERPROFILE%/AppData/Local/Temp`）。**正解不是「让用户去设环境变量」**，是别在残缺环境里跑构建（见第 2 条）。
|
||||
|
||||
**清理（有安全阀）**：
|
||||
|
||||
- ⚠ **绝不用 cmd / PowerShell 直接删**：`rd /s /q %SystemDrive%` 会被 cmd **展开成 `C:`**——
|
||||
等于对整块系统盘下令递归强删且不带确认。
|
||||
- ✅ 只用 bash 引号形态（`%` 在 bash 里没有特殊含义）：先 `find '%SystemDrive%' -type l` 确认不是
|
||||
reparse point / 符号链接，再 `rm -rf -- '%SystemDrive%'`；或 Node
|
||||
`fs.rmSync("%SystemDrive%", { recursive: true, force: true })`。
|
||||
- 它是**工具副产物**，不是谁在飞的改动——直接删，别 stash、更别提交（提交它 = 把本机缓存塞进历史）。
|
||||
|
||||
**让它不再污染工作区（两层，均已落地、可核验）**：
|
||||
|
||||
1. **进不了版本库**：`.gitignore:167` 的 `%SystemDrive%/`（2026-10-26 入库，注释里就写着复发证据）。
|
||||
核验三步（2026-10-28 复跑全绿）：造一份同名目录 + `.db` → `git status --porcelain` 零命中 →
|
||||
`git check-ignore -v <路径>` 落在 `.gitignore:167:%SystemDrive%/` → `git add -A --dry-run` 零暂存。
|
||||
2. **根本别再长出来**：本 skill 脚本 2026-10-28 起在拉起 UV4 前跑 `harden_windows_env()`——回填
|
||||
`SystemDrive`/`SystemRoot`/`windir`/`ComSpec`/`ProgramData`/`ALLUSERSPROFILE`/`ProgramFiles` 与
|
||||
`USERPROFILE`/`APPDATA`/`LOCALAPPDATA`/`TMP`/`TEMP`，就地展开环境里未展开的 `%VAR%` 字面量，
|
||||
并把 `TMP`/`TEMP` 指到真实目录；命中即打 `WARN: ENV_SPARSE:`。构建后再跑
|
||||
`check_percent_literal_junk()`，看到 `%SystemDrive%`/`%USERPROFILE%` 一类字面量目录就打
|
||||
`WARN: JUNK_DIR:`（**只告警不自动删**——删目录不该由构建脚本代劳）。守卫是兜底不是许可：
|
||||
**`@build` 仍要走 `ops_bash` / PowerShell（继承完整环境）**，非在 Node 里 spawn 就把 `env` 传全。
|
||||
@@ -28,83 +28,18 @@ whenToUse: 新增任务/加大缓冲/改栈/接入日志之前之后、链接报
|
||||
|
||||
## 测量身份口径（先钉树与时刻，再看数字）
|
||||
|
||||
### 1. 脚本按 `__file__` 定位产物，不按 cwd —— 跨树必须换脚本
|
||||
|
||||
```python
|
||||
# scripts/stack_report.py:36-38
|
||||
REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
|
||||
HTM_DEFAULT = REPO_ROOT / "MDK-ARM" / "STM32F407-Demo" / "STM32F407-Demo.htm"
|
||||
FREERTOS_C = REPO_ROOT / "Src" / "freertos.c" # 配置栈来源，无命令行开关
|
||||
# scripts/ram_report.py:16-18 同样用 dirname(dirname(abspath(__file__))) 定位 .map
|
||||
```
|
||||
|
||||
⇒ `cd 进别的 worktree 再跑主仓的脚本` 量的仍是**主仓**那份 .htm/.map，数字不可比。
|
||||
实测代价：这样一次"独立复算"量到主仓的 1,544 B / margin 1,016 B FAIL，据此写下的 +80 B 归因
|
||||
被队友的逐树逐帧差分表推翻——目标 worktree 的真数是 1,464 B / margin 1,096 B / PASS。
|
||||
|
||||
正确做法：**量哪棵树就跑那棵树自己的脚本**（该树必须已在这棵树上构建过、有自己的 .htm/.map；
|
||||
开树与合并的生命周期见 `task-worktree` skill）：
|
||||
|
||||
```bash
|
||||
'.venv/Scripts/python.exe' "<目标树>/scripts/stack_report.py"
|
||||
'.venv/Scripts/python.exe' "<目标树>/scripts/ram_report.py"
|
||||
```
|
||||
|
||||
⚠ 只给主仓脚本传 `-i <另一棵树的 .htm>`（或位置参数传另一棵树的 .map）**不够**：
|
||||
`stack_report.py` 的配置栈仍从**脚本所在那棵树**的 `Src/freertos.c` 读（`FREERTOS_C` 写死自 `__file__`，
|
||||
没有开关），两树栈配置一旦不同就是"半棵树的混合数字"。要整支脚本换树跑。
|
||||
|
||||
自检（每次复算都做）：报告头两行 `- Source: ...` 与 `- Linker run: ...` 就是你实际量的树和时刻。
|
||||
`Source` 若只打印一个裸文件名（不带 `MDK-ARM/...` 相对路径），说明 `-i` 指到了脚本 `REPO_ROOT` 之外的产物。
|
||||
|
||||
### 2. 重跑报告脚本**不算新测量**（复述 ≠ 复验）
|
||||
|
||||
`stack_report.py` / `ram_report.py` 只是解析盘上那一份 .htm/.map；产物没变，再跑一次数字必然不变。
|
||||
那只能叫"复述"，**不能写成"我复验过"**。要拿到新数字必须先有一次**新的 Linker run**（增量构建也算），
|
||||
并把新时刻与产物来源一并写进记录。
|
||||
|
||||
⚠ `ram_report.py` 正文里的 `> Generated: …` 是**脚本运行时刻**，重跑就变——它不是链接时刻，
|
||||
不能拿来当"这是新测量"的凭证。
|
||||
|
||||
### 3. 钉身份的取数法（.htm/.map 按约定不入库 → 把时刻写进正文/台账）
|
||||
|
||||
```bash
|
||||
grep -aE 'Last Updated|Maximum Stack Usage' MDK-ARM/STM32F407-Demo/STM32F407-Demo.htm | head -2
|
||||
# → "ARM Linker, 5060960: Last Updated: Mon Oct 26 22:52:12 2026"
|
||||
```
|
||||
|
||||
- .htm 里唯一的链接时刻锚点是 **`Last Updated:`**；`Linker run` 只是 `stack_report.py` 自己输出里的标签，
|
||||
`Date of Link`、`Image component` **不在 .htm 里**（实测按它们 grep 全空，白跑一轮）。
|
||||
- 取不到该字段时退回产物 mtime；同一笔链接里 .htm 与 .map 的 mtime 只差 ~0.1 s，可据此确认两份产物同源。
|
||||
再配 `git log -1 --format=%H` 与该树 `git status` 的未跟踪文件数。
|
||||
- 记录最小格式：**`tree/commit + Linker run 时刻 + 产物来源（本次构建 / 盘上既有）`**。
|
||||
本仓 .htm/.map 不入库，不钉时刻就等于把数字和树脱钩，下一个读数字的人无从判断它描述哪棵树。
|
||||
- 归属还能机械证明时顺手做掉：`git log --name-only <那笔>..HEAD -- "*.c" "*.h"` 逐行筛（排除 `.uvprojx`）。
|
||||
若那笔之后没有任何提交再碰固件源文件，产物描述的就是**在库那棵树**，不是提交前快照。
|
||||
- 同族坑：`git show :path` / `git show HEAD:path` 读的是索引/HEAD，**不是工作区**。
|
||||
1. 脚本按 __file__ 定位产物，不按 cwd —— 跨树必须换脚本（在主树跑脚本量任务树 = 拿旧 .map 当真值）
|
||||
2. 重跑报告脚本不算新测量（复述 ≠ 复验）：只有新的 Linker run 才算一次新测量
|
||||
3. 钉身份的取数法：.htm/.map 按约定不入库 → 把时刻写进正文/台账；记录最小格式 = tree/commit + Linker run 时刻 + 产物来源（本次构建 / 盘上既有）
|
||||
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [measurement-identity.md](reference/measurement-identity.md)。动手前先读那篇。
|
||||
|
||||
## 静态最坏链回归的归因（同涨同一数值 = 共享帧，不是调用方）
|
||||
|
||||
- **多条任务链分毫不差同涨/同降同一个数值**（实测 default/net/iec104 三条 +80 B；断环后九条链各 −80 B）
|
||||
⇒ 加深在这些任务**共用的被调帧 / 共享尾段**上，不在任何一个调用方。别逐个调用方翻，
|
||||
也**别先猜"新增了大局部缓冲"**——实测猜错过一次（`con_ring_try` 只有 24 B 帧、没有数组）。
|
||||
- 逐棵树逐帧比 frame size，不要只比总数：
|
||||
- `stack_report.py` 输出的「Frame-size ranking (own frame)」表 + 每任务最坏链文本，锁定**链尾公共段**
|
||||
（实测落在 `dbg_console_write_line → con_append → dbg_console_drain`，据此把账记到上一笔提交上）；
|
||||
- 直接在 .htm 里找环：`grep -ac 'In Cycle' MDK-ARM/STM32F407-Demo/STM32F407-Demo.htm`（实测 17 处），
|
||||
形态为 `Max Depth = 280 + In Cycle` 与 `Call Chain = Error_Handler => dbg_console_write_line (Cycle)`。
|
||||
`+ In Cycle` 表示 armlink 把**环上所有帧**计入含该环的每一条任务链——**链接器幻影环**能在无人改栈配置时让全仓链齐涨。
|
||||
- 实测样本（无人改栈配置、全仓链却齐涨的那种）：taskEXIT_CRITICAL ⇒ vPortExitCritical ⇒ configASSERT ⇒
|
||||
vApplicationAssertFailed ⇒ dbg_console_write_raw ⇒ 回到 console_log 内部 ⇒ 再进临界区；
|
||||
它使 `vApplicationAssertFailed` 的 Max Depth 由 ~40 B 变 128 B + In Cycle，差 88 B ≈ 三条链同涨 80 B 的来源。
|
||||
断环方向：内核临界区改 PRIMASK 保存/恢复（保存量放局部变量）→ 零调用帧、不成环；
|
||||
断环的**图证**（该帧从「136 B + In Cycle」变成「8 B、不再 In Cycle」）比数字更有说服力。
|
||||
- `Maximum Stack Usage = N bytes + Unknown(Cycles, Untraceable Function Pointers)` 里的 `+ Unknown(...)`
|
||||
说明静态图对环与函数指针不可完全解析，静态数是估计值，别当精确值上报。
|
||||
- 不采信任何口头结论：用**目标树的脚本 + `.venv` 解释器**自己复算；复算同样先按上节钉身份。
|
||||
- 处置后的下一步：抬栈（`Src/freertos.c` 的 `USER CODE` 区，属 Ask-first 动作）或收紧共享缓冲 / 断环，
|
||||
**改前改后各一次** `stack_report.py` + `ram_report.py`，且"改后"那次必须落在一次新的 Linker run 上；
|
||||
抬栈后跑 `gen_task_table.py` 同步任务表。
|
||||
- 多条任务链分毫不差同涨/同降同一个数值 ⇒ 加深在这些任务共用的被调帧 / 共享尾段上，不在任何一个调用方（别先猜「新增了大局部缓冲」，实测猜错过一次）
|
||||
- 逐棵树逐帧比 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)。动手前先读那篇。
|
||||
|
||||
## 判读口径
|
||||
|
||||
@@ -170,31 +105,15 @@ git add docs/内存管理/RAM预算台账.md docs/内存管理/RAM使用分析
|
||||
|
||||
### 回填链上的坑（实测）
|
||||
|
||||
- **`--write` 说「已是最新」而钩子还红** ≠ 钩子坏了，是**落点找错了**：tsv / 台账受管区 / 文档快照区
|
||||
三处各归一个旗标。按上表对号，别把同一个旗标重跑三遍；手改台账数字更不行——下次 `--write` 直接覆盖你，
|
||||
钩子仍按 .map 判漂移。
|
||||
- **tsv 落后只 WARN、不拦**：`--gate` 对「tsv 末行落后于当前 .map」只打印 `[WARN] …请跑 --update`
|
||||
（`ram_baseline.py:232`），**拦下来的是受管区漂移**。所以"钩子绿"绝不等于"趋势行也补了"，反之亦然，各查各的。
|
||||
- **`--gate` 无 .map → SKIP，而脚本自己写明「SKIP 不等于 PASS」**（`ram_baseline.py:177`）：
|
||||
新开的 task-worktree 从没在这棵树上构建过时必然走到这里；同一状态下 `--write` 直接
|
||||
`[FAIL] 找不到 .map 事实源，先 @build`（`ram_baseline.py:250`）——不是代码缺陷，是这棵树还没测过体积。
|
||||
无需 Keil 的强制兜底是 `scripts/check_size_gate.py --local`（= `scripts/ci_local.py` 的体积门禁步）与 CI 的 `--ci`。
|
||||
- **`--map <path>` 只换读、不换写**：`LEDGER`（`ram_baseline.py:45`）与 `TARGETS`（`check_mem_numbers.py:53-54`）
|
||||
都由 `REPO_ROOT = Path(__file__).resolve().parent.parent` 算出。拿主仓脚本配 `--map <另一棵树>/…map` 去 `--write`，
|
||||
等于用别的树的数字**改写主仓的台账**——比"半棵树混合数字"更糟，因为它落盘了。回填永远用本树自己的脚本。
|
||||
- **`--scan` 的散句告警 `--write` 不替你改**：正文里手抄的旧值（"现 RW_IRAM1 62.6%" 这类散句）只告警，
|
||||
脚本明确写着「`--write` 不会自动改写正文」（`check_mem_numbers.py:418`）→ 人工按受管区改那一行
|
||||
（Edit 精确替换；含中文的文档绝不整文件重写）。
|
||||
- **`--update` 的盖戳排在索引后面**：它顺带调 `check_size_gate.cmd_stamp()`（`ram_baseline.py:345`），
|
||||
而凭证指纹按 **git 索引内容**生成，有未 staged 的脏改动时**拒盖**，且这里只 `[WARN]`、不改返回值
|
||||
→ 现象是 tsv 多了一行而凭证仍是旧的，要等 `ci_local` 的体积门禁步 / CI 体积门禁那一侧才报出来。
|
||||
要么先 `git add` 再 `--update`，要么补跑 `python scripts/check_size_gate.py --stamp`。
|
||||
- **改写型钩子当场改文件是流程不是故障**：`trailing-whitespace` / `end-of-file-fixer` 报
|
||||
`files were modified by this hook`（新建的 .c 最常触发）时，先读 `ci-artifacts/cui.log` 的真实报错确认是哪几条红，
|
||||
`git add` 被改写的文件后重提。两条改写红 + 两条内存红混在同一次里时，别顺手把内存那条也当"钩子误报"绕过去。
|
||||
- **`mem-budget` 触发面很宽**：`files:` 覆盖 `App/` `Drivers/BSP/` `Src/` `Inc/` `Lib/lv_conf.h`
|
||||
`test/board/` `scripts/ram_baseline.` `docs/内存管理/` `.pre-commit-config.yaml`，且 pre-commit 4.x 已无
|
||||
`always: true` —— 纯 UI / 纯文档提交照样被它拦：盘上 .map 与台账不同源就红，跟这笔提交碰没碰内存文件无关。
|
||||
- --write 说「已是最新」而钩子还红
|
||||
- tsv 落后只 WARN、不拦
|
||||
- --gate 无 .map → SKIP，而脚本自己写明「SKIP 不等于 PASS」
|
||||
- --map <path> 只换读、不换写
|
||||
- --scan 的散句告警 --write 不替你改
|
||||
- --update 的盖戳排在索引后面
|
||||
- 改写型钩子当场改文件是流程不是故障
|
||||
- mem-budget 触发面很宽
|
||||
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [backfill-pitfalls.md](reference/backfill-pitfalls.md)。动手前先读那篇。
|
||||
|
||||
## 运行时峰值抖动与"算不算劣化"
|
||||
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# 回填链上的坑（实测）（自 SKILL.md 外置）
|
||||
|
||||
> 本文由 mem-budget 的 SKILL.md「回填链上的坑（实测）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
|
||||
|
||||
- **`--write` 说「已是最新」而钩子还红** ≠ 钩子坏了，是**落点找错了**：tsv / 台账受管区 / 文档快照区
|
||||
三处各归一个旗标。按上表对号，别把同一个旗标重跑三遍；手改台账数字更不行——下次 `--write` 直接覆盖你，
|
||||
钩子仍按 .map 判漂移。
|
||||
- **tsv 落后只 WARN、不拦**：`--gate` 对「tsv 末行落后于当前 .map」只打印 `[WARN] …请跑 --update`
|
||||
（`ram_baseline.py:232`），**拦下来的是受管区漂移**。所以"钩子绿"绝不等于"趋势行也补了"，反之亦然，各查各的。
|
||||
- **`--gate` 无 .map → SKIP，而脚本自己写明「SKIP 不等于 PASS」**（`ram_baseline.py:177`）：
|
||||
新开的 task-worktree 从没在这棵树上构建过时必然走到这里；同一状态下 `--write` 直接
|
||||
`[FAIL] 找不到 .map 事实源，先 @build`（`ram_baseline.py:250`）——不是代码缺陷，是这棵树还没测过体积。
|
||||
无需 Keil 的强制兜底是 `scripts/check_size_gate.py --local`（= `scripts/ci_local.py` 的体积门禁步）与 CI 的 `--ci`。
|
||||
- **`--map <path>` 只换读、不换写**：`LEDGER`（`ram_baseline.py:45`）与 `TARGETS`（`check_mem_numbers.py:53-54`）
|
||||
都由 `REPO_ROOT = Path(__file__).resolve().parent.parent` 算出。拿主仓脚本配 `--map <另一棵树>/…map` 去 `--write`，
|
||||
等于用别的树的数字**改写主仓的台账**——比"半棵树混合数字"更糟，因为它落盘了。回填永远用本树自己的脚本。
|
||||
- **`--scan` 的散句告警 `--write` 不替你改**：正文里手抄的旧值（"现 RW_IRAM1 62.6%" 这类散句）只告警，
|
||||
脚本明确写着「`--write` 不会自动改写正文」（`check_mem_numbers.py:418`）→ 人工按受管区改那一行
|
||||
（Edit 精确替换；含中文的文档绝不整文件重写）。
|
||||
- **`--update` 的盖戳排在索引后面**：它顺带调 `check_size_gate.cmd_stamp()`（`ram_baseline.py:345`），
|
||||
而凭证指纹按 **git 索引内容**生成，有未 staged 的脏改动时**拒盖**，且这里只 `[WARN]`、不改返回值
|
||||
→ 现象是 tsv 多了一行而凭证仍是旧的，要等 `ci_local` 的体积门禁步 / CI 体积门禁那一侧才报出来。
|
||||
要么先 `git add` 再 `--update`，要么补跑 `python scripts/check_size_gate.py --stamp`。
|
||||
- **改写型钩子当场改文件是流程不是故障**：`trailing-whitespace` / `end-of-file-fixer` 报
|
||||
`files were modified by this hook`（新建的 .c 最常触发）时，先读 `ci-artifacts/cui.log` 的真实报错确认是哪几条红，
|
||||
`git add` 被改写的文件后重提。两条改写红 + 两条内存红混在同一次里时，别顺手把内存那条也当"钩子误报"绕过去。
|
||||
- **`mem-budget` 触发面很宽**：`files:` 覆盖 `App/` `Drivers/BSP/` `Src/` `Inc/` `Lib/lv_conf.h`
|
||||
`test/board/` `scripts/ram_baseline.` `docs/内存管理/` `.pre-commit-config.yaml`，且 pre-commit 4.x 已无
|
||||
`always: true` —— 纯 UI / 纯文档提交照样被它拦：盘上 .map 与台账不同源就红，跟这笔提交碰没碰内存文件无关。
|
||||
@@ -0,0 +1,58 @@
|
||||
# 测量身份口径（先钉树与时刻，再看数字）（自 SKILL.md 外置）
|
||||
|
||||
> 本文由 mem-budget 的 SKILL.md「测量身份口径（先钉树与时刻，再看数字）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
|
||||
|
||||
### 1. 脚本按 `__file__` 定位产物，不按 cwd —— 跨树必须换脚本
|
||||
|
||||
```python
|
||||
# scripts/stack_report.py:36-38
|
||||
REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
|
||||
HTM_DEFAULT = REPO_ROOT / "MDK-ARM" / "STM32F407-Demo" / "STM32F407-Demo.htm"
|
||||
FREERTOS_C = REPO_ROOT / "Src" / "freertos.c" # 配置栈来源，无命令行开关
|
||||
# scripts/ram_report.py:16-18 同样用 dirname(dirname(abspath(__file__))) 定位 .map
|
||||
```
|
||||
|
||||
⇒ `cd 进别的 worktree 再跑主仓的脚本` 量的仍是**主仓**那份 .htm/.map，数字不可比。
|
||||
实测代价：这样一次"独立复算"量到主仓的 1,544 B / margin 1,016 B FAIL，据此写下的 +80 B 归因
|
||||
被队友的逐树逐帧差分表推翻——目标 worktree 的真数是 1,464 B / margin 1,096 B / PASS。
|
||||
|
||||
正确做法：**量哪棵树就跑那棵树自己的脚本**（该树必须已在这棵树上构建过、有自己的 .htm/.map；
|
||||
开树与合并的生命周期见 `task-worktree` skill）：
|
||||
|
||||
```bash
|
||||
'.venv/Scripts/python.exe' "<目标树>/scripts/stack_report.py"
|
||||
'.venv/Scripts/python.exe' "<目标树>/scripts/ram_report.py"
|
||||
```
|
||||
|
||||
⚠ 只给主仓脚本传 `-i <另一棵树的 .htm>`（或位置参数传另一棵树的 .map）**不够**：
|
||||
`stack_report.py` 的配置栈仍从**脚本所在那棵树**的 `Src/freertos.c` 读（`FREERTOS_C` 写死自 `__file__`，
|
||||
没有开关），两树栈配置一旦不同就是"半棵树的混合数字"。要整支脚本换树跑。
|
||||
|
||||
自检（每次复算都做）：报告头两行 `- Source: ...` 与 `- Linker run: ...` 就是你实际量的树和时刻。
|
||||
`Source` 若只打印一个裸文件名（不带 `MDK-ARM/...` 相对路径），说明 `-i` 指到了脚本 `REPO_ROOT` 之外的产物。
|
||||
|
||||
### 2. 重跑报告脚本**不算新测量**（复述 ≠ 复验）
|
||||
|
||||
`stack_report.py` / `ram_report.py` 只是解析盘上那一份 .htm/.map；产物没变，再跑一次数字必然不变。
|
||||
那只能叫"复述"，**不能写成"我复验过"**。要拿到新数字必须先有一次**新的 Linker run**（增量构建也算），
|
||||
并把新时刻与产物来源一并写进记录。
|
||||
|
||||
⚠ `ram_report.py` 正文里的 `> Generated: …` 是**脚本运行时刻**，重跑就变——它不是链接时刻，
|
||||
不能拿来当"这是新测量"的凭证。
|
||||
|
||||
### 3. 钉身份的取数法（.htm/.map 按约定不入库 → 把时刻写进正文/台账）
|
||||
|
||||
```bash
|
||||
grep -aE 'Last Updated|Maximum Stack Usage' MDK-ARM/STM32F407-Demo/STM32F407-Demo.htm | head -2
|
||||
# → "ARM Linker, 5060960: Last Updated: Mon Oct 26 22:52:12 2026"
|
||||
```
|
||||
|
||||
- .htm 里唯一的链接时刻锚点是 **`Last Updated:`**；`Linker run` 只是 `stack_report.py` 自己输出里的标签，
|
||||
`Date of Link`、`Image component` **不在 .htm 里**（实测按它们 grep 全空，白跑一轮）。
|
||||
- 取不到该字段时退回产物 mtime；同一笔链接里 .htm 与 .map 的 mtime 只差 ~0.1 s，可据此确认两份产物同源。
|
||||
再配 `git log -1 --format=%H` 与该树 `git status` 的未跟踪文件数。
|
||||
- 记录最小格式：**`tree/commit + Linker run 时刻 + 产物来源（本次构建 / 盘上既有）`**。
|
||||
本仓 .htm/.map 不入库，不钉时刻就等于把数字和树脱钩，下一个读数字的人无从判断它描述哪棵树。
|
||||
- 归属还能机械证明时顺手做掉：`git log --name-only <那笔>..HEAD -- "*.c" "*.h"` 逐行筛（排除 `.uvprojx`）。
|
||||
若那笔之后没有任何提交再碰固件源文件，产物描述的就是**在库那棵树**，不是提交前快照。
|
||||
- 同族坑：`git show :path` / `git show HEAD:path` 读的是索引/HEAD，**不是工作区**。
|
||||
@@ -0,0 +1,24 @@
|
||||
# 静态最坏链回归的归因（同涨同一数值 = 共享帧，不是调用方）（自 SKILL.md 外置）
|
||||
|
||||
> 本文由 mem-budget 的 SKILL.md「静态最坏链回归的归因（同涨同一数值 = 共享帧，不是调用方）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
|
||||
|
||||
- **多条任务链分毫不差同涨/同降同一个数值**（实测 default/net/iec104 三条 +80 B；断环后九条链各 −80 B）
|
||||
⇒ 加深在这些任务**共用的被调帧 / 共享尾段**上，不在任何一个调用方。别逐个调用方翻，
|
||||
也**别先猜"新增了大局部缓冲"**——实测猜错过一次（`con_ring_try` 只有 24 B 帧、没有数组）。
|
||||
- 逐棵树逐帧比 frame size，不要只比总数：
|
||||
- `stack_report.py` 输出的「Frame-size ranking (own frame)」表 + 每任务最坏链文本，锁定**链尾公共段**
|
||||
（实测落在 `dbg_console_write_line → con_append → dbg_console_drain`，据此把账记到上一笔提交上）；
|
||||
- 直接在 .htm 里找环：`grep -ac 'In Cycle' MDK-ARM/STM32F407-Demo/STM32F407-Demo.htm`（实测 17 处），
|
||||
形态为 `Max Depth = 280 + In Cycle` 与 `Call Chain = Error_Handler => dbg_console_write_line (Cycle)`。
|
||||
`+ In Cycle` 表示 armlink 把**环上所有帧**计入含该环的每一条任务链——**链接器幻影环**能在无人改栈配置时让全仓链齐涨。
|
||||
- 实测样本（无人改栈配置、全仓链却齐涨的那种）：taskEXIT_CRITICAL ⇒ vPortExitCritical ⇒ configASSERT ⇒
|
||||
vApplicationAssertFailed ⇒ dbg_console_write_raw ⇒ 回到 console_log 内部 ⇒ 再进临界区；
|
||||
它使 `vApplicationAssertFailed` 的 Max Depth 由 ~40 B 变 128 B + In Cycle，差 88 B ≈ 三条链同涨 80 B 的来源。
|
||||
断环方向：内核临界区改 PRIMASK 保存/恢复（保存量放局部变量）→ 零调用帧、不成环；
|
||||
断环的**图证**（该帧从「136 B + In Cycle」变成「8 B、不再 In Cycle」）比数字更有说服力。
|
||||
- `Maximum Stack Usage = N bytes + Unknown(Cycles, Untraceable Function Pointers)` 里的 `+ Unknown(...)`
|
||||
说明静态图对环与函数指针不可完全解析，静态数是估计值，别当精确值上报。
|
||||
- 不采信任何口头结论：用**目标树的脚本 + `.venv` 解释器**自己复算；复算同样先按上节钉身份。
|
||||
- 处置后的下一步：抬栈（`Src/freertos.c` 的 `USER CODE` 区，属 Ask-first 动作）或收紧共享缓冲 / 断环，
|
||||
**改前改后各一次** `stack_report.py` + `ram_report.py`，且"改后"那次必须落在一次新的 Linker run 上；
|
||||
抬栈后跑 `gen_task_table.py` 同步任务表。
|
||||
@@ -23,112 +23,38 @@ whenToUse: 某个计数/数字变了要跨 md/yaml/py/txt 同步、用户说「
|
||||
|
||||
## Steps
|
||||
|
||||
1. **实测真值：先剔伪命中，再双源互证**（不抄用户口述、不抄另一处文档）。逐数走上面那张表；两个来源对不上时**先找分歧根因**（把全部命中逐条打印出来看），不要取第一个、不要取平均，并在结论里写明分歧与取舍（实测：菜单 `#page=` 计数 29 对 注册表 28，根因是头部注释示例行）。
|
||||
|
||||
```bash
|
||||
cd "<repo>"
|
||||
ls simulator/tests/ref/shot_*.bin | wc -l # 张数（判据 = 入库实数）
|
||||
awk '/^PAGES = \[/,/^\]/' simulator/tests/check_content_pages.py | grep -cE '^ *\("' # 页数（第二个来源，两者必须一致）
|
||||
grep -n '#page=' ui_menu_tree.txt | head -3 # 先看首条是不是注释示例行，再定叶数
|
||||
grep -rn 'UI_PAGE_MAP_COUNT' Drivers/BSP/UI/ui_page_registry.h # 已绑叶数（生成物）
|
||||
grep -c '\.bitmap_index' Drivers/BSP/UI/ui_font_cn_12.c # 314 = 含 notdef；字形 = 该数 - 1
|
||||
& '.venv\Scripts\python.exe' -c "import yaml;d=yaml.safe_load(open('.pre-commit-config.yaml',encoding='utf-8'));print(sum(len(r['hooks']) for r in d['repos']))" # 钩子数口径
|
||||
```
|
||||
|
||||
⚠ **权威脚本输出乱码时**（`check_font_charset.py` 在 GBK 代码页下整行打印成 U+FFFD 替换字符串 + `: PASS`，数字全读不出来），**改为直接数源文件里符号出现次数**（`.bitmap_index` / `.range_start` / 码点唯一化）——不许臆读乱码，也不许因此退回去抄文档里的旧数。
|
||||
|
||||
2. **全形态 + 全命中面扫描**。一个数一次列出它全部历史形态，别只扫当前旧值：本轮 = `122/217`、`179/274`、`185/280`、`47 → 53`、`53 → 60`、`PAGES = 53`、`UI_PAGE_MAP_COUNT = 22`、`已绑 22 叶`、`未绑 11`、`内容页 53 页`。
|
||||
|
||||
```bash
|
||||
grep -rn --include=*.md --include=*.py --include=*.yaml --include=*.txt --include=*.c --include=*.h \
|
||||
-E '122 唯一字|217 字形|179 汉字|274 字形|185 唯一字|280 字形|47 → 53|53 → 60|内容页 53|PAGES = 53|UI_PAGE_MAP_COUNT = 22|已绑 22|未绑 11' . \
|
||||
| grep -v -E '^\./(ci-artifacts|\.mnemon|\.dsh/runs)/'
|
||||
```
|
||||
|
||||
**命中面比「文档」宽**，至少包含：`docs/**`、`AGENTS.md`、`.pre-commit-config.yaml`（**钩子 `name:` 显示名内嵌页数**：`name: UI 像素回归（菜单 8 状态 + 内容页 60 页 黄金参考）` 就是命中点）、`scripts/*.py`、`simulator/**/README.md`、以及 **`.dsh/skills/*/SKILL.md`**（本窗 `font-regen` 正文自带 179/274 计数，直到 step 150 才发现；编号门禁退役那轮 `id-family-semantic-migration`、`task-worktree` 两个 skill 正文与 `scripts/README.md` 同样是引用面）。
|
||||
|
||||
先列出 `文件:行:全文`，**判定前必须看整行**——`cut -c1-120` 会截掉后半句（那里常写着日期戳或口径）。
|
||||
|
||||
3. **逐条分类，五类各走各的路**（本 playbook 的核心，别用一条规则套全部命中）：
|
||||
|
||||
| 类别 | 判定 | 动作 |
|
||||
|---|---|---|
|
||||
| 当前态陈述 | 描述「现在是多少」 | 改成实测真值 |
|
||||
| 变更记录历史行 | 形如「47 → 53 页」的当日事实 | **原样冻结不回改**——但这条**只适用于保留变更记录的 5 篇**（台账 / 被别处当唯一证据出处的文档，清单 → `docs/文档规范.md` §5.1）；其余文档的变更记录节已于 2026-10-28 整节删除，**不再追加任何流水行**，数字同步只改**当前态** |
|
||||
| 同数不同义 | `最坏路径 < 40KB` 这类内存/绘制缓冲红线 | **不动**，并在结论里写明「为什么不动」 |
|
||||
| 带日期戳的测量 | 「2026-10-26 实跑 …覆盖当时 40 页中的」 | **不臆改新数**，只补「当时」两字锁口径；新数留待下次实跑回填 |
|
||||
| 数字对但**口径描述错** | 数没错、句子把口径讲错了（实测：写「218 字（含 ASCII/符号，共 313 字形）」，而 `ui_cn_chars.txt` 的 218 个码点**全为非 ASCII**） | **另起一笔只改口径的提交**（`6daa01ae`），不与数字同步混笔；这类命中在任何数字 diff 里都看不见，只能把口径句逐句读一遍 |
|
||||
|
||||
拿不准就回到第 2 步把整行打印出来再判；判错历史行 = 把当天事实改成假账。
|
||||
|
||||
4. **每处先读现文，再逐条字面替换并断言命中数**（弃用整文件正则批处理）。本窗两度返工都是没先读现文：step 45 断言 `HIT 0` 抛错（目标串与现文不一致），step 44 是脚本语法错。脚本写成临时文件再跑（内嵌 heredoc/模板字符串里的反引号会截断整脚本），按**字节**替换以保 BOM 与行尾不动：
|
||||
|
||||
```python
|
||||
import pathlib, sys
|
||||
sys.stdout.reconfigure(encoding='utf-8', errors='replace')
|
||||
JOBS = [ # (文件, old, new, 期望命中数)
|
||||
('AGENTS.md', '内容页 53 页黄金参考', '内容页 60 页黄金参考', 1),
|
||||
('.pre-commit-config.yaml', '内容页 53 页 黄金参考', '内容页 60 页 黄金参考', 1),
|
||||
('docs/架构设计/项目架构总览.md', '122 字/217 字形', '218 字/313 字形', 1),
|
||||
('docs/UI设计/UI_自动化测试流程.md', '文本断言 **310 条**、覆盖 40 页中的', '文本断言 **310 条**、覆盖当时 40 页中的', 1),
|
||||
]
|
||||
for path, old, new, expect in JOBS:
|
||||
p = pathlib.Path(path); raw = p.read_bytes()
|
||||
o, n = old.encode('utf-8'), new.encode('utf-8')
|
||||
got = raw.count(o)
|
||||
assert got == expect, f'{path}: 命中 {got}，期望 {expect}（未写入）'
|
||||
assert o != n, f'{path}: old 与 new 相同'
|
||||
p.write_bytes(raw.replace(o, n))
|
||||
print(f'OK {path}: {old} -> {new} x{got}')
|
||||
```
|
||||
|
||||
每行打印 `old -> new xN`，收口时这串输出就是「改了哪几处」的账。脚本报错/没编译过，**先 `git diff --stat` 确认零写入**再换写法（不要在半落地状态上叠改）。
|
||||
|
||||
- **反引号**：TS 侧先用可见占位符（如 `~TB~`）写文本，落盘前再还原成真反引号 —— `const BT = String.fromCharCode(96); const q = s => s.split(TOKEN).join(BT)`（本窗实测：直接把带反引号的串塞进模板字符串/heredoc，整批零落地或把变更记录行写坏）。用 `tools.edit` 批量改时同样先 `await tools.read` 现文再传 `old_string`；批量里若某条 `old_string` 与 `new_string` 相同会报 `must differ` —— **只有该条作废、其余已落盘**，别整批重跑。
|
||||
- **历史行被写坏**（反引号及紧随其后的字符经工具传递被吞 → 变更记录行只剩半行、尾部出现 `??` 这类残迹）：立刻按**无反引号兜底写法整行重写**——裸词 `accident / oper / alarm / start / yk`、页面绑定写成不带反引号的 `#page=`——而不是拿同样带反引号的串再改一遍（实测连返工三次：step 81→82→83→85）。
|
||||
|
||||
5. **一笔只装一类事**。数字同步一笔（`cbb4fdb8`：11 处 + 变更记录一行）；口径更正另起一笔（`6daa01ae`）；提交后复扫逮到的漏网当前态再补独立一笔（`11d60057`）。钩子一增一减写成一个当日行的两个阶段（51 → 52 加 `id-check-new`、随即 52 → 51 摘 `id-check`），别写两行互相打脸。提交说明如实写（「先认一笔自己的错：上一笔的未绑 21 叶是探针错」），别把口径修正包装成「补充说明」。
|
||||
|
||||
6. **被改文件全文通读，核对其余小节**——不是只看 diff。同一文档内互相引用的小节必须一致（本窗产品需求：§2.4 立项未排、§5.14 FR-SOE-3、§8.2 绑定现状、§8.3 已绑分页表、§9.1 差距表、§9.2 顺序表六处同时引用这四个数；`docs/任务规划/README.md` §1 当前执行表 vs §2 全项目顺序表）。若发现上一笔自己写进文档的数**口径就错了**，明确认错并改正，同时把**可复核的重算方法**写进文档（「按缩进判叶子：有更深缩进后继者即非叶子」），防止再错。
|
||||
|
||||
7. **提交后再复扫一遍**（收尾硬步骤，不许省，也不许只在提交前扫）。按第 2 步的**全部**旧形态整仓再扫一次，逐条分类为 当前态 / 历史行 / 同数不同义：本窗 `cbb4fdb8` 提交后复扫得 14 条命中，12 条以上都在变更记录历史行（`47 → 53`、`53 → 60`、`122/217` 冻结），**唯一残留的当前态命中**是 `docs/架构设计/项目架构总览.md` §3「界面层」那行 → 单独补一笔 `11d60057`。说不出归属的就是漏改。
|
||||
|
||||
```bash
|
||||
grep -rn -E '22 叶|未绑 11|11 叶|53 页|122 唯一字|217 字形|185 唯一字|280 字形|内容页 53|PAGES = 53|UI_PAGE_MAP_COUNT = 22' \
|
||||
. | grep -v -E '^\./(ci-artifacts|\.mnemon|\.dsh/runs)/'
|
||||
```
|
||||
|
||||
8. **跑门禁、分笔提交**（`git commit` 属 Ask first，须用户明确指示后再做）：
|
||||
|
||||
```bash
|
||||
& '.venv\Scripts\python.exe' scripts/check_doc_links.py --all --sections-strict # 期望「文档路径检查通过（N 个文档）」
|
||||
& '.venv\Scripts\python.exe' scripts/check_ids_new.py --self-test # 新增行编号门禁（旧 check_ids.py 已退役进 scripts/archive/id_gate/）
|
||||
& '.venv\Scripts\python.exe' scripts/ci_local.py # 或 pre-commit run --files <被改文件>
|
||||
```
|
||||
|
||||
PowerShell 形态把 `./.venv/Scripts/python.exe` 换成 `& '.venv\Scripts\python.exe'`。提交信息一律 `git commit -F <UTF-8 无 BOM 文件>`，别用 `-m`（中文长标题易超 100 字符、终端代码页会转码）；标题 ≤100、**正文每行 ≤80**（实测把正文压到 66/78 字符才过 gitlint）。
|
||||
1. 实测真值：先剔伪命中，再双源互证
|
||||
2. 全形态 + 全命中面扫描
|
||||
3. 逐条分类，五类各走各的路
|
||||
4. 每处先读现文，再逐条字面替换并断言命中数
|
||||
5. 一笔只装一类事
|
||||
6. 被改文件全文通读，核对其余小节
|
||||
7. 提交后再复扫一遍
|
||||
8. 跑门禁、分笔提交
|
||||
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [steps.md](reference/steps.md)。动手前先读那篇。
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- **把伪命中计进真值**：`grep '#page='` 的首条是菜单文件头部注释里的示例行，29 里含它；真值是注册表 `UI_PAGE_MAP_COUNT` 的 28。任何「数出现次数」式计数，先打印全部命中逐条看，剔注释行/模板行/示例行。
|
||||
- **字形数没剔 notdef**：`.bitmap_index` 314 条里第 1 条是 notdef，字形数是 **313**；照抄 314 就把占位符当成了字形。
|
||||
- **数字对但口径描述错**：218 这个数两处都对，错在「含 ASCII/符号」这句口径（实测 218 个码点全为非 ASCII）。它不进任何数字 diff，只能逐句读口径句；且必须**另起一笔**，混进数字同步那笔会让 review 者以为只是顺手改措辞。
|
||||
- **权威脚本乱码就臆读或退回抄文档**：Windows 代码页下 `font-charset` 的整行输出退化成 U+FFFD 替换字符时，改数源文件符号出现次数，别猜、别抄旧文档。
|
||||
- **钩子数用 `grep` 声明行**：多算一条注释掉的候选钩子（51 变 52）；反过来在配置注释里复述那个 grep 字面量会让文本计数再虚高 1。口径只认 YAML 解析后的条目数，且要与 AGENTS.md、`docs/门禁说明/README.md` §2 标题、`ci_local.py` 实跑 passed+failed+skipped 三数同源。
|
||||
- **张数与页数互相冒充**：一个 12 行分页页第 2 页要单独拍一张，于是「+2 页」可能等于「+3 张」。两个数分别报、分别换算，别互相顶替。
|
||||
- **只扫 docs/**：漏 `.pre-commit-config.yaml` 钩子 `name:` 显示名里的页数、AGENTS.md 钩子清单、`.dsh/skills/*/SKILL.md` 自带的计数与脚本路径（skill 正文也是命中面：font-regen 的 179/274 本窗最后才改）。
|
||||
- **提交完就收工**：第 7 步的提交后复扫才是把漏网当前态（架构总览 §3）揪出来的那一步；漏了它，仓库里就留下一行「当前态写旧数」直到别人再扫。
|
||||
- **去已删掉变更记录的文档里「补一行流水」**：2026-10-28 起全仓只有 **5 篇**保留变更记录表（清单 → `docs/文档规范.md` §5.1），计数同步**只改当前态**、过程交给 `git log`，别再到别的文档里找或加变更记录行。真要往那 5 篇的台账里加行，历史坑照旧：它们的表按日期**升序** → 新行**追加为末行**，插表顶会把首行「初版」挤成第二行。
|
||||
- **历史行被当陈旧值改掉**：「47 → 53 页」是当天事实，改了就是伪造历史；正确动作是**只改当前态那几处**、历史行一个字不动（保留变更记录的 5 篇要写台账也只追加、不回改）。**历史行被写坏**时按无反引号兜底写法整行重写，别用同样写法再改一遍。
|
||||
- **照抄用户给的数**：用户说「从 40 扩到 47」也要自己数 `ref/*.bin`；数出来不一定是 47。
|
||||
- **把节点行当叶子数**：42 是 `ui_menu_tree.txt` 的节点行数、33 才是叶子；不读文件头规则就数错（实测把错数写进两份文档，下一轮才自查出来）。
|
||||
- **整文件正则批处理**：第一次尝试的正则没编译过、整批零落地。改法 = 逐条字面替换 + 每处 `assert count == expect`。
|
||||
- **反引号截断**：脚本里含 `ui-golden`、`#page=` 这类反引号时，经 TS 模板字符串/内嵌 heredoc 传递会被截断，表现为「整批零落地」或「历史行写坏」。落成脚本文件再执行，或用 `chr(96)` / `String.fromCharCode(96)` 拼。
|
||||
- **只改记得的那节**：上一笔只改 §2 与开篇、漏改 §1，用户当场问出「§1 说 16 叶、§2 说剩 3 项，自相矛盾」。改完必须全文通读同一文档所有小节。
|
||||
- **误报跟着改**：「< 40KB」是绘制缓冲红线，与页数无关。
|
||||
- **带日期戳的测量臆改新数**：「2026-10-26 实跑 …覆盖 40 页」改成 47 就是把历史测量冒充现值；只加「当时」。
|
||||
- **用截断的 grep 输出判定**：`cut -c` 截掉的后半句常含日期戳/口径，据此分类必错。
|
||||
- **新写文本撞编号门禁**：新增的「单字母+数字」裸形（如 `SD2506`、`CP56Time2a`）会被 `id-check-new`（只查 `git diff` 新增行、零语料）拦下；旧的八项全库校验 `id-check` 已于 2026-10-28 退役进 `scripts/archive/id_gate/`。撞到就把自己这批文本逐处归因或改形态描述，别去放宽白名单。
|
||||
- 把伪命中计进真值
|
||||
- 字形数没剔 notdef
|
||||
- 数字对但口径描述错
|
||||
- 权威脚本乱码就臆读或退回抄文档
|
||||
- 钩子数用 grep 声明行
|
||||
- 张数与页数互相冒充
|
||||
- 只扫 docs/
|
||||
- 提交完就收工
|
||||
- 去已删掉变更记录的文档里「补一行流水」
|
||||
- 历史行被当陈旧值改掉
|
||||
- 照抄用户给的数
|
||||
- 把节点行当叶子数
|
||||
- 整文件正则批处理
|
||||
- 反引号截断
|
||||
- 只改记得的那节
|
||||
- 误报跟着改
|
||||
- 带日期戳的测量臆改新数
|
||||
- 用截断的 grep 输出判定
|
||||
- 新写文本撞编号门禁
|
||||
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [pitfalls.md](reference/pitfalls.md)。动手前先读那篇。
|
||||
|
||||
## Verification
|
||||
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
# Pitfalls（自 SKILL.md 外置）
|
||||
|
||||
> 本文由 stale-doc-count-sweep 的 SKILL.md「Pitfalls」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
|
||||
|
||||
- **把伪命中计进真值**：`grep '#page='` 的首条是菜单文件头部注释里的示例行，29 里含它；真值是注册表 `UI_PAGE_MAP_COUNT` 的 28。任何「数出现次数」式计数，先打印全部命中逐条看，剔注释行/模板行/示例行。
|
||||
- **字形数没剔 notdef**：`.bitmap_index` 314 条里第 1 条是 notdef，字形数是 **313**；照抄 314 就把占位符当成了字形。
|
||||
- **数字对但口径描述错**：218 这个数两处都对，错在「含 ASCII/符号」这句口径（实测 218 个码点全为非 ASCII）。它不进任何数字 diff，只能逐句读口径句；且必须**另起一笔**，混进数字同步那笔会让 review 者以为只是顺手改措辞。
|
||||
- **权威脚本乱码就臆读或退回抄文档**：Windows 代码页下 `font-charset` 的整行输出退化成 U+FFFD 替换字符时，改数源文件符号出现次数，别猜、别抄旧文档。
|
||||
- **钩子数用 `grep` 声明行**：多算一条注释掉的候选钩子（51 变 52）；反过来在配置注释里复述那个 grep 字面量会让文本计数再虚高 1。口径只认 YAML 解析后的条目数，且要与 AGENTS.md、`docs/门禁说明/README.md` §2 标题、`ci_local.py` 实跑 passed+failed+skipped 三数同源。
|
||||
- **张数与页数互相冒充**：一个 12 行分页页第 2 页要单独拍一张，于是「+2 页」可能等于「+3 张」。两个数分别报、分别换算，别互相顶替。
|
||||
- **只扫 docs/**：漏 `.pre-commit-config.yaml` 钩子 `name:` 显示名里的页数、AGENTS.md 钩子清单、`.dsh/skills/*/SKILL.md` 自带的计数与脚本路径（skill 正文也是命中面：font-regen 的 179/274 本窗最后才改）。
|
||||
- **提交完就收工**：第 7 步的提交后复扫才是把漏网当前态（架构总览 §3）揪出来的那一步；漏了它，仓库里就留下一行「当前态写旧数」直到别人再扫。
|
||||
- **去已删掉变更记录的文档里「补一行流水」**：2026-10-28 起全仓只有 **5 篇**保留变更记录表（清单 → `docs/文档规范.md` §5.1），计数同步**只改当前态**、过程交给 `git log`，别再到别的文档里找或加变更记录行。真要往那 5 篇的台账里加行，历史坑照旧：它们的表按日期**升序** → 新行**追加为末行**，插表顶会把首行「初版」挤成第二行。
|
||||
- **历史行被当陈旧值改掉**：「47 → 53 页」是当天事实，改了就是伪造历史；正确动作是**只改当前态那几处**、历史行一个字不动（保留变更记录的 5 篇要写台账也只追加、不回改）。**历史行被写坏**时按无反引号兜底写法整行重写，别用同样写法再改一遍。
|
||||
- **照抄用户给的数**：用户说「从 40 扩到 47」也要自己数 `ref/*.bin`；数出来不一定是 47。
|
||||
- **把节点行当叶子数**：42 是 `ui_menu_tree.txt` 的节点行数、33 才是叶子；不读文件头规则就数错（实测把错数写进两份文档，下一轮才自查出来）。
|
||||
- **整文件正则批处理**：第一次尝试的正则没编译过、整批零落地。改法 = 逐条字面替换 + 每处 `assert count == expect`。
|
||||
- **反引号截断**：脚本里含 `ui-golden`、`#page=` 这类反引号时，经 TS 模板字符串/内嵌 heredoc 传递会被截断，表现为「整批零落地」或「历史行写坏」。落成脚本文件再执行，或用 `chr(96)` / `String.fromCharCode(96)` 拼。
|
||||
- **只改记得的那节**：上一笔只改 §2 与开篇、漏改 §1，用户当场问出「§1 说 16 叶、§2 说剩 3 项，自相矛盾」。改完必须全文通读同一文档所有小节。
|
||||
- **误报跟着改**：「< 40KB」是绘制缓冲红线，与页数无关。
|
||||
- **带日期戳的测量臆改新数**：「2026-10-26 实跑 …覆盖 40 页」改成 47 就是把历史测量冒充现值；只加「当时」。
|
||||
- **用截断的 grep 输出判定**：`cut -c` 截掉的后半句常含日期戳/口径，据此分类必错。
|
||||
- **新写文本撞编号门禁**：新增的「单字母+数字」裸形（如 `SD2506`、`CP56Time2a`）会被 `id-check-new`（只查 `git diff` 新增行、零语料）拦下；旧的八项全库校验 `id-check` 已于 2026-10-28 退役进 `scripts/archive/id_gate/`。撞到就把自己这批文本逐处归因或改形态描述，别去放宽白名单。
|
||||
@@ -0,0 +1,88 @@
|
||||
# Steps（自 SKILL.md 外置）
|
||||
|
||||
> 本文由 stale-doc-count-sweep 的 SKILL.md「Steps」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
|
||||
|
||||
1. **实测真值：先剔伪命中，再双源互证**（不抄用户口述、不抄另一处文档）。逐数走上面那张表；两个来源对不上时**先找分歧根因**（把全部命中逐条打印出来看），不要取第一个、不要取平均，并在结论里写明分歧与取舍（实测：菜单 `#page=` 计数 29 对 注册表 28，根因是头部注释示例行）。
|
||||
|
||||
```bash
|
||||
cd "<repo>"
|
||||
ls simulator/tests/ref/shot_*.bin | wc -l # 张数（判据 = 入库实数）
|
||||
awk '/^PAGES = \[/,/^\]/' simulator/tests/check_content_pages.py | grep -cE '^ *\("' # 页数（第二个来源，两者必须一致）
|
||||
grep -n '#page=' ui_menu_tree.txt | head -3 # 先看首条是不是注释示例行，再定叶数
|
||||
grep -rn 'UI_PAGE_MAP_COUNT' Drivers/BSP/UI/ui_page_registry.h # 已绑叶数（生成物）
|
||||
grep -c '\.bitmap_index' Drivers/BSP/UI/ui_font_cn_12.c # 314 = 含 notdef；字形 = 该数 - 1
|
||||
& '.venv\Scripts\python.exe' -c "import yaml;d=yaml.safe_load(open('.pre-commit-config.yaml',encoding='utf-8'));print(sum(len(r['hooks']) for r in d['repos']))" # 钩子数口径
|
||||
```
|
||||
|
||||
⚠ **权威脚本输出乱码时**（`check_font_charset.py` 在 GBK 代码页下整行打印成 U+FFFD 替换字符串 + `: PASS`，数字全读不出来），**改为直接数源文件里符号出现次数**（`.bitmap_index` / `.range_start` / 码点唯一化）——不许臆读乱码，也不许因此退回去抄文档里的旧数。
|
||||
|
||||
2. **全形态 + 全命中面扫描**。一个数一次列出它全部历史形态，别只扫当前旧值：本轮 = `122/217`、`179/274`、`185/280`、`47 → 53`、`53 → 60`、`PAGES = 53`、`UI_PAGE_MAP_COUNT = 22`、`已绑 22 叶`、`未绑 11`、`内容页 53 页`。
|
||||
|
||||
```bash
|
||||
grep -rn --include=*.md --include=*.py --include=*.yaml --include=*.txt --include=*.c --include=*.h \
|
||||
-E '122 唯一字|217 字形|179 汉字|274 字形|185 唯一字|280 字形|47 → 53|53 → 60|内容页 53|PAGES = 53|UI_PAGE_MAP_COUNT = 22|已绑 22|未绑 11' . \
|
||||
| grep -v -E '^\./(ci-artifacts|\.mnemon|\.dsh/runs)/'
|
||||
```
|
||||
|
||||
**命中面比「文档」宽**，至少包含：`docs/**`、`AGENTS.md`、`.pre-commit-config.yaml`（**钩子 `name:` 显示名内嵌页数**：`name: UI 像素回归（菜单 8 状态 + 内容页 60 页 黄金参考）` 就是命中点）、`scripts/*.py`、`simulator/**/README.md`、以及 **`.dsh/skills/*/SKILL.md`**（本窗 `font-regen` 正文自带 179/274 计数，直到 step 150 才发现；编号门禁退役那轮 `id-family-semantic-migration`、`task-worktree` 两个 skill 正文与 `scripts/README.md` 同样是引用面）。
|
||||
|
||||
先列出 `文件:行:全文`，**判定前必须看整行**——`cut -c1-120` 会截掉后半句（那里常写着日期戳或口径）。
|
||||
|
||||
3. **逐条分类，五类各走各的路**（本 playbook 的核心，别用一条规则套全部命中）：
|
||||
|
||||
| 类别 | 判定 | 动作 |
|
||||
|---|---|---|
|
||||
| 当前态陈述 | 描述「现在是多少」 | 改成实测真值 |
|
||||
| 变更记录历史行 | 形如「47 → 53 页」的当日事实 | **原样冻结不回改**——但这条**只适用于保留变更记录的 5 篇**（台账 / 被别处当唯一证据出处的文档，清单 → `docs/文档规范.md` §5.1）；其余文档的变更记录节已于 2026-10-28 整节删除，**不再追加任何流水行**，数字同步只改**当前态** |
|
||||
| 同数不同义 | `最坏路径 < 40KB` 这类内存/绘制缓冲红线 | **不动**，并在结论里写明「为什么不动」 |
|
||||
| 带日期戳的测量 | 「2026-10-26 实跑 …覆盖当时 40 页中的」 | **不臆改新数**，只补「当时」两字锁口径；新数留待下次实跑回填 |
|
||||
| 数字对但**口径描述错** | 数没错、句子把口径讲错了（实测：写「218 字（含 ASCII/符号，共 313 字形）」，而 `ui_cn_chars.txt` 的 218 个码点**全为非 ASCII**） | **另起一笔只改口径的提交**（`6daa01ae`），不与数字同步混笔；这类命中在任何数字 diff 里都看不见，只能把口径句逐句读一遍 |
|
||||
|
||||
拿不准就回到第 2 步把整行打印出来再判；判错历史行 = 把当天事实改成假账。
|
||||
|
||||
4. **每处先读现文，再逐条字面替换并断言命中数**（弃用整文件正则批处理）。本窗两度返工都是没先读现文：step 45 断言 `HIT 0` 抛错（目标串与现文不一致），step 44 是脚本语法错。脚本写成临时文件再跑（内嵌 heredoc/模板字符串里的反引号会截断整脚本），按**字节**替换以保 BOM 与行尾不动：
|
||||
|
||||
```python
|
||||
import pathlib, sys
|
||||
sys.stdout.reconfigure(encoding='utf-8', errors='replace')
|
||||
JOBS = [ # (文件, old, new, 期望命中数)
|
||||
('AGENTS.md', '内容页 53 页黄金参考', '内容页 60 页黄金参考', 1),
|
||||
('.pre-commit-config.yaml', '内容页 53 页 黄金参考', '内容页 60 页 黄金参考', 1),
|
||||
('docs/架构设计/项目架构总览.md', '122 字/217 字形', '218 字/313 字形', 1),
|
||||
('docs/UI设计/UI_自动化测试流程.md', '文本断言 **310 条**、覆盖 40 页中的', '文本断言 **310 条**、覆盖当时 40 页中的', 1),
|
||||
]
|
||||
for path, old, new, expect in JOBS:
|
||||
p = pathlib.Path(path); raw = p.read_bytes()
|
||||
o, n = old.encode('utf-8'), new.encode('utf-8')
|
||||
got = raw.count(o)
|
||||
assert got == expect, f'{path}: 命中 {got}，期望 {expect}（未写入）'
|
||||
assert o != n, f'{path}: old 与 new 相同'
|
||||
p.write_bytes(raw.replace(o, n))
|
||||
print(f'OK {path}: {old} -> {new} x{got}')
|
||||
```
|
||||
|
||||
每行打印 `old -> new xN`，收口时这串输出就是「改了哪几处」的账。脚本报错/没编译过，**先 `git diff --stat` 确认零写入**再换写法（不要在半落地状态上叠改）。
|
||||
|
||||
- **反引号**：TS 侧先用可见占位符（如 `~TB~`）写文本，落盘前再还原成真反引号 —— `const BT = String.fromCharCode(96); const q = s => s.split(TOKEN).join(BT)`（本窗实测：直接把带反引号的串塞进模板字符串/heredoc，整批零落地或把变更记录行写坏）。用 `tools.edit` 批量改时同样先 `await tools.read` 现文再传 `old_string`；批量里若某条 `old_string` 与 `new_string` 相同会报 `must differ` —— **只有该条作废、其余已落盘**，别整批重跑。
|
||||
- **历史行被写坏**（反引号及紧随其后的字符经工具传递被吞 → 变更记录行只剩半行、尾部出现 `??` 这类残迹）：立刻按**无反引号兜底写法整行重写**——裸词 `accident / oper / alarm / start / yk`、页面绑定写成不带反引号的 `#page=`——而不是拿同样带反引号的串再改一遍（实测连返工三次：step 81→82→83→85）。
|
||||
|
||||
5. **一笔只装一类事**。数字同步一笔（`cbb4fdb8`：11 处 + 变更记录一行）；口径更正另起一笔（`6daa01ae`）；提交后复扫逮到的漏网当前态再补独立一笔（`11d60057`）。钩子一增一减写成一个当日行的两个阶段（51 → 52 加 `id-check-new`、随即 52 → 51 摘 `id-check`），别写两行互相打脸。提交说明如实写（「先认一笔自己的错：上一笔的未绑 21 叶是探针错」），别把口径修正包装成「补充说明」。
|
||||
|
||||
6. **被改文件全文通读，核对其余小节**——不是只看 diff。同一文档内互相引用的小节必须一致（本窗产品需求：§2.4 立项未排、§5.14 FR-SOE-3、§8.2 绑定现状、§8.3 已绑分页表、§9.1 差距表、§9.2 顺序表六处同时引用这四个数；`docs/任务规划/README.md` §1 当前执行表 vs §2 全项目顺序表）。若发现上一笔自己写进文档的数**口径就错了**，明确认错并改正，同时把**可复核的重算方法**写进文档（「按缩进判叶子：有更深缩进后继者即非叶子」），防止再错。
|
||||
|
||||
7. **提交后再复扫一遍**（收尾硬步骤，不许省，也不许只在提交前扫）。按第 2 步的**全部**旧形态整仓再扫一次，逐条分类为 当前态 / 历史行 / 同数不同义：本窗 `cbb4fdb8` 提交后复扫得 14 条命中，12 条以上都在变更记录历史行（`47 → 53`、`53 → 60`、`122/217` 冻结），**唯一残留的当前态命中**是 `docs/架构设计/项目架构总览.md` §3「界面层」那行 → 单独补一笔 `11d60057`。说不出归属的就是漏改。
|
||||
|
||||
```bash
|
||||
grep -rn -E '22 叶|未绑 11|11 叶|53 页|122 唯一字|217 字形|185 唯一字|280 字形|内容页 53|PAGES = 53|UI_PAGE_MAP_COUNT = 22' \
|
||||
. | grep -v -E '^\./(ci-artifacts|\.mnemon|\.dsh/runs)/'
|
||||
```
|
||||
|
||||
8. **跑门禁、分笔提交**（`git commit` 属 Ask first，须用户明确指示后再做）：
|
||||
|
||||
```bash
|
||||
& '.venv\Scripts\python.exe' scripts/check_doc_links.py --all --sections-strict # 期望「文档路径检查通过（N 个文档）」
|
||||
& '.venv\Scripts\python.exe' scripts/check_ids_new.py --self-test # 新增行编号门禁（旧 check_ids.py 已退役进 scripts/archive/id_gate/）
|
||||
& '.venv\Scripts\python.exe' scripts/ci_local.py # 或 pre-commit run --files <被改文件>
|
||||
```
|
||||
|
||||
PowerShell 形态把 `./.venv/Scripts/python.exe` 换成 `& '.venv\Scripts\python.exe'`。提交信息一律 `git commit -F <UTF-8 无 BOM 文件>`，别用 `-m`（中文长标题易超 100 字符、终端代码页会转码）；标题 ≤100、**正文每行 ≤80**（实测把正文压到 66/78 字符才过 gitlint）。
|
||||
@@ -1,14 +1,19 @@
|
||||
---
|
||||
name: task-worktree
|
||||
description: 多任务并行开发的空间管理（git worktree 生命周期）：new 开一棵工作树 + 任务分支、目录联接共享 .venv 与模拟器 SDK、活跃任务硬上限 8 与腾位、build/bench 两类独占锁（含非登记任务占锁后「缺台账」释放不掉的正解）、done 预演合并回主干、门禁未全绿的补基线收尾、并集合并残留审计、**非登记工作树（detached HEAD / 无台账 / 树内有在飞或未跟踪内容）的安全回收**（逐文件内容分桶 + 联接/reparse 预扫 + 唯一残留先备份再 --force + 悬挂台账清理复验），以及**把仓外 detached worktree 当净室测量仪**——门禁指标异常增长时一次只注入一份在飞文件、与基线差分做逐文件归因；**以及与 DSH worktree 插件（`/worktree`、模型工具 `worktree_create`，树在仓内 .dsh-worktrees/）的桥接**——`plugin adopt` 补共享联接、锁归属 `pw:<name>`、回收仍归 /worktree。规格见 docs/环境与部署/并行任务工作树方案.md。
|
||||
whenToUse: 要同时推进多个任务、担心同分支同文档互相冲突；要为新任务开一个隔离空间；要把任务合并回主干；或遇到 `new` 报「已有 8 个活跃任务（上限 8）」、`lock release` 报「任务 X 不存在（缺台账）」、`done` 报「门禁未全绿：工作树与分支保留，未清场」、两个任务抢 COM6 / UV4、"改了文档被覆盖"、并集合并残留时；或**门禁指标异常增长（如 id-check 的不可判定数从 1,162 涨到 1,178、+16）却查不出是哪个文件 / 哪条任务道造成的**、主工作树压着多条在飞改动而不许 stash / 提交 / 改门禁脚本、要按 HEAD 基线只读出像验收时；或**要回收 `@task list` 里根本看不到的工作树**（`git worktree list` 有它、台账没有 / detached HEAD / 树里疑似留着别的会话的在飞或未跟踪内容）、或**要清台账里 branch / path 都已不存在的悬挂条目**（`@task list` 输出发怪、`new` 报「任务已存在」或白占 8 个名额之一）；或**这棵隔离空间是 DSH worktree 插件开的**（会话选了「Worktree模式」/ `/worktree create`，树在仓库内 `.dsh-worktrees/`）——进去发现 `.venv` 不在、`@build` 与门禁全部起跑失败，或想看清谁在占 UV4 / 台架 → F 节。
|
||||
description: >-
|
||||
多任务并行开发的空间管理（git worktree 生命周期）：`@task new` 开工作树+任务分支、目录联接共享 .venv 与模拟器 SDK、活跃上限 8 与腾位（A 节）、build/bench 两类独占锁与非登记持有者「缺台账」释放不掉（B 节）、`done` 是合并点不是查看器（C 节）、主工作树被别的并发会话弄脏时的手工合并路径（C2 节，详情已外置）、门禁指标异常增长时用净室工作树逐文件归因（D 节，外置）、回收 `@task list` 看不到的工作树并清悬挂台账（E 节，外置）、与 DSH worktree 插件 `/worktree`、`worktree_create` 共存（F 节，外置）、任务树内跑门禁与 `simulator/SDL2` 联接假红、树内提交/合并信息的禁词自检（G 节，外置）、插件树两条共享联接的分级（`simulator/SDL2` 是硬需求、`.venv` 有解释器逃生门，F 节，外置）、并行上限数字的唯一事实源（`MAX_CONCURRENT`）。规格见 docs/环境与部署/并行任务工作树方案.md；标「外置」的深规程全文在本技能目录 reference/ 下，动手前先读对应那篇。
|
||||
whenToUse: >-
|
||||
要同时推进多个任务、担心同分支同文档互相冲突；要为新任务开隔离空间；要把任务合并回主干；或遇到 `new` 报「已有 8 个活跃任务（上限 8）」、`lock release` 报「任务 X 不存在（缺台账）」、`done` 报「门禁未全绿」或「主工作树不干净」而那份未提交改动是别的会话/插件留下的、两个任务抢 COM6 / UV4、"改了文档被覆盖"、并集合并残留；或要在任务树里跑文档/审计门禁（往 `ci-artifacts/` 写输出报 ENOENT、`--all` 的问题全在 `simulator/SDL2` 联接下）；或门禁指标异常增长（如不可判定数 +16）却查不出是哪个文件造成的；或要回收 `@task list` 里根本看不到的工作树、清台账里 branch/path 都已不存在的悬挂条目；或任务是在任务树里改文档再合主干、要写提交/合并信息（被清退的主题不得在消息里复现）；或想确认插件工作树里 `.venv` 与 `simulator/SDL2` 到底哪个必须补；或要改并行上限这个数字并同步全仓口径。
|
||||
---
|
||||
|
||||
# task-worktree — 多任务并行开发空间（短命令 `@task`）
|
||||
|
||||
**执行体 = 本 skill 自带脚本** `.dsh/skills/task-worktree/scripts/task_worktree.py`
|
||||
（纯标准库，任意 python3；拷整个 skill 目录到别的项目即可用）。
|
||||
|
||||
**本文档受 dsh-mnemon 写侧上限 65536 字节约束**（实测 2026-10-29：正文涨到 72,601 字节后，技能自进化每次「生成草案」都被写侧拒绝、
|
||||
那一行永久卡在「生成中」）。所以**新增的深规程写进 reference/<篇名>.md**，本文只留可执行判据的摘要 + 指针；瘦身前的 frontmatter
|
||||
原文逐字留在 [reference/frontmatter-history.md](reference/frontmatter-history.md)。**动手做某条深规程前，先把对应那篇 reference 读完**（摘要只用来判定要不要读）。
|
||||
|
||||
@T3@powershell
|
||||
# cwd = 仓库根（或任意子目录）
|
||||
& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" <子命令> [参数]
|
||||
@@ -32,9 +37,9 @@ PY=".venv/Scripts/python.exe"; TW=".dsh/skills/task-worktree/scripts/task_worktr
|
||||
| `list` | 所有任务一览：分支 / 落后领先 / 脏文件数 / 台架状态 + 两个锁的归属 |
|
||||
| `status <ID>` | 单任务详情（未提交清单、相对基线漂移、台架记录、已建联接） |
|
||||
| `sync <ID>` | 在任务工作树里 `rebase` 追平主干，把冲突控制在任务分支上 |
|
||||
| `lock acquire|release|status <build|bench>` | 独占资源锁 |
|
||||
| `plugin list|adopt|unadopt [插件树名]` | 与 DSH worktree 插件的桥：看清单 / 补共享联接 / 摘联接（**不删树**）→ F 节 |
|
||||
| `done <ID>` | 预演 → 合入主干 → 并集残留审计 → 重生成产物 → 门禁 → 清场 |
|
||||
| `lock acquire\|release\|status <build\|bench>` | 独占资源锁 |
|
||||
| `plugin list\|adopt\|unadopt [插件树名]` | 与 DSH worktree 插件的桥：看清单 / 补共享联接 / 摘联接（**不删树**）→ F 节 |
|
||||
| `done <ID>` | 预演 → 合入主干 → 并集残留审计 → 重生成产物 → 门禁 → 清场（主树被别的会话弄脏时改走 **C2** 手工合并） |
|
||||
| `abort <ID>` | 放弃任务（工作树 + 分支一起删，**永久丢弃**） |
|
||||
|
||||
`new` 常用开关：`--base <分支>`（默认 `v2-on-ui`）· `--needs-bench`（无台架 PASS 则 `done` 拒合）·
|
||||
@@ -76,7 +81,7 @@ PY=".venv/Scripts/python.exe"; TW=".dsh/skills/task-worktree/scripts/task_worktr
|
||||
`conflict` 字样的片段 → 据此误判「有冲突」。实测：`tail -2` 误读成 conflict，放宽到 `tail -10` 才看到
|
||||
`[ok] 无冲突，预演结果树 <sha>`。dry-run 全文只有 5~8 行，直接读全量。
|
||||
|
||||
## 分步操作（六条运行时机制）
|
||||
## 分步操作（八条运行时机制）
|
||||
|
||||
### A. `new` 被拒「已有 8 个活跃任务（上限 8）」——怎么腾位
|
||||
|
||||
@@ -158,323 +163,56 @@ git commit -F <UTF-8 无 BOM 的正文文件> # 提交属 Ask first（AGENTS.m
|
||||
7. 清场完成后再敲一次 `done <ID>` 会得到 `前置/环境错误：任务 <ID> 不存在（缺台账 …json）`（exit 2）——
|
||||
**这不是失败**：清场的最后一步 unlink 了台账。判完成以 `git log` 为准。
|
||||
|
||||
### C2. `done` 被「主工作树不干净」挡住，而那份脏改动是**别的并发会话**留下的
|
||||
|
||||
- **不许**对那份外部脏改动做 stash / checkout / reset / 提交 / 删除（项目级 Never，你也不知道它写没写完）；
|
||||
`done` 的前置要求主工作树干净，于是**合并与回收一起被挡**——这是挡给你看的保护，不是工具坏了。
|
||||
- **正解链（六步）**：取证（mtime + diff 定性有无交集，顺手 `worktree list` 看有没有别人中途新建的树）→
|
||||
`git merge-tree --write-tree <base> <task 分支>` 预演（判据：打出结果树 sha 且 RC=0）→ 主树
|
||||
`git merge --no-ff --no-edit -F ci-artifacts/merge-msg-<slug>.txt <task 分支>` → 合并后把
|
||||
`git hash-object <外部文件>` 与 `git diff --stat` 和**合并前存下的值逐项对账**（实测同为 `369380ca…`、2+/2−
|
||||
→ 证明 pre-commit 自己的 stash 往返没动别人的工作）→ 台账先 `cp` 成 `<ID>.json.state-bak` 再让 `done`（或 E 节
|
||||
手工路径）自己摘 .venv / simulator/SDL2 联接拆树 → `worktree list` + `lock status` 复验收工。
|
||||
- **报告里要写明绕开 `done` 的理由并逐项补回它的证据**：预演 sha + RC=0、blob id 对账、合并后在
|
||||
**主树**跑全库 `check_doc_links.py --all`（见 G 节）、两把锁空闲；并且点名那份外部脏文件与中途冒出来的第二棵树
|
||||
（谁的、怎么定性、你没动它的证据）。**blob id 变了 = stash pop 半冲突**：立刻停止收工，两份 blob id 与两份 diff
|
||||
交给该文件属主，绝不 `checkout` 抹平。
|
||||
- **认得出它**：本仓这份外部脏改动两次都是 `.dsh/skills/serial-boot-test/scripts/run_boot_test.py`（2+/2−，别的会话/插件正在写它）——别把它当成自己漏提交的文件去提交或清掉。同一次窗口里 `git -C "$MAIN" worktree list` 还会冒出**别人中途新建的第二棵树**（实测 `data-trust-restructure`），那是并发会话的硬证据：点名写进报告，并且不是你的树就别顺手回收（→ E 节）。
|
||||
- **合并信息也过 G 节的禁词自检**：清退/删主题类任务，`merge:` 那行与正文里被清退主题的关键词计数必须是 0。
|
||||
|
||||
> 详情已外置（本文件须留头量给自进化：dsh-mnemon 写侧上限 65536 字节，超限的技能再也生不成草案）。全文见 [reference/merge-dirty-main-tree.md](reference/merge-dirty-main-tree.md) —— 主树被别的并发会话弄脏时的手工合并路径（取证 → `merge-tree` 预演 → 主树 `merge --no-ff -F` → 外部改动 blob id / `diff --stat` 前后对账）。
|
||||
|
||||
### D. 门禁指标异常增长 → 逐文件归因（把净室工作树当**测量仪**，主树全程只读）
|
||||
|
||||
**场景**（2026-10-27 实测）：`id-check` 突然 FAIL「不可判定 1,178 > 上限 1,166」——比上一轮量到的 1,162 又涨了 **+16**，
|
||||
而主工作树里同时压着 4 条在飞任务道的未提交改动。**不许 stash / checkout / reset**（那是搬动甚至丢弃别人未提交的工作，
|
||||
项目级 Never；`git status` 一乱，整条道的现场就没了），**不许改门禁脚本本身**（它就是那把尺子，改了数字就不可信），
|
||||
**也别在脏主树里跑门禁**（那测的是 4 条道 + 未跟踪文件的混合体，永远分不出谁）。正解：**在仓库之外另起一棵
|
||||
detached HEAD 的干净工作树当净室，一次只往里注入一份在飞文件**，与基线差分即得每个文件的独立贡献。两步：
|
||||
**净室建树 → 单文件注入测量**。
|
||||
|
||||
1. **建净室 + 先落基线数**（路径必须**在仓库目录之外**；铁律 7 对临时树同样成立——放仓内就污染 `git status` /
|
||||
`pre-commit --all-files` / 全库搜索）：
|
||||
|
||||
@T3@bash
|
||||
MAIN="D:/Code/DTU Code/STM32F4-Base" # 主工作树绝对路径（含空格 → 变量整体加引号）
|
||||
WT="$MAIN/../_wt/und-attr" # 仓外同级 _wt/ 下；一次测量固定用同一个名字
|
||||
rm -rf "$WT" 2>/dev/null
|
||||
git -C "$MAIN" worktree add --detach "$WT" HEAD >/dev/null 2>&1 || { echo WT_FAIL; exit 9; }
|
||||
git -C "$WT" status --porcelain # 应为空
|
||||
"$PY" "$WT/scripts/archive/id_gate/check_ids.py" 2>&1 | tail -25 # ← 口径：id-check 钩子已于 2026-10-28 退役（脚本移入 scripts/archive/id_gate/），按该脚本自身默认参数跑；基线与注入用**同一条命令**
|
||||
@T3@
|
||||
|
||||
- `--detach`（**不要 `-b`**）：净室没有分支、不写 `_wt/.state/<ID>.json` 台账 → **不占 `MAX_CONCURRENT = 8`
|
||||
名额、不出现在 `$TW list`**，也没人会被误指去对它跑 `done`（建与拆都不走 `$TW new` / `$TW done`）。
|
||||
- 能这么量的前提：该门禁**只读仓库内文本**。依赖本树构建产物的门禁（`mem-numbers` / `mem-budget` 要 `.map`）
|
||||
在净室里必然报「找不到 .map 事实源」（见陷阱「新建工作树从未构建过」）——**那类指标不能这么归因**。
|
||||
- `git status --porcelain` 非空 = 有别人的未跟踪文件被带进净室 → 先 `git clean -xdn` **干扫**（别去 `n`）
|
||||
看清会删什么，只挪走多出来的那些再测；语料被污染出来的数字与 CI 不可比。
|
||||
2. **一次只注入一份在飞文件 → 跑同一个扫描器 → 与基线差分**（得到的是每个文件的**独立**贡献，不是合计）：
|
||||
|
||||
@T3@bash
|
||||
for f in "App/log/sys_log_mcu.c" "test/host/sys_log_mcu/sys_log_mcu_test.c" "docs/子系统设计/运行与自检记录设计说明.md"; do
|
||||
mkdir -p "$WT/$(dirname "$f")"
|
||||
cp "$MAIN/$f" "$WT/$f" # 拷进净室；主树那份只读、一字节不动
|
||||
echo "== $f =="; "$PY" "$WT/scripts/archive/id_gate/check_ids.py" 2>&1 | tail -25 # ← 与第 1 步同一条命令
|
||||
git -C "$WT" checkout -- "$f" # 只还原净室里自己刚拷进来的那份
|
||||
done
|
||||
@T3@
|
||||
|
||||
实测：`run_par.c` / `board_ui_nav.py` / `check_nested_comment.py` / keil `SKILL.md` **各 +0**，
|
||||
而 log 道那三个文件 **+6 / +8 / +2**，合计**正好 +16**。**Σ(逐文件增量) ≠ 观察到的涨幅 → 还有没被注入的
|
||||
在飞文件，或存在文件间交互项**，不许就此交卷。
|
||||
3. **定性增量是哪一类字面量**（只有「谁」没有「为什么」= 给不出可执行的改法）：同一计数器在 **HEAD 版**与
|
||||
**在飞版**各数一遍，**差值才是新增行带来的**（存量的不算这条道的账）；再对新增行直接 grep。本次 16 处全是
|
||||
**裸形 「字母 T 累进数字 4」**（`T` 在 `scripts/archive/id_gate/id_registry.json` 的 `bare_check_letters` 里，规范形态是连字符形），
|
||||
全部落进 `skip_bare_unmanaged` —— 到这一步结论才配发给属主。
|
||||
4. **闭合 + 复验主树一个字节没被污染**：
|
||||
|
||||
@T3@bash
|
||||
git -C "$MAIN" worktree remove --force "$WT" # 净室里只有自己的拷贝、没有原件，--force 安全
|
||||
git -C "$MAIN" worktree list # 不该再有 und-attr
|
||||
git -C "$MAIN" status --porcelain | sort # 与测量前**逐行一致**（测量前先存一份基线清单）
|
||||
@T3@
|
||||
|
||||
⚠ **上面第一行的前提是有条件的**：树里混进了别人的在飞 / 未跟踪内容时「只有自己的拷贝」就不成立了，
|
||||
`--force` 直接拆等于替别人把唯一版本删掉 → 先走 **E 节**（全景 → 逐文件分桶 → 联接预扫 → 唯一残留先备份），
|
||||
再回来执行本步；复验按 **E 第 5 步**做（拆前/拆后主树 `status --porcelain -uall` 行数必须相同）。
|
||||
**同一棵净室树的第二种用法**：按指定 commit **只读**构建出像 / 烧录验收——不搬动任何在飞改动，也不为台架
|
||||
提前抢发一笔提交；构建与烧录都在这棵树里做（不在主树），仍受 `bench` / `build` 锁串行（铁律 3）。
|
||||
> 详情已外置（本文件须留头量给自进化：dsh-mnemon 写侧上限 65536 字节，超限的技能再也生不成草案）。全文见 [reference/clean-room-measure.md](reference/clean-room-measure.md) —— 把仓外 detached 工作树当净室测量仪：一次只注入一份在飞文件、与 HEAD 基线差分做逐文件归因、主树全程只读。
|
||||
|
||||
### E. 回收**非登记**工作树（`$TW list` 为空 / detached HEAD / 树里有在飞或未跟踪内容）
|
||||
|
||||
**这类树的判定特征**（命中任意一条就适用本节）：`git worktree list` 里有它、但 `_wt/.state/<ID>.json` 台账不存在；
|
||||
HEAD 是 detached（`git rev-parse --abbrev-ref HEAD` 打 `HEAD`）；或树里的改动不属于本会话（别的会话留下的未提交 /
|
||||
未跟踪文件）。典型来源：D 节的 `--detach` 净室、`new` 之后被手工删目录只剩台账的残骸、别人手工 `git worktree add` 建的分析树
|
||||
（2026-10-28 实测一次回收 3 棵：`verify-task16` / `verify-batch` / `und-attr`，各 89 MB，全部无台账 + detached）。
|
||||
|
||||
**为什么 `done` / `abort` 在这里整体不适用**（铁律 9）：两条子命令的前置都是 `load_state()`，无台账 →
|
||||
`前置/环境错误：任务 <ID> 不存在（缺台账 …json）`（exit 2）当场停住、什么也不会发生；而**假如有**一份残留台账，
|
||||
`abort --force` 会拿台账的 `path` 直接 `git worktree remove` —— **绕过下面第 1~4 步的全部内容保全**，把别的会话的唯一版本一次删光；
|
||||
`done` 则会去找那条（多半已不存在的）`task/` 分支做合并。另：本路径没有「合并」这一步，所以 `done` 的并集合并残留审计
|
||||
在这里不发生，也没有三方对比可依据 —— **唯一性只由第 2 步的内容分桶给出**。回收只能手工走本节第 1~5 步 + 第 6 步清台账。
|
||||
|
||||
1. **建全景（全程只读）**：先看 `git worktree list` 的全集，再**逐棵**记三件事（脏行数含未跟踪 / 树顶提交 / 有无分支）
|
||||
加一条台账判定，同时存下主树的拆前基线清单：
|
||||
|
||||
@T3@bash
|
||||
MAIN="D:/Code/DTU Code/STM32F4-Base"; WTROOT="$MAIN/../_wt"
|
||||
git -c core.quotePath=false worktree list # 全集：登记树 + 非登记树都在这份里
|
||||
MAIN_SHA=$(git -C "$MAIN" rev-parse --short HEAD) # 下面所有比对都以这一版为主线尺子
|
||||
mkdir -p ci-artifacts
|
||||
git -C "$MAIN" status --porcelain -uall > ci-artifacts/wt-main-before.txt # 拆前主树基线（第 5 步逐行比）
|
||||
wc -l < ci-artifacts/wt-main-before.txt # 记下行数（实测 0）
|
||||
for t in "$WTROOT"/*/; do
|
||||
echo "--- $t"
|
||||
git -c core.quotePath=false -C "$t" status --porcelain -uall | wc -l # 脏 + 未跟踪行数
|
||||
git -c core.quotePath=false -C "$t" log --oneline -1 # 树顶提交
|
||||
git -C "$t" rev-parse --abbrev-ref HEAD # 打 HEAD = detached，压根没分支可 done
|
||||
ls "$WTROOT/.state/$(basename "$t").json" 2>/dev/null || echo "NO-LEDGER" # 台账位置随 DTU_WT_ROOT
|
||||
done
|
||||
@T3@
|
||||
|
||||
- **`-uall` 不是可选**：默认 `status --porcelain` 会把未跟踪目录折叠成一行 `dir/`，`-uall` 才展开到文件级；少了它
|
||||
第 2 步的分桶就漏项（实测 `und-attr` 唯一那份就是未跟踪 `?? scripts/check_nested_comment.py`）。
|
||||
- 路径含空格（本项目 `DTU Code`）→ 变量整体加引号；`core.quotePath=false` 让中文路径原样输出，便于逐行核对。
|
||||
- 判定「是不是登记树」看两样：**台账在不在 + HEAD 是否 detached**。两者都指「非登记」→ 从这里开始**禁止**
|
||||
`done` / `abort`（见本节开头），继续第 2 步。
|
||||
2. **逐文件与主线 HEAD 比内容并分三桶**：`IN-MAINLINE`（内容等价，拆 = 零损失）/ `UNIQUE-UNMERGED`（主线没有这份
|
||||
内容，拆 = 丢）/ `OLDER-DRAFT`（同路径主线已有更新版本）。落成独立只读探针跑（别用 heredoc 现写现改，
|
||||
见陷阱「别用 heredoc 打补丁造探针」）：
|
||||
|
||||
@T3@python
|
||||
# ci-artifacts/wt_bucket_scan.py — 只读：逐文件与主线工作区/HEAD 比对，三桶归类
|
||||
import os, subprocess, tempfile
|
||||
MAIN = r"D:\Code\DTU Code\STM32F4-Base"
|
||||
WTROOT = os.path.join(os.path.dirname(MAIN), "_wt")
|
||||
TREES = ["verify-task16", "verify-batch", "und-attr"] # ← 第 1 步全景里挑出的非登记树
|
||||
SKIP_TOP = {".venv", "MDK-ARM", ".git", "ci-artifacts"} # 联接 / 构建产物 / 忽略区，按项目调
|
||||
def git(*a):
|
||||
return subprocess.run(("git", "-c", "core.quotePath=false", "-C", MAIN) + a,
|
||||
capture_output=True, text=True, errors="replace")
|
||||
def bucket(rel, tree):
|
||||
p = os.path.join(tree, rel)
|
||||
if not os.path.exists(p):
|
||||
return "OTHER", "工作树里已不存在（多为已 staged 删除）"
|
||||
tf = tempfile.NamedTemporaryFile(delete=False)
|
||||
tf.write(open(p, "rb").read()); tf.close()
|
||||
# 1) 与主线工作区（= 当前 HEAD 的检出内容）逐字节比
|
||||
if git("diff", "--no-index", "--quiet", tf.name, rel).returncode == 0:
|
||||
os.unlink(tf.name); return "IN-MAINLINE", "与主线 HEAD 逐字节相同"
|
||||
# 2) 与主线历史各版比：内容等价于某个旧 commit → 只是主线又往前走了
|
||||
hist = [x.strip() for x in git("log", "--format=%H", "HEAD", "--", rel).stdout.splitlines()]
|
||||
for sha in hist[1:]:
|
||||
old = git("show", f"{sha}:{rel}")
|
||||
if old.returncode == 0 and old.stdout == open(p, encoding="utf-8", errors="replace").read():
|
||||
os.unlink(tf.name); return "IN-MAINLINE", f"内容等价于主线历史版 {sha[:8]}"
|
||||
# 3) 主线从没这条路径 → 唯一；否则同路径主线有更新版 → 更旧草稿（再用 blob diff 定性方向）
|
||||
os.unlink(tf.name)
|
||||
if not hist:
|
||||
return "UNIQUE-UNMERGED", "主线 HEAD 与历史都没有此路径"
|
||||
return "OLDER-DRAFT", "同路径主线有更新版本（用 diff --stat <HEAD> -- <f> 定性）"
|
||||
for name in TREES:
|
||||
tree = os.path.join(WTROOT, name)
|
||||
lines = subprocess.run(("git", "-c", "core.quotePath=false", "-C", tree,
|
||||
"status", "--porcelain", "-uall"),
|
||||
capture_output=True, text=True, errors="replace").stdout.splitlines()
|
||||
tally = {}
|
||||
for line in lines:
|
||||
rel = line[3:].split(" -> ")[-1].strip('"') # 兼容 ?? / M / A / R 的箭头形态
|
||||
if rel.split("/")[0] in SKIP_TOP:
|
||||
continue
|
||||
b, why = bucket(rel, tree)
|
||||
tally.setdefault(b, []).append((rel, why))
|
||||
g = lambda k: len(tally.get(k, []))
|
||||
print(f"== {name}: IN-MAINLINE={g('IN-MAINLINE')} UNIQUE-UNMERGED={g('UNIQUE-UNMERGED')} "
|
||||
f"OLDER-DRAFT={g('OLDER-DRAFT')} OTHER={g('OTHER')}")
|
||||
for b in ("UNIQUE-UNMERGED", "OLDER-DRAFT", "OTHER"):
|
||||
for rel, why in tally.get(b, []):
|
||||
print(f" {b}: {rel} # {why}")
|
||||
@T3@
|
||||
|
||||
报告里必须**逐桶给计数 + 判定证据**（实测：`verify-task16` IN-MAINLINE=6 / UNIQUE=0；`verify-batch` IN-MAINLINE=35 /
|
||||
UNIQUE=1；`und-attr` IN-MAINLINE=0 / UNIQUE=1）。两个非空桶再各钉一条命令把证据坐实：
|
||||
|
||||
@T3@bash
|
||||
# 「唯一未合并」是真更新还是更旧草稿？blob 级 diff + 逐行看方向
|
||||
git -c core.quotePath=false -C "$MAIN" diff --stat "$MAIN_SHA" -- simulator/tests/README.md
|
||||
diff <(git -C "$MAIN" show "$MAIN_SHA":simulator/tests/README.md) "$WTROOT/verify-batch/simulator/tests/README.md"
|
||||
# 「树顶提交要不要保」只看一件事：是否已并入 HEAD。别拿「目录很久没动」当判据
|
||||
for c in 77779d49 1d4b6a17; do
|
||||
git -C "$MAIN" merge-base --is-ancestor "$c" HEAD && echo "$c MERGED" || echo "$c NOT-merged"
|
||||
done
|
||||
@T3@
|
||||
|
||||
实测：那份 `simulator/tests/README.md` 树内写「27 页 × 3200 B」、主线 HEAD 已是「60 张 × 3200 B」→ **更旧草稿**（被取代的
|
||||
早先版本），不是未合并成果；`bench-21-77779d49` / `bench-23-1d4b6a17` 两棵 `merge-base --is-ancestor` 判 **MERGED** 且脏数 = 0
|
||||
→ **保留不动**（不属本节，等属主自己收，报告里点名说清为什么留）。
|
||||
**回收判据不是「看着旧」**：唯一内容如果没被提交过，`git log` 里根本看不见它；反过来「提交已 MERGED」也不等于可以拆——
|
||||
还得看未跟踪那一层。`UNIQUE-UNMERGED` 非空又确实要留 → 它进第 4 步的备份，**不许靠 `--force` 顺手带走**。
|
||||
3. **拆前扫联接 / reparse point（物理安全性 = 铁律 5 的可执行判据）**。存成 `ci-artifacts/wt_junction_scan.py` 再跑：
|
||||
|
||||
@T3@python
|
||||
# 只读预扫：一个路径是不是 reparse point（Windows 目录联接在这里现形）；发现即停止深入，绝不 walk 进联接
|
||||
import os, ctypes
|
||||
FILE_ATTRIBUTE_REPARSE_POINT = 0x400
|
||||
GA = ctypes.windll.kernel32.GetFileAttributesW
|
||||
def is_reparse(p):
|
||||
a = GA(p)
|
||||
return a != -1 and bool(a & FILE_ATTRIBUTE_REPARSE_POINT)
|
||||
for name in ["verify-task16", "verify-batch", "und-attr", "bench-21-77779d49", "bench-23-1d4b6a17"]:
|
||||
top = os.path.join(r"D:\Code\DTU Code\_wt", name)
|
||||
hits, entries = [], 0
|
||||
for root, ds, fs in os.walk(top):
|
||||
bad = [d for d in ds if is_reparse(os.path.join(root, d))]
|
||||
if bad:
|
||||
hits += [os.path.join(root, d) + "/" for d in bad]
|
||||
ds[:] = [] # 有联接就不再深入：防转进主树 .venv 把别人整棵树数一遍
|
||||
hits += [os.path.join(root, f) for f in fs if is_reparse(os.path.join(root, f))]
|
||||
entries += len(ds) + len(fs)
|
||||
print(f"== {name} scanned entries={entries}")
|
||||
print(" REPARSE: none → 可直接 git worktree remove --force"
|
||||
if not hits else " REPARSE:\n " + "
|
||||
".join(hits))
|
||||
@T3@
|
||||
|
||||
实测输出 `== verify-task16 ... REPARSE: none`（每棵的体积 / 条目数 + 零联接就是证据），而 `bench-*` 两棵各挂一个 `.venv`
|
||||
联接 → 判 **KEEP**（本节不拆它们；将来真要拆，先 `rmdir` 摘掉联接再 remove）。
|
||||
**判据是「扫出来一个都没有」，不是「我记得没建过联接」**：`new --no-bootstrap` 的树、别的手工 `mklink /J` 的树都可能带着指向主树的联接。
|
||||
摘联接用 `rmdir`（只删联接本身；**不是** `rd /s`，更不是 `rm -rf`——那会顺着联接删目标）。
|
||||
非 Windows 环境改用 `os.path.islink` / `find <tree> -type l`（本项目是 Windows + Keil 工具链，按上面这条走）。
|
||||
**到这里才算「拆前唯一性自检 + 物理安全预扫」齐**：`--force` 的安全前提 = 第 2 步 `UNIQUE-UNMERGED` 为 0
|
||||
（或剩下的已全部进第 4 步备份）**且**这里 `REPARSE: none`。
|
||||
4. **唯一内容先备份，再 `--force` 拆**。`UNIQUE-UNMERGED` 与需要留档的 `OLDER-DRAFT` 一律先备份进主树
|
||||
`ci-artifacts/wt-leftover-backup/`（`ci-artifacts/` 已被 `.gitignore` 忽略 → **备份不会改变主树脏行数**；仓库根不放一次性产物），
|
||||
**文件名 + 字节数必须打进输出**当证据：
|
||||
|
||||
@T3@bash
|
||||
BK="$MAIN/ci-artifacts/wt-leftover-backup"; mkdir -p "$BK"
|
||||
# 命名约定：<树名>__<原路径里的 / 换成 _>，反向可定位；台账备份统一后缀 .state-bak
|
||||
cp "$WTROOT/verify-batch/simulator/tests/README.md" "$BK/verify-batch__simulator_tests_README.md"
|
||||
cp "$WTROOT/und-attr/scripts/check_nested_comment.py" "$BK/und-attr__scripts_check_nested_comment.py"
|
||||
ls -l "$BK" # 实测：verify-batch__simulator_tests_README.md 1769 bytes / und-attr__scripts_check_nested_comment.py 14827 bytes
|
||||
for t in verify-task16 verify-batch und-attr; do
|
||||
git -C "$MAIN" worktree remove --force "$WTROOT/$t"; echo "$t remove_rc=$?" # 不接管道才读得到码（见「读输出」）
|
||||
done
|
||||
git -C "$MAIN" worktree prune # 顺带清 .git/worktrees 里的残籍
|
||||
@T3@
|
||||
|
||||
自检：**备份条目数 = 第 2 步里判「要留档」的条目数**，且每个都带字节数。这一步就是本节相对 D 第 4 步的增量——
|
||||
D 的前提是「净室里只有自己的拷贝」，本节的树里混着别人在飞的东西，`--force` 是一次不可逆删除，**先备份才谈得上安全**。
|
||||
5. **复验：主树一个字节没动 + 树确实没了**：
|
||||
|
||||
@T3@bash
|
||||
git -C "$MAIN" status --porcelain -uall > ci-artifacts/wt-main-after.txt
|
||||
wc -l < ci-artifacts/wt-main-before.txt; wc -l < ci-artifacts/wt-main-after.txt # 两个数必须相同（实测 0 → 0）
|
||||
diff ci-artifacts/wt-main-before.txt ci-artifacts/wt-main-after.txt # 空输出 = 逐行一致
|
||||
git -c core.quotePath=false -C "$MAIN" worktree list # 已拆路径逐条消失；主树与判「保留」的树原样在列
|
||||
@T3@
|
||||
|
||||
行数不同 = 备份或摘除碰到了主线（多半是备份写进了未被忽略的目录，或漏摘联接）→ 立刻定位，别报「回收完成」。
|
||||
第 2 步判「保留不动」的树还在 `worktree list` 里是**预期结果**，在报告里点名解释为什么留（附 `MERGED` 判据）。
|
||||
6. **顺手清悬挂台账**（branch / path 都已不存在的 `_wt/.state/<ID>.json`；它会让 `$TW list` 打出一行怪条目、并让下次
|
||||
`new` 同 ID 报「任务 <ID> 已存在」）。先给证据、后动手：
|
||||
|
||||
@T3@bash
|
||||
for j in "$WTROOT"/.state/*.json; do # 台账位置随 DTU_WT_ROOT
|
||||
id=$(basename "$j" .json)
|
||||
br=$("$PY" -c "import json,sys;print(json.load(open(sys.argv[1],encoding='utf-8')).get('branch',''))" "$j")
|
||||
pp=$("$PY" -c "import json,sys;print(json.load(open(sys.argv[1],encoding='utf-8')).get('path',''))" "$j")
|
||||
git -C "$MAIN" rev-parse --verify "$br" >/dev/null 2>&1 && b=branch-OK || b=branch-MISSING
|
||||
[ -d "$pp" ] && p=path-OK || p=path-MISSING
|
||||
echo "$id $b $p <- $j"
|
||||
done
|
||||
@T3@
|
||||
|
||||
实测这条判据打出的正是 `v5tool2 branch-MISSING path-MISSING`：`git rev-parse task/v5tool2-v11` 报
|
||||
`fatal: ambiguous argument 'task/v5tool2-v11': unknown revision ...`，台账 `path` 指的目录已无，`git worktree list` 里也没有这棵树。
|
||||
**三条齐（rev-parse fatal + path 目录不存在 + worktree list 无此树）才叫悬挂**；缺任何一条都回到第 1~2 步查是不是真有东西要保。
|
||||
然后**备份 → 删 → 复跑两条 list 复验**：
|
||||
|
||||
@T3@bash
|
||||
cp "$WTROOT/.state/v5tool2.json" "$BK/v5tool2.json.state-bak" && rm "$WTROOT/.state/v5tool2.json"
|
||||
"$PY" "$TW" list # 该条目消失（全空时打「（没有任务空间。用 new <ID> <slug> 建一个）」），echo RC=$? 应为 0
|
||||
"$PY" "$TW" lock status # build 空闲（TTL 1.0h）/ bench 空闲（TTL 6.0h）—— 证明清台账没牵连两把锁
|
||||
ls "$WTROOT"/.state/locks/ 2>/dev/null # 若该 ID 名下还有 .lock，先按 B 节释放，再删台账
|
||||
@T3@
|
||||
|
||||
- **必须 `cp` 先备份再 `rm`**：台账里存着 base / junctions / needs_bench / bench_pass，是真出纠纷时唯一的现场记录。
|
||||
- 悬挂条目按定义 `path` 已不存在 → 通常**不占** `MAX_CONCURRENT = 8` 名额（A 第 1 步的「活跃」判据要求 path 目录还在），
|
||||
但它把 `$TW list` 搅成怪输出、并永久挡住同 ID 复用；**path 还在的占位/残留台账才占名额**（早期为绕 B 节那个坑手写的占位台账就是这种）。两种都要清。
|
||||
- **仍不对这个 ID 跑 `done` / `abort`**：清场会拿台账里的死 `path` / 死 `branch` 去做 `git worktree remove` 和删分支
|
||||
（这正是 A 第 5 步说的「手工删目录留下的尾巴」，正解就是本步）。历史遗留的占位台账同理——活着时也别
|
||||
`done` / `abort`，用完直接删文件（来历与现状见 B 末条）。
|
||||
> 详情已外置（本文件须留头量给自进化：dsh-mnemon 写侧上限 65536 字节，超限的技能再也生不成草案）。全文见 [reference/reclaim-unregistered.md](reference/reclaim-unregistered.md) —— 回收 `@task list` 看不到的工作树：逐文件内容三桶归类、reparse/联接只读预扫、唯一残留先备份再 `--force`、悬挂台账清理复验。
|
||||
|
||||
### F. 与 DSH worktree 插件（`/worktree`、模型工具 `worktree_create`）共存
|
||||
|
||||
本仓现在有**两套**隔离空间。别混用，也别互相回收：
|
||||
- **两条共享联接不同级**（别答成「两个都必须」）：`simulator/SDL2` = **硬需求**——`simulator/CMakeLists.txt:12` 是普通 `set(SDL2_DIR "${CMAKE_CURRENT_SOURCE_DIR}/SDL2/SDL2-2.32.10")` 而**非 `CACHE`**，既没有环境变量也没有 `-DSDL2_DIR=` 逃生门，include / `lib/x64` / `SDL2.dll` 三条路径全从它派生（`:34` `:70` `:71` `:180` `:207`）→ 缺它 `build_sim.bat` 当场失败。`.venv` = **软需求**——`scripts/ci_local.py` 有 `DTU_PRECOMMIT_PYTHON` 显式逃生门 + 五级解释器候选（显式 var → `sys.executable` → 仓库 `.venv` → `which python` → 机器级常见位置），绕开联接只是**静默**落到机器级解释器（缺 fontTools → `generated-fresh` 假红）。`plugin adopt` 两条都补是因为便宜，不是两条都硬。
|
||||
- **「有插件了为什么还自持 Python 生命周期」别凭印象答**：先实读插件包（`npm root -g` → `node_modules/@deepseek-ai/dsh/` 下定位插件、读 `package.json` 记版本），再 grep 三个概念名并报命中数——独占锁 `lock`、共享目录联接（`.venv` / `simulator`-SDL2）、联接状态三态显示；插件侧零命中就是自持的理由。重叠面只有开/收两个动作（两侧底层都是 `git worktree add`，没重造「建树」）；锁、联接、台账与 `done` 的「预演 → 合并 → 审计 → 门禁 → 清场」编排才是插件没有的东西（本仓资源各只有一份：一块 ST-LINK、一套 Keil 授权、一个 COM6，SDL2 又无逃生门 → 必须串行 + 必须共享）。
|
||||
|
||||
| | `@task`（本 skill） | DSH worktree 插件（`dsh-task-worktree`） |
|
||||
|---|---|---|
|
||||
| 树在哪 | 仓库**外** `../_wt/<ID>-<slug>/` | 仓库**内** `.dsh-worktrees/worktree/<name>/` |
|
||||
| 谁建 | `new <ID> <slug>`（人来敲命令） | 会话选「Worktree模式」/ 模型调 `worktree_create`（零命令） |
|
||||
| 台账 | `_wt/.state/<ID>.json`（本 skill） | `.dsh-worktrees/manifest.json`（插件私有格式，别去改） |
|
||||
| 分支名 | `task/<ID>-<slug>` | `worktree/<name>` |
|
||||
| 共享联接 | `new` 自动建 | **建树时没有** → 要 `plugin adopt` 补 |
|
||||
| 回收 | `done`（预演 / 合并 / 门禁 / 清场）或 `abort` | 用户敲 `/worktree finish\|bring-back\|remove\|prune`（模型碰不到收尾命令） |
|
||||
> 详情已外置（本文件须留头量给自进化：dsh-mnemon 写侧上限 65536 字节，超限的技能再也生不成草案）。全文见 [reference/dsh-plugin-bridge.md](reference/dsh-plugin-bridge.md) —— 与 DSH worktree 插件（`/worktree`、`worktree_create`）共存：`plugin adopt` 补共享联接（两条联接的分级：SDL2 硬 / `.venv` 软）、锁归属 `pw:<name>`、回收仍归 /worktree、以及「为什么不用插件而自持生命周期」的取证姿势（F-2）。
|
||||
|
||||
**为什么允许它把树建在仓内**（铁律 7 的唯一例外）：路径写死在插件里（`WORKTREE_NAMESPACE = worktree`
|
||||
+ `<repo>/.dsh-worktrees/`），而暴露给模型的工具只有 `worktree_create` / `worktree_list` /
|
||||
`worktree_status` 三个，配置面改不动。兜法三件（均已落地）：
|
||||
### G. 任务树内跑门禁与审计：输出落点（ci-artifacts）与 SDL2 联接假红
|
||||
|
||||
1. `.gitignore` **预置** `.dsh-worktrees/` —— 插件首次 `create` 会往 `.gitignore` 追加一模一样的字面量，
|
||||
`ensureIgnored()` 见到同名规则即跳过；不预置就等于让插件在会话中途改这份受控文件（diff 里冒出
|
||||
一行"不是我加的"）。
|
||||
2. 全库扫描的排除面登记了它：`scripts/check_doc_links.py` 的 `SKIP_PARTS`、
|
||||
`tools/refgraph/gen_refgraph.py` 的 `EXCLUDE_DIRNAMES`、`scripts/check_layer_deps.py` 的 `os.walk` 兜底。
|
||||
一份仓库副本被全库扫描吞进去 = 文档链接假红 + 配图生成物逐字节漂移砸在某位同事头上。
|
||||
3. 联接与锁归属由本节命令接上（下面三步）。
|
||||
- **新建的任务树里没有 `ci-artifacts/`**（被 `.gitignore` 忽略 → 不会被检出）：重定向输出或
|
||||
`fs.writeFileSync` 直接 `ENOENT`，**整段程序零执行**。落盘前先单独一条 `mkdir -p ci-artifacts`；树内输出
|
||||
一律用树内相对路径（`cd` 进树后 `../_wt/x.txt` 会落到 `_wt/_wt/`，实测就是这句报错）。
|
||||
- **文档门禁在树内按单文件跑，全库 `--all` 基线留到合并后在主树跑**：树内的 `simulator/SDL2` 是指向
|
||||
主树同一份的目录联接，`--all` 会把这份「第二份仓库副本」一起扫：实测树内打 222 个文档 / 35 处问题、RC=1
|
||||
而 **35 处全在联接下**、要改的文档一条没有 = 假红；合并后主树同一条命令 = 2,597 处 / 194 个文档 / rc=0，
|
||||
这才是有效基线（单文件实测 161 处/98%/rc=0、16 处/88%/rc=0）。
|
||||
- 确要在树内跑 `--all`：判红固定三步——① 主树同命令拿基线 ② 过滤 `simulator/SDL2` 联接下的问题行
|
||||
③ 剩下的逐行比。只做一步（见 RC=1 就报「门禁挂了」/ 过滤后为空就报「全绿」）都是误判。
|
||||
- **跑门禁前先做一次字节体检**（文档改动在树内提交前的固定项）：`lines / bytes / BOM / CR / U+FFFD / 三连续空行 / 行尾空格 / 末行单个 LF` + 自写 Markdown 表格每行列数一致性检查。报出来的坏行**未必是本次改动**（实测 2,665 行的需求文档里两处坏表格与本次编辑无关）——先定位归属再决定动不动手，别顺手改别人的区域。这些面 `doc-links` / `no-mojibake` 只覆盖编码那半，表格断列与多出的空行要自己数。
|
||||
- **提交/合并信息一律 `-F` 读文件**（UTF-8 无 BOM、标题 ≤100 字符、正文每行 ≤80，文件放 `ci-artifacts/`），清退类任务另加一条**禁词自检**：`git log -1 --pretty=%B | grep -c '<被清退主题的关键词>'` 必须是 **0**（标题与正文都不许再出现那个关键词，改用「其它串口通道对照内容」这类语义短语；合并信息同样查一遍）。提交前自查消息里的行数/统计有没有算错；**未推送前**发现错了 → `git commit --amend -F <改好的文件>` 就地修，别追加一笔「更正」提交（那等于把禁词又写回历史）。
|
||||
|
||||
**这棵树是不是插件的**：`git worktree list` 里路径含 `.dsh-worktrees/` 就是。`$TW list` 现在会在台账段
|
||||
下面另起一段列出它们，联接列**点名缺哪一样**（`已联` / `缺 .venv` / `缺 SDL2` / `齐(实体SDL2)`）。**插件树不占
|
||||
`MAX_CONCURRENT = 8` 名额**——回收不归本 skill，
|
||||
硬计入只会让别人那棵关不掉的树把 `new` 挡死（`new` 会打印一行「另有 N 个插件工作树不计入上限」提醒并发代价）。
|
||||
> 详情已外置（本文件须留头量给自进化：dsh-mnemon 写侧上限 65536 字节，超限的技能再也生不成草案）。全文见 [reference/gates-in-tree.md](reference/gates-in-tree.md) —— 任务树内跑门禁与审计：`<tree>/ci-artifacts/` 先 `mkdir -p`、文档链接按单文件在树内跑、全库 `--all` 合并后在主树跑、`simulator/SDL2` 联接假红、提交/合并信息禁词自检、改完文档的字节与表格体检。
|
||||
|
||||
三步接上（`<name>` 可带 `worktree/` 前缀，也可多段如 `refactor/logging`）：
|
||||
|
||||
@T3@bash
|
||||
"$PY" "$TW" plugin list # 一览：分支 / 脏 / 缺哪个联接（缺项另起一行说后果）
|
||||
"$PY" "$TW" plugin adopt N21-dhara-isfree # 只补缺失的 .venv 与 simulator/SDL2 联接
|
||||
"$PY" "$TW" plugin unadopt N21-dhara-isfree # 只摘联接（os.rmdir），绝不动目标内容与树里文件
|
||||
@T3@
|
||||
|
||||
- **两条联接坏了的样子完全不同**：缺 `.venv` → `ci_local.py` 的四级解释器回退**静默**落到机器级
|
||||
python（无 fontTools = `generated-fresh` 假红的老根因，AGENTS.md 记着）；缺 `simulator/SDL2` →
|
||||
`build_sim.bat` 当场报错（`SDL2_DIR` 是裸 `set`，没有 env 逃生口）。所以列表只说「已联」不够——
|
||||
它按缺的那一样分别给后果，`adopt` 没补齐也只报「还不能算就绪」，不许说「现在可以跑」。
|
||||
- **adopt 只碰联接**：已联的跳过；`simulator/SDL2` 若已是实体目录只告警不动；`.dsh-worktrees/` 之外的路径
|
||||
一律 exit 2（实测 `plugin adopt ".."` 被拒）——这道闸防的是把主树或 `_wt` 目录当插件树遮蔽掉真实内容。
|
||||
- **锁归属现在认得出来**：`@build` 在插件树里自持自释时，持有者名从 cwd 反推成 `pw:<name>`（多段名压平成
|
||||
`-`），与 `plugin adopt` 打印的那个名字逐字相同（`keil_build.py: plugin_tree_owner()` ↔
|
||||
`task_worktree.py: plugin_lock_owner()`）→ `lock status` 不再一律落成 `build-cli`。
|
||||
- 上台架仍须手工占锁、用同一个名：`lock acquire bench --task pw:<name> --note <说明>` →
|
||||
`lock release bench --task pw:<name> --bench-pass`。插件树没有台账 → 按 B 节只 warn、锁照常放。
|
||||
- **命名建议**：插件 `<name>` 沿用 `@task` 的 `<ID>-<slug>` 形态（如 `N21-dhara-isfree`），两套视图同名好对账；
|
||||
但分支前缀必然不同（`worktree/` vs `task/`），别把两者说成同一个分支。
|
||||
- **收尾不在这**：`done` / `abort` 拿插件树名下手只会 exit 2（这是保护，别绕过去手工 `git worktree remove`；
|
||||
要拆先 `plugin unadopt` 摘联接，再由**用户** `/worktree remove`）。`/worktree bring-back` 要求主工作树干净，
|
||||
本仓常有在飞改动 → 提交或 stash 由用户定。反过来插件也不会碰 `_wt/`（路径根不同，谁也删不掉谁）。
|
||||
## 铁律
|
||||
|
||||
1. **`done` 只能在主工作树执行**——主干分支检出在主工作树，git 不允许同一分支在两处检出。
|
||||
@@ -492,6 +230,12 @@ ls "$WTROOT"/.state/locks/ 2>/dev/null # 若该 ID 名下还有 .lock，先按
|
||||
把主工作树的 `.venv` 一起删掉。手工拆任何一棵树之前先跑 **E 第 3 步**的预扫，拿到 `REPARSE: none` 才动手。
|
||||
6. **活跃任务硬上限 8**（脚本常量 `MAX_CONCURRENT = 8`，每棵约 83 MB 检出——du 口径，内容字节和 84.0 MiB → `docs/环境与部署/并行任务工作树方案.md` §4）。满了 `new` 直接 exit 2，
|
||||
腾位顺序与 `--force` 的代价 → A 节；悬挂台账的清理与复验 → **E 第 6 步**。
|
||||
**改上限 = 只改 `task_worktree.py` 里那一行常量**（`MAX_CONCURRENT`，:30）：报错文案「已有 N 个活跃任务（上限 8）」
|
||||
与 `new` 打的「另有 N 个 DSH 插件工作树（`.dsh-worktrees/`，不计入上限 8）」提示都是 `.format(…, MAX_CONCURRENT)`
|
||||
插值该常量（实测 `task_worktree.py:764-766` / `:768-771`）——AGENTS.md、方案文档、本技能 frontmatter 与 A 节里的
|
||||
数字**全是引用同步**，不是第二处事实源。全形态扫描（`最多 N` / `N 棵` / `三棵` / `第 N+1 棵` / `白占 N 个名额` /
|
||||
`MAX_CONCURRENT = N` / 硬上限）与「上限真生效」的隔离小仓验证（`REPO_ROOT` 由 `__file__` 反推 → 脚本必须按同一
|
||||
目录深度放，才能测到同级 `_wt/`）→ `stale-doc-count-sweep` skill；每棵树的磁盘代价按实测口径重述，别照抄旧数。
|
||||
7. **`@task` 的工作树放仓库同级 `_wt/`，绝不在仓库内部**——否则污染 `git status`、`pre-commit --all-files`
|
||||
与全库搜索。唯一例外 = DSH worktree 插件写死的仓内 `.dsh-worktrees/`（改不了；已用「预置 .gitignore +
|
||||
三个全库扫描门禁排除」兜住，见 **F 节**）。自己新建的树一律走 `_wt/`。
|
||||
@@ -503,133 +247,11 @@ ls "$WTROOT"/.state/locks/ 2>/dev/null # 若该 ID 名下还有 .lock，先按
|
||||
|
||||
## 陷阱（实测）
|
||||
|
||||
- **`--force` 不是万能钥匙**：它只覆盖四类检查——并发上限、持有者与 `--task` 不符、陈旧锁接管、
|
||||
清场时强制移除工作树。**台账缺失这类前置/环境错误（exit 2）跟它无关**（实测 `lock release
|
||||
--force --bench-pass` 报的是同一句话，锁照旧没放）。同理 `abort --force` 也只覆盖「树里有东西」这一条拒绝，
|
||||
**不会**替你做 E 节的内容保全——它只会删得更快。
|
||||
- **未跟踪文件在 `git log`、提交门禁与 `done` 的合并里都不留痕**（2026-10-29 回收现场）：钩子按 HEAD tree 的
|
||||
diff-index 取文件，未跟踪文件从没进过任何钩子的视野；`git log` 也照不出「唯一未合并」——它压根没被提交过。
|
||||
所以「这棵树没有遗留改动」这种结论**只能**由 E 第 2 步的逐文件内容比对给出，`log --oneline -1` + 脏计数都不够。
|
||||
- **`git status --porcelain` 不带 `-uall` 会折叠未跟踪目录**（E 第 1 步）：「全景」少一项、分桶少一个文件，
|
||||
最后拆掉的是别人唯一的草稿。回收路径上**一律 `-uall`**。
|
||||
- **`$TW list` 空 ≠ 没有工作树**：`list` 只遍历台账（A 第 1 步），用户说的「那 3 棵 done 掉」很可能在 `$TW list` 里
|
||||
一个都不存在（实测就是）→ 别照 `$TW list` 的空结果回「没有任务」，先 `git worktree list` 拿全集再逐棵定性（E 节）。
|
||||
2026-10-29 起 `list` 还会另起一段列出插件树（`.dsh-worktrees/`，F 节）——**"看见"不等于"归 `done` 管"**。
|
||||
- **「这棵树很久没动」不是回收判据**：实测 `bench-*` 两棵既没台账也没脏文件、mtime 很旧，但真正决定去留的是
|
||||
`git merge-base --is-ancestor <c> HEAD` = MERGED（提交已进主线）+ 未跟踪层为空；而另一棵 mtime 更新的树反而
|
||||
全是已在主线的副本。**判据是内容与祖先关系，不是时间戳。**
|
||||
- **「我记得没建过联接」不是安全判据**：判据只有扫出来的 `REPARSE: none`（E 第 3 步实测 `bench-*` 各挂一个 `.venv`
|
||||
联接，正是「不是自己建的」那类）。
|
||||
- **联接不是符号链接**：本仓库 `core.symlinks=false`，git 里的 symlink 会被检出成
|
||||
「内容是目标路径的文本文件」。共享 `.venv` 只能用 Windows **目录联接**（`mklink /J`，
|
||||
不需要管理员权限），且联接必须建在版本控制之外。
|
||||
实测（2026-10-12）：用 ctypes 直调 `DeviceIoControl(FSCTL_SET_REPARSE_POINT)`
|
||||
会被系统拒绝（Win32 4392），`mklink /J` 正常——所以脚本走后者，参数以列表交给
|
||||
subprocess，含空格的路径（本项目 `DTU Code`）由 subprocess 自动加引号。
|
||||
但**读属性**用 ctypes 没问题：`GetFileAttributesW` + `FILE_ATTRIBUTE_REPARSE_POINT` 就是 E 第 3 步的预扫手段。
|
||||
- **联接建失败不中止 `new`**：只告警并打印手工补建命令，避免留下半成品任务空间；
|
||||
但该任务里跑不了 `.venv\Scripts\python.exe`，`@build` / `ci_local.py` 会找不到解释器。
|
||||
- **`done` 前主工作树必须干净**：否则未提交改动会被卷进合并（补完基线再重跑 `done` 时最容易忘，见 C 第 6 步）。
|
||||
- **⚠ `done` 的门禁跑在 `@build` 之前 → 依赖 `.map` 的钩子会误报**（2026-10-12 实测）：
|
||||
`done` 的顺序是「合并 → 重生成 → **门禁（ci_local）** → `@build`」，而
|
||||
`mem-budget`（登记簿条目「缩堆迁 CCM 后半（暂缓）」）/ `mem-numbers` 是拿**文档快照 vs `.map`** 比对 —— 门禁跑时
|
||||
`.map` 还是**主工作树合并前**的旧产物，与刚合并进来的新台账**必然不一致** →
|
||||
误报 `[FAIL] 台账受管区与 .map 不一致`。`@build` 跑完后 `.map` 才是新的。
|
||||
**处置（2026-10-25 补全）**：按 C 节第 5 步的完整链补——`check_mem_numbers.py --write` →
|
||||
`ram_baseline.py --write` → `ram_baseline.py --update` → `check_test_coverage.py --update-baseline` →
|
||||
`check_doc_links.py --all` → 提交 → 重跑 `done`（它会检测到「已合入」直接清场）。
|
||||
此时主干已含合并提交，**绝不能用提示里的 `reset --hard` 回退**。
|
||||
- **`done` 的门禁 = `ci_local.py` = `pre-commit run --all-files`（50 条钩子全跑）**（2026-10-26）：红了先读
|
||||
`[SUMMARY] static: pre-commit hooks -- passed=N failed=M skipped=K`，**按钩子 id 定根因**，别一律当「`.map` 滞后」
|
||||
去跑补基线链。典型例外：`generated-fresh`（生成器幂等性，触发面 `tools/**`、`docs/images/*.svg`、UI 生成文件）——
|
||||
合进来的分支改了生成器却没重跑产物时，补基线链救不了，处置是在**主工作树重跑那个生成器**、脚本与产物同一笔提交，
|
||||
再重跑 `done`。另注意 `pre-commit run --all-files` 只跑 pre-commit stage，个别只在 commit-msg / 手工阶段跑的守卫不在此列
|
||||
（口径见 `scripts/ci_local.py` 头部说明）。
|
||||
- **⚠ 新建工作树从未构建过 → 体积类门禁必然红**（2026-10-25 实测）：`.map` 是每棵树各自的
|
||||
构建产物、不入版本库，所以 `new` 出来的空间里 `mem-numbers` / `mem-budget` / `ci_local.py`
|
||||
的体积门禁步都拿不到事实源，报 `[FAIL] 找不到 .map 事实源`（脚本提示已写明原因，不是代码缺陷）。
|
||||
同理 `done` 的重生成步骤会 `[skip] 未找到 .map，跳过内存快照同步（需先 @build）`。
|
||||
**处置**：新空间第一次提交前先 `@build` 一次（`build` 锁自动排队，与别的树串行）。与上一条
|
||||
的区别要分清：上一条是「有 `.map` 但是旧的」，本条是「根本没有 `.map`」，处置动作不同。
|
||||
- **⚠ 增量构建可能不重链 → `.map` 数字瞬态不一致**（2026-10-12 实测）：
|
||||
`@build` 若判定无需重链，`.map` 保持旧值，此时 `--write` 生成的快照是**瞬态值**
|
||||
（实测同一份源码两次读到 223,560 与 223,724，差 164 B）。**以主工作树（集成点）
|
||||
的 `.map` 为准**；改完 RAM 相关代码后确认重链再刷新快照。
|
||||
- **`ram_baseline.py` 的 help 串里有未转义的 `%`**（2026-10-25 实测：某些直调姿势会渲染 argparse help 并崩）——
|
||||
查用法读脚本头部 docstring，别靠 `--help`；修脚本本身属 `mem-budget` skill 的范围。
|
||||
- **合并冲突常落在「生成物」上**：`docs/内存管理/RAM使用分析与优化方案.md`（mem-numbers
|
||||
快照）在双方都改过时必冲突，且**两边都不能直接选**（各自基于不同基线）——
|
||||
正确做法是解冲突后用**合并后的实际构建**重新生成，不要挑一侧。
|
||||
- **并集合并残留**：双方都改过的文件（尤其 `.gitignore`）会被 git 自动并成**并集**，
|
||||
可能留下指向已删目录的死规则或重复条目。脚本会自动报「双方都改过」的文件清单 +
|
||||
连续重复行；**权威判据是 base / 两个 tip 三方对比**（`git show <ref>:<file>` 逐项 `grep -F`），
|
||||
别用 `tail -N` 目测。
|
||||
- **⚠ 别用 heredoc 打补丁改门禁脚本造探针**（2026-10-27 实测三连败，白烧一整轮）：heredoc 里的 python
|
||||
把门禁脚本改坏——`patched 3` 之后 `PROBE_RC=1`、`SyntaxError: unterminated string literal (detected at
|
||||
line 882)`，而它**正是被测对象**，改完的数不可信；另一处 `replace('\', '/')`（想把 Windows 反斜杠换成正斜杠）里的反斜杠被多层引号吞掉
|
||||
→ `SyntaxError (detected at line 16)`。**正解**：探针落成**独立 `.py` 文件**（写文件的工具，UTF-8 无 BOM）
|
||||
再 `"$PY" probe.py`；非用 heredoc 不可就用单引号定界 `<<'PY'`（防变量展开），且**路径一律 `as_posix()`、
|
||||
一个反斜杠都不写**——反斜杠字面量要穿「JS 模板串 → bash → shell 引号 → python」四层，必被吞。
|
||||
E 节那两段扫描脚本同理：**落成 `ci-artifacts/*.py` 再跑**（该目录已被忽略，不会污染第 5 步复验用的脏行数）。
|
||||
- **取门禁数字：import 门禁模块，别猜输出、别打补丁**（2026-10-27；grep 源码 / 手抄正则 / 解析 stdout 三种姿势
|
||||
都拿不到可复核的数，换成这句立刻拿到）：先读门禁脚本的 `main()`（直读末尾那几十行）看它怎么装配检查器，
|
||||
把**那几行照抄**进探针——`sys.path.insert(0, 'scripts')` → `import check_ids as ci` →
|
||||
`ci.load_json(ci.REGISTRY_FILE, 'reg')` + `ci.load_json(ci.ALIASES_FILE, 'alias')` →
|
||||
`ck = ci.Checker(reg, al, verbose=False)` → `ck.run()` → `print(ck.stats)`。别猜键名：先
|
||||
`print(sorted(ck.stats))` 列出全量计数项，再按精确键取数（顺带 `git diff` 确认门禁脚本自己**没被改过**）。
|
||||
- **别把「不可判定」当成一个数**（2026-10-27）：`id-check` 有两种口径——检查器自己算的**硬不可判定**实测只有
|
||||
**2** 处，而门禁红线（`scripts/archive/id_gate/id_registry.json` 的 `undecidable_total_ceiling`）量的是**派生值**
|
||||
`refs_total - decidable`（实测 8,744 - 7,582 = **1,162**，拆开 = `skip_bare_unmanaged` 834 +
|
||||
`noise_allowed` 326 + 硬不可判定 2，**三数精确闭合**）。所以**带属主登记处的族（TC-XXX 这类）加多少引用都算
|
||||
「可判定」、一点不吃这条余量**，真正吃余量的是**裸形字母+数字**字面量；反过来「把可判定引用改写成散文」才是
|
||||
**稀释比值**的动作，那才是绝对数红线要防的。口径混用会当场给整条道下错指令（本次就下错过、量完立刻撤回）。
|
||||
- **队友的自查结论要复核，小心它测的是错变量**（2026-10-27）：log 道做过受控实验、结论是「我们没推高这个数」——
|
||||
他们改的是 TC 号、盯的是 `skip_bare_unmanaged`，那个组合当然不动；而 +16 走的是另一条路（新增裸形 「字母 T 累进数字 4」）。
|
||||
定责用 D 节：逐文件注入 + HEAD/在飞两版同一计数器相减 + 对新增行 grep；闭合后 +16 = 16 处裸形 「字母 T 累进数字 4」，
|
||||
**推翻**了自查结论。口头自查与 `--note` 都不是证据，**可复核的差分数字才是**。
|
||||
- **`.workbuddy-ai/` 刻意不共享**：记忆不随任务分叉，也不给联接递归删除的机会。
|
||||
任务工作树自己的记忆由 `done` / `abort` 在清场前归并回主工作树。⚠ **手工回收（E 节）没有这一步归并**：
|
||||
拆之前顺手 `ls <tree>/.workbuddy-ai/` 看一眼，有内容就一并备份进 `ci-artifacts/wt-leftover-backup/`。
|
||||
- **`--lean` 只省磁盘不省时间**：实测全量 smudge 7.25 s / 83 MB，跳过 smudge 7.05 s / 45 MB，
|
||||
两者工作区都干净。默认走全量（参考图可用），磁盘紧张时才用 `--lean`。
|
||||
- **锁不绑定进程存活**：`lock acquire` 本身是短命进程，而真正用资源的烧录/构建在别的进程里跑。
|
||||
所以判「陈旧」只看**时效**（该锁的 TTL）加显式 `--force`；pid 仅作排障记录。
|
||||
同任务重复 acquire 是幂等的（不会把自己锁死）。
|
||||
- **TTL 按锁分设**（2026-10-12）：`build` = **1h**、`bench` = **6h**（`LOCK_TTL_HOURS`）。
|
||||
口径是「兜底窗口应与操作真实时长同量级」——编译是秒~分钟级，6h 的兜底太钝；
|
||||
bench 是会话级（flash→`@test`→探针），才配得上小时级。持有者还可用
|
||||
`lock acquire ... --ttl <小时>` **自报**更精确的窗口（`keil_build.py` 即按其 `--timeout` 自报）。
|
||||
- **陈旧锁自动接管**：超过该锁 TTL 未释放即视为陈旧，下次 `acquire` 会接管并提示；
|
||||
未到 TTL 的活锁需 `--force`。`done` 的收口前置也会**自动释放陈旧锁**（不再硬失败），但
|
||||
**未到 TTL 的活锁会把 `done` 挡在前置检查**（B 节第 8 步）。
|
||||
- **`build` 锁不必手工持**（2026-10-12 起）：`@build`（`keil_build.py`）**自持自释**——
|
||||
进入 acquire、`finally` 无条件 release，所以"Agent 忘了 release、锁一直挂到 TTL"这条在构建路径上已消除。
|
||||
`done` 的门禁自己持锁并给子进程设 `DTU_LOCK_HELD=build` 告知跳过（新旧脚本都兼容）。
|
||||
**`bench` 锁仍须 Agent 手工持**（会话作用域：跨烧录→`@test`→探针，见 `keil-build` SKILL.md）。
|
||||
> 详情已外置（本文件须留头量给自进化：dsh-mnemon 写侧上限 65536 字节，超限的技能再也生不成草案）。全文见 [reference/pitfalls.md](reference/pitfalls.md) —— 「陷阱（实测）」逐条清单原文。
|
||||
|
||||
## 验证
|
||||
|
||||
- `$TW list`：台账段条目数 = `ls _wt` 的目录数且 ≤ 3；刚回收的任务与历史占位条目都不再出现
|
||||
（插件树另起一段，不参与这条计数）。
|
||||
- `$TW lock status`：`build 空闲（TTL 1.0h）` + `bench 空闲（TTL 6.0h）`——没有本会话留下的持有者。
|
||||
- `git log --oneline -3`：能看到 `merge: task/<ID>-<slug> 合入 <base>` 与其后的补基线提交；
|
||||
`git status --porcelain` 为空（补链改动已提交，才谈得上重跑 `done`）。
|
||||
- `ls _wt/.state/`：该 ID 的台账已无（清场最后一步 unlink）；重复 `done` 报「任务不存在」不必再追。
|
||||
- **E 节回收**：`git worktree list` 只剩主树 + 判「保留不动」的树（已拆路径逐条消失）；**拆前/拆后主树
|
||||
`git status --porcelain -uall` 行数相同且 `diff` 为空**（实测 0 → 0）；`ci-artifacts/wt-leftover-backup/` 里每个留档件都打印过
|
||||
文件名与字节数、条目数 = 分桶判「要留档」的条目数；每棵被拆的树都留有 `REPARSE: none` 预扫记录；全景输出里
|
||||
`UNIQUE-UNMERGED` 归零（或全部已备份）；保留树在报告里点名给出判据（`merge-base --is-ancestor` = MERGED）。
|
||||
- **E 第 6 步清悬挂台账**：该 json 已从 `_wt/.state/` 消失（`.state-bak` 在备份目录里）、`$TW list` 不再打出它、
|
||||
`$TW lock status` 两把锁仍空闲；全程未对该 ID 跑 `done` / `abort`。
|
||||
- **F 节桥接**：`plugin list` 的「联接」列按实际三态点名（`已联` / `缺 .venv` / `缺 SDL2` /
|
||||
`齐(实体SDL2)`——旧实现只取样 `.venv`，半联树会说谎）；**adopt/unadopt 前后主树 `.venv` 与树内文件都
|
||||
还在**；主线缺 SDL2 时 `adopt` 打 `[skip]` + 「还不能算就绪」而不打「现在可以跑」；`plugin adopt ".."`
|
||||
必须 exit 2；打印的 `pw:<name>` 与 `keil_build.py` 从 cwd 反推的名字逐字相同；`done <插件树名>` 只 exit 2。
|
||||
- D 节归因：测量前后 `git -C "$MAIN" status --porcelain` **逐行一致**（主树全程只读）；
|
||||
`git worktree list` 里净室路径已消失；逐文件增量之和 **等于**观察到的涨幅（实测 +6+8+2 = +16），且每处增量
|
||||
都指到具体字面量类别（裸形 「字母 T 累进数字 4」）与属主；取数走 `import check_ids` 读 `ck.stats`，且门禁脚本自身 `git diff` 为空。
|
||||
- 补绿链的每一条都自己 `echo RC=$?` 看到 0，最后以重跑 `done` 打出的**清场日志**（`已摘除联接` /
|
||||
`已删除分支` / `完成（分支此前已合入）`）为成功判据，而不是 `tail` 出来的最后一行。
|
||||
> 详情已外置（本文件须留头量给自进化：dsh-mnemon 写侧上限 65536 字节，超限的技能再也生不成草案）。全文见 [reference/verification.md](reference/verification.md) —— 「验证」清单原文。
|
||||
|
||||
## 与其它 skill 的衔接
|
||||
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
### D. 门禁指标异常增长 → 逐文件归因（把净室工作树当**测量仪**，主树全程只读）
|
||||
|
||||
**场景**（2026-10-27 实测）：`id-check` 突然 FAIL「不可判定 1,178 > 上限 1,166」——比上一轮量到的 1,162 又涨了 **+16**，
|
||||
而主工作树里同时压着 4 条在飞任务道的未提交改动。**不许 stash / checkout / reset**（那是搬动甚至丢弃别人未提交的工作，
|
||||
项目级 Never；`git status` 一乱，整条道的现场就没了），**不许改门禁脚本本身**（它就是那把尺子，改了数字就不可信），
|
||||
**也别在脏主树里跑门禁**（那测的是 4 条道 + 未跟踪文件的混合体，永远分不出谁）。正解：**在仓库之外另起一棵
|
||||
detached HEAD 的干净工作树当净室，一次只往里注入一份在飞文件**，与基线差分即得每个文件的独立贡献。两步：
|
||||
**净室建树 → 单文件注入测量**。
|
||||
|
||||
1. **建净室 + 先落基线数**（路径必须**在仓库目录之外**；铁律 7 对临时树同样成立——放仓内就污染 `git status` /
|
||||
`pre-commit --all-files` / 全库搜索）：
|
||||
|
||||
@T3@bash
|
||||
MAIN="D:/Code/DTU Code/STM32F4-Base" # 主工作树绝对路径（含空格 → 变量整体加引号）
|
||||
WT="$MAIN/../_wt/und-attr" # 仓外同级 _wt/ 下；一次测量固定用同一个名字
|
||||
rm -rf "$WT" 2>/dev/null
|
||||
git -C "$MAIN" worktree add --detach "$WT" HEAD >/dev/null 2>&1 || { echo WT_FAIL; exit 9; }
|
||||
git -C "$WT" status --porcelain # 应为空
|
||||
"$PY" "$WT/scripts/archive/id_gate/check_ids.py" 2>&1 | tail -25 # ← 口径：id-check 钩子已于 2026-10-28 退役（脚本移入 scripts/archive/id_gate/），按该脚本自身默认参数跑；基线与注入用**同一条命令**
|
||||
@T3@
|
||||
|
||||
- `--detach`（**不要 `-b`**）：净室没有分支、不写 `_wt/.state/<ID>.json` 台账 → **不占 `MAX_CONCURRENT = 8`
|
||||
名额、不出现在 `$TW list`**，也没人会被误指去对它跑 `done`（建与拆都不走 `$TW new` / `$TW done`）。
|
||||
- 能这么量的前提：该门禁**只读仓库内文本**。依赖本树构建产物的门禁（`mem-numbers` / `mem-budget` 要 `.map`）
|
||||
在净室里必然报「找不到 .map 事实源」（见陷阱「新建工作树从未构建过」）——**那类指标不能这么归因**。
|
||||
- `git status --porcelain` 非空 = 有别人的未跟踪文件被带进净室 → 先 `git clean -xdn` **干扫**（别去 `n`）
|
||||
看清会删什么，只挪走多出来的那些再测；语料被污染出来的数字与 CI 不可比。
|
||||
2. **一次只注入一份在飞文件 → 跑同一个扫描器 → 与基线差分**（得到的是每个文件的**独立**贡献，不是合计）：
|
||||
|
||||
@T3@bash
|
||||
for f in "App/log/sys_log_mcu.c" "test/host/sys_log_mcu/sys_log_mcu_test.c" "docs/子系统设计/运行与自检记录设计说明.md"; do
|
||||
mkdir -p "$WT/$(dirname "$f")"
|
||||
cp "$MAIN/$f" "$WT/$f" # 拷进净室；主树那份只读、一字节不动
|
||||
echo "== $f =="; "$PY" "$WT/scripts/archive/id_gate/check_ids.py" 2>&1 | tail -25 # ← 与第 1 步同一条命令
|
||||
git -C "$WT" checkout -- "$f" # 只还原净室里自己刚拷进来的那份
|
||||
done
|
||||
@T3@
|
||||
|
||||
实测：`run_par.c` / `board_ui_nav.py` / `check_nested_comment.py` / keil `SKILL.md` **各 +0**，
|
||||
而 log 道那三个文件 **+6 / +8 / +2**，合计**正好 +16**。**Σ(逐文件增量) ≠ 观察到的涨幅 → 还有没被注入的
|
||||
在飞文件，或存在文件间交互项**，不许就此交卷。
|
||||
3. **定性增量是哪一类字面量**（只有「谁」没有「为什么」= 给不出可执行的改法）：同一计数器在 **HEAD 版**与
|
||||
**在飞版**各数一遍，**差值才是新增行带来的**（存量的不算这条道的账）；再对新增行直接 grep。本次 16 处全是
|
||||
**裸形 「字母 T 累进数字 4」**（`T` 在 `scripts/archive/id_gate/id_registry.json` 的 `bare_check_letters` 里，规范形态是连字符形），
|
||||
全部落进 `skip_bare_unmanaged` —— 到这一步结论才配发给属主。
|
||||
4. **闭合 + 复验主树一个字节没被污染**：
|
||||
|
||||
@T3@bash
|
||||
git -C "$MAIN" worktree remove --force "$WT" # 净室里只有自己的拷贝、没有原件，--force 安全
|
||||
git -C "$MAIN" worktree list # 不该再有 und-attr
|
||||
git -C "$MAIN" status --porcelain | sort # 与测量前**逐行一致**（测量前先存一份基线清单）
|
||||
@T3@
|
||||
|
||||
⚠ **上面第一行的前提是有条件的**：树里混进了别人的在飞 / 未跟踪内容时「只有自己的拷贝」就不成立了，
|
||||
`--force` 直接拆等于替别人把唯一版本删掉 → 先走 **E 节**（全景 → 逐文件分桶 → 联接预扫 → 唯一残留先备份），
|
||||
再回来执行本步；复验按 **E 第 5 步**做（拆前/拆后主树 `status --porcelain -uall` 行数必须相同）。
|
||||
**同一棵净室树的第二种用法**：按指定 commit **只读**构建出像 / 烧录验收——不搬动任何在飞改动，也不为台架
|
||||
提前抢发一笔提交；构建与烧录都在这棵树里做（不在主树），仍受 `bench` / `build` 锁串行（铁律 3）。
|
||||
@@ -0,0 +1,87 @@
|
||||
### F. 与 DSH worktree 插件（`/worktree`、模型工具 `worktree_create`）共存
|
||||
|
||||
本仓现在有**两套**隔离空间。别混用，也别互相回收：
|
||||
|
||||
| | `@task`（本 skill） | DSH worktree 插件（`dsh-task-worktree`） |
|
||||
|---|---|---|
|
||||
| 树在哪 | 仓库**外** `../_wt/<ID>-<slug>/` | 仓库**内** `.dsh-worktrees/worktree/<name>/` |
|
||||
| 谁建 | `new <ID> <slug>`（人来敲命令） | 会话选「Worktree模式」/ 模型调 `worktree_create`（零命令） |
|
||||
| 台账 | `_wt/.state/<ID>.json`（本 skill） | `.dsh-worktrees/manifest.json`（插件私有格式，别去改） |
|
||||
| 分支名 | `task/<ID>-<slug>` | `worktree/<name>` |
|
||||
| 共享联接 | `new` 自动建 | **建树时没有** → 要 `plugin adopt` 补 |
|
||||
| 回收 | `done`（预演 / 合并 / 门禁 / 清场）或 `abort` | 用户敲 `/worktree finish\|bring-back\|remove\|prune`（模型碰不到收尾命令） |
|
||||
|
||||
**为什么允许它把树建在仓内**（铁律 7 的唯一例外）：路径写死在插件里（`WORKTREE_NAMESPACE = worktree`
|
||||
+ `<repo>/.dsh-worktrees/`），而暴露给模型的工具只有 `worktree_create` / `worktree_list` /
|
||||
`worktree_status` 三个，配置面改不动。兜法三件（均已落地）：
|
||||
|
||||
1. `.gitignore` **预置** `.dsh-worktrees/` —— 插件首次 `create` 会往 `.gitignore` 追加一模一样的字面量，
|
||||
`ensureIgnored()` 见到同名规则即跳过；不预置就等于让插件在会话中途改这份受控文件（diff 里冒出
|
||||
一行"不是我加的"）。
|
||||
2. 全库扫描的排除面登记了它：`scripts/check_doc_links.py` 的 `SKIP_PARTS`、
|
||||
`tools/refgraph/gen_refgraph.py` 的 `EXCLUDE_DIRNAMES`、`scripts/check_layer_deps.py` 的 `os.walk` 兜底。
|
||||
一份仓库副本被全库扫描吞进去 = 文档链接假红 + 配图生成物逐字节漂移砸在某位同事头上。
|
||||
3. 联接与锁归属由本节命令接上（下面三步）。
|
||||
|
||||
**这棵树是不是插件的**：`git worktree list` 里路径含 `.dsh-worktrees/` 就是。`$TW list` 现在会在台账段
|
||||
下面另起一段列出它们，联接列**点名缺哪一样**（`已联` / `缺 .venv` / `缺 SDL2` / `齐(实体SDL2)`）。**插件树不占
|
||||
`MAX_CONCURRENT = 8` 名额**——回收不归本 skill，
|
||||
硬计入只会让别人那棵关不掉的树把 `new` 挡死（`new` 会打印一行「另有 N 个插件工作树不计入上限」提醒并发代价）。
|
||||
|
||||
三步接上（`<name>` 可带 `worktree/` 前缀，也可多段如 `refactor/logging`）：
|
||||
|
||||
@T3@bash
|
||||
"$PY" "$TW" plugin list # 一览：分支 / 脏 / 缺哪个联接（缺项另起一行说后果）
|
||||
"$PY" "$TW" plugin adopt N21-dhara-isfree # 只补缺失的 .venv 与 simulator/SDL2 联接
|
||||
"$PY" "$TW" plugin unadopt N21-dhara-isfree # 只摘联接（os.rmdir），绝不动目标内容与树里文件
|
||||
@T3@
|
||||
|
||||
- **两条联接坏了的样子完全不同**：缺 `.venv` → `ci_local.py` 的四级解释器回退**静默**落到机器级
|
||||
python（无 fontTools = `generated-fresh` 假红的老根因，AGENTS.md 记着）；缺 `simulator/SDL2` →
|
||||
`build_sim.bat` 当场报错（`SDL2_DIR` 是裸 `set`，没有 env 逃生口）。所以列表只说「已联」不够——
|
||||
它按缺的那一样分别给后果，`adopt` 没补齐也只报「还不能算就绪」，不许说「现在可以跑」。
|
||||
- **adopt 只碰联接**：已联的跳过；`simulator/SDL2` 若已是实体目录只告警不动；`.dsh-worktrees/` 之外的路径
|
||||
一律 exit 2（实测 `plugin adopt ".."` 被拒）——这道闸防的是把主树或 `_wt` 目录当插件树遮蔽掉真实内容。
|
||||
- **锁归属现在认得出来**：`@build` 在插件树里自持自释时，持有者名从 cwd 反推成 `pw:<name>`（多段名压平成
|
||||
`-`），与 `plugin adopt` 打印的那个名字逐字相同（`keil_build.py: plugin_tree_owner()` ↔
|
||||
`task_worktree.py: plugin_lock_owner()`）→ `lock status` 不再一律落成 `build-cli`。
|
||||
- 上台架仍须手工占锁、用同一个名：`lock acquire bench --task pw:<name> --note <说明>` →
|
||||
`lock release bench --task pw:<name> --bench-pass`。插件树没有台账 → 按 B 节只 warn、锁照常放。
|
||||
- **命名建议**：插件 `<name>` 沿用 `@task` 的 `<ID>-<slug>` 形态（如 `N21-dhara-isfree`），两套视图同名好对账；
|
||||
但分支前缀必然不同（`worktree/` vs `task/`），别把两者说成同一个分支。
|
||||
- **收尾不在这**：`done` / `abort` 拿插件树名下手只会 exit 2（这是保护，别绕过去手工 `git worktree remove`；
|
||||
要拆先 `plugin unadopt` 摘联接，再由**用户** `/worktree remove`）。`/worktree bring-back` 要求主工作树干净，
|
||||
本仓常有在飞改动 → 提交或 stash 由用户定。反过来插件也不会碰 `_wt/`（路径根不同，谁也删不掉谁）。
|
||||
|
||||
### F-1. 两条共享联接**不是同级需求**（按仓库实配定级；别答成「两个都必须」）
|
||||
|
||||
- **`simulator/SDL2` = 硬需求**：`simulator/CMakeLists.txt:12` 是
|
||||
`set(SDL2_DIR "\${CMAKE_CURRENT_SOURCE_DIR}/SDL2/SDL2-2.32.10")`——普通 `set()`、**非 `CACHE`**，所以既没有环境变量入口、
|
||||
命令行 `-DSDL2_DIR=` 也会被这个普通变量盖掉；`SDL2_INCLUDE_DIR`（:34）、`SDL2_INCLUDE_PARENT`（:70）、`SDL2_LIB_X64`（:71）、
|
||||
链接目录（:180）、`SDL2.dll` 拷贝（:207）**全部从它派生**。缺它 `build_sim.bat` 当场配不出来（脚本里的 `SDL2_DIR` 同样是
|
||||
裸 `set`，也没有 env 逃生口）。
|
||||
- **`.venv` = 软需求**（有显式逃生门，但绕开有代价）：`scripts/ci_local.py` 的解释器解析顺序（:108-:138）——
|
||||
① `DTU_PRECOMMIT_PYTHON`（显式配置，指错**立即报错**、不静默降级）→ ② `sys.executable` → ③ 仓库 `.venv` →
|
||||
④ `shutil.which("python")` → ⑤ `_global_python_candidates()` 的常见机器级位置。树内没有 `.venv` 时会**静默**落到机器级
|
||||
解释器 → 无 fontTools → `generated-fresh` 假红（AGENTS.md 记着的老根因）；可以用 `DTU_PRECOMMIT_PYTHON` 顶掉，
|
||||
但要每台机器自己配——这就是它「软」的意思：有路可走，走得不爽。
|
||||
|
||||
结论口径：**要补就两条都补（`plugin adopt` 一次干完，成本近乎零），但「都必须」是错的**——SDL2 没有任何替代路径，
|
||||
`.venv` 有 `DTU_PRECOMMIT_PYTHON` 这条门。现役命令形式仍是 `plugin list` / `plugin adopt <name>`；**不改代码、
|
||||
不改 `CMakeLists.txt`**（真要给 SDL2 加 CACHE 逃生门属于改模拟器构建口径，另案 → `lvgl-simulator` skill）。
|
||||
|
||||
### F-2. 「DSH 都有 worktree 插件了，为什么还自持 Python 生命周期」——取证姿势与答案边界
|
||||
|
||||
这题不许凭印象答，口径 = **实读插件源码**：在 DSH 安装目录定位插件包（`npm root -g` → `<global>/node_modules/@deepseek-ai/dsh/`，
|
||||
或读 profile 的 `dsh.profile.bundles` 找包名），**记下版本号与文件路径**，再对三个概念名逐个 grep 并**报出命中数**：
|
||||
|
||||
1. 独占锁 / 资源串行（`lock`、`acquire`、`release`、TTL）——插件侧**零命中**：它的模型是「一棵树一个会话」，没有跨会话排队概念。
|
||||
2. 共享目录联接（`.venv`、`simulator/SDL2`、`mklink /J`、reparse point）——零命中：插件建树就是纯 `git worktree add`，
|
||||
所以插件树天生缺这两条联接（定级见 F-1）。
|
||||
3. 联接状态显示（三态：已联 / 缺 .venv / 缺 SDL2 / 齐(实体SDL2)）——零命中。
|
||||
|
||||
**重叠面要说清**：两侧底层是**同一条** `git worktree add`，本 skill 没有重造「建树」；重叠只在**开**与**收**两个动作，
|
||||
而插件的收（`/worktree finish|bring-back|remove|prune`）是**人类命令**、模型碰不到，也没有「合并前预演 → 并集残留审计 →
|
||||
补基线 → 门禁 → 先摘联接」这条编排。本仓为什么必须自持：硬件各只有一份（一块 ST-LINK、一套 Keil 授权、一个 COM6、
|
||||
一个 `192.168.1.100`）→ 要 `build` / `bench` 锁串行；SDL2 是模拟器硬依赖且无逃生门 → 要共享联接；台架 PASS 要留给
|
||||
`done` 记账 → 要台账。**给不出版本号与 grep 命中数，就不要下结论。**
|
||||
@@ -0,0 +1,9 @@
|
||||
# 原 frontmatter（2026-10-29 因超 65536 字节写侧上限而瘦身，原文逐字留档）
|
||||
|
||||
本技能正文受 dsh-mnemon 插件写侧上限 65536 字节约束（只在写侧校验，加载侧不查），超限时自进化每次「生成草案」都会被拒、行永久卡在「生成中」。以下是瘦身前的 description / whenToUse 原文，触发词语义更全，写路由时可参考；如需恢复请连正文一起改回并先确认总体积 < 65536。
|
||||
|
||||
---
|
||||
name: task-worktree
|
||||
description: 多任务并行开发的空间管理（git worktree 生命周期）：new 开一棵工作树 + 任务分支、目录联接共享 .venv 与模拟器 SDK、活跃任务硬上限 8 与腾位、build/bench 两类独占锁（含非登记任务占锁后「缺台账」释放不掉的正解）、done 预演合并回主干、**主工作树被别的并发会话弄脏时的手工合并路径（取证 → `merge-tree` 预演 → `merge --no-ff -F` → 外部改动 blob id 前后对账 → C2 节）**、门禁未全绿的补基线收尾、并集合并残留审计、**任务树内门禁与审计输出的落点（`<tree>/ci-artifacts/` 先 `mkdir -p`；文档链接按单文件在树内跑、全库 `--all` 基线合并后在主树跑；`simulator/SDL2` 联接假红 → G 节）**、**非登记工作树（detached HEAD / 无台账 / 树内有在飞或未跟踪内容）的安全回收**（逐文件内容分桶 + 联接/reparse 预扫 + 唯一残留先备份再 --force + 悬挂台账清理复验），以及**把仓外 detached worktree 当净室测量仪**——门禁指标异常增长时一次只注入一份在飞文件、与基线差分做逐文件归因；**以及与 DSH worktree 插件（`/worktree`、模型工具 `worktree_create`，树在仓内 .dsh-worktrees/）的桥接**——`plugin adopt` 补共享联接、锁归属 `pw:<name>`、回收仍归 /worktree。规格见 docs/环境与部署/并行任务工作树方案.md。
|
||||
whenToUse: 要同时推进多个任务、担心同分支同文档互相冲突；要为新任务开一个隔离空间；要把任务合并回主干；或遇到 `new` 报「已有 8 个活跃任务（上限 8）」、`lock release` 报「任务 X 不存在（缺台账）」、`done` 报「门禁未全绿：工作树与分支保留，未清场」、或 `done` 报「主工作树不干净」而那份未提交改动是**别的会话/插件**留下的（不能提交也不能丢弃 → C2 节手工合并）、两个任务抢 COM6 / UV4、"改了文档被覆盖"、并集合并残留时；或**要在任务树里跑文档/审计门禁**——`--all` 报一堆问题却全在 `simulator/SDL2` 联接下、或往 `ci-artifacts/` 写输出报 ENOENT / No such file or directory（→ G 节）；或**门禁指标异常增长（如 id-check 的不可判定数从 1,162 涨到 1,178、+16）却查不出是哪个文件 / 哪条任务道造成的**、主工作树压着多条在飞改动而不许 stash / 提交 / 改门禁脚本、要按 HEAD 基线只读出像验收时；或**要回收 `@task list` 里根本看不到的工作树**（`git worktree list` 有它、台账没有 / detached HEAD / 树里疑似留着别的会话的在飞或未跟踪内容）、或**要清台账里 branch / path 都已不存在的悬挂条目**（`@task list` 输出发怪、`new` 报「任务已存在」或白占 8 个名额之一）；或**这棵隔离空间是 DSH worktree 插件开的**（会话选了「Worktree模式」/ `/worktree create`，树在仓库内 `.dsh-worktrees/`）——进去发现 `.venv` 不在、`@build` 与门禁全部起跑失败，或想看清谁在占 UV4 / 台架 → F 节。
|
||||
---
|
||||
@@ -0,0 +1,59 @@
|
||||
### G. 任务树内跑门禁与审计：输出落点（ci-artifacts）与 SDL2 联接假红
|
||||
|
||||
三条硬规矩，全是 2026-10-29 实测付过失败成本的（两起 ENOENT + 一次假红误判）：
|
||||
|
||||
1. **门禁/审计输出只落 `<tree>/ci-artifacts/`，而新树里它不存在 → 落盘前先 `mkdir -p`**。`ci-artifacts/` 被
|
||||
`.gitignore` 忽略（不污染脏行数，E 第 4 步的备份同理），但也因此**不会被检出**——`$TW new` 出来的树里没有这个
|
||||
目录。直接 `fs.writeFileSync("<tree>/ci-artifacts/head-md.md", …)` 当场 `ENOENT: no such file or directory`，
|
||||
**整段程序零执行**（实测：那一轮的门禁体检与快照读取全没跑成，白重跑一次）。用 Node 写之前先
|
||||
`fs.mkdirSync(dir, { recursive: true })`；用 bash 重定向就先单独敲一条 `mkdir -p ci-artifacts` 再落盘
|
||||
——重定向在命令执行**之前**解析，目录没建出来时是同一条命令直接失败，后面串着的 `grep` 跟着一起报
|
||||
`No such file or directory`，看着像「门禁没跑出结果」，其实是写错了地方。
|
||||
2. **`cd` 进任务树之后，`../_wt/x.txt` 不是你以为的地方**：`cd` 之后 `..` = `_wt`，`../_wt/x.txt` 落到
|
||||
`_wt/_wt/x.txt`（实测就是这么报的）。**树内命令的输出一律用树内相对路径**（`ci-artifacts/xxx.txt`）；
|
||||
要绝对路径就写完整绝对路径，跨树取文件用 `$MAIN/…`、`$WTROOT/…` 这种变量打头的全路径，
|
||||
不靠 `cd` 之后的相对层级往上跳。
|
||||
3. **任务树内文档门禁按单文件跑；全库 `--all` 基线留到合并后在主树跑**。任务树的 `simulator/SDL2` 是指向
|
||||
主树同一份的**目录联接**（`new` 的第 2/3 步建的），`--all` 会把这份「仓库里的第二份仓库副本」一起扫：
|
||||
实测任务树里 `check_doc_links.py --all` 打 `检查 222 个文档，35 处问题`、RC=1，而 **35 处全落在
|
||||
`simulator/SDL2` 联接下**、要改的文档一条都没有 → 判红纯属联接带来的假红。单文件检查不受影响
|
||||
（扫描根就是那一个文件，联接目录不在面内）。主树本身没有 SDL2 时不产生这类假红（联接如实镜像主树，
|
||||
F 节那棵树连 SDL2 都没得联），但**别据此认为 `--all` 在树内可信**。
|
||||
|
||||
@T3@bash
|
||||
F="docs/<子目录>/<本次改动的文件>.md" # 本次改动的那一个文件
|
||||
"$PY" scripts/check_doc_links.py "$F" > ci-artifacts/dl-<slug>.txt 2>&1; echo RC=$?
|
||||
cat ci-artifacts/dl-<slug>.txt
|
||||
@T3@
|
||||
|
||||
逐文件跑的实测读数：需求文档 161 处章节引用 / 98% 机器可判定 / rc=0；方案文档 16 处 / 88% / rc=0。
|
||||
确实要在树内跑 `--all` 时（例如怀疑主干基线本身），判红顺序**固定三步**，缺一步都不许下结论：
|
||||
① 在**主树**跑同一条命令拿基线；② 过滤掉 `simulator/SDL2` 联接下的问题行；③ 剩下的与主树基线逐行比。
|
||||
只跑 `--all` 见 RC=1 就回「文档门禁挂了」= 把基线噪声算成本任务的账；只跑「过滤后为空」就回「全绿」
|
||||
= 会漏掉真红。全库 `--all` 的正解位置是**合并后的主工作树**：实测合入后在主树跑 `check_doc_links.py --all`
|
||||
= 2,597 处章节引用 / 194 个文档 / rc=0 —— 这才证明「就地删叙述」没打断任何引用。
|
||||
另：**不因 `--all` 的既有假红跳过对本次改动文件的单文件复检**（假红是基线的事，你的文件仍要逐个过）。
|
||||
|
||||
4. **文档改动在树内提交前的固定体检**（2026-10-29 实测）：`lines / bytes / BOM / CR / U+FFFD / 三连续空行 /
|
||||
行尾空格 / 末行单个 LF` + 一个自写的 **Markdown 表格每行列数一致性**检查（数格子前先把转义管道 `\|` 还原成占位符，
|
||||
否则会把 `\|` 当成列边界数错）。为什么要自己数：`doc-links` 只管链接与章节、`no-mojibake` 只管编码面，
|
||||
**表格断列与删段留下的三连续空行没有任何钩子会报**。
|
||||
实测读数：需求文档 `lines=2665 bytes=196137 BOM=false CR=0 U+FFFD=0 tripleBlank=0 trailingWS=0 endLF=true`，
|
||||
表格体检另报两处坏表格（`L988-992 counts=5/7`、`L2472-2486 counts=2/3`）——**与本次编辑无关的历史行**。
|
||||
所以体检要**区分「本次改动 bad=0」与「整份文件 bad=0」**：先定位归属再决定动不动手，顺手改别人的区域等于把
|
||||
没打算提交的内容卷进这笔改动（报告里写「本次改动引入 0 处」，并点名那两处是存量）。
|
||||
|
||||
5. **提交 / 合并信息一律 `-F` 读文件；清退类任务还要做禁词自检**（2026-10-29 两遍实测）：消息文件写在
|
||||
`ci-artifacts/`（被忽略 → 不污染脏行数），UTF-8 无 BOM、CR=0、标题 ≤100 字符、正文每行 ≤80（实测标题 31 / 32 字符、
|
||||
正文最长行 50 / 55）——`-m` 会把中文按终端代码页转码搞坏，长中文标题还容易撞 gitlint。硬自检：
|
||||
|
||||
@T3@bash
|
||||
git log -1 --pretty=%B | grep -c '485' # 被清退主题的关键词：必须是 0
|
||||
git log -1 --pretty=%B | grep -ci '\bDE\b' # 同主题的次要关键词：同样 0
|
||||
@T3@
|
||||
|
||||
关键词不许出现在**标题、正文、合并信息**任何一处（实测标题改写成「删除与本方案无关的其它串口通道对照内容」这种
|
||||
语义短语替掉了它）——否则「别让我看到 X」这条要求在 `git log` 里当场破产。合并信息是另一份文件：
|
||||
`ci-artifacts/merge-msg-<slug>.txt` 落盘后**同样 grep 一遍**再 `git merge --no-ff --no-edit -F`（C2 第 3 步）。
|
||||
自审发现消息里的行数 / 统计算错而**尚未推送** → `git commit --amend -F <改好的文件>` 就地修（实测就这么修掉一次
|
||||
off-by-one）；**别追加一笔「更正」提交**——那等于把禁词和被更正的错数一起写回历史。
|
||||
@@ -0,0 +1,86 @@
|
||||
### C2. `done` 被「主工作树不干净」挡住，而那份脏改动是**别的并发会话**留下的
|
||||
|
||||
**场景**（2026-10-29 同一套流程在同一天跑了两遍，两遍都撞上它）：任务树里的文档改完、准备合回 `v2-on-ui`，
|
||||
主工作树却压着一个自己从没碰过的未提交改动（两次都是 `M .dsh/skills/serial-boot-test/scripts/run_boot_test.py`，
|
||||
另一个并发会话/插件留下的）。它既不能提交（不是我的改动，也不知道写没写完），也不能
|
||||
stash / checkout / reset / 删除（项目级 Never：丢弃别人的工作）。`$TW done <ID>` 的前置正好卡在这——
|
||||
它要求主工作树干净，否则未提交改动会被卷进合并（见 C 第 6 步），于是**合并与回收一起被挡**。
|
||||
|
||||
**正解 = 取证 → `merge-tree` 预演 → 主树手工 `--no-ff` 合并 → 自证外部文件没被动过 → 照常收工**，六步：
|
||||
|
||||
1. **先取证再动手**（别一看见脏就下「谁弄坏的」结论）。记下它的 mtime 与 diff 内容，判断与本合并有无交集，
|
||||
并把**合并前**的 blob id 与 `diff --stat` 存进 `ci-artifacts/`（第 4 步拿它对账）：
|
||||
|
||||
@T3@bash
|
||||
MAIN="D:/Code/DTU Code/STM32F4-Base"
|
||||
EXT=".dsh/skills/serial-boot-test/scripts/run_boot_test.py" # 外部脏文件的仓库相对路径
|
||||
mkdir -p ci-artifacts
|
||||
git -C "$MAIN" status --porcelain # 全量脏清单（本会话只认自己那几条）
|
||||
stat -c "%y %s %n" "$MAIN/$EXT" # mtime + 字节数：定性是谁在什么时候改的
|
||||
git -C "$MAIN" diff -- "$EXT" | cat # 内容性质；与本次合并有无同文件同区域
|
||||
git -C "$MAIN" hash-object "$MAIN/$EXT" | tee ci-artifacts/ext-blob-before.txt # ← 存下这个 blob id
|
||||
git -C "$MAIN" diff --stat -- "$EXT" | tee ci-artifacts/ext-stat-before.txt # ← 以及这份统计（几加几减）
|
||||
@T3@
|
||||
|
||||
实测：mtime 落在另一会话的活跃时段内，diff 是「docstring 引号改写」2+/2−，与要合的文档毫无交集 →
|
||||
定性为**与本合并无交集、不丢弃**。顺手 `git -C "$MAIN" worktree list` 看一眼有没有**别人中途新建的任务树**
|
||||
（两次里都撞见第二棵树 `data-trust-restructure`，正是这份外部改动的来路）——这是并发会话的硬证据。
|
||||
2. **`merge-tree` 预演：先证明能干净合并，再碰主干**。`$TW done --dry-run` 在这条路上同样被前置挡住，
|
||||
预演只能自己敲（git 2.38+ 的新语法，打印的是**结果树 sha**）：
|
||||
|
||||
@T3@bash
|
||||
git -C "$MAIN" merge-tree --write-tree v2-on-ui task/<ID>-<slug>; echo MT_RC=$?
|
||||
@T3@
|
||||
|
||||
判据 = **打印出一个 tree sha 且 RC=0**（实测打出 `4220906b…` + `MT_RC=0` 才敢往下走）。⚠ 本机 git 太旧没有
|
||||
这个子命令时退回 `$TW done <ID> --dry-run`——它的前置也是「主树干净」，可用环境变量 `DTU_INTEGRATION_WORKTREE`
|
||||
把集成点指到一棵干净的临时树去演练（见本文开头的环境变量）；**别为了跑 dry-run 去动主树那份脏改动**。
|
||||
预演报冲突 → 回到冲突本身处理，不许直接 `--no-ff` 硬合。
|
||||
3. **主工作树里手工 `--no-ff` 合并**（合并信息走 `-F` 文件，放在被忽略的 `ci-artifacts/`；编码口径同 C 第 5 步：
|
||||
UTF-8 无 BOM、正文每行 ≤80 字符；标题格式 `merge: task/<ID>-<slug> 合入 <base>`）：
|
||||
|
||||
@T3@bash
|
||||
git -C "$MAIN" merge --no-ff --no-edit -F ci-artifacts/merge-msg-<slug>.txt task/<ID>-<slug>
|
||||
@T3@
|
||||
|
||||
pre-commit 会**自己**把那份未提交改动 stash 起来、跑完钩子再放回（输出里能看到 `[INFO] Stashing unstaged files to …`）
|
||||
——**这条不是让你去手工 stash**，正好相反：钩子的 stash 往返让它自己走完，你只需在第 4 步验证它把东西原样还回来了。
|
||||
**为什么可以绕开 `done`**（报告里要写清这句）：`done` 的前置要求主工作树干净，而那份外部改动既不能提交也不能
|
||||
丢弃，所以合并只剩「手工预演 + 手工合并」一条合法路径；被跳过的门禁与审计由第 2 步（预演 sha + RC=0）、
|
||||
第 4 步（blob id 对账）、G 节（合并后在主树跑全库基线）、第 6 步（`lock status`）逐项补回。
|
||||
**这不是绕过保护**，是把保护要求的证据逐条自己交出来。
|
||||
4. **自证那份外部改动原样还在**（本节唯一的硬证据，两次实测都靠它结案）：合并后**再跑一次**同一对命令，
|
||||
与第 1 步存的两个值**逐项相同**：
|
||||
|
||||
@T3@bash
|
||||
git -C "$MAIN" hash-object "$MAIN/$EXT" | tee ci-artifacts/ext-blob-after.txt
|
||||
git -C "$MAIN" diff --stat -- "$EXT" | tee ci-artifacts/ext-stat-after.txt
|
||||
diff ci-artifacts/ext-blob-before.txt ci-artifacts/ext-blob-after.txt # 空输出才算过
|
||||
git -C "$MAIN" status --porcelain # 该文件仍是 M：没被顺手提交，也没被清成干净
|
||||
@T3@
|
||||
|
||||
实测：合并前后 blob id 同为 `369380ca8eb024b593d872455b6a020797abcd8d`、`diff --stat` 同为 2+/2−
|
||||
→ 证明 pre-commit 的 stash 往返没动别人的工作；合进主干的那份文档另按 G 节复核（零残留 + 全库基线）。
|
||||
blob id 变了 = stash pop 出了半冲突（现场会留下 stash 与冲突标记）→ **立刻停止收工**，把两份 blob id 与两份
|
||||
diff 原样贴进报告交给该文件属主；**绝不用 `git checkout -- $EXT` 抹平**（那是销毁别人的工作，项目级 Never）。
|
||||
5. **收工仍走技能自身的代码路径，别自己手写 rm**：先把台账**备份成 `*.state-bak`**（后缀与 E 第 6 步统一），
|
||||
再让脚本自己摘联接：
|
||||
|
||||
@T3@bash
|
||||
cp "$WTROOT/.state/<ID>.json" "$MAIN/ci-artifacts/<ID>.json.state-bak" # 先备份再动
|
||||
"$PY" "$TW" done <ID> # 打「已合入 <base>，跳过合并，直接清场」→ 先摘 .venv 与 simulator/SDL2 联接 → 删工作树 → 删分支 → unlink 台账
|
||||
@T3@
|
||||
|
||||
实测这条路径能走完（日志：`state backup -> ci-artifacts\screenlink-doc-history.json.state-bak` +
|
||||
`[ok] 已摘除联接 .venv` + `[ok] 已摘除联接 simulator/SDL2`）。**若它仍拿「主工作树不干净」挡在合并前**（没走到
|
||||
清场分支），改走 **E 节**的手工回收路径：台账仍按本步先 `cp` 成 `.state-bak`；第 1~2 步的前置换成
|
||||
「`status --porcelain -uall` 为空 + 唯一提交为空 + `merge-base --is-ancestor` 判 MERGED」三条（本次实测三条齐），
|
||||
第 3 步的联接预扫 + `rmdir` 摘联接**一步不能省**；再 `git worktree remove`（三条前置齐了就不必 `--force`）、
|
||||
删分支、`git worktree prune`。清完再敲一次 `done` 会得到「任务 <ID> 不存在（缺台账 …json）」（exit 2）——
|
||||
**这不是失败**（台账已被 unlink；判完成以 `git log` 为准，见 C 第 7 步）。
|
||||
6. **复验收工**：`git -C "$MAIN" worktree list` 只剩主树 + **别人的树**（那棵不是你的，保留并在报告里点名，
|
||||
别顺手回收 → E 节）；`"$PY" "$TW" lock status` 打 `build 空闲（TTL 1.0h）` + `bench 空闲（TTL 6.0h）` 才收工。
|
||||
|
||||
**并发会话证据必须写进报告**：主树里那份外部脏文件、中途冒出来的第二棵任务树，都要点名——是谁的、
|
||||
你怎么定性的、对这次合并的影响（本例：与本合并无交集 / 不丢弃 / 不进本次提交），以及你**没动它**的证据
|
||||
（blob id 前后一致）。「不能丢弃别人的工作」类问题九成是并发会话造成的，不写清就等于没取证。
|
||||
@@ -0,0 +1,117 @@
|
||||
## 陷阱（实测）
|
||||
|
||||
- **`--force` 不是万能钥匙**：它只覆盖四类检查——并发上限、持有者与 `--task` 不符、陈旧锁接管、
|
||||
清场时强制移除工作树。**台账缺失这类前置/环境错误（exit 2）跟它无关**（实测 `lock release
|
||||
--force --bench-pass` 报的是同一句话，锁照旧没放）。同理 `abort --force` 也只覆盖「树里有东西」这一条拒绝，
|
||||
**不会**替你做 E 节的内容保全——它只会删得更快。
|
||||
- **未跟踪文件在 `git log`、提交门禁与 `done` 的合并里都不留痕**（2026-10-29 回收现场）：钩子按 HEAD tree 的
|
||||
diff-index 取文件，未跟踪文件从没进过任何钩子的视野；`git log` 也照不出「唯一未合并」——它压根没被提交过。
|
||||
所以「这棵树没有遗留改动」这种结论**只能**由 E 第 2 步的逐文件内容比对给出，`log --oneline -1` + 脏计数都不够。
|
||||
- **`git status --porcelain` 不带 `-uall` 会折叠未跟踪目录**（E 第 1 步）：「全景」少一项、分桶少一个文件，
|
||||
最后拆掉的是别人唯一的草稿。回收路径上**一律 `-uall`**。
|
||||
- **`$TW list` 空 ≠ 没有工作树**：`list` 只遍历台账（A 第 1 步），用户说的「那 3 棵 done 掉」很可能在 `$TW list` 里
|
||||
一个都不存在（实测就是）→ 别照 `$TW list` 的空结果回「没有任务」，先 `git worktree list` 拿全集再逐棵定性（E 节）。
|
||||
2026-10-29 起 `list` 还会另起一段列出插件树（`.dsh-worktrees/`，F 节）——**"看见"不等于"归 `done` 管"**。
|
||||
- **「这棵树很久没动」不是回收判据**：实测 `bench-*` 两棵既没台账也没脏文件、mtime 很旧，但真正决定去留的是
|
||||
`git merge-base --is-ancestor <c> HEAD` = MERGED（提交已进主线）+ 未跟踪层为空；而另一棵 mtime 更新的树反而
|
||||
全是已在主线的副本。**判据是内容与祖先关系，不是时间戳。**
|
||||
- **「我记得没建过联接」不是安全判据**：判据只有扫出来的 `REPARSE: none`（E 第 3 步实测 `bench-*` 各挂一个 `.venv`
|
||||
联接，正是「不是自己建的」那类）。
|
||||
- **联接不是符号链接**：本仓库 `core.symlinks=false`，git 里的 symlink 会被检出成
|
||||
「内容是目标路径的文本文件」。共享 `.venv` 只能用 Windows **目录联接**（`mklink /J`，
|
||||
不需要管理员权限），且联接必须建在版本控制之外。
|
||||
实测（2026-10-12）：用 ctypes 直调 `DeviceIoControl(FSCTL_SET_REPARSE_POINT)`
|
||||
会被系统拒绝（Win32 4392），`mklink /J` 正常——所以脚本走后者，参数以列表交给
|
||||
subprocess，含空格的路径（本项目 `DTU Code`）由 subprocess 自动加引号。
|
||||
但**读属性**用 ctypes 没问题：`GetFileAttributesW` + `FILE_ATTRIBUTE_REPARSE_POINT` 就是 E 第 3 步的预扫手段。
|
||||
- **联接建失败不中止 `new`**：只告警并打印手工补建命令，避免留下半成品任务空间；
|
||||
但该任务里跑不了 `.venv\Scripts\python.exe`，`@build` / `ci_local.py` 会找不到解释器。
|
||||
- **`done` 前主工作树必须干净**：否则未提交改动会被卷进合并（补完基线再重跑 `done` 时最容易忘，见 C 第 6 步）。
|
||||
- **⚠ 任务树里 `check_doc_links.py --all` 的红多半是 `simulator/SDL2` 目录联接的假红**：全库扫描会吞下那份
|
||||
「仓库里的第二份仓库副本」（实测任务树 222 个文档 / 35 处问题全在联接下、RC=1，而主树同命令基线全绿）。
|
||||
判红必须先过滤 `simulator/SDL2` 下的问题行、再与主树**同一条命令**的基线比对；正解是树内按单文件跑、
|
||||
`--all` 基线合并后在主树跑 → **G 节**。
|
||||
- **新建的任务树里没有 `ci-artifacts/`**（被 `.gitignore` 忽略 → 不被检出）：`> ci-artifacts/x.txt` 与
|
||||
`fs.writeFileSync("<tree>/ci-artifacts/x", …)` 都会 `ENOENT`；`cd` 进树后再用 `../_wt/x.txt` 落到 `_wt/_wt/` →
|
||||
`No such file or directory`（两起实测，第二次直接废掉一整轮体检）。落盘前先 `mkdir -p ci-artifacts`，
|
||||
树内输出一律用树内相对路径 → **G 节**。
|
||||
- **`done` 报「主工作树不干净」而那份脏改动不是你的**（别的并发会话 / 插件留下的，实测两次都是
|
||||
`.dsh/skills/serial-boot-test/scripts/run_boot_test.py`）：**不许用 stash / 提交 / 删除去清场**（项目级 Never，
|
||||
你也无从判断它写没写完）→ 走 **C2**：取证（mtime + diff + `hash-object` 存进 ci-artifacts）→ `merge-tree` 预演
|
||||
→ 主树 `merge --no-ff -F` → 合并前后 blob id 与 `diff --stat` 对账。**「它看着像废弃的」不是丢弃判据**。
|
||||
- **⚠ `done` 的门禁跑在 `@build` 之前 → 依赖 `.map` 的钩子会误报**（2026-10-12 实测）：
|
||||
`done` 的顺序是「合并 → 重生成 → **门禁（ci_local）** → `@build`」，而
|
||||
`mem-budget`（登记簿条目「缩堆迁 CCM 后半（暂缓）」）/ `mem-numbers` 是拿**文档快照 vs `.map`** 比对 —— 门禁跑时
|
||||
`.map` 还是**主工作树合并前**的旧产物，与刚合并进来的新台账**必然不一致** →
|
||||
误报 `[FAIL] 台账受管区与 .map 不一致`。`@build` 跑完后 `.map` 才是新的。
|
||||
**处置（2026-10-25 补全）**：按 C 节第 5 步的完整链补——`check_mem_numbers.py --write` →
|
||||
`ram_baseline.py --write` → `ram_baseline.py --update` → `check_test_coverage.py --update-baseline` →
|
||||
`check_doc_links.py --all` → 提交 → 重跑 `done`（它会检测到「已合入」直接清场）。
|
||||
此时主干已含合并提交，**绝不能用提示里的 `reset --hard` 回退**。
|
||||
- **`done` 的门禁 = `ci_local.py` = `pre-commit run --all-files`（50 条钩子全跑）**（2026-10-26）：红了先读
|
||||
`[SUMMARY] static: pre-commit hooks -- passed=N failed=M skipped=K`，**按钩子 id 定根因**，别一律当「`.map` 滞后」
|
||||
去跑补基线链。典型例外：`generated-fresh`（生成器幂等性，触发面 `tools/**`、`docs/images/*.svg`、UI 生成文件）——
|
||||
合进来的分支改了生成器却没重跑产物时，补基线链救不了，处置是在**主工作树重跑那个生成器**、脚本与产物同一笔提交，
|
||||
再重跑 `done`。另注意 `pre-commit run --all-files` 只跑 pre-commit stage，个别只在 commit-msg / 手工阶段跑的守卫不在此列
|
||||
（口径见 `scripts/ci_local.py` 头部说明）。
|
||||
- **⚠ 新建工作树从未构建过 → 体积类门禁必然红**（2026-10-25 实测）：`.map` 是每棵树各自的
|
||||
构建产物、不入版本库，所以 `new` 出来的空间里 `mem-numbers` / `mem-budget` / `ci_local.py`
|
||||
的体积门禁步都拿不到事实源，报 `[FAIL] 找不到 .map 事实源`（脚本提示已写明原因，不是代码缺陷）。
|
||||
同理 `done` 的重生成步骤会 `[skip] 未找到 .map，跳过内存快照同步（需先 @build）`。
|
||||
**处置**：新空间第一次提交前先 `@build` 一次（`build` 锁自动排队，与别的树串行）。与上一条
|
||||
的区别要分清：上一条是「有 `.map` 但是旧的」，本条是「根本没有 `.map`」，处置动作不同。
|
||||
- **⚠ 增量构建可能不重链 → `.map` 数字瞬态不一致**（2026-10-12 实测）：
|
||||
`@build` 若判定无需重链，`.map` 保持旧值，此时 `--write` 生成的快照是**瞬态值**
|
||||
（实测同一份源码两次读到 223,560 与 223,724，差 164 B）。**以主工作树（集成点）
|
||||
的 `.map` 为准**；改完 RAM 相关代码后确认重链再刷新快照。
|
||||
- **`ram_baseline.py` 的 help 串里有未转义的 `%`**（2026-10-25 实测：某些直调姿势会渲染 argparse help 并崩）——
|
||||
查用法读脚本头部 docstring，别靠 `--help`；修脚本本身属 `mem-budget` skill 的范围。
|
||||
- **合并冲突常落在「生成物」上**：`docs/内存管理/RAM使用分析与优化方案.md`（mem-numbers
|
||||
快照）在双方都改过时必冲突，且**两边都不能直接选**（各自基于不同基线）——
|
||||
正确做法是解冲突后用**合并后的实际构建**重新生成，不要挑一侧。
|
||||
- **并集合并残留**：双方都改过的文件（尤其 `.gitignore`）会被 git 自动并成**并集**，
|
||||
可能留下指向已删目录的死规则或重复条目。脚本会自动报「双方都改过」的文件清单 +
|
||||
连续重复行；**权威判据是 base / 两个 tip 三方对比**（`git show <ref>:<file>` 逐项 `grep -F`），
|
||||
别用 `tail -N` 目测。
|
||||
- **⚠ 别用 heredoc 打补丁改门禁脚本造探针**（2026-10-27 实测三连败，白烧一整轮）：heredoc 里的 python
|
||||
把门禁脚本改坏——`patched 3` 之后 `PROBE_RC=1`、`SyntaxError: unterminated string literal (detected at
|
||||
line 882)`，而它**正是被测对象**，改完的数不可信；另一处 `replace('\', '/')`（想把 Windows 反斜杠换成正斜杠）里的反斜杠被多层引号吞掉
|
||||
→ `SyntaxError (detected at line 16)`。**正解**：探针落成**独立 `.py` 文件**（写文件的工具，UTF-8 无 BOM）
|
||||
再 `"$PY" probe.py`；非用 heredoc 不可就用单引号定界 `<<'PY'`（防变量展开），且**路径一律 `as_posix()`、
|
||||
一个反斜杠都不写**——反斜杠字面量要穿「JS 模板串 → bash → shell 引号 → python」四层，必被吞。
|
||||
E 节那两段扫描脚本同理：**落成 `ci-artifacts/*.py` 再跑**（该目录已被忽略，不会污染第 5 步复验用的脏行数）。
|
||||
- **取门禁数字：import 门禁模块，别猜输出、别打补丁**（2026-10-27；grep 源码 / 手抄正则 / 解析 stdout 三种姿势
|
||||
都拿不到可复核的数，换成这句立刻拿到）：先读门禁脚本的 `main()`（直读末尾那几十行）看它怎么装配检查器，
|
||||
把**那几行照抄**进探针——`sys.path.insert(0, 'scripts')` → `import check_ids as ci` →
|
||||
`ci.load_json(ci.REGISTRY_FILE, 'reg')` + `ci.load_json(ci.ALIASES_FILE, 'alias')` →
|
||||
`ck = ci.Checker(reg, al, verbose=False)` → `ck.run()` → `print(ck.stats)`。别猜键名：先
|
||||
`print(sorted(ck.stats))` 列出全量计数项，再按精确键取数（顺带 `git diff` 确认门禁脚本自己**没被改过**）。
|
||||
- **别把「不可判定」当成一个数**（2026-10-27）：`id-check` 有两种口径——检查器自己算的**硬不可判定**实测只有
|
||||
**2** 处，而门禁红线（`scripts/archive/id_gate/id_registry.json` 的 `undecidable_total_ceiling`）量的是**派生值**
|
||||
`refs_total - decidable`（实测 8,744 - 7,582 = **1,162**，拆开 = `skip_bare_unmanaged` 834 +
|
||||
`noise_allowed` 326 + 硬不可判定 2，**三数精确闭合**）。所以**带属主登记处的族（TC-XXX 这类）加多少引用都算
|
||||
「可判定」、一点不吃这条余量**，真正吃余量的是**裸形字母+数字**字面量；反过来「把可判定引用改写成散文」才是
|
||||
**稀释比值**的动作，那才是绝对数红线要防的。口径混用会当场给整条道下错指令（本次就下错过、量完立刻撤回）。
|
||||
- **队友的自查结论要复核，小心它测的是错变量**（2026-10-27）：log 道做过受控实验、结论是「我们没推高这个数」——
|
||||
他们改的是 TC 号、盯的是 `skip_bare_unmanaged`，那个组合当然不动；而 +16 走的是另一条路（新增裸形 「字母 T 累进数字 4」）。
|
||||
定责用 D 节：逐文件注入 + HEAD/在飞两版同一计数器相减 + 对新增行 grep；闭合后 +16 = 16 处裸形 「字母 T 累进数字 4」，
|
||||
**推翻**了自查结论。口头自查与 `--note` 都不是证据，**可复核的差分数字才是**。
|
||||
- **`.workbuddy-ai/` 刻意不共享**：记忆不随任务分叉，也不给联接递归删除的机会。
|
||||
任务工作树自己的记忆由 `done` / `abort` 在清场前归并回主工作树。⚠ **手工回收（E 节）没有这一步归并**：
|
||||
拆之前顺手 `ls <tree>/.workbuddy-ai/` 看一眼，有内容就一并备份进 `ci-artifacts/wt-leftover-backup/`。
|
||||
- **`--lean` 只省磁盘不省时间**：实测全量 smudge 7.25 s / 83 MB，跳过 smudge 7.05 s / 45 MB，
|
||||
两者工作区都干净。默认走全量（参考图可用），磁盘紧张时才用 `--lean`。
|
||||
- **锁不绑定进程存活**：`lock acquire` 本身是短命进程，而真正用资源的烧录/构建在别的进程里跑。
|
||||
所以判「陈旧」只看**时效**（该锁的 TTL）加显式 `--force`；pid 仅作排障记录。
|
||||
同任务重复 acquire 是幂等的（不会把自己锁死）。
|
||||
- **TTL 按锁分设**（2026-10-12）：`build` = **1h**、`bench` = **6h**（`LOCK_TTL_HOURS`）。
|
||||
口径是「兜底窗口应与操作真实时长同量级」——编译是秒~分钟级，6h 的兜底太钝；
|
||||
bench 是会话级（flash→`@test`→探针），才配得上小时级。持有者还可用
|
||||
`lock acquire ... --ttl <小时>` **自报**更精确的窗口（`keil_build.py` 即按其 `--timeout` 自报）。
|
||||
- **陈旧锁自动接管**：超过该锁 TTL 未释放即视为陈旧，下次 `acquire` 会接管并提示；
|
||||
未到 TTL 的活锁需 `--force`。`done` 的收口前置也会**自动释放陈旧锁**（不再硬失败），但
|
||||
**未到 TTL 的活锁会把 `done` 挡在前置检查**（B 节第 8 步）。
|
||||
- **`build` 锁不必手工持**（2026-10-12 起）：`@build`（`keil_build.py`）**自持自释**——
|
||||
进入 acquire、`finally` 无条件 release，所以"Agent 忘了 release、锁一直挂到 TTL"这条在构建路径上已消除。
|
||||
`done` 的门禁自己持锁并给子进程设 `DTU_LOCK_HELD=build` 告知跳过（新旧脚本都兼容）。
|
||||
**`bench` 锁仍须 Agent 手工持**（会话作用域：跨烧录→`@test`→探针，见 `keil-build` SKILL.md）。
|
||||
@@ -0,0 +1,203 @@
|
||||
### E. 回收**非登记**工作树（`$TW list` 为空 / detached HEAD / 树里有在飞或未跟踪内容）
|
||||
|
||||
**这类树的判定特征**（命中任意一条就适用本节）：`git worktree list` 里有它、但 `_wt/.state/<ID>.json` 台账不存在；
|
||||
HEAD 是 detached（`git rev-parse --abbrev-ref HEAD` 打 `HEAD`）；或树里的改动不属于本会话（别的会话留下的未提交 /
|
||||
未跟踪文件）。典型来源：D 节的 `--detach` 净室、`new` 之后被手工删目录只剩台账的残骸、别人手工 `git worktree add` 建的分析树
|
||||
（2026-10-28 实测一次回收 3 棵：`verify-task16` / `verify-batch` / `und-attr`，各 89 MB，全部无台账 + detached）。
|
||||
|
||||
**为什么 `done` / `abort` 在这里整体不适用**（铁律 9）：两条子命令的前置都是 `load_state()`，无台账 →
|
||||
`前置/环境错误：任务 <ID> 不存在（缺台账 …json）`（exit 2）当场停住、什么也不会发生；而**假如有**一份残留台账，
|
||||
`abort --force` 会拿台账的 `path` 直接 `git worktree remove` —— **绕过下面第 1~4 步的全部内容保全**，把别的会话的唯一版本一次删光；
|
||||
`done` 则会去找那条（多半已不存在的）`task/` 分支做合并。另：本路径没有「合并」这一步，所以 `done` 的并集合并残留审计
|
||||
在这里不发生，也没有三方对比可依据 —— **唯一性只由第 2 步的内容分桶给出**。回收只能手工走本节第 1~5 步 + 第 6 步清台账。
|
||||
|
||||
1. **建全景（全程只读）**：先看 `git worktree list` 的全集，再**逐棵**记三件事（脏行数含未跟踪 / 树顶提交 / 有无分支）
|
||||
加一条台账判定，同时存下主树的拆前基线清单：
|
||||
|
||||
@T3@bash
|
||||
MAIN="D:/Code/DTU Code/STM32F4-Base"; WTROOT="$MAIN/../_wt"
|
||||
git -c core.quotePath=false worktree list # 全集：登记树 + 非登记树都在这份里
|
||||
MAIN_SHA=$(git -C "$MAIN" rev-parse --short HEAD) # 下面所有比对都以这一版为主线尺子
|
||||
mkdir -p ci-artifacts
|
||||
git -C "$MAIN" status --porcelain -uall > ci-artifacts/wt-main-before.txt # 拆前主树基线（第 5 步逐行比）
|
||||
wc -l < ci-artifacts/wt-main-before.txt # 记下行数（实测 0）
|
||||
for t in "$WTROOT"/*/; do
|
||||
echo "--- $t"
|
||||
git -c core.quotePath=false -C "$t" status --porcelain -uall | wc -l # 脏 + 未跟踪行数
|
||||
git -c core.quotePath=false -C "$t" log --oneline -1 # 树顶提交
|
||||
git -C "$t" rev-parse --abbrev-ref HEAD # 打 HEAD = detached，压根没分支可 done
|
||||
ls "$WTROOT/.state/$(basename "$t").json" 2>/dev/null || echo "NO-LEDGER" # 台账位置随 DTU_WT_ROOT
|
||||
done
|
||||
@T3@
|
||||
|
||||
- **`-uall` 不是可选**：默认 `status --porcelain` 会把未跟踪目录折叠成一行 `dir/`，`-uall` 才展开到文件级；少了它
|
||||
第 2 步的分桶就漏项（实测 `und-attr` 唯一那份就是未跟踪 `?? scripts/check_nested_comment.py`）。
|
||||
- 路径含空格（本项目 `DTU Code`）→ 变量整体加引号；`core.quotePath=false` 让中文路径原样输出，便于逐行核对。
|
||||
- 判定「是不是登记树」看两样：**台账在不在 + HEAD 是否 detached**。两者都指「非登记」→ 从这里开始**禁止**
|
||||
`done` / `abort`（见本节开头），继续第 2 步。
|
||||
2. **逐文件与主线 HEAD 比内容并分三桶**：`IN-MAINLINE`（内容等价，拆 = 零损失）/ `UNIQUE-UNMERGED`（主线没有这份
|
||||
内容，拆 = 丢）/ `OLDER-DRAFT`（同路径主线已有更新版本）。落成独立只读探针跑（别用 heredoc 现写现改，
|
||||
见陷阱「别用 heredoc 打补丁造探针」）：
|
||||
|
||||
@T3@python
|
||||
# ci-artifacts/wt_bucket_scan.py — 只读：逐文件与主线工作区/HEAD 比对，三桶归类
|
||||
import os, subprocess, tempfile
|
||||
MAIN = r"D:\Code\DTU Code\STM32F4-Base"
|
||||
WTROOT = os.path.join(os.path.dirname(MAIN), "_wt")
|
||||
TREES = ["verify-task16", "verify-batch", "und-attr"] # ← 第 1 步全景里挑出的非登记树
|
||||
SKIP_TOP = {".venv", "MDK-ARM", ".git", "ci-artifacts"} # 联接 / 构建产物 / 忽略区，按项目调
|
||||
def git(*a):
|
||||
return subprocess.run(("git", "-c", "core.quotePath=false", "-C", MAIN) + a,
|
||||
capture_output=True, text=True, errors="replace")
|
||||
def bucket(rel, tree):
|
||||
p = os.path.join(tree, rel)
|
||||
if not os.path.exists(p):
|
||||
return "OTHER", "工作树里已不存在（多为已 staged 删除）"
|
||||
tf = tempfile.NamedTemporaryFile(delete=False)
|
||||
tf.write(open(p, "rb").read()); tf.close()
|
||||
# 1) 与主线工作区（= 当前 HEAD 的检出内容）逐字节比
|
||||
if git("diff", "--no-index", "--quiet", tf.name, rel).returncode == 0:
|
||||
os.unlink(tf.name); return "IN-MAINLINE", "与主线 HEAD 逐字节相同"
|
||||
# 2) 与主线历史各版比：内容等价于某个旧 commit → 只是主线又往前走了
|
||||
hist = [x.strip() for x in git("log", "--format=%H", "HEAD", "--", rel).stdout.splitlines()]
|
||||
for sha in hist[1:]:
|
||||
old = git("show", f"{sha}:{rel}")
|
||||
if old.returncode == 0 and old.stdout == open(p, encoding="utf-8", errors="replace").read():
|
||||
os.unlink(tf.name); return "IN-MAINLINE", f"内容等价于主线历史版 {sha[:8]}"
|
||||
# 3) 主线从没这条路径 → 唯一；否则同路径主线有更新版 → 更旧草稿（再用 blob diff 定性方向）
|
||||
os.unlink(tf.name)
|
||||
if not hist:
|
||||
return "UNIQUE-UNMERGED", "主线 HEAD 与历史都没有此路径"
|
||||
return "OLDER-DRAFT", "同路径主线有更新版本（用 diff --stat <HEAD> -- <f> 定性）"
|
||||
for name in TREES:
|
||||
tree = os.path.join(WTROOT, name)
|
||||
lines = subprocess.run(("git", "-c", "core.quotePath=false", "-C", tree,
|
||||
"status", "--porcelain", "-uall"),
|
||||
capture_output=True, text=True, errors="replace").stdout.splitlines()
|
||||
tally = {}
|
||||
for line in lines:
|
||||
rel = line[3:].split(" -> ")[-1].strip('"') # 兼容 ?? / M / A / R 的箭头形态
|
||||
if rel.split("/")[0] in SKIP_TOP:
|
||||
continue
|
||||
b, why = bucket(rel, tree)
|
||||
tally.setdefault(b, []).append((rel, why))
|
||||
g = lambda k: len(tally.get(k, []))
|
||||
print(f"== {name}: IN-MAINLINE={g('IN-MAINLINE')} UNIQUE-UNMERGED={g('UNIQUE-UNMERGED')} "
|
||||
f"OLDER-DRAFT={g('OLDER-DRAFT')} OTHER={g('OTHER')}")
|
||||
for b in ("UNIQUE-UNMERGED", "OLDER-DRAFT", "OTHER"):
|
||||
for rel, why in tally.get(b, []):
|
||||
print(f" {b}: {rel} # {why}")
|
||||
@T3@
|
||||
|
||||
报告里必须**逐桶给计数 + 判定证据**（实测：`verify-task16` IN-MAINLINE=6 / UNIQUE=0；`verify-batch` IN-MAINLINE=35 /
|
||||
UNIQUE=1；`und-attr` IN-MAINLINE=0 / UNIQUE=1）。两个非空桶再各钉一条命令把证据坐实：
|
||||
|
||||
@T3@bash
|
||||
# 「唯一未合并」是真更新还是更旧草稿？blob 级 diff + 逐行看方向
|
||||
git -c core.quotePath=false -C "$MAIN" diff --stat "$MAIN_SHA" -- simulator/tests/README.md
|
||||
diff <(git -C "$MAIN" show "$MAIN_SHA":simulator/tests/README.md) "$WTROOT/verify-batch/simulator/tests/README.md"
|
||||
# 「树顶提交要不要保」只看一件事：是否已并入 HEAD。别拿「目录很久没动」当判据
|
||||
for c in 77779d49 1d4b6a17; do
|
||||
git -C "$MAIN" merge-base --is-ancestor "$c" HEAD && echo "$c MERGED" || echo "$c NOT-merged"
|
||||
done
|
||||
@T3@
|
||||
|
||||
实测：那份 `simulator/tests/README.md` 树内写「27 页 × 3200 B」、主线 HEAD 已是「60 张 × 3200 B」→ **更旧草稿**（被取代的
|
||||
早先版本），不是未合并成果；`bench-21-77779d49` / `bench-23-1d4b6a17` 两棵 `merge-base --is-ancestor` 判 **MERGED** 且脏数 = 0
|
||||
→ **保留不动**（不属本节，等属主自己收，报告里点名说清为什么留）。
|
||||
**回收判据不是「看着旧」**：唯一内容如果没被提交过，`git log` 里根本看不见它；反过来「提交已 MERGED」也不等于可以拆——
|
||||
还得看未跟踪那一层。`UNIQUE-UNMERGED` 非空又确实要留 → 它进第 4 步的备份，**不许靠 `--force` 顺手带走**。
|
||||
3. **拆前扫联接 / reparse point（物理安全性 = 铁律 5 的可执行判据）**。存成 `ci-artifacts/wt_junction_scan.py` 再跑：
|
||||
|
||||
@T3@python
|
||||
# 只读预扫：一个路径是不是 reparse point（Windows 目录联接在这里现形）；发现即停止深入，绝不 walk 进联接
|
||||
import os, ctypes
|
||||
FILE_ATTRIBUTE_REPARSE_POINT = 0x400
|
||||
GA = ctypes.windll.kernel32.GetFileAttributesW
|
||||
def is_reparse(p):
|
||||
a = GA(p)
|
||||
return a != -1 and bool(a & FILE_ATTRIBUTE_REPARSE_POINT)
|
||||
for name in ["verify-task16", "verify-batch", "und-attr", "bench-21-77779d49", "bench-23-1d4b6a17"]:
|
||||
top = os.path.join(r"D:\Code\DTU Code\_wt", name)
|
||||
hits, entries = [], 0
|
||||
for root, ds, fs in os.walk(top):
|
||||
bad = [d for d in ds if is_reparse(os.path.join(root, d))]
|
||||
if bad:
|
||||
hits += [os.path.join(root, d) + "/" for d in bad]
|
||||
ds[:] = [] # 有联接就不再深入：防转进主树 .venv 把别人整棵树数一遍
|
||||
hits += [os.path.join(root, f) for f in fs if is_reparse(os.path.join(root, f))]
|
||||
entries += len(ds) + len(fs)
|
||||
print(f"== {name} scanned entries={entries}")
|
||||
print(" REPARSE: none → 可直接 git worktree remove --force"
|
||||
if not hits else " REPARSE:\n " + "
|
||||
".join(hits))
|
||||
@T3@
|
||||
|
||||
实测输出 `== verify-task16 ... REPARSE: none`（每棵的体积 / 条目数 + 零联接就是证据），而 `bench-*` 两棵各挂一个 `.venv`
|
||||
联接 → 判 **KEEP**（本节不拆它们；将来真要拆，先 `rmdir` 摘掉联接再 remove）。
|
||||
**判据是「扫出来一个都没有」，不是「我记得没建过联接」**：`new --no-bootstrap` 的树、别的手工 `mklink /J` 的树都可能带着指向主树的联接。
|
||||
摘联接用 `rmdir`（只删联接本身；**不是** `rd /s`，更不是 `rm -rf`——那会顺着联接删目标）。
|
||||
非 Windows 环境改用 `os.path.islink` / `find <tree> -type l`（本项目是 Windows + Keil 工具链，按上面这条走）。
|
||||
**到这里才算「拆前唯一性自检 + 物理安全预扫」齐**：`--force` 的安全前提 = 第 2 步 `UNIQUE-UNMERGED` 为 0
|
||||
（或剩下的已全部进第 4 步备份）**且**这里 `REPARSE: none`。
|
||||
4. **唯一内容先备份，再 `--force` 拆**。`UNIQUE-UNMERGED` 与需要留档的 `OLDER-DRAFT` 一律先备份进主树
|
||||
`ci-artifacts/wt-leftover-backup/`（`ci-artifacts/` 已被 `.gitignore` 忽略 → **备份不会改变主树脏行数**；仓库根不放一次性产物），
|
||||
**文件名 + 字节数必须打进输出**当证据：
|
||||
|
||||
@T3@bash
|
||||
BK="$MAIN/ci-artifacts/wt-leftover-backup"; mkdir -p "$BK"
|
||||
# 命名约定：<树名>__<原路径里的 / 换成 _>，反向可定位；台账备份统一后缀 .state-bak
|
||||
cp "$WTROOT/verify-batch/simulator/tests/README.md" "$BK/verify-batch__simulator_tests_README.md"
|
||||
cp "$WTROOT/und-attr/scripts/check_nested_comment.py" "$BK/und-attr__scripts_check_nested_comment.py"
|
||||
ls -l "$BK" # 实测：verify-batch__simulator_tests_README.md 1769 bytes / und-attr__scripts_check_nested_comment.py 14827 bytes
|
||||
for t in verify-task16 verify-batch und-attr; do
|
||||
git -C "$MAIN" worktree remove --force "$WTROOT/$t"; echo "$t remove_rc=$?" # 不接管道才读得到码（见「读输出」）
|
||||
done
|
||||
git -C "$MAIN" worktree prune # 顺带清 .git/worktrees 里的残籍
|
||||
@T3@
|
||||
|
||||
自检：**备份条目数 = 第 2 步里判「要留档」的条目数**，且每个都带字节数。这一步就是本节相对 D 第 4 步的增量——
|
||||
D 的前提是「净室里只有自己的拷贝」，本节的树里混着别人在飞的东西，`--force` 是一次不可逆删除，**先备份才谈得上安全**。
|
||||
5. **复验：主树一个字节没动 + 树确实没了**：
|
||||
|
||||
@T3@bash
|
||||
git -C "$MAIN" status --porcelain -uall > ci-artifacts/wt-main-after.txt
|
||||
wc -l < ci-artifacts/wt-main-before.txt; wc -l < ci-artifacts/wt-main-after.txt # 两个数必须相同（实测 0 → 0）
|
||||
diff ci-artifacts/wt-main-before.txt ci-artifacts/wt-main-after.txt # 空输出 = 逐行一致
|
||||
git -c core.quotePath=false -C "$MAIN" worktree list # 已拆路径逐条消失；主树与判「保留」的树原样在列
|
||||
@T3@
|
||||
|
||||
行数不同 = 备份或摘除碰到了主线（多半是备份写进了未被忽略的目录，或漏摘联接）→ 立刻定位，别报「回收完成」。
|
||||
第 2 步判「保留不动」的树还在 `worktree list` 里是**预期结果**，在报告里点名解释为什么留（附 `MERGED` 判据）。
|
||||
6. **顺手清悬挂台账**（branch / path 都已不存在的 `_wt/.state/<ID>.json`；它会让 `$TW list` 打出一行怪条目、并让下次
|
||||
`new` 同 ID 报「任务 <ID> 已存在」）。先给证据、后动手：
|
||||
|
||||
@T3@bash
|
||||
for j in "$WTROOT"/.state/*.json; do # 台账位置随 DTU_WT_ROOT
|
||||
id=$(basename "$j" .json)
|
||||
br=$("$PY" -c "import json,sys;print(json.load(open(sys.argv[1],encoding='utf-8')).get('branch',''))" "$j")
|
||||
pp=$("$PY" -c "import json,sys;print(json.load(open(sys.argv[1],encoding='utf-8')).get('path',''))" "$j")
|
||||
git -C "$MAIN" rev-parse --verify "$br" >/dev/null 2>&1 && b=branch-OK || b=branch-MISSING
|
||||
[ -d "$pp" ] && p=path-OK || p=path-MISSING
|
||||
echo "$id $b $p <- $j"
|
||||
done
|
||||
@T3@
|
||||
|
||||
实测这条判据打出的正是 `v5tool2 branch-MISSING path-MISSING`：`git rev-parse task/v5tool2-v11` 报
|
||||
`fatal: ambiguous argument 'task/v5tool2-v11': unknown revision ...`，台账 `path` 指的目录已无，`git worktree list` 里也没有这棵树。
|
||||
**三条齐（rev-parse fatal + path 目录不存在 + worktree list 无此树）才叫悬挂**；缺任何一条都回到第 1~2 步查是不是真有东西要保。
|
||||
然后**备份 → 删 → 复跑两条 list 复验**：
|
||||
|
||||
@T3@bash
|
||||
cp "$WTROOT/.state/v5tool2.json" "$BK/v5tool2.json.state-bak" && rm "$WTROOT/.state/v5tool2.json"
|
||||
"$PY" "$TW" list # 该条目消失（全空时打「（没有任务空间。用 new <ID> <slug> 建一个）」），echo RC=$? 应为 0
|
||||
"$PY" "$TW" lock status # build 空闲（TTL 1.0h）/ bench 空闲（TTL 6.0h）—— 证明清台账没牵连两把锁
|
||||
ls "$WTROOT"/.state/locks/ 2>/dev/null # 若该 ID 名下还有 .lock，先按 B 节释放，再删台账
|
||||
@T3@
|
||||
|
||||
- **必须 `cp` 先备份再 `rm`**：台账里存着 base / junctions / needs_bench / bench_pass，是真出纠纷时唯一的现场记录。
|
||||
- 悬挂条目按定义 `path` 已不存在 → 通常**不占** `MAX_CONCURRENT = 8` 名额（A 第 1 步的「活跃」判据要求 path 目录还在），
|
||||
但它把 `$TW list` 搅成怪输出、并永久挡住同 ID 复用；**path 还在的占位/残留台账才占名额**（早期为绕 B 节那个坑手写的占位台账就是这种）。两种都要清。
|
||||
- **仍不对这个 ID 跑 `done` / `abort`**：清场会拿台账里的死 `path` / 死 `branch` 去做 `git worktree remove` 和删分支
|
||||
（这正是 A 第 5 步说的「手工删目录留下的尾巴」，正解就是本步）。历史遗留的占位台账同理——活着时也别
|
||||
`done` / `abort`，用完直接删文件（来历与现状见 B 末条）。
|
||||
@@ -0,0 +1,44 @@
|
||||
## 验证
|
||||
|
||||
- `$TW list`：台账段条目数 = `ls _wt` 的目录数且 ≤ 8（`MAX_CONCURRENT`）；刚回收的任务与历史占位条目都不再出现
|
||||
（插件树另起一段，不参与这条计数）。
|
||||
- `$TW lock status`：`build 空闲（TTL 1.0h）` + `bench 空闲（TTL 6.0h）`——没有本会话留下的持有者。
|
||||
- `git log --oneline -3`：能看到 `merge: task/<ID>-<slug> 合入 <base>` 与其后的补基线提交；
|
||||
`git status --porcelain` 为空（补链改动已提交，才谈得上重跑 `done`）。
|
||||
- `ls _wt/.state/`：该 ID 的台账已无（清场最后一步 unlink）；重复 `done` 报「任务不存在」不必再追。
|
||||
- **E 节回收**：`git worktree list` 只剩主树 + 判「保留不动」的树（已拆路径逐条消失）；**拆前/拆后主树
|
||||
`git status --porcelain -uall` 行数相同且 `diff` 为空**（实测 0 → 0）；`ci-artifacts/wt-leftover-backup/` 里每个留档件都打印过
|
||||
文件名与字节数、条目数 = 分桶判「要留档」的条目数；每棵被拆的树都留有 `REPARSE: none` 预扫记录；全景输出里
|
||||
`UNIQUE-UNMERGED` 归零（或全部已备份）；保留树在报告里点名给出判据（`merge-base --is-ancestor` = MERGED）。
|
||||
- **E 第 6 步清悬挂台账**：该 json 已从 `_wt/.state/` 消失（`.state-bak` 在备份目录里）、`$TW list` 不再打出它、
|
||||
`$TW lock status` 两把锁仍空闲；全程未对该 ID 跑 `done` / `abort`。
|
||||
- **F 节桥接**：`plugin list` 的「联接」列按实际三态点名（`已联` / `缺 .venv` / `缺 SDL2` /
|
||||
`齐(实体SDL2)`——旧实现只取样 `.venv`，半联树会说谎）；**adopt/unadopt 前后主树 `.venv` 与树内文件都
|
||||
还在**；主线缺 SDL2 时 `adopt` 打 `[skip]` + 「还不能算就绪」而不打「现在可以跑」；`plugin adopt ".."`
|
||||
必须 exit 2；打印的 `pw:<name>` 与 `keil_build.py` 从 cwd 反推的名字逐字相同；`done <插件树名>` 只 exit 2。
|
||||
- **C2 主树被别的会话弄脏时的手工合并**：合并前打印过 `git merge-tree --write-tree` 的结果树 sha 且 `MT_RC=0`；
|
||||
合并用 `git merge --no-ff --no-edit -F ci-artifacts/merge-msg-<slug>.txt`（UTF-8 无 BOM）并写明绕开 `done` 的理由；
|
||||
外部文件合并前后的 `git hash-object` **逐字符相同**、`git diff --stat` 同一组数字、`status` 里仍是 `M`
|
||||
（没被提交也没被清掉；实测同为 `369380ca…`、2+/2−）；台账先 `cp` 成 `<ID>.json.state-bak` 再由 `$TW done`
|
||||
（或 E 节手工路径）摘联接拆树；收工前 `git worktree list` 只剩主树 + 别人的在飞树（点名保留）、
|
||||
`$TW lock status` 两把锁均空闲（`build 空闲（TTL 1.0h）` / `bench 空闲（TTL 6.0h）`）。
|
||||
- **G 节树内门禁**：`<tree>/ci-artifacts/` 先 `mkdir -p` 再写、事后 `ls` 得到真实文件（`cat` 读得到内容）；
|
||||
树内 `check_doc_links.py` 按**单文件**跑并打印「N 处 / 机器可判定百分比 / rc」（实测 161 处/98%/rc=0、16 处/88%/rc=0）；
|
||||
全库 `--all` 只在合并后的**主树**跑（实测 2,597 处 / 194 个文档 / rc=0）；若树内跑过 `--all` 且判红，报告里
|
||||
必须给得出「过滤 `simulator/SDL2` 后与主树同命令基线对比」这一步。
|
||||
- D 节归因：测量前后 `git -C "$MAIN" status --porcelain` **逐行一致**（主树全程只读）；
|
||||
`git worktree list` 里净室路径已消失；逐文件增量之和 **等于**观察到的涨幅（实测 +6+8+2 = +16），且每处增量
|
||||
都指到具体字面量类别（裸形 「字母 T 累进数字 4」）与属主；取数走 `import check_ids` 读 `ck.stats`，且门禁脚本自身 `git diff` 为空。
|
||||
- 补绿链的每一条都自己 `echo RC=$?` 看到 0，最后以重跑 `done` 打出的**清场日志**（`已摘除联接` /
|
||||
`已删除分支` / `完成（分支此前已合入）`）为成功判据，而不是 `tail` 出来的最后一行。
|
||||
- **树内提交 / 合并信息（G 节）**：`git log -1 --pretty=%B | grep -c '<被清退主题关键词>'` 打出 **0**（标题 + 正文 +
|
||||
合并信息三处都查过）；消息文件在 `ci-artifacts/`、UTF-8 无 BOM、CR=0、标题 ≤100、正文最长行 ≤80（实测 31/50、32/55）；
|
||||
自审发现消息统计算错是在**未推送**状态下 `--amend -F` 修掉的，历史里没有「更正」提交。
|
||||
- **文档改动体检（G 节）**：提交前打印过 `lines/bytes/BOM/CR/U+FFFD/三连续空行/行尾空格/末行 LF` 与表格列数一致性，
|
||||
并区分「本次改动引入 = 0」与「文件里既有的坏行」（实测两处历史坏表格与本次无关，只在报告里点名）。
|
||||
- **F 节分级与自持理由**：判 `simulator/SDL2` 为硬需求要给出 `simulator/CMakeLists.txt:12`（非 CACHE）+ 派生路径行号
|
||||
（:34/:70/:71/:180/:207）；判 `.venv` 为软需求要给出 `DTU_PRECOMMIT_PYTHON` 与 `ci_local.py` 五级解释器候选顺序；
|
||||
答「为什么不用插件」时报出插件包版本、文件与三个概念的 grep 命中数，并说明重叠只在 `git worktree add` 的开/收两个动作。
|
||||
- **改并行上限数字**：唯一事实源 = `task_worktree.py` 的 `MAX_CONCURRENT`（报错文案与 `new` 提示都 `.format()` 插值它，
|
||||
实测 `:764-766` / `:768-771`），其余全是引用同步；隔离小仓验证到「8 棵成功、第 9 棵不带 `--force` 被拒」，
|
||||
且没在真仓 `../_wt` 及其 `.state/` 留下验证树。
|
||||
Reference in New Issue
Block a user