@noob-stupid/dsh-plugin-console 0.5.71 → 0.5.85

package/lib/server/domain/disk-audit.js

@@ -0,0 +1,330 @@
+// L1 · domain —— disk-audit.js（`<DSH_HOME>/plugin-console` 的**只读体检** + **用户确认后**的清理；0.5.84 加法）
+// 分层分组：L1 · domain（不认识 cordis ctx；读盘/删除全部可注入）
+//
+// ── 为什么（用户 2026-10 第 7 项）────────────────────────────────────────────────
+//   这个目录涨到 2.1 GB：`framework-backups/` 里躺着历次框架升级前的**整棵树**（含全平台 office kit）。
+//   用户要的是「先看清楚谁占的，再决定删什么」——**绝不自动删**。
+//
+// ── 本模块的死规矩（每一条都有测试盯着；违背任何一条都比不清理更糟）───────────────
+//   ① **只读体检**：`auditConsoleDir()` 只统计，绝不删、不写、不改任何东西。
+//   ② **候选分级**：每一项标 `level`：
+//        · 'safe'      —— 删掉不影响任何功能（日志、旧自删守护留下的计数残渣、`*.bak-*` 状态备份、
+//                        本机测试残留 `persist-e2e-*`）；
+//        · 'tradeoff'  —— 删掉**会失去某种回退能力**（旧版本的框架备份、profile 快照备份）——
+//                        必须让人知道代价，仍然允许，但要说清楚；
+//        · 'protected' —— **绝不**列为可删：当前回滚点指向的检查点、当前框架版本的备份、
+//                        控制台自己的状态文件（compat-* / framework-state.json / install-jobs.json / sources…）。
+//       ⚠️ 真机实测（2026-10）：最大的那 2.1 GB 正是 `framework-backups/0.2.0-rc.1` ——
+//          而 `framework-rollback.json` 的 `checkpointDir` **就指向它**。所以"最大的那个"恰恰是**不能删**的：
+//          删了等于把当前唯一的框架回滚点销毁。判据必须从回滚记录里读，不能按体积猜。
+//   ③ **边界**：只允许删 `<root>` 之内、且经 `planCleanup()` 白名单放行的项；任何绝对路径/`..`一律拒。
+//   ④ **必须显式确认**：`runCleanup({ confirm: true })` 才动;否则返回 plan（"将删什么、能省多少"）。
+//   ⑤ **删完读回核实**：删不干净就如实回报（本仓 fsx.js 记过：Windows 上 rmSync 会静默落空）。
+import { existsSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
+
+/** 单次体检最多统计多少个文件（防止在异常目录上跑到天荒地老；超了如实标记 truncated）。 */
+const MAX_FILES = 60000
+/** 认为是"日志"的文件名。 */
+const LOG_RE = /\.log$/iu
+/** 状态备份（旧实现留下的 `.bak-<时间>`）：删了只失去"那时候的状态"。 */
+const STATE_BAK_RE = /\.bak-\d/iu
+/** 旧实现留下的自删守护计数（0.5.84 的代码已经不再创建它们）。 */
+const GUARD_RESIDUE_RE = /^restart-guard-\d+\.count$/iu
+/** 本机测试残留（含旧实现留下的 console-restart.log）。 */
+const TEST_RESIDUE_RE = /^(?:persist-e2e-|console-restart\.log$)/iu
+/** 需要**按子项**展开的目录：判据要细到"哪一份备份"，而不是整个目录一刀切。
+ *  为什么必须展开（真机 2026-10 实测）：`framework-backups/` 里 2.1 GB 全在 0.2.0-rc.1 这一份，
+ *  而回滚点正好指向它；其余 9 份加起来不到 2 MB。若按顶层整目录判，整块只能标"受保护"⇒
+ *  用户永远清不掉那 9 份旧备份；展开成子项后，只有被回滚点引用的那份受保护，其余标 tradeoff。 */
+const EXPAND_DIRS = new Set(['framework-backups', 'profile-sync-backups'])
+/** 绝不能删的状态文件（名字精确匹配或前缀匹配）。 */
+const PROTECTED_FILES = new Set([
+  'framework-rollback.json', 'framework-state.json', 'install-jobs.json', 'compat-pending.json',
+  'compat-gate.json', 'compat-mode.json', 'compat-ack.json', 'components.json', 'repo-land.json',
+  'preset-sources.json', 'auto-preflight.json', 'env-fingerprint.json', 'fw-quarantine.json',
+  'fw-quarantine-candidates.json', 'sources.json', 'ai-jobs.json', 'lock-autofix.json',
+])
+const PROTECTED_PREFIX = ['fw-upgrade-state.txt', 'link-self-sufficiency', 'source-specs', 'safe-boot', 'subdir-src']
+
+/** 递归量体积（字节 + 文件数）；只读，且带 MAX_FILES 上限。 */
+function measure(dir, { readdir = readdirSync, stat = statSync, budget = { files: MAX_FILES } } = {}) {
+  let bytes = 0
+  let files = 0
+  let truncated = false
+  const walk = (current) => {
+    let entries = []
+    try {
+      entries = readdir(current, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      if (budget.files <= 0) { truncated = true; return }
+      const full = join(current, entry.name)
+      if (entry.isDirectory()) {
+        walk(full)
+        continue
+      }
+      budget.files -= 1
+      files += 1
+      try {
+        bytes += stat(full).size
+      } catch {}
+    }
+  }
+  walk(dir)
+  return { bytes, files, truncated }
+}
+
+/** 当前框架回滚记录（读不到返回 null）——**最大的那份备份往往就是它指向的**。 */
+function readRollbackPointer({ root, readFile = (p) => readFileSync(p, 'utf8') } = {}) {
+  try {
+    const rec = JSON.parse(readFile(join(root, 'framework-rollback.json')))
+    return {
+      from: typeof rec?.from === 'string' ? rec.from : null,
+      to: typeof rec?.to === 'string' ? rec.to : null,
+      checkpointDir: typeof rec?.checkpointDir === 'string' ? rec.checkpointDir : null,
+      cliBackupDir: typeof rec?.cliBackupDir === 'string' ? rec.cliBackupDir : null,
+      at: typeof rec?.at === 'number' ? rec.at : null,
+    }
+  } catch {
+    return null
+  }
+}
+
+const mb = (bytes) => Math.round((bytes / 1024 / 1024) * 100) / 100
+
+/**
+ * **只读体检**：返回
+ * `{ ok, root, totalBytes, totalFiles, truncated, rollback, entries:[{ id, name, kind, bytes, files, level, reason }], reclaimableBytes, safeBytes }`。
+ * `entries` 按体积降序；`level` 见文件头 ②。任何一项都不删、不写。
+ */
+function auditConsoleDir({ root, deps = {} } = {}) {
+  const base = typeof root === 'string' && root !== '' ? resolve(root) : null
+  if (base === null) return { ok: false, error: '拿不到 plugin-console 目录', entries: [], totalBytes: 0, totalFiles: 0, truncated: false, rollback: null, reclaimableBytes: 0, safeBytes: 0 }
+  if (!existsSync(base)) return { ok: true, root: base, totalBytes: 0, totalFiles: 0, truncated: false, rollback: null, entries: [], reclaimableBytes: 0, safeBytes: 0, note: '目录还不存在（没产生过备份/日志）' }
+  const readdir = deps.readdir ?? readdirSync
+  const stat = deps.stat ?? statSync
+  const rollback = readRollbackPointer({ root: base, ...(deps.readFile === undefined ? {} : { readFile: deps.readFile }) })
+  const budget = { files: MAX_FILES }
+  let names = []
+  try {
+    names = readdir(base)
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error), entries: [], totalBytes: 0, totalFiles: 0, truncated: false, rollback, reclaimableBytes: 0, safeBytes: 0 }
+  }
+  const entries = []
+  let totalBytes = 0
+  let totalFiles = 0
+  let truncated = false
+  for (const name of names) {
+    const full = join(base, name)
+    let isDir = false
+    let fileBytes = 0
+    try {
+      const st = stat(full)
+      isDir = st.isDirectory()
+      if (!isDir) fileBytes = st.size
+    } catch {
+      continue
+    }
+    if (isDir && EXPAND_DIRS.has(name)) {
+      // 展开成子项（见 EXPAND_DIRS 的注释：判据要细到"哪一份备份"）
+      let children = []
+      try {
+        children = readdir(full)
+      } catch {
+        children = []
+      }
+      for (const child of children) {
+        const childFull = join(full, child)
+        let childIsDir = false
+        try {
+          childIsDir = stat(childFull).isDirectory()
+        } catch {
+          continue
+        }
+        const m = childIsDir ? measure(childFull, { readdir, stat, budget }) : { bytes: stat(childFull).size, files: 1, truncated: false }
+        if (m.truncated) truncated = true
+        totalBytes += m.bytes
+        totalFiles += m.files
+        entries.push({ id: `${name}/${child}`, name: child, parent: name, full: childFull, isDir: childIsDir, bytes: m.bytes, files: m.files })
+      }
+      continue
+    }
+    let bytes = fileBytes
+    let files = isDir ? 0 : 1
+    if (isDir) {
+      const m = measure(full, { readdir, stat, budget })
+      bytes = m.bytes
+      files = m.files
+      if (m.truncated) truncated = true
+    }
+    totalBytes += bytes
+    totalFiles += files
+    entries.push({ id: name, name, parent: null, full, isDir, bytes, files })
+  }
+  // ── 分级（唯一判据；面板与清理都不许另判一套）──────────────────────────────────
+  const inRollback = []
+  for (const p of [rollback?.checkpointDir, rollback?.cliBackupDir]) {
+    if (typeof p === 'string' && p !== '') inRollback.push(resolve(p))
+  }
+  const classify = (entry) => {
+    const { name, full, isDir, parent } = entry
+    // ① 回滚点指向的东西：绝不列为可删（真机实测：最大的 2.1 GB 就是这个）
+    if (inRollback.some((p) => resolve(full) === p || resolve(full) === resolve(p, '..') || p.startsWith(resolve(full) + sep))) {
+      return { level: 'protected', reason: '当前框架回滚点（framework-rollback.json）指向这里 —— 删掉就等于销毁唯一的回滚点' }
+    }
+    // ② 纯垃圾类（**先于**状态文件判据：`fw-upgrade-state.txt.bak-<时间>` 是那份状态的旧备份，
+    //    删它不丢当前状态；而 `fw-upgrade-state.txt` 本身仍然受下面的前缀保护）
+    if (!isDir && (LOG_RE.test(name) || GUARD_RESIDUE_RE.test(name) || STATE_BAK_RE.test(name) || TEST_RESIDUE_RE.test(name))) {
+      return { level: 'safe', reason: LOG_RE.test(name) ? '日志：删了只是丢历史输出'
+        : GUARD_RESIDUE_RE.test(name) ? '旧实现自删守护留下的计数残渣（现在的代码已不创建）'
+          : STATE_BAK_RE.test(name) ? '旧状态文件的 .bak 备份（当前状态文件不在清理范围）'
+            : '本机测试残留' }
+    }
+    if (isDir && TEST_RESIDUE_RE.test(name)) return { level: 'safe', reason: '本机测试残留' }
+    // ③ 控制台状态：一律不许动
+    if (PROTECTED_FILES.has(name) || PROTECTED_PREFIX.some((p) => name === p || name.startsWith(p))) {
+      return { level: 'protected', reason: '控制台状态文件/受保护目录（删了会丢配置、记录或已安装子目录插件的源码）' }
+    }
+    // ④ 展开出来的子项（framework-backups/<版本> / profile-sync-backups/<快照>）
+    if (parent === 'framework-backups') {
+      return { level: 'tradeoff', reason: '某一版本框架升级前的整棵树备份：删掉会失去回滚到该版本的能力（当前回滚点引用的那一份不在此列）' }
+    }
+    if (parent === 'profile-sync-backups') {
+      return { level: 'tradeoff', reason: '某一次 profile 快照备份：删掉会失去那一次的快照，不影响当前运行' }
+    }
+    if (isDir && (name === 'backups' || /^pre-upgrade-snapshot-/u.test(name))) {
+      return { level: 'tradeoff', reason: '历史快照备份：删掉会失去那几次的快照，不影响当前运行' }
+    }
+    if (isDir && name === 'release-0.5.38') {
+      return { level: 'tradeoff', reason: '旧版本的发布物副本：不影响当前运行' }
+    }
+    return { level: 'protected', reason: '未知/状态类条目：不在清理白名单里（宁可不删）' }
+  }
+  const graded = entries.map((entry) => {
+    const g = classify(entry)
+    return {
+      id: entry.id,
+      name: entry.name,
+      parent: entry.parent ?? null,
+      kind: entry.isDir ? 'dir' : 'file',
+      mb: mb(entry.bytes),
+      bytes: entry.bytes,
+      files: entry.files,
+      level: g.level,
+      reason: g.reason,
+    }
+  }).sort((a, b) => b.bytes - a.bytes)
+  const reclaimable = graded.filter((e) => e.level === 'safe' || e.level === 'tradeoff')
+  const safe = graded.filter((e) => e.level === 'safe')
+  return {
+    ok: true,
+    root: base,
+    totalBytes,
+    totalFiles,
+    totalMb: mb(totalBytes),
+    truncated,
+    rollback,
+    entries: graded,
+    reclaimableBytes: reclaimable.reduce((sum, e) => sum + e.bytes, 0),
+    reclaimableMb: mb(reclaimable.reduce((sum, e) => sum + e.bytes, 0)),
+    safeBytes: safe.reduce((sum, e) => sum + e.bytes, 0),
+    safeMb: mb(safe.reduce((sum, e) => sum + e.bytes, 0)),
+  }
+}
+
+/**
+ * 清理**计划**（纯函数，不删任何东西）：把用户点名的 id 过一遍白名单与边界。
+ * @returns {{ ok, plan:[{id,bytes,level}], refused:[{id,reason}], freedBytes, note }}
+ *   · 只接受 `audit.entries` 里出现过的 id；`protected` 一律拒绝并说明为什么；
+ *   · 任何包含 `/` `\` `..` 的 id 直接拒绝（路径穿越）。
+ */
+function planCleanup({ audit, ids } = {}) {
+  const list = Array.isArray(ids) ? ids : (typeof ids === 'string' && ids !== '' ? [ids] : [])
+  const byName = new Map((Array.isArray(audit?.entries) ? audit.entries : []).map((e) => [e.id, e]))
+  const plan = []
+  const refused = []
+  for (const raw of list) {
+    const id = typeof raw === 'string' ? raw.trim() : ''
+    if (id === '') continue
+    // 允许 `name` 或 `父目录/子项`（只展开一层：framework-backups/<版本>、profile-sync-backups/<快照>）；
+    // 任何 `..`、绝对路径、多级路径一律拒 —— 删东西的口子越小越好。
+    if (id === '..' || id === '.' || id.startsWith('/') || /^[A-Za-z]:/u.test(id) || (id.match(/\//gu) ?? []).length > 1 || /\\/u.test(id) || id.includes('..')) {
+      refused.push({ id, reason: '不是本目录下的条目名（拒绝路径穿越）' })
+      continue
+    }
+    const entry = byName.get(id)
+    if (entry === undefined) { refused.push({ id, reason: '体检结果里没有这一项（请先做一次体检）' }); continue }
+    if (entry.level === 'protected') { refused.push({ id, reason: entry.reason }); continue }
+    plan.push({ id, bytes: entry.bytes, mb: entry.mb, level: entry.level, reason: entry.reason })
+  }
+  return {
+    ok: refused.length === 0 && plan.length > 0,
+    plan,
+    refused,
+    freedBytes: plan.reduce((sum, p) => sum + p.bytes, 0),
+    freedMb: mb(plan.reduce((sum, p) => sum + p.bytes, 0)),
+    note: plan.length === 0 ? (refused.length === 0 ? '没有指定要清理的条目' : '所有指定条目都被拒绝了') : null,
+  }
+}
+
+/**
+ * **真的删**（只有在 `confirm === true` 时才会动）：删前再过一次 planCleanup，删后读回核实。
+ * @returns {{ ok, applied:boolean, removed:[], failed:[{id,reason}], needsConfirm:boolean, freedBytes, freedMb, plan }}
+ */
+function runCleanup({ root, audit, ids, confirm = false, deps = {} } = {}) {
+  const exists = deps.exists ?? existsSync
+  const remove = deps.remove ?? ((p) => rmSync(p, { recursive: true, force: false }))
+  const planResult = planCleanup({ audit, ids })
+  const base = typeof root === 'string' && root !== '' ? resolve(root) : (typeof audit?.root === 'string' ? resolve(audit.root) : null)
+  if (base === null) return { ok: false, applied: false, needsConfirm: false, removed: [], failed: [], freedBytes: 0, freedMb: 0, plan: planResult, error: '拿不到 plugin-console 目录' }
+  if (confirm !== true) {
+    // 没确认 ⇒ 只回计划（面板据此渲染"确认清理"按钮），**一个文件都不动**
+    return { ok: false, applied: false, needsConfirm: true, removed: [], failed: [], freedBytes: 0, freedMb: 0, plan: planResult, note: '需要显式确认（confirm:true）才会删除；未确认前后一个字都没动' }
+  }
+  const removed = []
+  const failed = []
+  let freed = 0
+  for (const item of planResult.plan) {
+    const target = resolve(base, item.id)
+    // 边界：目标必须在 root 之内（resolve 过，`..` 已经被 planCleanup 挡掉，这里是第二道）
+    if (!target.startsWith(resolve(base) + sep)) {
+      failed.push({ id: item.id, reason: '目标不在 plugin-console 目录内（拒绝删除）' })
+      continue
+    }
+    try {
+      remove(target)
+    } catch (error) {
+      failed.push({ id: item.id, reason: error instanceof Error ? error.message : String(error) })
+      continue
+    }
+    // 读回核实：Windows 上 rmSync 可能静默落空（infra/fsx.js 记过这类事）
+    if (exists(target)) {
+      failed.push({ id: item.id, reason: '删除后目录仍在（静默落空）' })
+      continue
+    }
+    removed.push({ id: item.id, bytes: item.bytes, mb: item.mb })
+    freed += item.bytes
+  }
+  return {
+    ok: failed.length === 0 && removed.length > 0,
+    applied: true,
+    needsConfirm: false,
+    removed,
+    failed,
+    freedBytes: freed,
+    freedMb: mb(freed),
+    plan: planResult,
+    note: failed.length === 0
+      ? `已清理 ${removed.length} 项，释放约 ${mb(freed)} MB`
+      : `清理了 ${removed.length} 项（约 ${mb(freed)} MB），但有 ${failed.length} 项没清干净（原因见 failed）`,
+  }
+}
+
+export {
+  GUARD_RESIDUE_RE, LOG_RE, MAX_FILES, PROTECTED_FILES, PROTECTED_PREFIX, STATE_BAK_RE, TEST_RESIDUE_RE,
+  auditConsoleDir, measure, planCleanup, readRollbackPointer, runCleanup,
+}

package/lib/server/domain/enrich-throttle.js

@@ -0,0 +1,242 @@
+// L1 · domain —— enrich-throttle.js（市场卡片「富化请求」的**唯一出口闸**；0.5.84 加法）
+// 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言；不认识 cordis ctx）
+//
+// ── 为什么要有这一层（真机症状）──────────────────────────────────────────────────
+//   一次打开市场面板，服务端会对**每一条**卡片发出下面这些请求（domain/market.js#enrichItemOne）：
+//     · package.json：curl 直连 + ghproxy 镜像（Promise.any 两条同时发）
+//     · SKILL.md    ：curl 直连 + ghproxy + jsDelivr（三条同时发，见 domain/skills.js#detectSkillRepo）
+//     · .gitmodules ：rawTextFetch 的四条通道竞速（https / gh / curl / jsDelivr）
+//   ⇒ 单条卡片最坏 ≈ 9 个并发请求，而 enrichItems 的 worker 数是 12 ⇒ 面板一打开就是 ≈100 个连接
+//     同时抢出去；raw.githubusercontent 在这个量级下几乎全部 ERR_TIMED_OUT / 404，
+//     网络被占满，安装作业（pnpm / clone）跟着卡 —— 用户看到的是「市场一直在转圈」。
+//
+// ── 这一层干什么（四条，缺一条都还会打满网络）────────────────────────────────────
+//   ① **并发上限**：所有富化请求共用**一个** limiter（默认 4）。不是每个调用点各写一份
+//      Promise.all —— 那样上限会随调用点数量相乘而失效。
+//   ② **单飞（single-flight）**：同一个 URL 同时只发一次。市场面板 + 详情卡片 + 搜索并发打开时，
+//      它们问的是同一批 URL，重复发没有意义。
+//   ③ **负缓存（短期记忆）**：失败的 URL 10 分钟内**不再发请求**，直接短路失败。
+//      这就是"不要反复重试同一个失败 URL"——黑洞期里重试只会继续吃掉并发额度。
+//   ④ **短缓存**：成功结果缓存 5 分钟（富化判定本身另有 24h/1h 缓存，见 market.js）。
+//      短缓存只解决"同一批卡片在几分钟内被反复打开"。
+//   另：**单次超时不许长**。富化是"锦上添花"的判定，不该占用 10s 的抓取预算（那 10s 是给
+//   安装路径上"必须读到清单"的场景的）；本模块把富化探针的预算统一压到 4s。
+//
+// ── 语义边界（重要）──────────────────────────────────────────────────────────────
+//   · 本模块**只做闸门与记忆**，不做判定：成功/失败/404 的解释权仍在各通道自己手里。
+//   · `throttledCurlText` / `throttledCurlJson` **失败仍然抛错**（与裸实现一致）—— 上游用
+//     `Promise.any` / `allSettled` 写的分支逻辑一个字都不用改；负缓存命中时也抛（只是不发请求）。
+//   · `throttledRawText` **失败仍然返回 null**（与 rawTextWithFallback 一致）。
+//   · 生产不注入任何东西就是真实现（默认值直接来自 infra/http.js，与全仓出网单点同一套）。
+import { FETCH_OK, curlJson, curlText, rawTextFetch } from '../infra/http.js'
+
+/** 并发上限（真机结论：4 条就够快，更多只会把网络打满）。 */
+const ENRICH_CONCURRENCY = 4
+/** 失败记忆窗口：这段时间内同一个 key 不再发请求。 */
+const FAILURE_COOLDOWN_MS = 10 * 60 * 1000
+/** 成功短缓存：同一批卡片在几分钟内重复打开不再打网络。 */
+const SHORT_CACHE_TTL_MS = 5 * 60 * 1000
+/** 富化探针的单次预算上限（"不要把单次超时设得太长"）。 */
+const ENRICH_TIMEOUT_MS = 4000
+/** 记忆表上限（防止长时间运行后无限增长；满了淘汰最旧的一批）。 */
+const MEMORY_LIMIT = 4000
+
+/** 计数限流器：`run(fn)` 在有空位时才真正执行 fn（队列 FIFO，绝不丢弃）。 */
+function makeLimiter(max) {
+  const size = Number.isFinite(max) && max > 0 ? Math.floor(max) : 1
+  let active = 0
+  let peak = 0
+  const queue = []
+  const pump = () => {
+    while (active < size && queue.length > 0) {
+      const job = queue.shift()
+      active += 1
+      if (active > peak) peak = active
+      Promise.resolve()
+        .then(job.fn)
+        .then(job.resolve, job.reject)
+        .then(() => { active -= 1; pump() }, () => { active -= 1; pump() })
+    }
+  }
+  return {
+    run(fn) {
+      return new Promise((resolve, reject) => { queue.push({ fn, resolve, reject }); pump() })
+    },
+    stats() { return { max: size, active, queued: queue.length, peak } },
+  }
+}
+
+/** 记忆表：`Map` + 上限淘汰（只清最旧的一批，不整体清空 —— 否则上限一到就等于没有记忆）。 */
+function boundedSet(map, key, value) {
+  if (map.size >= MEMORY_LIMIT) {
+    const drop = Math.max(1, Math.floor(MEMORY_LIMIT / 4))
+    let n = 0
+    for (const k of map.keys()) { map.delete(k); if (++n >= drop) break }
+  }
+  map.set(key, value)
+}
+
+// ── 模块级状态（一个进程一份闸门；`__resetEnrichThrottle()` 供单测还原）─────────────
+const state = {
+  limiter: makeLimiter(ENRICH_CONCURRENCY),
+  inflight: new Map(),   // key → Promise（单飞）
+  okCache: new Map(),    // key → { at, value }
+  failCache: new Map(),  // key → at（负缓存）
+  skipped: 0,            // 被负缓存短路掉的请求数（面板诊断用）
+  ran: 0,                // 真的发出去的请求数
+}
+
+/** 出网实现的注入缝（默认 = infra/http.js 的真实现；单测换成 tripwire 即可证明"一个请求都没发"）。 */
+let impl = null
+/** 单测注入出口实现：传对象 = 打桩（缺项回落真实现）；传 null = 还原。返回是否已注入。 */
+function __setEnrichThrottleImpl(next) {
+  impl = next !== null && typeof next === 'object' ? next : null
+  return impl !== null
+}
+
+/** 清空全部记忆与在途记录（单测 & 诊断用；已在途的请求不会被取消）。 */
+function __resetEnrichThrottle() {
+  state.limiter = makeLimiter(ENRICH_CONCURRENCY)
+  state.inflight.clear()
+  state.okCache.clear()
+  state.failCache.clear()
+  state.skipped = 0
+  state.ran = 0
+}
+
+/** 闸门现状（面板诊断 / 单测断言"并发确实被压住"用）。 */
+function enrichThrottleStats() {
+  return {
+    ...state.limiter.stats(),
+    inflight: state.inflight.size,
+    okCacheSize: state.okCache.size,
+    failCacheSize: state.failCache.size,
+    skipped: state.skipped,
+    ran: state.ran,
+    concurrencyLimit: ENRICH_CONCURRENCY,
+    failureCooldownMs: FAILURE_COOLDOWN_MS,
+    shortCacheTtlMs: SHORT_CACHE_TTL_MS,
+    timeoutMs: ENRICH_TIMEOUT_MS,
+  }
+}
+
+/** 占位错误：负缓存命中时用它短路（带上原因，别让上游以为是"文件不存在"）。 */
+function coolingDownError(key, waitMs) {
+  const error = new Error(`富化请求在冷却期（${Math.max(1, Math.round(waitMs / 1000))}s 内不再重试）：${key}`)
+  error.code = 'ENRICH_COOLING_DOWN'
+  return error
+}
+
+/**
+ * 过闸执行一次富化请求（**唯一入口**）。
+ * @param {string} key  记忆键（同一份内容必须给出同一个 key）
+ * @param {() => Promise<any>} run 真请求（抛错 = 失败；返回值由 accept 判定算不算"读到了"）
+ * @param {object} [opts]
+ * @param {(v:any) => boolean} [opts.accept] 什么算成功（默认"非空字符串"）
+ * @param {number} [opts.okTtlMs]   成功短缓存时长
+ * @param {number} [opts.failTtlMs] 失败记忆时长
+ * @returns {Promise<any>} 成功值；冷却命中/失败由调用方包装成各自的语义
+ */
+async function throughGate(key, run, opts = {}) {
+  const accept = typeof opts.accept === 'function' ? opts.accept : (v) => typeof v === 'string' && v.trim() !== ''
+  const okTtlMs = Number.isFinite(opts.okTtlMs) ? opts.okTtlMs : SHORT_CACHE_TTL_MS
+  const failTtlMs = Number.isFinite(opts.failTtlMs) ? opts.failTtlMs : FAILURE_COOLDOWN_MS
+  const now = Date.now()
+  // ④ 短缓存命中
+  const cached = state.okCache.get(key)
+  if (cached !== undefined) {
+    if (now - cached.at < okTtlMs) return cached.value
+    state.okCache.delete(key)
+  }
+  // ③ 负缓存命中 → **不发请求**，直接按"这次也不会有"短路
+  const failedAt = state.failCache.get(key)
+  if (failedAt !== undefined) {
+    if (now - failedAt < failTtlMs) {
+      state.skipped += 1
+      throw coolingDownError(key, failTtlMs - (now - failedAt))
+    }
+    state.failCache.delete(key)
+  }
+  // ② 单飞：同一 key 的并发调用共用同一个 Promise
+  const running = state.inflight.get(key)
+  if (running !== undefined) return running
+  const task = state.limiter
+    .run(() => { state.ran += 1; return run() })
+    .then((value) => {
+      if (accept(value)) {
+        boundedSet(state.okCache, key, { at: Date.now(), value })
+        state.failCache.delete(key)
+        return value
+      }
+      boundedSet(state.failCache, key, Date.now())
+      throw new Error('富化请求未读到内容')
+    }, (error) => {
+      boundedSet(state.failCache, key, Date.now())
+      throw error
+    })
+    .finally(() => { state.inflight.delete(key) })
+  state.inflight.set(key, task)
+  return task
+}
+
+/** 预算归一：富化探针一律压到 ENRICH_TIMEOUT_MS 以内。 */
+function budgetOf(timeoutMs) {
+  const wanted = Number.isFinite(timeoutMs) ? timeoutMs : ENRICH_TIMEOUT_MS
+  return Math.min(Math.max(wanted, 800), ENRICH_TIMEOUT_MS)
+}
+
+/**
+ * 过闸的 `curlText`（**失败仍然抛错**，与裸实现同语义）。
+ * @param {string} url
+ * @param {number} [timeoutMs] 超过 ENRICH_TIMEOUT_MS 会被压到上限
+ */
+async function throttledCurlText(url, timeoutMs = ENRICH_TIMEOUT_MS, opts = {}) {
+  const real = typeof impl?.curlText === 'function' ? impl.curlText : curlText
+  return await throughGate(`text:${url}`, () => real(url, budgetOf(timeoutMs), opts.curlOpts ?? {}), opts)
+}
+
+/** 过闸的 `curlJson`（**失败仍然抛错**）。 */
+async function throttledCurlJson(url, timeoutMs = ENRICH_TIMEOUT_MS, opts = {}) {
+  const real = typeof impl?.curlJson === 'function' ? impl.curlJson : curlJson
+  return await throughGate(
+    `json:${url}`,
+    () => real(url, budgetOf(timeoutMs), opts.headers ?? {}),
+    { ...opts, accept: opts.accept ?? ((v) => v !== null && typeof v === 'object') },
+  )
+}
+
+/**
+ * 过闸的 raw 抓取（**失败仍然返回 null**，与 rawTextWithFallback 同语义）。
+ * 通道竞速仍在 infra/http.js（四条通道一条不删），只是**预算由这里压到 ENRICH_TIMEOUT_MS 以内**
+ * 并共用同一个闸门 —— 富化探针绝不允许占用安装路径那 10s 的抓取预算。
+ */
+async function throttledRawText(repo, branch, path, opts = {}) {
+  const real = typeof impl?.rawTextFetch === 'function' ? impl.rawTextFetch : rawTextFetch
+  const budget = budgetOf(opts.budgetMs)
+  try {
+    const text = await throughGate(`raw:${repo}@${branch}/${path}`, async () => {
+      const { state: st, body } = await real(repo, branch, path, budget)
+      return st === FETCH_OK ? body : null
+    }, opts)
+    return typeof text === 'string' ? text : null
+  } catch {
+    // 冷却期 / 抓取失败 / 404 → 都是"这次没读到"，与 rawTextWithFallback 的 null 同义
+    return null
+  }
+}
+
+export {
+  ENRICH_CONCURRENCY,
+  ENRICH_TIMEOUT_MS,
+  FAILURE_COOLDOWN_MS,
+  SHORT_CACHE_TTL_MS,
+  MEMORY_LIMIT,
+  makeLimiter,
+  throughGate,
+  throttledCurlText,
+  throttledCurlJson,
+  throttledRawText,
+  enrichThrottleStats,
+  __resetEnrichThrottle,
+  __setEnrichThrottleImpl,
+}

package/lib/server/domain/install-finalize.js

@@ -32,7 +32,9 @@ async function finalizeInstallPersistence({
   // 与运行时已有行都不算，旧代码在这两条路上也不设 entryId）——撤销安装的归属判定依赖这一点。
   job.entryId = persist.after.parts.mount.via === 'patch-row' ? (persist.rowId ?? null) : null
   job.persisted = persist.persisted
-  job.persist = { missing: persist.missing, actual: persist.after.actual, note: persist.note }
+  // 0.5.84 判据降噪：把「这次不一致会不会丢插件」的结论一并下发（面板据此决定报红还是降级提示）。
+  // 纯加法：missing / actual / note 三个老字段一字未变，老客户端忽略 severity 即可。
+  job.persist = { missing: persist.missing, actual: persist.after.actual, note: persist.note, severity: persist.after?.severity ?? persist.severity ?? null }
   if (persist.persisted !== true) job.persistNote = persist.note
   const persistSuggested = persist.suggested ?? null
   if (persistSuggested !== null

package/lib/server/domain/install-job.js

@@ -1,7 +1,4 @@
 // L1 · domain —— install-job.js（安装任务编排：多通道安装 + 套装补丁 + 适配门 + 收尾）。
-// 分层 Step 8c-2 从 lib/index.js 搬出；形参由 ctx 收窄为 ports（调用方注入的窄接口），只搬移未改逻辑。
-// 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言）
-
 import { dirname, join, resolve } from 'node:path'
 import { aiRepair } from './ai-run.js'
 import { maybeAutoAdaptCompat } from './compat.js'
@@ -71,6 +68,9 @@ function channelImpls(ports) {
  *    属无意义尝试）**并保留 !expanded**（同一作业里对同一个 job.repo 反复 clone 纯属浪费时间，
  *    级联顺序也不该被破坏）。 */
 async function tryCandidateChannels({ job, ch, name, profileDir, registries, repoChannelAllowed, budget, baseUrl = null, expanded = false, deadline = null, expand = null, sourceDeps = {} }) {
+  const installSpec = (typeof job?.version === 'string' && job.version !== '' && name === job.packageName)
+    ? `${name}@${job.version}`
+    : name // ★ 0.5.81：规格与身份分离 —— name 仍是身份；点名包+指定版本时规格才带 @version
   // 声明行的目标 profile（0.5.28）：框架 0.1.7-rc.x 起预设不再靠目录发现，装配后必须往这个 profile 的补丁写 `preset-<id>` 行，否则用户看不见（见 preset-declare.js 顶部）。
   const patchPath = join(profileDir, 'cordis.patch.yml')
   let installedName = null
@@ -88,7 +88,7 @@ async function tryCandidateChannels({ job, ch, name, profileDir, registries, rep
   // 通道 0：并行竞速（pnpm 与 curl 同时启动，先成功者生效；失败方 abort，不影响后续串行通道）——守卫①
   {
     try {
-      const raced = await ch.raceInstallChannels(profileDir, name, registries)
+      const raced = await ch.raceInstallChannels(profileDir, installSpec, registries)
       if (raced) {
         installedName = name
         if (raced.channel === 'curl') {
@@ -117,7 +117,7 @@ async function tryCandidateChannels({ job, ch, name, profileDir, registries, rep
   let pnpmError = null
   for (let ri = 0; ri < registries.length && installedName === null; ri += 1) {
     try {
-      await ch.pnpmInstall(profileDir, name, registries[ri])
+      await ch.pnpmInstall(profileDir, installSpec, registries[ri])
       installedName = name
       break
     } catch (error) { lastError = error; pnpmError = error }