Android 薄接口

Android 宿主不通过 WebSocket 做所有事。启停实例、读状态、挂起更新这些操作走一组更薄的 HTTP 接口，前缀 /android/。

启用条件

只有在设置环境变量后才会注册路由：

AZURPILOT_ANDROID=1

桌面版没有这些路由。

鉴权

GET /android/status HTTP/1.1
X-AzurPilot-Android-Token: <token>

要求同时满足：

1. 请求来自回环地址（127.0.0.1 / ::1）。
2. Header 与 Runtime 持有的 token 常量时间比较一致。

否则返回 403 {"error": "loopback only"}。

不要把 25548 暴露到局域网后指望这层保护

薄接口的安全模型是「只允许本机」。一旦端口被转发出去，其他防护只剩 WebSocket 密码。

实例参数

所有涉及实例的接口接受查询参数：

?config=<实例名>

省略时：

• 若有正在运行的实例，取第一个；
• 否则用 alas。

实例名必须存在，否则返回 400。

端点

方法	路径	用途
GET	/android/status	运行状态
GET	/android/configs	实例名列表
GET	/android/logs?tail=N	纯文本日志（N ≤ 2000）
POST	/android/start	启动实例
POST	/android/stop	停止实例
POST	/android/tool/start?name=<tool>	启动工具任务
POST	/android/tool/stop	停止工具任务
GET	/android/update/status	热更状态
POST	/android/update/apply	应用热更
POST	/android/update/suspend	为整包更新挂起所有实例

status

{
  "runner_alive": true,
  "pid": 12345,
  "config": "ap",
  "gui_alive": true,
  "tool_alive": false,
  "tool_name": null,
  "log_lines": 128
}

字段	含义
runner_alive	实例在跑且当前不是工具任务
pid	调度器进程号
config	当前实例名
gui_alive	后端存活（当前实现恒为 true）
tool_alive / tool_name	是否在跑工具任务
log_lines	日志条目数

start / stop

• start：先停掉其他运行中的实例，再启动目标实例。若目标已经在跑同一个任务，直接返回状态。
• stop：只停目标实例。
• 两者都会先检查旧版宿主进程是否占用设备（探测 22300 与 22400）。占用时返回 DEVICE_BUSY，提示先停止旧版任务。

tool/start

支持的工具：

name	任务
daemon	Daemon（半自动点击）
event_story	EventStory（活动剧情）

未知名称返回 400。工具任务同一时间只能有一个。

logs

返回 text/plain，每行一条，默认 80 行：

GET /android/logs?config=ap&tail=200

update/suspend

整包更新前调用。行为：

1. 枚举所有运行中的调度器与工具任务。
2. 把实例名写入 config/reloadalas。
3. 逐个优雅停止。
4. 返回 {"ok": true, "suspended": ["ap", "ap-2"]}。

下次 WebUI 启动时 restart_processes() 读取该清单，自动复活被挂起的实例。

不要把 suspend 当成普通停止

它写恢复清单。手动调用后如果不再启动 WebUI，实例会一直停着。

错误

状态码	场景
400	实例不存在、未知工具、参数非法
403	非回环请求或 token 不匹配
404	路径不存在

错误体：

{ "error": "DEVICE_BUSY" }

错误信息会说明具体原因（如已有实例在运行、旧版任务未停止），按提示处理即可。

与 WebSocket 的分工

操作	走哪条
配置读写、任务参数	WebSocket
日志与统计订阅	WebSocket
启停、状态轮询	HTTP 薄接口
热更	HTTP 薄接口

Android 宿主用 HTTP 做「开关」，用 WebSocket 做「数据面」。这样即使 WebSocket 断线，宿主仍能安全地停止实例。