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 不变。
This commit is contained in:
+58
-22
@@ -20,21 +20,23 @@ spawn_teammate({
|
||||
|
||||
| 角色 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 |
|
||||
| `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` | 代码审查员 | 审查改动的正确性、安全性与规范合规 | 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 |
|
||||
| `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 路径不挂账)。所以本表不再列预算列,免得被当成上限承诺。缺口与后续补齐口径 → `docs/环境与部署/子Agent角色自动注入实现说明.md` §1.1。
|
||||
> **关于工具调用预算**:角色文件 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。
|
||||
|
||||
## 角色详细说明
|
||||
|
||||
@@ -92,7 +94,7 @@ spawn_teammate({
|
||||
|
||||
**审查维度**:正确性(分层边界、ISR 路径、socket 串行)、安全性(堆分配、返回值校验、竞态)、规范合规(命名、ASCII 字面量、BOM、日志冗余)、内存与资源(RAM 余量、DBG 成本)。
|
||||
|
||||
**工具限制**:只读(read/grep/glob),不做修改。
|
||||
**工具限制**:只读(`ops_grep`/`ops_glob`/`ops_inspect_local_file`),不做修改。
|
||||
|
||||
**适用场景**:提交前代码审查、跨模块改动评审、安全审计。
|
||||
|
||||
@@ -114,7 +116,7 @@ spawn_teammate({
|
||||
|
||||
**关键知识**:52 个钩子的触发面与口径、keil-build/serial-boot-test skill、ci_local.py 流程、Python .venv 环境、UV4 工程文件不入库。
|
||||
|
||||
**工具限制**:只读(read/grep/glob),只做验证和诊断。
|
||||
**工具限制**:只读(`ops_grep`/`ops_glob`/`ops_inspect_local_file`),只做验证和诊断。
|
||||
|
||||
**适用场景**:构建失败诊断、门禁报错排查、环境问题定位、提交前验证。
|
||||
|
||||
@@ -153,31 +155,63 @@ spawn_teammate({
|
||||
|
||||
## `tools` 字段说明
|
||||
|
||||
角色文件 frontmatter 中的 `tools` 字段控制子 agent 可用的工具白名单。它通过 `ctx.tools.restrict()` 实现,作用于子 agent 作用域内**通过 tools registry 注册的所有工具**。
|
||||
### 不能被 `tools` 字段管的工具
|
||||
角色文件 frontmatter 中的 `tools` 字段控制子 agent 可用的工具白名单。它通过 `ctx.tools.restrict()` 实现。
|
||||
|
||||
以下工具由 DSH harness 保留,`tools.restrict()` 拒绝接受其名称,始终对所有子 agent 可用:
|
||||
要正确理解它管得住什么,先要知道本宿主的工具名册分两层:
|
||||
|
||||
| 层 | 谁注册的 | 典型工具 | `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`)的对应行:
|
||||
|
||||
```text
|
||||
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 传输层保留工具 | `policy.js` L27: `UNRESTRICTABLE_TOOL_NAMES = new Set(['run_code'])`;`restrict()` 抛出 `cannot name reserved PTC mode presentation transport "run_code"` |
|
||||
| `run_code` | PTC 传输层保留工具,`restrict()` 拒收 | `lib/policy.js` 的 `UNRESTRICTABLE_TOOL_NAMES` |
|
||||
|
||||
> **注意**:billion-context 工具(`compress`/`decompress`/`search_context`/`acp_status`)、Mnemon 工具、QQ 工具、WorkBuddy 工具等**都可以被 `tools` 字段管理**。它们走正常的 tools registry,不在保留名单里。如果角色白名单里没有写它们,子 agent 就**不能用**这些工具。
|
||||
> **注意**:billion-context 工具(`compress`/`decompress`/`search_context`/`acp_status`)、Mnemon 工具、QQ 工具、WorkBuddy 工具都在**全局层**,白名单里不写就真的拿不到。这是本插件最可靠的一条约束面。
|
||||
|
||||
### 容错机制
|
||||
### 白名单里写不存在的名字会怎样
|
||||
|
||||
当角色白名单中包含子 agent 作用域内不存在的工具名时(如未连接的 MCP 工具),`restrict()` 抛出 `names unknown global tool "xxx"`,插件捕获后自动丢弃该名称并用剩余有效名称重试,同时在日志中输出 warn。如果所有白名单名称都被丢弃,整个工具限制失效,子 agent 获得全部工具。
|
||||
不会整批失败。插件先分区:查得到但属作用域层的进 `scopeLocal`(无损剔除),查不到的进 `unresolved`(剔除并写诊断),剩下的全局名照常生效。因此**白名单里多写几个名字不会让整个策略失效**——旧版本靠抛异常后求交集的做法已经移除。
|
||||
|
||||
源码依据:`policy.js` L44-51 `parseUnrestrictableToolNames()`,`tool.js` L816-831 容错重试逻辑。
|
||||
源码依据:`lib/policy.js` 的 `partitionToolFilter()` 与 `restrictableNameSet()`,调用点在 `lib/index.js` 的 `applyToolPolicy()` 与 `lib/tool.js` 的委派主路径、组合安装、诊断工具三处。
|
||||
|
||||
### 当前角色的工具策略
|
||||
|
||||
所有角色均包含以下公共工具组:
|
||||
- **文件操作基础**:`read`, `grep`, `glob`, `ops_bash`, `ops_inspect_local_file`, `ops_discover_tools`
|
||||
- **文件检索**:`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`
|
||||
@@ -190,5 +224,7 @@ spawn_teammate({
|
||||
- **上下文管理工具**:`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]` + 公共工具组 — 允许文件修改
|
||||
- **只读角色**(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` 也从只读角色白名单里去掉。
|
||||
|
||||
Reference in New Issue
Block a user