前言¶

很多人在开发或跑智能体时，会把代码和 CLI harness 放在一台 Linux 服务器上：本机用笔记本连 SSH，在终端里开 Kimi、Claude、Codex 等，再用 vim 或 scp 改文件。DeepSeek Harness（DSH）本身擅长在本机 Web 界面里编排插件和会话，但若工作目录在远端，往往还要在服务器上再装一套服务，或做目录同步。

BeastyZ 维护的 dsh-remote-agent 走另一条路：只在本机 DSH 里装一个客户端类插件，通过系统自带的 OpenSSH 连到远端，把远程目录、终端、文件树和已安装的 harness 搬进 DSH 左侧的「远程 Agent」工作台。服务器侧不需要安装 DSH，也不需要额外的 agent server。

这是什么¶

dsh-remote-agent 是 DSH 的远程 Agent 工作台插件（分类：客户端）。它解析本机 ~/.ssh/config，建立 SSH 连接，在 Web 里浏览远程目录作为工作区，在真实远程 PTY 中启动已检测到的 Agent CLI 或自定义命令，并在右侧编辑、预览远程文件，附带 Git 更改、worktree 并行和端口转发。

仓库：BeastyZ/dsh-remote-agent；社区目录页：skillhub.cn 插件条目。许可证 MIT；package.json 中版本为 1.0.1，引擎要求 DSH >=0.2.2-rc.1 <0.3.0-0（README 标注开发验证于 DSH Web / Desktop 0.2.2-rc.1）。

核心功能¶

下面按 README 中的能力归纳，均经官方文档核对。

连接与工作区¶

• 使用系统 ssh 与 ControlMaster 复用连接，支持密钥、ssh-agent、密码（仅保存在 Host 进程内存）、ProxyJump 等现有配置。
• 自动解析 ~/.ssh/config（含 Include、Host 多别名、Host * 默认项），也可手动添加连接（写入插件状态，不修改你的 config 文件）。
• 远程目录选择器支持浏览、输入路径、新建目录；工作区保存在插件状态，左侧可随时切换。切换工作区或 Git worktree 时，会话列表与标签同步切换，其他目录上的进程可在后台继续运行。

Agent 与终端¶

• 通过登录 shell 的 PATH 检测多种 harness（如 Kimi Code、Claude Code、Codex、Gemini、OpenCode、Aider、Qwen、DSH 等），也支持「自定义命令」启动任意 CLI。
• 远程终端为 ssh -tt 提供的真实 PTY，由 xterm.js 渲染；支持调尺寸、复制粘贴、Ctrl+C。
• 远端若已安装 tmux，新会话会进入插件专用 tmux -L dsh-remote-agent server，断线后可重连；无 tmux 时仍保留会话名称、目录与近期输出，可「重新启动程序」。会话元数据与最近输出落盘到本机 $DSH_HOME/remote-agent/，DSH 重启后仍可恢复列表（主动删除才会移除记录）。

文件与 Git¶

• 右侧文件树：文本编辑、Markdown 渲染、图片 / PDF / HTML / 音视频预览、上传下载，以及新建、重命名、删除、复制剪切粘贴等；保存时使用 mtime 乐观锁，远端被改动的文件会提示重载。
• Git「更改」面板：分支、ahead/behind、暂存区与 diff、暂存与提交。
• 一键创建 Git worktree（独立分支 + 目录），自动切换为新工作区，便于并行跑多个 Agent（README 表述为参考 Emdash 的远程工作区体验，但不包含 PR/CI、issue 集成等）。

端口预览与其它¶

• SSH 本地转发：终端输出中出现 localhost:3000 等地址时可一键转发并在本机 127.0.0.1 预览；也可在顶栏手动管理转发。
• 工作区内 ⌘P / Ctrl+P 按文件名远程搜索打开；⌘⌥R / Ctrl+Alt+R 打开远程工作台；界面语言跟随 DSH（zh / en）。

流量全部走本机 OpenSSH，因此密钥、ssh-agent、ProxyJump、known_hosts 等行为与你在终端里直接 ssh 一致。

安装与启用¶

插件以当前 DSH Host 进程权限运行，安装前建议浏览仓库源码与 MIT 许可证，并确认本机为 macOS 或 Linux 且装有 OpenSSH 客户端。

预构建包（推荐）¶

Desktop 用户请在 DSH 插件管理中选择对应 Desktop profile 的包。通用 CLI 安装方式如下：

# Desktop 用户请在 DSH 插件管理中安装对应 Desktop profile 的包。
dsh plugin --profile <profile> add https://github.com/BeastyZ/dsh-remote-agent/releases/latest/download/dsh-remote-agent.tgz

安装后重新加载 DSH 页面；首次使用或在 Host 端更新插件后，按界面提示重启。左侧栏会出现 远程 Agent 图标。

从本地目录安装（开发）¶

在 DSH 的 plugin_manager 中执行 install_bundle，目标为插件的绝对路径；或使用：

dsh plugin --profile <profile> add /absolute/path/to/dsh-remote-agent

修改 client-src/ 后需在仓库内执行 npm install 与 npm run build 重新生成 client.js（该步骤面向改 UI 的开发者，普通用户用发行版 tgz 即可）。

典型用法¶

下面步骤对应 README「使用」一节，可按顺序复现。

1. 连接：左侧「连接」列出 ~/.ssh/config 主机，点击连接；需要时弹窗输入密码或密钥口令。
2. 工作区：点「工作区」右侧 +，在远程目录选择器选中目录；下次打开会自动恢复。
3. 启动 Agent：选中工作区后点击检测到的 harness 卡片，或在「自定义命令」里输入 CLI；工作目录为当前工作区。
4. 编辑文件：右侧树中打开文件，Cmd/Ctrl+S 保存；Markdown 可切换编辑与渲染。
5. Git：在「更改」页签查看 diff、暂存与提交；需要并行任务时点「新建 worktree」建独立目录并切换工作区。
6. 预览服务：在终端启动 python -m http.server 3000 或 npm run dev 后，点击输出中的端口快捷项，建立转发并打开本机预览 URL。

SSH 配置示例（插件会列出 Host 别名，实际连接受 OpenSSH 解析）：

Host gpu-lab
    HostName 10.0.0.12
    User root
    Port 2222
    IdentityFile ~/.ssh/id_ed25519
    ProxyJump bastion

适用场景与注意¶

适合谁：本机已配置好 SSH，远端是标准 Linux（sshd、GNU coreutils），且已在服务器 PATH 里安装 Kimi、Claude、Codex 等 TUI harness；希望在 DSH 单界面里完成「连服务器 → 选目录 → 开 Agent → 改文件 → 看 Git diff」，又不想在远端装 DSH 或同步整棵目录树。

边界（README 明确说明）：不做 GitHub PR/CI 面板、不做结构化 ACP 聊天、不做团队任务与双向文件镜像；Agent 运行在真实终端里，适合任意命令行 harness。

安全与状态：

• 状态文件默认 ~/.dsh/remote-agent/state.json，不保存密码；终端存档在 ~/.dsh/remote-agent/terminals/，权限 0600，可能含终端曾显示的敏感内容，应按本地敏感数据惯例管理。
• Host 注册 HTTP 路由 /remote-agent/api/rpc，默认与 DSH 一样仅监听 loopback；若你对 DSH 使用 --trusted-host 对外暴露，需自行评估该路由边界。
• 主机密钥默认 StrictHostKeyChecking=accept-new，可在插件设置中调整；最多同时 12 个 PTY 连接。

DSH 社区插件目录（如 skillhub.cn）由社区维护，与 DeepSeek / 幻方无官方从属关系；安装第三方插件前核对来源与权限范围是通用习惯。

结尾¶

dsh-remote-agent 把「SSH 上的目录 + 终端 + harness」收成 DSH 里的一块工作台：复用本机 SSH 配置，远端零额外服务，并补齐远程文件、Git worktree 与端口预览。需要安装包、Issue 与源码时，见 GitHub 仓库 与 skillhub 目录页。