# Agent Teams 角色定义说明 本文档说明 STM32F4-Base 项目中所有可用的子 agent 角色,供 Lead 在分配任务时参考。 ## 使用方式 创建 teammate 时在 `prompt` 第一行写 `@role:<角色id>`,fork 版 `dsh-plugin-subagent-roles` 插件会自动注入对应角色的 persona 到系统提示词并应用工具策略。 ```js spawn_teammate({ name: "algo-fix", description: "修复傅氏相量窗口偏移", prompt: "@role:algo-specialist\n\n## 本次任务\n检查 phasor.c 的窗口对齐逻辑..." }) ``` ## 角色总览 ### 编排角色(给 Lead 自己看,不派发) | 角色 ID | 显示名 | 职责范围 | 工具权限 | |---------|--------|---------|---------| | `lead-orchestrator` | 团队编排(Lead) | Lead 侧行为规范:任务拆解、委派、验收判定、返工处理、上下文经济;不写模块代码 | 全局层全开 + 只读检索 + `ops_bash`(含 Lead 专用的 `team_gate_open`/`team_gate_close`) | ### 核心模块专家(双层结构:通用行业标准 + 项目专项) | 角色 ID | 显示名 | 职责范围 | 工具权限 | |---------|--------|---------|---------| | `algo-specialist` | 采集算法专家 | ADC 语义取数、全周傅氏相量、测频、保护判据 | `ops_grep`/`ops_glob`/`ops_inspect_local_file` + `edit`/`write` | | `network-specialist` | 网络协议专家 | CH395F SPI 以太网、netTask socket 栈、IEC 60870-5-104、FTP、SNTP | `ops_grep`/`ops_glob`/`ops_inspect_local_file` + `edit`/`write` | | `storage-specialist` | 存储文件系统专家 | GD5F SPI NAND、dhara FTL、FatFs、日志系统、卷自愈 | `ops_grep`/`ops_glob`/`ops_inspect_local_file` + `edit`/`write` | | `ui-specialist` | UI/LVGL 专家 | LVGL 160×160 单色菜单、PC 模拟器、菜单树生成器、UI 自动化回归 | `ops_grep`/`ops_glob`/`ops_inspect_local_file` + `edit`/`write` | | `mcu-specialist` | STM32 底层与引脚驱动专家 | GPIO/EXTI/AF 复用、时钟树、CubeMX 用户代码区边界、外部时序器件(移位寄存器/并口/SPI 从设备)的位操作与时序实现 | `ops_grep`/`ops_glob`/`ops_inspect_local_file` + `edit`/`write` | ### 通用工作角色(项目专项) | 角色 ID | 显示名 | 职责范围 | 工具权限 | |---------|--------|---------|---------| | `code-reviewer` | 代码审查员 | 审查改动的正确性、安全性与规范合规 | 只读:`ops_grep`/`ops_glob`/`ops_inspect_local_file`(无 `edit`/`write`) | | `test-engineer` | 测试工程师 | 主机侧单测、板级测试套件编写维护 | `ops_grep`/`ops_glob`/`ops_inspect_local_file` + `edit`/`write` | | `build-gatekeeper` | 构建与门禁验证 | Keil 构建、pre-commit 门禁、CI 本地自查诊断 | 只读:`ops_grep`/`ops_glob`/`ops_inspect_local_file`(无 `edit`/`write`) | | `bench-runner` | 台架执行与取证 | 执行烧录/复位/回读、串口抓日志、标记校验、板端 UI 导航;**只操作取证,不判定** | 只读文件 + `ops_bash`(无 `edit`/`write`,无 gate 提交权) | | `doc-writer` | 技术文档写手 | 技术文档编写维护、链接有效性、计数准确性 | `ops_grep`/`ops_glob`/`ops_inspect_local_file` + `edit`/`write` | > **关于工具调用预算**:角色文件 frontmatter 里都写了 `maxToolCalls`,但该预算**只对 `subagent_role` 路径生效**,对 `spawn_teammate` 起的 teammate 不起约束(插件 `lib/budget.js` 的 `arm()` 只由委派工具调用,team 路径不挂账)。所以本表不再列预算列,免得被当成上限承诺。缺口与后续补齐口径 → `.dsh/plugins/dsh-plugin-subagent-roles/docs/子Agent角色自动注入实现说明.md` §1.1。 > **关于模型**:角色文件 frontmatter **支持** `provider`/`model`/`reasoningEffort` 三个字段,但同样**只有 `subagent_role` 路径会读**。`spawn_teammate` 起的 teammate 一律跑在宿主默认模型上(本机 profile 的 `agent-default-model` = `workbuddy` / `deepseek-v4.1-flash`),与角色无关。当前 11 个角色文件都没写这三个字段,全部继承宿主默认。要给某个成员换模型用 `team_member_revive({ target, provider, model })`(活体立即生效,冷会话挂起到复活瞬间)。机制与两条改造路径 → `.dsh/plugins/dsh-plugin-subagent-roles/docs/子Agent角色自动注入实现说明.md` §1.2。 ## 角色详细说明 ### lead-orchestrator(团队编排 / Lead) 这是**给 Lead 自己看的行为规范**,不是派给 teammate 的角色——派一个 Lead 去当另一个 Lead 的助手只多一层转述。它回答的是"我该怎么拆、怎么派、怎么判、怎么退"。 **第一部分(通用方法论)**:Lead 的职责边界 · 何时用团队何时自己干(三条可操作判据 + 三种不该开团队的情况)· 任务描述四要素(目标/验收口径/约束/交付方式,缺一退回)· 三层分离(操作/采集/判定,执行者不自验)· 验收人 ≠ 执行人的四个适用面(代码/文档/判据本身/单向规则)· 返工处理(说清哪条没过 + 最小修正方向 + 重新提交的证据要求)· 上下文经济(什么自己读、什么让别人读完只报结论,判据是"我要能拿这句话去复跑")· 12 条反模式表。 **第二部分(项目专项)**:11 个角色的分工与派活边界表(负责什么/不碰什么/何时派它)· 委派协议(`@role:` 首行绑定、一律 fresh 不用 fork、写域声明、门禁流程、重启恢复)· 门禁插件实际状态 · 10 条实测硬约束(插件保证什么、不保证什么)· 参考索引。 **适用场景**:拆解复杂诉求、写任务书、开闸验收、仲裁跨域冲突、判定返工、汇总汇报。 --- ### 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 界面修改、菜单树变更、模拟器问题、字体子集更新、黄金参考基线变更、绘制缓冲调整。 --- ### mcu-specialist(STM32 底层与引脚驱动专家) **通用知识体系**:MCU 引脚的四层决定因素(焊盘/复用矩阵/GPIO 模式/时刻)、时钟使能与初始化顺序、微秒级时序约定(脉冲宽度、边沿极性、建立保持时间)、GPIO 位操作原子性、HAL 库的正确使用姿势(`GPIO_InitTypeDef` 清零、EXTI 回调在 ISR 上下文、HAL 时基依赖)、外部时序器件五维自查模型(装载/移位模式切换、时钟边沿方向、位序与移位方向、装载前后的时钟状态、上电静止态)、输出类器件(光耦/继电器)的有效电平与安全态。 **行业标准**:STM32F4 参考手册 RM0090(寄存器与复用映射)、数据手册 DS8626(Table 7 引脚定义)、CMSIS 与 HAL 的层次边界、74HC 系列逻辑器件手册(功能表与 AC 特性)、IEC 60255(出口回路语义)。 **项目专项**:引脚来源链 `.ioc` → `main.h` 的 `