SSH 远程工作区trrrrrryg/dsh-ssh-forge

DSH SSH Forge

release
license
runtime

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

⬇ 下载安装包 · 📖 安装全过程 · 🛡 安全策略 · 🧩 兼容性说明

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 中的历史 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 设计讨论，内容涵盖无凭据目标模型、断联即失败关闭、会话兼容与 Agent 执行路由。
- 安全承诺： 服务器密码、私钥内容与认证令牌不会提交到本仓库、上游 Discussion、Session、RPC、日志或对话中。
- 下一步： 跟进上游对 API 边界的反馈，推动核心兼容层收敛为标准插件扩展；期间按版本迭代维护离线安装包与兼容矩阵。

功能演示

① 新建连接 — KEY ONLY 认证 · 测试连接核验主机指纹

② 创建服务器工作区 — 目标显式化 · 允许根目录校验 · Agent 路由

整体路由概念循环演示。以上画面均为脱敏重建：示例地址使用 RFC 5737 保留段 203.0.113.10，无真实服务器或密钥数据；动画由 Huashu-Design 生成，源文件见 docs/assets/src。
查看完整交互版 ·
安全策略 ·
兼容性说明

它解决什么问题

| 过去 | 使用 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。

平台、兼容性与发布状态

| 项目 | 当前状态 |
| --- | --- |
| 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 兼容补丁。补丁精确对应 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 下载对应版本：v0.6.0 使用历史文件名 dsh-remote-workspace-release-v0.6.0.zip，后续版本使用 dsh-ssh-forge-release-vX.Y.Z.zip。右键文件 → 属性 → 勾选"解除锁定"→ 解压后进入文件夹。入口脚本会自动按 CHECKSUMS.txt 校验全部文件（fail-closed）；也可手动核对：

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

第 3 步 · 完全退出 DSH

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

第 4 步 · 执行安装

cd
Desktop + Web 双端（推荐）：
powershell -ExecutionPolicy Bypass -File .\install-release.ps1
-DshDesktopExecutable '\DSH Desktop.exe'
-DshPackageRoot   '\resources\app.asar.unpacked\node_modules\@deepseek-ai\dsh'
只用 Web 端：省略 -DshDesktopExecutable 即可

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

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

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

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 一步完成

迁移只改写头行版本号（正文逐字节不变），原文件备份到 \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 -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 -ExecutionPolicy Bypass -File .\scripts\install-local.ps1 -Profiles web

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

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 -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、工作区数据库或把远端路径伪装成本机路径。

详见 兼容原生引导说明 与 脱敏示例。

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

构建与验证

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），prepack 会自动执行类型检查、构建、发布门禁与内容审计；pack:developer 用于本地受限的 fork / compat 包验证。

展开：完整安全与安装约束

安全约束

- 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。任一步失败或下次发现未完成事务时，都会恢复精确旧状态。

项目导航

- 发布下载：离线一键安装包与各版本说明。
- 安全策略：威胁模型、凭据处理与运行时防护。
- 兼容性说明：DSH core seam、版本限制与失败关闭行为。
- 补丁说明：与 DSH core 兼容层的边界。
- 交互演示：无需网络、可在本地浏览器播放的完整流程。