diff --git a/.dsh/skills/draw-diagram/SKILL.md b/.dsh/skills/draw-diagram/SKILL.md index 560db380..dd8167ed 100644 --- a/.dsh/skills/draw-diagram/SKILL.md +++ b/.dsh/skills/draw-diagram/SKILL.md @@ -194,7 +194,7 @@ sha1sum docs/images/<主题>.svg - **`--screenshot=ci-artifacts/ladder.png`(相对路径)** → `EXIT 2` + `Failed to write file ci-artifacts/ladder.png: 系统找不到指定的路径。 (0x3)`,PNG 压根没落盘;换绝对 Windows 路径后写出 95549 bytes。这条报错**不区分**"相对路径"与"目录不存在"两种成因(实测 `mkdir -p ci-artifacts` 已先跑过、仍报同一句),排查时两条都排。 - **只做预检 + 缩略目检就收工(大图)**:`check_fit` 归零、PNG 看着干净,仍可能有二十来条标签压框——节点白底后画会吃掉压上去的标签;大图必须走 §三b 的解析式审计。 - **只做预检就收工**:`check_fit` / `OVERFLOW` 归零也不代表干净——本窗实测"门标签压第 5 级盒、蓝底标签挤、多余虚线"三类碰撞只有 PNG 回读看得见;反过来只目检不预检,脚注溢出就得靠眼睛反复量。**两者都要 0**。 -- **手改 SVG 成品**:等于制造「不是我改的」diff,且 `generated-fresh` 立刻 DIFF;也**不要退化成 ASCII 框图**(AGENTS.md 明令勿手绘)。一切修改都落在生成器常量上再重跑。 +- **手改 SVG 成品**:等于制造「不是我改的」diff,且 `generated-fresh` 立刻 DIFF;也**不要退化成 ASCII 框图**(图形一律走生成器 / Mermaid,本条是判据)。一切修改都落在生成器常量上再重跑。 - **批量改生成器时 `old_string` 不匹配**:一批 `edit` 会在中途抛错,但**前面的编辑已经落盘** → 半成品生成器(本窗实测:`emit` helper 缺失却仍打印 OK,几轮之后才查出)。正解:改前先 `read` 出精确原文,逐条改,末尾统一复验(`grep -n "def emit"`、`grep -c print`、再重跑看 rc 与 OK 行)。 - **PNG 尺寸 ≠ 画布**:`--window-size` 忘了跟着 `W`/`H` 改 → 截出来带大片空白或裁掉底部脚注;回读 `r.image.width/height` 与 `canvas WxH` 对一下再判定。 - **`docs/images/` 下手写 `.svg` 或放 PNG 预览**:前者没有生成器(NEW / 躲过门禁),后者污染"临时目录多了文件"判定。 @@ -208,4 +208,4 @@ sha1sum docs/images/<主题>.svg - [ ] 引用它的 `.md` 相对路径正确(根目录 `images/`,子目录 `../images/`);`tools/arch_diagram/README.md`「产物清单」已加行,「挂在」列的 `文档:行号` 用 `grep -rn "<图名>.svg" docs/ --include=*.md` 现扫核对(**别抄旧行号**,行号一漂整列就废)。 - [ ] 脚本 + 产物 `.svg` + `.md` + README 行一并暂存;`pre-commit run --files …` 全过(无乱码 / 行尾空白 / 编码 OK)。 -> **与规范文档的分工(2026-10-30 已对齐)**:`docs/架构设计/图形绘制流程.md` 是规范归属(AGENTS.md:同一事实只在一处详述),本 skill 是执行侧。该文档 §3.1 第 4 步与 §四 原先写的「浏览器打开 SVG / 给 `.venv` 装 cairosvg 转 PNG」在本机走不通,已同步成 headless Edge/Chrome 那套(命令只在 §四 详述,本 skill §三 留判据指针);**改渲染命令时两处一起改**——做图判据以本 skill 为准,规范条文以该文档为归属。 +> **与规范文档的分工(2026-10-30 已对齐)**:`docs/架构设计/图形绘制流程.md` 是规范归属(`docs/文档规范.md` §7 的「同一事实只在一处详述」),本 skill 是执行侧。该文档 §3.1 第 4 步与 §四 原先写的「浏览器打开 SVG / 给 `.venv` 装 cairosvg 转 PNG」在本机走不通,已同步成 headless Edge/Chrome 那套(命令只在 §四 详述,本 skill §三 留判据指针);**改渲染命令时两处一起改**——做图判据以本 skill 为准,规范条文以该文档为归属。 diff --git a/.dsh/skills/font-regen/SKILL.md b/.dsh/skills/font-regen/SKILL.md index 7ace06c2..2d8748c8 100644 --- a/.dsh/skills/font-regen/SKILL.md +++ b/.dsh/skills/font-regen/SKILL.md @@ -30,7 +30,7 @@ python tools/font_gen/extract_cn.py # 扫描 UI 源码字符串 → ## 坑 -- 不要用 PATH 默认 `python`(msys64,无 fonttools)跑 make_font.py;`.venv` 缺失时按 AGENTS.md「Python 环境」重建 +- 不要用 PATH 默认 `python`(msys64,无 fonttools)跑 make_font.py;`.venv` 缺失时按 `new-machine-setup` skill(`.venv` 重建)重来 - `requirements.txt` 必须**纯 ASCII**(Windows 下 pip 按 GBK 解码,中文注释 → UnicodeDecodeError) - 生僻字(宋体可能无字形)→ **写码前先手动验证字形**,避免"代码写完才发现是空白" - 生成成功后跑 `ui-verify` skill 全回归;黄金参考因字形变化而 FAIL 属预期 → `check_content_pages.py --update` 刷新 diff --git a/.dsh/skills/id-family-semantic-migration/SKILL.md b/.dsh/skills/id-family-semantic-migration/SKILL.md index b6872fd8..2bd96a60 100644 --- a/.dsh/skills/id-family-semantic-migration/SKILL.md +++ b/.dsh/skills/id-family-semantic-migration/SKILL.md @@ -115,5 +115,5 @@ version: 1.1.0 7. 规范与台账已回写并复跑核数:自己先前写进规范的清点数字要么按最终实测改对,要么标明为动手前基线;「等你裁定」残留 = 0;「不做」裁定已在 §4.1.1 + §9.1 + 批次结论段落三处落地(原「变更记录」那一处已随 2026-10-28 清流水退场)。 8. **无识别面族**:`git grep -nE '卡[ ]*[0-9]' -- .` 无输出(裸跑读 rc);自建扫描器的站点/文件数与提交正文一致;交付里明写「本族不在 check_ids 语料内、门禁判不到」与「刻意不进 `id_aliases.json`」的理由;§4.1.1 停发行 + §9.3 换算表 + 批次结论段落三处齐全,换算表行数 = 该族字面量数(实测 14),且写明旧号永久作废、不得重新取走。 9. **二次清洗三道各有实测数**:同句重复短语 0 行、各空格形态先计数后归一(复扫 0)、固定正则残留 0;被代码头注释引用的设计约束章节仍在(`git diff` 里没被动过)。 -10. **叙述同步**:`AGENTS.md` / `docs/README.md` / `docs/任务规划/README.md` / `docs/任务规划/登记簿.md` 里旧口径(「三项」「卡 N」类)实测归零;`ci-artifacts/` 里本次 spec 与中间产物已删。 +10. **叙述同步**:`docs/README.md` / `docs/任务规划/README.md` / `docs/任务规划/登记簿.md` 里旧口径(「三项」「卡 N」类)实测归零;`ci-artifacts/` 里本次 spec 与中间产物已删。 11. 门禁复跑清单齐:`check_ids.py` plain + `--strict`、`check_doc_links.py --all`、`bom-guard`、`no-mojibake`、`git diff --check`、`/keil-build` 或受影响单测——**每个数字标明是本回合实测**。 diff --git a/.dsh/skills/id-family-semantic-migration/reference/steps-chinese-prefix-family.md b/.dsh/skills/id-family-semantic-migration/reference/steps-chinese-prefix-family.md index 67398cc6..dbc43723 100644 --- a/.dsh/skills/id-family-semantic-migration/reference/steps-chinese-prefix-family.md +++ b/.dsh/skills/id-family-semantic-migration/reference/steps-chinese-prefix-family.md @@ -51,7 +51,7 @@ - `docs/文档规范.md` **§7.1「已停发、只读的旧号」段加一行**,三列齐全,第三列直写「⚠ **这一族从来没有机器面**:中文前缀不进任何编号语料(族 pattern 全是拉丁形态),而两道编号门禁已于 2026-10-28 / 29 退役 → 只有本表 + 归档换算表 + 评审三条兜;`id_aliases.json` 刻意不登记(没有机器读者,登记等于多一张没人核的表)」; - `scripts/archive/id_gate/编号治理历史.md` **§9.3 逐号换算表**(旧号形态 → 语义短语 → 现行口径出处;本族实测 14 行 = 0、0b、1~12)+ 同篇 §9 批次段落(裁定原文与逐号结论都落在归档正文),**写明旧号永久作废、不得重新取走**; - 表内**把形态写成「卡」+ 数字而不复述字面量**:规范本身是门禁语料,复述字面量会把「讲规则的文档」变成自己的引用站点; - - **同步叙述**:`AGENTS.md`「文档与图形」的销项条目、`docs/README.md`(历史实例:当时把「数据可信.md = 三项阻塞任务」改成两项;该文档已于 2026-11-09 拆分迁出并删除)、`docs/任务规划/README.md`、`docs/任务规划/登记簿.md`——「剩余三项」这类旧口径实测归零; + - **同步叙述**:`docs/README.md`(历史实例:当时把「数据可信.md = 三项阻塞任务」改成两项;该文档已于 2026-11-09 拆分迁出并删除)、`docs/任务规划/README.md`、`docs/任务规划/登记簿.md`——「剩余三项」这类旧口径实测归零; - **与有识别面族的判别写进同一张表**:能被脚本按字面量匹配 → 走 `rename_ids.py` + 别名登记;匹配不到(中文前缀、纯散文号、圈号)→ 走规范换算表,**不登记别名**; - 要机械化怎么办:得先给「中文前缀 + 数字」设计候选形态,属追溯机制改造,按 §7.3 单独开卡,**别夹在清退批里顺手做**。 8. **替换后三道二次清洗**(缺一必留疤,全部实测过): diff --git a/.dsh/skills/keil-build/SKILL.md b/.dsh/skills/keil-build/SKILL.md index a1944caa..aad9acb0 100644 --- a/.dsh/skills/keil-build/SKILL.md +++ b/.dsh/skills/keil-build/SKILL.md @@ -10,7 +10,7 @@ whenToUse: "需要编译 Keil MDK 工程、跑 /keil-build 验证代码改动( (纯标准库,任意 python3;拷整个 skill 目录到别的 Keil 项目即可用,不依赖仓库脚本)。 ```powershell -# cwd = 项目根目录;PowerShell 形态(AGENTS「构建与验证」的编译入口) +# cwd = 项目根目录;PowerShell 形态(本 skill 的编译入口) & $PY ".dsh\skills\keil-build\scripts\keil_build.py" # 覆盖:--project X.uvprojx --uv4 UV4.exe --target 名字 --log 路径 --timeout 600 ``` @@ -25,7 +25,7 @@ column 14` → **技能整份不加载**(`skill()` 读不到、也不进技能 ## 调用形态:先认执行器是哪个 shell(2026-10-26 实测) -- 同一条编译命令,PowerShell 与 bash 是两种写法:bash 侧要去掉前导 & 并把路径改正斜杠(照抄 AGENTS 的 PowerShell 形态进 ops_bash 会语法错秒退 exit 2) +- 同一条编译命令,PowerShell 与 bash 是两种写法:bash 侧要去掉前导 & 并把路径改正斜杠(照抄本文末「PowerShell 形态」整段进 ops_bash 会语法错秒退 exit 2) - ⚠ 那个 exit 2 不是脚本的环境错误 2:stderr 含 syntax error near unexpected token = 写法问题,换 bash 形态重跑,别去查 DTU_KEIL_UV4、别当环境错误排障 - 后台跑(run_in_background: true)要自己收码,且别把脚本接进管道:实测 $? 取到的是 tail 的码(恒 0);要看报错行就单独 grep MDK-ARM/build_log.txt - 解析顺序:命令行 > 项目档案 .serialtest/config.json > 环境 > 探测;UV4 显式设了但路径无效 = 立即报错,不静默回退 @@ -40,7 +40,7 @@ column 14` → **技能整份不加载**(`skill()` 读不到、也不进技能 且**退出码 2** = **环境错,不是构建失败**——本次 **UV4 根本没启动、`MDK-ARM/build_log.txt` 也没被改写**, 日志里看到的是上一次的。此时去改 `.c`/`.h` 或怀疑代码,就是把环境问题当编译问题排。 (会话为什么看不见:DSH 会话的 shell 由常驻服务派生,**服务启动之后**设的用户级变量不会自动进来; -`run_code` 起的 Node 进程 `process.env` 干脆是空的——AGENTS.md「会话不继承用户级变量」同记此坑。 +`run_code` 起的 Node 进程 `process.env` 干脆是空的(同一机制另见 `new-machine-setup` skill「实测坑」)。 所以**变量"已设但本会话看不见"是常态**,不是用户没设。) 1. **探测候选安装路径**(逐个 `fs.existsSync` / `test -f`,命中即取绝对路径)—— @@ -155,6 +155,23 @@ Agent 手工 `lock acquire build` 后忘了 `release`,锁要挂到 TTL 才被 `rm -rf -- '%SystemDrive%'`(bash 引号形态)删掉即可,**严禁 `rd /s /q %SystemDrive%`——cmd 会把它 展开成 `C:`**;`.gitignore` 已兜住 + 脚本已加 `ENV_SPARSE`/`JUNK_DIR` 守卫 → 见「构建副产物」一节。 - 报错定位读日志别只看终端回显:本仓库 = `MDK-ARM\build_log.txt`。 +- **批量改注释/文档脚本必须用字节模式(2026-11-16 一天内三个会话各踩一次)**:`open(p,'w')` / + `Path.write_text()` 在 Windows 上把 `\n` 翻成 `\r\n`,结果是**只改了 1 行、`git diff` 却显示整文件**, + 且提交时易触发「stashed changes conflicted with hook auto-fixes → Rolling back fixes」(提交不生成)。 + 铁律:读 `open(p,'rb')` / `Path.read_bytes()`,写 `open(p,'wb')` / `Path.write_bytes()`;非用文本模式 + 必须带 `newline=''`。改完用 `grep -c $'\r' <文件>` 或逐文件比对 `HEAD` 的 CRLF 计数验收—— + `.gitattributes` 的 `eol=lf` 只在提交时归一化,**工作区里被翻过的行尾不会自己变回来**。 +- **字节模式也不会救你:`replace` 会原样保留既有行尾(同一坑的另一面)**。字节层写入保证的是 + 「**忠实地坏**」——它不引入 CRLF,也不修复别人留下的 CRLF。所以「BOM 保住了」与「行尾被翻了」 + 是同一机制的两面:一次 `str.replace` 改动,带 BOM 的文件 BOM 仍在,带 CRLF 的文件 CRLF 仍在, + 两者都不报错、都要单独验收。改前加一道前置断言最省事:`assert b'\r\n' not in data`(或按 HEAD + 形态决定是否归一化),把问题挡在写之前而不是提交前。 +- **行尾验收判据是「相对 HEAD 不变」,不是「绝对 LF」**(这是本坑的判据,别用 `CRLF == 0`): + 对每个被改文件比 `work_CRLF > 0` 与 `HEAD_CRLF > 0` **是否一致**——两边都 0(LF 文件)→ OK; + 两边都 >0(CRLF 文件)→ OK;**一边 0 一边 >0 → 污染**。理由:`MDK-ARM/*.uvprojx` 这类文件在 HEAD + 里本来就是 CRLF 且有正当来源(UV4 改写),无差别归一化成 LF 反而制造假改动。批量脚本的自检就照这条 + 写(`git status --porcelain -z` 取路径,NUL 分隔避免非 ASCII 路径被 quoted 转义丢掉,再逐个 + `open(...,'rb')` 数 `\r\n`),别用 `git status --porcelain` 的默认 quoted 输出做路径解析。 - **exit 2 先分三种再动手**(2026-10-10 / 2026-10-26 / 2026-10-30 实测):① **bash 语法错**——stderr 有 `syntax error near unexpected token`,是把 PowerShell 形态丢进了 `ops_bash`,换写法即可; ② **真没设** `DTU_KEIL_UV4`;③ **已设但本会话看不见**(agent 的 shell 由常驻服务派生,服务启动**之后** @@ -162,7 +179,12 @@ Agent 手工 `lock acquire build` 后忘了 `release`,锁要挂到 TTL 才被 ②③ 一律走 **「exit 2 实战闭环」** 那一节:探测候选路径 + 读 `HKCU\Environment`, 再**只往那一次调用**的 env / `--uv4` 里注入命中路径重跑——别急着让用户去设,也别替他改全局。 - 编码类报错(`#870-D: invalid multibyte character sequence` 等)先怀疑源文件 - BOM/编码被改写,而不是代码本身(见仓库 AGENTS.md 编码铁律)。 + BOM/编码被改写,而不是代码本身(C 源码带 BOM 名单与理由 → `docs/文档规范.md` §2)。 +- **退出码数值口径**(本 skill 是唯一事实源,其它文档一律指这里):`0` 成功 / `1` 构建失败(有 error)/ + `2` **脚本判定的环境错误**(`BuildEnvError`:UV4 找不到、uvprojx 缺失等——但见上条,bash 语法错也打 2, + 须先看 stderr 分型)/ `3` 用法错误(argparse)/ `4` build 锁被占用(并发 `-b` 不可行)。 + ⚠ **"exit 2" 本身不等于环境问题**——它是 ①bash 写法错 ②真没设 `DTU_KEIL_UV4` ③已设但本会话看不见 + 三者共用的码位,故一律先按上面「exit 2 先分三种」分型再动手。 ## 与其它 skill 的衔接 diff --git a/.dsh/skills/keil-build/reference/executor-shell-forms.md b/.dsh/skills/keil-build/reference/executor-shell-forms.md index 74098ab9..e85c9bd0 100644 --- a/.dsh/skills/keil-build/reference/executor-shell-forms.md +++ b/.dsh/skills/keil-build/reference/executor-shell-forms.md @@ -3,7 +3,7 @@ > 本文由 keil-build 的 SKILL.md「调用形态:先认执行器是哪个 shell(2026-10-26 实测)」一节逐字外置而来(渐进展开:主文件只留索引与指针)。步骤号沿用原文,未重编。 同一条编译命令,**PowerShell 与 bash 是两种写法**;`ops_bash` / `run_code` 起的是 -`/usr/bin/bash -c`,**不认 PowerShell 形态**,照抄仓库 `AGENTS.md` 会直接语法错退出。 +`/usr/bin/bash -c`,**不认 PowerShell 形态**,照抄 skill 正文的 PowerShell 段会直接语法错退出。 | 执行器 | 正确写法(cwd = 仓库根) | |---|---| @@ -38,6 +38,6 @@ **收到 2 先确认它是脚本打的还是 shell 语法错打的**(见上节),再走"环境错误"排障。 > 2026-10-12 修正:旧实现把环境错误写成 `raise SystemExit("...")` → 实际退出码是 **1**, -> 而用法错误由 argparse 抛 `SystemExit(2)` → 恰好占了"环境错误"的位置。故 `AGENTS.md` / -> `new-machine-setup` 里写的"报 exit 2 = 环境问题"当时**不成立**。现按文档口径改正: +> 而用法错误由 argparse 抛 `SystemExit(2)` → 恰好占了"环境错误"的位置,于是当时"报 exit 2 +> = 环境问题"这条经验**不成立**。现按脚本实际行为改正(现行口径见 skill 正文「退出码数值口径」): > 环境错误 → 2(`BuildEnvError`),用法错误 → 3(覆盖 argparse 的 `error()`)。 diff --git a/.dsh/skills/keil-build/scripts/keil_build.py b/.dsh/skills/keil-build/scripts/keil_build.py index 9368e1ab..e2f5f11d 100644 --- a/.dsh/skills/keil-build/scripts/keil_build.py +++ b/.dsh/skills/keil-build/scripts/keil_build.py @@ -44,9 +44,9 @@ 4 = build 锁被占用(并发 -b 不可行) ⚠ 修正说明:旧实现把环境错误写成 `raise SystemExit("...")` → **实际退出码是 1**, -而用法错误由 argparse 抛 SystemExit(2) → 恰好占用了文档里"环境错误"的位置。 -故 AGENTS.md / `new-machine-setup` SKILL.md 里写的"报 exit 2 = 环境问题"当时**不成立**。 -现已按文档口径改正:环境错误 `BuildEnvError` → 2,argparse 用法错误 → 3。 +而用法错误由 argparse 抛 SystemExit(2) → 恰好占用了"环境错误"的位置,故当时"报 exit 2 += 环境问题"这条经验不成立。现已按本脚本实际行为改正:环境错误 `BuildEnvError` → 2, +argparse 用法错误 → 3。现行口径见 SKILL.md「退出码数值口径」。 """ import argparse diff --git a/.dsh/skills/mem-budget/SKILL.md b/.dsh/skills/mem-budget/SKILL.md index 2b2122e3..6b1bee04 100644 --- a/.dsh/skills/mem-budget/SKILL.md +++ b/.dsh/skills/mem-budget/SKILL.md @@ -67,7 +67,7 @@ whenToUse: 新增任务/加大缓冲/改栈/接入日志之前之后、链接报 | `docs/内存管理/RAM预算台账.md` 的 `` 受管区 | `ram_baseline.py --write` | 从 .map 重渲染区域水位 + 子系统配额对照(打印「已同步台账受管区。」或「台账受管区已是最新。」) | | `docs/内存管理/RAM使用分析与优化方案.md` 的 `` 快照区 | `check_mem_numbers.py --write` | 从**同一份** .map 重渲染内存/Flash 快照表(打印「已更新内存快照:…」) | -**AGENTS.md 与台账 §4 那句「每次 `/keil-build` 后跑 `scripts/ram_baseline.py --update`」喂的是趋势行,不等于回填受管区。** +**台账 §4 那句「每次 `/keil-build` 后跑 `scripts/ram_baseline.py --update`」只喂趋势行,不等于回填受管区。** 实测代价:照那句跑完 `--update` 就提交 → `mem-budget`、`mem-numbers` 两条钩子当场红。 `mem-budget` 的 entry 是 `python scripts/ram_baseline.py --gate`(`.pre-commit-config.yaml:571`)——它在 92% 阈值之外 还核**台账受管区与 .map 的一致性**,漂移即 `[FAIL] 台账受管区与 .map 不一致(区域水位或子系统配额表漂移)` diff --git a/.dsh/skills/serial-assistant/scripts/serial_tool.py b/.dsh/skills/serial-assistant/scripts/serial_tool.py index a1d44745..2b824ed7 100644 --- a/.dsh/skills/serial-assistant/scripts/serial_tool.py +++ b/.dsh/skills/serial-assistant/scripts/serial_tool.py @@ -1289,7 +1289,7 @@ def cmd_log(args): """读日志:**先过滤、后截尾**。 旧实现先 tail 后 grep → `log --grep "App init OK"`(--tail 默认 50)只在末 50 行 - 里找,开机标记必然查无此 marker——这就是 AGENTS.md 里"log --grep 实测不可信"的 + 里找,开机标记必然查无此 marker——这就是历史上"log --grep 实测不可信"的 根因(2026-10-09 实测复现并修复)。返回带 scanned/matched 计数,便于判定。 """ log_path, gen = resolve_log_paths() @@ -1334,7 +1334,7 @@ def cmd_wait_idle(args): # wait-idle 是同步阻塞的长操作:CLI 超时按等待上限自动推导。旧实现固定 5s # 硬超时会在 daemon 还在等的时候先掐断 → CLI 报 exit 2、daemon 侧 # ConnectionAbortedError traceback(本机 daemon.log 实测 16 次)。 - # AGENTS.md 抓开机日志铁律②"必须带 --timeout"就是这个坑的手工补丁。 + # 抓开机日志必须带 --timeout(CLI 侧默认不推导时的护栏),否则就是下面这个坑的手工补丁。 args.timeout = args.max_ms / 1000.0 + 5.0 return call_daemon(args, "POST", "/wait-idle", body) @@ -1514,7 +1514,7 @@ def run_selftest(): check("T5c 持续吐数判 timeout + 返回增量字节", r["reason"] == "timeout" and r["rx_bytes"] > 0, repr(r)) - # T6 log 命令:先 grep 后 tail(旧顺序即 AGENTS.md"log --grep 不可信"的根因) + # T6 log 命令:先 grep 后 tail(旧顺序即"log --grep 不可信"的根因) saved_log, saved_meta = LOG_FILE, load_meta saved_resolve = globals()["resolve_log_paths"] fd2, lpath2 = tempfile.mkstemp(prefix="serial_tool_selftest_log_", suffix=".log") diff --git a/.dsh/skills/serial-boot-test/SKILL.md b/.dsh/skills/serial-boot-test/SKILL.md index 6c0e6a25..92f8fe34 100644 --- a/.dsh/skills/serial-boot-test/SKILL.md +++ b/.dsh/skills/serial-boot-test/SKILL.md @@ -16,7 +16,7 @@ whenToUse: 需要向目标板烧录或复位后,用串口日志自动判定运 | `.dsh/skills/serial-boot-test/scripts/run_boot_test.py` | 一键闭环:open+clear → 烧录 → wait-idle → 提取 boot log → 烧录回读校验 → 标记校验。串口助手按 `$DSH_SERIAL_TOOL` > 同目录 > `../serial-assistant/scripts/serial_tool.py` 解析 | | `.dsh/skills/serial-boot-test/scripts/verify_log.py` | 对任意日志文件做标记校验(Required/Forbidden/锚点计数/顺序/耗时),可单独用。`--exact` 做**整行 `^…$` 锚定**(子串口径照不出"行还在但行首被吃掉/行内被插字节"那一类损坏)、`--pair` 做跨复位配对、`--allow-residual/--head-char` 服务崩溃注入腿、`--selftest` 跑内置判别用例(**证明这套判据不是空跑**)。四个行级开关(`--exact` / `--pair` / `--allow-residual` / `--head-char`)同时接进了 `run_boot_test.py`,/serial-boot-test 闭环直接可用 | -> **`/serial-boot-test` 是 DSH 会话的技能调用名、不是 shell 命令**(同 `/keil-build`,见 AGENTS「构建与验证」总口径):可执行形态 = 上表 `run_boot_test.py` 命令行(仓库根跑);项目配置与判据见本仓 `docs/测试说明/流程与规范/自动化测试流程.md`。 +> **`/serial-boot-test` 是 DSH 会话的技能调用名、不是 shell 命令**(同 `/keil-build`,见 `keil-build` skill「调用形态」):可执行形态 = 上表 `run_boot_test.py` 命令行(仓库根跑);项目配置与判据见本仓 `docs/测试说明/流程与规范/自动化测试流程.md`。 > **判据取向(重要,会复发)**:`--exact` 默认**只锚文本、不钉长度**——字节长度属于某一份构建,钉死它会在无辜改动上假红(`@@LEN=` 是显式逃生口,不是默认)。子串 `--required` 不能用于"可能丢行首/被插字节"的行。来龙去脉与固定动作见本仓 `docs/测试说明/专项验证/启动日志原子性复验流程.md`。 @@ -34,7 +34,7 @@ whenToUse: 需要向目标板烧录或复位后,用串口日志自动判定运 配置解析顺序:`$DSH_SERIAL_CONFIG` > `/.serialtest/config.json` > `/.opencode/serial_config.json`(旧位置,仅串口字段)。 -若项目没有 `.serialtest/config.json`:**先从项目文档(AGENTS.md/README/测试文档)推断各字段,推断不了的问用户**,然后按 `config.example.json` 写一份。字段含义: +若项目没有 `.serialtest/config.json`:**先从项目文档(入口文件/README/测试文档)推断各字段,推断不了的问用户**,然后按 `config.example.json` 写一份。字段含义: | 键 | 含义 | 缺省行为 | |---|---|---| diff --git a/.dsh/skills/stale-doc-count-sweep/SKILL.md b/.dsh/skills/stale-doc-count-sweep/SKILL.md index f1165f75..c577889b 100644 --- a/.dsh/skills/stale-doc-count-sweep/SKILL.md +++ b/.dsh/skills/stale-doc-count-sweep/SKILL.md @@ -16,7 +16,7 @@ whenToUse: 某个计数/数字变了要跨 md/yaml/py/txt 同步、用户说「 |---|---|---| | 内容页黄金参考**张数** | `simulator/tests/ref/` 下 `shot_*.bin` 实数(2026-10-29 实测 **66**)= `simulator/tests/check_content_pages.py` 的 `PAGES` 条目数(实测 **66**,其中 2 个 `_p2` 分页 → 页面 64) | 分页页要**单独再拍一张**(id 加 `_p2`,如 `runreport_p2`)→ **张数 = 页面个数 + 分页多出的张数**;两个数分开报,不许互相冒充(53 张时代的一个 12 行分页页会让 55 页变 56 张这类差 1) | | 已绑内容页**叶数** | `Drivers/BSP/UI/ui_page_registry.h` 的 `#define UI_PAGE_MAP_COUNT 30u`(由 `tools/menu_gen/gen_menu.py` 生成;2026-10-29 录波道绑两叶后 28→30) | `grep -c '#page=' ui_menu_tree.txt` 得 **31**:第 5 行是菜单文件**头部注释里的示例行** → 剔掉注释/模板行后的 30 才是真值 | -| 提交**钩子数** | YAML 解析后的条目数(实测 **51**):自查命令见 `docs/门禁说明/README.md` §2 首条;与 AGENTS.md「共 N 个钩子」、该目录 §2 标题**三数同源** | `grep -c` 配置里的声明行 = 52(多算一条**被注释掉的** clang-format 候选);在配置**注释里复述那个 grep 字面量**会让文本计数再虚高 1 | +| 提交**钩子数** | YAML 解析后的条目数(2026-11-16 实测 **52**):自查命令见 `docs/门禁说明/README.md` §2 首条;与 `AGENTS.md` 提交门禁节「共 N 个钩子」、该目录 §2 标题**三数同源** | `grep -c` 配置里的声明行 = 52(多算一条**被注释掉的** clang-format 候选);在配置**注释里复述那个 grep 字面量**会让文本计数再虚高 1 | | 字库**唯一字数** | `ui_cn_chars.txt` 唯一码点数(2026-10-29 实测 **224**,其中 ASCII 区 **0** 个) | `make_font.py` 的 `-r 0x20-0x7E` 是 ASCII 子集参数,**不算进字数** | | **字形数** | `Drivers/BSP/UI/ui_font_cn_12.c` 里 `.bitmap_index` 出现次数 **320 条含 notdef → 319 字形**;换算式 = 224 汉字/符号 + ASCII 95 = 319 | 直接报 314 就是把 notdef 当字形;文档必须写出「不含 ASCII」「含 notdef 共 314 条」这类口径句 | | 变更记录**保留篇数** | 变体标题感知的普查(`grep -rn "^## " docs scripts` 再看哪些标题是变更记录 / 修订记录);当前态清单以 `docs/文档规范.md` §5.1 那行为准 | 只 grep 裸 `^## 变更记录` 会**漏算带编号与中文序号的标题**(实测 5 篇真台账里 2 篇是 `## 6.` / `## 九、`,另有 `## 修订记录` 变体)——2026-10-29 就差点把 5 改成 3 | @@ -65,7 +65,7 @@ whenToUse: 某个计数/数字变了要跨 md/yaml/py/txt 同步、用户说「 - [ ] 字形数说明**是否剔除 notdef**并给出条目数→字形数的换算(条目数 − 1 = 字形数,2026-10-29 现值 320 − 1 = 319);字数说明**是否含 ASCII**,且该口径句与实测一致 - [ ] 分类表逐条列出:改了哪些当前态、哪些历史行保留、哪些误报不动(附理由)、哪些只加「当时」、哪些属**口径错**并已另起一笔 - [ ] 替换脚本打印了每处 `old -> new xN` 且每处 `assert` 通过(无半落地;报错时已 `git diff --stat` 确认零写入) -- [ ] 命中面覆盖 `.pre-commit-config.yaml` 钩子 `name:`、AGENTS.md、`docs/**`、`scripts/**`、`.dsh/skills/*/SKILL.md`,逐条在改动清单里出现 +- [ ] 命中面覆盖 `.pre-commit-config.yaml` 钩子 `name:`、`AGENTS.md`(钩子数等入口级计数)、`docs/**`、`scripts/**`、`.dsh/skills/*/SKILL.md`,逐条在改动清单里出现 - [ ] 被改文件已全文通读,同文档各小节与配套 README/清单的顺序、计数、完成状态一致;口径闭合(如 `未绑 = 待做 + 不做`) - [ ] 变更记录:**保留的 5 篇真台账**(清单 → `docs/文档规范.md` §5.1)历史行原文未动;其余文档本轮**零新增流水行**(当前态改完即止);钩子一增一减这类过程细节写进提交正文,不写进文档 - [ ] **提交后**又按全部旧形态复扫一次,当前态残留 = **0**,每条剩余命中都能归类(历史行 / 误报 / 已加「当时」);发现的漏网当前态已单独补一笔 diff --git a/.dsh/skills/stale-doc-count-sweep/reference/pitfalls.md b/.dsh/skills/stale-doc-count-sweep/reference/pitfalls.md index 69d76350..85e6e66b 100644 --- a/.dsh/skills/stale-doc-count-sweep/reference/pitfalls.md +++ b/.dsh/skills/stale-doc-count-sweep/reference/pitfalls.md @@ -6,10 +6,10 @@ - **字形数没剔 notdef**:`.bitmap_index` 314 条里第 1 条是 notdef,字形数是 **313**;照抄 314 就把占位符当成了字形。 - **数字对但口径描述错**:218 这个数两处都对,错在「含 ASCII/符号」这句口径(实测 218 个码点全为非 ASCII)。它不进任何数字 diff,只能逐句读口径句;且必须**另起一笔**,混进数字同步那笔会让 review 者以为只是顺手改措辞。 - **权威脚本乱码就臆读或退回抄文档**:Windows 代码页下 `font-charset` 的整行输出退化成 U+FFFD 替换字符时,改数源文件符号出现次数,别猜、别抄旧文档。 -- **钩子数用 `grep` 声明行**:多算一条注释掉的候选钩子(51 变 52);反过来在配置注释里复述那个 grep 字面量会让文本计数再虚高 1。口径只认 YAML 解析后的条目数,且要与 AGENTS.md、`docs/门禁说明/README.md` §2 标题、`ci_local.py` 实跑 passed+failed+skipped 三数同源。 +- **钩子数用 `grep` 声明行**:多算一条注释掉的候选钩子(51 变 52);反过来在配置注释里复述那个 grep 字面量会让文本计数再虚高 1。口径只认 YAML 解析后的条目数,且要与 `AGENTS.md` 提交门禁节「共 N 个钩子」、`docs/门禁说明/README.md` §2 标题、`ci_local.py` 实跑 passed+failed+skipped 三数同源。 - **张数与页数互相冒充**:一个 12 行分页页第 2 页要单独拍一张,于是「+2 页」可能等于「+3 张」。两个数分别报、分别换算,别互相顶替。 - **数篇数只 grep 裸标题**:`^## 变更记录` 漏掉 `## 6. 变更记录`、`## 九、变更记录`、`## 修订记录` 三种写法 → 篇数直接少数一半,拿这个错数去"同步"全仓就是把对的改成错的(2026-10-29 实测:5 篇真台账只数出 3 篇,改到第 10 处才发现)。普查一律 `grep -rn "^## " docs scripts` 再看标题,或直接读 `docs/文档规范.md` §5.1 那行的例外清单。 -- **只扫 docs/**:漏 `.pre-commit-config.yaml` 钩子 `name:` 显示名里的页数、AGENTS.md 钩子清单、`.dsh/skills/*/SKILL.md` 自带的计数与脚本路径(skill 正文也是命中面:font-regen 的 179/274 本窗最后才改)。 +- **只扫 docs/**:漏 `.pre-commit-config.yaml` 钩子 `name:` 显示名里的页数、`AGENTS.md` 提交门禁节的钩子数、`.dsh/skills/*/SKILL.md` 自带的计数与脚本路径(skill 正文也是命中面:font-regen 的 179/274 本窗最后才改)。 - **提交完就收工**:第 7 步的提交后复扫才是把漏网当前态(架构总览 §3)揪出来的那一步;漏了它,仓库里就留下一行「当前态写旧数」直到别人再扫。 - **去已删掉变更记录的文档里「补一行流水」**:2026-10-29 起全仓只剩 **5 篇**真台账保留变更记录表(清单 → `docs/文档规范.md` §5.1),外加 `scripts/archive/` 归档;其余文档**没有这一节**。计数同步**只改当前态**、过程交给 `git log`,别再到别的文档里找或加变更记录行。真要往那 5 篇的台账里加行,历史坑照旧:它们的表按日期**升序** → 新行**追加为末行**,插表顶会把首行「初版」挤成第二行。 - **历史行被当陈旧值改掉**:「47 → 53 页」是当天事实,改了就是伪造历史;正确动作是**只改当前态那几处**、历史行一个字不动(保留变更记录的 5 篇真台账要写台账也只追加、不回改)。**历史行被写坏**时按无反引号兜底写法整行重写,别用同样写法再改一遍。 diff --git a/.dsh/skills/stale-doc-count-sweep/reference/steps.md b/.dsh/skills/stale-doc-count-sweep/reference/steps.md index 6a1c06db..003d7031 100644 --- a/.dsh/skills/stale-doc-count-sweep/reference/steps.md +++ b/.dsh/skills/stale-doc-count-sweep/reference/steps.md @@ -24,7 +24,7 @@ | grep -v -E '^\./(ci-artifacts|\.mnemon|\.dsh/runs)/' ``` - **命中面比「文档」宽**,至少包含:`docs/**`、`AGENTS.md`、`.pre-commit-config.yaml`(**钩子 `name:` 显示名内嵌页数**:`name: UI 像素回归(菜单 8 状态 + 内容页 60 页 黄金参考)` 就是命中点)、`scripts/*.py`、`simulator/**/README.md`、以及 **`.dsh/skills/*/SKILL.md`**(本窗 `font-regen` 正文自带 179/274 计数,直到 step 150 才发现;编号门禁退役那轮 `id-family-semantic-migration`、`task-worktree` 两个 skill 正文与 `scripts/README.md` 同样是引用面)。 + **命中面比「文档」宽**,至少包含:`docs/**`、`AGENTS.md`(入口级计数:提交门禁节的钩子数等)、`.pre-commit-config.yaml`(**钩子 `name:` 显示名内嵌页数**:`name: UI 像素回归(菜单 8 状态 + 内容页 60 页 黄金参考)` 就是命中点)、`scripts/*.py`、`simulator/**/README.md`、以及 **`.dsh/skills/*/SKILL.md`**(本窗 `font-regen` 正文自带 179/274 计数,直到 step 150 才发现;编号门禁退役那轮 `id-family-semantic-migration`、`task-worktree` 两个 skill 正文与 `scripts/README.md` 同样是引用面)。 先列出 `文件:行:全文`,**判定前必须看整行**——`cut -c1-120` 会截掉后半句(那里常写着日期戳或口径)。 @@ -46,7 +46,7 @@ import pathlib, sys sys.stdout.reconfigure(encoding='utf-8', errors='replace') JOBS = [ # (文件, old, new, 期望命中数) - ('AGENTS.md', '内容页 53 页黄金参考', '内容页 60 页黄金参考', 1), + ('README.md', '内容页 53 页黄金参考', '内容页 60 页黄金参考', 1), # 历史实例:当时该文件里确有这一行 ('.pre-commit-config.yaml', '内容页 53 页 黄金参考', '内容页 60 页 黄金参考', 1), ('docs/架构设计/项目架构总览.md', '122 字/217 字形', '218 字/313 字形', 1), ('docs/UI设计/UI_自动化测试流程.md', '文本断言 **310 条**、覆盖 40 页中的', '文本断言 **310 条**、覆盖当时 40 页中的', 1), diff --git a/.dsh/skills/task-worktree/SKILL.md b/.dsh/skills/task-worktree/SKILL.md index ab065dfe..ecc36568 100644 --- a/.dsh/skills/task-worktree/SKILL.md +++ b/.dsh/skills/task-worktree/SKILL.md @@ -117,7 +117,7 @@ PY=".venv/Scripts/python.exe"; TW=".dsh/skills/task-worktree/scripts/task_worktr "$PY" scripts/check_test_coverage.py --update-baseline # 覆盖率基线(新单测 / 新套件时必刷) "$PY" scripts/check_doc_links.py --all # 文档链接与章节引用 git add <上面刷出来的基线/快照文件> # 显式列文件,别 -A 把别人在飞的改动一起提交 -git commit -F # 提交属 Ask first(AGENTS.md 边界) +git commit -F # 提交属 Ask first(入口文件「边界」节) ``` **`--dry-run` 新增台账碰撞预检**:双方都改过的已知生成文件(`ram_baseline.tsv` / `size_attestation.json` / RAM 台账 md)会在预演阶段提前警告,让你知道合并后需要 postmerge 重算。 @@ -163,7 +163,7 @@ git commit -F # 提交属 Ask first(AGENTS.md 1. **`done` 只能在主工作树执行**——主干分支检出在主树,git 不允许同一分支两处检出。 2. **`done` 不 push**:它结束于本地合入 + 门禁全绿;推送需用户明确许可。 3. **`build` 与 `bench` 都必须串行**(UV4 不能两个实例同时 `-b`;COM6、ST-LINK、设备 IP `192.168.1.100` 各一份)。`build` 锁由 **/keil-build 自持自释**(`keil_build.py`)→ 调用方**不要**手工 acquire/release;`bench` 锁**必须手工** acquire → 烧录 / `/serial-boot-test` → release `--bench-pass`。非登记持有者怎么放 → B 节;插件树 → F 节。 -4. **单写者文档**:`docs/任务规划/`(整个文件夹)、`AGENTS.md` 任务表块、`MDK-ARM/*.uvprojx`、`.pre-commit-config.yaml`、内存快照 —— 任务期**不在任务树里改**,留到 `done` 统一处理;用户显式豁免时(在任务树写、由 done 合回)要在交付报告里点名这条例外。 +4. **单写者文档**:`docs/任务规划/`(整个文件夹)、`AGENTS.md` 的任务表生成块(`TASK_TABLE`)、`MDK-ARM/*.uvprojx`、`.pre-commit-config.yaml`、内存快照 —— 任务期**不在任务树里改**,留到 `done` 统一处理;用户显式豁免时(在任务树写、由 done 合回)要在交付报告里点名这条例外。 5. **清场必须先摘联接**:脚本先 `os.rmdir` 掉 `.venv` / `simulator/SDL2` 联接再 `git worktree remove`。手工拆树前必跑 **E 第 3 步**预扫拿到 `REPARSE: none`——否则 git 可能递归进联接把主树 `.venv` 一起删掉。 6. **活跃任务硬上限 8 = 脚本常量 `MAX_CONCURRENT`(`task_worktree.py:30`)——唯一事实源**:报错文案与 `new` 的插件树提示都插值它,AGENTS.md / 方案文档 / frontmatter / A 节的数字全是引用同步。改这个数字 → 全形态扫描走 `stale-doc-count-sweep` skill + 隔离小仓验证上限真生效;每棵磁盘代价按实测口径重述、别照抄旧数(细节 → 验证清单末条)。满了 exit 2 → A;悬挂台账 → E 第 6 步。 7. **工作树放仓库同级 `_wt/`,绝不在仓库内部**(否则污染 `git status`、`--all-files` 与全库搜索)。唯一例外 = 插件写死的仓内 `.agents/worktrees/`(现役)与 `.dsh-worktrees/`(旧版);现役目录池自写 `.gitignore`,旧路径由根 `.gitignore` 预置,两处均已纳入三个全库扫描排除面(→ F 节)。 diff --git a/.dsh/skills/task-worktree/reference/dsh-plugin-bridge.md b/.dsh/skills/task-worktree/reference/dsh-plugin-bridge.md index 8a9b6c75..3665290c 100644 --- a/.dsh/skills/task-worktree/reference/dsh-plugin-bridge.md +++ b/.dsh/skills/task-worktree/reference/dsh-plugin-bridge.md @@ -37,7 +37,7 @@ ``` - **两条联接坏了的样子完全不同**:缺 `.venv` → `ci_local.py` 的四级解释器回退**静默**落到机器级 - python(无 fontTools = `generated-fresh` 假红的老根因,AGENTS.md 记着);缺 `simulator/SDL2` → + python(无 fontTools = `generated-fresh` 假红的老根因);缺 `simulator/SDL2` → `build_sim.bat` 当场报错(`SDL2_DIR` 是裸 `set`,没有 env 逃生口)。所以列表只说「已联」不够—— 它按缺的那一样分别给后果,`adopt` 没补齐也只报「还不能算就绪」,不许说「现在可以跑」。 - **adopt 只碰联接**:已联的跳过;`simulator/SDL2` 若已是实体目录只告警不动;`.dsh-worktrees/` 之外的路径 @@ -63,7 +63,7 @@ - **`.venv` = 软需求**(有显式逃生门,但绕开有代价):`scripts/ci_local.py` 的解释器解析顺序(:108-:138)—— ① `DTU_PRECOMMIT_PYTHON`(显式配置,指错**立即报错**、不静默降级)→ ② `sys.executable` → ③ 仓库 `.venv` → ④ `shutil.which("python")` → ⑤ `_global_python_candidates()` 的常见机器级位置。树内没有 `.venv` 时会**静默**落到机器级 - 解释器 → 无 fontTools → `generated-fresh` 假红(AGENTS.md 记着的老根因);可以用 `DTU_PRECOMMIT_PYTHON` 顶掉, + 解释器 → 无 fontTools → `generated-fresh` 假红(老根因);可以用 `DTU_PRECOMMIT_PYTHON` 顶掉, 但要每台机器自己配——这就是它「软」的意思:有路可走,走得不爽。 结论口径:**要补就两条都补(`plugin adopt` 一次干完,成本近乎零),但「都必须」是错的**——SDL2 没有任何替代路径, diff --git a/.dsh/skills/ui-verify/SKILL.md b/.dsh/skills/ui-verify/SKILL.md index a11e7b1c..97a54dc7 100644 --- a/.dsh/skills/ui-verify/SKILL.md +++ b/.dsh/skills/ui-verify/SKILL.md @@ -23,7 +23,7 @@ cmake --build simulator/build --config Debug # 0) 构建模拟器(须 0 警 .venv\Scripts\python.exe scripts/check_coding_standard.py # 4) 代码规范检查(PASS) ``` -退出码:0=PASS / 1=断言失败 / 2=环境错误(exe 缺失等,先按 AGENTS.md 重建对应环境再重跑)。 +退出码:0=PASS / 1=断言失败 / 2=环境错误(exe 缺失等,先按 `new-machine-setup` skill 重建对应环境再重跑)。 ## 失败处置决策 diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index 039bd979..7970e34c 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -11,7 +11,7 @@ # # 明确不做的两件事(都是刻意为之): # 1. `/keil-build`(Keil UV4)—— 需本机 Keil 授权,runner 上不具备;且静态门禁的 cppcheck + -# 代码规范已覆盖"编译前的静态问题",真编译仍是开发者的本地红线(AGENTS.md)。 +# 代码规范已覆盖"编译前的静态问题",真编译仍是开发者的本地红线(本地 `keil-build` skill)。 # 2. `mem-numbers` / `mem-budget` 两根钩子 —— 事实源都是 `MDK-ARM/**/*.map`(Keil # 构建产物、已 gitignore),无 `/keil-build` 即无 `.map`。故本 workflow 在**检测不到 # .map 时自动跳过它们**(见下方 "决定跳过哪些钩子" 步骤),有 .map 的 runner 照常跑。 @@ -52,7 +52,7 @@ # (报错行号正是含中文的那一行,极易误判为逻辑错误)。 # **故本文件所有 `run:` 块内零非 ASCII**(中文仅出现在 YAML 的 name:/注释里—— # 那些由 Gitea 按 UTF-8 读,不喂给 PowerShell,安全)。 -# ⚠️ 与 AGENTS.md「字符串字面量必须纯 ASCII」同源;改脚本时务必守住。 +# ⚠️ 与「字符串字面量必须纯 ASCII」同源(口径 → docs/文档规范.md §2);改脚本时务必守住。 # # 🔴🔴 工具链探测必须【可离线自测 + 保留机器级安装兜底】(2026-10-11 第三次实测修正): # `33a4aa4`(DTU_* 变量改造)把 Python 探测内联进本文件,并把候选**收窄成两个** @@ -72,7 +72,7 @@ # 2026-10-12 实测 `master` 18 定义 / 17 报告、`v2-on-ui` 26 定义 / 25 报告)—— # 缺的正是 gitlint:`stages: [commit-msg]` 写在 **gitlint 上游的 .pre-commit-hooks.yaml** # 里(项目配置里 grep 不到这一行),而 `pre-commit run --all-files` 只跑 pre-commit stage。 -# 即 AGENTS.md 的"单行中文标题 ≤100 字符"门禁**本地有、CI 无**, +# 即"单行中文标题 ≤100 字符"门禁**本地有、CI 无**(规则定义在 .gitlint), # 且表现为"全绿"而非失败,所以一直没人发现。现由 `scripts/ci_gitlint_range.ps1` # 逐条校验本次 push/PR 引入的提交(消息文件必须写在**仓库内**且 **UTF-8 无 BOM**: # 跨盘符会被 pre-commit 拒绝 `path is on mount 'C:', start on mount 'D:'`, diff --git a/.gitignore b/.gitignore index e9f3f352..315895e4 100644 --- a/.gitignore +++ b/.gitignore @@ -132,7 +132,7 @@ simulator/tests/ref/*.png docs/images/*.png *.pyc -# Python venv (unified env, see AGENTS.md "Python 环境"; rebuild via requirements.txt) +# Python venv (unified env; rebuild via requirements.txt, see the new-machine-setup skill) .venv/ # Serial assistant runtime state (daemon log/meta, local runtime artifacts) diff --git a/App/README.md b/App/README.md index 8e59ec81..fbced22b 100644 --- a/App/README.md +++ b/App/README.md @@ -7,7 +7,7 @@ `Src/main.c`(CubeMX 初始化)→ `app_main_init`(本目录 `app/app_main.c`)→ `osKernelStart` → 6 个 FreeRTOS 任务(见 `task/`)。**`osKernelStart` 之前全是内核启动前代码,禁止调用任何 -FreeRTOS/CMSIS-RTOS API**(见 `AGENTS.md`「平台约束」)。 +FreeRTOS/CMSIS-RTOS API**(本条与「就绪屏障位必须 `osFlagsNoClear`」的理由 → `docs/子系统设计/控制台单写者日志设计.md` §2.5 与 `docs/架构设计/项目启动顺序管理.md`)。 ## 目录结构(按职责分层) diff --git a/App/algo/adc_cal.h b/App/algo/adc_cal.h index d7195437..78bd792c 100644 --- a/App/algo/adc_cal.h +++ b/App/algo/adc_cal.h @@ -194,8 +194,8 @@ uint32_t adc_cal_flags(adc_semantic_t sem); * 0 - 三路全 VALID(标定侧允许判据跑) uint8_t * 限定条件:任意上下文(纯读 `adc_cal_flags()`,与它同一条并发契约:int32 对齐 * 字读写原子、cfg poll 重载 µs 级混窗设计接受);**现查,本层不留任何状态** - * 函数说明:① **为什么恰好这三路**:V0.1 把 8 路电气量分给两片转换器(AGENTS - * 「双转换器无共同采样触发」),UA/UN/IA = TPAFE 侧这三路是**唯一有效** + * 函数说明:① **为什么恰好这三路**:V0.1 把 8 路电气量分给两片转换器(无共同 + * 采样触发,见 docs/硬件平台/ADC通道映射说明.md),UA/UN/IA = TPAFE 侧这三路是**唯一有效** * 的测量通道;UB/UC/IB/IC/IN 即使将来标定也另受 `CLIPPED` 品质约束 * (M5 快照层处理),不掺进本闭锁源。 * ② ⚠ **不得当「保护在跑」的总括用**:判据停走共四路来源,本函数只覆盖 diff --git a/App/algo/adc_input.c b/App/algo/adc_input.c index 87d4c542..275f904f 100644 --- a/App/algo/adc_input.c +++ b/App/algo/adc_input.c @@ -24,7 +24,7 @@ #include #include "adc.h" /* hadc1:MX_ADC1_Init() 已配 9 通道 / 144 cycles / 软件触发 */ -#include "tpafe5160.h" /* tpafe5160_snapshot():临界区原子快照(AGENTS 铁律) */ +#include "tpafe5160.h" /* tpafe5160_snapshot():临界区原子快照(唯一许可取数面) */ /* STM32 ADC1 通道号上限(F4 上 ADC_CHANNEL_0..15 的宏值即通道号 0..15) */ #define ADC_INPUT_STM32_CH_MAX 16U @@ -222,7 +222,8 @@ int adc_input_init(void) { /* 挂**一次** DMA,之后不再重启:ADC 由 TIM3 TRGO 每拍触发一轮 9 通道转换, * DMA 在 CIRCULAR 模式下自动搬运、硬件自动重载 NDTR → 每 2 拍绕一圈(乒乓)。 - * 内核启动前调用安全:只碰寄存器/HAL,不创建任何 CMSIS 对象(AGENTS 铁律)。 + * 内核启动前调用安全:只碰寄存器/HAL,不创建任何 CMSIS 对象 + * (内核前编码约束 → docs/架构设计/项目启动顺序管理.md §7)。 * 此刻 TIM3 尚未启动(app_main.c 步骤 6)→ 不会发生任何转换或搬运。 */ if (HAL_ADC_Start_DMA(&hadc1, (uint32_t *)s_stm32_dma, ADC_INPUT_STM32_DMA_LEN) != HAL_OK) { diff --git a/App/app/app_main.c b/App/app/app_main.c index 9099fc5a..2d73b4b2 100644 --- a/App/app/app_main.c +++ b/App/app/app_main.c @@ -133,7 +133,7 @@ int app_main_init(void) { * 用途:/serial-boot-test 把"芯片里正在跑的镜像"和"刚编出来的镜像"对上号。此前开机标记 * 全是固定串(App init OK / Network Init / ...),旧镜像也照样全中,于是 * "反复重下载、芯片一直是旧镜像"这类事故在自动闭环里完全不可见 - * (AGENTS.md 烧录铁律记的正是它)。代价:1 条 DBG ≈ 90 B Flash + 30 B 常量。 + * (`.dsh/skills/serial-boot-test/SKILL.md` 镜像身份核对一节的由来)。代价:1 条 DBG ≈ 90 B Flash + 30 B 常量。 * ⚠ 戳只在**本 TU 被重编**时才刷新(增量构建),故本文件必须 #include * "test_config.h":否则只切套件宏(TEST_SUITE_* / ENABLE_DESTRUCTIVE_TESTS) * 不重编本 TU,产品镜像与测试镜像顶着同一个戳,戳校验对"两种构建互换"失明 @@ -182,7 +182,7 @@ int app_main_init(void) { * 为什么放这儿而不是 defaultTask 的存储 bring-up: * ① 这一步只做 1 次 I2C 读 + 至多 1 次 I2C 写,落在内核启动前—— * 单线程、非 ISR、调度器还没跑(本函数不调任何创建类内核 API, - * AGENTS「内核前禁调创建类 API」那条与此无关); + * 「内核前禁调创建类 API」那条与此无关); * ② 保持介质是 RTC 用户 SRAM,不是文件系统:不必等 STORAGE_READY, * 也就不必在喂狗点上碰卷锁(这条链上根本没有卷操作可言); * ③ sd2506_init 失败时这里自然走"读不到"那一支:状态标成不可信、 diff --git a/App/app/ui_data_feed.c b/App/app/ui_data_feed.c index 3ddb4e2c..94e273e4 100644 --- a/App/app/ui_data_feed.c +++ b/App/app/ui_data_feed.c @@ -51,7 +51,7 @@ #include "ui_data_feed.h" /* 日志锚点:本文件只在"点表点数与快照点数不等"这一条静默漂移上打一条一次性日志 - * (每条约 90 B Flash,见 AGENTS「日志不是免费的」——常规发布路径刻意一条都不加)。 + * (每条约 90 B Flash + 216 B 栈,见 docs/子系统设计/控制台单写者日志设计.md §7.1——常规发布路径刻意一条都不加)。 * ⚠ DBG_TAG 必须在 include 之前定义:dbg_log.h 的 DBG_ERROR 是宏,漏 include 时 * ARMCC 只把 DBG_ERROR 当隐式声明函数放过编译期,错误落在链接期(L6218E * Undefined symbol),比漏写头文件本身更难归因 */ @@ -787,7 +787,7 @@ static void feed_fill_info(ui_data_info_t *p_snap, uint32_t tick_ms) { * 一次空队列判断(drain 无请求时只是一次计数比较); * 差值法吸收 tick 回绕(同 App/algo/adc_health.h 的 now_ms 口径)。 * 写路径失败态(ERR_RANGE/ERR_LOCKED/ERR_BUSY)走屏上通道,不打日志 - * (每条 DBG 约 90 B Flash + 216 B 栈,AGENTS「日志不是免费的」) + * (每条 DBG 约 90 B Flash + 216 B 栈,见 docs/子系统设计/控制台单写者日志设计.md §7.1) */ void ui_data_feed_tick(void) { uint32_t now; diff --git a/App/log/README.md b/App/log/README.md index 3af8e6c2..4da37288 100644 --- a/App/log/README.md +++ b/App/log/README.md @@ -115,4 +115,4 @@ - `docs/子系统设计/控制台单写者日志设计.md` - `docs/子系统设计/运行与自检记录设计.md` -- FatFs 陷阱:`AGENTS.md`「平台约束」 +- FatFs 陷阱(`FA_WRITE|FA_OPEN_APPEND` 缺一即 `FR_DENIED`、短写须校验字节数、严格 8.3):`docs/架构设计/STM32F4-Base存储架构说明.md` §10 第 10/11 项 diff --git a/App/log/sys_log_mcu.c b/App/log/sys_log_mcu.c index c3fb2e58..51bca707 100644 --- a/App/log/sys_log_mcu.c +++ b/App/log/sys_log_mcu.c @@ -632,7 +632,7 @@ static int s_clear_try(syslog_id_t id) { if (rc != 0) { /* 一次用户动作至多一条留痕(失败不重试,见 s_clear_service),不会刷屏, * 所以这里不需要像 B/F 项那样另立节流位。 - * ⚠ 留这条的成本约 90 B Flash(AGENTS「日志与工具链」);留它的理由: + * ⚠ 留这条的成本约 90 B Flash + 216 B 栈(见 docs/子系统设计/控制台单写者日志设计.md §7.1);留它的理由: * "清除失败但盘上还有记录"在串口之外没有任何可观测面(UI 只有一个整数状态)。 */ DBG_ERROR("clear %s fail (%d)", s_paths[id], (int)fr); } diff --git a/App/protocol/iec104/iec104_comm.c b/App/protocol/iec104/iec104_comm.c index 8502144b..e0460696 100644 --- a/App/protocol/iec104/iec104_comm.c +++ b/App/protocol/iec104/iec104_comm.c @@ -27,7 +27,7 @@ * 不触引擎任何写路径;内核前注册点 = app_main.c(「先注册后 load」契约,同 * adc_cal_init / run_par_init)。App/protocol 零日志惯例保持——注册失败留痕 * 由调用方 app_main.c 锚点负责,getter/setter 纯 RAM 不打日志(iec104Task - * 深链省栈,AGENTS 日志成本口径)。 */ + * 深链省栈,日志成本见 docs/子系统设计/控制台单写者日志设计.md §7.1)。 */ /* RAM 副本(引擎原地更新;u16 半字对齐读原子,撕裂域 = 单字段新旧值) */ typedef struct { @@ -156,7 +156,7 @@ uint8_t iec104_comm_dirty_peek(void) { * 同一调用点旁挂,每轮无条件 * 函数说明:失败不打日志是刻意的(App/protocol 零日志惯例,本文件无 DBG): * cfg_file_save 自身已有 DBG_ERROR 留痕 + 脏位保留 = 屏上 ERR 的 - * 判定源,再打一条就是重复锚点(AGENTS 日志成本口径) + * 判定源,再打一条就是重复锚点(日志成本见 docs/子系统设计/控制台单写者日志设计.md §7.1) */ int iec104_comm_store_save(void) { if (s_comm_dirty == 0u) { diff --git a/App/task/README.md b/App/task/README.md index 35cbad14..14081d8a 100644 --- a/App/task/README.md +++ b/App/task/README.md @@ -14,7 +14,7 @@ | `rs485_task.c/h` | (RS-485 任务) | — | 半双工 RS-485 协议通信 | | `../sync/time_sync.c` | timeSyncTask | Normal | 墙钟时间同步(实现不在本目录,见 [`../sync/README.md`](../sync/README.md)) | -> 上表栈大小/优先级以 `Src/freertos.c` 为准(`README.md`/`AGENTS.md` 的任务表由 +> 上表栈大小/优先级以 `Src/freertos.c` 为准(`README.md` 的任务表由 > `scripts/gen_task_table.py` 生成,勿手抄)。 ## 就绪屏障(重要) diff --git a/App/task/adc_task.c b/App/task/adc_task.c index 4a41bedf..dafb9abd 100644 --- a/App/task/adc_task.c +++ b/App/task/adc_task.c @@ -5,7 +5,7 @@ * (App/algo/sample_ring.c)→ 全周傅氏相量重算(App/algo/phasor.c) * + 帧统计(节拍由 TIM3 硬件定时器提供) * 状态说明:**B1 已落地(2026-10-10)**——本任务从空桩转为真实消费者: - * 用 tpafe5160_snapshot() 原子取数(AGENTS 铁律),统计帧数/无新帧次数, + * 用 tpafe5160_snapshot() 原子取数(唯一许可取数面),统计帧数/无新帧次数, * 并纳入看门狗 required_mask(TASK_WD_ADC)。 * **采样节拍**:由 **TIM3 更新中断(1 kHz)** 硬件触发—— * ISR 内调 tpafe5160_start_conv_irq()(Src/main.c 的 @@ -22,7 +22,8 @@ * V0.1 上只有 TPAFE 三路(UA/UN/IA)测量有效;本任务只取数,不做保护运算。 * 接入前必读:取数只用 adc_input_raw() / tpafe5160_snapshot()(临界区原子快照, * 仅任务上下文;旧的 get_buf/data_ready/clear_ready 已删除);接消费者前的 - * 强制门禁见根 AGENTS.md「接 ADC / RS-485 消费者前的强制门禁」+ 建任务前后 + * 强制门禁见 docs/算法/继电保护功能复现规划.md 的取数契约,RS-485 侧 + * → docs/产品需求/产品需求设计文档.md §5.10「重启门禁」;建任务前后 * 各跑 scripts/stack_report.py 做栈预算。 * 适用平台:STM32F407ZGTx + TPAFE5160 * 作者:王建锋 diff --git a/App/task/adc_task.h b/App/task/adc_task.h index eb86a9b6..463f6938 100644 --- a/App/task/adc_task.h +++ b/App/task/adc_task.h @@ -24,7 +24,8 @@ void adc_task_func(void *arg); /* 事件驱动消费的唤醒标志。 * TIM3 1 kHz 更新中断触发 CONVST 后,用本标志唤醒 adcTask 消费一拍。 * 线程标志在此是**命令位**(等待即消费),不是状态位 → 用 osFlagsWaitAny, - * 不加 osFlagsNoClear(AGENTS「就绪屏障位必须 osFlagsNoClear」只约束状态位) */ + * 不加 osFlagsNoClear(「就绪位必须 osFlagsNoClear」只约束状态位,见 + * docs/架构设计/项目启动顺序管理.md §2) */ #define ADC_WAKE_FLAG 0x0001U /* ISR 入口:由 Src/main.c 的 HAL_TIM_PeriodElapsedCallback(TIM3 分支)调用。 diff --git a/App/task/protect_task.h b/App/task/protect_task.h index b2342f54..44174f59 100644 --- a/App/task/protect_task.h +++ b/App/task/protect_task.h @@ -5,7 +5,7 @@ *(保护功能清单见 docs/算法/继电保护功能复现规划.md) * 故障闭锁(`adc_health_flags()` 电平位 → 元件状态复位 + 本拍不判据)。 * 判据本体在 `App/algo/prot_elm.c`(纯逻辑,主机侧纯逻辑单测已覆盖),本文件 - * 只做消费/编排(AGENTS 目录地图:task 不装算法)。 + * 只做消费/编排(目录归属:算法进 App/algo/,task 不装算法)。 * 线程约定:仅本任务调 prot_elm_run / prot_set_selfcheck(prot_elm.h 线程约定); * prot_set 写在 P4 前无第二写者(104 定值写经 pts→prot_set,见注)。 * 创建日期:2026-10-12(B5) diff --git a/Drivers/BSP/NET/net_socket.c b/Drivers/BSP/NET/net_socket.c index 4b55723d..cb765206 100644 --- a/Drivers/BSP/NET/net_socket.c +++ b/Drivers/BSP/NET/net_socket.c @@ -823,7 +823,7 @@ void net_process_messages(void) { } /* ===== UDP 数据面(2026-11-03 队列化改造)===== * 芯片事务全部在 netTask 里执行;源地址出参不搭 net_msg_t(按值拷贝, - * AGENTS 禁止加"回传用"字段),而是经 net_udp.c 的 per-fd 槽写回调用方 + * 禁止加"回传用"字段),而是经 net_udp.c 的 per-fd 槽写回调用方 * 内存,通知值只带结果码。执行体定义见 net_udp.c。 */ case NET_MSG_UDP_BIND: { /* 打开芯片侧 Socket(恒服务器模式);端口 0 = 由执行体取动态游标 */ @@ -1244,7 +1244,7 @@ int net_listen_locked(int sockfd) { * Socket 的 SINT(见 :469 门控)→ 全量清等于把别的在用 Socket 的门一并 * 焊死,其 CONNECT/DISCONNECT 等边沿事件永久丢失(RECV 属条件位,下轮 * 可补回,见 TRAP-NET-08)。 - * 全局寄存器交 net_poll 集中读清(AGENTS 模块约定:所有 CH395F 中断经 + * 全局寄存器交 net_poll 集中读清(模块约定:所有 CH395F 中断经 * net_poll 集中读取并清除);本 Socket 残留的全局位被 net_poll 读到时 * SINT 已为 0,自然收尾。TRAP-NET-12/-18 指定的两级预清落在 * net_connect_locked / net_close_locked / relisten 隔离段,均为单 Socket, @@ -2561,7 +2561,7 @@ int net_close(int sockfd) { * -1 - 失败(BADF/INVAL/入队失败) int * 限定条件:1. 必须在【非 netTask】上下文调用(同其它 net_* API,netTask 内会自等死锁) * 2. 场景=应用放弃会话(对时 30s 预算耗尽、协议超时);EOF 路径**不要**调 - * (net 层 auto_relisten 已接管,见 AGENTS 单连接断开语义) + * (net 层 auto_relisten 已接管 → docs/网络/网络自愈架构设计.md §4.10) * 函数说明:1. 单连接模型下挂起但 TCP 仍活的客户端会永久占住监听(keepalive * 被 PC 内核自动 ACK 判不死,《网络自愈架构设计》§5.2 E13);应用不得 * net_close 监听 fd → 本 API 拆连接不拆监听 @@ -2894,7 +2894,7 @@ int net_udp_get_mode(int sockfd) { * 返回值:字节数(> 0);<= 0 为**原始码**(NET_ERR_* 或 NET_ERR),errno 由公开入口写 int * 限定条件:参数已由本函数校验 * 函数说明:1. 源地址回传不占 net_msg_t 字段——先在本任务上下文把出参登记进 - * net_udp 的 per-fd 槽(AGENTS:net_msg_t 按值拷贝,禁止加回传字段), + * net_udp 的 per-fd 槽(net_msg_t 按值拷贝,禁止加回传字段), * netTask 执行时按槽写回调用方内存,通知值只带结果码。 * 同一 fd 上槽位互斥:并发收包在数据报语义下无法区分归属,直接 BUSY。 * 2. 本函数不碰 errno:超时与错误都以原始码返回,由 net_recvfrom / diff --git a/Drivers/BSP/NET/net_socket.h b/Drivers/BSP/NET/net_socket.h index eb635fa4..647ad705 100644 --- a/Drivers/BSP/NET/net_socket.h +++ b/Drivers/BSP/NET/net_socket.h @@ -48,7 +48,7 @@ typedef enum { * NET_MSG_UDP_RECVFROM - buf/len=载荷 + timeout_ms=等待预算 + flags * ⚠ 源地址出参(src_addr / addrlen 两个指针)**不走本结构**:结构按值拷入 * 队列,指针若在 int 字段里过桥,64 位主机单测构建会被截断,且违反 - * AGENTS「勿给 net_msg_t 加回传用字段」。改走 net_udp.c 的 per-fd 挂起槽 + * 禁止给 net_msg_t 加回传用字段。改走 net_udp.c 的 per-fd 挂起槽 * (调用方在入队前登记自己的指针,netTask 完成后写进调用方内存 + 通知值回码), * 与 TCP 挂起 recv 把数据直接写进调用方 buf 是同一个模型。 * 详见 docs/网络/BSD_Socket_API_使用指南.md §6 */ @@ -366,7 +366,7 @@ int net_recv_to(int sockfd, void *buf, int len, uint32_t timeout_ms); * netTask 内直接执行不入队——自投递给自身 = 死锁) * 函数说明:1. 目的地址是**入参**,按值拷进 net_msg_t.addr 随消息进 netTask, * 与 net_connect 传地址同一条通道;结果(已发字节数/错误码) - * 搭任务通知值回来(AGENTS「勿给 net_msg_t 加回传字段」)。 + * 搭任务通知值回来(勿给 net_msg_t 加回传字段)。 * 2. 带显式目的地址 = 芯片 DesIP/DesPort 切到该对端 → 本 Socket 记账进入 * **UDP 客户端形态**(p_sock->udp_mode = NET_UDP_MODE_CLIENT):此后 * `dest_addr = NULL` 的发送就发往它。**收包帧格式不受影响**——信息头是 @@ -506,7 +506,8 @@ int net_close(int sockfd); * 见函数说明 2;含幂等:无活动会话),-1 失败 * 限定条件:非 netTask 上下文(经消息队列委托,同其它 net_* API) * 函数说明:1. 适用场景=应用层放弃会话(对时 30s 预算耗尽、协议超时等): - * 单连接模型禁止对监听 fd net_close(连监听一起毁,AGENTS 约定), + * 单连接模型禁止对监听 fd net_close(连监听一起毁 → + * docs/网络/网络自愈架构设计.md §4.10), * 而挂起但 TCP 仍活的客户端会永久占住单连接监听(PC 内核自动 * ACK keepalive,芯片僵尸判不死——《网络自愈架构设计》§5.2 E13 定案缺口) * 2. 实现(2026-10-25 探针窗口心跳缺口修复起):auto_relisten fd = 登记 QUARANTINE 隔离 diff --git a/Drivers/BSP/NET/net_types.h b/Drivers/BSP/NET/net_types.h index 0a18bb09..c1e5ad22 100644 --- a/Drivers/BSP/NET/net_types.h +++ b/Drivers/BSP/NET/net_types.h @@ -204,7 +204,7 @@ typedef struct { * 头里取源地址;此处 CLIENT 的对端簿记(复用 remote_ip_arr[4] + remote_port, * 与 TCP 同一对字段)只用于发送去向与不足 8 字节残包的源地址兜底。 * 位置选择:紧接 in_use 之后,落在 type/in_use 之后原有的 2 字节填充里 - * (本结构 8 个实例,净增 RAM = 0,见 AGENTS RAM 红线)。 */ + * (本结构 8 个实例,净增 RAM = 0;预算核对见 docs/内存管理/RAM预算台账.md)。 */ uint8_t udp_mode; uint16_t local_port; /* 本地端口(主机序) */ uint16_t remote_port; /* 远端端口(主机序) */ diff --git a/Drivers/BSP/NET/net_udp.h b/Drivers/BSP/NET/net_udp.h index 52cf8bed..8e442e66 100644 --- a/Drivers/BSP/NET/net_udp.h +++ b/Drivers/BSP/NET/net_udp.h @@ -6,7 +6,7 @@ * net_recvfrom_to / net_udp_set_peer / net_udp_get_mode)住在 * net_socket.h,那边只负责参数校验、装消息入队、等通知值回结果。 * 为什么单独成模块:源地址(src_addr/addrlen)是**出参指针**,不能塞进按值拷入 - * 队列的 net_msg_t(AGENTS 明文「勿给 net_msg_t 加回传用字段」; + * 队列的 net_msg_t(明文禁止「给 net_msg_t 加回传用字段」; * 指针过 int 桥在 64 位主机单测构建还会被截断)。所以出参走本模块的 * per-fd 槽:调用方入队前登记自己的指针,netTask 结算时把源地址写进 * 调用方内存、错误码/字节数搭任务通知值回去——与 TCP 挂起 recv 把数据 diff --git a/Drivers/BSP/README.md b/Drivers/BSP/README.md index e0410110..2a1effcb 100644 --- a/Drivers/BSP/README.md +++ b/Drivers/BSP/README.md @@ -38,7 +38,7 @@ | NET | 就绪屏障位必须 `osFlagsNoClear`;`s_net_errno` 已按任务隔离(勿改回全局) | | 通用 | 自研代码**禁用 C 库堆分配**(MicroLIB 堆仅 512 B),动态内存只用 `pvPortMalloc/vPortFree` | -> 完整平台约束见根 `AGENTS.md`「平台约束」章,以及各模块的 Trap Records。 +> 完整平台约束的落点:隔离与错误码语义 → `.dsh/roles/network-specialist.md`(网络)/ `.dsh/roles/storage-specialist.md`(存储);中断与吞吐细节 → `docs/网络/网络自愈架构设计.md`、`docs/架构设计/STM32F4-Base存储架构说明.md`;C 库堆禁令 → `docs/门禁说明/coding-standard.md`。另见各模块的 Trap Records。 ## 相关文档 diff --git a/Drivers/BSP/TPAFE5160/README.md b/Drivers/BSP/TPAFE5160/README.md index 35616095..65aec510 100644 --- a/Drivers/BSP/TPAFE5160/README.md +++ b/Drivers/BSP/TPAFE5160/README.md @@ -22,7 +22,7 @@ - **`tpafe5160_init()` 做首帧有效性自检**:完整跑一帧转换+读取,若整帧读下来 FRSTDATA **没有发生任何跳变**(芯片没在驱动并行总线;板上上拉会把它钉死为高)→ 返回 `BSP_ERR_NO_DEVICE`(旧 `TPAFE5160_FRSTDATA_ERR(-3)`,2026-10-23 收编)并打 `[ERR] Init FRSTDATA no-toggle`。判据刻意不锁死"哪个 RD 边沿拉高/拉低"(手册只给"RD 下降沿 → FRSTDATA 高/低"两个跳变,本板未实测边沿次序),只要求"一帧内必须跳变" → 既抓死芯片,也不会因极性假设错误误杀好芯片 - 采样数据的消费者 `App/task/adc_task.c` **已实现**(ADC 采集链路,2026-10-10:`tpafe5160_snapshot()` 原子取数 + 帧统计;`adcTask` 在 `Src/freertos.c` 的 `USER CODE` 区创建)。**v2.2(2026-10-10)**:采样节拍改由定时器更新中断硬件触发,本任务退化为纯消费者;**v2.8(2026-10-10)**:节拍源改 TIM3(同时经 TRGO 触发 ADC1 + DMA),STM32 侧改为消费 DMA 乒乓缓冲,单拍耗时 122 µs → **8 µs** - CONVST→BUSY→RD 三段时序对**建立/保持时间敏感**,改动需对照芯片手册 -- ⚠️ 本项目 ADC 相关功能**新增任务/缓冲前须核算 RAM**(见 `docs/内存管理/`);接消费者前的强制门禁见根 `AGENTS.md`「接 ADC / RS-485 消费者前的强制门禁」 +- ⚠️ 本项目 ADC 相关功能**新增任务/缓冲前须核算 RAM**(见 `docs/内存管理/`);接消费者前的强制门禁 = 取数契约(只用 `tpafe5160_snapshot()`/`adc_input_poll()`,见 `docs/算法/继电保护功能复现规划.md`)+ 建任务前后各跑一次 `scripts/stack_report.py`;RS-485 侧的重启门禁 → `docs/产品需求/产品需求设计文档.md` §5.10 - ⚠️ **通道语义不是通道号**:`buf[i]` 对应哪个电气量必须查 `docs/硬件平台/ADC通道映射说明.md`(`buf[2]=IA`、`buf[5]=UN`、`buf[6]=UA`);V0.1 上 8 路电气量分属两片转换器属硬件缺陷(`docs/任务规划/硬件改版登记.md` §1)→ **禁止**跨转换器做相位/功率/功率因数类运算 ## 已知问题 diff --git a/Drivers/BSP/UI/ui_data.h b/Drivers/BSP/UI/ui_data.h index 32e27ea1..4a836ab3 100644 --- a/Drivers/BSP/UI/ui_data.h +++ b/Drivers/BSP/UI/ui_data.h @@ -404,7 +404,7 @@ typedef struct { * (状态与队列都不动:调用方的编程错误不该落成屏上的"越界") int * 限定条件:uiTask 上下文(页面按键钩子);与 drain 同上下文 → 无锁 * 函数说明:本函数**不**校验值域(越界与否是执行侧事实,在 drain 里整批预检), - * 也不碰 prot_set、不碰文件系统(落盘归 defaultTask,AGENTS 模块约定) + * 也不碰 prot_set、不碰文件系统(落盘归 defaultTask 的模块约定) */ int ui_data_param_request(const ui_data_param_req_t *a_req); diff --git a/Drivers/BSP/app_assert.h b/Drivers/BSP/app_assert.h index 9cf38776..92602c2c 100644 --- a/Drivers/BSP/app_assert.h +++ b/Drivers/BSP/app_assert.h @@ -7,8 +7,8 @@ * 差异见下方"落地差异"。 * 落地差异(相对早期示意稿,均为有意): * 1. 断言点**不再额外发一条 DBG_ERROR**:钩子本身就打印 file:line(断言唯一有 - * 价值的现场信息),而每条 DBG_* 调用点约 90 B Flash + 216 B 栈(AGENTS - * 「日志不是免费的」);断言点又常处在"内核状态已不可信"的现场,走裸控制台 + * 价值的现场信息),而每条 DBG_* 调用点约 90 B Flash + 216 B 栈(见 + * docs/子系统设计/控制台单写者日志设计.md §7.1);断言点又常处在"内核状态已不可信"的现场,走裸控制台 * 比走日志行缓冲更稳。 * 2. 本头落在 Drivers/BSP 根目录(与 dbg_log.h、bsp_err.h 同级),不是示意稿写的 * App/util:它是纯宏叶子能力(无状态、无数据、不依赖任何上层服务),BSP 与 @@ -120,7 +120,7 @@ extern void vApplicationAssertFailed(const char *file, long line); * 4. 断言条件**不得带副作用**:关闭态不求值、打开态才求值,带副作用等于让行为 * 随开关漂移——这是本宏唯一真正危险的误用形态。 * 5. 台架口径:MCU 钩子打印以 [ERR] 开头 → 真机上断言一旦触发,/serial-boot-test 必然判本次 - * 失败,这是刻意的(AGENTS「Forbidden 标记含 [ERR]」/ 出现 Fault 即不通过)。 + * 失败,这是刻意的(Forbidden 标记含 [ERR] / 出现 Fault 即不通过)。 */ #ifdef __cplusplus diff --git a/Drivers/BSP/bsp_err.h b/Drivers/BSP/bsp_err.h index 7965a463..9ebcb6f8 100644 --- a/Drivers/BSP/bsp_err.h +++ b/Drivers/BSP/bsp_err.h @@ -90,7 +90,7 @@ typedef int bsp_err_t; * 三、自旋圈数型超时不许叫 *_TIMEOUT_MS,命名须含 LOOP/COUNT 且注释写明非时间量; * 返回码一律不许叫 *_TIMEOUT,改返回 BSP_ERR_TIMEOUT。 * - * ⚠ 两条硬纪律(AGENTS 铁律,这里只复述到最近的使用点): + * ⚠ 两条硬纪律(这里只复述到最近的使用点,完整条文见 docs/门禁说明/coding-standard.md): * · 内核启动前不得传 BSP_WAIT_FOREVER:osKernelInitialize 之前任何阻塞调用都会挂; * · 长等待与重试循环必须在循环内喂看门狗(本仓 IWDG 有 required_mask 机制)。 */ diff --git a/MDK-ARM/README.md b/MDK-ARM/README.md index 49f57a0b..be2b8263 100644 --- a/MDK-ARM/README.md +++ b/MDK-ARM/README.md @@ -56,10 +56,10 @@ - 工具路径经 `DTU_*` 环境变量解析(`DTU_KEIL_UV4` = UV4.exe 完整路径,`DTU_STLINK_CLI` = ST-LINK_CLI.exe 完整路径;换机设变量即可,**无需改脚本**;契约见 `docs/环境与部署/本地工具路径环境变量方案.md`) - 本目录被 pre-commit 门禁**排除** -- 启动文件的 `Heap_Size = 512B` 是**自研代码禁用 `malloc` 的根因**(见 `AGENTS.md`) +- 启动文件的 `Heap_Size = 512B` 是**自研代码禁用 `malloc` 的根因**(`CODE-RULE-20`,依据与豁免 → `docs/门禁说明/coding-standard.md`) ## 相关文档 - 烧录/复位:`docs/测试说明/测试工具/ST-LINK_CLI_复位使用说明.md` -- 构建与验证:根 `AGENTS.md`「构建与验证」章 +- 构建与验证:`keil-build` skill(`.dsh/skills/keil-build/SKILL.md`,含 exit 2 三种分型与 "0 错误 0 警告" 判定) - 测试流程:`docs/测试说明/流程与规范/自动化测试流程.md` diff --git a/README.md b/README.md index 5d27b246..93f3b53e 100644 --- a/README.md +++ b/README.md @@ -205,7 +205,7 @@ STM32F4-Base/ ├── tools/ # 开发工具 │ └── font_gen/ # 中文字体生成工具 ├── ui_cn_chars.txt # 中文字体字符集 -├── requirements.txt # Python 依赖清单(统一 .venv 环境,见 AGENTS.md「Python 环境」) +├── requirements.txt # Python 依赖清单(统一 .venv 环境,重建见 new-machine-setup skill) ├── STM32F407-Demo.ioc # CubeMX 工程文件 ├── .pre-commit-config.yaml # pre-commit 钩子配置 ├── .gitlint # commit message 检查规则 @@ -219,7 +219,7 @@ STM32F4-Base/ ### 环境要求 - **Keil MDK-ARM v5** (ARMCC 编译器) -- **Python 3**(统一入口为仓库内 `.venv`,依赖见 `requirements.txt`,重建方法见 AGENTS.md「Python 环境」) +- **Python 3**(统一入口为仓库内 `.venv`,依赖见 `requirements.txt`,重建方法见 `new-machine-setup` skill / `docs/环境与部署/项目部署环境要求.md`) - **ST-Link** 或兼容调试器 ### 编译 diff --git a/Src/freertos.c b/Src/freertos.c index 02ae0fef..3964ae03 100644 --- a/Src/freertos.c +++ b/Src/freertos.c @@ -92,7 +92,7 @@ static int hook_ptr_ok(const void *p) * `USER CODE BEGIN Variables` 这个标准保护位(模板真实生成、名字从未变过 → 重生成不丢)。 * 数据来源:`scripts/stack_report.py`(Keil 静态调用图最坏链)+ 串口 `[STACK]` 运行时水位; * 底线规则:余量 ≥ max(1024 B ISR, 30%)。完整核算见 docs/内存管理/RAM使用分析与优化方案.md, - * 全表(含 ftpTask 1024 / uiTask 4096 的现值)见 AGENTS.md 任务表。 + * 全表(含 ftpTask 1024 / uiTask 4096 的现值)见本文件 `FREERTOS.Tasks` 段。 * * defaultTask 1280 words:扛 mount+mkfs+FAT 探针+cfg 加载+syslog 写+配置引擎 * (全深层 FatFS I/O)。原 512,2KB 实测峰值溢出——开启 diff --git a/docs/CI/远程CI完整指南.md b/docs/CI/远程CI完整指南.md index 905201b2..a533426b 100644 --- a/docs/CI/远程CI完整指南.md +++ b/docs/CI/远程CI完整指南.md @@ -1132,7 +1132,7 @@ foreach ($f in @("check_env.ps1","run_runner_watchdog.ps1")) { > 💡 **纯 ASCII 的脚本不受影响,也不需要 BOM**。现行两个文件的口径: > `check_env.ps1` 含中文注释 → **必须带 BOM**;`run_runner_watchdog.ps1`(由 > `scripts/ci_runner_bootstrap.ps1` 生成)**刻意写成纯 ASCII**,因此对编码免疫—— -> 生成它的模板也要求纯 ASCII,理由见仓库 `AGENTS.md` 的编码铁律。 +> 生成它的模板也要求纯 ASCII,理由见 `docs/文档规范.md` §2 的编码铁律。 > 🗑 旧脚本 `deploy_runner_task.ps1` 已废弃(§3.2),不再作为示例对象。 ### 7.2 日志位置与查看方式 diff --git a/docs/README.md b/docs/README.md index 609fcca7..e820b443 100644 --- a/docs/README.md +++ b/docs/README.md @@ -45,7 +45,7 @@ docs/ | 2 | [`项目架构总览.md`](架构设计/项目架构总览.md) | 六层分层、启动时序、存储/网络/UI 三栈、目录组织 | | 3 | [`项目启动顺序管理.md`](架构设计/项目启动顺序管理.md) | Event Flags 就绪屏障(取代魔法延时)的任务启动模型 | | 4 | [`项目部署环境要求.md`](环境与部署/项目部署环境要求.md) | 开发机/目标板/现场部署的完整环境核对清单 | -| 5 | [`项目部署环境要求.md`](环境与部署/项目部署环境要求.md) → 构建 | 跑通 `/keil-build` / `/serial-boot-test`(见根 `AGENTS.md`) | +| 5 | [`项目部署环境要求.md`](环境与部署/项目部署环境要求.md) → 构建 | 跑通 `/keil-build` / `/serial-boot-test`(见 `keil-build` / `serial-boot-test` skill) | | 6 | [`测试开发标准流程.md`](测试说明/流程与规范/测试开发标准流程.md) | 测试分层 静态门禁~保护判据与门禁决策表 | | 7 | [`嵌入式C语言代码规范_V1.0.md`](代码规范/嵌入式C语言代码规范_V1.0.md) | 命名/格式/注释规范(提交门禁强制) | | 8 | [`项目架构总览.md`](架构设计/项目架构总览.md) → 按需 | 进入具体子系统设计文档 | diff --git a/docs/UI设计/LVGL模拟器部署与使用说明.md b/docs/UI设计/LVGL模拟器部署与使用说明.md index a9dbc1e1..876ff6e6 100644 --- a/docs/UI设计/LVGL模拟器部署与使用说明.md +++ b/docs/UI设计/LVGL模拟器部署与使用说明.md @@ -178,7 +178,7 @@ MCU 端 `Drivers/BSP/dbg_log.h` 会引用 `sys_clock.h`(RTC 时间戳),PC 1. **`SDL2/SDL.h` 找不到**:需先执行 3.1 的 `include/SDL2/` 头文件复制步骤。 2. **`lv_conf.h` 找不到**:`LV_CONF_DIR` 必须在 `add_subdirectory(lvgl)` **之前**定义(CMake 变量顺序问题)。当前 CMakeLists 已正确处理,勿随意调整顺序。 3. **改 CMakeLists.txt 后不生效**:MSVC 生成器可能缓存旧配置,先删 `build/` 重建。 -4. **中文字符串文件编码**:源码是 UTF-8,CMake 已加 `/utf-8` 编译选项消除 C4819 警告。**不要**用 PowerShell `Set-Content` 等重写含中文的文件(参照 AGENTS.md 编码铁律)。 +4. **中文字符串文件编码**:源码是 UTF-8,CMake 已加 `/utf-8` 编译选项消除 C4819 警告。**不要**用 PowerShell `Set-Content` 等重写含中文的文件(参照 `docs/文档规范.md` §2 编码铁律)。 ### 6.2 渲染相关 diff --git a/docs/UI设计/UI_中文字体生成与配置.md b/docs/UI设计/UI_中文字体生成与配置.md index c56ea7cd..3a8018c5 100644 --- a/docs/UI设计/UI_中文字体生成与配置.md +++ b/docs/UI设计/UI_中文字体生成与配置.md @@ -27,7 +27,7 @@ 安装完成后验证可用:`lv_font_conv -h` 能打印用法即成功。 -> **Python 解释器(统一入口)**:用仓库内 `.venv`(已装 fontTools,见 AGENTS.md「Python 环境」): +> **Python 解释器(统一入口)**:用仓库内 `.venv`(已装 fontTools,重建见 `new-machine-setup` skill): > > ```powershell > & '.venv\Scripts\python.exe' tools/font_gen/make_font.py diff --git a/docs/UI设计/UI_界面制作流程.md b/docs/UI设计/UI_界面制作流程.md index c593346e..2c2a29d0 100644 --- a/docs/UI设计/UI_界面制作流程.md +++ b/docs/UI设计/UI_界面制作流程.md @@ -51,7 +51,7 @@ flowchart TD | C3 | 字符集 | 子集字体(当前 224 汉字/符号 + ASCII 0x20-0x7E,共 319 字形);**缺字显示空白**;新字必须重生成字体 | `tools/font_gen/` | | C4 | LVGL 内存池 | 16KB(`LV_MEM_SIZE`,2026-10-15 由 40KB 收缩;实测峰值 6,568 B = 池的 40%);任一时刻只放"当前导航路径 + 当前内容页" | `Lib/lv_conf.h` | | C5 | 文本 | 一律静态字符串(`lv_label_set_text_static`),禁止动态字符串/strdup | 架构文档 | -| C6 | 编码 | `Drivers/BSP/UI/*`、`ui_task.c`、`Lib/lv_conf.h` 为 **UTF-8 带 BOM**;改动只用 Edit 工具,**禁止** PowerShell/cmd 整文件重写(U+FFFD 不可逆) | AGENTS.md 铁律 | +| C6 | 编码 | `Drivers/BSP/UI/*`、`ui_task.c`、`Lib/lv_conf.h` 为 **UTF-8 带 BOM**;改动只用 Edit 工具,**禁止** PowerShell/cmd 整文件重写(U+FFFD 不可逆) | `docs/文档规范.md` §2 | | C7 | 代码共用 | `ui_menu.c` / 字体为 MCU 与模拟器共用源,**禁止**在 `simulator/` 复制副本 | 架构文档 | | C8 | 视觉禁区(1bpp) | 圆角 / 阴影 / 透明度 / 渐变 / 多色 / 抗锯齿 全部禁用;设计与代码都不得引入 | 物理限制 | | C9 | 双端注册 | 新增 `Drivers/BSP/UI/*.c` 必须**两处**手动注册:Keil `.uvprojx` + `simulator/CMakeLists.txt` 的 `UI_SOURCES` 列表(均为显式列表,无通配扫描)。只注册一端 = 另一端静默缺文件 | 实测(2026-09-03) | @@ -187,7 +187,7 @@ flowchart TD 3. & '.venv\Scripts\python.exe' tools/font_gen/make_font.py # 宋体 12px 1bpp + ASCII + 字符集 → ui_font_cn_12.c(全量重生成 + 自动补回宋体缺失的 ▶ 箭头,幂等;需 fontTools) 4. 生成物 diff 检查:新增字在位、旧字不变、Opts 行字符集与预期一致 ``` -- 一次性环境准备:`npm i -g lv_font_conv`;fonttools/pillow 统一装进仓库 `.venv`(`.venv\Scripts\python.exe -m pip install -r requirements.txt`,见 AGENTS.md「Python 环境」)。PATH 默认 python 是 msys64 的、无第三方库,勿用它跑 make_font.py +- 一次性环境准备:`npm i -g lv_font_conv`;fonttools/pillow 统一装进仓库 `.venv`(`.venv\Scripts\python.exe -m pip install -r requirements.txt`,重建见 `new-machine-setup` skill)。PATH 默认 python 是 msys64 的、无第三方库,勿用它跑 make_font.py - `ui_cn_chars.txt`(仓库根,受 git 跟踪)与 `ui_font_cn_12.c` **随代码一起提交** - 双端 `LV_FONT_DEFAULT` 均指向 `&ui_font_cn_12` → 重生成后两端自动生效 - P0 已知的新增字若含生僻字(宋体可能无此字形)→ 在写码前先手动验证字形,避免"代码写完才发现是空白" @@ -248,7 +248,7 @@ flowchart TD ## 六、P3:MCU 验证 -1. `/keil-build` → **0 错误 0 警告**(AGENTS.md 强制;有警告看 `MDK-ARM/build_log.txt`) +1. `/keil-build` → **0 错误 0 警告**(`keil-build` skill 的判定口径;有警告看 `MDK-ARM/build_log.txt`) 2. `/serial-boot-test`(一键 `.dsh/skills/serial-boot-test/scripts/run_boot_test.py`): - 采集窗口**先于烧录武装**(脚本 `--flash-cmd` 已保证顺序) - Required:`UI port init: OK;UI menu init: OK` + 本界面定制标记(按屏增补,如页头标题字样) diff --git a/docs/UI设计/UI_自动化测试流程.md b/docs/UI设计/UI_自动化测试流程.md index 70a6077a..01956598 100644 --- a/docs/UI设计/UI_自动化测试流程.md +++ b/docs/UI设计/UI_自动化测试流程.md @@ -10,12 +10,12 @@ | 项 | 说明 | |---|---| | 模拟器已构建 | 仓库根目录:`& "simulator\build_sim.bat"`(自动探测本机 VS2019/2022/2026 生成器,见 `simulator/README.md` §3.2) | -| Python | 统一入口 `.venv\Scripts\python.exe`(AGENTS.md「Python 环境」);两个回归脚本纯标准库,任意 python3 均可,为保持一致一律用 .venv | +| Python | 统一入口 `.venv\Scripts\python.exe`(重建见 `new-machine-setup` skill);两个回归脚本纯标准库,任意 python3 均可,为保持一致一律用 .venv | ## 二、流程总览 ```powershell -# 仓库根目录执行(python 统一用 .venv,见 AGENTS.md「Python 环境」) +# 仓库根目录执行(python 统一用 .venv,重建见 new-machine-setup skill) cmake --build simulator/build --config Debug # 0) 构建模拟器(须 0 警告) .venv\Scripts\python.exe simulator/tests/check_menu_rows.py # 1) 菜单 8 状态像素回归 + 池基线门禁 .venv\Scripts\python.exe simulator/tests/check_content_pages.py # 2) 内容页黄金参考回归 + 往返池门禁 diff --git a/docs/UI设计/UI_设计架构.md b/docs/UI设计/UI_设计架构.md index 701bcf32..3baa4fa8 100644 --- a/docs/UI设计/UI_设计架构.md +++ b/docs/UI设计/UI_设计架构.md @@ -46,7 +46,7 @@ MCU **无物理屏幕**:LVGL 做 160×160 **1bpp 单色离屏渲染**,帧缓 1. **RAM 紧张**:新增页面/控件/缓冲前必须核算 LVGL 池(16KB,实测峰值 6,568 B)与任务栈余量(见 `docs/内存管理/RAM预算台账.md`) 2. **新增汉字必须重新生成字体**(`tools/font_gen/` 两步),否则显示空白 3. 文本一律用静态字符串(`lv_label_set_text_static`),不 strdup -4. UI 相关文件为 **UTF-8 带 BOM**(`Drivers/BSP/UI/*`、`ui_task.c`、`Lib/lv_conf.h`),其余源码无 BOM;禁止 PowerShell 整文件重写(编码铁律,见 AGENTS.md) +4. UI 相关文件为 **UTF-8 带 BOM**(`Drivers/BSP/UI/*`、`ui_task.c`、`Lib/lv_conf.h`),其余源码无 BOM;禁止 PowerShell 整文件重写(编码铁律,见 `docs/文档规范.md` §2) 5. 模拟器与 MCU **共用** UI 源码(`ui_menu*.c` / `ui_font_cn_12.c`),禁止在 `simulator/` 下复制副本;新增文件须同时注册进 Keil `.uvprojx` 与模拟器 CMakeLists(双端注册) 6. 验证顺序:模拟器预览 → `/keil-build`(0 错 0 警)→ `/serial-boot-test`(Required 加 `UI port init: OK;UI menu init: OK`) 7. **`LV_DRAW_SW_COMPLEX` 必须为 1**(两端均显式声明):主界面顶部"开口浅 V"装饰含斜线,`lv_line` 的斜段仅在复杂渲染器下绘制(`draw_line_skew`),关闭则只画水平线、两腿消失。且 `LV_DRAW_SW_CIRCLE_CACHE_SIZE` 须非零(默认 4),否则零长数组编译报错(C2466) diff --git a/docs/UI设计/内容页架构.md b/docs/UI设计/内容页架构.md index 09d8c8d2..c2165e16 100644 --- a/docs/UI设计/内容页架构.md +++ b/docs/UI设计/内容页架构.md @@ -419,7 +419,7 @@ extern const content_page_def_t ui_page_device_info_desc; /* 描述符(Flash - 行表 `s_rows[]` 是模块私有(`static`),只有描述符对象是外部链接 - 动态页的差异:`rows = NULL`,改在描述符里给 `refresh`(逐行取数),行数变化再给 `count_cb` - 文件编码:`Drivers/BSP/UI/` 下为 **UTF-8 带 BOM**(中文字面量依赖 BOM 让 MSVC 认 UTF-8, - 见 AGENTS.md 编码铁律) + 见 `docs/文档规范.md` §2 编码铁律) ## 六、执行上下文与内存 diff --git a/docs/images/架构总览_端到端链路.svg b/docs/images/架构总览_端到端链路.svg index 6186bca9..270979b5 100644 --- a/docs/images/架构总览_端到端链路.svg +++ b/docs/images/架构总览_端到端链路.svg @@ -279,6 +279,6 @@ 服务与落点 对外 / 同构端 -口径:AGENTS.md「数据主线」+ docs/架构设计/项目架构总览.md(行号级证据在那份文档与代码里)。RS-485 采集未接线:rs485_task 有实现但不建任务,接线后数据进语义取数层;其余行为条件(未标定闭锁 / 就绪位 NoClear / CH395F 单连接 / V0. -1 双转换器无共同采样触发)见正文,它们只改变判据与端口、不改变本图的框与连线。 +口径:docs/架构设计/项目架构总览.md §1「全景分层架构」(含 §1.3 端到端链路鸟瞰;行号级证据在那份文档与代码里)。RS-485 采集未接线:rs485_task 有实现但不建任务,接线后数据进语义取数层;其余行为条件(未标定闭锁 / 就绪位 NoClear / C +H395F 单连接 / V0.1 双转换器无共同采样触发)见正文,它们只改变判据与端口、不改变本图的框与连线。 diff --git a/docs/产品需求/产品需求设计文档.md b/docs/产品需求/产品需求设计文档.md index 686574c5..03707b48 100644 --- a/docs/产品需求/产品需求设计文档.md +++ b/docs/产品需求/产品需求设计文档.md @@ -1507,7 +1507,7 @@ pre-commit run --all-files | 结构与注册 | `registration-check`、`test-suite-switch`、`cubemx-survival` | 双端注册、套件互斥、CubeMX 保护区审计 | **受管事实源(禁止手改,由脚本生成)**: -- 任务表(`README.md` / `AGENTS.md`)← `scripts/gen_task_table.py` +- 任务表(`README.md` 与 `AGENTS.md` 的生成块)← `scripts/gen_task_table.py`(两者都是**生成的**,勿手改) - 内存/Flash 快照 ← `scripts/check_mem_numbers.py` - 菜单表 ← `tools/menu_gen/gen_menu.py` - 中文字体 ← `tools/font_gen/make_font.py` @@ -1834,5 +1834,5 @@ pre-commit run --all-files | 实机测试指南 | [`docs/测试说明/板级测试/实机测试实施指南.md`](../测试说明/板级测试/实机测试实施指南.md) | | 测试标准流程 | [`docs/测试说明/流程与规范/测试开发标准流程.md`](../测试说明/流程与规范/测试开发标准流程.md) | | RAM 预算与优化 | [`docs/内存管理/RAM使用分析与优化方案.md`](../../docs/内存管理/RAM使用分析与优化方案.md) | -| AI 开发规范 | `AGENTS.md`(仓库根) | +| AI 开发规范 | `AGENTS.md`(仓库根,agent 入口索引;事实归属见 `docs/文档规范.md` §6) | | 开发者入门 | `README.md`(仓库根) | diff --git a/docs/代码规范/pre-commit使用说明.md b/docs/代码规范/pre-commit使用说明.md index 20ae2535..d4185025 100644 --- a/docs/代码规范/pre-commit使用说明.md +++ b/docs/代码规范/pre-commit使用说明.md @@ -102,7 +102,7 @@ git commit | **增量拦截三段式** | 规则恒生效 + 存量钉在基线/台账 + `--prune` 点名"已还清、请删行";**脚本刻意没有 `--write`**(不提供"一条命令把现状洗成合法"的入口)。使用者(2026-10-26 实跑核对):`layer-deps`(**基线内 3** + ALLOW 永久豁免 3,共见 6 处)、`bsp-err`(38 条)、~~已退役的 `id-check`~(工作区台账已还清 = **0 条指纹 / 0 处**;HEAD 那版是 303 条指纹 / 651 处)。原写「layer-deps(6)」「id-check 台账 640 处」都是没跟着还账更新的旧数 | | **没有 `.map` 即跳过** | `mem-numbers` / `mem-budget` 在无 Keil 构建的机器(含远端 CI)上是**跳过**,不是"通过"——别把跳过读成有余量 | | **配置自己坏 = 全部静默不跑** | 改完 `.pre-commit-config.yaml` 的验收不是过 `check-yaml`,而是实跑 `-m pre_commit run --all-files`,确认目标钩子**出现在输出里**且状态不是 `Skipped` | -| **范围策略** | 第三方与生成物只靠 `.gitignore` 与顶层 `exclude`(不在各钩子里重复写目录名);权威口径 → `AGENTS.md` 提交门禁一节 + §5.5 | +| **范围策略** | 第三方与生成物只靠 `.gitignore` 与顶层 `exclude`(不在各钩子里重复写目录名);权威口径 → 本文 §5.5 + `.pre-commit-config.yaml` 顶层 `exclude` | | **新增一个门禁的三步** | ① 配置落地并**做一次注入自证**(故意违反一次,看它是否当场 FAIL);② 在 `docs/门禁说明/` 落一篇,**"限制与盲区"一节不许留空**;③ 在 `docs/门禁说明/README.md` 索引加一行 | ### 2.3 快速自查入口 @@ -134,7 +134,7 @@ git commit | RAM 静态占用 | `& '.venv\Scripts\python.exe' scripts/ram_report.py` | 涨了的段要能指到具体模块与函数 | | RAM 总量红线(`mem-budget` 的入口) | `& '.venv\Scripts\python.exe' scripts/ram_baseline.py --gate` | >92% 即 1;⚠ **0 包含「没有 `.map` 就跳过」——跳过不等于有余量** | | 代码规范(含 CODE-RULE-17 / 20) | `& '.venv\Scripts\python.exe' scripts/check_coding_standard.py <本笔的 .c/.h>` | 有违规即 1 | -| BOM 漂移 | `& '.venv\Scripts\python.exe' scripts/check_bom_drift.py --all` | HEAD 有 BOM 而工作区没有 → 1;⚠ **别用「有 BOM 就是错」的外行判据**——`Drivers/BSP/UI/*`、`App/task/ui_task.c` 等本就该带 BOM(§2.2 与 AGENTS 铁律) | +| BOM 漂移 | `& '.venv\Scripts\python.exe' scripts/check_bom_drift.py --all` | HEAD 有 BOM 而工作区没有 → 1;⚠ **别用「有 BOM 就是错」的外行判据**——`Drivers/BSP/UI/*`、`App/task/ui_task.c` 等本就该带 BOM(名单与理由 → `docs/文档规范.md` §2;本文件 §2.2) | | 乱码 U+FFFD | `& '.venv\Scripts\python.exe' scripts/check_mojibake.py <本笔文件>` | 出现即 1 | | **字节卫生 = 改写型钩子的只读等价** | 下面的一行式 + `git diff --check` | 一次查完**待提交清单(含未跟踪新文件)**的 CR / 缺尾换行 / U+FFFD / 行尾空格,全程不写盘 | | 受影响模块的主机单测 | `& '.venv\Scripts\python.exe' test/host/<模块>/run_unit_test.py` | 只跑你碰的那几套;**改过骨架** `test/host/common/unit_test_harness.py` 就要跑全套(等价 22 根钩子同时触发) | @@ -332,7 +332,7 @@ $env:PATH = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Env | 文件 | 位置 | 说明 | |---|---|---| -| `.pre-commit-config.yaml` | 仓库根 | 钩子配置(**52 个钩子**声明数,一次 `git commit` 实跑 49 根;口径 = YAML 解析后的 hook 条目数,自查命令 → `docs/门禁说明/README.md` §2。声明数与一次提交的实跑数分列,勿混写;计数改动的完整台账只记在 AGENTS.md 提交门禁节与本目录 README §2,本行不重述)。逐项详解在 `docs/门禁说明/`(索引 `docs/门禁说明/README.md`;主机侧单测 **22 根**合一篇,含各套件来历与「22 套无专属钩子」台账(现值 2026-10-29) `docs/门禁说明/host-unit-tests.md` §6;UI 侧另有 `font-charset` 与 `ui-golden` 两篇) | +| `.pre-commit-config.yaml` | 仓库根 | 钩子配置(**52 个钩子**声明数,一次 `git commit` 实跑 49 根;口径 = YAML 解析后的 hook 条目数,自查命令 → `docs/门禁说明/README.md` §2。声明数与一次提交的实跑数分列,勿混写;计数改动的完整台账只记在 `docs/门禁说明/README.md` §2,本行不重述)。逐项详解在 `docs/门禁说明/`(索引 `docs/门禁说明/README.md`;主机侧单测 **22 根**合一篇,含各套件来历与「22 套无专属钩子」台账(现值 2026-10-29) `docs/门禁说明/host-unit-tests.md` §6;UI 侧另有 `font-charset` 与 `ui-golden` 两篇) | | `.gitlint` | 仓库根 | gitlint 规则(宽松,兼容中文) | | `.cubemx_survival_baseline.json` | 仓库根 | CubeMX 易失定制基线(哈希;`--write` 重建) | | `scripts/check_mojibake.py` | scripts/ | U+FFFD 检测脚本 | @@ -346,7 +346,7 @@ $env:PATH = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Env | `scripts/check_font_charset.py` | scripts/ | UI 字符集差集检查(复用 `tools/font_gen/` 提取与 cmap 解析规则,防缺字白框) | | `scripts/check_layer_deps.py` | scripts/ | 分层方向门禁(BSP 反向 include App 的增量拦截,存量基线只减不增) | | `scripts/check_bsp_err.py` | scripts/ | BSP 错误码与超时命名门禁(三条规则的增量拦截,存量 19 条基线只减不增;`--emit-baseline` 建基线) | -| `docs/代码规范/嵌入式C语言代码规范_V1.0.md` | docs/代码规范/ | 代码规范原文(CODE-RULE-01~CODE-RULE-20 规则来源;`CODE-RULE-20` 出处不在规范正文而在 AGENTS.md 平台约束,见 `docs/门禁说明/coding-standard.md`) | +| `docs/代码规范/嵌入式C语言代码规范_V1.0.md` | docs/代码规范/ | 代码规范原文(CODE-RULE-01~CODE-RULE-20 规则来源;`CODE-RULE-20` 出处以 `docs/门禁说明/coding-standard.md` §2 为准) | | `docs/代码规范/cppcheck使用说明.md` | docs/代码规范/ | cppcheck 钩子详解(规则/配置/抑制) | | `docs/文档规范.md` | docs/ | 文档体系规范(链接形态/命名/门禁要求) | | `docs/代码规范/pre-commit使用说明.md` | 本文档 | 部署与使用说明 | diff --git a/docs/内存管理/RAM使用分析与优化方案.md b/docs/内存管理/RAM使用分析与优化方案.md index 8f9159dd..b8d0625d 100644 --- a/docs/内存管理/RAM使用分析与优化方案.md +++ b/docs/内存管理/RAM使用分析与优化方案.md @@ -209,7 +209,7 @@ dhara 失败类 +84;RO 另 +208,全是该失败类名表)→ `ER_IROM1` | 组件 | 大小 | 说明 | |---|---|---| | 启动栈 | 1,024 B | `startup_stm32f407xx.o`,仅 `HAL_Init`/`app_main_init` 期间 | -| C 库堆 | 512 B | `Heap_Size EQU 0x200` → **自研代码禁用 C 库 `malloc`**(AGENTS.md 铁律;lftpd 的 `malloc` 隐患见 §2.4-1 与 §4.2.1) | +| C 库堆 | 512 B | `Heap_Size EQU 0x200` → **自研代码禁用 C 库 `malloc`**(权威口径 → `docs/门禁说明/coding-standard.md` §2 CODE-RULE-20;lftpd 的 `malloc` 隐患见 §2.4-1 与 §4.2.1) | | C 库代码(Flash) | ~4.2 KB | printf / 浮点 / 字符串 | #### 2.6.4 Flash 1 MB 分布 @@ -643,7 +643,7 @@ ISR 余量:该任务运行期间可能被中断打断的最深中断链(SPI/ ### 阶段 3:长效机制(0.5 天 + 长期) 1. **RAM 预算台账**(✅ **2026-10-12 落地** `docs/内存管理/RAM预算台账.md`,模板见 §8.2):记录每个 Region/缓冲/栈的计划值、实测值、变更历史;每次改内存相关代码必须更新 -2. **AGENTS.md 增补**(✅ 2026-09-21 已完成:"内存预算紧张"条目已含 `ram_report.py`/`stack_report.py` 数据源与"改栈前后各跑一次"要求) +2. **内存预算口径增补**(✅ 2026-09-21 已完成:本文件 §2.3 已含 `ram_report.py`/`stack_report.py` 数据源与"改栈前后各跑一次"要求) 3. **pre-commit 门禁**(✅ **2026-10-12 落地** `mem-budget` 钩子 = `scripts/ram_baseline.py --gate`):钩子解析最新 map,RW_IRAM1 使用率 >92% 或 RW_CCM 超限 → 提交拦截并附 Top-10 RW+ZI 对象表 4. **/serial-boot-test 扩展**:`verify_log.py` 增加可选 Required 标记 `"[MEM] heap free"`,把堆余量下限纳入自动化回归 5. **map diff 常态化**:每次 `/keil-build` 后跑 `ram_report.py`,ZI 增量 >1KB 的改动必须在提交说明中解释 @@ -676,7 +676,7 @@ ISR 余量:该任务运行期间可能被中断打断的最深中断链(SPI/ | 步骤 6 | §4.1.2 CCM(scatter + section + 门禁宏) | map 显示 `RW_CCM`;关 `APP_CCM_ENABLE` 也能编译通过 | ⏸ **暂缓(2026-10-15 裁定)**;已完成部分仅 `RW_CCM` + 堆迁入(09-21),缓冲 section 迁移与门禁宏不再排期 | | 步骤 7 | §4.1.3 栈缩减(按步骤 3 数据)+ 复测 | 每任务 `free_min ≥ 新栈×30%`,无溢出钩子触发 | ⏸ **暂缓(2026-10-15 裁定)**(目标值已按 09-21 实测修正,重开时可直接用) | | 步骤 8 | §4.2.2 堆 48K→32K + 复测 | 全负载 `heap free ≥ 8KB` | ⏸ **暂缓(2026-10-15 裁定)**;⚠ 2026-10-12 保护任务 反向扩容至 56 KB,重开时须重跑 `stack_report.py` + 上板 `min_ever` | -| 步骤 9 | §4.1.5 小项 + 台账/门禁/AGENTS.md | `/keil-build` + `/serial-boot-test` 全绿 | ◐ AGENTS.md 内存条目已增补(09-21);台账 / 趋势 / `mem-budget` 三件套 ✅ 2026-10-12(**常开,不受暂缓影响**) | +| 步骤 9 | §4.1.5 小项 + 台账/门禁/本文 §2.3 | `/keil-build` + `/serial-boot-test` 全绿 | ◐ 内存预算口径已增补(09-21,现落在 §2.3);台账 / 趋势 / `mem-budget` 三件套 ✅ 2026-10-12(**常开,不受暂缓影响**) | 每步都必须 `/keil-build` 通过(0 错误 0 警告)后再进入下一步;涉及 UI 的步骤用 `simulator` 先过一遍再上实机。 @@ -690,7 +690,7 @@ ISR 余量:该任务运行期间可能被中断打断的最深中断链(SPI/ | 高水位低估 | 启动后未触发的路径(如格式化失败分支)没算进去 | 测试套件覆盖异常分支;保留 ≥30% free_min 底线 | | 第三方代码改动 | lftpd 被 pre-commit 排除,改动不受检查 | 最小侵入、台账登记、升级 lftpd 时需重放补丁 | | CubeMX 重生成 | `freertos.c`/`FreeRTOSConfig.h` 的 USER CODE 区受保护,但 CubeMX 改配置会覆盖部分生成区 | 所有内核宏改动只集中在 USER CODE 区与 `Inc/FreeRTOSConfig.h`(`App/app/app_cfg.h` 已无任何宏,不是宏的落点);`.ioc` 与代码双向核对 | -| 编码安全 | 新增 .c/.h 为 UTF-8 无 BOM;`Drivers/BSP/UI/*` 为 UTF-8 带 BOM | 遵守 AGENTS.md"源码编辑与编码安全"铁律:只用 Edit 工具改,不整文件重写 | +| 编码安全 | 新增 .c/.h 为 UTF-8 无 BOM;`Drivers/BSP/UI/*` 为 UTF-8 带 BOM | 遵守 `docs/文档规范.md` §2 的编码铁律:只用 Edit 工具改,不整文件重写 | ## 8. 附录 diff --git a/docs/内存管理/内存内容分配策略.md b/docs/内存管理/内存内容分配策略.md index 7b1810cf..66ab6185 100644 --- a/docs/内存管理/内存内容分配策略.md +++ b/docs/内存管理/内存内容分配策略.md @@ -57,7 +57,7 @@ | CPU-only + 自愈/瞬态(帧缓冲、渲染状态) | SRAM | 无需保护;DMA 门保留(R4) | | CPU-only + 持久程序状态(配置引擎、FAT 卷状态、网络状态机) | SRAM(默认) | 损坏属中级事故(可自愈/可重格式化恢复);CCM 配额留给致命类 | -- **R6(容量台账)**:任何新增静态缓冲 >4KB、或改动 scatter/堆大小,必须先核 §6 台账余量,改后同步更新 §6 数字、`.sct` 头注释与 `AGENTS.md` 栈表。 +- **R6(容量台账)**:任何新增静态缓冲 >4KB、或改动 scatter/堆大小,必须先核 §6 台账余量,改后同步更新 §6 数字、`.sct` 头注释与 `Src/freertos.c` 的栈配置(任务栈表由 `scripts/gen_task_table.py` 从源码生成,勿手改文档副本)。 ## 5. 决策记录:2026-09-21 CCM 驻留者裁决(堆 vs LVGL) @@ -108,7 +108,7 @@ CCM 64KB 只能容纳 {FreeRTOS 堆 48KB} 与 {LVGL 集合 ~52.5KB} 之一(两 ### 5.6 若未来确需改判 触发条件:测试构建 SRAM 余量不足,**且**已耗尽 `RAM使用分析与优化方案.md` 的帧副本去重(−6.4~9.6KB)与 LVGL 池缩减等低代价手段。 -流程:改 scatter → 走 §7 完整验证阶梯 → 同步更新本文档、`AGENTS.md`、`.sct` 头注释。在此之前,方案 A 是唯一有效布局。 +流程:改 scatter → 走 §7 完整验证阶梯 → 同步更新本文档、`.sct` 头注释与 `Src/freertos.c`(栈表源头)。在此之前,方案 A 是唯一有效布局。 ## 6. 容量台账(2026-10-29 冻结值;**本次改动后的当前值见 §6.1**,两处链接时刻不同、不互相加减;原为产品构建 task/wave-record 分支终值;2026-09-21 最坏构建=存储套件的历史基线见 `docs/内存管理/RAM预算台账.md` 趋势) @@ -135,7 +135,7 @@ LVGL 集合明细(均在 SRAM):LVGL 池 16,384B(`lv_mem_core_builtin.o` - **三档对照(SRAM1)**:81,536 B / 62.2 %(`scripts/ram_baseline.tsv` 2026-10-28 行)→ 88,296 B(录波数据面终值)→ **89,936 B / 68.6 %**(含 UI 道终值),累计 **+8,400 B**;`RW_CCM` 三档恒 57,376 B —— 设计文档 `docs/子系统设计/故障录波设计说明.md` §7 的「不进 CCM」落位达成,也没有挤动 CCM。 - **预估 vs 实测都要留**:设计文档 §7 原估静态增量约 5.9 KB(环 5,120 + 索引状态 32 + 双缓冲 512 + 读窗 256),实测数据面 +6,760 B。差额构成:`FIL` 528 B、`DIR`/`FILINFO`、段头副本 136 B、打包上下文(内含一份 136 B 段头)原估未记账;反向一项——落盘实际是**单缓冲 256 B**,不是预估的 512 B 双缓冲。只写实测会让下一次估算照着 6.7 KB 走、看不到原估漏了哪几项。 - **Flash**:`ER_IROM1` 264,580 → 270,248(数据面 +5,668 B)→ 272,300(UI 道 +2,052 B)→ 272,360(落盘判废复检 +60 B)→ **272,336 B**(cppcheck 返工:把变量声明搬进最小作用域,纯搬声明 −24 B),累计 **+7,756 B**、占 26.0 %;`Total ROM` 274,308 B(26.2 %)、`Code` 243,552 B。RAM 三项(RW 1,972 / ZI 145,388 / RW_IRAM1 89,936 B / 68.6 %)与 CCM 57,376 B / 87.9 % 均未变。 -- **栈:9 任务全 PASS、未抬栈**(`scripts/stack_report.py` 静态最坏链)——adcTask 1,424 B(余 1,136 B / 44 %)、defaultTask 3,040 B 不变、protectTask 880 B、uiTask 1,336 B(余 15,048 B / 91 %)。R6 三处同步里 `AGENTS.md` 栈表这一处的结论是**核对过、数值未变**。 +- **栈:9 任务全 PASS、未抬栈**(`scripts/stack_report.py` 静态最坏链)——adcTask 1,424 B(余 1,136 B / 44 %)、defaultTask 3,040 B 不变、protectTask 880 B、uiTask 1,336 B(余 15,048 B / 91 %)。R6 三处同步里「`Src/freertos.c` 栈配置 + 由它生成的文档栈表」这一处的结论是**核对过、数值未变**。 - **为什么比上一版低**:本表 2026-10-12 版记 95,816 B / 73.1 %,高于今天的 89,936 B。原因是此后 LVGL 内部池由 40 KB 缩到 16 KB(`docs/内存管理/RAM预算台账.md` §3「缩池 ✅ 2026-10-15」行;`scripts/ram_baseline.tsv` 2026-10-12 与 2026-10-24 两行的 `top_rwzi` 列可见 `lv_mem_core_builtin.o` 40960 → 16384)——**不是本波回收了什么**。 - **子系统归集的坑(本卡实测 → 2026-10-29 已修)**:`scripts/ram_baseline.py` 的 `subsystem_of()` 按对象名前缀首匹配,当时表里没有 `wave_` 前缀 → 录波环 `wave_ring.o` 5,300 B 落进 **「其它」(当时 15,853 B,参考值、无配额)**,配额 8 KB 的「应用」行看不见它;落盘道 `default_task.o`(+1,204 B)与 `adc_task.o` 才计入「应用」(当时现值 16,888 B,本波前该行已在配额外,成因见 `docs/内存管理/RAM预算台账.md` §2 的应用条目)。**同日后续**:补齐 12 个 `App/` 对象(9,445 B)的前缀,并加兜底——`App/**/*.c` 编出的对象只要落进「其它」,`python scripts/ram_baseline.py --gate` 就逐条 WARN 点名(软提醒不拦)。结论仍然有效:**子系统配额行不是录波预算的判据**,要按本节 per-file 台账读;差别只在「应用」行现在真含录波支路,两个口径不再互相看不见。 @@ -172,7 +172,7 @@ LVGL 集合明细(均在 SRAM):LVGL 池 16,384B(`lv_mem_core_builtin.o` 5. 恢复跑(`ENABLE_STORAGE_RECOVERY_TESTS`):期望 **3/3 PASSED** 6. **破坏性用例默认关闭**(见 `test_config.h` 的 `ENABLE_DESTRUCTIVE_TESTS`):写/擦 NAND、格式化、坏块注入与 FatFS 写类用例只在首次上电/产线首启或明确需要时开启——2026-09-21 实测一轮破坏性 GD5F 运行即让 dhara 多记一个坏块(容量 95248 → 95200,且该计数持久化在 dhara journal checkpoint 头里,`nand_ftl_format` 清不掉);日常回归请保持只读模式。容量满值 = **96064 pages(187 MB)**,被扣掉的容量可用 `ENABLE_STORAGE_RECOVERY_TESTS` + `STORAGE_RECOVERY_FULL_WIPE`(全片擦除 + 重建 BBT)恢复(实测 95200 → 96064 ✓) -通过全部关卡后:更新 §6 台账、`AGENTS.md` 栈表、`.sct` 头注释,并把本次裁决补入 §5。 +通过全部关卡后:更新 §6 台账、`Src/freertos.c` 栈配置(连同由它生成的文档栈表)、`.sct` 头注释,并把本次裁决补入 §5。 ## 8. 附:策略落点索引 diff --git a/docs/内存管理/存储栈RAM优化调研.md b/docs/内存管理/存储栈RAM优化调研.md index de48521e..40ce93f5 100644 --- a/docs/内存管理/存储栈RAM优化调研.md +++ b/docs/内存管理/存储栈RAM优化调研.md @@ -42,7 +42,7 @@ ## 4. 回归与基线 - **FTP 吞吐基线(2026-09-21 实测,4MB 文件,端到端含网络;瓶颈在存储侧,100M 网络非瓶颈)**:STOR **126.9 KB/s**(32.3s)/ RETR **321.4 KB/s**(12.7s),回传逐字节 MATCH(测试文件已自清理)→ 两条 FTP 相关方案前后各留一轮实测对比(`FF_FS_TINY` 那条预期吞吐降幅 20~40%) -- `FF_FS_TINY` 前后各跑一次 `stack_report.py` + `ram_report.py`(AGENTS.md 门禁) +- `FF_FS_TINY` 前后各跑一次 `stack_report.py` + `ram_report.py`(`mem-budget` skill 的测量口径 + `scripts/check_mem_numbers.py` 门禁) - 迁 CCM 方案的 ②(页缓冲入 CCM 走轮询)须以实测吞吐定去留:若 NAND 读吞吐降幅 >30%,则只迁 CPU-only 侧(①) - `s_copy_buf` 分块与 copy-back、数据块减半等小项:待 RAM 余量需要时再议 - 下次存储改动照常执行台架破坏性套件 + 掉电 resume diff --git a/docs/子系统设计/ADC采样节拍设计.md b/docs/子系统设计/ADC采样节拍设计.md index d0cfae4d..8e5fd1dd 100644 --- a/docs/子系统设计/ADC采样节拍设计.md +++ b/docs/子系统设计/ADC采样节拍设计.md @@ -333,11 +333,11 @@ t = 1000 µs 下一个更新事件 | 稳态 `adc1_gap` | 每 10 s 心跳 +1 点(开机日志突发期集中数十点) | §8:心跳拍超 1 ms + 相位伪影 | | 静态 RAM | `s_stm32_dma` 36 B 在 `RW_IRAM1` | `scripts/ram_report.py`;**加大缓冲前必须重跑 .map 确认仍在 `RW_IRAM1`**(§4.3) | | 任务与栈 | 零新任务;`adcTask` 640 words,静态最坏链约 1.3 KB、余量约 48% | `scripts/stack_report.py`、`docs/内存管理/RAM使用分析与优化方案.md` §2.3 | -| 动态分配 | 无(自研代码禁 C 库堆) | AGENTS.md「平台约束」 | +| 动态分配 | 无(自研代码禁 C 库堆) | `docs/门禁说明/coding-standard.md` §2(`CODE-RULE-20` 本体:MicroLIB 堆仅 512 B) | | ISR 负担 | 1 kHz 一次,两次 GPIO 写 + 一次标志置位 | §7 | **心跳拍的连带效应**:`adc1_gap` 的根治手段是**缩短心跳**(每 10 s 一次的多行日志),不是提高 DMA 能力。 -日志成本模型 → AGENTS.md「日志与工具链」。 +日志成本模型(每条日志约 90 B Flash + 216 B 栈,按调用点计)→ `docs/子系统设计/控制台单写者日志设计.md` §7.1。 --- diff --git a/docs/子系统设计/IEC104上行设计说明.md b/docs/子系统设计/IEC104上行设计说明.md index 2b5e777f..35a38f95 100644 --- a/docs/子系统设计/IEC104上行设计说明.md +++ b/docs/子系统设计/IEC104上行设计说明.md @@ -165,7 +165,7 @@ HW 测试层 0x1F5,含 保护任务 protect 位 bit8);主循环 100ms 节拍喂位,屏障等待按 100ms 分片喂位(timeSyncTask 2026-10-02 台架先例)。 - **就绪屏障**:等 `SYS_EVT_NET_READY`(`osFlagsNoClear` + 分片)后才建监听。 -- **单连接语义**(`AGENTS.md` 模块约定,抄 `ui_net_sink.c` 模板):监听端口(工厂默认 2404)与 +- **单连接语义**(`docs/网络/网络自愈架构设计.md` §4.10,抄 `ui_net_sink.c` 模板):监听端口(工厂默认 2404)与 数据通道复用同一 socket(accept 返回即 listen fd);EOF 时 net 层 auto_relisten, 应用层**不得**关 fd(`client == listen` 分支);仅模拟器多连接后端(fd 不同)显式关。 - **门控 + 兜底**:`net_listener_armed`/`net_can_read`(纯 RAM 读)省无谓 RPC 往返 diff --git a/docs/子系统设计/控制台单写者日志设计.md b/docs/子系统设计/控制台单写者日志设计.md index 34115e88..4a3dedfc 100644 --- a/docs/子系统设计/控制台单写者日志设计.md +++ b/docs/子系统设计/控制台单写者日志设计.md @@ -3,7 +3,7 @@ > **模块**:`App/log/console_log.{h,c}`(引擎)+ `App/log/dbg_log.h`(`DBG_*` 宏与行缓冲) > **通道**:UART5 / RS232#1(PC12 TX / PD2 RX),115200 8N1,轮询发送 > **写者**:`defaultTask`(全系统唯一) -> **关联**:`运行与自检记录设计.md`(同写者任务的持久化日志)· `项目架构总览.md` · AGENTS.md「平台约束」 +> **关联**:`运行与自检记录设计.md`(同写者任务的持久化日志)· `项目架构总览.md` · `docs/架构设计/项目启动顺序管理.md` ## 1. 设计目标与约束 @@ -21,8 +21,8 @@ | # | 约束 | 出处 | |---|------|------| -| K1 | 内核启动前禁止创建/使用任何 FreeRTOS/CMSIS-RTOS 对象 | AGENTS.md 平台约束 → 本模块内核前纯 BSS/寄存器机制 | -| K2 | 禁止 `malloc/calloc/realloc`(C 堆仅 512B) | AGENTS.md 平台约束(禁 C 库堆分配条)→ 全部状态静态 BSS | +| K1 | 内核启动前禁止创建/使用任何 FreeRTOS/CMSIS-RTOS 对象(节拍与对象模型 → `docs/架构设计/项目启动顺序管理.md` §7) | 本模块内核前纯 BSS/寄存器机制 | +| K2 | 禁止 `malloc/calloc/realloc`(C 堆仅 512B;权威口径 → `docs/门禁说明/coding-standard.md` §2 CODE-RULE-20) | 全部状态静态 BSS | | K3 | HAL 生成文件(`Src/`、`Inc/`)不含应用代码 | HAL 生成文件只放 CubeMX 内容 → 实现位于 `App/log/` | | K4 | 生产者阻塞时间有界 | 最多 `DBG_CON_WAIT_MS`(200ms),日志不得阻塞业务 | | K5 | RAM 预算紧张,新增静态内存必须核算 | §7 | @@ -36,7 +36,7 @@ | 生产者 | 全部任务 + 内核前主线程 + ISR | 调用点格式化整行(库 `snprintf`)→ `dbg_console_write_line()` | | 写者 | **defaultTask(唯一)** | 进主循环前 `dbg_console_writer_attach()` 注册为唯一发送者;循环内周期 `dbg_console_drain()` | | 物理通道 | **UART5(RS232#1:PC12 TX / PD2 RX,经 U9 隔离 → U13 TPT3232E → CN1;115200 8N1)** | 轮询发送(`HAL_UART_Transmit`);端口以 `CON_UART*` 宏收口在 `console_log.c` | -| 唤醒 | `SYS_EVT_CONSOLE_TX`(`sys_evt` bit 6) | **消费型命令位**(`osFlagsWaitAny` 默认消费,与 AGENTS.md 事件位语义一致;区别于就绪位必须 `osFlagsNoClear`) | +| 唤醒 | `SYS_EVT_CONSOLE_TX`(`sys_evt` bit 6) | **消费型命令位**(`osFlagsWaitAny` 默认消费,与 `docs/架构设计/项目启动顺序管理.md` §2 的事件位语义一致;区别于就绪位必须 `osFlagsNoClear`) | **与其他日志子系统的关系**(同一"单写者纪律",同一属主任务): @@ -258,7 +258,7 @@ sequenceDiagram | 常量 | 值 | 定义处 | 含义 | |------|-----|--------|------| | `DBG_CON_LINE_MAX` | 192 | `console_log.h` | 单行文本上限(含结尾 `'\0'`);环形缓冲/入环截断上限;超限截断 | -| `DBG_LINE_BUF_MAX` | = `DBG_CON_LINE_MAX`(深链模块设 **128**) | `dbg_log.h` | **调用点栈上行缓冲尺寸**。已收紧:`nand_ftl`/`gd5f2gq5ue`/`cfg_file`/`net_cfg`/`net_socket`/`ch395f`/`time_sync`/`default_task`。取值须 ≥ 该模块最长日志行,否则该行被截断 | +| `DBG_LINE_BUF_MAX` | = `DBG_CON_LINE_MAX`(深链模块设 **128**) | `dbg_log.h` | **调用点栈上行缓冲尺寸**。已收紧 **12 个翻译单元**,完整清单与增补规则见 §7.1——**新增深链模块时必须同步那份清单**。取值须 ≥ 该模块最长日志行,否则该行被截断 | | `DBG_TS_BUF_MAX` | 24 | `dbg_log.h` | 时间戳文本缓冲(`sys_clock_get_str` 恒写 19 字符 + `'\0'`);与行缓冲**共用一个数组** | | `DBG_CON_RING_SIZE` | 4096 | `console_log.c` | 环形缓冲字节数(必须为 2 的幂) | | `DBG_CON_CHUNK_MAX` | 256 | `console_log.c` | 写者单次发送上限 = 裸发上限 | @@ -289,10 +289,45 @@ sequenceDiagram | `s_con_head/tail/drop/writer_up/writer_task` | ≈14 B | BSS | | 生产者行缓冲 `__con_line`(`DBG_EMIT` 宏局部) | 默认 192 B + 时间戳 24 B;**深链模块 128 + 24 B**/调用 | 调用者任务栈(入环后即释放,峰值非累积) | -**结论:静态 +4.1KB(SRAM1);FreeRTOS 堆零增量、无新任务/栈、无新内核对象。** `heap free=8776B, min_ever=4816B`(CCM 堆不受影响);`__con_line` 192B 峰值在各任务既有栈预算内(任务栈按实测峰值 ×1.5 + 1KB ISR 余量定档,见 AGENTS.md 任务栈表)。 +**结论:静态 +4.1KB(SRAM1);FreeRTOS 堆零增量、无新任务/栈、无新内核对象。** `heap free=8776B, min_ever=4816B`(CCM 堆不受影响);`__con_line` 192B 峰值在各任务既有栈预算内(任务栈按实测峰值 ×1.5 + 1KB ISR 余量定档,栈表见 `Src/freertos.c`)。 > ⚠️ **行缓冲是静态栈链的第一大项**:行缓冲是**每个日志调用点**在栈上内联的一份数组,会进 armlink 最坏调用链。defaultTask 那条最深链上 **9 个帧各含一份**(192 + 32 B)→ **约 1.5 KB 纯粹是日志行缓冲**。对策 = `dbg_log.h` 的 `DBG_LINE_BUF_MAX`(深链模块收到 128)+ 时间戳缓冲并入行缓冲(32 → 24),该链 5312 → 2776 B。核算见 `docs/内存管理/RAM使用分析与优化方案.md`。 +### 7.1 日志调用点的成本(新建日志前必读,本节是权威口径) + +日志不是免费的,成本按**调用点**计、不按行计——同一行日志写到 N 处调用,成本就是 N 份: + +- **Flash**:每条约 **90 B**(格式串 + 常量 + 调用序列)。 +- **栈**:每条约 **216 B**(`__con_line` 行缓冲 + 时间戳缓冲 + 调用帧)。这条**直接进 armlink 静态最坏调用链**,是任务栈定档时必须算进去的一项。 +- **深调用链模块**:必须在该模块的 `dbg_log.h` 引入处 `#define DBG_LINE_BUF_MAX`(取值 ≥ 该模块最长日志行,现值 128),否则默认 192 B 会整份进链——defaultTask 9 帧同链时仅此一项就是约 1.5 KB。 + + 当前已收紧的**全部 12 个翻译单元**(2026-11-16 逐一核对,权威判据见本节末「怎么核对」): + + | 模块 | 位置 | + |---|---| + | main | `Src/main.c` | + | net_cfg | `Drivers/BSP/NETCFG/net_cfg.c` | + | net_events | `Drivers/BSP/NET/net_events.c` | + | net_socket | `Drivers/BSP/NET/net_socket.c` | + | gd5f2gq5ue | `Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue.c` | + | nand_ftl | `Drivers/BSP/GD5F2GQ5UE/nand_ftl.c` | + | ch395f | `Drivers/BSP/CH395F/ch395f.c` | + | default_task | `App/task/default_task.c` | + | iec104_serv | `App/task/iec104_serv.c` | + | protect_task | `App/task/protect_task.c` | + | time_sntp | `App/sync/time_sntp.c` | + | cfg_file | `App/cfg/cfg_file.c` | + + **怎么核对(权威判据,不要靠这份表自查)**:`DBG_LINE_BUF_MAX` 的定义是散落在各模块引入处的宏,**唯一事实源是代码本身**: + + ``` + grep -rn "define DBG_LINE_BUF_MAX" --include=*.c --include=*.h . + ``` + + 命中行数 − 1(`Drivers/BSP/dbg_log.h` 的默认定义)= 已收紧的翻译单元数(当前 **13**)。**新增或移除一处收紧,请同步更新上面这张表**;两者不一致时**以 grep 结果为准**,并修表。 + +推论(判据,不另立文档):**只在真正静默的黑洞处补锚点**,不要加"进入前/完成后"这类重复锚点;新增日志前先按上面的模型估一遍栈增量,再对照 `docs/内存管理/RAM使用分析与优化方案.md` §2.3 的任务栈余量。栈与 Flash 的实测口径 → `scripts/stack_report.py`、`scripts/ram_report.py`。 + ## 8. 设计决策与否决的替代方案 | # | 替代方案 | 否决 / 采纳理由 | diff --git a/docs/子系统设计/故障录波设计说明.md b/docs/子系统设计/故障录波设计说明.md index ce7d698e..5d970b64 100644 --- a/docs/子系统设计/故障录波设计说明.md +++ b/docs/子系统设计/故障录波设计说明.md @@ -314,7 +314,7 @@ flowchart TD - `err` 是落盘失败或 CRC 自弃次数(**字节数不符就算失败**,见 §5.2);`ovf` 是冷却期丢弃的触发数;`drop` 是冻结窗口丢掉的录波点数; - **实际落地形态(逐字)**:打印点在 `App/task/adc_task.c`:782 行,格式串 `"wave: seg=%lu armed=%u src=%s pts=%u err=%lu ovf=%lu drop=%lu"`——**字段名与顺序就是上面的模板**(台架与 PC 脚本按行名 grep,动它就断脚本);`src` 取 M(手动)/ P(保护)/ T(定时自抓)/ `-`(本次上电还没触发过);`armed` 只在 FREEZE 与 SEALED 为 1(COOL 期只挡新触发不录新段,画进 armed 会被台架误读);`seg` 是累计**成功回执**的段数、不是轮转号;`err` = 落盘失败 + SEALED 滞留超时自弃(含 §5.2 第四条的 ring abandoned 判废),由环内计数收口,落盘道不数第二份账。`err` 与 `ovf` 的**已知容差**(lead 裁定 2026-10-29,不修只入档):这两个计数是跨上下文的读-改-自增(`ovf` 由任意上下文的拒绝路径加、`err` 由 adcTask 的滞留自弃与 defaultTask 的落盘失败分别加),本层双端编译、不许引 FreeRTOS / CMSIS 的临界区内在函数,所以并发拒绝或并发失败时**理论上可能少计一次**。定性为**观测计数的已知容差**:只用于趋势与判读,**不作为任何判据的唯一依据**——要坐实「冷却期内确实来了第二次触发」,同时看 `armed` 与那一刻 `/log/start.log` 的时刻。契约原文见 `App/algo/wave_ring.h` 文件头「观测计数的已知容差」段; - **落盘道失败留痕名清单(2026-10-30 并入原卡片登记簿;台架判读按名索引,不新增第二种形态)**:单板上一律一行 `[WAVE] seg drop: <原因> (idx=… written=…)`,统一打印点 `App/task/default_task.c`:843——`crc selftest FAIL` / `mkdir /wave` / `opendir /wave` / `readdir /wave` / `seg_path` / `pack_start` / `f_open` / `pack_next` / `f_write short` / `pack stall` / `f_close` / `len mismatch` / **`ring abandoned`**(最后一条即 §5.2 第四条陷阱的处置留痕,2026-11-07 板级已闭环,留痕原文与三判据实证见 §10「bench 定时自抓与占卷弃段观察闭环记录」);另有一条非失败的慢段留痕 `[WAVE][WARN] seg held <毫秒> ms (idx=…)`(`App/task/default_task.c`:858)——搬得慢不是错,真失败才走 `seg drop`。 -- 只在原先静默的黑洞处补锚点,别重复已有步骤——每条 DBG 日志约 90 B Flash 加 216 B 栈(`AGENTS.md` 的日志与工具链节); +- 只在原先静默的黑洞处补锚点,别重复已有步骤——每条 DBG 日志约 90 B Flash 加 216 B 栈(成本模型与深链 `DBG_LINE_BUF_MAX` 口径 → `docs/子系统设计/控制台单写者日志设计.md` §7.1); - 该行已同步进 `docs/测试说明/专项验证/ADC前端注入验证流程.md` 的读数地点表(2026-10-29;同一张表还登记了录波段文件与 PC 侧读段工具)。 --- diff --git a/docs/子系统设计/看门狗设计说明.md b/docs/子系统设计/看门狗设计说明.md index 527b5b71..14bdcec3 100644 --- a/docs/子系统设计/看门狗设计说明.md +++ b/docs/子系统设计/看门狗设计说明.md @@ -248,7 +248,7 @@ static HAL_StatusTypeDef iwdg_deferred_start(const IWDG_HandleTypeDef *a_h) { (v **2026-10-10 栈整改**:钩子里的 `name[49]`/`num[16]` 改**函数级 static**(终点路径、打印完即复位、无并发),行号转换改原地反转,去掉 `HAL_Delay(200)`(`con_tx_bounded` 已等 TC)。原因:`configASSERT` 在 FreeRTOS 内部可达 → 本钩子挂在**每个任务**的最坏调用链尾,放栈上的 81 B 会出现在所有任务的静态最坏链上。 -4 个 Fault(Hard/Mem/Bus/Usage)的采集与使能(`fault_handler_enable()` 使能后三者,否则被升级成 HardFault 看不出根因)见 §10.2 与 `AGENTS.md`「平台约束」。 +4 个 Fault(Hard/Mem/Bus/Usage)的采集与使能(`fault_handler_enable()` 使能后三者,否则被升级成 HardFault 看不出根因)见 §10.2 与 `docs/架构设计/项目启动顺序管理.md` §7(内核前编码约束)。 **`Error_Handler()` 统一降级(2026-10-12)**:CubeMX 弱定义的这个入口旧形态是 `__disable_irq(); while(1){}`——**单处外设初始化失败即整机挂死**,只剩 IWDG 兜底且不留任何自检日志。现改为打 1 条自检 + `NVIC_SystemReset()`,与 4 个 Fault 处理同款自恢复(IWDG 退回"最后兜底"而非唯一出路;复位归因 `SFTRSTF` → 开机日志 `software (NVIC_SystemReset)`,§4.5)。三条实现约束: @@ -256,9 +256,9 @@ static HAL_StatusTypeDef iwdg_deferred_start(const IWDG_HandleTypeDef *a_h) { (v |---|---| | **不得 `__disable_irq()`** | 日志必须能走串口,关中断 = 现场彻底消失 | | **`__builtin_return_address(0)` 不可用** | AC5 前端接受但编成库函数调用,MicroLIB 无该符号 → `L6218E`(2026-10-12 台架实证,勿再尝试);ARMCC `__asm` 只有整函数形态且取不到 C 符号(§10.4)。→ **失败点靠"最后一条成功日志"与 `main()` 的 `MX_*_Init` 顺序之间定位**(GPIO→DMA→USART1→SPI2→SPI1→I2C1→UART4→UART5→USART2→USART3→IWDG→ADC1→TIM3→`app_main_init`) | -| **日志路径必须内核前安全** | 调用点全在 `osKernelStart` 之前:控制台写者未注册 → `con_append` 走 `dbg_console_write_raw`(DWT/计数有界轮询,`huart1` 未就绪即返回),`sys_clock_get_str` 未初始化打占位串——全程无内核 API(§4.7 与 `AGENTS.md`「平台约束」同源) | +| **日志路径必须内核前安全** | 调用点全在 `osKernelStart` 之前:控制台写者未注册 → `con_append` 走 `dbg_console_write_raw`(DWT/计数有界轮询,`huart1` 未就绪即返回),`sys_clock_get_str` 未初始化打占位串——全程无内核 API(§4.7 与 `docs/架构设计/项目启动顺序管理.md` §7 同源) | -成本 = 仅这 1 条日志(≈90 B Flash,见 `AGENTS.md` 日志成本)。重生成存活:函数体在 `USER CODE Error_Handler_Debug` 区(`KeepUserCode` 逐字保留)+ `check_cubemx_survival.py` 审计兜底。 +成本 = 仅这 1 条日志(≈90 B Flash + 216 B 栈,见 `docs/子系统设计/控制台单写者日志设计.md` §7.1)。重生成存活:函数体在 `USER CODE Error_Handler_Debug` 区(`KeepUserCode` 逐字保留)+ `check_cubemx_survival.py` 审计兜底。 ### 4.5 复位原因锁存与优先级 @@ -491,7 +491,7 @@ snapshot == required → miss_streak=0、证据门闩复位、喂狗 ## 10. CubeMX 重生成下的定制存活(方法论) -看门狗是本项目**第一次**把 CubeMX 生成流程引入可靠性关键路径,由此沉淀出与看门狗本身无关的通用方法论。`AGENTS.md`「平台约束」指向本节,改动 `.ioc`/`Src/`/`Inc/` 前请先读。 +看门狗是本项目**第一次**把 CubeMX 生成流程引入可靠性关键路径,由此沉淀出与看门狗本身无关的通用方法论。本节是该流程的权威落点,改动 `.ioc`/`Src/`/`Inc/` 前请先读。 > **2026-10-26(道G task-26)一句话登记,机制不在本文复述**:四个 Fault 与栈溢出 / 断言钩子的**崩溃上报发送口已归一**进控制台单写者(`dbg_console_write_raw` + 一次整行独占,不再自行调用 `HAL_UART_Transmit`),机制正文与残余见 `docs/子系统设计/控制台单写者日志设计.md` §3.4.1。本节只关心一件事:这些实现仍须整体待在 `Src/freertos.c` 的 `USER CODE BEGIN 4/5` 区与 `Src/stm32f4xx_it.c` 的 `USER CODE BEGIN 0` 区(§10.2 的「搬进 USER CODE 区」条),改完跑 `scripts/check_cubemx_survival.py`(§10.3)。同族另一笔只登记指针:断言钩子与临界区在控制台路径上互达会构成**幻影环**,armlink 的 `In Cycle` 记账随环形状波动(同一 port.o 三棵树实测每链差 0~80 B,休眠≠解耦),三树取证、量化表与「configASSERT 裁空宏 ≠ 优化收益」的钉死句见 `docs/内存管理/RAM使用分析与优化方案.md` §4.0.7(道G task-38)。 @@ -541,7 +541,7 @@ python scripts/check_cubemx_survival.py --write # 确认改动无误后重建 ### 10.4 ARMCC `__asm` 的三条语法约束(2026-09-29 踩坑) -> **出处**:自 `AGENTS.md`「ARMCC 内联汇编语法」条目迁入(AGENTS.md 瘦身,不再当事实存放地)。4 个 Fault Handler 是手工 `__asm`(§10.2 的「搬进 USER CODE 区」条);ARMCC 的内联汇编只有一种合法形态,以下三种写法全部实测踩坑: +> **出处**:本节是「ARMCC `__asm` 语法约束」的唯一事实源(2026-10-11 由入口文件迁入)。4 个 Fault Handler 是手工 `__asm`(§10.2 的「搬进 USER CODE 区」条);ARMCC 的内联汇编只有一种合法形态,以下三种写法全部实测踩坑: | # | 尝试写法 | ARMCC 实际报错 | 根因 | |---|---|---|---| diff --git a/docs/文档规范.md b/docs/文档规范.md index 0bde3269..70e83afa 100644 --- a/docs/文档规范.md +++ b/docs/文档规范.md @@ -58,8 +58,9 @@ | 文件尾 | 必须以单个换行结束(`end-of-file-fixer`) | | 乱码 | 禁止出现 `U+FFFD`(替换字符,字节序列 `EF BF BD`) | | 长中文正文与跨语言字面量 | 经 run_code 等程序化工具改写本文时,程序体内定界符只用一种 ASCII 引号;正文里的中文引号用全角「」,反引号字符用码位现取后再拼,不把反引号或 shell 变量形态写进字面量。落点选唯一锚点并断言命中数为 1,全部替换在内存串上跑完才一次性写回;落盘后打印 bom、crlf、乱码字节数与占位残留,并回读目标行确认已是新文本 | +| **C 源码 BOM 名单**(本行是**唯一事实源**,钩子与门禁脚本必须与本行对齐) | `Drivers/BSP/UI/`(整目录)、`App/task/ui_task.c`、`App/cfg/cfg_file.c`、`Lib/lv_conf.h` 为 **UTF-8 带 BOM**。三处互指:本行、`.pre-commit-config.yaml` 的 `bom-guard` 钩子 `files` 正则、`scripts/check_bom_drift.py` 的 `BOM_LIST`——改名单必须三处同笔改,`check_bom_drift.py` 会当场对不上并拦截 | -> ⚠️ **本仓库 BOM 铁律**(见 `AGENTS.md`「铁律:源码编辑与编码」):C 源码中 `Drivers/BSP/UI/*`、`App/task/ui_task.c`、`App/cfg/cfg_file.c`、`Lib/lv_conf.h` 等**带 BOM**,被工具改写后 BOM 会静默丢失 → ARMCC 改按 CP936 解码 → 中文字面量编译失败。 +> ⚠️ **为什么 C 源码带 BOM 不能丢**:名单内文件被工具改写后 BOM 会静默丢失 → ARMCC 改按 CP936 解码 → 中文字面量编译失败。故改这些文件**只用 Edit 工具**,改完核对 BOM 仍在(`bom-guard` 钩子自动拦截)。 > **文档(`.md`)不受此限**,一律用无 BOM UTF-8。 > > **行尾策略(2026-10-09 起写死进 `.gitattributes`,本节是权威口径)**:`* text=auto eol=lf`(仓库 blob 与工作区统一 LF)+ `*.bat`/`*.cmd` 强制 CRLF(cmd.exe 对 LF-only 的 goto/标签不可靠)+ PNG/TTF/DLL/LIB 等显式 `binary` + `*.jpg` 走 LFS 且 `-text`(该条必须排在 `*` 之后才能覆盖)。**不要再依赖 `core.autocrlf`,也不要把工作区文件"改回 CRLF"**——CubeMX 重生成写的就是 LF;此前每次重生成后 40+ 个第三方文件在 `git status` 里显示"已修改",根因就是行尾由每台机器各自的 autocrlf 决定。用脚本批量改写文档时仍须**按原样回写换行符**,否则会产生整文件行尾漂移的巨型 diff。 @@ -389,7 +390,7 @@ | 内容 | 归属 | |---|---| -| 项目级铁律、构建/烧录/测试命令、平台约束 | `AGENTS.md`(AI 协作上下文,**精简优先**) | +| 项目级铁律、构建/烧录/测试命令、平台约束 | `AGENTS.md`(AI 协作上下文,**精简优先**)。注意:`AGENTS.md` 只作**入口索引**,事实的归属按本表其余各行——每类事实都有自己的专科文档,见 §6 其余行 | | 开发者入门、架构速览、目录导航 | `README.md` | | 详细设计、专项说明、测试指南 | `docs/` 下对应子目录 | | 跨文档待办登记 | 各模块文档的「已知限制/重开条件」节(顺序归 `docs/任务规划/README.md`) | diff --git a/docs/架构设计/图形绘制流程.md b/docs/架构设计/图形绘制流程.md index 534fb37b..f404f0f8 100644 --- a/docs/架构设计/图形绘制流程.md +++ b/docs/架构设计/图形绘制流程.md @@ -144,7 +144,7 @@ sequenceDiagram > **别照旧写法装 `cairosvg`**:`.venv` 里没装(`ModuleNotFoundError`)、`requirements.txt` 里也没有, > `rsvg-convert` / `inkscape` / `magick` 这台机器上都不存在(2026-10-30 实测)。真要引入是**动 > `requirements.txt` 的决定**(第三方依赖统一进那里;另注意门禁 entry 的裸 `python` 不等于 `.venv` → -> AGENTS.md「Python 环境」),不是画图这一步的隐含前置。零工具兜底仍是「浏览器双击打开 `.svg` 用眼看」, +> `new-machine-setup` skill),不是画图这一步的隐含前置。零工具兜底仍是「浏览器双击打开 `.svg` 用眼看」, > 但半格压框这类问题靠眼看不出来。 > PNG 属**本地派生物、不入库**:忽略规则是 `.gitignore` 里针对目录的三条——`docs/images/*.png`(:132)、 diff --git a/docs/架构设计/引用关系图说明.md b/docs/架构设计/引用关系图说明.md index 39f0fe32..eb8a155a 100644 --- a/docs/架构设计/引用关系图说明.md +++ b/docs/架构设计/引用关系图说明.md @@ -83,7 +83,7 @@ - 双端(Keil MCU / CMake 模拟器)包含路径合并解析,个别引用是"另一端视角" (如 LVGL 的 SDL2 后端引用),属项目级引用面的如实呈现。 - 第一方/第三方划分规则见脚本头部 `classify()`;lftpd 为移植的第三方组件 - (与 AGENTS.md pre-commit 排除名单一致)。 + (与 `.pre-commit-config.yaml` 的 `exclude` 排除名单一致)。 ## 6. 维护 diff --git a/docs/架构设计/项目启动顺序管理.md b/docs/架构设计/项目启动顺序管理.md index 0348b2b4..7c1d9975 100644 --- a/docs/架构设计/项目启动顺序管理.md +++ b/docs/架构设计/项目启动顺序管理.md @@ -240,17 +240,17 @@ if (sys_evtHandle != NULL) { | 11 | `freq layer init: OK` | `freq_init()` | 纯 RAM(不会卡) | | 12 | `protection init: OK (set=N elm=N)` | `prot_set_init()` + `prot_elm_init()` | 纯 RAM(不会卡) | | 13 | `SD2506 ID/time/temp/battery` 共 5 行 | SD2506 诊断 | I2C1(同第 4 步);缺行 = 诊断段卡死 | - | 14 | `App init OK` | 全部完成(其后启动 TIM3 1kHz 采样节拍 `HAL_TIM_Base_Start_IT(&htim3)`,见 AGENTS.md 铁律) | 此后问题属任务/调度层,不再是启动段 | + | 14 | `App init OK` | 全部完成(其后启动 TIM3 1kHz 采样节拍 `HAL_TIM_Base_Start_IT(&htim3)`,见 `App/app/app_main.c`) | 此后问题属任务/调度层,不再是启动段 | - **若一行日志都没有**:问题在 `fault_handler_enable()` 之前(`HAL_Init` / 时钟树 / `system_stm32f4xx.c`),或 USART1 本身未初始化(`MX_USART1_UART_Init` 在 `main.c` 的 CubeMX 初始化段)。 - **若卡在某步且无该步结果日志**:看该步**内部**是否还有更细的日志(如 `sd2506_init` 的 `ID read FAIL` / `charge reg read FAIL` 区分了 I2C 失败与寄存器校验失败)。 - - **配套手段**:`sd2506_init` / `gd5f2gq5ue_init` 内部的失败日志已细化到错误码;`sys_clock_init` 的降级路径写 syslog 自检(`clock chip fault`)。**注意日志本身有成本**——`DBG_*` 单条约 90 B Flash + 192 B 栈(见根目录 `AGENTS.md`),故只补真正静默的黑洞,不加冗余的"进入前/完成后"重复锚点。 + - **配套手段**:`sd2506_init` / `gd5f2gq5ue_init` 内部的失败日志已细化到错误码;`sys_clock_init` 的降级路径写 syslog 自检(`clock chip fault`)。**注意日志本身有成本**——`DBG_*` 单条约 90 B Flash + 216 B 栈(成本模型与出处 → `docs/子系统设计/控制台单写者日志设计.md` §7.1),故只补真正静默的黑洞,不加冗余的"进入前/完成后"重复锚点。 --- ## 7. 内核启动前(`osKernelStart` 之前)的编码模式 -> 本节是根目录 `AGENTS.md`「平台约束」中这条铁律的完整细节迁入处(2026-10-11,AGENTS.md 瘦身,不再当事实存放地)。 +> 本节是「`osKernelStart` 之前禁止任何 RTOS 创建类 API」这条铁律的**完整细节归属处**(2026-10-11 迁入;AGENTS.md 只留一行禁令)。 **禁令:`osKernelStart` 之前禁止调用任何 FreeRTOS / CMSIS-RTOS 创建类 API**——`osMessageQueueNew` / `osMessageQueuePut` / `osMutexNew` / `osSemaphoreNew` 等在内核启动前调用会**直接杀死启动**。 diff --git a/docs/架构设计/项目架构总览.md b/docs/架构设计/项目架构总览.md index 592980fa..c600ffac 100644 --- a/docs/架构设计/项目架构总览.md +++ b/docs/架构设计/项目架构总览.md @@ -2,7 +2,7 @@ > 版本:v1.3 日期:2026-10-30 > 平台:STM32F407ZGTx @168MHz(HSE 8MHz → PLL M=4/N=168/P=2)+ FreeRTOS V10.3.1(CMSIS-RTOS2) -> 用途:一页看清项目的分层、任务、数据流与目录组织。现状能力与功能缺口的权威口径在 AGENTS.md「项目概况」,细节以各模块专项文档为准(见 §9)。 +> 用途:一页看清项目的分层、任务、数据流与目录组织。现状能力与功能缺口的权威口径在本节与 §2(`docs/产品需求/产品需求设计文档.md` §2.1),细节以各模块专项文档为准(见 §9)。 --- @@ -54,7 +54,7 @@ > 上图由 `tools/arch_diagram/gen_arch_endtoend_svg.py` 生成(42 框 / 37 边 / 5 条纵带,线型三类:实线 = 数据与读写、短虚线 = 命令·请求·配置、紫点线 = 屏障位·心跳·同源镜像)。 > **与 §1 分层图的分工**:§1 回答「谁属于哪一层、层间单向依赖」,本图回答「一条数据从引脚走到 104 报文 / 显存 / 记录文件要穿过哪些框、谁在什么时候被谁唤醒」。图里的五条纵带只是**列分组**(便于对齐),不是依赖声明——依赖方向仍以 §1.1 表与 `layer-deps` 门禁为准。 -> 影响链路走向的两条行为条件已画进图内(RS-485 未接线 → 暂缓接语义取数层;跨任务握手集中经 `就绪屏障`);其余行为条件(未标定闭锁、`osFlagsNoClear`、CH395F 单连接、V0.1 双转换器无共同采样触发)不在图上重复,见 AGENTS.md「项目概况 / 平台约束」与 §2.2、§5。 +> 影响链路走向的两条行为条件已画进图内(RS-485 未接线 → 暂缓接语义取数层;跨任务握手集中经 `就绪屏障`);其余行为条件(未标定闭锁、`osFlagsNoClear`、CH395F 单连接、V0.1 双转换器无共同采样触发)不在图上重复,见 `docs/产品需求/产品需求设计文档.md` §2.1 与本文 §2.2、§5。 > `*` `rs485_task.c` 任务体已实现,但**当前未在 `freertos.c` 创建**(RS-485 采集链路暂缓,见 `docs/产品需求/产品需求设计文档.md` §5.10);`adc_task.c` 已于 2026-10-10 接入创建(`adcTask`)。 > 串口三分(2026-10-29 屏板批 0 后的定态):**USART1 = 屏板链路 700 kbaud**、**UART4 = RS-485(115200,未接线)**、**UART5 = 控制台日志 115200**——日志口原在 USART1,屏板占用后迁至 UART5(RS232#1 台架线改接日志口)。 diff --git a/docs/测试说明/专项验证/ADC前端注入验证流程.md b/docs/测试说明/专项验证/ADC前端注入验证流程.md index 41274007..57797c2e 100644 --- a/docs/测试说明/专项验证/ADC前端注入验证流程.md +++ b/docs/测试说明/专项验证/ADC前端注入验证流程.md @@ -219,11 +219,11 @@ TPAFE 双极性补码可注负压;STM32 单极性负半周测不了。UA/UN/IA | 信号发生器 | 正弦 / 方波 / 三角,**并有 DC 档**;频率可锁 50.000 Hz、也能设 2 Hz;幅度 0~3 Vpp | 只要求"波形干净、幅度稳、频率锁得住",刻度不当基准(`docs/算法/采集与算法层设计说明.md §13.12` #9)。DC 档给削顶轮的直流削顶档 | | ⚠ 发生器端接 | 接板子时设**高阻负载**,不按 50 Ω 端接 | 50 Ω 端接而实际高阻 → 面板值与真实电压差 2 倍;台架"差一倍"最常见来源 | | 万用表 AC 档 | 能读 mV;**记明型号与响应类型**(真有效值 / 均值)——判别法:表身或说明书没印 "True RMS" 就当均值档;拿发生器注一个 Vpp 2.828 V 方波到 AC 档,读数 ≈1.41 V = 真有效值档、≈1.57 V = 均值档(差 11 %,一眼分辨) | 基准就是它;波形轮两种表读数都与基波期望差很多,不记响应类型说不清谁错 | -| 板子 | 产品构建(`test/board/test_config.h` 四 `TEST_SUITE_*` 全注释)+ `/keil-build` 0 错 0 警 + 烧录 `-Rst -Run` + 回读校验 | → `stlink-flash` skill 与 AGENTS.md「构建与验证」 | +| 板子 | 产品构建(`test/board/test_config.h` 四 `TEST_SUITE_*` 全注释)+ `/keil-build` 0 错 0 警 + 烧录 `-Rst -Run` + 回读校验 | → `keil-build` / `stlink-flash` skill | | `[adc_cal]` 状态 | **保持未标定**(`eng=0`),别为"读数好看"先写标定值 | 现在 `meas:` / `phasor` 量纲是 **ADC 引脚电压 V**——未标定态的设计本来就不折算(`App/algo/meas.h`);标定一生效换二次值,本节全部期望值作废 | | 串口 | 全程抓 RX 落盘:`serial-assistant` skill(`open` → `clear` → 跑 → 读日志 / `log --tail`) | 日志文件就是证据本体;**长跑别用 `/serial-boot-test`**——它绑一轮启动语义(静默 8 s、总超时 30 s、forbidden 含 `[ERR]`,削顶轮故意造 `[ERR]`),必超时或误判;daemon 写 `state/serial.log`(20 MB 截头保尾 10 MB,长跑防截断 → `docs/测试说明/流程与规范/自动化测试流程.md` 长时间采集) | | FTP 客户端 | 走 21 端口取段文件(出厂 `[ftp]` 账号,连续 5 次失败锁 60 s) | 相位 / 谐波的定量判据只能拿段文件来算;`/wave/WAVE.BIN`(00~99 轮转),**取回本机后立刻改名归档**,否则下次触发盖掉 | -| 录波触发路径 | 产品构建唯一**免改代码**路径 = UI 菜单第 26 叶「手动录波」确认页(`Drivers/BSP/UI/ui_page_wave_manual.c` → `App/task/ui_task.c:605`) | 保护启动上升沿也算触发,但保护判据现处**未标定闭锁**(AGENTS.md「现状」),别指望自动来段;bench 自抓在 `DTU_BENCH` 且 `WAVE_BENCH_AUTOCAP` 非 0(默认 0,`App/task/adc_task.c:153`),开它属临时措施,跑完撤销重编 | +| 录波触发路径 | 产品构建唯一**免改代码**路径 = UI 菜单第 26 叶「手动录波」确认页(`Drivers/BSP/UI/ui_page_wave_manual.c` → `App/task/ui_task.c:605`) | 保护启动上升沿也算触发,但保护判据现处**未标定闭锁**(`docs/产品需求/产品需求设计文档.md` §2.1 与 `docs/硬件平台/ADC通道映射说明.md` §7.5),别指望自动来段;bench 自抓在 `DTU_BENCH` 且 `WAVE_BENCH_AUTOCAP` 非 0(默认 0,`App/task/adc_task.c:153`),开它属临时措施,跑完撤销重编 | | 共地 | 发生器 LO/GND 与板 AGND **单点**相连 | 不共地量到的是两地之差,读数带与幅值无关的偏移或漂移 | **开机前置门**——插上网线、开了串口采集、**还没接发生器**之前,串口日志就该通过下面 8 条;任何一条不过,先回 §5.5 处理,别带着脏链往下跑: diff --git a/docs/测试说明/专项验证/模拟器差距清单.md b/docs/测试说明/专项验证/模拟器差距清单.md index a330a485..b6d23741 100644 --- a/docs/测试说明/专项验证/模拟器差距清单.md +++ b/docs/测试说明/专项验证/模拟器差距清单.md @@ -57,7 +57,7 @@ | **「清除记录」两端时序不同** | `syslog_request_clear()` 在调用内**同步**删除宿主文件(`sim_syslog.c` 单线程,没有卷锁、没有队列),返回后状态立刻是 `OK`/`FAIL`,`SYSLOG_CLEAR_WAIT` 永不出现 | 非写者上下文只置标志,真正的 `f_unlink` 排在 defaultTask 的 `syslog_drain()` 尾部(卷锁 try:拿不到锁就顺延,见 `App/log/sys_log_mcu.c`) | 「按了按钮 → 下一拍才见结果」这条异步链、卷占用顺延、以及删除与写者重建的交错,在模拟器上**结构上不存在**;UI 页面若把 WAIT 当失败,模拟器上看不出来 | 主机单测 `test/host/sys_log_mcu/`(TC-SYSLOG-110..122:请求侧零盘触点 / 落地只在 drain / 卷占用顺延 / 幂等 / 不误删;TC-SYSLOG-133/133b:清除成功投一条操作记录、清 oper 自己时不投)+ 台架装置维护页目检 | | **两条投递口在宿主端合一** | `syslog_post_quiet()` = `syslog_post()` 的别名(直写宿主文件,没有队列/待发数组),`syslog_post_dropped()` **恒返 0** | 两个口分开且判据不同:quiet 的调用链上不许内联日志行缓冲(protectTask / iec104Task 的静态最坏链硬线),丢弃只累加计数、由 defaultTask 在 `syslog_drain()` 里按差值补留痕 | 五类记录(事故 / 告警 / 启动 / 操作 / 遥控)在模拟器上**永不丢弃**,"队列满丢记录"、"丢了几条"、"投递侧不许打日志"这三件事在模拟器上结构上不可见;UI 若把"投了"当成"落盘了",模拟器看不出来 | 主机单测 `test/host/sys_log_mcu/`(TC-SYSLOG-132 / 134 / 135:队列侧与启动前数组侧各自的计数与零留痕)+ `scripts/stack_report.py` 静态最坏链(真机侧唯一手段) | | **宿主 cwd 的记录文件互相污染** | 七类记录在模拟器落**当前工作目录**的 `sim_.log`(如 `sim_oper.log`);`sim_post_oper()` 在时钟保存 / 网口保存 / 定值保存等**动作页**用例里真投记录 | 每条记录进 `/log/` 下各自 8.3 短名文件,跨页不互相影响(同一进程内不同页读的是同一份 NAND 文件,本来就该看见彼此写入的记录) | 回归若在**同一个 tmp 目录**跑全部页,前面动作页写的 3 条操作留痕会让「操作记录」页拍不到空态 → 空态判据被环境污染掩盖(真机上没有这个问题:写者只有 defaultTask 与事件边沿) | `simulator/tests/check_content_pages.py` 的 `FRESH_CWD` 表:记录 5 页各在独立空目录里跑(其余 55 页环境不变);手工跑 `lvgl_sim.exe` 前先确认当前目录没有 `sim_*.log`/`sim_config.ini` 残留 | -| **堆后端不同** | `cfg_store_alloc` = 宿主 `malloc`(堆余量以 MB 计) | FreeRTOS 堆(`configTOTAL_HEAP_SIZE` 48 KB,实测最低水位 ~4.8 KB) | **分配失败路径在模拟器上永不触发**——"KB 级分配必然返回 NULL"这类缺陷模拟器照不出来(`AGENTS.md` 已列为铁律) | 内存预算门禁 + 真机 `[HEAP]` 水位告警(S11) | +| **堆后端不同** | `cfg_store_alloc` = 宿主 `malloc`(堆余量以 MB 计) | FreeRTOS 堆(`configTOTAL_HEAP_SIZE` 48 KB,实测最低水位 ~4.8 KB) | **分配失败路径在模拟器上永不触发**——"KB 级分配必然返回 NULL"这类缺陷模拟器照不出来(禁 C 库堆的硬口径 → `docs/门禁说明/coding-standard.md` §2 CODE-RULE-20) | 内存预算门禁 + 真机 `[HEAP]` 水位告警(S11) | ### 2.3 硬件专属(模拟器完全无对应) diff --git a/docs/测试说明/专项验证/链路延迟测试说明.md b/docs/测试说明/专项验证/链路延迟测试说明.md index 4aff0547..1d324a30 100644 --- a/docs/测试说明/专项验证/链路延迟测试说明.md +++ b/docs/测试说明/专项验证/链路延迟测试说明.md @@ -727,7 +727,7 @@ sock4 auto-relisten ok / relisten retry ok ← 监听器随后自行恢复 --- -## 11. 约束核对(AGENTS.md) +## 11. 约束核对(编码 / 构建 / 堆三条硬约束的对应落点) - 每个测试阶段/修复 `/keil-build`(0 错 0 警)+ `/serial-boot-test` 硬件闭环; - 新 `.c` 注册:`test/*.c` 仅 MCU 端编译 → **只注册 `MDK-ARM/STM32F407-Demo.uvprojx`**(Test 组; diff --git a/docs/测试说明/单元测试/ADC输入层单元测试说明.md b/docs/测试说明/单元测试/ADC输入层单元测试说明.md index bf609eaf..95132fae 100644 --- a/docs/测试说明/单元测试/ADC输入层单元测试说明.md +++ b/docs/测试说明/单元测试/ADC输入层单元测试说明.md @@ -7,7 +7,7 @@ > **状态**:✅ 已落地(**103** 用例,`/W4` 0 告警,已挂 pre-commit 钩子) > **日期**:2026-10-10 > **关联文档**: -> [`../../../AGENTS.md`](../../../AGENTS.md)(平台约束 · CubeMX 生成区铁律)、 +> [`../../../docs/文档规范.md`](../../../docs/文档规范.md) §2(C 源码 BOM 名单与编码铁律)、 > [`测试开发标准流程.md`](../流程与规范/测试开发标准流程.md)(测试分层与门禁总览)、 > [`配置文件单元测试说明.md`](配置文件单元测试说明.md)(同层"强符号桩"范本)、 > [`相量层单元测试说明.md`](相量层单元测试说明.md)(同批落地的 全周傅氏相量姊妹篇)、 diff --git a/docs/测试说明/单元测试/主机单测覆盖率口径.md b/docs/测试说明/单元测试/主机单测覆盖率口径.md index eb8b110c..21d52b27 100644 --- a/docs/测试说明/单元测试/主机单测覆盖率口径.md +++ b/docs/测试说明/单元测试/主机单测覆盖率口径.md @@ -196,7 +196,7 @@ 缺口关闭。接线时的两个实测数:全闸跑完 **67 s**(33 套;本文别处写的"约 25 s"是只有 16 套、 "45 s"是 28 套时的值,都已过时);缺组件时钩子 **Failed**、脚本退出码 2 并打印 `[ENV]` 提示(合成自证)。 2. 它依赖 VS 可选组件(§7 第 8 条)。挂之前必须先定"缺组件时 skip 还是 FAIL"—— - 选 skip 就是一个会静默失效的门禁(与 `AGENTS.md` 里那条 `always: true 已失效、必须靠 files: 覆盖` + 选 skip 就是一个会静默失效的门禁(与 `docs/代码规范/pre-commit使用说明.md` §2.2 那条 `always: true 已失效、必须靠 files: 覆盖` 是同一类坑); 3. 基线首登后需要**真实回退事件**才算被验证过。已做的是**合成自证**(人为抬高 `test_coverage_baseline.json` 的三处数字后全量跑):行 / 函数 / 总计三条回退路径都报 `[REGRESS]` 且退出码 1;`--module` 子集运行 diff --git a/docs/测试说明/单元测试/卷锁单元测试说明.md b/docs/测试说明/单元测试/卷锁单元测试说明.md index f2bca839..173c0dbd 100644 --- a/docs/测试说明/单元测试/卷锁单元测试说明.md +++ b/docs/测试说明/单元测试/卷锁单元测试说明.md @@ -6,7 +6,7 @@ > **状态**:✅ 已落地(33 断言点,`/W4` 0 告警,已挂 pre-commit 钩子) > **日期**:2026-10-10 > **关联文档**: -> [`../../../AGENTS.md`](../../../AGENTS.md)(平台约束与看门狗铁律)、 +> [`../../../docs/子系统设计/看门狗设计说明.md`](../../../docs/子系统设计/看门狗设计说明.md) §3(心跳位图与单一喂狗者的铁律)、 > [`测试开发标准流程.md`](../流程与规范/测试开发标准流程.md)(测试分层与门禁总览)、 > [`看门狗单元测试说明.md`](看门狗单元测试说明.md)(同源的喂狗点语义)、 > [`相量层单元测试说明.md`](相量层单元测试说明.md)(同批落地的姊妹篇)、 diff --git a/docs/测试说明/单元测试/开机账本单元测试说明.md b/docs/测试说明/单元测试/开机账本单元测试说明.md index c5a233b7..1d78a42c 100644 --- a/docs/测试说明/单元测试/开机账本单元测试说明.md +++ b/docs/测试说明/单元测试/开机账本单元测试说明.md @@ -7,7 +7,7 @@ > **状态**:✅ 已落地(21 断言点,MSVC `/W4` 与 cppcheck 均 0 告警) > **日期**:2026-10-27(道G task-12) > **关联文档**: -> [`../../../AGENTS.md`](../../../AGENTS.md)(RTOS 与内存铁律、`[ERR]` 通道口径)、 +> [`../../../docs/子系统设计/控制台单写者日志设计.md`](../../../docs/子系统设计/控制台单写者日志设计.md) §1.2 / §7.1(内核前禁 RTOS API;日志成本按调用点计)、 > [`测试开发标准流程.md`](../流程与规范/测试开发标准流程.md)(测试分层与门禁总览)、 > [`主机单测覆盖率口径.md`](主机单测覆盖率口径.md)(覆盖率总闸如何收编本套)、 > [`../../子系统设计/系统墙钟时间维护说明.md`](../../子系统设计/系统墙钟时间维护说明.md) diff --git a/docs/测试说明/单元测试/时间同步单元测试说明.md b/docs/测试说明/单元测试/时间同步单元测试说明.md index d405c1e2..501e6ee0 100644 --- a/docs/测试说明/单元测试/时间同步单元测试说明.md +++ b/docs/测试说明/单元测试/时间同步单元测试说明.md @@ -6,7 +6,7 @@ > **状态**:✅ v2.0(:8888 退役后,33 断言点,已挂 pre-commit 钩子) > **日期**:2026-11-04(v2.0;v1.0 2026-10-10 的 TCP :8888 协议状态机套随 #78 退役重写) > **关联文档**: -> [`../../../AGENTS.md`](../../../AGENTS.md)(平台约束与看门狗铁律)、 +> [`../../../docs/子系统设计/看门狗设计说明.md`](../../../docs/子系统设计/看门狗设计说明.md) §3(心跳位图与单一喂狗者的铁律)、 > [`测试开发标准流程.md`](../流程与规范/测试开发标准流程.md)(测试分层与门禁总览)、 > [`看门狗单元测试说明.md`](看门狗单元测试说明.md)(喂狗位图判定状态机)、 > [`../../子系统设计/系统墙钟时间维护说明.md`](../../子系统设计/系统墙钟时间维护说明.md)(§15 退役历史 / §16 SNTP 现行设计)、 diff --git a/docs/测试说明/单元测试/相量层单元测试说明.md b/docs/测试说明/单元测试/相量层单元测试说明.md index 56ec62f8..a20eb30e 100644 --- a/docs/测试说明/单元测试/相量层单元测试说明.md +++ b/docs/测试说明/单元测试/相量层单元测试说明.md @@ -6,7 +6,7 @@ > **状态**:✅ 已落地(57 用例,`/W4` 0 告警,已挂 pre-commit 钩子) > **日期**:2026-10-10 > **关联文档**: -> [`../../../AGENTS.md`](../../../AGENTS.md)(平台约束)、 +> [`../../../docs/硬件平台/ADC通道映射说明.md`](../../../docs/硬件平台/ADC通道映射说明.md)(语义取数契约与 V0.1 双转换器边界)、 > [`测试开发标准流程.md`](../流程与规范/测试开发标准流程.md)(测试分层与门禁总览)、 > [`ADC输入层单元测试说明.md`](ADC输入层单元测试说明.md)(同批落地的 语义取数与有效性姊妹篇)、 > [`../../算法/傅氏算法详解.md`](../../算法/傅氏算法详解.md)(**系数约定权威口径** §2.3)、 diff --git a/docs/测试说明/单元测试/系统时钟单元测试说明.md b/docs/测试说明/单元测试/系统时钟单元测试说明.md index c6bd01ec..76c94c6d 100644 --- a/docs/测试说明/单元测试/系统时钟单元测试说明.md +++ b/docs/测试说明/单元测试/系统时钟单元测试说明.md @@ -6,7 +6,7 @@ > **状态**:✅ 已落地(20 用例 / 100 断言点,`/keil-build` 0/0,已挂 pre-commit 钩子) > **日期**:2026-10-02 > **关联文档**: -> [`../../../AGENTS.md`](../../../AGENTS.md)(平台约束)、 +> [`../../../docs/子系统设计/系统墙钟时间维护说明.md`](../../../docs/子系统设计/系统墙钟时间维护说明.md)(墙钟基准与 RTC 用户 SRAM 账本口径)、 > [`测试开发标准流程.md`](../流程与规范/测试开发标准流程.md)(测试分层与门禁总览)、 > [`看门狗单元测试说明.md`](看门狗单元测试说明.md)(同层范本) diff --git a/docs/测试说明/单元测试/配置文件单元测试说明.md b/docs/测试说明/单元测试/配置文件单元测试说明.md index a2f854a6..a66a0330 100644 --- a/docs/测试说明/单元测试/配置文件单元测试说明.md +++ b/docs/测试说明/单元测试/配置文件单元测试说明.md @@ -6,7 +6,7 @@ > **状态**:✅ 已落地(20 用例 / 139 断言点,`/keil-build` 0/0,已挂 pre-commit 钩子) > **日期**:2026-10-02 > **关联文档**: -> [`../../../AGENTS.md`](../../../AGENTS.md)(平台约束 · FatFs/内存铁律)、 +> [`../../../docs/架构设计/STM32F4-Base存储架构说明.md`](../../../docs/架构设计/STM32F4-Base存储架构说明.md) §10 第 10/11 项(FatFs 8.3 短名与 `FA_OPEN_APPEND` 陷阱)、 > [`测试开发标准流程.md`](../流程与规范/测试开发标准流程.md)(测试分层与门禁总览)、 > [`看门狗单元测试说明.md`](看门狗单元测试说明.md)、 > [`系统时钟单元测试说明.md`](系统时钟单元测试说明.md)(同层范本)、 diff --git a/docs/测试说明/板级测试/FTP_Test_Guide.md b/docs/测试说明/板级测试/FTP_Test_Guide.md index 359f26d8..147dca69 100644 --- a/docs/测试说明/板级测试/FTP_Test_Guide.md +++ b/docs/测试说明/板级测试/FTP_Test_Guide.md @@ -40,7 +40,7 @@ ## 3. 编译与运行(固件侧) - **默认构建即可提供 FTP Server**,无需切换测试套件。 -- 任何改动后必须执行 `/keil-build`(即 `keil-build` skill:`.dsh/skills/keil-build/scripts/keil_build.py`),确认 **0 Error(s) 0 Warning(s)** 再烧录(遵循 AGENTS.md 铁律)。 +- 任何改动后必须执行 `/keil-build`(即 `keil-build` skill:`.dsh/skills/keil-build/scripts/keil_build.py`),确认 **0 Error(s) 0 Warning(s)** 再烧录(`keil-build` skill 的判定口径)。 - 若需跑**自动化 FTP 文件传输用例**:在 `test/board/test_config.h` 选择 `TEST_SUITE_CH395F`,并在 `test/board/ch395f_test.h` 打开 `ENABLE_PHASE8_TESTS`(文件传输阶段),重新编译烧录。 - 烧录后打开串口(115200bps)观察: - `net_init` 完成、PHY link up; @@ -192,7 +192,7 @@ - **串口日志 + `DBG_*`**:在 `lftpd.c` / `net_socket` 关键路径加 `DBG_ERROR/INFO` 打印(注意编码安全铁律——只用 Edit 改中文源文件,禁止用 `Get/Set-Content` 整文件重写)。 - **抓包**:`ftp_capture.py` 或 Wireshark 过滤 `tcp.port==21`。 -- **编译验证**:`/keil-build` 必须 0/0 再烧录(AGENTS.md 铁律)。 +- **编译验证**:`/keil-build` 必须 0/0 再烧录(`keil-build` skill 的判定口径)。 - **套件切换**:`test/board/test_config.h` 改 `TEST_SUITE_CH395F` / `TEST_SUITE_GD5F` / `TEST_SUITE_STORAGE`(三选一,互斥)。 --- diff --git a/docs/测试说明/板级测试/实机测试实施指南.md b/docs/测试说明/板级测试/实机测试实施指南.md index 63ed57a1..bbe9aefd 100644 --- a/docs/测试说明/板级测试/实机测试实施指南.md +++ b/docs/测试说明/板级测试/实机测试实施指南.md @@ -226,7 +226,7 @@ $cli = if ($env:DTU_STLINK_CLI) { $env:DTU_STLINK_CLI } else { (Get-Command ST-L & '.venv\Scripts\python.exe' test/run_all_suites.py --check-build ``` -> ⚠️ **纪律**(呼应 `AGENTS.md` 铁律):自愈逻辑**严禁**把"名字/参数类错误码" +> ⚠️ **纪律**(契约来源 → `docs/网络/网络自愈架构设计.md`):自愈逻辑**严禁**把"名字/参数类错误码" > (如 `FR_INVALID_NAME`)归入"卷损坏触发集"——`.fschk` 无限重格式化事故即此类(2026-09-20)。 > ⚠️ **破坏性用例**:GD5F 套件默认只跑只读;`ENABLE_DESTRUCTIVE_TESTS` 跑一次消耗一个 NAND 块 > (实测 95248→95200),**仅在产线首启或明确需要时打开**。 diff --git a/docs/测试说明/流程与规范/测试开发标准流程.md b/docs/测试说明/流程与规范/测试开发标准流程.md index 55388262..d7ea2668 100644 --- a/docs/测试说明/流程与规范/测试开发标准流程.md +++ b/docs/测试说明/流程与规范/测试开发标准流程.md @@ -520,7 +520,7 @@ flowchart LR **明确不做的两件事(都是刻意为之)**: 1. **不跑 `/keil-build`(Keil UV4)**——需本机 Keil 授权,runner 上不具备。静态门禁的 cppcheck + 代码规范 - 已覆盖"编译前的静态问题",真编译仍是开发者的本地红线(`AGENTS.md`)。 + 已覆盖"编译前的静态问题",真编译仍是开发者的本地红线(`docs/CI/README.md`:CI 只跑静态门禁 + 主机侧单测,**不跑 `/keil-build`**)。 2. **`mem-numbers` 钩子按 `.map` 有无自适应跳过**——它的事实源是 `MDK-ARM/**/*.map` (Keil 构建产物,已 `.gitignore`),无 `/keil-build` 即无 `.map`。故 workflow 在**检测不到 `.map` 时自动跳过该钩子**(`SKIP=mem-numbers`,钩子显示 `Skipped` 而非 `Passed`—— diff --git a/docs/测试说明/流程与规范/自动化测试流程.md b/docs/测试说明/流程与规范/自动化测试流程.md index 0a5a1a35..35509e5b 100644 --- a/docs/测试说明/流程与规范/自动化测试流程.md +++ b/docs/测试说明/流程与规范/自动化测试流程.md @@ -101,7 +101,7 @@ | 现象 | 处理 | |---|---| -| `selftest` FAIL / `ModuleNotFoundError: pyserial` | venv 未建或依赖缺失:按 AGENTS.md「Python 环境」重建 `.venv` + `pip install -r requirements.txt` | +| `selftest` FAIL / `ModuleNotFoundError: pyserial` | venv 未建或依赖缺失:按 `new-machine-setup` skill 重建 `.venv` + `pip install -r requirements.txt` | | daemon 无响应 / 自动拉起失败 | 查 `.dsh/skills/serial-assistant/scripts/state/daemon.log`;`serial_tool.py restart` 重建 daemon;检查 COM 是否被其他程序占用 | | 抓到日志缺 `Network Init` | `-SettleMs` 太小(boot 任务间有 ~3-4s 自然静默间隙),用默认 8000ms;2026-10-10 起首字节到达前不启动静默计时(`--first-wait-ms` 默认 12000),首行晚到不再被提前收尾 | | 烧录后无数据(`no_data`) | 2026-10-10 起 `no_data` = **本次等待期间零字节**(旧实现比 daemon 累计字节,常驻 daemon 下永不触发,只能靠"日志里没有 [RX] 行"兜底);开串口 + clear 必须在烧录**前**完成(`run_boot_test.py` 已保证);核对 COM 号、板子供电,看 `state/serial.log` 有无 SYS 异常行 | diff --git a/docs/测试说明/测试工具/串口助手使用指南.md b/docs/测试说明/测试工具/串口助手使用指南.md index ddedb327..395fae39 100644 --- a/docs/测试说明/测试工具/串口助手使用指南.md +++ b/docs/测试说明/测试工具/串口助手使用指南.md @@ -1,7 +1,7 @@ # Python 串口助手(serial_tool)使用指南 > **定位**:面向使用者的操作手册——命令怎么敲、输出怎么看、常见场景怎么组合、出问题怎么排查。 -> **关联文档**:设计决策与实现细节见 `串口助手设计说明.md`;/serial-boot-test 自动化闭环见 `自动化测试流程.md`;`serial-assistant` skill 有一页速查(用到自动加载,AGENTS.md 不再重复收录)。 +> **关联文档**:设计决策与实现细节见 `串口助手设计说明.md`;/serial-boot-test 自动化闭环见 `自动化测试流程.md`;`serial-assistant` skill 有一页速查(用到自动加载,入口文件不重复收录)。 > **版本**:v1.2(与 `.dsh/skills/serial-assistant/scripts/serial_tool.py` 当前实现一致,2026-11-04;新增 daemon 死后串口自动重开与日志缺口标记——机理见 `docs/测试说明/测试工具/串口助手设计说明.md` §6.1,本文只讲行为) ## 1. 它是什么(60 秒版) diff --git a/docs/测试说明/测试工具/串口助手设计说明.md b/docs/测试说明/测试工具/串口助手设计说明.md index 2bdeb560..5a52fe77 100644 --- a/docs/测试说明/测试工具/串口助手设计说明.md +++ b/docs/测试说明/测试工具/串口助手设计说明.md @@ -227,7 +227,7 @@ flowchart LR | `.gitignore` | 增 `.dsh/skills/serial-assistant/scripts/state/` | | `opencode.json`(仓库根) | **删除 `mcp.serial` 段**(指向缺失二进制,已失效) | | `测试说明/serial-mcp-server_串口调试.md` | **已删除**(内容精华并入本文;工具历史见 §12) | -| `AGENTS.md` | "串口调试"节改写为 serial_tool(配置源仍 `serial_config.json`);"自动化测试"节同步新流程 | +| `AGENTS.md` 与 `docs/README.md` | "串口调试"节改写为 serial_tool(配置源仍 `serial_config.json`);"自动化测试"节同步新流程(**历史变更记录**,不是现行指针) | | `.opencode/command/test.md` | Step 0/2/Notes 改写(前置检查 = serial_tool 可用性 + `ports`;流程 = §7.1) | | `docs/测试说明/流程与规范/自动化测试流程.md` | 采集机制描述同步(去 serial-mcp-server 表述) | | `.opencode/serial_config.json` | 结构不变(可选增 `httpPort`);`note` 更新 | diff --git a/docs/环境与部署/并行任务工作树方案.md b/docs/环境与部署/并行任务工作树方案.md index 05c2df7e..e647de8e 100644 --- a/docs/环境与部署/并行任务工作树方案.md +++ b/docs/环境与部署/并行任务工作树方案.md @@ -156,7 +156,7 @@ STM32F4-Base/ # 主工作树,master 的唯一集成点 | 文件或目录 | 任务期规则 | 合并后处理 | |---|---|---| | `docs/任务规划/` | 默认只由主树写;任务树不并发销项 | 主树统一更新,完成即删对应待办行 | -| `AGENTS.md`、`docs/README.md` 的索引区 | 避免多个任务同时追加同一索引块 | 主树统一登记;只提交本任务应带的改动 | +| `AGENTS.md` 的生成块(`TASK_TABLE`)与 `docs/README.md` 的索引区 | 避免多个任务同时追加同一索引块 | 主树统一登记;只提交本任务应带的改动 | | FreeRTOS 任务表、内存快照与体积凭证 | 不手工拼合两份生成结果 | 基于合并后的真实源码和最新构建重生成 | | `MDK-ARM/*.uvprojx` | 新源文件按双端注册规程改;UV4 自动抖动不入库 | 检查注册并重新构建 | | `.pre-commit-config.yaml` | 新增钩子或检查范围时声明合并次序 | 合并后跑全量门禁,不能只信任务树结果 | diff --git a/docs/环境与部署/项目部署环境要求.md b/docs/环境与部署/项目部署环境要求.md index 3a11420e..5209a7ad 100644 --- a/docs/环境与部署/项目部署环境要求.md +++ b/docs/环境与部署/项目部署环境要求.md @@ -4,7 +4,7 @@ > 适用工程:STM32F4-Base(STM32F407ZGTx + CH395F 以太网 / LVGL UI / FreeRTOS) > 用途:新机器搭建、环境交接、现场部署时的**一站式环境核对清单**——开发机软件环境、 > 目标板硬件与资源预算、网络/服务现场部署、远端客户端环境、验收步骤与常见环境问题。 -> 文中所有版本/参数/数值均取自仓库内配置或本机实测(`AGENTS.md`、`MDK-ARM/*.bat`、 +> 文中所有版本/参数/数值均取自仓库内配置或本机实测(`requirements.txt`、`MDK-ARM/*.bat`、 > `simulator/README.md`、`docs/内存管理/`、`docs/子系统设计/网络配置说明.md`、`docs/测试说明/` 等), > 换机器时以仓库文件为准逐项核对。 diff --git a/docs/硬件平台/V0.0_网表详细分析报告.md b/docs/硬件平台/V0.0_网表详细分析报告.md index bdabe28c..65b92e8e 100644 --- a/docs/硬件平台/V0.0_网表详细分析报告.md +++ b/docs/硬件平台/V0.0_网表详细分析报告.md @@ -11,7 +11,7 @@ > **文档结构**:§1 结论速览 → §2 总体架构 → §3 问题清单 → §4 逐芯片详解 → §5 改进方向 → §6 最优先三件事 → 附录 A 勘误记录 / 附录 B 手册清单。 - **分析对象**:`V0.0.tel`(369 行,本目录) -- **对照依据**:`docs/芯片手册/`(12 份芯片手册 + 2 份 STM32 参考件,见附录 B)、`AGENTS.md`、`STM32F407-Demo.ioc`、`Drivers/BSP/` 驱动代码、`docs/问题记录/`、`docs/测试说明/` +- **对照依据**:`docs/芯片手册/`(12 份芯片手册 + 2 份 STM32 参考件,见附录 B)、`docs/架构设计/硬件规格与能力边界.md` §2、`STM32F407-Demo.ioc`、`Drivers/BSP/` 驱动代码、`docs/问题记录/`、`docs/测试说明/` - **分析日期**:2026-09-15 - **核实方法**:网表逐脚对照手册 → 代码/.ioc 交叉 → 实板开机标记反推;初版误判已全部撤回,汇总见**附录 A**;**2026-09-20 按 STM32 数据手册(DS8626)复核 U17 全部脚位并矫正,见附录 C** diff --git a/docs/硬件平台/开入开出实施说明.md b/docs/硬件平台/开入开出实施说明.md index 9bf0c80f..2307ef80 100644 --- a/docs/硬件平台/开入开出实施说明.md +++ b/docs/硬件平台/开入开出实施说明.md @@ -345,7 +345,7 @@ ### 6.4 保护判据未标定闭锁(承重限制) -保护判据目前处于**未标定闭锁**态:`adc_cal_prot_blocked()` 要求 UA/UN/IA 三路有效值齐备,而 UN 通道在本台架永久无数据(台架无接线),因此保护永久闭锁、不允许伪造有效值。详见仓库根 `AGENTS.md`「项目概况」。 +保护判据目前处于**未标定闭锁**态:`adc_cal_prot_blocked()` 要求 UA/UN/IA 三路有效值齐备,而 UN 通道在本台架永久无数据(台架无接线),因此保护永久闭锁、不允许伪造有效值。详见 `docs/产品需求/产品需求设计文档.md` §2.1 与 `docs/硬件平台/ADC通道映射说明.md` §7.5。 这意味着:**即使开出通道完全可用,也没有任何保护逻辑会去驱动它**——这是设计上的安全状态,不是缺陷。解除条件见 [`硬件规格与能力边界.md`](../架构设计/硬件规格与能力边界.md) 的 H3 行。 diff --git a/docs/算法/继电保护功能复现规划.md b/docs/算法/继电保护功能复现规划.md index a081cfe8..c6f9896f 100644 --- a/docs/算法/继电保护功能复现规划.md +++ b/docs/算法/继电保护功能复现规划.md @@ -215,7 +215,7 @@ | 采样缓冲 | 双缓冲(2 周波 = 40 点),写/读分属两区 | 环形缓冲 + **序号**(`tpafe5160_frame_seq()` 已有)+ 临界区快照,防撕裂 | | 相量区 | `tVectorRly[2][N]`,算完**原子交换**计算区/使用区指针 | 双区结构体 + 指针/索引原子切换(单核下用临界区或 `__atomic`) | | 遥测拷贝 | 0x55/0xaa 计算/拷贝握手标志 | 快照 + 序号,或 FreeRTOS 事件标志握手 | -| 取数契约 | —— | **只能用 `tpafe5160_snapshot()`**(`AGENTS.md` 铁律),不用已删除的 `get_buf` / `data_ready` | +| 取数契约 | —— | **只能用 `tpafe5160_snapshot()`**(本表即取数契约的权威口径,逐层映射见 `docs/硬件平台/ADC通道映射说明.md`),不用已删除的 `get_buf` / `data_ready` | ### 2.4 与现有子系统的接口 diff --git a/docs/算法/采样有效性校验设计说明.md b/docs/算法/采样有效性校验设计说明.md index 150da2b3..3bb0f79f 100644 --- a/docs/算法/采样有效性校验设计说明.md +++ b/docs/算法/采样有效性校验设计说明.md @@ -343,8 +343,8 @@ if (((serious | rise) & ~s_health_logged) != 0u) { /* 位图当去重键 */ - 控制台日志受 `dbg_console_writer_ready()` 门控(写者注册前直发会与 `defaultTask` 的存储初始化 日志字节级交错),但 **`SYSLOG_SELFTEST` 不受门控**——内核前有 `s_preboot` 缓冲, 开机窗口里的故障痕迹不能丢。 -- 每条 `DBG_*` 约 90 B Flash + 216 B 栈(每个调用点内联行缓冲与时间戳缓冲,见根 `AGENTS.md` - 平台约束)。**「判定层不打日志」不只为了可测性,也因为日志在 1 kHz 判定路径上是奢侈品**: +- 每条 `DBG_*` 约 90 B Flash + 216 B 栈(每个调用点内联行缓冲与时间戳缓冲,见 + `docs/子系统设计/控制台单写者日志设计.md` §7.1)。**「判定层不打日志」不只为了可测性,也因为日志在 1 kHz 判定路径上是奢侈品**: 编排把成本集中到少数几个沿上。 --- @@ -435,7 +435,7 @@ stateDiagram-v2 | 项 | 实测/核算 | 说明 | |---|---|---| -| 静态 RAM | 48 B(11 个 `uint32_t` = 44 B + 1 个 `uint8_t` 与对齐 4 B) | 判定层的全部驻留成本;无堆分配(自研代码禁 `malloc`,见根 `AGENTS.md` 平台约束) | +| 静态 RAM | 48 B(11 个 `uint32_t` = 44 B + 1 个 `uint8_t` 与对齐 4 B) | 判定层的全部驻留成本;无堆分配(自研代码禁 `malloc`,见 `docs/门禁说明/coding-standard.md` §2 CODE-RULE-20) | | 每拍 CPU | 约 20 条以内的整数加减与比较;无乘除、无浮点、无数组访问 | 与 1 kHz 节拍同频,量级远小于一次 `adc_input_poll()`(实测 8 us) | | 栈 | 判定本体只有 3 个局部量;最坏链在编排层的日志调用尾 | 判定层的日志尾是 `adcTask` 这条链加深的起点,曾直接触发抬栈一档;当前值与余量台账见 `docs/内存管理/RAM使用分析与优化方案.md` §2.3(配置与实测峰值)与 §4.0.6(静态最坏链与判定) | | Flash | 主要花在编排层的日志调用点,判定层本身很小 | 每条 `DBG_*` 约 90 B Flash,故新增位**不要**顺手加日志 | diff --git a/docs/网络/BSD_Socket_API_函数调用关系.md b/docs/网络/BSD_Socket_API_函数调用关系.md index 55c82179..95eb37cf 100644 --- a/docs/网络/BSD_Socket_API_函数调用关系.md +++ b/docs/网络/BSD_Socket_API_函数调用关系.md @@ -30,7 +30,7 @@ | **应用任务侧** | ftpTask / uiTask / timeSyncTask / testTask 等 | 经队列的公共 API(入队 + `xTaskNotifyWait` 等回执);纯 RAM 直调 API;**禁止直碰芯片** | 各服务任务 | | **直调快路径** | 同步调用,不经过队列 | `net_socket` / 查询族 / 回调注册 / `net_bind`(TCP) 记账(纯 RAM);**UDP 侧不再是例外**:`net_bind`(UDP) / `net_sendto` / `net_recvfrom` / `net_recvfrom_to` / `net_udp_set_peer` 已于 2026-11-03 全部并入队列 | 初始化阶段、netTask 上下文、测试套件(硬件层测试模式下 netTask 自挂起,testTask 独占芯片) | -> ⚠ 2026-11-03 起,**公开 API 里已经没有直碰 SPI 的口子**——原"三例外"(`net_bind`(UDP) / `net_sendto` / `net_recvfrom`)已全部并入队列,产品构建中应用任务的每一条 `net_*` 都是"入队 + 等回执"。仍需独占芯片的只剩**板级硬件层测试**:它绕过本层直接调 `ch395f_*`,前提是该测试模式下 netTask 自挂起、testTask 独占芯片(见 AGENTS.md"测试构建")。任何情况下从别的任务直接驱动 CH395F 都会与 `net_poll` 的 SPI 事务竞争、破坏芯片寄存器(TRAP-NET-14 实证:CONNECT 超时)。 +> ⚠ 2026-11-03 起,**公开 API 里已经没有直碰 SPI 的口子**——原"三例外"(`net_bind`(UDP) / `net_sendto` / `net_recvfrom`)已全部并入队列,产品构建中应用任务的每一条 `net_*` 都是"入队 + 等回执"。仍需独占芯片的只剩**板级硬件层测试**:它绕过本层直接调 `ch395f_*`,前提是该测试模式下 netTask 自挂起、testTask 独占芯片(见 `test_config.h` 套件互斥与 `board-test-suite` skill)。任何情况下从别的任务直接驱动 CH395F 都会与 `net_poll` 的 SPI 事务竞争、破坏芯片寄存器(TRAP-NET-14 实证:CONNECT 超时)。 --- @@ -281,7 +281,7 @@ flowchart TB | 函数 | 上下文 | 设计作用 | 关键决策 | |---|---|---|---| -| `net_udp_outparam_arm` / `net_udp_outparam_disarm` | 调用方任务(临界区只包"查占位"三步) | 登记"这次收包的源地址写回哪块调用方内存" | **源地址不搭 `net_msg_t`**:该结构按值拷入队列,AGENTS / TRAP-NET-10 明令禁止给它加"回传用"字段;出参指针进 per-fd 槽,netTask 直接写回调用方自己的内存,通知值只带结果码 | +| `net_udp_outparam_arm` / `net_udp_outparam_disarm` | 调用方任务(临界区只包"查占位"三步) | 登记"这次收包的源地址写回哪块调用方内存" | **源地址不搭 `net_msg_t`**:该结构按值拷入队列,契约与 TRAP-NET-10 明令禁止给它加"回传用"字段;出参指针进 per-fd 槽,netTask 直接写回调用方自己的内存,通知值只带结果码 | | `net_udp_clear` | 两侧 | 清本 fd 槽(`net_socket` 分配新 fd、入队失败、执行体每条出口都要清) | 槽位泄漏 = 该 fd 从此永久 `BUSY`;出口必清(ns_s7_udp.c UDP-7d / UDP-9e 钉住) | | `net_udp_bind_exec` | netTask | 服务器模式开芯片侧 Socket(5 条命令 + Socket 4~7 缓冲兜底) | DesIP/端口写在 open **之前**(手册 §9.2.4;open 复位寄存器);bind **恒服务器模式**——BSD 语义里 bind 不选对端;动态端口游标在 netTask 内推进(消掉跨任务写静态量) | | `net_udp_set_peer_exec` | netTask | 只写 DesIP/DesPort 切形态;`peer == NULL` 回服务器模式 | 不重开 Socket,因此**不清**芯片缓冲;要连残留包一起丢就再 `net_bind()`(重开形态) | diff --git a/docs/门禁说明/bom-guard.md b/docs/门禁说明/bom-guard.md index b1882684..b5cdda7f 100644 --- a/docs/门禁说明/bom-guard.md +++ b/docs/门禁说明/bom-guard.md @@ -64,7 +64,7 @@ BOM 名单),也可能是无意的;报红只会逼人 `--no-verify`,而** 漏加会在 `/keil-build` 时以真错误暴露——本门禁不假装自己能替代那一步。 ### 6.2 名单三处互指(防漂移) -AGENTS 铁律第 2 条的名单、钩子 `files` 正则、脚本内 `BOM_LIST` 必须一致;脚本每次运行都核一次, +权威名单在 `docs/文档规范.md` §2「编码与换行」表的「C 源码 BOM 名单」一行,钩子 `files` 正则、脚本内 `BOM_LIST` 必须与它一致;脚本每次运行都核一次, 不一致即 FAIL。比较时会先脱掉正则里的反斜杠与锚点——**核的是意图一致,不是字节相同**,否则 `App/task/ui_task\.c$` 会被误判成"没覆盖 App/task/ui_task.c"。 diff --git a/docs/门禁说明/check-yaml.md b/docs/门禁说明/check-yaml.md index f99b503d..fdb13f75 100644 --- a/docs/门禁说明/check-yaml.md +++ b/docs/门禁说明/check-yaml.md @@ -38,7 +38,7 @@ check yaml...............................................................Failed 1. **键名写错它不管**。本仓有现成教训:pre-commit 4.x 已移除 `always: true`,实测对 `local` 钩子里的这个键**只告警 `Unexpected key(s)` 然后忽略** —— 配置"看起来生效、其实没生效", 而 `check-yaml` 全绿。所以规则变成:**想让某个钩子总是跑,必须让 `files:` 覆盖到所有触发面** - (已写进 `AGENTS.md` 提交门禁一节,并在本目录多篇文档里复述为"触发面"一节)。 + (`AGENTS.md` 提交门禁一节只留一句禁令,逐钩子口径见本目录各篇的"触发面"一节)。 2. 不校验语义:`args` 少写一个参数、`entry` 指向一个不存在或不可执行的命令,都不报 (那要等到钩子真正跑起来才炸)。 3. 不校验 CI 表达式(`${{ ... }}` 内容原样当字符串)。 diff --git a/docs/门禁说明/cubemx-survival.md b/docs/门禁说明/cubemx-survival.md index b3f606e3..dcb80474 100644 --- a/docs/门禁说明/cubemx-survival.md +++ b/docs/门禁说明/cubemx-survival.md @@ -24,7 +24,7 @@ - 实测记录:`.ioc` 里 `ProjectManager.KeepUserCode=true` **只**保护 `USER CODE BEGIN/END` 之间; 2026-09-29 一次重生成覆盖了 **4 处定制**(P0×1 + P1×2 + P2×1)。典型形态:崩溃采集函数被打回 空 `while(1)`、加固宏被整块删除——**不报错,只在真崩的时候才发现没日志**。 -- AGENTS 把防丢失排成三层(写进 `.ioc` → 搬进 `USER CODE` 区 → **本门当审计兜底**)。 +- 防丢失排成三层(写进 `.ioc` → 搬进 `USER CODE` 区 → **本门当审计兜底**;方法论全文 → `docs/子系统设计/看门狗设计说明.md` §10)。 - 那一次被覆盖的具体内容:`HardFault_Handler` 的崩溃采集**被打回空 `while(1)`**、**两个 FreeRTOS 加固宏被整块删除**——两处都不报编译错,只在真出故障时才暴露。 @@ -46,7 +46,7 @@ CubeMX 重生成存活审计.......Failed - 单独跑:`--report` 只看审计报告(不比对基线);确认改动无误后 `--write` 重建基线。 - 正确动作:**先把定制搬回正确位置(优先写进 `.ioc` 与搬进 `USER CODE` 区),再 `--write`**;直接 `--write` 等于宣布 "被覆盖掉的样子是新的正确答案"。 -- 每次重生成后**立刻**跑(AGENTS 铁律),别等到提交时才发现。 +- 每次重生成后**立刻**跑(`cubemx-regen` skill 的完整流程),别等到提交时才发现。 ## 5. 好处 diff --git a/docs/门禁说明/gitlint.md b/docs/门禁说明/gitlint.md index 13c7996e..04e8b72c 100644 --- a/docs/门禁说明/gitlint.md +++ b/docs/门禁说明/gitlint.md @@ -20,7 +20,7 @@ - 本仓的提交说明是**主要载体**:实测数据、基线只减不增的口径、负结果、为什么这么改,全写在正文 里。格式一炸(超长行在 `git log` / 网页里被硬切),这些内容就没人读得下去。 -- 两条**本仓真踩过**的坑,已固化进 `AGENTS.md`: +- 两条**本仓真踩过**的坑(本文件是这两个坑的权威记录): ① 中文长标题极易超 100 → 标题保持短,细节写正文; ② 正文每行必须控制在 80 内,而且**用 `git commit -m` 传长中文会被终端代码页转码破坏** → 一律"短标题 + `git commit -F `"。 diff --git a/docs/门禁说明/host-unit-tests.md b/docs/门禁说明/host-unit-tests.md index 181201ff..6d9f20ee 100644 --- a/docs/门禁说明/host-unit-tests.md +++ b/docs/门禁说明/host-unit-tests.md @@ -115,7 +115,7 @@ ① 别把没接线的套件算进钩子账(原写「23 个 / 含 ui-sink」正是这么错的;2026-10-27 复核的准数是 22 根 / 40 套 / 18 套无专属钩子(三个数都是当时值)——第 41 套 `boot_stats` 当日 11:29 才入库,此后两数当时是 41 / 19,现值 47 / 25 以本条上面的实测行为准);② 也别把总闸的绿读成「每套都被单独归因过」——它只保证 「全跑过 + 覆盖率没回退」。将来确实要给某套补专属钩子,先过上一条判据,并在**同一笔**里改 - AGENTS 与门禁索引的计数(口径 = YAML 解析条目数,见 `docs/门禁说明/README.md` §2 首条)。 + 门禁索引的计数(口径 = YAML 解析条目数,见 `docs/门禁说明/README.md` §2 首条;该索引是唯一计数口径)。 - 总闸的触发面是 `App/`、`Drivers/BSP/`、`test/host/`、覆盖率脚本与基线,**外加门禁自身** (`.pre-commit-config.yaml`)——不带上自身就等于谁改坏这根闸的 `files:` 模式它就再也不跑 (同 `lv-conf-sync` / `bsp-err` 的既有做法)。纯 UI/文档改动不触发它,那时确实没有可回归的行为。 diff --git a/docs/门禁说明/layer-deps.md b/docs/门禁说明/layer-deps.md index b6efcff4..e1fb7490 100644 --- a/docs/门禁说明/layer-deps.md +++ b/docs/门禁说明/layer-deps.md @@ -6,7 +6,7 @@ - 配置:`entry: python scripts/check_layer_deps.py`、`pass_filenames: false`、 `files: ^Drivers/BSP/|^scripts/check_layer_deps\.py$|^\.pre-commit-config\.yaml$`。 - 规范出处:`docs/架构设计/项目架构总览.md`(六层单向:业务 → UI/基础服务 → 中间件 → - BSP 驱动 → HAL/RTOS → 硬件)、`AGENTS.md` 分层边界。 + BSP 驱动 → HAL/RTOS → 硬件)、`docs/架构设计/项目架构总览.md` §2 的分层边界表。 ## 1. 它在查什么 diff --git a/docs/门禁说明/mermaid-syntax.md b/docs/门禁说明/mermaid-syntax.md index 11dc1e8a..348c071d 100644 --- a/docs/门禁说明/mermaid-syntax.md +++ b/docs/门禁说明/mermaid-syntax.md @@ -93,4 +93,4 @@ R1 改图类型头;R2 改 `-.->|t|` 或 `-. t .->`;R3 补/删 `end`(打印 - 判定用「行首 token / 邻接字符」这类保守形态学,**不要**用「看起来像标签」的启发式—— 本仓围栏里混排中英文、全角符号、`µ`/`≠`/`→` 等字符,启发式必误伤。 - 本条钩子使 YAML 解析口径 **51 → 52**、提交期实跑 **48 → 49**;加/摘钩子按 - `docs/门禁说明/README.md` §2 首条的自查命令三数同核(AGENTS 与索引两处计数同批改)。 + `docs/门禁说明/README.md` §2 首条的自查命令三数同核(索引 §2 标题与 §1 计数同批改)。 diff --git a/docs/门禁说明/no-mojibake.md b/docs/门禁说明/no-mojibake.md index cb1a3e81..c3be3674 100644 --- a/docs/门禁说明/no-mojibake.md +++ b/docs/门禁说明/no-mojibake.md @@ -10,13 +10,13 @@ ## 1. 它在查什么 - 唯一判据:字节序列 `EF BF BD`(UTF-8 编码的 `U+FFFD`)。 -- 它**不试图判断**"这是不是故意的"——按 AGENTS 铁律,字符串字面量必须纯 ASCII,中文只写注释, +- 它**不试图判断**"这是不是故意的"——按编码铁律(`docs/文档规范.md` §2),字符串字面量必须纯 ASCII,中文只写注释, 所以正常代码里出现替换符一定是损坏。 ## 2. 为什么要它 - 本仓最常见的不可逆事故:用 `Get-Content`/`Set-Content`/`cmd` 重写含中文的文件,整文件按 - 系统默认代码页重解码 → 中文变 ``,**而且原内容再也拿不回来**(AGENTS 列为 Never)。 + 系统默认代码页重解码 → 中文变 ``,**而且原内容再也拿不回来**(`docs/文档规范.md` §2 列为 Never)。 - 它是那条铁律唯一机械化的部分:其它铁律(只用 Edit 工具、怀疑乱码先数 `EF BF BD`)都靠人。 ## 3. 触发面 / 看不见什么 @@ -39,7 +39,7 @@ Forbid U+FFFD mojibake.......Failed - 典型报错:`U+FFFD replacement chars found (encoding corrupted, irreversible!): path/to/file.c`。 - 修复路径:从 git 历史里找到**最后一个干净版本**,只把损坏区域搬回来(整文件 checkout 会连本次 - 改动一起丢掉,属 AGENTS 的 Never)。 + 改动一起丢掉,属 `docs/文档规范.md` §2 的 Never 清单)。 - 修完必须回头查**写入方式**(`Get-Content` / `Set-Content` / `cmd` 重写含中文文件),否则修好还会再来。 ## 5. 好处 diff --git a/docs/门禁说明/skill-size.md b/docs/门禁说明/skill-size.md index b26c90d3..4b89815c 100644 --- a/docs/门禁说明/skill-size.md +++ b/docs/门禁说明/skill-size.md @@ -36,7 +36,7 @@ | 全树实扫 | \`.dsh/skills\` 共 **17 个 SKILL.md:0 FAIL、0 WARN**,最大 \`task-worktree\` 28139 字节(42%);退出码 0 | | \`--selftest\` 五形态 | **5/5**:干净树 0 / 75% 线 0(带 WARN)/ 65546 字节 1 / 悬空指针 + BOM 1 / 根不存在 2 | | 钩子接线 | YAML 解析条目 **51 → 52**;\`stages: [manual]\` 仍 **3** 根(一次 \`git commit\` 实跑 49);\`pre-commit run skill-size --all-files\` 与 \`--files .dsh/skills/task-worktree/SKILL.md\` 两种触发都 **Passed** | -| 解释器面 | 钩子 entry 用裸 \`python\`:\`.venv\` 3.12 与 PATH 上的 3.14.7 都跑通——本脚本纯标准库,**不属于** AGENTS.md「裸 python 不等于 .venv」那条教训的适用面(那条针对 fontTools 这类第三方依赖) | +| 解释器面 | 钩子 entry 用裸 \`python\`:\`.venv\` 3.12 与 PATH 上的 3.14.7 都跑通——本脚本纯标准库,**不属于**「裸 `python` 不等于 `.venv`」那条教训的适用面(判据在 `keil-build` skill「调用形态」;那条针对 fontTools 这类第三方依赖) | | 负例落点 | 在 \`--selftest\` 的**临时树**里造,不在 \`.dsh/skills/\` 下造探针目录:那是活动技能目录,加载器与自进化都会看见它(见 §8) | ## 3. 触发面 diff --git a/requirements.txt b/requirements.txt index ebbb676c..8ad70ad5 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +1,5 @@ # DTU STM32F4-Base Python deps (unified entry: .venv\Scripts\python.exe) -# Rebuild instructions: see AGENTS.md "Python env" section. +# Rebuild instructions: see the new-machine-setup skill (and docs/环境与部署/项目部署环境要求.md). # NOTE: keep this file ASCII-only (pip on Windows decodes it with the locale codepage). fonttools==4.51.0 # tools/font_gen/make_font.py (font generation, verified version) pillow==10.3.0 # simulator/i1_to_png.py (screenshot to PNG, verified on this machine) diff --git a/scripts/archive/id_gate/id_aliases.json b/scripts/archive/id_gate/id_aliases.json index eacc46ac..75f0e40e 100644 --- a/scripts/archive/id_gate/id_aliases.json +++ b/scripts/archive/id_gate/id_aliases.json @@ -3246,7 +3246,7 @@ "N-03b": { "to": null, "status": "void", - "note": "报告 N-03b(IWDG / `configASSERT` / 两个钩子 / 4 个 Fault 现场)——属主文档 docs/问题记录/项目审查与优化建议报告.md 已于 2026-10-25 删除。现行去处:docs/子系统设计/看门狗设计说明.md §4.4、§10.1/§10.2 + AGENTS.md「平台约束」" + "note": "报告 N-03b(IWDG / `configASSERT` / 两个钩子 / 4 个 Fault 现场)——属主文档 docs/问题记录/项目审查与优化建议报告.md 已于 2026-10-25 删除。现行去处:docs/子系统设计/看门狗设计说明.md §4.4、§10.1/§10.2" }, "N-10": { "to": null, diff --git a/scripts/archive/id_gate/id_registry.json b/scripts/archive/id_gate/id_registry.json index 49a82a99..0999aba5 100644 --- a/scripts/archive/id_gate/id_registry.json +++ b/scripts/archive/id_gate/id_registry.json @@ -927,7 +927,7 @@ "审查" ], "collides_with": "N", - "cursor_note": "⚠ 与登记簿 N-x 同名不同义(§4.3 / AGENTS.md 模块约定)→ 引用必须紧邻「报告」或报告文档名", + "cursor_note": "⚠ 与登记簿 N-x 同名不同义(§4.3 / 网络模块约定)→ 引用必须紧邻「报告」或报告文档名", "snapshot_only": true, "snapshot_note": "§4.3 冻结历史快照:只在引用写了文档名(紧邻线索)时参与定族,不参与「定义位优先」——避免同号把活登记处接管走", "owner_note": "属主文档 docs/问题记录/项目审查与优化建议报告.md 已于 2026-10-25 删除(用户裁定:内容大部分已闭环);登记职责与 26 行「号 → 现在详述于」对照表迁到 编号规范.md §4.5,故 owner_docs 指向该节——它只用于**恢复可判定比例**(§4.5 是冻结存档登记处),定义集仍为空(snapshot_only 族剔除规范正文,见 check_ids.py 的 _def_owners),因此不参与悬空/撞号/裸形判定。未闭环项早已并轨到登记簿 N-19~N-29 + U 簇" diff --git a/scripts/check_bom_drift.py b/scripts/check_bom_drift.py index d402895e..b9b049d8 100644 --- a/scripts/check_bom_drift.py +++ b/scripts/check_bom_drift.py @@ -3,7 +3,7 @@ 模块名称:BOM 漂移检查(提交门禁 bom-guard 的实现) 模块功能:对给定文件集合(默认 = pre-commit 传进来的本次所改文件)逐个比较 HEAD 版本与工作区 版本的前 3 字节:HEAD 有 UTF-8 BOM(EF BB BF)而工作区没有 → FAIL 并列出补救动作。 -为什么要这条:AGENTS 铁律第 2 条记载的实测坑——编辑工具会**静默剥掉**文件原有 BOM,ARMCC +为什么要这条:编码铁律记载的实测坑(口径 → docs/文档规范.md §2)——编辑工具会**静默剥掉**文件原有 BOM,ARMCC 于是按 CP936 解码带中文的源文件,报出 #870-D / #8 / #274 一类**假语法错**(错的位置 和内容都不指向真因);MSVC(模拟器侧)与任何"只跑编译"的门禁都不覆盖这一步,历史 "0 警告"不代表安全。2026-10-25 一天之内道E 一个任务踩了 4 次、道B 批 1 踩过 1 次, diff --git a/scripts/check_coding_standard.py b/scripts/check_coding_standard.py index ec67f565..c7bdf45f 100644 --- a/scripts/check_coding_standard.py +++ b/scripts/check_coding_standard.py @@ -42,7 +42,7 @@ C_KEYWORDS = {'if', 'for', 'while', 'switch', 'do', 'else', 'return', NAME_PAREN_RE = re.compile(r'([A-Za-z_][A-Za-z0-9_]*)\s*\(') -# CODE-RULE-20 的例外:平台分配后端的**宿主侧实现**(AGENTS.md「只用 pvPortMalloc/vPortFree, +# CODE-RULE-20 的例外:平台分配后端的**宿主侧实现**(口径「只用 pvPortMalloc/vPortFree, # 或把分配收进平台后端」说的就是这种收口点)。只点名到文件 + 只放行这两个函数名, # 不做目录级豁免——新增一个想 malloc 的文件必须显式加进这里,评审时看得见。 HEAP_ALLOC_ALLOWLIST = { @@ -291,14 +291,14 @@ def check_file(path): # CODE-RULE-19 (4.4.2) 函数定义左大括号必须与右括号同行 # CODE-RULE-20 (平台约束,2026-10-23) 禁止 C 库堆分配 # 出处**不在规范 V1.0**(其 §6.1 示例本身就写着 malloc/free,属通用 C 模板遗留,已同日在示例 - # 下方加"本仓禁止"批注),而在 AGENTS.md「平台约束」+ docs/内存管理/RAM使用分析与优化方案.md: + # 下方加"本仓禁止"批注),而在本脚本的 FORBIDDEN 名单 + docs/内存管理/RAM使用分析与优化方案.md: # MicroLIB 的 C 堆由 startup_stm32f407xx.s 的 Heap_Size EQU 0x200 限定为 **512 B**,KB 级分配 # 必然返回 NULL,而**模拟器(宿主 CRT 堆)完全正常、照不出来** —— 典型"只有真机才炸",必须机器拦。 # 判据细节(三条都是踩过坑之后定的): # - 大小写敏感:pvPortMalloc / vPortFree(唯一允许的配对)不会中招; # - 词边界 \b:dhara_nand_is_free(、buf_alloc( 这类"同形后缀"的自有函数名不会误报; # - 跑在 masked 上:注释与字符串字面量里提到 malloc 不报(规范示例就是这种命中)。 - # 覆盖名比 AGENTS 列的五枚多带上 strndup / aligned_alloc —— 同族同类,漏一个就等于留个后门。 + # 覆盖名比口径列的五枚多带上 strndup / aligned_alloc —— 同族同类,漏一个就等于留个后门。 norm = path.replace('\\', '/') allow = frozenset() for suffix, names in HEAP_ALLOC_ALLOWLIST.items(): diff --git a/scripts/check_cubemx_survival.py b/scripts/check_cubemx_survival.py index 297b4b54..572bec43 100644 --- a/scripts/check_cubemx_survival.py +++ b/scripts/check_cubemx_survival.py @@ -30,7 +30,7 @@ CubeMX 重生成存活审计(check_cubemx_survival.py) 退出码:0 = 通过;1 = 有 FAIL 项。 -设计依据:docs/子系统设计/看门狗设计说明.md §10.2/§10.3;AGENTS.md「平台约束」。 +设计依据:docs/子系统设计/看门狗设计说明.md §10.2/§10.3;docs/门禁说明/cubemx-survival.md。 注意 ---- diff --git a/scripts/check_generated_fresh.py b/scripts/check_generated_fresh.py index 7016e996..71c8f22f 100644 --- a/scripts/check_generated_fresh.py +++ b/scripts/check_generated_fresh.py @@ -254,7 +254,7 @@ def report_no_interpreter(table): q = chr(39) print(" 修法(任一,改完直接重跑本脚本自检):") print(" 1) 显式指定:PowerShell 里 $env:DTU_GEN_PYTHON = " + q + venv + q) - print(" 2) 重建仓库虚拟环境(口径 AGENTS.md「Python 环境」):") + print(" 2) 重建仓库虚拟环境(口径见 new-machine-setup skill):") print(" & <本机任一 python ≥3.10> -m venv .venv ; & " + q + venv + q + " -m pip install -r requirements.txt") print(" ⚠ 这一项刻意**不 SKIP**:解释器或依赖坏了必须响,静默跳过等于造一根会假绿的闸") diff --git a/scripts/check_layer_deps.py b/scripts/check_layer_deps.py index 5a5250be..61a84c32 100644 --- a/scripts/check_layer_deps.py +++ b/scripts/check_layer_deps.py @@ -4,7 +4,7 @@ 背景(2026-10-22 加) ---------------- -AGENTS.md 与 docs/架构设计/项目架构总览.md 都写着"六层单向依赖:业务 → UI/基础服务 +docs/架构设计/项目架构总览.md §1 与 §2 写着"六层单向依赖:业务 → UI/基础服务 → 中间件 → BSP 驱动 → HAL/RTOS → 硬件",但**此前没有任何机械检查**:Drivers/BSP/ 里 可以随手 include "cfg_file.h" 而无人报警。后果是可测量的口径漂移——2026-09 审查报告 记"NETCFG 一处",2026-10-22 实测已长到 8 个文件 9 处。边界的静默腐蚀只能靠门禁止住: diff --git a/scripts/check_size_gate.py b/scripts/check_size_gate.py index d2817558..9d41b177 100644 --- a/scripts/check_size_gate.py +++ b/scripts/check_size_gate.py @@ -51,7 +51,7 @@ 原始字节——本仓 core.autocrlf=true 而 .gitattributes 写死 eol=lf,实测主树 1046/1388 个受管源码落成 CRLF、新建工作树同一提交落成 LF,而索引 blob 完全一致;按原始字节算 会让同一份代码在不同 checkout 得到不同指纹(主树盖的戳在别人工作树与 runner 上误红) -→ 索引 blob 才是跨 checkout 稳定的身份,也是 AGENTS「不依赖 core.autocrlf」的机器化。 +→ 索引 blob 才是跨 checkout 稳定的身份,也是「不依赖 core.autocrlf」口径的机器化(→ docs/文档规范.md §2)。 推论:**未 staged 的改动不在索引里**,凭证覆盖不到 → --stamp 拒绝在有脏时盖章, --local/--ci 也把它单独报出来(已 git add 的不算脏:索引已含其内容,正是要测的那份)。 @@ -121,7 +121,7 @@ def index_snapshot(): 完全相同**(实测 dbg_cfg.h:1247 B/LF vs 1293 B/CRLF,blob 都是 c39395f7)。 拿原始字节算指纹 = 同一份代码在不同 checkout 得到不同指纹:主树盖的戳在道C 新工作树里判"不同码",runner 上同样会误红——**门禁自己造 false positive**。 - 索引 blob 是 git 归一化后的身份,跨 checkout 稳定,也正是 AGENTS「行尾由 + 索引 blob 是 git 归一化后的身份,跨 checkout 稳定,也正是「行尾由 .gitattributes 写死、不依赖 core.autocrlf」的机器化说法。 """ raw = _git(["ls-files", "-s", "-z"]) diff --git a/scripts/ci_gitlint_range.ps1 b/scripts/ci_gitlint_range.ps1 index 9f917784..2b0fefdc 100644 --- a/scripts/ci_gitlint_range.ps1 +++ b/scripts/ci_gitlint_range.ps1 @@ -10,7 +10,7 @@ (measured 2026-10-12: master 18 defined / 17 reported, v2-on-ui 26 / 25). The missing one is `gitlint`: its hook definition declares `stages: [commit-msg]`, while `pre-commit run --all-files` only runs the - `pre-commit` stage. So the commit-message rule from AGENTS.md (title + `pre-commit` stage. So the commit-message rule (title < 100 chars, body lines <= 80) was enforced on developer machines and NEVER in CI -- a silent gate gap, not a failure. @@ -198,7 +198,7 @@ try { exit 2 } if ($failed -gt 0) { - Write-Host '::error::commit message gate failed -- see the gitlint output above for the exact rule id (rules in .gitlint; AGENTS.md: title <= 100 chars, body lines <= 80)' + Write-Host '::error::commit message gate failed -- see the gitlint output above for the exact rule id (rules in .gitlint; title <= 100 chars, body lines <= 80)' exit 1 } exit 0 diff --git a/simulator/README.md b/simulator/README.md index d70aa8c9..51bbb1c2 100644 --- a/simulator/README.md +++ b/simulator/README.md @@ -188,7 +188,7 @@ LVGL 场景(同一份 ui_menu.c) cd simulator # 1) 离屏渲染首帧,输出 I1(1bpp) 原始位图(已剥离 8 字节调色板,纯像素数据) .\build\Debug\lvgl_sim.exe --screenshot shot.bin -# 2) 转 PNG(默认 160x160;--scale 放大便于查看;python 统一用仓库 .venv,见 AGENTS.md「Python 环境」) +# 2) 转 PNG(默认 160x160;--scale 放大便于查看;python 统一用仓库 .venv,见 new-machine-setup skill) ..\.venv\Scripts\python.exe i1_to_png.py shot.bin # -> shot.png ..\.venv\Scripts\python.exe i1_to_png.py shot.bin -o 预览.png --scale 6 ``` @@ -277,7 +277,7 @@ UI 改动的自动化门禁脚本(完整流程见 `docs/UI设计/UI_自动化 4. **中文显示空白**:字体 `ui_font_cn_12` 是子集字体(当前 224 汉字/符号 + ASCII,共 319 字形;2026-10-29 录波 UI 道 +6 字(放该读削域不),218/313→224/319;2026-10-28 UI 补齐批 +33 字,旧数 183/278 系未回填、改前实测 185/280),缺字渲染为空白。 补字流程见 `docs/UI设计/UI_中文字体生成与配置.md`(`tools/font_gen/` 两步脚本)。 5. **改了 UI 代码但模拟器没变化**:确认改的是 `Drivers/BSP/UI/ui_menu.c`(共享原件)而非本目录副本(本目录无副本),然后重新 `cmake --build`。 -6. **编码**:UI 源码为 UTF-8(带 BOM),MSVC 已加 `/utf-8`。**不要**用 PowerShell `Set-Content` 等重写含中文的文件(编码铁律,见根目录 `AGENTS.md`)。 +6. **编码**:UI 源码为 UTF-8(带 BOM),MSVC 已加 `/utf-8`。**不要**用 PowerShell `Set-Content` 等重写含中文的文件(编码铁律,见 `docs/文档规范.md` §2)。 7. **键盘输入无响应(方向键/Enter 无效)**:`main.c` 主循环**不得**调用 `SDL_PollEvent`。 LVGL SDL 驱动内部有 5ms 定时器(`lv_sdl_window.c` 的 `sdl_event_handler`)统一轮询分发 SDL 事件; 主循环若先轮询会消费掉事件队列,键盘输入永远到不了 LVGL(现象:画面正常但按键全部无效)。 diff --git a/simulator/tests/regen_ref_png.py b/simulator/tests/regen_ref_png.py index 35754b6b..47f4da96 100644 --- a/simulator/tests/regen_ref_png.py +++ b/simulator/tests/regen_ref_png.py @@ -8,7 +8,7 @@ regen_ref_png.py — 由黄金参考 .bin 批量重生成目检用 PNG(simulat 刷过 `check_content_pages.py --update` 或改了字体/视觉后,必须重跑本脚本,否则 PNG 仍是旧渲染(缺字/错位,看似"乱码")。 -用法(仓库根目录;PIL 依赖用 .venv,见 AGENTS.md「Python 环境」): +用法(仓库根目录;PIL 依赖用 .venv,重建见 new-machine-setup skill): .venv\\Scripts\\python.exe simulator/tests/regen_ref_png.py .venv\\Scripts\\python.exe simulator/tests/regen_ref_png.py --scale 4 .venv\\Scripts\\python.exe simulator/tests/regen_ref_png.py --no-invert # 白字黑底(设备原样) diff --git a/test/board/README.md b/test/board/README.md index 3ae34c31..95ebd6ff 100644 --- a/test/board/README.md +++ b/test/board/README.md @@ -16,7 +16,7 @@ | `net_test_task.c/h` | 网络层测试 | | `net_latency_test.c/h` | 链路时延探针(DWT CYCCNT 时基,MCU 专属) | -## ⚠️ 构建约束(`AGENTS.md` 详述) +## ⚠️ 构建约束(详见本节与 `test_config.h`) - **套件互斥**:`test_config.h` 的 `TEST_SUITE_CH395F/STORAGE/GD5F/RTC` 一次只能启用一个 (违反则 `#error`);**全部注释 = 产品构建** @@ -41,5 +41,5 @@ ## 相关文档 - 测试指南:`docs/测试说明/板级测试/CH395F_Test_Guide.md`、`GD5F2GQ5UE_Test_Guide.md`、`SD2506_Test_Guide.md`、`FTP_Test_Guide.md` -- 套件配置:`AGENTS.md`「测试与验证」章 +- 套件配置:本节「构建约束」+ `board-test-suite` skill(套件互斥、破坏性开关代价、跑后恢复产品构建) - 容量恢复:`docs/测试说明/专项验证/存储维护与容量恢复.md` diff --git a/test/board/net_latency_test.h b/test/board/net_latency_test.h index bd68f1ae..b0bab174 100644 --- a/test/board/net_latency_test.h +++ b/test/board/net_latency_test.h @@ -46,7 +46,7 @@ extern "C" { #define LAT_VERDICT_FAIL 2 /* - * 采样保存上限:静态数组容量(自研代码禁用 C 库堆,见 AGENTS.md)。 + * 采样保存上限:静态数组容量(自研代码禁用 C 库堆 → docs/门禁说明/coding-standard.md §2)。 * n 可超过该值(min/max/spikes 仍对全量累计;med/p95 按已保存样本计算)。 */ #define LAT_MAX_SAMPLES 128 diff --git a/test/board/storage_test_task.c b/test/board/storage_test_task.c index 5ec4a2ad..e8243fc1 100644 --- a/test/board/storage_test_task.c +++ b/test/board/storage_test_task.c @@ -261,7 +261,7 @@ static void storage_test_badblock(void) * 非法名字 f_open 必返 FR_INVALID_NAME(纯 RAM 名字判定、不碰盘);合法但 * 不存在的名字返 FR_NO_FILE。本测试断言两类严格可区分——一旦哪天有人把 * FR_INVALID_NAME 误归入"卷损坏"自愈集合,这条测试就是最后的机械防线。 - * (详见 docs/问题记录/GD5F2GQ5UE_Trap_Records.md TRAP-GD5F-05 / AGENTS.md) + * (详见 docs/问题记录/GD5F2GQ5UE_Trap_Records.md TRAP-GD5F-05) */ static void storage_test_name_validation(void) { diff --git a/test/host/README.md b/test/host/README.md index 5ffc8410..c0291c8a 100644 --- a/test/host/README.md +++ b/test/host/README.md @@ -79,7 +79,7 @@ > `docs/测试说明/单元测试/时间同步单元测试说明.md`; > harness 用法见 [`common/README.md`](common/README.md)。 > 已挂 pre-commit 钩子(各模块同名 `*-unit-test`,共 **22** 个;逐个说明见 -> `docs/代码规范/pre-commit使用说明.md` §2 与 AGENTS.md 门禁条)。 +> `docs/代码规范/pre-commit使用说明.md` §2.2 与 `docs/门禁说明/host-unit-tests.md`)。 ### nand_port —— dhara NAND 移植层为什么能在 PC 上测 diff --git a/test/host/common/ch395f_fake.h b/test/host/common/ch395f_fake.h index 706739d7..15ac336e 100644 --- a/test/host/common/ch395f_fake.h +++ b/test/host/common/ch395f_fake.h @@ -17,7 +17,7 @@ * * 必须复刻的两条芯片怪癖(不复刻就等于把被测代码的坑假件掉): * 1. ch395f_get_sock_int_status() 是**整体读即清**、芯片没有按位清除手段。本假件 - * 返回该 socket 的挂起位图并同步清零。AGENTS 模块约定里 B3 的实证坑("顺手 + * 返回该 socket 的挂起位图并同步清零。模块约定 B3 的实证坑("顺手 * 全量清一遍"把别的在用 Socket 的门焊死)靠这条才照得出来。 * 2. *_cached 系列返回的是**缓存值**而不是现场值:open 状态与 TCP 状态分开、且 * "监听还活着"的判据是 (open != CLOSED && tcp_state == LISTEN)。测试据此能构造 @@ -80,7 +80,7 @@ * * 必须复刻的第三条芯片怪癖(前两套测不到、net_socket.c 却是主路): * 3. GET_GLOB_INT_STATUS_ALL(0x19,2 字节)**整体读即清**,且它是全局寄存器 - * (含全部 Socket 事件位)。AGENTS 模块约定 B3:唯一读者只能是 net_poll。 + * (含全部 Socket 事件位)。模块约定 B3:唯一读者只能是 net_poll。 * 假件按调用序号返回预置值,并单独计数,让"别处偷偷读全局"成为可断言的事。 * 4. sock_reset 复位机(E4 定案四步:读空 RX → CLOSE → 排空事件(quiescent) → * 等 byte0=00H,含 LISTEN 态二段 CLOSE 补发)。这里做**契约等价**实现: diff --git a/test/host/iec104_serv/run_unit_test.py b/test/host/iec104_serv/run_unit_test.py index 09a98be0..23374ba4 100644 --- a/test/host/iec104_serv/run_unit_test.py +++ b/test/host/iec104_serv/run_unit_test.py @@ -27,7 +27,7 @@ 退出码:0=PASS / 1=测试失败 / 2=环境错误。 -设计依据:docs/子系统设计/*104* 设计文档、AGENTS.md 模块约定(单连接 socket 断开语义、 +设计依据:docs/子系统设计/*104* 设计文档、docs/网络/网络自愈架构设计.md §4.10(单连接 socket 断开语义、 错误码经任务通知值回传)、docs/测试说明/单元测试/主机单测覆盖率口径.md §9 创建日期:2026-10-23 """ diff --git a/test/host/net_events/stub/dbg_log.h b/test/host/net_events/stub/dbg_log.h index a7e544d0..2d4d4670 100644 --- a/test/host/net_events/stub/dbg_log.h +++ b/test/host/net_events/stub/dbg_log.h @@ -1,7 +1,8 @@ /* * 模块名称:主机侧单测桩 - dbg_log.h(net_events 模块专用) * 模块功能:DBG_* 计数。注意 net_events.c 在 include 本头之前把 DBG_LINE_BUF_MAX - * 抬到 128U(AGENTS:深调用链模块必须抬,否则最长日志行会被截断), + * 抬到 128U(深调用链模块必须抬,否则最长日志行会被截断 → + * docs/子系统设计/控制台单写者日志设计.md §7.1), * 本桩不关心缓冲大小,只数条数。 * ⚠ 仅供主机侧单测使用,不参与 MCU 构建。 * 创建日期:2026-10-23 diff --git a/test/host/net_listener/net_listener_test.c b/test/host/net_listener/net_listener_test.c index 3d240509..16310c95 100644 --- a/test/host/net_listener/net_listener_test.c +++ b/test/host/net_listener/net_listener_test.c @@ -25,7 +25,7 @@ * 关不掉时,代码**不能放弃请求**,也不能每 30ms 刷一条日志。真机上验证一次要等 * 到真断线,主机侧把 tick 做成显式量后,1399ms 与 1400ms 的差别就是一行断言。 * 3. GET_SOCK_INT_STATUS 是**整体读即清**,"顺手全量清一遍"会把别的在用 socket 的 - * 门焊死(AGENTS 模块约定 B3 实证坑)。假芯片必须复刻读即清,本文件用调用顺序 + * 门焊死(模块约定 B3 实证坑)。假芯片必须复刻读即清,本文件用调用顺序 * 日志钉住"只读自己这一路"的时序。 * * 覆盖点: diff --git a/test/host/net_pending/net_pending_test.c b/test/host/net_pending/net_pending_test.c index 42d1a3a2..01f7e125 100644 --- a/test/host/net_pending/net_pending_test.c +++ b/test/host/net_pending/net_pending_test.c @@ -18,7 +18,7 @@ * 可控"芯片此刻还有多少字节可读";dbg_log 计数;net_set_errno 记录。 * * 为什么要主机侧单测(而不是只靠台架): - * 1. AGENTS 模块约定写着:net_* 公开 API 的错误码经**任务通知值**回传,因为 net_msg_t + * 1. 模块约定:net_* 公开 API 的错误码经**任务通知值**回传,因为 net_msg_t * 是**按值拷入队列**的,netTask 改的是自己那份副本,调用方永远看不到;也**勿给 * net_msg_t 加回传字段**(加了只会让调用方读到栈垃圾)。这条契约在真机上表现为 * "偶发拿到 0 或正数却不知道为什么",日志无痕;在 PC 上必须把 xTaskNotify 做成 diff --git a/test/host/net_pending/run_unit_test.py b/test/host/net_pending/run_unit_test.py index 91aa6fbb..4e16dd7a 100644 --- a/test/host/net_pending/run_unit_test.py +++ b/test/host/net_pending/run_unit_test.py @@ -29,7 +29,7 @@ 退出码:0=PASS / 1=测试失败 / 2=环境错误。 -设计依据:AGENTS.md 模块约定(错误码经任务通知值回传)、 +设计依据:模块约定(错误码经任务通知值回传,见 docs/网络/网络自愈架构设计.md §4.10)、 docs/网络/Net层阻塞模型架构设计.md、docs/测试说明/单元测试/主机单测覆盖率口径.md §9 创建日期:2026-10-23 """ diff --git a/test/host/net_pending/stub/net_socket.h b/test/host/net_pending/stub/net_socket.h index 5a70dfeb..e56c6f49 100644 --- a/test/host/net_pending/stub/net_socket.h +++ b/test/host/net_pending/stub/net_socket.h @@ -2,7 +2,7 @@ * 模块名称:主机侧单测桩 - net_socket.h(NET 域共享形态,见 net_listener 同名文件) * 模块功能:net_pending.c 需要 net_set_errno() 与 NET_ERR_RETURN_1()(写法照抄真实 * net_socket.h:528/532);socket 状态与错误码常量取**真实** net_types.h。 - * 本模块**不用** net_get_sock——tick 收的是 net_sock_t 表数组(AGENTS 模块 + * 本模块**不用** net_get_sock——tick 收的是 net_sock_t 表数组(模块 * 约定:net_get_sock 对未用槽位返回 NULL,而 tick 必须读 in_use==0 兜底)。 * ⚠ 仅供主机侧单测使用,不参与 MCU 构建。 * 创建日期:2026-10-23 diff --git a/test/host/net_pending/stub/task.h b/test/host/net_pending/stub/task.h index 768f78ba..57e17067 100644 --- a/test/host/net_pending/stub/task.h +++ b/test/host/net_pending/stub/task.h @@ -4,7 +4,7 @@ * 的假件:xTaskNotify 把 (目标句柄, 通知值) 记进日志, * xTaskGetCurrentTaskHandle 返回一个固定的"属主任务"句柄。 * ⚠ 仅供主机侧单测使用,不参与 MCU 构建。 - * 为什么这两个假件是重点:AGENTS 模块约定写着"net_msg_t 是按值拷入队列的, + * 为什么这两个假件是重点:模块约定写着"net_msg_t 是按值拷入队列的, * netTask 改的是自己那份副本,调用方永远看不到 → 错误码必须搭通知值回来", * 还写着"勿给 net_msg_t 加回传字段"。这条契约只有把 xTaskNotify 做成可观测的, * 才能在主机侧被验证(否则"调用方拿到错误码"这件事在 PC 上根本无法发生)。 diff --git a/test/host/net_socket/net_socket_test.c b/test/host/net_socket/net_socket_test.c index fa22c74f..b05aa0cd 100644 --- a/test/host/net_socket/net_socket_test.c +++ b/test/host/net_socket/net_socket_test.c @@ -20,7 +20,7 @@ * recv 快路径与 EOF vs WOULDBLOCK、connect 命令被拒的回滚、accept 的 * closed-with-readable 排空接受、close 的先结算再关芯片。 * - * ⚠ 断言只钉**真实契约**(AGENTS 模块约定 + docs/网络/网络自愈架构设计.md §4.10 + + * ⚠ 断言只钉**真实契约**(docs/网络/网络自愈架构设计.md §4.10 + * 源码注释里的定案编号),不钉假件规则:凡"因为假件这么做所以断言这么做"的一律不写。 * * 入口:int main(void),返回 0=PASS / 1=FAIL。跑法见同目录 run_unit_test.py。 diff --git a/test/host/net_socket/ns_s3_msg.c b/test/host/net_socket/ns_s3_msg.c index 7f0fb7bd..ae38e8b8 100644 --- a/test/host/net_socket/ns_s3_msg.c +++ b/test/host/net_socket/ns_s3_msg.c @@ -2,7 +2,7 @@ * 分片 3:跨上下文消息面(net_process_messages 全分派 + 结果经任务通知值回传) * 前置:net_socket_test.c 已纳入生产源与假内核/假芯片/兄弟模块桩(同一 TU)。 * - * 这一片是整套里最值钱的部分,钉的是 AGENTS 模块约定的两条硬契约: + * 这一片是整套里最值钱的部分,钉的是模块约定的两条硬契约: * A.「所有 net_* socket 操作经 netMsgQueue 在 netTask 串行执行」 * B.「net_* 公开 API 的错误码经任务通知值回传:net_msg_t 是按值拷入队列的, * netTask 改的是自己那份副本,调用方永远看不到 → 错误码搭 xTaskNotify 通知值回来; diff --git a/test/host/net_socket/ns_s4_state.c b/test/host/net_socket/ns_s4_state.c index a2c64e88..d4b75536 100644 --- a/test/host/net_socket/ns_s4_state.c +++ b/test/host/net_socket/ns_s4_state.c @@ -1,7 +1,7 @@ /* * 分片 4:net_poll 中断分派、监听/可读闸门、close 与 drop_conn 的拆除序列 * - * 这一片钉的是 AGENTS 模块约定里**没有文档就无法发现**的那条芯片约束: + * 这一片钉的是模块约定里**没有文档就无法发现**的那条芯片约束: * 所有 CH395F 中断在 net_poll() 内经 GET_GLOB_INT_STATUS 集中读取并清除,不得在 * ISR 或其他地方单独处理。全局寄存器整体读即清、芯片无按位清除手段,而 net_poll * 只在全局位为 1 时才读该 Socket 的 SINT → 顺手全量清一遍等于把别的在用 Socket 的 diff --git a/test/host/net_socket/ns_s7_udp.c b/test/host/net_socket/ns_s7_udp.c index a5f0c2a4..fd552bf7 100644 --- a/test/host/net_socket/ns_s7_udp.c +++ b/test/host/net_socket/ns_s7_udp.c @@ -12,7 +12,7 @@ * - 本分片只测**队列化之后**新增或变化的决策:出参经 per-fd 槽回传、挂起 recv、 * 截断排空、模式切换、以及"任何一条出口都必须通知调用方"。 * - * ⚠ 断言只钉真实契约(AGENTS 模块约定 + docs/芯片手册/CH395F.md §9.2.4 + + * ⚠ 断言只钉真实契约(docs/网络/网络自愈架构设计.md §4.10 + docs/芯片手册/CH395F.md §9.2.4 + * docs/问题记录/CH395F_Trap_Records.md),不钉假件规则。 * * 创建日期:2026-11-03 @@ -506,7 +506,7 @@ static void tc_udp8_pending_cancel(void) reset_all(); } -/* ================= UDP-9 出参互斥与泄漏(AGENTS 禁止的回传字段,本改造的替代面) ================= */ +/* ================= UDP-9 出参互斥与泄漏(禁止的回传字段,本改造的替代面) ================= */ static void tc_udp9_outparam_slot(void) { diff --git a/test/host/net_socket/run_unit_test.py b/test/host/net_socket/run_unit_test.py index d1f9691e..6c95a181 100644 --- a/test/host/net_socket/run_unit_test.py +++ b/test/host/net_socket/run_unit_test.py @@ -17,7 +17,7 @@ 为什么要主机侧单测(而不是只用台架): net_socket.c 是本产品**唯一的 SPI 串行化点**:所有 net_* 公开 API 把请求按值拷进 消息队列,由 netTask 串行执行,结果只能经 xTaskNotify 的 32 位通知值回来 - (net_msg_t 是按值入队的,netTask 改自己那份副本,调用方永远看不到——AGENTS + (net_msg_t 是按值入队的,netTask 改自己那份副本,调用方永远看不到——模块 模块约定明写"勿给 net_msg_t 加回传字段")。这条链的正确性取决于两个任务的 交错时序,真机上"通知丢了"表现为永久挂死并被看门狗复位,日志里只剩一条 [ERR];而错误码本身还按任务隔离,跨任务覆写只会让排障读到别人的码。 diff --git a/test/host/net_socket/stub/dbg_log.h b/test/host/net_socket/stub/dbg_log.h index b49c7d4e..9f66e82a 100644 --- a/test/host/net_socket/stub/dbg_log.h +++ b/test/host/net_socket/stub/dbg_log.h @@ -4,7 +4,8 @@ * 同名文件)。net_socket.c 有 11 条 DBG_ERROR + 6 条 DBG_INFO,其中 * 「短写必留痕」「版本门控拒置 bit3 必 [ERR]」「open 失败必 [ERR]」 * 「close 复位没成也放行仍要留痕」这四条本身就是可断言的契约。 - * 本模块在 include 本头之前把 DBG_LINE_BUF_MAX 设为 128U(AGENTS 深调用链纪律), + * 本模块在 include 本头之前把 DBG_LINE_BUF_MAX 设为 128U(深调用链纪律 → + * docs/子系统设计/控制台单写者日志设计.md §7.1), * 桩不关心缓冲大小,只数条数。 * ⚠ 仅供主机侧单测使用,不参与 MCU 构建。 * 创建日期:2026-10-24 diff --git a/tools/arch_diagram/gen_arch_endtoend_svg.py b/tools/arch_diagram/gen_arch_endtoend_svg.py index 2019cd4c..04375706 100644 --- a/tools/arch_diagram/gen_arch_endtoend_svg.py +++ b/tools/arch_diagram/gen_arch_endtoend_svg.py @@ -90,7 +90,7 @@ GRID_LINE = "#cbd5e1" TITLE = "STM32F407ZGTx 工业 DTU 平台 · 端到端链路总览" SUBTITLE = ("一个电气量从引脚到 104 报文 / 显存 / 记录文件穿过的框,与「谁在什么时候被谁唤醒」;" "分层归属与层内模块清单见 项目架构总览.svg,本图只画链路与握手") -FOOTNOTE = ("口径:AGENTS.md「数据主线」+ docs/架构设计/项目架构总览.md(行号级证据在那份文档与代码里)。" +FOOTNOTE = ("口径:docs/架构设计/项目架构总览.md §1「全景分层架构」(含 §1.3 端到端链路鸟瞰;行号级证据在那份文档与代码里)。" "RS-485 采集未接线:rs485_task 有实现但不建任务,接线后数据进语义取数层;" "其余行为条件(未标定闭锁 / 就绪位 NoClear / CH395F 单连接 / V0.1 双转换器无共同采样触发)见正文," "它们只改变判据与端口、不改变本图的框与连线。") diff --git a/tools/menu_gen/README.md b/tools/menu_gen/README.md index a98a5182..505b790f 100644 --- a/tools/menu_gen/README.md +++ b/tools/menu_gen/README.md @@ -19,7 +19,7 @@ ## ⚠️ 注意 - 生成产物**勿手改**(会被下次生成覆盖);要改菜单结构改**定义源**后重跑 -- 中文字符串字面量须为**纯 ASCII 安全**(见 `AGENTS.md` 编码铁律)——生成后的文案 +- 中文字符串字面量须为**纯 ASCII 安全**(见 `docs/文档规范.md` §2 编码铁律)——生成后的文案 如需汉字,须配套重跑字体生成(`tools/font_gen/`) ## 相关文档 diff --git a/tools/menu_gen/gen_menu.py b/tools/menu_gen/gen_menu.py index 9bd3be20..d4081686 100644 --- a/tools/menu_gen/gen_menu.py +++ b/tools/menu_gen/gen_menu.py @@ -605,7 +605,7 @@ def sync_registration(filenames): """把 UI 目录下的 .c 文件名补进 uvprojx 与 CMakeLists 的显式列表,返回实际插入项。 只做定点插入、不重排不改写其余内容:uvprojx 由 UV4 维护,任何无关改动都会污染 - diff(AGENTS 铁律"UV4 抖动不入库");已存在则不动(幂等,重复跑不产生 diff)。 + diff("UV4 抖动不入库"铁律);已存在则不动(幂等,重复跑不产生 diff)。 """ inserted = [] diff --git a/tools/netlist_semantics/gen_kb.py b/tools/netlist_semantics/gen_kb.py index 8f403927..97306a81 100644 --- a/tools/netlist_semantics/gen_kb.py +++ b/tools/netlist_semantics/gen_kb.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- """gen_kb.py - 生成 pinout_kb.json(V0.0 网表知识库)。 运行: & '.venv\\Scripts\\python.exe' tools/netlist_semantics/gen_kb.py -数据来源:V0.0.tel 实测 + docs/芯片手册 + AGENTS.md 硬件引脚表。 +数据来源:V0.0.tel 实测 + docs/芯片手册 + docs/架构设计/硬件规格与能力边界.md §2 引脚表。 """ import json import os @@ -232,7 +232,7 @@ KB = { "SWCLK": {"func": "SWD 时钟", "note": "U17→H2"}, "SWDIO": {"func": "SWD 数据", "note": "U17↔H2"}, "NRST": {"func": "复位", "note": "U17/U1,经 R40/SW1"}, - "LED1": {"func": "板级 LED1", "gpio": "PC4", "note": "低有效;顺序按 AGENTS.md 待核"}, + "LED1": {"func": "板级 LED1", "gpio": "PC4", "note": "低有效;顺序待核(见 docs/硬件平台/V0.0_网表详细分析报告.md)"}, "LED2": {"func": "板级 LED2", "gpio": "PC5", "note": "低有效"}, "LED3": {"func": "板级 LED3", "gpio": "PB1", "note": "低有效"}, "LED4": {"func": "板级 LED4", "gpio": "PB2", "note": "低有效"}, diff --git a/tools/netlist_semantics/pinout_kb.json b/tools/netlist_semantics/pinout_kb.json index d720b3ab..3a1b399f 100644 --- a/tools/netlist_semantics/pinout_kb.json +++ b/tools/netlist_semantics/pinout_kb.json @@ -863,7 +863,7 @@ "LED1": { "func": "板级 LED1", "gpio": "PC4", - "note": "低有效;顺序按 AGENTS.md 待核" + "note": "低有效;顺序待核(见 docs/硬件平台/V0.0_网表详细分析报告.md)" }, "LED2": { "func": "板级 LED2",