「设备互联」是 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) |
各自安装 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. 一次确认配对
配对是唯一的信任建立入口,全程需要被控端本地人工参与:
「发起配对」] --> 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
- 控制端发起:在「发现的设备」卡片上点「发起配对」;
- 被控端确认:被控端弹出确认窗,显示来源 IP,可一键拒绝——拒绝则连接不建立,全程落被控端审计;
- 输码:被控端确认后同屏展示一次性 6 位配对码与 5 分钟倒计时,控制端输入即建立连接;
- 长期免手工:此后该设备对凭已登记的令牌与证书指纹自动重连,双端重启都不需要再确认。
防滥用约束:配对码一次性、猜错达上限(默认 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 既是控制端也是被控端——每台机器的本机被控端随应用常驻,分别在各自信任的设备对里充当对方控制的对象;需要双向控制时各自发起配对即可。
评论