前言¶

在 DeepSeek Harness（DSH）里把任务委托给子代理（subagent）时，Harness 会持久化记录「执行意图」，但并不保证副作用类工具恰好执行一次。进程若在「已决定提交」与「把结果写回会话」之间崩溃，重试时若再次执行同一委托，就可能出现重复跑任务、重复写盘或重复调用外部 API 的问题。

社区插件 dsh-plugin-durable-subagent（维护者 Tim-ReJet，目录分类为工作流）在 Harness 侧注册 durable 子代理 provider，并暴露面向模型的 durable_subagent 工具，二者共同驱动 pi-durable-subagents。核心保证是：Harness 在崩溃前已接受的委托，恢复后读回首次结果，而不是再跑一遍。

这是什么¶

一句话：把 DSH 的持久化执行意图与 pi-durable-subagents 的按 id 单次决策接在一起，让子代理委托在崩溃与重试场景下收敛到第一次结果。

DSH 的 session checkpoint 策略写明：策略持久化的是执行意图，而非通用的 exactly-once 语义；有副作用的工具应在 provider 支持时把 exec.callId 作为幂等键转发。pi-durable-subagents 用 --request <id> 接受该键：同一 id 下首次提交被决定一次，之后携带相同内容的每次重试都返回该首次结果。本插件负责把 Harness 侧的 durable intent 与 key 交给 durable orchestrator，形成「先读后写」的状态机：每次尝试先 describe --key <id>，仅在 id 尚未决定时才 run；若进程在决定与上报之间退出，下次尝试会读到已持久化的决定，而不是再次执行。

核心功能¶

Provider 与工具¶

• 在 ctx.subagents 上注册名为 durable 的 provider（默认配置项 provider: durable）。
• 可选注册面向模型的工具（默认 enableTool: true，工具名 durable_subagent）。
• 二者均通过配置的 CLI（默认 pi-durable-subagents）与 orchestrator 交互。

一次调用如何变成 durable request¶

1. Harness 持久化检查该调用的意图，再以 exec.callId 执行工具体。
2. 工具根据调用会话 id 与 exec.callId 推导 request id；同一调用的 replay 会推导出相同 id。
3. 插件读取该 id 的 durable 状态：仅 absent、pending 会进入 run；running、asking 原样返回；sealed、rejected、pruned 为终态。
4. run --request <id> --spec - --cwd <cwd> --json 要么决定请求并返回首次结果，要么报告未决定（退出码 75），此时下一次尝试会再次读状态后再提交。

Provider 路径走 ctx.subagents，请求体 ResolvedSubagentStartRequest 不带 call identity，因此 id 由配置生成：unique 每次 start 一个新 id（不冲突但 replay 不稳定）；content 对相同委托内容 replay 稳定，但同一会话里两次相同委托会 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 所需的 question id 与 revision。
• 插件不会替模型轮询长任务，长委托运行期间不消耗父会话 token。

run 的回复通常是一行短文本；读已完成委托返回其输出，读运行中委托返回状态名。子代理完整 transcript 不会进入父会话历史；工具调用追加在可复用的历史前缀之后，不 rewrite 更早消息。

安装与启用¶

前置条件：pi-durable-subagents 必须在 PATH 中（或通过 command 配置指向的可执行文件）。未安装时每次 start 会直接失败并提示，而不会盲目重试。

插件尚未发布到 npm，需从 GitHub 安装；lib/ 已提交仓库，pnpm 对 git 包会阻止 build script，因此不要依赖 install 时的 prepare，本地改 TypeScript 后需自行 npm run build 刷新 lib/。

npm i -g pi-durable-subagents
dsh plugin --profile web add github:Tim-ReJet/dsh-plugin-durable-subagent

发布后可用更短形式（README 说明 bundle patch 会插入一行 durable-subagent）：

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

package.json 要求 Node >=22.19，许可证 MIT，当前版本 0.1.0。

配置要点¶

典型用法（模型工具）¶

面向模型的调用形态由 durable_subagent 的 action 驱动，例如：

1. action: run 并传入 task（及可选 agent）发起委托；根据返回的 request 与状态决定下一步。
2. 若状态为 running 或 pending，用 action: status 配合 request 地址再读，而不是假设子代理已结束。
3. 若状态为 asking，用返回的 qid、rev 调用 action: answer；需要干预时用 steer、notify、stop 等 action（见 README 参数说明）。

README 未给出完整 JSON 工具调用示例；实际字段以 Harness 暴露的工具 schema 与上述 action 列表为准。

适用场景与注意¶

适合谁： 需要在 DSH 工作流中把子任务交给 pi 系子代理、且担心 Harness 崩溃或 checkpoint 重放导致同一委托执行两次的开发者；目录分类为工作流，适合与 DSH「一切皆插件」的编排方式配合。

运行与权限： 插件随当前 DSH profile 加载，以该进程的用户与权限调用 pi-durable-subagents 和子代理；安装前应在 GitHub 仓库 查看源码与 MIT 许可证，并确认本机 orchestrator 与 agent 定义可信。

已知限制（摘自 README）：

• 通过 dsh plugin add 的 link 安装时，插件从自身目录解析 @deepseek-ai/*，本地需完整依赖闭包；用 npm install --legacy-peer-deps 可能导致 profile 启动失败（缺少 @deepseek-ai/dsh-scope 等）。npm 正式发布安装无此问题。
• cwd 参与提交摘要；从不同工作目录重试会变成 request-conflict，而非返回首次结果。
• Provider 路径无法像工具路径那样基于 call identity 做 replay-stable；精确一次需 Harness 在请求上提供 durable run identity。
• 不支持 continuable 子会话与 Agent Teams 成员关系；无工具过滤、persona、委托深度等扩展；orchestrator 不由插件托管进程生命周期。
• Workflow 层可能整体 status: "done" 而内部调用失败，需到各 call 的 output/error 查看详情。

社区插件目录 SkillHub 条目 与 DeepSeek / 幻方无官方从属关系，仅为社区索引。

结尾¶

dsh-plugin-durable-subagent 把 DSH 的 durable 执行意图和 exec.callId 幂等键接到 pi-durable-subagents，让崩溃后的子代理委托读回第一次结果，而不是重复执行。安装时先全局安装 orchestrator，再用 README 中的 dsh plugin --profile web add 命令启用；长任务用 status/answer 等 action 按需跟进即可。

• 目录页：https://www.skillhub.cn/plugins/Tim-ReJet/dsh-plugin-durable-subagent
• GitHub：https://github.com/Tim-ReJet/dsh-plugin-durable-subagent