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_* 出向钩子。 - 特性列表与测试覆盖描述同步。
2026-11-07 09:47:23 +00:00 · 2026-10-11 13:07:50 +08:00
parent f4d5e779a5
commit 66786bb0e3
3 changed files with 190 additions and 25 deletions
--- a/docs/lua-adapters.md
+++ b/docs/lua-adapters.md
@ -23,7 +23,7 @@
 5. [内置辅助函数](#5-内置辅助函数)
 6. [meta 约定](#6-meta-约定)
 7. [一个完整的最小适配器](#7-一个完整的最小适配器)
-8. [多模态与 disable_thinking](#8-多模态与-disable_thinking)
+8. [多模态与 thinking 预算](#8-多模态与-thinking-预算)

 ---

@ -73,8 +73,9 @@ end

 约定：
 - 返回的字符串将被原样 POST 到 `base_url + (source.endpoint or adapter.endpoint)`。
- 请求体中包含的 `disable_thinking`、`extra_body` 等网关内部字段，转换时应自行清理
-  （`openai.lua` 即删掉这两个字段）。
+- 契约 v2 起，内核**不再向适配器泄漏任何私有字段**：请求体里不会出现
+  `disable_thinking` / `extra_body` 这类键。推理开关与预算用中立的 `thinking`
+  字段表达（见下），适配器按目标协议各自映射。

 ### `transform_response(raw_body) -> string`

@ -176,6 +177,43 @@ end

 返回非 table 会报错；返回 `{}` 表示无自定义头（不会回退静态头）。

+### 出向序列化钩子（契约 v2）
+
+默认情况下，网关把适配器产出的**统一格式**按 OpenAI 线格式序列化给下游（这是内核
+保留的兑底，R5）。当上游协议不是 OpenAI（例如 Anthropic Messages API）时，适配器
+可以接管出向序列化，自己决定写给客户端的字节。
+
+五个钩子都是可选的，**全不声明就沿用 OpenAI 兑底**。一旦声明某个钩子，它就完全
+接管那一段输出——内核不会再往里混合 OpenAI 字段（不是“叠加”，是“取代”）。
+
+| 钩子 | 何时被调用 | 返回值 |
+|------|-----------|--------|
+| `serialize_response(payload)` | 非流式响应 | 写给客户端的响应体字符串 |
+| `serialize_open_preamble(payload)` | 流式开始（发第一个 chunk 前） | 要发的字节（可为 `""`） |
+| `serialize_chunk(delta)` | 流式每个增量 | 要发的字节（`""` 表示跳过） |
+| `serialize_close(payload)` | 流式结束 | 收尾字节（如 SSE `message_stop`） |
+| `serialize_done_marker(payload)` | 流式结束处的 `[DONE]` 标记 | 要写的字节；不声明则用 OpenAI 的 `data: [DONE]` |
+
+`payload` 是统一格式的结果表（见 `internal/types/maxwire.go` 的 `UnifiedResult` /
+`UnifiedDelta`），字段名中立，不依赖具体上游协议。
+
+```lua
+-- anthropic.lua 的简化形式：把统一结果写成 Anthropic Messages 形状
+function adapter.serialize_response(payload)
+  return json.encode({
+    id = payload.id,
+    type = "message",
+    role = "assistant",
+    content = { { type = "text", text = payload.content or "" } },
+    stop_reason = payload.finish_reason == "stop" and "end_turn" or nil,
+    usage = { input_tokens = payload.prompt_tokens, output_tokens = payload.completion_tokens },
+  })
+end
+```
+
+注意：钩子返回的是**完整要发送的字节**（包括必要时的 `event:` / `data:` 前缀与
+空行），因为只有适配器知道目标协议的 SSE 细节。
+
 ## 5. 内置辅助函数

 所有适配器共享的全局函数（由 Go 注入）：
@ -219,8 +257,13 @@ adapter.headers = { ["X-Tenant"] = "prod" }
 function adapter.transform_request(raw_body)
    local ok, req = pcall(json.decode, raw_body)
    if not ok then return raw_body end
-    req.disable_thinking = nil
-    req.extra_body = nil
+    -- 契约 v2：内核不再向适配器泄漏私有字段，`thinking` 是中立语义字段。
+    -- 这里把中立的 thinking 映射成目标协议需要的形状（示例：OpenAI 家族用
+    -- reasoning_effort）。不关心推理的源可以直接忽略它。
+    if req.thinking ~= nil then
+        if req.thinking.enabled == false then req.reasoning_effort = "none" end
+        req.thinking = nil
+    end
    return json.encode(req)
 end

@ -268,11 +311,21 @@ sources:
        kind: chat
 ```

-## 8. 多模态与 disable_thinking
+## 8. 多模态与 thinking 预算

 - **多模态**：请求的 `content` 若是数组（`[{type:"text"...},{type:"image_url"...}]`），Go 层
  原样透传给适配器。协议不支持的源（Anthropic/Gemini/Ollama）需在
  `transform_request` 内转换；内置 `anthropic.lua`/`gemini.lua`/`ollama.lua` 已实现。
- **disable_thinking**：网关将请求体中的 `disable_thinking:true` 透传进
-  `transform_request`。DeepSeek 适配器将其映射为 `extra_body.thinking = { type = "disabled" }`
-  并清理自身字段；其余适配器按各自协议处理（可自行实现或忽略）。
+- **thinking**：客户端请求里的推理开关/预算被内核归一成中立的 `thinking` 字段：
+
+  ```json
+  {"thinking": {"enabled": true, "budget_tokens": 4096}}
+  ```
+
+  `enabled=false` 表示关闭推理，`budget_tokens` 可选。适配器自行映射到目标协议
+  （内置实现：Anthropic → `thinking.budget_tokens`、Gemini →
+  `generationConfig.thinkingConfig.thinkingBudget`、DeepSeek →
+  `thinking.type = "disabled"`）。不支持的源直接忽略该字段。
+
+  契约 v1 的内核私有字段 `disable_thinking` 已被取代——它曾是内核细节泄漏进
+  适配器请求体的典型例子（迫使 10 个适配器各写一行 `req.disable_thinking = nil`）。
--- a/docs/plugins.md
+++ b/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 |
 | 必需性 | 核心 | 可选，缺了网关照常跑 |