@dsh-plugins/dsh-llm-hub 1.5.5 → 1.6.0

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 本项目遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## [1.6.0] - 2026-09-28
+
+### ✨ 智能路由：组可排序 + 折叠摘要
+
+- 路由组（公司 / 个人 …）新增 ↑↓ 上下移。组的先后决定智能路由先用哪个池子，此前只能手改 `settings.yaml`
+- 折叠态直接显示「主力模型 + N 条兜底」，不用展开也知道这一组会按什么顺序试；空组显示「还没加候选」
+- 序号与上下移按钮在折叠态也可用；首组 ↑ / 末组 ↓ 自动禁用
+
+## [1.5.6] - 2026-09-27
+
+### 📛 包装升级：首屏补齐居中标题 + 接入 README 门禁
+
+- 新增 `<h1 align="center">` 居中标题与双语 slogan
+- 8 个徽章从 `flat-square` 换成 `for-the-badge`
+- 新增 `scripts/readme-gate.mjs`，挂在 `prepublishOnly` 上
+  - 真源：`cs rule open_source_project_baseline`（README 首屏金字塔）
+  - 4 条契约：居中品牌 / `for-the-badge` 徽章 / 前 80 行有 Why This 对比表 / 有 `README.en.md`
+  - 逃生舱：`README_GATE=off`（仅限明确不需要包装的内部包）
+
+### 🛣️ 智能路由：`routableStateFor` 把"探测表里没记录"细分成 unknown / unavailable
+
+之前一刀切返回 `unavailable`，导致**冷启动 / 用户刚加 provider / 探针刚清空**时被路由跳过，
+即便 settings 里有配、key 也填了，照样不让 smart 接管。典型踩坑：zai-coding-cn 这类
+无 baseURL 的 provider，第一次请求时被 `routableStateFor` 当 unavailable 跳过去。
+
+新语义（`lib/index.js:2554-2580`）：
+
+- 探测表里有 verdict → 用 verdict.state（available / unknown / unavailable）
+- 探测表里没有 + settings 里**有**配 → `unknown`（routable，请求撞真上游，撞完探针补 verdict）
+- 探测表里没有 + settings 里**没**配 → `unavailable`（真不认识，撞 NO_ADAPTER，fail-open）
+
+测试新增 1 条（`pickSmartRoute：未探测（unknown）且候选里 → 仍接管`），全 132 项过。
+
+### 🛣️ 智能路由：`routableStateFor` 把"探测表里没记录"细分成 unknown / unavailable
+
+之前一刀切返回 `unavailable`，导致**冷启动 / 用户刚加 provider / 探针刚清空**时被路由跳过，
+即便 settings 里有配、key 也填了，照样不让 smart 接管。典型踩坑：zai-coding-cn 这类
+无 baseURL 的 provider，第一次请求时被 `routableStateFor` 当 unavailable 跳过去。
+
+新语义（`lib/index.js:2554-2580`）：
+
+- 探测表里有 verdict → 用 verdict.state（available / unknown / unavailable）
+- 探测表里没有 + settings 里**有**配 → `unknown`（routable，请求撞真上游，撞完探针补 verdict）
+- 探测表里没有 + settings 里**没**配 → `unavailable`（真不认识，撞 NO_ADAPTER，fail-open）
+
+测试新增 1 条（`pickSmartRoute：未探测（unknown）且候选里 → 仍接管`），全 132 项过。
+
 ## [1.5.5] - 2026-09-27
 
 ### 🪧 路由卡：每条候选的能力 chip（思考 + 多模态）

package/README.en.md

@@ -27,11 +27,13 @@ On DSH's Models page, the official adapters leave half the job undone. This plug
 
 ## Install
 
+> Only Node.js is required — **no global dsh install**; upstream's official entry is `npx @deepseek-ai/dsh`. If dsh is installed globally, use `dsh` instead.
+
 ```sh
-dsh plugin --profile web add @dsh-plugins/dsh-llm-hub
+npx @deepseek-ai/dsh plugin --profile web add @dsh-plugins/dsh-llm-hub
 ```
 
-Add `@dsh-plugins/dsh-llm-hub` to `dsh.profile.bundles` in `~/.dsh/profiles/web/package.json`, then run `~/.dsh/restart.sh`.
+Add `@dsh-plugins/dsh-llm-hub` to `dsh.profile.bundles` in `~/.dsh/profiles/web/package.json`, then restart DSH (stop it and rerun `npx @deepseek-ai/dsh web`).
 Open **Settings → Models** — a new row appears under the provider cards.
 
 <sub>A boot-graph change requires a restart; hot reload won't pick it up. `cordis.patch.yml` is inserted automatically by the bundle mechanism.</sub>

package/README.md

@@ -2,18 +2,25 @@
   <img src="https://img.webkubor.online/oss/dsh-llm-hub/banner.png" alt="dsh-llm-hub" width="100%" />
 </p>
 
+
+<h1 align="center">🔌 dsh-llm-hub</h1>
+
+<p align="center">
+  <strong>给 DSH 模型页补上官方适配器缺的那半。</strong><br/>
+  <sub>Gateway health, model catalog, balance — the half the built-in adapter leaves out.</sub>
+</p>
 <p align="center">
-  <a href="https://www.npmjs.com/package/@dsh-plugins/dsh-llm-hub"><img src="https://img.shields.io/npm/v/%40dsh-plugins%2Fdsh-llm-hub?style=flat-square&color=4C7EF3&logo=npm&label=npm" alt="npm" /></a>
-  <a href="https://www.npmjs.com/package/@dsh-plugins/dsh-llm-hub"><img src="https://img.shields.io/npm/dm/%40dsh-plugins%2Fdsh-llm-hub?style=flat-square&color=6d7f9c&label=downloads" alt="downloads" /></a>
-  <img src="https://img.shields.io/badge/DSH-%E2%89%A50.1.1--rc.2-4d6bfe?style=flat-square" alt="DSH" />
-  <img src="https://img.shields.io/badge/runtime_deps-0-5A9E6F?style=flat-square" alt="zero deps" />
-  <img src="https://img.shields.io/badge/license-MIT-777?style=flat-square" alt="MIT" />
+  <a href="https://www.npmjs.com/package/@dsh-plugins/dsh-llm-hub"><img src="https://img.shields.io/npm/v/%40dsh-plugins%2Fdsh-llm-hub?style=for-the-badge&color=4C7EF3&logo=npm&label=npm" alt="npm" /></a>
+  <a href="https://www.npmjs.com/package/@dsh-plugins/dsh-llm-hub"><img src="https://img.shields.io/npm/dm/%40dsh-plugins%2Fdsh-llm-hub?style=for-the-badge&color=6d7f9c&label=downloads" alt="downloads" /></a>
+  <img src="https://img.shields.io/badge/DSH-%E2%89%A50.1.1--rc.2-4d6bfe?style=for-the-badge" alt="DSH" />
+  <img src="https://img.shields.io/badge/runtime_deps-0-5A9E6F?style=for-the-badge" alt="zero deps" />
+  <img src="https://img.shields.io/badge/license-MIT-777?style=for-the-badge" alt="MIT" />
 </p>
 
 <p align="center">
-  <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DeepSeek_Harness-Plugin-4d6bfe?style=flat-square" alt="DSH Plugin" /></a>
-  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/topic-dsh--plugin-4d6bfe?style=flat-square" alt="dsh-plugin" /></a>
-  <a href="https://github.com/topics/llm-gateway"><img src="https://img.shields.io/badge/topic-llm--gateway-4C7EF3?style=flat-square" alt="llm-gateway" /></a>
+  <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DeepSeek_Harness-Plugin-4d6bfe?style=for-the-badge" alt="DSH Plugin" /></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/topic-dsh--plugin-4d6bfe?style=for-the-badge" alt="dsh-plugin" /></a>
+  <a href="https://github.com/topics/llm-gateway"><img src="https://img.shields.io/badge/topic-llm--gateway-4C7EF3?style=for-the-badge" alt="llm-gateway" /></a>
   &nbsp;·&nbsp; <a href="README.en.md">English</a> · <a href="CHANGELOG.md">更新日志</a>
 </p>
 
@@ -38,12 +45,14 @@ DSH 的模型页上，官方适配器有一半事情没做。这个插件把它
 
 ## 装
 
+> 前提：装好 Node.js 即可，**无需全局安装 dsh** —— 官方入口就是 `npx @deepseek-ai/dsh`。已全局安装的可把它换成 `dsh`。
+
 ```sh
-dsh plugin --profile web add @dsh-plugins/dsh-llm-hub
+npx @deepseek-ai/dsh plugin --profile web add @dsh-plugins/dsh-llm-hub
 ```
 
 再把 `@dsh-plugins/dsh-llm-hub` 加进 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles` 数组，
-然后 `~/.dsh/restart.sh`。打开**设置 → 模型**，provider 卡片下方会多出一行。
+然后重启 DSH（结束当前进程后重新运行 `npx @deepseek-ai/dsh web`）。打开**设置 → 模型**，provider 卡片下方会多出一行。
 
 <sub>boot graph 变了必须重启，热载不生效；`cordis.patch.yml` 由 bundle 机制自动 insert。</sub>
 
@@ -75,7 +84,7 @@ dsh plugin --profile web add @dsh-plugins/dsh-llm-hub
 升级：
 
 ```sh
-dsh plugin --profile web update @dsh-plugins/dsh-llm-hub@^1.5.1
+npx @deepseek-ai/dsh plugin --profile web update @dsh-plugins/dsh-llm-hub@^1.5.1
 # 重启 DSH
 ```
 
@@ -477,16 +486,24 @@ publish。Release 的存在性单独探测，所以「npm 发成功但 Release
   `name` 完全一致**，否则 DSH 拒绝注册。React 由 `factory(require)` 提供，不打包进产物。
   当前体量无需构建步骤；若将来拆多文件，再加 esbuild（`format: 'iife'`，React 等标 external）。
 
-## 🧩 Webkubor DSH 精选扩展家族 (Plugin Suite)
+## 🧩 DSH 插件全家桶
+
+<p align="center">
+  <img src="https://img.webkubor.online/projects/dsh-plugins/dsh-plugins-family.png" alt="DSH 插件全家桶：主题美化 / 模型管理 / 用户记忆 / 电脑环境" width="100%" />
+</p>
+
+<p align="center">
+  <a href="https://github.com/webkubor/dsh-bloom-theme">🎨 主题美化</a> ·
+  <a href="https://github.com/webkubor/dsh-llm-hub">⚡ 模型管理</a> ·
+  <a href="https://github.com/webkubor/dsh-mirror">🪞 用户记忆</a> ·
+  <a href="https://github.com/webkubor/dsh-env-inspector">🖥️ 电脑环境</a>
+</p>
 
-打造极致的 DeepSeek Harness 开发者与用户套件：
+一行装齐（只需 Node.js），装完重启 DSH 即可：
 
-| 插件 | 领域 | 核心功能 | 快速安装 |
-| :--- | :--- | :--- | :--- |
-| [🎨 **dsh-bloom-theme**](https://github.com/webkubor/dsh-bloom-theme) | 主题美化 | 现代毛玻璃美学、暗黑/亮色自适应与 20+ 精选艺术壁纸 | `dsh plugin install @dsh-plugins/dsh-bloom-theme` |
-| [⚡ **dsh-llm-hub**](https://github.com/webkubor/dsh-llm-hub) | 智能路由 | 多模型厂商聚合、秒级切换与故障智能重试 | `dsh plugin install @dsh-plugins/dsh-llm-hub` |
-| [🪞 **dsh-user-mirror**](https://github.com/webkubor/dsh-mirror) | 角色记忆 | 用户数字画像、习惯偏好与记忆沉淀网络 | `dsh plugin install @dsh-plugins/dsh-user-mirror` |
-| [🖥️ **dsh-env-inspector**](https://github.com/webkubor/dsh-env-inspector) | 运行环境 | 活跃端口一键释放、CLI 工具链与开发凭据大屏 | `dsh plugin install @dsh-plugins/dsh-env-inspector` |
+```bash
+npx -y @deepseek-ai/dsh plugin --profile web add dsh-bloom-theme @dsh-plugins/dsh-llm-hub @dsh-plugins/dsh-user-mirror @dsh-plugins/dsh-env-inspector && node -e 'const f=(process.env.DSH_HOME||require("os").homedir()+"/.dsh")+"/profiles/web/package.json",p=require(f),b=p.dsh.profile.bundles;for(const n of Object.keys(p.dependencies))if(/^(dsh-bloom-theme|@dsh-plugins\/)/.test(n)&&!b.includes(n))b.push(n);require("fs").writeFileSync(f,JSON.stringify(p,null,2)+"\n")'
+```
 
 ---
 

package/lib/client.js

@@ -192,6 +192,8 @@ window.__ModuleLoader__.load({
 				routeDeleteGroup: '删除该组',
 				routeUp: '上移',
 				routeDown: '下移',
+				routeNoCandidate: '（还没加候选）',
+				routeFallbackCount: '条兜底',
 				routeRemove: '移除',
 				routeGroupLabelPlaceholder: '组名（公司 / 个人）',
 				routeActiveTag: '当前组',
@@ -344,6 +346,8 @@ window.__ModuleLoader__.load({
 				routeDeleteGroup: 'Delete group',
 				routeUp: 'Move up',
 				routeDown: 'Move down',
+				routeNoCandidate: '(no candidates yet)',
+				routeFallbackCount: 'fallbacks',
 				routeRemove: 'Remove',
 				routeGroupLabelPlaceholder: 'Group name (work / personal)',
 				routeActiveTag: 'active',
@@ -613,7 +617,7 @@ window.__ModuleLoader__.load({
 				'border:.5px solid var(--dsw-alias-state-success-primary);',
 				'color:var(--dsw-alias-state-success-primary)}',
 				'.dsh-llm-hub-routing__suggestion{color:var(--dsw-alias-state-warn-primary);padding-top:2px}',
-				'.dsh-llm-hub-routing__reason{color:var(--dsw-alias-state-error-primary);padding-top:2px}',
+				'.dsh-llm-hub-routing__reason{font-size:10.5px;line-height:1.5;color:var(--dsw-alias-label-tertiary);padding-top:2px}',
 				// composer 快切 chip（conversation.input.left）
 				'.dsh-llm-hub-route{position:relative;display:inline-flex}',
 				'.dsh-llm-hub-route__btn{box-sizing:border-box;display:inline-flex;align-items:center;gap:4px;height:22px;',
@@ -629,8 +633,9 @@ window.__ModuleLoader__.load({
 				'background:var(--dsw-alias-bg-layer-1,rgba(15,15,15,.96));backdrop-filter:blur(14px);',
 				'box-shadow:0 8px 24px rgba(0,0,0,.28);display:flex;flex-direction:column;gap:8px;font-size:11px}',
 				'.dsh-llm-hub-route__modes{display:flex;gap:4px}',
-				'.dsh-llm-hub-route__mode{flex:1;padding:4px 6px;border-radius:5px;border:.5px solid var(--dsw-alias-border-l1);',
-				'background:transparent;color:var(--dsw-alias-label-secondary);cursor:pointer;font:inherit;font-size:10.5px;transition:all .15s ease}',
+				'.dsh-llm-hub-route__mode{flex:0 0 auto;padding:4px 9px;border-radius:5px;border:.5px solid var(--dsw-alias-border-l1);',
+				'background:transparent;color:var(--dsw-alias-label-secondary);cursor:pointer;font:inherit;font-size:10.5px;',
+				'transition:all .15s ease;white-space:nowrap;line-height:1.5}',
 				'.dsh-llm-hub-route__mode.is-on{border-color:var(--dsw-alias-state-warn-primary);color:var(--dsw-alias-state-warn-primary);',
 				'background:var(--dsw-alias-bg-layer-2)}',
 				'.dsh-llm-hub-route__group{display:flex;flex-direction:column;gap:3px;padding:6px 7px;border-radius:6px;',
@@ -655,9 +660,18 @@ window.__ModuleLoader__.load({
 				'.dsh-llm-hub-routing__group.is-active{border-color:var(--dsw-alias-state-warn-primary)}',
 				'.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-label{flex:1;min-width:110px;box-sizing:border-box;height:22px;padding:0 6px;border-radius:4px;',
+				'.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: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{font-size:10.5px;color:var(--dsw-alias-label-secondary);max-width:210px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
+				'.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}',
 				'.dsh-llm-hub-routing__candidates{display:flex;flex-direction:column;gap:3px;padding-top:2px}',
 				'.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);',
@@ -1886,6 +1900,25 @@ window.__ModuleLoader__.load({
 				next.splice(target, 0, item)
 				return { ...group, candidates: next }
 			})
+			/**
+			 * 组之间上下移。
+			 *
+			 * 为什么需要：候选（组内的 provider/model）早就能用 ↑↓ 排，但组本身
+			 * （公司 / 个人 …）此前没有任何排序入口 —— 顺序只能靠手改 settings.yaml。
+			 * 而组的先后是有语义的：activeGroup 之外的组在智能路由下也会按顺序兜底，
+			 * 「先用哪个池子」必须在页面上能配。
+			 *
+			 * @param {number} index - 当前组下标。
+			 * @param {number} delta - -1 上移 / +1 下移。
+			 */
+			const moveGroup = (index, delta) => {
+				const target = index + delta
+				if (target < 0 || target >= groups.length) return
+				const next = [...groups]
+				const [item] = next.splice(index, 1)
+				next.splice(target, 0, item)
+				setDraft(next)
+			}
 			const removeCandidate = (id, index) => editGroup(id, (group) => ({ ...group, candidates: group.candidates.filter((_, i) => i !== index) }))
 			const addCandidate = (id) => {
 				const provider = picker.provider
@@ -1974,20 +2007,54 @@ window.__ModuleLoader__.load({
 				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('button', {
-							type: 'button',
-							className: 'dsh-llm-hub-routing__group-toggle',
-							onClick: () => setExpanded(isOpen ? '' : group.id)
-						}, `${isOpen ? '▾' : '▸'} ${groupIndex + 1}`),
+						// 顺序即优先级，所以序号 + 上下移都得露在折叠态 —— 折叠着也能改顺序。
+						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('button', {
+								type: 'button',
+								className: 'dsh-llm-hub-routing__group-move',
+								title: t('routeUp'),
+								disabled: groupIndex === 0,
+								onClick: () => moveGroup(groupIndex, -1)
+							}, '↑'),
+							h('button', {
+								type: 'button',
+								className: 'dsh-llm-hub-routing__group-move',
+								title: t('routeDown'),
+								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 }))
 						}),
-						live?.wouldRoute
-							? h('span', { className: 'dsh-llm-hub-routing__group-state' }, `${live.wouldRoute.provider}/${live.wouldRoute.model}`)
-							: h('span', { className: 'dsh-llm-hub-routing__group-state' }, live?.reason ?? t('routeChipReasonNone')),
+						// 折叠态给出「这一组会按什么顺序试」的摘要：主力 + 兜底条数。
+						// 之前顺序完全藏在折叠区里，用户看不到自己在排什么。
+						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,
+								]),
 						activeGroup === group.id
 							? h('span', { className: 'dsh-llm-hub-routing__role' }, t('routeActiveTag'))
 							: h('button', {

package/lib/index.js

@@ -2563,12 +2563,37 @@ export function apply(ctx) {
 	}
 
 	/**
-	 * 路由目标专线的可用性：**探测表里没有的 provider 视为不可用**。
+	 * 一个 provider 是否在配置里"存在"：要么 `llm-pi-ai` 段有它的 profile，要么
+	 * `llm-deepseek` 段存在（即官方直连适配器挂上了）。
 	 *
-	 * `stateFor` 把「不认识这个 provider」和「探测结果是 unknown」都折成 unknown，
-	 * 后者可以路由，前者路由过去只会撞 NO_ADAPTER —— 请求直接失败。所以智能路由
-	 * 用这一版：配置里写错 provider 名 / 该 provider 还没注册时，候选被跳过，
-	 * 路由保持 fail-open（不动原配置），而不是把会话打挂。
+	 * 与 `routableStateFor` 配合用：探测表里没记录的 provider，
+	 * 若在此集合里 → 算 unknown（routable，让请求试一把）；
+	 * 不在此集合里 → 才算 unavailable（真不认识，路由过去会撞 NO_ADAPTER）。
+	 * @returns 已知 provider id 的 Set。
+	 */
+	const knownConfiguredProviders = () => {
+		const ids = new Set()
+		for (const [id, profile] of piaiProviders()) {
+			if (profile !== null && typeof profile === 'object') ids.add(id)
+		}
+		if (sectionOf() !== undefined) ids.add(DEEPSEEK_PROVIDER)
+		return ids
+	}
+
+	/**
+	 * 路由目标专线的可用性。
+	 *
+	 * 判定梯度（决定 `pickSmartRoute` 是跳过还是接管）：
+	 *   · 探测表里有 verdict：用 verdict.state（available / unknown / unavailable）
+	 *   · 探测表里没有 + provider 在 settings 里配了 → 'unknown'
+	 *     （冷启动 / 用户刚加 provider / 探针刚清空 —— 不阻塞路由，让请求发出去
+	 *     撞真上游；撞完探针会立刻补 verdict，下一轮就准了）
+	 *   · 探测表里没有 + provider **没在** settings 里 → 'unavailable'
+	 *     （典型：配置里写错名 / 该 provider 还没注册；路由过去只会撞 NO_ADAPTER，
+	 *     fail-open 保留原配置，比打挂请求更稳）
+	 *
+	 * `stateFor` 把前两种情况都折成 'unknown'，所以信息面板里仍是"待探明"，无歧义；
+	 * 区别只在路由**目标**的取与舍 —— 这是 routable vs stateful 的本意。
 	 * @param provider - provider id。
 	 * @returns 'available' | 'unknown' | 'unavailable'。
 	 */
@@ -2576,7 +2601,7 @@ export function apply(ctx) {
 		for (const verdict of baseVerdicts.values()) {
 			if (verdict.provider === provider) return verdict.state
 		}
-		return 'unavailable'
+		return knownConfiguredProviders().has(provider) ? 'unknown' : 'unavailable'
 	}
 
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plugins/dsh-llm-hub",
-  "version": "1.5.5",
+  "version": "1.6.0",
   "description": "DSH 模型管理层：网关可达性探测、模型目录拉取、DeepSeek + MiniMax/智谱/Moonshot/StepFun 余额与配额、本月用量统计、余额预警、Provider 健康看板，再把本机装好的 codex / claude / agy 注册成子代理（装了才出现）。零运行时依赖，不改动 DSH 安装。",
   "type": "module",
   "main": "lib/index.js",
@@ -32,7 +32,7 @@
     "preview": "npm run deploy && open http://127.0.0.1:3080",
     "check": "for f in lib/*.js; do node --check \"$f\" || exit 1; done",
     "test": "node --test",
-    "prepublishOnly": "npm run check && npm test && node scripts/prepublish-gate.mjs"
+    "prepublishOnly": "npm run check && npm test && node scripts/prepublish-gate.mjs && node scripts/readme-gate.mjs"
   },
   "keywords": [
     "dsh",

package/scripts/gate-lib.mjs

@@ -0,0 +1,88 @@
+/**
+ * 发版门禁的纯判据 —— 从 prepublish-gate.mjs 抽出来的可测部分。
+ *
+ * 为什么要抽：门禁脚本顶层会读 package.json、跑 npm pack、连 registry，
+ * 没法直接 import 进来做单元测试；而契约 4 的「纯文档版放行」判据恰恰是
+ * 最需要测的逻辑（判错的两个方向都很难看：误拦文档版 → 逼人用逃生舱；
+ * 误放代码版 → 契约 4 形同虚设）。
+ *
+ * 这些函数**不含任何副作用**，只做字符串/文件内容比对。
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { createHash } from 'node:crypto'
+
+/**
+ * 「运行期载荷」= tarball 里**除了文档/元数据/开发工具之外**的每一个文件。
+ *
+ * 判据必须能机械执行 —— 不用「CHANGELOG 里有没有 feat/fix 关键字」这种启发式
+ * （自省段落里出现一个「修」字就会误放行）。详见 docs/rules/release-semantics.md。
+ */
+export const EXCLUDE = [
+  /^readme(\.[^/]*)?$/i,
+  /^changelog(\.[^/]*)?$/i,
+  /^(license|notice|contributing)(\.[^/]*)?$/i,
+  /^docs\//i,
+  /^assets\//i,
+  /^scripts\//i,
+  /^\.github\//i,
+  /^\.githooks\//i,
+  /^tsconfig[^/]*\.json$/i,
+  /^(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?)$/i,
+  /^(screenshots\.json|llms\.txt|dev_notes[^/]*)$/i,
+  /^(\.npmignore|\.gitignore|\.gitattributes)$/i
+]
+
+export const isRuntime = (p) => !EXCLUDE.some((re) => re.test(p))
+
+/** 递归收集目录下所有文件（相对路径）。 */
+export function collectAllFiles(root) {
+  const out = []
+  const walk = (rel) => {
+    const abs = rel ? join(root, rel) : root
+    let st
+    try { st = statSync(abs) } catch { return }
+    if (st.isDirectory()) {
+      for (const e of readdirSync(abs)) walk(rel ? join(rel, e) : e)
+    } else {
+      out.push(rel)
+    }
+  }
+  walk('')
+  return out
+}
+
+/**
+ * 找出「本次包里内容与上一已发布版不同」的运行期文件。
+ *
+ * 只服务于契约 4 的「载荷指纹相同」分支：指纹相同说明集合级没变，
+ * 这时要再问一句「那到底动了什么」——
+ *   · 动的是运行期文件 → 说明内容变了但指纹没体现（改注释 / 重构不生效分支），拦
+ *   · 全是文档        → 纯文档版，放行
+ *
+ * 比对策略：逐文件 sha256。新增/删除也算「变了」。
+ */
+export function detectChangedRuntime(prevRoot, curRoot, curFiles) {
+  const changed = []
+  const prevFiles = new Set(collectAllFiles(prevRoot))
+
+  const hashOf = (root, rel) => {
+    try { return createHash('sha256').update(readFileSync(join(root, rel))).digest('hex') }
+    catch { return null }
+  }
+
+  for (const rel of curFiles) {
+    if (rel === 'package.json') continue
+    if (!isRuntime(rel)) continue
+    const cur = hashOf(curRoot, rel)
+    if (cur === null) continue
+    const prev = prevFiles.has(rel) ? hashOf(prevRoot, rel) : null
+    if (prev !== cur) changed.push(rel)
+  }
+  for (const rel of prevFiles) {
+    if (rel === 'package.json') continue
+    if (!isRuntime(rel)) continue
+    if (!curFiles.includes(rel)) changed.push(rel + ' (本次已移除)')
+  }
+  return changed
+}

package/scripts/prepublish-gate.mjs

@@ -31,6 +31,7 @@ import { dirname, join, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { tmpdir } from 'node:os'
 import { createHash } from 'node:crypto'
+import { EXCLUDE, isRuntime, collectAllFiles, detectChangedRuntime } from './gate-lib.mjs'
 
 const GATE_VERSION = 1
 
@@ -138,21 +139,6 @@ if (existsSync(changelogPath)) {
 // feat/fix 关键字」这种启发式（自省段落里出现一个「修」字就会误放行）。
 //
 // 详见 docs/rules/release-semantics.md。
-const EXCLUDE = [
-  /^readme(\.[^/]*)?$/i,
-  /^changelog(\.[^/]*)?$/i,
-  /^(license|notice|contributing)(\.[^/]*)?$/i,
-  /^docs\//i,
-  /^assets\//i,
-  /^scripts\//i,
-  /^\.github\//i,
-  /^\.githooks\//i,
-  /^tsconfig[^/]*\.json$/i,
-  /^(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?)$/i,
-  /^(screenshots\.json|llms\.txt|dev_notes[^/]*)$/i,
-  /^(\.npmignore|\.gitignore|\.gitattributes)$/i
-]
-const isRuntime = (p) => !EXCLUDE.some(re => re.test(p))
 
 const RUNTIME_PKG_FIELDS = [
   'name', 'type', 'main', 'module', 'types', 'exports', 'bin', 'dsh', 'files',
@@ -210,12 +196,27 @@ if (process.env.ALLOW_METADATA_ONLY === '1') {
         const before = runtimeFingerprint(prevRoot, collectAllFiles(prevRoot))
         const after = runtimeFingerprint(pkgRoot, packFiles)
         if (JSON.stringify(before) === JSON.stringify(after)) {
-          errors.push(
-            `运行期载荷与上一个已发布版本 ${previous} **完全相同** —— 这个 semver 号没有承载任何用户可感知的变化\n` +
-            `  → 本次只动了: ${packFiles.filter(p => !isRuntime(p)).slice(0, 6).join(', ') || '(仅 package.json 非运行期字段)'}\n` +
-            `  → semver 是对用户的契约: 流程修补 / 元数据修正 / 自省笔记不该占版本号（docs/rules/release-semantics.md）。\n` +
-            `     确实要发纯文档版时显式设 ALLOW_METADATA_ONLY=1`
-          )
+          // 载荷相同有两种情况，必须分开处理（2026-09-27 补）：
+          //
+          //   (a) 本次改动**全是文档**（README / LICENSE / CHANGELOG / assets）——
+          //       这正是 README 包装升级要发版的场景，拦下来只会逼人用逃生舱，
+          //       而 CI 跑 `npm publish` 时根本传不了环境变量。
+          //   (b) 本次动了**代码但载荷碰巧没变**（改了注释、重构了不生效的分支）——
+          //       这才是契约 4 要拦的：「diff 看着有东西，用户其实感知不到」。
+          //
+          // 判据：拿「本次 tarball 里与上一版内容不同的文件」去比对 isRuntime。
+          // 有任何一个是运行期文件 → 走 (b) 拦下；全是文档 → 走 (a) 放行。
+          const changedRuntime = detectChangedRuntime(prevRoot, pkgRoot, packFiles)
+          if (changedRuntime.length > 0) {
+            errors.push(
+              `运行期载荷与上一个已发布版本 ${previous} **完全相同** —— 这个 semver 号没有承载任何用户可感知的变化\n` +
+              `  → 本次改动的运行期文件: ${changedRuntime.slice(0, 6).join(', ')}\n` +
+              `  → 内容变了但载荷指纹没变（改了注释 / 重构了不生效的分支？），用户感知不到任何差异。\n` +
+              `  → semver 是对用户的契约: 流程修补 / 元数据修正 / 自省笔记不该占版本号（docs/rules/release-semantics.md）。`
+            )
+          } else {
+            console.log(`[prepublish-gate]   · 契约 4: 本次为纯文档版（载荷相对 ${previous} 无运行期变化，放行）`)
+          }
         } else {
           console.log(`[prepublish-gate]   · 契约 4: 运行期载荷相对 ${previous} 有变化（${before.length} 项比对）`)
         }
@@ -229,23 +230,6 @@ if (process.env.ALLOW_METADATA_ONLY === '1') {
   }
 }
 
-/** 递归收集目录下所有文件（相对路径），用于对上一版本解包目录做指纹。 */
-function collectAllFiles(root) {
-  const out = []
-  const walk = (rel) => {
-    const abs = rel ? join(root, rel) : root
-    let st
-    try { st = statSync(abs) } catch { return }
-    if (st.isDirectory()) {
-      for (const e of readdirSync(abs)) walk(rel ? join(rel, e) : e)
-    } else {
-      out.push(rel)
-    }
-  }
-  walk('')
-  return out
-}
-
 // ── 报告 ──────────────────────────────────────────────────────────────────
 if (errors.length > 0) {
   console.error(`\n[prepublish-gate] ${errors.length} 条契约不满足, 拒绝发版:\n`)

package/scripts/readme-gate.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+/**
+ * readme-gate —— 开源包装的首屏门禁
+ *
+ * 🔴 这个文件是**拷贝**，真源在 CortexOS：
+ *      CortexOS/scripts/release-gate/readme-gate.mjs
+ *    同步检查：node $CORTEXOS_ROOT/scripts/check-release-gate-sync.mjs
+ *    改逻辑请改真源，然后跑同步脚本把各仓拷一遍 —— 不要在各仓就地改。
+ *
+ * 为什么是门禁而不是文档：cs rule open_source_project_baseline 早就写明了
+ * README 首屏金字塔（居中品牌 → for-the-badge → Why This 对比表 → 30 秒上手），
+ * 但 2026-09-27 一查四个插件，规则说的和仓库里躺的完全是两回事：
+ *
+ *     · 徽章：四个仓全用 style=flat-square（8/10/8/7 个），规则要求 for-the-badge
+ *     · 居中标题：bloom-theme / llm-hub 用 <p align="center"> 而非 <h1 align="center">
+ *     · Why This 对比表：dsh-user-mirror 缺
+ *     · 英文 README：dsh-env-inspector 缺
+ *
+ * 共同点还是那句「约定没做成门禁」。所以把判据做成能跑的：
+ *
+ *   契约 1 居中品牌   —— 存在 <h1 align="center"> 开头且带 emoji/品牌名的标题
+ *   契约 2 徽章规格   —— 至少 1 个 for-the-badge；且不得残留 flat-square
+ *   契约 3 对比矩阵   —— 首屏（前 80 行）内有 Why This 对比表（Markdown 表格）
+ *   契约 4 双语       —— 存在 README.en.md（生态面向全球，英文是默认入场券）
+ *
+ * 逃生舱：README_GATE=off 跳过全部检查（仅限明确不需要包装的内部包）。
+ */
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const GATE_VERSION = 1
+
+const here = dirname(fileURLToPath(import.meta.url))
+const pkgRoot = dirname(here)
+
+const pkg = JSON.parse(readFileSync(join(pkgRoot, 'package.json'), 'utf8'))
+const errors = []
+const notes = []
+
+if (String(process.env.README_GATE).toLowerCase() === 'off') {
+  console.log('[readme-gate] ↩ README_GATE=off —— 跳过首屏包装检查')
+  process.exit(0)
+}
+
+const readmePath = join(pkgRoot, 'README.md')
+if (!existsSync(readmePath)) {
+  console.error('[readme-gate] ✖ 找不到 README.md —— 一个没有 README 的包不可能被人用起来')
+  process.exit(1)
+}
+const readme = readFileSync(readmePath, 'utf8')
+const lines = readme.split(/\r?\n/)
+
+// ── 1. 居中品牌标题 ────────────────────────────────────────────────────────
+// 接受 <h1 align="center">…</h1>；<p align="center"><h1> 也算（有些仓这么写）。
+const h1Centered =
+  /<h1[^>]*align=["']center["'][^>]*>/i.test(readme) ||
+  /<p[^>]*align=["']center["'][^>]*>\s*<h1/i.test(readme)
+
+if (!h1Centered) {
+  errors.push(
+    'README 缺少居中的 <h1 align="center"> 标题\n' +
+    '  → 首屏第一眼必须是品牌：<h1 align="center">🔐 项目名</h1>，紧跟一句居中 slogan'
+  )
+} else {
+  // 标题里带 emoji 或品牌名才像样，光 <h1 align="center"></h1> 是空的
+  const m = readme.match(/<h1[^>]*>([\s\S]*?)<\/h1>/i)
+  if (m && m[1].replace(/<[^>]+>/g, '').trim().length < 2) {
+    errors.push('README 的居中标题是空的 —— 补上 emoji + 项目名')
+  }
+}
+
+// ── 2. 徽章规格：for-the-badge，且不残留 flat-square ───────────────────────
+const badgeCount = (readme.match(/for-the-badge/g) ?? []).length
+const flatSquare = (readme.match(/flat-square/g) ?? []).length
+
+if (badgeCount === 0) {
+  errors.push(
+    'README 没有任何 style=for-the-badge 徽章\n' +
+    '  → 规则要求立体大徽章（style=for-the-badge），版本/许可证/DSH 版本/Build 这几个是基本盘'
+  )
+}
+if (flatSquare > 0) {
+  errors.push(
+    'README 里有 ' + flatSquare + ' 个 style=flat-square 徽章\n' +
+    '  → 统一换成 style=for-the-badge（把 URL 里的 flat-square 直接替换即可），' +
+    '否则首屏是细长方块，视觉重量撑不起品牌'
+  )
+}
+
+// ── 3. Why This 对比矩阵必须在首屏 ─────────────────────────────────────────
+// 「首屏」= 前 80 行。表格判定：连续的 | ... | 行，至少 3 行（表头+分隔+1 行数据）。
+const HEAD_LINES = 80
+const head = lines.slice(0, HEAD_LINES).join('\n')
+const tableBlocks = []
+let run = 0
+for (const l of lines.slice(0, HEAD_LINES)) {
+  if (/^\s*\|.*\|\s*$/.test(l)) { run++; if (run === 3) tableBlocks.push(1) }
+  else run = 0
+}
+const hasWhyTable = tableBlocks.length > 0
+
+if (!hasWhyTable) {
+  errors.push(
+    'README 首屏（前 ' + HEAD_LINES + ' 行）没有对比表格\n' +
+    '  → Why This Table 是转化率的关键：用 ✅ / ❌ 说明「为什么用你这个而不是别的」。' +
+    '同类方案、原生能力、手动配置都值得列成列'
+  )
+}
+
+// ── 4. 英文 README ─────────────────────────────────────────────────────────
+const hasEn = ['README.en.md', 'README.en-US.md', 'README.en_US.md']
+  .some((f) => existsSync(join(pkgRoot, f)))
+
+if (!hasEn) {
+  errors.push(
+    '缺少英文 README（README.en.md）\n' +
+    '  → dsh-plugin 生态面向全球，英文是默认入场券；中文 README 首行加上 [English](README.en.md) | 中文'
+  )
+}
+
+// ── 额外提示（不拦，但值得知道）───────────────────────────────────────────
+const shotCount = ['assets']
+  .flatMap((d) => {
+    const p = join(pkgRoot, d)
+    if (!existsSync(p)) return []
+    return readdirSync(p).filter((f) => /\.(png|jpe?g|webp|gif)$/i.test(f))
+  }).length
+if (shotCount === 0) {
+  notes.push('assets/ 里没有截图 —— 插件页没图等于没人点，建议至少 1 张真实界面截图')
+}
+
+// ── 汇总 ───────────────────────────────────────────────────────────────────
+if (errors.length > 0) {
+  console.error('[readme-gate] ✖ README 首屏不合规（gate v' + GATE_VERSION + '）：')
+  for (const e of errors) console.error('  · ' + e)
+  console.error('\n  真源：cs rule open_source_project_baseline（README 金字塔标准）')
+  console.error('  逃生舱：README_GATE=off（仅限内部包）')
+  process.exit(1)
+}
+
+console.log('[readme-gate] ✓ README 首屏四条契约通过（gate v' + GATE_VERSION + '）')
+console.log('  · for-the-badge 徽章 ' + badgeCount + ' 个；首屏对比表 ' + tableBlocks.length + ' 个；英文版 ✓')
+for (const n of notes) console.log('  · 提示：' + n)