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,记录绑定机制、存量成员缺口与「成员自省不可全信」的
台架教训。
284 lines
42 KiB
Markdown
284 lines
42 KiB
Markdown
# 更新日志
|
||
|
||
本文件记录 `dsh-plugin-subagent-roles` 的所有重要变更。
|
||
|
||
格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
|
||
|
||
## [0.5.0] - 2026-10-18
|
||
|
||
这一版把插件移植到 **DSH 0.2.1**。0.2.1 移除了 `subagents.start` / `startContinuable`、start 请求里的 `persona` / `toolFilter`、`SubagentRun.localAgent`、`dsh-subagent` 的 `settleRun` 导出,以及客户端设置服务与插件设置命名空间。**角色文件格式、项目/全局优先级、每角色模型绑定、预算与目录均不变。**
|
||
|
||
### 破坏性变更
|
||
|
||
- 只支持 DSH **0.2.1-rc.1+**(`engines.dsh: ^0.2.1-rc.1`)。0.2.0 及更早继续用 0.4.3。
|
||
|
||
### 委派
|
||
|
||
- `ctx.subagents.start(provider, request)` / `startContinuable(spec)` → `startActivation(spec)`:
|
||
- `label` / `signal` 移到 spec 上,`delivery: 'parent'`;
|
||
- 返回 `SubagentActivation`:`childId`、`result`、`dispose()`;
|
||
- foreground 仍等待结果后释放,background 仍经 `ctx.jobs` 结算,continuable 仍只返回 durable id 并保留 resident 子代理。
|
||
- background 的结算改为插件自带的 `settleActivation`(0.2.0 的 `settleRun` 语义:completed 带最终文本、本地 aborted 记 `killed`、带 diagnostic 的 aborted 记 `failed`)。0.2.1 只导出低层的 `settleRunResult`,其参数契约与本插件的 job 结果不同。
|
||
- 删除 `startToleratingUnrestrictableNames` 的重试路径;不可限制的工具名现在在子上下文安装 restriction 时就地丢弃一次(`onMissingTool: 'error'` 时仍然报错)。
|
||
|
||
### Composition
|
||
|
||
- persona 与 toolFilter 不再随 request 下发(0.2.1 的 `SubagentStartRequest` 已删除这两个字段,transport 能力位也不再声明它们)。插件在 `subagent/start` 事件里把两者安装到子上下文:
|
||
- persona 仍是 `deployment:persona-prefix` section,order 取 `DEPLOYMENT_PERSONA_PREFIX`,插值语义不变;
|
||
- toolFilter 仍按父上下文可见工具展开后调用子上下文的 `tools.restrict()`。
|
||
- **确定性关联**:`startActivation` 允许调用方指定 `childId`,插件先生成 id 并登记 composition;`subagent/start` 在宿主 materialize 内、初始 prompt 提交之前同步触发,因此首轮 assembly 就能看到 persona 与限制后的工具集。provider 若忽略该 id 或发布不了本地子代理,插件在 start 返回后按 `activation.childId` 再尝试一次并告警。
|
||
- 能力门禁只保留 `agentOptions` / `depthLimit`;`persona` / `toolFilter` 不再是 transport 能力,旧能力位(有或没有)都不再影响委派。
|
||
|
||
### 设置
|
||
|
||
- 删除 `settings.register` 的命名空间:0.2.1 的 Settings 服务没有该 API。裁剪与预算的六个旋钮以**行 config** 为准。
|
||
- 浏览器半边在 0.2.1 上不再挂载卡片(`settingsScope` / `settings.plugin.item` 均已移除),只打印一次说明后不注册 slot;不会因为缺少服务让整行停在 `pending`。
|
||
|
||
### 预算与可观测性
|
||
|
||
- `run.localAgent` → `ctx.agents.get(childId)`;wrap-up 通知、可观测性告警与 `session/event` 计数按 `childId` 关联。
|
||
- `SubagentActivation.dispose()` 仍由 foreground / background 的结算路径拥有;continuable 不释放,由 runtime 的 interrupt 收口。
|
||
|
||
### 元数据与验证
|
||
|
||
- `engines.dsh` / peer 依赖改为 `^0.2.1-rc.1`;开发依赖固定 `0.2.1-rc.2` 并在仓库内本地安装,不再借用 `~/.dsh/profiles/node_modules` 的 0.2.0 副本。
|
||
- `node --test` **331 项全过**;`npm run lint` 通过。
|
||
- 官方 `subagent` 工具在 0.2.1 改为 fire-and-return activation id、不再等待结果,因此 `test/parity.test.js` 的逐字节对照在 0.2.1 上跳过(脚本保留给 0.2.0 线),由本插件自己的委派/预算/能力测试覆盖。
|
||
|
||
## [0.4.3] - 2026-09-30
|
||
|
||
这一版收掉 0.4.2 独立确认 review 提出的 5 条非阻塞项:其中 2 条是**已发布的文档/注释说了不实的话**,1 条是**真实的静默失败**,其余是结构与注释的准确性。
|
||
|
||
### 修复
|
||
|
||
- **诊断去重改为「按当前装配做差集」,去掉一个真实的静默失败**:原实现是「报过就永久记住」,而被遮蔽的角色文件自身解析成功且命中 mtime 缓存、`loadRecord` 提前返回,于是**解除遮蔽后再被遮蔽时永远不会告警**。现在每次 per-step 读取都会算出本次该根下的全部诊断,与上一次该路径的「standing 原因集」比较:新出现的才上报,消失的(修好 / 解除遮蔽 / 删除改名)立即遗忘,并且**整体替换而非并集**。行为边界:新实现**不会少报**任何真正新出现的发现(对抗式 review 用 400 步差分 fuzz 加独立 oracle 验证 `under=0`,并覆盖了「cwd 变化导致某个根本次未被扫到」这类场景)。与旧实现的差别是:旧实现会在「发现仍然 standing、但被遮蔽的那个文件被改写/触碰」时再刷一次,新实现此时保持静默(更少、更准);新实现只在「发现曾经离开装配又回来」或「原因切换回来」时多报一次。「同一仍然存在的发现不重复刷屏」与全局角色根「每 loader 一次」的语义都不变。
|
||
- **去重结构由 `Set<path\0reason>` 改为 `Map<角色根, Map<精确路径, Set<原因>>>`**:原先每次文件解析成功都要遍历整个已报告集合做前缀匹配(O(全部已报告),极端场景实测 +78ms),现在单路径清除只与该路径的原因数成正比;精确路径键也彻底移除了「一个路径是另一个路径前缀」的误删面。
|
||
- **修正不实措辞(不改行为)**:代码注释曾称诊断「the agent is always told」以及「the delegating agent can only correct what it is told about」,而事实是**委派工具与 catalog 两条路径都只把诊断写进操作者日志(`ctx.logger.warn`)**——loader 返回的 `diagnostics` 不进委派工具结果,catalog 只返回角色清单。需要说清楚的是:可选的 `subagent_roles` 诊断工具(`enableListTool`,默认关闭)**本身**就会把完整清单返回给调用它的模型,那正是它的用途。注释已按此收窄,并新增断言钉死「委派工具返回值不携带诊断」。
|
||
- **`test/wiring.test.js` 注释与事实对齐**:它只钉 catalog 路径(去掉 `lib/index.js` 的 `freshDiagnostics` 才会红),委派路径由 `test/delegation.test.js` 的用例钉,两路共用同一份去重由新增集成测试钉。
|
||
|
||
### 验证
|
||
|
||
- `node --test` **345 项全过**(0.4.2 为 338),`node --check` 全部通过。
|
||
- 两条依赖线都跑过:本地 0.1.5-rc.3 线与干净安装的 `0.2.0-rc.2` 线(CI 实际解析结果)均 345/345。
|
||
- 6 处变异验证(仓库外副本把修复改回旧写法):整体回退旧实现 → 遮蔽复现 / 换因换回 / 删除重建 3 条红;去掉 `\0` 边界的前缀删 → 前缀安全测试红;折叠根级去重 → 多根同名测试红;分别去掉两条路径的 `freshDiagnostics` → 各自的「只报一次」测试红;诊断工具改为带 flag 读 → 全量清单测试红。
|
||
|
||
## [0.4.2] - 2026-09-30
|
||
|
||
这一版收掉 0.4.1 之后的三个「轻微」遗留项,以及它们引出的对抗式复审发现(复审在仓库外副本里独立复验了每条回归测试「有没有牙齿」,并逐条推翻了或确认了作者的声称)。
|
||
|
||
### 修复
|
||
|
||
- **坏角色文件的诊断不再每次委托都刷屏**:委派路径的 `loadSync` 现在与目录(catalog)路径共用 loader 的「已报告诊断」集合(identity = `path\0reason`)。**首次一定告知模型**,同文件同原因每条只报一次;同文件换原因仍会再报。旧测试 `skipped role files are reported on every delegation` 把「每次委托都报」钉成了预期,已**有意识改写**为新语义——旧行为正是本项要消除的噪音。
|
||
- **诊断去重不再吞掉「修好后复发」**:该集合原先没有任何过期机制,于是「坏 → 修好 → 用同样原因再改坏」会永久静默。现在文件**解析成功即遗忘该路径的所有已报告原因**,再次损坏会重新告警。
|
||
- **委派 info 日志有界**:原先把完整 `toolFilter`(`allow: ['*']` 会展开成全部可见工具)与路由 JSON 内嵌进一行。现在 info 只写有界摘要(`allow=N[前4个名字,…]`、`provider/model[/effort]`、`inherit+effort=<effort>`),完整对象降级到 `debug`。
|
||
- **只绑定 `reasoningEffort` 的角色不再被误报为继承**:`summarizeRoute` 原先只看 provider/model,两者皆空就报 `inherit`,而子代理实际拿到 `{ reasoningEffort: 'high' }`——在合法配置下把真实路由报成了相反的值(且 `debug` 低于默认日志级别,默认部署只能看到这个错值)。现在输出 `inherit+effort=high`;该函数此前**完全没有测试**,这正是漏网原因,已补。
|
||
- **裁剪不再靠异常兜底**:`section.text.length` / `context.text.length` 在 `text` 缺失时抛错,被外层 catch 兜成「整份 assembly 这一次不裁剪」。现在 `textLength()` 把缺失文本视为 0:该 part 视为空、内容规则不触发、不计入 saved、**其余 part 照常裁剪**,也不再产生误导性的 skipped 警告(同函数的 context 分支同一潜伏问题一并处理)。
|
||
|
||
### 文档
|
||
|
||
- README(中英)安装段补上**桌面版(DSH 桌面 App)**通道:侧栏 **Plugins** 页按包名或绝对路径安装;并说明 `desktop` profile 由 App 独占、`dsh plugin --profile desktop …` 会被明确拒绝,Plugins 页才是受支持通道;宿主行即时加载、客户端界面需刷新一次页面;**0.1.5 与 0.2.0 两条依赖线都支持**及其设置通道差异。
|
||
|
||
### 验证
|
||
|
||
- `node --test` **338 项全过**(0.4.1 为 333),`node --check` 全部通过。
|
||
- **两条依赖线都跑过**:本地 0.1.5-rc.3 线与干净安装的 `0.2.0-rc.2` 线(CI 实际解析结果)均 338/338。
|
||
- 每条新回归测试都做了**变异验证**(在仓库外副本把修复改回旧写法,确认对应测试会红):诊断去重、跨路径共用集合、路由摘要有界、只绑 effort 的路由、去重过期,共 5 处。
|
||
- 对抗式复审确认:工具 schema、prompt 文案与返回值均未改动,`subagent_roles` 诊断工具的全量清单仍完整。**唯一触及模型可见内容的是裁剪降级本身**——某个 part 缺 `text` 时,旧行为是「整份 assembly 这一次不裁剪」,新行为是「该 part 视为空、其余照常裁剪」,即子代理提示词的组成在异常装配下会变;这是该修复的目的,而不是无副作用,0.4.3 起在此更正表述。
|
||
|
||
## [0.4.1] - 2026-09-30
|
||
|
||
### 修复
|
||
|
||
- **DSH 0.2.0 冷启动直接失败**(`web boot: 1 entry did not activate` / `dsh-plugin-subagent-roles: pending (waiting for service: settingsScope)`)。浏览器半边原先把客户端 `settingsScope` 服务声明为**必需**依赖;0.2.0 移除了该服务(连同插件可注册的设置命名空间),于是这一行永远停在 pending,而**只要有一个行没激活,整个 web boot 就失败**——热加载时不校验,所以只有冷启动才暴露。
|
||
- `exports.inject` 由 `['slots', 'settingsScope']` 改为 `['slots']`:`settingsScope` 变成**可选**读取(属性访问包了 try/catch,且要求 `bind` 是函数),缺失时卡片主动让位并**只打印一次**说明,宿主半边(角色目录、按角色工具过滤、工具调用预算)继续按行配置正常工作。
|
||
- **服务晚到不再永久丢卡片**:一次性读取失败后改为监听 `internal/service` 注册事件,`settingsScope` 稍后出现即补挂。此处刻意**不用** `ctx.inject(['settingsScope'], …)`:那会创建一个 pending fiber,而「有行未激活」正是本次要消除的 boot 失败形态。
|
||
- 卡片 claim 改为**按上下文归属**(`claimOwner`):HMR 下 apply/dispose 两种顺序都不会丢卡片、也不会重复注册;`settings.plugin.item` 的 inject 交由 `ctx.effect` 拥有,注册残留不再可能。
|
||
- **子代理 run 泄漏**:前台/后台两条委托路径上,`onRun` / `track()`(预算 arm)/ logger 任一抛错都会跳过 `settleRun` / `settleForegroundRun`——而它们是 `run.dispose()` 的唯一调用点,run 会泄漏到整个会话结束。现在这些调用各自独立围栏,settle 始终执行,失败照旧上报(`failed` 判定不变)。
|
||
- **激活路径上的 logger 不再能拖垮整行**:`apply` 主路径缺 `systemPrompt` 时的 warn 改为与同文件其余日志一致的 `safely(...)` 包裹——抛错的 logger 在桌面版上等于 boot 失败。
|
||
- `readModelSelection` 对 0.2.0 的 `settings` 服务(无 `get`)改为**特性检测**,不再是抛错后落进空 catch 的死分支。
|
||
- **测试套件适配 0.2.0 依赖线**(此前 CI 在 `0.2.0-rc.2` 的 peer 下全红,本地用 0.1.5 线却是绿的):parity 测试实例化官方工具时缺了 0.2.0 新增的 `ctx.subagents.resolveMaxDepth` 校验依赖;核心 `settleRun` 把文本字段由 `output` 改名为 `result`;`run_in_background` 的官方描述文案在 **0.1.5 线与 0.2.0 线并不一致**(桌面版 bundle 用旧文案),因此 parity 断言改为「必须是官方两种文案之一」——出现**第三种**文案仍会让该测试失败,这正是它存在的意义。以上只动测试,不改生产行为。
|
||
- 0.2.0 上的设置改在 profile 补丁里本插件的**挂载行 `config`** 上(键名与设置卡片完全相同);卡片本身待按 0.2.0 的 `settings.section` 扩展点重做(见 README「Settings」)。
|
||
|
||
## [0.4.0] - 2026-09-22
|
||
|
||
### ⚠️ 不兼容提示(务必先读)
|
||
|
||
- **角色文件与插件版本从此绑定。** 本插件的 frontmatter **未知键会被拒绝**(见 README「文件格式」),因此任何使用了 `maxToolCalls` / `maxToolCallsScope` / `onToolCallBudget` / `graceToolCalls` 的角色文件,在**旧版插件**上会直接报 `unknown frontmatter key` 并被跳过。给角色加额度 = 每台使用该工作区的机器都必须把插件升到 **≥ 0.4.0**。
|
||
- 新增一个**运行时依赖** `@deepseek-ai/dsh-llm`(peer + dev):收尾通知需要用核心自己的 `createUserMessage` 构造,才能带上正确的 `plugin` 来源(见下方「说明」)。
|
||
|
||
### 新增
|
||
|
||
- **角色级工具调用预算硬上限**(`maxToolCalls`):可选、可继承、由插件**强制执行**,不依赖模型自律。计量单位钉死为**「次」而不是「轮」**——这正是口头「8 步」约定失效的根因(§1 实测:两个只读角色分别跑到 19 / 25 次且都未披露)。
|
||
- **计数来源是框架自己的 `tool/call` 事件**,不解析模型输出、不采信模型自报。同一步内并行调用**各计 1**;被策略/guard 拒绝的调用计 1、取消后跳过的调用也计 1(核心在 `startCall()` 第一行就无条件落盘 `tool/call`,拒绝/跳过随后补 `tool/result`,因此口径对三种情形一致)。`used === limit` **不触发**,第 `limit + 1` 次才触发。
|
||
- 四个 frontmatter 字段:`maxToolCalls`(`0` = 不限)、`maxToolCallsScope`(`delegation`(默认)/ `session`)、`onToolCallBudget`(`wrap-up`(默认)/ `interrupt` / `off`)、`graceToolCalls`(默认 `1`;`0` 等价 `interrupt`)。
|
||
- 四个行配置:`defaultMaxToolCalls`(默认 `0`,**刻意不硬编码全局默认数字**)、`maxToolCallsHardCap`(默认 `0`)、`onToolCallBudget`、`graceToolCalls`。角色文件优先于行/设置默认值;`maxToolCallsHardCap > 0` 时角色值被 `min` 削顶并告警——但**永不削顶「不限」的 `0`**(`0` 是哨兵而不是计数)。
|
||
- `scope: delegation` 在已知子会话观察到 `turn/start` 时重置计数,这是「每次后台唤醒各起一个新计数」唯一可观测的定义;`scope: session` 跨唤醒累计。
|
||
- **三条委派路径各自收口**:continuable 子代理走 `SubagentRuntime.interrupt(childId, { kind: 'ancestor', agent })`。**前台/后台 one-shot 走插件自持的取消信号**——因为 `interrupt` 对 one-shot/未知目标是**被接受的 no-op**(核心文档原文:「including a one-shot or unknown id」),若只依赖它会得到「看着生效、实际不生效」的最坏失败形态。前台路径把 `exec.signal` 的取消转发进插件自己的 controller;后台路径复用既有 job controller。
|
||
- **收口记录写进子会话**:收尾通知就是这次收口的**持久审计记录**(携带 `used`/`limit`/`scope`/`mode`),因此在**每次收口**时都会投递——包括 `interrupt`——而不是只在 `wrap-up`。这正是需求 5.3/§7「同一事实写入子会话」「可回放到停在哪一次、剩多少」:对一个被直接杀掉的子代理,宿主日志回答不了这个问题。`off` 只告警、不收口,因此不写子会话记录(已在 README 说明)。
|
||
- **`wrap-up` 在下一个 step 边界注入收尾通知**:用 `Agent.inject()`(`send(msg, 'next-step', false)`)而不是 `steer()`/`followup()`——后者 `wakeup: true` 会把**空闲**子代理唤醒成一个新轮次,等于把收尾指令变成额外工作量。通知是一条**显式 `plugin` 来源**的 `user` 消息:省略 source 会被解析成 `user`,那等于让机器生成的指令**冒充人类输入**并继承人类权威。远程传输不发布本地子代理对象(`SubagentRun.localAgent` 为 `undefined`)时,子代理跑在本进程之外:`tool/call` 到达不了护栏(既数不到也停不下),通知也投递不了——插件在**委派时**就告警,而不是把一个并未受保护的角色报成已受保护。进程内传输不受影响。
|
||
- **超限对主代理是「正常结果 + 状态字段」,不是错误**:前台返回 `status: 'tool-call-budget-exceeded'`、`reason: 'tool-call-budget'`、`role`/`used`/`limit`/`scope`/`mode` 与可选的 `partialOutput`,让主代理明确选择「再派一次更窄的任务 / 放宽额度 / 接受部分结论」;抛错会被当成可重试的工具故障,恰好相反。后台 job 的 detail 写明预算收口,从而不再与「用户 kill」混淆。
|
||
- **与 `timeoutMs` 正交**:预算先到 → 上面的结构化结果;deadline 先到 → 核心自己的 `TOOL_TIMEOUT` 错误(核心的 timeout 包装器在 `next()` 返回后按自己的 deadline 命中**替换**结果,插件无法也不应抢这条通道)。两者都有 `breached` / `isTornDown` 判定,绝不互相误报。
|
||
- **可在 Settings → Plugins 里改**:预算四个键与裁剪两个键共用同一个宿主 namespace `subagent-roles`(宿主按 namespace 整体服务,第二次注册同名 namespace 会被拒),行 config 仍是 `base` 层。浏览器卡片改为**声明式字段表**驱动,并对每个键做类型化转换(计数以**数字**写入,非法文本折叠为回退值而绝不写出宿主会拒绝的值)。
|
||
- **可观测**:`subagent_roles` 每个角色多一行 `tool-call budget: 30 (role, scope delegation, mode wrap-up, grace 1)`,来源标注角色文件 / 行默认 / 不限;超限日志固定一行 `[subagent-roles] role=… tool-call budget exceeded: used=… limit=… scope=… mode=…`;收尾通知本身持久化在子会话日志里,因此停在哪一次、剩多少都可回放。
|
||
|
||
### 说明
|
||
|
||
- **不改 DSH 核心**。核心确实没有 `maxSteps` / `maxToolCalls` 类旋钮(已 grep 确认),因此护栏全部落在本插件的配置与角色文件格式内。
|
||
- **收口按轮次限流为一次**:`scope: session` 的计数永不复位,因此父代理再次唤醒已超额的 continuable 子代理时会被**再次**停下(第一版把「已上报」与「已收口」合成一个锁,导致只有第一次唤醒会被拦——已修);但被停下那一批里从未启动的调用(核心会为它们补 `tool/call`)不会各自重复一遍停止。首次触发的事实(`usedAtBreach`)不会被后续唤醒改写。
|
||
- **`maxToolCallsHardCap` 的告警按来源措辞**:削顶的是角色文件就点名角色,削顶的是行/设置默认值就说「the row/Settings default asked for …」,不再把继承来的默认值说成角色自己要求的。
|
||
- **`maxToolCallsHardCap` 的削顶告警也进诊断工具**:`subagent_roles` 多一行 `warning: …`,否则它只显示被削后的数字而不说为什么。
|
||
- **超时与预算的次序**:两者独立呈现——预算收口是结构化结果,超时保留核心的 `TOOL_TIMEOUT`。已补「配置了 `timeoutMs` 但预算先到」的用例;反向的窄竞态(预算已开始收口、deadline 在拆卸期间到期导致核心替换结果)已在 README 已知边界里如实写明。
|
||
- **需求 3.1 的「报错信息带上该键需要插件 ≥ x.y」未实现**:旧版插件的未知键报错只能列出它**自己认识**的键,一个不认识 `maxToolCalls` 的版本不可能在报错里提到它——该要求对已发布版本逻辑上不可达。已改为文档层面的版本绑定(README 文件格式表 + 本文件顶部的不兼容提示)。
|
||
- **计数精度与保证边界**:收口是**反应式**的——跨过上限的那次调用已经写进会话日志,插件是在它结束前停下子代理,而不是阻止它开始。保证的是「子代理会停」,计数则是精确的。
|
||
- **`0` 语义**:额度 `0` 表示不限,且 `maxToolCallsHardCap` **不削顶它**。逃生口优先于上限是刻意的:硬上限的用途是削回一个已声明的数字,而不是禁止「不限」。
|
||
- **零成本**:`0`(不限)不会登记任何计数记录,也不参与事件处理;记录表有上限(256 条,**按插入序**淘汰,不是 LRU),且这只是防泄漏兜底:记录会在子会话 `session/disposed`、或委派结算时正常释放(前台/后台在 `finally` 里释放,continuable 靠 `session/disposed`),因此活记录不会被淘汰掉。
|
||
- **`childPromptTrim: 'off'` 的既有语义保留**:它仍会连同 Settings 卡片一起卸掉整个 namespace,因此预算旋钮也一并在 UI 里消失(额度此时只来自角色文件与行 config)。这是原「off 是不可被 UI 翻回来的关闭开关」约定,未改动。
|
||
- 预算**不出现在角色目录文本里**,只有 `subagent_roles` 报告它,因此带预算的角色对提示词体积没有影响。
|
||
|
||
### 测试
|
||
|
||
- 新增 `test/budget.test.js`(41 例):frontmatter 四种字段的合法/拒绝、额度解析与优先级、硬上限削顶与「不削顶 0」、计数语义(恰好等于上限不触发 / 第 `limit+1` 次触发 / 并行各计 1 / 非 `tool/call` 事件不计 / 未登记会话不计)、三种姿态与 grace 边界(`grace: 0` 等价 `interrupt`)、两种 scope 的隔离与 `turn/start` 重置、健壮性(已在拆卸中的委派不误报 / enforce 与 inject 抛错不外泄 / 通知投递失败要告警 / 记录表有界)、结构化结果的形状。
|
||
- `test/delegation.test.js` 扩到 72 例:三条路径端到端(前台断言 run 信号被 abort 而**不是** `interrupt`、continuable 断言 `interrupt` 参数与 ancestor authority、后台断言 job detail)、收尾通知**必须是 plugin 来源**(防回归到冒充人类输入)、`interrupt` 也必须投递那条持久通知、deadline 先到**不得**产生预算结果、**配置了 `timeoutMs` 但预算先到**必须返回预算结果、`session` 作用域的 continuable 在**下一次唤醒**会被再次停下、子会话 `session/disposed` 会释放记录、远程 provider 降级、行默认生效、诊断工具三态来源与削顶告警。
|
||
- `test/parity.test.js` 把「输出 schema」那条从「完全相同」改为「官方三支逐字节相同 + 追加的 budget-stop 支被显式钉死」,并把两处刻意偏离写进该文件的说明。
|
||
- `test/settings.test.js` / `test/client.test.js` 跟着 namespace 扩到六个键:`base` 层必须带上全部键(否则会静默落到 schema 默认而非行 config)、卡片字段表必须与宿主 schema 的键集**完全一致**、计数以数字写入、非法计数文本折叠为回退值。
|
||
- 新增 `test/seam.test.js`:用**真实的 cordis Context + 真实 SessionStore**(无 LLM、无 profile)验证整条护栏所依赖的**唯一假设**——带 `{ global: true }` 的 `session/event` 订阅确实能收到**子会话**已提交的事件(cordis 默认按 context 过滤监听器,写错就会「静默什么都数不到」,正是本插件已经吃过一次的失败形态)。同时钉住「恰好等于上限不触发 / 跨过才触发 / 未登记会话不计 / `turn/start` 重置 delegation 计数」。这两个包是 devDependencies;缺失时该套件按原因 skip 而不是失败。
|
||
|
||
## [0.3.0] - 2026-09-16
|
||
|
||
### 新增
|
||
|
||
- **子代理提示词裁剪**(`childPromptTrim`):核心把大多数工具说明注册成静态文本,只有 `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>` 说明——当 `<name>` 是注册表里**真实存在**的工具、而该 scope 看不到它时丢弃(规则从活的注册表推导,无需维护);
|
||
- 组标签说明(`tool:jobs`、`tool:goal`)——其名字不是工具名,改为在它**自身文本**里按整词匹配已知工具名,全部不可见时才丢弃;
|
||
- `full` 模式额外丢弃 `childPromptTrimNames` 命名的提示词片段(默认 `harness:source`、`app:web-surface`、`ui:deliverable-file-references`、`context:file-reference`),**同一份名单同时匹配 section 与 context**。
|
||
- 两个行配置:`childPromptTrim`(**`full`(默认)** / `tools` / `off`)与 `childPromptTrimNames`。**默认即裁剪**,零配置生效;`off` 是安全阀,`tools` 是"只删死文本、保留 GUI/checkout 那几段"的保守档。
|
||
- **可在 Web 的 Settings → Plugins 里改**:裁剪策略以宿主 settings namespace `subagent-roles` 发布,配一张浏览器侧卡片。行 config 是 namespace 的 `base` 层,卡片把用户层写进 `~/.dsh/settings.yaml`,`applies: live` —— 下一次子代理轮次生效,不用重启。卡片遵循宿主约定:编辑先暂存、Save 才写、每字段可 Reset 回组合默认、并标出被覆盖的字段。
|
||
- 卡片**逐条对照宿主的 `PluginCard`** 自画外壳:可折叠表头(标题/说明/旋转箭头)、未保存徽标、底部 Reset / Discard / Save,沿用 `--dsw-alias-*` design token。宿主只铺一列并派发 slot,"chrome, controls, and copy" 全归插件;画成扁平常展开的盒子会与同排的 bash / agent-loop / subagent 卡片格格不入。
|
||
- 只注册一张卡,不额外占 Settings 导航分组(dshmarket 那样的分组是因为它有一整页浏览界面)。
|
||
- **编辑遵循宿主的卡片约定**:暂存 → Save 才写、Discard 丢草稿、**Reset 只暂存组合默认(写入的是 unset,让字段重新继承部署配置)**、清空保存后自动折叠、保存失败保持展开并保留草稿。
|
||
- **修掉一个已发出的低级错误**:Save 按钮的颜色用了不存在的 `--dsw-alias-label-inverse`,而 `--dsw-alias-brand-primary` 解析出来就是 `label-primary`(深色主题下≈白)→ **深色主题下白字白底,对比度 1.0:1**。现完全照抄宿主 `.save` 规则(`background: label-primary; color: bg-layer-3`,浅色 18.9:1、深色 11.6:1),并加了两道防线:**token 白名单**(只允许主题里真实存在的 `--dsw-alias-*`)与 **Save 配色成对断言**。
|
||
- **文案跟随 Language 设置**:注册 `zh` / `en` 两份同键词典并在注册项上声明 `locale: <namespace>`,由渲染层绑定 `t`(`props.t`);无 locale 服务时依次退回自身绑定与英文词典。此前那版把"中英并列"硬编码进文案,既不跟随语言设置、在两种语言下都别扭,也偏离了生态里 dshmarket / task-board 的做法。
|
||
- 插件因此新增**浏览器半边**:`lib/client.js`(手写,走 `window.__ModuleLoader__` 信封,`react` 取自平台基线模块,**不引入任何构建步骤**,`node --check` 仍能检查它)、`exports["./client"]` 与 `dsh.client.platform: "web"` 声明。宿主侧只注册 namespace 是**不够的**:Plugins 页只为「已服务的 namespace × 注册在该 key 下的卡片」的交集渲染内容,没有卡片就是一个空标签页。
|
||
|
||
### 说明
|
||
|
||
- **只动子代理**:深度为 0 的顶层 agent 提示词逐字节不变(同一次实测里父子两次运行的父提示词逐字节相同,均为 6,431 字符)。真实委派实测:角色子代理提示词 **5,765 → 1,904 字符(−67%)**——该数字是**默认配置**(不带任何 override)跑出来的。
|
||
- 为什么默认连 GUI / harness checkout / 交付链接 / `@` 路径四段一起删:它们对验证者、审查者这类子代理是纯噪声,而父代理随时能在派发提示词里补上任何真正需要的上下文。若某个部署确实需要(例如派子代理改 DSH 本身、或 fork 子代理的回答直接面向 GUI 用户),把 `childPromptTrimNames` 清空即可全部保留。
|
||
- 规则基于**活的工具注册表**,因此 `tools` 模式不依赖任何写死的 section 名;`full` 模式的名单是版本敏感的,核心改名后该段只是不再被裁剪(安全方向),不会报错。
|
||
- 作用于宿主所见**每一个**子代理的组装,而不只是本插件发起的角色子代理——运行时不在子代理上记录角色标记。注册在 agent 自身作用域的工具(`subagent`、`list_agents`)不在全局视图里,其说明永不被裁剪。
|
||
|
||
### 说明(settings 侧)
|
||
|
||
- 没有 settings provider 的部署仍以行 config 为唯一权威;namespace 注册失败(存量配置非法、与另一行撞名、`ctx.get`/`inject` 抛错)只记告警并退回行 config —— 设置出问题不该让插件行倒下,更不该让裁剪失效。
|
||
- 卡片只覆盖默认行的 namespace;用改名 `toolName` 挂的第二行属于 `subagent-roles-<tool>`,没有卡片,直接改 `settings.yaml`。
|
||
- 实测(真实 `dsh-settings-file` 服务 + 真实 headless 委派):行 config 写 `tools`、用户层写 `full` 时,子代理提示词按 `full` 裁剪(3,882 → 1,904 字符);删掉用户层后回到 `tools`(1,627 字符的命名段落保留)。`settings.describe()` 带出组合 base,写入落进 settings 文档,`replace({})` 后重新继承行 config。
|
||
|
||
### 修复(第二轮:独立审查复核后)
|
||
|
||
- **`off` 之前并不生效**:`trimChildPrompt` 只在 `full` 分支上判断模式,R1/R1b 无条件执行,于是 Settings 里的 `off` 与 `tools` **行为完全相同**(实测:两者都丢掉 `tool:workflow`)。现 `off` 直接原样返回,并补了两条回归用例——一条纯函数、一条**驱动真实的 Settings 切换路径**(桩服务现在会 commit 并触发 watch,否则该断言会假通过)。
|
||
- **Reset 后继续编辑会被静默丢弃**:`patch` 从不清除该字段的暂存,Save 于是写 unset、把用户刚输入的值丢掉。现编辑会取消该字段的暂存(`applyEdit` 纯函数 + 回归用例)。
|
||
- **没改动的字段会被写成覆盖值**:用户层里"存在"即"已覆盖",只改模式也会把名单钉住、让以后改部署配置失效。现 `planSave` 只写真正变化的字段(未改动且未暂存则不写)。
|
||
- 补防线:token 白名单**改为从已安装主题派生**(CI 无主题时回退手抄清单)、删掉一条"匹配源码文本"的空洞断言、换成语义级的保存计划用例;状态行补 `role="status"`;重复点 Save 加在飞守卫;"与宿主逐条一致"的说法改为写明两处刻意偏离。
|
||
|
||
### 修复(第一轮)
|
||
|
||
- **实测发现的真 bug**:`context:file-reference`(`@路径` 说明)在当前核心里是以 **section** 注册的(`dsh-file-reference-local` 里 `systemPrompt.section({ name: "context:file-reference" })`),尽管名字带 `context:`。原先按 "section 名单 / context 名单" 分开匹配,导致这一段在真实会话里**没有被裁剪**——是重启后的活体会话验证抓到的(子代理仍带 `@路径`,另外三段已消失)。现在合并为**一份 kind-agnostic 名单**,对两个数组都匹配;回归用例 `a name is dropped wherever it appears — section or context` 钉住它。
|
||
- 记录一条实测踩坑并据以设计规则:直接把 `tool:<x>` 的 `<x>` 当工具名,会把组标签 `tool:jobs` / `tool:goal` 误判为「工具 jobs/goal 不存在」,从而删掉 1,116 字符仍然有效的说明(子代理明明有 `job_output`、`create_goal` 等工具)。规则必须先与注册表已知工具名求交集。
|
||
- 组标签规则的工具名匹配用**整词**而非子串:`already` 里含有 `read`,子串匹配会让一段无关文字被当成"点到了 read 工具"。
|
||
|
||
## [0.2.1] - 2026-09-13
|
||
|
||
本次为**文档与基建补丁**,不含运行期行为变更。
|
||
|
||
### 其他
|
||
|
||
- 新增本文件(`CHANGELOG.md`,中文),追溯 0.1.0 以来的全部版本,并纳入 `files` 随包发布。
|
||
- 发版工作流增加门禁:`CHANGELOG.md` 中没有 `## [<版本号>]` 条目即拒绝发布。发出去就收不回来,所以更新日志条目是发布的前置条件,而不是约定。
|
||
- 两份 README 的发版段落改写为三步(先补日志 → 再 `npm version` 推标签 → 工作流校验后发布),并互加更新日志入口。
|
||
|
||
## [0.2.0] - 2026-09-13
|
||
|
||
### 新增
|
||
|
||
- `timeoutMs` 行配置:前台委派的工具级超时。核心的 timeout policy 会替换 `exec.signal`,而前台路径本就把该 signal 传给 `ctx.subagents.start`,因此子代理随调用一起结束;后台委派立即返回,不受影响。
|
||
- `personaVariables` 行配置:扩充 persona 允许引用的提示词变量。默认仍是 agent loop 注册的 `cwd`、`model`、`provider`;不合核心语法的名字会被过滤。
|
||
- `listToolName` 行配置:诊断工具改名,使同一 profile 可以挂两行。
|
||
- `projectRootTtlMs` 行配置:项目根结果被信任多久后重新向上查找(此前 loader 支持但配置层触达不到)。
|
||
- 支持传输 provider 的 `agentRouteDefaults`:按官方语义合在角色自身绑定之下,且绝不会用来复活一个刚被授权清单拒绝的路由。
|
||
- **同一 profile 可挂两行**:角色目录的 section 名改为由 `toolName` 派生(`<toolName>:catalog`),诊断工具名走 `listToolName`。此前两者都是写死的常量,第二行的注册会抛"already registered"并被静默吞掉 —— 结果是第二行的角色永远不进目录,而插件看起来"半好"。
|
||
- 与官方 delegation 工具(`@deepseek-ai/dsh-tool-subagent`)的**对照测试**:同一形态的宿主桩挂载官方实现,两边用同一个假子代理结果驱动,凡"本应逐字一致"的部分断言相等。该包作为 devDependency 引入。
|
||
|
||
### 变更
|
||
|
||
- **路由改为真预检**:角色绑定的路由在子代理存在之前经 `llm.resolveCallConfig({provider, model, reasoningEffort}, signal)` 解析。角色文件里 `model` 写错、或 `reasoningEffort` 不为 adapter 所认,现在会当场报出可对症修正的错误,而不是从子代理创建深处抛出晦涩失败。旧部署没有该 seam 时降级回 provider 成员检查。
|
||
- **`respectModelSelection` 改为分层读取**:优先采用会话已捕获的策略(与官方委派工具写入的同一个 session projection `subagentModelSelectionPolicy`),没有捕获时才回退实时 `subagent-model-selection` 设置,子会话再回退其父会话。实时设置只用于给新会话播种,因此改动不再追溯影响运行中的会话。
|
||
- 委派日志改报**本次调用实际执行**的模式(此前直接抄 `backgroundMode`,在 `enableRunInBackground: false` + `backgroundMode: continuable` 时报了一个根本不会走的模式),并带上解析后的路由层级。
|
||
|
||
### 说明(settings 侧)
|
||
|
||
- 没有 settings provider 的部署仍以行 config 为唯一权威;namespace 注册失败(存量配置非法、与另一行撞名、`ctx.get`/`inject` 抛错)只记告警并退回行 config —— 设置出问题不该让插件行倒下,更不该让裁剪失效。
|
||
- 卡片只覆盖默认行的 namespace;用改名 `toolName` 挂的第二行属于 `subagent-roles-<tool>`,没有卡片,直接改 `settings.yaml`。
|
||
- 实测(真实 `dsh-settings-file` 服务 + 真实 headless 委派):行 config 写 `tools`、用户层写 `full` 时,子代理提示词按 `full` 裁剪(3,882 → 1,904 字符);删掉用户层后回到 `tools`(1,627 字符的命名段落保留)。`settings.describe()` 带出组合 base,写入落进 settings 文档,`replace({})` 后重新继承行 config。
|
||
|
||
### 修复
|
||
|
||
- `displayName` 撞名(例如项目角色与全局角色同名)时静默取先加载者,现明确告警并列出候选 id。
|
||
- 发现缓存(文件、目录、项目根、已告警诊断)按绝对路径无界增长,宿主常驻时会持续膨胀;现统一 512 条上限并淘汰最旧,结果不受影响。
|
||
- `route.js` 的 `layer` 只产出、无人消费,现接入委派日志。
|
||
- 诊断脚本的 `--project` / `--grep` 缺值会抛 TypeError 或去找字面量 `undefined`,现统一报错退出;裸 flag 不再被当作会话目录。
|
||
|
||
### 其他
|
||
|
||
- CI 增加 `npm run lint`(对 `lib/`、`scripts/`、`test/` 做 `node --check`),零依赖,能抓住不被任何测试 import 的文件的语法错误。
|
||
- `.gitignore` 忽略 `package-lock.json` —— 与本仓库"有意不提交 lockfile"的约定保持一致。
|
||
- README(中英同步):补 `name` frontmatter 字段与上述新增配置项;改写 `respectModelSelection`、`timeoutMs` 两条已知边界;补多行共存与缓存上限说明。
|
||
|
||
## [0.1.2] - 2026-09-13
|
||
|
||
### 说明(settings 侧)
|
||
|
||
- 没有 settings provider 的部署仍以行 config 为唯一权威;namespace 注册失败(存量配置非法、与另一行撞名、`ctx.get`/`inject` 抛错)只记告警并退回行 config —— 设置出问题不该让插件行倒下,更不该让裁剪失效。
|
||
- 卡片只覆盖默认行的 namespace;用改名 `toolName` 挂的第二行属于 `subagent-roles-<tool>`,没有卡片,直接改 `settings.yaml`。
|
||
- 实测(真实 `dsh-settings-file` 服务 + 真实 headless 委派):行 config 写 `tools`、用户层写 `full` 时,子代理提示词按 `full` 裁剪(3,882 → 1,904 字符);删掉用户层后回到 `tools`(1,627 字符的命名段落保留)。`settings.describe()` 带出组合 base,写入落进 settings 文档,`replace({})` 后重新继承行 config。
|
||
|
||
### 修复
|
||
|
||
- **子代理非正常结束时,provider 自己的 `diagnostic` 被整段丢弃**,主代理只拿到一句 `subagent run failed`,既无法自救也无法上报。现随报错一并给出(与官方工具逐字一致),并补上输出块的类型守卫。
|
||
- **fork 型传输 provider 下工具对模型说的是假话**:描述与 `prompt` 参数写死"子代理看不到本对话",而 fork 的子代理其实已带上本会话已完成的轮次。现按 `provider.inheritsParentContext` 切换措辞。
|
||
- **角色文件若是指向 FIFO 或字符设备的符号链接,`readFileSync` 会在提示词组装中同步永久阻塞**(无 signal、无 timeout 可打断),宿主当场冻死。现要求链接解析后仍是普通文件。
|
||
- **`maxBodyBytes` 此前在读完文件之后才比较**,`statSync` 已经给出的 `size` 形同虚设:10 字节的上限照样会把 64 MB 整份读进内存。守卫前移到读取之前,并留出 64 KiB frontmatter 余量。
|
||
- 诊断脚本的归属判定依赖"self-contained"字样,在 fork 措辞下会把自家工具误报为他人注册。
|
||
|
||
### 文档
|
||
|
||
- README / README.zh:说明委派措辞随传输 provider 变化。
|
||
|
||
## [0.1.1] - 2026-09-13
|
||
|
||
### 变更
|
||
|
||
- CI 在 Node.js 20、22、24 上运行测试。
|
||
- 发版改为 npm trusted publishing(OIDC)并附 provenance 证明,仓库不再保存长期 token。
|
||
|
||
## [0.1.0] - 2026-09-13
|
||
|
||
### 新增
|
||
|
||
- 首次发布。文件定义子代理角色:`<项目>/.dsh/roles/<id>.md` 与 `~/.dsh/roles/<id>.md`,项目同名角色优先。
|
||
- YAML frontmatter 承载 `description`、`displayName`、`whenToUse`、`provider`/`model`、`reasoningEffort`、`tools`/`toolFilter`;正文是该子代理的 persona。
|
||
- 紧凑角色目录:一个提示词 section,每个角色一行,仅在委派工具对该 agent 可见且工作区确有角色时渲染。
|
||
- 逐角色工具策略:允许清单 / 拒绝清单,支持 `*`、`?` 通配,按委派时可见的工具名展开;`run_code` 与子代理作用域内注册的工具名有专门处理。
|
||
- 逐角色模型路由,遵守官方 `subagent-model-selection` 授权清单。
|
||
- 可选诊断工具 `subagent_roles`;诊断脚本 `scripts/inspect-session-budget.mjs`。
|
||
|
||
[0.4.3]: https://github.com/troytse/dsh-plugin-subagent-roles/compare/v0.4.2...v0.4.3
|
||
[0.4.2]: https://github.com/troytse/dsh-plugin-subagent-roles/compare/v0.4.1...v0.4.2
|
||
[0.4.1]: https://github.com/troytse/dsh-plugin-subagent-roles/compare/v0.4.0...v0.4.1
|
||
[0.4.0]: https://github.com/troytse/dsh-plugin-subagent-roles/compare/v0.3.0...v0.4.0
|
||
[0.3.0]: https://github.com/troytse/dsh-plugin-subagent-roles/compare/v0.2.1...v0.3.0
|
||
[0.2.1]: https://github.com/troytse/dsh-plugin-subagent-roles/compare/v0.2.0...v0.2.1
|
||
[0.2.0]: https://github.com/troytse/dsh-plugin-subagent-roles/compare/v0.1.2...v0.2.0
|
||
[0.1.2]: https://github.com/troytse/dsh-plugin-subagent-roles/compare/v0.1.1...v0.1.2
|
||
[0.1.1]: https://github.com/troytse/dsh-plugin-subagent-roles/compare/v0.1.0...v0.1.1
|
||
[0.1.0]: https://github.com/troytse/dsh-plugin-subagent-roles/releases/tag/v0.1.0
|