aff8354c8a
fix(channels,provider): 渠道模型不可用 + 额度异常的三个根因
...
## 背景
用户报三问题：① channel 注册的模型无法使用；② 额度显示依旧异常；
③ 其他渠道应也存在类似问题。三条全部核实并给出结论（③ 见文档）。
## ① 网关解不开 `源名:模型名` 限定名（internal/provider/registry.go）
`ResolvePinned` 用 `strings.IndexAny(model, "-:/")` 找**第一个**分隔符。
而渠道源名形如 `channels-trae-b8dd6b3df30e`（**含 `-`**），于是
`channels-trae-b8dd6b3df30e:Doubao-Seed-2.1-Pro` 被切成
src="channels"、model="trae-b8dd6b3df30e:Doubao-Seed-2.1-Pro"
⇒ 源名永不匹配 ⇒ `Resolve()` 返回 nil
⇒ 客户端看到 `model "..." is not configured`。
**为什么这个写法必须支持**：本实例有 **44 个模型被多源同时提供**
（`glm-5.2` 由 6 个源提供），WebUI 的模型下拉框用 `源名:模型名` 作为
option value 是**有意设计** —— 用户必须能指定"从哪个源调用"。
修法：抽 `splitPinned()`，**按已知源名做最长前缀匹配**（源名是已知集合，
这是唯一可靠办法），保留旧 `-:/` 兜底以兼容非源名形态。
`EffectiveModel` 同步修（同一拆分规则，避免两处漂移）。
## ② trae 适配器三连错（internal/lua/plugins/channels.lua）
三个错误逐层叠加，每个都被上一层掩盖：
**(a) 没有 `build_headers`** ⇒ 内核兜底发 `Authorization: Bearer`，
而 trae 推理端点要 `Cloud-IDE-JWT` + 设备身份头 ⇒
401「We're sorry, but we are not able to authenticate you」。
→ 与上一轮「额度不可用」是**同一根因的两个出口**（额度端点修了、推理端点漏了）。
教训：修"某一族请求的鉴权"时，必须把该族的**所有出口**列出来逐个对齐。
**(b) header 常量的值是错的**（照参考 trae-product.ts 的 TRAE 配置逐项核对）：
· `X-App-Id` 抄成 `6eefa6c9`，真实是 `6eefa01c-1036-4c7e-9ca5-d891f63bfcd8`
· `app_version_code` 用了 `0.1.52`，真实是**日期式** `20260811`
⇒ 上游 `4001 bad request: binding: expr_path=app_version_code,
cause=parameter type does not match binding data`
**(c) 流式转换完全不对**：TRAE 是 **SOLO 自定义 SSE**：
event:output → data:{"response":"###","reasoning_content":null,...}
正文在 `response`，推理在 `reasoning_content`。
· 套 `__prelude.openai_stream_chunk` ⇒ 无 `choices` ⇒ `empty stream`
· 改成 OpenAI 外壳 `{choices:[{delta}]}` **仍然空** —— 内核
`json.Unmarshal(unified, &UnifiedChunk)` 解的是**扁平结构**，外壳字段全被丢弃
⇒ 必须输出扁平 `{content, reasoning_content, usage, done, finish_reason}`。
⚠️ 内核只把 `data:` 行交给适配器（`event:` 行在 provider.go 被丢弃），
因此判别帧类型只能靠**内容特征**（`response` / `reasoning_content` /
`finish_reason` / `prompt_tokens`），拿不到 event 名。
## ③ 余额恒为 0（同文件 balance.total_fn）
读的是 `p.credits_limit`（pack **顶层**）—— 该字段**根本不存在**。
真实路径是 `pack.entitlement_base_info.quota.credits_limit`
（参考 trae-credits.ts:341）+ `pack.usage.credits_amount`。
实测上游：`免费`(无该字段) / `每月登录赠送`(500) / `签到奖励`(100) ⇒ 实际 600。
修法：读嵌套路径 + 保留顶层兼容 + `usage_summary.{total,consumed}_amount` 兜底。
修后余额 600 → 实测 598.516（真实扣减）。
## ④ 夹具与生产形状不一致（internal/core/channels_trae_test.go）
夹具原先返回**扁平** `{"Token":...}`，与生产 `{"Result":{"Token":...}}` 不符
⇒ 「代码只读顶层」这个缺陷在夹具里**恰好是对的**，所有 trae 判据都绿。
**夹具形状错 = 判据必然虚假通过**。这是 ExchangeToken 缺陷藏了两轮的原因。
## 判据（新增，变异 4/4 咬住）
- `internal/provider/registry_pinned_name_test.go`（4 用例）
- `internal/core/channels_trae_chat_headers_test.go`（3 条）
- `internal/core/channels_trae_solo_sse_test.go`（2 条）
- `internal/core/channels_trae_credits_hdr_test.go`（1 条）
- `internal/core/channels_trae_exchange_shape_test.go`（2 条）
## 文档
`docs/channel-repair-plan.md`：现状快照（生产实测）+ 各渠道缺陷矩阵 +
后续计划（P0-P4）。**如实记录**：其余 4 个渠道（zcode/cline/gemini/qoder）
有同类缺陷风险，但**账号数均为 0、无法做生产验证**。
## 生产已实测
- `channels-trae-...:Doubao-Seed-2.1-Pro` → 80 帧，正文 27 + 推理 299
- `channels-trae-...:glm-5.2` / `channels-buddy-...:hy4-preview` → OK
- `credits/status` → active:true, dailyCredit:100, todayCheckedIn:true
- `credits/balances` → total:598.516 credits
2026-10-17 17:38:23 +08:00
7e0a428c23
docs(plugins): 补「前缀代理」章节 —— 插件自起服务挂到网关同端口
2026-10-15 15:01:58 +08:00
d3a0eb6311
docs(channels): 第三批逐模块对照 —— 新补 3 个真缺陷 + 判定不适用的附理由
...
新补：自动领取每天漏领（covers_today）、凭据续期是假的、isFree 与声明矛盾。
插件自装适配器增至 4 个（+channels-qoder / channels-cline）。
★ 判不适用的逐条附理由，而不是简单说没做：
- account-pool 并发写竞态：我们落盘是同步 tmp+rename（Lua 无异步），已加判据
- gemini-messages SSE 末帧：我们的 bufio.Scanner 对无尾换行照样产出（已实测自证）
- cline 30 分钟策略冷却：我们每账号一源，被拦只冷却自己
- retry-after.ts：参考那份自己就是死代码
- image-budget / message-shape / loop-recovery / reasoning-ladder：前提不存在或属内核改动
另记录一条环境教训：/tmp 是 8.8G tmpfs，被构建缓存占满会让测试看起来像死锁。
2026-10-14 20:15:08 +08:00
0c56392d29
docs(channels): 逐模块对照更新（含本轮新补 7 项与未实现清单的理由）
...
穷尽对照 143 模块 / 77720 行后的当前状态：本轮新补 dead-model-store /
catalog-gate / balance-rank+selector / account-probe / model-gate /
ttl-cache+serial-queue / opencode-capability，另修 3 个静默失败。
未实现清单逐条给出理由（不是没做，而是三类：需要真实浏览器/验证码的
captcha 系 ~3300 行、二进制缺失的 qoder wasm、以及宿主 UI 特性或前提不存在
的模块如 message-shape（DSH 消息形状迁移，我们无此问题）与 loop-recovery
（我们的内核没有循环守卫，前提不存在））。
2026-10-14 16:29:42 +08:00
a020247627
docs(channels): 记录数据事故全链（测试覆盖生产账号池）+ 修复中的自踩坑
...
含根因实测输出、为什么 DisableStatePersistence 不够（调度器 goroutine 比
t.Setenv 生命周期长）、两层修法、判据与变异验证。
另记一条我自己的操作事故：恢复账号时把保险库里的**密文**当明文喂给
account/add，而 vault 读取时会解密 → 凭据被二次加密（1971→2965 字符），
该账号推理开始返回空。教训：凭据只能由登录/续期路径写入。
2026-10-14 11:36:15 +08:00
f55d514e85
docs(channels): 生产实测 —— 不可用的真相是 13 个账号里只有 1 个有凭据
...
用户报「完全不可用」。逐平台实测 account/list 后根因不是代码：
| 平台 | 账号 | 有凭据 |
|---|---|---|
| buddy | 2 | 1 |
| trae/minimax/lobsterai/codearts | 3/1/1/5 | 0 |
| 其余 7 平台 | 0 | 0 |
13 个账号只有 1 个真有凭据，其余是**占位壳子**(has_credential:false)。
此前把「12 平台 0 个 manual」当作已接好的判据是**错的** —— manual 是 flow
类型，不等于登录成功。
排除项（全部实测，非推断）：
- 部署一致性：4 插件 sha256 与仓库全部一致，关键标记全在位
- **推理链路可用**：POST /v1/chat/completions 实测返回 "OK"
- 登录机制可用：minimax 真实返回 user_code，trae 起了服务端浏览器
- 设备码轮询正确：未授权时持续 pending，不误判成功/失败
结论：剩 12 平台都需**人工授权**（device-poll 去官方页输码、callback 在
VNC 里点、qr/wechat 扫码）。
B 类修正判断：
- qoder-wasm：二进制不在仓库（find -name '*.wasm' 为空），拿到才有意义
- zcode-captcha：**登录不需要它**。captcha 只用于签到/领取
（zcode-auth.ts:22-23 每个 plan 单独 mint）—— 真实价值是让领取全自动，
不是让平台可用
2026-10-14 00:28:32 +08:00
faa3be5c37
test+docs(channels): 三私有协议平台的源接线判据 + 自装适配器机制实录
...
补齐"装了适配器 ≠ 源用了它"这条判据。这是这类改动最可能的漏配，且
**不会报错** —— 只是签名/信封不生效、上游返回流内错误或 401，看起来像
"平台不稳定"。三个平台的失败模式不同、根因同一个（平台协议差异被当成
适配器名差异）：
codearts → 华为云 AK/SK 签名
trae → SOLO 载荷格式
gemini → 私有 /v1internal: 信封 + 身份五头
判据同时验 adapter 名、base_url 与"源里必须有模型"。
docs/channels-parity.md 补两节：
- 三个私有协议平台已改用插件自装适配器（含 credential_shape 的引入原因：
codearts 凭据没有 access_token，credentialOf 取不到 → 静默不出源）
- 附录：机制（内核早已具备，channels 插件引用数为 0）、三条实测能力、
六个"静默失败"类踩坑、判据清单
2026-10-13 23:44:30 +08:00
fe9d5c6054
docs(channels): 补架构差异分析 —— 为什么参考正常、我们靠 adapter 名硬撑
...
查证参考仓架构后的结论：
- 参考：一个平台一个继承宿主 LlmAdapter 的真类（trae 做 SOLO 转换、
codearts 做 AK/SK 签名、zcode 走 Anthropic），公共逻辑抽在
openai-compat.ts（1196 行，8/12 adapter 复用）
- 我们：内核是 proxy，插件只注册源；平台差异被当成 adapter 名差异
- 关键：内核**早已实现** __llmsproxy_adapters.install（含归属校验、冲突
仲裁、测试 TestPluginInstallsAdapterFromLua 通过），但 channels.lua
对这个全局的引用数是 **0** —— 一个适配器都没装过
- 我们还缺参考的共享前导：openai.lua 与 anthropic.lua 各复制一份
safe_tool_id
- 记录了下一步落地前必须先探的两条风险（适配器 VM 能否读 secrets、
流式转换能否跨 chunk 保持状态）
2026-10-13 18:40:00 +08:00
3e94047889
docs(channels): 三线对齐表（登录/模型获取/接入模型服务）逐平台实录
...
按参考仓的命名规律（X-auth / X-product / X-adapter）建表，记录：
- 本轮修的四件事（codearts 登录、模型兜底表、chat 端点、gemini 私有协议）
- 三个**未闭环**项并写明理由（codearts 模型获取需 AK/SK 签名、
trae 载荷需转 SOLO 格式、gemini 信封需字母序 + 身份五头）
- 明确不做的四项（gemini-sigstore 不适用、qoder-wasm/zcode-captcha/
captcha 池属 B 类）
- 本机实测的 5 个坑
2026-10-13 17:04:09 +08:00
c1733feeaa
feat(channels): Qoder 每日活动领取（多活动逐个领）+ 三条误报陷阱全部钉死
...
## 参考依据
`qoder-credits.ts` 的 `claimQoderDailyCheckin` / `parseQoderCampaigns` /
`claimQoderCampaign` / `hasQoderCampaignRefreshedToday`。
参考用**抓包 + 用户报障**定位过三条会「误报」的陷阱，全部在实现与判据里钉死：
### ① 「无可领活动」必须是 inactive，不能报 already-claimed
旧实现 targets 为空就说"今天已领取" ⇒ 只要服务端没下发可领项（含**请求头不完整**、
未到刷新时间、本就无活动三种情形），界面就谎报已领，与官方 IDE 的"可领取"直接矛盾。
用户报障原文：「没领过却显示今日已领取，去 IDE 看还能领」。
### ② 每日 10:00（UTC+8）刷新；刷新前的 CLAIMED 属于**昨天**
此时说"今天已领取"是谎报，且不可逆（用户以为今天不必再领）。
必须用**算术平移**判 UTC+8 —— 用本机时区在出差/改时区时会判错方向
（偏东提前把当天记为已处理、真漏领；偏西一天判两次）。
### ③ 未开通要给 action_required 的可操作提示
判据是**两条同时**满足（无 CLAIM_BENEFIT + 用量响应里 `addOnQuota` **字段缺失**）。
⚠️ 用「字段是否存在」而非「remaining 是否为 0」—— 后者对"额度用光"与"从未开通"
不可区分，会把用光额度的老账号误报成未开通。文案要可操作（去官方客户端登录一次），
并作为显式字段透传给 UI，而不是让 UI 猜文案。
### 其他要点
- 一个账号可能同时有**多个** CLAIM_BENEFIT 活动 → 逐个领取（实测有每日 100 与运营活动）
- 幂等判据是响应体的 **`replayed`**，不是 HTTP 状态码：重复领取同样回 200，
但 `replayed:true` 且不含 benefit（只看状态码会把"今天已领"误报成"成功 +100"）
- 请求体必须是**空串**（抓包实测 `content-length: 0`）
- 缺 `Cosy-MachineToken/MachineType` 时服务端不下发可领活动（见上一个提交）
## 判据
- `TestQoderClaimDecisionTable`：6 个用例覆盖四类结果 + claim 次数 + body 必须为空
- `TestQoderRefreshUsesUTC8NotLocalTime`：**注入 UTC 时刻**验证刷新判定
★ 修判据自身两处缺陷（首轮变异存活）：
1. `TestMain` 把测试进程 TZ 钉成 **UTC** —— 本机恰是 HKT(+0800)，于是
「UTC 平移」与「本机时区」结果**完全相同**，误用本机时区的实现抓不到（判据不可达）。
2. 决策表缺「无任何活动且已开通（addOnQuota 存在）」用例 →
把 inactive 误报成 already-claimed 的变异得以存活。补齐后两个变异都被抓。
## 统一前向声明（Lua 作用域，本文件第 N 次）
把 `qoderMachineIdentity / rfc3986Escape / newToken / lobsteraiClientVersion`
统一在 PLATFORMS 之前前向声明。此前逐个补、位置还放错过一次，导致运行时报
`attempt to call global 'x' (a nil value)` 而编译期静默。
## 文档
`docs/channels-parity.md` 更新：gemini-sigstore 标注为**⛔ 不适用**
（llmsproxy 的推理走无状态适配器，插件不参与推理 —— 插件侧缓存会成为死代码；
若将来要支持，位置在适配器侧，与"适配器无状态"约定冲突，须单独决策）。
2026-10-13 16:11:11 +08:00
1586a051da
fix(channels): CodeArts 签名按参考重写（华为云 SDK-HMAC-SHA256）+ 完整 4 步领取
...
## 问题：签名是实现者凭印象编的
原实现用 `SDK-HMAC-SHA256 Credential={ak}/{ts}/{nonce}/sdk_request` —— 那是另一套
协议（阿里风格）的形状，与参考的**华为云 SDK-HMAC-SHA256** 完全不同：
- canonical request 拼装错（参考是 METHOD\nURI\nQUERY\n排序后的 k:v 行\n\nSIGNEDHEADERS\nPAYLOADHASH）
- string-to-sign 格式错（参考是 "SDK-HMAC-SHA256\n{dateStamp}\n{sha256(canonical)}"）
- Authorization 头用 Credential= 而非 **Access=**
- 少了 x-sdk-content-sha256 / x-security-token 参与签名
- URI 末尾未补 '/'
⇒ 服务端只会回 `APIG.0301 ... verify ak sk signature fail`，看起来像"账号/权限问题"，
这个平台注定领不到额度。
## 修
逐行对齐参考 `sign.ts:signRequestHuawei` + `codearts-credits.ts`：
1. canonical request / string-to-sign / signature 全部照参考
2. 参与签名的头：host / x-sdk-date / x-sdk-content-sha256 / x-security-token
（非 GET 再加 content-type），按字典序拼 SignedHeaders
3. Authorization = `SDK-HMAC-SHA256 Access={ak},SignedHeaders=…,Signature=…`
4. Agent-Type / X-Language 是**签名后**追加的，绝不进 canonical（否则验签失败）
5. URI 末尾补 '/'
6. 完整领取 4 步（参考的 6 步判定顺序）：账户类型 → 活动列表 → claim →（benefit.id
非空时）confirm；用 done 哨兵回给 claim_daily（它自己发多个请求，契约只发一个）
- 非积分账户 → inactive（Token 账户不该被报成"领取失败"）
- activity.claimable=false 且状态属已领取态 → already-claimed（**唯一的幂等保护**，
本协议没有幂等键）
- confirm 失败不算整体失败（积分已在待确认态），只是降级提示
## 判据（差分，与参考逐字节一致）
`TestCodeArtsSignatureMatchesReference` + `tools/codearts_sig_expected.mjs`
（照抄参考函数生成期望值）。覆盖 canonical / string_to_sign / signature /
SignedHeaders / Authorization 形状 / canonical 不得含签名后追加的头。
变异验证：`Access=`→`Credential=`、去掉 content-type 参与签名、URI 不补斜杠
—— 三个全部被抓。
★ 修判据自身缺陷：首版探针**自己重算** canonical，导致真实签名被改坏时判据仍绿
（去掉 content-type 的变异存活）。改为让签名函数返回真实中间值，探针直接取用。
## 文档
新增 docs/channels-parity.md：与参考逐平台对齐清单（登录 / 额度 / 推理链路三张表
+ 差分判据表 + 未对齐项按影响排序），未对齐项**明示**而非含糊。
2026-10-13 15:38:35 +08:00
6fe6014d92
chore: 清理 emoji 与修正发布脚本仓库名
...
产品代码统一为纯文本风格（照参考实现），去掉 emoji：billing/quota/usage 插件、
channels 的提示文案、WebUI 文案，以及 go 测试、docs、packaging 脚本中的
注意/OK/FAIL 等符号化写法。第三方目录（vendor、node_modules、.probe）不动。
另：packaging/upload-release.sh 的仓库名改为真实全名
JianFeeeee/ModelRouter → HeNanMU-EEA/ModelRouter（前者是重定向，POST/PUT 不跟随
会 404）。
2026-10-13 13:42:57 +08:00
3c59c33c58
feat(adapters): 入向端点移交适配器 —— adapter.ingress + deserialize_request，内核主动让出
...
plan.md 的 R2 目标里有三行钩子契约，出向两条（serialize_response/serialize_chunk）
Phase 2 已落地，第三条 parse_request(protocol_body) -> unified 一直空着：
/v1/messages 的入向解析硬编码在内核 Go 里（anthropicRequest.toUnified），
Anthropic 改协议就得改内核。本次补齐这条对偶。
## 机制（与出向序列化对称）
- 适配器声明 adapter.ingress = "/v1/messages" 认领入站路径，并实现
deserialize_request(raw_body) -> unified_json。
- 内核 handleMessages 经新增的 parseViaIngress 判定：
- 有适配器认领该路径且实现了钩子 → 让出，解析由适配器完成；
- 无适配器认领 → 内核内置解析运行（R5 兜底，未配置部署仍可服务）。
- 认领了但钩子执行失败 → 硬错误 400，不静默换用另一种协议解析
（客户端说的正是该适配器声称支持的协议，悄悄换解析器只会错误调度）。
- 这是内核里唯一的新判定点，与 serializerFor 对称：出向选序列化器，入向选解析器。
## 内核改动
- internal/lua/vm.go：staticInfo 增 ingress 字段；inspectScript 读取；
新增 VM.AdapterForIngress(path)（确定性选择：同名多认领取字典序最小）。
- internal/gateway/messages.go：handleMessages 改为先读 body → parseViaIngress
（让出）→ 未认领时回落内置 anthropicRequest.toUnified。
内置解析与 anthropicRequest 类型保留——它们是兜底，不是死代码。
## 适配器改动
- internal/lua/adapters/anthropic.lua：声明 adapter.ingress = "/v1/messages"，
新增 deserialize_request，把内核原 Go 解析逻辑逐字段移植（system 两种拼写、
content 原样透传、缺省 thinking={enabled:false}、缺 messages 报错）。
内置 anthropic 默认随包播种，因此真实部署里内核总是让出给它，
Go 侧 anthropicRequest.toUnified 退化为纯兜底。
## 测试
- gateway：TestMessagesIngressYieldsToBundledAnthropic（让出后仍 200）、
TestAdapterForIngressClaim（声明可被找到、未声明路径为空、钩子存在）、
TestMessagesKernelFallbackWhenNoAdapterClaims（移除认领适配器后内核兜底仍 200）。
- lua：TestAnthropicDeserializeRequestShape 逐字段核对 Lua 与 Go 产出一致
（system 拼接、content、max_tokens/stream/temperature/top_p/top_k/stop_sequences、
缺省 thinking），TestAnthropicDeserializeRejectsMissingMessages。
- 全量回归：gateway/lua/core/config/types/provider/scheduler/e2e 全绿。
- 文档：docs/lua-adapters.md 补「入向让出钩子」章节 + plan.md 台账更新。
2026-10-12 16:32:30 +08:00
a59295e826
feat(lua): 插件可调内核动作面（R4-c）+ 凭据保险库（R4-d）
...
用户指出「接口不全」——此前插件只有 __llmsproxy_adapters 三个手写闭包，
够不到内核。对照参考插件（dsh-our-free-model，13 个账号渠道）的真实能力，
缺的正是这两块：
插件自己驱动链接认证 → 存凭据 → 定时领额度 → 把源接进内核
## R4-c 内核动作面：__llmsproxy_kernel
18 个动作，全部映射到既有 Core 方法（不是新造能力）：
只读 6：status / list_sources / list_models / list_adapters /
list_auto_rules / adapter_owner
写 8：reload / reset_health / probe_all / save_auto_rules /
save_key_auto / add_source / create_key / update_key
破坏性 4：remove_source / delete_key / remove_adapter / set_plugin_enabled
**add_source 是「插件注册自己的上游」的落点**——插件拿到凭据后可以自己把
端点接进网关，无需运维改 config.yaml。已端到端验证：插件调它 → 内核源列表
出现 → 模型进入可路由列表。
依赖方向：lua 不能 import core，所以接口定义在 lua、实现放 core
（kernel_actions.go），走 SetKernelAPI 注入——与 SetOutboundHosts 同一先例。
**凭据边界**：动作面**有意排除** list_keys/find_key。Core.ListKeys() 返回
明文网关密钥，交给第三方 Lua 等于交出整个部署的凭据面。有回归测试锁死
这条（TestKernelActionSurfaceExcludesPlaintextKeys）。list_sources 返回的
api_key 也强制掩码（只给 ***+后4位）。
**权限**（用户选「全开+设置页可配」）：18 个动作全部可达，但**默认拒绝**，
授权落盘 .kernel-perms.json（独立文件，不并进 .access.json——后者是
map[string]string，塞进去会破坏旧二进制能读的格式）。danger 级不接受通配符。
插件可在源码 plugin.kernel={...} **申请**，设置页显示申请 vs 已授予。
**Go 侧 deadline**（用户选定）：每个动作有超时预算，超时把 (nil,err) 还给
Lua。这可行的原因：Lua 只是等返回值，不占 Lua 栈执行权——与「Lua 死循环
不可中断」是两件事。
## R4-d 凭据保险库：__llmsproxy_secrets
此前插件存 token 只能写 plugin.state：0755 目录、明文、与计费累计量同文件、
会被 PUT /state 整体替换、会进 WebUI。现在独立文件：
<plugin_dir>/.secrets/<plugin>.json 文件 0600，目录 0700
临时文件**先 chmod 再 rename**，全程不存在宽权限窗口。读取身份在插件 boot
时绑定（不从 Lua 状态现读）⇒ 跨插件读不可行是机制而非约定。插件删除时清空
（DeleteAllSecrets + 启动 PurgeOrphanVaults）。
## 开发中被测试抓出的两个真实缺陷（我自己引入的）
写了 TestNoKernelActionDeadlocksFromLua 对**每个**动作断言「在插件 Lua 调用
（此时持有 p.mu）内不得死锁」，抓出：
1. **自死锁**：set_plugin_enabled → SetEnabled → p.mu.Lock()，而死锁发生在
调用者已持有的同一把锁上。
2. **更隐蔽的迟到副作用**：超时把 error 返回给插件后，动作仍在幕后执行完成——
插件以为失败，实际已生效。
修法：标注 Deferred 的动作在本次调用返回后异步执行，如实返回 accepted:true
而不是谎报成功。18 个动作全部复验无死锁，另有单独测试确认副作用真的落地
（只测「不死锁」的话，一个全空转的 dispatch 也能通过）。
测试 11 个（core 8 + lua 3）：动作可用/密钥掩码/默认拒绝/授权计数/
插件注册源并变为可路由/授权落盘重启保留/未知动作名被拒/凭据面排除明文/
全动作无死锁/破坏性动作生效/Lua 侧桥接可用。
2026-10-11 13:52:29 +08:00
dafc3b3fc3
feat(lua): 插件 Lua 侧适配器桥接（R4 Lua 绑定）+ 真二进制适配器接手 e2e
...
补上两个此前报告为"缺口"的东西。其中第一个的旧结论是**错的**，这里更正。
## R4 Lua 绑定：__llmsproxy_adapters
用户问的"为什么 Lua 绑不上"—— 结论是**能绑，之前的归因错了**。
旧结论是「NewTable + PushGoClosure + SetField 是 golua 雷区，会 SIGSEGV」。
反证：内核自己的 buildJSONTable 用的就是这同一个模式，长期稳定。真正的变量
是当时 Phase 4 的**双 VM 半成品**（钩子一个 VM、定时任务一个私有 VM），
bootPluginState 签名与调用点不一致，我改到一半编译不过就仓促回滚，留下的
中间态让 billing 一跑就崩。把双 VM 改回单 VM 之后，同一模式一次就通。
顺带回答一个备选方案（用户提出：Lua 只投递请求、Go 串行执行）：不需要。
p.mu 已经天然串行化同一插件的所有入口；再加队列只会引入"谁排空/超时后积压
怎么算"的新问题。而且桥接调用本身是微秒级的（交给 Go 重建一个小池），真正
长耗时的是插件自己去取 token 的 HTTP 请求，那跟桥接无关。
能力（Go 侧强制，非约定）：
- install(name, source) → (生效名, nil) | (nil, err)
- update(name, source) → (true, nil) | (nil, err) 只限自己装的
- remove(name) → (true, nil) | (nil, err) 只限自己装的
- 调用身份是插件**启动时的固定名**，不从 Lua 状态现读 ⇒ 无法冒充别的插件
- 不能影子内置（Lua 侧同样被拒，不是绕过 Go 校验的后门）
- 出错返回 (nil, err) 而非抛异常，与钩子/HTTP 处理器同一套约定
**分片 VM 故意不给**：分片是文档化的「只读、可丢弃」工作单元，而适配器
install 是**全局**副作用（改共享注册表）。给分片等于让"只读"的按需调用悄悄
改写所有请求共用的适配器 —— 正是分片契约要防的不可见变更。
测试 6 个：install/rotate/remove 从 Lua 调用、影子内置被拒、**定时任务里
轮换 token 且请求钩子立即可见**（R4 闭环）、分片无桥接。
## 真二进制 e2e：适配器接手对外服务
用户问到的第二个点。此前 /v1/messages 的 Anthropic 接管只在**进程内**
gateway 层测过（internal/gateway/messages_test.go），绕过了只会在真实进程里
发生的事：适配器磁盘 seed、配置加载、真 HTTP 栈。
新增 e2e/adapter_takeover_test.go，打**真编译的二进制** + 只说 Anthropic 的
假上游（该上游对不符形状的请求主动报错，不做宽容接受）：
- 非流式：出向必须是 Anthropic message 形状，不能有 OpenAI choices 外壳
- 流式：必须是 message_start…message_stop 序列，**不得**出现 [DONE]
- 压力：96 并发（48 流式）混合打真二进制，全部 200，无 5xx，无形状串味
压力测试初版把并发上限设成 4 于是大量 429，我把断言改正为：429 是内核**正确**
的容量背压，不算失败；失败的定义是 5xx 或 200 但内容/形状错。现在 96/96 通过。
2026-10-11 13:25:11 +08:00
66786bb0e3
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-10-11 13:07:50 +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
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
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
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
3806aaee03
docs(workflow): codify the branch model — main / feature / release branches
...
Adopt GitHub Flow + release branches, replacing "everything straight to main
plus a tag" which caused the 1.4.2 pain (a fix had to be retro-fitted to the
released version, forcing a remote-tag delete + full re-upload).
- main: only long-lived branch, always deployable, accumulates the next version
- feature/<desc>: born from main, merged back when done
- release/vX.Y.Z: cut from main, tagged, installers built from the tag
- hotfixes land on the release branch AND are cherry-picked back to main so
main never loses a fix
- end of lifecycle = retire the release branch (delete; or keep for long-term
maintenance), no wholesale merge back — hotfixes already flowed
- explicitly no rebase of main, no release-branch-merge, no quick edits on main
Companion release checklist includes the upload lessons (PUT --http1.1) and the
replace-artifacts-by-deleting-the-tag catch.
Docs in docs/git-workflow.md (zh) and docs/git-workflow-en.md, linked from both
READMEs.
2026-08-31 12:36:17 +08:00
b2183df1e8
feat(adapter): move per-source error condensing into transform_error hooks
...
Every upstream formats errors differently, which is adapter territory:
the protocol gains an optional transform_error(status, body) hook and all
built-in adapters implement their own envelope parsing (zen free-pool
labels, anthropic/gemini/ollama/mistral shapes, sensenova quota notes,
agentrouter WAF pages). The core keeps a single uniform fallback: when no
hook yields a reason clients get "api error <status>: unknown error" and
the raw body goes to server logs only.
2026-08-24 19:17:36 +08:00
5d50b69153
fix: tool call anchor & wire format, streaming chunk passthrough, WebUI narrow-screen, docs bilingual
2026-08-08 11:26:58 +08:00
