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

140 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# agent-device:远端设备执行端
把一台机器(Linux 盒子、Windows、macOS)变成 agent 的一双“手”:**主动出站**连到 core 的
WebSocket 端点,接收 shell 命令、流式回传输出与退出码、上报主机指标。
设备不需要公网 IP、不需要开任何入站端口,NAT、公司网络、随身热点都能用。
> 这不是通用 agent,只是执行端。会话、模型、记忆都在服务端;这里只负责“在那台机器上跑东西”。
## 二进制里没有服务器地址
`-server` 与 token 都**没有默认值**,不显式给就启动失败。所以拿到的二进制不会连到别人的服务器上——
它只连你指定的那一台。
## 安装
### 自己编译
需要 Go 1.22+:
```sh
git clone <本仓库> && cd device
go build -trimpath -ldflags "-s -w" -o bin/agent-device ./cmd/agent
```
交叉编译(一次出五个平台):
```sh
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。
## 运行
```sh
# 推荐:二进制旁边放一个 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`**(存在才读,不存在就当没配),所以部署时把二进制和配置放一个目录、直接跑就行:
```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 就写路径,
没装就保持默认。
```json
{ "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)。