本教程面向手头有多台电脑的开发者,讲解如何把多台机器组建成一条受控的开发流水线:A 设备的 Qoder 作为控制端,B 设备的 DeepSeek Harness 作为执行端,A 侧通过 a4agent 的设备互联能力在 B 侧执行命令、取文件、看屏幕,并可查询 B 侧 Agent 会话的实时进度。教程从两台设备起步,逐步扩展到多设备集群。教程包含完整的环境准备、配对流程、协同协议设计与可运行的示例脚本。
前置教程
如想快速开始学习本教程,你可能需要先完成以下前置教程:
- DeepSeek Harness 安装与使用教程,B 设备侧的执行端由 DeepSeek Harness 承担,需先完成安装与模型配置。
- DeepSeek Harness等Agent Skill安装与应用教程,跨设备控制能力以 Skill 形式提供给 Agent,需了解 Skill 的安装机制。
- 一键配置DeepSeek Harness等Agent桌面、手机提醒教程,a4agent 的桌面与手机提醒是跨设备状态汇报的旁路通知通道。
- Harness概念详解,理解 Harness 在 Agent 架构中的定位,有助于理解控制端与执行端的职责划分。
资源下载
- Qoder 下载地址,A 设备侧使用的 agent 形态,支持 Windows、macOS、Linux 与 HarmonyOS。注意 Qoder IDE 是另一个独立产品形态,本教程使用 agent 形态。国内访问可改用 qoder.cn。
- a4agent 安装包与使用文档,设备互联与跨设备控制能力的托管端,每台参与互联的设备都需要安装。
- CrossDevice 项目主页,被控端 node 运行时的上游项目,a4agent 安装包已内嵌,独立部署时需要。
1. 跨设备协同的适用场景
1.1 为什么需要多台设备协同
单体开发机在以下场景会遇到瓶颈:
| 场景 | 单机限制 | 多设备协同的做法 |
|---|---|---|
| 长时间构建与测试 | 占用本机全部算力,编辑器卡顿 | 把构建、测试、代码检查分发到执行端设备 |
| 平台相关验证 | 本机是 Windows,需要在 Linux 环境验证 | 执行端常驻 Linux 或 WSL 环境,控制端远程驱动 |
| 多批次并行开发 | 一条线跑长任务时无法同时推进另一条线 | 各设备各跑一条线,按文件面划分互不干扰 |
| 模型额度与算力分摊 | 单机 API 并发受限 | 各设备各自配置模型通道,额度合并使用 |
| 多工具能力互补 | 单一工具的能力侧重固定,难以覆盖全流程 | 按工具特长分配角色,例如一个设备负责编码、另一个负责测试与审查 |
随着设备数量增加,协同关系从「一台控制一台」演进为「一台汇总多台」,最终形成可以按任务分派的设备集群。
1.2 控制端、执行端与汇报通道
跨设备协同要求各设备明确分工,同时建立一条反向的状态通道:执行端在会话的关键节点主动向控制端汇报进度,控制端无需反复查询。
Qoder 控制端] A -->|a4agent 本地 API| AH[a4agent
回环 127.0.0.1] AH -->|TLS + 令牌
下发指令| BN[B 设备
CrossDevice node] BN --> B[B 设备
DeepSeek Harness] B -->|hook 主动写入
回合完成/提问/权限| ST[状态目录
node/tmp/status] ST -->|每 15 秒拉取| AH AH -->|状态入库| A B --> Repo[代码仓库] A -->|git pull 合并| Repo style User fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style A fill:#ffecd6,stroke:#e67e22,stroke-width:2px style AH fill:#d6eaf8,stroke:#2980b9,stroke-width:2px style BN fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style B fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style ST fill:#fdebd0,stroke:#b7950b,stroke-width:2px style Repo fill:#fadbd8,stroke:#c0392b,stroke-width:2px
链路包含两个方向:
| 方向 | 承载方式 | 传输内容 | 发起方 |
|---|---|---|---|
| 控制端到执行端 | CrossDevice node 的 HTTPS 接口 | 命令、文件、截屏请求 | 控制端主动 |
| 执行端到控制端 | hook 写状态目录 + 控制端轮询拉取 | 会话事件、状态、时间戳 | 执行端自动 |
反向通道由宿主级 hook 完成,执行端的 Agent 会话在回合结束、申请权限、等待回答三类节点触发 hook 进程,把一条状态原子写入本地状态目录;控制端每 15 秒经 node 的文件读取接口拉取一次并入库。这条通道不需要任务提示词写任何上报逻辑,对该端所有会话自动生效。
职责边界:
| 角色 | 位置 | 承担的工作 |
|---|---|---|
| 控制端 | A 设备 | 需求拆分、任务书生成、进度跟踪、代码合并、最终验收 |
| 执行端 | B 设备及后续设备 | 按任务书执行、产出代码与证据、推送到仓库 |
| 下发通道 | 两端 | a4agent 托管配对凭据,CrossDevice node 承载远程执行 |
| 汇报通道 | 两端 | 执行端 hook 写入状态目录,控制端定时拉取 |
| 汇聚点 | 代码仓库 | 执行端 push,控制端 pull 后合并 |
1.3 与远程桌面工具的差异
远程桌面工具传递的是画面与键鼠,跨设备协同传递的是命令、文件与会话状态。
| 维度 | 远程桌面 | 跨设备协同 |
|---|---|---|
| 传输内容 | 屏幕像素 + 键鼠事件 | 命令、文件、结构化状态 |
| 带宽占用 | 高,随分辨率与帧率上升 | 低,按需传输 |
| 可被 Agent 调用 | 否,需要人操作 | 是,通过本地 HTTP 接口 |
| 执行留痕 | 通常无 | 被控端完整审计日志 |
| 适合的任务 | 图形界面操作 | 命令行、构建、测试、批处理 |
2. 环境准备
2.1 各设备共同的前置条件
| 项目 | 要求 | 检查命令 |
|---|---|---|
| 操作系统 | Windows 10 及以上(CrossDevice node 仅支持 Windows) | winver |
| a4agent | 每台参与互联的设备都安装并运行,安装包已内嵌 node 运行时所需的 Python 解释器 | 见 2.2 |
| Qoder | A 设备安装 agent 形态 | 见 2.3 |
| DeepSeek Harness | 执行端设备安装并完成模型配置 | 见 2.4 |
| 网络 | 各设备可达同一私有网段 | 见第 4 章 |
| Python | 仅运行第 6 章示例脚本时需要,3.10 及以上 | python --version |
a4agent 的安装包在 node_runtime/ 目录下自带一个嵌入式 Python 解释器,被控端无需另外安装 Python 即可提供远程执行能力。Python 只在运行本教程第 6 章的示例脚本时才成为必需项。
2.2 在各设备安装并启动 a4agent
a4agent 是设备互联的托管端,它把 CrossDevice node 作为独立子进程拉起并守护。每台参与互联的设备都要安装。
启动后确认实例文件存在,其中记录了后端端口:
Get-Content "$env:APPDATA\a4agent\desktop.json"
输出示例:
{"port": 57037, "pid": 36856}
后端只监听 127.0.0.1,端口随机分配并记录在实例文件中。这个设计意味着控制端接口不能被对端直接调用,所有调用方向固定为「本机 Agent → 本机 a4agent → 对端 node」。
2.3 配置 A 设备的 Qoder
Qoder 侧需要两样东西:跨设备控制 Skill,以及会话 hook 注册。
打开 a4agent 的设备互联页,在「已配对设备」区块点击「安装控制技能」,把 Skill 装到 Qoder 的技能目录。安装后的文件位置:
%USERPROFILE%\.qoder\skills\crossdevice\SKILL.md
hook 注册用于让 Qoder 会话在关键节点向 A 侧本体汇报状态。检查注册结果:
Get-Content "$env:USERPROFILE\.qoder\settings.json" | Select-String "a4agent"
应当能看到三条事件对应的命令,分别挂在 Stop、PreToolUse、PermissionRequest 下,命令形态为:
{
"type": "command",
"command": "\"C:\\Users\\<用户名>\\AppData\\Local\\Programs\\a4agent\\a4agent.exe\" hook qoder"
}
2.4 配置 B 设备的 DeepSeek Harness
DeepSeek Harness(下称 dsh)在 B 设备承担执行端。安装与模型配置按前置教程完成,本节只说明与跨设备协同相关的部分。
先确认 dsh 已安装,并且 profile 已经初始化:
dsh --version
dsh web --help
第二条命令只为触发 %USERPROFILE%\.dsh 目录生成,随后可以立即中断。初始化完成后目录结构如下:
%USERPROFILE%\.dsh\
.credentials.yaml 模型密钥
profiles\
web\ Web 界面 profile
headless\ 无头执行 profile
dsh 的 hook 不走外部命令回调,而是以 Cordis 插件形式在进程内加载。a4agent 的注册器做两件事:把插件复制到 ~/.dsh/a4agent-hook/,再往每个 profile 的 cordis.patch.yml 追加一段挂载声明。
检查注册结果:
Get-ChildItem "$env:USERPROFILE\.dsh\profiles" -Recurse -Filter "cordis.patch.yml" |
Select-String "a4agent-dsh-hook"
应当能看到形如以下的段落:
# ===== a4agent dsh-hook (auto-generated) =====
- insert:
- id: a4agent-dsh-hook
name: "../../a4agent-hook/index.js"
# ===== end a4agent dsh-hook =====
这段声明里的相对路径以 profile 目录为基准,../../a4agent-hook/index.js 指向 ~/.dsh/a4agent-hook/index.js。插件加载失败时 dsh 会打印 1 entry did not activate 与 ERR_MODULE_NOT_FOUND,并给出解析到的绝对路径,据此可判断插件是否放对位置。
验证插件是否真的在运行,最直接的方式是跑一次会话,观察标准错误输出中是否出现插件日志:
dsh headless "say OK"
正常时除了模型回答,还会多出一行:
[a4agent-dsh-hook] 任务完成 session-<会话号> turn=1
这行日志表示插件已在进程内加载并完成了状态写入。写入的文件位于被控端的状态目录,控制端可通过状态接口读到,具体见 5.5 节。
Skill 安装位置与 Qoder 不同,dsh 使用自己的技能目录:
%USERPROFILE%\.dsh\skills\crossdevice\SKILL.md
模型凭据的存放位置是 ~/.dsh/.credentials.yaml。文件按 refs 段存放各家厂商的密钥,键名与 profile 中 apiKeyEnv 的值对应:
version: 1
refs:
DOTS_API_KEY: '你的密钥'
dsh 读取密钥有两条途径:一是通过凭据服务写入,二是从启动环境继承环境变量。直接把文件放在该位置在部分版本上不会自动生效,此时把同名环境变量设进用户环境即可:
setx DOTS_API_KEY "你的密钥"
setx 写入的是用户级永久环境变量,新开的进程才会继承,设置后需要重新启动终端。
2.5 首次启动后的自检
两端各执行一次,确认 node 在监听:
netstat -ano | Select-String "LISTENING" | Select-String ":51888|:51889"
51888 是 node 的业务端口,51889 是 UDP 发现广播端口。业务端口使用 TLS,直接访问会握手失败,这是正常的。
3. 设备配对
3.1 配对机制的四个环节
配对解决的是「谁可以控制谁」这个信任问题。广播只负责让设备互相看得见,信任建立必须经人工确认。
每 10 秒] --> D2[设备出现在
发现列表] D2 --> D3[控制端点配对] D3 --> D4[B 侧弹窗
显示来源 IP] D4 --> D5[B 侧确认
生成 6 位码] D5 --> D6[A 侧输码] D6 --> D7[签发令牌
登记证书指纹] style D1 fill:#d6eaf8,stroke:#2980b9,stroke-width:2px style D2 fill:#d6eaf8,stroke:#2980b9,stroke-width:2px style D3 fill:#ffecd6,stroke:#e67e22,stroke-width:2px style D4 fill:#fdebd0,stroke:#b7950b,stroke-width:2px style D5 fill:#fdebd0,stroke:#b7950b,stroke-width:2px style D6 fill:#ffecd6,stroke:#e67e22,stroke-width:2px style D7 fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
配对关系是「控制端对每台执行端各建立一份信任」,同一控制端可按相同流程与多台被控端分别配对,凭据各自独立保存。新增设备只需重复一次配对流程,不影响已有设备。
3.2 在 A 侧发起配对
打开 a4agent 的「设备互联」页,在「发现的设备」中找到 B 设备,点击「配对」。
A 侧发起后,B 侧 a4agent 会弹出确认窗口并显示来源 IP,同时触发一条系统通知。B 侧不需要停留在该页面也能收到这条通知。
3.3 在 B 侧确认并取码
B 侧点击确认后,屏幕上出现一个 6 位配对码,有效期 5 分钟。把码输入 A 侧的输入框完成配对。
防滥用机制三道:
| 机制 | 取值 | 触发后的行为 |
|---|---|---|
| 配对码时效 | 5 分钟 | 超时返回 PAIR_EXPIRED |
| 猜码上限 | 5 次 | 达到上限返回 PAIR_ATTEMPTS_EXCEEDED,会话作废 |
| 发起限频 | 同一来源 10 秒一次 | 超频返回 PAIR_RATE_LIMITED |
3.4 验证配对结果
配对成功后,设备卡片会显示对端的主机名、地址、设备 ID 与配对时间。凭据由 a4agent 用 Windows DPAPI 加密保存,不会出现在任何接口响应中。

图中设备名、内网地址与设备 ID 为脱敏后的示例值。
卡片下方一行显示对端 Agent 会话的最新状态。上图的状态行显示「任务完成 / 已完成」,并标注「已过时」,表示该记录距今超过 45 秒。状态陈旧与链路中断是两件事:链路正常时该行只显示时间与陈旧标记;链路中断时会额外出现一行「拉取失败」,携带具体的连接错误。排查顺序是先确认对端 node 是否运行,再看状态时间是否刷新。
下方的「发现的设备」列表显示对端为「在线」,最近出现时间为当前时刻,说明 UDP 广播心跳正常。已配对设备与发现列表是两套独立信息:前者表示已建立信任,后者只表示当前能收到对方的广播。
用示例脚本确认:
python xd-agent/xd_agent.py devices
输出示例:
名称 地址 主机名
DESKTOP-B 192.168.1.22:51889 DESKTOP-B

进一步探活:
python xd-agent/xd_agent.py ping DESKTOP-B
返回结果包含三个字段:
{
"status": "up",
"node_version": "0.5.1",
"rollback_flag": false
}
status 为 up 表示链路可用;node_version 是对端 node 运行时版本,两端版本不同不影响基本操作;rollback_flag 表示对端是否处于回滚态。证书指纹变更时连接会被本地拒绝,报 TOFU 开头的错误,此时需要确认对端确实重装过,再在设备互联页重置指纹。
4. 网络条件与隔离限制
4.1 node 只接受私网来源
这是跨设备方案的核心约束,必须先理解清楚再动手。node 的每个请求都经过 guard(),第一道检查是来源 IP 是否属于私网:
def guard(self, parsed):
client = self.client_address[0]
# ① 来源校验:先于一切
if not is_private(client):
self.fail("FORBIDDEN", "仅允许局域网访问:%s" % client, 403)
return None
# ② 身份校验 → ③ 防重放
私网判定按 IP 段进行:
def is_private(ip):
if ip in ("127.0.0.1", "::1"):
return True
parts = ip.split(".")
if len(parts) != 4:
return False
try:
a, b = int(parts[0]), int(parts[1])
except ValueError:
return False
return (a == 10 or a == 127
or (a == 172 and 16 <= b <= 31)
or (a == 192 and b == 168)
or (a == 169 and b == 254))
判定表:
| 来源 IP | 网段归属 | 是否放行 |
|---|---|---|
127.0.0.1 |
回环 | 放行 |
192.168.3.29 |
RFC1918 /16 | 放行 |
10.8.0.2 |
RFC1918 /8 | 放行 |
172.20.0.5 |
RFC1918 /12 | 放行 |
169.254.1.1 |
链路本地 | 放行 |
100.64.0.1 |
CGNAT(Tailscale、ZeroTier 常用) | 拒绝 |
172.32.0.1 |
公网(超出 172.16/12 上界) | 拒绝 |
8.8.8.8 |
公网 | 拒绝 |
node 没有任何命令行开关或环境变量可以放宽这条限制。它的命令行参数只有端口、监听地址、令牌、工作目录白名单与调试明文开关,来源校验不在可配置范围内。
4.2 跨互联网场景的可行路径
两台设备不在同一局域网时,能否协同取决于网络能不能给出一个「被判定为私网」的源地址。
| 方案 | 是否可行 | 是否改码 | 说明 |
|---|---|---|---|
| 三层私网隧道(WireGuard 等) | 可行 | 不需要 | 两端各得 10.x 地址,node 看到的源地址就是私网 |
| 公网端口映射 | 不可行 | — | 源 IP 仍是对端公网地址,来源校验必拒 |
| 反向代理转发 | 需具体看拓扑 | 需部署 | 代理改变不了 socket 层的源地址,只有代理与被控端同机时才通过 |
| CGNAT 段组网(Tailscale、ZeroTier 默认段) | 不可行 | 需改码 | 100.64.0.0/10 不在白名单内,需修改 is_private |
WireGuard 等三层隧道的原理是给两台机器各分配一个隧道内私有地址,node 的来源校验天然满足,CrossDevice 无需任何修改。这是跨互联网场景的推荐路径。
4.3 隧道场景下的发现与配对
UDP 广播的发送目标是受限广播地址 255.255.255.255 加上本机各私网网卡的定向广播地址,这类报文不跨三层隧道转发。因此隧道场景下「发现的设备」列表收不到对端,属于预期行为。
补偿入口是 a4agent 的手动连接线索接口:
curl -X POST "http://127.0.0.1:<端口>/api/v1/devices/pool/manual" \
-H "Content-Type: application/json" \
-d '{"ip":"10.8.0.3","port":51888}'
该接口只校验 IP 字面量合法,不限制私网,因此可跨隧道指定目标。线索本身不构成信任,配对仍走一次确认流程。
界面上的对应入口是「发现的设备」区块右侧的「手动添加 IP」按钮。该区块在隧道场景下通常显示为空,因为广播报文不跨隧道;此时通过手动线索指定对端的隧道内地址即可。

5. 协同工作流设计
5.1 文件面互斥
多设备并行开发最容易出问题的地方是同一个文件被多方同时改。解决办法是按文件面划分所有权,每台设备只改自己的部分。
| 文件面 | 归属 | 典型内容 |
|---|---|---|
| 后端代码、数据库迁移 | 控制端设备 | 接口实现、表结构变更 |
| 前端代码、设计稿 | 执行端设备 | 页面组件、样式、原型 |
| 契约包 | 单一所有者 | 类型定义,任一方修改都需评审 |
| 共享文档 | 分节追加 | 协作看板按节归属,各自追加不重写他人节 |
设备数量增加时,文件面按「一个文件面只有一个所有者」的原则继续细分,新增设备承担新的文件面或接管已划出的独立模块。
5.2 单向汇聚的同步协议
代码同步采用单向汇聚:B 侧推送到远程仓库,A 侧拉取后合并。A 侧是唯一的合并点。
这套协议解决三个问题:合并冲突因文件面互斥而基本不发生;整仓检查只在合并点跑一次,避免各设备重复消耗;提交历史保持线性,便于追溯。
5.3 从两台扩展到设备集群
a4agent 的设备注册表以设备名为键,不限制已配对设备的数量,一份控制端可以同时管理多台执行端。扩充设备时按以下顺序推进。
控制端] --> B1[B1 执行端
前端] A --> B2[B2 执行端
测试] A --> B3[B3 执行端
文档与素材] B1 --> R[代码仓库] B2 --> R B3 --> R R --> A style A fill:#ffecd6,stroke:#e67e22,stroke-width:2px style B1 fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style B2 fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style B3 fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style R fill:#fadbd8,stroke:#c0392b,stroke-width:2px
扩充步骤:
- 在新设备安装 a4agent 与目标 Agent 工具,启动 node。
- 完成一次确认配对,控制端的设备列表增加一条记录。
- 在文件面表中为新设备划出独立所有权,避免与已有设备重叠。
- 给新设备分配独立的会话命名与证据目录前缀,便于在汇总时区分来源。
- 控制端先单独跑一个小批验证链路,再纳入正式分派。
多设备后需要额外注意的三点:
| 关注点 | 说明 |
|---|---|
| 状态汇总 | 状态接口支持一次拉取全部设备,无需逐台查询;每台设备的记录独立保留 7 天 |
| 缺陷与变更编号 | 各设备只提报编号申请,由控制端统一分配,防止跨设备撞号 |
| 合并顺序 | 各设备只改自身文件面,控制端按批次串行合并,不并行合并多台推送 |
5.4 编号统一分配
多设备并行时,缺陷编号、变更编号这类递增标识容易撞号。约定由合并点统一分配号段,执行端只提出编号申请,不自行占用。
5.5 状态汇报的机制
让远程任务可管理的关键是状态回向。A 侧需要知道 B 侧会话进行到哪一步,而不必反复截屏。
机制是宿主级 hook:B 侧 Agent 会话在关键节点触发 hook,hook 进程把一条状态原子写入本机状态目录,A 侧每 15 秒拉取一次。
触发汇报的关键节点有三类:
| 事件 | 含义 | A 侧反应 |
|---|---|---|
hook.stop |
回合完成 | 桌面弹窗提示 |
hook.permission |
权限申请 | 桌面弹窗 + 手机推送 |
hook.question |
提问等待 | 桌面弹窗 + 手机推送 |
状态的写入是原子替换:先写临时文件再 os.replace 覆盖,避免 A 侧读到半截内容。写入失败只记日志,不影响 hook 主流程。
查询方式:
python xd-agent/xd_agent.py status
返回每个设备最近一条会话状态,字段含事件、状态、Agent 类型、工作目录、摘要、时间与陈旧标记。超过 45 秒未更新的记录标记为陈旧。
以下是执行端为 dsh 时的实际返回:
{
"device": "DESKTOP-B",
"hostname": "DESKTOP-B",
"last_error": null,
"sessions": [
{
"session_id": "session-8a67bf07-...",
"event": "dsh.complete",
"state": "done",
"agent": "DSH",
"age_seconds": 51,
"event_label": "DSH 任务完成",
"state_label": "已完成"
}
]
}

不同 Agent 的汇报字段有差异:ZCode 一类走外部 hook 的宿主使用 hook.stop、hook.permission、hook.question 三类事件;dsh 的插件在进程内直接上报,事件名为 dsh.complete,agent 字段标为 DSH。控制端按 agent 字段区分来源,不必为不同工具写不同的解析逻辑。
last_error 为 null 表示本次拉取没有链路错误,与状态是否陈旧是两件事:状态陈旧只说明该会话有一段时间没有新的 hook 事件,链路本身可能是正常的。
5.6 任务提示词的组织
跨设备任务以「任务书」形式下发:任务书是一份自包含的文档,粘贴到 B 侧 Agent 会话即可执行,不依赖上下文记忆。
任务书应当包含的段落:
| 段落 | 内容 |
|---|---|
| 基线与环境事实 | 当前代码版本、已通过的检查结果、环境已知问题 |
| 目标与范围 | 本批要做的项,逐项列出验收标准 |
| 派发与纪律 | 子代理分工、文件面边界、禁止操作 |
| 纪律红线 | 不可越界的操作、证据真实性要求 |
| 交付与验收 | 产物形态、证据目录、检查项 |
任务提示词里不写轮询或汇报要求。hook 对被控端所有会话自动生效,A 侧通过状态接口查进度即可。
6. 示例项目:跨设备任务分发脚本
6.1 项目结构
按以下结构放置文件:
xd-agent/
xd_agent.py 命令行工具,封装 a4agent 本地接口
README.md 用法说明
脚本只依赖 Python 标准库,不需要安装第三方包。
6.2 核心逻辑
脚本的第一步是定位 a4agent 的后端端口:
def instance_port() -> int:
"""从 a4agent 实例文件读出 backend 端口。"""
appdata = os.environ.get("APPDATA")
if not appdata:
raise SystemExit("未找到 APPDATA 环境变量,无法定位 a4agent 实例文件")
path = Path(appdata) / "a4agent" / "desktop.json"
if not path.is_file():
raise SystemExit(f"未找到 {path},请先启动 a4agent")
try:
return int(json.loads(path.read_text(encoding="utf-8"))["port"])
except (KeyError, ValueError, json.JSONDecodeError) as exc:
raise SystemExit(f"实例文件内容异常:{exc}")
远程执行是异步的:下发后拿到 job_id,再用长轮询取结果。这一设计让长时间命令不会卡住本地请求。
def cmd_exec(args, agent: Agent) -> int:
started = agent.exec(args.device, args.cmd, shell=args.shell,
timeout=args.timeout, cwd=args.cwd)
job_id = started.get("job_id")
if not job_id:
_print(started)
return 1
print(f"已下发 job_id={job_id},等待结果(最长 {args.wait} 秒)…")
result = wait_job(agent, args.device, job_id, time.time() + args.wait)
_print(result)
code = result.get("exit_code")
return 0 if code == 0 else 1
轮询逻辑在终态或超时处退出,不会无限等待:
def wait_job(agent: Agent, name: str, job_id: str, deadline: float, interval: int = 5) -> dict:
"""轮询任务直到终态或超时。"""
result: dict = {}
while time.time() < deadline:
result = agent.job(name, job_id, wait=interval)
if result.get("status") in ("done", "failed", "timeout"):
return result
return result
6.3 子命令一览
| 子命令 | 作用 | 示例 |
|---|---|---|
devices |
列出已配对设备 | python xd_agent.py devices |
ping |
探活并取 node 版本 | python xd_agent.py ping DEVICE |
exec |
远端执行命令 | python xd_agent.py exec DEVICE "git status" |
workspaces |
查可写根与暂存目录 | python xd_agent.py workspaces DEVICE |
status |
查会话状态汇报 | python xd_agent.py status DEVICE |
tasks |
查任务历史 | python xd_agent.py tasks DEVICE --limit 20 |
wait |
轮询已有任务 | python xd_agent.py wait DEVICE JOB_ID |
6.4 实测结果
以下结果来自一台 Windows 控制端与一台 Windows 执行端在同一局域网的实际运行。
先探活,再执行远端命令:

ping 返回 status: up,对端 node 版本为 0.5.1。exec 下发 hostname,job_id 即时返回,随后长轮询取得结果:exit_code 为 0,stdout 为对端主机名,duration 约 0.1 秒。
这次实测覆盖的能力与结果:
| 操作 | 结果 |
|---|---|
探活 ping |
status: up,node 版本 0.5.1 |
远端执行 exec |
exit_code: 0,耗时 0.107~0.128 秒 |
| 远端写文件后读回 | exit_code: 0,内容一致 |
| 上传到暂存目录 | 返回 md5,远端读取内容与本地一致 |
| 上传到白名单外路径 | 返回 SANDBOX_DENIED,附允许根路径 |
| 截屏 | 返回 PNG,1920×1080,约 1.3 MB |
| 状态汇报 | 返回会话列表,含事件、状态、Agent 类型与陈旧标记 |
| dsh 无头会话 | exit_code: 0,模型正常应答 |
| dsh hook 上报 | 插件日志 [a4agent-dsh-hook] 任务完成,状态接口读到 agent: DSH |
远端执行 hostname 的完整返回:
{
"id": "738348c876b5",
"identity": "a4agent",
"status": "done",
"cmd": "hostname",
"shell": "cmd",
"cwd": null,
"started_at": 1795166194.48,
"ended_at": 1795166194.62,
"exit_code": 0,
"stdout": "DESKTOP-B\r\n",
"stderr": "",
"duration": 0.128
}
返回字段中值得注意的几项:identity 是被控端登记的控制端身份名,duration 是远端执行耗时而非网络往返时间,started_at 与 ended_at 为远端时间戳。
上传到白名单外路径时的报错:
{
"detail": {
"message": "路径超出工作空间白名单:C:\\Windows\\Temp\\probe.txt;默认仅允许 node 暂存目录 ...;如需写入其他位置,请在被控端 node.json 配置 workspace 键或以 --workspace 启动参数添加允许根(被控端本地配置,控制端不可远程修改)",
"code": "SANDBOX_DENIED"
}
}
这条报错同时给出了原因与处理方式,并且明确说明白名单只能在被控端本地修改。上传到暂存目录则成功,返回体包含目标路径、字节数与 MD5:
{"path": "C:\\Users\\<用户名>\\AppData\\Roaming\\a4agent\\node\\tmp\\probe-upload.txt", "size": 5, "md5": "d8e8fca2dc0f896fd7cb4cb0031ba249"}
7. 在 Qoder 与 dsh 中调用这些能力
7.1 Skill 如何被 Agent 发现
跨设备控制能力对 Agent 而言是一个 Skill。Skill 文件以 Markdown 写成,带 YAML 头部声明名称与描述,Agent 会话启动时读取技能目录,据此判断何时调用。
Skill 的描述行决定了 Agent 会不会想到用它:
---
name: crossdevice
description: 控制局域网内已配对的 Windows 设备(远程命令、截屏、文件上传下载、任务历史),并查询对端设备上各宿主会话的进度状态。当任务需要在另一台机器上执行命令、取文件、看屏幕、跑长命令时使用。
---
7.2 在 Qoder 控制端的典型对话
在 A 设备的 Qoder 会话里,可以直接用自然语言描述目标,由 Agent 自行组织调用顺序:
请在 B 设备执行 hostname 命令,并告诉我结果。
Agent 的调用路径是:读实例文件取端口 → 拉设备全景确认配对名 → 调 /exec 下发命令 → 取 job_id 轮询结果 → 汇总回答。这条路径不需要人工指定接口地址,也不需要预先告诉它设备名。
下图是这次执行的实际界面。Qoder 在回答前先说明了它的探测过程:读取 a4agent 实例端口,再拉设备全景确认唯一配对设备是哪一台,然后才对目标设备执行命令。

回答中给出的结论包含三项:退出码为 0、hostname 输出与设备清单中的主机名字段一致、耗时约 0.1 秒。展开的「执行工具」条目可以看到实际发出的 HTTP 请求与轮询调用,说明 Agent 是直接调用本地接口完成的操作,没有经过任何中转。
图中间那行英文是模型的中间思考过程,它在此处比对了设备清单,用来确认「B 设备」对应哪一个已配对设备。这是 Agent 自行判断的环节,无需人工介入。
7.3 在 dsh 执行端的典型用法
B 设备的 dsh 承担执行角色,通常不主动发起跨设备调用,而是接收 A 侧下发的任务书。dsh 侧的跨设备能力主要用于反向查询与自检。
hook 在 dsh 侧以进程内插件形式运行,因此 dsh 会话结束时会自动产生状态记录,A 侧无需在任务书里写上报逻辑。
dsh 有两种运行形态,都支持 hook 上报:
| 形态 | 命令 | 适用场景 |
|---|---|---|
| Web 界面 | dsh web |
人工在 B 设备上交互操作 |
| 无头模式 | dsh headless "任务描述" |
由控制端通过 exec 下发,一次任务一次进程 |
无头模式与跨设备协同结合得最紧密:控制端用 exec 下发 dsh headless "<任务>",dsh 执行完打印结果并退出,插件在退出前把状态写入状态目录。这条路径适合把单个明确任务交给 B 侧,无需打开界面。
需要注意的是,无头模式下 dsh 每次都是一个新进程,会话不跨进程延续。需要多轮对话的场景应使用 Web 形态,由人在 B 侧界面中操作;跨设备协同负责的是任务下发与进度可见,不承担交互式对话的转发。
Web 形态的执行效果如下图。会话在工作区 node 中创建一个文件,模型为 dots3-note-prev,界面顶部显示「已完成,用时 9 秒」,正文给出文件路径与写入内容,编辑器区域以 diff 形式展示了新增的一行。

界面左侧的会话列表保留了此前通过 exec 下发的几次无头会话,说明这两种形态共用同一个工作区与会话存储。控制端下发的任务与人工操作的任务会出现在同一列表里,便于统一追踪。
8. 安全边界与运维要点
8.1 凭据与传输
| 项目 | 机制 |
|---|---|
| 传输加密 | TLS 1.3,自签证书 |
| 证书信任 | TOFU,首次连接记录指纹,之后变更即拒 |
| 身份令牌 | 每控制端一个 32 位十六进制令牌,常量时间比较 |
| 防重放 | 时间戳 ±300 秒窗口 + nonce 查重 |
| 凭据存储 | Windows DPAPI 加密,不进任何接口响应 |
8.2 命令执行的破坏力
远程执行可以运行任意命令,令牌泄露等于被控机完全控制。这是这套方案必须正视的前提,控制手段有三层:
- 网络层:仅在可信私网或隧道内使用,隧道内只放行必要端口。
- 审计层:被控端对每个通过来源校验的请求落审计,默认留存 180 天,含失败请求。
- 操作层:只执行任务所需范围内的命令,避免在远端起长驻交互式进程。
8.3 写操作白名单
写方向操作受被控端工作空间白名单约束。默认只有 node 暂存目录可写,其他路径返回 SANDBOX_DENIED。
这是防误操作的设计,不构成安全边界:远程执行本身可以绕过它。白名单根目录的配置必须在被控端本地完成,接口不提供远程修改入口。
8.4 长命令的使用方式
命令行有长度上限,多层引号转义也容易出错。较长脚本走文件通道:
- 上传脚本到暂存目录(
PUT /api/v1/devices/{name}/put)。 - 用
exec执行该文件路径。
8.5 常见故障排查
| 症状 | 可能原因 | 处理 |
|---|---|---|
UNREACHABLE |
node 未启动、隧道断开、防火墙拦截 | 重新 ping,检查对端 node 进程与端口监听 |
FORBIDDEN 来源非私网 |
从公网地址访问 | 改用私网隧道,或本机回环转发 |
TOFU_MISMATCH |
对端重装或换证书 | 确认后重置指纹重新连接 |
SANDBOX_DENIED |
目标路径不在白名单 | 改上传到暂存目录,或由对端所有者扩白名单 |
| 状态列表为空 | 会话仍在长回合中,Stop 未触发 | 先 ping 设备,再看响应中的 last_error |
| 发现的设备列表为空 | 处于隧道场景,广播不跨网段 | 使用手动连接线索接口添加目标 |
链路中断时,设备卡片会同时出现两处提示:状态行被标注为「已过时」,下方新增一行「拉取失败」并携带具体的连接错误。

上图是执行端未启动时控制端的界面。此时 ping 会返回 UNREACHABLE,而设备卡片本身仍然保留,因为配对关系保存在本地,不依赖对端在线。对端重新启动后,卡片上的「拉取失败」自动消失,无需重新配对。
9. 总结
9.1 核心内容回顾
- 跨设备协同按控制端、执行端、下发通道、汇报通道、汇聚点分工,职责边界清晰。
- node 只接受私网来源,这条限制写在代码里且无开关;跨互联网场景需用三层私网隧道满足。
- 配对是一次人工确认流程,广播仅负责可见性,不授予信任;同一控制端可与多台执行端分别配对。
- 并行开发靠文件面互斥与单向汇聚协议避免冲突,编号由合并点统一分配。
- 设备数量增加时按「一个文件面只有一个所有者」的原则继续细分,控制端串行合并各设备的推送。
- 状态汇报由宿主级 hook 自动完成,任务书里不写轮询逻辑。
- 远程执行是异步的,下发拿
job_id再长轮询,适合长命令。 - 凭据由 a4agent 加密托管,审计在被控端完整留痕。
9.2 常见问题与解答
问:每台设备都需要安装 a4agent 吗?
答:需要。a4agent 在不同设备上承担不同角色:控制端提供本地 API 与设备页,被控端托管 node 进程与 hook 注册。
问:能不能连更多设备?
答:可以。设备注册表以设备名为键,不限制数量。新增设备重复一次配对流程即可,随后在文件面表中为新设备划出独立所有权。
问:为什么配对了还是连不上?
答:先看错误码。FORBIDDEN 属来源校验失败,说明对端看到的源地址不是私网;UNREACHABLE 属链路问题,检查 node 进程、端口与防火墙;UNAUTHORIZED 属令牌问题,需要重新配对。
问:装 Tailscale 之后为什么还是不通?
答:Tailscale 默认分配 100.64.0.0/10 段地址,不属于 node 认可的私网范围。可改用分配 10.x 或 192.168.x 地址的组网方式。
问:截屏在锁屏状态下为什么失败?
答:锁屏或非交互会话下,截屏与键鼠注入不可用,命令执行与文件操作不受影响。这与 node 运行在交互式桌面会话的要求有关。
问:任务书里需要写「完成后告诉我」这类要求吗?
答:不需要。状态汇报由宿主级 hook 自动生效,覆盖该端所有会话。A 侧通过状态接口查进度即可。
评论