wandering1
1355dbe1b1
修复运行期改配置被打回出厂值的缺陷：cfg_file_poll() 按段循环复用同一 份读缓冲，而 s_parse() 通过 s_split_line()/s_key_value() 就地改写缓冲 （把换行与等号换成 NUL）。第一个段解析完，缓冲里已没有键值行，后续 7 个段静默保持出厂值；随后 run_par_store_save() 又把这份出厂值写回 config.ini，用户的标定值被永久覆盖。开机路径 cfg_file_load() 只解析一 轮，所以该缺陷长期不可见，只在运行中改配置时发作。 - s_parse() 改为非破坏性：入参 const char *，逐行 memcpy 到栈缓冲 （CFG_LINE_TEST_MAX + 1）后再交给会破坏缓冲的解析子函数；超长行跳 过（保存侧已拒绝落盘超长受管键行）。 - 新增 TC-CONFIG-063：同时改两段内容，断言第二个注册段也重载成功、 含负值 INT 键存活，把「热重载吞段」钉成机器面。 新增两点标定台架工具链（test/host/）： - cal_two_point.py：整数算术镜像 adc_cal_two_point()，支持单路模式与 从执行卡 CALDATA 表批量求解（--from-doc），带合法带与零点自检拦截。 - cal_write.py：复用 iec104_master 作库，经 104 定值段写 r 后写 b 并 读回校验，是所有写入的唯一入口。 adc_task 的 meas: 心跳行精度提到 4 位小数，标定读数需要。 文档：新增《采样数据校正全流程》（端到端导航）与《ADC 两点标定执行 流程》（台架执行卡，含 CALDATA 可填表）；ADC通道映射说明新增 §7.3 台 架实测结果（UA 554.687914、IA 29.634259，出厂默认值保持不变）；配置 文件设计说明新增解析器契约 v1.19；采集与算法层设计说明 §13 系列与 README 索引同步。 台架实测：UA r=554.687914（出厂 1000.0 偏大 1.80 倍，根因是接线分压 使 PT 一次侧只拿到一半电压，实测与参数算定 606.06 只差 8.5%）、IA r=29.634259（与出厂 29.4118 只差 0.76%，反证链路未算错）。UN 按用户 裁定本轮不标定，保护闭锁（vl=0x11）是预期行为，未伪造 VALID。 同时入库 .dsh/roles 角色定义（原被 .gitignore 挡住）。
Agent Teams 角色定义说明
本文档说明 STM32F4-Base 项目中所有可用的子 agent 角色，供 Lead 在分配任务时参考。
使用方式
创建 teammate 时在 prompt 第一行写 @role:<角色id>，fork 版 dsh-plugin-subagent-roles 插件会自动注入对应角色的 persona 到系统提示词并应用工具策略。
spawn_teammate({
name: "algo-fix",
description: "修复傅氏相量窗口偏移",
prompt: "@role:algo-specialist\n\n## 本次任务\n检查 phasor.c 的窗口对齐逻辑..."
})
角色总览
核心模块专家（双层结构：通用行业标准 + 项目专项）
| 角色 ID | 显示名 | 职责范围 | 工具权限 | 调用预算 |
|---|---|---|---|---|
algo-specialist |
采集算法专家 | ADC 语义取数、全周傅氏相量、测频、保护判据 | read/edit/write/grep/glob | 80 |
network-specialist |
网络协议专家 | CH395F SPI 以太网、netTask socket 栈、IEC 60870-5-104、FTP、SNTP | read/edit/write/grep/glob | 80 |
storage-specialist |
存储文件系统专家 | GD5F SPI NAND、dhara FTL、FatFs、日志系统、卷自愈 | read/edit/write/grep/glob | 80 |
ui-specialist |
UI/LVGL 专家 | LVGL 160×160 单色菜单、PC 模拟器、菜单树生成器、UI 自动化回归 | read/edit/write/grep/glob | 80 |
通用工作角色（项目专项）
| 角色 ID | 显示名 | 职责范围 | 工具权限 | 调用预算 |
|---|---|---|---|---|
code-reviewer |
代码审查员 | 审查改动的正确性、安全性与规范合规 | read/grep/glob（只读） | 3000 |
test-engineer |
测试工程师 | 主机侧单测、板级测试套件编写维护 | read/edit/write/grep/glob | 3000 |
build-gatekeeper |
构建与门禁验证 | Keil 构建、pre-commit 门禁、CI 本地自查诊断 | read/grep/glob（只读） | 3000 |
doc-writer |
技术文档写手 | 技术文档编写维护、链接有效性、计数准确性 | read/edit/write/grep/glob | 80 |
角色详细说明
algo-specialist（采集算法专家）
通用知识体系：信号采样与量化理论（奈奎斯特定理、ENOB、抗混叠滤波）、数字信号处理算法（全周波 DFT、频率自适应、功率计算）、继电保护判据（过流/过压/差动/方向元件）、实时嵌入式约束（ISR 最小化、确定性时序、内存安全）。
行业标准：IEC 60255-1/181（继电保护性能）、IEC 61850-9-2（采样值传输）、IEC 61000-4-30（电能质量测量）、GB/T 14549（公用电网谐波）、IEEE C37.90（继电器标准）。
项目专项：App/algo/ 分层边界、ISR 只走 adc_tick_irq_notify()、V0.1 跨转换器禁止相位运算、保护判据未标定闭锁态、新算法进 algo 不进 task。
适用场景：修改采集算法、调整傅氏相量计算、新增保护判据、标定流程变更、ADC 取数问题排查。
network-specialist（网络协议专家）
通用知识体系：TCP/IP 协议栈裁剪、嵌入式以太网驱动（DMA/PHY/缓存一致性）、Socket 编程模型（非阻塞+事件驱动、连接状态机）、零拷贝、静态内存池、心跳保活与指数退避重连、背压控制、接收状态机。
行业标准：IEC 60870-5-104（APCI 帧格式、定时器 t0-t3、流控 k/w）、IEC 62351（安全扩展）、Modbus TCP、RFC 793/6298（TCP/RTO）、IEEE 802.3。
项目专项：CH395F 全局中断读即清、netMsgQueue 串行执行、错误码经 xTaskNotify 回传、单连接 socket 断开语义、SPI 分频固定为 8、就绪屏障 osFlagsNoClear。
适用场景：修改网络驱动、调整 socket 生命周期、IEC 104 协议变更、FTP 服务问题、网络自愈逻辑、SNTP 对时。
storage-specialist（存储文件系统专家）
通用知识体系：NAND Flash 物理特性（读写擦不对称、P/E 寿命、数据保持力、读干扰）、FTL 算法（页/块/混合映射、GC、磨损均衡）、文件系统原理（日志结构 vs FAT、掉电安全）、可靠性理论（ECC 选型、写放大、寿命估算）、WAL/环形缓冲/幂等写入。
行业标准：JEDEC JESD230（NAND 接口）、ONFI、JEDEC JESD216（SFDP）、JESD218/219（SSD 耐久性）、FAT Specification。
项目专项：FatFs FA_OPEN_APPEND 不含 FA_WRITE、f_write 短写不报错须校验字节数、FF_USE_LFN=0 仅 8.3 短名、defaultTask 唯一日志写者、破坏性测试默认关闭。
适用场景：NAND 驱动修改、FTL 调优、FatFs 问题排查、日志格式变更、卷自愈逻辑、配置文件读写。
ui-specialist（UI/LVGL 专家）
通用知识体系：LVGL 渲染管线（失效区→绘制任务→像素输出）、部分刷新与 DMA 双缓冲、线程安全约束、样式系统、字体光栅化与 CJK 子集化、色彩空间与调色板。
行业标准：IEC 62366-1（医疗可用性工程）、ISO 9241-161/171（人机交互）、WCAG 2.2（无障碍）、触摸目标物理尺寸研究。
项目专项：I1 palette 头越界陷阱、白底白字整屏纯白、UI 源码与模拟器同一份、BOM 保护（Drivers/BSP/UI/*）、生成器改动必须重跑、ui-verify 5 步门禁、注释禁星号形态。
适用场景：UI 界面修改、菜单树变更、模拟器问题、字体子集更新、黄金参考基线变更、绘制缓冲调整。
code-reviewer（代码审查员）
职责：审查代码改动的正确性、安全性和规范合规性。按「阻塞项 / 建议项」分级输出结构化审查结论。
审查维度：正确性（分层边界、ISR 路径、socket 串行）、安全性（堆分配、返回值校验、竞态）、规范合规（命名、ASCII 字面量、BOM、日志冗余）、内存与资源（RAM 余量、DBG 成本）。
工具限制：只读（read/grep/glob），不做修改。
适用场景：提交前代码审查、跨模块改动评审、安全审计。
test-engineer（测试工程师）
职责：编写和维护主机侧单测（test/host/）和板级测试套件（test/board/），验证代码改动的正确性。
关键约束：新 .c 文件双端注册、测试配置互斥（test_config.h）、破坏性测试默认关闭、主机侧单测不依赖硬件、测试命名用语义短语。
适用场景：新增测试用例、修改测试框架、板级套件维护、测试覆盖率提升。
build-gatekeeper（构建与门禁验证）
职责：执行 Keil 构建和 pre-commit 门禁检查，诊断失败原因，给出修复建议。
关键知识：52 个钩子的触发面与口径、keil-build/serial-boot-test skill、ci_local.py 流程、Python .venv 环境、UV4 工程文件不入库。
工具限制：只读（read/grep/glob），只做验证和诊断。
适用场景：构建失败诊断、门禁报错排查、环境问题定位、提交前验证。
doc-writer（技术文档写手）
职责：编写和维护项目技术文档，确保内容准确、格式合规、链接有效。
写作规范：每节首句答"干什么/为什么"、不许未解释的内部速记、不写死源码行号、同一事实只在一处详述、待办完成即销项、语义短语标识。
门禁约束：doc-links（章节引用有效）、task-table（生成器产物）、mem-numbers（内存数字一致）、generated-fresh（生成器幂等）、mermaid-syntax（围栏语法预检）。
适用场景：新增/修改设计文档、更新索引、修复断链、文档规范合规检查。
角色选择指南
| 任务类型 | 推荐角色 |
|---|---|
| 修改 App/algo/ 下的采集/算法代码 | algo-specialist |
| 修改网络驱动/socket 栈/IEC 104 | network-specialist |
| 修改 NAND/FatFs/日志/配置引擎 | storage-specialist |
| 修改 UI 界面/模拟器/菜单树 | ui-specialist |
| 提交前审查代码改动 | code-reviewer |
| 新增或修改测试用例 | test-engineer |
| 构建失败或门禁报错诊断 | build-gatekeeper |
| 编写或修改技术文档 | doc-writer |
| 涉及多个模块的复杂任务 | 拆分为多个 teammate，各绑对应角色 |
注意事项
- 复杂任务一律用 Agent Teams，不用单独的 subagent/subagent_role
- 创建 teammate 时必须在 prompt 第一行写
@role:<id> - 角色文件修改后不需要重启 DSH，下次委派时自动读取最新版本
- 所有 8 个角色均为双层结构（第一部分通用知识体系 + 第二部分项目专项）
tools 字段说明
角色文件 frontmatter 中的 tools 字段控制子 agent 可用的工具白名单。它通过 ctx.tools.restrict() 实现，作用于子 agent 作用域内通过 tools registry 注册的所有工具。
不能被 tools 字段管的工具
以下工具由 DSH harness 保留，tools.restrict() 拒绝接受其名称，始终对所有子 agent 可用：
| 工具 | 原因 | 源码依据 |
|---|---|---|
run_code |
PTC 传输层保留工具 | policy.js L27: UNRESTRICTABLE_TOOL_NAMES = new Set(['run_code'])；restrict() 抛出 cannot name reserved PTC mode presentation transport "run_code" |
注意：billion-context 工具（
compress/decompress/search_context/acp_status）、Mnemon 工具、QQ 工具、WorkBuddy 工具等都可以被tools字段管理。它们走正常的 tools registry，不在保留名单里。如果角色白名单里没有写它们，子 agent 就不能用这些工具。
容错机制
当角色白名单中包含子 agent 作用域内不存在的工具名时（如未连接的 MCP 工具），restrict() 抛出 names unknown global tool "xxx"，插件捕获后自动丢弃该名称并用剩余有效名称重试，同时在日志中输出 warn。如果所有白名单名称都被丢弃，整个工具限制失效，子 agent 获得全部工具。
源码依据：policy.js L44-51 parseUnrestrictableToolNames()，tool.js L816-831 容错重试逻辑。
当前角色的工具策略
所有角色均包含以下公共工具组：
- 文件操作基础：
read,grep,glob,ops_bash,ops_inspect_local_file,ops_discover_tools - 文件修改（仅读写角色）：
edit,write - 交付与规划：
present,todo_write - 团队协作：
send_message,list_agents - 共享任务板：
team_task_get,team_task_list,team_task_update - 技能管理：
skill,create_skill - 图片查看：
read_image - 后台任务管理：
job_list,job_output,job_kill - 工作目录：
working_directory - 目标管理：
get_goal,update_goal - 项目记忆：
mnemon_recall,mnemon_remember,mnemon_document_search - 历史检索：
session_search,session_event_search - Web 工具：
web_search,web_fetch - 调度/目标工具：
schedule_create,schedule_list,create_goal - 上下文管理工具：
compress,decompress,search_context,acp_status
在此基础上按职责区分业务工具：
- 只读角色（code-reviewer / build-gatekeeper）：
[read, grep, glob]+ 公共工具组 — 禁止 edit/write，确保只做审查/诊断 - 读写角色（algo/network/storage/ui-specialist / test-engineer / doc-writer）：
[read, edit, write, grep, glob]+ 公共工具组 — 允许文件修改