dsh-ssh-bridge

English

本地 SSH 桥接服务：浏览器页面输入目标主机 (user@host[:port]) 与密码 → 本机桥接进程 → SSH 加密通道 → 目标主机，密码全程不经过聊天记录。主要作为 DSH (DeepSeek Harness) 插件使用，agent 经 router_exec 等工具在本机执行远端命令，任意 SSH 目标均可使用，无需预设主机；桥接核心不依赖 DSH，也可独立运行。

当前版本：v0.4.2

部署流程

依赖说明

程序	版本	说明
DSH	0.1.0-rc 系列	宿主 (插件模式)
pnpm	—	依赖安装 (由 dsh plugin 转发)
Node.js	≥18	运行环境
ssh2	^1.17	SSH 客户端库 (npm install 自动安装)
@deepseek-ai/schemastery	^3.18	插件配置 schema (npm install 自动安装)
@deepseek-ai/cordis	^4.0	DSH 宿主运行时 (peer 依赖, 由宿主提供, 可选)

具体步骤

# 1. 安装插件 (从 npm registry)
dsh plugin --profile web add dsh-ssh-bridge

# 2. 重启 DSH
dsh web

注意： pnpm 11 默认拦截 ssh2/cpu-features 的原生构建脚本 (node-gyp)，dsh plugin add 会以非零码退出、依赖装上了但插件不会挂载。需先在该 profile 的 pnpm-workspace.yaml 放行，再重跑安装：

allowBuilds:
  cpu-features: true
  ssh2: true

其他安装来源 (GitHub / 本地 tgz)：

# GitHub (tag 与 npm 版本一致)
dsh plugin --profile web add github:lance-kanglu/dsh-ssh-bridge#v0.4.2

# 本地 tgz (可从 GitHub Releases 下载)
dsh plugin --profile web add /path/to/dsh-ssh-bridge-0.4.2.tgz

dsh plugin add 会把包追加到 profile 的 dsh.profile.bundles 列表，重启 DSH 后插件自动挂载，无需手改配置；工具注册在全局层，所有会话的 agent 均可调用。

部署验证：dsh --profile web --dump-config 的组合配置树中应出现：

- id: ssh-bridge
  name: dsh-ssh-bridge/plugin
  config:
    basePort: 23991

手动方式 (本地开发调试，不经过 bundle)：把包放到部署的 profiles/node_modules 下 (可直接 junction 指向本项目目录)，再在 $DSH_HOME 的 cordis patch / 预设中加入一行：

- id: ssh-bridge
  name: dsh-ssh-bridge/plugin
  config:
    basePort: 23991

提示： 预设场景可用 agentPresets.standingKeyFor('<预设id>') 做 mount 校验 (会真实挂载整棵插件树)。

独立运行 (可选)

桥接核心不依赖 DSH，也可独立运行：

# 1. 安装依赖
npm install

# 2. 启动服务
npm start
# 等价于: node bridge.cjs

# 3. 打开页面
# 浏览器访问 http://127.0.0.1:23991

部署验证：启动日志输出如下，且浏览器可打开页面：

[ssh-bridge] 已启动: http://127.0.0.1:23991

使用说明

浏览器页面

1. 打开 http://127.0.0.1:23991，输入目标主机 (user@host[:port]) 与密码，点「连接」或回车；
2. 状态变为「已连接」后，下方输入框即目标主机的交互终端 (支持 ANSI 颜色渲染)，标题栏出现「断开连接」按钮；
3. 在终端输入 exit 会结束整个 SSH 会话 (与常规 SSH 客户端一致)；也可点「断开连接」按钮；
4. 断开后目标主机保留、密码清空，可重新输入密码连接；
5. 页面底部日志面板实时显示连接与请求状态，出错时可见具体原因。

命令执行 API (供代理 / 脚本调用)

每次启动生成随机 token 并打印在启动日志 ([ssh-bridge] token=xxxx)，调用以下接口需携带：

接口	方法	参数	说明
/api/auth	POST	{password, target?}	提交目标与密码建立 SSH 连接 (密码不写日志、不落盘；目标格式 user@host[:port])
/api/exec	POST	{cmd, token}	在目标主机执行一条命令，返回 {code, stdout, stderr}
/api/input	POST	{line, token}	向交互终端写入一行命令 (写 exit 会结束整个会话)
/api/ping	POST	{token}	查询连接状态 {ok, connected}
/api/disconnect	POST	{token}	断开 SSH 连接 (等价于页面「断开连接」按钮)
/api/reconnect	POST	{token}	复用页面认证时保存的凭据重新连接；未认证过返回 409

示例 (PowerShell)：

$body = @{ token = '<启动日志中的 token>'; cmd = 'uname -a' } | ConvertTo-Json
Invoke-RestMethod -Uri http://127.0.0.1:23991/api/exec -Method Post -ContentType 'application/json' -Body $body

安全： 服务只监听 127.0.0.1，外部网络无法访问；密码只在浏览器 → 本机进程 → SSH 加密通道之间流转。 注意： 端口 23991 被占用时自动顺延 (23992、23993...)，以启动日志为准。 提示： 更新页面代码后需强制刷新 (Ctrl+F5) 避免旧缓存；交互终端需在真实 SSH 会话中使用，网页终端仅回车可用。

DSH 插件化

机制

DSH 插件即 cordis 插件 (npm 包)：加载器 (@deepseek-ai/cordis-plugin-loader) 按包名导入插件、应用配置，行声明于 cordis.yml 或 patch 文件；模型工具经 tools 注册表挂载执行器，schema 自动注入提示词 (tool-pwsh、tool-bash 同机制)。

插件适配器

plugin/index.cjs 为 cordis 插件对象 (已对照 DSH 0.1.0-rc 实际运行时源码校准)：

• Config (schemastery) 声明配置并做默认值校验 — cordis 只读 Config 字段，schema 会被忽略；
• inject: ['tools'] 声明硬依赖，否则 ctx.tools 属性访问会抛 cannot get property ... without inject；
• 只经 tools.register() 注册执行器 (definition 必须含 output: { schema, render }，否则 register 直接抛 TypeError)。工具 schema 由 DSH 的 ToolRuntime.wireSchemas 从注册表自动注入 prompt，不要再调用 systemPrompt.tools() 重复注册，否则模型请求报 Tool names must be unique (INVALID_REQUEST 400)；
• 清理经 ctx.effect() 注册 — cordis 对函数声明形式的 apply 用 new 调用，apply 返回值会被当作类实例丢弃，不能用于 dispose。

注册三个工具：

工具	作用
router_exec	在目标主机执行一条命令；描述中携带桥接页面地址，并明确要求 agent 不索取/重复对话中的登录信息
router_disconnect	断开 SSH 连接 (等价于页面「断开连接」)
router_reconnect	复用页面认证时保存的凭据重新连接 (密码仅存进程内存)

已含三个契约/端到端测试：node test-plugin.cjs (cordis 注入/Config/register 契约，含「不得重复注册 schema」回归断言) 与 node test-mount.cjs (真实 SystemPrompt/ToolRuntime + scoped ctx 端到端，断言三个工具进入 scoped 层、prompt assemble 中恰好出现一次且工具名全局唯一)，以及 node test-e2e.cjs (真实本地 ssh2 服务器：认证 → exec → 断开 → 重连 → exit 结束会话)。

配置项

配置	默认值	说明
bindHost	127.0.0.1	监听地址，保持回环
basePort	23991	起始端口，占用自动顺延
execTimeoutMs	60000	单条命令超时

说明： 目标主机不预设，在桥接页面认证时输入 user@host[:port] 即可；CLI 模式可用环境变量提供默认目标，仅作页面预填。

注意：插件 ABI 目前为 0.1.0-rc 系列，第三方暂无公开文档；本适配器已按上述契约校准并测试通过。

代码结构

文件	作用
server.cjs	桥接核心 createBridge()，CLI 与插件共用
bridge.cjs	CLI 入口，支持环境变量配置 (SSH_BRIDGE_PORT、SSH_BRIDGE_ROUTER 等)
page.js	浏览器页面脚本 (ANSI 渲染)
plugin/index.cjs	DSH 插件适配器
test-parser.cjs	ANSI 渲染器测试 (npm test)
test-plugin.cjs	插件 cordis 契约测试 (node test-plugin.cjs)
test-mount.cjs	插件 scoped 挂载端到端测试 (node test-mount.cjs)
test-e2e.cjs	桥接核心端到端测试 (本地 ssh2 服务器, node test-e2e.cjs)

常见问题

• dsh plugin add 报 ERR_PNPM_IGNORED_BUILDS：pnpm 11 默认拦截 ssh2/cpu-features 的原生构建脚本，add 以非零码退出且插件不会挂载。先在该 profile 的 pnpm-workspace.yaml 配置 allowBuilds: { cpu-features: true, ssh2: true }，再重试。
• 页面打开无反应 / 点「连接」没反应：强制刷新 (Ctrl+F5)；确认服务在运行。
• 终端输出出现 [1;34m 等原始转义码：旧缓存所致，强制刷新即可 (已内置 ANSI 渲染器)。
• /api/exec 返回 not connected：先在页面完成密码认证，或让 agent 执行 router_reconnect。
• 终端输入 exit 后页面仍显示已连接：旧版本行为，v0.4 起 exit 会结束整个会话；若页面缓存了旧脚本请强制刷新 (Ctrl+F5)。
• /api/auth 返回 missing target：请求体需带 target，格式为 user@host[:port]；插件模式下未配置默认目标时该项必填。
• 端口被占用：服务自动顺延端口，以启动日志为准。
• 密码会泄露吗：不会。密码仅存于进程内存，不打印、不落盘；token 仅限本机、防跨站请求。

更新说明

v0.4.2

文档：

• README 重构为插件优先结构：部署流程改为 dsh plugin add 安装，独立运行降为「独立运行 (可选)」小节；
• 补充 pnpm 11 需在 pnpm-workspace.yaml 放行 ssh2/cpu-features 原生构建的说明。

v0.4.1

发布：

• 声明 dsh.bundle.patch 清单，支持 dsh plugin add dsh-ssh-bridge 一键安装；
• README 补充 npm / GitHub / 本地 tgz 三种安装方式。

v0.4

连接管理：

• 页面新增「断开连接」按钮；终端输入 exit 会结束整个 SSH 会话 (与常规 SSH 客户端一致)，不再停留在「已连接但无 shell」状态；
• 新增 /api/disconnect 与 /api/reconnect，agent 侧新增 router_disconnect 与 router_reconnect 工具，可依用户指令断开/重连 (重连复用页面认证时保存的凭据，密码仅存进程内存)；
• 工具描述携带桥接页面地址并明确要求 agent 不索取/重复对话中的登录信息，不假设具体主机；页面占位改为中性 user@192.168.x.x；
• 修复连接生命周期竞态：断开/重连后，旧连接迟到的 close/shell close 事件不再污染或误杀新连接；
• 新增 test-e2e.cjs (真实本地 ssh2 服务器端到端)。

v0.3

通用化：

• 目标主机不再预设，改为在浏览器页面输入 user@host[:port] 后连接，任意 SSH 目标均可使用；
• /api/auth 新增 target 参数，插件配置移除 routerHost/routerUser/routerPort；
• 插件适配器按 DSH 0.1.0-rc 实际契约校准：Config/inject/output {schema, render}/ctx.effect()；
• 修复工具重复注册：插件只经 tools.register() 注册，不再调用 systemPrompt.tools() — 注册表工具由 ToolRuntime.wireSchemas 自动注入 prompt，重复注册导致模型请求报 Tool names must be unique；
• 新增 test-plugin.cjs 与 test-mount.cjs 两个插件契约测试。

v0.2

新增：

• DSH 插件适配器 plugin/index.cjs，可注册 router_exec 工具 (实验性)；
• 核心重构为 server.cjs (createBridge())，CLI 与插件共用；
• CLI 支持环境变量配置，新增 LICENSE (MIT)。

v0.1

第一个正式版本。核心能力：浏览器密码认证、交互终端 (ANSI 颜色渲染)、本机 exec API、独立测试 (npm test)。