From e4981aa2f6fb3e2ea25bd91879e1864e8046da72 Mon Sep 17 00:00:00 2001 From: Wanderingss <1624155937@qq.com> Date: Mon, 16 Nov 2026 19:38:27 +0800 Subject: [PATCH] refactor(docs): point entry-file references at their new homes AGENTS.md stopped being the store of record for build steps, Python env, hardware pins, doc conventions, log cost and task ownership. Those facts already live in docs, skills and role files; the entry file now only points at them. This commit moves every reference that used to name the entry file to the authoritative landing point, so a reader who follows a link arrives at the fact instead of at a sentence that no longer exists. What changed is links and prose, not behaviour. Code, scripts and tests only have comment and docstring lines touched; the only non-comment edit in the whole changeset is one note string inside the generated pin table JSON, and its generator was changed in the same step so the two stay byte-identical. New landing points created before the references were retargeted: - The console single-writer log design doc, section 7.1, is now the single authority for log cost: about 90 B flash and 216 B stack per DBG_ line, and the rule that deep call chains must predefine DBG_LINE_BUF_MAX. It also carries the full list of the twelve translation units that have tightened it, plus the grep command that decides the truth if the list and the code ever disagree. - The document writing standard, section 2, now holds the BOM list. - keil-build skill gains an exit code table: 0 success, 1 build failure, 2 BuildEnvError, 3 usage, 4 build lock held. This corrects a belief that was never actually written down anywhere: exit 2 does not simply mean environment error, argparse also exits 2 and the wrapper script was remapped so the two no longer collide. Regenerated and checked byte for byte: - The end-to-end architecture SVG in docs/images from its generator. - tools/netlist_semantics/pinout_kb.json from gen_kb.py. Both are idempotent; running the generators again produces no diff. Deliberately not touched, because machines read them: - scripts/check_bom_drift.py joins every line containing BOM and asserts four paths are present, so the entry file BOM line must stay one line. - scripts/gen_task_table.py reads the TASK_TABLE anchors directly. - scripts/rename_maps and scripts/archive keep their historical wording; they describe what happened, not what is true now. Verified: doc links report the same six pre-existing findings as the base commit and no new ones, generated-fresh passes, bom drift is clean across 101 files, and AGENTS.md itself is unchanged in this commit. --- .dsh/skills/draw-diagram/SKILL.md | 4 +- .dsh/skills/font-regen/SKILL.md | 2 +- .../id-family-semantic-migration/SKILL.md | 2 +- .../reference/steps-chinese-prefix-family.md | 2 +- .dsh/skills/keil-build/SKILL.md | 30 ++++++++++-- .../reference/executor-shell-forms.md | 6 +-- .dsh/skills/keil-build/scripts/keil_build.py | 6 +-- .dsh/skills/mem-budget/SKILL.md | 2 +- .../serial-assistant/scripts/serial_tool.py | 6 +-- .dsh/skills/serial-boot-test/SKILL.md | 4 +- .dsh/skills/stale-doc-count-sweep/SKILL.md | 4 +- .../reference/pitfalls.md | 4 +- .../stale-doc-count-sweep/reference/steps.md | 4 +- .dsh/skills/task-worktree/SKILL.md | 4 +- .../reference/dsh-plugin-bridge.md | 4 +- .dsh/skills/ui-verify/SKILL.md | 2 +- .gitea/workflows/ci.yml | 6 +-- .gitignore | 2 +- App/README.md | 2 +- App/algo/adc_cal.h | 4 +- App/algo/adc_input.c | 5 +- App/app/app_main.c | 4 +- App/app/ui_data_feed.c | 4 +- App/log/README.md | 2 +- App/log/sys_log_mcu.c | 2 +- App/protocol/iec104/iec104_comm.c | 4 +- App/task/README.md | 2 +- App/task/adc_task.c | 5 +- App/task/adc_task.h | 3 +- App/task/protect_task.h | 2 +- Drivers/BSP/NET/net_socket.c | 8 ++-- Drivers/BSP/NET/net_socket.h | 7 +-- Drivers/BSP/NET/net_types.h | 2 +- Drivers/BSP/NET/net_udp.h | 2 +- Drivers/BSP/README.md | 2 +- Drivers/BSP/TPAFE5160/README.md | 2 +- Drivers/BSP/UI/ui_data.h | 2 +- Drivers/BSP/app_assert.h | 6 +-- Drivers/BSP/bsp_err.h | 2 +- MDK-ARM/README.md | 4 +- README.md | 4 +- Src/freertos.c | 2 +- docs/CI/远程CI完整指南.md | 2 +- docs/README.md | 2 +- docs/UI设计/LVGL模拟器部署与使用说明.md | 2 +- docs/UI设计/UI_中文字体生成与配置.md | 2 +- docs/UI设计/UI_界面制作流程.md | 6 +-- docs/UI设计/UI_自动化测试流程.md | 4 +- docs/UI设计/UI_设计架构.md | 2 +- docs/UI设计/内容页架构.md | 2 +- docs/images/架构总览_端到端链路.svg | 4 +- docs/产品需求/产品需求设计文档.md | 4 +- docs/代码规范/pre-commit使用说明.md | 8 ++-- docs/内存管理/RAM使用分析与优化方案.md | 8 ++-- docs/内存管理/内存内容分配策略.md | 8 ++-- docs/内存管理/存储栈RAM优化调研.md | 2 +- docs/子系统设计/ADC采样节拍设计.md | 4 +- docs/子系统设计/IEC104上行设计说明.md | 2 +- docs/子系统设计/控制台单写者日志设计.md | 47 ++++++++++++++++--- docs/子系统设计/故障录波设计说明.md | 2 +- docs/子系统设计/看门狗设计说明.md | 10 ++-- docs/文档规范.md | 5 +- docs/架构设计/图形绘制流程.md | 2 +- docs/架构设计/引用关系图说明.md | 2 +- docs/架构设计/项目启动顺序管理.md | 6 +-- docs/架构设计/项目架构总览.md | 4 +- docs/测试说明/专项验证/ADC前端注入验证流程.md | 4 +- docs/测试说明/专项验证/模拟器差距清单.md | 2 +- docs/测试说明/专项验证/链路延迟测试说明.md | 2 +- .../单元测试/ADC输入层单元测试说明.md | 2 +- docs/测试说明/单元测试/主机单测覆盖率口径.md | 2 +- docs/测试说明/单元测试/卷锁单元测试说明.md | 2 +- .../测试说明/单元测试/开机账本单元测试说明.md | 2 +- .../测试说明/单元测试/时间同步单元测试说明.md | 2 +- docs/测试说明/单元测试/相量层单元测试说明.md | 2 +- .../测试说明/单元测试/系统时钟单元测试说明.md | 2 +- .../测试说明/单元测试/配置文件单元测试说明.md | 2 +- docs/测试说明/板级测试/FTP_Test_Guide.md | 4 +- docs/测试说明/板级测试/实机测试实施指南.md | 2 +- docs/测试说明/流程与规范/测试开发标准流程.md | 2 +- docs/测试说明/流程与规范/自动化测试流程.md | 2 +- docs/测试说明/测试工具/串口助手使用指南.md | 2 +- docs/测试说明/测试工具/串口助手设计说明.md | 2 +- docs/环境与部署/并行任务工作树方案.md | 2 +- docs/环境与部署/项目部署环境要求.md | 2 +- docs/硬件平台/V0.0_网表详细分析报告.md | 2 +- docs/硬件平台/开入开出实施说明.md | 2 +- docs/算法/继电保护功能复现规划.md | 2 +- docs/算法/采样有效性校验设计说明.md | 6 +-- docs/网络/BSD_Socket_API_函数调用关系.md | 4 +- docs/门禁说明/bom-guard.md | 2 +- docs/门禁说明/check-yaml.md | 2 +- docs/门禁说明/cubemx-survival.md | 4 +- docs/门禁说明/gitlint.md | 2 +- docs/门禁说明/host-unit-tests.md | 2 +- docs/门禁说明/layer-deps.md | 2 +- docs/门禁说明/mermaid-syntax.md | 2 +- docs/门禁说明/no-mojibake.md | 6 +-- docs/门禁说明/skill-size.md | 2 +- requirements.txt | 2 +- scripts/archive/id_gate/id_aliases.json | 2 +- scripts/archive/id_gate/id_registry.json | 2 +- scripts/check_bom_drift.py | 2 +- scripts/check_coding_standard.py | 6 +-- scripts/check_cubemx_survival.py | 2 +- scripts/check_generated_fresh.py | 2 +- scripts/check_layer_deps.py | 2 +- scripts/check_size_gate.py | 4 +- scripts/ci_gitlint_range.ps1 | 4 +- simulator/README.md | 4 +- simulator/tests/regen_ref_png.py | 2 +- test/board/README.md | 4 +- test/board/net_latency_test.h | 2 +- test/board/storage_test_task.c | 2 +- test/host/README.md | 2 +- test/host/common/ch395f_fake.h | 4 +- test/host/iec104_serv/run_unit_test.py | 2 +- test/host/net_events/stub/dbg_log.h | 3 +- test/host/net_listener/net_listener_test.c | 2 +- test/host/net_pending/net_pending_test.c | 2 +- test/host/net_pending/run_unit_test.py | 2 +- test/host/net_pending/stub/net_socket.h | 2 +- test/host/net_pending/stub/task.h | 2 +- test/host/net_socket/net_socket_test.c | 2 +- test/host/net_socket/ns_s3_msg.c | 2 +- test/host/net_socket/ns_s4_state.c | 2 +- test/host/net_socket/ns_s7_udp.c | 4 +- test/host/net_socket/run_unit_test.py | 2 +- test/host/net_socket/stub/dbg_log.h | 3 +- tools/arch_diagram/gen_arch_endtoend_svg.py | 2 +- tools/menu_gen/README.md | 2 +- tools/menu_gen/gen_menu.py | 2 +- tools/netlist_semantics/gen_kb.py | 4 +- tools/netlist_semantics/pinout_kb.json | 2 +- 134 files changed, 276 insertions(+), 212 deletions(-) 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",