# 宿主兼容与维护范围

[English](compatibility_EN.md) · 中文

本表列出 dsh-sidenote **0.5.0** 的已验证组合与维护承诺。其他发布版本请查看对应 Release。安装引擎范围是接入门槛，不能代表其中所有 rc 或插件组合均已验证。

| 精确组合 | 维护分类 | 验收门槛 |
|---|---|---|
| DSH 0.1.7-rc.2，不装 BS | 当前维护 | 每个相关 PR 的完整固定验收 |
| DSH 0.1.5-rc.2，不装 BS | 延长维护，用户当前环境 | 同样的完整固定验收 |
| DSH 0.1.1-rc.2 + BS 0.12.3 | 旧版冻结，下限代表 | 完整固定验收，保留已承诺工作流 |
| DSH 0.1.1-rc.2 + BS 0.18.0 | 旧版冻结，独立组合 | 完整固定验收，未经退役 PR 不移除 |
| DSH 0.1.2-rc.1 + BS 0.18.0 | 旧版冻结，API 代际代表 | 完整固定验收 |
| DSH 0.2.0-rc.2，不装 BS | 当前维护，已完成精确准入 | 完整固定验收并作为必需检查 |

BS 指 dsh-better-sidebar。未列出的组合为尚未验证；原生宿主配 BS 0.19+ 的共存路径也不能从“不依赖 BS”推导为全部验证。Alpha 不作发布版兼容承诺。

0.5.0 包含主/侧统一注释、侧边回复划选、失败保留与恢复，以及默认关闭的兼容诊断。前期[新版准入 CI](https://github.com/g-yixuan/dsh-sidenote/actions/runs/38281154300)与[最终功能复核 CI](https://github.com/g-yixuan/dsh-sidenote/actions/runs/38344084161)记录各维护组合的实际运行版本、构建摘要和验证证据；后者通过六组 153 个真实 E2E 与 313 个单元测试。相关运行流程使用受控模型，外部模型回答不属于本次验证。旧 0.4.6 发布包不包含这些改动。

新增安装声明只包含精确 `0.2.0-rc.2`：`>=0.1.1-rc.1 <0.2.0 || =0.2.0-rc.2`；UI primitives 同样仅增加该精确版本。其他 0.2 rc、稳定版及 alpha 仍需各自准入。

冻结保留旧接入和已声明功能，不追逐宿主新能力。数据丢失、错误会话投递和安装回归仍需处理。默认维护最近两条已完整验证的版本线及一个明确的延长环境；该原则不会自动删除旧检查。退役必须另开 PR，记录最后验证的插件/宿主版本、影响、替代路径及中英文公告。没有有效数据时不以 npm 下载量估算宿主占比，不增加遥测。

## 接入与诊断

本次涉及的主消息/composer DOM、会话输入、持久内容、消息接受、模型和侧栏差异集中在 `src/client/host/`。业务层保留引用来源/目标、fork 生命周期和保存规则。保留有依据的代际分界，不使用版本到类的 adapter registry。

诊断默认关闭，正常使用不显示顶栏诊断按钮或整体受限标记。开发者调试或报告问题时，在 **设置 → 通用设置 → dsh-sidenote 诊断模式** 手动开启，再点击会话顶栏的“兼容诊断”查看或重查当前能力：可用、等待就绪、尚未确认、不可用。选择只保存在当前浏览器、当前 DSH 地址，刷新后保留；浏览器拒绝保存时，设置行会说明仅当前页生效。关闭后立即隐藏面板与按钮，不改变正文、附件、注释或侧聊，不关闭后台能力检测和输入恢复，也不读写宿主全局开发者开关。所有维护组合使用同一个插件开关，不跟随新版宿主缺省开启的开发者模式。

服务尚未提供、会话或 DOM 尚未挂载时不判断为不兼容；明确提供了缺必要方法的接口才记不可用，读取失败记尚未确认。空会话、没有打开侧聊或版本未知不会自动弹出故障提示。消息接受能力只有实际观察到当前会话代际的持久 user/steering 或权威 Queue/Inbox 才确认，不能根据清稿或乐观气泡判断。重新检查只读取状态，不发送测试消息、不创建侧聊或调用模型。

受限时保留已保存注释、正文和附件，并在现有编辑器/chip/输入框显示原因。接口恢复后重查并重试；恢复遇到另一份宿主草稿时保留本地内容，先核对再发送。看不到精确源消息时只隐藏角标，不删除引用或猜另一个会话。

诊断报告只在手动点击“导出报告”时下载，不自动上传；仅含软件版本、能力、原因和接入路径，不包含会话 ID、用户正文、鉴权 URL、Cookie、Key 或本机路径。插件版本由构建清单给出；宿主/组件缺可靠 metadata 时显示未知。完整组件版本由 CI 的实际运行 inventory 记录，不从 devDependencies 或 CLI 推断。

## 验收和新版准入

1. 从官方 dist-tag 选定候选后固定精确版本；安装失败直接报错，不能换测 latest。
2. 隔离 DSH_HOME/profile、工作区、端口，核对实际 CLI、运行组件和当前构建摘要；不升级日常实例。
3. 所有固定组合跑同一套主→主、主→侧、侧→侧、编辑/chip、完整协议、失败重试、恢复/隔离与回流流程。涉及的 Queue/Steer/Stop、busy fork、模型与图片也通过真实宿主链路验证。
4. 辨别安装/宿主故障、插件 API/DOM 适配及测试定位问题，保留原失败，聚焦修复并重跑旧维护组合；不能降低断言或跳过功能。
5. 候选需完成相关完整功能、真实运行和可见浏览器验收后，再通过 PR 更新支持声明、安装范围、双语指南和 required checks；核对 GitHub ruleset 的实际检查名称。

现有五组必需检查保留，新增 `plugin-mount (0.2.0-rc.2, none)`，共六组宿主检查。每周 canary 解析一次 latest，随后固定该版本跑相同流程和 inventory；失败保存证据且在 job 中可见，不自动修改支持范围或用户环境。使用现有 GitHub Actions 状态，不另建通知机器人。

真实输入 Ctrl/Cmd+Enter 的 Steer 遵循宿主步骤边界；停止保留的队列由后续发送继续唤醒。消息被接受和模型回答成功分别记录。