dsh-plugin 0.1.1 → 1.0.0

package/src/client/index.tsx

@@ -1,435 +1,21 @@
 /**
- * dsh-plugin client: a native "Plugin Hub" settings section that renders
- * the community marketplace (dsh-plugin.org) as a first-class catalog —
- * category tabs (11 categories + All), search, sorting and one-click
- * install-command copy. Plugin data is fetched live from dsh-plugin.org,
- * so the browser bundle stays small and always in sync with the site.
- *
- * Built by tsdown into the __ModuleLoader__ factory bundle at client/client.js.
+ * dsh-plugin client entry: wires the Plugin Hub into the host settings via
+ * the module-loader bundle (see tsdown.config.ts). All UI logic lives in
+ * PluginHubSection; this file only performs the cordis apply wiring.
  */
-import { createElement as h, useEffect, useMemo, useRef, useState } from 'react'
-import styles from './Section.module.css'
+import { createElement as h } from 'react'
+import type { HubClientContext } from './types.ts'
 import { en, zh } from './locales.ts'
+import { PluginHubSection } from './components/PluginHubSection.tsx'
+import './styles/tokens.module.css'
 
 const NS = 'dsh-plugin'
-const SITE_URL = 'https://dsh-plugin.org/'
-
-type LocaleId = 'zh' | 'en'
-
-/** The subset of the locale service this plugin touches. */
-interface LocaleService {
-  register(namespace: string, dicts: { zh: Record<string, string>; en: Record<string, string> }): unknown
-  bind(namespace: string): (key: string, params?: Record<string, string | number>) => string
-  getSnapshot(): { active: LocaleId }
-  subscribe(fn: () => void): () => void
-}
-
-/** The subset of the slots service this plugin touches. */
-interface SlotsService {
-  inject(slot: string, register: () => unknown): void
-  register(meta: Record<string, unknown>, component: () => unknown): unknown
-}
-
-/** The client cordis context shape this plugin relies on (structural). */
-interface HubClientContext {
-  effect(callback: () => unknown, label?: string): void
-  slots: SlotsService
-  locale: LocaleService
-}
-
-interface SectionProps {
-  t: (key: string, params?: Record<string, string | number>) => string
-  locale: LocaleService
-}
-
-/** Slim projection of the site's DirectoryPlugin entries. */
-interface HubPlugin {
-  /** 作者小写 key，与 slug 共同构成唯一身份（两级路径 /plugins/{ownerSlug}/{slug}）；旧数据可能缺省 */
-  ownerSlug?: string
-  slug: string
-  displayName?: string
-  category?: string
-  topics?: string[]
-  features?: string[]
-  description?: string
-  source?: { repo?: string }
-  compatibility?: { status?: string }
-  dates?: { repoUpdatedAt?: string; addedAt?: string }
-  stats?: { stargazers_count?: number; forks_count?: number }
-}
-
-const CATEGORY_ORDER = [
-  'interface', 'session', 'memory', 'tools', 'agent', 'workflow',
-  'integration', 'model', 'dev', 'knowledge', 'fun',
-]
-
-/**
- * 归一化在线 API（dsh-plugin.org/api/plugins.{lang}.json）返回的短 key 结构
- * （s/o/n/c/t/f/d/r/v/u/a/sg/fk），统一为 HubPlugin，保证渲染逻辑只认一种结构。
- */
-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,
-      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: typeof raw.r === 'string' ? { repo: raw.r } : 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
-}
-
-const CATEGORY_LABELS: Record<string, { zh: string; en: string }> = {
-  interface: { zh: '界面与体验', en: 'UI & Experience' },
-  session: { zh: '会话与消息', en: 'Sessions & Messages' },
-  memory: { zh: '记忆与上下文', en: 'Memory & Context' },
-  tools: { zh: '工具与能力', en: 'Tools & Capabilities' },
-  agent: { zh: '技能与智能体', en: 'Skills & Agents' },
-  workflow: { zh: '工作流与自动化', en: 'Workflow & Automation' },
-  integration: { zh: '集成与连接', en: 'Integrations & Connections' },
-  model: { zh: '模型与推理', en: 'Models & Reasoning' },
-  dev: { zh: '开发与运维', en: 'Development & Operations' },
-  knowledge: { zh: '数据与知识', en: 'Data & Knowledge' },
-  fun: { zh: '娱乐', en: 'Entertainment' },
-}
-
-const CATEGORY_SHORT_LABELS: Record<string, { zh: string; en: string }> = {
-  interface: { zh: '界面体验', en: 'UI Exp' },
-  session: { zh: '会话消息', en: 'Sessions' },
-  memory: { zh: '记忆上下文', en: 'Memory' },
-  tools: { zh: '工具能力', en: 'Tools' },
-  agent: { zh: '技能智能体', en: 'Agents' },
-  workflow: { zh: '工作流', en: 'Workflow' },
-  integration: { zh: '集成连接', en: 'Integrations' },
-  model: { zh: '模型推理', en: 'Models' },
-  dev: { zh: '开发运维', en: 'Dev' },
-  knowledge: { zh: '数据知识', en: 'Knowledge' },
-  fun: { zh: '娱乐', en: 'Fun' },
-}
-
-const SORTS = ['sortStars', 'sortUpdated', 'sortNewest'] as const
-type SortKey = (typeof SORTS)[number]
-
-function fmtStars(count?: number): string {
-  if (!count || count <= 0) return '0'
-  if (count < 1000) return String(count)
-  const k = count / 1000
-  return `${k >= 100 ? Math.round(k) : k.toFixed(1).replace(/\.0$/, '')}k`
-}
-
-function relTime(iso: string | undefined, t: SectionProps['t']): string {
-  if (!iso) return ''
-  const days = Math.floor((Date.now() - new Date(iso).getTime()) / 86400000)
-  if (days <= 0) return t('today')
-  if (days < 30) return t('daysAgo', { days })
-  if (days < 365) return t('monthsAgo', { months: Math.floor(days / 30) })
-  return t('yearsAgo', { years: Math.floor(days / 365) })
-}
-
-function PluginHubSection({ t: _hostT, locale }: SectionProps) {
-  const [lang, setLang] = useState<LocaleId>(locale.getSnapshot().active)
-  const [plugins, setPlugins] = useState<HubPlugin[] | null>(null)
-  /** 收录/精选统计（官网 /api/stats.json 实时拉取） */
-  const [stats, setStats] = useState<{ total: number; verified: number } | null>(null)
-  const [failed, setFailed] = useState(false)
-  const [reloadKey, setReloadKey] = useState(0)
-  const [category, setCategory] = useState('all')
-  const [query, setQuery] = useState('')
-  const [sort, setSort] = useState<SortKey>('sortStars')
-  const [copied, setCopied] = useState<string | null>(null)
-  /** 全局复制成功 Toast：{id} 用于重复点击时重新触发入场动画 */
-  const [toast, setToast] = useState<{ id: number } | null>(null)
-  /** 列表滚动容器：分类/搜索切换后列表内容替换但 scrollTop 保留，会让用户误以为列表没更新，需重置回顶部 */
-  const listRef = useRef<HTMLDivElement | null>(null)
-
-  useEffect(() => {
-    listRef.current?.scrollTo({ top: 0 })
-  }, [category])
-
-  useEffect(() => locale.subscribe(() => setLang(locale.getSnapshot().active)), [locale])
-
-  useEffect(() => {
-    let cancelled = false
-    setPlugins(null)
-    setStats(null)
-    setFailed(false)
-    const apply = (data: unknown) => {
-      if (cancelled) return
-      // 在线 API 已只返回 verified；再过滤一次，保证只展示人工验证通过的插件。
-      const list = (Array.isArray(data) ? data : []).map((item) => normalize(item as Record<string, unknown>))
-      setPlugins(list.filter((p) => p.compatibility?.status === 'verified'))
-    }
-    const fail = () => {
-      if (!cancelled) setFailed(true)
-    }
-    const fetchData = (url: string): Promise<unknown> =>
-      fetch(url).then((res) => {
-        if (!res.ok) throw new Error(String(res.status))
-        return res.json()
-      })
-    // 在线拉取最新数据（dsh-plugin.org，走 CDN 缓存），插件不发布也能拿到每日更新。
-    const remote = `https://dsh-plugin.org/api/plugins.${lang}.json`
-    fetchData(remote).then(apply).catch(fail)
-    // 收录/精选统计：实时拉取官网 /api/stats.json。
-    const applyStats = (s: { total: number; verified: number }) => {
-      if (!cancelled && s && typeof s.total === 'number' && typeof s.verified === 'number') setStats(s)
-    }
-    fetchData('https://dsh-plugin.org/api/stats.json')
-      .then((s) => applyStats(s as { total: number; verified: number }))
-      .catch(() => {})
-    return () => { cancelled = true }
-  }, [lang, reloadKey])
-
-  const visible = useMemo(() => {
-    if (!plugins) return []
-    const q = query.trim().toLowerCase()
-    const list = plugins.filter((p) => {
-      if (category !== 'all' && p.category !== category) return false
-      if (!q) return true
-      return (
-        (p.displayName ?? '').toLowerCase().includes(q) ||
-        (p.description ?? '').toLowerCase().includes(q) ||
-        (p.topics ?? []).some((topic) => topic.toLowerCase().includes(q))
-      )
-    })
-    return [...list].sort((a, b) => {
-      if (sort === 'sortStars') return (b.stats?.stargazers_count ?? 0) - (a.stats?.stargazers_count ?? 0)
-      if (sort === 'sortNewest') return (b.dates?.addedAt ?? '').localeCompare(a.dates?.addedAt ?? '')
-      return (b.dates?.repoUpdatedAt ?? '').localeCompare(a.dates?.repoUpdatedAt ?? '')
-    })
-  }, [plugins, category, query, sort])
-
-  const langKey: LocaleId = lang === 'en' ? 'en' : 'zh'
-  // dsh-plugin.org keeps zh pages under the /zh/ prefix; en is the root.
-  const langPath = lang === 'zh' ? 'zh/' : ''
-
-  // 插件界面语言由组件自身 lang 控制（左上角 EN/中文 按钮），宿主的 t() 绑定宿主 locale、
-  // 不跟随组件内 lang，因此这里基于本地字典自建翻译函数，保证切换语言后所有文本即时刷新。
-  // （settings.section 的导航 label 仍在 apply 里用宿主 t()，跟随宿主语言。）
-  const dict: Record<string, string> = langKey === 'en' ? en : zh
-  const t = (key: string, params?: Record<string, string | number>): string => {
-    const raw = dict[key] ?? key
-    return params ? raw.replace(/\{(\w+)\}/g, (_, k) => String(params[k] ?? '')) : raw
-  }
-  const catLabel = (map: Record<string, { zh: string; en: string }>, key: string): string =>
-    map[key]?.[langKey] ?? key
-
-  const copyInstall = async (repo: string) => {
-    const text = `dsh plugin add ${repo}`
-    let ok = false
-    try {
-      await navigator.clipboard.writeText(text)
-      ok = true
-    } catch {
-      // Clipboard API unavailable (permissions/iframe) — fall back to the
-      // legacy hidden-textarea trick, which works in any context.
-      const ta = document.createElement('textarea')
-      ta.value = text
-      ta.style.position = 'fixed'
-      ta.style.opacity = '0'
-      document.body.appendChild(ta)
-      ta.select()
-      try {
-        ok = document.execCommand('copy')
-      } catch {
-        ok = false
-      }
-      document.body.removeChild(ta)
-    }
-    if (ok) {
-      setCopied(repo)
-      setToast({ id: Date.now() })
-      window.setTimeout(() => setCopied((cur) => (cur === repo ? null : cur)), 1600)
-      window.setTimeout(() => setToast(null), 1800)
-    } else {
-      setCopied(null)
-    }
-  }
-
-  const total = plugins?.length ?? 0
-  const count = visible.length
-
-  // 统计数字：官网 /api/stats.json 优先；拉取失败时用已加载列表兜底，避免展示 undefined。
-  const statsTotal = stats?.total ?? total
-  const statsVerified = stats?.verified ?? 0
-
-  // Per-category plugin counts shown on the category chips.
-  const categoryCounts = useMemo(() => {
-    const counts: Record<string, number> = { all: total }
-    for (const p of plugins ?? []) {
-      if (p.category) counts[p.category] = (counts[p.category] ?? 0) + 1
-    }
-    return counts
-  }, [plugins, total])
-
-  return h('div', { className: styles.root },
-    h('div', { className: styles.header },
-      h('div', { className: styles.brand },
-        h('div', { className: styles.brandText },
-          // 市场主标题即本区块的 H1：与官网首页 H1 同文案（DSH-Plugin Hub for DeepSeek
-          // Harness），命中品牌词 DSH-Plugin + 产品词 DeepSeek Harness；关键词落在 tagline。
-          h('h1', { className: styles.title }, t('title')),
-          h('div', { className: styles.tagline }, t('tagline', { total: statsTotal, verified: statsVerified })),
-        ),
-      ),
-      h('div', { className: styles.controls },
-        h('input', {
-          className: styles.search,
-          type: 'search',
-          placeholder: t('search'),
-          value: query,
-          spellCheck: false,
-          onInput: (e: React.FormEvent<HTMLInputElement>) =>
-            setQuery((e.target as HTMLInputElement).value),
-        }),
-        h('select', {
-          className: styles.sort,
-          value: sort,
-          onChange: (e: React.FormEvent<HTMLSelectElement>) =>
-            setSort((e.target as HTMLSelectElement).value as SortKey),
-        }, SORTS.map((key) => h('option', { key, value: key }, t(key)))),
-        h('button', {
-          className: styles.langBtn,
-          title: lang === 'zh' ? t('toEn') : t('toZh'),
-          onClick: () => setLang(lang === 'zh' ? 'en' : 'zh'),
-        }, lang === 'zh' ? 'EN' : '中文'),
-        h('a', {
-          className: styles.openBtn,
-          href: `${SITE_URL}${langPath}`,
-          target: '_blank',
-          rel: 'noopener noreferrer',
-          title: t('openHint'),
-        }, t('openBtn'), h('span', { className: styles.openArrow }, '\u2197')),
-      ),
-    ),
-
-    h('a', {
-      className: styles.adBanner,
-      href: `${SITE_URL}${langPath}`,
-      target: '_blank',
-      rel: 'noopener noreferrer',
-    },
-    h('span', { className: styles.adBadge }, t('adBadge')),
-    h('span', { className: styles.adText }, t('ad', { total: statsTotal, verified: statsVerified })),
-    h('span', { className: styles.adArrow }, '\u2197')),
-
-    h('div', { className: styles.tabs },
-      h('button', {
-        key: 'all',
-        className: category === 'all' ? styles.tabActive : styles.tab,
-        onClick: () => setCategory('all'),
-      },
-      t('all'),
-      h('span', { className: category === 'all' ? styles.tabCountActive : styles.tabCount }, total)),
-      CATEGORY_ORDER.map((id) => h('button', {
-        key: id,
-        className: category === id ? styles.tabActive : styles.tab,
-        onClick: () => setCategory(id),
-      },
-      catLabel(CATEGORY_SHORT_LABELS, id),
-      h('span', { className: category === id ? styles.tabCountActive : styles.tabCount }, categoryCounts[id] ?? 0))),
-    ),
-
-    h('div', { className: styles.body },
-      h('div', { ref: listRef, className: styles.list },
-        plugins === null && !failed && h('div', { className: styles.state }, t('loading')),
-        failed && h('div', { className: styles.state },
-          h('div', { className: styles.stateTitle }, t('failed')),
-          h('div', { className: styles.stateDesc }, t('failedDesc')),
-          h('button', { className: styles.retryBtn, onClick: () => setReloadKey((k) => k + 1) }, t('retry')),
-        ),
-        plugins !== null && !failed && count === 0 && h('div', { className: styles.state },
-          h('div', { className: styles.stateTitle }, t('noResult')),
-          h('div', { className: styles.stateDesc }, t('noResultDesc')),
-        ),
-        plugins !== null && !failed && visible.map((p) => {
-          const repo = p.source?.repo ?? ''
-          const isCopied = copied === repo
-          return h('div', {
-            // 唯一 key：数据重构后同一 slug 可能对应多个作者仓库，仅用 slug 会撞 key，
-            // 导致切换分类时 React 复用旧 DOM、列表不刷新。
-            key: p.ownerSlug ? `${p.ownerSlug}/${p.slug}` : p.slug,
-            className: styles.card,
-          },
-            h('div', { className: styles.cardMain },
-              h('div', { className: styles.cardHead },
-                h('div', { className: styles.cardTitle, title: p.description ?? '' }, p.displayName ?? p.slug),
-                p.category ? h('span', { className: styles.categoryBadge }, catLabel(CATEGORY_LABELS, p.category)) : null,
-                p.compatibility?.status === 'verified'
-                  ? h('span', { className: styles.verified }, t('verified'))
-                  : null,
-              ),
-              // 英文模式下隐藏仍为中文的描述：站点英文数据缺翻译时 description 会回退成中文，
-              // 不显示可保证界面语言一致，不残留中文字符。
-              p.description && (langKey === 'zh' || !/[\u4e00-\u9fff]/.test(p.description))
-                ? h('p', { className: styles.desc }, p.description)
-                : null,
-              (p.topics?.length ?? 0) > 0
-                ? h('div', { className: styles.topics },
-                  p.topics!.slice(0, 3).map((topic) => h('span', { key: topic, className: styles.topic }, topic)),
-                )
-                : null,
-            ),
-            h('div', { className: styles.cardSide },
-              h('div', { className: styles.stats },
-                h('span', { className: styles.star }, '\u2605 ', fmtStars(p.stats?.stargazers_count)),
-                h('span', { className: styles.fork }, t('fork'), ' ', fmtStars(p.stats?.forks_count)),
-                h('span', { className: styles.date }, relTime(p.dates?.repoUpdatedAt, t)),
-              ),
-              repo
-                ? h('div', { className: styles.actions },
-                  h('a', {
-                    className: styles.detailBtn,
-                    // 两级路径：/plugins/{ownerSlug}/{slug}；旧数据缺 ownerSlug 时从 repo 推导
-                    href: `${SITE_URL}${langPath}plugins/${p.ownerSlug ?? repo.split('/')[0]?.toLowerCase() ?? ''}/${p.slug}`,
-                    target: '_blank',
-                    rel: 'noopener noreferrer',
-                    title: p.slug,
-                  }, t('detail')),
-                  h('button', {
-                    className: isCopied ? styles.installBtnCopied : styles.installBtn,
-                    // 文字恒定避免按钮宽度变化导致卡片跳动；成功反馈 = 蓝底高亮 + 右下角 Toast
-                    onClick: () => copyInstall(repo),
-                  }, t('copy')),
-                )
-                : null,
-            ),
-          )
-        }),
-      ),
-      plugins !== null && !failed && h('div', { className: styles.footer },
-        h('span', { className: styles.footText }, count === total ? t('pluginsTotal', { n: total }) : t('filteredCount', { n: count })),
-        h('a', {
-          className: styles.footLink,
-          href: `${SITE_URL}${langPath}`,
-          target: '_blank',
-          rel: 'noopener noreferrer',
-        }, t('browseAll', { n: total })),
-      ),
-    ),
-    // 复制成功提示条：右下角纯黑色文字条，1800ms 后自动消失
-    toast && h('div', { key: toast.id, className: styles.toast }, t('toastCopied')),
-  )
-}
 
 export const name = NS
 export const inject = ['slots', 'locale']
 
 export function apply(ctx: HubClientContext): void {
-  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'dsh-plugin: dictionaries')
+  ctx.effect(() => ctx.locale.register(NS, { zh, en }), `${NS}: dictionaries`)
   const t = ctx.locale.bind(NS)
   ctx.slots.inject('settings.section', () => ctx.slots.register({
     name: 'settings.section',

package/src/client/lib/catalog.ts

@@ -0,0 +1,204 @@
+/**
+ * Catalog constants and normalizers: site URLs, category metadata, sort keys
+ * and the mapping from the online API's short-key payloads to HubPlugin.
+ */
+import type { EnvInfo, HubPlugin, LocaleId } from '../types.ts'
+import { MAX_CORE_CHARS, classifyFailure, coreErrorCode, summarizeError } from './failures.ts'
+
+/** 插件中心官网地址。 */
+export const SITE_URL = 'https://dsh-plugin.org/'
+
+/** 插件中心源码仓库：头部右上角 GitHub 图标的跳转地址 */
+export const GITHUB_URL = 'https://github.com/dshplugin/dsh-plugin-hub'
+
+/** 构建时由 tsdown 从 package.json 注入的插件版本号（见 tsdown.config.ts define）。 */
+declare const __PLUGIN_VERSION__: string
+
+/**
+ * 插件当前版本号，供头部标题展示「DSH-Plugin Hub v0.1.1」。
+ * tsdown 构建时用 define 把 __PLUGIN_VERSION__ 替换成 package.json 的版本号；
+ * node --test 直接 import 本模块时该标识符不存在，typeof 守卫兜底为空串。
+ */
+export const PLUGIN_VERSION: string =
+  typeof __PLUGIN_VERSION__ === 'string' ? __PLUGIN_VERSION__ : ''
+
+/** dsh-plugin.org 中文页挂在 /zh/ 前缀下，英文在根路径。 */
+export function langPathOf(lang: LocaleId): string {
+  return lang === 'zh' ? 'zh/' : ''
+}
+
+/**
+ * 官网详情页两级路径：/plugins/{ownerSlug}/{slug}；
+ * 旧数据缺 ownerSlug 时从 repo 推导（卡片详情按钮与弹窗来源行共用）。
+ */
+export function pluginDetailUrl(plugin: HubPlugin, langPath: string): string {
+  const repo = plugin.source?.repo ?? ''
+  return `${SITE_URL}${langPath}plugins/${plugin.ownerSlug ?? repo.split('/')[0]?.toLowerCase() ?? ''}/${plugin.slug}`
+}
+
+/**
+ * 失败弹窗里仓库地址的跳转目标：官网详情页（含插件收录信息），
+ * 与 issue 正文的 Catalog 链接同一形式（单级 /plugins/{repo}）。
+ */
+export function pluginSiteUrl(repo: string): string {
+  return `${SITE_URL}plugins/${repo}`
+}
+
+/**
+ * 一键反馈 GitHub Issue 的预填链接：标题带「来自 dsh-plugin.org」标识，正文只带
+ * 核心信息 —— 原因判定 + 关键错误代码 + 宿主机器环境快照 + 错误核心摘要（完整日志
+ * 太长，塞进 URL 会被 GitHub 以「request URL too long」拒绝，故只收集重点）。
+ * 错误弹窗、失败记录共用此逻辑。
+ * env 取不到时为 null，链接照常生成、只是少环境段。
+ */
+export function pluginIssueUrl(repo: string, message: string, env?: EnvInfo | null): string {
+  const title = `[dsh-plugin.org | dsh-plugin-hub] Install/Remove failed: ${repo}`
+  // 原因判定：让作者一眼知道这是不是自己插件的问题。
+  // [packaging]（预检/装后校验拦截）单独列：点明「不支持官方默认安装方式」，并写清官方默认方式
+  // 是什么（git 直装要求仓库提交构建产物或提供 prepare 脚本），作者照此适配即可。
+  const kind = classifyFailure(message)
+  const reason = /\[packaging\]/i.test(message)
+    ? 'plugin does NOT support the official default install method (dsh plugin add github:owner/repo — requires build output committed to the repo or a prepare script); its git distribution lacks the entry file declared in package.json'
+      : kind === 'pluginPrepare'
+        ? 'plugin prepare/build script failed during install (packaging/distribution issue)'
+        : kind === 'pnpmIgnoredBuild'
+          ? 'plugin depends on a native module whose build script pnpm blocks by default (use a prebuilt variant)'
+          : 'plugin-side install failure'
+  const code = coreErrorCode(message)
+  // 按给定核心摘要预算构建完整预填 URL（含 URL 编码）；预算可调，供超长时逐档缩小
+  const build = (coreChars: number): string => {
+    const body = [
+      '## Summary',
+      `- Cause: ${reason}`,
+      ...(code ? [`- Key error: \`${code}\``] : []),
+      '',
+      // 来源说明：标题（链官网）+ 一句来源（链仓库）+ 实际执行的官方安装命令（含 --profile）与执行结果，链接由常量动态拼接
+      `## [DSH-Plugin 插件中心](${SITE_URL}) · 安装 Plugin 失败错误信息`,
+      `本错误信息由 [dsh-plugin-hub](${GITHUB_URL}) 插件中心的安装程序自动生成，随本次安装失败一并提交。`,
+      `- 使用的安装命令（官方默认安装方式）：\`dsh plugin${env?.profile ? ` --profile ${env.profile}` : ''} add github:${repo}\``,
+      `- 执行结果：安装失败，未能安装该插件。`,
+      // [packaging] 场景：向作者说明官方默认安装方式具体是什么，请其按该方式适配（提交构建产物或提供 prepare 脚本）
+      ...(/\[packaging\]/i.test(message)
+        ? [
+          '',
+          '## 官方默认安装方式',
+          'DSH 生态的官方默认安装方式是 `dsh plugin add github:owner/repo`（git 直装）：插件仓库需提交构建产物，或在 package.json 提供 `prepare` 脚本让 pnpm 安装时自动构建。当前插件两者皆不具备，因此无法按官方方式安装。',
+        ]
+        : []),
+      '',
+      '## Environment',
+      `- Plugin: \`${repo}\``,
+      // 宿主机器环境快照：便于作者本地复现；某字段缺失时如实写 unknown，不编造
+      ...(env
+        ? [
+          `- DSH: ${env.dshVersion ? `v${env.dshVersion}` : 'unknown'}`,
+          `- Plugin Hub: v${PLUGIN_VERSION}`,
+          `- Node: ${env.nodeVersion}`,
+          `- OS: ${env.platform} ${env.arch} (${env.release})`,
+          `- Profile: \`${env.profile}\``,
+          `- DSH Home: \`${env.dshHome}\``,
+        ]
+        : []),
+      // 该插件在插件中心的收录位置（详情页链接）
+      `- Catalog: [${pluginSiteUrl(repo)}](${pluginSiteUrl(repo)})`,
+      '',
+      '## Error (core)',
+      '',
+      '```',
+      // 核心错误收集器：只挑关键行（错误代码/构建失败/退出信息），去重截断，URL 才不至于超长
+      summarizeError(message, coreChars),
+      '```',
+      '',
+      '---',
+      // 底部署名：报错来自内置在 DeepSeek Harness 里的 dsh-plugin-hub 安装程序
+      `This error was produced by the [dsh-plugin-hub](${GITHUB_URL}) installer bundled with DeepSeek Harness.`,
+    ].join('\n')
+    return `https://github.com/${repo}/issues/new?title=${encodeURIComponent(title)}&body=${encodeURIComponent(body)}`
+  }
+  // GitHub 请求行上限 8192 字节：先用宽松预算（最多 ~5K 核心错误）构建，超长再逐档缩小，保证最终 URL 不超限
+  const MAX_URL_CHARS = 7600
+  let url = build(MAX_CORE_CHARS)
+  if (url.length > MAX_URL_CHARS) {
+    for (const budget of [4000, 2500, 1400, 800, 400]) {
+      url = build(budget)
+      if (url.length <= MAX_URL_CHARS) break
+    }
+  }
+  return url
+}
+
+export const CATEGORY_ORDER = [
+  'interface', 'session', 'memory', 'tools', 'agent', 'workflow',
+  'integration', 'model', 'dev', 'knowledge', 'fun',
+]
+
+/** 分类标签按界面语言取词；未知 key 原样返回。 */
+export function categoryLabel(
+  map: Record<string, { zh: string; en: string }>,
+  key: string,
+  lang: LocaleId,
+): string {
+  return map[key]?.[lang] ?? key
+}
+
+/**
+ * 归一化在线 API（dsh-plugin.org/api/plugins.{lang}.json）返回的短 key 结构
+ * （s/o/n/vr/c/t/f/d/r/v/u/a/sg/fk），统一为 HubPlugin，保证渲染逻辑只认一种结构。
+ */
+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: typeof raw.r === 'string' ? { repo: raw.r } : 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
+}
+
+export const CATEGORY_LABELS: Record<string, { zh: string; en: string }> = {
+  interface: { zh: '界面与体验', en: 'UI & Experience' },
+  session: { zh: '会话与消息', en: 'Sessions & Messages' },
+  memory: { zh: '记忆与上下文', en: 'Memory & Context' },
+  tools: { zh: '工具与能力', en: 'Tools & Capabilities' },
+  agent: { zh: '技能与智能体', en: 'Skills & Agents' },
+  workflow: { zh: '工作流与自动化', en: 'Workflow & Automation' },
+  integration: { zh: '集成与连接', en: 'Integrations & Connections' },
+  model: { zh: '模型与推理', en: 'Models & Reasoning' },
+  dev: { zh: '开发与运维', en: 'Development & Operations' },
+  knowledge: { zh: '数据与知识', en: 'Data & Knowledge' },
+  fun: { zh: '娱乐', en: 'Entertainment' },
+}
+
+/** 分类 Tab 的紧凑标签（英文模式空间受限时使用）。 */
+export const CATEGORY_SHORT_LABELS: Record<string, { zh: string; en: string }> = {
+  interface: { zh: '界面体验', en: 'UI Exp' },
+  session: { zh: '会话消息', en: 'Sessions' },
+  memory: { zh: '记忆上下文', en: 'Memory' },
+  tools: { zh: '工具能力', en: 'Tools' },
+  agent: { zh: '技能智能体', en: 'Agents' },
+  workflow: { zh: '工作流', en: 'Workflow' },
+  integration: { zh: '集成连接', en: 'Integrations' },
+  model: { zh: '模型推理', en: 'Models' },
+  dev: { zh: '开发运维', en: 'Dev' },
+  knowledge: { zh: '数据知识', en: 'Knowledge' },
+  fun: { zh: '娱乐', en: 'Fun' },
+}
+
+export const SORTS = ['sortStars', 'sortForks', 'sortUpdated', 'sortNewest'] as const
+export type SortKey = (typeof SORTS)[number]

package/src/client/lib/env.ts

@@ -0,0 +1,16 @@
+/**
+ * One-shot host environment snapshot for bug reports. Fetched lazily and
+ * cached at module level: issue URLs embed this info, and the environment
+ * does not change during a session. A failed fetch degrades to null so the
+ * issue links still work — they just ship without the environment block.
+ */
+import type { EnvInfo } from '../types.ts'
+
+let envPromise: Promise<EnvInfo | null> | null = null
+
+export function getEnv(): Promise<EnvInfo | null> {
+  envPromise ??= fetch('/dsh-plugin-hub/env', { cache: 'no-store' })
+    .then((res) => (res.ok ? (res.json() as Promise<EnvInfo>) : null))
+    .catch(() => null)
+  return envPromise
+}