wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 29 Pull Requests 1 Actions Packages Projects 2 Releases Wiki Activity

v2-on-ui #4

Merged
wandering1 merged 497 commits from v2-on-ui into master 2026-11-02 04:07:13 +08:00
Conversation 0 Commits 497 Files Changed 910
+126858 -19205
910 changed files with 126858 additions and 19205 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cubemx_survival_baseline.json
+11 -10
View File
@@ -1,20 +1,21 @@
{
"snapshot": {
"iwdg-defer-start": "ca839ffc1cda439f",
"hardfault-handler": "f3afab8d2be18794",
"fault-handlers-3": "f3afab8d2be18794",
"hardfault-handler": "a7f538eccdf1d88d",
"fault-handlers-3": "a7f538eccdf1d88d",
"fault-handler-enable": "be87fcd3a7926138",
"hardfault-report-impl": "f3afab8d2be18794",
"hardfault-report-impl": "a7f538eccdf1d88d",
"error-handler-degrade": "d02a92afda945c4b",
"stack-overflow-check": "d4735e3a265e16ee",
"malloc-failed-hook": "6b86b273ff34fce1",
"assert-not-deadloop": "d4a00718ab2bd071",
"assert-impl": "5d862ceb21c77a86",
"stack-overflow-hook-impl": "a006edbd30d2c4d7",
"assert-impl": "0ccf10a7fb115aa8",
"stack-overflow-hook-impl": "03a383dda578d12a",
"malloc-failed-hook-impl": "fcd7250e5cd6403b",
"stack-overflow-hook-helper": "cacd9fd028be9b5b",
"watchdog-module": "663f05caf22cf7d0",
"reset-cause-latch": "52fc71acbb0f1aed",
"watchdog-module": "5fd7efd90a78fe5a",
"net-msgq-adopt": "a0f913e3f34c8e9e",
"reset-cause-latch": "983927d587cb9f48",
"iwdg-hal-driver": "4b902875a84554e9",
"hal-iwdg-enabled": "1a8ed6cff34f7ba6",
"ioc-keepusercode": "b5bea41b6c623f7c",
@@ -22,11 +23,11 @@
"ioc-task-stacks": "58ee94dd2a093177",
"adc1-hal-enabled": "1a8ed6cff34f7ba6",
"adc1-calibration-call": "8d5f4b40fb218913",
"adc1-calibration-impl": "d33bc4323e243248",
"adc-tick-tim3-branch": "39c3548c37f6c4ae",
"adc1-calibration-impl": "25723dd0449ac701",
"adc-tick-tim3-branch": "17d43a565f50c6f2",
"ioc-adc-trig-t3trgo": "a9939de260ee46f8",
"ioc-adc-dma-continuous": "189126670d85d80a",
"adc1-dma-link": "397fce92dca3b728",
"adc1-dma-link": "8a57c70611db1a02",
"adc1-dma-irq-priority": "beff08e91333229b"
},
"_note": "CubeMX 存活审计基线；改动用 --write 重建"
.dsh/skills/board-test-suite/SKILL.md
+6 -6
View File
@@ -14,7 +14,7 @@ whenToUse: 要跑板级测试套件（CH395F/STORAGE/GD5F/RTC）回归、要开/
实测 GD5F 整轮破坏性跑一次即多记一个 NAND 坏块（容量 95248→95200），
计数持久化在 dhara journal checkpoint 头里，普通格式化恢复不回来。
- 提交门禁：pre-commit 钩子 `test-suite-switch` 默认拦截测试构建
（确需提交用 `ALLOW_TEST_BUILD=1` 显式放行）——**跑完务必改回全注释并 `@build`**。
（确需提交用 `ALLOW_TEST_BUILD=1` 显式放行）——**跑完务必改回全注释并 `/keil-build`**。
## 一键回归（推荐路径，勿手工循环）
@@ -28,15 +28,15 @@ whenToUse: 要跑板级测试套件（CH395F/STORAGE/GD5F/RTC）回归、要开/
- 脚本 try/finally **无条件还原 `test_config.h`**（含 Ctrl-C 路径）——这是它存在的核心
理由：跑完忘还原 = 测试固件进库。`--keep-config` 仅调试用。
- 退出码 0=全 PASS / 1=有 FAIL / 2=环境错误；4 套件真机一轮数分钟起，**仅回归窗口用，绝不挂 pre-commit**。
- 手工循环时的顺序（每轮）：改宏（只开一个）→ `@build` 0错0警 → 烧录 →
- 手工循环时的顺序（每轮）：改宏（只开一个）→ `/keil-build` 0错0警 → 烧录 →
`serial-assistant` 采集（open→clear→烧录→wait-idle）→ 判读套件汇总行。
## 跑后检查清单（必做）
1. `test_config.h` 恢复全注释（用 run_all_suites.py 则已自动）；
2. `@build` 确认产品构建 0 错 0 警；
2. `/keil-build` 确认产品构建 0 错 0 警；
3. 若开过破坏性开关：核对开机日志容量数字（健康满值 96064 pages / 187 MB），
掉了 → 按 `docs/测试说明/存储维护与容量恢复.md` 走恢复动作；
掉了 → 按 `docs/测试说明/专项验证/存储维护与容量恢复.md` 走恢复动作；
4. 提交前 `test-suite-switch` 门禁会再兜一道。
## 三个维护动作别混用（存储类）
@@ -47,8 +47,8 @@ whenToUse: 要跑板级测试套件（CH395F/STORAGE/GD5F/RTC）回归、要开/
| B 容量恢复 | A + `STORAGE_RECOVERY_FULL_WIPE`（擦净 2044 块 + 断电重启） | 卷全失，约 4s 擦除 |
| C 日常回归 | 只开 `TEST_SUITE_*`，不开破坏性 | 无（只读模式，横幅 `mode: READ-ONLY`） |
原理与完整步骤见 `docs/测试说明/存储维护与容量恢复.md`；各套件用例清单/判读见
`docs/测试说明/` 对应 `*_Test_Guide.md`；流程规范 `docs/测试说明/测试开发标准流程.md` §3。
原理与完整步骤见 `docs/测试说明/专项验证/存储维护与容量恢复.md`；各套件用例清单/判读见
`docs/测试说明/` 对应 `*_Test_Guide.md`；流程规范 `docs/测试说明/流程与规范/测试开发标准流程.md` §3。
## 其它项目怎么套
.dsh/skills/cubemx-regen/SKILL.md
+9 -9
View File
@@ -1,6 +1,6 @@
---
name: cubemx-regen
description: CubeMX 重生成存活工作流（L1 写进 .ioc → L2 USER CODE 区/宏改名 → L3 审计兜底）：重生成前后各跑什么、哪些定制会被静默覆盖、审计脚本 check_cubemx_survival.py 的 --check/--write 语义。STM32CubeMX 项目通用方法论 + 本仓库清单。
description: CubeMX 重生成存活工作流（写进 .ioc → 搬进 USER CODE 区/宏改名 → 审计兜底三层）：重生成前后各跑什么、哪些定制会被静默覆盖、审计脚本 check_cubemx_survival.py 的 --check/--write 语义。STM32CubeMX 项目通用方法论 + 本仓库清单。
whenToUse: 要用 CubeMX 重新生成工程（改 .ioc / 外设配置）、改动 Src/Inc 生成区附近代码、或排查"重生成后定制丢失/行为变了但编译不报错"时。
---
@@ -12,12 +12,12 @@ whenToUse: 要用 CubeMX 重新生成工程（改 .ioc / 外设配置）、改
## 三层优先级（防丢失的唯一正确顺序）
1. **L1 写进 `.ioc`**（权限最高）：凡 CubeMX 界面能表达的配置（任务栈/优先级/队列/
1. **写进 `.ioc`**（第一层，权限最高）：凡 CubeMX 界面能表达的配置（任务栈/优先级/队列/
事件组/堆大小/IWDG 参数/FreeRTOS 钩子开关）必须在 GUI 里设——重生成只会照写。
⚠ **别凭印象断言"界面里没有该项"**，先翻标签页或查 `db/mcu/IP/*_Modes.xml`
（实测 `configCHECK_FOR_STACK_OVERFLOW=2` 在 FreeRTOS → Config parameters →
Hook function related definitions 里，自造宏区被抹两次后才找到）。
2. **L2 搬进 `USER CODE` 区**：只信 CubeMX **当前模板真实生成**的区名（优先
2. **搬进 `USER CODE` 区**（第二层）：只信 CubeMX **当前模板真实生成**的区名（优先
`USER CODE BEGIN 0` 这类从未变过的标准位）。**不要依赖"自造标记区"**——
模板换代时自造区连同内容一起消失（实测中断函数模板换代的教训）。
生成区内要**去掉一句调用** → 宏改名：`USER CODE BEGIN 0` 里放空实现 +
@@ -26,12 +26,12 @@ whenToUse: 要用 CubeMX 重新生成工程（改 .ioc / 外设配置）、改
要**替换生成实体定义**（如 4 个 Fault Handler 本体）→ 我们的定义放
`USER CODE BEGIN 0`，**必须写在 `#define X X_Gen` 之前**（写在之后会被自己的宏改名），
生成区恢复原样，链接器自动移除未引用的 `*_Gen`。
3. **L3 审计兜底**：清单 + 哈希基线漂移检测（见下）。
3. **审计兜底**（第三层）：清单 + 哈希基线漂移检测（见下）。
## 重生成前后固定动作
```powershell
# 重生成前：把能在 GUI 表达的都写进 .ioc（L1 检查）
# 重生成前：把能在 GUI 表达的都写进 .ioc（第一层检查）
# 重生成后【立刻】：
& '.venv\Scripts\python.exe' scripts/check_cubemx_survival.py # 人读报告
& '.venv\Scripts\python.exe' scripts/check_cubemx_survival.py --check # 门禁模式（pre-commit 同款）
@@ -41,21 +41,21 @@ whenToUse: 要用 CubeMX 重新生成工程（改 .ioc / 外设配置）、改
- 退出码 0=通过 / 1=有 FAIL 项；已挂 pre-commit `cubemx-survival` 钩子
（改 `.ioc`/`Src/`/`Inc/`/`.uvprojx` 触发）。
- **L3 清单已清空 = 重生成应当零 diff**；仍有 diff 就是被覆盖了，直接跑脚本定位。
- **审计清单已清空 = 重生成应当零 diff**；仍有 diff 就是被覆盖了，直接跑脚本定位。
- `uvprojx` 不参与漂移检测（每次构建被 UV4 改写），只保留"源文件仍挂载"断言。
## 实测陷阱清单
- CubeMX 对 System Exception（HardFault/MemManage/BusFault/UsageFault）**只生成优先级、
从不生成使能代码**；`.ioc` 里 `NVIC.MemoryManagement_IRQn=true` ≠ 已使能（只是向量可见）。
`SHCSR` 使能位只能手工写（L2）+ 审计项兜底。
`SHCSR` 使能位只能手工写（第二层）+ 审计项兜底。
- 启用 FreeRTOS 后模板会生成 `USER CODE BEGIN 4 / 5` 区（默认空桩）——**钩子实现必须
整体写进这两个区**，且 helper 函数放更早的区（同名两处定义 = 编译错）。
- 生成文件行尾/末尾空行按工具自身风格，**勿用改写型钩子去修剪**（已豁免，勿"顺手格式化"）。
- 重生成后除审计脚本外，照常走 `@build`（0 错 0 警）+ 必要时 `@test` 闭环。
- 重生成后除审计脚本外，照常走 `/keil-build`（0 错 0 警）+ 必要时 `/serial-boot-test` 闭环。
## 其它 CubeMX 项目怎么套
L1/L2/L3 方法论与"宏改名两招"完全通用；本仓库的清单/基线在
这三层方法论与"宏改名两招"完全通用；本仓库的清单/基线在
`scripts/check_cubemx_survival.py`（21 项 + `.cubemx_survival_baseline.json`），
新项目照它建自己的清单。方法论详见 `docs/子系统设计/看门狗设计说明.md` §10.1/§10.2。
.dsh/skills/draw-diagram/SKILL.md
+171 -32
View File
@@ -1,12 +1,14 @@
---
name: draw-diagram
description: docs/ 文档技术配图绘制流程（精确布局图用 SVG 生成器 / 拓扑图用 Mermaid）：挑脚本 → 改顶部数据 → 重跑生成 → 目检 → md 相对路径引用 → 脚本+产物一并提交，产物统一放 docs/images/。
whenToUse: 需要新增/修改 docs/ 文档的技术配图（协议帧、分层架构、依赖/就绪屏障、流程图、时序、状态机），或用户要求"画个图 / 生成图 / 更新架构图 / 帧格式图"时。
description: docs/ 文档技术配图绘制流程（精确布局图用 tools/arch_diagram/ 的纯标准库 SVG 生成器 / 拓扑图用 Mermaid）：挑脚本或照抄骨架新建生成器 → 改顶部数据 → 跑生成并把 check_fit/OVERFLOW 溢出预检清零 → Windows 无渲染器时用 headless Chrome/Edge 截图 + read_image 回读目检 → 回改生成器重跑 → 过 generated-fresh 逐字节幂等 → md 相对路径引用 → 脚本+产物一并提交，产物统一放 docs/images/。
whenToUse: 需要新增/修改 docs/ 文档的技术配图（协议帧、分层架构、依赖/就绪屏障、台阶/泳道对照、刻度尺、流程图、时序、状态机），从零新写一个 gen_*_svg.py 生成器，在 Windows 上想"目检"一张 SVG，或用户要求"画个图 / 生成图 / 更新架构图 / 帧格式图"时。
---
# 文档配图绘制（SVG / Mermaid）
`docs/` 文档技术配图的统一流程；完整选型依据 / 约定 / 检查清单见 `docs/架构设计/图形绘制流程.md`。**产物统一放 `docs/images/`**（专门配图目录，`.svg` 入库；PNG 预览属本地派生物、不入库）。
`docs/` 文档技术配图的统一流程；完整选型依据 / 约定 / 检查清单见 `docs/架构设计/图形绘制流程.md`。**产物统一放 `docs/images/`**（专门配图目录，`.svg` 入库；PNG 预览属本地派生物、不入库，`.gitignore` 已含 `docs/images/*.png` 与 `ci-artifacts/`）。
> 本窗实测（2026-10-29，新建 2 张图）：**"浏览器打开 SVG 目检"这一步在 Windows 上不可直接执行**——没有现成 SVG 栅格化工具，只能走 headless Chrome/Edge 截图 + 图片回读；且 `generated-fresh` 是**逐字节**门禁，生成器自己的控制台打印也会成为失败源（见 §五）。
## 工具选型
@@ -15,15 +17,15 @@ whenToUse: 需要新增/修改 docs/ 文档的技术配图（协议帧、分层
| 协议帧 / 字节布局（字段宽 ∝ 字节数、偏移标尺） | SVG：`tools/arch_diagram/gen_frame_svg.py` |
| 分层架构 / 模块依赖 | SVG：`tools/arch_diagram/gen_arch_svg.py` |
| 就绪屏障 / 生产者-消费者 | SVG：`tools/arch_diagram/gen_barrier_svg.py` |
| 台阶 / 泳道对照 / 刻度尺等"高度差、并列对照"类 | SVG：**新写一个** `tools/arch_diagram/gen_<主题>_svg.py`（照抄最近生成器的骨架，见 §二） |
| 其他精确布局图 | **复制**最接近的生成器改顶部数据（`build()` 与数据解耦，通用） |
| 流程 / 时序 / 状态机 / ER（只表达拓扑关系） | Markdown 内嵌 ` ```mermaid ` 代码块（`flowchart` / `sequenceDiagram` / `stateDiagram-v2` / `erDiagram`），无需生成图片 |
| 流程 / 时序 / 状态机 / ER（只表达拓扑关系） | Markdown 内嵌 ```mermaid 代码块（`flowchart` / `sequenceDiagram` / `stateDiagram-v2` / `erDiagram`），无需生成图片 |
> Mermaid 盒子按文本自适应宽、自动加有向边，**只适合"关系"类图**；凡需精确像素 / 比例的布局图一律走 SVG 生成器。
> Mermaid 盒子按文本自适应宽、自动加有向边，**只适合"关系"类图**；凡需精确像素 / 比例 / 高度差的布局图一律走 SVG 生成器（实测教训：五级"台阶"用 Mermaid 会被压成同一高度，"还差一级"就看不出来了）。
## SVG 生成流程（仓库根目录执行）
## 一、改既有图（最短路线）
1. **挑 / 复制脚本**：新类型图复制最接近的生成器，只改顶部数据区。
2. **改顶部数据**：字段 / 节点 / 标题 / 配色。沿用既有调色板（主色 / 底色）：
1. 改**顶部数据 / 常量区**（字段、节点、标题、配色），不改 `build()` 结构。配色沿用既有调色板（主色 / 底色）：
| 语义 | 主色 | 底色 |
|---|---|---|
@@ -35,38 +37,175 @@ whenToUse: 需要新增/修改 docs/ 文档的技术配图（协议帧、分层
| 灰 | `#475569` | `#f1f5f9` |
| 玫红 | `#e11d48` | `#fff1f2` |
3. **重跑**（脚本内置 `ElementTree` 自检，XML 不合法直接抛错）：
2. 重跑（仓库根；脚本内置 `ET.fromstring` 自检，XML 不合法直接抛错）：
```powershell
& '.venv\Scripts\python.exe' tools/arch_diagram/gen_xxx.py
# 成功输出：OK <字节> bytes, canvas <W>x<H> -> <路径>
# 期望：OK <字节> bytes, canvas <W>x<H> -> <路径>，且没有 OVERFLOW WARN / overflow warnings 行
```
4. **目检**：浏览器打开 `docs/images/*.svg`——文字不溢出盒外、框 / 线 / 标签对齐、配色符合调色板。
5. **md 引用**（相对路径）：`docs/` 根的 md 写 `![标题](images/xxx.svg)`；`docs/UI设计/` 等子目录 md 写 `![…](../images/xxx.svg)`。
6. **提交**：生成器脚本（源）+ 生成的 `.svg`（产物）**一并**提交。
3. 目检（§三）→ 引用（§四）→ 幂等与门禁（§五）→ 提交（§六）。
## SVG 约定（手写 / 新增生成器必须遵循）
## 二、从零新写生成器（先抄骨架，别裸写）
- **纯标准库**拼 SVG（只用 `html` / `os`（+ `math`）），不引第三方库（SVG 由浏览器用系统字体渲染）
- 所有文本经 `html.escape(s, quote=True)`，防止破坏 XML
- 字体栈：`Microsoft YaHei, Segoe UI, PingFang SC, sans-serif`
- 文本宽估算（自适应盒宽）：CJK / 全角 / 圈码 / 箭头 ≈ `1.0em`，其余 ≈ `0.58em`（**宁大勿小**防溢出）
- 落盘：`open(OUT, "w", encoding="utf-8", newline="\n")`（UTF-8 无 BOM + LF）
- 写盘后 `xml.etree.ElementTree.fromstring(svg)` 自检
- 产物放 `docs/images/`，命名 `<主题>.svg`（可与同名 `.md` 对应）
1. **先读同目录 1~2 个最近的脚本**（如 `tools/arch_diagram/gen_adc_frontend_svg.py`、`gen_adc_code_scale_svg.py`），抄它们的三条约定：
- **文件头 docstring** 写清四件事：产物路径 + 这张图回答什么问题 + **「为什么不用 Mermaid」** + 用法（"仓库根目录，任意 python3"）与"改内容 vs 调坐标"的边界；
- **顶部集中常量块**：画布与几何（`W` / `H` / `PAD` / `RIGHT`）→ `FONT` → 各级字号 → 调色板 → 文案（`TITLE` / `SUB*` / 逐条目 / `FOOTNOTE`）；坐标一律由常量推导，别在 `build()` 里塞魔法数；
- **纯标准库**：`import html / os / sys / xml.etree.ElementTree as ET`，helpers 只有 `esc` / `text_w` / `txt` / `line` / `rect` / `wrap` / `check_fit` / `emit` / `build`。
2. **照抄预检三件套**（`gen_adc_frontend_svg.py` 里还没有；从 `tools/arch_diagram/gen_data_trust_ladder_svg.py` 抄）：`OVERFLOW = []` + `check_fit(s, fs, avail, where)` + `wrap(s, fs, avail, max_lines, where)`，标题 / 副标题 / 盒内标题走 `check_fit`，盒内正文与脚注走 `wrap`（`wrap` 按估宽折行、超行数用 `…` 收尾并记一条 OVERFLOW）。`build()` 末尾：`emit("OK ...")` 之后 `if OVERFLOW: emit("!! %d overflow warnings" % len(OVERFLOW))`。估宽口径不变：CJK / 全角 / 圈码 / 箭头 ≈ `1.0em`，其余 ≈ `0.58em`（宁大勿小）。
3. **照抄 `emit()`**（幂等门禁的地基，见 §五）：
## SVG → PNG（可选，本地派生物不入库）
```python
def emit(s):
"""控制台打印按目标编码替换，绝不因 GBK 终端遇上 ²/− 之类字符而崩
（generated-fresh 钩子会把本脚本拷进临时目录重跑，崩了就是一片假红）。"""
enc = getattr(sys.stdout, "encoding", None) or "ascii"
sys.stdout.write(s.encode(enc, "replace").decode(enc, "replace") + "\n")
```
- 最简单：浏览器打开 `.svg` → 另存为图片
- 脚本化：`& '.venv\Scripts\python.exe' -m pip install cairosvg` 后
`& '.venv\Scripts\python.exe' -c "import cairosvg; cairosvg.svg2png(url='docs/images/xxx.svg', write_to='x.png', scale=2)"`
- `.gitignore` 已含 `docs/images/*.png`
4. 路径锚在脚本自身位置，别用 cwd（临时目录重跑才不会漂）：
## 提交前检查清单
```python
ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
OUT = os.path.join(ROOT, "docs", "images", "<主题>.svg")
```
- [ ] 生成器输出 `OK … bytes`（无异常 = XML 合法）
- [ ] 浏览器目检：文字不溢出、框 / 线 / 标签对齐、配色符合调色板
- [ ] 引用它的 `.md` 里图片**相对路径**正确（能显示）
- [ ] 脚本 + 产物 `.svg` **一并**暂存
- [ ] `pre-commit run --files <脚本> <svg> <md>` 全过（无乱码 / 行尾空白 / 编码 OK）
5. 跑 `& '.venv\Scripts\python.exe' tools/arch_diagram/gen_<主题>_svg.py`，**把 OVERFLOW 告警打到 0 再进目检**——预检能在渲染前就报出 `foot: 974 > 968` 这类溢出（本窗实测两张图首跑各报一条脚注超宽），比靠眼睛反复量便宜一个数量级。
6. 新脚本落库时**同批**把行加进 `tools/arch_diagram/README.md` 的「**产物清单**」——那张表按图逐行，列 =
图 / 生成器 / 这张图答什么 / 顶部数据区 / 挂在（`文档:行号`）。**全仓只此一张逐脚本清单**：
`docs/架构设计/图形绘制流程.md` 曾另立一张三列表，结果两张各漏各的（2026-10-30 实测 README 漏 5 个、
那张漏 9 个），现已换成指针。所以新图只加一行，别在第二篇文档再起一张表。
## 三b、大图（几十框几十边）加一道碰撞审计，别只靠眼睛
边数一多，像素回读就查不全（本窗实测：42 框 37 边的端到端链路图，缩略 PNG 看着干净，
审计器一眼报出 23 条：边标签压节点、走线穿框、标签出画布）。做法是**解析自己生成的 SVG**
而不是解析渲染结果——`ET.parse` 产物，按 `font-size`/`fill` 分诊文字，估宽口径直接复用生成器的
`text_w()`（两边同一把尺子才不会假绿），然后判三件事：
1. **边标签的「文字盒」vs 节点框**（不是白片盒）：交集 > 6 px² 就算问题——节点在边之后画，
压上去的**文字**会被节点白底吃掉半个字（本窗症状：「串行执行」渲染成「行执行」）。
白片本身压到框边角是**无害**的（白片先画、节点后画，只是盖住一点白底，不改字）。
除「有没有压上」，还要打印**文字与最近框的最小水平余量**并按 < 3px 报问题：
本窗「TRGO 触发」余量 0.7px、「帧 B 下发」1.5px，都没压上却随时会被真实字宽吃笔画，
缩短标签后升到 3.5px 以上才算安全。
2. **走线段 vs 节点框**（内缩 2px 再判，排除贴边端点）：线穿框是硬伤，改边的出入框方位或独占通道。
3. **标签互压 / 出画布**：白片两两求交；`box[3] > H-2` 查脚注贴底。
4. **零余量复扫（生成器侧，别只跑 SVG 侧那一遍）**：SVG 反推不出哪两个框是本边端点，
走线只能内缩着查 → 1~3px 的切边照不到。用生成器自己的 `Box` / `route()` / `label_at()`
真值再扫一遍：框不膨胀不内缩、只跳本边两端。跑 SVG 侧与真值侧两遍都归零才算收工。
脚本骨架与判据见 `reference/svg-collision-audit.py`（可直接拷进 `ci-artifacts/` 当一次性工具用，
**别放 `tools/arch_diagram/`**——那里只放生成器，非 `gen_*.py` 的脚本混进去会让人以为在册）。
配套的两条几何纪律（都是本窗踩出来的）：
- **同轴直连不要插退化折点**：同行两框若按「同轴 → 加一段 gx 走廊」的通用规则生成，会产出
`[(195,176),(219,176),(219,176),(243,176)]` 这种点集——线还是直的，但**标签落点算成第一半的中点**，
整格偏移半个通道 → 压框。正解：出框轴与入框轴同轴且已对齐时直接返回两点线。
- **标签落点用弧长中点，不用「最长段中点」**：多段折线里最长段可能有多条（对称 Z 字），
取第一条会把标签推到拐角上；沿总弧长取 50% 再定位，配合 `seg`/`t` 旋钮微调。
**先验审计器本身，再信它的「0 条」**：本窗把 `hi > y0` 复制粘贴成 `hi > x0`，零余量那一遍
凭空报出 3 条「穿框」，差点为此重排三条边的走线。判据脚本的假阳性比漏报更贵——它会让你
去改一张本来没问题的图。规矩：写完后挑一条**已知干净**的边（例如两框正对的直连边）单独跑一遍，
确认它不报，再跑全量。
## 三、目检（Windows：本机没有任何现成 SVG 渲染器）
**先探测，别照抄 cairosvg 命令**：本仓 `.venv` 无 `cairosvg`（`ModuleNotFoundError: No module named 'cairosvg'`），`rsvg-convert` 不存在，只有 Edge / Chrome：
```bash
# ops_bash（git-bash）里探测；哪个存在用哪个
ls -1 "/c/Program Files/Google/Chrome/Application/chrome.exe" \
"/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe" 2>/dev/null
command -v rsvg-convert inkscape magick convert 2>/dev/null || echo "no CLI rasterizer"
```
```powershell
Test-Path "C:\Program Files\Google\Chrome\Application\chrome.exe"
Test-Path "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
```
截图（**`--screenshot=` 必须给绝对 Windows 路径 + 绝对 `file:///` 输入**，并且**固定用
`--headless=new`**：本窗用旧 `--headless` 同一套命令时成时不成——一次写出了 168 KB，
下一次静默不写文件；也别把 stderr 丢进 `/dev/null`，成功标志就是它自己打印的那行字数）：
```bash
mkdir -p ci-artifacts # Chrome 没有建目录的参数，先自己建
OUT="D:\\Code\\DTU Code\\<工作树名>\\ci-artifacts\\<主题>.png" # 绝对路径、反斜杠
"/c/Program Files/Google/Chrome/Application/chrome.exe" \
--headless=new --disable-gpu --hide-scrollbars --force-device-scale-factor=1 \
--window-size=1060,712 \
--screenshot="$OUT" \
"file:///D:/Code/DTU Code/<工作树名>/docs/images/<主题>.svg" 2>&1 | tail -2
```
成功标志是 Chrome 自己打印的 `<N> bytes written to file D:\...`。**回读 PNG 才算目检完成**：
```ts
const r = await tools.read_image({ file_path: "D:\\Code\\DTU Code\\<工作树名>\\ci-artifacts\\<主题>.png" });
console.log(r.image.width + "x" + r.image.height, "bytes=" + r.image.bytes); // 应等于 --window-size / 画布
```
看什么：文字压框 / 溢出盒外、标签互撞（本窗实测两轮才干净：台阶图首轮"文字压到盒下方 + 标签互撞"，第二、三轮才修完）、`wrap` 收尾的省略号 `…`（有 = 文案超长）、虚线与盒边线重叠、配色是否还在调色板里。发现问题**回改生成器常量并重跑预检**，然后**重新截图**（PNG 是派生物，不会自己更新），`--window-size` 跟着 `canvas WxH` 改。
## 四、md 引用（相对路径）
`docs/` 根的 md：`![标题](images/xxx.svg)`；`docs/任务规划/`、`docs/UI设计/` 等子目录 md：`![…](../images/xxx.svg)`（本窗实例：`docs/任务规划/数据可信.md` 写 `![数据可信是五级台阶，现在踩在第 2 级](../images/数据可信台阶.svg)`）。alt 文本写成"这张图的结论是什么"，别只重复文件名。
## 五、generated-fresh：逐字节幂等门禁（新图长期不假红的前提）
`generated-fresh` 把 `tools/arch_diagram/gen_*.py`（`docs-svg` 项：`per_script: true`、`pattern: gen_*.py`、`mode: exact`）**逐个拷进系统临时目录重跑**，与工作区产物**逐字节**比对：内容不同 = `DIFF`（生成物比生成器旧）、临时目录多出一个工作区没有的文件 = `NEW`、`rc≠0` = 「生成器报错」。由此推出四条硬约束：
1. **生成器只能写那一个 `.svg`**：绝不在脚本里顺手导出 PNG 预览（预览写 `ci-artifacts/`，不进 `docs/images/`）。
2. **stdout 不许崩**：GBK 终端遇上 `²` / `−` / CJK 路径会 `UnicodeEncodeError` → 钩子 `rc≠0`，一片假红。所以打印一律走 `emit()`，脚本里不留裸 `print()`（本窗实测：两份新生成器只改了一份，另一份照旧崩）。
3. **产物内容零不确定**：SVG 里不写时间戳 / 绝对路径 / 主机名；浮点坐标一律 `%g` / `%.1f` 定形；字典与 `os.listdir` 结果参与布局时先 `sorted()`。
4. **`gen_*.py` 命名即自动在册**（pattern 就是 `gen_*.py`）——故意不叫这个名字等于躲开门禁，门禁最大盲区正是"未登记的生成器"，别利用它。
自查（仓库根）：
```bash
.venv/Scripts/python.exe tools/arch_diagram/gen_<主题>_svg.py
sha1sum docs/images/<主题>.svg
.venv/Scripts/python.exe tools/arch_diagram/gen_<主题>_svg.py # 重跑后 sha1 必须不变
.venv/Scripts/python.exe scripts/check_generated_fresh.py # 期望 rc=0，无 DIFF/NEW，[BASELINE] 不增
```
```powershell
& '.venv\Scripts\python.exe' scripts/check_generated_fresh.py # 单独跑（不 stash 别人在飞的改动）
& '.venv\Scripts\python.exe' scripts/check_generated_fresh.py --list # 只看在册声明
& '.venv\Scripts\python.exe' -m pre_commit run generated-fresh --files tools/arch_diagram/gen_<主题>_svg.py docs/images/<主题>.svg
```
⚠ **别跑不带 `--files` 也不带 `--all-files` 的裸 `pre_commit run`**（会 stash 掉别人在飞的改动）；判读口径 → `docs/门禁说明/generated-fresh.md` §4。
## 六、提交
生成器脚本（源）+ `docs/images/<主题>.svg`（产物）+ 引用它的 `.md` + `tools/arch_diagram/README.md`「产物清单」那一行**同一笔**提交；PNG 预览不入库。
```powershell
& '.venv\Scripts\python.exe' -m pre_commit run --files <脚本> <svg> <md> <README.md>
```
## 陷阱（本窗实测）
- **想装渲染器再转 PNG**：`cairosvg` 不在 `.venv`（`ModuleNotFoundError`）、`requirements.txt` 里也没有，`rsvg-convert` / `inkscape` / `magick` 这台机器上都不存在 → 用 §三 的 headless Chrome/Edge（权威命令在 `docs/架构设计/图形绘制流程.md` §四，2026-10-30 已同步成这套，别再往回写）。**没真渲染出 PNG 的情况下不要声称"已目检"。**
- **`--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 明令勿手绘）。一切修改都落在生成器常量上再重跑。
- **批量改生成器时 `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 / 躲过门禁），后者污染"临时目录多了文件"判定。
## 验证清单
- [ ] 生成器输出 `OK … bytes, canvas WxH`，**无** `OVERFLOW WARN` / `!! N overflow warnings`；`grep -n "def emit"` 命中、`grep -c print` = 0。
- [ ] 绝对路径 PNG 存在、尺寸 = 画布，`read_image` 回读确认：无文字压框 / 溢出、无标签互撞、无 `…` 截断收尾、配色在调色板内。
- [ ] 连跑两次产物 sha1 不变；`scripts/check_generated_fresh.py` rc=0（无 DIFF / NEW，`[BASELINE]` 未增加）。
- [ ] 大图（≥20 边）：跑一遍 §三b 的碰撞审计，报数归零（标签压框 / 走线穿框 / 标签出画布）。
- [ ] 引用它的 `.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 为准，规范条文以该文档为归属。
.dsh/skills/draw-diagram/reference/svg-collision-audit.py
+154
View File
@@ -0,0 +1,154 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""一次性碰撞审计（拷进 `ci-artifacts/` 用，**不要放进 `tools/arch_diagram/`**）：
解析自己生成的 SVG，报「边标签压节点 / 走线穿框 / 标签互压 / 文字出画布 / 节点文字出框 /
标签余量过窄」，并打印最紧的三条「标签文字 ↔ 最近框」水平余量。
为什么需要它：`check_fit` 预检只量**框内**文字；几十框几十边的大图，
标签压框与走线穿框在缩略 PNG 里根本看不全（实测 42 框 37 边报出 23 条），
而像素回读又慢又主观。解析产物是确定性的。
依赖：待审图对应的生成器模块必须能被 import（脚本靠它复用同一把估宽尺子 `text_w()`
与几何常量 `CW` / `CH` / `EDGE_FONT` / `ECOL`，两边同尺子才不会假绿）。
生成器侧要求：边标签白片用 `fill-opacity="0.94"`、节点框用 `fill="#ffffff"` 且
`width==CW`、`height==CH`（本脚本靠这两条分诊）；文字用 `<text font-size fill>`。
**这一遍照不到的东西**（别把它当唯一判据）：
- 走线检查必须把框**内缩**几像素，否则合法的「线接在框边上」会全报成穿框——从 SVG
反推不出哪两个框是本边的端点。代价：1~3px 的切边也照不到。要零余量就在**生成器侧**
再用 `Box` / `route()` / `label_at()` 的真值扫一遍（线段 vs 不膨胀的框，只跳本边两端）。
- 白片比通道宽一点、被节点白底盖住边角：无害（白片先画、节点后画），不用改；
要盯的是**文字**的余量，上面那三条数就是。
- 自写的判据脚本先拿一条**已知干净**的边验它不报，再信它的「0 条」：实测一条
`hi > x0` 写成 `hi > y0` 的复制粘贴错，凭空报出 3 条「穿框」，差点为此重排走线。
用法（仓库根）：
python ci-artifacts/label_audit.py <生成器模块名> [svg 路径]
# 例：python ci-artifacts/label_audit.py gen_arch_endtoend_svg
# python ci-artifacts/label_audit.py gen_wave_record_flow_svg docs/images/故障录波数据流.svg
退出码：0 = 无问题，1 = 有问题（打印明细）。
别的生成器若没有同名常量（多数用 `CHIP_FONT` / 自己的线色变量），改脚本顶部 `EDGE_COLORS` 与 `edge_labels` 那两处筛选即可——估宽必须继续用该生成器自己的 `text_w()`，别换一把尺子。
"""
import sys
import xml.etree.ElementTree as ET
sys.path.insert(0, "tools/arch_diagram")
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
mod_name = sys.argv[1]
G = __import__(mod_name)
svg_path = sys.argv[2] if len(sys.argv) > 2 else G.OUT
MASK_OP = "0.94" # 边标签白片的 fill-opacity（生成器侧约定）
EDGE_COLORS = set(G.ECOL.values()) # 边标签颜色（生成器侧的线色表）
def box_of_text(el):
"""<text> → (x0, y0, x1, y1, 文本, 字号, 颜色)。baseline y 之上约 0.85em、之下 0.22em。"""
x, y = float(el.get("x")), float(el.get("y"))
fs = float(el.get("font-size"))
s = "".join(el.itertext())
w = G.text_w(s, fs)
a = el.get("text-anchor", "start")
x0 = x if a == "start" else (x - w / 2 if a == "middle" else x - w)
return (x0, y - fs * 0.85, x0 + w, y + fs * 0.22, s, fs, el.get("fill"))
def area(a, b):
ix = min(a[2], b[2]) - max(a[0], b[0])
iy = min(a[3], b[3]) - max(a[1], b[1])
return ix * iy if (ix > 0.5 and iy > 0.5) else 0.0
def segs_of(d):
n = [float(v) for v in d.replace("M", " ").replace("L", " ").replace(",", " ").split()]
pts = list(zip(n[0::2], n[1::2]))
return list(zip(pts, pts[1:]))
def seg_hits_rect(sg, r, m=2.0):
"""轴对齐线段 vs 矩形（内缩 m 排除贴边的合法端点）。斜段一律算可疑。"""
(x0, y0), (x1, y1) = sg
rx0, ry0, rx1, ry1 = r[0] + m, r[1] + m, r[2] - m, r[3] - m
if abs(y0 - y1) < 0.5:
return ry0 < y0 < ry1 and min(x0, x1) < rx1 - m and max(x0, x1) > rx0 + m
if abs(x0 - x1) < 0.5:
return rx0 < x0 < rx1 and min(y0, y1) < ry1 - m and max(y0, y1) > ry0 + m
return True
root = ET.parse(svg_path).getroot()
W, H = float(root.get("width")), float(root.get("height"))
texts, nodes, masks, paths = [], [], [], []
for el in root.iter():
tag = el.tag.split("}")[-1] # 去命名空间，否则一个都匹配不上
if tag == "text":
texts.append(box_of_text(el))
elif tag == "rect":
w, h = float(el.get("width")), float(el.get("height"))
x, y = float(el.get("x")), float(el.get("y"))
if el.get("fill") == "#ffffff" and abs(w - G.CW) < 0.6 and abs(h - G.CH) < 0.6:
nodes.append((x, y, x + w, y + h, "node"))
elif el.get("fill") == "#ffffff" and el.get("fill-opacity") == MASK_OP:
masks.append((x, y, x + w, y + h, "mask"))
elif tag == "path" and el.get("fill") == "none":
paths.append(segs_of(el.get("d")))
edge_labels = [t for t in texts if t[6] in EDGE_COLORS and t[5] == G.EDGE_FONT]
bad = []
for lb in edge_labels:
b = lb[:4]
for n in nodes:
a = area(b, n)
if a > 6: # 压到框边 6 px² 以上就会被节点吃掉半个字
bad.append("标签压节点 %-12s 压 node@(%.0f,%.0f) %.0f px²" % (lb[4][:12], n[0], n[1], a))
for ob in edge_labels:
if ob is not lb and area(b, ob[:4]) > 6:
bad.append("标签互压 %s / %s" % (lb[4][:10], ob[4][:10]))
if b[0] < 2 or b[2] > W - 2 or b[3] > H - 2 or b[1] < 2:
bad.append("标签出画布 %s box=(%.0f,%.0f,%.0f,%.0f) 画布 %.0fx%.0f"
% (lb[4][:12], b[0], b[1], b[2], b[3], W, H))
for segs in paths:
for sg in segs:
for n in nodes:
if seg_hits_rect(sg, n):
bad.append("走线穿框 (%d,%d)-(%d,%d) 压 node@(%.0f,%.0f)"
% (sg[0][0], sg[0][1], sg[1][0], sg[1][1], n[0], n[1]))
break
# 「节点文字出框」只能按几何判：文字中心落在某个节点框里，却没被该框完整包住。
# 别拿 font-size 当筛选——本仓惯例里副题字号 = 边标签字号 = 脚注字号（9.5），按字号筛会全灭。
for t in texts:
cx, cy = (t[0] + t[2]) / 2, (t[1] + t[3]) / 2
host = [n for n in nodes if n[0] <= cx <= n[2] and n[1] <= cy <= n[3]]
for n in host:
if not (t[0] >= n[0] - 1 and t[2] <= n[2] + 1 and t[1] >= n[1] - 1 and t[3] <= n[3] + 1):
bad.append("节点文字出框 %r 超 node@(%.0f,%.0f)" % (t[4][:16], n[0], n[1]))
break
# 余量比「有没有压上」更早暴露问题：本仓约定边标签整段落在框间通道里，
# 只要文字离最近框 < 3px，字宽估算稍偏（本脚本与生成器共用同一把尺子，
# 但真实字体度量和它有出入）就会被后画的节点吃掉笔画。
MIN_CLEAR = 3.0
clears = []
for lb in edge_labels:
b = lb[:4]
worst, wid = None, None
for n in nodes:
if min(b[3], n[3]) - max(b[1], n[1]) <= 0: # 竖直方向不相干
continue
c = max(n[0] - b[2], b[0] - n[2]) # 正=间距，负=压进去多深
if worst is None or c < worst:
worst, wid = c, (n[0], n[1])
if worst is not None:
clears.append((worst, lb[4][:12], wid))
if worst < MIN_CLEAR:
bad.append("标签余量过窄 %r 距 node@%s 仅 %.1fpx（< %.1f）"
% (lb[4][:12], wid, worst, MIN_CLEAR))
seen = []
for b in bad:
if b not in seen:
seen.append(b)
print("%s：边标签 %d / 节点 %d / 文字 %d / 路径 %d"
% (svg_path, len(edge_labels), len(nodes), len(texts), len(paths)))
for c in sorted(clears)[:3]:
print(" 最紧余量 %.1fpx 标签 %r 邻 node@%s" % (c[0], c[1], c[2]))
for b in seen:
print(" ! " + b)
print("合计问题 %d 条" % len(seen))
sys.exit(1 if seen else 0)
.dsh/skills/font-regen/SKILL.md
+6 -1
View File
@@ -14,6 +14,10 @@ whenToUse: UI 代码新增中文文案、用户报告屏幕缺字/空白块、
# 1. 代码落库（新界面字符串已写入 ui_menu.c / ui_content_page.c 等 UI 源码）
# 2. 提取字符集（纯标准库，任意 python3 均可）
python tools/font_gen/extract_cn.py # 扫描 UI 源码字符串 → 仓库根 ui_cn_chars.txt
# ⚠ extract 只认"当前源码字面量"，会把清单里 KEEP_EXTRA 那批**刻意保留字**（历史落盘
# 记录用字，逐条理由见 check_font_charset.py 的 KEEP_EXTRA 字典——不在本文列举，列举必
# 然过期）从 txt 洗掉：跑 make_font 前必须把它们并回 ui_cn_chars.txt，否则 font-charset
# 门禁 A 段 FAIL 并逐字打印保留理由；事故路径实名登记见 docs/门禁说明/font-charset.md §6.1
# 3. 生成字体（需 fontTools，一律用 .venv；宋体 .ttc 的 face0 抽取与 ▶ 箭头补回均自动完成，幂等）
.venv\Scripts\python.exe tools/font_gen/make_font.py
# 变体：--bpp 2（宋体细笔画发虚时）/ --font C:/path/to/font.ttf（换字体）
@@ -30,4 +34,5 @@ python tools/font_gen/extract_cn.py # 扫描 UI 源码字符串 →
- `requirements.txt` 必须**纯 ASCII**（Windows 下 pip 按 GBK 解码，中文注释 → UnicodeDecodeError）
- 生僻字（宋体可能无字形）→ **写码前先手动验证字形**，避免"代码写完才发现是空白"
- 生成成功后跑 `ui-verify` skill 全回归；黄金参考因字形变化而 FAIL 属预期 → `check_content_pages.py --update` 刷新
- 字数变化时同步更新文档中的字符集计数（当前 97 汉字 + ASCII 0x20-0x7E，共 193 字形）：`UI_中文字体生成与配置.md`、`UI_界面制作流程.md` C3、`UI_设计架构.md`、`simulator/README.md` 已知坑 #4
- 字数变化时同步更新文档中的字符集计数（当前 **224** 汉字/符号 + ASCII 0x20-0x7E，共 **319** 字形；2026-10-29 实测：`ui_cn_chars.txt` 唯一码点 224、`ui_font_cn_12.c` 的 `.bitmap_index` 320 条含 notdef → 319 字形。历史上 119/214 → 179/274 → 185/280 → 218/313 均为当时快照）：`UI_中文字体生成与配置.md`、`UI_界面制作流程.md` C3、`UI_设计架构.md`、`simulator/README.md` 已知坑 #4
- **新增字低于既有最小码位**（如 Ⅰ U+2160）会下探稀疏 cmap 起点并吞掉单码位补回条目（实测 ▶ 箭头全变方框而旧版 coverage 全绿）——`make_font.py`（2026-10-25 起）按 LVGL 首命中语义插入/守卫/校验，扩字后模拟器像素回归**必跑**
.dsh/skills/id-family-semantic-migration/SKILL.md
+119
View File
@@ -0,0 +1,119 @@
---
name: id-family-semantic-migration
description: 编号族整族清退/停发 playbook：把一个编号族（字母+数字如保护功能号 L1-x~L5-x、网络条目号 F-*、登记簿旧号 N-x、台架阶段裸形 T1~T3、用例号 TC-*，或中文前缀「卡」+ 数字这类门禁语料里**没有机器识别面**的族）在全仓代码注释、测试、活文档与门禁配置里改成语义短语（含销项删行与逐号换算表入档），或把「不清退」裁定写成硬口径入档。触发语：清退某族编号、编号改成语义名或语义短语、还有多少号可清、残留多少、批次二/批次三/批次五、「卡 0」「卡 0b」「卡 1~12」、销项删行并去除相关编号、id-check 报悬空引用或不可判定超限、不可判定引用绝对数涨点、「这一族不做了」。
whenToUse: 用于**整族**处理：先判这一族有没有机器识别面 → 清点存量 → 逐族分类 → 分批派单清退 → 收口 → 回写 docs/编号规范.md 对应节。单条待办行销项并写 void 别名用 ledger-row-retire-void-id；某个事实数（页数、叶数、钩子数）变了要同步全仓用 stale-doc-count-sweep；单个文件改名或挪目录用 scripts/rename_ref.py；跑 HEAD 版对照组用 task-worktree 的净室 worktree。这四类不由本技能覆盖，但「涨点归因」一节会用到净室 worktree。
version: 1.1.0
---
# 编号族清退成语义标识
**2026-10-29 用户裁定：全族一律停发**（含 `docs/编号规范.md` §4.1 那五个存量族）——本 playbook 的「停发」分支默认已成立，
现在唯一还需要决策的是**要不要清退存量**（全仓改语义 + 销项删行 + 逐号换算表入档）。
**动手前先判这一族有没有「机器识别面」**——它决定计数口径的来源与落地去处，两条路的做法**正好相反**：
| 族形态 | 计数口径来源 | 改名手段 | `scripts/archive/id_gate/id_aliases.json` |
|---|---|---|---|
| 字母+数字，且在 `scripts/archive/id_gate/check_ids.py` 语料内（`id_registry.json` 有族、族 pattern 能匹配它） | 门禁自身计数（`ck.refs` / `ck.stats` / 报告行） | `scripts/rename_ids.py`（映射表 + 显式 scope + 默认干跑） | **要登记**：死号 `void`、转短语 `retired-to-phrase` |
| 中文前缀（「卡」+ 数字）、纯散文里的号、圈号 ①②③ | **自建带标签正则扫描器**（门禁看不见它，2026-10-28 退役前的 id-check 全库报告与本族无关；两道门禁现都已退役（2026-10-28 / 2026-10-29），要普查形态就手工跑归档脚本 scripts/archive/id_gate/check_ids_new.py --range） | 逐处替换 + 断言命中数（`rename_ids.py` 靠族 pattern 驱动，这里用不上） | **刻意不登记**：登记了机器也看不见，只多一张没人核的表；停发只靠规范 + 评审 |
怎么判（三条，任一为否即无识别面）：① `grep -nE '"name"|"pattern"' scripts/archive/id_gate/id_registry.json`，没有任何族 pattern 能匹配该形态；② `./.venv/Scripts/python.exe scripts/archive/id_gate/check_ids.py --top 0` 的任何校验里找不到它；③ registry 的 `blind_spots` 已明写不判（圈号与正常列举无法机械区分、裸形同字母多义只在属主登记处判）。实测：「卡」+ 数字**没有族**（中文形态只有 `malformed` 里 `陷阱 ?[0-9]` 那条禁令，管的是陷阱编号不是卡号），该族真实站点 288 处 / 56 文件，而门禁对它贡献 0。
判错的代价是双向的：拿门禁计数当中文字面量族的口径 → 得出「0 处待改」的**假归零**；给无识别面的族登记别名 → 制造「有机器兜底」的错觉，真正生效的两条（§4.1.1 停发行、§9.3 换算表）反而没人写。
其余铁律照旧：**不要凭 grep 估数、不要凭印象决定改哪几处、不要把「不做」只划掉一行。**
## 口径：三套计数都要挑明，先问再比
| 口径 | 怎么数 | 用途 |
|---|---|---|
| 门禁 refs（去重） | `ck.refs`：字面量 → 文件集合，**只记属主登记处文档之外**的引用 | 门禁趋势、批次验收线 |
| 逐行站点 | 按族正则重扫 `ck.iter_files()` 语料，**含属主文档的定义行** | **排工作量、拆单** |
| 自建扫描器站点 | 无识别面族：带标签正则全仓 walk（排除 `.git`） | 该族唯一口径，**不能拿 id-check 输出代替** |
实测例：保护功能号一族「字面量 28 / 站点 184 / 文件 58」（`ck.refs`）与队友报的「219 站点 / 38 文件」并存且都对。队友报任何合并数（指纹、站点数）之前**先问口径**，不要拿自己的数去否他的数。**每个数字标明是本回合实测、动手前基线还是沿用昨日值**；**形似噪声号另立分母**（中文族一节第 4 步），绝不与待清族合并成一个总数。
## Steps（字母+数字族：门禁看得见的那一路）
1. 确认范围与定调
2. 按族实测三口径（字面量 / 站点 / 文件），不用 grep 估数
3. 逐族先分类再动手
4. 映射表由属主文档生成
5. 按写域拆道并行派单
6. 门禁配置注释也是本族写入面
7. 每处替换断言命中数
8. 同步更新门禁侧配置
9. 生成器文本改动必须同笔重跑产物
10. 核队友交付
11. 分笔提交走真实 pre-commit 钩子
12. 收口只认门禁自身计数
13. 回写 docs/编号规范.md
14. 裁定「不做」也要写成可执行硬口径入档
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [steps-alpha-numeric-family.md](reference/steps-alpha-numeric-family.md)。动手前先读那篇。
## Steps（中文前缀族：连归档扫描工具都咬不到的那一路）
1. 先确认连归档扫描工具也咬不到（两道编号门禁 2026-10-28 / 29 已退役，"咬不咬"从此只是工具层面的事），并把这句话写进交付
2. 销项删行前先核证据属主
3. 自建带标签正则扫描脚本
4. 该族与形似噪声号分开计数，各自给分母
5. 派单前写一份 spec 文件
6. 逐处替换断言命中数
7. 落地位置写死（这一族只有这几条兜）
8. 替换后三道二次清洗
9. 收尾复跑 + 清中间产物
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [steps-chinese-prefix-family.md](reference/steps-chinese-prefix-family.md)。动手前先读那篇。
## 不可判定引用绝对数涨点的净室归因
「不可判定引用绝对数」比今日低点涨了 N 处时：
1. **禁止**用「对提交新增行 grep 字母+数字形态」归因：`git diff -U0` 的加行里绝大多数文本是从旧行搬来的**存量上下文**（注释整段重写、表格加一列、Markdown 重新折行），形态匹配数出来的是「哪段文字最近被搬动」，不是「哪里涨了 N 处」——用它归因必然把老引用算成增量。`diff -U0` 只在**已定位到文件之后**用来绑笔次与行号。
2. **正解 A（首选，同一计数器相减）**：在**仓外 detached worktree 跑 HEAD 版**（`task-worktree` skill 的净室测量仪；不 stash、不碰在飞工作区），两边都用同一个 `check_ids.py` 计数器导出 `(rel, literal)` 多重集（`ck.findings` 或 `err_groups(ck)`），做**逐文件集合差**，落差的 N 处直接指向具体文件与字面量。
3. **正解 B（逐文件注入）**：一次只把一个文件换成在飞版跑计数器——涨点在哪个文件上，就只在注入它时出现；文件多时按 `git diff --name-only` 折半。
4. **当轮跑不完就如实说**：本轮未跑净室归因时，只报「现值需要重新实测」并说明**需要跑净室归因**，**不得**给出候选归因对象，**不得**把上一轮的现值或余量当本回合实测值报出（每个数标明来源与时刻）。
5. 与其它交付口径冲突的差值**登记为待查项**（两套计数可能都对），不当场判谁对谁错。
## Pitfalls
- 拿门禁计数当中文字面量族的口径
- 给无机器识别面的族登记 id_aliases.json
- 拿 grep 计数跟人吵口径
- heredoc 里嵌 Python 正则 / 中文
- 扫描没排除 .git
- 凭记忆敲 old 串
- 替换后不做同句重复检测
- 换算表里复述字面量
- | head 之后读 $?
- 占位符泄漏
- 删行前不核证据属主、不查当初为什么保留
- 涨点归因拿 diff 新增行 grep 形态
- 全局查找替换
- 未分类就动手
- 按简称匹配文件清单
- 复现不了队友的合并指纹就怀疑丢文件
- 替换 token 含
- 只改生成器文案不重跑产物
- grep 'A\|B' 空返回当文件干净
- 一次 run_code 串 5 × wait_agent(118000) ≈ 590s 整段 abort、进度全丢
- 游标整型比较静默不生效
- git add 目录路径带进别道文件
- amend 被 gitlint B1 拦
- 改「只动注释」要拿机器证据
- 冻结历史与原始证据不改
- *.uvprojx 抖动不入库
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [pitfalls.md](reference/pitfalls.md)。动手前先读那篇。
## Verification
1. `scripts/archive/id_gate/check_ids.py --strict` 与 plain **均 rc=0**（`[OK] 校验 1~6 无错误`），悬空引用为 0。
2. 编号字面量与**不可判定引用绝对数**只降不升、不超 `undecidable_total_ceiling`；可判定比例不低于 `id_registry.json` 基线（86.0%）。
3. 本族剩余站点复扫归零：有识别面族从 `ck.refs` 按族正则过滤字面量逐条打印；除冻结历史/原始证据行外无残留。
4. `pre-commit run generated-fresh --all-files` PASS + 目检 svg diff 只有文案与框宽自适应（只在动过生成器时适用）；`check_doc_links.py --all` 通过。
5. `/keil-build`：`BUILD=0`、0 错 0 警、`Program Size` 与改前同数（零行为改动证据，**本回合真跑**）；相关主机组（如 `net_socket 457/457`）全绿。
6. 真实 pre-commit 钩子全绿（如 `passed=33 failed=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 与中间产物已删。
11. 门禁复跑清单齐：`check_ids.py` plain + `--strict`、`check_doc_links.py --all`、`bom-guard`、`no-mojibake`、`git diff --check`、`/keil-build` 或受影响单测——**每个数字标明是本回合实测**。
.dsh/skills/id-family-semantic-migration/reference/pitfalls.md
+30
View File
@@ -0,0 +1,30 @@
# Pitfalls（自 SKILL.md 外置）
> 本文由 id-family-semantic-migration 的 SKILL.md「Pitfalls」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
- **拿门禁计数当中文字面量族的口径** → 得出「0 处待改」的假归零（实测该族真实站点 288 处 / 56 文件）；先跑自建扫描器报「站点 / 文件」，并在交付里写明该族不在语料内、门禁判不到。
- **给无机器识别面的族登记 `id_aliases.json`** → 中文前缀不进语料，登记了机器也看不见，只制造「有门禁兜底」的错觉；执行面是 §4.1.1 停发行 + §9.3 换算表 + 评审。反过来，有识别面的族不登记别名 → 门禁把旧号引用判成悬空。
- **拿 grep 计数跟人吵口径**：先拿实测三口径，再谈拆单；两套计数不一致不是有人算错（见上表）。**形似噪声号并进总数** → 把 132 处里程碑噪声算进 420 处待改，动手就改坏 `docs/芯片手册/` 原文。
- **heredoc 里嵌 Python 正则 / 中文** → `invalid escape sequence` 与语法错；脚本落文件再跑。中文正则用 **raw 串 + `\uXXXX`**：非 raw 串的 `"\b"` 会被解成退格符，正则**静默失配不报错**。
- **扫描没排除 `.git`** → `.git/COMMIT_MSG_*.txt` 的 GBK 乱码历史被当残留，越清越多；**靠控制台看中文** → 一律写 UTF-8 报告文件再解析，判乱码统计 `EF BF BD` 字节数。
- **凭记忆敲 `old` 串** → 中文引号与 ASCII 双引号形态不同，命中 0；回读原文取真身，断言前先看 `git status` 自证文件未变。
- **替换后不做同句重复检测** → 留下「运行参数段（「数据可信」运行参数段交付）」这类句子（实测 12 行）；**同一短语两种空格形态不归一** → 全仓口径漂移（归一前先 `git grep -c -F` 数各形态）。
- **换算表里复述字面量** → 讲规则的文档变成自己的引用站点（规范本身在门禁语料里）。
- **`| head` 之后读 `$?`** → 永远是 0，把「还有残留」当「已归零」。
- **占位符泄漏**：为躲转义把反引号写成 `«` / `»` 再全文替换，落盘后**必须核占位符残留 = 0**（实测 22 行泄漏到本节之外，含不是自己写的行）。
- **删行前不核证据属主、不查当初为什么保留** → 要么删掉唯一记录，要么把已撤销的「✅ 保留行」例外当常态。
- **涨点归因拿 diff 新增行 grep 形态** → 把存量上下文当增量；**把上一轮现值当本回合实测**、未跑净室归因就报具体归因对象 = 猜测。
- **全局查找替换**：跨族撞号（`S3` 三义）。必走 `rename_ids.py` 映射表 + 显式 scope + 干跑；无识别面族则逐处手写 + 断言命中数。
- **未分类就动手**：把变压器位号、Mermaid 节点名、数学记号、gitlint 规则名当编号改坏硬件资料；位号目录进 `excluded_paths`，记号进噪声表。
- **按简称匹配文件清单** → 误报 8 个文件丢失；比对前展开真实路径。
- **复现不了队友的合并指纹就怀疑丢文件**：先问口径（自定义顺序不可复现），改落自有逐文件 16 位基线并把跨道文件单列。
- **替换 token 含 `**` 加粗标记** → 命中数断言 0；取反引号最小形态。
- **只改生成器文案不重跑产物** → `generated-fresh` 必红（实证 `0f7b5a87` 同类）；「反正就是注释，不影响图」是错的，该文本进产物。
- **`grep 'A\|B'` 空返回当文件干净**：交替竖线在多层 bash 引号里被吃掉，是探针坏不是文件干净 → 反证为空的搜索必须换 `grep -F` 复测。
- **一次 run_code 串 `5 × wait_agent(118000)` ≈ 590s 整段 abort、进度全丢**；且一次串多条长中文 `send_message` 也撑爆 120s（发出 1 条后 abort，剩余未发）。轮询上限 4×118s，长消息拆开发。
- **游标整型比较静默不生效**（字符串形态）；抬完用 `--strict` 与 plain 双验。
- **`git add` 目录路径带进别道文件**、`git add -A` 卷进在飞改动；撤销自己的改动只按文件点名 `git restore scripts/archive/id_gate/id_registry.json`，不碰同树其它道文件。
- **amend 被 gitlint B1 拦**：正文行 >80，别把 ASCII 双引号写成正文首字符。
- **改「只动注释」要拿机器证据**：`/keil-build` 0 错 0 警且 `Program Size` 与改前**逐字节同数**（本回合真跑，引用历史提交正文自报的数字不算证据），别口头承诺。
- **冻结历史与原始证据不改**：boot 串口日志等采集现场是冻结证据，改了就是篡改；历史「修改记录」行按裁定保持改名后形态（号已全仓退役，留一个查无此号的引用比留改过名的条目更坏）。
- **`*.uvprojx` 抖动不入库**；`ci-artifacts/` 里的 spec 与扫描中间产物收尾删掉，别当交付物留下。
.dsh/skills/id-family-semantic-migration/reference/steps-alpha-numeric-family.md
+66
View File
@@ -0,0 +1,66 @@
# Steps（字母+数字族：门禁看得见的那一路）（自 SKILL.md 外置）
> 本文由 id-family-semantic-migration 的 SKILL.md「Steps（字母+数字族：门禁看得见的那一路）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
1. **确认范围与定调**：先按开头的表判识别面（无识别面 → 走下一节）；再读 `docs/编号规范.md` §4.1（族总表，穷举）、§4.1.1（已停发栏），存量与批次见 `scripts/archive/id_gate/编号治理历史.md` §9，明确本族属主登记处（`owner_docs_glob`）；旧判据「有脚本按字面量匹配它」自 2026-10-29 起作废——全族一律停发。清退 = 全仓改语义；停发 = 在规范表里写死不再新增引用（`id_registry.json` 的游标冻结只是裁定留痕，2026-10-29 起无机器读者）。
2. **按族实测三口径（字面量 / 站点 / 文件），不用 grep 估数**。`Checker.refs` 是 **dict（字面量 → 文件集合）不是方法**，`ck.refs(fam)` 这种写法会 `TypeError`；站点数门禁不直接给，用族正则重扫它自己的语料：
```python
import sys; sys.path.insert(0, "scripts")
import check_ids as ci
reg = ci.load_json(ci.REGISTRY_FILE, "r"); al = ci.load_json(ci.ALIASES_FILE, "a")
ck = ci.Checker(reg, al); ck.run() # run() 填充 refs / stats / findings
for name in ("N", "S-LDG", "TC", "FEAT"): # 族名以 id_registry.json 的 "name" 为准
rx = next(f for f in ck.families if f["name"] == name)["_re"]
lits = {l for l in ck.refs if rx.fullmatch(l)} # 字面量（属主文档之外）
files = {r for l in lits for r in ck.refs[l]} # 文件
sites = sum(len(rx.findall(line))
for rel in ck.iter_files() # 与门禁同一语料
for line in ck.read(rel).splitlines()) # 含属主文档定义行
print(name, "literals", len(lits), "sites", sites, "files", len(files))
```
全库扫一遍不便宜（数十秒量级）：可丢后台 job，不要和别的长活串在同一个 120s 预算里。把活族清单与每族数字记下来作为**动手前基线**（拆批次与派单依据）。新测试套件发号导致 `id-check` 校验 3 报悬空引用时，**先按号前缀聚合**定位是哪个套件/哪个族（`check_ids.py 2>&1 | grep -a '悬空引用' | ...` 前缀计数），别逐条读。
3. **逐族先分类再动手**——不是每个命中的裸形都是编号，四类分治（实测 T1/T2/T3 的 41 处里只有部分是编号）：
- 真编号 → 语义短语 / 功能名；
- 硬件位号（变压器 T1~T3 等）→ 把目录整目录登记进 `check_ids` 的 `excluded_paths`（如 `excluded_paths += tools/netlist_semantics/`），**不逐处改位号名**；
- Mermaid 流程图节点名 → 改语义名但**节点数与连线关系不变**，图结构不动；
- 数学记号 → 进噪声表；门禁自身的规则名（gitlint `T2 Title has trailing whitespace`）→ 不改。
分类前先把剩余每处原文打出来看（`grep -F` 逐文件），否则会把硬件资料改坏。
4. **映射表由属主文档生成**：从属主文档取「编号 → 功能名/语义短语」全表（实测 42 个定义 / 28 个在用），改名走 `scripts/rename_ids.py`（映射表驱动 + **显式 scope** + **默认干跑** + 自动往 `scripts/archive/id_gate/id_aliases.json` 写 scoped 旧号→新号条目，状态 `renamed` / `retired-to-phrase` / `void`）。**绝不全局查找替换**：同一裸形字面量可能同时属多个族（实测 `S3` 三义），全局替换等于造新撞号。
5. **按写域拆道并行派单**（代码与测试半 / 文档半 / 某功能面各一条道），同笔用 `send_message` 下发**统一改写口径**（措辞、是否动字符串字面量、生成器归属、冻结历史行怎么处理），避免各道自定措辞；口径长就先落成 spec 文件（中文族一节第 5 步的做法同样适用）。看板任务只认 `team_task_update` 的 `task_id` / `expected_revision` / `action=reassign` / `owner` 四个字段。
6. **门禁配置注释也是本族写入面**：`.pre-commit-config.yaml` 的注释里会挂着功能号（实测 `7h) ADC 采样有效性校验（语义取数与有效性层）`、`7i) 保护定值模型（P1 / 动作留痕层载体）`、`规划 §3.3 保护判据层`）。配置属 Lead 写域，Lead 自己改（注释不占钩子行为、不影响 51 条钩子口径），但**必须计入批次范围并在提交正文写清是 Lead 改的 config**。
7. **每处替换断言命中数**，不做整文件正则批量改写（批量改写会静默漏改）：
```python
def sub(path, pairs):
p = pathlib.Path(path); t = p.read_text(encoding='utf-8')
for old, new, want in pairs:
got = t.count(old); assert got == want, (path, old, got, want)
t = t.replace(old, new)
p.write_text(t, encoding='utf-8')
```
**token 取最小形态**：文档里被反引号/加粗包住的号，替换单位取反引号形（```T4```）而**不含 `**` 标记**（第 225 行是 `**裸形 `T4`**`，按「裸形 `T4`」替就命中 0）。讲编号的文档改成**形态描述**（如「字母 T 紧跟数字 4」）能把不可判定绝对数还回余量：实测 4 处 → 982 降到 978，且 lesson 不丢。
8. **同步更新归档扫描器的配置**：`check_ids` 的 `excluded_paths` 与噪声表按第 3 步的分类结果改，使剩余命中不再是「假编号」；新测试套件发号的悬空引用要先定**定义位**：
- 定义位**只能落一处**——注册表族（`scripts/archive/id_gate/id_registry.json`）或该套件说明文档，**两处并存比没有定义位更坏**；文档真写出来了（含判据与上板清单）就以文档为准、**撤族**；
- 要建族就照现有同类族克隆（`pattern` / `digit_width` / `owner_docs_glob` / `scope` / `cursor`），别自造字段；
- **抬游标前先确认游标是字符串形态**（`'cursor': 'TC-UIDATA-026'`）——整型比较会静默不生效（实测踩坑），用字符串解析或正则取序号再比。
9. **生成器文本改动必须同笔重跑产物**：`tools/arch_diagram/gen_*.py` 里的 docstring/文案会进产物，`generated-fresh` 把生成器拷到临时目录重跑逐字节比对，**只改源不改产物必红**。这类站点整包转给生成器属主，「谁改谁跑生成器」，脚本 + 全部 svg 产物同一笔：
```bash
./.venv/Scripts/python.exe tools/arch_diagram/gen_net_instability_svg.py 2>&1 | tail -3
pre-commit run generated-fresh --all-files # 单钩子复跑必须带 --all-files 或 --files
```
⚠ **不带这两个参数的裸 `pre-commit run` 会进 staged_files_only 上下文并 stash 别道在飞的改动**（`docs/门禁说明/generated-fresh.md` §2）；`pre-commit` 不在 PATH 时改用 `& '.venv\Scripts\python.exe' -m pre_commit run generated-fresh --all-files`。PASS 后再目检 diff：只应文字变长、框宽自适应（526→551、右缘未越界、画布不变）。不把该站点从批次里悄悄丢掉：登记为「待未完成半批」，收口时核对。
10. **核队友交付**（按写域并行后必做）：
- 文件清单**先展开真实路径再比**：按简称匹配会误报丢失（作者列 `phasor.py`/`adc_health.py` 等 8 个，实为 `test/host/<模块>/run_unit_test.py`）；用 `git -c core.quotepath=false diff --name-only` 取全路径做集合差。
- 合并指纹对不上先问口径：作者按**自定义顺序**算的数 Lead 侧复现不了（`d0a289b7` vs 报的 `a45e7e2b`）。改建 **Lead 自有逐文件 16 位基线**存 `ci-artifacts/lead_lane_b_files.json`，并把**跨道文件单列**（实测 `App/algo/README.md`）——autostash 后按逐文件比对，不假称对上别人的合并数。
11. **分笔提交走真实 pre-commit 钩子**：`git add` 用显式清单。坑：`git add -- App/algo` 把文档道的 `App/algo/README.md`（26 处）带上车，正文按 48 只文件写就不准了 → 该笔未 push 时 `--amend` 挪到文档笔并补一句归属说明；`git add -A` 会把别道在飞文件卷进来（覆盖率钩子在他编译不过的半成品上报红）→ 撤出他人域后重跑。提交正文每行 ≤80（gitlint B1），别把 ASCII 双引号写成正文首字符。
12. **收口只认门禁自身计数**（**仅限语料内的族**；无识别面族见下一节第 8~9 步），并核**只减不增**：
```bash
./.venv/Scripts/python.exe scripts/archive/id_gate/check_ids.py 2>&1 | grep -aE '扫描|可判定 |不可判定引用' | head -4
./.venv/Scripts/python.exe scripts/archive/id_gate/check_ids.py --strict 2>&1 | tail -1 # [OK] 校验 1~6 无错误
```
报告「字面量 8787→8299→7828」「不可判定绝对数 1161→984→982→978（上限 1166）」「可判定比例 88.14%（基线 86.0%，容差 0.1pp）」。**绝对数与比例两根线都要报**：把可判定引用改成散文会稀释比值，所以另有不可判定绝对数上限。涨点归因见「净室归因」一节。
13. **回写 `docs/编号规范.md`**：§4.1 族表（停发/待清栏）、§4.1.1 已停发栏；存量表与批次结果表在 `scripts/archive/id_gate/编号治理历史.md` §9（只减不增、清点数字按最终实测同步）；表格若保留动手前的清点数，**明确标注「不是当前存量，是动手前基线」**，否则就是拿旧数当现状。**用户裁定原文与理由直接写进对应节**（§4.1.1 停发行 + 该族的批次结论段落）——2026-10-28 起不再往变更记录写流水（`docs/文档规范.md` §5.1）。
14. **裁定「不做」也要写成可执行硬口径入档**（不是只划掉一行——「不做」最容易被读成「那还可以继续发号」）：
- §4.1.1「已停发」栏新增该族一行：**游标冻结、现存号只减不增、新用例改用语义化测试函数名 + 文档表格行名**，并写清与 §4.1 存量族栏的关系（那五族 2026-10-29 起也一律停发）；
- 批次段落写明裁定原文与理由（归档 `scripts/archive/id_gate/编号治理历史.md` §9.1——§9 一族的事实源已在归档篇，规范正文只留口径）（该族是唯一真被脚本按字面量匹配的族：C 断言标签 + 测试函数名 + 文档用例表三处同一号），并给出**将来真要清退的前置条件**：追溯器（`check_test_traceability.py`）先同时认新旧两种形态、并行核对通过，**不许先改文档再改代码**；
- 全文核「等你裁定 / 需你裁定」悬空表述残留数归 0；
- 无机器识别面的族落地面不同（`docs/编号规范.md` §4.1.1 一行 + 归档 `编号治理历史.md` §9.3 换算表 + 叙述同步三处），见下一节第 7 步。
.dsh/skills/id-family-semantic-migration/reference/steps-chinese-prefix-family.md
+65
View File
@@ -0,0 +1,65 @@
# Steps（中文前缀族：连归档扫描工具都咬不到的那一路）（自 SKILL.md 外置）
> 本文由 id-family-semantic-migration 的 SKILL.md「Steps（中文前缀族：门禁咬不到的那一路）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
1. **先确认连归档扫描工具也咬不到，并把这句话写进交付**（两道编号门禁已退役，机器面整体消失）：`scripts/archive/id_gate/check_ids.py` 的族 pattern 是拉丁形态、中文前缀不进语料 → **id-check 的 refs / 可判定比例 / 悬空引用与本族无关**；报告开头写「本族不在 check_ids 语料内，口径 = 自建扫描器」。
2. **销项删行前先核证据属主**（这是删行的唯一许可证）：
- 先取历史口径：`git log --oneline -20 -- <文档>`、`git show <rev>:<文档> | sed -n '/^## 5/,/^## 6/p'` 找回被删的卡表与当初「完成即销项删行 / 标 ✅ 保留行」的理由；
- 核对判据与实测记录**已完整沉淀进属主章节**（实测：「已知电压注入验证」六项判据全 PASS、斜率 6544.2 码/V、偏差 −0.14 % 全在 `docs/硬件平台/ADC通道映射说明.md` §8.1，执行侧在 `docs/测试说明/专项验证/ADC前端注入验证流程.md`）；
- **删的是任务规划侧的行与结论块，不是证据本体**；被代码头注释指称的设计约束章节（§2~§4 那类）**原样保留**，只删已完成记录；
- 该行若当初是被「代码头注释按号引用」当例外保住的（实测 `App/task/adc_task.c` 的 v3.3 修订行按卡号当口径出处），必须**先把引用侧改成语义短语**，例外才成立撤销，并在规范里写明撤销理由（上一笔「完成即保留行」的例外就是这么随引用侧改动被撤掉的）；
- 删完逐行通读被改小节，报**行数变化**，不留孤立残句（实测 J7 dropped line 234 len=639、J13 闭环结论块 6 行删除并注明证据属主）。
3. **自建带标签正则扫描脚本**——四条硬规矩，全是实测返工换来的：
- 脚本**落文件**（`ci-artifacts/scan_ka_refs.py`）再跑，**不用 bash heredoc**（heredoc 里的 `\s` 被多层引号咬坏：`SyntaxWarning: invalid escape sequence` + 语法错）；
- 正则**一律 raw 字符串**、汉字写 `\uXXXX`：`KA = r"\u5361"`。非 raw 串里 `"\b"` 会先被 Python 解成退格符（0x08）→ 正则**静默失配且不报错**；`"\s"` 只是警告还能跑，`"\b"` 是真错；
- **排除 `.git`**（连同 `.venv`、`ci-artifacts`、`__pycache__`、`node_modules`）——实测扫进 `.git/COMMIT_MSG_*.txt`，一堆 GBK 乱码历史被当成残留，越清越多；
- 报告**写 UTF-8 文件**（`ci-artifacts/ka_refs.txt`）再本地解析，别靠控制台输出（Windows 控制台按 GBK 渲染中文 = 乱码）；判乱码统计 `EF BF BD` 字节数，别信终端渲染。
```python
# -*- coding: utf-8 -*-
"""扫描中文前缀任务卡号与同期形似噪声号；报告写 UTF-8 文件。"""
import io, os, re
KA = r"\u5361" # 卡
PATS = [("CARD_ANY", re.compile(KA + r"\s*[0-9]")),
("KA0B", re.compile(KA + r"\s*0b")),
("KA12", re.compile(KA + r"\s*12")),
("M4", re.compile(r"\bM4\b")),
("M5", re.compile(r"\bM5\b")),
("M6", re.compile(r"\bM6\b"))]
SKIP = {".git", ".venv", "ci-artifacts", "__pycache__", "node_modules"}
out = io.open("ci-artifacts/ka_refs.txt", "w", encoding="utf-8")
for root, dirs, names in os.walk("."):
dirs[:] = [d for d in dirs if d not in SKIP]
for n in names:
p = os.path.join(root, n)
try:
txt = io.open(p, encoding="utf-8", errors="ignore").read()
except OSError:
continue
for i, line in enumerate(txt.splitlines(), 1):
for tag, rx in PATS:
if rx.search(line):
out.write("===== %s\n" % p) # 同一行可命中多标签 → 按标签分别计数
out.write("%d [%s] %s\n" % (i, tag, line.strip()[:200]))
out.close()
```
末尾打 `TOTAL_SITES / FILES / SCANNED / 各标签计数`；**带标签**才拆得开噪声（同一行可同时命中 `CARD_ANY` 与 `KA12`）。
4. **该族与形似噪声号分开计数，各自给分母**：一遍扫描出 `TOTAL_SITES 420 FILES 85 SCANNED 1025`，必须再拆成**卡族 288 处 / 56 文件** 与 **里程碑噪声 132 处 / 44 文件**（`M4/M5/M6` 大片落在 `docs/芯片手册/` 参考手册与料号上下文里）。两套数字各自给分母——**「420 处待改」是错的**：把 132 处噪声算进清退范围就会去改芯片手册原文。噪声侧一律保持原样，是否清退等用户单独裁定，**不要顺手做**。
5. **派单前写一份 spec 文件**（`ci-artifacts/card_retire_spec.md`），作为各道唯一口径来源，含五块：① 背景与**用户裁定原文**；② 逐号映射表（旧号形态 → 语义短语 → 属主出处）；③ 措辞规则（补短语时括号怎么降级、动不动字符串字面量、生成器归属、悬空引用怎么判）；④ 硬约束（BOM 原样补回、行尾由 `.gitattributes` 写死、冻结历史行与原始证据不回改、代码头注释引用的设计约束章节保留、带 BOM 文件名单）；⑤ 自检与交付格式（逐文件命中数、删了哪几行、残留数、门禁复跑结果）。`send_message` 只发路径 + 关键裁定，长中文正文不要整段塞进消息（一次串多条长消息会撑爆 120s，发出 1 条后 abort，剩余未发）。
6. **逐处替换断言命中数**（同第 7 步的 `rep(tag, old, new, want)`），且 `old` 串**从原文取、不凭记忆敲**：本仓中文引号与 ASCII 双引号混用（实测某文档里的「中文引号」其实是 ASCII `"`），凭印象写 `old` 必 `got=0`；断言抛错后先 `git status --porcelain=v1 -- <文件>` 自证文件未被别道改动，再回读该行真身重跑。删行类改动单独记 tag 并打印删了几行、行号与原行长度。多道并行时同一文件常被别道改过：`edit` 报 `file changed since it was read` → 重新 `read` 再改；报 `ReplaceFileW EIO (Win32 1175)` → 先自证文件字节完好（BOM / CRLF / `EF BF BD` 三项）再重试同一笔，不要顺手改内容。
7. **落地位置写死（这一族只有这几条兜）**：
- `docs/编号规范.md` **§4.1.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 = 三项阻塞任务` → 两项）、`docs/任务规划/README.md`、`docs/任务规划/登记簿.md`——「剩余三项」这类旧口径实测归零；
- **与有识别面族的判别写进同一张表**：能被脚本按字面量匹配 → 走 `rename_ids.py` + 别名登记；匹配不到（中文前缀、纯散文号、圈号）→ 走规范换算表，**不登记别名**；
- 要机械化怎么办：得先给「中文前缀 + 数字」设计候选形态，属追溯机制改造，按 §7.3 单独开卡，**别夹在清退批里顺手做**。
8. **替换后三道二次清洗**（缺一必留疤，全部实测过）：
```bash
git grep -c -F '端子 / 子板变比确认' -- . ; git grep -c -F '端子/子板变比确认' -- . # 先数各形态再归一
git grep -nE '卡[ ]*[0-9]' -- . ; echo "rc=$?" # 裸跑读 rc；1 = 归零
```
- **同句重复短语**：编号位置补上的语义短语与原句已有短语撞车 → 扫「同一行里同一短语出现 ≥2 次」（实测 12 行，如 `.pre-commit-config.yaml:401`「运行参数段（「数据可信」运行参数段交付）」、`App/algo/README.md:110`「遥测快照发布（L2 发布侧，「数据可信」遥测快照发布）」）→ 改法是**把括号里的引用降级**成不含该短语的写法（「道D 交付项」「波次」「该点 DoD 原句」），逐处断言命中 = 1，别删信息；
- **空格与引号形态归一**：同一语义短语可能有 `端子 / 子板变比确认` 与 `端子/子板变比确认` 两种形态 → **先 `git grep -c -F` 分别数**（实测带空格 8 处），再整文件归一，归一后复扫到 0（残留常藏在表格单元格里，逐行打印定位）；引号形态同理；
- **固定正则复扫**：`卡[ ]*[0-9]` 全仓无输出。⚠ 判 rc 时**不要把命令接在 `| head` 之后再读 `$?`**（那拿到的是 `head` 的 0，会把「还有残留」读成「已归零」）。
9. **收尾复跑 + 清中间产物**：`check_ids.py`（plain 与 `--strict`）、`check_doc_links.py --all`、bom 与乱码两道（`pre-commit run bom-guard --files <改过的文件>`、`pre-commit run no-mojibake --files <改过的文件>`）、`git diff --check`；**纯注释/纯文档改动不算免编译**——仍跑一次 `/keil-build` 取「0 错误 0 警告」且 `Program Size` 与改前同数（**本回合真跑**，引用历史提交正文自报的四个数不算），受影响的主机组单测照跑。最后**删掉 spec 与全部扫描中间产物**，别往 `ci-artifacts/` 再堆 log/txt。
.dsh/skills/keil-build/SKILL.md
+115 -25
View File
@@ -1,7 +1,7 @@
---
name: keil-build
description: Keil MDK-ARM 命令行编译闭环（自带独立脚本 keil_build.py，纯标准库，拷到任何 Keil 项目即用）：UV4 -b 构建 → "0 错误 0 警告"判定 → build_log 定位报错。封装入口约定、退出码判读、UV4 改写工程文件的入库陷阱。
whenToUse: 需要编译 Keil MDK 工程、验证代码改动是否 0 错误 0 警告、或解读 UV4 构建日志时。
description: "Keil MDK-ARM 命令行编译闭环（自带独立脚本 keil_build.py，纯标准库，拷到任何 Keil 项目即用），覆盖 UV4 -b 构建、「0 错误 0 警告」判定、build_log 定位报错、PowerShell 与 bash 两种调用形态及各自的 exit 2 归属、退出码与 build 锁持有者名判读（含插件树的 pw: 前缀）、exit 2 时 UV4.exe 的候选路径探测与单次调用 env 注入闭环、UV4 改写工程文件的入库陷阱、构建副产物「%SystemDrive% 字面量垃圾目录」的取证、清理与入库排除。"
whenToUse: "需要编译 Keil MDK 工程、跑 /keil-build 验证代码改动（只改 .c 注释也算改动）是否「0 错误 0 警告」、/keil-build 报 BUILD_ENV_ERROR 与 UV4.exe not found（退出码 2；DSH 会话看不见用户级 DTU_KEIL_UV4）、解读 UV4 构建日志、退出码 2/4 或 build 锁持有者名（含 pw: 前缀），在 bash / ops_bash 里执行 PowerShell 形态的编译命令行报 syntax error near unexpected token，或构建后 git status 冒出 %SystemDrive% 目录时。"
---
# keil-build — Keil 命令行编译（独立可运行 skill）
@@ -10,21 +10,82 @@ whenToUse: 需要编译 Keil MDK 工程、验证代码改动是否 0 错误 0
（纯标准库，任意 python3；拷整个 skill 目录到别的 Keil 项目即可用，不依赖仓库脚本）。
```powershell
# cwd = 项目根目录
# cwd = 项目根目录；PowerShell 形态（AGENTS「构建与验证」的编译入口）
& $PY ".dsh\skills\keil-build\scripts\keil_build.py"
# 覆盖：--project X.uvprojx --uv4 UV4.exe --target 名字 --log 路径 --timeout 600
```
解析顺序（命令行 > 项目档案 `.serialtest/config.json` > 环境 > 探测）：
工程 `uvprojx`（档案缺省时自动搜 cwd 下唯一 `*.uvprojx`）；UV4 `uv4` >
`$DSH_KEIL_UV4` > `$DTU_KEIL_UV4` > PATH（**显式设了但路径无效 = 立即报错，不静默回退**）。
退出码：`0`=PASS(0错0警) / `1`=构建失败（打印报错行）/ **`2`=环境错误**（UV4 找不到或
路径无效、工程找不到、档案解析失败）/ `3`=用法错误 / `4`=build 锁被占用（并发 `-b` 不可行）。
⚠ **改本文件 frontmatter 要么整值加双引号，要么一个 ASCII 冒号都别写**（2026-10-30 这份就因此整份加载失败）。
DSH 用 `yaml` 包的 `parse()` 读 frontmatter（`@deepseek-ai/dsh-skill-filesystem` 的 `parseFrontmatter()`），
plain scalar 里出现 **ASCII「冒号 + 空格」**（例如把报错原文 `BUILD_ENV_ERROR: UV4.exe not found` 或
`pw: 前缀` 直接写进 description）就报 `Nested mappings are not allowed in compact mappings at line 2,
column 14` → **技能整份不加载**（`skill()` 读不到、也不进技能目录）。**`js-yaml` 能吃下去** ——
拿它自检会假绿，必须用 DSH 自带的那个解析器验。另 — 值首字符不能是 `%`（directive indicator）或 `&`
（anchor），双引号里的 `%SystemDrive%` 之类不受影响。落盘后**让 DSH 真加载一次**再收口。
> 2026-10-12 修正：旧实现把环境错误写成 `raise SystemExit("...")` → 实际退出码是 **1**，
> 而用法错误由 argparse 抛 `SystemExit(2)` → 恰好占了"环境错误"的位置。故 `AGENTS.md` /
> `new-machine-setup` 里写的"报 exit 2 = 环境问题"当时**不成立**。现按文档口径改正：
> 环境错误 → 2（`BuildEnvError`），用法错误 → 3（覆盖 argparse 的 `error()`）。
## 调用形态：先认执行器是哪个 shell（2026-10-26 实测）
- 同一条编译命令，PowerShell 与 bash 是两种写法：bash 侧要去掉前导 & 并把路径改正斜杠（照抄 AGENTS 的 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 显式设了但路径无效 = 立即报错，不静默回退
- 退出码 0=PASS(0错0警) / 1=构建失败 / 2=环境错误 / 3=用法 / 4=build 锁被占用；2026-10-12 修正过 2 与 3 的归属，该篇末尾记了前后口径
- **bash / `ops_bash` 侧「构建到底过没过」的一次自查**（2026-10-26 实测口径）：先 `cd` 到仓库根（或该 worktree 根），跑 `.venv/Scripts/python.exe .dsh/skills/keil-build/scripts/keil_build.py; echo BUILD_RC=$?` —— 正斜杠、**无前导 `&`**，退出码归 python、不归 bash；再单独读日志计数 `grep -a -E "Error\(s\)|error:|Warning\(s\)" MDK-ARM/build_log.txt`。报结论要三样齐 —— **`BUILD_RC=0` + `UV4_RC: 0` + `BUILD_OK: 0 errors, 0 warnings`**（脚本自己判「无 `error:` 行 且 尾行含 `0 Error(s), 0 Warning(s)`」）；bash 吐的 `syntax error near unexpected token` **既不是构建通过也不是构建失败**，那是写法问题，别拿它当构建结论报。
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [executor-shell-forms.md](reference/executor-shell-forms.md)。动手前先读那篇。
## exit 2 实战闭环：`UV4.exe not found` 的探测 → 注入 → 复核（2026-10-30 实测）
**先定性，别动源码**：脚本报
`BUILD_ENV_ERROR: UV4.exe not found (--uv4 / config 'uv4' / $DSH_KEIL_UV4 / $DTU_KEIL_UV4 / PATH)`
且**退出码 2** = **环境错，不是构建失败**——本次 **UV4 根本没启动、`MDK-ARM/build_log.txt` 也没被改写**，
日志里看到的是上一次的。此时去改 `.c`/`.h` 或怀疑代码，就是把环境问题当编译问题排。
（会话为什么看不见：DSH 会话的 shell 由常驻服务派生，**服务启动之后**设的用户级变量不会自动进来；
`run_code` 起的 Node 进程 `process.env` 干脆是空的——AGENTS.md「会话不继承用户级变量」同记此坑。
所以**变量"已设但本会话看不见"是常态**，不是用户没设。）
1. **探测候选安装路径**（逐个 `fs.existsSync` / `test -f`，命中即取绝对路径）——
`C:/Keil_v5/UV4/UV4.exe`、`C:/Keil/UV4/UV4.exe`、`D:/Keil_v5/UV4/UV4.exe`、`D:/Keil/UV4/UV4.exe`、
`C:/Program Files/Keil_v5/UV4/UV4.exe`、`D:/Program Files/Keil_v5/UV4/UV4.exe`
（2026-10-30 实测只命中 `C:/Keil_v5/UV4/UV4.exe`，其余五个都不存在）。
```bash
for p in 'C:/Keil_v5/UV4/UV4.exe' 'C:/Keil/UV4/UV4.exe' 'D:/Keil_v5/UV4/UV4.exe' \
'D:/Keil/UV4/UV4.exe' 'C:/Program Files/Keil_v5/UV4/UV4.exe' 'D:/Program Files/Keil_v5/UV4/UV4.exe'; do
[ -f "$p" ] && echo "HIT $p"; done
```
2. **读用户级来源确认"值本来就对"**（同一轮里顺手做掉，别只靠猜路径）：
bash / Node 侧 `reg query HKCU\Environment`（整表打出来再找 `DTU_KEIL_UV4` / `DSH_KEIL_UV4`），
PowerShell 侧 `[Environment]::GetEnvironmentVariable('DTU_KEIL_UV4','User')`。
有值 → 直接用它；没值/值指向旧目录 → 用第 1 步的命中路径。
⚠ **不替用户改全局**：不要 `setx`、不要 `SetEnvironmentVariable(...,'User')`——那是用户自己在真终端里
做的事（`docs/环境与部署/本地工具路径环境变量方案.md`）；本闭环只解决"这一次构建怎么跑起来"，
报告里也必须这么写。
3. **只给这一次调用注入**再重跑（两种等价形态，二选一）：
```js
// run_code：options.env 是**整体替换**，所以要连 SystemRoot / Path / USERPROFILE 一起给
const { execSync } = await import('node:child_process');
execSync('".venv/Scripts/python.exe" .dsh/skills/keil-build/scripts/keil_build.py', {
cwd: MAIN, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
env: { SystemRoot: 'C:\\Windows', Path: 'C:\\Windows;C:\\Windows\\System32',
USERPROFILE: 'C:\\Users\\<你>', DTU_KEIL_UV4: 'C:\\Keil_v5\\UV4\\UV4.exe' } });
```
- bash / `ops_bash` 侧的等价写法 = 显式参数 `--uv4 'C:\Keil_v5\UV4\UV4.exe'`（值含空格要整体加引号）。
- `run_code` 的 `timeoutMs` 给足：注入后这次构建实测 **10 s** 跑完，但首次冷构建更长（我给的 500000）。
- **别顺手加 `--no-lock`**：注入重跑时锁链照旧（`LOCK: 已获取 build 锁（task=build-cli）` → `已释放锁`）。
4. **复核口径**（三样齐了才算真跑过，缺一样就是没构建）：脚本回显
`UV4: <绝对路径> (<来源>)`（来源随注入方式变：`$DTU_KEIL_UV4` 或 `--uv4`）→
`UV4_RC: 0` → `BUILD_OK: 0 errors, 0 warnings`，且**外层退出码 0**（自己包 execSync 就显式把码打出来，
别接管道，见「调用形态」）。报告里写清"本次注入 + 来源"，**不得声称已永久设置系统/用户环境变量**。
- ⚠ 注入的若是**注册表里那个陈旧值**，会撞同族的另一种 2：
`BUILD_ENV_ERROR: $DTU_KEIL_UV4 is set but not a file: … (fix the value; no silent fallback)`
—— 值在但指向旧盘符/旧目录名（本仓踩过 `D:\Code\DTU 程序\…` 搬迁）。脚本**刻意不静默回退**，
回到第 1 步用探测命中的路径覆盖它，别去猜目录、更别改脚本让它"猜 C 盘"（设计上明确禁止从旧路径猜）。
- ⚠ 本闭环只回答"UV4 在哪儿"，**不回答"调用写法对不对"**：从 bash 侧照抄 PowerShell 的 `&` 也是 exit 2，
但 stderr 是 `syntax error near unexpected token`（见「调用形态」）。**先看 stderr 再决定排障方向**，
两种 2 的处置完全不同。
- **改 `.c` 注释（哪怕只改一行中文注释）也必须跑完这道构建验证**：2026-10-30 的实测就是
「改注释 → `/keil-build` → 吃 rc=2 → 探测+注入 → 10 s 通过」。注释类坑（BOM 被剥 → `#870-D`、
注释里写 `**` 路径 → 9-D）只在**重编译那个 TU 时**才暴露，"以前 0 警告"不代表安全。
## build 锁：脚本自持自释（2026-10-12）
@@ -35,7 +96,7 @@ Agent 手工 `lock acquire build` 后忘了 `release`，锁要挂到 TTL 才被
| 开关 | 作用 |
|---|---|
| `--lock-task <ID>` | 持有者名。默认 `$DTU_TASK_ID` → 从 cwd 的 `_wt/<ID>-<slug>/` 反推 `<ID>` → `build-cli` |
| `--lock-task <ID>` | 持有者名。默认 `$DTU_TASK_ID` → 从 cwd 反推：`_wt/<ID>-<slug>/` → `<ID>`（`@task` 那批）；`.dsh-worktrees/worktree/<name>/` → `pw:<name>`（DSH worktree **插件**建的树，`plugin_tree_owner()`）→ 都没有才落 `build-cli` |
| `--lock-wait <N>` | 锁被占时等待 N 秒（默认 0 = 立即失败，退出码 4） |
| `--no-lock` | 完全不加锁（危险：并发 `-b` 互相干扰） |
| `DTU_LOCK_HELD=build` | 环境变量：**调用方已持锁**时设它，本脚本跳过自持自释（`task-worktree done` 的门禁即如此用） |
@@ -46,39 +107,68 @@ Agent 手工 `lock acquire build` 后忘了 `release`，锁要挂到 TTL 才被
- 锁工具 = 兄弟 skill `task-worktree/scripts/task_worktree.py`；**找不到则降级为不加锁
并告警**（保持本 skill 可独立搬运）。
- ⚠ 从 `_wt/<ID>-<slug>/` 反推持有者名，意味着"手工 `lock acquire build --task <ID>`
后再跑 `@build`"仍**幂等**（同名即视为自己持有），不会自我死锁。
后再跑 `/keil-build`"仍**幂等**（同名即视为自己持有），不会自我死锁。
- **退出码 4 的持有者名带 `pw:`（如 `pw:refactor-logging`）= 插件在 `.dsh-worktrees/worktree/<name>/` 里跑的构建占着 UV4，不是某个 `@task` 任务 ID**：
插件树**没有台账**，别拿它去 `lock release <ID>`（释放不掉别人的锁）、更别去杀 UV4 进程。正解 =
等那次构建自己 `finally` 释放（自持自释；崩溃则按自报 TTL 兜底），或本次加 `--lock-wait <N>` 排队；
想知道是哪棵树的谁：`"$PY" "$TW" plugin list`（缺联接再 `plugin adopt <name>`）→ 细节归
`task-worktree` skill F 节（插件桥）。
- **只 build 锁自动；`bench` 锁仍须 Agent 手工持**（它是**会话作用域**，跨
烧录→`@test`→探针多条命令，逐命令自动释放会让别的任务插进来扰动设备）。
烧录→`/serial-boot-test`→探针多条命令，逐命令自动释放会让别的任务插进来扰动设备）。
## 构建副产物：`%SystemDrive%` 字面量垃圾目录（2026-10-26 两次复发 → 2026-10-28 定性并加守卫）
- 症状：/keil-build（或 check_font_charset.py 这类 fontTools 工具）跑完，仓库根冒出未跟踪的 %SystemDrive%/ProgramData/…/Caches/（几个 .db，约 1 MB）= 本机缓存被按字面量原地复刻
- 根因（2026-10-28 实测）：run_code 的 Node 进程 process.env 是空的 → known-folder 可展开串展不开变成相对路径 → 按当前目录建在仓库根；同族还会冒出 %USERPROFILE%/AppData/Local/Temp
- 清理有安全阀：⚠ 绝不用 cmd / PowerShell 直接删（rd /s /q %SystemDrive% 会被展开成 C:）；只用 bash 引号形态，先 find '%SystemDrive%' -type l 预检再 rm -rf --。它是工具副产物，直接删、别 stash、更别提交
- 两层防线均已落地可核验：.gitignore:167 挡入库 + 脚本 harden_windows_env() 回填环境变量、check_percent_literal_junk() 只告警不自动删；守卫是兜底不是许可，/keil-build 仍要走 ops_bash / PowerShell
- **取证在前，处置在后**（2026-10-28 实测，别一上来 `rm -rf`）：`ls -laR -- "%SystemDrive%"` + `du -sh "%SystemDrive%"` 枚举内容与体积，再 `find "%SystemDrive%" -printf "%T@ %p\n" | sort -rn | head -3` 看**最新 mtime** —— 最近几分钟还在被重建 = 环境仍残缺（脚本会打 `WARN: ENV_SPARSE:`），先断源头（换 `ops_bash`/PowerShell 跑，或按「UV4.exe not found」一节把 `env` 传全）再删，否则删完立刻长回来；顺带确认仓库里只有这一个该名字的东西（`find . -maxdepth 1 -name "*SystemDrive*"`）
- **要留证据就搬走、别就地删** —— ⚠ **shell 的 `mv` 搬不动它**：`mv "%SystemDrive%/..."` 报 `cannot stat`（含 `%` 的目录名被当变量展开 / 吃掉，路径根本对不上）。改用 Python 遍历搬到**仓库外**的临时目录 —— `os.walk` + `shutil.move`（或 `glob.glob("%SystemDrive%/*")` 逐个 `shutil.move` 到 `os.environ["TEMP"]` 下）；确认是纯工具副产物（几个 `.db` 缓存）才 `rm -rf --`
- **入库排除要落成条目并核验**：补 `.gitignore` 前先 `grep -n "SystemDrive" .gitignore` 定位精确原文行再 Edit（凭记忆写 `old_string` 必不匹配，2026-10-28 踩过）。本仓条目 = `.gitignore:167` 的 `%SystemDrive%/`，上面那段注释就是复发证据（新增条目也照此**写明第几次复发、谁造的**）。收尾核验 —— `git status --porcelain` 里该目录零命中（且别的未跟踪产物一个没少）、`git check-ignore -v` 落在那一行、`git add -A --dry-run` 零命中；**绝不提交**（把本机缓存塞进历史）
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [systemdrive-junk-dir.md](reference/systemdrive-junk-dir.md)。动手前先读那篇。
## 本仓库
**`@build` = 本 skill**（2026-10-10 起为仓库文档口径）：在仓库根目录跑
`& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py`。
判定口径（与原 `MDK-ARM/build.bat` 同款；该文件已于 2026-10-10 删除，本 skill 即 `@build`）：
**本 skill 的调用名 = `/keil-build`**（**技能调用名不是 shell 命令**——原样敲进终端是 command not found / syntax error，可执行形态永远是下面这条命令行）：在仓库根目录跑
`& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py`——
**bash / `ops_bash` 下要写成 `'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py`**
（原因见「调用形态」）。
判定口径（与原 `MDK-ARM/build.bat` 同款；该文件已于 2026-10-10 删除，本 skill 即编译入口）：
先删旧日志 → `-b -j0 -o` → 无 `error:` 且含 `0 Error(s), 0 Warning(s)`。
本 skill 另有超时保护、UV4 多级解析链（含 PATH 兜底）、失败只打报错行。
环境变量 `DTU_KEIL_UV4`（用户级，指向 UV4.exe）。
环境变量 `DTU_KEIL_UV4`（用户级，指向 UV4.exe）——注意**它设了不等于本会话能看见**，仍报退出码 2 时走「exit 2 实战闭环」那一节，别先去找用户。
## 铁律与陷阱（实测教训）
- **任何代码改动后必须先编译验证（0 错误 0 警告）再谈烧录/提交**——编译不过就进
硬件闭环只会把编译错误伪装成运行问题。
- **警告也算失败**：判 PASS 只认退出码 0，别只看"有没有 error:"。
硬件闭环只会把编译错误伪装成运行问题。**只改 `.c` 里一行中文注释也算改动**（2026-10-30 实测：
改注释 → `/keil-build` → 环境错 → 探测注入 → 10 s 通过）：BOM/嵌套注释这类坑只在重编译那个 TU 时才暴露。
- **警告也算失败**：判 PASS 只认退出码 0，别只看"有没有 error:"（取退出码的管道陷阱见「调用形态」）。
- **`MDK-ARM/*.uvprojx` 每次构建后被 UV4 自动改写，改动一律不入库**：UV4 会把工程
XML 归一化成本机风格（`<Tag />` → `<Tag></Tag>`、XML 声明加 `standalone="no"`）并把
`PackID` 降到**本机装的 DFP 版本**（属降级——提交后会把别人的 Pack 版本一起改掉）。
判断：`git diff` 里只见 XML 格式/`PackID` 差异而**无源文件挂载增删** →
`git checkout -- <uvprojx>` 丢弃；只有真的增删了源文件（grep 文件名计数变化）才提交。
同目录的 `*.uvoptx` / `*.uvguix.*` 是 IDE 个人设置，已在 `.gitignore` 里，不会露出来。
- **构建后仓库根冒出 `%SystemDrive%/`** = UV4 / 字体工具在残缺环境（缺 `SystemDrive`、`ProgramData`）
里按**未展开的 known-folder 字面量**建出来的**相对路径**目录，不是任何人在飞的改动：
`rm -rf -- '%SystemDrive%'`（bash 引号形态）删掉即可，**严禁 `rd /s /q %SystemDrive%`——cmd 会把它
展开成 `C:`**；`.gitignore` 已兜住 + 脚本已加 `ENV_SPARSE`/`JUNK_DIR` 守卫 → 见「构建副产物」一节。
- 报错定位读日志别只看终端回显：本仓库 = `MDK-ARM\build_log.txt`。
- **exit 2 先分清"真没设"还是"会话没继承"**（2026-10-10 实测）：agent 的 shell 由
常驻服务派生，服务启动**之后**设置的用户级环境变量不会自动进来。查
`[Environment]::GetEnvironmentVariable('DTU_KEIL_UV4','User')`，有值就
`$env:DTU_KEIL_UV4 = <该值>` 注入本会话再跑，别急着让用户去设。
- **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 由常驻服务派生，服务启动**之后**
设的用户级变量不会进来；`run_code` 的 `process.env` 直接是空的）。
②③ 一律走 **「exit 2 实战闭环」** 那一节：探测候选路径 + 读 `HKCU\Environment`，
再**只往那一次调用**的 env / `--uv4` 里注入命中路径重跑——别急着让用户去设，也别替他改全局。
- 编码类报错（`#870-D: invalid multibyte character sequence` 等）先怀疑源文件
BOM/编码被改写，而不是代码本身（见仓库 AGENTS.md 编码铁律）。
## 与其它 skill 的衔接
- **build 锁的对面是谁**（`BUILD_LOCK_BUSY`、退出码 4、`pw:<name>` 插件树、`@task plugin list` / `plugin adopt`、`_wt/` 台账与合并回收）归 `task-worktree` skill（F 节 = DSH worktree 插件桥）；换机/新克隆时 `DTU_*` 工具路径变量的设立与「会话不继承」坑 = `new-machine-setup` skill。
- 烧录/回读 = `stlink-flash` skill；串口闭环 = `serial-boot-test` skill
（其档案 `flash_cmd`/`readback_cmd` 即 stlink-flash 的入口命令）。
- 收尾固定链（2026-10-26 实证）：`/keil-build` → `scripts/ram_baseline.py --update` →
体积门禁盖戳 → 内存数字回填与 `--scan` → 复跑 `ci_local` 静态段，
直到钩子全绿且 0 错误 0 警告（RAM/栈口径见 `mem-budget` skill）。
.dsh/skills/keil-build/reference/executor-shell-forms.md
+43
View File
@@ -0,0 +1,43 @@
# 调用形态：先认执行器是哪个 shell（2026-10-26 实测）（自 SKILL.md 外置）
> 本文由 keil-build 的 SKILL.md「调用形态：先认执行器是哪个 shell（2026-10-26 实测）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
同一条编译命令，**PowerShell 与 bash 是两种写法**；`ops_bash` / `run_code` 起的是
`/usr/bin/bash -c`，**不认 PowerShell 形态**，照抄仓库 `AGENTS.md` 会直接语法错退出。
| 执行器 | 正确写法（cwd = 仓库根） |
|---|---|
| PowerShell | `& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py` |
| bash（`ops_bash`） | `'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py` |
- bash 侧**去掉前导 `&`**（bash 里 `&` 是"丢后台"，不是调用操作符）、**路径改正斜杠**
（`\Scripts\python.exe` 的反斜杠在 bash 是转义，路径根本解析不出来）。
- 实测（step 41→42）：把 PowerShell 形态丢进 `ops_bash` 后台任务 → 任务**秒退**、
`exit 2`，stderr 只有这一行：
```text
/usr/bin/bash: -c: line 1: syntax error near unexpected token `&'
```
- ⚠ **这个 2 不是脚本的环境错误 2**：脚本自己报环境错误会打出 `BuildEnvError` /
中文诊断（UV4 找不到、工程找不到、档案解析失败），而语法错**连解释器都没启动**，
`MDK-ARM/build_log.txt` 不会被改写。判据：stderr 含 `syntax error near unexpected token`
= 写法问题 → 换 bash 形态重跑，**别去查 `DTU_KEIL_UV4`、别当环境错误排障**。
- 后台跑（`run_in_background: true`）时要自己收码，且**别把脚本接进管道**：
`'.venv/Scripts/python.exe' .dsh/skills/keil-build/scripts/keil_build.py; rc=$?; echo RC=$rc`。
实测 `脚本 | tail -6; echo RC=$?` 里的 `$?` 是 `tail` 的退出码（恒 0），
拿它当 PASS/FAIL 会永远"绿"；`set -o pipefail` 能透出非零码，但尾巴上挂的 `grep`
无匹配时同样报 1，也不可信。要看报错行就单独 grep 日志：
`grep -a -E 'Error|error:|Warning' MDK-ARM/build_log.txt`。
解析顺序（命令行 > 项目档案 `.serialtest/config.json` > 环境 > 探测）：
工程 `uvprojx`（档案缺省时自动搜 cwd 下唯一 `*.uvprojx`）；UV4 `uv4` >
`$DSH_KEIL_UV4` > `$DTU_KEIL_UV4` > PATH（**显式设了但路径无效 = 立即报错，不静默回退**）。
退出码：`0`=PASS(0错0警) / `1`=构建失败（打印报错行）/ **`2`=环境错误**（UV4 找不到或
路径无效、工程找不到、档案解析失败）/ `3`=用法错误 / `4`=build 锁被占用（并发 `-b` 不可行）。
**收到 2 先确认它是脚本打的还是 shell 语法错打的**（见上节），再走"环境错误"排障。
> 2026-10-12 修正：旧实现把环境错误写成 `raise SystemExit("...")` → 实际退出码是 **1**，
> 而用法错误由 argparse 抛 `SystemExit(2)` → 恰好占了"环境错误"的位置。故 `AGENTS.md` /
> `new-machine-setup` 里写的"报 exit 2 = 环境问题"当时**不成立**。现按文档口径改正：
> 环境错误 → 2（`BuildEnvError`），用法错误 → 3（覆盖 argparse 的 `error()`）。
.dsh/skills/keil-build/reference/systemdrive-junk-dir.md
+44
View File
@@ -0,0 +1,44 @@
# 构建副产物：`%SystemDrive%` 字面量垃圾目录（2026-10-26 两次复发 → 2026-10-28 定性并加守卫）（自 SKILL.md 外置）
> 本文由 keil-build 的 SKILL.md「构建副产物：`%SystemDrive%` 字面量垃圾目录（2026-10-26 两次复发 → 2026-10-28 定性并加守卫）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
**症状**：`/keil-build`（或 `scripts/check_font_charset.py` 这类 fontTools 字体工具）跑完，仓库根
冒出未跟踪目录 `%SystemDrive%/ProgramData/Microsoft/Windows/Caches/`，里面是几个 `.db`
（`cversions.2.db` + `{6AF0698E-…}` 图标缓存 + `{DDF571F2-…}` 字体缓存，合计约 1 MB）——
就是本机 `C:\ProgramData\Microsoft\Windows\Caches` 那份缓存被**按字面量原地复刻**了一份。
**根因（2026-10-28 实测）**：Windows 的 known-folder 路径在注册表里是**可展开串**；展开不了，
它就变成一个**相对路径**，于是按「当前目录」（= 仓库根）建出来。三条现场证据：
```bash
reg.exe query HKCU\Environment # 本机 TMP/TEMP = REG_EXPAND_SZ %USERPROFILE%\AppData\Local\Temp
env | wc -l # ops_bash 里 = 74（完整环境）
node -e "console.log(Object.keys(process.env).length)" # run_code 里 = 0（空环境！）
```
`run_code` 的 Node 进程 `process.env` 是**空的**，从它里面 `spawn` 出去的 UV4 / 字体脚本就拿不到
`SystemDrive`/`ProgramData`/`ALLUSERSPROFILE`；实测 `os.path.expandvars("%SystemDrive%\ProgramData")`
原样返回、且 `os.path.isabs()` = **False** → 目录就长在工作区里（同族还会冒出
`%USERPROFILE%/AppData/Local/Temp`）。**正解不是「让用户去设环境变量」**，是别在残缺环境里跑构建（见第 2 条）。
**清理（有安全阀）**：
- ⚠ **绝不用 cmd / PowerShell 直接删**：`rd /s /q %SystemDrive%` 会被 cmd **展开成 `C:`**——
等于对整块系统盘下令递归强删且不带确认。
- ✅ 只用 bash 引号形态（`%` 在 bash 里没有特殊含义）：先 `find '%SystemDrive%' -type l` 确认不是
reparse point / 符号链接，再 `rm -rf -- '%SystemDrive%'`；或 Node
`fs.rmSync("%SystemDrive%", { recursive: true, force: true })`。
- 它是**工具副产物**，不是谁在飞的改动——直接删，别 stash、更别提交（提交它 = 把本机缓存塞进历史）。
**让它不再污染工作区（两层，均已落地、可核验）**：
1. **进不了版本库**：`.gitignore:167` 的 `%SystemDrive%/`（2026-10-26 入库，注释里就写着复发证据）。
核验三步（2026-10-28 复跑全绿）：造一份同名目录 + `.db` → `git status --porcelain` 零命中 →
`git check-ignore -v <路径>` 落在 `.gitignore:167:%SystemDrive%/` → `git add -A --dry-run` 零暂存。
2. **根本别再长出来**：本 skill 脚本 2026-10-28 起在拉起 UV4 前跑 `harden_windows_env()`——回填
`SystemDrive`/`SystemRoot`/`windir`/`ComSpec`/`ProgramData`/`ALLUSERSPROFILE`/`ProgramFiles` 与
`USERPROFILE`/`APPDATA`/`LOCALAPPDATA`/`TMP`/`TEMP`，就地展开环境里未展开的 `%VAR%` 字面量，
并把 `TMP`/`TEMP` 指到真实目录；命中即打 `WARN: ENV_SPARSE:`。构建后再跑
`check_percent_literal_junk()`，看到 `%SystemDrive%`/`%USERPROFILE%` 一类字面量目录就打
`WARN: JUNK_DIR:`（**只告警不自动删**——删目录不该由构建脚本代劳）。守卫是兜底不是许可：
**`/keil-build` 仍要走 `ops_bash` / PowerShell（继承完整环境）**，非在 Node 里 spawn 就把 `env` 传全。
.dsh/skills/keil-build/scripts/keil_build.py
+135 -3
View File
@@ -14,7 +14,7 @@
（环境变量**显式设了但路径无效 = 立即报错，不静默回退**）
日志 --log > 档案 "build_log" > <工程目录>\\build_log.txt
判定口径（实测教训沉淀；原仓库 MDK-ARM/build.bat 已删除，本脚本即 @build）:
判定口径（实测教训沉淀；原仓库 MDK-ARM/build.bat 已删除，本脚本即仓库编译入口）:
1. 先删旧日志——UV4 -o 只在真跑了构建才写日志，残留旧日志会被当成本次结果
2. UV4 单实例：IDE 开着时 -b 可能被转发给 IDE（退出码丢失）→ 只 WARN 不杀进程
3. PASS = 日志存在 + 无 "error:"（大小写不敏感）+ 含 "0 Error(s), 0 Warning(s)"
@@ -64,6 +64,117 @@ class BuildEnvError(Exception):
"""环境/前置错误（UV4 或工程找不到、档案解析失败）→ 退出码 2。"""
def _expand_deep(v):
"""展开未展开的 REG_EXPAND_SZ 字面量（百分号形态的变量引用），最多四轮，防自指死循环。"""
for _ in range(4):
nv = os.path.expandvars(v)
if nv == v:
break
v = nv
return v
def harden_windows_env():
"""拉起 UV4 前补齐/展开子进程环境——堵住仓库根的「%SystemDrive%/」字面量垃圾目录。
Windows 的 known-folder 路径在注册表里是**可展开串**：ProgramData 的真实取值来自
「%SystemDrive%/ProgramData/…」，本机 HKCU Environment 里的 TMP/TEMP 实测就是未展开的
「%USERPROFILE%/AppData/Local/Temp」。父进程环境残缺时（典型：Agent 在 Node
child_process / run_code 里 spawn，子进程继承到一个**空环境**，SystemDrive、ProgramData、
USERPROFILE 一个都没有）这些串展不开、留在原地就成了**相对路径**，于是 UV4 / fontTools 类
字体工具按它在**当前目录**（= 仓库根）建出
「%SystemDrive%/ProgramData/Microsoft/Windows/Caches/*.db」（图标+字体缓存库，约 1 MB），
污染 git status（2026-10-26 同一会话两次复发；仓库 .gitignore 已入库兜住它，但正解是
**根本别让它长出来**）。故此处回填 + 展开，并打可定位的 WARN：ENV_SPARSE。
"""
if os.name != "nt":
return
filled, expanded = [], []
for key, val in list(os.environ.items()):
if isinstance(val, str) and "%" in val:
new = _expand_deep(val)
if new != val and "%" not in new:
os.environ[key] = new
expanded.append(key)
root = os.environ.get("SystemRoot") or os.environ.get("windir") or ""
root = _expand_deep(root)
if "%" in root or (root and not os.path.isdir(root)):
root = os.path.join(os.path.abspath(os.sep), "Windows") # 兜底：当前盘根下的 Windows 目录
drive = os.path.splitdrive(root)[0] or os.path.abspath(os.sep)[:2]
drive = drive.rstrip(os.sep) or "C:"
sysroot = drive + os.sep
user = _expand_deep(os.environ.get("USERPROFILE") or "")
if "%" in user:
user = ""
defaults = {
"SystemDrive": drive,
"SystemRoot": root,
"windir": root,
"ComSpec": os.path.join(root, "System32", "cmd.exe"),
"ProgramData": os.path.join(sysroot, "ProgramData"),
"ALLUSERSPROFILE": os.path.join(sysroot, "ProgramData"),
"ProgramFiles": os.path.join(sysroot, "Program Files"),
}
if not user:
guess = _expand_deep(os.path.expanduser("~"))
if not guess.startswith("~") and "%" not in guess:
user = guess
if user:
defaults["USERPROFILE"] = user
defaults["APPDATA"] = os.path.join(user, "AppData", "Roaming")
defaults["LOCALAPPDATA"] = os.path.join(user, "AppData", "Local")
defaults["TMP"] = os.path.join(user, "AppData", "Local", "Temp")
defaults["TEMP"] = defaults["TMP"]
for key, val in defaults.items():
if not os.environ.get(key):
os.environ[key] = val
filled.append(key)
# TMP/TEMP 必须落在真实目录：留未展开值 = 工具按字面量在当前目录建「%USERPROFILE%/…」垃圾树
td = os.environ.get("TEMP") or os.environ.get("TMP") or ""
if "%" in td or (td and not os.path.isdir(td)):
cand = []
lad = os.environ.get("LOCALAPPDATA") or ""
if lad and "%" not in lad:
cand.append(os.path.join(lad, "Temp"))
cand.append(os.path.join(sysroot, "Temp"))
picked = next((c for c in cand if os.path.isdir(c)), None)
if not picked:
for c in cand:
try:
os.makedirs(c, exist_ok=True)
picked = c
break
except OSError:
continue
if picked:
os.environ["TEMP"] = picked
os.environ["TMP"] = picked
filled.append("TEMP/TMP=" + picked)
if filled or expanded:
print("WARN: ENV_SPARSE: 子进程环境残缺/含未展开字面量 —— 已回填[{}] 已展开[{}]".format(
", ".join(sorted(filled)) or "-", ", ".join(sorted(expanded)) or "-"))
print(" 正解：用继承**完整环境**的 shell 跑编译（ops_bash / PowerShell），"
"别从 Node spawn（空 process.env）直接起 UV4 或字体门禁脚本")
def check_percent_literal_junk():
"""构建后自检：环境残缺时 Windows 会在**当前目录**按字面量建 %SystemDrive%/ 之类的垃圾树。
只告警、不自动删——删除口径见本 skill「构建副产物」一节：必须用 bash 引号形态，
绝不能用 cmd（cmd 会把 %SystemDrive% 展开成 C:，等于对整块系统盘下 rd /s /q）。
"""
for name in ("%SystemDrive%", "%USERPROFILE%", "%LOCALAPPDATA%", "%APPDATA%",
"%ProgramData%", "%TEMP%", "%TMP%"):
if os.path.isdir(name):
print("WARN: JUNK_DIR: 工作区出现字面量目录 {}（未展开的 known-folder 路径；"
".gitignore 已兜住，不得入库）".format(name))
print(" 清理（只用 bash 引号形态，禁用 cmd 以免展开成 C:）: rm -rf -- '{}'".format(name))
class _ArgumentParser(argparse.ArgumentParser):
"""用法错误 → 退出码 3。
@@ -162,8 +273,25 @@ def find_lock_tool():
return cand if cand.is_file() else None
def plugin_tree_owner(cwd: Path):
"""DSH worktree 插件的树（仓库内 .dsh-worktrees/worktree/<name>）→ 持有者名 pw:<name>。
2026-10-29 与 task-worktree skill 的 `plugin` 子命令对齐：插件建的树不在 _wt/ 约定里，
以前在这里跑构建，持有者名一律落成 "build-cli"——`lock status` 看不出是谁在占 UV4，
多个插件树 / 主树并发时就只剩猜。名字里的多段斜杠压平成 -，与
task_worktree.py 的 plugin_lock_owner() 完全一致（同一个可 grep 的标识）。
"""
parts = cwd.parts
if ".dsh-worktrees" not in parts:
return None
tail = parts[parts.index(".dsh-worktrees") + 1:]
if tail and tail[0] == "worktree":
tail = tail[1:]
return "pw:" + "-".join(tail) if tail else "pw:?"
def default_lock_task():
"""持有者名：$DTU_TASK_ID > cwd 反推 `_wt/<ID>-<slug>/` 的 `<ID>` > "build-cli"。"""
"""持有者名：$DTU_TASK_ID > cwd 反推 `_wt/<ID>-<slug>/` 的 `<ID>` > 插件树 `pw:<name>` > "build-cli"。"""
v = os.environ.get("DTU_TASK_ID")
if v:
return v
@@ -174,7 +302,7 @@ def default_lock_task():
for p in (cwd, *cwd.parents):
if p.parent.name == "_wt":
return p.name.split("-", 1)[0] or p.name
return "build-cli"
return plugin_tree_owner(cwd) or "build-cli"
def build_lock_ttl_hours(timeout_s):
@@ -242,6 +370,9 @@ def run_build(args):
print("PROJ: {} target={}".format(proj, target or "(default)"))
print("LOG: {}".format(log))
# 环境残缺守卫：先补齐/展开，否则 UV4 会在仓库根按字面量建 %SystemDrive%/ 垃圾树
harden_windows_env()
# UV4 单实例陷阱：IDE 开着时 -b 可能被转发（退出码丢失、GUI 弹出）——只 WARN
try:
tl = subprocess.run(["tasklist", "/fi", "imagename eq UV4.exe", "/nh"],
@@ -268,6 +399,7 @@ def run_build(args):
print("BUILD_FAIL: UV4 timed out after {}s (hung or forwarded to IDE?)".format(args.timeout))
return 1
print("UV4_RC: {}".format(rc))
check_percent_literal_junk()
if not log.is_file():
print("BUILD_FAIL: no build log produced - UV4 did not run or hung")
.dsh/skills/lvgl-simulator/SKILL.md
+7 -5
View File
@@ -26,19 +26,21 @@ PC 上编译运行与 MCU **同一份** UI 源码（CMake + MSVC + SDL2，x64，
| `lvgl_sim.exe --screenshot shot.bin` | 离屏渲染首帧 → `simulator/i1_to_png.py` 转 PNG 目检 |
| `lvgl_sim.exe --keys "ud" shot.bin` | 注入键序后截图：`u`=↑ `d`=↓ `l`=← `r`=→ `e`=Enter `s`=Esc（`main.c` 实锤） |
| `lvgl_sim.exe --standby shot.bin` | 待机页截图 |
| `lvgl_sim.exe --cfgtest` | 配置引擎闭环：加载→轮询→外部改文件重载→外科式保存回验（在当前 CWD 产生 `sim_config.ini`） |
| `lvgl_sim.exe --cfgtest` | 配置引擎闭环：加载→轮询→外部改文件重载→外科式保存回验。临时用当前 CWD 的 `sim_config.ini`，**跑完无论成败一律删除**（旧行为连 PASS 路径也会留一份 4000 B 伪造档 → 之后每次运行都被加载 → 引擎按设计拒写超长文档 → 网口设置页保存行变 `ERR`，把像素回归带偏） |
| `lvgl_sim.exe --logtest` | syslog 后端闭环（定长记录/时间戳/轮转） |
⚠ **模拟器按当前工作目录读写 `sim_config.ini`**：目录里残留一份配置就会改变页面内容。`simulator/tests/` 两套回归因此一律在**空临时目录**里跑（`cwd=tmp`）；手工跑 `--keys`/`--screenshot` 做对比时，也要先确认当前目录没有 `sim_config.ini`，否则"复现不了别人的 FAIL"。
## UI 改动回归 → 用 `ui-verify` skill（勿在此零散手跑）
5 步门禁 = 构建 → `check_menu_rows.py`（菜单 8 状态像素 + 池基线）→ `check_content_pages.py`（文本断言 + 11 页黄金参考 + 往返池）→ `@build` → `coding-standard`。
5 步门禁 = 构建 → `check_menu_rows.py`（菜单 8 状态像素 + 池基线）→ `check_content_pages.py`（文本断言 + 66 张黄金参考 + 往返池）→ `/keil-build` → `coding-standard`。
RemoDispBus 推流回归单独跑：`.venv\Scripts\python.exe simulator/tests/check_remo_sink.py`。
黄金参考 `tests/ref/` 是**本地生成物不入库**：换机后先 `check_content_pages.py --update` 生成，再 `regen_ref_png.py` 出目检 PNG。
黄金参考 `tests/ref/*.bin` **随仓库入库**（`.gitignore` 在全仓 *.bin 兜底之后又显式反选，2026-10-22 起；缺基准 = 新克隆跑 `ui-golden` 必 FAIL）：不入库的只是派生目检图 `ref/*.png`，换机后先 `check_content_pages.py --update` 生成，再 `regen_ref_png.py` 出目检 PNG。
## 两条铁律
- **改 `simulator/lv_conf.h` 触发 `lv-conf-sync` 门禁**：它与 MCU 端 `Lib/lv_conf.h` 必须保持同一特性子集（按**生效值**比对，未定义取 `lv_conf_internal.h` 兜底）；白名单与四类判定 → `docs/代码规范/pre-commit使用说明.md` §2.15 / §5.5
- **模拟器代码与固件同标准受检**（`cppcheck` / `coding-standard` / 乱码 / 改写型钩子 / `doc-links` 全覆盖 `simulator/`）；**改动触及 `sim/` 任何后端，必须同步在 `docs/测试说明/模拟器差距清单.md` 登记一行**——模拟器跑过 ≠ 真机跑过
- **改 `simulator/lv_conf.h` 触发 `lv-conf-sync` 门禁**：它与 MCU 端 `Lib/lv_conf.h` 必须保持同一特性子集（按**生效值**比对，未定义取 `lv_conf_internal.h` 兜底）；四类判定与端专属白名单 → `docs/门禁说明/lv-conf-sync.md`；顶层 exclude 的教训 → `docs/代码规范/pre-commit使用说明.md` §5.5
- **模拟器代码与固件同标准受检**（`cppcheck` / `coding-standard` / 乱码 / 改写型钩子 / `doc-links` 全覆盖 `simulator/`）；**改动触及 `sim/` 任何后端，必须同步在 `docs/测试说明/专项验证/模拟器差距清单.md` 登记一行**——模拟器跑过 ≠ 真机跑过
## 构建/运行报错速查（详解 `simulator/README.md`「四、已知坑（构建/运行）」）
.dsh/skills/mem-budget/SKILL.md
+114 -7
View File
@@ -1,7 +1,7 @@
---
name: mem-budget
description: 嵌入式 RAM/栈预算核算工作流：Keil .map/.htm 静态报告（ram_report/stack_report）+ 串口运行时水位叠加 + DBG 日志成本模型（每条约 90B Flash/216B 栈）。"改任务/缓冲/栈之前必须核算"的固定动作与判读口径。
whenToUse: 新增任务/加大缓冲/改栈/接入日志之前之后、链接报 L6406E 或 RAM 溢出、串口 [STACK] 水位余量低于底线、或需要回答"这个改动花多少 RAM/Flash"时。
description: 嵌入式 RAM/栈预算核算工作流：Keil .map/.htm 静态报告（ram_report/stack_report）+ 串口运行时水位叠加 + 权威构建后的台账回填（ram_baseline.py --update 只往 ram_baseline.tsv 追加趋势行、--write 才同步 RAM预算台账 受管区、check_mem_numbers.py --write 同步文档快照区）+ DBG 日志成本模型（每条约 90B Flash/216B 栈）+ 跨树（worktree）测量的身份口径——脚本按 __file__ 定位产物、什么才算一次新测量、多条链同涨同一数值的共享帧/幻影环归因法。"改任务/缓冲/栈之前必须核算"、"这个数属于哪棵树、哪次构建"与"内存/Flash 数字钩子红了、提交前台账怎么回填"的固定动作和判读口径。
whenToUse: 新增任务/加大缓冲/改栈/接入日志之前之后、链接报 L6406E 或 RAM 溢出、串口 [STACK] 水位余量低于底线、要回答"这个改动花多少 RAM/Flash"；以及要复算或比对另一个 worktree 的栈数字、独立验证某个栈回归该记在哪一笔提交上、判断多次启动的栈峰值抖动算不算劣化时；还有 /keil-build 之后要把内存数字回填进台账/文档、纠结该跑 ram_baseline.py --write 还是 --update、提交时 mem-budget / mem-numbers 两条钩子报"与 .map 不一致"时。
---
# mem-budget — RAM/栈预算核算
@@ -9,26 +9,120 @@ whenToUse: 新增任务/加大缓冲/改栈/接入日志之前之后、链接报
## 固定动作（改前、改后各跑一次）
```powershell
# cwd = 项目根；先 @build 保证 .htm/.map 是最新的
# cwd = 项目根；先 /keil-build 保证 .htm/.map 是最新的（产物按脚本自身位置定位，见下节）
& '.venv\Scripts\python.exe' ".dsh\skills\mem-budget\scripts\mem_check.py"
# 等价于分别跑：
# scripts/ram_report.py （.map → RAM/Flash 分区与按文件占用表）
# scripts/stack_report.py （.htm 静态调用图 → 每任务最坏链 vs 配置栈）
# 报告落盘留档（改前/改后各一份，供逐帧差分）：
& '.venv\Scripts\python.exe' scripts/stack_report.py -o ci-artifacts/sr_before.md
# 叠加运行时水位（有真机日志时）：
& '.venv\Scripts\python.exe' scripts/stack_report.py -s .dsh\skills\serial-assistant\scripts\state\serial.log
```
退出码：0=全部通过 / 1=有任务不达标 / 2=解析错误（.htm/.map 缺失先重跑构建）。
别整篇读输出，抓关键行：`grep -aE 'iec104|margin|FAIL|ISR|Rule' ci-artifacts/sr_before.md`。
**「改前 / 改后」必须是两次不同的 Linker run**（两个不同的产物身份）：同一份 .htm/.map 上跑两遍
只是把同一个数字复述两遍，不构成"改后已复验"。
## 测量身份口径（先钉树与时刻，再看数字）
1. 脚本按 __file__ 定位产物，不按 cwd —— 跨树必须换脚本（在主树跑脚本量任务树 = 拿旧 .map 当真值）
2. 重跑报告脚本不算新测量（复述 ≠ 复验）：只有新的 Linker run 才算一次新测量
3. 钉身份的取数法：.htm/.map 按约定不入库 → 把时刻写进正文/台账；记录最小格式 = tree/commit + Linker run 时刻 + 产物来源（本次构建 / 盘上既有）
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [measurement-identity.md](reference/measurement-identity.md)。动手前先读那篇。
## 静态最坏链回归的归因（同涨同一数值 = 共享帧，不是调用方）
- 多条任务链分毫不差同涨/同降同一个数值 ⇒ 加深在这些任务共用的被调帧 / 共享尾段上，不在任何一个调用方（别先猜「新增了大局部缓冲」，实测猜错过一次）
- 逐棵树逐帧比 frame size、不只比总数：stack_report.py 的 own-frame 表锁链尾公共段；grep -ac 'In Cycle' 在 .htm 里找环（实测 17 处）—— 链接器幻影环能在无人改栈配置时让全仓链齐涨
- Maximum Stack Usage 里的 + Unknown(Cycles, Untraceable Function Pointers) 说明静态数是估计值，别当精确值上报；不采信口头结论，用目标树的脚本 + .venv 解释器自己复算
- 处置后的下一步：抬栈（Src/freertos.c 的 USER CODE 区，属 Ask-first）或收紧共享缓冲 / 断环；改前改后各跑一次 stack_report.py + ram_report.py，且「改后」那次必须落在一次新的 Linker run 上
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [shared-frame-attribution.md](reference/shared-frame-attribution.md)。动手前先读那篇。
## 判读口径
- **静态**：`stack_report.py` 的 Max Depth（最坏调用链累计）vs `Src/freertos.c` 配置栈；
默认要求余量 ≥30%（`--min-free-pct`），ISR 另留 `--isr-margin`（默认 1024B）。
判定式 `margin = cfg - max(static_max_depth, runtime_peak)` 须 ≥ `max(isr_margin, 30% of cfg)`。
- **运行时**：开机日志 `[STACK] <task> peak_used=…/… free_min=…` 与静态值对照——
静态是上界、运行时是下界证据，**两者都要看**；余量 <1KB 底线要上报。
**静态最坏链是上界（硬线）、运行时峰值是下界证据（趋势）**，两者都要看；余量 <1KB 底线要上报。
- **RAM 总量**：`ram_report.py` 对 Grand Totals 与 `docs/内存管理/` 预算表核对；
链接错 `L6406E` = 已经溢出，用按文件表找大头。
- 任务表一致性由 pre-commit `task-table` 钩子保证（改栈后 `gen_task_table.py` 同步 AGENTS.md）。
- 任务表一致性由 pre-commit `task-table` 钩子保证；`mem-budget` 钩子拦 RW_IRAM1/RW_CCM >92%，
**并核台账受管区是否与 .map 同源**；`mem-numbers` 钩子核文档里的内存数字——
数字与树/时刻脱钩、或**构建后只跑了 `--update` 没回填受管区**时，响的就是这两条（回填见下一节）。
## 权威构建后的台账回填（三个旗标，别混）
`.map` 是内存/Flash 数字的**唯一事实源**；台账与文档里的数字由脚本从它生成——**不手抄、不手改**
（`docs/内存管理/RAM预算台账.md` 首段就写着"数字不手抄"）。三份落点 = 三个旗标，一条命令只干其中一件：
`ram_baseline.py` 的 `--gate/--write/--update/--trend` 是 `add_mutually_exclusive_group()`
（`scripts/ram_baseline.py:415-419`），想干两件就得调两次。
| 落点 | 旗标 | 实际改了什么 |
|---|---|---|
| `scripts/ram_baseline.tsv` 趋势基线（顺带刷 `scripts/size_attestation.json` 同码凭证） | `ram_baseline.py --update` | **只**追加/覆盖当日那一行趋势（Code/RO/RW/ZI + 三区水位 + Top-10 RW+ZI）。**不碰台账正文** |
| `docs/内存管理/RAM预算台账.md` 的 `<!-- MEM_BUDGET:BEGIN/END -->` 受管区 | `ram_baseline.py --write` | 从 .map 重渲染区域水位 + 子系统配额对照（打印「已同步台账受管区。」或「台账受管区已是最新。」） |
| `docs/内存管理/RAM使用分析与优化方案.md` 的 `<!-- MEM_SNAPSHOT:BEGIN/END -->` 快照区 | `check_mem_numbers.py --write` | 从**同一份** .map 重渲染内存/Flash 快照表（打印「已更新内存快照：…」） |
**AGENTS.md 与台账 §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 不一致（区域水位或子系统配额表漂移）`
并打印 `修复：python scripts/ram_baseline.py --write`（`scripts/ram_baseline.py:221-224`）；
`mem-numbers` 的 entry 是 `python scripts/check_mem_numbers.py --scan`（同文件 :193），不一致时打印
`修复：运行 python scripts/check_mem_numbers.py --write`（`scripts/check_mem_numbers.py:416`）。
改用两个 `--write` 后重提，同一笔提交触发的 26 条钩子全 Passed。
### 提交前固定顺序（构建 → 回填 → 真钩子提交）
```powershell
# cwd = 项目根，一律 .venv 解释器
# 0) 权威构建先行（0 错 0 警）：回填读的是**盘上那份 .map**，构建没落定就 --write = 把旧数字写进台账，钩子照样红
& '.venv\Scripts\python.exe' .dsh\skills\keil-build\scripts\keil_build.py
# 1) 趋势行（纪律项，不是回填）：覆盖 tsv 当日行 + 顺带刷体积同码凭证
& '.venv\Scripts\python.exe' scripts/ram_baseline.py --update
# 2) 回填台账受管区（mem-budget 钩子核的就是这一段）
& '.venv\Scripts\python.exe' scripts/ram_baseline.py --write
# 3) 回填文档快照区（mem-numbers 钩子核的就是这一张表）
& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --write
# 4) 逐字自跑提交时会跑的这两条 entry（比事后翻 pre-commit 输出快）
& '.venv\Scripts\python.exe' scripts/ram_baseline.py --gate # 0 = 阈值 + 受管区都过
& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --scan # 0 = 快照区与 .map 一致
# 5) 把刚落盘的落点一并 add，然后**真钩子**提交（绝不 --no-verify、绝不手改数字）
git add docs/内存管理/RAM预算台账.md docs/内存管理/RAM使用分析与优化方案.md scripts/ram_baseline.tsv scripts/size_attestation.json
```
退出码：`ram_baseline.py` 0=通过或跳过 / **1=阈值超限或受管区漂移** / 2=.map 解析失败；
`check_mem_numbers.py` 0=一致 / 1=不一致、缺受管锚点或找不到事实源。
### 回填链上的坑（实测）
- --write 说「已是最新」而钩子还红
- tsv 落后只 WARN、不拦
- --gate 无 .map → SKIP，而脚本自己写明「SKIP 不等于 PASS」
- --map <path> 只换读、不换写
- --scan 的散句告警 --write 不替你改
- --update 的盖戳排在索引后面
- 改写型钩子当场改文件是流程不是故障
- mem-budget 触发面很宽
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [backfill-pitfalls.md](reference/backfill-pitfalls.md)。动手前先读那篇。
## 运行时峰值抖动与"算不算劣化"
- 同一份镜像连续启动 5 次，`uiTask` 峰值实测在 4116~4188 之间摆 **72 B** ⇒ 跨启动本身就有几十 B 抖动，
"相对上一轮 +100 B"**不可归因**于被测改动。判据写成"栈水位不劣于上一轮"必然假红。
- 可执行修法（二选一，别都留着）：
1. 同一份像**≥3 次启动取最大值**互比，并加容差（**±128 B 量级**）；
2. 硬线改用 `stack_report.py` 的**静态最坏链**，运行时峰值降级为趋势参考。
- 判据一改要同步**所有落点**：判据正文、跑判据的脚本、记录判据的文档三处一起改，只改一处等于各说各话。
## 成本模型（实测，估算用）
@@ -42,8 +136,21 @@ whenToUse: 新增任务/加大缓冲/改栈/接入日志之前之后、链接报
- **自研代码禁 C 库堆**（MicroLIB 堆仅 512B）：只用 `pvPortMalloc/vPortFree`（FreeRTOS 堆），
模拟器 CRT 堆照不出 MCU 堆分配失败。
## 验证（这轮测量算数了吗）
1. 报告头 `- Source:` 的相对路径落在**我要量的那棵树**下（不是裸文件名，更不是别的树）；
2. `- Linker run:`（或 .htm 的 `Last Updated:` / mtime）与本轮那次构建对得上，且**不同于**上一轮那次的时刻
——相同就是复述，回去先做一次构建再比；
3. 树身份已按 `tree/commit + 时刻 + 产物来源` 写进提交正文/台账，而不是只留在终端输出里；
4. 结论里互比的数字必须来自**同一棵树同一次链接**；跨树比较要各自给出树与时刻；
5. 涉及劣化判定时注明依据的是静态最坏链（硬线）还是运行时峰值（趋势），并已计入跨启动抖动。
6. 要入库的数字：本轮已按「`/keil-build` → `ram_baseline.py --update` → `ram_baseline.py --write` →
`check_mem_numbers.py --write`」回填，并逐字自跑 `ram_baseline.py --gate` 与 `check_mem_numbers.py --scan` 各返 0；
台账 / 文档 / tsv 的改动与代码同一笔入库，**未手改数字、未用 `--no-verify`**。
## 其它项目怎么套
模式通用：链接器 map + 调用图 htm 是**免硬件**的栈可观测源；固定"改前改后各跑一次
报告 + 运行时水位叠加 + 余量阈值"三件套。本仓库两个报告脚本按 Keil 输出格式解析，
换工具链（GCC newlib + `-fstack-usage`）需替换解析层，工作流不变。
报告 + 运行时水位叠加 + 余量阈值"三件套，**外加一条身份口径——脚本按自身位置定位产物，
跨树比的是"两棵树各自的脚本 + 各自的链接时刻"，重跑同一份产物永远只是复述**。
本仓库两个报告脚本按 Keil 输出格式解析，换工具链（GCC newlib + `-fstack-usage`）需替换解析层，工作流不变。
.dsh/skills/mem-budget/reference/backfill-pitfalls.md
+29
View File
@@ -0,0 +1,29 @@
# 回填链上的坑（实测）（自 SKILL.md 外置）
> 本文由 mem-budget 的 SKILL.md「回填链上的坑（实测）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
- **`--write` 说「已是最新」而钩子还红** ≠ 钩子坏了，是**落点找错了**：tsv / 台账受管区 / 文档快照区
三处各归一个旗标。按上表对号，别把同一个旗标重跑三遍；手改台账数字更不行——下次 `--write` 直接覆盖你，
钩子仍按 .map 判漂移。
- **tsv 落后只 WARN、不拦**：`--gate` 对「tsv 末行落后于当前 .map」只打印 `[WARN] …请跑 --update`
（`ram_baseline.py:232`），**拦下来的是受管区漂移**。所以"钩子绿"绝不等于"趋势行也补了"，反之亦然，各查各的。
- **`--gate` 无 .map → SKIP，而脚本自己写明「SKIP 不等于 PASS」**（`ram_baseline.py:177`）：
新开的 task-worktree 从没在这棵树上构建过时必然走到这里；同一状态下 `--write` 直接
`[FAIL] 找不到 .map 事实源，先 /keil-build`（`ram_baseline.py:250`）——不是代码缺陷，是这棵树还没测过体积。
无需 Keil 的强制兜底是 `scripts/check_size_gate.py --local`（= `scripts/ci_local.py` 的体积门禁步）与 CI 的 `--ci`。
- **`--map <path>` 只换读、不换写**：`LEDGER`（`ram_baseline.py:45`）与 `TARGETS`（`check_mem_numbers.py:53-54`）
都由 `REPO_ROOT = Path(__file__).resolve().parent.parent` 算出。拿主仓脚本配 `--map <另一棵树>/…map` 去 `--write`，
等于用别的树的数字**改写主仓的台账**——比"半棵树混合数字"更糟，因为它落盘了。回填永远用本树自己的脚本。
- **`--scan` 的散句告警 `--write` 不替你改**：正文里手抄的旧值（"现 RW_IRAM1 62.6%" 这类散句）只告警，
脚本明确写着「`--write` 不会自动改写正文」（`check_mem_numbers.py:418`）→ 人工按受管区改那一行
（Edit 精确替换；含中文的文档绝不整文件重写）。
- **`--update` 的盖戳排在索引后面**：它顺带调 `check_size_gate.cmd_stamp()`（`ram_baseline.py:345`），
而凭证指纹按 **git 索引内容**生成，有未 staged 的脏改动时**拒盖**，且这里只 `[WARN]`、不改返回值
→ 现象是 tsv 多了一行而凭证仍是旧的，要等 `ci_local` 的体积门禁步 / CI 体积门禁那一侧才报出来。
要么先 `git add` 再 `--update`，要么补跑 `python scripts/check_size_gate.py --stamp`。
- **改写型钩子当场改文件是流程不是故障**：`trailing-whitespace` / `end-of-file-fixer` 报
`files were modified by this hook`（新建的 .c 最常触发）时，先读 `ci-artifacts/cui.log` 的真实报错确认是哪几条红，
`git add` 被改写的文件后重提。两条改写红 + 两条内存红混在同一次里时，别顺手把内存那条也当"钩子误报"绕过去。
- **`mem-budget` 触发面很宽**：`files:` 覆盖 `App/` `Drivers/BSP/` `Src/` `Inc/` `Lib/lv_conf.h`
`test/board/` `scripts/ram_baseline.` `docs/内存管理/` `.pre-commit-config.yaml`，且 pre-commit 4.x 已无
`always: true` —— 纯 UI / 纯文档提交照样被它拦：盘上 .map 与台账不同源就红，跟这笔提交碰没碰内存文件无关。
.dsh/skills/mem-budget/reference/measurement-identity.md
+58
View File
@@ -0,0 +1,58 @@
# 测量身份口径（先钉树与时刻，再看数字）（自 SKILL.md 外置）
> 本文由 mem-budget 的 SKILL.md「测量身份口径（先钉树与时刻，再看数字）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
### 1. 脚本按 `__file__` 定位产物，不按 cwd —— 跨树必须换脚本
```python
# scripts/stack_report.py:36-38
REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
HTM_DEFAULT = REPO_ROOT / "MDK-ARM" / "STM32F407-Demo" / "STM32F407-Demo.htm"
FREERTOS_C = REPO_ROOT / "Src" / "freertos.c" # 配置栈来源，无命令行开关
# scripts/ram_report.py:16-18 同样用 dirname(dirname(abspath(__file__))) 定位 .map
```
⇒ `cd 进别的 worktree 再跑主仓的脚本` 量的仍是**主仓**那份 .htm/.map，数字不可比。
实测代价：这样一次"独立复算"量到主仓的 1,544 B / margin 1,016 B FAIL，据此写下的 +80 B 归因
被队友的逐树逐帧差分表推翻——目标 worktree 的真数是 1,464 B / margin 1,096 B / PASS。
正确做法：**量哪棵树就跑那棵树自己的脚本**（该树必须已在这棵树上构建过、有自己的 .htm/.map；
开树与合并的生命周期见 `task-worktree` skill）：
```bash
'.venv/Scripts/python.exe' "<目标树>/scripts/stack_report.py"
'.venv/Scripts/python.exe' "<目标树>/scripts/ram_report.py"
```
⚠ 只给主仓脚本传 `-i <另一棵树的 .htm>`（或位置参数传另一棵树的 .map）**不够**：
`stack_report.py` 的配置栈仍从**脚本所在那棵树**的 `Src/freertos.c` 读（`FREERTOS_C` 写死自 `__file__`，
没有开关），两树栈配置一旦不同就是"半棵树的混合数字"。要整支脚本换树跑。
自检（每次复算都做）：报告头两行 `- Source: ...` 与 `- Linker run: ...` 就是你实际量的树和时刻。
`Source` 若只打印一个裸文件名（不带 `MDK-ARM/...` 相对路径），说明 `-i` 指到了脚本 `REPO_ROOT` 之外的产物。
### 2. 重跑报告脚本**不算新测量**（复述 ≠ 复验）
`stack_report.py` / `ram_report.py` 只是解析盘上那一份 .htm/.map；产物没变，再跑一次数字必然不变。
那只能叫"复述"，**不能写成"我复验过"**。要拿到新数字必须先有一次**新的 Linker run**（增量构建也算），
并把新时刻与产物来源一并写进记录。
⚠ `ram_report.py` 正文里的 `> Generated: …` 是**脚本运行时刻**，重跑就变——它不是链接时刻，
不能拿来当"这是新测量"的凭证。
### 3. 钉身份的取数法（.htm/.map 按约定不入库 → 把时刻写进正文/台账）
```bash
grep -aE 'Last Updated|Maximum Stack Usage' MDK-ARM/STM32F407-Demo/STM32F407-Demo.htm | head -2
# → "ARM Linker, 5060960: Last Updated: Mon Oct 26 22:52:12 2026"
```
- .htm 里唯一的链接时刻锚点是 **`Last Updated:`**；`Linker run` 只是 `stack_report.py` 自己输出里的标签，
`Date of Link`、`Image component` **不在 .htm 里**（实测按它们 grep 全空，白跑一轮）。
- 取不到该字段时退回产物 mtime；同一笔链接里 .htm 与 .map 的 mtime 只差 ~0.1 s，可据此确认两份产物同源。
再配 `git log -1 --format=%H` 与该树 `git status` 的未跟踪文件数。
- 记录最小格式：**`tree/commit + Linker run 时刻 + 产物来源（本次构建 / 盘上既有）`**。
本仓 .htm/.map 不入库，不钉时刻就等于把数字和树脱钩，下一个读数字的人无从判断它描述哪棵树。
- 归属还能机械证明时顺手做掉：`git log --name-only <那笔>..HEAD -- "*.c" "*.h"` 逐行筛（排除 `.uvprojx`）。
若那笔之后没有任何提交再碰固件源文件，产物描述的就是**在库那棵树**，不是提交前快照。
- 同族坑：`git show :path` / `git show HEAD:path` 读的是索引/HEAD，**不是工作区**。
.dsh/skills/mem-budget/reference/shared-frame-attribution.md
+24
View File
@@ -0,0 +1,24 @@
# 静态最坏链回归的归因（同涨同一数值 = 共享帧，不是调用方）（自 SKILL.md 外置）
> 本文由 mem-budget 的 SKILL.md「静态最坏链回归的归因（同涨同一数值 = 共享帧，不是调用方）」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
- **多条任务链分毫不差同涨/同降同一个数值**（实测 default/net/iec104 三条 +80 B；断环后九条链各 −80 B）
⇒ 加深在这些任务**共用的被调帧 / 共享尾段**上，不在任何一个调用方。别逐个调用方翻，
也**别先猜"新增了大局部缓冲"**——实测猜错过一次（`con_ring_try` 只有 24 B 帧、没有数组）。
- 逐棵树逐帧比 frame size，不要只比总数：
- `stack_report.py` 输出的「Frame-size ranking (own frame)」表 + 每任务最坏链文本，锁定**链尾公共段**
（实测落在 `dbg_console_write_line → con_append → dbg_console_drain`，据此把账记到上一笔提交上）；
- 直接在 .htm 里找环：`grep -ac 'In Cycle' MDK-ARM/STM32F407-Demo/STM32F407-Demo.htm`（实测 17 处），
形态为 `Max Depth = 280 + In Cycle` 与 `Call Chain = Error_Handler => dbg_console_write_line (Cycle)`。
`+ In Cycle` 表示 armlink 把**环上所有帧**计入含该环的每一条任务链——**链接器幻影环**能在无人改栈配置时让全仓链齐涨。
- 实测样本（无人改栈配置、全仓链却齐涨的那种）：taskEXIT_CRITICAL ⇒ vPortExitCritical ⇒ configASSERT ⇒
vApplicationAssertFailed ⇒ dbg_console_write_raw ⇒ 回到 console_log 内部 ⇒ 再进临界区；
它使 `vApplicationAssertFailed` 的 Max Depth 由 ~40 B 变 128 B + In Cycle，差 88 B ≈ 三条链同涨 80 B 的来源。
断环方向：内核临界区改 PRIMASK 保存/恢复（保存量放局部变量）→ 零调用帧、不成环；
断环的**图证**（该帧从「136 B + In Cycle」变成「8 B、不再 In Cycle」）比数字更有说服力。
- `Maximum Stack Usage = N bytes + Unknown(Cycles, Untraceable Function Pointers)` 里的 `+ Unknown(...)`
说明静态图对环与函数指针不可完全解析，静态数是估计值，别当精确值上报。
- 不采信任何口头结论：用**目标树的脚本 + `.venv` 解释器**自己复算；复算同样先按上节钉身份。
- 处置后的下一步：抬栈（`Src/freertos.c` 的 `USER CODE` 区，属 Ask-first 动作）或收紧共享缓冲 / 断环，
**改前改后各一次** `stack_report.py` + `ram_report.py`，且"改后"那次必须落在一次新的 Linker run 上；
抬栈后跑 `gen_task_table.py` 同步任务表。
.dsh/skills/new-source-file/SKILL.md
+1 -1
View File
@@ -36,5 +36,5 @@ cmake --build simulator/build --config Debug # 0 警告
- **禁止**把源文件复制进 `simulator/`——两端共用 `Drivers/BSP/` 原件（UI_界面制作流程.md C7）
- 只注册 `.c`（含 `.s`）；`.h` 靠 include 路径找到，不加工程
- 漏注册的典型症状：一端编译失败（undefined reference）或一端行为悄悄停留在旧逻辑
- 注册完成后跑回归：UI 文件 → `ui-verify` skill；其他模块 → `@test`（`.dsh/skills/serial-boot-test/scripts/run_boot_test.py`）
- 注册完成后跑回归：UI 文件 → `ui-verify` skill；其他模块 → `/serial-boot-test`（`.dsh/skills/serial-boot-test/scripts/run_boot_test.py`）
- 改过 `CMakeLists.txt` 后需重新 `cmake -B build` 配置
.dsh/skills/serial-assistant/scripts/serial_tool.py
+16 -16
View File
@@ -2,7 +2,7 @@
# -*- coding: utf-8 -*-
"""serial_tool — Python 串口助手（常驻 daemon + 薄 CLI + 日志文件即接口）。
设计文档：docs/测试说明/串口助手设计说明.md
设计文档：docs/测试说明/测试工具/串口助手设计说明.md
架构：
CLI（短命进程，硬超时） --HTTP JSON--> daemon（detached 单实例，127.0.0.1）
@@ -19,7 +19,7 @@
status 全状态（单条 JSON）
log --tail N --grep P 读日志（先过滤后截尾；-i 忽略大小写 / --regex 正则）
clear 清空日志（原子截断 + 代际递增）
wait-idle 等 RX 静默（@test 用；--settle-ms / --max-ms / --first-timeout-ms）
wait-idle 等 RX 静默（/serial-boot-test 用；--settle-ms / --max-ms / --first-timeout-ms）
start / stop / restart daemon 生命周期（其余命令会自动拉起 daemon）
selftest 无头自检（行拆分/解码回退/截头算法，无需硬件）
@@ -615,10 +615,10 @@ class Daemon:
def wait_idle(self, settle_s, max_s, first_timeout_s=None):
"""等 RX 静默，返回 reason ∈ {idle, no_data, timeout}。
2026-10-09 修三处（旧实现会让 @test 在"板子全程没输出"时误判收尾）：
2026-10-09 修三处（旧实现会让 /serial-boot-test 在"板子全程没输出"时误判收尾）：
1. no_data 判据：旧实现比的是"进入函数时 daemon 累计 rx_bytes 是否为 0"。
daemon 常驻（本机实测 rx_bytes=1.2MB）→ 永远 >0 → 板子一个字节都不发
也返回 idle:true，@test 的 no_data 拦截形同虚设。现按**本次增量**判。
也返回 idle:true，/serial-boot-test 的 no_data 拦截形同虚设。现按**本次增量**判。
2. 首字节门：旧实现从进入即开始计静默时间，板子第一行比 settle_ms 来得
晚就提前收尾（"开机日志缺尾巴"的另一半成因）。现首字节到达前不启动
settle 计时，改由 first_timeout_s 兜底（默认 = max_s）。
@@ -1123,26 +1123,26 @@ def run_selftest():
def check(name, cond, detail=""):
results.append((name, bool(cond), detail))
# T1 行拆分：CRLF / 多行 / 残行冲刷
# 行拆分：CRLF / 多行 / 残行冲刷
sp = LineSplitter()
got = [l for _, l in sp.feed(b"abc\r\n", 1000.0)]
check("T1a CRLF 行", got == [b"abc"], repr(got))
check("行拆分：CRLF 行", got == [b"abc"], repr(got))
got = [l for _, l in sp.feed(b"de\nf\n", 1001.0)]
check("T1b 多行", got == [b"de", b"f"], repr(got))
check("T1c 残行不入文件", sp.feed(b"ghi", 1002.0) == [] and sp.buf == b"ghi")
check("行拆分：多行", got == [b"de", b"f"], repr(got))
check("行拆分：残行不入文件", sp.feed(b"ghi", 1002.0) == [] and sp.buf == b"ghi")
got = [l for _, l in sp.flush_partial()]
check("T1d 残行冲刷", got == [b"ghi"], repr(got))
check("行拆分：残行冲刷", got == [b"ghi"], repr(got))
got = sp.feed(b"\n\n", 1003.0)
check("T1e 空行忽略", all(not raw for _, raw in got) and sp.buf == b"", repr(got))
check("行拆分：空行忽略", all(not raw for _, raw in got) and sp.buf == b"", repr(got))
# T2 解码回退链
# 解码回退链
check("T2a UTF-8", decode_line("中文ok".encode("utf-8")) == "中文ok")
check("T2b GBK", decode_line("中文".encode("gbk")) == "中文")
check("T2c HEX 兜底", decode_line(b"\xff\xfe\x01") == "HEX:fffe01")
# T3 时间戳格式
# 时间戳格式
s = line_at(time.time(), "RX", "x")
check("T3 行格式", s.startswith("[RX] ") and "T" in s.split(" ")[1], s)
check("时间戳行格式", s.startswith("[RX] ") and "T" in s.split(" ")[1], s)
# T4 截头算法（保留尾部 + 截后继续追加）
pat = b"0123456789abcdef"
@@ -1298,8 +1298,8 @@ def run_selftest():
except OSError:
pass
# T10 端口建议：换 USB 口后 COM 号变了，唯一候选直接给（多候选不猜）
check("T10 port_hint 唯一候选才给建议",
# 端口建议：换 USB 口后 COM 号变了，唯一候选直接给（多候选不猜）
check("端口建议：唯一候选才给建议",
port_hint("COM7", ["COM6"]) == "COM6"
and port_hint("COM7", ["COM6", "COM9"]) is None
and port_hint("COM6", ["COM6"]) is None)
@@ -1353,7 +1353,7 @@ def build_parser():
sub.add_parser("clear", parents=[common], help="清空日志（代际 +1）")
p = sub.add_parser("wait-idle", parents=[common], help="等 RX 静默（@test 用）")
p = sub.add_parser("wait-idle", parents=[common], help="等 RX 静默（/serial-boot-test 用）")
p.add_argument("--settle-ms", type=int, default=8000,
help="静默判据毫秒（默认 8000：boot 有 3~4s 自然静默间隙）")
p.add_argument("--max-ms", type=int, default=30000, help="最长等待毫秒（默认 30000）")
.dsh/skills/serial-boot-test/SKILL.md
+8 -2
View File
@@ -14,7 +14,11 @@ 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/锚点计数/顺序/耗时），可单独用 |
| `.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`。
> **判据取向（重要，会复发）**：`--exact` 默认**只锚文本、不钉长度**——字节长度属于某一份构建，钉死它会在无辜改动上假红（`@@LEN=<n>` 是显式逃生口，不是默认）。子串 `--required` 不能用于"可能丢行首/被插字节"的行。来龙去脉与固定动作见本仓 `docs/测试说明/专项验证/启动日志原子性复验流程.md`。
交互式串口操作（open/send/log/wait-idle/status 等）不属于本 skill——
**用 `serial-assistant` skill**。
@@ -47,7 +51,9 @@ whenToUse: 需要向目标板烧录或复位后，用串口日志自动判定运
| `done_marker` + `max_boot_ms` | 开机耗时口径与上限 | 空/0 = 只报告不判 |
| `settle_ms` / `max_wait_ms` / `first_wait_ms` | RX 静默判据 / 总超时 / 首字节超时 | 8000 / 30000 / 12000 |
| `require_order` / `expect_reset_cause` / `require_suite_summary` | 顺序校验 / 复位原因白名单 / 套件汇总行 | 空 = 关闭 |
| `require_selftest_pass` + `device_ip` | 设备侧自检台账联合判定（FTP 抓取） | 关闭 |
| `selftest_scope` | 自检台账判定口径：`this-run`（烧录前取基线，只判新增）/ `all`（累计，任一记录即 FAIL） | `this-run` |
| `ftp_user` / `ftp_pass` | 抓 `/log/selftest.log` 用的 FTP 账号（设备无匿名通道） | `admin` / `admin` |
| `require_selftest_pass` + `device_ip` | 设备侧自检台账联合判定（FTP 抓取；**默认只判本次启动新增**，抓取失败/无数据源一律 FAIL） | 关闭 |
**先跑项目的构建**（本仓库 = `keil-build` skill，其它 Keil 项目照该 skill 套；
非 Keil 项目用项目自己的构建入口），确认 0 错误 0 警告后再进闭环。
.dsh/skills/serial-boot-test/config.example.json
+3
View File
@@ -24,6 +24,9 @@
"require_selftest_pass": false,
"device_ip": "",
"selftest_scope": "this-run",
"ftp_user": "admin",
"ftp_pass": "admin",
"httpPort": 18765
}
.dsh/skills/serial-boot-test/scripts/run_boot_test.py
+183 -31
View File
@@ -19,9 +19,12 @@
5. verify_log.py 标记校验（含启动锚点计数 config "boot_marker" + --max-boot-count；
--expect-reset-cause 原因白名单；--require-order 标记顺序；
--done-marker + --max-boot-ms 开机耗时）
6. （仅当 --require-selftest-pass）自检记录联合判定（S7）：
--selftest-log 提供本地副本则直接用它，否则从设备 FTP 抓取 /log/selftest.log
（需 config "device_ip"）；判定：文件缺失 / 0 字节 = 无故障 → PASS
6. （仅当 --require-selftest-pass）自检台账联合判定：默认**只判本次启动新增**
——烧录前先经 FTP 取 /log/selftest.log 基线，启动后再取一次，只把"基线之后新增"的
记录交给判定（该文件是 512 条环形累计历史，"非空即 FAIL"判一次启动永远不可能过）。
设备侧无此文件 = 台账干净 = PASS；**抓取失败 / 没有数据源 / 基线被环覆盖 → FAIL**，
不再"视为无记录"放过。累计口径用 --selftest-scope all；--selftest-log 走本地副本
（无基线可比，自动降级为 all）。FTP 凭据 --ftp-user/--ftp-pass（默认出厂 admin）。
采集在烧录**之前**武装（open + clear 先于烧录），daemon 常驻全量日志兜底，
无采集窗口/首字节等待仪式。
@@ -46,7 +49,7 @@
[--flash-cmd "<烧录命令>"] [--flash-timeout 180]
[--required "m1;m2"] [--forbidden "FAIL;ERROR;HardFault"]
[--require-suite-summary "Storage Tests"]
[--require-selftest-pass] [--selftest-log <本地副本>]
[--require-selftest-pass [--selftest-scope this-run|all]] [--selftest-log <副本>]
[--device-ip 192.168.1.100] [--out-dir <目录>] [--show-tail-lines 15]
[--fw-hex <构建产物 hex>] [--no-fw-check]
[--no-verify-flash] [--readback-timeout 120]
@@ -58,7 +61,7 @@
退出码（与旧版一致）:
0 = PASS（采集成功 + Required 全中 + Forbidden 零命中）
1 = FAIL（标记缺失/命中）
1 = FAIL（标记缺失/命中；或要求自检台账判定却判不了——无数据源/抓取失败/无法证明无新增）
2 = 采集或烧录错误（含烧录回读不一致 = 芯片内容与刚编的镜像不同，本次运行作废）
3 = 用法/预检错误
"""
@@ -137,8 +140,8 @@ def _split_cmd(cmd_str):
直接交给 subprocess、**不经 `cmd /c`**：CreateProcess 能直接跑 .bat，且 Python
会给含空格的路径正确加引号。旧写法 `['cmd','/c', 串]` 在本仓库（目录名
`DTU Code` 含空格）会被 cmd 的 /c 引号规则玩坏——实测报
`'D:\Code\DTU' is not recognized`，回读校验被假判成"芯片内容不一致"。
路径本身含空格时把该段用引号包住（`"D:\some dir\flash_tool.bat" flash`）。
「'D:\Code\DTU' is not recognized」，回读校验被假判成"芯片内容不一致"。
路径本身含空格时把该段用引号包住（「"D:\some dir\flash_tool.bat" flash」）。
posix=False 是必须的：posix=True 会吃掉 Windows 路径里的反斜杠。
"""
return [p.strip('"') for p in shlex.split(cmd_str, posix=False)]
@@ -223,7 +226,7 @@ def _ftp_quit(ftp):
def _prune_out_dir(out_dir, keep):
"""只保留最近 N 份产物（`boot_log_*.txt` / `selftest_log_*.log`）。
这些文件按 `%Y%m%d_%H%M%S` 命名、每次 @test 各留一份，旧实现从不清理——
这些文件按 `%Y%m%d_%H%M%S` 命名、每次 /serial-boot-test 各留一份，旧实现从不清理——
本机实测 out 目录已堆到 31 份 boot_log + 7 份 selftest_log（2026-10-10）。
文件名含时间戳 → 按名字排序即按时间排序。
"""
@@ -240,42 +243,86 @@ def _prune_out_dir(out_dir, keep):
return removed
def _fetch_selftest_log(device_ip, out_dir, stamp):
"""从设备 FTP 抓取 /log/selftest.log（lftpd :21 匿名，根目录 = 卷根）。
def _selftest_records(path):
"""把 selftest.log 的本地副本切成 64 B 定长记录（尾部残块不算记录）。
成功返回本地路径字符串；失败（网络不可达 / FTP 错误 / 设备侧文件缺失）返回 ""
（按 S7 语义视为无故障记录；此处打 WARN，调用方不判整体 FAIL）。
返回 [] = 台账为空（干净设备）；返回 None = **未知**（文件不可读等）。
两者绝不能混——把"看不见"当成"没有"正是假绿的成因。
"""
if not path:
return []
try:
raw = Path(path).read_bytes()
except OSError as exc:
print("RUN_TEST_WARN: 自检台账本地副本不可读: {}".format(exc))
return None
n = len(raw) - (len(raw) % 64)
return [raw[i:i + 64] for i in range(0, n, 64)]
def _selftest_new_records(baseline, after):
"""基线对比 → 本次运行新增的记录，返回 (新增列表, 能否证明)。
· baseline is None → 基线未知 → 无法证明
· baseline == [] → 设备原本无台账 → after 全部算本次新增
· 基线最后一条在 after 里找得到 → 它之后的就是新增
· 找不到 → 512 条环已覆盖基线（更新量 ≥ 环容）→ 无法证明；
宁可 FAIL，也不拿"看不到"当"没有"
"""
if baseline is None or after is None:
return [], False
if not baseline:
return list(after), True
last = baseline[-1]
for idx in range(len(after) - 1, -1, -1):
if after[idx] == last:
return list(after[idx + 1:]), True
return [], False
def _fetch_selftest_log(device_ip, out_dir, stamp, ftp_user="admin", ftp_pass="admin"):
"""从设备 FTP 抓取 /log/selftest.log（lftpd :21 需鉴权，根目录 = 卷根）。
返回 (本地路径, 状态)，状态 ∈ {"ok", "absent", "error"}：
ok = 抓到文件（路径有效）
absent = 设备侧确实没有这个文件 = 台账干净（正常路径，不是故障）
error = 连不上 / 登录被拒 / FTP 故障 → 结果**未知**，调用方必须判 FAIL
⚠ 2026-10-22 关键更正：旧实现把 absent 与 error 都返回 ""，调用方一律"视为无
记录 → PASS"。于是抓取失败会被读成"设备很干净"——这就是那条假绿。三种结果
必须分开。
2026-10-02 台架修复：原实现只 `except OSError`，而 ftplib 的 error_temp /
error_perm 继承自 Exception 而非 OSError —— 台账"仅故障才写"，干净设备上
/log/selftest.log 根本不存在，RETR 返回 450 直接抛出未捕获异常，令整个
`@test --require-selftest-pass` 在最后一步崩掉（而它本该是 PASS 路径）。
`run_boot_test.py --require-selftest-pass` 在最后一步崩掉（而它本该是 PASS 路径）。
现把"设备侧无此文件"单列为正常路径（INFO），其余 FTP 错误保留 WARN。
"""
local = Path(out_dir) / "selftest_log_{}.log".format(stamp)
ftp = ftplib.FTP()
try:
ftp.connect(device_ip, 21, timeout=10)
ftp.login() # 匿名（lftpd 接受 USER anonymous / 空 PASS）
# lftpd 按 /config.ini 的 [ftp] 校验账号（user / pwd_hash），出厂 admin/admin；
# 设备没有匿名通道——匿名登录一律 530，所以这里必须带凭据。
ftp.login(ftp_user, ftp_pass)
except (OSError, ftplib.Error) as e:
print("RUN_TEST_WARN: selftest fetch failed: {} "
"(按 S7 语义视为无记录；设备网络/FTP 需另行排查)".format(e))
return ""
print("SELFTEST_FETCH: {} -> ERROR ({}) 连不上/登录被拒/FTP 故障 → 状态未知"
.format(device_ip, e))
return "", "error"
buf = bytearray()
try:
ftp.retrbinary("RETR /log/selftest.log", buf.extend)
except ftplib.all_errors as e:
# 450/550 = 设备侧无此文件：干净台账，S7 判 PASS（正常路径，非故障）
print("SELFTEST_FETCH: {} -> (ledger absent: {}) 按 S7 视为无故障记录"
# 450/550 = 设备侧无此文件：干净台账 → 判定 PASS（正常路径，非故障）
print("SELFTEST_FETCH: {} -> (ledger absent: {}) 台账干净"
.format(device_ip, str(e).strip()))
_ftp_quit(ftp)
return ""
return "", "absent"
_ftp_quit(ftp)
local.write_bytes(bytes(buf))
print("SELFTEST_FETCH: {} -> {} ({} bytes)".format(device_ip, local, len(buf)))
return str(local)
return str(local), "ok"
def main(argv=None):
@@ -308,14 +355,23 @@ def main(argv=None):
help="forbidden patterns, ';' separated (config 'forbidden')")
ap.add_argument("--require-suite-summary", default=None,
help="suite names that MUST appear as '=== <name>: N/M PASSED (failed=0) ===' "
"with N>0, ';' separated (T-2). Empty = off")
"with N>0, ';' separated. Empty = off")
ap.add_argument("--require-selftest-pass", action="store_true", default=None,
help="jointly judge /log/selftest.log (S7): missing/empty = PASS, "
help="jointly judge /log/selftest.log: missing/empty = PASS, "
"any 64B record = FAIL")
ap.add_argument("--selftest-log", default=None,
help="local copy of /log/selftest.log (skips device-side fetch when given)")
ap.add_argument("--selftest-scope", choices=("this-run", "all"), default=None,
help="this-run (default): only records added by THIS run count as "
"faults -- needs a pre-flash baseline over FTP, so device_ip is "
"required. all: legacy cumulative rule (any record = FAIL); use it "
"for audits or a first baseline. Unproveable cases FAIL, never PASS.")
ap.add_argument("--device-ip", default=None,
help="device IP for fetching /log/selftest.log via FTP (anonymous)")
help="device IP for fetching /log/selftest.log via FTP")
ap.add_argument("--ftp-user", default=None,
help="FTP user for the selftest fetch (config 'ftp_user'; default admin)")
ap.add_argument("--ftp-pass", default=None,
help="FTP password for the selftest fetch (config 'ftp_pass'; default admin)")
ap.add_argument("--out-dir", default=None)
ap.add_argument("--show-tail-lines", type=int, default=None)
ap.add_argument("--fw-hex", default=None,
@@ -336,6 +392,23 @@ def main(argv=None):
ap.add_argument("--require-order", default=None,
help="'>'-separated markers that must appear in that line order "
"(catches out-of-order boot steps); empty = off")
ap.add_argument("--exact", action="append", default=[],
help="repeatable regex that must match a WHOLE firmware line "
"(forwarded to verify_log.py --exact). Use it instead of --required "
"for any marker whose line could lose its head or gain spliced "
"bytes -- substring matching cannot see that class of damage. "
"Suffix '@@LEN=<n>' pins byte length: opt-in only, lengths belong "
"to one image")
ap.add_argument("--pair", action="append", nargs=2, metavar=("FIRST", "THEN"), default=[],
help="repeatable cross-reset pairing (exactly one FIRST, then exactly "
"one THEN after it), e.g. --pair MEMFAULT 'reset cause:'")
ap.add_argument("--allow-residual", type=int, default=0,
help="accept up to N stray bytes before the line head on a --exact hit "
"(crash-dump legs: 1 leftover from a reset mid-byte is known; "
"recorded, not a failure)")
ap.add_argument("--head-char", default="",
help="every --exact hit must start with this char after the optional "
"residual prefix (crash-dump legs: '[')")
ap.add_argument("--done-marker", default=None,
help="marker whose line marks boot completion (for --max-boot-ms); "
"empty = don't measure")
@@ -384,10 +457,17 @@ def main(argv=None):
args.forbidden = str(_pick(args.forbidden, "forbidden", default=FORBIDDEN_DEFAULT))
args.require_suite_summary = str(_pick(args.require_suite_summary,
"require_suite_summary", default="") or "")
args.selftest_scope = str(_pick(args.selftest_scope, "selftest_scope",
default="this-run") or "this-run")
if args.selftest_scope not in ("this-run", "all"):
print("RUN_TEST_USAGE_ERROR: selftest_scope must be this-run or all")
return 3
args.require_selftest_pass = bool(_pick(args.require_selftest_pass,
"require_selftest_pass", default=False))
args.selftest_log = str(_pick(args.selftest_log, "selftest_log", default="") or "")
args.device_ip = str(_pick(args.device_ip, "device_ip", default="") or "")
args.ftp_user = str(_pick(args.ftp_user, "ftp_user", default="admin") or "admin")
args.ftp_pass = str(_pick(args.ftp_pass, "ftp_pass", default="admin") or "admin")
args.out_dir = str(_pick(args.out_dir, "out_dir",
default=str(Path(tempfile.gettempdir()) / "serial-boot-test")))
args.show_tail_lines = int(_pick(args.show_tail_lines, "show_tail_lines", default=15))
@@ -446,6 +526,34 @@ def main(argv=None):
print("Port: {} @ {} settle={}ms max={}ms".format(
port, args.baud_rate, args.settle_ms, args.max_wait_ms))
# 0.6 自检台账基线（只看本次新增）：**必须排在串口采集武装之前**。
# /log/selftest.log 是 512 条环形累计历史，用"文件非空即 FAIL"去判一次启动，在任何
# 做过故障注入或长跑的设备上永远不可能 PASS（本仓台架实测：抓到的 29 条记录时间戳
# 全是 2026-10-10 ~ 10-14 留下的，与本次启动无关）。这里记下基线的最后一条记录，
# 启动后只判"它之后新增了几条"；抓不到基线就判不了本次 → 退出码 2，不降级成"视为
# 无记录"。
# ⚠ 为什么排在 open/clear 之前（2026-10-22 实测踩到）：抓基线是一次真实 FTP 会话，
# 设备会把 `USER/PASS/RETR` 打到串口上，客户端退出时还会多打一行 `[ERR] [FTP] error
# reading next command`——放在采集武装之后，这些行就落进本次启动日志：既让 Forbidden
# `[ERR]` 命中（本次判 FAIL），又把开机耗时从 ~0.6 s 拉到 ~8 s（假指标）。
st_baseline = None
if args.require_selftest_pass and args.selftest_scope == "this-run":
if args.selftest_log:
print("SELFTEST_BASELINE: 用的是本地副本，无基线可比 → 本次按累计口径判定")
args.selftest_scope = "all"
elif not args.device_ip:
print("SELFTEST_BASELINE: 没有 device_ip 就取不到基线 → 本次按累计口径判定")
args.selftest_scope = "all"
else:
base_local, base_status = _fetch_selftest_log(
args.device_ip, out_dir, stamp + "_base", args.ftp_user, args.ftp_pass)
if base_status == "error":
print("RUN_TEST_ERROR: 自检台账基线抓取失败 → 无法证明本次无新增故障"
"（不把抓取失败当成设备干净）")
return 2
st_baseline = _selftest_records(base_local)
print("SELFTEST_BASELINE: 既有记录 {} 条（status={}）"
.format(len(st_baseline or []), base_status))
# 1. open（幂等；未运行则自动拉起常驻 daemon）
data, out = tool("open", "--port", port, "--baud", str(args.baud_rate), "--timeout", "15")
if data is None:
@@ -590,13 +698,50 @@ def main(argv=None):
print("RUN_TEST_ERROR: flash readback mismatch (chip content != built image)")
return 2
# 5.5 自检记录抓取（S7）：启用且未提供本地副本时才走 FTP（需 config "device_ip"）
# 5.5 自检记录判定：默认只判「本次启动新增」，累计口径要显式指定。
# 三种抓取结果必须分开对待（旧实现把后两种都当"无记录 → PASS"，就是假绿）：
# absent（设备侧无此文件） → 台账干净 → 无新增 → PASS
# error（连不上/登录被拒/故障）→ 未知 → FAIL（要求判定却没数据，不能当通过）
# 没有数据源（无 device_ip 又无 --selftest-log）→ FAIL（同上）
selftest_local = args.selftest_log
if args.require_selftest_pass and not selftest_local and not args.device_ip:
print("RUN_TEST_WARN: require_selftest_pass but no device_ip/selftest_log "
"-> treated as no record (S7 PASS path)")
if args.require_selftest_pass and not selftest_local and args.device_ip:
selftest_local = _fetch_selftest_log(args.device_ip, out_dir, stamp)
selftest_forced_fail = False
if args.require_selftest_pass:
if selftest_local:
pass # 本地副本：按它自己的口径判（基线已在 2.5 降级）
elif not args.device_ip:
print("RUN_TEST_FAIL: 要求自检台账判定，但既没有 device_ip 也没有 --selftest-log"
" → 无数据源，判 FAIL（旧行为是 WARN 后当无记录放过）")
selftest_forced_fail = True
else:
after_local, after_status = _fetch_selftest_log(
args.device_ip, out_dir, stamp, args.ftp_user, args.ftp_pass)
if after_status == "error":
print("RUN_TEST_FAIL: 自检台账抓取失败（设备不可达 / FTP 故障）→ 判 FAIL"
"（不把抓取失败当成设备干净）")
selftest_forced_fail = True
elif after_status == "absent":
selftest_local = None # 空台账 = 确无故障
elif args.selftest_scope == "this-run":
new_recs, provable = _selftest_new_records(
st_baseline, _selftest_records(after_local))
if not provable:
print("SELFTEST_JUDGE: FAIL —— 无法证明本次无新增"
"（基线最后一条已被 512 条环覆盖，或基线/台账不可读）")
selftest_forced_fail = True
elif not new_recs:
print("SELFTEST_JUDGE: 本次启动无新增记录（基线 {} 条 → 台账不变）"
.format(len(st_baseline or [])))
selftest_local = None
else:
# 文件名必须落在 selftest_log_*.log 里，才会被 --keep-out 的保留规则收走
delta = out_dir / "selftest_log_{}_new.log".format(stamp)
delta.write_bytes(b"".join(new_recs))
print("SELFTEST_JUDGE: 本次启动新增 {} 条 → 只把新增部分交给判定"
.format(len(new_recs)))
selftest_local = str(delta)
else:
selftest_local = after_local # --selftest-scope all：累计口径
# 6. 标记校验（含固件身份戳、启动锚点计数、可选的自检记录联合判定）
# 启动锚点（config "boot_marker"，如本仓库的 'reset cause:'）未配置 =
@@ -615,7 +760,14 @@ def main(argv=None):
expect_reset_cause=args.expect_reset_cause,
require_order=args.require_order,
done_marker=args.done_marker,
max_boot_ms=args.max_boot_ms)
max_boot_ms=args.max_boot_ms,
exact=args.exact, pairs=args.pair,
allow_residual=args.allow_residual, head_char=args.head_char)
if selftest_forced_fail and rc == 0:
# 标记校验全过，但自检台账判定根本没能执行（无数据源 / 抓取失败 / 无法证明无新增）
# —— 这类"判不了"必须以 FAIL 收口，否则就又回到假绿。
print("RUN_TEST_VERDICT: FAIL —— 自检台账判定未能执行（见上方 SELFTEST 行）")
rc = 1
print("RUN_TEST_RC={}".format(rc))
return rc
.dsh/skills/serial-boot-test/scripts/verify_log.py
+324 -16
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env python3
"""verify_log.py - 对抓取的 MCU 调试日志做标记校验（纯标准库，2026-09-20 替代 verify_log.ps1）。
用于 @test 闭环：烧录后从串口助手日志提取的开机日志交给本脚本 grep 标记，
用于 /serial-boot-test 闭环：烧录后从串口助手日志提取的开机日志交给本脚本 grep 标记，
输出结构化判定（格式与旧 PowerShell 版逐字一致，下游文档/习惯不受影响）。
用法:
@@ -16,10 +16,15 @@
[--require-order 'App init OK>Network Init>net init: OK']
[--done-marker 'net init: OK'] [--max-boot-ms 8000] [--json]
退出码（与旧版一致）:
退出码（2026-10-27 task-32 起把 2 讲清楚；/serial-boot-test 那层的码不变）:
0 = PASS（所有 Required 标记找到，Forbidden 零命中，汇总行要求满足）
1 = FAIL（缺 Required / 命中 Forbidden / 汇总行要求不满足）
2 = ERROR（日志文件不存在/不可读）
1 = FAIL（**设备侧真有坏消息**：缺 Required / 命中 Forbidden / 汇总行不满足 / 顺序或耗时超限）
2 = **测量没成立**（日志不存在或不可读；或开了 --max-boot-count 却零启动锚点 = 采集器没开、
日志被清、或采集没从复位开始）——这**不是**一次设备故障，按码聚合的脚本必须把它和 1
分开算，否则"采集断了"会被统计成"又崩了一次"。verdict 字段给 MEASUREMENT_BROKEN，
JSON 里 measurement.* 带三计数明细（payload_lines / boot_anchor_count / exact_hits /
loose_neighbours）。注意优先级：**零锚点但同时有 Forbidden 命中或自检故障记录时仍判 1**，
测量问题最多在旁边加一行 WARN——绝不能把真崩溃降级成"没数据"。
默认 Required 标记对应 STM32F4-Base 启动序列（见 App/app/app_main.c + App/task/net_task.c），
按测试用例覆盖，例如:
@@ -37,15 +42,19 @@
- 读取编码：先按 UTF-8，解码失败回退系统 locale 编码（旧版 Get-Content 行为）
- 控制台输出重配置为 UTF-8（errors=replace）：任何 Windows 控制台代码页
都只影响终端显示，不会导致本脚本崩溃
- 汇总行（2026-10-01 加，T-2）：纯 Required 子串匹配有个盲区——套件启动横幅
- 汇总行（2026-10-01 加）：纯 Required 子串匹配有个盲区——套件启动横幅
命中即判 PASS，**套件是否跑到汇总行、断言数是否为 0 完全不可见**（套件中途
挂死/复位、或 Phase 宏全关时会被误判为通过）。`--require-suite-summary`
要求日志中出现 `=== <名称>: N/M PASSED (failed=0) ===` 且 **N > 0**。
- 自检记录联合判定（S7，2026-10 实机窗口）：`--require-selftest-pass` 对 /log/selftest.log
的本地副本（定长 64B 记录，格式见 App/log/sys_log.h）判定。自检仅故障写盘（v1 不记
通过项）：**文件缺失 / 0 字节 = 无故障 → PASS**；存在任何一条记录 = 有故障 → FAIL
（退出码 1），并逐条打印时间戳 + 描述。抓取失败（设备不可达 / FTP 错误等）由调用方
（run_boot_test.py）先打 WARN，本地文件按缺失处理 → 按上述规则不判整体 FAIL。
- 自检记录联合判定（2026-10 实机窗口；判据 2026-10-22 改为"只看本次新增"）：
`--require-selftest-pass` 对 /log/selftest.log 的本地副本（定长 64B 记录，格式见
App/log/sys_log.h）判定。自检仅故障写盘（v1 不记通过项）：**文件缺失 / 0 字节 = 无故障
→ PASS**；存在记录 = FAIL（退出码 1），逐条打印时间戳 + 描述。
⚠ 该文件是 512 条环形**累计历史**，所以本函数收到的"有记录"必须由调用方先做差集：
run_boot_test.py 在烧录前取基线、启动后只把"基线之后新增"的记录写成临时副本交给本
函数（`--selftest-scope this-run`，默认）。**抓取失败/无数据源/无法证明无新增一律由
调用方判 FAIL**——旧实现把这些都当"无记录 → PASS"，是假绿（详见
docs/测试说明/流程与规范/自动化测试流程.md 的自检结果判定节）。
- 启动锚点计数（2026-10-10）：`--max-boot-count N`（run_boot_test.py 默认传 1）统计
`reset cause:` 锚点出现次数——**0 次** = 采集没从复位开始（标记全中也可能只是上一轮
的残留日志）；**>N 次** = 板子在采集窗口内自己复位过（IWDG 咬狗 / Fault 后
@@ -110,6 +119,106 @@ def _read_lines(path):
return raw.decode("utf-8", errors="replace").splitlines()
# --- whole-line exact matching (2026-10-26, task-36; absorbed from bench-runner scratch) ---
# Why this exists (measured, not theoretical): -Required is a SUBSTRING check, and the
# console-interleave defect kept the substring while destroying the line, e.g. the
# headless victim line "26-10-26 08:37:07][NAND_FTL] Initializing NAND FTL..." still
# contains the marker "Initializing NAND FTL" -> the old check called that boot a PASS.
# Any marker whose line can lose its head is therefore NOT verifiable by substring alone.
# --exact anchors the WHOLE payload (^ ... $) so one spliced byte breaks the match, and it
# also reports lines containing the pattern's longest literal run that do NOT match fully:
# that is the splicing signature and it must never stay silent. Length pinning is OPT-IN
# ("@@LEN=<n>"): byte lengths belong to one image, pinning them by default gives a false
# red on innocent commits (measured uiTask stack swing 4116..4188 on ONE image).
EXACT_LEN_SEP = "@@LEN="
_DAEMON_RX = re.compile(r"^\[RX\] \S+ (.*)$")
_RUNBT_RX = re.compile(r"^\[\+\d+ms\] (.*)$")
def _parse_exact(spec):
"""'REGEX@@LEN=42' -> (regex, 42); no suffix -> (regex, None)."""
if EXACT_LEN_SEP in spec:
pat, _, ln = spec.rpartition(EXACT_LEN_SEP)
return pat, int(ln.strip())
return spec, None
def _payload_of(line):
"""Drop the collector prefix so ^...$ applies to the firmware line itself.
Handles serial-assistant daemon lines ('[RX] <iso> ...'), run_boot_test boot logs
('[+Nms] ...') and bare payload lines. Archived evidence files may carry a leading
'#' provenance header; those are dropped unless include_comments is set (otherwise a
header that merely MENTIONS [ERR] would trip Forbidden / pollute exact counts).
"""
for rx in (_DAEMON_RX, _RUNBT_RX):
m = rx.match(line)
if m:
return m.group(1)
return line
def _longest_literal(pattern):
"""Longest run of non-metacharacters in a regex -> a greppable neighbour probe."""
parts = re.split(r"\\.|\\\[|\]|\(|\)|\{|\}|\||\*|\+|\?|\^|\$|\.|\[:", pattern)
parts = [x for x in parts if x and not x.startswith("\\")]
return max(parts, key=len) if parts else ""
def exact_check(payloads, spec, allow_residual=0, head_char=""):
"""(ok, detail, neighbours, residuals) for one --exact spec. See block note above."""
pat, want_len = _parse_exact(spec)
rx = re.compile("^" + pat + "$")
hits, residuals, consumed = [], [], set()
for idx, pl in enumerate(payloads):
if rx.match(pl):
hits.append(pl)
consumed.add(idx)
continue
if allow_residual > 0:
for k in range(1, allow_residual + 1):
if len(pl) > k and pl[k] == "[" and rx.match(pl[k:]):
hits.append(pl[k:])
residuals.append((k, pl[:k]))
consumed.add(idx)
break
key = _longest_literal(pat)
# a line counted (directly or after residual realignment) is never also a neighbour
neigh = [pl for i2, pl in enumerate(payloads) if key and key in pl and i2 not in consumed]
detail = "hits={} lens={} loose_neighbours={}".format(
len(hits), [len(h) for h in hits], len(neigh))
if residuals:
detail += " residual_head_bytes={}".format([(k, repr(v)) for k, v in residuals])
ok = len(hits) >= 1 and not neigh
if want_len is not None:
ok = ok and all(len(h) == want_len for h in hits)
detail += " want_len={}".format(want_len)
if head_char:
bad = [h for h in hits if not h.startswith(head_char)]
ok = ok and not bad
detail += " head_char={!r} bad={}".format(head_char, len(bad))
return ok, detail, neigh[:3], residuals[:3]
def pair_check(payloads, first_pat, then_pat):
"""Exactly one FIRST line with exactly one THEN line after it (cross-reset pairing).
Crash-dump legs need this: the fault line must pair with the NEXT boot's reset cause,
and a second following cause would mean an unlogged or repeated reset.
"""
frx, trx = re.compile(first_pat), re.compile(then_pat)
fi = [i for i, pl in enumerate(payloads) if frx.search(pl)]
ti = [i for i, pl in enumerate(payloads) if trx.search(pl)]
if len(fi) != 1:
return False, "first matches={} (want exactly 1), then matches={}".format(len(fi), len(ti))
after = [i for i in ti if i > fi[0]]
if len(after) != 1:
return False, "first at L{} but following THEN count={} at {} (want exactly 1)".format(
fi[0] + 1, len(after), [x + 1 for x in after])
return True, "first L{} -> only following THEN at L{} (gap {} line(s))".format(
fi[0] + 1, after[0] + 1, after[0] - fi[0])
def _reset_cause_of(line, marker):
"""从 `reset cause: software (NVIC_SystemReset) (CSR=0x14000000)` 取原因文本。"""
i = line.find(marker)
@@ -120,12 +229,38 @@ def _reset_cause_of(line, marker):
return tail[:j] if j > 0 else tail
# --- measurement-vs-device classification (task-32; bench-runner night rule) ---
# Three counters decide which kind of "nothing found" we are looking at, and they must not
# be conflated: an all-zero read is a BROKEN MEASUREMENT, not a healthy device.
# hits=0, loose_neighbours=0, boot anchors=0 -> measurement broke (wrong file, closed
# serial port, dead collector). Nothing was observed -> no verdict is meaningful.
# hits=0, loose_neighbours>=1 -> the line exists but is damaged (head
# eaten / bytes spliced in) -> that is a real device-side defect, --exact's purpose.
# hits=0, loose_neighbours=0, anchors>=1 -> the boot DID happen; the marker is
# genuinely absent -> allowed to read as a functional miss.
# Reported as its own exit code (2, the existing "measurement/environment did not happen"
# family) so aggregation by exit code never counts a dead collector as a device failure.
def classify_measurement(n_lines, boot_count, boot_check_on, exact_checked, hits, neighbours):
"""(broken, reason). Only judges when a boot anchor check was actually requested."""
if not boot_check_on:
return False, "anchor check off (max_boot_count=0) -> cannot classify"
if n_lines == 0:
return True, "zero payload lines (collector closed / log truncated / wrong file)"
if boot_count == 0:
return True, ("log readable (%d line(s)) but ZERO boot anchor -> capture did not "
"start at a reset" % n_lines)
if exact_checked and hits == 0 and neighbours == 0:
return False, "anchors present: exact markers genuinely absent (functional miss, not measurement)"
return False, "measurement ok (hits=%d neighbours=%d anchors=%d)" % (hits, neighbours, boot_count)
def verify(log_path, required=REQUIRED_DEFAULT, forbidden=FORBIDDEN_DEFAULT,
show_tail=40, out=print, suite_summary="",
selftest_pass=False, selftest_log="",
boot_marker=BOOT_MARKER_DEFAULT, max_boot_count=0,
expect_reset_cause="", require_order="", done_marker="",
max_boot_ms=0, as_json=False):
max_boot_ms=0, as_json=False, exact=None, pairs=None,
allow_residual=0, head_char="", include_comments=False):
"""标记校验核心（可被 run_boot_test.py 复用）。返回退出码 0/1/2。
suite_summary: ';' 分隔的套件名列表。非空时，要求日志中每个套件都出现
@@ -147,7 +282,8 @@ def verify(log_path, required=REQUIRED_DEFAULT, forbidden=FORBIDDEN_DEFAULT,
"""
res = {"log_path": str(log_path), "lines": 0, "bytes": 0, "required_missing": [],
"forbidden_hits": [], "boot": None, "suites_bad": [], "selftest": None,
"order_bad": [], "timing": None, "tail": [], "verdict": None, "exit": None}
"order_bad": [], "timing": None, "tail": [], "verdict": None, "exit": None,
"exact_bad": [], "exact_ok": [], "pair_bad": [], "pair_ok": []}
emit = out
def finish(code):
@@ -169,6 +305,10 @@ def verify(log_path, required=REQUIRED_DEFAULT, forbidden=FORBIDDEN_DEFAULT,
except OSError:
out("VERIFY_ERROR: cannot read log file: {}".format(log_path))
return finish(2)
if not include_comments:
# archived evidence files carry an ASCII provenance header; a header that merely
# MENTIONS [ERR] must not trip Forbidden (tool-level false-red guard, task-36)
lines = [l for l in lines if not l.lstrip().startswith("#")]
full = "\n".join(lines)
req_list = _split_list(required)
@@ -209,6 +349,37 @@ def verify(log_path, required=REQUIRED_DEFAULT, forbidden=FORBIDDEN_DEFAULT,
else:
out("[OK] forbidden pattern absent: {}".format(f))
# ---- whole-line exact checks + cross-reset pairing (task-36) ----
payloads = [_payload_of(l) for l in lines]
res["payload_lines"] = len(payloads)
exact_bad = []
for spec in (exact or []):
pat, _want = _parse_exact(spec)
ok_x, detail, neigh, residuals = exact_check(payloads, spec, allow_residual, head_char)
if ok_x:
out("[OK] exact line: {} {}".format(pat[:64], detail))
res["exact_ok"].append({"pattern": pat, "detail": detail})
else:
out("[FAIL] exact line: {} {}".format(pat[:64], detail))
for nb in neigh:
out(" inexact neighbour: {}".format(nb.strip()[:170]))
exact_bad.append(pat)
res["exact_bad"].append({"pattern": pat, "detail": detail,
"neighbours": [n.strip()[:170] for n in neigh]})
for k, v in residuals:
out("[NOTE] {} residual byte(s) before the line head, realigned and NOT a "
"failure: {}".format(k, repr(v)))
pair_bad = []
for f_pat, t_pat in (pairs or []):
ok_p, detail = pair_check(payloads, f_pat, t_pat)
if ok_p:
out("[OK] pair: {} -> {}".format(f_pat[:44], t_pat[:44]))
res["pair_ok"].append({"first": f_pat, "then": t_pat, "detail": detail})
else:
out("[FAIL] pair: {} -> {} {}".format(f_pat[:44], t_pat[:44], detail))
pair_bad.append({"first": f_pat, "then": t_pat, "detail": detail})
res["pair_bad"].append(detail)
# 启动锚点计数（2026-10-10）：抓"跑完但中途复位过"和"采集没从复位开始"
boot_issue = False
if max_boot_count > 0:
@@ -307,7 +478,7 @@ def verify(log_path, required=REQUIRED_DEFAULT, forbidden=FORBIDDEN_DEFAULT,
"(run_boot_test.py adds it; --raw-log turns it off)")
res["timing"] = timing
# 套件汇总行解析（T-2）：抓"没跑到汇总行 / 断言数为 0"的盲区
# 套件汇总行解析：抓"没跑到汇总行 / 断言数为 0"的盲区
bad_summary = []
if summary_list:
parsed = {}
@@ -378,15 +549,123 @@ def verify(log_path, required=REQUIRED_DEFAULT, forbidden=FORBIDDEN_DEFAULT,
for ln in lines[-show_tail:]:
out(ln)
# ---- measurement vs device (task-32) ----
n_exact_checked = len(exact or [])
n_exact_hits = sum(1 for e in (res.get("exact_ok") or []) if "hits=0" not in e["detail"])
n_neighbours = 0
for e in (res.get("exact_ok") or []) + (res.get("exact_bad") or []):
m = re.search(r"loose_neighbours=(\d+)", e.get("detail", ""))
if m:
n_neighbours += int(m.group(1))
b_on = max_boot_count > 0
b_cnt = (res.get("boot") or {}).get("count", 0)
broken, m_reason = classify_measurement(len(payloads), b_cnt, b_on,
n_exact_checked > 0, n_exact_hits, n_neighbours)
res["measurement"] = {"broken": broken, "reason": m_reason, "payload_lines": len(payloads),
"boot_anchor_count": b_cnt, "anchor_check_on": b_on,
"exact_checked": n_exact_checked, "exact_hits": n_exact_hits,
"loose_neighbours": n_neighbours}
# A broken capture must never mask real device-side bad news: if the log carries
# Forbidden hits or selftest fault records, that evidence stands and we report FAIL(1)
# with the measurement problem noted on top of it (worst outcome = a real crash quietly
# re-labelled as "no data").
if broken and (hits or selftest_fail):
out("")
out("[WARN] capture also looks incomplete: " + m_reason)
out(" but device-side bad news is present -> verdict stays FAIL, not MEASUREMENT-BROKEN")
broken = False
if broken:
out("")
out("[MEASUREMENT-BROKEN] " + m_reason)
out(" no verdict is meaningful here -- fix the measurement first (open the port,")
out(" assert the collector is alive, capture from a reset). Exit 2, NOT 1:")
out(" a dead collector must not be counted as one more device failure.")
return finish(2)
out("")
if (missing or hits or bad_summary or selftest_fail or boot_issue
or order_issue or timing_issue):
or order_issue or timing_issue or exact_bad or pair_bad):
out("VERDICT: FAIL")
return finish(1)
out("VERDICT: PASS")
return finish(0)
def selftest(out=print):
"""Prove the exact/pair machinery actually discriminates (exit 0 = all behaviours ok).
Written because a PASS that cannot fail is worthless: case 2/3 are the real captured
shapes of the 2026-10-26 console-interleave defect, and case 9 shows that the legacy
substring check calls the SAME defective line a PASS -- that is the blind spot --exact
exists to close.
"""
T = "[2026-10-26 08:00:00]"
prot_re = (r"\[\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\]\[PROT\] uncalibrated -> protection "
r"blocked \(UA/UN/IA VALID not all set\)")
nand_re = r"\[\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\]\[NAND_FTL\] Initializing NAND FTL\.\.\."
prot_ok = T + "[PROT] uncalibrated -> protection blocked (UA/UN/IA VALID not all set)"
prot_spliced = T + "[PROT] uncalibrated -> protection [blocked (UA/UN/IA VALI2D not all s0et)"
nand_ok = T + "[NAND_FTL] Initializing NAND FTL..."
nand_headless = "26-10-26 08:37:07][NAND_FTL] Initializing NAND FTL..."
mem_re = r"\[ERR\] MEMFAULT PC=\S+ LR=\S+ CFSR=\S+ HFSR=\S+"
mem_ok = "[ERR] MEMFAULT PC=0x08004a12 LR=0x08004a3f CFSR=0x00008200 HFSR=0x40000000"
rc_ok = T + "[APP] reset cause: software (NVIC_SystemReset) (CSR=0x14000000)"
cases = []
def chk(name, got, want):
cases.append((name, got == want, "got={!r} want={!r}".format(got, want)))
chk("clean exact", exact_check([prot_ok], prot_re)[0], True)
ok_s, _d_s, neigh_s, _r_s = exact_check([prot_spliced], prot_re)
chk("spliced line rejected", ok_s, False)
chk("spliced line fails even with broken probe key", len(neigh_s), 0)
ok_n, _d_n, neigh_n, _r_n = exact_check([nand_headless], nand_re)
chk("headless line rejected", ok_n, False)
chk("headless line reported as neighbour", len(neigh_n) >= 1, True)
chk("residual 1 rejected when not allowed", exact_check(["#" + nand_ok], nand_re)[0], False)
ok_r, det_r, _n_r, res_r = exact_check(["#" + nand_ok], nand_re, allow_residual=1)
chk("residual 1 accepted when allowed", ok_r and len(res_r) == 1, True)
chk("residual 2 still rejected", exact_check(["##" + nand_ok], nand_re, allow_residual=1)[0], False)
chk("head_char enforced", exact_check([nand_ok], nand_re, 0, "[")[0], True)
chk("head_char catches wrong head", exact_check([nand_headless], r"26-10-26.*NAND_FTL.*", 0, "[")[0], False)
chk("len pin ok", exact_check([nand_ok], nand_re + EXACT_LEN_SEP + str(len(nand_ok)))[0], True)
chk("len pin mismatch fails", exact_check([nand_ok], nand_re + EXACT_LEN_SEP + "9")[0], False)
chk("pair good", pair_check([mem_ok, rc_ok], "MEMFAULT", "reset cause:")[0], True)
chk("pair two following causes fails",
pair_check([mem_ok, rc_ok, rc_ok], "MEMFAULT", "reset cause:")[0], False)
chk("pair wrong order fails",
pair_check([rc_ok, mem_ok], "MEMFAULT", "reset cause:")[0], False)
# blind spot: legacy substring would PASS on this defective line
full = "\n".join([prot_ok, nand_headless])
legacy_present = "Initializing NAND FTL" in full # what --required sees
exact_ok_here = exact_check([prot_ok, nand_headless], nand_re)[0]
chk("blind spot proven: legacy substring PASSES where --exact FAILS",
legacy_present and not exact_ok_here, True)
# measurement-vs-device classification (task-32): the three-counter rule IS this function,
# so it is pinned here -- an all-zero read must not be reportable as a healthy device.
chk("measure: good capture -> not broken", classify_measurement(137, 1, True, True, 1, 0)[0], False)
chk("measure: zero payload lines -> broken", classify_measurement(0, 0, True, True, 0, 0)[0], True)
chk("measure: readable but no boot anchor -> broken",
classify_measurement(1, 0, True, True, 0, 0)[0], True)
chk("measure: anchor check off -> abstain (non-boot logs stay usable)",
classify_measurement(0, 0, False, True, 0, 0)[0], False)
chk("measure: damaged lines are device-side, not 'no data'",
classify_measurement(120, 1, True, True, 0, 3)[0], False)
chk("measure: anchors present + no neighbour = functional miss",
classify_measurement(120, 1, True, True, 0, 0)[0], False)
bad = 0
for name, ok, detail in cases:
out("{} {}".format("[OK] " if ok else "[FAIL]", name))
if not ok:
out(" {}".format(detail))
bad += 1
out("SELFTEST: {} case(s), {} failure(s) -> {}".format(
len(cases), bad, "PASS" if bad == 0 else "FAIL"))
return 0 if bad == 0 else 1
def main(argv=None):
# 控制台输出固定 UTF-8：Windows 代码页（GBK/UTF-8 终端）均不会让本脚本崩溃
for stream in (sys.stdout, sys.stderr):
@@ -403,7 +682,7 @@ def main(argv=None):
help="forbidden patterns, ';' separated (case-insensitive)")
ap.add_argument("--require-suite-summary", default="",
help="suite names that MUST appear as '=== <name>: N/M PASSED (failed=0) ===' "
"with N>0, ';' separated (T-2). Empty = off")
"with N>0, ';' separated. Empty = off")
ap.add_argument("--show-tail-lines", type=int, default=40,
help="show last N log lines (0 = off)")
ap.add_argument("--require-selftest-pass", action="store_true",
@@ -427,10 +706,36 @@ def main(argv=None):
ap.add_argument("--max-boot-ms", type=int, default=0,
help="fail if time from first line to --done-marker exceeds N ms "
"(needs '[+Nms]' line prefix; 0 = off)")
ap.add_argument("--exact", action="append", default=[],
help="repeatable regex that must match a WHOLE firmware line "
"(collector prefix stripped, anchored ^...$); a spliced byte or a "
"missing line head fails. Optional suffix '@@LEN=<n>' pins the byte "
"length -- opt-in only, lengths belong to one image. Use --exact "
"instead of --required for any marker whose line can lose its head.")
ap.add_argument("--allow-residual", type=int, default=0,
help="accept up to N stray bytes before the line head on an --exact hit "
"(crash-dump legs: 1 shift-register leftover is known; recorded, "
"not a failure). 0 = strict (default)")
ap.add_argument("--head-char", default="",
help="every --exact hit must start with this char right after the "
"optional residual prefix (crash-dump legs: '[')")
ap.add_argument("--pair", action="append", nargs=2, metavar=("FIRST", "THEN"), default=[],
help="repeatable pair: exactly one FIRST line, and exactly one THEN line "
"after it (cross-reset pairing, e.g. 'MEMFAULT' 'reset cause:')")
ap.add_argument("--include-comments", action="store_true",
help="do NOT skip '#' lines (archived evidence files carry an ASCII "
"provenance header; skipping it is the default so a header that "
"merely mentions [ERR] cannot trip --forbidden)")
ap.add_argument("--selftest", action="store_true",
help="run the built-in discrimination cases and exit (0 = all behave "
"as specified); needs no log file and no hardware")
ap.add_argument("--json", action="store_true",
help="emit one JSON object instead of the text verdict (exit code unchanged)")
args = ap.parse_args(argv)
if args.selftest:
return selftest()
return verify(args.log_path, args.required, args.forbidden,
args.show_tail_lines, suite_summary=args.require_suite_summary,
selftest_pass=args.require_selftest_pass,
@@ -441,7 +746,10 @@ def main(argv=None):
require_order=args.require_order,
done_marker=args.done_marker,
max_boot_ms=args.max_boot_ms,
as_json=args.json)
as_json=args.json,
exact=args.exact, pairs=args.pair,
allow_residual=args.allow_residual, head_char=args.head_char,
include_comments=args.include_comments)
if __name__ == "__main__":
.dsh/skills/stale-doc-count-sweep/SKILL.md
+73
View File
@@ -0,0 +1,73 @@
---
name: stale-doc-count-sweep
description: 全仓陈旧计数同步 playbook——某个事实数（黄金参考页数/张数、菜单树叶数与已绑叶数、字库字数与字形数、提交钩子数等）变了之后：每个数先剔伪命中再双源互证定真值 → 全形态全命中面扫描（含 .pre-commit 钩子显示名与 .dsh/skills 正文）→ 逐条分类（当前态改 / 历史行冻结（只有保留变更记录的 5 篇真台账与 scripts/archive/ 归档） / 同数不同义不动 / 带日期戳的测量只加「当时」/ 数字对但口径描述错另起一笔）→ 每处先读现文再字面替换并断言命中数 → 全文通读核对各小节 → 提交后再按全部旧形态复扫归零 → 跑门禁分笔提交。
whenToUse: 某个计数/数字变了要跨 md/yaml/py/txt 同步、用户说「同步一下 / 全仓改一遍 / 这个页数（张数、叶数、字形数、钩子数）不对」、怀疑某个数是伪命中或口径错了（含 notdef 吗、含 ASCII 吗、是张数还是页数）、发现文档数字与实测不符、或同一份文档两节数字/顺序对不上要先核口径时。
---
# 陈旧计数全仓同步
适用：**一个事实数变了**（黄金参考 27→40→47→53→60→66、已绑叶数 22→28→30、主机单测套数 28→33→41→44、无专属钩子套数 18→19→22、字库 185/280→218/313→224/319、菜单节点行数 42→43、钩子 51→52→51→52…），仓库里多处引用它的当前态表述要跟着变，而历史记录、同数异义、带日期戳的测量**不能**跟着变。
本仓已跑过四轮，照序列复跑、别临场重新发明分类：`b24b2b5f`（27→40，13 文件）、`31ca4a1f`（40→47，11 文件）、UI 补齐批（`94b0d790` 落地 → `cbb4fdb8` 产品需求同步 → `11d60057` 架构总览补漏 → `6daa01ae` 字体**口径**更正）、钩子一增一减（`1668842d`，52→51）、**第五轮 2026-10-29 录波落地**（套数 41→44、无专属钩子 19→22、黄金 60→66、菜单 42→43 节点 / 33→34 叶、已绑 28→30、字库 218/313→224/319；改动面含 `.pre-commit-config.yaml` 显示名与 `docs/门禁说明/README.md` 成对、三个 skill 正文）。
## 各计数的权威口径速查（本仓实测值，动手前先对表）
| 计数 | 真值来源（**至少两处互证**） | 已知伪命中 / 换算 |
|---|---|---|
| 内容页黄金参考**张数** | `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 |
| 字库**唯一字数** | `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 |
| 菜单**节点数 / 叶子数** | `ui_menu_tree.txt` 头部规则：缩进即层级（每级 2 空格）、`#` 开头为注释、空行忽略；叶子 = **不存在更深缩进后继行**的行 | 43 是节点行数、34 才是叶子（2026-10-29 现值；42 / 33 是此前时点）；`未绑 = 待做 + 不做` 要与分类表逐项闭合 |
## Steps
1. 实测真值：先剔伪命中，再双源互证
2. 全形态 + 全命中面扫描
3. 逐条分类，五类各走各的路
4. 每处先读现文，再逐条字面替换并断言命中数
5. 一笔只装一类事
6. 被改文件全文通读，核对其余小节
7. 提交后再复扫一遍
8. 跑门禁、分笔提交
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [steps.md](reference/steps.md)。动手前先读那篇。
## Pitfalls
- 把伪命中计进真值
- 字形数没剔 notdef
- 数字对但口径描述错
- 权威脚本乱码就臆读或退回抄文档
- 钩子数用 grep 声明行
- 张数与页数互相冒充
- 只扫 docs/
- 提交完就收工
- 去已删掉变更记录的文档里「补一行流水」
- 历史行被当陈旧值改掉
- 照抄用户给的数
- 把节点行当叶子数
- 整文件正则批处理
- 反引号截断
- 只改记得的那节
- 误报跟着改
- 带日期戳的测量臆改新数
- 用截断的 grep 输出判定
- 新写文本撞编号门禁
> 本节全文（逐字搬移、未改写，含命令与实测数字）→ [pitfalls.md](reference/pitfalls.md)。动手前先读那篇。
## Verification
提交前逐条打勾；回报时**逐处列文件 + 命中数断言**，不要笼统说「已全部更新」。
- [ ] 每个数都写了**两个独立来源**且数值一致（`ref/shot_*.bin` 实数 ＝ `PAGES` 条目数；`UI_PAGE_MAP_COUNT` ＝ 剔伪命中后的 `#page=` 计数），并在结论里贴出该数字与伪命中取舍理由
- [ ] 字形数说明**是否剔除 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`，逐条在改动清单里出现
- [ ] 被改文件已全文通读，同文档各小节与配套 README/清单的顺序、计数、完成状态一致；口径闭合（如 `未绑 = 待做 + 不做`）
- [ ] 变更记录：**保留的 5 篇真台账**（清单 → `docs/文档规范.md` §5.1）历史行原文未动；其余文档本轮**零新增流水行**（当前态改完即止）；钩子一增一减这类过程细节写进提交正文，不写进文档
- [ ] **提交后**又按全部旧形态复扫一次，当前态残留 = **0**，每条剩余命中都能归类（历史行 / 误报 / 已加「当时」）；发现的漏网当前态已单独补一笔
- [ ] `check_doc_links.py --all --sections-strict` 打印「文档路径检查通过（N 个文档）」；`ci_local.py` / `pre-commit` 全绿（RC=0、`failed=0`）；BOM 与原文件一致、无 `EF BF BD`
- [ ] 分笔提交完成，回报 commit 号 + 每笔改了哪些文件 + 没动的那几类及理由
.dsh/skills/stale-doc-count-sweep/reference/pitfalls.md
+24
View File
@@ -0,0 +1,24 @@
# Pitfalls（自 SKILL.md 外置）
> 本文由 stale-doc-count-sweep 的 SKILL.md「Pitfalls」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
- **把伪命中计进真值**：`grep '#page='` 的首条是菜单文件头部注释里的示例行，29 里含它；真值是注册表 `UI_PAGE_MAP_COUNT` 的 28。任何「数出现次数」式计数，先打印全部命中逐条看，剔注释行/模板行/示例行。
- **字形数没剔 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 三数同源。
- **张数与页数互相冒充**：一个 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 本窗最后才改）。
- **提交完就收工**：第 7 步的提交后复扫才是把漏网当前态（架构总览 §3）揪出来的那一步；漏了它，仓库里就留下一行「当前态写旧数」直到别人再扫。
- **去已删掉变更记录的文档里「补一行流水」**：2026-10-29 起全仓只剩 **5 篇**真台账保留变更记录表（清单 → `docs/文档规范.md` §5.1），外加 `scripts/archive/` 归档；其余文档**没有这一节**。计数同步**只改当前态**、过程交给 `git log`，别再到别的文档里找或加变更记录行。真要往那 5 篇的台账里加行，历史坑照旧：它们的表按日期**升序** → 新行**追加为末行**，插表顶会把首行「初版」挤成第二行。
- **历史行被当陈旧值改掉**：「47 → 53 页」是当天事实，改了就是伪造历史；正确动作是**只改当前态那几处**、历史行一个字不动（保留变更记录的 5 篇真台账要写台账也只追加、不回改）。**历史行被写坏**时按无反引号兜底写法整行重写，别用同样写法再改一遍。
- **照抄用户给的数**：用户说「从 40 扩到 47」也要自己数 `ref/*.bin`；数出来不一定是 47。
- **把节点行当叶子数**：42 是 `ui_menu_tree.txt` 的节点行数、33 才是叶子；不读文件头规则就数错（实测把错数写进两份文档，下一轮才自查出来）。
- **整文件正则批处理**：第一次尝试的正则没编译过、整批零落地。改法 = 逐条字面替换 + 每处 `assert count == expect`。
- **反引号截断**：脚本里含 `ui-golden`、`#page=` 这类反引号时，经 TS 模板字符串/内嵌 heredoc 传递会被截断，表现为「整批零落地」或「历史行写坏」。落成脚本文件再执行，或用 `chr(96)` / `String.fromCharCode(96)` 拼。
- **只改记得的那节**：上一笔只改 §2 与开篇、漏改 §1，用户当场问出「§1 说 16 叶、§2 说剩 3 项，自相矛盾」。改完必须全文通读同一文档所有小节。
- **误报跟着改**：「< 40KB」是绘制缓冲红线，与页数无关。
- **带日期戳的测量臆改新数**：「2026-10-26 实跑 …覆盖 40 页」改成 47 就是把历史测量冒充现值；只加「当时」。
- **用截断的 grep 输出判定**：`cut -c` 截掉的后半句常含日期戳/口径，据此分类必错。
- **新写文本别再造编号**：两道编号门禁都已退役（全库八项校验 2026-10-28、只查新增行 2026-10-29，脚本与白名单在 `scripts/archive/id_gate/`），**撞号不再有机器报警**，只剩规范与评审——所以这批文本的形态自查要自己做（`docs/编号规范.md` §1 三句；要机器帮忙就手工跑 `scripts/archive/id_gate/check_ids_new.py --worktree`）。
.dsh/skills/stale-doc-count-sweep/reference/steps.md
+88
View File
@@ -0,0 +1,88 @@
# Steps（自 SKILL.md 外置）
> 本文由 stale-doc-count-sweep 的 SKILL.md「Steps」一节逐字外置而来（渐进展开：主文件只留索引与指针）。步骤号沿用原文，未重编。
1. **实测真值：先剔伪命中，再双源互证**（不抄用户口述、不抄另一处文档）。逐数走上面那张表；两个来源对不上时**先找分歧根因**（把全部命中逐条打印出来看），不要取第一个、不要取平均，并在结论里写明分歧与取舍（实测：菜单 `#page=` 计数 29 对 注册表 28，根因是头部注释示例行）。
```bash
cd "<repo>"
ls simulator/tests/ref/shot_*.bin | wc -l # 张数（判据 = 入库实数）
awk '/^PAGES = \[/,/^\]/' simulator/tests/check_content_pages.py | grep -cE '^ *\("' # 页数（第二个来源，两者必须一致）
grep -n '#page=' ui_menu_tree.txt | head -3 # 先看首条是不是注释示例行，再定叶数
grep -rn 'UI_PAGE_MAP_COUNT' Drivers/BSP/UI/ui_page_registry.h # 已绑叶数（生成物）
grep -c '\.bitmap_index' Drivers/BSP/UI/ui_font_cn_12.c # 314 = 含 notdef；字形 = 该数 - 1
& '.venv\Scripts\python.exe' -c "import yaml;d=yaml.safe_load(open('.pre-commit-config.yaml',encoding='utf-8'));print(sum(len(r['hooks']) for r in d['repos']))" # 钩子数口径
```
⚠ **权威脚本输出乱码时**（`check_font_charset.py` 在 GBK 代码页下整行打印成 U+FFFD 替换字符串 + `: PASS`，数字全读不出来），**改为直接数源文件里符号出现次数**（`.bitmap_index` / `.range_start` / 码点唯一化）——不许臆读乱码，也不许因此退回去抄文档里的旧数。
2. **全形态 + 全命中面扫描**。一个数一次列出它全部历史形态，别只扫当前旧值：本轮 = `122/217`、`179/274`、`185/280`、`47 → 53`、`53 → 60`、`PAGES = 53`、`UI_PAGE_MAP_COUNT = 22`、`已绑 22 叶`、`未绑 11`、`内容页 53 页`。
```bash
grep -rn --include=*.md --include=*.py --include=*.yaml --include=*.txt --include=*.c --include=*.h \
-E '122 唯一字|217 字形|179 汉字|274 字形|185 唯一字|280 字形|47 → 53|53 → 60|内容页 53|PAGES = 53|UI_PAGE_MAP_COUNT = 22|已绑 22|未绑 11' . \
| 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` 同样是引用面）。
先列出 `文件:行:全文`，**判定前必须看整行**——`cut -c1-120` 会截掉后半句（那里常写着日期戳或口径）。
3. **逐条分类，五类各走各的路**（本 playbook 的核心，别用一条规则套全部命中）：
| 类别 | 判定 | 动作 |
|---|---|---|
| 当前态陈述 | 描述「现在是多少」 | 改成实测真值 |
| 变更记录历史行 | 形如「47 → 53 页」的当日事实 | **原样冻结不回改**——但这条**只适用于保留变更记录的 5 篇真台账**（台账 / 被别处当唯一证据出处的文档，清单 → `docs/文档规范.md` §5.1）与 `scripts/archive/` 归档；其余文档没有变更记录节，**不再追加任何流水行**，数字同步只改**当前态** |
| 同数不同义 | `最坏路径 < 40KB` 这类内存/绘制缓冲红线 | **不动**，并在结论里写明「为什么不动」 |
| 带日期戳的测量 | 「2026-10-26 实跑 …覆盖当时 40 页中的」 | **不臆改新数**，只补「当时」两字锁口径；新数留待下次实跑回填 |
| 数字对但**口径描述错** | 数没错、句子把口径讲错了（实测：写「218 字（含 ASCII/符号，共 313 字形）」，而 `ui_cn_chars.txt` 的 218 个码点**全为非 ASCII**） | **另起一笔只改口径的提交**（`6daa01ae`），不与数字同步混笔；这类命中在任何数字 diff 里都看不见，只能把口径句逐句读一遍 |
拿不准就回到第 2 步把整行打印出来再判；判错历史行 = 把当天事实改成假账。
4. **每处先读现文，再逐条字面替换并断言命中数**（弃用整文件正则批处理）。本窗两度返工都是没先读现文：step 45 断言 `HIT 0` 抛错（目标串与现文不一致），step 44 是脚本语法错。脚本写成临时文件再跑（内嵌 heredoc/模板字符串里的反引号会截断整脚本），按**字节**替换以保 BOM 与行尾不动：
```python
import pathlib, sys
sys.stdout.reconfigure(encoding='utf-8', errors='replace')
JOBS = [ # (文件, old, new, 期望命中数)
('AGENTS.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),
]
for path, old, new, expect in JOBS:
p = pathlib.Path(path); raw = p.read_bytes()
o, n = old.encode('utf-8'), new.encode('utf-8')
got = raw.count(o)
assert got == expect, f'{path}: 命中 {got}，期望 {expect}（未写入）'
assert o != n, f'{path}: old 与 new 相同'
p.write_bytes(raw.replace(o, n))
print(f'OK {path}: {old} -> {new} x{got}')
```
每行打印 `old -> new xN`，收口时这串输出就是「改了哪几处」的账。脚本报错/没编译过，**先 `git diff --stat` 确认零写入**再换写法（不要在半落地状态上叠改）。
- **反引号**：TS 侧先用可见占位符（如 `~TB~`）写文本，落盘前再还原成真反引号 —— `const BT = String.fromCharCode(96); const q = s => s.split(TOKEN).join(BT)`（本窗实测：直接把带反引号的串塞进模板字符串/heredoc，整批零落地或把变更记录行写坏）。用 `tools.edit` 批量改时同样先 `await tools.read` 现文再传 `old_string`；批量里若某条 `old_string` 与 `new_string` 相同会报 `must differ` —— **只有该条作废、其余已落盘**，别整批重跑。
- **历史行被写坏**（反引号及紧随其后的字符经工具传递被吞 → 变更记录行只剩半行、尾部出现 `??` 这类残迹）：立刻按**无反引号兜底写法整行重写**——裸词 `accident / oper / alarm / start / yk`、页面绑定写成不带反引号的 `#page=`——而不是拿同样带反引号的串再改一遍（实测连返工三次：step 81→82→83→85）。
5. **一笔只装一类事**。数字同步一笔（`cbb4fdb8`：11 处 + 变更记录一行）；口径更正另起一笔（`6daa01ae`）；提交后复扫逮到的漏网当前态再补独立一笔（`11d60057`）。钩子一增一减写成一个当日行的两个阶段（51 → 52 加 `id-check-new`、随即 52 → 51 摘 `id-check`），别写两行互相打脸。提交说明如实写（「先认一笔自己的错：上一笔的未绑 21 叶是探针错」），别把口径修正包装成「补充说明」。
6. **被改文件全文通读，核对其余小节**——不是只看 diff。同一文档内互相引用的小节必须一致（本窗产品需求：§2.4 立项未排、§5.14 FR-SOE-3、§8.2 绑定现状、§8.3 已绑分页表、§9.1 差距表、§9.2 顺序表六处同时引用这四个数；`docs/任务规划/README.md` §1 当前执行表 vs §2 全项目顺序表）。若发现上一笔自己写进文档的数**口径就错了**，明确认错并改正，同时把**可复核的重算方法**写进文档（「按缩进判叶子：有更深缩进后继者即非叶子」），防止再错。
7. **提交后再复扫一遍**（收尾硬步骤，不许省，也不许只在提交前扫）。按第 2 步的**全部**旧形态整仓再扫一次，逐条分类为 当前态 / 历史行 / 同数不同义：本窗 `cbb4fdb8` 提交后复扫得 14 条命中，12 条以上都在变更记录历史行（`47 → 53`、`53 → 60`、`122/217` 冻结），**唯一残留的当前态命中**是 `docs/架构设计/项目架构总览.md` §3「界面层」那行 → 单独补一笔 `11d60057`。说不出归属的就是漏改。
```bash
grep -rn -E '22 叶|未绑 11|11 叶|53 页|122 唯一字|217 字形|185 唯一字|280 字形|内容页 53|PAGES = 53|UI_PAGE_MAP_COUNT = 22' \
. | grep -v -E '^\./(ci-artifacts|\.mnemon|\.dsh/runs)/'
```
8. **跑门禁、分笔提交**（`git commit` 属 Ask first，须用户明确指示后再做）：
```bash
& '.venv\Scripts\python.exe' scripts/check_doc_links.py --all --sections-strict # 期望「文档路径检查通过（N 个文档）」
& '\.venv\Scripts\python.exe' scripts/archive/id_gate/check_ids_new.py --range A..B # 编号形态普查（两道门禁 2026-10-28 / 2026-10-29 都已退役，不再是提交钩子）
& '.venv\Scripts\python.exe' scripts/ci_local.py # 或 pre-commit run --files <被改文件>
```
PowerShell 形态把 `./.venv/Scripts/python.exe` 换成 `& '.venv\Scripts\python.exe'`。提交信息一律 `git commit -F <UTF-8 无 BOM 文件>`，别用 `-m`（中文长标题易超 100 字符、终端代码页会转码）；标题 ≤100、**正文每行 ≤80**（实测把正文压到 66/78 字符才过 gitlint）。
.dsh/skills/stlink-flash/SKILL.md
+1 -1
View File
@@ -47,7 +47,7 @@ whenToUse: 需要向 STM32 目标烧录 .hex/.bin、只复位重启目标、校
被拒，本 skill 会打印 `RESET_NOTE` 并**自动降级**为这条系统复位（仍按降级结果给 rc）。
- 探针在位先 `list`；`Programming Complete` 但行为像旧固件 → 先怀疑缺 `-Rst -Run`，
再怀疑 hex 没重编（对比 hex 时间戳）。
- 完整复位语义/故障排查（本仓库）：`docs/测试说明/ST-LINK_CLI_复位使用说明.md`。
- 完整复位语义/故障排查（本仓库）：`docs/测试说明/测试工具/ST-LINK_CLI_复位使用说明.md`。
## 与其它 skill 的衔接
.dsh/skills/task-worktree/SKILL.md
+148 -98
View File
@@ -1,123 +1,173 @@
---
name: task-worktree
description: 多任务并行开发的空间管理（git worktree 生命周期）：new 开一棵工作树 + 任务分支、目录联接共享 .venv 与模拟器 SDK、build/bench 两类独占锁、done 预演合并回主干并审计并集残留。规格见 docs/环境与部署/并行任务工作树方案.md。
whenToUse: 要同时推进多个任务、担心同分支同文档互相冲突；要为新任务开一个隔离空间；要把任务合并回主干；或遇到两个任务抢 COM6 / UV4、"改了文档被覆盖"、并集合并残留时。
description: >-
并行开发的空间管理（git worktree 生命周期；`@task` 只是文档别名不是可执行命令，DSH 会话显式调用 `/task-worktree`）：开任务树与分支、联接共享 `.venv` 与模拟器 SDK、build/bench 独占锁、并发上限与腾位（A）、放不掉的锁（B）、`done` 是合并点不是查看器与补绿链（C）、主树被别的会话弄脏时的手工合并（C2）、门禁指标异常的净室归因（D）、回收非登记树与悬挂台账（E）、与 DSH worktree 插件共存及联接分级（F）、树内跑门禁与消息禁词（G）、树内自查与合并后补绿命令化（`precheck` / `postmerge`）。规格 = docs/环境与部署/并行任务工作树方案.md；深规程全文在 reference/。
whenToUse: >-
要为新任务开隔离空间、同时推进多个任务、把任务合回主干或回收工作树；或撞到 `new` 报「已有 8 个活跃任务（上限 8）」、`lock release` 报「任务 X 不存在（缺台账）」、`done` 报「门禁未全绿」或「主工作树不干净」而那份脏改动是别的会话/插件留的、两个任务抢 COM6 或 UV4、并集合并残留；或在任务树里跑门禁写输出报 ENOENT、`--all` 的问题全在 `simulator/SDL2` 联接下；或门禁指标异常增长查不出哪个文件造成；或要回收 `list` 台账看不到的树、清 branch/path 都已不存在的悬挂台账；或要确认插件树里 `.venv` 与 `simulator/SDL2` 哪个必须补；或要改并行上限这个数字并同步全仓口径。
---
# task-worktree — 多任务并行开发空间（`@task` 仅为文档别名；DSH 显式调用 `/task-worktree`；可执行形态见「固定命令」）
# task-worktree — 多任务并行开发空间（短命令 `@task`）
- **执行体** = `.dsh/skills/task-worktree/scripts/task_worktree.py`（纯标准库；拷整个 skill 目录即可换项目用）。
- **深规程全文在 reference/ 下：做 C2 / D / E / F / G 任何一条之前先把对应那篇读完**——本文只留判得出来「要不要读」的判据。
- 为什么这么拆：本文件受 dsh-mnemon 写侧上限 **65536 字节**（`skill-size` 钩子 49152 告警；实测 72,601 字节的技能照常可读可提交，只是自进化每次「生成草案」被拒、永久卡在「生成中」）→ **新增深规程进 reference/，本文只加判据**。瘦身前 frontmatter 原文 → [frontmatter-history.md](reference/frontmatter-history.md)。
**执行体 = 本 skill 自带脚本** `.dsh/skills/task-worktree/scripts/task_worktree.py`
（纯标准库，任意 python3；拷整个 skill 目录到别的项目即可用）。
## 症状 → 去哪一节
```powershell
# cwd = 仓库根（或任意子目录）
& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" <子命令> [参数]
```
退出码：`0`=成功 / `1`=操作失败 / `2`=前置或环境错误 / `3`=用法。
| 现场 / 目标 | 去 |
|---|---|
| 开新树 / 看全景 / 追平主干 / 放弃任务 | 固定命令、典型流程 |
| `new` 报「已有 8 个活跃任务（上限 8）」 | **A** |
| `lock release` 报「任务 X 不存在（缺台账）」，锁照旧挂着 | **B** |
| `done` 做了什么、红了怎么补绿、能不能反悔、怎么算「真完成」 | **C** |
| `done` 报「主工作树不干净」，而那份脏是别的会话/插件留的 | **C2** → [merge-dirty-main-tree.md](reference/merge-dirty-main-tree.md) |
| 门禁指标异常增长要逐文件归因（主树全程只读） | **D** → [clean-room-measure.md](reference/clean-room-measure.md) |
| `list` 台账里没有的树要回收 / detached / 有在飞内容 / 悬挂台账 | **E** → [reclaim-unregistered.md](reference/reclaim-unregistered.md) |
| 插件树缺联接、锁归属 `pw:<name>`、「有插件为何还自持生命周期」 | **F** → [dsh-plugin-bridge.md](reference/dsh-plugin-bridge.md) |
| 树内写门禁输出 ENOENT、`--all` 假红、写提交/合并信息、字节体检 | **G** → [gates-in-tree.md](reference/gates-in-tree.md) |
| 收工前树内自查、或合并后体积凭证/台账红了想一条命令补绿 | `precheck` / `postmerge`（固定命令表 + C 节第 5~6 步） |
| 退出码读到 0 其实是 2、`tail` 之后误判「有冲突」 | 读输出 |
| 谁不许跑 `done`/`abort`、清场前必做什么、任务期哪些文件不许改 | 铁律 1–9 |
| 收工前最后一遍自查（各节该留什么证据）／全部实测坑 | [verification.md](reference/verification.md) ／ [pitfalls.md](reference/pitfalls.md) |
## 固定命令
```bash
PY=".venv/Scripts/python.exe"; TW=".dsh/skills/task-worktree/scripts/task_worktree.py"
"$PY" "$TW" <子命令> [参数] # PowerShell：& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" <子命令>（cwd = 仓库根或任意子目录）
```
| 命令 | 作用 |
|---|---|
| `new <ID> <slug>` | 建分支 `task/<ID>-<slug>` + 工作树 + 共享联接 + 台账；打印新空间路径 |
| `list` | 所有任务一览：分支 / 落后领先 / 脏文件数 / 台架状态 + 两个锁的归属 |
| `status <ID>` | 单任务详情（未提交清单、相对基线漂移、台架记录、已建联接） |
| `sync <ID>` | 在任务工作树里 `rebase` 追平主干，把冲突控制在任务分支上 |
| `lock acquire\|release\|status <build\|bench>` | 独占资源锁 |
| `new <ID> <slug>` | 建分支 `task/<ID>-<slug>` + 工作树 + 共享联接 + 台账，打印新空间路径 |
| `list` | 分支 / 落后领先 / 脏文件数 / 台架状态 + 两把锁归属。**只遍历台账** → 非登记树看不见（E 节） |
| `status <ID>` | 未提交清单、相对基线漂移、台架记录、已建联接 |
| `sync <ID>` | 在任务树里 `rebase` 追平主干，把冲突留在任务分支上 |
| `lock acquire|release|status <build\|bench>` | 独占资源锁（→ 铁律 3、B 节） |
| `plugin list|adopt|unadopt [插件树名]` | 插件桥：看清单 / 补共享联接 / 摘联接（**不删树**）→ F 节 |
| `done <ID>` | 预演 → 合入主干 → 并集残留审计 → 重生成产物 → 门禁 → 清场 |
| `abort <ID>` | 放弃任务（工作树 + 分支一起删，**永久丢弃**） |
| `abort <ID>` | 工作树 + 分支一起删，**永久丢弃** |
| `precheck` | 树内自查（**只读**）：BOM 漂移 / CR / U+FFFD + docs 逐档门禁 + `--msgfile --ban` 消息检查；顺手补 `ci-artifacts/`（G 节机械项） |
| `postmerge` | 主树合并后补绿：体积凭证**自动诊断**（新鲜跳过；红→先短链 `--update`，只读复检真漂了才升全链）+ `check_doc_links --all` + 列待提交文件，**不代提交** |
`new` 常用开关：`--base <分支>`（默认 `v2-on-ui`）· `--needs-bench`（无台架 PASS 则 `done` 拒合）·
`--lean`（跳过 Git LFS smudge）· `--no-bootstrap`（不建联接）。
`done` 常用开关：`--dry-run`（只预演，零改动）· `--skip-build` · `--skip-gates` · `--force`。
**环境变量**（高级）：`DTU_WT_ROOT`（任务容器位置，默认仓库同级 `_wt/`）·
`DTU_TASK_BASE`（默认基线分支，默认 `v2-on-ui`）·
`DTU_INTEGRATION_WORKTREE`（集成点，默认主工作树——用于隔离演练/测试）。
- **退出码** `0` 成功 / `1` 操作失败 / `2` 前置或环境错误 / `3` 用法——**只有不接管道才读得到**（→ 读输出）。
- `new`：`--base`（默认 `v2-on-ui`）· `--needs-bench`（无台架 PASS 则 `done` 拒合）· `--lean`（跳 LFS smudge，只省磁盘不省时间）· `--no-bootstrap`（不建联接）· `--force`（**只跳过并发上限检查**，不解决谁让位 → A）
- `done`：`--dry-run` · `--skip-build` · `--skip-gates` · `--force`。⚠ `--dry-run` **只保护预演段、不保护清场段**（实测：对已合入的分支它照样摘联接、删分支、清台账；且它的前置也要抢 `build` 锁）→ 用完复验 `git worktree list`，细节 → 陷阱清单。
- `lock`：`--task`（acquire 必填）· `--wait <秒>` · `--ttl <小时>`（默认 `build`=1h / `bench`=6h，超期视为陈旧、下次 acquire 自动接管）· `--note` · `--bench-pass` · `--force`。⚠ `--note` 只在 **acquire** 写进 payload，**release 时被忽略** → 验收证据写主干提交说明或文档。
- 环境变量：`DTU_WT_ROOT`（默认仓库同级 `_wt/`）· `DTU_TASK_BASE`（默认基线）· `DTU_INTEGRATION_WORKTREE`（集成点，用于隔离演练）。
## 典型流程
```powershell
& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" new N21 dhara-isfree --needs-bench
# → 把新会话的工作目录切到打印出来的 _wt/N21-dhara-isfree/，在那里干活
& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" lock acquire bench --task N21
# 烧录 / @test / 板级套件……
& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" lock release bench --task N21 --bench-pass
# 回到主工作树执行回收
& $PY ".dsh\skills\task-worktree\scripts\task_worktree.py" done N21
```bash
"$PY" "$TW" new N21 dhara-isfree --needs-bench # 把新会话工作目录切到打印出来的 _wt/N21-dhara-isfree/
"$PY" "$TW" lock acquire bench --task N21 # 烧录 / /serial-boot-test / 板级套件
"$PY" "$TW" lock release bench --task N21 --bench-pass
"$PY" "$TW" done N21 # 回主工作树（铁律 1）；先 --dry-run 读全量
```
## 读输出：管道与截断（两起误判的共同根因）
1. **`| tail -N` 之后的退出码是 `tail` 的，恒 0** → 脚本的 1/2 全被吞（实测三条「rc=0」真码都是 2）。判据先看文本（`[ok]` / `!!` / `前置/环境错误：` / `失败：`），要真码就**不接管道**或取 `${PIPESTATUS[0]}`。
2. **`done` 的输出别 `tail -2`**：管道下 python stdout 块缓冲、git 子进程 stderr 不缓冲，两股流错位 → 只剩尾部那句「--dry-run：到此为止…」加带 `conflict` 字样的 stderr 片段，据此误判「有冲突」。dry-run 全文 5~8 行，**读全量**。
## 分步操作（节号 A–G/C2、各节步骤号与铁律编号被 reference/ 与 docs 引用，**不许重排**）
### A. `new` 撞并发上限 → 腾位
1. 认原文 `前置/环境错误：已有 8 个活跃任务（上限 8）；先 done/abort，或加 --force`（exit 2）。「活跃」= `_wt/.state/<ID>.json` 在且台账 `path` 目录还在 → **手工删目录不占名额、但留悬挂台账**（E 第 6 步）。
2. `$TW list` 定谁让位：**已完成的先 `done`**（合并回收一步不省）。
3. 无人认领、零提交、未 claim 的空闲树 → `abort <ID>`；有未提交或有提交时脚本会拒，确认可弃才 `--force`。
4. 真要第 9 棵才 `--force`：并行度上去，**冲突面与台架排队一起上去**（每棵磁盘代价见铁律 6）。
5. **别用手工 `git worktree remove` 给登记任务腾位**：台账不删（同 ID 报「任务已存在」）、又绕过「先摘联接」（铁律 5），有让 git 递归进联接删掉主树 `.venv` 的风险。要回收的是**非登记树**（`list` 里没有它）→ **E 节**。
6. 复验：`list` 条目数 == `ls _wt` 目录数，再 `new`。
### B. 非登记持有者的锁放不掉
症状：`lock release bench --task acceptwin --bench-pass`（带 `--force` 同）报 `前置/环境错误：任务 acceptwin 不存在（缺台账 _wt/.state/acceptwin.json）`，**锁照旧挂着**。根因：`release` 带 `--bench-pass` 就先 `load_state(task)`，而 `acquire` 侧不查台账 → 「释放」被「记账」挡死；锁没放，`done` 的 `release_stale_locks()` 对未到 TTL 的活锁判失败 → **一个没登记的名字挡住所有任务收口**。
**2026-10-29 已修**：无台账降级为 `[warn] …跳过 PASS 记录，仅释放锁`，**不再需要手写占位台账**。
1. `$TW lock status` 认现场（持有者 / pid / 已持有 / TTL）——别对同一句报错反复重试。
2. `$TW lock release <build|bench> --task <NAME> [--bench-pass]` 直接放；PASS 记不上会 warn，锁照放。
3. **PASS 后面还要用**（`done` 只认台账 `bench_pass`）→ 从一开始就用已 `new` 的 ID 占锁，或把结论写进主干提交/文档。插件树 `pw:<name>` 天然无台账 → F 节。
4. 最后手段：锁 = `_wt/.state/locks/<name>.lock` 的单行 JSON（`name/task/pid/host/epoch/at/note/ttl`），`release` 就是 unlink 它——手工删 = 不记 PASS 的强制释放，前面各步都不可用才做。**早期为绕坑手写的占位台账现在有害**（既占上限名额又被 `list` 当任务）→ E 第 6 步备份后删。
### C. `done <ID>`：它是合并点，不是查看器
1. **合并前确认属主提交完**：`$TW status <ID>` 看未提交与领先数，跨会话再问属主一句。实测教训：属主还剩「2/2」没提交就 `done` → 只含 1/2 的分支进了主干，只能另开一棵树补后半（自己的时序错，不是分支问题）。
2. 先 `--dry-run` 且**读全量**。判据两行：`[ok] 前置检查通过（领先 <base> 共 N 个提交）` + `[ok] 无冲突，预演结果树 <sha>`；**N 必须等于属主应交的提交数**，对不上回第 1 步。
3. 正式 `$TW done <ID>`——**必须在主工作树**（铁律 1）。
4. 见 `!! 门禁未全绿：工作树与分支**保留**，未清场` 时，紧跟的 `主干已含合并提交 <sha>` 说明**合并已落主干**；先定位哪条钩子红（`[SUMMARY] static: pre-commit hooks -- passed=N failed=M`），最常态是 `.map` 滞后 → 第 5 步。
- ✅ 走提示 a)：主工作树修正后追加提交。
- ❌ **绝不用 b) 的 `reset --hard <sha>`**——那是丢弃已入库的合并提交，且 `reset --hard` 是项目级 Never（连未提交工作一起丢）。提示 b 是列出的可能性，不是建议。
5. 补绿固定链（顺序即因果，全在主工作树，逐条不接管道看退出码）：
```bash
"$PY" scripts/check_mem_numbers.py --write # 台账受管区 ↔ 新 .map 对齐
"$PY" scripts/ram_baseline.py --write # RAM 快照 / 92% 预算台账
"$PY" scripts/ram_baseline.py --update # 趋势基线追加一行
"$PY" scripts/check_test_coverage.py --update-baseline # 覆盖率基线（新单测 / 新套件时必刷）
"$PY" scripts/check_doc_links.py --all # 文档链接与章节引用
git add <上面刷出来的基线/快照文件> # 显式列文件，别 -A 把别人在飞的改动一起提交
git commit -F <UTF-8 无 BOM 的正文文件> # 提交属 Ask first（AGENTS.md 边界）
```
为什么必然要补 → 陷阱「`done` 的门禁跑在 `/keil-build` 之前」。合并解过冲突时，**合并提交期 pre-commit 只查冲突文件**（→ G 节第 3 条）→ 落主干后必须另跑全量。
**注释/文档-only 但碰了 .c/.h 的短链**：先比 `Program Size` 与合并前是否逐项相同——相同就只 `ram_baseline.py --update` 重写体积凭证（`scripts/size_attestation.json` 跟着补提交笔走），**别 `--write` 动受管区**（等于给在飞分支造冲突面）；数字变了才走上面全链。**已命令化**：`"$PY" "$TW" postmerge`——新鲜直接跳过；红则先短链，再用只读 `check_mem_numbers` 复检裁定是否升全链；末尾跑 `--all` 并列出待提交文件（不代提交）。上面的手工全链仍是权威兜底。
6. **重跑 `done` 前主树必须干净**，否则 `失败：主工作树不干净（…）——合并会把未提交改动卷进来` → 第 5 步产物先提交。分支已并时重跑打印 `[i] task/<ID>-<slug> 已合入 <base>，跳过合并，直接清场`——**该路径在门禁之前就返回，不会替你复绿**：上一次门禁没跑到的尾巴（主树 `ci_local.py` + `check_doc_links.py --all`；体积/文档那半可 `postmerge` 一把跑）必须自己补。主树脏且那份脏不是你的 → **C2**。
7. 清场后再敲一次 `done <ID>` 得 `前置/环境错误：任务 <ID> 不存在（缺台账 …json）`（exit 2）——**不是失败**：清场最后一步 unlink 了台账。**判完成以 `git log` 为准**。
### C2. `done` 被「主工作树不干净」挡住，而那份脏是**别的并发会话**留的
- **不许**对它做 stash / checkout / reset / 提交 / 删除（项目级 Never，你不知它写没写完）。`done` 要求主树干净 → 合并与回收一起被挡，**那是保护不是工具坏了**。
- 正解六步，编号与 [reference/merge-dirty-main-tree.md](reference/merge-dirty-main-tree.md) 第 1~6 步一一对应（每步的确切命令与判据在那篇）：**取证**（mtime + diff 定性有无交集，顺带 `worktree list` 看有无别人中途新建的树）→ **预演** `git merge-tree --write-tree <base> <task>`（打出结果树 sha 且 RC=0）→ **主树手工合并** `git merge --no-ff --no-edit -F ci-artifacts/merge-msg-<slug>.txt <task>` → **对账**（合并后 blob id 与 stat 同合并前存值逐项一致）→ **备份台账** `cp <ID>.json <ID>.json.state-bak` 后让 `done` 自己摘联接拆树 → **复验** `worktree list` + `lock status`。
- **blob id 变了 = stash pop 半冲突**：立刻停止收工，把两份 blob id 与 diff 交给该文件属主，绝不 `checkout` 抹平。
- **报告要点名**：绕开 `done` 的理由 + 补回它的证据（预演 sha 与 RC、blob 对账、主树全库 `check_doc_links.py --all`、两把锁空闲）+ 那份外部脏文件与中途冒出来的第二棵树（谁的、你没动它的证据）。合并信息也过 G 的禁词自检；「这份脏通常是谁」见陷阱清单。
### D. 门禁指标异常增长 → 净室逐文件归因（主树全程只读）
三条判据：仓外 detached 树当净室、**一次只注入一份在飞文件**、与 HEAD 基线逐文件差分；主树前后 `git status --porcelain` 逐行一致才算「全程只读」。全文 → [reference/clean-room-measure.md](reference/clean-room-measure.md)。
### E. 回收**非登记**工作树（`list` 为空 / detached / 树里有在飞或未跟踪内容）
三条不可跳过：① 逐文件内容**三桶归类**（与主线工作区/HEAD 比对；「很久没动」不是判据）② 动手前跑**只读 reparse 预扫**，拿到 `REPARSE: none` 才许 `git worktree remove`（铁律 5）③ 唯一未合并残留先备份再 `--force`，拆完复验 + 清悬挂台账。**绝不跑 `done`/`abort`**（铁律 9）。全文（第 1~6 步 + 两份探针脚本）→ [reference/reclaim-unregistered.md](reference/reclaim-unregistered.md)。
### F. 与 DSH worktree 插件（`/worktree`、`worktree_create`）共存
| 联接 | 级别 | 依据 | 缺了会怎样 | 逃生门 |
|---|---|---|---|---|
| `simulator/SDL2` | **硬需求** | `simulator/CMakeLists.txt:12` 的 `set(SDL2_DIR …)` **非 `CACHE`**，include / `lib/x64` / `SDL2.dll` 全从它派生 | `build_sim.bat` 当场失败 | **无** |
| `.venv` | 软需求 | `scripts/ci_local.py` 有 `DTU_PRECOMMIT_PYTHON` + 五级解释器候选 | **静默**落机器级解释器（缺 fontTools → `generated-fresh` 假红） | 环境变量 |
- `plugin adopt` 两条都补只是因为便宜，不代表两条都硬。插件树占锁记 `pw:<name>`、**回收仍归 /worktree**（本 skill 不删插件树，插件也不删 `_wt/`）。「有插件为何还自持生命周期」＝先读插件包（`npm root -g`）再 grep 三个概念名报命中数，插件侧零命中就是理由——取证姿势与答案边界 → [reference/dsh-plugin-bridge.md](reference/dsh-plugin-bridge.md) F-2。
### G. 任务树内跑门禁：落点、`--all` 假红、消息禁词
- **新树没有 `ci-artifacts/`**（被 ignore → 不检出）：重定向/写文件直接 `ENOENT` 且**整段程序零执行** → 落盘前先单独一条 `mkdir -p ci-artifacts`；树内输出一律树内相对路径（`cd` 进树后 `../_wt/x.txt` 落到 `_wt/_wt/`）。一次性产物**不进仓库根**。
- **文档门禁树内按单文件跑；全库 `--all` 留到合并后在主树跑**——树内 `simulator/SDL2` 是同一份仓库的联接，`--all` 把它一起扫成假红（实测 RC=1 而问题全在联接下、要改的文档一条没有）。非要树内跑：① 主树同命令拿基线 ② 过滤联接下的问题行 ③ 剩下的逐行比。**只做一步就是误判。**
- **合并提交期 pre-commit 只查冲突文件**（日志首行 `[INFO] Checking merge-conflict files only.`，其余全 `(no files to check) Skipped`）→ 合并落主干后**必须另跑全量** `scripts/ci_local.py`。
- **跨层改动拆不成「按层分笔」**：钩子看到的世界 = HEAD + 本笔 staged（未暂存被 stash；未跟踪文件不被 stash 但会拖红同一棵树上别人的提交）→ 登记文件 / 生成物 / 互锁引用的文档分到他笔，本笔必被整仓门禁拦（`doc-links`/`registration-check`/`generated-fresh`/`mem-numbers`）。判据：**一笔提交必须自洽**。
- **跑门禁前字节体检**：`lines / bytes / BOM / CR / U+FFFD / 三连续空行 / 行尾空格 / 末行单个 LF` + Markdown 表格每行列数一致性（单元格内竖线写成反斜杠竖线，否则被当分隔符断列）。坏行**未必是本次改动**，先定归属。`doc-links`/`no-mojibake` 只覆盖编码那半。机械项已命令化：`"$TW" precheck`（BOM 漂移 / CR / U+FFFD + docs 逐档门禁，只读）；列数一致性与归属判定仍人做。
- **提交/合并信息一律 `-F` 读文件**（UTF-8 无 BOM、标题 ≤100、正文每行 ≤80，放 `ci-artifacts/`）；清退类任务加**禁词自检**：`git log -1 --pretty=%B | grep -c '<关键词>'` 必须是 **0**。未推送前发现消息写错 → `--amend -F` 就地修，别追加「更正」提交（等于把禁词写回历史）。BOM/CRLF/行长/禁词一次查：`"$TW" precheck --msgfile <文件> --ban <词1> --ban <词2>…`。
- 全文（第 1~7 条，含 stash 机制与四道整仓门禁现场）→ [reference/gates-in-tree.md](reference/gates-in-tree.md)。
## 铁律
1. **`done` 只能在主工作树执行**——主干分支检出在主工作树，git 不允许同一分支在两处检出。
2. **`done` 不 push**。它结束于本地合入 + 门禁全绿；推送需用户明确许可（项目既有纪律）。
3. **`build` 与 `bench` 都必须串行**：UV4 不能两个实例同时 `-b`；串口 COM6、ST-LINK、
设备 IP `192.168.1.100` 各只有一份。**构建与烧录都不可并发。**
- `build` 锁由 **`@build` 自持自释**，调用方无需手工 acquire/release；
- `bench` 锁**必须手工**：`lock acquire bench --task <ID>` → 烧录/`@test`/探针 →
`lock release bench --task <ID> --bench-pass`。
4. **单写者文档**：`docs/任务规划/`（整个文件夹）、`AGENTS.md` 的任务表块、`MDK-ARM/*.uvprojx`、
`.pre-commit-config.yaml`、内存快照 —— 任务期**不在任务工作树里改**，留到 `done` 统一处理。
5. **清场必须先摘联接**：脚本会先 `os.rmdir` 掉 `.venv` / `simulator/SDL2` 联接再
`git worktree remove`。**手工清场时千万别直接 `git worktree remove`**——git 可能递归进联接，
把主工作树的 `.venv` 一起删掉。
6. **并发上限 3 棵工作树**（每棵约 83 MB 检出）。
7. **工作树放仓库同级 `_wt/`，绝不在仓库内部**——否则污染 `git status`、`pre-commit --all-files` 与全库搜索。
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 合回）要在交付报告里点名这条例外。
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` 与全库搜索）。唯一例外 = 插件写死的仓内 `.dsh-worktrees/`（改不了，已用预置 .gitignore + 三个全库扫描排除兜住 → F 节）。
8. **`done` 是合并点**：属主没提交完就别跑；合并提交进了主干就只用「主树补提交」收尾，**不用 `reset --hard`** 反悔 → C 节。
9. **非登记 / detached 的树绝不跑 `done` / `abort`**：两者都以台账为前置（无台账 exit 2），带残留台账时 `abort --force` 会绕过内容保全把别人在飞的改动连树一起删 → E 节。
## 陷阱（实测）
## 陷阱与验证（收工前各扫一遍）
- **联接不是符号链接**：本仓库 `core.symlinks=false`，git 里的 symlink 会被检出成
「内容是目标路径的文本文件」。共享 `.venv` 只能用 Windows **目录联接**（`mklink /J`，
不需要管理员权限），且联接必须建在版本控制之外。
实测（2026-10-12）：用 ctypes 直调 `DeviceIoControl(FSCTL_SET_REPARSE_POINT)`
会被系统拒绝（Win32 4392），`mklink /J` 正常——所以脚本走后者，参数以列表交给
subprocess，含空格的路径（本项目 `DTU Code`）由 subprocess 自动加引号。
- **联接建失败不中止 `new`**：只告警并打印手工补建命令，避免留下半成品任务空间；
但该任务里跑不了 `.venv\Scripts\python.exe`，`@build` / `ci_local.py` 会找不到解释器。
- **`done` 前主工作树必须干净**：否则未提交改动会被卷进合并。
- **⚠ `done` 的门禁跑在 `@build` 之前 → 依赖 `.map` 的钩子会误报**（2026-10-12 实测）：
`done` 的顺序是「合并 → 重生成 → **门禁（ci_local）** → `@build`」，而
`mem-budget`（N-27）/ `mem-numbers` 是拿**文档快照 vs `.map`** 比对 —— 门禁跑时
`.map` 还是**主工作树合并前**的旧产物，与刚合并进来的新台账**必然不一致** →
误报 `[FAIL] 台账受管区与 .map 不一致`。`@build` 跑完后 `.map` 才是新的。
**处置**：门禁失败且只差这两项时，按提示在主工作树跑
`python scripts/ram_baseline.py --write` + `python scripts/check_mem_numbers.py --write`
后追加提交，再重跑 `done`（它会检测到「已合入」直接清场）。
- **⚠ 增量构建可能不重链 → `.map` 数字瞬态不一致**（2026-10-12 实测）：
`@build` 若判定无需重链，`.map` 保持旧值，此时 `--write` 生成的快照是**瞬态值**
（实测同一份源码两次读到 223,560 与 223,724，差 164 B）。**以主工作树（集成点）
的 `.map` 为准**；改完 RAM 相关代码后确认重链再刷新快照。
- **合并冲突常落在「生成物」上**：`docs/内存管理/RAM使用分析与优化方案.md`（mem-numbers
快照）在双方都改过时必冲突，且**两边都不能直接选**（各自基于不同基线）——
正确做法是解冲突后用**合并后的实际构建**重新生成，不要挑一侧。
- **并集合并残留**：双方都改过的文件（尤其 `.gitignore`）会被 git 自动并成**并集**，
可能留下指向已删目录的死规则或重复条目。脚本会自动报「双方都改过」的文件清单 +
连续重复行；**权威判据是 base / 两个 tip 三方对比**（`git show <ref>:<file>` 逐项 `grep -F`），
别用 `tail -N` 目测。
- **`.workbuddy-ai/` 刻意不共享**：记忆不随任务分叉，也不给联接递归删除的机会。
任务工作树自己的记忆由 `done` / `abort` 在清场前归并回主工作树。
- **`--lean` 只省磁盘不省时间**：实测全量 smudge 7.25 s / 83 MB，跳过 smudge 7.05 s / 45 MB，
两者工作区都干净。默认走全量（参考图可用），磁盘紧张时才用 `--lean`。
- **锁不绑定进程存活**：`lock acquire` 本身是短命进程，而真正用资源的烧录/构建在别的进程里跑。
所以判「陈旧」只看**时效**（该锁的 TTL）加显式 `--force`；pid 仅作排障记录。
同任务重复 acquire 是幂等的（不会把自己锁死）。
- **TTL 按锁分设**（2026-10-12）：`build` = **1h**、`bench` = **6h**（`LOCK_TTL_HOURS`）。
口径是「兜底窗口应与操作真实时长同量级」——编译是秒~分钟级，6h 的兜底太钝；
bench 是会话级（flash→`@test`→探针），才配得上小时级。持有者还可用
`lock acquire ... --ttl <小时>` **自报**更精确的窗口（`keil_build.py` 即按其 `--timeout` 自报）。
- **陈旧锁自动接管**：超过该锁 TTL 未释放即视为陈旧，下次 `acquire` 会接管并提示；
未到 TTL 的活锁需 `--force`。`done` 的收口前置也会**自动释放陈旧锁**（不再硬失败）。
- **`build` 锁不必手工持**（2026-10-12 起）：`@build`（`keil_build.py`）**自持自释**——
进入 acquire、`finally` 无条件 release，所以"Agent 忘了 release、锁一直挂到 TTL"这条在构建路径上已消除。
`done` 的门禁自己持锁并给子进程设 `DTU_LOCK_HELD=build` 告知跳过（新旧脚本都兼容）。
**`bench` 锁仍须 Agent 手工持**（会话作用域：跨烧录→`@test`→探针，见 `keil-build` SKILL.md）。
- [reference/pitfalls.md](reference/pitfalls.md)：全部实测坑逐条（含 `--dry-run` 不保护清场段、门禁跑在 `/keil-build` 之前、未跟踪文件在 `git log` 与合并里都不留痕、并集合并残留、新树从未构建 → 体积类门禁必然红、注释-only 也刷红体积凭证、「已合入」快路径在门禁前返回不替你复绿、`--force` 只覆盖四类检查、联接不是 symlink（`core.symlinks=false`）、锁不绑进程存活、文件工具先读后改按绝对路径记账、中文门禁回显乱码但 rc 可信）。收工前扫一眼。
- [reference/verification.md](reference/verification.md)：每节要留的证据（预演 sha + `MT_RC=0`、blob id 对账、两把锁空闲、禁词计数 0、`REPARSE: none`、改上限数字后的全形态扫描）。
## 与其它 skill 的衔接
- 构建 = `keil-build` skill（`@build`）；烧录/回读 = `stlink-flash` skill；串口闭环 = `serial-boot-test` skill
- 新 `.c` 文件 = `new-source-file` skill（`uvprojx` 与 `CMakeLists.txt` 双端注册）
- 完整机制与目录分配 → `docs/环境与部署/并行任务工作树方案.md`
- 构建 = `keil-build`· 烧录/回读 = `stlink-flash` · 串口闭环 = `serial-boot-test`（真实 hex 路径以 `.serialtest/config.json` 的 hex 键为准——实测 `MDK-ARM/Objects/STM32F407-Demo.hex` 不存在，拷错 = 烧旧镜像）
- 新 `.c` 双端注册 = `new-source-file` · RAM/.map 台账 = `mem-budget` · UI 回归 = `ui-verify` · 计数同步 = `stale-doc-count-sweep` · 卡死的技能台账行 = `mnemon-skill-ledger-stuck-repair`
- DSH worktree 插件（`/worktree` / `worktree_create`，仓内 `.dsh-worktrees/`）与本 skill 的分工、桥接命令、锁归属 → F 节 · 完整机制与目录分配 → `docs/环境与部署/并行任务工作树方案.md`
.dsh/skills/task-worktree/reference/clean-room-measure.md
+58
View File
@@ -0,0 +1,58 @@
### D. 门禁指标异常增长 → 逐文件归因（把净室工作树当**测量仪**，主树全程只读）
**场景**（2026-10-27 实测）：`id-check` 突然 FAIL「不可判定 1,178 > 上限 1,166」——比上一轮量到的 1,162 又涨了 **+16**，
而主工作树里同时压着 4 条在飞任务道的未提交改动。**不许 stash / checkout / reset**（那是搬动甚至丢弃别人未提交的工作，
项目级 Never；`git status` 一乱，整条道的现场就没了），**不许改门禁脚本本身**（它就是那把尺子，改了数字就不可信），
**也别在脏主树里跑门禁**（那测的是 4 条道 + 未跟踪文件的混合体，永远分不出谁）。正解：**在仓库之外另起一棵
detached HEAD 的干净工作树当净室，一次只往里注入一份在飞文件**，与基线差分即得每个文件的独立贡献。两步：
**净室建树 → 单文件注入测量**。
1. **建净室 + 先落基线数**（路径必须**在仓库目录之外**；铁律 7 对临时树同样成立——放仓内就污染 `git status` /
`pre-commit --all-files` / 全库搜索）：
```bash
MAIN="D:/Code/DTU Code/STM32F4-Base" # 主工作树绝对路径（含空格 → 变量整体加引号）
WT="$MAIN/../_wt/und-attr" # 仓外同级 _wt/ 下；一次测量固定用同一个名字
rm -rf "$WT" 2>/dev/null
git -C "$MAIN" worktree add --detach "$WT" HEAD >/dev/null 2>&1 || { echo WT_FAIL; exit 9; }
git -C "$WT" status --porcelain # 应为空
"$PY" "$WT/scripts/archive/id_gate/check_ids.py" 2>&1 | tail -25 # ← 口径：id-check 钩子已于 2026-10-28 退役（脚本移入 scripts/archive/id_gate/），按该脚本自身默认参数跑；基线与注入用**同一条命令**
```
- `--detach`（**不要 `-b`**）：净室没有分支、不写 `_wt/.state/<ID>.json` 台账 → **不占 `MAX_CONCURRENT = 8`
名额、不出现在 `$TW list`**，也没人会被误指去对它跑 `done`（建与拆都不走 `$TW new` / `$TW done`）。
- 能这么量的前提：该门禁**只读仓库内文本**。依赖本树构建产物的门禁（`mem-numbers` / `mem-budget` 要 `.map`）
在净室里必然报「找不到 .map 事实源」（见陷阱「新建工作树从未构建过」）——**那类指标不能这么归因**。
- `git status --porcelain` 非空 = 有别人的未跟踪文件被带进净室 → 先 `git clean -xdn` **干扫**（别去 `n`）
看清会删什么，只挪走多出来的那些再测；语料被污染出来的数字与 CI 不可比。
2. **一次只注入一份在飞文件 → 跑同一个扫描器 → 与基线差分**（得到的是每个文件的**独立**贡献，不是合计）：
```bash
for f in "App/log/sys_log_mcu.c" "test/host/sys_log_mcu/sys_log_mcu_test.c" "docs/子系统设计/运行与自检记录设计说明.md"; do
mkdir -p "$WT/$(dirname "$f")"
cp "$MAIN/$f" "$WT/$f" # 拷进净室；主树那份只读、一字节不动
echo "== $f =="; "$PY" "$WT/scripts/archive/id_gate/check_ids.py" 2>&1 | tail -25 # ← 与第 1 步同一条命令
git -C "$WT" checkout -- "$f" # 只还原净室里自己刚拷进来的那份
done
```
实测：`run_par.c` / `board_ui_nav.py` / `check_nested_comment.py` / keil `SKILL.md` **各 +0**，
而 log 道那三个文件 **+6 / +8 / +2**，合计**正好 +16**。**Σ(逐文件增量) ≠ 观察到的涨幅 → 还有没被注入的
在飞文件，或存在文件间交互项**，不许就此交卷。
3. **定性增量是哪一类字面量**（只有「谁」没有「为什么」= 给不出可执行的改法）：同一计数器在 **HEAD 版**与
**在飞版**各数一遍，**差值才是新增行带来的**（存量的不算这条道的账）；再对新增行直接 grep。本次 16 处全是
**裸形 「字母 T 累进数字 4」**（`T` 在 `scripts/archive/id_gate/id_registry.json` 的 `bare_check_letters` 里，规范形态是连字符形），
全部落进 `skip_bare_unmanaged` —— 到这一步结论才配发给属主。
4. **闭合 + 复验主树一个字节没被污染**：
```bash
git -C "$MAIN" worktree remove --force "$WT" # 净室里只有自己的拷贝、没有原件，--force 安全
git -C "$MAIN" worktree list # 不该再有 und-attr
git -C "$MAIN" status --porcelain | sort # 与测量前**逐行一致**（测量前先存一份基线清单）
```
⚠ **上面第一行的前提是有条件的**：树里混进了别人的在飞 / 未跟踪内容时「只有自己的拷贝」就不成立了，
`--force` 直接拆等于替别人把唯一版本删掉 → 先走 **E 节**（全景 → 逐文件分桶 → 联接预扫 → 唯一残留先备份），
再回来执行本步；复验按 **E 第 5 步**做（拆前/拆后主树 `status --porcelain -uall` 行数必须相同）。
**同一棵净室树的第二种用法**：按指定 commit **只读**构建出像 / 烧录验收——不搬动任何在飞改动，也不为台架
提前抢发一笔提交；构建与烧录都在这棵树里做（不在主树），仍受 `bench` / `build` 锁串行（铁律 3）。
.dsh/skills/task-worktree/reference/dsh-plugin-bridge.md
+87
View File
@@ -0,0 +1,87 @@
### F. 与 DSH worktree 插件（`/worktree`、模型工具 `worktree_create`）共存
本仓现在有**两套**隔离空间。别混用，也别互相回收：
| | 本 skill（文档别名 `@task`，DSH 显式调用 `/task-worktree`） | DSH worktree 插件（`dsh-task-worktree`） |
|---|---|---|
| 树在哪 | 仓库**外** `../_wt/<ID>-<slug>/` | 仓库**内** `.dsh-worktrees/worktree/<name>/` |
| 谁建 | `new <ID> <slug>`（人来敲命令） | 会话选「Worktree模式」/ 模型调 `worktree_create`（零命令） |
| 台账 | `_wt/.state/<ID>.json`（本 skill） | `.dsh-worktrees/manifest.json`（插件私有格式，别去改） |
| 分支名 | `task/<ID>-<slug>` | `worktree/<name>` |
| 共享联接 | `new` 自动建 | **建树时没有** → 要 `plugin adopt` 补 |
| 回收 | `done`（预演 / 合并 / 门禁 / 清场）或 `abort` | 用户敲 `/worktree finish\|bring-back\|remove\|prune`（模型碰不到收尾命令） |
**为什么允许它把树建在仓内**（铁律 7 的唯一例外）：路径写死在插件里（`WORKTREE_NAMESPACE = worktree`
+ `<repo>/.dsh-worktrees/`），而暴露给模型的工具只有 `worktree_create` / `worktree_list` /
`worktree_status` 三个，配置面改不动。兜法三件（均已落地）：
1. `.gitignore` **预置** `.dsh-worktrees/` —— 插件首次 `create` 会往 `.gitignore` 追加一模一样的字面量，
`ensureIgnored()` 见到同名规则即跳过；不预置就等于让插件在会话中途改这份受控文件（diff 里冒出
一行"不是我加的"）。
2. 全库扫描的排除面登记了它：`scripts/check_doc_links.py` 的 `SKIP_PARTS`、
`tools/refgraph/gen_refgraph.py` 的 `EXCLUDE_DIRNAMES`、`scripts/check_layer_deps.py` 的 `os.walk` 兜底。
一份仓库副本被全库扫描吞进去 = 文档链接假红 + 配图生成物逐字节漂移砸在某位同事头上。
3. 联接与锁归属由本节命令接上（下面三步）。
**这棵树是不是插件的**：`git worktree list` 里路径含 `.dsh-worktrees/` 就是。`$TW list` 现在会在台账段
下面另起一段列出它们，联接列**点名缺哪一样**（`已联` / `缺 .venv` / `缺 SDL2` / `齐(实体SDL2)`）。**插件树不占
`MAX_CONCURRENT = 8` 名额**——回收不归本 skill，
硬计入只会让别人那棵关不掉的树把 `new` 挡死（`new` 会打印一行「另有 N 个插件工作树不计入上限」提醒并发代价）。
三步接上（`<name>` 可带 `worktree/` 前缀，也可多段如 `refactor/logging`）：
```bash
"$PY" "$TW" plugin list # 一览：分支 / 脏 / 缺哪个联接（缺项另起一行说后果）
"$PY" "$TW" plugin adopt N21-dhara-isfree # 只补缺失的 .venv 与 simulator/SDL2 联接
"$PY" "$TW" plugin unadopt N21-dhara-isfree # 只摘联接（os.rmdir），绝不动目标内容与树里文件
```
- **两条联接坏了的样子完全不同**：缺 `.venv` → `ci_local.py` 的四级解释器回退**静默**落到机器级
python（无 fontTools = `generated-fresh` 假红的老根因，AGENTS.md 记着）；缺 `simulator/SDL2` →
`build_sim.bat` 当场报错（`SDL2_DIR` 是裸 `set`，没有 env 逃生口）。所以列表只说「已联」不够——
它按缺的那一样分别给后果，`adopt` 没补齐也只报「还不能算就绪」，不许说「现在可以跑」。
- **adopt 只碰联接**：已联的跳过；`simulator/SDL2` 若已是实体目录只告警不动；`.dsh-worktrees/` 之外的路径
一律 exit 2（实测 `plugin adopt ".."` 被拒）——这道闸防的是把主树或 `_wt` 目录当插件树遮蔽掉真实内容。
- **锁归属现在认得出来**：`/keil-build` 在插件树里自持自释时，持有者名从 cwd 反推成 `pw:<name>`（多段名压平成
`-`），与 `plugin adopt` 打印的那个名字逐字相同（`keil_build.py: plugin_tree_owner()` ↔
`task_worktree.py: plugin_lock_owner()`）→ `lock status` 不再一律落成 `build-cli`。
- 上台架仍须手工占锁、用同一个名：`lock acquire bench --task pw:<name> --note <说明>` →
`lock release bench --task pw:<name> --bench-pass`。插件树没有台账 → 按 B 节只 warn、锁照常放。
- **命名建议**：插件 `<name>` 沿用本 skill 的 `<ID>-<slug>` 形态（如 `N21-dhara-isfree`），两套视图同名好对账；
但分支前缀必然不同（`worktree/` vs `task/`），别把两者说成同一个分支。
- **收尾不在这**：`done` / `abort` 拿插件树名下手只会 exit 2（这是保护，别绕过去手工 `git worktree remove`；
要拆先 `plugin unadopt` 摘联接，再由**用户** `/worktree remove`）。`/worktree bring-back` 要求主工作树干净，
本仓常有在飞改动 → 提交或 stash 由用户定。反过来插件也不会碰 `_wt/`（路径根不同，谁也删不掉谁）。
### F-1. 两条共享联接**不是同级需求**（按仓库实配定级；别答成「两个都必须」）
- **`simulator/SDL2` = 硬需求**：`simulator/CMakeLists.txt:12` 是
`set(SDL2_DIR "\${CMAKE_CURRENT_SOURCE_DIR}/SDL2/SDL2-2.32.10")`——普通 `set()`、**非 `CACHE`**，所以既没有环境变量入口、
命令行 `-DSDL2_DIR=` 也会被这个普通变量盖掉；`SDL2_INCLUDE_DIR`（:34）、`SDL2_INCLUDE_PARENT`（:70）、`SDL2_LIB_X64`（:71）、
链接目录（:180）、`SDL2.dll` 拷贝（:207）**全部从它派生**。缺它 `build_sim.bat` 当场配不出来（脚本里的 `SDL2_DIR` 同样是
裸 `set`，也没有 env 逃生口）。
- **`.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` 顶掉，
但要每台机器自己配——这就是它「软」的意思：有路可走，走得不爽。
结论口径：**要补就两条都补（`plugin adopt` 一次干完，成本近乎零），但「都必须」是错的**——SDL2 没有任何替代路径，
`.venv` 有 `DTU_PRECOMMIT_PYTHON` 这条门。现役命令形式仍是 `plugin list` / `plugin adopt <name>`；**不改代码、
不改 `CMakeLists.txt`**（真要给 SDL2 加 CACHE 逃生门属于改模拟器构建口径，另案 → `lvgl-simulator` skill）。
### F-2. 「DSH 都有 worktree 插件了，为什么还自持 Python 生命周期」——取证姿势与答案边界
这题不许凭印象答，口径 = **实读插件源码**：在 DSH 安装目录定位插件包（`npm root -g` → `<global>/node_modules/@deepseek-ai/dsh/`，
或读 profile 的 `dsh.profile.bundles` 找包名），**记下版本号与文件路径**，再对三个概念名逐个 grep 并**报出命中数**：
1. 独占锁 / 资源串行（`lock`、`acquire`、`release`、TTL）——插件侧**零命中**：它的模型是「一棵树一个会话」，没有跨会话排队概念。
2. 共享目录联接（`.venv`、`simulator/SDL2`、`mklink /J`、reparse point）——零命中：插件建树就是纯 `git worktree add`，
所以插件树天生缺这两条联接（定级见 F-1）。
3. 联接状态显示（三态：已联 / 缺 .venv / 缺 SDL2 / 齐(实体SDL2)）——零命中。
**重叠面要说清**：两侧底层是**同一条** `git worktree add`，本 skill 没有重造「建树」；重叠只在**开**与**收**两个动作，
而插件的收（`/worktree finish|bring-back|remove|prune`）是**人类命令**、模型碰不到，也没有「合并前预演 → 并集残留审计 →
补基线 → 门禁 → 先摘联接」这条编排。本仓为什么必须自持：硬件各只有一份（一块 ST-LINK、一套 Keil 授权、一个 COM6、
一个 `192.168.1.100`）→ 要 `build` / `bench` 锁串行；SDL2 是模拟器硬依赖且无逃生门 → 要共享联接；台架 PASS 要留给
`done` 记账 → 要台账。**给不出版本号与 grep 命中数，就不要下结论。**
.dsh/skills/task-worktree/reference/frontmatter-history.md
+9
View File
@@ -0,0 +1,9 @@
# 原 frontmatter（2026-10-29 因超 65536 字节写侧上限而瘦身，原文逐字留档）
本技能正文受 dsh-mnemon 插件写侧上限 65536 字节约束（只在写侧校验，加载侧不查），超限时自进化每次「生成草案」都会被拒、行永久卡在「生成中」。以下是瘦身前的 description / whenToUse 原文，触发词语义更全，写路由时可参考；如需恢复请连正文一起改回并先确认总体积 < 65536。
---
name: task-worktree
description: 多任务并行开发的空间管理（git worktree 生命周期）：new 开一棵工作树 + 任务分支、目录联接共享 .venv 与模拟器 SDK、活跃任务硬上限 8 与腾位、build/bench 两类独占锁（含非登记任务占锁后「缺台账」释放不掉的正解）、done 预演合并回主干、**主工作树被别的并发会话弄脏时的手工合并路径（取证 → `merge-tree` 预演 → `merge --no-ff -F` → 外部改动 blob id 前后对账 → C2 节）**、门禁未全绿的补基线收尾、并集合并残留审计、**任务树内门禁与审计输出的落点（`<tree>/ci-artifacts/` 先 `mkdir -p`；文档链接按单文件在树内跑、全库 `--all` 基线合并后在主树跑；`simulator/SDL2` 联接假红 → G 节）**、**非登记工作树（detached HEAD / 无台账 / 树内有在飞或未跟踪内容）的安全回收**（逐文件内容分桶 + 联接/reparse 预扫 + 唯一残留先备份再 --force + 悬挂台账清理复验），以及**把仓外 detached worktree 当净室测量仪**——门禁指标异常增长时一次只注入一份在飞文件、与基线差分做逐文件归因；**以及与 DSH worktree 插件（`/worktree`、模型工具 `worktree_create`，树在仓内 .dsh-worktrees/）的桥接**——`plugin adopt` 补共享联接、锁归属 `pw:<name>`、回收仍归 /worktree。规格见 docs/环境与部署/并行任务工作树方案.md。
whenToUse: 要同时推进多个任务、担心同分支同文档互相冲突；要为新任务开一个隔离空间；要把任务合并回主干；或遇到 `new` 报「已有 8 个活跃任务（上限 8）」、`lock release` 报「任务 X 不存在（缺台账）」、`done` 报「门禁未全绿：工作树与分支保留，未清场」、或 `done` 报「主工作树不干净」而那份未提交改动是**别的会话/插件**留下的（不能提交也不能丢弃 → C2 节手工合并）、两个任务抢 COM6 / UV4、"改了文档被覆盖"、并集合并残留时；或**要在任务树里跑文档/审计门禁**——`--all` 报一堆问题却全在 `simulator/SDL2` 联接下、或往 `ci-artifacts/` 写输出报 ENOENT / No such file or directory（→ G 节）；或**门禁指标异常增长（如 id-check 的不可判定数从 1,162 涨到 1,178、+16）却查不出是哪个文件 / 哪条任务道造成的**、主工作树压着多条在飞改动而不许 stash / 提交 / 改门禁脚本、要按 HEAD 基线只读出像验收时；或**要回收 `@task list` 里根本看不到的工作树**（`git worktree list` 有它、台账没有 / detached HEAD / 树里疑似留着别的会话的在飞或未跟踪内容）、或**要清台账里 branch / path 都已不存在的悬挂条目**（`@task list` 输出发怪、`new` 报「任务已存在」或白占 8 个名额之一）；或**这棵隔离空间是 DSH worktree 插件开的**（会话选了「Worktree模式」/ `/worktree create`，树在仓库内 `.dsh-worktrees/`）——进去发现 `.venv` 不在、`@build` 与门禁全部起跑失败，或想看清谁在占 UV4 / 台架 → F 节。
---
.dsh/skills/task-worktree/reference/gates-in-tree.md
+61
View File
@@ -0,0 +1,61 @@
### G. 任务树内跑门禁与审计：输出落点（ci-artifacts）与 SDL2 联接假红
三条硬规矩，全是 2026-10-29 实测付过失败成本的（两起 ENOENT + 一次假红误判）：
1. **门禁/审计输出只落 `<tree>/ci-artifacts/`，而新树里它不存在 → 落盘前先 `mkdir -p`**。`ci-artifacts/` 被
`.gitignore` 忽略（不污染脏行数，E 第 4 步的备份同理），但也因此**不会被检出**——`$TW new` 出来的树里没有这个
目录。直接 `fs.writeFileSync("<tree>/ci-artifacts/head-md.md", …)` 当场 `ENOENT: no such file or directory`，
**整段程序零执行**（实测：那一轮的门禁体检与快照读取全没跑成，白重跑一次）。用 Node 写之前先
`fs.mkdirSync(dir, { recursive: true })`；用 bash 重定向就先单独敲一条 `mkdir -p ci-artifacts` 再落盘
——重定向在命令执行**之前**解析，目录没建出来时是同一条命令直接失败，后面串着的 `grep` 跟着一起报
`No such file or directory`，看着像「门禁没跑出结果」，其实是写错了地方。
2. **`cd` 进任务树之后，`../_wt/x.txt` 不是你以为的地方**：`cd` 之后 `..` = `_wt`，`../_wt/x.txt` 落到
`_wt/_wt/x.txt`（实测就是这么报的）。**树内命令的输出一律用树内相对路径**（`ci-artifacts/xxx.txt`）；
要绝对路径就写完整绝对路径，跨树取文件用 `$MAIN/…`、`$WTROOT/…` 这种变量打头的全路径，
不靠 `cd` 之后的相对层级往上跳。
3. **任务树内文档门禁按单文件跑；全库 `--all` 基线留到合并后在主树跑**。任务树的 `simulator/SDL2` 是指向
主树同一份的**目录联接**（`new` 的第 2/3 步建的），`--all` 会把这份「仓库里的第二份仓库副本」一起扫：
实测任务树里 `check_doc_links.py --all` 打 `检查 222 个文档，35 处问题`、RC=1，而 **35 处全落在
`simulator/SDL2` 联接下**、要改的文档一条都没有 → 判红纯属联接带来的假红。单文件检查不受影响
（扫描根就是那一个文件，联接目录不在面内）。主树本身没有 SDL2 时不产生这类假红（联接如实镜像主树，
F 节那棵树连 SDL2 都没得联），但**别据此认为 `--all` 在树内可信**。
```bash
F="docs/<子目录>/<本次改动的文件>.md" # 本次改动的那一个文件
"$PY" scripts/check_doc_links.py "$F" > ci-artifacts/dl-<slug>.txt 2>&1; echo RC=$?
cat ci-artifacts/dl-<slug>.txt
```
逐文件跑的实测读数：需求文档 161 处章节引用 / 98% 机器可判定 / rc=0；方案文档 16 处 / 88% / rc=0。
确实要在树内跑 `--all` 时（例如怀疑主干基线本身），判红顺序**固定三步**，缺一步都不许下结论：
① 在**主树**跑同一条命令拿基线；② 过滤掉 `simulator/SDL2` 联接下的问题行；③ 剩下的与主树基线逐行比。
只跑 `--all` 见 RC=1 就回「文档门禁挂了」= 把基线噪声算成本任务的账；只跑「过滤后为空」就回「全绿」
= 会漏掉真红。全库 `--all` 的正解位置是**合并后的主工作树**：实测合入后在主树跑 `check_doc_links.py --all`
= 2,597 处章节引用 / 194 个文档 / rc=0 —— 这才证明「就地删叙述」没打断任何引用。
另：**不因 `--all` 的既有假红跳过对本次改动文件的单文件复检**（假红是基线的事，你的文件仍要逐个过）。
4. **文档改动在树内提交前的固定体检**（2026-10-29 实测）：`lines / bytes / BOM / CR / U+FFFD / 三连续空行 /
行尾空格 / 末行单个 LF` + 一个自写的 **Markdown 表格每行列数一致性**检查（数格子前先把转义管道 `\|` 还原成占位符，
否则会把 `\|` 当成列边界数错）。为什么要自己数：`doc-links` 只管链接与章节、`no-mojibake` 只管编码面，
**表格断列与删段留下的三连续空行没有任何钩子会报**。
实测读数：需求文档 `lines=2665 bytes=196137 BOM=false CR=0 U+FFFD=0 tripleBlank=0 trailingWS=0 endLF=true`，
表格体检另报两处坏表格（`L988-992 counts=5/7`、`L2472-2486 counts=2/3`）——**与本次编辑无关的历史行**。
所以体检要**区分「本次改动 bad=0」与「整份文件 bad=0」**：先定位归属再决定动不动手，顺手改别人的区域等于把
没打算提交的内容卷进这笔改动（报告里写「本次改动引入 0 处」，并点名那两处是存量）。
5. **提交 / 合并信息一律 `-F` 读文件；清退类任务还要做禁词自检**（2026-10-29 两遍实测）：消息文件写在
`ci-artifacts/`（被忽略 → 不污染脏行数），UTF-8 无 BOM、CR=0、标题 ≤100 字符、正文每行 ≤80（实测标题 31 / 32 字符、
正文最长行 50 / 55）——`-m` 会把中文按终端代码页转码搞坏，长中文标题还容易撞 gitlint。硬自检：
```bash
git log -1 --pretty=%B | grep -c '485' # 被清退主题的关键词：必须是 0
git log -1 --pretty=%B | grep -ci '\bDE\b' # 同主题的次要关键词：同样 0
```
关键词不许出现在**标题、正文、合并信息**任何一处（实测标题改写成「删除与本方案无关的其它串口通道对照内容」这种
语义短语替掉了它）——否则「别让我看到 X」这条要求在 `git log` 里当场破产。合并信息是另一份文件：
`ci-artifacts/merge-msg-<slug>.txt` 落盘后**同样 grep 一遍**再 `git merge --no-ff --no-edit -F`（C2 第 3 步）。
自审发现消息里的行数 / 统计算错而**尚未推送** → `git commit --amend -F <改好的文件>` 就地修（实测就这么修掉一次
off-by-one）；**别追加一笔「更正」提交**——那等于把禁词和被更正的错数一起写回历史。
6. **合并提交期 pre-commit 只查冲突文件（2026-10-29 实测）**：合并那一次提交的钩子日志首行是 `[INFO] Checking merge-conflict files only.`，其余钩子全打 `(no files to check) Skipped` —— 于是「合并提交通过了 30 项钩子」这句话**只覆盖冲突文件**，别拿它当全量绿。正解：合并落主干后立刻在主工作树跑全量 `scripts/ci_local.py`（静态 + 提交信息 + 主机侧单测 + manual 段），实测全量这一步才会抓到「表格断列」「章节引用悬空」这类跨文件问题。合并解冲突时若上游把 Markdown 表格重排过，注意**单元格里的竖线必须写成反斜杠竖线**（先例 `docs/子系统设计/运行与自检记录设计说明.md` 的 `FA_WRITE\|FA_SEEKEND`），否则 `FA_WRITE|FA_OPEN_APPEND` 会被当列分隔符打断，而 `doc-links` 不查表格列数——要自己数（第 4 条）。
7. **跨层改动拆不成「按层分笔」提交（2026-10-29 实测，四笔改一笔）**：钩子看到的世界 = HEAD + 本笔 staged——pre-commit 会 stash 已跟踪文件的未暂存改动，而**未跟踪文件不在 `git diff-index` 里、不会被藏**（`git add -N` 也救不了，pre-commit 会把它撤下索引、文件仍在盘上）。后果：把双端登记（`MDK-ARM/*.uvprojx` / `simulator/CMakeLists.txt`）、生成器产物、互锁引用的文档分到别的笔里，本笔必被 `doc-links`（引用了还没入册的小节）、`registration-check`（源文件登记在另一笔）、`generated-fresh`（`#page=` 找不到页面描述符、字库清单与源不一致）、`mem-numbers`（受管区还是旧 .map 的数）四道**整仓**门禁一起拦。判据：**一笔提交必须自洽**——互锁的改动（代码 + 登记 + 生成物 + 文档）走同一笔；机制与三条处置结论（半成品要么先落地要么先挪出工作树）→ `docs/代码规范/pre-commit使用说明.md` §2「stash 覆盖面」。
.dsh/skills/task-worktree/reference/merge-dirty-main-tree.md
+86
View File
@@ -0,0 +1,86 @@
### C2. `done` 被「主工作树不干净」挡住，而那份脏改动是**别的并发会话**留下的
**场景**（2026-10-29 同一套流程在同一天跑了两遍，两遍都撞上它）：任务树里的文档改完、准备合回 `v2-on-ui`，
主工作树却压着一个自己从没碰过的未提交改动（两次都是 `M .dsh/skills/serial-boot-test/scripts/run_boot_test.py`，
另一个并发会话/插件留下的）。它既不能提交（不是我的改动，也不知道写没写完），也不能
stash / checkout / reset / 删除（项目级 Never：丢弃别人的工作）。`$TW done <ID>` 的前置正好卡在这——
它要求主工作树干净，否则未提交改动会被卷进合并（见 C 第 6 步），于是**合并与回收一起被挡**。
**正解 = 取证 → `merge-tree` 预演 → 主树手工 `--no-ff` 合并 → 自证外部文件没被动过 → 照常收工**，六步：
1. **先取证再动手**（别一看见脏就下「谁弄坏的」结论）。记下它的 mtime 与 diff 内容，判断与本合并有无交集，
并把**合并前**的 blob id 与 `diff --stat` 存进 `ci-artifacts/`（第 4 步拿它对账）：
```bash
MAIN="D:/Code/DTU Code/STM32F4-Base"
EXT=".dsh/skills/serial-boot-test/scripts/run_boot_test.py" # 外部脏文件的仓库相对路径
mkdir -p ci-artifacts
git -C "$MAIN" status --porcelain # 全量脏清单（本会话只认自己那几条）
stat -c "%y %s %n" "$MAIN/$EXT" # mtime + 字节数：定性是谁在什么时候改的
git -C "$MAIN" diff -- "$EXT" | cat # 内容性质；与本次合并有无同文件同区域
git -C "$MAIN" hash-object "$MAIN/$EXT" | tee ci-artifacts/ext-blob-before.txt # ← 存下这个 blob id
git -C "$MAIN" diff --stat -- "$EXT" | tee ci-artifacts/ext-stat-before.txt # ← 以及这份统计（几加几减）
```
实测：mtime 落在另一会话的活跃时段内，diff 是「docstring 引号改写」2+/2−，与要合的文档毫无交集 →
定性为**与本合并无交集、不丢弃**。顺手 `git -C "$MAIN" worktree list` 看一眼有没有**别人中途新建的任务树**
（两次里都撞见第二棵树 `data-trust-restructure`，正是这份外部改动的来路）——这是并发会话的硬证据。
2. **`merge-tree` 预演：先证明能干净合并，再碰主干**。`$TW done --dry-run` 在这条路上同样被前置挡住，
预演只能自己敲（git 2.38+ 的新语法，打印的是**结果树 sha**）：
```bash
git -C "$MAIN" merge-tree --write-tree v2-on-ui task/<ID>-<slug>; echo MT_RC=$?
```
判据 = **打印出一个 tree sha 且 RC=0**（实测打出 `4220906b…` + `MT_RC=0` 才敢往下走）。⚠ 本机 git 太旧没有
这个子命令时退回 `$TW done <ID> --dry-run`——它的前置也是「主树干净」，可用环境变量 `DTU_INTEGRATION_WORKTREE`
把集成点指到一棵干净的临时树去演练（见本文开头的环境变量）；**别为了跑 dry-run 去动主树那份脏改动**。
预演报冲突 → 回到冲突本身处理，不许直接 `--no-ff` 硬合。
3. **主工作树里手工 `--no-ff` 合并**（合并信息走 `-F` 文件，放在被忽略的 `ci-artifacts/`；编码口径同 C 第 5 步：
UTF-8 无 BOM、正文每行 ≤80 字符；标题格式 `merge: task/<ID>-<slug> 合入 <base>`）：
```bash
git -C "$MAIN" merge --no-ff --no-edit -F ci-artifacts/merge-msg-<slug>.txt task/<ID>-<slug>
```
pre-commit 会**自己**把那份未提交改动 stash 起来、跑完钩子再放回（输出里能看到 `[INFO] Stashing unstaged files to …`）
——**这条不是让你去手工 stash**，正好相反：钩子的 stash 往返让它自己走完，你只需在第 4 步验证它把东西原样还回来了。
**为什么可以绕开 `done`**（报告里要写清这句）：`done` 的前置要求主工作树干净，而那份外部改动既不能提交也不能
丢弃，所以合并只剩「手工预演 + 手工合并」一条合法路径；被跳过的门禁与审计由第 2 步（预演 sha + RC=0）、
第 4 步（blob id 对账）、G 节（合并后在主树跑全库基线）、第 6 步（`lock status`）逐项补回。
**这不是绕过保护**，是把保护要求的证据逐条自己交出来。
4. **自证那份外部改动原样还在**（本节唯一的硬证据，两次实测都靠它结案）：合并后**再跑一次**同一对命令，
与第 1 步存的两个值**逐项相同**：
```bash
git -C "$MAIN" hash-object "$MAIN/$EXT" | tee ci-artifacts/ext-blob-after.txt
git -C "$MAIN" diff --stat -- "$EXT" | tee ci-artifacts/ext-stat-after.txt
diff ci-artifacts/ext-blob-before.txt ci-artifacts/ext-blob-after.txt # 空输出才算过
git -C "$MAIN" status --porcelain # 该文件仍是 M：没被顺手提交，也没被清成干净
```
实测：合并前后 blob id 同为 `369380ca8eb024b593d872455b6a020797abcd8d`、`diff --stat` 同为 2+/2−
→ 证明 pre-commit 的 stash 往返没动别人的工作；合进主干的那份文档另按 G 节复核（零残留 + 全库基线）。
blob id 变了 = stash pop 出了半冲突（现场会留下 stash 与冲突标记）→ **立刻停止收工**，把两份 blob id 与两份
diff 原样贴进报告交给该文件属主；**绝不用 `git checkout -- $EXT` 抹平**（那是销毁别人的工作，项目级 Never）。
5. **收工仍走技能自身的代码路径，别自己手写 rm**：先把台账**备份成 `*.state-bak`**（后缀与 E 第 6 步统一），
再让脚本自己摘联接：
```bash
cp "$WTROOT/.state/<ID>.json" "$MAIN/ci-artifacts/<ID>.json.state-bak" # 先备份再动
"$PY" "$TW" done <ID> # 打「已合入 <base>，跳过合并，直接清场」→ 先摘 .venv 与 simulator/SDL2 联接 → 删工作树 → 删分支 → unlink 台账
```
实测这条路径能走完（日志：`state backup -> ci-artifacts\screenlink-doc-history.json.state-bak` +
`[ok] 已摘除联接 .venv` + `[ok] 已摘除联接 simulator/SDL2`）。**若它仍拿「主工作树不干净」挡在合并前**（没走到
清场分支），改走 **E 节**的手工回收路径：台账仍按本步先 `cp` 成 `.state-bak`；第 1~2 步的前置换成
「`status --porcelain -uall` 为空 + 唯一提交为空 + `merge-base --is-ancestor` 判 MERGED」三条（本次实测三条齐），
第 3 步的联接预扫 + `rmdir` 摘联接**一步不能省**；再 `git worktree remove`（三条前置齐了就不必 `--force`）、
删分支、`git worktree prune`。清完再敲一次 `done` 会得到「任务 <ID> 不存在（缺台账 …json）」（exit 2）——
**这不是失败**（台账已被 unlink；判完成以 `git log` 为准，见 C 第 7 步）。
6. **复验收工**：`git -C "$MAIN" worktree list` 只剩主树 + **别人的树**（那棵不是你的，保留并在报告里点名，
别顺手回收 → E 节）；`"$PY" "$TW" lock status` 打 `build 空闲（TTL 1.0h）` + `bench 空闲（TTL 6.0h）` 才收工。
**并发会话证据必须写进报告**：主树里那份外部脏文件、中途冒出来的第二棵任务树，都要点名——是谁的、
你怎么定性的、对这次合并的影响（本例：与本合并无交集 / 不丢弃 / 不进本次提交），以及你**没动它**的证据
（blob id 前后一致）。「不能丢弃别人的工作」类问题九成是并发会话造成的，不写清就等于没取证。
.dsh/skills/task-worktree/reference/pitfalls.md
+134
View File
@@ -0,0 +1,134 @@
## 陷阱（实测）
- **`--force` 不是万能钥匙**：它只覆盖四类检查——并发上限、持有者与 `--task` 不符、陈旧锁接管、
清场时强制移除工作树。**台账缺失这类前置/环境错误（exit 2）跟它无关**（实测 `lock release
--force --bench-pass` 报的是同一句话，锁照旧没放）。同理 `abort --force` 也只覆盖「树里有东西」这一条拒绝，
**不会**替你做 E 节的内容保全——它只会删得更快。
- **未跟踪文件在 `git log`、提交门禁与 `done` 的合并里都不留痕**（2026-10-29 回收现场）：钩子按 HEAD tree 的
diff-index 取文件，未跟踪文件从没进过任何钩子的视野；`git log` 也照不出「唯一未合并」——它压根没被提交过。
所以「这棵树没有遗留改动」这种结论**只能**由 E 第 2 步的逐文件内容比对给出，`log --oneline -1` + 脏计数都不够。
- **`git status --porcelain` 不带 `-uall` 会折叠未跟踪目录**（E 第 1 步）：「全景」少一项、分桶少一个文件，
最后拆掉的是别人唯一的草稿。回收路径上**一律 `-uall`**。
- **`$TW list` 空 ≠ 没有工作树**：`list` 只遍历台账（A 第 1 步），用户说的「那 3 棵 done 掉」很可能在 `$TW list` 里
一个都不存在（实测就是）→ 别照 `$TW list` 的空结果回「没有任务」，先 `git worktree list` 拿全集再逐棵定性（E 节）。
2026-10-29 起 `list` 还会另起一段列出插件树（`.dsh-worktrees/`，F 节）——**"看见"不等于"归 `done` 管"**。
- **「这棵树很久没动」不是回收判据**：实测 `bench-*` 两棵既没台账也没脏文件、mtime 很旧，但真正决定去留的是
`git merge-base --is-ancestor <c> HEAD` = MERGED（提交已进主线）+ 未跟踪层为空；而另一棵 mtime 更新的树反而
全是已在主线的副本。**判据是内容与祖先关系，不是时间戳。**
- **「我记得没建过联接」不是安全判据**：判据只有扫出来的 `REPARSE: none`（E 第 3 步实测 `bench-*` 各挂一个 `.venv`
联接，正是「不是自己建的」那类）。
- **联接不是符号链接**：本仓库 `core.symlinks=false`，git 里的 symlink 会被检出成
「内容是目标路径的文本文件」。共享 `.venv` 只能用 Windows **目录联接**（`mklink /J`，
不需要管理员权限），且联接必须建在版本控制之外。
实测（2026-10-12）：用 ctypes 直调 `DeviceIoControl(FSCTL_SET_REPARSE_POINT)`
会被系统拒绝（Win32 4392），`mklink /J` 正常——所以脚本走后者，参数以列表交给
subprocess，含空格的路径（本项目 `DTU Code`）由 subprocess 自动加引号。
但**读属性**用 ctypes 没问题：`GetFileAttributesW` + `FILE_ATTRIBUTE_REPARSE_POINT` 就是 E 第 3 步的预扫手段。
- **联接建失败不中止 `new`**：只告警并打印手工补建命令，避免留下半成品任务空间；
但该任务里跑不了 `.venv\Scripts\python.exe`，`/keil-build` / `ci_local.py` 会找不到解释器。
- **`done` 前主工作树必须干净**：否则未提交改动会被卷进合并（补完基线再重跑 `done` 时最容易忘，见 C 第 6 步）。
- **⚠ 任务树里 `check_doc_links.py --all` 的红多半是 `simulator/SDL2` 目录联接的假红**：全库扫描会吞下那份
「仓库里的第二份仓库副本」（实测任务树 222 个文档 / 35 处问题全在联接下、RC=1，而主树同命令基线全绿）。
判红必须先过滤 `simulator/SDL2` 下的问题行、再与主树**同一条命令**的基线比对；正解是树内按单文件跑、
`--all` 基线合并后在主树跑 → **G 节**。
- **新建的任务树里没有 `ci-artifacts/`**（被 `.gitignore` 忽略 → 不被检出）：`> ci-artifacts/x.txt` 与
`fs.writeFileSync("<tree>/ci-artifacts/x", …)` 都会 `ENOENT`；`cd` 进树后再用 `../_wt/x.txt` 落到 `_wt/_wt/` →
`No such file or directory`（两起实测，第二次直接废掉一整轮体检）。落盘前先 `mkdir -p ci-artifacts`，
树内输出一律用树内相对路径 → **G 节**。
- **`done` 报「主工作树不干净」而那份脏改动不是你的**（别的并发会话 / 插件留下的，实测两次都是
`.dsh/skills/serial-boot-test/scripts/run_boot_test.py`）：**不许用 stash / 提交 / 删除去清场**（项目级 Never，
你也无从判断它写没写完）→ 走 **C2**：取证（mtime + diff + `hash-object` 存进 ci-artifacts）→ `merge-tree` 预演
→ 主树 `merge --no-ff -F` → 合并前后 blob id 与 `diff --stat` 对账。**「它看着像废弃的」不是丢弃判据**。
- **⚠ `done` 的门禁跑在 `/keil-build` 之前 → 依赖 `.map` 的钩子会误报**（2026-10-12 实测）：
`done` 的顺序是「合并 → 重生成 → **门禁（ci_local）** → `/keil-build`」，而
`mem-budget`（登记簿条目「缩堆迁 CCM 后半（暂缓）」）/ `mem-numbers` 是拿**文档快照 vs `.map`** 比对 —— 门禁跑时
`.map` 还是**主工作树合并前**的旧产物，与刚合并进来的新台账**必然不一致** →
误报 `[FAIL] 台账受管区与 .map 不一致`。`/keil-build` 跑完后 `.map` 才是新的。
**处置（2026-10-25 补全）**：按 C 节第 5 步的完整链补——`check_mem_numbers.py --write` →
`ram_baseline.py --write` → `ram_baseline.py --update` → `check_test_coverage.py --update-baseline` →
`check_doc_links.py --all` → 提交 → 重跑 `done`（它会检测到「已合入」直接清场）。
此时主干已含合并提交，**绝不能用提示里的 `reset --hard` 回退**。
- **`done` 的门禁 = `ci_local.py` = `pre-commit run --all-files`（50 条钩子全跑）**（2026-10-26）：红了先读
`[SUMMARY] static: pre-commit hooks -- passed=N failed=M skipped=K`，**按钩子 id 定根因**，别一律当「`.map` 滞后」
去跑补基线链。典型例外：`generated-fresh`（生成器幂等性，触发面 `tools/**`、`docs/images/*.svg`、UI 生成文件）——
合进来的分支改了生成器却没重跑产物时，补基线链救不了，处置是在**主工作树重跑那个生成器**、脚本与产物同一笔提交，
再重跑 `done`。另注意 `pre-commit run --all-files` 只跑 pre-commit stage，个别只在 commit-msg / 手工阶段跑的守卫不在此列
（口径见 `scripts/ci_local.py` 头部说明）。
- **⚠ 新建工作树从未构建过 → 体积类门禁必然红**（2026-10-25 实测）：`.map` 是每棵树各自的
构建产物、不入版本库，所以 `new` 出来的空间里 `mem-numbers` / `mem-budget` / `ci_local.py`
的体积门禁步都拿不到事实源，报 `[FAIL] 找不到 .map 事实源`（脚本提示已写明原因，不是代码缺陷）。
同理 `done` 的重生成步骤会 `[skip] 未找到 .map，跳过内存快照同步（需先 /keil-build）`。
**处置**：新空间第一次提交前先 `/keil-build` 一次（`build` 锁自动排队，与别的树串行）。与上一条
的区别要分清：上一条是「有 `.map` 但是旧的」，本条是「根本没有 `.map`」，处置动作不同。
- **⚠ 只改注释里的文档路径，也会把「体积同码凭证」刷红**（2026-10-30 实测，`done testdoc`）：
`scripts/check_size_gate.py` 的判据是**索引 blob 指纹**（实测 1466 个文件），**不是体积数字**——
那笔全库路径同步顺带改了 20 个 `.c/.h` 的注释，`Program Size` 逐项没变
（Code=246160 / RO-data=29816 / RW-data=2036 / ZI-data=149700），凭证照旧红：
`本次代码（指纹 172c6c78b8fb…，1466 文件）与体积测量（指纹 1ed4267c77f6…，2026-10-30T01:15:01）不同码`。
**处置比上一条那条补绿链短**：合并后 `done` 自己那次 `/keil-build` 已 0 错 0 警，此时只需
`ram_baseline.py --update` 重写凭证（改的是 `scripts/size_attestation.json`；同日同数字时
`ram_baseline.tsv` 连趋势行都不会新增），**别顺手 `--write` 去动内存受管快照**——数字没变就改受管区，
等于给别的在飞分支造冲突面（台账归属口径见 `mem-budget` skill）。
**判据顺序**：先比 `Program Size` 与合并前是否逐项相同 → 相同就只补凭证；不同才走 C 节第 5 步全链。
连带的第二个坑：`done` 对「分支已合入」的路径**在门禁之前就 return**（`cmd_done` 里
`already and ahead == 0` 那条分支直接清场），所以补完凭证重跑 `done` **不会替你复绿**——
落主干后的全量证据得自己跑：`scripts/ci_local.py`（实测 47 runner / 3896 断言全绿）
+ 主树 `check_doc_links.py --all`（实测 215 个文档 / 2993 处章节引用 rc=0）。
- **⚠ 增量构建可能不重链 → `.map` 数字瞬态不一致**（2026-10-12 实测）：
`/keil-build` 若判定无需重链，`.map` 保持旧值，此时 `--write` 生成的快照是**瞬态值**
（实测同一份源码两次读到 223,560 与 223,724，差 164 B）。**以主工作树（集成点）
的 `.map` 为准**；改完 RAM 相关代码后确认重链再刷新快照。
- **`ram_baseline.py` 的 help 串里有未转义的 `%`**（2026-10-25 实测：某些直调姿势会渲染 argparse help 并崩）——
查用法读脚本头部 docstring，别靠 `--help`；修脚本本身属 `mem-budget` skill 的范围。
- **合并冲突常落在「生成物」上**：`docs/内存管理/RAM使用分析与优化方案.md`（mem-numbers
快照）在双方都改过时必冲突，且**两边都不能直接选**（各自基于不同基线）——
正确做法是解冲突后用**合并后的实际构建**重新生成，不要挑一侧。
- **并集合并残留**：双方都改过的文件（尤其 `.gitignore`）会被 git 自动并成**并集**，
可能留下指向已删目录的死规则或重复条目。脚本会自动报「双方都改过」的文件清单 +
连续重复行；**权威判据是 base / 两个 tip 三方对比**（`git show <ref>:<file>` 逐项 `grep -F`），
别用 `tail -N` 目测。
- **⚠ 别用 heredoc 打补丁改门禁脚本造探针**（2026-10-27 实测三连败，白烧一整轮）：heredoc 里的 python
把门禁脚本改坏——`patched 3` 之后 `PROBE_RC=1`、`SyntaxError: unterminated string literal (detected at
line 882)`，而它**正是被测对象**，改完的数不可信；另一处 `replace('\', '/')`（想把 Windows 反斜杠换成正斜杠）里的反斜杠被多层引号吞掉
→ `SyntaxError (detected at line 16)`。**正解**：探针落成**独立 `.py` 文件**（写文件的工具，UTF-8 无 BOM）
再 `"$PY" probe.py`；非用 heredoc 不可就用单引号定界 `<<'PY'`（防变量展开），且**路径一律 `as_posix()`、
一个反斜杠都不写**——反斜杠字面量要穿「JS 模板串 → bash → shell 引号 → python」四层，必被吞。
E 节那两段扫描脚本同理：**落成 `ci-artifacts/*.py` 再跑**（该目录已被忽略，不会污染第 5 步复验用的脏行数）。
- **取门禁数字：import 门禁模块，别猜输出、别打补丁**（2026-10-27；grep 源码 / 手抄正则 / 解析 stdout 三种姿势
都拿不到可复核的数，换成这句立刻拿到）：先读门禁脚本的 `main()`（直读末尾那几十行）看它怎么装配检查器，
把**那几行照抄**进探针——`sys.path.insert(0, 'scripts')` → `import check_ids as ci` →
`ci.load_json(ci.REGISTRY_FILE, 'reg')` + `ci.load_json(ci.ALIASES_FILE, 'alias')` →
`ck = ci.Checker(reg, al, verbose=False)` → `ck.run()` → `print(ck.stats)`。别猜键名：先
`print(sorted(ck.stats))` 列出全量计数项，再按精确键取数（顺带 `git diff` 确认门禁脚本自己**没被改过**）。
- **别把「不可判定」当成一个数**（2026-10-27）：`id-check` 有两种口径——检查器自己算的**硬不可判定**实测只有
**2** 处，而门禁红线（`scripts/archive/id_gate/id_registry.json` 的 `undecidable_total_ceiling`）量的是**派生值**
`refs_total - decidable`（实测 8,744 - 7,582 = **1,162**，拆开 = `skip_bare_unmanaged` 834 +
`noise_allowed` 326 + 硬不可判定 2，**三数精确闭合**）。所以**带属主登记处的族（TC-XXX 这类）加多少引用都算
「可判定」、一点不吃这条余量**，真正吃余量的是**裸形字母+数字**字面量；反过来「把可判定引用改写成散文」才是
**稀释比值**的动作，那才是绝对数红线要防的。口径混用会当场给整条道下错指令（本次就下错过、量完立刻撤回）。
- **队友的自查结论要复核，小心它测的是错变量**（2026-10-27）：log 道做过受控实验、结论是「我们没推高这个数」——
他们改的是 TC 号、盯的是 `skip_bare_unmanaged`，那个组合当然不动；而 +16 走的是另一条路（新增裸形 「字母 T 累进数字 4」）。
定责用 D 节：逐文件注入 + HEAD/在飞两版同一计数器相减 + 对新增行 grep；闭合后 +16 = 16 处裸形 「字母 T 累进数字 4」，
**推翻**了自查结论。口头自查与 `--note` 都不是证据，**可复核的差分数字才是**。
- **`.workbuddy-ai/` 刻意不共享**：记忆不随任务分叉，也不给联接递归删除的机会。
任务工作树自己的记忆由 `done` / `abort` 在清场前归并回主工作树。⚠ **手工回收（E 节）没有这一步归并**：
拆之前顺手 `ls <tree>/.workbuddy-ai/` 看一眼，有内容就一并备份进 `ci-artifacts/wt-leftover-backup/`。
- **`--lean` 只省磁盘不省时间**：实测全量 smudge 7.25 s / 83 MB，跳过 smudge 7.05 s / 45 MB，
两者工作区都干净。默认走全量（参考图可用），磁盘紧张时才用 `--lean`。
- **锁不绑定进程存活**：`lock acquire` 本身是短命进程，而真正用资源的烧录/构建在别的进程里跑。
所以判「陈旧」只看**时效**（该锁的 TTL）加显式 `--force`；pid 仅作排障记录。
同任务重复 acquire 是幂等的（不会把自己锁死）。
- **TTL 按锁分设**（2026-10-12）：`build` = **1h**、`bench` = **6h**（`LOCK_TTL_HOURS`）。
口径是「兜底窗口应与操作真实时长同量级」——编译是秒~分钟级，6h 的兜底太钝；
bench 是会话级（flash→`/serial-boot-test`→探针），才配得上小时级。持有者还可用
`lock acquire ... --ttl <小时>` **自报**更精确的窗口（`keil_build.py` 即按其 `--timeout` 自报）。
- **陈旧锁自动接管**：超过该锁 TTL 未释放即视为陈旧，下次 `acquire` 会接管并提示；
未到 TTL 的活锁需 `--force`。`done` 的收口前置也会**自动释放陈旧锁**（不再硬失败），但
**未到 TTL 的活锁会把 `done` 挡在前置检查**（B 节第 8 步）。
- **`build` 锁不必手工持**（2026-10-12 起）：`/keil-build`（`keil_build.py`）**自持自释**——
进入 acquire、`finally` 无条件 release，所以"Agent 忘了 release、锁一直挂到 TTL"这条在构建路径上已消除。
`done` 的门禁自己持锁并给子进程设 `DTU_LOCK_HELD=build` 告知跳过（新旧脚本都兼容）。
**`bench` 锁仍须 Agent 手工持**（会话作用域：跨烧录→`/serial-boot-test`→探针，见 `keil-build` SKILL.md）。
- **⚠ `done --dry-run` 只保护预演段、不保护清场段**（2026-10-29 实测）：`done <ID> --dry-run --skip-build --skip-gates` 在「分支已合入主干」这条路上**照样执行清场**——摘 `.venv` / `simulator/SDL2` 联接、删分支、清台账，然后打「完成（分支此前已合入）」。想真·零改动就只跑不带 `--skip-gates` 的 `--dry-run` 并停在预演输出；用完一律 `git worktree list` 复验（判完成以 `git log` 为准，不是以有没有再敲一次 `done` 为准）。另：`--dry-run` 的前置检查同样要抢 `build` 锁——被别的任务占着时它会直接报「独占资源 build 仍被 X 占用，先 release」，此时加 `--skip-build` 或先 release，**别为了预演去抢别人的锁**。
- **⚠ 文件工具「先读后改」按解析后的绝对路径记账，切树后要重新读**（2026-10-30 实测，屏板链路任务树）：开新树后先用**相对路径**读过一批文件（读历史记到当时解析到的主树文件上），再进任务树直接 `edit` → 6 条并行编辑全被 `file has not been read — read the file, then retry` 拒。判据：**树内改动一律用树内绝对路径，先 read 再改**——读历史不跨路径复用，工具不做「同名相对路径」宽容。
- **⚠ 中文门禁输出回显乱码 ≠ 路径坏**（2026-10-30 实测）：对含中文文件名的文档跑 `check_doc_links.py`，终端回显整段乱码，但 **rc 与判定计数全部正确**。只认 `[SUMMARY]` 行与退出码，别误诊成「文档丢失」；脚本化批量调用走 python subprocess + 显式 `encoding`，别经命令行中转中文名。
.dsh/skills/task-worktree/reference/reclaim-unregistered.md
+203
View File
@@ -0,0 +1,203 @@
### E. 回收**非登记**工作树（`$TW list` 为空 / detached HEAD / 树里有在飞或未跟踪内容）
**这类树的判定特征**（命中任意一条就适用本节）：`git worktree list` 里有它、但 `_wt/.state/<ID>.json` 台账不存在；
HEAD 是 detached（`git rev-parse --abbrev-ref HEAD` 打 `HEAD`）；或树里的改动不属于本会话（别的会话留下的未提交 /
未跟踪文件）。典型来源：D 节的 `--detach` 净室、`new` 之后被手工删目录只剩台账的残骸、别人手工 `git worktree add` 建的分析树
（2026-10-28 实测一次回收 3 棵：`verify-task16` / `verify-batch` / `und-attr`，各 89 MB，全部无台账 + detached）。
**为什么 `done` / `abort` 在这里整体不适用**（铁律 9）：两条子命令的前置都是 `load_state()`，无台账 →
`前置/环境错误：任务 <ID> 不存在（缺台账 …json）`（exit 2）当场停住、什么也不会发生；而**假如有**一份残留台账，
`abort --force` 会拿台账的 `path` 直接 `git worktree remove` —— **绕过下面第 1~4 步的全部内容保全**，把别的会话的唯一版本一次删光；
`done` 则会去找那条（多半已不存在的）`task/` 分支做合并。另：本路径没有「合并」这一步，所以 `done` 的并集合并残留审计
在这里不发生，也没有三方对比可依据 —— **唯一性只由第 2 步的内容分桶给出**。回收只能手工走本节第 1~5 步 + 第 6 步清台账。
1. **建全景（全程只读）**：先看 `git worktree list` 的全集，再**逐棵**记三件事（脏行数含未跟踪 / 树顶提交 / 有无分支）
加一条台账判定，同时存下主树的拆前基线清单：
```bash
MAIN="D:/Code/DTU Code/STM32F4-Base"; WTROOT="$MAIN/../_wt"
git -c core.quotePath=false worktree list # 全集：登记树 + 非登记树都在这份里
MAIN_SHA=$(git -C "$MAIN" rev-parse --short HEAD) # 下面所有比对都以这一版为主线尺子
mkdir -p ci-artifacts
git -C "$MAIN" status --porcelain -uall > ci-artifacts/wt-main-before.txt # 拆前主树基线（第 5 步逐行比）
wc -l < ci-artifacts/wt-main-before.txt # 记下行数（实测 0）
for t in "$WTROOT"/*/; do
echo "--- $t"
git -c core.quotePath=false -C "$t" status --porcelain -uall | wc -l # 脏 + 未跟踪行数
git -c core.quotePath=false -C "$t" log --oneline -1 # 树顶提交
git -C "$t" rev-parse --abbrev-ref HEAD # 打 HEAD = detached，压根没分支可 done
ls "$WTROOT/.state/$(basename "$t").json" 2>/dev/null || echo "NO-LEDGER" # 台账位置随 DTU_WT_ROOT
done
```
- **`-uall` 不是可选**：默认 `status --porcelain` 会把未跟踪目录折叠成一行 `dir/`，`-uall` 才展开到文件级；少了它
第 2 步的分桶就漏项（实测 `und-attr` 唯一那份就是未跟踪 `?? scripts/check_nested_comment.py`）。
- 路径含空格（本项目 `DTU Code`）→ 变量整体加引号；`core.quotePath=false` 让中文路径原样输出，便于逐行核对。
- 判定「是不是登记树」看两样：**台账在不在 + HEAD 是否 detached**。两者都指「非登记」→ 从这里开始**禁止**
`done` / `abort`（见本节开头），继续第 2 步。
2. **逐文件与主线 HEAD 比内容并分三桶**：`IN-MAINLINE`（内容等价，拆 = 零损失）/ `UNIQUE-UNMERGED`（主线没有这份
内容，拆 = 丢）/ `OLDER-DRAFT`（同路径主线已有更新版本）。落成独立只读探针跑（别用 heredoc 现写现改，
见陷阱「别用 heredoc 打补丁造探针」）：
```python
# ci-artifacts/wt_bucket_scan.py — 只读：逐文件与主线工作区/HEAD 比对，三桶归类
import os, subprocess, tempfile
MAIN = r"D:\Code\DTU Code\STM32F4-Base"
WTROOT = os.path.join(os.path.dirname(MAIN), "_wt")
TREES = ["verify-task16", "verify-batch", "und-attr"] # ← 第 1 步全景里挑出的非登记树
SKIP_TOP = {".venv", "MDK-ARM", ".git", "ci-artifacts"} # 联接 / 构建产物 / 忽略区，按项目调
def git(*a):
return subprocess.run(("git", "-c", "core.quotePath=false", "-C", MAIN) + a,
capture_output=True, text=True, errors="replace")
def bucket(rel, tree):
p = os.path.join(tree, rel)
if not os.path.exists(p):
return "OTHER", "工作树里已不存在（多为已 staged 删除）"
tf = tempfile.NamedTemporaryFile(delete=False)
tf.write(open(p, "rb").read()); tf.close()
# 1) 与主线工作区（= 当前 HEAD 的检出内容）逐字节比
if git("diff", "--no-index", "--quiet", tf.name, rel).returncode == 0:
os.unlink(tf.name); return "IN-MAINLINE", "与主线 HEAD 逐字节相同"
# 2) 与主线历史各版比：内容等价于某个旧 commit → 只是主线又往前走了
hist = [x.strip() for x in git("log", "--format=%H", "HEAD", "--", rel).stdout.splitlines()]
for sha in hist[1:]:
old = git("show", f"{sha}:{rel}")
if old.returncode == 0 and old.stdout == open(p, encoding="utf-8", errors="replace").read():
os.unlink(tf.name); return "IN-MAINLINE", f"内容等价于主线历史版 {sha[:8]}"
# 3) 主线从没这条路径 → 唯一；否则同路径主线有更新版 → 更旧草稿（再用 blob diff 定性方向）
os.unlink(tf.name)
if not hist:
return "UNIQUE-UNMERGED", "主线 HEAD 与历史都没有此路径"
return "OLDER-DRAFT", "同路径主线有更新版本（用 diff --stat <HEAD> -- <f> 定性）"
for name in TREES:
tree = os.path.join(WTROOT, name)
lines = subprocess.run(("git", "-c", "core.quotePath=false", "-C", tree,
"status", "--porcelain", "-uall"),
capture_output=True, text=True, errors="replace").stdout.splitlines()
tally = {}
for line in lines:
rel = line[3:].split(" -> ")[-1].strip('"') # 兼容 ?? / M / A / R 的箭头形态
if rel.split("/")[0] in SKIP_TOP:
continue
b, why = bucket(rel, tree)
tally.setdefault(b, []).append((rel, why))
g = lambda k: len(tally.get(k, []))
print(f"== {name}: IN-MAINLINE={g('IN-MAINLINE')} UNIQUE-UNMERGED={g('UNIQUE-UNMERGED')} "
f"OLDER-DRAFT={g('OLDER-DRAFT')} OTHER={g('OTHER')}")
for b in ("UNIQUE-UNMERGED", "OLDER-DRAFT", "OTHER"):
for rel, why in tally.get(b, []):
print(f" {b}: {rel} # {why}")
```
报告里必须**逐桶给计数 + 判定证据**（实测：`verify-task16` IN-MAINLINE=6 / UNIQUE=0；`verify-batch` IN-MAINLINE=35 /
UNIQUE=1；`und-attr` IN-MAINLINE=0 / UNIQUE=1）。两个非空桶再各钉一条命令把证据坐实：
```bash
# 「唯一未合并」是真更新还是更旧草稿？blob 级 diff + 逐行看方向
git -c core.quotePath=false -C "$MAIN" diff --stat "$MAIN_SHA" -- simulator/tests/README.md
diff <(git -C "$MAIN" show "$MAIN_SHA":simulator/tests/README.md) "$WTROOT/verify-batch/simulator/tests/README.md"
# 「树顶提交要不要保」只看一件事：是否已并入 HEAD。别拿「目录很久没动」当判据
for c in 77779d49 1d4b6a17; do
git -C "$MAIN" merge-base --is-ancestor "$c" HEAD && echo "$c MERGED" || echo "$c NOT-merged"
done
```
实测：那份 `simulator/tests/README.md` 树内写「27 页 × 3200 B」、主线 HEAD 已是「60 张 × 3200 B」→ **更旧草稿**（被取代的
早先版本），不是未合并成果；`bench-21-77779d49` / `bench-23-1d4b6a17` 两棵 `merge-base --is-ancestor` 判 **MERGED** 且脏数 = 0
→ **保留不动**（不属本节，等属主自己收，报告里点名说清为什么留）。
**回收判据不是「看着旧」**：唯一内容如果没被提交过，`git log` 里根本看不见它；反过来「提交已 MERGED」也不等于可以拆——
还得看未跟踪那一层。`UNIQUE-UNMERGED` 非空又确实要留 → 它进第 4 步的备份，**不许靠 `--force` 顺手带走**。
3. **拆前扫联接 / reparse point（物理安全性 = 铁律 5 的可执行判据）**。存成 `ci-artifacts/wt_junction_scan.py` 再跑：
```python
# 只读预扫：一个路径是不是 reparse point（Windows 目录联接在这里现形）；发现即停止深入，绝不 walk 进联接
import os, ctypes
FILE_ATTRIBUTE_REPARSE_POINT = 0x400
GA = ctypes.windll.kernel32.GetFileAttributesW
def is_reparse(p):
a = GA(p)
return a != -1 and bool(a & FILE_ATTRIBUTE_REPARSE_POINT)
for name in ["verify-task16", "verify-batch", "und-attr", "bench-21-77779d49", "bench-23-1d4b6a17"]:
top = os.path.join(r"D:\Code\DTU Code\_wt", name)
hits, entries = [], 0
for root, ds, fs in os.walk(top):
bad = [d for d in ds if is_reparse(os.path.join(root, d))]
if bad:
hits += [os.path.join(root, d) + "/" for d in bad]
ds[:] = [] # 有联接就不再深入：防转进主树 .venv 把别人整棵树数一遍
hits += [os.path.join(root, f) for f in fs if is_reparse(os.path.join(root, f))]
entries += len(ds) + len(fs)
print(f"== {name} scanned entries={entries}")
print(" REPARSE: none → 可直接 git worktree remove --force"
if not hits else " REPARSE:\n " + "
".join(hits))
```
实测输出 `== verify-task16 ... REPARSE: none`（每棵的体积 / 条目数 + 零联接就是证据），而 `bench-*` 两棵各挂一个 `.venv`
联接 → 判 **KEEP**（本节不拆它们；将来真要拆，先 `rmdir` 摘掉联接再 remove）。
**判据是「扫出来一个都没有」，不是「我记得没建过联接」**：`new --no-bootstrap` 的树、别的手工 `mklink /J` 的树都可能带着指向主树的联接。
摘联接用 `rmdir`（只删联接本身；**不是** `rd /s`，更不是 `rm -rf`——那会顺着联接删目标）。
非 Windows 环境改用 `os.path.islink` / `find <tree> -type l`（本项目是 Windows + Keil 工具链，按上面这条走）。
**到这里才算「拆前唯一性自检 + 物理安全预扫」齐**：`--force` 的安全前提 = 第 2 步 `UNIQUE-UNMERGED` 为 0
（或剩下的已全部进第 4 步备份）**且**这里 `REPARSE: none`。
4. **唯一内容先备份，再 `--force` 拆**。`UNIQUE-UNMERGED` 与需要留档的 `OLDER-DRAFT` 一律先备份进主树
`ci-artifacts/wt-leftover-backup/`（`ci-artifacts/` 已被 `.gitignore` 忽略 → **备份不会改变主树脏行数**；仓库根不放一次性产物），
**文件名 + 字节数必须打进输出**当证据：
```bash
BK="$MAIN/ci-artifacts/wt-leftover-backup"; mkdir -p "$BK"
# 命名约定：<树名>__<原路径里的 / 换成 _>，反向可定位；台账备份统一后缀 .state-bak
cp "$WTROOT/verify-batch/simulator/tests/README.md" "$BK/verify-batch__simulator_tests_README.md"
cp "$WTROOT/und-attr/scripts/check_nested_comment.py" "$BK/und-attr__scripts_check_nested_comment.py"
ls -l "$BK" # 实测：verify-batch__simulator_tests_README.md 1769 bytes / und-attr__scripts_check_nested_comment.py 14827 bytes
for t in verify-task16 verify-batch und-attr; do
git -C "$MAIN" worktree remove --force "$WTROOT/$t"; echo "$t remove_rc=$?" # 不接管道才读得到码（见「读输出」）
done
git -C "$MAIN" worktree prune # 顺带清 .git/worktrees 里的残籍
```
自检：**备份条目数 = 第 2 步里判「要留档」的条目数**，且每个都带字节数。这一步就是本节相对 D 第 4 步的增量——
D 的前提是「净室里只有自己的拷贝」，本节的树里混着别人在飞的东西，`--force` 是一次不可逆删除，**先备份才谈得上安全**。
5. **复验：主树一个字节没动 + 树确实没了**：
```bash
git -C "$MAIN" status --porcelain -uall > ci-artifacts/wt-main-after.txt
wc -l < ci-artifacts/wt-main-before.txt; wc -l < ci-artifacts/wt-main-after.txt # 两个数必须相同（实测 0 → 0）
diff ci-artifacts/wt-main-before.txt ci-artifacts/wt-main-after.txt # 空输出 = 逐行一致
git -c core.quotePath=false -C "$MAIN" worktree list # 已拆路径逐条消失；主树与判「保留」的树原样在列
```
行数不同 = 备份或摘除碰到了主线（多半是备份写进了未被忽略的目录，或漏摘联接）→ 立刻定位，别报「回收完成」。
第 2 步判「保留不动」的树还在 `worktree list` 里是**预期结果**，在报告里点名解释为什么留（附 `MERGED` 判据）。
6. **顺手清悬挂台账**（branch / path 都已不存在的 `_wt/.state/<ID>.json`；它会让 `$TW list` 打出一行怪条目、并让下次
`new` 同 ID 报「任务 <ID> 已存在」）。先给证据、后动手：
```bash
for j in "$WTROOT"/.state/*.json; do # 台账位置随 DTU_WT_ROOT
id=$(basename "$j" .json)
br=$("$PY" -c "import json,sys;print(json.load(open(sys.argv[1],encoding='utf-8')).get('branch',''))" "$j")
pp=$("$PY" -c "import json,sys;print(json.load(open(sys.argv[1],encoding='utf-8')).get('path',''))" "$j")
git -C "$MAIN" rev-parse --verify "$br" >/dev/null 2>&1 && b=branch-OK || b=branch-MISSING
[ -d "$pp" ] && p=path-OK || p=path-MISSING
echo "$id $b $p <- $j"
done
```
实测这条判据打出的正是 `v5tool2 branch-MISSING path-MISSING`：`git rev-parse task/v5tool2-v11` 报
`fatal: ambiguous argument 'task/v5tool2-v11': unknown revision ...`，台账 `path` 指的目录已无，`git worktree list` 里也没有这棵树。
**三条齐（rev-parse fatal + path 目录不存在 + worktree list 无此树）才叫悬挂**；缺任何一条都回到第 1~2 步查是不是真有东西要保。
然后**备份 → 删 → 复跑两条 list 复验**：
```bash
cp "$WTROOT/.state/v5tool2.json" "$BK/v5tool2.json.state-bak" && rm "$WTROOT/.state/v5tool2.json"
"$PY" "$TW" list # 该条目消失（全空时打「（没有任务空间。用 new <ID> <slug> 建一个）」），echo RC=$? 应为 0
"$PY" "$TW" lock status # build 空闲（TTL 1.0h）/ bench 空闲（TTL 6.0h）—— 证明清台账没牵连两把锁
ls "$WTROOT"/.state/locks/ 2>/dev/null # 若该 ID 名下还有 .lock，先按 B 节释放，再删台账
```
- **必须 `cp` 先备份再 `rm`**：台账里存着 base / junctions / needs_bench / bench_pass，是真出纠纷时唯一的现场记录。
- 悬挂条目按定义 `path` 已不存在 → 通常**不占** `MAX_CONCURRENT = 8` 名额（A 第 1 步的「活跃」判据要求 path 目录还在），
但它把 `$TW list` 搅成怪输出、并永久挡住同 ID 复用；**path 还在的占位/残留台账才占名额**（早期为绕 B 节那个坑手写的占位台账就是这种）。两种都要清。
- **仍不对这个 ID 跑 `done` / `abort`**：清场会拿台账里的死 `path` / 死 `branch` 去做 `git worktree remove` 和删分支
（这正是 A 第 5 步说的「手工删目录留下的尾巴」，正解就是本步）。历史遗留的占位台账同理——活着时也别
`done` / `abort`，用完直接删文件（来历与现状见 B 末条）。
.dsh/skills/task-worktree/reference/verification.md
+44
View File
@@ -0,0 +1,44 @@
## 验证
- `$TW list`：台账段条目数 = `ls _wt` 的目录数且 ≤ 8（`MAX_CONCURRENT`）；刚回收的任务与历史占位条目都不再出现
（插件树另起一段，不参与这条计数）。
- `$TW lock status`：`build 空闲（TTL 1.0h）` + `bench 空闲（TTL 6.0h）`——没有本会话留下的持有者。
- `git log --oneline -3`：能看到 `merge: task/<ID>-<slug> 合入 <base>` 与其后的补基线提交；
`git status --porcelain` 为空（补链改动已提交，才谈得上重跑 `done`）。
- `ls _wt/.state/`：该 ID 的台账已无（清场最后一步 unlink）；重复 `done` 报「任务不存在」不必再追。
- **E 节回收**：`git worktree list` 只剩主树 + 判「保留不动」的树（已拆路径逐条消失）；**拆前/拆后主树
`git status --porcelain -uall` 行数相同且 `diff` 为空**（实测 0 → 0）；`ci-artifacts/wt-leftover-backup/` 里每个留档件都打印过
文件名与字节数、条目数 = 分桶判「要留档」的条目数；每棵被拆的树都留有 `REPARSE: none` 预扫记录；全景输出里
`UNIQUE-UNMERGED` 归零（或全部已备份）；保留树在报告里点名给出判据（`merge-base --is-ancestor` = MERGED）。
- **E 第 6 步清悬挂台账**：该 json 已从 `_wt/.state/` 消失（`.state-bak` 在备份目录里）、`$TW list` 不再打出它、
`$TW lock status` 两把锁仍空闲；全程未对该 ID 跑 `done` / `abort`。
- **F 节桥接**：`plugin list` 的「联接」列按实际三态点名（`已联` / `缺 .venv` / `缺 SDL2` /
`齐(实体SDL2)`——旧实现只取样 `.venv`，半联树会说谎）；**adopt/unadopt 前后主树 `.venv` 与树内文件都
还在**；主线缺 SDL2 时 `adopt` 打 `[skip]` + 「还不能算就绪」而不打「现在可以跑」；`plugin adopt ".."`
必须 exit 2；打印的 `pw:<name>` 与 `keil_build.py` 从 cwd 反推的名字逐字相同；`done <插件树名>` 只 exit 2。
- **C2 主树被别的会话弄脏时的手工合并**：合并前打印过 `git merge-tree --write-tree` 的结果树 sha 且 `MT_RC=0`；
合并用 `git merge --no-ff --no-edit -F ci-artifacts/merge-msg-<slug>.txt`（UTF-8 无 BOM）并写明绕开 `done` 的理由；
外部文件合并前后的 `git hash-object` **逐字符相同**、`git diff --stat` 同一组数字、`status` 里仍是 `M`
（没被提交也没被清掉；实测同为 `369380ca…`、2+/2−）；台账先 `cp` 成 `<ID>.json.state-bak` 再由 `$TW done`
（或 E 节手工路径）摘联接拆树；收工前 `git worktree list` 只剩主树 + 别人的在飞树（点名保留）、
`$TW lock status` 两把锁均空闲（`build 空闲（TTL 1.0h）` / `bench 空闲（TTL 6.0h）`）。
- **G 节树内门禁**：`<tree>/ci-artifacts/` 先 `mkdir -p` 再写、事后 `ls` 得到真实文件（`cat` 读得到内容）；
树内 `check_doc_links.py` 按**单文件**跑并打印「N 处 / 机器可判定百分比 / rc」（实测 161 处/98%/rc=0、16 处/88%/rc=0）；
全库 `--all` 只在合并后的**主树**跑（实测 2,597 处 / 194 个文档 / rc=0）；若树内跑过 `--all` 且判红，报告里
必须给得出「过滤 `simulator/SDL2` 后与主树同命令基线对比」这一步。
- D 节归因：测量前后 `git -C "$MAIN" status --porcelain` **逐行一致**（主树全程只读）；
`git worktree list` 里净室路径已消失；逐文件增量之和 **等于**观察到的涨幅（实测 +6+8+2 = +16），且每处增量
都指到具体字面量类别（裸形 「字母 T 累进数字 4」）与属主；取数走 `import check_ids` 读 `ck.stats`，且门禁脚本自身 `git diff` 为空。
- 补绿链的每一条都自己 `echo RC=$?` 看到 0，最后以重跑 `done` 打出的**清场日志**（`已摘除联接` /
`已删除分支` / `完成（分支此前已合入）`）为成功判据，而不是 `tail` 出来的最后一行。
- **树内提交 / 合并信息（G 节）**：`git log -1 --pretty=%B | grep -c '<被清退主题关键词>'` 打出 **0**（标题 + 正文 +
合并信息三处都查过）；消息文件在 `ci-artifacts/`、UTF-8 无 BOM、CR=0、标题 ≤100、正文最长行 ≤80（实测 31/50、32/55）；
自审发现消息统计算错是在**未推送**状态下 `--amend -F` 修掉的，历史里没有「更正」提交。
- **文档改动体检（G 节）**：提交前打印过 `lines/bytes/BOM/CR/U+FFFD/三连续空行/行尾空格/末行 LF` 与表格列数一致性，
并区分「本次改动引入 = 0」与「文件里既有的坏行」（实测两处历史坏表格与本次无关，只在报告里点名）。
- **F 节分级与自持理由**：判 `simulator/SDL2` 为硬需求要给出 `simulator/CMakeLists.txt:12`（非 CACHE）+ 派生路径行号
（:34/:70/:71/:180/:207）；判 `.venv` 为软需求要给出 `DTU_PRECOMMIT_PYTHON` 与 `ci_local.py` 五级解释器候选顺序；
答「为什么不用插件」时报出插件包版本、文件与三个概念的 grep 命中数，并说明重叠只在 `git worktree add` 的开/收两个动作。
- **改并行上限数字**：唯一事实源 = `task_worktree.py` 的 `MAX_CONCURRENT`（报错文案与 `new` 提示都 `.format()` 插值它，
实测 `:764-766` / `:768-771`），其余全是引用同步；隔离小仓验证到「8 棵成功、第 9 棵不带 `--force` 被拒」，
且没在真仓 `../_wt` 及其 `.state/` 留下验证树。
.dsh/skills/task-worktree/scripts/task_worktree.py
+383 -15
View File
@@ -27,12 +27,12 @@ for _stream in (sys.stdout, sys.stderr):
EXIT_OK, EXIT_FAIL, EXIT_ENV, EXIT_USAGE = 0, 1, 2, 3
BRANCH_PREFIX = "task/"
MAX_CONCURRENT = 3
MAX_CONCURRENT = 8
LOCK_NAMES = ("build", "bench")
# 按锁分设陈旧窗口（小时）——兜底窗口应与「操作真实时长」同量级：
# build：编译是秒~分钟级（keil_build.py 自持自释，持有窗口 ≈ UV4 运行时长，
# 上限 = --timeout，默认 600s）；崩溃泄漏时应在数十分钟内即可接管 → 1h。
# bench：会话级（flash → @test → 探针，天然几十分钟~数小时）→ 保留 6h。
# bench：会话级（flash → /serial-boot-test → 探针，天然几十分钟~数小时）→ 保留 6h。
# 另：锁 payload 里持有者可用 `ttl` 字段自报窗口（见 lock_acquire(ttl=...)），
# 优先于这里的默认值——这样 build 锁的窗口能自动跟随其 --timeout。
LOCK_TTL_HOURS = {"build": 1.0, "bench": 6.0}
@@ -82,6 +82,15 @@ BASE_BRANCH = os.environ.get("DTU_TASK_BASE", "v2-on-ui")
STATE_DIR = WT_ROOT / ".state"
LOCKS_DIR = STATE_DIR / "locks"
# DSH 的 worktree 插件（包名 dsh-task-worktree；模型工具 worktree_create、人类命令
# /worktree）把任务树建在**仓库内**这个命名空间下，与本 skill 的仓外 _wt/ 刻意分开。
# .gitignore 里预置同名规则，正是为了让插件的 ensureIgnored() 见到就跳过、
# 不在会话中途往这份受控文件里追加一行。
PLUGIN_ROOT = REPO_ROOT / ".dsh-worktrees"
PLUGIN_NAMESPACE = "worktree" # 插件侧 WORKTREE_NAMESPACE：name 即分支尾段
PLUGIN_SUBDIR = PLUGIN_ROOT / PLUGIN_NAMESPACE
PLUGIN_LOCK_PREFIX = "pw" # 插件树在锁 payload 里的持有者前缀
# --------------------------------------------------------------------- 基础工具
@@ -390,33 +399,232 @@ def bootstrap(wt: Path):
return made
# --------------------------------------------------------------------- DSH 插件工作树
#
# 插件建的树（.dsh-worktrees/worktree/<name>）缺三样东西，下面的命令逐条补。
# 回收**不在这里**：插件树由「/worktree remove|prune」收，done/abort 也不该拿去处理它。
# 1. 共享联接——没有 .venv 与 simulator 的 SDL2 SDK，插件树里「.venv\Scripts\python.exe」
# 直接找不到解释器：/keil-build、ci_local.py、所有 scripts/check_*.py 全部起跑失败；
# 2. 可见性——插件树不在台账里，「list」看不见它，8 个活跃名额也只数登记任务；
# 3. 独占资源归属——build 锁由 keil_build.py 自持自释（按 cwd 反推持有者名，
# 插件树里算成 pw:<name>），bench 锁仍要人占，占锁名得和「lock status」对得上。
def plugin_lock_owner(name: str) -> str:
"""插件树在锁 payload 里的持有者名：pw:<name>（多段名压平成 -）。
必须与 keil_build.py 的 default_lock_task() 对同一种树算出的名字一致——这样构建
自持自释留下的归属，和手工「lock acquire bench --task pw:x」才是同一个可 grep 的标识。
"""
# 与 plugin_dir_for 同样容忍「worktree/」前缀，否则同一棵树会出现两个持有者名
# （pw:refactor-logging vs pw:worktree-refactor-logging），lock status 就散了。
segs = [s for s in name.replace(os.sep, "/").strip("/").split("/") if s]
if segs and segs[0] == PLUGIN_NAMESPACE:
segs = segs[1:]
return "{}:{}".format(PLUGIN_LOCK_PREFIX, "-".join(segs) or "?")
def plugin_dir_for(name: str) -> Path:
"""插件 worktree 名 → 树目录；**只允许落在 .dsh-worktrees/worktree/ 里面**。
adopt/unadopt 会在解析出的目录上建/摘目录联接；不加这道闸，等于允许把主工作树或
任意 _wt 目录当插件树动手（联接会遮蔽真实内容，事后很难看出来）。
"""
raw = (name or "").strip().replace(os.sep, "/").strip("/")
if not raw:
raise EnvError("缺插件 worktree 名（先跑「plugin list」看现有树）")
if raw == PLUGIN_NAMESPACE or raw.startswith(PLUGIN_NAMESPACE + "/"):
raw = raw[len(PLUGIN_NAMESPACE):].strip("/")
p = (PLUGIN_SUBDIR / raw).resolve()
base = PLUGIN_SUBDIR.resolve()
if p == base or base not in p.parents:
raise EnvError("拒绝 {}：只接受 {} 里面的树".format(p, PLUGIN_SUBDIR))
return p
def junction_states(wt: Path):
"""每个共享联接的三态：link（目录联接）/ real（实体内容）/ absent（真缺）。
这是「联没联上」的**唯一**判定处——列表显示与 adopt 收尾都读它。早先列表只取样
JUNCTION_SPECS 的第一项，于是「有 .venv、缺 simulator/SDL2」的半联树被报成已联，
而 adopt 可以只成功一条（主线缺 SDL2 走 skip、联接失败走 warn）→ 说谎的正是这一列。
"""
st = {}
for rel, _desc in JUNCTION_SPECS:
link = wt / rel
if is_reparse(link):
st[rel] = "link"
elif os.path.lexists(str(link)):
st[rel] = "real"
else:
st[rel] = "absent"
return st
def junction_label(st) -> str:
"""把三态压成一列短标签：缺什么都点名，实体内容也算「齐」但不算共享。"""
tag = {rel: rel.rsplit("/", 1)[-1] for rel in st}
absent = [tag[r] for r, s in st.items() if s == "absent"]
real = [tag[r] for r, s in st.items() if s == "real"]
if absent:
return "缺 " + "+".join(absent)
return "齐(实体" + "+".join(real) + ")" if real else "已联"
def plugin_trees():
""".dsh-worktrees/worktree/ 下的工作树（事实源 = git worktree list，不读插件 manifest）。
manifest.json 是插件私有格式（MANIFEST_VERSION 1，字段随版本变），而 git 的注册表
同时覆盖「插件正常建的树」和「manifest 丢了 / 树被手工删」的残留——桥接命令要看的
是真实存在的东西。
"""
try:
base = PLUGIN_SUBDIR.resolve()
except OSError:
return []
trees = []
for ent in worktree_entries():
p = ent["path"]
try:
rp = p.resolve()
except OSError:
continue
if rp == base or base not in rp.parents:
continue
dirty = (len(git_out("status", "--porcelain", cwd=p, check=False).splitlines())
if p.is_dir() else -1)
trees.append({
"name": rp.relative_to(base).as_posix(),
"path": str(p),
"branch": ent.get("branch") or "(detached)",
"dirty": dirty,
"jn": junction_states(p),
})
return trees
def print_plugin_trees() -> int:
"""打印插件树一览（无树则静默），返回数量——「list」与「new」共用同一事实。"""
trees = plugin_trees()
if not trees:
return 0
print()
print("DSH 插件工作树（{} 下；**不在本 skill 台账** → 不占 {} 个名额、done/abort "
"管不到，回收走 /worktree remove|prune）：".format(PLUGIN_SUBDIR, MAX_CONCURRENT))
print("{:<26} {:<34} {:>4} {:>16}".format("名称", "分支", "脏", "联接"))
for t in trees:
print("{:<26} {:<34} {:>4} {:>16}".format(
t["name"], t["branch"], "-" if t["dirty"] < 0 else str(t["dirty"]),
junction_label(t["jn"])))
def miss(rel):
return any(t["jn"].get(rel) == "absent" for t in trees)
if miss(".venv"):
print(" 缺 .venv：进去跑 /keil-build / ci_local.py 会**静默**落到机器级解释器（无 "
"fontTools，generated-fresh 假红的老根因）")
if miss("simulator/SDL2"):
print(" 缺 simulator/SDL2：模拟器 build_sim.bat 直接报错——CMakeLists.txt 的 "
"SDL2_DIR 是裸 set，没有环境变量逃生口")
if miss(".venv") or miss("simulator/SDL2"):
print(" 补法：「plugin adopt <name>」——只建缺失的联接，不碰树里任何文件")
return len(trees)
def adopt_junctions(wt: Path):
"""只补**缺失**的共享联接（已联的跳过、实体目录绝不碰），返回 (已有, 本次新建)。"""
already, made = [], []
st = junction_states(wt)
for rel, desc in JUNCTION_SPECS:
link = wt / rel
if st[rel] == "link":
already.append(rel)
continue
if st[rel] == "real":
print("[warn] {} 已是实体目录/文件（不是联接）——不动它".format(rel))
already.append(rel)
continue
target = REPO_ROOT / rel
if not target.exists():
print("[skip] {}（{}）主线里不存在，跳过".format(rel, desc))
continue
try:
make_junction(link, target)
except (Fail, EnvError) as err:
print("[WARN] {} 联接失败：{}".format(rel, err))
continue
made.append(rel)
print("[ok] 联接 {} -> {}".format(rel, target))
return already, made
def cmd_plugin(a) -> int:
if a.action == "list":
if print_plugin_trees() == 0:
print("（{} 下没有插件工作树）".format(PLUGIN_SUBDIR))
print(" 建法：新会话输入框选「Worktree模式」/ 让模型调 worktree_create / "
"/worktree create <name>")
print(" 建完回来「plugin adopt <name>」补共享联接，才能在里面跑 /keil-build 与门禁。")
return EXIT_OK
wt = plugin_dir_for(a.name)
if not wt.is_dir():
raise EnvError("目录不存在：{}（先用插件建树：/worktree create 或 worktree_create）".format(wt))
if a.action == "adopt":
if git("rev-parse", "--git-dir", cwd=wt, check=False).returncode != 0:
raise EnvError("{} 不是 git 工作树（别拿普通目录当插件树）".format(wt))
print("为插件树补共享联接：{}".format(wt))
already, made = adopt_junctions(wt)
owner = plugin_lock_owner(a.name)
# 复算一次：adopt 里 skip/warn/失败都不算成功，「已有 N + 新建 M」两两相加可能对不上
# 总数——就绪判定只能按**现在的实际状态**说，否则又是把没联上的说成联上了
still = [r for r, s in junction_states(wt).items() if s == "absent"]
print()
print("[ok] 联接：已有 {} 个、本次新建 {} 个".format(len(already), len(made)))
if still:
print("[warn] 仍缺 {}：主线里该路径不存在或联接失败——先补主线再复跑 adopt"
"（这棵树还不能算就绪）".format("、".join(still)))
else:
print("该目录现在可以跑 /keil-build / ci_local.py / /serial-boot-test")
print("build 锁由 keil_build.py 自持自释，持有者名就是 {}".format(owner))
print("上台架前：$TW lock acquire bench --task {} --note <说明>".format(owner))
print("下台架后：$TW lock release bench --task {}".format(owner))
print("回收仍归插件：/worktree remove {}（本 skill 不删插件树）".format(a.name))
return EXIT_OK
removed = [rel for rel, _spec in JUNCTION_SPECS if remove_junction(wt / rel)]
print("[ok] 摘掉联接：{}（只摘联接本身，绝不动目标内容与树里文件）".format(
"、".join(removed) if removed else "无（该树没有联接着）"))
return EXIT_OK
# --------------------------------------------------------------------- 子进程脚本
def regen(cwd: Path) -> None:
run_script("scripts/gen_task_table.py", ["--write"], cwd, "重生成 FreeRTOS 任务表")
if list((Path(cwd) / "MDK-ARM").glob("**/*.map")):
run_script("scripts/check_mem_numbers.py", ["--write"], cwd, "同步内存/Flash 快照")
else:
print("[skip] 未找到 .map，跳过内存快照同步（需先 @build）")
print("[skip] 未找到 .map，跳过内存快照同步（需先 /keil-build）")
def run_gates(cwd: Path, skip_build: bool) -> bool:
ok = run_script("scripts/ci_local.py", [], cwd, "L0 + L0.5 本地等价 CI")
ok = run_script("scripts/ci_local.py", [], cwd, "静态门禁 + 主机侧纯逻辑单测 本地等价 CI")
if skip_build:
print("[skip] 按 --skip-build 跳过 @build")
print("[skip] 按 --skip-build 跳过 /keil-build")
return ok
got, info = lock_acquire("build", "__done__", wait=900)
if not got:
print("!! build 锁被 {} 占用（UV4 不能并发构建），跳过 @build".format(info.get("task")))
print("!! build 锁被 {} 占用（UV4 不能并发构建），跳过 /keil-build".format(info.get("task")))
return False
# 告知 @build「调用方已持锁」：新版 keil_build.py 自持自释（见其 docstring），
# 告知 /keil-build「调用方已持锁」：新版 keil_build.py 自持自释（见其 docstring），
# 读到本变量即跳过，避免自我死锁；**旧版根本不看此变量、也不会自锁**，
# 故此处对「工作树里还是旧脚本」的在途任务同样安全（向后兼容）。
os.environ["DTU_LOCK_HELD"] = "build"
try:
if not run_script(".dsh/skills/keil-build/scripts/keil_build.py", [], cwd,
"@build（0 错 0 警）"):
"/keil-build（0 错 0 警）"):
ok = False
finally:
os.environ.pop("DTU_LOCK_HELD", None)
@@ -557,6 +765,10 @@ def cmd_new(a) -> int:
raise EnvError("已有 {} 个活跃任务（上限 {}）；先 done/abort，或加 --force".format(
len(active), MAX_CONCURRENT))
n_plugin = len(plugin_trees())
if n_plugin:
print("[i] 另有 {} 个 DSH 插件工作树（.dsh-worktrees/，不计入上限 {}）；"
"磁盘与 UV4 / 台架仍是共享资源——「plugin list」看清单".format(n_plugin, MAX_CONCURRENT))
WT_ROOT.mkdir(parents=True, exist_ok=True)
print("[1/3] 建工作树（分支 {}，基线 {}{}）…".format(
branch, a.base, "，跳过 LFS smudge" if a.lean else ""))
@@ -577,7 +789,7 @@ def cmd_new(a) -> int:
print()
print("下一步：把新会话的工作目录切到")
print(" " + str(wt))
print("在该目录里干活、跑 @build 与 ci_local.py（并行安全）；")
print("在该目录里干活、跑 /keil-build 与 ci_local.py（并行安全）；")
print("要动台架先 `lock acquire bench --task {}`，完事 `lock release bench --task {} --bench-pass`。".format(
a.task_id, a.task_id))
print("回收用 `done {}`（**必须在主工作树执行**）。".format(a.task_id))
@@ -588,6 +800,7 @@ def cmd_list(a) -> int:
states = all_states()
if not states:
print("（没有任务空间。用 `new <ID> <slug>` 建一个）")
print_plugin_trees()
return EXIT_OK
print("{:<12} {:<32} {:>5} {:>5} {:>4} {}".format(
"任务", "分支", "落后", "领先", "脏", "台架"))
@@ -612,6 +825,7 @@ def cmd_list(a) -> int:
else:
print("锁 {:<6} {} 持有（已 {:.1f} 小时，于 {}）".format(
n, info.get("task"), lock_age_hours(info), info.get("at")))
print_plugin_trees()
return EXIT_OK
@@ -692,10 +906,19 @@ def cmd_lock(a) -> int:
if a.bench_pass:
if not a.task:
raise EnvError("--bench-pass 需要 --task <ID>")
st = load_state(a.task)
st["bench_pass"] = True
save_state(st)
print("[ok] 已为任务 {} 记录台架 PASS".format(a.task))
# 非登记持有者（lead 的验收窗、插件树 pw:*）没有台账。以前这里先 load_state
# 就抛「任务 X 不存在（缺台账）」，**根本走不到释放**：锁还挂着，而 done 的前置
# 会因活锁判失败——一个名字没登记，就挡住所有任务的收口。现在降级为显式告警 +
# 照常释放：PASS 没进台账是事实，但不该拿「锁放不掉」当代价。
if state_file(a.task).is_file():
st = load_state(a.task)
st["bench_pass"] = True
save_state(st)
print("[ok] 已为任务 {} 记录台架 PASS".format(a.task))
else:
print("[warn] 任务 {} 无台账（{}）→ **跳过 PASS 记录，仅释放锁**；要把 PASS 留在"
"台账里就得用已「new」出来的任务 ID 占锁，或把验收结论写进主干提交说明/文档"
.format(a.task, state_file(a.task)))
ok, msg = lock_release(a.name, a.task, force=a.force)
print(msg)
return EXIT_OK if ok else EXIT_FAIL
@@ -747,13 +970,15 @@ def cmd_done(a) -> int:
raise Fail("任务分支相对 {} 没有新提交，无需合并".format(base))
if already and ahead == 0:
print("[i] {} 已合入 {}，跳过合并，直接清场".format(branch, base))
print("[i] 该路径在门禁之前就返回——不替你复绿；上一次门禁没跑到的尾巴，"
"清场后去主树跑 `postmerge`（或手工 ci_local + check_doc_links --all）")
print("=== 清场 ===")
teardown_worktree(st, force=a.force, base=base)
print("\n完成（分支此前已合入）。")
return EXIT_OK
if st.get("needs_bench") and not st.get("bench_pass"):
raise Fail("任务标记 --needs-bench 但无台架 PASS 记录；跑完 @test 后执行 "
raise Fail("任务标记 --needs-bench 但无台架 PASS 记录；跑完 /serial-boot-test 后执行 "
"`lock release bench --task {} --bench-pass`".format(st["id"]))
print("[ok] 前置检查通过（领先 {} 共 {} 个提交）".format(base, ahead))
@@ -797,6 +1022,7 @@ def cmd_done(a) -> int:
print("!! 门禁未全绿：工作树与分支**保留**，未清场。")
print(" 主干已含合并提交 {}".format(base_after[:12]))
print(" 可选：a) 在主工作树修正后追加提交（推荐）")
print(" ——体积凭证/台账红就用 `postmerge` 自动诊断回填，别手抄补链")
print(" b) 回退本次合并：git -C \"{}\" reset --hard {}".format(main, base_before[:12]))
return EXIT_FAIL
@@ -808,6 +1034,130 @@ def cmd_done(a) -> int:
return EXIT_OK
# ------------------------------------------------- 树内预检 / 合并后补绿（机械化）
HYGIENE_BINARY = (".png", ".jpg", ".gif", ".ico", ".ttf", ".bin", ".hex", ".elf",
".axf", ".o", ".crf", ".lst", ".zip", ".gz", ".pdf", ".cur")
CR_EXEMPT = (".bat", ".cmd") # .gitattributes 强制 CRLF
def _git_bytes(*args, cwd=None):
r = subprocess.run(["git"] + [str(x) for x in args], cwd=str(cwd or REPO_ROOT),
capture_output=True, stdin=subprocess.DEVNULL)
return r.stdout if r.returncode == 0 else None
def _changed_paths(cwd: Path):
q = ("-c", "core.quotePath=false") # 中文文件名不许被八进制转义出去
tracked = git(*q, "diff", "--name-only", "HEAD", cwd=cwd, check=False).stdout
others = git(*q, "ls-files", "--others", "--exclude-standard", cwd=cwd, check=False).stdout
return ([p.strip() for p in tracked.splitlines() if p.strip()],
[p.strip() for p in others.splitlines() if p.strip()])
def cmd_precheck(a) -> int:
"""树内自查（只读）：字节体检 + docs 逐档门禁 + 可选提交信息检查。绝不代改。"""
cwd = Path.cwd()
(cwd / "ci-artifacts").mkdir(exist_ok=True) # 新树没有 ci-artifacts（G 节：ENOENT 坑）
tracked, untracked = _changed_paths(cwd)
print("[i] {}：改动 {} 个（tracked {} + untracked {}）".format(
cwd, len(tracked) + len(untracked), len(tracked), len(untracked)))
bom3, cr, fffd = bytes.fromhex("efbbbf"), b"\r", bytes.fromhex("efbfbd")
problems, docs = 0, []
for p in tracked + untracked:
f = cwd / p
if not f.is_file() or p.lower().endswith(HYGIENE_BINARY):
continue
b = f.read_bytes()
bad = []
if cr in b and not p.lower().endswith(CR_EXEMPT):
bad.append("CR")
n = b.count(fffd)
if n:
bad.append("U+FFFD x{}".format(n))
if p in tracked:
hb = _git_bytes("show", "HEAD:" + p, cwd=cwd)
if hb is not None and hb.startswith(bom3) and not b.startswith(bom3):
bad.append("BOM 漂移（HEAD 有 BOM、工作区没了——bom-guard 会拦）")
if p.startswith("docs/") and p.endswith(".md"):
docs.append(p)
if bad:
problems += 1
print("!! {}：{}".format(p, " / ".join(bad)))
for d in docs:
if not run_script("scripts/check_doc_links.py", [d], cwd, "文档门禁 " + d, tail=6):
problems += 1
if a.msgfile:
m = Path(a.msgfile)
if not m.is_file():
raise EnvError("消息文件不存在：{}".format(m))
mb = m.read_bytes()
if mb.startswith(bom3):
problems += 1
print("!! 消息带 BOM（commit -F 要 UTF-8 无 BOM）")
if cr in mb:
problems += 1
print("!! 消息含 CRLF")
ml = mb.decode("utf-8", "replace").splitlines()
for i, ln in enumerate(ml):
lim = 100 if i == 0 else 80
if len(ln) > lim:
problems += 1
print("!! 消息第 {} 行长 {} > {}".format(i + 1, len(ln), lim))
break
for w in a.ban:
c = mb.decode("utf-8", "replace").lower().count(w.lower())
print("[i] 禁词 {!r}：{} 次".format(w, c))
if c:
problems += 1
print("完成：问题 {} 个".format(problems))
return EXIT_OK if problems == 0 else EXIT_FAIL
def cmd_postmerge(a) -> int:
"""主树合并后补绿：体积凭证自动诊断（短链/全链）+ 文档全量。列文件，不提交。
裁定外包给现有门禁：凭证红 → 先短链（--update 重写）→ 用只读的
check_mem_numbers 复检裁定数字是否真变——红了才升级全链（--write 族）。
"""
main = main_worktree()
if Path.cwd().resolve() != main.resolve():
raise EnvError("postmerge 必须在主工作树跑：{}".format(main))
if not list((main / "MDK-ARM").glob("**/*.map")):
raise EnvError("主树没有 .map——先 /keil-build 0/0 再回来（C.5 的前提）")
gate = "scripts/check_size_gate.py"
if not a.force and run_script(gate, ["--local"], main, "体积凭证检查（同码）", tail=8):
print("[ok] 凭证同码新鲜，无需补链")
else:
run_script("scripts/ram_baseline.py", ["--update"], main, "短链：重写体积凭证", tail=6)
mem_ok = (a.skip_mem or run_script("scripts/check_mem_numbers.py", [], main,
"受管区一致性复检（只读）", tail=8))
if not mem_ok:
print("[i] 快照与 .map 真漂了 → 升级全链（数字变了才动受管区）")
run_script("scripts/check_mem_numbers.py", ["--write"], main, "同步内存快照")
run_script("scripts/ram_baseline.py", ["--write"], main, "同步 RAM 预算台账")
if a.coverage:
run_script("scripts/check_test_coverage.py", ["--update-baseline"], main,
"覆盖率基线刷新", tail=6)
if not run_script(gate, ["--local"], main, "凭证复检（期望绿）", tail=8):
print("!! 凭证复检仍红——贴输出查 check_size_gate 原因，别硬提交")
return EXIT_FAIL
ok = True
if not a.skip_docs:
ok = run_script("scripts/check_doc_links.py", ["--all"], main, "文档全库检查", tail=8)
dirty = git("-c", "core.quotePath=false", "diff", "--name-only", "HEAD",
cwd=main, check=False).stdout.splitlines()
dirty = [x.strip() for x in dirty if x.strip()]
if dirty:
print()
print("[i] 回填产物（提交属 Ask first，本命令不代提交）：")
for p in dirty:
print(" - " + p)
print(" 建议：git add <上面列的文件> && git commit -F <正文文件>")
return EXIT_OK if ok else EXIT_FAIL
def cmd_abort(a) -> int:
st = load_state(a.task_id)
wt = Path(st["path"])
@@ -874,11 +1224,17 @@ def build_parser():
help="release bench 时顺带为该任务记录台架 PASS")
p.set_defaults(func=cmd_lock)
p = sub.add_parser("plugin", help="DSH worktree 插件的树（.dsh-worktrees/）：list / adopt / unadopt")
p.add_argument("action", choices=["list", "adopt", "unadopt"])
p.add_argument("name", nargs="?", default="",
help="插件 worktree 名（可带 worktree/ 前缀或多段斜杠）")
p.set_defaults(func=cmd_plugin)
p = sub.add_parser("done", help="回收：预演 → 合入主干 → 审计 → 重生成 → 门禁 → 清场")
p.add_argument("task_id")
p.add_argument("--base", default=None)
p.add_argument("--dry-run", action="store_true", help="只预演，不做任何改动")
p.add_argument("--skip-build", action="store_true", help="跳过 @build")
p.add_argument("--skip-build", action="store_true", help="跳过 /keil-build")
p.add_argument("--skip-gates", action="store_true", help="跳过全部门禁")
p.add_argument("--force", action="store_true", help="清场时强制移除工作树")
p.set_defaults(func=cmd_done)
@@ -887,6 +1243,18 @@ def build_parser():
p.add_argument("task_id")
p.add_argument("--force", action="store_true")
p.set_defaults(func=cmd_abort)
p = sub.add_parser("precheck", help="树内自查（只读）：字节体检 + docs 逐档门禁 + 可选消息检查")
p.add_argument("--msgfile", default=None, help="附带检查提交信息文件（BOM/CRLF/行长/禁词）")
p.add_argument("--ban", action="append", default=[], help="禁词，可重复")
p.set_defaults(func=cmd_precheck)
p = sub.add_parser("postmerge", help="主树合并后补绿：体积凭证自动诊断（短/全链）+ 文档全量；不代提交")
p.add_argument("--force", action="store_true", help="凭证新鲜也强制走一遍 --update")
p.add_argument("--coverage", action="store_true", help="附带覆盖率基线刷新")
p.add_argument("--skip-docs", action="store_true", help="跳过 check_doc_links --all")
p.add_argument("--skip-mem", action="store_true", help="只挪凭证，跳过受管区复检/全链")
p.set_defaults(func=cmd_postmerge)
return ap
.dsh/skills/template-skill/SKILL.md
+6
View File
@@ -0,0 +1,6 @@
---
name: template-skill
description: Replace with description of the skill and when Claude should use it.
---
# Insert instructions below
.dsh/skills/ui-verify/SKILL.md
+7 -4
View File
@@ -31,21 +31,24 @@ cmake --build simulator/build --config Debug # 0) 构建模拟器（须 0 警
|---|---|---|
| 内容页 FAIL，且**有意**改了该页视觉 | 预期变化 | 先肉眼确认新效果正确（窗口模式或 `i1_to_png.py` 出图对照 mockup），再 `.venv\Scripts\python.exe simulator/tests/check_content_pages.py --update` 刷参考，`git diff` 检查 ref/ 变化后随代码提交 |
| 内容页 FAIL，但**未**有意改视觉 | bug（缺字/几何漂移/样式回归） | 修代码；**禁止**刷参考掩盖 |
| 池水位门禁失败但像素一致 | 结构/样式变更（常量样式转换、增删框体等） | 确认新值合理（残留分解见 `菜单页面设计.md` §9.5）→ 更新脚本常量 + 在流程文档变更记录登记 |
| 池水位门禁失败但像素一致 | 结构/样式变更（常量样式转换、增删框体等） | 确认新值合理（残留分解见 `菜单页面设计.md` §9.5）→ 更新脚本常量 + 把新值与它的实测来源写进 `docs/UI设计/UI_自动化测试流程.md` 正文常量表（2026-10-28 起不再记流水，见 `docs/文档规范.md` §5.1） |
| 菜单回归失败 | 结构断言（白带占比/边框/往返一致） | 按脚本打印的未过断言清单逐项修代码，无参考文件可刷 |
## 池水位门禁常量（在脚本头部）
| 常量 | 脚本 | 当前值 | 含义 |
|---|---|---|---|
| `MENU_POOL_BASELINE` | check_menu_rows.py | 4784 B | 菜单根框建完的 LVGL 池 used（x64 模拟器） |
| `POOL_AFTER_ROUNDTRIP` | check_content_pages.py | 4864 B | 开页-关页往返后 = 基线 + 80 B 一次性残留 |
| `MENU_POOL_BASELINE` | check_menu_rows.py | 5368 B | 菜单根框建完的 LVGL 池 used（x64 模拟器；2026-10-11 随 LVGL 控件裁剪由 4784 上移） |
| `POOL_AFTER_ROUNDTRIP` | check_content_pages.py | 5448 B | 开页-关页往返后 = 基线 + 80 B 一次性残留 |
⚠ 两个常量量的是池的 **`used`**，与 `LV_MEM_SIZE` 总大小**无关** → 改池大小（如 2026-10-15 缩池 40→16 KB）**不该动这两个数**；动了就是页面结构变化或泄漏。
**禁止为过门禁盲目改常量**——无法解释的漂移 = 内存回归 bug。
## 关联注意
- `.venv` 缺失/换机：`& <本机任一 python ≥3.10> -m venv .venv; & '.venv\Scripts\python.exe' -m pip install -r requirements.txt`（`requirements.txt` 已含 `pre-commit`，重建后 L0 门禁直接可跑）
- `.venv` 缺失/换机：`& <本机任一 python ≥3.10> -m venv .venv; & '.venv\Scripts\python.exe' -m pip install -r requirements.txt`（`requirements.txt` 已含 `pre-commit`，重建后静态门禁直接可跑）
- 新增 UI `.c` 文件先走 `new-source-file` skill 双端注册，否则一端静默缺文件
- 改 `ui_menu_tree.txt` 或界面里的中文字符串 → **同一笔**重跑生成器（`tools/menu_gen/gen_menu.py`；字体走 **font-regen** 四步），否则提交门禁 `generated-fresh` 直接拦：它把生成器拷进系统临时目录重跑、与工作区逐字节比对（实证 `0f7b5a87` 改了模板没重跑）→ `docs/门禁说明/generated-fresh.md`
- 字体重生成后全页大面积像素差异属预期：确认字形正确后 `--update` 刷参考
- 涉及新界面/大改时本 skill 是 P3 门禁，完整管线（P0~P5）见 `docs/UI设计/UI_界面制作流程.md`
.gitea/workflows/ci.yml
+188 -62
View File
@@ -1,25 +1,36 @@
# Gitea Actions CI —— STM32F4-Base 持续集成
#
# 覆盖范围（**只做不依赖硬件的层**，见 docs/测试说明/测试开发标准流程.md §1/§9）：
# L0 静态门禁 = pre-commit 全部钩子（等价本地 `pre-commit run --all-files`）
# L0.5 主机侧纯逻辑单测 = test/host/**（MSVC 离线编译，零硬件）
# 覆盖范围（**只做不依赖硬件的层**，见 docs/测试说明/流程与规范/测试开发标准流程.md §1/§9）：
# 静态门禁 static = pre-commit 全部钩子（等价本地 `pre-commit run --all-files`）
# + 手动阶段三根（覆盖率总闸 / 全量 cppcheck / test-cppcheck，`--hook-stage manual`；
# 它们在 .pre-commit-config.yaml 里带 stages: [manual]，提交期不跑，由本 job 强制）
# 主机侧纯逻辑单测 host-unit = test/host/**（MSVC 离线编译，零硬件）
#
# ⛔ L1 板端套件（test/board/，需真机 + ST-LINK）/ L2 @test 闭环 / L3 人工目检
# ⛔ 板端测试套件（test/board/，需真机 + ST-LINK）/ 主机侧回归（/serial-boot-test 闭环）/ 人工目检
# **不上 CI** —— 需要开发板与烧录器，只能在本地跑。
#
# 明确不做的两件事（都是刻意为之）：
# 1. `@build`（Keil UV4）—— 需本机 Keil 授权，runner 上不具备；且 L0 的 cppcheck +
# 1. `/keil-build`（Keil UV4）—— 需本机 Keil 授权，runner 上不具备；且静态门禁的 cppcheck +
# 代码规范已覆盖"编译前的静态问题"，真编译仍是开发者的本地红线（AGENTS.md）。
# 2. `mem-numbers` 钩子 —— 它的事实源是 `MDK-ARM/**/*.map`（Keil 构建产物、已 gitignore），
# 无 `@build` 即无 `.map`。故本 workflow 在**检测不到 .map 时自动跳过该钩子**
# （见下方 "决定跳过哪些钩子" 步骤），有 .map 的 runner（如自建带 Keil 的机器）则照常跑。
# 2. `mem-numbers` / `mem-budget` 两根钩子 —— 事实源都是 `MDK-ARM/**/*.map`（Keil
# 构建产物、已 gitignore），无 `/keil-build` 即无 `.map`。故本 workflow 在**检测不到
# .map 时自动跳过它们**（见下方 "决定跳过哪些钩子" 步骤），有 .map 的 runner 照常跑。
#
# 🔴 门禁盲区声明（S14，2026-10-02）：跳过 `mem-numbers` 意味着 **CI 不守 Flash/RAM 体积门禁**。
# 体积变更（新增任务/缓冲/代码）不会在 CI 被拦下；必须靠**本地 `@build` 后**
# `python scripts/check_mem_numbers.py --scan` 兜底。故该跳过以 `::warning::` 明示
# （不是弱化的 `::notice::`），并写入 job step-summary 的醒目行。
# 🔴 体积门禁：盲区已关闭为**强制路径**（2026-10-25 起；原先只做到"声明"）
# 跳过钩子只解释了"runner 没有 Keil"，没解决**"没跑 = 通过"**：钩子在无 .map 时
# 自适应 SKIP 并返回 0，于是 CI 全绿仍可能被读成"体积也守住了"。现由静态门禁作业**最后
# 一步** `python scripts/check_size_gate.py --ci` 在**不需要 Keil** 的前提下补两条判据：
# · 同码性：`scripts/size_attestation.json` 的源码指纹必须等于本次检出树的指纹，
# 而该凭证只能由"新鲜 .map + 当时未超线"的真实链接测量写出（见 --stamp 三道前置）
# ——等价于"这份代码至少被 Keil 链接并核算过一次"；
# · 红线：该次测量记录的受管区占比 ≤92%，与 `mem-budget` 同一常数同一口径。
# 强制落点 = **主干 push**（唯一能保证"这就是要发出去的那份"的位置）；其余事件降级为
# `::warning::`——任务分支上的代码尚未定型，拦红只制造噪音，还会诱发多条道同时
# 抢写 scripts/ 台账。仍守不住的（**口径正文唯一**在 scripts/check_size_gate.py 的
# 模块 docstring，此处不重复）：绝对数字由本地真实构建产生（runner 无 Keil 许可证）、
# 编译器选项（uvprojx，UV4 每次改写且不入库）不在指纹范围内。
#
# 产物存档（S3，2026-10-02）：两个 job 把关键输出 `Tee-Object` 到 `ci-artifacts/*.log`，
# 产物存档与结果可见性（2026-10-02 起）：两个 job 把关键输出 `Tee-Object` 到 `ci-artifacts/*.log`，
# 并写 $GITHUB_STEP_SUMMARY（Gitea UI 直接可见）+ `::notice::` 汇总行。
# **刻意不用 `actions/upload-artifact`**——内网可能拉不到外层 action（见 docs/CI/远程CI完整指南.md §5.3）；
# 零依赖方案下日志留在 runner 工作区，UI 通过 step-summary 即可排障。
@@ -50,7 +61,7 @@
# · 仓库 `.venv` 已 gitignore，runner 的全新工作区里**根本不存在**。
# 唯一可用的机器级解释器（`C:\ProgramData\anaconda3\python.exe`）不再被探测，而文档
# 要求的机器级 `DTU_PRECOMMIT_PYTHON` 从未设置（Machine 作用域一个 DTU_* 都没有）
# → run 14/15 的 L0 **全部死在"环境自检"，一个钩子都没跑**。cppcheck 同理：
# → run 14/15 的静态门禁 **全部死在"环境自检"，一个钩子都没跑**。cppcheck 同理：
# 旧写法"不在 PATH 就把 C:\Program Files\Cppcheck 加进 PATH"的兜底也被删了。
# **故探测逻辑搬进 `scripts/ci_find_python.ps1`**（两个 job 共用、可离线跑、失败时
# 打印全部候选），并恢复常见机器级安装位置兜底；`DTU_*` 仍是最高优先级、
@@ -77,7 +88,7 @@
# - 该 Gitea 实例已启用 Actions：`[actions] ENABLED = true`（site admin 配置）
# - 已注册一个 **Windows** runner（labels 含 `windows`），且装有：
# Python 3.x、cppcheck、pre-commit、MSVC（VS2019/2022 的 C++ 工具链 + Windows SDK）
# - 缺 MSVC 时 L0.5 步骤会**降级为提示并跳过**（不硬失败），但会打印醒目 WARNING
# - 缺 MSVC 时主机侧单测步骤会**降级为提示并跳过**（不硬失败），但会打印醒目 WARNING
#
# 🔧 runner 机器级环境变量（可选项覆盖；runner 以 SYSTEM 服务运行，用户级变量不可见）：
# DTU_PRECOMMIT_PYTHON / DTU_CPPCHECK / DTU_MSVC_CL —— 未设置时按 PATH / 标准 VS 布局自动发现。
@@ -110,10 +121,10 @@ concurrency:
jobs:
# ------------------------------------------------------------------
# L0：静态门禁（pre-commit 钩子全集）
# 静态门禁（pre-commit 钩子全集）
# ------------------------------------------------------------------
l0-gates:
name: L0 静态门禁 (pre-commit)
static-gates:
name: 静态门禁 (pre-commit)
runs-on: windows
steps:
- uses: actions/checkout@v4
@@ -132,7 +143,7 @@ jobs:
# * both jobs share ONE implementation,
# * it can be run (and its failure list inspected) offline,
# * the well-known machine-wide install locations stay probed.
# The previous inline 2-candidate probe is what killed every L0 run
# The previous inline 2-candidate probe is what killed every static-gate run
# since 33a4aa4 -- see the file header.
#
# The script prints diagnostics with Write-Host and emits ONLY the
@@ -154,7 +165,7 @@ jobs:
# The directory fallback is NOT cosmetic: the runner service runs as
# SYSTEM, whose PATH has no Cppcheck entry (a USER-scope PATH entry is
# invisible to it), and no machine-level DTU_CPPCHECK is set on a
# stock runner. Dropping this fallback in 33a4aa4 is what made L0 die
# stock runner. Dropping this fallback in 33a4aa4 is what made the static-gate job die
# on cppcheck as well, right after the Python probe had been fixed.
$found = $null
$envCpp = $env:DTU_CPPCHECK
@@ -235,32 +246,36 @@ jobs:
id: skip
shell: powershell
run: |
# mem-numbers fact source is the Keil build artifact .map (gitignored).
# No .map => this hook cannot run => skip (not "pass", but "not applicable").
# mem-numbers / mem-budget fact source is the Keil build artifact .map
# (gitignored). No .map => those hooks cannot run => skip them EXPLICITLY.
#
# S14 (2026-10-02): make this GAP loud. mem-numbers is the ONLY gate that
# checks docs/memory numbers against the real .map (Flash/RAM size). When
# it is skipped, CI effectively does NOT guard the size budget -- a silent
# ::notice:: was too easy to miss. So:
# - emit ::warning:: (not ::notice::) so it shows in the run summary
# - write a machine-readable marker file for the summary step
# - append a bold line to the job step-summary
# 2026-10-25: two honesty fixes here.
# 1) mem-budget used NOT to be listed, yet it self-skips inside the script
# when .map is missing (exit 0) -- so on a Keil-less runner it reported
# "Passed" while checking nothing. A gate that fakes green is worse than
# a gate that is visibly skipped: skip it here so the report says Skipped.
# 2) "skipped" alone is still the blind spot, so the compensation is a
# real step, not only a warning: see the "size gate" step at the end of
# this job (scripts/check_size_gate.py --ci, no Keil needed: attestation
# parity + 92% re-check on the recorded numbers). Boundary and rationale
# live in that script docstring (single source of truth).
$map = Get-ChildItem -Path 'MDK-ARM' -Recurse -Filter '*.map' -ErrorAction SilentlyContinue
if ($map) {
Write-Host "found .map: $($map[0].FullName) -- mem-numbers runs normally"
Write-Host "found .map: $($map[0].FullName) -- size hooks run normally"
"value=" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
"sizegate=on" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
"> Volume gate (mem-numbers): RAN (.map present)" |
"> Volume gates (mem-numbers, mem-budget): RAN (.map present)" |
Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append -Encoding utf8
} else {
Write-Host "::warning::no .map found (no Keil build) -- SKIPPING mem-numbers, so the Flash/RAM size gate does NOT run in CI. Size changes are NOT caught here; verify locally with 'python scripts/check_mem_numbers.py --scan' after a Keil build."
"value=mem-numbers" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
Write-Host "::warning::no .map found (no Keil build) -- SKIPPING mem-numbers and mem-budget, so absolute Flash/RAM numbers are NOT recomputed here."
Write-Host "::warning::that gap is no longer silent: the final step of this job runs scripts/check_size_gate.py --ci (forced path: attestation parity + 92% budget re-check). Locally: scripts/ci_local.py size step."
"value=mem-numbers,mem-budget" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
"sizegate=off" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
"> :warning: Volume gate (mem-numbers): **NOT RUN** -- no `.map` (no Keil build)." |
"> :warning: Volume gates (mem-numbers, mem-budget): **NOT RUN** -- no `.map` (no Keil build); compensated by the size-gate step below." |
Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Append -Encoding utf8
}
- name: 运行 L0 门禁（--all-files）
- name: 运行静态门禁（--all-files）
shell: powershell
env:
SKIP: ${{ steps.skip.outputs.value }}
@@ -274,7 +289,7 @@ jobs:
# would ABORT the pipeline. Relax the preference around the pipeline and
# restore it afterwards (same pattern as the env-check step above).
New-Item -ItemType Directory -Force -Path 'ci-artifacts' | Out-Null
$log = 'ci-artifacts\l0-pre-commit.log'
$log = 'ci-artifacts\static-pre-commit.log'
if ($env:SKIP) { Write-Host "SKIP=$env:SKIP" }
$saved = $ErrorActionPreference
$ErrorActionPreference = 'Continue'
@@ -288,37 +303,148 @@ jobs:
$passed = @($lines | Select-String -Pattern 'Passed$').Count
$failed = @($lines | Select-String -Pattern 'Failed$').Count
$skipd = @($lines | Select-String -Pattern 'Skipped$').Count
$summary = "L0: pre-commit hooks -- passed=$passed failed=$failed skipped=$skipd (log: $log)"
$summary = "static: pre-commit hooks -- passed=$passed failed=$failed skipped=$skipd (log: $log)"
Write-Host "::notice::$summary"
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### L0 static gates" -Encoding utf8
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### 静态门禁 (static gates)" -Encoding utf8
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value $summary -Encoding utf8
if ($rc -ne 0) {
Write-Host "::error::L0 static gates failed (see output above and $log)"
Write-Host "::error::static gates failed (see output above and $log)"
exit $rc
}
- name: 归档 L0 日志（供下载/排障）
# ------------------------------------------------------------
# 手动阶段门禁（2026-10-28 用户裁定）：主机单测覆盖率总闸 + 全量 cppcheck。
# 这三根钩子在 .pre-commit-config.yaml 里带 `stages: [manual]`，**不在 git commit 时跑**
# （实测合计 ~165 s = 一次带代码提交耗时的三分之二）；提交期只跑快的那些，全量扫描由本 job 强制。
# 逐根调用而不是一条命令：`pre_commit run <a> <b>` 不支持多 id（实测 argparse 报
# "unrecognized arguments"）。
- name: 手动阶段门禁（覆盖率总闸 + 全量 cppcheck）
if: always()
shell: powershell
run: |
# S3: zero-dependency artifact archival. We do NOT use
# Pure ASCII only (see file header). Same $ErrorActionPreference dance as the
# static-gate step above: the runner injects 'Stop', and '2>&1 |' turns a
# native command's stderr into an ErrorRecord that would abort the pipeline.
New-Item -ItemType Directory -Force -Path 'ci-artifacts' | Out-Null
$log = 'ci-artifacts/manual-stage.log'
if (Test-Path $log) { Remove-Item $log -Force }
$rc = 0
$hooks = @('cppcheck', 'test-cppcheck', 'test-coverage')
foreach ($h in $hooks) {
Write-Host "== manual hook: $h =="
$saved = $ErrorActionPreference
$ErrorActionPreference = 'Continue'
& $env:PYTHON -s -m pre_commit run --all-files --hook-stage manual $h 2>&1 |
Tee-Object -FilePath $log -Append
$one = $LASTEXITCODE
$ErrorActionPreference = $saved
Write-Host "manual hook $h rc=$one"
if ($one -ne 0) { $rc = $one }
}
$lines = Get-Content $log -ErrorAction SilentlyContinue
$passed = @($lines | Select-String -Pattern 'Passed$').Count
$failed = @($lines | Select-String -Pattern 'Failed$').Count
$summary = "manual-stage: coverage + cppcheck -- passed=$passed failed=$failed (log: $log)"
Write-Host "::notice::$summary"
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### manual stage gates (coverage + cppcheck)" -Encoding utf8
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value $summary -Encoding utf8
if ($rc -ne 0) {
Write-Host "::error::manual-stage gates failed (see output above and $log)"
exit $rc
}
- name: 归档静态门禁日志（供下载/排障）
if: always()
shell: powershell
run: |
# Result visibility: zero-dependency artifact archival. We do NOT use
# actions/upload-artifact (inner networks may not fetch outer actions);
# instead we keep the log on the runner AND surface its path + tail in
# the step summary, so the UI is self-sufficient for triage.
if (Test-Path 'ci-artifacts\l0-pre-commit.log') {
$size = (Get-Item 'ci-artifacts\l0-pre-commit.log').Length
Write-Host "archived: ci-artifacts/l0-pre-commit.log ($size bytes)"
if (Test-Path 'ci-artifacts\static-pre-commit.log') {
$size = (Get-Item 'ci-artifacts\static-pre-commit.log').Length
Write-Host "archived: ci-artifacts/static-pre-commit.log ($size bytes)"
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "" -Encoding utf8
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "Archived log: ``ci-artifacts/l0-pre-commit.log`` ($size bytes on runner)" -Encoding utf8
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "Archived log: ``ci-artifacts/static-pre-commit.log`` ($size bytes on runner)" -Encoding utf8
}
if (Test-Path 'ci-artifacts\manual-stage.log') {
$msize = (Get-Item 'ci-artifacts\manual-stage.log').Length
Write-Host "archived: ci-artifacts/manual-stage.log ($msize bytes)"
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "Archived log: ``ci-artifacts/manual-stage.log`` ($msize bytes on runner)" -Encoding utf8
}
Write-Host "::notice::static-gate artifacts kept on runner at: ci-artifacts\ (static-pre-commit.log, manual-stage.log)"
# ------------------------------------------------------------
# 强制体积门禁（2026-10-25）：不需要 Keil，也不需要 .map
# 放在静态门禁作业**最后**且 if: always()——静态门禁失败时这条结论同样要看得到，
# 而它自己失败会让整个作业变红（这正是"强制"的含义）。
- name: 体积门禁（强制路径：同码凭证 + 92% 红线，无需 Keil）
if: always()
shell: powershell
env:
GATE_REF: ${{ github.ref }}
GATE_EVENT: ${{ github.event_name }}
run: |
# Pure ASCII only (see file header).
#
# WHY THIS STEP EXISTS: mem-numbers / mem-budget read the Keil .map and
# self-skip (exit 0) without it, so "not measured" used to look like
# "passed" -- that is exactly the blind spot ("CI all green does not
# mean the size budget held"). Merely declaring it did not close it.
#
# This step enforces a check that needs NO Keil and NO .map:
# * parity -- scripts/size_attestation.json (a committed attestation
# that --stamp refuses to write unless the .map is present, newer
# than every source file in scope, and inside budget) must
# fingerprint-match THIS checked-out tree => this exact code was
# linked for real at least once;
# * budget -- the region percentages that measurement recorded must
# stay within the same 92% line mem-budget uses.
#
# Enforcement point = trunk push, the only ref guaranteed to be the code
# we ship. Task branches / WIP pull requests run --warn-only instead: the
# code there is still moving, and blocking it would push every lane to
# edit the same scripts/ ledger file at the same time.
New-Item -ItemType Directory -Force -Path 'ci-artifacts' | Out-Null
$log = 'ci-artifacts\size-gate.log'
if (-not $env:PYTHON) {
# The environment probe step already failed in that case, so the job is
# red anyway; do not mask that with a second, unrelated error.
Write-Host "::warning::PYTHON unresolved (env step failed) -- size gate cannot run"
exit 0
}
$trunks = @('refs/heads/v2-on-ui', 'refs/heads/master', 'refs/heads/main')
$enforce = ($env:GATE_EVENT -eq 'push') -and ($trunks -contains $env:GATE_REF)
if ($enforce) {
$mode = @()
$label = 'ENFORCING (trunk push)'
} else {
$mode = @('--warn-only')
$label = 'advisory (non-trunk event)'
}
$saved = $ErrorActionPreference
$ErrorActionPreference = 'Continue'
& $env:PYTHON -s scripts/check_size_gate.py --ci @mode 2>&1 |
Tee-Object -FilePath $log
$rc = $LASTEXITCODE
$ErrorActionPreference = $saved
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "" -Encoding utf8
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### Volume gate (forced path)" -Encoding utf8
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "size gate: rc=$rc mode=$label (attestation parity + 92% re-check; no Keil)" -Encoding utf8
Write-Host "::notice::size gate: rc=$rc mode=$label (log: $log)"
if ($rc -ne 0) {
Write-Host "::error::volume gate FAILED: this tree has no matching real Keil measurement, or the measured regions exceed the 92% budget."
Write-Host "::error::fix: run the Keil build locally (0 errors 0 warnings), then 'python scripts/ram_baseline.py --update', and commit scripts/size_attestation.json (scripts/ram_baseline.tsv is refreshed by the same command). Rationale/boundary: scripts/check_size_gate.py docstring."
exit $rc
}
Write-Host "::notice::L0 artifacts kept on runner at: ci-artifacts\l0-pre-commit.log"
# ------------------------------------------------------------------
# L0.5：主机侧纯逻辑单测（零硬件；缺 MSVC 则跳过）
# 主机侧纯逻辑单测（零硬件；缺 MSVC 则跳过）
# ------------------------------------------------------------------
l05-host-unit-tests:
name: L0.5 主机侧单测 (MSVC)
host-unit-tests:
name: 主机侧单测 (MSVC)
runs-on: windows
steps:
- uses: actions/checkout@v4
@@ -376,7 +502,7 @@ jobs:
if ($found) {
"value=yes" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
} else {
Write-Host "::warning::runner has no MSVC (VS C++ toolchain) -- skipping L0.5. Install VS BuildTools and re-run."
Write-Host "::warning::runner has no MSVC (VS C++ toolchain) -- skipping host-side unit tests. Install VS BuildTools and re-run."
"value=no" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
}
@@ -385,9 +511,9 @@ jobs:
if: steps.msvc.outputs.value == 'yes'
shell: powershell
run: |
# Resolve a working Python with the SAME shared probe as L0 (no
# Resolve a working Python with the SAME shared probe as the static-gate job (no
# -NeedPreCommit: these harnesses are stdlib-only). The old inline
# probe here had the same 2-candidate blind spot as L0 -- it only
# probe here had the same 2-candidate blind spot as the static-gate job -- it only
# survived by luck, because the stdlib tests also run on the msys64
# python that happens to be on SYSTEM's PATH.
$py = & './scripts/ci_find_python.ps1' -WriteEnv
@@ -413,12 +539,12 @@ jobs:
$sumPass = 0
$sumTotal = 0
# Relax preference around each `2>&1 | Tee-Object` pipeline (native stderr
# becomes ErrorRecord -> 'Stop' would abort). See L0 step for details.
# becomes ErrorRecord -> 'Stop' would abort). See the static-gate steps for details.
$savedPref = $ErrorActionPreference
foreach ($r in $runners) {
$runnerCount++
$name = $r.Directory.Name
$log = "ci-artifacts\l05-$name.log"
$log = "ci-artifacts\host-unit-$name.log"
Write-Host "================================"
Write-Host "run: $($r.FullName)"
Write-Host "================================"
@@ -444,19 +570,19 @@ jobs:
}
}
$agg = "L0.5: $runnerCount runner(s), $sumPass/$sumTotal assertions passed, fail=$fail"
$agg = "host-unit: $runnerCount runner(s), $sumPass/$sumTotal assertions passed, fail=$fail"
Write-Host "::notice::$agg"
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### L0.5 host-side unit tests" -Encoding utf8
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### 主机侧纯逻辑单测 (host-unit)" -Encoding utf8
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value $agg -Encoding utf8
"count=$runnerCount" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
"agg=$agg" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding ascii
exit $fail
- name: 归档 L0.5 日志（供下载/排障）
- name: 归档主机侧单测日志（供下载/排障）
if: always()
shell: powershell
run: |
# S3: same zero-dependency archival as L0.
# Result visibility: same zero-dependency archival as the static-gate job.
if (Test-Path 'ci-artifacts') {
$logs = Get-ChildItem -Path 'ci-artifacts' -Filter '*.log' -ErrorAction SilentlyContinue
foreach ($f in $logs) {
@@ -468,15 +594,15 @@ jobs:
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "Archived logs on runner: $names" -Encoding utf8
}
} else {
Write-Host "no ci-artifacts directory (L0.5 skipped or failed early)"
Write-Host "no ci-artifacts directory (host-side unit tests skipped or failed early)"
}
- name: L0.5 跳过说明
- name: 主机侧单测跳过说明
if: steps.msvc.outputs.value == 'no'
shell: powershell
run: |
Write-Host "L0.5 skipped: runner has no MSVC."
Write-Host "host-side unit tests skipped: runner has no MSVC."
Write-Host "Local equivalent: & '.venv\Scripts\python.exe' scripts/ci_local.py"
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### L0.5 host-side unit tests" -Encoding utf8
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value "### 主机侧纯逻辑单测 (host-unit)" -Encoding utf8
Add-Content -Path $env:GITHUB_STEP_SUMMARY -Value ":warning: **NOT RUN** -- runner has no MSVC (VS C++ toolchain)." -Encoding utf8
exit 0
.gitignore
+42 -3
View File
@@ -120,9 +120,14 @@ simulator/SDL2/
*.exe
*.pdb
*.ilk
# 内容页黄金参考（ref/*.bin）与目检 PNG 均为本地生成物，不入库：
# 首次/换机后先跑 check_content_pages.py --update 生成 ref/*.bin，再跑 regen_ref_png.py 出 PNG
simulator/tests/ref/
# 内容页像素黄金参考 ref/*.bin **已入库**（2026-10-22）：整目录不入库时，任何新克隆 /
# 新工作树跑 ui-golden 都必然 FAIL（缺基准），这条像素回归就只在老机器上真实存在。
# 交叉验证：两份各自独立构建的 lvgl_sim（不同构建目录、相隔 11 天的代码）对同一批 ref
# 逐字节一致 → 渲染可复现，基线可入库。派生的目检 PNG 仍是本地产物，继续忽略：
simulator/tests/ref/*.png
# ⚠ 上面第 115 行的全仓 `*.bin` 兜底（挡模拟器的 sim_netcfg.bin 之类运行产物）会连入库的
# 黄金参考一起挡掉 → 必须显式反选；反选只有排在 `*.bin` **之后**才生效（.gitignore 后者覆盖前者）
!simulator/tests/ref/*.bin
# 架构图 PNG 预览（源为 docs/images/*.svg，PNG 本地渲染生成，不入库）
docs/images/*.png
*.pyc
@@ -133,6 +138,19 @@ docs/images/*.png
# Serial assistant runtime state (daemon log/meta, local runtime artifacts)
.dsh/skills/serial-assistant/scripts/state/
# agent 会话草稿（2026-10-14 定）：提交信息草稿 / 门禁输出 / 台架日志 / 一次性改名
# 脚本 / 故障注入 patch —— 一律不入库，**而且不落仓库根**（写进 ci-artifacts/ 或系统临时
# 目录：2026-10-28 清理仓库根时那里堆着四个一次性计数改名脚本 + 一份提交信息草稿，全是
# 未跟踪的 ?? —— 一次 git add -A 就进历史；仓库根只留工程配置与生成器输入两份 .txt）。
# 判据三条，命中任一就不值得留：
# ① 能重跑的（门禁输出、日志）；② 内容已在 git 历史里的（已合并实现的过程 diff）；
# ③ 离开已丢弃的任务分支就跑不通的（依赖 NET_FAULT_INJECT 的注入产物）——
# 这种提交进去是"看着有证据、实际不可复现"的假证据，**方法应沉淀成文档文字**
# （见 docs/网络/网络自愈架构设计.md §5.2 E18/E19）。
# ⚠ .dsh/skills/ 是**入库的项目知识**（skills = 子域方法论），必须放行。
.dsh/*
!.dsh/skills/
# 记忆工具（Mnemon）本地状态：项目文档索引 documents/ + 运行时记忆
# runtime/MEMORY.md、USER.md、memories.json。**只留本机、不进版本库**
# （2026-10-11 定）：记忆是按机器/按人累积的私有状态，入库会让每次记忆
@@ -141,4 +159,25 @@ docs/images/*.png
# CI 运行时产物（.gitea/workflows/ci.yml 的 S3 步骤在 runner 工作区落盘的日志；
# 零依赖存档方案——落在工作区目录而非上传 artifact，故必须忽略以免误提交）
# 子进程环境残缺时 Windows 会按字面量建目录（本会话实测两次复发：UV4 / 字体
# 工具在缺 SystemDrive、ProgramData 的环境里于仓库根创建
# %SystemDrive%/ProgramData/Microsoft/Windows/Caches/*.db，约 1 MB 字体缓存库）。
# 与"一次性中间产物不进 .gitignore"那条教训不同：这是任何一条道随时可能再生的环境
# 副产物，不兜住就会被某次 git add -A 带进历史。正解仍是继承完整环境跑这类工具。
%SystemDrive%/
ci-artifacts/
# 提交信息草稿的兜底反选（上一条草稿块的「不入库」靠人自觉把文件写进 ci-artifacts/，
# 但 `git commit -F` 那份文件随手落在仓库根就会以 ?? 出现，被某次 add -A 带走）：
# 正文已经进了 commit message，落盘副本零信息量 → 根目录锚定挡掉这个命名。
/commitmsg*.txt
# DSH worktree 插件（dsh-task-worktree）把任务树建在**仓库内**这个命名空间下，与
# @task skill 的仓外 _wt/ 两套并存。这一行必须**先由我们自己写好**：插件首次 create
# 会往 .gitignore 追加分毫不相同的字面量（ensureIgnored 见同名规则即跳过），但那等于
# 在会话中途改这份受控文件——门禁 diff 里冒出一行"不是我加的"最坑人。
# 该目录同时登记进了 check_doc_links / gen_refgraph / check_layer_deps 的排除面
# （整份仓库副本不能进全库扫描）；细节 → .dsh/skills/task-worktree/SKILL.md
.dsh-worktrees/
.obsidian/
.pre-commit-config.yaml
+434 -30
View File
@@ -1,5 +1,8 @@
# pre-commit 自动化代码审查配置
# 详见 docs/代码规范/pre-commit使用说明.md
# 通用机制（阶段 / stash 陷阱 / 触发面 / 增量拦截三段式）→ docs/代码规范/pre-commit使用说明.md §2
# 每个门禁一篇详解（含限制与盲区）→ docs/门禁说明/README.md
# 加/删一条钩子：同一笔提交里改 AGENTS.md 的「共 N 个钩子」与本文件注释；口径 = YAML 解析后的 hook 条目数，
# 自查命令与「声明 / 文档 / 实跑」三数同源核对 → docs/门禁说明/README.md §2（直接数文本行会把下面注释掉的候选条目算进去）
default_install_hook_types: [pre-commit, commit-msg]
# 顶层 exclude 只挡**第三方与生成物**。
@@ -8,8 +11,15 @@ default_install_hook_types: [pre-commit, commit-msg]
# tests/*.py、两份配置与 README）。整目录豁免 = 自研代码落在所有钩子之外（连
# lv-conf-sync 都拦不到）；实测把 simulator/ 纳入 cppcheck 后，立刻揪出
# sim_syslog.c 一处真实的空指针解引用。真正的生成物/第三方（`simulator/build/`、
# `simulator/SDL2/`、`simulator/tests/ref/`、`simulator/shot*.{bin,png}`、`__pycache__/`）
# **已在 .gitignore 里**，永远不会进 git 索引 → 无需在此重复豁免，故直接删掉该条。
# `simulator/SDL2/`、`simulator/shot*.{bin,png}`、`__pycache__/`）**已在 .gitignore 里**，
# 不会进 git 索引 → 无需在此重复豁免，故直接删掉该条。
# ⚠ 例外（2026-10-22）：`simulator/tests/ref/*.bin`（ui-golden 的像素黄金参考）已从
# 「整目录 gitignore」改为**入库**——基线不入库时任何新克隆 / 新工作树都必然报
# 「缺黄金参考」，这条门禁就只在有老副本的机器上真实存在。入库前提是实测可复现：
# 两份各自独立构建的 lvgl_sim（不同构建目录、相隔 11 天的代码）对同一批 11 个 .bin
# SHA-256 全部一致。改写型钩子（trailing-whitespace / end-of-file-fixer）声明
# `types: [text]`，位图含 NUL → 被判二进制自动 Skipped（实测「索引 blob == 磁盘 ==
# 参照」三方一致），无需为它另加 exclude。
exclude: |
(?x)^(
\.opencode/node_modules/|
@@ -66,6 +76,11 @@ repos:
hooks:
- id: cppcheck
name: cppcheck
# ⚠ stages: [manual]（2026-10-28 用户裁定）：全库扫描实测 ~20 s，不压在提交期；
# 由**远端 CI** 强制（.gitea/workflows/ci.yml 的「手动阶段门禁（覆盖率总闸 + 全量 cppcheck）」步），
# 本地的等价入口 = scripts/ci_local.py（manual 段）或
# python -m pre_commit run --all-files --hook-stage manual cppcheck
stages: [manual]
entry: cppcheck
# 注意：YAML 流序列中逗号是元素分隔符，含逗号/空格的参数必须加引号
args: ['--enable=warning,performance,portability,style', '--error-exitcode=1',
@@ -105,6 +120,9 @@ repos:
# 依据：docs/审查记录/测试与架构改进建议.md §3.4；实机测试实施指南.md §8.1
- id: test-cppcheck
name: cppcheck (test/, warning only)
# ⚠ stages: [manual]（2026-10-28，同 cppcheck）：实测 ~38 s；由远端 CI 与
# scripts/ci_local.py 的 manual 段跑，提交期不跑。
stages: [manual]
entry: cppcheck
args: ['--enable=warning', '--error-exitcode=1',
'--inline-suppr', '--std=c99', '--quiet',
@@ -152,11 +170,11 @@ repos:
Inc/
)
# 5) 文档一致性门禁（D-7）
# 5) 文档一致性门禁
# 存在性：md 互链 / 反引号路径是否指向真实文件（防迁移/删除后残留死链）
# 章节：`§N.M` 必须能在目标文档的编号标题里找到（--sections-strict：自引用失效也拦）
- id: doc-links
name: 文档链接存在性 (D-3/D-7)
name: 文档链接存在性
entry: python scripts/check_doc_links.py --sections-strict
language: system
files: \.md$
@@ -169,23 +187,46 @@ repos:
MDK-ARM/RTE/|
docs/芯片手册/
)
# 数值：README/AGENTS 任务表须与 Src/freertos.c 一致（D-2/D-7）
# mermaid 图：围栏内确定性语法预检（第 52 条，2026-10-30 加，口径 51 → 52，提交期实跑 48 → 49）。
# 为什么要有：屏板链路设计说明.md §1 的 flowchart 里 `-.|"文字"|`（`-.` 直接跟管道，不是任何合法
# 箭头 token）让 mermaid 渲染 `Syntax error in text`——该图 2026-10-29 落库、期间 doc-links 等
# 全绿：文档门禁查链接与章节，**从不查围栏内图表语法**，这是它们的共同盲区。
# v1 只查「错了必渲染失败」三条（不重造解析器）：R1 缺/错图类型头；R2 `-.` 后直接跟 `|`
# （带文字点线合法形态只有 `-.->|t|` 与 `-. 文字 .->`，selftest 证明两种合法形态不误伤）；
# R3 flowchart 的 subgraph 与独占行 `end` 计数配对、sequence 的块起点与 `end` 计数配对。
# 存量基线：接线当日 --all 实测 29 个自有文件 60 块围栏、0 命中 ⇒ **空基线零语料**（还清类
# 先例：id-check-new）；docs/芯片手册/ 是导入转录、围栏不受控，与 doc-links 同排除面不进语料。
# 自证：--selftest 五条（正例含三种合法点线 / 本坑形态必响 / 缺 end 必响 / 假头必响且
# sequence alt-else-end 不误伤 / 基线吞得下且清空后同命中算新发）。
- id: mermaid-syntax
name: "mermaid 围栏语法预检（图类型头 / 非法点线管道 / 块配对）"
entry: python scripts/check_mermaid.py
language: system
files: \.md$
exclude: |
(?x)^(
\.opencode/node_modules/|
Lib/lvgl/|
MDK-ARM/RTE/|
docs/芯片手册/
)
# 数值：README/AGENTS 任务表须与 Src/freertos.c 一致
- id: task-table
name: FreeRTOS 任务表一致性 (D-2/D-7)
name: FreeRTOS 任务表一致性
entry: python scripts/gen_task_table.py --check
language: system
files: ^(README\.md|AGENTS\.md|Src/freertos\.c)$
pass_filenames: false
# 体积：内存/Flash 数字须与最新 .map 一致（D-7 第三档）
# 体积：内存/Flash 数字须与最新 .map 一致（体积档）
# 只在内存文档或代码变动时触发；.map 未生成时脚本自身给出明确提示
- id: mem-numbers
name: 内存/Flash 数字一致性 (D-7 体积档)
name: 内存/Flash 数字一致性（体积档）
entry: python scripts/check_mem_numbers.py --scan
language: system
files: ^(docs/内存管理/.*\.md|scripts/check_mem_numbers\.py|App/.*\.c|App/.*\.h|Src/.*\.c|Inc/.*\.h)$
pass_filenames: false
# 5d) 两份 lv_conf.h 特性子集一致性（2026-10-11 加，随 F-1/F-2/F-3 落地）
# 5d) 两份 lv_conf.h 特性子集一致性（2026-10-11 加）
# 背景：`Lib/lv_conf.h`（MCU）与 `simulator/lv_conf.h`（PC）是两份独立文件，
# 此前长期漂移——模拟器早已 I1-only，MCU 端却让 11 个 `LV_DRAW_SW_SUPPORT_*`、
# 5 个未用控件类、`LV_USE_THEME_SIMPLE`、`LV_USE_FLEX/GRID` 靠 lv_conf_internal
@@ -223,7 +264,7 @@ repos:
# 累计 / 100ms 节流 / tick 回绕）是纯逻辑，板端套件无法穷举边界；本钩子
# 用 MSVC 离线编译真实源文件（#include 纳入）并用可观测桩驱动，秒级、零
# 硬件、不占 MCU RAM。仅在被测文件或其平台层 / 测试变动时触发。
# 详见 docs/测试说明/看门狗单元测试说明.md
# 详见 docs/测试说明/单元测试/看门狗单元测试说明.md
- id: watchdog-unit-test
name: 看门狗判定状态机单测（主机侧）
entry: python test/host/watchdog/run_unit_test.py
@@ -261,7 +302,7 @@ repos:
files: ^(App/cfg/cfg_file\.(c|h)|App/cfg/cfg_file_store\.h|App/log/sys_log\.h|test/host/cfg_file/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7d) 相量层（L2）主机侧单元测试（2026-10-10 加）
# 7d) 相量层（全周傅氏相量）主机侧单元测试（2026-10-10 加）
# 背景：App/algo/ 为**纯算法**层（无寄存器、无 RTOS、无外设依赖），是本项目
# 首个可完全离线验证的算法层。板端**无信号源**，无法注入已知幅值/相位/频率的
# 标准波形，故"读数 = 设定值"这一核心判据在板上不可验；本钩子用 MSVC 离线编译
@@ -275,7 +316,7 @@ repos:
files: ^(App/algo/(phasor|sample_ring)\.(c|h)|test/host/phasor/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7e) ADC 输入层（L1）主机侧单元测试（2026-10-10 加）
# 7e) ADC 输入层（语义取数与有效性）主机侧单元测试（2026-10-10 加）
# 背景：adc_input.c 的核心是"通道号 <-> Rank 顺序 <-> 语义"三者映射的正确性；
# 板端无信号源，无法注入已知电压验证"读到的是哪只脚"（映射说明 §8）。本钩子用
# MSVC 离线编译真实源文件（#include 纳入）+ HAL/TPAFE 可注入桩：给每个 Rank
@@ -304,8 +345,23 @@ repos:
files: ^(App/fs/vol_lock\.(c|h)|test/host/vol_lock/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7f2) 卷空闲同步（写回缓存空闲 flush）主机侧单元测试（2026-10-25 加，道F 批 2）
# 背景：该模块是写回缓存掉电窗口的兜底网——掉电与"脏页驻留"本身台架
# 不可按需构造；卷忙跳过 / ioctl 失败边沿 latch / 32 位 tick 回绕 /
# 失败路径成对放锁（不得空放）全是纯状态逻辑。本钩子用 MSVC 离线编译
# 真实源文件（#include 纳入；桩：可控时钟 + 事件位图 + 卷忙注入 +
# 可注入 disk_ioctl），把四级门与 latch 分支一次钉死。
# files 含被测源与其头、就绪位属主 sys_events 的消费面 default_task.c、
# 以及 harness 本身。
- id: vol-idle-sync-unit-test
name: 卷空闲同步单测（主机侧）
entry: python test/host/vol_idle_sync/run_unit_test.py
language: system
files: ^(App/fs/vol_idle_sync\.(c|h)|App/task/default_task\.c|test/host/vol_idle_sync/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7g) 时间同步（time_sync）主机侧单元测试（2026-10-10 加）
# 背景：time_sync.c 是 TCP 时间同步协议状态机，也是 N-17 号看门狗风险的**全部
# 背景：time_sync.c 是 TCP 时间同步协议状态机，也是探针窗口心跳缺口那项看门狗风险的**全部
# 逻辑贡献者**——"listen 重建 -> 800ms~1s 心跳间隔"由本模块的分片延时/退避/
# 结算等待组成，板端只能看到"是否复位"这一结果，看不到各段延时是否如设计。本钩子
# 用 MSVC 离线编译真实源文件（#include 纳入）+ 可脚本化的网络/事件桩（含 longjmp
@@ -319,7 +375,7 @@ repos:
files: ^(App/sync/time_sync\.(c|h)|App/util/task_watchdog\.h|test/host/time_sync/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7h) ADC 采样有效性校验（L1-6）主机侧单元测试（2026-10-11 加）
# 7h) ADC 采样有效性校验主机侧单元测试（2026-10-11 加）
# 背景：adc_health.c 是"静默/丢帧/序号倒退/错误计数增量"的判定层——这些
# 故障在健康台架上**不可复现**（复现 = 拔芯片/改驱动），板端闭环只能证明
# "健康时不误报"，证不了"故障时必报"；100ms 门限、tick 回绕、事件边沿
@@ -333,7 +389,58 @@ repos:
files: ^(App/algo/adc_health\.(c|h)|App/task/adc_task\.c|test/host/adc_health/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7i) 保护定值模型（P1 / L5-1 载体）主机侧单元测试（2026-10-11 加）
# 7h2) 通道标定层（标定折算，「数据可信」标定折算与落盘整定）主机侧单元测试（2026-10-25 加，道A）
# 背景：标定折算是"码值→工程量"的唯一插入点，Q16 系数/零点两段落盘 +
# 合法带哨兵回退 + 两点标定公式——板端无标准源、坏文件注入路径在真机
# 上难以复现，只有离线端能逐系数钉死。钩子用 MSVC 编译真实源文件
# （#include 纳入；桩：dbg_log / cfg_file_register / adc_input_desc 强符号）。
# files 含被测源与头、系数口径联动的 adc_health/cfg_file/adc_task 消费方，
# 以及 harness 本身。
- id: adc-cal-unit-test
name: 通道标定层单测（主机侧）
entry: python test/host/adc_cal/run_unit_test.py
language: system
files: ^(App/algo/adc_cal\.(c|h)|App/algo/adc_health\.(c|h)|App/cfg/cfg_file\.(c|h)|App/task/adc_task\.c|test/host/adc_cal/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7h3) 量纲回归（「数据可信」"不该动作时不动作"用例，道A）主机侧单元测试（2026-10-25 加）
# 背景：台架曾长期缺"不该动作时不动作"的判据，码值/工程量错配曾以
# 恒假动作的形态混过验收。本钩子用真实链（adc_cal→ring→phasor→
# prot_elm）+ 显式换算的合成波把七类元件的量纲钉死：折算点被旁路
# 或量纲再错位，断言立刻翻转。files 覆盖链上全部生产源与两处编排。
- id: prot-dim-unit-test
name: 量纲回归单测（主机侧）
entry: python test/host/prot_dim/run_unit_test.py
language: system
files: ^(App/algo/(adc_cal|prot_elm|prot_set|phasor|sample_ring|freq)\.(c|h)|App/task/(adc_task|protect_task)\.c|test/host/prot_dim/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7h4) 遥测快照层（全周傅氏相量发布侧，「数据可信」遥测快照发布，道D）主机侧单元测试（2026-10-25 加）
# 背景：遥测快照发布项的 DoD 一半是并发与结构类判据——双区切换无撕裂（撕裂窗
# 200 ms 量级，台架人工比对观测不到）、seq 只增、§4.5 布局与字段偏移
# （104 与 UI 直接按整体拷贝消费，破布局 = 破协议）、CLIPPED 品质汇总
# （削顶位图要等两点标定才真实出现）。主机侧以 #include 原样纳入
# meas/phasor/sample_ring 生产源，合成 9 通道帧序列一次性钉死；
# 读数与注入源比对类判据仍归台架（实测采样类）。files 覆盖被测源、
# 同链核（phasor/sample_ring）、编排方 adc_task 与 harness 本身。
- id: meas-unit-test
name: 遥测快照层单测（主机侧）
entry: python test/host/meas/run_unit_test.py
language: system
files: ^(App/algo/meas\.(c|h)|App/algo/(phasor|sample_ring)\.(c|h)|App/task/adc_task\.c|test/host/meas/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7h5) 运行参数段（「数据可信」道D 交付项）主机侧单元测试（2026-10-25 加）
# 死区把守突发上报的量、104 整定段是现场唯一远程写入口：注册契约、
# 分档量程守卫、两段式、系数直通的合法带与生效值回显必须离线钉死。
- id: run-par-unit-test
name: 运行参数段单测（主机侧）
entry: python test/host/run_par/run_unit_test.py
language: system
files: ^(App/algo/run_par\.(c|h)|App/algo/adc_cal\.(c|h)|App/cfg/cfg_file(_store)?\.(c|h)|test/host/run_par/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7i) 保护定值模型（定值校验和载体）主机侧单元测试（2026-10-11 加）
# 定值是保护动作的"输入宪法"：范围校验、整表装载 all-or-nothing、
# 校验和封存-自检-闭锁（参考 tagPRS dwTagSum/dwTagSumN 模式）必须在
# 任何元件接线之前钉死——板端无法穷举越界定值注入，主机侧毫秒级全跑。
@@ -344,7 +451,7 @@ repos:
files: ^(App/algo/prot_set\.(c|h)|test/host/prot_set/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7j) 保护元件框架（L3 P1 子集）主机侧单元测试（2026-10-11 加）
# 7j) 保护元件框架（保护判据 P1 子集）主机侧单元测试（2026-10-11 加）
# 判据核（滞回/定时限/欠量方向/闭锁联动/时基回绕）是纯逻辑，
# 板端复现需要标准源 + 故障注入，主机侧用合成测量序列即可穷举
# 1.2×/0.9× 验收口径（规划 §8）。
@@ -355,10 +462,10 @@ repos:
files: ^(App/algo/prot_elm\.(c|h)|App/algo/prot_set\.(c|h)|App/algo/phasor\.(c|h)|App/algo/freq\.(c|h)|test/host/prot_elm/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7j2) 频率测量层（L2.5，B8）主机侧单元测试（2026-10-12 加）
# 7j2) 频率测量层（测频与遥测快照，B8）主机侧单元测试（2026-10-12 加）
# 自适应窗测频（K_eff 对齐负序泄漏纹波周期）的 J1~J6 判据
# （扫频/噪声/收敛/阶跃/浮空 valid=0/钳制恢复）是纯合成信号
# 可穷举的精度契约；板端无标准源照不出来（规划 §3.3 L3-5）。
# 可穷举的精度契约；板端无标准源照不出来（规划 §3.3 过频 / 低频）。
- id: freq-unit-test
name: 频率测量单测（主机侧）
entry: python test/host/freq/run_unit_test.py
@@ -366,7 +473,7 @@ repos:
files: ^(App/algo/freq\.(c|h)|App/algo/phasor\.(c|h)|App/algo/sample_ring\.(c|h)|test/host/freq/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7k) SHA-256 主机侧单元测试（2026-10-11 加，N-19 FTP 鉴权）
# 7k) SHA-256 主机侧单元测试（2026-10-11 加，FTP 鉴权）
# sha256 是 FTP pwd_hash 校验的地基——哈希算错是"正确口令被拒 /
# 错误口令放行"的静默语义错误，板端只见 530/230 看不出根因；
# FIPS 180-4 标准向量（空串/abc/56B 补位跨界/1MB）+ hex_eq 非法输入
@@ -378,7 +485,7 @@ repos:
files: ^(App/util/sha256\.(c|h)|test/host/sha256/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7l) FTP 鉴权状态机主机侧单元测试（2026-10-11 加，N-19）
# 7l) FTP 鉴权状态机主机侧单元测试（2026-10-11 加，FTP 鉴权）
# 锁定 60s/解锁/成功清零/tick 32 位回绕是"防口令爆破"契约核心，
# 板端每验一条要真等 60s、回绕要跑满 49.7 天；lftpd_auth 纯函数
# 设计（tick 参数注入）就是为了让这些分支主机侧毫秒级穷举。
@@ -391,22 +498,23 @@ repos:
# 7m) IEC 60870-5-104 被控站协议栈主机侧单元测试（2026-10-12 加，B4）
# APCI 重组/STARTDT/总召分片/COV/k-w-t1~t3/遥控定值两段式/C_CS/错误
# 应答——link 层 tick 注入 + pts 数据源 vtable 抽象就是为 L0.5 全离线
# 穷举设计（A-4 约束 1）；板端复现这些分支要真主站+真等待。
# 应答——link 层 tick 注入 + pts 数据源 vtable 抽象就是为主机侧纯逻辑单测全离线
# 穷举设计（分层约束）；板端复现这些分支要真主站+真等待。
# 触发面含数据源依赖（prot_set/prot_elm/phasor/sample_ring）——测试
# 直接 #include 这些生产源，签名变了要立刻在这里暴露。
- id: iec104-unit-test
name: IEC104 协议栈单测（主机侧）
entry: python test/host/iec104/run_unit_test.py
language: system
files: ^(App/protocol/iec104/iec104_(asdu|pts|link)\.(c|h)|App/algo/(prot_set|prot_elm|phasor|sample_ring|adc_input|freq)\.(c|h)|test/host/iec104/.*|test/host/common/unit_test_harness\.py)$
# 运行参数段落地起本 TU 链入真实 cfg_file/adc_cal/run_par（板端真源链），触发面同步扩
files: ^(App/protocol/iec104/iec104_(asdu|pts|link)\.(c|h)|App/algo/(prot_set|prot_elm|phasor|sample_ring|adc_input|freq|meas|adc_cal|run_par)\.(c|h)|App/cfg/cfg_file(_store)?\.(c|h)|test/host/iec104/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7m2) SOE 动作记录编解码主机侧单元测试（2026-10-12 加，B9）
# 64 B 定长记录（类型/seq/CP56Time2a/epoch/校验和）是磁盘上的
# 字节级契约——编解码错了要 FTP 下载+解码才看得见；纯 codec
# 零平台依赖（soe_store 胶水 SIM_EXEMPT），主机侧穷举往返/
# 截断/坏校验/IV 位/seq 连续性（规划 §3.4 L4）。
# 截断/坏校验/IV 位/seq 连续性（规划 §3.4 出口与记录）。
- id: soe-unit-test
name: SOE 动作记录编解码单测（主机侧）
entry: python test/host/soe/run_unit_test.py
@@ -414,13 +522,49 @@ repos:
files: ^(App/log/soe_rec\.(c|h)|App/log/soe_store\.(c|h)|test/host/soe/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7n) dhara NAND 移植层（nand_ftl）主机侧单元测试（2026-10-15 加）
# 背景：移植层六个 HAL 入口是**纯地址算术**，此前对越界页/块号（含
# DHARA_PAGE_NONE 哨兵）**不做任何上界校验**——加偏移送进 SPI 命令后被地址位
# 截断成某个真实页 → 静默读写/搬走无辜数据；而 is_free 旧实现只看页首 64 B，
# 会把"页首 0xFF、后段有数据"的已编程页误判空闲 → dhara 往已编程页再编程
# = 数据丢失。两类缺陷真机**极难复现**（要恰好撞上特定页形态 / 被污染的 meta），
# 板端只能表现为"某次复位后丢数据"，无从定位。
# 本钩子用 MSVC 离线编译真实 nand_ftl.c（#include 纳入）+ **RAM 假芯片**
# （32 块 x 64 页 x 2048 B）：把"双编程"做成可数事件、记录全部
# 访问次数，于是"越界不产生任何芯片访问""越界标坏块次数为 0"可机械断言；
# 并内联一份"只看页首 64 B"的旧算法做对照，证明这组断言真能咬人。
# 触发面含 dhara 本体（测试一并 #include map.c/journal.c 跑真链路场景）。
- id: nand-port-unit-test
name: dhara NAND 移植层单测（主机侧）
entry: python test/host/nand_port/run_unit_test.py
language: system
files: ^(Drivers/BSP/GD5F2GQ5UE/nand_ftl\.(c|h)|Drivers/BSP/GD5F2GQ5UE/gd5f2gq5ue\.h|Lib/dhara/(map|journal|nand|error|bytes)\.(c|h)|test/host/nand_port/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 7z) UI 数据快照层（道E task-14）主机侧单元测试（2026-10-25 加）
# 背景：ui_data 是"页面看到的整个世界"，但 ui-golden 只覆盖已接线的页面——
# 遥信 27 点、定值 40 项、遥测未接线的通道错了不会让任何参考图变红。本钩子
# 用 MSVC 离线编译真实 ui_data.c 与 ui_w_soe.c（#include 纳入，零桩），把两件事
# 钉死：① 快照存储语义（首帧前读 -1 / 序号由本层盖章 / 三通道互不串台 /
# NULL 防御）；② 跨层不透明下标与显示名映射的**现场一致性**——测试单元在同一
# TU 里同时 include BSP 侧与 App/algo、App/log 真头，逐项比对 adc_semantic_t /
# prot_set_id_t / soe_type_t / prot_elm_id_t（解耦换来的"魔法下标"风险，口径
# docs/UI设计/UI_数据供给设计说明.md §9.4；SOE 类型含未标定闭锁=7/复归=8）。
# files 覆盖被测两件 + 编号真源四头 + 页面消费面（ui_content_page/ui_menu*）+ harness。
- id: ui-data-unit-test
name: UI 数据快照层单测（主机侧）
entry: python test/host/ui_data/run_unit_test.py
language: system
files: ^(Drivers/BSP/UI/(ui_data|ui_w_soe|ui_w_records|ui_content_page|ui_menu)\.(c|h)|App/app/ui_data_feed\.(c|h)|App/algo/(adc_input|prot_set|prot_elm)\.(c|h)|App/log/soe_rec\.(c|h)|test/host/ui_data/.*|test/host/common/unit_test_harness\.py)$
pass_filenames: false
# 8) 测试套件开关门禁（2026-10-01 加）
# 背景：test_config.h 的 TEST_SUITE_* 决定固件里编入哪个测试套件，
# 全部注释 = 产品构建。但此前**无任何门禁检查**——实测已提交的 HEAD 里
# TEST_SUITE_CH395F 就是开启状态（.map 含 34 处 test 代码），即仓库里
# 躺着的是测试固件。本钩子抓这个静默漏网：默认要求产品构建，跑套件回归
# 确需提交测试构建时用 `--allow-test-build` / ALLOW_TEST_BUILD=1 显式放行。
# 详见 docs/任务规划/登记簿.md T-1
# 详见 docs/任务规划/登记簿.md
- id: test-suite-switch
name: 测试套件开关=产品构建
entry: python scripts/check_test_suite.py
@@ -428,7 +572,7 @@ repos:
files: ^test/board/test_config\.h$
pass_filenames: false
# 9) 双端注册反向校验（2026-10-12 加，登记簿 N-23 / 审查报告 N-06 残余）
# 9) 双端注册反向校验（2026-10-12 加，登记簿条目「rs485_task 白名单缺口」）
# 背景：新 .c 必须手动注册两处（`MDK-ARM/*.uvprojx` + `simulator/CMakeLists.txt`）
# 才会被编译；历史上 `App/task/rs485_task.c`、`Drivers/BSP/NET/lftpd/lftpd_log.c`
# **两处都没注册** = 写了却从不参与任何一端编译的**死代码**，误导读者以为功能已生效。
@@ -445,17 +589,277 @@ repos:
language: system
files: (\.c$|\.uvprojx$|CMakeLists\.txt$|^scripts/check_registration\.py$)
pass_filenames: false
# 10) RAM 预算 92% 阈值门禁（2026-10-12 加，登记簿 N-27 前半 / 审查报告 §5.5 三件套）
# 10) RAM 预算 92% 阈值门禁（2026-10-12 加，登记簿条目「缩堆迁 CCM 后半（暂缓）」的台账/门禁那半 / 审查报告 §5.5 三件套）
# 背景：报告 §5.5 第 1 条要求"超阈值即失败 + Top-10 附表"——此前 mem-numbers 只防
# "文档数字漂移"，**没有任何机械检查拦"占用超阈值"**；台账三件套（ram_baseline.py +
# ram_baseline.tsv + docs/内存管理/RAM预算台账.md）落地后，本钩子把 92% 红线机械化。
# 逻辑：RW_IRAM1/RW_CCM 任一 >92% → FAIL + Top-10 RW+ZI 对象表；台账受管区漂移 → FAIL
# （提示 --write）；无 .map → 自适应跳过（同 mem-numbers 在 CI 的行为，盲区登记 A-5 残余）。
# （提示 --write）；无 .map → 自适应跳过（同 mem-numbers 在 CI 的行为，盲区已登记）。
# ⚠ pre-commit 4.x 无 `always: true` → files 覆盖所有能改变 RAM 的触发面：
# 全部自研代码目录 + lv_conf.h + 测试板配置 + 脚本/tsv/台账自身 + 本配置文件。
- id: mem-budget
name: RAM 预算 92% 阈值门禁 (N-27)
name: RAM 预算 92% 阈值门禁
entry: python scripts/ram_baseline.py --gate
language: system
files: ^(App/|Drivers/BSP/|Src/|Inc/|Lib/lv_conf\.h|test/board/|scripts/ram_baseline\.|docs/内存管理/|\.pre-commit-config\.yaml$)
pass_filenames: false
# 11) UI 字符集差集检查（2026-10-15 加，报告 §6.5 的 UI 字符集与像素回归门禁残余 / §7 交付物清单"字符集差集检查"行）
# 背景：`ui_font_cn_12.c` 是**子集**字体，只含 `ui_cn_chars.txt` 列出的码位。
# 生成链 UI 源码 --extract_cn--> ui_cn_chars.txt --make_font--> 字体 .c，其中
# verify_coverage 只在**生成期**校验"txt ⊆ cmap"；改完 UI 字符串忘了重跑
# font-regen 就提交 → 缺字上机渲染为空白（白框），无日志无报错只能肉眼截图发现
# （font-regen skill 的"缺字渲染为空白"约定，此前纯靠自律）。本钩子把它机械化：
# A. 源码在用 vs txt 缺 → FAIL（白框方向）；多 → WARN（只费 Flash，--strict 升级）
# B. txt vs 字体 cmap 缺 → FAIL（lv_font_conv 对缺字形/低码位**静默丢字**）
# A 过 + B 过 ⟹ 字体 ⊇ 源码每个在用字。提取与 cmap 解析**复用** tools/font_gen
# 两个生成器的同一套规则（importlib 直载 extract_cn.SCAN/collect + make_font.
# verify_coverage），杜绝第二套解析规则漂移（§5.5 同类教训）。
# ⚠ pre-commit 4.x 已移除 `always: true` → files 必须覆盖全部触发面：
# UI 源码（含字体 .c 自身）+ ui_task.{c,h} + 字符集 txt + 两个生成器 + 本脚本。
- id: font-charset
name: UI 字符集差集检查（防缺字白框）
entry: python scripts/check_font_charset.py
language: system
files: ^(Drivers/BSP/UI/|App/task/ui_task\.(c|h)$|ui_cn_chars\.txt$|tools/font_gen/|scripts/check_font_charset\.py$)
pass_filenames: false
# 12a) BOM 漂移门禁（2026-10-25 道E task-20）
# 背景：AGENTS 铁律第 2 条——编辑工具会**静默剥掉**文件原有 BOM，ARMCC 于是按 CP936
# 解码带中文的源文件，报 #870-D / #8 / #274 一类**假语法错**（报错位置与内容都不指向
# 真因），而 MSVC（模拟器侧）与既有钩子全照不出来。2026-10-25 一天内道E 踩 4 次、
# 道B 批 1 踩 1 次，此前全靠人工逐文件比 HEAD 兜底——人工审计只防得住记得做的人。
# 判定：HEAD 有 EF BB BF 而工作区没有 → FAIL。两条刻意不报（新增文件无 BOM、HEAD 无
# BOM 而工作区加了 BOM）与一条刻意不做（不自动补：整文件重写正是本仓更大的坑）都
# 写在脚本头部。files 与 AGENTS 名单、脚本内 BOM_LIST **三处互指**，脚本每次跑核一次，
# 单独改任何一处都会在别人的提交里被拦下——名单散在三处而无人同步等于没有名单。
- id: bom-guard
name: BOM 漂移检查（带 BOM 文件被剥掉即拦）
entry: python scripts/check_bom_drift.py
language: system
files: ^(Drivers/BSP/UI/|App/task/ui_task\.c$|App/cfg/cfg_file\.c$|Lib/lv_conf\.h$)
# 12b) 定值查看行表一致性（2026-10-25 道E task-20 追加批；脚本随 task-15 批 3 落）
# 核 Drivers/BSP/UI/ui_w_setview.c 的四张视图表与 App/algo/prot_set 的枚举序、
# g_prot_set_meta 上下限是否仍是同一份口径：id 恰好覆盖 0..39 各一次、数值行
# min/max 等于 meta 换算、kind 与 meta.is_ctl 一致、单位纯 ASCII、小数位查表与行表
# 一致。为什么必须机械化：BSP 侧看不到 App 头，行表里的 id 是裸数字 + 行尾注名，
# 这条对齐在编译期**物理上无法自证**；而页面上只有当前可见的 8 行会被像素断言看到，
# 错位要翻到第 2、3 页才可能被人发现（发现了也已被基线钉死）。
# ⚠ 跨分支先后：脚本文件随 task-15 分支合入主干；在此之前 files 永不命中 → 钩子自然
# skip（skip 不是失败），合并后自动生效，不需要任何人再动这条配置。
- id: setview-check
name: 定值查看行表与 prot_set 枚举/上下限一致性
entry: python tools/setview_check/check_setview_limits.py
language: system
files: ^(tools/setview_check/|Drivers/BSP/UI/ui_w_setview\.(c|h)$)
pass_filenames: false
# 12) UI 像素回归门禁（2026-10-20 加，W6 的 UI 字符集与像素回归门禁收尾第三件 / 报告 §6.5 同项、§6.1 golden 行）
# 背景：golden 两脚本（check_menu_rows.py / check_content_pages.py）早已存在且一直在
# 人工跑，但**从未进自动门禁**——"有基线"不等于"有门禁"（报告 §6.1 原文即自认此缺口）。
# 形态选型依据实测：改一个 UI 源文件后 build_sim 增量重编 + 两条 golden 合计 **2~4 秒**，
# 成本可接受 → 走自动门禁（若实测要几分钟，则应改为文档化人工门禁，一个逼人
# --no-verify 的门禁等于没有门禁）。
# 有牙实测：给 ui_page_dc.c 的 .top_y 注入 +3 位移 → build_sim 重编 →
# golden FAIL 且点名 `[dc] FAIL 与参考页不一致（1366 px 差异）`、退出码 1；还原后 diff 干净。
# ⚠ 两条 golden 按"整棵菜单树 + 全量参考图"工作、不接受文件参数，故包装器有意忽略
# argv 并 pass_filenames: false（pre-commit 传的变更名对它无意义）。
# ⚠ 参考图 simulator/tests/ref/*.bin 是判据本身，改动它等于改判据——它已入库，
# 评审时看 `git diff -- simulator/tests/ref` 必须逐页过目并在提交正文说明；
# 任何时候都不得用 --update 刷基线来"让钩子变绿"。
# ⚠ pre-commit 4.x 无 `always: true` → files 必须覆盖所有能改变像素的触发面。
# ⚠ 已知瞬时现象：首次实测时在"连续注入/还原的紧邻重建"之间偶发失败一次，
# 疑似 MSBuild 节点争用；此后 3 次干净树连跑均绿。判据：单次失败先复跑一次再看，
# 连续两次失败才当真（不许直接 --no-verify 绕过）。
- id: ui-golden
name: UI 像素回归（菜单 8 状态 + 内容页 66 张 黄金参考）
entry: python scripts/check_ui_golden.py
language: system
files: ^(Drivers/BSP/UI/|App/task/ui_task\.(c|h)$|simulator/(tests|sim|src)/|simulator/main\.c$|simulator/CMakeLists\.txt$|simulator/lv_conf\.h$|scripts/check_ui_golden\.py$|\.pre-commit-config\.yaml$)
pass_filenames: false
# 12a) 板端 UI 导航器认屏自检（2026-10-25 道E task-25）
# 背景：大窗实测——靠预置键序盲走到深页时，9 帧里只有 3 帧真是它声称的态；
# KEY 的 ACK 是空应答、不携带状态，所以**画面是唯一事实源**。判据脚本
# scripts/board_ui_nav.py 据此改成闭环：每按一键重新认屏再决定下一个键。
# 本钩子跑它的**快检档** --selftest-quick：只核"认屏认得对"（接线当时 18 张、现 66 张黄金参考 +
# 真机留档帧，目录不在版本控制里、缺就整段跳过），秒级、无构建产物依赖。
# ⚠ 不挂完整 --selftest：第三段闭环需要 lvgl_sim.exe（构建产物，新工作树里没有）
# —— 正是同一天 mem-numbers 缺 .map 那课的形状；脚本对缺 exe 报 FAIL 并给出
# 可执行提示，不"跳过当通过"。合入前 / 上板前手工跑一次完整档：
# python scripts/board_ui_nav.py --selftest（约 30 s，含全绑定页闭环）。
# ⚠ 触发面刻意只两块（脚本自身、黄金参考帧）：字体或菜单树变动**不**触发它，
# 那两类的守卫分别是 font-charset / ui-golden / registration-check 与 id 侧；
# 把每个 UI 提交都拉去跑导航器，只会让人习惯等一个与本改动无关的钩子。
- id: uinav-selftest
name: 板端 UI 导航器认屏自检（快检：黄金参考帧分类）
entry: python scripts/board_ui_nav.py --selftest-quick
language: system
files: ^(scripts/board_ui_nav\.py$|simulator/tests/ref/.*\.bin$)
pass_filenames: false
# 13) 编号门禁的历史：2026-10-20 起曾有一版「全库语料审计」（规范 §8 的 8 项校验 +
# 99 族 registry + 别名表）。它 2026-10-28 退役——维护成本高过收益（近 80 笔提交
# 61 笔被编号体系牵连），脚本与语料整体移入 `scripts/archive/id_gate/`
# （保留可复现性，**不再进提交门禁**）。退役路线与判据替换见规范 §8.5。
# 14) 编号门禁（2026-10-28 上线只查新增行那一道；2026-10-29 用户裁定**整体退役**，钩子已摘）
# 退役后编号形态没有机器面：判据回到 docs/编号规范.md §1 三句自问 + §4.1 族总表 + 评审。
# 脚本移入 scripts/archive/id_gate/check_ids_new.py（手工可跑，--self-test 保留），留档说明
# → docs/门禁说明/id-check-new.md；手工普查与恢复机器面 → docs/编号规范.md §8.5。
# ⚠ 计数口径：本条摘除使 YAML 解析条目 52 → **51**，须与 AGENTS.md 的「共 N 个钩子」、
# docs/门禁说明/README.md §2 标题三数同源同批改（自查命令见该条；别在注释里写数钩子的字面量）。
# 14) 分层方向门禁（2026-10-22 加，结构债的"防扩大"那一半）
# 背景：AGENTS.md 与 项目架构总览.md 早就写着"六层单向依赖"，但**从来没有机械检查**
# ——Drivers/BSP/ 里可以随手 include "cfg_file.h" 而无人报警。后果可测量：2026-09 审查
# 报告记"NETCFG 一处"，2026-10-22 实测已长到 **8 个文件 9 处**。边界的静默腐蚀只能
# 靠门禁止住，所以本钩子做**增量拦截**（与 id-check 同构）：现状 6 条钉成 BASELINE
# （只减不增，没有 --write 往里加），新出现的 (BSP 文件, App 头) 组合直接 FAIL；
# 3 条横切基础设施头走 ALLOW 永久豁免（日志后端 / 时间源 / 纯算法工具——它们是
# 任何层都要用的叶子能力，不是上层服务）。修完存量后跑 --prune 会点名让你收紧基线，
# 于是"还欠几条"变成可见进度，而不是文档里的一句口号。
# 注：本钩子只拦"静态 include 方向"；**运行时的属主纪律本来就没错**（UI 只投递
# net_cfg_save_request()，写盘在 defaultTask），别把它当缺陷读。
# 扫描范围恒为全库（要跨文件建 App 头索引），故 pass_filenames: false。
- id: layer-deps
name: 分层方向（BSP 不得反向 include App）
entry: python scripts/check_layer_deps.py
language: system
files: ^Drivers/BSP/|^scripts/check_layer_deps\.py$|^\.pre-commit-config\.yaml$
pass_filenames: false
# 15) BSP 错误码与超时命名约定（机械检查那一半）。
# 四项检查：公开 API 不得用 HAL_StatusTypeDef/bool 当错误通道（谓词 is_/has_/can_/valid
# 不在此列）；*_TIMEOUT 宏不得取负值（名字叫 TIMEOUT 其实是返回码）；非 void 的公开 API
# 必须有「返回值：」注释；**返回错误码的函数不得裸丢弃返回值**（接住或显式 (void)——实测
# ARMCC v5 与 cppcheck 都不报这类，只有这条会响）。存量钉 BASELINE、只减不增（2026-10-23
# 首清点 19 条 → 已还 18；新增一项又暴露 37 条 → **现 38 条**：37 丢弃 + 1 个 bool 待改签名），
# 修完跑 --prune 点名收紧基线。约定正文 = Drivers/BSP/bsp_err.h，规则说明 =
# scripts/check_bsp_err.py 文件头，逐项详解（含限制与盲区）= docs/门禁说明/bsp-err.md。
# 恒扫全库（要按 git 清单建公开头索引），故 pass_filenames: false。
- id: bsp-err
name: BSP 错误码与超时命名约定
entry: python scripts/check_bsp_err.py
language: system
files: ^Drivers/BSP/|^scripts/check_bsp_err\.py$|^\.pre-commit-config\.yaml$
pass_filenames: false
# 8) 主机单测覆盖率总闸（2026-10-24 接线，用户裁定选 FAIL 语义）
# 为什么现在才挂：接线前本文件只有 16 个 *-unit-test 钩子，而仓库已有 28 套主机单测——
# P1 新增的 12 套不在任何提交钩子里。原先"再加一份全量插桩等于同一件事做两遍"
# 这条理由到现在已经**反了**（现状是有一遍没做），所以必须挂；缺口此前如实登记在
# docs/测试说明/单元测试/主机单测覆盖率口径.md §8。
# 为什么挂这一根而不是补 12 个 per-module 钩子：本钩子当时跑**全部 28 套**（现值 47 套，台账见
# docs/门禁说明/host-unit-tests.md §6 第 4 条），并且守 §5 的
# 回退台账（某套被删、或某文件的已覆盖行变少 → [REGRESS] 直接红）。这是 per-module
# 钩子做不到的——删掉一套测试，它那根钩子只会因为"没有文件要检查"而静默跳过。
# ⚠ FAIL 语义（用户裁定 2026-10-24）：找不到 mscoverage 时脚本退出码 2 → 本钩子**失败**，
# 不做 skip。理由：skip 等于造一根会静默失效的门禁（与 pre-commit 4.x 移除 always: true
# 是同一类坑）；宁可在没装组件的机器上被挡一次、看清 [ENV] 那行提示，也不要一根假绿的闸。
# 本机与 CI runner 同一台；实测两份 VS 安装都自带该 exe（口径 §7 第 8 条已按实测更正）。
# 口径 / 分母 / 基线 / 盲区详解都在 docs/测试说明/单元测试/主机单测覆盖率口径.md，本处只留接线事实。
# 触发面**含门禁自身**（.pre-commit-config.yaml）：不带自身就等于谁改坏这根闸的 files:
# 模式，它就再也不跑且无人察觉（同 lv-conf-sync / bsp-err 的既有做法）。
# ⚠ stages: [manual]（2026-10-28 用户裁定）：本钩子跑光全部 47 套单测（41 套时实测 ~105 s，套件数
# 涨了耗时就涨，47 套这轮未重测耗时；
# 占一次带代码提交耗时的三分之二）→ 不压在提交期，由**远端 CI** 强制
# （.gitea/workflows/ci.yml 的「手动阶段门禁（覆盖率总闸 + 全量 cppcheck）」步），本地等价入口 =
# scripts/ci_local.py（manual 段）；手工复跑：
# python -m pre_commit run --all-files --hook-stage manual test-coverage
# 另：此前它没写 stages: → 默认属于所有阶段，同一次提交输出里出现两次（commit-msg
# 阶段那遍几乎必然 Skipped，只看结尾会把实跑读成"没跑"）。固定 manual 阶段后不再有这一坑。
- id: test-coverage
name: 主机单测覆盖率（增量拦截：已覆盖行只增不减）
stages: [manual]
entry: python scripts/check_test_coverage.py
language: system
files: ^(App/|Drivers/BSP/|test/host/|scripts/check_test_coverage\.py|scripts/test_coverage_baseline\.json|\.pre-commit-config\.yaml$)
pass_filenames: false
# 16) 生成器幂等性（2026-10-26 加，task-18；判据正文 docs/文档规范.md §4.4，索引行见 docs/门禁说明/README.md）
# 背景（实证，不是预防性）：0f7b5a87 改了 tools/menu_gen/gen_menu.py 的**模板文字**却没重跑
# 生成物 → HEAD 里 Drivers/BSP/UI/ui_menu_tab.h 与模板不一致，后来是别人重跑生成器才被顺带
# 纠正（属主确认以生成器输出为准）。接线前实测又扫出 **5 张 docs/images/*.svg** 与各自生成器
# 不一致（文档挪目录后 rename_ref.py 只改了 tools/ 里的引用路径、产物没跟着重跑）——生成物
# 比生成器旧是**系统性**缺口。隐蔽之处：改生成器的人看不到任何 diff（脚本改动编译、单测全过），
# 下一个**碰巧**重跑的人却看到一段「不是我改的」改动 → 要么连带提交、要么 revert 掉真修复。
# 判定：把声明的输入与生成器脚本一起拷进**系统临时目录**重跑（三个生成器都按 __file__ 的三级
# 父目录定位仓库根 → 只会写 temp），再逐字节比对 temp 与工作区：DIFF / NEW / 生成器报错 = FAIL。
# **仓库一个字节都不写**，因此不需要还原、也不会 stash 别人在飞的改动（多人同树可安全跑）。
# 覆盖：gen_menu（含它回写的 uvprojx + CMakeLists 两份注册表）、中文字库链（extract_cn →
# ui_cn_chars.txt、make_font → ui_font_cn_12.c）、tools/arch_diagram 全部配图生成器。
# 一处刻意不按裸字节比对：ui_cn_chars.txt 按 font-regen 约定 = 源码在用 ∪ KEEP_EXTRA，改判
# 「txt 恰等于 重跑 ∪ KEEP_EXTRA」（两向都不许差；清单 importlib 直载 scripts/check_font_charset.py，
# 不留第二份清单）。存量基线 = 接线当天已漂的那 5 张 SVG，钉进脚本内 BASELINE 走 WARN 不拦提交
# （只减不增，还清即删、默认运行会点名）；业务生成物（菜单表 / 页面注册表 / 字库 / 双端注册表）
# **零豁免面**，漂了就是 FAIL。
# ⚠ entry 是裸 python，而 pre-commit 在提交环境里可能把它解到**机器级**解释器：2026-10-26 真实提
# 交实测解到 C:/Python314（无 fontTools）→ 字体链报 No module named fontTools = 假红。所以脚本
# 自己按「显式 DTU_GEN_PYTHON > 当前解释器 > 仓库 .venv > PATH」解析并**逐个探针校验**（要真能
# import fontTools 才算数），整轮统一用同一个解释器；挑不出来打 [ENV]+候选表+修法、退出码 2 不
# SKIP。不把 entry 写死成 .venv 路径：那是 ci_local 2026-10-11「候选收窄 → runner 上静态门禁全灭」
# 的同一条坑（详解 docs/门禁说明/generated-fresh.md §4）。
# ⚠ 字体链外部工具（node + 全局 lv_font_conv + 系统 simsun.ttc / seguisym.ttf）缺失时该项 SKIP 并
# 打印 [SKIP]，--strict-env 才升 FAIL——与 test-coverage「缺 mscoverage 必 FAIL」刻意不同：
# 缺工具的机器上没有可执行的修法，SKIP 至少把「这台没验过」留在输出里（盲区同登记在索引行）。
# ⚠ pre-commit 4.x 已移除 always: true → files 必须覆盖全部触发面：任何生成器（tools/）、
# 生成器的输入（Drivers/BSP/UI 源码、App/task/ui_task、ui_menu_tree.txt、ui_cn_chars.txt）、
# 生成物（docs/images/*.svg + 两份注册表）、脚本自身与本配置文件（同 registration-check 口径）。
- id: generated-fresh
name: 生成器幂等性（重跑到临时目录 → 与工作区逐字节一致）
entry: python scripts/check_generated_fresh.py
language: system
files: ^(tools/.+|Drivers/BSP/UI/.+|docs/images/.*\.svg|App/task/ui_task\.(c|h)|ui_menu_tree\.txt|ui_cn_chars\.txt|MDK-ARM/STM32F407-Demo\.uvprojx|simulator/CMakeLists\.txt|scripts/check_generated_fresh\.py|scripts/check_font_charset\.py|\.pre-commit-config\.yaml)$
pass_filenames: false
# ── 块注释嵌套（第 51 条，2026-10-27 加，task-29）─────────────────────────────
# 查什么：C/C++ 块注释体内再出现 /* —— ARMCC 诊断 9-D「nested comment is not allowed」。
# 本仓的诱因是「在注释里写作用域 / 通配路径」这种常态写法：Drivers/BSP/UI/** 里那个
# /* 就是第二次注释的起点（C 的块注释不嵌套）。
# 为什么要闸：它**只在重编译那个 TU 时才暴露**，历史「0 警告」不代表安全；而且按包含者
# 数量刷屏——一份被广泛 include 的头里一处嵌套 = 每个包含者一行警告（实测一例扩散到 16
# 条，把整批真警告挤到看不见）。有了这根，提交时就报，不用等 /keil-build。
# 接线当日实证（冻结引用，别去翻构建日志——它每次 /keil-build 就被覆盖、也不入库）：当日 02:22
# 那次构建日志报过 ..\App\algo\run_par.c(267): warning: #9-D: nested comment is not
# allowed ——那是别人**未提交**的在飞状态。原文抄在 docs/门禁说明/nested-comment.md §2.1；
# 已提交历史回放 281 份旧字节 0 命中 ⇒ 这类问题一直靠人工在编译后清，从没被机器拦过。
# 存量基线（只减不增，除这 2 处外**零豁免**）：全仓 --all 实扫 403 个 C/H，新发 0，存量
# 2 处 = test/host/common/ch395f_fake.h:7 与 fatfs_fake.h:9（注释里写 test/host/**，属
# test/ 写域，等那侧改成语义短语；还清后删 BASELINE 行，--prune 打台账）。
# 自证：--selftest 四项（正例照得出 / 字符串与行注释不误报 / 基线吞得下 / 只减不增有牙），
# 另有 10 项形态电池（含「注释里写 UI/*」「块注释内行首再开 /*」等真形态）。
# ⚠ 计数口径：本条使 YAML 解析条目 50 → **51**；配置里那条被注释掉的 clang-format 候选仍
# 在，所以**按文本 grep 声明行会得 52**（多算那条候选）——那不是口径。本行刻意不复现那个字面量，
# 否则注释自己也会被 grep 数进去（2026-10-27 实测踩过：写过一次，计数立刻虚高 1）。
# 口径与自查命令见 docs/门禁说明/README.md §2 首条。
- id: nested-comment
name: "块注释体内不得再出现 /*（ARMCC 9-D 嵌套注释）"
entry: python scripts/check_nested_comment.py
language: system
types: [c]
# ─── SKILL.md 体积与 reference/ 指针门禁（第 52 条，2026-10-29 加）─────────────────────
# 为什么要有：dsh-mnemon 插件对技能正文有 65536 字节的**写侧**硬上限（validateSkillContent），
# 但**加载侧不查**——超限的 SKILL.md 照常可读、照常进技能目录，只有一件事会坏：自进化每次
# 「生成草案」都在落盘那一步被拒，那一行永久卡在「生成中」、界面只剩转圈、连「忽略」都不出现
# （Draft/Dismiss 只在 pending 渲染）。实测 2026-10-29 一天内两个技能各卡一次（第二个 72,601
# 字节），每次白烧一个 30 分钟的草案 Agent。**在加这根之前，仓库里没有任何一处会告诉你某个
# 技能已经废了**——文件能读、能改、能提交，全绿。
# 判据：> 65536 FAIL（与插件同数、同口径：utf-8 字节数不是字符数）；>= 49152（75%）WARN 不拦
# （越线通常只隔一次草案采纳：实测 49821 → 62806）；正文里 (reference/xxx.md) 指向的文件不在
# → FAIL；带 UTF-8 BOM → FAIL（插件按 utf-8 解析，BOM 会让 frontmatter 读歪）。
# 全树扫不只看变更文件：钩子拿到 filenames 只当触发用，判定始终扫整个 .dsh/skills/——因为改
# reference/*.md 时 SKILL.md 没动，但它可能正是被那次外置撑过线/掏空的那一份。
# 为什么 entry 敢用裸 python：AGENTS.md「钩子 entry 的裸 python 不等于 .venv」那条教训针对的是
# 第三方依赖（fontTools）；本脚本纯标准库，任意 python3 均可（实测 .venv 3.12 与 PATH 上 3.14
# 都跑通），所以不需要脚本内再自解析解释器。
# ⚠ 盲区：只管仓库内 .dsh/skills/；用户级 ~/.dsh/skills/ 不在仓库里，本钩子照不到（手工
# `node "$HOME/.dsh/scripts/mnemon-skill-ledger-doctor.mjs" --root .` 或本脚本 --root 都只报，
# 要拦得另配 shell 钩子）。只认 markdown 链接形态的指针，纯文本里写的路径不算。
# 自证：--selftest 五形态（干净 0 / 75% 线 0 带 WARN / 超上限 1 / 悬空指针+BOM 1 / 根不存在 2）。
# 详解与限制 → docs/门禁说明/skill-size.md。
- id: skill-size
name: "SKILL.md 不超插件写侧上限 65536 且 reference/ 指针不悬空"
entry: python scripts/check_skill_size.py
language: system
files: ^\.dsh/skills/
.serialtest/config.json
+1 -1
View File
@@ -1,5 +1,5 @@
{
"portName": "COM6",
"portName": "COM3",
"baudRate": 115200,
"flash_cmd": ".venv\\Scripts\\python.exe .dsh\\skills\\stlink-flash\\scripts\\stlink_flash.py flash",
AGENTS.md
+42 -35
View File
File diff suppressed because one or more lines are too long
App/README.md
+2 -2
View File
@@ -13,10 +13,10 @@ FreeRTOS/CMSIS-RTOS API**（见 `AGENTS.md`「平台约束」）。
| 目录 | 内容 | README |
|---|---|---|
| `app/` | **应用入口与全局**：`app_main.c/h`（初始化入口）、`app_cfg.h`（编译开关）、`sys_events.h`（就绪事件） | [`app/README.md`](app/README.md) |
| `app/` | **应用入口与全局**：`app_main.c/h`（初始化入口）、`app_cfg.h`（裁剪决策占位说明，当前无宏）、`sys_events.h`（就绪事件） | [`app/README.md`](app/README.md) |
| `cfg/` | **配置引擎**：`/config.ini` 解析 + 原子持久化（旧二进制档已废弃，2026-10-10） | [`cfg/README.md`](cfg/README.md) |
| `sync/` | **时间同步任务**：`time_sync.c/h` | [`sync/README.md`](sync/README.md) |
| `algo/` | **采集与算法层（L1/L2）**：`adc_input.c/h`（语义通道映射 + STM32 ADC1 扫描） | [`algo/README.md`](algo/README.md) |
| `algo/` | **采集与算法层**：语义取数 + 有效性判定 + 采样环/相量/测频 + 定值模型 + 保护元件框架 | [`algo/README.md`](algo/README.md)（索引）；设计 → `docs/算法/采集与算法层设计说明.md` |
| `log/` | **日志子系统**：syslog（NAND）+ 控制台单写者日志 | [`log/README.md`](log/README.md) |
| `task/` | **FreeRTOS 任务实现**（6 个任务） | [`task/README.md`](task/README.md) |
| `util/` | **通用工具**：CRC / 环形缓冲 / 墙钟时间 | [`util/README.md`](util/README.md) |
App/algo/README.md
+240 -335
View File
@@ -1,360 +1,265 @@
# App/algo/ — 采集与算法层（L1 / L2）
# App/algo/ — 采集与算法层（语义取数与有效性 / 全周傅氏相量 / 保护判据）
> **自研代码**，属 `docs/算法/继电保护功能复现规划.md` §2.1 分层中的 **L1（采集与预处理）**
> 与 **L2（相量计算）**。原则：**算法与 I/O、与调度分离**——本层不建任务、不做保护判据、
> 不碰寄存器（唯一例外见 §3.1），只做"数"（原始码值 → 语义通道）与"相量"
> （采样序列 → 复相量），因而可被主机侧单元测试（L0.5）离线全覆盖（落实登记簿 **A-4**）。
>
> 任务侧（`App/task/adc_task.c`）只做**消费与编排**；任何新算法一律落在本目录，勿塞进 `App/task/`。
> 本目录的**索引**：文件清单、依赖、逐文件的"改代码必须知道"、构建与测试入口、新增模块动作。
> **详细设计——机制、契约、判据、为什么这样设计 → `docs/算法/采集与算法层设计说明.md`**（本文不复制其内容）。
> 分层归属与功能项状态 → `docs/算法/继电保护功能复现规划.md` §2.1；
> 通道映射唯一权威 → `docs/硬件平台/ADC通道映射说明.md`；采样节拍 → `docs/子系统设计/ADC采样节拍设计说明.md`。
## 1. 文件清单（一眼版）
| 文件 | 层 | 作用（一句话） | 主要对外入口 | 覆盖规划项 |
|---|---|---|---|---|
| `adc_input.h` / `adc_input.c` | L1 | **统一语义取数层**：把两片转换器的原始码值按语义（`UA…IN`/温度）暴露，并消费 STM32 ADC1 的 DMA 乒乓双缓冲 | `adc_input_init()` `adc_input_poll()` `adc_input_raw()` | L1-2 / L1-3 / L1-4 |
| `adc_health.h` / `adc_health.c` | L1 | **采样有效性判定层**：吃"计数快照"（帧序号/错误计数），产出静默/丢帧/单调性/错误增量故障位——判定与告警编排分离 | `adc_health_init()` `adc_health_check()` `adc_health_flags()` | L1-6 |
| `sample_ring.h` / `sample_ring.c` | L2 输入 | **采样环缓冲**：按语义通道保存最近 2 个周波（40 点）采样值，供相量层"以当前时刻为终止"取窗 | `sample_ring_push_frame()` `sample_ring_window()` | L2 输入（为 L2-6 滑动窗供数） |
| `phasor.h` / `phasor.c` | L2 | **全周傅氏相量计算**：一周波 20 点单频 DFT → 基波/谐波相量（有效值口径），双区原子切换供无锁读 | `phasor_run()` `phasor_get()` `phasor_calc()` | L2-1 / L2-2 / L2-3 / L2-6 / L2-7 |
| `prot_set.h` / `prot_set.c` | L3 输入 | **保护定值模型**：Q10 定点 RAM 表（通讯地址对照参考 `g_tCommSetParaTab`）+ 范围校验 + 校验和封存自检闭锁 | `prot_set_init()` `prot_set_load_raw()` `prot_set_get_f()` `prot_set_selfcheck()` | §5 定值模型 / L5-1 |
| `prot_elm.h` / `prot_elm.c` | L3 | **保护元件框架**：通用"越限 + 返回系数滞回 + 定时限"核 + 数据驱动实例表（过流三段 / 过负荷 / 过压 / 欠压 / 零序过压 / **过频 / 低频**） | `prot_elm_init()` `prot_elm_eval()` `prot_elm_run()` `prot_elm_active_mask()` | L3-1 / L3-3 / L3-4 / L3-5 / L3-6（软件侧） |
| `freq.h` / `freq.c` | L2 派生量 | **频率测量**：相邻两拍基波相量共轭乘积取角（每拍相位增量）+ 自适应窗长滑动平均 + 假值钳制 + 幅值门（UA→IA 源回退） | `freq_init()` `freq_run()` `freq_get()` `freq_valid()` | L3-5 测量侧（`docs/算法/继电保护功能复现规划.md` §4.2 测频范围） |
| `adc_input.h` / `.c` | 语义取数与有效性 | 统一语义取数：两片转换器的码值按语义（`UA…IN` / 温度）暴露，并消费 STM32 ADC1 的 DMA 乒乓缓冲 | `adc_input_init()` `adc_input_poll()` `adc_input_raw()` | TPAFE 快照消费 / STM32 ADC1 启动与扫描 / 通道语义映射 |
| `adc_health.h` / `.c` | 语义取数与有效性 | 采样有效性判定：吃计数快照，产出静默 / 丢帧 / 单调性 / 错误增量故障位（判定与告警编排分离）；「采样通道自检」残余的码值贴轨观察器同层 | `adc_health_check()` `adc_health_flags()` `adc_health_rail_watch()` | 「采样有效性校验」/「采样通道自检」（残余） |
| `adc_cal.h` / `.c` | 标定折算 | 通道标定折算（「数据可信」标定折算与落盘整定）：工程量 =(code+b)×k，Q16 系数/零点两段落盘 + 三态 flags + 合法带哨兵 + 两点公式 | `adc_cal_apply()` `adc_cal_flags()` `adc_cal_set()` | 「通道标定（一次系数 + 零漂）」（M4 半边） |
| `meas.h` / `.c` | 全周傅氏相量发布 | 遥测快照（「数据可信」遥测快照发布，M5 地基）：200 ms 基波有效值 + 品质快照，双区无锁读，全仓唯一发布者 = adcTask | `meas_tick()` `meas_get()` `meas_seq()` | M5（104 改读快照与频率点绑定、UI 是读者） |
| `sample_ring.h` / `.c` | 全周傅氏相量输入 | 按语义通道存最近 2 周波（40 点），供相量层"以当前时刻为终止"取窗 | `sample_ring_push_frame()` `sample_ring_window()` | 全周傅氏相量输入（为「每 1 ms 滑动窗刷新」供数） |
| `phasor.h` / `.c` | 全周傅氏相量 | 全周傅氏：一周波 20 点 DFT → 基波 / 谐波相量（有效值口径），双区原子切换供无锁读 | `phasor_run()` `phasor_get()` `phasor_calc()` | 全周傅氏系数表 / 基波相量实例 / 相量有效值输出 / 每 1 ms 滑动窗刷新 / 双区指针原子交换 |
| `freq.h` / `.c` | 全周傅氏相量的派生量 | 频率测量：相邻两拍基波相量共轭乘积取角 + 自适应窗滑动平均 + 假值钳制 + 幅值门（UA→IA 源回退） | `freq_run()` `freq_get()` `freq_valid()` | 「过频 / 低频」测量侧（测频范围 → `docs/算法/继电保护功能复现规划.md` §4.2） |
| `prot_set.h` / `.c` | 保护判据输入 | 保护定值模型：Q10 定点 RAM 表 + 范围校验 + 校验和封存 / 自检 / 闭锁 + 持久化 blob 纯逻辑 | `prot_set_load_raw()` `prot_set_get_f()` `prot_set_selfcheck()` | 「定值校验和」载体 |
| `prot_elm.h` / `.c` | 保护判据 | 保护元件框架：通用"越限 + 返回系数滞回 + 定时限"核 + 数据驱动实例表（过流三段 / 过负荷 / 过压 / 欠压 / 零序过压 / 过频 / 低频） | `prot_elm_run()` `prot_elm_eval()` `prot_elm_active_mask()` | 「三段式相间过流」/「过负荷」/「过压 / 欠压」/「过频 / 低频」/「零序过压」（软件侧） |
| `wave_ring.h` / `.c` | 故障录波数据面 | 录波环与冻结状态机：int16 × 320 点 × 8 路按通道分列，触发即冻结写指针、后触发计满 160 点封段、落盘回执才解冻、冷却期只加溢出计数 | `wave_ring_push()` `wave_ring_tick()` `wave_ring_request()` `wave_ring_sealed()` `wave_ring_read_ch()` | 「故障录波」数据面（环 + 触发冻结语义） |
| `wave_store.h` / `.c` | 故障录波段格式 | 段文件字节层的编解码与分次搬运游标：段头 + 通道表 + 两处 CRC-16/MODBUS + 段名轮转与反解 + 整段自检；不碰文件系统 | `wave_store_crc()` `wave_store_head_build()` `wave_store_head_parse()` `wave_store_seg_check()` `wave_store_pack_next()` `wave_store_seg_path()` | 「故障录波」段格式（布局 + 自检） |
依赖关系（自下而上，无环）：`adc_input.h`（纯枚举 + 声明）← `sample_ring` ← `phasor` ← `freq`；
`prot_set` **独立**（仅 `stdint.h`）；`prot_elm` ← `prot_set` + `phasor` + `freq`。
`sample_ring.c` / `phasor.c` / `adc_health.c` / `prot_set.c` / `prot_elm.c` / `freq.c` **零平台依赖**
（只用 `math.h` / `stddef.h` / `stdint.h` 与本目录头）；
`adc_input.c` 另依赖 `adc.h`（`hadc1`）与 `tpafe5160.h`（快照），主机侧以桩头替身。
依赖（自下而上、无环）：`adc_input.h`（纯枚举 + 声明）← `adc_cal`（另依赖 `cfg_file.h` 接口，
纯头文件级）← `sample_ring` ← `phasor` ← `freq`；`meas` ← `sample_ring` + `phasor`
（仅 `phasor_calc` 纯核；频率/品质由调用方注入，**不链** `freq`/`adc_cal`）；
`prot_set` **独立**；`prot_elm` ← `prot_set` + `phasor` + `freq`。
`wave_store` **独立**（只用 `stdint.h` 与 `stddef.h`，编码与解码共用同一个字段校验函数）；`wave_ring` ← `wave_store`（只取段头类型与返回码；**不链** `adc_cal`——封存瞬间的系数由
adcTask 现取现填后交棒，本层不复制第二个事实源）。两份录波文件同样零平台依赖、不碰文件系统。
`adc_health` 只吃调用方喂进来的计数 / 码值，不反向依赖 语义取数与有效性实现（「采样通道自检」贴轨门限由调用方
从 `adc_cal_rail_ths()` 取，本层仍零算法依赖）。
## 2. 数据流（一拍 = TIM3 1 kHz 节拍）
**除 `adc_input.c` 外全部零平台依赖**（只用 `stdint.h` / `math.h` / `stddef.h` 与本目录头）
→ 可被主机单测 `#include` 原样纳入、免桩跑。`adc_input.c` 另依赖 `adc.h`（`hadc1`）与
`tpafe5160.h`（快照），主机侧以桩头替身。
```mermaid
flowchart TD
TIM3["TIM3 更新事件 1 kHz（PSC 83 / ARR 999）<br/>ISR: tpafe5160_start_conv_irq() + adc_tick_irq_notify()<br/>同一事件经 TRGO 触发 ADC1"] --> TPAFE["TPAFE5160 转换<br/>BUSY EXTI 收帧"]
TIM3 --> ADC["STM32 ADC1 一轮 9 通道（≈67 us）<br/>DMA2_Stream4 循环模式自动搬运"]
ADC --> PP["乒乓双缓冲 s_stm32_dma[2×9]<br/>半传输 / 传输完成回调各推进 seq"]
TIM3 -. "ADC_WAKE_FLAG<br/>osThreadFlagsWait" .-> TASK
TPAFE --> POLL
PP --> POLL
TASK["adcTask（事件驱动唤醒，非定时轮询）<br/>App/task/adc_task.c"] --> POLL["adc_input_poll()<br/>TPAFE 快照 + 消费刚完成的那半区（零忙等）"]
POLL --> RAW["adc_input_raw(ch) × 9<br/>按语义取原始码值"]
RAW --> RING["sample_ring_push_frame()<br/>整帧入环（40 点窗）"]
RING --> RUN["phasor_run()<br/>逐实例 20 点重算 + 双区切换"]
RUN --> FREQ["freq_run()<br/>共轭乘积相位增量 + 自适应窗均值（B8）"]
RUN --> GET["phasor_get(idx)"]
FREQ --> FGET["freq_get() / freq_valid()"]
GET --> CONS["消费者：adcTask 日志（现状）<br/>UI / 自检 / L3 保护任务（待接）"]
FGET --> PCONS["消费者：prot_elm_run() OF/UF 判据（B8）<br/>adcTask 心跳 freq 行"]
```
## 2. 一拍的数据流（一眼版）
初始化落点：`adc_input_init()` 与 `phasor_init()`、`freq_init()` 由 `App/app/app_main.c` 的
`app_main_init()` 在**内核启动前**调用（各 `*_init()` 均无 RTOS 依赖、幂等）；
`phasor_init()` 内部会连带 `sample_ring_init()`，等价于"刚上电"。
`adc_input_poll()` → `adc_input_raw()` ×9 → `adc_cal_apply()` ×9（标定折算折算，现口径 =
ADC 引脚电压 V）+ `adc_health_rail_watch()` ×9（「采样通道自检」，码值域）→ `sample_ring_push_frame()`
→ `phasor_run()` → `freq_run()` → 消费者（`adcTask` 心跳与 语义取数与有效性健康判定；`protectTask` 每 20 ms 取相量 / 频率跑
`prot_elm_run()`；**每 200 ms** `meas_tick()` 发布遥测快照供 iec104Task / uiTask 读，即「数据可信」遥测快照发布）。节拍 = TIM3 1 kHz 更新事件，两片转换器同源触发。
完整数据流图与初始化落点 → `docs/算法/采集与算法层设计说明.md` §2。
## 3. 逐文件说明
录波支路（与上面这条相量主线**并行**、同拍只多走两步，互不阻塞）：`adc_input_raw()` 取 8 路 →
`wave_ring_push()` → `wave_ring_tick()`（触发即冻结写指针，后触发计满 160 点封段）→ defaultTask
只见 `wave_ring_sealed()` 与已封存区读口 → 游标分次搬运落盘 → `wave_ring_write_done()` 才解冻。
→ docs/子系统设计/故障录波设计说明.md §4.2 与 §5.1。
### 3.1 `adc_input.c` / `adc_input.h` — L1 ADC 输入层
## 3. 逐文件要点（只留"改代码时必须知道"的；机制与理由见设计文档）
**解决的问题**：V0.1 上 8 路电气量被两片转换器分片（硬件缺陷 **N-18**），且网名 `AINn`
≠ 板级 `ADCn` ≠ 转换器通道号（13/17 路置换）。若消费侧直接索引驱动缓冲，改版即全线错位。
本层把"哪一路"收进一张表，上层**按语义取数、不写死下标**。
> **改本目录前先记五条红线**：① 取数只经 `adc_input_raw()`，不写死下标；② **禁止跨转换器**做
> 相位 / 功率 / 矢量运算（双转换器无共同采样触发）；③ 帧值已是 标定折算工程量，但 **未标定（`adc_cal_flags()` 无
> VALID）时单位只是 ADC 引脚电压**，不是端子二次值——下游消费精度判据见「数据可信」§4.2 三态
> 表；④ 工程量 → 帧的唯一折算点是 `adc_cal_apply()`，禁止旁路再乘系数；⑤ 本层不建任务、
> 不等事件、不写日志（`adc_cal` 的 `[ERR]` 哨兵留痕是唯一例外，且每通道每开机一次），
> `*_init()` 才可在内核前调。
> 全文 → `docs/算法/采集与算法层设计说明.md` §10。
| API | 干什么 | 注意 |
### 3.1 `adc_input.c` / `adc_input.h` — 语义取数与有效性语义取数
- 语义映射表 `k_adc_map[]` 的**内容**唯一权威是 `docs/硬件平台/ADC通道映射说明.md`；V0.2 改版只改表内容，API 不动。
- `adc_input_poll()` **仅任务上下文**（TPAFE 快照是临界区）；STM32 侧固定滞后 1 拍。
- 四类 STM32 计数（`adc1_seq` / `adc1_gap` / `adc1_err` / `adc1_hw`）成因不同，**勿混读**。
- 本目录**唯一**允许出现 HAL 调用的文件。→ `docs/算法/采集与算法层设计说明.md` §3。
### 3.2 `sample_ring.c` / `.h` — 全周傅氏相量输入采样环
- 整帧写入后才推进写指针 → 取到的窗永远落在整帧边界。
- 本拍取数失败 → **整拍跳过入环**（`adc_task.c` 的 `skip`），**绝不补 0 点**。
- 不做跨通道运算、不做丢帧判定（只出 `frames()` 计数）。→ `docs/算法/采集与算法层设计说明.md` §5。
### 3.3 `phasor.c` / `.h` — 全周傅氏相量计算
- 系数表预乘 √2/N → `fAmSQ` **直接是有效值**（口径 `docs/算法/傅氏算法详解.md` §2.3）。
- 实例表 `k_inst[]` 数据驱动：**新增实例只在表尾加一行**。
- 任一实例不足一周波 → **本拍整体不产出**（不切使用区）；每拍 20 点**全部重算**（不做增量递推）。
- → `docs/算法/采集与算法层设计说明.md` §6。
### 3.4 `adc_health.c` / `.h` — 语义取数与有效性判定
- 三类位**严格分开**：电平（可自愈）/ 锁存（必留痕）/ 边沿事件（仅当拍）；**静默 ≠ 丢帧**。
- **gap 不告警**（消费者超拍是已知现象）；告警编排在 `adc_task.c`，不在本层。
- 首拍 `check()` 只建基线。→ `docs/算法/采集与算法层设计说明.md` §4。
### 3.5 `prot_set.c` / `.h` — 保护定值模型（「定值校验和」载体）
- 装载 **all-or-nothing**：任一项越界整表不装载，越界项由 `prot_set_bad_mask()` 指认。
- 批量 `prot_set_set()` 后**必须** `prot_set_seal()`；单项原子写用 `prot_set_set_sealed()`。
- 定值项 / 实例**只许尾部追加**（枚举序 = 数组序 = 校验和覆盖序）。
- blob **换代（返回 2）≠ 损坏（返回负）**：前者打 INFO、不记自检。→ `docs/算法/采集与算法层设计说明.md` §8、§12.3。
### 3.6 `prot_elm.c` / `.h` — 保护判据元件框架
- 数据缺失两种处理**刻意不同**：相量类任一未就绪 → 整拍跳过；频率类无有效读数 → 按方向填"必不启动"值，**不整拍跳过**。
- `prot_set_locked()` 或投退 = 0 → 元件整体复位不判据；跨上下文复归走 `prot_elm_request_reset()`。
- 零序过流（IN 走 STM32）**故意不在实例表**；OF / UF 无独立 104 遥信点，只经 YX15 总聚合可见。
- `prot_elm_init()` 须在 `phasor_init()` 之后。→ `docs/算法/采集与算法层设计说明.md` §9。
### 3.7 `freq.c` / `.h` — 频率测量（「过频 / 低频」的测量输入）
- `freq_run()` **仅 adcTask 上下文**，须在 `phasor_run()` 之后同拍调；保护口径 =
`freq_get() == 0 && freq_valid() == 1`。
- 精度靠**自适应窗长**（窗长 = 泄漏纹波周期的整数倍）；定长平均压不到 0.02 Hz，
换窗长 = 换精度，二者不是独立旋钮。
- 源切换即废相位基准重建（UA / IA 无共同相位基准，即双转换器无共同采样触发）。
- 判据 **J1~J6** 与实测口径 → `docs/算法/采集与算法层设计说明.md` §7.2（与 `test/host/freq/freq_test.c` 文件头同源）。
### 3.8 `adc_cal.c` / `.h` — 标定折算通道标定折算（「数据可信」标定折算与落盘整定）
- 折算模型：工程量 = (code + b) × k；**k 落盘用 int32 Q16（µV/码 × 65536）**、b 用
int32 码值（负零点靠 `CFG_VAL_INT`）——单位与定点格式的选型依据见
`docs/任务规划/数据可信.md` §4.1，勿改回 V/码 直存（Q16 只剩 20 个刻度）。
- **ROM 默认 = 量程口径冻结定死的引脚侧 LSB**（TPAFE 152.59 / STM32 805.66 µV/码，
`docs/硬件平台/ADC通道映射说明.md` §7.1）；表下标 = 语义枚举（UA0…IN7），
V0.2 改版与本目录 `adc_input` 映射表同步改。
- 三态可用性 `adc_cal_flags()`：VALID（已按变比标定，二次值成立——端子变比确认与两点标定前恒 0）
/ CLIPPED（运行期按来源派生，V0.2 后自动清零）。**消费者判「能不能信」只许查它**，
`adc_cal_apply()` 不返回可用性（「数据可信」§8 风险表）。
- 合法带哨兵：k ∉ ROM×[0.5,2.0] 或 |b| > 8192 → 折算回退 ROM + 每通道每开机一条
`[ERR]` + VALID 被压制（**即便文件位图说已标定**）；这层兜底同时挡坏文件与坏标定。
- `adc_cal_set()` / `adc_cal_two_point()`：整定与两点公式的算术核已齐备（单测还原合成
k/b）；**台架两点标定待实测**，本层不含注入。
- cfg 两段 `[adc_cal]` / `[adc_cal_ofs]` **不挂回调**（RAM 副本即生效值，引擎 load/poll
原地改写，逐点现读）；注册在 `app_main_init()` 内核前完成，必须先于 `cfg_file_load`。
### 3.9 `meas.c` / `.h` — 遥测快照发布（全周傅氏相量发布侧，「数据可信」波次）
- **唯一发布者 = adcTask**：`phasor_run()`/`freq_run()` 同拍、200 ms **tick 经过**分频
调 `meas_tick()`（非拍计数——idle/skip 拍拉长名义节拍）。docs/任务规划/数据可信.md §8
风险表"快照双写"行 = 评审判据：全仓 `meas_tick` 调用点数须为 1；iec104Task /
uiTask 只读。
- 值口径（第二轮「遥测快照发布」的 A-lite 裁决）：**基波有效值瞬时透传**，与 phasor 使用区
**同拍同核逐位相等**（单测钉死）；**不做** 4 点平均 / 谐波方和根——按
docs/任务规划/数据可信.md §4.5"上送节拍非平均窗，再平均引入滞后"；谐波 k-bin 轨
（docs/算法/继电保护功能复现规划.md 「遥测谐波轨（可选）」）扩展只许结构尾部追加，
docs/任务规划/数据可信.md §4.5 字段序 = 协议（布局由单测按偏移钉死，72 B × 双区）。
- 并发 = phasor 双区 + 单字节索引翻转（「双区指针原子交换」同型，无锁）；seq 只增供消费者判换帧。
- 品质注入：削顶位图唯一源 = `adc_cal_flags()`（口径 docs/任务规划/数据可信.md §4.2
三态表；由 adc_task 编排注入，本层不链 `adc_cal`）；TEMP = 最新一拍原始值透传 +
`NT`（「数据可信」决策 5）；`MEAS_QDS_*` 低字节与 104 QDS 线上字节同值
（本层**不** include 协议层头——分层方向）。
- 104 死区迁移 / 频率点绑定 = 104 改读快照那一波（道D 后续分支）；读数与注入源比对 = **待台架实测**。
### 3.10 `wave_ring.c` / `wave_ring.h` — 录波环与冻结状态机（「故障录波」数据面）
- **形态三条钉死**（动它之前读 docs/子系统设计/故障录波设计说明.md §6.2 与 §7）：只存 `int16`
原始码值（不做折算、不许 `float`）、**按通道分列**（不按帧交错——回放与搬运都是整列取）、
`ch_count` 固定 8（TEMP 本波不录：未折算的非线性量进录波只多占字节不增信息）。环本体 5120 B，
本层全部可写静态 5298 B，落 SRAM1（scatter 的 `RW_IRAM1` 收 `.ANY (+RW +ZI)`，代码里**没有**
任何 section 属性；CCM 只放 FreeRTOS 堆，那 5 KB 既塞不进也不该塞）。
- **冻结 ≠ 停采集**：触发冻住的是覆盖窗口（写指针停走），丢的只是录波样本，`drop_cnt` 的单位是
「点」（一拍 8 路 = 8 点）；`sample_ring` / 相量 / 保护在同拍照常跑，本层不碰它们。
- **点序**：触发那一拍的样本落在段内点 159（预触发窗最后一点），点 160 起是触发后第一拍，两半
各 160 点、不重叠；回放页横轴与 PC 脚本都按这条对齐（设计说明未钉死 ±1，本层按不重叠实现）。
- **封存握手（顺序不许换，单测逐拍钉死）**：`wave_ring_tick()` 计满那一拍返回
`WAVE_RING_EVT_SEALED` → adcTask 才去取标定事实并 `wave_ring_latch_meta()` → `wave_ring_sealed()`
要求「状态 SEALED **且**已 latch」才返 1（两个标志并成一个，落盘道不可能拿半份快照落盘）→
defaultTask 只读锁副本 → `wave_ring_write_done(0 / 非 0)` 是唯一解冻入口：成功才推进轮转号与段
计数，失败只计 err 且**保持同号**（下一段重写同一个文件，盘上不留半截）。
- **两条不许把环焊死的兜底**：SEALED 滞留超过 `WAVE_SEAL_TIMEOUT_MS`（2000 拍，待台架核）自弃本段
并计 err；冷却窗 `WAVE_RING_COOL_MS`（500 拍，待台架核）**只在回执之后**计时——「落完解冻」用的是
状态不是时间，回执前任何新触发只加 `ovf_cnt` 不重录。
- **上下文归属直接长在函数命名上**（跨任务安全不靠约定）：`wave_ring_init` / `push` / `tick` /
`latch_meta` 只能在 adcTask（⚠ 严禁挂到 TIM3 回调：那是 ISR 且比调度器早约 100 ms，本层没有
消费者就绪门）；`wave_ring_write_done` 只能在 defaultTask；`request` / `state` / `sealed` /
`sealed_meta` / `read_ch` / `read_cb` / `get_stat` / `col` 任意上下文可调。**本层不提供任何读活
缓冲的口子**（docs/子系统设计/故障录波设计说明.md §5.2 第一条陷阱：`sample_ring_window()` 无临界区，本波不复用）。
- `seg_idx` 只是本次上电的本地计数；盘上的下一个写号归落盘道自持（开机扫目录用
`wave_store_idx_from_name()` 重建、写成功后 `wave_store_next_idx()` 推进）。
### 3.11 `wave_store.c` / `wave_store.h` — 段文件字节层（「故障录波」段格式）
- **只做字节**：文件落点、路径拼法、标定系数、数据本体全部由调用方注入（meta 由 adcTask 填、
数据经 `wave_reader_fn` 回调取、路径由落盘道拼）→ 两份文件零平台依赖，主机单测免桩 `#include`
原样纳入；`wave_store_meta_init()` 只填格式侧静态事实（并把通道表 `sem` 钉成下标、按归属填
`conv` / `bits`），`avail` / `k_q16` / `b_codes` 一律留 0 等封存瞬间现取现填——不复制第二个事实源。
- **尺寸等式**（单测钉死，落盘道拿它比对写回字节数）：整段 = 32 + 12×通道数 + 2×点数×通道数 + 2；
当前口径（8 路 320 点）= 头 128 + 数据 5120 + 尾 CRC 2 = **5250 字节**（这条等式是给落盘道比对写回
字节数用的）：FatFs 该移植在簇分配失败时会返回 FR_OK + 短写且无错误码，判成功必须校验字节数
（故障录波设计说明「四条已知陷阱」第二条）。
- **CRC-16/MODBUS 自带无表实现**（反射多项式 0xA001、初值 0xFFFF、异或输出 0，自检锚点字符串
"123456789" = 0x4B37）。设计说明 §6.2 原写「与屏板链路同一张表」经全仓实测**不成立**（这张表不
存在：crc.c 与 crc.h 已于 2026-10-02 删除，屏板侧 `remo_crc()` 是单字节异或）——文档等文档道回改，
代码不擅自改口径，也不再新造第三张表。
- **编解码同一把尺**：`wave_store_head_build()` 与 `wave_store_head_parse()` 走同一个字段校验函数，
判据与 PC 侧读段脚本的拒绝清单逐条对齐（零长度、每周波点数不足 2、每通道点数不够一周波、
预触发点数超段长、通道表项语义号不等于下标、版本号与魔数第三字节不一致）——防的就是「板端
写得出、PC 读不了」。反过来**不设**任何品质侧不变式：`avail` 同时带有效与削顶是合法事实
（lead 裁定 2026-10-29），编码器如实透传、解码器不许据此判废。
- **游标分次搬运**（256 B 缓冲够用，整段绝不驻留 RAM；数据 CRC 走增量中间值）：
`wave_store_pack_next()` 头那一步要求缓冲容量不小于整头 128，否则返 `WAVE_ST_E_PARAM` 且**不推进
游标**；没有数据源却进数据区 → `WAVE_ST_E_STATE` 且**不产空字节**（产空字节等于写出「长度对、
内容全 0」的段 = docs/子系统设计/故障录波设计说明.md §8.1 明令禁止的伪造证据）。
- 段名严格 8.3（该移植 `FF_USE_LFN=0`）：`wave_store_seg_path()` 当前布局恒返回 16 个字符（不含结束
符），**调用方缓冲至少 17 字节**（`WAVE_ST_PATH_MAX`，原写 16 会让结束符写到缓冲外一字节）；
100 个号轮转，`wave_store_next_idx()` 回绕，`wave_store_idx_from_name()` 只认 basename 上的段名。
- `wave_store_head_build()` / `wave_ring_read_ch()` 这类函数**成功时返回实际字节数 / 点数**（不是
`WAVE_ST_OK`），负值才是错误码——写断言前先读头文件的「返 回 值」行（本层单测两次踩在这上面）。
## 4. 构建与测试
### 4.1 挂载与模拟器边界
- 十一个 `.c` 已登记在 `MDK-ARM/STM32F407-Demo.uvprojx`；`../App/algo` 已在 `<IncludePath>` 内。
- 模拟器侧分两类（Lead 裁定 2026-10-29）：`wave_ring.c` 与 `wave_store.c` **真实参与**
`simulator/CMakeLists.txt`——回放页要在模拟器里出真波形，两份又零平台依赖，与「双端共享核心、不造
第二真相」同一条口径，故**不进** `SIM_EXEMPT`；其余九个采集链文件（UI 模拟器不跑采集链路）仍登记在
`scripts/check_registration.py` 的 `SIM_EXEMPT`（附理由），`registration-check` 钩子反向校验（登记簿条目「rs485_task 白名单缺口」）。
### 4.2 主机侧纯逻辑单测——生产源文件以 `#include` 原样纳入
| 模块 | 命令 | pre-commit 钩子 |
|---|---|---|
| `adc_input_init()` | 清缓冲与统计 + **映射表自检**（每个 STM32 语义通道必须落在扫描 Rank 序列内）+ `HAL_ADC_Start_DMA()` 挂载乒乓缓冲（**只挂一次**） | 内核启动前调用；`-1` = 映射指向了从不扫描的通道（会恒读陈旧值）；`-2` = DMA 挂载失败 |
| `adc_input_poll()` | 采一拍：`tpafe5160_snapshot()` 原子快照（8 通道）+ **消费刚完成的那半区**（`stm32_take()`，按 `seq` 奇偶选半区，零忙等） | **仅任务上下文**（快照走临界区）；只搬码值，不做标定/运算；STM32 侧固定滞后 1 拍 |
| `adc_input_raw(ch, &out)` | 按语义读原始码值（TPAFE 16 位补码 / STM32 0..4095） | 消费侧取数**唯一入口**；须先成功 `poll()`；`-2` = 该来源尚无有效数据 |
| `adc_input_desc(ch)` | 语义 → 物理通道描述（来源 + 下标/通道号） | 供自检注入、UI 通道序；返回静态地址，勿改 |
| `adc_input_stm32_rc()` | STM32 侧最近一拍状态码（0 OK / -2 本拍无新帧） | 心跳日志 `adc1_rc` |
| `adc_input_stm32_seq()` / `_errs()` / `_gaps()` / `_hw_errs()` | DMA 整帧完成计数 / 停摆（连续 ≥2 拍无新帧）/ 丢帧（seq 一次前进 >1）/ HAL 错误回调 | 心跳日志 `adc1_seq` / `adc1_err` / `adc1_gap` / `adc1_hw`——四类成因不同，**勿混读** |
| 相量 / 采样环 | `& '.venv\Scripts\python.exe' test/host/phasor/run_unit_test.py` | `phasor-unit-test` |
| ADC 输入层 | `& '.venv\Scripts\python.exe' test/host/adc_input/run_unit_test.py` | `adc-input-unit-test` |
| 有效性校验 | `& '.venv\Scripts\python.exe' test/host/adc_health/run_unit_test.py` | `adc-health-unit-test` |
| 定值模型 | `& '.venv\Scripts\python.exe' test/host/prot_set/run_unit_test.py` | `prot-set-unit-test` |
| 元件框架 | `& '.venv\Scripts\python.exe' test/host/prot_elm/run_unit_test.py` | `prot-elm-unit-test` |
| 频率测量 | `& '.venv\Scripts\python.exe' test/host/freq/run_unit_test.py` | `freq-unit-test` |
| 通道标定（含真实 cfg_file 引擎集成） | `& '.venv\Scripts\python.exe' test/host/adc_cal/run_unit_test.py` | `adc-cal-unit-test` |
| 遥测快照（布局钉死/双区无撕裂/品质汇总） | `& '.venv\Scripts\python.exe' test/host/meas/run_unit_test.py` | `meas-unit-test` |
| 录波环（几何与点序 / 冻结与丢样 / 封存握手 / 读窗夹取 / 自弃与冷却） | `& '.venv\Scripts\python.exe' test/host/wave_ring/run_unit_test.py` | 无专属钩子：靠 `test-coverage` 总闸真跑 |
| 录波段格式（尺寸等式 / CRC 锚点 / 编解码往返与拒绝清单 / 搬运游标 / 段名轮转） | `& '.venv\Scripts\python.exe' test/host/wave_store/run_unit_test.py` | 同上 |
| 录波触发与全链路（三条来路 / 同拍多请求 / 已封存区不变 / 字节逐列对环） | `& '.venv\Scripts\python.exe' test/host/wave_trig/run_unit_test.py` | 同上 |
**要点**
改本目录任一 `.c/.h`，提交时对应钩子自动跑。**用例清单与判据数字的属主**是各
`test/host/<模块>/` 与 `docs/测试说明/` 下的单测说明，本文不复制（三处抄数字必然打架）。
- 语义映射表 `k_adc_map[]` 的**唯一权威口径**是 `docs/硬件平台/ADC通道映射说明.md`：
`UA/UN/IA` → TPAFE `buf[6]/[5]/[2]`；`UB/UC/IB/IC/IN/TEMP` → ADC1 `CH14/3/6/1/2/5`。
**V0.2 改版只改这张表的内容**，本层 API 与上层语义不动。
- STM32 侧是**顺序扫描**（Rank1..8 = CH0..CH7、Rank9 = CH14，与 `MX_ADC1_Init()` 严格一致），
9 个通道**不是同一时刻**（一轮 ≈67 µs）。v2.0 起这一轮由 **TIM3 TRGO 硬件触发 + DMA 自动搬运**，
消费侧**零忙等**（旧实现逐通道轮询、单通道超时 2 ms，已于 2026-10-10 移除）。
代价：STM32 侧数据**固定滞后 1 拍（1 ms）**——与 TPAFE 侧本来就没有同刻性（N-18），无新增误差。
- 本文件是本层**唯一**允许出现 HAL 调用的地方（它必须驱动 ADC1）；新增模块若不需要外设，
请保持 `sample_ring` / `phasor` 那种零依赖形态，才能免桩单测。
录波三套**刻意不新增专属钩子**（Lead 裁定 2026-10-27：钩子口径冻结，新增套数由 `test-coverage`
总闸全量真跑并守基线回退，失败照样拦，只是归因落在总闸输出上）。两套录波单测之间刻意留了
一份**分工**：环那套管语义、段格式那套管字节、`wave_trig` 管「接起来之后的语义」（含把封存区
逐列读出来与打包游标产出的字节逐字节对齐）。两套合成段落在临时目录并把绝对路径打进日志（日志里
同时标明是哪一份形态），要跟 PC 侧读段脚本互验时把当次产物拷进 `ci-artifacts/wave_interop/` 再报
路径——**别拿旧副本当本次产物**（踩过：拷过一次之后没刷，别人读到的是上一轮的字节）。
### 3.2 `sample_ring.c` / `sample_ring.h` — L2 输入采样环
### 4.3 板端
`/keil-build` 0 错误 0 警告 → `/serial-boot-test` 看 `[ADC_TASK]` 首拍 / 心跳（`phasor(...)`、`freq(...)`、
`cal: ua_mv=… vl=0x00 cl=0xE6 rail=…`、`ring` / `skip` / `adc1_*` / `tgap`）；
健康判据 = **零 `[ERR]`**（健康告警与标定哨兵全以 `[ERR]` 开头，误报会被闭环直接抓住；
`vl` 在未标定默认构建必须为 0x00，未标定即闭锁落地后 `cal:` 行就是台架期望的直接证据）。
→ `docs/算法/采集与算法层设计说明.md` §12。
**解决的问题**：相量计算要"以当前时刻为终止的一周波"，而 L1 每次只给最新一帧。
本层按**语义通道**存最近 `SAMPLE_RING_CYCLES = 2` 个周波（`SAMPLE_RING_DEPTH = 40` 点），
与参考系统 `CN_BUFSAM_CYCLE = 2` 一致，并为后续加长数据窗（1.5~2 周波抗衰减直流）预留空间。
| API | 干什么 | 返回 |
|---|---|---|
| `sample_ring_init()` | 清全部通道历史与计数（幂等，内核启动前可调） | — |
| `sample_ring_push_frame(values, n)` | 整帧压入（长度须 `= ADC_SEM_COUNT`） | `0` / `-1` 参数错 |
| `sample_ring_window(ch, n, out)` | 取该语义通道最近 `n` 点，**按时间序旧 → 新**（`out[n-1]` 最新） | `0` / `-1` 参数错 / `-2` 点数不足 |
| `sample_ring_filled()` | 已累积点数（**饱和**于 40）——判"够不够一周波" | `0..40` |
| `sample_ring_frames()` | 累计入环帧数（**不饱和**，1 kHz 下约 49.7 天回绕） | 帧数 |
**要点**
- **整帧写入后统一推进写指针** → 单帧内不可能"半新半旧"，消费侧取到的窗永远落在整帧边界。
- 本层**只做按时序存/取，不做任何跨通道运算**：同刻性由上游 L1 负责，本层既不保证也不假设。
- `frames()` 与 L1 的 `tpafe5160_frame_seq()` 对照即可判丢帧（L1-6 的判据之一）；
本层只提供计数，**判定不在这里**。
- 上层若某通道本拍取数失败，应**整拍跳过入环**（现 `adc_task` 的 `s_frames_skip` 即此），
切勿补 0 点——0 会污染相量窗。
### 3.3 `phasor.c` / `phasor.h` — L2 相量计算
**算法**：全周傅氏（单频 DFT），`N = PHASOR_N = 20`（1 kHz @ 50 Hz）。系数表
`k_fft_sin/k_fft_cos` **离线生成**并**预乘 √2/N**（口径 `docs/算法/傅氏算法详解.md` §2.3），
故 `fAmSQ = √(fRe²+fIm²)` **直接就是有效值**，`fAm = √2·fAmSQ` 为峰值。运行期不调 `sinf/cosf`。
| API | 干什么 | 注意 |
|---|---|---|
| `phasor_init()` | 双区清零 + 使用区/就绪复位 + `sample_ring_init()` | 幂等；内核启动前调用 |
| `phasor_inst_count()` / `phasor_inst(idx)` | 遍历实例表（`{name, sem, harm}`） | 返回静态地址，勿改；越界 `NULL` |
| `phasor_run()` | 逐实例取 20 点窗 → 重算 → 写计算区 → **一次性切换使用区** | 仅任务上下文；须先 `push_frame()` |
| `phasor_get(idx, &out)` | 读**使用区**结果 | `0` / `-1` 参数错 / `-2` 未攒满一周波 |
| `phasor_calc(x, n, harm, &out)` | 对给定窗口算 `harm` 次相量 | **纯函数**，可脱离采样环独立单测 |
**要点**
- **实例表数据驱动**（`k_inst[]`，现 5 行）：`C01-IA-F1`（过流/过负荷）、`C02-UA-F1`（过压/欠压/频率）、
`C03-UN-F1`（零序过压）、`C04-IA-F2`（二次谐波制动）、`C05-IA-F5`（五次谐波选线）。
**新增实例只在表尾加一行**，遍历/日志/单测自动适配。
- **双区（计算区 / 使用区）**：结果先写非使用区，全部实例写完后单字节 `volatile` store 切换
`s_use_zone`（Cortex-M 上原子）→ 消费侧无锁、无撕裂。今日唯一消费者是 adcTask 自身，
该机制为后续独立 L3 保护任务预留。
- **任一实例数据不足一周波 → 本拍整体不产出**（不切换使用区），避免"部分新部分旧"的混合结果。
- 每拍 20 点**全部重算**（暴力法，无累积误差；迭代加减首尾项会累积）。相量刷新周期 = 1 ms。
- 相位（L2-4）**未常驻**结构体，需要时自行 `atan2f(fIm, fRe)`。
### 3.4 `adc_health.c` / `adc_health.h` — L1-6 采样有效性判定
**解决的问题**：驱动侧只有"观测计数"（`tpafe5160_frame_seq/_frstdata_err`、
`adc_input_stm32_seq/_errs/_gaps/_hw_errs`），**没有判定**——芯片静默、消费者超拍丢帧、
计数器被改写这些故障此前只能靠人读心跳日志发现。本层把判定收进纯逻辑，
告警编排留在消费者（`adc_task.c` 的 `adc_health_report()`）→ 判定可主机免桩单测。
| API | 干什么 | 注意 |
|---|---|---|
| `adc_health_init()` | 清全部状态（幂等） | 首拍 `check()` 只建基线、不判定 |
| `adc_health_check(&in, &out)` | 吃计数快照做一次判定（每拍调，常数次整数运算） | 差值法 `(int32_t)(now-prev)`，tick/计数回绕安全 |
| `adc_health_flags()` | 电平故障位：`TPAFE_STALL` / `STM32_STALL`（≥100 ms 无前进，可自愈）/ `SEQ_BACKWARD`（锁存） | 为 L5-4 闭锁预留 |
| `adc_health_sticky()` | 锁存位（含 `FRSTDATA` / `STM32_ERR` / `HW_ERR` 增量痕迹） | 自愈后仍留痕 |
| `adc_health_tpafe_gaps()` | TPAFE 累计丢帧点数（序号前进 >1 的超出部分） | 与 STM32 侧 `adc_input_stm32_gaps()` 对称 |
**要点**
- **三类语义严格分开**：电平位（stall，可自愈）/ 锁存位（出现过必留痕）/ 边沿事件位
（仅当拍有效）。`ADC_HE_FRSTDATA/STM32_ERR/HW_ERR` 与同名 `ADC_HF_*` **编号对齐**，
消费者直接用事件掩码对"已留痕位图"做每类一次 `SYSLOG_SELFTEST` 的编排。
- **gap 不告警**：消费者超拍（心跳日志 ~2 ms）是已知现象，`adc1_gap`/`tgap` 每 10 s 心跳
可见；若按事件告警会把真故障淹掉（台架实测开机 `adc1_gap≈24`、稳态每 10 s +2）。
- **静默 ≠ 丢帧**：d=0 才是静默候选；d>1 只说明消费者没跟上，生产者还活着——两者
处置完全不同，判据不许混。
- 告警策略（在 `adc_task.c`，不在本层）：严重事件/电平上升沿 `DBG_ERROR` +
`SYSLOG_SELFTEST`（每类每次开机一次，防刷屏写满 32KB selftest.log）；下降沿 `DBG_INFO`。
### 3.5 `prot_set.c` / `prot_set.h` — 保护定值模型（P1 / L5-1 载体）
**解决的问题**：保护判据的"输入宪法"。参考系统把定值放 EEPROM + `tagPRS` 常量表
校验和自检；本层做 **RAM 模型 + 持久化纯逻辑层**（blob 序列化/解析；文件胶水在
`App/cfg/prot_set_store.c`，B7），把编号 / 通讯地址 / 范围 / 默认值 / 校验和闭环钉死。
| API | 干什么 | 注意 |
|---|---|---|
| `prot_set_init()` | 装默认值 + 封存校验和（幂等） | 内核启动前可调 |
| `prot_set_load_raw(vals)` | 整表装载（B7 由 `prot_set_store_parse` 内部走同一路径），逐项范围校验 | **all-or-nothing**：任一项越界整表不装载，`prot_set_bad_mask()` 指认越界项；影子区 + 单字交换，读侧无中间态 |
| `prot_set_set(id, q10)` | 单项写入（范围校验，批处理路径） | **不自动重封存**——批量改完必须 `prot_set_seal()`，否则 selfcheck 判"非法改写"；板端单项写一律用下行 |
| `prot_set_set_sealed(id, q10)` | **原子写+封存（B7）**：影子区改好重封后单字交换 | selfcheck 永不见中间态（收口 B5 竞态窗口）；置脏标志 |
| `prot_set_dirty_peek/take/mark()` | 脏标志三件套（B7 落盘握手） | peek=iec104Task 通知；take=属主落盘前消费；mark=写失败回置重试 |
| `prot_set_store_serialize/parse(buf,len)` | 持久化 blob（`PSET`+版本+值区+sum32 正/反码对） | parse **整表原子**：magic/版本/长度/校验对/范围任一失败 = 一字不动 |
| `prot_set_get_f()` / `get_ctl()` | 工程量浮点 / 投退读取 | 单字读原子 |
| `prot_set_selfcheck()` | 重算 sum32 与封存正/反码比对，失配 → 闭锁 | L5-1；seqlock 式复核：提交撞见 = 本轮跳过不误锁；`prot_set_seal()` 是解锁的唯一合法路径 |
**要点**
- **Q10 定点**（×1024）与参考 `2^10` 折算口径一致；元数据表（地址/范围/默认）是
ROM 常量，校验和只覆盖 RAM 值区。
- **通讯地址逐项对照参考** `Comm/Pub/Const_CommSetPara.c` `g_tCommSetParaTab`
（基址 0x8820）；单测 TC-PS-006 保证地址不重复、`min ≤ def ≤ max`、投退项 0..1。
- ⚠ **默认值/范围为拟定值**（参考 EEPROM 出厂表不在本仓库），待对照修订——
见规划 §5.4 落实进度注。
- **B8 扩 8 项（32→40）**：`PS_OF_EN/OF_HZ/OF_DLY/UF_EN/UF_HZ/UF_DLY/RET_OF/RET_UF`
**尾追加**（编号不回收，枚举序 = 数组序 = 校验和覆盖序）。OF/UF 的逐项通讯地址
不在本仓库（参考保护定值段 0x8820~0x8882 仅示"含低压/低频"类目）→ 全部按
**本地项 comm_addr=0** 登记（104 C_SE 不可寻址），待对照参考表补。
频率返回系数**独立**（`RET_OF=0.99 / RET_UF=1.01`，返回门槛 = 定值×系数）——
频率滞回带与电气量 0.95/1.05 不同量级，勿共用。
- **B8 换代语义**：项数变 → blob 144→176 B、`PROT_SET_BLOB_VER` 1→2。B7 旧档
（ver=1/32 项）在新固件 parse 即被**版本/长度闸**拒绝 → 出厂默认；
`prot_set_store_load()` 返回码分流：**2 = 换代**（`prot_set_store.c` 打 INFO
"prot set blob version change, defaults in use"，**不是** CORRUPT、不记自检），
−1 = 真损坏（defaultTask 打 ERROR + 自检留痕）。升级路径不得报成损坏。
- **bad_mask 随项数扩为 `uint64_t`**（bit i = 第 i 项越界；消费方仅主机单测，
板端闭锁走 `prot_set_locked()`）。
### 3.6 `prot_elm.c` / `prot_elm.h` — 保护元件框架（L3，P1 子集）
**解决的问题**：参考系统 89 个 `PRS_*.c` 各自实现"滞回 + 定时限"——本框架把这段
公共核收敛为**一个通用核 + 数据驱动实例表**（同 `phasor` 的 `k_inst` 模式），
新增元件 = 表加一行 + 定值加几项。
| API | 干什么 | 注意 |
|---|---|---|
| `prot_elm_init()` | 复位状态 + 解析相量实例索引（按名前缀 `C01/C02/C03`） | 须在 `phasor_init()` 之后调；`src=FREQ` 行无相量绑定（`pidx=0xFF`，run 不查它） |
| `prot_elm_eval(now_ms, meas)` | **纯判据**：定值 RAM + 测量数组 → 全元件状态机 | 主机单测入口；NULL 测量按 0 |
| `prot_elm_run(now_ms)` | 适配层：按实例表 `src` 组测量 → eval（`src=0` 取 `phasor_get()` rms，`src=1` 取 `freq_get()`） | 相量类任一未就绪 → **整拍跳过**（不引入陈旧判据）；频率类无有效读数 → **按方向填"必不启动"值**（过量填 0 / 欠量填 `1e30` → 滞回比较恒假 → 元件复位），**不整拍跳过**——频率源缺失不得饿死电流/电压类元件 |
| `prot_elm_state()` / `prot_elm_active_mask()` | 状态快照 / 动作位图 | 供 L4 出口与心跳日志 |
**要点**
- **滞回**：已启动用返回门槛（`定值 × 返回系数`），未启动用动作门槛——
过量/欠量方向由实例表 `over` 位统一处理（`UV`/`UF` 为欠量实例）。
- **定时限**：`(uint32_t)(int32_t)(now - t0) >= dly` 差值法，tick 回绕安全；
`dly=0` → 启动同拍即动作。返回**即时**（参考带 10 ms 返回延时，P4 接出口硬件时再补）。
- **闭锁联动**：`prot_set_locked()`（L5-1）或投退=0 → 该元件状态整体复位、不判据。
- **V0.1 实例**（N-18）：`OC1/OC2/OC3/OL`（IA）、`OV/UV`（UA）、`3U0`（UN 外部通道）、
`OF/UF`（freq 层测频，B8）。零序过流（IN 走 STM32）**故意不在表中**。
- **OF/UF 出口可见性（B8）**：两元件**未单独映射 104 遥信点**（送检点表 = B10 口径），
其动作目前**只经 YX15 保护总聚合可见**（`iec104_pts` 的 fault-total 掩码含 OC/3U0，
OF/UF 动作会置总位但无独立分点）——README 与规划 §3.3 L3-5 行必须同此口径，勿写"独立遥信"。
- **板端接线已落地（B5，2026-10-12）**：`App/task/protect_task.c`（protectTask，
20 ms 节拍）消费 `prot_elm_run()` + L5-4 采样故障闭锁 + L5-1 校验和巡检；
跨上下文复归走 `prot_elm_request_reset()`（104 YK11 落请求、eval 头部消费）。
判据结果经 104 遥信上送（`iec104_pts` YX15~23/31）。→ `docs/算法/继电保护功能复现规划.md` §7
⚠ 实例数 7→9（B8）：protectTask 启动锚点 `elm=` 与 `prot_elm_active_mask()` 位宽随之变，
`.serialtest` 锚点表未含 `elm=` 数字（已核），无需改配置。
### 3.7 `freq.c` / `freq.h` — 频率测量层（L2 派生量，L3-5 测量输入，B8）
**解决的问题**：过频/低频（L3-5）需要系统频率读数，而 L2 只出相量。本层把
"相邻两拍基波相量的相位差"变成"频率"，并解决**非整周波窗长的 DFT 泄漏纹波**
这一决定精度的关键问题。
| API | 干什么 | 注意 |
|---|---|---|
| `freq_init()` | 清增量环/计数/读数/相位基准/有效标志（幂等） | 内核启动前可调，须在 `phasor_init()` 之后无要求 |
| `freq_run()` | 每拍步进：选源（UA→IA 过幅值门）→ 共轭乘积 `P=Z(m)·conj(Z(m-1))` 取角 → 假值钳制 → 自适应窗均值 | **仅 adcTask 上下文**，须在 `phasor_run()` 之后同拍调 |
| `freq_get(out)` | 读数（Hz） | 0 有读数（可能是保持值）/ −1 参数错 / −2 从未启动收敛（写 0） |
| `freq_valid()` | "本拍新鲜"标志 | 1 = 幅值门 OK 且已收敛；保护消费口径 = `get()==0 && valid()==1` |
| `freq_last()` | 最近有效读数 | 从未收敛返回 0.0 |
**算法要点（精度是实测驱动定稿的，两轮弯路记录在 freq.c 文件头）**
- **相位微分免解缠绕**：`arg(Z_now·conj(Z_prev))` 天然落在 (−π, π]，纯音每拍
角**增大** 2πf/Fs（本层相量约定 φ=atan2(fIm,fRe)=窗首初相，窗每拍前滑一点）；
45~55 Hz 段 |Δφ| ≈ 0.28~0.35 rad，距 ±π 裕度巨大。
- **自适应窗长**（核心）：20 点矩形窗在非整周波时混入**负序泄漏项**
（45/55 Hz 处 |S₂/S₁| ≈ 3~5%），相量端轨迹成椭圆 → 逐拍相位差带周期
δ(φ) 纹波，周期 = fs/(2f) ≈ 9.1~11.1 拍。定长窗平均不整除纹波周期 →
扫频最坏误差 **0.317 Hz**（40 拍算术平均）/ **0.197 Hz**（60 拍复数和 Kay，
交叉项和角不随 K² 衰减，勿再尝试）。改 `K_eff = round(8·Fs/(2·f̂))`
（45~55 Hz 段 73~89 拍）使窗长恰为纹波周期整数倍 → 纹波相消，最坏 **0.0101 Hz**。
- **假值钳制带 35~65 Hz**（宽于系统合理带 40.5~60.5 = 参考 `CN_HERTZ_SOFTFR_MIN/MAX`，
规划 §10.1）：单拍相位差本身带 ±5 Hz 纹波，钳制带贴边会**非对称丢弃纹波半周**
→ 均值偏置（实测 45 Hz 点 +0.16 Hz，已修）。35~65 仍拦得住窗滑 2 拍的 ≈2f
（90~110 Hz）与相位跳变假值；系统合理带由 OF/UF 定值范围在消费侧把关。
- **幅值门** `FREQ_AMP_MIN=50.0`（原始码值口径，**拟定待 L1-5 标定复核**）：
低于门 = 无有效波形（浮空/PT 断线 rms≈0，相位无意义）→ 停更新、`valid` 清零、
读数保持 → 台架浮空不发散。信号消失过渡段（≤20 ms 残窗）读数漂移有界 ≤0.3 Hz。
- **源优先级 UA(C02)→IA(C01)**，按名前缀解析、每拍动态回退（台架只注电流亦可测频）；
源切换即废相位基准重建（UA/IA 无共同相位基准，N-18）。
**精度判据（J1~J6，与 `test/host/freq/freq_test.c` 文件头同口径，数字为实测）**
| 判据 | 条件 | 门槛 | 实测最坏 |
|---|---|---|---|
| J1 扫频 | 纯音 45.00~55.00 Hz，0.5 Hz 步进（21 点） | **≤ 0.02 Hz** | **0.0101 Hz** @55.0 Hz |
| J2 噪声 | 幅值 1000 码、噪声 rms = 1% 幅值 | **≤ 0.10 Hz** | **0.0160 Hz** |
| J3 启动收敛 | 首个有效相量 → 首个有效读数 | **≤ 40 ms** | 20 ms（@39 ms 拍，相量 @19 ms） |
| J4 频率阶跃 | 50→51 Hz 进入 ±0.05 Hz 并保持 | **≤ 120 ms** | 98 ms（稳态 err 0.0053 Hz） |
| J5 零幅/浮空 | rms < 幅值门 | valid=0、不发散、保持漂移 ≤0.3 Hz | 漂移 0.13 Hz，无 NaN |
| J6 假值钳制 | 幅值+频率双跳变拍 | 60 ms 内回 ±0.05 Hz | 0.0000 Hz |
附加鲁棒性（同套件实测）：直流偏置 8000 码 → err 0.0018 Hz；3/5 次谐波 20%/10%
→ err 0.0065 Hz；UA 无幅值落 IA → err 0.0020 Hz。
**J4 = 120 ms 是"精度优先于响应"的显式取舍（Lead 批准 2026-10-12）**：自适应窗
（M=8 ≈ 4 个泄漏纹波周期 ≈ 4 个信号周波）换来 0.317→0.0101 Hz，代价是频率骤变后
的窗冲刷（实测 98 ms）。OF/UF 定时限默认 **1000 ms** → 测频响应占保护总动作时间
**<10%**；暂态假值另有 J6（跳变后 ≤60 ms 回 ±0.05 Hz）兜底。故 120 ms 是工程整定，
不是判据失守——若将来要压响应，须同时重估精度（缩短窗 = 精度回退到 0.2~0.3 Hz 档）。
**板端可见性（DoD）**：adcTask 心跳/首拍日志追加一行
`freq(hb): f=5000 valid=1 (x0.01)`（MicroLIB 无 %f → ×0.01 定点，分辨率 0.01 Hz）。
正常带波形应 `valid=1` 且 `f≈5000`；浮空应 `valid=0`、`f` 为保持值。
## 4. 关键约定
- **语义映射唯一权威口径**：`docs/硬件平台/ADC通道映射说明.md`。取数一律经 `adc_input_raw()`，
禁止在消费侧直接索引驱动缓冲或写死下标。
- **禁止跨转换器运算**（V0.1 硬件缺陷 N-18）：`UA/UN/IA` 在 TPAFE、`UB/UC/IB/IC/IN` 在 STM32 ADC1，
两者无共同采样触发 → 无同一时刻性、相位不确定。故本层**不做**跨转换器的相位 / 功率 /
功率因数 / 负序零序类矢量运算（V0.2 把 8 路电气量全接 TPAFE 后方可解禁）。
- **标定（L1-5）尚未实现**（缺标准源）：现以**原始码值**充当工程量（系数 = 1），
因此相量读数只证明**链路通**，**不可作幅值精度判据**。
- **本层不建任务、不等事件、不写日志之外的副作用**；日志由调用侧（adcTask）打。
- 内核启动前只允许调 `*_init()`；`adc_input_poll()` / `phasor_run()` 仅任务上下文。
## 5. 静态足迹（BSS，供栈/RAM 预算参考）
| 位置 | 量 |
|---|---|
| `sample_ring.c` `s_ring[9][40]` float | **1440 B** |
| `phasor.c` `s_zone[2][5]` `phasor_t` | 160 B |
| `adc_input.c` `s_stm32_raw[16]` + `s_tpafe_raw[8]` | 48 B |
| `adc_health.c` 内部状态（9 × uint32 + uint8） | ≈ 40 B |
| `prot_set.c` `s_val[2][40]` + 封存/位图(64 位)/闭锁 | 336 B（B8：31→40 项） |
| `prot_elm.c` `s_rt[9]`（16 B/实例） | 144 B（B8：7→9 实例） |
| `freq.c` 相位增量环 `fq_d[96]` + 占位标志 + 状态 | **≈ 520 B**（B8 新增） |
| 运行期栈：`phasor_run()` 的 `win[20]` | 80 B/帧 |
| 运行期栈：`freq_run()` 局部 | ≈ 30 B/帧（无大局部数组） |
改容量（`SAMPLE_RING_CYCLES` / 实例数 / `ADC_SEM_COUNT` / `FREQ_AVG_TAPS`）前后各跑一次
`& '.venv\Scripts\python.exe' scripts/stack_report.py`（口径见 `mem-budget` skill）。
**B8 实测（adcTask 静态最坏链）**：见 READY 消息与 `docs/内存管理/` 台账回填。
## 6. 构建与测试
- **挂载**：八个 `.c` 已登记在 `MDK-ARM/STM32F407-Demo.uvprojx`，`../App/algo` 已在 `<IncludePath>` 内。
本层**不进** `simulator/CMakeLists.txt`（UI 模拟器不跑采集链路）——纯算法且模拟器无消费路径的
新文件（`prot_set.c` / `freq.c`）改在 `scripts/check_registration.py` 的 `SIM_EXEMPT` 登记豁免
（`registration-check` 钩子反向校验，N-23）。
- **主机侧单测（L0.5）**——生产源文件以 `#include` 原样纳入，无需改产品代码：
| 套件 | 命令 | pre-commit 钩子 |
|---|---|---|
| 相量层（57 用例：系数表逐项复核 / 幅值·相位 / 谐波抑制与提取 / 频偏 / 采样环 / 双区交换） | `& '.venv\Scripts\python.exe' test/host/phasor/run_unit_test.py` | `phasor-unit-test` |
| ADC 输入层（逐 Rank 注入互异码值钉死映射 + HAL 启动失败/超时分支） | `& '.venv\Scripts\python.exe' test/host/adc_input/run_unit_test.py` | `adc-input-unit-test` |
| 有效性校验（31 用例：100 ms 静默门限两侧 / 丢帧边沿 / 倒退锁存 / 错误增量 / tick 回绕 / NULL 守卫 / init 幂等） | `& '.venv\Scripts\python.exe' test/host/adc_health/run_unit_test.py` | `adc-health-unit-test` |
| 定值模型（90 用例：范围校验 / all-or-nothing 装载 / 封存-自检-闭锁 / Q10 往返 / 元数据表自检 / B7 blob 往返与损坏拒绝 / **B8 OF-UF 行 + 64 位 bad_mask + 换代拒绝**） | `& '.venv\Scripts\python.exe' test/host/prot_set/run_unit_test.py` | `prot-set-unit-test` |
| 元件框架（47 用例：滞回与定时限 / 欠量方向 / 投退 / 闭锁联动 / 时基回绕 / 位图聚合 / **B8 OF-UF 滞回与方向隔离 + run() 测频接线**） | `& '.venv\Scripts\python.exe' test/host/prot_elm/run_unit_test.py` | `prot-elm-unit-test` |
| **频率测量（46 用例：J1 扫频 45~55 Hz / J2 噪声 / J3 启动收敛 / J4 阶跃 / J5 浮空不发散 / J6 假值钳制 / 直流·谐波抑制 / UA→IA 回退 / 守卫与幂等）** | `& '.venv\Scripts\python.exe' test/host/freq/run_unit_test.py` | `freq-unit-test`（**待登记**，合并时由 Lead 加钩子） |
改本目录任一 `.c/.h`，提交时对应钩子自动跑；详见 `docs/测试说明/相量层单元测试说明.md`。
- **板端**：`@build` 0 错误 0 警告 → `@test` 看 `[ADC_TASK]` 首拍/心跳日志（`phasor(...)` 行、
`freq(...)` 行、`ring` / `skip` 计数、`adc1_rc` / `adc1_err`、`tgap`）；健康判据 = 零 `[ERR]`
（`adc_health_report` 的告警全部以 `[ERR]` 开头 → 误报会被闭环直接抓住）。
- **定值档升级 vs 损坏（B8，台架判读）**：`prot_set_store_load()` **rc=2 = 换代**
（旧固件/旧项数的档被版本闸拒绝）→ 只打 INFO `prot set blob version change, defaults in use`，
**不是** `[ERR] ... CORRUPT`、不记自检；**rc<0 = 真损坏** → `[ERR] prot set blob CORRUPT` + 自检留痕。
升级固件后首启看到"version change"一行属**预期**，勿当故障排查。
## 7. 新增一个算法模块的固定动作
## 5. 新增一个算法模块的固定动作
1. 在本目录建 `xxx.c/h`，文件头写模块注释块（规范 V1.0），**尽量零平台依赖**以便免桩单测。
2. 用 `new-source-file` skill 注册到 `MDK-ARM/STM32F407-Demo.uvprojx`（目录已在 IncludePath，
若新建子目录则必须补 IncludePath）。模拟器侧二选一：有消费路径 → 加
`simulator/CMakeLists.txt`；**纯算法无消费路径 → 加 `scripts/check_registration.py`
的 `SIM_EXEMPT`**（照 `prot_set.c` / `freq.c` 先例写理由），否则 `registration-check` 钩子拦。
3. 加 `test/host/<模块>/` 主机单测 + `.pre-commit-config.yaml` 钩子（照 `phasor-unit-test` 抄）。
4. 消费者写在 `App/task/`，本层只出"数"；跨转换器运算的禁令见 §4。
需要 `NULL` 的 `.c` 自己 `#include` 一个 `stddef.h`：ARMCC 的 `stdint.h` 不提供 `NULL`，而主机侧
MSVC / gcc 会传递性把它拉进来，**主机单测照不出这个分叉**（2026-10-29 台基线构建实测报 22 条
identifier "NULL" 未定义，根因即此；与 `sample_ring.c` / `freq.c` 同口径，别塞进公共头）。
2. 用 `new-source-file` skill 注册到 `MDK-ARM/STM32F407-Demo.uvprojx`（新建子目录还要补 `<IncludePath>`）。
模拟器侧二选一：有消费路径 → 加 `simulator/CMakeLists.txt`；纯算法无消费路径 → 加
`scripts/check_registration.py` 的 `SIM_EXEMPT`（照本目录既有七条写理由），否则 `registration-check` 拦。
3. 加 `test/host/<模块>/` 主机单测（照 `test/host/meas` 或 `test/host/soe_store` 抄目录形态与
`run_unit_test.py`）。**要不要补 `.pre-commit-config.yaml` 专属钩子按 Lead 裁定 2026-10-27：默认不补**，
由 `test-coverage` 总闸全量真跑；确有秒级归因需求再单独申请。用例标题写「它在验证什么」这类语义
短语，**不要发字母紧跟数字的新编号**（`docs/编号规范.md` §4.1「已停发」栏：停发不等于可以新发）。
4. 消费者写在 `App/task/`，本层只出"数"；跨转换器禁令见 §3 开头四条红线。
5. 在本 README §1 清单加一行，并在 `docs/算法/采集与算法层设计说明.md` 里写清该模块的契约与理由。
6. **单测产出的互验字节（要被别人的脚本读的那些）：跑测之后立刻刷新副本并记下 sha256**。三套录波单测把合成段落
在临时目录、并把**绝对路径 + 是哪一份形态**打进日志，所以「跑完顺手拷一次、以后再没刷」必然留下旧副本——
本仓这类坑不止一次（旧副本被当本次证据引用过：一次是别人拿上一轮的字节下了「字节级已闭合」的结论）。
判据：引用方只认**当次运行日志里那条路径 + 当次 sha256**；产物有第二种形态（例如本波真值形态与「已标定后
仍削顶」的构造形态）就在文件名或日志里把形态写明，别让读者靠猜；拷进 `ci-artifacts/wave_interop/` 之类的
共享目录时，同一笔操作里就把新 sha 一起报给对岸，别隔一轮。
## 8. 相关文档
## 6. 相关文档
- **本层设计与判据**：`docs/算法/采集与算法层设计说明.md`
- 通道映射权威口径：`docs/硬件平台/ADC通道映射说明.md`
- 分层与路线图（L1/L2 清单与状态）：`docs/算法/继电保护功能复现规划.md`
- 分层与功能项清单：`docs/算法/继电保护功能复现规划.md`
- 傅氏算法与有效值口径：`docs/算法/傅氏算法详解.md`
- 采样节拍（TIM3 1 kHz + TRGO 触发 ADC1/DMA）：`docs/子系统设计/ADC采样节拍设计说明.md`
- 相量层单测细则：`docs/测试说明/相量层单元测试说明.md`
- 采样节拍（TIM3 1 kHz + TRGO 触发 ADC1 / DMA）：`docs/子系统设计/ADC采样节拍设计说明.md`
- **故障录波**（数据面 / 段格式 / 现场回放契约）：docs/子系统设计/故障录波设计说明.md §6.2 是段文件
字节布局的属主，同一篇的 docs/子系统设计/故障录波设计说明.md §6.3 是字段口径裁定——两节合起来是板端
编码器与 PC 读段脚本两份独立实现的共同依据；板级判据与执行顺序 → docs/子系统设计/故障录波设计说明.md §10
- 相量层 / ADC 输入层单测细则：`docs/测试说明/单元测试/相量层单元测试说明.md`、`docs/测试说明/单元测试/ADC输入层单元测试说明.md`
- RAM 与栈台账：`docs/内存管理/RAM使用分析与优化方案.md`
App/algo/adc_cal.c
+487
View File
@@ -0,0 +1,487 @@
/*
* 模块名称：通道标定与量纲折算（标定折算）——实现
* 模块功能：见 adc_cal.h。折算模型（工程量 = (code + b) × k × 1e-6，k 为 Q16
* µV/码）与两段 cfg 布局（[adc_cal]：k_* + valid 位图；[adc_cal_ofs]：
* b_*）照 docs/任务规划/数据可信.md §4.1 / §4.4 落地；系数口径
* （ROM 默认 = 量程口径冻结定死的引脚侧 LSB）见 docs/硬件平台/ADC通道映射说明.md
* §7.1。
* 并发契约：cfg RAM 副本属主 = 配置引擎（defaultTask 的 load/poll 原地
* 改写），本层逐点折算现读——int32 对齐字在 Cortex-M4 上读写原子，
* poll 重载「复位默认 + 逐键解析」存在 µs 级窗口，撞上则该拍该通道
* 为默认值/半新值（相量 20 点窗摊薄，且触发面 = 用户改文件后 4 s
* 沉降一次性事件）——「数据可信」§4.4 明载此设计（不挂回调）。
* 合法带哨兵（防损坏文件/错误标定把假电压送进下游）：k ∉ ROM×[0.5,2.0]
* 或 |b| > ADC_CAL_B_MAX → 该通道折算回退 ROM + b=0，flags 不报
* VALID，每通道每次开机首见沿打一条 [ERR]（adc_cal_init 重置留痕）。
* 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
* 作者：DTU 项目组
* 创建日期：2026-10-25（道A 标定折算与落盘整定）
* 修改记录：
* v1.0 2026-10-25 DTU 项目组 创建：Q16 系数/零点两段落盘 + 折算 + 三态 flags
* v1.1 2026-10-25 DTU 项目组 运行参数段（道D）：新增 adc_cal_b_codes() 生效零点
* 读取口；set() 授权写者扩至 iec104Task 直通路径
* （run_par 0x8040~/0x8048~，契约同 §4.4）
* + 合法带哨兵回退 + 两点标定公式（台架注入待跑）
* v1.2 2026-10-26 DTU 项目组 道F task-16：新增 adc_cal_prot_blocked()——未标定
* 闭锁（UA/UN/IA 三路 VALID 全齐才放行）收成本层单点，
* DTU_BENCH 旁路同时收成全仓唯一一处；此前该判据在
* protect_task.c 与 ui_data_feed.c 各写一份，两处一旦
* 漂移，屏上「未标定」与判据实际停走就不是同一件事
* v1.3 2026-10-29 DTU 项目组 故障录波 task-2：新增 adc_cal_k_q16() int32 原值直读口
* （段头 k 字段 LSB 精确，float 反推在 5.28e7 掉尾数，
* 口径见 docs/子系统设计/故障录波设计说明.md §6.3）
*/
/* 头文件包含区 */
#include <stddef.h>
#include <string.h>
#include "adc_cal.h"
#include "cfg_file.h"
#define DBG_TAG "[CAL]"
#include "dbg_log.h"
/* 常量定义区 */
/* 段名（≤ CFG_FILE_MAX_NAME_LEN）与键名（k_ua…b_in，均 4/5 字符）
* ——「数据可信」§4.4 布局；键的书写顺序按该表，存储下标按语义枚举 */
#define ADC_CAL_SEC_K "adc_cal"
#define ADC_CAL_SEC_B "adc_cal_ofs"
/* Q16 → V 的合并比例因子：1e-6 / 65536（float 常量，精确到 1 ulp 以内即可：
* 系数本身 Q16 舍入误差 < 0.001 %，见「数据可信」§4.1） */
#define ADC_CAL_K_SCALE (1.52587890625e-11f)
/* 静态变量定义区 */
/* [adc_cal] 段 RAM 副本：k 按语义下标 0..7，valid 位图 bit=语义下标。
* data_size 取 offsetof(valid)+1 = 33（尾随对齐填充不属于引擎视图，
* 引擎「复位默认」按 data_size memcpy，必须覆盖 valid，见单测 TC-ADCCAL-001） */
typedef struct {
int32_t k[8];
uint8_t valid;
} adc_cal_kcfg_t;
/* [adc_cal_ofs] 段 RAM 副本：b 按语义下标 0..7（int32 有符号，有符号零点类型
* CFG_VAL_INT 是负零点偏移能干净落盘的前提） */
typedef struct {
int32_t b[8];
} adc_cal_bcfg_t;
static adc_cal_kcfg_t s_kcfg; /* 生效系数副本（引擎原地更新） */
static adc_cal_bcfg_t s_bcfg; /* 生效零点副本 */
/* 工厂默认（ROM 理论系数，量程口径冻结定死，「数据可信」§4.4）：**下标 = 语义枚举**
* （UA0 / UB1 / UC2 / UN3 / IA4 / IB5 / IC6 / IN7）——UA/UN/IA 走 TPAFE
* （16 位 ±5 V 档），UB/UC/IB/IC/IN 走 STM32 ADC1；逐路对过
* docs/硬件平台/ADC通道映射说明.md §3（IN=ADC11/STM32，勿再按分组顺序误写）。
* ROM 表按**当前 V0.1 来源排布**显式书写（不查 desc 运行期派生），因为它是
* 量程口径冻结定稿的存档事实；V0.2 改版（消除双转换器无共同采样触发）时本表与 adc_input 映射表同步改，
* 上层语义与 API 不动。CLIPPED 位则**运行期按来源派生**（见 adc_cal_flags） */
static const adc_cal_kcfg_t s_kcfg_rom = {
/* idx0 UA / idx1 UB / idx2 UC / idx3 UN */
{ ADC_CAL_K_Q16_TPAFE, ADC_CAL_K_Q16_STM32, ADC_CAL_K_Q16_STM32,
ADC_CAL_K_Q16_TPAFE,
/* idx4 IA / idx5 IB / idx6 IC / idx7 IN */
ADC_CAL_K_Q16_TPAFE, ADC_CAL_K_Q16_STM32, ADC_CAL_K_Q16_STM32,
ADC_CAL_K_Q16_STM32 },
0u /* 出厂未标定：VALID 全 0 */
};
static const adc_cal_bcfg_t s_bcfg_rom = { { 0L, 0L, 0L, 0L, 0L, 0L, 0L, 0L } };
/* 合法带哨兵留痕位（bit=语义下标；每通道每次开机只打一条 [ERR]，
* adc_cal_init 清零 = 新一轮观测窗） */
static uint8_t s_err_latched;
/*
* 观测计数（三态语义唯一落点在 adc_cal.h，这里只写"怎么自增"）：与上面那个留痕位
* 不同，这三个数一个 [ERR] 都不打、也不参与任何判定，因此 **adc_cal_init() 刻意不清**
* ——清了水位与计数就失配，会凭空造出一段"假未落盘"差额。
*/
static volatile uint32_t s_st_set_ok; /* 成功改写 RAM 副本的次数 */
static volatile uint32_t s_st_set_reject; /* 被拒次数（非法通道 / 越出合法带） */
static volatile uint32_t s_st_persist_water; /* 落盘水位：盖写，绝不自增 */
/* 键表：offset 用 offsetof 取真值（k[0]@0 / k[1]@4 … valid@32） */
static const cfg_key_def_t s_k_keys_tbl[9] = {
{ "k_ua", CFG_VAL_INT, offsetof(adc_cal_kcfg_t, k[0]), 4u },
{ "k_un", CFG_VAL_INT, offsetof(adc_cal_kcfg_t, k[3]), 4u },
{ "k_ia", CFG_VAL_INT, offsetof(adc_cal_kcfg_t, k[4]), 4u },
{ "k_ub", CFG_VAL_INT, offsetof(adc_cal_kcfg_t, k[1]), 4u },
{ "k_uc", CFG_VAL_INT, offsetof(adc_cal_kcfg_t, k[2]), 4u },
{ "k_ib", CFG_VAL_INT, offsetof(adc_cal_kcfg_t, k[5]), 4u },
{ "k_ic", CFG_VAL_INT, offsetof(adc_cal_kcfg_t, k[6]), 4u },
{ "k_in", CFG_VAL_INT, offsetof(adc_cal_kcfg_t, k[7]), 4u },
{ "valid", CFG_VAL_UINT, offsetof(adc_cal_kcfg_t, valid), 1u },
};
static const cfg_key_def_t s_b_keys_tbl[8] = {
{ "b_ua", CFG_VAL_INT, offsetof(adc_cal_bcfg_t, b[0]), 4u },
{ "b_un", CFG_VAL_INT, offsetof(adc_cal_bcfg_t, b[3]), 4u },
{ "b_ia", CFG_VAL_INT, offsetof(adc_cal_bcfg_t, b[4]), 4u },
{ "b_ub", CFG_VAL_INT, offsetof(adc_cal_bcfg_t, b[1]), 4u },
{ "b_uc", CFG_VAL_INT, offsetof(adc_cal_bcfg_t, b[2]), 4u },
{ "b_ib", CFG_VAL_INT, offsetof(adc_cal_bcfg_t, b[5]), 4u },
{ "b_ic", CFG_VAL_INT, offsetof(adc_cal_bcfg_t, b[6]), 4u },
{ "b_in", CFG_VAL_INT, offsetof(adc_cal_bcfg_t, b[7]), 4u },
};
/* 函数定义区 */
/*
* 函数功能：判定语义通道是否 STM32 源（经 adc_input 权威映射表，不另立第二份表）
* 入口参数：sem - 语义通道 unsigned
* 返 回 值：1 - STM32；0 - TPAFE（含 desc 取不到时的保守分支） int
* 限定条件：无
*/
static int s_rom_k_stm32(unsigned sem) {
const adc_channel_desc_t *d = adc_input_desc((adc_semantic_t)sem);
return ((d != NULL) && (d->source == ADC_SRC_STM32)) ? 1 : 0;
}
/*
* 函数功能：取语义通道的 ROM 默认系数（合法带/回退参照）
* 入口参数：sem - 语义下标（0..7） unsigned
* 返 回 值：Q16 系数 int32_t
* 限定条件：sem < 8（调用方已先行拦截 TEMP/越界）
* 函数说明：直接读出厂表本体——保证「哨兵合法带基准」与「引擎工厂默认」
* 永远同一份数（两者若靠重复表达式各算各的，改一处漏一处就是暗雷）
*/
static int32_t s_rom_k(unsigned sem) {
return s_kcfg_rom.k[sem];
}
/*
* 函数功能：k/b 合法带检查（ROM×[0.5,2.0] / |b| ≤ ADC_CAL_B_MAX）
* 入口参数：sem - 语义下标（0..7） unsigned
* k - 待检系数 Q16 int32_t
* b - 待检零点 码值 int32_t
* 返 回 值：1 - 合法；0 - 越带 int
* 限定条件：sem < 8
*/
static int s_kband_ok(unsigned sem, int32_t k, int32_t b) {
const int32_t rom = s_rom_k(sem);
if (k < (rom >> 1) || k > (rom << 1)) {
return 0;
}
if (b > ADC_CAL_B_MAX || b < -ADC_CAL_B_MAX) {
return 0;
}
return 1;
}
/*
* 函数功能：越带留痕（每通道每次开机首见沿一条 [ERR]，init 重置）
* 入口参数：sem - 语义下标 0..7；k/b - 现场值
* 返 回 值：无
* 限定条件：仅 adc_cal_apply/set 内部
*/
static void s_note_bad(unsigned sem, int32_t k, int32_t b) {
const uint8_t bit = (uint8_t)(1u << sem);
if ((s_err_latched & bit) == 0u) {
s_err_latched |= bit;
DBG_ERROR("ch=%u k_q16=%ld b=%ld out of ROM band [0.5x,2x]/|b|<=%ld -> ROM fallback",
(unsigned)sem, (long)k, (long)b, (long)ADC_CAL_B_MAX);
}
}
/*
* 函数功能：读通道「当前生效且合法」的 k/b（越带就地回退 ROM）
* 入口参数：sem - 语义下标 0..7；p_k/p_b - 输出
* 返 回 值：1 - 用了合法值；0 - 已回退 ROM
* 限定条件：sem < 8
*/
static int s_eff_kb(unsigned sem, int32_t *p_k, int32_t *p_b) {
const int32_t k = s_kcfg.k[sem];
const int32_t b = s_bcfg.b[sem];
if (s_kband_ok(sem, k, b) != 0) {
*p_k = k;
*p_b = b;
return 1;
}
s_note_bad(sem, k, b);
*p_k = s_rom_k(sem);
*p_b = 0L;
return 0;
}
/*
* 函数功能：标定层初始化——RAM 副本置 ROM 默认 + 注册两段进 cfg 引擎（幂等）
* 入口参数：无
* 返 回 值：无
* 限定条件：内核启动前调用（app_main_init）；注册必须先于 cfg_file_load
* 函数说明：完整契约见 adc_cal_init() 同名声明（adc_cal.h）；注册失败（段名重复/
* 段数超限）打 [ERR] 后继续——ROM 默认系数照常生效，仅文件整定失效
*/
void adc_cal_init(void) {
cfg_section_reg_t reg;
(void)memcpy(&s_kcfg, &s_kcfg_rom, sizeof(s_kcfg));
(void)memcpy(&s_bcfg, &s_bcfg_rom, sizeof(s_bcfg));
s_err_latched = 0u;
(void)memset(&reg, 0, sizeof(reg));
reg.name = ADC_CAL_SEC_K;
reg.p_data = &s_kcfg;
reg.p_defaults = &s_kcfg_rom;
reg.data_size = (offsetof(adc_cal_kcfg_t, valid) + 1u); /* 33：覆盖到 valid */
reg.p_keys = s_k_keys_tbl;
reg.key_count = 9u;
reg.p_cb = NULL; /* 不挂回调：RAM 副本即生效值（「数据可信」§4.4） */
if (cfg_file_register(&reg) != 0) {
DBG_ERROR("register '%s' FAIL (dup/full?) - calibration file values inactive",
ADC_CAL_SEC_K);
}
(void)memset(&reg, 0, sizeof(reg));
reg.name = ADC_CAL_SEC_B;
reg.p_data = &s_bcfg;
reg.p_defaults = &s_bcfg_rom;
reg.data_size = sizeof(s_bcfg); /* 32 */
reg.p_keys = s_b_keys_tbl;
reg.key_count = 8u;
reg.p_cb = NULL;
if (cfg_file_register(&reg) != 0) {
DBG_ERROR("register '%s' FAIL (dup/full?) - zero-offset file values inactive",
ADC_CAL_SEC_B);
}
}
/*
* 函数功能：码值 → 工程量折算（「数据可信」§4.1 模型）
* 入口参数：sem - 语义通道；code - 原始码值 adc_semantic_t / int32_t
* 返 回 值：工程量浮点（未标定 = ADC 引脚电压 V；TEMP/越界 = 原样透传码值） float
* 限定条件：无（任意上下文，纯读）
* 函数说明：见 adc_cal.h 同名声明；k/b 经 s_eff_kb 合法带哨兵（越带回退 ROM）
*/
float adc_cal_apply(adc_semantic_t sem, int32_t code) {
int32_t k;
int32_t b;
if ((unsigned)sem >= (unsigned)ADC_SEM_TEMP) {
return (float)code; /* TEMP/越界：不纳入线性标定（决策 5），原样透传 */
}
(void)s_eff_kb((unsigned)sem, &k, &b);
return ((float)(code + b)) * ((float)k) * ADC_CAL_K_SCALE;
}
/*
* 函数功能：读通道可用性标志（消费者判「能不能信」的唯一入口）
* 入口参数：sem - 语义通道 adc_semantic_t
* 返 回 值：ADC_CAL_F_VALID / ADC_CAL_F_CLIPPED 组合；TEMP/越界恒 0 uint32_t
* 限定条件：无
* 函数说明：VALID 需文件位图与 k 合法带**同时**成立（哨兵压制说谎位图，见文件头）
*/
uint32_t adc_cal_flags(adc_semantic_t sem) {
uint32_t f = 0u;
if ((unsigned)sem >= (unsigned)ADC_SEM_TEMP) {
return 0u;
}
/* VALID = 文件位图置位 且 k 合法（哨兵不落共享状态，随重载自愈） */
if (((s_kcfg.valid & (uint8_t)(1u << (unsigned)sem)) != 0u) &&
(s_kband_ok((unsigned)sem, s_kcfg.k[sem], s_bcfg.b[sem]) != 0)) {
f |= ADC_CAL_F_VALID;
}
/* CLIPPED 由**来源**派生（R5：STM32 侧单极性无偏置 → 负半周削顶）——
* V0.2 改版（8 路全接 TPAFE，消除双转换器无共同采样触发）后本位自动恒 0，无需改码，
* 对应「数据可信」§10「页面与 104 绑定零改动」的要求 */
if (s_rom_k_stm32((unsigned)sem) != 0) {
f |= ADC_CAL_F_CLIPPED;
}
return f;
}
/*
* 函数功能：未标定闭锁判定（判据所需的 UA/UN/IA 三路是否齐）
* 返 回 值：1 - 闭锁；0 - 放行 uint8_t（契约、三路集合的理由、判据停走的四路
* 来源、两个同族谓词的边界都写在 adc_cal.h，本处不重述——重述就是第二真源）
* 函数说明：**现查 flags()，本函数不留任何状态**。刻意不复用保护任务里那份
* 「上拍闭锁态」——那是给边沿日志用的，开机首拍前恒 0；拿它当判据等于在
* 「还没判过」的时候谎称「已标定」，而这正是本谓词最贵的失效（屏上
* 「未标定」徽标一消失，现场读到的就是「改了定值就会动作」）。
* DTU_BENCH 旁路留在这里、且全仓只此一处；用 #ifndef 把产品默认路径留在
* 主分支——#ifdef 双分支会让 cppcheck 对未定义宏取真分支、把静态分析引到
* 旁路上报 knownConditionTrueFalse 假信号（实测 2026-10-25，这条形态说明原先
* 写在 protect_task.c 的实现处，随判据一起搬到这里）
*/
uint8_t adc_cal_prot_blocked(void) {
#ifndef DTU_BENCH
if (((adc_cal_flags(ADC_SEM_UA) & ADC_CAL_F_VALID) == 0u) ||
((adc_cal_flags(ADC_SEM_UN) & ADC_CAL_F_VALID) == 0u) ||
((adc_cal_flags(ADC_SEM_IA) & ADC_CAL_F_VALID) == 0u)) {
return 1u;
}
#endif
return 0u;
}
/*
* 函数功能：读通道当前生效系数（µV/码，回退后口径）
* 入口参数：sem - 语义通道 adc_semantic_t
* 返 回 值：k[µV/码]；TEMP/越界返 0 float
* 限定条件：无
* 函数说明：Q16 现值 ÷ 65536 浮点还原；勿据其反推二次值（可用性看 flags）
*/
float adc_cal_k_uv(adc_semantic_t sem) {
int32_t k;
int32_t b;
if ((unsigned)sem >= (unsigned)ADC_SEM_TEMP) {
return 0.0f;
}
(void)s_eff_kb((unsigned)sem, &k, &b);
return ((float)k) / 65536.0f;
}
/*
* 函数功能：读通道当前生效系数的 int32 Q16 原值（adc_cal_k_uv 孪生，见 .h 声明）
* 入口参数：sem - 语义通道 adc_semantic_t
* 返 回 值：k[Q16]；TEMP/越界返 0 int32_t
* 限定条件：无（任意上下文，纯读）
* 函数说明：与 adc_cal_k_uv() 共用 s_eff_kb 生效视图（越带回退 ROM 口径一致），
* 差别只在不做浮点还原——录波段头按 LSB 精确记账必须走本口（§6.3）
*/
int32_t adc_cal_k_q16(adc_semantic_t sem) {
int32_t k;
int32_t b;
if ((unsigned)sem >= (unsigned)ADC_SEM_TEMP) {
return 0;
}
(void)s_eff_kb((unsigned)sem, &k, &b);
return k;
}
/*
* 函数功能：读通道当前生效零点偏移（码值，浮点）——adc_cal_k_uv 孪生入口
* 入口参数：sem - 语义通道 adc_semantic_t
* 返 回 值：b[码值]（越带时 s_eff_kb 已回 0）；TEMP/越界返 0 float
* 限定条件：无（任意上下文，纯读）
* 函数说明：运行参数段的 104 b 覆盖回显 + k 单侧改写 RMW 读侧（App/algo/run_par.c）
*/
float adc_cal_b_codes(adc_semantic_t sem) {
int32_t k;
int32_t b;
if ((unsigned)sem >= (unsigned)ADC_SEM_TEMP) {
return 0.0f;
}
(void)s_eff_kb((unsigned)sem, &k, &b);
return ((float)b);
}
/*
* 函数功能：整定入口——写通道系数与零点，并置位 VALID（「数据可信」标定落盘与整定入口）
* 入口参数：sem - 语义通道；k_q16 - 系数（µV/码×65536）；b_codes - 零点（码值）
* 返 回 值：0 - 成功；-1 - 参数非法/越出合法带（RAM 不动，[ERR] 留痕） int
* 限定条件：整定路径上下文（defaultTask 整定/标定链；iec104Task 经 run_par
* 直通为运行参数段授权写者，单字原子契约同 §4.4）；落盘由属主经 cfg_file_save
* 函数说明：见 adc_cal.h 同名声明
*/
int adc_cal_set(adc_semantic_t sem, int32_t k_q16, int32_t b_codes) {
if ((unsigned)sem >= (unsigned)ADC_SEM_TEMP) {
s_st_set_reject++; /* 观测：连通道号都非法，RAM 未动 */
return -1;
}
if (s_kband_ok((unsigned)sem, k_q16, b_codes) == 0) {
DBG_ERROR("set ch=%u rejected: k_q16=%ld b=%ld out of ROM band [0.5x,2x]/|b|<=%ld",
(unsigned)sem, (long)k_q16, (long)b_codes, (long)ADC_CAL_B_MAX);
s_st_set_reject++; /* 观测：越出合法带，RAM 未动（[ERR] 由上一行打） */
return -1;
}
s_kcfg.k[sem] = k_q16;
s_bcfg.b[sem] = b_codes;
s_kcfg.valid |= (uint8_t)(1u << (unsigned)sem);
s_st_set_ok++; /* 观测：RAM 副本确实被改写了（与落盘无关） */
return 0;
}
/*
* 函数功能：读标定层观测计数（不取锁、不取时刻、任意上下文可读）
* 返 回 值：无 void
* 限定条件：无；adc_cal_init() 之前可读（全 0 = 本层还没被改写过）
* 函数说明：见 adc_cal.h 同名声明（三态语义与那张成对读表都在那里，本处只取数）
*/
void adc_cal_get_stats(adc_cal_stats_t *p_out) {
if (p_out == NULL) {
return; /* 观测件不得反过来制造故障 */
}
p_out->set_ok = s_st_set_ok;
p_out->set_reject = s_st_set_reject;
p_out->persisted_set_ok = s_st_persist_water;
}
/*
* 函数功能：落盘成功回执——把水位盖写为当前的 set_ok（不是自增）
* 返 回 值：无 void
* 限定条件：仅"整档保存已成功"那一条路径（当前唯一调用点 run_par_store_save()）
* 函数说明：盖写而非自增的理由与回归用例见 adc_cal.h 同名声明。水位直接取 set_ok 的
* 当前值，因此它**在结构上不可能越过** set_ok——差额是 uint32 相减，一旦越过
* 就绕回成一个巨大的假未落盘数，这里不留那种可能
*/
void adc_cal_note_persisted(void) {
s_st_persist_water = s_st_set_ok; /* 水位只会追平，不会越过 */
}
/*
* 函数功能：两点标定公式（标定项的算术核，纯函数无状态）
* 入口参数：c_lo/c_hi、v_lo_uv/v_hi_uv、p_k_q16/p_b 见 adc_cal.h 同名声明
* 返 回 值：0 成功 / -1 参数或斜率非法 / -2 零点越 ±B_MAX int
* 限定条件：无（int64 中间量，主机可测；台架注入待跑）
*/
int adc_cal_two_point(int32_t c_lo, int32_t c_hi, int32_t v_lo_uv, int32_t v_hi_uv,
int32_t *p_k_q16, int32_t *p_b) {
long long dc;
long long dv;
long long kq;
long long bb;
if ((p_k_q16 == NULL) || (p_b == NULL)) {
return -1;
}
dc = (long long)c_hi - (long long)c_lo;
dv = (long long)v_hi_uv - (long long)v_lo_uv;
if ((dc <= 0LL) || (dv <= 0LL)) {
return -1; /* 斜率必须为正：码与电压同向，反向 = 映射/接线错 */
}
kq = ((dv << 16) + (dc >> 1)) / dc; /* (v_hi−v_lo)×65536/dc，四舍五入（dc>0） */
if ((kq <= 0LL) || (kq > 100000000LL)) {
return -1; /* 绝对合理域上界 1526 µV/code：越界 = 单位/量级错 */
}
bb = (((long long)v_lo_uv) << 16) / kq - (long long)c_lo;
if ((bb > (long long)ADC_CAL_B_MAX) || (bb < -(long long)ADC_CAL_B_MAX)) {
return -2; /* 零点异常 → 先查前端，别用系数凑（§8 风险表） */
}
*p_k_q16 = (int32_t)kq;
*p_b = (int32_t)bb;
return 0;
}
/*
* 函数功能：通道码值域贴轨带门限（采样通道自检 判定的门限来源，按 FS 百分比）
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* 入口参数：sem - 语义通道；p_lo_th/p_hi_th - 输出下/上轨带界 int32_t *
* 返 回 值：0 - 已给出门限；-1 - TEMP/越界/参数空（不做贴轨监视） int
* 限定条件：无
* 函数说明：状态机在 adc_health_rail_watch()；本函数只供门限，无状态
*/
int adc_cal_rail_ths(adc_semantic_t sem, int32_t *p_lo_th, int32_t *p_hi_th) {
if ((p_lo_th == NULL) || (p_hi_th == NULL) ||
((unsigned)sem >= (unsigned)ADC_SEM_TEMP)) {
return -1; /* TEMP（热敏非线性，不判「轨」）与越界不做监视 */
}
if (s_rom_k_stm32((unsigned)sem) != 0) {
*p_hi_th = (int32_t)((4095L * 98L) / 100L); /* 4013 = 98 % FS */
*p_lo_th = (int32_t)((4095L * 2L) / 100L); /* 81 = 触底带（削顶签名） */
} else {
*p_hi_th = 32112L; /* +98 % 半量程 */
*p_lo_th = -32112L; /* -98 % 半量程 */
}
return 0;
}
App/algo/adc_cal.h
+276
View File
@@ -0,0 +1,276 @@
/*
* 模块名称：通道标定与量纲折算（标定折算，「数据可信」标定折算与落盘整定）
* 模块功能：把 adc_input 的原始码值折算成工程量——模型与系数口径的唯一落点：
* 工程量 = (code + b) × k_f，k_f = k[µV/码] × 1e-6
* k 以 int32 **Q16**（µV/码 × 65536）落盘、b 以 int32 码值落盘，
* RAM 副本注册进 cfg_file 引擎（[adc_cal] / [adc_cal_ofs] 两段，
* 布局见 docs/任务规划/数据可信.md §4.4）；**不挂回调**——RAM 副本
* 即生效值，逐点折算现取现用（1 kHz × 9 通道 = 9k 次/秒浮点乘，可忽略）。
* 三态可用性：ADC_CAL_F_VALID（已按变比标定 → 工程量为二次值）与
* ADC_CAL_F_CLIPPED（V0.1 硬件削顶）由 adc_cal_flags() 单点查询，
* 104 / UI / 保护闭锁（未标定即闭锁）共用（docs/任务规划/数据可信.md §4.2）。
* **未标定闭锁的判定本身也归本层**（`adc_cal_prot_blocked()`）：它讲的是
* 「这几路标定齐了没」，属标定层事实，不是任务编排逻辑——保护任务与 UI
* 组装器都只是它的消费者（道F task-16 把此前的两份实现收成一份）。
* ⚠ 输出单位口径 = **ADC 引脚电压 V**（eng=0）：ROM 默认系数按量程口径冻结
* 定死的引脚侧 LSB（TPAFE 152.59 µV/码、STM32 805.66 µV/码，见
* docs/硬件平台/ADC通道映射说明.md §7.1）；端子/子板变比确认与两点
* 标定完成前不得把输出当二次值消费。TEMP 不参与线性标定
* （决策 5），adc_cal_apply() 原样透传码值。
* 本层**纯算法 + 纯数据**：不碰寄存器、不等事件；adc_cal_init() 内核前
* 可调（注册进引擎必须先于 cfg_file_load，FTP 鉴权确立的契约）；apply/flags
* 任意上下文可读（cfg RAM 副本 4 字节对齐字读写在 Cortex-M4 上原子，
* 与 defaultTask 的 load/poll 复位存在 µs 级混窗——设计接受，见 .c 头）。
* 适用平台：STM32F407ZGTx（Cortex-M4F）；主机侧纯逻辑单测 test/host/adc_cal/
* 作者：DTU 项目组
* 创建日期：2026-10-25（道A 标定折算与落盘整定）
* 修改记录：
* v1.0 2026-10-25 DTU 项目组 创建：Q16 系数/零点 + 折算/flags/集
* v1.1 2026-10-25 DTU 项目组 运行参数段：+adc_cal_b_codes()（run_par 回显/RMW 用）
* v1.2 2026-10-26 DTU 项目组 道F task-16：+adc_cal_prot_blocked()——「UA/UN/IA
* 三路 VALID 是否齐」这份判据停走条件从
* protect_task.c 与 ui_data_feed.c 的两份重复实现收成本层
* 单点（DTU_BENCH 旁路同时收成一处）
* v1.3 2026-10-29 DTU 项目组 故障录波 task-2：新增 adc_cal_k_q16()——k 的 int32
* Q16 原值直读口（adc_cal_k_uv 的孪生）。录波段头 k 字段
* 是 LSB 精确记账，float 在 5.28e7 码字上掉尾数，
* 禁止经浮点反推（docs/子系统设计/故障录波设计说明.md §6.3）
*/
#ifndef ADC_CAL_H
#define ADC_CAL_H
#include <stdint.h>
#include "adc_input.h" /* adc_semantic_t（语义通道编号 = 系数表下标口径） */
#ifdef __cplusplus
extern "C" {
#endif
/* 通道可用性标志（adc_cal_flags() 返回值位） */
#define ADC_CAL_F_VALID (0x01u) /* k 已按变比标定 → 工程量为二次值（两点标定后置位） */
#define ADC_CAL_F_CLIPPED (0x02u) /* 硬件削顶（V0.1 STM32 侧单极性无偏置）→ 交流量不可信 */
/*
* ROM 默认系数（int32 Q16 = µV/码 × 65536，量程口径冻结定死的引脚侧口径）：
* TPAFE ±5 V 档：10 V 跨度 / 65536 码 = 152.587890625 µV/码 → ×65536 = 10,000,000（整）
* STM32 0~3.3 V：3.3 V / 4096 码 = 805.6640625 µV/码 → ×65536 = 52,800,000（整）
* 两个默认值在 Q16 下**无舍入**（系数定点舍入项从误差预算里抹掉，
* 选型依据 → docs/任务规划/数据可信.md §4.1）
*/
#define ADC_CAL_K_Q16_TPAFE (10000000L)
#define ADC_CAL_K_Q16_STM32 (52800000L)
/* 系数合法带（「数据可信」§8 风险表）：k 必须落在板级 ROM 系数的 ×[0.5, 2.0]
* 区间内；带宽用 ROM 值移位实现（>>1 / <<1），不设独立宏防两处真相 */
/* 零点偏移幅值上限（码值）：超此即判文件损坏/异常标定，回退 ROM 并留痕 */
#define ADC_CAL_B_MAX (8192L)
/*
* 函数功能：标定层初始化——RAM 副本置 ROM 默认 + 注册两段进 cfg 引擎（幂等）
* 入口参数：无
* 返 回 值：无
* 限定条件：内核启动前调用（app_main_init）；注册必须先于 cfg_file_load
* （「所有受管段先注册、后 load」契约，见 Drivers/BSP/NETCFG/net_cfg.c 的
* net_cfg_load 注释）
* 函数说明：段属主为 defaultTask（配置引擎），本模块只提供 RAM 副本与默认值；
* 文件值由引擎 load/poll 原地写入 RAM 副本，本层逐点折算现读
*/
void adc_cal_init(void);
/*
* 函数功能：码值 → 工程量折算（「数据可信」§4.1 模型）
* 入口参数：sem - 语义通道（TEMP 透传不折算） adc_semantic_t
* code - 原始码值（TPAFE 16 位补码 / STM32 0..4095） int32_t
* 返 回 值：工程量浮点（未标定时单位 = ADC 引脚电压 V；VALID 后置位 = 二次值） float
* 限定条件：无（任意上下文，纯读）
* 函数说明：eng = (code + b) × k[µV/码] × 1e-6，由 Q16 现值派生，无缓存副本
* （避免无回调下的陈旧系数）；k/b 越合法带 → 该通道回退 ROM 默认 +
* 首见沿 [ERR] 留痕（adc_cal_init 重置留痕位），flags 同时不报 VALID
*/
float adc_cal_apply(adc_semantic_t sem, int32_t code);
/*
* 函数功能：读通道可用性标志（消费者判「能不能信」的唯一入口）
* 入口参数：sem - 语义通道 adc_semantic_t
* 返 回 值：ADC_CAL_F_VALID / ADC_CAL_F_CLIPPED 组合；TEMP 恒 0；sem 越界恒 0 uint32_t
* 限定条件：无
* 函数说明：VALID = 文件位图置位 **且** 该通道 k 在合法带内（哨兵不落状态，
* 天然跟随 load/poll 重载）；CLIPPED = V0.1 静态表（UB/UC/IB/IC/IN）
*/
uint32_t adc_cal_flags(adc_semantic_t sem);
/*
* 函数功能：**未标定闭锁判定**——保护判据所需的三路标定是否齐（「数据可信」未标定即闭锁
* / §4.3；道F task-16 把它从两处重复实现收敛成这一份真源）
* 入口参数：无
* 返 回 值：1 - 闭锁（UA/UN/IA 中至少一路 `ADC_CAL_F_VALID` 未置位，判据链应停走）；
* 0 - 三路全 VALID（标定侧允许判据跑） uint8_t
* 限定条件：任意上下文（纯读 `adc_cal_flags()`，与它同一条并发契约：int32 对齐
* 字读写原子、cfg poll 重载 µs 级混窗设计接受）；**现查，本层不留任何状态**
* 函数说明：① **为什么恰好这三路**：V0.1 把 8 路电气量分给两片转换器（AGENTS
* 「双转换器无共同采样触发」），UA/UN/IA = TPAFE 侧这三路是**唯一有效**
* 的测量通道；UB/UC/IB/IC/IN 即使将来标定也另受 `CLIPPED` 品质约束
* （M5 快照层处理），不掺进本闭锁源。
* ② ⚠ **不得当「保护在跑」的总括用**：判据停走共四路来源，本函数只覆盖
* 第二路——(a) 自检失败闭锁 采样故障闭锁（`adc_health_flags()`）；(b) 本函数
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* （未标定）；(c) 定值校验和失配闭锁（`prot_set_locked()`）；(d) 全局软压板
* 退出（`PS_GLOBAL_EN` = 0）。要判「这拍到底评估了没有」必须四路一起看
* （编排顺序见 `App/task/protect_task.c`）。
* ③ ⚠ **两个同族谓词与它不是一件事，不要顺手合并**（三种口径各有用途）：
* · 电气 **8** 路全 VALID 才升 eng=二次值（量纲标签，判据在
* `App/app/ui_data_feed.c` 的 `feed_eng()`）——并进来会让部分标定的整帧
* 被误标二次值；反过来把本三路口径当 8 路用，V0.1 下 UB/UC/IB/IC/IN
* 永不置位 → 徽标与停走**永不解除**；
* · 逐通道打印 VALID/CLIPPED 位图是诊断输出（`App/task/adc_task.c`），
* 不是判定。
* ④ 台架调试旁路 = 编译期 `-DDTU_BENCH`（「数据可信」§4.3 决策 1 的例外通道，
* 仅本地台架自行定义；本仓任何工程档都不定义 = 产品恒强制）。旁路**只在
* 本函数实现内部这一处**，调用方不再各自写 `#ifndef`：否则有人只给单个
* TU 加宏，屏上「未标定」徽标与判据停走当场分叉，且 0 错误 0 警告。
*/
uint8_t adc_cal_prot_blocked(void);
/*
* 函数功能：读通道当前生效系数（µV/码，浮点）
* 入口参数：sem - 语义通道 adc_semantic_t
* 返 回 值：k[µV/码]（回退后口径）；TEMP / 越界返 0 float
* 限定条件：无
* 函数说明：采样通道自检 门限换算、日志与整定界面回显用；勿据其反推二次值（看 flags）
*/
float adc_cal_k_uv(adc_semantic_t sem);
/*
* 函数功能：读通道当前生效零点偏移（码值，浮点）——adc_cal_k_uv 的孪生入口
* 入口参数：sem - 语义通道 adc_semantic_t
* 返 回 值：b[码值]（越带时为 0，与折算同视图）；TEMP/越界返 0 float
* 限定条件：无
* 函数说明：104 运行参数段（「数据可信」这一项）b 覆盖回显与 k 单侧改写的 RMW
* 读侧用（App/algo/run_par.c）；勿据其反推二次值（看 flags）。
*/
float adc_cal_b_codes(adc_semantic_t sem);
/*
* 函数功能：读通道当前生效系数的 **int32 Q16 原值**（µV/码 × 65536）——
* adc_cal_k_uv() 的孪生入口，给「必须 LSB 精确」的消费者用
* 入口参数：sem - 语义通道 adc_semantic_t
* 返 回 值：k[Q16 原值]（与折算同一生效视图：越带回退 ROM、b 不参与）；TEMP/越界返 0 int32_t
* 限定条件：无（任意上下文，纯读）
* 函数说明：故障录波段头的 k 字段是 int32 LSB 精确记账（docs/子系统设计/故障录波设计说明.md
* §6.3 裁定）——float 还原后在 5.28e7 码字上掉尾数，**禁止**拿
* adc_cal_k_uv() 反乘 65536 回算落盘，故开本原值口。
*/
int32_t adc_cal_k_q16(adc_semantic_t sem);
/*
* 函数功能：整定入口——写通道系数与零点，并置位 VALID（「数据可信」标定落盘与整定入口）
* 入口参数：sem - 语义通道（电气 8 路） adc_semantic_t
* k_q16 - 系数，µV/码 × 65536 内 int32_t
* b_codes - 零点偏移，码值 内 int32_t
* 返 回 值：0 - 成功；-1 - 参数非法/越出合法带（RAM 不动，[ERR] 留痕） int
* 限定条件：**整定路径上下文**（defaultTask 标定流程/整定链；运行参数段落地起 iec104Task
* 经 App/algo/run_par.c 的 0x8040~/0x8048~ 直通写亦为授权写者——写的仍是
* 引擎对齐 int32 单字，µs 级混窗契约同「数据可信」§4.4）。勿在 adcTask 调用
* 函数说明：**只写 RAM 副本，不置脏、不落盘、不返回"稍后会存"的承诺**——落盘由属主经
* cfg_file_save 完成，而"要不要落盘"这件事只有一个真源：run_par 的脏标志。
* 因此授权写者是 run_par 的语义 setter（写值 + 置脏成对发生，lead 裁②）；
* 绕过它直调本函数 = 值只活在 RAM 里，重启即丢且**没有错误返回**，
* 该形态现可被本层观测计数抓到（差分口径见下方 adc_cal_stats_t 那张表）
*/
int adc_cal_set(adc_semantic_t sem, int32_t k_q16, int32_t b_codes);
/*
* 函数功能：两点标定公式（「数据可信」标定项的算术核，纯函数无状态）
* 入口参数：c_lo/c_hi - 两点码值（c_hi > c_lo） int32_t
* v_lo_uv/v_hi_uv - 两点实测电压（µV，v_hi > v_lo，端子/引脚域均可） int32_t
* p_k_q16 / p_b - 输出：系数（Q16）与零点偏移（码值） int32_t *
* 返 回 值：0 - 成功；-1 - 参数/斜率非法；-2 - 零点越 ±ADC_CAL_B_MAX（先查前端，
* 不得用系数凑错斜率，「数据可信」§8 风险表） int
* 限定条件：无（纯整数运算，主机侧可直接单测）
* 函数说明：k = (v_hi−v_lo)×65536/(c_hi−c_lo)（四舍五入），b = v_lo×65536/k − c_lo；
* 实测注入未做（台架待跑），本函数即「公式齐备」的交付物
*/
int adc_cal_two_point(int32_t c_lo, int32_t c_hi, int32_t v_lo_uv, int32_t v_hi_uv,
int32_t *p_k_q16, int32_t *p_b);
/*
* 函数功能：通道码值域「贴轨带」门限（采样通道自检 越界检出的门限来源，按 FS 百分比）
* 入口参数：sem - 语义通道 adc_semantic_t
* p_lo_th - 下轨带上界（code ≤ 此值判触底） int32_t *
* p_hi_th - 上轨带下界（code ≥ 此值判触顶） int32_t *
* 返 回 值：0 - 已给出门限；-1 - TEMP/越界（不做贴轨监视） int
* 限定条件：无
* 函数说明：TPAFE 双极性 ±98% FS（±32112）；STM32 上轨 98% FS（4013）、
* 下轨 2% FS（81）；判定状态机在 adc_health_rail_watch()（采样通道自检）
*/
int adc_cal_rail_ths(adc_semantic_t sem, int32_t *p_lo_th, int32_t *p_hi_th);
/*
* 观测计数：把「改了没落盘」从意图式陈述变成可诊断事实（道G task-43 第②项；
* 先例 App/fs/vol_lock.h 的同族设计——只计数、不取锁、不在调用点打日志、不打 [ERR]）
*
* 三态语义（**定义只在本头文件这一处**，消费者只描述取数与断言，不重定义）：
* set_ok RAM 副本被本层 API 成功改写的累计次数
* set_reject 被本层拒掉的整定请求累计次数（参数非法 / 越出合法带）
* persisted_set_ok **水位**而不是计数：最近一次随整档保存落盘成功时的
* set_ok 快照（由 adc_cal_note_persisted() 盖写，永不越过 set_ok）
*
* 未落盘差额 = set_ok − persisted_set_ok，即"自上次成功落盘之后被改写的次数"。
* 单看差额不够定性，必须与 run_par_dirty_peek() 成对读（两列一起才只有一种解释）：
*
* 差额 run_par_dirty_peek() 说的是什么事
* ------ ---------------------- ----------------------------------------------
* 0 0 盘与 RAM 齐（或压根没改过）——健康
* >0 1 改了、还没到落盘时机——正常在途
* >0 0 **改了且永远不会落盘**：写者绕过 run_par 的语义
* setter 直调 adc_cal_set()（运行参数段起的事）
*
* 消费者告诫（与 vol_lock_get_stats() 同一套，别重犯）：
* ① 本组接口不取锁、不取时刻，任意上下文可读；三个数各自是 uint32 单字读写，
* Cortex-M4 上原子，但三个数之间**没有共同时刻**——别把它们拼成"一个瞬间的快照"
* 下结论，定性只按上面那张两列表成对读。
* ② 需要"被观测到的时刻"请在消费者侧自盖并冠 obs_ 前缀命名（先例：喂狗点单写者 latch），
* 本层不存时刻——存了就得连带管溢出与单位。
* ③ 这些计数**不参与任何判定**：能不能信只看 adc_cal_flags() /
* adc_cal_prot_blocked()，要不要落盘只看 run_par 的脏标志。别拿差额去改控制流，
* 那等于把观测升级成第二真源（标定写入口已由 run_par 语义 setter 收口，不再加口）。
* ④ 写清盲区：本层刻意**不挂** cfg_file 回调，因此"盘 → RAM 的覆盖"（cfg_file_load
* 与外部变更重载）不产生任何计数；未落盘的改值被一次重载无声吞掉，正是这三个
* 数照不到的那一条。要照它得先给本层挂回调 = 行为改动，另行立项处置。
*/
typedef struct {
uint32_t set_ok; /* 成功改写 RAM 副本次数（见上方唯一落点） */
uint32_t set_reject; /* 被拒次数（见上方唯一落点） */
uint32_t persisted_set_ok; /* 落盘水位，不是计数（见上方唯一落点） */
} adc_cal_stats_t;
/*
* 函数功能：读标定层观测计数（只读，不改任何状态）
* 入口参数：p_out - 输出：三个观测计数 adc_cal_stats_t *
* 返 回 值：无 void
* 限定条件：任意上下文可读（含 ISR 与内核启动前）；adc_cal_init() 之前可读，得全 0
* 函数说明：p_out 为 NULL 时静默返回——观测件不得反过来制造故障
*/
void adc_cal_get_stats(adc_cal_stats_t *p_out);
/*
* 函数功能：落盘成功回执——把水位 persisted_set_ok 盖写为当前的 set_ok（**不是自增**）
* 入口参数：无 void
* 返 回 值：无 void
* 限定条件：只允许配置引擎属主侧"整档保存已成功"那一条路径调用；当前唯一调用点 =
* App/algo/run_par.c 的 run_par_store_save() 中 cfg_file_save() 返 0 之后
* 函数说明：为什么盖写不自增——一次 save 覆盖整档，可能对应多次整定改写（逐通道
* 标定 3 路 = 3 次 adc_cal_set + 1 次 save）；自增会留下 2 次"假未落盘"。
* 水位语义让差额只反映"上次落盘之后的改写"，回归锁见
* test/host/adc_cal/adc_cal_test.c 的 TC-ADCCAL-021
*/
void adc_cal_note_persisted(void);
#ifdef __cplusplus
}
#endif
#endif /* ADC_CAL_H */
App/algo/adc_health.c
+132 -3
View File
@@ -1,16 +1,26 @@
/*
* 模块名称：ADC 采样有效性校验（L1 采集与预处理，规划项 L1-6）
* 模块名称：ADC 采样有效性校验（语义取数与预处理）
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* 模块功能：见 adc_health.h 文件头。本文件为**纯逻辑实现**：输入计数快照、
* 输出故障位/事件位，零平台依赖（仅 stdint.h）→ 主机侧免桩单测。
* 输出故障位/事件位，零平台依赖（仅 stdint.h/string.h 标准 C）→
* 主机侧免桩单测。
* 适用平台：STM32F407ZGTx + TPAFE5160
* 作者：王建锋
* 创建日期：2026-10-11
* 修改记录：
* v1.0 2026-10-11 王建锋 创建：L1-6 采样有效性校验
* v1.0 2026-10-11 王建锋 创建：采样有效性校验
* v1.1 2026-10-21 王建锋 新增 adc_health_age_stale()：无模块状态的帧年龄
* 纯判据（参照系由调用方自存），供 protectTask 的
* 兜底新鲜度门使用，见 adc_health.h 同名声明
* v1.2 2026-10-25 DTU 项目组 新增 采样通道自检 残余：码值越界（贴轨）观察器
* （rail_watch/rail_sticky/rail_init），判据与释放
* 沿理由见 adc_health.h 采样通道自检 段注释
*/
#include "adc_health.h"
#include <string.h> /* memset（采样通道自检 贴轨观察器数组复位） */
/* ===================== 内部状态 ===================== */
/* 基线是否已建立：首次 check() 只记基线、不判定（开机首拍无参照系） */
@@ -33,6 +43,17 @@ static uint32_t s_flags; /* 电平位（stall 可自愈；backward 锁存在
static uint32_t s_sticky; /* 锁存位（含电平位历史并集） */
static uint32_t s_tpafe_gaps;
/* 采样通道自检 贴轨观察器（每通道独立小状态机，单写者 = adcTask） */
typedef struct {
uint16_t run_hi; /* 连续贴上轨计数（饱和 0xFFFF） */
uint16_t run_lo; /* 连续贴下轨计数 */
uint8_t seen_mid; /* 见过中带样本（释放沿）——锁存的必要前提 */
uint8_t latched; /* 已报过边沿（不重复报） */
} adc_rail_t;
static adc_rail_t s_rail[ADC_RAIL_CH_NUM];
static uint32_t s_rail_sticky;
/* ===================== 对外接口 ===================== */
/*
@@ -43,6 +64,7 @@ static uint32_t s_tpafe_gaps;
* 函数说明：清全部内部状态；判定从下一次 check() 的首拍基线重新开始。
*/
void adc_health_init(void) {
adc_health_rail_init();
s_primed = 0u;
s_tpafe_seq = 0u;
s_tpafe_frst = 0u;
@@ -166,6 +188,43 @@ void adc_health_check(const adc_health_in_t *in, adc_health_status_t *out) {
}
}
/*
* 函数功能：帧年龄判定（无模块状态，保护侧兜底门专用）
* 入口参数：见 adc_health.h 同名声明
* 返 回 值：1 - 已陈旧；0 - 新鲜或仍在建立基线
* 限定条件：任意任务上下文；不读写本模块任何 static（与 check() 的关键区别）
* 函数说明：三步——建基线 → 有前进即刷新参照系 → 原地不动才量"距最后一次前进"。
* 倒退也按"有变化"处理（本函数不判单调性，那归 ADC_HF_SEQ_BACKWARD）。
*/
uint8_t adc_health_age_stale(adc_health_age_t *a_p_age, uint32_t a_cur_seq,
uint32_t a_now_ms, uint32_t a_age_ms) {
if (a_p_age == 0) {
return 0u;
}
/* 1) 首拍建基线：此刻序号往往已非 0（TIM3 比调度器早约 100 ms 就在生产帧），
* 没有"上一拍"就没有参照系——开机窗口内绝不允许把保护锁掉 */
if (a_p_age->primed == 0u) {
a_p_age->primed = 1u;
a_p_age->seq = a_cur_seq;
a_p_age->adv_ms = a_now_ms;
return 0u;
}
/* 2) 有任何前进（含跨多帧、含跨回绕、含倒退）即算新鲜，并刷新参照系 */
if (a_cur_seq != a_p_age->seq) {
a_p_age->seq = a_cur_seq;
a_p_age->adv_ms = a_now_ms;
return 0u;
}
/* 3) 序号原地不动：只看"距最后一次前进多久"，含等号（与 stall 判据同边界） */
if ((uint32_t)(int32_t)(a_now_ms - a_p_age->adv_ms) >= a_age_ms) {
return 1u;
}
return 0u;
}
/*
* 函数功能：读当前电平故障位
* 入口参数：无
@@ -198,3 +257,73 @@ uint32_t adc_health_sticky(void) {
uint32_t adc_health_tpafe_gaps(void) {
return s_tpafe_gaps;
}
/* ===================== 采样通道自检 贴轨观察器实现 ===================== */
/*
* 函数功能：贴轨观察器复位（幂等；adc_health_init() 已内含）
* 入口参数：无
* 返 回 值：无
* 限定条件：与 check() 同为单写者任务上下文
*/
void adc_health_rail_init(void) {
(void)memset(s_rail, 0, sizeof(s_rail));
s_rail_sticky = 0u;
}
/*
* 函数功能：单通道单拍贴轨观察（判据与释放沿前提见 adc_health.h 同名声明）
* 入口参数：ch / code / lo_th / hi_th - 见 adc_health.h
* 返 回 值：1 - 本拍新锁存（边沿）；0 - 无新事件（含 ch 越界忽略） uint32_t
* 限定条件：每拍每通道至多一次；纯算术、零平台依赖
*/
uint32_t adc_health_rail_watch(uint8_t ch, int32_t code, int32_t lo_th, int32_t hi_th) {
adc_rail_t *p;
if (ch >= (uint8_t)ADC_RAIL_CH_NUM) {
return 0u;
}
p = &s_rail[ch];
if (code >= hi_th) { /* 贴上轨带：清对侧计数 */
p->run_lo = 0u;
if (p->run_hi < 0xFFFFu) {
p->run_hi++;
}
if ((p->run_hi >= (uint16_t)ADC_RAIL_N_RUN) && (p->seen_mid != 0u)
&& (p->latched == 0u)) {
p->latched = 1u;
s_rail_sticky |= (1uL << ch);
return 1u;
}
return 0u;
}
if (code <= lo_th) { /* 贴下轨带（对称） */
p->run_hi = 0u;
if (p->run_lo < 0xFFFFu) {
p->run_lo++;
}
if ((p->run_lo >= (uint16_t)ADC_RAIL_N_RUN) && (p->seen_mid != 0u)
&& (p->latched == 0u)) {
p->latched = 1u;
s_rail_sticky |= (1uL << ch);
return 1u;
}
return 0u;
}
/* 中带：记释放沿（锁存的必要前提），并清两侧连续计数 */
p->seen_mid = 1u;
p->run_hi = 0u;
p->run_lo = 0u;
return 0u;
}
/*
* 函数功能：读贴轨锁存位图
* 入口参数：无
* 返 回 值：bit ch = 曾检出贴轨（低 9 位有效） uint32_t
* 限定条件：无
*/
uint32_t adc_health_rail_sticky(void) {
return s_rail_sticky;
}
App/algo/adc_health.h
+96 -5
View File
@@ -1,5 +1,6 @@
/*
* 模块名称：ADC 采样有效性校验（L1 采集与预处理，规划项 L1-6）
* 模块名称：ADC 采样有效性校验（语义取数与预处理）
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* 模块功能：对两片转换器的"节拍是否还在喂数据"做**判定层**（观测计数由
* `adc_input` / `tpafe5160` 驱动提供，本模块只做判定与告警位）：
* ① 静默（stall）：帧序号连续 >= ADC_HEALTH_STALL_MS 无前进；
@@ -8,12 +9,25 @@
* ④ 错误计数增量：FRSTDATA 跳变 / HAL ADC·DMA 错误 / STM32 停摆计数。
* ⚠ 本层**纯逻辑**：不碰寄存器、不取数、不打日志——输入是调用方
* 采集的计数快照，输出是故障位；日志与自检上报由消费者
* （`App/task/adc_task.c`）按位执行 → 主机侧可单测（L0.5，A-4）。
* （`App/task/adc_task.c`）按位执行 → 主机侧可纯逻辑单测。
* 适用平台：STM32F407ZGTx + TPAFE5160
* 作者：王建锋
* 创建日期：2026-10-11
* 修改记录：
* v1.0 2026-10-11 王建锋 创建：L1-6 采样有效性校验（静默/丢帧/单调性/错误增量）
* v1.0 2026-10-11 王建锋 创建：采样有效性校验（静默/丢帧/单调性/错误增量）
* v1.1 2026-10-21 王建锋 新增 adc_health_age_stale()（无模块状态的帧年龄
* 纯判据，参照系由调用方自存）与 ADC_HF_STALE 位：
* 判定层的 stall/backward 位只在 adcTask 每拍跑
* check() 时才可能置起，节拍源停摆会把本任务卡在
* osThreadFlagsWait 上 → 那些位永远是 0，而相量冻在
* 最后一帧仍被 protectTask 用于判据。该纯判据让保护侧
* 能用**自己的时基 + 中断侧计数器**独立判"数据还新不新" * v1.2 2026-10-25 DTU 项目组 新增 采样通道自检 残余「码值越界（贴轨）检出」：
* adc_health_rail_watch()/rail_sticky()/rail_init()
* ——连续 N 拍贴满量程带且该通道见过释放沿才锁存
* （空载恒 0 / 开机恒 0 是合法工况，不误报）；
* 判据动因 docs/问题记录/采集与数据处理短板评测.md
* §6.2，门限来源 adc_cal_rail_ths()（按 FS 百分比）
*/
#ifndef ADC_HEALTH_H
@@ -31,7 +45,7 @@ extern "C" {
#define ADC_HEALTH_STALL_MS 100U
/* 电平故障位（adc_health_flags()，当前活跃；stall 可自愈清除，backward 锁存）
* ——供后续 L5-4「自检失败闭锁」直接消费 */
* ——供后续「自检失败闭锁」直接消费 */
#define ADC_HF_TPAFE_STALL (1uL << 0) /* TPAFE 帧序号静默 */
#define ADC_HF_STM32_STALL (1uL << 1) /* STM32 DMA 完成计数静默 */
#define ADC_HF_SEQ_BACKWARD (1uL << 2) /* 帧序号倒退（锁存，不自愈） */
@@ -51,6 +65,13 @@ extern "C" {
#define ADC_HE_FRSTDATA (1uL << 3) /* 本次 FRSTDATA 计数有增量 */
#define ADC_HE_HW_ERR (1uL << 5) /* 本次 HAL 错误计数有增量 */
/* 兜底新鲜度位（bit8，与判定层 bit0..bit7 位段错开）
* ⚠ 本位**不由本模块置位**：由 protectTask 调 adc_health_age_stale() 独立观测后
* OR 进闭锁位图。因此它不进 sticky、不进 adc_task 编排层的 logged 位图、
* 也不由本模块打日志——留痕走 protect 侧既有的闭锁边沿日志与 SOE。
* 位段纪律见 docs/算法/采样有效性校验设计说明.md §14 */
#define ADC_HF_STALE (1uL << 8) /* 帧年龄超限（电平，序号恢复前进即清） */
/* 计数快照（由调用方采集，本模块不触碰任何驱动/外设） */
typedef struct {
uint32_t tpafe_seq; /* tpafe5160_frame_seq() */
@@ -71,6 +92,15 @@ typedef struct {
uint32_t tpafe_stall_ms; /* TPAFE 当前静默时长（0=正常） */
} adc_health_status_t;
/* 帧年龄参照系（adc_health_age_stale() 用）。状态**归调用方所有**，所以多个观察者
* 各判各的、互不污染——这是它与本模块其余接口的关键区别（check() 用的是模块级
* 单写者状态，只能有一个每拍调用者） */
typedef struct {
uint32_t seq; /* 上次看到的序号 */
uint32_t adv_ms; /* 最后一次看到序号前进的时刻（与调用方时基同源） */
uint8_t primed; /* 0 = 尚未建立基线（首拍只记录、不判定） */
} adc_health_age_t;
/*
* 函数功能：采样有效性校验初始化（幂等，内核启动前可调）
* 入口参数：无
@@ -91,12 +121,29 @@ void adc_health_init(void);
*/
void adc_health_check(const adc_health_in_t *in, adc_health_status_t *out);
/*
* 函数功能：帧年龄判定（无模块状态，供与消费者存活解耦的兜底门使用）
* 入口参数：a_p_age - 调用方自存的参照系
* a_cur_seq - 本次读到的序号（须是**中断侧**递增的计数器，如
* tpafe5160_frame_seq() / adc_input_stm32_seq()）
* a_now_ms - 本次时基（与 a_p_age->adv_ms 取同一个任务的 tick）
* a_age_ms - 判老门限（ms）
* 返 回 值：1 - 已陈旧（调用方应据此闭锁）；0 - 新鲜，或仍在建立基线
* 限定条件：任意任务上下文；零内核依赖、零共享状态 → 主机侧免桩可直接单测
* 函数说明：差值口径与 adc_health_check() 一致（(int32_t) 差值，计数与 tick
* 回绕均安全）。首次调用只建基线并返回 0；序号有任何前进即返回 0
* （一次前进多帧属消费者超拍，不是故障）；倒退不在此判老，单调性
* 破坏归 ADC_HF_SEQ_BACKWARD 管。参数错返回 0——宁可不锁，不可误锁。
*/
uint8_t adc_health_age_stale(adc_health_age_t *a_p_age, uint32_t a_cur_seq,
uint32_t a_now_ms, uint32_t a_age_ms);
/*
* 函数功能：读当前电平故障位
* 入口参数：无
* 返 回 值：ADC_HF_TPAFE_STALL / ADC_HF_STM32_STALL / ADC_HF_SEQ_BACKWARD 组合
* 限定条件：无
* 函数说明：供 L5-4 闭锁判定与 UI；与 check() 出参 flags 同源。
* 函数说明：供自检失败闭锁判定与 UI；与 check() 出参 flags 同源。
*/
uint32_t adc_health_flags(void);
@@ -119,6 +166,50 @@ uint32_t adc_health_sticky(void);
*/
uint32_t adc_health_tpafe_gaps(void);
/* ===================== 采样通道自检 残余：码值越界（贴轨）检出，2026-10-25 ===================== */
/* 贴轨锁存的连续拍数：20 拍 = 1 kHz 节拍下一个 50 Hz 周波。削顶/触轨波形的
* 贴带段持续 ≥ 半周波；噪声毛刺不可能连续 20 拍钉在同侧轨带内（短板评测 §6.2
* 判据①「连续 N 点贴满量程」的定标）。 */
#define ADC_RAIL_N_RUN 20u
/* 贴轨监视的通道数上限（9 = 8 电气量 + 温度；温度是否监视由调用方经
* adc_cal_rail_ths() 返回 -1 决定，本层不内嵌语义知识） */
#define ADC_RAIL_CH_NUM 9u
/*
* 函数功能：贴轨观察器复位（adc_health_init() 已内含，单独暴露供编排层复用）
* 入口参数：无
* 返 回 值：无
* 限定条件：与 check() 同——仅任务上下文（单写者）
*/
void adc_health_rail_init(void);
/*
* 函数功能：单通道单拍贴轨观察（采样通道自检 码值越界检出，纯算术）
* 入口参数：ch - 通道号（0..ADC_RAIL_CH_NUM-1，越界忽略） uint8_t
* code - 本拍原始码值（**码值域**，与标定无关） int32_t
* lo_th - 下轨带上界（code ≤ 此值算贴底） int32_t
* hi_th - 上轨带下界（code ≥ 此值算贴顶） int32_t
* 返 回 值：1 - 本拍**新锁存**该通道（边沿，供编排层落日志）；0 - 无新事件 uint32_t
* 限定条件：每拍每通道至多一次（与采样帧同节奏，单写者）
* 函数说明：锁存条件 = 连续 ADC_RAIL_N_RUN 拍贴**同一侧**轨带，且该通道此前
* 出现过中带样本（「释放沿」）。释放沿要求的理由：空载信号恒 0、
* 开机未采到帧恒 0 都是**合法工况**（短板评测 §6.2：空载与零值都是
* 合法工况）——只有「动过又钉死在轨上」才是削顶/越界签名。锁存后
* 不再重复报边沿，直到 rail_init/health_init 重置。
*/
uint32_t adc_health_rail_watch(uint8_t ch, int32_t code, int32_t lo_th, int32_t hi_th);
/*
* 函数功能：读贴轨锁存位图
* 入口参数：无
* 返 回 值：bit ch = 该通道曾检出贴轨（1 kHz × 9 路 → 低 9 位有效） uint32_t
* 限定条件：无
* 函数说明：供心跳日志 / 后续品质位映射（遥测快照发布与 104 消费的 qds 消费者）只读。
*/
uint32_t adc_health_rail_sticky(void);
#ifdef __cplusplus
}
#endif
App/algo/adc_input.c
+32 -20
View File
@@ -1,17 +1,22 @@
/*
* 模块名称：ADC 输入层（L1 采集与预处理）
* 模块功能：语义通道映射（L1-4）+ STM32 ADC1 采样消费（L1-3，TIM3 TRGO 触发 +
* 模块名称：ADC 输入层（语义取数与预处理）
* 模块功能：语义通道映射（通道语义映射）+ STM32 ADC1 采样消费（STM32 ADC1 启动与扫描，TIM3 TRGO 触发 +
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* DMA 双缓冲）+ TPAFE 快照消费。
* 消费侧经 adc_input_raw() 按语义取数，不写死下标。
* 适用平台：STM32F407ZGTx + TPAFE5160
* 作者：王建锋
* 创建日期：2026-10-10
* 修改记录：
* v1.0 2026-10-10 王建锋 创建：L1-3（STM32 ADC1 扫描）+ L1-4（语义映射）
* v1.0 2026-10-10 王建锋 创建：STM32 ADC1 启动与扫描（STM32 ADC1 扫描）+ 通道语义映射（语义映射）
* v2.0 2026-10-10 王建锋 STM32 侧由"软件触发 + 逐通道轮询"改为
* "TIM3 TRGO 硬件触发 + DMA 双缓冲消费"：本层不再触发
* 也不等待转换（消除最坏 2~3 ms 忙等）；新增三个 HAL
* 回调（ISR 内只计数）与 seq / hw_errs 观测量
* v2.1 2026-10-21 王建锋 丢帧计数口径由「次数」改为「帧点数」（累加每次前进
* 的超出部分），与判定层 TPAFE 侧
* adc_health_tpafe_gaps() 同单位。⚠ 换版前固件里心跳
* 字段 adc1_gap 是次数口径，不可跨版本直接对比
*/
#include "adc_input.h"
@@ -33,11 +38,11 @@
/* 连续"无新帧"达到该拍数才计一次停摆故障（单拍是相位伪影，见 stm32_take 注释） */
#define ADC_INPUT_STALL_RUN_MAX 2U
/* ===== 语义映射表（L1-4）=====
/* ===== 语义映射表（通道语义映射）=====
* 权威口径：docs/硬件平台/ADC通道映射说明.md（2026-10-09 硬件确认的语义分配）。
* index 含义：TPAFE 源 = 驱动 buf 下标 0..7；STM32 源 = ADC1 通道号 0..15。
* ⚠ 消费侧一律经本表按语义取数，**不得写死下标**（V0.1 有 13/17 路被置换，
* 网名编号与通道号不等价）；V0.2 改版（N-18）只改本表内容。 */
* 网名编号与通道号不等价）；V0.2 改版（消除双转换器无共同采样触发）只改本表内容。 */
static const adc_channel_desc_t k_adc_map[ADC_SEM_COUNT] = {
[ADC_SEM_UA] = { ADC_SRC_TPAFE, 6U }, /* TPAFE buf[6]（ch7） */
[ADC_SEM_UB] = { ADC_SRC_STM32, (uint8_t)ADC_CHANNEL_14 }, /* PC4 */
@@ -69,7 +74,7 @@ static uint16_t s_stm32_dma[ADC_INPUT_STM32_DMA_LEN];
static volatile uint32_t s_dma_seq; /* DMA 半帧/整帧完成次数（ISR 递增，只增不清） */
static uint32_t s_dma_seq_seen; /* 消费侧上次看到的完成计数 */
static volatile uint32_t s_stm32_hw_errs; /* HAL ADC/DMA 错误回调累计（ISR 写） */
static uint32_t s_stm32_gaps; /* 丢帧：seq 一次前进 >1（消费者超拍漏读）*/
static uint32_t s_stm32_gaps; /* 丢帧点数：Σ(前进量-1)，与 tgap 同单位 */
static uint8_t s_stall_run; /* 连续"无新帧"拍数（相位伪影只会是 1 拍）*/
/* TPAFE5160 最新一帧原始码值（16 位二进制补码），按驱动 buf 下标索引 */
static int16_t s_tpafe_raw[ADC_INPUT_TPAFE_CH_NUM];
@@ -79,21 +84,22 @@ static int s_stm32_rc; /* STM32 最近一次扫描状态码 */
static uint32_t s_stm32_errs; /* STM32 扫描累计失败次数 */
/*
* 函数功能：消费一帧 STM32 ADC1 采样（L1-3，v2.0 DMA 双缓冲版）
* 函数功能：消费一帧 STM32 ADC1 采样（STM32 ADC1 启动与扫描，DMA 双缓冲）
* 入口参数：无
* 返 回 值：0 - 取到新一帧；-2 - 本拍无新帧（TIM3 未启动 / ADC 停摆 / DMA 出错）
* 限定条件：仅任务上下文调用；adc_input_init() 已挂好 DMA
* 函数说明：本函数**既不触发转换也不等待转换**——转换由 TIM3 TRGO 硬件触发、由 DMA
* 自动搬运。每拍只做"看完成计数是否前进 + 拷 9 个半字"，故**零忙等**：
* 原轮询版常态 adcp=122 µs、超时拍最坏 2~3 ms，现在两档都降到 ~1 µs 量级。
* 单拍只剩"读一个计数 + 拷 9 个半字"→ µs 量级。
* 读的是"上一拍刚完成的那一半"乒乓缓冲（DMA 此刻正在写另一半）→ 无撕裂。
* ⚠ 计数未前进 = 本拍 STM32 侧**无有效数据**，必须清 s_stm32_valid，绝不
* 沿用上一拍旧值（同 2026-10-10 修的陈旧帧缺陷口径）→ adc_input_raw()
* 沿用上一拍旧值（半新半旧的混合帧会污染相量窗）→ adc_input_raw()
* 返 -2 → adc_task 走既有"整帧跳过"路径；下一拍自动恢复。
*/
static int stm32_take(void) {
uint32_t seq = s_dma_seq; /* 单次 32 位读：与 ISR 自增不产生撕裂 */
const uint16_t *src;
uint32_t d;
uint8_t half;
uint8_t i;
@@ -105,7 +111,7 @@ static int stm32_take(void) {
* 看到"计数没前进"（那个完成已被上一拍消费掉）。这种伪影**只会连续 1 拍**——
* DMA 若真停，第 2 拍仍不会前进。故只有连续 >= ADC_INPUT_STALL_RUN_MAX 拍
* 无新帧才计入故障计数（实测开机日志突发期约 21~26 次伪影、稳态每 10 s 心跳 1 次，
* 全部为单拍；见 docs/子系统设计/ADC采样节拍设计说明.md §10.5） */
* 全部为单拍；见 docs/子系统设计/ADC采样节拍设计说明.md §8） */
if (s_stall_run < 255u) {
s_stall_run++;
}
@@ -115,11 +121,14 @@ static int stm32_take(void) {
return ADC_INPUT_RC_STALL;
}
if ((uint32_t)(seq - s_dma_seq_seen) > 1u) {
d = seq - s_dma_seq_seen;
if (d > 1u) {
/* 计数一次前进 >1 = 中间有帧没被读走（乒乓缓冲已被覆盖）→ **真丢帧**，
* 与"无新帧"分开计数：前者是消费者超拍（本任务单拍耗时 > 1 ms），
* 后者多半是相位伪影 */
s_stm32_gaps++;
* 后者多半是相位伪影。按**丢掉的帧数**累计（d-1），与判定层 TPAFE 侧的
* adc_health_tpafe_gaps() 同单位——否则心跳里 adc1_gap 与 tgap 一个是次
* 一个是点，跨字段对比会得出错误结论 */
s_stm32_gaps += (d - 1u);
}
s_stall_run = 0u;
s_dma_seq_seen = seq;
@@ -145,8 +154,9 @@ static int stm32_take(void) {
* 函数说明：逐条校验映射表与扫描配置是否一致——① TPAFE 源下标须落在
* buf[0..7]；② STM32 源的通道号必须出现在 k_stm32_rank_ch[] 中，
* 否则该通道永远不会被扫描（读到的恒为陈旧值）。这是"通道宏写错 →
* 读到另一只脚/读不到"这一 §5 警告的代码级兜底（无信号源时无法做
* 引脚级注入验证，见 docs/硬件平台/ADC通道映射说明.md §8）。
* 读到另一只脚/读不到"这一警告的代码级兜底（警告口径与逐通道验证方法：
* docs/硬件平台/ADC通道映射说明.md §5、§8。台架注入验证只在台架做一次，
* 本自检每次开机都跑，两者不互相替代）。
*/
static int map_check(void) {
uint8_t s;
@@ -232,7 +242,7 @@ int adc_input_init(void) {
* STM32 侧无新帧不影响 TPAFE 快照与返回值语义（其状态另由
* adc_input_stm32_rc() / adc_input_stm32_seq() 暴露）。
* ⚠ STM32 侧数据比 TPAFE 侧**滞后 1 拍**（乒乓双缓冲的固有延迟，
* 9 路一致）；按 N-18，V0.1 本就禁止跨转换器做矢量运算。
* 9 路一致）；因双转换器无共同采样触发，V0.1 本就禁止跨转换器做矢量运算。
*/
int adc_input_poll(void) {
int r = tpafe5160_snapshot(s_tpafe_raw, (uint8_t)ADC_INPUT_TPAFE_CH_NUM);
@@ -310,12 +320,14 @@ uint32_t adc_input_stm32_errs(void) {
}
/*
* 函数功能：读取 STM32 ADC1 的丢帧次数
* 函数功能：读取 STM32 ADC1 累计丢帧点数
* 入口参数：无
* 返 回 值：DMA 完成计数一次前进 >1 的次数（中间那帧已被乒乓缓冲覆盖）
* 返 回 值：Σ(完成计数每次前进的超出部分)，即被乒乓缓冲覆盖掉、没被消费的帧数
* 限定条件：无
* 函数说明：这是"消费者超拍"的直接证据（本任务单拍耗时 > 1 ms，如突发日志突发期）；
* 与 adc_input_stm32_errs()（节拍源停摆）是两类不同的故障。
* 函数说明：这是"消费者超拍"的直接证据（本任务单拍耗时 > 1 ms，如心跳日志突发期）；
* 与 adc_input_stm32_errs()（节拍源停摆）是两类不同的故障，**勿混读**。
* 单位与判定层 TPAFE 侧 adc_health_tpafe_gaps() 一致（都是帧点数），心跳里
* 可直接对比；注意 2026-10-21 之前固件该字段是"次数"口径。
*/
uint32_t adc_input_stm32_gaps(void) {
return s_stm32_gaps;
App/algo/adc_input.h
+18 -12
View File
@@ -1,11 +1,12 @@
/*
* 模块名称：ADC 输入层（L1 采集与预处理）
* 模块名称：ADC 输入层（语义取数与预处理）
* 模块功能：把两片转换器的原始码值按**语义**（UA/UB/UC/UN/IA/IB/IC/IN/温度）统一
* 暴露，使上层（UI / 自检 / 保护算法）**按语义取数，不写死下标**：
* ① 语义通道映射表（L1-4）——权威口径 docs/硬件平台/ADC通道映射说明.md；
* ② STM32 ADC1 9 通道采样（L1-3）——由 **TIM3 TRGO 硬件触发 + DMA 双缓冲
* 搬运**（v2.0），本层只消费、不触发、不等待。
* V0.1 上 8 路电气量分属两片转换器（硬件缺陷 N-18）：UA/UN/IA 走
* ① 语义通道映射表（通道语义映射）——权威口径 docs/硬件平台/ADC通道映射说明.md；
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* ② STM32 ADC1 9 通道采样（STM32 ADC1 启动与扫描）——由 **TIM3 TRGO 硬件触发 + DMA 双缓冲
* 搬运**，本层只消费、不触发、不等待。
* V0.1 上 8 路电气量分属两片转换器（硬件缺陷：双转换器无共同采样触发）：UA/UN/IA 走
* TPAFE5160（16 位 / ±5 V 双极性），UB/UC/IB/IC/IN 走 STM32 ADC1
* （12 位 / 0~3.3 V 单极性）。V0.2 改版（8 路电气量全部接 TPAFE）
* 只改映射表内容，本层 API 与上层语义不动。
@@ -13,11 +14,14 @@
* 作者：王建锋
* 创建日期：2026-10-10
* 修改记录：
* v1.0 2026-10-10 王建锋 创建：L1-3（STM32 ADC1 扫描）+ L1-4（语义映射）
* v1.0 2026-10-10 王建锋 创建：STM32 ADC1 启动与扫描（STM32 ADC1 扫描）+ 通道语义映射（语义映射）
* v2.0 2026-10-10 王建锋 STM32 侧改 TIM3 TRGO 硬件触发 + DMA 双缓冲消费：
* 消除逐通道轮询的 2 ms 忙等；节拍源 TIM6 -> TIM3
* （F4 上 ADC1 只认 TIM2/TIM3/TIM8 的 TRGO，TIM6 TRGO
* 仅接 DAC）；新增 adc_input_stm32_seq()/_hw_errs()
* （换源判据：F4 上 ADC1 收不到 TIM6/TIM7 的 TRGO，见
* docs/子系统设计/ADC采样节拍设计说明.md §3.2）；新增
* adc_input_stm32_seq() / _hw_errs()
* v2.1 2026-10-21 王建锋 adc_input_stm32_gaps() 单位由「次数」改为「帧点数」，
* 与判定层 adc_health_tpafe_gaps() 同单位
*/
#ifndef ADC_INPUT_H
@@ -44,7 +48,7 @@ typedef enum {
ADC_SEM_COUNT /* 语义通道数（哨兵） */
} adc_semantic_t;
/* 数据来源：V0.1 的 8 路电气量分属两片转换器（N-18） */
/* 数据来源：V0.1 的 8 路电气量分属两片转换器（双转换器无共同采样触发） */
typedef enum {
ADC_SRC_TPAFE = 0, /* TPAFE5160：16 位、±5 V 双极性、8 通道同步 */
ADC_SRC_STM32 /* STM32 ADC1：12 位、0~3.3 V 单极性、9 通道顺序扫描 */
@@ -61,7 +65,7 @@ typedef struct {
/* STM32 ADC1 顺序扫描通道数（Rank 1..9） */
#define ADC_INPUT_STM32_CH_NUM 9U
/* STM32 ADC1 最近一次取帧状态码（v2.0：DMA 消费，已无"轮询超时"这一档） */
/* STM32 ADC1 最近一次取帧状态码（DMA 消费，已无"轮询超时"这一档） */
#define ADC_INPUT_RC_OK (0) /* 取到新一帧 */
#define ADC_INPUT_RC_START (-1) /* HAL_ADC_Start_DMA 挂载失败 */
#define ADC_INPUT_RC_STALL (-2) /* 本拍无新帧（TIM3 未启动 / ADC 停摆 / DMA 出错） */
@@ -129,12 +133,14 @@ int adc_input_stm32_rc(void);
uint32_t adc_input_stm32_errs(void);
/*
* 函数功能：读取 STM32 ADC1 的丢帧次数
* 函数功能：读取 STM32 ADC1 累计丢帧点数
* 入口参数：无
* 返 回 值：DMA 完成计数一次前进 >1 的次数（中间那帧已被覆盖，未及消费）
* 返 回 值：Σ(完成计数每次前进的超出部分)，即没被消费就被覆盖掉的帧数
* 限定条件：无
* 函数说明：与 errs 分开——gap = 消费者超拍（单拍耗时 > 1 ms），
* err = 节拍源/ DMA 停摆。两类故障处置不同，混在一起就查不了。
* 单位与判定层 adc_health_tpafe_gaps() 一致（帧点数），心跳里可直接对比；
* 2026-10-21 之前的固件该字段是"次数"口径。
*/
uint32_t adc_input_stm32_gaps(void);
App/algo/freq.c
+2 -2
View File
@@ -1,5 +1,5 @@
/*
* 模块名称：频率测量层（L2 派生量）——实现
* 模块名称：频率测量层（全周傅氏相量的派生量）——实现
* 模块功能：见 freq.h。相邻两拍基波相量共轭乘积取角（= 每拍相位增量，免
* 显式解缠绕）+ **自适应窗长滑动平均** + 瞬时值钳制 + 幅值门。
* 输入 = phasor 使用区基波相量（UA 优先，UA 无幅值用 IA）。
@@ -15,7 +15,7 @@
* ≈4 个信号周波），使窗长恰为纹波周期的整数倍 → δ(m+K)≈δ(m)，残差进入
* 0.01 Hz 量级。f_hat 用上一拍读数（收敛后误差 <0.1 Hz → K_eff 偏差 <1 拍，
* 自洽）。
* **精度优先于响应的显式取舍（Lead 批准 2026-10-12）**：4 周波窗换来
* **精度优先于响应的显式取舍**：4 周波窗换来
* 0.317→0.0101 Hz，代价是频率骤变后的窗冲刷（J4 阶跃整定 ≤120 ms，实测
* 98 ms）。OF/UF 定时限默认 1000 ms → 测频响应占保护总动作时间 <10%；
* 暂态假值另有 J6（跳变后 ≤60 ms 回 ±0.05 Hz）兜底。故 J4 的 120 ms 是
App/algo/freq.h
+15 -8
View File
@@ -1,15 +1,16 @@
/*
* 模块名称：频率测量层（L2 派生量，L3-5 过频/低频的测量输入）
* 模块功能：由 L2 相量使用区的基波相量导出系统频率——相邻两拍基波相量取
* 模块名称：频率测量层（全周傅氏相量的派生量，过频 / 低频的测量输入）
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* 模块功能：由 全周傅氏相量使用区的基波相量导出系统频率——相邻两拍基波相量取
* **共轭乘积** P = Z(m)·conj(Z(m-1))（其角 = 每拍相位增量，纯音 =
* +2πf/Fs，免显式解缠绕），再对**自适应窗长**的相位增量做滑动平均：
* K_eff = round(8·Fs/(2·f_hat)) ≈ 泄漏纹波周期 fs/(2f) 的整数倍
* -> 非整周波 DFT 负序泄漏造成的 ~10 ms 周期相位纹波相消
* （定长窗平均实测扫频误差 0.2~0.32 Hz，自适应窗进入 0.01 Hz 量级，
* 推导与实测见 freq.c 文件头与 test/host/freq 输出）。
* 覆盖规划 §3.3 L3-5 的测量侧与 §4.2 测频范围（45~55 Hz 建议段）。
* 覆盖规划 §3.3 过频 / 低频 的测量侧与 §4.2 测频范围（45~55 Hz 建议段）。
*
* 原理与判据（详见 App/algo/README.md §3.7 与 test/host/freq/）：
* 原理与判据（详见 docs/算法/采集与算法层设计说明.md §7 与 test/host/freq/）：
* - 采样率 Fs = 1000 Hz（TIM3 节拍，与 phasor 同源）；45~55 Hz 段每拍
* 相位增量 ≈ 0.28~0.35 rad，距 ±π 缠绕边界裕度巨大，无歧义；
* - 瞬时值钳制：单拍相位差折算越出 35~65 Hz（**假值带**，宽于系统合理带
@@ -21,7 +22,7 @@
* - 信号源优先级：UA 基波 → IA 基波（UA 无幅值时用 IA，台架只注电流亦可测频）。
*
* ⚠ 本层**纯算法**：不碰寄存器、不碰 RTOS、不自己取数（输入 = phasor 使用区）
* → 主机侧可免桩单测（L0.5，落实登记簿 A-4）。
* → 主机侧可免桩纯逻辑单测。
* 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
* 作者：DTU 项目组
* 创建日期：2026-10-12（B8）
@@ -49,9 +50,15 @@
#define FREQ_INST_MIN_HZ 35.0f
#define FREQ_INST_MAX_HZ 65.0f
/* 幅值门限（有效值，**原始码值口径**，L1-5 标定未实现）：低于该值判
* "无有效波形"。⚠ 拟定值（远小于正常波形千级码值、远大于浮空噪声），
* 标定落地后须按工程量口径复核（同 prot_set 默认值"拟定"口径）。 */
/* 幅值门限（有效值，**二次值 V 口径**，「数据可信」下游常数按工程量重定的结果，依据其 §2.3 表第 1 行）：
* 低于该值判"无有效波形"。取值 50 V = 0.5×Un（相电压标称 100 V，与
* App/algo/prot_set.c 头部量纲基准同源）：正常带载 UA 在 0.9~1.1×Un，
* 50 V 之下只可能是断保险/PT 空载/浮空噪声（浮空实测 ~1.7 V 引脚域、
* 二次域更小），不会吃掉正常纹波（纹波谷值远大于 0.5×Un）。
* ⚠ 过渡期行为（eng=0，两点标定完成前）：帧值还是引脚电压（≤5 V < 50 V），
* 本门**恒失效** → freq_valid()=0 → OF/UF 按"必不启动"填充复位——与未标定即闭锁
* 同向（判据链本就停走），不构成额外风险；标定后自动恢复本意。
* 数值沿用原 50.0f 属巧合（原为"远小于千级码值"的拟定值），不是漏改。 */
#define FREQ_AMP_MIN 50.0f
/* 相位增量滑窗环容量（拍）：96 拍 = 96 ms 上限。实际平均窗长**自适应**
App/algo/meas.c
+171
View File
@@ -0,0 +1,171 @@
/*
* 模块名称：遥测快照发布层（全周傅氏相量派生·发布侧，「数据可信」§4.5）
* 模块功能：实现见 meas.h——200 ms 基波有效值 + 品质快照，双区无锁读。
* 本文件纯算法：输入 = sample_ring 取窗 + 调用方注入（频率/削顶位图），
* 无 RTOS / 无寄存器 / 无日志（「数据可信」层内禁令：本目录不写日志）。
* 双区不变量（docs/任务规划/数据可信.md §4.5，双区指针原子交换 同型，先例 = App/algo/
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* phasor.c 的双区注释）：写侧只碰**非使用区**，全部字段填完后一次
* volatile 单字节 store 翻转使用区；读者先取索引再整体拷贝 → 拷贝期
* 间写者不可能改读者所在区（两帧间隔 200 ms 远大于 72 B 拷贝）。
* 单核顺序执行，无需内存屏障；volatile 阻编译器把字段写入挪到翻转后。
* 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
* 作者：DTU 项目组
* 创建日期：2026-10-25（道D 遥测快照发布）
* 修改记录：
* v1.0 2026-10-25 DTU 项目组 创建：200 ms 遥测快照 + 双区无锁读
*/
#include "meas.h"
#include <stddef.h>
#include "phasor.h" /* phasor_calc()：基波 DFT 纯函数核（与使用区同核） */
#include "sample_ring.h" /* sample_ring_window()：以本拍为终止的一周波窗 */
/* ===== 双区（计算区 / 使用区），口径同 App/algo/phasor.c 的 双区指针原子交换===== */
static meas_snap_t s_ms_snap[2];
static volatile uint8_t s_ms_use;
static uint8_t s_ms_ready; /* 使用区是否已产出过有效结果 */
static uint32_t s_ms_seq; /* 只增帧号（写者单写者，读者原子单字读） */
/*
* 函数功能：清零一份快照（含 rsv 与全部数组元素）
* 入口参数：p - 目标快照
* 返 回 值：无
* 限定条件：p 非空
* 函数说明：静态辅助；逐字段清零（不依赖 memset，行为与本目录 phasor_zero 同型）。
*/
static void meas_zero(meas_snap_t *p) {
uint8_t i;
p->seq = 0u;
p->tick_ms = 0u;
p->valid = 0u;
p->rsv[0] = 0u;
p->rsv[1] = 0u;
p->rsv[2] = 0u;
p->freq_valid = 0u;
p->freq_hz = 0.0f;
for (i = 0u; i < (uint8_t)ADC_SEM_COUNT; i++) {
p->yc[i] = 0.0f;
p->qds[i] = 0u;
}
}
/*
* 函数功能：遥测快照层初始化
* 入口参数：无
* 返 回 值：0 - 成功
* 限定条件：内核启动前或任务上下文皆可；幂等，可重复调用
* 函数说明：清双区 + 索引/就绪/序号复位。init 后到首次发布前，meas_get() 恒
* 返 -2（out 清零）、meas_seq() 恒返 0。
*/
int meas_init(void) {
meas_zero(&s_ms_snap[0]);
meas_zero(&s_ms_snap[1]);
s_ms_use = 0u;
s_ms_ready = 0u;
s_ms_seq = 0u;
return 0;
}
/*
* 函数功能：一拍遥测发布（被调即发布，节拍把关在调用方）
* 入口参数：tick_ms - 本拍时基（毫秒） uint32_t
* freq_valid_in - 频率读数新鲜度（freq_valid() 值） uint8_t
* freq_hz_in - 频率读数（freq_last() 值） float
* clip_mask - 削顶通道位图（bit s = 语义通道 s，来源唯一 =
* adc_cal_flags()，编排方注入） uint32_t
* 返 回 值：无
* 限定条件：仅 adcTask 上下文、全仓唯一调用点（meas.h 发布纪律）；须在
* phasor_run() 之后调用（本拍窗含最新点，与使用区同窗同核）
* 函数说明：电气 8 路（语义序中 TEMP 之前的全部通道，映射表属主 =
* docs/硬件平台/ADC通道映射说明.md）逐路一周波基波 DFT；任一路取窗
* 不足（开机未满一周波）→ 该路 IV|NT + 整帧 valid=0，但照常发布
* （品质节拍性刷新，见 meas_tick 头注）。TEMP 只取最新一点透传 +
* NT（「数据可信」决策 5）。品质值不因 IV 清零——"值在场但不可信"
* 与"值缺失"分开，消费者按 qds 裁决。
*/
void meas_tick(uint32_t tick_ms, uint8_t freq_valid_in, float freq_hz_in,
uint32_t clip_mask) {
meas_snap_t *z = &s_ms_snap[1u - s_ms_use]; /* 计算区 = 非使用区 */
float win[PHASOR_N];
phasor_t p;
uint8_t all_ok = 1u;
uint8_t s;
meas_zero(z);
z->seq = s_ms_seq + 1u;
z->tick_ms = tick_ms;
for (s = 0u; s < (uint8_t)ADC_SEM_TEMP; s++) {
if (sample_ring_window((adc_semantic_t)s, (uint8_t)PHASOR_N, win) == 0) {
phasor_calc(win, (uint8_t)PHASOR_N, 1u, &p);
z->yc[s] = p.fAmSQ; /* 有效值口径（系数已折算，同 phasor 层） */
if ((clip_mask & (1uL << s)) != 0u) {
z->qds[s] |= (uint16_t)MEAS_QDS_CLIPPED;
}
} else {
/* 本路窗不足：值缺位（yc 保持 0）+ IV|NT；整帧判不可信 */
z->qds[s] = (uint16_t)(MEAS_QDS_IV | MEAS_QDS_NT);
all_ok = 0u;
}
}
/* TEMP：非交流量语义（「数据可信」决策 5），最新一点原始帧值透传 + NT；
* clip_mask 位 8 不参与（adc_cal_flags(TEMP) 恒 0，无削顶语义） */
{
float tv = 0.0f;
if (sample_ring_window(ADC_SEM_TEMP, 1u, &tv) == 0) {
z->yc[ADC_SEM_TEMP] = tv;
z->qds[ADC_SEM_TEMP] = (uint16_t)MEAS_QDS_NT;
} else {
z->qds[ADC_SEM_TEMP] = (uint16_t)(MEAS_QDS_IV | MEAS_QDS_NT);
}
}
z->valid = all_ok;
z->freq_valid = (freq_valid_in != 0u) ? 1u : 0u;
z->freq_hz = freq_hz_in;
/* 全部字段就绪后才翻索引 + 置就绪（顺序即协议，勿交换） */
s_ms_seq = z->seq;
s_ms_use = (uint8_t)(1u - s_ms_use);
s_ms_ready = 1u;
}
/*
* 函数功能：读当前使用区快照（无锁整体拷贝）
* 入口参数：out - 输出快照；失败路径同样清零填充
* 返 回 值：0 - 成功；-1 - 参数错；-2 - 从未发布过 int
* 限定条件：任意上下文；无（读 volatile 索引 + 普通拷贝）
* 函数说明：先取索引再索引拷贝，避免拷贝中途索引被翻转导致"半旧半新"。
* 返回 0 时帧内部自洽（同一发布拍的 seq/tick_ms/yc/qds 成套）。
*/
int meas_get(meas_snap_t *out) {
uint8_t z;
if (out == NULL) {
return -1;
}
if (s_ms_ready == 0u) {
meas_zero(out);
return -2;
}
z = s_ms_use;
*out = s_ms_snap[z];
return 0;
}
/*
* 函数功能：读已发布帧数（只增）
* 入口参数：无
* 返 回 值：seq，0 = 从未发布（单字读，原子） uint32_t
* 限定条件：任意上下文
* 函数说明：轻量"是否换帧"探针，正式取数以 meas_get() 为准。
*/
uint32_t meas_seq(void) {
return s_ms_seq;
}
App/algo/meas.h
+137
View File
@@ -0,0 +1,137 @@
/*
* 模块名称：遥测快照发布层（全周傅氏相量派生·发布侧，「数据可信」§4.5）
* 模块功能：每 **200 ms** 从 全周傅氏相量层取一次基波有效值 + 品质，产出一份全仓唯一的
* 遥测快照（meas_snap_t，布局权威 = docs/任务规划/数据可信.md §4.5），
* 让 104 与 UI **共用同一份上游**——"什么时候算新值、品质怎么判"只此
* 一处决定（M5 遥测链的地基；104 侧消费见「数据可信」104 改读快照，UI 侧 ui_data_feed 属
* 「UI 扩展」波次，两者都只是本快照的读者）。
* 值口径（批 2「遥测快照发布」的 A-lite 裁决，2026-10-25）：**基波有效值瞬时透传**
* （同拍 phasor 使用区口径，系数已在 标定折算折算进帧值——现单位 = ADC
* 引脚电压 V，二次值语义等 adc_cal_flags() 出 VALID，见
* docs/算法/采集与算法层设计说明.md §10 红线③）；**不做** 4 点平均 /
* 谐波方和根——docs/任务规划/数据可信.md §4.5 明示"200 ms 是上送节拍
* 不是平均窗，再平均引入滞后"；谐波 k-bin 轨（docs/算法/继电保护功能
* 复现规划.md 遥测谐波轨（可选））将来扩展时只许在本结构**尾部追加**或留在发布侧
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* 内部状态，既有字段序不得变更。
* TEMP 通道（「数据可信」决策 5：不参与线性标定）：yc = 最新一拍原始
* 帧值透传，qds 恒置 NT——值在场但非交流量语义，UI 按「数据可信」§4.2
* 三态表显示占位符，104 无对应点。
* 并发（docs/任务规划/数据可信.md §4.5 原文口径）：沿用 phasor 的
* **双区 + 单字节活跃索引翻转**（双区指针原子交换 同型，不是新机制）——写侧填满
* 计算区后一次 store 翻转，读者先取索引再整体拷贝，全程无锁；
* seq 只增，消费者据此判"是否换帧"。
* 本层**纯算法**：不碰寄存器、不碰 RTOS、不自己取数（窗自 sample_ring、
* 频率/品质由调用方注入）→ 主机侧免桩纯逻辑单测 test/host/meas/。
* 发布纪律：唯一发布者 = adcTask（在 phasor_run()/freq_run() 之后 200 ms 分频
* 调 meas_tick()）。评审判据 = 全仓 meas_tick 调用点数 == 1（「数据可信」
* §8 风险表"快照双写"行）；其余任务/模块**只读**。
* 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
* 作者：DTU 项目组
* 创建日期：2026-10-25（道D 遥测快照发布）
* 修改记录：
* v1.0 2026-10-25 DTU 项目组 创建：200 ms 遥测快照 + 双区无锁读
*/
#ifndef MEAS_H
#define MEAS_H
#include <stdint.h>
#include "adc_input.h" /* adc_semantic_t / ADC_SEM_COUNT：yc/qds 下标 = 语义通道 */
#ifdef __cplusplus
extern "C" {
#endif
/* 上送节拍（ms）：adc_task 按本宏对 1 kHz 拍做**经过时间**分频（非拍计数——
* idle/skip 拍会把拍计数口径拉得比名义值长），落点见 App/task/adc_task.c */
#define MEAS_PERIOD_MS 200u
/* 每点品质位（uint16）。**低字节与线上 104 QDS 字节同值**（OV/NT/IV，数值
* 口径同 App/protocol/iec104/iec104_asdu.h 的 IEC104_QDS_*）——但本层**不得**
* include 协议层头（分层方向：算法层在协议层之下，反向依赖禁止），故在此自
* 定义同值常量；104 侧消费（104 改读快照）直接截低字节上送，一致性由本目录单测与
* test/host/iec104/ 既有断言双向钉住。高字节为 meas 域扩展位（线上不直接
* 出现，由消费者映射）： */
#define MEAS_QDS_OV (0x0001u) /* 溢出（留位，本项不产出——判据待运行参数化） */
#define MEAS_QDS_NT (0x0020u) /* 非当前值：未就绪 / 语义未处理（TEMP） */
#define MEAS_QDS_IV (0x0080u) /* 无效：该路取窗失败，无有效读数 */
#define MEAS_QDS_CLIPPED (0x0100u) /* 硬件削顶（adc_cal_flags 位图直通，
* 「数据可信」§4.2 三态表；AC 量不可信，
* 消费者应映射为品质无效，如 104 改读快照侧的 IV） */
/* 遥测快照（docs/任务规划/数据可信.md §4.5 权威布局；实测 72 B，2×72 ≈ 144 B
* 双区 = 本项 DoD 预算口径，由 test/host/meas/ 的布局钉死用例锁字段偏移——
* 改字段 = 破协议，须同步 104 改读快照 / UI） */
typedef struct {
uint32_t seq; /* 只增；消费者据此判断是否换帧 */
uint32_t tick_ms; /* 发布拍时基（osKernelGetTickCount 原值） */
uint8_t valid; /* 整帧有效：本拍 8 电气路取窗全部成功 */
uint8_t rsv[3]; /* 对齐填充，恒 0 */
float yc[ADC_SEM_COUNT]; /* 工程量（引脚电压 V 域；二次值等 VALID 标定） */
uint16_t qds[ADC_SEM_COUNT]; /* 每点品质 MEAS_QDS_*（值本身不因品质清零） */
uint8_t freq_valid; /* 频率读数新鲜度（freq_valid() 注入） */
float freq_hz; /* 频率读数（freq_last() 注入，未收敛为 0） */
} meas_snap_t;
/*
* 函数功能：遥测快照层初始化（清双区 / 索引 / 序号 / 就绪标志）
* 入口参数：无
* 返 回 值：0 - 成功 int
* 限定条件：内核启动前或任务上下文皆可（纯 .bss 状态，无 RTOS 依赖）；
* 本仓落点 = adc_task_init()（每开机一次，幂等可重复调）
* 函数说明：init 后 meas_get() 返 -2、meas_seq() 返 0，直到首次 meas_tick()
* 发布——消费者据 -2 走"未就绪"分支，不读半初始化数据。
*/
int meas_init(void);
/*
* 函数功能：一拍遥测发布（200 ms 分频由调用方把关，本函数被调即发布一帧）
* 入口参数：tick_ms - 本拍时基（毫秒） uint32_t
* freq_valid_in - 频率读数新鲜度（freq_valid() 值） uint8_t
* freq_hz_in - 频率读数（freq_last() 值；从未收敛为 0.0） float
* clip_mask - 削顶通道位图（bit s = 语义通道 s；来源唯一 =
* adc_cal_flags() 的 ADC_CAL_F_CLIPPED，编排方注入，
* 本层不链 adc_cal——可用性属主在折算侧） uint32_t
* 返 回 值：无
* 限定条件：**仅 adcTask 上下文、全仓唯一调用点**（发布纪律见文件头）；
* 须在 sample_ring_push_frame()/phasor_run() 之后调用，本拍窗才含最新点
* 函数说明：8 电气路逐路取"以本拍为终止的一周波"做基波 DFT（复用 phasor_calc
* 纯函数核，与 phasor 使用区同窗同核 → 同拍同值，见单测钉死），
* 任一路窗不足 → 该路 yc=0 + qds=IV|NT、整帧 valid=0（不产出半新半旧
* 混合帧；与 phasor_run 的差异：phasor 宁可不切区，meas **照常发布**
* 让品质位可见——消费者需要节拍性的品质刷新，seq 亦随之只增）。
* TEMP = 最新一点透传 + NT（见文件头）。末尾单字节翻转使用区，
* 读者无锁。
*/
void meas_tick(uint32_t tick_ms, uint8_t freq_valid_in, float freq_hz_in,
uint32_t clip_mask);
/*
* 函数功能：读当前使用区快照（无锁整体拷贝）
* 入口参数：out - 输出快照；失败（含 -2 未就绪）时**清零填充**，调用方可安全读
* 返 回 值：0 - 成功；-1 - 参数错；-2 - 从未发布过（out 已清零，seq=0） int
* 限定条件：任意上下文（任务级读者：iec104Task / uiTask / protectTask）
* 函数说明：先取一次使用区索引再索引拷贝——拷贝期间写者最多改"**非使用区**"，
* 本帧无撕裂（双区不变量，同 phasor_get 口径；写者两帧间隔 200 ms
* 远大于 72 B 拷贝耗时，读者被压超 200 ms 的竞态窗口按 §4.5 设计接受）。
* 判"新不新"用 seq：与上次不同则换帧。
*/
int meas_get(meas_snap_t *out);
/*
* 函数功能：读已发布帧数（只增）
* 入口参数：无
* 返 回 值：seq（0 = 从未发布；单字 32 位读，Cortex-M 原子） uint32_t
* 限定条件：任意上下文
* 函数说明：轻量观测入口（104 周期上送可先比 seq 省 72 B 拷贝）；
* 与 meas_get 之间无原子性配对要求（读者以 get 返回的 seq 为准）。
*/
uint32_t meas_seq(void);
#ifdef __cplusplus
}
#endif
#endif /* MEAS_H */
App/algo/phasor.c
+18 -18
View File
@@ -1,12 +1,12 @@
/*
* 模块名称：相量计算层（L2 相量计算）
* 模块名称：相量计算层（全周傅氏相量计算）
* 模块功能：全周傅氏算法（单频 DFT）——系数表预乘 √2/N，fAmSQ 直接即有效值。
* 覆盖 L2-1 系数表 / L2-2 实例 / L2-3 有效值 / L2-6 滑动窗 / L2-7 双区交换。
* 覆盖 全周傅氏系数表 / 基波相量实例 / 相量有效值输出 / 每 1 ms 滑动窗刷新 / 双区指针原子交换。
* 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
* 作者：王建锋
* 创建日期：2026-10-10
* 修改记录：
* v1.0 2026-10-10 王建锋 创建：L2-1/2/3/6/7
* v1.0 2026-10-10 王建锋 创建：全周傅氏系数表 等
*/
#include "phasor.h"
@@ -16,7 +16,7 @@
#include "sample_ring.h"
/* ===== L2-1 全周傅氏系数表 =====
/* ===== 全周傅氏系数表 =====
* g_fFFTSin20[k] = sin(2πk/N)·(√2/N)
* g_fFFTCos20[k] = cos(2πk/N)·(√2/N) N = PHASOR_N = 20
* 权威口径：docs/算法/傅氏算法详解.md §2.3（"把 √2 藏进系数表"）。
@@ -41,29 +41,29 @@ static const float k_fft_cos[PHASOR_N] = {
/* √2：幅值 = √2 × 有效值（与系数表的 √2 折算互逆） */
#define PHASOR_SQRT2 1.4142135623730951f
/* ===== L2-2 相量实例表 =====
/* ===== 基波相量实例表 =====
* 参考项目为 **4 个实例**（C01 基波 I/U、C02 零序基波、C03 二次谐波、C04 五次谐波，
* `APP/CLS100_Dsp/InstCalCell.c`）。本项目按 V0.1 **有效通道**（`UA`/`UN`/`IA`，
* 见规划 §1.6：`UB/UC/IB/IC/IN` 无中点偏置 → 削顶不可用）展开——C01 的"I/U"
* 拆为两行（IA 电流 / UA 电压），并补出 C04 的五次谐波轨（L1-9）。
* 见 docs/算法/继电保护功能复现规划.md §1.6：`UB/UC/IB/IC/IN` 无中点偏置 → 削顶不可用）展开——C01 的"I/U"
* 拆为两行（IA 电流 / UA 电压），并补出 C04 的五次谐波轨（二次谐波/五次谐波提取入口）。
* 新增实例只需在表尾加一行，其余代码自动适配。 */
static const phasor_inst_t k_inst[] = {
{ "C01-IA-F1", ADC_SEM_IA, 1u }, /* A 相电流基波（L3-1 过流 / L3-3 过负荷） */
{ "C02-UA-F1", ADC_SEM_UA, 1u }, /* A 相电压基波（L3-4 过压/欠压、L3-5 频率） */
{ "C03-UN-F1", ADC_SEM_UN, 1u }, /* 零序电压基波（L3-6 零序过压） */
{ "C04-IA-F2", ADC_SEM_IA, 2u }, /* 二次谐波（L3-7 涌流制动） */
{ "C05-IA-F5", ADC_SEM_IA, 5u }, /* 五次谐波（L1-9 选线） */
{ "C01-IA-F1", ADC_SEM_IA, 1u }, /* A 相电流基波（三段式相间过流 / 过负荷） */
{ "C02-UA-F1", ADC_SEM_UA, 1u }, /* A 相电压基波（过压 / 欠压、过频 / 低频） */
{ "C03-UN-F1", ADC_SEM_UN, 1u }, /* 零序电压基波（零序过压） */
{ "C04-IA-F2", ADC_SEM_IA, 2u }, /* 二次谐波（涌流制动） */
{ "C05-IA-F5", ADC_SEM_IA, 5u }, /* 五次谐波（二次谐波/五次谐波提取入口（选线用）） */
};
#define PHASOR_INST_N (sizeof(k_inst) / sizeof(k_inst[0]))
/* ===== L2-7 双区（计算区 / 使用区）=====
/* ===== 双区指针原子交换（计算区 / 使用区）=====
* 本拍结果先写入"计算区"，全部实例写完后**一次性**切换 s_use_zone
* （单字节 store，Cortex-M 上原子），消费侧读"使用区" → 无锁、无撕裂。
* s_use_zone 声明 volatile：阻止编译器把结果写入挪到切换之后
* （本平台单核顺序执行，无需额外内存屏障）。
* 今日唯一消费者是 adcTask 自身（同拍读写、实际无竞争），本机制为后续
* 独立保护任务（L3）预留。 */
* 写者 = adcTask（同拍）；读者跨两个上下文：adcTask 心跳与 protectTask 判据
* （prot_elm_run → phasor_get）→ 无锁读正是为后者服务，勿改成加锁或去掉双区。 */
static phasor_t s_zone[2][PHASOR_INST_N];
static volatile uint8_t s_use_zone;
static uint8_t s_ready; /* 使用区是否已产出过有效结果 */
@@ -83,7 +83,7 @@ static void phasor_zero(phasor_t *p) {
}
/*
* 函数功能：对 n 点窗口算 harm 次相量（L2-1 系数表 + L2-3 有效值）
* 函数功能：对 n 点窗口算 harm 次相量（全周傅氏系数表 + 相量有效值输出）
* 入口参数：x - 采样窗（按时间序，旧 → 新）
* n - 窗长（必须等于 PHASOR_N）
* harm - 谐波次数（>=1）
@@ -134,7 +134,7 @@ int phasor_init(void) {
}
/*
* 函数功能：取相量实例数（L2-2）
* 函数功能：取相量实例数
* 入口参数：无
* 返 回 值：实例个数
* 限定条件：无
@@ -159,7 +159,7 @@ const phasor_inst_t *phasor_inst(uint8_t idx) {
}
/*
* 函数功能：重算全部实例 + 双区原子切换（L2-6 / L2-7）
* 函数功能：重算全部实例 + 双区原子切换（每 1 ms 滑动窗刷新 / 双区指针原子交换）
* 入口参数：无
* 返 回 值：无
* 限定条件：仅任务上下文调用；须先 sample_ring_push_frame() 压入本拍数据
App/algo/phasor.h
+11 -10
View File
@@ -1,18 +1,19 @@
/*
* 模块名称：相量计算层（L2 相量计算）
* 模块名称：相量计算层（全周傅氏相量计算）
* 模块功能：全周傅氏（全周波傅里叶）算法——对一周波 20 点采样做单频 DFT，
* 产出基波/谐波相量。系数表**预乘 √2/N**（口径见
* `docs/算法/傅氏算法详解.md` §2.3），故 `fAmSQ = √(fRe²+fIm²)`
* **直接就是有效值**，无需再除 √2。
* 覆盖规划 §3.2：L2-1 系数表 / L2-2 实例 / L2-3 有效值输出 /
* L2-6 每 1 ms 滑动窗 / L2-7 双区指针原子交换。
* 覆盖规划 §3.2：全周傅氏系数表 / 基波相量实例 / 相量有效值输出 /
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* 每 1 ms 滑动窗刷新 / 双区指针原子交换。
* ⚠ 本层**纯算法**：不碰寄存器、不碰任务调度、不自己取数（输入由
* `sample_ring` 提供）→ 主机侧可单测（L0.5，落实登记簿 A-4）。
* `sample_ring` 提供）→ 主机侧可纯逻辑单测。
* 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
* 作者：王建锋
* 创建日期：2026-10-10
* 修改记录：
* v1.0 2026-10-10 王建锋 创建：L2-1/2/3/6/7（基波 + 谐波相量）
* v1.0 2026-10-10 王建锋 创建：全周傅氏系数表 等（基波 + 谐波相量）
*/
#ifndef PHASOR_H
@@ -35,7 +36,7 @@ extern "C" {
* fIm - 虚部 = b1/√2（有效值相量虚部）
* fAm - 幅值 = √2·√(fRe²+fIm²)（正弦峰值 A1）
* fAmSQ - 有效值 = √(fRe²+fIm²)（系数已折算 √2/N，故直接即有效值）
* 相位（L2-4）按需由 `atan2(fIm, fRe)` 导出，不常驻本结构。 */
* 相位输出按需由 `atan2(fIm, fRe)` 导出，不常驻本结构。 */
typedef struct {
float fRe;
float fIm;
@@ -43,7 +44,7 @@ typedef struct {
float fAmSQ;
} phasor_t;
/* 相量实例（L2-2）：**数据驱动**——新增实例只需在实例表尾加一行 */
/* 基波相量实例：**数据驱动**——新增实例只需在实例表尾加一行 */
typedef struct {
const char *name; /* 实例名（日志 / UI 用） */
adc_semantic_t sem; /* 语义通道 */
@@ -60,7 +61,7 @@ typedef struct {
int phasor_init(void);
/*
* 函数功能：取相量实例数（L2-2）
* 函数功能：取相量实例数
* 入口参数：无
* 返 回 值：实例个数
* 限定条件：无
@@ -78,7 +79,7 @@ uint8_t phasor_inst_count(void);
const phasor_inst_t *phasor_inst(uint8_t idx);
/*
* 函数功能：重算全部实例并从计算区原子切换到使用区（L2-6 滑动窗 + L2-7 双区交换）
* 函数功能：重算全部实例并从计算区原子切换到使用区（每 1 ms 滑动窗刷新 + 双区指针原子交换）
* 入口参数：无
* 返 回 值：无
* 限定条件：仅任务上下文调用；须先经 `sample_ring_push_frame()` 压入本拍数据
@@ -99,7 +100,7 @@ void phasor_run(void);
int phasor_get(uint8_t idx, phasor_t *out);
/*
* 函数功能：对 n 点窗口算 harm 次相量（L2-1 系数表 + L2-3 有效值）
* 函数功能：对 n 点窗口算 harm 次相量（全周傅氏系数表 + 相量有效值输出）
* 入口参数：x - 采样窗（按时间序，旧 → 新；长度须 = PHASOR_N）
* n - 窗长（必须等于 PHASOR_N）
* harm - 谐波次数（>=1）
App/algo/prot_elm.c
+75 -15
View File
@@ -1,5 +1,5 @@
/*
* 模块名称：保护元件框架（L3，P1 子集）——实现
* 模块名称：保护元件框架（保护判据，P1 子集）——实现
* 模块功能：见 prot_elm.h。判据核 prot_elm_eval() 为纯逻辑（prot_set RAM +
* 测量数组 → 状态机），prot_elm_run() 是 phasor→测量的薄适配层。
*
@@ -18,12 +18,20 @@ typedef struct {
uint8_t over; /* 1 = 过量（越上限动作），0 = 欠量（越下限动作） */
uint8_t src; /* 测量源：0 = phasor 基波有效值，1 = freq 测频 */
prot_set_id_t en_id; /* 投退定值 */
uint8_t trip_ctl; /* 跳闸投退定值项（PS_*_TRIP）；PROT_ELM_NO_TRIP =
* 该元件没有这一项（告警类）→ 动作只出告警记录。
* 用 uint8_t 而不是 prot_set_id_t 就是因为要能表达
* "无此项"这个第 41 种取值（PS_ID_COUNT 是数组长度，
* 拿去喂 prot_set_get_ctl() 会越界读） */
prot_set_id_t set_id; /* 动作定值 */
prot_set_id_t dly_id; /* 延时定值（ms） */
prot_set_id_t ret_id; /* 返回系数定值（RET_OVER / RET_UNDER） */
const char *pprefix; /* 相量实例名前缀（"C01"…）；src=1 时为 0（不用） */
} pe_cfg_t;
/* k_pe[].trip_ctl 的"无此定值项"取值（见上方字段注释） */
#define PROT_ELM_NO_TRIP 0xFFu
/* 测量源枚举（pe_cfg_t.src） */
#define PE_SRC_PHASOR 0u
#define PE_SRC_FREQ 1u
@@ -31,18 +39,24 @@ typedef struct {
/* freq 无有效读数时给欠量元件的"必不启动"填充值（远大于任何欠量定值上限） */
#define PE_MEAS_BIG 1e30f
static const pe_cfg_t k_pe[PE_COUNT] = {
{ "OC1-IA", 1u, PE_SRC_PHASOR, PS_OC1_EN, PS_OC1_CUR, PS_OC1_DLY, PS_RET_OVER, "C01" },
{ "OC2-IA", 1u, PE_SRC_PHASOR, PS_OC2_EN, PS_OC2_CUR, PS_OC2_DLY, PS_RET_OVER, "C01" },
{ "OC3-IA", 1u, PE_SRC_PHASOR, PS_OC3_EN, PS_OC3_CUR, PS_OC3_DLY, PS_RET_OVER, "C01" },
{ "OL-IA", 1u, PE_SRC_PHASOR, PS_OL_EN, PS_OL_CUR, PS_OL_DLY, PS_RET_OVER, "C01" },
{ "OV-UA", 1u, PE_SRC_PHASOR, PS_OV_EN, PS_OV_VOL, PS_OV_DLY, PS_RET_OVER, "C02" },
{ "UV-UA", 0u, PE_SRC_PHASOR, PS_UV_EN, PS_UV_VOL, PS_UV_DLY, PS_RET_UNDER, "C02" },
{ "3U0-UN", 1u, PE_SRC_PHASOR, PS_3U0_EN, PS_3U0_VOL, PS_3U0_DLY, PS_RET_OVER, "C03" },
/* 过频/低频（L3-5，B8）：测量量 = freq 层测得频率（Hz），返回系数独立
/* 列序 = pe_cfg_t 字段序（name, over, src, en_id, trip_ctl, set_id, dly_id, ret_id,
* pprefix）。⚠ trip_ctl 紧跟 en_id 插入，新增元件必须照这一列的口径填：有跳闸投退
* 定值项的填 PS_*_TRIP，没有的填 PROT_ELM_NO_TRIP（= 该元件动作只出告警记录）。*/
static const pe_cfg_t k_pe[PE_COUNT] = { /* ← 表头注释见上，行内列序与之一致 */
{ "OC1-IA", 1u, PE_SRC_PHASOR, PS_OC1_EN, PS_OC1_TRIP, PS_OC1_CUR, PS_OC1_DLY, PS_RET_OVER, "C01" },
{ "OC2-IA", 1u, PE_SRC_PHASOR, PS_OC2_EN, PS_OC2_TRIP, PS_OC2_CUR, PS_OC2_DLY, PS_RET_OVER, "C01" },
{ "OC3-IA", 1u, PE_SRC_PHASOR, PS_OC3_EN, PS_OC3_TRIP, PS_OC3_CUR, PS_OC3_DLY, PS_RET_OVER, "C01" },
{ "OL-IA", 1u, PE_SRC_PHASOR, PS_OL_EN, PS_OL_TRIP, PS_OL_CUR, PS_OL_DLY, PS_RET_OVER, "C01" },
/* ↓ 三项 + 下面两项频率元件：参考系统的告警段（0x8027~0x802A）本就没有「跳闸
投退」这一档，g_prot_set_meta 也无对应项 → PROT_ELM_NO_TRIP，动作一律归告警。
这不是兜底猜测，是照实反映（"哪些元件算跳闸"的真源始终是这张表 + 定值表）。*/
{ "OV-UA", 1u, PE_SRC_PHASOR, PS_OV_EN, PROT_ELM_NO_TRIP, PS_OV_VOL, PS_OV_DLY, PS_RET_OVER, "C02" },
{ "UV-UA", 0u, PE_SRC_PHASOR, PS_UV_EN, PROT_ELM_NO_TRIP, PS_UV_VOL, PS_UV_DLY, PS_RET_UNDER, "C02" },
{ "3U0-UN", 1u, PE_SRC_PHASOR, PS_3U0_EN, PROT_ELM_NO_TRIP, PS_3U0_VOL, PS_3U0_DLY, PS_RET_OVER, "C03" },
/* 过频/低频（过频 / 低频，B8）：测量量 = freq 层测得频率（Hz），返回系数独立
* （RET_OF/RET_UF——频率滞回带与电气量不同量级，勿共用 0.95/1.05） */
{ "OF-F", 1u, PE_SRC_FREQ, PS_OF_EN, PS_OF_HZ, PS_OF_DLY, PS_RET_OF, 0 },
{ "UF-F", 0u, PE_SRC_FREQ, PS_UF_EN, PS_UF_HZ, PS_UF_DLY, PS_RET_UF, 0 },
{ "OF-F", 1u, PE_SRC_FREQ, PS_OF_EN, PROT_ELM_NO_TRIP, PS_OF_HZ, PS_OF_DLY, PS_RET_OF, 0 },
{ "UF-F", 0u, PE_SRC_FREQ, PS_UF_EN, PROT_ELM_NO_TRIP, PS_UF_HZ, PS_UF_DLY, PS_RET_UF, 0 },
};
/* 运行时状态（picked/asserted 的对外快照 + 延时起点 + 相量实例索引缓存） */
@@ -122,7 +136,8 @@ void prot_elm_request_reset(void) {
* 入口参数：now_ms - 单调时基（tick ms，差值法回绕安全）
* meas - PE_COUNT 个测量值（工程量 A/V）；NULL 视为全 0
* 返 回 值：无
* 函数说明：投退=0 或定值闭锁（L5-1）→ 状态整体复位、不判据；
* 函数说明：投退=0 或定值闭锁（定值校验和）→ 状态整体复位、不判据；
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* 滞回 = 已启动用返回门槛（定值×系数）、未启动用动作门槛；
* 延时 dly=0 → 启动同拍即动作；返回即时（P4 接出口时再补返回延时）。
*/
@@ -189,7 +204,8 @@ void prot_elm_eval(uint32_t now_ms, const float meas[PE_COUNT]) {
* 函数功能：适配层——按实例表 src 组装测量数组后调判据核
* 入口参数：now_ms - 单调时基（tick ms）
* 返 回 值：无
* 限定条件：仅保护消费者任务上下文；工程量↔码值换算 = 1（L1-5 标定未实现）
* 限定条件：仅保护消费者任务上下文；测量已是 标定折算工程量（未标定域由
* protectTask 未标定即闭锁挡在门外，本函数不感知标定态）
* 函数说明：src=PHASOR 行任一相量未就绪（未满一周波）→ **整拍跳过**，
* 不引入陈旧/半新测量（B5 口径）。src=FREQ 行：freq 有有效读数
* （started 且幅值门 OK）→ 填测得频率；否则按方向填"必不启动"值
@@ -244,7 +260,7 @@ void prot_elm_state(prot_elm_id_t id, prot_elm_state_t *out) {
/*
* 函数功能：聚合动作位图
* 入口参数：无
* 返 回 值：bit i = 元件 i asserted（供 L4 出口 / 心跳日志）
* 返 回 值：bit i = 元件 i asserted（供 出口与记录 / 心跳日志）
*/
uint32_t prot_elm_active_mask(void) {
uint32_t mask = 0u;
@@ -258,6 +274,50 @@ uint32_t prot_elm_active_mask(void) {
return mask;
}
/*
* 函数功能：聚合启动位图
* 入口参数：无
* 返 回 值：bit i = 元件 i picked（越限电平，早于/等于 asserted）
* 限定条件：任意上下文（只读快照，无锁；与 prot_elm_active_mask 同口径）
* 函数说明：调用方是 protectTask 的「保护启动」记录边沿检测（task-10）。本函数
* **只聚合电平**，不造边沿——边沿属观测者状态（s_prev_pick 在那一侧），
* 判据核里再存一份"上一拍"会让 eval 不再幂等。
*/
uint32_t prot_elm_pick_mask(void) {
uint32_t mask = 0u;
uint32_t i;
for (i = 0u; i < (uint32_t)PE_COUNT; i++) {
if (s_rt[i].picked != 0u) {
mask |= (1uL << i);
}
}
return mask;
}
/*
* 函数功能：判定该元件动作上升沿应归哪一类记录（见 prot_elm.h 同号声明）
* 入口参数：id - 元件编号 prot_elm_id_t
* 返 回 值：PROT_REC_TRIP / PROT_REC_ALARM / PROT_REC_NONE（id 越界） prot_rec_kind_t
* 限定条件：任意上下文；只读，不改任何状态
* 函数说明：判据唯一来源 = k_pe[id].trip_ctl 指向的那枚 PS_*_TRIP 投退定值。
* trip_ctl == PROT_ELM_NO_TRIP 时**先返回告警**，绝不把 0xFF 喂给
* prot_set_get_ctl()（那是数组越界读，会读到定值区外的 RAM——
* 与"未标定拿 ADC 引脚电压当二次值"同类的静默错数据形状）。
*/
prot_rec_kind_t prot_elm_record_kind(prot_elm_id_t id) {
uint8_t trip_ctl;
if (id >= PE_COUNT) {
return PROT_REC_NONE;
}
trip_ctl = k_pe[(uint32_t)id].trip_ctl;
if (trip_ctl == (uint8_t)PROT_ELM_NO_TRIP) {
return PROT_REC_ALARM;
}
return (prot_set_get_ctl((prot_set_id_t)trip_ctl) != 0u) ? PROT_REC_TRIP : PROT_REC_ALARM;
}
/*
* 函数功能：取实例名（日志用）
* 入口参数：id - 元件编号
App/algo/prot_elm.h
+54 -13
View File
@@ -1,15 +1,16 @@
/*
* 模块名称：保护元件框架（L3，P1 子集）
* 模块名称：保护元件框架（保护判据，P1 子集）
* 模块功能：通用"越限 + 返回系数滞回 + 定时限"元件核 + 实例表（数据驱动，
* 同 phasor 实例表模式）。判据为**纯逻辑**（吃测量值 + 定值），
* 主机侧可离线单测；出口/SOE（L4）与任务编排为后续。
* 主机侧可离线单测；出口/SOE（出口与记录）与任务编排为后续。
*
* V0.1 有效实例（N-18：仅 TPAFE 三路）：
* OC1/OC2/OC3 三段式相间过流（A 相 IA，L3-1）
* OL 过负荷（A 相 IA，L3-3）
* OV/UV 过压/欠压（UA，L3-4）
* 3U0 零序过压（UN 外部零序电压通道，L3-6）
* OF/UF 过频/低频（测量量 = freq 层测得频率，L3-5，B8 落地）
* V0.1 有效实例（双转换器无共同采样触发 → 仅 TPAFE 三路）：
* OC1/OC2/OC3 三段式相间过流（A 相 IA）
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* OL 过负荷（A 相 IA）
* OV/UV 过压/欠压（UA，过压 / 欠压）
* 3U0 零序过压（UN 外部零序电压通道）
* OF/UF 过频/低频（测量量 = freq 层测得频率，过频 / 低频，B8 落地）
*
* 测量数组口径：相量类实例 = 基波有效值（A/V）；OF/UF = 测得频率（Hz）。
* run() 按实例表 src 字段取数（0=phasor rms，1=freq）。freq 无有效读数
@@ -22,7 +23,10 @@
* - 返回**即时**（参考 GRly_TimeRelay 带 10 ms 返回延时——V0.1 无出口硬件，
* 抖动只影响日志，P4 接出口时再补返回延时）；
* - 复压/方向/无压无流闭锁（dwSetFyCtrl 类）随 P2/P3 元件扩展；
* - 工程量↔码值换算系数暂为 1（L1-5 标定未实现，同 phasor 层口径）。
* - 测量输入 = adc_task 经 adc_cal_apply() 折算后的工程量（标定折算，标定折算已落地）：
* 未标定（VALID=0）时单位只是 ADC 引脚电压——该域下判据必然错配，由
* protectTask 的「数据可信」未标定即闭锁停走整条判据链，元件核本身不掺和
* 标定语义（保持纯逻辑）；标定后单位 = 二次值，定值口径才名副其实。
*
* 线程约定：init 内核启动前或保护消费者任务上下文；eval/run 仅保护消费者任务
* 上下文（B5 起 = protectTask）；request_reset 任意上下文（跨上下文复归请求，
@@ -45,8 +49,8 @@ typedef enum {
PE_OV, /* 过压（UA） */
PE_UV, /* 欠压（UA，欠量方向） */
PE_3U0, /* 零序过压（UN） */
PE_OF, /* 过频（测量量 = freq 层测得频率，B8，L3-5） */
PE_UF, /* 低频（测量量 = freq 层测得频率，欠量方向，B8，L3-5） */
PE_OF, /* 过频（测量量 = freq 层测得频率，B8，过频 / 低频） */
PE_UF, /* 低频（测量量 = freq 层测得频率，欠量方向，B8，过频 / 低频） */
PE_COUNT
} prot_elm_id_t;
@@ -78,7 +82,7 @@ void prot_elm_request_reset(void);
* meas - PE_COUNT 个测量值（工程量：A / V），NULL 视为全 0
* 返 回 值：无
* 限定条件：仅保护消费者任务上下文；调用方保证定值已装载
* 函数说明：越限方向由实例表决定；投退=0 或定值闭锁（L5-1）→ 状态复位、
* 函数说明：越限方向由实例表决定；投退=0 或定值闭锁（定值校验和）→ 状态复位、
* 不判据。延时判定用 (uint32_t)(int32_t)(now - t0) >= dly，回绕安全。
*/
void prot_elm_eval(uint32_t now_ms, const float meas[PE_COUNT]);
@@ -94,9 +98,46 @@ void prot_elm_run(uint32_t now_ms);
/* 状态快照拷贝（NULL 安全；越界全零） */
void prot_elm_state(prot_elm_id_t id, prot_elm_state_t *out);
/* 动作位图（bit i = 元件 i asserted），供 L4 出口 / 心跳日志 */
/* 动作位图（bit i = 元件 i asserted），供 出口与记录 / 心跳日志 */
uint32_t prot_elm_active_mask(void);
/* 启动位图（bit i = 元件 i picked），供「保护启动」记录边沿（task-10，2026-10-26）：
* picked 是越限滞回后的电平，早于（或同拍于）asserted——只看 active_mask 会让
* "启动了但没到点"这一整段在记录里彻底消失，而它正是"保护启动"页要看的东西。 */
uint32_t prot_elm_pick_mask(void);
/*
* 元件动作边沿的记录归属（task-10「五类记录」）。
* ⚠ 本枚举刻意**不**用 syslog_id_t：那会把 App/log 的头拽进 algo 层，而
* App/algo/prot_elm.c 同时被 test/host/prot_dim 编进测试单元（那个运行器的
* include 路径里没有 App/log，且不在本道写域）→ 一改就在别人的单测上爆错。
* "元件 → 哪一类"是判据域事实（属主在本文件），"哪一类 → 哪个日志文件"是
* 记录域映射（属主在 App/task/protect_task.c 的一行三元），两边各自单源。
*/
typedef enum {
PROT_REC_TRIP = 0u, /* 跳闸型动作 → 事故记录 */
PROT_REC_ALARM, /* 告警型动作 → 保护告警记录 */
PROT_REC_NONE /* id 越界 → 调用方一条都不许落 */
} prot_rec_kind_t;
/*
* 函数功能：判定"该元件若发生动作上升沿，应归哪一类记录"
* 入口参数：id - 元件编号 prot_elm_id_t
* 返回值：PROT_REC_TRIP / PROT_REC_ALARM / PROT_REC_NONE（越界） prot_rec_kind_t
* 限定条件：任意上下文（只读 k_pe[] + prot_set RAM，不落任何状态）
* 函数说明：判据**唯一来源** = 该元件的跳闸投退定值项 g_prot_set_meta 里的
* PS_*_TRIP（其枚举注释即"0 告警 / 1 跳闸"）。元件→投退项的对应关系
* 放在实例表 k_pe[] 的 trip_ctl 列（与 en_id/set_id/dly_id 同一张表，
* 新增元件只加一行）；**本函数里没有第二份"哪些元件算跳闸"的名单**，
* 所以它不会与 g_prot_set_meta / k_pe[] / 整定视图门禁互相打架。
* 过压/欠压/零序过压/过频/低频五项本就没有 TRIP 投退项（告警类）→
* trip_ctl = PROT_ELM_NO_TRIP → 恒 PROT_REC_ALARM，这是照实反映，
* 不是兜底猜测。
* 定值巡检闭锁（prot_set_locked）不影响本判定：闭锁态下元件会被复位、
* 根本走不到动作上升沿，调用方无需在此重复判闭锁。
*/
prot_rec_kind_t prot_elm_record_kind(prot_elm_id_t id);
/* 实例名（ROM 常量，日志用） */
const char *prot_elm_name(prot_elm_id_t id);
App/algo/prot_set.c
+13 -4
View File
@@ -1,10 +1,19 @@
/*
* 模块名称：保护定值模型（P1，L5-1 载体）——实现
* 模块名称：保护定值模型（P1，定值校验和 载体）——实现
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* 模块功能：见 prot_set.h。纯逻辑，零平台依赖（仅 stdint.h + 自身头）。
*
* ⚠ 默认值/范围为拟定值（参考 EEPROM 出厂默认表不在本仓库，规划 §10.3 待补）；
* 通讯地址逐项对照参考 Comm/Pub/Const_CommSetPara.c g_tCommSetParaTab。
*
* 量纲口径（「数据可信」下游常数按工程量重定一项复核，2026-10-25）：A/V 项 = **二次值**工程量，
* 标称基准 100 V / 1 A（UA/UB/UC 相电压、3U0、OV/UV 同域——OV 120 = 1.2×Un、
* UV 20 = 0.2×Un、3U0 15 = 0.15×Un；OC1/2/3 = 10/5/2 ×Ir、OL = 1.0×Ir，
* 三段递升与过负荷低于速断均自洽）。ADC 帧仅在 adc_cal VALID 置位后才处
* 于此域（未标定 = 引脚电压域，由未标定即闭锁停走判据，见 protect_task.c）；
* min/max 范围覆盖 0~4×标称，无需随这一项改动数值——换算依据与三处下游
* 常数同源，见 docs/任务规划/数据可信.md §2.3。
*
* 创建日期：2026-10-11
*/
#include "prot_set.h"
@@ -47,7 +56,7 @@ const prot_set_meta_t g_prot_set_meta[PS_ID_COUNT] = {
{ 0x8825, 0u, PROT_SET_Q10(100.0), PROT_SET_Q10(1.0), PROT_SET_Q10(10000.0) },
{ 0x8826, 0u, PROT_SET_Q10(5.0), PROT_SET_Q10(1.0), PROT_SET_Q10(10.0) },
{ 0x0000, 1u, PROT_SET_Q10(1), 0, PROT_SET_Q10(1) }, /* 全局软压板投退（YK12，B7） */
/* --- 过频 / 低频（L3-5，B8）：地址全 0 = 本地项（参考逐项地址不在
/* --- 过频 / 低频（B8）：地址全 0 = 本地项（参考逐项地址不在
* 本仓库，规划 §5.1 仅示"8820~8882 含低压/低频"类目）；
* 默认值/范围**拟定**（DTU 馈线典型量级），待对照参考出厂表修订 --- */
{ 0x0000, 1u, PROT_SET_Q10(1), 0, PROT_SET_Q10(1) }, /* OF 投退（本地） */
@@ -67,7 +76,7 @@ static volatile uint8_t s_act; /* 活跃区下标（0/1）；交换 =
static uint32_t s_sum; /* 封存的正码 */
static uint32_t s_sumn; /* 封存的反码 */
static uint64_t s_bad_mask; /* load_raw/parse 越界位图（B8：40 项 → 64 位） */
static uint8_t s_locked; /* 定值非法 → 闭锁（L5-1） */
static uint8_t s_locked; /* 定值非法 → 闭锁（定值校验和） */
static uint8_t s_dirty; /* 未落盘定值改动（B7 持久化脏标志） */
/*
@@ -285,7 +294,7 @@ void prot_set_seal(void) {
}
/*
* 函数功能：定值自检（L5-1）——重算 sum32 并与封存值比对
* 函数功能：定值自检（定值校验和）——重算 sum32 并与封存值比对
* 入口参数：无
* 返 回 值：0 通过 / -1 失配（已置闭锁）
* 函数说明：失配 → s_locked 置位并保持，直到下一次 seal；
App/algo/prot_set.h
+15 -11
View File
@@ -1,5 +1,5 @@
/*
* 模块名称：保护定值模型（P1，L5-1 载体）
* 模块名称：保护定值模型（P1，定值校验和 载体）
* 模块功能：保护定值的 RAM 模型——编号 / 通讯地址 / 范围 / 默认值 / 校验和自检，
* 以及 B7 定值持久化的**纯逻辑层**（blob 序列化/解析 + 原子装载）。
* 文件读写胶水在 App/cfg/prot_set_store.c（MCU 端）。
@@ -8,7 +8,7 @@
* - 定点存储：Q10（×1024），与参考系统定点系数 2^10 一致（§5.3）；
* - 通讯地址：与参考 g_tCommSetParaTab（Comm/Pub/Const_CommSetPara.c）逐项对齐，
* 基址 0x8820（=34848）；告警类沿用运行参数段 0x8027/0x8029；
* - 校验和（L5-1）：sum32 正码 + 反码成对封存（参考 tagPRS 的
* - 校验和（定值校验和）：sum32 正码 + 反码成对封存（参考 tagPRS 的
* dwTagSum/dwTagSumN 模式），selfcheck 失配 → 置闭锁；
* - ⚠ 默认值/范围为**拟定值**：参考 EEPROM 出厂默认表未在本仓库，
* 待对照后逐项修订（规划 §10.3 待补项）；范围先按 DTU 馈线典型量级。
@@ -26,13 +26,17 @@
#include <stdint.h>
/* Q10 定点：工程量 × 1024（与参考 2^10 口径一致） */
#define PROT_SET_Q10(v) ((int32_t)(((double)(v)) * 1024.0))
#define PROT_SET_FROM_Q10(v) ((float)((double)(v) / 1024.0))
/* Q10 定点：工程量 × 1024（与参考 2^10 口径一致）。
* 必须写成单精度：×/÷1024 只是 2^10 指数平移，float 与 double 的结果逐位相同
* （宏里 42 个字面量 + int32 全域往返均已穷举核对），而写成 double 会把
* MicroLIB 的软浮点拉进镜像——F407 只有单精度 FPU，本工程的保护判据每
* 20 ms 节拍每元件要读三次定值（见 prot_elm_run），软件双精度纯属白烧。 */
#define PROT_SET_Q10(v) ((int32_t)((float)(v) * 1024.0f))
#define PROT_SET_FROM_Q10(v) ((float)(v) / 1024.0f)
/* 定值项编号（枚举序 = RAM 数组序 = 校验和覆盖序，只增不删不改序） */
typedef enum {
/* --- 三段式相间过流（A 相，L3-1）：投退/跳闸投退/电流/延时 --- */
/* --- 三段式相间过流（A 相）：投退/跳闸投退/电流/延时 --- */
PS_OC1_EN = 0, /* 0x8856 Ⅰ段投退 */
PS_OC1_TRIP, /* 0x8857 Ⅰ段跳闸投退（0 告警 / 1 跳闸） */
PS_OC1_CUR, /* 0x8858 Ⅰ段电流定值（A，二次值） */
@@ -45,19 +49,19 @@ typedef enum {
PS_OC3_TRIP, /* 0x885F */
PS_OC3_CUR, /* 0x8860 */
PS_OC3_DLY, /* 0x8861 */
/* --- 过负荷（A 相，L3-3） --- */
/* --- 过负荷（A 相） --- */
PS_OL_EN, /* 0x8871 */
PS_OL_TRIP, /* 0x8872 */
PS_OL_CUR, /* 0x8873 */
PS_OL_DLY, /* 0x8874 */
/* --- 过压 / 欠压（UA，L3-4；沿用参考告警段 0x8029/0x8027） --- */
/* --- 过压 / 欠压（UA；沿用参考告警段 0x8029/0x8027） --- */
PS_OV_EN, /* 本地投退（参考告警类无独立投退，V0.1 补） */
PS_OV_VOL, /* 0x8029 过电压门限（V，二次值） */
PS_OV_DLY, /* 0x802A 过电压延时（ms） */
PS_UV_EN, /* 本地投退 */
PS_UV_VOL, /* 0x8027 低电压门限（V，二次值） */
PS_UV_DLY, /* 0x8028 低电压延时（ms） */
/* --- 零序过压（UN，L3-6） --- */
/* --- 零序过压（UN） --- */
PS_3U0_EN, /* 0x888E */
PS_3U0_VOL, /* 0x888F 3U0 定值（V，二次值） */
PS_3U0_DLY, /* 0x8890 延时（ms） */
@@ -70,7 +74,7 @@ typedef enum {
PS_CT_SEC, /* 0x8826 CT 二次额定（A） */
/* --- 全局软压板（B7）：104 YK12 两段式投退；0 = 保护退出服务 --- */
PS_GLOBAL_EN, /* 本地项（无通讯地址，经 YK12 写、C_RD 不可读） */
/* --- 过频 / 低频（L3-5，B8）：投退/动作频率/延时 + 各自返回系数 ---
/* --- 过频 / 低频（B8）：投退/动作频率/延时 + 各自返回系数 ---
* ⚠ 通讯地址：参考 g_tCommSetParaTab 的保护定值段（0x8820~0x8882）
* 含"低压/低频"类目（规划 §5.1），但 OF/UF 的**逐项地址不在本仓库**
* （参考 Comm 源文件未随仓库提供）→ 按"找不到对应即本地项"规则全部
@@ -126,7 +130,7 @@ int32_t prot_set_get(prot_set_id_t id); /* Q10 原值 */
float prot_set_get_f(prot_set_id_t id); /* 工程量浮点 */
uint8_t prot_set_get_ctl(prot_set_id_t id); /* 投退项：!=0 视为投入 */
/* 校验和（L5-1）：sum32 覆盖 RAM 值区；seal 封存正/反码对 */
/* 校验和（定值校验和）：sum32 覆盖 RAM 值区；seal 封存正/反码对 */
uint32_t prot_set_checksum(void);
void prot_set_seal(void);
/* 自检：重算并与封存值比对，失配 → 置闭锁并返回 -1（已闭锁也返回 -1） */
App/algo/run_par.c
+372
View File
@@ -0,0 +1,372 @@
/*
* 模块名称：运行参数段（全周傅氏相量/保护判据整定层，「数据可信」这一项）——实现
* 模块功能：见 run_par.h。工厂默认 = 「数据可信」下游常数按工程量重定后的额定 0.5 % 档（电压 500
* mV / 电流 5 mA / 频率 500 mHz，毫单位 int32 定点落盘）；[run_par]
* 段 9 键（db_ua…db_freq，均 ≤15 字符）≤ CFG_FILE_MAX_KEYS 不拆段
* （通道系数覆盖**不落本段**——直通 adc_cal 的 [adc_cal]/[adc_cal_ofs]，
* 系数唯一真源在那两段，lead 裁②a）。
* 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
* 作者：DTU 项目组
* 创建日期：2026-10-25（道D 运行参数段）
* 修改记录：
* v1.0 2026-10-25 DTU 项目组 创建：[run_par] 段 + 104 映射 + 直通 adc_cal
* + B7 式脏标志落盘请求
*/
/* 头文件包含区 */
#include <math.h>
#include <stddef.h>
#include <string.h>
#include "run_par.h"
#include "adc_cal.h"
#include "cfg_file.h"
#define DBG_TAG "[PAR]"
#include "dbg_log.h"
/* 常量定义区 */
/* cfg 段名（≤ CFG_FILE_MAX_NAME_LEN）；键名 6~7 字符小写 */
#define RUN_PAR_SEC "run_par"
/* 104 运行参数地址（复现规划 §5.1 类内落实；权威逐项表不在仓，送检点表到位
* 后以送检为准替换本常量段——lead 裁①。0x8027~0x802A = prot_set 告警段，永不让位） */
#define RUN_PAR_IOA_DB0 0x8030u /* 9 点：0x8030~0x8038 */
#define RUN_PAR_IOA_K0 0x8040u /* k 覆盖 8 路：0x8040~0x8047 */
#define RUN_PAR_IOA_B0 0x8048u /* b 覆盖 8 路：0x8048~0x804F */
/* 死区合法域上限（毫单位）：电压 50 V / 电流 1 A / 频率 5 Hz——守卫挡误写，
* 不限工况；下限统一 0（负死区 = 配置错误） */
#define RUN_PAR_DB_MAX_U 50000L
#define RUN_PAR_DB_MAX_I 1000L
#define RUN_PAR_DB_MAX_F 5000L
/* 静态变量定义区 */
/* [run_par] 段 RAM 副本（引擎原地更新；属主契约与 µs 级混窗见「数据可信」§4.4，
* 同 adc_cal——本层不挂回调，副本即生效值，消费侧实时读） */
typedef struct {
int32_t db[RUN_PAR_DB_N];
} run_par_db_t;
static const run_par_db_t s_db_rom = {
{ 500L, 500L, 500L, 500L, /* UA/UB/UC/UN：0.5 V（工程量重定后的额定档） */
5L, 5L, 5L, 5L, /* IA/IB/IC/IN：0.005 A */
500L } /* 频率：0.5 Hz（绝对档，非额定百分比） */
};
static run_par_db_t s_db;
/* 键表 offset 与 run_par_db_t 字段一一对应（sizeof(int32_t) 步进） */
static const cfg_key_def_t s_db_keys[] = {
{ "db_ua", CFG_VAL_INT, 0u, 4u },
{ "db_ub", CFG_VAL_INT, 4u, 4u },
{ "db_uc", CFG_VAL_INT, 8u, 4u },
{ "db_un", CFG_VAL_INT, 12u, 4u },
{ "db_ia", CFG_VAL_INT, 16u, 4u },
{ "db_ib", CFG_VAL_INT, 20u, 4u },
{ "db_ic", CFG_VAL_INT, 24u, 4u },
{ "db_in", CFG_VAL_INT, 28u, 4u },
{ "db_freq", CFG_VAL_INT, 32u, 4u }
};
/* 落盘脏标志：104 写成功置位，run_par_store_save 成功清零（B7 prot_set 同款，
* 只置不清 = 写盘失败天然重试）；单字节，跨任务 peek 无害 */
static uint8_t s_dirty;
/* 内部函数实现区 */
/*
* 函数功能：毫单位定点 → 工程量浮点（**本模块唯一换算点**）
* 入口参数：milli - 毫单位 内 int32_t
* 返 回 值：工程量 内 float
* 限定条件：仅本文件内使用（消费侧一律走 run_par_deadband()/run_par_db_range()，
* 不许各自再写一次 /1000——那才是"第二真源"最常见的样子）
*/
static float s_milli_to_eng(int32_t milli) {
return (float)milli / 1000.0f;
}
/*
* 函数功能：死区点量程上限（毫单位）
* 入口参数：idx - 0..8 uint8_t
* 返 回 值：上限；idx 越界返 0 内 int32_t
*/
static int32_t s_db_cap_milli(uint8_t idx) {
if (idx < 4u) {
return RUN_PAR_DB_MAX_U;
}
if (idx < RUN_PAR_DB_N - 1u) {
return RUN_PAR_DB_MAX_I;
}
if (idx == (uint8_t)(RUN_PAR_DB_N - 1u)) {
return RUN_PAR_DB_MAX_F;
}
return 0L;
}
/*
* 函数功能：工程量浮点 → 毫单位定点（只舍不入的截断由调用侧范围守卫兜底）
* 入口参数：v - 工程量（须已判有限） float
* 返 回 值：四舍五入最近毫单位 内 int32_t
*/
static int32_t s_milli_of(float v) {
return (int32_t)lrintf(v * 1000.0f);
}
/*
* 函数功能：死区值校验（不提交），set/104 选择段共用同一守卫 = 两路语义同源
* 入口参数：idx - 0..8 uint8_t；db - 工程量 float
* 返 回 值：合法毫单位 ≥0；-1 非法（越界/NaN/负/越程） 内 int32_t
*/
static int32_t s_db_check(uint8_t idx, float db) {
int32_t milli;
if ((idx >= RUN_PAR_DB_N) || !isfinite(db) || !(db >= 0.0f)) {
return -1L;
}
milli = s_milli_of(db);
if ((milli < 0L) || ((long long)milli > (long long)s_db_cap_milli(idx))) {
return -1L;
}
return milli;
}
/* 公共函数实现区 */
/*
* 函数功能：初始化——副本置工厂默认 + 注册 [run_par] 段（幂等，内核前）
* 返 回 值：无
*/
void run_par_init(void) {
cfg_section_reg_t reg;
(void)memcpy(&s_db, &s_db_rom, sizeof(s_db));
s_dirty = 0u;
(void)memset(&reg, 0, sizeof(reg));
reg.name = RUN_PAR_SEC;
reg.p_data = &s_db;
reg.p_defaults = &s_db_rom;
reg.data_size = sizeof(s_db);
reg.p_keys = s_db_keys;
reg.key_count = (uint8_t)(sizeof(s_db_keys) / sizeof(s_db_keys[0]));
reg.p_cb = NULL; /* 不挂回调：RAM 副本即生效值（同 adc_cal） */
if (cfg_file_register(&reg) != 0) {
DBG_ERROR("register %s FAIL (dup/full?) - file values inactive",
RUN_PAR_SEC);
}
}
/*
* 函数功能：读第 idx 路死区（工程量）
* 返 回 值：V / A / Hz；越界返 0.0（消费侧按"无死区"保守处理） float
*/
float run_par_deadband(uint8_t idx) {
if (idx >= RUN_PAR_DB_N) {
return 0.0f;
}
return s_milli_to_eng(s_db.db[idx]); /* 毫→工程：唯一换算点 = s_milli_to_eng */
}
/*
* 函数功能：取第 idx 路死区的合法域（工程量）——**合法域的唯一出口**
* 入口参数：idx - 0..8 uint8_t；lo/hi - 输出下限/上限（工程量 V/A/Hz） float *
* 返回值：0 - 已写出；-1 - idx 越界或指针为空（调用方不得回退成自造默认域） int
* 限定条件：任意上下文（纯常量读，无锁、无 I/O）
* 函数说明：为什么公开这个口：UI 整定页要给数字编辑器设 min/max，而这些上限的
* 真源是本模块的 RUN_PAR_DB_MAX_*（电压 50V / 电流 1A / 频率 5Hz，
* "额定 × 二档裕量"）。页面里抄一份就是第二真源——判据「不新增第二份
* 真源」最典型的复发形态是"顺手把常量写进界面代码"。因此本函数的
* 消费者是装配层 App/app/ui_data_feed.c 的注入表实现，不是页面本身。
* ⚠ 给的是**粗守域**（挡误写），不是工况域；真提交仍由 s_db_check
* 同源守卫裁（104 选择段与 UI 编辑器共用同一批常量，不会漂移）。
*/
int run_par_db_range(uint8_t idx, float *lo, float *hi) {
if ((idx >= RUN_PAR_DB_N) || (lo == NULL) || (hi == NULL)) {
return -1;
}
*lo = 0.0f;
*hi = s_milli_to_eng(s_db_cap_milli(idx));
return 0;
}
/*
* 函数功能：写第 idx 路死区（守卫通过才提交；成功置脏）
* 返 回 值：0 成功；-1 非法（副本不动） int
*/
int run_par_deadband_set(uint8_t idx, float db) {
int32_t milli = s_db_check(idx, db);
if (milli < 0L) {
return -1;
}
s_db.db[idx] = milli;
s_dirty = 1u;
return 0;
}
/*
* 函数功能：104 运行参数地址读（命中集精确匹配，见 run_par.h 地址表）
* 返 回 值：0 命中；-1 非本段（调用方落 prot_set） int
*/
int run_par_104_read(uint32_t addr, float *out) {
if (out == NULL) {
return -1;
}
if ((addr >= RUN_PAR_IOA_DB0) && (addr < RUN_PAR_IOA_DB0 + RUN_PAR_DB_N)) {
*out = run_par_deadband((uint8_t)(addr - RUN_PAR_IOA_DB0));
return 0;
}
if ((addr >= RUN_PAR_IOA_K0) && (addr < RUN_PAR_IOA_K0 + RUN_PAR_CH_N)) {
*out = adc_cal_k_uv((adc_semantic_t)(addr - RUN_PAR_IOA_K0));
return 0;
}
if ((addr >= RUN_PAR_IOA_B0) && (addr < RUN_PAR_IOA_B0 + RUN_PAR_CH_N)) {
*out = adc_cal_b_codes((adc_semantic_t)(addr - RUN_PAR_IOA_B0));
return 0;
}
return -1;
}
/*
* 函数功能：写某路系数 k（µV/码）**并在同一函数内置脏**——整定的语义写入口
* 入口参数：sem - 电气语义通道 adc_semantic_t；k_uv - 系数（µV/码，>0） float
* 返回值：0 - RAM 副本已写 + 已置脏；-1 - 粗守或执行段拒（副本未动、不置脏） int
* 限定条件：整定路径上下文（iec104Task 的 104 执行段；UI 经 ui_data_yt_ops_t 由
* 装配层 App/app/ui_data_feed.c 转进来）。勿在 adcTask 调用
* 函数说明：**为什么"写值 + 置脏"必须长在一个函数里**（lead 裁②，2026-10-27）：
* 置脏是持久化承诺，写值是 RAM 事实，两者拆开就会出现"屏上已改、盘上
* 永不落、且没有任何错误返回"这种无人报错的状态——本仓今天已实测到它的
* 既有形态（绕过本模块直调 adc_cal_set() 的写者不置脏，值永远不落盘，
* 另立 task-43 处置）。所以这里不提供单独的 mark_dirty 公开口：它一旦
* 存在就一定有人只调它（同"零消费者的状态查询口"那条教训）。
* 零点 b 走 RMW 取**当前生效值**（经合法带哨兵，天然满足再写校验）。
* 粗守（0 < k ≤ RUN_PAR_K_MAX_UV）只为挡误写，真带在 adc_cal 执行段裁：
* 两层各说各的，页面上"合法域内仍被拒(ERR)"就是执行段拒的，不伪装。
*/
int run_par_cal_k_set(adc_semantic_t sem, float k_uv) {
int32_t k_q16;
int32_t b_codes;
/* 通道号不在这里判：adc_cal_set 自带合法性与合法带裁决（越界一律 -1），
* 本层再判一次就是第二真源。粗守只挡误写：0 < k ≤ RUN_PAR_K_MAX_UV */
if (!isfinite(k_uv) || !(k_uv > 0.0f) || (k_uv > RUN_PAR_K_MAX_UV)) {
return -1;
}
k_q16 = (int32_t)lrintf(k_uv * 65536.0f);
b_codes = (int32_t)lrintf(adc_cal_b_codes(sem));
if (adc_cal_set(sem, k_q16, b_codes) != 0) {
return -1; /* 执行段拒：副本未动，脏位也不置 = 不承诺任何持久化 */
}
s_dirty = 1u;
return 0;
}
/*
* 函数功能：写某路零点偏移 b（码值）并置脏（与 k 同款语义，粗守 ±1e6 码）
* 入口参数：sem - 电气语义通道 adc_semantic_t；b_codes - 零点（码值） int32_t
* 返回值：0 - 已写并置脏；-1 - 粗守或执行段拒（副本未动、不置脏） int
* 限定条件：同 run_par_cal_k_set()
* 函数说明：k 侧 RMW 用当前生效值；±8192 真带由 adc_cal 执行段裁（粗守目的是
* 挡误写不是限工况）。本函数的消费者 = 104 的 0x8048~ 分支（改造后），
* 不是"为将来预留"的口
*/
int run_par_cal_b_set(adc_semantic_t sem, int32_t b_codes) {
int32_t k_q16;
if (((float)b_codes < -1.0e6f) || ((float)b_codes > 1.0e6f)) {
return -1;
}
k_q16 = (int32_t)lrintf(adc_cal_k_uv(sem) * 65536.0f);
if (adc_cal_set(sem, k_q16, b_codes) != 0) {
return -1;
}
s_dirty = 1u;
return 0;
}
/*
* 函数功能：104 运行参数地址写（两段式；k/b 经本模块语义 setter——**run_par 不存
* 系数**，系数唯一真源 = [adc_cal]/[adc_cal_ofs]，lead 裁②a）
* 返 回 值：0 接受 / -1 拒绝 / -2 非本段（调用方落 prot_set） int
* 函数说明：选择段 = 校验不提交（死区走与 set 同源守卫；k/b 的 adc_cal 合法带
* 由执行段裁决——IEC104 允许执行段 PN，两段结果可不一致，注释在此
* 明说防"选择过了怎么还 PN"的现场困惑）。k/b 两支自 2026-10-27 起一律
* 走 run_par_cal_k_set() / run_par_cal_b_set()：写值与置脏在同一个函数
* 里发生，本函数不再自己碰 s_dirty（lead 裁②：消除两份置脏逻辑）。
*/
int run_par_104_write(uint32_t addr, float v, uint8_t select) {
uint8_t slot; /* 每个命中分支先赋值再使用（无未init读路径） */
if ((addr >= RUN_PAR_IOA_DB0) && (addr < RUN_PAR_IOA_DB0 + RUN_PAR_DB_N)) {
int32_t milli;
slot = (uint8_t)(addr - RUN_PAR_IOA_DB0);
milli = s_db_check(slot, v);
if (milli < 0L) {
return -1;
}
if (select == 0u) {
s_db.db[slot] = milli;
s_dirty = 1u;
}
return 0;
}
if ((addr >= RUN_PAR_IOA_K0) && (addr < RUN_PAR_IOA_K0 + RUN_PAR_CH_N)) {
slot = (uint8_t)(addr - RUN_PAR_IOA_K0);
if (!isfinite(v) || !(v > 0.0f) || (v > 1.0e9f)) {
return -1;
}
if (select != 0u) {
return 0; /* 粗守过了 ≠ 执行必过：合法带裁决在执行段（见函数头） */
}
/* 写值 + 置脏收进语义 setter（粗守 0<k≤上限 也在里面，与本支
* 原先那条逐字同值守卫一致，行为不变）*/
return run_par_cal_k_set((adc_semantic_t)slot, v);
}
if ((addr >= RUN_PAR_IOA_B0) && (addr < RUN_PAR_IOA_B0 + RUN_PAR_CH_N)) {
slot = (uint8_t)(addr - RUN_PAR_IOA_B0);
if (!isfinite(v)) {
return -1; /* NaN/Inf 不得进 lrintf（该转换是 UB） */
}
if (select != 0u) {
return 0;
}
/* 同款语义 setter：粗守 ±1e6 码在 setter 内，±8192 真带由 adc_cal 执行段裁 */
return run_par_cal_b_set((adc_semantic_t)slot, (int32_t)lrintf(v));
}
return -2;
}
/*
* 函数功能：落盘脏探查（非消费）
* 返 回 值：1 有未落盘整定；0 干净 uint8_t
*/
uint8_t run_par_dirty_peek(void) {
return s_dirty;
}
/*
* 函数功能：执行落盘（整档外科保存成功后清脏；失败脏保持 = 下轮重试）
* 返 回 值：0 成功/无脏；-1 写盘失败 int
* 限定条件：defaultTask（配置引擎属主）上下文，SYS_EVT_RUN_PAR_SAVE 驱动
* 函数说明：一次 save 同时覆盖 [run_par] 9 键与刚被 adc_cal_set 改写的
* [adc_cal]/[adc_cal_ofs] 副本（lead 裁②：一条事件位一次 save）。
* 成功路径上给标定层盖一次落盘水位（adc_cal_note_persisted()）——它是
* **观测回执**，不参与本函数任何判定；失败路径不盖，于是"save 一直失败"
* 在标定层侧表现为差额长期不归零（道G task-43 第②项）。
*/
int run_par_store_save(void) {
if (s_dirty == 0u) {
return 0;
}
if (cfg_file_save() != 0) {
DBG_ERROR("cfg save FAIL - keep dirty, retry next round");
return -1;
}
s_dirty = 0u;
adc_cal_note_persisted(); /* 观测回执：水位追平，差额归零（不是判定输入） */
return 0;
}
App/algo/run_par.h
+199
View File
@@ -0,0 +1,199 @@
/*
* 模块名称：运行参数段（全周傅氏相量/保护判据整定层，「数据可信」这一项）
* 模块功能：遥测死区（9 点）与通道标定系数覆盖（k/b 各 8 路）的**单一真源**：
* - 死区 = 本模块 int32 毫单位 RAM 副本（注册进 cfg 引擎 [run_par] 段，
* 工厂默认 = 「数据可信」下游常数按工程量重定后的额定 0.5 % 档），104 消费侧
* （App/protocol/iec104/iec104_pts.c）每拍实时读取——无投递、无缓存
* 副本（104 改读快照曾在 pts 侧留运行时副本 s_yc_db，运行参数段落地后收编于此，
* 双源必打架）；
* - 系数覆盖 = **直通 adc_cal_set()**（[adc_cal]/[adc_cal_ofs] 是系数
* 唯一真源，标定落盘与整定入口已定；本模块只加 104 地址映射 + 落盘请求，不另存
* 一份系数——同 D1 裁"两处判断必打架"逻辑）。
* 104 地址映射（docs/算法/继电保护功能复现规划.md §5.1 运行参数类
* 0x8020H~0x8058H；逐项表原文"待补"（参考项目 CommPara_ConfigTable
* 不在仓），本表即运行参数段的落实，送检点表若另给权威地址只改常量段：
* 0x8030~0x8038 = 死区 UA/UB/UC/UN/IA/IB/IC/IN/FREQ（工程量 V/A/Hz）；
* 0x8040~0x8047 = k 覆盖（µV/码）；0x8048~0x804F = b 覆盖（码值，可负）；
* 其余留白（未启用类别），**0x8027~0x802A 属 prot_set 告警段**，本表
* 永不让位（两表按精确地址分流，见 iec104_pts.c set 路由）。
* 持久化（B7 prot_set 先例同款）：任一写成功 → 脏标志只置不清；
* iec104Task 主循环 peek → 置 SYS_EVT_RUN_PAR_SAVE → defaultTask
* （配置引擎属主）run_par_store_save() 调 cfg_file_save() 整档外科
* 保存（含 [run_par] 与刚被 adc_cal_set 改写的 [adc_cal]/[adc_cal_ofs]
* 副本）→ 成功清脏；失败留脏 = 下轮天然重试。本模块自身零文件 IO
* （属主纪律）。
* ⚠ 三份职责别混（道G task-43 第③项，此前只有意图式陈述）：
* - **谁写 RAM**：系数/零点的唯一真源是 adc_cal 的引擎副本，而本模块那两支
* 语义 setter（run_par_cal_k_set / run_par_cal_b_set，task-7 落地）是**唯一
* "写值 + 置脏"成对发生**的入口；任何消费者绕过它们直调 adc_cal_set()，
* 值只进 RAM、脏标志不动 ⇒ 屏上"当前生效"是新的、盘上仍是旧的、重启即丢，
* 且该路径**没有错误返回**。这条形态现在可观测：adc_cal 侧
* set_ok 与落盘水位的差额 > 0，而 run_par_dirty_peek() 恒为 0。
* - **谁落盘 / 什么时机**：只有 defaultTask 的 run_par_store_save()（由
* iec104Task peek 后置的 SYS_EVT_RUN_PAR_SAVE 驱动）；本模块零文件 IO。
* - **cfg_file_poll() 不是保存路径**：它的方向是**盘 → RAM 的重载**（外部
* 改档 → 沉降去抖 → 重载），拿它"兜住"未落盘的改值会把 FTP 侧的旧档倒灌
* 回 RAM，比不兜更坏。设计依据见 docs/算法/采集与算法层设计说明.md §10.1。
* 并发契约：引擎副本 int32 对齐字读写在 Cortex-M4 上原子；poll 重载 µs 级窗口
* 为「数据可信」§4.4 明载设计（adc_cal 同款）。写路径 = 104 执行段
* （iec104Task）与引擎读路径互不加锁，勿改成"读侧缓存"（缓存 = 新真源）。
* 纯算法：只用 stdint/stddef/math + cfg_file.h/adc_cal.h 头（注册/直通均为
* 接口级）→ 主机侧可单测（test/host/run_par，链真 cfg 引擎 + 真 adc_cal）。
* 适用平台：STM32F407ZGTx（Cortex-M4F，硬件 FPU）
* 作者：DTU 项目组
* 创建日期：2026-10-25（道D 运行参数段）
* 修改记录：
* v1.0 2026-10-25 DTU 项目组 创建：[run_par] 段 + 104 地址映射 + 直通
* adc_cal + B7 式脏标志落盘请求
* v1.1 2026-10-27 DTU 项目组 道F task-7（遥测整定两页）配套：新增语义
* setter run_par_cal_k_set / run_par_cal_b_set
* （写值 + 置脏成对；104 的 k/b 两支同批改调它，
* 消除两份置脏逻辑）+ 合法域唯一出口
* run_par_db_range() + 系数粗守上限
* RUN_PAR_K_MAX_UV；毫→工程换算收进模块内单点
* s_milli_to_eng()（顺带把 task-43 第①项所需的
* "写值必置脏"这一半满足掉）
* v1.2 2026-10-27 DTU 项目组 道G task-43 第②③项：run_par_store_save() 成功路径
* 给标定层盖一次落盘水位（纯观测回执，不参与判定）；
* 本头把"谁写 RAM / 谁落盘 / 什么时机 / poll 不是保存
* 路径"从意图式陈述改成逐条契约
*/
#ifndef RUN_PAR_H
#define RUN_PAR_H
#include <stdint.h>
#include "adc_cal.h" /* adc_semantic_t：公开语义 setter 的形参类型（同层 algo→algo，方向不逆）*/
#ifdef __cplusplus
extern "C" {
#endif
/* 死区/覆盖点数（死区 = YC 表行数：电气 8 + 频率；覆盖 = 语义电气 8 路） */
#define RUN_PAR_DB_N 9u
#define RUN_PAR_CH_N 8u
/* 系数 k 的**粗守**上限（µV/码）：只为挡误写（如把 mV 当 µV 填），不是工况域；
* 真合法带在 adc_cal 执行段裁（µV/码 ×[0.5,2.0]），两层各说各的、互不掩盖。
* 公开它是因为 UI 整定页要给编辑器设上限——上限在这里，就不许页面再抄一份。*/
#define RUN_PAR_K_MAX_UV 1.0e9f
/*
* 函数功能：运行参数初始化——副本置工厂默认 + 注册 [run_par] 段进 cfg 引擎
* 入口参数：无
* 返 回 值：无
* 限定条件：**内核启动前**调用（app_main_init，adc_cal_init 之后）；注册必须先
* 于 defaultTask 的 cfg_file_load（FTP 鉴权确立的契约，同 adc_cal 先例）；幂等
* 函数说明：注册失败（段名重复/段数超限）打 [ERR] 后继续——工厂默认照常生效，
* 仅文件整定失效（adc_cal_init 同款降级）。
*/
void run_par_init(void);
/*
* 函数功能：读第 idx 路遥测死区（工程量）
* 入口参数：idx - 0..7 = 语义通道序（UA..IN），8 = 频率 uint8_t
* 返 回 值：死区 V / A / Hz；idx 越界返 0.0（调用方按"无死区"保守处理） float
* 限定条件：任意上下文（int32 单字读原子；104 COV 每拍调用）
* 函数说明：毫单位 → 浮点的换算在本模块内也只有一处（run_par.c 的
* s_milli_to_eng()，run_par_deadband 与 run_par_db_range 共用）；
* 消费侧一律取本模块给的工程量，不要再各自除 1000。
*/
float run_par_deadband(uint8_t idx);
/*
* 函数功能：写第 idx 路死区（工程量，含范围守卫 + 脏置位）
* 入口参数：idx - 同上 uint8_t；db - 死区工程量（V/A/Hz，≥0） float
* 返 回 值：0 成功；-1 越界/越程/NaN（副本不动） int
* 限定条件：写者两门——**iec104Task**（104 C_SE 执行段）与 **uiTask**（遥测死区页
* 经 ui_data 通道五注入转达，道F task-7 起；ui_data.h 通道五表注：合法域
* 与"写值+置脏"必须原子发生在执行侧）。两门都只写 RAM 副本 + 置脏，
* 落盘统一收敛在 defaultTask（勿在 adcTask 调用；此句为 2026-10-27 措辞
* 收口——原写"UI 若整定需另行走属主路径"是 task-2 期遗留，task-7 已接线）
* 函数说明：合法域按点型分档——电压 0~50 V、电流 0~1 A、频率 0~5 Hz（上限 =
* 额定 × 二档裕量，守卫目的是挡误写不是限工况；见 .c 常量段）。
* 成功即置脏（落盘请求，见文件头持久化契约）。
*/
int run_par_deadband_set(uint8_t idx, float db);
/*
* 函数功能：104 运行参数地址读（C_RD 路由，先于 prot_set 扫描）
* 入口参数：addr - 通讯地址（0x8020~0x8058 段内） uint32_t；out - 工程量浮点
* （死区 V/A/Hz；k 覆盖 µV/码；b 覆盖 码值） float *
* 返 回 值：0 命中并写出；-1 地址不归本段（调用方继续走 prot_set） int
* 限定条件：iec104Task 上下文
* 函数说明：命中集 = 0x8030~0x8038 / 0x8040~0x8047 / 0x8048~0x804F 精确匹配；
* k/b 读回 = adc_cal **当前生效值**（与折算同视图：文件坏值被合法带
* 哨兵回退 ROM 时，回显的就是 ROM——主站看到的即下游实际吃到的）。
*/
int run_par_104_read(uint32_t addr, float *out);
/*
* 函数功能：104 运行参数地址写（C_SE 两段式路由，先于 prot_set 扫描）
* 入口参数：addr - 通讯地址 uint32_t；v - 工程量浮点 float；
* select - 1 = 选择段（只校验不落副本）/ 0 = 执行段 uint8_t
* 返 回 值：0 接受；-1 拒绝（越程/NaN/合法带外/非本段可写地址命中守卫）；
* -2 地址不归本段（调用方继续走 prot_set） int
* 限定条件：iec104Task 上下文；执行段成功即置脏
* 函数说明：k/b 覆盖经 adc_cal_set() 合法带哨兵（µV/码 ×[0.5,2.0]、|b|≤8192，
* 越带 -1 → 104 侧 PN 否定确认，adc_cal 不留痕由**其自身**越带 [ERR]
* 机制负责——本模块直通不重复留痕）；两段式与 prot_set 定值写同构。
*/
int run_par_104_write(uint32_t addr, float v, uint8_t select);
/*
* 函数功能：写某路系数 k（µV/码）**并在同一函数内置脏**——整定的语义写入口
* 入口参数：sem - 电气语义通道（adc_semantic_t 枚举序） adc_semantic_t；
* k_uv - 系数（µV/码，须 >0 且 <= RUN_PAR_K_MAX_UV） float
* 返回值：0 - RAM 副本已写且已置脏；-1 - 粗守或执行段拒（副本未动、不置脏） int
* 限定条件：整定路径上下文（iec104Task 的 C_SE 执行段；UI 侧由装配层
* App/app/ui_data_feed.c 经 ui_data_yt_ops_t 转进来）。勿在 adcTask 调用
* 函数说明：**写值与置脏成对，不许拆开**（lead 裁②）：拆开就等于"屏上已改、
* 盘上永不落、且没有任何错误返回"。因此本模块**不提供**公开的
* mark_dirty——单独调它等于空承诺；零点 b 由本函数 RMW 取当前生效值。
*/
int run_par_cal_k_set(adc_semantic_t sem, float k_uv);
/*
* 函数功能：写某路零点偏移 b（码值）并置脏（与 k 同款语义，粗守 ±1e6 码）
* 入口参数：sem - 电气语义通道 adc_semantic_t；b_codes - 零点（码值） int32_t
* 返回值：0 - 已写并置脏；-1 - 粗守或执行段拒（副本未动、不置脏） int
* 限定条件：同 run_par_cal_k_set()
* 函数说明：k 侧 RMW 取当前生效值；±8192 真带由 adc_cal 执行段裁。消费者 =
* 104 的 0x8048~ 分支（改造后走这里），不是为将来预留的口
*/
int run_par_cal_b_set(adc_semantic_t sem, int32_t b_codes);
/*
* 函数功能：取第 idx 路死区的合法域（工程量）——**合法域的唯一出口**
* 入口参数：idx - 0..8 uint8_t；lo/hi - 输出下限/上限（V/A/Hz） float *
* 返回值：0 - 已写出；-1 - idx 越界或指针空（调用方不得回退成自造默认域） int
* 限定条件：任意上下文（纯常量读）
* 函数说明：存在的唯一理由：UI 整定页要给编辑器设 min/max，而这些上限的真源是
* 本模块的 RUN_PAR_DB_MAX_*；页面抄一份就是第二真源。给的是**粗守域**，
* 真提交仍由与 104 选择段同源的守卫裁，两条路不会漂移到两套数字。
*/
int run_par_db_range(uint8_t idx, float *lo, float *hi);
/*
* 函数功能：落盘脏标志探查（非消费）
* 入口参数：无
* 返 回 值：1 = 有已整定未落盘的改动；0 = 干净 uint8_t
* 限定条件：任意上下文（单字节）；iec104_serv 主循环 peek 后投递事件（B7 同款）
*/
uint8_t run_par_dirty_peek(void);
/*
* 函数功能：执行落盘请求（cfg_file_save 整档外科保存 + 成功清脏）
* 入口参数：无
* 返 回 值：0 成功（或无脏可存）；-1 写盘失败（脏保持，下轮重试） int
* 限定条件：**defaultTask（配置引擎属主）上下文**，由 SYS_EVT_RUN_PAR_SAVE 驱动
* 函数说明：save 走引擎唯一写闸（超长拒写/原子改名）；本函数不清
* 引擎以外模块的脏语义（[adc_cal] 副本值已由写路径就位）。
*/
int run_par_store_save(void);
#ifdef __cplusplus
}
#endif
#endif /* RUN_PAR_H */
App/algo/sample_ring.c
+24 -10
View File
@@ -1,11 +1,11 @@
/*
* 模块名称：采样环缓冲（L2 相量计算的输入）
* 模块功能：按语义通道保存最近 2 个周波（40 点）采样值，供 L2 相量计算按窗取数。
* 模块名称：采样环缓冲（全周傅氏相量计算的输入）
* 模块功能：按语义通道保存最近 2 个周波（40 点）采样值，供 全周傅氏相量计算按窗取数。
* 适用平台：STM32F407ZGTx（纯算法，无寄存器/无 RTOS 依赖）
* 作者：王建锋
* 创建日期：2026-10-10
* 修改记录：
* v1.0 2026-10-10 王建锋 创建：L2 输入环缓冲（20 点/周波 × 2 周波）
* v1.0 2026-10-10 王建锋 创建：全周傅氏相量输入环缓冲（20 点/周波 × 2 周波）
*/
#include "sample_ring.h"
@@ -48,7 +48,7 @@ void sample_ring_init(void) {
* 入口参数：values - 按语义通道顺序排列的一帧采样值（长度须 = ADC_SEM_COUNT）
* n - 实际长度（必须等于 ADC_SEM_COUNT）
* 返 回 值：0 - 成功；-1 - 参数错
* 限定条件：同一帧内各通道须同刻（同族量同刻性由上游 L1 负责）
* 限定条件：同一帧内各通道须同刻（同族量同刻性由上游 语义取数与有效性负责）
* 函数说明：整帧写入完毕后**统一**推进写指针——单帧内不存在"半新半旧"，
* 消费侧取到的窗永远落在整帧边界上（无帧内撕裂）。
*/
@@ -73,28 +73,41 @@ int sample_ring_push_frame(const float *values, uint8_t n) {
/*
* 函数功能：取指定语义通道最近 n 点的窗（按时间序，旧 → 新）
* 入口参数：ch - 语义通道
* n - 取点数（1..SAMPLE_RING_DEPTH）
* out - 输出缓冲（长度须 >= n）
* 入口参数：ch - 语义通道（0 .. ADC_SEM_COUNT-1）
* n - 取点数（1 .. SAMPLE_RING_DEPTH）
* out - 输出缓冲（调用方保证长度 >= n，本层不校验容量）
* 返 回 值：0 - 成功；-1 - 参数错；-2 - 已累积点数不足 n
* 限定条件：无
* 函数说明：out[n-1] 为最新一点。最老点下标 = head - n（模 DEPTH）。
* 限定条件：仅 adcTask 上下文（写者与读者同任务串行，故不加锁、不用 volatile）；
* 须在同拍 sample_ring_push_frame() 之后调用。
* 函数说明：以最新一点为终点、向前回溯 n 点；out[0] 最老、out[n-1] 最新，
* 与 phasor_run() 的求和方向一致。
* 为什么需要这一层、环内布局与窗首下标的推导 →
* docs/算法/采集与算法层设计说明.md §5（本文件只留落地要点）。
*/
int sample_ring_window(adc_semantic_t ch, uint8_t n, float *out) {
uint16_t start;
uint16_t i;
/* 通道号先转 unsigned 再比：枚举底层可为有符号，负值会骗过 ch >= COUNT 的判据。 */
if ((out == NULL) || ((unsigned int)ch >= (unsigned int)ADC_SEM_COUNT)) {
return -1;
}
/* n = 0 是空窗；n > DEPTH 一个环装不下连续 n 点（回绕会把同一点重复读出）。 */
if ((n == 0u) || (n > SAMPLE_RING_DEPTH)) {
return -1;
}
/* -2 = 窗还没攒够，调用方跳过本拍即可（首周波启动期必然出现），不是故障。 */
if (s_filled < (uint16_t)n) {
return -2;
}
/* 窗首 = s_head - n（s_head 是"下一待写"位置，故窗尾 = s_head - 1）。
* 必须先加 DEPTH 再减：直接减在 s_head < n 时下溢或得负数，而
* (x mod 65536) mod 40 不等于 x mod 40、C99 的负数取模也不是同余解。
* 加 DEPTH 不改同余类，并把中间值锁在 [0, 2·DEPTH - 2]。详见设计说明 §5.3。 */
start = (uint16_t)((s_head + SAMPLE_RING_DEPTH - (uint16_t)n) % SAMPLE_RING_DEPTH);
/* 逐点取模拷贝：窗可能跨环尾，环在内存里首尾不相连，不能用一次 memcpy。 */
for (i = 0u; i < (uint16_t)n; i++) {
out[i] = s_ring[ch][(uint16_t)((start + i) % SAMPLE_RING_DEPTH)];
}
@@ -117,7 +130,8 @@ uint16_t sample_ring_filled(void) {
* 入口参数：无
* 返 回 值：累计入环帧数
* 限定条件：无
* 函数说明：供心跳日志 / 丢帧观测（L1-6 判据之一）。
* 函数说明：供心跳日志 / 丢帧观测（采样有效性校验 判据之一）。
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
*/
uint32_t sample_ring_frames(void) {
return s_frames;
App/algo/sample_ring.h
+12 -8
View File
@@ -1,16 +1,16 @@
/*
* 模块名称：采样环缓冲（L2 相量计算的输入）
* 模块功能：按**语义通道**保存最近若干周波的采样值，供 L2 相量计算按窗取数。
* V0.1 上 8 路电气量分属两片转换器（硬件缺陷 N-18），本层只做"按时序
* 存/取"，**不做任何跨通道运算**——同刻性由上游（L1）保证，本层不假设。
* 模块名称：采样环缓冲（全周傅氏相量计算的输入）
* 模块功能：按**语义通道**保存最近若干周波的采样值，供 全周傅氏相量计算按窗取数。
* V0.1 上 8 路电气量分属两片转换器（双转换器无共同采样触发），本层只做"按时序
* 存/取"，**不做任何跨通道运算**——同刻性由上游（语义取数与有效性）保证，本层不假设。
* 容量取 **2 个周波（40 点）**，与参考系统 `CN_BUFSAM_CYCLE = 2`
* （规划 §10.1）一致，为后续加长数据窗（1.5~2 周波，抗衰减直流，
* 见 `傅氏算法详解.md` §9 Q4）预留空间。
* 适用平台：STM32F407ZGTx（**纯算法**：不碰寄存器、不碰 RTOS → 可主机侧单测 L0.5）
* 适用平台：STM32F407ZGTx（**纯算法**：不碰寄存器、不碰 RTOS → 可主机侧纯逻辑单测）
* 作者：王建锋
* 创建日期：2026-10-10
* 修改记录：
* v1.0 2026-10-10 王建锋 创建：L2 输入环缓冲（20 点/周波 × 2 周波）
* v1.0 2026-10-10 王建锋 创建：全周傅氏相量输入环缓冲（20 点/周波 × 2 周波）
*/
#ifndef SAMPLE_RING_H
@@ -45,7 +45,7 @@ void sample_ring_init(void);
* 入口参数：values - 按语义通道顺序排列的一帧采样值（浮点工程量，长度须 = ADC_SEM_COUNT）
* n - 实际长度（必须等于 ADC_SEM_COUNT，否则拒收）
* 返 回 值：0 - 成功；-1 - 参数错（空指针或长度不符）
* 限定条件：调用方保证同一帧内各通道**同刻**（同族量同刻性由上游 L1 负责）
* 限定条件：调用方保证同一帧内各通道**同刻**（同族量同刻性由上游 语义取数与有效性负责）
* 函数说明：整帧一次性写入，写完统一推进写指针——单帧内不可能出现"半新半旧"，
* 即天然无帧内撕裂。消费侧读到的窗永远是**整帧**边界。
*/
@@ -59,6 +59,9 @@ int sample_ring_push_frame(const float *values, uint8_t n);
* 返 回 值：0 - 成功；-1 - 参数错；-2 - 已累积点数不足 n
* 限定条件：无
* 函数说明：out[n-1] 为最新一点。相量层以本函数取"以当前时刻为终止的一周波"。
* ⚠ 仅 adcTask 上下文调用（写者与读者同任务串行，本层不加锁）；
* 为什么需要这一层、环内布局与窗首下标的推导 →
* `docs/算法/采集与算法层设计说明.md` §5。
*/
int sample_ring_window(adc_semantic_t ch, uint8_t n, float *out);
@@ -76,7 +79,8 @@ uint16_t sample_ring_filled(void);
* 入口参数：无
* 返 回 值：累计入环帧数（32 位，1 kHz 下约 49.7 天回绕）
* 限定条件：无
* 函数说明：与 L1 的 `tpafe5160_frame_seq()` 对照可判丢帧（L1-6 采样有效性校验
* 函数说明：与 语义取数与有效性的 `tpafe5160_frame_seq()` 对照可判丢帧（采样有效性校验
*（保护功能清单见 docs/算法/继电保护功能复现规划.md）
* 的判据之一，本层只提供计数，不做判定）。
*/
uint32_t sample_ring_frames(void);
App/algo/sb_led_map.c
+58
View File
@@ -0,0 +1,58 @@
/*
* 模块名称：屏板状态灯位映射（业务状态 → LED 位掩码）
* 模块功能：sb_led_map_eval()——状态快照进、32 位 LED 掩码出。位定义与理由全在
* sb_led_map.h（映射表唯一出处），本文件只做折算。
* 适用平台：平台无关（纯标准 C）
* 作者：王建锋
* 创建日期：2026-10-29
* 修改记录：
* 2026-10-29 王建锋 创建初始版本（批 3 的 3-1）
*/
#include <stddef.h> /* NULL：纯逻辑不经 main.h，NULL 要自己带来 */
#include "sb_led_map.h"
/* NULL 输入归一用的全零快照（static const：不占 RAM，语义就是"什么都没发生"） */
static const sb_led_in_t s_in_zero = { 0UL, 0UL, 0UL, 0U, { 0U, 0U, 0U } };
/*
* 函数功能：把状态快照折算成屏板 LED 32 位掩码（契约见 sb_led_map.h）
* 入口参数：p_in - 状态快照，允许 NULL（= 全零输入，只跑心跳）
* now_ms - 毫秒时基（只用于运行灯相位）
* 返回值：32 位 LED 掩码（bit i = 灯 ID i；本函数不触碰 bit0 与 ID 6~19）
* 限定条件：任意上下文，纯函数
* 函数说明：心跳相位取 (now_ms / SB_LED_BLINK_HALF_MS) 的奇偶——用**除法取奇偶**
* 而不是"与上次比差值再翻转"，因为后者要把相位存成静态量，纯函数就没了
* （单测要能不开机就验完整个闪烁序列）。回绕只截短一个半周期，无害。
*/
uint32_t sb_led_map_eval(const sb_led_in_t *p_in, uint32_t now_ms)
{
const sb_led_in_t *q = (p_in != NULL) ? p_in : &s_in_zero;
uint32_t mask = 0UL;
/* ID 1 运行心跳：偶数个 500 ms 段 = 亮 */
if (((now_ms / SB_LED_BLINK_HALF_MS) & 1UL) == 0UL)
{
mask |= SB_LED_BIT_RUN;
}
if (q->prot_active != 0UL)
{
mask |= SB_LED_BIT_ALARM;
}
if (q->iec104_run != 0U)
{
mask |= SB_LED_BIT_COMM;
}
if (q->adc_flags != 0UL)
{
mask |= SB_LED_BIT_ADC_FAULT;
}
if (q->prot_pick != 0UL)
{
mask |= SB_LED_BIT_PICKUP;
}
return mask;
}
App/algo/sb_led_map.h
+101
View File
@@ -0,0 +1,101 @@
/*
* 模块名称：屏板状态灯位映射（业务状态 → LED 位掩码）
* 模块功能：把装置的业务状态（保护动作 / 保护启动 / 采样故障 / 104 主站在线 /
* 运行心跳）折算成屏板帧 B `info[0..3]` 的 32 位 LED 掩码。
* ⚠ 本层**纯逻辑**：不碰 HAL、不读全局、不打日志——输入是调用方
* （uiTask）采好的状态快照，输出是一个 uint32_t → 主机侧可纯逻辑单测
* （test/host/sb_led_map/）。与 Drivers/BSP/ScreenLink/sb_proto 同一分层理由。
* 适用平台：平台无关（纯标准 C）
* 作者：王建锋
* 创建日期：2026-10-29
* 修改记录：
* 2026-10-29 王建锋 创建初始版本（映射表口径见 docs/子系统设计/屏板链路设计说明.md §6）
*
* 这张表为什么必须"自定"：屏板源码（DTU-LCD LED_Printf）只规定了"位 → 灯号"的
* 物理口径（bit1~bit19 → ID 1~19，ID 0 电源灯硬件常亮、不看位，bit20~31 未使用），
* **"哪路状态占哪一位"在参考主机源码里不存在**（参考的 LCD_LED_Update 实现在
* 未开源的屏板 BSP 库里）。出处 docs/产品需求/产品需求设计文档.md §5.16.3 ①。
*/
#ifndef SB_LED_MAP_H
#define SB_LED_MAP_H
#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
/* ============================================================================
* 一、位定义（屏板物理口径：bit i = 灯 ID i；bit0 被屏板忽略，别指望用它）
* ==========================================================================*/
/* ID 1 = 运行灯：装置活着的心跳，500 ms 半周期闪烁（与主板 LED1~3 心跳节奏同源，
* docs/产品需求/产品需求设计文档.md §5.8）。它**不取决于任何输入状态**——只要这段
* 代码还在被调度，灯就在闪；灯不闪 = uiTask 停了，这正是操作员要看的信号。 */
#define SB_LED_BIT_RUN (1UL << 1)
/* ID 2 = 告警灯：任一保护元件处于**动作**态（prot_elm_active_mask != 0）。
* ⚠ 产品构建处于「未标定闭锁」（App/task/protect_task.c 的 VALID 门禁），
* 标定前恒灭——与屏上"保护动作 N"同一已知口径，不是本灯的缺陷。 */
#define SB_LED_BIT_ALARM (1UL << 2)
/* ID 3 = 通信灯：IEC 60870-5-104 链路处于 RUN（STARTDT 已确认 = 主站真的在线在
* 轮询）。选 RUN 而不选"TCP 已建连"：连上不发 STARTDT 的扫描器不该点亮它。 */
#define SB_LED_BIT_COMM (1UL << 3)
/* ID 4 = 采样故障灯：ADC 采样有效性**电平**故障位非零（adc_health_flags，
* 静默/倒退等，当前活跃、可自愈熄灭）。选电平不选 sticky：这盏灯要能熄灭，
* "曾经故障过"的账在自检记录里，不该用一盏长明灯喊给操作员。 */
#define SB_LED_BIT_ADC_FAULT (1UL << 4)
/* ID 5 = 保护启动灯：任一保护元件处于**启动**（picked）态（prot_elm_pick_mask）。
* picked 早于 asserted，"越限启动了但没到动作点"这段过程只在这盏灯上可见
* （与 104「保护启动」记录同一动机，App/algo/prot_elm.h 的 pick_mask 注释）。
* 同样受未标定闭锁口径约束。 */
#define SB_LED_BIT_PICKUP (1UL << 5)
/* 已赋义位的并集（判据用：掩码里不得出现本表之外的置位）。
* ID 6~19 保留未用，恒 0；将来扩展从 ID 6 顺序取，跳号留白不回收语义。 */
#define SB_LED_BITS_DEFINED (SB_LED_BIT_RUN | SB_LED_BIT_ALARM | SB_LED_BIT_COMM | \
SB_LED_BIT_ADC_FAULT | SB_LED_BIT_PICKUP)
/* 运行灯闪烁半周期（ms）：0 ~ SB_LED_BLINK_HALF_MS-1 亮，下一个 500 ms 灭，交替。
* 取 500 是为与主板 LED 心跳（defaultTask 500 ms 翻转）同拍，两套灯闪烁同相。 */
#define SB_LED_BLINK_HALF_MS (500U)
/* ============================================================================
* 二、状态输入快照（调用方每拍现采，本模块不缓存、不加锁）
* ==========================================================================*/
typedef struct
{
uint32_t prot_active; /* prot_elm_active_mask()：bit i = 元件 i 动作 */
uint32_t prot_pick; /* prot_elm_pick_mask()：bit i = 元件 i 启动 */
uint32_t adc_flags; /* adc_health_flags()：ADC_HF_* 电平故障位 */
uint8_t iec104_run; /* 1 = IEC 104 链路 RUN（iec104_serv_link_run()） */
uint8_t pad[3]; /* 显式补齐：结构体大小固定 16 B，主机/目标端一致 */
} sb_led_in_t;
/* ============================================================================
* 三、求值入口
* ==========================================================================*/
/*
* 函数功能：把状态快照折算成屏板 LED 32 位掩码（纯函数，映射表唯一出处见本头 §一）
* 入口参数：p_in - 状态快照；**允许 NULL**：等价于全零输入（只跑运行灯心跳——
* 心跳证明的是"这段代码活着"，与别的状态无关，不该被空输入连坐）
* now_ms - 当前毫秒时基（运行灯相位唯一依赖；osKernelGetTickCount 同域）
* 返回值：32 位 LED 掩码（bit i = 灯 ID i；bit0 与 ID 6~19 恒 0，直接进帧 B info[0..3]）
* 限定条件：任意上下文（纯计算：无分支副作用、不读写任何静态量、时基回绕安全——
* 回绕瞬间至多把一个半周期截短或延长 1 拍，500 ms 的心跳灯看不出来）
* 函数说明：闪烁相位 = (now_ms / 500) 的奇偶，偶 = 亮。上电 first 500 ms 为亮，
* "刚上电灯就在闪"是最直观的自检信号。各状态位相互独立，任一非零即置位，
* 无优先级、无互斥（告警与通信可以同时亮，那是两件同时在真发生的事）。
*/
uint32_t sb_led_map_eval(const sb_led_in_t *p_in, uint32_t now_ms);
#ifdef __cplusplus
}
#endif
#endif /* SB_LED_MAP_H */
App/algo/wave_ring.c
+535
View File
@@ -0,0 +1,535 @@
/*
* 模块名称：录波环（故障录波 · 数据面纯逻辑层：滚动环 + 触发冻结状态机 + 已封存区读口）
* 模块功能：见 App/algo/wave_ring.h 的文件头注释块——所有权矩阵、封存握手、跨任务安全、
* 形态钉死与预算全部写在那里，本文件不重抄一遍，只在实现处补「为什么这么写」。
* 本文件是纯逻辑：只 include App/algo/wave_ring.h（它带 wave_store.h），
* 不 include HAL / CMSIS / RTOS 头、不调 FatFs、不建任何 RTOS 对象、不打日志。
* 临界区也不需要：写者只有 adcTask 一个，读者只碰 SEALED 期间冻结的已封存区，
* §5.2 第一条陷阱（无临界区的活缓冲窗口）在本层根本不成立，因为没有那种入口。
* 适用平台：STM32F407ZGTx（Cortex-M4，小端）；主机侧单测 test/host/wave_ring/
* 与 test/host/wave_trig/
* 作者：DTU 项目组
* 创建日期：2026-10-29（故障录波 task-1 · 数据面纯逻辑层）
* 修改记录：
* v1.0 2026-10-29 DTU 项目组 创建
* v1.1 2026-10-29 DTU 项目组 触发挂号改单字节载荷编码（lead 评审：三段写在
* adcTask 抢占下会把段头的触发源 / 元件号录成上一段的旧值，溯源字段作废）
*/
#include "wave_ring.h"
/* ARMCC 的 stdint.h 不提供 NULL，而主机侧 gcc / MSVC 会传递性把它拉进来 ——
* 这个差别主机单测照不出来（2026-10-29 台基线实跑 /keil-build 才暴露：本层
* wave_ring.c 报 22 条 identifier "NULL" 未定义）。与 App/algo/sample_ring.c、App/algo/freq.c
* 同一口径：谁用 NULL 谁自己 include stddef.h，不往公共头里塞（少波及别人的 TU）。 */
#include <stddef.h>
/* 触发挂号的载荷编码（v1.1）：挂号量必须**一次单字节存写**才原子，所以把载荷本身编进
* 那一个字节 —— 0 = 无请求，非 0 = (触发源 << 位移) | 元件号。触发源取值 1 到 3 占高 3 位、
* 元件号取 prot_elm 的 picked 位号（uint32 位图 → 0 到 31）占低 5 位，合起来 8 位够用。
* 本层双端编译（板端 ARMCC 与模拟器），不能引 FreeRTOS / CMSIS 的临界区内在函数，
* 所以「把三个字节压成一个字节」是唯一既原子又不依赖平台的写法。 */
#define WAVE_RG_REQ_SHIFT (5u) /* 载荷里触发源的低位置 */
#define WAVE_RG_REQ_ELM_MSK (0x1Fu) /* 载荷里元件号的位掩码（低 5 位） */
#define WAVE_RG_REQ_ELM_MAX (32u) /* 元件号合法上界（不含），picked 位图只有 32 位 */
/* ===== 一、静态对象（全部文件作用域 static，禁堆分配；落位与字节数见头注第七节） ===== */
/* 数据区：按通道分列，8 列 × 320 点 × 2 字节 = 5120 字节（§7 预算的大头）。
* 不许改成 float、不许按帧交错（§12：形态错一次 RAM 翻倍 + 跨步取数）。
* 不放在 CCM：DMA 看不见它，且 .sct 里 RW_CCM 只收 heap_4.o，普通 .bss 天然落 SRAM1 */
static int16_t s_ring[WAVE_RING_CH][WAVE_RING_PTS];
/* 已封存段的段头：latch 之前只有环侧字段有效，latch 之后才是完整段头。
* 这是 defaultTask 与 uiTask 能看到的唯一「段头视图」——内部指针一律不外露 */
static wave_seg_meta_t s_sealed;
/* 观测计数（§9 周期行的 seg= / ovf= / drop= / err= 全从这里取，落盘道不数第二份账） */
static uint32_t s_seg_total; /* 成功 ACK 的段数 */
static uint32_t s_ovf_cnt; /* 被忽略的触发数 */
static uint32_t s_drop_cnt; /* SEALED 窗口丢弃的点数（单位 = 点，一次丢一拍 = 加 8） */
static uint32_t s_err_cnt; /* 落盘失败 + 滞留超时自弃 */
static uint32_t s_last_t0_ms; /* 最近一段段首毫秒 */
static uint32_t s_last_seq; /* 最近一段段首帧序号 */
/* 状态机与索引 */
static uint16_t s_head; /* 下一个写入点（滚动位置） */
static uint16_t s_base; /* 已封存 / 正在录的段首在环内的下标（段内点 0） */
static uint16_t s_post_left; /* 后触发还差多少点封段 */
static uint16_t s_cool_left; /* 冷却剩余拍数 */
static uint16_t s_seal_hold; /* SEALED 已滞留拍数 */
static uint8_t s_state; /* wave_ring_state_t */
/* 触发请求挂号：0 = 无请求；非 0 = (触发源 << WAVE_RG_REQ_SHIFT) | 元件号。
* 刻意只用这一个字节承载「是谁要录波」：旧实现分三个字节写（先写挂号位、后写载荷），
* adcTask 抢在两条指令之间就会把上一段的旧触发源 / 旧元件号抄进本段 —— 而这两个字段是
* 这段记录唯一的溯源信息（现场靠它与 /log/start.log 对表），错一次事后无从发现。
* 单字节存写在 Cortex-M4 上原子，写序不再有意义，所以不需要任何顺序假设或屏障。 */
static uint8_t s_req;
static uint8_t s_trig_src; /* 本段实际用的触发源（钉基址时从请求抄过来） */
static uint8_t s_trig_elm; /* 本段实际用的元件序号 */
static uint8_t s_meta_ready; /* 1 = 段头已 latch */
static uint8_t s_seg_idx; /* 本次上电的轮转下标（跨上电接号由落盘道自持，见头注） */
/* 语义号 → 列号（本波恒等，但把这条恒等式收在一处：二期带 TEMP 时只改这张表，
* 写死下标的调用点会静默错位，走本函数的不会） */
static const int8_t s_col_of_sem[(uint8_t)WAVE_ST_CH_MAX] = {
0, 1, 2, 3, 4, 5, 6, 7, -1
};
/* ===== 二、内部小工具 ===== */
/*
* 函数功能：环内下标 +n 后取模
* 入口参数：a_idx 当前下标；a_step 步长（小于环长）
* 返 回 值：取模后的下标 uint16_t
* 限定条件：仅本文件；a_idx 与 a_step 均在环长量级，无溢出风险
* 函数说明：环长 320 是 2 的幂吗？不是（320 = 64×5），所以老老实实取模，
* 不用位与——写错一次就是「看起来能跑、偶尔串段」的那种 bug。
*/
static uint16_t wave_rg_wrap(uint16_t a_idx, uint16_t a_step) {
uint16_t v = (uint16_t)(a_idx + a_step);
if (v >= (uint16_t)WAVE_RING_PTS) {
v = (uint16_t)(v - (uint16_t)WAVE_RING_PTS);
}
return v;
}
/*
* 函数功能：把已封存段的「环侧字段」初始化（封存瞬间调，标定字段一律清零待 latch）
* 入口参数：a_now_ms 段首毫秒；a_frame_seq 段首帧序号
* 返 回 值：无 void
* 限定条件：仅本文件；只在钉基址那一拍调一次
* 函数说明：先把 ch[] 全部清成「sem = 下标、其余 0」，是为了让**没有 latch** 的段
* 不可能带着上一段的系数被写进文件：sealed() 在未 latch 时本就是 0，
* 但清零让「万一有人绕过握手直接读 s_sealed」也读不出旧真值。
*/
static void wave_rg_seal_reset(uint32_t a_now_ms, uint32_t a_frame_seq) {
uint8_t i;
s_sealed.fs_hz = (uint16_t)WAVE_ST_FS_DEF;
s_sealed.pts_per_cycle = (uint8_t)WAVE_ST_PPC_DEF;
s_sealed.ch_count = (uint8_t)WAVE_RING_CH;
s_sealed.pts_per_ch = (uint16_t)WAVE_RING_PTS;
s_sealed.pre_pts = (uint16_t)WAVE_RING_PRE;
s_sealed.trig_src = s_trig_src;
s_sealed.trig_elm = s_trig_elm;
s_sealed.t0_ms = a_now_ms;
s_sealed.wall = 0u;
s_sealed.eng = (uint8_t)WAVE_ENG_PIN;
s_sealed.flags_seq = 0u;
s_sealed.clip_mask = 0u;
s_sealed.frame_seq = a_frame_seq;
for (i = 0u; i < (uint8_t)WAVE_ST_CH_MAX; i++) {
s_sealed.ch[i].sem = i;
s_sealed.ch[i].conv = 0u;
s_sealed.ch[i].bits = 0u;
s_sealed.ch[i].avail = 0u;
s_sealed.ch[i].k_q16 = 0;
s_sealed.ch[i].b_codes = 0;
}
}
/* ===== 三、初始化与压环 ===== */
/*
* 函数功能：复位环与全部状态
* 入口参数：无
* 返 回 值：无 void
* 限定条件：只能在 adcTask 调，且在开始压环之前（见头文件同函数注释）
* 函数说明：数据区显式清零而不是依赖 .bss 清零：本函数也可能在运行中被重新调
* （显式重配 / 单测复用），留旧数据就等于留下「上一段的尾巴混进下一段」的口子。
*/
void wave_ring_init(void) {
uint8_t c;
uint16_t i;
for (c = 0u; c < (uint8_t)WAVE_RING_CH; c++) {
for (i = 0u; i < (uint16_t)WAVE_RING_PTS; i++) {
s_ring[c][i] = 0;
}
}
s_head = 0u;
s_base = 0u;
s_post_left = 0u;
s_cool_left = 0u;
s_seal_hold = 0u;
s_state = (uint8_t)WAVE_RING_ST_IDLE;
s_req = 0u;
s_trig_src = (uint8_t)WAVE_TRIG_NONE;
s_trig_elm = 0u;
s_meta_ready = 0u;
s_seg_idx = 0u;
s_seg_total = 0u;
s_ovf_cnt = 0u;
s_drop_cnt = 0u;
s_err_cnt = 0u;
s_last_t0_ms = 0u;
s_last_seq = 0u;
wave_rg_seal_reset(0u, 0u);
}
/*
* 函数功能：压入一拍的 8 路原始码值
* 入口参数：p_codes 语义序数组（前 8 项）；a_n 必须等于 WAVE_RING_CH
* 返 回 值：WAVE_ST_OK 已写入；WAVE_ST_DONE 本拍被丢弃（SEALED 窗口）；WAVE_ST_E_PARAM 参数错 int32_t
* 限定条件：只能在 adcTask 调，每拍一次
* 函数说明：写的是「列优先」的 8 个分散地址（每列同一行）——这就是 §6.2 分列形态的代价，
* 换来的是落盘与回放都能按列连续搬，不用跨步长取数。
*/
int32_t wave_ring_push(const int16_t *p_codes, uint8_t a_n) {
uint8_t c;
if ((p_codes == NULL) || (a_n != (uint8_t)WAVE_RING_CH)) {
return WAVE_ST_E_PARAM;
}
if (s_state == (uint8_t)WAVE_RING_ST_SEALED) {
/* 冻结窗口丢样本（§4.2）：计数单位是点，一次丢一整拍 = WAVE_RING_CH 点 */
s_drop_cnt += (uint32_t)a_n;
return WAVE_ST_DONE;
}
for (c = 0u; c < (uint8_t)WAVE_RING_CH; c++) {
s_ring[c][s_head] = p_codes[c];
}
s_head = wave_rg_wrap(s_head, 1u);
return WAVE_ST_OK;
}
/* ===== 四、触发、推进、交棒、ACK ===== */
/*
* 函数功能：投递一次录波请求
* 入口参数：a_src 触发源（1 手动 / 2 保护 / 3 bench）；a_elm 元件序号（0 到 31）
* 返 回 值：WAVE_ST_OK 受理；WAVE_ST_DONE 被忽略（ovf 已加一）；WAVE_ST_E_PARAM 触发源
* 非法或元件号越界 int32_t
* 限定条件：任意上下文（**只写一个字节**，理由见 s_req 声明处）
* 函数说明：这里判「非 IDLE 就拒」而不是「非 IDLE 就排队」——本波不做多段排队（已定裁定），
* 而且排队会把「最近一次故障」降级成「上上次故障」。
* s_req 已挂号时也拒：同一拍内多个元件同时 picked 只该录一段。
* 两条入参校验排在状态判断之前：非法调用是调用方的错，不该记进 ovf 账 ——
* ovf 的语义是「真来了第二次触发」。
* 元件号上界写死在这里：今天没有调用方会越界（picked 是 uint32 位图），这条是给
* 二期加元件的人留的牙 —— 载荷只有 5 位，越界必须当场拒，不许静默截断。
*/
int32_t wave_ring_request(uint8_t a_src, uint8_t a_elm) {
if ((a_src < (uint8_t)WAVE_TRIG_MANUAL) || (a_src > (uint8_t)WAVE_TRIG_BENCH)) {
return WAVE_ST_E_PARAM;
}
if (a_elm >= (uint8_t)WAVE_RG_REQ_ELM_MAX) {
return WAVE_ST_E_PARAM;
}
if ((s_state != (uint8_t)WAVE_RING_ST_IDLE) || (s_req != 0u)) {
s_ovf_cnt++;
return WAVE_ST_DONE;
}
/* 一次存写：触发源与元件号同字节落地。别的上下文要么看到「没请求」、要么看到
* 「完整的这次请求」，不存在读到半份载荷的中间态 */
s_req = (uint8_t)(((uint32_t)a_src << (uint32_t)WAVE_RG_REQ_SHIFT) | (uint32_t)a_elm);
return WAVE_ST_OK;
}
/*
* 函数功能：推进一拍状态机
* 入口参数：a_now_ms 当前相对上电毫秒；a_frame_seq 当前帧序号
* 返 回 值：wave_ring_evt_t（本拍刚封段返回 WAVE_RING_EVT_SEALED） int32_t
* 限定条件：只能在 adcTask 调，每拍在 wave_ring_push 之后一次
* 函数说明：五个分支各管一件事，互不重叠：
* IDLE —— 消费挂号、钉段首基址、转 FREEZE
* FREEZE —— 后触发计点，计满转 SEALED
* SEALED —— 只计滞留，超时自弃（绝不让环永久焊死）
* COOL —— 递减冷却，到 0 回 IDLE
* 段首基址 = 触发那一拍写入点的「往前 160 点」，于是段内点 0 是最老的预触发点、
* 点 160 正好是触发后第一点；后触发的 160 点落在环的另一半（本来就即将被覆盖的
* 最老那 160 槽），所以「冻结」在物理上是**停止滚动覆盖**，不是停止写入。
*/
int32_t wave_ring_tick(uint32_t a_now_ms, uint32_t a_frame_seq) {
int32_t evt = (int32_t)WAVE_RING_EVT_NONE;
switch (s_state) {
case (uint8_t)WAVE_RING_ST_IDLE:
s_cool_left = 0u;
s_seal_hold = 0u;
{
/* 只读一次快照再解码：分两次读就会把两次请求的字段拼成一段的身份 */
uint8_t req = s_req;
if (req != 0u) {
/* 钉基址：本拍的样本已写进 (head-1)，段首 = head - 预触发点数 */
s_trig_src = (uint8_t)((uint32_t)req >> (uint32_t)WAVE_RG_REQ_SHIFT);
s_trig_elm = (uint8_t)((uint32_t)req & (uint32_t)WAVE_RG_REQ_ELM_MSK);
s_req = 0u;
s_base = wave_rg_wrap(s_head, (uint16_t)((uint32_t)WAVE_RING_PTS - (uint32_t)WAVE_RING_PRE));
s_post_left = (uint16_t)WAVE_RING_POST;
s_meta_ready = 0u;
s_last_t0_ms = a_now_ms;
s_last_seq = a_frame_seq;
wave_rg_seal_reset(a_now_ms, a_frame_seq);
s_state = (uint8_t)WAVE_RING_ST_FREEZE;
}
}
break;
case (uint8_t)WAVE_RING_ST_FREEZE:
if (s_post_left > 0u) {
s_post_left--;
}
if (s_post_left == 0u) {
/* 封段：此刻起 s_head 正好回到 s_base，再写就覆盖段内点 0 —— 所以 push 开始丢 */
s_state = (uint8_t)WAVE_RING_ST_SEALED;
s_seal_hold = 0u;
evt = (int32_t)WAVE_RING_EVT_SEALED;
}
break;
case (uint8_t)WAVE_RING_ST_SEALED:
/* 兜底：defaultTask 挂住 / 卷没挂载 / 落盘道被更高优先级的事挡住，都不能让环
* 永久冻结——下一次真故障无波可录是比丢一段更贵的代价（lead 裁定） */
s_seal_hold++;
if (s_seal_hold >= (uint16_t)WAVE_SEAL_TIMEOUT_MS) {
s_err_cnt++;
s_meta_ready = 0u;
s_seal_hold = 0u;
s_cool_left = (uint16_t)WAVE_RING_COOL_MS;
s_state = (uint8_t)WAVE_RING_ST_COOL;
}
break;
case (uint8_t)WAVE_RING_ST_COOL:
/* 冷却只在 ACK（或自弃）之后计时：它是二次抑制窗，不是冻结窗 */
if (s_cool_left > 0u) {
s_cool_left--;
}
if (s_cool_left == 0u) {
s_state = (uint8_t)WAVE_RING_ST_IDLE;
}
break;
default:
/* 状态字节被写坏（跑飞 / 越界写）时回到 IDLE 而不是卡死：录波宁可多录也不能停 */
s_state = (uint8_t)WAVE_RING_ST_IDLE;
break;
}
return evt;
}
/*
* 函数功能：封存交棒——把封存瞬间事实锁进段头
* 入口参数：p_cal 封存瞬间事实（不可为 NULL）
* 返 回 值：WAVE_ST_OK 已锁存；WAVE_ST_E_STATE 不在待交棒态；WAVE_ST_E_PARAM 参数错 int32_t
* 限定条件：只能在 adcTask 调，只在 EVT_SEALED 那一拍调一次
* 函数说明：只 copy 封存瞬间的事实，不动环侧字段（点数 / 采样率 / 预触发这些
* 在封段那刻已按 §6.2 定死）。重复调用直接拒，不覆盖已有锁存：
* 半路换系数会让落盘道写进去的头与它已经在搬的数据不同源。
*/
int32_t wave_ring_latch_meta(const wave_seal_cal_t *p_cal) {
uint8_t i;
if (p_cal == NULL) {
return WAVE_ST_E_PARAM;
}
if (p_cal->eng > (uint8_t)WAVE_ENG_PRI) {
return WAVE_ST_E_PARAM;
}
if ((s_state != (uint8_t)WAVE_RING_ST_SEALED) || (s_meta_ready != 0u)) {
return WAVE_ST_E_STATE;
}
s_sealed.eng = p_cal->eng;
s_sealed.flags_seq = p_cal->flags_seq;
s_sealed.clip_mask = p_cal->clip_mask;
s_sealed.wall = p_cal->wall;
for (i = 0u; i < s_sealed.ch_count; i++) {
s_sealed.ch[i].conv = p_cal->ch[i].conv;
s_sealed.ch[i].bits = p_cal->ch[i].bits;
s_sealed.ch[i].avail = p_cal->ch[i].avail;
s_sealed.ch[i].k_q16 = p_cal->ch[i].k_q16;
s_sealed.ch[i].b_codes = p_cal->ch[i].b_codes;
}
s_meta_ready = 1u;
return WAVE_ST_OK;
}
/*
* 函数功能：落盘 ACK
* 入口参数：a_result 0 = 成功；非 0 = 失败（短写 / 打开失败 / CRC 自弃）
* 返 回 值：WAVE_ST_OK 已解冻并起冷却；WAVE_ST_E_STATE 当前不在 SEALED int32_t
* 限定条件：只能由 defaultTask 调，一段一次
* 函数说明：无论成败都解冻 + 起冷却：错误只计数不冻结（环冻着的代价是下一次故障无波可录）。
* 成功才推进轮转号与段计数（失败段留同号，下次重写覆盖，不留半截文件）。
*/
int32_t wave_ring_write_done(int32_t a_result) {
if (s_state != (uint8_t)WAVE_RING_ST_SEALED) {
return WAVE_ST_E_STATE;
}
if (s_meta_ready == 0u) {
/* 没 latch 就没有「段」可 ACK：这时候段头从未就绪，落盘道根本拿不到
* wave_ring_sealed_meta()，绝不可能真写出文件。若在这里放过 ACK，
* 就会白推进轮转号（号 +1 而盘上没那个文件 = 凭空吃掉一个号）并把
* seg_total 报成一个没发生过的数（串口周期行的 seg=NN 从此对不上账）。
* 拒绝而不是记账，把「没交棒就 ACK」变成调用方看得见的错误。
* 本段的出口只有一个：滞留到 WAVE_SEAL_TIMEOUT_MS 自弃（那一路照实计 err）。 */
return WAVE_ST_E_STATE;
}
if (a_result == 0) {
s_seg_idx = wave_store_next_idx(s_seg_idx);
s_seg_total++;
} else {
s_err_cnt++;
}
s_meta_ready = 0u;
s_seal_hold = 0u;
s_cool_left = (uint16_t)WAVE_RING_COOL_MS;
s_state = (uint8_t)WAVE_RING_ST_COOL;
return WAVE_ST_OK;
}
/* ===== 五、状态查询与已封存区读口 ===== */
/*
* 函数功能：查当前状态
* 入口参数：无
* 返 回 值：wave_ring_state_t 取值 uint8_t
* 限定条件：任意上下文（只读单字节）
*/
uint8_t wave_ring_state(void) {
return s_state;
}
/*
* 函数功能：查「有已封存段可读」——跨任务唯一握手量
* 入口参数：无
* 返 回 值：1 = SEALED 且段头已 latch；0 = 不可用 uint8_t
* 限定条件：任意上下文（只读单字节）
*/
uint8_t wave_ring_sealed(void) {
if ((s_state == (uint8_t)WAVE_RING_ST_SEALED) && (s_meta_ready != 0u)) {
return 1u;
}
return 0u;
}
/*
* 函数功能：取已封存段的段头快照
* 入口参数：p_out 输出（整份拷出）
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针；WAVE_ST_E_STATE 无就绪段 int32_t
* 限定条件：任意上下文（defaultTask / uiTask 只读）
*/
int32_t wave_ring_sealed_meta(wave_seg_meta_t *p_out) {
uint16_t i;
const uint8_t *p_src;
uint8_t *p_dst;
if (p_out == NULL) {
return WAVE_ST_E_PARAM;
}
if (wave_ring_sealed() == 0u) {
return WAVE_ST_E_STATE;
}
/* 逐字节拷出而不是 *p_out = s_sealed：结构体赋值在 ARMCC 上会调 __aeabi_memcpy，
* 这里没必要为一个赋值多拉一层依赖，量也就 136 字节 */
p_src = (const uint8_t *)&s_sealed;
p_dst = (uint8_t *)p_out;
for (i = 0u; i < (uint16_t)sizeof(wave_seg_meta_t); i++) {
p_dst[i] = p_src[i];
}
return WAVE_ST_OK;
}
/*
* 函数功能：按通道读已封存区的连续点窗
* 入口参数：a_ch 列号；a_from 段内起点；a_cnt 期望点数（超出段尾自动夹）；p_dst 输出
* 返 回 值：实际点数；WAVE_ST_E_PARAM / WAVE_ST_E_RANGE / WAVE_ST_E_STATE int32_t
* 限定条件：任意上下文，只读已封存区（本层没有任何读活缓冲的入口）
* 函数说明：按 s_base 取模展开，读者看到的是 320 点的线性数组。
*/
int32_t wave_ring_read_ch(uint8_t a_ch, uint16_t a_from, uint16_t a_cnt, int16_t *p_dst) {
uint16_t left;
uint16_t n;
uint16_t idx;
uint16_t i;
if ((p_dst == NULL) || (a_cnt == 0u)) {
return WAVE_ST_E_PARAM;
}
if ((a_ch >= (uint8_t)WAVE_RING_CH) || (a_from >= (uint16_t)WAVE_RING_PTS)) {
return WAVE_ST_E_RANGE;
}
if (wave_ring_sealed() == 0u) {
return WAVE_ST_E_STATE;
}
left = (uint16_t)((uint16_t)WAVE_RING_PTS - a_from);
n = (a_cnt < left) ? a_cnt : left;
idx = wave_rg_wrap(s_base, a_from);
for (i = 0u; i < n; i++) {
p_dst[i] = s_ring[a_ch][idx];
idx = wave_rg_wrap(idx, 1u);
}
return (int32_t)n;
}
/*
* 函数功能：读口的 wave_reader_fn 形态适配（落盘道直接把它交给打包游标）
* 入口参数：p_user 未用；其余同 wave_ring_read_ch（点数与起点是 uint32 形态）
* 返 回 值：实际点数；负 = WAVE_ST_E_* int32_t
* 限定条件：任意上下文，只读已封存区
* 函数说明：32 位入参先夹到 16 位形态再转调，越界一律报错不夹成 0 ——
* 夹成 0 会让落盘道以为「这一列读完了」而写出一个短段。
*/
int32_t wave_ring_read_cb(void *p_user, uint8_t a_ch, uint32_t a_from,
uint32_t a_cnt, int16_t *p_dst) {
(void)p_user;
if (a_cnt > (uint32_t)WAVE_RING_PTS) {
return WAVE_ST_E_PARAM;
}
if (a_from > (uint32_t)WAVE_RING_PTS) {
return WAVE_ST_E_RANGE;
}
return wave_ring_read_ch(a_ch, (uint16_t)a_from, (uint16_t)a_cnt, p_dst);
}
/*
* 函数功能：取观测计数快照
* 入口参数：p_out 输出（不可为 NULL）
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针 int32_t
* 限定条件：任意上下文（只读）
*/
int32_t wave_ring_get_stat(wave_ring_stat_t *p_out) {
if (p_out == NULL) {
return WAVE_ST_E_PARAM;
}
p_out->state = s_state;
p_out->trig_src = s_trig_src;
p_out->trig_elm = s_trig_elm;
p_out->meta_ready = s_meta_ready;
p_out->seg_idx = s_seg_idx;
/* 对外字段是 8 位：本波后触发最多 160 点，不会溢出；真溢出说明环长被改过，
* 饱和在 255 让它在日志里显眼，而不是绕回 0 假装快封段了 */
p_out->post_left = (s_post_left > 255u) ? 255u : (uint8_t)s_post_left;
p_out->rsv1 = 0u;
p_out->rsv2 = 0u;
p_out->cool_left = s_cool_left;
p_out->seal_hold = s_seal_hold;
p_out->seg_total = s_seg_total;
p_out->ovf_cnt = s_ovf_cnt;
p_out->drop_cnt = s_drop_cnt;
p_out->err_cnt = s_err_cnt;
p_out->last_t0_ms = s_last_t0_ms;
p_out->last_seq = s_last_seq;
return WAVE_ST_OK;
}
/*
* 函数功能：语义通道号 → 本环列号
* 入口参数：a_sem 语义号
* 返 回 值：列号；WAVE_ST_E_RANGE = 该语义不录 int32_t
* 限定条件：任意上下文（纯计算）
*/
int32_t wave_ring_col(uint8_t a_sem) {
if (a_sem >= (uint8_t)WAVE_ST_CH_MAX) {
return WAVE_ST_E_RANGE;
}
if (s_col_of_sem[a_sem] < 0) {
return WAVE_ST_E_RANGE;
}
return (int32_t)s_col_of_sem[a_sem];
}
App/algo/wave_ring.h
+406
View File
@@ -0,0 +1,406 @@
/*
* 模块名称：录波环形缓冲层（故障录波 · 8 路 × 320 点原始码值环 + 触发冻结状态机）
* 模块功能：按拍把 8 路电气量的原始码值压进环形缓冲，在「预触发 + 后触发」窗口计满后
* 把这一段冻结成只读的已封存区，等落盘道取走并明确 ACK 之后才解冻。口径属主 =
* docs/子系统设计/故障录波设计说明.md §4.2（段长与冻结语义）、§5.1（任务所有权）、
* §5.2（三条陷阱）、§6.2 与 §6.3（段格式；本层的已封存区就是数据区的字节形态）、
* §7（预算与落位）、§12（风险表）。本文件是它的机器可执行形态；冲突以设计文档
* 为准并回报 lead，不在代码里单方面「修正」。
* 纯逻辑层纪律：不 include HAL / CMSIS / RTOS 头、不建任务、不打日志、不碰文件系统，
* 也不链 App/algo/adc_cal —— 折算档位、有效性位图、削顶位图、epoch 秒与每路
* k_q16 / b_codes 由 adcTask 在「刚封存那一拍」作为参数交棒（见 wave_ring_latch_meta
* 与下面的「封存握手顺序」），本层只负责把它们随段头一起锁存。因此本层可被
* 主机侧单测 test/host/wave_ring/ 与 test/host/wave_trig/ 原样纳入断言、零桩。
* 与 sample_ring 的关系（为什么另起一个环）：App/algo/sample_ring.c 是相量与保护的
* 上游、float 形态、深度 256，且它的 sample_ring_window() 没有临界区
* （§5.2 第一条陷阱）。录波要的是 int16 原始码值、320 点、跨任务只读，复用那个环
* 要么改它的形态与深度（动相量链），要么在跨任务读上继续裸奔 —— 两条都比另起
* 一个环贵，故本波解耦（§2.1 第 3 条结构约束）。
*
* 形态钉死（§7 预算 + §12 风险表，动这里之前先读）：
* - 元素类型 int16，不许 float：float 让环从 5120 字节变 10240 字节，直接顶穿 §7 的
* 约 5.9 KB 静态增量目标；
* - 按通道分列（一路连续 320 点），不按帧交错：回放页只画一路、PC 重算全周傅氏也逐路
* 独立，交错布局两种用法都要跨步长取数（§6.2 末段「为什么按通道分列」）；
* - 通道数固定 8，TEMP 不录：温度是片内 ADC 的 12 位单极性原始值、非线性且未参与线性
* 标定（docs/任务规划/数据可信.md §7 已定案），进录波只多占 640 字节，并让回放页多一
* 格会被误读成电气量的通道；带 TEMP 属二期，且必须连 flags_seq 与 clip_mask 一起升
* 版本（§6.2 那两行的括注）；
* - 落位 SRAM1：本层全部是普通文件级静态，链接脚本 MDK-ARM/STM32F407-Demo/
* STM32F407-Demo.sct 把 RW_IRAM1 的 .ANY (+RW +ZI) 收在 0x20000000，CCM 只收
* heap_4.o 与 .noinit → 不加任何段属性就落在 SRAM1。CCM 只剩 7904 字节没有余量，
* 而本环不是 DMA 可见对象，也没有非进 CCM 不可的理由。
*
* 封存握手顺序（唯一合法次序，写死在这里，接线道与后续改动都必须照此）：
* 1) adcTask 每拍 wave_ring_push() 然后 wave_ring_tick()；
* 2) tick 计满后触发点返回 WAVE_RING_EVT_SEALED —— 此刻状态进 WAVE_RING_ST_SEALED 但
* **尚未就绪**，wave_ring_sealed() 仍返 0；
* 3) adcTask 在**同一拍**现取封存瞬间事实（adc_cal_k_q16 / adc_cal_flags / sys_clock /
* 削顶位图）并调 wave_ring_latch_meta() 一次 —— 只在第 2 步那一拍取一次，
* 既不每拍读 adc_cal（1 kHz 下 8 路白读），也不低频刷新（低频刷新等于快照可能
* 来自标定之前的旧值，正是 §12「标定落地后老文件被解释错」的入口）；
* 4) 此后 wave_ring_sealed() 才返 1，defaultTask 才准开文件落盘；meta 未就绪时
* defaultTask 必须把本段当「不可用」处理并计 err，**不许拿半份快照落盘**；
* 5) defaultTask 搬完（成功或失败都算搬完）调 wave_ring_write_done(result) 明确 ACK；
* ACK 之前冻结一直有效、新触发一律只加 ovf；ACK 之后才起冷却抑制窗。
* 为什么必须用状态而不是用时间来挡（lead 裁定 2026-10-29）：若解冻靠计时，会出现
* 「冷却走完、adcTask 重新推进写指针，而 defaultTask 还在读那份已封存区」→
* 半新半旧的段落进文件且没有任何错误码 —— §5.2 第一条陷阱的翻版。
* 兜底：WAVE_RING_ST_SEALED 滞留超过 WAVE_SEAL_TIMEOUT_MS（写者没来取：卷未挂载、
* 落盘链卡死都算）→ 自弃本段、err 计数加一、走冷却解冻。**绝不许让录波把环永久焊死**，
* 那会让下一次真故障无波可录。
*
* 跨任务安全（§5.1 与 §5.2 第一条；本层的唯一并发契约）：
* 写者只有 adcTask，读者是 defaultTask 与 uiTask，因此只暴露「已封存」标志与已封存区
* 读口，不给任何跨任务读活缓冲的路径：
* 只能在 adcTask 调：wave_ring_init、wave_ring_push、wave_ring_tick、
* wave_ring_latch_meta；
* 只能由文件系统唯一写者 defaultTask 调：wave_ring_write_done；
* 任意上下文可调：wave_ring_request（只投一个字节，protectTask / uiTask /
* bench 都走它）、wave_ring_state、wave_ring_sealed、
* wave_ring_sealed_meta、wave_ring_read_ch、wave_ring_read_cb、
* wave_ring_get_stat、wave_ring_col。
* 为什么这样就够、不需要临界区：单字节状态量与请求量在 Cortex-M4 上单字读写天然原子；
* sealed 为 1 期间已封存区对 adcTask 是只读不写（写指针被冻在窗口之外），读者看到的数据
* 不会在脚下变；请求走「单字投递 + 下一拍由 adcTask 自己消费」，与 App/algo/prot_elm.c
* 的 prot_elm_request_reset() 同一模式。
* 「单字」是硬要求不是措辞（lead 评审 2026-10-29）：投递方是 protectTask（Normal）与
* uiTask（BelowNormal），消费者是 adcTask（AboveNormal，会**抢占**它们）。旧实现先写挂号位
* 再写触发源与元件号（三个字节、两条指令的窗口），adcTask 抢在中间就会把上一段的旧触发源
* 与旧元件号抄进本段 —— 波形没错，错的恰好是这段记录唯一的溯源字段（现场靠它与
* /log/start.log 对表），一次故障只录一段、错过事后无从发现。现在载荷本身编进那一个字节
* （0 = 无请求，非 0 = 触发源占高位 | 元件号占低 5 位），一次存写要么看不见、要么看见完整
* 一份，不需要顺序假设，也不需要任何平台相关的屏障或临界区（本层双端编译，禁止引
* FreeRTOS / CMSIS 内在函数）。
*
* 观测计数的已知容差（**不修、只入档**，lead 裁定 2026-10-29）：ovf 与 err 两个计数是跨上下文
* 的读-改-自增（ovf 由任意上下文的拒绝路径加、err 由 adcTask 的超时自弃与 defaultTask 的落盘
* 失败分别加），本层不设临界区，所以在并发拒绝 / 并发失败时理论上可能少计一次。定性成
* **观测计数的已知容差**：它们只用于趋势与判读，不作为任何判据的唯一依据 —— 要坐实「冷却期
* 内确实来了第二次触发」，同时看 armed 位与 /log/start.log 的时刻，别只盯 ovf 数字。
*
* 触发与冻结语义（§4.2，严格按此实现，别「顺手优化」）：
* IDLE →（触发）FREEZE：段首基址当拍钉死（预触发区从此不再被覆盖，后触发区继续写入），
* 后触发计满 160 点 → SEALED：整段只读，新样本一律丢弃并计 drop，等 meta latch 与落盘
* ACK → （ACK）COOL：恢复正常滚动写入，但本窗口内新触发只加 ovf 不重录 → IDLE。
* 冻结期间丢的是录波样本：sample_ring、相量、保护照常跑，本层不碰它们、也无权影响它们。
*
* 适用平台：STM32F407ZGTx（Cortex-M4，小端）；主机侧单测 test/host/wave_ring/、
* test/host/wave_trig/
* 作者：DTU 项目组
* 创建日期：2026-10-29（故障录波 task-1 · 数据面纯逻辑层）
* 修改记录：
* v1.0 2026-10-29 DTU 项目组 创建：8 路 × 320 点 int16 分列环、请求/冻结/封段/ACK/
* 冷却状态机（含 SEALED 滞留超时自弃）、段头锁存与
* 已封存区按通道读口
*/
#ifndef WAVE_RING_H
#define WAVE_RING_H
/* 本头对外只暴露 stdint 的类型；文件里出现的 NULL 全在注释内（「不可为 NULL」这类
* 约束说明），所以这里刻意不 include stddef.h —— 需要 NULL 的是包含本头的 .c，
* 它们自己 include（台基线实测：ARMCC 的 stdint.h 不带 NULL）。 */
#include <stdint.h>
#include "wave_store.h" /* 同层配对头：wave_seg_meta_t / wave_ch_desc_t / wave_reader_fn /
WAVE_ST_* 返回码（本层复用同一套 int 返回码通道，不另发明） */
#ifdef __cplusplus
extern "C" {
#endif
/* ===== 一、环几何（数值属主 = docs/子系统设计/故障录波设计说明.md §4.2 与 §7） ===== */
/* 每通道点数 = 预触发 8 周波 + 后触发 8 周波 = 160 + 160 = 320 点（1 kHz 下 320 ms） */
#define WAVE_RING_PTS (320u)
/* 预触发点数：触发点之前保留 8 周波；回放画触发光标的位点就是这个数（也是段内触发点下标） */
#define WAVE_RING_PRE (160u)
/* 后触发点数：触发点之后采满 8 周波才封段 */
#define WAVE_RING_POST (160u)
/* 通道数 = 8（TEMP 不录，理由见本文件头注）；必须与 WAVE_ST_CH_NUM 相等，单测里钉住 */
#define WAVE_RING_CH (8u)
/* 冷却抑制窗：ACK 之后这么多拍内新触发只加 ovf 不重录（§4.2「只记第一次」）。
* 500 拍 = 500 ms @1 kHz。注意：「覆盖一轮落盘窗口」这件事由 ACK 保证，本数值只是
* ACK 之后的二次抑制（防同一次故障的抖动重复触发），待台架核。 */
#define WAVE_RING_COOL_MS (500u)
/* 已封存滞留上限：SEALED 状态超过这么多拍仍没人来取（卷未挂载、落盘链卡死都算）
* → 自弃本段 + err 计数加一 + 走冷却解冻。2000 拍 = 2 s @1 kHz，待台架核。
* 判据是 tick 的推进次数（也就是 adcTask 的存活），不是墙上时间：adcTask 自己挂了
* 就轮到看门狗处理，本层不越权。 */
#define WAVE_SEAL_TIMEOUT_MS (2000u)
/* 环数据区字节数：int16 × 320 × 8 = 5120（§7 预算里最大的一项；动它等于动预算） */
#define WAVE_RING_BYTES (WAVE_RING_PTS * WAVE_RING_CH * (uint32_t)sizeof(int16_t))
/* ===== 二、类型 ===== */
/* wave_ring_tick 的事件：返回值语义是「本拍发生了什么」，不是错误 */
typedef enum {
WAVE_RING_EVT_NONE = 0, /* 正常推进，无事件 */
WAVE_RING_EVT_SEALED = 1 /* 本拍刚计满后触发：**adcTask 必须在本拍调
* wave_ring_latch_meta() 交棒封存瞬间事实**；
* 不调则本段永不就绪，最终由 WAVE_SEAL_TIMEOUT_MS
* 自弃（err 加一），可从串口周期行看到 */
} wave_ring_evt_t;
/* 环状态。迁移只发生在 wave_ring_tick 与 wave_ring_write_done 里（单写者） */
typedef enum {
WAVE_RING_ST_IDLE = 0, /* 滚动：新样本覆盖最旧点，接受触发 */
WAVE_RING_ST_FREEZE = 1, /* 已触发：段首基址已钉死（预触发区不再被覆盖），
后触发区继续写入，直到计满 WAVE_RING_POST 点 */
WAVE_RING_ST_SEALED = 2, /* 已封存：整段只读，新样本一律丢弃并计 drop；
等 meta latch、等 defaultTask 落盘并 ACK */
WAVE_RING_ST_COOL = 3 /* 冷却：已 ACK 解冻、恢复正常滚动，但新触发只加 ovf */
} wave_ring_state_t;
/* 封存瞬间必须由 adcTask 交棒的事实（本层不链 App/algo/adc_cal，全靠这份入参）。
* 段长 / 采样率 / 每周波点数 / 预触发点数 / 触发源与序号 / t0_ms / frame_seq 由本层自己填
* （环就是这些数的物理实现，让调用方填只会多一个「忘了填」的失败面）。 */
typedef struct {
uint8_t eng; /* 折算档位（wave_eng_t：0 引脚域 / 1 二次值 / 2 一次值） */
uint8_t flags_seq; /* bit s = 语义通道 s 的 ADC_CAL_F_VALID（§6.3） */
uint16_t clip_mask; /* bit s = 语义通道 s 的 ADC_CAL_F_CLIPPED（V0.1 恒 0xE6） */
uint32_t wall; /* 对时后的 epoch 秒（未对时 0；未对时就写 0，不许拿上电毫秒冒充） */
wave_ch_desc_t ch[WAVE_ST_CH_MAX]; /* 通道表前 8 项的 avail / k_q16 / b_codes：
必须取 adc_cal_k_q16() 的 int32 原值，
不许经 adc_cal_k_uv() 的 float 回算（§6.3：
float 在 5.28e7 量级掉尾数）；
conv 与 bits 也在这里给（本层无从知道两片
转换器的归属）；sem 由本层按「表内语义号 == 下标」
自己钉，传进来的 sem 被忽略 */
} wave_seal_cal_t;
/* 观测快照（给 §9 那条周期行 wave: 与主机单测；字段序 ≈ 日志序，别随手换） */
typedef struct {
uint8_t state; /* wave_ring_state_t */
uint8_t trig_src; /* 当前/最近一段的触发源（wave_trig_src_t；未触发为 0） */
uint8_t trig_elm; /* 触发元件序号（prot_elm 实例下标；手动与 bench 为 0） */
uint8_t meta_ready; /* 1 = 段头已 latch 可落盘；SEALED 期间为 0 就是「本段不可用」 */
uint8_t seg_idx; /* 下一个要写的段号 0..99（轮转号由本层持有，defaultTask 照它取名） */
uint8_t post_left; /* 后触发还差多少点封段（FREEZE 期间有意义；>255 时饱和在 255） */
uint8_t rsv1; /* 对齐补齐 */
uint8_t rsv2; /* 对齐补齐 */
uint16_t cool_left; /* 冷却剩余拍数 */
uint16_t seal_hold; /* 本段已在 SEALED 滞留多少拍（与 WAVE_SEAL_TIMEOUT_MS 对照） */
uint32_t seg_total; /* 累计成功 ACK 的段数（给日志 seg=NN 与对账） */
uint32_t ovf_cnt; /* 被丢弃的触发数：ACK 前重复触发 + 冷却期内触发（§9 ovf=） */
uint32_t drop_cnt; /* 冻结窗口丢弃的录波点数，单位 = 点不是拍（§9 drop=） */
uint32_t err_cnt; /* 落盘失败（write_done 非 0，含短写与 CRC 自弃）
+ SEALED 滞留超时自弃 的次数（§9 err=） */
uint32_t last_t0_ms; /* 最近一段段首相对上电毫秒 */
uint32_t last_seq; /* 最近一段段首帧序号（与串口周期行的 frames 对账） */
} wave_ring_stat_t;
/* ===== 三、生命周期（写者侧） ===== */
/*
* 函数功能：复位环与全部状态（清 5120 字节数据区 + 索引 + 状态机 + 观测计数 + 轮转号）
* 入口参数：无
* 返 回 值：无 void
* 限定条件：**只能在 adcTask 调**，且只能在开始压环之前调（启动期或显式重配）。
* 内核启动前调用也安全：本函数不调任何 RTOS API、不建对象，纯数组清零
* （平台约束「osKernelStart 之前禁止创建类 API」对本层不适用）
* 函数说明：观测计数（seg_total / ovf_cnt / drop_cnt / err_cnt）与轮转号一并归零：
* 重启录波就是重新起账，不留旧账，免得串口周期行的累计数与段文件对不上。
* 轮转号归零意味着**本层的 seg_idx 只是本次上电的本地计数**（供日志与首轮参考），
* 不是盘上真值：跨上电的权威下标必须由落盘道自持——启动扫目录用
* wave_store_idx_from_name 重建、每次写成功后用 wave_store_next_idx 推进。
* 若照本层归零后的 0 直接取名，重启后第一笔覆盖的就是上次上电的**最新**段，
* 与轮转「新证据优先」的初衷正相反（§6.2 轮转语义）。
*/
void wave_ring_init(void);
/*
* 函数功能：压入一拍的 8 路原始码值（数据面的唯一写入路径）
* 入口参数：p_codes 8 路码值数组，顺序 = adc_semantic_t 的前 8 项
* （UA UB UC UN IA IB IC IN，即语义号升序，与段文件通道表列序
* 同一口径，§6.3）
* a_n 数组长度，必须等于 WAVE_RING_CH
* 返 回 值：WAVE_ST_OK = 已写入；WAVE_ST_DONE = 本拍样本被丢弃（SEALED 窗口，drop 已加一）；
* WAVE_ST_E_PARAM = 空指针或长度不对 int32_t
* 限定条件：**只能在 adcTask 调**，每拍一次（1 kHz）；不得从其它任务或 ISR 调。
* 尤其禁止图省事挂在 Src/freertos.c 的 TIM3 回调里（adc_tick_irq_notify()
* 旁边）：那是 ISR 上下文，且 ISR 比调度器早约 100 ms 启动
* （docs/子系统设计/看门狗设计说明.md §10.1），本层没有「消费者就绪」门，
* 挂上去就是拿 ISR 改状态机。
* 函数说明：IDLE、FREEZE、COOL 三态都写入；SEALED 一律丢弃并计数 —— 这就是 §4.2
* 「冻结期间丢的是录波样本」，不是丢采样链路：sample_ring、相量、保护照常被
* adcTask 喂，本层无权也不该影响它们。
* 码值是转换器原始输出：TPAFE 为 16 位补码双极性、片内 ADC 为 0..4095 原样
* 正数，**不做中点偏置、不做折算**（§6.3「样本编码」行：加偏置等于伪造双极性）。
*/
int32_t wave_ring_push(const int16_t *p_codes, uint8_t a_n);
/* ===== 四、触发请求、每拍推进、封存交棒、落盘 ACK ===== */
/*
* 函数功能：投递一次录波请求（单字投递，不碰环、不碰索引）
* 入口参数：a_src 触发源（wave_trig_src_t 的 1 / 2 / 3；0 与其它值按参数错拒绝）
* a_elm 触发元件序号（prot_elm 的 picked 位号，**必须小于 32**；
* 手动与 bench 定时传 0。越界当场拒，不许静默截断 —— 载荷只有 5 位）
* 返 回 值：WAVE_ST_OK = 已受理（下一拍由 adcTask 自己钉段首基址）；
* WAVE_ST_DONE = 被忽略（处于 FREEZE 或 SEALED 或 COOL，或请求还没被消费；
* ovf 计数已加一，§9 的 ovf=）；
* WAVE_ST_E_PARAM = 触发源非法或元件号越界（参数错**不记 ovf 账**） int32_t
* 限定条件：**任意上下文可调**（protectTask 的 picked 上升沿、uiTask 的手动确认、
* bench 定周期、adcTask 自己），它只写**一个字节**（载荷编码见文件头
* 「跨任务安全」段），与 App/algo/prot_elm.c 的 prot_elm_request_reset()
* 同一模式（§5.1）
* 函数说明：本函数不产生「立刻冻结」的效果 —— 段首基址由 adcTask 在下一拍
* wave_ring_tick 里钉，避免跨上下文改环索引。最坏延迟一拍 = 1 ms，
* 相对 160 点的预触发窗可以忽略。
* **ACK 前一律只加 ovf**（lead 裁定）：SEALED 期间再来触发不重录、不排队，
* 本波不做多段排队。
* **返回 WAVE_ST_E_PARAM 的两条路径不触碰任何计数**（ovf / err / drop 一个都不加，
* 也不留挂号）：那是调用方传错参数，与「第二次真触发」是两回事。台架不得拿 ovf
* 当「谁误用了接口」的证据——误用只在返回值里体现（lead 裁定 2026-10-29）。
*/
int32_t wave_ring_request(uint8_t a_src, uint8_t a_elm);
/*
* 函数功能：推进一拍状态机（消费请求钉基址、计后触发点数、到点进 SEALED、
* 冷却递减、SEALED 滞留超时自弃）
* 入口参数：a_now_ms 当前相对上电毫秒（填段头 t0_ms；用 adcTask 已有的时基即可）
* a_frame_seq 当前帧序号（填段头 frame_seq，与串口周期行的 frames 对账）
* 返 回 值：wave_ring_evt_t（WAVE_RING_EVT_NONE / WAVE_RING_EVT_SEALED） int32_t
* 限定条件：**只能在 adcTask 调**，且每拍在 wave_ring_push 之后调一次
* （先写样本再算点数，后触发才正好 160 个点）
* 函数说明：FREEZE 期间写入行为与滚动无异，只是段首基址已钉死、预触发区不再被覆盖
* —— 这就是 §4.2「触发即冻结写指针」的准确含义：冻住的是覆盖窗口，
* 不是停止采集。计满 WAVE_RING_POST 点的本拍返回 WAVE_RING_EVT_SEALED。
* SEALED 期间本函数只做「滞留计时 + 超时自弃」，不动数据、不动基址。
*/
int32_t wave_ring_tick(uint32_t a_now_ms, uint32_t a_frame_seq);
/*
* 函数功能：封存交棒 —— 把「环已知字段 + adcTask 现取的封存瞬间事实」拼成完整段头并锁存
* 入口参数：p_cal 封存瞬间事实（折算档位 / 有效性位图 / 削顶位图 / epoch 秒 / 通道表的
* conv、bits、avail、k_q16、b_codes；不可为 NULL）
* 返 回 值：WAVE_ST_OK = 已锁存，wave_ring_sealed() 从此为 1；
* WAVE_ST_E_STATE = 不在「刚封段待交棒」态（含已 latch 过第二次、非 SEALED）；
* WAVE_ST_E_PARAM = 空指针或折算档位非法 int32_t
* 限定条件：**只能在 adcTask 调**，且只在 wave_ring_tick 返回 WAVE_RING_EVT_SEALED 的
* 那一拍调一次（重复调返回 WAVE_ST_E_STATE 且不覆盖已有锁存值 —— 半路覆盖
* 会让落盘道读到的头与数据不同源）
* 函数说明：为什么系数要调用方传、而不让本层自己读 adc_cal —— 本层要能被主机单测零桩
* 纳入；更根本的是 §12 的要求：标定一旦落地，老文件必须还能按**当时**的系数
* 解释，所以 eng / k / b / clip 属于段头、不属于当前固件状态。
* 取值只能在第 3 步那一拍做一次（不每拍读、不低频刷），理由见本文件头注。
*/
int32_t wave_ring_latch_meta(const wave_seal_cal_t *p_cal);
/*
* 函数功能：落盘 ACK —— defaultTask 明确告知本段已搬完（成功或失败），据此解冻并起冷却
* 入口参数：a_result 0 = 落盘成功（打开、写入字节数相符、目录可用）；
* 非 0 = 失败（含 f_write 短写、打开/建目录失败、CRC 自弃）——
* 失败时段已丢，但环必须解冻，错误只计数不冻结
* 返 回 值：WAVE_ST_OK = 已 ACK 并转入冷却；WAVE_ST_E_STATE = 当前不在 SEALED
* （重复 ACK 或没有段可 ACK —— 不静默改状态，防落盘道把上一段的 ACK 打到新段），
* 或段头还没 latch（第 3 步没做）：这时候落盘道拿不到 sealed_meta，根本没可能
* 写出文件，放过 ACK 等于白吃一个轮转号并把 seg=NN 报成没发生过的数，
* 故一律拒绝。这种段唯一的出口是滞留到 WAVE_SEAL_TIMEOUT_MS 自弃并计 err int32_t
* 限定条件：**只能由文件系统唯一写者 defaultTask 调**，一段一次，调之前先看
* wave_ring_sealed()（它就是「SEALED 且已 latch」的合并判据）
* 函数说明：失败不推进轮转号（下一段仍用同号重写，同号文件按 FA_CREATE_ALWAYS 截断，
* 不留半截文件骗过 PC 脚本）；成功才推进 seg_idx 与 seg_total。
* 本函数不删文件、不碰 FatFs：那些都在落盘道（§5.1 所有权）。
*/
int32_t wave_ring_write_done(int32_t a_result);
/* ===== 五、状态查询与已封存区读口（跨任务安全的唯一入口） ===== */
/*
* 函数功能：查当前状态
* 入口参数：无
* 返 回 值：wave_ring_state_t 的取值 uint8_t
* 限定条件：任意上下文（只读单字节）
*/
uint8_t wave_ring_state(void);
/*
* 函数功能：查「有已封存段可读」标志 —— 跨任务的唯一握手量（§5.2 第一条陷阱）
* 入口参数：无
* 返 回 值：1 = 状态为 SEALED **且段头已 latch**，此刻起 wave_ring_sealed_meta 与
* wave_ring_read_ch 可用；0 = 不可用 uint8_t
* 限定条件：任意上下文（只读单字节）
* 函数说明：为什么把「已 latch」并进来而不是单开一个查询：省得 defaultTask 自己
* 拼两个标志、拼错就是拿半份快照落盘（第 4 步明写的禁忌）。
* 为 1 期间已封存区对 adcTask 只读不写，读者可以慢慢分次取、不需要临界区；
* 为 0 时所有读口一律返 WAVE_ST_E_STATE 而**不是返回旧数据** ——
* 把上一段的字节当这一段，等于伪造证据。
*/
uint8_t wave_ring_sealed(void);
/*
* 函数功能：取已封存段的段头快照（落盘道编头、回放页画标题都用它）
* 入口参数：p_out 输出（整份拷出，约 136 字节；不可为 NULL）
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针；WAVE_ST_E_STATE 无就绪段 int32_t
* 限定条件：任意上下文（defaultTask / uiTask 只读）。整份拷贝、不暴露内部指针，
* 免得调用方攥着指针跨到下一段去看
* 函数说明：这里的 fs_hz / pts_per_cycle / pre_pts 是**数据**，回放页与 PC 脚本必须
* 从这里读，不许当编译期常量（§2.1 第 1 条）。
*/
int32_t wave_ring_sealed_meta(wave_seg_meta_t *p_out);
/*
* 函数功能：按通道读已封存区的连续点窗（回放页画一路、落盘道搬一路都走它）
* 入口参数：a_ch 列号 = 通道表下标 = 语义号（0 到 WAVE_RING_CH-1）
* a_from 段内起始点下标（0 = 段首 = 最早的一点。点序口径：触发那一拍的
* 样本落在点 WAVE_RING_PRE-1（预触发窗的最后一点），段内点
* WAVE_RING_PRE 起是触发之后的第一拍——预触发 8 周波与后触发
* 8 周波各 160 点，故障时刻正好是两半的分界（§4.2）
* a_cnt 点数（1 起；超出段尾时函数内部夹到剩余点数，不报错）
* p_dst 输出 int16 数组（不可为 NULL；画窗 40 点或搬运 128 点按调用方给的容量）
* 返 回 值：不小于 0 = 实际读出的点数（到段尾会少于 a_cnt）；
* WAVE_ST_E_PARAM 空指针或 a_cnt 为 0；WAVE_ST_E_RANGE 列号或起始点越界；
* WAVE_ST_E_STATE 无就绪段 int32_t
* 限定条件：任意上下文，但**只读已封存区**：本层不提供任何读活缓冲的接口，
* IDLE / FREEZE / COOL 下一律 WAVE_ST_E_STATE（§5.2 第一条：不给跨任务读活环的路径）
* 函数说明：内部按段首基址取模展开，对读者来说已封存区就是一段 320 点的线性数组。
* 回放页画 2 周波 = 40 点（§8.1）一次调用即可；字节形态 = 段文件数据区的
* 字节形态（int16 小端），所以落盘道能直接把它交给 wave_store 的打包游标。
*/
int32_t wave_ring_read_ch(uint8_t a_ch, uint16_t a_from, uint16_t a_cnt, int16_t *p_dst);
/*
* 函数功能：同上，形态适配 App/algo/wave_store.h 的 wave_reader_fn（落盘道直接传它）
* 入口参数：p_user 上下文（本层是单例，忽略，传 NULL 即可）
* a_ch 列号
* a_from 段内起始点下标
* a_cnt 点数
* p_dst 输出 int16 数组
* 返 回 值：实际读出的点数（不小于 0）；负 = WAVE_ST_E_*（同上三条） int32_t
* 限定条件：任意上下文；只读已封存区（同上）
* 函数说明：存在的唯一理由是让 wave_store_pack_start 的 p_reader 直接指过来，
* 省掉接线索里一个只为转发的包装函数。
*/
int32_t wave_ring_read_cb(void *p_user, uint8_t a_ch, uint32_t a_from,
uint32_t a_cnt, int16_t *p_dst);
/*
* 函数功能：取观测计数快照（给 §9 的周期行与主机单测）
* 入口参数：p_out 输出（不可为 NULL）
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针 int32_t
* 限定条件：任意上下文（只读；一次拷约 44 字节，个别字段可能与 adcTask 的推进错开一拍，
* 这是观测量的固有精度，不构成判据错误）
* 函数说明：err_cnt 的两条来源都在本层收口（write_done 非 0、SEALED 滞留超时自弃），
* 所以 §9 日志行的 err= 直接取它即可 —— 落盘道不需要自己数第二份账。
*/
int32_t wave_ring_get_stat(wave_ring_stat_t *p_out);
/*
* 函数功能：把「语义通道号」换算成本环的列号（列序 = 语义号升序，§6.3）
* 入口参数：a_sem 语义号（adc_semantic_t 值）
* 返 回 值：0 到 WAVE_RING_CH-1 = 列号；WAVE_ST_E_RANGE = 该语义不录（TEMP 与越界值） int32_t
* 限定条件：任意上下文（纯计算）
* 函数说明：本波只录前 8 个语义通道，所以「列号 == 语义号」这条恒等式成立；
* 但调用方必须走这个函数而不是自己写死下标 —— 二期带 TEMP 时列号与语义号
* 就会分叉，写死下标的地方会静默错位。
*/
int32_t wave_ring_col(uint8_t a_sem);
#ifdef __cplusplus
}
#endif
#endif /* WAVE_RING_H */
App/algo/wave_store.c
+981
View File
@@ -0,0 +1,981 @@
/*
* 模块名称：录波段格式层实现（故障录波 · 段文件字节布局编解码 + 打包游标 + 段名轮转）
* 模块功能：见 App/algo/wave_store.h 的文件头注释块——口径属主、职责边界、跨任务安全、
* 二期不返工的约束全部写在那里，本文件不重复一遍。
* 本文件是纯逻辑：只 include App/algo/wave_store.h 与 C 标准库的 stdint/stddef，
* 不 include HAL / CMSIS / RTOS 头、不调 FatFs、不碰文件系统、不打日志。
* 适用平台：STM32F407ZGTx（Cortex-M4，小端）；主机侧单测 test/host/wave_store/
* 作者：DTU 项目组
* 创建日期：2026-10-29（故障录波 task-1 · 数据面纯逻辑层）
* 修改记录：
* v1.0 2026-10-29 DTU 项目组 创建
*/
#include "wave_store.h"
/* ARMCC 的 stdint.h 不提供 NULL，而主机侧 gcc / MSVC 会传递性把它拉进来 ——
* 这个差别主机单测照不出来（2026-10-29 台基线实跑 /keil-build 才暴露：本层
* wave_store.c 报 22 条 identifier "NULL" 未定义）。与 App/algo/sample_ring.c、App/algo/freq.c
* 同一口径：谁用 NULL 谁自己 include stddef.h，不往公共头里塞（少波及别人的 TU）。 */
#include <stddef.h>
/* 打包游标一次最多从数据源取多少个点（128 字节栈上临时区，落盘道在 defaultTask 上跑，
* 不在 1 kHz 采集链上；取批是为了把「每点一次回调」压成「每 64 点一次回调」） */
#define WAVE_ST_BATCH (64u)
/* 数据区点下标非法时的内部哨兵（对外一律走 wave_store_data_off 的 0xFFFFFFFFu） */
#define WAVE_ST_BAD_OFF (0xFFFFFFFFu)
/* ===== 内部：小端读写（显式移位拼装，不依赖宿主字节序，板端与 PC 侧同一判据） ===== */
/*
* 函数功能：写 16 位小端
* 入口参数：p 目标位置（至少 2 字节）；v 值
* 返 回 值：无 void
* 限定条件：调用方保证 p 可写 2 字节
*/
static void wave_st_put16(uint8_t *p, uint16_t v) {
p[0] = (uint8_t)(v & 0xFFu);
p[1] = (uint8_t)((v >> 8) & 0xFFu);
}
/*
* 函数功能：写 32 位小端
* 入口参数：p 目标位置（至少 4 字节）；v 值
* 返 回 值：无 void
* 限定条件：调用方保证 p 可写 4 字节
*/
static void wave_st_put32(uint8_t *p, uint32_t v) {
p[0] = (uint8_t)(v & 0xFFu);
p[1] = (uint8_t)((v >> 8) & 0xFFu);
p[2] = (uint8_t)((v >> 16) & 0xFFu);
p[3] = (uint8_t)((v >> 24) & 0xFFu);
}
/*
* 函数功能：读 16 位小端
* 入口参数：p 源位置（至少 2 字节）
* 返 回 值：值 uint16_t
* 限定条件：调用方保证 p 可读 2 字节
*/
static uint16_t wave_st_get16(const uint8_t *p) {
return (uint16_t)((uint16_t)p[0] | ((uint16_t)p[1] << 8));
}
/*
* 函数功能：读 32 位小端
* 入口参数：p 源位置（至少 4 字节）
* 返 回 值：值 uint32_t
* 限定条件：调用方保证 p 可读 4 字节
*/
static uint32_t wave_st_get32(const uint8_t *p) {
return ((uint32_t)p[0]) | (((uint32_t)p[1]) << 8) |
(((uint32_t)p[2]) << 16) | (((uint32_t)p[3]) << 24);
}
/*
* 函数功能：把 int16 写成小端两字节
* 入口参数：p 目标位置；v 码值
* 返 回 值：无 void
* 限定条件：调用方保证 p 可写 2 字节
* 函数说明：先转 uint16 再移位——负数右移是实现定义行为，转成无符号后行为确定。
*/
static void wave_st_put_code(uint8_t *p, int16_t v) {
wave_st_put16(p, (uint16_t)v);
}
/* ===== 内部：段头字段一致性自检（编码前与解码后各跑一次，同一把尺子） ===== */
/*
* 函数功能：校验段头元数据的**几何与表序**是否自相矛盾
* 入口参数：p_meta 段头元数据（非空）
* 返 回 值：WAVE_ST_OK = 合法；WAVE_ST_E_SIZE 长度类不成立（零通道 / 零点数 / 预触发超段长）；
* WAVE_ST_E_FORMAT 档位 / 触发源 / 表序非法 int
* 限定条件：p_meta 由调用方保证非空
* 函数说明：为什么编码侧也要跑：写一个「看起来像样的坏段文件」比拒写糟得多——落盘道会
* 把 CRC 与长度都算自洽的垃圾写进 NAND，等到回放页或 PC 脚本才发现，那时
* 现场已经没了（§8.1「画成一条直线等于伪造证据」是同一条忌讳的另一半）。
*/
static int wave_st_meta_check(const wave_seg_meta_t *p_meta) {
uint8_t i;
/* 零通道 / 零点数：这一段连长度都不成立（§6.2 末行「长度为 0 判废」） */
if ((p_meta->ch_count == 0u) || (p_meta->ch_count > (uint8_t)WAVE_ST_CH_MAX)) {
return WAVE_ST_E_SIZE;
}
if (p_meta->pts_per_ch == 0u) {
return WAVE_ST_E_SIZE;
}
/* 预触发点数不能大于一段的点数；后触发 = pts_per_ch - pre_pts，允许为 0（手动触发
* 撞上落盘窗口等极端情形），但不允许负数——那是把段长算错 */
if (p_meta->pre_pts > p_meta->pts_per_ch) {
return WAVE_ST_E_SIZE;
}
/* 采样率与每周波点数是数据，但为 0 的数据没法解释（回放与 PC 都要拿它做除数） */
if ((p_meta->fs_hz == 0u) || (p_meta->pts_per_cycle == 0u)) {
return WAVE_ST_E_SIZE;
}
/* 与 PC 侧 reader 的拒绝清单对齐（谁都不能产出一段「自己写得出、对面读不了」的文件）：
* 每周波不足 2 点连一个周期都描不出来；段长不足一个整周期则基波算法无从取窗。 */
if (p_meta->pts_per_cycle < 2u) {
return WAVE_ST_E_SIZE;
}
if (p_meta->pts_per_ch < (uint32_t)p_meta->pts_per_cycle) {
return WAVE_ST_E_SIZE;
}
if (p_meta->eng > (uint8_t)WAVE_ENG_PRI) {
return WAVE_ST_E_FORMAT;
}
if (p_meta->trig_src > (uint8_t)WAVE_TRIG_BENCH) {
return WAVE_ST_E_FORMAT;
}
/* 表序：第 i 项的语义号必须等于下标（§6.3「通道表序与列序」行）——
* 数据区第 i 列归第 i 项解释，错一位就是拿 IB 的波形配 IC 的系数 */
for (i = 0u; i < p_meta->ch_count; i++) {
if (p_meta->ch[i].sem != i) {
return WAVE_ST_E_FORMAT;
}
if (p_meta->ch[i].conv > (uint8_t)1u) {
return WAVE_ST_E_FORMAT;
}
/* 位宽留个合理域：本波只有 16（TPAFE）与 12（片内 ADC），但格式层不写死这两个值，
* 只挡明显不成立的（0 位、超过 32 位）——二期换转换器不必改这里 */
if ((p_meta->ch[i].bits == 0u) || (p_meta->ch[i].bits > 32u)) {
return WAVE_ST_E_FORMAT;
}
}
return WAVE_ST_OK;
}
/* ===== CRC-16/MODBUS ===== */
/*
* 函数功能：CRC-16/MODBUS 增量计算
* 入口参数：a_crc 上一次的中间值（首次传 WAVE_ST_CRC_INIT）
* p_data 数据（NULL 视为空操作）
* a_len 字节数
* 返 回 值：新的中间值 uint16_t
* 限定条件：任意上下文；纯计算
* 函数说明：反射形态 = 右移、异或 0xA001、初值 0xFFFF、异或输出 0；
* 写进文件时低字节在前（§6.3）。无表实现的理由见 wave_store.h 头注。
*/
uint16_t wave_store_crc_update(uint16_t a_crc, const uint8_t *p_data, uint32_t a_len) {
uint16_t crc = a_crc;
uint32_t i;
if (p_data == NULL) {
return crc;
}
for (i = 0u; i < a_len; i++) {
uint8_t b = p_data[i]; /* 身兼两职：本路字节 + 下面内层 8 次的计数器 */
crc = (uint16_t)(crc ^ (uint16_t)b);
for (b = 0u; b < 8u; b++) {
if ((crc & 0x0001u) != 0u) {
crc = (uint16_t)((crc >> 1) ^ WAVE_ST_CRC_POLY);
} else {
crc = (uint16_t)(crc >> 1);
}
}
}
/* 异或输出恒 0：写成宏引用，换异或输出时只改一处 */
return (uint16_t)(crc ^ WAVE_ST_CRC_XOROUT);
}
/*
* 函数功能：CRC-16/MODBUS 一次算完
* 入口参数：p_data 数据；a_len 字节数
* 返 回 值：CRC；空输入返回初值定义 uint16_t
* 限定条件：任意上下文。零长度的判废由调用方做（见 wave_store.h 同函数注释）
*/
uint16_t wave_store_crc(const uint8_t *p_data, uint32_t a_len) {
return wave_store_crc_update(WAVE_ST_CRC_INIT, p_data, a_len);
}
/*
* 函数功能：CRC 实现自检（对规范锚点，不是自算自验）
* 入口参数：无
* 返 回 值：WAVE_ST_OK 相符；WAVE_ST_E_FORMAT 不符 int
* 限定条件：任意上下文；开机或首次落盘前一次，不在每拍路径上
* 函数说明：锚点串「123456789」的 CRC-16/MODBUS = 0x4B37（§6.3）。字面量必须纯 ASCII，
* 所以这里用显式字节数组而不是把中文塞进字符串。
*/
int wave_store_crc_selftest(void) {
static const uint8_t s_anchor[9] = {
(uint8_t)0x31u, (uint8_t)0x32u, (uint8_t)0x33u,
(uint8_t)0x34u, (uint8_t)0x35u, (uint8_t)0x36u,
(uint8_t)0x37u, (uint8_t)0x38u, (uint8_t)0x39u
};
uint16_t got;
got = wave_store_crc(s_anchor, (uint32_t)sizeof(s_anchor));
if (got != WAVE_ST_CRC_CHECK) {
return WAVE_ST_E_FORMAT;
}
return WAVE_ST_OK;
}
/* ===== 段头编解码 ===== */
/* 语义通道的转换器归属与位宽（0 = TPAFE5160，1 = 片内 ADC1；口径属主是
* docs/硬件平台/ADC通道映射说明.md，本表是其抄本，改硬件接线时两处一起改）。
* 第 9 项 TEMP 本波不录入段文件（ch_count 恒 8），仍按实际归属填，
* 免得将来放开 TEMP 时这里是个 0。 */
static const uint8_t s_sem_conv[(uint8_t)WAVE_ST_CH_MAX] = {
(uint8_t)0u, (uint8_t)1u, (uint8_t)1u,
(uint8_t)0u, (uint8_t)0u, (uint8_t)1u, (uint8_t)1u, (uint8_t)1u, (uint8_t)1u
};
static const uint8_t s_sem_bits[(uint8_t)WAVE_ST_CH_MAX] = {
16u, 12u, 12u,
16u, 16u, 12u, 12u, 12u, 12u
};
/*
* 函数功能：把段头元数据填成本波默认值（只填格式侧静态事实）
* 入口参数：p_meta 输出
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针 int
* 限定条件：任意上下文
* 函数说明：填三样格式侧的静态事实：语义号 = 下标（§6.3 表序口径，也是 PC 侧判据）、
* conv / bits 按两片转换器的归属（下面那张表的口径属主是
* docs/硬件平台/ADC通道映射说明.md 的抄本，本层刻意不带 adc_input.h，
* 这样格式层在主机侧不需要任何假件就能编译；单测里 0xE6 的算术交叉验证
* 会同时钉住这套顺序，抄错就会红）。
* 不填 avail / k_q16 / b_codes：那些是封存瞬间的事实，必须由调用方现取现填
* （adc_cal_k_q16 / adc_cal_flags / sys_clock），本层不链它们；
* 调用方忘填 k_q16 与 avail 不会让编码失败（0 是合法整数），
* 但会让 PC 侧把波形解释成一条 0 线——所以单测里有一条专门检查
* 「填了系数的往返」与「没填系数时段的形状仍然正确、只是幅值归零」。
*/
int wave_store_meta_init(wave_seg_meta_t *p_meta) {
uint8_t i;
if (p_meta == NULL) {
return WAVE_ST_E_PARAM;
}
p_meta->fs_hz = (uint16_t)WAVE_ST_FS_DEF;
p_meta->pts_per_cycle = (uint8_t)WAVE_ST_PPC_DEF;
p_meta->ch_count = (uint8_t)WAVE_ST_CH_NUM;
p_meta->pts_per_ch = (uint16_t)WAVE_ST_PTS_DEF;
p_meta->pre_pts = (uint16_t)WAVE_ST_PRE_DEF;
p_meta->trig_src = (uint8_t)WAVE_TRIG_NONE;
p_meta->trig_elm = 0u;
p_meta->t0_ms = 0u;
p_meta->wall = 0u;
p_meta->eng = (uint8_t)WAVE_ENG_PIN;
p_meta->flags_seq = 0u;
p_meta->clip_mask = 0u;
p_meta->frame_seq = 0u;
for (i = 0u; i < (uint8_t)WAVE_ST_CH_MAX; i++) {
p_meta->ch[i].sem = i;
p_meta->ch[i].conv = s_sem_conv[i];
p_meta->ch[i].bits = s_sem_bits[i];
p_meta->ch[i].avail = 0u;
p_meta->ch[i].k_q16 = 0;
p_meta->ch[i].b_codes = 0;
}
return WAVE_ST_OK;
}
/*
* 函数功能：内部——把固定头 + 通道表写进缓冲（不含头 CRC）
* 入口参数：p_meta 段头；p_out 缓冲（容量须 >= 头 CRC 覆盖区）
* 返 回 值：写入字节数（= 头 CRC 覆盖区长度） uint32_t
* 限定条件：p_meta 已过 wave_st_meta_check、p_out 容量已核过
*/
static uint32_t wave_st_head_raw(const wave_seg_meta_t *p_meta, uint8_t *p_out) {
uint8_t i;
const uint32_t tbl_n = (uint32_t)p_meta->ch_count * WAVE_ST_CH_BYTES;
p_out[WAVE_ST_OFF_MAGIC] = (uint8_t)WAVE_ST_MAGIC0;
p_out[WAVE_ST_OFF_MAGIC + 1u] = (uint8_t)WAVE_ST_MAGIC1;
/* 魔数第三字节 = 版本号：与 ver 字段同源同值（§6.2 第 0 行 + §6.3 判废口径） */
p_out[WAVE_ST_OFF_MAGIC + 2u] = (uint8_t)WAVE_ST_VER;
p_out[WAVE_ST_OFF_VER] = (uint8_t)WAVE_ST_VER;
wave_st_put16(&p_out[WAVE_ST_OFF_FS_HZ], p_meta->fs_hz);
p_out[WAVE_ST_OFF_PTS_CYC] = p_meta->pts_per_cycle;
p_out[WAVE_ST_OFF_CH_CNT] = p_meta->ch_count;
wave_st_put16(&p_out[WAVE_ST_OFF_PTS_CH], p_meta->pts_per_ch);
wave_st_put16(&p_out[WAVE_ST_OFF_PRE_PTS], p_meta->pre_pts);
p_out[WAVE_ST_OFF_TRIG_SRC] = p_meta->trig_src;
p_out[WAVE_ST_OFF_TRIG_ELM] = p_meta->trig_elm;
wave_st_put32(&p_out[WAVE_ST_OFF_T0_MS], p_meta->t0_ms);
wave_st_put32(&p_out[WAVE_ST_OFF_WALL], p_meta->wall);
p_out[WAVE_ST_OFF_ENG] = p_meta->eng;
p_out[WAVE_ST_OFF_FLAGS] = p_meta->flags_seq;
wave_st_put16(&p_out[WAVE_ST_OFF_CLIP], p_meta->clip_mask);
wave_st_put32(&p_out[WAVE_ST_OFF_SEQ], p_meta->frame_seq);
for (i = 0u; i < p_meta->ch_count; i++) {
uint32_t pos = (uint32_t)WAVE_ST_OFF_TBL + ((uint32_t)i * WAVE_ST_CH_BYTES);
p_out[pos + WAVE_ST_CH_OFF_SEM] = p_meta->ch[i].sem;
p_out[pos + WAVE_ST_CH_OFF_CONV] = p_meta->ch[i].conv;
p_out[pos + WAVE_ST_CH_OFF_BITS] = p_meta->ch[i].bits;
p_out[pos + WAVE_ST_CH_OFF_AVAIL] = p_meta->ch[i].avail;
/* int32 系数按小端原样落 4 字节：右移到 24 位前把符号扩展掉，
* 保证板端 ARMCC 与主机 CRT 写出同一串字节 */
wave_st_put32(&p_out[pos + WAVE_ST_CH_OFF_KQ16], (uint32_t)p_meta->ch[i].k_q16);
wave_st_put32(&p_out[pos + WAVE_ST_CH_OFF_BCODE], (uint32_t)p_meta->ch[i].b_codes);
}
return (uint32_t)WAVE_ST_OFF_TBL + tbl_n;
}
/*
* 函数功能：编码段头（固定头 + 通道表 + 头 CRC）
* 入口参数：p_meta 段头元数据；p_out 输出缓冲；a_cap 容量
* 返 回 值：>= 0 写入字节数；负 = WAVE_ST_E_* int
* 限定条件：任意上下文；无静态缓冲、可重入
* 函数说明：头 CRC 覆盖 [0, 30+12×ch_count)、自身紧随其后、低字节在前（§6.3）。
*/
int wave_store_head_build(const wave_seg_meta_t *p_meta, uint8_t *p_out, uint32_t a_cap) {
uint32_t crc_pos;
uint16_t crc;
int rc;
if ((p_meta == NULL) || (p_out == NULL)) {
return WAVE_ST_E_PARAM;
}
rc = wave_st_meta_check(p_meta);
if (rc != WAVE_ST_OK) {
return rc;
}
crc_pos = WAVE_ST_HEAD_CRC_POS(p_meta->ch_count);
if (a_cap < (crc_pos + 2u)) {
return WAVE_ST_E_PARAM;
}
(void)wave_st_head_raw(p_meta, p_out);
crc = wave_store_crc(p_out, crc_pos);
/* 低字节在前（§6.3 首行）：put16 本来就是小端，这里不额外翻转 */
wave_st_put16(&p_out[crc_pos], crc);
return (int)(crc_pos + 2u);
}
/*
* 函数功能：解码 + 全套判废（魔数 / 版本 / 缓冲长度 / 几何 / 表序 / 头 CRC）
* 入口参数：p_buf 头字节流；a_len 可读字节数；p_meta 输出
* 返 回 值：WAVE_ST_OK 或 WAVE_ST_E_*（见 wave_store.h） int
* 限定条件：任意上下文
* 函数说明：顺序刻意是「先验魔数与版本，再算整头长度，再验 CRC，最后验语义」——
* 前两步决定我们**有没有资格**按这份布局去数偏移；反过来先按 ch_count 算长度，
* 一个被写坏的 ch_count 就能让我们读到缓冲外面去。
*/
int wave_store_head_parse(const uint8_t *p_buf, uint32_t a_len, wave_seg_meta_t *p_meta) {
uint8_t ch_count;
uint32_t crc_pos;
uint32_t head_sz;
uint16_t want;
uint16_t got;
int rc;
wave_seg_meta_t tmp;
if ((p_buf == NULL) || (p_meta == NULL)) {
return WAVE_ST_E_PARAM;
}
/* 固定头是 30 + 1 字节通道数才能算出整头长度，至少得读到偏移 7 */
if (a_len < ((uint32_t)WAVE_ST_OFF_CH_CNT + 1u)) {
return WAVE_ST_E_PARAM;
}
if ((p_buf[WAVE_ST_OFF_MAGIC] != (uint8_t)WAVE_ST_MAGIC0) ||
(p_buf[WAVE_ST_OFF_MAGIC + 1u] != (uint8_t)WAVE_ST_MAGIC1)) {
return WAVE_ST_E_FORMAT;
}
/* ver 必须等于魔数第三字节、且等于本层认识的版本（§6.2 末行） */
if ((p_buf[WAVE_ST_OFF_VER] != p_buf[WAVE_ST_OFF_MAGIC + 2u]) ||
(p_buf[WAVE_ST_OFF_VER] != (uint8_t)WAVE_ST_VER)) {
return WAVE_ST_E_FORMAT;
}
ch_count = p_buf[WAVE_ST_OFF_CH_CNT];
head_sz = wave_store_head_bytes(ch_count);
if (head_sz == 0u) {
return WAVE_ST_E_SIZE;
}
if (a_len < head_sz) {
return WAVE_ST_E_PARAM;
}
crc_pos = WAVE_ST_HEAD_CRC_POS(ch_count);
want = wave_st_get16(&p_buf[crc_pos]);
got = wave_store_crc(p_buf, crc_pos);
if (want != got) {
return WAVE_ST_E_CRC;
}
/* 头 CRC 过了才开始解释字段：下面填的是一份可交回调用方的完整元数据 */
tmp.fs_hz = wave_st_get16(&p_buf[WAVE_ST_OFF_FS_HZ]);
tmp.pts_per_cycle = p_buf[WAVE_ST_OFF_PTS_CYC];
tmp.ch_count = ch_count;
tmp.pts_per_ch = wave_st_get16(&p_buf[WAVE_ST_OFF_PTS_CH]);
tmp.pre_pts = wave_st_get16(&p_buf[WAVE_ST_OFF_PRE_PTS]);
tmp.trig_src = p_buf[WAVE_ST_OFF_TRIG_SRC];
tmp.trig_elm = p_buf[WAVE_ST_OFF_TRIG_ELM];
tmp.t0_ms = wave_st_get32(&p_buf[WAVE_ST_OFF_T0_MS]);
tmp.wall = wave_st_get32(&p_buf[WAVE_ST_OFF_WALL]);
tmp.eng = p_buf[WAVE_ST_OFF_ENG];
tmp.flags_seq = p_buf[WAVE_ST_OFF_FLAGS];
tmp.clip_mask = wave_st_get16(&p_buf[WAVE_ST_OFF_CLIP]);
tmp.frame_seq = wave_st_get32(&p_buf[WAVE_ST_OFF_SEQ]);
for (ch_count = 0u; ch_count < (uint8_t)WAVE_ST_CH_MAX; ch_count++) {
tmp.ch[ch_count].sem = 0u;
tmp.ch[ch_count].conv = 0u;
tmp.ch[ch_count].bits = 0u;
tmp.ch[ch_count].avail = 0u;
tmp.ch[ch_count].k_q16 = 0;
tmp.ch[ch_count].b_codes = 0;
}
for (ch_count = 0u; ch_count < p_buf[WAVE_ST_OFF_CH_CNT]; ch_count++) {
uint32_t pos = (uint32_t)WAVE_ST_OFF_TBL + ((uint32_t)ch_count * WAVE_ST_CH_BYTES);
tmp.ch[ch_count].sem = p_buf[pos + WAVE_ST_CH_OFF_SEM];
tmp.ch[ch_count].conv = p_buf[pos + WAVE_ST_CH_OFF_CONV];
tmp.ch[ch_count].bits = p_buf[pos + WAVE_ST_CH_OFF_BITS];
tmp.ch[ch_count].avail = p_buf[pos + WAVE_ST_CH_OFF_AVAIL];
tmp.ch[ch_count].k_q16 = (int32_t)wave_st_get32(&p_buf[pos + WAVE_ST_CH_OFF_KQ16]);
tmp.ch[ch_count].b_codes = (int32_t)wave_st_get32(&p_buf[pos + WAVE_ST_CH_OFF_BCODE]);
}
rc = wave_st_meta_check(&tmp);
if (rc != WAVE_ST_OK) {
return rc;
}
*p_meta = tmp;
return WAVE_ST_OK;
}
/* ===== 长度 / 偏移换算 ===== */
/*
* 函数功能：整头字节数
* 入口参数：a_ch_count 通道数
* 返 回 值：字节数；通道数非法返回 0 uint32_t
* 限定条件：任意上下文
*/
uint32_t wave_store_head_bytes(uint8_t a_ch_count) {
if ((a_ch_count == 0u) || (a_ch_count > (uint8_t)WAVE_ST_CH_MAX)) {
return 0u;
}
return WAVE_ST_HEAD_BYTES(a_ch_count);
}
/*
* 函数功能：按头部字段算整段应有字节数
* 入口参数：p_meta 段头
* 返 回 值：期望字节数；字段非法返回 0 uint32_t
* 限定条件：任意上下文
* 函数说明：等式 = 32 + 12×ch_count + pts_per_ch×ch_count×2 + 2（§6.3；
* 8 路 320 点 = 5250）。落盘道拿它比对 f_write 写回字节数与 f_size。
*/
uint32_t wave_store_seg_size(const wave_seg_meta_t *p_meta) {
if (p_meta == NULL) {
return 0u;
}
if ((p_meta->ch_count == 0u) || (p_meta->ch_count > (uint8_t)WAVE_ST_CH_MAX)) {
return 0u;
}
if (p_meta->pts_per_ch == 0u) {
return 0u;
}
return WAVE_ST_SEG_TOTAL(p_meta->ch_count, p_meta->pts_per_ch);
}
/*
* 函数功能：数据区某点的文件绝对偏移
* 入口参数：a_ch_count 通道数；a_pts_ch 每通道点数；a_ch 列号；a_pt 段内点下标
* 返 回 值：偏移；非法返回 0xFFFFFFFFu 哨兵 uint32_t
* 限定条件：任意上下文
* 函数说明：按通道分列 → 偏移 = 整头长 + (列 × 点数 + 点下标) × 2。单通道整列是连续的，
* 这正是 §6.2「只读那一路」能一次连续读的原因。
*/
uint32_t wave_store_data_off(uint8_t a_ch_count, uint16_t a_pts_ch,
uint8_t a_ch, uint32_t a_pt) {
uint32_t head_sz = wave_store_head_bytes(a_ch_count);
if ((head_sz == 0u) || (a_pts_ch == 0u) || (a_ch >= a_ch_count)) {
return WAVE_ST_BAD_OFF;
}
if (a_pt >= (uint32_t)a_pts_ch) {
return WAVE_ST_BAD_OFF;
}
return head_sz + (((uint32_t)a_ch * (uint32_t)a_pts_ch) + a_pt) * 2u;
}
/*
* 函数功能：从某点起当前列还能连续读多少字节
* 入口参数：a_pts_ch 每通道点数；a_pt 起始点下标；a_want 想读点数
* 返 回 值：可连续读字节数（参数非法返回 0） uint32_t
* 限定条件：任意上下文
*/
uint32_t wave_store_data_bytes_avail(uint16_t a_pts_ch, uint32_t a_pt, uint32_t a_want) {
uint32_t left;
uint32_t n;
if ((a_pts_ch == 0u) || (a_want == 0u)) {
return 0u;
}
if (a_pt >= (uint32_t)a_pts_ch) {
return 0u;
}
left = (uint32_t)a_pts_ch - a_pt;
n = (a_want < left) ? a_want : left;
return n * 2u;
}
/*
* 函数功能：小端字节 → int16 点序列
* 入口参数：p_raw 原始字节；a_len 字节数；p_out 输出；a_max_pts 容量；p_pts 实际点数（可空）
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针 / 奇数字节 / 容量不足 int
* 限定条件：任意上下文
* 函数说明：奇数字节按参数错处理而不是「丢掉尾巴」——半截样本被静默吞掉，
* 回放页画出来的波形会比真的少最后一个点，而这种误差正好最难查。
*/
int wave_store_le_decode(const uint8_t *p_raw, uint32_t a_len,
int16_t *p_out, uint32_t a_max_pts, uint32_t *p_pts) {
uint32_t n;
uint32_t i;
if ((p_raw == NULL) || (p_out == NULL)) {
return WAVE_ST_E_PARAM;
}
if (((a_len & 0x00000001u) != 0u) || (a_len > (a_max_pts * 2u))) {
return WAVE_ST_E_PARAM;
}
n = a_len / 2u;
for (i = 0u; i < n; i++) {
/* 先攒成 uint16 再转 int16：补码回绕在 C 里是实现定义但两大编译器一致，
* 而这里需要的正是「按补码位型解释」——TPAFE 的 16 位补码就是这么存的 */
p_out[i] = (int16_t)wave_st_get16(&p_raw[i * 2u]);
}
if (p_pts != NULL) {
*p_pts = n;
}
return WAVE_ST_OK;
}
/*
* 函数功能：码值 → 定点毫单位（mV）
* 入口参数：p_desc 通道表项（必须来自段文件头）；a_code 码值；p_milli 输出 mV
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针 int
* 限定条件：任意上下文（只在回放页与单测用，不在 1 kHz 采集链上；用 int64 中间量）
* 函数说明：模型 eng = (code + b) × k × 1e-6（§6.3，与 adc_cal_apply() 同式），
* k = k_q16 / 65536 µV/码 → mV = (code + b) × k_q16 / 65536000，四舍五入。
* 中间量最大约 (32767 + 8192) × 5.28e7 ≈ 2.2e12，int64 宽裕。
*/
int wave_store_code_to_milli(const wave_ch_desc_t *p_desc, int16_t a_code,
int32_t *p_milli) {
int64_t num;
int64_t den = 65536000;
int64_t v;
if ((p_desc == NULL) || (p_milli == NULL)) {
return WAVE_ST_E_PARAM;
}
num = ((int64_t)a_code + (int64_t)p_desc->b_codes) * (int64_t)p_desc->k_q16;
if (num >= 0) {
v = (num + (den / 2)) / den;
} else {
v = -(((-num) + (den / 2)) / den);
}
*p_milli = (int32_t)v;
return WAVE_ST_OK;
}
/* ===== 整段校验 ===== */
/*
* 函数功能：整段镜像自检（头 + 数据区 + 数据 CRC）
* 入口参数：p_img 镜像；a_len 长度；p_meta 输出段头（可空）
* 返 回 值：WAVE_ST_OK 或 WAVE_ST_E_*（见 wave_store.h） int
* 限定条件：任意上下文；整段驻留时用（本波 5250 字节）
* 函数说明：三条判废一条都不能省：长度 0 或不等、头 CRC、数据 CRC。
* 期望总长用**头里的字段**算，不用编译期常量——文件是自己说它多长，
* 与镜像实际长度不一致就是坏段（§6.2 末行）。
*/
int wave_store_seg_check(const uint8_t *p_img, uint32_t a_len, wave_seg_meta_t *p_meta) {
wave_seg_meta_t meta;
uint32_t want_total;
uint32_t data_off;
uint32_t data_len;
uint16_t want;
uint16_t got;
int rc;
if (p_img == NULL) {
return WAVE_ST_E_PARAM;
}
if (a_len == 0u) {
return WAVE_ST_E_SIZE;
}
rc = wave_store_head_parse(p_img, a_len, &meta);
if (rc != WAVE_ST_OK) {
return rc;
}
want_total = wave_store_seg_size(&meta);
if (want_total == 0u) {
return WAVE_ST_E_SIZE;
}
if (a_len != want_total) {
return WAVE_ST_E_SIZE;
}
data_off = wave_store_head_bytes(meta.ch_count); /* 数据区起点 = 整头字节数 */
data_len = a_len - 2u - data_off;
if (data_len == 0u) {
return WAVE_ST_E_SIZE;
}
want = wave_st_get16(&p_img[a_len - 2u]);
got = wave_store_crc(&p_img[data_off], data_len);
if (want != got) {
return WAVE_ST_E_CRC;
}
if (p_meta != NULL) {
*p_meta = meta;
}
return WAVE_ST_OK;
}
/* ===== 打包游标 ===== */
/*
* 函数功能：初始化打包游标
* 入口参数：p_ctx 游标；p_meta 段头；p_reader 数据源（可空 = 只产头）；p_user 上下文
* 返 回 值：WAVE_ST_OK 或 WAVE_ST_E_* int
* 限定条件：任意上下文（纯计算）；一段一个游标
* 函数说明：段头整份拷进游标——搬运窗口几十毫秒，期间调用方完全可以去改它自己那份
* （比如 adcTask 又跑了几拍），本段的字节不能受影响。
*/
int wave_store_pack_start(wave_pack_ctx_t *p_ctx, const wave_seg_meta_t *p_meta,
wave_reader_fn p_reader, void *p_user) {
int rc;
if ((p_ctx == NULL) || (p_meta == NULL)) {
return WAVE_ST_E_PARAM;
}
rc = wave_st_meta_check(p_meta);
if (rc != WAVE_ST_OK) {
p_ctx->phase = (uint8_t)WAVE_PACK_IDLE;
return rc;
}
p_ctx->total = wave_store_seg_size(p_meta);
if (p_ctx->total == 0u) {
p_ctx->phase = (uint8_t)WAVE_PACK_IDLE;
return WAVE_ST_E_SIZE;
}
p_ctx->phase = (uint8_t)WAVE_PACK_HEAD;
p_ctx->ch = 0u;
p_ctx->head_done = 0u;
p_ctx->ch_done = 0u;
p_ctx->tail_done = 0u;
p_ctx->rsv = 0u;
p_ctx->crc_data = WAVE_ST_CRC_INIT;
p_ctx->sent = 0u;
p_ctx->p_reader = p_reader;
p_ctx->p_user = p_user;
p_ctx->meta = *p_meta;
return WAVE_ST_OK;
}
/*
* 函数功能：取整段字节流的下一片
* 入口参数：p_ctx 游标；p_out 缓冲；a_cap 容量；p_len 实际产出字节数
* 返 回 值：WAVE_ST_OK 还有后续；WAVE_ST_DONE 整段产完；负 = WAVE_ST_E_* int
* 限定条件：任意上下文，同一游标不得并发使用
* 函数说明：三段推进——头（一次给完，要求容量 >= 整头）、数据区（按列连续、整样本切，
* 绝不切半个 int16，也不跨列，便于回调按列读）、尾 CRC 两字节。
* 数据 CRC 边产边算（增量中间值），所以全程不需要整段驻留 RAM。
*/
int wave_store_pack_next(wave_pack_ctx_t *p_ctx, uint8_t *p_out,
uint32_t a_cap, uint32_t *p_len) {
uint32_t n = 0u;
if ((p_ctx == NULL) || (p_out == NULL) || (p_len == NULL)) {
return WAVE_ST_E_PARAM;
}
*p_len = 0u;
if ((p_ctx->phase == (uint8_t)WAVE_PACK_IDLE) || (a_cap == 0u)) {
return WAVE_ST_E_STATE;
}
if (p_ctx->phase == (uint8_t)WAVE_PACK_DONE) {
return WAVE_ST_DONE;
}
/* --- 头：整头一次产完（接线索按 §7 给 256 字节缓冲，足够 128 字节整头） --- */
if (p_ctx->phase == (uint8_t)WAVE_PACK_HEAD) {
uint32_t head_sz;
int rc;
head_sz = wave_store_head_bytes(p_ctx->meta.ch_count);
if (head_sz == 0u) {
return WAVE_ST_E_SIZE;
}
if (a_cap < head_sz) {
/* 不拆着头给：半截头意味着游标要存 128 字节中间态，纯浪费 */
return WAVE_ST_E_PARAM;
}
rc = wave_store_head_build(&p_ctx->meta, p_out, a_cap);
if (rc < 0) {
return rc;
}
n = (uint32_t)rc;
p_ctx->head_done = (uint16_t)n;
p_ctx->sent += n;
*p_len = n;
p_ctx->phase = (uint8_t)WAVE_PACK_DATA;
return WAVE_ST_OK;
}
/* --- 数据区：按列推进，一次最多一批 --- */
if (p_ctx->phase == (uint8_t)WAVE_PACK_DATA) {
int16_t batch[WAVE_ST_BATCH];
if (p_ctx->p_reader == NULL) {
/* 没有数据源却进了数据区：宁可报错也不产空字节。
* 产空字节会写出「长度对、内容是 0」的段文件，回放页会画出一条直线——
* 那正是 §8.1 明令禁止的伪造证据形态。 */
return WAVE_ST_E_STATE;
}
while ((n < a_cap) && (p_ctx->ch < p_ctx->meta.ch_count)) {
uint32_t room_pts = (a_cap - n) / 2u;
uint32_t col_left = (uint32_t)p_ctx->meta.pts_per_ch - (uint32_t)p_ctx->ch_done;
uint32_t take;
int32_t got;
uint32_t i;
if (col_left == 0u) {
p_ctx->ch++;
p_ctx->ch_done = 0u;
continue;
}
if (room_pts == 0u) {
break;
}
take = (room_pts < col_left) ? room_pts : col_left;
if (take > (uint32_t)WAVE_ST_BATCH) {
take = (uint32_t)WAVE_ST_BATCH;
}
got = p_ctx->p_reader(p_ctx->p_user, p_ctx->ch, (uint32_t)p_ctx->ch_done,
take, batch);
if (got < 0) {
return (int)got;
}
if ((uint32_t)got != take) {
/* 数据源给不满就是数据源的问题（越界 / 未封存），不拿半批凑长度 */
return WAVE_ST_E_STATE;
}
uint32_t base_n = n;
for (i = 0u; i < take; i++) {
wave_st_put_code(&p_out[n], batch[i]);
n += 2u;
}
p_ctx->crc_data = wave_store_crc_update(p_ctx->crc_data, &p_out[base_n], take * 2u);
p_ctx->ch_done = (uint16_t)((uint32_t)p_ctx->ch_done + take);
}
if (p_ctx->ch >= p_ctx->meta.ch_count) {
/* 最后一列的最后一点产出后，「列走完了」要到下一次进循环才发现，
* 所以这一拍可能一个字节都没产。这时候不许当参数错报出去：整段就差
* 最后两片 CRC，报 E_PARAM 会让落盘道把一次真故障判成落盘失败（白丢）。
* 让它落到下面的尾段分支，在同一次调用里把尾产完。 */
p_ctx->phase = (uint8_t)WAVE_PACK_TAIL;
}
p_ctx->sent += n;
*p_len = n;
if (n > 0u) {
return WAVE_ST_OK;
}
if (p_ctx->phase != (uint8_t)WAVE_PACK_TAIL) {
return WAVE_ST_E_PARAM; /* 容量连一个整样本都装不下 */
}
}
/* --- 尾：数据区 CRC，低字节在前 --- */
if (p_ctx->phase == (uint8_t)WAVE_PACK_TAIL) {
if (p_ctx->tail_done == 0u) {
p_out[n] = (uint8_t)(p_ctx->crc_data & 0xFFu);
n++;
p_ctx->tail_done = 1u;
}
if ((p_ctx->tail_done == 1u) && (n < a_cap)) {
p_out[n] = (uint8_t)((p_ctx->crc_data >> 8) & 0xFFu);
n++;
p_ctx->tail_done = 2u;
p_ctx->phase = (uint8_t)WAVE_PACK_DONE;
}
p_ctx->sent += n;
*p_len = n;
return (p_ctx->phase == (uint8_t)WAVE_PACK_DONE) ? WAVE_ST_DONE : WAVE_ST_OK;
}
return WAVE_ST_E_STATE;
}
/*
* 函数功能：游标已产出字节数
* 入口参数：p_ctx 游标
* 返 回 值：字节数；空指针返回 0 uint32_t
* 限定条件：任意上下文（只读）
*/
uint32_t wave_store_pack_offset(const wave_pack_ctx_t *p_ctx) {
return (p_ctx == NULL) ? 0u : p_ctx->sent;
}
/*
* 函数功能：游标对应整段的期望总长
* 入口参数：p_ctx 游标
* 返 回 值：字节数；空指针返回 0 uint32_t
* 限定条件：任意上下文（只读）
*/
uint32_t wave_store_pack_total(const wave_pack_ctx_t *p_ctx) {
return (p_ctx == NULL) ? 0u : p_ctx->total;
}
/* ===== 段文件名轮转（只算名字，不碰文件系统） ===== */
/*
* 函数功能：内部——把两位十进制写进缓冲
* 入口参数：p 目标（至少 2 字节）；a_idx 0..99
* 返 回 值：无 void
* 限定条件：a_idx 已由调用方限制在 0..99
*/
static void wave_st_put_idx2(char *p, uint8_t a_idx) {
p[0] = (char)('0' + (a_idx / 10u));
p[1] = (char)('0' + (a_idx % 10u));
}
/*
* 函数功能：按段号生成段文件路径
* 入口参数：p_out 缓冲；a_cap 容量；a_idx 段号 0..99
* 返 回 值：>= 0 写入字符数（不含结束符）；WAVE_ST_E_PARAM / WAVE_ST_E_RANGE int
* 限定条件：任意上下文；纯字符拼装（不用格式化函数），板端与 PC 侧逐字节一致
* 函数说明：形态 = 目录 / 前缀 + 两位十进制 + 扩展名，严格 8.3（§5.2 第三条）。
*/
int wave_store_seg_path(char *p_out, uint32_t a_cap, uint8_t a_idx) {
static const char s_dir[] = WAVE_ST_DIR;
static const char s_pfx[] = WAVE_ST_PFX;
static const char s_ext[] = WAVE_ST_EXT;
uint32_t pos = 0u;
uint32_t i;
char buf[WAVE_ST_PATH_MAX];
if (p_out == NULL) {
return WAVE_ST_E_PARAM;
}
if (a_idx >= (uint8_t)WAVE_ST_SEG_MAX) {
return WAVE_ST_E_RANGE;
}
for (i = 0u; i < ((uint32_t)sizeof(s_dir) - 1u); i++) {
buf[pos++] = s_dir[i];
}
buf[pos++] = '/';
for (i = 0u; i < ((uint32_t)sizeof(s_pfx) - 1u); i++) {
buf[pos++] = s_pfx[i];
}
wave_st_put_idx2(&buf[pos], a_idx);
pos += 2u;
for (i = 0u; i < ((uint32_t)sizeof(s_ext) - 1u); i++) {
buf[pos++] = s_ext[i];
}
if (pos >= (uint32_t)sizeof(buf)) {
/* 宏与拼装长度漂移时的兜底：宁可给不出名字，也绝不把结束符写到别人缓冲外 */
return WAVE_ST_E_SIZE;
}
buf[pos] = '\0';
/* 容量必须容得下结束符：写成 a_cap < pos 会放过「刚好差一个字节」的调用方，
* 于是把 p_out[pos] 写到别人缓冲外面（越界写在板子上是静默的） */
if (a_cap <= pos) {
return WAVE_ST_E_PARAM;
}
for (i = 0u; i <= pos; i++) {
p_out[i] = buf[i];
}
return (int)pos;
}
/*
* 函数功能：下一个轮转段号
* 入口参数：a_idx 当前段号（越界按 0 处理）
* 返 回 值：下一个段号 uint8_t
* 限定条件：任意上下文
*/
uint8_t wave_store_next_idx(uint8_t a_idx) {
if (a_idx >= (uint8_t)WAVE_ST_SEG_MAX) {
return 0u;
}
if (a_idx >= ((uint8_t)WAVE_ST_SEG_MAX - 1u)) {
return 0u;
}
return (uint8_t)(a_idx + 1u);
}
/*
* 函数功能：内部——大小写无关地比对一个字符
* 入口参数：a 待测字符（视作 ASCII）；b 期望字符（取自段名宏）
* 返 回 值：1 相同；0 不同 uint8_t
* 限定条件：两侧都是 ASCII；非字母字符原样比
* 函数说明：**两侧都**归一化成小写再比。只归一化一侧是个真踩过一次的坑——
* 段名宏 WAVE_ST_PFX / WAVE_ST_EXT 是大写形态（FatFs 8.3 短名就是大写），
* 只把待测串转小写等于「小写 vs 大写」永不相等，反解会拒绝掉全部合法段名
* （单测 用例：首轮 100% 拒绝就是这个）。盘上大小写与宏写法
* 谁都不该去猜，故两侧各归一一次。
*/
static uint8_t wave_st_ci_eq(char a, char b) {
char x = a;
char y = b;
if ((x >= 'A') && (x <= 'Z')) {
x = (char)(x + ('a' - 'A'));
}
if ((y >= 'A') && (y <= 'Z')) {
y = (char)(y + ('a' - 'A'));
}
return (x == y) ? 1u : 0u;
}
/*
* 函数功能：从文件名或路径反解段号
* 入口参数：p_path 路径或纯文件名；p_idx 输出
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针；WAVE_ST_E_NAME 不是本层命名形态 int
* 限定条件：任意上下文
* 函数说明：只认 basename 上的「wave + 两位数字 + .bin」（大小写都收）。
* 不匹配就返回错误，**绝不**把陌生名字当录波段——扫目录重建段账时误认一个
* 别的文件，等于把别人的文件当波形解释（名字/参数类错误码严禁升级成卷操作，
* 存储架构说明 §10.1 同一条教训）。
*/
int wave_store_idx_from_name(const char *p_path, uint8_t *p_idx) {
static const char s_pfx[] = WAVE_ST_PFX;
static const char s_ext[] = WAVE_ST_EXT;
const char *base = p_path;
const char *q = p_path;
uint32_t i;
uint32_t len = 0u;
uint8_t hi;
uint8_t lo;
if ((p_path == NULL) || (p_idx == NULL)) {
return WAVE_ST_E_PARAM;
}
/* 找 basename：支持反斜杠形态（PC 侧脚本拼出来的路径可能被原样传进来） */
while (*q != '\0') {
if ((*q == '/') || (*q == '\\')) {
base = q + 1;
}
q++;
}
q = base;
while ((*q != '\0') && (len < (uint32_t)WAVE_ST_PATH_MAX)) {
q++;
len++;
}
if ((*q != '\0') || (len != ((uint32_t)sizeof(s_pfx) - 1u) + 2u +
((uint32_t)sizeof(s_ext) - 1u))) {
return WAVE_ST_E_NAME;
}
for (i = 0u; i < ((uint32_t)sizeof(s_pfx) - 1u); i++) {
if (wave_st_ci_eq(base[i], s_pfx[i]) == 0u) {
return WAVE_ST_E_NAME;
}
}
hi = (uint8_t)base[i];
lo = (uint8_t)base[i + 1u];
if ((hi < '0') || (hi > '9') || (lo < '0') || (lo > '9')) {
return WAVE_ST_E_NAME;
}
for (i = (i + 2u); i < len; i++) {
if (wave_st_ci_eq(base[i], s_ext[i - ((uint32_t)sizeof(s_pfx) - 1u) - 2u]) == 0u) {
return WAVE_ST_E_NAME;
}
}
*p_idx = (uint8_t)(((hi - '0') * 10u) + (lo - '0'));
return WAVE_ST_OK;
}
App/algo/wave_store.h
+491
View File
@@ -0,0 +1,491 @@
/*
* 模块名称：录波段格式层（故障录波 · 段文件字节布局编解码 + 打包游标 + 段名轮转）
* 模块功能：把「一段录波」在内存字节缓冲与结构化元数据之间逐字节翻译，并给落盘道
* 提供分次搬运的打包游标。口径唯一属主 = docs/子系统设计/故障录波设计说明.md §6.2
* （字节布局）与 §6.3（九问裁定：板端编码器与 PC 解码器 test/host/wave_read.py
* 两份独立实现的共同依据）。本文件是它的机器可执行形态，不在此重新定义任何口径；
* 两处冲突以设计文档为准并回报 lead，不在代码里单方面「修正」。
* 纯逻辑层纪律：不 include HAL / CMSIS / RTOS 头、不调 FatFs、不碰文件系统、
* 不建任务、不打日志（文件 I/O 与任务钩子全在接线层 App/task/ 里做），
* 因此可被主机侧单测 test/host/wave_store/ 原样纳入做逐字节断言。
* 职责边界（为什么这样切）：
* 1) 固定头 + 通道表编解码、头 CRC 与数据区 CRC 自检 —— 格式知识只此一处；
* 2) 打包游标（分次搬运）：文件系统唯一写者只要「每次给我不超过 256 字节的下一片」，
* 整段 5250 字节不驻留 RAM（设计说明 §7：搬运缓冲 256 B × 2，不做整段驻留）；
* 3) 段文件名轮转与反解：只算名字，不打开文件（FatFs FF_USE_LFN=0 只能严格
* 8.3 短名，见 docs/架构设计/STM32F4-Base存储架构说明.md §10.1）；
* 4) 数据区偏移换算 + 小端解码：回放页只画一路（设计说明 §8.1），按通道分列
* 让「只读那一路」成为一次连续读。
* 不链 App/algo/adc_cal（零依赖 = 主机免桩可测）：通道表里的 k_q16 / b_codes /
* 可用性由调用方在封存瞬间取 int32 原值填进 meta 后交给本层编码。系数必须走
* adc_cal_k_q16()（接线道补的 int32 直读入口），不得经 adc_cal_k_uv() 的 float
* 通道回算 —— float 在 5.28e7 量级掉尾数（设计说明 §6.3「k / b 宽度与角色」行）。
* CRC 一张表的原始说法不成立，lead 已在 §6.3 记录实测依据：全仓无可复用的
* CRC-16 表（App/util/README.md 记 crc.c 与 crc.h 已于 2026-10-02 删除；屏板链路
* Drivers/BSP/UI/ui_net_sink.c 的 remo_crc() 是单字节异或、不是 CRC-16）。
* 故本层自带无表位运算 CRC-16/MODBUS，并用规范锚点自校验。
* 适用平台：STM32F407ZGTx（Cortex-M4，小端）；主机侧单测 test/host/wave_store/
* 作者：DTU 项目组
* 创建日期：2026-10-29（故障录波 task-1 · 数据面纯逻辑层）
* 修改记录：
* v1.0 2026-10-29 DTU 项目组 创建：段头/通道表编解码、CRC-16/MODBUS 无表实现、
* 打包游标、段名轮转与反解、数据区偏移换算与小端解码
*
* 二期不返工的结构约束（设计说明 §2.1，改本层前先读）：
* 1) 采样率与每周波点数是写进文件头的数据，不是编译期假设 —— 回放端与 PC 脚本一律
* 从头里读，本层算长度也照 meta 里的值算，不在代码里写死 1000 / 20；
* 2) 版本号并进魔数第三字节，换格式即变；本层解到不认识的版本一律判废；
* 3) 「带 TEMP 就要连 flags_seq 与 clip_mask 一起升版本」同源（§6.2 那两行的括注），
* 所以本层的通道数上限留到 9，但本波实际只用 8。
*/
#ifndef WAVE_STORE_H
#define WAVE_STORE_H
/* 同 App/algo/wave_ring.h：本头的 NULL 只出现在注释里（字段与入参的约束说明），
* 代码只用 stdint 的类型，故不 include stddef.h；用 NULL 的 .c 自己带。 */
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
/* ===== 一、段文件布局常量（逐字段照 docs/子系统设计/故障录波设计说明.md §6.2 与 §6.3） ===== */
/* 魔数前两字节固定 'W' 与 'R'，第三字节 = 版本号（设计说明 §6.2 偏移 0 行） */
#define WAVE_ST_MAGIC0 (0x57u) /* 'W' */
#define WAVE_ST_MAGIC1 (0x52u) /* 'R' */
/* 版本：本波恒 1。ver 字段必须同时等于魔数第三字节与本宏，否则整段判废（§6.2 末行） */
#define WAVE_ST_VER (1u)
/* 固定头字段偏移（字节，小端） */
#define WAVE_ST_OFF_MAGIC (0u) /* 3 字节：'W' 'R' ver */
#define WAVE_ST_OFF_VER (3u) /* 1 字节 */
#define WAVE_ST_OFF_FS_HZ (4u) /* 2 字节 本波 1000 */
#define WAVE_ST_OFF_PTS_CYC (6u) /* 1 字节 本波 20 */
#define WAVE_ST_OFF_CH_CNT (7u) /* 1 字节 本波 8 */
#define WAVE_ST_OFF_PTS_CH (8u) /* 2 字节 本波 320 */
#define WAVE_ST_OFF_PRE_PTS (10u) /* 2 字节 本波 160 */
#define WAVE_ST_OFF_TRIG_SRC (12u) /* 1 字节 */
#define WAVE_ST_OFF_TRIG_ELM (13u) /* 1 字节 */
#define WAVE_ST_OFF_T0_MS (14u) /* 4 字节 u32 */
#define WAVE_ST_OFF_WALL (18u) /* 4 字节 u32 */
#define WAVE_ST_OFF_ENG (22u) /* 1 字节 */
#define WAVE_ST_OFF_FLAGS (23u) /* 1 字节 */
#define WAVE_ST_OFF_CLIP (24u) /* 2 字节 */
#define WAVE_ST_OFF_SEQ (26u) /* 4 字节 u32 */
#define WAVE_ST_OFF_TBL (30u) /* 通道表起点 */
/* 通道表一路 12 字节 = 语义号 1 + 来源转换器 1 + 位宽 1 + 可用性 1 + k_q16 4 + b_codes 4
* 设计说明 §6.3「LSB 从哪来」：不设独立 LSB 字段，k_q16 就是 LSB（单位 µV/码 × 65536） */
#define WAVE_ST_CH_OFF_SEM (0u) /* 1 字节 */
#define WAVE_ST_CH_OFF_CONV (1u) /* 1 字节 */
#define WAVE_ST_CH_OFF_BITS (2u) /* 1 字节 */
#define WAVE_ST_CH_OFF_AVAIL (3u) /* 1 字节 = adc_cal_flags(sem) 低 8 位原值，不自造位义 */
#define WAVE_ST_CH_OFF_KQ16 (4u) /* 4 字节 int32 */
#define WAVE_ST_CH_OFF_BCODE (8u) /* 4 字节 int32 */
#define WAVE_ST_CH_BYTES (12u)
/* 本波通道数固定 8（TEMP 不录：理由见 §6.3 末段与 docs/任务规划/数据可信.md §7） */
#define WAVE_ST_CH_NUM (8u)
/* 通道数上限：给二期「带 TEMP 且同时升版本」留位；真正的口径是 meta 里的 ch_count 字段 */
#define WAVE_ST_CH_MAX (9u)
/* 每通道点数默认（= 预触发 + 后触发 = 160 + 160；长度是文件里的数据，宏只作默认值） */
#define WAVE_ST_PTS_DEF (320u)
#define WAVE_ST_PRE_DEF (160u)
#define WAVE_ST_FS_DEF (1000u)
#define WAVE_ST_PPC_DEF (20u)
/* 尺寸一律由字段算出，不写死字面量（改通道数/点数时自动跟着走）：
* 头 CRC 覆盖区 = 30 + 12 × ch_count；头 CRC 自身紧随其后 2 字节；数据区自 32 + 12 × ch 起
* ch_count = 8 时：覆盖区 126、整头 128、数据区 5120、整段 5250（§6.3「CRC 覆盖范围」行） */
#define WAVE_ST_HEAD_CRC_POS(ch) ((uint32_t)(WAVE_ST_OFF_TBL) + \
((uint32_t)(ch) * WAVE_ST_CH_BYTES))
#define WAVE_ST_HEAD_BYTES(ch) ((uint32_t)(WAVE_ST_HEAD_CRC_POS(ch)) + 2u)
#define WAVE_ST_DATA_BYTES(ch, pts) ((uint32_t)(pts) * (uint32_t)(ch) * 2u)
#define WAVE_ST_SEG_TOTAL(ch, pts) (WAVE_ST_HEAD_BYTES(ch) + \
WAVE_ST_DATA_BYTES(ch, pts) + 2u)
/* 本波实际值（只给注释与单测引用，代码里一律用上面的参数化形态） */
#define WAVE_ST_HEAD_SZ_CUR (128u)
#define WAVE_ST_SEG_SZ_CUR (5250u)
/* 段目录与轮转（设计说明 §5.2 第三条：只能严格 8.3 短名；目录与 /log 平级、FTP 根下可见）
* 名字形态 = 目录 + 前缀 + 两位十进制 + 扩展名，号 0..99 共 100 个轮转覆盖 */
#define WAVE_ST_DIR "/wave"
#define WAVE_ST_PFX "WAVE"
#define WAVE_ST_EXT ".BIN"
#define WAVE_ST_SEG_MAX (100u)
#define WAVE_ST_PATH_MAX (17u) /* /wave/WAVE00.BIN = 16 字符 + 结束符 = 17 字节 */
/* CRC-16/MODBUS：多项式 0x8005 反射形态 = 0xA001、初值 0xFFFF、异或输出 0、低字节在前 */
#define WAVE_ST_CRC_POLY (0xA001u)
#define WAVE_ST_CRC_INIT (0xFFFFu)
#define WAVE_ST_CRC_XOROUT (0x0000u)
/* 自检锚点：串 123456789 的 CRC（§6.3 首行钉的常量） */
#define WAVE_ST_CRC_CHECK (0x4B37u)
/* ===== 二、返回码（int 通道；调用方必须接住或显式 (void)，不得裸丢） ===== */
#define WAVE_ST_OK (0) /* 成功 */
#define WAVE_ST_DONE (1) /* 打包游标：整段已产完（不是错误） */
#define WAVE_ST_E_PARAM (-1) /* 空指针 / 容量不足 / 字段非法 */
#define WAVE_ST_E_CRC (-2) /* CRC 不符（头或数据区）：整段判废 */
#define WAVE_ST_E_FORMAT (-3) /* 魔数不符 / 版本不认识 / 表内语义号不等于下标 */
#define WAVE_ST_E_SIZE (-4) /* 长度为 0 或长度与头部字段矛盾：整段判废 */
#define WAVE_ST_E_RANGE (-5) /* 列号 / 点下标 / 段号越界 */
#define WAVE_ST_E_STATE (-6) /* 状态错：未封存就读、未 start 就步进、缺数据源 */
#define WAVE_ST_E_NAME (-7) /* 文件名不是本层命名形态（扫目录重建段账时用） */
/* ===== 三、类型 ===== */
/* 触发源（§6.2 偏移 12 的取值；0 表示「无触发」，只出现在段外的状态查询里） */
typedef enum {
WAVE_TRIG_NONE = 0, /* 无 */
WAVE_TRIG_MANUAL = 1, /* 手动（UI「手动录波」确认，task-2 接线） */
WAVE_TRIG_PROTECT = 2, /* 保护启动（App/algo/prot_elm.c 的 picked 上升沿） */
WAVE_TRIG_BENCH = 3 /* bench 定周期自抓（只在 DTU_BENCH 构建里有这条来路） */
} wave_trig_src_t;
/* 折算档位（§6.2 偏移 22；单位一律以头里的 eng 为准，PC 不许按当前固件口径猜） */
typedef enum {
WAVE_ENG_PIN = 0, /* 引脚域（未标定；V0.1 产品构建停在这档） */
WAVE_ENG_SEC = 1, /* 二次值 */
WAVE_ENG_PRI = 2 /* 一次值 */
} wave_eng_t;
/* 通道表一路的内存形态（字段序 = §6.2 通道表字节序） */
typedef struct {
uint8_t sem; /* 语义号（adc_semantic_t 值；必须等于表内下标，§6.3） */
uint8_t conv; /* 来源转换器（adc_source_t 值：0 = TPAFE，1 = STM32） */
uint8_t bits; /* 转换器输出位宽（TPAFE 16 / STM32 12） */
uint8_t avail; /* 可用性 = adc_cal_flags(sem) 低 8 位原值（不自造位义） */
int32_t k_q16; /* 封存瞬间生效系数：µV/码 × 65536，就是 LSB */
int32_t b_codes; /* 封存瞬间生效零点偏移：码值 */
} wave_ch_desc_t;
/* 段头元数据 = 固定头 + 通道表的内存形态。
* 这是「待编码的段头」，不是「已写盘的证据」：打包游标只读它、不改它。 */
typedef struct {
uint16_t fs_hz; /* 采样率 Hz（从文件读出来的数据，不是编译期常量） */
uint8_t pts_per_cycle; /* 每周波点数 */
uint8_t ch_count; /* 通道数（本波 8） */
uint16_t pts_per_ch; /* 每通道点数（本波 320） */
uint16_t pre_pts; /* 预触发点数（本波 160；回放画触发光标用） */
uint8_t trig_src; /* 触发源（wave_trig_src_t） */
uint8_t trig_elm; /* 触发元件序号（prot_elm 实例下标；手动与定时为 0） */
uint32_t t0_ms; /* 段首相对上电毫秒 */
uint32_t wall; /* 对时后的 epoch 秒（未对时 0） */
uint8_t eng; /* 折算档位（wave_eng_t） */
uint8_t flags_seq; /* bit s = 语义通道 s 的 ADC_CAL_F_VALID（§6.3） */
uint16_t clip_mask; /* bit s = 语义通道 s 的 ADC_CAL_F_CLIPPED（V0.1 恒 0xE6） */
uint32_t frame_seq; /* 段首帧序号（与串口周期行的 frames 对账） */
wave_ch_desc_t ch[WAVE_ST_CH_MAX]; /* 通道表（前 ch_count 项有效） */
} wave_seg_meta_t;
/* 打包游标阶段（对外只用于「已搬完」判定与观测日志；推进全在 wave_store_pack_next 内部） */
typedef enum {
WAVE_PACK_IDLE = 0, /* 未初始化 */
WAVE_PACK_HEAD = 1, /* 正在产头（固定头 + 通道表 + 头 CRC） */
WAVE_PACK_DATA = 2, /* 正在产数据区（按通道分列，一列一列产） */
WAVE_PACK_TAIL = 3, /* 只剩数据区 CRC 两字节 */
WAVE_PACK_DONE = 4 /* 整段已产完 */
} wave_pack_phase_t;
/* 数据源回调：把「第 a_ch 列、段内第 a_from 点起的 a_cnt 个点」取进 p_dst。
* 返 回 值：实际拷贝的点数（等于 a_cnt 表示全给到）；负 = 错误码 int32_t
* 只允许读已封存区：本层不提供、也不允许任何跨任务读活缓冲的路径
* （设计说明 §5.2 第一条陷阱：App/algo/sample_ring.c 的 sample_ring_window() 无临界区，
* 本波不复用它，跨任务只传「已封存」标志）。
* 生产实现 = wave_ring_read_cb()（签名一致，可直接传给 wave_store_pack_start）。 */
typedef int32_t (*wave_reader_fn)(void *p_user, uint8_t a_ch, uint32_t a_from,
uint32_t a_cnt, int16_t *p_dst);
/* 打包游标：段文件字节流的「拉模式」状态机。
* 为什么拉模式 + 小缓冲：defaultTask 是文件系统唯一写者，落盘窗口几十毫秒量级，
* 一次心跳最多一段；整段驻留 RAM 既超预算也没必要（设计说明 §7）。
* 游标不校验写回字节数 —— 那是调用方对着 f_write 做的事（§5.2 第二条陷阱：本移植
* f_write 簇分配失败会返 FR_OK + 短写、没有错误码，必须靠比对写回字节数判失败）。 */
typedef struct {
uint8_t phase; /* wave_pack_phase_t */
uint8_t ch; /* 数据区当前列 */
uint16_t head_done; /* 头区已产出字节数（含头 CRC 两字节） */
uint16_t ch_done; /* 当前列已产出点数 */
uint8_t tail_done; /* 尾部数据 CRC 已产出字节数（0..2） */
uint8_t rsv; /* 补齐用，保持结构体偶数字节 */
uint16_t crc_data; /* 数据区运行 CRC（增量中间值，避免整段驻留） */
uint32_t total; /* 整段期望字节数 */
uint32_t sent; /* 已产出字节数（= 下一片的文件偏移） */
wave_seg_meta_t meta; /* 段头快照（start 时拷入；搬运期间调用方改自己那份不影响） */
wave_reader_fn p_reader; /* 数据源；NULL = 只产头 */
void *p_user; /* 数据源上下文 */
} wave_pack_ctx_t;
/* ===== 四、CRC-16/MODBUS（无表位运算） ===== */
/*
* 函数功能：CRC-16/MODBUS 增量计算（输入输出均低位在前）
* 入口参数：a_crc 上一次的中间值（首次传 WAVE_ST_CRC_INIT）
* p_data 数据指针（NULL 且 a_len = 0 视为空操作，原样返回 a_crc）
* a_len 字节数
* 返 回 值：新的中间值（写文件时低字节在前，见 §6.3 首行） uint16_t
* 限定条件：任意上下文（含 adcTask 之外的 defaultTask / uiTask）；纯计算、无静态状态、
* 不碰外设、不取临界区
* 函数说明：为什么自带实现 —— 全仓没有可复用的 CRC-16 表（依据见本文件头注）。
* 无表 = 零新增表 RAM 与表 Flash；数据区 5120 字节每字节 8 次移位，在 168 MHz
* 上量级是几十微秒，且只在 defaultTask 的落盘链上出现，不在 1 kHz 采集链上。
*/
uint16_t wave_store_crc_update(uint16_t a_crc, const uint8_t *p_data, uint32_t a_len);
/*
* 函数功能：CRC-16/MODBUS 一次算完（从初值起步）
* 入口参数：p_data 数据指针
* a_len 字节数
* 返 回 值：CRC uint16_t
* 限定条件：任意上下文。p_data 为 NULL 或 a_len = 0 时返回 WAVE_ST_CRC_INIT —— 这是
* 空输入的定义值，不是「算好的段 CRC」：零长度一律判废，调用方必须先判长度
* （设计说明 §6.2 末行：长度为 0 → 整段作废）
*/
uint16_t wave_store_crc(const uint8_t *p_data, uint32_t a_len);
/*
* 函数功能：CRC 自检 —— 用规范锚点验算实现是否仍是 CRC-16/MODBUS
* 入口参数：无
* 返 回 值：WAVE_ST_OK 相符；WAVE_ST_E_FORMAT 不符（实现或编译配置被改坏） int
* 限定条件：任意上下文；开机或首次落盘前调一次即可，不在每拍路径上
* 函数说明：锚点 = 串 123456789 的 CRC = 0x4B37（§6.3）。这条是机器可执行的口径锚，
* 防的是「自算自验永远相符」：只有对已知常数才咬得住（换机、换编译器、
* 反射方向写反都在这里暴露）。落盘前失败就自弃本段并计入 err（§9 观测行）。
*/
int wave_store_crc_selftest(void);
/* ===== 五、段头编解码 ===== */
/*
* 函数功能：把段头元数据填成本波默认值（只填格式侧的静态事实）
* 入口参数：p_meta 输出（调用方持有的结构；本层不返回静态地址）
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针 int
* 限定条件：任意上下文；不碰文件系统
* 函数说明：填 fs_hz = 1000、pts_per_cycle = 20、ch_count = 8、pts_per_ch = 320、
* pre_pts = 160，以及通道表的 sem = 下标 + conv / bits 按两片转换器
* （UA / UN / IA 走 TPAFE 16 位；UB / UC / IB / IC / IN 走片内 ADC 12 位 ——
* 通道归属口径属主是 docs/硬件平台/ADC通道映射说明.md，本函数只是它的抄本，
* 单测里对 0xE6 的算术交叉验证会同时钉住这套顺序）。
* 不填 avail / k_q16 / b_codes / trig_* / t0_ms / wall / eng / flags_seq /
* clip_mask / frame_seq：那些是封存瞬间的事实，必须由调用方现取现填
* （adc_cal_k_q16 / adc_cal_flags / sys_clock / wave_ring），本层不链它们。
*/
int wave_store_meta_init(wave_seg_meta_t *p_meta);
/*
* 函数功能：把段头元数据编码成段文件头字节流（固定头 + 通道表 + 头 CRC，全小端）
* 入口参数：p_meta 段头元数据（只读）
* p_out 输出缓冲
* a_cap 缓冲容量（须不小于按 ch_count 算出的整头字节数）
* 返 回 值：不小于 0 = 实际写入字节数；负 = WAVE_ST_E_* int
* 限定条件：任意上下文；无静态缓冲、可重入；不碰文件系统
* 函数说明：编码前先自检字段一致性 —— ch_count 为 0 或越界、pts_per_ch = 0、
* pre_pts 大于 pts_per_ch、表内语义号不等于下标（§6.3「通道表序与列序」那条
* PC 侧判据在编码侧同样成立）一律拒绝：不把坏头写成看起来像样的文件。
*/
int wave_store_head_build(const wave_seg_meta_t *p_meta, uint8_t *p_out, uint32_t a_cap);
/*
* 函数功能：把段文件头字节流解回元数据，并做全套判废检查（魔数 / 版本 / 长度 / 表序 / 头 CRC）
* 入口参数：p_buf 头字节流
* a_len 可读字节数
* p_meta 输出元数据（判废时内容不保证有效，调用方不得消费）
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针或缓冲不足；WAVE_ST_E_FORMAT 魔数 / 版本 /
* 表序不符；WAVE_ST_E_SIZE 零长度或长度与字段矛盾；WAVE_ST_E_CRC 头 CRC 不符 int
* 限定条件：任意上下文（uiTask 与 defaultTask 都可调）。UI 与 PC 侧必须用同一套判废语义：
* 解不过就只能显示「该段不可读」，绝不允许退化画一条直线
* （设计说明 §8.1 空态行：画直线等于伪造证据）
* 函数说明：a_len 不足「按头里 ch_count 推出来的整头长度」时按缓冲不足返回，不猜没读到
* 的字节；ver 不等于魔数第三字节、或不等于 WAVE_ST_VER 一律判废。
*/
int wave_store_head_parse(const uint8_t *p_buf, uint32_t a_len, wave_seg_meta_t *p_meta);
/* ===== 六、整段校验与长度 / 偏移换算（读侧） ===== */
/*
* 函数功能：整段镜像自检 —— 头 + 数据区 + 数据 CRC 三道全过才算「这一段可读」
* 入口参数：p_img 整段文件镜像（调用方已读进内存）
* a_len 镜像长度
* p_meta 输出段头（可为 NULL）
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针；WAVE_ST_E_SIZE 长度为 0 或与期望总长不符；
* WAVE_ST_E_CRC 任一 CRC 不符；WAVE_ST_E_FORMAT 头本身判废 int
* 限定条件：任意上下文；只在整段驻留（本波 5250 字节）时用。回放页不要走这条 ——
* 用 wave_store_head_parse + wave_store_data_off + wave_store_crc_update 分段查，
* 才符合 §7 的 256 字节读窗预算
* 函数说明：这是「段文件 CRC 不符时脚本必须拒绝而不是画出东西」那条判据在板侧的同一份
* 实现，也是本层与 PC 解码器逐字节同解的对照物（两套主机单测互验）。
*/
int wave_store_seg_check(const uint8_t *p_img, uint32_t a_len, wave_seg_meta_t *p_meta);
/*
* 函数功能：按头部字段算整段文件应有的字节数（写侧记账与读侧长度判废共用）
* 入口参数：p_meta 段头元数据
* 返 回 值：期望字节数（8 路 320 点 = 5250）；字段非法（含零长度）返回 0 uint32_t
* 限定条件：任意上下文
* 函数说明：返回 0 就是「这一段连长度都不成立」，据此判废。不要拿 0 去开缓冲，
* 也不要拿 0 去比对 f_write 的写回字节数（那会把失败读成成功）。
*/
uint32_t wave_store_seg_size(const wave_seg_meta_t *p_meta);
/*
* 函数功能：整头字节数（固定头 + 通道表 + 头 CRC 两字节）
* 入口参数：a_ch_count 通道数
* 返 回 值：字节数；通道数为 0 或越界返回 0 uint32_t
* 限定条件：任意上下文
*/
uint32_t wave_store_head_bytes(uint8_t a_ch_count);
/*
* 函数功能：数据区某一点在段文件里的绝对偏移（按通道分列 → 单通道是一整段连续区）
* 入口参数：a_ch_count 通道数
* a_pts_ch 每通道点数
* a_ch 列号（= 通道表下标 = 语义号，0 到 a_ch_count-1）
* a_pt 段内点下标（0 到 a_pts_ch-1）
* 返 回 值：文件偏移；参数非法返回 0xFFFFFFFFu 哨兵（这个值不是任何合法偏移） uint32_t
* 限定条件：任意上下文
* 函数说明：回放页据此定位「只读那一路」，配合 wave_store_data_bytes_avail 一次连续读；
* PC 侧同一算法，两份实现互验。
*/
uint32_t wave_store_data_off(uint8_t a_ch_count, uint16_t a_pts_ch,
uint8_t a_ch, uint32_t a_pt);
/*
* 函数功能：从某点起当前列还能连续读多少字节（不跨列、不越段尾）
* 入口参数：a_pts_ch 每通道点数
* a_pt 起始点下标
* a_want 想读的点数
* 返 回 值：可连续读字节数 = 2 × 实际可给点数；参数非法返回 0 uint32_t
* 限定条件：任意上下文
*/
uint32_t wave_store_data_bytes_avail(uint16_t a_pts_ch, uint32_t a_pt, uint32_t a_want);
/*
* 函数功能：把段文件读出的小端字节解码成 int16 点序列（按时间序，旧到新）
* 入口参数：p_raw 原始字节（来自文件，2 × 点数）
* a_len 字节数（须为偶数，且不大于 a_max_pts × 2）
* p_out 输出 int16 数组
* a_max_pts 输出容量（点数）
* p_pts 输出实际点数（可为 NULL）
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针 / 奇数字节 / 容量不足 int
* 限定条件：任意上下文
* 函数说明：显式按小端逐字节拼装，不依赖宿主字节序，所以板端与 PC 侧同一判据。
* 片内 ADC 那几路的值本就是 0..4095 的原样正数，不做中点偏置
* （§6.3「样本编码」行：加偏置等于伪造双极性）。
*/
int wave_store_le_decode(const uint8_t *p_raw, uint32_t a_len,
int16_t *p_out, uint32_t a_max_pts, uint32_t *p_pts);
/*
* 函数功能：把一路的 int16 码值折成定点毫单位（回放页峰值标注用；纯整数，不用 float）
* 入口参数：p_desc 该路通道表项（k_q16 / b_codes 来自段文件头，不来自当前固件）
* a_code 原始码值
* p_milli 输出四舍五入后的毫单位（k_q16 是 µV/码 → 输出单位 mV）（不可为 NULL）
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针 int
* 限定条件：任意上下文（只在回放页与单测里用，不在 1 kHz 采集链上；内部用 int64 中间量，
* 落在这条路径上时可接受）
* 函数说明：算式 eng = (code + b) × k × 1e-6，与 App/algo/adc_cal.c 的 adc_cal_apply()
* 同一模型（§6.3）。输出单位是 mV；单位含义由段头 eng 字段决定（eng = 0 是
* 引脚域，别读成二次值）。必须用段文件里的 k / b，不许拿当前固件的系数解释
* 老文件（§12 风险表「标定落地后老文件被解释错」）。
*/
int wave_store_code_to_milli(const wave_ch_desc_t *p_desc, int16_t a_code,
int32_t *p_milli);
/* ===== 七、打包游标（分次搬运，给文件系统唯一写者） ===== */
/*
* 函数功能：初始化打包游标（段头拷进游标，随后逐次拉整段字节流）
* 入口参数：p_ctx 游标（调用方持有，栈上或静态都行；本层不记它的地址）
* p_meta 段头元数据（内部拷贝；搬运期间调用方改自己那份不影响本段）
* p_reader 数据源回调；NULL = 只产头（回放页只校验头 / 主机单测只测头）
* p_user 数据源上下文（生产传 NULL，wave_ring 是单例不需要）
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针；WAVE_ST_E_FORMAT 段头字段非法；
* WAVE_ST_E_SIZE 算不出合法长度 int
* 限定条件：任意上下文（纯计算，无临界区）；一段一个游标，搬完再 start 下一段
* 函数说明：p_reader 为 NULL 而 ch_count 大于 0 时，游标仍能产头，但进数据区那一步
* 返回 WAVE_ST_E_STATE —— 不静默跳过数据区，否则调用方会写出一个
* 「长度看着对、内容是空的」段文件（那正是 §8.1 要防的伪造证据形态）。
*/
int wave_store_pack_start(wave_pack_ctx_t *p_ctx, const wave_seg_meta_t *p_meta,
wave_reader_fn p_reader, void *p_user);
/*
* 函数功能：取整段字节流的下一片（分次搬运的唯一推进口）
* 入口参数：p_ctx 已 start 的游标
* p_out 输出缓冲
* a_cap 本片容量（建议 256 字节，见 §7；数据区不切半点，奇数容量会少产 1 字节）
* p_len 输出本片实际字节数（不可为 NULL）
* 返 回 值：WAVE_ST_OK 产出本片且还有后续；WAVE_ST_DONE 整段已产完（*p_len 可为 0）；
* 负 = WAVE_ST_E_*（未 start / 容量为 0 / 数据源回调返错 / 游标状态错） int
* 限定条件：任意上下文，但同一游标不得并发使用（文件系统唯一写者单线程推进）
* 函数说明：头区字节流与 wave_store_head_build 完全一致（内部同一份写字段函数）；
* **头那一步要求 a_cap 不小于整头字节数**（本波 8 路 = 128），否则返回
* WAVE_ST_E_PARAM 且不推进游标——不拆着头给，是为了让游标不必存 128 字节
* 中间态；§7 的 256 字节搬运缓冲天然满足。
* 数据区 CRC 走增量中间值，整段最后两片是数据 CRC 的低字节、高字节。
* 调用方每写完一片都必须比对 f_write 写回字节数，短写按失败处理（§5.2）。
*/
int wave_store_pack_next(wave_pack_ctx_t *p_ctx, uint8_t *p_out,
uint32_t a_cap, uint32_t *p_len);
/*
* 函数功能：读游标已产出字节数（= 当前文件偏移；供记账、观测与「写没写全」判定）
* 入口参数：p_ctx 游标
* 返 回 值：已产出字节数；p_ctx 为 NULL 返回 0 uint32_t
* 限定条件：任意上下文（只读）
*/
uint32_t wave_store_pack_offset(const wave_pack_ctx_t *p_ctx);
/*
* 函数功能：读游标对应整段文件的期望总长（写完与 f_size / 累计写回字节数比对）
* 入口参数：p_ctx 游标
* 返 回 值：期望总字节数；p_ctx 为 NULL 返回 0 uint32_t
* 限定条件：任意上下文（只读）
*/
uint32_t wave_store_pack_total(const wave_pack_ctx_t *p_ctx);
/* ===== 八、段文件名轮转（只算名字，不碰文件系统） ===== */
/*
* 函数功能：按段号生成段文件路径（严格 8.3 短名：目录 + 前缀 + 两位十进制 + 扩展名）
* 入口参数：p_out 输出缓冲（容量须不小于 WAVE_ST_PATH_MAX）
* a_cap 容量
* a_idx 段号 0 到 WAVE_ST_SEG_MAX-1
* 返 回 值：不小于 0 = 写入的字符数（不含结束符；当前布局恒为 16，故缓冲至少要 17 字节）；
* WAVE_ST_E_PARAM 空指针或容量不足；
* WAVE_ST_E_RANGE 段号越界 int
* 限定条件：任意上下文；纯字符拼装（不用 sprintf，见 CODE-RULE-06 系），逐字节可预期
* 函数说明：号 0..99 轮转覆盖，共 100 个名字，写满回绕盖最老的（§5.2 第三条）。
* 本函数不检查文件是否存在、不建目录：那些都是接线道的职责。
*/
int wave_store_seg_path(char *p_out, uint32_t a_cap, uint8_t a_idx);
/*
* 函数功能：下一个轮转段号（到 99 后回 0）
* 入口参数：a_idx 当前段号（越界输入按 0 处理，不猜）
* 返 回 值：下一个段号 uint8_t
* 限定条件：任意上下文
*/
uint8_t wave_store_next_idx(uint8_t a_idx);
/*
* 函数功能：从文件名或路径反解段号（掉电后靠扫目录重建段账用）
* 入口参数：p_path 路径或纯文件名（只看最后一段，大小写都收）
* p_idx 输出段号（不可为 NULL）
* 返 回 值：WAVE_ST_OK；WAVE_ST_E_PARAM 空指针；WAVE_ST_E_NAME 不是本层命名形态 int
* 限定条件：任意上下文
* 函数说明：只认「前缀 + 两位数字 + 扩展名」，其余（目录名、长名、以点开头）一律判不匹配
* —— 扫目录重建账时不许把陌生名字当录波段；名字/参数类错误码严禁升级成卷操作
* （docs/架构设计/STM32F4-Base存储架构说明.md §10.1 的同一条教训）。
*/
int wave_store_idx_from_name(const char *p_path, uint8_t *p_idx);
#ifdef __cplusplus
}
#endif
#endif /* WAVE_STORE_H */
App/app/README.md
+1 -1
View File
@@ -7,7 +7,7 @@
| 文件 | 作用 |
|---|---|
| `app_main.c/h` | **应用初始化入口 `app_main_init`**：时间子系统优先 → RS485 → NAND → ADC → 诊断（在 `osKernelStart` 之前执行） |
| `app_cfg.h` | **功能模块编译开关**（裁剪测试套件/模块用） |
| `app_cfg.h` | **功能裁剪的决策占位说明**——2026-10-22 起**不含任何宏**（原 3 个 `APP_*_ENABLE` 零消费点，已删；接回方法见该文件修改记录 v1.2） |
| `sys_events.h` | **系统就绪事件定义**（CMSIS-RTOS v2 Event Flags：`SYS_EVT_NET_READY` / `SYS_EVT_STORAGE_READY` / `SYS_EVT_FTP_READY` / `SYS_EVT_TIMESYNC_READY` 及命令位） |
## 初始化顺序（`app_main_init`）
App/app/app_cfg.h
+12 -33
View File
@@ -1,47 +1,26 @@
/*
* 模块名称：Application Configuration
* 模块功能：应用层全局配置宏（**预留占位，当前均未接线**）
* 模块功能：功能裁剪开关的决策占位说明（**本头文件当前不提供任何宏，也不被任何 .c 包含**）
* 适用平台：STM32F407ZGTx
* 作者：王建锋
* 创建日期：2026-07-19
* 修改记录：
* v1.0 2026-07-19 王建锋 创建初始版本
* v1.1 2026-10-04 王建锋 P2-12：下列宏此前被表述为"功能模块使能开关"，但全库
* 零代码引用（grep 仅本文件有定义）——"开关名存实亡"会
* 误导评审者以为模块可裁剪。现如实标注为**预留占位**：
* 当前**不门控任何代码**，各模块一律编译进产品。是否/
* 如何接线取决于产品定义（docs/任务规划/README.md §2 阶段 B0），
* 确认后再在真实初始化点（如 app_main.c 的 rs485_init /
* tpafe5160_init）加门控；在此之前**不要**把它们当开关用。
* v1.1 2026-10-04 王建锋 如实标注三个 APP_*_ENABLE 为"未接线占位"（全库零消费点）
* v1.2 2026-10-22 王建锋 收口（登记簿 C5）：删除 4 个零消费点的宏
* （APP_NET_ENABLE / APP_ADC_ENABLE / APP_RS485_ENABLE /
* APP_SYS_TIME_SRC）。留"看起来能裁剪、其实不生效"的宏比不留更糟：
* 评审者会误信模块可裁剪，而关掉它们不会产生任何编译期效果。
* 需要真实门控时（产品定义 B0 落定后），在真实初始化点接入并**在本
* 文件登记**，同时接回 App/app/app_main.c 的 include；在此之前
* 本模块一律编译进产品（各外设的常驻事实见
* docs/环境与部署/项目部署环境要求.md §3.2）。
* 注意：本文件不是 App/app/README.md 里说的"编译开关"，那行已同步更正。
*/
#ifndef APP_CFG_H
#define APP_CFG_H
#ifdef __cplusplus
extern "C" {
#endif
/*
* 系统时钟源选择（**预留占位，未接线**）
* 0 - DWT CYCCNT（当前实现：console_log.c 直接使用 DWT，未读本宏）
* 1 - TIM2（未实现）
* 说明：本宏当前无任何消费点；实际的"与时间源无关硬上界"由 console_log.c 内联
* 使能 DWT 实现，不经过本宏。
*/
#define APP_SYS_TIME_SRC 0
/*
* 功能模块"预留开关"（**当前均未接线，不门控任何代码**）
* 三个宏一律保持定义（= 模块编译进产品）；它们**不产生任何编译期效果**，
* 仅作为产品定义（B0）落定后接入真实门控的占位锚点。
*/
#define APP_NET_ENABLE
#define APP_ADC_ENABLE
#define APP_RS485_ENABLE
#ifdef __cplusplus
}
#endif
/* 故意不提供任何宏：功能裁剪当前不存在。理由与接回方法见上方修改记录 v1.2。 */
#endif /* APP_CFG_H */
App/app/app_main.c
+112 -42
View File
@@ -12,24 +12,29 @@
*/
#include "app_main.h"
#include "app_cfg.h"
#include "main.h" /* ST_DIR4_GPIO_Port / ST_DIR4_Pin 等 CubeMX 宏 */
#include "stm32f4xx_it.h" /* fault_handler_enable() */
#include "usart.h" /* huart5 */
#include "tim.h" /* htim3：1 kHz 采样节拍（TIM3 更新中断触发 CONVST + TRGO 触发 ADC1） */
#include "adc.h" /* adc1_disable()：挂 DMA 前把 ADC 关掉，让 Start_DMA 自己使能 */
#include "rs485.h"
#include "sb_link.h" /* 屏板链路传输层：sb_link_init()（USART1 收中断，批 1 的 1-3） */
#include "sd2506.h"
#include "boot_stats.h" /* 开机账本：上电次数（RTC 用户 SRAM）+ 本次复位原因快照（道G task-12） */
#include "sys_clock.h"
#include "gd5f2gq5ue.h"
#include "tpafe5160.h"
#include "adc_input.h" /* L1 采集层：adc_input_init()（语义映射 + STM32 ADC1 扫描） */
#include "phasor.h" /* L2 相量层：phasor_init()（系数表 + 实例 + 双区交换） */
#include "freq.h" /* L2 派生量：freq_init()（相位解缠绕测频，B8） */
#include "prot_set.h" /* L3 定值模型：prot_set_init()（B5，内核前封存） */
#include "prot_elm.h" /* L3 元件框架：prot_elm_init()（B5，解析相量索引） */
#include "adc_input.h" /* 语义取数与有效性层：adc_input_init()（语义映射 + STM32 ADC1 扫描） */
#include "adc_cal.h" /* 标定折算层：adc_cal_init()（ROM 系数 + cfg 两段注册，道A 标定折算与落盘整定） */
#include "run_par.h" /* 运行参数段：run_par_init()（[run_par] 注册 + 104 地址映射真源，道D 这一项） */
#include "iec104_comm.h" /* [comm] 段：iec104_comm_init()（ca/端口注册，道G task-8） */
#include "phasor.h" /* 全周傅氏相量层：phasor_init()（系数表 + 实例 + 双区交换） */
#include "freq.h" /* 全周傅氏相量的派生量：freq_init()（相位解缠绕测频，B8） */
#include "prot_set.h" /* 保护判据定值模型：prot_set_init()（B5，内核前封存） */
#include "prot_elm.h" /* 保护判据元件框架：prot_elm_init()（B5，解析相量索引） */
#include "sys_log.h"
#include "task_watchdog.h" /* task_wd_seg_report()：round 8 复位不丢"进段打点"上报 */
#include "task_watchdog.h" /* task_wd_seg_report()：第 8 轮复位不丢"进段打点"上报 */
#include "test_config.h" /* 套件开关：身份戳的构建变体串（FW_BUILD_VARIANT）依赖本头，
* 改 TEST_SUITE_* / ENABLE_DESTRUCTIVE_TESTS 必重编本 TU →
* __DATE__/__TIME__ 随之刷新，见 app_main_init() 的戳注释 */
@@ -74,23 +79,11 @@ volatile uint32_t g_rcc_csr_latched;
* 兜底，两者同时置位时报告看门狗更有价值）。纯 ASCII，防编码坑。
*/
static void reset_cause_str(uint32_t csr, char *buf, unsigned int len) {
const char *cause;
if ((csr & RCC_CSR_IWDGRSTF) != 0u) {
cause = "IWDG (independent watchdog)";
} else if ((csr & RCC_CSR_WWDGRSTF) != 0u) {
cause = "WWDG (window watchdog)";
} else if ((csr & RCC_CSR_SFTRSTF) != 0u) {
cause = "software (NVIC_SystemReset)";
} else if ((csr & RCC_CSR_PORRSTF) != 0u) {
cause = "power-on (POR)";
} else if ((csr & RCC_CSR_PINRSTF) != 0u) {
cause = "external pin (NRST)";
} else if ((csr & RCC_CSR_BORRSTF) != 0u) {
cause = "brown-out (BOR)";
} else {
cause = "unknown";
}
/* 优先级链**不在这里再写一遍**：改由 boot_stats 出一份（IWDG > WWDG > 软件 >
* POR > PIN > BOR）。原先这条 if-else 链与页面上要显示的编码各写一份，两份早晚
* 会漂——漂了的症状是串口说 "IWDG"、屏幕写 "software"，两条却都"看着有据"。
* 顺序本身的理由见本函数上方原注释与 App/util/boot_stats.h 的函数头。 */
const char *cause = boot_stats_cause_str(boot_stats_cause_from_csr(csr));
/* 简单有界拼接（不引 snprintf，避免依赖与栈开销） */
if (buf == NULL || len == 0u) {
@@ -116,7 +109,7 @@ static void reset_cause_str(uint32_t csr, char *buf, unsigned int len) {
* 1) 时间子系统（SD2506 RTC → 墙钟基准）
* 2) RS-485
* 3) GD5F NAND
* 4) TPAFE5160 ADC → ADC 输入层（L1，语义映射 + STM32 ADC1）
* 4) TPAFE5160 ADC → ADC 输入层（语义取数与有效性，语义映射 + STM32 ADC1）
* 5) SD2506 诊断信息
* 6) 启动 TIM3 1 kHz 采样节拍（ISR 内脉冲 CONVST；同一更新事件经 TRGO 硬件触发 ADC1 + DMA）
*/
@@ -130,14 +123,14 @@ int app_main_init(void) {
/* 日志引擎初始化（创建待发队列；须先于任何 syslog_post） */
(void)syslog_mcu_init();
/* 启动锚点（2026-10-02 S10）：本函数在内核启动前执行、不创建任何 RTOS 对象，
/* 启动锚点（2026-10-02 加）：本函数在内核启动前执行、不创建任何 RTOS 对象，
* 恒成功且无副作用；本行是"启动进度轨迹"的起点——之后的每一步都有结果日志，
* 故某次启动卡死时，最后一行日志即可指向卡住的步骤。 */
DBG_INFO("boot: syslog init OK");
/* 固件身份戳（2026-10-10）：__DATE__/__TIME__ 由编译器展开，与前面的字面量做
* C 字符串拼接 → .rodata 里是一段连续 ASCII，可直接在 .hex 里原样搜到。
* 用途：@test 把"芯片里正在跑的镜像"和"刚编出来的镜像"对上号。此前开机标记
* 用途：/serial-boot-test 把"芯片里正在跑的镜像"和"刚编出来的镜像"对上号。此前开机标记
* 全是固定串（App init OK / Network Init / ...），旧镜像也照样全中，于是
* "反复重下载、芯片一直是旧镜像"这类事故在自动闭环里完全不可见
* （AGENTS.md 烧录铁律记的正是它）。代价：1 条 DBG ≈ 90 B Flash + 30 B 常量。
@@ -165,10 +158,10 @@ int app_main_init(void) {
}
}
/* 0b) round 8 取证：上报上一轮 defaultTask 主循环的**最后进段**。
/* 0b) 第 8 轮取证：上报上一轮 defaultTask 主循环的**最后进段**。
* 轨迹槽在 .noinit（scatter UNINIT_CCM），IWDG/引脚复位不清 SRAM →
* 误复位后开机第一时间可见 `PREVRUN seg=N`，直接指向主循环阻塞点
* （round 7 观察"判定分支未执行"经 round 8b 更正：真因是 IWDG 超时被静默
* （第 7 轮观察"判定分支未执行"经第 8b 轮更正：真因是 IWDG 超时被静默
* 配成复位默认值，见 docs/子系统设计/看门狗设计说明.md 2026-10-02 变更记录）。
* 裸 UART 直发，且一次复位只报一次（内部清 magic）。 */
task_wd_seg_report();
@@ -177,29 +170,58 @@ int app_main_init(void) {
* 1) 时间子系统初始化（尽早完成，后续所有日志带时间戳）
* sd2506_init() 从 RTC 读取初始时间
* sys_clock_init() 将 RTC 时间转为 Unix epoch，建立墙钟基准
* S10（2026-10-02）：sd2506_init 原先所有失败路径静默返回，是启动段
* 启动段可观测性（2026-10-02 加）：sd2506_init 原先所有失败路径静默返回，是启动段
* 唯一无日志的初始化；现内部已逐路径打 DBG_ERROR，此处再补一行
* 带错误码的结果回执，使 I2C 不通时能看到"在哪一步、什么错"。
*/
{
int rtc_ret = sd2506_init();
bsp_err_t rtc_ret = sd2506_init();
DBG_INFO("SD2506 init: %s (ret=%d)",
(rtc_ret == SD2506_OK) ? "OK" : "FAILED", rtc_ret);
(rtc_ret == BSP_OK) ? "OK" : "FAILED", rtc_ret);
/* 1b) 开机账本（道G task-12）：紧接 sd2506_init 之后，是**唯一**的调用点。
* 为什么放这儿而不是 defaultTask 的存储 bring-up：
* ① 这一步只做 1 次 I2C 读 + 至多 1 次 I2C 写，落在内核启动前——
* 单线程、非 ISR、调度器还没跑（本函数不调任何创建类内核 API，
* AGENTS「内核前禁调创建类 API」那条与此无关）；
* ② 保持介质是 RTC 用户 SRAM，不是文件系统：不必等 STORAGE_READY，
* 也就不必在喂狗点上碰卷锁（这条链上根本没有卷操作可言）；
* ③ sd2506_init 失败时这里自然走"读不到"那一支：状态标成不可信、
* 且不回写，不会把可能还完好的记录覆盖掉。
* 失败一律不打日志（可观测性事件不进 [ERR]），状态留在 boot_stats_get()。 */
boot_stats_init();
}
if (sys_clock_init() != 0) {
syslog_post(SYSLOG_SELFTEST, "clock chip fault");
}
/* 2) RS-485 初始化（UART4 + PD0 方向控制），初始化即自动开启接收 */
/* 2) RS-485 初始化（UART4 + 方向脚 = ST_DIR4 宏：V0.1 板实测 PA15，V0.0 曾是 PD0，
* 轮换记录 = docs/硬件平台/V0.1_网表详细分析报告.md 的 V0.0→V0.1 引脚迁移表），
* 初始化即自动开启接收 */
rs485_init(&g_rs485, &huart4, ST_DIR4_GPIO_Port, ST_DIR4_Pin);
DBG_INFO("RS485 init: OK (UART4, DE=PA15)");
/* 2b) 屏板链路初始化（USART1，700 kbaud 8N1，IDLE 中断接收）。
* 放在 NAND 全片扫描之前：这一步只是挂接收（µs 级），挂上之后屏板的周期召唤
* 就已经能被收下来并计数，台架不必等启动跑完才能看到链路状态。
* 波特率不在本调用里设——在 Src/usart.c 的 USER CODE 区（CubeMX 重生成只保护那里），
* 本调用只做一次交叉核对，对不上会报 BSP_ERR_STATE 并打 ERR 行。 */
{
bsp_err_t sb_ret = sb_link_init(&huart1);
/* BRR 直接读出来打：1-2 的判据是"实测位宽误差 < 1 %"，而 BRR 是位宽的唯一决定量——
* 84 MHz / (16 x 700 kHz) = 7.5 → 期望 0x0078（整数 7、小数 0.5x16 = 8），误差 0 %。
* 有这一行就不必为了核波特率去架示波器：BRR 对不上就说明 USER CODE 覆盖没生效。 */
DBG_INFO("ScreenLink init: %s (ret=%d, USART1 %lu baud, BRR=0x%04lX)",
(sb_ret == BSP_OK) ? "OK" : "FAILED",
sb_ret, (unsigned long)SB_LINK_BAUD,
(unsigned long)huart1.Instance->BRR);
}
/* 3) GD5F 初始化测试（BBT 全片扫描，启动段最耗时的一步） */
int ret = gd5f2gq5ue_init();
DBG_INFO("NAND init: %s",
(ret == GD5F_OK) ? "OK" :
(ret == GD5F_ERROR) ? "ERROR" :
(ret == GD5F_BUSY_TIMEOUT) ? "BUSY TIMEOUT" :
(ret == GD5F_WAIT_EXPIRED) ? "BUSY TIMEOUT" :
(ret == GD5F_ECC_ERROR) ? "ECC ERROR" :
(ret == GD5F_PROGRAM_FAIL) ? "PROGRAM FAIL" :
(ret == GD5F_ERASE_FAIL) ? "ERASE FAIL" :
@@ -209,14 +231,34 @@ int app_main_init(void) {
}
/* 4) TPAFE5160 ADC 测试 */
int tp_ret = tpafe5160_init();
bsp_err_t tp_ret = tpafe5160_init();
DBG_INFO("ADC init: %s",
(tp_ret == TPAFE5160_OK) ? "OK" : "TIMEOUT");
if (tp_ret != TPAFE5160_OK) {
(tp_ret == BSP_OK) ? "OK" :
(tp_ret == BSP_ERR_TIMEOUT) ? "TIMEOUT" :
(tp_ret == BSP_ERR_NO_DEVICE) ? "NO CHIP" : "FAIL");
if (tp_ret != BSP_OK) {
syslog_post(SYSLOG_SELFTEST, "ADC fault");
}
/* 4b) ADC 输入层（L1）初始化：清原始码值缓冲与统计 + **语义映射表自洽性自检**
/* 4b-pre) 挂 DMA 之前**先把 ADC 关掉**，让使能动作由 HAL_ADC_Start_DMA 内部完成
* （它自己 __HAL_ADC_ENABLE + 等 Tstab ~20 µs，然后紧接着开 CR2.DMA 并启流）。
*
* 为什么必须这样做：MX_ADC1_Init() 在 main() 里就调用了，而挂 DMA 在这里，
* 中间隔着 GD5F 全片 BBT 扫描（数秒）。台架实测（同一次开机内用无 DMA 单通道
* 探针取真值对照，9/9 完美置换）：**ADC 使能后闲置数秒才挂 DMA，DMA 乒乓缓冲
* 会整体 +2 格旋转** —— 槽 i 装的是 rank ((i+1) mod 9)+1，9 路通道按 rank 序
* 整体错开 2 位。表象是"接地 AIN2、UB 却读到别的通道的值"，极易被误判成
* 映射表写错或夹子位置不对。
* 把使能与挂 DMA 压到同一时刻后旋转消失（台架 4/4 次，同开机对照差值 ≤4 码）。
* 证据与复现方法见 docs/子系统设计/ADC采样节拍设计说明.md §4.5。
*
* ⚠ 顺序不可调换：本调用必须严格早于下面的 adc_input_init()。
* 若 ADC 在本步之后仍处于使能态，旋转会重新出现。 */
if (adc1_disable() != 0) {
DBG_ERROR("ADC1 disable before DMA arm: TIMEOUT");
}
/* 4b) ADC 输入层（语义取数与有效性）初始化：清原始码值缓冲与统计 + **语义映射表自洽性自检**
* （映射指向了不会被扫描的通道 → 返回 -1，避免"读到恒为陈旧值"的静默错）
* + 挂载一次 STM32 ADC1 的 DMA（失败返回 -2）。
* ADC1 外设已由 MX_ADC1_Init()（main.c）配好 9 通道 / 144 cycles /
@@ -236,19 +278,47 @@ int app_main_init(void) {
}
}
/* 4c) 相量层（L2）初始化：清双区结果与有效标志 + 复位采样环缓冲。
/* 4c) 相量层（全周傅氏相量）初始化：清双区结果与有效标志 + 复位采样环缓冲。
* 纯算法层（无外设 / 无 RTOS 依赖，见 docs/算法/继电保护功能复现规划.md
* §3.2），须在启动采样节拍（步骤 6）之前。幂等、当前无失败路径
* （返回值保留供后续自检扩展）。 */
(void)phasor_init();
DBG_INFO("phasor layer init: OK (inst=%u)", (unsigned)phasor_inst_count());
/* 4c-2) 测频层（L2 派生量，B8）初始化：清平均窗/相位基准/有效标志。
/* 4c-2) 测频层（全周傅氏相量的派生量，B8）初始化：清平均窗/相位基准/有效标志。
* 纯算法（输入 = phasor 使用区），消费在 adcTask（freq_run 每拍）
* 与 protectTask（OF/UF 判据经 prot_elm_run 取数）。 */
(void)freq_init();
DBG_INFO("freq layer init: OK");
/* 4c-3) 通道标定层（标定折算，「数据可信」标定折算与落盘整定）初始化：RAM 系数副本置
* ROM 默认（量程口径冻结定死的引脚侧 LSB，docs/硬件平台/ADC通道映射说明.md §7.1）
* + 向配置引擎注册 [adc_cal] / [adc_cal_ofs] 两段。注册必须先于
* defaultTask 的 cfg_file_load（「先注册后 load」契约）→ 只能落内核前；
* 折算消费在 adcTask 每拍（adc_cal_apply），标定文件值随 load/poll 原地
* 生效，无回调。 */
adc_cal_init();
DBG_INFO("adc cal init: OK (k_q16 tpafe=%ld stm32=%ld)",
(long)ADC_CAL_K_Q16_TPAFE, (long)ADC_CAL_K_Q16_STM32);
/* 4c2) 运行参数段初始化（「数据可信」这一项）：死区 9 点工厂默认 + 注册
* [run_par] 段。同 adc_cal 的「先注册后 load」契约 → 必须内核前；
* 104 消费（COV 实时读 / 0x8020 段读写映射）在 iec104Task 启动后进行。 */
run_par_init();
DBG_INFO("run par init: OK (db9 k/b via adc_cal, evt=1<<8)");
/* 4c3) 通讯参数段初始化（道G task-8，「UI 补齐」第 5 项非 UI 前置）：ca/端口
* 工厂默认 + 注册 [comm] 段。与 adc_cal / run_par 同「先注册后 load」契约
* → 必须内核前：defaultTask 在 storage_bring_up 里才做 net_cfg_load →
* cfg_file_load（引擎唯一读点），本注册必须排在它前面。生效语义 =
* 改后重启（iec104Task 启动读 getter，不挂回调，见 iec104_comm.h）。 */
if (iec104_comm_init() != 0) {
DBG_ERROR("comm init FAIL (dup/full?) - file values inactive");
} else {
DBG_INFO("comm init: OK (ca=%u port=%u)",
(unsigned)iec104_comm_ca(), (unsigned)iec104_comm_port());
}
/* 4d) 保护定值 + 元件层初始化（B5）：出厂默认定值封存校验和 + 元件状态
* 复位并解析相量索引（须在 phasor_init 之后）。内核前完成 → iec104
* 定值读/protectTask 首拍前定值必已装载。判据消费在 protectTask。 */
@@ -289,8 +359,8 @@ int app_main_init(void) {
/* 6) 启动 1 kHz 采样节拍：TIM3 更新事件 → ① ISR 内脉冲 CONVST（Src/main.c）
* ② 同一事件经 TRGO 硬件触发 STM32 ADC1 一轮 9 通道转换（DMA 自动搬运）。
* ⚠ 必须在 tpafe5160_init() 成功之后启动，否则 ISR 会在驱动首帧自检
* （E-44 有效性探针）期间乱发 CONVST。消费端 adcTask 退化为纯消费者。
* ⚠ 节拍源 v2.0 由 TIM6 改为 **TIM3**：F4 上 ADC1 的外部触发只认
* （有效性探针）期间乱发 CONVST。消费端 adcTask 退化为纯消费者。
* ⚠ 节拍源必须能触发 ADC1，故用 **TIM3**：F4 上 ADC1 的外部触发只认
* TIM1/TIM2/TIM3/TIM4/TIM5/TIM8 的 CC 或 TRGO，**TIM6/TIM7 的 TRGO 只接
* DAC**（查 CubeMX DB 与本仓库 stm32f4xx_hal_adc.h 的 EXTSEL 表证实）
* → 要让两片转换器由同一个硬件事件驱动，节拍源必须换成 TIM3。 */
App/app/app_main.h
+8
View File
@@ -17,6 +17,14 @@ extern "C" {
#include <stdint.h>
/*
* 复位原因锁存影子（定义于 app_main.c）。Src/main.c 在 HAL_Init() 之后、串口/日志
* 尚未就绪时读 RCC->CSR 并清标志，这里提供引用契约——原先写成 main.c 函数内的局部
* extern（跨文件裸 extern，改名/删除都不会有提示）。读→清两步的顺序约束见 main.c
* 该段注释，不可调换。
*/
extern volatile uint32_t g_rcc_csr_latched;
int app_main_init(void);
void app_main_run(void);
App/app/sys_events.h
+8 -3
View File
@@ -22,11 +22,12 @@ extern "C" {
* 由 MX_FREERTOS_Init 在 freertos.c 的 generated 区域自动声明并 osEventFlagsNew 创建） */
extern osEventFlagsId_t sys_evtHandle;
/* 各子系统"就绪"事件位（32 位上限内的 bit 0~30） */
/* 各子系统"就绪"事件位（32 位上限内的 bit 0~30）。**bit0 / bit1 在用，bit2 / bit3 是预留位**
* ——逐位的生产者与消费者对照表 = docs/架构设计/项目启动顺序管理.md §3.2 */
#define SYS_EVT_NET_READY (1u << 0) /* netTask：net_init + PHY 稳定完成 */
#define SYS_EVT_STORAGE_READY (1u << 1) /* defaultTask：FTL/FatFS 挂载完成 */
#define SYS_EVT_FTP_READY (1u << 2) /* ftpTask：lftpd_start 完成 */
#define SYS_EVT_TIMESYNC_READY (1u << 3) /* timeSyncTask：首次时间同步完成 */
#define SYS_EVT_FTP_READY (1u << 2) /* ftpTask：lftpd_start 完成后置位；暂无消费者（预留） */
#define SYS_EVT_TIMESYNC_READY (1u << 3) /* 预留：timeSyncTask 在跑但不置本位，生产者消费者都没有 */
#define SYS_EVT_NET_RECONFIG (1u << 4) /* UI：请求立即应用新网口配置（netTask 消费后重建网络） */
#define SYS_EVT_CFG_SAVE (1u << 5) /* UI：网口配置保存请求（defaultTask = 配置引擎属主，消费并写盘） */
#define SYS_EVT_CONSOLE_TX (1u << 6) /* 控制台单写者：生产者入环形缓冲后置位，defaultTask 消费并发送
@@ -34,6 +35,10 @@ extern osEventFlagsId_t sys_evtHandle;
#define SYS_EVT_PROT_SET_SAVE (1u << 7) /* 保护定值落盘请求（B7）：iec104Task 检测到定值脏置位，
* defaultTask（配置引擎属主）消费并写 /prot_set.bin
* （消费型命令位；写盘失败脏标志保留 → 下轮再通知重试） */
#define SYS_EVT_RUN_PAR_SAVE (1u << 8) /* 运行参数段落盘请求（「数据可信」这一项）：iec104Task
* 检测到 run_par 脏（死区 9 键 / 系数覆盖联动 [adc_cal]）
* 置位，defaultTask 消费并 cfg_file_save 整档外科保存
* （消费型命令位；失败脏保留 → 下轮重试，B7 同款） */
#ifdef __cplusplus
}
App/app/ui_data_feed.c
+857
View File
@@ -0,0 +1,857 @@
/*
* 模块名称：UI 数据组装器（ui_data_feed）
* 模块功能：App → UI 数据通道的写侧——按节拍从采集/标定/相量/测频/保护/协议/墙钟
* 各模块取数，组装成 docs/UI设计/UI_数据供给设计说明.md §4 契约的三帧
* （实时量 rt / 参数 par / 装置信息 info），经 Drivers/BSP/UI/ui_data.h
* 的发布 API 推给 UI 层；本模块是快照的**唯一填充者**，不含任何布局、
* 格式化与 LVGL 调用（显示规格全在页面行表，同文档 §8）
* 写方向（道F task-1）：同一条 tick 顺带把页面投递的定值整定请求落定——
* ui_data_param_drain() 每轮取一条，执行动作经本文件的 s_param_ops
* （locked = prot_set_locked / check = g_prot_set_meta 上下限 /
* apply = prot_set_set_sealed）注入给 BSP；值域与落盘事实都留在 App
* 侧，BSP 只有队列与状态机（契约 §6.1"UI 不能直写"的落地形态）
* 量纲诚实性：eng 字段按**真值**填——docs/任务规划/数据可信.md §2.6 把承诺边界定在
* "引脚电压"，故未做两点标定前 eng = UI_DATA_ENG_PIN（值 = ADC 引脚电压 V，
* 不是端子二次值）；电气 8 路 adc_cal_flags() 的 VALID 全置位才升
* UI_DATA_ENG_SEC。TEMP 按决策不参与线性标定 → 恒带 UI_DATA_Q_RAW，
* 页面据此不挂单位（三态口径同文档 §4.2）
* 适用平台：STM32F407ZGTx（PC 模拟器不链接本文件，见 ui_data_feed.h 端接法）
* 作者：王建锋
* 创建日期：2026-10-25
* 修改记录：
* v1.0 2026-10-25 王建锋 创建（道E task-14）
* v1.1 2026-10-26 DTU 项目组 道F task-1：① tick 前置 ui_data_param_drain()
* （定值写路径出队 → 闭锁/越界预检 → set_sealed，
* 见 s_param_ops）；② 参数帧尾填 cal_block（未标定
* 闭锁徽标，三路口径同 protect_task.c，不用 eng）
* v1.3 2026-10-27 DTU 项目组 道F task-7：遥测整定注入表（ui_data_yt_ops_t）
* v1.4 2026-10-27 DTU 项目组 道G task-9：通讯参数注入表（ui_data_comm_ops_t，
* 通讯设置页）；port_104 快照从 IEC104_SERV_PORT 宏
* 切 iec104_comm_port() 真源（宏同笔删除，交接口径见
* IEC104上行设计说明.md §8）
* 装配层实现 + 首轮懒绑（时序与通道四绑定等价，
* 见 feed_yt_bind_once 函数头）；行数等值由编译期
* 守卫钉，量纲分档与合法域分档同源同序
* v1.2 2026-10-26 DTU 项目组 道F task-16：删除本地镜像 feed_cal_block()，
* 两个调用点（填帧 / 门控比较）改调
* adc_cal_prot_blocked()——同一份三路判定此前在
* 本文件与 protect_task.c 各写一遍，且各自带一份
* #ifndef DTU_BENCH（只给单个 TU 加宏就能让屏与判据
* 分叉）；真源现落在 App/algo/adc_cal.c，旁路全仓一处。
* 行为不变（判定式逐字同构、调用时机不变）
*/
/* 头文件包含区 */
#include <string.h>
#include "cmsis_os.h" /* osKernelGetTickCount：与 adc_task 同一 ms 时基 */
#include "boot_stats.h" /* 运行报告：上电次数 + 本次复位原因快照（道G task-12 数据面） */
#include "iec104_serv.h" /* 运行报告：四个 104 只读观测计数（本次开机以来，跨重连不清零） */
#include "ui_data_feed.h"
/* 日志锚点：本文件只在"点表点数与快照点数不等"这一条静默漂移上打一条一次性日志
* （每条约 90 B Flash，见 AGENTS「日志不是免费的」——常规发布路径刻意一条都不加）。
* ⚠ DBG_TAG 必须在 include 之前定义：dbg_log.h 的 DBG_ERROR 是宏，漏 include 时
* ARMCC 只把 DBG_ERROR 当隐式声明函数放过编译期，错误落在链接期（L6218E
* Undefined symbol），比漏写头文件本身更难归因 */
#define DBG_TAG "[UIDATA]"
#include "dbg_log.h"
/* 下层（Drivers/BSP）：快照存侧 + 两个端口/用户名常量来源（App → BSP 是合法方向） */
#include "ui_data.h"
#include "ui_net_sink.h" /* UI_NET_SINK_PORT：远程显示（RemoDispBus）监听端口 */
#include "ftp_cfg.h" /* FTP_CFG_USER_MAX / ftp_cfg_get() */
/* 同层（App）数据源 */
#include "adc_input.h" /* ADC_SEM_COUNT / adc_input_raw（TEMP 码值） */
#include "adc_cal.h" /* adc_cal_flags：VALID/CLIPPED 三态可用性；adc_cal_prot_blocked：未标定闭锁单点；adc_cal_k_uv：系数当前生效值（与 104 回显同视图） */
#include "run_par.h" /* 道F task-7 遥测整定注入表：死区/合法域/系数 setter/脏位（真源全在本模块与 adc_cal，feed 只转达） */
#include "phasor.h" /* 基波/谐波有效值（fAmSQ） */
#include "freq.h" /* 测频读数与新鲜度 */
#include "prot_elm.h" /* 元件动作态（遥信位图来源） */
#include "prot_set.h" /* 40 项定值 Q10 + 校验和 + 闭锁 + 越界位图 */
#include "sys_clock.h" /* 墙钟字符串 */
#include "iec104_comm.h" /* 道G task-9：[comm] 真源 getter/setter/脏位；快照端口切 getter，IEC104_SERV_PORT 字面宏同笔删除 */
#include "iec104_pts.h" /* task-15 批4：遥信点数与单/双点性质（点表事实的唯一来源） */
/* 私有宏定义区 */
/* 实时帧与信息帧发布节拍（ms）；参数帧只在定值校验和变化时发布
* （节拍依据 docs/UI设计/UI_数据供给设计说明.md §5.2） */
#define FEED_RT_PERIOD_MS 200u
/* 遥信位号：**与 App/protocol/iec104/iec104_pts.c 板端源的位图同源**（该文件把
* 位号写死在函数体内、未导出，UI 侧不得 include 协议头，故在此镜像一份）。
* 变更纪律：104 点表位号改动时必须同步这里 + 页面名表 + 主机一致性测试
* （test/host/ui_data 的位图断言）。V0.1 有硬件来源的只有以下 6 位，
* 其余 27 位恒无效（开入未实现）；过压/欠压/过频/低频四个元件在
* V0.1 点表里没有对应遥信点，故本函数不产出。 */
#define FEED_YX_BIT_FAULT_ALL 14u /* YX15 故障总（任一电压/电流段或零序动作） */
#define FEED_YX_BIT_OC1 15u /* YX16 过流 I 段 */
#define FEED_YX_BIT_OC2 16u /* YX17 过流 II 段 */
#define FEED_YX_BIT_OC3 17u /* YX18 过流 III 段 */
#define FEED_YX_BIT_OL 22u /* YX23 过载（过负荷） */
#define FEED_YX_BIT_LOCK 30u /* YX31 保护闭锁（定值校验和自检失败） */
/* YX1~4（bit0..3）是开关位置类双点点，V0.1 无开入硬件 → 恒 0 且不在有效位图内，
* 因此本文件不为它们定义常量（定义了也不参与任何判定 = 看着像接了线其实没有） */
/* 有效位图：YX15~18/23/31（与 104 点表 YX_VALID_MASK 同集合） */
#define FEED_YX_VALID_MASK ((((uint64_t)1u << FEED_YX_BIT_FAULT_ALL) | \
((uint64_t)1u << FEED_YX_BIT_OC1) | \
((uint64_t)1u << FEED_YX_BIT_OC2) | \
((uint64_t)1u << FEED_YX_BIT_OC3) | \
((uint64_t)1u << FEED_YX_BIT_OL) | \
((uint64_t)1u << FEED_YX_BIT_LOCK)))
/*
* 装置身份（版本类）：仓库内**没有**产品级版本登记表，值沿用页面既有显示值
* （docs/UI设计/内容页架构.md 的装置信息行表现值），有正式口径后只改本段一处。
* ⚠ 软件校验不抄参考项目遗留的 "4454"：构建期没有 CRC 生成步骤，如实显示 "--"
* （处置口径 docs/UI设计/页面扩充详细方案.md §3.7 第 5 行）
*/
#define FEED_MODEL "F30"
#define FEED_SW_VER "SV0.010"
#define FEED_HW_VER "HW0.010"
#define FEED_SW_SUM "--"
/* 编译期一致性守卫（ARMCC C99 无 _Static_assert，用项目惯用的数组宽度法，
* 先例 App/cfg/cfg_file.c 与 Drivers/BSP/UI/ui_menu_tab.h）：
* 快照下标空间与各 App 枚举一旦漂移，编译即失败，不留到运行期
* （契约 docs/UI设计/UI_数据供给设计说明.md §9.4 第 1/2 条） */
typedef char feed_chk_yc_n_t[(UI_DATA_YC_N == (uint32_t)ADC_SEM_COUNT) ? 1 : -1];
typedef char feed_chk_set_n_t[(UI_DATA_SET_N == (uint32_t)PS_ID_COUNT) ? 1 : -1];
/* 写路径注入表的 id 形参是 uint8_t（BSP 侧不透明编号宽度，位图只有 64 位）：
* 定值项数一旦破 64/255，request 的 mask 与 check/apply 的编号都会静默截断，
* 故在写侧也钉一道（BSP 侧同一条守卫在 Drivers/BSP/UI/ui_data.c） */
typedef char feed_chk_set_u8_t[((uint32_t)PS_ID_COUNT <= 64u) ? 1 : -1];
typedef char feed_chk_fuser_t[(UI_DATA_FUSER_LEN >= FTP_CFG_USER_MAX) ? 1 : -1];
/* 静态变量定义区 */
/* 组装缓冲：三帧串行填充，共用一块存储，省两份 RAM。
* 实际最大者是**实时帧**（208 B > par 192 B > info），故给 par 尾追加字段
* 只要不超过 rt 就一字节 RAM 都不多花（这条由主机单测 TC-UIDATA-021g/h 钉住，
* 尺寸一变这里就是唯一会撒谎的地方） */
static union {
ui_data_rt_t rt;
ui_data_par_t par;
ui_data_info_t info;
} s_scr;
/* 语义通道 → 基波相量实例下标缓存（-1 = 该通道无基波实例 → 该路发 IV）；
* 首帧惰性建表（相量实例表是 ROM 表，运行期不变，建一次即可） */
static int8_t s_yc_phasor[ADC_SEM_COUNT];
static uint8_t s_map_done;
/* 发布节拍与参数变化检测状态
* par 帧有**三个各自独立**的变化源，任一变了就要重发一帧（详见 tick 里的门控注释）：
* s_par_sum 定值改动（校验和）
* s_par_locked 定值闭锁（定值校验和自检失配，校验和不动）
* s_par_cal_block 未标定闭锁（两点标定完成，校验和也不动）
* 后两个各占一字节——省下来就是"屏上状态与真值脱拍"这笔债 */
static uint32_t s_last_rt_ms;
static uint32_t s_par_sum;
static uint8_t s_par_sum_valid;
static uint8_t s_par_locked;
static uint8_t s_par_cal_block;
static uint8_t s_first_done;
/* 函数定义区 */
/*
* 函数功能：定长缓冲内拷贝字符串（跨层快照只允许定长数组，禁指针）
* 入口参数：p_dst - 目标缓冲（结构体内数组首地址） char *
* dst_len - 目标容量（含 NUL） size_t
* a_src - 源串（Flash 字面量或上层缓冲） const char *
* 返回值：无
* 限定条件：三者非 NULL 且 dst_len > 0；截断时保证 NUL 结尾
* 函数说明：不用 strcpy/sprintf（门禁 CODE-RULE-06 禁用不安全函数），
* 超长**静默截断**——快照字段本就是定长显示串，截断只会少显示尾部，
* 不会越界；本函数每 200 ms 调用个位数次，不为此加日志
*/
static void feed_copy_str(char *p_dst, size_t dst_len, const char *a_src) {
size_t n;
if ((p_dst == NULL) || (a_src == NULL) || (dst_len == 0u)) {
return;
}
n = strlen(a_src);
if (n > (dst_len - 1u)) {
n = dst_len - 1u;
}
(void)memcpy(p_dst, a_src, n);
p_dst[n] = '\0';
}
/*
* 函数功能：建立"语义通道 → 基波相量实例"映射（首帧一次）
* 入口参数：无
* 返回值：无
* 限定条件：uiTask 上下文，ui_data_feed_tick 首帧前调用
* 函数说明：只认 harm == 1 的实例；一个语义通道有多个基波实例时取**首个**
* （现状 k_inst[] 每通道最多一个基波，取首个即唯一解）。
* UB/UC/IB/IC/IN 无实例（V0.1 硬件削顶：双转换器无共同采样触发）→ 留 -1，该路发 IV
*/
static void feed_map_phasor(void) {
uint8_t n;
uint8_t i;
for (i = 0u; i < (uint8_t)ADC_SEM_COUNT; i++) {
s_yc_phasor[i] = -1;
}
n = phasor_inst_count();
for (i = 0u; i < n; i++) {
const phasor_inst_t *p = phasor_inst(i);
if ((p == NULL) || (p->harm != 1u) || ((uint8_t)p->sem >= (uint8_t)ADC_SEM_COUNT)) {
continue;
}
if (s_yc_phasor[(uint8_t)p->sem] < 0) {
s_yc_phasor[(uint8_t)p->sem] = (int8_t)i;
}
}
s_map_done = 1u;
}
/*
* 函数功能：算整帧量纲口径 eng
* 入口参数：无
* 返回值：UI_DATA_ENG_PIN 或 UI_DATA_ENG_SEC uint8_t
* 限定条件：无（纯读）
* 函数说明：**全或无**——电气 8 路（TEMP 除外，它不参与线性标定）的
* ADC_CAL_F_VALID 全置位才升二次值。取全或无是因为整帧共用一个 eng：
* 只要还有一路是引脚电压，页面挂"二次值"就会把那一路的读数误标
* （宁可整体显示"未标定"，也不给部分真值贴真值标签）
*/
static uint8_t feed_eng(void) {
uint8_t sem;
for (sem = 0u; sem < (uint8_t)ADC_SEM_TEMP; sem++) {
if ((adc_cal_flags((adc_semantic_t)sem) & ADC_CAL_F_VALID) == 0u) {
return UI_DATA_ENG_PIN;
}
}
return UI_DATA_ENG_SEC;
}
/*
* 函数功能：组装遥信双点位图（bit i = 第 i 点是双点型 M_DP）
* 入口参数：无
* 返回值：位图 uint64_t
* 限定条件：uiTask 上下文；点数上限 UI_DATA_YX_N（<64，故位图放得下）
* 函数说明：逐点问点表 `iec104_pts_yx_is_dp()`，**不在此复制"前 4 点是双点"这个事实**
* ——那句话写在这里就是第二真相，点表一改就悄悄错（下发位图的理由见
* ui_data.h 的 yx_dp 字段注释）
*/
static uint64_t feed_yx_dp(void) {
uint64_t m = 0u;
uint8_t i;
for (i = 0u; (i < (uint8_t)UI_DATA_YX_N) && (i < 64u); i++) {
if (iec104_pts_yx_is_dp(i) != 0u) {
m |= ((uint64_t)1u << i);
}
}
return m;
}
/*
* 函数功能：组装遥信位图（bit i = 第 i 点"合/动作"）
* 入口参数：无
* 返回值：位图 uint64_t
* 限定条件：uiTask 上下文（读 protectTask 写的元件状态快照，读侧拷贝语义，
* 与 App/protocol/iec104/iec104_pts.c 板端源同形）
* 函数说明：位号镜像本文件 FEED_YX_BIT_* 一组宏的注释（含同步纪律）；
* 双点遥信 YX1~4 无硬件 → 恒 0 且不在有效位图内
*/
static uint64_t feed_yx_bits(void) {
prot_elm_state_t st;
uint64_t bits = 0u;
uint8_t fault_all;
fault_all = 0u;
prot_elm_state(PE_OC1, &st);
if (st.asserted != 0u) {
bits |= ((uint64_t)1u << FEED_YX_BIT_OC1);
fault_all = 1u;
}
prot_elm_state(PE_OC2, &st);
if (st.asserted != 0u) {
bits |= ((uint64_t)1u << FEED_YX_BIT_OC2);
fault_all = 1u;
}
prot_elm_state(PE_OC3, &st);
if (st.asserted != 0u) {
bits |= ((uint64_t)1u << FEED_YX_BIT_OC3);
fault_all = 1u;
}
prot_elm_state(PE_3U0, &st);
if (st.asserted != 0u) {
fault_all = 1u;
}
if (fault_all != 0u) {
bits |= ((uint64_t)1u << FEED_YX_BIT_FAULT_ALL);
}
prot_elm_state(PE_OL, &st);
if (st.asserted != 0u) {
bits |= ((uint64_t)1u << FEED_YX_BIT_OL);
}
if (prot_set_locked() != 0u) {
bits |= ((uint64_t)1u << FEED_YX_BIT_LOCK);
}
return bits;
}
/*
* 函数功能：组装实时量快照（遥测 9 路 + 相量实例槽 + 遥信 + 频率 + 墙钟）
* 入口参数：p_snap - 目标帧（调用方已清零） ui_data_rt_t *
* tick_ms - 发布时刻（tick 域） uint32_t
* 返回值：无
* 限定条件：uiTask 上下文；映射表已建（feed_map_phasor）
* 函数说明：取数口径与 104 上送同源不同路——本函数读**相量使用区**（1 ms 刷新、
* 双区原子交换），不做死区与平均；遥测链快照（docs/任务规划/数据可信.md
* §4.5 的 meas 快照）落地后，本函数改成读该快照即可，页面零改动
* （这正是本层存在的意义：换数据源只改这里）
*/
static void feed_fill_rt(ui_data_rt_t *p_snap, uint32_t tick_ms) {
uint32_t now_ep;
uint8_t sem;
char ts[UI_DATA_CLOCK_LEN];
p_snap->tick_ms = tick_ms;
p_snap->valid = 1u;
p_snap->eng = feed_eng();
/* 遥测：语义通道序的基波有效值（采样环已按 adc_cal 折算 → 当前为引脚电压域） */
for (sem = 0u; sem < (uint8_t)ADC_SEM_COUNT; sem++) {
int8_t pi = s_yc_phasor[sem];
p_snap->yc[sem].val = 0.0f;
p_snap->yc[sem].qds = 0u;
if (sem == (uint8_t)ADC_SEM_TEMP) {
/* 温度：不参与线性标定，透传转换器码值并打 RAW 位（页面不得挂单位） */
int32_t code = 0;
p_snap->yc[sem].qds = UI_DATA_Q_RAW;
if (adc_input_raw((adc_semantic_t)sem, &code) == 0) {
p_snap->yc[sem].val = (float)code;
} else {
p_snap->yc[sem].qds |= UI_DATA_Q_IV;
}
continue;
}
if (pi < 0) {
/* 无基波实例 = V0.1 该通道无可用采样源（削顶） → 无效 */
p_snap->yc[sem].qds = UI_DATA_Q_IV;
} else {
phasor_t ph;
int rc = phasor_get((uint8_t)pi, &ph);
if (rc == 0) {
p_snap->yc[sem].val = ph.fAmSQ; /* 有效值口径（系数已折 sqrt2/N） */
} else if (rc == -2) {
p_snap->yc[sem].qds = UI_DATA_Q_NT; /* 未攒满一周波 */
} else {
p_snap->yc[sem].qds = UI_DATA_Q_IV;
}
}
if ((adc_cal_flags((adc_semantic_t)sem) & ADC_CAL_F_CLIPPED) != 0u) {
p_snap->yc[sem].qds |= UI_DATA_Q_OV; /* 硬件削顶：交流量不可信 */
}
}
/* 相量实例槽：含谐波（Ia 二次/五次），交流量页的 Ia2/Ia5 行走这条带 */
{
uint8_t n = phasor_inst_count();
if (n > UI_DATA_PH_MAX) {
n = UI_DATA_PH_MAX; /* 超出槽上限的实例本帧不发布（现 5 实例，余 3 槽） */
}
p_snap->ph_n = n;
for (sem = 0u; sem < UI_DATA_PH_MAX; sem++) {
p_snap->ph[sem].val = 0.0f;
p_snap->ph[sem].qds = UI_DATA_Q_IV;
}
for (sem = 0u; sem < n; sem++) {
phasor_t ph;
if (phasor_get(sem, &ph) == 0) {
p_snap->ph[sem].val = ph.fAmSQ;
p_snap->ph[sem].qds = 0u;
} else {
p_snap->ph[sem].qds = UI_DATA_Q_NT;
}
}
}
p_snap->yx_bits = feed_yx_bits();
p_snap->yx_valid = FEED_YX_VALID_MASK;
p_snap->yx_dp = feed_yx_dp();
/* 点数漂移检查（只在真漂走时打一条日志）：点表 YX_N 与本层 UI_DATA_YX_N 一旦不等，
* 页面按 33 行画、协议按另一个数上送，两边都"看起来正常"——这是静默错，值得花一条
* DBG（约 90 B Flash）换一次现场可见的自证；只打一次不刷屏（同丢弃计数口径） */
{
static uint8_t s_yx_n_bad;
uint8_t n = iec104_pts_yx_count();
if ((n != (uint8_t)UI_DATA_YX_N) && (s_yx_n_bad == 0u)) {
s_yx_n_bad = 1u;
DBG_ERROR("yx point count drift: pts=%u ui_name_table=%u",
(unsigned)n, (unsigned)UI_DATA_YX_N);
}
}
/* 测频：读数新鲜度单独走 freq_valid()（幅值门 + 收敛），两者任一不成立
* 页面即显示 "--"——eng=0 期间幅值门恒失效，读数本就不可消费，如实反映 */
{
float hz = 0.0f;
p_snap->freq_valid = 0u;
p_snap->freq_hz = 0.0f;
if (freq_get(&hz) == 0) {
p_snap->freq_hz = hz;
if (freq_valid() != 0u) {
p_snap->freq_valid = 1u;
}
}
}
/* 墙钟：UINT32_MAX 是 sys_clock_get() 的失败哨兵 → clock_ok=0、串清空 */
p_snap->clock_ok = 0u;
p_snap->clock[0] = '\0';
now_ep = sys_clock_get();
if ((now_ep != UINT32_MAX) && (sys_clock_get_str(ts, sizeof(ts)) != NULL)) {
feed_copy_str(p_snap->clock, sizeof(p_snap->clock), ts);
p_snap->clock_ok = 1u;
}
}
/* ── 写路径（契约 §6.2）：把 prot_set 的三个动作包成注入给 BSP 的函数表 ────── */
/*
* 函数功能：写路径判定"定值闭锁中吗"（BSP 经 ui_data_param_ops_t 来问）
* 入口参数：无
* 返 回 值：1 - 闭锁（定值校验和自检失败态，禁一切定值写入）；0 - 可写 uint8_t
* 限定条件：uiTask 上下文（只读 prot_set 状态位）
* 函数说明：这里的"闭锁"是**定值闭锁**（= par.locked = YX31 遥信），**不是**未标定
* 闭锁（= par.cal_block）：后者仍可改定值、只是判据停走，两者在屏上不得
* 互认（三词三源口径 docs/任务规划/数据可信.md §4.3 + 落地简报 §7-6）
*/
static uint8_t feed_param_locked(void) {
return prot_set_locked();
}
/*
* 函数功能：写路径整批预检——单项是否落在 meta 上下限内
* 入口参数：a_id - 定值项编号（位图位序；uint8_t 是 BSP 侧不透明编号的宽度）
* a_q10 - 待写 Q10 定点值
* 返 回 值：0 - 合法；-1 - 编号越界或值越界 int
* 限定条件：只读 g_prot_set_meta（ROM 表），任意上下文安全
* 函数说明：上下限**只此一处取**——BSP 行表（Drivers/BSP/UI/ui_w_setview.c）是它的
* 换算镜像，由 setview-check 钩子核一致；本函数再抄一份数字就是第二真相
* （"查看合法、整定越界"两套边界就是这么来的）
*/
static int feed_param_check(uint8_t a_id, int32_t a_q10) {
if (a_id >= (uint8_t)PS_ID_COUNT) {
return -1;
}
if ((a_q10 < g_prot_set_meta[a_id].min) || (a_q10 > g_prot_set_meta[a_id].max)) {
return -1;
}
return 0;
}
/*
* 函数功能：写路径落值——单项**原子**写入 + 重封校验和 + 置脏
* 入口参数：a_id - 定值项编号；a_q10 - Q10 定点值
* 返 回 值：0 - 已写入；-1 - 编号越界或 prot_set 拒写（原值不动） int
* 限定条件：uiTask 上下文；调用前 BSP 已整批预检通过（两条件与本函数一致）
* 函数说明：用 prot_set_set_sealed()（影子拷贝→改→重封→单字交换，**每项自带置脏**，
* 落盘由 defaultTask 50 ms 圈扫脏写 /prot_set.bin，本模块不碰 FatFs）。
* ⚠ 不得改成 prot_set_set() + 批末 prot_set_seal()：两条路径之间有
* "已改未封存"窗口，prot_set.c 明令不得交错，撞上就被定值校验和自检判成
* "定值被非法改写"→ 整台保护闭锁
*/
static int feed_param_apply(uint8_t a_id, int32_t a_q10) {
if (a_id >= (uint8_t)PS_ID_COUNT) {
return -1;
}
return prot_set_set_sealed((prot_set_id_t)a_id, a_q10);
}
/* 注入给 ui_data_param_drain() 的执行侧实现（BSP 不保存副本，每次调用现传） */
static const ui_data_param_ops_t s_param_ops = {
feed_param_locked,
feed_param_check,
feed_param_apply
};
/*
* ======================= 道F task-7：遥测整定注入表（ui_data_yt_ops_t）装配
*
* 两页唯一的执行侧转达处。四条装配纪律：
* ① 数值与合法域**都**现给执行侧（run_par_deadband / run_par_db_range /
* adc_cal_k_uv / RUN_PAR_K_MAX_UV）——本文件不出现任何范围数字字面量；
* 系数真带（µV/码执行段裁）没有公开访问器，也**不在此补一份**（task-43 收口），
* 真带拒的值经 set 原样返 -1，页面反显 + 保存行 ERR，两层守卫互不掩盖。
* ② 写走语义 setter（写值与置脏同一函数内发生，run_par_cal_k_set 文件头契约）；
* 本层不存在"只置脏不写值"或"只写值不置脏"的组合，UI 永远够不到裸脏位。
* ③ 跨任务写口径：真机默认档 = iec104Task 的 C_SE；本文件的调用在 uiTask，
* 这**正是** Lead 裁定（task-7 派发②）批准的"装配层转达"整定路径——与 104
* 走同一批 setter、同一 int32 单字原子契约，不新开工；run_par.h 里死区旧
* 接口"iec104Task 上下文"的限定条件语写于该裁定之前，语义已被裁定覆盖
* （系数两支的限定条件已明写装配层入口，措辞同步归算法层下一笔）。
* ④ 落盘不靠本表：写成功置脏 → defaultTask 每轮无条件 run_par_store_save()
* （查实：唯一 cfg_file_save 调用者，首行"无脏立即返回"；104 的 peek→事件位
* 只是加速器不是必经链）——所以"OK = 盘上真落了"在真机与模拟器（pump 清脏）
* 两端口径一致，黄金参考拍的 WAIT/OK 不是表演。
*/
/* 跨层行数等值守卫：BSP 侧契约值 ↔ 执行侧真值。本文件是全仓第一处两份头
* 同时可见的编译单元——BSP 物理上无法自证（看不到 App 头），守卫落这里 */
typedef char feed_yt_db_n_check_t[(UI_DATA_YT_DB_N == (uint8_t)RUN_PAR_DB_N) ? 1 : -1];
typedef char feed_yt_ch_n_check_t[(UI_DATA_YT_CH_N == (uint8_t)RUN_PAR_CH_N) ? 1 : -1];
/*
* 函数功能：死区点数（执行侧真值直通）
* 入口参数：无
* 返回值：RUN_PAR_DB_N uint8_t
* 限定条件：uiTask（注入表回调）
* 函数说明：行数从这一头出、BSP 契约常量在文件头编译期守卫对表——两边不等
* 编不过，等值不靠注释维持
*/
static uint8_t feed_yt_db_n(void) {
return (uint8_t)RUN_PAR_DB_N;
}
/*
* 函数功能：读第 idx 行死区现状（值 + 粗守域现给；量纲按点型分档）
* 入口参数：idx - 0..8（0..7 电气语义通道序，8 频率） uint8_t
* a_out - 行现状 ui_data_yt_row_t *
* 返回值：0 - 已写出；-1 - 越界 / 指针空（run_par_db_range 自判，本层不重复判） int
* 函数说明：unit 的分档（前 4 电压、中 4 电流、末 1 频率）**必须**与
* run_par_db_range 的档位分档同序——两处真源都没导出量纲，唯一防线是
* run_par.h 地址映射表（0x8030~0x8038 = UA..IN/FREQ）与本表同序这条
* 写死的对表纪律 + 黄金像素（档位漂了屏上会呈现"0~50"配 "A" 的肉眼矛盾）；
* decimals 取 3 = 死区在引擎里的存储分辨率（毫单位 int32，换算单点
* s_milli_to_eng 在 run_par.c，本层不重除）
*/
static int feed_yt_db_row(uint8_t a_idx, ui_data_yt_row_t *a_out) {
float lo;
float hi;
if (run_par_db_range(a_idx, &lo, &hi) != 0) {
return -1;
}
a_out->val = run_par_deadband(a_idx);
a_out->lo = lo;
a_out->hi = hi;
a_out->decimals = 3u;
a_out->unit = (a_idx < 4u) ? UI_DATA_YT_UNIT_V
: ((a_idx < 8u) ? UI_DATA_YT_UNIT_A : UI_DATA_YT_UNIT_HZ);
return 0;
}
/* 函数功能：写第 idx 行死区（直通语义 setter；返回值原样上抛，页面据此记账） int */
static int feed_yt_db_set(uint8_t a_idx, float a_eng) {
return run_par_deadband_set(a_idx, a_eng);
}
static uint8_t feed_yt_cal_n(void) {
return (uint8_t)RUN_PAR_CH_N;
}
/*
* 函数功能：读第 idx 路系数现状（k = adc_cal **当前生效值**，µV/码）
* 返回值：0 - 已写出；-1 - idx 越界或指针空 int
* 函数说明：显示值与 104 C_RD 回显同视图（run_par_104_read 用的就是 adc_cal_k_uv：
* 文件坏值被真带回退 ROM 时，屏与主站看到同一份 ROM——"页面值按比例
* 变化"判据因此量的就是执行段真正吃的数）；
* lo/hi 只有粗守一层（0..RUN_PAR_K_MAX_UV，上限来自 run_par 唯一出口），
* 真带在执行段裁——两层守卫的注释纪律见 ui_w_ytview 头注；
* decimals 取 0 是**显示域容量约束**不是精度偏好：粗守上限 1e9 在
* ui_w_setlist 的 int32 显示域里只够零位小数（带 2 位则上限装不下），
* 屏上输入按整 µV 量化、写口仍收 float；要小数位得收紧粗守或改组件
* 值通道，都不在本批，也不许在此抄一份更小的假上限
*/
static int feed_yt_cal_row(uint8_t a_idx, ui_data_yt_row_t *a_out) {
if ((a_out == NULL) || (a_idx >= (uint8_t)RUN_PAR_CH_N)) {
return -1;
}
a_out->val = adc_cal_k_uv((adc_semantic_t)a_idx);
a_out->lo = 0.0f; /* 下限 0 由写口拒 k<=0 兜住，这里只给输入框边界 */
a_out->hi = RUN_PAR_K_MAX_UV;
a_out->decimals = 0u;
a_out->unit = UI_DATA_YT_UNIT_UV;
return 0;
}
/* 函数功能：写第 idx 路系数 k（越界防御后再进语义 setter——setter 形参是枚举，
* 编译器帮不上越界忙；返回码直通） int */
static int feed_yt_cal_k_set(uint8_t a_idx, float a_uv) {
if (a_idx >= (uint8_t)RUN_PAR_CH_N) {
return -1;
}
return run_par_cal_k_set((adc_semantic_t)a_idx, a_uv);
}
/* 函数功能：未标定闭锁徽标源（task-16 单点访问器，与判据停走同一个判定） uint8_t */
static uint8_t feed_yt_cal_blocked(void) {
return (adc_cal_prot_blocked() != 0) ? 1u : 0u;
}
/* 函数功能：整档落盘脏位（保存行三态判据；与 104 留痕同一个 peek，不另发明） uint8_t */
static uint8_t feed_yt_pending(void) {
return run_par_dirty_peek();
}
/* 遥测整定注入表（八件齐全；ui_data_yt_bind 拒残表，缺件就是装配错） */
static const ui_data_yt_ops_t s_yt_ops = {
feed_yt_db_n,
feed_yt_db_row,
feed_yt_db_set,
feed_yt_cal_n,
feed_yt_cal_row,
feed_yt_cal_k_set,
feed_yt_cal_blocked,
feed_yt_pending
};
/* ======================= 道G task-9：通讯参数注入表（ui_data_comm_ops_t）===
*
* 页面形状（两行的名/序）归 ui_page_comm.c；本层只转达值与合法带——
* lo/hi 现取 iec104_comm.h 带宏（唯一出口），值现取 getter（带内自愈），
* 装配层**不写第二份数值**（通道五同一条纪律）。
*/
/*
* 函数功能：读第 idx 行通讯参数现状（值 + 合法带）
* 入口参数：idx - UI_DATA_COMM_ROW_CA/_PORT uint8_t
* a_out - 行现状 ui_data_comm_row_t *
* 返回值：0 - 已整份写出；-1 - idx 越界（不猜、不顶替） int
* 限定条件：uiTask 页面绘制链（经 ui_data 通道六转发）
*/
static int feed_comm_row(uint8_t a_idx, ui_data_comm_row_t *a_out) {
if (a_idx == UI_DATA_COMM_ROW_CA) {
a_out->val = iec104_comm_ca();
a_out->lo = IEC104_COMM_CA_MIN;
a_out->hi = IEC104_COMM_CA_MAX;
return 0;
}
if (a_idx == UI_DATA_COMM_ROW_PORT) {
a_out->val = iec104_comm_port();
a_out->lo = IEC104_COMM_PORT_MIN;
a_out->hi = IEC104_COMM_PORT_MAX;
return 0;
}
return -1;
}
/*
* 函数功能：写第 idx 行通讯参数（守卫在 setter：带外拒、副本不动、不置脏）
* 返回值：0 - 已写并置脏；-1 - idx 越界或带外拒 int
* 限定条件：uiTask 按键链（编辑提交）
* 函数说明：a_val > 65535 不在此先裁——截断成 u16 会把 65536 洗成 0 再被
* setter 合法拒掉，等于替屏幕编了个假值；越界一律原样送 setter 拒
*/
static int feed_comm_set(uint8_t a_idx, uint32_t a_val) {
if (a_val > 65535uL) {
return -1;
}
if (a_idx == UI_DATA_COMM_ROW_CA) {
return iec104_comm_ca_set((uint16_t)a_val);
}
if (a_idx == UI_DATA_COMM_ROW_PORT) {
return iec104_comm_port_set((uint16_t)a_val);
}
return -1;
}
/* 函数功能：[comm] 段落盘脏位（与页面 WAIT/OK 同一枚 peek，不另发明） uint8_t */
static uint8_t feed_comm_pending(void) {
return iec104_comm_dirty_peek();
}
/* 通讯参数注入表（三件齐全；ui_data_comm_bind 拒残表） */
static const ui_data_comm_ops_t s_comm_ops = {
feed_comm_row,
feed_comm_set,
feed_comm_pending
};
/* 首轮懒绑一次：ui_data_feed_tick() 的首个调用点在 App/task/ui_task.c 里先于
* ui_menu_init()（首帧发布那次），与通道四 ui_data_maint_bind 的绑定时序等价；
* 不在 ui_task.c 直接绑是为了本批写域收在派发单列出的文件里。残表是真故障，
* 必须能在启动日志里看见，不能静默（通道四同口径） */
static uint8_t s_yt_bound;
static uint8_t s_comm_bound; /* 道G task-9 通讯参数表懒绑门（同款先置位防刷日志） */
/*
* 函数功能：组装参数快照（40 项定值 Q10 + 校验和 + 封存态 + 越界位图 + 未标定闭锁）
* 入口参数：p_snap - 目标帧（调用方已清零） ui_data_par_t *
* sum - 本次发布的 prot_set_checksum() 值 uint32_t
* 返回值：无
* 限定条件：uiTask 上下文（读侧；写者 = iec104Task 的 set_sealed 与装载路径，
* 读到的永远是"值区与封存一致"的完整快照）
* 函数说明：只搬 Q10 原值不换算小数位——换算属表现层
* （docs/UI设计/UI_数据供给设计说明.md §8）
*/
static void feed_fill_par(ui_data_par_t *p_snap, uint32_t sum) {
uint8_t i;
p_snap->checksum = sum;
p_snap->valid = 1u;
p_snap->locked = prot_set_locked();
p_snap->bad_mask = prot_set_bad_mask();
/* 越界位图非 0 = 上一次整表装载/提交有越界项（prot_set_bad_mask 的既有口径），
* 页面据此反显；为 0 时无意义位图不参与显示 */
p_snap->bad_valid = (p_snap->bad_mask != 0u) ? 1u : 0u;
/* v2 尾追加：未标定闭锁徽标（与判据停走**同一个判定**：App/algo/adc_cal.c 的
* adc_cal_prot_blocked()，道F task-16 起本文件不再自带一份三路判定——两份实现
* 可以各自漂移，屏上"未标定"就会与判据实际停不走同一件事）。
* ⚠ 不要改回用 rt.eng 反推：eng 要求电气 **8** 路全 VALID，V0.1 双转换器下
* UB/UC/IB/IC/IN 永不置位 → eng 恒为引脚档，照它画徽标就永不解锁；
* 两个谓词各有用途，边界写在 adc_cal.h 的函数头第③条。
* ⚠ 与上面的 locked 是两件事——locked 禁编辑，cal_block 只说明"改了也不会动作" */
p_snap->cal_block = adc_cal_prot_blocked();
for (i = 0u; i < (uint8_t)PS_ID_COUNT; i++) {
p_snap->q10[i] = prot_set_get((prot_set_id_t)i);
}
}
/*
* 函数功能：组装装置信息快照（身份 + 运行时长 + 通讯参数）
* 入口参数：p_snap - 目标帧（调用方已清零） ui_data_info_t *
* tick_ms - 当前 tick（换算 uptime_s 用） uint32_t
* 返回值：无
* 限定条件：uiTask 上下文
* 函数说明：页面不得自己 include 协议/配置头取这些值，一律经本帧下发
* （docs/UI设计/页面扩充详细方案.md §3.5"值必须在 App 侧取"）；
* 公共地址 CA 不在此下发——固件里 CA 是逐帧从 ASDU 头解析的，
* 没有集中常量可取，待 104 侧给出查询点后按扩展规则追加字段
*/
static void feed_fill_info(ui_data_info_t *p_snap, uint32_t tick_ms) {
const ftp_cfg_t *p_ftp = ftp_cfg_get();
boot_stats_t boot;
iec104_serv_stats_t st104;
p_snap->valid = 1u;
p_snap->uptime_s = tick_ms / 1000u;
p_snap->port_104 = iec104_comm_port(); /* 真源 = [comm] RAM 副本（getter 带内恒成立，u16 读原子） */
p_snap->port_disp = (uint16_t)UI_NET_SINK_PORT;
feed_copy_str(p_snap->model, sizeof(p_snap->model), FEED_MODEL);
feed_copy_str(p_snap->sw_ver, sizeof(p_snap->sw_ver), FEED_SW_VER);
feed_copy_str(p_snap->hw_ver, sizeof(p_snap->hw_ver), FEED_HW_VER);
feed_copy_str(p_snap->build_date, sizeof(p_snap->build_date), __DATE__);
feed_copy_str(p_snap->sw_sum, sizeof(p_snap->sw_sum), FEED_SW_SUM);
if (p_ftp != NULL) {
feed_copy_str(p_snap->ftp_user, sizeof(p_snap->ftp_user), p_ftp->user);
} else {
p_snap->ftp_user[0] = '\0';
}
/* 运行报告四数（2026-10-28 UI 补齐）：纯搬运，页面不得自己去 include 这两个头。
* uptime_s 仍由本函数用 tick 差算——boot_stats 不提供时长，别在那里再算一份。 */
boot_stats_get(&boot);
iec104_serv_get_stats(&st104);
p_snap->boot_count = boot.boot_count;
p_snap->boot_seq_state = boot.seq_state;
p_snap->boot_write_failed = boot.write_failed;
p_snap->rst_cause = boot.rst_cause;
p_snap->boot_ready = boot.ready;
p_snap->iec104_conn_up = st104.conn_up;
p_snap->iec104_apdu_tx = st104.apdu_tx;
p_snap->iec104_tx_fail = st104.tx_fail;
p_snap->iec104_rx_bytes = st104.rx_bytes;
}
/*
* 函数功能：装配节拍入口——先落定一条定值整定请求（写方向），再发布实时帧与
* 信息帧（满 200 ms 一次）、参数帧（仅校验和变化时）；首轮立即发布
* （免启动初期出现一闪的 "--"）
* 入口参数：无
* 返回值：无
* 限定条件：uiTask 上下文，主循环每轮一次（UI 循环周期 10 ms）
* 函数说明：每轮未到期时代价 = 一次 osKernelGetTickCount + 两次减法比较 +
* 一次空队列判断（drain 无请求时只是一次计数比较）；
* 差值法吸收 tick 回绕（同 App/algo/adc_health.h 的 now_ms 口径）。
* 写路径失败态（ERR_RANGE/ERR_LOCKED/ERR_BUSY）走屏上通道，不打日志
* （每条 DBG 约 90 B Flash + 216 B 栈，AGENTS「日志不是免费的」）
*/
void ui_data_feed_tick(void) {
uint32_t now;
uint32_t sum;
uint8_t due_rt;
if (s_yt_bound == 0u) {
s_yt_bound = 1u; /* 先置位再绑：失败也不每轮重试刷日志（90 B/条） */
if (ui_data_yt_bind(&s_yt_ops) != 0) {
DBG_ERROR("UI yt bind: FAIL");
}
}
if (s_comm_bound == 0u) {
s_comm_bound = 1u; /* 道G task-9：同款一轮一绑；两表时序等价（先于 ui_menu_init） */
if (ui_data_comm_bind(&s_comm_ops) != 0) {
DBG_ERROR("UI comm bind: FAIL");
}
}
now = osKernelGetTickCount();
if (s_map_done == 0u) {
feed_map_phasor();
}
/* 写路径：先落定整定请求，**再**取校验和——本轮刚写进 prot_set 的定值就进
* 本轮"校验和变化才发"那道门，页面保存行的 OK 与新值同一帧回来，不必多等
* 一轮（10 ms）。顺序反了不出错，只是慢一轮。
* 每轮最多处理一条（ui_data_param_drain 的限定条件）：整定是人工低频事件，
* 一轮一条已经把最坏耗时钉住，不必排空整个队列
* ⚠ 返回值必须显式丢弃：本函数不消费"处理了几条"，但 bsp-err 的
* consume-result 只认接住或 (void) 两种写法（实测编译器与 cppcheck 都不报） */
(void)ui_data_param_drain(&s_param_ops);
sum = prot_set_checksum();
due_rt = 0u;
if ((s_first_done == 0u) || ((uint32_t)(now - s_last_rt_ms) >= FEED_RT_PERIOD_MS)) {
due_rt = 1u;
s_first_done = 1u;
s_last_rt_ms = now;
}
if (due_rt != 0u) {
(void)memset(&s_scr, 0, sizeof(s_scr));
feed_fill_rt(&s_scr.rt, now);
(void)ui_data_publish_rt(&s_scr.rt);
(void)memset(&s_scr, 0, sizeof(s_scr));
feed_fill_info(&s_scr.info, now);
(void)ui_data_publish_info(&s_scr.info);
}
/* 参数帧门控：定值变化是低频事件，不随 200 ms 白拷一帧（契约 §5.2）。
* 但"校验和没变"不等于"页面该看的没变"——本帧里还有两个与校验和无关的事实：
* · locked（定值闭锁）：自检失配时置位，校验和一字不变，
* 而整定页保存行要显示 LOCK 并禁编辑；
* · cal_block（未标定闭锁）：两点标定写完 [adc_cal] 的 valid 就翻转，
* 校验和同样不动，而标题上的"未标定"徽标要当场消失。
* 只盯校验和，这两件事都到不了屏上（真机现象：标定做完了屏上徽标永远挂着，
* 直到某次定值改动才被顺带刷掉——那是把两件不相干的事当同步点）。
* 代价：每轮多两次字节比较（无变化时零拷贝），换来屏上状态与真值同拍 */
{
uint8_t locked_now = prot_set_locked();
uint8_t cal_now = adc_cal_prot_blocked(); /* 标定层单点，与判据同源 */
if ((s_par_sum_valid == 0u) || (sum != s_par_sum)
|| (locked_now != s_par_locked) || (cal_now != s_par_cal_block)) {
(void)memset(&s_scr, 0, sizeof(s_scr));
feed_fill_par(&s_scr.par, sum);
(void)ui_data_publish_par(&s_scr.par);
s_par_sum = sum;
s_par_locked = locked_now;
s_par_cal_block = cal_now;
s_par_sum_valid = 1u;
}
}
}
App/app/ui_data_feed.h
+54
View File
@@ -0,0 +1,54 @@
/*
* 模块名称：UI 数据组装器（ui_data_feed）
* 模块功能：App → UI 数据通道的"写侧"——按节拍从采集/算法/保护/协议/时钟各模块
* 取数，组装成 docs/UI设计/UI_数据供给设计说明.md §4 契约的三帧
* （实时量 rt / 参数 par / 装置信息 info），经 Drivers/BSP/UI/ui_data.h
* 的发布 API 推给 UI 层；本模块是快照的**唯一填充者**
* 适用范围：App/app（装配层：可同时 include 两侧头，方向仍是上层依赖下层，
* scripts/check_layer_deps.py 只拦"Drivers/BSP 目录反向 include App 目录"）
* 线程约定：uiTask 上下文，主循环每轮调 ui_data_feed_tick() 一次；与页面读写同
* 上下文串行 → 无锁（docs/UI设计/UI_数据供给设计说明.md §5.1）。
* ⚠ 不得在 adcTask/protectTask/netTask 里调用本模块
* 端接法：MCU = App/task/ui_task.c 主循环；PC 模拟器**不链接本文件**（模拟器不跑
* 固件装配链，快照由 simulator/main.c 直接发布固定帧保证像素回归可复现，
* 见 docs/UI设计/UI_数据供给设计说明.md §9.2；模拟器豁免登记在
* scripts/check_registration.py 的 SIM_EXEMPT）
* 作者：王建锋
* 创建日期：2026-10-25
* 修改记录：
* v1.0 2026-10-25 王建锋 创建（道E task-14）
* v1.1 2026-10-26 DTU 项目组 道F task-1：tick 兼任定值写路径的落定节拍
* （契约 §6.2；实现见 .c 的 s_param_ops）
*/
#ifndef UI_DATA_FEED_H
#define UI_DATA_FEED_H
#ifdef __cplusplus
extern "C" {
#endif
/*
* 函数功能：装配节拍入口——先落定一条定值整定请求（写方向），再发布实时帧与
* 信息帧（满 200 ms 一次）、参数帧（仅校验和变化时）；首轮立即发布
* （免启动后出现一闪的 "--"）
* 入口参数：无
* 返回值：无
* 限定条件：uiTask 上下文，主循环每轮一次（UI 循环周期 10 ms）；页面"保存"按键
* 与本页节拍同上下文，故写路径的投递/落定之间不需要任何锁
* （Drivers/BSP/UI/ui_data.h 写路径节）
* 函数说明：本函数每轮代价 = 一次 tick 差值比较 + 一次校验和比较 + 一次
* ui_data_param_drain()（队列空时只是一次计数判断）；真正的取数与组装
* 只在到期时发生（docs/UI设计/UI_数据供给设计说明.md §5.2）。
* ⚠ drain 排在取校验和**之前**：本轮写入的定值要在本轮就被"校验和变化
* 才发"那道门看见，页面才能在同一帧里同时显示 OK 与新值
* 内部零阻塞、零堆分配、零日志（日志每条约 90 B Flash + 216 B 栈，
* 200 ms 周期打不起）；整定失败态走屏上通道，不打日志
*/
void ui_data_feed_tick(void);
#ifdef __cplusplus
}
#endif
#endif /* UI_DATA_FEED_H */
App/cfg/README.md
+1 -1
View File
@@ -10,7 +10,7 @@
| `cfg_file.c/h` | **配置引擎核心**：解析 / 查询 / 保存 / 2s 周期 `cfg_file_poll` |
| `cfg_file_store.h` | **存储后端抽象接口**（MCU=FreeRTOS 堆 / 模拟器=宿主堆，共享核心零分配符号） |
| `cfg_file_store_mcu.c` | **MCU 端后端实现**：`/config.ini`（临时名由目标路径同目录推导 + `f_rename` 原子写） |
| `prot_set_store.c/h` | **保护定值持久化胶水（B7）**：`/prot_set.bin` blob 读写（blob 格式/校验/原子装载在 `App/algo/prot_set.c` 纯逻辑层）；装载 = storage bring-up（屏障前），落盘 = defaultTask 消费 `SYS_EVT_PROT_SET_SAVE` |
| `prot_set_store.c/h` | **保护定值持久化胶水**：`/prot_set.bin` blob 读写（blob 格式/校验/原子装载在 `App/algo/prot_set.c` 纯逻辑层）；装载 = storage bring-up（屏障前），落盘 = defaultTask 消费 `SYS_EVT_PROT_SET_SAVE` |
## 设计要点
App/cfg/cfg_file.c
+106 -20
View File
@@ -8,20 +8,28 @@
* 创建日期：2026-09-14
* 修改记录：
* v1.0 2026-09-14 王建锋 创建初始版本（P3：段键表引擎 + net_cfg 集成）
* v1.1 2026-09-18 王建锋 P0-1：临时缓冲改经 cfg_store_alloc（MCU = FreeRTOS 堆），
* v1.1 2026-09-18 王建锋 临时缓冲改经 cfg_store_alloc（MCU = FreeRTOS 堆），
* 移除对 C 库 malloc 的全部依赖（MicroLIB C 堆仅 512B，
* 原 4 处 KB 级 malloc 真机必然失败）；增编译期堆峰值预算
* 校验 + 失败上报自检记录
* v1.2 2026-09-21 王建锋 E-01（错误码传播审计 P0）：超长文件守卫根治——poll 判定
* v1.2 2026-09-21 王建锋 超长文件守卫根治——poll 判定
* 前置到 cfg_store_stat 真实 st.size（旧检查位于截断后的
* len 上恒假=死码，超长文件被截断当有效解析 → 界外静默
* 回工厂默认 → 基线粘住 → 用户配置销毁链）；save 输出上限
* 由 CFG_OUT_MAX 收紧至 CFG_FILE_MAX_LEN；s_write_doc 写盘
* 唯一闸口拒写超长文档；load/poll 超长处置补自检留痕
* v1.3 2026-10-04 王建锋 P2-1：受管键行超 CFG_LINE_TEST_MAX 时拒绝保存——
* v1.3 2026-10-04 王建锋 受管键行超 CFG_LINE_TEST_MAX 时拒绝保存——
* 原实现 Pass1 静默跳过超长行，Pass2 遂在段头补写新 KV 且
* 原文超长行原样保留 → 同一键出现两行（旧值残留、静默截断）
* 函数说明：引擎状态非重入——调用方须收敛同一任务（defaultTask：poll/save，见 P1-3；
* v1.4 2026-10-15 王建锋 生成文档边界余量收口——
* s_gen_document 两处 `off += snprintf(...)` 改检查式（截断即
* 返回 -1，不再跳过缓冲末尾）；注册拒超长键名（≤ 15 字符），
* 使每行 112 字节余量成为可编译期验证的前提
* v1.5 2026-10-25 DTU 项目组 「数据可信」有符号零点类型：新增值类型 CFG_VAL_INT（有符号十进制，
* len 1/2/4 小端补码）——s_decode_int() 用 strtol + ERANGE +
* 宽度上下界校验，s_encode() 带负号输出；负零点偏移从此可
* 干净落盘（动因见 docs/任务规划/数据可信.md §4.4 与 §7 决策 3）
* 函数说明：引擎状态非重入——调用方须收敛同一任务（defaultTask：poll/save；
* 启动期 load 先于任务竞争）；FS 卷并发由 FatFS REENTRANT 卷锁保证
* （见《配置文件设计说明》D15 A+ 方案）
*/
@@ -29,12 +37,14 @@
/* 头文件包含区 */
#include <string.h>
#include <stdlib.h> /* strtoul（键值解码）；堆分配一律走 cfg_store_alloc，禁 malloc */
#include <stdlib.h> /* strtoul / strtol（键值解码）；堆分配一律走 cfg_store_alloc，禁 malloc */
#include <stdio.h>
#include <ctype.h>
#include <errno.h> /* ERANGE：strtol 饱和判别（INT 键解码需要，「数据可信」有符号零点类型） */
#include "cfg_file.h"
#include "cfg_file_store.h"
@@ -63,7 +73,7 @@ static const char s_doc_header[] =
#define CFG_OUT_MAX 5120u /* 保存输出缓冲上限（经 cfg_store_alloc 取，见下方堆峰值预算） */
#define CFG_LINE_TEST_MAX 127u /* 受管键行匹配的行长上限（超长必非受管键行） */
#define CFG_SNAP_MAX 64u /* 变更检测段快照缓冲（挂回调段 data_size 须 ≤ 此值） */
#define CFG_NAME_MAX 16u /* 段名缓冲（15 字符 + NUL） */
#define CFG_NAME_MAX (CFG_FILE_MAX_NAME_LEN + 1u) /* 段名/键名缓冲（15 字符 + NUL） */
#define CFG_HEAP_BUDGET 10240u /* 暂态堆峰值预算：读缓冲(1B NUL) + 输出缓冲之和上限 */
/* 编译期钉死暂态堆峰值：放大 CFG_FILE_MAX_LEN / CFG_OUT_MAX 会先在此编译失败，强制
@@ -259,6 +269,28 @@ static int s_encode(const cfg_key_def_t *p_key, const uint8_t *p_src, char *p_ds
n = snprintf(p_dst, cap, "%lu", v);
break;
}
case CFG_VAL_INT: {
long v = 0L;
unsigned long raw = 0uL;
size_t i;
if (p_key->len != 1u && p_key->len != 2u && p_key->len != 4u) {
return -1;
}
for (i = 0u; i < p_key->len; i++) {
raw |= ((unsigned long)p_src[i]) << (8u * i);
}
/* 小端补码还原为有符号值（两端 long = 32 位：ARMCC 32 位 ARM / MSVC LLP64） */
if (p_key->len == 1u) {
v = (long)(int8_t)(raw & 0xFFuL);
} else if (p_key->len == 2u) {
v = (long)(int16_t)(raw & 0xFFFFuL);
} else {
v = (long)(int32_t)raw;
}
n = snprintf(p_dst, cap, "%ld", v);
break;
}
case CFG_VAL_IP4:
n = snprintf(p_dst, cap, "%u.%u.%u.%u",
(unsigned)p_src[0], (unsigned)p_src[1],
@@ -272,7 +304,7 @@ static int s_encode(const cfg_key_def_t *p_key, const uint8_t *p_src, char *p_ds
case CFG_VAL_STR: {
size_t slen;
/* P3-1：len==0 时 `p_key->len - 1u` 回绕为 SIZE_MAX → memcpy 巨长越界。
/* len==0 时 `p_key->len - 1u` 回绕为 SIZE_MAX → memcpy 巨长越界。
* STR 字段至少 1 字节（含结尾 NUL），len==0 非法，直接拒绝 */
if (p_key->len == 0u) {
return -1;
@@ -325,6 +357,44 @@ static int s_decode_uint(uint8_t *p_dst, size_t len, const char *p_val) {
return 0;
}
/*
* 函数功能：解析有符号十进制值（小端补码写入，「数据可信」有符号零点类型）
* 入口参数：p_dst - 目标字段 uint8_t *
* len - 字段字节数（1/2/4） size_t
* p_val - 值文本（可带 +/- 号） const char *
* 返回值：0 - 成功；-1 - 非法（空/非数字/带后缀/超本宽度范围/strtol 饱和） int
* 限定条件：无
* 函数说明：两端 long = 32 位，strtol 对超范围文本饱和到 LONG_MAX/MIN 并置
* ERANGE（如 "2147483648" 饱和成 INT32_MAX 本身，光比 v>max_v 抓不住），
* 故 ERANGE 与宽度上下界两道都要查；1/2 字节键按 int8/int16 范围收窄
*/
static int s_decode_int(uint8_t *p_dst, size_t len, const char *p_val) {
const long min_v = (len == 1u) ? -128L : ((len == 2u) ? -32768L : (-2147483647L - 1L));
const long max_v = (len == 1u) ? 127L : ((len == 2u) ? 32767L : 2147483647L);
char *p_end = NULL;
long v;
size_t i;
if (len != 1u && len != 2u && len != 4u) {
return -1;
}
if (p_val[0] == '\0') {
return -1;
}
errno = 0;
v = strtol(p_val, &p_end, 10);
if (p_end == p_val || *p_end != '\0' || errno == ERANGE) {
return -1;
}
if (v < min_v || v > max_v) {
return -1;
}
for (i = 0u; i < len; i++) {
p_dst[i] = (uint8_t)(((unsigned long)v) >> (8u * i));
}
return 0;
}
/*
* 函数功能：解析点分 IPv4（"a.b.c.d"，每段 0~255）
* 入口参数：p_dst - 4 字节目标 uint8_t *
@@ -436,6 +506,8 @@ static int s_decode(const cfg_key_def_t *p_key, uint8_t *p_dst, const char *p_va
switch (p_key->type) {
case CFG_VAL_UINT:
return s_decode_uint(p_dst, p_key->len, p_val);
case CFG_VAL_INT:
return s_decode_int(p_dst, p_key->len, p_val);
case CFG_VAL_IP4:
return s_decode_ip4(p_dst, p_val);
case CFG_VAL_MAC:
@@ -457,6 +529,7 @@ static int s_decode(const cfg_key_def_t *p_key, uint8_t *p_dst, const char *p_va
*/
static int s_gen_document(char *p_buf, size_t cap, size_t *p_len) {
size_t off;
int n;
int i;
int k;
size_t hlen;
@@ -480,7 +553,11 @@ static int s_gen_document(char *p_buf, size_t cap, size_t *p_len) {
if (cap < off + 112u) {
return -1;
}
off += (size_t)snprintf(p_buf + off, cap - off, "\r\n[%s]\r\n", p_sec->name);
n = snprintf(p_buf + off, cap - off, "\r\n[%s]\r\n", p_sec->name);
if (n < 0 || (size_t)n >= cap - off) {
return -1;
}
off += (size_t)n;
for (k = 0; k < (int)p_sec->key_count; k++) {
const cfg_key_def_t *p_key = &p_sec->p_keys[k];
@@ -492,7 +569,11 @@ static int s_gen_document(char *p_buf, size_t cap, size_t *p_len) {
if (cap < off + 112u) {
return -1;
}
off += (size_t)snprintf(p_buf + off, cap - off, "%s=%s\r\n", p_key->name, v);
n = snprintf(p_buf + off, cap - off, "%s=%s\r\n", p_key->name, v);
if (n < 0 || (size_t)n >= cap - off) {
return -1;
}
off += (size_t)n;
}
}
*p_len = off;
@@ -538,7 +619,7 @@ static int s_load_file(uint8_t **p_pbuf, size_t *p_len) {
* len - 数据长度 size_t
* 返回值：0 - 成功；-1 - 写失败或超长拒写 int
* 限定条件：p_buf 非空；len ≤ CFG_FILE_MAX_LEN
* 函数说明：E-01 纵深防御——超长文档一旦落盘，下次开机 load 守卫即判损坏、
* 函数说明：纵深防御——超长文档一旦落盘，下次开机 load 守卫即判损坏、
* 整份用户配置连同注释/未知段销毁，故在唯一出口硬性拦截，使
* "引擎永不产出超长 config.ini"成为结构性质（调用者新增路径免疫）
*/
@@ -747,7 +828,7 @@ static int s_surgical(char *p_in, size_t in_len, char *p_out, size_t out_cap, si
char v[80];
/* s_encode 成功返回文本长度（≥1），失败返回 -1：
* 故判成功必须 `< 0` 取反，不能写 `== 0`（恒假，
* 使补写路径沦为死码，见 2026-10-02 L0.5 修复） */
* 使补写路径沦为死码，见 2026-10-02 主机侧纯逻辑单测修复） */
if (s_encode(p_key, (const uint8_t *)s_sections[idx].p_data + p_key->offset,
v, sizeof(v)) >= 0) {
if (s_emit_kv(p_out, out_cap, &off, p_key->name, v) != 0) {
@@ -842,7 +923,7 @@ static int s_surgical(char *p_in, size_t in_len, char *p_out, size_t out_cap, si
* i_sec - 段索引 int
* 返回值：1 - 是受管键；0 - 不是（无 '=' 或键名不匹配） int
* 限定条件：仅比较 '=' 前的键名（大小写无关、剥尾部空白），不解析值
* 函数说明：P2-1 用于"超长行是否落在受管键上"的判定（值可能很长，无法拷入定长缓冲）；
* 函数说明：用于"超长行是否落在受管键上"的判定（值可能很长，无法拷入定长缓冲）；
* 非修改式，故可安全用于仍供 Pass2 原样保留的行
*/
static int s_line_key_managed(const char *p_line, int i_sec) {
@@ -888,9 +969,9 @@ static int s_line_key_managed(const char *p_line, int i_sec) {
/*
* 函数功能：保存 Pass 1——定位段头行号与各受管键行号
* 入口参数：p_in - 原文本（可修改） char *
* 返回值：0 - 成功；-1 - 受管键行超 CFG_LINE_TEST_MAX（拒绝保存，见 P2-1） int
* 返回值：0 - 成功；-1 - 受管键行超 CFG_LINE_TEST_MAX（拒绝保存） int
* 限定条件：行末被 NUL 化且不复原——调用方须传一次性副本
* 函数说明：P2-1（2026-10-04）：受管键行超过 CFG_LINE_TEST_MAX 时**不能**静默跳过
* 函数说明：受管键行超过 CFG_LINE_TEST_MAX 时**不能**静默跳过
* ——Pass2 会因该行未登记而在段头补写新 KV，同时原文超长行原样保留，导致
* 同一键出现两行（旧值残留 + 新值，解析取谁取决于行序）。故此处显式拒绝：
* 返回 -1，调用方中止保存、原文件不动、自检留痕。非受管键的超长行照旧跳过
@@ -952,7 +1033,7 @@ static int s_surgical_pass1(char *p_in) {
}
}
else if (i_cur >= 0) {
/* 超长行（> CFG_LINE_TEST_MAX）：若其键名为本段受管键 → 拒绝保存（P2-1）；
/* 超长行（> CFG_LINE_TEST_MAX）：若其键名为本段受管键 → 拒绝保存；
* 否则按未知内容放过（Pass2 原样保留） */
if (s_line_key_managed(p_line, i_cur) != 0) {
return -1;
@@ -1004,13 +1085,18 @@ int cfg_file_register(const cfg_section_reg_t *p_reg) {
for (k = 0; k < (int)p_reg->key_count; k++) {
const cfg_key_def_t *p_key = &p_reg->p_keys[k];
if (p_key->name == NULL || p_key->len == 0u) {
if (p_key->name == NULL || p_key->len == 0u ||
strlen(p_key->name) >= CFG_NAME_MAX) {
return -1;
}
if (p_key->type == CFG_VAL_UINT &&
(p_key->len != 1u && p_key->len != 2u && p_key->len != 4u)) {
return -1;
}
if (p_key->type == CFG_VAL_INT &&
(p_key->len != 1u && p_key->len != 2u && p_key->len != 4u)) {
return -1;
}
if (p_key->type == CFG_VAL_IP4 && p_key->len != 4u) {
return -1;
}
@@ -1079,7 +1165,7 @@ int cfg_file_load(void) {
}
if (st.size > CFG_FILE_MAX_LEN) {
/* 文件超长 = 损坏：留工厂默认 + 重建模板（E-01：补自检留痕——销毁
/* 文件超长 = 损坏：留工厂默认 + 重建模板（补自检留痕——销毁
* 用户文件属重大事件，仅串口 DBG_ERROR 在现场无调试器时不可追溯） */
if (s_write_template() != 0) {
DBG_ERROR("load: corrupt file, template write FAIL");
@@ -1168,7 +1254,7 @@ int cfg_file_save(void) {
(void)memcpy(p_in1, p_in, in_len + 1u);
if (s_surgical_pass1((char *)p_in1) != 0) {
/* P2-1：受管键行超 CFG_LINE_TEST_MAX → 中止保存（原文件不动）。此类超长行
/* 受管键行超 CFG_LINE_TEST_MAX → 中止保存（原文件不动）。此类超长行
* 只可能来自手工编辑（代码生成的受管 KV 行恒 <127B）；若强行外科保存会
* 产生重复键行，故宁可拒存并留痕，也不静默写坏。 */
cfg_store_free(p_in1);
@@ -1190,7 +1276,7 @@ int cfg_file_save(void) {
return -1;
}
/* E-01：输出上限由 CFG_OUT_MAX(5120) 收紧至 CFG_FILE_MAX_LEN(4096)——
/* 输出上限由 CFG_OUT_MAX(5120) 收紧至 CFG_FILE_MAX_LEN(4096)——
* 旧上限允许把 >4096B 文档合法写盘（= 下一颗雷：下次开机 load 守卫
* 判损坏、整份用户文件连同注释/未知段一起销毁）。超限走下方既有
* 溢出中止路径：原文件不动 + 自检上报，RAM 副本保留（可修复后重试） */
@@ -1256,7 +1342,7 @@ void cfg_file_poll(void) {
{
int i;
/* E-01（2026-09-21 审计 P0）：超长守卫必须基于 cfg_store_stat 的真实
/* 2026-09-21 审计 P0：超长守卫必须基于 cfg_store_stat 的真实
* st.size 且先于 s_load_file——s_load_file 读长钉死 CFG_FILE_MAX_LEN
* （nread ≤ 4096 恒成立），旧检查写在读后的 len 上恒假（死码）：
* 超长文件被截断当有效解析 → 界外段/键静默回工厂默认 → 基线粘住 →
App/cfg/cfg_file.h
+21 -9
View File
@@ -8,11 +8,16 @@
* 创建日期：2026-09-14
* 修改记录：
* v1.0 2026-09-14 王建锋 创建初始版本（P3：段键表引擎 + net_cfg 集成）
* v1.1 2026-09-15 王建锋 属主任务由 netTask 改为 defaultTask（配置引擎单一属主，P1-3）
* v1.2 2026-09-21 王建锋 E-01（错误码传播审计 P0）：超长守卫契约同步——poll 沉降
* v1.1 2026-09-15 王建锋 属主任务由 netTask 改为 defaultTask（配置引擎单一属主）
* v1.2 2026-09-21 王建锋 超长守卫契约同步——poll 沉降
* 后先按真实 st.size 判超长（旧实现查截断后读长恒假）、
* save 输出上限收紧至 CFG_FILE_MAX_LEN、写盘唯一闸口拒写
* 超长；超长处置补自检留痕
* v1.3 2026-10-15 王建锋 新增公开常量
* CFG_FILE_MAX_NAME_LEN（段名/键名上限 15 字符）
* v1.4 2026-10-25 DTU 项目组 「数据可信」有符号零点类型：新增 CFG_VAL_INT 有符号十进制值类型
* （len = 1/2/4，小端补码）——标定零点偏移等负值需有符号
* 落盘，动因与取舍见 docs/任务规划/数据可信.md §4.4
*/
#ifndef CFG_FILE_H
@@ -27,12 +32,16 @@ extern "C" {
#include <stddef.h>
/* 配置文件长度上限（字节）；超过 = 文件损坏，按出厂模板重建
* （load 与 poll 同判，E-01：poll 在读取前基于真实 st.size 判定） */
* （load 与 poll 同判：poll 在读取前基于真实 st.size 判定） */
#define CFG_FILE_MAX_LEN 4096u
/* 引擎可注册段数上限 */
#define CFG_FILE_MAX_SECTIONS 8u
/* 段名 / 键名最大字符数（不含结尾 NUL）；超长的注册描述符被 cfg_file_register 拒绝。
* 该上限是生成文档每行余量（112 字节）可编译期验证的前提，勿放宽 */
#define CFG_FILE_MAX_NAME_LEN 15u
/* 单段键数上限 */
#define CFG_FILE_MAX_KEYS 16u
@@ -45,17 +54,20 @@ extern "C" {
* IP4 ：点分 IPv4 "a.b.c.d"；字段 uint8_t[4]
* MAC ：十六进制 MAC "xx:xx:xx:xx:xx:xx"（分隔符兼容 - 与 .）；字段 uint8_t[6]
* STR ：ASCII 字符串；字段 char[len]（len = 缓冲长度，自动补 NUL）
* INT ：有符号十进制（可带 + / - 号）；len = 目标字段字节数（1/2/4，小端补码，
* 范围按宽度收窄：int8/int16/int32；负值合法，如标定零点偏移）
*/
typedef enum {
CFG_VAL_UINT = 0,
CFG_VAL_IP4,
CFG_VAL_MAC,
CFG_VAL_STR
CFG_VAL_STR,
CFG_VAL_INT
} cfg_val_type_t;
/* 键定义（offset/len 均相对段 RAM 副本起始） */
typedef struct {
const char *name; /* 键名（小写） */
const char *name; /* 键名（小写，≤ CFG_FILE_MAX_NAME_LEN 字符） */
cfg_val_type_t type; /* 值类型 */
size_t offset; /* 字段偏移 */
size_t len; /* 字段长度 */
@@ -63,7 +75,7 @@ typedef struct {
/* 段注册描述符 */
typedef struct {
const char *name; /* 段名（≤ 15 字符） */
const char *name; /* 段名（≤ CFG_FILE_MAX_NAME_LEN 字符） */
void *p_data; /* 段 RAM 副本（模块自有静态区，引擎原地更新） */
const void *p_defaults; /* 工厂默认值（与 p_data 同布局；load 先复位再解析） */
size_t data_size; /* RAM 副本字节数 */
@@ -91,7 +103,7 @@ int cfg_file_register(const cfg_section_reg_t *p_reg);
* 2. 文件缺失 → 按当前 RAM 副本生成出厂模板写盘（首启建文件）
* 3. 文件存在 → 解析：有效键写入 RAM 副本；无效键留工厂默认并留痕
* 4. 文件超长（> CFG_FILE_MAX_LEN）= 损坏 → 工厂默认 + 重建模板
* + 自检留痕（poll 检出运行期超长文件执行同一契约，E-01）
* + 自检留痕（poll 检出运行期超长文件执行同一契约）
*/
int cfg_file_load(void);
@@ -104,7 +116,7 @@ int cfg_file_load(void);
* 值原位改写，缺失段/键补写；文件缺失/损坏 → 按 RAM 副本重建
* 完整文档（含文件头注释）；写盘 = 临时文件 + 原子改名；输出超
* CFG_FILE_MAX_LEN → 拒绝保存返回 -1（原文件不动 + 自检上报，
* 引擎写盘闸口同拒，E-01）
* 引擎写盘闸口同拒）
*/
int cfg_file_save(void);
@@ -117,7 +129,7 @@ int cfg_file_save(void);
* 函数说明：(size, mtime 变更令牌) 相对基线变化且连续 CFG_FILE_SETTLE_CNT
* 次轮询稳定 → 先查 st.size 超 CFG_FILE_MAX_LEN = 损坏 → 工厂默认
* + 重建模板 + 自检留痕（不触发段回调：保留在线修复通道，重启
* 收敛，E-01）；否则重载全部段（各段复位工厂默认后解析）；挂回调
* 收敛）；否则重载全部段（各段复位工厂默认后解析）；挂回调
* 段有差异 → 调用其回调（如触发网络重建）；重载后刷新基线
* （回调触发的写盘不引发二次重载）
*/
App/cfg/cfg_file_store_mcu.c
+20 -8
View File
@@ -9,16 +9,20 @@
* 修改记录：
* v1.0 2026-09-14 王建锋 创建初始版本
* v1.1 2026-09-18 王建锋 增 cfg_store_alloc / cfg_store_free / cfg_store_heap_free：
* 共享核心临时缓冲改走 FreeRTOS 堆（P0-1，MicroLIB C 堆仅 512B）
* 共享核心临时缓冲改走 FreeRTOS 堆（MicroLIB C 堆仅 512B）
* v1.2 2026-09-22 王建锋 原子写修复：rename 前先 unlink 已存在目标——本 FatFs
* 移植 f_rename 不覆盖既有目标（FR_EXIST），旧实现一切
* "目标存在的覆盖写"必然失败（E-01 台架验证暴露）
* "目标存在的覆盖写"必然失败（台架验证暴露）
* v1.3 2026-10-02 王建锋 四个后端函数纳入卷锁 try 语义（vol_lock_wait(0)）：
* 与 ftpTask 的 lftpd 文件操作互斥（并发 FTL 写 →
* dhara journal 竞争实证）；busy 返回 -1 由调用方
* 按既有失败语义处理（poll 保留 RAM/保存待重试），
* 本任务 = 看门狗喂狗点，绝不阻塞等锁
* v1.4 2026-10-05 王建锋 原子写临时文件由 p_path 推导（P3-2）：与目标同目录的
* v1.5 2026-10-24 王建锋 仅注释更正：cfg_store_read 的"限定条件"引用了
* FRESULT 里不存在的 FR_NO_SYSTEM，改成实际会返回的
* FR_NOT_READY / FR_NO_FILESYSTEM 并写明"非 FR_OK 一律
* 转 -1，不要枚举错误码集合"（无行为改动）
* v1.4 2026-10-05 王建锋 原子写临时文件由 p_path 推导：与目标同目录的
* 固定 8.3 名 config.TMP，不再硬编码卷根；目标恒为
* "/config.ini" 时推导结果与旧值逐字节一致
*/
@@ -47,7 +51,15 @@ static const char s_path_tmp[] = "/config.TMP";
* cap - 缓冲容量 size_t
* p_nread - 实际读字节数输出（不可为 NULL） size_t *
* 返回值：0 - 成功；-1 - 文件缺失/读失败 int
* 限定条件：卷已挂载（未挂载时 f_open 返回 FR_NO_SYSTEM，转 -1）
* 限定条件：卷已挂载。未挂载时本函数一律转 -1，但**别照着不存在的错误码去写
* 判据**：Lib/FatFs/ff.h 的 FRESULT 共 20 个码（FR_OK..FR_INVALID_PARAMETER），
* 没有 FR_NO_SYSTEM（旧注释此处笔误，2026-10-24 更正）。本移植里卷未挂载
* 实际返回 FR_NOT_READY(3)（物理驱动器不可用）或 FF_VOLUMES 内无已挂载卷时
* 由 mount_volume 直接给错；卷上无有效 FAT 则返回 FR_NO_FILESYSTEM(13)。
* 本函数（以及 write_atomic / stat / remove）对**任何**非 FR_OK 一律转 -1，
* 所以这些码的差异不影响对外语义——也正因如此，谁都不该去枚举错误码集合，
* 除了自愈触发集那种"必须区分能不能靠删文件修好"的场合（见 sys_log_mcu.c
* 的 s_is_selfheal_code）。
* 函数说明：FIL 为**函数级 static**而非局部——本 FatFs 移植 FF_FS_TINY=0，
* `FIL` 内含 `buf[FF_MAX_SS]`=512 B（Lib/FatFs/ff.h），一个局部对象就吃掉
* 528 B 栈，是配置/syslog 调用链栈深的主要来源（2026-10-10 栈预算整改）。
@@ -86,7 +98,7 @@ int cfg_store_read(const char *p_path, uint8_t *p_buf, size_t cap, size_t *p_nre
#define CFG_STORE_TMP_PATH_MAX 24u
/*
* 函数功能：由目标路径推导同目录的临时文件路径（P3-2）
* 函数功能：由目标路径推导同目录的临时文件路径
* 入口参数：p_path - 目标文件路径 const char *
* p_out - 输出缓冲 char *
* cap - 缓冲容量 size_t
@@ -132,7 +144,7 @@ int cfg_store_write_atomic(const char *p_path, const uint8_t *p_buf, size_t len)
if (p_buf == NULL) {
return -1;
}
/* P3-2：临时文件由 p_path 推导（同目录 + 固定 8.3 名），不再硬编码卷根 */
/* 临时文件由 p_path 推导（同目录 + 固定 8.3 名），不再硬编码卷根 */
if (s_build_tmp_path(p_path, tmp_path, sizeof(tmp_path)) != 0) {
return -1;
}
@@ -153,7 +165,7 @@ int cfg_store_write_atomic(const char *p_path, const uint8_t *p_buf, size_t len)
}
/* 本 FatFs 移植的 f_rename 对已存在目标返回 FR_EXIST、不覆盖（ff.c
* "new name already in use" 检查，上游同语义）——"目标存在的覆盖写"必须先
* unlink 目标再 rename。2026-09-22 台架实证（E-01 验证暴露）：缺本步时
* unlink 目标再 rename。2026-09-22 台架实证：缺本步时
* 一切非首启写（UI 保存/模板重建）静默失败，模拟器后端（POSIX rename
* 覆盖语义）照不出。unlink→rename 非原子窗口掉电 = 配置文件暂失，
* 开机 load 按"首启"重建工厂模板——与函数失败语义一致，丢失边界 =
@@ -250,7 +262,7 @@ const char *cfg_store_tmp_path(void) {
* 返回值：缓冲指针（内容未清零）；失败返回 NULL void *
* 限定条件：任务上下文调用（heap_4 内部临界区自护）；释放必须用 cfg_store_free
* 函数说明：MCU 端 MicroLIB C 堆仅 512B（startup Heap_Size=0x200），共享核心的 KB 级
* 缓冲若走 C 库 malloc 必然返回 NULL，故统一由本接口取 FreeRTOS 堆（P0-1）
* 缓冲若走 C 库 malloc 必然返回 NULL，故统一由本接口取 FreeRTOS 堆
*/
void *cfg_store_alloc(size_t size) {
return pvPortMalloc(size);
App/cfg/prot_set_store.c
+1 -1
View File
@@ -52,7 +52,7 @@ static uint32_t s_ld32(const uint8_t *p) {
* -1 损坏被拒
* 函数说明：读失败与"文件不存在"同归 1——启动期卷锁无竞争（本任务独占
* bring-up），try-lock 失败即真 I/O 故障，此时保持出厂默认并让
* 调用方按"无档"处理是安全侧（定值仍封存自洽，L5-1 不误锁）。
* 调用方按"无档"处理是安全侧（定值仍封存自洽，定值校验和不误锁）。
* **换代与损坏分开**（B8）：magic 完好但 ver/cnt 与当前固件不符 =
* 定值表升级（如 B8 32→40 项），是**预期升级路径**不是损坏 →
* 归 2 并打 INFO（"version change"措辞），调用方不得按 CORRUPT
App/fs/vol_idle_sync.c
+125
View File
@@ -0,0 +1,125 @@
/*
* 模块名称：Volume Idle Sync（写回缓存空闲 flush）— MCU 实现
* 模块功能：就绪门控 + 周期节流 + 卷锁 try + disk_ioctl(CTRL_SYNC) 的兜底
* 状态机（设计/使用约定/边界见 vol_idle_sync.h）
* 适用平台：STM32F407ZGTx + FreeRTOS
* 作者：DTU 项目组
* 创建日期：2026-10-25
* 修改记录：
* v1.0 2026-10-25 DTU 项目组 创建（道F 批 2：写回缓存空闲 flush 收口）
*/
/* 头文件包含区 */
#include "vol_idle_sync.h"
#include "test_config.h"
#if !defined(TEST_SUITE_STORAGE)
#include "cmsis_os.h"
#include "FreeRTOS.h"
#include "task.h"
#include "ff.h" /* FatFs 基础类型（diskio.h 依赖 BYTE/LBA_t 等，须先纳） */
#include "diskio.h" /* disk_ioctl / CTRL_SYNC / DRESULT */
#include "vol_lock.h"
#include "sys_events.h"
/* 本模块日志仅一条失败留痕（≤60 字符），默认行缓冲即可，不调 DBG_LINE_BUF_MAX */
#include "dbg_log.h"
/* Private defines -----------------------------------------------------------*/
/* 空闲同步检查周期（= 漏网脏页的最大掉电驻留窗，另加一个主循环拍 ≈50ms）。
* 取值依据：clean 态为"脏标志 + journal"双短路（零 NAND 触点），高频不伤介质
* 只是白跑；脏态最多一次页编程 + journal 收账，与 f_close 同型，但落在卷
* 已空闲的窗口、远离活跃写会话。5 s 与主循环其余慢观测（栈/堆水位 2 s）同
* 量级而更稀疏——本模块是兜底网，不是持久性主路径（主路径 = close 内同步）。
* 锁忙（卷不空闲）同样按本周期重试：不做欠账补偿，节奏恒定好推理。 */
#define VOL_IDLE_SYNC_PERIOD_MS 5000u
/* 静态变量定义区 */
/* 状态量放文件级 static（非函数内）：主机侧白盒单测（test/host/vol_idle_sync/）
* 以 #include 纳入本文件后需要复位它们；命名带 vol 前缀避免与测试桩撞名 */
static uint32_t s_vol_sync_last_ms; /* 上次尝试时刻（tick ms，uint32 回绕） */
static uint8_t s_vol_sync_armed; /* 0 = 从未尝试（首拍直接放行） */
static uint8_t s_vol_sync_fail_latch; /* 失败留痕边沿 latch：一个 episode 一条 */
/* 函数定义区 */
/*
* 函数功能：存储空闲周期同步轮询（就绪门控 → 节流 → try 卷锁 → CTRL_SYNC）
* 入口参数：无 void
* 返回值：无 void
* 限定条件：仅 defaultTask 主循环调用；内部绝不阻塞（try 锁 + 常数级耗时，
* 最坏成本 = 一次 f_close 的同步段）
* 函数说明：四级门，逐级变贵：
* ① 就绪门：sys_evtHandle 未建或 STORAGE_READY 未置 → 静默
* （挂载前 disk_ioctl 只会 RES_NOTRDY，且 bring-up 失败重试期
* 卷状态未定，一律不碰）；
* ② 节流门：距上次尝试不足 VOL_IDLE_SYNC_PERIOD_MS → 返回。
* 无符号差值判据（(uint32)(now - last) < 周期）天然跨 32 位回绕
* 正确，与 stack_probe_poll 同一 idiom；勿"优化"成大小比较；
* ③ 空闲门：vol_lock_wait(0) try——锁被持有 = 有文件操作序列在做
* （syslog 落盘 / 配置保存 / lftpd open...close），本轮跳过，
* 绝不改变"文件持有期内不同步"的既有语义；
* ④ 动作：disk_ioctl(0, CTRL_SYNC)——FatFs 官方幂等落盘原语
* （f_close 尾部同一条路径）：FTL 脏页刷入 + dhara_map_sync。
* clean 时两级短路立即返回，零 NAND 操作。
* 失败留痕：RES_ERROR 只按"边沿"打一条 DBG_ERROR（latch），持续失败
* 不刷屏；下一次成功后 latch 复位，新 episode 再报。底层失败形态
* （Cache flush FAIL / Map sync failed）已由 nand_ftl 就地打点，
* 本条只补"空闲路径也救不回"的上下文，不重复堆日志锚点。
*/
void vol_idle_sync_poll(void) {
const uint32_t now = (uint32_t)xTaskGetTickCount();
DRESULT dr;
/* ① 就绪门 */
if (sys_evtHandle == NULL) {
return;
}
if ((osEventFlagsGet(sys_evtHandle) & SYS_EVT_STORAGE_READY) == 0u) {
return;
}
/* ② 节流门（回绕安全判据，见函数说明②） */
if ((s_vol_sync_armed != 0u)
&& ((uint32_t)(now - s_vol_sync_last_ms)
< (uint32_t)pdMS_TO_TICKS(VOL_IDLE_SYNC_PERIOD_MS))) {
return;
}
s_vol_sync_last_ms = now;
s_vol_sync_armed = 1u;
/* ③ 空闲门：try 锁，拿不到 = 卷不空闲，本轮跳过（下周期再试） */
if (vol_lock_wait(0u) == 0u) {
return;
}
/* ④ 幂等落盘：脏页刷入 + journal 收账；clean 时零 NAND 触点 */
dr = disk_ioctl(0, CTRL_SYNC, NULL);
vol_lock_release(); /* 成败都放锁：同步失败不产生锁泄漏 */
if (dr != RES_OK) {
if (s_vol_sync_fail_latch == 0u) {
s_vol_sync_fail_latch = 1u;
DBG_ERROR("[FS] idle sync FAIL (dr=%d)", (int)dr);
}
} else {
s_vol_sync_fail_latch = 0u; /* 成功：重新武装，下个 episode 可再报 */
}
}
#else /* TEST_SUITE_STORAGE */
/*
* 函数功能：STORAGE 套件构建下的空实现（编译期裁剪落点）
* 入口参数：无 void
* 返回值：无 void
* 限定条件：仅当 test_config.h 选中 TEST_SUITE_STORAGE 时编入本分支
* 函数说明：该构建里挂载/盘写由 testTask 的 storage_test_run 独占（测试含
* nand_ftl_deinit 掉电模拟），后台同步与它并发会互相踩坏 FTL/FatFs
* 状态——必须彻底静默，而非仅靠运行时门控。
*/
void vol_idle_sync_poll(void) {
}
#endif /* TEST_SUITE_STORAGE */
App/fs/vol_idle_sync.h
+50
View File
@@ -0,0 +1,50 @@
/*
* 模块名称：Volume Idle Sync（写回缓存空闲 flush）
* 模块功能：随 defaultTask 主循环周期轮询，在存储**空闲**时对 NAND FatFs 卷
* 补发一次 CTRL_SYNC（FatFs 幂等落盘语义 = FTL 单页写回缓存脏页刷入
* + dhara journal 待办收账，见 docs/架构设计/STM32F4-Base存储架构说明.md
* §5.5），作为写回缓存持久性的兜底网：
* - 正常写事务语义不变：f_close 内部 sync_fs 已同步，本模块零干预；
* - 价值在漏网兜底：任何"缓存留脏、之后再无调用触发 sync"的状态
* （异常路径中途放锁等）其掉电驻留窗从"无限期，直到下一笔写"
* 收敛为"不超过本模块周期"；
* - 卷不空闲（卷锁被持有：syslog 落盘 / 配置保存 / lftpd
* open...close 序列进行中）本轮跳过——不改变文件持有期（如 FTP
* STOR 进行中）的既有语义。
* clean 态零 NAND 触点（脏标志与 journal 双短路）；脏态成本与一次
* f_close 同型。周期 5 s（.c 内 VOL_IDLE_SYNC_PERIOD_MS）。
* ⚠ 边界（勿当成掉电保护）：本板无掉电检测硬件，"掉电前强制 flush"
* 不可行；"单次写事务进行中掉电"的丢失边界也不因本模块改变。
* 适用平台：STM32F407ZGTx + FreeRTOS（CMSIS-RTOS V2）；仅 MCU 端，
* 主机侧纯逻辑单测 test/host/vol_idle_sync/
* 作者：DTU 项目组
* 创建日期：2026-10-25（道F 批 2：写回缓存空闲 flush 收口）
* 修改记录：
* v1.0 2026-10-25 DTU 项目组 创建：STORAGE_READY 门控 + 周期节流 +
* 卷锁 try + disk_ioctl(CTRL_SYNC) + 失败边沿 latch
*/
#ifndef VOL_IDLE_SYNC_H
#define VOL_IDLE_SYNC_H
#ifdef __cplusplus
extern "C" {
#endif
/*
* 函数功能：存储空闲周期同步的轮询入口（内部自带就绪门控 / 节流 / 非阻塞
* try 锁 / clean 短路，调用点每轮无条件调用即可）
* 入口参数：无 void
* 返回值：无 void
* 限定条件：仅 defaultTask 主循环调用（存储属主任务；本函数内部绝不阻塞——
* defaultTask 是看门狗喂狗点，见 vol_lock.h 使用约定）；
* TEST_SUITE_STORAGE 构建下为空实现（卷由 testTask 独占，后台同步
* 必须彻底静默）
*/
void vol_idle_sync_poll(void);
#ifdef __cplusplus
}
#endif
#endif /* VOL_IDLE_SYNC_H */
App/fs/vol_lock.c
+62 -2
View File
@@ -6,6 +6,14 @@
* 创建日期：2026-10-02
* 修改记录：
* v1.0 2026-10-02 王建锋 创建
* v1.1 2026-10-26 DTU 项目组 道G task-17：① 新增 4 个观测计数（持锁 / try 超时 /
* 分片退让 / 零互斥 四态，
* 共 16 B 静态）与 vol_lock_get_stats() 只读口 —— 不取锁、
* 零外部调用、零局部变量，13 处调用点一字未动；
* ② 修 :38「返回值」注释与代码相反的错（fail-open 原被
* 归给 0，实际返 1）；③ 刻意不记时刻：时刻要读 tick，
* 等于给 defaultTask 取锁链添帧，改由消费方观测并自盖
* （命名 obs_first_ms/obs_last_ms，见 vol_lock.h 告诫 ②）
*/
/* 头文件包含区 */
@@ -16,6 +24,22 @@
/* 静态变量定义区 */
static osMutexId_t s_lock; /* 卷串行化互斥锁（vol_lock_init 创建） */
/* 观测计数（道G task-17「卷锁 5 态可观测性」）—— 本模块唯一的新增状态，共 16 B。
* 为什么计数必须在锁层、而且只有计数没有别的：
* ① 13 处调用点各自 return、历史上零痕；在每个调用点各写一份 = 13 份真源。
* ② 不能在这里打日志或投记录：唯一能落盘的通道（/log/wdev.log、run.log）自己也要
* 取这把卷锁，而卷锁**非递归** —— 被卷忙挡住时既写不出东西，还会自取死锁。
* ③ 也不读 tick 记时刻：那会给 defaultTask 的取锁链添一个 callee 与几字节帧，而
* 这条链的栈余量正是要省着花的；"什么时候开始忙"交给消费方观测（口径见 vol_lock.h
* 的告诫 ②：观测时刻不等于发生时刻，别写成首次发生）。
* 并发：多个任务可同时自增同一个计数，竞态下少计不会多计（判据是"是否 > 0 / 是否还
* 在增长"，不是精确值），所以不为此上临界区 —— 上临界区反倒把观测做成了故障本身。
* volatile：跨任务读写且无锁保护，禁止把读侧重复读优化掉。 */
static volatile uint32_t s_st_acquired; /* 持锁态：真取到互斥（四态定义见 vol_lock.h） */
static volatile uint32_t s_st_try_timeout; /* try 超时态：timeout=0 没取到，卷被别人占住 */
static volatile uint32_t s_st_blk_timeout; /* 分片退让态：分片等待超时，ftpTask 正常退让 */
static volatile uint32_t s_st_failopen; /* 零互斥态：锁不存在却返 1，谎报成功那一态 */
/* 函数定义区 */
/*
@@ -35,18 +59,35 @@ int vol_lock_init(void) {
/*
* 函数功能：获取卷锁（首次调用自动 vol_lock_init）
* 入口参数：timeout_ms - 等待上限（毫秒）；0 = try 语义（不阻塞） uint32_t
* 返回值：1 - 已持锁；0 - 超时/未取得，或锁创建失败（fail-open） int
* 返回值：1 - 已取得互斥，**或锁不存在的 fail-open（返 1 但此刻并未串行化）**；
* 0 - 未取得（timeout=0 的 try 失败，或 timeout>0 的分片等待超时） int
* 限定条件：返回 0 时调用方**不得** vol_lock_release；fail-open 是为保证
* 看门狗喂狗点（defaultTask）绝不能因等锁而阻塞
* 函数说明：⚠ 原 v1.0 这行「返回值」把 fail-open 归给 0，与本函数 :46 的代码和
* TC-VOLLOCK-008 都相反（道G task-17 修正）。"返 1"有两种成因，调用方
* 无需各自分辨（它们只关心能不能干活），但整机的判据必须看
* vol_lock_get_stats().failopen —— 累计 > 0 = 本 boot 至少发生过一次
* "无互斥读写卷"。本函数只自增计数：不打日志、不投记录、不读 tick、
* 不新增局部变量（理由见上面计数块）。
*/
int vol_lock_wait(uint32_t timeout_ms) {
if (s_lock == NULL) {
(void)vol_lock_init();
if (s_lock == NULL) {
s_st_failopen++; /* 零互斥态：返 1 但零互斥 —— 谎报成功那一态 */
return 1; /* 锁创建失败：fail-open（不阻塞，保持启动段可用） */
}
}
return (osMutexWait(s_lock, timeout_ms) == osOK) ? 1 : 0;
if (osMutexWait(s_lock, timeout_ms) == osOK) {
s_st_acquired++; /* 持锁态：真持锁 */
return 1;
}
if (timeout_ms == 0u) {
s_st_try_timeout++; /* try 超时态：压根没等（喂狗点/绘制路径只有这一态会发生） */
} else {
s_st_blk_timeout++; /* 分片退让态：等了一会儿没等到，与 try 超时态语义不同 */
}
return 0;
}
/*
@@ -60,3 +101,22 @@ void vol_lock_release(void) {
(void)osMutexRelease(s_lock);
}
}
/*
* 函数功能：读卷锁观测计数（契约与消费方告诫见 vol_lock.h 的函数头）
* 入口参数：p_out - 输出缓冲；NULL 时无害返回 vol_lock_stats_t *
* 返 回 值：无 void
* 限定条件：不取卷锁、不关中断、不阻塞；**零外部调用、零局部变量**，因此不改变
* 任何调用方的栈最坏链（这条是本卡选型的结论，不要"顺手优化"掉）
* 函数说明：逐字段拷而非整体赋值 —— 每个字段都是某个真实值，不会读到半更新的字；
* 四元组之间不保证同一瞬间（诊断够用，理由见 .h 的告诫 ①）
*/
void vol_lock_get_stats(vol_lock_stats_t *p_out) {
if (p_out == NULL) {
return;
}
p_out->acquired = s_st_acquired;
p_out->try_timeout = s_st_try_timeout;
p_out->blk_timeout = s_st_blk_timeout;
p_out->failopen = s_st_failopen;
}
App/fs/vol_lock.h
+63 -1
View File
@@ -13,6 +13,13 @@
* 长耗时恢复旋转饥饿 defaultTask 主循环（喂狗点）
* → IWDG 误复位；单写者卷属主假设在多任务 FatFs
* 调用下不成立，须显式串行化）
* v1.1 2026-10-26 DTU 项目组 道G task-17：① 修契约——vol_lock.c 原 :38 的
* 「返回值」把 fail-open 归给 0，而代码（:46）与
* TC-VOLLOCK-008 都是返 1；现在 .h/.c 两处都按代码写实，
* 并显式警告"返 1 也可能是零互斥"；② 新增 5 态计数与
* vol_lock_get_stats() 只读口（不取锁、任意上下文可调）；
* ③ 使用约定补「可观测性」段（为何计数在锁层、为何不得
* 在失败分支里取锁打日志）
*
* 使用约定（铁律）：
* - 锁跨越"一次完整文件操作序列"（open...close / opendir...closedir /
@@ -23,6 +30,12 @@
* - ftpTask 调用方用 100ms 分片阻塞等待 + 每片心跳（lftpd_task_wd_beat），
* 防长等待导致 FTP 心跳位缺席误复位；
* - 锁在内核启动后由 defaultTask 存储 bring-up 创建（vol_lock_init 幂等）。
*
* 可观测性（道G task-17）：锁层自带 5 态计数 + `vol_lock_get_stats()` 只读口。
* 为什么计数必须在**锁层**：唯一能把事写下来的通道（`/log/wdev.log` 等）自己也要
* 取这把锁，而卷锁**非递归**——被卷忙挡住时既写不出日志，也不许在失败分支里再取
* 同一把锁。所以锁层只自增计数；一次性留痕交给 defaultTask（syslog 唯一写者）按边沿
* 补投自检记录。调用方 13 处 try 的分支与返回值一字不动（不动分支 = 不动行为）。
*/
#ifndef VOL_LOCK_H
@@ -45,11 +58,60 @@ int vol_lock_init(void);
/*
* 函数功能：获取卷锁
* 入口参数：timeout_ms - 等待超时（0 = 非阻塞 try） uint32_t
* 返回值：1 - 已获取；0 - 超时未获取（卷被占用） int
* 返回值：1 - 已取得互斥，**或锁不存在的 fail-open（此时并未串行化）**；
* 0 - 未取得（try 超时，或分片等待超时） int
* 限定条件：见文件头使用约定（defaultTask 必须 timeout_ms=0）
* 函数说明：⚠ 道G task-17 修掉的契约缺口——本函数只有 0/1 两值，而"返 1"有两种
* 成因：真取到锁，与 `osMutexNew` 失败时的 fail-open（返 1 但对卷的访问
* **零互斥**）。要求 13 处调用方各自区分是不现实的（它们只关心"能不能干活"），
* 判据请改用 `vol_lock_get_stats()` 的 `failopen` 计数：累计 > 0 =
* 本 boot 内至少发生过一次"无互斥读写卷"。
* 本函数内只**自增计数**：不打日志、不投记录、不阻塞（理由见 .c 计数块）。
*/
int vol_lock_wait(uint32_t timeout_ms);
/*
* 卷锁观测计数（道G task-17「卷锁 5 态可观测性」）。四个字段就是四态，语义**不得**合并：
* `acquired` 持锁态 = 真取到互斥的次数
* `try_timeout` try 超时态 = timeout=0 的 try 失败次数（卷被别的任务占住；
* defaultTask/uiTask 的喂狗与绘制路径只有这一态会发生）
* `blk_timeout` 分片退让态 = timeout>0 的分片等待超时次数（ftpTask 100 ms 分片正常
* 退让；与 try 超时态语义不同：那是"等了一会儿没等到"，
* 这是"压根没等"）
* `failopen` 零互斥态 = 锁不存在却返 1 的次数（**谎报成功**那一态，见 wait 函数头）
* 「未调用」这一态不占计数：三个计数全 0 就说明这条路径没跑过——区分"没跑过"与
* "跑了但一直忙"正是本卡的目的（此前两者在日志上完全一样）。
* ⚠ 本层**刻意不记时刻**：记时刻就得读 tick，等于给 defaultTask 的取锁链添一个
* callee 与几字节帧，而这条链的余量我们整天都在省着花（诊断不值那几个字节）。
* 代价是"什么时候开始忙"只能由消费方观测，见下面 get_stats 的第② 条告诫。
*/
typedef struct {
uint32_t acquired;
uint32_t try_timeout;
uint32_t blk_timeout;
uint32_t failopen;
} vol_lock_stats_t;
/*
* 函数功能：读卷锁观测计数（纯拷字段）
* 入口参数：p_out - 输出缓冲；NULL 时无害返回 vol_lock_stats_t *
* 返 回 值：无 void
* 限定条件：任意上下文可调——**不取卷锁**、不关中断、不阻塞（卷被长期占住时正是最
* 需要读这几位的时刻，观测口再抢锁就把观测做成故障的一部分）
* 函数说明：① 四个字段各是 32 位对齐量，Cortex-M4 上单字读写原子，但**不保证是同一
* 瞬间的四元组快照**（诊断够用）。计数本身跨任务读-改-写，竞态下可能
* **少计不会多计** → 判据用「是否 > 0 / 与上一轮比是否增长」，别拿精确值当账。
* ② ⚠ **给消费方的告诫**（消费方 = 看门狗/自检记录道，接口按此写就不会错）：
* 本层不产出时刻。消费方若自行盖时间戳，那是「**被观测到的时刻**」，不是
* 「**发生的时刻**」——真实发生可以早到一整个轮询周期之前。命名请用
* `obs_first_ms` / `obs_last_ms`（观测时刻）这类，**别用** `first_ms`/`last_ms`，
* 文案里也别写「首次/末次发生」（那就是新的谎报）。
* 一次性留痕自己做边沿：照 `sys_log.h` 的 `syslog_post_dropped()` 先例（唯一
* 写者按差值补发，一个 episode 一条），锁层自身绝不产日志、不投记录。
* ③ 本函数零外部调用、零局部变量（除出参），因此不改变任何调用方的栈最坏链。
*/
void vol_lock_get_stats(vol_lock_stats_t *p_out);
/*
* 函数功能：释放卷锁（获取方任务释放）
* 入口参数：无
App/log/README.md
+65 -4
View File
@@ -7,11 +7,11 @@
| 文件 | 作用 |
|---|---|
| `sys_log.h` | **日志接口（平台无关）**：定长 64B 记录写入 `/log/run.log`·`selftest.log` |
| `sys_log.h` | **日志接口（平台无关）**：定长 64B 记录，七类各一个 `/log` 文件（run / selftest / accid / alarm / start / oper / yk）|
| `sys_log_mcu.c` | `sys_log` 的 MCU 端后端实现（NAND + FatFs） |
| `console_log.c/h` | **控制台单写者日志**：多任务日志经队列汇入唯一写者，避免串口输出交错 |
| `soe_rec.c/h` | **SOE 记录纯编解码**（B9）：64B 定长记录（CP56Time2a 时标 + 类型 + 元件号 + 单调序号 + 值 + sum8 撕裂校验），零 I/O 零 OS 依赖，主机单测覆盖 |
| `soe_store.c/h` | **SOE 落盘胶水**（B9）：`/log/soe.log`，protectTask 投递（零文件系统）→ defaultTask 排空落盘 |
| `soe_rec.c/h` | **SOE 记录纯编解码**：64B 定长记录（CP56Time2a 时标 + 类型 + 元件号 + 单调序号 + 值 + sum8 撕裂校验），零 I/O 零 OS 依赖，主机单测覆盖 |
| `soe_store.c/h` | **SOE 落盘胶水**：`/log/soe.log`，protectTask 投递（零文件系统）→ defaultTask 排空落盘 |
## 关键机制
@@ -23,13 +23,74 @@
内核启动后由 `syslog_drain` 惰性创建真队列并排空
- ⚠️ 写盘必须校验 `f_write` 返回的**字节数**（该 FatFs 移植在簇分配失败时返回 `FR_OK` + 短写，
不报错误码）；追加写必须 `FA_WRITE|FA_OPEN_APPEND`（`FA_OPEN_APPEND` 单独用**不含写位**）
- **清除记录 = 请求 / 落地分离**：非写者上下文（uiTask 等）只能 `syslog_request_clear(id)`
置一个标志（零盘触点、零卷锁），真正的 `f_unlink` 在 **defaultTask** 的 `syslog_drain()`
**尾部**执行——顺序也是判据的一部分：排在条目排空之后，否则本轮刚排空的旧记录会被
写回去、`syslog_count()` 不归零。结果读 `syslog_clear_state(id)`
（`NONE/OK/WAIT/FAIL`），事实复核读 `syslog_count()`。
落地函数 `syslog_clear_apply(id)` 是 MCU 后端专属（模拟器不实现 → 共享代码误调在
链接期就报错）：卷锁一律 try，卷占用返 -1 且**不动原文件**；幂等只认 `FR_NO_FILE`，
`FR_NO_PATH` 如实返 -1 且**不做任何卷级动作**（不补目录、不重格式化）
- 删除的作用域 = 上表七个记录文件（`syslog_request_clear(id)` 逐 id 独立请求）；取证文件
`wdev.log` 与 `soe.log` 各有各的属主与通道，不在本 API 作用域，想清它们要另开 API。
清除成功会往**操作记录**里落一条 `clear <文件>`——但清 `oper.log` 自己时**刻意不投**，
否则"我清除了记录"这条会把刚删空的文件又写成 1 条，直接砸掉「删除后 `syslog_count()`
归零」这条判据（`TC-SYSLOG-133b` 钉住）
- ⚠ 宿主后端（`simulator/sim/sim_syslog.c`）与 MCU 端**判据相同、时序不同**：模拟器单线程，
七类对应工作目录下七份宿主文件（`sim_accid.log` 等），`syslog_post_quiet()` 在本端
等价于 `syslog_post()`（宿主进程没有那条栈硬线，也没有队列与丢弃）；
`syslog_request_clear()` 调用内就删完了，因此 `WAIT` 态在模拟器上永不出现
（同 `syslog_post` 在两端"有队列 / 直写无队列"的差异）
### 五类记录与「记录类型 = 日志 ID」（道F task-10，2026-10-26；task-11 记录 5 页按此做，2026-10-28 五页已落地）
**决策一：记录类型就是 `syslog_id_t` 本身，一类记录 = `/log` 下一个严格 8.3 短名的文件。**
64B 定长记录体里**没有类型字段位**：`[0..18]` 时标 / `[19]` 空格 / `[20..29]` epoch /
`[30]` 空格 / `[31..58]` 描述 / 尾部补零，这个布局被 UI 记录页与主机解码工具按**固定偏移**
读了了很久（run.log / selftest.log 是既有文件，既有读者）。塞类型字节要么挪走 epoch
（上电/重启分类就断），要么挪走描述（屏上少字），且两端读者同批改——所以
"这条记录是什么类型"由**它在哪个文件里**回答。`TC-SYSLOG-136` 把这条钉成机器断言：
同一条内容在七类之间逐字节相同，记录体不编码类型。
**决策二：不动 `soe_type_t`（二进制 SOE 通道保持现有 8 型）。** 加 SOE 类型必须同步 UI 侧
`ui_w_soe.c` 的类型名表（那是另一位队友的写域），而 SOE 页与这五页本就是两套读者
（二进制解码器 vs 文本列表）。**别把新类型顺手加进 SOE**：那会同时造出
"同一个事件两个真源"。
| 记录 | 日志 ID / 文件 | 容量上限 | 写入点 | 触发判据 |
|---|---|---|---|---|
| 事故 | `SYSLOG_ACCIDENT` / `accid.log` | 512 | `App/task/protect_task.c:188` | `asserted` 上升沿**且**该元件跳闸投退项 = 1 |
| 保护告警 | `SYSLOG_ALARM` / `alarm.log` | 1024 | 同文件 `191` | `asserted` 上升沿**且**跳闸投退项 = 0 或该元件无此项 |
| 保护启动 | `SYSLOG_START` / `start.log` | 1024 | 同文件 `183` | `picked` 上升沿（越限电平，早于/等于动作） |
| 操作 | `SYSLOG_OPER` / `oper.log` | 512 | `App/protocol/iec104/iec104_pts.c:582/610`、`App/task/default_task.c:266`、`App/log/sys_log_mcu.c:682`（宿主 `sim_syslog.c:245`） | 强制复归受理 / 软压板投退落地 / 定值**真落盘成功** / 清除记录成功 |
| 遥控 | `SYSLOG_YK` / `yk.log` | 256 | `App/protocol/iec104/iec104_pts.c:581/584/590/594/604/606/617` | 104 双点命令的选择段、执行段、非法 DPC、未知 IOA 各一条 |
- **"哪些元件算跳闸"只有一个真源**：定值表 `g_prot_set_meta` 里的 `PS_*_TRIP`（枚举注释
即"0 告警 / 1 跳闸"）+ 实例表 `k_pe[]` 的 `trip_ctl` 列。分类入口
`prot_elm_record_kind()`（`App/algo/prot_elm.c`）里**没有第二份元件名单**，
没有该投退项的五项（OV/UV/3U0/OF/UF）填 `PROT_ELM_NO_TRIP=0xFF` → 恒告警；
`TC-PROTELEM-015` 逐元钉住"逐项独立 / 改定值即改类别 / 无此项者不受别人定值影响"。
- **描述只用 ROM 常量或 `prot_elm_name()` 直传**：所有写入点零 `snprintf`、零拼接。
最长一条 20 字节 < `SYSLOG_DESC_MAX`(28)；`TC-IEC104-030` 逐条量长度（超 28 会被
投递侧静默截断，屏上少几个字，没人会去数）。
- ⚠️ **两个投递口，按调用者的栈预算选**：`syslog_post()` 的两个"满态丢弃留痕"分支
内联着日志行缓冲（每处约 216 B 栈），因此 `syslog_post_quiet()` 给静态最坏链吃紧的
任务用（**protectTask、iec104Task 必须用它**），丢弃只累加 `syslog_post_dropped()`、
由唯一写者 defaultTask 在 `syslog_drain()` 里按差值补一条留痕——同 `soe_store_post`
当年那条 `872 → 1192 B FAIL` 的实证纪律。收/丢判据两个口完全一致。
- **读侧契约（给 task-11；2026-10-28 五页已按此接上）**：`syslog_count(id)` + `syslog_get_record(id, idx, ts, ts_len,
desc, desc_len)` 与运行/自检记录**同一枚 reader**，"最近 20 条"= 从 `count-20` 起读；
`count()==0` 就是空态，页面显示"无记录"。**不要**在共享代码里调 MCU 专属的
`syslog_clear_apply()`（模拟器不实现 → 链接期报错是故意的）；清除一律走
`syslog_request_clear()` + `syslog_clear_state()`，并把 `WAIT` 当正常态看（模拟器端
永不出现 `WAIT`，见下条）。
### console_log（控制台单写者）
- 多任务的生产者 → **单写者消费者**，消除任务间日志行交错
- 设计详见 `docs/子系统设计/控制台单写者日志设计说明.md`
### soe（SOE 事件顺序记录，B9）
### soe（SOE 事件顺序记录，SOE 记录）
- **记录 = 64 B 定长二进制**（`soe_rec.h` 布局），落 `/log/soe.log`；
与 run.log 分文件——run.log 是文本记录、有 UI/主机读取方，二进制 SOE
App/log/console_log.c
+407 -68
View File
@@ -1,5 +1,5 @@
/*
* 模块名称：Console Single-Writer Logging — 控制台单写者日志（USART1）实现
* 模块名称：Console Single-Writer Logging — 控制台单写者日志（RS232#1 / UART5）实现
* 模块功能：控制台单写者日志的环形缓冲 + 唯一写者发送实现（API 见 console_log.h）；
* 兼载 MicroLIB printf 底层 fputc 重定向
* 适用平台：STM32F407ZGTx（仅 MCU 端）
@@ -8,17 +8,17 @@
* 修改记录：
* 2026-09-24 王建锋 创建（自 Src/usart.c USER CODE 区迁出，实现逻辑不变，
* 仅变更文件位置：HAL 库生成文件不得包含应用代码）
* 2026-10-02 王建锋 僵尸通道喂狗节奏保护（台架 gen-288 实证）：round-3 的
* 2026-10-02 王建锋 僵尸通道喂狗节奏保护（台架日志代次 288 实证）：第 3 轮的
* "单次 drain 预算 250ms" 只限单次调用——ORE 锁存在外设软复位后
* 毫秒级重锁（PA10 悬空 + RX 使能），背靠背 drain 每轮再耗 100ms
* 块超时 → 主循环周期拉到 450~500ms → 100ms 节流的喂狗抽样间隙
* 超过 IWDG 最坏容限 1.7s → 停喂 → 误复位（且心跳位全员健康、
* 无 stall 日志，纯节奏性饥饿）。修复：发送故障后立即结束本轮
* drain 并进入 300ms 发送冷却（冷却期内 drain 直接让位主循环），
* 保证喂狗节奏 ≤ ~300ms。根治（USART1 TX-only 灭 ORE 机制）
* 另行推进（.ioc 结构性修改 + CubeMX 重生成，见 docs/任务规划/登记簿.md S-3）。
* 2026-10-02 王建锋 round 8b 加固：发送超时判据改用 DWT CYCCNT（时间源无关）。
* 台架 round 8a 取证（见 docs/子系统设计/看门狗设计说明.md 2026-10-02 变更记录）定位到：defaultTask
* 保证喂狗节奏 ≤ ~300ms。根治（把 USART1 改成只发不收）已于 2026-10-26
* 由用户裁定不做，本缓解即长期方案；机制详述 docs/子系统设计/控制台单写者日志设计说明.md §12。
* 2026-10-02 王建锋 第 8b 轮加固：发送超时判据改用 DWT CYCCNT（时间源无关）。
* 台架第 8a 轮取证（见 docs/子系统设计/看门狗设计说明.md 2026-10-02 变更记录）定位到：defaultTask
* 冻结在 console 突发行内、无 STALL、复位为 IWDGRSTF。唯一自洽机理 =
* HAL_UART_Transmit 的超时判据 `HAL_GetTick() - Tickstart` 依赖
* TIM7 的 uwTick —— TIM7 一旦停摆，超时永不成立 → 写者死等 TXE →
@@ -31,6 +31,44 @@
* adcTask（B1）等周期任务此时落日志会与 defaultTask 的存储初始化
* 日志字节级交错（台架实测 [ADC_TASK] 首帧行与 [NAND_FTL] 行交错）。
* 提供就绪查询供周期任务门控自身日志，不改直发路径本身。
* 2026-10-26 王建锋 **O1 第二个实例（台架实证）修复：裸发路径加「行级单一所有者」**。
* 台架同镜像两次启动（fw 戳 Oct 26 2026 16:27:01，排除构建差异）：16:28 那次
* protectTask 的未标定 INFO 完好，16:37 那次同一行变成
* "protection [blocked (UA/UN/IA VALI2D not all s0et)" —— 多出的 3 个字节是
* '[' '2' '0'，而 DBG 行前缀恰是 '[' + sys_clock_get_str() 的 "2026-…"，
* **即另一条行的行首三个字符**；串口 framing 错只会改字节、不会让行变长，
* 故只可能是另一个写者在同一行内插入。机理 = 写者注册前（内核启动 ->
* default_task.c 的 dbg_console_writer_attach，中间隔着整段 storage_bring_up）
* 所有任务的整行都走 dbg_console_write_raw 逐字节轮询 USART1->DR，**零互斥**
* （docs/子系统设计/控制台单写者日志设计说明.md 在册 O1；20261012_B6 那次
* "st[art:" 同一形态）。修法 = con_tx_try_claim()/con_tx_release() 一对
* **非阻塞**所有权（只在几条指令的临界区里做 test-and-set，绝不把 7.8 ms
* 的发送包进临界区、绝不关中断、绝不等待）；抢不到所有权的那条行**不丢**，
* 落进既有环形缓冲延后发（竞争失败不该变成丢行，更不该变成 [ERR] 假红——
* 那个窗口每 3 次启动命中 2 次），只有环也放不下才计入既有 dropped 账
* （真溢出仍然看得见）。顺带堵掉第二处洞：**attach 恰好撞上别人已发出的半行**
* ——dbg_console_drain 现在也必须先拿到所有权才开轮，拿不到就让位
* （tail 不推进，环里一条不少，下轮 ≤50 ms 后重发，这条路径永不丢）。
* 另导出 dbg_console_tx_begin()/tx_end() 供"一条行分多段裸发"的调用方收口
* （Src/freertos.c 故障钩子是下一张卡），本模块不改任何调用方文件。
* 2026-10-24 王建锋 主机单测（test/host/console_log）照出的四条一并修复：
* 冷却改判独立标志 s_con_cooling（旧写法拿 tick 值当"是否在冷却"哨兵，
* 故障恰好落在 HAL_GetTick()==0 那一拍时冷却等于没记）；
* con_append 的"复核空位 + 整行拷贝 + 推进 head"收进同一临界区（旧写法
* 判据在区外，多生产者可在环将满时同时过判据 -> head 越过容量把未发出
* 的旧行静默覆盖，既不报错也不计丢弃）；
* drain 失败分诊：Instance==NULL（未初始化）不再走外设软复位自愈（那会
* 在 HAL 未就绪时重配 RCC/GPIO），改记 dropped；僵尸通道仍自愈；
* 三本账分开（docs §13-O2）：新增 dbg_console_tx_timeout()，dropped 只记
* 真丢的，tx_fault 仍只记软复位自愈次数；[ERR] dropped 行改为"发成功才
* 销账"，通道不可用期间不再把丢弃证据一起冲掉。
* 2026-10-28 王建锋 **根因归因更正（纯注释，无行为变更）**：原注释把 ORE 锁存
* 写成"PA10 悬空 / 未接线"，用户确认 PA10 **一直是接线的**，该归因不成立。
* 真正的充分条件是"**RX 使能了却从不读 DR**"——线上任意一个字节或一个
* 噪声沿使 RXNE 置位后无人读，下一个事件即锁存 ORE（ORE 只能靠"先读 SR
* 再读 DR"清除 ⇒ 永不自愈）；引脚悬空只影响发生率，不是必要条件。
* 缓解措施与结论不变，仅改注释；机制详见
* docs/子系统设计/控制台单写者日志设计说明.md §12。
*/
#include "console_log.h"
@@ -55,22 +93,37 @@
* ① 行级原子：整行在一次临界区内拷入环形缓冲，写者按块一次 HAL_UART_Transmit
* 发出 → 行与行不可能再交错（UART 只有这一个调用点）；
* ② 指针可控：进 UART 的缓冲恒为本文件的环形缓冲，调用方脏指针再也到不了 UART；
* ③ 写者未注册（内核启动早期/裸机）或中断上下文：回退直接阻塞发送（无并发或必须裸发）。
* ③ 写者未注册（内核启动早期/裸机）或中断上下文：回退直接发送，但**整行独占**
* 由 con_tx_try_claim() 保证（道G task-23：未注册期原来就是"多个任务都直发、
* 零互斥"，O1 两个实例都出在这里）；抢不到独占的那条行不丢，落环形缓冲延后发，
* 与当场直发逐字节相同。ISR / 调度器未启动两种上下文放行（不许等）。
* 约束：不新增任务、不动态分配；环形缓冲为 BSS（SRAM1，非 CCM），无 DMA 可达性冲突。
*/
/* ===== 控制台端口（单点收口）=====
* 换口只改这一段：句柄 / IRQn / 初始化函数。时钟宏随句柄走——UART5 在 APB1、
* USART1 在 APB2，别照抄；串口模式与波特率在 Src/usart.c 的 MX_*_Init 里，本模块不管。
* 控制台在 RS232#1/UART5（USART1 专用给屏板链路——700 kbaud 只有它 MCU 引脚直出）。
* 端口排布、台架端子与判据见 docs/子系统设计/屏板链路设计说明.md 的 §2 与 §3.2。 */
#define CON_UART huart5
#define CON_UART_IRQN UART5_IRQn
#define CON_UART_CLK_DISABLE() __HAL_RCC_UART5_CLK_DISABLE()
#define CON_UART_CLK_ENABLE() __HAL_RCC_UART5_CLK_ENABLE()
#define CON_UART_INIT() MX_UART5_Init()
#define DBG_CON_RING_SIZE 4096U /* 环形缓冲字节数（必须为 2 的幂） */
#define DBG_CON_CHUNK_MAX 256U /* 写者单次 HAL_UART_Transmit 字节上限 */
#define DBG_CON_WAIT_MS 200U /* 缓冲满时生产者最长等待（ms），仍满则丢弃并计数 */
#define DBG_CON_TX_TIMEOUT_MS 100U /* 单次发送超时：256B 块 @115200 标称 22ms；僵尸通道限时 + 自愈 */
#define DBG_CON_DRAIN_BUDGET_MS 250U /* 单次 drain 连续发送上限：让位喂狗轮询（缺失容忍 800ms） */
#define DBG_CON_FAULT_COOL_MS 300U /* 故障后发送冷却：ORE 锁存毫秒级重锁，背靠连发无益
且拖长主循环周期 → 喂狗节奏饥饿（gen-288 实证）；
且拖长主循环周期 → 喂狗节奏饥饿（台架日志代次 288 实证）；
冷却期内 drain 只让位、不发送，下轮重试 */
/* ==== round 8b：与时间源无关的硬上界（DWT CYCCNT）====
/* ==== 第 8b 轮：与时间源无关的硬上界（DWT CYCCNT）====
* HAL_UART_Transmit 的超时判据是 `HAL_GetTick() - Tickstart > Timeout`，而 HAL 时基
* = TIM7 的 uwTick。TIM7 停摆 → 超时永不成立 → 写者死等 TXE → 唯一喂狗者停摆 →
* IWDG 误复位（round 8a 台架现场）。改用 DWT CYCCNT（内核硬件周期计数，不依赖任何
* IWDG 误复位（第 8a 轮台架现场）。改用 DWT CYCCNT（内核硬件周期计数，不依赖任何
* 中断/uwTick）做判据；DWT 使能失败时退回 HAL_UART_Transmit（旧行为，功能不退化）。 */
#define CON_TX_TIMEOUT_CYC (SystemCoreClock / 10U) /* 发送硬上界 = 100ms 对应周期数 */
/*
@@ -89,20 +142,74 @@
static uint8_t s_con_ring[DBG_CON_RING_SIZE];
static volatile uint16_t s_con_head; /* 生产者写入位置 */
static volatile uint16_t s_con_tail; /* 写者读取位置 */
static volatile uint32_t s_con_drop; /* 因缓冲满丢弃的行数 */
static volatile uint32_t s_con_drop; /* 真没落地的丢弃数（一次一行/一块） */
static volatile uint32_t s_con_tx_fault; /* TX 失败（僵尸通道）次数，均经外设软复位自愈 */
static volatile uint8_t s_con_tx_fault_log; /* TX 故障留痕待上报（由写者任务在 drain 之外补记 run.log） */
static volatile uint32_t s_con_cool_until; /* 故障冷却截止 tick（0 = 无冷却） */
static volatile uint32_t s_con_cool_until; /* 故障冷却截止 tick（只存时刻，不再兼作哨兵） */
static volatile uint8_t s_con_cooling; /* 1 = 正在故障冷却（独立标志：tick 恰好等于 0 的那一拍也必须算在冷却） */
static volatile uint32_t s_con_tx_timeout; /* 发送块超时次数（写者排空所见，与丢弃账分开） */
static volatile uint8_t s_con_draining; /* 1 = 处于 drain 中（重入保护） */
static volatile uint8_t s_con_writer_up; /* 1 = 写者已注册（此后走环形缓冲） */
static volatile uint8_t s_con_dwt_up; /* 1 = DWT CYCCNT 已使能（硬上界基准可用） */
static TaskHandle_t s_con_writer_task; /* 写者任务句柄（自等保护用） */
/* 行级单一所有者（道G task-23，O1 第二实例）：控制台串口数据寄存器同一时刻只允许
* 一个上下文在逐字节轮询写入。NULL = 空闲。
* ⚠ 这不是"锁"，是**所有权凭证**：拿不到就当场让路，绝不排队等待（见
* con_tx_try_claim 函数头：裸发一行 @115200 约 7.8 ms，把它包进临界区等于给
* 启动窗口塞进 7.8 ms 的中断延迟与最坏喂狗抖动，比交错本身更糟）。 */
/*
* 本模块"只有几条指令"的关中断窗口（道G task-26 收口时定，2026-10-26）
* ---------------------------------------------------------------------
* 刻意**不用** taskENTER_CRITICAL()/taskEXIT_CRITICAL()，改用 CMSIS 的 PRIMASK
* 保存 + 恢复。理由是一条只在**静态调用图**上看得见、真机上却很贵的坑：
* taskEXIT_CRITICAL() => vPortExitCritical() => configASSERT()
* => vApplicationAssertFailed() （本仓断言钩子自 2026-09-29 起就调
* dbg_console_write_raw 上报 file:line）
* => 又回到本模块 => 又进临界区
* armlink 因此在本模块周围长出三条互递归环（con_tx_try_claim => vPortExitCritical、
* dbg_console_write_raw => con_tx_release、con_ring_try => vPortExitCritical），并把
* 这坨算进**每一条含临界区的任务链**：实测 vApplicationAssertFailed 的 Max Depth 从
* 约 40 B 变 128 B + In Cycle，defaultTask 3,040->3,120、netTask 1,920->2,000、
* iec104Task 1,464->1,544 —— 三条同涨 80 B 就是"加深在共享帧上"的铁证，iec104 的
* margin 因此掉到 1,016 < 1,024 ISR 底线。
* 换成 PRIMASK 之后：
* ① 三个原语都是 core_cmFunc.h 里的静态内联 —— 零调用帧、零断言，那三条环不成立；
* ② **屏蔽面变宽是有意的**：本 port（RVDS/ARM_CM4F）的临界区走 BASEPRI，只挡
* 优先级数值 >= configMAX_SYSCALL_INTERRUPT_PRIORITY 的中断，PRIMASK 连更高
* 优先级的也一起挡（NMI 与 HardFault 除外）。这是**语义变强**，不是变弱；窗口
* 只有几条指令（一次 test-and-set / 一次清属主 / 一次整行入环拷贝，与换之前
* 同宽度同时长），代价是几微秒级的额外屏蔽，读代码的人必须知道这一点。
* ③ 不依赖调度器与 uxCriticalNesting，未注册期与中断里同样可用。
* ⚠ **为什么必须把 PRIMASK 存进局部变量、退出时原样写回，而不是直接 __enable_irq()**：
* 本模块的窗口可能嵌套在调用者已有的临界区里（断言/故障钩子、写者 drain 轮内的
* 留痕行都是）。无条件开中断 = **替别人把任务级临界区提前打开**，那是比交错严重
* 一个量级的竞态；保存/恢复则天然支持嵌套。保存量放局部而不是共享静态量，是因为
* 窗口可能被更高优先级上下文再次进入，共享量会被它改写、退出时就恢复错了。
* ⚠ 只允许包住"几条指令"的量级，**绝不允许**包住串口发送本身：一行 90 B @115200
* 约 7.8 ms，把它关进中断等于给启动窗口塞 7.8 ms 中断延迟与最坏喂狗抖动
* （红线与机器判据见 con_tx_bounded 函数头与主机单测 TC-CONLOG-015b 与 TC-CONLOG-177）。
*/
#define CON_CRIT_ENTER(pm_var) do { (pm_var) = __get_PRIMASK(); __disable_irq(); } while (0)
#define CON_CRIT_EXIT(pm_var) do { __set_PRIMASK(pm_var); } while (0)
static volatile TaskHandle_t s_con_tx_owner;
static volatile uint8_t s_con_tx_depth; /* 同一任务重入深度（drain 轮内的裸发留痕行） */
/* con_tx_try_claim 的三种结果（区分开是必要的：**放行**的那些上下文没有持有凭证，
* 绝不能在释放时把别人的所有权清掉） */
#define CON_TX_NO 0u /* 别人正持有整行 -> 调用方让路（不阻塞） */
#define CON_TX_BYPASS 1u /* 放行：本上下文不许等也无需凭证（ISR / 调度器未启动） */
#define CON_TX_HELD 2u /* 已持有：调用方发完必须 con_tx_release */
/*
* 函数功能：计算环形缓冲已用字节数（head-tail 差值回绕取模，无锁）
* 入口参数：无
* 返回值：已用字节数 uint16_t
*/
static uint8_t con_ring_try(const char *p_buf, uint16_t len);
/* 定义在下方 con_append 旁；裸发让路路径要用，故前置声明
* （ARMCC 对隐式声明报警告，本仓红线是 0 警告） */
static uint16_t con_used(void) {
return (uint16_t)((uint16_t)(s_con_head - s_con_tail) & (DBG_CON_RING_SIZE - 1U));
}
@@ -133,7 +240,7 @@ static void con_dwt_ensure(void) {
* 入口参数：u - USART 寄存器基址（调用方已判非 NULL） USART_TypeDef *
* p_buf - 待发数据；len - 字节数
* 返回值：HAL_OK - 已发出；HAL_TIMEOUT - 计数上界内未完成（本块放弃）
* 限定条件：USART1 已初始化
* 限定条件：控制台串口已初始化
* 函数说明：刻意不用 HAL_UART_Transmit——理由见 CON_TX_GUARD_MAX 处注释
* （tick 依赖不可信 + 其调用链污染所有任务的最坏栈链）
*/
@@ -163,12 +270,12 @@ static HAL_StatusTypeDef con_tx_counted(USART_TypeDef *u, const uint8_t *p_buf,
* 函数功能：有界裸发送（不依赖 uwTick / HAL 超时）
* 入口参数：p_buf - 待发数据；len - 字节数（调用方已限 ≤ DBG_CON_CHUNK_MAX）
* 返回值：HAL_OK - 已全部写入发送寄存器；HAL_TIMEOUT - 有界上界内未完成
* 限定条件：USART1 已初始化
* 限定条件：控制台串口已初始化
* 函数说明：寄存器级轮询 TXE/TC，超时判据用 DWT CYCCNT（CON_TX_TIMEOUT_CYC）；
* DWT 未使能时走 con_tx_counted（指令计数上界，2026-10-10 取代
* HAL_UART_Transmit 回退）。本函数只做 TX，
* 不触碰 RX/错误标志——僵尸通道自愈由调用方按返回值处理。
* ⚠ USART1 未初始化（huart1.Instance == NULL，如 HAL_Init 早期或
* ⚠ 控制台串口未初始化（CON_UART.Instance == NULL，如 HAL_Init 早期或
* 断言/故障上报路径）时立即返回 HAL_ERROR：否则会解引用 NULL 去读写
* 地址 0（flash 别名区）→ 在故障处理里再触发故障（2026-10-02 台架实测）。
*/
@@ -178,45 +285,181 @@ static HAL_StatusTypeDef con_tx_bounded(const uint8_t *p_buf, uint16_t len) {
uint16_t i;
con_dwt_ensure();
if (huart1.Instance == NULL) {
return HAL_ERROR; /* USART1 未初始化：无可用通道，安全让位 */
if (CON_UART.Instance == NULL) {
return HAL_ERROR; /* 控制台串口未初始化：无可用通道，安全让位（不是超时，不记超时账） */
}
if (s_con_dwt_up == 0U) {
return con_tx_counted(huart1.Instance, p_buf, len);
return con_tx_counted(CON_UART.Instance, p_buf, len);
}
u = huart1.Instance;
u = CON_UART.Instance;
t0 = DWT->CYCCNT;
for (i = 0U; i < len; i++) {
while ((u->SR & USART_SR_TXE) == 0U) {
if ((uint32_t)(DWT->CYCCNT - t0) >= CON_TX_TIMEOUT_CYC) {
return HAL_TIMEOUT; /* 有界：本块放弃（调用方自愈） */
return HAL_TIMEOUT; /* 有界：本块放弃（记账由调用方按返回值做） */
}
}
u->DR = (uint16_t)p_buf[i];
}
while ((u->SR & USART_SR_TC) == 0U) {
if ((uint32_t)(DWT->CYCCNT - t0) >= CON_TX_TIMEOUT_CYC) {
return HAL_TIMEOUT;
return HAL_TIMEOUT; /* TC 超时：字节已交给发送器，调用方分账 */
}
}
return HAL_OK;
}
/*
* 函数功能：控制台裸发送（异常/早期路径专用：有界、单次、不加锁）
* 函数功能：尝试取得"控制台串口整行发送所有权"（**非阻塞**，道G task-23）
* 返回值：CON_TX_HELD 已持有（发完必须 con_tx_release）/ CON_TX_BYPASS 放行且不记账
* / CON_TX_NO 别人正持有整行，调用方须让路
* 限定条件：任意上下文（内部只有一次几条指令的临界区，绝不睡眠、绝不长期关中断）
* 函数说明：三条规则各有硬理由，改动前请连读 docs/子系统设计/控制台单写者日志设计说明.md
* 的「行级单一所有者」一节：
* ① IPSR != 0（异常/中断，含四个 Fault 的崩溃上报）-> **放行**：这些上下文不许阻塞，
* 且一发生就要复位，日志是唯一遗言，绝不允许在这里"让路"掉。已知残余（登记在同一
* 篇文档）：ISR 可以打断某任务已发出半行的裸发，两侧仍可能交错——但 Fault 行以
* "[ERR]" 起头且整段在同一次 con_tx_bounded 内，标记校验按字节 grep 仍能命中，
* 不构成漏检；把钩子改成"一条行一次发完"是另一张卡的活（API 已备：tx_begin/tx_end）。
* ② 调度器未启动（xTaskGetCurrentTaskHandle() == NULL，osKernelStart 之前）-> **放行**：
* 此刻全系统只有一个执行流，本就没有第二个写者；早期启动日志一条都不该丢。
* ③ 已调度且空闲 -> 临界区里"看 + 认领"（几条指令），拿到即整行独占；已被持有 ->
* 立刻返回 CON_TX_NO，**不排队**：裸发一行 @115200 约 7.8 ms，等锁等于把自己的
* 日志节拍压到别人的串口耗时上，adcTask（AboveNormal，1 kHz 消费）可能被压住
* 数十拍，比交错更糟。
*/
static uint8_t con_tx_try_claim(void) {
TaskHandle_t me;
uint32_t pm;
uint8_t got = 0U;
if (__get_IPSR() != 0U) {
return (uint8_t)CON_TX_BYPASS;
}
me = xTaskGetCurrentTaskHandle();
if (me == NULL) {
return (uint8_t)CON_TX_BYPASS;
}
if (s_con_tx_owner == me) {
if (s_con_tx_depth < 255U) {
s_con_tx_depth++;
}
return (uint8_t)CON_TX_HELD;
}
CON_CRIT_ENTER(pm); /* 窗口选型与嵌套语义理由见 CON_CRIT_ENTER 定义处 */
if (s_con_tx_owner == NULL) {
s_con_tx_owner = me;
s_con_tx_depth = 1U;
got = 1U;
}
CON_CRIT_EXIT(pm);
return (got != 0U) ? (uint8_t)CON_TX_HELD : (uint8_t)CON_TX_NO;
}
/*
* 函数功能：归还整行发送所有权（与 con_tx_try_claim 成对）
* 入口参数：held - con_tx_try_claim 的返回值（只有 CON_TX_HELD 才真正归还）
* 返回值：无
* 限定条件：与取锁同上下文；CON_TX_BYPASS / CON_TX_NO 一律空操作——放行的那些上下文
* 从未持有凭证，误清会把别人正持有的整行放开，等于把这次修复改没
* 函数说明：同任务嵌套按深度递减（写者一轮 drain 内还会再裸发 [WARN]/[ERR] 留痕行，
* 那是嵌套持有者，最外层释放时才清 owner）
*/
static void con_tx_release(uint8_t held) {
TaskHandle_t me;
uint32_t pm;
if (held != (uint8_t)CON_TX_HELD) {
return;
}
me = xTaskGetCurrentTaskHandle();
if (s_con_tx_owner != me) {
return;
}
if (s_con_tx_depth > 1U) {
s_con_tx_depth--;
return;
}
CON_CRIT_ENTER(pm);
if (s_con_tx_owner == me) {
s_con_tx_owner = NULL;
s_con_tx_depth = 0U;
}
CON_CRIT_EXIT(pm);
}
/*
* 函数功能：把"一条行分几段裸发"的调用方收成一个整行独占者（道G task-23）
* 返回值：1 - 已独占（此后本任务每次 dbg_console_write_raw 都直接发，段间无人插入）
* 0 - 别人正持有；调用方**照发即可**（本函数不改变任何调用方的既有语义，
* 绝不阻塞、绝不吞字，只是段间仍可能被插——调用方自己权衡）
* 限定条件：任务上下文（ISR 内调用会返回 1 但不记账，见 con_tx_try_claim ①）
* 函数说明：给多段裸发的诊断/崩溃钩子用（Src/freertos.c 的钩子把一条行拆成
* head/name/":"/" (resetting)" 等多次直发，段与段之间就是插字节的位置）。
* 配对使用：tx_begin() -> 若干次 write_raw -> tx_end()。嵌套安全（按深度计）。
*/
uint8_t dbg_console_tx_begin(void) {
uint8_t held = con_tx_try_claim();
return (held == (uint8_t)CON_TX_NO) ? 0U : 1U;
}
/*
* 函数功能：结束一次整行独占（与 dbg_console_tx_begin 成对）
* 入口参数：无
* 返回值：无
* 限定条件：只在 dbg_console_tx_begin() 之后调用；未持有时为空操作（幂等）
*/
void dbg_console_tx_end(void) {
con_tx_release((uint8_t)CON_TX_HELD);
}
/*
* 函数功能：控制台裸发送（异常/早期路径专用：有界、单次；**整行独占发送器**）
* 入口参数：buf - 文本缓冲；len - 字节数（超上限截断）
* 限定条件：串口已初始化；仅用于写者未注册、中断/异常上下文、崩溃上报
* 返回值：无
* 限定条件：串口已初始化；写者未注册、中断/异常上下文、崩溃上报、诊断转储
* 函数说明：走 con_tx_bounded（DWT 硬上界），tick 停摆时仍能在有界时间内返回。
* 道G task-23 起本函数是裸发的**唯一漏斗**（所有裸发调用点都经过它，所以调用方
* 文件一个都不用改）：
* · 拿到所有权 -> 整行一次发完，中途不会有别人的字节插进来；
* · 拿不到 -> **本行不丢**，改投既有环形缓冲延后发。竞争失败不该变成丢行，更不该
* 变成 [ERR]：台架那个未注册窗口每 3 次启动命中 2 次，按"丢弃 + [ERR]"处理只会
* 把静默缺陷换成常红的门禁（[ERR] 是 /serial-boot-test 的 Forbidden 标记）。
* 入环的是**同一批字节原文**，本模块与 drain 都不补前缀、不重打时间戳（DBG_* 的
* 前缀在调用点就已 snprintf 进调用方缓冲）-> 延后发出去的行与它当场直发时
* 逐字节相同（判据⑦），取证时不会出现"证据说谎"；
* · 环也放不下 -> 这才计入既有 s_con_drop（真溢出，仍然可见，不静默）；
* · ISR / 调度器未启动 -> 放行直发（con_tx_try_claim ①②）。
*/
void dbg_console_write_raw(const char *buf, unsigned len) {
uint8_t held;
if ((buf == NULL) || (len == 0U)) {
return;
}
if (len > DBG_CON_CHUNK_MAX) {
len = DBG_CON_CHUNK_MAX;
}
held = con_tx_try_claim();
if (held == (uint8_t)CON_TX_NO) {
if (con_ring_try(buf, (uint16_t)len) != 0U) {
/* 延后发：写者空出来就排出去（未注册时也一样——注册后第一轮 drain 就发）。
* 唤醒事件只在事件组已建时发（内核前 sys_evtHandle 还是 NULL） */
if (sys_evtHandle != NULL) {
(void)osEventFlagsSet(sys_evtHandle, SYS_EVT_CONSOLE_TX);
}
} else {
s_con_drop++; /* 让了路又放不下环 = 真丢，进既有那本账 */
}
return;
}
(void)con_tx_bounded((const uint8_t *)buf, (uint16_t)len);
con_tx_release(held);
}
/*
@@ -242,20 +485,24 @@ uint8_t dbg_console_writer_ready(void) {
}
/*
* 函数功能：USART1 僵尸通道自愈（清错误锁存 + 整外设重初始化）
* 函数说明：RX 悬空噪声（PA10 未接线）锁存的 ORE/NE/FE/PE 使 HAL 轮询 TX 恒快速失败
* （控制台静默、系统不复位）；发送器卡死状态则使 TXE 等待耗满超时（冻结唯一
* 写者 → 看门狗误复位，2026-10-02 台架实证）。外设软复位清锁存与卡死状态后
* 重新初始化，故障时间被单块超时限定
* 函数功能：控制台串口僵尸通道自愈（清错误锁存 + 整外设重初始化）
* 函数说明：**RX 使能了却从不读 DR** → 线上任意一个字节或一个噪声沿使 RXNE 置位后无人读，
* 下一个事件即锁存 ORE（常伴 NE/FE/PE）；ORE 只能靠"先读 SR 再读 DR"清除 ⇒ 永不自愈。
* 锁存后 HAL 轮询 TX 恒快速失败（控制台静默、系统不复位）；发送器卡死状态则使 TXE
* 等待耗满超时（冻结唯一写者 → 看门狗误复位，2026-10-02 台架实证）。外设软复位清锁存与卡死状态后
* 重新初始化，故障时间被单块超时限定。
* ⚠ 2026-10-28 更正：原注释把根因写成"PA10 未接线 / 悬空"，用户确认 PA10 一直是接线的；
* 充分条件是"RX 使能却不消费 DR"，与引脚是否悬空无关
* （详见 docs/子系统设计/控制台单写者日志设计说明.md §12）。
*/
static void con_uart_reinit(void) {
__NVIC_ClearPendingIRQ(USART1_IRQn);
__HAL_RCC_USART1_CLK_DISABLE();
__HAL_RCC_USART1_CLK_ENABLE();
huart1.gState = HAL_UART_STATE_RESET;
huart1.RxState = HAL_UART_STATE_RESET;
huart1.ErrorCode = HAL_UART_ERROR_NONE;
(void)MX_USART1_UART_Init();
__NVIC_ClearPendingIRQ(CON_UART_IRQN);
CON_UART_CLK_DISABLE();
CON_UART_CLK_ENABLE();
CON_UART.gState = HAL_UART_STATE_RESET;
CON_UART.RxState = HAL_UART_STATE_RESET;
CON_UART.ErrorCode = HAL_UART_ERROR_NONE;
(void)CON_UART_INIT();
}
/*
@@ -268,6 +515,7 @@ static void con_uart_reinit(void) {
void dbg_console_drain(void) {
uint16_t used;
uint32_t t0;
uint8_t held;
if (s_con_writer_up == 0U) {
return;
@@ -276,18 +524,32 @@ void dbg_console_drain(void) {
return; /* 重入保护：写者自记录不触发嵌套 drain */
}
/* 整行所有权（道G task-23）：本函数按块直写 CON_UART->DR，若此刻别的应用上下文
* 还在未注册期那条裸发里发到自己一半（attach 就发生在 defaultTask 里，与别的
* 任务裸发**可以**前后脚撞上），两边就会逐字节交错——那正是本卡要修的形态。
* 拿不到就**本轮让位**：tail 不推进 => 环里一条不少，主循环 ≤50 ms 后再试，
* 所以这条路径**永不丢弃**，也就不该在这里加任何计数（加了就是把让位谎报成丢行）。 */
held = con_tx_try_claim();
if (held == (uint8_t)CON_TX_NO) {
return;
}
s_con_draining = 1U;
t0 = (uint32_t)HAL_GetTick();
/* 故障冷却：僵尸通道（ORE 重锁）秒内不自愈，冷却期内不发送——
* 本轮 drain 直接让位主循环，保住喂狗节奏（gen-288 停喂误复位的
* 直接诱因 = 背靠连发的块超时链）。无符号差值跨 49.7 天回绕安全 */
if (s_con_cool_until != 0U) {
* 本轮 drain 直接让位主循环，保住喂狗节奏（日志代次 288 停喂误复位的
* 直接诱因 = 背靠连发的块超时链）。是否在冷却看 s_con_cooling 独立标志，
* **不再拿 tick 值当哨兵**（2026-10-24 实测：故障恰好落在 tick==0 那一拍时，旧写法
* 记出的 cool_until==0 等于没记冷却，下一轮立刻再耗一次 100ms 块超时）。
* 无符号差值跨 49.7 天回绕安全 */
if (s_con_cooling != 0U) {
if ((uint32_t)(t0 - s_con_cool_until) < DBG_CON_FAULT_COOL_MS) {
s_con_draining = 0U;
con_tx_release(held); /* 让位也要归还凭证，否则别人永远进不来 */
return;
}
s_con_cool_until = 0U;
s_con_cooling = 0U;
}
while ((used = con_used()) != 0U) {
@@ -309,12 +571,28 @@ void dbg_console_drain(void) {
taskEXIT_CRITICAL();
if (st != HAL_OK) {
if (st == HAL_ERROR) {
/* 2026-10-24 修复：控制台串口 **未初始化**（CON_UART.Instance == NULL，
* 只可能出现在 HAL_Init 早期或断言/故障上报路径）与"僵尸通道"是两回事：
* 这里**绝不做外设重初始化**——那会在 HAL 尚未就绪时跑 MspInit 重配
* RCC/GPIO；也不计 tx_fault（那本账的语义是"软复位自愈次数"）。
* 本块字节确实一个都没上线 -> 计入 dropped（只记真丢的），
* 末尾的 [ERR] dropped 行负责留痕；本轮到此为止（失败即止）。 */
s_con_drop++;
break;
}
/* 僵尸通道：软复位自愈 + 进入发送冷却（ORE 毫秒级重锁，
* 继续背靠连发只会把主循环耗在块超时链上）；本块丢弃
* （行已出环，不可重放） */
* （行已出环，不可重放），本块在超时账与丢弃账上各记一笔 */
s_con_tx_timeout++; /* 新增账：块超时次数（TXE 与 TC 两条硬上界
* 都算，口径 = 写者排空时观察到的块超时） */
con_uart_reinit();
s_con_tx_fault++;
s_con_drop++; /* 确认不了的块算真丢（一次丢弃事件），
* 旧写法只涨 tx_fault -> 账上看不出日志在丢，
* docs §13-O2 记的正是这条 */
s_con_cool_until = (uint32_t)HAL_GetTick();
s_con_cooling = 1U;
if (s_con_tx_fault == 1U) {
static const char note[] = "\r\n[WARN] CONSOLE tx fault: UART reinit (self-healed)\r\n";
@@ -338,31 +616,96 @@ void dbg_console_drain(void) {
s_con_draining = 0U;
/* 丢弃可观测性：缓冲满丢行必须显式可见（否则会掩盖开机自检/测试标记的丢失） */
/* 丢弃可观测性：缓冲满丢行必须显式可见（否则会掩盖开机自检/测试标记的丢失）。
* 账上有两种成因，都算"真没落地"：① 环满等不到空位（con_append）；② 抢不到整行
* 所有权**且**环也放不下（dbg_console_write_raw，道G task-23）。正常让路不入这本账，
* 所以 [ERR] 行至今仍是"控制台在丢东西"的唯一信号，没被稀释。 */
if (s_con_drop != 0U) {
char note[64];
uint32_t d = s_con_drop;
int n;
s_con_drop = 0U;
n = snprintf(note, sizeof(note), "\r\n[ERR] CONSOLE dropped %lu lines\r\n",
(unsigned long)d);
if (n > 0) {
if (n > (int)sizeof(note) - 1) {
n = (int)sizeof(note) - 1;
}
dbg_console_write_raw(note, (unsigned)n);
/* 只有**真发出去了才销账**（2026-10-24 一并修正）：旧写法先把计数清零
* 再裸发，通道不可用/僵尸时那一发也失败 -> 丢弃证据被一起冲掉，[ERR] 行
* 永远出不来（"永不静默"变成"永不显示"）。留到下一轮或串口恢复后补发。 */
/* 所有权仍在手里（本凭证覆盖整轮，含这条留痕行） */
if (con_tx_bounded((const uint8_t *)note, (uint16_t)n) == HAL_OK) {
/* 按"本次报出去的这条"扣账而不是清零：期间生产者新丢的行留下轮报。
* 递减只发生在这一处（单写者 + s_con_draining 重入保护），生产者只增，
* 故 s_con_drop >= d 恒成立，无需再写下溢分支（写了也永远测不到）。 */
s_con_drop -= d;
}
}
}
con_tx_release(held);
}
/*
* 函数功能：尝试把一整行原文放进环形缓冲（**只试一次，绝不等待**）
* 入口参数：p_buf - 整行文本；len - 字节数（调用方已钳位）
* 返回值：1 - 已入环（head 已推进）；0 - 空位不够，什么都没写
* 限定条件：任务上下文（内部是一次几条指令至多拷满 192B 的临界区，不睡眠）
* 函数说明：两个调用方共用同一份判据，避免长出"两套入环语义"：
* ① con_append 的常规路径（外面套有界等待，等写者腾位）；
* ② dbg_console_write_raw 抢不到整行所有权时的让路路径（**不套等待**：延后发一条行
* 可以，把调用者压住 200ms 就是另一场事故）。
* 复核空位 + 整行拷贝 + 推进 head **必须在同一个临界区内**（2026-10-24 修复）：旧写法
* 先出区判 free_space >= len 再进区写，两个生产者可在环 >95% 满时同时过判据，head
* 合计越过容量 -> con_used() 回绕变小 -> 后写的行覆盖尚未发出的旧行，且既不报错也不
* 计丢弃（静默损坏）。等待（vTaskDelay/DWT 判据）刻意留在区外。
* ⚠ 入环的是调用方给的**字节原文**：本函数与 drain 都不补前缀、不重打时间戳
* （DBG_* 的前缀在调用点就已 snprintf 进调用方缓冲）——延后发与当场直发逐字节
* 相同，这是 task-23 判据⑦的结构保证。
*/
static uint8_t con_ring_try(const char *p_buf, uint16_t len)
{
uint32_t pm;
uint8_t fitted = 0U;
/* 窗口用 PRIMASK 而不是 taskENTER_CRITICAL()：后者会经 vPortExitCritical 里的
* configASSERT 接回断言钩子，再回到本模块，静态调用图上长出一条环，armlink 把它
* 整条记进**每一条含临界区的任务链**（实测三条链同涨 80 B）。理由全文见
* CON_CRIT_ENTER 定义处。屏蔽时长与换之前一致（就是这一次整行拷贝）。 */
CON_CRIT_ENTER(pm);
if ((uint16_t)((DBG_CON_RING_SIZE - 1U) - con_used()) >= len) {
uint16_t head = s_con_head;
uint16_t first = (uint16_t)(DBG_CON_RING_SIZE - head);
uint16_t i;
if (first > len) {
first = len;
}
for (i = 0U; i < first; i++) {
s_con_ring[head + i] = (uint8_t)p_buf[i];
}
for (i = first; i < len; i++) {
s_con_ring[(uint16_t)((uint16_t)(head + i) & (DBG_CON_RING_SIZE - 1U))] =
(uint8_t)p_buf[i];
}
s_con_head = (uint16_t)((uint16_t)(head + len) & (DBG_CON_RING_SIZE - 1U));
fitted = 1U;
}
CON_CRIT_EXIT(pm);
return fitted;
}
/*
* 函数功能：把一段文本放入控制台（写者已注册）/直接发出（未注册或中断上下文）
* 返回值：0 - 已入缓冲或已直发；-1 - 缓冲满丢弃（计入 dbg_console_dropped）
* 函数说明：生产者不持锁等待过久：最多 DBG_CON_WAIT_MS，仍满则丢弃该行；
* "复核空位 -> 整行拷贝 -> 推进 head"是一个原子的临界区动作；
* 环满等待（vTaskDelay / DWT 判据）一律在临界区之外，区内绝不睡眠。
* 写者自身记录日志时先排空缓冲，避免自等。
* 等待上界优先用 DWT 真实时间（CON_APPEND_WAIT_CYC，时间源无关）——
* tick 停摆时 vTaskDelay 本身也会停，故不能用它作唯一判据（round 8b）。
* tick 停摆时 vTaskDelay 本身也会停，故不能用它作唯一判据（第 8b 轮加固）。
*/
static int con_append(const char *buf, uint16_t len) {
uint32_t waited = 0U;
@@ -392,10 +735,9 @@ static int con_append(const char *buf, uint16_t len) {
}
for (;;) {
uint16_t used = con_used();
uint16_t free_space = (uint16_t)((DBG_CON_RING_SIZE - 1U) - used);
if (free_space >= len) {
/* 判据与拷贝都在 con_ring_try 的那一个临界区里完成（函数头有为什么）；
* 本函数只负责"等多久"——等待一律在区外，区内绝不睡眠 */
if (con_ring_try(buf, len) != 0U) {
break;
}
if (have_dwt != 0U) {
@@ -411,26 +753,6 @@ static int con_append(const char *buf, uint16_t len) {
waited++;
}
taskENTER_CRITICAL();
{
uint16_t head = s_con_head;
uint16_t first = (uint16_t)(DBG_CON_RING_SIZE - head);
uint16_t i;
if (first > len) {
first = len;
}
for (i = 0U; i < first; i++) {
s_con_ring[head + i] = (uint8_t)buf[i];
}
for (i = first; i < len; i++) {
s_con_ring[(uint16_t)((uint16_t)(head + i) & (DBG_CON_RING_SIZE - 1U))] =
(uint8_t)buf[i];
}
s_con_head = (uint16_t)((uint16_t)(head + len) & (DBG_CON_RING_SIZE - 1U));
}
taskEXIT_CRITICAL();
if (sys_evtHandle != NULL) {
(void)osEventFlagsSet(sys_evtHandle, SYS_EVT_CONSOLE_TX); /* 唤醒写者 */
}
@@ -472,6 +794,23 @@ uint32_t dbg_console_tx_fault(void) {
return s_con_tx_fault;
}
/*
* 函数功能：已发生的发送块超时次数（诊断用）
* 返回值：块超时累计次数 uint32_t
* 限定条件：无（任意上下文可读，含 ISR）
* 函数说明：三本账分开（docs/子系统设计/控制台单写者日志设计说明.md §13-O2）——
* dbg_console_dropped() = **真没落地**的丢弃数（缓冲满丢的一行，或一个
* 没能确认送达而出环的块；[ERR] 行报的就是它）；
* dbg_console_tx_fault() = 外设软复位**自愈次数**（语义不变）；
* dbg_console_tx_timeout() = 本账：写者排空时观察到的**块超时**次数
* （TXE 与 TC 两条硬上界都算）。
* 裸发路径（内核前 / ISR / 两条告警行自身）的超时不记本账——那些上下文里
* 没有"块"的概念，也只可能发生在启动极早期，混进来只会让运维读数失去意义。
* UART 物理失效但字节已发出的情形只涨本账，不污染另两本。 */
uint32_t dbg_console_tx_timeout(void) {
return s_con_tx_timeout;
}
/*
* 函数功能：取走"控制台 TX 故障待上报"标志（读后清）
* 返回值：1 - 需要补记一条 run.log 证据，0 - 无
App/log/console_log.h
+22 -4
View File
@@ -1,5 +1,5 @@
/*
* 模块名称：Console Single-Writer Logging — 控制台单写者日志（USART1 调试串口）
* 模块名称：Console Single-Writer Logging — 控制台单写者日志（RS232#1 / UART5）
* 模块功能：调试控制台单写者环形缓冲的公共 API：所有任务/上下文（含 printf）只把
* 已格式化整行文本入环形缓冲，写者任务（defaultTask）为唯一
* HAL_UART_Transmit 发送点（行级原子 + 指针可控）
@@ -15,6 +15,9 @@
* 修改记录：
* 2026-09-24 王建锋 创建（自 Src/usart.c USER CODE 区迁出：
* HAL 库生成文件不得包含应用代码）
* 2026-10-26 王建锋 道G task-23：裸发路径加「行级单一所有者」（O1 第二实例），
* 新增 dbg_console_tx_begin()/dbg_console_tx_end() 供"一条行分多段裸发"
* 的调用方收口；dbg_console_write_raw() 的"不加锁"三个字从接口上取消
*/
#ifndef CONSOLE_LOG_H
@@ -32,15 +35,27 @@ extern "C" {
* dbg_console_write_line - 生产者入口：调用方已格式化好的整行文本一次入环形缓冲
* （刻意**不用**自研可变参数函数——规范 S12 7.6 禁止；格式化在
* DBG_PRINT 宏内用库 snprintf 完成）
* dbg_console_write_raw - 异常/早期路径：有界单次直发（不加锁）
* dbg_console_write_raw - 异常/早期路径：有界单次直发；**整行独占发送器**
* （道G task-23：拿不到独占就把整行原文转入环形缓冲延后发，
* 与当场直发逐字节相同——不补前缀、不重打时间戳；
* 连环都放不下才计入 dbg_console_dropped()）
* dbg_console_writer_attach- 写者任务（defaultTask）注册自己为唯一发送者
* dbg_console_writer_ready - 写者是否已注册（1=已注册）。供**周期性任务**在写者就绪前
* 抑制日志用：写者未注册时 con_append 走无锁直发路径
* （仅假设 defaultTask 在日志），其余任务此时落日志会与
* defaultTask 的存储初始化日志字节级交错（2026-10-10 台架实测）
* dbg_console_drain - 写者任务排空缓冲并发送（单次有界；TX 失败自动软复位自愈）
* dbg_console_dropped - 因缓冲满丢弃的行数（诊断）
* dbg_console_tx_fault - 因僵尸通道软复位自愈的次数（诊断）
* dbg_console_dropped - 真没落地的丢弃数：① 缓冲满丢的一行；② 一个没能确认
* 送达而出环的块；③ 抢不到整行所有权**且**环也放不下的裸发
* （道G task-23）。诊断；[ERR] CONSOLE dropped 行报的就是它。
* ⚠ 抢不到所有权但成功让路入环的那条行**不入本账**（它没丢，
* 只是晚一点发）——这本账必须保持"红得有意义"，因为
* [ERR] 是 /serial-boot-test 的 Forbidden 标记）
* dbg_console_tx_fault - 因僵尸通道软复位自愈的次数（诊断，语义不变）
* dbg_console_tx_timeout - 写者排空时观察到的块超时次数（TXE / TC 两条硬上界都算）。
* 三本账分开：看日志有没有在丢 -> dropped；看外设自愈了几次
* -> tx_fault；看 UART 物理失效（含"字节已发出但 TC 不置位"）
* -> tx_timeout。别把三本账混成一个数（docs §13-O2 ）
* dbg_console_tx_fault_log_take
* - 取走"TX 故障待上报"标志（读后清）。**必须**由写者任务在
* dbg_console_drain() 之外调用后自行 syslog_post——本模块
@@ -50,11 +65,14 @@ extern "C" {
#define DBG_CON_LINE_MAX 192U /* 单行文本上限（含结尾 '\0'，超出截断） */
int dbg_console_write_line(const char *line, unsigned len);
void dbg_console_write_raw(const char *buf, unsigned len);
uint8_t dbg_console_tx_begin(void); /* 1=已独占一条行；0=别人持有（调用方照发即可） */
void dbg_console_tx_end(void); /* 与 tx_begin 成对；未持有时空操作（幂等） */
void dbg_console_writer_attach(void);
uint8_t dbg_console_writer_ready(void);
void dbg_console_drain(void);
uint32_t dbg_console_dropped(void);
uint32_t dbg_console_tx_fault(void);
uint32_t dbg_console_tx_timeout(void);
uint8_t dbg_console_tx_fault_log_take(void);
/*
App/log/soe_rec.h
+9 -3
View File
@@ -2,9 +2,9 @@
* 模块名称：SOE Record — 事件顺序记录编解码（纯逻辑，双端可测）
* 模块功能：定长 64B SOE（Sequence-of-Events）记录的构建与解析：
* CP56Time2a 时标 + 记录类型 + 元件号 + 单调序号 + 值 + 校验和。
* **零 I/O、零 OS 依赖**（仅 stdint/string）→ 主机侧 L0.5 离线单测
* （落实登记簿 A-4 约束 1"协议/记录与硬件 I/O 分离"）。
* 记录口径（docs/算法/继电保护功能复现规划.md §3.4 L4-4/L4-5，B9）：
* **零 I/O、零 OS 依赖**（仅 stdint/string）→ 主机侧纯逻辑离线单测
* （分层约束：协议/记录与硬件 I/O 分离）。
* 记录口径（docs/算法/继电保护功能复现规划.md §3.4「SOE 记录」「动作记录」，B9）：
* 落盘文件 = /log/soe.log（8.3 合规；FF_USE_LFN=0 约束），定长 64B 一条
* （照 run.log 先例：count = filesize/64 O(1)、容量满删除重建）。
* 独立于 run.log 的理由：run.log 是文本记录（时间戳+epoch+UTF-8 描述，
@@ -61,6 +61,8 @@ extern "C" {
* 4 软压板投入 value = 1
* 5 采样闭锁 value = adc_health 闭锁位图（触发时的 hf & mask）
* 6 采样恢复 value = 0
* 7 标定闭锁 value = UA/UN/IA VALID 未齐的通道位图（未标定即闭锁，2026-10-25）
* 8 标定复归 value = 0
*/
typedef enum {
SOE_T_ELM_ASSERT = 1u,
@@ -69,6 +71,10 @@ typedef enum {
SOE_T_PLATE_IN,
SOE_T_SAMPLE_BLOCK,
SOE_T_SAMPLE_RESUME,
/* 未标定闭锁（「数据可信」未标定即闭锁一项，2026-10-25 道A 追加）：UA/UN/IA 的 VALID
* 未全置位 → 判据停走；与采样闭锁分型，边沿各留一条记录 */
SOE_T_CAL_BLOCK,
SOE_T_CAL_RESUME,
SOE_T_COUNT /* 哨兵值，非有效类型 */
} soe_type_t;
App/log/soe_store.c
+183 -5
View File
@@ -3,6 +3,16 @@
* 模块功能：实现 soe_store.h——protectTask 投递（取时标 + soe_rec_build +
* SPSC 待发环 / 消息队列，零 FS）；defaultTask（syslog_drain 尾部）
* 排空落 /log/soe.log（64B 定长，容量满删除重建）。
* 修改记录：
* v1.0 2026-10-12 王建锋 创建初始版本（B9，设计见 docs/算法/继电保护功能复现规划.md §3.4）
* v1.1 2026-10-24 王建锋 仅注释/文档更正（D 项，无行为改动）：s_soe_append
* 函数头原写"打开/写入结构性错误 → unlink 重试一次
* （同 run.log）"，与实现不符且方向错误——实现里
* f_open 失败直接返回 -1、不 unlink，这是**有意**的：
* SOE 是事件序列，打开失败就删文件等于销毁已发生的
* 事件。改为如实描述"仅写失败才重试一次"，并补上
* 与 sys_log_mcu.c s_is_selfheal_code 同源的逐码表
* （名字/参数类错误码两侧都绝不 unlink）
* 创建日期：2026-10-12（B9）
*/
@@ -38,6 +48,16 @@ static osMessageQueueId_t s_queue; /* 运行期队列（drain 首次调
static const osMessageQueueAttr_t s_queue_attr = { .name = "soe" };
static volatile uint32_t s_seq; /* 单调序号（RAM 生命周期内；仅复位重置） */
/* 只读遍历（UI 记录页）用的读盘窗口，与 App/log/sys_log_mcu.c 读侧同构：
* 定长记录按 8 条一窗整块取回（8 × 64 B = 512 B），命中窗口零 I/O；
* 代数由写者在卷锁区间内自增，读者也在卷锁区间内采样代数 → 窗口不会跨写失效 */
#define SOE_RD_WINDOW 8u
static uint8_t s_rd_win[SOE_RD_WINDOW][SOE_REC_SIZE];
static uint32_t s_rd_win_base;
static uint32_t s_rd_win_cnt;
static volatile uint32_t s_rd_gen; /* 写者落盘/重建次数（对齐 32 位读写在 ARM 上原子） */
static uint32_t s_rd_win_gen;
static volatile uint32_t s_drop_cnt; /* 丢弃计数（队列满/环满） */
static uint32_t s_drop_logged; /* 丢弃留痕水位（drain 侧差值上报） */
static uint8_t s_fault_reported; /* 写故障留痕去重（成功写复位） */
@@ -88,6 +108,30 @@ void soe_store_post(uint8_t type, uint8_t elm_id, uint32_t value) {
}
}
/*
* ── 自愈触发集逐码依据（与 sys_log_mcu.c 的同名资料块同源；2026-10-24 逐条核对
* Lib/FatFs/ff.c）─────────────────────────────────────────────────────────
* 进触发集（run.log 侧允许 unlink 重建一次）：介质/结构类 FR_DISK_ERR(1) /
* FR_INT_ERR(2) / FR_NO_FILESYSTEM(13) / FR_DENIED(7)。本模块**只在写失败路径**
* 上碰自己的文件——打开失败连这些码也不 unlink。
* 不算自愈：FR_NO_FILE(4)——带 FA_OPEN_APPEND 打开时文件会被直接建出来；返回本
* 码的唯一现实场景是同名对象是目录（ff.c:3854），unlink 修不好它。
* 两侧都绝不 unlink：名字/参数类 FR_INVALID_NAME(6) / FR_NO_PATH(5) /
* FR_INVALID_OBJECT(9)，以及 FR_NOT_READY(3) / FR_NOT_ENABLED(12) /
* FR_TIMEOUT(15)——同名同因，删了也修不好，反而每轮丢一份历史（§10.1 第 10 条
* 严禁的正是这种归集）。
* 写失败路径不接这套判定：f_write 的返回码里不存在名字/参数类（能走到那里说明
* 已经打开成功），而簇分配失败是 FR_OK + 短写、根本没有错误码可判，只能无条件
* 重试一次。
* 为什么 SOE 比 run.log 保守（两侧资料块各写一份、互指，改动必须同步）：run.log
* 是滚动运行日志，坏了重建损失有限；SOE 是**事件序列**，文件里是一条条已经发生
* 过的保护事件，"打开失败就删整个历史文件"等于**销毁事件证据**——SOE 的存在就
* 是为了留这些事件，删了比写不进去更糟。正确出路是等 syslog_mcu_mounted() 每 2s
* 重试补目录 / 等卷恢复，条目留在待发环与队列里，不丢。
* （run.log 侧的同一张表 + 同一理由见 App/log/sys_log_mcu.c 的同名资料块，测试
* 侧两侧对齐由 TC-SYSLOG-101/102 与 TC-SOESTORE-022/022b 分别钉住。）
*/
/*
* 函数功能：追加一条 64B SOE 记录到 /log/soe.log
* 入口参数：rec - 完整记录（SOE_REC_SIZE 字节） const uint8_t *
@@ -98,11 +142,20 @@ void soe_store_post(uint8_t type, uint8_t elm_id, uint32_t value) {
* ② FA_WRITE|FA_OPEN_APPEND（本移植 OPEN_APPEND 不含 WRITE，
* 缺写位 f_write 恒 FR_DENIED，2026-09-20 实证）；
* ③ 判失败必须校验写回字节数（FR_OK+短写 = 失败，簇分配无错误码）；
* ④ 容量满 unlink 重建；打开/写入结构性错误 → unlink 重试一次
* （L1 文件级自愈，同 run.log）。
* ④ 容量满 unlink 重建；**仅写入失败（含 FR_OK+短写）才 unlink 重试
* 一次**——f_open 失败一律直接返回 -1、不 unlink。
* （2026-10-24 定案：本条旧注释写的是"打开/写入结构性错误都 unlink
* 重试一次（同 run.log）"，与实际实现不符，也与本模块的语义相反：
* run.log 是**滚动运行日志**，坏了重建损失有限；SOE 是**事件序列**，
* 文件里是已经发生的事件，打开失败就把整个历史文件删掉等于销毁
* 证据，方向是错的。正确出路是让 syslog_mcu_mounted() 每 2s 重试
* 补目录/等卷恢复，条目留在待发环与队列里，不丢。）
* ⑤ 自愈触发集与 sys_log_mcu.c 的 s_is_selfheal_code() 同源，但本模块取
* 更保守的子集：打开失败**任何错误码都不 unlink**，只有写失败才重试
* 一次。逐码依据与两侧差异见上方同名资料块。
* ⚠ 本模块**没有**任何"卷损坏"归类/重格式化路径：unlink 失败、
* 名字/参数类错误码一律只留痕（存储架构 §10.1 教训），条目丢弃
* 计数，绝不升级成卷操作。
* 计数，绝不升级成卷操作（全模块无 f_mount/f_mkfs/f_opendir）。
*/
static int s_soe_append(const uint8_t *rec) {
static FIL f; /* static：FF_FS_TINY=0 → FIL=528B 栈；
@@ -121,6 +174,9 @@ static int s_soe_append(const uint8_t *rec) {
? ((uint32_t)finfo.fsize / SOE_REC_SIZE) : 0u;
if (cnt >= SOE_STORE_MAX) {
(void)f_unlink(SOE_PATH);
/* 代数自增（读者窗口失效）：**unlink 当场就加**，不等写成功——文件已没了，
* 旧窗口里那几条记录在任何索引上都不再存在，晚一步都会有读者按陈旧窗口读数 */
s_rd_gen++;
DBG_INFO("cap full, recreate " SOE_PATH);
}
@@ -129,8 +185,9 @@ static int s_soe_append(const uint8_t *rec) {
fr = f_write(&f, rec, SOE_REC_SIZE, &bw);
(void)f_close(&f);
if ((fr != FR_OK) || (bw != SOE_REC_SIZE)) {
/* L1 文件级自愈：陈旧/损坏条目 → 删除重建、重试一次（同 run.log；
* unlink 返回值刻意不检查——失败也只是重试失败 → 留痕，不升级） */
/* 文件级自愈：**只有写失败**才删除重建、重试一次（打开失败走下面
* 的 else，不删——见函数头 ④）。unlink 返回值刻意不检查：失败也只是
* 重试失败 → 留痕计数，绝不升级成卷操作。 */
(void)f_unlink(SOE_PATH);
bw = 0u;
fr = f_open(&f, SOE_PATH, FA_WRITE | FA_OPEN_APPEND);
@@ -143,10 +200,13 @@ static int s_soe_append(const uint8_t *rec) {
}
}
} else {
/* 打开失败：只留痕、**不 unlink**（SOE 是事件序列，删文件 = 销毁历史；
* 名字/参数类错误码 unlink 也修不好，见函数头的逐码表） */
rc = -1;
}
if (rc == 0) {
s_fault_reported = 0u;
s_rd_gen++; /* 落盘成功 → 读者窗口作废（在卷锁区间内自增，与读者同锁同调） */
} else if (s_fault_reported == 0u) {
s_fault_reported = 1u;
DBG_ERROR("write " SOE_PATH " fail (%d)", (int)fr);
@@ -208,3 +268,121 @@ void soe_store_drain(void) {
uint32_t soe_store_dropped(void) {
return s_drop_cnt;
}
/* ========================= 只读遍历（UI 记录页） ============================ */
/*
* 函数功能：已落盘的 SOE 记录条数（= filesize / SOE_REC_SIZE，O(1)）
* 入口参数：无
* 返回值：条数；文件缺失、未挂载或 f_stat 失败返回 0 uint32_t
* 限定条件：任意任务上下文可调（uiTask 的 SOE 记录页用）；只做 f_stat，不取卷锁
* ——与 App/log/sys_log_mcu.c 的 syslog_count() 同一口径，不另起第二套
* 函数说明：条数按**整条 64 B 槽**相除，写者留下的半条尾槽天然不计入，这是
* "读者看不到半成品记录"的第一道保障（另两道见 soe_store_read 头注）
*/
uint32_t soe_store_count(void) {
FILINFO finfo;
if (f_stat(SOE_PATH, &finfo) != FR_OK) {
return 0u;
}
return (uint32_t)finfo.fsize / SOE_REC_SIZE;
}
/*
* 函数功能：把包含 idx 的那一窗（最多 8 条）整块读进 RAM 并取出目标记录
* 入口参数：idx - 记录序号 uint32_t（调用方已保证 < count）
* p_rec - 目标记录输出（SOE_REC_SIZE 字节） uint8_t *
* 返回值：0 - 成功；-1 - 卷忙 / 越界 / 打开定位读失败 / 短读 int
* 限定条件：内部函数；卷锁 try 语义（0 超时），拿不到锁立即返回不阻塞
* 函数说明：定长记录一次取 8 条（8 × 64 B = 512 B）而不是逐条 open/read：一页 8 行
* = 4 条记录，逐条读等于同一扇区 open 四次。记录页只在开页与翻页时重算，命中
* 窗口即零 I/O——整套"窗口 + 代数 + try 锁"结论与 App/log/sys_log_mcu.c 读侧
* 同源，刻意不另起第二套读盘路径（两套读盘规则必然漂移，是本仓反复在防的）
*/
static int s_rd_fill(uint32_t idx, uint8_t *p_rec) {
static FIL f; /* static：FF_FS_TINY=0 → FIL=528 B 栈；
* open~close 全程在卷锁区间内，跨任务由卷锁串行化 */
FRESULT fr;
UINT br = 0u;
uint32_t total;
uint32_t base;
uint32_t want;
if (vol_lock_wait(0u) == 0u) {
return -1; /* 卷忙不是故障：uiTask 下一轮重绘自然重试 */
}
/* 等锁期间写者可能已推进（甚至已 unlink 重建）→ 锁内重新取条数再校验边界 */
total = soe_store_count();
if ((total == 0u) || (idx >= total)) {
vol_lock_release();
return -1;
}
base = (idx / SOE_RD_WINDOW) * SOE_RD_WINDOW;
want = total - base;
if (want > SOE_RD_WINDOW) {
want = SOE_RD_WINDOW;
}
fr = f_open(&f, SOE_PATH, FA_READ);
if (fr == FR_OK) {
fr = f_lseek(&f, (FSIZE_t)base * SOE_REC_SIZE);
if (fr == FR_OK) {
fr = f_read(&f, s_rd_win, want * SOE_REC_SIZE, &br);
}
(void)f_close(&f);
}
if ((fr != FR_OK) || (br != (UINT)(want * SOE_REC_SIZE))) {
s_rd_win_cnt = 0u; /* 作废窗口：坏窗口留着会让后续行继续读到垃圾 */
s_rd_win_gen = 0u;
vol_lock_release();
return -1;
}
s_rd_win_base = base;
s_rd_win_cnt = want;
/* 代数在**卷锁区间内**采样：写者也只在持锁时自增，二者同侧 → 窗口与代数一致 */
s_rd_win_gen = s_rd_gen;
vol_lock_release();
(void)memcpy(p_rec, (const uint8_t *)s_rd_win + ((size_t)(idx - base) * SOE_REC_SIZE),
SOE_REC_SIZE);
return 0;
}
/*
* 函数功能：读取第 idx 条 SOE 记录（解析后的结构体；idx 0 = 最早一条）
* 入口参数：idx - 记录序号 uint32_t
* p_out - 输出（不可为 NULL） soe_rec_t *
* 返回值：0 - 成功；-1 - p_out 为空 / 越界 / 卷忙 / I/O 失败 / 记录校验不过 int
* 限定条件：uiTask 上下文（记录页逐行取数）；**不阻塞**——卷忙立即 -1，页面这行
* 退化显示"读失败"，下一轮重绘再试；SOE 页坏不得拖住主界面节拍
* 函数说明：读者不得看到半成品记录，三道保障缺一不可：
* ① count 只数整条 64 B 槽（半条尾槽不计入）；
* ② 窗口代数：写者每次成功落盘/重建在卷锁区间内自增 s_rd_gen，读者
* 比对填充时记下的代数，不匹配即重填——对齐 32 位读写在 ARM 上原子，
* 跨任务无需临界区，最坏多读一轮（同 syslog 读侧结论）；
* ③ 单条硬门槛：soe_rec_parse() 校版本 + 校验和，撕裂/半写一律 -3 拒收。
* count 与 read 之间新落一条的竞态**容忍**为"本次遍历少看到一条"
* （200 ms 重绘自然追上），绝不容忍读到半条——所以边界一律以锁内
* 重取到的 total 为准，不用调用方传进来的旧 total。
* soe_rec_parse 的 -1/-2/-3 在本 API 折成一个 -1：调用方（UI）对三者
* 的处理完全相同（这行显示读不到），把内部码外溢只会诱导页面写死分支
*/
int soe_store_read(uint32_t idx, soe_rec_t *p_out) {
uint8_t rec[SOE_REC_SIZE];
if (p_out == NULL) {
return -1;
}
/* 快路径：同代数且落在窗口内 → 零 I/O（代数比较用无锁读，最坏多刷一轮） */
if ((s_rd_win_cnt != 0u) && (s_rd_win_gen == s_rd_gen) &&
(idx >= s_rd_win_base) && (idx < s_rd_win_base + s_rd_win_cnt)) {
(void)memcpy(rec, (const uint8_t *)s_rd_win
+ ((size_t)(idx - s_rd_win_base) * SOE_REC_SIZE), SOE_REC_SIZE);
} else if (s_rd_fill(idx, rec) != 0) {
return -1;
} else {
/* 窗口未命中的分支已在 s_rd_fill 里完成取数与校验，这里不重复读盘 */
}
if (soe_rec_parse(rec, p_out) != 0) {
return -1;
}
return 0;
}
App/log/soe_store.h
+37
View File
@@ -59,6 +59,43 @@ void soe_store_drain(void);
*/
uint32_t soe_store_dropped(void);
/* ---------------- 只读遍历（UI 的 SOE 记录页用；写侧零影响） ----------------
* 读者不得看到半成品记录，三道保障缺一不可（实现见 soe_store.c 同号函数）：
* 1) count 只数**整条 64 B 槽**（filesize / SOE_REC_SIZE 整除），写者留下的
* 半条尾槽天然不计入；
* 2) 窗口代数：写者每次成功落盘 / 容量重建，在**卷锁区间内**自增内部代数，
* 读者比对填窗时记下的代数，不符即重填。对齐的 32 位读写在 ARM 上原子，
* 跨任务不需要临界区；最坏多读一轮，不会读出错数据；
* 3) 单条硬门槛：soe_rec_parse() 校版本 + 校验和，撕裂/半写一律拒收（-3）。
* 容忍的竞态只有一个：count 与 read 之间新落一条 → 本次遍历少看到一条，下一轮
* 重绘（uiTask 200 ms 节拍）自然追上。**不容忍**的是读到半条，所以边界一律以
* 卷锁内重新取到的条数为准，不用调用方传进来的旧值。
* 与 App/log/sys_log_mcu.c 的 syslog_count/syslog_get_record 同构（同一套窗口 +
* 代数 + try 锁纪律），刻意不另起第二套读盘路径。
*/
/*
* 函数功能：已落盘的 SOE 记录条数（= filesize / SOE_REC_SIZE，O(1)）
* 入口参数：无
* 返回值：条数；文件缺失、未挂载或 f_stat 失败返回 0 uint32_t
* 限定条件：任意任务上下文可调（uiTask 记录页用）；只 f_stat，不取卷锁
* 函数说明：见上方"只读遍历"总说明第 1 道保障
*/
uint32_t soe_store_count(void);
/*
* 函数功能：读取第 idx 条 SOE 记录（解析后的结构体，idx 0 = 最早一条）
* 入口参数：idx - 记录序号 uint32_t
* p_out - 输出（不可为 NULL） soe_rec_t *
* 返回值：0 - 成功；-1 - p_out 为空 / 越界 / 卷忙 / I/O 失败 / 版本或校验和不过 int
* 限定条件：uiTask 等读上下文；**不阻塞**——卷被占用立即返回 -1（调用方这行退化
* 显示"读失败"，下轮重绘再试），排障页不得拖住主界面节拍
* 函数说明：soe_rec_parse 的 -1/-2/-3 在此折成一个 -1：调用方对三者的处置完全相同
* （这行读不到），把内部码外溢只会诱导页面为区分不出来的差异写分支。
* 时间字段取记录内的 CP56（事件自己的时标），不用"现在的时间"换算
*/
int soe_store_read(uint32_t idx, soe_rec_t *p_out);
#ifdef __cplusplus
}
#endif
App/log/sys_log.h
+177 -7
View File
@@ -7,6 +7,20 @@
* 创建日期：2026-09-14
* 修改记录：
* v1.0 2026-09-14 王建锋 创建初始版本（设计见 docs/子系统设计/运行与自检记录设计说明.md §4）
* v1.2 2026-10-26 王建锋 新增「记录删除」API（UI 装置维护「清除记录」的前置，
* 道F task-4；判据 docs/任务规划/UI补齐.md §2 第 3 行
* 「不允许只做一个没有实际效果的按钮」）：
* 共享层 syslog_request_clear() / syslog_clear_state()
* （双端都实现，UI 侧只准用这两个）+ MCU 后端专属
* syslog_clear_apply()（落地半边，仅 defaultTask）。
* 请求与落地分离的理由与执行点写在下面声明处
* v1.1 2026-10-24 王建锋 仅契约注释更正，与 App/log/sys_log_mcu.c 的 C/F 两项
* 整改同步（无签名、无行为改动）：
* syslog_get_record 写死容量要求（ts_len > SYSLOG_TS_LEN、
* desc_len > SYSLOG_DESC_MAX）并明确"容量不足一律 -1、
* 不截断、不写调用方缓冲"——旧注释像是"给少了会被截断"，
* 实际是整条读不到；syslog_post 写明必须假设丢弃存在、
* 且丢弃留痕已按通道节流（节流后无丢弃计数）
*/
#ifndef SYS_LOG_H
@@ -21,10 +35,29 @@ extern "C" {
/*
* 日志 ID：决定落盘文件与容量上限
*
* ⚠ **记录类型 = 日志 ID 本身**（一类记录 = /log 下一个严格 8.3 短名的文件），
* 记录体内**没有**类型字段位（Lead 裁定 2026-10-26，task-10）：64B 定长格式被
* UI 记录页（文本读者）与主机解码工具同时按固定偏移读，塞类型字节等于当场砸掉
* 这两批既有读者；而运行/自检记录已经在这份格式里跑了很久，不能为五类新记录
* 改版本位。于是"这条记录是什么类型"由它在哪个文件里回答。
* 同理二进制 SOE 通道的 soe_type_t 本轮**不动**：改它必须同步 UI 侧的类型名表
* （类型名表在 UI 侧 <Drivers/BSP/UI/ui_w_soe.c>，不在本道写域），而且 SOE
* 页与这五页是两套读者。
* 口径与五个写入点已登记进 App/log/README.md（task-11「记录 5 页」按此做——五个页面已于
* 2026-10-28 落地：ui_page_accident / oper / alarm / start / yk，各页只读一个文件）。
*/
typedef enum {
SYSLOG_RUN = 0u, /* 运行记录 /log/run.log：上电/重启事件 */
SYSLOG_SELFTEST, /* 自检记录 /log/selftest.log：开机自检故障（仅故障才写） */
/* ↓ 五类记录（docs/UI设计/页面扩充详细方案.md §3.6 的五行，task-10 落写入点）
* ⚠ 只准**尾部追加**：id 值即枚举序 = 两端 s_paths[]/s_caps[] 的下标，
* 中间插值会让老文件被新 id 读成别的类型（静默错类别，比崩更难查）。 */
SYSLOG_ACCIDENT, /* 事故记录 /log/accid.log：跳闸投退=1 的元件动作 */
SYSLOG_ALARM, /* 保护告警 /log/alarm.log：跳闸投退=0 或该项不存在的元件动作 */
SYSLOG_START, /* 保护启动 /log/start.log：元件 picked 上升沿 */
SYSLOG_OPER, /* 操作记录 /log/oper.log：强制复归 / 清除记录 / 对时 / 定值保存 */
SYSLOG_YK, /* 遥控记录 /log/yk.log：104 遥控的选择 / 执行 / 拒绝 */
SYSLOG_COUNT /* 哨兵值，非有效 ID */
} syslog_id_t;
@@ -46,9 +79,21 @@ typedef enum {
/*
* 容量上限（条数；满时删除重建，设计文档 §4.3）
*
* ⚠ **上限是逻辑上限，不是预分配**：文件按追加写自然增长，一条不写就不占簇；
* 到顶才 unlink 重建（照 run.log 先例）。七类全满的名义峰值 =
* (1024+512+512+1024+1024+512+256) × 64B = **304 KB**，NAND 2 GB、且这些
* 记录只在事件边沿才写（判据动作/遥控/人工操作），不构成容量或磨损瓶颈。
* 告警/启动给到 1024 是因为一次系统故障会连片触发多个元件，别让最想了解
* 故障过程的两类记录最先被截掉。
*/
#define SYSLOG_RUN_MAX 1024u /* /log/run.log：64KB */
#define SYSLOG_SELFTEST_MAX 512u /* /log/selftest.log：32KB */
#define SYSLOG_ACCIDENT_MAX 512u /* /log/accid.log：32KB（跳闸稀有，换长历史） */
#define SYSLOG_ALARM_MAX 1024u /* /log/alarm.log：64KB */
#define SYSLOG_START_MAX 1024u /* /log/start.log：64KB */
#define SYSLOG_OPER_MAX 512u /* /log/oper.log：32KB */
#define SYSLOG_YK_MAX 256u /* /log/yk.log：16KB（低频，与事故同稀有） */
/*
* 上电/重启分类窗口（秒）：run.log 末条 epoch 距 now < 该值 → "reboot"，否则 "power on"
@@ -58,12 +103,52 @@ typedef enum {
/*
* 函数功能：投递一条日志（任意上下文；非阻塞，队列满则丢弃）
* 入口参数：id - 日志 ID syslog_id_t
* desc - 描述串（UTF-8，≤SYSLOG_DESC_MAX 字节；超长截断） const char *
* desc - 描述串（UTF-8；超过 SYSLOG_DESC_MAX 的部分丢弃，落盘只留前 28 字节）
* 本参数**投递时即拷贝进待发条目**：调用方缓冲区可立即复用，
* 不要求生命周期覆盖到落盘（2026-10-24 台架实证后由「只存指针」
* 改为条目内嵌定长缓冲，理由见 sys_log_mcu.c 的 syslog_entry_t 注释）
* 指针本身不可为 NULL const char *
* 返回值：无
* 限定条件：MCU 端 FreeRTOS 启动前调用走静态待发数组（由 defaultTask 挂载后落盘）
* 函数说明：调用方**必须假设投递可能被丢弃**——MCU 后端（sys_log_mcu.c）队列 8 槽、
* 启动前待发数组 8 槽，卷被 ftpTask 长期占用时 defaultTask 会把整批回投
* 队列（队列因此可长时间处于满态），此时本函数直接丢弃该条，并只在
* "转入故障"的那一次留痕（丢弃留痕按正常→故障节流，F 项整改 2026-10-24；
* 节流后**丢弃总数没有计数**，要计量得另加计数器）。必须留住的证据走
* sys_log_evidence()，不要靠 syslog_post 重试。
* 模拟器后端（simulator/sim/sim_syslog.c）是单线程直写宿主文件、**没有
* 队列与丢弃**，因此上面这段满态语义只约束 MCU 端。
*/
void syslog_post(syslog_id_t id, const char *desc);
/*
* 函数功能：投递一条日志——**调用链上不带日志行缓冲**的那一个版本
* 入口参数：id - 日志 ID syslog_id_t
* desc - 描述串（NUL 结尾；超过 SYSLOG_DESC_MAX 截断），同 syslog_post
* 返回值：无
* 限定条件：任意上下文；MCU 端不碰 FatFs、不碰卷锁、不阻塞
* 函数说明：为什么要有第二个投递口（不是洁癖）：每个 DBG_* 调用点在调用者栈上
* 内联约 216 B 行缓冲，而 syslog_post 的两个"满态丢弃留痕"分支就躺在
* 它自己的帧里——于是"调一次 post"在静态最坏链上等于"带上这两处缓冲"。
* protectTask 的静态最坏链是 B9 写进 DoD 的硬线（872 B / 57%，当年在
* post 里加一条 DBG_* 实测垫到 1192 B = stack_report FAIL），iec104Task
* 同样是深链任务，所以这五类记录的写入点一律走本函数。
* 代价是丢弃时不当场留痕：只累加 syslog_post_dropped()，由唯一写者
* defaultTask 在 syslog_drain() 里按差值补一条（照 soe_store 的先例）。
* 与 syslog_post 的差别**只有留痕路径**，收/丢的判据逐条相同。
* 模拟器后端没有队列也没有栈预算问题，本函数等价于 syslog_post。
*/
void syslog_post_quiet(syslog_id_t id, const char *desc);
/*
* 函数功能：取 syslog_post_quiet() 通道的累计丢弃条数（可观测性）
* 入口参数：无
* 返回值：MCU 端 = 队列满 / 启动前数组满累计次数；模拟器端恒 0（直写不丢） uint32_t
* 函数说明：与 soe_store_dropped() 同款定位。留痕由 drain 按差值上报，本函数是
* 给单测与台架读数用的，不参与任何判定路径。
*/
uint32_t syslog_post_dropped(void);
/*
* 函数功能：获取记录条数（= filesize / SYSLOG_REC_SIZE，O(1)）
* 入口参数：id - 日志 ID syslog_id_t
@@ -75,11 +160,19 @@ uint32_t syslog_count(syslog_id_t id);
* 函数功能：读取第 idx 条记录（时间戳 + 描述，均 NUL 结尾）
* 入口参数：id - 日志 ID syslog_id_t
* idx - 记录序号（0 起） uint32_t
* p_ts - 时间戳输出缓冲（≥SYSLOG_TS_LEN+1 字节；不可为 NULL） char *
* ts_len- p_ts 容量 size_t
* p_desc- 描述输出缓冲（≥SYSLOG_DESC_MAX+1 字节；不可为 NULL） char *
* desc_len - p_desc 容量 size_t
* 返回值：0 - 成功；-1 - 越界/读失败 int
* p_ts - 时间戳输出缓冲（不可为 NULL） char *
* ts_len- p_ts 容量，必须 > SYSLOG_TS_LEN（即 ≥ SYSLOG_TS_LEN+1 = 20 字节） size_t
* p_desc- 描述输出缓冲（不可为 NULL） char *
* desc_len - p_desc 容量，必须 > SYSLOG_DESC_MAX（即 ≥ 29 字节） size_t
* 返回值：0 - 成功；-1 - 越界 / 读失败 / **缓冲容量不足** int
* 限定条件：容量不足一律返回 -1，**不做静默截断、也不写调用方一个字节**
* （C 项整改 2026-10-24；旧注释只写"≥…+1 字节"像是"给少了会被截断"，
* 照它给 28 字节缓冲的结果是整条读不到而不是读到 27 字符）。
* 描述字段在写入侧已截到 SYSLOG_DESC_MAX，所以按上面的最小容量给缓冲
* 就一定装得下，读侧不需要第二道截断。
* MCU 后端与模拟器后端（sim_syslog.c）在这条守卫上取值相同，行为一致；
* 模拟器侧那份同样不可达的截断支还留在文件里（未列入本轮改动范围）。
* 调用方：uiTask 的日志页（行缓冲 32B）与 SYSLOG 取证打印。
*/
int syslog_get_record(syslog_id_t id, uint32_t idx, char *p_ts, size_t ts_len, char *p_desc, size_t desc_len);
@@ -91,6 +184,58 @@ int syslog_get_record(syslog_id_t id, uint32_t idx, char *p_ts, size_t ts_len, c
*/
int syslog_last_epoch(syslog_id_t id, uint32_t *p_epoch);
/*
* 记录删除（「清除记录」）：请求 → 落地分离
*
* 为什么必须分两步：defaultTask 是本模块**唯一写者**（存储架构说明 §10.1 第 7 条），
* uiTask 直接 f_unlink 会与写者的追加写/「容量满 unlink 重建」交错，而且删除要走
* 卷锁 + FAT 回写——uiTask 在 IWDG required_mask 内、每 100 ms 喂一次心跳，
* 给它一条最坏数百 ms 的存储路径就是拿误复位当代价。故 UI 侧只登记请求，
* 真正的删除在 defaultTask 的 syslog_drain() 尾部执行
* （范式同 App/algo/prot_elm.c 的 prot_elm_request_reset()：单字节标志 + 消费者落地）。
*
* 状态码（syslog_clear_state 返回值；写成宏而不是枚举，与本头既有 SYSLOG_* 常量同族）
*/
#define SYSLOG_CLEAR_NONE 0 /* 从未请求过清除（上电初值） */
#define SYSLOG_CLEAR_OK 1 /* 已清空：文件不在盘上，同拍 syslog_count() 必为 0 */
#define SYSLOG_CLEAR_WAIT (-1) /* 请求排队中：等 defaultTask 下一轮 drain（含卷占用顺延、卷未就绪挂起） */
#define SYSLOG_CLEAR_FAIL (-2) /* 最近一次落地失败：原文件未被删除，可再发一次请求 */
/*
* 函数功能：登记「清除某日志全部记录」的请求（任意上下文；不碰存储、不阻塞）
* 入口参数：id - 日志 ID syslog_id_t
* 返回值：0 - 请求已登记（同一 id 重复登记合并为一次，幂等）
* -1 - id 越界（请求未登记，状态一个字节都没动） int
* 限定条件：非唯一写者的上下文（uiTask / netTask / iec104Task）**只能**用本函数发起
* 删除，不得直调 MCU 后端的 syslog_clear_apply()
* 函数说明：本函数**不等于"已清除"**，只代表"已受理"——MCU 端的删除动作发生在
* defaultTask 的下一次 syslog_drain()（50 ms 节拍），结果读
* syslog_clear_state()，事实复核读 syslog_count()。
* ⚠ 两端时序有别（同 syslog_post 的队列/直写差异，那边写在 post 的头注释里）：
* MCU 端返回后状态通常是 SYSLOG_CLEAR_WAIT；模拟器端单线程、本调用内
* 同步落地，返回后立即是 OK/FAIL，**永远不会读到 WAIT**。UI 侧要按
* "WAIT 也正常"写判断，别把 WAIT 当失败。
* 刻意**不**在删除成功后补一条 "records cleared" 留痕：判据要求
* syslog_count() 归零，写了立刻变 1；要留痕归操作记录/SOE
* （docs/任务规划/UI补齐.md 第 6 项的写入方），不是本 API 的职责。
*/
int syslog_request_clear(syslog_id_t id);
/*
* 函数功能：查「清除记录」的状态（给 UI 出真实反馈，不是"按了就算成功"）
* 入口参数：id - 日志 ID syslog_id_t
* 返回值：SYSLOG_CLEAR_NONE(0) / SYSLOG_CLEAR_OK(1) / SYSLOG_CLEAR_WAIT(-1) /
* SYSLOG_CLEAR_FAIL(-2)；id 越界按 NONE 返回（等价"从没请求过"） int
* 限定条件：任意上下文（MCU 端只读两个 volatile 单字节，Cortex-M 上原子，无锁）
* 函数说明：排队位优先于结果字节——否则连点两次会先把上一次的结果当成这次的，
* 还在排队的请求被显示成"已清空"。
* 无锁交接的最坏竞态只有两种，都不产生错误数据：① 写者已销账、尚未写
* 结果的那几个指令周期里读 → 读到上一次的结果（同向，多为 OK）；
* ② 上一次失败被新请求清零 → 那次失败不再显示（用户已在重新发起，
* 语义正确）。为它上临界区要引 FreeRTOS 头 + 宿主桩，不值。
*/
int syslog_clear_state(syslog_id_t id);
/*
* MCU 后端专属 API（sys_log_mcu.c；模拟器端无对应实现，勿在共享代码调用）
*/
@@ -116,16 +261,41 @@ void syslog_mcu_mounted(void);
* 入口参数：无
* 返回值：无
* 限定条件：仅 defaultTask（唯一写者）调用；卷未就绪时直接返回（条目滞留待重试）
* 本函数尾部同时消费「清除记录」请求（syslog_request_clear 的落地半边，
* 排在条目排空之后——删除必须是本轮对这两个文件的最后一次盘上动作，
* 先删后写会把刚排空的旧记录又落回去，"清除"就变成没效果的按钮）
*/
void syslog_drain(void);
/*
* 函数功能：立即删除某日志的全部记录（「清除记录」的落地半边，MCU 后端专属）
* 入口参数：id - 日志 ID syslog_id_t
* 返回值：0 - 记录已清空（含"文件本就不存在"的幂等成功，见下）
* -1 - 未清空：卷被占用或删除失败，**原文件一个字节都没少** int
* 限定条件：仅 defaultTask（syslog 唯一写者）上下文，且调用处**不得持卷锁**
* （卷锁非递归锁）；卷锁一律 try（vol_lock_wait(0)，本任务 = 看门狗
* 喂狗点，阻塞等锁 = 停喂 = IWDG 误复位）
* 函数说明：其它上下文请调 syslog_request_clear()（本头文件上方）；本函数在
* MCU 后端之外**没有任何实现**，共享代码误调会在链接期报错，
* 这比运行时断言硬。产品路径上唯一的调用者是 syslog_drain 尾部的
* 请求消费循环，直接调用只用于板级套件与主机单测。
* 幂等口径：只有 FR_NO_FILE 算"已经没有什么可删了"→ 返 0；
* FR_NO_PATH（/log 目录不在）**不算**幂等——记录确实读不到，但成因是
* 目录没了而不是"被清空"，补目录归 syslog_mcu_mounted() 每 2s 的重试，
* 这里如实返 -1，不把卷异常洗成"清除成功"。
* 名字/参数类错误码（FR_INVALID_NAME 等）一律只返 -1 不做任何补救动作：
* 本函数压根没有卷级动作（无 f_mkdir / 无 f_mkfs / 不重试 unlink），
* 这正是存储架构说明 §10.1 第 10 条在删除路径上的落地形态。
*/
int syslog_clear_apply(syslog_id_t id);
/*
* 函数功能：把一条取证行追加到 /log/wdev.log（掉电不丢；变长行，不走 64B 定长格式）
* 入口参数：p_desc - 取证描述行（调用方已格式化；不可为 NULL） const char *
* 返回值：0 - 成功；-1 - 卷占用或写失败（证据可能回滚，**不阻断判定**） int
* 限定条件：poller（defaultTask）上下文调用；卷锁一律 try（绝不阻塞，
* 本上下文 = 看门狗喂狗点）
* 函数说明：round 7 取证通道（设计见 docs/子系统设计/看门狗设计说明.md 2026-10-02 变更记录：
* 函数说明：第 7 轮取证通道（设计见 docs/子系统设计/看门狗设计说明.md 2026-10-02 变更记录：
* 误复位后 RAM 态随复位消失、stall 行经僵尸串口丢失，故证据必须落盘）。
* 内部在释放卷锁后立刻追加一条 s_append(SYSLOG_RUN, ...) 写另一个
* 文件——FTL 单页缓存语义为"写到不同 LPN 才把前一脏页刷进 NAND"，
App/log/sys_log_mcu.c
+907 -112
View File
File diff suppressed because it is too large Load Diff
App/protocol/README.md
+1 -1
View File
@@ -11,7 +11,7 @@
| 子目录 | 协议 | 说明 |
|---|---|---|
| `iec104/` | IEC 60870-5-104 被控站（TCP 2404 上行） | **纯逻辑**三件套（asdu/pts/link，零 I/O，数据源 vtable 注入）→ 全栈 L0.5 主机单测；板端胶水与点表决策 → `docs/子系统设计/IEC104上行设计说明.md` |
| `iec104/` | IEC 60870-5-104 被控站（TCP 工厂默认 2404 上行） | **纯逻辑**三件套（asdu/pts/link，零 I/O，数据源 vtable 注入）→ 全栈主机侧纯逻辑单测；板端胶水与点表决策 → `docs/子系统设计/IEC104上行设计说明.md` |
## 何时使用本目录
App/protocol/iec104/iec104_asdu.h
+2 -2
View File
@@ -1,8 +1,8 @@
/*
* 模块名称：IEC 60870-5-104 ASDU 编解码（应用层，纯逻辑）
* 模块功能：104 规约应用服务数据单元（ASDU）的类型/传送原因常量、组帧与解析。
* **零 I/O、零平台依赖**（仅 stdint.h）→ 主机侧 L0.5 可离线单测
* （登记簿 A-4 约束 1"协议解析与硬件 I/O 分离"）。
* **零 I/O、零平台依赖**（仅 stdint.h）→ 主机侧可离线纯逻辑单测
* （分层约束：协议解析与硬件 I/O 分离）。
* 口径来源：docs/算法/继电保护功能复现规划.md §1.5（B0 产品定义）——
* 公共地址 2 字节、传送原因 2 字节、信息体地址 IOA **3 字节**（101 为 2 字节）；
* 遥测上送**短浮点** M_ME_NC_1（系数 = 1）；遥信双点上双点、其余单点；

Some files were not shown because too many files have changed in this diff Show More