A rule can describe an action and still be unusable when the action's input has no source. That is what happened here: the acceptance-side rules were amended three times before the wording could be executed. Add rule one, item four: a checker must print the denominator, that is how many objects it was supposed to verify, and silence is not a pass. The rule carries both halves: - output side: list every object name together with its verdict, never a bare aggregate OK - checking side: write down the expected object list first, count how many distinct objects appear in the output, then reconcile the two The object list may only come from the task description or from the dispatcher. It must never be derived from the checker's own output, because a derived list always agrees with that output and the check can then never turn red. A report whose object list is absent or has no traceable origin is treated as coverage unverified, not as passed. Task description gains a fifth required item, the expected object list. A dispatcher who omits it has not defined the denominator, and the executor must ask instead of guessing. write_scopes and any list of files an executor happened to touch are action ranges, not object lists; the two sets may be entirely disjoint. Recorded with the measured contrast that motivated it: the same checker with the list taken from its own output passes both when one side is injected and when both are; with the list fixed by the task description it fails as soon as one object is missing. The reference case is a self-check script over two role files that was only ever fed a bad sample for one of them. It reported two failures instead of four and nobody noticed, because the count itself carries no information about how many objects were covered. Wording only where the subject changed; no rule bodies from the two earlier rounds were rewritten.
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 的窗口对齐逻辑..."
})
角色总览
编排角色(给 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:<id> 首行绑定、一律 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 的 <Label>_Pin 宏 → gpio.c 的 MX_GPIO_Init()、自定义代码只在 USER CODE 区、改引脚必须改 .ioc 而非手补初始化、HAL 时基是 TIM7 不是 SysTick、NVIC 优先级 ≥ 5、ARMCC C99 无 GCC 特性、新 .c 双端注册、cubemx-survival 审计脚本。
适用场景:新增或修改 GPIO 引脚配置、外部移位寄存器/并口/SPI 从设备驱动、EXIT 与中断引脚、继电器与光耦输出回路、引脚时序问题排查、CubeMX 重生成后的代码存活修复。
code-reviewer(代码审查员)
职责:审查代码改动的正确性、安全性和规范合规性。按「阻塞项 / 建议项」分级输出结构化审查结论。
审查维度:正确性(分层边界、ISR 路径、socket 串行)、安全性(堆分配、返回值校验、竞态)、规范合规(命名、ASCII 字面量、BOM、日志冗余)、内存与资源(RAM 余量、DBG 成本)。
工具限制:只读(ops_grep/ops_glob/ops_inspect_local_file),不做修改。
适用场景:提交前代码审查、跨模块改动评审、安全审计。
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 工程文件不入库。
工具限制:只读(ops_grep/ops_glob/ops_inspect_local_file),只做验证和诊断。
适用场景:构建失败诊断、门禁报错排查、环境问题定位、提交前验证。
bench-runner(台架执行与取证)
职责:替 Lead 动手操作板子——烧录/复位/回读校验、串口开机日志抓取、标记校验、板端 UI 导航、板级套件运行——并把原始证据贴回来。
定位:执行层,不是决策层。 它只回答"命令退出码是几""日志第 N 行是什么""某标记出现几次",不判通过/不通过。判定标准由发起方提供。这是对"验收人 ≠ 执行人"的落实,也是为了避免台架判读变成执行者自证自验。
关键知识:采集必须先于操作(先 open+clear 再烧);烧录必须 -Rst -Run 且回读校验排在日志采集之后;固件新旧不能只看 fw build: 时间戳(__DATE__ 是每个翻译单元各自展开的),要找本次新增的运行时字段;wait-idle 的零字节结论要先确认采集器在收。
工具限制:只读文件 + ops_bash(无 edit/write),且无 gate 提交权——它不能 team_gate_submit/team_gate_accept。
适用场景:烧录固件、抓开机日志、跑串口标记校验、板端 UI 操作、继电器等需要物理动作的验证。
动手前的硬性确认:开出/继电器类操作必须由发起方说明负载状态(空载 / 接真实设备),没说就停下来问。
doc-writer(技术文档写手)
职责:编写和维护项目技术文档,确保内容准确、格式合规、链接有效。
写作规范:每节首句答"干什么/为什么"、不许未解释的内部速记、不写死源码行号、同一事实只在一处详述、待办完成即销项、语义短语标识。
门禁约束:doc-links(章节引用有效)、task-table(生成器产物)、mem-numbers(内存数字一致)、generated-fresh(生成器幂等)、mermaid-syntax(围栏语法预检)。
适用场景:新增/修改设计文档、更新索引、修复断链、文档规范合规检查。
角色选择指南
| 任务类型 | 推荐角色 |
|---|---|
| 拆解复杂诉求、写任务书、开闸验收、仲裁跨域 | lead-orchestrator(Lead 自己照此执行,不派发) |
| 修改 App/algo/ 下的采集/算法代码 | algo-specialist |
| 修改网络驱动/socket 栈/IEC 104 | network-specialist |
| 修改 NAND/FatFs/日志/配置引擎 | storage-specialist |
| 修改 UI 界面/模拟器/菜单树 | ui-specialist |
| 修改 GPIO 引脚配置/外部时序器件驱动/继电器光耦输出 | mcu-specialist |
| 提交前审查代码改动 | code-reviewer |
| 新增或修改测试用例 | test-engineer |
| 构建失败或门禁报错诊断 | build-gatekeeper |
| 烧录固件、抓开机日志、跑板端验证、板端 UI 操作 | bench-runner |
| 编写或修改技术文档 | doc-writer |
| 涉及多个模块的复杂任务 | 提前按 lead-orchestrator 的方法论拆解,再分派给多个 teammate |
注意事项
- 复杂任务一律用 Agent Teams,不用单独的 subagent/subagent_role
lead-orchestrator是给 Lead 自己看的行为规范,一般不作为 teammate 角色派发——派一个 Lead 去当另一个 Lead 的助手只多一层转述,该派出去的是模块专家- 创建 teammate 时必须在 prompt 第一行写
@role:<id> - 角色文件修改后不需要重启 DSH,下次委派时自动读取最新版本
- 所有 11 个角色均为双层结构(第一部分通用知识体系 + 第二部分项目专项)
tools 字段说明
角色文件 frontmatter 中的 tools 字段控制子 agent 可用的工具白名单。它通过 ctx.tools.restrict() 实现。
要正确理解它管得住什么,先要知道本宿主的工具名册分两层:
| 层 | 谁注册的 | 典型工具 | restrict() 能约束吗 |
|---|---|---|---|
| 全局层 | 宿主与插件束挂到顶层名册 | edit/write/web_search/send_message/interrupt_agent/present/skill/mnemon_*/qq_*/workbuddy_* |
能 |
| 作用域层(agent 自己那层) | OPS 插件、团队协作插件在 agent 物化时注册 | ops_bash/ops_grep/ops_glob/ops_inspect_local_file/ops_discover_tools、team_task_*、team_gate_*、spawn_teammate、wait_agent |
不能 |
restrict() 只校验全局层的名字表。插件因此采取先分区再 restrict:把白名单切成三桶再交出去,而不是整串硬交、靠抛异常兜底。
| 桶 | 含义 | 处理 |
|---|---|---|
| 可限制 | 在全局层 | 进 allow,真正生效 |
scopeLocal |
可见,但属 agent 自己那层 | 从 allow 剔除——它在不在白名单里都一样可见,剔除无损 |
unresolved |
此刻既不可限制也不可见 | 剔除并写诊断;多半是注入之后才惰性注册的 team_task_* 之类 |
诊断日志(~/.dsh/role-inject-diag.log)的对应行:
tool policy for role "doc-writer": omitted 4 scope-local name(s) (visible either way): ops_grep,ops_glob,ops_bash,ops_inspect_local_file
tool policy for role "doc-writer": 4 name(s) not visible yet and not restrictable, so left out of the enforced policy: ops_discover_tools,team_task_get,team_task_list,team_task_update
tool policy applied in one pass for role "doc-writer" (allow=35)
第二行的措辞是刻意的:注入那一刻查不到,不等于这台机器没注册这个工具(team_task_* 就是 agent 物化之后才出现的)。看到它就说明"白名单里这几个名字此刻还没生效",不是角色文件写错了。只有反复出现且名字确实是拼错时,才回去改角色文件。
一个必须知道的能力边界
tools 管得住注入那一刻的可见面,管不住注入之后被 ops_discover_tools 激活出来的工具。2026-11-16 实测:@role:doc-writer 成员的白名单里没有 ops_write_file/ops_edit_file/ops_diff,但该成员调用一次 ops_discover_tools(query="grep file content search") 后,这三个写侧工具就出现在它的工具面里了——因为 discovery 激活的是作用域层,而 restrict() 够不着作用域层。
结论:tools 是"初始可见面的裁剪",不是安全边界。真要对成员做写权限封锁,得连 ops_discover_tools 一起从白名单里去掉。
不能被 tools 字段管的工具
| 工具 | 原因 | 源码依据 |
|---|---|---|
run_code |
PTC 传输层保留工具,restrict() 拒收 |
lib/policy.js 的 UNRESTRICTABLE_TOOL_NAMES |
注意:billion-context 工具(
compress/decompress/search_context/acp_status)、Mnemon 工具、QQ 工具、WorkBuddy 工具都在全局层,白名单里不写就真的拿不到。这是本插件最可靠的一条约束面。
白名单里写不存在的名字会怎样
不会整批失败。插件先分区:查得到但属作用域层的进 scopeLocal(无损剔除),查不到的进 unresolved(剔除并写诊断),剩下的全局名照常生效。因此白名单里多写几个名字不会让整个策略失效——旧版本靠抛异常后求交集的做法已经移除。
源码依据:lib/policy.js 的 partitionToolFilter() 与 restrictableNameSet(),调用点在 lib/index.js 的 applyToolPolicy() 与 lib/tool.js 的委派主路径、组合安装、诊断工具三处。
当前角色的工具策略
所有角色均包含以下公共工具组:
- 文件检索:
ops_grep,ops_glob,ops_inspect_local_file - 命令执行与能力发现:
ops_bash,ops_discover_tools - 文件修改(仅读写角色):
edit,write - 交付与规划:
present,todo_write - 团队协作:
send_message,list_agents - 共享任务板:
team_task_get,team_task_list,team_task_update - 验收门禁:
team_gate_open,team_gate_submit,team_gate_accept,team_gate_reject,team_gate_close,team_gate_list - 技能管理:
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 / bench-runner):
ops_grep/ops_glob/ops_inspect_local_file+ 公共工具组,白名单里没有edit/write— 只做审查/诊断/取证 - 读写角色(algo/network/storage/ui-specialist / test-engineer / doc-writer):
edit/write+ops_grep/ops_glob/ops_inspect_local_file+ 公共工具组 — 允许文件修改 - 编排角色(lead-orchestrator):全局层全开 + 只读检索 +
ops_bash。它手里有edit/write是为了写任务书与门禁清单,不是给写业务逻辑用的
只读角色的只读性靠"全局层没有
edit/write"保证,是可靠的;但按上面那条边界,它们仍能通过ops_discover_tools激活写侧作用域工具。要真正封死,得把ops_discover_tools也从只读角色白名单里去掉。