Files
STM32F4-Base/.dsh/roles/README.md
T
wandering1 9f68b7bc03
CI / 静态门禁 (pre-commit) (push) Failing after 3m46s
CI / 主机侧单测 (MSVC) (push) Successful in 30s
feat(dsh): spawn_teammate 角色 persona 自动注入 + 测频带外饱和边界登记
一、子 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)。
2026-11-14 10:07:27 +08:00

195 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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]` + 公共工具组 — 允许文件修改