dsh-ssh/packages/dsh-ssh

一句话定位

dsh-ssh 是 DSH Web GUI 的远程 SSH 运维插件：在浏览器里管理多台 SSH 主机（密钥 / 密码 / ProxyJump 跳板机），跑命令、打开 Web 终端、SFTP 上传下载、做本地端口转发，以及一键并发跑多台主机；同时把这 6 个能力（ssh_list / ssh_exec / ssh_upload / ssh_download / ssh_tunnel / ssh_cluster）暴露给 Agent，GUI 和 AI 共用同一份主机配置与连接池。

核心能力

• 管理多台 SSH 主机：在 Web 界面增删改查、搜索、测试连接；支持密钥 / 密码认证、passphrase 加密密钥、ProxyJump 多级跳板机；配置可一键从标准 ~/.ssh/config 导入
• 执行远程命令：单条命令带超时（默认 60 秒）、stdout/stderr 分离、2MB 输出截断保护，断线自动重连最多 3 次；并发集群执行可按别名 / 环境 / 标签过滤，默认并发 8
• Web 终端：xterm.js + WebSocket PTY 终端，自适应列/行尺寸，带 1MB / 512KB TCP 背压暂停 / 恢复
• SFTP 传输：上传走 NDJSON 进度流、下载走二进制流附 Content-Disposition，远程目录浏览会跟符号链接并按批并行 stat
• 本地端口转发隧道：把远程内网服务的端口映射到 127.0.0.1，访问远程数据库 / Web UI 只需连本地端口；支持列表 / 停止 / 全部停止
• Agent 工具 6 件套：ssh_list 列主机、ssh_exec 跑命令、ssh_upload / ssh_download 传文件、ssh_tunnel 管隧道、ssh_cluster 集群执行；GUI 与 Agent 共用 SshEngine 单例

技术实现

• 语言: TypeScript（host 半区 Node.js + client 半区 React/浏览器 bundle）
• 关键依赖: ssh2（ssh2 客户端，支持 exec / shell / SFTP / forwardOut / MaxSessions 兼容）、ws（WebSocket Server，用于 /api/dsh-ssh/terminal 升级）、@xterm/xterm + @xterm/addon-fit（浏览器侧终端渲染）、schemastery（插件配置 Schema 校验）
• 架构模式: 双半区 cordis 插件 + profile bundle patch：dsh.bundle.patch（cordis.patch.yml）以插件名 @deepseek-ai/dsh-ssh 把行插入 web profile roster，host 半区（exports "."）注册 SshEngine + /api/dsh-ssh 路由 + WebSocket 终端 + Agent 工具 + system-prompt 宣告，client 半区（exports "./client"）通过 DOM 注入在侧边栏新增「SSH」入口并挂载中心面板的 hosts / terminal / transfer / tunnels / cluster 五个 tab；不修改 DSH 源码
• 入口文件: host 端 packages/dsh-ssh/src/index.ts、client 端 packages/dsh-ssh/src/client/index.ts、profile 补丁 packages/dsh-ssh/cordis.patch.yml

适用场景

适合需要在自己的开发服务器、内网机器或云上节点手动跑运维操作（跑命令、传文件、开隧道）的 DSH 用户：直接在网页侧边栏点开 SSH 入口就能配置多台主机、打开 Web 终端维护服务、用 SFTP 部署产物。同时希望让 AI 也参与远程运维时，模型可调用 ssh_list / ssh_exec / ssh_upload / ssh_download / ssh_tunnel / ssh_cluster，把 GUI 配好的主机当作 AI 的远程手足。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:chenw2759-wq/dsh-IDE/packages/dsh-ssh

配置项

主机配置（别名 / 主机 / 端口 / 用户名 / 密码或密钥路径 / ProxyJump 链 / 标签 / 备注）独立存放在 ~/.dsh/dsh-ssh.json（文件权限 0600、目录 0700），通过 SSH 面板的「主机」页或「从 ~/.ssh/config 导入」按钮维护，详见 src/store.ts。

常见问题

Q: 这个插件和官方 dsh-ssh 是什么关系？

A: 这就是官方收录的条目。dsh-ssh 由 chenw2759-wq/dsh-IDE 仓库发布，负责 DSH 上的「手动 SSH 运维」（管理主机、Web 终端、SFTP、隧道、集群）；同一仓库下的 dsh-easyssh 在其之上加了「工作区模式切换」，让模型日常的 read/write/edit/bash 工具在 SSH 模式下透明作用于远程。两个插件共享 ~/.dsh/dsh-ssh.json。

Q: 安装后需要额外配置吗？

A: 无需改文件。插件自带 cordis.patch.yml（声明在 package.json#dsh.bundle.patch），会以 profile bundle layer 形式自动应用，插入 id 为 ssh 的双半区插件行；设置面板里有 enabled 与 announceToAgent 两个开关可调。

Q: Agent 调用前必须先在 GUI 配主机吗？

A: 是。ssh_exec 等 6 个 Agent 工具共用同一份主机配置（~/.dsh/dsh-ssh.json）；首次使用需在 SSH 面板的「主机」页手动加，也可以从 ~/.ssh/config 一键导入（已存在的别名会自动跳过）。

Q: 配置文件存在哪里？是否加密？

A: 存于 ~/.dsh/dsh-ssh.json，文件权限 0600、目录 0700（store.ts 写入时显式 mode: 0o600）。密码与密钥口令以明文保存，文档明确说明这是「与 ssh-skill 在 ssh-config 注释里写密码同一信任模型」——按本地凭据对待，不要把该文件上传到云端或共享给他人。

Q: 支持跳板机（ProxyJump）吗？

A: 支持多级。链中的每一跳必须是本插件已配置的主机别名（store.find 必须能找到），按顺序通过 hopClient.forwardOut 转发到下一跳的 127.0.0.1:0，最终落到目标主机。

Q: Web 终端走的是什么协议？

A: xterm.js + 真实 RFC 6455 WebSocket。浏览器发起到 /api/dsh-ssh/terminal?alias=...&cols=...&rows=... 的 WebSocket 升级请求，host 端用 ws 做 noServer 升级并调 ssh2 的 client.shell({ term: 'xterm-256color', ... })；缓冲背压 1MB 暂停 shell 输出、512KB 恢复，保证慢客户端不丢消息。

Q: 上传 / 下载路径有什么限制？

A: 上传的目标路径必须是绝对路径（相对路径会被 remotePath must be an absolute path 拒绝）；下载暂不支持整个目录（仅单文件，逐文件下载），上传支持目录递归（走本地 walk 逐文件传）；临时暂存在 os.tmpdir()/dsh-ssh-uploads/，传输完成后清理。

Q: 网络断线会怎样？命令会重复执行吗？

A: SshEngine.withClient 每个操作默认最多重试 3 次；exec 断线重连可能重复执行非幂等命令（重启服务类），长命令需注意副作用；SFTP 通道按 client 缓存复用，避免撞 OpenSSH MaxSessions（默认 10）导致后续列表 / 读取间歇失败；ls / stat / readFile 带 15s / 60s 超时，半死连接会报错而不是无限转圈。

上手难度

入门 — 安装一行命令后侧边栏自动出现「SSH」入口，主机可手动填或一键从 ~/.ssh/config 导入；Web 终端、SFTP、隧道都是 GUI 操作；Agent 工具对模型自动声明，无需用户记忆 API。

已知问题与限制

• 断线自动重连最多 3 次：exec 通道可能重复执行非幂等命令（重启服务、删除文件等），长命令需注意副作用（engine.ts:249 withClient(attempts = 3)）
• 上传必须绝对路径：相对路径会被拒绝；下载不支持整个目录（仅单文件），上传支持目录递归（README §已知限制 + engine.ts:591）
• 跳板机每一跳必须是本插件已配置的主机别名：否则报 proxyJump alias 'X' not found，且不支持外部 ssh_config 主机（engine.ts:293）
• 远程命令输出原样返回：包括 env / cat ~/.aws/credentials 等可能带回敏感信息的内容，远程输出不脱敏（README §安全模型）
• ssh_upload / ssh_download 以宿主进程权限直接读写本机任意路径：不经本机沙箱（与 ssh-skill 相同语义，README §安全模型），Agent 调用前需确认路径可信
• 密码与密钥口令以明文存于 ~/.dsh/dsh-ssh.json：文件权限 0600 / 目录 0700，但仍是本地凭据，不要同步到云端（store.ts:334 + README §安全模型）
• 断点续传（resume）未实现：上传 / 下载中断后必须重传（README §已知限制）
• pnpm 10+ 默认阻止 ssh2 / cpu-features 构建脚本：安装后会在 <profile>/pnpm-workspace.yaml 自动写入占位，需把 allowBuilds.ssh2 与 allowBuilds.cpu-features 改为 true 再重新 dsh plugin add（父仓库 README §安装）
• SFTP 操作受 OpenSSH MaxSessions（默认 10）约束：本插件按 client 缓存复用 SFTP 通道缓解，撞上限时列表 / 读取会间歇失败（engine.ts:201-208）
• WebSocket 终端背压阈值固定 1MB / 512KB：极端慢客户端可能短暂卡顿，未提供自定义（routes.ts:36-39）
• 配置 JSON 上限 64KB：/api/dsh-ssh/hosts 的 JSON 请求体上限 MAX_JSON_BODY_BYTES = 64 * 1024（routes.ts:23），超大主机列表会 400
• 上传 body 上限 4GB：/api/dsh-ssh/upload 的 MAX_UPLOAD_BYTES = 4GB（routes.ts:26），更大文件需分片
• 主机别名语法限制：仅允许小写字母、数字与单连字符（/^[a-z0-9]+(-[a-z0-9]+)*$/），含下划线或大写的别名会被 store 拒绝（store.ts:62）
• alias 命名区分大小写：内部存储按字符串精确匹配（file.hosts.some(entry => entry.alias === alias)），需保持一致（store.ts:134）

中文 | English

把 DeepSeek Harness（DSH）Web GUI 升级为一体化开发环境，四大核心能力：

• 🖥️ 右侧边栏：可停靠的右栏抽屉——文件树 + 预览/编辑同框；拖 tab 拖出成浮窗，拖回右缘自动停靠（下框 / 右栏 / 浮动 / 三栏 IDE 四态切换）
• 📄 预览：Markdown / HTML / 图片 / CSV / Office（docx / xlsx / pptx）/ 日志等多格式直接预览
• ✏️ 编辑：代码即时编辑（语法高亮 + 行号 + 斑马纹）+ Markdown/HTML Word 式可视化编辑 + Office 框内富文本编辑
• 🧩 IDE：文件树、命令行终端、Trae 风格红绿 diff、类型颜色标签、Git 角标、监视路径——开箱即用的 JupyterLab 式工作区

同时内置 SSH 远程工作区模式：右上角（session log 左侧）配置 SSH 主机（密码 / 密钥，复用 ~/.dsh/dsh-ssh.json），进入后右侧面板自动切换为远程文件树，模型本机的 read / write / edit / glob / grep 与 bash / 终端在 SSH 模式下透明地在远程服务器执行，LLM 与 Agent 循环仍在本机——「本地大脑、远程手脚」。

功能总览

⚙️ 右边栏工作区设置（系统设置内）

「设置」→「右边栏工作区」栏目集中管理右栏工作区的功能开关（8 项：自动 diff / 监视圆点 / Git 角标 / 语法高亮 / 缩放预览 / 三栏 IDE / 终端停靠 / 会话隔离）与编辑工具栏工具（9 项，供富文本编辑选用），圆角卡片 + 开关，改动即时生效并持久化。

🖼️ Markdown 预览（三种布局）

Markdown 文件在面板中直接渲染预览（青色标签），并支持三种布局随意切换：

• 下框展示（⇊）：预览显示在下栏
• 右侧弹出（⇉）：预览显示在右侧代码栏
• 浮动覆盖（⇱）：浮动覆盖在对话框上方，宽度更大

🌳 左侧文件树

左侧文件树：懒加载、按文件名搜索定位、Git 状态角标（A/M/D/R/U/C）、右键菜单（新建文件 / 新建文件夹 / 下载 / 行内重命名 / 复制 / 粘贴 / 删除进回收站），本地目录与 SSH 远程目录自动切换；已打开的文件绝不重复开 tab，磁盘变化时在原 tab 上自动刷新内容。

🔍 监视路径（自动弹出范围）：默认只监视一级目录（根目录及其直接子目录下的文件）。 点击目录行右侧圆点逐级切换：浅黄 = 监视此目录下一级路径，绿色 = 监视此目录下所有层级（n级），再点恢复默认；监视标记按会话记忆。顶栏（文件 / 变更 / >_ 右侧）有规则说明框。构建产物、临时文件、锁文件等过程文件无论标记都不弹出。

📊 状态栏

底部状态栏展示工作区状态。

✏️ 支持代码即时编辑

代码区即时编辑：五颜六色的语法高亮（Trae 风格配色，跟随浅色/深色主题自动切换）+ 行号 + 斑马底纹，可读写编辑、Ctrl+S 保存、保存带 mtime 冲突检测；工具栏提供分屏（编辑器 | 预览）、刷新等操作。

🔴🟢 红绿标注（Trae 风格编辑 diff）

任何外部编辑（Agent 工具写文件、其他进程改动）都会自动弹出「Update(路径)」卡片到下栏—— Added/removed 统计 + 删除行红底、新增行绿底；每个文件的每次编辑都会弹（基线自动推进，不重复不遗漏）； 保存后同样弹出：

• 全新文件（无历史基线）自动弹出全绿卡片（整份文件视为新增）
• 文件被删除自动弹出全红卡片（整份文件视为移除）
• diff 卡带固定双列行号（旧 / 新各一列，增删行号对齐）、未变更行斑马底纹
• 点「编辑最新版本」→ 编辑器覆盖整个显示框，可直接修改最新代码并保存（保存后红绿自动更新）； 点「刷新」红绿不丢失

🎨 颜色标记（类型颜色标签）

每个打开的标签带类型色块——橙 = 图片、绿 = CSV、蓝 = Python、黄 = JS/TS、紫 = JSON、 青 = Markdown、红 = diff、灰 = 日志——标签再多也能一眼分辨；新打开的文件与 diff 自动滚到 可见位置，标签条横向滚动 + 标题截断，绝不拥挤。

⌨️ 命令行展示（终端与运行）

内置命令行终端：代码工具栏「▶ 运行」直接执行当前文件（python / node / bash 等），「>_ 终端」打开 命令行面板随时输入命令（SSH 模式下均在远程执行）；文件栏 tab 条也有独立终端入口。终端以 真实终端风格停靠在聊天栏底部五分之一处（黑体、macOS 圆点标题、❯ 提示符、绿光标，不与对话重叠）。

📜 日志预览

日志文件（灰色标签）在面板中直接预览。

🖼️ 图片预览 / 📋 CSV 预览 / 🌐 HTML 预览

• 图片（橙色标签）与 HTML（紫色标签）预览支持放大/缩小：工具栏 − / % / + / 1:1 / 适应宽度，或 Ctrl+滚轮缩放
• CSV 数据表渲染为表格（绿色标签）

🖥️ 右侧边栏（可停靠抽屉 · 拖拽停靠 / 脱离）

• 右栏抽屉（默认）：预览停靠在右侧栏（文件树 + 预览同框的 drawer）；四态切换——下框（⇊）/ 右栏（⇉） / 浮动（⇱）/ 三栏 IDE（⿻，对话 | 文件树 | 预览三栏并排）
• 拖 tab 拖出成浮窗：任意布局下按住预览 tab 条 / 工具栏空白处拖动，即把预览拖出成浮动窗，位置 1:1 跟随指针、动画流畅不卡
• 拖回右缘自动停靠：把浮窗拖到屏幕右缘松手，自动停靠回右侧抽屉；拖到「盖住文件树（树自动折叠为圆形按钮）/ 树下方 / 聊天区下方」附近则吸附到对应预设位，拖出吸附区即回到自由浮动
• 浮窗自由缩放：右下角斜纹把手拖拽改宽高（尺寸记忆，吸附时保留）
• 聚焦模式：预览打开时点文件栏折叠箭头，文件树收为约 30px 右栏 rail（仅留小圆角展开按钮），点击即展开，专注预览与编辑；折叠后预览框保持原宽度

🧬 R 语言支持

.R / .r 脚本以 Rscript 运行（▶ 运行），R 标签用 R 官方蓝；.Rmd（R Markdown）识别为 Markdown 可预览渲染；代码高亮原生支持 R。

📄 Office 呈现（docx / xlsx / pptx 直接预览）

• docx：段落 / 表格 / 加粗 / 斜体 / 下划线 / 文字颜色 / 字号 / 高亮 / 对齐 / 字体（含中文字体 w:eastAsia）/ 段落与文本底纹 / 内联图片与形状照片（w:drawing/a:blip，含 mc:AlternateContent 形状）/ 内容控件（w:sdt）/ 页眉页脚（header1.xml 等 part 的 logo/信头）直接渲染
• xlsx：首个工作表渲染为表格（共享字符串解析）
• pptx：逐页卡片式呈现
• 浏览器端 ZIP 解析，无需宿主依赖、无需重启 dsh

✏️ 框内富文本编辑（Office）

预览工具栏「编辑」进入框内编辑：工具栏按设置面板勾选显示（字体 / 字号 / 加粗斜体 / 对齐 / 下划线 / 文字颜色 / 高亮 / 段间距行间距 / 页边距）；保存时由编辑后 HTML 重建 docx/xlsx/pptx 并以二进制写回（mtime 冲突保护，粗体/斜体/下划线/颜色/字号/字体/高亮等 run 格式编辑保存后不丢）。 已知限制：图表（word/charts/*）与嵌入对象（嵌入 Excel）等复杂结构暂不解析，编辑保存也不保留。

🎨 HTML / Markdown 可视化编辑（Word 式原地编辑）

预览工具栏「可视化编辑」：渲染结果本身就是可编辑文档（不再是浮动文本框）——像 Word 一样在渲染页上直接改。Markdown 在可编辑区里改编译后的 HTML，保存时转回 markdown 源（标题含中划线不会乱码、代码围栏保留语言）；颜色 / 字号 / 字体 / 下划线 / 高亮以严格白名单的内联 HTML 持久化，改字色不再误刷底色、粗斜体字号保存后不丢。HTML 在完整文档 iframe 里编辑（PPT 式富文本修改：颜色/字号/粗斜体/对齐/下划线/高亮），原 <style> 与画布背景照常渲染，保存回写整个文档（不再丢成单列覆盖的 body 碎片）。工具栏提供加粗/斜体/下划线/文字颜色/高亮/字体/字号/对齐/撤销/重做。文字颜色 / 底色为 Word 式按钮：点一下「A」就把当前记住的颜色套到选区（下方色条显示当前颜色），小「▾」弹出调色板选色即记住并生效——选色不再要点好几下，且可与粗体/斜体对同一段同时生效。工具栏会高亮当前选区已有的格式（加粗/斜体/下划线/对齐/颜色/底色按钮呈现阴影），像 Word 一样一眼看出选中文字带了什么格式。

🚀 SSH 远程开发（本地大脑、远程手脚）

• 接缝切换：通过 profile 补丁把 ctx.fs / ctx.subprocess 切换为模式路由门面——本地模式委托 给部署自带的沙箱化实现，SSH 模式委托给 SFTP/SSH 远程实现（原子写、版本校验、CRLF 处理、流式输出、 PTY 终端）。模型工具零改动地远程执行。
• 远程文件系统：完整 @deepseek-ai/dsh-fs 实现，路径 / 版本 / 原子写 / CRLF / 规范路径传输。
• 远程子进程：完整 @deepseek-ai/dsh-subprocess 实现，exec + PTY 终端，输出溢出转储到本地。
• 多主机：GUI 配置多台主机（含 ProxyJump 跳板链、密钥 passphrase），一键切换；设置页主机管理 专区（增删改 / 测试连接 / 进入退出），配置持久化在 ~/.dsh/dsh-ssh.json。
• 圆角胶囊按钮 + 多机选择栏：会话头部 SSH 按钮圆角化（远程态品牌色高亮）；连接对话框顶部列出 已保存主机，点击即进入（多机一键切换）。
• 会话级 SSH 状态隔离：每个会话记住自己的设备与模式，切换会话自动恢复（不同会话可分别处于 不同主机或本地）。限制：宿主侧 fs/subprocess 接缝按全局模式路由，隔离作用于面板与显式 remote_* 工具。
• 符号链接跟随：远程文件树正确识别符号链接目录（如 AutoDL 的 /root/autodl-tmp）。
• 显式远程工具：remote_status / remote_ls / remote_read / remote_write / remote_mkdir / remote_rm / remote_rename / remote_glob / remote_grep，以及 ssh_exec / ssh_upload / ssh_download。

SSH 主机配置：别名 / 主机 / 端口 / 用户名 / 密码或密钥 / 远程根目录，保存并测试连接后一键进入 SSH 模式。

进入 SSH 模式后，右侧面板自动切换为远程文件树，read / write / edit / glob / grep 与终端透明地在远程服务器执行。

操作速览

• 布局切换：预览 tab 条右侧「⇊ / ⇉ / ⇱」循环切换——下框展示 / 右侧抽屉（默认）/ 浮动覆盖（更宽）。
• 拖拽停靠：按住 tab 条 / 工具栏空白处拖出成浮窗；拖到屏幕右缘松手停靠回右栏抽屉；拖到预设位吸附。
• 编辑文件：打开 .py / .md / .js 等文件 → 直接输入 → Ctrl+S 保存（mtime 冲突检测）。
• 运行代码：打开 .py / .js / .sh 等文件 → 工具栏「▶ 运行」，SSH 模式下在远程主机执行。
• 打开终端：预览工具栏「>_ 终端」，或文件栏 tab 条「>_」按钮（不打开代码也能开命令行）。
• 查看 diff：外部编辑 / 保存后自动弹卡；点「编辑最新版本」直接改，点「刷新」保留红绿。
• 文件右键：文件树节点右键 → 下载 / 重命名 / 复制 / 粘贴 / 删除（本地与远程一致）。

仓库结构

dsh-IDE/
├── packages/
│   ├── dsh-aionui-panel/ # 右侧面板系统：文件树/预览/终端/编辑 diff/类型色标签（IDE 工作区本体）
│   ├── dsh-ssh/          # SSH 引擎：ssh2 连接池、exec/PTY/SFTP/隧道/集群（SSH 远程模式依赖）
│   └── dsh-easyssh/      # SSH 远程工作区：模式状态机、接缝门面、远程实现、Web GUI 前端
└── README.md

右侧文件面板（文件树 / 预览 / 终端 / 右键菜单 / 编辑 diff）由 dsh-aionui-panel（DSH Web GUI 右侧 面板系统）提供，本仓库内与 dsh-IDE 配套维护；dsh-easyssh 通过 sshWorkspaceMode 跨插件服务驱动它 跟随 SSH 模式。SSH 远程开发只是 dsh-IDE 的能力之一——本地目录同样享受完整的 IDE 工作区。

安装

前置要求：Node.js ≥ 22、pnpm、已安装 dsh（npx @deepseek-ai/dsh）。

# 1) 克隆并构建
git clone https://github.com/chenw2759-wq/dsh-IDE.git
cd dsh-IDE
pnpm install
pnpm --filter "./packages/dsh-aionui-panel" build
pnpm --filter "./packages/dsh-ssh" build
pnpm --filter "./packages/dsh-easyssh" build

# 2) 把三个包安装到 web profile（注意用你自己的绝对路径）
dsh plugin --profile web add file:C:/你的路径/dsh-IDE/packages/dsh-aionui-panel
dsh plugin --profile web add file:C:/你的路径/dsh-IDE/packages/dsh-ssh
dsh plugin --profile web add file:C:/你的路径/dsh-IDE/packages/dsh-easyssh

仓库品牌为 dsh-IDE；核心插件包名沿用 dsh-easyssh（安装标识，不随品牌改名）。

💡 pnpm 构建放行（一行）：dsh-ssh 依赖的原生库（ssh2 / cpu-features）需要构建。pnpm 10+ 默认阻止依赖构建脚本，dsh plugin add 会报 ERR_PNPM_IGNORED_BUILDS: Ignored build scripts: [email protected], [email protected]，并在 <profile>/pnpm-workspace.yaml 里自动写入占位：

allowBuilds:
  cpu-features: set this to true or false
  ssh2: set this to true or false

把两个 set this to true or false 改成 true，然后重新执行第 2 步的 dsh plugin add （重复执行是幂等的）。这是 pnpm 的标准流程，任何带原生依赖的插件都一样。

第 3 步：接缝切换（自动，无需手动）

安装 dsh-easyssh 时，其自带的 cordis.patch.yml（经 dsh.bundle.patch 声明）会作为 profile bundle 层自动应用：禁用部署自带的 fs-sandbox / subprocess，挂载模式路由门面 easyssh-fs / easyssh-subprocess（SSH 模式下模型工具透明地远程执行；本地模式委托回同一套 沙箱实现）。不需要手动编辑 <profile>/cordis.patch.yml。

⚠️ 升级用户必读：手动写入接缝补丁只属于 0.1.0 之前的旧版本。若你按旧文档在 <profile>/cordis.patch.yml（Windows 默认 C:\Users\<你>\.dsh\profiles\web\cordis.patch.yml） 里写过手写补丁，升级后必须把它删除（恢复为 []）——否则自动补丁 + 手写补丁各插入一次 相同的 ssh-workspace-fs / ssh-workspace-subprocess 行，启动会报 duplicate loader entry id 错误。删除后重启即可（自动补丁内容与旧手写补丁一致，行 id 相同）。

第 4 步：重启

# 重启 dsh
npx @deepseek-ai/dsh web

打开 http://127.0.0.1:3080 → Ctrl+F5 硬刷新（浏览器缓存旧 client 包时必做）→ 右上角 SSH 按钮配置主机 → 进入 SSH 模式。

回滚 = 把 cordis.patch.yml 恢复为 [] 再重启。

使用

1. 会话右上角（session log 左侧）点击 SSH → 填主机（别名/主机/端口/用户名/密码或密钥/远程根） → 保存并测试 → 进入 SSH 模式。
2. 右侧面板自动切换到远程文件树；直接对 Agent 说「读/改远程文件」「在服务器上执行命令」——普通工具即远程执行。
3. 路径规则：远程绝对路径直接用；相对路径以远程根 remoteRoot（默认 ~）为基准；不要用 Windows 本机路径。
4. 右上角切换按钮随时回到本机模式。

安全

• 路由仅 loopback（同源校验）；认证材料存 ~/.dsh/dsh-ssh.json（0600）。
• 远程操作消耗真实远程资源，先确认再执行；SSH 模式下本机沙箱不对远程执行生效。
• 远程 grep/glob/realpath 依赖 GNU find/grep/coreutils。

致谢

远程 ctx.fs / ctx.subprocess 实现移植并改编自 UynajGI/dsh-ssh （MIT，详见各文件头与 NOTICE），在其基础上补全了 Web GUI 前端与运行时模式切换。

License

BSD-3-Clause。远程实现的 MIT 版权归 UynajGI/dsh-ssh 原作者（见 NOTICE）。