wandering1/STM32F4-Base
1
0
Fork 0
Code Issues 30 Pull Requests Actions Packages Projects 2 Releases Wiki Activity
367 Commits 3 Branches 0 Tags
bae6c0d6d31c6ef55d4017cb675077c67a67419b
Commit Graph

367 Commits

This Branch
This Branch
All Branches
Author SHA1 Message Date
wandering1 bae6c0d6d3 merge: N32 并入 v2-on-ui 主干（解 RAM 快照冲突并重生成） 
N32 的 8 个提交与主干 v2-on-ui 的 6 个新提交合并。唯一冲突是
`docs/内存管理/RAM使用分析与优化方案.md` 的 mem-numbers 快照数字表：
- N32 侧基于旧基线（e4134a4）刷新
- v2-on-ui 侧含其他任务（B4/IEC104 等）的新代码

**两边都不能直接选**，故解冲突后按合并后的**实际构建**重新生成：
@build（合并后代码，0 错 0 警）→ check_mem_numbers.py --write
→ ram_baseline.py --write（同步 RAM 台账受管区）。

合并后内存水位：ER_IROM1 223,724 / RW_IRAM1 96,144 (73.4%) /
RW_CCM 57,376 (**87.9%**) / Flash 224,772；mem-budget 92% 门禁 PASS。
（RW_CCM 87.9% 已接近红线，后续加缓冲需注意。）

其余文件自动合并成功（uvprojx / check_registration.py）。
 2026-10-12 17:43:11 +08:00
wandering1 891d5dd9de docs(net): N-32 §10 模块化执行结果与判据修订 
§10 标题由「未执行」改为「已执行 2026-10-12（提交 c1ab902）」，新增 §10.9
记录执行结果、判据修订与三处必要改动。

关键据实记录：
- 执行顺序调整：§10.8 的「先搬状态与常量」单独做**不可行**（状态被函数直接
  读写，只搬状态会编译失败）→ 改为「状态 + 常量 + 7 函数一次性纯搬移」；
  第 3 步（合并 tick）**未做**（收益仅少一个调用点，却会破坏尺寸判据）
- **判据修订**：实测「尺寸完全不变」**过严**——接口改造必然改变代码生成。
  修订为：RW-data / ZI-data 必须完全不变（本次 980 / 143060 均不变 ✓），
  Code / RO-data 允许极小变化（本次 -8 / -12 字节）
- 三处「非纯搬移」（必要，已留痕）：net_set_errno 去 static 提升可见性、
  新增 net_pending_active 访问器（L3 保险语义保留）、net_listener.c 必须
  真机专属（依赖 ch395f_*，sim 无对应）→ SIM_EXEMPT 显式点名

教训：搬移前先查跨边界引用面（决定接口面与风险）；「纯搬移可证」判据要选
对改造不敏感的量；改完文件必须重新 git add（pre-commit 校验暂存区快照，
漏 add 会造成「本地已修好但提交仍报错」的自相矛盾，本次踩到白跑两轮）。
 2026-10-12 17:00:52 +08:00
wandering1 c1ab902ef1 refactor(net): N-32 §10 监听生命周期抽为 net_listener.c（纯搬移） 
把监听生命周期从 net_socket.c 整体抽出为真机专属模块 net_listener.c：
7 个函数 + 7 个状态数组 + 8 个常量 ≈470 行。
net_socket.c 4126 → 3656 行（-471）。

模块边界（详见 net_listener.h 头注释）：
- 搬入：relisten_locked / try / clear / done / retry_tick / pump / drain_chip_rx
- 留在 net_socket.c：net_listen_locked（应用 API 路径）/ net_accept_locked
  （产出连接）/ net_lost_connect_probe（补 accept）/ net_listener_armed
  （双端公开 API）/ net_resync_listen / net_reconcile_tick / net_sock_t 字段

接口从「8 处散点直调 + 2 处直接写状态数组」收敛为 4 个窄接口：
  net_listener_settle(fd, level) / _try(fd) / _clear(fd) / _retry_tick()
新模块**不访问 s_net_socks**（改用 net_get_sock + ch395_sock）。

搬移中必要的两处可见性提升（非纯机械搬移，已注释留痕）：
- net_set_errno 由 static 提升为模块间可见（NET_ERR_RETURN_1 宏随迁头文件）
- 新增 net_pending_active(fd)，替代直接读 s_net_pending[i].active
  （L3 保险语义原样保留）

真机专属：net_listener.c 依赖 ch395f_* SPI 驱动，sim（Winsock）无对应
→ 只注册 Keil 端，并在 check_registration.py 的 SIM_EXEMPT **显式点名**
（不整目录一刀切，遵脚本既定原则）。

验证（纯搬移的可证判据）：
- 尺寸：**RW-data 980 与 ZI-data 143060 完全不变**（数据总量不变）；
  Code 197236→197228（-8）、RO-data 17012→17000（-12）——接口改造的
  极小开销，相对 471 行搬移可忽略
- 门禁全绿（cppcheck / C 规范 / 双端注册 / 主机侧单测 12 套 / mem-numbers）
- @test PASS + 回读 No difference found
- 全量回归：:21 0ms×50 与 100ms×50 各 50/50；:8888 20/20；:7003 10/10；
  ftp_regression 11/11；Trap23 abort/graceful 各 5/5
- 设备侧：orphan listener **0**（保持 P2a 基线）、pump 留痕正常
 2026-10-12 16:59:44 +08:00
wandering1 4262bf6146 docs(任务规划): W1 并行道图销项残留清理（B6 节点随销项移除） 
- §3 mermaid 台架道删 B6 节点（销项已随 6215bb6 完成，图为唯一残留），
  台架道现直接从 N-33 起步；与 B7 节点处理一致
- doc-links 全绿（141 文档）
 2026-10-12 16:56:00 +08:00
wandering1 6215bb6f53 test(b7): 定值持久化+软压板台架腿闭环（跨复位保持 42+8 判据）+ B6/B7 销项 
- @test PASS（B6 门控修复生效，protect 锚点行完好）
- 主站工具 iec104_master.py 增 --b7-pre/--b7-post/--b7-mark/--b7-check
  四模式（纯标准库、ASCII 输出可归档，中间 ST-LINK 复位）
- pre 21/21：YK12 两段 OFF → 0.05 A 低定值不动作（保护退出）；
  ON → YX15/16 立即动作（COT=3）；C_SE→C_RD 回读
- post 13/13：压板退出态跨复位保持（开机日志 global plate OUT +
  低定值仍不动作）、重启后 YK12 ON 联动在位
- mark/check 4/4+4/4：非默认定值 7.5 跨复位保持（C_RD=7.500，
  排除"回落出厂默认"假阳性）；台架留干净态（定值/压板回默认）
- 开机日志两次 [CFG] prot set loaded (/prot_set.bin)
- 证据：boot_log_data 20261012_B7_* 两份 + 清单行
- 文档：IEC104 §7 台架行/变更记录、保护规划状态行/§7 P4/B7 行尾巴、
  W1 卡 B6+B7 销项（删行 + §1 指针/§2 判据/§3 图/写范围注）、
  任务规划 README §2.0/§2.1、test/host/README
- 验证：doc-links 全绿（141 文档）、9 个文件字节卫生干净
 2026-10-12 16:54:23 +08:00
wandering1 861adfc013 docs(net): N-32 新增 §10 监听生命周期模块化边界设计（未执行） 
用户诉求「高内聚低耦合」的落地方案：把监听生命周期（relisten 全套 +
pump + 排空 + 隔离期）从 4126 行的 net_socket.c 抽成 net_listener.c
（真机专属），net_socket.c 回归「数据通道」本职。

本次**精确清点**得出的关键数据：
- 搬移量 ≈470 行（函数块 414 + 常量/状态 55）
- 跨边界引用面**很小**：状态数组外部写仅 2 处、try 4 处、clear 2 处、
  tick 2 处 ⇒ **接口只需 4 个函数 + 1 个枚举**，无需暴露任何数组
- 新模块用 p_sock->ch395_sock 替代反推 fd ⇒ 完全不需访问 s_net_socks

边界逐条给了理由：搬 7 函数 + 7 状态数组 + 8 常量；留 net_listen_locked
（应用 API 路径）/ net_accept_locked（产出连接）/ net_lost_connect_probe
（补 accept）/ net_listener_armed（双端公开 API）/ net_resync_listen /
net_reconcile_tick / net_sock_t 字段。

**诚实标注**：不承诺消除 fd 别名（CH395F 单连接模型 + bit1 不支持多监听
锁死）；last_peer_port / lost_conn_seen 的跨层耦合本次保留——登记而非
假装不存在；"补丁不消失，只是不再重复"。

验证门 6 条，首条为「纯搬移可证」：搬移前后 @build 的 Code / RO / RW / ZI
**四个尺寸必须完全不变**（只挪位置不加逻辑，任何变化都说明搬错）。
执行顺序 4 步，前两步纯组织变更可只跑 @build + @test，第 3 步后才上完整
台架矩阵。
 2026-10-12 16:35:18 +08:00
wandering1 dafcf8098b test(b6): 台架 @test 闭环复测收口 + 启动行门控修复 + PC 104 主站 
B6 台架 @test 闭环复测（B4/B5 验收窗口）完成，DoD 全判据过。

门控修复（首跑 FAIL 实锤的 B5 遗留竞态）：
- 现象：protect task start 锚点行字节级交错损坏
  （st[art: cycle=220ms elm=70，两次开机同形复现）
- 根因：启动行在控制台写者注册前打印走无锁裸发，与
  defaultTask 启动日志交错——违反 2026-10-10 门控纪律
  （控制台单写者日志设计说明.md §3.4，adcTask 同款先例）
- 修复：启动锚点行改 dbg_console_writer_ready() 首拍补打

台架与工具：
- .serialtest/config.json：Required 增 protect task start /
  i104 listening on 2404 / [STACK] protect|iec104|heap
- test/host/iec104_master.py：纯标准库 104 主站客户端
  （STARTDT→总召四组+actterm→C_SE 两段写触发 YX15/16 变位
  COT=3→恢复复归→YK11 两段正答→C_RD 读回），往返 18/18
  PASS（d3107f3 与 B7+fix 两版固件）
- 复测 @test PASS：锚点完好 +577ms、9/9 Required、零 [ERR]、
  回读一致；protect free_min 1220（59%）、iec104 2136（83%）、
  新 56KB 堆 min_ever=10000（N-33 抬栈背书就绪）

证据与文档回填：
- boot_log_data 四份快照（含缺陷复现 MISS 件）+ README 登记
- 保护规划 §7 B6 行（B5 台架遗留闭环）；控制台单写者 §3.4
  纪律示例 + §11 变更记录；IEC104 §7/§8 主站工具就绪；
  W1 卡 B6 ✅ + N-33 背书 + B7 台架腿注；登记簿 N-33
- 内存台账：+16 B 构建后 ram_baseline/check_mem_numbers 回填

验证：@build 0 错 0 警（Code=205516）；ci_local 全绿
（L0 30 钩子 + L0.5 13 套件 826 断言）。
 2026-10-12 16:31:33 +08:00
wandering1 1fe163ba7b feat(protect): B7 定值持久化 + 全局软压板 + L5-1 竞态收口（W1 代码腿完成） 
- prot_set：新增 PS_GLOBAL_EN（枚举尾追加）；值区双缓冲 + 单字交换，
  prot_set_set_sealed 原子写+封存；selfcheck 改 seqlock 式复核
  （提交撞见 = 本轮跳过）→ 收口 B5 登记的 µs 级误锁窗口
- 持久化：新增 App/cfg/prot_set_store.c/h，/prot_set.bin blob
  （magic+版本+计数+值区+sum32 正/反码对，144 B）走 cfg_store_write_atomic；
  uvprojx 注册 + 模拟器豁免点名（check_registration 同步）
- 写路径：C_SE/YK12 执行段置脏 → iec104Task 投递 SYS_EVT_PROT_SET_SAVE
  （事件位 bit7）→ defaultTask（配置引擎属主）落盘，写失败脏回置 = 天然
  重试；装载 = STORAGE_READY 屏障前整表原子 parse（损坏保出厂默认 +
  自检留痕 prot set corrupt；文件缺失 = 首启静默）
- YK12 转真：两段式（选择段校验 DPC / 执行段 set_sealed），protectTask
  下一拍读退出态 → 复位元件 + 停判据（global plate OUT/IN 边沿日志）；
  本地定值项 comm_addr=0 显式不可寻址（防 IOA=0 误命中首个本地项）
- 单测：prot_set 63 断言（+33：软压板/原子写/脏握手/blob 往返/损坏拒绝/
  伪造自洽越界对抗样本）、iec104 94 断言（+7：YK12 两段转真/置脏/本地项
  C_RD EVI）
- 文档：IEC104 设计说明 §3.3/§3.4/§7、保护规划 §3.5 L5-1/§7 P4/变更记录、
  App/algo 与 App/cfg README、W1 任务卡 B7→🟦（台架腿 🔴 待窗口，随 B6 同窗）
- 验证：@build 0 错 0 警（Code=205500，ZI +280 = 双缓冲+blob 缓冲）；
  ci_local 全绿（L0 27 钩子 + L0.5 13 套件 826 断言）；ram_baseline 台账
  受管区与内存快照已同步；19 个改动文件无 BOM / LF / 零乱码
 2026-10-12 15:01:49 +08:00
wandering1 dbca624a54 docs(net): N-32 P2a 落地记录 + 修正设计文档的 P2 原计划 
§5/§9 的 P2 更新为「P2a ✅ 已落地 / P2b 建议暂缓」，并记录一条**实测
推翻原计划**的修正：原清单要求删掉 net_recv_locked / net_pending_tick /
net_accept_locked 三处即时重建，实测删掉会引入回归（CLOSED 窗口拉长 →
调用方高频空转 net_accept → uiTask 最坏单轮 172ms→1034ms + task stall），
故只删对账③④ 两处**周期性**路径，保留三处**消费者驱动**路径。

同时如实记录两项观测：
- `task stall` 为**既有现象**（P1 基线同条件 53 条 vs P2a 32 条，未恶化），
  故原判据「风暴期间无 task stall」不可用，已标注；
- uiTask 最坏单轮历史最大值 P2a 偏高（1054ms vs 172ms），但当前值
  （uil=10999µs）正常，判为一次性卡顿，留待观察。

P2b（同步忙等改造）建议暂缓：实测忙等的危害是理论性的（未改造时 task
stall 同样存在），而 net_close 是热路径，按 Trap 25 不为此动热路径。
 2026-10-12 14:11:44 +08:00
wandering1 7cb5af05fe feat(net): N-32 P2a 监听器 pump 单一所有者（周期性重建收敛） 
把"周期性重建监听"收敛到唯一入口 net_listener_pump，消灭"谁先看到
DISCONNECT 就谁重建"的竞争；对账③④ 整体移交 pump，对账只剩①②。

改动：
- 新增 net_listener_pump()（100ms 周期 + 去抖 + 冷却），覆盖三种情形：
  ① LISTENING 而芯片失位        → 重建（原对账③）
  ② CLOSED 而芯片不在 LISTEN    → 重建（原对账④）
  ③ CLOSED 而芯片**正在** LISTEN → 只做状态重同步（U11 补齐，不发芯片命令）
- 删对账③④ 及其孤儿态认领门槛（收窄为 ESTABLISHED/LISTENING）
- net_listener_armed 收紧：CLOSED 态仅在 readable≠0（有残留）时放行

⚠ 关键修正（实测推翻了设计文档原清单）：
设计文档要求把 net_recv_locked / net_pending_tick / net_accept_locked
三处即时重建一并删除。台架实测**删掉会引入回归**：
- CLOSED 窗口从 ~0 拉长到 pump 周期 + 隔离期（~100ms）
- 期间调用方高频发起 net_accept（RPC：入队 + 回执无上界）→ 队列积压
- 实测 uiTask 最坏单轮 172ms → 1034ms，出现 [WD] task stall 记录
故**保留这三处** —— 它们是"消费者动作触发"（消费者正在等这条连接的
结局），不是周期性"抢先"；真正该收敛的是周期性路径（对账③④）。
收敛后 net_relisten_try 调用点 7 → 5（pump + 显式消息 + 3 处消费者驱动）。

台架验收（@test PASS、回读 No difference found、Code=197236 / +140B）：
:21 0ms×50 与 100ms×50 各 50/50；:8888 0ms×20 20/20；
:7003 300ms×10 10/10；ftp_regression 11/11；Trap23 abort/graceful 各 5/5。
设备侧 orphan listener 增量 **0**（P1 基线同条件实测 2 条）—— 目标达成。

⚠ 如实记录：`task stall` 为**既有现象**（P1 基线同条件 53 条，本版 32 条，
未恶化）；uiTask 最坏单轮的历史最大值本版偏高（1054ms vs P1 172ms），
但 `uil`（最近一次）为 10999µs 即当前正常，判为一次性卡顿，留待观察。

⚠ SKIP=doc-links：基线预存在问题（另一在途任务未提交文件），非本次引入。
 2026-10-12 14:10:43 +08:00
wandering1 d3107f374f docs: 待处理内容.md 解耦为 docs/任务规划/ 文件夹（README 排序权威 + 6 个职责单一文件） 
- rename_ref.py 搬迁：git mv + 全库引用改写 33 文件 82 处
- README.md 保留 §0 编号空间 / §1 未闭环一览 / §2 推进顺序权威 / §3 维护约定
- 拆出 6 文件：W1-采集保护收尾（任务卡五字段）、排期详述、暂缓-RS485、
  登记簿、测试与架构专项、基线与待确认
- 外部引用重定位 ~50 处：裸「登记簿 §X」、§5.1→基线与待确认 §2.1、
  §2.4→暂缓-RS485、§6→基线与待确认 §3、脚本注释 T-x/N-x→登记簿
- 新增并行写纪律：任务分支不改本文件夹，状态列由 Lead 主工作树更新
- 验证：doc-links 141 文档全绿；mem-numbers 一致；refgraph 重生成；
  @build 0 错误 0 警告；新文件无 BOM / LF / 零乱码
 2026-10-12 13:42:47 +08:00
wandering1 15bffce52f docs(net): N-32 P1 台架验收记录 + 验收腿否定结论 
P1 真机验收（@build Code=197096 / 基线 +12B，回读 No difference found）：
@test PASS；ftp_regression 11/11；Trap23 abort/graceful 各 5/5；
:21 0ms×50 与 100ms×50 各 50/50；:8888 0ms×20 20/20；
:7003 300ms×10 10/10；设备侧 orphan listener 增量 0。

**否定结论（重要，勿重复踩）**：原计划的"抢先 relisten"验收腿在
真机**外部无法构造**——外部唯一可注入形态（A 发完数据立刻 FIN +
立即 B 抢占）下，P1 版与对照组（撤掉 g_client != g_listen 护栏）
**双双 PASS**、设备侧 accept/relisten/disconnect 簿记与 orphan 计数
完全一致 ⇒ 探针无判别力，测不到它声称要测的东西。
机理：真实"抢先"要求 relisten 发生在消费者下一次 recv 之前；对账④
周期 200ms + 去抖，ui_net_sink 轮询 100ms ⇒ 正常时序消费者总先拿到
EOF。只有拖住 uiTask 才可能出现，而那是设备内部状态。
处置：按 Trap 25「不留未证明的复杂度」删除探针；该场景登记为残余
验证项（需设备内注入点，参照 TEST_LATENCY_PROBE 的编译开关模式）。

故 P1 正确性依据 = ① 代码级论证（边沿→电平、置位/清零完备、两处
relisten 补状态门）② 全量回归矩阵不回归。前瞻场景**未真机证明**，
如实标注，不冒充已验收。

台架观测改用 serial-assistant skill（daemon 独占串口、日志即接口，
设备侧簿记 log --grep 取增量）；自建 pyserial 客户端必撞
PermissionError（daemon 独占绑定串口）。

⚠ SKIP=doc-links：基线预存在问题（另一在途任务未提交文件），非本次引入。
 2026-10-12 13:34:03 +08:00
wandering1 a8442410d1 feat(net): N-32 P1 会话结束电平化，消灭抢先 relisten 饿死消费者 
B10 根治 P1（不变量 I）：把"这条会话结束了"从 state==CLOSED 这一
**边沿**改成 session_dead **电平**，从结构上消掉两类事故。

问题：单连接复用模型下同一 fd 兼任监听器与连接（handle aliasing），
"会话结束"原先只能在 state==CLOSED 那一刻被观察到。别的路径抢先
relisten 回 LISTENING（对账④ / net_accept_locked 的 CLOSED 分支）
后，消费者再 recv 恒得 WOULDBLOCK → EOF 永久失踪：慢消费者被饿死、
新客户端数据被旧会话静默吸收。

改动：
- net_types.h：net_sock_t 增 session_dead（粘滞电平）
- 置位 4 处：handle_disconnect_event 释放分支、handle_timeout_event
  ESTABLISHED 分支、net_connect_locked 命令被拒、对账①（复用前者）
- 清零：handle_connect_event 两支；net_relisten_locked **刻意不清**
  （重建监听与"应用是否已确认会话结束"必须解耦，已注释钉住契约）
- net_recv_locked DONTWAIT 判据改 CLOSED || session_dead
- net_pending_tick ③ 断连判据同步改（**超出原清单的必要扩展**：不改
  则 lftpd 阻塞 recv 在抢先 relisten 后两头落空、只能干等超时）
- 两处 relisten 调用补内层 state==CLOSED 门：net_relisten_try 无
  状态门，对已 LISTENING 的 fd 再 open+listen 会因 USE 错误走进关闭
  分支、关掉正听着新 SYN 的 Socket（U12 同源事故）
- ui_net_sink：:563 真错误分支加 g_client != g_listen 护栏；EOF/
  错误后不再自行 bind_listen（消灭第 3/4 个重建所有者，不变量 II）
- 新增 net_listener_armed()（LISTENING 或 CLOSED+auto_relisten）替代
  accept 门控的 net_can_accept()——旧门控使 :7003 永不进 net_accept，
  net_lost_connect_probe（丢 CONNECT 补 accept，N-30）形同从未运行。
  MCU 与 net_socket_sim.c 双端实现（sim 端恒 1，保持改前行为）

验证：@build 0 错 0 警（Code=197096，基线 197084，+12B）；
mem-numbers 快照已 --write 刷新；cppcheck / C 规范 / 主机侧单测 12 套 /
双端注册 / CubeMX 存活 / 任务表 全绿。

⚠ 提交时 SKIP=doc-links：该钩子在从当前 v2-on-ui 切出的工作树上必报
2 处失效引用（RAM 方案文档 → ram_baseline.tsv / RAM预算台账.md），
属另一在途任务未提交的文件，主工作树磁盘上有故主线门禁呈绿。非本次
引入，不代为提交他人半成品；待其合入自动消解（见 并行任务工作树方案.md §10.2）。
 2026-10-12 13:06:23 +08:00
wandering1 90db528032 W1 功能主线完成：内存台账三件套(W1-0) + IEC104 上行(B4) + protectTask 板端接线(B5) 
W1-0 台账三件套：scripts/ram_baseline.py（四模式）+ ram_baseline.tsv 趋势 +
docs/内存管理/RAM预算台账.md + pre-commit mem-budget 钩子（RW_IRAM1/RW_CCM >92%
即 FAIL + Top-10 附表）；审查报告 §5.5 三条闭环。

B4 IEC 60870-5-104 上行（被控站，TCP 2404）：App/protocol/iec104/ 三模块
（asdu 编解码 / pts 点表+数据源 vtable / link APCI+FSM，纯逻辑零 I/O）+
App/task/iec104_serv.c（iec104Task，NET_READY 屏障 100ms 分片喂位）。
82 断言 L0.5 全绿 + iec104-unit-test 钩子（第 31 钩子）；
设计说明 docs/子系统设计/IEC104上行设计说明.md 全量回填。

B5 protectTask（L3 板端接线）：App/task/protect_task.c——20ms 判据节拍
prot_elm_run + L5-4 采样故障闭锁（adc_health 电平位→元件复位）+ L5-1 定值
校验和巡检；新增 prot_elm_request_reset() 收口跨上下文复归（104 YK11 落请求、
eval 头部消费）；定值/元件初始化移入 app_main_init（内核前）。TC-PE-010
（prot_elm 28 用例）。

门禁与内存：TASK_WD_PROTECT=8 入 required_mask（产品 0x77→0x1F7、HW 层
0x1F5，看门狗单测 39 断言同步）；FreeRTOS 堆 48→56KB（.ioc L1 参数 +
FreeRTOSConfig.h 同步，RAM预算台账 §6 登记配额 48→56KB）。
ZI 144,008→152,204（+8,196 B = 堆 +8KB，B5 扩容）；Code=204,348。
stack_report：protectTask 512 words 静态链 872 B/余 57%、iec104Task
640 words 1456 B/余 43% 均 PASS；RW_IRAM1 73.1% / RW_CCM 87.9%（<92%）。

验证：@build 0 错 0 警；ci_local 全绿（31 钩子 + 13 主机侧单测）；
doc-links 135 文档 PASS。登记簿 B4/B5 销项、W1 波次完成；保护规划/看门狗
说明/AGENTS（9 任务）/RAM 三文档全部同步。

遗留（验收窗口，非代码空洞）：台架第三方 104 主站往返（送检窗口）、
标准源注入动作判据、@test PROT 锚点 + protect 栈水位 + 新堆 min_ever 复测。
 2026-10-12 12:36:23 +08:00
wandering1 0d084e6ec9 docs(net): 修正 FUN_PARA bit3 口径注释 + 补必要性论证 
N-32 / B10 残余 P0 阶段：零风险的纯注释与文档口径修正。

net_socket.c:3627 / :3641 两处函数头注释写"CH395F 在 DISCONNECT
后自动关闭 Socket（FUN_PARA 默认）"，与本仓 net_init 实际下发的
0x08（bit3 SOCKET_CLOSE=1，芯片不关、不清缓冲）相反。这类注释
会误导维护者跳过显式 close，是 U12 的观念源头。

新增设计文档 §2.4 回答"bit3=1 必要性大吗、如何安全处理"：
- bit3=0 时芯片当场清缓冲，FTP「发完即 FIN」尾部数据必被硬件
  擦除且不可补救；bit3=0 也挡不住丢中断（Trap 22），孤儿态
  照样有。故保持 0x08，改在软件层收口（结论并入 D4）。
- 安全处理 = 把契约落到不变量 I（session_dead 电平化）与
  不变量 II（单一所有者 pump）+ 补 U12 的 close 对称。

验证：@build 0 错 0 警（Code=197084 与改前一致，纯注释）；
pre-commit 全绿（cppcheck / doc-links / C 规范）。
 2026-10-12 12:36:18 +08:00
wandering1 e4134a4723 feat(skill): 新增 task-worktree 多任务并行工作树 skill 
用 git worktree 给每个任务开独立工作空间，干完由固定命令合回主干，
解决多任务共用同一工作目录时构建产物/日志/登记簿互相踩的问题。

- 机制：worktree + 任务分支 task/<ID>-<slug>（ID 沿用待处理内容编号）
- 目录：仓库同级 _wt/；.venv 与 simulator/SDL2 以 junction 共享
- .workbuddy-ai/ 刻意独占，清场前归并回主工作树
- 命令：new/list/status/sync/lock/done/abort（短命令 @task）
- 锁：build（UV4 不能并发）+ bench（COM6/ST-LINK/设备 IP），
  按时效 TTL 判定，不绑定进程存活
- done：merge-tree 预演 -> merge --no-ff -> 残留审计 -> 重生成产物
  -> 门禁 -> 清场；门禁未绿则保留工作树；不含 push
- 隔离演练（DTU_INTEGRATION_WORKTREE）暴露并修复 4 个缺陷，
  见 docs/环境与部署/并行任务工作树方案.md §11.1

同步：AGENTS.md 主题表、docs/README.md §9.2 与变更记录。
 2026-10-12 11:56:13 +08:00
wandering1 09f8a6fb20 docs(net): 监听生命周期根治设计——证据、决策与执行清单 
新增 docs/子系统设计/网络Socket监听生命周期设计说明.md（9 节）：

原理三层证据——芯片层：LISTEN 与 ESTABLISHED 是同一 TCP 状态字节的互斥
取值（手册 §5.22 L535-545、§5.29 L609「直到连接成功后」），全手册无任何
"连接结束自动恢复监听"条款；且本仓 fun_para=0x08（bit3 SOCKET_CLOSE=1，
Trap 18/25 定案）使断开后芯片停在 0x05/0x00，即 B10 看到的"孤儿芯片态"
是本仓配置的合法后果，而非芯片异常。规范层：RFC 1122 §4.2.2.18 明文被动
OPEN MUST NOT affect any previously created connection record，POSIX
accept() 原文 socket 不变，lwIP 把监听器所有权写进 tcp_close() 文档——
本仓需要靠"EOF 不得 close 监听 fd"铁律维持正确性，即架构欠债的凭证。
实现层：EOF 是时序敏感边沿（只在 recv 那一刻 state==CLOSED 才给），导致
重建所有者散成 12 个（栈内 8 + 应用 4）、15 个迁移点、15 个无人负责组合。

关键决定 D1~D7：不启用芯片原生多连接模式（A′ 出局——FTP 改造清单第 4 条
已定案"多连接模式不支持多监听"，本产品有 21/8888/7003 三个常驻监听加会
话期动态 PASV，且历史上踩过 Trap 02/11，FUN_PARA 初始化后不可改）；采用
"会话结束电平化 + 监听重建单一所有者"的形态 B 深化，不做控制面重写；对
账④保留不撤回（Trap 22 实证事件会丢，周期对账不可删），其副作用由 P1
消除；fun_para 保持 0x08，不回退 Trap 25 的排空契约。

证据附录含 B10 探针日志、A/B 归因数据（基线 5/1/1/5 vs B3 3/7/2/1，均值
3.0 vs 3.25，统计不可区分）、④ 修复后完整回归矩阵、官方 EXAM5/EXAM10 所
有权模型（SDK 行号）、状态机 15 迁移点与关键判据、三服务契约不一致表。

Trap_Records B10 残余改写为指向该文档，并明确记录 ④ 的副作用：抢先
relisten 会把慢消费者的 EOF 永久吞掉，g_client 不清、新客户端数据被旧会
话静默吸收——④ 修好了端口拒连却撑大了另一侧窗口，P1 必须补。

登记行 N-32 已写入 docs/待处理内容.md 工作区，但该文件与并发在途的 N-27
改动混杂，本次不提交，留待其归属方一并入库。
 2026-10-12 11:17:48 +08:00
wandering1 4f2cc8bc90 fix(net): B3 只清本 Socket 中断；B10 对账认领孤儿监听修永久拒连 
B3（net_listen_locked / net_relisten_locked 两处）：
原先对全部 8 个 Socket 做 GET_INT_STATUS_SN（读即清）并丢弃式读全局中断
状态。依据三条：§5.15 明文全局寄存器整体读即清且无按位清除手段；net_poll
只在全局位置位时才读该 Socket 的 SINT（位图门控）；SINT 粘滞到被读
（Trap 14 实证 close/open 都不清）→ 读走即永久销毁其它在用 Socket 的
CONNECT/DISCONNECT/TIM_OUT/SENBUF_FREE。git 考古定性为多连接时代调试遗留
（e862009bc → 319d00e3 → db64e6acf），不属于任何已登记 Trap 的修复；官方
SDK 21 个例程一律"位图门控 + 单 Socket 读 + 立刻转存"，open/listen 前后
不清任何中断，无一例全量读 8 个 SINT。现收窄为只清本 Socket 的 SINT，
全局交 net_poll 集中读清，与 AGENTS 模块约定一致。

B10（孤儿监听 → 端口永久拒连）：
断开时 handle_disconnect_event 释放分支置 CLOSED 并注释"等待应用重新监
听"，而 ui_net_sink 只在 net_recv 返 0（EOF）时才清 g_client，EOF 已被该
事件分支消费 → net 层等应用、应用等 EOF、对账只裁 ESTABLISHED/LISTENING
直接跳过、芯片不会自己回 LISTEN，四方互等。实测孤儿态 state=0 /
chip=0x05/0x00 持续 12s+，:7003 300ms×10 为 0/10 且 +30s 仍拒连。
net_reconcile_tick 新增类型④认领孤儿，复用 net_relisten_try（自带"已在
重试队列不重复登记"保护，与 D10 队列、Trap 23 沉降隔离兼容）。门槛中
auto_relisten 是决定性一条：缺它则出向连接（板级 Phase 7 TC701~703 绑本
地口）会被误判孤儿并被 relisten 成监听器。

工具：ftp_abort_probe.py 仍用 anonymous 登录，N-19 后 530 拒 → Trap 23 两
条腿假 0/5（round1 PASV failed，且半认证会话占死 FTP 唯一会话）。改
admin/admin 后 RST 5/5、FIN 5/5。

回归：:7003 300ms×10 由 0/10 永久死 → 10/10（+20s 存活）；:21 0ms×50 与
100ms×50 均 50/50；:8888 0ms×20 为 20/20；ftp_regression 11/11×2；Trap 23
RST 5/5、FIN 5/5；@test PASS（600ms、回读无差异）；@build 0/0，
Code=197084。

残余：B10 生产者未根治，释放分支仍把状态停在 CLOSED 等应用重建，类型④
是兜底；根治涉及 Trap 25 closed-with-data 契约，单列评估。
 2026-10-12 10:35:55 +08:00
wandering1 794a688a3c fix(net): B2 不再丢弃 TCP_CONNECT 命令状态，命令级被拒立即回滚返 -1 
问题：net_connect_locked() 调 ch395f_tcp_connect() 后直接丢弃返回值，
而同函数内 open/listen 都查了状态。§9.2.2 ⑧ 明文：发完
CMD_TCP_CONNECT_SN 后须轮询 GET_CMD_STATUS，返回 SUCCESS 仅表示
**命令**执行成功（不代表 TCP 连接成功），其他值表示命令执行失败。
丢弃它 = 命令级被拒时本层停在 CONNECTING，要等 30 s recv 超时才暴露。

修法（不能一刀切）：只拦"非 SUCCESS 且非 BUSY"。因为
ch395f_poll_cmd_status() 超时返回的就是 CH395F_ERR_BUSY（= 4 s 内
芯片仍在执行，命令并未被拒绝），把它当失败会误杀慢芯片。明确失败
→ 打 [ERR] rejected by chip: 0xNN 留痕 + 按 §9.2.2 ⑧"再次连接需从
⑤ 重开"关掉 Socket、状态回滚 CLOSED、返 -1（NET_ERR_INVAL）。

顺带修一处错注释：原写"发起 TCP 连接（异步：芯片立即返回）"，实际
驱动内部已按 §9.2.2 ⑧ 轮询 GET_CMD_STATUS 最多 4 s，并非立即返回。

硬件回归（Phase 7，NET 层 TCP Client 主动连接）：
- TC701 连接 + 64 B 回显逐字节比对 PASS（cksum=0x000007E0）
- TC702 关闭重连 x3 全 PASS → 正常连接路径无误杀
- 不可达对端时芯片回的是 SUCCESS、ret=0 且不打 rejected by chip
  → 失败仍由 CONNECT TIMEOUT(~1.6 s) 裁定，行为未变；新分支只在
  芯片明确说"命令执行失败"时才走
- TC704 socket create #5 FAIL = E-23 既有（NET_MAX_SOCKETS=8 减 3
  个常驻监听 → 并发上限 5，而 PHASE7_MULTI_COUNT 仍是 8），与本次无关
- TC703 要求 PC 服务器离线，与 701/702/704 环境互斥，同轮连跑必有
  一侧失真；其 rc==0 断言等于把"返回值被丢弃"写进判据，真发生命令
  级被拒时它会 FAIL（属正确告警）

前两轮 Phase 7 全灭不是改动问题，已登记为台架坑：本机对
C:\programdata\anaconda3\python.exe 有两条 Public 入站 Block 规则，
而 .venv 的基座解释器正是 Anaconda python；Windows 防火墙块规则优先
于放行规则，故中途加的 8081 端口级 Allow 完全无效，只有临时关 Public
才通。症状极具误导性（芯片 1.6 s 报 CONNECT TIMEOUT、net_connect 仍
返 0、openOK 照常打印），看着像芯片/驱动故障。

残余（登记未动）：net_reconcile_tick 仍只裁 ESTABLISHED/LISTENING，
CONNECTING 丢中断无人收口——产品不走出向连接、无法实测，按 Trap 25
"不加未证明的复杂度"只登记不实现。

验证：构建 0 错 0 警、Code=197032；内存快照已刷新；doc-links EXIT=0、
无 U+FFFD；@test 闭环 PASS（戳 fw build: Oct 12 2026 08:03:29
suite=NONE、回读无差异、548 ms）。测试宏已复原，两个测试头文件与
HEAD 字节一致；临时防火墙规则已删除、Public 已重新启用。
 2026-10-12 08:17:36 +08:00
wandering1 9a45be1700 docs(net-audit): B1 服务器侧 KeepAlive 前提被实测推翻，撤回改动并记台架注入陷阱 
B1 原判"产品路径从未启用 Socket KeepAlive → 静默断开无人知晓"（§5.56
要求 TCP 服务器在产生 SINT_STAT_CONNECT 后开启，产品三服务全是
Server，60s/5s/3 参数空转）。本轮按 §5.56 在 LISTENING→ESTABLISHED
分支补了 ch395f_set_keepalive_enable() 并上板做定案实验，结果推翻前提。

实测：连接静置时禁用 PC 网卡（真·静默死亡），芯片 +2 s 即报
"[ERR][NET] sock0 TIMEOUT" → 本层 relisten quarantine 释放重开监听。
2 s 只能是重传（§5.17 本仓 8×200 ms = 1.6 s 量级），与 KeepAlive 无
关——IDLE 最短 60 s、芯片默认也要 20 s。链路层失效本就被快速覆盖，
故依 Trap 25 铁律「不留未证明的复杂度」撤回该改动，只在代码内留注释
记录（含未覆盖场景与注入难点），不保留无证据的动作。

另一半天真：设备 2 s 就重开监听，PC 侧那条 socket 却继续"自认存活"
直到 4 分钟后自行 close（Python 对死链路 close() 不报错）。不对称恢复
才是现场隐患——客户端下次写会吃到 §5.29 的 RESET；单靠设备侧开
KeepAlive 只解决设备这一半。

新增「台架注入陷阱（2026-10-12）」四条（本轮踩到的，全部实测）：
1. Windows 出站防火墙规则不能模拟"对端静默死亡"——WFP 对已建立的流
   有状态缓存，中途加 Block 不影响既有连接；实测静置+阻断 250 s 芯片
   毫无反应，看着像"KeepAlive 不生效"，实则 ACK 一直正常往返。
2. 该规则还会吃掉本机后发的 FIN → 设备留下幽灵 ESTABLISHED，之后新
   连接被 §5.29"向试图连接的远端发送 TCP RESET"直接 RST，表现为"端口
   拒连"，极易误判成设备故障（实为自伤，撤规则后自愈）。
3. 真正掐断链路用 Disable-NetAdapter；本机该 cmdlet 只有 -Name /
   -InterfaceDescription，没有 -InterfaceIndex/-ifIndex（第一次写错
   导致那轮网卡根本没关）。网卡名是中文，用
   (Get-NetAdapter -InterfaceIndex 19).Name 取值再传，避免命令行写中文；
   禁用/恢复必须写在 try/finally 里。
4. 仍未覆盖："链路仍在、对端静默"（NAT 会话过期、中间节点黑洞）才是
   服务器侧 KeepAlive 唯一可能的价值场景，本机无安全注入手段（静态
   ARP 黑洞会被交换机泛洪兜底、删 IP 会连带拆掉本机连接）——未证实，
   故不保留改动。

判读教训（与 Trap 25 同源）：看到 TIMEOUT 先算时序再归因，2 s 与 60 s
一眼可分；否则会把重传超时误记成"KeepAlive 生效"，把相关性当因果。

验证：构建 0 错 0 警、Code=196912（与 afb0bfd 一致，说明撤回后二进制
回到已提交状态）；doc-links EXIT=0、Trap_Records 无 U+FFFD 无 BOM；
@test 闭环 PASS（回读无差异 + forbidden 三项与 [ERR] 全缺席 + 594 ms）。
 2026-10-12 07:49:58 +08:00
wandering1 afb0bfd5ff fix(net-audit): 修 6 处寄存器口径/注释错误 + Trap 记录全量复核与审计章节 
智能体团队四路并行只读审计（驱动层逐命令 / NET+测试层逐调用点 /
Trap 01-12 复核 / Trap 13-25 复核），三源交叉：芯片手册 + WCH 官方
SDK（CH395CMD.c / CH395INC.H / 21 个例程）+ git 历史。本提交只落
"已确认且低风险"的修法，其余发现登记进文末审计章节待逐项决策。

已修（A 类，全部有手册/SDK 出处）：
A1 测试 TC-203 反核实写成 st_chk[0]==CH395F_TCP_ESTABLISHED——§5.22
   byte0 只有 00H/05H，条件恒假，这道 Trap 14 防线自写下起从未生效
   且日志无痕（与 Trap 07 同类的 byte0/byte1 语义越界）。改为
   byte0==OPEN && byte1==ESTABLISHED。
A2 测试 Phase3/4 把 GET_RECV_LEN 返回值直接当读取长度（本地
   rx_buf[300]/[64]，芯片 RX 缓冲 2KB）→ 栈溢出；补夹取 + 留痕
   （同文件 TC201/202/204 早已 clamp，这两处是漏）。
A3 CH395F_GINT_STAT_DHCPV6 由 0x8000(bit15) 改 0x1000：SDK 是
   (1<<12)、§5.16 明确 CH395F 的 [12:15] 保留。全仓零引用。
A4 ch395f.h 命令分组注释字节数错 4 处（GET_GLOB_INT_STATUS_ALL /
   GET_UNREACH_IPPT 归"1 字节输出"、SET_FUN_PARA 归"1 入 1 出"、
   SET_RETRAN_PERIOD 归"3 字节输入"、GET_SOCKET_STATUS_SN 归"1 字节
   输出"）；KeepAlive 参数注释"秒"改"毫秒"（§5.53/5.54 单位 ms）；
   set_retrans_count 删"0=默认值5"（§5.17 默认 12、无 0=默认语义）。
   实现全对、注释误导——Trap 25 的 1 字节缓冲栈越界正是这类注释发起。
A5 net_socket.c 六处注释与手册/HEAD 相反：FUN_PARA(SOCKET_CLOSE=0)
   实为 bit3=1（正是 closed-with-data accept 的契约依据，写反会诱导
   把 0x08 改回去）、"初始化成功后设置 MAC"（§9.2.1 ① 是之前）、
   "复用默认缓冲"（net_init 已为 8 Socket 显式分配）、"由 MSS 推导"
   （固定布局、Trap 21 已解耦）、"等 SEND_OK"（门控是 SENBUF_FREE）、
   UDP 头 [0-1] reserved（§9.2.4 是数据长度）。
A6 ch395f.c write_send_buf 超限静默 return（void 无日志），且上限取
   DMA 2048 而非发送缓冲 1024；读路径有 OVERSIZE 金丝雀、写路径没有
   → 补 [ERR] 留痕 + >1KB 告警，行为不变（分块责任仍在调用方）。

审计确认"不是 bug"的最危险一项：GET_GLOB_INT_STATUS_ALL 拼装方向。
我们"第1字节|第2字节<<8"与官方 CH395CMDGetGlobIntStatus() 逐字相同，
glob & (1<<(sock+4)) = §5.16 bit4..bit11 = SDK GINT_STAT_SOCKn，三源
一致。另 55 条命令码、9 处 16 位字节序、14 条读命令字节数、60 个
常量、12 个单位参数点、48 块缓冲布局逐条核对无异常；17 处
get_socket_status 调用点全是 st[2]，Trap 25 的 1 字节 bug 无残留。

文档：Trap_Records 加文末「2026-10-11 寄存器/数值口径全量审计」章节
（干净清单计数 + 15 条新发现含已修/待修 + 文档待修清单）。就地修正：
Trap 07 定案更正里"全文 RST 仅见于错误码与引脚"的绝对表述（§5.29 /
§9.2.6 其实写了芯片发 TCP RESET，只是都与 close 无关）+ 删不可核验的
"11 个悬空提交"；Trap 16 的"IP/端口寄存器大端"（端口 §5.25/5.26 明确
低字节在前）+ 注明 §5.8 总括与官方例程自相矛盾；Trap 18 删悬空
"Trap 19"（该条从未存在）、net_socket() 改 net_bind()；速查清单 DMA
1500 改 2052；Trap 13 加复核注（最高优先级：其"部分读后 recv_len
归零"与 §5.34 直接相左、与本仓 TC201 注释相反，且同族结论已被 Trap 21
撤回，却仍被 6 处当现行约束引用）；Test_Guide 的 TRAP-07 行仍教
"卡 FIN_WAIT_2 / close(RST)"、悬空的 Trap 19 与两处"见风险 #N"。

待修（B 类，登记未动，需逐项决策与实测）：B1 产品路径从未启用 Socket
KeepAlive（唯一调用点在 client 分支，产品三服务全是 TCP Server，
§5.56 要求服务器在 CONNECT 后开，60s/5s/3 参数空转）；B2 tcp_connect
返回值丢弃且 CONNECTING 不在对账范围；B3 net_listen_locked 全 8 Socket
读即清会吞别槽事件；B4 全局中断 bit0-3 从不消费、get_unreach_info 零
调用；B5 getsockname 的 s_addr 与本层约定相反致 FTP 日志设备 IP 反序
（PASV 双重反转恰好正确，勿误判）；B6 三处判据只看 byte1 未按 byte0
门控；B7 Phase5 单次写 4093B；B8 Phase4 缓冲块与 sock4 交叠；B9 杂项。

验证：产品构建 0 错 0 警、Code=196912（+124B，写路径两条新日志）；
测试路径（PHASE2/3/4 打开）单独编译 0/0；内存快照已刷新；doc-links
EXIT=0、无 U+FFFD、pre-commit 全绿；@test 闭环 PASS（戳匹配 + 回读无
差异 + 锚点 x1 + 548ms）。
 2026-10-12 00:20:17 +08:00
wandering1 bca6cc694c test(net): TC-NET-204 定案 Trap 07——disconnect→close 不卡死，真因是 bit3 
Trap 07（2026-07-19 写成"2025-07"）断言"disconnect→close 让 Socket 卡
FIN_WAIT_2 数分钟、因为 close 不发 RST"。新增定案用例 TC-NET-204（Phase 2
硬件层，同一 Socket、同一 PC 回显、FUN_PARA=0x08，三模式 × 5 轮 = 45 项判定
全过）做受控对照，实测推翻其机制说法、保留其做法：

  A close                → 回 CLOSED 0/0/150/0/0 ms，重开 5/5 OK
  B disconnect → close   → 全部 +0 ms，重开 5/5 OK（"卡死"未出现）
  C disconnect（不 close）→ 10 s 内从未回 CLOSED，byte0 恒 0x05、byte1 0x00；
                            直接 open → 0x20 FAIL（5/5），补 close 后 +0 ms

三条推翻：① FIN_WAIT_2(06H) 全程未出现（15 轮 × 9 采样点），实测过渡态只有
TIME_WAIT(0AH)；② 手册无 RST 语义（§5.35 只说 close 前自动断链），且主动发
FIN 先进 FIN_WAIT_1 才进 FIN_WAIT_2，原说法跳拍；③ 观测越过了 byte1 的语义
边界——§5.22 byte0 只有 00H/05H，官方 SDK 注释明确 byte1 仅在 byte0=OPEN 时
有意义，而当年代码判据用的是正确的 byte0，break 后照样打印 byte1，于是"已
CLOSED 下的残留读数"被读成"卡在某个 TCP 态"。

真因：FUN_PARA bit3 SOCKET_CLOSE=1（§5.52 ②）下产生 DISCONNECT 后芯片不关
Socket、不清缓冲，Socket 停在 0x05(OPEN)/0x00(TCP_CLOSED)，此时 open_socket
必返 0x20 FAIL——即历史那条 Phase 2 open_socket: 0x20 / socket 未完全关闭。
拉回 CLOSED 的动作是 close，与 RST 无关。

git 佐证：ch395f_tcp_disconnect() 自首个提交起只有定义、零调用点（含全部分支
与 11 个悬空提交），"disconnect→close" 从未进入提交代码；当时驱动已轮询
GET_CMD_STATUS（4 s 上限），也不是"命令没等完成"。

做法保留，理由换成三条有支撑的：§5.35 close 已自动断链故 disconnect 多余；
disconnect 制造的 DISCONNECT 事件在 bit3=1 下须我方消费/预清（Trap 14/17/22）；
它把芯片推进 closing 过渡态、重开需沉降（Trap 09）。本轮 15 轮重开均未观察到
残留 DISCONNECT(0x10)——close 顺带清掉锁存，这才是"直接 close"安全的原因。
另消解 Trap 17 与 Trap 07 的旧矛盾：实测支持 Trap 17（close 走 FIN teardown、
0~150 ms 可见 TIME_WAIT），不支持 RST 说法。

文档：Trap_Records.md 加 Trap 07「定案更正」整节 + 改写「驱动关键点 → TCP 关闭
重连」速查清单（删 RST 说法、补 byte0/byte1 口径与 0x20 陷阱）；Test_Guide.md
新增 TC-NET-204 用例表（前置含 tcp_server --timeout 900 这条坑：首连后连接
间隔 >60 s 服务器会自行退出）。

验证：测试构建 0 错 0 警、Phase 2 74/75（唯一 FAIL 是 TC-203 环境守卫，PC 服务
未及时关闭）；宏已还原，产品构建 Code=196788 与 HEAD 一致（用例全在测试宏内、
产品零足迹），@test 闭环 PASS（戳匹配 + 回读无差异 + 锚点 x1 + 590 ms）。
pre-commit 全绿（test-cppcheck / doc-links / no-mojibake 均 Passed）。
 2026-10-11 21:40:45 +08:00
wandering1 c5227291bd test(fw-stamp): 身份戳覆盖测试宏——头依赖 + suite/dstr 变体串 
问题：__DATE__/__TIME__ 只在所属 TU 被重编时才刷新，而 app_main.c 不依赖
test/board/test_config.h → 只切套件宏的增量构建不重编它，测试镜像与产品
镜像顶着同一个 fw build: 戳，@test 的戳校验对"两种构建互换"完全失明
（2026-10-11 N-31 复测实测：两者戳同为 Oct 11 2026 14:44:11，只有
-CmpFile 回读才发现镜像不同）。

修复（App/app/app_main.c，两条防线）：
- #include "test_config.h" 建立头依赖 → 改 TEST_SUITE_* /
  ENABLE_DESTRUCTIVE_TESTS 必重编本 TU，戳必刷新（根因修复）
- 戳串追加 FW_BUILD_VARIANT = " suite=<TEST_SUITE_NAME> dstr=<on|off>"
  → 戳内容本身区分构建，时间撞车也能分辨

实测：产品 20:36:11 suite=NONE dstr=off ↔ 测试 20:36:40 suite=CH395F
dstr=on ↔ 还原宏后 20:36:55 suite=NONE dstr=off（时间戳每次都变 = 头依赖
真的生效）。@test 全闭环 PASS：戳匹配 + 回读 No difference found +
锚点 x1 + 零 [ERR]。run_boot_test.py 无需改动（戳按"标记后连续可打印
ASCII"抠取，天然吃下新后缀）。

代价：Code 196764 → 196788（+24 B），@build 0 错 0 警。

文档：自动化测试流程.md 补「戳覆盖构建配置」小节与变更记录行；失败模式
表新增一行——戳命中但 suite= 与要跑的套件不符 = 烧的是产品镜像。

门禁：mem-numbers 钩子拦下「RAM 文档快照与 .map 不一致」→ 用
check_mem_numbers.py --write 刷新生成区（ER_IROM1 213,256 → 213,396 B）。
 2026-10-11 20:45:09 +08:00
wandering1 b8619a0984 docs(net): N-31 销项——0x08 下多 Socket 实测 34/34，补台架前置排雷 
N-31（0x08 下的多 Socket 台架复测）已闭环并销项。

实测（2026-10-11 20:18，板端 CH395F ver=0x4A，日志 fun_para=0x08）：
- 构建：TEST_SUITE_CH395F + ENABLE_PHASE7_TESTS，PHASE7_MULTI_COUNT=5
  （E-23 未修：NET_MAX_SOCKETS=8 减去 FTP/对时/远显三个常驻监听）
- PC 侧：ch395f_socket_test.py tcp_server --port 8081 --max-conn 8
- 结果：**Phase 7 34/34 PASSED（failed=0）**；TC704 五路全部
  ESTABLISHED，每路 64 B 回显字节级比对通过
- 芯片 Socket 实测落在 sock2/4/5/6/7（0/1/3 被监听占用）→ Socket 4~7
  在 bit0=0 下完全可用，与官方手册"8 Socket 原生 + _SN 索引寻址"一致
- 烧录 -Rst -Run + 回读 No difference found；测试宏已还原、产品构建重烧

台架前置排雷（两条都会造成全量假 FAIL，已登记进 Trap 18）：
1. PC 适配器落在 Public 防火墙配置文件 → 入站 8081 被静默丢弃，症状是
   TC701/702/704 全部 CONNECT TIMEOUT（而 PC→设备 21 端口与 ping 正常），
   极易误判成"0x08 毁了 client"。
2. 上一轮遗留的 tcp_server 进程仍占着 8081，新起的服务器绑不上端口
   却不报错。

登记簿：N-31 行删除（完成即销项），W5 行加销项注记；Test_Guide TC704
补复跑记录与前置条件；Trap 25 疑点条目改判为"已实测通过"。

验证：@build 0 错 0 警（产品构建 Code=196764）；check_doc_links --all 通过。
 2026-10-11 20:24:39 +08:00
wandering1 d758d5cd7b docs+net: FUN_PARA 定案 0x08——bit0 保留位证伪，Trap18 定案更正 + N-31 
CH395F FUN_PARA 的 bit0 之争定案：取 0x08（bit3 SOCKET_CLOSE=1，bit0=0）。

证据（一手，按强度）：
- 官方手册 V2.2/V2.3 与旧版 V1C/V1E/2020 版 §5.52 位表：bit0 一律
  「保留,必须为0」，任何版本都不存在「bit0=多 Socket」这一行。
- 官方 SDK CH395INC.H:349-353 位宏只有 bit1/3/4/7/8，无 bit0 宏。
- 官方例程直接反例：EXAM5_TCP_Server 传 0x02（bit0=0）却给 Socket 0~7
  全部配缓冲；EXAM11_FTPClient 直接传 0x08；全 EVT 包无一处 0x09。
- 手册命令章前言：8 Socket 是芯片原生能力，靠 _SN 索引寻址；§5.45
  真正的门槛是缓冲分配（Socket 个数 >4 须重分配缓冲）。
- 概念讹传源是 bit1 FUN_PARA_FLAG_TCP_SERVER（服务器多连接，§9.2.6）。
- 互联网检索无任何出处称 bit0 为单/多 Socket 模式。

Trap 18 的「bit0 决定 Socket 数量」是推论而非实测：无日志、无 TC 号，
且当年 Socket 1~7 未显式配缓冲（Trap 01/02 混淆因子未排除）；TC704
40/40 与结论出自同一提交，属自证，不构成 0x08 的对照。

改动：
- net_socket.c：0x09→0x08（原为未提交改动，现已过编译门禁）+ 版本留痕
- ch395f_reuse_bench.c：0x09→0x08，与生产 net_init 同构
- net_test_task.c：TC704 注释纠正（Socket 可用性不依赖 FUN_PARA）
- Trap 18 新增「定案更正」完整证据链；Trap 25 疑点改判为定案
- Test_Guide / 产品需求 / 架构总览 / BSD 调用关系：0x09→0x08 改口径
- 待处理内容.md 登记 N-31：0x08 下多 Socket 台架复测（TC704 降并发
  ≤5 + FTP 回归），补 Trap 25 销项时漏登记的尾巴

验证：@build 0 错误 0 警告；check_doc_links --all 通过；无 U+FFFD。
 2026-10-11 20:05:22 +08:00
wandering1 d1e6bb4ba7 W5波+N-19收口：FTP鉴权落地、Trap25三连定案修复(N-30)、N-20/N-23/N-26 
N-19 FTP 鉴权：
- lftpd_auth（USER/PASS 状态机 + 连续5次失败锁60s）+ SHA-256
  (user||pwd) 口令哈希；config.ini [ftp] 段 user/pwd_hash/write，
  出厂 admin/admin 在用有启动告警；lftpd_log.c 删除并入 lftpd_auth
- ftp_cfg 配置读写；台架 ftp_auth_bench.py 13/13

N-30 / Trap 25（CH395F_Trap_Records.md 四次定案全记录）：
- 修复1 closed-with-data accept：客户端发完正常 FIN 后芯片按
  FUN_PARA(0x09) §5.52② 保留 Socket+RX 缓冲，旧代码把 CLOSED 一律
  relisten 自毁缓冲 → STOR 必挂 425；改为接受"已关但可读"连接排空
- 修复2 丢 CONNECT 中断探针 net_lost_connect_probe + last_peer_port
  幽灵甄别（拆链窗口握手完成但中断丢失，双信源去抖补 accept）
- 修复3 send_list/send_nlst 批量单发：背靠背 ~60B 小段毒化芯片 TX
  （芯片报 SEND_OK 但对端全丢），整份目录一次性写入
- 证伪存档：固定沉降/Socket 轮换冷却/listen 门控（台架 v7 矩阵）
- 台架工具 test/board/ch395f_reuse_bench.{c,h} + host 脚本存档
  （不注册编译；实验分支 n30-chip-bench 保留）

N-20：Error_Handler 死循环降级（记录+复位路径）
N-23：scripts/check_registration.py 双端注册反向校验（pre-commit）
N-26：GD5F NAND 直 DMA 调用方缓冲窗口断言

验证：BUILD_OK 0/0；ftp_regression 连跑 4 轮 11/11（修复前
LIST#4/#7 100% 挂、STOR#2 曾 100% 425）；ftp_auth_bench 13/13；
@test 启动标记 PASS；ci_local L0+L0.5 全过；doc-links 通过。
登记簿 N-30 已销项。
 2026-10-11 18:50:24 +08:00
wandering1 eddbedeee8 docs(AGENTS): 入口重构——补宏观概况与边界块，瘦身51KB→25.8KB，子域知识入skills
CI / L0 静态门禁 (pre-commit) (push) Has been cancelled
Details
CI / L0.5 主机侧单测 (MSVC) (push) Has been cancelled
Details 
- AGENTS.md 51,067→25,828 B（−50%）：审计→迁移→删除，逐节 diff 零信息损失
- 按调研（agents.md 官方/aihero/airflow）补「项目概况」：一句话定位、
  数据主线、顶层目录地图、分层边界；平台约束 17 条分 5 组
- 新增「边界（Ask first / Never）」：git commit/push 须明确指示首次入库
- 串口助手、LVGL 模拟器两节移入 serial-assistant / 新建 lvgl-simulator skill
  （开关语义按 main.c 实锤）；LVGL 两条实证坑移入 ui-verify skill
- 9 条入口独有细节迁移至对应设计文档（存储/看门狗/启动顺序/文档规范/
  pre-commit 使用说明/keil-build skill）；@test 细节指向自动化测试流程
- 新增 docs/AGENTS编写指南.md：六原则/模板/反模式/维护纪律 + 本仓案例
- 修正 3 处对 AGENTS 串口节的过时引用；docs/README.md 登记新文档
 2026-10-11 10:44:50 +08:00
wandering1 3b90107181 chore: .mnemon/ 记忆状态只留本机，不进版本库 
- 加入 .gitignore：documents/index.json、runtime/MEMORY.md、USER.md、
  memories.json 是按机器/按人累积的本地私有状态
- 入库的代价：每次记忆写入都产生提交抖动，且可能带出本机绝对路径与
  个人偏好
- 上一笔只含 .mnemon/ 四个空骨架文件的提交（未推送）已撤销，历史里
  不含 .mnemon/；磁盘上的文件保持原样，只是不再被跟踪
 2026-10-11 08:59:03 +08:00
wandering1 c936441c83 门禁扩容：新增 lv-conf-sync、simulator/ 纳入全部钩子；含 L3 定值/元件框架落地 
本轮把"自研代码落在门禁之外"的口子收掉，同时落地 LVGL 特性裁剪与
L3 保护定值/元件框架。

门禁（.pre-commit-config.yaml，26 个钩子）
- 新增 scripts/check_lv_conf_sync.py + 钩子 lv-conf-sync：比对两份
  lv_conf.h 的**生效值**（未定义则取 lv_conf_internal.h 兜底默认），
  抓 MISMATCH / LVGL 不认的宏名 / 同文件重复定义
- 顶层 exclude 删掉 simulator/：其下 21 个 tracked 文件全是本项目自研
  代码，生成物（build/、SDL2/、tests/ref/、shot*）已在 .gitignore；
  doc-links 的 exclude 同步删除
- lv-conf-sync 的 files: 覆盖两端配置 → 只改 simulator/lv_conf.h 也触发
  （pre-commit 4.x 已移除 always: true，实测只告警并跳过，无兜底开关）
- 新增 prot-set-unit-test / prot-elm-unit-test 两个主机侧单测钩子
- S11(2.3.5) 判定细化：禁的是"用路径找文件"，尖括号系统头带子目录
  （如 <sys/stat.h>）不再误报；全仓库复核仅 2 处项目代码判定变化

模拟器代码整改（纳入钩子后暴露，全部修代码而非豁免）
- cppcheck 4 处：sim_syslog.c 判空分支内解引用 p_epoch（真实 bug）、
  2 处 struct tm 未初始化、1 处指针可加 const
- coding-standard 61 处：44 处函数左大括号并到右括号同行、8 处补函数
  注释、3 处补文件头注释块、2 处 __ 前缀保护宏改 XXX_H、2 处 sprintf
  改 snprintf（写入字节数与原来完全一致）

LVGL 特性裁剪（F-1/F-2/F-3）
- 两端 lv_conf.h 对齐同一特性子集：删 26 个 LVGL 9.3 不存在的选项名、
  3 处重复定义，10 项靠默认值隐式生效的改为显式固化
- 实测对镜像体积中性；价值在防漂移，且模拟器 golden 回归跑的正是固件
  实际编译的配置

L3 软件侧
- App/algo/prot_set.* Q10 定值模型（范围校验 / 整表 all-or-nothing /
  校验和封存-自检-闭锁）+ prot_elm.* 通用"滞回+定时限"元件框架 7 实例
- test/host/prot_set、test/host/prot_elm 主机侧单测；uvprojx 挂载两处

文档同步
- pre-commit使用说明：§2.8 S11 口径、§2.15 lv-conf-sync 详解、新增 §5.5
  复盘（教训：exclude 只写真正不该进钩子的路径）
- AGENTS.md、UI_设计架构 §1.4 第 10 条、RAM 分析、审查报告刷新与销项

验证
- @build BUILD_OK 0/0（Code=194276 RO=15872 RW=876 ZI=139892）
- 模拟器重建：菜单 8 状态像素逐字节一致（池 5368 B）、11 内容页黄金参考
  全过（往返 5448 B）、remo sink 0/25600 位差异、--logtest/--cfgtest PASS
- 全仓库 cppcheck / coding-standard / no-mojibake --all-files 全过
- check_doc_links --all 129/0；check_mem_numbers --check 内存数字一致
- 端到端：往 simulator/lv_conf.h 注入一行漂移 → 钩子 FAIL（exit 1）
 2026-10-11 08:48:49 +08:00
wandering1 13a4e61c27 L1-6 采样有效性校验：adc_health 判定层 + 告警编排 + 31 用例单测 + 台架闭环 
新增 App/algo/adc_health.c/h（纯逻辑判定层，零平台依赖免桩单测）：
- 静默：两侧帧序号连续 >=100ms 无前进（电平位可自愈，flags() 为 L5-4 闭锁预留）
- 丢帧：TPAFE 序号一次前进 >1 计 tgap（与 STM32 侧 adc1_gap 对称，边沿事件）
- 单调性：序号倒退锁存位；tick/计数差值法 (int32_t)(a-b) 回绕安全
- 错误增量：FRSTDATA / HAL 错误 / STM32 停摆计数增量，事件位与锁存位编号对齐，
  消费者按位图做"每类每次开机留痕一次"编排

adc_task.c v2.9 告警编排（判定与编排分离）：严重事件/电平上升沿 DBG_ERROR +
SYSLOG_SELFTEST（每类每次开机一次防刷屏），下降沿 DBG_INFO 恢复；gap 不告警
（消费者超拍是已知现象，告警会淹没真故障）；心跳行增 tgap 观测字段。

主机单测 test/host/adc_health/ 31 用例全绿（100ms 门限两侧 / 边沿语义 /
倒退锁存 / tick 回绕 / NULL 守卫 / init 幂等），登记 adc-health-unit-test 钩子。

台架 @test PASS：零 [ERR]（健康不误报）、tgap=1->2 与 adc1_gap 同步可见、
frames 1000.0 Hz；证据 boot_log_data/20261011_prod_adc_health_boot_log.txt。

抬栈：adc_health_report->syslog_post 控制台回显尾使 adcTask 静态最坏链
832->1080 B（512 words 余 968 B < 1024 B ISR 底线）-> 512->640 words，
复测余 1480 B / 57%，堆 min_ever 7152->6640 B（-512 B 符合预算）。
AGENTS/README 任务表、RAM 方案 §2.3、规划文档 §3.1 L1-6 已同步置完成。
 2026-10-11 01:28:20 +08:00
wandering1 6c8f82ec54 docs(algo): L2 相量层台架闭环收尾，P0 里程碑达成（证据+栈复测） 
- @test 新增 Required 标记 phasor(first)/phasor(hb) 并校验顺序
  App init OK>phasor(first)>phasor(hb) → PASS（net init: OK 不在序内：
  adcTask 与 netTask 并行，phasor(first)≈+500ms 早于 net init 属正常）
- 证据归档 boot_log_data/20261011_prod_phasor_boot_log.txt：5 实例相量
  开机即产出、frames 每 10s +10000（1000.0 Hz）、idle=0、零 [ERR]、
  fw build 身份戳匹配、回读一致、锚点 ×1
- 栈复测：adcTask 静态 832 B / 实测峰值 928/2048（余 54%），7 任务
  全 PASS；RAM 方案 §2.3 基线同步
- 规划 §3.1 L1-9、§3.2 L2-1~L2-4/L2-6/L2-7 置 ✅（精度判据保留
  "待标准源"注）；L2-5 更正为"V0.1 不适用、随 V0.2"（N-18 + 外部
  零序专用通道，原表下注系误记）；§7.1 P0 里程碑置 ✅
- 自动化测试流程登记 phasor 常开标记（hb 需采集窗口 ≥10s）
 2026-10-11 00:56:23 +08:00
wandering1 54d6d2d5d5 docs: 删除 Task #32 停摆分析（已结案），可复用结论并入看门狗设计说明 §11 
按登记簿"完成即销项"规则删除 docs/问题记录/UI任务看门狗停摆分析.md
（560 行）。结案依据：累计 38 次上板启动 0 复现（原 L2 基线 3/10），
P0/P1-4a/P1-5/P2/方案 A 全部落地，方案 B 已评估决定不做。

并入 docs/子系统设计/看门狗设计说明.md 新增 §11（只留可复用部分）：
- §11.1 三条易误读的判读口径：启动期 MISS start 0x67 是良性 episode；
  miss= 是累计不是连续（连续数饱和在 WD_MISS_TOLERANCE=8）；
  reset cause 不能区分 IWDG 溢出与台架软件复位
- §11.2 诊断四步：先看掩码缺几位（只缺 1 位 = 定点打击，多位 = 全局
  饥饿）→ 逐项量化占空比（实测 10%~13%，否掉"CPU 饱和"直觉）→
  用计数速率反证空转（ring 恰好 1000/s）→ 用 [PROF] 指认占用者
- §11.3 三条结构性脆弱点（uiTask 唯一 BelowNormal／心跳曾依赖 netTask
  往返／自定截止期不可恢复）+ 两个顺带修掉的正确性缺陷（无新帧仍压环
  ≈3% 频率失配、失败拍静默沿用旧值）
- §11.4 [PROF]/[PROF2] 全字段语义 + v2.8 实测基线（netp=0 是真实值、
  adcm 峰值来自心跳日志、uip 地板 = LVGL 帧周期）与三机理判读口诀
- §11.5 三条教训：门控类优化必须保留低频兜底；门控会顺手消灭暴露路径；
  事件驱动要核对节拍源启动时刻 vs 消费者创建时刻
- §11.6 明确不做的四条及理由（提 uiTask 优先级会掩盖真缺陷、net_* 有界
  等待版会串回执、推流搬出 uiTask、推流塞进 netTask）

UI 推流门控与方案 B 否决理由收进 RemoDispBus 协议说明 §3（该处原本已有
摘要，改为自洽不再回指）；就绪门控 API 的约束已在 BSD Socket 指南 §10.1。

引用改指 12 处：ui_task.c、task_prof.c/.h、ui_net_sink.c/.h、docs/README、
RemoDispBus、看门狗设计说明 R7 行、ADC 采样节拍设计说明、BSD Socket 指南
×2、项目审查报告 N-10 ×2。

⚠ ui_task.c / ui_net_sink.c / ui_net_sink.h 是带 BOM 文件，Edit 剥掉了
BOM，已按原样补回 3 字节 EF BB BF（未整文件重写）。

验证：check_doc_links --all 通过（127 个文档，无悬空引用）；
@build 0 错 0 警，Code=257660 与删除前一字不差（纯注释改动）。
 2026-10-11 00:38:50 +08:00
wandering1 9bbe117f97 adc: 节拍源 TIM6->TIM3 + ADC1 走 DMA 乒乓双缓冲，消除 2 ms 忙等（P1-5 单拍硬上界办结） 
用户选定最彻底方案（B2）：DMA + 定时器 TRGO 硬件触发 + 消费上一拍
已完成的半区。对应 P1-5 拆出的"单拍硬上界"，现已办结。

硬件事实更正（查 CubeMX 器件库 + 本仓 HAL 头证实）：F4 上 ADC1 的
外部触发清单里没有 TIM6/TIM7 TRGO（只接 DAC）。故 1 kHz 节拍源由
TIM6 改为 TIM3（PSC 83 / ARR 999，TRGO=UPDATE），同一个更新事件
同时 ① ISR 脉冲 TPAFE CONVST ② 经 TRGO 触发 ADC1 一轮 9 通道
③ 置位 ADC_WAKE_FLAG 唤醒 adcTask。TIM6 从 .ioc 整体移除。

代码：
- Src/tim.c/h：新增 MX_TIM3_Init（含 MasterSlaveMode），删 htim6
- Src/adc.c：ExternalTrigConv=T3_TRGO + EDGE_RISING +
  DMAContinuousRequests=ENABLE；MspInit 挂 hdma_adc1（DMA2_Stream4
  循环模式）。DDS 位关掉 = 一轮只发一次请求，静默丢 8 路
- Src/dma.c：DMA2_Stream4 NVIC 优先级 6（CubeMX 换流会把它重置为 0，
  优先级 0 会抢占 FreeRTOS 临界区，违反"外设中断 ≥5"）
- Src/main.c：周期回调加 TIM3 分支；stm32f4xx_it.c 向量同步
- App/algo/adc_input.c：stm32_scan() → stm32_take()，逐通道
  PollForConversion 全删；乒乓半区由完成计数奇偶推出（只读一个
  32 位量 → 与 ISR 无竞态）；STM32 侧数据固定滞后 1 拍
- App/task/adc_task.c：心跳日志拆出四类计数

观测性：adc1_seq（完成计数）/ adc1_gap（seq 前进 >1 = 丢帧）/
adc1_err（连续 ≥2 拍无新帧 = 停摆）/ adc1_hw（HAL 错误回调）。
单拍无新帧是消费者相位伪影（DMA 完成落在唤醒后 ≈67 µs），不计故障。

验证：
- 主机单测 79 → 101 全绿；反向验证四连均咬（半区奇偶取反 11 条、
  停摆拍置 valid 4 条、STALL_RUN_MAX 改 1 为 6 条、gap 阈值 1 条）
- @build 0 错 0 警，Code 256872 → 257660
- @test PASS：adcp 122 µs → 8 µs、adc1_err=0、adc1_hw=0、
  adc1_gap=27/20002 拍、adc1_seq 与 seq 恒定偏移 2
- stack_report 7/7 PASS，adcTask 832 B / 余 59%（不变）
- cubemx-survival 新增 5 项审计（TIM3 分支 / T3_TRGO / DDS /
  DMA 挂载 / 流优先级），28 通过 0 失败

文档：ADC 采样节拍设计说明新增 §11；看门狗停摆分析 §4.4 与 §8 收口；
算法规划 L1-1/L1-3、通道映射、测试说明、各 README 同步。
 2026-10-11 00:31:33 +08:00
wandering1 dd8210867a adc_input: 失败拍清 s_stm32_valid，杜绝超时沿用上一拍旧值（单测 70->79） 
缺陷（真机实测发现）：本层只有一份 s_stm32_raw[]，有效标志此前只在成功时
置 1、失败时从不清零 -> 超时拍消费侧照样取数、照样压入采样环（且超时前
几个 Rank 已写本拍新值、后面几个是上一拍旧值 = 半新半旧混合帧），直接污
染 20 点 DFT 相量窗；adc_input_poll() 返回值只由 TPAFE 决定，s_frames_skip
也抓不到它。

修复：stm32_scan() 两条失败支路（HAL_ADC_Start 失败 / 轮询超时）都清
s_stm32_valid -> 本拍 adc_input_raw() 对 STM32 语义通道返 -2 -> adc_task
走既有 skip 整帧跳过路径；下一拍扫描成功自动置回 1（自愈）。

测试：新增 TC-AI-070..078（70 -> 79 用例）。旧用例 TC-AI-034/039b 都是
init 后立刻失败（valid 本就是 0），照不出成功过之后再失败这条路径，故新
用例先成功一拍进入有效态再注入失败。**反向验证已做**：把支路改回旧行为 ->
TC-AI-039b/073/074 立即 FAIL（76/79），证明用例有效。

验证：主机单测 79/79 PASS；@build 0 错 0 警（Code 256868 -> 256872）；
@test PASS（本轮无超时：adc1_err=0、skip=0、idle=0、frames=20001）；
18 钩子全绿。文档同步 4 处（停摆分析 4.4 / ADC采样节拍 10.4 / ADC输入层
单测说明 / test-host README）。

遗留：2 ms 忙等本身未消（硬化 2 = DMA，方案 B2 待 CubeMX 配置）。
 2026-10-10 23:08:01 +08:00
wandering1 9231a3c22c adcTask 事件驱动消费（P1-5 方案 a）+ 补 F4 ADC 上电自校准 + 修正 2 ms 忙等过期表述 
P1-5 方案 a（事件驱动消费，Task #32）：
- TIM6 1 kHz ISR 除触发 CONVST 外再调 adc_tick_irq_notify()，置位
  ADC_WAKE_FLAG；adcTask 循环尾改 osThreadFlagsWait(osWaitForever)，
  删除 ADC_TASK_BEAT_MS 定时轮询
- adcTask 优先级 Normal(24) -> AboveNormal(32)（Src/freertos.c USER CODE 区）
- 补消费者就绪门（规划未预见）：TIM6 在 app_main_init 就启动，比调度器
  早约 100 ms，未就绪时 ISR 不得 osThreadFlagsSet
- 实测 6 次上板：idle 由 1~649 降到 0/20000 拍，frames 1000.0 Hz，
  seq-frames=7 正是就绪窗口；UI 侧 uip/uiw/uis 无退化

补 STM32F4 ADC 上电自校准（此前项目从未做过）：
- 核查证实裁剪版 HAL 无 HAL_ADCEx_Calibration_Start、裁剪版 CMSIS 头无
  ADC_CR2_CAL -> 按 RM0090 13.3.6 在 Src/adc.c 的 USER CODE 区手写
  adc1_calibrate()，MX_ADC1_Init() 末尾调用
- 新增 cubemx-survival 审计项 adc1-calibration-call / -impl（清单 21->23）
- 实测校准前后同一拍 STM32 侧 6 路同向偏移 +10~+63 LSB，TPAFE 侧不变

修正两处过期表述（实测反证）：
- 原文 9 通道全超时最坏 = 18 ms 连占 有误：stm32_scan() 在首个超时处即
  Stop+return，单拍上界 = 一次超时约 2~3 ms
- adcm 约 2.1 ms 的峰值归因由 ADC 采集改判为每 10 s 一次的心跳日志；
  6 次对照 adcp = 122 us（无超时）/ 2209 us（超时 1 次）
- 同步修正 adc_task.c 两处过期注释；新发现超时拍 STM32 侧静默沿用
  上一拍值的正确性代价，硬化排序记入 4.4 / 10.4（未实施）

验证：@build 0 错 0 警（Code 256728 -> 256868）；@test 6/6 PASS；
stack_report 7 任务全 PASS（adcTask 832 B / 余 59%）；18 钩子全绿
 2026-10-10 22:41:19 +08:00
wandering1 1d1a9d4656 net/ui: UI 推流加就绪门控，刷新脱离 netTask 往返（销项 N-10） 
新增 net_can_accept() / net_can_read()：纯 RAM 读 Socket 控制块，不入队、
不等 netTask 回执，供实时性敏感任务在发 RPC 前判断"有没有活"。
ui_net_sink_poll() 改为先门控再 RPC；无客户端时 RPC 从 100 msg/s 降到 0。

两条兜底（门控引入的新卡死路径，设计阶段未预见）：
- I-2 每 32 轮无条件 recv：readable 仅由 RECV_OK 中断置位，Trap 22 三类
  对账不含"RX 非空但 readable=0"，纯门控会把已到达的数据永久藏住；
- I-3 门控返 0 时查监听控制块，消失即 g_listen=-1 重建（改前靠每轮
  accept 撞 BADF 暴露，门控会连这条暴露路径一起消掉）。
net_can_read() 对非 ESTABLISHED / 非法 fd 故意返 1，让上层必得 EOF/BADF
走既有错误分支——返 0 会把死连接永久藏住。
模拟器后端恒返 1（Winsock 无 RPC 成本，行为逐位不变）。

实测：uis 50ms→1µs、uiw 50ms→11.4ms（只剩 LVGL）；@build 0 错 0 警、
@test 10/10 PASS（uis≤1µs、uisn≡0、0 task stall、0 [ERR]）、
check_remo_sink.py e2e 0/25600 位差异、内容页文本断言 50/50。
uip 最坏 61ms 是 LVGL 帧周期地板、与网络无关，判据已按实测修订。

方案 B（把推流搬出 uiTask + 帧 seqlock）已评估并决定不做：搬任务不会
让刷新变快，收益只剩极端并发下的观感隔离，成本含必改 .ioc 的 CubeMX
重生成。残留暴露与观测手段（uis/uisn）如实记录在 §9.4。
N-19 / C7 不入登记簿（当日结案），结论沉淀进问题记录 §9。
 2026-10-10 20:47:59 +08:00
wandering1 35b5b78209 docs(adc): Task #32 P1-5 事件驱动消费方案 a 规划入档 
用户决策"ISR 只发唤醒 + 计算留任务 + 提优先级"（方案 a），拒绝 ISR 内计算；
附下一版硬件 DMA 双缓冲建议（方案 b）。代码待实施。

- 新增 §10：决策依据、拟改造清单（main.c/freertos.c/adc_task.c/adc_task.h）、
  预期收益、残留风险（P1-5 硬化）、DMA 硬件建议（§10.5）
- 状态头与 §9 变更记录同步"规划/待实施"口径
- 未改代码；消费端当前仍为 1ms 轮询
 2026-10-10 19:59:34 +08:00
wandering1 3b1d0308d8 fix(ui): Task #32 P0/P1/P2 — 解耦 UI 心跳、修 adc 压环与截止期、加测量探针 
Task #32 UI 看门狗停摆（docs/问题记录/UI任务看门狗停摆分析.md）

P0 adc_task.c（已上板验证）:
- 仅 r==1 才压环+重算；上板印证 ring==frames（修前 ring=frames+idle）
- osDelayUntil 返回值重同步，落后拉回基准，解除永久空转死锁

P1-4a ui_task.c v1.3: task_wd_beat 提到 ui_net_sink_poll 之前
  → 心跳测"UI 活着"而非"netTask 响应"，解开 §4.2 心跳依赖
  → 未上 P1-3（提优先级会掩盖 §4.2/§4.4）；P1-5 暂缓

P2 新增 App/util/task_prof.c/.h: DWT 常开探针，测各任务周期/耗时/
  推流往返/ADC 轮询/控制台排空/syslog 落盘/net_poll 最坏值；心跳位图
  1→0 边沿裸 UART 直发 [PROF]/[PROF2] 快照；uvprojx 已登记

doc: 分析 doc §7 补良性启动 episode 与复位非诊断项；§8 加处置落地
验证: P0+P1 累计 32 次上板启动 0/32 复现（原 L2 基线 3/10），构建 0/0
 2026-10-10 19:06:06 +08:00
wandering1 28bd391035 问题记录：UI 任务看门狗停摆归因（Task #32） 
- 新增 docs/问题记录/UI任务看门狗停摆分析.md，并在 docs/README.md §7.3 登记。
- 否掉"CPU 负载饱和"：实测 adcTask 占空比 10%~20%（ADC1 扫描约 67us + 压环与
  相量约 10~15us + 超时忙等），且日志 ring 严格 +10000/10s（= 1000 次/秒）
  反证 adcTask 每拍都在 osDelayUntil 里睡满、没有空转。
- 定位真因：uiTask 是 required_mask 六个任务里唯一的 osPriorityBelowNormal
  （其余五个全 Normal，CMSIS 包装直接把优先级赋给 uxPriority），且其心跳必须
  先经 ui_net_sink_poll -> net_accept -> osMessageQueuePut + xTaskNotifyWait
  (portMAX_DELAY) 绕 netTask 一次往返之后才发出。失败日志只缺 bit4(UI)、
  其余任务心跳全在，与"非全局饥饿"一致。
- 另发现一个独立正确性缺陷：adc_task 在 r == 0（TPAFE 无新帧）时仍压环 +
  phasor_run；日志 ring = frames + idle 精确吻合（10001 = 9957+44）。会把重复
  采样点塞进 20 点 DFT 窗，造成约 3% 的等效采样率偏移（系统性误差）。
- 给出 P0（压环条件、osDelayUntil 重同步）/ P1（优先级、解耦心跳、ADC 去忙等）
  / P2（观测）分层处置，并建议先启用现成的 TEST_LATENCY_PROBE 测量再定方案。
- 本文只做归因与方案建议，未改动任何生产代码。
 2026-10-10 18:24:06 +08:00
wandering1 c25baba2f1 对齐 L2-2 实例数口径：规划表 4 → 5 个实例（参考项目 4 个） 
- 规划 §3.2 L2-2 行：由"4 个实例：C01 基波 I/U、C02 零序基波、C03 二次、C04 五次"
  改为本项目的 5 个实例（C01-IA-F1 / C02-UA-F1 / C03-UN-F1 / C04-IA-F2 /
  C05-IA-F5），并加注说明 4 → 5 的来历：参考项目为 4 个，本项目按 V0.1 有效通道
  （UA/UN/IA）把 C01 的 I/U 拆为两行，其余顺延。
- 规划 §4.3 相量区 RAM 行：双区 + 4 实例 → 双区 + 5 实例。
- 傅氏算法详解 §7：该处的"4 个实例"标注为参考项目口径（其引用来源是
  APP/CLS100_Dsp/InstCalCell.c），并指向规划 §3.2 的本项目口径。
- 相量层单测说明 §4.3：由"与规划表的一处待对齐"改为"实例数 4 → 5：规划表已对齐"。
- 规划文档补记 L2 相量层落地（sample_ring + phasor + 57 用例主机单测），并显式说明
  §3.2 的 L2 各点状态仍标 ⬜ 的理由：台架 @test 闭环未做、L2-3 判据需标准源。
 2026-10-10 18:16:17 +08:00
wandering1 0b0cd0048b 补两份主机单测说明文档：卷锁（fail-open）与时间同步（N-17） 
- 卷锁单元测试说明.md：33 断言点。钉死 fail-open 不变量（互斥量创建失败时
  vol_lock_wait 必须返回 1 且绝不阻塞——defaultTask 是喂狗点）、幂等、超时透传、
  判空 release；并说明"白盒置 s_lock=NULL"的取舍与桩只验调用契约的边界。
- 时间同步单元测试说明.md：80 断言点。钉死分片喂狗延时、监听退避、时间包重组
  （半包/粘连/EOF/真错/预算耗尽/tick 回绕）、任务主循环；含 setjmp/longjmp 跳出
  for(;;) 的手法，以及"C 暂定定义静默合并同名 static 变量"这一无告警缺陷的记录。
- test/host/README.md：补齐 7 套主机单测的清单、运行方式与钩子（原表缺
  phasor / adc_input / vol_lock / time_sync 四套），并修正 cfg_file 断言数。
- docs/README.md：主机侧单测（L0.5）表登记两份新文档，并同步修正 cfg_file 断言数。
 2026-10-10 18:06:43 +08:00
wandering1 317e97fca6 docs(algo): App/algo/README.md 补齐为详版（分层/数据流/接口/测试/扩展） 
- 该文件此前仅 27 行（仅"现有模块"表 + 约定 + 相关文档），本次补齐为 168 行
  详版：文件清单、1 ms 数据流图、逐文件 API 表与要点、关键约定、静态足迹、
  构建与测试（含两个主机单测钩子）、新增算法模块的固定动作。
- 内容已逐项对照当前源码核验：相量实例 5 行 / 环容量 2×20 点 / 9 个语义通道 /
  Rank 映射（CH0..CH7 + CH14）/ 所引文档、脚本与 skill 均存在。
- 与 L1/L2 现状一致：adc_input（L1）、sample_ring + phasor（L2）三模块。
 2026-10-10 18:04:51 +08:00
wandering1 a2f5d1397a 主机单测：新增卷锁与时间同步两套用例（33+80 项）并登记钩子 
- vol_lock（App/fs/vol_lock.c）：33 用例。核心不变量是 fail-open——
  互斥量创建失败时 vol_lock_wait() 必须返回 1 且绝不阻塞，因为调用者
  defaultTask 是看门狗喂狗点；板端该路径只在内存耗尽时才可能走到。
- time_sync（App/sync/time_sync.c）：80 用例。本模块是 N-17 看门狗风险的
  全部逻辑贡献者，用例钉死分片喂狗节奏、监听退避、报文重组（半包/粘连/
  EOF/真错/预算耗尽/tick 回绕）、重听门控；用 longjmp 跳出 for(;;) 任务循环。
- 两套均为纯逻辑主机侧测试，MSVC 离线编译真实源文件（#include 纳入）。
- 新增钩子 vol-lock-unit-test、time-sync-unit-test（7f/7g）。
- 全量主机单测：watchdog 39 + sys_clock 100 + cfg_file 149 + phasor 57
  + adc_input 70 + vol_lock 33 + time_sync 80 = 528 项，全绿。
 2026-10-10 18:03:31 +08:00
wandering1 3715f8a34c 补两份主机单测说明文档：ADC 输入层（L1）与相量层（L2） 
按仓库惯例（每个主机侧单测配一份 docs/测试说明/*单元测试说明.md 并在
docs/README.md 注册）补齐上一提交新落地的两个套件。

- docs/测试说明/ADC输入层单元测试说明.md：70 用例逐条列出（init 复位 /
  语义映射表 / map_check / ADC1 顺序扫描与 Rank 到通道判据 / raw 守卫与
  补码 / poll 契约 / rc 与 errs 观测）；含桩表与"反向路径不可达"说明。
- docs/测试说明/相量层单元测试说明.md：57 用例（系数表 / 幅值相位 /
  直流与谐波抑制 / 任意次谐波提取 / 频偏 / 采样环 / 实例层 / 滑动窗 /
  双区交换 / phasor_zero 与 init 清零）；含 sqrt2/N 系数约定与"暴力重算"
  取舍说明，并记录 L2-2 实例数（规划 4 vs 实现 5）待对齐。
- docs/README.md：主机侧单元测试（L0.5）表新增两行。

doc-links / mojibake / EOF 等钩子全绿。
 2026-10-10 17:53:48 +08:00
wandering1 63c262fe2c 相量层单测：补 phasor_zero/init 清零用例（L1/L2 函数覆盖 20/20） 
函数级覆盖审计发现 phasor_zero() 仅被 phasor_init() 间接执行、其效果
无可观测断言（init 同时把 s_ready 清 0，公开 API 看不到清零）。补直接
白盒用例：

- TC-PH-030 直接调 phasor_zero，四字段（含 fAm/fAmSQ）全清零
- TC-PH-031/032/033 先把双区写脏，init 后双区全零 + 使用区复位 +
  就绪标志清（get -> -2）
- TC-PH-034 init 幂等

审计结果：App/algo 三个源共 20 个函数，0 个未覆盖。
相量层单测 57/57 PASSED（原 52）。
 2026-10-10 17:48:13 +08:00
wandering1 696a1a49a9 主机单测：新增 ADC 输入层（L1）用例 70 项并登记 L1/L2 单测钩子 
新增 App/algo/adc_input.c 的主机侧单测（L1），补齐 L1/L2 算法层
"每个函数都可离线验证"的最后一处空白。

- test/host/adc_input/{adc_input_test.c,run_unit_test.py,stub/}：
  70 个用例，覆盖 6 个公开函数 + map_check + stm32_scan。
  关键判据 = "通道号 <-> Rank 顺序 <-> 语义"三者映射：给每个 Rank
  注入互不相同的码值，逐通道钉死映射（板端无信号源，无法验此项）。
  另钉死 HAL 启动失败 / 轮询超时 / 参数错 / 无有效数据等分支。
- .pre-commit-config.yaml：登记 phasor-unit-test（7d）与
  adc-input-unit-test（7e）两个主机侧单测钩子。

主机侧全套：adc_input 70/70、phasor 52/52，均 0 失败、无 /W4 告警。
 2026-10-10 17:46:45 +08:00
wandering1 3762c03bb4 L2 相量层：采样环缓冲 + 全周傅氏 + 主机单测（台架间歇复位待查） 
新增（均已通过主机侧单测与构建，**台架存在未定位的间歇性回归，见下**）：
- App/algo/sample_ring.c/h：按语义通道的采样环缓冲（2 周波 = 40 点），
  整帧压入 + 帧计数，供 L2 按窗取数。
- App/algo/phasor.c/h：全周傅氏相量层，覆盖规划 §3.2 的 L2-1/2/3/6/7——
  系数表按 docs/算法/傅氏算法详解.md §2.3 预乘 √2/N（fAmSQ 直接即有效值）；
  5 个数据驱动实例（IA/UA/UN 基波 + IA 二/五次谐波）；暴力滑动窗；
  计算区/使用区双区原子切换。
- test/host/phasor/：主机侧单测（52/52 PASSED，无需桩）——系数表逐项复核、
  幅值/有效值/相位、直流与谐波抑制、任意次谐波提取、频率敏感性（±2Hz≤3%）、
  环缓冲时序与回绕、实例层与双区交换。
- 集成：adc_task 每拍压帧 + 重算（v2.4）；app_main 调 phasor_init()；
  Keil 工程挂 phasor.c/sample_ring.c（App/algo 已在 IncludePath）。

验证：
- 主机单测 52/52 PASSED。
- @build 0 错误 0 警告；内存快照已刷新（RW_IRAM1 89,320→90,936 B）。
- 台架：L2 链路数据正常（ring=10001、skip=0、回读一致、相量日志可见），
  但 10 次运行中 3 次出现 UI 任务看门狗停喂（mask=0x67 缺 TASK_WD_UI）
  → IWDG 复位；改动前基线 6 次运行 0 次。属**未定位的间歇性回归**。

未完成：定位并修复该间歇性复位；L2 文档状态与登记簿条目尚未按结论更新。
 2026-10-10 17:39:37 +08:00
wandering1 66186e1dae chore: 清理 .gitignore 合并残留（死忽略项 + .venv 重复）
CI / L0 静态门禁 (pre-commit) (push) Has been cancelled
Details
CI / L0.5 主机侧单测 (MSVC) (push) Has been cancelled
Details 
合并 v2-on-ui 时 master 侧的两条忽略项成为残留：

- tools/serial_tool/state/ —— 该目录在 v2-on-ui 已删除，忽略规则失效
- .venv/ 重复 —— 与 v2-on-ui 的 "# Python venv (unified env, ...)" 重复

删掉这 6 行后 master 的 .gitignore 与 v2-on-ui 完全一致（均 138 行）。
*.dep / *.suo 的重复是历史遗留（合并前即存在），本次未动。
 2026-10-10 16:55:12 +08:00
wandering1 f81747f7e3 Merge branch 'v2-on-ui' into master
CI / L0 静态门禁 (pre-commit) (push) Has been cancelled
Details
CI / L0.5 主机侧单测 (MSVC) (push) Has been cancelled
Details 
把 v2-on-ui 开发主线（250 个提交）合并进 master：涵盖 B0 产品定义、
B1 ADC 采集链路、1 kHz TIM6 采样节拍、L1-3/L1-4 语义通道映射、
@build/@download 收敛到 .dsh/skills/ 下的 skill（删除 build.bat /
download.bat / reset.bat）等。

master 侧 3 个提交（.gitignore 忽略项 + simulator/sim_config.ini）
已保留，无冲突。
 2026-10-10 16:46:28 +08:00
wandering1 5009a844a9 收敛 reset.bat 到 stlink-flash skill 并删除该批处理
CI / L0 静态门禁 (pre-commit) (push) Has been cancelled
Details
CI / L0.5 主机侧单测 (MSVC) (push) Has been cancelled
Details 
stlink_flash.py 新增 hard 子命令（-c SWD RM=Hrst -HardRst PULSE=100），
RM= 被 CLI 拒绝时自动降级为系统复位并打印 RESET_NOTE；至此 reset.bat 的
全部子命令（复位/hard/halt/run/list/flash/cmp）均已由 skill 覆盖。

删除 MDK-ARM/reset.bat（git rm）。@build/@download 两条旧批处理入口至此
全部收敛到 .dsh/skills/ 下的 skill，一个能力一个实现。

同步更新引用：AGENTS.md、README、MDK-ARM/README、7 篇 docs、4 个 skill
（stlink-flash/serial-boot-test/new-machine-setup 及 config.example.json）。

真机验证：hard 子命令 RM= 被拒 → RESET_NOTE → 回退系统复位 → STLINK_RC=0。
 2026-10-10 16:41:46 +08:00