dsh-session-repair

English | 中文

DSH Web 会话诊断、可信 checkpoint、pre-repair backup 与安全修复插件。

DSH Web 会话诊断、可信 checkpoint、pre-repair backup 与安全修复插件。

安装

从 npm 安装（推荐）

dsh plugin --profile web add dsh-session-repair

安装后重启 dsh web，再刷新 http://127.0.0.1:3080。

从 GitHub 安装

dsh plugin --profile web add github:Zn-Dk/dsh-session-repair

开发阶段：link 本地源码

cd /root/proj/dsh-proj/dsh-session-repair
pnpm install
pnpm build
dsh plugin --profile web add link:/root/proj/dsh-proj/dsh-session-repair

修改源码后重启现有 dsh web；不要启动替代服务器。若同时运行 deepseek-harness 的 dev:web watcher，Client bundle 可通过现有 HMR 接收更新。

状态分级

诊断报告的 severity 由检查项汇总而来，用于决定是否显示可写修复入口：

| status | case-when | | --- | --- | | healthy | 无 blocked/repairable/warning 检查项。seq-gap 与 live 会话中未闭合的 turn/step 仅作 info 观察项，不抬高等级。 | | warning | 已结束（非 live）的历史存在未闭合的 turn/step 结构，或有其他潜在问题。可读、不提供写入修复。 | | repairable | 存在确定性可修复问题（如空 tool-call ID 链），可提交修复计划。 | | blocked | 会话无法正常展示，且存在无法自动修复的硬冲突（如 ID 冲突、zstd 损坏、会话不匹配）。 |

使用

打开任意会话，在 Chat header 点击「会话体检」。当报告为 repairable 且至少有一条确定性修复计划时，面板会显示「备份并修复」按钮，并列出全部待修 seq 链。点击后先确认目标 seq 和 pre-repair backup，再一次性执行修复并重新校验；歧义、live、文件变化或其他 blocked 状态不会显示可写修复按钮。

面板按钮说明：

• 「刷新诊断」：重新读取当前会话工件并更新报告。
• 「复制报告」：把诊断 JSON 复制到剪贴板。
• 「导出报告」：下载诊断报告 JSON 文件。
• 「恢复上次修复前」：仅当会话为 repairable/blocked 且存在 pre-repair 备份时显示，一键回滚到最近一次修复前的状态。
• 「清空备份」：手动清空 safety 备份。
• 「备份并修复」：仅当报告为 repairable 且存在确定性修复计划时显示。

Agent 工具（模型调用）

插件注册了一个模型可调用工具 dsh_session_repair，它不是用户手动触发，而是由 agent 判断并调用：

• 参数：sessionId（可选；缺省时诊断当前会话）
• 返回：结构化诊断报告（severity / checks / repairPlans / maxSeq / eventCount 等）

典型用法：

1. 在健康会话里对 agent 说：「诊断 session-xxxx 这个 history unavailable 会话」，agent 会调用 dsh_session_repair 并传入旧 sessionId。
2. 在当前会话里对 agent 说：「帮我体检一下当前会话」，agent 调用时不传 sessionId，诊断当前会话。

注意：该工具只做只读诊断，不会执行修复。修复仍需在 header 的「会话体检」面板里点按钮完成。

安全边界

Host 先读取 raw storage，再决定是否调用引擎展示接口。Client 不直接触碰 ~/.dsh，也不能提交任意 JSON patch。修复使用 batchId 与 artifact fingerprint，修复前必生成 pre-repair backup，复验成功后才原子替换。多条独立空 ID 链在一次性批次中修复；歧义、zstd 损坏、文件变化、live/追加中的会话一律不写入。live 会话通过 ctx.get('sessions') / ctx.get('agents') 判定，其未闭合的 turn/step 属正常追加状态，仅记为 info。

插件自有数据位于 ~/.dsh/session-repair/，包括 backups 和 audit。外部 ~/.dsh/backup-sessions-* 目录只作为 legacy 取证与比较来源，默认不自动恢复。

当前实现状态

当前仓库已包含 raw zstd/JSONL 诊断、tool-call ID 检查、确定性 repair plan、checkpoint/pre-repair backup 写入、backup 列表/对比、报告导出、RPC、Agent tool、header 报告面板和随包 Skill。全部端点为已实现或明确返回 not-implemented，不会伪装成功。

发布与收录

• npm：dsh-session-repair
• GitHub：https://github.com/Zn-Dk/dsh-session-repair
• 收录：提交 PR 至 https://github.com/awesome-dsh-plugin/awesome-dsh-plugin（data/plugins/Zn-Dk__dsh-session-repair.yml，category: session）

Skill

随包 Skill 发布在 skills/dsh-session-repair/SKILL.md，由 Host runtime 注册；与插件同名但属于不同注册表，不单独发布、不使用 submodule、不默认软链接。