dsh-plugin 1.1.1 → 1.2.0

package/src/client/{lib → logic}/failures.ts

@@ -1,21 +1,27 @@
 /**
- * Persistent install/remove notifications.
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
  *
- * Every settled task — success or failure — is appended to localStorage the
- * moment the backend reports it, so a result is never lost even when the
- * dialog was dismissed or nobody was watching the progress strip. Newest
- * first, capped at MAX entries. Failures keep their full output for the
- * issue-filing flow; successes are lightweight (no log).
+ * Failure classification, issue-body summarization and persistent
+ * install/remove notifications.
+ *
+ * Every settled task is recorded two ways: the server-side system log
+ * (hub.log) and a client-side localStorage record that feeds the
+ * notification center — so a result is never lost even when the dialog
+ * was dismissed or nobody was watching the progress strip.
  */
 export interface NotificationRecord {
   id: number
-  kind: 'install' | 'uninstall'
+  kind: 'install' | 'uninstall' | 'update'
   /** true = 成功（轻量记录）；false = 失败（message 携带完整错误日志） */
   ok: boolean
   /** owner/repo（可能为空：请求层失败但拿不到仓库时） */
   repo: string
   /** 失败时的完整错误日志；成功记录为空串 */
   message: string
+  /** 更新提醒：目录里的新版本号（展示用；其余通知省略） */
+  version?: string
   /** 实际执行的安装/卸载命令（issue 预填时如实展示）；历史记录可能缺失 */
   command?: string
   /** 尝试过的安装方式（npm registry 反查 + 实际执行命令，按先后顺序）：失败提 Issue 时贴给作者，便于反推正确的 npm 包名 */
@@ -27,12 +33,84 @@ export interface NotificationRecord {
 const KEY = 'gro.ngilp-hsd.failure-records'
 const MAX = 50
 
-export type FailureKind = 'pnpmIgnoredBuild' | 'pluginPrepare' | 'repo'
+/** 运行时 localStorage 访问：类型上不依赖 DOM lib（Node 测试环境也能编译），浏览器里取 window。 */
+const storage = (): Storage | undefined =>
+  (globalThis as { localStorage?: Storage }).localStorage
+
+/** 读取本地通知记录（损坏/不可用时返回空列表，不抛错）。列表最新在前，全部保留，只由「清空」按钮手动移除。 */
+export function loadNotifications(): NotificationRecord[] {
+  try {
+    const raw = storage()?.getItem(KEY)
+    if (!raw) return []
+    const list = JSON.parse(raw) as unknown
+    if (!Array.isArray(list)) return []
+    return list
+      .filter((r): r is NotificationRecord =>
+        !!r && typeof r === 'object' && typeof (r as { message?: unknown }).message === 'string')
+      // ok 字段缺省时按失败渲染
+      .map((r) => ({ ...r, ok: r.ok === true }))
+  } catch {
+    return []
+  }
+}
+
+function save(list: NotificationRecord[]): void {
+  try {
+    storage()?.setItem(KEY, JSON.stringify(list))
+  } catch {
+    /* storage full / unavailable：仅保留内存态，界面仍可查看 */
+  }
+}
+
+/** 追加一条通知记录并持久化，返回更新后的完整列表（最新在前，超上限裁剪）。
+ *  每次成功/失败都各自留痕：同一插件的安装/卸载记录都完整保留、只由「清空」按钮手动移除，
+ *  不会因后续操作被自动覆盖清除。 */
+export function addNotification(record: Omit<NotificationRecord, 'id' | 'at'>): NotificationRecord[] {
+  const prev = loadNotifications()
+  let id = Date.now()
+  while (prev.some((r) => r.id === id)) id += 1
+  const next = [{ ...record, id, at: id }, ...prev].slice(0, MAX)
+  save(next)
+  return next
+}
+
+/** 记录一次失败：携带完整错误日志，供通知中心查看/复制/提 Issue。 */
+export function addFailure(record: Omit<NotificationRecord, 'id' | 'at' | 'ok'>): NotificationRecord[] {
+  return addNotification({ ...record, ok: false })
+}
+
+/** 记录一次成功：轻量记录，不带日志。 */
+export function addSuccess(record: Omit<NotificationRecord, 'id' | 'at' | 'ok' | 'message'>): NotificationRecord[] {
+  return addNotification({ ...record, ok: true, message: '' })
+}
+
+/** 记录一条「发现新版本」更新提醒：成功类轻量记录，携带目录新版本号供通知中心展示。 */
+export function addUpdateNotice(record: Omit<NotificationRecord, 'id' | 'at' | 'ok' | 'message'>): NotificationRecord[] {
+  return addNotification({ ...record, ok: true, message: '' })
+}
+
+/** 清空全部通知记录，返回空列表。 */
+export function clearNotifications(): NotificationRecord[] {
+  save([])
+  return []
+}
+
+/** 按 id 删除单条通知记录，返回更新后的列表（仅移除该条，不影响其余记录）。 */
+export function removeNotification(id: number): NotificationRecord[] {
+  const next = loadNotifications().filter((r) => r.id !== id)
+  save(next)
+  return next
+}
+
+export type FailureKind = 'npmTooOld' | 'pnpmIgnoredBuild' | 'pluginPrepare' | 'repo'
 
 /**
- * 失败归类，三态。无论底层机制如何（pnpm 白名单拦截 / 构建脚本被忽略 / prepare 失败），
+ * 失败归类，四态。无论底层机制如何（pnpm 白名单拦截 / 构建脚本被忽略 / prepare 失败），
  * 对用户而言结果都一样 —— 当前安装通道（npm 或 git）装不上，就是插件分发/依赖的问题，
- * 一律引导提 Issue：
+ * 一律引导提 Issue；唯一例外是本机 npm 自身版本过低导致的内部崩溃（见 npmTooOld）：
+ * - npmTooOld：失败输出含 npm arborist 的 `edgesOut` 崩溃特征（build-ideal-tree.js 解 peer 依赖时
+ *   内部抛错，npm 11.6.0 前必现的已知缺陷，npm/cli#8261、#9787），或服务端已核实本机版本低于
+ *   阈值并打了 `[npm-too-low]` 标记 —— 是本机 npm 版本过低/自身缺陷，不是插件问题 → 引导升级 npm
  * - pnpmIgnoredBuild：插件依赖里的原生模块构建脚本被 pnpm 默认拦截（如 node-pty，
  *   `ERR_PNPM_IGNORED_BUILDS`）。只影响带原生模块的插件，其他插件不受影响 —— 差异在
  *   插件的依赖选择，属插件依赖/打包问题 → 引导去仓库提 Issue（建议改用预编译版本）
@@ -41,6 +119,10 @@ export type FailureKind = 'pnpmIgnoredBuild' | 'pluginPrepare' | 'repo'
  * - repo：其余失败（含 git prepare 被 pnpm 白名单拦截等），默认按插件仓库问题引导提 Issue
  */
 export function classifyFailure(message: string): FailureKind {
+  // npm 内部崩溃（edgesOut）或服务端 [npm-too-low] 标记：是本机 npm 版本过低/自身缺陷，
+  // 不是插件问题 —— 必须最先判，否则该报错会被外层 ERR_PNPM_PREPARE_PACKAGE 吞成
+  // 「插件打包分发问题」，误导用户去提 Issue
+  if (/\[npm-too-low\]|edgesOut/i.test(message)) return 'npmTooOld'
   // 装后校验拦截（服务端 verifyInstalledEntry 标记）：入口文件缺失 = git 分发缺构建产物，
   // 与 pluginPrepare 同类（插件打包/分发问题），引导去仓库提 Issue
   if (/\[packaging\]|entry file missing/i.test(message)) return 'pluginPrepare'
@@ -53,6 +135,13 @@ export function classifyFailure(message: string): FailureKind {
   return 'repo'
 }
 
+/** 从服务端 `[npm-too-low]` 标记行提取本机 npm 版本（如 `[npm-too-low] npm@11.3.0` → "11.3.0"）；
+ *  历史记录无标记时返回 null，前端据此决定提示文案是否带具体版本。 */
+export function npmTooLowVersion(message: string): string | null {
+  const m = message.match(/\[npm-too-low\]\s*npm@(\d+\.\d+\.\d+)/i)
+  return m ? m[1] : null
+}
+
 /** 核心行特征：错误代码 / 生命周期脚本失败 / prepare 失败 / 描述性报错（子模块缺失、找不到等）/ 退出与宿主提示信息。 */
 const CORE_LINE_RE = /ERR_[A-Z_]+|ELIFECYCLE|Command failed|prepare-guard|Failed to prepare|exit code|\bprepare\b|pnpm failed in profile|git-hosted plugins build|submodule|not found|cannot find|no such|unable to|fatal|missing|error/i
 /** 提交 issue 时正文里错误摘要的上限字符数。GitHub 请求行上限 8192 字节，
@@ -99,67 +188,3 @@ export function coreErrorCode(message: string): string | null {
   const m = message.match(/\[?ERR_[A-Z_]+\]?/)
   return m ? m[0].replace(/^\[|\]$/g, '') : null
 }
-
-/** 运行时 localStorage 访问：类型上不依赖 DOM lib（Node 测试环境也能编译），浏览器里取 window。 */
-const storage = (): Storage | undefined =>
-  (globalThis as { localStorage?: Storage }).localStorage
-
-/** 读取本地通知记录（损坏/不可用时返回空列表，不抛错）。列表最新在前，全部保留，只由「清空」按钮手动移除。 */
-export function loadNotifications(): NotificationRecord[] {
-  try {
-    const raw = storage()?.getItem(KEY)
-    if (!raw) return []
-    const list = JSON.parse(raw) as unknown
-    if (!Array.isArray(list)) return []
-    return list
-      .filter((r): r is NotificationRecord =>
-        !!r && typeof r === 'object' && typeof (r as { message?: unknown }).message === 'string')
-      // 历史失败记录没有 ok 字段：缺省按失败渲染，保证旧数据照常可查
-      .map((r) => ({ ...r, ok: r.ok === true }))
-  } catch {
-    return []
-  }
-}
-
-function save(list: NotificationRecord[]): void {
-  try {
-    storage()?.setItem(KEY, JSON.stringify(list))
-  } catch {
-    /* storage full / unavailable：仅保留内存态，界面仍可查看 */
-  }
-}
-
-/** 追加一条通知记录并持久化，返回更新后的完整列表（最新在前，超上限裁剪）。
- *  每次成功/失败都各自留痕：同一插件的安装/卸载记录都完整保留、只由「清空」按钮手动移除，
- *  不会因后续操作被自动覆盖清除。 */
-export function addNotification(record: Omit<NotificationRecord, 'id' | 'at'>): NotificationRecord[] {
-  const prev = loadNotifications()
-  let id = Date.now()
-  while (prev.some((r) => r.id === id)) id += 1
-  const next = [{ ...record, id, at: id }, ...prev].slice(0, MAX)
-  save(next)
-  return next
-}
-
-/** 记录一次失败：携带完整错误日志，供通知中心查看/复制/提 Issue。 */
-export function addFailure(record: Omit<NotificationRecord, 'id' | 'at' | 'ok'>): NotificationRecord[] {
-  return addNotification({ ...record, ok: false })
-}
-
-/** 记录一次成功：轻量记录，不带日志。 */
-export function addSuccess(record: Omit<NotificationRecord, 'id' | 'at' | 'ok' | 'message'>): NotificationRecord[] {
-  return addNotification({ ...record, ok: true, message: '' })
-}
-
-/** 清空全部通知记录，返回空列表。 */
-export function clearNotifications(): NotificationRecord[] {
-  save([])
-  return []
-}
-
-/** 按 id 删除单条通知记录，返回更新后的列表（仅移除该条，不影响其余记录）。 */
-export function removeNotification(id: number): NotificationRecord[] {
-  const next = loadNotifications().filter((r) => r.id !== id)
-  save(next)
-  return next
-}

package/src/client/{lib → logic}/format.ts

@@ -1,4 +1,8 @@
 /**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
  * Presentation formatters shared across the catalog list and the cards.
  */
 import type { Translate } from '../types.ts'

package/src/client/logic/install-command.ts

@@ -0,0 +1,56 @@
+/**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * Install target/command helpers: decide the install channel (npm package
+ * vs explicit-HTTPS GitHub), build the display command and normalize a raw
+ * install spec back to its owner/repo identity.
+ */
+import type { HubPlugin } from '../types.ts'
+
+/**
+ * 安装通道决策（用户无感知）：目录探测到 npm 包名 → 用 npm 包名安装
+ * （走 npm registry tarball，更快、与 GitHub 网络无关）；无 npm 包名 → git 直装。
+ * 返回值 target 即传给后端 /install 的安装目标（npm 包名 或 owner/repo）。
+ */
+export function installTargetOf(p: HubPlugin): { target: string; via: 'npm' | 'github' } {
+  const pkg = (p.source?.npmPackage ?? '').trim()
+  const repo = (p.source?.repo ?? '').trim()
+  if (pkg && repo) return { target: pkg, via: 'npm' }
+  return { target: repo, via: 'github' }
+}
+
+/** 展示用安装命令（复制/弹窗）：目录下发的权威命令优先（CLI-only 插件如 dsh-tui
+ *  需专属 profile（--profile dsh-tui），无法从 repo/npm 包名推断，必须用官方命令）；
+ *  常规插件无目录命令时按通道回退生成：npm 显示包名，git 显示显式 HTTPS URL。 */
+export function installCommandOf(p: HubPlugin, withProfile = false): string {
+  const { target, via } = installTargetOf(p)
+  if (via === 'npm') {
+    const cmd = p.install?.command
+    if (cmd) return cmd
+  } else {
+    const cmd = p.install?.githubCommand
+    if (cmd) return cmd
+  }
+  return via === 'npm'
+    ? `dsh plugin${withProfile ? ' --profile web' : ''} add ${target}`
+    : `dsh plugin${withProfile ? ' --profile web' : ''} add git+https://github.com/${target}.git`
+}
+
+/** Normalize a task/install target to its owner/repo display identity. */
+export function repoFromInstallTarget(value: string): string {
+  const input = value.trim()
+  if (/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(input)) return input
+  const patterns = [
+    /^github:([^/]+)\/([^/]+)$/i,
+    /^(?:git\+)?https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?(?:[?#].*)?$/i,
+    /^(?:git\+)?ssh:\/\/(?:git@)?github\.com\/([^/]+)\/([^/]+?)(?:\.git)?(?:[?#].*)?$/i,
+    /^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?(?:[?#].*)?$/i,
+  ]
+  for (const pattern of patterns) {
+    const match = pattern.exec(input)
+    if (match !== null) return `${match[1]}/${match[2]}`
+  }
+  return value
+}

package/src/client/logic/installed.ts

@@ -0,0 +1,207 @@
+/**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * Installed-plugin model (pure logic, zero React/UI dependencies).
+ *
+ * Merges the local installed table (from the host's `/installed` route:
+ * npm name → manifest spec) with the catalog projection into a single
+ * `InstalledItem` view-model consumed by the Installed view. Also hosts the
+ * install matching / update detection used by the market view, so both
+ * views share one source of truth.
+ */
+import type { HubPlugin } from '../types.ts'
+import { HUB_REPO } from './constants.ts'
+import { repoFromInstallTarget } from './install-command.ts'
+
+/** 安装时记录的目录信号（versions 表项）。 */
+export interface InstalledVersionSignal {
+  version: string
+  updatedAt: string
+  installedAt?: string
+  npmPackage?: string
+}
+
+/** 已安装项统一模型：目录元数据 + 宿主运行时信息的合并视图（驱动「已安装」tab）。 */
+export interface InstalledItem {
+  /** npm 包名（profile 依赖 key） */
+  name: string
+  /** manifest spec（github:owner/repo、git+https://…、或 npm 版本号） */
+  spec: string
+  /** 目录里匹配到的插件；目录外/未收录的安装为 null */
+  plugin: HubPlugin | null
+  /** 仓库身份（owner/repo）；纯 npm 安装无法识别时为 null */
+  repo: string | null
+  /** 安装到系统上的路径（profile/node_modules/<包名>）；宿主未提供为 null */
+  installPath: string | null
+  /** 安装时记录的目录版本（无记录为 null） */
+  installedVersion: string | null
+  /** 安装时间（ISO，无记录为 null） */
+  installedAt: string | null
+  /** 目录当前最新版本（仓库无 release 为 null） */
+  catalogVersion: string | null
+  /** 是否有可用更新（有版本比版本，无版本比仓库更新时间） */
+  hasUpdate: boolean
+  /** 是否已加载进运行中 loader（官方 ctx.loader 对账）；false = 已安装但未挂载（装完未重启） */
+  loaded: boolean
+  /** 是否真正的 dsh 插件（包内声明 dsh 配置 / 在 profile bundles 清单）：
+   *  非 dsh 插件（如 GitHub 官方示例仓库）装上也不会被宿主加载，不提示「待重启」 */
+  dshCapable: boolean
+}
+
+/** 安装时记录的目录信号（按仓库小写 key 查表）。 */
+function signalOf(repo: string | null, versions: Record<string, InstalledVersionSignal>): InstalledVersionSignal | null {
+  if (!repo) return null
+  return versions[repo.toLowerCase()] ?? null
+}
+
+/** 插件是否已安装：匹配 Git spec 中的 owner/repo，或 npm 通道安装的依赖包名；命中返回 npm 包名。 */
+export function installedNameOf(
+  plugin: HubPlugin,
+  installed: Record<string, string>,
+  versions: Record<string, InstalledVersionSignal>,
+): string | null {
+  const repo = plugin.source?.repo
+  if (!repo) return null
+  const needle = repo.toLowerCase()
+  for (const [name, spec] of Object.entries(installed)) {
+    if (repoFromInstallTarget(spec).toLowerCase() === needle) return name
+  }
+  // npm 通道安装：profile 依赖 key 直接是 npm 包名。包名来源两处——目录数据（npmPackage），
+  // 或服务端 npm 优先反查持久化的映射（versions[repo].npmPackage，覆盖组织 scope 与 GitHub
+  // 用户名不一致、目录未下发包名的场景）；命中任一并依赖 key 真实存在即视为已安装。
+  // 只认 npm 安装的依赖（spec 无法解析出仓库身份）：git/本地安装的依赖身份由仓库匹配决定，
+  // 包名同名不代表同仓库——否则「git 装 A 仓库」会被「npm 包名同名但仓库不同」的目录条目
+  // 误认领成已安装（假阳性），installedItems 里出现同 key 双条目，排序一变化就渲染出幽灵行。
+  const pkg = ((plugin.source?.npmPackage || versions[repo.toLowerCase()]?.npmPackage) ?? '').toLowerCase()
+  if (pkg) {
+    for (const [name, spec] of Object.entries(installed)) {
+      if (isRepoLike(repoFromInstallTarget(spec))) continue
+      if (name.toLowerCase() === pkg) return name
+    }
+  }
+  return null
+}
+
+/** 该插件安装时记录的目录版本（无记录/未安装 → null）。 */
+export function installedVersionOf(plugin: HubPlugin, versions: Record<string, InstalledVersionSignal>): string | null {
+  const repo = plugin.source?.repo
+  if (!repo) return null
+  return versions[repo.toLowerCase()]?.version ?? null
+}
+
+/**
+ * 是否有更新：仅对已安装插件有意义。
+ * 双信号判定——有 release 版本的比版本；无版本（repo 不打 tag）的比仓库最近更新时间
+ * （repoUpdatedAt，ISO 字符串字典序 = 时间序），更新时间变新说明有新提交。
+ */
+export function hasUpdateOf(
+  plugin: HubPlugin,
+  installed: Record<string, string>,
+  versions: Record<string, InstalledVersionSignal>,
+): boolean {
+  if (installedNameOf(plugin, installed, versions) === null) return false
+  const repo = plugin.source?.repo
+  if (!repo) return false
+  const rec = versions[repo.toLowerCase()]
+  if (!rec) return false
+  if (plugin.version) return plugin.version !== rec.version
+  const current = plugin.dates?.repoUpdatedAt
+  return Boolean(current && rec.updatedAt && current > rec.updatedAt)
+}
+
+/** 依赖 spec 能否解析出仓库身份（owner/repo 形态才算）。 */
+function isRepoLike(value: string): boolean {
+  return /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(value)
+}
+
+/** 已安装项 → 弹窗可用的伪插件对象：卸载确认弹窗只读名称/来源行，
+ *  自定义安装（目录外）没有完整目录数据，用它把 InstalledItem 适配成 HubPlugin。 */
+export function pluginOfItem(item: InstalledItem): HubPlugin {
+  return {
+    slug: item.name,
+    displayName: item.plugin?.displayName ?? item.name,
+    source: item.repo ? { repo: item.repo } : undefined,
+    description: item.plugin?.description,
+  }
+}
+
+/**
+ * Hub 自身（本插件 dsh-plugin）的识别：三维互证，杜绝误伤同名第三方包。
+ *  1) 依赖 key 固定为 `dsh-plugin`（本插件 npm 包名）；
+ *  2) spec 为 `file:`/`link:` 本地链接（hub 以 file: 安装进宿主）；
+ *  3) 或 spec 解析出的仓库身份就是自营仓库 `dshplugin/dsh-plugin-hub`。
+ * 命中即视为宿主内置本体：永不出现在「自定义安装」里，卸载接口也早已对
+ * 它 400 拒绝（服务端多维防线之一）——显示出来只会让用户误点卸载。
+ */
+function isHubSelf(name: string, spec: string): boolean {
+  if (name !== 'dsh-plugin') return false
+  if (spec.startsWith('file:') || spec.startsWith('link:')) return true
+  const repo = repoFromInstallTarget(spec)
+  return isRepoLike(repo) && repo.toLowerCase() === HUB_REPO.toLowerCase()
+}
+
+/**
+ * 构建已安装项列表：目录插件按命中关系合并（拥有完整元数据），
+ * 剩余未认领的依赖 key 归为自定义安装（目录外，仅运行时信息）。
+ */
+export function installedItemsOf(
+  plugins: HubPlugin[] | null,
+  installed: Record<string, string>,
+  versions: Record<string, InstalledVersionSignal>,
+  paths: Record<string, string> | null,
+  loadedNames: string[] | null,
+  dshCapableNames: string[] | null,
+): InstalledItem[] {
+  const items: InstalledItem[] = []
+  // 已被目录条目认领的依赖 key：同一依赖只归属一个目录条目（React key 必须唯一，
+  // 否则同名双条目排序一变化就渲染出幽灵行）；剩余未认领的归自定义安装。
+  const claimed = new Set<string>()
+  // 目录匹配：遍历目录插件，命中 installedNameOf 即视为已安装并合并元数据
+  for (const p of plugins ?? []) {
+    const name = installedNameOf(p, installed, versions)
+    if (name === null || claimed.has(name)) continue
+    claimed.add(name)
+    const repo = p.source?.repo ?? null
+    const rec = signalOf(repo, versions)
+    items.push({
+      name,
+      spec: installed[name],
+      plugin: p,
+      repo,
+      installPath: paths?.[name] ?? null,
+      installedVersion: rec?.version ?? null,
+      installedAt: rec?.installedAt ?? null,
+      catalogVersion: p.version ?? null,
+      hasUpdate: hasUpdateOf(p, installed, versions),
+      loaded: loadedNames?.includes(name) ?? false,
+      dshCapable: dshCapableNames?.includes(name) ?? false,
+    })
+  }
+  // 自定义安装：依赖表里没被任何目录插件认领的条目（命令行安装的目录外插件）
+  for (const [name, spec] of Object.entries(installed)) {
+    if (claimed.has(name)) continue
+    // Hub 自身（本插件 dsh-plugin）由宿主内置加载，不是可管理的插件：永不进已安装列表，
+    // 避免出现在「自定义安装」里被误点卸载（服务端卸载接口对它的 400 拒绝是最后一道防线）
+    if (isHubSelf(name, spec)) continue
+    const parsed = repoFromInstallTarget(spec)
+    const repo = isRepoLike(parsed) ? parsed : null
+    const rec = signalOf(repo, versions)
+    items.push({
+      name,
+      spec,
+      plugin: null,
+      repo,
+      installPath: paths?.[name] ?? null,
+      installedVersion: rec?.version ?? null,
+      installedAt: rec?.installedAt ?? null,
+      catalogVersion: null,
+      // 目录外没有目录信号可比，无法判断是否有更新
+      hasUpdate: false,
+      loaded: loadedNames?.includes(name) ?? false,
+      dshCapable: dshCapableNames?.includes(name) ?? false,
+    })
+  }
+  return items
+}

package/src/client/logic/normalize.ts

@@ -0,0 +1,52 @@
+/**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
+ * Normalizer: maps the online API's short-key payload (s/o/n/vr/c/t/f/d/r/v/u/a/sg/fk)
+ * to HubPlugin so rendering only ever sees one shape.
+ */
+import type { HubPlugin } from '../types.ts'
+
+export function normalize(raw: Record<string, unknown>): HubPlugin {
+  if (typeof raw.s === 'string') {
+    return {
+      slug: raw.s,
+      ownerSlug: typeof raw.o === 'string' ? raw.o : undefined,
+      displayName: typeof raw.n === 'string' ? raw.n : undefined,
+      version: typeof raw.vr === 'string' ? raw.vr : undefined,
+      category: typeof raw.c === 'string' ? raw.c : undefined,
+      topics: Array.isArray(raw.t) ? (raw.t as string[]) : undefined,
+      features: Array.isArray(raw.f) ? (raw.f as string[]) : undefined,
+      description: typeof raw.d === 'string' ? raw.d : undefined,
+      // source 双形态：字符串 repo，或 { repo, npmPackage } 对象
+      source: typeof raw.r === 'string'
+        ? { repo: raw.r }
+        : raw.r !== null && typeof raw.r === 'object'
+          ? {
+            repo: typeof (raw.r as { repo?: unknown }).repo === 'string' ? (raw.r as { repo: string }).repo : undefined,
+            npmPackage: typeof (raw.r as { npmPackage?: unknown }).npmPackage === 'string' ? (raw.r as { npmPackage: string }).npmPackage : undefined,
+          }
+          : undefined,
+      // 安装信息：wi 仅在 false 时下发（缺省视为 true 可一键安装）；
+      // ic/igc = 目录下发的权威安装命令（npm/git 通道各一条，CLI-only 插件如 dsh-tui 必须用）
+      install: raw.wi === false || typeof raw.ic === 'string' || typeof raw.igc === 'string'
+        ? {
+          webInstallable: raw.wi === false ? false : undefined,
+          command: typeof raw.ic === 'string' ? raw.ic : undefined,
+          githubCommand: typeof raw.igc === 'string' ? raw.igc : undefined,
+        }
+        : undefined,
+      compatibility: typeof raw.v === 'string' ? { status: raw.v } : undefined,
+      dates: {
+        repoUpdatedAt: typeof raw.u === 'string' ? raw.u : undefined,
+        addedAt: typeof raw.a === 'string' ? raw.a : undefined,
+      },
+      stats: {
+        stargazers_count: typeof raw.sg === 'number' ? raw.sg : undefined,
+        forks_count: typeof raw.fk === 'number' ? raw.fk : undefined,
+      },
+    }
+  }
+  return raw as unknown as HubPlugin
+}

package/src/client/{lib → logic}/renderMarkdown.ts

@@ -1,4 +1,8 @@
 /**
+ * DSH-Plugin Hub — the community plugin marketplace for DeepSeek Harness.
+ * Website: https://dsh-plugin.org
+ * GitHub: https://github.com/dshplugin/dsh-plugin-hub
+ *
  * 轻量 Markdown 渲染器：仅用于 Hub 自我更新的变更记录（Worker 下发的 notes）。
  *
  * 内容由插件作者自己编写、属可信内容，但渲染端仍先整体 HTML 转义，再按