接口总览
核心程序对外只有三类接口。它们共享同一套配置与进程模型，但协议、鉴权与适用场景不同。
| 接口 | 端点 | 协议 | 鉴权 | 用途 |
|---|---|---|---|---|
| WebSocket API | /api/v1/ws | JSON RPC over WS | 会话密码 / 配对凭据 | 前端、Android、自建看板 |
| Android 薄接口 | /android/* | HTTP | 本机回环 + Header Token | Android 宿主 |
| MCP 服务 | /mcp/sse 或独立 :22268 | MCP SSE | Bearer（WebUI 密码） | AI 客户端 |
另有 /healthz 用于就绪探测，无鉴权、无业务数据。
稳定性边界
只有注册的方法才是公开接口
module/api/router.py 里的 72 个方法是公开契约，由 dev_tools.export_api_schema 生成类型。业务模块内部的 Python 函数不是 API，不要在前端或外部工具里直接调用。
| 层 | 稳定性 |
|---|---|
router.py 注册方法 | 公开，参数模型受严格校验 |
/android/* | App 专用，随宿主版本演进 |
| MCP 工具 | 公开，数量与语义随版本变化 |
| 内部 service / 模块函数 | 私有，随时可改 |
端口
| 端口 | 用途 | 来源 |
|---|---|---|
25548 | WebUI + WebSocket | deploy.yaml 的 WebuiPort |
22267 | 启动器打开的 WebUI | 启动器指定 |
22268 | 独立 MCP / OCR 服务 | OcrServerPort |
22302 | Android OCR 张量 API | Android :ocr |
22300 / 22400 | 旧版宿主进程探测 | Android 兼容检查 |
22268 是共用端口
MCP 独立服务与 OCR 服务默认都用 22268。同机运行两者会冲突，先改其中一个。
鉴权
| 场景 | 方式 |
|---|---|
| 本机回环、未设密码 | 免密 |
| 浏览器 / 局域网 | auth.login 提交 WebUI 密码 |
| Android 远程客户端 | 配对凭据（独立于主密码） |
| Android 本地宿主 | X-AzurPilot-Android-Token，且必须来自回环 |
| MCP | Authorization: Bearer <WebUI 密码> 或 ?key= |
密码来源：--key 参数、config/deploy.yaml 的 Password，或自动生成的 password.txt。
最小示例
WebSocket：
json
{"v":1,"type":"request","id":"1","method":"system.ping","params":{}}
{"v":1,"type":"response","id":"1","ok":true,"result":{"pong":true}}HTTP：
bash
curl -s http://127.0.0.1:25548/healthzMCP：
json
{
"mcpServers": {
"azurpilot": {
"url": "http://127.0.0.1:25548/mcp/sse",
"headers": { "Authorization": "Bearer <WebUI 密码>" }
}
}
}