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,记录绑定机制、存量成员缺口与「成员自省不可全信」的
台架教训。
42 KiB
42 KiB
更新日志
本文件记录 dsh-plugin-subagent-roles 的所有重要变更。
格式参考 Keep a Changelog,版本号遵循语义化版本。
[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-prefixsection,order 取DEPLOYMENT_PERSONA_PREFIX,插值语义不变; - toolFilter 仍按父上下文可见工具展开后调用子上下文的
tools.restrict()。
- persona 仍是
- 确定性关联:
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 --test331 项全过;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 --test345 项全过(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 页按包名或绝对路径安装;并说明
desktopprofile 由 App 独占、dsh plugin --profile desktop …会被明确拒绝,Plugins 页才是受支持通道;宿主行即时加载、客户端界面需刷新一次页面;0.1.5 与 0.2.0 两条依赖线都支持及其设置通道差异。
验证
node --test338 项全过(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 projectionsubagentModelSelectionPolicy),没有捕获时才回退实时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(中英同步):补
namefrontmatter 字段与上述新增配置项;改写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。