持久子代理 Tim-ReJet/dsh-plugin-durable-subagent

dsh-plugin-durable-subagent

为 DeepSeek Harness 提供持久化的子代理执行能力。它在 ctx.subagents 上注册 durable 服务商，同时注册面向模型的 durable_subagent 工具，两者都驱动 pi-durable-subagents。

这对组合只为一件事提供保证：崩溃之前 harness 已接受的委派，会被读回，而不是重新执行。

保证从何而来

DeepSeek Harness 持久化记录执行意图，但不承诺恰好一次的效果。它的会话检查点策略写明了本插件实现的约定：

"The policy durably records execution intent, not generic exactly-once effects. Side-effecting tools should forward exec.callId as an idempotency key when their provider supports one."
— @deepseek-ai/dsh-session-checkpoint-policy

pi-durable-subagents 恰好接受这个键，形式为 --request <id>：同一个 id 下的第一次提交只判定一次，之后任何携带相同内容的重试都拿到第一次的结果。于是 harness 提供持久化意图和这个键，持久化编排器提供唯一的那次判定。

两者的衔接是一个先读后写的状态机。每次尝试都先读 describe --key <id>，只有 id 尚未判定时才提交，所以某个进程如果在判定提交和上报结果之间死掉，留下的持久化判定会被下一次尝试读出来，而不是重新执行。无键测试套件锁定了这条路径；带追踪的 CLI 调用序列是 describe → run → describe，只记录一次执行。

安装

dsh plugin --profile web add dsh-plugin-durable-subagent

bundle 补丁插入一行，durable-subagent。它要求 pi-durable-subagents 在 PATH 上（npm i -g pi-durable-subagents），或者用一个 command 指向它；两者都没有时，每次启动都会失败并给出相应提示，而不是重试。

配置

| 字段 | 默认值 | 含义 |
| provider | durable | 在 ctx.subagents 上的注册名。 |
| command | pi-durable-subagents | 可执行文件，只写 argv[0]。 |
| commandArgs | [] | 子命令之前的参数，用于启动器而非裸可执行文件。 |
| home | — | 每次调用时的 DSA_HOME。 |
| agent | worker | 委派运行时使用的 pi 智能体定义，除非调用中指定了别的。 |
| cwd | harness 进程的工作目录 | 每次调用的工作目录。一次运行的 cwd 是 CLI 参与哈希的内容之一。 |
| idempotency | unique | 服务商如何生成请求 id：unique（每次启动一个）或 content（每次相同的委派一个）。工具始终使用调用标识。 |
| attempts | 3 | 启动失败前的提交尝试次数。 |
| settleTimeoutMs | 600000 | 运行句柄等待持久化判定结果的时间。 |
| pollIntervalMs | 1000 | 等待期间的轮询间隔。 |
| timeoutMs | 120000 | CLI 每次调用的截止时间。 |
| enableTool | true | 注册面向模型的工具。 |
| tool | durable_subagent | 面向模型的工具名。 |

一次调用如何变成持久化请求

1. Harness 先持久化检查调用的意图，然后用 exec.callId 运行工具主体。
2. 工具根据发起调用的会话 id 和 exec.callId 推导出请求 id，因此重放同一次调用会推导出同一个 id。
3. 插件读取该 id 的持久化状态。只有 absent 和 pending 会继续执行 run；running 和 asking 原样返回，sealed、rejected、pruned 是终态。
4. run --request <id> --spec - --cwd <cwd> --json 要么对请求做出裁决，要么返回第一个结果，要么报告 75（尚未裁决）。遇到 75 时，下一次尝试会先重新读取持久化状态，再重新提交。

服务商路径走的是 ctx.subagents，那里拿不到调用身份（ResolvedSubagentStartRequest 不携带任何身份信息）。因此它从配置生成 id：unique 永不冲突，但重放不稳定；content 重放稳定，但同一会话里两次内容相同的委派会以 request-conflict 冲突。只有当各次委派内容互不相同时，才选 content。

模型体验

工具

durable_subagent 接受 action（run、status、answer、steer、notify、stop），以及各 action 所需的 task、agent、to、message、qid、rev。

run 在委派被裁决时就返回，而不是等它的工作完成，并报告 sealed、running、pending 或 asking，附带 request 地址。status 再次读取该地址；asking 状态会带上 answer 所需的问题 id 和修订号。不会替模型做任何轮询，所以长时间委派在运行期间不消耗 token。

Token 影响

run 的回复只有短短一行。读取已完成的委派会返回它的输出；读取运行中的委派会返回一个状态名。子会话的记录不会进入父会话的历史。

KV 缓存影响

工具调用追加在可复用的历史前缀之后。这里不会改写更早的消息。

已知限制与待办工作

- 链接安装的插件从自己的仓库解析导入。 dsh plugin add <path> 会记录一个 link:，Node 顺着符号链接走到插件的真实路径，于是 @deepseek-ai/ 从插件目录解析，绝不会从配置档解析。因此本地安装必须携带完整的依赖闭包：npm install 会解析本包的 harness 对等依赖，而 npm install --legacy-peer-deps 会让 @deepseek-ai/dsh-tools 缺少它声明为对等依赖的九个包，配置档随后启动失败，报 failed to import loader entry durable-subagent (dsh-plugin-durable-subagent): Cannot find package '@deepseek-ai/dsh-scope'。从 npm 发布的安装没有这个问题。
- cwd 是提交摘要的一部分。 从不同工作目录重试会得到 request-conflict，而不是第一次的结果。默认值在 harness 进程的整个生命周期内保持稳定；按会话设置 cwd 目前还没有接上。
- 服务商路径无法做到可重放稳定。 ResolvedSubagentStartRequest 不携带调用标识，所以只有工具路径能做到每次调用一次执行。要让服务商路径也精确，需要在请求上带持久运行标识；这属于 harness 的改动。
- dispose() 会停止运行，但不会等待静默。 编排器是独立进程，自己负责清理，所以运行句柄观察不到子进程退出。
- 不支持可续子进程，也不支持 Agent Teams 成员资格。 prepareContinuable 故意没有实现：spawn_teammate 和冷恢复都需要持久子会话，而这个服务商不创建。
- 没有工具过滤、人设或委派深度。 服务商只上报 outputSchema；请求需要其他能力时，子代理服务会直接报错拒绝，而不是默默忽略。
- outputSchema 校验交给下游。 pi-durable-subagents 在封存前会拿收到的 schema 校验 report，所以封存后的 data 载荷是 schema 合法的；插件不会再次校验。
- 编排器不受监管。 插件既不启动也不重启 pi-durable-subagents；它依赖编排器自身的懒启动、锁和空闲退出。如果放到 ctx.subprocess 下运行，harness 清理时会把它杀掉。
- 失败是按调用计的。 即使工作流里每次调用都失败，它仍会报告 status: "done"，而 output/error 挂在各次调用上。summarize() 从那里读取；只看只读的 status 视图，会把失败的委派当成已完成。

验证

Phase 0 用真实的 pi-durable-subagents 1.0.39 命令行对真实编排器做了验证，并把 bundle 挂载进了真实的 DeepSeek Harness 配置档。

| 检查项 | 结果 |
| npm run typecheck，针对已发布的 @deepseek-ai/dsh-subagent/dsh-tools 0.1.1-rc.2、cordis 4.x、schemastery 3.x | 通过 |
| node --test 无密钥测试套件（fixture 命令行，无 harness、无 pi） | 32 项通过 |
| dsh-plugin-doctor | 10 项通过，0 个错误；剩余项是新仓库的年龄和远程 |
| npm run build + npm pack --dry-run | 产出 lib/.js + lib/types/.d.ts；22 个文件 |
| describe --key <id> --json 的回复结构 | 已对真实命令行确认；载荷固定在 test/fixtures/real-replies.json |
| converge() 对真实命令行，在「崩溃」的调用方留下持久决策之后 | 一次读取，零次提交；重试返回了第一个 wid |
| 同一 id 下重复提交相同内容 | 退出码 0，wid 相同，created: false |
| 同一 id，内容不同 | 退出码 3 request-conflict，回显 state |
| 用 dsh plugin --profile web add 安装 bundle，组合后的树 | 存在 durable-subagent 行及其配置 |
| 挂载插件后的无头启动 | loader 条目激活；运行停在 MISSING_CREDENTIAL，而不是停在插件处 |
| 实时会话中由模型驱动的 durable_subagent 调用 | 端到端验证通过：run → status ×2 → sealed，用 request 寻址 |
| 同一个调用改用 wid 而非 request id 驱动 | 返回 absent；正因如此，渲染现在以 request= 开头 |
| 真实的 pi 1.0.2 子进程完成一次模型调用 | 未验证：这个一次性 pi 没有水合模型目录，报 Unknown provider: unknown |
| 决策与执行之间编排器崩溃 | 未验证；测试的崩溃窗口属于调用方 |

Phase 0 证据

对真实命令行提交同一个 id 两次：

$ pi-durable-subagents run --request spike-1 --spec spec.json --json
{"request":"spike-1","wid":"01M4THR3CMT54R65BASRA9QX3V","created":true,"spec_digest":"3a8fdf42…"}
$ pi-durable-subagents run --request spike-1 --spec spec.json --json
{"request":"spike-1","wid":"01M4THR3CMT54R65BASRA9QX3V","created":false,"spec_digest":"3a8fdf42…"}

在真实命令行上驱动本插件自己的 converge()，中间隔一层 shim，记录每次调用；第一个调用方提交后随即「死亡」，没有读取回复：

CLI invocations: run -> describe -> describe -> run -> describe -> describe -> run
converge after the crash: running (wid 01M4THR3CMT54R65BASRA9QX3V)

三次 run 调用分别来自崩溃的调用方、一次新 id 收敛，以及一次故意制造冲突的探测。对于已经定案的 id，converge 一次都没有发起。

一个工作流，唯一一次调用失败了，却报告 status: "done"：

$ pi-durable-subagents describe --key spike-1 --json
{"state":"sealed","status":"done","calls":[{"status":"failed","ok":false,"error":"lost ×5","output":""}]}

正因如此，summarize() 按每次调用读取成功状态。这次运行没花什么成本：usage 输入 0、输出 0。

Phase 0b 证据

一个真实的 DeepSeek Harness 无头会话，挂载了 bundle，PATH 上有真实的 pi-durable-subagents 1.0.39 命令行，被要求委派一个任务。它自己的报告：

- Request id: df9631829b6-call-00-xnXLGCeOhmS8M4PETs0m0219-e847ef97bab53919
- Final state: sealed
- Succeeded: No — the delegation failed.
- Output / error (verbatim):
sealed: request=df9631829b6-…-e847ef97bab53919 (wid 01M4TJKGB6Q3ZX7XNCKW5DX2PG) — failed: lost ×5; last error: Unknown provider: unknown 这次运行有三点收获。句柄可寻址：模型从渲染结果里读到了 request=，每次 status 调用都能解析成功；而第一次尝试只渲染了 wid，四次都得到 absent。调用级失败映射在生产环境里生效：某个工作流唯一的调用挂掉了，上报的是失败，并带上子调用自己的错误，而不是一次输出为空的已完成委派。请求 id 现在也符合语法了——工具调用 id 是 call_00_zkMrBAcVpchoWOd2TzA93108，其中的下划线不在 [A-Za-z0-9][A-Za-z0-9._:-] 范围内。

子调用本身从未连上模型：临时安装的 pi 1.0.2 没有可用的模型目录，所以它以 unknown/unknown 启动。从 harness 凭据存储提供 DEEPSEEK_API_KEY 之前和之后，pi auth check --provider deepseek 都报 invalid_state，这是那次全新安装自身的性质，跟本插件无关。

License

MIT。pi-durable-subagents 采用 MIT，© purboo，并改编了 pi-subagents（MIT，© Nico Bailon）的部分内容；本插件既未内嵌也未再分发该仓库。DeepSeek Harness 采用 MIT。