# 兼容性与升级检查

## 当前适配范围

插件 0.1.1；DSH 适配基线 0.1.7-rc.1 / 0.2.0-rc.1 / 0.2.1-rc.2。本轮在独立 Windows Web profile 验证 0.2.1 的安装、原生侧栏和两后端协议；此前 WSL → Agent Box 的证据保留在历史审计中。完整跨平台 SSH、真实模型流式运行与多客户端并发仍未完成本轮实机验收，不能宣传“所有平台已验证”。

| 功能 | 实现及验证范围 |
| --- | --- |
| 原生会话、历史、流式输出 | gateway 按所属后端路由；此前原生浏览器验收通过 |
| 发送、取消 | 接入；本地模拟协议测试覆盖。当前轮没有对真实后端发送模型请求或取消已有任务 |
| 改名、归档、工作区内排序 | 接入；本轮在专用空会话上真实验收 |
| 创建工作区和会话 | 在“多端管理”中浏览或新建目录，再通过所属后端登记工作区。系统弹窗模式自动回退到 SSH SFTP；不修改远端 DSH 配置。0.2.1 独立环境验证了创建工作区/会话、目录浏览和新建目录 |
| 分叉 | 转发原生 fork 接口并转换返回会话 ID；未在本轮对真实有历史会话验收 |
| 队列操作、附件读取与上传、会话 skills、文件引用 | 已接入显式路由与身份隔离测试；完整真实 UI 流程仍待验收。传输响应及流帧当前限制 64 MiB |
| 工具审批、用户提问 | 未接入。上游使用可回传结果的远程事件通道，不是普通会话 RPC；须到所属后端界面处理 |
| 第三方卡片和动态插件运行 | 未接入；不能因为原生界面渲染了卡片就认为其交互已支持 |
| 已归档会话 | 管理页隐藏；0.1.7 原生取消归档接口已接入 |
| 置顶与侧栏搜索 | 0.1.7 的 pinned 工作区状态、pin/unpin 与 session/search 已聚合；远端会话搜索及打开历史已实机验收，置顶未在本轮实测 |
| 远端文件侧栏 | 0.1.1在 DSH 0.2.1-rc.2 接入原生只读预览与变更订阅；Markdown、PNG、PDF 独立 UI 验收通过，Office 转换未接入 |
| 跨机器移动/复制 | 不支持；不同后端身份组合拒绝执行 |
| 重连 | 有限重试、保留身份、原生重新订阅；不会自动重发变更请求 |
| 主后端重启 | 自动读取登录信息连接过的主机自动恢复；手动登录链接不保存 |
| 全局设置、插件与 skills 同步 | 不同步，主后端仍负责全局界面 |

## 0.1.1：子智能体与远端只读文件（2026-10-28）

本轮针对 DSH 0.2.1-rc.2 官方契约修复，沿用原生侧栏与会话界面。

- 子智能体只转换协议中已知的 subagentCatalog[].id；不递归改写正文、路径、历史或其他插件 payload。支持 sequenced、cached、migration-required 和 null 的原有区别，父子孙会话保留所属端与叶节点模式。
- 显式接入 workspaceFiles/stat、list、read、readBytes 与 changes。会话 scope 交给所属远端的原生服务授权；路径按远端 OS 语义原样传递，不回退本地读取。没有增加远端文件写入接口。
- DSH 0.2.1 的 readBytes 使用 multipart 二进制附件。仅接受单个已知 data 字段，校验响应 RPC ID、附件路径、占位符及重复/额外字段；不解释任意远端附件路径。
- 二进制 HTTP 响应限制为 64 MiB + 64 KiB 协议开销；普通 JSON 响应和单个流帧限制为 64 MiB。远端 DSH 可以设置更小的读取限制。请求可取消，错误不会自动重发变更操作。
- 错误仅保留白名单协议码、接口名与 HTTP 状态；未知错误使用固定说明，丢弃远端原始 message/details/stack。owner 与已撤销 Peer 的原生检查保持不变。
- 验证范围：本地模拟的双主机 ID 隔离、Windows/Linux 路径、目录/历史/首帧/实时更新、重连后 ID 稳定；独立 Windows DSH 实例的父子孙目录与历史、文件读取、字节范围、变更订阅；Edge 原生文件侧栏的 Markdown 自动更新、PNG 与 PDF。
- 两个临时 Windows Web 后端之间的浏览器测试使用专用 loopback 字节载体替代 SSH；不等于完整跨平台 SSH 实机验证。没有发送模型请求或操作生产任务，真实模型子智能体的运行/结束状态本轮由协议回归覆盖。
- Office 的 officeToPdf/render 与 generation 未接入；远端 Word/PPT 不能宣称支持。远端 OS 的“外部程序打开”也不等于在本机打开其路径。旧 DSH 的新增文件预览接口尚未逐版本实测。


## 0.1.1：64 MiB 与历史流恢复

- 单个 WebSocket 消息、ReadableStream 队列和普通 HTTP 响应上限均为 64 MiB。二进制 multipart 额外留 64 KiB 协议开销；文件能否读取仍由所属 DSH 的权限和 maxFileBytes 决定。
- 不会按上限预先分配所有空间，但解码、JSON 和 UI 状态会产生额外内存；并发大历史仍需关注内存峰值。
- 只有初始历史尚未交付、或只读 session/page 超限时，才自动缩小原生 maxMessages 到 50/10/1，并同步收缩 turnWindow.minMessages。地址、throughSeq、beforeSeq 等游标保持原样，hasMore 仍由原生接口提供。
- 超过预算的单条记录、慢消费者、格式错误及远端业务失败不会被误判为整机断网；保留安全的原生结构错误码，其他会话可以继续使用。
- 真正 socket/SSH 断开仍触发有限恢复；不会自动重发 prompt 或其他变更操作，也不会在已交付快照后自动重开历史。
- 回归覆盖 63 MiB 合法帧、65 MiB 超限、逐级缩窗、分页游标、业务拒绝、慢消费者、真实 socket 丢失和不重复交付历史。独立官方 DSH 验收了 8 MiB 历史和 72 MB 人工历史；后者自动缩窗后首帧约 30 MB，并经后续两页读回全部 120 条消息，无重复、无全局重连。
- Windows/Linux/macOS 使用同一套标准 Node/OpenSSH 传输；没有新增个人主机或路径常量。完整平台组合仍须实机验收，不能宣称所有组合均验证完成。


<a id="dsh-021-audit"></a>
## 0.2.1-rc.2 原生能力审查与适配（2026-10-18）

审查对象固定为上游标签 `dsh-v0.2.1-rc.2`，提交 `687f282e8625c6b8d11ff58211a90524be2e4317`；运行时安装官方 `@deepseek-ai/dsh@0.2.1-rc.2`，不是 master 或后续版本。

### 是否已经有原生替代

结论：源码提供了 SSH 远端执行能力，但未发现把多个已有 DSH 后端的工作区、会话和历史汇总进同一个原生界面的功能，不能把这两种能力等同。

| 官方能力 | 本标签中的实际范围 | 与本插件的区别 |
| --- | --- | --- |
| `dsh-ssh`、`fs-ssh`、`subprocess-ssh`、`sandbox-ssh` | 一个部署在自定义 profile 中使用远端文件和进程；Harness、模型连接和会话存储仍在主机。官方 SSH 组合要求两端 Linux/macOS 与辅助运行时 | 不连接另一台机器上已运行的 DSH，不汇总对方已有会话 |
| Web 经 SSH 转发 | 通过转发地址打开一个远端 Web profile | 不把多个独立后端合并到一个侧栏 |
| `api/remotes`、`api/remote-access` | 应用 Remote API 的选取/事件转发，以及每个 Peer 的权限策略 | 不是远端主机发现或多后端连接管理器 |

源码依据：[官方 SSH 提供者](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-rc.2/packages/ssh/ssh/README.md)、[Web 通过 SSH 运行](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-rc.2/packages/bundle/web-app/README.md#running-over-ssh)、[Remote API 组装](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-rc.2/packages/api/remotes/README.md)、[Remote 访问控制](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.2.1-rc.2/packages/api/remote-access/README.md)。另核对了原生 `ui-sidebar`、`ui-workspace` 和发布 profile 的组成。

### 0.0.10 的改动

- 新版 Gateway 引入 Peer principal 和生命周期访问边界。本插件只向 owner/旧 carrier 接入远端数据；非 owner 或已撤销 Peer 的调用和订阅交还原始 Gateway，保留上游检查。
- 新版 `openWireStream` 增加第七个 `uplinkWindow` 参数。插件完整保留该参数，避免其他原生流在安装插件后改变行为。
- 更新协议提示基线，保留 0.1.7/0.2.0 的回归用例；没有改写 DSH 安装文件，没有新增个人主机或目录常量。

### 验证证据与边界

- 77 项 Node 回归测试、1 项可选真实两后端集成测试、4 项 Python 测试通过；运行依赖审计未发现漏洞。
- 独立 Node 24、两个专用 `DSH_HOME`、不同 loopback 端口；没有更新、重启或连接用户主力 DSH/Agent Box。
- 真实协议：登录、事件订阅建立、工作区/control baseline、目录浏览/新建子目录、工作区登记、两端工作区聚合、会话创建/改名、projections、历史 snapshot、搜索接口、归档/取消归档、置顶/取消置顶。
- 安装包经官方 `dsh plugin --profile web add -w` 安装。真实 Edge 浏览器验证了插件加载、两端原生侧栏标签、输入部分路径显示候选、点击进入目录并添加远端工作区、原生打开远端空会话；控制台没有 error。创建/重连测试时会主动重新订阅，观察到预期的连接重试 warning。
- 测试远端在自己的 profile 中显式使用官方 browse 目录提供者；插件仍不自动改变用户后端目录模式。系统弹窗模式的 SFTP 回退由现有模拟测试覆盖。
- 本轮两后端之间使用直接 loopback 字节通道替代 OpenSSH 隧道，既有 SSH/SFTP、重连和实时通知有回归覆盖。未发送付费模型请求；不能由此声称完整跨平台 SSH、真实模型输出或 Windows/macOS 全组合已实机验证。
- 官方 Web profile 的全文搜索仍默认关闭。空会话可以验证搜索接口，但不能作为消息内容搜索的正例；开启方法见下面历史验证说明。非 owner 的受限客户端暂不支持本插件的远端聚合，保留上游自身范围。

## 0.2.0-rc.1 隔离验证（2026-10-04）

锁定上游标签 `dsh-v0.2.0-rc.1`（提交 `4878cdabd87d4041bdaff61d04c966883b9fd07a`），安装官方 `@deepseek-ai/dsh@0.2.0-rc.1`，使用独立 Node 24、两个专用 `DSH_HOME`、随机 loopback 端口。没有升级、重启或改写用户主力 DSH。

- 修正新增的 `session/projections` 路由；远端会话状态只向所属后端请求，缺失会话的 `null` 保持原样。
- 真实两后端验证：登录、事件订阅建立、工作区/control baseline、工作区登记、会话创建/改名、projections、历史 snapshot、搜索接口、归档/取消归档、置顶/取消置顶。
- 浏览器验证：最终 0.0.9 安装包可以加载，多端管理的原生面板正常；两端工作区同时出现在原生侧栏，通过管理器输入路径可添加远端工作区，远端空会话可在原生界面打开。没有填写模型密钥。
- 本轮真实协议测试使用直接 loopback socket 替代 SSH 字节隧道；OpenSSH/SFTP、断线恢复与实时状态变化另有自动化回归。没有实际连接 Agent Box，没有发送真实模型请求；不能把本轮验证宣传为完整 SSH、模型流式运行或全平台实机验收。
- Windows 默认系统目录弹窗会返回 `directory-picker/unavailable`。插件保留 SFTP 回退和手动路径登记；本轮验证了手动登记，目录回退由现有模拟测试覆盖。
- 官方 Web profile 的全文搜索默认 `openAt: never`。需要全文搜索时，由用户在相关后端的 profile `cordis.patch.yml` 配置官方能力，插件不会自动开启：

```yaml
- id: session-query-sqlite
  config:
    path: ':memory:'
    openAt: first-search
```

原生全文搜索扫描消息内容，不搜索空会话的标题。测试 profile 单独启用了上述配置；真实搜索接口验证不等于带消息内容的搜索 UI 验收。

可选集成测试（需先在专用目录启动两套一次性 DSH，日志分别为 `primary.stdout.log` 和 `remote.stdout.log`）：设置 `DSH_COMPAT_TEST_ROOT` 为该目录，运行 `node --test tests/dsh-runtime.test.js`。测试会创建工作区和空会话，只可指向测试环境。常规 `npm test` 不设置该变量时跳过此项。

## 跨平台审计（2026-09-24）

结论：这是面向多平台的 DSH Web 插件，不能宣称兼容所有 0.1.7-rc.1 安装方式或所有原生交互。版本相同并不保证启用了相同的服务、目录选择器和客户端载入器。

| 范围 | 代码支持与限制 | 实机证据 |
| --- | --- | --- |
| WSL/Linux 主后端 → Linux 远端 | OpenSSH 隧道、原生 Web Gateway；远端无需安装本插件 | 已验证连接、重启恢复、侧栏、搜索、历史及工作区登记/移除 |
| Windows 主后端 | 使用系统 OpenSSH 路径；需安装 Windows OpenSSH Client，只有其他位置的 ssh.exe 不够 | 尚未完整实测 |
| macOS 主后端 | 从 PATH 调用 ssh，使用当前用户的 SSH 配置 | 尚未实测 |
| Windows/macOS 远端 | 手动提供 DSH loopback HTTP 登录链接，通过 SSH 转发；不依赖远端 Python | 尚未实测 |
| 自动读取登录信息 | 仅 Linux；需 Python 3、同用户可读的 /proc 和保存登录链接的进程标准输出文件 | 已验证当前 Linux 启动方式；终端、journal 或容器启动不保证可用 |
| 主机、路径与端口 | 无个人主机或项目目录硬编码；SSH/DSH 端口均接受 1–65535。远端目录原样交给远端 DSH，不在本机拼接 | 端口、Windows 风格路径有自动化测试；非默认端口未跨平台实测 |
| DSH 客户端 | 声明 platform: web；依赖原生 sidebar、layout、sessions 和 Gateway 服务 | 当前 Windows Desktop 承载的 Web 页面可用；其他 Desktop 载入方式不能据此保证 |

其他边界：仅支持 SSH 密钥/Agent，SSH 服务必须允许 TCP 转发；导入只枚举用户 ~/.ssh/config 中的具体别名，通配符与 Match 条件不能当作完整自动发现。手动登录链接不落盘，因此主后端重启后需要重新提供。每帧/响应上限 64 MiB、最多 16 个连接，以及尚未转发的审批、提问、第三方卡片，都会限制“完整原生体验”。

公开发布前仍需在 Windows 和 macOS 主后端、Windows 和 macOS 远端分别验证连接、目录/会话操作、消息起止状态与重连；模拟平台参数测试不能替代这些实机组合。

## 接入实现

`src/index.js` 在插件生命周期内包装 `typertGateway.invoke/stream`；`native-wire.js` 对 DSH 0.1.7 / 0.2.0 Web Carrier 的 `invokeRpc/openWireStream` 作限定适配，卸载时恢复原方法。此入口不是上游公开的稳定扩展 API，升级 DSH 前必须重新核对并运行协议与浏览器回归。`native-gateway.js` 只翻译已知身份字段，不改写对话文本、路径和附件内容。`native-contract.js` 集中声明当前适配的操作。

这是对公开服务方法的运行时适配，不是上游承诺稳定的多后端中间件接口。没有覆盖 DSH 安装文件，也没有第二套对话 renderer 接管原生会话；源码中保留的早期 renderer 仅用于历史测试，不是当前界面。

设置和主页面通过 DSH 插件槽注册。原有 directoryFlow 是单占用槽，本插件不替换其现有目录选择器；远端“添加工作区”入口仅在多端管理中，原生“+”仍创建主后端工作区。

## 基础协议检查的边界

连接和重新登录时，在暂存的 SSH carrier 上读取 workspace/follow 与 session/control 的首个 baseline，校验结构并关闭探测订阅。失败则不接入，主后端保持可用。当前契约不提供这里可以依赖的 DSH 语义版本字段，所以界面明确显示“远端版本未核验”；不能把它标为与主机版本一致。基础协议检查也不能证明所有写操作都兼容。

## 更新流程

1. 记录目标 DSH 版本，检查 Host gateway、Client loader 依赖、原生会话与工作区签名。
2. 在独立 profile 加载插件，运行 `npm ci`、`npm run build`、`npm test`。
3. 实际验证连接、目录浏览、创建、原生会话、改名、归档、排序、断线、未发送草稿；变更测试只用专用会话。
4. 分别验证附件、审批及第三方卡片，不能用文本对话通过代替这些验收。
5. 记录通过和未覆盖的范围，再发布插件预览版。不要直接在运行任务的主力后端升级。

DSH 当前开发安装不监视链接源码；Host 代码更新需要检查任务状态后重载后端，刷新浏览器只能更新 Client 代码。

## 上游源码参照

- [DSH 源码](https://github.com/deepseek-ai/deepseek-harness)
- `packages/client/ui-workspace` 的 directoryFlow 与工作区注入契约。
- 安装包 `dsh-api-workspace-controller`、`dsh-api-session-controller` 的 `typert.remote-client.d.ts`。
- `dsh-api-remotes` 转发事件中的 `approval/request` 与 `user-questions/request`。

上述 master 链接只用来定位源码，不构成对任意未来版本的兼容承诺。