9e538d2809
二、门禁与唤醒(新插件 dsh-plugin-team-ledger 0.2.0)
宿主 Agent Teams 缺两块能力,补在独立仓
D:/Code/AI/dsh-plugin-team-ledger:
- 状态存放:<工作区>/.dsh/team/gate.jsonl 追加账本,记验收
清单、实测证据、认领历史,跨重启存活;canonical JSON +
fsync,坏尾行截断恢复。
- 唤醒模型:门禁推进后按事件计划唤醒下一责任人,借活体
Lead 作 caller 走宿主 sendMessage;无定时器;30 分钟滑动
窗口限 4 次防复活风暴。
- 验收独立性由机器强制:执行人/历史认领者不能 accept,
checklist 逐项 passed=true 缺一不可。
- team_member_revive(Lead 专用):成员模型路由死亡后的
复活通道——可换 provider/model,再经 subagents.sendMessage
冷恢复唤醒,绕过宿主 roster 的 phase=active 门禁。
二、角色绑定跨重启还原(roles fork 0.5.2)
persona 与工具白名单只有运行中 agent 的内存态,宿主重启后
冷恢复的成员既无 persona 也无白名单——实测出现 doc-writer
成员带全量工具面(qq_*/ImageGen),属静默权限放大。改为
注入成功时持久化 childId -> {roleId, cwd} 到
~/.dsh/role-inject-bindings.json,并在 agent/created 时重放。
追加 team_member_rebind 补绑定,覆盖 0.5.2 之前已存在的成员。
三、配套
- .dsh/roles 八个角色白名单加入门禁工具;AGENTS.md 委派策略
补门禁/复活/重绑三套操作口径。
- docs/环境与部署/子Agent角色自动注入实现说明.md 新增
§5.1,记录绑定机制、存量成员缺口与「成员自省不可全信」的
台架教训。
275 lines
26 KiB
Markdown
275 lines
26 KiB
Markdown
# dsh-plugin-subagent-roles
|
||
|
||
[English](README.md) | 中文 | [更新日志](CHANGELOG.md)
|
||
|
||
[](https://www.npmjs.com/package/dsh-plugin-subagent-roles)
|
||
[](https://github.com/troytse/dsh-plugin-subagent-roles/actions/workflows/ci.yml)
|
||
[](LICENSE)
|
||
|
||
## 概述
|
||
|
||
`dsh-plugin-subagent-roles` 用文件来定义子代理角色。一个角色就是一个 Markdown 文件:frontmatter 里是显示名、路由描述、可选的模型路由、工具策略和可选的工具调用预算,正文是子代理要遵循的 persona。项目级角色放在 `<项目>/.dsh/roles/`,全局角色放在 `~/.dsh/roles/`;同 id 同时存在时项目级生效。
|
||
|
||
插件注册一个委派工具,并把当前工作区里的角色以一行行的紧凑目录告知主代理。委派到某个角色时,子代理带着该角色的 persona 启动,且只保留策略允许的工具——主代理的上下文里不会出现 persona 正文,没有角色文件的项目也不会看到任何目录。角色还可以限制子代理能用多少次工具:这是由框架自己的 `tool/call` 事件计数的**硬**上限,因此不肯收尾的子代理会被强制停下。
|
||
|
||
## 安装
|
||
|
||
**桌面版(DSH 桌面 App)**——在 App 侧栏的 **Plugins** 页里安装:粘包名即从 npm 拉取,粘**绝对路径**则安装本地检出。
|
||
|
||
```
|
||
dsh-plugin-subagent-roles
|
||
# 或本地检出
|
||
/path/to/dsh-plugin-subagent-roles
|
||
```
|
||
|
||
`desktop` 这个 profile 归 App 独占——`dsh plugin --profile desktop …` 会被明确拒绝(`profile "desktop" is managed exclusively by the Electron application`),所以桌面版走 Plugins 页。它会安装包、把 bundle 追加进 profile,随后该行会出现在设置页的清单里。宿主侧的行会即时加载;客户端界面(其它插件的侧栏/任务页/用量页)需要刷新一次页面才会出现。
|
||
|
||
**命令行 profile(`dsh web`、TUI、headless)**——按名字装进对应 profile,或 link 一个检出:
|
||
|
||
```sh
|
||
# 从 npm 安装
|
||
dsh plugin --profile web add dsh-plugin-subagent-roles
|
||
|
||
# 或本地 checkout
|
||
dsh plugin --profile web add link:/path/to/dsh-plugin-subagent-roles
|
||
```
|
||
|
||
装好后重启该 profile(`dsh web`)。包内自带 bundle patch,会自行插入它的那一行组合,无需手改 composition。要求 Node.js 20 以上,以及提供 `@deepseek-ai/dsh-tools` 与 `@deepseek-ai/dsh-subagent` 的 DSH 部署。
|
||
|
||
**版本线**:0.5.x 只支持 **DSH 0.2.1-rc.1+**;0.2.0 及更早请继续用 0.4.3。0.2.1 移除了 `subagents.start` / `startContinuable`、请求里的 `persona` / `toolFilter` 以及客户端设置服务,0.5.0 已按新 API 重写委派与 composition,角色文件格式与模型绑定不变。
|
||
|
||
## 快速开始
|
||
|
||
在项目里创建一个角色文件:
|
||
|
||
```markdown
|
||
---
|
||
displayName: 代码审查员
|
||
description: 审查改动的正确性、安全性与测试覆盖,按严重级别给出结论。
|
||
provider: deepseek-official
|
||
model: deepseek-v4-flash
|
||
reasoningEffort: low
|
||
tools: [read, grep, glob]
|
||
---
|
||
你是代码审查员。先读改动再下结论,区分阻塞项与建议项,
|
||
每条问题都给出文件与行号。
|
||
```
|
||
|
||
然后让主代理委派——“让代码审查员角色审一下这个改动”——或直接调用工具:
|
||
|
||
```js
|
||
subagent_role({ role: "code-reviewer", prompt: "审查已暂存的改动。", description: "审查暂存改动" })
|
||
```
|
||
|
||
角色在组装提示词时读取、在委派开始时再读取一次,因此改角色文件**不需要重启 DSH**。同风格的派发提示词见 `examples/delegation-prompts.zh.md`。
|
||
|
||
## 角色文件
|
||
|
||
### 角色从哪里读取
|
||
|
||
| 优先级 | 路径 | 说明 |
|
||
|---|---|---|
|
||
| 1 | `<项目>/.dsh/roles/<id>.md` | `<项目>` 是从会话工作目录向上找到的第一个含项目标记(默认 `.git`)的目录;找不到标记时就是工作目录本身。 |
|
||
| 2 | `~/.dsh/roles/<id>.md` | 跨项目共用。可用 `dshHome` 改位置。 |
|
||
|
||
角色文件可以是符号链接。文件按文件名寻址,因此 id 就是文件名(去掉 `.md`),必须是 kebab-case。
|
||
|
||
### 文件格式
|
||
|
||
frontmatter 是 YAML 映射,正文是 persona。
|
||
|
||
| 字段 | 必填 | 含义 |
|
||
|---|---|---|
|
||
| `description` | 是 | 目录里显示的一行描述,主代理据此判断要不要委派。 |
|
||
| `name` | 否 | 写了就必须与文件 id 一致,用来拦住"改了文件名却没改声明"。 |
|
||
| `displayName` | 否 | 人可读的名字,默认取 id。 |
|
||
| `whenToUse` | 否 | 追加在目录行末尾的补充路由提示。 |
|
||
| `provider`、`model` | 否 | 子代理的模型路由。两者必须同时出现或同时省略;省略时继承主代理的路由。 |
|
||
| `reasoningEffort` | 否 | 子代理的思考力度,随路由一起生效。 |
|
||
| `tools` | 否 | 允许清单简写,如 `[read, grep, glob]`。 |
|
||
| `toolFilter` | 否 | 显式策略:`{ allow: [...], deny: [...] }`。 |
|
||
| `maxToolCalls` | 否 | 子代理工具调用次数的硬上限,整数。**省略**则继承行配置的 `defaultMaxToolCalls`;写 `0` 表示**显式不限**,它会**覆盖**行默认值。 |
|
||
| `maxToolCallsScope` | 否 | `delegation`(默认)每次委派重新计数——continuable 子代理的每个 `turn/start`(即一次后台唤醒)也算新的一次;`session` 则按该子代理整个生命周期累计。 |
|
||
| `onToolCallBudget` | 否 | 额度耗尽时的行为:`wrap-up`(默认)、`interrupt` 或 `off`。 |
|
||
| `graceToolCalls` | 否 | `wrap-up` 注入通知后额外放行的调用次数,默认 `1`;`0` 表示在触发的那一次调用上直接收口。 |
|
||
|
||
`tools` 与 `toolFilter` 只能二选一。**未知的 frontmatter 键会被拒绝**而不是忽略,避免拼写错误悄悄放宽角色的工具范围。
|
||
|
||
`maxToolCalls` 族字段需要**插件 ≥ 0.4.0**。旧版本完全不认识这些键,会把整个角色文件判为非法而跳过,因此**角色文件与插件版本是绑定的**:给某个角色加上额度,就意味着每个使用该工作区的机器都要升级插件。
|
||
|
||
persona 正文可以使用 `{{cwd}}`、`{{model}}`、`{{provider}}`——**恰好是 agent loop 注册的那三个**,由框架在子代理侧插值。部署里若另有插件注册了更多变量,可在 `personaVariables` 中列出;除此之外的任何引用都会在读取角色文件时被拒绝,因为未知变量会让**该子代理的每一轮**都抛错。引用按精确规则匹配(花括号内不能有空格);而目录字段——`description`、`displayName`、`whenToUse`——**完全不能出现 `{{`**,因为目录文本在到达模型之前同样会经过插值。
|
||
|
||
## 配置
|
||
|
||
行配置如下;在 profile patch 里按 id 覆盖即可:
|
||
|
||
```yaml
|
||
# ~/.dsh/profiles/web/cordis.patch.yml
|
||
- id: subagent-roles
|
||
name: dsh-plugin-subagent-roles
|
||
config:
|
||
catalogDescriptionMaxLength: 120
|
||
```
|
||
|
||
| 选项 | 默认 | 含义 |
|
||
|---|---|---|
|
||
| `toolName` | `subagent_role` | 模型可见的委派工具名。 |
|
||
| `subagentProvider` | `spawn` | 子代理传输 provider。 |
|
||
| `backgroundMode` | `one-shot` | `one-shot` 或 `continuable`。 |
|
||
| `enableRunInBackground` | `true` | 是否在工具上暴露 `run_in_background`。 |
|
||
| `maxDepth` | 不设 | 委派深度上限;不设则由 provider 决定。`0` 表示拒绝任何委派。 |
|
||
| `defaultRole` | 不设 | 调用未给 `role` 时使用的角色。 |
|
||
| `catalog` | `compact` | `compact` 渲染角色目录;`off` 完全不渲染。 |
|
||
| `catalogScope` | `main` | `main` 只向顶层 agent 展示角色;`all` 连子代理也展示。 |
|
||
| `catalogDescriptionMaxLength` | `160` | 目录行里每条描述的截断长度。 |
|
||
| `projectRootMarkers` | `['.git']` | 从会话工作目录向上寻找项目根的标记。 |
|
||
| `projectRootTtlMs` | `5000` | 项目根结果被信任多久后重新向上查找,好让会话运行中 `git init` 也能被发现。 |
|
||
| `dshHome` | `$DSH_HOME` 或 `~/.dsh` | 全局 `roles/` 目录所在位置。 |
|
||
| `maxBodyBytes` | `65536` | persona 体积上限,按 UTF-8 字节计。超过该值加 64 KiB frontmatter 余量的文件**在读取之前**就被拒绝。 |
|
||
| `personaVariables` | `['cwd', 'model', 'provider']` | 允许 persona 引用的提示词变量。仅当部署确实注册了更多变量时才扩充。 |
|
||
| `respectModelSelection` | `true` | 是否遵守官方 `subagent-model-selection` 允许清单:先看会话已捕获的策略,再看实时设置。 |
|
||
| `onMissingTool` | `drop` | 不可用的工具名:`drop` 告警后继续,`error` 直接拒绝委派。 |
|
||
| `timeoutMs` | 不设 | 单次前台委派的工具调用超时。不设则不限时。 |
|
||
| `defaultMaxToolCalls` | `0` | 角色文件未声明额度时使用的工具调用预算。`0` 表示不限,且**默认就是 0**:2277 个文件的大仓和一个小项目对"合理调用数"的定义不同,所以这个数字属于角色文件而不是全局硬编码。 |
|
||
| `maxToolCallsHardCap` | `0` | 角色文件不得超过的上限,防止项目侧把额度开到失去意义。`0` 表示不设上限,且**永不削顶显式的 `maxToolCalls: 0`**——"不限"是哨兵值而不是数值零。 |
|
||
| `onToolCallBudget` | `wrap-up` | 额度耗尽行为的行级默认值,可被角色文件覆盖。 |
|
||
| `graceToolCalls` | `1` | 宽限次数的行级默认值,可被角色文件覆盖。 |
|
||
| `enableListTool` | `false` | 是否注册诊断工具。 |
|
||
| `listToolName` | `subagent_roles` | 诊断工具的名字,让第二行能与之共存。 |
|
||
| `childPromptTrim` | `full` | 裁剪**子代理**提示词:`full` 丢弃子代理用不上的工具说明,外加命名过的提示词片段;`tools` 只丢前者;`off` 不注册该监听器。主代理的提示词永不改动。 |
|
||
| `childPromptTrimNames` | `['harness:source', 'app:web-surface', 'ui:deliverable-file-references', 'context:file-reference']` | `full` 模式下丢弃的提示词片段名,**section 与 context 一并匹配**。清空该列表即全部保留。 |
|
||
|
||
## 工具策略
|
||
|
||
角色的策略决定子代理能看见、能调用哪些工具。`tools`(以及 `toolFilter.allow`)是允许清单:未列出的一切都会从子代理消失——schema 与对应提示词一起——调用也会被拒。`toolFilter.deny` 只移除指定工具、保留其余。条目支持通配符 `*` 与 `?`,例如 `mcp__demo__*`。
|
||
|
||
通配符在委派时按**主代理当时可见的工具名**展开,所以某个工具还没注册也不会让委派失败。不可用的字面名会被丢弃并告警;`onMissingTool: 'error'` 会改为直接拒绝。允许清单展开为空时会原样传下去(空允许清单 = 隐藏全部继承来的工具),而不是放开全部工具。
|
||
|
||
两类情况单独处理:
|
||
|
||
- `run_code`(PTC 部署的呈现传输)永远不会进入策略:工具注册表会列出它,但核心不允许按这个名字做限制。
|
||
- 主代理**自己作用域**里注册的工具会被父代理继承,但不属于子代理的作用域链。写出这类名字会导致核心拒绝创建子代理;插件会把这些名字剔除、重试一次委派,并告警。
|
||
|
||
## 工具调用预算
|
||
|
||
角色文件里的 `maxToolCalls` 是插件**强制执行**的硬上限,**不依赖子代理自觉**。计数取自框架自己记录的 `tool/call` 事件,既不采信子代理自报,也不解析它的输出。
|
||
|
||
### 什么算"一次"
|
||
|
||
计量单位是**次**而不是**轮**——这正是当初"8 步"口头约定失效的原因:
|
||
|
||
| 情形 | 计为 |
|
||
|---|---|
|
||
| 同一步内并行发起的多个调用 | 各计 1 |
|
||
| 调度器已落盘、随后被策略/guard 拒绝的调用 | 1 |
|
||
| 同一步中被取消而跳过的调用 | 1 |
|
||
| wrap-up 注入的收尾通知本身(是消息,不是工具调用) | 0 |
|
||
| 子代理自己再派生的孙代理 | 只计该子代理自身;每个孙代理独立计数 |
|
||
|
||
`used === limit` **不算超限**;跨过上限的那一次才算。收口是**反应式**的:那次调用已经写进会话日志,插件是在它结束前把子代理停下。所以保证的是"子代理会停",而不是"触发的那次调用不会开始"。
|
||
|
||
### 额度耗尽时
|
||
|
||
| 模式 | 行为 |
|
||
|---|---|
|
||
| `wrap-up`(默认) | 投递一条插件署名的收尾通知("预算已耗尽,请产出部分结论"),再宽限 `graceToolCalls` 次调用,之后才停下子代理。 |
|
||
| `interrupt` | 投递**同一条**通知,并在触发的那一次调用上立即停下。 |
|
||
| `off` | 只告警一次,永不拦截——因此也**不往子会话写入任何持久记录**。 |
|
||
|
||
`graceToolCalls: 0` 就是 `interrupt`:同一条通知、同一次调用上的同一个停止点。
|
||
|
||
收口机制取决于委派路径,这一点值得记住:`SubagentRuntime.interrupt()` 对 one-shot run 是**被接受的 no-op**,因此前台/后台的 one-shot 子代理是通过它启动时所用的信号被取消的,只有 `continuable` 子代理才走运行时中断。远程传输若不发布本地子代理对象,它的子代理就**跑在本进程之外**:其 `tool/call` 事件到达不了护栏,既数不到也停不下,wrap-up 通知也投递不了——插件会在委派时就告警,而不是把一个并未受保护的角色报成已受保护。
|
||
|
||
### 如何通知子代理与主代理
|
||
|
||
收尾通知是一条带**显式 `plugin` 来源**的 `user` 角色消息,通过 `Agent.inject()` 投递,因此它落在下一个 step 边界,且**不会把空闲子代理唤醒成一个新轮次**。显式来源是必须的:省略 source 会被解析成 `user`,等于让机器生成的指令冒充人类输入。
|
||
|
||
同一条通知就是**这次收口的持久记录**:它把 `used`/`limit`/`scope`/`mode` 写进子会话自己的日志,因此被停下的委派可以回放——**停在哪一次、还剩多少**。正因如此,它在**每一次**收口时都会投递(包括 `interrupt`),而不只是 `wrap-up`:对一个被直接杀掉的子代理,光靠宿主日志回答不了这个问题。`off` 是唯一从不收口的姿态,因此不写子会话记录。
|
||
|
||
被停下的**前台**委派返回一个正常的结构化结果——`status: 'tool-call-budget-exceeded'`,外加 `reason`、`role`、`used`、`limit`、`scope`、`mode` 与可能的 `partialOutput`。它**故意不是错误**:抛错会被主代理当成可重试的工具故障,而这里真正该选的是"派更窄的任务 / 放宽额度 / 接受部分结论"。**后台**委派则让 job 的 detail 明确写出预算收口,从而不会与"用户 kill"混淆。
|
||
|
||
`timeoutMs` 与预算是**正交**的两个护栏,谁先到就由谁出报告:预算收口是上面那个结构化结果,而超时保留核心自己的 `TOOL_TIMEOUT` 错误。两者不会被混成同一个失败。
|
||
|
||
## 诊断
|
||
|
||
打开 `enableListTool` 后会注册 `subagent_roles`:它逐个列出角色及其来源、文件路径、绑定路由、persona 体积、展开后的策略、schema 字符预算,以及**工具调用额度与它的来源**(角色文件 / 行默认 / 不限),还有被跳过的文件和原因。
|
||
|
||
要核对一次已完成的委派,读子代理的会话日志即可:
|
||
|
||
```sh
|
||
node scripts/inspect-session-budget.mjs --project <项目目录>
|
||
node scripts/inspect-session-budget.mjs <会话目录> --all --grep "你是代码审查员"
|
||
```
|
||
|
||
该脚本只读地解码会话日志,打印系统提示体积、该会话请求的工具 schema,以及角色目录是否到达了那个会话。
|
||
|
||
## 设置界面
|
||
|
||
**DSH 0.2.1 上本插件没有 Settings 卡片**:0.2.1 移除了客户端 `settingsScope` 服务、插件可注册的设置命名空间与 `settings.plugin.item` slot。裁剪与预算的六个旋钮就是本插件的**行 config**;在 profile 的 `cordis.patch.yml` 里写在本行 `config` 下,改动后重启该 profile(行会重新激活)。
|
||
|
||
| 键 | 默认 | 含义 |
|
||
| --- | --- | --- |
|
||
| `childPromptTrim` | `full` | `full` / `tools` / `off` |
|
||
| `childPromptTrimNames` | 内置名单 | `full` 模式下额外丢弃的 section/context 名 |
|
||
| `defaultMaxToolCalls` | `0` | 角色文件未声明时的默认额度;0 不限 |
|
||
| `maxToolCallsHardCap` | `0` | 角色文件不得超过的硬上限;0 不设 |
|
||
| `onToolCallBudget` | `wrap-up` | `wrap-up` / `interrupt` / `off` |
|
||
| `graceToolCalls` | `1` | wrap-up 通知后的宽限调用数 |
|
||
|
||
角色文件自己声明的 `maxToolCalls` 仍然优先;行 config 只提供「角色文件省略时的默认值」与硬上限。
|
||
|
||
没有 GUI 卡片是刻意的取舍:0.2.1 的插件配置页要求插件自己实现 `plugins.row.config` 组件并绑定 `configForms`。本版优先保证宿主半边的行为正确;浏览器半边仍会加载,只打印一次说明后不注册任何 slot,绝不会因为缺少服务让整行停在 `pending`。
|
||
|
||
## 工作原理
|
||
|
||
- **目录**:一个提示词 section,按每次组装求值,列出该 agent 工作区的角色:一行说明,加每个角色一行 `- <id> (<显示名>): <描述>`。在以下情况渲染为空且不占上下文——项目没有角色、目录被关闭、当前是子代理、或该 agent 看不到委派工具。
|
||
- **委派**:`subagent_role` 按主代理的工作目录解析角色,然后经 `ctx.subagents` 启动子代理,带上该角色的 persona、路由与工具策略。工具面向模型的说明会跟随传输 provider:fork 型 provider 的子代理已带上本会话已完成的轮次,此时说明改成「在已有轮次上继续」,而不是「必须自带完整上下文」。路由在子代理存在之前就会经 `llm.resolveCallConfig()` 预检,因此角色文件里 `model` 或 `reasoningEffort` 写错时,报错会回到主代理手上,而不是从子代理创建过程里抛出。
|
||
- **多行共存**:目录 section 与诊断工具都按行命名(`<toolName>:catalog`、`listToolName`),所以同一个 profile 可以为另一种传输 provider 再挂一行(`toolName: subagent_role_fork`),两边都不会撞名。
|
||
- **子代理提示词裁剪**:核心把大多数工具说明注册成**静态文本**(只有 `dsh-tool-fs`、`dsh-tool-fs-search`、`dsh-tool-web`、`dsh-file-reference-local` 会按 scope 求值),于是子代理既继续为「被角色策略藏掉的工具」付说明费,也继续读它永远用不上的 Web GUI、harness checkout 与交付链接说明。一个 host 层的 `system-prompt/assemble` 监听器只丢这些死文本:子代理看不到的**已注册**工具的 `tool:<name>` 说明;组标签说明(`tool:jobs`、`tool:goal`)在它自身文本点到的工具全部不可见时丢弃;`full` 模式(默认)再丢命名过的提示词片段。真实委派实测:角色子代理提示词 5,765 → 1,904 字符(−67%),而主代理逐字节不变。规则推导的部分无需维护;命名的那部分是逐行可覆盖的——子代理该不该继续看到 harness checkout 或交付链接属于部署判断,不是事实。**一份名单同时匹配 section 与 context 是刻意的**:实测发现当前核心把 `context:file-reference` 注册成了 section(尽管名字里有 `context:`),只匹配 context 的名单会静默放过它。
|
||
- **继承与 composition**:不传 `agentPreset` 时子代理加入父代理的 agent preset,因此保留父代理的提示词与工具。角色 persona 与工具策略在 `subagent/start` 时安装到子上下文——该事件在宿主 materialize 内、初始 prompt 提交之前同步触发,所以首轮 assembly 就能看到它们。角色 persona 只对该子代理遮蔽部署 persona 前缀。
|
||
- **工具调用预算**:每行一个 host 层 `session/event` 观察者,统计本行发起过的每个子会话所提交的 `tool/call` 事件;另有一个 `session/disposed` 释放钩子,避免已结束子会话的记录滞留。委派启动时登记一条记录——`0`(不限)不登记任何东西,因此没有预算的角色零成本。跨过上限时通过 `Agent.inject()` 投递一条插件署名通知(它同时就是持久审计记录),随后由收口姿态用两种机制之一结束子代理:one-shot 用其 run 信号,continuable 用 `SubagentRuntime.interrupt()`。收口按轮次限流为一次,因此被停下那一批里从未启动的调用不会把同一次停止重复一遍。计数按子会话 id 索引,父代理、兄弟与孙代理互不共享。
|
||
|
||
## 已知边界
|
||
|
||
- 子代理**自己作用域**里注册的工具不受角色工具策略影响:核心的 restrict 只作用于继承来的工具。委派运行时与部分工具插件会按 agent 注册,因此子代理可能比允许清单多出少量工具。
|
||
- 隐藏工具会移除它的 schema 以及作用域感知的提示词段落;纯静态文本的段落仍会留在子代理提示词里——这正是 `childPromptTrim` 要处理的部分,也是 `tools` 模式无需维护、而 `full` 模式依赖 section 名的原因(未来核心改名后该段只是不再被裁剪,不会报错)。
|
||
- 角色 persona 会替换子代理的部署 persona 前缀;persona 后缀(例如工作目录那一行)保留。
|
||
- `respectModelSelection` 优先使用会话已捕获的策略(与官方委派工具写入的同一个持久 projection),没有捕获时才回退到实时 `subagent-model-selection` 设置——实时设置只用于给新会话播种。因此改动只对**尚未捕获策略**的会话生效。
|
||
- `childPromptTrim` 作用于宿主所见**每一个**子代理的组装,而不只是本插件发起的角色子代理:运行时不在子代理上记录角色标记,所以 `subagent` 等其他行的子代理同样受益。注册在 agent 自身作用域里的工具(`subagent`、`list_agents`)不在注册表的全局视图里,因此它们的说明永不被裁剪——真的能调用它的子代理会保住自己的说明。
|
||
- 委派工具默认不声明 `timeoutMs`,前台委派因此可能比发起它的对话活得更久;长任务请用 `timeoutMs`、`maxDepth` 或派发提示词约束。
|
||
- 工具调用预算是**反应式**收口的:跨过上限的那一次调用已经写进会话日志,插件是在它结束前停下子代理,而不是阻止它开始。计数本身是精确的。
|
||
- 远程传输若不发布本地子代理对象(`SubagentRun.localAgent` 为 `undefined`,例如进程外 provider),其子代理跑在本进程之外,`tool/call` 事件到达不了护栏:预算既数不到也停不下它,通知也投递不了。插件会在委派时告警,而不是把一个并未受保护的角色报成已受保护。进程内传输不受影响。
|
||
- `timeoutMs` 与预算是相互独立的,但它们**呈现**结果的方式也独立——如果预算收口已经开始、而工具调用 deadline 在停止后的 run 仍在拆卸时到期,核心自己的 timeout 包装器会用 `TOOL_TIMEOUT` 错误替换掉那个结构化结果。子代理两种情况下都会被停下,只是"报告"可能归后到的那个护栏。
|
||
- `scope: session` 的收口按轮次限流为一次:被父代理再次唤醒的、已超额的 continuable 子代理会被**再次**停下,但被停下那一批里从未启动的调用不会各自重复一遍停止。
|
||
- 反过来,按轮次限流也意味着:`scope: delegation` 的额度一旦触发,在**该轮剩余时间里**会保持安静,即使 `used` 继续增长;下一轮重新计数(也会重新收口)。
|
||
- 监视器的记录表有上限(256 条),淘汰顺序是**插入序而不是使用序**——它是防泄漏的兜底,不是生命周期本体。记录通常会在其子会话被 dispose、或委派结算时释放,所以淘汰理应只碰到被遗弃的条目;极端churn 下若真有活记录被淘汰,那个角色的额度会静默失效。
|
||
- `maxToolCallsHardCap` **不会**约束显式的 `maxToolCalls: 0` / `defaultMaxToolCalls: 0`。`0` 是"不限"哨兵而不是计数,因此逃生口优先于上限——请用上限去削一个已声明的数字,而不是用它禁止"不限"。
|
||
- 额度按子会话计数:同名角色的两个并发委派不会共享计数;`scope: session` 会跨 continuable 子代理的多次唤醒持续累计,直到插件行卸载或那个有上限的记录表把它淘汰。
|
||
- 角色额度**不会**出现在角色目录里,只有 `subagent_roles` 会报告它,因此带预算的角色对提示词体积没有影响。
|
||
- 发现缓存有上限(512 条),因此同一宿主进程里访问过极多不同项目时,会比其他情况更频繁地重新 stat 文件;结果不受影响。
|
||
- 诊断脚本需要 Node.js 22.15 以上(多帧 zstd 解码);插件本身在 Node.js 20 上运行。
|
||
|
||
## 开发
|
||
|
||
```sh
|
||
npm test # 单元测试(node --test)
|
||
npm run lint # 对 lib/、scripts/、test/ 做 node --check
|
||
node --test --experimental-test-coverage # 逐文件覆盖率
|
||
```
|
||
|
||
运行时在 `lib/`:`roles.js`(发现与解析)、`catalog.js`(目录文本)、`policy.js`(工具策略)、`route.js`(模型路由)、`budget.js`(工具调用预算的解析与计数)、`tool.js`(委派与诊断工具)、`config.js`(行配置)、`settings.js`(设置命名空间)、`index.js`(插件装配)。
|
||
|
||
CI 在 Node.js 20、22、24 上运行 `npm run lint` 与 `npm test`。
|
||
|
||
### 发版
|
||
|
||
1. 先在 `CHANGELOG.md` 补一条 `## [<版本号>]` 记录。发版工作流会拒绝发布一个更新日志里没有的版本。
|
||
2. `npm version <patch|minor|major>` 会提交版本号变更并打 tag,推送提交与 tag。
|
||
3. `.github/workflows/publish.yml` 会跑测试、校验 tag 与 `package.json` 版本一致、校验更新日志条目,再通过 npm trusted publishing(OIDC)发布并附带 provenance 证明,因此仓库里不保存任何长期 token。
|
||
|
||
首次自动发版前,需要先在 npm 的包设置页把 `publish.yml` 登记为 trusted publisher。
|
||
|
||
## 许可
|
||
|
||
MIT
|