ifu Agent 通信协议与 API 详解

如果你想开发自己的控制端（如手机 App、桌面管理软件），可以参考本文详细了解 ifu Agent 的通信协议。它同时开放了三套协议：UDP 负责发现设备、TCP 提供可靠指令通道、HTTP 面向 Web 与脚本，并统一了电源控制与桌面控制共 12 个命令。

通用请求格式

所有命令均为 JSON 对象，核心字段：

字段	类型	必选	说明
`cmd`	string	✅	命令名（见下方命令表）
`mac`	string	✅	目标机器 MAC 地址；`"all"` 表示广播
`value`	int	按命令	数值参数（音量 0-100、静音开关 0/1）
`text`	string	按命令	文本参数（键盘输入、剪贴板内容）
`key` / `mods`	string / []string	按命令	按键名称与修饰键（ctrl/shift/alt/win）
`x` / `y`	int	按命令	鼠标屏幕坐标
`button`	string	按命令	鼠标按键 left/right/middle（默认 left）
`scroll`	int	按命令	滚轮格数（正=上滚，负=下滚）

MAC 地址支持格式：aa:bb:cc:dd:ee:ff、aa-bb-cc-dd-ee-ff、aabbccddeeff、all。

传输细节

HTTP：POST /，Content-Type: application/json，请求体上限 4KB
TCP：每行一条 JSON 命令，以换行符 \n 结尾，单行上限 4KB
UDP：单包一条 JSON 命令，上限 2048 字节；包内同时是设备发现协议的载体

通用响应格式

{
  "status": "success | error | skipped",
  "message": "人类可读信息",
  "data": { }   // 可选：查询类命令的返回值
}

状态	含义
`success`	命令执行成功
`error`	执行失败，`message` 含失败原因（含功能不可用原因）
`skipped`	MAC 地址不匹配，命令未执行

1. UDP 设备发现协议

设备发现基于 UDP 广播机制，允许控制端在不知道 IP 的情况下发现局域网内的设备。

端口：42002
模式：请求/响应 (Request/Response)

发现流程

控制端向 255.255.255.255:42002 发送广播包。
客户端收到广播包后，校验 server 字段。
客户端向控制端的发送源 IP 和端口回复单播响应包。

请求包 (Request)

{
  "type": "discovery",
  "action": "ping",
  "server": "ifu-agent-server", // 必须匹配，否则会被忽略
  "timestamp": 1734267000
}

响应包 (Response)

{
  "type": "discovery",
  "action": "pong",
  "mac": "00:11:22:33:44:55",   // 客户端的 MAC 地址
  "response_time": 1734267001, // 响应时间戳 (Unix Timestamp)
  "timestamp": 1734267001      // 同上
}

时间戳非零时，接收方会将本机时钟同步为发送方时间（差异超过 30 秒时执行）。

2. TCP 控制协议

TCP 协议提供可靠的命令传输通道，适合需要确认命令送达的场景。

端口：42001
连接方式：长连接或短连接均可，建议发送完命令接收响应后断开。

交互流程

建立 TCP 连接。
发送 JSON 格式的命令字符串（以 \n 结尾）。
接收 JSON 格式的响应字符串。
(可选) 断开连接。

请求示例：

{"cmd":"volume_set","mac":"all","value":30}

3. HTTP API

HTTP 协议基于 RESTful 风格，适合 Web 集成和脚本调用。

端口：42000
基础 URL：http://<ip>:42000

接口列表

路径	方法	描述	参数
`/`	`POST`	执行命令（电源/音量/屏幕/键盘/鼠标/剪贴板）	JSON Body
`/health`	`GET`	健康检查	无
`/capabilities`	`GET`	功能能力清单（可用性与缺失原因）	无
`/control`	`GET`	Web 控制台	无

健康检查

{
  "status": "success",
  "time": "2024/05/20 10:00:00"
}

功能能力查询

返回 6 个功能项（固定顺序）：power、volume、screen、keyboard、mouse、clipboard。available=false 时 reason 说明缺失原因（Session 0、缺依赖、权限不足等）。

{
  "features": [
    { "name": "power", "available": true },
    { "name": "volume", "available": false, "reason": "服务模式（Session 0）无交互音频会话，音量控制需在前台模式下使用" },
    { "name": "screen", "available": true },
    { "name": "keyboard", "available": true },
    { "name": "mouse", "available": true },
    { "name": "clipboard", "available": true }
  ]
}

执行命令

URL：/
Method：POST
Content-Type：application/json

# 关机
curl -X POST http://localhost:42000/ -H "Content-Type: application/json" \
  -d '{"cmd":"poweroff","mac":"all"}'

# 设置音量 30
curl -X POST http://localhost:42000/ -H "Content-Type: application/json" \
  -d '{"cmd":"volume_set","mac":"all","value":30}'

# 组合键 Ctrl+Shift+Tab
curl -X POST http://localhost:42000/ -H "Content-Type: application/json" \
  -d '{"cmd":"key_tap","mac":"all","key":"tab","mods":["ctrl","shift"]}'

# 写入剪贴板
curl -X POST http://localhost:42000/ -H "Content-Type: application/json" \
  -d '{"cmd":"clipboard_write","mac":"all","text":"内容"}'

# 查询功能能力
curl http://localhost:42000/capabilities

4. 命令表（12 个命令）

音量/屏幕/键盘/鼠标/剪贴板命令需在前台模式下使用（服务模式 Session 0 不可用）；功能不可用时返回 error 并附缺失原因。

命令	参数	响应 `data`	说明
`poweroff` / `reboot`	`mac`	-	关机 / 重启
`volume_get`	-	`{volume, muted}`	查询音量
`volume_set`	`value` (0-100)	-	设置音量
`volume_mute`	`value` (1/0)	-	静音开关
`screen_off` / `screen_on`	-	-	关闭/打开显示器
`key_tap`	`key`, `mods`	-	模拟按键（支持组合键）
`key_type`	`text`	-	输入文本（Unicode）
`mouse_move`	`x`, `y`	-	移动鼠标
`mouse_click`	`button`	-	鼠标点击
`mouse_scroll`	`scroll`	-	滚轮滚动
`clipboard_write`	`text`	-	写入剪贴板
`clipboard_read`	-	`{text}`	读取剪贴板

5. 错误码说明

HTTP 接口返回标准状态码：200 成功、400 JSON 格式错误、405 方法错误、500 服务器内部错误。

状态 (status)	消息 (message)	说明
`error`	`Method not allowed`	HTTP 方法错误（如用 GET 访问 POST 接口）
`error`	`Invalid JSON format`	请求体不是有效的 JSON
`error`	`请求体过大`	请求体超过 4KB（HTTP 413）
`error`	`MAC address does not match`	请求中的 MAC 地址与本机不匹配
`error`	`Unknown command`	不支持的命令
`error`	`<功能>功能不可用: <原因>`	功能在当前环境不可用（如服务模式、缺依赖、权限不足）
`error`	`不支持的按键/修饰键/鼠标按键...`	参数非法
`skipped`	`Command skipped`	命令被跳过（MAC 不匹配）

继续阅读

ifu Agent API 完整参考手册—— 协议详解的续篇：12 个命令逐个详解（参数作用、返回值、按键名称表）、UDP/TCP 帧格式与错误响应约定。
ifu Agent 是什么？—— 快速了解产品定位与核心功能。
ifu Agent 模块架构与扩展指南—— 想为 Agent 新增命令，看模块设计与扩展流程。
ifu Agent 常见问题与排查—— 联调中遇到问题先查这篇。

关联工具

第一时间获取 ifu 团队的文章与工具更新

订阅 RSS 返回文摘