「设备互联」是 a4agent 自 0.7.0 起的页签:内置 CrossDevice 设备运行时(MIT 协议),把「本机被控端 + 局域网设备管理」做进同一个应用——双端安装 a4agent 后同网段设备自动互见,经一次确认配对建立长期信任,之后可远程下发命令、全屏截屏与传输文件,全程免手工重连。0.7.1 起补齐「安装即用」(内嵌 Python 解释器)与 Agent 开放交互(内置 crossdevice 技能包,AI 编程 Agent 可直接发现并使用设备控制能力),0.7.2 起支持本机被控端多实例与配对系统 toast。本文章介绍运行时与设备页、局域网发现、配对流程、配对后的远程能力、Agent 开放交互、多实例,以及安全边界与数据落盘。

1. 功能概述

维度 说明
定位 局域网跨设备控制:发现、一次确认配对、远程命令 / 截屏 / 文件传输
运行时 CrossDevice node 随安装包交付(安装目录 node_runtime\),首启自动拉起并守护
发现 UDP 广播自动互见(约 10 秒心跳、30 秒无帧判离线),支持手动添加 IP
配对 被控端本地一次确认 + 一次性 6 位配对码,配对后长期免手工
远程能力 异步远程命令、全屏截屏、分块断点续传文件、可写根(白名单)查询
Agent 交互 /overview 聚合发现 + 内置 crossdevice 技能一键安装(0.7.1 起)
引入版本 0.7.0(发现 / 配对 / 远程能力),0.7.1(内嵌 Python、Agent 开放交互),0.7.2(node 0.5.1、多实例、配对 toast)
graph LR A[两台设备
各自安装 a4agent] --> B[UDP 广播
同网段自动互见] B --> C[控制端点发起配对] C --> D[被控端弹确认窗
可拒绝] D --> E[同屏展示一次性
6 位配对码] E --> F[控制端输码
建立长期信任] F --> G[远程命令 / 截屏
文件传输] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style C fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style D fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style E fill:#ffecd6,stroke:#e67e22,stroke-width:2px style F fill:#d5f5e3,stroke:#27ae60,stroke-width:2px style G fill:#d5f5e3,stroke:#27ae60,stroke-width:2px

2. 本机运行时(被控端)

安装包内嵌 CrossDevice 设备运行时(MIT 协议)到安装目录 node_runtime\,应用首启自动以独立子进程拉起本机被控端 node 并守护:

  • 退出自动重启:node 进程退出后由守护线程拉起;
  • 连续崩溃熔断:短时间反复崩溃时停止重启,避免空转;
  • TLS 证书缺失自动生成:首次运行自动生成本地证书;
  • 安装即用(0.7.1 起):安装包内嵌 Python 运行时(python 3.12 embeddable,约 11 MB)到 node_runtime\python\,解释器解析顺序将其置于最前——全新机器无需预装任何 Python 即可拉起被控端。

设备页顶部「运行时」区显示 node 路径与运行状态,可手动启动 / 停止;「运行时设置」可指定自定义 node.py 路径(开发态可直接指向 CrossDevice 仓库)与解释器,路径也可用环境变量 A4AGENT_NODE_PATH / A4AGENT_NODE_PYTHON 覆盖(详见数据目录与日志说明)。

0.7.2 起,backend 另有一个常驻 pair_watcher 监听本机 node 的配对会话:有设备发起配对时直发系统 toast「有设备请求配对,请在设备页确认」,批准成功再发一条回执 toast(不含配对码 / IP / 令牌);toast 不可用时静默降级,绝不阻断配对流程——你不在设备页也能第一时间知道有人请求配对。

3. 局域网自动发现

双端安装 a4agent 后,「发现的设备」列表会经 UDP 广播自动出现同网段设备:

  • 约 10 秒心跳广播一次,30 秒无帧判离线;同源限频去重,防止同一设备刷屏;
  • 本机回环来源的广播帧直接丢弃(0.7.2 起),「发现的设备」不再出现本机幽灵条目;
  • 广播只提供「看得见」,不自动建立信任——出现 ≠ 可控制,控制必须走第 4 节的配对确认;
  • 不广播的设备(如未装 a4agent、防火墙拦了广播)可点「手动添加 IP」按 IP + 端口加入发现池。

4. 一次确认配对

配对是唯一的信任建立入口,全程需要被控端本地人工参与:

graph LR A[控制端点
「发起配对」] --> B[被控端弹确认窗
显示来源 IP 可拒绝] B -->|确认| C[同屏展示一次性
6 位配对码+5 分钟倒计时] B -->|拒绝| D[连接不建立
落审计] C --> E[控制端输码
TOFU 校验证书] E --> F[凭据 DPAPI 加密登记
此后长期免手工] style A fill:#e8f4f8,stroke:#1a6b8a,stroke-width:2px style B fill:#ffecd6,stroke:#e67e22,stroke-width:2px style C fill:#ebdef0,stroke:#8e44ad,stroke-width:2px style D fill:#fadbd8,stroke:#c0392b,stroke-width:2px style E fill:#d6eaf8,stroke:#1a6b8a,stroke-width:2px style F fill:#d5f5e3,stroke:#27ae60,stroke-width:2px
  1. 控制端发起:在「发现的设备」卡片上点「发起配对」;
  2. 被控端确认:被控端弹出确认窗,显示来源 IP,可一键拒绝——拒绝则连接不建立,全程落被控端审计;
  3. 输码:被控端确认后同屏展示一次性 6 位配对码与 5 分钟倒计时,控制端输入即建立连接;
  4. 长期免手工:此后该设备对凭已登记的令牌与证书指纹自动重连,双端重启都不需要再确认。

防滥用约束:配对码一次性、猜错达上限(默认 5 次)即作废本次会话,发起端受 10 秒限频保护;配对成功 / 失败 / 拒绝全程落被控端审计。已配对设备的证书指纹变更会被拒绝(防中间人),确属对方重装系统等正当场景时,在设备页「重置指纹」后重新走一次配对即可。

5. 配对后的远程能力

能力 说明
远程命令 对被控端下发异步命令,返回任务号后可用任务号查询状态与产出;任务历史按设备身份过滤
全屏截屏 抓取被控端原始分辨率整屏 PNG,在控制端本地保存(不经任何第三方)
文件上传 / 下载 4 MB 分块 + 断点续传 + MD5 校验,大文件传输中断后可续
可写根查询 查询被控端当前的写入白名单(工作空间根 + 默认暂存目录,0.7.2 起)

文件上传有沙箱白名单:只有白名单内的目录可写;被拒绝时报错会携带当前允许根列表(allowed_roots / staging_root),默认暂存目录(node 数据目录下的 tmp)恒可写——先传到暂存目录再在被控端移动,是内置技能推荐的大文件 / 长脚本投递路径。

6. Agent 开放交互(0.7.1 起)

设备控制能力不只属于人——a4agent 把它同时开放给 AI 编程 Agent:

  • 聚合发现端点 GET /api/v1/devices/overview:一次调用返回已配对设备全景、backend 地址与操作接口速查表;设备令牌与证书指纹不出 backend,Agent 拿到的是「能调哪些接口」而不是凭据;
  • 内置 crossdevice 技能包:能力概述、动态发现流程、API 速查与边界声明随包内置;设备页点「安装控制技能」即安装到指定位置,支持全局技能库 / 已注册项目根 / 自定义目录三档(同名不覆盖),全局档覆盖全部九端(见技能管理);
  • 边界不变:Agent 能发现、能调用接口,但配对确认永远是设备页的人工动作——AI 无法替你信任一台新设备。

0.7.2 起技能副本同步更新:新增「大 payload / 长脚本投递」节与「宏(xd macro rec/run)」能力节(宏是 CrossDevice 控制端 CLI 的本地能力,不经 a4agent HTTP 接口)。

7. 多实例(0.7.2 起)

一台机器可以同时是多个独立的被控端设备:在运行时设置里维护实例名清单,守护进程按实例逐个拉起独立 node 子进程(--instance 参数):

  • 每个实例独立:独立配置、独立审计、独立任务库;共享 TLS 证书,端口自动顺延(默认从 51888 起);
  • 设备页按实例渲染多卡片:每个实例单独启停、移除,也可添加新实例;
  • 向后兼容:默认不配置任何实例时,单实例行为与旧版完全一致,配对协议零变更。

8. 安全边界与凭据存储

  • 未配对一律 401:未配对设备对被控端的任何请求都被拒绝;
  • 非私网一律拒绝:来自非私有网段的请求不受理,设备互联只在局域网内成立;
  • 无静默互信:不提供同网段自动互信,每台新设备都需要被控端本地一次确认;
  • 凭据加密落盘:控制端侧的设备令牌与证书指纹经 Windows DPAPI 加密后写入数据目录 devices.json,只在内存解密使用,任何接口与日志都不回传明文;被控端 node 自身的 node.json 保持明文(node 运行时零第三方依赖约束优先,a4agent 只通过 /v1/* 协议与 node 交互、不读它的配置);
  • 审计可追溯:配对成功 / 失败 / 拒绝全程落被控端审计。

安全机制的总体设计意图另见安全设计。

9. 数据落盘

路径 内容
%APPDATA%\a4agent\devices.json 控制端已配对设备注册表(令牌与证书指纹 DPAPI 加密)
%APPDATA%\a4agent\node\ 本机被控端 node 的配置目录
%APPDATA%\a4agent\device_runtime.json 运行时设置(实例名清单、自定义路径等)
%APPDATA%\a4agent\device_tmp\ 设备相关临时与暂存目录
<安装目录>\node_runtime\ 内嵌 CrossDevice 运行时(node.py、生成证书脚本;0.7.1 起含 python\ 内嵌解释器)

完整的数据目录清单与路径覆盖环境变量见数据目录与日志说明,安装与卸载对 node_runtime\ 的处理见安装升级与卸载(卸载会连同内嵌运行时一并清除,数据目录按设计保留)。

10. 常见问题

问:设备页里看不见另一台电脑?

答:按顺序检查:双方都装了 a4agent 且设备页运行时处于运行状态;两台机器在同一局域网网段(跨网段广播不可达,可改用「手动添加 IP」);路由器 / 防火墙没有拦截 UDP 广播。仍未出现时用手动添加 IP 直连再发起配对。

问:配对码输错了怎么办?

答:配对码是一次性的,猜错累计到上限(默认 5 次)本次会话即作废,被控端重新确认一次会生成新码;发起端还有 10 秒限频,稍等再试即可。

问:对方重装系统后连不上了?

答:重装后 node 的 TLS 证书通常已重建,与登记的证书指纹不一致,a4agent 会拒绝连接(防中间人)。确认是对方本人后,在设备页对该设备「重置指纹」,再走一次配对即可。

问:没有安装 Python 的全新电脑能当被控端吗?

答:能(0.7.1 起)。安装包内嵌了 Python 运行时(约 11 MB)到 node_runtime\python\,解释器解析顺序将其置于最前,全新机器装完 a4agent 即具备被控端能力,无需任何额外依赖。

问:怎么让 Claude Code 这类 Agent 使用设备控制?

答:在设备页点「安装控制技能」,把内置的 crossdevice 技能装到全局技能库或某个项目根;之后 Agent 在该工作空间里即可通过技能了解设备能力、调用 /overview 发现设备并执行远程操作。配对确认始终是设备页的人工动作,AI 不能替你信任新设备。

问:文件传到被控端的哪里?

答:上传受沙箱白名单限制,默认暂存目录(node 数据目录下的 tmp)恒可写;被拒绝时报错会列出当前允许根。可以先传暂存目录、再通过远程命令在被控端移动文件;下载同理从白名单根读取。

问:两台机器能互为控制端吗?

答:可以。a4agent 既是控制端也是被控端——每台机器的本机被控端随应用常驻,分别在各自信任的设备对里充当对方控制的对象;需要双向控制时各自发起配对即可。