前言¶
用 DeepSeek Harness（DSH）跑重构、补测试、多文件改动时，进程一关或会话一断，模型往往不知道「刚才改到哪、测过没有」。把整段聊天历史再灌回去成本高，也未必能准确还原执行态。@liuhange/dsh-session-recovery 走另一条路：在关键节点把少量事实写成本地 JSONL 检查点，下次启动只扫描未完成会话，续跑时新建会话并注入最后几条进度的精简摘要，而不是做全量会话恢复。
这是什么¶
插件由 liuhange789 维护，npm 包名 @liuhange/dsh-session-recovery（当前资料版本 1.0.0，MIT）。社区目录归类为「记忆」，仓库：GitHub，介绍页：SkillHub 目录。
一句话定位：在工具调用成功的稳定信号处落盘轻量检查点；DSH 重启后列出可恢复候选，由模型通过宿主侧 session_recovery 工具选择续跑或忽略。
检查点如何产生¶
插件不按每次工具调用都记，而是用两类 stepType 作为「可以从此处继续」的信号。
| 触发条件 | stepType |
|---|---|
连续 2 次成功的 write / edit 类工具调用 |
edit-burst |
| 1 次成功的 bash 测试命令（如 npm/pnpm/yarn/bun test、vitest、jest、pytest、go test、cargo test、mvn test、dotnet test 等） | test-pass |
失败调用或其它成功调用会打断 write/edit 的连续计数。设计意图是：单次孤立编辑不足以说明进度，连续落盘或测试通过才更稳定。
每条检查点示例（单行 JSON）：
{
"timestamp": 1762668000000,
"stepType": "edit-burst",
"toolName": "edit_file",
"argSummary": "file_path=src/a.ts | content=...",
"resultStatus": "success"
}
argSummary 最多 200 字，超出截断并加 …；每个会话最多保留 50 条，写入时滑动淘汰最旧记录。写入按会话串行化，临时文件加 rename，避免中断留下半行；损坏的 JSONL 行跳过，不影响其余行。
检查点存在哪里¶
优先级从高到低：
$DSH_RECOVERY_DIR（测试或运维显式覆盖）$DSH_HOME/profiles/web/recovery~/.dsh/profiles/web/recovery（默认布局）
文件名 {sessionId}.jsonl。忽略某会话时写入 {sessionId}.completed.json，后续扫描不再提示。路径规则与 DSH 的 @deepseek-ai/dsh-home-paths 一致，代码不写死机器路径。
恢复流程¶
经过上面的落盘规则，续跑侧步骤如下。
- DSH 启动时扫描 recovery 目录，找出最近 24 小时内仍有新鲜检查点、且未标记完成的会话，并写入启动日志。
- 模型调用
session_recovery，{ "action": "list" }查看候选。 { "action": "resume", "sessionId": "..." }：宿主新建空会话；把最后 3 个检查点的argSummary组装为「上次会话执行到：…。用户选择从此处继续。」；摘要仅在新会话下一次 systemPrompt 组装时注入一次，之后清除；来源会话标记完成。{ "action": "dismiss", "sessionId": "..." }：不恢复，直接标记完成。
摘要总长度不超过 500 字；超长时截断正文但保留固定结尾。
安装与启用¶
先做依赖安装：
npm install @liuhange/dsh-session-recovery
包内通过 cordis.patch.yml 声明 bundle 插入：
- insert:
- id: "@liuhange/dsh-session-recovery"
name: "@liuhange/dsh-session-recovery"
任选其一启用：
- 把该包加入
$DSH_HOME/profiles/web/package.json的dsh.profile.bundles； - 或在
$DSH_HOME/profiles/web/cordis.patch.yml追加上述insert条目。
重启 DSH 生效。卸载时从 bundles 或 patch 中移除对应条目并重启。
如何验证生效¶
下面步骤可与 README 中的验证清单对照执行。
- 在会话内连续两次成功的
write/edit，或执行一次npm test等测试命令。 - 查看
$DSH_HOME/profiles/web/recovery/（默认~/.dsh/profiles/web/recovery/）是否出现{sessionId}.jsonl，且不超过 50 行。 - 重启 DSH，启动日志应出现
session-recovery: startup scan complete，candidates包含该会话。 - 让模型调用
session_recovery的list/resume，确认摘要只含最后 3 条进度且长度 ≤500。
适用场景与注意¶
适合谁： 经常做跨文件编辑、跑测试的长任务；可以接受「新开会话 + 三句进度」而非完整历史回放的用户。
权限与安全： 插件以当前 DSH 进程权限读写本机 recovery 目录。安装前建议阅读 仓库源码 与 MIT 许可证，确认符合你的环境策略。社区目录 SkillHub 为独立站点，与 DeepSeek / 幻方无官方从属关系。
已知限制： 当前版本没有会话列表顶部恢复卡片。Cordis 客户端插件拿到的 ctx 无法读取宿主插件本地文件或调用宿主方法；检查点在宿主文件系统上，因此恢复入口只能是宿主侧 session_recovery 工具。若后续 DSH 提供宿主到客户端的数据通道，可在不改动检查点与摘要逻辑的前提下补展示层。
结尾¶
@liuhange/dsh-session-recovery 用本地 JSONL 检查点和 24 小时内的启动扫描，把「断在哪」收成最多三句、500 字以内的续跑提示，适合 DSH 上需要断点续跑、又不愿全量恢复会话的场景。更多信息见 目录页 与 GitHub 仓库。
