8f2c5572e7
chore!: 移除厂商私有协议适配器与渠道业务插件（合规清理）
...
G-Star 合规要求下，把"模拟官方客户端、复刻私有协议、自动领取平台额度"这一类
能力整体移出仓库。这些实现依赖各平台未公开的端点、签名算法与官方 client id，
属于绕过客户端校验获取额度，风险高于普通协议适配。
移除（93 个文件）：
- 适配器：opencodezen（伪装 UA 取免费池）、trae、buddy、kimicode
- 插件：channels.lua（12 个平台登录/领额度/签到）、quota.lua（厂商额度探针）
- 随之删除的 78 个渠道/额度专用测试与 3 份渠道文档
同时修掉的既有问题：
- **硬编码第三方 OAuth client_secret**（Google Cloud Code 的 GOCSPX-…，两处）
随 channels.lua 一起消失。
- `deploy.sh` 的 `sync_plugins` 整段删除：它仍按"内置插件是发行物"的旧前提
把插件复制/覆盖进 plugin_dir，与"插件属运维资产、网关不安装不覆盖"的契约
冲突。现在部署脚本只同步适配器与二进制/配置。
- 适配器清单去掉已移除项；e2e 配置改用显式 `auto:` 链（`models.priority` 早已
移除，该测试此前已失效）。
保留（公开协议）：openai / anthropic / gemini / deepseek / github / groq /
mistral / ollama / qwen38 / sensenova = 10 个适配器；插件示例 billing / usage。
验证：go build -tags luajit ./... OK；internal/lua 21.4s、provider、core 51s、
gateway 122.8s、e2e 9.0s 全绿。
2026-10-27 09:25:58 +08:00
e2ced5ed66
fix(packaging): 包内 unit 指向 /usr/bin；core-dist 支持无 nfpm 打包
...
两个都是发布链上的真缺陷，构建 v3.0.0 产物时才暴露：
1. **unit 与包内二进制路径不一致**：deb/rpm 把二进制装到 `/usr/bin/modelrouter`，
而 `modelrouter.service` 的 `ExecStart` 写 `/usr/local/bin/modelrouter`。
装包后 `systemctl start` 只会给 203/EXEC，看起来像"装好了但起不来"。
- 包内 unit 改 `/usr/bin/modelrouter`（FHS，装包即用）
- 源码部署仍用 `/usr/local/bin`，`deploy.sh` 增加校验：unit 的 ExecStart
指向不存在的文件时**中止**并说明两种布局的区别
- docs/deployment.md 同步说明
2. **core-dist 硬依赖 nfpm**：构建机离线（GOPROXY 不可达）时装不上 nfpm，
发布直接被堵死。现在 nfpm 优先，缺失时回退 dpkg-deb + rpmbuild，
两者产出同一套文件布局，并继续由末尾的 archive-content 门禁校验。
- rpm 回退踩到的坑：postinst/prerm 末尾无换行时，`%preun` 会粘在
`exit 0` 后面，整个 `%files` 段被吞，rpmbuild 报
"Installed (but unpackaged) file(s) found"。
- `%dir /etc/modelrouter` 要求 buildroot 里存在该目录，否则
"Directory not found"。
验证：`./packaging/core-dist.sh 3.0.0` 产出 deb(4220KB)/rpm(4229KB)/tar(4145KB)；
包内 unit `ExecStart=/usr/bin/modelrouter`，`systemd-analyze verify --root` 通过；
deb/rpm 均不含 `plugins/`，adapters=14。
2026-10-27 00:51:12 +08:00
f7e926ccb7
docs: README 拆分为主题文档 + 中性化竞品表述
...
README 从 642 行降到 131 行，只保留简介、核心能力、最小快速开始、文档索引、
改名说明、目录结构与测试入口。其余内容迁到 docs/，中英文索引一一对应：
docs/features.md 实现与完整特性清单（原 README 的"实现/特性"）
docs/configuration.md 配置文件、自动探测模型、多密钥与配额
docs/routing.md 模型路由、AUTO 链、冷却与半冷却、源/适配器、源模板
docs/performance.md 实测内存占用与调优、thinking 预算
docs/webui.md WebUI 使用
docs/adapters.md Lua 适配器协议与内置适配器清单
docs/gui.md 桌面端 Headless/Desktop 两种产物与构建
docs/development.md 目录职责、开发协作、测试
docs/deployment.md 部署、发行包、目录权限、llmsproxy 迁移与验证清单
中性化：README / README_EN / GUI 注释里的 `Clash Verge` 类比全部改为
「桌面壳 / desktop shell」，仓库内（源码与文档）已无该表述。
2026-10-26 22:28:24 +08:00
688dce88d1
refactor(rename)!: llmsproxy → modelrouter（module / 二进制 / 路径 / env）
...
产品名早已是 ModelRouter，但仓库标识符仍沿用旧名。这次统一，读写两侧都做兼容，
已部署的机器不会因为顺序问题立刻失效。
- go module `llmsproxy` → `modelrouter`；全仓 import 与 `cmd/modelrouter` 同步。
- `Makefile BINARY=modelrouter`；发行包名、systemd unit、/usr/share 资源、
`/usr/local/bin` 目标全部改为 modelrouter。
- 默认配置目录 `/etc/llmsproxy` → `/etc/modelrouter`。**读取侧回退**：插件与
`storeDir` 仍会检查旧路径，所以"先换二进制、后改 unit"不会立即失效。
- 环境变量 `LLMSPROXY_*`（PLUGIN_DIR / XDISPLAY_BASE / ARCH / LIVE_ZEN /
BUILD_DIR）改为 `MODELROUTER_*`；`LLMS_PROXY_MASTER_KEY` →
`MODELROUTER_MASTER_KEY`。旧名在读取侧继续接受。
- 桌面端内嵌核心 `bin/llmsproxy` → `bin/modelrouter`，并保留旧文件名回退，
避免升级到一半的 profile 被判成"core binary missing"。
- 新增 `packaging/migrate-to-modelrouter.sh`：**默认 dry-run**，复制而非移动、
旧目录永不删除、支持 `--rollback`；随 release tar 分发并由 core-dist 校验。
- `deploy.sh` 增加改名保护：发现旧 `/etc/llmsproxy` 而新配置不存在时**中止**，
否则会部署出一个"能启动但没有 key、没有源"的空实例。
- 临时目录前缀 `/tmp/llmsproxy-*` → `/tmp/modelrouter-*`；清理逻辑同时回收两代。
兼容别名（`__llmsproxy_*` 全局、`llmsproxy` SDK 别名、旧路径/旧 env）刻意保留，
它们是升级路径而非遗留；docs/plugins.md 已标注为废弃。
本提交未包含：`adapters/opencodezen.lua`、`adapter_opencodezen_test.go`、
`adapter_opencodezen_live_test.go`（OpenCode UA/免费池的既有改动，另批提交）。
2026-10-26 22:28:08 +08:00
de7553eaa2
feat(lua)!: 插件只通过 modelrouter SDK 与内核交互，且不再随内核安装
...
- 新增唯一公开接口表 `modelrouter`（sdk_version=1.0）：http / secrets /
kernel / adapters / plugin_dir。成员与内部桥是**同一对象**而非副本 ——
复制会让凭据保险库分叉（插件写 A、内核读 B）。
- `llmsproxy` 与 `__llmsproxy_*` 降为同对象兼容别名，只为已装插件继续可用。
仓库内 4 个插件（channels / billing / quota / usage）全部改用
`modelrouter.*`：此前它们直接依赖内核私有全局，内核无法在不炸插件的前提下
改实现（重命名、加守卫、换实现都算破坏性变更）。
- 插件不再由网关安装：`SeedBundled()` 变彻底 no-op，`core.New` 不再调用；
`ReadBundledPlugin` 改为按源文件定位（脱离 cwd），只服务测试与开发工具。
- 桌面端删除 `BUILTIN_PLUGINS` 与 `syncBundledPluginsOnUpgrade`：升级不再
删除、改名或覆盖用户插件文件。插件是运维资产，不是内核资源。
- `Builtin` 不再靠"源码与仓库示例逐字节相同"推断，插件一律视为外部文件。
- 判据：SDK 存在/版本/形状、别名与内部桥同一张表、适配器 VM 拿不到 SDK、
经 SDK 真实写读凭据并驱动内核动作、GUI 升级不动插件文件、release 包不含插件。
说明：channels.lua / quota.lua 同时带有此前的渠道与额度改动（含 OpenCode 免费池
监控），与 SDK 改名同处一个文件，无法文件级拆分，故一并纳入。
2026-10-26 22:27:12 +08:00
7941b4110a
refactor(billing)!: 计费全部沉入插件，内核零 billing 代码；规则由插件自持
...
按维护者要求（issue #1 回复方向）：内核不处理任何 billing 特有逻辑；插件有完整
OS 权限，自己保存配置文件。据此不再保留任何"内核 ↔ billing 插件"的专用对接。
## 内核（删除）
- `internal/billing`（Go 编译器 + 测试）：删除；
- `internal/core` 的 billing 接口/降级应用/规则加载：删除（含 `billingPath`）；
- `internal/gateway` 的 `/api/plugins/billing/rules` 端点与测试：删除；
- `config` 的 `BillingDSL/Profile/Rule/Token/Peak/LongContext` 与校验、
`billing:`/`billing_file:` 配置段：删除。系统配置里不再有 billing 段。
内核只保留所有插件通用的能力：加载 .lua、插件状态持久化、插件目录
（`__llmsproxy_plugin_dir`）、`plugin.http` 路由、插件可用的 io/os。
## 插件（billing.lua）
- 规则文件移到**插件自己的目录**：`<plugin_dir>/billing.json`，由插件用 io 自己
读写（tmp + rename 原子替换）；加载插件时自己读文件并编译；
- 规则以**源名** `source` 为键（`url:"*"` 仅表示全局模型价目表）：URL→源名映射
属于内核配置，插件不为它和内核对接；编辑页在浏览器里取 `/api/sources` 选源名；
- 规则编辑 API 改为插件自己的 `/api/plugins/http/billing/rules`
（GET/PUT/POST/DELETE，roles=admin），写盘也在插件内完成；
- 计费账目仍在插件状态文件（内核通用持久化）`<plugin_dir>/.billing.state.json`；
- `priceFor` 落地 profile 级 `default` 策略与显式 `mode=unpriced` 的优先级。
## 迁移
生产已迁移：`config.yaml` 的 `billing:` 规则转为 `plugins/billing.json`（按源名
重写），并从系统配置中移除；规则文件与系统配置从此各自独立保存。
## 判据
- `internal/lua/billing_rules_test.go`：插件自写 billing.json 并重启恢复、
free/subscription/token/通配符编译语义、1e6+1e6 token = 0.75 端到端、
非法规则被拒且不覆盖旧文件、reasoning/long_context/peak；
- `internal/lua/billing_test.go`：profile default 策略三态 + 显式 unpriced 优先；
- `internal/lua/billing_ui_test.go`：规则编辑页仍挂在 billing 页内、列宽/列数守卫。
2026-10-20 18:57:23 +08:00
b4c5f0f0fc
refactor(billing): 计费语义下沉到 Lua（内核只解 YAML/传数据）+ 采纳 PR #2 语义
...
按 issue #1 的修复方向（维护者评论）：内核不再持有任何计费语义，billing 逻辑
全部在 `plugins/billing.lua`；内核只负责解 config.yaml、校验 schema、把
profile + 源 base_url 作为**数据**交给插件，再把插件算出的价目通过 `prices`
侧车注入。计费账目仍持久化在插件状态文件（`plugin_dir/.billing.state.json`）。
## 变更
- **删除** `internal/billing`（compile.go 359 行 + 其 Go 测试）；
- 新增 `core.compileBillingPrices`：把 profile/sources JSON 化后调用插件导出
`compile_prices`，返回价目表 + 未匹配规则清单（供错误日志点名 URL）；
- `applyBillingDSL` / 规则编辑器改为走同一个插件编译入口（编辑器 lenient，
半成品规则可保存、可报告）；
- `billing.lua` 新增 `compile_prices`：URL 归一匹配、首条命中优先、
free/subscription/unpriced/token、USD/M→per-token、peak 窗口、
long_context 边际价、reasoning 可选价、default 策略、未匹配清单。
错误通过载荷 `error` 字段回传（插件导出第二返回值通道不可靠）。
## 与 PR #2（valuelesser）合并后的语义
- **token 规则不产生任何源条目**：未列价的模型落到 unpriced 统计（可见），
不再"静默计 $0"。比 issue 正文里的 `{per_request:0}` 标记更收口；
- `default: free` 由**编译期**给未匹配源写 `{per_request:0}` 标记；
`unpriced`/缺省不写。删除无人读取的 `default_mode` 死键；
- 保留 `unmatched_rules` 清单（只用于降级应用时点名过期 URL）。
## 判据（原 Go 单测平移到 Lua + PR #2 的用例）
- `internal/lua/billing_compile_test.go`：通配符不标记源、token 规则无源条目、
任意源条目不得携带 token 价（根因直防）、free/subscription 保留有意零价、
reasoning 缺席、long_context 三种形态、peak 形状、URL 归一+首条优先、
lenient 未匹配清单、硬错误 5 例、default 两态；
- `internal/lua/billing_test.go`：编译输出驱动真实 priceFor 的 A/B 用例
（旧形状 cost=0 / 新形状 0.75 且 unpriced=0）、default 编译期语义 e2e；
- `internal/gateway`：token 规则断言"无源条目"、模型价 per-token 量级；
- `internal/core`：过期规则 URL 降级应用（有效规则仍生效）。
2026-10-20 18:33:26 +08:00
33cb2bdb06
fix(billing): 源层零价不再覆盖模型价（issue #1）+ default_mode 生效 + 文档/判据补齐
...
GitCode issue #1：任何按 `mode: token` 且 URL 非通配符的规则定价的源，计费恒为 0，
且 `unpriced_reqs` 也不增长 —— 完全静默。
## 真因
- `compile.go` 给这类规则写源条目 `{prompt:0, completion:0, per_request:0}`，
本意只是"标记该源已定价"（同源未列入价目表的模型不算 unpriced）；
- `billing.lua` 的 priceFor() 源层在模型层之后、且 `sp.prompt ~= nil` 即覆盖；
- 两者叠加 ⇒ 模型价被清成 0，而 `out.priced` 仍为 true ⇒ 连未定价计数都不涨。
## 修法
1. `compile.go`：token 规则的源条目只写 `{per_request: 0}`（只是标记，不参与 token
计价）。`free` / `subscription` 保留全零（那里 0 本身就是语义）。
2. `billing.lua`：
- `priceFor()` 的 `out` 补 `local`（此前是 VM 级全局变量，跨请求残留）；
- 实现 `profiles[].default` 的 `free|unpriced` 语义：`free` = 刻意免费（不进
unpriced），`unpriced`（默认）= 未定价债务。此前 compile.go 写 `default_mode`
但**无人读**，两种取值运行时完全等价。
3. `core.go`：应用 profile 时把 `unmatched_sources` 打进日志（WARNING 列出没有
规则命中的源）。该字段此前只写不读，是第二个静默少报点。
4. `docs/plugins.md`：token 价优先级改为与实际实现一致的
`keys > sources > models > default`，并写明"标记已定价只能用 per_request:0"。
## 判据（都先红后绿）
- `internal/billing`：token 规则的源条目**不含** prompt/completion；free/subscription
仍保留显式 0。
- `internal/lua`：同源同模型下旧形状 cost=0（缺陷本身）、新形状 cost=0.75 且
unpriced_reqs=0；未列入价目表的模型仍算"已定价"；default_mode 三态。
- `internal/gateway`：`billing_rules_api_test` 的单位断言原本读
`cc["models"]`（恒 false，整块被跳过——从未执行过），改为 `prices["models"]`，
并新增"源条目不得带 token 价"断言。
## 顺带修掉一个"永不执行"的判据
`discover_mutate_test.go` 的变异锚点写成 6 个空格，而 `discover.go` 已是 2 个空格
⇒ 该变异每次都 `anchor not found`，变异 campaign 长期红着。修正锚点后，
"嵌套 metadata 不再读取"这条变异真的被执行并被测试 KILL。
2026-10-20 17:46:52 +08:00
662f8f02b6
fix(channels): 商汤扫码链路重建 + 双区登录 + 凭据过期口径 + 四条老化判据
...
① 商汤（Raccoon）扫码「链接无效」——两个真根因
- 登录页 /login/mp 已被站点删除（Next 路由 404，实测只有 404 页）；
- 旧实现本地随机造 qrcode_code，而上游早已不认自造码：旧端点
/api/web/auth/v1/login_with_qrcode_code 对任意 code 恒回 pending
（服务端没有该会话）⇒ 扫码永远完不成，账号一直是空凭据。
修法：改为上游现行 IAM 流程（逐行对齐其网页客户端 auth chunk）——
POST /api/iam/v1/auth/mp/qrcode 建会话 → 链接用
/login?code=…&appname=…&source=platform（实测 200 + 微信扫码面板）
→ 轮询 /api/iam/v1/auth/mp/qrcode/login（IAM code:"OK" 与旧 code:0 都认）。
服务端建码失败才退回旧本地码并打 warn。UI 对扫码流程改文案为
「用微信扫码」（原本文案会让人以为点开就自动登录）。
生产实测：链接 HTTP 200、轮询回 pending（会话真实存在）。
② 双区登录（P7）
- 凭据增加 region（intl|cn，缺省＝历史行为）；start_login 接受 region，
会话按区域选端点，完成登录写进凭据；
- CodeBuddy：cn=copilot.tencent.com（platform=ide）/
intl=www.workbuddy.ai（platform=workbuddy-ai，X-Domain、
X-Product-Code、UA 按区域；实测 auth/state 回 200 信封）；
- Qoder：intl=openapi.qoder.sh+qoder.com（client_id e883ade2-…）/
cn=openapi.qoder.com.cn+qoder.cn（client_id 不同 732aef47-…，照参考
QODER_CN）。CN 无公开 chat 端点 ⇒ CN 只做登录/领取；
- UI：buddy/qoder 详情页增加「＋国际区」按钮。
③ 凭据过期时刻的时区口径（P6 真根因）
credentialExpiresAtMs 把 ISO 过期时刻按本地时区解析，而 codearts 给的是
UTC ISO（2026-10-19T16:42:43.06Z）⇒ 本机 +08 下过期时刻虚早 8 小时 ⇒
refresh_creds 每 30 分钟都判"已过期"并对华为云真打一次 STS（token 本还有
23 小时寿命）。改为按声明时区解析（Z / ±hh:mm / 无后缀=UTC 三种形态同一
epoch），补 TestCredentialExpiresAtMsParsesISOAsUTC。
④ 四条老化/假红判据
- TestCreditsPoolReason*：account_add 触发的选号会用构造期默认余额 (0,0)
先查一次并缓存 60s ⇒ 之后改假上游读不到（"余额 100 却报 exhausted"）。
harness 改余额后清 TTL 缓存（__ttl_reset_probe，与生产同一实现）。
- TestAccountReorderActually... / TestPoolListOrderIsDeterministic：随
「一通道一源」失效（按 channels-buddy-<acct> 过滤恒得空）。改写为——
重排必须切换服务账号（新增 __chosen_account_probe），顺序确定性改为断言
选号顺序（__rank_accounts_probe）由 id 稳定决定。
- channels.lua 顶层 local 余量：区域表与 5 份适配器源码常量收进 plugin.K
（TestChannelsLuaHasLocalHeadroom 需要 ≥10 槽位）；ZCode 适配器源码里的
CLI_PREFIX 必须留在源码内（适配器沙箱没有 plugin 全局）。
⑤ 错误文案
openai_error 增补腾讯 codebuddy 三层嵌套 {error:{data:{code,msg}}}：实测
429 code=14018「额度已用尽」此前落到"不识别"，客户端只看到通用文案。
验证：core 434s 全绿、lua 62s 全绿、provider 全绿；生产已部署并实测
raccoon 链接 200 / trae 非流式 200 / zcode 适配器加载。
2026-10-20 08:27:28 +08:00
2113bfc125
fix(channels): 四渠道修复 —— qoder 裸 token 领取 / trae+buddy 非流式 / opencode 目录 / 隐藏适配器
...
生产实测逐渠道排查（2026-10-19）：
* qoder：PKCE 设备码流无 register 第二跳，落库凭据是裸 token 字符串；
qoderClaim 硬要求结构化 table 导致「缺少凭据对象」（而 account_test
走 token 路径正常 —— 自相矛盾状态）。改为非空裸 tok 就地包
{access_token=tok}；补 TestQoderClaimAcceptsBareTokenCredential。
* trae（SOLO 自装适配器）：上游对非流式请求也回 SSE（event: 前缀帧），
transform_response 不识别 → 整个 body 原样透传 → Go unmarshal 报
invalid character 'e'。补 aggregate_solo_sse 聚合。
* buddy（CodeBuddy）：上游 400 11101 只支持流式。transform_request 强制
stream=true；transform_response 补 SSE 聚合（tool_calls 按 index 拼分片）。
* provider 流式：真实 tool-call 片段之后出现 finish_reason=stop 时归一为
tool_calls（trae 实测如此发）；buddy/trae 不再序列化空 tool_calls 表。
* opencode：远端目录端点改为 /zen/v1/models（裸 /v1/models 回 HTML）；
兜底目录同步 2026-10-19 实测（space-bunny-free 410 下架等 5 项变化）。
opencodezen 适配器 v1.1.0：会话亲和（client_session / 首 user 消息指纹
分桶），保留免费层门禁四要素。
* 内核：适配器可声明 adapter.hidden = true 退出用户可见列表；被源引用的
隐藏适配器保持可见（源编辑器要回显当前值）。opencodezen 默认隐藏。
* channels UI：切渠道立即清空账号/模型区 + 响应代际校验，修复 qoder 账号
闪现在 opencode 卡片下的渲染竞态。
* channels request_end hook：挂接丢失的 isModelGone/recordDeadModel ——
真实 404（如 codearts GLM-5.3 "The model is not registered"）现在会进
deadModels，不再每轮 404 仍可选中。
2026-10-19 22:32:18 +08:00
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
