会话完整性修复 DON738110198/dsh-session-integrity

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 已经合入该修改。

- 上游事故与复现证据
- Core 预防补丁提案（fork）
- 上游 Discussions 中的插件展示

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 仍处于开发者预览阶段，因此每个版本都需要单独验证兼容性。