jianf/ModelRouter
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/ModelRouter.git synced 2026-11-07 09:47:23 +00:00
Code Issues Packages Projects Releases Wiki Activity
361 Commits 10 Branches 90 Tags
711ccdeea8ebe6c692b35f459c134fc64d6ebef1
Commit Graph

13 Commits

Author SHA1 Message Date
JianFeeeee
9bec158d2e chore(main): 回流 release/v2.0.x（v2.0.12）—— 内容对齐，main 无独有内容 
按发布纪律回流。**注意这是内容对齐而非 merge**，理由与依据：

1. 纪律禁止 merge 回主干，因为 merge 会把发布分支的**版本号变更**带进 main。
   本项目版本号**只由 `git describe --tags` 推导**（Makefile VERSION），
   仓库里没有任何文件存放版本号 ⇒ 回流不存在版本污染风险。
2. 逐项核对确认 **main 是 release 的内容严格子集**：
   - `main` 独有的**文件**：0 个；
   - `internal/lua/plugins.go` / `internal/core/kernel_actions.go` 等内核文件
     main 独有行数：0；
   - `deploy.sh` 那 14 行只是 emoji 清理（release 刻意去掉了 emoji）；
   - `channels.lua` 那 333 行是**旧版内容**（旧 exports 表、旧模型名单）。
   - main 独有的 9 个提交按 patch-id **全部已在 release 中等效存在**
     （`git cherry` 逐条列出均为 `-`，即已合入）。
3. 故回流 = 把 release 的内容带到 main，等价于"只捡拾修复、不带版本号"，
   且不会丢任何 main 独有的修复。

本次带回 v2.0.12 的全部内容（37 个提交）：
- 源串行 + 按模型节流（照 model-gate）
- 已失效模型存储 + 远端目录闸门
- 余额分档选号
- 模型能力元数据（models.dev，isFree 权威判定）
- **凭据续期修复**（此前恒报 ok:true 却一个请求都不发）
- 通用件 TTL 缓存 + 串行锁；account_test/account_adopt/account_delete 修正
- 内核级：出站授权持久化重启后不生效、`__llmsproxy_plugin_dir` ground truth

校验：`git diff release/v2.0.x` = 0 行；`go build -tags luajit ./...` 通过。
 2026-10-14 16:52:58 +08:00
JianFeeeee
93eeba3762 feat(types): 统一格式落地为内核实际使用的类型 —— 私有字段泄漏归零 
Phase 2 收尾（入向）。ChatRequest 从"客户端发什么就是什么"改为
UnifiedRequest（最大集合）的别名，内核真正用上了那个超集类型。

改掉的具体缺陷：

1. 私有字段泄漏归零（v1 的核心问题）
   v1 的 disable_thinking 是内核私有开关，却被序列化进交给适配器的 body，
   迫使 10 个适配器各自写 req.disable_thinking = nil 来清理。
   现在它是中立的 thinking 字段（{enabled, budget_tokens}），客户端与
   适配器都认这个词：
   - gateway/chat.go：thinkingFromClient() 把 disable_thinking 翻译成
     thinking.enabled=false；冲突时中立字段优先（它能带预算，布尔不能）
   - deepseek.lua：thinking.enabled=false → extra_body.thinking.type=disabled
   - anthropic.lua：thinking.enabled=true + budget → 原生 {type,budget_tokens}
     （enabled=false 时不传该字段——Anthropic 没有 type=disabled 这个写法）
   - 其余 7 个适配器：把"清理内核私有字段"改成"清理中立字段"

2. Tools/ToolChoice 改 json.RawMessage
   原为 []interface{}（OpenAI 原始形状 = 内核在假设某个协议）。
   内核从不解释工具 schema——它原样交给适配器，所以原始形状不损失任何
   内核侧统一性。ToolDef 结构化类型保留在包内供新适配器选用。

3. 删除 MarshalJSON 后门
   v1 手工 splice ExtraBody 进 OpenAI 形状的 body；现在 ExtraBody 是
   UnifiedRequest 上一个正正经经声明的字段。

渐进迁移：ChatRequest 保留为别名（不是新类型），49 处引用零改动编译，
语义变更不被机械改名淹没。

测试：新增 thinking_test.go（翻译链 4 例 + 泄漏回归 + tools 透传）；
vm_test.go 两处迁移到中立语义。golden 字节级未漂移。
 2026-10-11 09:35:32 +08:00
JianFeeeee
91e3013cb5 feat(billing): 长上下文阶梯定价（边际费率，与缓存折扣/峰段可叠加） 
## 影响面实测

审计里 1000 条请求：**883 条（88.3%）prompt 超过 128k**，中位数 246849，
p90 298179，最大 354251。这不是小众场景，是 agent 负载的主流形态。

按「模型 × 源」拆开：其中真正按 token 计价的只有 alittokenplan 的 10 次
（deepseek-v4.1-flash，约 350k prompt），其余走 $70 套餐（commandcode）或
免费源（localzen），记 0 是正确的，对阶梯无影响。

那 10 次当前少算 54.9%（$0.3148 → $0.4877）。绝对值不大，但比例严重，
而且这个偏差只会随上下文变长而变大。

## 边际而非混合平均

阶梯只对**超过阈值的部分**重新计价，不是把整段按高价算。理由是可叠加性：
缓存读取同时享受缓存折扣**和**长上下文阶梯价，这与供应商的计费方式一致。
混合平均必须二选一，选错就正好低估「缓存命中的长请求」——而这恰是缓存
存在的意义所在（本部署缓存命中率 88%）。

超出部分按缓存/新鲜的比例拆分，不重不漏。

## DSL 两种写法

供应商两种发布方式都支持：绝对费率（OpenAI 报 \$3.00/M past 200k）和
倍数（DeepSeek 报 2x past 128k）。两者都缺必须报错 —— 一个没有费率的阶梯
会编译成一条「看起来处理了长上下文、实际没处理」的规则，静默少算且无迹可寻。
两者都给时以绝对费率为准，因为那是供应商真正报出的数字。

## 判据

Lua 侧两条（边际性、与缓存折扣叠加）+ Go 侧一条（两种写法与拒绝规则）。
变异自证三次：整段按高价 / 缓存部分不叠加折扣 / 缓存部分不计阶梯，
分别命中 0.40 vs 0.272、0.165 vs 0.2325、0.09 vs 0.2325。

规则编辑器加了三个输入（阈值 + 绝对费率 + 倍数），三项都留空 = 无阶梯 ——
与「阶梯费率为 0」刻意区分，所以是三个独立输入而不是从 0 推断是否存在阶梯。

Co-Authored-By: ModelRouter <noreply@modelrouter.dev>
(cherry picked from commit 314f4da8f2)
 2026-10-04 14:50:47 +08:00
JianFeeeee
d119d09929 feat(billing): 记录 reasoning token，并支持按规则单独定价（默认不启用） 
## 断掉的链路

types.go 里 ReasoningTokens 从被定义起就没人读过。适配器层早就解析并透传了
（opencodego / gemini / anthropic 都写了那段提取），网关在 chat.go 记录 usage
时读了 PromptTokensDetails.CachedTokens，却在隔壁的
CompletionTokensDetails.ReasoningTokens 上把它丢了 —— 数字到了响应里，
在唯一能留住它的地方被扔掉。

后果：任何计费规则都无法区分「思考」和「可见输出」。

## 为什么默认不启用定价

实测四个源（deepseek-v4.1-flash / claude-opus-4-8 / glm-5.3-flash /
space-bunny-free，含 anthropic thinking opt-in）全部不返回该字段。所以
reasoning_price 默认为 nil，costFor 完全跳过该分支，标准公式与改动前逐位相同
—— 这是关键：现有账单不能因为这次改动而变动。

启用时只应用「差额」：把思考部分从普通输出价重定价到思考价。完整再收一次会
对每个思考 token 双重计费，这正是判据里最容易被写出的错误实现。

clamp 到 completion_tokens：供应商报出比 completion 还大的 reasoning 是畸形
数据，不 clamp 会得到 92 倍于整个请求的费用，而且这个数字看起来足够合理，
能在仪表盘上活下来。

判据三条 + 三次变异自证（移除 clamp / 双重计费 / 默认启用）全部变红。

## 遗留

reasoning_price 未接入 BillingRule DSL —— 目前只能通过直接写 prices 生效。
DSL 字段要连带改 config 结构、编译器和规则编辑器 UI，是独立一步。
实测全部源都不返回该字段，所以这条暂时没有实际影响面。

Co-Authored-By: ModelRouter <noreply@modelrouter.dev>
(cherry picked from commit c36200b78b)
 2026-10-04 14:50:47 +08:00
JianFeeeee
27b908d98c fix(billing): 未定价按天统计，让「已修好」和「还在漏」不再长得一样 
计费页只有一个终身计数器 unpriced_reqs，实测 6378 —— 占 18981 请求的 34%。
但这个数字回答不了运维唯一会问的问题：「还在漏吗？」

原因是它把两件事混在一起：加规则之前的历史欠账，和加规则之后仍在发生的漏计。
修好一个源之后终身计数纹丝不动，于是仪表盘上「未定价 6378」和一个仍在
什么都没记的系统完全无法区分。

改动：
- 钩子按 UTC 天写入 unpriced_by_day{day:{reqs, models}}。终身计数保留
  （报表不该改写历史），天桶是新增的观察维度。
- 页面加「未定价（近 7 天）」一行。为 0 时额外显示「近 7 天无」——这时候
  零本身就是结论：加的规则确实生效了。
- 没有天桶数据时返回 null 而不是 0。旧的 state 文件说「未知」，
  不该假装有一份干净记录。

生产实测：全部视图 终身 6378 / 近 7 天 2；日视图隐藏终身计数（null）但保留
近 7 天 —— 周期视图原本把两者都置 null，因为那时根本没有天桶。

失败的请求同样计入（上游 502 的 gpt-5.5 也进了天桶）：一次失败的请求照样
消耗上游配额，只是没拿到 token，单看 token 维度会漏掉。

判据：两个不同日期的请求必须落到两个天桶且终身计数不重复累加；变异成
「总记今天」即变红（只判首日会漏掉这一点）。

Co-Authored-By: ModelRouter <noreply@modelrouter.dev>
(cherry picked from commit ba6de89d57)
 2026-10-04 14:50:46 +08:00
JianFeeeee
85c81c63cc feat(plugins): ccquota 多账户额度插件 + 页面→Lua 调用通道 
A quota plugin cannot work on billing's model. Billing reports what the gateway
already measured, delivered on hooks during request forwarding. A plan balance
has no such arrival path: it exists only on the vendor's side, and the only way
to learn it is to ask — at the moment the operator clicks Refresh. No hook fires
on a click, and pluginAPI offered only state read/write.

So this adds the missing piece: POST /api/plugins/{name}/call/{fn}, plus
pluginAPI.call on the page side.

## Why the gate is an explicit export list

That endpoint is an HTTP surface into a Lua state. Without a declared allowlist
it would let any caller invoke the plugin's private helpers with crafted
arguments and read whatever it can see — for a plugin holding an API key, that
is handing the key to anyone who can POST. So a function is callable only if the
plugin listed it in plugin.exports. A plugin with no exports has no callable
surface; reading the missing list as "allow all" is exactly the failure mode
worth designing against. The endpoint is also admin-only.

## ccquota

One account per configured source on api.commandcode.ai, keyed by that source's
own key — two keys on one host are two seats, and both are shown. Reads
/alpha/whoami, /alpha/billing/credits, /alpha/billing/subscriptions and
/alpha/usage/summary. Each endpoint degrades independently: a vendor retiring
one route must not blank the others, and a key out of quota still reads credits
fine while inference 401s, so the report records WHICH part failed rather than
rendering a zero that reads as "no quota left".

The 401-is-everything trap: those endpoints need a bearer token plus three
headers. The token lives in the table now, per request. Passing the shared
header table straight through — my first version — yields 401 on every
endpoint, which is indistinguishable from a revoked key and sent me auditing the
account instead of the plugin.

## Also fixed: three real defects found by going live

- The bridge was registered as `httpGlobal` (the Go const's IDENTIFIER) instead
  of `__llmsproxy_http` (its VALUE). Green unit tests, "attempt to call global
  '__llmsproxy_http' (a nil value)" on first real request. Now a test boots a
  real plugin and calls it the way a plugin does.
- The call router kept `call/` in the function name, so every call 502'd with
  `does not export "call/collect_account"` while the exports list looked fine.
- readPluginExports used luaToJSON, which needs the `json` global — not yet
  installed while a plugin is registering — so it silently returned an empty
  list and every export looked undeclared. It uses luaTableToGoValue now.

Two tests hardcoded counts ("1 bundled plugin", "4 pages") and turned red the
moment a second bundled plugin existed. They now assert what they mean: billing
is among the bundled plugins, and the pages this test contributed all merged in
order. A count assertion is a changelog detector.

## Verified on production

  commandcode    2198972886@qq.com  active  $0.0811  5h 0/14  wk 0.803/35  44,921 req
  commmandcode2  jianf3112@gmail.com active  $0.0700  5h 0/14  wk 0/35      43,827 req

Co-Authored-By: ModelRouter <noreply@modelrouter.dev>
(cherry picked from commit 111dc6d53f)
(cherry picked from commit 22c9215b02)
 2026-10-04 14:50:46 +08:00
JianFeeeee
c19b8e6394 fix(scheduler): AUTO 遇空内容响应降级到下一个 slot（客户端曾报 "no content"） 
生产故障：pi 客户端报 `model "AUTO" returned a completed response with no content`，
重试延迟 8 秒。实测 AUTO 20 次有 2 次返回空 content，全部是 claude-opus-4-8。

根因（直连上游抓包确认）：思考型模型先吐 reasoning_content，max_tokens 小到
思考阶段就把预算用完时，上游返回 200 / finish_reason=length，28 个 chunk 全是
reasoning_content、content 一片空白。runTier 只看 err == nil 就当成功返回，
客户端拿到一个空响应。

修复：
- resultIsEmpty：非流式路径把「无 content、无 tool_calls、无 image」的响应当作
  slot 失败继续降级。注意 ReasoningContent 不算内容——客户端要的是文本，为
  另一个模型的思考阶段扣住请求比降级更糟。
- peekStream：流式路径在出现首个真实内容前缓冲 reasoning 前导，流结束仍无内容
  则回报空结果，让 chainDrive 换 slot。缓冲只覆盖思考前导，拿到内容后立即
  转发。tool_calls delta 算内容，agent 回合不会被误判。
- 3 条判据 + 3 个变异（恒 false / 恒 true / reasoning 算内容）全部被捕获。

同时修三个 WebUI 布局缺陷（都靠截图而非 DOM 断言发现）：
- 插件侧栏项只渲染图标没有标题：btn.innerHTML 只塞 pluginIconHTML(pg.icon)，
  与原生页的「图标 + <span>标题</span>」不一致，侧栏是一排无名图标。
- 计费维度表 8 列挤在 465px 卡片里：table-layout:fixed 把每列压到 62px，
  23/80 个单元格溢出、数字互相重叠。改为 6 列（token 细分合并为
  「输入(新鲜+缓存)」，细分进 title）+ table-layout:auto，实测 0/60 溢出。
- 数字列 word-break:break-all 让每个字符独占一行（USD 0.56 竖排成 U/S/D），
  改 nowrap + 容器横向滚动。
 2026-10-02 15:10:01 +08:00
JianFeeeee
d9652f479a fix(plugins): 插件 Lua 报错不再拖垮网关（生产事故修复） 
## 事故

13:37 部署后线上 6 次 SIGSEGV 崩溃循环，8081 完全不可用，用户报大量
connect error。崩溃点固定在 internal/lua/plugins.go:invoke → L.Call →
golua StackTrace 里的 lua_getinfo。

## 根因（不是并发/GC/锁）

golua 的 callEx 在**任何** pcall 失败后无条件执行 L.StackTrace()，而
StackTrace 调 lua_getinfo，这个 LuaJIT 构建在栈够深时（带 AUTO 链轨迹的
request_end payload 正好够深）直接段错误。这是 C 层信号，Go 无法 recover，
所以一个插件的脚本错误就能带走整个进程和所有在途请求。

触发错误来自我上一轮加的 billing 日级维度：

    add(bucket(bucket(bucket(s.by_day_src, dk), payload.source)), ...)

三个 bucket( 只对应两个 )，最外层 bucket() 只收到一个参数，k=nil，于是
billing.lua:141 `tbl[k] = b` 抛 "table index is nil"，**每个请求都抛**。

同时还有第二个 bug：中间层用了 bucket()（返回 emptyBucket，含 cost/requests
字段）当作嵌套容器，结构也是错的。改为 dayMap() 返回纯表。

## 修法

1. billing.lua：修正括号，多层容器改用 dayMap()。
2. **pcall 守卫**（真正的架构修复）：在 setupGlobals 里注册
   __llmsproxy_call_hook，钩子改为经它调用。

       function __llmsproxy_call_hook(fn, payload)
         local ok, res = pcall(fn, payload)
         if not ok then return nil, tostring(res) end
         return res, nil
       end

   Lua 侧 pcall 在 golua 看到非零 pcall 状态之前就拦下错误，C 栈回溯路径
   永远进不去。错误变成普通返回值 (nil, msg)，Go 侧记进 hook_errors 并跳过
   ——"插件出错不影响请求转发"这条承诺对脚本错误也终于成立，而不只是对 Go panic。

## 这同时修掉了那个查了很久的间歇崩溃

同一个机制解释了此前 8/20 复现、却查不出根因的 SIGSEGV（怀疑过 janitor 竞态、
GC、LuaJIT 全局状态、VM 释放时序，全部排除）。实测对比：

  TestBillingPrecedence   修复前 8/20 崩溃 → 修复后 0/20
  并发建 16 个 VM 的探针   修复前 3/3  崩溃 → 修复后 0/6
  全量 ./...              连跑 5 次全绿

那些崩溃本来就是一个 Lua 钩子错误在栈深时炸掉 StackTrace，时机随机所以看着
像并发问题。

## 判据

TestHookThatRaisesDoesNotCrashTheProcess：装一个每请求必崩的插件，连打 50 次，
断言进程存活 + 错误被记录 + 同状态里健康的 billing 插件照常工作。
3 个变异（守卫不 pcall / 守卫名写错 / 守卫未注册）全部被捕获，其中第一个直接
让 SIGSEGV 重现，说明守卫就是唯一防线。

## 线上验证

往生产插件目录放一个每请求必然报错的插件，连打 30 个真实流式请求：

  30× HTTP 200，SIGSEGV 0 次
  hook_errors 记录 count=44 且指名 zbroken-test（可观测）
  billing 照常累计（2999 请求 / $0.5668）

测试插件已移除。

回滚点：/usr/local/bin/llmsproxy.bak-real-<TS>、billing.lua.bak-real-<TS>。
 2026-10-02 14:07:44 +08:00
JianFeeeee
fbdf0dea10 fix(billing): 缓存命中统计缺失 + Billing 页空白 + 侧栏图标 
三个问题都来自生产实测，不是代码审阅。

## 1. 缓存命中被计费却不被统计
网关确实从上游 usage 提取了 prompt_cache_hit_tokens（审计里能看到
cache_hit_tokens: 270104 / cache_reported: true，占 prompt 的 99.9%），
costFor() 也用它给缓存段定价了 —— 但**没有任何 bucket 记录它**。
结果：一个 99.88% 命中率的网关，报表显示 prompt_tokens 却看不出其中
多少是缓存读，也无从按源/模型/key 看命中率。

每个 bucket 现在多三个字段：
  cache_hit_tokens    命中数（按上游上报）
  cache_fresh_tokens  未命中的 prompt
  cache_reported_reqs 上游确实上报了缓存数的请求数

第三个字段是刻意的：**「零命中」与「上游根本不上报」在命中总量里完全一样**，
而它们在「缓存折扣有没有生效」这个问题上含义相反。没有它就无法区分，
只能猜。

chat.go 的 payload 之前**没有** cache_reported（审计有、插件没有），
所以任何插件侧的缓存统计都只能猜 —— 已补上。

旧 state 文件的 bucket 没有这些字段：Lua 里 nil + number 会抛错，而钩子抛错
会让**该请求完全不记账**（一个统计缺口会变成静默缺口）。add() 里做了回填。

UI 增加 fresh/cache/cache% 三列 + Cache hit rate KPI；未上报的显示 n/r 而不是 0%。

## 2. Billing 页空白：render() 引用了未定义的 s
`render(st)` 里两处 KPI 写成 `s.degraded_reqs`，ReferenceError 让整个渲染
中断，所有表格停在初始的空 innerHTML。症状是「页面加载了但什么都没有」，
而 /api/plugins/billing/state 返回 200 且有真实数据 —— 载荷完全正确，
DOM 是空的。

更糟的是 refresh() 里的 `catch (e) { /* never break the page */ }` 把错误
**静默吞掉**了：网络面板一切正常，页面什么都没有。现在 catch 会
console.error（仍然不抛，装饰性组件不该拖垮宿主页，但必须留痕）。

## 3. 侧栏图标
billing 声明 icon = "💰"，而原生 tab 全是内联 SVG（stroke: currentColor）。
emoji 尺寸不对、不跟随主题。

WebUI 增加 pluginIconHTML：插件图标可以是文本，也可以是内联 SVG。
**SVG 走严格白名单**（tag + 属性都是 allowlist，不是 denylist）——
插件是在运维者浏览器里跑的第三方代码，不能"信任插件"；但也不能直接拒绝
SVG，因为那是唯一能和原生 tab 视觉一致的方式。

用真实 Chromium 验证 12 个用例，全部挡住，包括 foreignObject 里嵌 HTML
命名空间 <img onerror> 这个经典绕过（整体丢弃，所以 img/onerror 也没了）。
★ node 里没有 DOMParser/jsdom，所以没法在单测里跑这个过滤器 —— 用正则近似
会得到一个"测试通过但浏览器里失效"的过滤器，这比没有测试更糟。

顺带修了过滤器的两个真缺陷：输出里嵌套了空 `<svg></svg>`，且 viewBox
是从包装元素读的（永远是 null）而不是插件自己的，所以任何自定义 viewBox
的图标都会丢失。

## 判据（新增 7 项，全部变异验证）
写「注入脚本能否正常执行」这个守卫时我错了四次：
  1. 静态扫「已声明的名字」→ 把 HTML 字符串里的 CSS 类名（class/div/td）
     全报成未定义
  2. 用 CSS 选择器解析器查样式表 → 报样式表本身坏了
  3. 只挂 process 的 uncaughtException → 脚本在 IIFE 里异步跑，错误是
     unhandledRejection，判据对原 bug 全绿
  4. 只查「有没有抛错」→ render() 开头是 `if (!st) return`，传错字段是
     **静默 no-op**：不抛、不打日志、不报错，只是页面空白
最终判据是：在 node 里用 DOM stub 真跑一遍，同时要求「无异常」且
「至少写进一个容器」，并监听 console.error。变异验证：还原 s → 红；
render 收到 undefined 字段 → 红。

表头/行列数一致性也有守卫：row() 加了缓存列而表头没加时，表格会整体错位
（cache% 落到 completion 列下）—— 渲染正常、有数据、但要仔细看才发现。

## 生产验证
重启后价目表与累计账完整保留（1.17 亿 prompt tokens）。
新请求缓存统计生效：cache_hit 947,436 / cache_fresh 888，
cache_reported_reqs 7 / 395（其余来自旧 state，正是该字段存在的意义）。
真实浏览器：表格 3 行、KPI 7 项、表头 name/cost/reqs/prompt/fresh/cache/cache%/completion、
SVG 图标 currentColor 渲染、控制台无 billing 错误。391 个测试全绿。

## 另发现一个无关 bug（未修）
首页 stats 图表抛 IndexSizeError: arc 半径为负（-2），在 ui/index.html 的
paintStats 附近。属状态页图表，不在本次范围。
 2026-10-02 11:16:15 +08:00
JianFeeeee
a78f7cb6c5 feat(plugin): 启用/禁用 + 磁盘列表 + 峰谷定价 + 随核心发布 
## 插件管理后端
- PUT /api/plugins/{name} {"enabled":bool}   启用/禁用
- GET /api/plugins/{name}                    读源码（编辑器用，与 /state 区分）
- GET /api/plugins 的 on_disk 字段            列出目录里所有 .lua 及其加载态
- validPluginName 提取为共享函数，install/remove/read 三处共用，防止检查漂移

禁用是**运行态开关，不删文件**：插件把线上网关搞坏了、但离修好只差一行时，
运维需要把它移出请求路径而不丢失它（同 systemd mask 而非 remove 的道理）。
它**不跨重启保留**——一个悄悄比操作者意图活得更久的"禁用"本身就是个意外。

Builtin 的判定是「加载的源码与内嵌版本逐字节相同」，而不是「名字匹配」：
被改过的 billing.lua 不能被标成 builtin，否则 UI 会提供覆盖用户改动的操作。

on_disk 列表包含**加载失败**的插件。否则一个语法错误的插件在 UI 上直接消失，
运维看到的现象是"插件不见了"而不是"插件报错了"。

## 峰谷 / 时段定价
commandcode 的 DeepSeek V4 系列就是高峰 01-04 & 06-10 UTC 工作日 2 倍价
（非高峰 17h/天）。静态价目表达不了，而算错方向是**静默**的。

价目条目可带 peak = {multiplier, windows=[{days, hours}]}。命中任一窗口即乘。
★ 用 `os.date("!%H")` 取 **UTC** 小时：provider 费率表按 UTC 标注，而网关跑在
本地时区（本机 Asia/Hong_Kong）。混用本地小时会让峰谷整体偏移 8 小时，
白天算成夜间——比不做峰谷还糟。

## ★ 实现与注释不一致，被判据抓住
applyPeak 最初直接 `price.prompt = price.prompt * m`，注释写「缓存读不翻倍」。
但 costFor 里**缓存读价是从 price.prompt 派生的**，所以原地翻倍会把缓存读
也翻倍——两个折扣被叠在一起，而 provider 从没打算叠。
改成 applyPeak 只**记录**乘数，由 costFor 分段应用：fresh prompt 与 completion
翻倍，cache read 那一项不动。
只靠注释说明意图是不够的：TestBillingPeakDoesNotDoubleCacheRead 立刻红了
（0.006 vs 期望 0.003）。变异回原实现仍是红的。

## 判据（21 个计费测试全绿，新增 5 个峰谷）
  窗口恒命中 ×2 / 窗口永不命中保持静态价 / 星期不匹配不命中
  （这条正是防"用本地时区整体偏移 8 小时"）/ 无 peak 规则向后兼容
  / 缓存读不随峰谷翻倍

后端部分：构建/vet/gofmt 干净，8 个包全绿。
 2026-10-02 08:33:41 +08:00
JianFeeeee
cb6df0a3f0 fix(billing): 缓存命中按全价计 + 未定价流量静默记 0 
部署前审计计费插件时自己找到的两个真缺陷，都会直接算错钱。

## ★ 缺陷 1：缓存命中按全价计（高估约 10 倍）
costFor 只看 prompt_tokens，不区分其中多少是缓存命中。实测（审计脚本，非推演）：
1M prompt token 里 900k 是 cache_hit → **算出 10 USD**，而缓存读通常只要 1/10
价，正确值 ~1.9。agent 流量反复重放长前缀，正是缓存要让它便宜的那类流量，所以
这个偏差恰好落在最高频的流量上。

改为拆分：
    fresh  = prompt_tokens - cache_hit_tokens  → 全价
    cached = cache_hit_tokens                  → 全价 × cache_discount
cache_discount 默认 0.1（DeepSeek/Qwen/Kimi 的量级），可按条目覆盖——**折扣率是
每个 provider 的事实、不是自然常数**，所以 0.1 只是默认值而不是硬编码常量。
另外把 cache_hit 钳到 prompt 以内：适配器报出比 prompt 还大的缓存命中数时，
fresh 会变负数，凭空产生负计费 token。

## ★ 缺陷 2：未定价模型静默记 0（最危险）
没有任何价目覆盖的请求，成本记 0，而 **requests 和 token 数照常计入 total**。
于是账单看起来完全正常，只是 quietly 少报——没有任何报错，没有任何异常。
比多算危险得多：多算你会去查，少算你不会知道。

新增两个维度把这件事变成显式信号：
    unpriced_reqs    未定价请求数
    unpriced_models  按模型点名，直接告诉你价目表缺哪一行
仪表盘加一张 "Unpriced" 卡片，**这个数应该是 0**。
任何维度（source / model / key）覆盖了就算 priced。

## 修这两个时自己踩的坑
第一版把未定价统计块写在了 `local s = plugin.state` **之前十行**，
在一个全新插件上 hook 直接抛 "attempt to index global 's'"，于是
**整条请求什么都没记**——计费插件能有的最坏失败方式。
是 TestBillingZeroPricesIsSafe 的 "requests = 0" 抓到的。
代价：一个计费插件静默失效，而网关日志里只有一行 hook error。

## 判据（351 个测试全绿，计费相关 16 个）
新增 5 个，全部是**具体金额**断言：
  TestBillingCacheHitsAreDiscounted          1M/900k 命中 → 1.9
  TestBillingCacheDiscountIsPerModel         覆盖为 0 / 1 两种极端
  TestBillingCacheHitClampedToPrompt         荒谬的命中数不产生负费用
  TestBillingCountsUnpricedTraffic           只数未定价的那个，且流量仍计入 total
  TestBillingAnyDimensionCountsAsPriced      源维度定价也算 priced
 2026-10-02 01:14:33 +08:00
JianFeeeee
42764bc99e feat(plugin): AUTO 调度轨迹可见（chain_step stage） 
被问"还有 auto 调度相关 stage 呢？"问出来的真实缺口。

## 问题
chainDrive 只返回 (resp, src, model, err)，调用方只知道**最终哪个槽位赢了**。
遍历过程中算出来又丢掉的东西——哪些档被跳过、为什么跳过、哪些槽位硬失败、
哪档全忙——一律不可见。ChainErr 里其实有这些，但**只在全部失败时**才填，
而它是 error 返回值不是记录。于是：

    "tier 1 冷却所以降级到 tier 3"  ==  "tier 1 正常接单"

对插件而言 tier 只是个常量 -2（"resolved by the chain"），信息量为零。而这
恰恰是优先级链存在的全部理由，也是"我那个贵模型为什么没被用"的答案。

## 做法（scheduler 侧零新依赖）
新增 TraceEvent / TraceSink，chainDrive 多一个可选 sink 参数：

  - TraceEvent 是本包的普通 struct，sink 是 func 参数 ⇒ **不新增 import**，
    scheduler 仍然可独立测试
  - sink 为 nil 时每次 emit 只多一次 nil 判断；没有插件的网关在 AUTO 热路径上
    零开销（gateway 的 chainTraceSink 直接返回 nil）
  - 事件是纯观测：scheduler 不基于它做任何分支，gateway 也不把它喂回路由/
    冷却/配额

四种 kind：tier_skip / slot_fail / tier_busy / selected，selected 每次成功
遍历恰好一次且是最后一步。顺序保证所有 step 在 routed 之前。

## 暴露给插件
新增 chain_step stage（逐个步骤），并在 request_end 载荷里加三个便于做报表的
字段：chain_walk（上限 12 步，防审计记录膨胀）、degraded、tier_served。

## ★ 计费口径（我按推荐的做，已写进文档，需要你确认）
**按实际服务的模型计费**：降级到 tier 3 仍按 tier 3 的价算，轨迹只作观测。
理由与 §7.5 的边界一致——插件只报表不执法，两套口径混在一起会引出"降级该不该
多收钱"这种无法从代码判断的争议。若要改成"按本该用的档计价"，需要在 models
价目里允许按 tier 定价，这我没做，因为那是个产品决策。

## 计费插件同步消费
by_tier_served / skip_reasons / degraded_reqs 三个新维度。skip_reasons 的等待
时长做了归一（`no free slot within <wait>`），否则 busy-wait 文案一变就多一行。
降级次数在 request_end 里计而不是在 chain_step 里计：一次降级的请求要走多步，
按步计会重复计数。

## 判据（346 个测试全绿，新增 15 个）
  scheduler  6 个：正常路径只发一个 selected / 跳档+降级可见 / 硬失败与跳档
                严格区分（不可混为一谈，否则抖动上游看起来像空闲上游）/
                nil sink 安全 / 全失败时轨迹与 ChainErr 并存且不互相破坏 /
                空链不发事件
  gateway    1 个端到端：tier 1 全 500 → 插件收到 slot_fail(tier 1) +
                selected(tier 2)，request_end 的 tier_served=2 且 degraded=true
  lua        2 个：降级计数与按实际模型计价 / 跳过原因归一聚合
  lua        1 个：chain_step 是真 stage 且顺序正确

3 个变异都红：去掉 slot_fail（3 个判据红）/ 去掉 tier_skip（1 个）/
去掉 degraded 字段（1 个）。
 2026-10-02 01:03:39 +08:00
JianFeeeee
a51a6811a6 feat(plugin): Lua 插件机制 + 计费插件 + 插件文档 
插件 = plugin_dir 下的单个 .lua 文件，做两件事：挂请求流水线的钩子、在启动时
贡献 WebUI 界面（整页或往现有页面追加组件）。两者独立。

## 流水线 stage（三个）
  request_start  已解析鉴权、未选源
  routed         已选定 (source, model)、未发往上游
  request_end    每请求恰好一次，带最终计量
request_end 挂在 gateway.writeRec——四条入口路径（直连/AUTO × 流式/非流式）的
唯一汇合点：既不漏（流式 token 只有流结束才知道）也不重。

## 计费插件（plugins/billing.lua，默认 seed，开箱可用）
源 / 模型 / 密钥三个维度定价。token 价优先级 keys > models > default；per_request
固定价是**叠加**的（生图模型可以既算 token 又收固定费）。单位是 USD/单 token，
即各家 provider 的公布口径。累计 total / by_source / by_model / by_key / by_day。
失败请求保留 token 费用、丢弃固定费（可经 count_failures 翻转）。
界面 = 一个独立页 + 状态页顶部一块总开销 tile。

## 一个明确的设计边界
计费插件**只报表，不执法**。网关自己的配额会计（stats.go，入口强制）才是限额
权威，插件不参与任何路由/配额决策。两套独立会计若对不上，比一套功能略少的
更糟。

## ★ 中途改掉的一个根本设计错误
最初让插件复用适配器的**弹性 worker 池**（多状态）。这对适配器是对的（它们无
状态），对插件是错的：计费插件往 plugin.state 累加，多状态意味着总量被劈成
几份；而 SetState 写价格只写进其中一个 worker，钩子恰好跑到另一个时**所有请求
按 0 计费**。改为**单状态 + 互斥锁**。代价写进文档：钩子必须短、同步、不阻塞，
卡住的钩子会卡住所有插件的钩子。
这个 bug 是测试逼出来的——先写了 SetState+Fire 的用例，数字全是 0 才挖出来。

另一个连带缺陷：只带 prices 的 PUT 会整体替换 state，把累计量清零。改为
prices/state 分离——prices 是配置、state 是历史，改价不动账。

## 撞到的三个 Lua 绑定的坑（都写进注释）
  - SetGlobal **会 pop 栈**：连着调两次，第二次从空栈取，赋成 nil
  - GetField 索引越界是 **SIGABRT 整个进程**，不是 panic，recover 救不了
  - Call(nargs, n) **不接受函数索引**，它调的是 nargs 个参数正下方那个；
    传索引会调到参数上（"attempt to call a table value"）
另外 GetField/SetField 用绝对索引，SetTop(0) 之后必须重取。

## 错误隔离
钩子 error() 不影响转发：捕获 → 记进 hook_errors → 跳下一个插件。适配器出错
会让源进冷却，插件出错**零惩罚**——插件是可选功能。/api/plugins 的 hook_errors
让"坏掉的插件"可见而不是静默消失。

## 界面注入
GET /api/ui-inject 一次返回所有插件的扩展（侧栏需要全部 page 才能建好）。
WebUI 在首次 render **之前** await 注入：先插 HTML 再重建 <script> 让它执行
（innerHTML/template 插入的 script 不会执行，这正是要的效果——避免脚本跑在
自己 DOM 之前）。注入失败不影响仪表盘。
browser 侧 pluginAPI 暴露 fetchState / postState / onTabShown。

## 文档
docs/plugins.md —— 快速上手、加载与热更新、三个 stage 的完整字段表、界面扩展、
状态与 HTTP API、运行时约束（单状态/异常隔离/内置函数）、计费插件的定价与
计费策略、排错表、与适配器的对比表。

## 判据（328 个测试全绿，插件相关 33 个）
  - 计费断言的是**具体金额**（0.00625 / 0.0402 / 0.0075…），不是"能加载"
  - 4 个变异都红：钩子异常不隔离 / prices 清空累计 / 忽略 key 优先级 /
    毫秒时间戳不换算
  - UI 侧 6 个判据把注入顺序、script 执行时机、pluginAPI 名称、tab 路由、
    anchor 四种形式、失败非致命全钉住
  - 鉴权：state 读任意角色、写仅 admin
 2026-10-02 00:37:29 +08:00