@dsh-remote/workspace-plugin

Readme

# DSH SSH Forge

<div align="center">

![release](https://img.shields.io/badge/release-v0.6.0-c8e56e?style=flat&labelColor=1c1b19)
![license](https://img.shields.io/badge/license-MIT-e5a462?style=flat&labelColor=1c1b19)
![runtime](https://img.shields.io/badge/DSH_Desktop-2.0.2-4da3ff?style=flat&labelColor=1c1b19)

**把经过身份核验的服务器目录，变成 Agent 可以安全使用的工作区。**

[⬇ 下载安装包](https://github.com/trrrrrryg/dsh-ssh-forge/releases) · [📖 安装全过程](#公开安装全过程github-releasesv060-起) · [🛡 安全策略](./SECURITY.md) · [🧩 兼容性说明](./COMPATIBILITY.md)

</div>

DSH SSH Forge 不是另一个 SSH 终端。它让本地目录与服务器目录并列成为明确的工作区目标：选择远端工作区后，Agent 的文件工具与普通命令才会路由到已核验的 SSH Provider；当身份、连接或权限无法确认时，操作会失败关闭，而不会静默回落到本机。

## 当前项目状态（2026-08-25）

> **v0.6.0 已通过 GitHub Releases 公开发布。** 普通用户下载离线安装包即可完成安装，无需 Node.js、源码或构建工具。运行时仍精确锁定 DSH Desktop `2.0.2` / DSH core `0.1.1-rc.2`——要让任意版本的 stock DSH 无门槛安装，仍需上游提供稳定的 `Workspace Provider API v1` 扩展点。

- **公开分发已上线：** [Releases](https://github.com/trrrrrryg/dsh-ssh-forge/releases) 中的历史 v0.6.0 资产仍名为 `dsh-remote-workspace-release-v0.6.0.zip`；后续版本统一使用 `dsh-ssh-forge-release-vX.Y.Z.zip`。发行包内含预构建插件、核心兼容产物（逐文件 SHA-256 清单）、CHECKSUMS.txt 与中文安装指南。
- **上游沟通持续进行：** 已在 DeepSeek Harness 官方仓库发布 [Workspace Provider API v1 设计讨论](https://github.com/deepseek-ai/deepseek-harness/discussions/4423)，内容涵盖无凭据目标模型、断联即失败关闭、会话兼容与 Agent 执行路由。
- **安全承诺：** 服务器密码、私钥内容与认证令牌不会提交到本仓库、上游 Discussion、Session、RPC、日志或对话中。
- **下一步：** 跟进上游对 API 边界的反馈，推动核心兼容层收敛为标准插件扩展；期间按版本迭代维护离线安装包与兼容矩阵。

## 功能演示

<table>
  <tr>
    <td width="50%" align="center">
      <img src="./docs/assets/new-connection.gif" alt="新建连接：密钥认证、测试连接与主机指纹核验" />
      <br><sub><b>① 新建连接</b> — KEY ONLY 认证 · 测试连接核验主机指纹</sub>
    </td>
    <td width="50%" align="center">
      <img src="./docs/assets/create-server-workspace.gif" alt="创建服务器工作区：目标类型、路径校验与结构化 WorkspaceTarget" />
      <br><sub><b>② 创建服务器工作区</b> — 目标显式化 · 允许根目录校验 · Agent 路由</sub>
    </td>
  </tr>
</table>

<p align="center">
  <img src="./docs/assets/remote-workspace-operation.gif" alt="路由概念：Agent → 工作区 → SSH Provider 循环演示" /><br>
  <sub>整体路由概念循环演示。以上画面均为<b>脱敏重建</b>：示例地址使用 RFC 5737 保留段 <code>203.0.113.10</code>，无真实服务器或密钥数据；动画由 Huashu-Design 生成，源文件见 <a href="./docs/assets/src">docs/assets/src</a>。</sub><br>
  <a href="./docs/remote-workspace-demo.html">查看完整交互版</a> ·
  <a href="./SECURITY.md">安全策略</a> ·
  <a href="./COMPATIBILITY.md">兼容性说明</a>
</p>

## 它解决什么问题

| 过去 | 使用 DSH SSH Forge 后 |
| --- | --- |
| Agent 不知道命令究竟在哪台机器执行 | 工作区本身就是执行目标，本地与远端清晰区分 |
| 远程连接依赖重复登录或临时命令拼接 | 连接配置、主机指纹与允许目录组成可复用身份 |
| 连接失败时容易误把操作落到本机 | 身份失配、断联或 Provider 不可用时直接失败关闭 |
| 远端目录缺少风险边界 | 路径在服务器端规范化后校验，越界访问被拒绝 |

## 一次操作如何到达服务器

| 步骤 | 用户与系统发生的事 |
| --- | --- |
| 01 · 选择 | 在工作区列表中选择已连接的服务器目录，而非本地路径 |
| 02 · 核验 | 使用密钥对 / SSH Agent、主机指纹及允许根目录确认目标身份 |
| 03 · 路由 | Agent 的文件读写与普通命令按当前 WorkspaceTarget 进入 SSH Provider |
| 04 · 执行 | 远端进程受 DSH 权限策略与工作目录边界约束；出现不确定状态立即停止 |

## 核心能力

### 连接与身份

- 设置中提供一级“远程连接”栏目；新建连接默认选择密钥文件认证，也可切换到 SSH Agent。
- 可在当前 DSH Host 生成独立的 ED25519 密钥对；界面只获得公钥、指纹与私钥路径，私钥内容不会返回。
- 配对帮助覆盖通用 Linux / 宝塔、阿里云、腾讯云、华为云、AWS、Azure 与 Google Cloud。
- 首次连接确认主机指纹；后续严格校验 `known_hosts`，支持自动连接与断线重试。

### 工作区与文件

- 在“新建工作区”中并列选择本地目录或服务器目录；远端目录注册为结构化 `WorkspaceTarget`，不会伪装成本机路径。
- 远端目录浏览、UTF-8 文本读取与带版本写入均限制在允许根目录内。
- 工作区侧栏在目录右侧显示服务器 IP：连接时为蓝色 `●`，断联或 Provider 不可用时为红色 `×`，并配有非颜色状态文本。

### Agent 执行

- 远程工作区的文件工具和普通 shell 子进程按精确的 Agent 身份路由到 SSH Provider。
- Provider 缺失、身份不匹配或连接断开时不会回落到本机执行。
- 当前覆盖 Agent 文件工具与普通 shell 命令；交互式 SSH PTY / persistent terminal 暂未提供，调用会明确失败。

## 安全设计

> `root` 登录、整机目录 `/` 与 `/root` 均为高风险操作。它们必须经过不可跳过的显式确认；取消、关闭、点击遮罩或按 Esc 均不会授权。

- **私钥不离开 Host**：仅保存路径引用，不进入 Renderer、HTTP 响应、日志、对话或剪贴板。
- **路径不可逃逸**：远端路径会在服务器端 `realpath` 后校验允许根目录，阻止 `..` 与符号链接越界。
- **主机身份固定**：工作区绑定主机、端口、用户名与主机指纹；任一身份字段改变都会使旧工作区失效。
- **写入不盲覆盖**：文本更新携带内容版本，发生冲突时拒绝写入。
- **远程清理可证明**：普通命令使用受监督的独立进程组；不确定、断联或异常退出均会保留保护性 cleanup fence，而不是把状态误判为成功。

详细边界见 [SECURITY.md](./SECURITY.md)。

## 平台、兼容性与发布状态

| 项目 | 当前状态 |
| --- | --- |
| DSH Desktop 与本机 Web | 共享同一套 Client / Host 插件能力 |
| Web 场景的 SSH 发起位置 | DSH Web Host 所在机器，而不是浏览器所在机器 |
| 支持的运行时 | DSH Desktop `2.0.2` / DSH core `0.1.1-rc.2`（发行包内置对应核心兼容产物，逐哈希校验） |
| stock DSH 任意版本 | 尚不能宣称兼容：上游仍缺少 Workspace Provider API v1 |
| 面向公众发布 | **已开放**：GitHub Releases 离线一键安装包（MIT 许可，附上游许可归属） |

本仓库同时包含 SSH 插件源码与 [DSH core 兼容补丁](./patches/README.md)。补丁精确对应 DeepSeek Harness `b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`，不包含上游仓库、依赖目录或本地连接数据。

## 快速开始

### 公开安装全过程（GitHub Releases，v0.6.0 起）

面向普通用户的离线安装包，无需 Node.js 或任何构建工具。

**第 1 步 · 自检环境**

- Windows 10/11（系统自带 PowerShell 5.1+ 即可）。
- DeepSeek Harness Desktop 必须是 **2.0.2**（内置 DSH core **0.1.1-rc.2**），见 Desktop 关于页版本号。其他版本会被安全拒绝。
- 记下两个路径备用：`DSH Desktop.exe` 所在目录；Desktop 安装目录下的 `resources\app.asar.unpacked\node_modules\@deepseek-ai\dsh`。

**第 2 步 · 下载与校验**

从 [Releases](https://github.com/trrrrrryg/dsh-ssh-forge/releases) 下载对应版本：v0.6.0 使用历史文件名 `dsh-remote-workspace-release-v0.6.0.zip`，后续版本使用 `dsh-ssh-forge-release-vX.Y.Z.zip`。右键文件 → 属性 → 勾选"解除锁定"→ 解压后进入文件夹。入口脚本会自动按 `CHECKSUMS.txt` 校验全部文件（fail-closed）；也可手动核对：

```powershell
Get-ChildItem -File | Get-FileHash SHA256   # 与 CHECKSUMS.txt 逐行对照
```

**第 3 步 · 完全退出 DSH**

退出 DSH Desktop 与 DSH Web Host（含托盘图标）。安装器自带进程守卫：检测到残留进程会点名 PID 并拒绝继续。

**第 4 步 · 执行安装**

```powershell
cd <解压出的文件夹>
# Desktop + Web 双端（推荐）：
powershell -ExecutionPolicy Bypass -File .\install-release.ps1 `
  -DshDesktopExecutable '<DSH 安装目录>\DSH Desktop.exe' `
  -DshPackageRoot   '<DSH 安装目录>\resources\app.asar.unpacked\node_modules\@deepseek-ai\dsh'
# 只用 Web 端：省略 -DshDesktopExecutable 即可
```

官方 `dsh` 命令已在 PATH 时可省略 `-DshPackageRoot`（安装器会自动发现并逐候选验证）。安装流程：完整性校验 → 预检（版本/身份/哈希/进程）→ 备份 → 事务化替换 → 写入收据。**任何一步失败都会自动恢复原状**，备份保留于 `<DSH_HOME>\backups\remote-workspace\<时间戳>`。

**第 5 步 · 旧版会话日志迁移（如被提示）**

若预检发现 v0 会话日志会拒绝安装并列出全部文件与迁移命令。先预览再执行：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\migrate-session-logs.ps1 -DshHome "$env:USERPROFILE\.dsh" -WhatIf
powershell -ExecutionPolicy Bypass -File .\scripts\migrate-session-logs.ps1 -DshHome "$env:USERPROFILE\.dsh"
# 或在安装命令上直接追加 -MigrateV0Sessions 一步完成
```

迁移只改写头行版本号（正文逐字节不变），原文件备份到 `<DSH_HOME>\backups\session-v0-migration\<时间戳>`。

**第 6 步 · 重启并验收**

重启 DSH Desktop 后依次确认：

1. 设置页出现"远程连接"入口；
2. `/dsh-remote/api/health` 返回 `workspaceProvider=READY`；
3. 新建 SSH 连接并创建服务器工作区，状态 connected；
4. 打开一个旧会话仍能正常加载。

**回滚与卸载**

- 整体回滚（插件 + 核心 + profile 三者精确还原）：同一安装命令追加 `-RestoreLastInstall`。
- 仅移除插件注册：`scripts\uninstall-local.ps1`；完整还原必须用 `-RestoreLastInstall`。
- 回滚不会删除已保存的连接元数据。

### 上游标准 bundle 安装（长期方向）

普通用户最终应通过 DSH 的标准 bundle 安装机制安装 `dsh.bundle.patch` 指向的 `cordis.patch.yml`，而无需替换 DSH core 包。

> 此路径仍待上游支持：stock DSH 尚未提供本插件要求的 Workspace Provider API v1。在官方扩展点落地前，GitHub Releases 的离线安装包是唯一的公开分发方式。

### 开发者 fork / compat 安装

> **仅面向维护者。** 安装器会事务性替换锁定版本的本地 DSH runtime 包；普通用户不要执行。

安装器严格绑定 DSH Desktop `2.0.2` 与 DSH core `0.1.1-rc.2`。先完全退出 DSH Desktop 和 DSH Web Host，构建相邻的 `dsh-core-remote-provider` 与本插件，再为 Desktop 显式传入可执行文件：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-local.ps1 `
  -DshDesktopExecutable 'C:\path\to\DSH Desktop.exe' `
  -DshPackageRoot 'C:\path\to\resources\app.asar.unpacked\node_modules\@deepseek-ai\dsh'
```

只安装 Web profile 时无需 Desktop 可执行文件：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-local.ps1 -Profiles web
```

若要撤销最近一次已完成安装并恢复安装前的插件、core 与 profile：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-local.ps1 `
  -DshPackageRoot 'C:\path\to\resources\app.asar.unpacked\node_modules\@deepseek-ai\dsh' `
  -RestoreLastInstall
```

`uninstall-local.ps1` 仅移除插件注册；需要完整恢复时必须使用 `-RestoreLastInstall`。恢复与卸载均不会删除已保存的连接元数据。

### 旧版 v0 会话日志迁移

新版 core 只读取 v1 会话格式。安装前若检测到 v0 日志，安装器会失败关闭并列出全部文件；可先预览再原位迁移（仅重写头行版本号，正文逐字节不变，自动镜像备份到 `$DSH_HOME/backups/session-v0-migration/`）：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\migrate-session-logs.ps1 -WhatIf   # 预览
powershell -ExecutionPolicy Bypass -File .\scripts\migrate-session-logs.ps1           # 迁移
```

或在重跑安装器时显式加 `-MigrateV0Sessions` 由其先行迁移。损坏、未知版本或形状不符的日志会被跳过并逐条说明，永不盲改。

### 兼容原生模式：首次工作区引导

维护者可把一份**不含密钥内容、密码、Token 或命令**的远端连接/目录声明传给安装器。安装器只把它原子写入插件自己的待导入队列；下一次启动时，插件会等待 Provider API v1 就绪，再通过 DSH 的结构化工作区服务创建远端工作区。它不会直接编辑 session JSONL、工作区数据库或把远端路径伪装成本机路径。

详见 [兼容原生引导说明](./docs/compat-native-bootstrap.md) 与 [脱敏示例](./docs/examples/remote-workspace-bootstrap.v1.json)。

连接配置保存在 `$DSH_HOME/remote-workspace/<profile>/connections.v1.json`，其中仅含非机密元数据与私钥路径引用。自动生成的密钥位于 `$DSH_HOME/remote-workspace/<profile>/keys/<uuid>/id_ed25519`；删除连接不会删除密钥文件。

## 构建与验证

```powershell
pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm verify:public-release   # 发布门禁：清单 / pack 审计 / 内容审计，输出 READY

# 维护者：产出发布物
powershell -ExecutionPolicy Bypass -File .\scripts\export-core-artifact.ps1    # 核心兼容产物 + 逐文件 SHA-256 清单
powershell -ExecutionPolicy Bypass -File .\scripts\export-release-bundle.ps1   # 离线安装包（CHECKSUMS.txt + 中文指南）
pnpm pack:public                                                               # 标准 npm 包（prepack 自动重跑完整校验）

# 安装链路冒烟套件（含普通用户端到端仿真：下载 zip → 解压 → 校验 → 安装 → 回滚）
powershell -ExecutionPolicy Bypass -File .\scripts\test-installer.ps1
```

- 插件类型检查与 Host / Client 构建通过；插件测试为 **20 个文件、171 项**。
- DSH core Workspace Provider 定向测试 7 项通过；Windows 上两项符号链接用例会受当前账户“创建符号链接”权限影响，不属于本功能断言失败。
- 已完成密钥生成、root 授权门、主机指纹、远程命令清理与 SSH key-only 连接的隔离验证；验证不会读取或输出私钥内容。
- 安装链路已在真实 Desktop / Web Host 完成功能验收（连接、远端工作区创建、会话读写与回滚）；界面视觉走查随版本迭代持续进行。

`pack:plugin` / `pack:public` 是公开发布的标准 npm 入口，发布元数据已确认（MIT，见 [LICENSE](./LICENSE)），`prepack` 会自动执行类型检查、构建、发布门禁与内容审计；`pack:developer` 用于本地受限的 fork / compat 包验证。

<details>
<summary><strong>展开：完整安全与安装约束</strong></summary>

### 安全约束

- SSH 密码与键盘交互认证始终禁止。自动生成的私钥只写入当前 DSH Host 的插件数据目录；加密密钥须预先加载到 SSH Agent。
- 每次生成密钥都会使用独立随机目录且绝不覆盖旧文件。Windows 仅允许当前账户、SYSTEM 与 Administrators；POSIX 使用目录 `0700`、密钥文件 `0600`。权限无法严格验证时失败关闭。
- 插件不会自动修改服务器的 `authorized_keys`；用户必须在帮助指引下显式安装公钥，并保留救援会话完成测试。
- 首次配置必须检测并确认 `SHA256:` 主机指纹。`ssh-keyscan` 不兼容时，插件会以禁用全部认证、远端命令和终端分配的 `ssh` / `ssh.exe` 回退，只协商并读取服务器公钥。
- 连接管理、目录与文件 API 只调用固定 Python helper；只有已创建远程 Session 的 Agent shell 工具可在所选服务器工作区执行命令，并持续受 DSH 权限策略与工作目录边界约束。
- `root`、`/` 与 `/root` 风险确认会随主机、端口、用户名或主机指纹变化而失效，必须重新确认。
- 远程普通命令由 Linux subreaper 监督，使用独立进程组，并执行 `TERM → grace → KILL`。执行前会原子持久化 cleanup fence；同一连接的并发执行世界全部经独立校验静止后才清除。Host 强杀、断电或崩溃后的 fence 只允许 SSH 身份完全一致的新上下文继承；身份修改与连接删除仍会被阻断。命令输出、旧控制文件、SSH 退出码或传输关闭都不能伪造成功。管理员只有在服务器侧独立确认残留进程已清理后，才能在退出 DSH 后备份并移除该 fence 文件以恢复。
- 连接管理 API 仅接受直接 loopback 请求。远程浏览器必须通过 SSH 本地端口转发访问；DSH 当前没有可复用的插件认证 seam，因此非 loopback Web 管理被安全禁用。

### 安装约束

脚本会在任何修改前严格核对 DSH core 源码、已安装 runtime 的 name / version、所需 core seam 与应用退出状态；再校验同级实际 runtime package 的 name / version 与锁定 hash。随后取得按 `$DSH_HOME` 隔离的进程互斥锁和独占文件锁，备份 Desktop / Web profile、旧插件与受影响的 core package，再以同卷暂存目录进行替换。安装回执绑定规范化路径、备份与 SHA-256；恢复会在首次写入前完整验证 schema、集合唯一性、备份存在性、哈希和 manifest。任一步失败或下次发现未完成事务时，都会恢复精确旧状态。

</details>

## 项目导航

- [发布下载](https://github.com/trrrrrryg/dsh-ssh-forge/releases)：离线一键安装包与各版本说明。
- [安全策略](./SECURITY.md)：威胁模型、凭据处理与运行时防护。
- [兼容性说明](./COMPATIBILITY.md)：DSH core seam、版本限制与失败关闭行为。
- [补丁说明](./patches/README.md)：与 DSH core 兼容层的边界。
- [交互演示](./docs/remote-workspace-demo.html)：无需网络、可在本地浏览器播放的完整流程。