# dsh 0.1.5-rc.1 适配与版本合并评估

> 历史快照：本文记录 2026-09-10 的调查结论与当时的仓库状态，不是现行兼容说明；其中的版本号、HEAD、发布状态和“尚未完成”的判断都停留在该时点。现行支持边界见 [README](../README.zh-CN.md) 和 [DESIGN](../DESIGN.md)。

核对日期：2026-09-10。仓库基线：main `e6e23bf`；上游固定标签：`dsh-v0.1.5-rc.1`。

## 结论

可以将本次适配与已有 0.8.6 候选发布线合并，建议下一版为 **0.8.6-rc.2**。无需退回 0.8.4 重做此前适配，也没有待合入的 0.8.6 分支：PR #4 已合入 main，当前远端开放 PR 数为 0。

但不应覆盖 v0.8.6-rc.1，也不建议现在直接晋升 0.8.6 正式版。rc.1 已于 2026-09-07 发布至 GitHub Pre-release 和 npm next；新宿主上的完整安装、Web 启动和浏览器联调尚未验证。当前评估只能确认类型、构建、现有组件测试和 Cordis 组合测试兼容，还没有完成全部发布前检查。

## 版本盘点

GitHub API 全量标签与本地一致：34 个版本标签，另有移动标签 latest。GitHub Release 共 32 个；v0.5.1、v0.5.2 有标签但无对应 Release。npm 共 8 个已发布版本。

| 范围 | Git 版本标签（省略 v 前缀） |
| --- | --- |
| 0.2–0.4 | 0.2.0、0.2.1、0.2.2、0.3.0、0.4.0 |
| 0.5 | 0.5.0、0.5.1、0.5.2、0.5.3、0.5.4、0.5.6、0.5.7、0.5.8、0.5.9 |
| 0.6–0.7 | 0.6.0、0.6.1、0.6.2、0.6.3、0.7.0、0.7.1、0.7.2 |
| 0.8 | 0.8.0、0.8.1、0.8.2-rc.1 至 rc.5、0.8.2、0.8.3-rc.1、0.8.3、0.8.4-rc.1、0.8.4、0.8.6-rc.1 |

没有查到 0.8.5、0.8.6 正式版或 0.8.6-rc.2；版本号缺口无需补发。

| 发布面 | 实际状态 |
| --- | --- |
| npm latest / Git latest | 0.8.4 / `00a699f`；README 对应 dsh 0.1.1-rc.2 |
| npm next | 0.8.6-rc.1；开发及 CI 对应 dsh 0.1.2-rc.1 |
| v0.8.6-rc.1 | 指向提交 `586ab980f1dd6bb12d429bba99e853e4c415b788`；GitHub Pre-release |
| main | `e6e23bf`；比 RC 多一次版本兼容说明文档提交；package.json 仍为 0.8.6-rc.1 |
| npm 历史 | 0.8.2-rc.4、0.8.2-rc.5、0.8.2、0.8.3-rc.1、0.8.3、0.8.4-rc.1、0.8.4、0.8.6-rc.1 |
| 上游 npm latest / next | 两者均为 0.1.5-rc.1；不能把上游 latest 误认为无预发布后缀的稳定版 |

rc.1 对应 push/PR CI 已成功。现有 promote job 要求 main 与 RC 提交相同，因此即使不做本次适配，当前 main 也不能直接用 rc.1 晋升：会触发 `main advanced ... create and validate a new RC`。应正常产生新的候选版本，不应绕过该检查。

## 代码与上游接口核对

| 部分 | 核对结果与适配判断 |
| --- | --- |
| 宿主 LLM | `LlmAdapter`、注册适配器、retry policy replace、可配置 provider、独立 signal 的模型发现接口仍可用。当前源码对 0.1.5-rc.1 类型检查通过。 |
| Settings / Credentials | `ctx.settings.installSection` 与客户端 `remote.settings`、`remote.credentials` 调用仍可用；无需改写现有设置段 `llm-newapi` 和凭据引用 `newapi`。 |
| 客户端 | 当前注册 `settings.section`，未使用被调整的 conversation/Sidebar 面板接口；新类型检查和现有组件测试通过。模块工厂构建方式可继续沿用，实际 Web 加载仍待验证。 |
| 自定义 RPC | 新版保留 `connection.rpc.handle(channel, handler)` 与客户端 `rpc.call`；`/llm-newapi` 自有通道未被强制迁往 `/api`。源码调用与新版类型一致。 |
| 文件与图片 | 新 FileBlock 由 LlmRuntime 在调用适配器前投影为文本，常规宿主调用无需插件自行解析文件。插件继续声明 text-only；不能因上游 DeepSeek 增加视觉能力就宣称所有 NewAPI 模型支持图片。 |
| 动态系统提示词 | 新增可选 `systemPromptUpdate: 'in-history'` 能力，缺省仍为只读取前置系统消息。当前插件未声明该能力，符合保守兼容；如需启用，应逐模型配置并测试，不能全局开启。 |
| Session V3 / Agent API | 插件没有直接读写 Session 日志、访问 ctx.agent 或实现 Inbox。未发现需要跟随这些破坏性变更改动的调用点。宿主升级后的会话降级限制仍属于上游迁移约束。 |
| 网络代理 | 新宿主在启动时安装全局代理 dispatcher。插件 `/models`、`/chat/completions` 和未配置自有代理时的 models.dev 请求均使用全局 fetch，因而遵循宿主代理。models.dev 显式 ProxyAgent 仍覆盖该次请求。现有“未启用代理即直连”的说明及错误提示需要修正。 |
| 用量统计 | 新 TokenUsage 有可选 totalTokens；上游 DeepSeek 翻译器检查并填充精确总量。当前插件仍给出原有 input/output/cache/reasoning 字段，类型兼容；可以补充总量支持，但不能未验证就声称已适配新版全部统计展示。 |

### 必须处理的依赖声明问题

当前 peerDependencies 使用 `>=0.1.2-rc.1`。用本机 npm 内置 semver 实测：

```text
satisfies('0.1.2-rc.1', '>=0.1.2-rc.1') = true
satisfies('0.1.5-rc.1', '>=0.1.2-rc.1') = false
satisfies('0.1.5',      '>=0.1.2-rc.1') = true
```

npm 范围不会自动接纳另一个版本核心的 prerelease；而源码最低版本 guard 的自行比较会接受 0.1.5-rc.1，造成声明与运行时判断不一致。适配不能只改 devDependencies。

建议明确选择支持策略：保留旧版覆盖时，peer 范围显式包括 `0.1.2-rc.1` 和 `0.1.5-rc.1`，CI 验证两组固定版本；如接受相应补丁线后续正式版本，可用 `>=0.1.2-rc.1 <0.1.3 || >=0.1.5-rc.1 <0.1.6`，但不得将范围内所有版本都写成“已验证”。宿主版本 guard 的文案与范围应同步审视。

## 本次实际验证

在隔离目录 `.verify/compat-015` 中复制当前源码，将所有 dsh 开发依赖和已有的替代依赖统一切换到 0.1.5-rc.1，再安装 npm 实际发布的包。为避免一次改变太多条件，本次测试保留了原有 overrides；这不代表新版本仍然需要它们，正式升级依赖时应逐项核查。

| 检查 | dsh 0.1.2-rc.1 基线 | dsh 0.1.5-rc.1 隔离环境 |
| --- | --- | --- |
| host + client typecheck | 通过 | 通过 |
| build | 本轮基线使用已有产物 | 通过，生成 lib/index.js 与入库文件文本无差异 |
| 客户端组件测试 | 12/12 | 12/12 |
| 宿主导出与模块加载测试 | 修复 Windows 测试路径后通过 | 通过；工作区导出检查使用新版，离线加载测试仍使用旧版接口快照 |
| Cordis smoke | 通过 | 通过 |
| 新版真实 dsh web / 安装 tarball / 浏览器联调 | 本轮未运行 | 尚未运行 |

组合测试使用真实 Cordis、LlmRuntime 和 SettingsProvider 的内存实现，网关请求和凭据由测试替身提供。它不能代替真实浏览器或远端网关联调。由于本地没有 models.dev 缓存，本轮跳过了真实目录检查；可选的宿主接口快照一致性检查也没有运行。

上游源码归档已读取；Windows 解包时有若干符号链接无法创建，相关 LLM、settings、connection、代理源文件可正常读取。关键接口另以真实发布 npm 包的类型检查与测试验证。

适配评估阶段唯一已有文件改动是 `test/host-compat.mjs`：两处子进程动态 import 改用 `pathToFileURL(...).href`，修复 Windows 把盘符识别为 URL scheme 的失败。该阶段未改动主仓库业务代码、package.json、lockfile、lib 和发布配置。后续文档整理已重写 README 与设计说明、新增配置和开发指南，并将 docs 加入包的分发清单；包版本仍为 0.8.6-rc.1。

## 建议实施步骤与合入条件

1. 从当前 main 开始，将包版本更新为 0.8.6-rc.2；保留 rc.1 标签和 npm 包。
2. 升级开发依赖和锁文件，在 peerDependencies 中明确支持新 RC，并重新检查 overrides 是否仍有必要；补充 0.1.5-rc.1 导出快照，保留旧宿主拒绝检查。
3. CI 固定目标为 0.1.5-rc.1；若保留 0.1.2-rc.1 支持，则同时覆盖两组宿主，而非只凭最低版本 guard 放行。
4. 更新双语兼容表、代理行为及失败提示；按需求另行决定 totalTokens、图片和动态系统提示词能力，不与最低兼容要求混淆。
5. 完成构建、类型检查、现有测试、产物一致性检查、打包自包含检查和插件规范检查。使用同一个待发布 tarball，在隔离的 DSH_HOME 中验证 Web 认证启动、客户端加载清单、自有 RPC、模型发现、设置与凭据保存，以及浏览器中的实际设置页；再用本地网关验证文本流、工具调用与取消。
6. 所有必需检查通过后，合入 main 并将 v0.8.6-rc.2 发布到 npm next，同时在 GitHub 标记为 Pre-release。本轮明确不晋升正式版，npm 与 Git latest 保持 0.8.4；未来是否发布正式版另行决定。

**合并判定：可以合并到同一候选发布线；目前证据不支持直接正式发布。**

## 外部核对来源

- [上游 0.1.5-rc.1 发布说明](https://github.com/deepseek-ai/deepseek-harness/releases/tag/dsh-v0.1.5-rc.1)
- [本仓库 rc.1 Release / PR #4](https://github.com/wenzetan/dsh-llm-newapi/releases/tag/v0.8.6-rc.1)
- [rc.1 成功 CI](https://github.com/wenzetan/dsh-llm-newapi/actions/runs/34114813214)
- [插件 npm 元数据](https://registry.npmjs.org/dsh-llm-newapi)
- [宿主 npm 元数据](https://registry.npmjs.org/@deepseek-ai%2fdsh)
- [上游 LLM 接口](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.5-rc.1/packages/llm/llm/src/types.ts)
- [上游代理契约](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.5-rc.1/packages/util/http-proxy/README.zh.md)