# dsh-session-integrity

[English](README.md) | [简体中文](README.zh-CN.md)

面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的
Session 完整性诊断与非破坏式恢复插件。

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

## 问题是什么

### Provider 要求的不变量

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

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

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

# 缺少：tool/result c1
```

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

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

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

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

- [上游事故与复现证据](https://github.com/deepseek-ai/deepseek-harness/discussions/3524#discussioncomment-18089302)
- [Core 预防补丁提案（fork）](https://github.com/DON738110198/deepseek-harness/tree/fix/scheduler-failure-tool-results)
- [上游 Discussions 中的插件展示](https://github.com/deepseek-ai/deepseek-harness/discussions/3555)

DeepSeek Harness 目前要求外部贡献通过 Discussions、插件、指南和社区支持进入，而不是
直接提交外部 Pull Request，详见官方[贡献政策](https://github.com/deepseek-ai/deepseek-harness/blob/master/CONTRIBUTING.zh.md)。
在维护者邀请或重新开放 PR 路径之前，fork 会保留完整、可审查的补丁。

## 安全边界

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

## 从 GitHub 安装

```sh
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 创建并打开子会话。当前轮次仍在运行时会拒绝执行；原会话
始终保留，也不会被自动归档。

## 离线检查

```sh
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 操作
- 非单调事件序列

## 开发验证

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