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

package/CHANGELOG.md

@@ -23,6 +23,25 @@
 
 ## [Unreleased]
 
+## [0.13.2] — 2026-10-23
+
+本版两件事：**网关新上的模型默认就能发图**，以及**余额胶囊上会多一段「· N 新模型」**。两处都只影响 AgnesCode（桌面端）这条线。
+
+### 变更：新模型默认能发图，胶囊会告诉你网关多了哪个模型
+
+- **改（识图）**：网关新上的模型不再默认被当成纯文本。旧版只认「官方文档表里写过的」那几个，表里没有的模型就不给图片入口——看不到任何提示，只能自己发现。现在没证据的模型**默认放开图片输入**，面板把它标成「可看图·未实测」；确认看不见图的模型才被收回去（记在一份否决清单里，带实测日期）。
+- **新（胶囊）**：小浣熊/AgnesCode 的余额胶囊上会多一段「· N 新模型」。它比的是插件自己记的「这台机器见过哪些模型」，所以只在网关真的新上了模型时出现。新模型名字在 tooltip 和展开卡片里，最多列三个。标记保持 7 天，不弹窗、不需要点确认；装上新版后的第一次运行会把当时的目录当作「早就见过」，不会把整张表报成新的。
+- **说明**：两处都只影响 AgnesCode 这条线，商汤 Token Plan 侧的面板与胶囊不变。
+
+## [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,13 @@
-# 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 +18,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，参与对话、出图与出视频；
@@ -66,7 +75,8 @@
 
 - 读数与面板**同源**：控制台百分比优先用平台自己报的 `usage_pct`、缺失才回落 `已用 / 上限`，**不做钳制**（超额窗口就显示 >100%，那是事实）；桌面端画的是**存量**，所以**不造百分比**——网关只公布积分，没有「上限」可以当分母；
 - 两条上游**互不借用**：`agnescode` 的会话只读它自己的路由、绝不画控制台窗口，反之亦然；切到**别的 provider**（其它插件）的模型时胶囊直接消失，也不再发任何请求；
-- 读不到时**保留上一次数字并标「上次数据」**，不会清零或伪装成 0%；余额里的 `0` 是「烧完了」的读数（红色告警），`—` 才是「这次没读到」——这个区别是刻意的。
+- 读不到时**保留上一次数字并标「上次数据」**，不会清零或伪装成 0%；余额里的 `0` 是「烧完了」的读数（红色告警），`—` 才是「这次没读到」——这个区别是刻意的；
+- 网关新上了模型时，余额胶囊会多一段**「· N 新模型」**（名字在 tooltip 与展开卡里，最多三个，保留 7 天）。这里的「新」指**这台机器第一次见到它**，不是上游的上架时间——网关目录没有这个字段。装上新版后的第一次运行只把当时的目录记下来当基线，不会把整张表报成新的。
 
 ![AgnesCode 积分余额胶囊（点开读数卡）](assets/agnescode-usage-capsule.png)
 
@@ -100,26 +110,22 @@
 
 ## 运维诊断：这台机器现在挂没挂 provider？
 
-provider / 出图开关的生效值存在插件私有状态文件里（`$DSH_HOME/state/<name>/`），不在任何配置或路由上——查"到底开没开"用 doctor，它只读状态文件、不碰凭据，Host 没起也能跑：
-
-```powershell
-npm run doctor          # 人读：每个 profile 的 provider / draw / video / agnescode 开关与模型清单
-npm run doctor:json     # 机器读：JSON（可进你的巡检 / 工单脚本）
-```
+provider / 出图 / 视频 / AgnesCode 开关的生效值存在插件私有状态文件里（`$DSH_HOME/state/<name>/`），不在任何配置或路由上；`npm run doctor` 只读状态文件、不碰凭据，Host 没起也能跑（人读 / 机器读两个口径见 [docs/SETUP.md](docs/SETUP.md) §6.1）。
 
 ## 文档
 
 - [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/client.js

@@ -264,6 +264,12 @@ var dsh_connect_agnes_token_plan_client = (function() {
 			"agnescode.models": "模型（{count}）",
 			"agnescode.fallbackRoster": "未取到实时目录，以下为内置清单，倍率截至 {asOf}。",
 			"agnescode.memberOnly": "会员",
+			"agnescode.visionAssumed": "可看图·未实测",
+			"agnescode.visionAssumedTitle": "网关没声明这个模型能否看图，插件默认放开图片入口（未实测）。真发过去模型说看不到，就把它的 id 记进否决清单。",
+			"agnescd.newModels": "新模型",
+			"agnescd.newModelsRow": "本机新见",
+			"agnescd.newModelsTitle": "本机首次见到的模型：",
+			"agnescd.newModelsSep": "、",
 			"agnescode.rateTitle": "平台公布的积分消耗倍率（0 为免费）",
 			"agnescode.registeredPill": "已注册",
 			"agnescode.rosterHint": "勾选决定哪些模型推送进 DSH 模型列表，改动即时生效。",
@@ -524,6 +530,12 @@ var dsh_connect_agnes_token_plan_client = (function() {
 			"agnescode.models": "Models ({count})",
 			"agnescode.fallbackRoster": "Live catalogue unavailable — showing the built-in list, rates as of {asOf}.",
 			"agnescode.memberOnly": "member",
+			"agnescode.visionAssumed": "vision (unverified)",
+			"agnescode.visionAssumedTitle": "The gateway did not declare whether this model sees images, so picture input is allowed by default and this is unverified. If the model answers it cannot see the image, add its id to the vision denylist.",
+			"agnescd.newModels": "new",
+			"agnescd.newModelsRow": "New here",
+			"agnescd.newModelsTitle": "First seen on this machine: ",
+			"agnescd.newModelsSep": ", ",
 			"agnescode.rateTitle": "Credit multiplier as published by the platform (0 = free)",
 			"agnescode.registeredPill": "Registered",
 			"agnescode.rosterHint": "Ticking decides which models are pushed into DSH's model list; the change takes effect immediately.",
@@ -1562,6 +1574,10 @@ var dsh_connect_agnes_token_plan_client = (function() {
 			},
 			pillReading: { fontVariantNumeric: "tabular-nums" },
 			pillStale: { color: "var(--dsw-alias-label-secondary)" },
+			pillNewTag: {
+				color: "var(--dsw-alias-label-secondary)",
+				flexShrink: 0
+			},
 			pillErrorText: { color: "var(--dsw-alias-state-error-primary)" },
 			pillTierOk: { background: "var(--dsw-alias-state-success-primary, #22c55e)" },
 			pillTierWarn: { background: "var(--dsw-alias-state-warn-primary, #f59e0b)" },
@@ -4050,7 +4066,10 @@ var dsh_connect_agnes_token_plan_client = (function() {
 			}), h("span", { style: S.spacer }), promo === null ? null : h("span", { style: S.modelPromo }, promo), rate === null ? null : h("span", {
 				style: S.modelRate,
 				title: tt("agnescode.rateTitle")
-			}, `×${rate}`), row.memberOnly === true ? h("span", { style: S.modelBadge }, tt("agnescode.memberOnly")) : null), meta === "" ? null : h("div", { style: S.modelMeta }, meta));
+			}, `×${rate}`), row?.vision === true ? h("span", {
+				style: S.modelBadge,
+				title: row?.visionSource === "assumed" ? tt("agnescode.visionAssumedTitle") : void 0
+			}, row?.visionSource === "assumed" ? tt("agnescode.visionAssumed") : tt("llm.rosterVision")) : null, row.memberOnly === true ? h("span", { style: S.modelBadge }, tt("agnescode.memberOnly")) : null), meta === "" ? null : h("div", { style: S.modelMeta }, meta));
 		})));
 	}
 	/**
@@ -4665,10 +4684,17 @@ var dsh_connect_agnes_token_plan_client = (function() {
 		const permanent = partOf(state, "permanentBalance");
 		const split = timeLimited === null || permanent === null ? null : `${tt("agnescode.balanceTimeLabel")} ${count(timeLimited)} · ${tt("agnescode.balancePermanentLabel")} ${count(permanent)}`;
 		const usageText = agnescodeUsageText(state?.usage ?? null, tt);
+		const newIds = (Array.isArray(state?.newModelIds) ? state.newModelIds : []).filter((id) => typeof id === "string" && id !== "");
+		const shownNames = newIds.map((id) => {
+			const row = state?.models?.find((model) => model.id === id);
+			return row?.name ?? row?.id ?? id;
+		}).slice(0, 3);
+		const newModelTitle = newIds.length === 0 ? null : `${tt("agnescd.newModelsTitle")}${shownNames.join(tt("agnescd.newModelsSep"))}${newIds.length > shownNames.length ? "…" : ""}`;
 		const title = [
 			tt("composer.balanceTitle"),
 			split,
 			why,
+			newModelTitle,
 			stale ? tt("composer.stale") : null
 		].filter(Boolean).join(" · ");
 		const { popoverId, open, setOpen, rootRef, cardRef, triggerRef } = usePillPopover();
@@ -4693,6 +4719,10 @@ var dsh_connect_agnes_token_plan_client = (function() {
 				key: "why",
 				style: S.pillPopMuted
 			}, why) : null,
+			newIds.length > 0 ? h("div", {
+				key: "new-models",
+				style: S.pillPopMuted
+			}, `${tt("agnescd.newModelsRow")} ${shownNames.join(tt("agnescd.newModelsSep"))}${newIds.length > shownNames.length ? "…" : ""}`) : null,
 			stale ? h("div", {
 				key: "stale",
 				style: S.pillPopMuted
@@ -4716,7 +4746,13 @@ var dsh_connect_agnes_token_plan_client = (function() {
 			popoverOpen: open,
 			popoverId,
 			buttonRef: triggerRef,
-			children: h("span", { style: S.pillReading }, pending ? "…" : balance === null ? "—" : `${count(balance)} ${tt("composer.balanceUnit")}`)
+			children: [h("span", {
+				key: "reading",
+				style: S.pillReading
+			}, pending ? "…" : balance === null ? "—" : `${count(balance)} ${tt("composer.balanceUnit")}`), newIds.length === 0 ? null : h("span", {
+				key: "new-models",
+				style: S.pillNewTag
+			}, ` · ${newIds.length} ${tt("agnescd.newModels")}`)]
 		}), open ? h("div", {
 			ref: cardRef,
 			id: popoverId,

package/docs/ADR.md

@@ -206,3 +206,24 @@
 - **受影响的文档**：`src/host/agnescode-models.ts`（`agnescodeThinkingLevelMap(id)` per-model + 模块头决策 1）、`test/agnescode.test.mjs`（新增 agnes-2.5-pro 断言块）、`docs/ROADMAP.md` §6.3.1（新增 2026-10-18 探针行）、`CHANGELOG.md`（[Unreleased]）。ADR-009 原文按考古纪律保留不改写。
 - **与既有条目的关系**：细化 ADR-009 的档位映射（该裁定以 3.0-flash 探针为基础，未覆盖 2.5-pro 的阶梯差异）；不改变 `docs/DSH-LLM-DEVELOP.md` §4 的通用裁法（Token Plan 侧 `thinkingLevelMapFor` 未动）。
 
+## ADR-018 agnescode 识图默认放行：没证据的行也收图，但面板必须说「未实测」
+
+- **日期**：2026-10-22
+- **状态**：现行（实现见 `src/host/agnescode-models.ts` 的 `AGNESCODE_VISION_DENYLIST` / `agnescodeVisionVerdict` / `agnescodeVisionSource`，`agnescodeRoster` 把 `vision` 与 `visionSource` 一起透出；面板 chip 见 `src/client/agnescode-tab.ts`；门禁见 `test/agnescode.test.mjs` 的判定阶梯段与 `test/dom-render.test.mjs` 的 chip 段）
+- **裁定**：判定阶梯四级——**实测否决集 → 行内声明 → `PROBED_VISION` 实测表 → 默认放行（`assumed`）**。前三级给面板一个朴素 chip；`assumed` 必须画成「可看图·未实测」并带 tooltip；否决项画 `vision:false`、无 chip。换言之：**默认值是「给它图片」，唯一能否掉它的是带日期实测的否决条目**。
+- **理由**：网关 `/models` 的每一行都只写 `model_type: "text"`，从不说自己能不能看图（`fetchAgnescodeCatalog` 因此钉死 `vision:false`——那是 wire 事实，不是判决）。旧逻辑把「文档表里没有」读成「不支持」，于是网关每上一次新模型，图片入口就静默消失一次：用户看不到任何提示，只能自己发现并来报。这条失效方向是不可见的（能力缺失不像错报那样会在会话里露头），而错报在当前网关是可观测的：模型收到图片后自述看不见，HTTP 仍是 200。
+- **代价与护栏**：默认放行把失效方向翻成「错报」，但没有翻成「谎报」——`visionSource` 让面板把未实测的行标出来，读者因此知道这是插件的默认，不是平台的声明。否决集是唯一维护面：发现某模型自述看不见，就把它带日期加进 `AGNESCODE_VISION_DENYLIST`。
+- **边界**：只动 agnescode 这条上游；Token Plan 侧 `identifyVisionModel`（按 `/v1/models` 的 `input_modalities` 判定）不受影响，两侧判定函数不合并。`AGNESCODE_FALLBACK_MODELS` 的 `vision` 列是手写快照，不经过本判定函数；`visionSource` 只影响面板显示，不改变 descriptor 的 `input` 数组长度约定（`vision:true` → `["text","image"]`）。
+- **复核条件**：若网关开始在 `/models` 里声明模态（`input_modalities` 或视觉标签），第二级（`declared`）就会接管绝大多数行，`assumed` 退化为稀有位——那时本条仍然成立，只是很少被用到。若哪天实测发现「未实测默认可看图」在本网关的错报代价高到不可接受（例如图片被静默吞掉且模型照常编造），把默认改回 `false` 并把本条的 `assumed` 换成一个显式的 `unknown` chip。
+
+## ADR-019 网关新增模型走胶囊的「· N 新模型」，不弹窗、不留确认态
+
+- **日期**：2026-10-22
+- **状态**：现行（实现见 `src/host/agnescode-roster-seen-store.ts` 的首次见到历史、`src/host/routes/agnescode.ts` 的 `newModelIds` 差分、`src/client/composer-usage-pill.ts` 的 AgnesCode 胶囊段；门禁见 `test/agnescode.test.mjs` 的两个新段与 `test/dom-render.test.mjs` 的胶囊三帧）
+- **裁定**：网关目录里出现本机没见过的 model id 时，**只在胶囊上多一段「· N 新模型」**（tooltip 与 popover 给名字，最多列三个），不弹窗、不阻塞、不留「已读」按钮。判定基准是插件自己写的首次见到文件 `agnescode-roster-seen.json`：**首次写入是播种（整表记为已见、一条都不报）**，之后新增的 id 记为「现在」并保持 7 天，离开目录的 id 从表里删除（重新上架算新）。
+- **理由**：DSH 的 Host 面没有通知/弹窗服务，插件的可见面只有插件卡与胶囊；而胶囊本来就是读者扫余额的地方，把「网关多了个模型」放在余额旁边是同一类信息（都关于「现在能用什么」）。播种是必须的：升级后的第一次运行会把当时整张目录写成历史，否则每个老用户都会被告知全部七个模型都是新的——那是噪音，不是提醒。
+- **为什么不是弹窗 / 已读态**：弹窗需要用户处理，而「多了个模型」不需要处理；已读态需要一个点击，等于把一个纯信息变成一次任务。7 天窗口是提醒的寿命：够长到用户会看见，够短到不会永远挂着。重上架的 id 再报一次，因为那说明这一行背后的东西换过手，值得知道。
+- **边界**：只在 `modelsSource === "live"` 时差分——回退快照表是插件自己的六行文本，拿它差分会在登录/离线那几帧凭空造出「新模型」。差分对象是**整张 live 目录**，不是用户勾选的子集：某个模型是不是网关的新闻，与这台机器勾了哪些框无关；拿子集差分还会让一个上架很久的模型在「被勾上」的那天冒充新模型。`newModelIds` 缺席（旧生产者、离线、首次播种）时胶囊什么都不画，不画空段、不留悬空分隔符。该标记只出现在 agnescode provider 被选中的胶囊上；Token Plan 侧名册没有这个字段。
+- **复核条件**：若网关开始提供「上架时间」字段，差分就应改成读那个字段，本文件降级为离线兜底；若 DSH 之后提供通知服务，这段可以迁过去，胶囊只留计数。
+
+

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.2",
   "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,19 @@ 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)，不在此重复。
+
+### 6.1 查这台机器的开关生效值（doctor）
+
+provider / 出图 / 视频 / AgnesCode 四个开关的生效值存在插件私有状态文件里（`$DSH_HOME/state/<name>/`），不在任何配置或路由上；`npm run doctor` 只读状态文件、不碰凭据，Host 没起也能跑：
+
+```powershell
+npm run doctor          # 人读：每个 profile 的 provider / draw / video / agnescode 开关与模型清单
+npm run doctor:json     # 机器读：JSON（可进你的巡检 / 工单脚本）
+```
+
+doctor 的只读范围与实现见 [PITFALLS.md](./PITFALLS.md) §22 与 [ROADMAP.md](./ROADMAP.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/lib/agnescode-stats-store.js

@@ -2087,28 +2087,73 @@ function agnescodeRequestHeaders() {
 	return { ...AGNESCODE_BASE_HEADERS };
 }
 /**
-* Whether an AgnesCode roster row accepts image input.
-*
-* AgnesCode's own BFF `/models` rows declare no modality field — only
-* `model_type: "text"` and `supported_endpoint_types` — so the catalogue alone
-* would answer "no vision" for EVERY row (that is why `fetchAgnescodeCatalog`
-* pins `vision: false`). But AgnesCode serves the SAME Agnes model family the
-* Token Plan gateway does (`agnes-3.0-flash` / `agnes-2.5-flash` /
-* `agnes-2.5-pro` all appear in both rosters), whose official docs declare
-* image input — `PROBED_VISION` (llm-models.ts) is that evidence, and the
-* Token Plan side already probed `agnes-3.0-flash` accepting the standard
-* OpenAI `image_url` block live. Non-agnes ids (`deepseek-*` / `glm-*` /
-* `kimi-*`) have no such claim and stay text-only.
-*
-* Resolution order: the row's own `vision` (if the catalogue ever declares
-* one) wins, then `PROBED_VISION` for the Agnes family, then false.
+* Models confirmed on this gateway to CANNOT read an image, in a LIVE probe
+* with the same picture + question the allow side was measured with (a live
+* re-probe runs against this set, so the day a gateway routing change makes a
+* denied model able to see, the baseline turns and the entry comes out).
+* Membership is a dated measurement, never a design call about the model.
+*
+* STARTS EMPTY: nothing about this gateway is known to be blind. An entry is
+* added only when a user reports a model that cannot see the image (with a
+* probe that proves it), and it leaves the same way. Until a report lands
+* here, every untagged row is OFFERED image input by default and labelled
+* unverified — see the companion verdict below.
+* @type {ReadonlySet<string>}
+*/
+const AGNESCODE_VISION_DENYLIST = Object.freeze(/* @__PURE__ */ new Set([]));
+/**
+* Whether an AgnesCode roster row accepts image input, together with how the
+* verdict was reached.
+*
+* The BFF's own `/models` rows declare no modality field (only `model_type:
+* "text"`), so `fetchAgnescodeCatalog` pins `vision: false` — a raw fact about
+* what the wire said, NOT a verdict. The verdict is made here. The ladder is
+* asymmetric on purpose: a false "it can see" (an image sent to a model that
+* ignores it, HTTP 200, no error anywhere upstream) is worse than a hidden
+* capability, so the DEFAULT is to offer the entry but SAY it is unverified,
+* and only a dated live probe may deny it:
+*
+* 1. `AGNESCODE_VISION_DENYLIST` wins: a row confirmed blind in a live probe is
+*    not offered image input; `source: "denied"` tells the panel to draw no chip.
+* 2. A row carrying `vision: true` (a future BFF that starts declaring its own
+*    modality) is `declared`.
+* 3. The `PROBED_VISION` official-docs table (llm-models.ts) — the Agnes family
+*    the platform already proved — is `measured`.
+* 4. Otherwise: `assumed` (true). A model the docs table never mentioned is
+*    still offered image input — it does not vanish from the image picker —
+*    and the panel marks it unverified. Reading "absent from `PROBED_VISION`"
+*    as "text-only" is what made every newly-listed gateway model silently
+*    lose the attachment entry.
 * @param {object} row - one AgnesCode roster row (must carry `id`).
+* @returns {object} the verdict and how it was reached.
+*/
+function agnescodeVisionVerdict(row) {
+	const id = str(row?.id, "");
+	if (id !== "" && AGNESCODE_VISION_DENYLIST.has(id)) return {
+		vision: false,
+		source: "denied"
+	};
+	if (row?.vision === true) return {
+		vision: true,
+		source: "declared"
+	};
+	if (id !== "" && PROBED_VISION[id] === true) return {
+		vision: true,
+		source: "measured"
+	};
+	return {
+		vision: true,
+		source: "assumed"
+	};
+}
+/**
+* The boolean-only view of {@link agnescodeVisionVerdict}, kept for call sites
+* and tests that want the capability bit without the provenance.
+* @param {object} row - one AgnesCode roster row.
 * @returns {boolean} whether the row accepts image input.
 */
 function agnescodeVisionOf(row) {
-	if (row?.vision === true) return true;
-	const id = str(row?.id, "");
-	return PROBED_VISION[id] === true;
+	return agnescodeVisionVerdict(row).vision;
 }
 /**
 * The AgnesCode model rows the panel shows and the adapter offers.
@@ -2128,10 +2173,12 @@ function agnescodeRoster(catalog, maxTokensOverrides) {
 		const multiplier = numZeroOk(row?.multiplier);
 		const maxOutputLength = agnescodeMaxTokensFor(id, row?.maxOutputLength, maxTokensOverrides);
 		const displayLabel = str(row?.displayLabel, "");
+		const verdict = agnescodeVisionVerdict(row);
 		out.push({
 			id,
 			name: str(row?.name, id),
-			vision: agnescodeVisionOf(row),
+			vision: verdict.vision,
+			visionSource: verdict.source,
 			memberOnly: row?.memberOnly === true,
 			...multiplier === void 0 ? {} : { multiplier },
 			...displayLabel === "" ? {} : { displayLabel },

package/lib/index.js

@@ -106,7 +106,7 @@ function throttleDir() {
 * @param {() => number} now - clock source.
 * @returns {{code: string, parked: boolean, until: number|null, attempt: number}|null}
 */
-function parse(raw, now) {
+function parse$1(raw, now) {
 	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
 	const body = raw;
 	const version = num(body.version, 0);
@@ -119,7 +119,7 @@ function parse(raw, now) {
 		};
 		const migrated = migrateToCurrent(body);
 		if (migrated === null) return null;
-		return parse({
+		return parse$1({
 			...migrated,
 			version: THROTTLE_VERSION
 		}, now);
@@ -158,7 +158,7 @@ function createFileThrottleStore({ dir = throttleDir(), now = Date.now } = {}) {
 	const file = join(dir, "throttle.json");
 	return {
 		async read() {
-			return parse(await readStateJson(file), now);
+			return parse$1(await readStateJson(file), now);
 		},
 		async write(state) {
 			const temporary = temporaryOf(dir, "throttle.json");
@@ -201,7 +201,7 @@ function createMemoryThrottleStore(now = Date.now) {
 	let held = null;
 	return {
 		async read() {
-			return parse(held, now);
+			return parse$1(held, now);
 		},
 		async write(state) {
 			held = {
@@ -2260,6 +2260,171 @@ function createFileAgnescodeModelsStore(options = {}) {
 	};
 }
 
+//#endregion
+//#region src/host/agnescode-roster-seen-store.ts
+/**
+* dsh-connect-agnes-token-plan — when each AgnesCode roster id was FIRST seen.
+*
+* WHY this exists (and why it is a separate file, not `agnescode-store.ts`): the
+* gateway's catalogue rows carry no "listed since" fact — the model list is the
+* only signal that "a model is new to this user", and it is knowable only by
+* diffing today's roster against a roster THIS plugin wrote down. In memory
+* would do for one process, but the composer pill has to survive a restart to
+* be worth rendering, so the history lives in a state file of its own (the same
+* discipline as `agnescode-stats-store.ts`: one concern, one file, one reader).
+*
+* Semantics, stated once because two consumers read them:
+*  - the FIRST ever write SEEDS: it stamps the whole roster one window back and
+*    announces nothing new — an upgrade must not tell every existing user the
+*    entire roster is brand new;
+*  - an id that LEAVES the roster is dropped, so a model the gateway re-lists
+*    later counts as new again (a re-listing IS a change the reader may want);
+*  - "new" is a WINDOW, not a tick: an id first seen less than
+*    {@link AGNESCODE_ROSTER_NEW_WINDOW_MS} ago stays new across polls, so the
+*    marker does not vanish between two catalogue reads;
+*  - a roster larger than {@link AGNESCODE_ROSTER_SEEN_MAX_IDS} is a shape
+*    drift: nothing is written or announced for its duration (evicting a live
+*    id would re-announce it next poll and the count would oscillate);
+*  - an unrecognised or foreign-version file reads as "no history" (PITFALLS
+*    §23), but the FIRST write over it is REFUSED, not stomped — the ADR-006
+*    discipline. A caller that cannot write degrades to "no marker", never to a
+*    wrong one.
+*
+* The marker is only fed from a LIVE roster: the static fallback table is this
+* plugin's own text, and diffing it would announce our rows as gateway news.
+*
+* @module dsh-connect-agnes-token-plan/agnescode-roster-seen-store
+*/
+/** Shape version, bumped when the persisted form changes incompatibly. */
+const AGNESCODE_ROSTER_SEEN_VERSION = 1;
+/**
+* How long a first sighting keeps reading as "new". Seven days: long enough that
+* a user who opens the panel twice a week still catches it, short enough that a
+* stale marker cannot outlive the model it announces.
+*/
+const AGNESCODE_ROSTER_NEW_WINDOW_MS = 6048e5;
+/**
+* The largest roster one file will track — a SHAPE-DRIFT guard, not a queue.
+* A roster past the cap is read as a broken/looping producer: NOTHING is
+* written or announced for its duration, and the previous map is kept as-is.
+*/
+const AGNESCODE_ROSTER_SEEN_MAX_IDS = 200;
+/** Where the record lives: the SHARED directory, `$DSH_HOME/state/<plugin>`. */
+function agnescodeRosterSeenDir() {
+	return stateDir(name);
+}
+/**
+* Read one persisted map, keeping only well-formed entries. A non-numeric stamp
+* is dropped rather than coerced (a coerced `0` would read as "seen since 1970"
+* and mark nothing new forever). Never throws.
+* @param {unknown} raw - the persisted or posted value.
+* @returns {Record<string, number>} the usable entries (possibly empty).
+*/
+function normalizeRosterSeen(raw) {
+	const source = raw !== null && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+	const seen = {};
+	for (const [id, stamp] of Object.entries(source)) {
+		if (id === "" || typeof stamp !== "number" || !Number.isFinite(stamp) || stamp <= 0) continue;
+		seen[id] = stamp;
+	}
+	return seen;
+}
+/**
+* Keep the map ONLY while the roster is a sane size: a roster past the cap is a
+* shape drift, so NOTHING is written or announced and the previous map survives.
+* @param {Record<string, number>} next - this round's map.
+* @returns {Record<string, number>|null} the map to persist, or `null` to skip.
+*/
+function bounded(next) {
+	return Object.keys(next).length <= 200 ? next : null;
+}
+/** Is the parsed payload a shape THIS build recognises (a known version)? */
+function parse(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+	const body = raw;
+	if (body.version !== 1) return null;
+	return { seen: normalizeRosterSeen(body.seen) };
+}
+/**
+* The file-backed first-sighting history.
+* @param {object} [options] - `{ dir, now }` (a clock source for the tests).
+* @returns {object} the store.
+*/
+function createFileAgnescodeRosterSeenStore({ dir = agnescodeRosterSeenDir(), now = Date.now } = {}) {
+	const file = join(dir, "agnescode-roster-seen.json");
+	const readThrough = async () => {
+		const raw = await readStateJson(file);
+		return {
+			raw: raw === null ? null : raw,
+			parsed: parse(raw)
+		};
+	};
+	/** Persist one map (atomic). Refuses to stomp a foreign-version file (ADR-006). */
+	const persist = async (seen) => {
+		const { raw } = await readThrough();
+		if (raw !== null && parse(raw) === null) return;
+		const body = JSON.stringify({
+			version: 1,
+			seen,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		});
+		const temporary = temporaryOf(dir, "agnescode-roster-seen.json");
+		await ensureStateDir(dir);
+		await writeStateFile(file, body, { temporary });
+	};
+	return {
+		/** The whole first-sighting map. */
+		async seen() {
+			const { parsed } = await readThrough();
+			return parsed?.seen ?? {};
+		},
+		/** Whether this store has ever written a recognisable history. */
+		async isSet() {
+			const { parsed } = await readThrough();
+			return parsed !== null;
+		},
+		/**
+		* Record today's roster and answer which ids still read as new.
+		* @param {string[]} ids - the FULL live roster as the gateway just listed it.
+		* @param {number} [nowMs] - the clock (tests inject it).
+		* @returns {Promise<{newIds: string[]}>} ids first seen inside the window,
+		*   oldest first; empty on the seeding write and on a roster with nothing fresh.
+		*/
+		async note(ids, nowMs = now()) {
+			const list = Array.isArray(ids) ? ids.filter((id) => typeof id === "string" && id !== "") : [];
+			const unique = [...new Set(list)];
+			if (unique.length === 0) return { newIds: [] };
+			const nowT = Number.isFinite(nowMs) ? nowMs : now();
+			const { raw, parsed } = await readThrough();
+			if (raw !== null && parsed === null) return { newIds: [] };
+			const previous = parsed?.seen ?? {};
+			const next = {};
+			const seeded = parsed === null && raw === null;
+			for (const id of unique) {
+				const first = previous[id];
+				next[id] = typeof first === "number" && first > 0 ? Math.min(first, nowT) : seeded ? nowT - AGNESCODE_ROSTER_NEW_WINDOW_MS : nowT;
+			}
+			const trimmed = bounded(next);
+			if (trimmed === null) return { newIds: [] };
+			if (seeded || Object.keys(previous).length !== Object.keys(trimmed).length || Object.keys(trimmed).some((id) => previous[id] !== trimmed[id])) await persist(trimmed);
+			return { newIds: seeded ? [] : Object.entries(trimmed).filter(([, first]) => nowT - first < AGNESCODE_ROSTER_NEW_WINDOW_MS).sort((left, right) => left[1] - right[1]).map(([id]) => id) };
+		},
+		/** Forget the history (the next `note` reseeds). */
+		async forget() {
+			const { raw } = await readThrough();
+			if (raw !== null && parse(raw) === null) return;
+			const body = JSON.stringify({
+				version: 1,
+				seen: {},
+				updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			const temporary = temporaryOf(dir, "agnescode-roster-seen.json");
+			await ensureStateDir(dir);
+			await writeStateFile(file, body, { temporary });
+		}
+	};
+}
+
 //#endregion
 //#region src/host/switch-precedence.ts
 /**
@@ -5994,7 +6159,7 @@ function readThroughAgnescode(key, cache, inflight, produce) {
 * @returns {Function} the `off()` unregister callback.
 */
 function registerAgnescodeRoute(ctx, wiring) {
-	const { settings, agnescodeStore, agnescodeSwitch, agnescodePublisher, agnescodeModels, cache, inflight, agnescodeFetch } = wiring;
+	const { settings, agnescodeStore, agnescodeSwitch, agnescodePublisher, agnescodeModels, agnescodeRosterSeen, cache, inflight, agnescodeFetch } = wiring;
 	let lastHarvest = null;
 	let agnescodeHarvestInFlight = null;
 	let agnescodeLoginInFlight = null;
@@ -6067,6 +6232,12 @@ function registerAgnescodeRoute(ctx, wiring) {
 				const publisherState = agnescodePublisher?.state ?? null;
 				const enabledModelIds = agnescodeModels !== null && agnescodeModels !== void 0 ? await agnescodeModels.listEnabledIds().catch(() => []) : [];
 				const { usage, ...rateLimit } = await agnescodeStats.read();
+				let newModelIds;
+				if (liveRoster && agnescodeRosterSeen !== null && agnescodeRosterSeen !== void 0) {
+					const offered = roster.map((r) => r.id).filter((id) => typeof id === "string" && id !== "");
+					const noted = await agnescodeRosterSeen.note(offered);
+					if (noted.newIds.length > 0) newModelIds = noted.newIds;
+				}
 				return {
 					ok: true,
 					enabled: effectiveEnabled,
@@ -6083,6 +6254,7 @@ function registerAgnescodeRoute(ctx, wiring) {
 					models: roster,
 					modelsSource: liveRoster ? "live" : "fallback",
 					...liveRoster ? {} : { modelsAsOf: AGNESCODE_FALLBACK_ASOF },
+					...newModelIds !== void 0 ? { newModelIds } : {},
 					enabledModelIds,
 					providerRegistered: publisherState?.registered === true,
 					...publisherState?.error !== null && publisherState?.error !== void 0 ? { providerError: publisherState.error } : {},
@@ -7760,6 +7932,7 @@ function apply(ctx, config = {}, deps = {}) {
 	const agnescodeStore = createAgnescodeStore({ credentials: () => ctx.get("credentials") ?? null });
 	const agnescodeSwitch = createFileAgnescodeStore({ profile });
 	const agnescodeModels = createFileAgnescodeModelsStore({ profile });
+	const agnescodeRosterSeen = createFileAgnescodeRosterSeenStore();
 	const { publisher: agnescodePublisher, seed: agnescodeSeed } = wireAgnescodePublisher({
 		store: agnescodeStore,
 		panelSwitch: () => agnescodeSwitch.enabled().catch(() => null),
@@ -7806,6 +7979,7 @@ function apply(ctx, config = {}, deps = {}) {
 		agnescodeStore,
 		agnescodeSwitch,
 		agnescodeModels,
+		agnescodeRosterSeen,
 		agnescodePublisher,
 		agnescodeFetch: deps.agnescodeFetch ?? ((url, options) => fetch(url, options))
 	};

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.2",
   "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",