c241a19b51
feat(stats): 用量按日/周/月/全部统计（审计文件聚合）
...
统计页原来只有一个视图——进程启动以来的累计。早上没人和一整周没人看起来
一模一样。加日/周/月/总四个周期。
## 口径与实现
周期视图必须走审计文件，不能走内存聚合：内存 byModel/byKey 等是终身累计，
而 recs 环形缓冲只有 500 条（defaultRingSize）。读环会把任何超过几百个
请求的周期悄悄少算——这正是要消除的那类错数。
- 日/周/月 = UTC 日历窗口（今日 / ISO 周周一 00:00 / 本月 1 日）。
刻意不用滚动 24h：滚动窗口会让"今天"和"最近一天"边界不同，同一个数字
随查看时刻在两张卡片间跳。UTC 也和 billing 的峰段计算同口径，峰谷小时
不会在费用视图和用量视图里落到不同一天。
- 全部 = 复用现有 Snapshot（内存聚合），无审计文件时依然可用。
- 时间桶：日→每小时（今天内部的尖峰要看得见），周/月→每天（否则一周是
7×24 个点、一个月 31×24）。全部视图无时间线（终身总量没有有意义的
时间轴，硬画 500 个滚动小时点是另一种撒谎）。
- key 过滤在所有维度生效；非法 period 返回 400 而不是静默回落"全部"——
书签里的手误应当报错，而不是悄悄换成终身数字。
## 判据（10 条 + 8 个变异全部被捕获）
窗口边界（含"周日必须回到上一个周一"这个 Go Weekday() 陷阱）、旧记录不
计入、维度独立聚合且 by_model 求和等于 total、日桶按小时且有序、key 隔离、
全部视图走终身、空窗口标记 truncated、period 校验、query 解析。
变异验证时 by_status 假绿了一次：禁用状态码聚合后判据全过，查下去是我
**根本没测 by_status**（零覆盖）。补 TestPeriodStatusDimension 后该变异
立即被捕获。判据报假问题时，先怀疑判据——这次确实是我错了。
## 真实流量核对
生产审计文件手算 vs 后端（含轮转文件）：
day 手算 3559 / 后端 3532
week 手算 43240 / 后端 35034
month 手算 13696 / 后端 13670
差异是核对快照与请求之间的新流量，量级一致。
一个必须说明的发现：审计文件里混着两种记录 —— Req（type/model/
prompt_tokens）和访问日志（lat_ms/status/path）。46026 行里 33450 行是
访问日志，Go 侧按 r.Type=="" 跳过。这不是 bug（CSV 导出同样如此），但
意味着任何按行数手算都必须过滤，否则会差一个数量级。
CDP 实测四周期切换：reqs 3,571 / 35,075 / 13,710 / 196,712，与后端一致，
无控制台错误，localStorage 持久化生效。
2026-10-02 12:26:26 +08:00
d1da40e493
fix(billing): 页面文字溢出卡片 + 数字千分位
...
用户报 billing 页"文字超出展示框"。真因是三处叠加，都不是文案问题：
1. KPI 卡是 CSS grid，grid item 默认 min-width:auto。2e8 级的 prompt
tokens（实测 270,149,209）无法收缩，于是把 grid 轨道撑出容器 → 整页横向
溢出。修法是 min-width:0 + overflow:hidden（不给 min-width:0 的话，
grid 子项永远不肯收缩，这是 grid 最常见的溢出坑）。
2. 表格写死 min-width:560px，窄视口下必然溢出。改 width:100% +
table-layout:fixed，列宽由布局分配而不是由内容撑开。
3. 长名称（deepseek-v4.1-flash 这类模型 id）撑宽单元格。名称列改 ellipsis +
title 悬停看全名；数字列 word-break:break-all 在列宽内换行。
顺手：所有 token/请求数走 toLocaleString 千分位。原始 9 位数字读起来要数
零位数，分组后 270,149,209 一眼可读，也顺带缩短了字符串宽度。
CDP 实测（820px 窄视口，逼出溢出条件）：
main/body 横向溢出 = no
table=338 < card=366（修复前 min-width:560 必然 > 366）
KPI 输入 tokens = 270,149,209
billing 页无控制台错误
残留（不影响布局）：表头 TH 在固定布局下 48>42 轻微超出自身格，因为
word-break 不拆单个长词；表格整体仍在容器内，未产生页面滚动。
全量测试全绿（8 包）。
2026-10-02 12:16:40 +08:00
aa10ee8c27
fix(billing): 插件页不可达（真·空白根因）+ i18n + 溢出 + 状态页 tile
...
## ★ 用户报告「Billing 页还是空白」—— 上一轮的验证有漏洞
上一轮我用 goTab('billing') 直接调用验证，显示"有数据、无错误"就下了结论。
但用户是**点侧栏按钮**。真实点击路径走 goTab，而 goTab 只遍历硬编码的 TABS
常量来切换 `hidden` 类 —— 插件页不在 TABS 里，所以 #tab-billing 的 hidden
**永远不会被移除**。内容一直躺在 DOM 里（KPI/表格都填好了），只是不可见。
这个 bug 没有任何报错：注入正确、数据正确、API 200，唯一的问题是宿主页的
路由逻辑没把插件页纳入。而它是上一轮「TABS 收敛为单一常量」时留下的：
收敛让三处共用一个常量，却没让插件页进入它。
修法：goTab 同时遍历 PLUGIN_PAGES。PLUGIN_PAGES 从 const 改为 var 并**提前到
goTab 之前声明** —— const 在文件后部声明的话，goTab 的读取落在 TDZ 里，
第一次点击插件页就会抛 ReferenceError（同类问题这个文件里已是第二次）。
判据 TestPluginPagesAreReachableByGoTab 锁两件事：goTab 遍历插件页集合 +
声明在使用之前。变异验证：删掉遍历 → 红；var 改回 const → 红。
## 插件 UI 不跟随多语言
宿主的 applyI18n/data-i 只覆盖**宿主渲染的标记**；插件注入的 HTML 对它不可见，
所以整个 UI 切中文时 Billing 页还是英文。
pluginAPI 增加 lang（getter，实时值）与 onLangChange（切换回调）。
billing 页所有文案改走双语字典：KPI、表头（fresh/cache/cache%）、区块标题
（占位后由脚本填）、空态、状态页 tile 标签。切换时立即重渲染标题，
不用等下一次 fetch。
## 部分页面超出 UI 区域
#main 只有 overflow-y，插件页内容（8 列表格 min-width、长字符串）会横向撑破。
两层修：插件 pane 统一 min-width:0/max-width:100%/overflow-x:auto（第三方
任意 HTML 的兜底，与原生 pane 一致）；billing 的宽表格在自身容器内滚动。
## 状态页 tile 的 TypeError（每次重绘都报）
tile 的 tick() 在 await 之后直接 getElementById(...).textContent = ...，
但状态页每次刷新都整体重建 pane，元素可能已不存在 → null 属性赋值。
await 之后重新取元素并判空。
## 顺手补的缺口
上一轮加了缓存表格列，但 KPI 卡片漏了（那次替换 assert 失败后重试只重做了
表格）—— 缓存命中率在表格里有、KPI 里没有。本次补上。
## 验证
真实浏览器（禁缓存、真实点击侧栏按钮）：pane 可见、KPI 9 项、表头双语、
语言双向切换正确（Per source ⇄ 按源）、无水平溢出、无 billing 控制台错误。
生产数据：Total USD 0.566798 / 732 请求 / 降级 231 / 2.09 亿 prompt tokens。
387+ 测试全绿。
## DSL（进行中，未完）
config.BillingDSL（active + profiles + rules，rule 按 url 匹配 mode=free/
token/subscription/unpriced）与 internal/billing.Compile（url 规则 → 插件
prices 表，含峰谷窗口的形状编译 —— 之前手写 JSON 两次弄错的正是这个形状）
已落地并通过校验/编译；core 启动接线已写。profile 切换 API 与 WebUI 选择器
未做，生产 config.yaml 也尚未写 billing 段 —— 下一轮继续。
2026-10-02 11:47:24 +08:00
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
30064696b3
perf(plugin): 去掉钩子热路径的 JSON 往返 + 同 stage 跨插件并行
...
## 1. 去掉 JSON 往返（快路径）
实测单次 Fire 14.6µs，其中 json.Marshal 4.0 + json.Unmarshal 5.6 = 9.6µs，
**67% 花在把 map[string]interface{} 序列化再反序列化**，而紧接着的
pushGoValue 本来就能直接遍历这两种类型。改为按类型直接转换（fastvalue.go），
只对不认识���类型才回落 JSON —— 陌生字段仍然会被送到插件，而不是消失。
快路径与 JSON 路径逐字节等价由 TestFastPathMatchesJSONPath 锁住（8 组载荷，
覆盖 int/uint/float 各宽度、嵌套、slice、map[string]string、未知类型）。
还有一条专门防止「优化悄悄失效」：TestFastPathIsActuallyUsed 用真实的
request_end 载荷断言它确实走快路径。
同一份代码 A/B 实测：JSON 往返 56.4µs → 快路径 35.3µs（省 37%）。
## 2. 同 stage 跨插件并行
参照 /home/program/TrueAgent 的 StageHost.RunStage：
- **快照后释放锁**再并行 —— 它记录过一次自死锁（p.Stop → onExit → ReclaimOwner
要拿 registry 锁，持锁并行即死锁）。这里同理：钩子可能经 admin API 增删插件，
那条路径要拿 ps.mu 写锁，所以并行段内不持任何 ps 锁。
- 每个 goroutine recover。
- 单插件走直连路径，不付 goroutine 代价（生产就是这种配置）。
**与 TrueAgent 不同的一点**：它可以放心并行，因为 handler 只写 ctx.Response 并有
IsResponded() 仲裁；我们的钩子返回 table 会合并进 payload，而
docs/plugins.md 明确承诺「payload 原样传给下一个插件」。所以合并**按插件加载
顺序**执行，结果确定，不依赖调度；代价是钩子之间不再互相可见 —— 这是一处
**契约变化**，已在文档里写明，并说明随核心发布的 billing 从不返回任何值
（代码注释就写着 "nobody downstream would read a return value"）。
实测收益（真实二进制，三实例对照，3000 请求）：
无插件 1 插件 4 插件
稳态并发32 849 rps 768 (-9.5%) 741 (-12.7%)
突发并发64 1524-1893 1182-1676 1064-1443
4 插件只降 10-20%，而并行前实测 4 插件是 63.8µs vs 单插件 14.6µs（-300%）。
## ★ 我自己造成的两次性能事故
**① 持久化把热路径拖慢 26 倍。** 最初的快照在钩子路径上做：走 luaValueToGo +
json.Marshal + json.Unmarshal 三重转换，每请求 264µs，Fire 从 14.6µs 变成 385µs。
改成 saver 按自己节奏拉取（钩子只标记 dirty，flush 时才快照），385µs → 25.7µs。
**这里还踩了第二次 use-after-free**：让后台 goroutine 去读 Lua 表，vm.Stop() 后
那是已释放内存（SIGSEGV）。安全性现在由「Plugins.Close 等 saver 的最后一次
flush 完成后，调用方才停 VM」保证。
**② 基准被自己的后台写入污染。** 关掉 markDirty 反而测出 36µs、比开着还慢，
方向完全反了 —— 是 saver 每 2 秒写盘混进了计时。加了 DisableStatePersistence
后数据才可信。
## 判据（11 项，全部变异验证）
快路径等价/确实生效/不别名输入 + 并行与单插件路径合并一致 + 合并顺序确定 +
抛异常的钩子不拖累同伴 + 每插件恰好执行一次 + 并发 Fire 安全 + Fire 期间不持
注册表锁 + 真实 billing 在并行下正常 + 持久化 7 项。
变异：改坏合并顺序 → 红；去掉单插件路径的合并 → 红（3 个既有测试同时抓到）。
★ 「删掉 recover」这个变异**没有**让判据变红，查下去发现 golua 把 error()、
nil 索引、调用 nil、深递归全部转成 error RETURN，不产生 Go panic —— 那个测试
根本没测到 recover。已改名 TestThrowingHook 并在注释里写明 recover() 当前无法
被 Lua 触达，保留它是为了守 Go 侧。留一个「看起来有覆盖」的断言比没有更糟。
## 端到端（真实二进制 + 真实 billing）
20 万请求全 200，rps 1870，p99 96ms，RSS 37.9→42MB 有界；
负载停止后四个插件计数**完全一致**（231745），hook_errors 为空；
systemctl restart 后 billing 仍是 231745 —— 并行与持久化同时生效。
381 个测试全绿，含 -race。
2026-10-02 10:45:20 +08:00
ce2032435a
fix(plugin): 插件 state 持久化 —— 重启不再丢账
...
## 问题（压测实测）
插件 state 活在 Lua VM 里，进程一死就没了。实测线上量级：
重启前 {"requests":218241,"prompt_tokens":26188920,...}
重启后 {"requests":0,"prompt_tokens":0,...}
对计费插件来说这不是舍入误差，是功能本身没生效 —— 它存在的意义就是那个
不断累加的数字，而一次 systemctl restart 就能把它抹掉。
## 设计
- prices（配置）与 state（累计历史）**分开存**在同一个文件里但不同字段。
SetState 在内存里已经这么分，磁盘必须同意：合并会让改价看起来像清零，
或让恢复历史时顺带复活过期价格。
- 原子写（临时文件 + rename）：写一半崩掉时上一份仍可读，而不是留下一个
解析失败的半截 JSON —— 那等于这次也丢。
- 损坏文件只警告不阻断启动。转发不能依赖插件的账本活着。
- 防抖后台刷：钩子路径只标记，真正的写在一个 goroutine 里合并进行。
计费插件每请求都改 state，同步写会把一次 JSON 编码 + 文件写放到热路径上
（实测钩子本身已经 14.6µs，写会盖过它）。
- Core.Close 必须先刷插件再停 VM：flush 要读 Lua 表，vm.Stop() 之后读的是
已释放的内存。
## ★ 实现中踩的四个坑（都由测试或崩溃直接暴露，不是推测）
1. **后台 goroutine 碰 Lua = use-after-free**。最初让 flush 线程去读 Lua 状态，
vm.Stop() 后那是已释放内存 —— 表现为 golua 里的 SIGSEGV，不是干净报错。
改成：钩子路径（VM 必然存活、已持 p.mu）取快照，后台只写文件。
2. **自死锁**：markDirtyLocked 被 invoke 调用，而 invoke 全程持 p.mu，
再 Lock 一次就是死锁。lua 包测试直接挂到超时。
3. **luaToJSON 独占整个栈**（每条路径结尾都 SetTop(0)）。连续调两次读两个
字段时第二次访问的是不存在的槽位 —— 这个绑定不 panic，直接 SIGABRT。
改为每次重建栈。中间还因为提前 return 没 Pop 而让栈逐次错位。
4. **快照顺序**：先快照后读返回值，会把钩子的返回值清掉，于是每个"有意见"的
插件静默变成"没意见"，而文档承诺的"返回 table 合并进 payload"就废了，
且没有任何报错。
## 判据（7 项，全部变异验证过）
重启后总计保留 / prices 与 state 分离 / 纯 prices 更新也持久化 /
钩子返回值不被快照吃掉 / 损坏文件降级不阻断 / 500 次变更合并成个位数次写 /
Close 刷出尾部。
变异结果：
关掉 mark → TestStateSurvivesRestart + TestPricesAndStateAreSeparate 红
Close 不等 flush → TestCloseFlushesTail 红
prices-only 不写盘 → TestPricesOnlyUpdatePersists 红
还原快照顺序 → TestHookReturnValueSurvivesSnapshot 红
★ 第一次跑「关掉 mark」时判据没报错，原因是我的变异脚本写出未使用变量导致
编译失败 —— go test 根本没跑测试，我却读成了"通过"。换成 _, _ = 后如期变红。
## 端到端
隔离实例发 12 次请求 → systemctl restart → requests 仍为 12，token 数不变。
371 个测试全绿。
2026-10-02 10:17:07 +08:00
8de1499c40
fix(ui): 插件元素注入被宿主页面重建擦除 —— 元素型注入从未真正生效
...
## 现象
部署示例后打开 WebUI：侧栏有 Billing 页，但**状态页上没有任何计费组件**。
插件明明声明了 elements，/api/ui-inject 也确实返回了 mount（1570 字节）。
## 根因（不是缺功能）
七个宿主页面的渲染函数都用 `pane.innerHTML = ...` **整体替换**自己的 DOM。
`renderStatus` 在 `injectPluginUI()` 之后由 refresh() 立刻调用，于是刚挂上的
plugin-el 连同整个 pane 一起被下一次赋值销毁。
时序上它**从没有过"显示一帧"的机会**：注入 → refresh("status") → innerHTML 覆盖。
所以症状是"元素从来没出现过"，而不是"刷新后消失"——这正是我先前据
/api/ui-inject 返回值判定"注入正常"而漏掉的地方：**载荷到达 ≠ DOM 存活**。
Billing 页不受影响，因为它属于 PLUGIN_PAGES，走插件自有 DOM，不经宿主重建。
于是看起来像"页面注入有效、元素注入无效"，把排查引向插件声明本身。
## 修法
- mountPluginElements 改成具名可重入函数，并注册进 PLUGIN_MOUNT_HOOKS
- refresh() 在**唯一出口**统一调 remountPluginElements()，而不是给七个渲染函数
各加一次调用——后者是多一处会忘的地方，而忘记的后果是静默的
- 每个挂载点按 data-idx 幂等：宿主重绘时若该 pane 已有该元素就直接返回，
否则插件的 <script> 会每次重绘都跑一遍，计数器静默翻倍
## ★ 验证方式换了：真实浏览器，而不是 payload
静态测试和 curl 都看不出这个 bug（载荷完全正确）。用 CDP 连本机共享浏览器实测：
修复后：首屏 tile=1，页面重建后=1，连续重建 5 次仍=1，console 无错误
回退后：tile 全程=0
对照二进制（把 done 改成空函数重编译）实测首屏就是 0，
**证明"从未显示过"，不是"显示后消失"**。
## 判据与变异
TestPluginElementsSurviveHostRebuild 锁住：remountPluginElements 存在、
PLUGIN_MOUNT_HOOKS 在使用之前声明（const TDZ 会让首屏直接抛错）、refresh 挂了重挂、
挂载按 data-idx 幂等。
三个变异全部被抓住：撤掉 refresh 的重挂 / 去掉幂等守卫 / 把 const 声明移到 push 之后。
★ 第一次跑第三个变异时**判据正确地没报**，因为我的替换脚本命中了注释里的同名文本，
真正的 const 没被移动——是变异无效，不是判据有洞。换按行定位后如期变红。
## 同时补上部署示例
packaging/config.example.yaml 里补 plugin_dir 说明（之前只有 online 部署路径踩过）。
实测升级路径本身是好的：给已有配置加 plugin_dir 后，首次启动会自动 seed 内置
billing 插件，无需手工放置文件。
2026-10-02 09:04:47 +08:00
1c690611f8
feat(gui): WebUI 与 Electron 壳的插件安装/删除/禁用/编辑
...
## WebUI：新增「插件」页
- 列表来自 on_disk（不是 loaded 集合）——**加载失败的插件也必须显示并带错误**，
否则一个语法错误看起来和"插件没装"完全一样
- 启用/禁用（PUT {"enabled":bool}）、删除、编辑源码、安装/覆盖
- 显示 hook_errors：插件抛异常在别处毫无痕迹，没有这一栏的症状就是
"功能就是不work"
- 插到 dropzone 与代码编辑器都做了泛型化（bindDropzone / openCodeModal），
适配器与插件共用一份，而不是复制第二份只改 4 个 id 的函数
## TABS 收敛为单一常量
tab 清单原本是字面量散在三处：goTab、refresh()、admin-only 隐藏列表。
加一个 tab 意味着三处都要记得改，漏一处就是"路由认得但界面不显示"——
和今天早些时候 chain_step 漏报同一类静默缺口。现在只有 const TABS。
## Electron 壳：设置面板里的插件管理
渲染进程不能直连内嵌核心（没有 key、不知道端口），所以走 IPC：
renderer → plugins:proxy → main → HTTP /api/plugins
代理是 (method, path, body) 透传而不是固定命令表：固定表每加一个端点就要扩，
而"按钮存在但什么都不做"比"没有这个按钮"更糟。透传让渲染层能调用核心将来
新增的任何 /api/plugins 路由，路径在主进程校验。
## ★ GUI 此前零测试，而本次改动就引入了三类"看起来没事"的问题
1. 引用了不存在的 CSS 类（.tag / .sm）——渲染成无样式文本
2. 引用了不存在的 helper（esc / escAttr）——那是 WebUI 的，renderer/app.js
是独立文档，点击时 ReferenceError
3. .ghost/.primary 只在 .form .actions 作用域内生效，插件按钮在 .pl-acts 里
于是是无样式裸按钮
补 4 个静态判据（不启动 Electron，守卫的正是"打开应用才看得见"那一类）：
TestGUICSSClassesExist 用到的类必须在样式表里定义
TestGUIHelperFunctionsAreDefined 被调用的函数必须有定义
TestGUIPluginPanelIsReachable 面板在 overlay 内、按钮已绑定、打开设置会加载
TestGUIIPCPathIsConstrained 代理必须限定 /api/plugins 前缀并拒绝路径穿越
写第一个判据时我错了三次：CSS 解析器先丢最后一个 selector、再把变量块当
selector、最后漏掉复合选择器（.tb-btn.tb-close）。两次"判据自己坏了"的
教训和本项目一贯一致——**判据出错的信号是它报了一个假问题**。现在改用宽松的
token 提取 + 显式的 guiKnownUnstyled 豁免表（blob/tgl/rail 是既有无样式类，
不是本次引入，失败它们只会让判据对新工作失去意义）。
## 变异验证
改坏唯一的 CSS 定义（.pl-empty）→ TestGUICSSClassesExist 红
改坏 helper 名 → TestGUIHelperFunctionsAreDefined 红
★ 第一次变异我改了 .pl-broken，判据**正确地没报**——因为它还被另一条规则定义。
这是变异选错目标，不是判据有洞；换 .pl-empty 后如期变红。
363 个测试全绿。
2026-10-02 08:47:08 +08:00
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
d0c7465130
fix(plugin): /api/ui-inject 的 stages 漏掉 chain_step + 忽略临时构建目录
...
部署到线上时用隔离实例（独立端口 18099 + 独立 config/runtime/adapter 目录）
发真实请求验证，抓到的第三个 bug。
## bug：discovery 文档漏掉新 stage
handlePluginUI 的响应里 stages 是**字面写死的三个**。加 chain_step 时只改了
lua.AllStages，没改这里，于是插件作者读 GET /api/ui-inject 会看到
["request_start","routed","request_end"]，**合理地得出结论：没有 chain_step 这个
stage**。stage 本身是注册好的、也确实在触发，只是没被声明。
改成从 lua.AllStages 派生——AllStages 是唯一定义顺序的地方，让它保持唯一。
★ 而我原来的测试断言 `len(view.Stages) != 3`，**断言本身是 bug 的保护伞**：
它把"三个"固化成了期望值，于是新增第四个 stage 时测试全绿、bug 上线。
现在断言改为「与 AllStages 等长且逐项相同」，并显式要求 chain_step 在其中。
新增 stage 而忘了声明，这类问题会立刻红。
## 顺带：.gitignore 补上临时构建目录
.probe/ 和 .build-work/ 是我调试时当 GOTMPDIR 和临时二进制用的，之前每轮
手工删，这轮差点提交进去 9.5MB 的二进制。
## 部署验证留档
隔离实例跑真实 chat（158 prompt / 13 completion / 128 cache_hit），计费插件
算出 0.000688，与手算 (158-128)*1e-5 + 128*1e-5*0.1 + 13*2e-5 **逐位吻合**。
★ 第一次手算我按全价算成 0.00184，一度以为插件算错了——查审计记录才看到
cache_hit_tokens。**算钱不对时先查输入再怀疑实现**，而我忘的恰是刚修的折扣。
## 验证
351 个测试全绿；变异（stages 改回硬编码三个）被 TestUIInjectServesPluginUI
抓住，3 条断言同时红。
2026-10-02 06:24:34 +08:00
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
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
8c18e0c3d7
fix(plugin): request_start 在直连与生图路径上根本没触发
...
被"你确定功能全部正常了？你全部测试了？"问出来的。之前所有插件测试都是直接调
Plugins.Fire()，只证明 Lua 运行时没问题，**完全没验证网关有没有真的触发**——
把 handleChat 里的三处调用删掉，整个套件照样全绿，而线上一个钩子都不会跑。
补上走真实 HTTP 的端到端判据后，立刻抓到两个真 bug：
## bug 1：直连路径完全跳过 request_start
fireStart 只写在 handleChat 的 AUTO 分支里，任何指定了具体模型的请求（也就是
绝大多数请求）都不触发。修法是挪到 isAuto 判断之前，两条路径共用一次调用。
顺带修正位置语义：它在配额/模型范围闸门**之前**触发，所以插件能统计到被网关
拒绝的请求；否则插件永远只能报"被服务的请求数"，算不出真实请求率。
## bug 2：生图路径三个 stage 全断
handleImage 是第三个入口，有自己的 handler 和自己的调度调用。"聊天能用"对它
毫无证明力。而生图是计费流量，计费插件看不到就等于少报。
已补 fireImageStart + 两处 fireRouted（direct -1 / AUTO -2）。
它写独立函数而不是复用 fireStart 传空 chatRequest：image 请求没有 messages
和 tools，传一个为聊天设计的零值结构会诱导后来者去读不存在的字段。
## 端到端判据（6 个，全部走真实 handler）
TestHooksFireOnRealDirectChat 直连：三个 stage 顺序 + 真实 source/model/tokens
TestHooksFireOnRealStreamChat 流式是另一条路径（记录由 defer 在流结束后写）
TestHooksFireOnAutoRequest AUTO 链：start 报 "AUTO"、routed 报**解析后**的模型
TestHooksFireOnFailedRequest 失败请求：routed 不触发（没选到源）、
request_end **必须**触发（否则计费看不到失败流量）
TestHooksFireOnRealImageRequest 生图：type=image，第三个入口
TestRejectedChatStillFiresRequestStart 404 拒绝也要触发 start（顺序决定的钉子）
TestBrokenPluginDoesNotBreakForwarding 插件每 stage 都抛异常时聊天仍返回 200
## 变异验证
把 fireStart 挪回 AUTO 分支（= 重现我犯的错）→ 4 个判据红：DirectChat /
StreamChat / FailedRequest / RejectedChat。恢复后 336 个测试全绿。
这两个 bug 都属于"读代码看不出来"的类型：fireStart 那一行就在 handleChat 里，
看着挺像那么回事，只有真的发一个请求才知道它没被调到。
2026-10-02 00:49:32 +08:00
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
a2e1adc2d8
fix(gemini): endpoint 自相矛盾导致预置模板必失败
...
gemini.lua 里 adapter.endpoint = "/v1/models"，而它自己的注释写的是
POST /v1/models/{model}:generateContent
两者矛盾，而 Go 侧是静态拼接（provider.URL = base_url + endpoint），拼不出
模型名。预置模板 "Google Gemini"（base_url=.../v1beta）于是会 POST 到
https://generativelanguage.googleapis.com/v1beta/v1/models
既多一段 /v1，又缺 :generateContent——那是 Gemini 的模型**列表**端点，
对 POST 返 405。所以任何用户从模板建这个源，拿到的都是必定失败的源。
实测确认影响范围：线上 21 个源里没有 gemini（openai×15 / trae / sensenova /
opencodezen / deepseek / anthropic / agentrouter），所以是潜伏缺陷。
修法：endpoint 改成模板 `/v1beta/models/{model}:generateContent`，新增
provider.ChatURL(model, stream)：
- 用 **PathEscape** 替换 {model}——模型 id 进的是 URL 路径，不转义的话
一个 "/" 就会静默指向另一个资源（判据里用 RequestURI 而非 URL.Path
断言，因为后者是解码后的，看不出 %2F）；
- 流式把 ":generateContent" 换成 ":streamGenerateContent"（同一个路径、
不同动词，也在路径里）。替换刻意只认这个精确后缀，免得别的适配器
仅仅提到这个词就被改写；
- source 自己设的 endpoint: 仍然优先，模板被整体跳过。
Chat / ChatStream / probeChat 三处调用点改为传本次请求真实的 model——AUTO
按槽位把 req.Model 钉死，所以 URL 必须跟随**请求**的模型，用源默认模型会让
多模型源每次都打同一个（还记到别的模型的账上）。
判定静态 endpoint 的其他 10 个适配器零影响（TestNonGeminiEndpointsAreUntouched）。
顺带：Stats 的 mutex 不是可重入的，导出方法自己加锁、*Locked 后缀要求调用
方持锁。持锁调导出方法会死锁——我的探针真卡死过一次（直到 10 分钟超时）。
补上 LOCKING 注释，并加判据把这条规则钉住（含一个 20 秒上限的行为判据，
让未来的重构撞死锁时快速失败而不是拖满整个套件）。
2026-10-01 23:37:17 +08:00
7082ffb723
fix(packaging): 去掉重复的加固块，并同步线上单元的确切内容
...
上一版把线上单元拷进来后又追加了一份英文注释的加固指令，导致
NoNewPrivileges / ProtectSystem / SystemCallFilter 等在同一个 unit 里
出现两次。systemd 对重复指令取最后一个，行为上不会坏，但文件本身是错的
（读的人会以为有两套加固），且 packaged 与 deployed 不再一致。
现在 packaged/llmsproxy.service 与线上 /etc/systemd/system/llmsproxy.service
逐字节相同，每条指令只出现一次。
2026-10-01 20:59:34 +08:00
5e723b5aa5
feat(packaging): systemd unit 加固（逐条实测，非照抄模板）
...
原单元只有内存调优两行环境变量，加固项一个都没有，且以 root 运行。补上
一组经验证的加固指令。
关键决定：**仍然以 root 运行**。本服务要读 master.key（0600 root）。实测加
User=llmsproxy 直接起不来，且失败方式隐蔽——
[config] secrets disabled: open /etc/llmsproxy/master.key: permission denied
只是一行日志，服务会带着「敏感值以明文落盘」继续跑。也就是说在当前文件
权限下降权不是加固而是把密钥降级。要降权得先把 key 交给服务用户、统一
/etc/llmsproxy 属主，那是独立的、需要回滚预案的变更，不混进来。
每条指令都在一个独立探针单元（临时端口 + 独立 runtime_file/adapter_dir，
拷了真实适配器）上验证过：
- 鉴权 401/200 正常；
- 一次真实 /v1/chat/completions 走通（证明 SystemCallFilter=@system-service
没打断 LuaJIT 适配器的 JIT 代码路径——这是最容易被 seccomp 搞坏的地方）；
- 审计文件可写可轮转（ReadWritePaths=/etc/llmsproxy 够用）；
- 连续重启 3 次都 active + http 200，kill -9 行为符合预期。
systemd 对非法指令值不报错只「忽略」，所以逐条实测是唯一可靠做法。
读路径全在 /etc/llmsproxy；运行时写入经核对只有 config.yaml / runtime.json /
*.audit.jsonl / adapters/*.lua / master.key，全在该目录下，故 ProtectSystem=strict
+ ReadWritePaths=/etc/llmsproxy 即可。CapabilityBoundingSet 置空（本服务不需要
任何 capability，留空比写允许清单更难出错）。
已部署到线上 /etc/systemd/system/llmsproxy.service（原单元已备份为 .bak-*），
restart 后服务 active、监听 8081、WebUI 可达、审计继续写入；本仓库的
packaging/llmsproxy.service 与线上一致（去掉了部署机特有的 RSS 实测数字）。
2026-10-01 20:58:23 +08:00
e10bfbb278
fix(deploy): 适配器备份只保留最近 5 份，不再无限堆积
...
sync_adapters 每次部署都新建一个 adapters.bak.<时间戳> 目录，而回滚只用到
最近一次（$BACKUP_BIN / $BACKUP_CONFIG 都是单文件覆盖）。多出来的目录从没人
清理——线上实测已积累 71 个，把 /etc/llmsproxy 顶到 122M。
prune_adapter_backups：
- 按时间保留最近 KEEP_ADAPTER_BACKUPS=5 份（sort 升序，删前面较旧的）；
- 另给目录数一个硬上限（5×4），防一次误配置在几秒内造出成百上千个目录；
- 只删名字严格匹配 adapters.bak.<14位时间戳> 的目录，手工放的
adapters.bak.MANUAL 之类一律跳过不删（宁可留着也不误伤）。
本地用真实形状的名字（14 位 YYYYMMDDHHMMSS）跑了 5 个用例验证：
12 份→留最新 5 且手工目录/无关目录不动、恰好 5 份→全留、40 份→走硬上限、
0 份→不报错、只有手工目录→原样保留。
线上已手动按同一规则清到 5 份（122M→114M；剩下的大头是 runtime.json 的
审计 .old，由 auditKeepOld=16 自行限额，不在本次范围）。
2026-10-01 20:52:23 +08:00
ad54616bee
docs: 对齐分支命名实际用法 + 修正示例配置的存储位置说明
...
三处都是"文档说的"与"仓库实际做的"不一致，读文档的人会被误导。
1. 分支命名：文档写 release/vX.Y.Z 且举例 release/v1.4.2，实际从
release/v1.4.x 起一律用字面 x（release/v1.5.x / v1.7.x）。改成实际情况，
并说明"一条 minor 分支跨多个 patch"是刻意的：patch 是同批功能的修订，
hotfix 落同一条分支，回流 main 时不必处理多条 release 分支间的依赖。
2. 退役规则与实践不符：文档说"下个版本发布就删上一个 release 分支"，但
release/v1.4.x / v1.5.x 至今仍在。保留无害（hotfix 已回流），但与规则
矛盾。两份文档都如实记下这个出入，并记录特性分支**确实**在清理——本次
删除的四个分支都逐提交用 git patch-id 核对过，工作已全部进入 main
（唯一 patch-id 不同的是 bf0657b
2026-10-01 20:41:57 +08:00
18e422a943
fix(sources): 源编辑不再清零 proxy_url / api_key_env / timeout
...
bf0657b
2026-10-01 20:36:48 +08:00
980f4a0e40
fix(gui): 缓存解封结果，否则每个请求都要 spawn 一个进程
...
The auth rule calls readAdminKey() on every outbound request so injection
never depends on ordering. Once the sealed-config path shells out to the
core, that turns each request into a process spawn: 200 simulated requests
took 1012ms and launched 200 cores.
Cache the unsealed key against config.yaml's mtime. Editing the config still
invalidates it, which is what the auth rule actually needs -- the port
rewrite, the first write, and a user edit all change mtime. Measured: 200
requests now cost 10ms and one spawn.
Only a successful unseal is cached. Caching a failure would pin an empty key
until the config next changes, turning a momentary spawn error into a locked
out user.
2026-10-01 19:23:32 +08:00
429afce67e
fix(gui): 桌面版被自己的密钥封存挡住登录
...
The desktop build authenticates the embedded core by reading the admin key
out of config.yaml with a regex and injecting it as a gw_key cookie. The core
seals credentials at rest (enc:v1:...), so from the second start onward that
regex yields ciphertext, the cookie is worthless, and the app asks the user for
a key they never set. The key is generated and hidden by the app itself.
Reproduced end to end: first start writes a plaintext profile, the core seals
it, every later start reads back "enc:v1:..." and falls through to the login
prompt.
- when the stored value is sealed, ask the core to unseal it via
-show-secrets, which only reads, prints and exits. Reimplementing the core's
AEAD in JS would be a second source of truth for its key format.
- cwd must be the profile dir. The core locates master.key relative to the
config's runtime_file, so a call made from anywhere else has it generate a
second master key in the CWD and then fail to decrypt ("master key changed?").
Electron's CWD is not the profile dir, so without this the desktop build
cannot read its own key even after unsealing is wired up.
- the loose regex is kept as a fallback so a future change to the -show-secrets
output degrades to a login prompt rather than to a wrong credential.
Verified: plaintext start -> core seals -> restart recovers the same key, with
the core running the whole time. Dropping cwd:PROFILE_DIR makes the unseal fail
and leaves a stray master.key in the CWD, so the cwd argument is load-bearing
rather than tidiness.
2026-10-01 19:19:40 +08:00
5639bb662c
chore(version): 1.7.5 -> 1.7.6
...
PUT /api/sources/{name} 未实现却见于文档（返回 405），以及 POST upsert
会用占位符/空值覆盖真实 api_key —— 写入返回 200，源却在之后一直 401。
2026-10-01 18:29:11 +08:00
bf0657bb84
fix(sources): implement PUT and stop partial edits from clobbering api_key
...
Two defects on the admin source write path, both found while adding a model
to a live source by hand.
PUT /api/sources/{name} was advertised in the API index but never
implemented — handleSourcesAPI only switched on GET/POST/DELETE, so the
documented update verb answered 405 while the POST upsert behind it worked.
POST is an upsert that replaces the whole source, so a partial edit that did
not carry api_key persisted an empty or placeholder credential. The source
kept its name, base_url and models, the write returned 200, and the source
then answered 401 on the next request — long after the writing script exited
0. The WebUI had been routing around this by loading the real key through
?reveal=credentials; any script or partial update went straight into it.
- implement PUT, taking the name from the path and rejecting a body name
that disagrees rather than silently resolving to one of them
- inherit the stored credential when api_key is omitted or sent as the
literal "__KEEP__"; an explicit new key still rotates
- an empty api_key on a source that does not exist yet stays empty, since
credential-less local upstreams are legitimate
- add model_ids, an additive shorthand, so "add these models" never has to
read and echo the existing list back
- align the API index with the implementation
The model_ids merge had a first cut that dropped the existing list when the
request carried no models field; TestSourceModelIDsIsAdditive caught it.
Verified by mutation: removing PUT turns three tests red, flattening
resolveAPIKey into a pass-through turns TestSourceUpsertKeepsAPIKey red
on both subtests, and making model_ids replace instead of merge turns
TestSourceModelIDsIsAdditive red.
2026-10-01 18:15:29 +08:00
504c5ac9a0
chore(version): 1.7.4 -> 1.7.5
...
启动密钥警告误报的修复。
2026-09-28 23:42:48 +08:00
70f1c879bd
fix(startup): 密钥警告改读真实生效的 key 集合
...
启动时那条「gateway_keys is EMPTY — without a key every request is rejected」
读的是 legacy 的 cfg.GatewayKeys 段，而鉴权实际用 cfg.Keys（core.ListKeys）。
seedKeys 首次启动把 gateway_keys 搬进 keys[] 之后，YAML 里那个列表就不再
被鉴权使用。于是在它被清空（例如轮换掉 starter key 之后）而 keys[] 仍有
7 把可用 key（含 admin）时，进程每次启动都谎报「所有请求都会被拒绝」。
实测：生产日志出现该警告，而同一个 key 请求 /v1/models 返回 200。
- main.go 改为检查 c.ListKeys()，文案改成不绑定字段名。
- 顺带删掉 gateway.New 的 gatewayKeys 参数：函数体从未使用它，
只读 ListKeys()，留着会继续诱导人以为鉴权来自那个列表。
判据：e2e/TestStartupWarningReflectsRealKeysNotLegacyList —— 构造
「gateway_keys 空 + keys[] 有 key」的真实形态，先断言该 key 确实能鉴权，
再断言日志里不再出现那句谎报。变异验证：回退成 GatewayKeys() 即变红。
2026-09-28 23:42:48 +08:00
04e544c823
chore(version): 1.7.3 -> 1.7.4
...
发行包不再内置可用 admin key 的修复，走 patch 发布。
2026-09-28 23:27:54 +08:00
7e33d11d15
fix(packaging): 发行包不再内置可用的 admin key
...
打包时把本地 config.yaml（gitignored，含运维真实密钥）原样复制成
config.example.yaml，而 postinst 在首次安装且 /etc 无配置时又把它
cp 成生产配置 ⇒ 每次安装都得到一个同值的、公开已知的 admin key。
实测该 key（sk-gw-local-0001）在生产上真实有效（/v1/models 返回 200，
而网关监听 0.0.0.0）。
三处修正：
- 新增 packaging/config.example.yaml（受 git 跟踪的净化模板），
gateway_keys 留空、sources 留空，并写明不要填死值。
- core-dist.sh / nfpm.yaml 改为打包该模板，不再碰本地 config.yaml。
- postinst.sh 不再投递示例配置：留空文件会让网关启动但拒绝所有请求
（无门可入）。改为让二进制首启时自行生成随机 admin key 并打印 ——
每次安装都不同，且开箱可用。示例文件仅作为 /usr/share 下的参考保留。
实测首启：生成 sk-gw-838d66a1... 并打印，与旧的共享固定值不同。
2026-09-28 23:27:42 +08:00
cd82835f25
chore(version): 1.7.2 -> 1.7.3
...
启动重复播种 admin key 与配置封存非幂等的修复，走 patch 发布。
2026-09-28 22:53:19 +08:00
26ea782350
fix(core): 修复启动重复播种 admin key + 配置封存非幂等
...
根因是 unseal 时序：NewFromConfig 把解密放在最后，而之前几步已经在读凭据。
1. seedKeys 重复播种（生产已累积 4 个同名 admin key）
seedKeys 用 cfg.Keys[i].Key 与明文 gateway_keys 比对去重，但此时内存里的
key 还是密文 enc:v1:…，比对永不命中 ⇒ 每次重启追加一个同值 admin key。
实测：core.New(path) 连续重启，seeded key 数 2→3→4 递增。
（旧测试用 NewFromConfig 构造全新内存对象，没有「盘上已有密文」这个前提，
复现不出 —— 必须走 core.New 这条读盘的生产路径。）
2. 启动恒重写 config.yaml
migratePlaintextSecrets 按内存状态判断，而 Save() 末尾会把内存恢复为明文，
于是每次调用都判定「还有明文」并重写；注释却自称幂等。
改为 UnsealSecrets 在解密前记录「盘上是否明文」，SealIfNeeded 据此决定
是否写回 ⇒ 已封存的配置启动不再落盘。
原测试 TestMigratePlaintextSecretsIsIdempotent 用 ModTime 比较，两次写落在同一
时间戳刻度内就看不出来，所以表现为 ~1/6 概率的 flake 而非稳定失败。已改为比较
文件内容并走真实启动路径（UnsealSecrets + SealIfNeeded），并顺带消除该 flake。
附带更正：先前判断「rebuildRegistry 也会拿到密文 API key」不成立 ——
mergedSources → resolveSourceKey 对每个 source 独立解密（belt-and-braces），
provider 始终拿到明文。unseal 前置仍予保留，以消除对该兜底路径的隐性依赖、
并让 seedKeys 在明文下比较。
判据：
- TestRestartDoesNotDuplicateSeededKeys（敏感：回退顺序必红）
- TestSealingIsIdempotentAcrossStarts（12/12 稳定，原先 1/6 flake）
- TestProvidersGetPlaintextCredentials（钉 provider 必须拿到明文这一不变量）
2026-09-28 22:52:51 +08:00
5c58244781
chore(version): 1.7.1 -> 1.7.2
...
token 统计单位修复（流式改用上游真实 usage、图片不再记 token），
影响 per-model 配额计费口径，走 patch 发布。
2026-09-28 22:19:24 +08:00
0121d23f91
fix(tokens): 流式统计改用上游真实 usage，图片不再记 token
...
两处 token 单位错误，均影响 per-model 配额计费：
1. 流式路径的 prompt/completion 只是「字节÷3」估算。
pumpStream 明明收到了上游最后一帧的真实 usage，却只发给客户端、
从不回写审计记录，于是配额按估算值扣。生产实测同一请求：
上游 prompt=37/completion=179 → 记账 27/262，prompt 低估 1.4x、
completion 高估 1.5x（双向失真）。同模型流式 completion 中位数
是非流式的 4-27 倍。非流式路径本就用真实值，两路不一致。
修法：lastUsage 非零时写回 rec.Prompt/rec.Compl，估算降为兜底
（上游不报 usage 时仍保留原估算行为）。
2. 图片请求把「图片张数」记成 completion_tokens。
rec.Compl = int64(len(resp.ImageData))，len 是切片长度即张数
（生产 38 条 image 记录全是 1），且被计入 token 总量。
图片生成无 token 概念 ⇒ 新增 Req.ImageCount 独立字段，
Prompt/Compl 归 0；UI 记录表 image 行改显示张数（新增 i18n thImgs）。
顺带补 TestUILocaleKeyParity：此前无人校验 zh/en 键集合一致，
单边加键不会报错，只会显示原始键名。
新增 token_units_test.go（定值上游 6 项），做过变异验证：
回退修复实测复现 stream=16/173 vs chat=44/100、image completion=3。
2026-09-28 22:19:12 +08:00
de7c372ad2
chore(version): 1.7.0 -> 1.7.1
...
v1.7.0 的配额语义（整钥总额）与最终设计不符，本 patch 版把配额改为
按模型独立计费。已在生产部署过的 v1.7.0 保留不动，语义修正走 patch。
2026-09-27 19:07:48 +08:00
c51066f0b6
refactor(quota): 配额改为按模型，删除整钥总配额
...
用户明确要求：配额应当是密钥对应的**每个模型的单独配额**，而非整体配额。
## 语义变更
删除 GWKey.TokenQuota / ReqQuota / Period / Hours（整钥总额）。
ModelScope 新增 ReqQuota —— 请求数配额下沉到每条模型范围。
现在：每条 models[] 各自带 token 配额 + 请求数配额 + 重置周期，
彼此独立。一个模型用满只影响该模型。
★ 为什么不保留整钥总额：它会让「把 A 模型的额度挪给 B」变成一次全局
重分配；按模型独立计费则每个模型各自可控，运维能直接看出哪个模型在吃预算。
## 连带改动
- checkQuota 合并 key 级与 scope 级判定；checkKeyQuotaRetry 整体删除
（顺带修掉上轮遗留的双重判定：入口不再先判空再重算）
- core：CreateKeyWithQuota / UpdateKeyWithQuota / ApplyQuota 全部删除，
改由 ValidateScopeQuotas 校验每条 scope 的配额
- admin key：scope 上的配额不强制（admin 的 scope 仍限制模型范围，
但不强制配额）—— 否则管理员会把自己锁在门外
- /api/v1/keys 不再回显 key 级配额字段（scope 里已含）
- WebUI：删除整钥配额徽标 / 「配额」按钮 / 创建表单的配额组 /
putScope 的整钥回传；模型砖块与范围编辑器新增「请求数配额」输入，
徽标显示 `1.0K 77×·1h`（未设配额显示 ∞）
## 判据
- TestOneModelsQuotaDoesNotBlockAnother 是本次核心保证。
★ 它第一版是**假判据**：m2 从不消耗，key-wide 计数器与 m1 自己的计数器
读数恰好相同，退回 key-wide 仍通过。变异测试抓到后改为「先用 m2 花掉
远超 m1 配额的量，再验证 m1 仍可用」—— 这样两种设计才可区分。
- TestUncappedModelNeverBlocked / TestAdminKeyScopesAreNotEnforced 新增
- UI 契约判据重写：整钥配额界面必须彻底消失（13 个符号）、
scope 编辑器必须往返 req_quota、putScope 只发 scope 列表
- 错误消息点名具体模型（TestKeyAPIRejectionNamesTheModel）
- 3/3 变异全被抓
实测（真实进程 + 浏览器）：m2 配额 500000 连打 25 次全成功，
m1 配额 1000 立即 429「token quota exceeded for "m1" (4315/1000)」，
此后 m2/m3 仍 200。UI：整钥配额元素全为 0，砖块各显配额，
编辑器预填/保存正确，零 JS 异常。
2026-09-27 19:02:13 +08:00
5530912d32
chore(version): 1.6.0 -> 1.7.0
...
中版本跃迁：新开 release/v1.7.x 承载 1.7.x 全部 patch。
v1.5.x 已发到 v1.6.0（tag），不再追加。
2026-09-27 18:46:59 +08:00
cc5e725226
docs: 补齐 per-key 配额的运维视角文档
...
代码回流 main 时配额小节已随行，但本轮新增的三项认知此前只存在于
commit message 与判据注释里，运维查不到：
1. **配额拒绝 vs 容量拒绝是两种东西**。配额在入口检查、不占上游槽位，
是廉价拒绝（实测 19–21ms，429 + Retry-After）；容量不足要等满
busyWait 才 503（约 2.6s）。客户端据此可以区分「等窗口重置」与
「等上游腾容量」——前者只需耐心，后者通常该降并发或换源。
附实测对照表（容量 8、0.6s/请求、100 并发）。
2. **配额的开销**。每请求检查 149ns（配了配额）/ 42.6ns（未配配额，
不碰桶）/ 37ns（admin）；窗口查询按窗口长度扫描而非扫全量保留
（1h 49ns、24h 55ns、30d 3.9us）；生产形态内存 3.7MB。
明确写出「未配配额的 key 几乎不付代价」，运维可放心多建 key。
3. **按源 pin 的桶是惰性创建的，以及它的代价**。无条件维护会让
20 密钥 × 8 模型 × 3 源多占 18MB，所以只有真被 pin 查询过才维护；
代价是配置 pinned 配额之前的历史用量无法事后按源拆分，首个窗口
可能少算 —— 这是个会让排障困惑的行为，必须写出来。
同时更新 WebUI 密钥页说明：卡片配额徽标、「配额」编辑按钮、创建表单
可配预算（admin 自动禁用）、「我的密钥」页展示本 key 预算。
README.md / README_EN.md 同步。
2026-09-27 18:46:39 +08:00
652842783f
test(gateway): 补配额桶的真实并发竞态判据
...
per-key 配额桶是共享 map：每个被记录的请求写它，每个配额检查读它。
单线程单测完全看不到这里的竞态，只有让多个 goroutine 同时读写才有效。
key_quota_concurrency_test.go：64 goroutine 跑 2 秒，并发 Record +
KeyWindowTokens + KeyWindowReqs + KeyWindowModelTokens，其中一条路径
在中途 opt in 惰性创建的 pinned 桶（那条路径一次改两个桶 map）。
go test -race 结果：零 DATA RACE，5444 万 token 全部入账。
全仓 -race（./...）亦全绿。
(cherry picked from commit 18cfd6d32b
2026-09-27 18:44:41 +08:00
a21ae84cbe
perf(gateway): 拒绝路径只判定一次 + 补配额交互判据
...
复查后修掉一个自己引入的缺陷，并补上此前缺失的交叉场景验证。
## 修复：拒绝路径重复判定
4 个入口原本先 checkModelScope（判是否为空）再 writeScopeReject
（内部又 checkQuota 一次）。即每个【被拒】的请求要跑两遍配额统计，
且两次之间用量可能变化 —— 判定与响应存在理论竞态。
改为 checkQuota 一次判定直接把 *quotaRejection 交给 writeReject，
消息与 Retry-After 都来自同一次读，不再有二次求值。
checkModelScope 保留（只需知道放行与否的调用方仍可用）。
## 补判据：此前完全没验证过的交叉场景
1. TestKeyQuotaWinsOverSlotQuota —— key 配额与 AUTO 槽位配额是两种
不同作用域的限额（槽位是全网关共享的上游预算，key 配额属于单个
调用方）。两者同时耗尽时必须报【key 配额】：报槽位配额会被表述成
「无可用容量」，读起来像上游故障，而调用方能处理的恰恰是 key 配额。
2. TestUncappedKeyNeverBlockedByEmptyScope —— 只配模型范围、不配配额的
key（生产上 5 把 user key 全是这种）绝不能被槽位检查误伤。
## 复查补测的实测数据
配额检查的真实开销（每请求一次，走完整 checkQuota 路径）：
配了配额 149 ns 0 allocs
未配配额 42.6 ns 0 allocs <- 生产上 5/7 把 key 是这种
admin key 37 ns 0 allocs
未配配额的 key 只付 FindKey 的开销、根本不碰桶。相对一次 LLM 请求
（秒级）可忽略。
生产配置副本（7 key / 16 源 / 真加密凭据 / 真上游）实测：
- 100 并发 -> 50 成功 / 50 容量拒绝，RSS 19.9 -> 25.8 MB
- 生产形态桶内存（7 key x 8 model x 2 源 x 40 天满 retention）
= 3.73 MB，占 ~32MB 预算的 11%
- 配额记账与 stats 一致：配 63000 配额后报 64062/63000
- **跨重启存活**：重启后从审计日志回放，仍报 64062/63000 并拦截；
未配配额的 key 仍 200
(cherry picked from commit 9811654b3e
2026-09-27 18:44:41 +08:00
d072a03c9a
perf(gateway): 配额桶扫描改为窗口化 + pinned 桶惰性创建
...
审查本特性线的性能时发现两个问题，均有实测数据。
## 1. 窗口查询是全扫，代价落在每个请求上
sumBuckets 原来遍历整个 map（最多 960 个小时桶），实测 5.9us/op。
配额检查在每个请求上跑 2-3 次（key 总 token、key 请求数、scope token），
于是单请求多付约 18us。
注意这**不是本改动引入的成本**：main 上既有的 WindowTokens 同样是
5907ns/op（全扫）。是本改动让它在请求路径上被调用得更多。
改为只遍历窗口可能覆盖的桶（键是整点小时，范围是精确的，不是采样）：
- 24h 窗口 200ns -> 55ns
- 1h 窗口 80ns -> 49ns
- 30d 窗口 5.9us -> 3.9us（720 次查找，只有配 month 配额时才走到）
等价性由 TestSumBucketsMatchesFullScan 保证（400 组随机桶位置 x 6 种
窗口，对全扫逐项比对）。★ 第一次写错成 floor，判据立刻抓到：
30 天窗口报 8878 而全扫是 8649 —— 正确是 ceil。
## 2. pinned 桶无条件创建，内存最坏 26.7MB
每条记录写两个桶：裸 model 与 "source::model"。但 pinned 桶只有
「配额里显式 pin 了 source」时才会被查。
实测最坏情况（20 key x 8 model x 3 source x 40 天全 retention）：
HeapAlloc 26.67MB —— 而 README 宣传「16 源生产实例 ~32-35MB」，
等于吃掉 80% 内存预算。
改为惰性：只有 KeyWindowModelTokens 带 source 查询过某个 (key, model)
之后，才开始维护它的 pinned 桶。
20key x 8model x 3src 26.67MB -> 8.87MB (-67%)
5key x 6model（真实） 3.36MB -> 2.26MB (-33%)
5key x 12model 5.82MB -> 3.59MB (-38%)
代价：配 pinned 配额之前发生的用量无法事后按源拆分（记录里虽然有
Source，但桶只存了裸 model），所以 pinned 配额的首个窗口可能少算。
已在代码注释与判据中写明。
## 其余实测
Record main 基线 275ns/429B/3allocs -> 283ns/429B/3allocs
（+8ns，分配数不变；3 allocs 来自 ring buffer）
配额检查全路径 115ns / 0 allocs（每请求新增）
纯读路径 6.5ns / 0 allocs
## 100 并发调度/拒绝压测（真实进程 + 可报并发峰值的假上游）
容量 100（4+96），0.15s/请求，100 并发 ok=100 fail=0 上游峰值 42
容量 100，0.15s/请求，200 并发 ok=200 fail=0 上游峰值 97
容量 8，3s/请求，100 并发 ok=8 fail=92 上游峰值 8
容量 8，0.6s/请求，100 并发 ok=32 fail=68 上游峰值 8
容量 8，0.6s/请求，40 并发 ok=32 fail=8 上游峰值 8
上游峰值恒定不超过 max_concurrent，容量拒绝返回 503 + busyWait 有界
等待（约 2.6s）。main 基线在同条件下 ok=32 fail=68、上游峰值 8、
延迟分布相同 —— 配额改动没有触碰调度/拒绝路径。
配额拒绝单独验证（低并发避开容量拒绝）：req_quota=50 用尽后
100 并发全部 429 rate_limit_exceeded + Retry-After: 1661，
**延迟仅 19-21ms**、上游 total 未增加 —— 配额在入口廉价拒绝，
不占用任何上游槽位，与容量不足的昂贵等待形成明确分工。
## 判据
key_quota_perf_test.go：4 个基准 + 2 个判据（sumBuckets 等价性、
pinned 桶惰性）。3/3 变异全被抓（无条件建 pinned 桶、firstHour 用
floor、keyHour 不再写）。
(cherry picked from commit be11a06a46
2026-09-27 18:44:41 +08:00
f814ff7468
fix(webui): 修 7 处弹窗关闭错对象 + 模板管理器变量遮蔽
...
上一提交只修了自己新加的两处弹窗，全站其余 7 处是同一缺陷：所有对话框
共用 id="modal-wrap"（CSS `#modal-wrap:not(:empty){display:flex}`）且可以叠
加（seed-key 提示就盖在密钥页上），而
`const w = $("#modal-wrap"); w.remove()` 移除的是**文档里第一个**，不是用户
刚提交的那一个。
逐处改为两种安全写法：
- 能拿到按钮的（saveSource / saveTemplate / sortScopeSave / scopeSave /
keyQuotaSave / createKey / downloadStatsCsv / downloadKeysCsv /
scrAddFromForm）：`btn.closest("#modal-wrap")`
- 拿不到按钮的：新增 `closeTopModal()` 取**最后一个**（用户看到的那个），
并作为所有 `if (w) w.remove()` 之后的兜底
- 顺带把 sortScopeSave / downloadStatsCsv / downloadKeysCsv / scrAddFromForm
的签名补上 btn / this 参数 —— 否则 .closest 恒为 null，表单永远不关
同时修一个相邻的既有 bug：`openTemplateModal` 的 `.map((t) => ...)` 用 t 做
循环变量，模板字面量里又调 t("srcEdit")，t 被遮蔽成对象 ⇒ 打开模板管理器
直接抛 `t is not a function`，整个弹窗渲染失败（main 上就有，git show 确认）。
参数改名 tpl。修后模板管理器完整渲染（浏览器实测：DeepSeek / 智谱 / Kimi /
SiliconFlow 各行 + Edit/Delete 按钮文案全部正常，零异常）。
判据从 2 处扩到全量（internal/gateway/ui_quota_contract_test.go，+3 例）：
- 全文档扫描：任何 `.remove()` 配裸 `$("#modal-wrap")` 即失败
- 9 个关闭对话框的处理器必须走 .closest 或 closeTopModal
- closeTopModal 必须取 all.length - 1（首尾颠倒就是原 bug）
- 用 .closest 的处理器，其签名必须真的有 btn 参数 —— 否则查找恒为 null，
表单永远不关
5/5 变异全被抓：sortScopeSave 去 btn 参数、closeTopModal 取第一个、scopeSave
退回裸选择器、saveSource 退回裸选择器、downloadKeysCsv 删兜底。
浏览器实测（共享 Chromium CDP，真实进程，每处都插入一个「decoy」弹窗
占据文档首位，复现原 bug 的触发条件）：
- scopeSave / keyQuotaSave / scrAddFromForm / saveSource / saveTemplate
五个处理器：自己的表单关、decoy 保留 ✓
- 零 JS 异常
★ 测试自身踩了两个坑，都不是代码问题：① `document.querySelector(sel) && .click()`
在 CDP 里求值为 undefined，改成箭头函数；② 编辑模板时没填名字就点保存，
saveTemplate 因 `if (!nm)` 早退、fetch 零调用 —— 一开始我把这个误读成
「修复失效」，加 fetch 拦截 + 读 #s-name 的值才定位到是测试数据缺失。
⇒ 「点按钮没反应」要先分清是「事件没触发」「请求失败」还是「早退」。
(cherry picked from commit b5c3fea0bb
2026-09-27 18:44:41 +08:00
ef631b43dd
feat(webui): 密钥配额表单 + 修复弹窗关闭错对象
...
功能：让 per-key 配额在 WebUI 里可配置可见，之前的实现只有 API 与
config.yaml 能配。
- 密钥卡片头部显示配额徽标（token / 请求数 + 重置窗口），admin key
不显示编辑入口（服务端本就永不受限，给入口只会让人以为配了会生效）。
- 新增「配额」编辑弹窗：token 配额、请求数配额、重置周期（复用既有
的 period 词表与 n-hour 联动），预填从 canvas 的 data-* 读。
- 创建密钥弹窗同步加配额字段；选 admin 角色时自动禁用（同样因为服务端
忽略 admin 的配额）。
- 「我的密钥」页新增 KEY-WIDE QUOTA 列，用户能看到自己这把 key 的预算。
修一个真 bug：保存弹窗用 $("#modal-wrap") 关闭自己，而全站弹窗共用这个
id、且可以叠加（seed key 提示就盖在密钥页上）。实测（共享 Chromium
CDP，seed 提示与配额弹窗共存）确认：保存后被移除的是 seed 提示，配额表单
反而留在屏幕上 —— 症状是「保存了但弹窗没关」，指向的方向完全错。改为用
点击的按钮 btn.closest("#modal-wrap") 解析自己的弹窗。createKey 有同样
问题，一并修。既有文件里另有 7 处同样写法，未动（不在本次范围，且新判据
只对本次改的两处断言，避免误伤）。
判据新增 internal/gateway/ui_quota_contract_test.go（6 例）：
- 两个表单必须用 .closest 解析自己的弹窗
- putScope 必须带上 4 个配额字段（API 视其为指针，省略=清空预算）
- 创建请求必须真的发出配额字段
- **数据流判据**：徽标要真读 k.token_quota 等、编辑表单要真读
canvas 写的 data-kquota 等。只查字面量存在会漏 —— 字段躺在死分支里
判据照样通过（这是本轮实际踩到的：keyCapBadges 经 keyPeriodSuffix
间接读 k.period，被判据抓到后我把读取显式化而不是放宽判据）
- 弹窗扫描先剥注释，否则修复说明里引用的字面量会被当成违规
- 复用既有 ui_contract_test.go 的 jsFunctionBody（大括号配平）；
自己第一版用 2000 字符固定窗口，被长注释顶开后仍在窗口外命中后面
函数的同名字段，读起来像通过 —— 窗口法在这里是假判据
7 个变异全部被抓（unsafe 关闭、putScope 丢字段、createKey 丢字段、
徽标不读字段、canvas 不写 data-*、kq-hours 改名、周期词表缺项）。
浏览器实测（共享 Chromium CDP，真实进程 + 加密配置）：
- 徽标渲染 1.0K·1h / 5×·1h；编辑框预填 1000/5/hour，hours 框按周期联动
- 保存后回读 250000/77/nhour/6，徽标更新为 250.0K·6h，toast Saved
- 零 JS 异常
- **关键回归**：编辑模型 scope 后配额仍是 250000/77/nhour，未被清空
- 创建带配额的 key，服务端确认 {t:50000,r:300,p:week,role:user}
- user 视角「我的密钥」显示 777·1h 与 9×·1h
文档：README.md / README_EN.md 补「密钥用量配额」小节（配置示例、
周期词表、429 语义、admin 豁免、整点分桶最晚晚 1 小时释放、PUT 的
省略 vs 0 语义、429 响应样例），特性列表各加一条。
(cherry picked from commit ce66c7f6c2
2026-09-27 18:44:41 +08:00
9c3aabb7f9
feat(gateway): per-key 用量配额（token + 请求数）与重置周期
...
问题：密钥控制只能限制模型范围。实测发现三个缺陷，其中前两个让
per-model token_quota 在真实链路上从未生效：
1. 桶键不含 key。scopeTokens 调 WindowTokens(model, source, win)，
桶键是 model / source::model，与调用方无关。实测两把 key 各用
1000 token，窗口报 2000 —— A key 的额度被 B key 消耗。
2. 无 source pin 的桶永远是空的。真实记录 Source 总被填上，桶键存成
"deepseek::m1"，而无 pin 的查询找 "m1" —— 读到 0，永远 < quota，
配额形同虚设。实测 WindowTokens("m1","",1h)=0 而 pinned=2000。
3. AUTO scope 走 KeyTokens(key)，是全时段累计、永不重置。实测 30 天
前的 200 token 仍计入 1 小时配额（报 210 而非 10）。配了
period: hour 也不会每小时归零。
生产 5 把 user key 全是 token_quota: 0，所以前两条一直没暴露。
改动：
- Stats 新增 per-key 小时桶 keyModelHour（key → model → hour）与
keyHour（key 总量）、keyReqHour（请求数），retention 40 天，与既有
modelHour 对齐以覆盖最长的 month 窗口；LoadAudit 走 aggregateLocked，
所以窗口用量跨重启存活。modelHour 保持 key-blind：它服务的是 AUTO
槽位配额（限制整个网关对某槽位的消耗），语义不同，不应被 per-key
改造污染。
- 每个请求写两份模型桶：裸 model 与 source::model。无 pin 的 scope
条目读前者，有 pin 的读后者。
- GWKey 新增 TokenQuota / ReqQuota / Period / Hours：整钥配额，
跨该 key 所有模型共享一份预算；ReqQuota 覆盖持续请求量（源上的
RPM 只管突发）。
- 配额耗尽返回 429 + Retry-After（rate_limit_exceeded），而不是 403：
403 让客户端以为这把 key 永远不能用该模型，直接放弃；429 + 等待
才能在窗口重置后自动恢复。模型越权仍是 403。
- admin key 永不受配额限制 —— 否则操作者会把自己锁在门外。
- 周期词表在写入时校验，拼错的 period 被拒绝而不是静默当成永不过期
（那与操作者输入的意图正好相反）。
- PUT /api/keys 的配额字段是指针：省略=保留原值，显式 0=解除限制。
否则只改模型范围就会悄悄清空预算。
判据 3 个文件 24 例，9 个变异全部被抓：key 隔离、pin 桶缺失、
AUTO 周期、key-blind 退化、429→403、admin 被限、PUT 清空配额、
Validate 失效、pinned 桶缺失。前三个变异最初漏网 —— 判据只测了
Stats 层没测接线，补了走真实 HTTP 的接线层与 API 层判据后抓住。
端到端验证：真实进程 + 加密配置往返，配额字段与 enc:v1 密钥均正常。
(cherry picked from commit 5306251840
2026-09-27 18:44:41 +08:00
a7355debed
feat(deploy): 部署前校验 master.key 可解封配置 + llmsproxy -show-secrets
...
密钥校验（deploy.sh）
- 新增 verify_master_key，在 build/替换任何文件之前执行。失败则二进制与
配置分毫未动、服务不受影响（已负向验证：缺钥匙、错钥匙两种情况都挡住）
- 走真实的 -show-secrets 解密路径，而不是只检查钥匙文件格式——格式合法
但内容不匹配（重新生成、恢复了错的备份、换机器）同样会被拒
- 钥匙来源与 config 包一致：LLMS_PROXY_MASTER_KEY 优先，否则
dirname(runtime_file)/master.key
- 配置里没有密文时跳过并提示（首次加密场景）
-show-secrets
- llmsproxy -show-secrets -config <path>：把凭据打到 stdout 后退出
- 不启动任何东西、不写任何文件（已验证 mtime 不变）
- 加密往返无损：封存前后输出逐字节一致
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com >
(cherry picked from commit a8cff57e24
2026-09-27 17:12:03 +08:00
f6baa13583
feat: WebUI 改为依赖 /api/v1，UI 与 agent 共用一套 API 契约
...
- sources / sort / keys 三个页面的数据源从 /api/sources 切到 /api/v1/sources
（写操作仍走 /api/sources：v1 是只读门面，不做变更）
- 编辑弹窗改用 /api/v1/sources/{name}?reveal=credentials（admin-only）取明文 key。
这是必须的：表单要整体回传源，若不回填 key，改个端口就会把 key 清空。
- 遮蔽视图仍是默认，只有显式 reveal 才返回明文
端到端验证（真浏览器 + 临时实例，非仅 API 测试）：
- sources/sort/keys 三页实际发出 GET /api/v1/sources，0 console error
- editSource('demo') → reveal=credentials，#s-key 与 #s-url 正确回填
- 写入往返：改 base_url /v1→/v2 后重开，key 仍在（未被清空）
- 落盘 api_key 明文残留 0、密文 1
测试：+1（reveal 必须 admin，否则任意 user key 可读全部凭据）
变异验证：reveal 去掉 admin 校验 → 403 断言变红
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com >
(cherry picked from commit 926b9f6565
2026-09-27 17:12:03 +08:00
fd03ef6e4a
feat: 密钥静态加密 + /api/v1 agent 管理 API
...
密钥加密（写侧封存 / 读侧解封）
- config.yaml 的 sources[].api_key、sources[].headers、keys[].key 落盘即
AES-256-GCM 密文（enc:v1: 前缀），master.key 复用 runtime store 那把
- 内存里永远是明文：鉴权比对、API 返回新建 key、WebUI 编辑回填都不受影响
- 启动时一次性封存现存明文（幂等，已封存则不写盘）；-check 不写文件
- UpsertSourceInYAML 增加 box 参数，新加的源不再以明文落盘
- 解密失败改为硬错误：原先 MustDecrypt 返回密文会被下次 Save 二次封存
（实测：源 key 18→20、静默损坏），现在启动即失败且配置分毫不动
/api/v1：面向 agent 的管理 API（WebUI 零影响）
- GET /api/v1 机器可读索引，列出每个端点的方法/权限/用途
- GET /api/v1/overview 一次调用看全貌：源 + AUTO 链 + 密钥数 + 健康度
- GET /api/v1/health 仅健康快照
- GET /api/v1/models 按源分组的可路由模型清单
- GET /api/v1/sources[/{name}] 凭据遮蔽后的源
- GET /api/v1/auto 调度链与实时槽位状态
- GET /api/v1/keys admin only，密钥元数据，绝不回显密钥本身
- 沿用同一套网关 key 鉴权；读端点任意角色，写仍需 admin
测试：15 个新用例（含负向：泄密、越权、写操作必须被拒）
变异验证：maskKey 不遮蔽→红、去掉 admin 校验→红
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com >
(cherry picked from commit ad28a924a5
2026-09-27 17:12:03 +08:00
97bb9c6ef4
feat(opencode): 透传 completion_tokens_details.reasoning_tokens 与上游 cost
...
回答「opencodego 的用量与费用透传呢」时逐字段核对上游产出，发现 usage 漏了
一项、费用整项丢失。
## 上游实际发什么（实测 opencode.ai/zen/go/v1）
{
"choices": [...],
"usage": { "prompt_tokens": 37, "completion_tokens": 40, "total_tokens": 77,
"prompt_cache_hit_tokens": 0, "prompt_cache_miss_tokens": 37,
"prompt_tokens_details": {"cached_tokens": 0},
"completion_tokens_details": {"reasoning_tokens": 40} },
"cost": "0"
}
cost 在**顶层**且是**字符串**。流式时还会单独发一帧：
{"choices":[],"cost":"0"}
## 此前丢了两样
1. completion_tokens_details.reasoning_tokens —— 输出里有多少是思考 token。
没有它，客户端无法判断 completion_tokens 里多少是可见回答、多少是思考，
而两者都按输出计费。
2. cost —— 唯一的费用信号，网关整个丢弃。Go 订阅是包月制恒为 "0"，
但 Zen 按量付费模型（以及未来的其它源）有信息量。
顺带修掉一处流式/非流式不一致：命中缓存时上游同时给
prompt_tokens_details.cached_tokens 和独立的 hit/miss，流式路径写成了 elseif，
只留 details，与非流式产出不同（只认独立字段的老客户端会看不到缓存）。
## 实现
- types.TokenUsage += CompletionTokensDetails；UnifiedResponse / UnifiedChunk += Cost
- opencodego/opencodezen 适配器映射两个字段；空 choices 帧改成 usage 与 cost
都可带（早退只带 usage 会把同帧的 cost 丢干净 —— 新测试先抓到的就是这个）
- Gateway ChatCompletion / ChatChunk += cost，随终帧发（对齐上游的
{"choices":[],"cost":"0"} 形态）
- Go 兜底 standardSSEChunk 同步支持（openai 系适配器不再漏 reasoning_tokens；
纯 cost 帧不再被整体丢弃），新增 rawCostString 兼容字符串/数字两种形态
费用只做**搬运**：不解析、不换算、不汇总 —— 它是上游事实，且只有部分上游提供。
## 验证
经网关实测 gozen:deepseek-v4.1-flash，流式与非流式产出逐字段一致：
prompt_tokens_details.cached_tokens=6784
prompt_cache_hit_tokens=6784 / miss=148
completion_tokens_details.reasoning_tokens=16
cost="0"
测试：TestOpenCodeCostAndReasoningPassthrough（含「无数据不得凭空造字段」反例）、
TestOpenCodeStreamCacheFieldsMatchNonStream、TestTokenUsageMarshalsCompletionTokensDetails。
(cherry picked from commit c744ee151e
2026-09-27 17:12:03 +08:00
d81074621a
fix(opencode): 采纳客户端真实会话 id + 超窗消息不再被限流措辞封杀
...
两处都源于同一次排查：pi 到底有没有带会话标识、超窗为什么触发不了压缩。
## 1) 客户端会话 id：pi 一直在发，只是被配置关掉了
之前结论是「通用客户端不发会话 id」——只对了一半。pi 有会话 id，且能发：
pi-ai 的 createClient 在 compat.sendSessionAffinityHeaders 为真时，会把
平台会话 id（uuidv7，整个会话恒定）放到 x-session-affinity /
x-client-request-id / session_id 上。该开关默认 false，而 llmsproxy 的
provider 配置里没开，所以此前一直收不到。
现在网关按优先级采纳：x-session-affinity → x-session-id → session_id →
body 的 prompt_cache_key，并把值经 types.ChatRequest.ClientSession 传到
适配器 meta.client_session。适配器的会号种子优先级变为：
客户端会话 id > 首条 user 消息指纹 > 按源固定。
刻意不采纳 x-client-request-id：名字含 request，部分客户端每请求都换，
拿它当会话会让上游前缀缓存永不命中（pi 总会同时发 x-session-affinity，够用）。
实测：抓 127.0.0.1:8081 的真实 pi 请求，配置打开后收到
x-session-affinity = session_id = x-client-request-id = <子会话 uuid>。
上游缓存确为会话级隔离（同前缀、不同会号：A 冷→命中，B 首次仍为 0），
两个不同 header 值互不命中，反证网关确实采纳了客户端会话 id。
## 2) 超窗消息必须「干净」，否则被同链的限流措辞反向封杀
pi 的 isContextOverflow 先查 NON_OVERFLOW_PATTERNS（/rate limit/、
/too many requests/、Bedrock 前缀），命中就直接判为「非超窗」——**即使
消息里已经有 context_length_exceeded**，pi 也不会压缩重试。
而 AUTO 链的失败消息天生是多 tier 原因的拼接，超窗 tier（gozen 400
maximum context length）常与配额/限流 tier（429 token plan exhausted、
cooling、no free slot）同时出现。此前把 tier 明细原样拼在归一化标记后面，
等于让一条限流 tier 的措辞反过来封杀超窗识别。
现在超窗走独立的干净消息：
context_length_exceeded: context window is full; reduce the length of
the messages (gozen/deepseek-v4.1-flash)
只留超窗措辞 + 超窗源名，不带任何其它 tier 的文本。
测试：TestOverflowMessageSurvivesRateLimitedSiblingTier 用 pi 的完整判定
顺序（先 NON_OVERFLOW 后 OVERFLOW）断言同链限流 tier 不再封杀超窗识别；
TestClientSessionFromRequestHeaders / TestClientRequestIDIsNotUsedAsSession /
TestOpenCodePrefersClientSessionID 覆盖会话采纳与优先级。
(cherry picked from commit c9c09b2ba2
2026-09-27 17:12:03 +08:00
4dd3431c26
feat(opencode): per-conversation session via first-user-message fingerprint
...
Follow-on to the session-stability fix. "Per source" already made the
prefix cache hit, but it puts every conversation into one upstream session.
Using the client's own session id is not possible: capturing real agent
traffic (tcpdump on 127.0.0.1:8081) shows generic OpenAI clients send NO
session identifier at all — no user / session_id / conversation_id /
metadata in the body, and no session header (only X-Stainless-* plus
User-Agent: pi). The x-opencode-session the Go endpoint asks for is an
OpenCode native-client concept that a generic client cannot forward.
Since history is replayed every turn, the FIRST user message is invariant
for the life of a conversation, so it is used as the conversation
fingerprint. The session becomes stable within a conversation and distinct
across conversations; requests with no user message fall back to per-source
stability.
Measured through the gateway (same 5.7k-token prompt): 2nd call
cached_tokens=5504, and an unrelated conversation gets its own session.
Test: TestOpenCodeSessionIsStableForCache covers same-conversation
stability, cross-conversation separation, per-request request ids and the
sessionless fallback.
(cherry picked from commit 39b48e556e
2026-09-27 17:12:03 +08:00
3d1407e6fa
fix(opencode): make x-opencode-session stable so the upstream prefix cache can hit
...
The opencode adapters derived x-opencode-session from meta.timestamp, i.e. a
brand new session on every request. The upstream prefix cache is
session-scoped, so no request could ever hit it, and the cache fields the
endpoint does report (prompt_tokens_details.cached_tokens,
prompt_cache_hit_tokens/prompt_cache_miss_tokens) always came back 0/absent.
Measured against the live endpoint, same 6032-token prompt:
fixed session id -> 2nd call: hit 5888, miss 144
rotating session id -> every call: hit 0, miss 6032
Fix: derive the session from the source name (stable), matching how
x-opencode-project is already derived. x-opencode-request stays unique per
request — it is only a request identifier, not part of the cache key.
Applied to both opencodego and opencodezen.
Through the gateway the same prompt now reports, on the 2nd call:
details={'cached_tokens': 5888} hit=5888 miss=144 (non-streaming)
prompt_tokens_details={'cached_tokens': 5888} (streaming)
Test: TestOpenCodeSessionIsStableForCache asserts the session is stable
across requests for one source while the request id differs.
(cherry picked from commit 791d198f47
2026-09-27 17:12:03 +08:00
db320d2f6c
fix(opencodego): inject empty reasoning_content on tool-calling turns
...
v1.5.4 stopped stripping reasoning_content, which fixes clients that send
it — but most agent clients (pi included) never store or replay their
reasoning, keeping only the tool call. OpenCode Go validates the field on
any assistant turn that carries tool_calls and rejects the whole request:
400 invalid_request_error: The `reasoning_content` in the thinking mode
must be passed back to the API.
Verified against the live endpoint that an EMPTY string satisfies the
check, so the adapter now fills in "" when a tool-calling assistant turn
has no reasoning_content. Nothing is fabricated: the reasoning shown to
the client is still exactly what the upstream returned for that turn.
Measured: with a tool_call + tool_result history and no reasoning_content,
all 25 configured Go models returned 400 before and all 25 answer
correctly now.
Test: TestOpenCodeGoVsZenReasoning also pins that a plain assistant turn
(no tool calls) must NOT gain the field.
(cherry picked from commit d1a72cd23a
2026-09-27 17:12:03 +08:00
