dsh-easyssh/packages/dsh-easyssh

一句话定位

dsh-easyssh 是 DSH Web GUI 的 SSH 远程工作区插件：让用户在聊天界面右侧切换到「SSH 模式」，使本机的 LLM 与 Agent 循环通过 SSH/SFTP 透明地读写远程服务器上的文件、运行命令，而无需切换终端。

核心能力

• 在会话头部新增两个按钮：配置 SSH 主机（别名 / 主机 / 端口 / 用户名 / 密码或密钥）、一键进入或退出 SSH 模式
• 进入 SSH 模式后，左侧文件树面板自动切换到远程根目录，支持懒加载、文件名搜索、文本预览与编辑、保存时带 mtime 冲突检测
• 把模型本机的 read / write / edit / glob / grep 与 bash / 终端工具在 SSH 模式下透明切换到远程主机执行
• 提供 9 个显式 remote_* 工具（status / ls / read / write / mkdir / rm / rename / glob / grep），路径被限制在远程根目录内
• 复用 dsh-ssh 的主机配置与持久 SSH 连接池（~/.dsh/dsh-ssh.json），并通过 system-prompt 宣告告知 LLM 当前的工作模式与路径规则
• 在 Settings 页面提供 SSH 主机管理页（别名、密码/密钥、远程根目录），与头部配置对话框共享同一份数据

技术实现

• 语言: TypeScript（双半区产物：host 端 Node.js + client 端 React/浏览器 bundle）
• 关键依赖: @deepseek-ai/dsh-ssh（SSH 引擎与主机存储，工作区 file 依赖）、@deepseek-ai/dsh-fs-sandbox / dsh-subprocess-local（本地后端门面）、@deepseek-ai/dsh-client-runtime / dsh-client-ui-slots（浏览器侧注入与插槽注册）
• 架构模式: 三行 cordis 插件 + profile patch：主行（easyssh）提供 mode store、路由、agent 工具、提示词宣告与共享 core；patch 禁用 fs-sandbox / subprocess，由 easyssh-fs / easyssh-subprocess 两个接缝行接管 ctx.fs 与 ctx.subprocess，按当前模式路由到本地沙箱实现或 SFTP/SSH 实现
• 入口文件: packages/dsh-easyssh/src/index.ts（host 半区）、packages/dsh-easyssh/src/client/index.ts（client 半区）、packages/dsh-easyssh/cordis.patch.yml（profile 补丁）

适用场景

适合需要让 AI 直接在自己常用的开发服务器、内网机器或 CI 节点上读写代码、跑命令、又不想离开 DSH 聊天界面的开发者：例如让 Agent 在远程服务器上重构老项目、批量改配置、跑构建与脚本。SSH 模式下文件树、模型工具、提示词自动跟随目标主机，普通用户在网页上点击切换即可。

前置依赖与兼容性

安装方式

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

配置项

提示：模式状态（local / remote、alias、remoteRoot）在 host 进程内为单例，会话头部按钮随时切换。

常见问题

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

A: dsh-easyssh 复用 dsh-ssh 的 SSH 引擎与主机存储（同一份 ~/.dsh/dsh-ssh.json），并在其上加一层「工作区」：自动接缝切换让模型的 read/write/edit/bash 在 SSH 模式下直接作用于远程，而 dsh-ssh 主要负责手动 ssh_exec / ssh_upload / ssh_download 等运维操作。

Q: 安装后还需要手动改配置文件吗？

A: 不需要。插件自带的 cordis.patch.yml 会在安装时作为 profile bundle layer 自动应用：禁用 fs-sandbox / subprocess 行并插入 easyssh-fs / easyssh-subprocess 两条接缝行，重启 DSH 即生效。

Q: SSH 模式下模型的普通工具会受影响吗？

A: 会。read/write/edit/glob/grep 与 bash/终端在 SSH 模式下透明切换到远程主机执行；路径以远程根目录（默认登录用户 ~）为基准，相对路径以 remoteRoot 为锚点。显式的 remote_* 工具与 dsh-ssh 的 ssh_* 工具仍可用作精确操作。

Q: 配置文件存在哪里？是否安全？

A: SSH 主机与凭据存放在 dsh-ssh 的 ~/.dsh/dsh-ssh.json（权限 0600/0700）；HTTP API（/api/dsh-easyssh/*）仅接受 127.0.0.1 / localhost loopback 请求并校验同源，禁止跨站访问与 LAN 暴露。

Q: 支持哪些平台？Windows 远程主机可以吗？

A: 客户端跨平台（macOS / Windows / Linux 浏览器均可）；远程主机需要 SSH + SFTP + GNU find/grep/coreutils（-printf / -mz / base64 -w0）。POSIX 主机（Linux / macOS）支持最完整；SSH 模式下不要使用 Windows 本机路径（C:\、M:\ 等），请改用 ssh_exec 走远端 shell。

Q: 有哪些使用限制？

A: 模式状态为 host 进程内单例（多标签页共享，P2 才按 sessionId 隔离）；左侧预览仅 80KB 以下文本，二进制/超大文件请用 ssh_exec / ssh_download；远程 grep/glob 限深 4~6 层、限 200 条；SSH 模式下本机沙箱不对远程执行生效。

Q: 如何卸载？

A: 通过 dsh plugin remove 卸载并重启 DSH 即可恢复原 fs-sandbox / subprocess 行；若之前手动应用过 patch，需把 profile 的 cordis.patch.yml 恢复为 []。

上手难度

入门 — 安装一行命令即生效，会话头部出现 SSH 按钮，无需任何额外配置；首次使用只需在对话框里填主机、用户名、密码/密钥即可进入远程工作区。

已知问题与限制

• 模式状态为 host 进程内单例，多标签页共享同一状态（P2 才按 sessionId 隔离，见 README §已知限制）
• 文件预览仅限 80KB 以下文本，二进制文件（含 NUL 字节）和超大文件会被拒绝，建议改用 ssh_exec / ssh_download
• 远程 grep/glob 依赖 GNU find/grep/coreutils（-printf / -mz / base64 -w0），最大深度 4~6 层、最多 200 条
• 远程命令 printf %s "$HOME" 用于解析登录用户家目录，仅在远程 shell 支持此语法时有效（默认 POSIX）
• SSH 模式下本机内核沙箱不对远程进程生效，remote_* 工具描述明确要求「先确认再执行」
• pwsh 工具在 POSIX 远程主机上不可用，应改用 bash 语义命令或 ssh_exec
• /api/dsh-easyssh/* 路由接收的 JSON 请求体上限 4MB（routes.ts:16 MAX_JSON_BODY_BYTES），超大将返回 400
• 真实路径解析对符号链接有 32 跳上限保护，超过会抛 outside-root 错误

中文 | 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）。