dsh-ssh-bridge

ZCode 风格的 SSH 远程开发插件，为本地部署的 DeepSeek Harness（DSH web）而做。

一键向导创建远程工作区 → 左侧工作区列表出现远程服务器 → 在里面开的会话自动就是远程会话（bash / 文件读写 / 搜索透明地在服务器上执行）→ 侧边栏文件浏览器直接显示远程目录树。

DSH 会话 ──tools/execute 桥──▶ SSH 引擎 ──▶ 远程服务器（只需 sshd，零足迹）
     ▲                                   │
     └──── better-sidebar 文件浏览器 ◀───┘

功能总览

安装

> --profile 后跟你的 DSH profile 名（大多数部署是 web，用 dsh plugin --profile <名字> list 可查看已有 profile）。

# 方式一：从 GitHub 安装（lib/ 已提交，无需构建）
dsh plugin --profile web add github:Pytorchlover/dsh-ssh-bridge
dsh web   # 重启 dsh web 生效（已在运行的话，重启对应进程）

# 方式二：本地开发（改代码后 pnpm build + 刷新页面即可，服务端改动需重启）
git clone https://github.com/Pytorchlover/dsh-ssh-bridge && cd dsh-ssh-bridge
pnpm install && pnpm build
dsh plugin --profile web add link:$(pwd)

使用

远程工作区（推荐）

1. 侧边栏「＋ 远程」→ 向导三步：选主机 → 连接 → 选目录。 2. 左侧出现远程工作区，点它的「New session」开会话——自动远程，直接对 Agent 说“跑下测试”、“改一下 xx 文件”。 3. 底部 better-sidebar 文件浏览器显示远程目录树（需打一次桥接补丁，见下）。

管理面板

向导里点「取消」进入主机管理页：新增/编辑/删除主机、导入 ~/.ssh/config、连接后浏览文件/开终端、把已有会话手动绑定到远程（解绑即回本地）。

better-sidebar 桥接补丁（远程文件树）

dsh-better-sidebar 的文件浏览器只认本地文件系统。补丁让它在会话 cwd 是远程工作区时改走 SSH：

node scripts/patch-better-sidebar.mjs            # 打补丁（src + lib，幂等）
node scripts/patch-better-sidebar.mjs --revert   # 还原
# 重启 dsh web 生效；better-sidebar 每次升级后需重跑

补丁只按需转发 fs.tree / fs.read / fs.write（非远程路径零改动），git 面板仍走本地。

与 ZCode 远程开发的差异（插件层架构所限）

• DSH 会话进程跑在本机，本插件通过工具分发层把会话操作转发远程——效果等价于 ZCode 的“Agent 在远端干活”，但左侧工作区标签对应的本地路径是标记目录；
• ZCode 的“配置同步（Skill/MCP 推到远端）”需要 harness 级支持，插件层不做；
• 远程会话中 read_image 与 bash 后台任务不可用（会收到明确报错）。

架构与排障

src/
  index.ts           # 插件装配：settings 区段、引擎、路由、工具、远程会话监听、系统提示、旧数据迁移
  protocol.ts        # host/client 共享纯类型 + 路由常量 + withCwd
  secrets.ts         # 凭证库适配器（DSH_REMOTE_SSH_* 引用）
  store.ts           # 主机/最近工作区/会话绑定存储、~/.ssh/config 解析与导入、旧插件迁移
  engine.ts          # ssh2 连接池（SFTP 通道用完即关）、exec、PTY、文件操作、连接日志、审计、命令探测
  routes.ts          # /api/remote-ssh/* 路由族 + 终端 WebSocket 升级
  tools.ts           # Agent 显式工具（ssh_list/exec/list_dir/read_file/write_file/upload/download）
  remote-session.ts  # 远程会话：tools/execute 拦截，按原工具 schema 自适应返回
  workspace-marker.ts# 远程工作区标记目录（会话 cwd → 远程绑定自动解析）
  sidebar-bridge.ts  # better-sidebar 文件桥（globalThis 通道）
  client/            # 浏览器半区：向导、Dock 面板、入口、API 封装

关键机制：

• 远程工作区 = 标记目录：~/.dsh/remote-ssh/ws/<alias>_<dir>/marker.json 记录 {alias, dir}；会话 cwd 落在标记目录内 → tools/execute 按 Session.header.cwd 动态解析远程绑定（子代理同样覆盖）。
• SFTP 通道卫生：每次操作开新通道、用完即关。sshd MaxSessions（默认 10）限制单连接并发通道，泄漏会累积到 Channel open failure: open failed；通道级失败自动标记连接损坏并重连重试。
• 双 bash 变体：dsh-base 同时装配 dsh-tool-bash（结构化输出）与 dsh-tool-bash-persistent（字符串输出）；拦截器运行时查询实际注册变体的 schema 自适应。
• 直连 harness RPC：向导通过 POST /api/workspace.create|workspace.rename|session.create（信封 {type:'client-request', rpcId, method, payload}）创建工作区与会话。

致谢

工程设计参考了社区里成熟 SSH 工具的实践：mcp-ssh-manager（审计日志、输出治理、策略层思想）与 opencode-remote-code（rg 回退链、透明工具覆盖）。终端使用 xterm.js（MIT），SSH 使用 ssh2（MIT）。

License

MIT