dsh-connect-agnes-token-plan 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 本文件只记**公开行为变化**（新增能力、破坏性改动、重要修复）。实现细节、重构与测试加固请直接看 `git log`。
 
+## [0.10.1] — 2026-10-06
+
+### 修复：AgnesCode 截图里的真实账号昵称已脱敏（该图曾随 0.10.0 发布）
+
+- **修（资产泄漏）：`assets/panel-AgnesCode.png` 此前把面板上的真实关联账号昵称原样截进了市场页截图**——面板那一行渲染的是登录账号的昵称字段（`i18n` 的 `agnescode.loggedIn` 槽位 `已关联：{nick}`），截图取景时该值未做任何遮挡。昵称指向的是一个真实账号，**这不是示例数据**，因此 0.10.0 的 tarball 里那张图等同于把该账号名随包分发。图已重截，该行改为中性占位文案，账号名不再出现在任何像素里。
+- **这是 0.10.1 头号动机，优先级高于本节其余条目**：0.10.0 已发布且**不可覆盖**（npm 同版本号唯一，`unpublish` 后同号也不可复用），所以修复只能随新版本到达用户——这也是本版应当尽快发布的原因。
+- **处置边界要说清，避免误判风险面**：泄漏面**仅此一个二进制资源**。已核对 0.10.0 tarball 内全部文本类文件（`.md` / `.json` / `.yml`），账号名**无任何文本残留**；其余两张截图不含账号名。本仓红线条目（凭据不入库、错误文本脱敏）针对的是凭据与令牌，昵称属个人信息、不在凭据服务内，故**不触发凭据层面的处置流程**，但仍按泄漏修掉。
+- **`screenshots.json` 与文件名未变**：只换了图片内容，未增删文件，因此市场页的清单与 `files` 白名单不需跟着改（`files` 含 `assets`，重截自动随包发布）。
+- 影响面：`assets/panel-AgnesCode.png`（仅此一个文件，无代码改动）。
+
+### 登录表单服从 Host 下发的节流窗口：刷新页面不再让按钮在锁定期内可点
+
+- **修：跨进程 / 跨 profile 的锁定期内在面板上按一次就可能撞锁**。登录节流写在插件自己的 `throttle.json` 里，**机器级共享**（desktop profile 吃到的 429，在 web profile 的 Host 上同样真实），而 Host 一直把「剩余窗口」与「已停车」两个事实下发到快照的 `auth` 块。面板此前**不读它们**：倒计时从组件本地 state 起步，只有本进程那次登录失败才会被填上。刷新页面、换 profile、换 Host 进程这三种再正常不过的操作，都会让提交按钮在一个 Host 仍在服务的窗口里显示为可用——而 `POST /account` 是**刻意**清节流的（理由是「用户是在按面板的指示操作」），那次点击于是不止白费：它抹掉另一个进程正在遵守的记录，并把一次真实尝试打进可能已锁的账号。倒计时现由 `servedWaitMs` 判定、`servedWaitUntil` 换算，表单用前者播种并单调吸收后续窗口（只延后不缩短，避免把读者已在等的窗口提前解锁）。
+- **新增：已停车（`needsUserAction`）时给一句话而不是倒计时**。错密码、需人工验证、自造退避用尽这三类拒绝**没有**可等待的期限——倒计时数到零不会有任何东西重试，所以那个数字是撒谎。面板现在明说「已停止自动重试，请核对账号与密码后手动登录」并保持提交按钮可用（重新输入才是出路），与 `auth.locked`（平台说账号本身被锁）分作两句。
+- **修：验证码类拒绝会同时渲染两句矛盾的话**。`POST /account` 的失败体在「平台给了 `Retry-After`」时会同时带一个整段窗口与 `needsUserAction: true`，于是旧渲染路径上「已停止自动重试」与一个两小时倒计时同时出现。`submit` 现在让 parked 优先于窗口——`AccountForm` 与 `snapshot.ts` 的规则同源，此前只有后者。
+- **`API.md` 补上 `auth` 块两个节流字段的契约**（单位是**剩余**毫秒不是整段窗口；parked 时不许倒计时；面板必须服从它们而非只认自己那次失败），`AUTH.md` §7 与 `ARCHITECTURE.md` §3 数据流图同步接入。字段此前只有两个 JSON 值、没有任何语义说明，按字面读会把「parked 也倒计时」这类 bug 写出来。
+- 影响面：`src/client/{snapshot,account-form,i18n}.ts`、`test/{panel.test.mjs,panel-decision.js}`、`docs/{API,AUTH,ARCHITECTURE,ADR}.md`、`docs/PITFALLS.md`（新增 §52–§54）、`docs/ADR.md`（新增 ADR-010）、`client.js`（重建产物）。`lib/` 未改——本次全部改动在 client 半边。
+
+### 插件卡补上图标：Plugins 页不再裸显示包名 + 一段英文
+
+- **新增 `icon.svg`**（`icon: "./icon.svg"`）：Plugins 页的插件卡此前只有文字，卡片图标由 DSH Host 读 `package.json` 的 `icon` 字段渲染——不提供就缺一块。沿用面板的「积分币」母题（渐变圆盘 + 白色记数笔画），配色对齐本插件自己的品牌蓝 `--agnes-brand`（#1E40AF），与面板开关 / tab 下边框 / 额度进度条同一套 token，不跟 DSH 的中性色走。几何与兄弟插件 `dsh-connect-sensenova-token-plan` 保持一致，避免同系列插件卡片形态各异。
+- **读取端是硬校验，不是降级**：`icon` 必须是相对路径、扩展名限 SVG/PNG/JPEG/WebP、文件必须落在 `files` 白名单目录内、体积 ≤256 KiB——任一不满足会让整条插件元数据报错（该经验的出处是 `dsh-connect-sensenova-token-plan` CHANGELOG 0.4.4，已写进 `docs/PITFALLS.md` §27）。因此 `icon.svg` 同时进 `files` 白名单，`exports` 无需新增子路径（图标由 Host 直接按仓库路径读，不走包导出）。
+- 影响面：`icon.svg`、`package.json`、`docs/DSH-PLUGIN.md`（教学快照同步 `icon` 字段与 `files` 数组）。
+
+### 评审整改：红线④文档措辞更正 + 新增 ADR-012「大统一」爆炸半径权衡
+
+- **修（文档 / 红线④）：`AGENTS.md` 红线④称「`AUTH_DEFAULTS.consoleOrigin` 是唯一出处」与代码不符**。代码里后端源站字面量实际有两处——`agnes-auth.ts:47` 的 `AUTH_DEFAULTS.consoleOrigin` 与 `host-config.ts:41` 的 `CONFIG_DEFAULTS.consoleBase`——两者值一致，且由 `host-config.ts:323`（`resolveAuthOverrides` 在 `:384` 以 `consoleOrigin: consoleBase` 汇流）合并为单一 `consoleOrigin`，运行时是一条源、非漂移 bug。红线④现改为「两处字面量一致、配置边界汇流为单一 `consoleOrigin`，别写第三处也别让两处分叉」。
+- **新增（决策账本）：`ADR-012` 把「大统一」的结构性爆炸半径列为已知权衡**。ADR-001 把额度面板升级为商汤全过程集成单点入口；实测同进程现承载 LLM provider 注册、出图执行、视频异步状态机，以及解密第三方桌面端 AgnesCode 的 os_crypt/DPAPI 会话文件（攻击面最敏感的一块）。隔离纪律真实（agnescode 与主线 publisher 共用 `publish-core.ts` 机制、不共用状态；`kind:"grant"` 单点构造/判定；throttle 与凭据 grant 刻意共享不统一），但结构性爆炸半径被重新集中——这正是对 PITFALLS §6「私有状态误进凭据服务会炸整台机器」那次教训的现代重演形态。判定：属设计张力非缺陷；主动缓解是 §5 不变量（五源软失败 / 一个模块缺席不埋别的模块）与 ADR-005 准入门槛 + 拆分蓝图把结构债从事后锐评变事前决策点。
+- 影响面：`AGENTS.md`（红线④措辞）、`docs/ADR.md`（新增 ADR-012）、本文件。
+
+### 评审整改（续）：ADR-012 债务控制阀落地为可执行术前自查
+
+- **把 ADR-012 的「债务控制阀」从账本里的已知权衡变成吸收决策的实际闸门**。原条目只说「后续新能力吸收先对照这条」，现在钉死成 ADR-005「申报容器」步骤里必填的一张**爆炸半径对照表**——四问：① 承重面归类（落在四类既有承重面之一，还是引入第五类共享承重面 → 自动触发拆分蓝图）；② 新增共享状态（写盘 / 凭据引用 / 解密密钥访问是否复用既有机制，不得新开 state 窝点又不走蓝图）；③ 失败域边界（会不会撞 ADR-004/007「一个模块缺席不许埋掉别的模块」）；④ 基线可冻结（行为基线能否写进 store/routes 测试）。四问任一命中「引入新承重面 / 新 state 窝点 / 失败域外溢 / 基线不可冻」，先回 ADR-005 拆分蓝图或降级改造，而非带债落地。
+- 影响面：`docs/ADR.md`（ADR-012 债务控制阀段扩充）、本文件。
+
+## [0.10.0] — 2026-10-04
+
+### AgnesCode 目录改读 `/v2/models`：模型名带上平台真实的积分倍率与促销标
+
+- **目录端点从 `/v1/models` 换到 `{origin}/v2/models`**：两者是同一 host 上的**两条不同目录**，不是同一份数据——v1 只有 8 行且**不带任何按模型价格**，v2 有 9 行且其中 8 行带平台自己的 `points_cost_multiplier`。桌面端一直读 v2，这就是它的选择器能显示 `1.20x` / `1.85x` 而本插件此前什么都不显示的原因。此前的结论「AgnesCode 不存在按模型倍率」**是错的**，根因是端点选错（详见 `docs/ROADMAP.md` §6.3.1「倍率字段正记」）。
+- **模型显示名带上倍率 `Name · xNN.NN`**：pi-ai 的 descriptor 没有承载计费的字段（`cost` 是每 token 美元，本网关是积分制），所以倍率走**显示名**——这是 DSH 选择器唯一会渲染的表面。拼写沿用兄弟插件 `dsh-connect-sensenova-token-plan` 与 WorkBuddy 自有选择器既有的 `· x` 形态，**不引入第二套约定**。
+- **`0` 是已公布的价格（免费），不是缺失读数**：`×0.00` 与「未声明」是两件事，前者照常显示、后者才不画。为此新增 `numZeroOk()`——仓库既有的 `num()` / `numOrNull()` 都以 `> 0` 为准，直接复用会把「免费」静默变成「没读到」。
+- **面板花名册新增促销标芯片**（`display_label`，如 `限时七折`）：用桌面端同款蓝底配色，与中性灰底的「会员」徽章刻意区分——一个是**平台定价事实**，一个是**账号状态**。平台在**每一行**都放这个键、未促销的值为空串，因此判据是「非空才画」，而不是「键存在就画」。
+- **`auto` 行排除**：v2 多出的 `auto` 是路由别名而非模型（无价格、无厂商），按 id 显式排除；判据不取「没有倍率」，以免平台给它定价后它悄悄回到花名册。
+- **会员门槛字段随端点迁移**（`is_member_only` 布尔 → `allowed_subscription` 列表）：映射规则为「列表非空即会员」，已对 v1 逐行核对 **8/8 一致**，属**重新编码**而非重新解释。
+- **修：改价不触发重注册**（`catalogSignature` 现纳入倍率）。签名原先只编码 `id:vision`，而倍率已进显示名——`glm-5.2` 从 `1.85` 改到 `9.99` 时签名**完全相同**，选择器会一直显示旧倍率。平台在促销边界上确实会改价（`glm-5.2` 当前带 `限时七折`），所以这是会真实发生的路径。**操作者手填的伪倍率仍不触发重注册**（它在签名之后才挂上），原裁定不变。
+- **修：AgnesCode tab 在文档隐藏时停止轮询**（与 `PanelPage` 对齐），不再在后台空转。
+- **修：`render.test.mjs` 的午夜 flake**：`now + 1h` 在 23:00 之后跨到次日，而断言仍要求「同日」的裸时钟——每天 23:00–00:00 之间该门禁固定转红 1 项。改为按构造恒为当天的时刻。详见 `docs/PITFALLS.md` §48（与 §41「护栏的存活守卫自己漏了平台假设」同族，这次漏的是**时间**假设）。
+- **文档**：`docs/AGNES-API.md` §7.3 记入「单次 chat 请求图像上限 4 张」的 400 实测（官方文档未公示该上限）；`docs/PITFALLS.md` 新增 §48（午夜 flake）与 §49（`num()` 把「免费」塌成「未声明」）。
+- 影响面：`src/host/{agnescode.ts, agnescode-models.ts, provider-publish.ts, util.ts, routes/agnescode.ts}`、`src/client/{agnescode-tab.ts, wire.ts, styles.ts, i18n.ts}`、`test/{agnescode, publish-core, render, live-agnescode}`、`docs/{ROADMAP, AGNES-API, PITFALLS, TESTING}`。
+
 ## [0.9.0] — 2026-10-03
 
 ### UI：开关统一为项目品牌色，积分额度拆成三张卡片
@@ -47,6 +98,11 @@
 
 **AgnesCode 面板从「只读花名册」升级为「可勾选的模型推送给」**：每个模型一行勾选框，决定哪些模型注册进 DSH 模型列表，改动即时生效；配套搜索 + 全部勾选/取消 + 已勾选计数，与 Token Plan 那套同一形状。勾选存在独立的 profile 级状态文件，**空 = 不筛选 = 全推**，所以没勾过的安装行为完全不变。面板信息架构另有一刀（额度 / 累计 / 套餐拆成三个 section）。另修掉一个「删注释时误删三元条件行、构建失败、插件无法加载」的问题。
 
+### 评审整改：API.md §1 补上 `/agnescode` 的 `saveModels` 动作与 `enabledModelIds` 字段
+
+- **`/agnescode` 契约文档漏记已上线能力**：代码（`routes/agnescode.ts:248`、`lib/index.js`、`client.js`、`agnescode-tab.ts`、`agnescode.test.mjs`）早已实现第三个 POST 动作 `saveModels`（持久化花名册勾选并即时重发过滤后 roster），且 GET 响应含 `enabledModelIds` 推送允许清单，但 `docs/API.md` §1 仍写「POST 动作两种」、GET 形状也未列 `enabledModelIds`。本次把 POST 改为三种动作、GET 形状补 `enabledModelIds`，与 CHANGELOG「AgnesCode：模型勾选」那条及路由代码对齐。
+- 影响面：`docs/API.md`（§1 agnescode 块）、本文件。
+
 ### AgnesCode：模型勾选决定哪些模型推送进 DSH
 
 - **能力**：AgnesCode tab 的模型花名册每行加勾选框（未勾选行降低透明度），决定哪些模型注册进 DSH 模型列表；保存后**立刻**重发一次过滤后的 roster，不必等下一次轮询。
@@ -284,7 +340,7 @@
 ### 模型花名册重排（WorkBuddy 形态）
 
 - **行去卡内框、改用分隔线**：`modelRow` 由横向 flex 行改为纵向列（头行 + 缩进的参数行），新增 `modelRowHead` 包裹头行；徽章只标 notable 态（删「纯文本」徽章、补「额度耗尽」徽章）。工具行计数成组右置，批量按钮 32px 与搜索框等高。
-- **每行只留会变的 per-model 事实**：参数段从「上下文 · 最大输出 · 默认思考强度」改为**本模型实际可选档位**——「思考 关闭/低/中/高/极高[/最高]」，由 Host 新导出的 `supportedThinkingLevels` 按 pi-ai `getSupportedThinkingLevels` 同一规则过滤（与 DSH 选择器同源），glm-5.2 独显「最高」。provider 级常数（默认思考强度）收进花名册头部只说一次（`llm.rosterThinkingDefault`），**删掉逐行重复的恒定默认档**——用户锐评「恒定默认档逐行重复=噪音」，该反模式已记入 `docs/IMPROVEMENTS.md` §7。
+- **每行只留会变的 per-model 事实**：参数段从「上下文 · 最大输出 · 默认思考强度」改为**本模型实际可选档位**——「思考 关闭/低/中/高/极高[/最高]」，由 Host 新导出的 `supportedThinkingLevels` 按 pi-ai `getSupportedThinkingLevels` 同一规则过滤（与 DSH 选择器同源），glm-5.2 独显「最高」。provider 级常数（默认思考强度）收进花名册头部只说一次（`llm.rosterThinkingDefault`），**删掉逐行重复的恒定默认档**——用户锐评「恒定默认档逐行重复=噪音」，该反模式记于 `docs/ARCHIVE-IMPROVEMENTS-2026-09.md` §7（2026-10-05 归档）。
 - **`tokenSize` 修正 1049k → 1M**：千整走十进制、纯二进制走 1024、≥1M 归 M。Host 侧新增 `maxOutputLength` 投影（`0` = 未声明则整段不画，绝不猜）。
 - **`matchMultiplier` 单一匹配器**：趋势行 ×N 与花名册 ×N 同源同值，两处显示不可能不一致。
 
@@ -405,7 +461,7 @@ Token Plan 与小浣熊同为商汤旗下产品线，`sensenova` 这个名头名
 
 ### 文档修正：撤销 ROADMAP §0 被证伪的前提
 
-- [ROADMAP.md](docs/ROADMAP.md) §0 与 §2 引言原写「本插件已是双 profile 的 `agent-default-model`——即这台机器的**默认推理通道**，故障域已升级为推理可用性」。该论断 2026-09-29 已被 [IMPROVEMENTS.md](docs/IMPROVEMENTS.md) §1.2 撤销（`agent-default-model` 是宿主的选择记录服务，原引用不可复现），但 ROADMAP 未同步。现改为「**能力事实**：可注册 provider `sensenova-token-plan`；是否默认通道由 profile 与用户模型选择决定；一旦某 profile 选它作默认，故障域才从面板升级为推理可用性（条件性爆炸半径）」。两份文档不再正面矛盾。
+- [ROADMAP.md](docs/ROADMAP.md) §0 与 §2 引言原写「本插件已是双 profile 的 `agent-default-model`——即这台机器的**默认推理通道**，故障域已升级为推理可用性」。该论断 2026-09-29 已被研究原稿 §1.2 撤销（`agent-default-model` 是宿主的选择记录服务，原引用不可复现；撤销原文现见 [ARCHIVE-BOUNDARY-DECISIONS.md](docs/ARCHIVE-BOUNDARY-DECISIONS.md) A1），但 ROADMAP 未同步。现改为「**能力事实**：可注册 provider `sensenova-token-plan`；是否默认通道由 profile 与用户模型选择决定；一旦某 profile 选它作默认，故障域才从面板升级为推理可用性（条件性爆炸半径）」。两份文档不再正面矛盾。
 
 ### 文档与仓库纪律
 

package/README.md

@@ -1,77 +1,90 @@
 # dsh-connect-agnes-token-plan
 
-Agnes 接入的 DSH **Plugins 页**插件卡**全家桶**（三个 tab）：① **积分额度** tab——登录一次 Agnes 控制台，实时查看四类额度窗口与账号累计用量，令牌失效自动重登，之后无需再管；② **接入 API** tab——把 Agnes 模型注册为 DSH provider，参与对话与出图；③ **AgnesCode** tab（可选、默认关）——读取本机 AgnesCode 桌面端登录态接入桌面端上游。两条上游凭据相互独立。此外 429 自愈在后台生效：限频被误判为"额度耗尽"时在 Host 侧纠正回退避重试，模型不会无端消失。
+把 Agnes 接进 DSH 的 **Plugins 页**插件卡。**DSH** 即 **DeepSeek Harness**；**Agnes**（爱思）是全模态大模型平台，本插件对接其**控制台 API** 与**推理 API**。
 
-## 功能
 
-Agnes 的 Token Plan **按窗口限流**，不是积分余额——账号级四个维度各有上限，用超了只能等窗口滚过：
+> **第一次读这个仓库？先看这三句。**
+>
+> 1. **这是给 DeepSeek Harness 用的插件**，不是独立应用；所有入口都在 DSH 的 Plugins 页那张卡上（三个 tab，见下）。
+> 2. **三种「红」是正常的，不是回归**：① `test/wiring.test.mjs` 等 peer 套件报 `cannot resolve the peer dependency` —— 那是 DSH runtime 自带的包不在本仓库，属环境问题，先查 `test/peer-roots.mjs`；② 没装 `dsh` CLI 时 e2e 会 SKIP，属预期；③ 若在 **23:00–00:00** 之间单独跑 `render.test.mjs` 报红，那是历史上的午夜窗口缺陷（已在 0.10.0 修复，见 [docs/PITFALLS.md](docs/PITFALLS.md) §48），当前安装版本已含，无需升级。
+> 3. **见到「奇怪」的写法先别定罪**——本仓多数刻意的取舍都在 [docs/PITFALLS.md](docs/PITFALLS.md) / [docs/ADR.md](docs/ADR.md) 有明文出处。**动手前先 grep 一遍 docs/**。
+>
+> 协作会话的完整纪律见 [AGENTS.md](AGENTS.md)。
 
-| 维度 | 上限字段 | 窗口 |
-|---|---|---|
-| 模型请求 | `concurrency_limit` | `concurrency_window_h`（各档均为 5 小时） |
-| 每周请求 | `text_weekly_limit` | 168 小时 |
-| 生图 | `image_daily_limit` | 24 小时 |
-| 视频 | `video_daily_limit` | 24 小时 |
+- **积分额度**——登录一次，实时查看积分余额、额度窗口与每模型消耗，令牌自动续期，之后无需再管；
+- **接入 API**——把 Agnes 模型注册为 DSH provider，参与对话、出图与出视频；
+- **AgnesCode**——上游限流较宽松的另一条产品线（爱思办公桌面端），独立账号、独立积分。
 
-这个面板把数字搬进 DSH 的 Plugins 页，写代码时不用切网页就能盯住：
+面板分三个 tab，按「先看数、再接入、最后可选加桌面端上游」排序：
 
-- **额度窗口**：四个窗口的上限、周期与**平台报出的已用量**（`used / limit` 与百分比）。面板直接引用控制台自己的「当前用量」，进度条是逐字转写、不做减法；`usage_pct` 也是平台算好的
+## 积分额度
+
+将 Agnes 的 Token Plan 接入 DSH，用超了只能等窗口重置。这个 tab 把数字搬进 DSH，写代码时不用切网页就能盯住：
+
+- **额度窗口**：模型请求（5 小时滚动）、每周请求、生图与视频（各 24 小时），**平台报出已用量**、独立滚动，（含百分比与重置时间）
 - **账号累计用量**：控制台口径的累计请求 / 文本 Token / 生图 / 视频秒数 / 活跃天数，以及近 N 天的分桶柱图
-- **套餐对比**：平台**公开**的套餐目录（六档：入门版 / 专业版 / 高级版 × 月付 / 年付），无需登录即可读，用来回答"升级能买到什么"
-- **模型清单**：当前 Key 实际能调哪些模型，其中哪些能看图（按平台 `input_modalities` 判定，不靠名字猜）
-- **可选接入**：把 Agnes 模型接进 DSH 对话，思考强度可选；并可注册出图 / 视频工具
-- **桌面端上游（默认关）**：面板「AgnesCode」tab 读取本机 AgnesCode 桌面端的登录态，独立 provider 与独立积分池
+- **套餐对比**：平台**公开**的套餐目录（六档），无需登录即可读，用来回答"升级能买到什么"
 
-面板**不代你操作账务**：不改套餐、不代扣额度、不碰 Key 明文；数据来自 Agnes 控制台自己的 API，与网页控制台口径一致。真正会「动」的四部分——注册 provider、挂出图工具、挂视频工具、接入 AgnesCode 桌面端上游——全部 opt-in 且**默认关闭**，不打开时插件退化为纯信息展示。
+![「积分额度」tab](assets/panel-credit.png)
 
-**注册 provider 时**（面板开关打开），插件把 Agnes 模型接进 DSH 的对话模型选择器，并在 Host 侧纠正 peer 对限频 429 的误判（peer 的 `isQuotaExceededError` 命中面过宽，任何带额度措辞的 429——如 `out of rate budget`——都会被抢判成「额度耗尽」而不重试）——限频真正退避重试，模型不再无端 "消失"。
+首次使用在「连接 Agnes 控制台」填一次账号和密码（Agnes 不发 refresh token，续期就是自动重登一次）。登录失败时表单会直接显示 Agnes 返回的原因；密码错误属于**凭据型拒绝**，面板**绝不自动重试**（Agnes 有失败次数锁定）。想清除账号，用面板底部的按钮。
 
-## 安装
+## 接入 API（可选）
 
-1. 在 DSH「插件」页搜索 `dsh-connect-agnes-token-plan` 点击安装，或运行：
+把 Agnes 模型注册为 DSH provider，参与对话与出图。
 
-   ```powershell
-   dsh plugin --profile web add dsh-connect-agnes-token-plan       # Web 端
-   dsh plugin --profile desktop add dsh-connect-agnes-token-plan  # 桌面端
-   ```
+- **模型清单**：在「API Key」卡粘贴 Key 保存`AGNES_TOKEN_PLAN_API_KEY`，Host 以 `agnes-token-plan` 之名注册 OpenAI 兼容 provider，模型列表随 `/v1/models` 自动刷新；
+- **语言模型**：显示当前 Key 实际能调哪些模型，其中哪些能看图（按平台 `input_modalities` 判定，不靠名字猜）。
+- **出图工具**：Host 给 agent 注册 `agnes_draw_image` ，出图模型按 catalog 的 `output_modalities` 结构化判定。
+- **视频工具**：Host 给 agent 注册 `agnes_video_generate`，按选中模型分派 V2.0 / 2.5 两套互斥参数。
+- 开关与勾选都在面板热生效，无需重启。但工具的实际挂载 / 缺席发生在**下一次 Host 启动**（agent tools 没有 unregister 语义）。细节见 [docs/SETUP.md](docs/SETUP.md) §3、[docs/PROVIDER-HOT-RELOAD.md](docs/PROVIDER-HOT-RELOAD.md) 与 [docs/AGNES-API.md](docs/AGNES-API.md) §7.5。
 
-2. **完全退出 DSH（含托盘）再启动**。
+![「接入 API」tab](assets/panel-API-provider.png)
 
-> 装到的是哪一版由源决定：安装器会询问 profile 配的 registry，**默认含 `registry.npmmirror.com`，刚发布的版本在镜像上可能延迟几分钟**，官方源立即可用；要确认拿到了哪一版，对照 `npm view dsh-connect-agnes-token-plan version --registry=https://registry.npmjs.org`。三种 target 形态（npm 包名 / git 地址 / 本地路径）见 [docs/SETUP.md](docs/SETUP.md)。
+注意：`sk-` 走 API 按量计费，`cpk-` 走订阅配额（本 tab 只读订阅配额），两类 Key 有独立限制池，需从官网了解实际限制。
 
-## 快速开始
+## AgnesCode（可选，默认关）
 
-1. 打开 DSH 的 **Plugins 页**，找到 `dsh-connect-agnes-token-plan` 的插件卡（面板是页内的内联卡片，**不在侧边栏**）。
-2. 在「积分额度」tab 点「连接 Agnes 控制台」，填一次账号和密码，点登录。
-3. 之后令牌失效会自动重登（Agnes 不发 refresh token，续期的唯一路径就是重登一次），无需再操作。
+**读取 AgnesCode 桌面端** 留在本机的加密会话文件，获取登录态，再以 provider id `agnescode` 注册**独立** provider、独立积分池——两条上游凭据互不相通：
 
-登录失败时表单会直接显示 Agnes 返回的原因；密码错误属于**凭据型拒绝**，面板**绝不自动重试**（Agnes 有失败次数锁定），只有你主动点「登录」才会再发一次。想清除账号，用面板底部的按钮。
 
-## 它是怎么工作的
+1. **接口地址**：写在会话文件里、**按账号跟随**，钉死在 Agnes 域名族内，地址不对就拒绝使用；
+2. **显示口径**：积分是**订阅池**（时效 + 永久）；模型清单带「会员」标记而不隐藏——会员门槛是账号状态，不是模型不存在；
+3. **约 28 天续期一次**：JWT 过期后没有自动路径，开一次桌面 App、再点「检测本机登录态」重新采集即可。
 
-登录原理一句话：Host 在后台向 `{consoleBase}/api/user/login` 发**一次**账号密码 POST 换取 access token（Agnes 没有 OIDC 跳转、没有 refresh token），令牌过期或被拒时用同一路径**重登一次**；面板打开时才轮询一个只读本地路由，关掉即停。协议细节（一跳登录、密码明文过 TLS 与「不落盘」纪律、防锁号节流）见 [docs/AUTH.md](docs/AUTH.md)，接口契约见 [docs/AGNES-API.md](docs/AGNES-API.md)。
+协议探针记录见 [docs/ROADMAP.md](docs/ROADMAP.md) §6.3。
 
-**窗口「已用」是平台报出的，面板不计算**：`/api/cn/user/subscription` 直接返回每个窗口的 `used` / `limit` / `reset_at` / `usage_pct`（控制台「当前用量」那一屏的数据源），面板逐字转写并渲染进度条。但 `overview` / `series` 是**账号累计**口径，覆盖的是一段更长的时间——**不能用它去减窗口上限**，那个「剩余」跨周期、没人能担保，所以面板把「窗口用量」与「账号累计」作为两个独立事实并排显示，并明说不可相减。
+![AgnesCode tab](assets/panel-AgnesCode.png)
 
-## 把 Agnes 模型接进 DSH（可选）
+注意：检测不到登录态时，面板会逐条列出探测过哪些文件、各自为什么没成（「没装 App」「解不开密」「会话里没有令牌」是三种不同的处理）；
 
-「接入 API」tab 的三张卡按"你为什么来这"排序，而不是按依赖排序：**语言模型**（注册 provider + 勾选推送哪些模型）、**出图工具**——两张都在最前且默认展开；**API Key** 收在最后（默认收起），它是前两张卡的前置条件，由它们指回来。
+## 边界
 
-在「API Key」卡里粘贴 API Key 保存（免费版 `sk-` 或 Token Plan `cpk-` 皆可）：Host 即以 `agnes-token-plan` 之名注册 OpenAI 兼容 provider，模型列表随 `/v1/models` 自动刷新，还能在「语言模型」卡勾选具体要推送哪些模型。Key 只进 DSH 凭据（引用名 `AGNES_TOKEN_PLAN_API_KEY`）、面板永不回显。开关与勾选都在面板热生效，无需重启。细节见 [docs/SETUP.md](docs/SETUP.md) §3 与 [docs/PROVIDER-HOT-RELOAD.md](docs/PROVIDER-HOT-RELOAD.md)。
+- 面板**不代你操作账务**——不改套餐、不代扣额度、不碰 Key 明文；数据来自 Agnes 控制台自己的 API，与网页控制台口径一致。
+- 注册 provider、挂出图工具、挂视频工具、接桌面端上游，全部 opt-in 且**默认关闭**；一个都不打开时，插件退化为纯信息展示。
 
-> **免费版与付费 Token Plan 共用同一个 API Key 输入框**：`sk-`（免费版）与 `cpk-`（Token Plan）两类 Key 都走同一份 `/v1/models` 目录，本插件对前缀不做限制。**计费双轨**——`sk-` 走 API 按 token / 张 / 秒计费（`agnes-2.5-flash` / `agnes-3.0-flash` / 图片模型当前优惠价 `$0`，`agnes-2.5-pro` 按刊例价），`cpk-` 走 Token Plan 订阅配额（四窗口）。面板「积分额度」tab 只读**订阅配额**，不读 API 按量余额；两类 Key 使用**独立限制池**，换 Key 即换池。两者都能在此粘贴。
+## 安装
+
+1. 在 DSH「插件」页搜索 `dsh-connect-agnes-token-plan` 点击安装，或运行：
+
+   ```bash
+   dsh plugin --profile web add dsh-connect-agnes-token-plan       # Web 端
+   dsh plugin --profile desktop add dsh-connect-agnes-token-plan  # 桌面端
+   ```
 
-## 出图工具（可选，默认关）
+2. **完全退出 DSH（含托盘）再启动**。
 
-面板「出图工具」卡（在「语言模型」下方，默认展开）打开开关后，Host 给 agent 注册工具 `agnes_draw_image`（首选模型由 `drawModelId` 指定），鉴权走同一把 `AGNES_TOKEN_PLAN_API_KEY`。出图模型优先按 catalog 的 `output_modalities` 结构化判定，该字段在 Agnes 目录上**缺失**时退回模型名里的 `image` 段（名字兜底才是实际命中的路径）。注意：工具的实际挂载 / 缺席发生在**下一次 Host 启动**（agent tools 没有 unregister 语义），开关值本身立即生效。
+3. 打开 DSH 的 **Plugins 页**，找到 `dsh-connect-agnes-token-plan` 的插件卡（面板是页内的内联卡片，**不在侧边栏**）。
 
-## 视频工具（可选，默认关）
+> 装到的是哪一版由源决定：安装器会询问 profile 配的 registry，**默认含 `registry.npmmirror.com`，刚发布的版本在镜像上可能延迟几分钟**，官方源立即可用；要确认拿到了哪一版，对照 `npm view dsh-connect-agnes-token-plan version --registry=https://registry.npmjs.org`。三种 target 形态（npm 包名 / git 地址 / 本地路径）见 [docs/SETUP.md](docs/SETUP.md)。
 
-面板「视频工具」卡（在「出图工具」下方，默认展开）打开开关后，Host 给 agent 注册工具 `agnes_video_generate`（首选模型由 `videoModelId` 指定），鉴权同样走 `AGNES_TOKEN_PLAN_API_KEY`。与出图**不同**的是协议：图片一次请求同步返回，视频是**异步任务制**——建任务后轮询到完成。**V2.0 与 2.5 两个参数体系都覆盖**，工具按选中模型分派请求体：V2.0（`agnes-video-v2.0`）走 `width`/`height`/`num_frames`/`frame_rate`，2.5（`agnes-video-2.5` / `agnes-video-2.5-flash`）走 `mode`/`seconds`/`size`/`aspect_ratio`。两套字段互斥、永不同时发给同一模型，但处理是**不对称**的：V2.0 帧数字段发到 2.5 模型会被换算成最接近的整秒（`121 @ 24fps → 5s`），保留「不判断家族也能出片」的退路；反过来，2.5 专有字段发到 V2.0 模型会**当场报错并给出修法**——工具不会静默丢弃，丢弃等于让你以为拿到 10 秒 2K、实际拿到 5 秒 720P。自动选择优先 V2.0，目录里没有 V2.0 时回落第一个 2.5 模型；面板仍会把 2.5 家族单独点名。协议细节与校验规则见 [docs/AGNES-API.md](docs/AGNES-API.md) §7.5。
+## 它是怎么工作的
 
-## 桌面端上游：AgnesCode（可选，默认关）
+登录原理：
+- Host 在后台向 `{consoleBase}/api/user/login` 发**一次**账号密码 POST 换取 access token（Agnes 没有 OIDC 跳转、没有 refresh token），令牌过期或被拒时用同一路径**重登一次**；
+- `/api/cn/user/subscription` 直接返回每个窗口的 `used` / `limit` / `reset_at` / `usage_pct`（控制台「当前用量」那一屏的数据源），面板逐字转写、不做减法。下方的「账号累计用量」统计同理，
+- 面板打开时才轮询一个只读本地路由，关掉即停。协议细节（一跳登录、密码明文过 TLS 与「不落盘」纪律、防锁号节流）见 [docs/AUTH.md](docs/AUTH.md)，接口契约见 [docs/AGNES-API.md](docs/AGNES-API.md)。
 
-面板「AgnesCode」tab 接的是 **AgnesCode 桌面端**的登录态：微信扫码发生在桌面 App 里，本插件只**读取** App 留在本机的加密会话文件（Chromium os_crypt，密钥经系统 DPAPI 解封，全程内存使用、不落盘不显示；解出的凭据随后存入 DSH 凭据服务，与账号密码同一纪律），并以 provider id `agnescode`（显示名 AgnesCode）注册**独立** provider。它的接口地址写在会话文件里、**按账号跟随**（钉死在 Agnes 域名族内，地址不对就拒绝使用）；显示的积分是**订阅池**口径（时效 + 永久），模型清单带「会员」标记（会员门槛是账号状态，不是模型不存在，所以标记而不隐藏）。检测不到登录态时，面板逐条列出**探测过哪些文件、各自为什么没成**——「没装 App」「解不开密」「会话里没有令牌」是三种不同的处理方式，不会笼统叫你重新登录。JWT 有效期约 28 天，过期后开一次桌面 App 再点「检测本机登录态」即可；协议探针记录见 [docs/ROADMAP.md](docs/ROADMAP.md) §6.3。
 
 ## 运维诊断：这台机器现在挂没挂 provider？
 
@@ -84,21 +97,21 @@ npm run doctor:json     # 机器读：JSON（可进你的巡检 / 工单脚本
 
 ## 文档
 
+- [docs/README.md](docs/README.md) — 全量文档索引（每篇按「内容 / 何时查」路由；本表只列主文档）
 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — 架构与数据流
 - [docs/SETUP.md](docs/SETUP.md) — 配置字段、改动后重启、常见信号
 - [docs/AUTH.md](docs/AUTH.md) — 登录 / 重登 / 节流设计
 - [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) — 真实踩坑（47 条）
+- [docs/PITFALLS.md](docs/PITFALLS.md) — 真实踩坑（55 条）
 - [CHANGELOG.md](CHANGELOG.md) — 版本变化
 
-AI 协作会话请先读 [AGENTS.md](AGENTS.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` 门禁。
 
 ## 诚实声明
 
 - 面板显示的是**控制台自己的口径**，与网页控制台一致；`GET /v1/models` 只区分权限，不计费也不占推理额度；
-- 窗口卡片里的「已用」是控制台报出的「当前用量」，面板逐字转写、不做减法；下方「账号累计」覆盖的是另一段时间，不能与窗口上限相减；
 - 令牌被拒时面板明确提示重新登录，而不是静默显示旧数据；
 - 凭据（账号、access token）只经 DSH 凭据服务保存，**密码不落盘**；本插件不写任何明文凭据文件或调试日志。
 

package/THIRD_PARTY_NOTICES.md

@@ -32,7 +32,7 @@
 
 `package.json` 的 `files` 打包清单（由 `test/package.test.mjs` 的 import 闭包检查钉住）**不包含任何第三方代码**：
 
-- `peerDependencies`（`react`、`@deepseek-ai/dsh`、`@deepseek-ai/dsh-credentials`）由 DSH Host 运行时在运行期提供，不随本插件安装或打包（见 `docs/DSH-PLUGIN.md` §2）；测试基建 `test/peer-roots.mjs` 就地解析它们，不引入新依赖；
+- `peerDependencies`（共 13 个，由 DSH Host 运行时在运行期提供，不随本插件安装或打包；见 `package.json` 的 `peerDependencies` 与 `docs/DSH-PLUGIN.md` §2）：`@deepseek-ai/cordis`、`@deepseek-ai/dsh-client-locale`、`@deepseek-ai/dsh-client-ui-layout`、`@deepseek-ai/dsh-client-ui-renderer`、`@deepseek-ai/dsh-credentials`、`@deepseek-ai/dsh-home-paths`、`@deepseek-ai/dsh-host-webserver`、`@deepseek-ai/dsh-llm`、`@deepseek-ai/dsh-llm-pi-ai`、`@deepseek-ai/dsh-settings`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/schemastery`、`@earendil-works/pi-ai`。其中 `@deepseek-ai/cordis` 在 `peerDependenciesMeta` 中标记为 optional。注意：**本插件不依赖 `react`**，也不依赖 `@deepseek-ai/dsh`（与旧文案不同）；测试基建 `test/peer-roots.mjs` 就地解析这些 peer，不引入新依赖；
 - `react` 为 MIT 许可；`@deepseek-ai/*` 属 DSH 运行时发行物，其许可证以 DSH 官方发行版为准；
 - `LICENSE` 与本文随包携带，但均为本项目自身文档。