Files
agent/device/README.md
T
kicer 3c9f9d2bdb feat(device): 文件通道 pull/push
core 与设备复用同一条 WS 搬文件:256KiB 分块、base64、50MiB 上限,
写盘先 .part 再校验 size/sha256 后 rename;device 工具新增 pull/push 两个动作。
2026-11-19 19:01:34 +08:00

5.7 KiB
Raw Blame History

agent-device:远端设备执行端

把一台机器(Linux 盒子、Windows、macOS)变成 agent 的一双“手”:主动出站连到 core 的 WebSocket 端点,接收 shell 命令、流式回传输出与退出码、上报主机指标。

设备不需要公网 IP、不需要开任何入站端口,NAT、公司网络、随身热点都能用。

这不是通用 agent,只是执行端。会话、模型、记忆都在服务端;这里只负责“在那台机器上跑东西”。

二进制里没有服务器地址

-server 与 token 都没有默认值,不显式给就启动失败。所以拿到的二进制不会连到别人的服务器上—— 它只连你指定的那一台。

安装

自己编译

需要 Go 1.22+:

git clone <本仓库> && cd device
go build -trimpath -ldflags "-s -w" -o bin/agent-device ./cmd/agent

交叉编译(一次出五个平台):

sh scripts/build.sh all

脚本只做构建:不联网、不推送、不依赖任何特定服务器。本机没有 Go 但装了 docker 时, 会自动用 golang:1.23-alpine 容器编译。

下载预编译

从本仓库的 Releases 页面取对应平台的文件(agent-device-linux-arm64、agent-device-windows-amd64.exe 等), chmod +x 即可,静态链接、无运行时依赖,一个文件约 5.5 MB。

运行

# 推荐:二进制旁边放一个 config.json,直接启动(token 不出现在 ps 里)
./agent-device

# 或者全走命令行
./agent-device -server wss://your-host.example/dev/ws -token <TOKEN> -root /var/agent-work -name box-01

# 配置文件不在默认位置时显式指定
./agent-device -config /etc/agent-device.json

默认会自动读可执行文件同目录的 config.json(存在才读,不存在就当没配),所以部署时把二进制和配置放一个目录、直接跑就行:

{
  "server": "wss://your-host.example/dev/ws",
  "token": "…",
  "root": "/var/agent-work",
  "name": "box-01"
}

优先级:命令行显式参数 > 环境变量 NODE_TOKEN(仅 token)> 配置文件 > 默认值。

shell 用哪个

默认:macOS / Linux 用 /bin/sh(固定,不读 $SHELL——用户把默认 shell 设成 fish 时, 模型写的 POSIX 语法会全废);Windows 用 cmd。

想换就在 config.json 里写 shell,不做自动探测:装了 Git Bash / busybox 就写路径, 没装就保持默认。

{ "shell": "C:\\Program Files\\Git\\bin\\bash.exe" }

报给 core 的是短标签(sh / bash / busybox / cmd / powershell),同时带上解释器路径与版本。

参数 说明
-server core 的接入地址,wss://…/dev/ws
-token Bearer token,须与服务端 DEVICE_TOKEN 一致
-root 工作根目录,命令的 cwd 必须落在它之内(默认 ~/agent-work,会自动建)
-name 设备名,服务端用它区分设备(默认 hostname)
-shell sh / cmd / powershell,默认按平台
-config 配置文件路径,默认 <二进制所在目录>/config.json
-insecure 跳过证书校验(自签证书调试用)
-fix-clock 证书报错时用服务器 Date 头校准本机时间(小设备没有 RTC 时用,Linux 需 root)

设备名重复时后接入的会顶掉前一个连接(换机、重装不留僵尸连接)。

协议

一条 WebSocket 上全是 JSON 文本帧,t 区分类型:

方向 消息
设备 → core {t:"hello", ver, name, os, arch, shell, shell_path, shell_ver, root}
core → 设备 {t:"exec", id, cmd, cwd, timeout_ms} · {t:"kill", id} · {t:"ping"} · {t:"health", id}
文件通道 {t:"file", id, op:"read"|"write", path, size?, sha256?} · {t:"file.chunk", id, data:<base64>} ×N · {t:"file.done", id, size?, sha256?, err?}
设备 → core {t:"chunk", id, out:"out"|"err", chunk:<base64>} · {t:"exit", id, code, killed_by, ms, truncated} · {t:"pong"} · {t:"health", …}
  • 保活:core 每 20 秒发 ping,设备回 pong;90 秒无任何消息即断开重连。
  • 断线:指数退避 1s → 2s → 4s → … 上限 30s,连上后重置。
  • 超时:命令超过 timeout_ms 由设备侧杀进程组,回 killed_by:"timeout"。
  • 输出:单流超过上限截断并置 truncated。
  • shell 报的是实际解释器(/bin/sh 可能是 dash / bash / busybox),连同版本,供模型决定命令语法。

文件通道

core 通过同一条连接搬文件,设备不需要任何额外端口:

方向 流程
拉取(设备 → 会话目录) file{op:read} → 设备分块回 file.chunk → file.done{size,sha256}
推送(会话目录 → 设备) file{op:write,size,sha256} → 分块 file.chunk → file.done
  • 每块 256 KiB(base64 后约 341 KiB),单文件上限 50 MiB;
  • 写盘先落 <path>.part,size 与 sha256 都对上才 rename;
  • 设备侧路径必须在工作根内(与 exec 的 cwd 校验同一套)。

安全边界

  • 设备主动出站,服务端不需要知道设备 IP;
  • token 走 Authorization: Bearer,与业务 token 分开;
  • cwd 只约束起始目录,命令内部仍可 cd 到别处——给了 shell 就是这个语义,需要强隔离请用容器/namespaces;
  • 同一个 token 可被多台设备共用(当前设计),吊销需换 token 并重启所有设备。

实测

用例 结果
exec 基本 cwd 自动创建,stdout/stderr 分流,退出码透传
超时 杀进程组,killed_by=timeout
起始 cwd 越界 拒绝
断线重连 1s→2s→4s 退避,恢复后自动注册

在 Linux / macOS / Windows 三平台编译验证(amd64 + arm64)。