dsh-connect-agnes-token-plan 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -23,6 +23,75 @@
 
 ## [Unreleased]
 
+## [0.12.0] — 2026-10-18
+
+本版两条主线：**AgnesCode 一侧把平台的账真正透出来**——面板多三行（平台额度 / 限流记录 / 账户流水），输出上限还能按模型自己定；以及**对话框胶囊从一枚读数变成可点开的明细卡**，积分额度 tab 的用量图同时按平台的 7 天配额周期分组。
+
+另有几处「不再沉默」的修复：凭据过期、推理 Key 被平台拒绝时面板都会明说，而不是只在聊天里冒一个 401；平台拒绝时后台目录检查改为逐次退避，不再每 30 秒重试一次；「近 30 天消耗」没数完时按下限措辞呈现；出图工具要 base64 时真的拿得到图。
+
+### 修复：AgnesCode 积分「近 30 天」不再把没数完的数当成精确值
+
+- **修（面板 + 胶囊）**：AgnesCode tab 与对话框用量胶囊上的「近 30 天消耗」，在账号近期流水**超过插件一次最多采的 500 条**、且上游没回总条数时，以前会当成**已数完**、直接报一个精确数字——而这个数字只是最近若干条的合计，实际消耗可能更多。现在这种「采到上限但没确认数完」的情况会明确标成「至少」下限，跟你自己在桌面 App 里核对到的差额对得上时才不留误导。账目短、或上游回了总条数并已数完的，照旧报精确值、不加「至少」。
+- 内部：`covered30d` 判定收紧（仅「短页收尾」或「总条数已数完」算证明确已数完，踩到页预算上限本身不算），回归用例见 `test/agnescode-ledger.test.mjs` §6。
+
+### 修复：关掉面板后模型目录不再停止更新
+
+- **修（Host）**：模型目录（`/v1/models`）以前只在你打开面板、或页面轮询时才会去取，所以**面板一关，平台新上的模型就不再出现**，要重启 DSH 才能看到。现在插件自己按面板的刷新节奏（默认 30 秒）检查一次，目录过期才真去取——关掉面板时最多每小时一次请求，面板开着时两边共用同一次取数，请求数不变。
+- **修（Host）**：两个窗口同时开着时，同一次目录变化可能被写盘两次、把 provider 重建两次。现在写入走同一条队列，一次变化只落一次。
+- **不影响**：没配推理 API Key 时后台零请求（目录本来就无处可取）；配置行写错时不会启动后台检查；停止插件时会先停掉这个节奏。
+
+### 修复：平台拒绝时不再每 30 秒重试一次
+
+- **修（Host）**：上面的后台检查遇到平台拒绝（401/403/5xx）时，以前会按刷新节奏一直重试——默认 30 秒一次，一小时 120 次、一天 2880 次，而且日志里一行都没有。现在按 30 秒起、逐次翻倍、最长 15 分钟退避，稳定后每小时 4 次；第一次失败会记一行日志，恢复时再记一行。
+
+### 修复：出图工具要 base64 时拿不到图
+
+- **修（出图工具）**：`return_base64: true` 以前会拿到一句「请把 base64 图片展示出来」，但**图本身没有传回来**——平台返回的 base64 在工具结果里被丢掉了。现在载荷以 `data:image/png;base64,…` 放在结果的 `url` 字段里，真的能拿到。注意它会计入对话上下文（2K 图是几 MB 文本），不需要字节时别开这个参数。
+
+### 修复：AgnesCode 凭据过期时会明说
+
+- **修（面板）**：凭据过期以前只显示一个过去的日期，灰色小字，和有效时长得一样——唯一的症状是聊天里冒出一个 401。现在日期标红并写「已过期」，下面一行说明该做什么（重开桌面 App 登录一次，下一次请求自动重采集）。
+
+### 修复：推理 Key 被平台拒绝时，面板会说了
+
+- **修（面板 + Host）**：API Key 被吊销、轮换或填成另一个账号的 Key 时，面板以前一直显示「已配置」，模型清单也还在——唯一的症状是聊天里冒出一个 401。原因是唯一真正用到这把 Key 的读（模型目录）失败后被静默吞掉了。现在快照的 `llm` 块多一个 `catalogError`（含 `code`）：401/403 归类为 `KEY_REJECTED`，面板在 Key 卡上用醒目的一行说明「平台拒绝了这把 Key」，并保留「已配置」那一行（Key 确实还存着）；其他目录故障只作灰色备注，因为 Key 可能没问题。
+- **不影响**：目录读失败仍是软失败——额度、积分、AgnesCode 两个 tab 照常工作，快照仍然 `ok: true`。
+
+### 文档更正：AgnesCode 续期不需要再点按钮
+
+- **更正**：此前文档说 JWT 过期后「必须重开桌面 App、再点『检测本机登录态』」。实际**重采集是自动的**：过期后下一次请求会自己重读会话文件，你只要让桌面 App 重新登录一次即可；那个按钮用于主动触发和查看分诊结果，不是必须步骤。令牌本身仍然不会被续期（上游没有刷新端点）。
+- 内部：定时器与写入器在 `catalog-refresh.ts`，账本见 `docs/ADR.md` ADR-015。
+
+### 新增：用量图按 7 天配额周期分组——浅色背景带 + 每周请求合计
+
+- **新增（积分额度 tab）**：日用量柱状图现在按平台的 7 天配额周期分组：同一周期的日子共享一层浅色背景带，带上标出该周的请求合计，鼠标悬停可见周期起止日期；每日柱子与柱顶的次数保持不变。分组边界从平台公布的周窗口重置时间倒推，无需配置。平台没给重置时间时，图表回到原来的纯按日形态，不做日历周猜测。
+
+### 修复：评审整改五项——/agnescode 读放大、subscription 形状漂移盲区、内置花名册不标日期、Windows 边界不点不明
+
+- **修（Host，读放大）**：`/agnescode` 的 GET 此前每次轮询都实打实打两次 BFF（余额 + 目录），自愈发布再打第三次；tab 与用量胶囊各按 60 秒轮询同一个路由，读放大随读者数翻倍。现在这两次读走**按账号键控的缓存 + 单飞**（60 秒 TTL，与轮询同节奏）：tab 与胶囊共享同一次上游读，失败（null）答案**不缓存**——瞬时故障不会被冻成整整一分钟「暂无数据」。键含账号指纹（SHA-256 截断，令牌原文不进键），换账号自动失效。
+- **修（Host，盲区）**：`subscription` 源的形状漂移（`plan_name` / `billing_cycle` 改名）此前不挂 `shapeWarnings`——`EXPECTED_SHAPES` 声明了第三档却没人读它，套餐卡片会永远渲染成空而没有任何警告。PITFALLS §12 一直声称三档都报。
+- **修（Host + 面板，可标日期的价格）**：内置备份花名册生效时（实时目录取不到），面板明说「倍率截至 {日期}」——`modelsSource: "live" | "fallback"` + `modelsAsOf`（扁平标量），冻结价格不再被当成实时价呈现。日期单一出处 `AGNESCODE_FALLBACK_ASOF`。
+- **修（面板 + README，边界前置）**：「本机登录态采集仅支持 Windows」写进未关联卡片（点击前就能看到，而非点完只收到一行 `unsupported_platform` 分诊）与 README AgnesCode 段第 4 条。
+- **修（账实不符三处）**：`oneFailure` 的 JSDoc 写的是 `firstFailure` 的签名（参数表从未匹配过实现）；AGENTS.md 事实 2 漏了 `agnes_video_generate`（工具真实存在）；`decodeAgnescodeJwtExpMs` 与 `readJwtExpiry` 是同一问题的两份实现（JWT exp 解码），合并为后者 + `?? undefined` 语义适配。
+- 影响面：`src/host/{routes/agnescode,agnescode,snapshot-aggregate,types,index}.ts`、`src/client/{agnescode-tab,wire,i18n}.ts`、`client.js`、README、AGENTS.md、`test/{agnescode,contract,panel,docs}.test.mjs`。
+
+### 新增：点击用量胶囊打开明细小卡
+
+- **新增（用量胶囊）**：输入框右侧的用量胶囊以前只画读数，读不到细节。现在点开会一张小卡：控制台模型一侧是 5 小时 / 本周的百分比读数与「最近读取」时间；AgnesCode 模型一侧是积分余额及时效 / 常存拆分，下方附平台额度、限流记录、账户流水三行（见下条）。卡片点外部或按 Esc 关闭；同一页挂着多颗胶囊时各开各的，互不关闭、互不抢焦点。
+
+### 新增：AgnesCode 面板多三行——平台额度、限流记录、账户流水
+
+- **新增（AgnesCode tab + 用量胶囊）**：池三卡（余额 / 拆分 / 明细）下方多三行说明：
+  - **平台额度**：平台公布的 `daily_free_credits` / `subscription_credits` / `daily_effect_quota` / `effect_quota_balance` 四项。本机免费账号四项全 0——没有隐藏的每日免费额度，真正的限制是 RPM 限频（面板不猜阈值，只呈现已公布事实）。
+  - **限流记录**：本插件自身请求今日 / 近 30 天撞限次数与最近一次时间。只记症状、不反推限流阈值；桌面 App 的份额不计（平台没有按 token 的可读口径，本地自记会严重低估）。
+  - **账户流水**：本账号今日 / 近 30 天的积分出入合计，**含桌面 App 的份额**——这是本地自记给不出的口径。取不尽时「近 30 天出 **至少** N」按下限措辞呈现，不写死。
+  - 流水的明细描述只在 Host 侧读，永不出现在面板、日志或磁盘上。
+
+### 新增：AgnesCode 按模型自定义输出上限（`maxTokensOverrides`）
+
+- **新增（配置）**：`maxTokensOverrides` 按**精确模型名**（不匹配子串）给 AgnesCode 路由逐模型设置请求里带出去的输出上限。优先级：这份配置 > 平台实报值 > 内置兜底表同模型行 > 宿主默认。面板「最大输出」徽章与请求实际带的数走同一个解析——你看到的数就是发出去的数。
+- **为什么只有 AgnesCode 有这一位**：这条路由的上限受按账号 BFF 影响，会话轮换可能报出不同的表，平台报低了时本地没有别的真能纠正它，只有你知道实情。姊妹路由 `agnes-token-plan` 的上限是全平台探针验证过的（65536、请求恒带），在那边开放覆盖只会让你填一个平台已被证明会拒的数——所以没有。
+
 ## [0.11.2] — 2026-10-17
 
 ### 修复：AgnesCode 写操作不再被在途的读盖回、胶囊在后台页面上不再轮询

package/README.md

@@ -50,7 +50,9 @@
 
 1. **接口地址**：写在会话文件里、**按账号跟随**，钉死在 Agnes 域名族内，地址不对就拒绝使用；
 2. **显示口径**：积分是**订阅池**（时效 + 永久）；模型清单带「会员」标记而不隐藏——会员门槛是账号状态，不是模型不存在；
-3. **约 28 天续期一次**：JWT 过期后没有自动路径，开一次桌面 App、再点「检测本机登录态」重新采集即可。
+3. **约 28 天续期一次**：JWT 过期后没有续期端点，**重采集是自动的**——让桌面 App 重新登录一次，下一次请求就会自己重读会话文件；tab 里的「检测本机登录态」是主动触发（能看分诊结果），不是必须步骤；
+4. **本机登录态采集仅支持 Windows**：macOS / Linux 的采集路径未实现（面板里也会这么提示）；
+5. **读的是桌面 App 的登录态，不是本插件的账号**：插件只读、从不写回那个会话文件，也**没有「登出」按钮**——关开关只是停用（已存的令牌还在，重新打开即可复用）；要真正吊销，请在桌面 App 里登出或改密码。授权与撤销都在 App 那一侧，本插件不代劳（详见 [docs/SETUP.md](docs/SETUP.md) §3）。
 
 协议探针记录见 [docs/ROADMAP.md](docs/ROADMAP.md) §6.3。
 
@@ -60,7 +62,7 @@
 
 ## 对话框用量胶囊（自动出现）
 
-输入框右侧会出现一枚用量胶囊，**画哪条上游的额度由当前会话选中的模型决定**，前缀写明是谁的：选中 `agnes-token-plan` 的模型显示控制台的 **5 小时 / 本周**已用百分比（前缀 `Token Plan`）；选中 `agnescode`（桌面端）的模型显示那套**积分余额**（前缀 `AgnesCode`）。圆点分级（绿 / 黄 / 红 / 灰），余下的细节——重置时刻、账号昵称与时效 / 永久拆分、以及「为什么没有数字」——都在悬停提示里。
+输入框右侧会出现一枚用量胶囊，**画哪条上游的额度由当前会话选中的模型决定**，前缀写明是谁的：选中 `agnes-token-plan` 的模型显示控制台的 **5 小时 / 本周**已用百分比（前缀 `Token Plan`）；选中 `agnescode`（桌面端）的模型显示那套**积分余额**（前缀 `AgnesCode`）。圆点分级（绿 / 黄 / 红 / 灰）。点开余额胶囊是一张**只看关键数的卡**：余额、时效 / 永久拆分，加一行**「经本插件」今日调用次数与 token 用量**（只算经本插件 agnescode provider 的请求，不含桌面 App，也不冒充账号总量），以及「为什么没有数字」；账号昵称、平台发放、限流记录、账户流水这些**深记录都留在 AgnesCode tab**，不塞进这枚 28px 的胶囊。
 
 - 读数与面板**同源**：控制台百分比优先用平台自己报的 `usage_pct`、缺失才回落 `已用 / 上限`，**不做钳制**（超额窗口就显示 >100%，那是事实）；桌面端画的是**存量**，所以**不造百分比**——网关只公布积分，没有「上限」可以当分母；
 - 两条上游**互不借用**：`agnescode` 的会话只读它自己的路由、绝不画控制台窗口，反之亦然；切到**别的 provider**（其它插件）的模型时胶囊直接消失，也不再发任何请求；
@@ -112,7 +114,7 @@ npm run doctor:json     # 机器读：JSON（可进你的巡检 / 工单脚本
 - [docs/API.md](docs/API.md) — 路由与控制台端点
 - [docs/AGNES-API.md](docs/AGNES-API.md) — Agnes 接口全集（控制台额度侧 + 推理侧）
 - [docs/TESTING.md](docs/TESTING.md) — 测试体系
-- [docs/PITFALLS.md](docs/PITFALLS.md) — 真实踩坑（56 条）
+- [docs/PITFALLS.md](docs/PITFALLS.md) — 真实踩坑（57 条）
 - [CHANGELOG.md](CHANGELOG.md) — 版本变化
 
 AI 协作会话请先读 [AGENTS.md](AGENTS.md)。人类贡献者先读 [SETUP.md](docs/SETUP.md) 与 [ARCHITECTURE.md](docs/ARCHITECTURE.md) §2 理解结构与改动代价，改代码前再读 [AGENTS.md](AGENTS.md) 的红线与 [TESTING.md](docs/TESTING.md) 的 `npm test` 门禁。