dsh-remote-agent

dsh plugin --profile web add dsh-remote-agent

dsh-remote-agent



简体中文 | [English](README.en.md)

把另一台电脑变成你 DSH 的远程 Agent 同事。

副机拥有自己的 DSH 与独立 Agent 循环，任务在它本地持久运行；主电脑只拿到

handoff 结果卡与产物清单，成品要显式拉取才过河。

┌─────────────── 主电脑（hub）────────────────┐
│  DSH · 模型 · 会话日志 · 全部凭证            │
│  ┌─ dsh-remote-agent ─────────────────────┐ │
│  │ 19 个 remote_* 工具 + Web 面板          │ │
│  └────────────────────────────────────────┘ │
└──────────────────▲──────────────────────────┘
                   │ 节点主动拨入（direct / relay）
┌──────────────────┴──────────────────────────┐
│  ┌─ 副电脑（worker）───────────────────────┐ │
│  │  独立 Agent 循环 · 独立模型上下文        │ │
│  │  D:\work\**  中间产物留在这里            │ │
│  └────────────────────────────────────────┘ │
└─────────────────────────────────────────────┘

状态 · 0.9.5 —— 主机 + 副机端到端可用；exec 与 agent 双链路均已在两台真机上验证通过；CI 覆盖 Windows / macOS / Linux

DSH · 桌面版 / CLI，0.2.0-rc.2 验证

平台 · Windows（全量验证）· Linux / macOS（CI 覆盖）

依赖 · 零外部 npm 依赖 —— 只用 node: 内置模块

Node · ^22.19.0 \ · \ · >=24.0.0

测试 · 987 项（985 pass / 2 skip）· 123 条文档漂移断言 · eslint 严格档

Web 面板（侧栏「远程同事」）：节点列表（含 CPU/内存徽章）、派发任务、

任务状态、结果摘要、工作区变更、成品清单、日志尾巴、环境体检、

工作区共享（SMB）、模型下拉。

开箱即用：装完重启 DSH 就能用。包内 patch 默认 role: auto（没配

hubUrl 就是主机），自动生效。

副机连的是插件自己的端口，不用改 DSH 的任何配置。 0.9.3 起本插件自己

开一个独立监听（默认 19387），副机直接拨这个端口 —— **不再依赖

webserver**，也就不用去 cordis.patch.yml 里填 host。

绑哪个地址是自动选的：listenHost（如果你填了）> Tailscale IP >

局域网 IP > 回环。想指定就配 listenHost: '100.x.x.x'；

0.0.0.0 一律拒绝（新版 DSH 硬拒通配地址，绑了会让 DSH 启动崩溃）。

详见下方「安装」。

<p align="center">

<img src="docs/screenshots/panel-main.png" width="720" alt="Web 面板：节点、派发表单、任务列表">

</p>

<p align="center">

<img src="docs/screenshots/panel-task-detail.png" width="720" alt="任务详情：结果摘要、工作区变更、成品清单">

</p>

---

五分钟上手

按你的动手能力选一条路线，每条都通向同一个终点：

路线 · 主机 · 副机 · 适合

① 零终端（Windows） · 双击 bin/setup.cmd → 回车 → Web 面板「副机接入」复制配对码 · 双击同一文件 → 粘配对码 → 回车自动写盘 · 见到黑窗口就慌

② 向导（推荐） · 终端跑向导 → 回车确认写盘 · 同左，粘配对码 · 会开终端

③ 手动 · 参照下文配置节手写 · 手写（inject: [] 必加） · 想完全掌控每行

任一路线完成后：两台重启 DSH，对主机说一句「副机上有哪些节点在线？」——

在线即通。出问题跑 --doctor 体检，每项 ✗ 都带怎么修。

node bin/dsh-remote-setup.js

Windows 不想开终端？ 在插件的 bin/ 目录里**双击

setup.cmd** —— 打开的窗口里全程回车即可。

插件装在 %USERPROFILE%\.dsh\dsh_orb\dsh-plugin\dsh-remote-agent\bin\。

1. 主机上跑：选「1=主机」→ 向导自动找本机局域网 IP、生成 nt_ 强随机

nodeToken、输出副机配对码（一行 dshra1://…）与两台机器的完整 YAML

（含防火墙放行命令）。

2. 副机上跑：选「2=副机」→ 直接粘贴主机给的配对码（或手抄地址与

token）→ 向导会先探活主机端口，然后生成副机配置。最坑的 inject: []

已替你填好（不填它副机会永远静默不上线）。副机配置里也可以只写一行

pair: '<配对码>'，运行时自动展开成地址与 token（显式配置优先，写

hubUrl: 可临时覆盖）。

3. 两台重启 DSH，对主机说一句「副机上有哪些节点在线？」—— 在线即通。

4. 免终端路径（图形界面）：打开主机的 Web 面板 →「副机接入」按钮 →

一键生成并复制配对码（含防火墙放行命令）。主机面板派任务时也可在

「模型」栏指定副机用的模型（留空用副机默认）。

5. 出问题就体检（读取配置文件逐项检查，每项 ✗ 都带怎么修）：

node bin/dsh-remote-setup.js --doctor 你的配置.yml

不想交互？一条命令直接生成：`--role worker --hub-url 192.168.1.10:19387

--token nt_xxx --roots D:\work --node-id slave-pc`。

---

功能

一、把任务派给副机

功能 · 说明

两种任务模式 · exec 直接跑命令（D:\work 里 npm run build、git pull、批量重命名）；agent 让副机起独立 Agent 会话，它自己规划、调工具、写文件

两阶段审批 · exec 默认挂起等确认（approval: 'manual'）——等不到人不执行。防止 AI 误派危险命令

dry-run 预览 · 派发前先看"会路由到哪台、用哪个模型、在哪个目录跑、预计什么产物"，不真派

仓库感知调度 · 副机上报它 roots 下的 git 仓库（名字 + 远端 url），remote_task({repo: 'my-project'}) 自动找有那个仓库的副机

负载感知路由 · 副机每 30s 上报 CPU/内存/负载；不指定节点时按负载挑一台

模型选择 · 面板从副机自述的可用模型清单里下拉选（不用猜 provider/model 名）；headless 后端不支持指定模型时派发前就拦，不用等跑到副机才失败

超时按模式区分 · exec 默认 10 分钟（失控命令不该占机一小时）；agent 默认 1 小时

并发上限 · 副机 maxConcurrent（默认 4）限制同时跑几个任务；超出的排队，remote_status 能看到排队数与最久等待

二、拿结果，但不搬整个工作区

功能 · 说明

handoff 结果卡 · 任务结束回一张卡：结果摘要 + 工作区变更 + 成品清单 + 退出码。不是把整个目录传回来

产物三分类 · 工作区文件按 final / intermediate / other 分类，只有 final 能拉。日志、缓存、node_modules 全留在副机

显式拉取 · 要哪个文件用 remote_pull 单独拉，支持 glob 过滤

断点续传 · 拉到一半掉线不从头重传：已收字节保留，重试从中段续（startOffset + prefixSha256 校验）

变更 diff 视图 · 任务前后对比工作区，看清它到底改了哪些文件、增删多少字节

三、直接翻副机的文件（不占任务队列）

四个只读工具，走独立的 fs/req↔fs/res 帧 —— 不进任务队列、不占并发槽。

副机正跑长任务堵着队列时，这些依然秒回：

工具 · 用途

remote_ls · 列目录（单层、分页）

remote_read · 读文件（文本按行分段；二进制只回元数据）

remote_grep · 副机本地全文搜索（纯 JS，不 spawn 进程）

remote_tree · 目录树摘要（扫描在副机跑完，只回结构）

安全边界：路径必须在该节点 roots 内、denyPaths 生效、符号链接只列条目不解引用。

四、用本地 IDE 打开副机的文件（SMB 共享）

面板上「工作区共享」区：把副机工作区通过 SMB 共享出去，主机

net use X: \\副机\dsh-work-... 映射成盘符 —— 可以用本地 VS Code 直接打开。

⚠ 这会绕过本插件的安全边界（roots / denyPaths 失效、中间产物与密钥

对主机可见、新增凭证面）。需要二次确认，默认只读。

完整风险与用法见 [docs/workspace-share.md](docs/workspace-share.md)。

五、出问题能自己诊断

功能 · 说明

环境体检 · 面板一键体检 8 项：角色配置、inject 依赖、Web 服务是否绑在可达地址、端口、防火墙、roots 是否存在、Tailscale、副机在线。每条都给具体修法，能自动修的标出来

一键修复 · 机械可判定的项（webserver host、role）可以预览后一键修。见下面「七、一键修复」

错误翻译成人话 · ECONNREFUSED / 401 / timeout after 40000ms 这类原始错误统一翻译成「哪里没对 + 下一步做什么」。覆盖 errno、17 个协议错误码、HTTP 状态、文案特征

连接失败可见 · 记录每一次副机连接尝试（成功/失败 + 原因 + 时间 + 远端地址）。面板直接显示「最后尝试 2 分钟前 —— 握手超时 → 检查…」，并区分从没连过 / 连过又断了（排查方向完全不同）

外部工具检测 · 一键探测 Tailscale / PowerShell / git / Node.js 在不在，缺了告诉你「为什么需要 + 安装命令 + 官方链接」。见下面「八、外部工具」

可达性自检 · 启动时检查端点是否绑在 loopback —— 绑了副机永远连不上，且主机侧毫无异常。绑了会打明确 warn + 面板红色横幅

队列健康快照 · 副机随资源帧上报 queued / running / maxConcurrent / 最久等待；堵死时面板与 remote_nodes 都会警告

面板「运行中」分组 · 运行中的任务置顶，显示已跑多久，并直接显示**最近一步在干

…(truncated)