2026-08-24 09:03:37 +08:00
|
|
|
|
# UI Bridge v1
|
|
|
|
|
|
|
|
|
|
|
|
## 加载方式
|
|
|
|
|
|
|
|
|
|
|
|
宿主为每次打开配置页创建短时 UI 会话：
|
|
|
|
|
|
|
|
|
|
|
|
```text
|
|
|
|
|
|
/api/v1/plugin-ui/<asset-token>/index.html#bridge_token=<bridge-token>
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
资源 Token 用于读取包内 `ui/` 文件，Bridge Token 只存在于 URL fragment，不会发送到服务器。iframe 使用 `sandbox="allow-scripts"`，不授予 `allow-same-origin`。
|
|
|
|
|
|
|
|
|
|
|
|
UI 只能加载包内、已在清单声明的资源。CSP 禁止外部网络连接、表单提交和外部 frame。
|
|
|
|
|
|
|
|
|
|
|
|
## 消息信封
|
|
|
|
|
|
|
|
|
|
|
|
UI 到宿主：
|
|
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
|
{
|
|
|
|
|
|
"source": "sub2api-plugin-ui",
|
|
|
|
|
|
"bridge_token": "TOKEN",
|
|
|
|
|
|
"type": "config.load",
|
|
|
|
|
|
"request_id": "UNIQUE_ID"
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
宿主到 UI：
|
|
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
|
{
|
|
|
|
|
|
"source": "sub2api-plugin-host",
|
|
|
|
|
|
"bridge_token": "TOKEN",
|
|
|
|
|
|
"request_id": "UNIQUE_ID",
|
|
|
|
|
|
"ok": true
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 方法
|
|
|
|
|
|
|
|
|
|
|
|
| `type` | UI 参数 | 成功响应 |
|
|
|
|
|
|
|---|---|---|
|
|
|
|
|
|
| `sub2api.plugin.ready` | 无 | 无响应 |
|
|
|
|
|
|
| `config.load` | 无 | `config` |
|
|
|
|
|
|
| `config.save` | `config` 对象 | 规范化后的 `config` |
|
|
|
|
|
|
| `config.test` | 无 | `result` |
|
2026-09-19 11:25:56 +08:00
|
|
|
|
| `plugin.status` | 无 | `result`（`Health`：`{healthy, message, status_json}`） |
|
2026-08-24 09:03:37 +08:00
|
|
|
|
| `ui.resize` | `height` | 无响应 |
|
|
|
|
|
|
| `ui.notify` | `level`、`message` | 无响应 |
|
|
|
|
|
|
|
2026-09-19 11:25:56 +08:00
|
|
|
|
`config.test` 在 v1 中测试已保存配置（需二次验证，可产生副作用）。UI 若要测试当前表单，应先调用 `config.save`。
|
|
|
|
|
|
|
|
|
|
|
|
`plugin.status` 是只读运行时状态通道：无副作用、免二次验证、不弹宿主提示，供状态面板轮询。它映射到插件 `Health`，`result.status_json` 是插件自定义的不透明 JSON 快照。带状态展示的插件应使用它，而不是把 `config.test` 当作状态轮询。
|
2026-08-24 09:03:37 +08:00
|
|
|
|
|
|
|
|
|
|
## 必须执行的校验
|
|
|
|
|
|
|
|
|
|
|
|
UI 接收消息时必须验证 `event.source === parent`、消息来源标识、Bridge Token 和等待中的 `request_id`。每个请求必须有超时和卸载清理。
|
|
|
|
|
|
|
|
|
|
|
|
宿主不会向 iframe 提供管理员 Token。插件 UI 不得尝试访问管理 API、Cookie、父页面 DOM 或浏览器存储中的宿主数据。
|
