dsh-plugin 1.6.11 → 2.0.0

package/src/server/services/install/task-queue.ts

@@ -15,7 +15,7 @@ import type { InstallResult, InstallTask, Invocation, QueueItem } from './instal
 import { CAPTURE_LIMIT_BYTES, MAX_TASKS, MAX_TASK_LINES } from './install-types.ts'
 import { npmTooLowMarker } from './npm-check.ts'
 import { registryMissingMarker } from './registry-check.ts'
-import { backfillOperationLog } from './operation-log.ts'
+import { backfillOperationLog, operationLogPathOf } from './operation-log.ts'
 import { cleanLine, estimateProgress } from '../profile/progress.ts'
 import type { LoaderHandle } from '../loader.ts'
 import { hasClientUi, isDshPlugin, mountLoadedEntry, removeLoadedEntry } from '../loader.ts'
@@ -23,15 +23,15 @@ import { addPendingRestart, clearPendingRestart } from '../profile/pending-resta
 import { addAllowBuildsKey, githubRepoOf, parseAllowBuildsKey, profileDirectory } from '../profile/profile.ts'
 import { appendLog } from '../log.ts'
 
-/** In-memory task registry, keyed by task id. */
+/** 内存任务注册表，按任务 id 索引。 */
 const tasks = new Map<number, InstallTask>()
 let nextTaskId = 1
-/** Pending tasks awaiting their turn (FIFO). The queue worker runs at most one mutation at a time. */
+/** 等待轮到的排队任务（FIFO）。队列 worker 同一时刻最多跑一个变更。 */
 const queue: QueueItem[] = []
-/** Child processes of currently running tasks (for cancel). */
+/** 当前运行任务的子进程（用于取消）。 */
 const runningChildren = new Map<number, ReturnType<typeof spawn>>()
 
-/** Snapshot of a task (keeps the live object untouched by consumers). */
+/** 任务快照（避免消费方改动实时对象）。 */
 export function getTask(id: number): InstallTask | undefined {
   const task = tasks.get(id)
   if (!task) return undefined
@@ -45,17 +45,17 @@ export interface ActiveTaskInfo {
   status: 'pending' | 'running'
   progress: number
   lines: string[]
-  /** 尝试过的安装方式（npm 反查 + 实际执行命令）：失败时前端 issue 预填需要 */
+  /** 尝试过的安装方式（实际执行过的命令）：失败时前端 issue 预填需要 */
   attempts: string[]
-  /** 自定义安装入口渠道（NPM 包 / GitHub 源码 / DSH 命令卡片）：前端刷新恢复后仍能精准溯源 */
-  installChannel?: 'npm' | 'git' | 'dsh'
+  /** 自定义安装入口渠道（NPM 包卡片）：前端刷新恢复后仍能精准溯源 */
+  installChannel?: 'npm'
 }
 
-/** All non-terminal tasks in queue order (running first, then pending). Lets the client resume a queue after a page reload. */
+/** 全部未终态任务，按队列顺序（running 在前、pending 在后）。供客户端刷新页面后恢复队列。 */
 export function activeTask(): ActiveTaskInfo[] {
   const found: ActiveTaskInfo[] = []
-  // 展示目标用 displayTarget（owner/repo）：安装 target 可能被服务端切成 npm 包名
-  // （npm 反查命中），队列恢复/待重启展示对用户保持仓库名无感知
+  // 展示目标用 displayTarget（owner/repo）：安装 target 是 npm 包名，
+  // 队列恢复/待重启展示对用户保持仓库名无感知
   const show = (task: InstallTask): string => task.displayTarget ?? task.target
   for (const item of queue) {
     const task = item.task
@@ -90,26 +90,24 @@ export function activeTask(): ActiveTaskInfo[] {
 }
 
 /**
- * True while a mutation child process is still alive. The concurrent slot is
- * keyed off the live child set rather than task.status: cancelling a running
- * task flips its status immediately, but the child may still be shutting down
- * (the close event lands later) — the slot must stay held until then, otherwise
- * a new task would start while the old pnpm still runs in the same profile dir.
+ * 变更子进程仍存活时为 true。并发占位以存活子进程集合为准，而非 task.status：
+ * 取消运行中任务会立即翻转其状态，但子进程可能仍在退出中（close 事件稍后才到）——
+ * 占位必须维持到那时，否则旧 pnpm 还在同一 profile 目录跑，新任务就开始了。
  */
 export function hasRunningTask(): boolean {
   return runningChildren.size > 0
 }
 
-/** Whether the target already has a non-terminal task in the queue (install/uninstall dedupe). */
+/** 目标在队列里是否已有未终态任务（安装/卸载去重）。 */
 export function hasQueuedTarget(target: string): boolean {
   return queue.some((it) => it.task.target === target && (it.task.status === 'pending' || it.task.status === 'running'))
 }
 
 /**
- * Cancel a queued or running task.
- * - pending: removed from the queue immediately (never spawned).
- * - running: kills the child process; the queue worker then picks the next one.
- * Returns false when the task is unknown or already finished.
+ * 取消排队中或运行中的任务。
+ * - pending：立即移出队列（从未 spawn）。
+ * - running：杀掉子进程；队列 worker 随后取下一个。
+ * 任务不存在或已结束时返回 false。
  */
 export function cancelTask(id: number): boolean {
   const task = tasks.get(id)
@@ -149,6 +147,13 @@ function pushLine(task: InstallTask, line: string): void {
   }
 }
 
+/** spawn 的 cwd：profile 目录（asar 路径不能作 cwd）；目录不存在时回退进程工作目录，
+ *  否则 Node 报的是 `spawn <file> ENOENT`，与「可执行文件不存在」无法区分。 */
+function spawnCwdFor(profile: string): string {
+  const dir = profileDirectory(profile)
+  return existsSync(dir) ? dir : process.cwd()
+}
+
 function cliInvocation(profile: string): Invocation {
   const entry = process.argv[1]
   if (entry !== undefined) {
@@ -162,8 +167,8 @@ function cliInvocation(profile: string): Invocation {
       return {
         file: process.execPath,
         prefixArgs: ['--expose-internals', bootstrap],
-        // 工作目录用 profile 目录（真实存在的目录）：asar 内的路径不能作为 spawn 的 cwd
-        cwd: profileDirectory(profile),
+        // cwd 用 profile 目录（asar 路径不能作 cwd），不存在时由 spawnCwdFor 回退
+        cwd: spawnCwdFor(profile),
         useShell: false,
         // Electron 可执行文件只有带这个变量才按 Node 运行引导脚本
         env: { ELECTRON_RUN_AS_NODE: '1' },
@@ -253,17 +258,14 @@ function mutationVerb(action: 'add' | 'remove' | 'update'): string {
 
 /** 系统日志入口渠道后缀：自定义安装（带渠道）在日志里体现「从哪张卡片发起」，
  *  目录插件安装（无渠道）返回空串。日志中文语境，渠道名用中文口语。 */
-function channelLabel(channel: 'npm' | 'git' | 'dsh' | undefined): string {
-  if (channel === 'git') return '（GitHub 源码入口）'
-  if (channel === 'dsh') return '（DSH 命令入口）'
+function channelLabel(channel: 'npm' | undefined): string {
   if (channel === 'npm') return '（NPM 包入口）'
   return ''
 }
 
 /**
- * Enqueue a plugin mutation and return its task. Tasks run strictly serially:
- * the queue worker starts the next one only after the previous finishes.
- * Progress is visible through `getTask(id)` / `activeTask()` until done.
+ * 插件变更入队并返回其任务。任务严格串行：队列 worker 只在上一个结束后才启动下一个。
+ * 完成前可通过 `getTask(id)` / `activeTask()` 查看进度。
  */
 export function startPluginMutation(options: {
   action: 'add' | 'remove' | 'update'
@@ -278,13 +280,13 @@ export function startPluginMutation(options: {
   /** 运行中 loader：安装成功后热挂新条目、卸载成功后停用旧条目，两类操作都尽量立即生效
    *  （缺失时安装/卸载仍需重启） */
   loader?: LoaderHandle
-  /** 入队前已尝试的安装方式（npm registry 反查等）：失败提 Issue 时如实展示；实际执行的命令由 spawn 时追加 */
+  /** 入队前已尝试的安装方式：失败提 Issue 时如实展示；实际执行的命令由 spawn 时追加 */
   attempts?: string[]
   /** 更新已安装的 npm 包（mode=update）：命令显式带 @latest，让 pnpm 真正解析最新版本 */
   updateNpm?: boolean
-  /** 自定义安装入口渠道（客户端三张卡片：NPM 包 / GitHub 源码 / DSH 命令）：
-   *  任务输出行与系统日志据此溯源「从哪个入口发起」；目录插件安装不传 */
-  installChannel?: 'npm' | 'git' | 'dsh'
+  /** 自定义安装入口渠道（NPM 包卡片）：任务输出行与系统日志据此溯源「从哪个入口发起」；
+   *  目录插件安装不传 */
+  installChannel?: 'npm'
 }): InstallTask {
   // 卸载入队时先快照「该包是否带客户端 UI」：卸载完成后包已从磁盘删除，读不到 package.json，
   // 只能在此刻取；卸载成功且曾存活时据此决定是否要刷新页面摘除插件面板
@@ -334,7 +336,7 @@ export function startPluginMutation(options: {
   return task
 }
 
-/** Queue worker: at most one mutation runs at a time; pick the next pending task when the slot frees up. */
+/** 队列 worker：同一时刻最多跑一个变更；占位空出时取下一个 pending 任务。 */
 function pumpQueue(): void {
   if (hasRunningTask()) return
   const item = queue.find((it) => it.task.status === 'pending')
@@ -392,9 +394,8 @@ function pumpQueue(): void {
 }
 
 /**
- * Run one `dsh plugin --profile <profile> <action> <target>` spawn, stream
- * its output onto the tracked task and resolve with the captured result.
- * Never rejects; failures surface through the result / task state.
+ * 执行一次 `dsh plugin --profile <profile> <action> <target>` spawn，把输出流式写到
+ * 跟踪的任务上，并以捕获结果 resolve。绝不 reject；失败通过结果/任务状态体现。
  */
 function spawnMutation(options: {
   action: 'add' | 'remove' | 'update'
@@ -431,8 +432,7 @@ function spawnMutation(options: {
   const args = isGlobalNpm
     ? ['install', '-g', ...(globalNpm ?? [])]
     : [...invocation.prefixArgs, 'plugin', '--profile', profile, cliAction, npmUpdateTarget]
-  // 记录实际执行的命令（npm 通道显示包名，git 通道显示 HTTPS 源），
-  // 失败提 Issue 时作为「已尝试的安装方式」随附
+  // 记录实际执行的命令（显示包名），失败提 Issue 时作为「已尝试的安装方式」随附
   const executed = isGlobalNpm
     ? `npm install -g ${(globalNpm ?? []).join(' ')}`
     : `dsh plugin --profile ${profile} ${cliAction} ${npmUpdateTarget}`
@@ -475,15 +475,19 @@ function spawnMutation(options: {
         stdio: ['ignore', 'pipe', 'pipe'],
       })
     } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error)
+      // 宿主自身入口起不来 → 补标记，前端据此归因
+      const marker = hostSpawnMarker(invocation, error)
       if (task) {
         task.status = 'failed'
         task.exitCode = null
-        pushLine(task, `[error] ${error instanceof Error ? error.message : String(error)}`)
+        pushLine(task, `[error] ${detail}`)
+        if (marker !== null) pushLine(task, marker)
       }
       resolveOnce({
         exitCode: null,
         timedOut: false,
-        error: error instanceof Error ? error.message : String(error),
+        error: marker === null ? detail : `${detail}\n${marker}`,
         stdout,
         stderr,
       })
@@ -554,12 +558,15 @@ function spawnMutation(options: {
     })
 
     child.once('error', (error) => {
+      // 同同步抛出那条路径：宿主自身入口起不来 → 补标记
+      const marker = hostSpawnMarker(invocation, error)
       if (task && task.status !== 'cancelled') {
         task.status = 'failed'
         task.exitCode = null
         pushLine(task, `[error] ${error.message}`)
+        if (marker !== null) pushLine(task, marker)
       }
-      settleOnce({ exitCode: null, timedOut: false, error: error.message, stdout, stderr })
+      settleOnce({ exitCode: null, timedOut: false, error: marker === null ? error.message : `${error.message}\n${marker}`, stdout, stderr })
     })
 
     child.once('close', (code) => {
@@ -641,7 +648,7 @@ function spawnMutation(options: {
 
 /**
  * 安装后校验已装包里 package.json 声明的文件（main / exports["."].default 与
- * dsh.bundle.patch）是否真实存在。git: 分发常不提交构建产物（lib/ 等），pnpm 装完没有
+ * dsh.bundle.patch）是否真实存在。npm 包也可能漏发构建产物（lib/ 等），pnpm 装完没有
  * 报错，但宿主重启加载插件树时会 ERR_MODULE_NOT_FOUND 直接崩溃、网页打不开 —— 这里在
  * 登记「待重启」前就把这类残缺包拦下。没有声明过的文件不在这里追究：没声明入口的
  * bundle 包（只挂技能）本来就不需要入口，宿主读的是它的 package.json 与声明的补丁。
@@ -712,10 +719,8 @@ function annotateNpmTooLow(result: InstallResult, options: {
   return { ...result, stderr: `${result.stderr}\n${line}`, error: result.error ? `${result.error}\n${line}` : line }
 }
 
-/** 包在 registry 不存在（404）→ 用官方源复查一次，把「作者依赖缺失/包被删」与「本机镜像源滞后」
- *  分开（两者的提示与去向不同：前者引导投作者、后者只提示换源）。检测逻辑在独立的
- *  registry-check.ts；这里之所以是异步，是因为要联网查官方 registry —— 只在安装失败且日志含 404
- *  时发生，代价可忽略。 */
+/** 安装失败且日志含 404 时，用官方源复查一次并注入标记（逻辑见 registry-check.ts）。
+ *  异步是因为要联网；只在失败路径上发生。 */
 async function annotateRegistryMissing(result: InstallResult, options: {
   action: 'add' | 'remove' | 'update'
   profile: string
@@ -731,13 +736,22 @@ async function annotateRegistryMissing(result: InstallResult, options: {
 }
 
 /**
- * Run a plugin mutation with one recovery path: when `add` fails because
- * pnpm's allowBuilds gate blocks a build script — either the git-hosted
- * package's own `prepare` (`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`, key from
- * the printed key@url hint) or a dependency's native build
- * (`ERR_PNPM_IGNORED_BUILDS`, key = the listed name@version) — write the
- * exact keys into the profile's pnpm-workspace.yaml and retry once.
- * Other failures fall through to the single-spawn result.
+ * 宿主自身 CLI 调不起来时的 ASCII 标记行：spawn 我们解析出的宿主入口报 ENOENT 时返回
+ * `[host-spawn]`，供前端单独归因、不引导提 Issue。PATH 上的 dsh/npm 各有自己的标记，返回 null。
+ * 导出供单测覆盖判据。
+ */
+export function hostSpawnMarker(invocation: Invocation, error: unknown): string | null {
+  if ((error as NodeJS.ErrnoException | null)?.code !== 'ENOENT') return null
+  if (invocation.file === 'dsh' || invocation.file === 'npm') return null
+  return `[host-spawn] the DSH host could not be launched (${invocation.file}: ENOENT)`
+}
+
+/**
+ * 执行插件变更，带一条恢复路径：当 `add` 因 pnpm 的 allowBuilds 门禁拦下构建脚本而失败 ——
+ * 或是 git 源包自己的 `prepare`（`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`，key 取自打印的
+ * key@url 提示），或是某依赖的原生构建（`ERR_PNPM_IGNORED_BUILDS`，key = 列出的 name@version）——
+ * 就把确切的 key 写进 profile 的 pnpm-workspace.yaml 并重试一次。
+ * 其它失败一律落到单次 spawn 的结果。
  */
 export async function runPluginMutation(options: {
   action: 'add' | 'remove' | 'update'
@@ -764,8 +778,7 @@ export async function runPluginMutation(options: {
       const key = parseAllowBuildsKey(output)
       if (key !== null) {
         if (options.task) {
-          // First attempt already marked the task failed; reset it so the
-          // retry streams progress as a running task again.
+          // 首次尝试已把任务标为失败；重置它，让重试重新以 running 任务形式流式输出进度。
           options.task.status = 'running'
           options.task.exitCode = null
           pushLine(options.task, `[allow build] ${key}`)
@@ -792,14 +805,14 @@ export async function runPluginMutation(options: {
       }
     }
   }
-  // pnpm 安装本身成功，但目标包声明分发的文件缺失（git 分发缺构建产物 / 缺声明的补丁）→ 判为失败：
+  // pnpm 安装本身成功，但目标包声明分发的文件缺失（分发物缺构建产物 / 缺声明的补丁）→ 判为失败：
   // 撤销刚登记的待重启，避免用户重启时宿主加载残缺包直接崩溃。
   // 全局 npm 安装不进 profile（profile deps 里没有这些包），跳过入口校验
   if (options.action !== 'remove' && result.exitCode === 0 && !result.timedOut && (options.globalNpm ?? []).length === 0) {
     const verified = verifyInstalledEntry(options.profile, options.target)
     if (verified.name !== null && verified.missing !== null) {
       clearPendingRestart(options.displayTarget ?? options.target)
-      const detail = `[packaging] ${verified.name}: declared file missing: ${verified.missing} (git distribution lacks build output — install the npm version or report to the author)`
+      const detail = `[packaging] ${verified.name}: declared file missing: ${verified.missing} (the published package is missing this file — report it to the author)`
       if (options.task && options.task.status !== 'cancelled') {
         options.task.status = 'failed'
         options.task.exitCode = null
@@ -809,18 +822,21 @@ export async function runPluginMutation(options: {
       return { exitCode: 1, timedOut: false, error: `declared file missing: ${verified.missing}`, stdout: result.stdout, stderr: `${result.stderr}\n${detail}` }
     }
   }
-  // DSH 只把一行摘要（`dsh: plugin command failed; diagnostics: <path>`）回显到控制台时，
-  // 控制台里没有任何错误特征，前端只能把失败归为「未知」（issue #192）。这里按该路径回捞
-  // operation 日志尾部补进失败信息：用户直接看到真实报错，自动归类也有据可依。
-  // 只在本就不含任何错误码时回捞 —— pnpm 已把报错回显出来时无需多读一次文件。
+  // 宿主只把一行摘要（`dsh: plugin command failed; diagnostics: <path>`）回显到控制台、真正的报错
+  // 写进该日志文件时，前端拿不到任何错误特征、只能归为「未知」。按该路径回捞日志尾部补进失败信息。
+  // 只在输出本就不含错误码时回捞 —— pnpm 已回显报错时无需多读一次文件。
   if (result.exitCode !== 0 && !result.timedOut && !/\bERR_[A-Z0-9_]+\b/.test(`${result.stderr}\n${result.stdout}`)) {
-    const backfilled = backfillOperationLog(`${result.stderr}\n${result.stdout}`)
+    const output = `${result.stderr}\n${result.stdout}`
+    const backfilled = backfillOperationLog(output)
     if (backfilled !== null) {
       if (options.task && options.task.status !== 'cancelled') {
         pushLine(options.task, '[pnpm log] DSH did not echo pnpm output — recovered the operation log from disk')
         for (const line of backfilled.split(/\r?\n/)) if (line.trim() !== '') pushLine(options.task, line.trimEnd())
       }
       result = { ...result, stderr: `${result.stderr}\n${backfilled}` }
+    } else if (options.task && options.task.status !== 'cancelled' && operationLogPathOf(output) !== null) {
+      // 诊断路径在、日志却取不到：留一行证据，否则下一次同类上报又只剩宿主那句摘要、看不出根因
+      pushLine(options.task, '[pnpm log] the host-reported diagnostics log could not be read from disk (missing, empty, or unreadable)')
     }
   }
   // 包在 registry 不存在（404）→ 官方源复查，区分「作者的依赖缺失/包被删」与「本机镜像源滞后」

package/src/server/services/npm-release-age.ts

@@ -0,0 +1,107 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * npm 包最新版本的发布时间查询：为「已安装插件是否有更新」提供供应链门禁依据。
+ * pnpm 对发布不满 24h（dsh profile minimumReleaseAge=1440）的版本会静默回退到旧版本，
+ * 因此发布未满门槛的版本不该提示更新（否则用户点了也装不上）。
+ * 结果按包名内存缓存，同一次会话内不重复请求；失败/超时/响应过大一律返回 null，绝不抛错、绝不阻塞。
+ */
+import { get as httpsGet } from 'node:https'
+import { validPackageName } from './profile/profile.ts'
+import { fetchViaCurl } from './probe.ts'
+
+export interface NpmRelease {
+  version: string
+  publishedAt: string
+}
+
+/** 请求体包名数量上限：只为已安装插件按需查询，几十个足矣，封顶防滥用。 */
+export const MAX_RELEASE_AGE_PACKAGES = 50
+/** 单包查询超时（ms）：慢网络下失败即返回 null，不拖住整个响应。 */
+export const RELEASE_AGE_TIMEOUT_MS = 8000
+/** 响应体上限：完整 packument 可能达数 MB，超限直接放弃，避免异常大包拖垮服务。 */
+const MAX_PACKUMENT_BYTES = 10 * 1024 * 1024
+export const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org'
+
+/** 会话内缓存（包名 → 版本与发布时间）：只存成功结果，一次网络抖动不会把判断永久粘住。 */
+const releaseCache = new Map<string, NpmRelease>()
+
+/** 从完整 packument 取 dist-tags.latest 对应版本及其发布时间；缺任一字段返回 null。 */
+export function latestReleaseOf(packument: unknown): NpmRelease | null {
+  if (packument === null || typeof packument !== 'object') return null
+  const doc = packument as { 'dist-tags'?: unknown; time?: unknown }
+  const tags = doc['dist-tags']
+  const version = tags !== null && typeof tags === 'object' ? (tags as { latest?: unknown }).latest : undefined
+  if (typeof version !== 'string' || version === '') return null
+  const time = doc.time
+  const publishedAt = time !== null && typeof time === 'object' ? (time as Record<string, unknown>)[version] : undefined
+  if (typeof publishedAt !== 'string' || publishedAt === '') return null
+  return { version, publishedAt }
+}
+
+/** 请求体 → 去重后的合法包名列表；非数组 / 超量 / 含非法包名一律 null（拒绝非法输入）。 */
+export function parseReleaseAgeRequest(body: unknown): string[] | null {
+  if (body === null || typeof body !== 'object') return null
+  const raw = (body as { packages?: unknown }).packages
+  if (!Array.isArray(raw) || raw.length > MAX_RELEASE_AGE_PACKAGES) return null
+  const names = new Set<string>()
+  for (const item of raw) {
+    if (typeof item !== 'string' || item === '' || item.startsWith('-') || !validPackageName(item)) return null
+    names.add(item)
+  }
+  return [...names]
+}
+
+/** node:https 直连 GET，仅接受 200；超时/超限/网络失败返回 null。 */
+function getJson(url: string, timeoutMs: number): Promise<string | null> {
+  return new Promise((resolve) => {
+    let done = false
+    const finish = (value: string | null) => { if (!done) { done = true; resolve(value) } }
+    const req = httpsGet(url, { timeout: timeoutMs, headers: { accept: 'application/json' } }, (res) => {
+      if (res.statusCode !== 200) { res.resume(); finish(null); return }
+      const declared = Number(res.headers['content-length'])
+      if (Number.isFinite(declared) && declared > MAX_PACKUMENT_BYTES) { res.destroy(); finish(null); return }
+      let body = ''
+      let bytes = 0
+      res.on('data', (chunk: Buffer) => {
+        bytes += chunk.length
+        if (bytes > MAX_PACKUMENT_BYTES) { res.destroy(); finish(null); return }
+        body += chunk.toString()
+      })
+      res.on('end', () => finish(body))
+      res.on('error', () => finish(null))
+    })
+    req.on('timeout', () => req.destroy())
+    req.on('error', () => finish(null))
+  })
+}
+
+/** 拉取一个包的完整 packument 正文；配了代理时复用与安装/目录同一套代理口径（curl 子进程注入 proxy env）。 */
+async function fetchPackument(url: string, proxy: string, timeoutMs: number): Promise<string | null> {
+  if (proxy !== '') {
+    const r = await fetchViaCurl(url, proxy, timeoutMs)
+    return r.ok && r.body !== '' && Buffer.byteLength(r.body) <= MAX_PACKUMENT_BYTES ? r.body : null
+  }
+  return getJson(url, timeoutMs)
+}
+
+/** 查询一个包的最新版本与发布时间（成功结果缓存，同会话内同包不重复请求）；registry 为空回退官方源，失败返回 null。 */
+export async function lookupReleaseAge(
+  packageName: string,
+  registry: string,
+  proxy: string,
+  timeoutMs = RELEASE_AGE_TIMEOUT_MS,
+): Promise<NpmRelease | null> {
+  const cached = releaseCache.get(packageName)
+  if (cached !== undefined) return cached
+  const base = registry.replace(/\/+$/, '') || DEFAULT_NPM_REGISTRY
+  const body = await fetchPackument(`${base}/${encodeURIComponent(packageName)}`, proxy, timeoutMs)
+  if (body === null) return null
+  let parsed: unknown
+  try { parsed = JSON.parse(body) } catch { return null }
+  const release = latestReleaseOf(parsed)
+  if (release !== null) releaseCache.set(packageName, release)
+  return release
+}

package/src/server/services/probe.ts

@@ -99,7 +99,7 @@ function macSystemProxy(): string | null {
  * `http=host:port;https=host:port`（按协议分别配置）。
  * 字符类必须同时排除 `/` 与 `=`：只排除 `=` 时，带 scheme 的值会让「主机名」吞掉 `//`，
  * 拼出 `http:////127.0.0.1:10793` 这种立刻失败的非法地址 —— 代理本来是通的，却把诊断、
- * 目录拉取、npm/git 预检全判成「不可达」。
+ * 目录拉取、安装前网络探测全判成「不可达」。
  */
 export function parseWinProxyServer(stdout: string): string | null {
   const m = /([^:\s=/]+):(\d+)/.exec(stdout)
@@ -220,13 +220,13 @@ export function probeUrl(url: string, proxy: string, timeoutMs: number): Promise
 }
 
 /**
- * git 通道真实克隆握手探测：spawn git ls-remote（https 传输，与 pnpm 克隆前的
+ * git 真实克隆握手探测：spawn git ls-remote（https 传输，与 pnpm 克隆前的
  * ref 握手一致），注入代理 env，GIT_TERMINAL_PROMPT=0 防凭据提示挂起。
  *
  * 为什么要真实 git 而非 curl 打网页：网页「能打开」和 git「能克隆」是两码事 ——
  * 防火墙/代理常按端口与协议区分，HTTP 页可达不代表 git 传输可达。这里测的就是
- * 克隆握手本身，回答「github:owner/repo 装不装得动」。
- * 供系统诊断 GitHub 通道使用；探测目标用 dshplugin/hello-dsh 小仓库（秒级完成，
+ * 克隆握手本身，回答「能不能连上 github.com」。
+ * 供系统诊断 GitHub 可达性使用；探测目标用 dshplugin/hello-dsh 小仓库（秒级完成，
  * 不打 17MB 的 dsh-plugin-hub 主页）。
  */
 export function gitLsRemote(url: string, proxy: string, timeoutMs: number): Promise<ProbeResult> {

package/src/server/services/profile/installed-versions.ts

@@ -3,23 +3,19 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Installed-plugin version tracking.
+ * 已安装插件版本追踪。
  *
- * The installed table (`readInstalled` in routes.ts) only knows the manifest
- * spec of each Git dependency, which carries no version.
- * To let the Plugin Hub tell "an update is available", we record the catalog
- * signal present at install time into a small per-profile JSON file, then
- * compare it against the catalog's current signal later.
+ * 已安装表（routes.ts 的 `readInstalled`）只知道每个 Git 依赖的 manifest spec，不含版本号。
+ * 为让插件中心能判断「有更新」，我们把安装时的目录信号记进一个 per-profile 的小 JSON 文件，
+ * 之后再与目录当前信号比对。
  *
- * Two signals cover every repo:
- *   - version:  the catalog's latest release tag (e.g. v1.2.3). Repos that
- *     publish releases are compared on this.
- *   - updatedAt: the repo's last push time (GitHub pushed_at, `repoUpdatedAt`).
- *     Repos that never publish a release fall back to this: a newer push time
- *     means new commits → an update is available.
+ * 两个信号覆盖所有仓库：
+ *   - version：目录最新 release tag（如 v1.2.3），发 release 的仓库按它比对。
+ *   - updatedAt：仓库最近 push 时间（GitHub pushed_at，即 `repoUpdatedAt`），
+ *     从不发 release 的仓库回退用它：push 时间变新即有新提交 → 有更新。
  *
- * Storage: `DSH_HOME/profiles/<profile>/gro.ngilp-hsd-versions.json`
- *   { "<owner>/<repo>" (lowercase): { version: string, updatedAt: string, installedAt: string } }
+ * 存储：`DSH_HOME/profiles/<profile>/gro.ngilp-hsd-versions.json`
+ *   { "<owner>/<repo>"（小写）: { version, updatedAt, installedAt } }
  */
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
 import { homedir } from 'node:os'
@@ -31,7 +27,7 @@ export interface InstalledVersionRecord {
   /** 安装时的仓库最近更新时间（ISO，GitHub pushed_at）；无 release 仓库的更新依据 */
   updatedAt: string
   installedAt: string
-  /** npm 优先通道反查命中的官方 npm 包名（repo → 包名映射）：目录数据可能未下发
+  /** 安装时记录在案的官方 npm 包名（repo → 包名映射）：目录数据可能未下发
    *  npmPackage（组织 scope 与 GitHub 用户名不一致），客户端据此把依赖 key 匹配回仓库 */
   npmPackage?: string
 }
@@ -51,21 +47,19 @@ export function readInstalledVersions(profile: string): InstalledVersionTable {
   }
 }
 
-/** Record the catalog signals (version + repo updated time) present at install time for one repo. */
+/** 记录某仓库安装时的目录信号（版本 + 仓库更新时间）。 */
 export function recordInstalledVersion(profile: string, repo: string, version: string, updatedAt: string): void {
   const table = readInstalledVersions(profile)
   const key = repo.toLowerCase()
-  // 合并写入：保留已记录的 npmPackage（npm 优先通道的 repo → 包名映射），
+  // 合并写入：保留已记录的 npmPackage（repo → 包名映射），
   // 客户端同步版本信号时不能把它覆盖掉
   table[key] = { ...table[key], version, updatedAt, installedAt: new Date().toISOString() }
   writeVersions(profile, table)
 }
 
 /**
- * Record the npm package name resolved for a repo (npm-first install channel).
- * Called at `/install` time so the mapping exists even before the task finishes;
- * harmless when the repo is not (yet) installed — the client only treats a repo
- * as installed when its dependency key actually exists.
+ * 记录某仓库解析出的 npm 包名。在 `/install` 时调用，让映射在任务完成前就存在；
+ * 仓库尚未安装时也无害 —— 客户端只在依赖 key 真实存在时才把仓库当作已安装。
  */
 export function recordResolvedNpmPackage(profile: string, repo: string, npmPackage: string): void {
   const table = readInstalledVersions(profile)
@@ -74,7 +68,7 @@ export function recordResolvedNpmPackage(profile: string, repo: string, npmPacka
   writeVersions(profile, table)
 }
 
-/** Forget the recorded version for one repo (called on uninstall). */
+/** 清除某仓库记录的版本（卸载时调用）。 */
 export function removeInstalledVersion(profile: string, repo: string): void {
   const table = readInstalledVersions(profile)
   delete table[repo.toLowerCase()]