持久智能体 hy-sde/dsh-pi-durable

[!NOTE]
📦 本插件位于 dsh-plugins monorepo —— 问题和 PR 请提到那里。
npm：@hy-sde-org/dsh-pi-durable · @hy-sde-org/dsh-tool-pi-durable

dsh-pi-durable —— 给 DeepSeek Harness 的持久化智能体会话

为 DeepSeek Harness 提供持久化智能体能力，拆成两个独立的 @hy-sde-org 包（不改 harness 源码）：一个由模型驱动的独立会话——有自己的对话记录、自己的编码工具集（通过 CodingTools + NodeExecutionEnv 提供 bash/read/write/edit）、自己的持久化 SQLite 存储，以及自己的模型路由（配置好的 relay）。

| 标识 | 值 |
| 包（引擎） | @hy-sde-org/dsh-pi-durable —— HOST 平面；发布 piDurableAgent 服务：一个 pi-durable Harness，跑在 ~/.dsh/storages/pi-agent.sqlite 上，配 OpenAI 兼容的 relay 服务商（@earendil-works/pi-durable + @earendil-works/pi-ai） |
| 包（工具） | @hy-sde-org/dsh-tool-pi-durable —— 预设行；面向模型的工具（durable_agent_submit、durable_agent_write、durable_agent_status、durable_agent_history、durable_agent_fork、durable_agent_abort）+ durable-agent 提示词段；按名字解析引擎服务 |
| 插件行 id | hy-sde-pi-durable、hy-sde-tool-pi-durable（hy-sde- 前缀避免和任何内置行冲突——加载器 id 重复会导致启动失败） |

基于 franekp 的 pi（MIT） —— 持久化智能体 harness 以未修改的 npm 包形式挂载：@earendil-works/pi-durable（会话、恰好一次提交、在条目处分叉、任务、基于 SQLite 存储后端的文档）、@earendil-works/pi-ai（模型层：createProvider、OpenAI 兼容 API 处理器）、@earendil-works/chord（结构化并发上下文）。本仓库没有内嵌 pi 的任何源码——对 DeepSeek Harness 的适配就是这两个 cordis 行（cordis 插件契约和面向模型的工具注册），不改 harness 源码。见 THIRD-PARTY-NOTICES.md。

为什么

后台运行的生命周期长于启动它的宿主：持久化智能体把对话记录存在自己的持久化 SQLite 存储里，每次提交都会打检查点，进程崩溃后能恢复——宿主重启既不丢会话，也不会忘记某次运行进行到哪一步。提交按 requestId 保证恰好一次，所以崩溃后重试不会把任务跑两遍；会话可以在任意条目处分叉（对话记录继承到分叉点为止），所以分叉出的分支能重试，不用重放历史。编排平面的其余部分跟踪的是谁承诺了什么、谁 需要唤醒，pi-durable 记录一段对话走到了多远：每步检查点、入口处分叉、持久化文档/任务。

前置条件

- Node.js ^22.19.0 || >=24.0.0，且 PATH 中有 npm 和 pnpm；
- 一个 DeepSeek Harness 发行版，带有 0.2.0-rc.2 对等依赖范围 —— @deepseek-ai/cordis ~4.0.4 和 @deepseek-ai/dsh-tools ^0.2.0-rc.2 ——包括标准的 dsh 命令行；
- 生成时：一个 OpenAI 兼容的中转端点（baseUrl），以及由 apiKeyEnv 指定的环境变量（默认 PI_DURABLE_API_KEY）。
没有 baseUrl 时，引擎仍可安装并以只写模式运行；
- 无需其他东西 —— 引擎自带存储介质。

继续之前，先安装 Harness 命令行和 pnpm：

npm install --global @deepseek-ai/dsh pnpm
dsh --version

快速开始

路线 A —— 已发布的 npm 包（推荐）

dsh plugin --profile web add @hy-sde-org/dsh-pi-durable @hy-sde-org/dsh-tool-pi-durable

路线 B —— 从源码（验证此检出或修改插件）

git clone git@github.com:hy-sde/dsh-plugins.git
cd dsh-plugins
pnpm install
PI_DURABLE_TGZ="$(cd dsh-pi-durable/packages/pi-durable && pnpm pack --pack-destination /tmp | tail -n 1)"
TOOL_PI_DURABLE_TGZ="$(cd dsh-pi-durable/packages/tool-pi-durable && pnpm pack --pack-destination /tmp | tail -n 1)"
dsh plugin --profile web add "$PI_DURABLE_TGZ" "$TOOL_PI_DURABLE_TGZ"

pnpm pack 会运行常规的 prepack 构建，生成包含 dist/ 的 tarball。
直接依赖 github:<this-repo> 不包含构建产物，不是受支持的安装方式 —— 始终安装构建好的 tarball（或已发布的包）。

验证组合后的配置

dsh web --dump-config

组合后的树必须显示 hy-sde-pi-durable 行加载 @hy-sde-org/dsh-pi-durable，以及 hy-sde-tool-pi-durable 行加载 @hy-sde-org/dsh-tool-pi-durable。

运行

dsh web

让智能体用 durable_agent_submit 提交一个自包含任务 —— 工具在准入后返回提交 id，运行在后台继续；用 durable_agent_status 轮询，用 durable_agent_history 读取记录，用 durable_agent_fork 在任意条目处分叉，用 durable_agent_abort 停止。未配置中转时，引擎保持只写模式（见配置）。

卸载

dsh plugin --profile web remove @hy-sde-org/dsh-pi-durable
dsh plugin --profile web remove @hy-sde-org/dsh-tool-pi-durable

这个包做什么

每个包声明一个 DSH 包（dsh.bundle.patch → cordis.patch.yml），因此 dsh plugin 会安装两者并应用它们的补丁：

1. 引擎包插入 hy-sde-pi-durable 行 —— HOST 平面的 piDurableAgent 服务。它不从宿主注入任何东西：pi-durable 自带存储介质，所以该行位于宿主平面（一个持久的、进程级服务），而不是在预设内部。
2. 工具包会插入 hy-sde-tool-pi-durable 预设行，其中包含六个 durable_agent_ 工具，以及 durable-agent 提示词段落。没有引擎服务时，这些工具仍会挂载，但每次调用都会明确报错，返回 [pi-durable-unavailable]。挂载预设绝不能因为一个可选宿主而破坏会话创建。

持久化智能体是什么

它是一个独立会话，由模型驱动：有自己的对话记录、自己的编码工具集（通过 CodingTools + NodeExecutionEnv 提供 bash/read/write/edit）、自己的持久化 SQLite 存储，以及自己的模型路由（配置好的 relay）。提交按 requestId 保证恰好一次，每次提交都会生成检查点，进程崩溃后可以恢复，会话可以在任意入口分叉（对话记录继承到分叉点为止）。

分层（互补，零代码重叠）：

- Maka / dsh-graph —— 编排平面：谁承诺了什么、谁需要被唤醒（工作排期、恰好一次认领、唤醒）。
- pi-durable（本插件） —— 单个会话推进到哪一步：逐步检查点、按入口分叉、持久化文档/任务。
- celld（可选底层，此处未使用）—— 写入是否跨进程达到持久化证明（RPO=0）。

配置

引擎行的 config: 默认为空。未设置 baseUrl 时引擎仍会运行：被动写入、文档和任务都能用；durable_agent_submit 会明确报错，返回 [pi-durable-not-configured]。把 baseUrl 指向任意 OpenAI 兼容端点，并设置 apiKeyEnv，即可启用生成。按部署覆盖时，按 id 打补丁修改该行：

- id: hy-sde-pi-durable
config:
path: /var/lib/dsh/pi-agent.sqlite
baseUrl: https://relay.internal/v1
apiKeyEnv: MY_RELAY_KEY
modelId: my-model

工具行也按同样方式按部署禁用（hy-sde-tool-pi-durable → config.enabled: false）。

挂载

这些自包含的行让 dsh plugin add 快速上手就够了；本节是手动替代方案。行文件就是各包的 cordis.patch.yml（dsh.bundle.patch）；plugin_manager install_bundle 会挂载它们。若要手动接线：把引擎行加入宿主组合（它不注入任何东西，只发布服务），把工具行加入预设的 plugins 列表——参见各行李的注释。这些包必须在宿主进程中可解析：发布到 npm，或给 fork 的 apps/cli/package.json 加相对 file: 依赖：

"@hy-sde-org/dsh-pi-durable": "file:../../../dsh-plugins/dsh-pi-durable/packages/pi-durable",
"@hy-sde-org/dsh-tool-pi-durable": "file:../../../dsh-plugins/dsh-pi-durable/packages/tool-pi-durable"

兼容性

| 组件 | 支持的契约 |
| Node.js | ^22.19.0 \|\| >=24.0.0（engines.node） |
| DeepSeek Harness | 0.2.0-rc.2 peer 范围（@deepseek-ai/cordis ~4.0.4、@deepseek-ai/dsh-tools ^0.2.0-rc.2） |
| 上游运行时 | @earendil-works/pi-durable、@earendil-works/pi-ai、@earendil-works/chord 锁定 1.4.0（上游 v1.4.0，schema-v2 SQLite 存储）—— 常规 npm 依赖，未做修改 |
| 存储 | pi-durable 自己管理 SQLite 存储介质 —— 默认 ~/.dsh/storages/pi-agent.sqlite，可通过该行的 path 覆盖 |

上游接缝契约变更需要发布新包版本，并经过契约评审。

开发

pnpm install
pnpm --filter @hy-sde-org/dsh-pi-durable check && pnpm --filter @hy-sde-org/dsh-pi-durable test
pnpm build # container-wide build/check/test via package scripts

引擎测试在真实 SQLite 上跑持久化流程（写入 → 关闭 → 重新打开 → 校验、requestId 去重、fork、状态），不配置模型。

许可证与署名

本包采用 MIT 许可证 —— 见 LICENSE。它挂载的 pi 系列包是第三方 npm 依赖，按各自的 MIT 许可证原样使用（项目 pi，作者 franekp）；本仓库未内置它们的任何源码。上游声明转载于 THIRD-PARTY-NOTICES.md。

本插件是独立可安装的包；harness 仍归其自身项目所有。