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

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 本项目遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## [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 项过。
+
 ## [1.5.5] - 2026-09-27
 
 ### 🪧 路由卡：每条候选的能力 chip（思考 + 多模态）

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>
 

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.5.6",
   "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/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)