本文是 ifu Agent 的 API 完整参考手册，面向需要二次开发的开发者（控制端、自动化脚本、集成方）。如果你只需要快速了解协议能力，可以先读《ifu Agent 通信协议与 API 详解》。
1. 接口总览
ifu Agent 同时开放三个端口，职责清晰：
| 协议 | 端口 | 用途 |
|---|---|---|
| HTTP | 42000 | REST API + Web 控制台 |
| TCP | 42001 | 可靠指令通道（需要确认送达的场景） |
| UDP | 42002 | 设备发现 + 简单命令 |
2. 通用请求格式
所有命令均为 JSON 对象，核心字段：
| 字段 | 类型 | 必选 | 说明 |
|---|---|---|---|
cmd |
string | ✅ | 命令名（见第 4 节命令详解） |
mac |
string | ✅ | 目标机器 MAC 地址；"all" 表示广播（本机验证通过才执行） |
value |
int | 按命令 | 数值参数（音量 0-100、静音开关 0/1） |
text |
string | 按命令 | 文本参数（键盘输入、剪贴板内容） |
key |
string | 按命令 | 按键名称（见 4.5 按键名称表） |
mods |
[]string | 按命令 | 修饰键列表：ctrl / shift / alt / win |
x / y |
int | 按命令 | 鼠标屏幕坐标 |
button |
string | 按命令 | 鼠标按键：left / right / middle（默认 left） |
scroll |
int | 按命令 | 滚轮格数（正=上滚，负=下滚） |
MAC 地址支持 4 种格式（统一为小写）：
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 字节 |
3. 通用响应格式
{
"status": "success | error | skipped",
"message": "人类可读信息",
"data": {}
}
| 状态 | 含义 |
|---|---|
success |
命令执行成功 |
error |
执行失败，message 含失败原因（含功能不可用原因） |
skipped |
MAC 地址不匹配，命令未执行 |
data 为可选字段，仅在查询类命令（volume_get、clipboard_read）中返回。
4. 命令详解（12 个命令）
音量 / 屏幕 / 键盘 / 鼠标 / 剪贴板命令需在前台模式下使用；服务模式（Session 0）下返回
error并附缺失原因。可用GET /capabilities查询。
4.1 电源控制
| 命令 | 参数 | 响应 data |
说明 |
|---|---|---|---|
poweroff |
mac |
- | 立即关机 |
reboot |
mac |
- | 立即重启 |
{ "cmd": "poweroff", "mac": "aa:bb:cc:dd:ee:ff" }
{ "status": "success", "message": "Executing reboot command" }
4.2 系统音量（前台模式可用）
| 命令 | 参数 | 响应 data |
说明 |
|---|---|---|---|
volume_get |
- | {"volume": 50, "muted": false} |
查询当前音量（0-100）与静音状态 |
volume_set |
value (0-100) |
- | 设置音量，越界返回错误 |
volume_mute |
value (1=静音, 0=取消) |
- | 切换静音状态 |
{ "cmd": "volume_set", "mac": "all", "value": 30 }
{ "status": "success", "message": "获取音量成功", "data": { "volume": 50, "muted": false } }
4.3 屏幕开关（前台模式可用；Linux 仅 X11）
| 命令 | 参数 | 响应 data |
说明 |
|---|---|---|---|
screen_off |
- | - | 关闭显示器（DPMS 待机） |
screen_on |
- | - | 打开显示器 |
{ "cmd": "screen_off", "mac": "all" }
4.4 键盘模拟（前台模式可用）
| 命令 | 参数 | 响应 data |
说明 |
|---|---|---|---|
key_tap |
key, mods |
- | 模拟按键（支持组合键） |
key_type |
text |
- | 输入文本（支持 Unicode） |
{ "cmd": "key_tap", "mac": "all", "key": "c", "mods": ["ctrl"] }
组合键示例：{"key":"tab","mods":["ctrl","shift"]} 等价于 Ctrl+Shift+Tab。
4.5 key_tap 支持的按键名称
字母 a-z、数字 0-9、功能键 f1-f12，以及：
| 名称 | 按键 | 名称 | 按键 |
|---|---|---|---|
enter / return |
回车 | space |
空格 |
tab |
Tab | esc / escape |
退出 |
backspace |
退格 | delete / del |
删除 |
insert |
插入 | home / end |
Home / End |
pageup / pagedown |
翻页 | up / down / left / right |
方向键 |
capslock |
大写锁定 | printscreen |
截屏键 |
scrolllock / pause |
锁定 / 暂停 | minus / equals |
- / = |
comma / period / dot |
, . | slash / backslash |
/ \ |
semicolon / quote |
; ' | bracketleft / bracketright |
[ ] |
4.6 鼠标控制（前台模式可用）
| 命令 | 参数 | 响应 data |
说明 |
|---|---|---|---|
mouse_move |
x, y |
- | 移动鼠标到屏幕坐标 |
mouse_click |
button |
- | 单击（left / right / middle） |
mouse_scroll |
scroll |
- | 滚动滚轮（格数） |
{ "cmd": "mouse_click", "mac": "all", "button": "right" }
4.7 剪贴板（前台模式可用；Linux 需 xclip/xsel/wl-copy）
| 命令 | 参数 | 响应 data |
说明 |
|---|---|---|---|
clipboard_write |
text |
- | 写入剪贴板（Unicode） |
clipboard_read |
- | {"text": "剪贴板内容"} |
读取剪贴板文本 |
{ "cmd": "clipboard_write", "mac": "all", "text": "要复制的内容" }
{ "status": "success", "message": "读取剪贴板成功", "data": { "text": "剪贴板内容" } }
5. UDP 设备发现协议
设备发现基于 UDP 广播，允许控制端在不知道 IP 的情况下发现局域网内的设备。
发现流程：
- 控制端向
255.255.255.255:42002发送广播包。 - 客户端收到广播包后校验
server字段。 - 客户端向控制端的发送源 IP 和端口回复单播响应包。
请求包（ping）：
{
"type": "discovery",
"action": "ping",
"server": "ifu-agent-server",
"timestamp": 1734267000
}
server 字段必须匹配 ifu-agent-server，否则请求被忽略。
响应包（pong）：
{
"type": "discovery",
"action": "pong",
"mac": "00:11:22:33:44:55",
"response_time": 1734267001,
"timestamp": 1734267001
}
时间戳同步规则：时间戳非零时，接收方会将本机时钟同步为发送方时间（差异超过 30 秒时执行）。
6. TCP 控制协议
- 端口
42001，长连接或短连接均可（建议发送完命令接收响应后断开）。 - 每行一条 JSON 命令，以
\n结尾，单行上限 4KB。
交互流程： 建立连接 → 发送 JSON 命令 → 接收 JSON 响应 → 断开。
{"cmd":"volume_set","mac":"all","value":30}
{"status":"success","message":"Executing reboot command"}
7. HTTP 特殊端点
| 端点 | 方法 | 说明 |
|---|---|---|
/health |
GET | 健康检查，返回 {"status":"success","time":"2024/05/20 10:00:00"} |
/control |
GET | Web 控制面板（HTML 页面） |
/capabilities |
GET | 功能能力清单（可用性与缺失原因） |
/capabilities 返回 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 }
]
}
8. 错误码与响应约定
HTTP 接口返回标准状态码：200 成功、400 JSON 格式错误、405 方法错误、413 请求体过大、500 服务器内部错误。
| 场景 | 响应 |
|---|---|
| JSON 解析失败 | HTTP 400 {"status":"error","message":"Invalid JSON format"} |
| 请求体超限（>4KB） | HTTP 413 {"status":"error","message":"请求体过大"} |
| HTTP 方法不允许 | HTTP 405 |
| 命令未知 | {"status":"error","message":"Unknown command"} |
| MAC 不匹配 | {"status":"skipped","message":"Command skipped - MAC address mismatch"} |
| 功能不可用 | {"status":"error","message":"<功能>功能不可用: <缺失原因>"} |
| 参数非法 | {"status":"error","message":"不支持的按键: ..."} / "音量必须在 0-100 之间" 等 |
功能不可用示例：{"status":"error","message":"键盘模拟功能不可用: /dev/uinput 无写权限"}
9. curl 快速上手
# 关机
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
继续阅读
- ifu Agent 通信协议与 API 详解—— 协议入门概览，三协议定位与交互流程。
- ifu Agent 模块架构与扩展指南—— 想新增命令，看模块设计与扩展流程。
- ifu Agent 常见问题与排查—— 联调中遇到问题先查这篇。
