兼容矩阵与升级政策

本文是 DeepSeek Harness 兼容性的单一事实来源，机器可读副本位于 src/config/dsh-compat.ts，配套自动化： scripts/check-dsh-upstream.mjs（上游雷达）与 scripts/probe-dsh-compat.mjs （真实可用性探测，CI compat-probe 任务）。

1. 兼容矩阵

最后验证：2026-08-25（临时 DSH_HOME 安装 + SDK / ACP initialize；ACP task/permission；SDK notify/ask/plan/approval、live session 续接与 restart collision；rc.7 SQLite fail-closed 实测）。

组件	锁定版本	说明
DeepSeek Harness CLI（dsh）	0.1.0-rc.8	SDK / ACP runtime initialize 握手实测通过
@deepseek-ai/dsh-sdk-client	0.1.0-rc.8	package.json 精确锁定（dependencies）
@deepseek-ai/dsh-sdk-jsonrpc-server	0.1.0-rc.8	SDK runtime profile 安装版本（dsh-compat.ts）
@deepseek-ai/dsh-acp	0.1.0-rc.8	ACP runtime profile 安装版本（dsh-compat.ts）
Node.js	>=22.19.0	engines 与 dsh-compat.ts 一致

版本约束规则：

• SDK client 与托管 SDK server / ACP 顶层包精确 pin；本仓库 lockfile 的 SDK peer graph 通过 pnpm.overrides 统一到矩阵版本。override 不会传递给下游，因此每次发现新上游版本都必须重跑 全新 consumer 安装与真实 probe，不能把当前注册表快照当成永久保证。
• 本包不直接依赖 @deepseek-ai/dsh-tools；工具以 raw JSON Schema 注册到宿主 registry， 防止两份模块级 scheduler Symbol。lockfile 不允许混入任何非当前矩阵版本的 dsh core 包。
• dsh-compat.ts 是唯一事实来源；scripts/check-dsh-upstream.mjs 会校验它和 package.json 的 dsh-sdk-client 版本一致，不一致即报错（防漂移）。
• 模型 / provider / 凭据管理走 dsh 官方 settings.yaml + .credentials.yaml 存储协议， 与 SDK 版本无关；SDK/ACP 协议漂移集中在 src/adapters/dsh/，宿主工具 registry 漂移 集中在 src/notify/ 的 raw-schema 注册边界。

2. 升级政策

DeepSeek Harness 处于 developer preview（0.1.0-rc 系列），接口频繁破坏性变更。政策：

1. 优先跟随 stable：latest dist-tag 出现非 rc 稳定版（或 rc 更高版本）时，按第 3 节流程升级。
2. 不在 rc 迭代期盲目追新：除非修复直接影响本 bot 的缺陷，否则保持冻结版本， 等一个被验证的版本再批量对齐。
3. 升级 = 一次受控发布：改版本 → 全量回归 → 更新验证日期 → 发版，而不是原地换依赖。

3. 升级操作手册（Upgrade Runbook）

以从当前 0.1.0-rc.8 升级到 X.Y.Z 为例：

1. 确认上游：pnpm upstream:report（或每日 CI upstream-release-watch 任务）合并检查 GitHub Releases 与 npm 全版本/time/dist-tags；阅读自动创建的 upstream-update Issue，再人工判断 SDK/ACP release notes 中的破坏性变更。
2. 更新单一事实来源：改 src/config/dsh-compat.ts 中 harness / sdkClient / sdkServer / acp（按需），verifiedAt 留空待验证后填写。
3. 同步锁定：把 package.json 的 @deepseek-ai/dsh-sdk-client 改为同一精确版本， 执行 pnpm install 更新锁文件。
4. 全量回归：pnpm release:check（diff 检查 + typecheck + 全部测试 + 构建 + 上游一致性检查 + 真实 dsh 可用性探测）。发布 workflow 在上传任何包之前也会独立执行同一探针， 因而普通 CI 失败时不能绕过兼容门禁继续发布。
5. 单独复跑真实可用性探测：需要定位兼容问题时可运行 pnpm compat:probe（本机），或检查推送后 CI compat-probe 任务： 在临时 DSH_HOME 安装锁定版 dsh，走 SDK / ACP runtime 初始化握手，并用本地 OpenAI-compatible fixture 验证 ACP 文本任务 + plan + one-shot permission 拒绝，以及 SDK 任务、lark_notify / lark_ask_user / lark_request_plan_approval 回调、计划前 bash 强制拒绝 → 计划批准 → rc.8 one-shot approval → 实际执行的顺序、 one-shot 拒绝后 agent 继续替代工具路径、同一 live runtime 的 session 续接，以及关闭重开后 persisted-log collision 的上游边界明确可识别；bridge 的 live-owner 检查必须在调用上游前拒绝 复用失效 binding，并用 transcript 新建 session。
6. 实机回归：重启 profile（dsh --profile <name>，或守护模式下 dsh-lark-bot guardian status 观察接管/交还）后运行 dsh-lark-bot doctor， 确认 dsh profile 中插件装载正常（dsh --profile <name> 内引擎启动）；飞书会话内跑一轮真实任务。
7. 更新验证日期：把 verifiedAt 改为当天，同步本文矩阵表与 README.md「兼容性」章节。
8. 发版：提交、push、打 tag，release 流水线自动发布双包。

4. 自动化

机制	位置	作用
上游雷达	scripts/check-dsh-upstream.mjs + scripts/upstream-release-config.mjs + .github/workflows/dsh-upstream.yml（每日 03:17 UTC + 手动触发）	dsh + dsh-TUI 双源归一；逐版本创建/补充 upstream-update Issue；同时校验本地矩阵、workshop、lockfile 与无直接 dsh-tools 依赖
真实探测	scripts/probe-dsh-compat.mjs + .github/workflows/ci.yml（compat-probe 任务）+ .github/workflows/release.yml（发布前门禁）	临时 DSH_HOME 安装锁定 dsh，验证 rc.7 SQLite 被 rc.8 原样拒绝、SDK / ACP initialize、ACP task/permission/image capability，以及 SDK notify/ask/plan/approval、live resume/restart collision；策略预检、低风险静默放行和真实一次性审批分别计数，并由快速单测对照生产 handler 契约；模拟模型回合设有请求上限，状态断言漂移时快速失败而不耗尽内存
发版前检查	pnpm release:check（= ci:local + 上游一致性 + 真实兼容探针）	本地全量门禁；GitHub Release 在发布包之前重复真实探针

5. 风险披露

• dsh 仍是 pre-release：即使锁定版本，接口仍可能随 patch 行为变化；以 CI 实测为准。
• 探测任务需要网络与 pnpm；失败时优先看 workflow 日志中的 dsh 安装 / 握手错误。
• 发布雷达当前首次基线（2026-08-23 核验）为 dsh 0.1.1-rc.2、dsh-TUI 0.9.0；基线只控制 通知起点，不代表本项目已经兼容该版本。GitHub/npm 单源故障会在 Issue 中标注降级，双源均失败则 workflow 失败且不创建不完整通知。
• rc.8 的已知 session 边界与本次验证限制见 DSH_RC8_AUDIT.md。
• rc.8 不兼容 schema 只属于 opt-in SQLite provider；托管 SDK/ACP 使用 JSONL。自定义 SQLite profile 不自动迁移，必须保留旧 runtime 或自行导出后新建 schema 17 数据库。