dsh-remote-subagent
English · 简体中文
DSH（DeepSeek Harness）远端子代理插件：本地会话用 remote_agent 工具把任务派给远端 DSH（SSH 上的另一台机器），远端 agent 用它自己的模型、工具与沙箱干活，思考 / 工具调用 / 工具结果 / 最终答复实时流回本地会话，并可在同一远端会话上追加消息——用法与内置 subagent 类似，但执行发生在远端机器里。
本地会话 ── remote_agent 工具 ──SSH──> 远端 dsh headless --json <task>
▲ │
└──── 事件流（thinking / tool_call / tool_result / final）◄──┘
为什么用远端 dsh headless --json
DSH 自带 headless 入口，--json 会把一次 run 的过程按行输出为 JSON 事件；--session-id 可续跑同一个 Session：
dsh headless --json '<task>' # 新远端会话
dsh headless --json --session-id <id> '<msg>' # 同一会话续跑
插件通过 SSH 的 exec 通道直接读这个流，因此：
- 不需要在远端开公网端口，也不需要 token / WebSocket 协议；
- 远端 agent 用它自己的模型配置、工具、沙箱与 session 存储（session 落在远端
$DSH_HOME/sessions，在远端 DSH Web UI 里同样可见）；
- 追加消息用
--session-id，语义与 subagent 的 send 一致；
- 事件流本身就是「工作过程」，不需要额外埋点。
安装
# 从 npm 安装到当前 profile（bundle 形式）
dsh plugin --profile <profile> add dsh-remote-subagent
# 或在 DSH 插件市场/plugin_manager 里安装 dsh-remote-subagent
依赖会自动安装（ssh2）。启用后：左侧栏出现「远端代理」图标，模型侧多出 remote_agent 工具。
机器从哪来
不重复配置 SSH 清单：目标机器读取 dsh-remote 的注册表
$DSH_HOME/remote-workspaces/machines.json
解析顺序：插件 config.machineId → 注册表 currentId → 第一个已保存机器 → config.machine（独立部署无 dsh-remote 时用）。支持密码、私钥（含 passphrase）、SSH agent。主机密钥采用 TOFU：首次连接把指纹记录到 $DSH_HOME/dsh-remote-subagent/known_hosts.json，之后必须匹配。
工具：remote_agent
| action | 作用 | 关键参数 |
|---|
spawn | 起一次新的远端 run（独立远端会话） | task, machine?, cwd? |
wait | 阻塞等 run 结束或超时（默认 30s，上限 120s；超时不影响远端继续跑） | runId, waitSeconds? |
get | 状态 + 最近 N 条过程事件 + 结果 | runId, eventLimit? |
send | 给同一远端会话追加消息（新 run，--session-id 续跑，turn+1） | runId, task |
list | 最近的 run 列表 | limit? |
cancel | 终止远端进程（按 pid 文件 kill -TERM） | runId |
machines | 可用的远端机器 | — |
典型用法：
remote_agent({action:"spawn", task:"在 /opt/app 跑一次只读健康检查：磁盘、内存、监听端口，最后总结"})
→ runId
remote_agent({action:"wait", runId, waitSeconds:120})
remote_agent({action:"get", runId, eventLimit:30})
remote_agent({action:"send", runId, task:"把监听端口按大小排序再列一次"})
复用语义：spawn 永远新建远端会话（等于 subagent 的 spawn）；send 复用该 run 所属的同一远端会话（等于 subagent 的 send_message）。多个 spawn 并发 = 多个互不共享上下文的远端会话；同一会话同一时刻只能跑一个 turn。run 历史与 sessionId 持久化在本地，DSH 重启后仍可 send 续跑。
面板（Client 半）
左侧栏「远端代理」→ 主面板：
- 左列：新建任务（选机器 + 任务文本 + 派活）、run 列表（状态点 / 任务摘要 / 机器 / 用时）；
- 右列：run 详情（状态、远端 session id、cwd、轮次、事件数、token）、实时事件时间线（1.5s 轮询增量、自动滚底）、结果框、终止 / 刷新、追加消息输入框。
数据接口（同源；Desktop 走 /api 前缀，Web 走裸路径）：
GET /dsh-remote-subagent/runs
GET /dsh-remote-subagent/run?id=<run>&from=<seq>&limit=<n>
POST /dsh-remote-subagent/action {action: spawn|send|cancel, ...}
配置（可选）
插件配置在 profile 的 cordis.patch.yml 的 config: 下，全部可省略：
| 字段 | 默认 | 说明 |
|---|
machineId | '' | 默认机器（id/名称/host） |
machinesFile | '' | 自定义机器注册表路径 |
headlessCommand | dsh headless | 远端命令前缀 |
cwd | '' | 远端工作目录（空 = 机器 home） |
maxConcurrent | 4 | 并行 run 上限 |
timeoutSeconds | 900 | 单 run 上限，超时自动终止远端进程 |
maxEvents | 4000 | 每个 run 保留的事件上限 |
connectTimeoutMs | 20000 | SSH 连接超时 |
本地数据
$DSH_HOME/dsh-remote-subagent/runs/<runId>.json：每个 run 的元数据 + 事件 transcript（重启后历史仍在；重启瞬间仍在跑的 run 标记 failed/interrupted，但保留 session id，可 send 续跑）；$DSH_HOME/dsh-remote-subagent/known_hosts.json：TOFU 主机指纹。
实测状态（v0.1.0，2026-11-04）
在一个 Linux 远端（DSH 0.2.0-rc.2，SSH 密码登录）上跑通：
spawn → 11s / 23 条事件 / turn 1，含 tool_call 与 tool_result；send 续跑同一 session-*，turn 2 正确引用上一轮上下文，回答数值与 turn 1 一致；- DSH 重启 + 插件热重载后
send 仍能续上同一远端会话（turn 3）；
cancel 后远端无残留 dsh headless 进程，pid 文件清理；- 面板槽位注册（
sidebar.panellist id=remote-agents、main key=remote-agents）与三条面板接口的处理器行为均有单测/实测覆盖。
单测覆盖（离线，无网络）：机器解析顺序与报错、事件流解析/分页/续跑/取消/持久化、面板路由、SSH 引用与 TOFU 指纹、Client 槽位注册。
已知边界
- 远端需要
dsh 在 SSH 登录 PATH 上，且 headless profile 可用；远端版本过老、没有 --json / --session-id 时不可用；
- 只支持 POSIX 远端（命令用
sh -c 包装）；Windows 远端未实现；
- 不支持 dsh-remote 的
useSshConfig 别名机器与 ProxyJump 跳板（请用直连条目）；
- 远端 run 的模型/工具/沙箱完全由远端 profile 决定，本地不能改；
wait 超时不会终止远端 run；运行中不支持插话，需 wait 或 cancel 后再 send；- 事件流覆盖 headless 单 turn；远端 agent 若把活丢进后台 job，其后续输出不在本 run 流里。
回滚
- 卸载：从 profile 移除
dsh-remote-subagent bundle；
- 清数据：删除
$DSH_HOME/dsh-remote-subagent/（run 历史 + TOFU 指纹）；
- 对远端无持久改动：仅
/tmp/dsh-remote-subagent-*.pid（正常结束自动清理）与远端 session 目录。
License
MIT
