新增 .dsh/roles/skill-custodian.md(双层结构:Agent Skills 三级加载 与官方体积约束 + 本仓 17 个技能现状盘点、12 条可判定审核清单、 改进四步流程、写域边界)。 口径固化三处,同一事实只详述一处: - AGENTS.md 铁律新增「技能写法」:主文件只放默认可用方案,按本项目 配好默认参数、一条命令能跑通、给出成功输出样例;失败时由脚本打印 稳定索引键,主文件按该键指向 reference/ 同名小节;排查细节、边界、 历史坑、手工兜底一律不进主文件。 - .dsh/roles/README.md:角色总览表、详细说明段、派活速查表各加一行, 角色计数 11 -> 12,并记录 worktree 新增角色不注入的实测坑。 - .dsh/roles/lead-orchestrator.md:分工表加一行。 实测:subagent_role 探针逐字回读 persona 首行与硬口径小节均命中; pre_commit 四文件全 Passed 零 Failed;BOM/CR/U+FFFD 均为 0。
24 KiB
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 |
skill-custodian |
技能处理者 | 审核、创建、改进 .dsh/skills/ 下的技能;主文件只留默认路径、长尾进 reference |
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),与角色无关。当前 12 个角色文件都没写这三个字段,全部继承宿主默认。要给某个成员换模型用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 条反模式表。
第二部分(项目专项):12 个角色的分工与派活边界表(负责什么/不碰什么/何时派它)· 委派协议(@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 子集化、色彩空间与调色板。
本屏的可用性约束:160×160 单色(I1)、无触摸、按键导航。1bpp 下没有颜色编码可用,重要状态须在文字/形状/位置里至少占两项;对比度只有"白底黑字"与"反显"两种;报警优先级不在屏上体现(走上送),但排版不能让故障与普通遥信等权。通用的医疗可用性工程、人机工效、WCAG 三套标准以触摸目标尺寸与颜色对比度为前提,本屏不适用,已从角色文件移除。
项目专项: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(围栏语法预检)。
适用场景:新增/修改设计文档、更新索引、修复断链、文档规范合规检查。
skill-custodian(技能处理者)
职责:审核、创建、改进 .dsh/skills/ 下的技能。产物是结构合理的技能与可复现的审核结论;不写业务代码、不改 docs/ 正文(那是 doc-writer 的写域)。
核心口径(用户 m05776 明确提出,已固化为本项目技能原则):主文件只放默认使用方案——按当前项目配好默认参数,一条命令能跑通,成功即结束;出错时由失败信息给出稳定的索引键(阶段名/退出码/报错前缀),主文件按该键指向 reference/ 里的同名小节。排查细节、边界情况、历史坑、手工兜底一律不进主文件。理由:默认路径是命中率最高的分支,值得占正文;长尾值得存在但不值得常驻,搬进 reference/ 不损失能力却让每次触发少背几 KB。
审核方法:结构审核(行数/字节数、指针兑现、索引键与小节标题双射并用脚本比对)+ 行为审核(真跑默认路径、制造一次失败验证路由、观察实际打开了哪些引用文件)+ 变异测试(往审核脚本喂坏样本确认它变红,防假绿)。
项目专项:.dsh/skills/ 17 个技能现状盘点、skill-size 门禁(65,536 字节硬上限 / 49,152 WARN / 悬空指针 FAIL)、主文件 2–6 KB 舒适区、索引键用语义短语不用字母数字编号。
适用场景:新建技能、拆分过长的技能主文件、把排查内容外置成 reference、审核技能描述与触发面、检查索引键与文档小节是否对得上。
角色选择指南
| 任务类型 | 推荐角色 |
|---|---|
| 拆解复杂诉求、写任务书、开闸验收、仲裁跨域 | 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 |
| 新建/改进/审核技能(SKILL.md 与 reference 拆分) | skill-custodian |
| 涉及多个模块的复杂任务 | 提前按 lead-orchestrator 的方法论拆解,再分派给多个 teammate |
注意事项
- 复杂任务一律用 Agent Teams,不用单独的 subagent/subagent_role
lead-orchestrator是给 Lead 自己看的行为规范,一般不作为 teammate 角色派发——派一个 Lead 去当另一个 Lead 的助手只多一层转述,该派出去的是模块专家- 创建 teammate 时必须在 prompt 第一行写
@role:<id> - 角色文件修改后不需要重启 DSH,下次委派时自动读取最新版本
- 在 worktree 里新增/改角色文件,persona 不会注入(2026-11-18 实测):插件按
spawn_teammate那一刻的工作目录向上找.git定项目根(lib/roles.js的projectRootFor(),标记只有.git),而团队成员的角色查找用的是主树 cwd(诊断日志role-inject-diag.log记role "x" not found (cwd=<主树>)→install FAILED)。所以新增角色的验收顺序是:先在主树.dsh/roles/放好文件 → 再起探针成员确认 persona 首行与工具白名单都对 → 最后才谈合并提交。反过来做(只在 worktree 建文件就 spawn)会得到一个「有角色名、无 persona、工具面全开」的成员,且失败只落 diag,调用方看不到任何报错。 - 所有 12 个角色均为双层结构(第一部分通用知识体系 + 第二部分项目专项)
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也从只读角色白名单里去掉。