前言¶

在 DSH 里做智能体开发，常见做法是本地开 workspace、会话和终端都在本机 runtime 上跑。模型和算力在另一台机器、或希望远程目录就是真实工作区时，往往会再搭一套远程 Web、自定义聊天面板，或依赖 dsh-remote 一类方案，本地界面和远程执行容易分裂。

下面介绍社区插件 dsh-remote-sessions（维护者 atlas5301）：它是 standalone native-session backend，不自带客户端入口、自定义聊天面板、远程 Web 应用或浏览器依赖，也不依赖 dsh-remote。本地仍是 Existing native DSH frontend（unchanged），通过 ordinary session API、本地「仅元数据」会话与 backend proxy，经 strict SSH / bounded protocol 连到远端独立托管的 DSH 与 companion，远程侧仍是 AgentLoop、模型、工具、文件与持久化。会话、文件树、终端、Composer、审批与历史都走原有原生 UI。

这是什么¶

• 名称：dsh-remote-sessions（npm 包名同插件名）
• 分类：在 SkillHub 目录 中归为「客户端」；实现上为 backend-only，原生 UI 不变
• 维护者：atlas5301
• 源码：github.com/atlas5301/dsh-remote-sessions

一句话：在 strict-SSH 常驻（resident）生命周期 之上，做 session / 文件树 / 终端转发 与 持久化 binding，让你在本地 DSH 里像用本地 workspace 一样操作远程 Agent，而不用改核心或换界面。

核心功能¶

架构分层¶

资料中的结构可以概括为：

Existing native DSH frontend (unchanged)
                  │ ordinary session APIs
Local metadata-only session + backend proxy
                  │ strict SSH / bounded protocol
Independently supervised remote DSH + companion
                  │
Remote AgentLoop, models, tools, files and persistence

设置页与托管 workspace¶

插件提供 一个原生设置分区「Remote Sessions」及对应 backend，没有额外 chat 面板、侧栏入口或 workspace 选择器接管。

• Machines：按名称与 SSH 目标添加机器；Detect 为只读 SSH 探测（Node 路径/版本、npm、已装 DSH CLI，并填充 socket 与目录等安全默认值）；Start 触发自动 setup；有新版 resident bundle 时出现 Upgrade（远程仍有活跃工作时会拒绝）。仍有关联 workspace 的机器不能删除。
• Remote workspaces：Open remote workspace 在 strict SSH 上浏览（机器 → 目录 → 可选新建文件夹 → 打开）。打开时会：在远程 DSH 上创建真实 workspace（转发 workspace/create，幂等）；链接插件管理的本地 anchor（~/.dsh/remote-sessions/anchors/…，用户无需手建）；启动原生 workspace 与首个 session，之后由普通 UI 接管。一台机器可多个 workspace，多台机器并存；每条映射是 一个 managed anchor ↔ 一个远程目录。Unlink 只删映射，anchor 与远程 workspace 仍保留。

本地 anchor 不是同步镜像，也不托管远程 agent；相对路径 @file 补全来自远程 session；上传文件进入远程 attachment 存储。映射只作用于 新创建的 session；已有本地 session 不会静默迁到远程。持久化 proxy binding 保留机器 authority、runtime UUID、进程实例、session ID 与目录，即使之后改配置。

远端 resident 自动 setup¶

安装本地插件 不会 主动 SSH；配置好的机器 首次使用 时，传输层先走 strict SSH relay，若 private socket 不存在，setup facade 会在一次重试前运行：

1. Detection：只读探测 node 版本、DSH CLI 路径/版本、resident 标记（<runtimeDirectory>/resident.json）、private socket 及 PID。
2. Reuse：已在服务的 socket 不会被停、换或重写。
3. Start：已 provision 但未运行的 resident 用记录的 CLI 启动，不改文件。
4. Provision：缺失则创建——私有目录、经 stdin 上传 resident bundle（tar）、组合 @deepseek-ai/dsh-base 与 resident bundle 的 profile、detach 启动（setsid，失败则 nohup）并写 PID。远端无 DSH CLI 时，npm install -g @deepseek-ai/dsh@<version> 与本地 runtime 同版本。

版本管理：GET /remote-sessions/runtime/status 报告各机 runtime/node/bundle 与可升级情况；POST /remote-sessions/runtime/ensure 与 POST /remote-sessions/runtime/upgrade 针对单机操作。升级在远程 session 仍在跑（ACTIVE_WORK_PRESENT）或 socket 无法经记录 PID 验证/监管（ACTIVE_WORK_UNVERIFIABLE、RESIDENT_UNSUPERVISED）时会拒绝；仅停该 PID，再 re-provision 并重启，之后旧 binding 与任意远程进程重启一样 fail closed。可在机器上设 autoSetup: false 完全关闭自动 setup；npmInstall: false 禁止远端 npm 安装。

生命周期相关字段（remoteCli、remoteHome、residentProfile、runtimeDirectory、dshVersion、autoSetup、npmInstall）不参与执行 authority；仅改 setup 字段时，已有 binding 仍保持 pinned identity。

Remote Web 按钮¶

设置页 Web 打开 machine-scoped web bridge profile（rs-web-<machine>）：在远端用 resident 的 session/attachment/credential store 与同步后的模型目录组合 Web UI。两侧 session、模型与凭证一致——在 bridge Web 里建的 session 可通过 list adoption 出现在本地 workspace，本地创建的 session 也会出现在 bridge。

手动 YAML¶

仍支持手写配置（与设置页写入同一套 machine-registry 校验并持久化）：

- id: remote-sessions
  config:
    machines:
      - name: build-host
        ssh: [user@build-host]
        remoteNode: /usr/bin/node
        socketPath: /home/user/.dsh/rs-runtime/agent.sock
        remoteCwd: /srv/project
        authorityRevision: '1'
    workspaces:
      - localPath: /absolute/local/remote-project-anchor
        target: build-host
        remotePath: /srv/project

请使用规范绝对路径，勿用 symlink 别名；更具体的 configured root 优先。若远程根是 symlink，backend 会在启动时将映射根解析为 canonical 形式，两种拼写视为同一目录。

资料中 Version 0.8.10 status 说明：源码已实现，在 DSH 0.2.0-rc.2 上与隔离真实 runtime 测试，并在 live 远程主机上经 strict SSH 验证端到端（provisioning、模型/凭证同步、session proxy、文件树、终端、升级与重启流程）。npm 上 package 版本以发布页为准（资料中 package.json 为 0.8.11）。

安装与启用¶

在 DSH profile 中安装（插件为 backend-only，原生 UI 不变）：

dsh plugin --profile web add dsh-remote-sessions     # 或: --profile desktop

然后 重启该 profile 的 runtime，打开 Settings → Remote Sessions 添加机器。上述命令为官方渠道；资料还列出：

• npm：在 profile 内 npm install dsh-remote-sessions，或 dsh plugin --profile web add npm:dsh-remote-sessions@0.8.3 固定版本。
• GitHub：dsh plugin --profile web add github:atlas5301/dsh-remote-sessions（releases 与发布版本对应）。
• Plugin Hub：在 DSH Plugin Hub 或 Settings → Plugin Hub 搜索 dsh-remote-sessions 从目录安装。

环境要求（资料原文）：

• 本地与远端主机均需要 DSH 0.2.0-rc.2 或更高（0.2.x）
• Node 22.15+
• SSH 须 非交互 认证（密钥或 agent），且登录用户与拥有 runtime 目录的 Unix 用户一致

典型用法¶

1. 按上一节安装插件并重启 runtime。
2. 进入 Settings → Remote Sessions，添加机器（名称 + SSH target），点 Detect 填充 Node/DSH/路径默认值。
3. 点 Start 完成首次 resident setup（或依赖首次打开 workspace 时的自动流程）。
4. 在 Remote workspaces 使用 Open remote workspace，选远端目录（建议如 ~/dsh-workspaces/<name> per 项目，不建议 把整个 home 当作 remote workspace root，否则 resident sandbox 缺少跨 workspace 写隔离）。
5. 在原生 workspace 中照常开会话、看文件树、开终端；需要时在设置页用 Web 打开该机的 bridge，与本地列表互通。

远端 runtime 版本可在设置或 API（/remote-sessions/runtime/status 等）查看；有 bundle 更新且无活跃远程工作时再 Upgrade。

适用场景与注意¶

适合：希望在 同一套 DSH 原生界面 里操作 远程真实目录 上的 AgentLoop；需要 strict SSH、resident 生命周期与 持久 binding；多机、每机多 workspace 的映射管理。

注意：

• 插件在本机 DSH profile runtime 内作为 backend 运行，会以 当前 dsh 进程权限 发起 SSH、写本地 anchor 与配置；安装前请阅读 源码 与仓库 LICENSE，自行评估信任边界。
• SSH 必须免密（或 agent）且用户与远端 runtime 目录所有者一致，否则探测与 setup 无法自动化。
• 社区目录 SkillHub 与 DSH Plugin Hub 为生态站点，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本文仅介绍该插件在资料中写明的能力。

结尾¶

dsh-remote-sessions 把远程 DSH 收成「本地元数据 + backend proxy + strict SSH resident」，会话、文件树与终端仍走未改动的原生 UI，并支持设置页托管 workspace、runtime 升级与 machine-scoped Web bridge。进一步细节见 GitHub README（含 中文 README）与 SkillHub 插件页。