本教程面向手头有多台电脑的开发者,讲解如何把多台机器组建成一条受控的开发流水线:A 设备的 Qoder 作为控制端,B 设备的 DeepSeek Harness 作为执行端,A 侧通过 a4agent 的设备互联能力在 B 侧执行命令、取文件、看屏幕,并可查询 B 侧 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 控制端、执行端与汇报通道

跨设备协同要求各设备明确分工,同时建立一条反向的状态通道:执行端在会话的关键节点主动向控制端汇报进度,控制端无需反复查询。

graph LR User[开发者] --> A[A 设备
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 配对机制的四个环节

配对解决的是「谁可以控制谁」这个信任问题。广播只负责让设备互相看得见,信任建立必须经人工确认。

graph LR D1[UDP 广播
每 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」按钮。该区块在隧道场景下通常显示为空,因为广播报文不跨隧道;此时通过手动线索指定对端的隧道内地址即可。

发现设备区块,红框标注手动添加 IP 入口

5. 协同工作流设计

5.1 文件面互斥

多设备并行开发最容易出问题的地方是同一个文件被多方同时改。解决办法是按文件面划分所有权,每台设备只改自己的部分。

文件面 归属 典型内容
后端代码、数据库迁移 控制端设备 接口实现、表结构变更
前端代码、设计稿 执行端设备 页面组件、样式、原型
契约包 单一所有者 类型定义,任一方修改都需评审
共享文档 分节追加 协作看板按节归属,各自追加不重写他人节

设备数量增加时,文件面按「一个文件面只有一个所有者」的原则继续细分,新增设备承担新的文件面或接管已划出的独立模块。

5.2 单向汇聚的同步协议

代码同步采用单向汇聚:B 侧推送到远程仓库,A 侧拉取后合并。A 侧是唯一的合并点。

graph LR B1[B 侧完成任务] --> B2[commit 自身文件面] B2 --> B3[push 远程仓库] B3 --> A1[A 侧 git pull] A1 --> A2[文件面核验] A2 --> A3[合并] A3 --> A4[整仓检查] A4 --> A5[入库] style B1 fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style B2 fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style B3 fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style A1 fill:#ffecd6,stroke:#e67e22,stroke-width:2px style A2 fill:#fdebd0,stroke:#b7950b,stroke-width:2px style A3 fill:#ffecd6,stroke:#e67e22,stroke-width:2px style A4 fill:#d6eaf8,stroke:#2980b9,stroke-width:2px style A5 fill:#d5f5e3,stroke:#27ae60,stroke-width:2px

这套协议解决三个问题:合并冲突因文件面互斥而基本不发生;整仓检查只在合并点跑一次,避免各设备重复消耗;提交历史保持线性,便于追溯。

5.3 从两台扩展到设备集群

a4agent 的设备注册表以设备名为键,不限制已配对设备的数量,一份控制端可以同时管理多台执行端。扩充设备时按以下顺序推进。

graph LR A[A 设备
控制端] --> 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

扩充步骤:

  1. 在新设备安装 a4agent 与目标 Agent 工具,启动 node。
  2. 完成一次确认配对,控制端的设备列表增加一条记录。
  3. 在文件面表中为新设备划出独立所有权,避免与已有设备重叠。
  4. 给新设备分配独立的会话命名与证据目录前缀,便于在汇总时区分来源。
  5. 控制端先单独跑一个小批验证链路,再纳入正式分派。

多设备后需要额外注意的三点:

关注点 说明
状态汇总 状态接口支持一次拉取全部设备,无需逐台查询;每台设备的记录独立保留 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": "已完成"
    }
  ]
}

状态接口返回的 DSH 会话记录,红框依次标注会话列表、Agent 类型与事件标签

不同 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 结果与任务执行结果

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 实例端口,再拉设备全景确认唯一配对设备是哪一台,然后才对目标设备执行命令。

Qoder 会话中完成跨设备命令,红框标注用户提问与 hostname 执行结果

回答中给出的结论包含三项:退出码为 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 形式展示了新增的一行。

dsh Web 界面完成跨设备任务,红框标注用户提问、完成状态与文件写入结果

界面左侧的会话列表保留了此前通过 exec 下发的几次无头会话,说明这两种形态共用同一个工作区与会话存储。控制端下发的任务与人工操作的任务会出现在同一列表里,便于统一追踪。

8. 安全边界与运维要点

8.1 凭据与传输

项目 机制
传输加密 TLS 1.3,自签证书
证书信任 TOFU,首次连接记录指纹,之后变更即拒
身份令牌 每控制端一个 32 位十六进制令牌,常量时间比较
防重放 时间戳 ±300 秒窗口 + nonce 查重
凭据存储 Windows DPAPI 加密,不进任何接口响应

8.2 命令执行的破坏力

远程执行可以运行任意命令,令牌泄露等于被控机完全控制。这是这套方案必须正视的前提,控制手段有三层:

  • 网络层:仅在可信私网或隧道内使用,隧道内只放行必要端口。
  • 审计层:被控端对每个通过来源校验的请求落审计,默认留存 180 天,含失败请求。
  • 操作层:只执行任务所需范围内的命令,避免在远端起长驻交互式进程。

8.3 写操作白名单

写方向操作受被控端工作空间白名单约束。默认只有 node 暂存目录可写,其他路径返回 SANDBOX_DENIED。

这是防误操作的设计,不构成安全边界:远程执行本身可以绕过它。白名单根目录的配置必须在被控端本地完成,接口不提供远程修改入口。

8.4 长命令的使用方式

命令行有长度上限,多层引号转义也容易出错。较长脚本走文件通道:

  1. 上传脚本到暂存目录(PUT /api/v1/devices/{name}/put)。
  2. 用 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 侧通过状态接口查进度即可。