dsh-plugin 1.6.12 → 2.0.0

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

@@ -0,0 +1,42 @@
+/**
+ * DSH Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * npm 包发布时间查询路由：按已安装插件的 npm 包名按需查询最新版本的发布时间，
+ * 供客户端判定 pnpm 24h 供应链门禁（发布未满门槛的版本不提示更新）。
+ */
+import { systemProxy } from '../services/probe.ts'
+import { lookupReleaseAge, parseReleaseAgeRequest } from '../services/npm-release-age.ts'
+import { loadSettings } from '../services/settings.ts'
+import { readJsonBody, requireTrustedPost, sendJson, type WebRoute, type WebServerService } from './shared.ts'
+
+export function registerNpmReleaseAgeRoutes(webServer: WebServerService, profile: string): WebRoute[] {
+  return [
+    {
+      kind: 'exact',
+      path: '/dsh-plugin-hub/npm-release-age',
+      handler: async (request, response) => {
+        if (!requireTrustedPost(request, response)) return
+        try {
+          const packages = parseReleaseAgeRequest(await readJsonBody(request))
+          if (packages === null) {
+            sendJson(response, 400, { error: 'invalid package list' })
+            return
+          }
+          const settings = loadSettings(profile)
+          // 代理口径与安装/目录一致：设置里的代理 → 系统代理 → 环境变量 → 直连
+          const proxy = settings.proxy !== ''
+            ? settings.proxy
+            : (systemProxy() ?? process.env.HTTPS_PROXY ?? process.env.https_proxy ?? '')
+          // 并发查询：单包各自带超时且失败即 null，整体不因任一包失败而失败
+          const results = await Promise.all(packages.map(async (name) =>
+            [name, await lookupReleaseAge(name, settings.npmRegistry, proxy)] as const))
+          sendJson(response, 200, { packages: Object.fromEntries(results) })
+        } catch (error) {
+          sendJson(response, 500, { error: error instanceof Error ? error.message : String(error) })
+        }
+      },
+    },
+  ]
+}

package/src/server/http/routes.ts

@@ -3,10 +3,9 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Local HTTP routes exposing real installs to the in-app Plugin Hub UI.
- * The client fetches the same-origin `/dsh-plugin-hub/*` endpoints; the
- * install handler validates the target, then spawns the official dsh CLI
- * (see services/install/install.ts) and reports the captured result back.
+ * 本地 HTTP 路由：把真实安装能力暴露给应用内的插件中心 UI。客户端请求同源
+ * `/dsh-plugin-hub/*` 端点；安装处理校验目标后 spawn 官方 dsh CLI（见
+ * services/install/install.ts）并回传捕获的结果。
  */
 import { type LoaderHandle } from '../services/install/install.ts'
 import { appendLog } from '../services/log.ts'
@@ -17,13 +16,13 @@ import { registerSettingsRoutes } from './settings.ts'
 import { registerLogsRoutes } from './logs.ts'
 import { registerDiagnosticsRoutes } from './diagnostics.ts'
 import { registerTaskRoutes } from './task.ts'
+import { registerNpmReleaseAgeRoutes } from './npm-release-age.ts'
 
 /**
- * Register the Plugin Hub API on the host web server and return a disposer.
- * @param webServer - DSH web server service.
- * @param profile - profile that owns plugin mutations.
- * @param loader - running loader (optional): lets uninstall remove the entry
- *   immediately so the page survives a refresh without a host restart.
+ * 在宿主 web server 上注册插件中心 API 并返回 dispose 函数。
+ * @param webServer - DSH web server 服务。
+ * @param profile - 拥有插件变更权限的 profile。
+ * @param loader - 运行中 loader（可选）：让卸载立即移除条目，页面刷新即生效、无需重启宿主。
  */
 export function mountPluginHubRoutes(webServer: WebServerService, profile: string, loader?: LoaderHandle): () => void {
   if (!PROFILE_RE.test(profile)) throw new Error(`invalid profile name: ${profile}`)
@@ -43,6 +42,7 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
     ...registerLogsRoutes(webServer, profile),
     ...registerDiagnosticsRoutes(webServer, profile),
     ...registerTaskRoutes(webServer, profile, loader),
+    ...registerNpmReleaseAgeRoutes(webServer, profile),
   ]
   const disposers = routes.map((route) => webServer.register(route))
   return () => {
@@ -50,9 +50,9 @@ export function mountPluginHubRoutes(webServer: WebServerService, profile: strin
   }
 }
 
-/** Profile resolution shared with the client route docs. */
+/** 与客户端路由文档共用的 profile 解析。 */
 export { readProfileArg } from '../services/install/install.ts'
-/** Re-exported so the host entry (index.ts) keeps importing it from this module. */
+/** 转出以便宿主入口（index.ts）继续从本模块引入。 */
 export type { WebServerService } from './shared.ts'
-/** Re-exported so tests/routes.test.ts keeps importing these from this module. */
+/** 转出以便 tests/routes.test.ts 继续从本模块引入。 */
 export { isDesktopHost, isSameOrigin } from './shared.ts'

package/src/server/http/settings.ts

@@ -3,7 +3,7 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Settings routes: read/write the hub settings and reset them to defaults.
+ * 设置路由：读写插件中心设置，以及恢复默认。
  */
 import { mkdirSync } from 'node:fs'
 import { dirname } from 'node:path'
@@ -28,7 +28,7 @@ export function registerSettingsRoutes(webServer: WebServerService, profile: str
           // 白名单字段：只接受已知设置项，防客户端把任意键写进文件
           const patch: Record<string, unknown> = {}
           const source = typeof body === 'object' && body !== null ? body as Record<string, unknown> : {}
-          for (const key of ['checkUpdatesOnStart', 'enableNpmInstall', 'enableGitInstall', 'enableDshInstall', 'npmRegistry', 'proxy', 'logPath'] as const) {
+          for (const key of ['checkUpdatesOnStart', 'enableNpmInstall', 'npmRegistry', 'proxy', 'logPath'] as const) {
             if (source[key] !== undefined) patch[key] = source[key]
           }
           // 日志位置：非空时预建目录验证可写，失败直接 400 拦截（默认位置永远合法，空串 = 回默认）

package/src/server/http/shared.ts

@@ -3,9 +3,8 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Shared HTTP utilities: route/service types, request validation helpers and
- * the same-origin check guarding every POST mutation. Imported by the other
- * route modules in this directory.
+ * 共享 HTTP 工具：路由/服务类型、请求校验助手，以及守卫每个 POST 变更的同源校验。
+ * 由本目录其它路由模块引入。
  */
 import type { IncomingMessage, ServerResponse } from 'node:http'
 
@@ -97,7 +96,7 @@ export interface WebRoute {
   handler: (request: IncomingMessage, response: ServerResponse) => void | Promise<void>
 }
 
-/** The subset of the host web-server service this plugin touches. */
+/** 本插件用到的宿主 web-server 服务子集。 */
 export interface WebServerService {
   register(route: WebRoute): () => void
 }
@@ -135,8 +134,8 @@ function loopbackAuthority(authority: string): string | null {
   }
 }
 
-/** POST mutations are only accepted from the local web server origin or the desktop host page.
- *  Exported for tests (tests/routes.test.ts) — the origin check is the whole CSRF defence. */
+/** POST 变更只接受来自本地 web server 来源或桌面宿主页面。转出供测试（tests/routes.test.ts）使用 ——
+ *  来源校验就是全部的 CSRF 防御。 */
 export function isSameOrigin(request: IncomingMessage): boolean {
   // 服务只绑定本机回环地址：Host 不是回环（局域网 IP、被改写的域名）一律拒绝，
   // 顺带挡掉 DNS rebinding（Host 是攻击者域名，即便解析到 127.0.0.1）。

package/src/server/http/task.ts

@@ -3,8 +3,7 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Task/misc routes: task polling, host restart, loader-entry debugging, and
- * the installed-plugin inventory the client uses to reconcile its list.
+ * 任务/杂项路由：任务轮询、宿主重启、loader 条目调试，以及客户端用于对账列表的已装插件清单。
  */
 import { spawn } from 'node:child_process'
 import { join } from 'node:path'

package/src/server/index.ts

@@ -3,9 +3,8 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * dsh-plugin host entry: mounts the Plugin Hub HTTP routes once the host
- * web server service is available. The browser bundle (src/client) talks to
- * these same-origin routes to perform real installs from inside the app.
+ * dsh-plugin 宿主入口：宿主 webServer 服务就绪后挂载插件中心的 HTTP 路由。
+ * 浏览器 bundle（src/client）通过这些同源路由在应用内执行真正的安装。
  */
 import { readProfileArg, type LoaderHandle } from './services/install/install.ts'
 import { mountPluginHubRoutes, type WebServerService } from './http/routes.ts'
@@ -13,11 +12,11 @@ import { mountPluginHubRoutes, type WebServerService } from './http/routes.ts'
 export const name = 'dsh-plugin'
 
 export interface Config {
-  /** DSH profile that owns plugin mutations. Defaults to the booted profile. */
+  /** 拥有插件变更权限的 DSH profile，缺省用启动时的 profile。 */
   profile?: string
 }
 
-/** The subset of the cordis host context this plugin touches. */
+/** 本插件用到的 cordis 宿主上下文子集。 */
 interface HostContext {
   webServer: WebServerService
   /** 运行中 loader：卸载成功后主动移除条目、立即生效（宿主未提供时卸载仍需重启） */
@@ -27,9 +26,9 @@ interface HostContext {
 }
 
 /**
- * Mount the Plugin Hub routes after the web server service becomes available.
- * @param ctx - cordis host context.
- * @param config - optional profile override.
+ * webServer 服务就绪后挂载插件中心路由。
+ * @param ctx - cordis 宿主上下文。
+ * @param config - 可选的 profile 覆盖。
  */
 export function apply(ctx: HostContext, config: Config = {}): void {
   const profile = config.profile ?? readProfileArg('web')

package/src/server/services/install/install-types.ts

@@ -17,27 +17,26 @@ export interface InstallResult {
 
 export interface InstallTask {
   id: number
-  /** 操作目标：显式 HTTPS Git URL（安装）或 npm 包名（卸载），冲突/恢复时需要展示给用户 */
+  /** 操作目标：npm 包名（安装、更新、卸载一致），冲突/恢复时需要展示给用户 */
   target: string
   /** 展示用目标（owner/repo）：npm 安装时 target 是包名，前端恢复用此字段显示仓库名，保持用户无感知 */
   displayTarget?: string
-  /** 尝试过的安装方式（npm registry 反查 + 实际执行的 CLI 命令，按先后顺序）：
-   *  失败提 Issue 时如实贴给作者，作者据此反推正确的 npm 包名（组织 scope 与 GitHub 用户名不一致时
-   *  仅凭仓库名猜不到，作者看到我们查过/试过的命令就能直接指认）。 */
+  /** 尝试过的安装方式（实际执行过的 CLI 命令，按先后顺序）：
+   *  失败提 Issue 时如实贴给作者，作者据此判断我们真正执行了什么。 */
   attempts: string[]
   /** 全局 npm 安装（官方 `npm install -g <pkgs>`）：非空时任务执行全局 npm 安装，不进任何 profile */
   globalNpm?: string[]
   action: 'add' | 'remove' | 'update'
-  /** 自定义安装入口渠道（客户端三张卡片：NPM 包 / GitHub 源码 / DSH 命令）：
+  /** 自定义安装入口渠道（NPM 包卡片）：
    *  任务输出行与系统日志据此溯源「从哪个入口发起」；目录插件安装无此字段。 */
-  installChannel?: 'npm' | 'git' | 'dsh'
+  installChannel?: 'npm'
   /** 队列语义：pending 排队中 / running 执行中 / done / failed / cancelled（用户取消） */
   status: 'pending' | 'running' | 'done' | 'failed' | 'cancelled'
   timedOut: boolean
   exitCode: number | null
   /** 0-100 估算进度：解析 pnpm 的 `Progress: resolved…` 输出，阶段行兜底 */
   progress: number
-  /** Newest output lines first (consumer shows the tail). */
+  /** 输出行最新在前（消费方展示尾部）。 */
   lines: string[]
   /** 完成后是否仍需宿主重启才生效：仅「热挂载失败 / 非 dsh 插件 / 更新（ESM 缓存取不到新代码）/
    *  无 loader」等刷新解决不了的兜底场景为 true（弹窗给「立即重启」）；其余一律 false。 */
@@ -70,7 +69,7 @@ export interface QueueItem {
     timeoutMs?: number
     env?: NodeJS.ProcessEnv
     globalNpm?: string[]
-    installChannel?: 'npm' | 'git' | 'dsh'
+    installChannel?: 'npm'
   }
 }
 
@@ -79,7 +78,7 @@ export interface QueueItem {
  * 它自然清空，正好等于「重启后提醒消失」的语义，无需任何重启探测。
  */
 export interface PendingRestart {
-  /** Git 安装目标（与任务一致；卸载时为展示用的 owner/repo） */
+  /** 安装目标（与任务一致；卸载时为展示用的 owner/repo） */
   target: string
   /** 待重启语义：install 装完等挂载生效 / uninstall 卸完等清理 loader 残留 */
   kind: 'install' | 'uninstall'
@@ -87,13 +86,13 @@ export interface PendingRestart {
   at: number
 }
 
-/** Grammar of a catalog GitHub repository identity (`owner/repo`). */
+/** 目录 GitHub 仓库身份（`owner/repo`）的语法。 */
 export const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/
-/** Grammar of an npm package name (used for uninstall targets). */
+/** npm 包名的语法（用于卸载目标）。 */
 export const PACKAGE_RE = /^(?:@[a-z0-9._-]+\/)?[A-Za-z0-9._-]+$/
 /** 捕获输出上限：stdout/stderr 各保留尾部 N 字节。 */
 export const CAPTURE_LIMIT_BYTES = 64 * 1024
-/** Max output lines kept per task (newest wins). */
+/** 每个任务保留的最大输出行数（最新优先）。 */
 export const MAX_TASK_LINES = 200
-/** Max tracked tasks; oldest finished tasks are dropped first. */
+/** 最多跟踪的任务数；超出时先丢弃最早结束的任务。 */
 export const MAX_TASKS = 50

package/src/server/services/install/install.ts

@@ -20,7 +20,6 @@ export { addPendingRestart, clearPendingRestart, listPendingRestarts } from '../
 export { dumpLoaderEntries, removeLoadedEntry } from '../loader.ts'
 export {
   addAllowBuildsKey,
-  githubRefOf,
   githubRepoOf,
   githubTarget,
   globalNpmPackagesOf,

package/src/server/services/install/npm-check.ts

@@ -5,8 +5,9 @@
  *
  * 本机 npm 环境检测：判断一次安装失败是否源于「本机 npm 版本过低」。
  *
- * 背景：pnpm 在 git 源插件的 prepare 阶段会调 npm 装依赖，npm arborist 在解 peer 依赖时有
- * 已知内部崩溃 —— `Cannot read properties of null (reading 'edgesOut')`。这是 npm 自身缺陷，
+ * 背景：pnpm 在带 `prepare` 构建脚本的依赖上会调 npm 装依赖（npm 包同样可能带原生
+ * 依赖或 git 依赖），npm arborist 在解 peer 依赖时有已知内部崩溃 ——
+ * `Cannot read properties of null (reading 'edgesOut')`。这是 npm 自身缺陷，
  * 该报错会被 pnpm 包进 ERR_PNPM_PREPARE_PACKAGE 输出，不能按插件打包问题引导用户提 Issue。
  *
  * 这里的 `npmTooLowMarker` 是纯函数（输出文本 + 环境 → 标记行或 null），不触碰任务/队列，

package/src/server/services/install/npm-resolve.ts

@@ -3,50 +3,18 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * npm 包反查：git 分发不完整（缺构建产物/子模块）导致安装失败时，用 npm
- * registry 的搜索接口按 repository 地址反查该仓库对应的官方 npm 包。
+ * npm 包校验：确认某个 npm 包确实属于该 GitHub 仓库、且声明为 DSH 插件
+ * （包元数据里的 repository 指向该仓库，并带 `dsh-plugin` 关键词或 `dsh` manifest）。
  *
  * 这是通用机制，不针对任何具体插件：只要作者发布了 repository 指向该
- * GitHub 仓库的 npm 包（scope 名与 GitHub 用户名是否一致无所谓），就能命中，
- * 从而把 git 分发不完整的插件切换到 npm 通道安装。命中结果带内存缓存，
- * 避免同一会话内重复查询 registry。
+ * GitHub 仓库的 npm 包（scope 名与 GitHub 用户名是否一致无所谓），就能命中。
  */
 import { get } from 'node:https'
 import { githubRepoOf } from '../profile/profile.ts'
 import { finalUrl } from '../probe.ts'
 
-/** 反查缓存：repo 小写 → npm 包名（null 表示已确认无对应 npm 包；网络异常不缓存）。 */
-const cache = new Map<string, string | null>()
-
-/** 单次 registry 查询超时（ms）：慢网络下失败返回 null，不阻塞安装流程。 */
+/** 单次 registry 查询超时（ms）：慢网络下失败返回 false，不阻塞安装流程。 */
 const REQUEST_TIMEOUT_MS = 8000
-/** npm search 是相关性搜索而非 repository 精确索引；拉满单页结果后再本地做严格 repo 过滤。 */
-const SEARCH_RESULT_LIMIT = 250
-
-/**
- * 反查 repo（`owner/repo`）对应的官方 npm 包名；未命中、网络异常或超时返回 null。
- * 返回 null 不代表仓库一定没有 npm 包，只代表本次未能确认 —— 调用方应保留
- * 原有错误路径，反查只是额外的一次尝试。只有「已确认」的结果（包名，或 200
- * 响应下确认无匹配）会进缓存；网络异常/超时/解析失败不缓存，同一会话内下次
- * 安装仍会重试反查，避免一次瞬时故障把整个会话锁死在 git 通道。
- * registry 参数：npm 镜像源地址，空串 = 官方源；与安装通道吃同一 registry，
- * 保证「配置了镜像」时反查和安装走同一个源（镜像节点同步完整时结果一致）。
- * proxy 参数：GitHub 改名跳转探测走的代理（与安装/诊断同一口径）。
- * 慢网络下失败不阻塞安装。
- */
-export async function resolveNpmPackage(repo: string, registry = '', proxy = ''): Promise<string | null> {
-  const key = repo.toLowerCase()
-  if (cache.has(key)) return cache.get(key) ?? null
-  let found = await searchRepo(repo, registry)
-  // 仓库改名后 npm 包的 repository 已指向新名，按旧名反查不到：跟随一次 GitHub 的
-  // 改名跳转拿到规范名再查一遍（旧地址本身仍可用，只是仓库名变了）。
-  if (found === null) {
-    const canonical = await canonicalRepo(repo, proxy)
-    if (canonical !== '' && canonical.toLowerCase() !== key) found = await searchRepo(canonical, registry)
-  }
-  if (found !== undefined) cache.set(key, found)
-  return found ?? null
-}
 
 type NpmSearchPackage = {
   name?: unknown
@@ -56,16 +24,7 @@ type NpmSearchPackage = {
   dsh?: unknown
 }
 
-type NpmSearchObject = { package?: NpmSearchPackage }
-type NpmSearchResponse = { objects?: NpmSearchObject[] }
-
-/**
- * Pick the installable npm package for one GitHub repository. npm search is a
- * relevance-ranked text search, not an exact repository index, so first filter
- * by repository URL. If a monorepo publishes both a CLI/helper package and a
- * DSH plugin, prefer the package that explicitly advertises the `dsh-plugin`
- * keyword instead of whichever result npm happened to rank first.
- */
+/** 从包元数据取 repository 地址：字符串或 `{ url }` 对象，缺省回退 search 结果的 links.repository。 */
 function repositoryUrlOf(pkg: NpmSearchPackage): string {
   if (typeof pkg.repository === 'string') return pkg.repository
   if (pkg.repository !== null && typeof pkg.repository === 'object') {
@@ -83,6 +42,10 @@ export function isDshPackageMetadataForRepo(pkg: NpmSearchPackage, repo: string)
   return keywordMarked || manifestMarked
 }
 
+/**
+ * 校验包名对应的 npm 包确实属于该仓库且声明为 DSH 插件：取 registry 上的 `latest`
+ * 元数据比对 repository 与插件标记。网络异常、超时、非 200 一律返回 false，不阻塞调用方。
+ */
 export function isDshNpmPackageForRepo(packageName: string, repo: string, registry = '', proxy = ''): Promise<boolean> {
   if (packageName === '' || repo === '') return Promise.resolve(false)
   const base = registry === '' ? 'https://registry.npmjs.org' : registry.replace(/\/+$/, '')
@@ -130,56 +93,3 @@ async function canonicalRepo(repo: string, proxy: string): Promise<string> {
   const canonical = final === null ? null : githubRepoOf(final)
   return canonical !== null && canonical.toLowerCase() !== key ? canonical : ''
 }
-
-function matchingPackagesForRepo(objects: NpmSearchObject[], repo: string): Array<{ name: string; isDshPlugin: boolean }> {
-  const matches: Array<{ name: string; isDshPlugin: boolean }> = []
-
-  for (const obj of objects) {
-    const pkg = obj.package
-    if (typeof pkg?.name !== 'string' || pkg.name === '') continue
-    const repoUrl = repositoryUrlOf(pkg)
-    if (githubRepoOf(repoUrl)?.toLowerCase() !== repo.toLowerCase()) continue
-    const keywords = Array.isArray(pkg.keywords) ? pkg.keywords : []
-    matches.push({
-      name: pkg.name,
-      isDshPlugin: keywords.some((keyword) => typeof keyword === 'string' && keyword.toLowerCase() === 'dsh-plugin'),
-    })
-  }
-
-  return matches
-}
-
-export function selectNpmPackageForRepo(objects: NpmSearchObject[], repo: string): string | null {
-  const matches = matchingPackagesForRepo(objects, repo)
-  return matches.find((candidate) => candidate.isDshPlugin)?.name ?? matches[0]?.name ?? null
-}
-
-/** 用 npm search 接口按 repository 地址反查，并做铁证校验（包元数据必须指向该仓库）。
- * 返回：包名 = 命中；null = 200 响应下确认无匹配；undefined = 本次未能确认（网络/超时/解析失败）。 */
-function searchRepo(repo: string, registry: string): Promise<string | null | undefined> {
-  const [owner, name] = repo.split('/')
-  if (owner === undefined || name === undefined || name === '') return Promise.resolve(null)
-  const base = registry === '' ? 'https://registry.npmjs.org' : registry.replace(/\/+$/, '')
-  const url = `${base}/-/v1/search?text=${encodeURIComponent(`repository:${owner}/${name}`)}&size=${SEARCH_RESULT_LIMIT}`
-  return new Promise((resolve) => {
-    const req = get(url, { timeout: REQUEST_TIMEOUT_MS }, (res) => {
-      if (res.statusCode !== 200) {
-        res.resume()
-        resolve(undefined)
-        return
-      }
-      let body = ''
-      res.on('data', (chunk: Buffer) => { body += chunk.toString() })
-      res.on('end', () => {
-        try {
-          const data = JSON.parse(body) as NpmSearchResponse
-          resolve(selectNpmPackageForRepo(data.objects ?? [], `${owner}/${name}`))
-        } catch {
-          resolve(undefined)
-        }
-      })
-    })
-    req.on('timeout', () => req.destroy())
-    req.on('error', () => resolve(undefined))
-  })
-}

package/src/server/services/install/package-entry.ts

@@ -4,17 +4,12 @@
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
  * 分发文件解析：从 package.json 推出装完后必须真实存在的文件 —— 作者声明的入口
- * （exports["."] / main）与 bundle 声明的补丁（dsh.bundle.patch）。git 通道（tar 预检）
- * 与 npm 通道（装后 statSync 校验）共用，保证两条通道对同一个包判定一致。
+ * （exports["."] / main）与 bundle 声明的补丁（dsh.bundle.patch），供装后校验使用。
  *
- * 这里不替作者补一个 index.js：宿主加载一个 bundle 读的是它的 package.json 和它声明的
- * 补丁文件（官方 bundleManifest 的注释即「Read bundle metadata without loading its
- * JavaScript」），从不 import 包本身。凭空要求一个作者没声明的入口，只会把完整的
- * 技能包判成分发残缺，并把一条假缺陷推到作者仓库（见 QingYunA/answer-me-with-html#209）。
- *
- * 例外是补丁自己 mount 了本包：dsh 的《打包与安装插件》里组合包的常规写法就是
- * `- insert: - name: <本包名>`，宿主随后按包名 import 本包，入口那时必须存在。
- * 所以只有补丁真的写了自己的包名，才把这个入口算进分发要求。
+ * 只在包自己声明了入口时才要求它存在：宿主加载 bundle 读的是它的 package.json 与声明的补丁，
+ * 从不 import 包本身。硬要一个作者没声明过的 index.js，会把完整的包判成分发残缺、把一条假缺陷
+ * 推到作者仓库。例外是补丁自己 mount 了本包（组合包的常规写法）—— 那时宿主按包名 import 本包，
+ * 入口必须存在，所以只有补丁真的写了自己的包名才把这个入口算进分发要求。
  */
 
 /** exports 条件对象里按优先级尝试的键；Node 语义下 default 最宽，import/require 次之。 */
@@ -53,7 +48,7 @@ export function resolvePackageEntry(meta: PackageManifest): string | null {
 /**
  * 解析 `dsh.bundle.patch` 声明的补丁文件（相对包根，不带 `./` 前缀）。
  * 形状不合规范（既不是字符串也不是字符串数组）在这里不判定：那是 dsh 启动时
- * bundlePatchFiles 的报错职责，预检只负责「声明了就要在包里存在」。
+ * bundlePatchFiles 的报错职责，装后校验只负责「声明了就要在包里存在」。
  */
 export function resolveBundlePatchFiles(meta: PackageManifest): string[] {
   const patch = (meta.dsh as { bundle?: { patch?: unknown } } | undefined)?.bundle?.patch

package/src/server/services/install/registry-check.ts

@@ -69,8 +69,8 @@ export async function registryMissingMarker(
 ): Promise<string | null> {
   const name = missingPackageOf(output)
   if (name === null) return null
-  // ① profile 自己声明的残留依赖（#73）：用户环境问题，交给既有的 pnpmMissingDep 提示（该提示就是
-  // 教用户删 profile 里那条依赖），这里不再产出标记、不改归属
+  // 该包是 profile 自己声明的依赖（用户环境里留下的条目）→ 用户环境问题，交给既有的 pnpmMissingDep
+  // 提示处理（那条提示就是教用户删掉它），不产出标记、不改归属
   if (profileDependencyNames(opts.profileDir).some((dep) => dep.toLowerCase() === name.toLowerCase())) return null
   const exists = await existsOnOfficialRegistry(name, opts.fetchImpl ?? fetch, opts.timeoutMs ?? 8000)
   if (exists === false) {

package/src/server/services/install/release-target.ts

@@ -3,14 +3,13 @@
  * Website: https://dsh-plugin.org
  * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * 预构建 GitHub release 安装目标（目录权威命令 → 可安装直链）。
- * 部分插件（如 loopx）把构建产物发布成 GitHub release 的 .tgz，仓库 HEAD 反而是
- * monorepo 根、走 git 直装会因缺入口文件失败；目录下发的权威安装命令直接指向该
- * release 包。这里把「目录命令」解析成安全的 release 目标，供客户端选路与服务端
- * 校验共用（单一事实来源，避免两端口径漂移）。
+ * 预构建 release 直链的仓库身份解析。部分插件（如 loopx）当初以 GitHub release 的 .tgz
+ * 安装过，仓库 HEAD 反而是 monorepo 根、走 git 直装会因缺入口文件失败；老安装记录里留的
+ * 就是这种 release 直链。这里把「历史安装目标」还原成所属仓库身份，供已装态读回、队列
+ * 去重与展示复用（单一事实来源，避免两端口径漂移）。
  *
  * 只接受固定形态的 HTTPS `github.com/<owner>/<repo>/releases/download/<tag>/<asset>.tgz`：
- * 目录命令是展示数据、绝非 shell 代码，绝不执行命令文本；跨仓跳转、外部主机、凭据、
+ * 输入是记录/展示数据、绝非 shell 代码，绝不执行其文本；跨仓跳转、外部主机、凭据、
  * 移动的 latest 链接、query/fragment、多余 CLI 参数与 shell 片段一律拒绝。
  */
 
@@ -22,15 +21,15 @@ export interface GithubReleaseTarget {
   repo: string
 }
 
-/** 目录权威命令：`dsh plugin --profile <p> add|update <target>`（与 profile.ts installTargetOf 同口径）。 */
+/** 完整命令前缀：`dsh plugin --profile <p> add|update <target>`（与 profile.ts installTargetOf 同口径）。 */
 const DSH_PLUGIN_CMD_RE = /^dsh[ \t]+plugin[ \t]+--profile(?:[ \t]+|=)[A-Za-z0-9_-]+[ \t]+(?:add|update)[ \t]+(.+)$/i
 
 /** 固定形态的 release .tgz 直链：主机、路径段与扩展名全部锁死。 */
 const RELEASE_URL_RE = /^https:\/\/github\.com\/([A-Za-z0-9._-]+)\/([A-Za-z0-9._-]+)\/releases\/download\/([A-Za-z0-9._+-]+)\/([A-Za-z0-9._+-]+\.tgz)$/
 
 /**
- * 解析一个 release 安装目标。
- * @param value - 目录命令（`dsh plugin --profile web add <url>`）或裸直链。
+ * 解析一个历史安装目标里的 release 直链。
+ * @param value - 完整命令（`dsh plugin --profile web add <url>`）或裸直链。
  * @returns 命中返回 `{ target, repo }`，否则 null。
  */
 export function githubReleaseTarget(value: string): GithubReleaseTarget | null {