@dsh-plugins/dsh-llm-hub 1.6.1 → 1.8.0

package/CHANGELOG.md

@@ -2,6 +2,67 @@
 
 本项目遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## [1.8.0] - 2026-09-29
+
+### 🔧 适配 DSH 0.1.7 的 settings 架构（升级到 0.1.7 后配置读不到的那版）
+
+**症状**：升到 DSH 0.1.7 后，路由组「凭空消失」—— chip 不渲染，设置页路由卡是空的，
+写接口一律拒绝。数据其实好好躺在配置里，只是没人读。
+
+**根因**：0.1.7 把 settings 架构整个换掉了。`settings.register(ns, schema)` 和
+`settings.get(ns)` 双双消失（0.1.5 的 `dsh-settings` 里有 20 处 `register` 引用，
+0.1.7 是 0 处）。老代码里 `settings.register(...)` 抛 `TypeError` 被 catch 吞掉，
+`hubRegistered` 恒为 false，于是整个 `dsh-llm-hub` 段的读写全部短路。
+
+**改造**
+- 导出 `Config`，配置改由 `apply(ctx, config)` 注入（0.1.7 的官方姿势，
+  `@deepseek-ai/dsh-llm-pi-ai` 的 providers 段同款）
+- 读自己的段走 `config.routing.get()`；读**别人**的段（`llm-pi-ai` / `llm-deepseek`）
+  走 `settings.describe()` —— 0.1.7 里那是唯一的跨插件读法
+- 拆掉 `hubRegistered` 守卫（该概念已不存在）
+- 三个字段全部标 `.volatile()`：`settings.update()` 拒绝「没有 volatile 字段的条目」
+  （原话：`Plugin entry "dsh-llm-hub" has no volatile fields`），而 volatile 的语义
+  正是本插件要的 —— 路由组/预警/别名都是每次请求惰性重读的，切一次路由不该重跑 apply
+- `@deepseek-ai/schemastery` 加为 **devDependency**（静态 import 需要它才能加载；
+  运行时依赖仍是零 —— 它由 DSH 宿主提供）
+
+**配置迁移**：0.1.7 启动时把全局 `settings.yaml` 迁进 profile 的 `cordis.patch.yml`
+并把原文件改名为 `settings.yaml.imported`。本插件的段需要一条 `dsh-llm-hub` entry；
+未迁移时该段读为空，也就是上面那个症状。
+
+**验证**：157 个单测 + 门禁全过；真机确认路由组、设置页路由卡、跨插件读（balance 能
+解析出真实 key）、写路径（`routing/select` 200）全部恢复。
+
+## [1.7.0] - 2026-09-29
+
+### 🧭 路由设置卡：始终折叠，展开才编辑
+
+- **默认全折叠**，当前组也不例外（反了 1.7.0 之前的「当前组默认展开」）。进这页要回答的是「这几组各自会路由到哪」，折叠行就答完了；逐条候选是低频编辑动作，默认展开等于一进来就糊一屏表单
+- 折叠行折叠时组名是**纯文本**，展开才给输入框 —— 折叠行还摆着输入框，会让「在编辑」和「在显示」长得一样
+- 折叠行只留三件事：**会路由到哪** · **可用/总** · 组名。为此砍掉两处：
+  - 「主力 provider/model」—— 答的是「第一个是谁」，展开态第一行就有
+  - 「+N 条兜底」—— 与「4/5」同义重复
+- 新增组健康点三色：全绿（都可用）/ 琥珀（还剩几个）/ 红（一个不剩）。半可用混成全绿会让人以为不用管，混成全红会误报故障
+- 全不可用时，不可用原因顶替「会路由到」那个位置 —— 两者是同一个槽位，不是两件事
+
+**踩坑（都靠浏览器实测发现，单测一条都拦不住）**
+
+- 设置内容区只有 564px，组头扣掉序号/组名/两个按钮后摘要只剩 ~210px，真实数据的 provider/model 要 200-215px。差的这几十像素省不掉：先砍内容，仍不够才改成**换行**而不是截断 —— 砍掉的正好是判断路由最需要的模型名
+- `.dot--degraded` 一开始写在基础 `.dot` 规则**之前**：同特异度下后者生效，灰底把琥珀色盖掉，`4/5` 显示成灰点。已移到基础规则之后
+- DSH 的 client bundle 缓存很硬：`Page.reload --ignoreCache` 不足以刷新样式表，必须 `Network.clearBrowserCache`。中途因此把「源码已改、页面没变」误判成 CSS 没写对
+
+## [1.6.2] - 2026-09-29
+
+### 🐛 修复：路由快切 chip 的浮层点完不消失
+
+- 症状：在浮层里点「智能路由 / 手动模型」或点某个组，按钮高亮变了、状态也切了，浮层却纹丝不动地盖在输入框上，只能**再点一次 chip** 才收得回去（2026-09-29 浏览器实测）
+- 根因：`open` 只有 chip 按钮那一个 toggle 在写 —— 菜单内所有 `onClick` 都只调 `select()`，从不 `setOpen(false)`，也没有「点外部 / Esc」的兜底
+- 修复：
+  - 点组 / 切模式**写成功后立刻收起**浮层（写失败**不收** —— 状态没变，收起来等于把失败藏了）
+  - 点当前**已生效**的那个模式（本来就没请求可发）也收起，否则「点了完全没反应」会被当成界面卡住
+  - 补上「点浮层外面」与「Esc」两条关闭路径；只在 `open` 时挂 document 监听，卸载时卸干净
+- 测试：新增 7 条回归。React 桩补上 setter / ref / effect 记录 —— 「点完浮层有没有收起」看渲染树验不出来，发生在事件回调里，只能观察状态被写成了什么
+
 ## [1.6.1] - 2026-09-28
 
 ### 🧹 去掉模型页底部的「热门大模型一键装配」，改为添加时按厂商匹配

package/lib/client.js

@@ -168,6 +168,10 @@ window.__ModuleLoader__.load({
 				routingPrimary: '主力',
 				routingNoRecommendation: '全部不可用',
 				routingLoading: '路由解析中…',
+				routingNav: '路由',
+				// 只讲「这页怎么改」。原先这里还复述了一遍「按顺序取第一个可用的」，
+				// 而下面的规则块和模式提示已经各讲了一次 —— 同一件事在三屏之内说了三遍。
+				routingPageDesc: '每个组是一串按优先级排的模型：第一个是主力，后面依次兜底。点「设为主力」或直接在下拉框里换模型来调整顺序。',
 				routeChipSmart: '智能',
 				routeChipManual: '手动',
 				routeChipModeSmart: '智能路由',
@@ -180,10 +184,18 @@ window.__ModuleLoader__.load({
 				routeRuleText: '按组内顺序取第一个可用；探测失败或额度耗尽的自动跳过；全不可用则保持原样（fail-open）。顺序即优先级 —— 固定成本（包月/订阅）放前面，按量付费放后面兜底。',
 				routeSmartNotice: '已接管：输入框的模型下拉只作参考，实际请求按本卡规则走（实时结果见聊天框左侧 chip）。',
 				routeManualNotice: '未接管：请求还是用你在模型下拉里选的；点「智能路由」才按本卡规则自动切。',
-				routeEditHint: '编辑后点保存写入 settings.dsh-llm-hub.routing',
+				routeEditHint: '改动会自动保存到 settings.dsh-llm-hub.routing',
 				routeSave: '保存',
 				routeSaved: '已保存',
 				routeSaveFailed: '保存失败',
+				routeSaving: '保存中…',
+				routeAutoSaved: '已自动保存',
+				routeRetry: '重试',
+				routeEdit: '编辑',
+				routeCollapse: '收起',
+				routeMakePrimary: '设为主力',
+				routeNotePlaceholder: '备注',
+				routeGroupNotePlaceholder: '这组的备注（比如：公司报销额度，先用它）',
 				routeAddCandidate: '+ 添加候选',
 				routeAddProvider: '提供方',
 				routeAddModel: '模型',
@@ -318,6 +330,8 @@ window.__ModuleLoader__.load({
 				routingPrimary: 'primary',
 				routingNoRecommendation: 'none available',
 				routingLoading: 'resolving routing…',
+				routingNav: 'Routing',
+				routingPageDesc: 'Each group is a priority-ordered list: the first is primary, the rest follow as fallbacks. Use “Make primary” or swap the model in a dropdown to change the order.',
 				routeChipSmart: 'Smart',
 				routeChipManual: 'Manual',
 				routeChipModeSmart: 'Smart routing',
@@ -330,7 +344,15 @@ window.__ModuleLoader__.load({
 				routeRuleText: 'First usable candidate in group order wins; failed probes and exhausted quotas are skipped; if none is usable the original selection is kept (fail-open). Order is priority — fixed-cost plans first, metered pay-as-you-go last.',
 				routeSmartNotice: 'Takeover is on: the composer model dropdown is only a reference; requests follow this card (live result shows in the chip beside the composer).',
 				routeManualNotice: 'Not taking over: requests still use the model you picked in the dropdown. Switch to Smart routing to auto-select.',
-				routeEditHint: 'Save writes settings.dsh-llm-hub.routing',
+				routeEditHint: 'Changes auto-save to settings.dsh-llm-hub.routing',
+				routeSaving: 'Saving…',
+				routeAutoSaved: 'Auto-saved',
+				routeRetry: 'Retry',
+				routeEdit: 'Edit',
+				routeCollapse: 'Collapse',
+				routeMakePrimary: 'Make primary',
+				routeNotePlaceholder: 'Note',
+				routeGroupNotePlaceholder: 'Group note (e.g. company quota, use first)',
 				routeSave: 'Save',
 				routeSaved: 'Saved',
 				routeSaveFailed: 'Save failed',
@@ -589,15 +611,20 @@ window.__ModuleLoader__.load({
 				'.dsh-llm-hub-routing__active{color:var(--dsw-alias-label-primary)}',
 				'.dsh-llm-hub-routing__rows{display:flex;flex-direction:column;gap:2px}',
 				'.dsh-llm-hub-routing__row{display:flex;align-items:center;gap:6px;flex-wrap:wrap;padding:2px 4px}',
-				'.dsh-llm-hub-routing__role{display:inline-flex;align-items:center;height:16px;padding:0 5px;',
+				'.dsh-llm-hub-routing__role{box-sizing:border-box;display:inline-flex;align-items:center;justify-content:center;min-width:34px;height:18px;padding:0 6px;white-space:nowrap;',
 				'border-radius:3px;border:.5px solid var(--dsw-alias-border-l2);',
-				'background:transparent;font-size:10px;color:var(--dsw-alias-label-secondary)}',
+				'background:transparent;font-size:10.5px;color:var(--dsw-alias-label-secondary);transition:all .15s ease}',
+				// 主力：品牌色徽标，与兜底行的中性色拉开差距
+				'.dsh-llm-hub-routing__role.is-primary{',
+				'color:var(--dsw-alias-brand-primary,#3b82f6);',
+				'border-color:var(--dsw-alias-brand-primary,#3b82f6);',
+				'background:var(--dsw-alias-bg-layer-3,rgba(255,255,255,.06));font-weight:600}',
 				'.dsh-llm-hub-routing__name{color:var(--dsw-alias-label-primary);font-weight:600}',
 				// capability 标识：思考 / 多模态。两枚 chip 同形，左思考、右图像；
 				// 边色走 state 提示色，跟健康状态 chip 区分开 —— 一个说「能干什么」，
 				// 一个说「能不能用」。
 				'.dsh-llm-hub-routing__reasoning,.dsh-llm-hub-routing__multimodal{',
-				'display:inline-flex;align-items:center;height:16px;padding:0 6px;',
+				'display:inline-flex;align-items:center;justify-content:center;height:18px;min-width:20px;padding:0 3px;',
 				'border-radius:3px;font-size:10px;line-height:14px;font-weight:500;',
 				'background:transparent;cursor:help}',
 				// 思考：走 warn 主题色（消耗更多 token、需要警觉）
@@ -643,31 +670,99 @@ window.__ModuleLoader__.load({
 				'font-family:ui-monospace,SFMono-Regular,monospace;word-break:break-all;line-height:1.4}',
 				// 智能路由编辑器（设置页路由卡）
 				'.dsh-llm-hub-routing__modes{display:flex;gap:4px;margin-left:auto}',
-				'.dsh-llm-hub-routing__rule{display:flex;gap:6px;align-items:flex-start;font-size:10.5px;line-height:1.5;',
-				'color:var(--dsw-alias-label-secondary);padding:6px 8px;border-radius:6px;background:var(--dsw-alias-bg-layer-2)}',
-				'.dsh-llm-hub-routing__rule-tag{flex:none;font-weight:600;color:var(--dsw-alias-label-primary)}',
+				// 规则说明：去掉盒子背景，只留淡灰单行注脚，视觉权重要低于第 2 行「将路由到…」
+				'.dsh-llm-hub-routing__rule{display:flex;gap:6px;align-items:center;flex-wrap:wrap;font-size:10.5px;line-height:1.5;',
+				'color:var(--dsw-alias-label-tertiary);padding:0}',
+				'.dsh-llm-hub-routing__rule-tag{flex:none;font-weight:500;color:var(--dsw-alias-label-secondary)}',
 				'.dsh-llm-hub-routing__now{font-size:11px;color:var(--dsw-alias-label-primary);font-weight:600}',
 				'.dsh-llm-hub-routing__groups{display:flex;flex-direction:column;gap:6px;margin-top:8px}',
-				'.dsh-llm-hub-routing__group{border:.5px solid var(--dsw-alias-border-l1);border-radius:6px;padding:6px 8px;display:flex;flex-direction:column;gap:5px}',
-				'.dsh-llm-hub-routing__group.is-active{border-color:var(--dsw-alias-state-warn-primary)}',
+				'.dsh-llm-hub-routing__group{border:.5px solid var(--dsw-alias-border-l1);border-radius:6px;padding:6px 8px;display:flex;flex-direction:column;gap:5px;transition:border-color .15s ease,box-shadow .15s ease}',
+				// 当前组：边框降一档 + 顶部 brand 细线高亮，替代原本的 warn 四边描边
+				'.dsh-llm-hub-routing__group.is-active{border-color:var(--dsw-alias-border-l2,var(--dsw-alias-border-l1));box-shadow:inset 0 1px 0 var(--dsw-alias-brand-primary,#3b82f6)}',
 				'.dsh-llm-hub-routing__group-top{display:flex;align-items:center;gap:6px;flex-wrap:wrap}',
-				'.dsh-llm-hub-routing__group-toggle{border:0;background:0 0;padding:0;cursor:pointer;font:inherit;font-size:11px;color:var(--dsw-alias-label-secondary)}',
+				'.dsh-llm-hub-routing__group-toggle{display:inline-flex;align-items:center;justify-content:center;height:22px;padding:0 8px;margin-left:4px;',
+				'border:.5px solid var(--dsw-alias-border-l1);border-radius:4px;background:transparent;cursor:pointer;',
+				'font:inherit;font-size:11px;line-height:1;color:var(--dsw-alias-label-secondary);white-space:nowrap;transition:all .15s ease}',
+				'.dsh-llm-hub-routing__group-toggle:hover{color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-border-l2,var(--dsw-alias-border-l1));background:var(--dsw-alias-bg-layer-2)}',
 				'.dsh-llm-hub-routing__group-order{display:flex;align-items:center;gap:2px;flex:none}',
-				'.dsh-llm-hub-routing__group-move{border:0;background:0 0;padding:0 2px;cursor:pointer;font:inherit;font-size:10px;',
-				'color:var(--dsw-alias-label-tertiary);line-height:1}',
-				'.dsh-llm-hub-routing__group-move:hover:not(:disabled){color:var(--dsw-alias-label-primary)}',
+				'.dsh-llm-hub-routing__group-move{display:inline-flex;align-items:center;justify-content:center;width:18px;height:22px;',
+				'border:0;background:transparent;padding:0;cursor:pointer;font:inherit;font-size:12px;line-height:1;',
+				'color:var(--dsw-alias-label-tertiary);border-radius:3px;transition:all .15s ease}',
+				'.dsh-llm-hub-routing__group-move:hover:not(:disabled){color:var(--dsw-alias-label-primary);background:var(--dsw-alias-bg-layer-2)}',
 				'.dsh-llm-hub-routing__group-move:disabled{opacity:.25;cursor:default}',
-				'.dsh-llm-hub-routing__group-state b{font-weight:600;color:var(--dsw-alias-label-primary)}',
-				'.dsh-llm-hub-routing__group-more{color:var(--dsw-alias-label-tertiary)}',
-				'.dsh-llm-hub-routing__group-would{color:var(--dsw-alias-state-warn-primary);margin-left:5px}',
 				'.dsh-llm-hub-routing__group-empty{font-style:normal;color:var(--dsw-alias-label-tertiary)}',
-				'.dsh-llm-hub-routing__group-label{flex:0 0 128px;width:128px;box-sizing:border-box;height:22px;padding:0 6px;border-radius:4px;',
-				'border:.5px solid var(--dsw-alias-border-l1);background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary);font:inherit;font-size:11px}',
-				'.dsh-llm-hub-routing__group-state{flex:1;min-width:0;font-size:10.5px;color:var(--dsw-alias-label-secondary);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
+				// 折叠行（1.6.2）：组名 + 「将路由到 X」+ 主力 + 兜底条数，一行读完。
+				// 组名给固定宽度，与下面展开态的 label 输入框同宽 —— 收起/展开时这一列不跳。
+				'.dsh-llm-hub-routing__group-name{flex:0 0 112px;min-width:0;overflow:hidden;text-overflow:ellipsis;',
+				'white-space:nowrap;font-size:11.5px;font-weight:600;color:var(--dsw-alias-label-primary)}',
+				'.dsh-llm-hub-routing__group-label{flex:0 0 112px;width:112px;box-sizing:border-box;height:22px;padding:0 8px;border-radius:5px;',
+				'border:.5px solid var(--dsw-alias-border-l1);background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary);',
+				'font:inherit;font-size:11px;outline:none;transition:border-color .15s ease}',
+				'.dsh-llm-hub-routing__group-label:focus{border-color:var(--dsw-alias-brand-primary,#3b82f6)}',
+				// 允许换行，不允许截断（1.6.2 浏览器实测后改的）。设置内容区只有 564px，
+				// 扣掉序号/组名/两个按钮，摘要只剩 ~210px；而真实数据的 provider/model
+				// 要 200-215px —— 差的这几十像素，省不掉，只能换行。之前用 nowrap+ellipsis
+				// 把「→ modelgo-gateway/claude-sonnet-5」砍成「→ modelgo-gatewa…」，
+				// 砍掉的正好是判断路由结果最需要的那段：看不出是 sonnet-5 还是别的。
+				// 组头因此高一行，是「读得全」该付的代价。
+				'.dsh-llm-hub-routing__group-state{flex:1;min-width:0;font-size:10.5px;line-height:1.5;',
+				'color:var(--dsw-alias-label-secondary);display:flex;flex-wrap:wrap;align-items:center;gap:2px 8px}',
+				// 断行点放在 provider 与 model 之间的斜杠上：读起来是两条完整信息，
+				// 而不是把一个词从中间劈开。break-all 是兜底 —— provider id 里也有长词。
+				'.dsh-llm-hub-routing__group-would{font-weight:600;color:var(--dsw-alias-label-primary);',
+				'min-width:0;word-break:break-word;overflow-wrap:anywhere}',
+				// 可用/总：紧跟在「将路由到」后面，且**不参与压缩** —— 压它等于把
+				// 「还剩几个能兜」这个答案藏掉，而它只要 30px。
+				'.dsh-llm-hub-routing__group-count{flex:none;display:inline-flex;align-items:center;gap:3px;',
+				'color:var(--dsw-alias-label-tertiary);font-variant-numeric:tabular-nums}',
+				'.dsh-llm-hub-routing__group-count .dsh-llm-hub-routing__dot{margin:0}',
 				'.dsh-llm-hub-routing__candidates{display:flex;flex-direction:column;gap:3px;padding-top:2px}',
+				// 1.7.0 路由编辑器：序号徽标、编辑按钮、原地下拉、备注、放大的操作按钮、自动保存状态
+				'.dsh-llm-hub-routing__group-index{display:inline-flex;align-items:center;justify-content:center;min-width:18px;height:22px;border-radius:4px;',
+				'padding:0 6px;font-size:10.5px;font-weight:600;background:var(--dsw-alias-bg-layer-3,rgba(255,255,255,.08));color:var(--dsw-alias-label-secondary)}',
+				// 全组共用一张网格：行与 pick 都是 display:contents，列宽由整组一起决定 ——
+				// 各行自成网格时，右侧标签列按本行内容伸缩，模型下拉的右边缘每行都不一样（浏览器实测 908 vs 845px）。
+				'.dsh-llm-hub-routing-page{display:flex;flex-direction:column;gap:6px}',
+				'.dsh-llm-hub-routing-page__head{display:flex;align-items:center;justify-content:space-between;gap:12px}',
+				'.dsh-llm-hub-routing__group-delete{margin-left:4px;white-space:nowrap}',
+				'.dsh-llm-hub-routing-page__title{margin:0;font-size:18px;font-weight:600;color:var(--dsw-alias-label-primary)}',
+				'.dsh-llm-hub-routing-page__desc{margin:0 0 8px;font-size:12.5px;line-height:1.6;color:var(--dsw-alias-label-secondary)}',
+				'.dsh-llm-hub-routing__candidates{display:grid;grid-template-columns:40px minmax(0,1fr) minmax(0,1.3fr);gap:4px 6px;align-items:center}',
+				'.dsh-llm-hub-routing__candidates>:not(.dsh-llm-hub-routing__row){grid-column:1/-1}',
+				'.dsh-llm-hub-routing__candidates .dsh-llm-hub-routing__row,.dsh-llm-hub-routing__candidates .dsh-llm-hub-routing__pick{display:contents}',
+				'.dsh-llm-hub-routing__candidates .dsh-llm-hub-routing__role{grid-column:1;justify-self:start;margin-top:6px}',
+				'.dsh-llm-hub-routing__candidates .dsh-llm-hub-routing__pick .dsh-llm-hub-routing__select{width:100%;min-width:0;max-width:none;margin-top:6px}',
+				'.dsh-llm-hub-routing__candidates .dsh-llm-hub-routing__name{grid-column:2/4;min-width:0;margin-top:6px}',
+				'.dsh-llm-hub-routing__line2{grid-column:2/-1;display:flex;align-items:center;gap:6px;min-width:0}',
+				// 标签区给固定宽度并靠右：有无「思考/图像」标签的行，备注框都一样宽，右边缘对齐。
+				'.dsh-llm-hub-routing__meta{display:inline-flex;align-items:center;justify-content:flex-end;gap:4px;white-space:nowrap;flex:none;width:78px}',
+				'.dsh-llm-hub-routing__dot{display:inline-block;flex:none;width:7px;height:7px;border-radius:50%;margin:0 2px;cursor:help;background:var(--dsw-alias-label-tertiary)}',
+				'.dsh-llm-hub-routing__dot--available{background:var(--dsw-alias-state-success-primary)}',
+				'.dsh-llm-hub-routing__dot--unavailable{background:var(--dsw-alias-state-error-primary)}',
+				// 半可用单独一色：全绿和全红之间还有「还剩几个」这个状态，
+				// 混成全绿会让人以为不用管，混成全红会误报故障。
+				'.dsh-llm-hub-routing__dot--degraded{background:var(--dsw-alias-state-warn-primary)}',
+				'.dsh-llm-hub-routing__candidates .dsh-llm-hub-routing__row .dsh-llm-hub-routing__note{flex:1 1 auto;width:auto;max-width:none;min-width:60px}',
+				// 同理固定宽度：主力行没有「设为主力」，按钮区只有 77px（其余 141px），备注右边缘会错开 64px。
+				'.dsh-llm-hub-routing__ops{display:inline-flex;justify-content:flex-end;gap:4px;white-space:nowrap;flex:none;min-width:141px}',
+				'.dsh-llm-hub-routing__note{box-sizing:border-box;height:22px;padding:0 8px;border-radius:4px;',
+				'border:.5px solid var(--dsw-alias-border-l1);background:transparent;color:var(--dsw-alias-label-secondary);',
+				'font:inherit;font-size:10.5px;flex:1 1 120px;min-width:90px;max-width:260px;outline:none;transition:border-color .15s ease}',
+				'.dsh-llm-hub-routing__note:focus{border-color:var(--dsw-alias-brand-primary,#3b82f6)}',
+				'.dsh-llm-hub-routing__note::placeholder{color:var(--dsw-alias-label-tertiary)}',
+				// 候选区是纵向 flex：note 的 flex-basis 120px 在这里会变成「高 120px」，组备注必须脱离 flex 伸缩。
+				'.dsh-llm-hub-routing__note--group{display:block;flex:none;width:100%;max-width:none;margin:2px 0 6px}',
+				'.dsh-llm-hub-routing__op{border:.5px solid var(--dsw-alias-border-l1);background:transparent;border-radius:4px;min-width:22px;height:22px;padding:0 6px;cursor:pointer;font:inherit;font-size:11.5px;color:var(--dsw-alias-label-secondary)}',
+				'.dsh-llm-hub-routing__op:hover:not(:disabled){color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-border-l2,var(--dsw-alias-border-l1))}',
+				'.dsh-llm-hub-routing__op:disabled{opacity:.3;cursor:default}',
+				'.dsh-llm-hub-routing__op--danger:hover:not(:disabled){color:var(--dsw-alias-state-error-primary)}',
+				'.dsh-llm-hub-routing__status{font-size:10.5px;color:var(--dsw-alias-label-tertiary)}',
+				'.dsh-llm-hub-routing__status.is-fail{color:var(--dsw-alias-state-error-primary)}',
 				'.dsh-llm-hub-routing__add{display:flex;align-items:center;gap:5px;flex-wrap:wrap;font-size:10.5px;color:var(--dsw-alias-label-secondary);padding-top:4px}',
-				'.dsh-llm-hub-routing__select{box-sizing:border-box;height:22px;padding:0 4px;border-radius:4px;border:.5px solid var(--dsw-alias-border-l1);',
-				'background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary);font:inherit;font-size:11px;max-width:170px}',
+				'.dsh-llm-hub-routing__select{box-sizing:border-box;height:22px;padding:0 6px;border-radius:4px;border:.5px solid var(--dsw-alias-border-l1);',
+				'background:var(--dsw-alias-bg-layer-2);color:var(--dsw-alias-label-primary);font:inherit;font-size:11px;max-width:170px;outline:none;',
+				'transition:border-color .15s ease;cursor:pointer}',
+				'.dsh-llm-hub-routing__select:focus{border-color:var(--dsw-alias-brand-primary,#3b82f6)}',
 				'.dsh-llm-hub-routing__actions{display:flex;align-items:center;gap:8px;flex-wrap:wrap;padding-top:6px;border-top:.5px solid var(--dsw-alias-border-l1);margin-top:8px}',
 				'.dsh-llm-hub-routing__hint{font-size:10px;color:var(--dsw-alias-label-tertiary)}',
 				'.dsh-llm-hub-routing__mm{display:inline-flex;align-items:center;margin-left:4px;font-size:10px;cursor:help;',
@@ -1675,6 +1770,8 @@ window.__ModuleLoader__.load({
 			const [state, setState] = React.useState(null)
 			const [open, setOpen] = React.useState(false)
 			const [busy, setBusy] = React.useState(false)
+			// 浮层根节点：判断「这次点击算不算点在浮层外面」要用它。
+			const rootRef = React.useRef(null)
 			const query = React.useCallback(() => {
 				fetch(ROUTING_STATE_URL, { headers: { accept: 'application/json' } })
 					.then((res) => res.json())
@@ -1686,6 +1783,25 @@ window.__ModuleLoader__.load({
 				const interval = setInterval(query, 30000)
 				return () => clearInterval(interval)
 			}, [query])
+			// 点浮层外面 / 按 Esc 收起来。少了这条，用户在浮层里做完选择后
+			// 手会先伸向输入框 —— 浮层却还盖在上面，不点第二次 chip 就挡着视线。
+			// 只在 open 时挂监听：关着的时候不留全局 handler。
+			// 必须写在下面那个 `state === null` 早返回之前 —— hooks 不能条件调用。
+			React.useEffect(() => {
+				if (!open) return undefined
+				const onPointerDown = (event) => {
+					const root = rootRef.current
+					if (root !== null && root !== undefined && typeof root.contains === 'function' && root.contains(event.target)) return
+					setOpen(false)
+				}
+				const onKeyDown = (event) => { if (event.key === 'Escape') setOpen(false) }
+				document.addEventListener('mousedown', onPointerDown)
+				document.addEventListener('keydown', onKeyDown)
+				return () => {
+					document.removeEventListener('mousedown', onPointerDown)
+					document.removeEventListener('keydown', onKeyDown)
+				}
+			}, [open])
 			// 一个组都没有：chip 无事可做，不渲染（配置在 settings.yaml 里加）。
 			if (state === null || !Array.isArray(state.groups) || state.groups.length === 0) return null
 			ensureStyle()
@@ -1708,7 +1824,10 @@ window.__ModuleLoader__.load({
 					body: JSON.stringify(patch)
 				})
 					.then((res) => res.json())
-					.then((body) => { if (body !== null && typeof body === 'object' && body.ok === true) setState(body) })
+					// 选完即收：浮层是「选一个值」的一次性动作，不是常驻面板。
+					// 留着不关，用户会以为没点上，只能再点一次 chip 才收得回去。
+					// 写失败时**不关** —— 状态没变，收起来等于把失败藏了。
+					.then((body) => { if (body !== null && typeof body === 'object' && body.ok === true) { setState(body); setOpen(false) } })
 					.catch(() => {})
 					.finally(() => { setBusy(false); query() })
 			}
@@ -1724,12 +1843,14 @@ window.__ModuleLoader__.load({
 					h('button', {
 						type: 'button',
 						className: `dsh-llm-hub-route__mode${isSmart ? ' is-on' : ''}`,
-						onClick: () => { if (!isSmart) select({ mode: 'smart' }) }
+						// 点当前已生效的那个模式：没有请求要发，但**照样收起浮层**。
+						// 否则「点了完全没反应」，用户会当成界面卡住反复点。
+						onClick: () => { if (isSmart) setOpen(false); else select({ mode: 'smart' }) }
 					}, `⚡ ${t('routeChipModeSmart')}`),
 					h('button', {
 						type: 'button',
 						className: `dsh-llm-hub-route__mode${!isSmart ? ' is-on' : ''}`,
-						onClick: () => { if (isSmart) select({ mode: 'manual' }) }
+						onClick: () => { if (!isSmart) setOpen(false); else select({ mode: 'manual' }) }
 					}, t('routeChipModeManual'))),
 				...state.groups.map((group) => h('button', {
 					key: group.id,
@@ -1752,7 +1873,7 @@ window.__ModuleLoader__.load({
 						? h('span', { className: 'dsh-llm-hub-route__hint' }, group.reason)
 						: null)),
 				h('div', { className: 'dsh-llm-hub-route__hint' }, t('routeRuleText'))) : null
-			return h('div', { className: 'dsh-llm-hub-route' },
+			return h('div', { className: 'dsh-llm-hub-route', ref: rootRef },
 				h('button', {
 					type: 'button',
 					className: chipClass,
@@ -1793,22 +1914,29 @@ window.__ModuleLoader__.load({
 			// candidates[0] = 主力（primary），其余是 fallback —— 与 settings 形态一一对应。
 			const [draft, setDraft] = React.useState(null)
 			const [activeGroup, setActiveGroup] = React.useState('')
-			const [expanded, setExpanded] = React.useState('')
+			// null = 还没手动开合过，此时默认展开当前组 —— 一进来就能看到、能改。
+			const [expanded, setExpanded] = React.useState(null)
 			const [picker, setPicker] = React.useState({ provider: '', model: '' })
 			const [busy, setBusy] = React.useState(false)
 			const [notice, setNotice] = React.useState(null)
 			// 保存过/刚拉回的 draft 指纹：用它判断「脏」，避免后台刷新把用户正在编辑的内容冲掉。
 			const [savedKey, setSavedKey] = React.useState('')
 			// label 归一成「空 = null」：草稿里是 ''，服务端回的是 null，不归一会永远显示「未保存」。
-			const draftKeyOf = (report) => JSON.stringify((report?.groups ?? []).map((group) => [
-				group.id,
-				group.label ? group.label : null,
-				(group.candidates ?? []).map((candidate) => `${candidate.provider}/${candidate.model}`)
-			]))
+			// 空组（刚点「新建组」、还没加候选）不参与比较：服务端会丢弃空组，
+			// 若把它算成「脏」，自动保存会一直重试、而且保存回读后这个组就消失了。
+			const draftKeyOf = (report) => JSON.stringify((report?.groups ?? [])
+				.filter((group) => (group.candidates ?? []).length > 0)
+				.map((group) => [
+					group.id,
+					group.label ? group.label : null,
+					group.note ? group.note : null,
+					(group.candidates ?? []).map((candidate) => [`${candidate.provider}/${candidate.model}`, candidate.note ? candidate.note : null])
+				]))
 			const draftFrom = (report) => (report.groups ?? []).map((group) => ({
 				id: group.id,
 				label: group.label ?? '',
-				candidates: group.candidates.map((candidate) => ({ provider: candidate.provider, model: candidate.model }))
+				note: group.note ?? '',
+				candidates: group.candidates.map((candidate) => ({ provider: candidate.provider, model: candidate.model, note: candidate.note ?? '' }))
 			}))
 			// force=true 只用在一处：保存成功后的回读 —— 那时服务端就是权威。
 			// 其余时候（挂载、切模式、轮询）保留用户正在编辑的草稿。
@@ -1831,16 +1959,25 @@ window.__ModuleLoader__.load({
 					.then((body) => { if (body !== null && typeof body === 'object' && body.ok === true && Array.isArray(body.providers)) setCatalog(body.providers) })
 					.catch(() => {})
 			}, [loadState])
+			// 自动保存的防抖定时器。必须写在下面那个 `state === null` 提前 return 之前 ——
+			// hooks 不能出现在条件分支后面；save 定义在后面，所以经 ref 调用。
+			const saveRef = React.useRef(null)
+			const draftKey = draft === null ? '' : draftKeyOf({ groups: draft })
+			React.useEffect(() => {
+				if (draft === null || draftKey === savedKey || notice === 'fail' || notice === 'saving') return undefined
+				const timer = setTimeout(() => { if (typeof saveRef.current === 'function') saveRef.current() }, 800)
+				return () => clearTimeout(timer)
+			}, [draftKey, savedKey, notice])
 			if (state === null) {
-				return h('div', { className: 'dsh-llm-hub-routing' },
-					h('div', { className: 'dsh-llm-hub-routing__head' },
-						h('span', { className: 'dsh-llm-hub-routing__title' }, t('routingTitle')),
+				return h('div', { className: 'dsh-llm-hub-routing dsh-llm-hub-routing-page' },
+					h('div', { className: 'dsh-llm-hub-routing-page__head' },
+						h('h2', { className: 'dsh-llm-hub-routing-page__title' }, t('routingNav')),
 						h('span', null, t('routingLoading'))))
 			}
 			ensureStyle()
 			const isSmart = state.mode === 'smart'
 			const groups = draft ?? []
-			const isDirty = draft !== null && draftKeyOf({ groups: groups.map((group) => ({ id: group.id, label: group.label, candidates: group.candidates })) }) !== savedKey
+			const isDirty = draft !== null && draftKeyOf({ groups }) !== savedKey
 			const post = (url, payload) => fetch(url, {
 				method: 'POST',
 				headers: { 'content-type': 'application/json', accept: 'application/json' },
@@ -1859,18 +1996,23 @@ window.__ModuleLoader__.load({
 					.then((body) => { if (body?.ok === true) adopt(body) })
 					.catch(() => setNotice('fail'))
 			}
+			// 自动保存（1.7.0）：原来要去卡片最底下点「保存」，改完就走的人会丢改动。
+			// 草稿变「脏」后 800ms 防抖落盘；回读**不强制**覆盖草稿 —— 用户可能还在打字。
+			// 只提交有候选的组（空组服务端本来就丢弃），草稿里的空组留在页面上。
 			const save = () => {
-				if (groups.length === 0) return
+				const payload = groups.filter((group) => group.candidates.length > 0)
+				if (payload.length === 0) return
 				setBusy(true)
-				setNotice(null)
-				post(ROUTING_CONFIG_URL, { groups, activeGroup })
+				setNotice('saving')
+				post(ROUTING_CONFIG_URL, { groups: payload, activeGroup })
 					.then((body) => {
-						if (body?.ok === true) { adopt(body, true); setNotice('saved') }
+						if (body?.ok === true) { adopt(body); setNotice('saved') }
 						else setNotice('fail')
 					})
 					.catch(() => setNotice('fail'))
 					.finally(() => setBusy(false))
 			}
+			saveRef.current = save
 			// ── 草稿编辑（全部是纯函数式更新，不碰服务端；保存才落盘）──
 			const editGroup = (id, mutate) => setDraft(groups.map((group) => (group.id === id ? mutate(group) : group)))
 			const moveCandidate = (id, index, delta) => editGroup(id, (group) => {
@@ -1900,26 +2042,64 @@ window.__ModuleLoader__.load({
 				next.splice(target, 0, item)
 				setDraft(next)
 			}
+			const updateCandidate = (id, index, patch) => editGroup(id, (group) => ({
+				...group,
+				candidates: group.candidates.map((candidate, i) => (i === index ? { ...candidate, ...patch } : candidate))
+			}))
+			// 换提供方时模型跟着换成该家第一个模型 —— 留着旧 model 名几乎一定是错的组合。
+			const changeProvider = (id, index, provider) => {
+				const entry = catalog.find((item) => item.id === provider)
+				updateCandidate(id, index, { provider, model: entry?.models?.[0]?.id ?? '' })
+			}
+			const makePrimary = (id, index) => editGroup(id, (group) => {
+				const next = [...group.candidates]
+				const [item] = next.splice(index, 1)
+				return { ...group, candidates: [item, ...next] }
+			})
 			const removeCandidate = (id, index) => editGroup(id, (group) => ({ ...group, candidates: group.candidates.filter((_, i) => i !== index) }))
 			const addCandidate = (id) => {
 				const provider = picker.provider
 				const model = picker.model
 				if (provider === '' || model === '') return
-				editGroup(id, (group) => ({ ...group, candidates: [...group.candidates, { provider, model }] }))
+				editGroup(id, (group) => ({ ...group, candidates: [...group.candidates, { provider, model, note: '' }] }))
 				setPicker({ provider: '', model: '' })
 			}
 			const addGroup = () => {
 				let index = groups.length + 1
 				let id = `group-${index}`
 				while (groups.some((group) => group.id === id)) { index += 1; id = `group-${index}` }
-				setDraft([...groups, { id, label: '', candidates: [] }])
+				setDraft([...groups, { id, label: '', note: '', candidates: [] }])
 				setExpanded(id)
 			}
 			const removeGroup = (id) => {
 				setDraft(groups.filter((group) => group.id !== id))
-				if (expanded === id) setExpanded('')
+				if (expanded === id) setExpanded(null)
+			}
+			const catalogEntryFor = (provider) => catalog.find((item) => item.id === provider)
+			const modelOptionsFor = (provider, current) => {
+				const ids = (catalogEntryFor(provider)?.models ?? []).map((model) => model.id)
+				return current && !ids.includes(current) ? [current, ...ids] : ids
 			}
 			const stateChipClass = (value) => `dsh-llm-hub-health__chip dsh-llm-hub-health__chip--${value ?? 'unknown'}`
+			/**
+			 * 一组里探测为「可用」的候选数。探不到（没记录）时返回 0 —— 折叠行要报
+			 * 「0/N」而不是假装健康：未探明和不可用在用户眼里同样是「先别指望它」。
+			 * @param {object | undefined} live - /routing/state 里该组的快照。
+			 * @returns {number} 可用候选数。
+			 */
+			const availableOf = (live) => (live?.candidates ?? []).filter((item) => item.state === 'available').length
+			/**
+			 * 折叠行那个健康点的颜色：全可用 / 还剩几个 / 一个都不剩。
+			 * 不用单一绿点，绿点只说「还行」，说不出「还剩几个能兜」。
+			 * @param {object | undefined} live - 该组快照。
+			 * @returns {'available' | 'degraded' | 'unavailable'}
+			 */
+			const groupDotState = (live) => {
+				const total = live?.candidates?.length ?? 0
+				const available = availableOf(live)
+				if (total === 0 || available === 0) return 'unavailable'
+				return available < total ? 'degraded' : 'available'
+			}
 			/**
 			 * 一个候选是否多模态（输入含 text 之外的模态，典型是 image）。
 			 *
@@ -1963,8 +2143,9 @@ window.__ModuleLoader__.load({
 				if (group?.wouldRoute) return `${t('routeChipWouldRoute')}: ${group.wouldRoute.provider}/${group.wouldRoute.model}`
 				return group?.reason ?? t('routeChipReasonNone')
 			}
-			const header = h('div', { className: 'dsh-llm-hub-routing__head' },
-				h('span', { className: 'dsh-llm-hub-routing__title' }, t('routingTitle')),
+			// 页头（1.7.0）：「路由」标题与模式开关同一行。原来页头一个「路由」、卡内又一个「当前路由」，重复。
+			const header = h('div', { className: 'dsh-llm-hub-routing-page__head' },
+				h('h2', { className: 'dsh-llm-hub-routing-page__title' }, t('routingNav')),
 				h('div', { className: 'dsh-llm-hub-routing__modes' },
 					h('button', {
 						type: 'button',
@@ -1976,25 +2157,29 @@ window.__ModuleLoader__.load({
 						className: `dsh-llm-hub-route__mode${!isSmart ? ' is-on' : ''}`,
 						onClick: () => { if (isSmart) setMode('manual') }
 					}, t('routeChipModeManual'))))
-			const rule = h('div', { className: 'dsh-llm-hub-routing__rule' },
+				const pageDesc = h('p', { className: 'dsh-llm-hub-routing-page__desc' }, t('routingPageDesc'))
+				const rule = h('div', { className: 'dsh-llm-hub-routing__rule' },
 				h('span', { className: 'dsh-llm-hub-routing__rule-tag' }, t('routeRuleTitle')),
 				h('span', null, t('routeRuleText')))
-			const noticeLine = h('div', { className: 'dsh-llm-hub-routing__reason' },
-				isSmart ? t('routeSmartNotice') : t('routeManualNotice'))
+			// 只在智能路由真的接管时提示。手动模式下那行「请求还是用你在模型下拉里
+			// 选的」讲的是当前高亮的按钮本身，没有新信息，却常驻占一整行；
+			// 而接管后「下拉只作参考」是按钮推不出来的，必须留着。
+			const noticeLine = isSmart
+				? h('div', { className: 'dsh-llm-hub-routing__reason' }, t('routeSmartNotice'))
+				: null
 			const nowLine = h('div', { className: 'dsh-llm-hub-routing__now' }, resolvedText())
 			const groupRows = groups.map((group, groupIndex) => {
 				const live = state.groups.find((item) => item.id === group.id)
+				// 始终折叠，展开才编辑（1.6.2）。原先是「当前组默认展开」，于是这页一进来
+				// 就是一屏逐条候选的表单 —— 而进来看的是「这几组各自会路由到哪」，
+				// 那是折叠行就能答完的问题。编辑是低频动作，折叠是默认态。
 				const isOpen = expanded === group.id
 				const candidates = group.candidates
 				return h('div', { key: group.id, className: `dsh-llm-hub-routing__group${activeGroup === group.id ? ' is-active' : ''}` },
 					h('div', { className: 'dsh-llm-hub-routing__group-top' },
 						// 顺序即优先级，所以序号 + 上下移都得露在折叠态 —— 折叠着也能改顺序。
 						h('div', { className: 'dsh-llm-hub-routing__group-order' },
-							h('button', {
-								type: 'button',
-								className: 'dsh-llm-hub-routing__group-toggle',
-								onClick: () => setExpanded(isOpen ? '' : group.id)
-							}, `${isOpen ? '▾' : '▸'} ${groupIndex + 1}`),
+							h('span', { className: 'dsh-llm-hub-routing__group-index' }, `${groupIndex + 1}`),
 							h('button', {
 								type: 'button',
 								className: 'dsh-llm-hub-routing__group-move',
@@ -2009,42 +2194,78 @@ window.__ModuleLoader__.load({
 								disabled: groupIndex === groups.length - 1,
 								onClick: () => moveGroup(groupIndex, 1)
 							}, '↓')),
-						h('input', {
-							className: 'dsh-llm-hub-routing__group-label',
-							value: group.label ?? '',
-							placeholder: t('routeGroupLabelPlaceholder'),
-							onChange: (event) => editGroup(group.id, (current) => ({ ...current, label: event.target.value }))
-						}),
-						// 折叠态给出「这一组会按什么顺序试」的摘要：主力 + 兜底条数。
-						// 之前顺序完全藏在折叠区里，用户看不到自己在排什么。
-						h('span', { className: 'dsh-llm-hub-routing__group-state' },
-							candidates.length === 0
-								? h('em', { className: 'dsh-llm-hub-routing__group-empty' }, t('routeNoCandidate'))
-								: [
-									h('b', { key: 'p' }, `${candidates[0].provider}/${candidates[0].model}`),
-									candidates.length > 1
-										? h('span', { key: 'n', className: 'dsh-llm-hub-routing__group-more' },
-											` + ${candidates.length - 1} ${t('routeFallbackCount')}`)
-										: null,
-									// 只在「实际会切到非主模型」时才提示 —— 跟主模型相同的箭头是纯冗余，
-									// 还会把摘要挤到省略号里。真正有信息量的只有「兜底被选上了」。
-									live?.wouldRoute && `${live.wouldRoute.provider}/${live.wouldRoute.model}` !== `${candidates[0].provider}/${candidates[0].model}`
-										? h('span', { key: 'w', className: 'dsh-llm-hub-routing__group-would' },
-											`→ ${live.wouldRoute.provider}/${live.wouldRoute.model}`)
-										: null,
-									live?.reason
-										? h('span', { key: 'r', className: 'dsh-llm-hub-routing__group-would' }, live.reason)
-										: null,
-								]),
+						// 组名折叠时是**纯文本**，展开才给输入框。折叠行还摆着一个输入框，
+						// 会让「这一行正在编辑」和「这一行只是显示」看起来一模一样 ——
+						// 而折叠行的职责恰恰是「看，不是改」。
+						isOpen
+							? h('input', {
+								className: 'dsh-llm-hub-routing__group-label',
+								value: group.label ?? '',
+								placeholder: t('routeGroupLabelPlaceholder'),
+								onChange: (event) => editGroup(group.id, (current) => ({ ...current, label: event.target.value }))
+							})
+							: h('span', { className: 'dsh-llm-hub-routing__group-name' }, group.label || group.id),
+						// 折叠态就三件事：会路由到哪 · 组里几个候选、几个可用 · 组名。
+						// 为什么是这三件：设置内容区只有 564px，组头扣掉序号/组名/两个按钮后，
+						// 摘要只剩 ~235px；而「将路由到 modelgo-gateway/claude-sonnet-5」按真实数据
+						// 就要 231px。再塞第四件（主力 provider/model）必然把最该被读到的那段
+						// 压成「将路由到 m…」（浏览器实测）。所以砍内容，不是调 CSS：
+						//   · 主力去掉 —— 它答「第一个是谁」，这行该答「实际走哪个」，展开态第一行就有；
+						//   · 「+N 条兜底」去掉 —— 旁边「4/5」已把总数和可用数都说了，是同义重复；
+						//   · 「将路由到」四字换成箭头 —— 省 48px，全称进 title 悬停可见。
+						!isOpen
+							? h('span', { className: 'dsh-llm-hub-routing__group-state' },
+								candidates.length === 0
+									? h('em', { className: 'dsh-llm-hub-routing__group-empty' }, t('routeNoCandidate'))
+									: [
+										live?.wouldRoute
+											? h('b', {
+												key: 'w',
+												className: 'dsh-llm-hub-routing__group-would',
+												title: `${t('routeChipWouldRoute')} ${live.wouldRoute.provider}/${live.wouldRoute.model}`
+											}, `\u2192 ${live.wouldRoute.provider}/${live.wouldRoute.model}`)
+											: h('em', {
+												key: 'w',
+												className: 'dsh-llm-hub-routing__group-would',
+												title: live?.reason ?? t('routeChipReasonNone')
+											}, live?.reason ?? t('routeChipReasonNone')),
+										// 「可用/总」比一个孤零零的绿点有信息：点只说「还行」，数字说清还剩几个能兜。
+										h('span', { key: 'c', className: 'dsh-llm-hub-routing__group-count' },
+											h('span', { className: `dsh-llm-hub-routing__dot dsh-llm-hub-routing__dot--${groupDotState(live)}` }),
+											`${availableOf(live)}/${live?.candidates?.length ?? candidates.length}`),
+									])
+							: null,
 						activeGroup === group.id
 							? h('span', { className: 'dsh-llm-hub-routing__role' }, t('routeActiveTag'))
 							: h('button', {
 								type: 'button',
 								className: 'dsh-llm-hub-foot__link',
 								onClick: () => markActive(group.id)
-							}, t('routeSetActive'))),
+							}, t('routeSetActive')),
+						// 「删除该组」原来孤零零挂在组底正中；挪到组头、只在展开编辑时出现，挨着「收起」。
+						isOpen
+							? h('button', {
+								type: 'button',
+								className: 'dsh-llm-hub-routing__op dsh-llm-hub-routing__op--danger dsh-llm-hub-routing__group-delete',
+								onClick: () => removeGroup(group.id)
+							}, t('routeDeleteGroup'))
+							: null,
+						// 原来开合藏在序号「▸ 1」上，看不出能点；现在是一个写明「编辑 / 收起」的按钮。
+						// 关起用 null 而不是 ''：空串只是「曾经用过的哨兵值」，读代码的人分不清它
+						// 跟「还没开合过」是不是一回事（1.6.2 之前确实当成两码事）。
+						h('button', {
+							type: 'button',
+							className: 'dsh-llm-hub-btn dsh-llm-hub-routing__group-toggle',
+							onClick: () => setExpanded(isOpen ? null : group.id)
+						}, isOpen ? `▾ ${t('routeCollapse')}` : `✎ ${t('routeEdit')}`)),
 					isOpen
 						? h('div', { className: 'dsh-llm-hub-routing__candidates' },
+							h('input', {
+								className: 'dsh-llm-hub-routing__note dsh-llm-hub-routing__note--group',
+								value: group.note ?? '',
+								placeholder: t('routeGroupNotePlaceholder'),
+								onChange: (event) => editGroup(group.id, (current) => ({ ...current, note: event.target.value }))
+							}),
 							...candidates.map((candidate, index) => {
 								const liveCandidate = live?.candidates?.find((item) => item.provider === candidate.provider && item.model === candidate.model)
 								const multimodal = isMultimodal(candidate.provider, candidate.model)
@@ -2052,28 +2273,67 @@ window.__ModuleLoader__.load({
 								const reasoningTip = reasoning === undefined
 									? undefined
 									: `${t('routeReasoningTip')}\n${reasoning.map((level) => `  · ${level.name} → ${level.id}`).join('\n')}`
-								return h('div', { key: `${candidate.provider}/${candidate.model}/${index}`, className: 'dsh-llm-hub-routing__row' },
-									h('span', { className: 'dsh-llm-hub-routing__role' }, index === 0 ? t('routePrimaryTag') : `${t('routeFallbackTag')}${index}`),
-									h('span', { className: 'dsh-llm-hub-routing__name' }, `${candidate.provider}/${candidate.model}`),
-									reasoning !== undefined
-										? h('span', {
-											key: 'reasoning',
-											className: 'dsh-llm-hub-routing__reasoning',
-											title: reasoningTip
-										}, `💭 ${t('routeReasoningShort')} ${reasoningShort(reasoning)}`)
-										: null,
-									multimodal === true
-										? h('span', {
-											key: 'multimodal',
-											className: 'dsh-llm-hub-routing__multimodal',
-											title: t('routeMultimodalTip')
-										}, '👁 ' + t('routeMultimodalShort'))
+								return h('div', { key: `${candidate.provider}/${candidate.model}/${index}`, className: `dsh-llm-hub-routing__row${index === 0 ? ' is-primary' : ''}` },
+									h('span', { className: `dsh-llm-hub-routing__role${index === 0 ? ' is-primary' : ''}` }, index === 0 ? t('routePrimaryTag') : `${t('routeFallbackTag')}${index}`),
+									// 原地改（1.7.0）：提供方 / 模型直接是下拉框，不用删了重加再连点 ↑。
+									// 目录里没有这家（没配置 / 目录没拉到）时退回纯文本，不让一行坏数据变成下拉框里的空值。
+									catalogEntryFor(candidate.provider) !== undefined
+										? h('span', { className: 'dsh-llm-hub-routing__pick' },
+											h('select', {
+												className: 'dsh-llm-hub-routing__select',
+												value: candidate.provider,
+												title: t('routeAddProvider'),
+												onChange: (event) => changeProvider(group.id, index, event.target.value)
+											}, ...catalog.map((entry) => h('option', { key: entry.id, value: entry.id }, `${entry.displayName ?? entry.id}`))),
+											h('select', {
+												className: 'dsh-llm-hub-routing__select',
+												value: candidate.model,
+												title: t('routeAddModel'),
+												onChange: (event) => updateCandidate(group.id, index, { model: event.target.value })
+											}, ...modelOptionsFor(candidate.provider, candidate.model).map((id) => h('option', { key: id, value: id }, id))))
+										: h('span', { className: 'dsh-llm-hub-routing__name' }, `${candidate.provider}/${candidate.model}`),
+									// 行排成固定两行网格（1.7.0）：第一行 角色 · 提供方 · 模型 · 能力/状态，
+									// 第二行 备注（占满） · 操作按钮（右对齐）。原来全部 flex-wrap，每行按内容长短
+									// 在不同位置折行，五行排不成列（浏览器实测截图）。
+									// 第二行：备注（撑满）· 能力/状态标签 · 操作按钮。标签原来在第一行最右，固定吃掉约 180px，
+									// 两个下拉被挤到截断「Antigravity 本地反…」「MiniMax-M3.1-Flash-Prev…」。
+									h('span', { className: 'dsh-llm-hub-routing__line2' },
+									h('input', {
+										className: 'dsh-llm-hub-routing__note',
+										value: candidate.note ?? '',
+										placeholder: t('routeNotePlaceholder'),
+										title: candidate.note ?? '',
+										onChange: (event) => updateCandidate(group.id, index, { note: event.target.value })
+									}),
+									h('span', { className: 'dsh-llm-hub-routing__meta' },
+										// 窄容器只放图标，文字进 title（1.7.0）：「思考 high/max / 图像 / 可用」三枚文字标签
+										// 吃掉约 176px，备注框被挤到只剩 150px、备注被截断（浏览器实测）。
+										reasoning !== undefined
+											? h('span', {
+												key: 'reasoning',
+												className: 'dsh-llm-hub-routing__reasoning',
+												title: `${t('routeReasoningShort')} ${reasoningShort(reasoning)}\n${reasoningTip}`
+											}, '💭')
+											: null,
+										multimodal === true
+											? h('span', {
+												key: 'multimodal',
+												className: 'dsh-llm-hub-routing__multimodal',
+												title: `${t('routeMultimodalShort')} · ${t('routeMultimodalTip')}`
+											}, '👁')
+											: null,
+										h('span', {
+											className: `dsh-llm-hub-routing__dot dsh-llm-hub-routing__dot--${liveCandidate?.state ?? 'unknown'}`,
+											title: liveCandidate?.state === 'available' ? '可用' : (liveCandidate?.state === 'unknown' ? '未探明' : '不可用')
+										})),
+									h('span', { className: 'dsh-llm-hub-routing__ops' },
+									index > 0
+										? h('button', { type: 'button', className: 'dsh-llm-hub-routing__op', onClick: () => makePrimary(group.id, index) }, t('routeMakePrimary'))
 										: null,
-									h('span', { className: stateChipClass(liveCandidate?.state) }, liveCandidate?.state === 'available' ? '可用' : (liveCandidate?.state === 'unknown' ? '未探明' : '不可用')),
-									h('button', { type: 'button', className: 'dsh-llm-hub-foot__link', title: t('routeUp'), onClick: () => moveCandidate(group.id, index, -1) }, '↑'),
-									h('button', { type: 'button', className: 'dsh-llm-hub-foot__link', title: t('routeDown'), onClick: () => moveCandidate(group.id, index, 1) }, '↓'),
-									h('button', { type: 'button', className: 'dsh-llm-hub-foot__link', title: t('routeRemove'), onClick: () => removeCandidate(group.id, index) }, '✕'))
-							}),
+									h('button', { type: 'button', className: 'dsh-llm-hub-routing__op', title: t('routeUp'), disabled: index === 0, onClick: () => moveCandidate(group.id, index, -1) }, '↑'),
+									h('button', { type: 'button', className: 'dsh-llm-hub-routing__op', title: t('routeDown'), disabled: index === candidates.length - 1, onClick: () => moveCandidate(group.id, index, 1) }, '↓'),
+									h('button', { type: 'button', className: 'dsh-llm-hub-routing__op dsh-llm-hub-routing__op--danger', title: t('routeRemove'), onClick: () => removeCandidate(group.id, index) }, '✕'))))
+								}),
 							h('div', { className: 'dsh-llm-hub-routing__add' },
 								h('span', null, t('routeAddProvider')),
 								catalog.length > 0
@@ -2123,26 +2383,31 @@ window.__ModuleLoader__.load({
 									className: 'dsh-llm-hub-btn',
 									onClick: () => addCandidate(group.id)
 								}, t('routeAdd'))),
-							catalog.length === 0 ? h('div', { className: 'dsh-llm-hub-routing__rule' }, t('routeNoCatalog')) : null,
-							h('button', {
-								type: 'button',
-								className: 'dsh-llm-hub-foot__link',
-								onClick: () => removeGroup(group.id)
-							}, t('routeDeleteGroup')))
+							catalog.length === 0 ? h('div', { className: 'dsh-llm-hub-routing__rule' }, t('routeNoCatalog')) : null)
 						: null)
 			})
+			// 空闲态不再写死「已保存」—— 那三个字跟「刚刚存成功」长得一模一样，
+			// 读起来像一条一直挂着的成功提示，而它其实什么都没说。空闲时干脆不占位，
+			// 真存过 / 存到一半 / 存失败才给反馈。
+			const noticing = notice === 'fail' || notice === 'saving' || notice === 'saved'
 			const footer = h('div', { className: 'dsh-llm-hub-routing__actions' },
 				h('button', { type: 'button', className: 'dsh-llm-hub-btn', onClick: addGroup }, t('routeNewGroup')),
-				h('button', {
-					type: 'button',
-					className: 'dsh-llm-hub-btn',
-					disabled: busy || !isDirty,
-					onClick: save
-				}, isDirty ? t('routeSave') : t('routeSaved')),
-				notice === 'fail' ? h('span', { className: 'dsh-llm-hub-routing__reason' }, t('routeSaveFailed')) : null,
+				// 注意这里不能写成 h(cond ? <span/> : null) —— 多包的那层 h 没有 tag，
+				// flatten 不递归进去，状态文案在测试里就永远取不到（真实浏览器里没事，
+				// 因为 DOM 照样渲染 —— 正是「测试挂了但界面看着正常」的那类坑）。
+				noticing || busy || isDirty
+					? h('span', { className: `dsh-llm-hub-routing__status${notice === 'fail' ? ' is-fail' : ''}` },
+						notice === 'fail' ? t('routeSaveFailed')
+							: (busy || notice === 'saving' || isDirty) ? t('routeSaving')
+								: t('routeAutoSaved'))
+					: null,
+				notice === 'fail'
+					? h('button', { type: 'button', className: 'dsh-llm-hub-btn', disabled: busy, onClick: () => { setNotice(null); save() } }, t('routeRetry'))
+					: null,
 				h('span', { className: 'dsh-llm-hub-routing__hint' }, t('routeEditHint')))
-			return h('div', { className: 'dsh-llm-hub-routing' },
+			return h('div', { className: 'dsh-llm-hub-routing dsh-llm-hub-routing-page' },
 				header,
+				pageDesc,
 				rule,
 				noticeLine,
 				nowLine,
@@ -2150,6 +2415,14 @@ window.__ModuleLoader__.load({
 				footer)
 		}
 
+		/**
+		 * 「路由」设置页：页头（标题 + 一句怎么用）+ 路由编辑器。
+		 * 直接调用 RoutingCard(props) 而不是 h(RoutingCard)：少一层组件，hooks 顺序不变。
+		 */
+		function RoutingSection(props) {
+			return RoutingCard(props)
+		}
+
 		/**
 		 * 格式化 token 数字 —— 大数带千分位，>9999 折成 1.2万。
 		 * @param value - token 数。
@@ -2639,13 +2912,17 @@ window.__ModuleLoader__.load({
 				locale: NS,
 				inject: () => ({ t, availability })
 			}, HealthCard))
-			ctx.slots.inject('settings.models.footer', () => ctx.slots.register({
-				name: 'settings.models.footer',
+			// 路由配置是独立的一页（1.7.0）：原来挂在「模型」页脚第 75 位，要往下翻好几屏才找得到，
+			// 用户的原话是「我自己怎么选主力、在哪里改」。settings.section 的 order：
+			// 通用 0 / 模型 10 / 插件 15 —— 取 12，正好排在「模型」下面。
+			ctx.slots.inject('settings.section', () => ctx.slots.register({
+				name: 'settings.section',
 				id: 'dsh-llm-hub-routing',
-				order: 75,
+				order: 12,
+				label: () => t('routingNav'),
 				locale: NS,
 				inject: () => ({ t })
-			}, RoutingCard))
+			}, RoutingSection))
 			ctx.slots.inject('settings.models.footer', () => ctx.slots.register({
 				name: 'settings.models.footer',
 				id: 'dsh-llm-hub-usage',

package/lib/index.js

@@ -33,12 +33,14 @@
 /** 官方直连适配器拥有的 settings 命名空间。 */
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
+import z from '@deepseek-ai/schemastery'
 import { applyHarness, harnessReport } from './harness.js'
 import { detectBillingMode, sortProviders } from './sorter.js'
 import { AvailabilityStore, isDropDeadHidden, classifyFailure } from './availability-store.js'
 
 export { detectBillingMode, sortProviders } from './sorter.js'
 export { AvailabilityStore, isDropDeadHidden, classifyFailure } from './availability-store.js'
+export { Config }
 
 /**
  * 用量统计 domain 的 spec。
@@ -291,6 +293,35 @@ export function parseRouteEntryPure(entry) {
  * @param {object|undefined|null} routing - settings.routing 段。
  * @returns {{ groups: Array, mode: 'manual'|'smart', activeGroup: string }}
  */
+/**
+ * 备注清洗：只收字符串，去首尾空白，空串视为没有，最长 120 字。
+ * @param {unknown} value - 原始备注。
+ * @returns {string | null}
+ */
+export function cleanRouteNote(value) {
+	if (typeof value !== 'string') return null
+	const note = value.trim().slice(0, 120)
+	return note === '' ? null : note
+}
+
+/**
+ * 候选备注表：只保留键是合法 `provider/model`、且确实在本组候选里的条目 ——
+ * 删掉候选时它的备注一并消失，不在 settings 里留孤儿。
+ * @param {unknown} raw - settings 里的 notes 字典。
+ * @param {Array<{provider: string, model: string}>} entries - 本组全部候选。
+ * @returns {Record<string, string> | null}
+ */
+function cleanRouteNotes(raw, entries) {
+	if (raw === null || typeof raw !== 'object') return null
+	const keys = new Set(entries.map((entry) => `${entry.provider}/${entry.model}`))
+	const out = {}
+	for (const [key, value] of Object.entries(raw)) {
+		const note = cleanRouteNote(value)
+		if (note !== null && keys.has(key)) out[key] = note
+	}
+	return Object.keys(out).length > 0 ? out : null
+}
+
 export function parseRoutingGroups(routing) {
 	const r = routing !== null && typeof routing === 'object' ? routing : {}
 	const mode = r.mode === 'smart' ? 'smart' : 'manual'
@@ -306,11 +337,15 @@ export function parseRoutingGroups(routing) {
 			.filter((entry) => entry !== undefined)
 		if (primary === null && fallbacks.length === 0) continue
 		seen.add(id)
+		const note = cleanRouteNote(raw.note)
+		const notes = cleanRouteNotes(raw.notes, [...(primary !== null ? [primary] : []), ...fallbacks])
 		groups.push({
 			id,
 			label: typeof raw.label === 'string' && raw.label.trim() !== '' ? raw.label.trim() : null,
 			primary,
-			fallbacks
+			fallbacks,
+			...(note !== null ? { note } : {}),
+			...(notes !== null ? { notes } : {})
 		})
 	}
 	if (groups.length === 0) {
@@ -422,11 +457,22 @@ export function normalizeRoutingGroupsInput(raw) {
 		}
 		if (primary === null && fallbacks.length === 0) { dropped.push(`组 ${id} 没有任何合法候选`); continue }
 		seen.add(id)
+		// 候选备注两种来源：编辑器形态里每个候选对象自带 note；落盘形态是组上的 notes 字典。
+		const noteSource = { ...(item.notes !== null && typeof item.notes === 'object' ? item.notes : {}) }
+		for (const candidate of ordered ?? []) {
+			const entry = asEntry(candidate)
+			const note = candidate !== null && typeof candidate === 'object' ? cleanRouteNote(candidate.note) : null
+			if (entry !== undefined && note !== null) noteSource[`${entry.provider}/${entry.model}`] = note
+		}
+		const note = cleanRouteNote(item.note)
+		const notes = cleanRouteNotes(noteSource, [...(primary !== null ? [primary] : []), ...fallbacks])
 		groups.push({
 			id,
 			label: typeof item.label === 'string' && item.label.trim() !== '' ? item.label.trim().slice(0, 32) : null,
 			primary,
-			fallbacks
+			fallbacks,
+			...(note !== null ? { note } : {}),
+			...(notes !== null ? { notes } : {})
 		})
 	}
 	return { groups, dropped }
@@ -613,64 +659,70 @@ export const name = 'dsh-llm-hub'
  * 用量统计走的是**局部注入**：`storageDomain` 缺席时不报错，本插件其余功能照常工作
  * —— 没有 storageDomain 也能用余额/可用性/harness，只是没法跨会话记 token 用量。
  */
+/**
+ * 本插件的配置形态（DSH 0.1.7 的 settings 契约）。
+ *
+ * 0.1.7 起配置不再运行时 `settings.register()` 注册，而是由 Loader 按**条目 id**
+ * 从 profile 的 `cordis.patch.yml` 读取；插件导出这个 `Config`，`apply(ctx, config)`
+ * 收下 `config`，页面的表单与 `settings.update(ns, patch)` 也都按它生成。
+ * 字段与 1.5.0 起的段结构一一对应，所以老 settings.yaml 里的段能原样迁进 patch。
+ *
+ * note / notes：页面上写的备注。YAML 注释在页面保存时会被整段替换冲掉，
+ * 所以说明要落成字段才留得住。notes 以 'provider/model' 为键。
+ */
+const groupItem = z.object({
+	id: z.string().required(),
+	label: z.string(),
+	note: z.string(),
+	primary: z.string(),
+	fallbacks: z.array(z.string()),
+	notes: z.dict(z.string())
+})
+// ⚠️ 三个字段都必须 .volatile()：0.1.7 的 settings.update() 拒绝「没有 volatile
+// 字段的条目」（原话：Plugin entry "dsh-llm-hub" has no volatile fields）。
+// volatile 的语义正是本插件要的行为 —— 配置改动只换值、不重跑 apply：路由组、预警
+// 阈值、别名全是**每次请求惰性重读**的（见 hubSectionOf 的注释），让切一次路由就去
+// 重新 apply 整个插件是白付代价。官方 dsh-llm-pi-ai 的 providers 段同样标了 volatile。
+const Config = z.object({
+	routing: z.object({
+		mode: z.union(['manual', 'smart']).default('manual'),
+		activeGroup: z.string().default(''),
+		groups: z.array(groupItem).default([])
+	}).default({}).volatile(),
+	warning: z.object({ cashCNY: z.number().default(10), planPercent: z.number().default(10) }).default({}).volatile(),
+	aliases: z.dict(z.string()).default({}).volatile()
+})
+
 export const inject = ['llm', 'webServer']
 
 /**
  * 注册模型发现与余额路由。
  * @param ctx - 插件上下文。
  */
-export function apply(ctx) {
+export function apply(ctx, config) {
 
 	// ── 插件自有 settings 命名空间（dsh-llm-hub）────────────────────────────
 	//
-	// 1.5.0 起：routing / warning / aliases 的真源从 `llm-deepseek` 段迁到独立
-	// 的 `dsh-llm-hub` 段 —— README 文档里写的顶层 `dsh-llm-hub:` 键此前**从未
-	// 被读到过**（没注册过命名空间，settings.get 会抛），这是 1.1.0 起的历史
-	// 缺陷，这里一起修掉。
-	//
-	// schema 尽量懒加载 `@deepseek-ai/schemastery`；失败时退回 `Object` 构造器
-	// （schemastery 接受原生构造器作为 schema）。注册失败不 fatal：配置读取退
-	// 回 legacy 路径，智能路由降级为「只建议」。
-	let hubRegistered = false
-	ctx.inject(['settings'], (settingsCtx) => {
-		void (async () => {
-			let schema
-			try {
-				const mod = await import('@deepseek-ai/schemastery')
-				const z = (mod && typeof mod === 'object' ? mod.default ?? mod : mod)
-				const groupItem = z.object({ id: z.string().required(), label: z.string(), primary: z.string(), fallbacks: z.array(z.string()) })
-				schema = z.object({
-					routing: z.object({
-						mode: z.union(['manual', 'smart']).default('manual'),
-						activeGroup: z.string().default(''),
-						groups: z.array(groupItem).default([])
-					}).default({}),
-					warning: z.object({ cashCNY: z.number().default(10), planPercent: z.number().default(10) }).default({}),
-					aliases: z.dict(z.string()).default({})
-				})
-			} catch {
-				// 零依赖环境：schemastery 没解析到 —— 用原生构造器兜底。
-				schema = Object
-			}
-			try {
-				settingsCtx.settings.register(HUB_NS, schema)
-				hubRegistered = true
-			} catch (error) {
-				ctx.logger.warn(`dsh-llm-hub: settings ns "dsh-llm-hub" register failed: ${error?.message ?? error}`)
-			}
-		})()
-	})
+	// DSH 0.1.7 把 settings 架构整个换了：`settings.register(ns, schema)` 与
+	// `settings.get(ns)` 双双消失，配置改由 Loader 按**条目 id**从 profile 的
+	// cordis.patch.yml 读，插件自己导出 `Config`，再由 `apply(ctx, config)` 收下。
+	// 老写法在 0.1.7 上是 `TypeError: settings.register is not a function`，
+	// 被下面那个 catch 吞掉 → hubRegistered 恒 false → 整个 dsh-llm-hub 段读写
+	// 全死。对外表现是「路由组凭空消失」：数据好好躺在 patch 里，只是没人读。
 
 	/**
 	 * 读 `dsh-llm-hub` 设置段（1.5.0 起的真源）。
 	 * @returns 已解析设置段；未注册 / 未配置时为 `undefined`。
 	 */
 	const hubSectionOf = () => {
-		const settings = ctx.get('settings')
-		if (settings === undefined) return undefined
+		// 0.1.7：配置由 `apply(ctx, config)` 注入，惰性 .get() 每次拿当前修订。
+		// 不再走 settings.get(HUB_NS) —— 那个方法在 0.1.7 已被移除。
+		if (config === undefined || config === null) return undefined
 		try {
-			const value = settings.get(HUB_NS)
-			return value !== null && typeof value === 'object' ? value : undefined
+			const routing = config.routing?.get?.()
+			const warning = config.warning?.get?.()
+			const aliases = config.aliases?.get?.()
+			return { routing, warning, aliases }
 		} catch {
 			return undefined
 		}
@@ -683,13 +735,31 @@ export function apply(ctx) {
 	 * @returns 已解析的设置段；不可用时为 `undefined`。
 	 */
 	const sectionOf = () => {
+		// 0.1.7：读**别的插件**的配置不再有 settings.get(ns)。改走
+		// settings.describe() —— 它返回所有条目的 ns + 实时 value。
 		const settings = ctx.get('settings')
 		if (settings === undefined) return undefined
 		try {
-			const value = settings.get(NS)
+			const row = settings.describe().find((item) => item.ns === NS)
+			const value = row?.value
+			return value !== null && typeof value === 'object' ? value : undefined
+		} catch {
+			return undefined
+		}
+	}
+
+	/**
+	 * 读任意命名空间（跨插件）在 0.1.7 的唯一途径。
+	 * @param {string} ns - profile 条目 id。
+	 * @returns {object | undefined} 该条目的实时配置值。
+	 */
+	const sectionOfNs = (ns) => {
+		const settings = ctx.get('settings')
+		if (settings === undefined) return undefined
+		try {
+			const value = settings.describe().find((item) => item.ns === ns)?.value
 			return value !== null && typeof value === 'object' ? value : undefined
 		} catch {
-			// 命名空间尚未注册时会抛 —— 那是正常启动竞态，不是失败。
 			return undefined
 		}
 	}
@@ -1079,7 +1149,7 @@ export function apply(ctx) {
 		const settings = ctx.get('settings')
 		if (settings === undefined) return []
 		try {
-			const section = settings.get(PIAI_NS)
+			const section = sectionOfNs(PIAI_NS)
 			const providers = section !== null && typeof section === 'object' ? section.providers : undefined
 			if (providers === null || typeof providers !== 'object') return []
 			return Object.entries(providers).filter(([, profile]) => profile !== null && typeof profile === 'object')
@@ -1099,7 +1169,7 @@ export function apply(ctx) {
 		const settings = ctx.get('settings')
 		if (settings === undefined) return undefined
 		try {
-			const section = settings.get(PIAI_NS)
+			const section = sectionOfNs(PIAI_NS)
 			const providers = section !== null && typeof section === 'object' ? section.providers : undefined
 			const profile = providers !== null && typeof providers === 'object' ? providers[provider] : undefined
 			return profile !== null && typeof profile === 'object' ? profile : undefined
@@ -1294,7 +1364,12 @@ export function apply(ctx) {
 			auth: 'raw',
 			shape: (body) => {
 				if (body?.success === false || (typeof body?.code === 'number' && body.code !== 200)) {
-					return { unavailable: label(body?.msg) ?? 'quota unavailable' }
+					// 服务端用一份完整的 JSON 明确回答「你这个号没有套餐」
+					// （2026-09-29 实测：`当前用户不存在coding plan`）。
+					// 这跟 `fail()` 那几条「连不上 / 看不懂 / 没这个接口」不是一回事：
+					// 前者是确知不可用，值得判死并隐藏；后者是拿不准，必须 fail-open 保留。
+					// 不标 definitive 的话，欠费会永远停在「显示着但一用就报错」。
+					return { unavailable: label(body?.msg) ?? 'quota unavailable', definitive: true }
 				}
 				const limits = Array.isArray(body?.data?.limits) ? body.data.limits : []
 				const items = []
@@ -1361,6 +1436,13 @@ export function apply(ctx) {
 		return undefined
 	}
 
+	/**
+	 * provider -> 最近一次余额信封。排序要用它判计费模式，而排序是同步的
+	 * （`llm.listProviders` 不能 await），所以只能读探测顺手存下来的快照。
+	 * @type {Map<string, object>}
+	 */
+	const balanceSnapshot = new Map()
+
 	/**
 	 * 查询某 provider 的余额/配额。统一信封：`{ ok, kind, available, items?, reason? }`；
 	 * 匹配不到适配器给 `{ ok, supported:false }`，无 key / 上游失败都折叠成 `available:false`
@@ -1419,9 +1501,12 @@ export function apply(ctx) {
 		}
 		const shaped = adapter.shape(body)
 		if (shaped.unavailable !== undefined) {
-			return { ok: true, provider, kind: adapter.kind, available: false, reason: shaped.unavailable }
+			// definitive 只在「上游结构化回答了不可用」时为真；网络/解析失败走 fail()，没有这个字段。
+			return { ok: true, provider, kind: adapter.kind, available: false, reason: shaped.unavailable, definitive: shaped.definitive === true }
 		}
-		return { ok: true, provider, kind: adapter.kind, adapter: adapterName, meaning: adapter.meaning, level: shaped.level, items: shaped.items ?? [] }
+		const envelope = { ok: true, provider, kind: adapter.kind, adapter: adapterName, meaning: adapter.meaning, level: shaped.level, items: shaped.items ?? [] }
+		balanceSnapshot.set(provider, envelope)
+		return envelope
 	}
 
 	/**
@@ -1665,9 +1750,18 @@ export function apply(ctx) {
 			return undefined
 		}
 		if (envelope === null || typeof envelope !== 'object' || envelope.ok !== true || envelope.supported === false) return undefined
-		// available=false 只表示「这次余额查询没成功」；原因千差万别（没 key、查不通、
-		// 没有套餐），除开 key 缺失（已由凭据那步覆盖）都不构成隐藏理由。
-		if (envelope.available === false) return undefined
+		// available=false 有两种，混在一起处理会让欠费永远漏网：
+		//   · definitive —— 上游用完整 JSON 确知「这个号没有套餐」，判死并隐藏；
+		//   · 其余（没 key / 连不上 / 看不懂 / 没这个接口）—— 只是这次没查成，
+		//     按 fail-open 保留，否则一次网络抖动就把能用的模型藏了。
+		// 2026-09-29 实测智谱 coding 端点就栽在这：余额接口白纸黑字回了
+		// 「当前用户不存在coding plan」，却因为和「查不通」共用 available=false 而被放过。
+		if (envelope.available === false) {
+			if (envelope.definitive === true) {
+				return { state: 'unavailable', code: 'ACCOUNT_UNAVAILABLE', source: 'balance', reason: label(envelope.reason) ?? '账户没有可用套餐' }
+			}
+			return undefined
+		}
 		const items = Array.isArray(envelope.items) ? envelope.items : []
 		if (envelope.kind === 'cash') {
 			const amount = items[0]?.amount
@@ -1993,7 +2087,13 @@ export function apply(ctx) {
 			if (profile?.billingMode === 'usage' || profile?.billingMode === 'subscription') {
 				return profile.billingMode
 			}
-			return detectBillingMode(profile || { provider: cleanId })
+			// ⚠️ balance 必须传：少了它，`detectBillingMode` 里认 `kind: 'plan' | 'quota'`、
+			// `resetsAt`、`weeklyPercent` 的那几条分支全是死代码，最后一律落到兜底的
+			// `return 'usage'`。2026-09-29 实测：MiniMax 余额信封明明是
+			// `{kind:'plan', items:[{resetsAt:'15:00', weeklyPercent:97}]}`，下拉里却被当成
+			// 按量付费排在套餐后面 —— 配置卡片显示对了（client 传了 balance），
+			// 下拉排序却是错的（host 没传），两边对不上就是这个漏传造成的。
+			return detectBillingMode(profile || { provider: cleanId }, profile, balanceSnapshot.get(cleanId) ?? balanceSnapshot.get(id))
 		}
 
 		const filtered = function (...args) {
@@ -2128,10 +2228,10 @@ export function apply(ctx) {
 				// modelgo 这种 pi-ai 风格 provider 在 'llm-pi-ai' namespace 下；
 				// dsh-llm-hub 自己的 NS 是 'llm-deepseek'，但写回属于跨 namespace 兜底：
 				// plugin 不是 pi-ai 的 owner，只是借用 settings 服务给 pi-ai 段补一份目录。
-				const source = settingsCtx.settings.get(PIAI_NS)
+				const source = sectionOfNs(PIAI_NS)
 				const updates = await populateEmptyProviderModels(source)
 				if (Object.keys(updates).length === 0) return
-				const current = settingsCtx.settings.get(PIAI_NS)
+				const current = sectionOfNs(PIAI_NS)
 				for (const provider of Object.keys(updates)) {
 					const live = current?.providers?.[provider]
 					if (Array.isArray(live?.models) && live.models.length > 0) {
@@ -2707,9 +2807,11 @@ export function apply(ctx) {
 			return {
 				id: group.id,
 				label: group.label,
+				note: group.note ?? null,
 				candidates: candidates.map((candidate) => ({
 					provider: candidate.provider,
 					model: candidate.model,
+					note: group.notes?.[`${candidate.provider}/${candidate.model}`] ?? null,
 					state: stateFor(candidate.provider, candidate.model)
 				})),
 				wouldRoute: winner.to,
@@ -2734,7 +2836,7 @@ export function apply(ctx) {
 	/** 读 settings 的 routing 段并按需覆写 mode / activeGroup，持久化。 */
 	const applyRoutingSelect = async (patch) => {
 		const settings = ctx.get('settings')
-		if (settings === undefined || hubRegistered !== true) {
+		if (settings === undefined) {
 			return { ok: false, error: 'settings 命名空间 dsh-llm-hub 尚未就绪 —— 稍后重试' }
 		}
 		const current = routingObjOf()
@@ -2852,7 +2954,7 @@ export function apply(ctx) {
 	/** 写回整份路由组（设置页编辑器保存路径），并返回最新状态。 */
 	const applyRoutingConfig = async (payload) => {
 		const settings = ctx.get('settings')
-		if (settings === undefined || hubRegistered !== true) {
+		if (settings === undefined) {
 			return { ok: false, error: 'settings 命名空间 dsh-llm-hub 尚未就绪 —— 稍后重试' }
 		}
 		const normalized = normalizeRoutingGroupsInput(payload?.groups)
@@ -2877,8 +2979,10 @@ export function apply(ctx) {
 					groups: normalized.groups.map((group) => ({
 						id: group.id,
 						...(group.label !== null ? { label: group.label } : {}),
+						...(group.note ? { note: group.note } : {}),
 						...(group.primary !== null ? { primary: `${group.primary.provider}/${group.primary.model}` } : {}),
-						fallbacks: group.fallbacks.map((entry) => `${entry.provider}/${entry.model}`)
+						fallbacks: group.fallbacks.map((entry) => `${entry.provider}/${entry.model}`),
+						...(group.notes ? { notes: group.notes } : {})
 					}))
 				}
 			})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plugins/dsh-llm-hub",
-  "version": "1.6.1",
+  "version": "1.8.0",
   "description": "DSH 模型管理层：网关可达性探测、模型目录拉取、DeepSeek + MiniMax/智谱/Moonshot/StepFun 余额与配额、本月用量统计、余额预警、Provider 健康看板，再把本机装好的 codex / claude / agy 注册成子代理（装了才出现）。零运行时依赖，不改动 DSH 安装。",
   "type": "module",
   "main": "lib/index.js",
@@ -79,5 +79,8 @@
     "lib",
     "scripts",
     "types"
-  ]
+  ],
+  "devDependencies": {
+    "@deepseek-ai/schemastery": "3.18.4"
+  }
 }

package/scripts/prepublish-gate.mjs

@@ -85,8 +85,17 @@ const walkStrings = (v) => {
 for (const field of ['main', 'types', 'module', 'bin', 'exports']) walkStrings(pkg[field])
 if (pkg.dsh && typeof pkg.dsh === 'object') walkStrings(pkg.dsh.bundle)
 
+// exports 允许「子路径模式」：`"./styles/*": "./styles/*"`。
+// 这是 npm 官方推荐的整目录可 import 写法，不是错字 —— 2026-09-22 的 retro 记过：
+// 白名单式把每个子路径列一遍，漏一个下游构建就直接 `Missing "./styles/x.css"` 失败。
+// 所以带 * 的条目必须按 glob 去匹配 tarball，而不是要求存在一个名叫 `styles/*` 的文件。
+// 但「模式一个文件都匹配不到」仍要拦 —— 那说明目录被删了或没进 files[]，模式是死的。
+const entryGlobRe = (g) => new RegExp(
+  '^' + g.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$'
+)
 for (const p of entryPaths) {
-  if (!inPack(p)) {
+  const ok = /[*?]/.test(p) ? packFiles.some(f => entryGlobRe(p).test(f)) : inPack(p)
+  if (!ok) {
     errors.push(`package.json 的入口字段引用了 '${p}'，但 tarball 里没有\n  → 装包的人会在 require/import 时直接失败`)
   }
 }