dsh-connect-agnes-token-plan 0.13.0 → 0.13.1

package/CHANGELOG.md

@@ -23,6 +23,15 @@
 
 ## [Unreleased]
 
+## [0.13.1] — 2026-10-22
+
+本版只改一件事：**插件卡的标题**。中文叫「Agnes 模型接入」，英文叫「Agnes Model Access」，与「商汤模型接入」「魔搭模型接入」同构。
+
+### 变更：插件卡标题换成「Agnes 模型接入」
+
+- **改（插件卡·中英文界面）**：标题此前是「Agnes Token Plan 接入全家桶」——「接入全家桶」是内部叫法，英文那版「Agnes Token Plan Connect」也不是一句英文。现在中文叫「Agnes 模型接入」，英文叫「Agnes Model Access」，与同族插件一眼能对上。
+- **说明**：插件的包名与市场条目没有改（仍是 `dsh-connect-agnes-token-plan`），按旧名搜索照旧找得到；面板里的字也没动。
+
 ## [0.13.0] — 2026-10-21
 
 本版新增 **AgnesCode 扫码登录**：桌面端没装、没登录也能用这条线。另外修了促销标丢失、并发记录丢失、令牌被悄悄改写三处问题，并扩大了凭据脱敏面。

package/README.md

@@ -1,4 +1,22 @@
-# dsh-connect-agnes-token-plan
+<h1 align="center">dsh-connect-agnes-token-plan</h1>
+
+<p align="center"><b>把 Agnes（爱思）接进 DSH 的 Plugins 页插件卡，并在会话输入框常驻一枚用量胶囊。</b></p>
+
+<p align="center">
+  <a href="#安装">安装</a> ·
+  <a href="#它是怎么工作的">工作原理</a> ·
+  <a href="CHANGELOG.md">更新日志</a> ·
+  <a href="https://github.com/eghrhegpe/dsh-connect-agnes-token-plan/issues">问题反馈</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-connect-agnes-token-plan"><img src="https://img.shields.io/npm/v/dsh-connect-agnes-token-plan?style=flat-square&label=npm&color=cb3837" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/dsh-connect-agnes-token-plan"><img src="https://img.shields.io/npm/d18m/dsh-connect-agnes-token-plan?style=flat-square&label=downloads&color=cb3837" alt="npm downloads"></a>
+  <a href="https://github.com/eghrhegpe/dsh-connect-agnes-token-plan/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/eghrhegpe/dsh-connect-agnes-token-plan/ci.yml?branch=main&style=flat-square&label=tests" alt="test status"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/eghrhegpe/dsh-connect-agnes-token-plan?style=flat-square" alt="MIT license"></a>
+  <a href="https://github.com/eghrhegpe/dsh-connect-agnes-token-plan/stargazers"><img src="https://img.shields.io/github/stars/eghrhegpe/dsh-connect-agnes-token-plan?style=flat-square" alt="GitHub stars"></a>
+  <a href="https://dshfind.com/plugins/eghrhegpe/dsh-connect-agnes-token-plan"><img src="https://dshfind.com/api/badge/eghrhegpe/dsh-connect-agnes-token-plan" alt="dshfind plugin"></a>
+</p>
 
 把 Agnes 接进 DSH：**Plugins 页**的插件卡（三个 tab），外加**会话输入框右侧的一枚用量胶囊**。**DSH** 即 **DeepSeek Harness**；**Agnes**（爱思）是全模态大模型平台，本插件对接其**控制台 API** 与**推理 API**。
 
@@ -9,7 +27,7 @@
 > 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)。
+> 协作会话的完整纪律见 [AGENTS.md](https://github.com/eghrhegpe/dsh-connect-agnes-token-plan/blob/master/AGENTS.md)（**不随 npm 包发布**，registry 页面上请从 GitHub 打开）。
 
 - **积分额度**——登录后实时查看积分余额、额度窗口与每模型消耗；设了 `AGNES_PASSWORD` 则令牌到期自动重登，之后无需再管；
 - **接入 API**——把 Agnes 模型注册为 DSH provider，参与对话、出图与出视频；
@@ -111,15 +129,16 @@ npm run doctor:json     # 机器读：JSON（可进你的巡检 / 工单脚本
 
 - [docs/README.md](docs/README.md) — 全量文档索引（每篇按「内容 / 何时查」路由；本表只列主文档）
 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — 架构与数据流
-- [docs/SETUP.md](docs/SETUP.md) — 配置字段、改动后重启、常见信号
+- [docs/SETUP.md](docs/SETUP.md) — 配置字段、改动后重启
+- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.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) — 真实踩坑（61 条）
+- [docs/PITFALLS.md](docs/PITFALLS.md) — 真实踩坑（61 条；数字由 `docs.test.mjs` 的 `PITFALLS_REFS` 与文件内编号钉住）
 - [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` 门禁。
+AI 协作会话请先读 [AGENTS.md](https://github.com/eghrhegpe/dsh-connect-agnes-token-plan/blob/master/AGENTS.md)（在仓库里，**不在 npm 包里**）。人类贡献者先读 [SETUP.md](docs/SETUP.md) 与 [ARCHITECTURE.md](docs/ARCHITECTURE.md) §2 理解结构与改动代价，改代码前再读 `AGENTS.md` 的红线与 [TESTING.md](docs/TESTING.md) 的 `npm test` 门禁。
 
 ## 诚实声明
 

package/docs/DSH-PLUGIN.md

@@ -25,7 +25,7 @@ DSH 插件是一段在 **Host**（桌面版或 `dsh web`）进程内运行的代
 {
   "name": "dsh-connect-agnes-token-plan",
   "icon": "./icon.svg",                  // Plugins 页插件卡图标：Host 读此字段按 SVG/PNG/JPEG/WebP 渲染（相对路径、落在 files 内、≤256 KiB，任一不满足会让整条元数据报错）
-  "version": "0.13.0",
+  "version": "0.13.1",
   "main": "./lib/index.js",              // Host 半边入口：src/host/*.ts 经 tsdown 打成的单条 bundle
   "exports": {
     ".": "./lib/index.js",               // 源码在 src/host/，lib/ 为纯构建产物（随库提交，git/市场直装零构建）

package/docs/README.md

@@ -4,7 +4,7 @@
 
 AI 协作会话从根目录 [AGENTS.md](../AGENTS.md) 进入：验证怎么跑、红线、文档地图都在那里，本目录提供细节。
 
-阅读顺序建议：先 [ARCHITECTURE.md](./ARCHITECTURE.md) 建立整体认知，再按需查 [SETUP.md](./SETUP.md) / [AUTH.md](./AUTH.md) / [API.md](./API.md)；改动代码前读 [TESTING.md](./TESTING.md) 与 [CONTRIBUTING.md](./CONTRIBUTING.md)。
+阅读顺序建议：先 [ARCHITECTURE.md](./ARCHITECTURE.md) 建立整体认知，再按需查 [SETUP.md](./SETUP.md) / [AUTH.md](./AUTH.md) / [API.md](./API.md)；**它坏了、只有一句报错**则直接进 [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)；改动代码前读 [TESTING.md](./TESTING.md) 与 [CONTRIBUTING.md](./CONTRIBUTING.md)。
 
 | 文档 | 内容 | 何时查 |
 |---|---|---|
@@ -12,13 +12,14 @@ AI 协作会话从根目录 [AGENTS.md](../AGENTS.md) 进入：验证怎么跑
 | [ROADMAP.md](./ROADMAP.md) | 战略执行路线图（2026-09-29 起）：P0 解耦与契约回归（§2，`index.js` 控制面拆模块 + 推理契约自动化回归）、429 全局自愈、§5「多 Key 池」纠偏、文档精炼、明确不做的边界 | 定吸收顺序 / 优先级、拍板侵入性、防范围漂移 |
 | [DSH-PLUGIN.md](./DSH-PLUGIN.md) | DSH 插件机制总览（bundle 结构、Loader 条目、cordis.patch.yml、安装重启、peer 依赖、与兄弟插件关系） | 理解「这是一个 DSH 插件」、对照 dsh-connect-qoder 范本 |
 | [DSH-LLM-DEVELOP.md](./DSH-LLM-DEVELOP.md) | **LLM / provider 接入开发指南**：三个 peer 分工、注册三件套、adapter 组装、descriptor 契约（含 maxTokens 兜底坑）、live-contract 探针纪律、排查速查 | 把某平台接成 DSH provider、排查模型路由故障、定钉值策略 |
-| [SETUP.md](./SETUP.md) | 安装、配置字段表、改动后必须重启 Host、首次使用、常见信号处置 | 装环境、改配置、排「跑的是旧代码」、查面板报错信号 |
+| [SETUP.md](./SETUP.md) | 安装、配置字段表、改动后必须重启 Host、首次使用；排障已迁出（见下一行） | 装环境、改配置、排「跑的是旧代码」 |
+| [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) | **排障入口，按界面原文索引**：面板上那句话属于哪一层、第一动作是什么、细节在哪份文档的哪一节；含「看着像坏了其实是设计」清单；不发明症状码（理由在 §4） | 只知道一句报错或界面文案、不知道是哪个模块；接手别人「它坏了」的问题 |
 | [AUTH.md](./AUTH.md) | 一跳账号密码登录、无 refresh token（重登即续期）、密码明文过 TLS 与不落盘纪律、登录 trace、防锁号节流 | 改登录/重登、排查登录失败 |
 | [API.md](./API.md) | 本地路由（`snapshot` / `account` / `api-key` / `provider` / `models` / `draw` / `video` / `agnescode` 共 8 组）、控制台端点、配置端点清单 | 对接路由、看返回结构、调端点 |
 | [PROVIDER-HOT-RELOAD.md](./PROVIDER-HOT-RELOAD.md) | 提供方注册开关：从「配置字段 + 重启」到「面板开关 + 立即生效」的设计决策与同类插件调研 | 改 provider 注册、理解开关语义 |
 | [TESTING.md](./TESTING.md) | 离线测试体系、`panel-decision.js` 机制、已知缺口 | 跑测试、理解测试为什么这样写 |
 | [AGNES-API.md](./AGNES-API.md) | **现行接口事实源**：控制台额度侧（端点表、响应信封、四窗口额度模型、套餐目录与 uuid 匹配）＋推理侧（provider `agnes-token-plan`、key `AGNES_TOKEN_PLAN_API_KEY`、思考档位 safe-set、live-contract 护栏） | 改额度/推理接口、排「打到错网关」、对 live-contract 基线 |
-| [PITFALLS.md](./PITFALLS.md) | 61 条真实踩坑（现象→根因→修法） | 改代码前避坑、理解防御性代码的来由 |
+| [PITFALLS.md](./PITFALLS.md) | 真实踩坑（现象→根因→修法）；**条数以文件内 `## N.` 编号为准，别在此写死** | 改代码前避坑、理解防御性代码的来由 |
 | [CONTRIBUTING.md](./CONTRIBUTING.md) | 提交约定、红线（凭据/`upstream/` 不进库）、仓库整洁 | 准备提交、清理历史误跟踪 |
 | [REFERENCES.md](./REFERENCES.md) | **参照件索引与纪律**：`upstream/` 容器里谁是谁（来源 / 版本 / 许可 / 承重在哪）——AgnesCode 线六件参照件与本机桌面端快照、只吸收事实不复制代码的红线 | 查「这条事实当初从哪来」、新增参照件、防再次「纯探测不落盘」 |
 | [CHANGELOG.md](../CHANGELOG.md) | 公开行为变化的版本记录（非 git log 替代） | 看「这个版本改了什么」 |

package/docs/SETUP.md

@@ -115,16 +115,8 @@ AgnesCode tab 读的是**另一个应用**（AgnesCode 桌面端）已经登录
 
 ---
 
-## 6. 常见信号与处置
+## 6. 出问题了
 
-| 面板 / 接口信号 | 含义 | 怎么做 |
-|---|---|---|
-| 面板顶部 `config_error` | 配置面有非法端点地址等挂载期错误 | 检查 `cordis.patch.yml` 的端点类字段（§3），改后重装 / 重载 Host |
-| 快照带 `shapeWarnings` | 控制台返回结构与预期不符（如字段改名） | 对照 [AGNES-API.md](./AGNES-API.md) §2 核对接口字段——这是接口变更的第一信号，不是「暂无数据」 |
-| 面板 `console_error` | 控制台没应答 | 通常是下一轮轮询自愈；持续出现再查网络与控制台状态 |
-| `quota.error` 指名某个 source | 那一个额度源降级了（series / subscription / plans / overview），其余照常 | 看 `message` 里平台自己的话；当前实现将五个源一律软失败，`overview` 失败时面板会显示 `consoleConnected:false` 并保留其他来源数据。旧文曾写「overview 是致命源」，现已改为软降级（见 [ADR.md](./ADR.md) ADR-007 及 [ARCHITECTURE.md](./ARCHITECTURE.md) §5 不变量）。 |
-| 快照接口没有 `auth` 字段 | 跑的还是旧代码 | 完全退出 DSH（含托盘）再启动（见 §4） |
-| 面板提示需要重新登录 | 令牌被拒且环境里已无密码 | 面板表单填一次账号密码即可 |
-| 面板「可看图」一行缺失，但 `/v1/models` 有模型 | 没有 API key，模型目录没拉（`catalogAvailable: false`），视觉清单随之不显示 | 在面板「API Key」卡粘贴 API Key 保存（免费版 `sk-` 或 Token Plan `cpk-` 皆可；写入 DSH 凭据服务引用），或在用户级 env 变量层配 `AGNES_TOKEN_PLAN_API_KEY`；下一轮 poll 自动亮起来，无需重启 |
-| 「可看图」清单为空但 catalog 有模型 | Agnes 目录条目**不带** `input_modalities`（§7.1 实测只有 `id`/`object`/`created`/`owned_by`/`supported_endpoint_types` 五个字段），`identifyVisionModel` 只能读目录 → 恒 false | **这是「读不到」，不是「没有」**——官方文档（`docs/AGNES-API-docs/`）明说 `agnes-3.0-flash` / `agnes-2.5-pro` / `agnes-2.5-flash` 支持「文本 + 图像 URL 输入」。空清单不能当作「真没有可看图模型」的证据；要补 vision 需按 §7.1.1 的硬编码清单路线 |
-| `quota.planUnknown`（界面文案键） | 订阅 payload 没有可匹配的套餐身份（uuid / 名称）时，面板用 i18n 文案键 `quota.planUnknown` 渲染一行说明——**它是 client 侧的渲染文案键，不是快照信号字段**；套餐对比卡照常显示（公开目录），当前套餐上限需要 `/api/cn/user/subscription` 返回可识别的套餐名或 uuid，见 [AGNES-API.md](./AGNES-API.md) §5 |
+信号与处置的整张表已迁到 **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)**（按面板上的**界面原文**索引：面板读不出来、登录被拒、模型目录为空、以及「看着像坏了其实是设计」的清单）。
+
+本文件只管装、配、重启；排障从那份进。`shapeWarnings`、`quota.error` 按源降级、「可看图」为空是「读不到」等接口侧含义，那份表指到 [AGNES-API.md](./AGNES-API.md) 与 [ADR.md](./ADR.md)，不在此重复。

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,89 @@
+# 排障入口（按界面原文查）
+
+当手上只有一句话（面板上的一句话、快照里的一个字段、日志里的一行），没有模块名时，从本文件进。
+
+**本文件不解释机制**，只做一件事：把那句话翻译成「属于哪一层、下一步看哪份文档的哪一节」。机制细节的唯一定义处是 [AUTH.md](./AUTH.md)（登录/节流）、[AGNES-API.md](./AGNES-API.md)（接口事实）、[API.md](./API.md)（路由与快照结构）、[PITFALLS.md](./PITFALLS.md)（现象→根因→修法）。这里复制它们的表，只会多出一份会分叉的副本（`docs.test.mjs` 的 `TABLES` 门禁也是这样要求的）。
+
+怎么用：
+
+1. 面板文案是**原文**（取自 `src/client/i18n.ts` 的 `zh` 字典，键集真源；英文界面同一键的值不同，但键一样），方括号里是文案键——按文案键 grep 能直接定位渲染处与判定条件，比按中文句子搜更稳。
+2. 先看 §1（面板上的话）；面板整块是空的、或者只有接口没有界面，看 §2。
+3. §3 是「看着像坏了、其实是设计」的清单。**这里的东西不要去修**。
+
+---
+
+## 1. 面板上的话 → 下一步
+
+### 1.1 整块读不出来 / 配置类
+
+| 界面原文 | 含义 | 第一动作 | 细节 |
+|---|---|---|---|
+| 插件配置有误：{error} [`panel.configError` / 快照码 `config_error`] | 挂载期校验失败，几乎只有「端点字段不是合法 http(s) 绝对地址」一种 | 对照 [SETUP.md](./SETUP.md) §3 的配置表检查 `cordis.patch.yml` 的端点类字段，改后重装 / 重载 Host | [SETUP.md](./SETUP.md) §3 |
+| 读取失败：{error} [`panel.error`] | 快照路由本身失败，不是上游失败 | 到 **Host 终端 stdout** 与 `$DSH_HOME/logs/` 找同一时刻的堆栈——浏览器 F12 里没有 Host 半边 | [PITFALLS.md](./PITFALLS.md) §42 |
+| Agnes 控制台暂时无法读取，通常下一次自动刷新即可恢复… [`panel.consoleTransient` / 快照码 `console_error`] | 传输层瞬时失败，设计上交给下一轮轮询 | 什么都不做，等一轮；连续出现才查网络与平台状态 | [ARCHITECTURE.md](./ARCHITECTURE.md) §5（软失败不变量） |
+| Agnes 控制台未连接，本页的额度与用量都读不到。 [`quota.consoleOffline`] | `overview` 源失败（软降级），其余源的数据仍可能在 | 按提示到本页下方卡片登录；不要当成插件坏了 | [ADR.md](./ADR.md) ADR-007 |
+| 读取 {source} 失败：{message} [`quota.error`] | **单个**额度源（series / subscription / plans / overview）降级，互不牵连 | 先看 `{message}` 里平台自己的话；只有五个源同时失败才是平台级问题 | [AGNES-API.md](./AGNES-API.md) §2、[ARCHITECTURE.md](./ARCHITECTURE.md) §5 |
+| 上游返回的结构可能有变：{detail} [`panel.shapeDrift`] | 控制台响应结构与预期不符（字段改名等）——**接口变更的第一信号** | 对照 [AGNES-API.md](./AGNES-API.md) §2 核字段，别当成「暂无数据」；持续出现记进 PITFALLS | [AGNES-API.md](./AGNES-API.md) §2 |
+| 暂无额度数据。 [`quota.none`] | 读到了响应但没有可用窗口，通常是没登录或账号无额度 | 先确认登录态（§1.2），再看控制台网页端是否同样为空 | [AGNES-API.md](./AGNES-API.md) §5 |
+| 未能识别当前套餐——控制台没有返回可匹配的套餐信息… [`quota.planUnknown`] | 订阅 payload 里没有可匹配的 uuid / 名称；**这是渲染文案键，不是快照信号字段** | 属正常显示：下方「套餐对比」是平台公开目录，不依赖登录 | [AGNES-API.md](./AGNES-API.md) §5 |
+
+### 1.2 登录与账号类
+
+| 界面原文 | 含义 | 第一动作 | 细节 |
+|---|---|---|---|
+| 需要重新登录 [`auth.needsLogin`] | 令牌被拒且环境里已无密码可自动重登 | 面板表单填一次账号密码 | [AUTH.md](./AUTH.md) §8 |
+| 控制台令牌已失效…Host 会用已保存的账号重新登录一次… [`panel.jwtExpired`] | 一跳重登已触发（Agnes 不发 refresh token） | 等一轮刷新；反复出现按「重登没用」查 | [AUTH.md](./AUTH.md) §5、[PITFALLS.md](./PITFALLS.md) §46 |
+| 令牌自动续期中 [`auth.selfRenew`] | 正常状态，不是告警 | 不用处理 | [AUTH.md](./AUTH.md) §5 |
+| Host 已停止自动重试：上一次登录被拒… [`auth.parked`] | 凭据型拒绝，或自造退避次数用尽，已**停车**（`needsUserAction`） | 核对账号密码后手动登录；等倒计时不会有结果 | [AUTH.md](./AUTH.md) §7、[PITFALLS.md](./PITFALLS.md) §52 |
+| 账号已被锁定。…期间面板不会自动重试。 [`auth.locked`] | 平台锁号；插件刻意不再敲门以免延长锁定 | 去控制台网页端确认账号状态，**别**在面板反复点登录 | [AUTH.md](./AUTH.md) §7 |
+| 平台要求等待约 {minutes} 分钟后再试… [`auth.retryAfter`] | 平台声明了等待窗口，照单全收、不截短 | 等满窗口；期间任何手动重试都可能重新触发 | [AUTH.md](./AUTH.md) §7 |
+| 需要额外验证（短信/图形验证码）… [`auth.verification`] | 自动化登录无法完成验证码 | 先在浏览器登录一次，再回面板 | [AUTH.md](./AUTH.md) §7 |
+| 登录未完成：{reason} [`auth.failed`] | 分类器没认出这句话（兜底 `LOGIN_FAILED`） | 看 `{reason}` 原文与 `$DSH_HOME/logs/` 的 trace；这类形状值得记进 PITFALLS | [AUTH.md](./AUTH.md) §6、§8 |
+| 注意：当前 Host 没有凭据服务… [`auth.ephemeral`] | 缺 `@deepseek-ai/dsh-credentials`，账号只在内存 | 接受「重启需重登」，或换带凭据服务的 Host | [SETUP.md](./SETUP.md) §1 |
+
+### 1.3 推理 / 出图 / 视频 / AgnesCode 类
+
+| 界面原文 | 含义 | 第一动作 | 细节 |
+|---|---|---|---|
+| 模型目录暂时读不到：{error}（额度与聊天不受影响） [`llm.catalogFailed`] | 没有 API Key → 目录没拉（`catalogAvailable: false`）或目录端点失败；**额度面板不受牵连** | 面板「API Key」卡保存 Key（免费版 `sk-` 或 Token Plan `cpk-`），或用户级 env 配 `AGNES_TOKEN_PLAN_API_KEY`；下一轮 poll 自动恢复，无需重启 | [AGNES-API.md](./AGNES-API.md) §7.1 |
+| 提供方注册失败：{error} [`llm.error`] | 向 DSH 注册 provider 失败（Host 级动作） | 看 `{error}`；注册三件套与 descriptor 契约见 DSH-LLM-DEVELOP | [DSH-LLM-DEVELOP.md](./DSH-LLM-DEVELOP.md) |
+| 额度耗尽 [`llm.rosterExhausted`] | 模型花名册侧标记，不等于 402/429 已发生 | 区分额度不足（402）与速率上限（429），后者等一分钟即可 | [AGNES-API.md](./AGNES-API.md)、[PITFALLS.md](./PITFALLS.md) §45 |
+| 当前 API Key 目录里暂无出图模型；出图不可用。 [`draw.noCandidates`] | 目录里没识别出图模型（名称兜底也没命中） | 换有出图权限的 Key，或显式设 `drawModelId` | [SETUP.md](./SETUP.md) §3（`drawEnabled` / `drawModelId`） |
+| 当前 API Key 目录里暂无视频模型；视频不可用。 [`video.noCandidates`] | 同上，视频侧 | 显式设 `videoModelId`（V2.0 / 2.5 家族均可） | [SETUP.md](./SETUP.md) §3、[AGNES-API.md](./AGNES-API.md) §7.5 |
+| 未关联——请先在 AgnesCode 桌面端登录… [`agnescode.notLogged`] | 本插件不发起登录，只读桌面 App 的会话文件 | 桌面 App 里登录一次，再点「检测本机登录态」 | [SETUP.md](./SETUP.md) §3「AgnesCode 已知限制」 |
+| 本机登录态采集目前仅支持 Windows… [`agnescode.harvestWindowsOnly`] | 采集侧只有 DPAPI 一条路 | 非 Windows 用「扫码登录」 | [AGNESCODE-SCAN-LOGIN.md](./AGNESCODE-SCAN-LOGIN.md) |
+| 扫码登录失败：{error} [`agnescode.loginFail`] | 设备流换 token 失败 | 看 `{error}`；换 token 端点实测记录在扫码登录文档 | [AGNESCODE-SCAN-LOGIN.md](./AGNESCODE-SCAN-LOGIN.md) |
+
+---
+
+## 2. 快照 / 日志里的信号（没有界面文案）
+
+| 信号 | 含义 | 第一动作 | 细节 |
+|---|---|---|---|
+| 快照**没有 `auth` 字段**，只有 `totals` / `recent` | 跑的是旧代码（Host 半边只在启动时加载一次） | 完全退出 DSH（**含托盘**）再启动 | [SETUP.md](./SETUP.md) §4 |
+| `shapeWarnings` 非空 | 控制台返回结构与预期不符（字段改名等）——**接口变更的第一信号** | 对照接口文档核字段，别当成「暂无数据」 | [AGNES-API.md](./AGNES-API.md) §2 |
+| `config_error`（面板顶部） | 挂载期配置错误 | 同 §1.1 第一行 | [SETUP.md](./SETUP.md) §3 |
+| Host 日志 `unknown config key(s) ignored: …` | patch 里有拼错的键（**不**升为 `config_error`，刻意如此） | 改掉拼写；遗留键可不理，但别指望它生效 | [SETUP.md](./SETUP.md) §3 |
+| 浏览器 F12 里没有任何插件报错 | 两半进程：Host 报错在 `dsh web` 终端 stdout 与 `$DSH_HOME/logs/` | 换地方看，不是「没有日志」 | [PITFALLS.md](./PITFALLS.md) §42 |
+| 桌面上看着改了、实际没生效 | 桌面端是安装副本、web 是 symlink；两者还是不同 profile、不同端口 | 先确认你在看哪个进程，再查三层装载 | [PITFALLS.md](./PITFALLS.md) §22、[SETUP.md](./SETUP.md) §4 注记 |
+
+---
+
+## 3. 看着像坏了，其实是设计
+
+先读这一节，能省掉一半的「修」。这些行为都有明确理由，**不要当成缺陷去打补丁**：
+
+- **没有「登出」按钮**：能停的是 provider 开关，不是令牌。「删除已存 JWT」是隐私动作，被刻意移出日常操作；真正吊销只能在桌面 App 里登出 / 改密码。见 [SETUP.md](./SETUP.md) §3。
+- **「可看图」清单为空**：Agnes 目录条目**不带** `input_modalities`（实测只有 `id`/`object`/`created`/`owned_by`/`supported_endpoint_types` 五个字段），`identifyVisionModel` 只能读目录 → 恒 false。这是**「读不到」而不是「没有」**——官方文档（`AGNES-API-docs/`）明说 `agnes-3.0-flash` / `agnes-2.5-pro` / `agnes-2.5-flash` 支持「文本 + 图像 URL 输入」，所以空清单不能当作「真没有可看图模型」的证据。见 [AGNES-API.md](./AGNES-API.md) §7.1。
+- **「可看图」整行消失**：不是被裁掉，是没有 API Key → 目录没拉 → 视觉清单无从生成。见 §1.3 第一行。
+- **改了设置不重启也生效，但工具挂载要等下次启动**：开关与勾选走热生效；agent 工具没有 unregister 语义，挂载 / 缺席只发生在 Host 启动时。见 [PROVIDER-HOT-RELOAD.md](./PROVIDER-HOT-RELOAD.md)。
+- **拼错的配置键只记日志、不报错**：老 patch 里的历史键不该把面板打成配置错误。见 [SETUP.md](./SETUP.md) §3。
+- **429 与额度耗尽不是一件事**：402 是额度不足，429 多为速率上限（订阅用尽也可能回 429）。见 [AGNES-API.md](./AGNES-API.md)。
+
+---
+
+## 4. 为什么这份文件没有「症状码」
+
+兄弟仓 `dsh-connect-sensenova-token-plan` 的排障入口是按**稳定症状码**组织的（`SYMPTOM` / `SYMPTOM_HINT` + `doctor.report.symptoms`，并由 `test/doctor.test.mjs` 双向钉住文档锚点）。本仓目前只有下半层：`CODE`（平台失败码，进 `body.code`）与 `doctor` 的 scope 事实（`providerPanel` / `drawPanel` / `unreadable` / `writable`），**没有从「用户现象」到「失败码」的映射层**。
+
+所以本文件按**界面原文 + 文案键**索引，不发明一套本仓代码里不存在的码——那种码没有任何东西守着，会静默腐烂（本仓对「文档里的量化断言必须可复现」的纪律见 [CONTRIBUTING.md](./CONTRIBUTING.md)）。要升级成兄弟仓那套，需要同时动 `src/host/codes.ts`（加 `SYMPTOM` / `SYMPTOM_HINT`）、`src/host/doctor.ts`（`report.symptoms`）与 `test/doctor.test.mjs`（锚点双向钉住），属另案。

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "Agnes Token Plan Connect",
+    "title": "Agnes Model Access",
     "description": "One-tap connect Agnes language, image and video models into DSH (off by default), with image recognition and thinking level filled in automatically. After signing in to the Agnes console (re-login uses AGNES_PASSWORD), you can see the quota windows (5-hour requests, weekly requests, daily images, video), account-wide cumulative usage, and a usage pill beside the input box. AgnesCode desktop models can be connected too (Windows only), re-reading the desktop app login when the token expires, with rate-limit hits backing off on their own."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "Agnes Token Plan 接入全家桶",
+    "title": "Agnes 模型接入",
     "description": "一键接入 Agnes 的语言、生图、视频模型到 DSH（默认关），自动填入图片识别与思考强度；登录 Agnes 控制台后（重登需 AGNES_PASSWORD），可看额度窗口（5 小时请求、每周请求、每日图片、视频）、账号累计用量，以及输入框旁的用量胶囊；也支持接入 AgnesCode 桌面端模型（仅 Windows），令牌到期时重新读取桌面端登录态，撞限额自动退避重试。"
   }
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-connect-agnes-token-plan",
   "displayName": "DSH Connect Agnes Token Plan",
   "icon": "./icon.svg",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "One-tap connect Agnes language, image and video models into DSH (off by default), with image recognition and thinking level filled in automatically. After signing in to the Agnes console (re-login uses AGNES_PASSWORD), you can see the quota windows (5-hour requests, weekly requests, daily images, video), account-wide cumulative usage, and a usage pill beside the input box. AgnesCode desktop models can be connected too (Windows only), re-reading the desktop app login when the token expires, with rate-limit hits backing off on their own.",
   "keywords": [
     "dsh-plugin",