前言¶

在 DeepSeek Harness（DSH）里跑长任务时，网络抖动、上游超时、5xx、进程重启都会打断当前轮次。会话日志里往往还留着完整对话，但 Agent 重启后仍需要一份紧凑、结构化的「进行到哪了」：目标、当前步骤、已完成的工具调用、结果不确定的调用、待办，以及最后可见的输出。单靠翻历史消息重建上下文，既慢也容易漏状态。

下面介绍社区插件 dsh-task-checkpoint-guard（维护者 jlnkx5200-beep，分类：工作流）。它在本地持久化结构化检查点，对可恢复的传输类失败做分类，并在策略允许时用有界探测或延迟后重新武装 Goal，而不是无差别自动重试。

这是什么¶

dsh-task-checkpoint-guard 的定位是：Durable task checkpoints and safe, bounded recovery for DeepSeek Harness agents——为 DSH Agent 提供可 durable 的任务检查点，以及在明确边界内的安全恢复。

当前版本 v0.1.0，在 DSH 0.2.1-rc.3、Windows 11、Node.js 24.21.0 环境下开发与测试；package.json 中 engines.dsh 声明接受范围为 >=0.2.1-rc.3 <0.3.0，其他 DSH 版本未宣称已测。许可证为 MIT。插件不保存隐藏 chain-of-thought，也不上传任务记录。

核心功能¶

检查点写入¶

每个活跃 DSH 会话持久化结构化检查点，形式为 JSON + Markdown + 会话指针。
记录原始人类指令、Goal 目标/修订号、待办、轮次/步骤位置、工具生命周期，以及有长度上限的可见结果。
不写入模型推理正文，仅保留 reasoning 块/字符计数。
写入前对凭证形态字符串和疑似密钥的 JSON 字段做脱敏。
采用同目录临时文件、fsync、重命名原子写入；保留 <file>.previous 作为上一份有效副本。

默认目录为 $DSH_HOME/task-checkpoints；未设置 DSH_HOME 时在 Windows 上为 %USERPROFILE%\.dsh\task-checkpoints。

失败分类与 fail-closed 恢复¶

将失败分为 NETWORK、TIMEOUT、SERVICE、AUTH_OR_REQUEST、ABORTED、UNKNOWN 等类型，并采用 fail-closed 策略，例如：

用户取消、鉴权/请求错误、max-token 停止、部分流式输出后，不自动恢复；
工具调用尚无 durable 结果时，不自动恢复；
对已结束或结果未知的工具调用，不盲目重试。

三种 recoveryMode¶

off：仅写检查点（默认）；
probe：重新武装 Goal 前做有界 HTTP(S) 就绪探测；
deferred：显式配置的延迟，不发起出站探测。

恢复时会用 compare-and-set 校验 Goal 修订号，重新武装已 disarm 的活跃 Goal，并注入一条结构化上下文消息。可选在恢复后第一轮拒绝指纹完全相同的重复工具调用，之后 guard 自动清除。

明确不做的事（使用前要清楚）¶

不重建隐藏 chain-of-thought；恢复依赖可见消息、durable 执行事实与结构化状态。
不上传、不同步检查点；除用户配置的就绪探测外，无其他出站请求。
不保证工具幂等；重复 guard 只覆盖恢复首轮的完全重复指纹。
不自行开启模型轮次；自动续跑需要 DSH 的 goals 与 goal-round-driver。无 driver 时 Goal 可被 re-arm 且上下文入队，但未必有新 turn。
可选通过公开 ctx.sessionQuery 补齐插件挂载前或检查点滞后于 live log 时缺失的会话事件（需宿主提供该能力）。

宿主依赖¶

Node.js： ^22.19.0 或 >=24.0.0（与 DSH 0.2.1-rc.3 声明范围一致）。
必需服务： agents、sessions。
可选： goals + goal-round-driver（自动 Goal 续跑）、credentials（探测鉴权）、sessionQuery（事件回放）。
运行时 无 npm 依赖。

安装与启用¶

先在仓库根目录打包发布 tarball：

npm pack

安装到实际使用的 DSH profile：

dsh plugin --profile <profile> add ./dsh-task-checkpoint-guard-0.1.0.tgz

若使用源码目录，可直接：

dsh plugin --profile <profile> add ./dsh-task-checkpoint-guard

确认 profile 合成结果中包含该 bundle：

dsh --profile <profile> --dump-config

按 profile 正常启动（标准 Web profile 也可用 dsh web）：

dsh --profile <profile>

卸载（不删除已写入的检查点文件，需自行删目录）：

dsh plugin --profile <profile> remove dsh-task-checkpoint-guard

典型用法¶

验证检查点是否落盘¶

任务跑过后查看本地文件。PowerShell 示例：

Get-ChildItem "$HOME\.dsh\task-checkpoints" -Recurse
Get-Content "$HOME\.dsh\task-checkpoints\tasks\<task-id>.md"

POSIX shell：

find "${DSH_HOME:-$HOME/.dsh}/task-checkpoints" -maxdepth 3 -type f

通过 cordis.patch 覆盖配置¶

Bundle 默认 recoveryMode: off、启用本地检查点、重复工具 guard 限于恢复首轮。要在 profile 的 cordis.patch.yml 中整行重写该 bundle 的 config（后 patch 会替换整行配置）。示例片段（占位 URL 与凭证名需换成你的环境）：

- id: task-checkpoint-guard
  name: dsh-task-checkpoint-guard
  config:
    checkpointRoot: ~/.dsh/task-checkpoints
    recoveryMode: probe
    probeUrl: https://api.example.test/v1/models
    probeMethod: GET
    probeAuth: bearer
    credentialRef: EXAMPLE_API_KEY
    probeExpectedStatuses: [200]
    probeTimeoutMs: 5000
    maxProbeAttempts: 5
    initialProbeDelayMs: 1000
    maxProbeDelayMs: 30000
    jitterRatio: 0.2
    maxAutoResumes: 3
    providerFilter: null
    duplicateToolPolicy: deny-on-recovery
    maxToolHistory: 80
    maxToolResultChars: 2000
    maxToolArgumentChars: 1000
    maxRecoveryContextChars: 16000
    persistDebounceMs: 100
    reconstructFromSessionQuery: true

credentialRef 指向 DSH credentials 服务中的密钥名，值不会写入检查点。完整参数语义见仓库 docs/configuration.md。

适用场景与注意¶

适合谁： 需要在 DSH 上跑较长 Goal/多步工具链、且希望在进程或链路中断后保留结构化进度、并在可控条件下尝试续跑的工作流场景。默认 recoveryMode: off 时，可先只当「本地任务账本 + 人工决策是否继续」使用；需要自动 re-arm 时再打开 probe 或 deferred，并确保 profile 具备 goal-round-driver。

安全与权限： 插件以当前 dsh 进程权限运行，读写本地检查点目录；启用 probe 时会向配置的 HTTP(S) 端点发起探测。安装前应阅读源码与 MIT 许可证，确认 cordis.patch.yml 与 docs/ 中的行为符合你的合规要求。DSH 生态强调「一切皆插件」；社区目录站点与 DeepSeek / 幻方无官方从属关系，本文介绍的是第三方仓库 jlnkx5200-beep/dsh-task-checkpoint-guard，而非官方应用商店条目。

兼容： 未承诺适配每一个 DSH 发行版；以 engines.dsh 与 README 中的测试说明为准。

结尾¶

经过上面的步骤，你可以在本机为 DSH 会话留下 JSON/Markdown 检查点，在传输类失败分类清晰的前提下，用 fail-closed 与有界探测避免盲目重试。目录页与源码：

社区目录：https://www.skillhub.cn/plugins/jlnkx5200-beep/dsh-task-checkpoint-guard
GitHub：https://github.com/jlnkx5200-beep/dsh-task-checkpoint-guard

dsh-task-checkpoint-guard：DSH 长任务的本地检查点与有界恢复

前言¶

这是什么¶

核心功能¶

检查点写入¶

失败分类与 fail-closed 恢复¶

三种 recoveryMode¶

明确不做的事（使用前要清楚）¶

宿主依赖¶

安装与启用¶

典型用法¶

验证检查点是否落盘¶

通过 cordis.patch 覆盖配置¶

适用场景与注意¶

结尾¶

精选优惠券

dsh-task-checkpoint-guard：DSH 长任务的本地检查点与有界恢复

前言¶

这是什么¶

核心功能¶

检查点写入¶

失败分类与 fail-closed 恢复¶

三种 recoveryMode¶

明确不做的事（使用前要清楚）¶

宿主依赖¶

安装与启用¶

典型用法¶

验证检查点是否落盘¶

通过 cordis.patch 覆盖配置¶

适用场景与注意¶

结尾¶

精选优惠券

相关文章