@noob-stupid/dsh-plugin-console 0.5.92 → 0.5.94

package/lib/server/domain/update-batch.js

@@ -0,0 +1,181 @@
+// L1 · domain —— update-batch.js（已安装插件「一键检测全部更新」的批量执行器；issue #22 ①）
+// 分层分组：L1 · domain（tests/test-architecture-guard.mjs 断言边界；不认识 cordis ctx、不联网、不碰盘）
+//
+// ── 它解决什么 ────────────────────────────────────────────────────────────────
+//   issue #22 ①：`familyCheckUpdate` 只覆盖全家桶内部，单独装的第三方插件要逐个点卡片上的「检测更新」。
+//   批量检测 = 把 N 个包名丢给同一个探针（probe）跑一遍。风险只有一个，而且是**已经发生过的那一个**：
+//
+// ── 并发上限为什么必须在这里、而且是"进程一份" ─────────────────────────────────
+//   0.5.84 的真机事故（domain/enrich-throttle.js 顶部有完整记录）：市场富化当时按"每条卡片各发自己的
+//   请求"来写，worker 12 × 每条 9 通道 ≈ 100 个连接同时出去，网络被占满，安装作业（pnpm / clone）跟着卡死。
+//   结论：限流器**不能每个调用点各写一份** —— 那样上限会随调用点数量相乘而失效。
+//   这里因此分两层：
+//     · `createBatchUpdater()` 造出来的是**进程级一份**实例（路由模块加载时造一次），并发上限与缓存在
+//       所有调用点之间共享 → 用户连点两次「一键检测」也不会变成两份并发；
+//     · 探针本身随请求变（它要用本次请求的 ctx），所以以 `run(names, { probe })` 的形式**每次传入**，
+//       而不是在工厂里绑死 —— 即"闸门是共享的，被执行的活是每次的"。
+//   上限取 4：与 enrich-throttle 的 ENRICH_CONCURRENCY 同一个实测结论（4 条就够快，更多只会打满网络）。
+//
+// ── 判据（版本比较）不在这里 ──────────────────────────────────────────────────
+//   本模块**不做任何版本比较**：谁新谁旧由探针（probe）回答，而探针是 `routes/framework.js#probePackageUpdate`
+//   —— 单卡「检测更新」用的**同一份**代码，末尾走 `dropStaleUpdateCandidates` + `pickUpdateTarget`，
+//   也就是 `infra/semver.js` 里 `<<<update-pick>>>` 那块唯一判据（tests/test-update-version-pick.mjs 钉死）。
+//   本模块只把结论归成三态（batchStatusOf），不参与"哪个版本更高"的判断。
+//
+// ── 三态语义（面板据此标注卡片；不猜）──────────────────────────────────────────
+//   · 'update'  ：探针给出了严格更高的目标版本（target 非空）→ 卡片可以出现「更新」按钮；
+//   · 'current' ：探针查到了候选，但没有比已装更高的（target 为空、错误为空）→ 「已最新」；
+//   · 'unknown' ：探针**一个候选都没拿到**（npm/GitHub 都没答上来）→ 「未检测到」。绝不把它说成"已最新"：
+//                 没查到 ≠ 没有新版。
+//
+// ── 缓存（60s TTL）为什么值得有 ────────────────────────────────────────────────
+//   批量入口一次要问几十个包；用户点完一次再点一次（或换筛选后回来点）没有理由再打一遍网络。
+//   TTL 内直接复用上轮结论，响应里 `cached: true` 如实标注这是复用而不是新查的。
+//   `force: true` 越过缓存（面板将来若要"强制重查"就是这个开关）。
+import { makeLimiter } from './enrich-throttle.js'
+
+/** 并发上限（与域内富化闸同一实测结论：4 条够快，再多只会把网络打满）。 */
+const BATCH_UPDATE_CONCURRENCY = 4
+/** 结论缓存时长：同一批包在这段时间内重复点「一键检测」不再打网络。 */
+const BATCH_UPDATE_TTL_MS = 60 * 1000
+/** 单次批量最多接受多少个包名（防"把整个 registry 拉一遍"这种自伤用法）。 */
+const BATCH_UPDATE_MAX = 200
+
+/**
+ * 把一次探针结论归成三态（纯函数；**不比较版本**，版本高低由探针/唯一判据给出）。
+ * @param {{target?: string|null, latest?: string|null, next?: string|null, beta?: string|null, error?: string|null}|null|undefined} result
+ * @returns {'update'|'current'|'unknown'}
+ */
+function batchStatusOf(result) {
+  const src = result !== null && typeof result === 'object' ? result : {}
+  const target = typeof src.target === 'string' ? src.target.trim() : ''
+  if (target !== '') return 'update'
+  const hasCandidate = [src.latest, src.next, src.beta].some((v) => typeof v === 'string' && v.trim() !== '')
+  if (hasCandidate) return 'current'
+  // 一个候选都没有：查得到结论（error 为空）才算"已最新"；查不到就是"未检测到"
+  return typeof src.error === 'string' && src.error !== '' ? 'unknown' : 'current'
+}
+
+/**
+ * 造一个批量更新检测器。**路由模块加载时造一次、进程内共享**（并发上限与缓存都是共享的）。
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.concurrency] 并发上限（默认 BATCH_UPDATE_CONCURRENCY=4）
+ * @param {number} [opts.ttlMs]       结论缓存时长（默认 60s）
+ * @param {number} [opts.max]         单次最多处理的包名数（默认 200）
+ * @param {() => number} [opts.now]   时钟注入缝（单测判缓存过期用）
+ */
+function createBatchUpdater({ concurrency = BATCH_UPDATE_CONCURRENCY, ttlMs = BATCH_UPDATE_TTL_MS, max = BATCH_UPDATE_MAX, now = Date.now } = {}) {
+  const limit = Number.isFinite(concurrency) && concurrency > 0 ? Math.floor(concurrency) : BATCH_UPDATE_CONCURRENCY
+  const ttl = Number.isFinite(ttlMs) && ttlMs >= 0 ? ttlMs : BATCH_UPDATE_TTL_MS
+  const cap = Number.isFinite(max) && max > 0 ? Math.floor(max) : BATCH_UPDATE_MAX
+  // ★ 进程一份闸门（不是每次 run 一份）：连点两次也共用同一个上限
+  const limiter = makeLimiter(limit)
+  /** packageName → { at, result }（结论缓存；失败也缓存，避免黑洞期反复打同一个包） */
+  const cache = new Map()
+  const counters = { runs: 0, probed: 0, cacheHits: 0, failures: 0 }
+
+  /**
+   * 跑一次批量检测。
+   * @param {string[]} packageNames 包名（调用方已校验；这里仍会去重/截断，但**不**放宽校验）
+   * @param {object} io
+   * @param {(packageName: string) => Promise<object>} io.probe 探针（单包结论）
+   * @param {(packageName: string) => (string|null)} [io.installedOf] 已装版本（只作展示，不参与判据）
+   * @param {boolean} [io.force] 越过缓存
+   * @returns {Promise<{ items: Array<object>, checked: number, updatable: number, unknown: number, stats: object }>}
+   */
+  async function run(packageNames, io = {}) {
+    const probe = typeof io.probe === 'function' ? io.probe : null
+    const installedOf = typeof io.installedOf === 'function' ? io.installedOf : null
+    const force = io.force === true
+    const list = []
+    const seen = new Set()
+    for (const raw of Array.isArray(packageNames) ? packageNames : []) {
+      const name = typeof raw === 'string' ? raw.trim() : ''
+      if (name === '' || seen.has(name)) continue
+      seen.add(name)
+      list.push(name)
+      if (list.length >= cap) break
+    }
+    counters.runs += 1
+    if (probe === null) {
+      // 没有探针就是接线错了 —— 如实报，不假装"都没有更新"
+      return { items: [], checked: 0, updatable: 0, unknown: 0, error: '没有提供探针（probe），拒绝把"查不到"说成"已最新"', stats: statsOf() }
+    }
+    // ① 缓存命中判定（同步做，保持结果顺序与请求顺序一致）
+    const slots = list.map((packageName) => {
+      const hit = force ? undefined : cache.get(packageName)
+      const fresh = hit !== undefined && now() - hit.at < ttl
+      if (fresh) counters.cacheHits += 1
+      return { packageName, cached: fresh ? hit : null, fromCache: fresh }
+    })
+    // ② 未命中的并发查（**全部**经同一个 limiter；队列 FIFO，绝不丢弃）
+    await Promise.all(slots.map(async (slot) => {
+      if (slot.cached !== null) return
+      let result
+      try {
+        counters.probed += 1
+        result = await limiter.run(() => probe(slot.packageName))
+        if (result === null || typeof result !== 'object') {
+          result = { latest: null, next: null, beta: null, target: null, error: '探针没有返回结论', source: 'npm', depsOutdated: [], migrate: null }
+          counters.failures += 1
+        }
+      } catch (error) {
+        // 单包失败**只影响自己**：批量里一个包炸掉不许拖垮其余（如实带上原因）
+        counters.failures += 1
+        result = { latest: null, next: null, beta: null, target: null, error: error instanceof Error ? error.message : String(error), source: 'npm', depsOutdated: [], migrate: null }
+      }
+      cache.set(slot.packageName, { at: now(), result })
+      slot.cached = { at: now(), result }
+    }))
+    // ③ 组装（顺序 = 请求顺序；每项都带 status 与 cached，前端无需自己推）
+    const items = slots.map((slot) => {
+      const result = slot.cached !== null && typeof slot.cached === 'object' ? slot.cached.result : {}
+      return {
+        packageName: slot.packageName,
+        installedVersion: installedOf === null ? null : installedOf(slot.packageName),
+        latest: result.latest ?? null,
+        next: result.next ?? null,
+        beta: result.beta ?? null,
+        target: result.target ?? null,
+        source: result.source ?? 'npm',
+        error: result.error ?? null,
+        depsOutdated: Array.isArray(result.depsOutdated) ? result.depsOutdated : [],
+        migrate: result.migrate ?? null,
+        status: batchStatusOf(result),
+        // 如实标注这一项是"本轮新查的"还是"复用 TTL 内的缓存"
+        cached: slot.fromCache === true,
+      }
+    })
+    return {
+      items,
+      checked: items.length,
+      updatable: items.filter((i) => i.status === 'update').length,
+      unknown: items.filter((i) => i.status === 'unknown').length,
+      stats: statsOf(),
+    }
+  }
+
+  function statsOf() {
+    const limiterStats = limiter.stats()
+    // 注意：limiter.stats() 也有一个 `max`（= 并发上限）。这里把它摊平改名，避免与本模块的
+    // `maxPackages`（单次最多多少个包）撞名 —— 两个"上限"含义完全不同，撞名会读错诊断。
+    return {
+      concurrencyLimit: limit,
+      ttlMs: ttl,
+      maxPackages: cap,
+      cacheSize: cache.size,
+      cacheHits: counters.cacheHits,
+      probed: counters.probed,
+      runs: counters.runs,
+      failures: counters.failures,
+      active: limiterStats.active,
+      queued: limiterStats.queued,
+      peak: limiterStats.peak,
+    }
+  }
+
+  return { run, stats: statsOf, clearCache: () => cache.clear() }
+}
+
+export { BATCH_UPDATE_CONCURRENCY, BATCH_UPDATE_TTL_MS, BATCH_UPDATE_MAX, batchStatusOf, createBatchUpdater }

package/lib/server/routes/annotations.js

@@ -0,0 +1,82 @@
+// L2 · routes —— /annotations（用户备注 / 用户徽章 / 用户分组；issue #22 ②③）
+//
+// 两条路由，同一个路径（与既有的 `/sources` 同一手法：GET 只读住守卫前，POST 吃 body 住守卫后）：
+//   · GET  /plugin-console/annotations  → 读整份注解（**纯只读**，永不抛；坏文件降级 + 带原因）
+//   · POST /plugin-console/annotations  → 一次写动作（action 见 domain/plugin-annotations.js）
+//
+// 三条边界：
+//   ① **与插件列表完全解耦**：注解读/写失败只影响这两条路由，绝不进 /state 的路径
+//      （插件列表照常渲染；"注解坏了不该让我看不见插件"——用户明确要求）。
+//   ② 写动作全部走 domain 的四步（备份 → 原子写 → 读回核实 → 回滚），路由只做**入参映射 + 状态码**：
+//      校验 400、坏文件/重名 409、分组不存在 404、其余 200。绝不在这里自己写盘。
+//   ③ 成功时回**整份最新状态**（plugins + groups + stats），面板不必再请求一次就能重绘
+//      （少一次往返，也避免"写成功但界面还是旧的"这种自相矛盾）。
+//
+// 路由注册：`lib/server/routes/index.js`（GET 在 ROUTES_EARLY，POST 在 ROUTES）；
+// 路由清单：`tests/test-route-inventory.mjs`。
+import { annotationsSummary, annotationsPath, applyAnnotation, readAnnotations } from '../domain/plugin-annotations.js'
+import { sendError, sendJson } from '../infra/httpd.js'
+
+/** 一份可直接给面板渲染的注解视图（读不到也永远有完整形状）。 */
+function annotationsView(read) {
+  const data = read.data
+  return {
+    ok: read.ok === true,
+    file: read.file,
+    exists: read.exists === true,
+    emptyFile: read.emptyFile === true,
+    version: data.version ?? 1,
+    updatedAt: data.updatedAt ?? 0,
+    plugins: data.plugins,
+    groups: data.groups,
+    stats: annotationsSummary(data),
+    // 读的时候做过规范化（用户手工改过文件）：如实把"我改了哪些"说出来，不静默
+    repaired: Array.isArray(read.repaired) ? read.repaired : [],
+    error: read.error ?? null,
+  }
+}
+
+async function routeAnnotationsGet(req, res, rc) {
+  void rc
+  const read = readAnnotations()
+  // 只读接口永远 200：坏文件也要让面板拿得到"空结构 + 原因"，否则面板只能显示一句泛泛的失败
+  sendJson(res, 200, annotationsView(read))
+}
+
+async function routeAnnotationsPost(req, res, rc) {
+  const body = rc.body ?? {}
+  const action = typeof body.action === 'string' ? body.action : ''
+  if (action === '') {
+    sendError(res, 400, '缺少 action（可用：note / badges / group-create / group-rename / group-delete / group-restore / group-assign / group-collapse）')
+    return
+  }
+  // input 原样透传：所有校验都在 domain（**一处判据**），路由不重复判断、也不放宽
+  const result = await applyAnnotation({ ...body, action })
+  const after = readAnnotations()
+  const view = annotationsView({ ...after, data: result.data ?? after.data })
+  const payload = {
+    ok: result.ok === true,
+    action,
+    changed: result.changed === true,
+    error: result.error ?? null,
+    backup: result.backup ?? null,
+    file: result.file ?? annotationsPath(),
+    key: result.meta?.key ?? null,
+    group: result.meta?.group ?? null,
+    deleted: result.meta?.deleted ?? null,
+    index: result.meta?.index ?? null,
+    movedFrom: result.meta?.movedFrom ?? null,
+    removedFrom: result.meta?.removedFrom ?? null,
+    plugins: view.plugins,
+    groups: view.groups,
+    stats: view.stats,
+  }
+  if (result.ok === true) {
+    sendJson(res, 200, payload)
+    return
+  }
+  const status = Number.isFinite(result.status) ? result.status : 400
+  sendJson(res, status, { ...payload, ok: false })
+}
+
+export { routeAnnotationsGet, routeAnnotationsPost, annotationsView }

package/lib/server/routes/framework.js

@@ -235,136 +235,153 @@ async function routeCompatGate(req, res, rc) {
     return
 }
 
-async function routeCheckUpdate(req, res, rc) {
+/**
+ * 单个已装插件的更新检测 —— **唯一实现**（issue #22 ①：一键批量检测必须与单卡检测同结论）。
+ * 批量入口若另写一份"问 registry / 回落 GitHub release / 净化陈旧候选"，就是第二套检测逻辑 ——
+ * 本仓已为"两套判据分叉"付过代价（0.5.37 反向更新）。所以只留一份：`/check-update`（单卡）与
+ * `/check-updates`（批量）都调本函数；判据仍是 `infra/semver.js` 的 `<<<update-pick>>>` 块。
+ * 本函数**不是路由**：不写 res、不校验入参（调用方各自校验），只回结论。
+ * options.fetchJson = 出网注入缝（默认 infra/http.js 的 fetchJsonUrl ⇒ 生产行为零变化；批量离线测试靠它）。
+ */
+async function probePackageUpdate(packageName, rc, options = {}) {
   const currentFrameworkVersion = rc.deps.currentFrameworkVersion
   const ctx = rc.ctx
-  const url = rc.url
-  const pathname = rc.pathname
-  const method = rc.method
-  const body = rc.body
-    // 检测已安装插件是否有新版本：curl registry 元数据取 dist-tags.latest（node 网络黑洞时 curl 可用）。
-    // 聚合包（有 dependencies）额外对比子包版本：声明版本 vs 本地 node_modules 实际版本，
-    // 返回 depsOutdated 提示"更新本包需同步子包"，避免半更新混搭导致启动冲突。
-    const packageName = packageNameOf(typeof body.packageName === 'string' ? body.packageName.trim() : '')
-    if (!packageName) {
-      sendError(res, 400, 'packageName 不能为空')
-      return
+  const fetchJson = typeof options.fetchJson === 'function' ? options.fetchJson : fetchJsonUrl
+  // ★ 2026-10-25 改错（抽函数时发现）：profileDir 必须在**函数作用域**里。
+  //   旧代码只在 registry 那个 `try {}` 块内声明 `const profileDir = dirname(patchPath)`，
+  //   而下面的 migrate（换名检测）块在 try **之外**引用它 ⇒ 每次调用必抛
+  //   `ReferenceError: profileDir is not defined`，被那个块自己的 `catch {}` 吞掉
+  //   ⇒ `migrate` 恒为 null（面板上"项目已改名/迁移发布 → 去装新包"这条提示从未生效过）。
+  //   tests/test-update-batch.mjs ⑤ 用正控钉住：声明了 dsh.migrate.to 的包必须真的回 migrate。
+  const profileDir = dirname(findPatchPath(ctx))
+  let latest = null
+  let next = null
+  let beta = null
+  let depsOutdated = []
+  let error = null
+  let source = 'npm'
+  // 检测已安装插件是否有新版本：curl registry 元数据取 dist-tags.latest（node 网络黑洞时 curl 可用）。
+  // 聚合包（有 dependencies）额外对比子包版本：声明版本 vs 本地 node_modules 实际版本，
+  // 返回 depsOutdated 提示"更新本包需同步子包"，避免半更新混搭导致启动冲突。
+  try {
+    const encoded = packageName.startsWith('@')
+      ? `@${encodeURIComponent(packageName.slice(1).split('/')[0])}%2f${encodeURIComponent(packageName.split('/').slice(1).join('/'))}`
+      : encodeURIComponent(packageName)
+    const data = await fetchJson(`https://registry.npmmirror.com/${encoded}`)
+    latest = data?.['dist-tags']?.latest ?? null
+    next = data?.['dist-tags']?.next ?? null
+    beta = data?.['dist-tags']?.beta ?? null
+    if (latest === null) throw new Error(`registry 无 dist-tags.latest（${packageName}）`)
+    // 子包配套检查：最新版声明依赖 vs 本地实际版本
+    const declared = latest ? data?.versions?.[latest]?.dependencies ?? {} : {}
+    const keys = typeof declared === 'object' ? Object.keys(declared) : []
+    for (const dep of keys) {
+      const required = String(declared[dep] ?? '').replace(/^[\^~>=< ]+/u, '')
+      if (!required) continue
+      let current = null
+      try {
+        const pkgPath = join(profileDir, 'node_modules', dep, 'package.json')
+        if (existsSync(pkgPath)) {
+          const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+          current = typeof pkg.version === 'string' ? pkg.version : null
+        }
+      } catch {}
+      if (current !== null && current !== required) {
+        depsOutdated.push({ name: dep, current, required })
+      }
     }
-    let latest = null
-    let next = null
-    let beta = null
-    let depsOutdated = []
-    let error = null
-    let source = 'npm'
+  } catch (err) {
+    // GitHub 发布回退（自身/未发布到 npm 的插件）：npm registry 404/无 latest 时，
+    // 从已装包 package.json 的 repository 字段反查 GitHub 最新版本。
+    // 通道顺序：GitHub API（带 token）→ jsDelivr 版本 API（GitHub 黑洞期可用，已验证 200）。
+    // 覆盖 dsh-plugin-console（本面板）这类"源码在 GitHub、npm 上不存在"的宿主插件。
+    let fallbackError = err instanceof Error ? err.message : String(err)
     try {
-      const encoded = packageName.startsWith('@')
-        ? `@${encodeURIComponent(packageName.slice(1).split('/')[0])}%2f${encodeURIComponent(packageName.split('/').slice(1).join('/'))}`
-        : encodeURIComponent(packageName)
-      const data = await fetchJsonUrl(`https://registry.npmmirror.com/${encoded}`)
-      latest = data?.['dist-tags']?.latest ?? null
-      next = data?.['dist-tags']?.next ?? null
-      beta = data?.['dist-tags']?.beta ?? null
-      if (latest === null) throw new Error(`registry 无 dist-tags.latest（${packageName}）`)
-      // 子包配套检查：最新版声明依赖 vs 本地实际版本
-      const patchPath = findPatchPath(ctx)
-      const profileDir = dirname(patchPath)
-      const declared = latest ? data?.versions?.[latest]?.dependencies ?? {} : {}
-      const keys = typeof declared === 'object' ? Object.keys(declared) : []
-      for (const dep of keys) {
-        const required = String(declared[dep] ?? '').replace(/^[\^~>=< ]+/u, '')
-        if (!required) continue
-        let current = null
+      const meta = entryPkgMeta(packageName, ctx.baseUrl ?? 'file:///', profileDirOf(ctx))
+      const repo = typeof meta?.repository === 'string'
+        ? meta.repository.replace(/^git\+/u, '').replace(/\.git$/u, '')
+        : (meta?.repository && typeof meta.repository === 'object' ? meta.repository.url : null)
+      const m = typeof repo === 'string' ? repo.match(/github\.com[/:]([^/]+\/[^/]+?)(?:\.git)?$/u) : null
+      if (m) {
+        let tag = null
+        // 通道 1：GitHub API（匿名可读，限流 60/h；token 时 5000/h）
         try {
-          const pkgPath = join(profileDir, 'node_modules', dep, 'package.json')
-          if (existsSync(pkgPath)) {
-            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
-            current = typeof pkg.version === 'string' ? pkg.version : null
-          }
+          const auth = readGithubAuth()
+          const headers = { 'User-Agent': 'dsh-plugin-console' }
+          if (auth.token) headers.Authorization = `token ${auth.token}`
+          const release = await fetchJson(`https://api.github.com/repos/${m[1]}/releases/latest`, 12000, headers)
+          if (typeof release?.tag_name === 'string') tag = release.tag_name
         } catch {}
-        if (current !== null && current !== required) {
-          depsOutdated.push({ name: dep, current, required })
-        }
-      }
-    } catch (err) {
-      // GitHub 发布回退（自身/未发布到 npm 的插件）：npm registry 404/无 latest 时，
-      // 从已装包 package.json 的 repository 字段反查 GitHub 最新版本。
-      // 通道顺序：GitHub API（带 token）→ jsDelivr 版本 API（GitHub 黑洞期可用，已验证 200）。
-      // 覆盖 dsh-plugin-console（本面板）这类"源码在 GitHub、npm 上不存在"的宿主插件。
-      let fallbackError = err instanceof Error ? err.message : String(err)
-      try {
-        const meta = entryPkgMeta(packageName, ctx.baseUrl ?? 'file:///', profileDirOf(ctx))
-        const repo = typeof meta?.repository === 'string'
-          ? meta.repository.replace(/^git\+/u, '').replace(/\.git$/u, '')
-          : (meta?.repository && typeof meta.repository === 'object' ? meta.repository.url : null)
-        const m = typeof repo === 'string' ? repo.match(/github\.com[/:]([^/]+\/[^/]+?)(?:\.git)?$/u) : null
-        if (m) {
-          let tag = null
-          // 通道 1：GitHub API（匿名可读，限流 60/h；token 时 5000/h）
+        // 通道 2：jsDelivr 版本列表（GitHub 直连黑洞时可用；取最高版本号）
+        if (tag === null) {
           try {
-            const auth = readGithubAuth()
-            const headers = { 'User-Agent': 'dsh-plugin-console' }
-            if (auth.token) headers.Authorization = `token ${auth.token}`
-            const release = await fetchJsonUrl(`https://api.github.com/repos/${m[1]}/releases/latest`, 12000, headers)
-            if (typeof release?.tag_name === 'string') tag = release.tag_name
+            const data = await fetchJson(`https://data.jsdelivr.com/v1/packages/gh/${m[1]}`, 12000)
+            const versions = Array.isArray(data?.versions) ? data.versions.map((v) => String(v.version ?? '')) : []
+            // 按语义版本号排序取最高（v 前缀剥离后比较）
+            const parsed = versions
+              .map((v) => ({ raw: v, ver: v.replace(/^v/iu, '') }))
+              .filter((x) => /^\d+\.\d+\.\d+/u.test(x.ver))
+              .sort((a, b) => {
+                const pa = a.ver.split(/[.-]/u).map((n) => (Number.isFinite(Number(n)) ? Number(n) : n))
+                const pb = b.ver.split(/[.-]/u).map((n) => (Number.isFinite(Number(n)) ? Number(n) : n))
+                for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+                  const x = pa[i] ?? -1; const y = pb[i] ?? -1
+                  if (x !== y) return typeof x === 'number' && typeof y === 'number' ? x - y : String(x) < String(y) ? -1 : 1
+                }
+                return 0
+              })
+            if (parsed.length > 0) tag = parsed[parsed.length - 1].raw
           } catch {}
-          // 通道 2：jsDelivr 版本列表（GitHub 直连黑洞时可用；取最高版本号）
-          if (tag === null) {
-            try {
-              const data = await fetchJsonUrl(`https://data.jsdelivr.com/v1/packages/gh/${m[1]}`, 12000)
-              const versions = Array.isArray(data?.versions) ? data.versions.map((v) => String(v.version ?? '')) : []
-              // 按语义版本号排序取最高（v 前缀剥离后比较）
-              const parsed = versions
-                .map((v) => ({ raw: v, ver: v.replace(/^v/iu, '') }))
-                .filter((x) => /^\d+\.\d+\.\d+/u.test(x.ver))
-                .sort((a, b) => {
-                  const pa = a.ver.split(/[.-]/u).map((n) => (Number.isFinite(Number(n)) ? Number(n) : n))
-                  const pb = b.ver.split(/[.-]/u).map((n) => (Number.isFinite(Number(n)) ? Number(n) : n))
-                  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-                    const x = pa[i] ?? -1; const y = pb[i] ?? -1
-                    if (x !== y) return typeof x === 'number' && typeof y === 'number' ? x - y : String(x) < String(y) ? -1 : 1
-                  }
-                  return 0
-                })
-              if (parsed.length > 0) tag = parsed[parsed.length - 1].raw
-            } catch {}
-          }
-          if (tag !== null) {
-            latest = tag.replace(/^v/iu, '')
-            next = null
-            source = 'github'
-            error = null
-            fallbackError = null
-          }
         }
-        if (fallbackError !== null && latest === null) error = `npm 与 GitHub 均未检测到版本（${fallbackError}）`
-      } catch (fbErr) {
-        error = `npm registry 查询失败且 GitHub 回退不可用（${fallbackError}；${fbErr instanceof Error ? fbErr.message : String(fbErr)}）`
+        if (tag !== null) {
+          latest = tag.replace(/^v/iu, '')
+          next = null
+          source = 'github'
+          error = null
+          fallbackError = null
+        }
       }
+      if (fallbackError !== null && latest === null) error = `npm 与 GitHub 均未检测到版本（${fallbackError}）`
+    } catch (fbErr) {
+      error = `npm registry 查询失败且 GitHub 回退不可用（${fallbackError}；${fbErr instanceof Error ? fbErr.message : String(fbErr)}）`
     }
-    // migrate 换名检测（2026-09-04 缺陷修复）：本地包声明 dsh.migrate.to 时查目标包最新版/引擎声明，
-    // 识别「项目已改名/迁移发布」的更新（如 @linxin666/dsh-web-ui-all → @linxin666/dsh-web-all 0.3.14）
-    let migrate = null
-    try {
-      const localPath = resolvePackageJson(packageName, profileDir)
-      if (localPath !== null) {
-      const localPkg = JSON.parse(readFileSync(localPath, 'utf8'))
-      const to = typeof localPkg.dsh?.migrate?.to === 'string' ? localPkg.dsh.migrate.to : null
-      if (to !== null && to !== '' && to !== packageName) {
-        const encTo = to.startsWith('@')
-          ? `@${encodeURIComponent(to.slice(1).split('/')[0])}%2f${encodeURIComponent(to.split('/').slice(1).join('/'))}`
-          : encodeURIComponent(to)
-        const meta = await fetchJsonUrl(`https://registry.npmmirror.com/${encTo}`)
-        const toLatest = meta?.['dist-tags']?.latest ?? meta?.['dist-tags']?.next ?? null
-        const toPkg = toLatest !== null ? (meta?.versions?.[toLatest] ?? null) : null
-        const engine = toPkg?.dsh?.engines?.dsh ?? toPkg?.engines?.dsh ?? null
-        const fwVer = currentFrameworkVersion(ctx)
-        const compatible = fwVer !== null && (engine === null || semverRangeMatchLoose(fwVer, engine))
-        migrate = { to, latest: toLatest, engine, compatible }
-      }
-      }
-    } catch {}
-    // 兜底（0.5.37）：低于已装版本的候选不是"新版"（真机：镜像 latest=0.1.1-rc.1 < 已装 0.2.0-rc.2）
-    ;({ latest, next, beta } = dropStaleUpdateCandidates({ latest, next, beta }, packageName, ctx.baseUrl ?? 'file:///', profileDirOf(ctx)))
+  }
+  // migrate 换名检测（2026-09-04 缺陷修复）：本地包声明 dsh.migrate.to 时查目标包最新版/引擎声明，
+  // 识别「项目已改名/迁移发布」的更新（如 @linxin666/dsh-web-ui-all → @linxin666/dsh-web-all 0.3.14）
+  let migrate = null
+  try {
+    const localPath = resolvePackageJson(packageName, profileDir)
+    if (localPath !== null) {
+    const localPkg = JSON.parse(readFileSync(localPath, 'utf8'))
+    const to = typeof localPkg.dsh?.migrate?.to === 'string' ? localPkg.dsh.migrate.to : null
+    if (to !== null && to !== '' && to !== packageName) {
+      const encTo = to.startsWith('@')
+        ? `@${encodeURIComponent(to.slice(1).split('/')[0])}%2f${encodeURIComponent(to.split('/').slice(1).join('/'))}`
+        : encodeURIComponent(to)
+      const meta = await fetchJson(`https://registry.npmmirror.com/${encTo}`)
+      const toLatest = meta?.['dist-tags']?.latest ?? meta?.['dist-tags']?.next ?? null
+      const toPkg = toLatest !== null ? (meta?.versions?.[toLatest] ?? null) : null
+      const engine = toPkg?.dsh?.engines?.dsh ?? toPkg?.engines?.dsh ?? null
+      const fwVer = currentFrameworkVersion(ctx)
+      const compatible = fwVer !== null && (engine === null || semverRangeMatchLoose(fwVer, engine))
+      migrate = { to, latest: toLatest, engine, compatible }
+    }
+    }
+  } catch {}
+  // 兜底（0.5.37）：低于已装版本的候选不是"新版"（真机：镜像 latest=0.1.1-rc.1 < 已装 0.2.0-rc.2）
+  ;({ latest, next, beta } = dropStaleUpdateCandidates({ latest, next, beta }, packageName, ctx.baseUrl ?? 'file:///', profileDirOf(ctx)))
+  return { latest, next, beta, depsOutdated, error, source, migrate }
+}
+
+async function routeCheckUpdate(req, res, rc) {
+  const body = rc.body
+    const packageName = packageNameOf(typeof body.packageName === 'string' ? body.packageName.trim() : '')
+    if (!packageName) {
+      sendError(res, 400, 'packageName 不能为空')
+      return
+    }
+    // 检测走**唯一实现** probePackageUpdate（与 /check-updates 批量入口同一份，见其函数注释）
+    const { latest, next, beta, depsOutdated, error, source, migrate } = await probePackageUpdate(packageName, rc, { fetchJson: rc.deps.fetchJson })
     sendJson(res, 200, { ok: true, packageName, latest, next, beta, target: pickUpdateTarget({ latest, next, beta }), depsOutdated, error, source, migrate })
     return
 }
@@ -573,4 +590,4 @@ async function routeFrameworkStatusClear(req, res, rc) {
   }
   sendJson(res, 200, { ok: true, removed, failed, status: 'idle', message: null })
 }
-export { refuseWhenShellHosted, refuseWhenPlatformUnsupported, routeFrameworkStatusClear, routeFrameworkUpgradeStatusGet, routeFrameworkRelaunch, routeFrameworkCheck, routeCompatGate, routeCheckUpdate, routeFrameworkRollback, routeRestart }
+export { refuseWhenShellHosted, refuseWhenPlatformUnsupported, routeFrameworkStatusClear, routeFrameworkUpgradeStatusGet, routeFrameworkRelaunch, routeFrameworkCheck, routeCompatGate, routeCheckUpdate, routeFrameworkRollback, routeRestart, probePackageUpdate }

package/lib/server/routes/index.js

@@ -18,6 +18,8 @@ import { routeRunSuggested } from './actions.js'
 import { routeComponentAutostart, routeComponentStart, routeComponentStatus, routeComponentStop, routeComponents, routeRepoClone, routeRepoLandConfig, routeRepoList, routeRepoOpen, routeRepoRemove } from './components.js'
 import { routeCompatAck, routeCompatMode, routeCompatStamp, routeCompatStatusGet, routeDeclareInstalled } from './compat.js'
 import { routeSafeBoot } from './safe-boot.js'
+// issue #22 ②③ 加法：用户备注 / 用户徽章 / 用户自建分组（独立文件，与插件列表完全解耦）
+import { routeAnnotationsGet, routeAnnotationsPost } from './annotations.js'
 import { routePatchAuditGet } from './patch-audit.js'
 import { routePresetAuditGet } from './preset-audit.js'
 // 0.5.84 加法（用户第 7 项）：<DSH_HOME>/plugin-console 的磁盘体检（只读）与**确认后**清理
@@ -25,6 +27,8 @@ import { routeDiskAudit, routeDiskCleanup } from './disk.js'
 import { routeFrameworkUpgrade } from './framework-upgrade.js'
 import { routeFrameworkPreflight, routeFrameworkPreflightPatch } from './framework-preflight.js'
 import { routeCheckUpdate, routeCompatGate, routeFrameworkCheck, routeFrameworkRelaunch, routeFrameworkRollback, routeFrameworkStatusClear, routeFrameworkUpgradeStatusGet, routeRestart } from './framework.js'
+// issue #22 ① 加法：已安装插件「一键检测全部更新」（判据复用 routeCheckUpdate 那条唯一实现）
+import { routeCheckUpdates } from './update-batch.js'
 import { routeGithubLogin, routeGithubOpenLogin } from './github-login.js'
 import { routeInstall, routeInstallStatus } from './install.js'
 import { routeLockfileCheck, routeLockfileRepair } from './lockfile.js'
@@ -66,6 +70,8 @@ const ROUTES_EARLY = [
   // 0.5.84 加法（用户第 7 项）：磁盘体检**只读** ⇒ 必须住在 405 守卫之前的表里（声明 GET 就要走得到）。
   { methods: ['GET'], path: `${ROUTE_PREFIX}/disk-audit`, handler: routeDiskAudit },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/framework-relaunch`, handler: routeFrameworkRelaunch },
+  // issue #22 ②③ 加法：注解**只读**（用户备注/徽章/分组）。纯只读 ⇒ 必须住在 405 守卫之前。
+  { methods: ['GET'], path: `${ROUTE_PREFIX}/annotations`, handler: routeAnnotationsGet },
 
 ]
 
@@ -122,6 +128,9 @@ const ROUTES = [
   { methods: ['POST'], path: `${ROUTE_PREFIX}/install-status`, handler: routeInstallStatus },  { methods: ['POST'], path: `${ROUTE_PREFIX}/framework-check`, handler: routeFrameworkCheck },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/compat-gate`, handler: routeCompatGate },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/check-update`, handler: routeCheckUpdate },
+  // issue #22 ① 加法：批量检测（已安装列表的「一键检测全部更新」）。
+  // ★ 与 /check-update 共用同一个探针（probePackageUpdate），判据不分叉；并发上限在 domain/update-batch.js。
+  { methods: ['POST'], path: `${ROUTE_PREFIX}/check-updates`, handler: routeCheckUpdates },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/framework-upgrade`, handler: routeFrameworkUpgrade },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/framework-preflight`, handler: routeFrameworkPreflight },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/framework-preflight-patch`, handler: routeFrameworkPreflightPatch },
@@ -140,6 +149,9 @@ const ROUTES = [
   // 安全启动材料恢复入口（2026-09-29 加法 D3-①，0.5.32）：白名单动作 list / restore-last-good /
   // disable-suspects / mark-good；只认动作名，绝不接受命令串；服务起不来时走 scripts/safe-boot.mjs
   { methods: ['POST'], path: `${ROUTE_PREFIX}/safe-boot`, handler: routeSafeBoot },
+  // issue #22 ②③ 加法：注解**写**动作（action = note / badges / group-*）。
+  // 写盘纪律全在 domain/plugin-annotations.js（备份 → 原子写 → 读回核实 → 回滚），路由只映射状态码。
+  { methods: ['POST'], path: `${ROUTE_PREFIX}/annotations`, handler: routeAnnotationsPost },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/framework-rollback`, handler: routeFrameworkRollback },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/restart`, handler: routeRestart },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/toggle`, handler: routeToggle },