dsh-session-integrity

面向 DeepSeek Harness 的 Session 完整性诊断与非破坏式恢复插件。

一次内部调度异常，就可能把普通工具失败变成持久化 transcript 缺陷，使之后每次模型请求都在模型开始回答之前失败。

问题是什么

Provider 要求的不变量

assistant 消息请求工具后，每个 Provider 可见的 tool call id 都必须紧跟一个对应的 tool result。普通工具执行失败并不会破坏对话，因为 Harness 会把错误序列化为结果，模型仍然能够看到错误并决定下一步。

这里的问题不同：Harness 已经持久化 assistant 请求和工具执行开始事件，但没有结果进入模型可见的 Session surface。

assistant/message  tool-call c1
tool/call          c1
scheduler.prepare  抛出异常
step/end
turn/end           error

# 缺少：tool/result c1

下一次请求会回放这个没有结果的 assistant 工具调用。DeepSeek 在模型推理开始前直接拒绝请求，典型协议错误是：

An assistant message with 'tool_calls' must be followed by tool messages
responding to each 'tool_call_id'.

因此，再发送一条用户消息也不能恢复 Session。非法历史已经被持久化，之后每轮都会再次发送同一个缺口。

sequenceDiagram
    participant M as 模型
    participant H as Harness
    participant S as 工具调度器
    participant P as Provider
    M-->>H: assistant 请求工具 c1
    H->>H: 持久化 assistant/message 与 tool/call
    H->>S: prepare(c1)
    S--xH: 抛出异常
    H->>H: 持久化 turn/end(error)，没有 tool/result
    H->>P: 后续请求回放未配对的 c1
    P--xH: 推理前返回 HTTP 400

为什么一次错误会永久污染 Session

这个事故包含三个相互独立的层次：

1. 触发原因： prepare() 或其他内部调度边界抛出异常。运行时包重复安装造成 Symbol 不一致可以触发它，但这只是可能原因之一。 2. 持久化缺陷： tool/call 已经记录，而唯一追加 tool/result 的路径没有执行。 3. 回放放大： 本轮仍然写入了 turn/end，所以只处理开放尾部的崩溃恢复逻辑不会修复它。之后每次 Provider 请求都会携带相同的未配对调用并再次失败。

所以，结构性缺陷并不依赖最初的具体触发原因。脆弱区间内的任何异常都有可能污染一个原本健康的 Session。

为什么不能统一补一个普通错误后盲目重试

如果异常发生在 dispatch 之前，工具确定没有运行，仍有需要时可以安全重试。如果 dispatch 已经开始但结果尚未持久提交，外部副作用可能已经发生。此时必须把结果标记为未知，并在重试写入、支付、部署或其他非幂等操作前核验外部状态。

这个项目做什么

Cordis 插件在加载时及每次 turn/end 后检查 live Sessions。
离线 CLI 可以在不发起模型请求的情况下检查导出的 JSON 或未压缩 JSONL。
区分 Provider 当前可见的缺陷与已经被 compaction 隐藏的原始执行缺口。
报告只使用哈希引用，不包含提示词、工具参数或工具结果。
恢复规划器会找到仍可安全发送给 Provider 的最近完整轮次。
Web 插件为历史 assistant 轮次增加“从这里继续”，创建并打开 fork，同时保留原

Session。

分析器与规划器保持只读；恢复调用 Harness 的公开 fork 能力，而不是改写持久历史。

该问题已经在干净的 dsh-v0.1.0-rc.8 / master 基线上复现：未修复的回归测试记录了一个 tool/call 和零个 tool/result。fork 中经过测试的预防补丁会用 TOOL_SCHEDULER_FAILED_BEFORE_DISPATCH 闭合尚未分发的调用，用 TOOL_SCHEDULER_OUTCOME_UNKNOWN 闭合已经分发的调用，同时不会重新执行 dispatch 或 finalizer。它是供上游审查的提案，并不表示 DeepSeek 已经合入该修改。

DeepSeek Harness 目前要求外部贡献通过 Discussions、插件、指南和社区支持进入，而不是直接提交外部 Pull Request，详见官方贡献政策。在维护者邀请或重新开放 PR 路径之前，fork 会保留完整、可审查的补丁。

安全边界

不修改、修复、删除或替换源 Session 中的任何 event。
恢复通过 Harness fork API 创建子 Session，不重试工具，也不声称外部副作用已回滚。
不输出提示词、工具参数、工具结果、原始 Session id 或原始 call id。
区分 Provider 当前可见的致命缺陷与已被 compaction 隐藏的执行日志警告。
不提供硬删除。当前公开持久化服务没有跨后端统一的 Session 删除操作。

从 GitHub 安装

dsh plugin --profile web add github:DON738110198/dsh-session-integrity#v0.2.1
dsh --profile web --dump-config
dsh --profile web

包内直接提供构建完成的 JavaScript，无须在安装时运行构建脚本。Host 插件加载时扫描当前 live Sessions，并在每个 turn/end 后重新检查；同一缺陷只告警一次。

在 Web UI 中，后面仍有对话记录的已完成 assistant 消息会显示一个分支图标。点击后通过官方 Session fork API 创建并打开子会话。当前轮次仍在运行时会拒绝执行；原会话始终保留，也不会被自动归档。

离线检查

dsh plugin --profile web exec dsh-session-integrity ./session.jsonl
dsh plugin --profile web exec dsh-session-integrity ./session.jsonl --json > integrity-report.json
dsh plugin --profile web exec dsh-session-integrity recover ./session.jsonl --json > recovery-plan.json
dsh plugin --profile web exec dsh-session-integrity recover ./session.jsonl --at 42

如果从仓库 checkout 运行，请使用 node ./cli.js ./session.jsonl。该包尚未发布到 npm，因此文档不会把裸 npx dsh-session-integrity 写成可用安装路径。

recover 把 --at 解释为 Session event 锚点：先检查该锚点所在的完整轮次，如果该前缀会阻断 Provider，则继续向前寻找最近的安全轮次。输出只是计划，不修改文件或 live Session。

scan 的退出码：0 表示没有阻断 Provider 的缺陷，1 表示输入错误，2 表示发现严重缺陷。recover 中，0 表示找到安全 fork 边界，2 表示应新建 Session。工具不会自行解码 Zstandard，请使用 Harness 导出文件或未压缩 JSONL。

为什么恢复采用 fork，而不是原地回滚

Harness Session 是 append-only event log。删除一条可见消息时，也可能一并删除工具调用、请求头、compaction 来源或外部副作用的证据。因此，“从这里继续”会从一个完整轮次创建新的会话谱系，而不是假装后续事件从未发生。

永久删除属于另一项 Core 能力：它必须同时协调 live agent、JSONL 与 SQLite 后端、 Workspace 记账、projection、缓存索引和附件保留策略。单纯增加前端删除按钮或直接删除文件不能满足这个契约，所以本插件刻意不提供硬删除。

当前检查项

assistant 工具请求缺失对应的模型可见工具结果
意外或 call id 不匹配的工具结果
重复的 assistant call id 或执行事件
已退出 surface 但仍未完成的 tool/call
非法 surface 操作
非单调事件序列

开发验证

npm test
npm run check
npm run pack:check

测试覆盖健康与受污染的恢复边界、浏览器 fork 编排、prepare() 异常、合成取消、开放崩溃尾部、被 compaction 隐藏的缺口、packed JSONL、告警去重和 CLI 退出码。

0.2.x 针对 DeepSeek Harness dsh-v0.1.0-rc.8。Harness 仍处于开发者预览阶段，因此每个版本都需要单独验证兼容性。

来源信息

安装

检查来源文件