@dsh-plugins/dsh-llm-hub 1.5.2 → 1.5.4

package/CHANGELOG.md

@@ -2,6 +2,74 @@
 
 本项目遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## [1.5.4] - 2026-09-27
+
+### 🛡️ 智能路由接管的两处加固（1.5.0 的补丁）
+
+1.5.0 让 `smart` 模式用 `agent/request` waterfall 真实改写请求的 provider/model。
+两处会在真机上把会话打挂的边界，这一版补上：
+
+#### 未注册 / 未探测到的 provider 不当路由目标
+
+- **病灶**：`stateFor` 把「不认识这个 provider」与「探测结果是 unknown」都折成
+  `unknown`，而 `unknown` 在裁决里是**可用**的（首次路由需要它兜底）。于是配置里
+  写错一个 provider 名（或该 provider 还没注册）时，接管会把请求指向一个不存在的
+  adapter，请求以 `NO_ADAPTER` 直接失败 —— 比不接管更糟。
+- **修法**：新增 `routableStateFor` —— 探测表里查不到的 provider 一律视为
+  `unavailable`，候选被跳过、路由保持 fail-open（不动原配置）。手动模式下的建议
+  列表仍用旧的 `stateFor`（那里 unknown 是诚实的信息，不是路由目标）。
+- **验证**：`test/host-routing-groups.test.mjs` 覆盖组解析与裁决；`node --test`
+  120 项全过。
+
+#### 首次请求预热可用性探测
+
+- **病灶**：生产环境里可用性探测此前只由客户端触发（打开设置页 / 下拉重探）。
+  开机后如果没人开设置页，探测表是空的 → smart 模式全部候选被判 `unavailable`
+  → 路由长期静默不生效，表现为「开了智能模式但一直在用原模型」。
+- **修法**：`agent/request` 里若 `baseVerdicts` 为空，后台热一把
+  `ensureAvailabilityFresh()`（不阻塞当次请求），这次仍 fail-open 走原配置。
+
+**没做**：没有发布任何新功能，也没有改配置格式 —— `groups` / `mode` / `activeGroup`
+与切组入口（composer 路由 chip）与 1.5.0–1.5.3 完全一致。
+
+## [1.5.3] - 2026-09-26
+
+### 🛂 工程纪律对齐
+
+#### 发版脚本 + tarball 收齐
+
+- `scripts/prepublish-gate.mjs` 列入 `package.json#files`，随 tarball 出厂（1.5.2 时漏配）。
+- 这条本身没功能改动，单纯是「门禁脚本要在 tarball 里」的一致性修补。
+
+#### 作者身份纠正（修 1.5.0/1.5.1/1.5.2 的提交）
+
+**根因**：1.5.0/1.5.1/1.5.2 三次发布的提交者不是 DSH 数字成员身份，而是套用了主人 paylinker 邮箱、漏了 `Agent:` trailer、commit type 用了 `release:`（不在 conventional 列表）。违反：
+
+- `commit_convention §1`：数字成员用自己的 D1 email，禁止套主人邮箱。
+- `commit_convention §1.5`：本机 CLI 提交必须带 `Agent: cli:<id>` trailer。
+- `commit_convention §2`：commit type 必须是 `feat / fix / refactor / chore / docs / style / test / ci / perf`。
+- `external-cli-layering`：GitHub 操作应该走 L1 `gh` CLI 而不是 L3 `curl`。
+
+**为什么 1.5.0/1.5.1/1.5.2 不改**：tag 已发布、npm tarball 不可变、GH Release body 已建，回滚会
+让那一批点升级的用户装不到。本版只**纠正未来**：
+
+- 1.5.3 起 commit author 署 `DSH <dsh@webkubor.online>`（D1 上的 agent 身份）。
+- trailer：`Agent: cli:claude-code`。
+- commit type 用 conventional 写法 `chore(release):`。
+- GH 操作走 `gh` CLI。
+
+**为什么这次保留 `dsh-llm-hub` 的工作流**：1.5.0/1.5.1/1.5.2 的 commit 内容、CHANGELOG、assets/ 都是
+对的，错的只是元数据（author / trailer / type）。元数据修一遍不影响业务，下次升级自然拉到
+1.5.3 的内容。
+
+**没有破坏性变更**，没有功能改动。
+
+升级：
+
+```bash
+dsh plugin --profile web update @dsh-plugins/dsh-llm-hub@^1.5.3
+```
+
 ## [1.5.2] - 2026-09-26
 
 ### 🔧 发版门禁 + README 推广区

package/lib/index.js

@@ -169,13 +169,18 @@ const WARNING_CHECK_PATH = '/api/dsh-llm-hub/warning/check'
 /**
  * 智能路由建议：把当前可用性 + 用户声明的 fallback 顺序折成「该用哪个」。
  *
- * **不做自动切换** —— DSH 的 `conversation.input.model` 是 single + user-controlled
- * slot（`replaceRisk: shadows-shipped-ui`），没有供插件改的 setter；强行覆盖会
- * 撞 README 红线。这条路由返回的是**建议**，真值为用户在 UI 里点一下。
+ * 1.5.0 起语义升级：这条路由仍然只**建议**（composer 的 `conversation.input.model`
+ * 是 single + user-controlled slot，插件不碰它）；真正的自动接管走
+ * `agent/request` waterfall（见本文件「智能路由组 + 模式接管」段）—— manual 模式
+ * 下这里就是全部，smart 模式下这里变成「读一眼路由现状」的视图。
  *
- * 请求体：当前已激活用户的 provider/model（如 'modelgo' / 'gpt-4o'），返回：
+ * 请求体：当前已激活的 provider/model（如 'modelgo' / 'gpt-4o'），可选 `group`
+ * 指定组；返回：
  *   {
  *     ok: true,
+ *     mode: 'manual'|'smart',
+ *     activeGroup: 'company',
+ *     groups: [{ id, label, candidateCount }, ...],
  *     active: { provider, model, state: 'available'|'unknown'|'unavailable' },
  *     candidates: [{ provider, model, state, ... }, ...],   // 主 → fallback → 备用
  *     recommendation: { provider, model } | null,            // 第一个 available 的
@@ -2473,6 +2478,23 @@ export function apply(ctx) {
 		return 'unknown'
 	}
 
+	/**
+	 * 路由目标专线的可用性：**探测表里没有的 provider 视为不可用**。
+	 *
+	 * `stateFor` 把「不认识这个 provider」和「探测结果是 unknown」都折成 unknown，
+	 * 后者可以路由，前者路由过去只会撞 NO_ADAPTER —— 请求直接失败。所以智能路由
+	 * 用这一版：配置里写错 provider 名 / 该 provider 还没注册时，候选被跳过，
+	 * 路由保持 fail-open（不动原配置），而不是把会话打挂。
+	 * @param provider - provider id。
+	 * @returns 'available' | 'unknown' | 'unavailable'。
+	 */
+	const routableStateFor = (provider) => {
+		for (const verdict of baseVerdicts.values()) {
+			if (verdict.provider === provider) return verdict.state
+		}
+		return 'unavailable'
+	}
+
 	/**
 	 * 路由解析：给客户端返回「该用哪个 + 原因」（1.5.0 起按组解析）。
 	 * @param active - 客户端 POST 进来的当前已激活 (provider, model)。
@@ -2572,7 +2594,7 @@ export function apply(ctx) {
 				...(group.primary !== null ? [group.primary] : []),
 				...group.fallbacks
 			]
-			const winner = pickSmartRoute(candidates, (provider) => stateFor(provider, ''), null)
+			const winner = pickSmartRoute(candidates, (provider) => routableStateFor(provider), null)
 			return {
 				id: group.id,
 				label: group.label,
@@ -2688,13 +2710,16 @@ export function apply(ctx) {
 			if (config === null || typeof config !== 'object') return config
 			const state = routingGroupsOf()
 			if (state.mode !== 'smart' || state.groups.length === 0) return config
+			// 探测表空 = 还没人探过。后台热一把（不阻塞这次请求），这次照 fail-open 走原配
+			// —— 否则「刚开机就发请求」会让智能路由一直等到用户开设置页才生效。
+			if (baseVerdicts.size === 0) ensureAvailabilityFresh()
 			const group = state.groups.find((candidate) => candidate.id === state.activeGroup) ?? state.groups[0]
 			const candidates = [
 				...(group.primary !== null ? [group.primary] : []),
 				...group.fallbacks
 			]
 			const active = { provider: config.provider, model: config.model }
-			const decision = pickSmartRoute(candidates, (provider) => stateFor(provider, ''), active)
+			const decision = pickSmartRoute(candidates, (provider) => routableStateFor(provider), active)
 			lastSmartDecision.at = Date.now()
 			lastSmartDecision.group = group.id
 			lastSmartDecision.from = active

package/package.json

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

package/scripts/prepublish-gate.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+/**
+ * prepublish-gate —— 发版前的机械门禁（四条契约）
+ *
+ * 🔴 这个文件是**拷贝**，真源在 CortexOS：
+ *      CortexOS/scripts/release-gate/prepublish-gate.mjs
+ *    同步检查：`node $CORTEXOS_ROOT/scripts/check-release-gate-sync.mjs`
+ *    改逻辑请改真源，然后跑同步脚本把各仓拷一遍 —— 不要在各仓就地改。
+ *
+ * 为什么是门禁而不是文档：2026-09-26 一天里给 dsh-llm-hub 发了 1.5.0/1.5.1/1.5.2/1.5.3
+ * 四个版本号，用户可感知的变化只有 1.5.0 一个；同一轮还漏了 bloom-theme 的 assets
+ * （README 引用 11 个相对路径截图、tarball 里 0 个 → npm 页面上全是坏图；那 11 张合计
+ * 10MB，正确修法是换成图床直链而不是把 10MB 塞进每个安装包）。共同点是
+ * 「约定没做成门禁」，所以把判据做成能跑的：
+ *
+ *   契约 1 产物完整性 —— package.json 必须在；`files` 里每个字面量条目至少命中一个文件；
+ *                       main / types / exports / dsh 引用的相对路径文件必须存在。
+ *   契约 2 图片引用   —— README 里以**相对路径**引用的 assets/* 必须在 tarball 里。
+ *                       否则 npm 页面上是坏图（bloom-theme 就是这么坏的）。
+ *                       只认 `](assets/…)` 与 `src="assets/…"`，不认 URL 里的 assets/
+ *                       （raw.githubusercontent 那种在 npm 上照样能显示，不算坏图）。
+ *   契约 3 CHANGELOG  —— 存在 CHANGELOG.md 时，必含 `## [<当前 version>]` 段。
+ *   契约 4 发版语义   —— 运行期载荷必须与上一个已发布版本**不同**。
+ *                       见 docs/rules/release-semantics.md；ALLOW_METADATA_ONLY=1 是逃生舱。
+ *
+ * 任一条挂了 → exit 1 + stderr 指明错在哪、怎么修。
+ */
+import { readFileSync, mkdtempSync, rmSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { execFileSync } from 'node:child_process'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { tmpdir } from 'node:os'
+import { createHash } from 'node:crypto'
+
+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 version = pkg.version
+const errors = []
+
+// ── 0. 打包清单 ────────────────────────────────────────────────────────────
+let packFiles
+try {
+  const out = execFileSync('npm', ['pack', '--dry-run', '--json'], {
+    cwd: pkgRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit']
+  })
+  packFiles = JSON.parse(out)[0].files.map(f => f.path)
+} catch (err) {
+  console.error('[prepublish-gate] npm pack --dry-run 失败:', err.message)
+  process.exit(2)
+}
+const inPack = (p) => packFiles.includes(p)
+
+// ── 1. 产物完整性 ──────────────────────────────────────────────────────────
+if (!inPack('package.json')) errors.push('tarball 里没有 package.json')
+
+// files[] 里的字面量条目（不含 glob）必须命中至少一个文件
+for (const entry of pkg.files ?? []) {
+  if (/[*?[\]{}!]/.test(entry)) continue            // glob 跳过
+  const e = entry.replace(/\/$/, '')
+  const hit = packFiles.some(f => f === e || f.startsWith(e + '/'))
+  if (!hit) {
+    errors.push(`package.json#files 声明了 '${entry}'，但 tarball 里一个文件都没有\n  → 条目过期或文件被删/被 ignore`)
+  }
+}
+
+// main / types / module / bin / exports / dsh.bundle 引用的路径必须在 tarball 里。
+// 只走这几个字段，因为 package.json 里别的字符串不是路径 —— 典型陷阱：
+// `dsh.client.platform: "web"` 和 `dsh.client.inject: ["@deepseek-ai/..."]`
+// 一旦被当成路径就会误报。
+const entryPaths = new Set()
+const addPath = (v) => {
+  if (typeof v !== 'string' || v === '') return
+  if (/^[a-z][a-z0-9+.-]*:/i.test(v) || v.startsWith('/')) return   // URL / 绝对路径
+  entryPaths.add(v.replace(/^\.\//, ''))
+}
+const walkStrings = (v) => {
+  if (typeof v === 'string') addPath(v)
+  else if (v && typeof v === 'object') for (const x of Object.values(v)) walkStrings(x)
+}
+for (const field of ['main', 'types', 'module', 'bin', 'exports']) walkStrings(pkg[field])
+if (pkg.dsh && typeof pkg.dsh === 'object') walkStrings(pkg.dsh.bundle)
+
+for (const p of entryPaths) {
+  if (!inPack(p)) {
+    errors.push(`package.json 的入口字段引用了 '${p}'，但 tarball 里没有\n  → 装包的人会在 require/import 时直接失败`)
+  }
+}
+
+// ── 2. README 里相对引用的 assets/* 必须在 tarball 里 ──────────────────────
+const readmes = ['README.md', 'README.en.md', 'README.zh.md', 'README.zh-CN.md']
+  .filter(f => existsSync(join(pkgRoot, f)))
+
+const referencedAssets = new Set()
+for (const f of readmes) {
+  const text = readFileSync(join(pkgRoot, f), 'utf8')
+  // 只认相对引用：](assets/x) 与 src="assets/x"。URL 里的 assets/ 不算。
+  for (const m of text.matchAll(/\]\((assets\/[^)\s]+)\)/g)) referencedAssets.add(m[1])
+  for (const m of text.matchAll(/src=["'](assets\/[^"']+)["']/g)) referencedAssets.add(m[1])
+}
+
+const missingAssets = [...referencedAssets].filter(a => existsSync(join(pkgRoot, a)) && !inPack(a))
+if (missingAssets.length > 0) {
+  errors.push(
+    `README 引用了 ${missingAssets.length} 个 assets 文件，但 tarball 里没有 —— npm 页面上会是坏图:\n` +
+    missingAssets.slice(0, 5).map(a => `    · ${a}`).join('\n') +
+    (missingAssets.length > 5 ? `\n    …（共 ${missingAssets.length} 个）` : '') +
+    `\n  → 二选一：(a) 把 'assets' 加进 package.json 的 'files'（图小就用这个）；` +
+    `\n                (b) 把 README 改成图床绝对 URL 并确认真能打开（图大就用这个，别把十几 MB 塞进每个安装包）`
+  )
+}
+
+// ── 3. CHANGELOG 必须有当前版本段 ──────────────────────────────────────────
+// 标题写法各仓不一（`## [1.5.3]` / `## 3.7.0 (2026-09-16)` /
+// `## [0.14.0](compare-link) (2026-09-25)` / `## v0.14.0`），
+// 只认「二级标题 + 版本号本身」，不强制 keep-a-changelog 的方括号。
+// 版本号后用负向前瞻收尾，避免 0.14.0 命中 0.14.01 这种前缀。
+const changelogPath = join(pkgRoot, 'CHANGELOG.md')
+if (existsSync(changelogPath)) {
+  const text = readFileSync(changelogPath, 'utf8')
+  const esc = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const heading = new RegExp(`^##\\s*\\[?v?${esc}(?![\\d.])`, 'm')
+  if (!heading.test(text)) {
+    errors.push(
+      `CHANGELOG.md 缺少当前版本（${version}）的二级标题段\n` +
+      `  → 发版正文（GitHub Release / npm 页）直接取这一段；缺了会出现「npm 上了 / Release 没建」的漂移`
+    )
+  }
+}
+
+// ── 4. 发版语义：运行期载荷必须与上一已发布版本不同 ────────────────────────
+//
+// 「运行期载荷」= tarball 里**除了文档/元数据/开发工具之外**的每一个文件，
+// 外加 package.json 的运行期字段。判据要能机械执行 —— 不用「CHANGELOG 里有没有
+// 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',
+  'dependencies', 'peerDependencies', 'optionalDependencies', 'engines'
+]
+
+/** 运行期载荷指纹: 排序后的 "路径:哈希" 列表。 */
+function runtimeFingerprint(root, list) {
+  const entries = []
+  for (const rel of list) {
+    if (!isRuntime(rel)) continue
+    if (rel === 'package.json') continue
+    try {
+      entries.push([rel, createHash('sha256').update(readFileSync(join(root, rel))).digest('hex')])
+    } catch { /* 目录项或读不到，跳过 */ }
+  }
+  try {
+    const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+    const runtimePkg = {}
+    for (const f of RUNTIME_PKG_FIELDS) {
+      if (manifest[f] !== undefined) runtimePkg[f] = manifest[f]
+    }
+    entries.push(['package.json(运行期字段)', createHash('sha256').update(JSON.stringify(runtimePkg)).digest('hex')])
+  } catch { /* 读不到是别处的问题 */ }
+  return entries.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+}
+
+if (process.env.ALLOW_METADATA_ONLY === '1') {
+  console.warn('[prepublish-gate] ⚠️  ALLOW_METADATA_ONLY=1 —— 跳过契约 4（纯文档/元数据版本）')
+} else {
+  try {
+    const raw = execFileSync('npm', ['view', pkg.name, 'versions', '--json'], {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore']
+    })
+    const parsed = JSON.parse(raw)
+    const list = Array.isArray(parsed) ? parsed : [parsed]
+    const previous = list.filter(v => v !== version).pop()
+
+    if (previous === undefined) {
+      console.log(`[prepublish-gate]   · 契约 4: ${pkg.name} 尚无更早版本, 跳过载荷比对`)
+    } else {
+      const tarballUrl = execFileSync('npm', ['view', `${pkg.name}@${previous}`, 'dist.tarball'], {
+        encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore']
+      }).trim()
+      const stage = mkdtempSync(join(tmpdir(), 'prepublish-gate-'))
+      try {
+        const tgz = join(stage, 'prev.tgz')
+        const res = await fetch(tarballUrl)
+        if (!res.ok) throw new Error(`下载 ${previous} tarball 失败: HTTP ${res.status}`)
+        const { writeFileSync } = await import('node:fs')
+        writeFileSync(tgz, Buffer.from(await res.arrayBuffer()))
+        execFileSync('tar', ['-xzf', tgz, '-C', stage], { stdio: 'ignore' })
+        const prevRoot = join(stage, 'package')
+
+        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`
+          )
+        } else {
+          console.log(`[prepublish-gate]   · 契约 4: 运行期载荷相对 ${previous} 有变化（${before.length} 项比对）`)
+        }
+      } finally {
+        rmSync(stage, { recursive: true, force: true })
+      }
+    }
+  } catch (err) {
+    // 网络/registry 不可用时不阻断发版：门禁不该因为一次查询失败就卡住真实发布。
+    console.warn(`[prepublish-gate] ⚠️  契约 4 未能执行（不阻断）: ${err.message}`)
+  }
+}
+
+/** 递归收集目录下所有文件（相对路径），用于对上一版本解包目录做指纹。 */
+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`)
+  for (const e of errors) {
+    console.error('  ✖', e)
+    console.error('')
+  }
+  console.error('[prepublish-gate] exit 1 → npm publish 已中止。修完再推。')
+  process.exit(1)
+}
+
+console.log(`[prepublish-gate] ✓ ${pkg.name}@${version} 四条契约通过（gate v${GATE_VERSION}）`)
+console.log(`[prepublish-gate]   · tarball ${packFiles.length} 个文件；运行期载荷 ${packFiles.filter(isRuntime).length} 个`)
+if (referencedAssets.size > 0) console.log(`[prepublish-gate]   · README 引用的 ${referencedAssets.size} 个 assets 均在包内`)
+console.log(`[prepublish-gate]   · CHANGELOG 含当前版本段`)