STM32F4-Base/AGENTS.md

STM32F4-Base

工业级嵌入式 DTU 平台固件：STM32F407ZGTx @168MHz，集成以太网（CH395F）、SPI NAND 存储（GD5F）、电气量采集（TPAFE5160 + 片内 ADC）、RS-485、FTP 文件服务，自带远程显示（UI 推流）、墙钟对时、看门狗自恢复、运行/自检记录——既是可独立部署的现场设备，也是可复用的平台底座（保护测控等后续产品在此底座上补齐）。产品基线 → docs/产品需求/产品需求设计文档.md §2.1。

仅 Keil MDK-ARM v5 (ARMCC, C99) 工具链；FreeRTOS V10.3.1 / CMSIS-RTOS2；192KB SRAM / 1MB Flash。

任何代码修改后必须先 @build 验证（0 错误 0 警告）再提交；硬件闭环用 @test。

本文件 = agent 入口：宏观概况 + 每次都在场的铁律在这里，细节在 docs/ 与 skills（文末索引）。同一事实只在一处详述（docs/文档规范.md 同此要求）。

项目概况

现状一句话：平台能力（网络 / 存储 / 时间 / UI / 日志 / 看门狗 / FTP / 配置）已实现并台架验收；采集主线已闭环到业务消费者（语义取数与有效性→全周傅氏相量→测频与遥测快照→保护判据 protectTask→104 遥信/遥测+UI，B5/批 2）；⚠ 保护判据现处于「未标定闭锁」态——产品构建下 adc_cal_flags() 的 ADC_CAL_F_VALID 未置位，protect_task.c:98 直接停走判据，等两点标定写入 [adc_cal] valid 后自动解卡（用户裁定 2026-10-25：保持闭锁，不用万用表走捷径）；RS-485 采集尚未接线（B2 按用户决策冻结，见 docs/任务规划/暂缓-RS485.md）——当前最大功能缺口，接线节奏受 RS-485 接线门禁约束（见「平台约束」）。

数据主线（能力视角；分层图与跨层依赖表 → docs/架构设计/项目架构总览.md）：

• 采集：TPAFE5160（计量级 8 路，并行总线）+ 片内 ADC1（9 路，DMA）→ TIM3 1 kHz 节拍 + 原子快照 → adcTask → 语义取数与有效性校验 → 全周傅氏相量 → 测频与遥测快照（meas 200 ms 双区，104 与 UI 共用同一份上游，批 2）+ 保护判据（protectTask 20 ms 判据节拍，B5）→ 104 遥信/遥测上送
• 存储：GD5F SPI NAND → dhara FTL → FatFs → /log 运行与自检记录、/config.ini 配置、FTP 根目录
• 网络：CH395F → netTask 串行 socket 栈 → FTP(21) / 对时(8888) / RemoDispBus 远程显示(7003) / IEC 60870-5-104 上行(2404)
• 人机：LVGL 160×160 单色菜单（uiTask），与 PC 模拟器同一份 UI 源码，远端可看图 + 注键

目录地图（只列顶层——稳定边界；细结构自己 ls，别背路径；仓库根不放一次性产物——提交信息草稿 / 临时改写脚本 / 门禁输出与日志一律进 ci-artifacts/（已忽略，口径见 .gitignore 尾注），根目录只留工程配置与两份生成器输入 ui_menu_tree.txt、ui_cn_chars.txt）：

目录	职责	可改性
Src/ Inc/	CubeMX 生成（外设初始化 / 中断向量 / freertos.c 任务表）	只写 USER CODE 区
App/	应用层：app/ 启动与就绪事件 · task/ 任务编排 · algo/ 采集与算法分层（语义取数与有效性 → 保护判据） · cfg/ 配置引擎 · log/ 日志 · fs/ 卷锁 · sync/ 对时 · util/ 工具	手写
Drivers/BSP/	手写芯片驱动与服务：TPAFE5160 CH395F NET(socket 栈+lftpd) NETCFG GD5F2GQ5UE SD2506 RS485 UI(LVGL 界面)	手写
Drivers/STM32F4xx_HAL_Driver/ Drivers/CMSIS/ Middlewares/	ST HAL / CMSIS / FreeRTOS	第三方，只读
Lib/	第三方库：lvgl FatFs dhara + lv_conf.h（MCU 端）	只读（本地补丁须有文档登记，如 LVGL I1 补丁）
MDK-ARM/	Keil 工程（.uvprojx、scatter、下载脚本）	工程配置手改；UV4 抖动不入库
simulator/	LVGL PC 模拟器（CMake + SDL2），与固件同标准受检	手写 → lvgl-simulator skill
test/	board/ 板级套件 · host/ 主机侧单测（提交门禁实跑）	手写
scripts/ tools/	门禁与报告脚本（check_* / gen_* / ci_local.py）· 配图/字体/引用图生成器	手写
docs/	全量设计 / 测试 / 规范文档（人类索引 docs/README.md）	手写，doc-links 门禁
.dsh/skills/ .gitea/ .serialtest/	agent skills（子域知识入口）· CI 工作流 · 串口/烧录配置	手写

分层边界：上层只依赖相邻下层（业务 → UI/基础服务 → 中间件 → BSP 驱动 → HAL/RTOS → 硬件，单向）；新算法模块进 App/algo/，勿塞 App/task/（任务只做消费/编排）；新 .c 必须双端注册（new-source-file skill）。

架构要点

Src/main.c（CubeMX 初始化）→ app_main_init → osKernelStart → 9 任务（osKernelStart 之前全是内核启动前代码：禁调任何内核 API，见「平台约束」）

• app_main_init（时间子系统优先，使后续日志带时间戳）：sd2506_init → sys_clock_init → rs485_init → gd5f2gq5ue_init → tpafe5160_init → adc_input_init（语义取数与有效性层）→ SD2506 诊断 → 启动 TIM3 1 kHz 采样节拍
• 就绪屏障（App/app/sys_events.h Event Flags，取代魔法延时）：SYS_EVT_NET_READY / STORAGE_READY / FTP_READY / TIMESYNC_READY；消费者用 osEventFlagsWait 阻塞等待（就绪位 osFlagsNoClear）
• netTask：net_stack_bring_up（配置已由 defaultTask 在屏障前加载，本任务只读 RAM 副本）→ 置 NET_READY → 循环 net_poll + net_process_messages；消费 SYS_EVT_NET_RECONFIG → 按网络代次号重建监听（新 IP 免重启生效）
• defaultTask：f_mount forced（无卷自动 f_mkfs；挂载后卷健康探针，FAT 区陈旧时自愈重格式化）→ 加载网络配置 → STORAGE_READY → LED 闪烁；同时是 syslog（/log/run.log·selftest.log，定长 64B 记录）的唯一写者与配置引擎属主（netTask/uiTask 不得直接触碰配置引擎）
• adcTask：纯消费者——每拍 adc_input_poll()（TPAFE 原子快照 + 消费一帧 STM32 ADC1 DMA 双缓冲），只取数不做保护运算；节拍与唤醒同源（TIM3 ISR 内触发 CONVST + 同一更新事件经 TRGO 触发 ADC1，并调 adc_tick_irq_notify() 置位，任务 osThreadFlagsWait 等唤醒）。⚠ ISR 侧只能走 adc_tick_irq_notify()（内含"消费者就绪"门，TIM3 比调度器早 ≈100 ms 启动）；手写于 Src/freertos.c 的 USER CODE 区，纳入 IWDG required_mask（TASK_WD_ADC）
• 采集与算法层（语义取数与有效性/全周傅氏相量/保护判据）落在 App/algo/：adc_input/adc_health = 语义取数与有效性，sample_ring/phasor = 全周傅氏相量，freq = 测频与遥测快照（B8，自适应窗），prot_set/prot_elm = 保护判据。板端消费者 = protectTask（B5，2026-10-12）：20 ms 节拍 prot_elm_run() + 自检失败闭锁（采样故障闭锁）+ 定值校验和巡检；跨上下文复归（104 YK11）经 prot_elm_request_reset() 落请求。纳入 IWDG required_mask（TASK_WD_PROTECT，产品 0x1F7）。→ docs/算法/采集与算法层设计说明.md（设计与判据）、App/algo/README.md（目录索引）
• 全景 → docs/架构设计/项目架构总览.md；启动时序与内核前模式 → docs/架构设计/项目启动顺序管理.md

Task	栈 (words)	优先级
defaultTask	1280	Normal
netTask	960	Normal
ftpTask	1024	Normal
testTask	2048	BelowNormal
uiTask	4096	BelowNormal
timeSyncTask	640	Normal
adcTask	640	AboveNormal
iec104Task	640	Normal
protectTask	512	Normal

（实际值以 Src/freertos.c 为准，本表由 scripts/gen_task_table.py 生成、task-table 钩子校验；testTask 仅在启用测试套件时创建。FreeRTOS 堆已迁 CCM，任务栈不占 SRAM；每次抬栈的实测最坏链与余量台账 → docs/内存管理/RAM使用分析与优化方案.md §2.3（任务栈配置与实测峰值）与 §4.0.6（静态最坏链与判定）、docs/内存管理/内存内容分配策略.md §6（容量台账））

铁律：源码编辑与编码

• 改代码只用 Edit 工具（精确子串替换 / replaceAll）；绝不用 Get-Content/Set-Content/cmd 重写含中文的文件——整文件重写按系统默认编码重解码 → U+FFFD 乱码且不可逆
• Edit 会静默剥掉文件原有的 UTF-8 BOM：带 BOM 的文件（Drivers/BSP/UI/*、App/task/ui_task.c、App/cfg/cfg_file.c、Lib/lv_conf.h）被 Edit 后丢 BOM → ARMCC 改按 CP936 解码 → 中文字面量报 #870-D: invalid multibyte character sequence（只有重编译该文件才暴露，历史"0 警告"不代表安全）。改完须核对 BOM 并按原样补回（只前缀 3 字节 EF BB BF，勿整文件重写）。已机械化：bom-guard 钩子（scripts/check_bom_drift.py：HEAD 有 BOM 而工作区没有即拦；上面这份名单与钩子 files 正则、脚本内 BOM_LIST 三处互指，脚本每次跑都核一次，单独改一处会在别人的提交里被拦下）
• 字符串字面量必须纯 ASCII：无 BOM 文件里奇数个汉字会吞掉结束引号（偶数侥幸通过）→ 中文只写注释
• 注释里写作用域/路径别写星号形态：Drivers/BSP/UI/** 里的 /* 会被 ARMCC 当第二次注释起点（诊断 9-D），C 块注释不嵌套；且每个包含者各刷一行、只在重编译那个 TU 时才暴露。写全目录（Drivers/BSP/UI/）或用尖括号（<Drivers/BSP/UI/ui_x.c>）——已机械化 nested-comment 钩子，存量 2 处基线只减不增 → docs/门禁说明/nested-comment.md
• 怀疑乱码先统计 EF BF BD 字节数（勿信终端/Read 渲染）；不要急著 git checkout（会丢弃全部未提交工作）——用 Edit 只修坏行
• 行尾由 .gitattributes 写死（* text=auto eol=lf；*.bat/*.cmd 强制 CRLF）：不依赖 core.autocrlf、不要把工作区文件改回 CRLF → 权威口径 docs/文档规范.md §2
• 代码规范 V1.0：小写下划线命名（g_/s_/p_/a_ 前缀）、头文件保护宏 XXX_H（禁 __ 前缀）、常量在右、文件头模块注释块 → docs/代码规范/
• 手改 .dsh/skills/**/SKILL.md 有 65536 字节写侧硬上限（dsh-mnemon 插件 validateSkillContent() 只在写侧校验，加载侧不查）：超限的技能照常 skill() 可读、照常进技能目录，但自进化每次「生成草案」都在落盘那一步被拒 → 建议永久卡在「生成中」、界面只剩转圈、连「忽略」都点不动（实测 2026-10-29 两个技能同日各卡一次，第二次的文件 72,601 字节）。加内容前先看体积：node "$HOME/.dsh/scripts/mnemon-skill-ledger-doctor.mjs" --root .（只报不改）；正文控制在 ~48 KB（≥75% doctor 就报 CLOSE）。新增的深规程写进同目录 reference/<篇名>.md，正文只留可执行判据的摘要 + 指针，且不重排既有步骤号。已卡死的取证与自愈 → mnemon-skill-ledger-stuck-repair skill。已机械化：skill-size 钩子（scripts/check_skill_size.py，纯标准库；--selftest 五形态、--root 可指到用户级 ~/.dsh/skills 手工量）

构建与验证

• 门禁时机（用户裁定 2026-10-13）：@build / scripts/ci_local.py / check_doc_links.py 只在准备提交时跑（用户让 commit 后统一跑一遍），不是每次中间改动后都跑——多步改动期间直接改即可，验证集中在提交门禁；@test 硬件闭环仍按任务需要跑
• @build / @test / @task 都是本仓库的文档别名，不是 shell 命令（2026-10-30 实测：bash 里直接敲 @task / @build 是 command not found，dsh task 会被解析成 profile 名报错）——下面 = 后的命令行才是可执行形态（PowerShell 形态，bash 下路径正斜杠）；DSH 会话显式调用 skill 用 /keil-build、/serial-boot-test、/task-worktree
• @build = & '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py（仓库根执行）。退出码 0=PASS / 1=构建失败 / 2=环境错误（UV4/工程/档案）/ 3=用法 / 4=build 锁被占用；日志 MDK-ARM/build_log.txt；换机必设 DTU_KEIL_UV4 → 细节 keil-build skill + docs/环境与部署/本地工具路径环境变量方案.md
• @test = & '.venv\Scripts\python.exe' .dsh\skills\serial-boot-test\scripts\run_boot_test.py：开串口+清日志 → 烧录（固件身份戳保证烧进去的就是这份构建、回读校验）→ wait-idle → 采日志 → 标记校验（含启动锚点计数）。退出码 0=PASS / 1=FAIL / 2=采集或烧录错误 / 3=用法；戳提取规则、锚点计数判据与按模块定制标记见 docs/测试说明/流程与规范/自动化测试流程.md
• Forbidden 标记含 [ERR]：四个 Fault 的崩溃日志都以 [ERR] 开头 → 出现 Fault 即本次不通过（刻意）
• 烧录必须 -Rst -Run（stlink-flash skill 的 flash）：裸 -P 会报 Programming Complete，但目标核处于死循环/异常时写入并不落地（"反复重下载、芯片一直是旧镜像、二分法失效"的根因）。烧后必须回读校验（stlink_flash.py cmp = -CmpFile，No difference found 才算真正写入）；⚠ -CmpFile 连接时会复位目标 → 必须排在采日志之后 → docs/测试说明/测试工具/ST-LINK_CLI_复位使用说明.md
• ⚠️ 旧绝对路径 D:\Code\DTU 程序\... 出现即失效（仓库已搬迁），一律改用仓库相对路径

Python 环境

• 统一入口 & '.venv\Scripts\python.exe'（3.12，fontTools/Pillow 已装）；PATH 上的 python 是 msys64 的，不要用它跑依赖第三方库的脚本；纯标准库脚本任意 python3 均可
• ⚠ 钩子 entry 的裸 python 不等于 .venv：2026-10-26 真实提交实测 pre-commit 把它解析成机器级解释器（无 fontTools）→ 字体链生成器报 No module named fontTools、generated-fresh 假红（同族第二次发作见 scripts/ci_local.py 文件头 2026-10-11「静态门禁全灭」）。凡依赖第三方库的门禁脚本，一律在脚本内自己按「显式 var > 当前解释器 > 仓库 .venv > PATH」解析并探针校验（装了 pre-commit ≠ 装了 fontTools），但别把 entry 写死成某台机器的绝对路径（那等于把门禁绑死在一台机器上）→ docs/门禁说明/generated-fresh.md §4
• 重建/换机：<本机任一 python ≥3.10> -m venv .venv + pip install -r requirements.txt（含 pre-commit；DTU_PRECOMMIT_PYTHON 可指向别的装了 pre-commit 的解释器）；requirements.txt 必须纯 ASCII（Windows 下 pip 按 GBK 代码页解码）

提交门禁（pre-commit）

• 任一失败即拦截，共 52 个钩子（口径 = YAML 解析后的 hook 条目数：自查命令与「声明 / 文档 / 实跑」三数同源核对见 docs/门禁说明/README.md §2 首条——⚠ 直接 grep 配置里的声明行会多算一条注释掉的候选钩子（比口径多 1），不是口径；配置注释里也别复述那个 grep 字面量，它会让文本计数再虚高 1（2026-10-27 实测踩过）；加一条钩子就同批改 AGENTS 与门禁索引两处计数。2026-10-25 道E 连加 bom-guard / setview-check / uinav-selftest 三条，2026-10-26 加 generated-fresh 一条，2026-10-27 加 nested-comment 一条；2026-10-28 加 id-check-new 一条并同批退役 id-check（口径 52 → 51：编号门禁换牙——新的只查新增行、零语料，旧的八项全库校验连语料一起移入 scripts/archive/id_gate/，手工普查与恢复机器面见 docs/编号规范.md §8.5）；2026-10-29 加 skill-size 一条（51 → 52），同日按用户裁定退役 id-check-new（52 → 51：只查新增行的编号门禁整体退场，脚本与白名单一起移入 scripts/archive/id_gate/，编号形态此后无机器面，留档 docs/门禁说明/id-check-new.md）；2026-10-30 加 mermaid-syntax 一条（51 → 52：mermaid 围栏内确定性语法——坏图此前只能靠肉眼在渲染端发现，实证见专篇）；每种门禁一篇详解（查什么 / 拦下过什么真事 / 限制与盲区 / 基线口径）→ docs/门禁说明/README.md 索引；通用机制与整体口径 → docs/代码规范/pre-commit使用说明.md）：通用 5 + gitlint + cppcheck / test-cppcheck + no-mojibake + coding-standard + 文档三件套 doc-links / task-table / mem-numbers + lv-conf-sync（两份 lv_conf.h 特性子集一致）+ cubemx-survival + bom-guard / setview-check / uinav-selftest（2026-10-25 道E 那三条：前半句的加钩流水里有它们、逐项枚举里漏了，补上后本行各项相加才等于 51；2026-10-30 又加 mermaid-syntax 后此句的"等于"目标数为 52）+ 主机侧单测 22 根专属钩子（-unit-test 后缀 = 有独立 files: 触发面、需要秒级归因的那个子集；2026-10-25 增补 adc-cal / prot-dim / vol-idle-sync / ui-data / meas / run-par 六根）——这是口径不是缺口：test/host/ 实测 44 套带 run_unit_test.py，其余 22 套（含 test/host/ui_sink 与录波三套）没有专属钩子，但每次 CI / scripts/ci_local.py 都被 test-coverage 总闸全量真跑并守基线回退，失败照样拦，只是归因落在总闸输出上；没有专属钩子 ≠ 没被跑，22 套台账与补钩子的判据 → docs/门禁说明/host-unit-tests.md §6 第 4 条。Lead 裁定 2026-10-27：不补第 23 根——读「这套跑没跑」去看总闸输出，别数钩子（原写「23 个 / 含 ui-sink 七个」是双重错：既把 22 说成 23，又宣称 ui-sink 有钩子——配置历史里 ui-sink-unit-test 从未存在）+ test-coverage（覆盖率总闸：跑全部 44 套并守基线回退；缺 mscoverage 组件时按用户裁定 FAIL、不 skip，2026-10-24）+ test-suite-switch + registration-check（双端注册反向校验 + UI 页面描述符表接线，登记簿条目「rs485_task 白名单缺口」）+ generated-fresh（生成器幂等性：把 tools/menu_gen/gen_menu.py、中文字库链、tools/arch_diagram/gen_*.py 拷进系统临时目录重跑，与工作区逐字节必须一致——钩子只读、不写仓库也不 stash 别人在飞的改动；实证 0f7b5a87 改了模板文字没重跑生成物，接线前实测另有 5 张 docs/images/ 配图已漂 → 钉成只减不增基线，业务生成物零豁免面 → docs/门禁说明/generated-fresh.md）+ nested-comment（块注释嵌套：注释体内再出现 /* 会被 ARMCC 报 9-D，且按包含者数量刷屏、只在重编译该 TU 时才暴露；本仓诱因就是「在注释里写作用域/通配路径」，改法是写全目录或用尖括号 <Drivers/BSP/UI/ui_x.c>；接线当日实扫 403 个 .c/.h，新发 0、存量 2 处（test/host/common/ 两份假件头）钉只减不增基线 → docs/门禁说明/nested-comment.md）+ skill-size（SKILL.md 不超插件写侧上限 65536 字节：dsh-mnemon 只在写侧校验、加载侧不查，超限技能照常可读却每次「生成草案」被拒、永久卡在「生成中」；另查 reference/ 指针悬空与 BOM → docs/门禁说明/skill-size.md）+ mermaid-syntax（mermaid 围栏语法预检：```mermaid 块里只查「错了必渲染失败」三条——图类型头 / -. 后直接跟管道（本坑：屏板链路设计说明 §1 坏图靠肉眼在渲染端发现，期间各文档门禁全绿）/ subgraph 与 sequence 块的 end 计数配对；零语料空基线、docs/芯片手册/ 与 doc-links 同排除面 → docs/门禁说明/mermaid-syntax.md）+ mem-budget（RAM 92% 预算门禁，登记簿条目「缩堆迁 CCM 后半（暂缓）」）+ font-charset（UI 字符集差集检查，防缺字白框）+ ui-golden（UI 像素回归，菜单 8 状态 + 内容页 66 张黄金参考）+ layer-deps（分层方向：Drivers/BSP/** 不得 include App/** 的头；存量 3 条基线只减不增（2026-10-25 记录 reader 注入削掉 UI 记录 3 条边，6→3））+ bsp-err（BSP 错误码与超时命名约定：公开 API 不得拿 HAL_StatusTypeDef/bool 当错误通道、*_TIMEOUT 宏不得取负值、非 void 须写「返回值：」、返回错误码的函数不得裸丢弃返回值（须接住或显式 (void)；实测编译器与 cppcheck 都不报这类，只有这条会响）；约定正文 Drivers/BSP/bsp_err.h，存量基线只减不增（2026-10-23 首清点 19 条 → 已还 18；consume-result 上线又暴露 37 条存量丢弃 → 现 38 条））。提交期实跑 49 根（2026-10-30 起，前值是 48；三根慢钩子让位的裁定 2026-10-28）：cppcheck / test-cppcheck / test-coverage 三根带 stages: [manual]——实测合计 ~165 s = 一次带代码提交耗时的三分之二，提交期只跑快的那些；这三根由远端 CI 强制（.gitea/workflows/ci.yml 的「手动阶段门禁」步，逐根 --hook-stage manual）与 scripts/ci_local.py 的 manual 段，本地手工复跑 python -m pre_commit run --all-files --hook-stage manual <hook-id>（一次只能一个 id）
• 范围 = 项目代码：第三方（Lib/、Middlewares/、CMSIS、HAL、lftpd、dhara、MDK-ARM）排除；cppcheck/coding-standard 另排除 test/，规范检查再排除 CubeMX 生成的 Src//Inc/。simulator/ 已纳入全部钩子（2026-10-11）——生成物只靠 .gitignore 挡，不在 exclude 里写目录名（教训见 docs/代码规范/pre-commit使用说明.md §5.5）
• ⚠ pre-commit 4.x 已移除 always: true（实测对 local 钩子只告警 Unexpected key(s) 并跳过）→ 想"总是跑"的钩子必须让 files: 覆盖到所有会触发它的文件，没有兜底开关
• 改写型钩子（trailing-whitespace + end-of-file-fixer）豁免 CubeMX/Keil 生成文件（配置里 YAML 锚点 &cubemx-generated）；⚠ 只读检查不受影响：cppcheck / 乱码 / cubemx-survival / task-table / mem-numbers 仍覆盖 Src/、Inc/
• 提交信息：标题 ≤100 字符、正文每行 ≤80（.gitlint + gitlint 默认）→ 长说明一律用短标题 + git commit -F <UTF-8 无 BOM 文件> 多行正文（中文长标题极易超限，且 -m 会被终端代码页转码破坏）
• CI（.gitea/workflows/ci.yml）只跑静态门禁 + 主机侧纯逻辑单测，刻意不跑 @build（需 Keil 授权）、不含采集链分层（需真机）。远程 CI 的全部资料（服务端开关 / runner 部署与保活 / workflow / 排障 / 实测坑）集中在 docs/CI/README.md，不放本节——它只跑在本机一台 runner win-stm32-ci 上，其他机器与项目都不涉及。日常改代码的等价自查是 & '.venv\Scripts\python.exe' scripts/ci_local.py（静态门禁 + 提交信息门禁 + 主机侧纯逻辑单测）——runner 不在线也不影响本地门禁，不能因"已配 CI"放宽本地要求

平台约束

CubeMX 与 Fault

• Inc//Src/ 是 CubeMX 生成文件（带 USER CODE BEGIN/END 标记）：自定义代码只写标记区之间；Drivers/BSP/ 为纯手工代码
• 重生成会覆盖标记区之外的一切（.ioc 的 KeepUserCode=true 只保护 USER CODE 区；实测两次重生成各覆盖 4~5 处定制，其中两处不报编译错、只在真出故障时暴露）。防丢失按三层优先级 写进 .ioc → 搬进 USER CODE 区 → 审计兜底；每次重生成后立刻跑 python scripts/check_cubemx_survival.py（已挂 cubemx-survival 钩子）。方法论与全部实测坑（自造标记区会被模板换代抹掉、宏改名 #define f f_Gen 让位、FreeRTOS 钩子必须写进 USER CODE BEGIN 4/5 区…）→ docs/子系统设计/看门狗设计说明.md §10
• ARMCC __asm 只有一种合法形态：整函数 __asm void f(void) { ... }；GCC 内联语法报 #18、块内联把寄存器名当 C 标识符报 #20、取不到 C 的数据符号（A1516E: Bad symbol）→ 三条坑与可用写法 docs/子系统设计/看门狗设计说明.md §10.4
• 4 个 Cortex-M4 Fault 全部采集现场（手工 __asm Handler 取 MSP/PSP → B 到 per-fault C 入口 fault_entry_{hard,mem,bus,usage} → hard_fault_report 打 [ERR] <TAG> … 后 NVIC_SystemReset()）；MemManage/BusFault/UsageFault 默认禁用，不使能就被升级成 HardFault、日志看不出根因 → fault_handler_enable() 必须在 app_main_init() 第一行；SHCSR 的使能位无法在 CubeMX 配置（模板只生成优先级）→ 看门狗设计说明 §10

RTOS 与内存

• osKernelStart 之前禁止任何 FreeRTOS/CMSIS-RTOS 创建类 API（osMessageQueueNew 等会杀死启动，2026-09-20 实证根因）→ 内核前标准模式（纯寄存器/HAL 轮询 + 无锁静态缓冲 + 内核启动后惰性创建真队列）见 docs/架构设计/项目启动顺序管理.md
• 就绪屏障位必须 osFlagsNoClear：osEventFlagsWait 默认消费所等位，就绪位被先消费掉 → ftpTask 的 WaitAll 永不成立 → FTP 21 端口静默不监听（无日志无报错）。命令位（SYS_EVT_CFG_SAVE/NET_RECONFIG）保持消费型
• 自研代码禁用 C 库堆分配（malloc/calloc/realloc/strdup/free）：2026-10-23 起由提交门禁机器拦截（coding-standard 的 CODE-RULE-20，唯一豁免 = 平台分配后端的宿主侧实现，见 docs/门禁说明/coding-standard.md §7）：MicroLIB 的 C 堆由 startup_stm32f407xx.s 的 Heap_Size EQU 0x200 限定为 512 B，KB 级分配必然返回 NULL，而模拟器（宿主 CRT 堆）完全正常、照不出来 → 只用 pvPortMalloc/vPortFree，或把分配收进平台后端 → docs/内存管理/RAM使用分析与优化方案.md
• 内存预算紧张：新增任何任务/缓冲/栈前先核算 RAM 余量；改栈或加大局部变量前后各跑一次 scripts/stack_report.py（静态最坏链 + 串口 [STACK] 水位）与 scripts/ram_report.py（.map 静态占用）；总量红线已机械化：mem-budget 钩子拦 RW_IRAM1/RW_CCM >92%，子系统配额 / CCM 台账 / 趋势见 docs/内存管理/RAM预算台账.md（每次 @build 后跑 scripts/ram_baseline.py --update）→ docs/内存管理/
• FreeRTOS V10.3.1（CMSIS-RTOS V2）；HAL 时基 = TIM7（非 SysTick），tick = 1ms；NVIC 4 位优先级分组，外设中断优先级 ≥ 5

采集链（ADC / RS-485）

• ADC 取数只用 tpafe5160_snapshot()（临界区原子快照）：旧的 get_buf()/data_ready()/clear_ready() 已从驱动删除（两步之间被抢占会拷回两帧混合数据；s_ready 三写者竞态）。消费者侧一律经 adc_input_poll() / adc_input_raw() 按语义取数（不写死下标）→ docs/子系统设计/ADC采样节拍设计说明.md、App/algo/README.md
• F4 上 ADC1 的硬件触发源与 DMA 流是硬约束：① ADC1 的外部触发清单没有 TIM6/TIM7 TRGO（F4 上它们只接 DAC）→ 同时驱动两片转换器必须用 TIM3（PSC 83 / ARR 999 → 1 kHz + TRGO_UPDATE）；② ADC1 在 DMA2 只挂 Stream0 或 Stream4 → 选 Stream4 才不挤走 SPI1/USART1 RX，且换流会被重置为优先级 0（违反"外设中断 ≥5"）→ 改流后必须回 NVIC 核对 Src/dma.c；③ DMAContinuousRequests 必须 ENABLE（关掉 = 一轮 9 通道只发一次请求，静默丢 8 路）；④ DMA 目的缓冲必须在 SRAM（DMA2 不可达 CCM）→ docs/硬件平台/ADC通道映射说明.md
• STM32F4 ADC 上电必须自校准：CubeMX 不生成这一步，本仓裁剪版 HAL 没有 HAL_ADCEx_Calibration_Start、裁剪版 CMSIS 头没有 ADC_CR2_CAL → 按 RM0090 §13.3.6 手写 adc1_calibrate()（Src/adc.c 的 USER CODE BEGIN 1 区）+ MX_ADC1_Init() 末尾调用；缺它不报任何错，只是读数带失调
• 接 ADC / RS-485 消费者前的强制门禁（RS-485 接线门禁）：先确认驱动契约已修——TPAFE 三条 ✅（原子快照取数 / 帧序号取代就绪电平标志 / FRSTDATA 数据有效性校验）；RS485 已修两条 ✅，但 单缓冲包撕裂、TX 超时拉 DE 两条未修 ❌ → rs485_task 仍被挡。建任务前后各跑一次 stack_report.py

存储与网络外设

• FatFs（Lib/FatFs 移植版）两条台架实证陷阱：① 追加写必须 FA_WRITE|FA_OPEN_APPEND——该移植 FA_OPEN_APPEND 不含 FA_WRITE，不带写位打开的文件 f_write 恒返 FR_DENIED；且 f_write 簇分配失败时返回 FR_OK+短写（无错误码）→ 判失败必须校验写回字节数。② FF_USE_LFN=0 → 只支持严格 8.3 短名（不得以点开头），.fschk 恒返 FR_INVALID_NAME；自愈类逻辑严禁把名字/参数类错误码归入卷损坏触发集 → 完整口径与标志位编号表 docs/架构设计/STM32F4-Base存储架构说明.md §10.1
• CH395F SPI：每次事务须 ch395f_spi_begin()/end() 包裹；分频系数必须为 8（PCB 约束，勿"优化"）

日志与工具链

• DBG_* 每条日志约 90 B Flash + 216 B 栈（每个调用点内联行缓冲 + 时间戳缓冲）→ 日志不是免费的，已覆盖的步骤别加重复锚点，只在原先静默返回的黑洞处补；深调用链模块在 #include "dbg_log.h" 之前 #define DBG_LINE_BUF_MAX 128U（取值必须 ≥ 该模块最长日志行，否则该行被截断）
• MDK-ARM/*.uvprojx 每次 @build 后被 UV4 自动改写，改动一律不入库（XML 归一化 + PackID 降到本机 DFP 版本）；判据与例外（真的增删源文件才提交）→ keil-build skill

硬件引脚

• 完整引脚表（含 SD2506 I2C1、SWD、调试口）→ docs/产品需求/产品需求设计文档.md §4.2（权威，V0.1 口径；勿在本文重复抄表）
• ⚠ 网名 AINn ≠ 板级 ADCn ≠ 转换器通道号（17 路里 13 路置换）→ 取数必须查 docs/硬件平台/ADC通道映射说明.md（TPAFE buf[2]=IA/buf[5]=UN/buf[6]=UA；网名 ADC17=PC4 用 ADC_CHANNEL_14，不是 ADC_CHANNEL_12）
• ⚠ 8 路电气量被分给两片转换器是 V0.1 硬件缺陷，不是有意分配（跨转换器无共同采样触发 → 无同一时刻性、相位不确定）→ V0.1 上禁止跨转换器做相位/功率/功率因数/矢量运算；V0.2 须把 8 路全接 TPAFE（登记簿条目「双转换器无共同采样触发」）

模块约定

• CH395F 单连接 socket：监听与数据通道复用同一 Socket（CONNECT 后转数据通道，DISCONNECT/TIMEOUT 后重开 → LISTEN）；所有 CH395F 中断在 net_poll() 内经 GET_GLOB_INT_STATUS 集中读取并清除，不得在 ISR 或其他地方单独处理。⚠ 全局寄存器整体读即清、芯片无按位清除手段，而 net_poll 只在全局位为 1 时才读该 Socket 的 SINT → "顺手全量清一遍"等于把别的在用 Socket 的门焊死（B3 实证）。现存读清点全量审计 + 新增一处读清的三条准入判据 → docs/网络/网络自愈架构设计.md §4.10
• 所有 net_* socket 操作经 netMsgQueue 在 netTask 串行执行；非 netTask 任务直接调 net_* API，勿直接碰 CH395F 驱动
• net_* 公开 API 的错误码经"任务通知值"回传：net_msg_t 是按值拷入队列的，netTask 改的是自己那份副本，调用方永远看不到 → 错误码搭 xTaskNotify() 通知值回来。勿给 net_msg_t 加"回传用"字段（调用方只会读到栈垃圾）
• 单连接 socket 的断开语义：EOF 时 net 层已 auto_relisten，应用层不得在 EOF 时 net_close 该 fd（会连监听一起毁掉 → 端口"连接被拒"）；仅当数据 fd ≠ 监听 fd（模拟器多连接后端）时才关
• 网口配置：/config.ini [network] 段（工厂默认 192.168.1.100/24、gw .1；MAC 全零 = 芯片内置；UI 保存立即生效；旧档 /cfg/netcfg.bin 迁移已于 2026-10-10 删除，旧档存在则被忽略）；同文件 [ftp] 段 = FTP 鉴权（user / pwd_hash = SHA-256(user‖password) / write，出厂默认 admin/admin，默认口令在用有启动告警；连续 5 次失败锁 60 s）→ docs/子系统设计/网络配置说明.md
• 新 .c 文件必须手动注册到两处才能双端编译：MDK-ARM/STM32F407-Demo.uvprojx + simulator/CMakeLists.txt（用 new-source-file skill）；⚠ 新文件落在还没有的新目录，还要把该目录加进 uvprojx 的 <IncludePath>——否则报错落在消费者 TU 上（cannot open source input file），极易误判
• 测试构建：test/board/test_config.h 的 TEST_SUITE_CH395F/STORAGE/GD5F/RTC 互斥（一次只能一个，#error）；全部注释 = 产品构建，受 test-suite-switch 钩子门禁；ENABLE_DESTRUCTIVE_TESTS 默认关闭（关闭时套件只读模式，可随时在在用设备上跑）——⚠ 跑一轮破坏性 GD5F 即让 dhara 多记一个坏块且该计数持久化，普通恢复清不掉 → docs/测试说明/专项验证/存储维护与容量恢复.md；板级套件运行用 board-test-suite skill
• 改驱动前先读对应 docs/问题记录/*_Trap_Records.md（CH395F / GD5F2GQ5UE / SD2506）；各模块测试指南见 docs/测试说明/
• 改 UI / 绘制缓冲前读两条实证坑（I1 palette 头越界、白底白字整屏纯白）→ docs/UI设计/UI_设计架构.md §1.4 第 8/9 条，ui-verify skill 亦载

文档与图形

• 登记簿类文档「完成即销项」：docs/任务规划/README.md 这类待办登记簿，事项修复/关闭后直接从表中删除该行（不保留"已消化"行）——结论与证据应已沉淀进对应模块文档/问题记录。销项时必须：① 先核对目标文档确已含完整记录 ② 同步清理其他文档对该编号的引用 ③ 改完跑 check_doc_links.py --all + pre-commit。新条目标识（用户裁定 2026-10-14；2026-10-29 收口为一律不再发号）：# 列填语义短语（如 沉降窗 800ms 上限只留痕），不再新增字母+数字编号——"编号不回收"只写规则却不留痕迹就不可执行（销项删行后仓库里毫无痕迹，2026-10-14 实测就发生过「销项号被重新取走」的撞号事故），语义标识自带唯一性；存量编号（登记簿 N-x / S-x / T-x 与专项 A-x）已于 2026-10-26 全部转成语义短语，旧号进 scripts/archive/id_gate/id_aliases.json 标 retired-to-phrase、不得再指；「数据可信」任务卡号（中文前缀「卡」+ 数字，14 个）已于 2026-10-27 随卡销项整族清退，换算表 scripts/archive/id_gate/编号治理历史.md §9.3——这一族刻意不进 id_aliases.json：中文前缀不进 check_ids 语料，登记了机器也看不见，没有机器识别面，停发只靠规范与评审；已随销项消失的号永久作废、不得复用 → docs/任务规划/README.md §0
• 图形走 draw-diagram skill：精确布局图用 tools/arch_diagram/gen_*.py 生成器（产物放 docs/images/，脚本与产物同一笔提交：改生成器没重跑，下一个碰巧重跑的人会看到一段「不是我改的」diff——已机械化 generated-fresh，重跑到临时目录逐字节比对 → docs/文档规范.md §4.4）；拓扑图用 Mermaid；勿手绘 ASCII 框图。文件引用关系图走 tools/refgraph（& 'tools\refgraph\gen_refgraph.bat'）
• 改名 / 挪目录一律走 scripts/rename_ref.py（先 dry-run，确认后 --apply）：git mv + 自动改写全库引用（反引号引用 / Markdown 链接 / 图片 ../ 层级换算 / #include / uvprojx <FilePath> / CMakeLists.txt），落盘后自动跑 check_doc_links --all 复核——手工扫引用既慢又漏（一次改名历史上波及 10~30 文件）。引用章节用「路径.md §N.M」紧邻写法（doc-links 校验编号是否还在：紧邻/裸名/前缀/别名/自引用全部拦提交（钩子带 --sections-strict）；每次跑打印「可判定比例」，--section-todo 出待改清单，昵称歧义就登记 scripts/section_aliases.json 或写清楚）→ docs/文档规范.md §3.5 / §3.6。编号改名走 scripts/rename_ids.py（映射表驱动、显式 scope、干跑默认、自动写 scripts/archive/id_gate/id_aliases.json 的 scoped 旧号→新号条目；[示例]/[计划] 行与变更记录表不改写；绝不全局查找替换——同一裸形字面量可能同时属多个族，全局替换等于造新撞号，实测 S3 三义）
• 文档写作规范（编码/BOM/链接/表格/一致性钩子）→ docs/文档规范.md；全量索引与推荐阅读顺序 → docs/README.md

边界（Ask first / Never）

Ask first（须用户明确指示才做，均不是任何任务的隐含步骤）：git commit / git push（构建与测试通过后停下等指令）· 开 ENABLE_DESTRUCTIVE_TESTS 跑破坏性套件（持久代价 → 模块约定）· CubeMX 重生成（→ cubemx-regen skill）· 登记簿删行销项（→ 文档与图形）· 建任务/抬栈/加大缓冲（先跑预算脚本 → 平台约束）

Never（任何任务）：用 Get-Content/Set-Content/cmd 重写含中文文件、用 git checkout/reset --hard 丢弃未提交工作（→ 铁律）· 在 USER CODE 区之外写定制代码、自研代码写 C 库堆分配（→ 平台约束）· 非 defaultTask 直接触碰配置引擎、非 netTask 直接碰 CH395F 驱动（→ 模块约定）· 提交 UV4 抖动的 *.uvprojx、提交 .mnemon/（记忆工具本地状态，已 .gitignore）

按主题查哪份文档

主题	去处
全量索引 / 推荐阅读顺序	docs/README.md
架构全景 / 启动时序与内核前模式	docs/架构设计/项目架构总览.md、docs/架构设计/项目启动顺序管理.md
产品需求基线（做到什么程度）	docs/产品需求/产品需求设计文档.md
看门狗 + CubeMX 重生成存活方法论 + ARMCC __asm	docs/子系统设计/看门狗设计说明.md §10
ADC 采样节拍 / 通道映射 / V0.1 硬件缺陷	docs/子系统设计/ADC采样节拍设计说明.md、docs/硬件平台/ADC通道映射说明.md
存储栈（FatFs / dhara / lftpd / 两条 FatFs 陷阱）	docs/架构设计/STM32F4-Base存储架构说明.md
RAM / 栈预算 / 容量台账	docs/内存管理/RAM使用分析与优化方案.md、内存内容分配策略.md
每个提交门禁一篇详解（查什么 / 拦下过什么真事 / 限制与盲区 / 基线口径）	docs/门禁说明/README.md（52 个钩子 → 30 篇索引，其中 2 篇是退役留档 + 1 指针）
还想给东西发编号？（2026-10-29 用户裁定：一律不发，写语义短语；§4.1 五个存量族的既有号只读引用——「停发」不等于「暂缓」，也不等于「可以清号」）/ 编号门禁现状（两道都已退役：全库八项校验 2026-10-28、只查新增行 2026-10-29；此后无机器面，只靠 §1 与评审）	docs/编号规范.md（§1 默认答案、§4.1 存量族〔穷举〕与『已停发』栏、§8.5 手工普查与恢复机器面）
提交门禁通用机制（阶段 / stash 陷阱 / 触发面 / 增量拦截三段式）	docs/代码规范/pre-commit使用说明.md §2
代码规范 V1.0 / cppcheck 口径	docs/代码规范/嵌入式C语言代码规范_V1.0.md、cppcheck使用说明.md
自动化测试 / 实机测试 / 板级套件	docs/测试说明/流程与规范/自动化测试流程.md、实机测试实施指南.md、board-test-suite skill
烧录与复位语义	docs/测试说明/测试工具/ST-LINK_CLI_复位使用说明.md
串口助手	serial-assistant skill（命令/判据/陷阱，用到自动加载）、docs/测试说明/测试工具/串口助手使用指南.md、串口助手设计说明.md
UI 架构 / 模拟器 / UI 自动化回归	lvgl-simulator skill（构建/自检/报错速查，用到自动加载）、docs/UI设计/UI_设计架构.md、LVGL模拟器部署与使用说明.md、UI_自动化测试流程.md；UI 改动回归走 ui-verify skill
待办与审计发现登记簿	docs/任务规划/README.md
多任务并行开发（开空间 / 合并回收 / 台架与构建排队）；DSH worktree 插件的仓内树怎么接上（.dsh-worktrees/ 缺 .venv、plugin adopt、锁归属 pw:<name>）	task-worktree skill（@task 仅为文档别名非可执行命令，显式调用 /task-worktree，用到自动加载；插件桥 → 其 F 节）、docs/环境与部署/并行任务工作树方案.md §3.4
换机 / 工具路径环境变量	docs/环境与部署/
远程 CI（Gitea Actions，只跑本机一台 runner）	docs/CI/README.md