mirror of
https://gitcode.com/JianFeeeee/ModelRouter.git
synced 2026-11-07 09:47:23 +00:00
docs: 契约 v2 文档收尾（Phase 7）
用户要求的收尾。三份文档与代码对齐。
## docs/lua-adapters.md
- 新增 §4「出向序列化钩子（契约 v2）」：serialize_response /
serialize_open_preamble / serialize_chunk / serialize_close /
serialize_done_marker。核心语义：**声明即完全取代**内核的 OpenAI 兜底，
不是叠加 —— 适配器输出里不会有内核补的 OpenAI 字段（R2/R5）。
- §8 标题与内容从 disable_thinking 改为中立的 thinking 预算：
`{enabled, budget_tokens}`，由适配器映射到目标协议。v1 的
disable_thinking/extra_body 是内核细节泄漏进适配器请求体的典型
（迫使 10 个适配器各写一行清理），已记明已被取代。
- §7 最小适配器示例同步改成映射中立 thinking 字段。
## docs/plugins.md
- §5.4 定时任务（PLUGIN.schedule）：every/at/jitter/timeout 字段表 +
**内核 ticker 驱动、浏览器关着也跑** + 任务与钩子同一个 VM（写
plugin.state 立即可见于请求）+ 卡死则停用该插件（不能中断 Lua 的
能力边界）。
- §5.5 自定义对外挂载点：plugin.http 声明同时可在 /api/plugins/http/、
/plugins/、/v1/plugins/ 三处访问；命名空间约束与内核路由冲突拒绝。
- §5.6 运行时安装/更新适配器（token 轮换）+ 三条安全规则。
- §6.1 更正：某个卡住的钩子/任务只卡**它自己**那个插件的钩子（跨插件
并行），原文写的是"卡住所有插件"。
- §9 对比表补周期任务/对外端点两行，钩子列表补 serialize_*。
## README
- disable_thinking 章节 → thinking 预算（中立字段 + 各适配器映射）。
- 适配器协议示例补 serialize_* 出向钩子。
- 特性列表与测试覆盖描述同步。
This commit is contained in:
JianFeeeee
116
docs/plugins.md
116
docs/plugins.md
@ -301,20 +301,118 @@ PUT /api/plugins/{name}/state 替换状态（admin）
|
||||
`hook_errors` 是**排错入口**：一个坏掉的插件表现为"功能缺失"而不是报错，
|
||||
这个计数让它可见。
|
||||
|
||||
### 5.4 定时任务（`PLUGIN.schedule`）—— 浏览器关着也会跑
|
||||
|
||||
要求插件做“随时间发生”的事（自动签到、token 轮换、额度轮询）时，声明一个
|
||||
调度表：
|
||||
|
||||
```lua
|
||||
plugin.schedule = {
|
||||
{ fn = "refresh_token", every = 3600 }, -- 每小时（秒）
|
||||
{ fn = "daily_checkin", every = 86400, at = "03:30" }, -- 每天固定时刻（本地时间）
|
||||
{ fn = "poll_quota", every = 300, jitter = 30 }, -- 首次触发加 0-30s 抖动
|
||||
}
|
||||
function plugin.refresh_token()
|
||||
-- 注意：直接写 plugin.state 就是对的 ——
|
||||
-- 任务和钩子跑在同一个 VM 上
|
||||
plugin.state.token = fetch_new_token()
|
||||
end
|
||||
```
|
||||
|
||||
| 字段 | 含义 |
|
||||
|---|---|
|
||||
| `fn` | 要调用的插件函数名（必须存在） |
|
||||
| `every` | 间隔秒数。与 `at` 二选一 |
|
||||
| `at` | 每天本地时间 `"HH:MM"`；设了它就忽略 `every` |
|
||||
| `jitter` | 首次触发额外随机延迟秒数（避免多实例整点齐射） |
|
||||
| `timeout` | 解析保留但目前**不生效**（见下） |
|
||||
|
||||
要点：
|
||||
|
||||
- **内核 ticker 驱动**，不是前端轮询：没有浏览器、没人登录也会执行。
|
||||
- **任务跑在插件自己的 VM 上**，与请求钩子共用 `plugin.state` —— 任务写的
|
||||
token 对下一个请求立即可见，也会经同一套机制持久化到 `.<name>.state.json`。
|
||||
- 任务函数出错只记 `hook_errors`，不影响钩子与转发。
|
||||
- 没有 `schedule` 的插件不获得任何额外 VM/goroutine（零开销）。
|
||||
- **超时不能中断一个运行中的 Lua 调用**（本 LuaJIT 构建的硬限制）。任务超过
|
||||
10 分钟不返回，该插件被**停用**（`disarmed`）：不再调度，钩子快速失败并
|
||||
记 `hook_errors`。这是为了不让一个卡死的任务把请求永久堵在它那把锁后面。
|
||||
修好插件后重新加载（重传/重启）即可恢复。
|
||||
|
||||
> 同一条 6.1 的约束：任务占着插件锁，所以**任务里不要写死循环**。
|
||||
|
||||
### 5.5 自定义对外挂载点
|
||||
|
||||
插件的 HTTP 端点默认挂在 `/api/plugins/http/...` 下。同一个声明**同时**可在两个
|
||||
公开命名空间下访问，只要把 `path` 的第一段起成插件名：
|
||||
|
||||
```lua
|
||||
plugin.http = {
|
||||
{ path = "myplugin/callback", method = "POST", handler = "on_callback" },
|
||||
}
|
||||
```
|
||||
|
||||
该端点因此可在三个地方访问：
|
||||
|
||||
| 路径 | 用途 |
|
||||
|---|---|
|
||||
| `/api/plugins/http/myplugin/callback` | 默认前缀（带登录态的管理 UI） |
|
||||
| `/plugins/myplugin/callback` | 公开（浏览器路径） |
|
||||
| `/v1/plugins/myplugin/callback` | 公开（API 路径） |
|
||||
|
||||
可占用的命名空间只有后两个：
|
||||
|
||||
| 前缀 | 例子 |
|
||||
|---|---|
|
||||
| `/plugins/` | `/plugins/myplugin/callback` |
|
||||
| `/v1/plugins/` | `/v1/plugins/myplugin/callback` |
|
||||
|
||||
限制（都是为了不把内核路由变成可被插件改写的）：
|
||||
|
||||
- **不能影子内核路由**：与 `/v1/chat/completions`、`/v1/messages`、`/api/...`
|
||||
等重叠的挂载在加载时就被拒绝，错误信息点名冲突对象。
|
||||
- **只能是上面两个命名空间**，不接受任意前缀（否则可以拦截推理请求）。
|
||||
- 鉴权沿用端点的 `roles` / `keys` / `public` 语义（见 §5.1）；
|
||||
`/v1/plugins/...` 属于 API 路径，未认证返回 401；`/plugins/...` 为浏览器
|
||||
路径，未认证会跳登录页。
|
||||
- 未声明的路径不会因为落在允许命名空间而被放行——不在 handler 表里就是 404。
|
||||
|
||||
### 5.6 在运行时安装/更新适配器（token 轮换）
|
||||
|
||||
插件可以在运行时安装、改写**自己的**适配器 —— 这是"带自动轮换的认证"的实现
|
||||
方式：拿着新 token 重写适配器源码，后续请求自然使用新逻辑（内核重建该适配器
|
||||
的池）。这是 Phase 3 的桥接能力，安全规则如下：
|
||||
|
||||
- 插件**只能改自己装的**适配器（归属表在 Go 侧记录，不靠约定）。
|
||||
- 插件**不能影子内置适配器**（否则等于篡改发行物）；运维仍可自行覆盖。
|
||||
- 名字经过路径安全校验（无穿越/绝对路径/空白）。
|
||||
|
||||
> 注：这层桥接目前以 Go API 形式提供并被测试覆盖；插件 `.lua` 直接调用它的
|
||||
> 全局绑定尚未接通（见 plan.md 已知限制）。
|
||||
|
||||
---
|
||||
|
||||
## 6. 运行时约束（重要）
|
||||
|
||||
### 6.1 一个插件 = 一个 Lua 状态
|
||||
### 6.1 一个插件 = 一个 Lua 状态（也就是一个 VM）
|
||||
|
||||
适配器可以有多个独立的 worker 状态（它们无状态，这是对的）。**插件不行**：
|
||||
钩子通常往 `plugin.state` 里累加，多个状态就意味着总额被劈成几份，而写价格只
|
||||
写进其中一个状态，钩子恰好跑到另一个时**所有请求按 0 计费**。
|
||||
|
||||
因此插件持有**唯一一个**状态，所有入口（`Fire` / `State` / `SetState`）用互斥锁
|
||||
串行化。代价：**一个卡住的钩子会卡住所有插件的钩子**。所以——
|
||||
因此插件持有**唯一一个**状态，所有入口（`Fire` / `State` / `SetState` / **定时任务**）
|
||||
都用这同一把互斥锁串行化。
|
||||
|
||||
> **钩子必须短、同步、不阻塞。** 不要在里面做 HTTP 请求、睡眠或重计算。
|
||||
⚠️ 这条约束对**定时任务尤其关键**：任务和钩子必须是同一个 VM，否则任务写的
|
||||
`plugin.state` 是一个请求路径永远读不到的副本 —— token 轮换看起来成功了，
|
||||
对实际流量完全无效。
|
||||
|
||||
代价：**一个卡住的钩子会卡住该插件自己的钩子**（跨插件仍然并行，每插件各自
|
||||
一把锁、各自一个 VM）。所以——
|
||||
|
||||
> **钩子与定时任务都必须短、同步、不阻塞。** 不要在钩子里做 HTTP 请求、睡眠
|
||||
> 或重计算；长耗时的周期工作应放进 `PLUGIN.schedule`（见 §5.4），它在自己的
|
||||
> 调度 goroutine 上跑，但仍然持有这把锁，因此不能是死循环。
|
||||
|
||||
### 6.2 异常被隔离
|
||||
|
||||
@ -497,10 +595,12 @@ journalctl -u llmsproxy -f | grep -i plugin
|
||||
| | 适配器 | 插件 |
|
||||
|---|---|---|
|
||||
| 位置 | `adapter_dir` | `plugin_dir` |
|
||||
| 作用 | 上游协议转换 | 请求流水线 + 界面 |
|
||||
| 钩子 | `transform_request` / `transform_response` / `transform_stream_chunk` / `build_headers` / `transform_error` | `request_start` / `routed` / `request_end` |
|
||||
| 状态 | 每个源独立，多 worker | 单状态，见 §6.1 |
|
||||
| 出错后果 | 该 (源,模型) 进入冷却退避 | 仅该功能缺失 |
|
||||
| 作用 | 上游协议转换 | 请求流水线 + 界面 + 周期任务 |
|
||||
| 钩子 | `transform_request` / `transform_response` / `transform_stream_chunk` / `build_headers` / `transform_error` / `serialize_*` | `request_start` / `routed` / `request_end` |
|
||||
| 周期任务 | **无**（无状态请求级） | `PLUGIN.schedule`（内核 ticker 驱动） |
|
||||
| 对外端点 | 不开放（见 §5.5） | `/api/plugins/http/...` + 自定义挂载 |
|
||||
| 状态 | 每个源独立，多 worker | **单 VM、单状态**，见 §6.1 |
|
||||
| 出错后果 | 该 (源,模型) 进入冷却退避 | 仅该功能缺失；卡死则停用该插件 |
|
||||
| 鉴权 | 需要 `gateway_keys` 之外的独立凭据 | 网关 key |
|
||||
| 必需性 | 核心 | 可选，缺了网关照常跑 |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user