Files
STM32F4-Base/scripts
wandering1 0264b49489 feat(algo): B8 频率测量层 + 过频/低频保护(L3-5)
新增 App/algo/freq.c/h:由 L2 基波相量导出系统频率。相邻两拍共轭
乘积 P=Z(m)·conj(Z(m-1)) 取角 = 每拍相位增量(免显式解缠绕),再按
自适应窗长 K_eff=round(8·Fs/(2·f_hat))(45~55 Hz 段 73~89 拍)做滑动
平均。定长窗受 20 点矩形窗负序泄漏纹波限制(实测扫频最坏 0.317 Hz;
60 拍 Kay 复数和 0.197 Hz,交叉项和角不按 1/K^2 衰减),自适应窗使
窗长恰为纹波周期 fs/(2f) 整数倍 -> 最坏 0.0101 Hz。推导与两轮弯路
写在 freq.c 文件头。

假值钳制带取 35~65 Hz,刻意宽于系统合理带 40.5~60.5:单拍相位差本身
带 ±5 Hz 泄漏纹波,贴边钳制会非对称丢弃纹波半周 -> 均值偏置(实测
45 Hz 点 +0.16 Hz)。系统合理带由 OF/UF 定值范围在消费侧把关。
幅值门 FREQ_AMP_MIN=50 码(拟定,待 L1-5 标定复核):低于门判无有效
波形,停更新、valid 清零、读数保持 -> 浮空/PT 断线不发散。源优先级
UA(C02)->IA(C01),按名前缀解析、每拍动态回退,切换即废相位基准。

prot_set:尾追加 8 项(PS_ID_COUNT 32->40,编号不回收)
OF_EN/OF_HZ/OF_DLY/UF_EN/UF_HZ/UF_DLY/RET_OF/RET_UF。OF/UF 逐项通讯
地址不在本仓库 -> 全部 comm_addr=0 本地项(104 C_SE 不可寻址,待对照
参考表补)。频率返回系数独立(0.99/1.01),勿与电气量 0.95/1.05 共用。
bad_mask 随项数扩为 uint64_t。PROT_SET_BLOB_VER 1->2。

prot_set_store:换代与损坏分流。load 返回 2 = 版本/项数换代(本文件
打 INFO "prot set blob version change, defaults in use"),-1 = 真损坏
(defaultTask 按 CORRUPT 报 ERROR + 自检留痕)。B7 旧档(ver=1/32 项)
升级首启属预期路径,不得报成损坏。语义分流收在属主文件内,
default_task.c 不动。

prot_elm:实例表加 src 字段(0=phasor rms,1=freq),PE_OF/PE_UF 尾
追加(PE_COUNT 7->9)。freq 无有效读数按方向填"必不启动"值(过量 0 /
欠量 1e30 -> 滞回比较恒假 -> 元件复位),不整拍跳过——频率源缺失不得
饿死电流/电压类元件(B5 行为不回归)。OF/UF 暂未映射独立 104 遥信点,
动作只经 YX15 保护总聚合可见(送检点表 = B10)。

板端接线:adcTask 在 phasor_run() 之后同拍调 freq_run();心跳/首拍日志
追加 freq(<tag>): f=%ld valid=%u (x0.01)(MicroLIB 无 %f)。app_main
内核前 freq_init()。

主机单测:freq 46 用例(J1 扫频 45~55 Hz <=0.02 Hz 实测最坏 0.0101;
J2 噪声 1% <=0.10 实测 0.0160;J3 启动收敛 <=40 ms 实测 20;J4 阶跃
50->51 <=120 ms 实测 98;J5 浮空 valid=0 不发散;J6 跳变 60 ms 内回
±0.05;另直流 8000 码 / 3-5 次谐波 20%/10% / UA->IA 回退)。
prot_set 90(+TC-PS-011 OF/UF 行 + 64 位 bad_mask bit39 + 旧档拒绝)、
prot_elm 47(+OF/UF 滞回与方向隔离 + run() 测频接线)。回归:phasor
57、iec104 94 全绿。

J4=120 ms 是"精度优先于响应"的显式取舍(Lead 批准):4 周波窗换
0.317->0.0101 Hz,测频响应 98 ms << OF/UF 定时限默认 1000 ms(占
总动作时间 <10%),暂态另有 J6 <=60 ms 兜底。

注册:freq.c 入 uvprojx algo 组 + check_registration.py SIM_EXEMPT
(纯算法、模拟器无消费路径,照 prot_set.c 先例)。

@build 0 错误 0 警告(Code=207468 RO=18304 RW=1068 ZI=153084)。
RAM:RW_IRAM1 96096->96728 B(+632 B,73.3%->73.8%)、RW_CCM 不变
57376 B(87.9%)、Flash 224596->226840 B(+2244 B,21.4%->21.6%);
台账随合并由 Lead 回填。stack_report:adcTask 静态最坏链 1320 B /
余量 1240 B(48%)改前后完全不变(freq_run 帧未进最坏链,无需抬栈);
protectTask 链 872 B / 余 1176 B(57%)同样不变。

gate: only mem-budget/mem-numbers pending lead ledger backfill
--------------------------------------------------------------
门禁实跑(pre-commit run --all-files,Lead 批准 --no-verify 提交):
28 Passed / 2 Failed,失败仅 mem-numbers 与 mem-budget 两条——均为
docs/内存管理 受管快照与本 .map 不一致(台账由 Lead 每次合并后
--write 回填,避免多分支同改受管表冲突)。其余含 doc-links /
coding-standard / no-mojibake / cppcheck / registration-check /
13 条主机单测钩子全 Passed(gitlint 属 commit-msg 阶段,不在该次
--all-files 内)。ci_local L0.5 全绿(freq 46/46 等)。
字节卫生自查(--no-verify 跳过卫生钩子,故手工核):17 个暂存文件
全部 BOM=无 / CR=0(纯 LF)/ U+FFFD=0;自研 .c/.h 去注释后字符串
字面量 100% ASCII(唯一非 ASCII 字面量在 test/host/iec104/iec104_test.c
的既有用例名,非本次改动行;test/ 不在 coding-standard 钩子范围)。
2026-10-12 19:16:37 +08:00
..

scripts/ — 开发脚本(提交门禁 + 报告生成)

本目录是 pre-commit 门禁脚本与报告生成脚本的存放处。 与 tools/(面向开发者的功能工具)区别:本目录服务于质量门禁与工程度量。

文件一览

提交门禁(接入 .pre-commit-config.yaml)

脚本 钩子名 作用
check_coding_standard.py C coding standard C 代码规范机械检查(命名前缀/常量右置/头文件保护宏等)
check_mojibake.py Forbid U+FFFD mojibake 扫描 U+FFFD 乱码(EF BF BD 字节)
check_doc_links.py doc-links 文档链接存在性 + 命名规范(D-3/D-7)+ §N.M 章节引用(口径见 docs/文档规范.md §3.5)。钩子已带 --sections-strict(自引用失效也拦);--section-todo 列出机器判不了目标的 §(带改写建议)。每次跑打印「可判定比例」行,防覆盖率回落
section_aliases.json (被 check_doc_links.py 读) 文档昵称别名表:「内存方案」→ docs/内存管理/RAM使用分析与优化方案.md。只登记无歧义昵称;登记一次即把该昵称的引用纳入硬门禁
gen_task_table.py task-table FreeRTOS 任务表以 Src/freertos.c 为唯一事实源生成/校验(D-2/D-7)
check_mem_numbers.py mem-numbers 内存/Flash 数字以 .map 为唯一事实源校验(D-7 体积档)
check_test_suite.py test-suite-switch 测试套件开关=产品构建(防测试固件静默提交)

报告生成(非门禁)

脚本 作用
ram_report.py 从 .map 生成静态 RAM/Flash 占用报告(→ docs/内存管理/data/)
stack_report.py 从 Keil 静态调用图 + 串口 [STACK] 水位生成每任务最坏链报告

引用同步(改名 / 挪目录)

脚本 作用
rename_ref.py 改名/挪目录 + 全库引用自动改写:默认 dry-run 预览,--apply 才落盘(git mv → 改写引用 → 自动跑 check_doc_links --all 复核)。覆盖反引号引用、Markdown 链接、图片 ../ 层级换算、#include、uvprojx/CMakeLists.txt 源列表。固定动作与边界 → docs/文档规范.md §3.6

check_doc_links.py 除链接存在性外,还校验 §N.M 章节引用是否指向目标文档真实存在的编号标题(口径见 docs/文档规范.md §3.5)。

CI 与本地等价(2026-10-01 T-6)

脚本 / 文件 作用
ci_local.py 本地跑与 CI 等价的门禁(L0 pre-commit + L0.5 主机侧单测):自动选用装了 pre-commit 的解释器;无 .map 时自适应跳过 mem-numbers;退出码 0/1/2 与 CI 对齐。CI 定义见 ../.gitea/workflows/ci.yml,说明见 docs/测试说明/测试开发标准流程.md §9

使用方式

# 全库跑门禁(用仓库 .venv 的 python,其 pre-commit 随 requirements.txt 安装;
# 其他装有 pre-commit 的解释器可用 DTU_PRECOMMIT_PYTHON 指定)
& '.venv\Scripts\python.exe' -m pre_commit run --all-files

# 本地跑与 CI 等价的门禁(L0 + L0.5)
& '.venv\Scripts\python.exe' scripts/ci_local.py
& '.venv\Scripts\python.exe' scripts/ci_local.py --l0-only    # 只跑 L0
& '.venv\Scripts\python.exe' scripts/ci_local.py --l05-only   # 只跑 L0.5

# 单个脚本
& '.venv\Scripts\python.exe' scripts/check_doc_links.py --all
& '.venv\Scripts\python.exe' scripts/rename_ref.py docs/旧/名.md docs/新/名.md          # 预览
& '.venv\Scripts\python.exe' scripts/rename_ref.py docs/旧/名.md docs/新/名.md --apply  # 落盘
& '.venv\Scripts\python.exe' scripts/gen_task_table.py --check   # 或 --write / --diff
& '.venv\Scripts\python.exe' scripts/check_mem_numbers.py --check
& '.venv\Scripts\python.exe' scripts/check_test_suite.py               # 门禁判定
& '.venv\Scripts\python.exe' scripts/check_test_suite.py --allow-test-build  # 放行测试构建
& '.venv\Scripts\python.exe' scripts/ram_report.py
& '.venv\Scripts\python.exe' scripts/stack_report.py -s .dsh\skills\serial-assistant\scripts\state\serial.log

⚠️ 脚本编写约定

  • 保真回写:改文件前先探测原换行符(LF/CRLF)与 BOM,按原样回写(本仓库各文件换行混杂)
  • 受管区锚点:改文档中的数值/表格时用 <!-- XXX:BEGIN/END --> 锚点,只替换锚点内内容
  • 脚本输出文件绝不能落在自身扫描范围内(否则会"自我污染",见 docs-tree-reorg skill)
  • 生成器与校验器共用同一套正则/口径,避免两处数字打架

相关文档

  • docs/代码规范/pre-commit使用说明.md — 门禁完整说明与排除项
  • docs/代码规范/cppcheck使用说明.md
  • docs/文档规范.md — 文档门禁三档
  • docs/内存管理/RAM使用分析与优化方案.md — RAM/栈报告口径