Commit Graph

8 Commits

Author SHA1 Message Date
wandering1 e4981aa2f6 refactor(docs): point entry-file references at their new homes
AGENTS.md stopped being the store of record for build steps, Python env,
hardware pins, doc conventions, log cost and task ownership. Those facts
already live in docs, skills and role files; the entry file now only
points at them. This commit moves every reference that used to name the
entry file to the authoritative landing point, so a reader who follows a
link arrives at the fact instead of at a sentence that no longer exists.

What changed is links and prose, not behaviour. Code, scripts and tests
only have comment and docstring lines touched; the only non-comment edit
in the whole changeset is one note string inside the generated pin table
JSON, and its generator was changed in the same step so the two stay
byte-identical.

New landing points created before the references were retargeted:
- The console single-writer log design doc, section 7.1, is now the single
  authority for log cost: about 90 B flash and 216 B stack per DBG_ line,
  and the rule that deep call chains must predefine DBG_LINE_BUF_MAX.
  It also carries the full list of the twelve translation units that have
  tightened it, plus the grep command that decides the truth if the list
  and the code ever disagree.
- The document writing standard, section 2, now holds the BOM list.
- keil-build skill gains an exit code table: 0 success, 1 build failure,
  2 BuildEnvError, 3 usage, 4 build lock held. This corrects a belief
  that was never actually written down anywhere: exit 2 does not simply
  mean environment error, argparse also exits 2 and the wrapper script
  was remapped so the two no longer collide.

Regenerated and checked byte for byte:
- The end-to-end architecture SVG in docs/images from its generator.
- tools/netlist_semantics/pinout_kb.json from gen_kb.py.
Both are idempotent; running the generators again produces no diff.

Deliberately not touched, because machines read them:
- scripts/check_bom_drift.py joins every line containing BOM and asserts
  four paths are present, so the entry file BOM line must stay one line.
- scripts/gen_task_table.py reads the TASK_TABLE anchors directly.
- scripts/rename_maps and scripts/archive keep their historical wording;
  they describe what happened, not what is true now.

Verified: doc links report the same six pre-existing findings as the base
commit and no new ones, generated-fresh passes, bom drift is clean across
101 files, and AGENTS.md itself is unchanged in this commit.
2026-11-16 19:38:27 +08:00
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 94cce8b615 docs+scripts: 删除测试与架构专项文档并把引用改成就地口径
这是并行的另一路在飞的改动(本会话按用户「全部提交」指示代为落盘):
移除 docs/任务规划/测试与架构专项.md,并把指向它的引用改成就地口径
(app_assert.h / net_socket.c / ch395f_test.h 头注释改指本文件注释或
对应文档,check_size_gate.py 与 ram_baseline.py 的出处改指 CI 文档,
RAM预算台账、暂缓-RS485、采集与算法层设计说明、cubemx-survival、
id-check、两份 README 同步改引)。

如要拆回:git reset --soft HEAD~1 即可把这一笔退回工作区。
合树后 @build 0 错 0 警(Code=236456 RO=28124 RW=1876 ZI=137084)。
2026-10-28 22:00:34 +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 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 4c05b58f3a feat(tools): v5 判读工具 v1.1——MISS 降级诊断行,违规只看 stall 与嫌疑段
道F task-22(F1,大窗判读三票之首)commit 1/2。违规口径改造:
violation := task stall>0 或 真停滞嫌疑静默段>0;MISS start 自 v1.1 起整体降级
为诊断行(看门狗 v1.5 按位分账后它只是复合缺席边沿,不代表停喂,设计说明
docs/子系统设计/看门狗设计说明.md §6.1)。v1.0 把运行期 MISS 计入违规是我在
task-19 把判读口径收紧过头——2026-10-25 台架 70min 窗 1262 条运行期 MISS 经
逐窗归因实为重建风暴复合边沿(456 条贴探针窗)+ FTP 传输窗抖动(632 条),
非心跳丢失,予以纠正(当轮 FAIL 判定的误伤面即此)。

【新增输出】MISS 归因诊断(人读 + --json miss_diag):开机良性 / 探针窗内 /
窗外运行期 三分类 + 窗外每分钟速率 top5;counters 同步扩字段,旧字段
(miss_runtime 等)保留不动,既有 JSON 消费方零破坏。stall 行文本不变,
语义注释更新 = v1.5 起每行都是「同一任务 800ms 单串」真猎物。

【自检】--selftest 15→18 断言:新增 v1.1 回归钉 = 零 stall + 运行期 MISS 样例
必须 PASS,且归因计数(探针窗内 1 / 窗外 1)与分钟分桶正确;PASS 文案与新
口径同步(改口径先改文档再改脚本的漂移闸语义保持)。

【文档】实机测试实施指南 §7.2 判读工具块重写(v1.1 口径 + 降级依据 + stall
语义指针);N-2 销项条件同段由「stall 与 MISS 双零」改为「stall 与真停滞嫌疑
段双零」。开机豁免(§9 第 8 条)保留、仅作用于 MISS 诊断分类。

【顺手修(越界申报)】scripts/check_size_gate.py 无参/非法参直调在 print_help
崩(argparse 对 help 做 %-插值,「92% 红线」裸 % + 中文 = ValueError;lead 派
单附注确认):help 改 92%%,加注释防复发;--ci 功能语义零改动。非本票写域,
系 lead 明示「要不要顺手修由你定」。

【票内待办(commit 2/2)】boot_log_data 的 gz 摘录:原定素材(16:18-16:48
megawin 段)**已不可得**——serial-assistant state 日志被后续 @test 窗 clear
轮转,全盘(含 Temp/ci-artifacts)无副本,已报 lead。替代落点 = 本轮 F2/F3
验收两轮 30min 判据轮(最终主干 1a624b1,效果取证素材)各出一只 gz 入库 +
README 索引,语义上是「v1.1 判据下的达标基线」比旧误判窗更有归档价值。

【门禁】--all-files 48 全绿(本树补跑一次 @build 落地 .map 后 mem-numbers/
budget 自然绿,数字 224860/24640/1332/135100 与凭证同码一致;固件源码零
改动);uvprojx UV4 抖动未入库。
2026-10-25 19:10:29 +08:00
wandering1 7c4628b043 fix(A5): 体积凭证指纹改取 git 索引 blob——跨 checkout 稳定,并拦未 staged 改动
现象(道C-3 开工第一步就撞上,属于上一提交 e25e51c 引入的缺陷):
_wt/P1-10-test-fw 里 check_size_gate --local 报"不同码",而两棵树 git status 全干净、
HEAD 同为 e1967cf。定位:主工作树的受管源码里 **1046/1388 个文件落成 CRLF**,新建
工作树同一提交落成 **LF**(实测 Drivers/BSP/dbg_cfg.h:1293 B/CRLF vs 1247 B/LF),
但两者的**索引 blob 完全相同**(都是 c39395f7…)。根因是本仓 core.autocrlf=true 与
.gitattributes 的 eol=lf 并存——所以"工作树原始字节"根本不是跨 checkout 的稳定身份。
后果比红一次更糟:主树盖的凭证在**每一条道的平行工作树**里都会误红,runner 上同样
(checkout 出来的行尾取决于那台机器的配置)→ 门禁自己造 false positive。

修法(AGENTS「行尾不依赖 core.autocrlf」的机器化版本):
- 指纹 = git **索引** blob:`git ls-files -s` 的 path+blob 逐行聚合哈希(v2),
  跨 checkout / 跨机器一致;凭证 schema 从 1 抬到 2,旧凭证直接判"不符、重新盖戳",
  不做静默兼容(v1 凭证在别的树里必然误红,留着只会污染判读)。
- 新增第四道前置:**范围内有未 staged 改动/未跟踪文件时拒绝盖戳**——未 staged 的部分
  不在索引里,凭证会声称覆盖一份并不存在的代码。已 git add 的不算脏:索引已含其内容,
  正是"将要提交并被测量"的那一份。--local/--ci 同样把这类脏单独报出来。
- 新增守卫的机理性说明写在 index_snapshot() 上方与 docstring 的"指纹范围"节(唯一正文)。
- scripts/size_attestation.json:按 v2 重新盖戳(本树产品态实测 Code=214104 /
  RW=1204 / ZI=131852 / RW_IRAM1 75,632 B / RW_CCM 57,376 B,与主干 2026-10-25
  台账行同源)。

验证:
- 跨树一致性:_wt/P1-10-test-fw 与主工作树分别独立算索引指纹,结果都是
  bf6ec94a761e…(1388 文件)→ CROSS-TREE STABLE。
- --stamp / --local / --ci 三态均 rc=0;凭证与 tsv 末行互证同源(Code=214,104 B)。
- 负向:在 test/board/ 放一个未跟踪探针文件 → --local 与 --stamp 双双 rc=1 并点名该
  文件;删除后 --local 回到 rc=0(本树已确认干净,探针不留痕)。
- py_compile 通过;门禁实跑:no-mojibake / trailing-whitespace / end-of-file-fixer /
  check-added-large-files / id-check 全部 0。

RAM 增量:0 B(凭证与门禁脚本,不进固件)。gate:全过,未用 --no-verify。
⚠ 需要 lead 做一步:合入后主树跑一次 python scripts/check_size_gate.py --stamp
  (或 ram_baseline.py --update)把 v1 凭证换成 v2,否则主树的 L0c 会报 schema 不符。
2026-10-25 04:18:32 +08:00
wandering1 e25e51c378 ci(A-5): 体积门禁补强制路径——同码凭证 + CI 无需 Keil 复核 92% 红线
背景:A-5 残余(docs/任务规划/测试与架构专项.md)说得很直白——mem-numbers 在
CI 被跳过(runner 无 Keil/无 .map),上一轮只把"跳过"声明成一条 ::warning::,
"盲区本身未消除":看到 CI 全绿仍会以为体积也守住了。

复核时本地侧同样漏:ram_baseline.py --gate 在无 .map 时自适应 SKIP 且返回 0;
mem-budget 甚至没进 CI 的 SKIP 名单——它在 runner 上以"Passed"的面貌出现,实际
什么都没检查。两处共同点是**"没跑 = 通过"**。

做法:给体积数字配一条可提交、CI 可复核的**同码凭证**,而不是要求 runner 装 Keil。
- 新增 scripts/check_size_gate.py(口径与边界的唯一正文在其模块 docstring)
  · --stamp:只在三条都成立时才盖章——① .map 存在且解析得出执行区与 Grand
    Totals;② .map 不早于指纹范围内任何源码的 mtime;③ 受管区占比不超过
    mem-budget 用的同一常数。凭证因此不是随手可写的。
  · --local:工作树指纹必须等于凭证指纹,否则 FAIL(="改了代码但体积从没测过")
  · --ci:不需要 Keil 也能判的两条——同码性 + 按凭证记录的数字复核 92% 红线
  · --show:排障用。指纹 = git ls-files 范围内逐文件 sha256(路径+内容) 再聚合,
    覆盖 App/ Drivers/ Src/ Inc/ Lib/ Middlewares/ test/board/ 与 MDK-ARM 的 .sct/.s
- 新增 scripts/size_attestation.json:本树的凭证(由本树一次真实 @build 盖戳)
- scripts/ram_baseline.py:--update 顺手盖戳——"每次 @build 后跑 --update"是既有
  纪律,不新增人工步骤;在函数内 import 防成环;盖戳失败只告警、不改 --update
  返回值(新鲜度由门禁自己 fail-closed 兜)。_util/_read_tsv 提为公开名
  region_pct / read_tsv_rows 供其复用(体积口径禁第二处定义);--gate 的无 .map
  文案改成明说"SKIP 不等于 PASS"并指向兜底路径。
- scripts/ci_local.py:新增 L0c 体积门禁步(fail-closed、无条件照跑、约 0.3 s)
  与 --size-only 开关;docstring 里把"无 .map 时跳过两根钩子"的语义补全。
- .gitea/workflows/ci.yml:L0 作业末尾加「体积门禁」步(if: always(),无需 Keil);
  主干 push 拦红、其余事件 --warn-only(分支上代码尚未定型,拦红只造噪音,还会
  诱发多条道同时抢写 scripts/ 台账);SKIP 名单补 mem-budget,让它诚实显示
  Skipped 而不是假 Passed;文件头的"门禁盲区声明"改写为"已关闭为强制路径 +
  仍守不住的三项"。run: 块全部纯 ASCII(PS 5.1 无 BOM 按 GBK 解码的实测坑)。
- scripts/README.md:登记新脚本与凭证文件,补用法行。

验证(工作树 _wt/A5-size-gate,分支 task/A5-size-gate)
- @build 0 错 0 警:Code=213780 RO=18860 RW=1204 ZI=131852——与 ram_baseline.tsv
  的 2026-10-24 行逐项相同(本改动不碰固件源码,指纹不变,零体积增量)。
- 门禁实跑全 0:check-yaml / trailing-whitespace / end-of-file-fixer /
  check-added-large-files / no-mojibake / id-check / doc-links / mem-budget。
- 负向 8 例全过:改凭证指纹 → --local 与 --ci 都 rc=1;凭证占比改成 95% →
  --ci rc=1,加 --warn-only 则 rc=0;凭证写成非法 JSON → rc=1;用 mtime 回拨的
  .map 去 --stamp → 拒绝且不动凭证;把区 max 改小到必然超线再 --stamp → 同样拒绝。
- 正向:--stamp 之后 --local / --ci 均 rc=0,并与 tsv 末行互证同源。
- --update 的盖戳联动单独验(把 TSV_PATH 与凭证指到仓库内已 gitignore 的
  ci-artifacts/ 探针文件,跑完清理,本树台账未被测试污染)。
- ci_local 全量:L0.5 33 runner / 2227 断言全绿、gitlint 10/10、L0c rc=0。L0 里
  test-cppcheck 与 test-coverage 各报过一次"files were modified"——单独重跑两条
  均 rc=0 且工作树无改动,判定为三条道并行跑主机单测时 %TEMP% 里按套件名派生
  的 obj/exe 互相踩踏(harness 产物名全机共用一个 TEMP 目录),非本改动引入。

RAM 增量:0 B(未动固件源码,凭证数字与本树一次真实链接一致)。
gate:全部通过,未使用 --no-verify。

遗留 / 需要 lead 裁定
1. 合入后主干 push 会要求"同码测量":done 流程在 @build 0/0 之后要多跑一条
   python scripts/ram_baseline.py --update,并把 scripts/size_attestation.json
   (数字变了则连 scripts/ram_baseline.tsv)一并提交。这就是"强制"的含义,但
   确实新增半步——若你想先只在本地强制(L0c),我把 CI 那步改成 --warn-only。
2. 文档口径同步我没做(docs/任务规划/**、docs/门禁说明/**、docs/CI/README.md
   归主树):A-5 销项时建议把"CI 不守体积"改为"CI 守同码性 + 红线,绝对数字仍
   由本地真实构建产生",正文引用 check_size_gate.py 的模块 docstring。
3. 编译器选项(uvprojx)刻意不进指纹:UV4 每次构建改写它且不入库,进指纹会让
   门禁在"刚刚构建完"的那一刻自己变红;代价是改优化等级/宏不触发本门禁,需人工
   重测——已写进边界正文。
2026-10-25 03:51:19 +08:00