sijie-ni-0214/dsh-subagent-error-details

dsh-subagent-error-details

DSH 插件：告诉父 agent 为什么 后台子 agent 失败了。

问题

当后台子 agent 在回合中途死亡时（例如模型 API 429 速率限制），官方结算通知内容如下：

Background subagent  failed before it finished.
Its closing message:

然后就什么都没有了。失败原因被核心 dsh-subagent 丢弃了（notifySettlement 将 stopReason 映射为一句固定的话，并拼接子 agent 最后的部分输出，而对于回合中途死亡的情况，那只是推理 + 工具调用块）。真正的错误记录在子会话的终止 turn/end 事件中——但没有任何东西把它传递给父 agent。

上游讨论：deepseek-harness#4334。

这个插件做什么

1. 作为 host-plane bundle 监听公开的 subagent/end 事件：携带作用域的事件沿作用域链向上冒泡，因此一个实例可以观察到每个父 agent 的委派，无论每个会话运行在哪个预设上。
2. 当 stopReason === "error" 时，通过 sessionPersistence.load()（优先使用实时会话存储，其次使用持久化 JSONL 日志）解析子会话的终止 turn/end 失败详情，并通过子会话头部的 parentSession 和 agent 注册表路由回所属的父 agent。
3. 向父 agent 投递一条简短的伴随消息，镜像核心的 followup/steer 拆分：

Subagent  failed with: RATE_LIMIT: 429 Rate limit exceeded for api_key ... Limit resets at ...

一旦核心自身在官方通知中包含失败文本（上游修复），收件箱监视器会检测到它并自动抑制这条伴随消息。

安装

一条命令，适用于所有 agent 预设——无需编辑组合：

dsh plugin --profile web add dsh-subagent-error-details

（该 CLI 命令是 pnpm 包装器；cd ~/.dsh/profiles/web && pnpm add dsh-subagent-error-details 是等效的）。bundle 补丁将插件挂载到 profile 组合中，该组合在启动时重建，因此重启 dsh 以激活。

新版本发布注意事项（pnpm ≥ 11）：pnpm 11 启用了一项供应链默认设置，会拒绝发布时间不足 24 小时的包版本（minimumReleaseAge）。在发布后的第一天内，安装可能会失败并报 "minimumReleaseAge" 策略错误。要么等待 24 小时，要么仅对这一条命令绕过它：

dsh plugin --profile web add --config.minimumReleaseAge=0 dsh-subagent-error-details

本地开发则从检出目录安装：

cd ~/.dsh/profiles/web
pnpm add file:/path/to/dsh-subagent-error-details
restart dsh

设计保证

- 绝不破坏父循环：每条路径都被包裹；插件 bug 会降级为“无详情”，而不是报错。
- 零注入、惰性服务查找：服务在处理器内部通过 ctx.get 解析，任何缺失都会优雅降级，因此激活永远不会导致会话挂载失败。
- 防御性解析：会话 schema 漂移会优雅降级；遇到未知结构时绝不崩溃。
- 版本契约：dsh.engines.dsh: ">=0.1.1-rc.2 <0.2"，其中 @deepseek-ai/cordis 是唯一的 peer 依赖（harness 包作为其类型的 dev 依赖出现；该插件零运行时依赖）。由于 dsh 是预发布版本且不承诺兼容性，请针对每个新的 dsh rc 重新验证。

已知限制

- 官方通知文本本身保持不变（由核心生成）；此插件添加一条伴随消息。
- 没有会话记录的一次性进程内运行只能报告 stopReason，没有详细信息。
- 持久化读取依赖于会话检查点策略已刷新 turn/end 事件；有界重试覆盖常见窗口。

开发

pnpm install
pnpm build      # tsc
pnpm test       # node --test test/extract.test.mjs

许可证

MIT