前言¶

在 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 插件頁。