# DSH 版本兼容性

本插件依赖 DSH 的四个扩展点：

- `tools/pre-execute`
- `tools/post-execute`（含 `additionalContexts`）
- `agent/pre-step`
- `session/event`（`todo/write` / `turn/start` / `turn/end`）

以及 `todo_write` 的 `{ content, status }` 整表替换语义。

## 2026-10-18 版本审计

| 项目 | 版本 |
|---|---|
| 当前桌面端 | `0.2.1-rc.2`（`runtime.json` / `app.asar`；用户已升级） |
| npm `latest` | `0.2.0-rc.2` |
| npm `next` | `0.2.1-rc.2` |
| npm `alpha` | `0.2.1-alpha.5` |
| 本机全局 CLI | `@deepseek-ai/dsh` `0.1.5-rc.2`（旧） |

结论：桌面端现在使用 npm `next`（`0.2.1-rc.2`），比 `latest` 更新。插件 1.0.0 已在该运行时完成 live 冒烟：

- 只含 `pending` 的 `todo_write` 成功，并收到即时 notice；
- 设为 `in_progress` 后连续 5 次顶层工具调用，收到停滞 notice；
- 两轮均无 `format v4` 错误；无需改代码。

## 0.2.0-rc.2 vs 0.2.1-rc.2 的关键差异

审计方法：从 npm 拉取 `@deepseek-ai/dsh-session`、`dsh-tools`、`dsh-agent`、`dsh-agent-loop`、`dsh-tool-todo`、`dsh-session-format` 的 `0.2.1-rc.2` 包，检查 `.d.ts` 与实现。

| 项 | 0.2.0-rc.2 | 0.2.1-rc.2 | 对本插件的影响 |
|---|---|---|---|
| `SESSION_FORMAT_VERSION` | 4 | **4** | 无；继续使用 v4 producer-owned source |
| `tools/post-execute` | 有 | 有 | 无 |
| `additionalContexts` | 有 | 有 | 无 |
| `agent/pre-step` | 有 | 有 | 无 |
| `session/event` | 有 | 有 | 无 |
| `todo_write` | 整表替换、`pending/in_progress/completed` | 相同 | 无 |
| `todo/write` 投影 | 有 | 有 | 无 |

因此插件在 `0.2.0-rc.2` 与 `0.2.1-rc.2` 上使用同一套 hook 和 v4 source kind 即可。

## 跨版本 source kind

Session format v4（DSH 0.1.7-rc.1 起）退役了旧的 plugin source 包装：

```js
// v3
{ kind: 'plugin', plugin: 'task-guard', form: 'notice', summary: '...' }

// v4
{ kind: 'plugin:task-guard', form: 'notice', summary: '...' }
```

插件默认 `sourceKind: 'auto'`，通过 `session.header.version` 判断：

- `version < 4` → v3 形状
- `version >= 4` → v4 形状

也可以用配置强制：

```yaml
sourceKind: v3   # 或 v4；默认 auto
```

这使同一个构建同时支持：

| DSH | Session format | 状态 |
|---|---|---|
| `0.1.5-rc.2` | v3 | ✅ 自动选择 v3 source |
| `0.2.0-rc.2` | v4 | ✅ 已 live 验证 |
| `0.2.1-rc.2` | v4 | ✅ 当前桌面端；包类型审计 + live 冒烟 |

## 兼容性验证

```powershell
cd <repo>
pnpm check
```

当前 18 个测试通过，其中跨版本相关：

- 默认（无 header）→ v4 source；
- `session.header.version = 3` → `{ kind: 'plugin', plugin: 'task-guard' }`；
- 显式 `sourceKind: 'v4'` 强制 v4；
- 真实 Cordis Context 下的 v3/v4 waterfall 测试；
- `sourceKind` 非法值在加载时 fail-loud。

## 自动检测更新

仓库建议用一个定时任务周期性检查：

```powershell
npm view @deepseek-ai/dsh dist-tags --json --registry=https://registry.npmjs.org/
```

同时看 [GitHub releases](https://github.com/deepseek-ai/deepseek-harness/releases) 与桌面端 `runtime.json`。发现新版本后，按本文件的方法拉取对应核心包、对比上面那张表，再决定是否需要改 hook/source kind。仓库固定每周日运行一次本机检查任务；基准版本记录在 [docs/dsh-version-baseline.json](./dsh-version-baseline.json)。