Files
STM32F4-Base/.dsh/roles
wandering1 d9f8dbfd90 fix(roles): 角色工具白名单改宿主注册名,ui-specialist 内联技能手册
8 个角色文件:
- 白名单里的 read/grep/glob 是幻影名(宿主未注册过),改为
  ops_grep / ops_glob / ops_inspect_local_file,删除 read
- 公共工具组补 team_gate_* 六项(门禁账本插件已接入,成员
  应能认领与提交门禁)

roles/README:
- tools 字段说明重写:两层名册对照表(全局层可限制 / 作用域层
  不可限制)、三桶语义(可限制 / scopeLocal / unresolved)、
  diag 三行原文;容错口径改为「多写名字不会让策略整批失效」
- 新增「一个必须知道的能力边界」:ops_discover_tools 能激活
  写侧作用域工具,白名单不是安全边界
- 新增「关于模型」:角色 frontmatter 的 provider/model 只有
  subagent_role 路径读,team 注入路径不带模型路由,成员一律
  跑宿主默认模型,换模型走 team_member_revive

ui-specialist:
- 第三部分内联 ui-verify / lvgl-simulator / board-ui-nav /
  font-regen 四个技能全文,成员无需 skill() 路由即得完整
  规程(persona 28855B,上限 65536B);权威源仍是
  .dsh/skills/,段首写明同步纪律

实测:插件真实 parseRoleDocument 通过;白名单计数
43/43/43/43/43/43/41/41;maxToolCalls 3000 不变。
2026-11-16 16:43:50 +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 语义取数、全周傅氏相量、测频、保护判据 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

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

角色 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)
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),与角色无关。当前 8 个角色文件都没写这三个字段,全部继承宿主默认。要给某个成员换模型用 team_member_revive({ target, provider, model })(活体立即生效,冷会话挂起到复活瞬间)。机制与两条改造路径 → .dsh/plugins/dsh-plugin-subagent-roles/docs/子Agent角色自动注入实现说明.md §1.2。

角色详细说明

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 成本)。

工具限制:只读(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),只做验证和诊断。

适用场景:构建失败诊断、门禁报错排查、环境问题定位、提交前验证。


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() 实现。

要正确理解它管得住什么,先要知道本宿主的工具名册分两层:

层 谁注册的 典型工具 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):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 + 公共工具组 — 允许文件修改

只读角色的只读性靠"全局层没有 edit/write"保证,是可靠的;但按上面那条边界,它们仍能通过 ops_discover_tools 激活写侧作用域工具。要真正封死,得把 ops_discover_tools 也从只读角色白名单里去掉。