集成与 API

把 IFU 接进现有系统

1. 集成方式总览

三种传输共用同一命令契约：同一命令在任一传输上的参数校验、MAC 守卫、响应结构完全一致。

2. 接口清单

3. 认证

按顺序判定，命中即放行：

• 令牌首次启动自动生成，写入配置文件 auth.token。
• 回环来源（127.0.0.1 / ::1）免认证，但叠加 Origin / Referer / Host 校验；高危命令（power.*、screen.*、input.*、clipboard.*、process.kill、timesync.set、notify.toast）即使来自回环也强制认证。内核会把内置默认清单与 config.json 的 auth.high_risk_commands 做并集合并，因此覆盖安装后新增的高危命令自动生效、无需手改配置；可在配置里追加自定义项，但不能靠删配置项缩小保护范围。
• 管理端点（/admin/*）无论来源一律要求令牌或证书，不接受回环免认证——否则任意网页都能借浏览器发起跨站请求来操作插件。
• 免认证端点：GET /health、GET /capabilities；/console/ 页面本身为静态资源不鉴权，页内每个管理请求仍需令牌。

HMAC 签名三字段：sig（HMAC-SHA256，base64url 无填充）、ts（Unix 秒）、nonce（16 字节 base64url，同窗口内不重复）。 待签字符串：

FOXAGENT-HMAC-V1

其中 canonicalBody 是报文剔除 sig/ts/nonce 后重新序列化的结果；scope 命令请求为命令名，管理端点为「方法 + 空格 + 完整请求目标（含查询串）」。

4. 请求参数

所有命令均为扁平 JSON，核心字段：

传输细节：HTTP POST /，Content-Type: application/json，上限 4KB；TCP 每行一条 JSON 以 结尾，单行上限 4KB；UDP 单包上限 2048 字节。

5. 命令表

大结果（screen.capture / file.read 超限时 / log.export）不放在返回体里，只回 blob_id 等引用， 内容经 GET /blob/{id} 流式下载（需认证，见第 2 节）。原因：内核读插件 stdout 有单行 1MB 上限。

5.1 设备发现（UDP 专用）

请求：

{"type":"discovery","action":"ping","timestamp":1758500000}

响应：

{"type":"discovery","action":"pong","mac":"00:e0:4c:82:84:54","response_time":0,"timestamp":1758500001,
 "hostname":"DESKTOP-ABC","os":"windows","arch":"amd64","kernel_version":"4.3.0","protocol_version":1,"uptime_seconds":123456}

• pong 载荷字段：type、action、mac、response_time、timestamp，以及只读的 hostname / os / arch / kernel_version / protocol_version / uptime_seconds（后 6 项为本版新增）。
• mac 为本机真实物理网卡 MAC（自动排除虚拟网卡）；探测失败回退为 00:00:00:00:00:00。
• 本机不执行任何校时：请求里的 timestamp 仅作对端比对用、被本机忽略，pong 里的 timestamp 是本机应答时刻。发现通道是无副作用的应答通道（UDP 分支不经认证层），不改变任何系统状态；如需校准目标机时钟，请改用经认证的 timesync.set 命令（见第 5 节命令表）。

6. 返回值

{
  "status": "success | error | skipped",
  "message": "人类可读信息",
  "data": { }
}

7. 错误码

HTTP 层

插件协议层（不外露，仅内核日志）

业务响应示例

8. 调用示例

# 设置音量 30（命令端点，回环免 Token）
curl -X POST http://localhost:42101/ -H "Content-Type: application/json" 
  -d '{"cmd":"volume.set","mac":"all","value":30}'

# 组合键 Ctrl+Shift+Tab（input.key.tap 属高危命令，即便回环也需带 Token）
curl -X POST http://localhost:42101/ -H "Content-Type: application/json" 
  -H "X-Auth-Token: " 
  -d '{"cmd":"input.key.tap","mac":"all","key":"tab","mods":["ctrl","shift"]}'

# 写入剪贴板（clipboard.write 属高危命令，即便回环也需带 Token）
curl -X POST http://localhost:42101/ -H "Content-Type: application/json" 
  -H "X-Auth-Token: " 
  -d '{"cmd":"clipboard.write","mac":"all","text":"内容"}'

# 非回环：携带 Token
curl -X POST http://192.168.1.10:42101/ 
  -H "Content-Type: application/json" 
  -H "X-Auth-Token: " 
  -d '{"cmd":"power.reboot","mac":"aa:bb:cc:dd:ee:ff"}'

# 查询能力清单（免认证）
curl http://localhost:42101/capabilities

# TCP：每行一条命令
echo '{"cmd":"volume.get","mac":"all"}' | nc 127.0.0.1 42102

# 管理：查看插件清单（管理端点不接受回环免认证，必须带 Token）
curl -H "X-Auth-Token: " http://localhost:42101/admin/plugins

# 管理：内核状态汇总
curl -H "X-Auth-Token: " http://localhost:42101/admin/status

# 管理：命令清单（含命令作用、用法、参数与结果 schema，可当插件文档读）
curl -H "X-Auth-Token: " http://localhost:42101/admin/commands

本机 Web 控制台直接用浏览器打开 http://127.0.0.1:42101/console/ 即可；页面本身免认证，首次进入后把 auth.token 粘进登录框，后续页内管理请求会自动带上该令牌。

9. 集成注意事项

• 连接数 / 超时：TCP 为长连接，单行上限 4KB；UDP 单包上限 2048 字节，超限请拆包或改用 TCP。
• 心跳与发现：无插件处理发现请求时内核不回包，调用方应以超时判定「对端不存在」；建议超时 1–2 秒。
• 签名防重放：nonce 在同一时间窗内只能用一次，重复即拒绝。
• 时钟：启用 HMAC 时调用方与终端时钟须同步，否则会表现为「签名无效」。
• 不降级原则：报文一旦出现 sig/ts/nonce，就必须验签通过，不允许「签名无效退回令牌」。
• 能力先行：对接前先读 /capabilities，据此决定可调用范围；能力不可用时命令会直接失败并给出原因。

分享