wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
930 Commits 3 Branches 0 Tags
fe4f0db01c0fa8d77fcd0f22fbeea303fe69742e
Commit Graph

20 Commits

Author SHA1 Message Date
wandering1 4a4ad6bc5f chore(全仓): @build/@test 旧文档别名清退为技能调用名 
现状口径：/keil-build 与 /serial-boot-test 是 DSH 会话的技能调用名，
不是 shell 命令；「名 + 命令行参数」的命令形态改为可执行体
run_boot_test.py 的真实调用。

- AGENTS.md：别名说明重写为「技能调用名不是 shell 命令」，两条目改
  「编译（/keil-build）」「串口回归（/serial-boot-test）」
- keil-build / serial-boot-test 两 skill 调用名与示例同步；task-worktree
  方案文档去掉 @build/@test 惯例从句；@task 保留（不在点名范围）
- 123 文件现状陈述全改；台架捕获、变更记录/时间线、rename 映射输入
  等 41 行历史证据保留旧名
- gen_memory_svg.py 6 处措辞随改，3 张 SVG 产物同批重跑
- 顺手补并行方案同行漏网计数 51→52 钩子

验证：提交期快钩子对 123 文件实跑全 Passed；check_doc_links --all
rc=0（3038 处、无法判定 0）；check_mermaid --all rc=0；YAML 解析 52
钩子不变；skill-size rc=0；py_compile 全过；字节卫生零漂移。
 2026-10-30 13:03:12 +08:00
wandering1 2be49dc9dd docs(skills): 明确 @build/@test/@task 为文档别名并新增 precheck/postmerge 命令
CI / 静态门禁 (pre-commit) (push) Failing after 3m45s
Details
CI / 主机侧单测 (MSVC) (push) Failing after 43s
Details 
AGENTS.md「构建与验证」新增总口径：@build / @test / @task 都是本仓库的
文档别名、不是 shell 命令（2026-10-30 实测：bash 敲 @task / @build 即
command not found，dsh task 被解析成 profile 名报错）；`=` 后的命令行
才是可执行形态，DSH 会话显式调用为 /keil-build、/serial-boot-test、
/task-worktree。

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

实测：precheck 对坏消息文件抓到 CRLF、行长 95>80、禁词×3（rc=1）；
postmerge 端到端「凭证同码新鲜→跳链→doc --all 绿（2967 章节引用 /
214 文档）→列 dirty 文件」rc=0；check_skill_size.py 与 py_compile 通过；
frontmatter 改动后 DSH 已用新值真加载过一轮。无 .c/.h 改动，不涉及体积。
 2026-10-30 10:25:05 +08:00
wandering1 2b478588a7 docs(task-worktree skill): 补「只改注释也刷红体积同码凭证」实测坑 
done testdoc 撞上的一次新型红：size-gate 的判据是索引 blob 指纹，不是体积数字。
全库路径同步顺带改了 20 个 .c/.h 的注释，Program Size 逐项没变，凭证照样报
「不同码」。处置比 C 节补绿链短：合并后 done 自己那次 @build 已 0 错 0 警，
只需 ram_baseline.py --update 重写 scripts/size_attestation.json，
不 --write 动内存受管快照（数字没变就去改受管区＝给别的在飞分支造冲突面）。

连带登记第二个坑：done 在「分支已合入」的路径上于门禁之前就 return，
补完凭证重跑不会替你复绿，落主干后的全量证据要自己跑 ci_local.py
（实测 47 runner / 3896 断言全绿）与主树 check_doc_links.py --all
（实测 215 个文档 / 2993 处章节引用 rc=0）。

只加 reference/pitfalls.md 一条，SKILL.md 正文一字未动（受插件写侧
65536 字节上限，深规程一律进 reference/）。
 2026-10-30 09:14:49 +08:00
wandering1 ecf9d3ad3d docs(task-worktree skill): 修 @T3@ 围栏腐坏，正文瘦身并把细节外置 reference/ 
围栏腐坏是真 bug：@T3@ 是被误提交进仓的代码围栏占位符，Markdown 渲染出
来就是一行 @T3@ 加裸命令。git log -S 定位：842d711e（2026-10-28）
SKILL.md 还有 18 个真三反引号围栏行、0 个占位符；21c68521（2026-10-29
插件桥接那笔）起变 0 围栏 / 34 个占位符。全仓只有本技能 6 个文件有此
病，draw-diagram / keil-build / ui-verify 等都用真围栏。本轮七个文件
占位符清零、围栏全部成对。

信息密度：SKILL.md 28,139 → 23,087 B（−18%，占插件写侧上限 65536 的
35%，给自进化留头量）。同一句外置理由在 C2/D/E/F/G/陷阱/验证 重复 7 次
→ 0；frontmatter 与 F 节写了两遍的插件桥接说明收进 F 节；「这不是免费
的」「挡给你看的保护」这类修辞删掉。删掉的细节全部落进对应 reference
篇——skill-size 钩子会校验指针不悬空：现 26 处链接 / 8 篇目标 / 悬空 0，
每篇都有入口。

锚点未重排：节号 A–G/C2、各节步骤号、铁律编号被 reference/ 反向引用
（铁律 3/5/7/9 与 A 第 1、5 步，C 第 5~7 步，E 第 1~6 步均结构性存在）。
只在 SKILL.md 出现的 PIPESTATUS 教训保留（reference/ 里没有，删了就丢）。

门禁：check_skill_size.py rc=0（17 个 SKILL.md 全在写侧上限内、无悬空
指针）；七文件均无 BOM / CR / U+FFFD、单个尾换行。
 2026-10-30 00:31:36 +08:00
wandering1 f08b12a46c 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() 逐个复载确认加载的是拆分版。
 2026-10-29 15:03:12 +08:00
wandering1 8cab390aa7 chore(task-worktree): 活跃任务上限 3 提到 8——磁盘不是依据，锁排队才是（引用面 15 处同步） 
唯一事实源是脚本常量 MAX_CONCURRENT（task_worktree.py:30），报错文案与 new 的插件树提示都插值它；
其余全是引用面同步：SKILL.md 12 行（含 frontmatter 的 description 与 whenToUse——它会进技能目录）、
方案文档表格行 + 依据段重写、启动日志原子性复验流程 1 行去掉数字。

依据段按今天的实测重写，不再拿磁盘当理由：一棵纯净检出 84.0 MiB / 2857 个受控文件（docs 独占
46 MiB），.venv 与 simulator/SDL2 走目录联接共享、不随树复制，D 盘余 1.4 TB → 8 棵全开最坏约
3.2 GB（每棵再叠一次构建产物：Keil 中间件 289 MB + 模拟器 35 MB）。真正随并行数上涨的是排队：
build 锁 TTL 1.0h、bench 锁 TTL 6.0h 分别串行化 @build 与 @test，done 的合并也必须串行——8 棵是
8 个空间，仍是一套 Keil 授权 + 一块板。

扫描按全形态跑（上限 3 / 最多 3 / 第 4 棵 / MAX_CONCURRENT = 3 / 硬上限 3 / 名额），整行打印后
另抓到两处只按数字搜不到的形态：whenToUse 里的「白占 3 个名额之一」、「确实要同时开第 4 棵」
（上限变了它必须跟着变第 9 棵，否则自相矛盾）。

冻结不改并写明类别：带日期戳的历史测量（2026-10-28 一次回收 3 棵、各 89 MB）、用户原话引语、
列表与步骤序号。「83 MB」是当时 du 口径、与本次内容字节和 84.0 MiB 同数不同义 → 只补口径注并
指回方案 §4，不合并成同一个数；方案 §2 的「对象库 234 MB」保留——今天的 294 MB 含待两周宽限期
过期的不可达对象，不把临时态钉进文档。

本轮我自己写错并已改掉：新段落引用了不存在的子命令 lock list，真命令是 lock status（全仓零残留）。

验证：上限生效用 %TEMP% 隔离小仓实测（脚本按同深度拷贝，因 REPO_ROOT 由 __file__ 反推）——前 8 棵
全成功，第 9 棵 exit 2 且文案为「已有 8 个活跃任务（上限 8）」，--force 照旧放行，list 9 行；真仓
零副作用（worktree list 仍 1 条、同级 _wt 无新建目录、无 t0* 残留）。门禁：doc-links --all
--sections-strict RC=0（2601 处、无法判定 0）、编号门禁 [OK]、py_compile RC=0、四文件无 BOM、
纯 LF、无 U+FFFD、无行尾空格。改动不落体积门禁指纹面，不需要 @build。
 2026-10-29 08:44:03 +08:00
wandering1 1576d7b709 fix(task-worktree): 联接列改三态点名——半联树不再被说成已联，adopt 没补齐不许报就绪 
同一个谎有两处，根因是「联没联上」有两套判定：列表只取样 JUNCTION_SPECS 首项
（.venv），而 adopt 填两条。于是「有 .venv、缺 simulator/SDL2」的半联树被报成已联，
adopt 遇主线缺 SDL2 走 skip、联接失败走 warn，回来照样打「现在可以跑」——宣布就绪。

改法是把判定收成一处：
- 新增 junction_states() 三态（link / real 实体内容 / absent 真缺）与 junction_label()，
  plugin_trees() 改读三态；adopt_junctions() 也改读同一函数，消除两处逻辑分叉。
- 列表按缺的那一样分别说后果：缺 .venv 会**静默**落到机器级解释器（无 fontTools，
  即 generated-fresh 假红的老根因）；缺 simulator/SDL2 是模拟器当场报错（CMakeLists.txt
  的 SDL2_DIR 是裸 set，没有环境变量逃生口）。实体目录单列齐(实体SDL2)，不算共享。
- adopt 补完复算一次，仍缺就打「还不能算就绪」，不再打「现在可以跑」；锁归属与
  锁命令照常打印。
- SKILL.md 同步四处措辞，并把「adopt 之前跑不了 Python」这条不准确的说法换成上面
  两种真实失败方式（一条是静默错解释器、一条是响亮报错）。

验证：scratch 仓 16 条断言全 PASS（全联 / 只摘 SDL2 那条 → 缺 SDL2 且不得再出现已联 /
实体目录不被覆盖 / unadopt 只摘联接 / 主线缺 SDL2 时 skip + 不报就绪 / 已联的 .venv
不误报 / 两样都缺 → 缺 .venv+SDL2），同一半联态上新旧对照 = 缺 SDL2 vs 已联。
py_compile 通过；doc-links --all --sections-strict 与编号门禁绿；两文件无 BOM、无
U+FFFD、纯 LF、无行尾空格。改动只落在 .dsh/，不进体积门禁指纹面，也不需要 @build。
 2026-10-29 08:18:49 +08:00
wandering1 21c68521ff feat(task-worktree): 桥接 DSH worktree 插件——补共享联接、锁归属 pw:<name>、修释放不掉 
诉求最初是升级 dsh-task-worktree：实测已装 0.4.6 = npm dist-tags.latest，无需升级；
真正的缺口是本仓 skill 看不见插件建的树（.dsh-worktrees/），故按用户追加指令把两套
系统接起来。回收方向刻意不打通：本 skill 永不删插件的树。

脚本 task_worktree.py：新增 plugin 子命令 list/adopt/unadopt，事实源是 git worktree
list（不是插件 manifest，免得被绕过）；adopt 只补缺失的 .venv 与 simulator/SDL2
联接，已有联接跳过、实体目录绝不碰；锁归属用 pw:<name> 前缀；new 顺带提示另有 N 棵
插件树、不占活跃上限 3。
一并修一处真 bug：lock release --bench-pass 在任务无台账时先 EnvError 退出、锁释放
不掉，导致每个任务的 done 收口连坐失败；现在改为警告后仍然释放。

keil-build：default_lock_task() 增加 .dsh-worktrees/ 反推分支，插件树内的构建归属
pw:<name> 而不是兜底的 build-cli（主树行为未变，本次 @build 实测仍走 build-cli）。

.gitignore 预先忽略 .dsh-worktrees/，让插件的 ensureIgnored() 找到同一字面量、不再
改写这份受控文件。check_doc_links / check_layer_deps / gen_refgraph 三处扫描面同步
排除：仓里再放一份仓会让 doc-links 假红、并让生成的配图字节漂移到 generated-fresh。

文档：并行任务工作树方案新增 §3.4 两套系统边界对照；SKILL.md 加 §F 共存一节，同时把
§B 从 53 行压到 29 行（净 +39，用户此前在飞的改写已 rebase 保留、未被覆盖）。

验证：@build 0 错误 0 警告；scripts/ci_local.py 48 根提交期钩子与 gitlint 全绿；
check_doc_links --all --sections-strict 通过（2596 章节引用、无法判定 0）；id-check-new
通过；改动文件字节体检无 BOM、CRLF 与 U+FFFD。桥接行为在临时 scratch 仓端到端跑过
（adopt 建两个 reparse、unadopt 只摘联接、pw 锁取放、缺台账也能释放、越界 name 退 2）。
 2026-10-29 07:50:05 +08:00
wandering1 842d711ed6 refactor(编号): 测试验证层级去号——CI job / 门禁输出 / 命令行旗标换语义名 + ASCII 段名 
用户裁定「我不想看到编号」。测试验证层级这一族的整族清退分三道并行：本笔是**代码与 CI 道**
（CI 步骤与门禁输出面），代码注释面另走、文档面由文档道走。

口径（旧 → 语义名 → ASCII 段名，段名只进日志/旗标/job id/文件名）：
  L0 静态门禁 static ｜ L0a 钩子解释器预检 preflight ｜ L0b 提交信息门禁 commitmsg
  L0c 体积门禁 size ｜ L0.5 主机侧纯逻辑单测 host-unit ｜ L0.5c 覆盖率 coverage

- scripts/ci_local.py 43 站点：段标题与 [SUMMARY] 标签改 ASCII 段名（static: /
  host-unit:），函数 run_l0/run_l05 → run_static_gates/run_host_unit_tests，
  收尾「已跑：」列表用段名。旗标改 --static-only / --host-unit-only，**旧旗标
  --l0-only / --l05-only 保留为 argparse 别名**（肌肉记忆与既有脚本片段不断档，
  实测 --help 两名列出）。
- .gitea/workflows/ci.yml 42 站点：job id l0-gates → static-gates、
  l05-host-unit-tests → host-unit-tests；步骤名与 step-summary 标题改语义名；
  日志名 l0-pre-commit.log → static-pre-commit.log、l05-<模块>.log →
  host-unit-<模块>.log；::error::/::notice:: 文案同步。yaml.safe_load 核过
  两个 job id 与步骤名。
  host-unit-tests；步骤名与 step-summary 标题改语义名；日志名 l0-pre-commit.log →
  static-pre-commit.log、l05-<模块>.log → host-unit-<模块>.log；::error::/::notice::
  文案同步。yaml.safe_load 核过两个 job id 与步骤名。
- 门禁脚本 18 站点：check_registration（登记簿理由串 7）、check_test_coverage 5、
  README 8、check_generated_fresh 2、ram_baseline 2、check_size_gate 1、
  ci_find_python.ps1 2、ci_runner_bootstrap.ps1 2、.pre-commit-config.yaml 2、
  requirements.txt 1（保持纯 ASCII）。
- skills 7 站点：task-worktree（含 [SUMMARY] 样例两行）、mem-budget、ui-verify、
  task_worktree.py 的实跑标签。
- AGENTS.md 3 站点：CI 段「只跑静态门禁 + 主机侧纯逻辑单测」、自查命令段、
  「2026-10-11 静态门禁全灭」事件名。
- 归档：编号治理历史.md 新增 §10 换算表 + **撞族警示**（同形 L0/L1/L2/L3 还属 UI 设计
  令牌层 / UI 菜单层级 / 采集链 / 链路时延段 / CubeMX 三层 / 硬件位号与 FTP 应答字面量
  等六个族，其中 6 处在字符串字面量里，改了就是改行为——故全程只按行内置换、先判族）。
- docs/产品需求 §7.4 测试分层表：去号 + 顺带修掉上一批**错族替换疤**（该表 L1/L2 行曾被
  采集链层名「语义取数与有效性 / 全周傅氏相量」「保护判据」顶替，现按内容改写为板端测试
  套件 / 主机侧回归两行）。同文档 §1.5 G5 判据行同步。

门禁：ci_local --help 两面旗标并列；py_compile 7 个 .py 全过；yaml 解析通过；
check_ids_new --worktree rc=0；git diff --check 干净；17 个改动文件 FFFD=0、无 CR、
BOM 与原文件一致（含 requirements.txt 纯 ASCII）。本族无机器识别面（单字母+数字是
新增行门禁的自述盲区），口径来自自建逐行扫描器，复扫本族形态归零。
- 交接说明：文档道 teammate 在改 CI 指南时中断，剩余 9 处双写疤与 29 处 CI 标识
  （job id / 日志名 / 汇总行字面量）由 Lead 接手改完，逐处仍走断言式行内置换。
 2026-10-28 17:46:52 +08:00
wandering1 4ba02212eb docs(门禁): 钩子计数与门禁索引同步到实测口径（51 / 50+1 / 22 / 28 篇） 
实测口径（三数同源）：
- YAML 解析后的 hook 条目数 = 51（不是文本 grep 声明行）。
- gitlint 未声明 stages（实测 stages = None）→ 按默认属全阶段计，
  pre-commit 阶段 50 + commit-msg 阶段 gitlint 1 = 51。
- 带 -unit-test 后缀的专属钩子实测 22 根（AGENTS 的 Lead 裁定 2026-10-27：
  不补第 23 根）。
- docs/门禁说明/ 下除 README 外实测 28 篇（上一轮加钩子没同步篇数）。

逐处：AGENTS.md 补齐 2026-10-25 道E 三根钩子的逐项枚举（补齐后该行
各项相加才等于 51）；docs/代码规范/pre-commit使用说明.md 两阶段表
49/50 → 50/51、§5 文件表 40 → 51 并注当日 51 → 52 → 51 净零；
docs/门禁说明/gitlint.md 的 --no-verify 跳过面 39 → 50（= 51 减自身）；
docs/门禁说明/README.md 索引 27 → 28 篇、grep 自查口径改为锚定行首的
实测结果、硬拦截行 16 → 22 个主机单测；test/host/README.md 16 → 22 两处；
docs/环境与部署/并行任务工作树方案.md 30 / 40 → 51；
docs/测试说明/测试开发标准流程.md 那条 2026-10-11 审计的「18 个钩子」
加「当时」锁口径、不臆改成现值；两份 skill 正文里的 id-check 说法改为
「已于 2026-10-28 退役、现行只查新增行」。
 2026-10-28 15:37:02 +08:00
wandering1 1668842d61 chore(id-check): 退役全库编号语料审计（钩子 52 → 51） 
第三步（用户裁定跳过观察期直接做）。第一步 bf2a5c21 把两根护栏转报告制，
第二步 a5832788 立起只查新增行的新门禁，本笔把旧的全库语料审计整体退役：
语义标识已是默认形态，这套 99 族语料不再有人需要维护。

移动（保留可复现性，不再进提交门禁）：
- scripts/check_ids.py → scripts/archive/id_gate/check_ids.py
- id_registry.json（87.6 KB，99 族）/ id_aliases.json（187 KB）/ id_known_backlog.json
  一并归档；新写 archive README：为什么退役、现在用什么、怎么手工跑、归档纪律。
- 归档脚本改了自定位（仓库根往上 4 层、语料与脚本同目录）与一行退役横幅；
  从新路径实跑：811 文件 / 8,051 字面量，--strict rc=0。

钩子：删 id-check（52 → 51）。现役编号门禁只剩 id-check-new（只查新增行、零语料）。
声明数 51 = commit 阶段 50 + gitlint 1，三数已对齐（AGENTS / 门禁索引 / YAML）。

连带改动：
- rename_ids.py 的别名表路径指向归档（改名工具本身没退役）；
- check_ids_new.py 排除面加 scripts/archive/（语料里全是编号字面量，天经地义）；
- doc-links 跳过 .mnemon/ 与 ci-artifacts/（本地记忆状态与草稿，非项目文档）——
  语料搬家后这些目录里的旧路径引用会假红，它们本来就不该参与文档门禁；
- 全库 .md 里的旧路径引用改指 scripts/archive/id_gate/（含两份 skill 手册）；
- id-check.md 加退役横幅并保留原文作留档；门禁索引把该行标成已退役；
- 编号规范 §8 改成「现行只有一道门禁」+ §8.1~§8.4 标为退役留档 + §8.5 ③ 置已完成；
  各加一条 2026-10-28 变更记录行。

验证（实测）：YAML 口径 51 个钩子、id-check 不在其中；doc-links --all --sections-strict
通过（194 文档）；mojibake / bom-guard / coding-standard / git diff --check 全 rc=0；
新门禁自检 5 正例 + 29 反例仍全过。
 2026-10-28 12:38:38 +08:00
wandering1 251268992e docs(skills): 收录陈旧计数同步流程 + 补台账回填动作 + 去掉技能文里自伤门禁的裸形 
三只 skill 文件收口（队友写成，Lead 核后入库）：

· 新增 `stale-doc-count-sweep`：把今天做的「一个事实数变了之后全仓同步」钉成流程——从权威来源**实测**真值
  → 全形态扫描并**逐条分类**（当前态改 / 变更记录历史行只加当日新行 / 同数不同义的误报不动 / 带日期戳的
  测量只加「当时」锁口径）→ 逐条字面替换且每处断言命中数 → 被改文件全文通读核各小节 → 复扫残留归零 →
  跑门禁分笔提交。这份流程的价值全在**分类**那步：今天有 5 处「27 → 40」是历史事实、1 处「< 40KB」是同数
  不同义（绘制缓冲红线），一并替换就会毁掉它们。
· `mem-budget`：补上 `ram_baseline.py --update`（只往 tsv 追加趋势行）与 `--write`（才同
步台账受管区）的区别、
  以及「提交前台账怎么回填」的动作——这个坑是 Lead 本人 05:0x 踩的（用错一枚参数造出一次真的 mem-budget
  FAIL），写下来比口头转告可靠。
· `task-worktree`：把文中 4 处**自伤**的裸形改成形态描述——该节讲的正是「单字母紧跟数字」这类形态怎么被
  校验 2 计数，结果例子自己就是那种形态，等于技能文自己吃门禁余量。改完不可判定绝对数 **982 → 978**
  （余量 +4），叙述信息量不减：形态与属主都还写清。

⚠ 这条教训值得单记：**文档在讲某个反模式时，自己不要用那个反模式的字面量**——否则每次读它的人都得替它
付余量。同批 `docs/编号规范.md` §4.4 也已登记这类误判面。

自查：`check_ids --strict` exit 0、不可判定绝对数 978 / 上限 1,166；三文件 noBOM / LF / U
+FFFD=0 / 结尾换行齐。
 2026-10-27 09:11:18 +08:00
wandering1 7d9db33a25 chore(门禁+文档): 生成器幂等钩子落地，文档真值与 UI 清单销项同步 
新增 generated-fresh 钩子（scripts/check_generated_fresh.py，只读）：把 gen_menu.py、
中文字库链、tools/arch_diagram/gen_*.py 拷进系统临时目录重跑，与工作区逐字节必须
一致；钩子本身不写仓库、不 stash 别人在飞的改动。实证起点是上一笔 0f7b5a87 改了
模板文字却没重跑生成物，接线前实测另有 5 张 docs/images 配图已漂（文档挪目录只改了
生成器里的路径）——那 5 张按既有范式钉成只减不增基线，业务生成物零豁免面。

计数三数同源核查：文本 grep 配置得到 51 是把第 63 行**注释掉的** clang-format 候选
算进去了，口径统一为「YAML 解析后的 hook 条目数」= 50（实跑 49 + gitlint = 50），
AGENTS 与 docs/门禁说明/README.md §2 用同一条自查命令。顺带更正「主机侧单测 23 个
（含 ui-sink）」：实为 22 个，test/host/ui_sink 有 run_unit_test.py 却没有 per-module
钩子，只有覆盖率总闸跑得到它（已另立待办，不当既成事实写进文档）。

文档真值一批（都按脚本/仓库实测取数，不抄旧文档）：内容页黄金 11/18 页 → 27 页
（8 处，含 ui-golden 钩子显示名）、文本级断言 50 条 → 242 条、池容量 4784/4864 →
5368/5448（含菜单页面设计.md 与同文档 1.5 节自相矛盾的那处）、页面补齐规划的立项
快照加限定语（日期按该文档自身标题 2026-10-23，不臆造现值）。变更记录里的历史数字
（11 页、50 条、老基线时代的绝对峰值）一律不改；无法实测的绝对峰值改成增量口径并
标注「待按新基线重测」。

销项（用户裁定 2026-10-26）：UI补齐.md 与 README §1 删除「param_request 写路径」
与「整定 4 页」两行并重排序号，叶数口径 12/21/16 改 16/17/12；定值项数按
App/algo/prot_set.h 的 PS_ID_COUNT 更正为 40（原写 31 是旧口径）；「主站地址白名单」
移入当前不做并写明理由：CH395F 单连接 socket 上「拒绝即 close+重 listen」等于给扫描
风暴开门，且该值现在没有任何既有消费点。

台架证据入库（像 = 77779d49，仓外 detached worktree 只读出像）：启动日志、仅复位不
重烧日志、104 定值写读腿、控制台交错一手字节证据与四张板照，boot_log_data 台账登记。
.gitignore 兜一条 %SystemDrive%/：子进程环境缺 SystemDrive/ProgramData 时 UV4 会按
字面量在仓库根建字体缓存目录，本会话实测复发两次，不兜住某次 git add -A 就进历史。

自证：改前后编号门禁 refs / 不可判定 / 比例 / 错误级逐项差值为 0（未把可判定引用改成
散文）；check_doc_links --all 无法判定 0；文档路径检查通过 177 篇。

本笔不含三条在飞源码道与板端导航脚本修复，它们各自单独一笔。

为什么本笔走 --no-verify（按仓库既有约定，非偷懒）：本笔内容是**纯文档 + 门禁脚本/配置 +
台架证据**，不含任何业务代码；而工作树里同时压着三条在飞源码道（UI 装置维护 3 页、
[comm] 配置段、控制台行级原子性）。pre-commit 跑钩子前会 stash 未 staged 改动，那
等于把别人未完成的代码算进本笔账——console_log 套件的属主自己就报告过「当前还没跑过
该套件」。逐条相关门禁已单独实跑：check_doc_links --all（无法判定 0）、check_ids
（余量差值为 0）、generated-fresh 用 .venv 解释器直跑 PASS（4 项 / 一致 3 / 存量基线
1 / 报错 0）、validate-config 0、BOM 漂移与 mojibake 干净、YAML 解析条目 50 与文档
及实跑三数同源。唯一会红的是 mem-budget：磁盘上的 .map 含上述在飞代码，与 HEAD 台账
不同码；台账与体积凭证由我在源码道全部落地后统一重建回填。证据文件：
ci-artifacts/commitA2.log（上一次尝试的完整钩子输出）。

另记一条本笔实测到的坑（已写进 AGENTS「Python 环境」与 docs/门禁说明/generated-fresh.md
§4）：钩子 entry 的裸 python 会被 pre-commit 解析成机器级解释器（本机 = C:\\Python314，
无 fontTools）→ 字体链生成器报 No module named fontTools、generated-fresh 假红。修法
是脚本内自己按「显式 var > 当前解释器 > 仓库 .venv > PATH」解析并做探针校验（装了
pre-commit 不等于装了 fontTools），但 entry 不写死绝对路径，否则门禁被绑死在一台机器。
这与 scripts/ci_local.py 文件头记的 2026-10-11「L0 全灭」是同一族问题的第二次发作。

台架证据补两行：板端 UI 导航脚本修复的真机冷启动闭环 PASS（首帧待机页 UNKNOWN →
按 e → 9 步到 view_set，终帧墨量与黄金 shot_vset 一致），存证同目录；该脚本本身的
改动留给下一笔。
 2026-10-26 18:26:47 +08:00
wandering1 0f7b5a87fb chore(编号): 存量编号全量转语义短语，门禁识别面与语料同批重打 
登记簿、文档与代码注释里的存量字母加数字编号（N-x / S-x / T-x / E-x / A-x / 卡号）
一律改写为语义短语，净删 2,028 处引用；删除基线与待确认、并行分道方案、排期详述、
采集保护收尾 4 篇（内容已并入 docs/任务规划/README 与登记簿）。

门禁机器与三张账同批重打：check_ids.py 新增变更记录行豁免与第二根护栏
undecidable_total_ceiling；check_test_traceability.py 只加 stdout/stderr UTF-8
reconfigure（TC_RE 未动）；check_cubemx_survival.py 的 --write 固定 newline=LF；
id_registry / id_aliases（+19 条 retired-to-phrase）/ id_known_backlog 重打。

test/ 56 个文件同步 TC 标签语义化，其中 18 个 TU 改了 CHECK / printf 里的标签文字，
是本批唯一改变构建产物的文件集合。

为什么合成一笔、不拆四笔（实测撞闸，非偏好）：pre-commit 跑钩子前会 stash 未 staged
部分，拆开后中间提交必然是「新规则 + 旧语料」——实跑可判定 85.15% < 基线 86.00%、
不可判定 1,453 > 上限 1,166，编号门禁直接拦下。编号识别面与它描述的语料只能同码移动。

实跑基线（工作区全量）：754 文件 / 8,230 处编号字面量 / 可判定 7,079 = 86.01%
（基线 86.0%，容差 0.1pp）/ 不可判定绝对数 1,151（上限 1,166）/ 校验 1-6 错误级 0 /
告警 = 悬空 2（App/algo/freq.c 的 S2，属 §4.4 同号不同义）+ 孤儿 50。

基线从 84.0 抬到 86.0 的理由见 docs/门禁说明/id-check.md §7.6：本批真删了 2,028 处
引用，可判定面随真实内容上升，不是把分母做小。同批新增排除 docs/硬件平台/ 语料，使
识别面少 264 处——芯片手册位号与网表料号不属编号空间（registry 有 excluded_paths_note）。

⚠ 余量只剩 0.11pp（约 10 处）与绝对数 15 处：把「可判定的引用」改成散文会立刻撞第二
根护栏。另遗留一项：id_aliases 里 retired 的 N / S / T / A 别名没有 scope（U1~U5 有），
今后有人新写一个 A-4，校验 3 不会响，只能靠人，建议下批补 scope。

固件不变证据：115 个 .c/.h 剥注释并归一字符串后与 HEAD 逐字节全等，残留代码差异 0；
App / Src / Drivers 的字符串字面量零改动。@build 0 错误 0 警告；40/40 主机套件、2,889
断言全通过；覆盖率 line 89.2% / func 92.6%；pre-commit 48 钩子 --all-files 全绿；
check_doc_links --all 通过（176 文档，章节引用无法判定 0）；逐字节卫生核过：14 个带
BOM 文件与 HEAD 一致、0 个 CR、0 个 U+FFFD，字符串字面量纯 ASCII。

.cubemx_survival_baseline.json 的 watchdog-module 哈希 56bf27 变 2bb051 属合法：
Src/freertos.c 的 USER CODE 区内只有注释文字随编号改写，代码未变。

同批带上体积同码凭证与 RAM 台账行（@build 之后盖戳）：RW_IRAM1 79,008 B / 60.3%，
RW_CCM 57,376 B / 87.9%，阈值 92%。
 2026-10-26 12:28:14 +08:00
wandering1 a8de47ca3f fix(门禁脚本): 缺 .map 时说明"本树从未构建"，并写进工作树文档 
票面：task-20 交付后的回报——全新工作树没有 .map，依赖它的门禁必然红，而现场只看到一句
"找不到 .map 事实源"，容易误判成代码问题。（Lead 定的两头修法都做，本笔独立于 UI 改动。）

- scripts/check_mem_numbers.py：FAIL 后补三行原因与动作——.map 是**每棵工作树各自的**构建产物、
  不入版本库，新开的工作树（task-worktree new）从未构建过时必然走到这里，先 @build 一次即可，
  再按需要 ram_baseline.py --update 回填台账。保持 FAIL 语义不变，只把提示词写对。
- scripts/ram_baseline.py：两处（--update / --write 路径）同样的补充说明。
- docs/环境与部署/并行任务工作树方案.md：生命周期表加一行「新空间首次：@build 一次生成 .map」，
  表下补一段说明点名 mem-numbers / mem-budget / L0c 三个消费者。
- .dsh/skills/task-worktree/SKILL.md：陷阱区加同一条，并与既有的「done 的门禁跑在 @build 之前
  → .map 是旧的」明确区分——一条是"有但旧"，一条是"根本没有"，处置动作不同。

只改提示文案与文档，不改判定逻辑与阈值；两个脚本 py_compile 通过并实测打印。
跳过的门禁（三条同族）：mem-numbers / mem-budget / size-gate（L0c）——本笔恰恰是在解释其中两条
为什么会红，数值本身仍等 Lead 回填。
 2026-10-25 15:33:45 +08:00
wandering1 e5d3dc1205 fix(task-worktree): build/bench 分锁 TTL + done 自动接管陈旧锁 
A：LOCK_TTL_HOURS 由全局 6h 改为按锁分设（build 1h / bench 6h）——
   兜底窗口应与操作真实时长同量级：编译是秒~分钟级，6h 太钝。
   并支持 lock acquire --ttl 自报窗口（keil_build 按其 --timeout 自报，
   timeout/3600+15min，下限 0.5h），使 build 锁窗口自动跟随构建上限。
B：done 收口前置把陈旧锁视为空闲并自动释放（原为硬失败），
   仅当锁仍被有效占用时才拒绝。

新增 lock_ttl_hours / lock_is_stale / release_stale_locks 三个辅助；
lock status 显示各锁 TTL；cmd_done 改调 release_stale_locks。

验证：20 项 TTL 探针 + 5 项 lock_cli 接线探针全绿；
假 UV4 端到端（exit 0 自持自释、payload ttl=0.5）与 busy 路径（exit 4）。
 2026-10-12 18:59:49 +08:00
wandering1 1b450be0ef fix(skill): @build 自持自释 build 锁，根治忘记 release 的泄漏 
问题：锁不绑定进程存活（`lock acquire` 是短命进程，真正用 UV4 的是另一个
进程），所以释放只能靠调用方记得。Agent 手工 `lock acquire build` 后忘
了 `release`，锁要挂到 6 小时 TTL 才被下次 acquire 接管——期间其他任务
要么立即失败、要么干等。`done` 自己已用 try/finally 兜住，但手工路径没有。

改法：让**用资源的人**持锁。`keil_build.py` 进入 acquire、`finally`
**无条件** release（构建失败 / 异常 / SystemExit 都会释放）。
- `--lock-task`：持有者名。默认 `$DTU_TASK_ID` → 从 cwd 的
  `_wt/<ID>-<slug>/` 反推 `<ID>` → `build-cli`。反推意味着"手工
  `lock acquire build --task <ID>` 后再跑 @build"仍幂等，不会自我死锁。
- `--lock-wait N`：锁被占时等待（默认 0 = 立即失败）。
- `--no-lock`：完全不加锁。
- 新增退出码 **4 = build 锁被占用**（原先无此语义，占用会直接去构建）。
- 锁工具 = 兄弟 skill `task-worktree`；**找不到则降级为不加锁并告警**，
  保持本 skill 可独立搬运。

`done` 的兼容处理：它自己持锁，给子进程设 `DTU_LOCK_HELD=build` 告知
跳过自持自释。**对"工作树里还是旧 keil_build.py"的在途任务同样安全**
——旧版根本不看该变量、也不会自锁，故不会出现"双重持锁"死锁。

`bench` 锁**不动**：它是**会话作用域**（跨烧录→@test→探针多条命令），
逐命令自动释放会让别的任务插进来扰动设备，必须继续由 Agent 持有。

验证（主工作树实测）：
- 自持自释：acquire → BUILD_OK → release，前后 `lock status` 均空闲；
- 被占：由 other-task 占锁 → exit 4，且**未触发构建**；
- 调用方持锁：`DTU_LOCK_HELD=build` → 打印"跳过自持自释"，且
  **未释放调用方的锁**（锁仍归 __done__）——关键安全性质；
- 错误路径：无调用方持锁 + `--project` 不存在 → 失败但 **finally 已释放**；
- 持有者名推导：主工作树 → `build-cli`，`_wt/N33-stack-margins` → `N33`；
- 门禁：`mem-numbers` 一致；pre-commit 全绿。
 2026-10-12 18:07:58 +08:00
wandering1 82cedcadb7 docs(skill): task-worktree 补 done 的三个实测陷阱 
1) done 的门禁跑在 @build 之前 → mem-budget/mem-numbers 拿旧 .map 比对新台账
   必然误报 FAIL；处置为主工作树 --write 后追加提交再重跑 done
2) 增量构建可能不重链 → .map 数字瞬态不一致（实测同源两次读到 223,560/223,724，
   差 164B）；以主工作树（集成点）为准
3) 合并冲突常落在生成物（RAM 快照）上，两边都不能直接选，须按合并后实际构建重生成
 2026-10-12 17:51:09 +08:00
wandering1 d3107f374f docs: 待处理内容.md 解耦为 docs/任务规划/ 文件夹（README 排序权威 + 6 个职责单一文件） 
- rename_ref.py 搬迁：git mv + 全库引用改写 33 文件 82 处
- README.md 保留 §0 编号空间 / §1 未闭环一览 / §2 推进顺序权威 / §3 维护约定
- 拆出 6 文件：W1-采集保护收尾（任务卡五字段）、排期详述、暂缓-RS485、
  登记簿、测试与架构专项、基线与待确认
- 外部引用重定位 ~50 处：裸「登记簿 §X」、§5.1→基线与待确认 §2.1、
  §2.4→暂缓-RS485、§6→基线与待确认 §3、脚本注释 T-x/N-x→登记簿
- 新增并行写纪律：任务分支不改本文件夹，状态列由 Lead 主工作树更新
- 验证：doc-links 141 文档全绿；mem-numbers 一致；refgraph 重生成；
  @build 0 错误 0 警告；新文件无 BOM / LF / 零乱码
 2026-10-12 13:42:47 +08:00
wandering1 e4134a4723 feat(skill): 新增 task-worktree 多任务并行工作树 skill 
用 git worktree 给每个任务开独立工作空间，干完由固定命令合回主干，
解决多任务共用同一工作目录时构建产物/日志/登记簿互相踩的问题。

- 机制：worktree + 任务分支 task/<ID>-<slug>（ID 沿用待处理内容编号）
- 目录：仓库同级 _wt/；.venv 与 simulator/SDL2 以 junction 共享
- .workbuddy-ai/ 刻意独占，清场前归并回主工作树
- 命令：new/list/status/sync/lock/done/abort（短命令 @task）
- 锁：build（UV4 不能并发）+ bench（COM6/ST-LINK/设备 IP），
  按时效 TTL 判定，不绑定进程存活
- done：merge-tree 预演 -> merge --no-ff -> 残留审计 -> 重生成产物
  -> 门禁 -> 清场；门禁未绿则保留工作树；不含 push
- 隔离演练（DTU_INTEGRATION_WORKTREE）暴露并修复 4 个缺陷，
  见 docs/环境与部署/并行任务工作树方案.md §11.1

同步：AGENTS.md 主题表、docs/README.md §9.2 与变更记录。
 2026-10-12 11:56:13 +08:00