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

126 Commits

Author SHA1 Message Date
wandering1 7099c56c34 chore(ledger): pages 批 1~4 合入后回填凭证/覆盖率并同步黄金参考计数 
task/pages-ui 合入（merge dea7591 + 修复 498cc60）：三页回炉 + SOE 页 +
四查看页 + 遥信 33 行页 + ui_data 三通道 + soe_store 只读 API + 字库与
门禁配套共 12 笔。凭证重盖（Code=224,688 / RW_IRAM1 78,992 B=60.3% /
CCM 87.9%）；覆盖率基线 39/39 套件复算。ui-golden 黄金参考 11→18 页
随批 4 扩容，AGENTS 门禁行/索引行与门禁说明两处、覆盖率口径一处同步；
两篇新详解（bom-guard/setview-check）已由道E 交付、索引去"待补"。
memset 隐式声明一条教训：分支树增量构建"0 警"不覆盖未重编文件，
done 主树全量重编才是终判。
 2026-10-25 15:49:42 +08:00
wandering1 3965eb3f28 feat(门禁): bom-guard 机械化 BOM 漂移，附 setview-check 行表一致性 
把 AGENTS 铁律第 2 条从"人工逐文件比 HEAD"变成提交硬闸：HEAD 有 EF BB BF 而工作区没有 → FAIL。
2026-10-25 一天之内道E 在 task-15 里连踩 4 次、道B 批 1 踩过 1 次，此前全靠人记得做审计兜底——
人工审计只防得住记得做的人，这正是它该变成门禁的理由（票 = task-20）。

scripts/check_bom_drift.py（纯标准库）
- 判定只有一条：HEAD 前 3 字节是 BOM 而工作区不是 → 列出文件与补救动作，不含二义措辞。
- 两条刻意不报（票面要求的边界，--selftest 逐条自证）：① HEAD 里根本没有的新文件无 BOM 不误报；
  ② HEAD 无 BOM 而工作区加了 BOM 也不报——那是另一个方向的改动，可能是有意的（把文件纳入名单），
  报红只会逼人 --no-verify，而"养成绕门禁的习惯"比漏检一次贵得多。
- 一条刻意不做：不自动补 BOM。正确修复是在文件最前面加 3 个字节；脚本整文件重写会按系统默认编码
  重打中文，把可修的丢 BOM 变成不可修的 U+FFFD（AGENTS 铁律第 1 条那条更大的坑）。补救文案里把
  这句完整写出来了——报错信息的作用是让踩的人当场做对动作，不是让他知道有人不高兴。
- 名单三处互指：AGENTS 铁律名单 / 本钩子 files 正则 / 脚本内 BOM_LIST，每次运行核一次；单独改任何
  一处都会在别人的提交里被拦下。名单散在三处而无人同步，等于没有名单。
- --selftest 在临时 git 仓库里跑 4 条判定（含上述两条边界 + 主用例 + 名单外文件不参与），全过。

setview-check（Lead 指令：并入 task-20 同窗机械化）
- 核 Drivers/BSP/UI/ui_w_setview.c 的四张视图表与 App/algo/prot_set 枚举序、
  g_prot_set_meta 上下限是否同一份口径：id 恰好覆盖 0..39 各一次 / 数值行 min-max
  等于 meta 换算 / kind 与 is_ctl 一致 /
  单位纯 ASCII / 小数位查表与行表一致。机械化的理由不是"多一道保险"：BSP 侧看不到 App 头，
  行表里的 id 是裸数字 + 行尾注名，这条对齐在编译期**物理上无法自证**；而页面上只有当前可见
  的 8 行会被像素断言看到，错位要翻到第 2、3 页才可能被人发现——那时它已被黄金参考钉死了。
- 跨分支先后写成注释：脚本文件随 task-15 分支合入主干；在此之前 files 永不命中 → 钩子自然 skip
  （skip 不是失败），合并后自动生效，不需要任何人再动这条配置。

AGENTS.md（票面授权：只加一句机械化标注；下面实际动了两处计数，一并申报）
- 铁律第 2 条末尾加"已机械化：bom-guard 钩子"+ 三处互指一句。
- 钩子计数 46 → 48 两处同步（不同步就是让 AGENTS 说谎）；并在文档索引行标出"bom-guard /
  setview-check 两篇待补"，把欠的详解篇目挂在明面上，不留沉默债。

验证
- 本笔**未用 --no-verify**：全量 pre-commit --all-files 46 项 Passed、0 Failed（含两条新钩子）。
- 端到端实测（不止 --selftest 自证）：真把 Drivers/BSP/UI/ui_w_records.c 的 BOM 剥掉并 stage →
  bom-guard rc=1 并打印补救动作；还原后该文件与 HEAD 逐字节相同，工作树干净。
- 顺带发现并行开发方案的一条空白（本笔未修，写域之外）：全新工作树没有 .map，mem-numbers 会因
  "找不到 .map 真实源" FAIL，跑一次 @build 才绿。门禁隐含的"本树必须先构建过"前提在
  docs/环境与部署/并行任务工作树方案.md 里没写；已回报 Lead 定夺归属。
- 自报一条：本笔第一次提交被 gitlint 拦下——正文有一行 92 > 80，**我量出来了却仍然按了提交**。
  记在这里是给下一篇门禁详解留素材：这条门禁拦下过的人里也包括写门禁的人自己，而「拦下过
  什么真事」那一栏不该只挑别人的事写。
 2026-10-25 14:36:50 +08:00
wandering1 42b47aa5ac chore(ledger): runpar 合入后回填台账/凭证/覆盖率并同步计数 
task/runpar-par 合入（merge 7bbcc9c）：卡10 运行参数段 [run_par] 9 键 +
104 映射 0x8030~0x804F + 死区真源收编 + SYS_EVT_RUN_PAR_SAVE 落盘链。
@build 0/0：Code=219,620 / RO=22,036 / RW=1,280 / ZI=132,864；
RW_IRAM1 76,720 B（58.6%）、CCM 87.9%。Flash +1,912 B、RAM +8 B 与
lane-d 申报一致，--no-verify 欠账清。meas.c 静态更名越界照准（同 TU
撞名 C2369 的最小修）。run_par.c 入覆盖率基线（39/39 套件）；钩子
45→46、单测钩子 21→22、总闸 38→39（AGENTS + 门禁 README）。
 2026-10-25 13:21:39 +08:00
wandering1 adeef7d21b chore(ledger): meas 与 n17 两笔合入后回填台账/凭证/覆盖率并同步计数 
task/meas-snap 合入（merge 9c2653c，meas 快照层，分支树冲突由 lead 并集
手工解：id_registry 三族 UIDATA/VOLSYNC/MEAS 共存，JSON 校验过；该合并
提交按 mem 域例外 --no-verify，理由=合并树 .map 滞后，回填本笔兑现）。
task/n17-probe 合入（merge 969fc5c，drop 路径异步化 Flash +16 B/RAM 0）。
合并后 @build 0/0：Code=217,828 / RO=21,600 / RW=1,264 / ZI=132,840；
RW_IRAM1 76,664 B（58.5%）、CCM 87.9% 不变。覆盖率 38/38 套件基线登记
（meas.c 入账）；凭证按最终 .map 重盖。计数：钩子 44→45、单测钩子
20→21、总闸 37→38 套（AGENTS + 门禁 README）。
 2026-10-25 10:37:05 +08:00
wandering1 b746a1ff00 chore(ledger): ui-data 合入后回填台账/凭证/覆盖率并同步门禁计数 
task/ui-data-feed 合入（merge 98664a1）：ui_data 三通道快照 +
ui_data_feed 装配 + ui_w_soe 显示名 + 字库 +4 字（采/样/恢/效，
179→183）。合并后 @build 0/0：Code=217,204 / RO=21,504 /
RW=1,256 / ZI=132,680；RW_IRAM1 76,512 B（58.4%）、CCM 87.9%。
lane-e 分支侧 --no-verify 欠账清；覆盖率基线登记 ui_data.c
（37/37 套件、tested 41）；凭证重盖（L0c 恢复序列）。
AGENTS/门禁 README 计数 42→44 钩、18→20 单测钩子（n22+ui-data 两笔带进来）。
 2026-10-25 10:07:15 +08:00
wandering1 8c28f3bfdd docs(收口同步): 批 1 落地后 AGENTS/104/算法层口径更新 + SOE 7/8 消费面补齐 
- AGENTS.md：钩子 40→42、主机单测钩子 16→18（adc-cal/prot-dim）、
  覆盖率总闸 28→35 套、layer-deps 基线 6→3（记录 reader 注入兑现）
- IEC104上行设计说明.md：遥测读数改工程量口径 + 死区额定 0.5% 重定
  已落地（卡 6）；§8 第 4 条改写、变更记录追加行
- 采集与算法层设计说明.md：状态行/红线③/幅值门三处由「标定未实现」
  更新为「折算已落地、精度复核待卡 12 注入」
- App/log/soe_rec.h 类型注释表补 7/8 两行（lane-a 口误 6/7 已勘误，
  真值按枚举链 SAMPLE_RESUME=6 连续计数）
- test/host/soe/decode_soe.py：TYPE_NAMES + docstring 补 7/8——
  否则台架 FTP 下载校验会把标定闭锁记录判 bad type 误红（隐藏消费边）；
  soe 套件 32/32 复跑绿
 2026-10-25 05:55:00 +08:00
wandering1 744a1cb086 ci(gates): 接线 test-coverage 覆盖率总闸（FAIL 语义），并修三处已成假话的门禁文档 
用户裁定 2026-10-24：缺 mscoverage 组件时**失败**，不做 skip。于是 P1 之后那个
"钩子只挂 16/28 套"的缺口关闭了。

为什么挂这一根而不是补 12 根 per-module 钩子：本闸跑**全部 28 套**，并且守
"已覆盖行只增不减"的基线台账。这是 per-module 钩子结构性做不到的——删掉一套
测试，它那根钩子只会因为"没有文件要检查"而静默跳过（Skipped 不等于失败）。
实测接线代价：45 s（28 套，含 28 次 MSVC 编译与插桩运行）。

FAIL 语义已按本仓"合成自证"的纪律验证（不是只测绿的那一半）：把
DTU_MS_COVERAGE 指到一个不存在的文件 → 钩子 Failed、脚本退出码 2、并打印可
执行的 [ENV] 提示（说明该 exe 装在哪、怎么覆盖）。脚本对显式环境变量刻意
"不做自动探测回退"，所以指错会被点名，而不是悄悄换一份工具跑出另一本账。

顺手修掉三条**现在已经不成立**的文档说法（门禁文档最贵的就是骗人）：
- 口径 §7 第 8 条：原写"只有 BuildTools 且没勾代码覆盖率工具的机器会退出码 2"。
  实测本机 Community 18.10 与 BuildTools 18.9 **两份安装都自带**该 exe（mtime
  2026-09-15 02:30 / 2026-09-05 16:17，都是各自安装当日，不是后来补勾）→ VS 18
  的 BuildTools 默认就带它。真实风险面只剩：裸 MSVC 无 VS 的机器、环境变量指错、
  以及靠 PATH 兜底的环境。
- 门禁说明 host-unit-tests.md 盲区第 4 条：原写"没有对应钩子的模块 = 零回归"——
  如今 12 套新模块由总闸兜住，这句话已经不成立，改成两种口径并写清触发面。
- 同篇第 6 条：原写"无覆盖率统计"。行/函数覆盖**已有**度量（本闸出 Cobertura 并
  守基线），仍无的只是分支覆盖——那是用户裁定 2026-10-23 记下的**已接受缺口**，
  不是待办，改口时把这个区分写清楚。

钩子计数同步（新增 1 根 → 声明 40 根 / pre-commit 阶段 39 根 + commit-msg 的
gitlint，已用脚本核对，不是手数）：AGENTS.md（总数、枚举、索引表）、
pre-commit使用说明.md（66 / 91 / 234 三处，含清点日期）、门禁说明 README
（正文与索引标题，另加一行索引指向口径文档——23 篇不变，同一事实不在两处维护）、
门禁说明 gitlint.md（--no-verify 跳过的"其它 38 个"→39）、并行任务工作树方案。

自查：end-of-file-fixer 与 trailing-whitespace 复跑 Passed（首轮 --all-files 只
因末行空行红过一次，已按钩子自身规范化）；doc-links --all --sections-strict 通过
（178 个文档）；id-check --strict 零台账外新账；8 个改动文件 U+FFFD = 0、无 CRLF。
零代码改动，故未跑 @build。未 push。
 2026-10-24 07:50:53 +08:00
wandering1 6505cef9df feat(门禁): coding-standard 加 CODE-RULE-20 禁 C 库堆分配（销 §4.8 空白 ②） 
规则：在**掩码后**的文本上匹配 malloc/calloc/realloc/strdup/strndup/
free/aligned_alloc 调用。三条判据都是踩过坑之后定的——
- 大小写敏感：pvPortMalloc / vPortFree（唯一允许的配对）不会误报；
- 词边界 \b：dhara_nand_is_free(、buf_alloc( 这类同形后缀不误报；
- 用掩码：注释与字符串字面量里写 malloc 不报（规范示例就踩过这种）。
覆盖名比 AGENTS 列的五枚多带上 strndup / aligned_alloc——同族同类，
漏一个就等于留后门。

出处不在规范 V1.0，在平台约束：MicroLIB 的 C 堆由 startup_stm32f407xx.s
的 Heap_Size EQU 0x200 只有 512 B，KB 级分配必返 NULL，而模拟器（宿主
CRT 堆）完全正常、**照不出来**——配置引擎 2026-09-18 那次堆分配纠偏与
lftpd 的 malloc 隐患都是**先上线才发现**的那类，靠评审等于没管。

落地前按 门禁说明/coding-standard.md §8 的纪律先全库普查：钩子范围内
C/H 共 151 个文件，命中**只有** simulator/sim/cfg_file_store_sim.c 两行，
即 cfg_store_alloc/cfg_store_free = **平台分配后端的宿主侧实现**（设计依据
写在 docs/子系统设计/配置文件设计说明.md 的"MCU 端 = pvPortMalloc、
模拟器端 = 宿主 CRT"）。所以零基线、直接硬拦截；豁免用脚本里的
HEAP_ALLOC_ALLOWLIST（**文件路径 + 函数名**双条件），刻意不做目录级豁免：
下次谁要碰 C 堆就得往这张表加一行，评审看得见。

自证：临时样例文件里 malloc/calloc/free 各报一处，pvPortMalloc/vPortFree/
buf_alloc(、注释、字符串五种陷阱形态全部不误报；
pre-commit run coding-standard --all-files → **Passed**（= 全库零存量）。

顺带修三处口径不一致：
- 规范 V1.0 §6.1 的示例自己写着 malloc/free（通用 C 模板遗留）→ 已在示例
  下加"本仓例外，别照抄"批注，事实源指向 AGENTS.md 平台约束；
- docs/门禁说明/mem-budget.md 里"这条纪律只靠 AGENTS 铁律与评审"已过期 →
  更正为由 CODE-RULE-20 机器拦截；
- AGENTS.md 平台约束条加"已机器拦截 + 唯一豁免"一句；scripts/README.md
  补登 check_test_coverage.py（上一个提交漏登记）。

另：本次一并修好上一处编辑事故——报告 §4.8 曾被我的脚本调用截成半句
（只落第一行、丢掉 malloc 那半句），已重写为"两处空白均已闭合"。

自查：pre-commit run --files（9 个改动文件）适用项全 Passed；
check_doc_links.py --all = 35 处，与主干同数（本分支贡献 0）；
check_ids.py --strict 通过（裸编号 P0-1 改平实说法，避免记成新账）；
9 个文件 BOM/CR/U+FFFD/行尾与 HEAD 逐项一致。本轮零 .c/.h 改动，未跑
@build、未占 build/bench 锁；分支已 rebase 到 v2-on-ui，覆盖率脚本全量
回归仍 16/16、line=2552/2893 不变。
 2026-10-23 23:44:46 +08:00
wandering1 6822726b2c docs(门禁说明): 手册 §2 收敛为通用机制与查号表，逐项详解归一到 23 篇 
用户一句"现在门禁都在干什么，我一概不知"引出的收尾。原手册 §2 有 27 个逐钩子小节，只回答
"拦了什么、怎么配"，回答不了"什么时候会骗我"；docs/门禁说明/ 已把逐项详解（含"限制与盲区"
一节）建好，本笔做收敛：同一事实只留一处（docs/文档规范.md 的要求）。

**先搬后删**（否则收敛等于丢事实）：旧 §2 里独有条目逐篇折回，共 18 处插入、15 篇受益。折回的
东西包括：六套主机单测的来历与用例规模（13/36/82/46/32/149 断言，含 nand-port 的"与旧算法
对照"）与"改动公共骨架 unit_test_harness.py 会同时触发 16 个钩子"；UI 页面**两层注册**（构建
注册 vs 框架注册：枚举 + s_defs[] 描述符表）与"豁免不整目录一刀切"；lv-conf-sync 首次落地清掉
26 个 LVGL 9.3 不存在的选项、3 处重复定义、10 项隐式开关显式化，以及 ALLOW_DIFF 端专属白名单
与必须穿过 lv_conf_internal.h 里那层 KCONFIG 包裹；cubemx-survival 的 16 项清单、断言前先剥
C 注释（本仓注释刻意引用历史代码，不剥就恒定误报）、旧手册"自造标记区"建议与看门狗文档实测
教训之间的优先级；id-check 顺带收编 check_test_traceability.py、裸形同字母多义属**显式承认的
盲区**、--update-baseline 只许涨；layer-deps 的注入自证与报错时三条修法（注入回调 / 上层递数据
/ 才谈 ALLOW）；coding-standard **nand_ftl.* 也在排除清单**（我先前那篇漏了）；test-suite-switch
的剥注释判定与派生宏白名单；mem-budget 两类软提醒不拦、退出码 2 是解析失败不是通过；doc-links
的排除目录与状态词 ±40 字符距离；task-table 改栈三步；gitlint 报错样例；no-mojibake 的修复路径。

**顺带抓到旧文档两处错**（记进文档，不悄悄改）：一是 check-added-large-files 的阈值旧手册写
"单个文件 > 1MB"，按本机安装的钩子源码实测是 --maxkb 默认 **500**（500 KB）——已更正，并把
"本目录任何默认值都以实测或安装的钩子源码为准"写进 end-of-file-fixer 当反面教材；二是
**ui-golden 在旧手册里连小节都没有**，只活在配置注释里：除了"有基线不等于有门禁"，这是另一种
失踪——有钩子、没文档。

手册 §2 改写为三节：迁移说明 / **旧编号 → 新文档 查号表**（历史引用靠它读，旧号按"冻结历史不
回改"保留）/ **跨钩子通用机制**：两阶段与换机必须重装 hooks 才带 commit-msg、stash 陷阱、
always: true 已废、改写型与只读型豁免不对称、增量拦截三段式且刻意没有 --write、没有 .map 是
"跳过"不是"通过"、改配置的验收是看目标钩子出现在输出里且不是 Skipped、新增门禁三步必须做
注入自证且"限制与盲区"不许留空，另有快速自查入口。手册 707 行 → 273 行。

引用**按内容**重指（只核编号存在与否不够，同号小节会被当本文自引用静默放过）：编号规范、
scripts/README（顺带更正那里过时的 warn-only 说法，早已关闸为增量拦截）、RAM 使用分析与优化
方案、测试开发标准流程、lvgl-simulator skill、AGENTS 文档表（拆成"每门禁一篇详解"与"通用
机制"两行）、.pre-commit-config.yaml 头注释、docs/README.md 描述、手册自身 §5.5 与 §6 的两处
内部引用。另：表格里的裸节号会被 doc-links 判成本文自引用，查号表统一写成不带 § 的形态。

写说明过程又被自家门禁拦一次：gitlint 篇里引用报错样例时写了两个规则号字面量，被判形态不合规
→ 改成中文描述，没有往台账里塞 reason 解决。

验证：纯文档与注释改动，不动代码，Program Size 不变，故不跑 @build/@test；
check_doc_links --all --sections-strict **171 篇 0 问题**；id-check 增量拦截通过；
pre-commit run **RC=0 / 13 项 Passed**；28 个改动文件字节卫生 **0 异常**（无 BOM、无 CR、
无 U+FFFD、均 LF、无行尾空白）。
 2026-10-23 11:44:21 +08:00
wandering1 3488617bc9 docs(门禁说明): 新建逐项门禁文档目录，先落索引 README 与 bsp-err 首篇 
用户的原话是："现在门禁都在干什么，我一概不知。" 现有文档只回答"有哪些钩子、怎么配"
（docs/代码规范/pre-commit使用说明.md），回答不了"这一条到底在拦什么、什么时候会骗我"。
故新开一个目录，**每种门禁一篇**，八段固定结构：查什么 / 为什么要它（拦下过什么真事）/
触发面 / 报错怎么读 / 好处 / **限制与盲区** / 豁免与基线口径 / 改门禁本身要注意什么。

**最后一节是这批文档存在的理由**：只看"拦了什么"的门禁文档会让人以为绿就是对的。而本仓
三个增量拦截门禁（layer-deps 6 条、bsp-err 38 条、id-check 台账 640 处）的绿灯含义只是
"没有比上次更差"。

索引按 39 个 hook → 23 篇规划（16 个主机单测是同机制 16 实例，合一篇；cppcheck 与
test-cppcheck 是同工具两套范围，合一篇），文件直接用 hook id 命名，与提交输出里的名字
一致、可 grep。README 另有一节"三种拦截姿态"——改写型 / 硬拦截 / 增量拦截——分清这三类，
报错时才知道该改代码、还是该还基线。钩子清单、files 范围、pass_filenames 全部从
.pre-commit-config.yaml 实测解析（39 个 id：官方 5 + gitlint + local 33），不是手抄。

本次交付：索引 README + 首篇 bsp-err.md。首篇里把今天踩过的坑全写进"限制与盲区"，共 10 条，
例如：只扫 Drivers/BSP（App 层同类问题仍无人管）；consume-result 只认单行整句的裸调用，
跨行写的调用按正则形状测不到；must-use 名单靠"返回类型 + 注释关键词"启发式，注释不写
"错误码/失败"就漏、改名就能绕开规则；HAL 族是固定清单，清单外的返回 HAL 状态的函数不在
名单里；return-doc 的判据是"注释块里出现『返回值』字样"，**散文里出现这三个字也会放行**
（本仓真发生过两条靠函数说明里的关键词误判通过）；基线键带出现序号，--prune 只报"消失"、
不会报告某处只是搬了家；改标签名等于改基线键，必须原子完成。在册数量与构成按当前基线
逐条数出来写（38 = consume-result 37：gd5f2gq5ue.c 28 含 14 处 HAL 丢弃 + 14 处自家原语、
ui_net_sink.c 6 全为 net_close、rs485.c 2、nand_ftl.c 1；err-type 1 为 bool
ui_content_page_open()）。

同步指向：AGENTS.md 提交门禁一节改为"每种门禁一篇详解 → docs/门禁说明/README.md"，通用
机制仍指 pre-commit使用说明.md；docs/README.md §7.1 增加索引行；.pre-commit-config.yaml 的
bsp-err 注释块顺手更正（原文还写着"三条规则""现 1 条""只能靠书写约定兜着"，均已过时）。
迁移状态用索引表的"状态"列跟踪；全部写完后 pre-commit使用说明.md §2 收敛为通用机制 +
总览，同一事实只留一处（docs/文档规范.md 的要求）。

验证：纯文档与注释改动，未触碰构建产物；check_doc_links --all --sections-strict 149 篇
0 问题（新目录的相对链接、跨文档章节引用都能判定）；bsp-err 仍 38/38/0；本次受影响文件的
pre-commit 全绿 RC=0；两份新文档字节卫生 ok（无 BOM、无 CR、无 U+FFFD、有尾换行）。
 2026-10-23 09:48:26 +08:00
wandering1 2575177e81 refactor(gate): bsp-err 四项检查改用自描述标签，废掉 R1~R4 这组撞车代号 
纯改名，检查行为一个字没动：规则逻辑、阈值、豁免形状全部原样。

改名原因（用户一句「R4 到底是什么」问出来的）：R1~R4 是我在 check_bsp_err.py 注释里
自造的序号，而这个裸形在本仓另有含义——R1~R8 已在 scripts/id_registry.json 登记为
"专项风险"的文档内编号（保护规划与看门狗的风险表都在用），带连字符的那一族又是审查
报告的可靠性 / 内存优化项编号（编号规范 §1 的"连字符承载语义"一行正是这么写的）。
**同一个裸形四种意思**。最刺人的一点：编号门禁**不会报**这种撞法，因为编号规范 §4.3
已把这些裸形声明为"同号不同义"、走 collides_with 白名单，校验 4 不计事故——同一天里
我起的另一组自造号被当场拦下、这组代号却一路绿灯，差别不在我做对了什么，而在白名单
挡的是"事故"、不是"可读性"。

新名同时是基线键的第二字段（格式 文件|标签|名字）：
· err-type        错误通道不外泄（对外接口不拿 HAL_StatusTypeDef / bool 当成败）
· timeout-name    超时宏不取负值
· return-doc      公开函数必须写「返回值：」
· consume-result  返回值不得裸丢弃（须接住或显式 (void)）
老名对照：R1=err-type、R2=timeout-name、R3=return-doc、R4=consume-result。

同步面：脚本里的规则码与 38 条基线键的字段**一起换**（中途不跑 --prune，否则改名会被
读成"38 条全还清 + 38 条新账"），换完 --emit-baseline 复核仍是 38/38/0、RC=0。现状类
文本全部换新名：AGENTS.md、pre-commit使用说明.md §2.27（新增"检查项叫什么"一行含老新
对照与撞号说明）、bsp_err.h 边界纪律、报告 §0.4 / §9 / 附录 A，以及代码注释里的 5 处
（gd5f2gq5ue.c/.h、nand_ftl.h、ui_menu_tab.h）。已提交的变更记录行里的老名按"冻结历史
不回改"处理，以 §2.27 对照行为准。ui_menu_tab.h 带 BOM，Edit 又剥掉、已按原样补回。

写说明文字时又被编号门禁拦了一次：我为了举例"老名撞车"，在那段话里写了两个编号字面，
被判"未紧邻文档名 / 未登记前缀"共 3 类新账——连批评自造编号的段落本身都在自造编号。
改法是不写号、只描述形态并指向权威条目。

验证：@build **0 错 0 警告**，Program Size 与上一笔**逐字段相同**（Code 213,676、RO
18,860、RW 1,188、ZI 131,500）→ 证明确为注释与文案，故不跑 @test（无指令变化）；
pre-commit run 全绿 **17 项 Passed**；check_doc_links --all --sections-strict 147
  篇 0
问题（中途我自己写的 §4.3 没紧邻文档名，被判成本文自引用，已补全路径）；9 个文件字节
卫生 0 异常（UI 头 BOM 仍在、无 CR、无 U+FFFD、均有尾换行）。
 2026-10-23 09:36:01 +08:00
wandering1 d9b887c0af feat(S-5 R4): 返回值不得裸丢弃成为机械检查，并修掉照出的第一处 ECC 静默降级 
B 的第一步（加规则）与第二步（修最小最值的那处）。用户裁定"B 按你说的进行"。

**为什么只能项目侧自己做**（两条实测负结果，已写进 §2.27 与 bsp_err.h 边界纪律 4）：
· ARMCC v5 对 __attribute__((warn_unused_result)) 不生效（凌晨在 rs485_transmit 上实测：属性
  在位、调用点裸调不接返回值，构建仍 0 错 0 警告）；
· cppcheck 也照不出来——按本仓自己的 --enable=warning,style,performance,portability 跑
  gd5f2gq5ue.c，对 14 处丢弃 HAL_SPI_* 返回值、以及"未初始化局部量直接进 P_FAIL 判定"
  **一条不报**（它假定 gd5f_read_status(&status) 会写出参，而失败路径根本不写）。
结论：**丢弃底层传输的返回值，今天没有任何工具会响**。

**R4 上线即照出 37 条存量丢弃**：gd5f2gq5ue.c 29（14 处 HAL + 15 处自家原语）、net_socket.c 8、
ui_net_sink.c 4（net_close）、rs485.c 2、nand_ftl.c 1。按增量拦截老规矩入基线、只减不增——
这是覆盖面扩大新暴露的历史债，不是新增违规；基线 19 → 1 → **38**。

**R4 自己被修三次（逐条记下，都是"规则比我想的更脆"）**：
① 首版漏判"裸调用行尾带注释"这种写法（正则的 \s*$ 卡死），而那恰是最常见的"带说明的丢弃"
   → 补可选注释分支，并做 6 条正/反例自检；
② 把 net_set_errno 八处误判成丢弃（它是 setter，返回 int 是状态回声不是调用成败）→ **按真实
   反例把规则收窄**（谓词 + setter 两类豁免），而不是塞进基线洗掉假阳性；
③ must-use 名单只从**头文件**取，gd5f_set_feature 这类 static 原语整个在视野外——而下面那处
   真窟窿恰恰是 static、靠人工才发现 → 名单扩到 .c 内 static 定义（同一套启发式），补完立刻
   又照出 gd5f_bbt_save#1：**运行时标坏后 BBT 落盘结果被丢弃 = 坏块记账可能没持久化**，已入
   基线记为待还，本步不动行为。
另修一处自己的排版误判：R3 原本要求注释块出现字面"返回值"，规范 V1.0 允许列对齐写法
「返 回 值：」→ 改为忽略空格匹配（门禁不该规定排版）。

**修掉的第一处真窟窿**：bbt_rebuild 的注释写着"无论扫描成败都须恢复 ECC，否则后续 I/O 在无
ECC 下运行"，而它下面 gd5f_set_feature(0xB0,…) + gd5f_wait_busy(100) **返回值全丢**：SPI 一抖
ECC 就保持关闭，且 gd5f_check_ecc() 在 ECC 关闭时恒读"无 ECC 错"——整条链再没有任何信号。
补法复用 init 路径的 E-10（写完回读 B0h 验 ECC_EN 位真生效，"写了但没生效"与写失败同罪），
并把"关 ECC 失败"改成**立即中止**（此时 ECC 仍开着，是安全侧；带着 ECC 去扫 spare 反而会把
厂标好块误判成坏块，"重建 BBT"变成制造坏块）。恢复失败时按 (void)gd5f_bbt_load() 回读盘上
副本，避免 RAM 留着"比盘上更新"的表而下次上电又退回旧表。

**一条定位纠正（差点把修复记大）**：查链接映射发现 Removing gd5f2gq5ue.o
(i.gd5f2gq5ue_bbt_rebuild), (604 bytes)——该函数在产品镜像里**根本没被链接**（产品构建无调用
者），只由 ENABLE_STORAGE_RECOVERY_TESTS 的恢复构建经 testTask 调用。所以本次修的是**恢复流程
自身的安全**（跑恢复时若 ECC 没恢复，设备会带着"已恢复"的结论在无保护状态下继续跑），不是
现场日常路径；相应地镜像 Code 的 +28 B 也不是它带来的（未逐字节追，线索是
gd5f_private_get_feature 由单调用点变多调用点、内联决策可能变化）。验证因此不能只跑产品构建：
临时打开 TEST_SUITE_STORAGE + ENABLE_STORAGE_RECOVERY_TESTS 编一次（0 错 0 警告且该函数不再
出现在 Removing 列表），随即还原两处开关并重编产品构建核对（test/board 无残留差异）。

**编号门禁把我自己的自造编号拦下了**：我起初用 B-1/B2/B3/B4 标记这批缺陷，id-check 报"未登记
前缀"13 处（且 B2/B3/B4 会与真实里程碑号撞号）→ 全部改写成平实语言。这是那条"注释与文档里
不许用没人检索得到的内部阶段编号"的规则第一次在提交前拦住我，规则是对的。

验证：@build 0 错 0 警告，Code 213,648 → **213,676**、RO 18,860、ER_IROM1 **232,536 B
  / 22.2%**
（ROM 合计 233,724 B；RAM 逐字段不变）；ram_report 重生成 + ram_baseline.py --update + 配图常量
同步（mem-numbers Passed）；@test **PASS**（到 net init: OK 682 ms、[ERR] 0）；R4 两处**探针
实证**（临时加一条裸调用 → 立刻成为新增并 RC=1；还原 → 38/38/0）；--prune 点名本次还掉的 2 条
已删；pre-commit run 全绿 15 Passed；check_doc_links --all --sections-strict 147 篇
  0 问题；
id-check --strict 增量拦截通过。

文档：AGENTS.md 与 .pre-commit-config.yaml 的 bsp-err 口径（四条规则、基线 38）；
pre-commit使用说明.md §2.27（R4 全量口径 + 两条负结果 + 名单来源与豁免形状 + 单行限度）；
bsp_err.h 边界纪律 4；报告 §0.4 / §5.1 / §9 / 附录 A + 变更记录；存储维护与容量恢复.md 新增
§4.3（运维判据：出现 ECC restore FAILED / ECC not enabled 即本次恢复**不算完成**，须断电重启
重走 init，不许接着 nand_ftl_format() 当作已修好；并记明该函数产品镜像不链接）——顺带修该文
结构缺陷：原 ## 5. 变更记录 误插在 §4.1 与 §4.2 之间，会让 §4.2 变成 §5 的子节。
 2026-10-23 09:15:41 +08:00
wandering1 cc2966319a docs(S-5): 补齐 16 条返回值约定，bsp-err 基线 19 → 1，并修门禁自身误判 
A（还债）先行，B（GD5F 的 SPI 失败被吞成成功）另波处理。本笔不改行为：@build 的
Program Size 与上一笔逐字段相同（Code 213,648、RO 18,860、RW 1,188、ZI 131,500）。

**补齐 16 条「返回值：」约定，bsp-err 存量基线 19 → 1**：
· gd5f2gq5ue.h 九个 SPI 原语（wait_busy / write_enable / read_status / page_read /
  read_from_cache / program_load / program_exec / block_erase / check_ecc）
  写全规范五要素，
  并把**每个函数能返回哪些码**写死：哪一个是"可重试"的 GD5F_WAIT_EXPIRED、哪一个才是
  器件自认坏块的 P_FAIL/E_FAIL、失败时出参为什么不可信（E-42 同族）。
· nand_ftl.h 从零散三行补成带模块头，并明写 **nand_ftl_init() 的 −1 抹掉了失败类**：
  分类目前只在失败点进日志，要按类分支需要 C4 快照（现无消费者故未做）；同时警告"不得
  把 −1 解读成卷坏了可以重格式化"（E-31 的教训正在这条上）。
· ui_menu_tab.h 五个表查询 API 由行尾短注释升级为完整块（含"越界返回 false 是保守取
  只读"、"宁可按一张错表导航失败也不要按错表导航成功"这类判断依据）。

**修掉门禁自己的一条误判口径**（本笔最该记的）：R3 原本要求紧邻注释块里出现字面"返回值"，
而规范 V1.0 允许列对齐写法「返 回 值：」。后果有两层：① 合规写法被判违规；② 反向更糟——
gd5f_write_enable / gd5f_read_status 两条**早就"通过"了**，原因竟是它们的**函数说明**里顺口
写了"返回值"三个字，而不是真有一行返回值说明。**一条会因为散文里出现关键词而放行的规则，
等于在奖励运气**。修法是在块内忽略空格后再匹配关键词（排版选择不是违规），并在注释里写明
为什么不许把"必须写成不空格的形式"写进规则。

剩余 1 条刻意保留：bool ui_content_page_open()。它与"补注释"不是一档事——要改签名、要处理
3 个调用点（ui_menu.c:138/192/196 **今天三处全部丢弃返回值**，即"按 ENTER 开页失败是静默的"
这件事现在没人知道）、且 UI 源码双端编译（模拟器同一份），验证面是"重建模拟器 + 像素回归 +
真机逐页进菜单"。这不是还债，是独立一波改动，留档待决策。UI 三个文件带 BOM，Edit 会静默
剥掉 → 已按原样补回 3 字节（AGENTS 铁律：丢 BOM 后 ARMCC 按 CP936 解码，中文报 #870-D）。

**更正我自己写进文档的一条错话**：S-5 各条里我把 GD5F_SPI_TIMEOUT 100 记成"自旋圈数（改
分频时长会变）"。这次逐行核它 12 处用法，**全部是 HAL_* 超时参数或 HAL_GetTick() 差值 →
它也是毫秒**。真问题降级为"单位没写进名字（缺 _MS 后缀），读代码必须回实现里查单位"。
osWaitForever 与 HAL_MAX_DELAY 同为 0xFFFFFFFFU、以及 *_BUSY_TIMEOUT = -2 其实是返回码这两条
仍然成立（后者已改）。现状类条目（报告 §0.4、bsp_err.h、pre-commit使用说明.md §2.27、脚本
文件头）已全部改准；**已提交的变更记录行仍写着旧说法——按 §8.1 冻结历史不回改，以本笔新增
的更正行为准**。

验证：@build 0 错 0 警告（尺寸同上，故**不跑 @test**——无指令变化，跑它没有新信息）；受影响
文件的 17 个钩子全 Passed（含 ui-golden 像素回归、cppcheck、编码规范、bsp-err 1/1/0 且
--prune 干净）；check_doc_links --all --sections-strict 147 篇 0 问题；id-check
  --strict 通过；
9 个文件字节卫生 0 异常（UI 头 BOM 仍在、无 CR、无 U+FFFD、无行尾空格、均有尾换行）。
口径同步：AGENTS.md、.pre-commit-config.yaml、pre-commit使用说明.md §2.27 的基线计数 19 → 1；
报告 §0.4 / §9 / 附录 A 与变更记录两条（还债一条、更正一条）。
 2026-10-23 08:25:58 +08:00
wandering1 78248a1cdf feat(S-5): 收编 SD2506/TPAFE 并给 dhara 失败分类，门禁基线 19→17 
前一笔立契约与门禁（`Drivers/BSP/bsp_err.h` + `bsp-err` 钩子 + RS485 试点）；这一笔按用户
指定顺序 C3 → C1 → C2 把三个模块真正收编，并让存储失败第一次变得可读、可分类。

**C3 · SD2506 整模块（11 个公共 API + 6 个内部 helper）**：三枚私有宏 `SD2506_OK`/
`SD2506_ERROR`/`SD2506_I2C_ERROR` **删除而不是留别名**——留别名等于新代码还能用旧形状，
把迁移洗掉；编译器替我们找全所有调用点。新增 `sd2506_err_from_hal()`，**把 I2C 超时从
"和没人应答共用一个 −2"里拆出来归成 `BSP_ERR_TIMEOUT`（可重试）**——SD2506 是启动链第一站、
I2C1 上电时序敏感，这是本波唯一真正的语义改善，不是改名。`sd2506_init` 的 charge 寄存器
**回读校验不符**原返参数类错误，改归 `BSP_ERR_IO`（那不是调用方的错）。

**C1 · 同形两义**：`GD5F_BUSY_TIMEOUT` → `GD5F_WAIT_EXPIRED`（**值 −2 不变**，纯消"名字叫
TIMEOUT 其实是返回码"）。**GD5F 私有码集整体收编刻意没做**：169 处引用里 48 处在板级套件、
还要动 Trap 记录用词，属另一波带真机+套件回归的工作，不夹带。TPAFE5160 收编 23 处：
`BUSY_TIMEOUT → BSP_ERR_TIMEOUT`、`ERROR → BSP_ERR_PARAM`（**同值 −1，行为零变化**）、
`FRSTDATA_ERR → BSP_ERR_NO_DEVICE`（E-44 的本义就是"芯片没驱动 DB 总线"，归到器件无响应比
私有 −3 有用，且避开与 `BSP_ERR_TIMEOUT` 撞值）。实测 `tpafe5160.o`/`gd5f2gq5ue.o` 的 Code
增量为 **0**——改名不产生一条指令。

⚠ **`tpafe5160_snapshot()` 刻意不套成败码**：它是 1=有新帧 / 0=无新帧 / −1=参数错 的三态
**状态**返回，0 不是错误而是"这一拍没有新数据"，强行收编会把慢消费者的正常路径变成失败。
顺带订正我上一版在 `bsp_err.h` 的断言——"本层只有 `net_*` 把数量与错误挤同一返回值"是错的，
`snapshot`/`adc_input_poll` 就是第二族；两族现都已写明并各注保留理由。

**C2 · FTL 坍缩点分类**：`ftl_flush_cache`/`ftl_read_page` 不再把 dhara 失败压成
  `GD5F_ERROR`，
按**处置差异**分三类，并在最早同时知道 LPN 与原始码的位置就地打印：`ECC`/`TOO_BAD` →
`BSP_ERR_CRC`（页级，重试或换页，不代表卷坏）；`JOURNAL_FULL`/`MAP_FULL` →
`BSP_ERR_NO_SPACE`（介质健康但块池/日志见底，此时重格式化只是把问题推回去）；
`BAD_BLOCK`/`RECOVER`/`CORRUPT_MAP`/越界 → `BSP_ERR_IO`（完整性故障，保卷 + 上报，不许自愈
重格式化）。这与 **E-31** 是同一条纪律的两端。可读名用自建短表：**本仓 dhara 没有编
`error.c`，用 `dhara_strerror()` 会直接链接失败**。`disk_read`/`disk_write` 仍回
  `RES_ERROR`
（FatFs 契约）；要让 defaultTask 卷健康探针按类分支还差跨调用存活的快照 → C4 待还。

**两次靠核实拦住的自我错误**：① 我一度认定 `DBG_ERROR("... err=%d", err)` 是把结构体塞进
varargs 的格式 bug——核 `Lib/dhara/error.h` 后确认 `dhara_error_t` 是 `enum`（标量），那行日志
本来合法，改了反而是引入错误；② `bsp-err` 一次 `replace_all` 越界把 8 处 **GD5F 码空间**的
判据改成 `!= BSP_OK`（数值同为 0、无行为变化），但那正是"把两个码空间混起来"，已逐一还原。
`cppcheck` 亦抓到 `cls` 声明作用域过宽，已收进失败分支。

**验证**：`@build` 0 错 0 警告（`Code` 213,648、RO 18,860、`ER_IROM1` 232,508 B /
  22.2%、
`ROM 合计` 233,696；**RAM 三项零增量**）；`@test` PASS（692 ms，烧入戳 `Oct 23 01:35:32`）
且逐条读到被改模块的锚点：`SD2506 init: OK (ret=0)` 与 ID/时间/温度/电池四条读回正常、
`ADC init: OK`、`NAND init: OK`、`Map resumed: 14094/97504`、`adc=` 帧计数持续递增（证明
snapshot 三态未被改坏）、`[ERR]`/Fault/FAIL 0 条。主机单测：系统时钟 100/100、dhara NAND
移植层 149/149（两者都因本次改动需补 `Drivers/BSP` include 路径，补后在钩子内实跑 Passed）。
`pre-commit run` 全量 RC=0（20 个实跑钩子 Passed）；`bsp-err` 基线 **19 → 17**（还掉两个
`*_BUSY_TIMEOUT = -2`）、`--prune` 干净；`doc-links --all --sections-strict` 147 篇
  0 问题；
`id-check --strict`、`layer-deps`、`mem-numbers`、`mem-budget`、`ui-golden` 全过；33
  个文件
字节卫生 0 异常（无 CR / 无 U+FFFD / 无行尾空格 / 均有尾换行）。

**口径与数字联动**：新增 `docs/架构设计/STM32F4-Base存储架构说明.md` §10.4（三类码与处置
理由）；`pre-commit使用说明.md` §2.27 与 `AGENTS.md` 基线计数 19 → 17；TPAFE README、
GD5F 测试指南与 Trap 记录均**保留旧名留痕**以便对旧日志；配图桶按 .map 对象级增量重算
（`dhara/FTL` 10,931 → 11,222，+291 全部落在 `nand_ftl.o`；应用代码/UI +36 落在
`app_main.o`；其余散量入"其他"7,557；桶和 = Code+RO 断言通过、文本溢出 0）；
`ram_baseline --update/--write`、`ram_report_20261023.md` 快照、报告 §1.3/§5.1/§5.4
  与
部署文档 §3.3 数字全部同步；报告 §0.4/§9 的 S-5 状态改为 🟡 主体已落地。
 2026-10-23 07:42:02 +08:00
wandering1 6ede1443e9 feat(门禁): 新增 layer-deps——BSP 反向 include App 的增量拦截（37→38） 
推荐清单第 5 步的拆分执行：反转依赖（5a）暂缓，**只把"防扩大"的门禁先上**。

**为什么门禁比搬迁值钱**：AGENTS.md 与分层图早就写着"六层单向依赖"，可从来没有
机械检查——于是同一件事的记载从 2026-09 审查报告的"NETCFG 一处"，漂到 2026-10-22
实测的 **8 个文件 9 处**，全靠人读代码才发现。边界的静默腐蚀只能靠门禁止住。

**机制（与 `id-check` 的增量拦截同构）**：`scripts/check_layer_deps.py` 扫
`Drivers/BSP/**.{c,h}` 的 include，按 `App/**` 头文件索引解析反向边（同名头按字面
路径消歧），命中分三类：
· ALLOW 永久豁免 3 条横切叶子头——`App/log/console_log.h`（日志后端，BSP 的
  dbg_log.h 就建在它上面）、`App/util/sys_clock.h`（时间源）、`App/util/sha256.h`
  （纯算法、无状态）。它们是"任何层都要用的叶子能力"，不是上层服务；新增豁免
  必须先回答"它为什么不是上层服务"。
· BASELINE 钉住存量 6 条：`cfg_file.h`×2（NETCFG）、`vol_lock.h`×1（lftpd_io）、
  `sys_log.h`×3（UI 两处 + `ui_w_records.h`）。**只减不增**（脚本没有 `--write`）。
· 新出现的 (BSP 文件, App 头) 组合 → FAIL，并给出三条出路（注入回调 / 上层传参 /
  确属叶子才可豁免）。
`--prune` 在某条存量还清时点名"可从基线删除"，于是"还欠几条"成为可见进度，而不是
文档里的一句口号。

**当场自证**：落地时临时给 `Drivers/BSP/RS485/rs485.c` 加了一行 include `cfg_file.h
`，钩子当场 FAIL 并点名该文件与该头（退出码 1），删掉后转绿——没被触发过的门禁
等于没有门禁。

**边界要说清（免得被误读成缺陷）**：本钩子只拦**静态 include 方向**。运行时的属主
纪律本来就没破——UI 只投递 `net_cfg_save_request()`，真正写盘在 defaultTask，模拟器
也早在主机侧跑整条配置链。

**口径同步**：钩子数 37 → 38 共 6 处（`AGENTS.md` 两处、`pre-commit使用说明.md` 两处
并新增 §2.26 详解、`并行任务工作树方案.md`、报告 §0.1/§1.1）；
`项目架构总览.md` §1 分层原则处补"此方向已机械检查"；报告 §0.4 的 S-1 计数由
"7 文件 15 处"更正为脚本口径的 8 文件 9 处，§9 状态改 🟡。

**暂缓项（都已在报告 §0.4 记因）**：5a 反转依赖——没有功能在等它，且要过"改 IP
免重启生效"整条真机链，留给下次真动 NETCFG/UI 时顺带做；5b 目录搬迁——uvprojx 326
条 + IncludePath + CMakeLists + 42 个 UI 文件 + 全库引用改写，收益只是"目录名好看"，
而远程 CI 仍刻意不跑 `@build`，兜底未成立。

门禁：`layer-deps` 自身通过；`check_doc_links.py --all --sections-strict` 146 文档 0
问题；`check_ids.py --strict` 增量拦截通过、可判定 82.84%；`mem-numbers` 0；
`py_compile` 通过。本轮无 `.c/.h` 改动，未重跑 `@build`。未推送。
 2026-10-22 19:30:02 +08:00
wandering1 504db26698 docs(内存): 阶段子项改层级编号 4.阶段.项，消除与顶层章节同号撞面
CI / L0 静态门禁 (pre-commit) (push) Failing after 2m1s
Details
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 21s
Details 
根因：`RAM使用分析与优化方案.md` 顶层有 §1 背景 / §2 现状测量（2.1~2.6），而 §4
「方案」下"阶段 N"的子项也用裸号 0.x / 1.x / 2.x——阶段 2 的 2.1/2.2/2.3 与顶层
2.x **完全同号**，阶段 1 的 1.x 又长得像"第 1 章第 x 节"。`doc-links` 对本文自
引用按设计直接放过，于是门禁和人一起看错：AGENTS.md 把"栈余量台账"写成 §1.4，
而 §1.4 其实是阶段 1 的 lftpd 静态化项（上一笔提交的信息里我把它误判成断链，
已 amend 更正）。

改法：阶段子项一律改层级编号，阶段号不变、只加 `4.` 前缀 —— 0.x→4.0.x、
1.x→4.1.x、2.x→4.2.x。共改 14 个标题；文内自引用与实施序列表（S4~S9 那套）、
暂缓清单、§5 预期效果列里的裸号一并补成 §4.x.y。

外部引用同步 15 处：AGENTS.md、lftpd/README ×2、菜单页面设计、RAM预算台账 ×2、
项目架构总览 ×3、FTP_Test_Guide ×3、boot_log_data/README、部署环境要求、审查
报告、ram_baseline.py ×3。最有说服力的两处歧义：审查报告与 RAM预算台账都写
"缩堆见 …§2.2"——既可读成顶层 §2.2（静态大项排行）也可读成阶段 2 第 2 项，
现均为 §4.2.2（阶段 2 第 2 项"缩堆"）。

另修 4 处把 §1.4 当"栈台账"的错指：采样有效性校验设计说明 :441/:593/:650 改
指 §2.3（任务栈配置与实测峰值）与 §4.0.6（静态最坏链与判定）；id_aliases.json
 的 note 改指 §4.0.6 并标注"原 §1.4，2026-10-22 层级编号"。

冻结与示例：其它文档**变更记录行**里的旧编号按项目纪律不改写（项目架构总览
:367、RAM预算台账 :98），改在被引文档 §4 开头留一张换算表 + 约定说明；把旧号
当语法示例写的 7 处一并换掉（文档规范 ×3、check_doc_links ×3、rename_ref ×1），
否则示例本身指向已改名的锚点。主文档版本行 bump 到 v1.3 / 2026-10-22。

门禁：check_doc_links.py --all --sections-strict → 146 个文档 0 问题（章节引用
2513 处、机器可判定 1491）；check_ids.py --strict 增量拦截通过；mem-numbers、
ram_baseline --gate（SRAM1 57.4% / CCM 87.9%）、task-table 全绿；本轮未改任何
.c/.h。16 个文件字节卫生自查 BOM/CR/U+FFFD/行尾空格全清。已提交本地，未推送。
 2026-10-22 15:38:14 +08:00
wandering1 f4b9bd57d5 docs(部署): 删任务栈副本表改指针；纠 CCM/FPU 事实并刷新配图基线 
范围：AGENTS.md 一处指针、部署环境要求 §2.2/§3.1/§3.3、RAM 方案 6 处现状
数字、内存配图生成器 + 3 张 SVG、两份报告脚本的行尾与路径修正、新增两份
.map/.htm 数据快照。未改任何 .c/.h（仍跑 @build 复核：0 错误 0 警告）。

部署环境要求.md
- §3.3 删"任务栈预算"副本表、改为指针：该表已缺 adcTask/iec104Task/
  protectTask，defaultTask/timeSyncTask 两值停在旧数，注释却写"由
  gen_task_table.py 同源"——该钩子的校验面只有 README.md / AGENTS.md
  两处受管块，抄出来的副本没有门禁、改栈后必漂。指针指向 Src/freertos.c
  + 两份受管表 + RAM 方案 §2.3/§0.6，并留一条"别再抄"的成因说明。
- §2.2 链接布局补 `RW_CCM 0x10000000`（scatter 给 0x0000FF00 = 65,280 B，
  2026-10-11 起承载 FreeRTOS 堆；另有 256 B UNINIT_CCM 尾区），写明 CCM
  不可 DMA。原文"SRAM3/CCM 故意未映射"与 STM32F407-Demo.sct 直接矛盾。
- §3.1 MCU 行更正为**单精度 FPU（VFPv4-SP，无硬件双精度）、无 TrustZone**
  （原写"双精度 FPU / TrustZone"是芯片事实错误，也正是报告 F-6 双精度软
  浮点被长期误判的土壤）；SRAM 行改为"两块都在用，仅 SRAM3 未映射"。
- §3.3 资源预算表补 CCM 行，并把"主 SRAM 125,104 B / 95.4% / 极度紧张"
  更正为 75,264 B / 57.4%（余 55,808 B）；红线改标在 CCM（余 7,904 B）。
- 变更记录补 2026-10-22 行（含上一提交里的资源表刷新那一笔）。

AGENTS.md：任务表注里 "RAM使用分析与优化方案.md §1.4" 是**指错小节**——§1.4 确实
存在（该文档 §4「方案」下的阶段 1 子项，讲 lftpd 大局部缓冲静态化），但栈余量
台账在 §2.3（任务栈配置与实测峰值）与 §0.6（静态最坏链与判定），故改指这两处
再加 内存内容分配策略.md §6。根因是该文档里 §1（背景）与 §4 下的 1.1~1.5 同号
撞面，人和 doc-links（自引用放过）都会看错——本会话我上一轮就被它带错过一次。

配图与数据（draw-diagram 流程：改生成器顶部数据 → 重跑 → 逐文本核越界）
- 新增 data/ram_report_20261022.md、data/stack_report_20261022.md；后者
  运行时水位取自 2026-10-22 真机 [STACK] 心跳（8 任务高水位 + heap
  free=15,800 / min_ever=8,464），静态侧来自同日 .htm（全局最深链 3,024 B）。
- gen_memory_svg.py：三组图数据从 2026-09-21 / 10-10 快照换成 2026-10-22
  实测；任务栈 6 → 9 行，堆总量 48KB → 56KB，判定 6/6 → 9/9 PASS，新增
  AboveNormal 配色；Flash 子条改为"窄段不压字 + 下方四列图例"；任务栈
  画布 440 → 620 高。CCM 段总量按 scatter 用 65,280 B（与台账同口径）。
- 三张 SVG 重生成；用"CJK≈1.0em / 其余≈0.58em + 锚点"逐文本估算边界，
  修掉 5 处文字越界/压字（生成器内置 ElementTree 自检亦通过）。
- ram_report.py / stack_report.py 两处工具性修正：write_text 未指定 newline
  参数 → Windows 下把 data/ 快照写成 CRLF（与 .gitattributes 及既有快照
  不符）；stack_report 的 relative_to 在传相对 -i 时抛 ValueError，且会把
  本机绝对路径写进入库快照 → 统一走 resolve+relative_to 的相对路径回退。

RAM 方案：6 处"当前状态"随 .map/[STACK] 更正——RW_IRAM1 89,168 → 75,264、
RW_CCM 49,184 → 57,376、FreeRTOS 堆 48KB → 56KB（两处）、CCM 余量 ~16KB →
7,904 B、min_ever 4,848 → 8,464 B、6 任务全过 → 9/9 PASS；S-1 历史句保留。

门禁：pre-commit 对全部改动文件 Passed（doc-links --sections-strict、
task-table、mem-numbers、mem-budget、id-check 增量拦截）；字节卫生自查
BOM / CR / U+FFFD / 行尾空格全清。已提交本地，未推送。
 2026-10-22 15:08:04 +08:00
wandering1 64d8b052b1 docs(algo): App/algo/README 缩成目录索引，详细设计迁入 docs/算法 
拆分层级
- 新建 docs/算法/采集与算法层设计说明.md（413 行、13 节）承接机制、契约、
  判据与设计理由：定位与边界 / 数据流与初始化落点 / adc_input / adc_health /
  sample_ring / phasor / freq（7.1 为什么自适应窗、7.2 判据 J1~J6）/
  prot_set / prot_elm / 关键约定与禁令 / 资源足迹 / 验证与判读 / 相关文档
- App/algo/README.md 360 -> 128 行：只留文件清单、依赖、逐文件"改代码必须
  知道"的红线、构建与测试入口、新增模块动作；深挖改成逐条指针
- README 保留 §3.1-§3.7 原编号，既有"§3.7"引用不失效

索引与引用同步
- 索引：docs/README.md §5.2 新增行；项目架构总览主题表拆成"设计与判据 /
  目录索引"两行；AGENTS.md 与 App/README.md 指向（后者原文还写着 L1/L2）
- 按内容重指（编号仍在但内容已搬走，只核编号会静默指错）：App/algo/freq.h、
  test/host/freq/freq_test.c、run_unit_test.py、继电保护规划 L2-4 行、
  pre-commit使用说明 J4 行 -> 指向设计说明
- ADC采样节拍设计说明的两处指向同步改到新文档

修 README 内过时事实
- 挂载写"八个 .c"，实际 uvprojx 内 7 个
- SIM_EXEMPT 写"prot_set / freq 才登记豁免"，实际七个全在表内
- freq-unit-test 标"待登记"，实际已在 .pre-commit-config.yaml
- 定值项数一处 31->40、一处 32->40；blob 144->176 B 证明是 32->40
- 用例与判据数字不再三处复制：属主是 test/host/<模块>/ 与 docs/测试说明/

门禁
- doc-links --all 无新增问题；--sections-strict 覆盖 10 篇文档通过
- id-check 可判定 82.65%（基线 82.6，容差 0.1）；TC 双向追溯差异 124 处不变
- registration-check PASS（1 条已知 WARN）；freq 单测 46/46；@build 0 错 0 警
- 全部改动文件无 BOM、无 CR、U+FFFD = 0
 2026-10-21 11:39:53 +08:00
wandering1 858434492c feat(门禁): id-check 关闸——按债务台账增量拦截，warn-only 时代结束 
机制（--strict 不再「有错就失败」，而是只拦台账外的新账）
- scripts/id_known_backlog.json：340 条指纹覆盖 710 处存量（②167 类 / ⑥135 / ③38）
- 指纹 = (文件, 校验号, 字面量) → 计数，故意不含行号：行号每改必漂，
  用它当指纹会让台账天天假新增，三天后没人敢看 strict，台账失效比没台账更糟
- 带计数而非集合：同一文件里同一个号多出现一次也算新账（复制粘贴式扩散
  正是编号烂掉的主路径，只按「出现过没有」判会放过它）
- 新增 --write-backlog 与 --prune-backlog（只减不增；台账内条目变多当场点名）；
  --strict 缺台账返回 2，绝不退化成一次性拦死存量；--only 与 --strict 互斥
- 钩子 entry 加 --strict；--only 与 --strict 互斥
- 顺带修 _scan_malformed 的反向 bug：原条件 (skip and name != "空格形 Trap")
  语义正好写反，带 [示例] 的行反而专被 Trap 规则咬；改为示例行全部不判
- 第一次提交就被自己的台账咬住（id_known_backlog.json 里当然写着 P1-3 等号，
  被当成新引用）→ 台账加入 excluded_paths：登记号的表不是引用号的文档，
  与 id_aliases.json / id_registry.json 同一条道理

为什么不照「清零再升 strict」的原节奏（§8.4 详述）
- 存量 710 处清完要数周，这期间新债一条都不拦，而新增才是烂掉主因
- 「等清零」让人习惯「报红但照样提交」，真关闸那天没人再信门禁；
  本仓已有 mem-budget / mem-numbers 走 --no-verify 的先例，不再开第二个口子

关闸验收三例（临时件当场还原、git diff 干净）
- A 全新前缀 Z-99 → exit 1 点名 ✅ 咬
- B 同号计数 1→2 → exit 1 点名 ✅ 咬
- C 干净态 710 处 → exit 0 放行 ✅ 放（放不住存量就会逼出 --no-verify）

验证：--strict 干净态 exit 0；可判定比例 82.74%（基线 82.6%）；
doc-links 失效/待确认 0；未改 C/H 不需 @build。
文档：编号规范 §8 上线节奏改写 + 新增 §8.4 机制表；pre-commit使用说明 §2.25；
AGENTS.md 门禁行由 warn-only 改为已关闸增量拦截。
 2026-10-21 11:35:30 +08:00
wandering1 301c3e5183 feat(门禁): 编号门禁 id-check 落地（36→37 钩子）+ 批 1 编号单词化改名 
新增门禁本体
- scripts/check_ids.py：实现 docs/编号规范.md §8 八项校验；默认 warn-only，
  唯一硬拦项是「可判定比例跌破基线」（防回退的本体）
- scripts/id_registry.json：66 个前缀族，逐项来自 §4 总表 + 全库实测游标，
  偏差一律写进 cursor_note，不凭记忆编造
- scripts/id_aliases.json：旧号 → 新号 / 作废标记（照搬 section_aliases.json 范式）
- 顺带收编 check_test_traceability.py：正则补齐大写后缀与无模块码形态，
  比对范围扩到 test/host 与 7 篇「单元测试说明.md」，另加 --board-only 回退旧口径

批 1 改名（用户授权解禁「不改写存量号」）
- 代码规范条款 S1~S19 → CODE-RULE-nn：78 处 / 2 文件
- UI 像素回归状态 S0~S7 → MENU-STATE-nn：61 处 / 3 文件（冻结在 07）
- 两族属主登记处 = 脚本自身的规则表 / STATES 表，文档只作引用方
- 新增 scripts/rename_ids.py（§7.3 规划脚本）：映射表驱动、显式 scope、默认干跑、
  自动写 scoped 别名，跳过 [示例]/[计划] 行与变更记录表，按原字节读写保 BOM 行尾
- 已应用映射表存档 scripts/rename_maps/batch1.json 作审计轨迹

有牙实测（证明门禁不是空转）
- 注入 Z-99 / 裸形 / 悬空 / 越游标 / 未紧邻 / 跨文档重复定义 六例，
  分别被校验 1/2/3/5/6/4 点名，--strict 退出码 1；临时档删除后工作树干净

验证与同步
- 可判定比例基线 82.3% → 82.7%（已 --update-baseline 入档）；错误级 1312 → 1291
- ci_local.py 全绿（L0 + L0.5 共 1104 断言）；ui-golden Passed；
  check_doc_links.py --all 无法判定 0
- 未改任何 C/H 源文件，故本次不需 @build
- 文档：AGENTS.md 与 pre-commit使用说明.md 计数 36→37 并新增 §2.25 详解；
  编号规范 §4.1 补两行、§8.1 落地记录、§8.2 规范与仓库偏差、§8.3 迁移批次记录
 2026-10-21 09:33:54 +08:00
wandering1 44dec5c49b feat(UI): golden 像素回归入提交门禁（W6 U4 第三件，35→36 钩子） 
补上我上一轮自己标记为 2/3 的那块缺口：两个 golden 脚本早已存在且一直在
人工跑，但**从未进自动门禁**——"有基线"不等于"有门禁"（§6.1 原文即自认）。

## 先实测成本再定形态
改一个 UI 源文件后「增量重编模拟器 + 两条 golden」合计 **2~4 秒**，支持走
自动门禁。若实测要几分钟，正确做法是明确不挂、改为文档化人工门禁——一个
逼人 --no-verify 的门禁等于没有门禁，故这个数字是本决定的前提而非附注。

## 落地
新增 scripts/check_ui_golden.py：串「增量构建 → 菜单 8 状态 → 内容页 11 页
+ 池水位」。**有意忽略 argv 且 pass_filenames: false**——两条 golden 按整棵
菜单树 + 全量参考图工作，不接受文件参数，pre-commit 传的变更名对它无意义。
files: 覆盖 UI 源 + ui_task.{c,h} + 模拟器 tests/sim/src + main.c +
CMakeLists + lv_conf.h + 包装器与本配置自身（pre-commit 4.x 无 always: true，
files 是唯一触发手段）。

## 端到端验的是钩子，不是脚本
干净树连跑 3 次 rc=0 全 Passed；给 ui_page_dc.c 的 .top_y 注入 +5 位移 →
**钩子 Failed** 并点名 `[dc] FAIL 与参考页不一致（1882 px 差异）`；还原后
git diff 干净、simulator/tests/ref 的 git status 为空——**全程未用 --update
刷基线**（那正是本钩子要防的行为）。
诚实记录瑕疵：首次实测在"连续注入/还原的紧邻重建"之间偶发失败一次，疑似
MSBuild 节点争用，此后 3 次连跑均绿。已把"单次失败先复跑、连续两次才当真、
不许直接 --no-verify 绕过"写进钩子注释。

## 文档同步
AGENTS.md 钩子数与文末索引 35→36 + 钩子清单补 ui-golden；
pre-commit使用说明.md 概览计数同步；报告 §6.5 U4 由 2/3 → **3/3**（这次是
"真进了自动门禁"，不是"脚本存在"）、§6.1 golden 行转 ✅、§0.1 缺口描述更新。

## W6 剩余
U2 合并两页记录、U5 落地目标页（须先对齐"目标页 vs 现存 7 个 ui_page_*.c"
的差集——报告的"27 页"是目标数而非现状数）。
 2026-10-20 22:14:42 +08:00
wandering1 dafc18f5ed feat(UI): W6 第一波——设计令牌层、页面注册表生成器与 UI 门禁补强 
启动 docs/任务规划/README.md 的 W6 UI 扩展簇（用户裁定，覆盖 2026-10-11
的"本轮不排期"）。四个工作包，全部验证通过。

## U1 设计令牌层（零行为变化）
新建 Drivers/BSP/UI/ui_tokens.h（20 个宏），框架 + 7 个页面 + App/task/
ui_task.c 全部接入。屏幕几何**复用 ui_port.h 既有 UI_SCREEN_W/H**，不重复
定义；令牌头自身只 include ui_port.h，不把 LVGL 拖进全部消费者。
补收了报告没列但代码里真重复的量：UI_TEXT_BAND_H 15（7 次）、列表左右边界
与每页行数（各 4 个页面逐字复制）、推流协议几何与显示几何同源（此前硬编码
3200 且注释写着"须与 UI_FB_SIZE 一致"——典型漂移隐患）、UI_TASK_TICK_MS
（ui_port_step 与 osDelay 必须同值，原先靠注释维系）。
故意不收页面私有几何与"同形不同义"的值（device_info 的 pitch=15 与列表
UI_ROW_PITCH=14 合并即改像素）。

## U3 页面注册表与生成器（删手工分发）
ui_page_registry.{c,h} 由生成器产出，**手工 menu_content_page_for() 已删
除**（仓库内仅存 2 处历史说明注释）。密码页按代码实况**单独出口**
（ui_page_registry_password()）——它非节点绑定，任何 #P 叶子进同一页。
顺带落地此前判定"U1 阶段做不了"的共享 flat 样式 ui_style.{c,h}。
生成器除产注册表外**自动把新 .c 写进 uvprojx 与 CMakeLists.txt**，且
**双向对账**：加页打印 registered、删页打印 pruned，不留死条目；并双向
校验（#page 找不到实例报错、实例未被任何 #page 引用也报错）。

## U4 门禁补强（35 个钩子）
新增 font-charset 钩子（scripts/check_font_charset.py）：复用
tools/font_gen 的同一套提取与 cmap 解析规则（importlib 直载，零第二套
规则），A 段查源码在用 vs 字符集、B 段查字符集 vs 字体 cmap。
registration-check 补第 ④ 类：实测原规则对"进了两端构建但没接描述符表"
的页面**全绿**——desc 被链接器剥离、编译链接全过、菜单永远打不开的死代码。
仍照不出的两项已如实写进文档（枚举漏加归 @build、菜单树漏挂归 golden）。

## 字体子集瘦身（D 案，4 留 3 删）
ui_cn_chars.txt 122→119 字（恰删 上/电/重，零新增）。异/常/片/芯 进
KEEP_EXTRA 带理由白名单：它们曾在 9eb1bd63 被写进中文自检描述落盘
/log/selftest.log（定长 64B 记录跨固件持久），删字形会使历史故障记录
渲染空白且不可逆。保留字按**必需**处理，反向有牙——谁只跑 extract_cn
把它们静默洗掉，钩子直接 FAIL 并逐字打印理由。
--strict 口径为"未知冗余 = 0"而非"冗余 = 0"。

## 验证
@build 0 错 0 警；ER_IROM1 232,052 B（较 HEAD −228 B）、RW_IRAM1
75,232 B **零增量**、RW_CCM 87.9% 未变。golden：菜单 8 状态全像素一致 +
内容页 11 页逐字节一致，**参考图 sha256 差异 0 条**（未用 --update 刷
基线）；池水位菜单基线 5368 B、开页-关页往返 5448 B 与 U1 时相同。
38 个在途修改文件逐个核对 BOM/CRLF/U+FFFD 全部与 HEAD 一致。
L0 33 钩子 + L0.5 16 runner / 1104 断言全绿；check_doc_links --all
142 篇、无法判定 0；mem-budget / mem-numbers 已回填。

## 单位成本实测（U5 排期依据）
临时页 zzprobe 绑到"遥信量"叶子 → 只跑生成器 → 带页 @build 0/0 →
注册表出现 {5u, &ui_page_zzprobe_desc} → 回滚后 6 个产出文件 zzprobe
残留计数均 0、重编回基线。
**结论：新增一页 = 3 处人工（新 .c + 新 .h + 菜单树那一行加
 #page=<名>）+ 1 条生成器命令，手工编辑注册文件 0 处。**
据此修正报告原口径"8 处降到 1 处"——那个 1 只在"1 处对既有文件的修改"
意义下成立，页面自身 2 个文件本就要写，真实处数是 3。

## 文档同步与两处自我修正
§0.1 UI 行 B → B+；§6.1「内容页」「设计令牌」两行按实况回填；§6.5 U1/U3
状态更新；§6 顶部加"建议栏不可照抄"总警示（本轮四次证伪：ui_port.h 已有
同名宏、LV_COLOR_BLACK/WHITE 不存在且极性反了、27 页实为目标页数现存 7
个、生成器草图漏密码页非节点绑定）。
两处改口：① §6.5 U4 从我上一版**误写的 3/3 改回 2/3**——"golden 脚本早已
存在"不等于"已进自动门禁"，两个 golden 脚本至今未挂 pre-commit，该缺口
单列为待办；② 原计划"分三笔提交"**作废**，U1 与 U3 改同一批文件、文件内
交叠，硬切会产生不可编译的中间态，故整波一笔。
 2026-10-20 21:14:14 +08:00
wandering1 720f841494 fix(storage): dhara 移植层 is_free 整页精度 + HAL 越界守卫；日志读写批量化 
登记簿 N-21（报告 N-12/N-13）与 N-24（报告 N-16）两项未闭环问题修复并销项。

N-12：dhara_nand_is_free() 旧实现只读页首 64 B 判全 0xFF，会把"页首
0xFF、后段有数据"的已编程页误判空闲，dhara 遂往已编程页再编程 = 位碰撞、
journal/map 指向垃圾且不报任何错。改整页扫描（栈上 64 B 分块、页首命中即
早退，故"已编程且页首有数据"的绝大多数页成本与旧实现同价）。

N-13：报告原建议经核对不成立——本仓裁剪版 dhara 既无 DHARA_NO_PAGE（哨兵
实为 DHARA_PAGE_NONE，journal.h:46）也无 DHARA_E_UNSUPPORTED（error.h 枚举
里没有，照抄直接编译失败），且 map.c 三处 dhara_journal_copy 调用点各自已
挡掉哨兵。真风险是移植层零上界校验：越界页号被芯片地址位截断成某个真实页
→ 静默读写错页。改为六个 HAL 入口统一几何上界守卫 + DHARA_E_CORRUPT_MAP。
错误码选择是刻意的：BAD_BLOCK 会让 journal.c:904 标坏无辜好块，RECOVER 会
让 map.c:275 启动回收；无错误通道的 is_free/is_bad/mark_bad 一律取保守值。

N-16 写侧：一次排空合并成"每文件一次 open/write/close"（≤8 条 = 512 B
静态缓冲）。掉电语义不变——批次仍在同一次 drain 调用内 close，而 close
回写目录项这个不同 LPN 会把 FTL 单页写回缓存逼出到 NAND；失败尾部回投
队列，条目不丢（旧实现 -2 卷忙会直接丢掉那一条）。容量轮转仍只在按条慢
路径做，批量路径发现装不下一批就返回 -3 退回。
N-16 读侧：s_read_raw() 加 8 条滑动读窗口 + 写者代数失效，API 与 UI 零改动。

验证：@build 0 错 0 警（Code 213,540 / ER_IROM1 232,280 B = 22.2%，
RW_IRAM1 75,232 B = 57.4%，ZI +1,640 B 全为静态缓冲、不吃任务栈）；
@test PASS，且台架 journal 恢复点与修复前同轨——连续四次启动 sectors used
恒 14,094、Map head 每轮 +128 单调推进、epoch 稳定 3 → 整页 is_free 未
改变恢复语义、无双编程、无回退；stack_report 9 个任务全 PASS（defaultTask
静态最坏链 3,024 B / 余 40%，实测峰值 2,164 B / 余 57%）。

新增主机侧移植层单测 test/host/nand_port/（第 16 个 -unit-test 钩子）：
RAM 假芯片 + 真实 dhara map/journal 源，149 断言，含"旧算法只看页首 64 B"
对照用例（将来有人把 is_free 改回去会立刻红）与 dhara 级 resume 双编程计数
为 0 的场景。L0.5 由 15 runner / 955 断言 → 16 runner / 1,104 断言。

文档：存储架构说明 §5.3 加移植层两条硬约束；运行与自检记录设计说明
§4.4/§4.5 写批量化与读窗口；GD5F Trap Records 新增 Trap 07（含三条遗留
代价与一条待办编译期断言）；登记簿 N-21/N-24 删行销项并同步 README
§1/§2.0/§2.1、排期详述 C3、报告 §0.1/§0.2/§0.4/§4.x/§7 与去处表；
钩子计数 33→34、主机侧单测 15→16 全库同步。
 2026-10-15 12:34:39 +08:00
wandering1 2a6080827d docs(网络): 自愈架构 §4.1 形态详解 / §4.10 读即清审计 / §1.5 横向对照 
四块内容，都是"把已经做完的事写进文档"，无新增设计。

1. §4.1 形态表扩成 6 小节：两个所有者 / 四个词 / 形态表（补"芯片命令"列与
   U11 独立行）/ 每个形态为什么长这样、怎么验的 / 为什么 ①③⑤ 常态 0 命中 /
   M3 可疑门与沿革。
   ⚠ 修一处文档 bug：原 ④ 行实际描述的是 U11，真正的 ④ 没有行。已补 U11
   独立行，并在 ⚠ 注记里记录这次更正及其 U12 后果。

2. §4.10 读即清信源审计：两个读即清寄存器与两级门控、现存读清点全量清单
   （产品代码 6 处）、已根除的三条互吞实例、一处"看着像缺陷其实是配对
   消费"、新增一处读清的三条准入判据 + 结构性残余。AGENTS.md 的 CH395F
   单连接 socket 条目加指针。

3. §1.5 与主流 offload 驱动的代码级对照（正面回答"是不是过度设计"）：
   ioLibrary close()/listen() 原文、四个机制一一映射、三条约束差异表、
   "死等把代价挪到运行时"、lwIP/Zephyr 对照、诚实清单（可省 16 B / 不可省
   沉降窗 + D10 + listen 前排清 + 登记执行分离）、唯一杠杆是芯片。

4. 模块归属修正（承接 63cf73b 的 net_events.c 抽出）：
   - §11.5 新增一节，含"为什么是一个模块而不是两个"（对账真实调用事件
     处理器 2 处 + NET_RECON_STABLE_DEATH 两边共用）与三处非纯搬移；
   - §9 行数快照更新，并加警告：这类快照**当天就会漂移**，是地图不是判据；
   - §1.5 的 net_listener.c 行数随注释精简同步（508/277 → 386/155）。
   引用修正波及 5 个文件：BSD_Socket_API 使用指南文件职责表（拆出
   net_events.c 行）、函数调用关系 §4.8 标题、Net 层阻塞模型两处形态⑤表格、
   CH395F_Trap_Records 两处"对应文件"（保留"原在 net_socket.c"的历史）。
   ⚠ doc-links 只校验 § 编号存在性，照不出"函数在哪个文件"——这类归属
   漂移门禁不拦，必须人工扫。

验证：check_doc_links --all --sections-strict PASS（2146 处引用，可判定
1263，无法判定 0，142 文档）；ci_local L0 32 钩子 + L0.5 953/953 全过。
 2026-10-14 18:18:06 +08:00
wandering1 e95d2be30b docs(任务规划): 新条目改用语义标识——"编号不回收"在实践中不可执行 
登记簿原规则写着"编号不回收"（README §0 与 §3 各一处），但销项 = 删行，
删完仓库里就不留任何痕迹 → 该规则要靠人先想起去翻 git log 才成立。

实测撞号：登记簿 N-31（2026-10-11 的 Phase 7 复跑项）销项后，2026-10-14
新建条目按"现存最大值 +1"又取了 N-31，与 CH395F_Test_Guide.md、
自动化测试流程.md 里那两处历史引用同号。

裁定（用户 2026-10-14）：新条目 # 列填语义短语（如
"沉降窗 800ms 上限只留痕"），不再新增字母+数字编号；存量编号冻结沿用，
已随销项消失的号一律永久作废、不得作为新条目候选。语义标识自带唯一性
（重名一眼可见），从结构上消除复用可能。

改动：README §0 表首新增"语义标识"行 + 撞号因果注记；§3 原"编号一律
沿用且不回收"整条重写；AGENTS.md 完成即销项条目追加本裁定。
已确认无门禁校验编号格式（check_doc_links 只校 §N.M 与文档路径，
脚本里的 N-23/T-1 是注释性出处）→ 换标识不破任何钩子。
 2026-10-14 15:56:54 +08:00
wandering1 a12367981d fix(N34): E14 丢中断复核——芯片不丢事件；listen 排事件挪至 LISTEN 前+全局读收口+全库归因更正 
48 轮直读 SINT 矩阵（8 周期×6 变体）复核历史"丢中断"说法：芯片侧事件
丢失 = 0。归类：drain 读清消费 3/48（drain-int 探针现场抓获）、门控
竞态 2/48、主机同步 1/48、幽灵态 0/48 未复现。

根除性修复：net_listen_locked / net_listener_try 的排事件读清从
listen 后挪至 LISTEN 命令之前——新连接 CONNECT 落进该窗即被本方读清
吞掉，即"数据被吞"的生产侧自伤机制（台架 3/48 为同形态放大版）。

全局读收口：全局中断寄存器唯一读者 = net_poll（I7）；生产/测试/台架
游离全局读全部删除，ch395f.h 声明处加护栏注释。

归因更正：17 文件约 40 处"丢中断"措辞改为"事件未收到/读清消费竞态"
（机制全部保留，仅归因更正）；设计文档 §5.2 新增 E14 锚点；Trap
Records TRAP-NET-17/-20/B3 归因更正段；配图生成器与 SVG 重生成。

台架：事件未收到复核探针保留（drain-int / SINT 补读×3 / 超时归类），
下次跑矩阵自动归类；实验注册（main.c/uvprojx）已完全还原。

验证：@build 0 错误 0 警告；ci_local L0 32/0 + gitlint + L0.5
953/953；doc-links --all --sections-strict 通过；@test PASS（无
[ERR]，net init 619ms）；回归 :7003 300ms×10 = 10/10、:21 n30×50 =
0/50 失败。
 2026-10-14 02:48:50 +08:00
wandering1 09d6195906 chore: 收口已结束会话遗留的本地改动（RAM 台账/AGENTS/SOE 日志）
CI / L0 静态门禁 (pre-commit) (push) Failing after 1m12s
Details
CI / L0.5 主机侧单测 (MSVC) (push) Successful in 17s
Details 
提交此前已结束会话在主工作区遗留、未提交的改动：
- docs/任务规划/ 与 RAM 占用台账、快照的同步更新
- AGENTS.md 索引与 scripts/ram_baseline.tsv 更新
- docs/测试说明/boot_log_data/ 新增 B9 IEC104/SOE 台架日志与解码产物
- .pre-commit-config.yaml 微调

来源为该会话结束时的未提交快照，整体收口便于并入 master。
 2026-10-12 20:10:12 +08:00
wandering1 c077e9a481 merge: 远程 CI 分支 v2-on-ui-ci 合入 v2-on-ui
CI / L0.5 主机侧单测 (MSVC) (push) Has been cancelled
Details
CI / L0 静态门禁 (pre-commit) (push) Has been cancelled
Details 
将 origin/v2-on-ui-ci（13 个提交：远程 CI 文档独立成 docs/CI/、
runner 保活/日志编码/gitlint 空转修复、ci_local L0b 等）合入开发主线。

冲突 5 处，按「两侧意图取并集」解决：
- AGENTS.md / docs/README.md：保留主线 待处理内容.md→任务规划/ 重构，
  并入 CI 分支的 docs/CI/ 索引行与更新日志
- 测试开发标准流程.md §9.1：取 CI 分支，引用改指
  ../CI/远程CI完整指南.md 对应小节
- docs/待处理内容.md：接受主线删除，已重构为 docs/任务规划/
- docs/环境与部署/CI配置指南.md：接受 CI 分支删除，已并入 docs/CI/

合并引入的 doc-links 失效已修（doc-links 合并态走 --sections-strict，
自引用解析失败即硬错误）：
- CI 指南 §0.0 标题把 ⚠️ 移到编号后（编号须打头才解析得出）
- CI 指南对 待处理内容.md 的引用改指 docs/任务规划/登记簿.md T-7 条
- CI 指南并入来源《测试开发标准流程》§9.4 / §9.2 改为全路径限定
- 测试开发标准流程 §9.4：§0.2/§2/§2.4/§4.1.3 原与 CI 文档路径间隔
  超过链式继承上限 40 字符，改为紧跟路径并拆分明细句
- 测试开发标准流程 §9.1：步骤级细节引用同样全路径限定到 CI 指南
 2026-10-12 19:42:24 +08:00
wandering1 0d39cf63b1 docs(b8): B8 销项回填——freq 钩子登记 + 规划 L3-5/P2 置位 + RAM 快照再生 
- RAM 快照再生（合并后 .map）：RW_IRAM1 96,776 B（73.8%）/ CCM 不变 /
  ram_baseline.tsv 追加 B8 行（B8 分支 --no-verify 时欠的两条钩子在此补平）
- .pre-commit-config.yaml：新增 freq-unit-test（31→32）；prot-elm /
  iec104 两钩子 files: 追加 App/algo/freq
- AGENTS.md：钩子计数 32 / 单测 14；算法层行补 freq = L2.5 测频（B8）
- pre-commit 使用说明：§2.21 freq-unit-test 详解 + 计数同步
- 保护规划：§3.3 L3-5 置 ✅（软件侧）、§7 P2 更新、变更记录 B8 行
  （自适应窗三代弯路 0.317→0.197→0.0101 Hz、J1~J6 判据、blob VER 1→2
  换代/损坏分流、prot_elm 7→9、OF/UF 暂只经 YX15 可见归 B10 分点）
- W1 卡：B8 销项删行；M2 注 B8 ✅；mermaid 代码道只剩 B9；
  写范围注更新（B9 sync 时 iec104_test.c 两边叠加）
- 任务规划 README：代码道 B7✅→B8✅→B9
- 合并侧已完成：merge 37f74f0（@build 0/0，L0 全绿）
- 验证：doc-links 全绿（142 文档）
 2026-10-12 19:29:34 +08:00
wandering1 3c7ad9c75c fix(skill): 修正 @build 退出码口径不符（环境错误 1→2、用法 2→3） 
`AGENTS.md` 与 `keil-build` / `new-machine-setup` 的 SKILL.md 一直写着
"2=UV4 未找到/无效（环境错误）、3=用法"，但实现是反的：
- 环境错误走 `raise SystemExit("...")` → **实际退出码 1**（与"构建失败"
  撞号，调用方分不清"编译不过"和"UV4 没配好"）；
- 用法错误由 argparse 抛 `SystemExit(2)` → 恰好占用了文档里"环境错误"
  的位置，于是 `new-machine-setup` 里"报 exit 2 先分清真没设还是没继承"
  这条排障指引**从未生效**。

改法（让实现服从既有文档口径，而非改文档）：
- 新增 `BuildEnvError`；`find_uv4` / `find_project` / `load_config` 失败
  一律抛它，由 `main()` 捕获 → 打印 + 退出码 **2**；
- 覆盖 argparse 的 `error()`（默认 `SystemExit(2)`）→ 用法错误退出码 **3**；
- `run_build` 的档案解析失败原为 `return 3`（用法），实属环境错误 → 并入 2。

调用方安全性：`test/run_all_suites.py` 与 `task-worktree` 的 `run_script`
都只判 `rc == 0` / `rc != 0`，不区分具体码，故本次改动不影响它们。

验证（全部实测，用假 UV4 避免与在途构建争 UV4 与 build 锁）：
| 场景 | 期望 | 实测 |
|---|---|---|
| `--help` | 0 | 0 |
| 成功构建（假 UV4 写 0E0W） | 0 | 0（BUILD_OK） |
| 构建失败（假 UV4 写 `error:`） | 1 | 1（BUILD_FAIL） |
| `--project` 不存在 | 2 | 2 |
| 档案 `uvprojx` 不存在 | 2 | 2 |
| 档案 JSON 解析失败 | 2 | 2 |
| 未知参数 `--bogus` | 3 | 3 |
| 参数缺值 `--timeout` | 3 | 3 |
| build 锁被占用 | 4 | 4（B9 在构建时实测） |

同步更新 `AGENTS.md` 的退出码行（补 2 的完整含义与 4）与 `keil-build`
SKILL.md（记录本次修正的来龙去脉）。pre-commit 全绿。
 2026-10-12 18:49:24 +08:00
wandering1 4bad54b607 merge: master 的远程 CI 修复带入 v2-on-ui（门禁数字改为分支中立） 
把 master 上本轮 10 个 CI 相关提交合入 v2-on-ui，使该分支同样具备可用的
runner 保活与本地门禁自查能力。合并只涉及文档与脚本，零 C 代码改动。

冲突两处，均按"保留 v2-on-ui 新版结构 + 搬入语义"解决：
- AGENTS.md：丢弃 master 侧已被瘦身版取代的旧门禁 bullet，保留其分层边界
  行；把"CI 资料集中在 docs/CI/README.md、只跑本机一台 runner"这条指针
  并入新版 CI bullet 与文末索引表。
- docs/README.md：两侧都是变更记录历史行，按日期先后并列保留。

数字口径改为分支中立：本分支 26 个钩子 / 10 个主机单测套件，master 是
18 / 3，写死任一数字都会让同一篇文档在另一分支上失真。指南 §6 验收第
8 行、§7 排障表、§10 验收标准改为讲规则（报告数 = 定义数 − 1；runner 数
= test/host 下 run_unit_test.py 个数）+ 分分支实测快照。

验证：@build 0 错误 0 警告；ci_local.py 全绿（L0 25 钩子 + L0.5 10 runner
/ 647 断言，fail=0）。首轮 mem-numbers 失败系 master 构建遗留的 .map 所
致，本分支重新构建后即一致。
 2026-10-12 18:28:02 +08:00
wandering1 51bc325b57 fix(stack): N-33 抬栈收口 defaultTask/timeSyncTask 栈余量（2 FAIL -> 0 FAIL） 
既有债收口（非新引入）：B7 定值持久化把 defaultTask 静态最坏链推到
3016 B、timeSyncTask 推到 1264 B，两者跌破 stack_report 判据
（余量 >= max(1024 B ISR, 配置 x 30%)）。本轮只抬栈，不动调用链。

前基线（stack_report，9 任务）：
- defaultTask  cfg 4096 B / 静态 3016 B / 余 1080 B (26%)  FAIL
- timeSyncTask cfg 2048 B / 静态 1264 B / 余  784 B (38%)  FAIL
- 其余 7 任务 PASS（net 2112/1728、ftp 1456/2640、ui 1336/15048、
  test 736/7456、adc 1320/1240、iec104 1456/1104、protect 872/1176）

改动：
- defaultTask 1024 -> 1280 words（4096 -> 5120 B）：余 2104 B / 41%
- timeSyncTask 512 -> 640 words（2048 -> 2560 B）：余 1296 B / 50%
- 后基线：9 任务 0 FAIL（stack_report 退出码 0）

堆开销（任务栈来自 FreeRTOS 堆，.map 静态数字不变）：
- defaultTask +1024 B、timeSyncTask +512 B，合计 +1536 B
- 台架背书基线 heap free=17936 / min_ever=10000 B（B6），抬后
  min_ever 预计 ~8464 B，仍远高于 3072 B 告警线

防丢失（CubeMX 存活 L1 纪律）：
- STM32F407-Demo.ioc 的 FREERTOS.Tasks01 同步改 1024 -> 1280
  （.ioc 是 CubeMX 生成任务栈值的事实源，未跑重生成）
- Src/freertos.c 生成区 .stack_size 与 .ioc 保持一致
- USER CODE BEGIN Variables 核算注释块补 N-33 依据（栈值理由唯一落点）
- .cubemx_survival_baseline.json 经 --write 重建（仅 ioc-task-stacks 一行）

task-table 生成区随栈变更再生成（README.md + AGENTS.md 的
TASK_TABLE 锚点区各 2 行，锚点区外无任何改动）。

验证：@build 0 错误 0 警告（Program Size 与改前逐字节一致）；
ci_local 全绿（L0 + L0.5，826/826 断言）；stack_report 前后各跑一次。
台架 @test 与串口 [STACK] 水位复测在提交后单独跑。
 2026-10-12 17:47:15 +08:00
wandering1 ba40cc0d20 远程 CI 文档独立成 docs/CI/：两篇重叠指南合并为一篇，AGENTS.md 压成一行指针 
动因：远程 CI 只跑在本机一台 runner（win-stm32-ci）上，其他机器与项目都不涉及，
但内容散在 4 处约 2000 行——两篇高度重叠的指南躺在「环境与部署」里与换机核对清单
并列，AGENTS.md 提交门禁节还塞了 4 条 runner 运维经验，导致每次会话都被这些机器
专属细节干扰。

结构：新建 docs/CI/，README.md 作唯一入口（适用范围 + 章节速查 + 常用命令），
远程CI完整指南.md 为合并稿。

- 合并：CI配置指南 477 行 + Gitea_Runner部署指南 917 行 → 一篇 1300 行；骨架内容
  逐行比对核实无丢失（仅章节重编号与相对链接按新位置改写），重复段按"留新版"去重，
  独有内容全部搬入（下载/config.yaml 字段语义/不能用 Windows 服务的根因/内网 action
  三种处置/check_env 自检/TL;DR/排障表 13 条独有行/MySQL 直查核验）
- 再分配：测试流程 §9.2 两个 job 的步骤细节并入指南 §5.5、§9.4 部署前置表并入 §0.2；
  测试流程 §9 只留测试分层视角（覆盖哪些层、触发与 paths-ignore、本地等价、
  "CI 不替代本地门禁"）
- AGENTS.md：4 条 CI 经验（看门狗 / gitlint stage / UTF-16LE / CI 概览）压成 1 行指针
- 引用同步 6 个文件：docs/README 目录树与索引、项目部署环境要求 3 处、本地工具路径
  环境变量方案、待处理内容、scripts/README（补登 3 个 CI 脚本并标注为本机专属）

验证：check_doc_links.py --all 125 篇 0 问题；pre-commit run --all-files 17 项全 Passed。
两篇旧文档以 git rm 删除（历史仍在 git 中）；各文档变更记录的历史行按仓库惯例不改写，
只新增 2026-10-12 行。
 2026-10-12 14:03:44 +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 038e2cfba3 合并后对齐钩子计数：master 已 18 个，并补记 stages 的真实来源 
master 比本分支基线多一个 test-cppcheck 钩子，故"定义数 / CI 报告数"由 17/16
变为 18/17（实测本地跑 --all-files 得 17 条：passed=16 failed=1，那 1 个 failed
是本机 .map 陈旧导致的 mem-numbers，与门禁逻辑无关）。

同时更正一处机制性误述：stages:[commit-msg] 并不在项目配置里，它写在 gitlint
上游的 .pre-commit-hooks.yaml（本机可查证 ~\.cache\pre-commit\repo*\），所以在
.pre-commit-config.yaml 里 grep stages 一无所获、极易误判成"没有限制"。
受影响四处：AGENTS.md、ci.yml 头注释、测试开发标准流程 §9.1、CI配置指南 §6 与
变更记录，另 ci_local.py 文档串。
 2026-10-12 13:09:19 +08:00
wandering1 daee6e05f8 合并 CI 门禁修复：runner 看门狗 + Python/cppcheck 探测回归 + gitlint 提交信息门禁 2026-10-12 13:02:07 +08:00
wandering1 0f0ea03ff4 修复bootstrap注册崩溃：StartWhenAvailable属任务设置而非触发器 
现场：用户以管理员跑 -SetEnv -StartNow 时脚本抛
SetValueInvocationException（触发器上没有 StartWhenAvailable 属性），
而它是在"已注销旧任务、尚未注册新任务"之间抛的，等于把 runner 任务删没了。

- StartWhenAvailable 改设到 settings（MSFT_TaskSettings 继承属性，
  CIM 属性列表里看不见但可直接赋值，实测 StartWhenAvailable=True）
- 任务对象改由 New-WatchdogTaskPlan 统一构建，先构建、后注销旧任务
- Register-ScheduledTask 失败时显式告警"旧任务已删、CI 裸奔"并 exit 1
- 新增 -DryRun：免管理员即可全量校验 action/trigger/settings
- -Status 增补上次运行时间与返回码，并提示"非管理员看不见任务"

同时更正根因：旧计划任务其实一直存在（非管理员会话看不见，先前误判为
"从未注册"），但它跑的是单次 run_runner.cmd——daemon 属"正常退出"而非
"失败"，计划任务的失败重启根本接不到，必须靠看门狗循环重拉。
 2026-10-12 12:52:27 +08:00
wandering1 20ee35b76a 修复CI门禁三因：runner掉线致12个job零日志、L0探测回归全灭、gitlint在CI从不执行 
1) runner 掉线：run 16~21 共 12 个 job 零日志。gitea-runner v4 的
   daemon 无服务支持、首次 Declare 失败即退出进程，Gitea/机器重启
   一次 CI 就静默停摆；叠加 cancel-in-progress 后症状是"任务凭空
   消失"。新增 scripts/ci_runner_bootstrap.ps1：等 Gitea 就绪 +
   崩溃自拉起看门狗 + 开机计划任务 + -SetEnv 写 MACHINE 级 DTU_*。
2) L0 自 33a4aa4 起在 runner 上必挂：Python 候选被收窄成 PATH python
   (msys64，无 pre-commit) + 仓库 .venv(gitignore)，cppcheck 目录兜底
   亦被删，而机器级 DTU_* 从未设置。探测收进 ci_find_python.ps1
   （两 job 共用、可离线自测、恢复机器级安装兜底）。
3) gitlint 声明 stages:[commit-msg]，而 --all-files 只跑 pre-commit
   stage → 17 个钩子定义 CI 只报 16 个且全绿。新增
   ci_gitlint_range.ps1 逐条校验本次范围，ci_local.py 增 L0b 段。
另：GITHUB_ENV/PATH/OUTPUT 写入显式 -Encoding ascii（PS 5.1 的
   Out-File -Append 默认 UTF-16LE，会把带 NUL 的行追加进 UTF-8 文件）
 2026-10-12 12:39:27 +08:00
wandering1 90db528032 W1 功能主线完成：内存台账三件套(W1-0) + IEC104 上行(B4) + protectTask 板端接线(B5) 
W1-0 台账三件套：scripts/ram_baseline.py（四模式）+ ram_baseline.tsv 趋势 +
docs/内存管理/RAM预算台账.md + pre-commit mem-budget 钩子（RW_IRAM1/RW_CCM >92%
即 FAIL + Top-10 附表）；审查报告 §5.5 三条闭环。

B4 IEC 60870-5-104 上行（被控站，TCP 2404）：App/protocol/iec104/ 三模块
（asdu 编解码 / pts 点表+数据源 vtable / link APCI+FSM，纯逻辑零 I/O）+
App/task/iec104_serv.c（iec104Task，NET_READY 屏障 100ms 分片喂位）。
82 断言 L0.5 全绿 + iec104-unit-test 钩子（第 31 钩子）；
设计说明 docs/子系统设计/IEC104上行设计说明.md 全量回填。

B5 protectTask（L3 板端接线）：App/task/protect_task.c——20ms 判据节拍
prot_elm_run + L5-4 采样故障闭锁（adc_health 电平位→元件复位）+ L5-1 定值
校验和巡检；新增 prot_elm_request_reset() 收口跨上下文复归（104 YK11 落请求、
eval 头部消费）；定值/元件初始化移入 app_main_init（内核前）。TC-PE-010
（prot_elm 28 用例）。

门禁与内存：TASK_WD_PROTECT=8 入 required_mask（产品 0x77→0x1F7、HW 层
0x1F5，看门狗单测 39 断言同步）；FreeRTOS 堆 48→56KB（.ioc L1 参数 +
FreeRTOSConfig.h 同步，RAM预算台账 §6 登记配额 48→56KB）。
ZI 144,008→152,204（+8,196 B = 堆 +8KB，B5 扩容）；Code=204,348。
stack_report：protectTask 512 words 静态链 872 B/余 57%、iec104Task
640 words 1456 B/余 43% 均 PASS；RW_IRAM1 73.1% / RW_CCM 87.9%（<92%）。

验证：@build 0 错 0 警；ci_local 全绿（31 钩子 + 13 主机侧单测）；
doc-links 135 文档 PASS。登记簿 B4/B5 销项、W1 波次完成；保护规划/看门狗
说明/AGENTS（9 任务）/RAM 三文档全部同步。

遗留（验收窗口，非代码空洞）：台架第三方 104 主站往返（送检窗口）、
标准源注入动作判据、@test PROT 锚点 + protect 栈水位 + 新堆 min_ever 复测。
 2026-10-12 12:36:23 +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
wandering1 d1e6bb4ba7 W5波+N-19收口：FTP鉴权落地、Trap25三连定案修复(N-30)、N-20/N-23/N-26 
N-19 FTP 鉴权：
- lftpd_auth（USER/PASS 状态机 + 连续5次失败锁60s）+ SHA-256
  (user||pwd) 口令哈希；config.ini [ftp] 段 user/pwd_hash/write，
  出厂 admin/admin 在用有启动告警；lftpd_log.c 删除并入 lftpd_auth
- ftp_cfg 配置读写；台架 ftp_auth_bench.py 13/13

N-30 / Trap 25（CH395F_Trap_Records.md 四次定案全记录）：
- 修复1 closed-with-data accept：客户端发完正常 FIN 后芯片按
  FUN_PARA(0x09) §5.52② 保留 Socket+RX 缓冲，旧代码把 CLOSED 一律
  relisten 自毁缓冲 → STOR 必挂 425；改为接受"已关但可读"连接排空
- 修复2 丢 CONNECT 中断探针 net_lost_connect_probe + last_peer_port
  幽灵甄别（拆链窗口握手完成但中断丢失，双信源去抖补 accept）
- 修复3 send_list/send_nlst 批量单发：背靠背 ~60B 小段毒化芯片 TX
  （芯片报 SEND_OK 但对端全丢），整份目录一次性写入
- 证伪存档：固定沉降/Socket 轮换冷却/listen 门控（台架 v7 矩阵）
- 台架工具 test/board/ch395f_reuse_bench.{c,h} + host 脚本存档
  （不注册编译；实验分支 n30-chip-bench 保留）

N-20：Error_Handler 死循环降级（记录+复位路径）
N-23：scripts/check_registration.py 双端注册反向校验（pre-commit）
N-26：GD5F NAND 直 DMA 调用方缓冲窗口断言

验证：BUILD_OK 0/0；ftp_regression 连跑 4 轮 11/11（修复前
LIST#4/#7 100% 挂、STOR#2 曾 100% 425）；ftp_auth_bench 13/13；
@test 启动标记 PASS；ci_local L0+L0.5 全过；doc-links 通过。
登记簿 N-30 已销项。
 2026-10-11 18:50:24 +08:00
wandering1 eddbedeee8 docs(AGENTS): 入口重构——补宏观概况与边界块，瘦身51KB→25.8KB，子域知识入skills
CI / L0 静态门禁 (pre-commit) (push) Has been cancelled
Details
CI / L0.5 主机侧单测 (MSVC) (push) Has been cancelled
Details 
- AGENTS.md 51,067→25,828 B（−50%）：审计→迁移→删除，逐节 diff 零信息损失
- 按调研（agents.md 官方/aihero/airflow）补「项目概况」：一句话定位、
  数据主线、顶层目录地图、分层边界；平台约束 17 条分 5 组
- 新增「边界（Ask first / Never）」：git commit/push 须明确指示首次入库
- 串口助手、LVGL 模拟器两节移入 serial-assistant / 新建 lvgl-simulator skill
  （开关语义按 main.c 实锤）；LVGL 两条实证坑移入 ui-verify skill
- 9 条入口独有细节迁移至对应设计文档（存储/看门狗/启动顺序/文档规范/
  pre-commit 使用说明/keil-build skill）；@test 细节指向自动化测试流程
- 新增 docs/AGENTS编写指南.md：六原则/模板/反模式/维护纪律 + 本仓案例
- 修正 3 处对 AGENTS 串口节的过时引用；docs/README.md 登记新文档
 2026-10-11 10:44:50 +08:00
wandering1 c936441c83 门禁扩容：新增 lv-conf-sync、simulator/ 纳入全部钩子；含 L3 定值/元件框架落地 
本轮把"自研代码落在门禁之外"的口子收掉，同时落地 LVGL 特性裁剪与
L3 保护定值/元件框架。

门禁（.pre-commit-config.yaml，26 个钩子）
- 新增 scripts/check_lv_conf_sync.py + 钩子 lv-conf-sync：比对两份
  lv_conf.h 的**生效值**（未定义则取 lv_conf_internal.h 兜底默认），
  抓 MISMATCH / LVGL 不认的宏名 / 同文件重复定义
- 顶层 exclude 删掉 simulator/：其下 21 个 tracked 文件全是本项目自研
  代码，生成物（build/、SDL2/、tests/ref/、shot*）已在 .gitignore；
  doc-links 的 exclude 同步删除
- lv-conf-sync 的 files: 覆盖两端配置 → 只改 simulator/lv_conf.h 也触发
  （pre-commit 4.x 已移除 always: true，实测只告警并跳过，无兜底开关）
- 新增 prot-set-unit-test / prot-elm-unit-test 两个主机侧单测钩子
- S11(2.3.5) 判定细化：禁的是"用路径找文件"，尖括号系统头带子目录
  （如 <sys/stat.h>）不再误报；全仓库复核仅 2 处项目代码判定变化

模拟器代码整改（纳入钩子后暴露，全部修代码而非豁免）
- cppcheck 4 处：sim_syslog.c 判空分支内解引用 p_epoch（真实 bug）、
  2 处 struct tm 未初始化、1 处指针可加 const
- coding-standard 61 处：44 处函数左大括号并到右括号同行、8 处补函数
  注释、3 处补文件头注释块、2 处 __ 前缀保护宏改 XXX_H、2 处 sprintf
  改 snprintf（写入字节数与原来完全一致）

LVGL 特性裁剪（F-1/F-2/F-3）
- 两端 lv_conf.h 对齐同一特性子集：删 26 个 LVGL 9.3 不存在的选项名、
  3 处重复定义，10 项靠默认值隐式生效的改为显式固化
- 实测对镜像体积中性；价值在防漂移，且模拟器 golden 回归跑的正是固件
  实际编译的配置

L3 软件侧
- App/algo/prot_set.* Q10 定值模型（范围校验 / 整表 all-or-nothing /
  校验和封存-自检-闭锁）+ prot_elm.* 通用"滞回+定时限"元件框架 7 实例
- test/host/prot_set、test/host/prot_elm 主机侧单测；uvprojx 挂载两处

文档同步
- pre-commit使用说明：§2.8 S11 口径、§2.15 lv-conf-sync 详解、新增 §5.5
  复盘（教训：exclude 只写真正不该进钩子的路径）
- AGENTS.md、UI_设计架构 §1.4 第 10 条、RAM 分析、审查报告刷新与销项

验证
- @build BUILD_OK 0/0（Code=194276 RO=15872 RW=876 ZI=139892）
- 模拟器重建：菜单 8 状态像素逐字节一致（池 5368 B）、11 内容页黄金参考
  全过（往返 5448 B）、remo sink 0/25600 位差异、--logtest/--cfgtest PASS
- 全仓库 cppcheck / coding-standard / no-mojibake --all-files 全过
- check_doc_links --all 129/0；check_mem_numbers --check 内存数字一致
- 端到端：往 simulator/lv_conf.h 注入一行漂移 → 钩子 FAIL（exit 1）
 2026-10-11 08:48:49 +08:00
wandering1 13a4e61c27 L1-6 采样有效性校验：adc_health 判定层 + 告警编排 + 31 用例单测 + 台架闭环 
新增 App/algo/adc_health.c/h（纯逻辑判定层，零平台依赖免桩单测）：
- 静默：两侧帧序号连续 >=100ms 无前进（电平位可自愈，flags() 为 L5-4 闭锁预留）
- 丢帧：TPAFE 序号一次前进 >1 计 tgap（与 STM32 侧 adc1_gap 对称，边沿事件）
- 单调性：序号倒退锁存位；tick/计数差值法 (int32_t)(a-b) 回绕安全
- 错误增量：FRSTDATA / HAL 错误 / STM32 停摆计数增量，事件位与锁存位编号对齐，
  消费者按位图做"每类每次开机留痕一次"编排

adc_task.c v2.9 告警编排（判定与编排分离）：严重事件/电平上升沿 DBG_ERROR +
SYSLOG_SELFTEST（每类每次开机一次防刷屏），下降沿 DBG_INFO 恢复；gap 不告警
（消费者超拍是已知现象，告警会淹没真故障）；心跳行增 tgap 观测字段。

主机单测 test/host/adc_health/ 31 用例全绿（100ms 门限两侧 / 边沿语义 /
倒退锁存 / tick 回绕 / NULL 守卫 / init 幂等），登记 adc-health-unit-test 钩子。

台架 @test PASS：零 [ERR]（健康不误报）、tgap=1->2 与 adc1_gap 同步可见、
frames 1000.0 Hz；证据 boot_log_data/20261011_prod_adc_health_boot_log.txt。

抬栈：adc_health_report->syslog_post 控制台回显尾使 adcTask 静态最坏链
832->1080 B（512 words 余 968 B < 1024 B ISR 底线）-> 512->640 words，
复测余 1480 B / 57%，堆 min_ever 7152->6640 B（-512 B 符合预算）。
AGENTS/README 任务表、RAM 方案 §2.3、规划文档 §3.1 L1-6 已同步置完成。
 2026-10-11 01:28:20 +08:00
wandering1 9bbe117f97 adc: 节拍源 TIM6->TIM3 + ADC1 走 DMA 乒乓双缓冲，消除 2 ms 忙等（P1-5 单拍硬上界办结） 
用户选定最彻底方案（B2）：DMA + 定时器 TRGO 硬件触发 + 消费上一拍
已完成的半区。对应 P1-5 拆出的"单拍硬上界"，现已办结。

硬件事实更正（查 CubeMX 器件库 + 本仓 HAL 头证实）：F4 上 ADC1 的
外部触发清单里没有 TIM6/TIM7 TRGO（只接 DAC）。故 1 kHz 节拍源由
TIM6 改为 TIM3（PSC 83 / ARR 999，TRGO=UPDATE），同一个更新事件
同时 ① ISR 脉冲 TPAFE CONVST ② 经 TRGO 触发 ADC1 一轮 9 通道
③ 置位 ADC_WAKE_FLAG 唤醒 adcTask。TIM6 从 .ioc 整体移除。

代码：
- Src/tim.c/h：新增 MX_TIM3_Init（含 MasterSlaveMode），删 htim6
- Src/adc.c：ExternalTrigConv=T3_TRGO + EDGE_RISING +
  DMAContinuousRequests=ENABLE；MspInit 挂 hdma_adc1（DMA2_Stream4
  循环模式）。DDS 位关掉 = 一轮只发一次请求，静默丢 8 路
- Src/dma.c：DMA2_Stream4 NVIC 优先级 6（CubeMX 换流会把它重置为 0，
  优先级 0 会抢占 FreeRTOS 临界区，违反"外设中断 ≥5"）
- Src/main.c：周期回调加 TIM3 分支；stm32f4xx_it.c 向量同步
- App/algo/adc_input.c：stm32_scan() → stm32_take()，逐通道
  PollForConversion 全删；乒乓半区由完成计数奇偶推出（只读一个
  32 位量 → 与 ISR 无竞态）；STM32 侧数据固定滞后 1 拍
- App/task/adc_task.c：心跳日志拆出四类计数

观测性：adc1_seq（完成计数）/ adc1_gap（seq 前进 >1 = 丢帧）/
adc1_err（连续 ≥2 拍无新帧 = 停摆）/ adc1_hw（HAL 错误回调）。
单拍无新帧是消费者相位伪影（DMA 完成落在唤醒后 ≈67 µs），不计故障。

验证：
- 主机单测 79 → 101 全绿；反向验证四连均咬（半区奇偶取反 11 条、
  停摆拍置 valid 4 条、STALL_RUN_MAX 改 1 为 6 条、gap 阈值 1 条）
- @build 0 错 0 警，Code 256872 → 257660
- @test PASS：adcp 122 µs → 8 µs、adc1_err=0、adc1_hw=0、
  adc1_gap=27/20002 拍、adc1_seq 与 seq 恒定偏移 2
- stack_report 7/7 PASS，adcTask 832 B / 余 59%（不变）
- cubemx-survival 新增 5 项审计（TIM3 分支 / T3_TRGO / DDS /
  DMA 挂载 / 流优先级），28 通过 0 失败

文档：ADC 采样节拍设计说明新增 §11；看门狗停摆分析 §4.4 与 §8 收口；
算法规划 L1-1/L1-3、通道映射、测试说明、各 README 同步。
 2026-10-11 00:31:33 +08:00
wandering1 9231a3c22c adcTask 事件驱动消费（P1-5 方案 a）+ 补 F4 ADC 上电自校准 + 修正 2 ms 忙等过期表述 
P1-5 方案 a（事件驱动消费，Task #32）：
- TIM6 1 kHz ISR 除触发 CONVST 外再调 adc_tick_irq_notify()，置位
  ADC_WAKE_FLAG；adcTask 循环尾改 osThreadFlagsWait(osWaitForever)，
  删除 ADC_TASK_BEAT_MS 定时轮询
- adcTask 优先级 Normal(24) -> AboveNormal(32)（Src/freertos.c USER CODE 区）
- 补消费者就绪门（规划未预见）：TIM6 在 app_main_init 就启动，比调度器
  早约 100 ms，未就绪时 ISR 不得 osThreadFlagsSet
- 实测 6 次上板：idle 由 1~649 降到 0/20000 拍，frames 1000.0 Hz，
  seq-frames=7 正是就绪窗口；UI 侧 uip/uiw/uis 无退化

补 STM32F4 ADC 上电自校准（此前项目从未做过）：
- 核查证实裁剪版 HAL 无 HAL_ADCEx_Calibration_Start、裁剪版 CMSIS 头无
  ADC_CR2_CAL -> 按 RM0090 13.3.6 在 Src/adc.c 的 USER CODE 区手写
  adc1_calibrate()，MX_ADC1_Init() 末尾调用
- 新增 cubemx-survival 审计项 adc1-calibration-call / -impl（清单 21->23）
- 实测校准前后同一拍 STM32 侧 6 路同向偏移 +10~+63 LSB，TPAFE 侧不变

修正两处过期表述（实测反证）：
- 原文 9 通道全超时最坏 = 18 ms 连占 有误：stm32_scan() 在首个超时处即
  Stop+return，单拍上界 = 一次超时约 2~3 ms
- adcm 约 2.1 ms 的峰值归因由 ADC 采集改判为每 10 s 一次的心跳日志；
  6 次对照 adcp = 122 us（无超时）/ 2209 us（超时 1 次）
- 同步修正 adc_task.c 两处过期注释；新发现超时拍 STM32 侧静默沿用
  上一拍值的正确性代价，硬化排序记入 4.4 / 10.4（未实施）

验证：@build 0 错 0 警（Code 256728 -> 256868）；@test 6/6 PASS；
stack_report 7 任务全 PASS（adcTask 832 B / 余 59%）；18 钩子全绿
 2026-10-10 22:41:19 +08:00
wandering1 5009a844a9 收敛 reset.bat 到 stlink-flash skill 并删除该批处理
CI / L0 静态门禁 (pre-commit) (push) Has been cancelled
Details
CI / L0.5 主机侧单测 (MSVC) (push) Has been cancelled
Details 
stlink_flash.py 新增 hard 子命令（-c SWD RM=Hrst -HardRst PULSE=100），
RM= 被 CLI 拒绝时自动降级为系统复位并打印 RESET_NOTE；至此 reset.bat 的
全部子命令（复位/hard/halt/run/list/flash/cmp）均已由 skill 覆盖。

删除 MDK-ARM/reset.bat（git rm）。@build/@download 两条旧批处理入口至此
全部收敛到 .dsh/skills/ 下的 skill，一个能力一个实现。

同步更新引用：AGENTS.md、README、MDK-ARM/README、7 篇 docs、4 个 skill
（stlink-flash/serial-boot-test/new-machine-setup 及 config.example.json）。

真机验证：hard 子命令 RM= 被拒 → RESET_NOTE → 回退系统复位 → STLINK_RC=0。
 2026-10-10 16:41:46 +08:00
wandering1 5defabcabb build: 删除 MDK-ARM/download.bat，烧录收敛到 stlink-flash skill 
- test/run_all_suites.py 是唯一执行它的地方：DOWNLOAD_BAT 改为 STLINK_FLASH
  （.dsh/skills/stlink-flash/scripts/stlink_flash.py）；直烧改
  [py, STLINK_FLASH, "flash"]（原先把 .bat 包给命令行解释器执行）；
  --flash-cmd 改由同一常量拼出，不再硬编码 .bat 路径
- 机制变化（须知晓）：原 download.bat 走 UV4 -f（CMSIS-DAP），现走
  ST-LINK_CLI -P <hex> -Rst -Run —— 与 .serialtest/config.json 的
  flash_cmd、AGENTS.md 烧录铁律、回读 -CmpFile 要求同源；6.5s/1MB
  也快于 UV4 路径
- AGENTS.md / 环境与部署 3 篇 / ST-LINK_CLI 复位说明（原文写"正式流程仍以
  download.bat 为准"，已反转）/ 自动化测试流程 / 串口助手设计说明 /
  链路延迟 / m2_data / README / MDK-ARM/README：引用改指 skill
- .gitignore：download_log.txt 条目保留并注明 legacy（他机残留物不变
  untracked）；build 日志注释同步
- 保留 MDK-ARM/reset.bat：其 hard/halt/run 子命令是 skill 没有的
- 刻意未改：docs/问题记录/项目审查与优化建议报告.md 的 P2-15（史实）
- 验证：run_all_suites.py --dry-run 解析出 skill 路径；doc-links 123 通过
 2026-10-10 16:28:58 +08:00
wandering1 c77c5824f9 build: 删除 MDK-ARM/build.bat，@build 完全收敛到 keil-build skill 
- test/run_all_suites.py 是唯一真正执行它的地方：BUILD_BAT 常量改为
  KEIL_BUILD（.dsh/skills/keil-build/scripts/keil_build.py）；两处构建点
  改传 --timeout（脚本内超时先于 _run 超时触发，超时得 rc=1 + BUILD_FAIL
  文案，而不是被 _run 杀掉）
- AGENTS.md / keil-build SKILL.md / new-machine-setup SKILL.md：删除
  "等价原生入口"口径，改为注明该文件已于 2026-10-10 删除
- 环境与部署 3 篇 / 项目架构总览 / README / MDK-ARM/README /
  download.bat 注释 / check_mem_numbers.py 提示串：移除 build.bat 引用
- 刻意未改：docs/问题记录/项目审查与优化建议报告.md 的 P2-14 / N-18
  （历史审计条目；doc-links 不校验裸文件名，保留不影响门禁）
- 验证：keil_build.py --timeout 300 -> BUILD_OK / rc=0；
  run_all_suites.py --dry-run 正确解析 skill 路径；doc-links 123 文档通过
 2026-10-10 16:23:54 +08:00
wandering1 7a54fdbc73 docs(build): @build 统一为 keil-build skill，build.bat 降为等价原生入口 
- AGENTS.md 构建条：@build = keil-build skill（写明 UV4 解析链、退出码
  0/1/2/3、日志路径）；MDK-ARM/build.bat 明确为等价原生入口，并列出
  它相对 skill 缺的三项（无超时保护 / UV4 只认 DTU_KEIL_UV4 / 失败 dump 整份日志）
- keil-build SKILL.md「本仓库」段同步：skill 即 @build 口径
- 3 个 skill（new-source-file / ui-verify / new-machine-setup）与 8 篇
  docs、README、MDK-ARM/README、环境与部署 3 篇：命令示例与 @build
  标识统一改指 skill
- scripts/stack_report.py 的构建提示串改指 skill
- 环境与部署：DTU_KEIL_UV4 使用方补 keil_build.py；反向测试期望的报错
  文案对齐 skill 实际输出（BUILD_ENV_ERROR: ... is set but not a file）
- 刻意未改：docs/问题记录/项目审查与优化建议报告.md 的 P2-14/N-18
  历史审计条目（属史实记录）；test/run_all_suites.py 的 BUILD_BAT
  常量（是代码、非文档，改动需另做验证）
 2026-10-10 16:19:14 +08:00