Files
STM32F4-Base/.dsh/roles
wandering1 f5902bcc21 docs(design): 运行/自检记录与 ADC 节拍两篇改为现状设计并去掉档名"说明"
两篇规划期文档改成对当前系统的描述,档名统一去掉"设计说明"的"说明"。

运行与自检记录:
- 旧档重写为现状版(10 节:概览 / 记录布局 / 写入路径 / 读取与呈现 /
  事件分类 / 控制台日志 / 双端差异 / 内存 / 异常恢复 / 自测要点),
  删掉需求表、调研摘要、模块清单动作列、实施步骤与开放问题。
- 按代码纠正:七类记录齐备(原文只写了两类)、自检描述串换成实际
  落盘的 28 条、待机阈值以 ui_tokens.h 为准、记录页已走 ui_w_records
  共享组件、容量满只删该文件而非整卷清空。
- 待机屏移出本篇:它不属于日志,归 UI 侧;内容页架构补"待机屏
  (覆盖层)"一节,产品需求 FR-LOG-3 拆成单纯的上电/重启分类,
  待机显示归口已有的 FR-UI-3。

ADC 采样节拍:
- §4.5 从 45 行压到 24 行,只留规则 / 违反的代价 / 为什么 / 兜底与
  档案指针;九路置换实测表、A/B 对照、探针计数等取证归
  ADC_Trap_Records.md 的 TRAP-ADC-01(那里已有完整档案)。
- adc1_gap 字段去掉"2026-10-21 起、此前固件为次数"的修订记录式括号。
- app_main.c 的注释改为指向 TRAP-ADC-01 取证、§4.5 设计口径。

引用同步:两个旧档名全仓替换(含代码注释、角色档、归档 id 表),
旧名残留 0;对 ADC 篇的 § 引用逐条复核落在真实章节上。

验证:48 个提交期钩子全通过,check_doc_links --sections-strict 通过。
2026-11-15 21:30:07 +08:00
..

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
network-specialist 网络协议专家 CH395F SPI 以太网、netTask socket 栈、IEC 60870-5-104、FTP、SNTP read/edit/write/grep/glob
storage-specialist 存储文件系统专家 GD5F SPI NAND、dhara FTL、FatFs、日志系统、卷自愈 read/edit/write/grep/glob
ui-specialist UI/LVGL 专家 LVGL 160×160 单色菜单、PC 模拟器、菜单树生成器、UI 自动化回归 read/edit/write/grep/glob

通用工作角色(项目专项)

角色 ID 显示名 职责范围 工具权限
code-reviewer 代码审查员 审查改动的正确性、安全性与规范合规 read/grep/glob(只读)
test-engineer 测试工程师 主机侧单测、板级测试套件编写维护 read/edit/write/grep/glob
build-gatekeeper 构建与门禁验证 Keil 构建、pre-commit 门禁、CI 本地自查诊断 read/grep/glob(只读)
doc-writer 技术文档写手 技术文档编写维护、链接有效性、计数准确性 read/edit/write/grep/glob

关于工具调用预算:角色文件 frontmatter 里都写了 maxToolCalls,但该预算只对 subagent_role 路径生效,对 spawn_teammate 起的 teammate 不起约束(插件 lib/budget.js 的 arm() 只由委派工具调用,team 路径不挂账)。所以本表不再列预算列,免得被当成上限承诺。缺口与后续补齐口径 → docs/环境与部署/子Agent角色自动注入实现说明.md §1.1。

角色详细说明

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] + 公共工具组 — 允许文件修改