9f68b7bc03
一、子 Agent 角色自动注入(本批主线) dsh-plugin-subagent-roles fork(仓库 .dsh/plugins/)新增事件路径注入: spawn_teammate 的 prompt 首行写 @role:<角色id>,插件在子会话首轮模型 请求组装之前把 .dsh/roles/<id>.md 的 persona 注入其系统提示词,并应用 工具白名单。此前只有 subagent_role 路径自动注入,team 路径需 Lead 手工 拼接 persona,本批把两条路径拉齐。 实现要点(细节见 docs/环境与部署/子Agent角色自动注入实现说明.md): - 在 lead 会话的 tool/call(spawn_teammate) 截获 @role 标记,在 subagent/catalog 拿 childId 后经 agents.get(childId) 注入——子会话侧 user/message 必然晚于首轮 system/message,只能在 lead 侧接力。 - tools.restrict() 只校验全局工具名,ops_* 等作用域工具混入会整批抛错; 降级为解析报错尾部 known global tools 求交集后重试。 - 保留子会话 @role 标记兜底路径(第 2 步起生效)+ 双去重集合。 - 诊断日志 ~/.dsh/role-inject-diag.log,一次健康注入 4 行。 配套文档与口径: - 新增 docs/环境与部署/子Agent角色自动注入实现说明.md(实现参考 + 排障速查,9 章),docs/README.md 索引挂载。 - AGENTS.md 委派策略改为自动注入口径(无需手工拼接)。 - .dsh/roles/README.md 删去"调用预算"列:budget.js 的 arm() 只由 subagent_role 委派路径调用,teammate 路径不挂账,原列是假上限承诺; 改加脚注指向实现说明 §1.1。 二、测频幅值门放宽至 5 V + 带外饱和边界登记(freq.h) - FREQ_AMP_MIN 50 V -> 5 V(用户裁定 2026-11-13):台架低端注入(标定 用 5~25 V 档)与低负荷工况也能测频;浮空二次域噪声几十 mV,仍差两个 数量级,噪声不测频的本意不变。 - 注释同步登记:IA 回退候选同拿 5.0 比较,二次电流 0.5~2 A 够不到 "5 A",只注电流实际不回退测频(电流域门限另裁);窗环钳位区间 [72,96] 只对 41.7~55.6 Hz 满足整倍条件,带外读数饱和钉沿。 - docs/算法/采集与算法层设计说明.md 新增 §7.3 准确测频带与带外饱和 (60 Hz 实证钉 ~55;用户裁定不改参数,只登记边界)。 验证:/keil-build 0 错误 0 警告(Code=256592 RO=32036 RW=2088 ZI=152584);pre-commit 52 钩子全绿(含 3 根 manual 阶段:cppcheck、 test-cppcheck、test-coverage)。
195 lines
12 KiB
Markdown
195 lines
12 KiB
Markdown
# 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 的窗口对齐逻辑..."
|
||
})
|
||
```
|
||
|
||
## 角色总览
|
||
|
||
### 核心模块专家(双层结构:通用行业标准 + 项目专项)
|
||
|
||
| 角色 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]` + 公共工具组 — 允许文件修改
|