dsh-plugin-manager-companion 0.1.0

package/dist/settings.js

@@ -0,0 +1,263 @@
+/**
+ * 本插件的配置面。
+ *
+ * 归属：A 类·重写（新代码；旧仓库把配置散在 profile 文件与 market 缓存里）。
+ * 官方复用：ctx.settings（SettingsProvider）—— 注册一个命名空间，由官方负责
+ *   校验、落盘、修订号与观察。
+ * 前提检查：用户明确要求"无需手动编辑配置文件"。官方 settings 服务正是这条
+ *   要求的原生实现；自己写 YAML 既违背要求也与官方并发写同一文件。
+ *
+ * 配置只描述**本插件自己的行为**，绝不描述环境状态：环境状态是事实，读出来
+ * 即可，不该由用户配置。
+ */
+import z from '@deepseek-ai/schemastery';
+/** 本插件在官方 settings 里的命名空间（小写连字符，官方校验）。 */
+export const SETTINGS_NAMESPACE = 'plugin-manager-companion';
+/**
+ * 试装配置的默认值。
+ *
+ * 单独一份（而不是只有 DEFAULT_CONFIG.trial）：CompanionConfig.trial 是可选字段，
+ * 类型上它可能是 undefined；读配置的人都该拿这一份，不该拿"可能是 undefined 的默认值"。
+ */
+export const DEFAULT_TRIAL_CONFIG = {
+    // 试装默认关闭：它会在用户机器上真实装包并执行对方代码（DESIGN §5.2），必须显式开启。
+    enabled: false,
+    depth: 'auto',
+    baseline: true,
+    allowNetwork: true,
+    onFailure: 'block',
+    autoCleanup: true,
+    retentionDays: 14,
+    maxKept: 0,
+};
+/** 升级配置的默认值（单独一份：CompanionConfig.upgrade 是可选字段）。 */
+export const DEFAULT_UPGRADE_CONFIG = {
+    autoCheck: true,
+    interval: 'daily',
+    registryUrl: '',
+};
+/** 默认配置：诊断全开、质量门拦截、市场启用、试装关闭、升级检查每天一次。 */
+export const DEFAULT_CONFIG = {
+    diagnostics: {
+        dependency: true,
+        composition: true,
+        runtime: true,
+        consistency: true,
+        // 生态层要联网，默认关闭——诊断页在用户显式开启后才访问网络。
+        ecosystem: false,
+    },
+    qualityGate: { enabled: true, mode: 'block', allowlist: [] },
+    marketplace: { enabled: true, cacheTtlMinutes: 1440, timeoutMs: 15_000, indexUrl: '' },
+    trial: { ...DEFAULT_TRIAL_CONFIG },
+    upgrade: { ...DEFAULT_UPGRADE_CONFIG },
+};
+/** 试装的告知事实（口径：Linux x64 / Node 24 / DSH 0.1.6-alpha.2，headless 验证启动）。 */
+export const TRIAL_DISCLOSURE = {
+    executesCandidateCode: true,
+    peakMemoryMiB: 161,
+    measurement: '实测口径：headless 验证启动的 maxrss 峰值 161 MiB，'
+        + '在 Linux x64 / Node 24 / DSH 0.1.6-alpha.2 上量得；候选包自带的安装脚本会真的在你机器上执行。',
+};
+/**
+ * 官方 settings 的 schema。
+ *
+ * `.default()` 逐项给出，使旧配置文件在新增字段后仍能解析；未知字段由
+ * schemastery 丢弃，不会因为未来删字段而炸掉整份配置。
+ */
+export const ConfigSchema = z.object({
+    diagnostics: z.object({
+        dependency: z.boolean().default(true),
+        composition: z.boolean().default(true),
+        runtime: z.boolean().default(true),
+        consistency: z.boolean().default(true),
+        ecosystem: z.boolean().default(false),
+    }).default({ ...DEFAULT_CONFIG.diagnostics }),
+    qualityGate: z.object({
+        enabled: z.boolean().default(true),
+        mode: z.union([z.const('block'), z.const('warn')]).default('block'),
+        allowlist: z.array(z.string()).default([]),
+    }).default({
+        enabled: DEFAULT_CONFIG.qualityGate.enabled,
+        mode: DEFAULT_CONFIG.qualityGate.mode,
+        allowlist: [...DEFAULT_CONFIG.qualityGate.allowlist],
+    }),
+    marketplace: z.object({
+        enabled: z.boolean().default(true),
+        cacheTtlMinutes: z.number().min(1).max(10_080).default(1440),
+        timeoutMs: z.number().min(1_000).max(120_000).default(15_000),
+        indexUrl: z.string().default(''),
+    }).default({ ...DEFAULT_CONFIG.marketplace }),
+    // 注意：maxKept 用 0 = 不限而**不用 null**。实测（schemastery 3.18.2）：
+    // 字段 schema 里含 z.const(null) 时，用户配置只写了别的字段，这个键会被整个丢掉
+    // （值变成 undefined，不是 null）——即"用户在设置页看不到的一个洞"。
+    // 也正因如此，读配置一律走 effectiveTrialConfig()：schema 的默认值不是运行期保证。
+    trial: z.object({
+        enabled: z.boolean().default(false),
+        depth: z.union([z.const('auto'), z.const('shallow'), z.const('full')]).default('auto'),
+        baseline: z.boolean().default(true),
+        allowNetwork: z.boolean().default(true),
+        onFailure: z.union([z.const('block'), z.const('warn')]).default('block'),
+        autoCleanup: z.boolean().default(true),
+        retentionDays: z.natural().min(1).max(3_650).default(14),
+        maxKept: z.natural().max(1_000).default(0),
+    }).default({ ...DEFAULT_TRIAL_CONFIG }),
+    upgrade: z.object({
+        autoCheck: z.boolean().default(true),
+        interval: z.union([z.const('session'), z.const('6h'), z.const('daily'), z.const('manual')]).default('daily'),
+        registryUrl: z.string().default(''),
+    }).default({ ...DEFAULT_UPGRADE_CONFIG }),
+});
+/**
+ * 读试装配置：缺字段、字段类型不对、越界一律回落到默认值。
+ *
+ * 为什么需要它（不是多此一举）：schema 的默认值只在"官方 settings 解析过这份配置"时成立。
+ * 事实是配置对象还会从别处来——测试与工具自己拼的 CompanionConfig 字面量、以及未来
+ * schemastery 行为变化（本文件里 maxKept 那条注释就是一个实测例子）。试装是**会写磁盘、会起进程**
+ * 的动作，任何一个字段读到 undefined 都必须变成"用安全默认值"，不能变成"意外地开启/强制浅快照"。
+ *
+ * @param config - 任意形状的配置片段。
+ * @returns 补齐后的试装配置（全部字段都有确定值）。
+ */
+export function effectiveTrialConfig(config) {
+    const fallback = DEFAULT_TRIAL_CONFIG;
+    const raw = (config?.trial ?? {});
+    const bool = (value, byDefault) => typeof value === 'boolean' ? value : byDefault;
+    const count = (value, byDefault, min, max) => {
+        const parsed = typeof value === 'number' && Number.isFinite(value) ? Math.trunc(value) : byDefault;
+        return Math.min(max, Math.max(min, parsed));
+    };
+    return {
+        enabled: bool(raw.enabled, fallback.enabled),
+        depth: raw.depth === 'shallow' || raw.depth === 'full' ? raw.depth : 'auto',
+        baseline: bool(raw.baseline, fallback.baseline),
+        allowNetwork: bool(raw.allowNetwork, fallback.allowNetwork),
+        onFailure: raw.onFailure === 'warn' ? 'warn' : 'block',
+        autoCleanup: bool(raw.autoCleanup, fallback.autoCleanup),
+        retentionDays: count(raw.retentionDays, fallback.retentionDays, 1, 3_650),
+        maxKept: count(raw.maxKept, fallback.maxKept, 0, 1_000),
+    };
+}
+/**
+ * 检查间隔对应的毫秒数；`null` = 仅手动（永不自动检查）。
+ *
+ * 纯函数、单一事实来源：引擎与界面用它算"要不要查"，避免两处各写一份间隔表而漂移。
+ *
+ * @param interval - 配置里的间隔。
+ * @returns 毫秒；仅手动时为 null。
+ */
+export function upgradeIntervalMs(interval) {
+    switch (interval) {
+        case 'session': return 0;
+        case '6h': return 6 * 60 * 60 * 1000;
+        case 'manual': return null;
+        default: return 24 * 60 * 60 * 1000;
+    }
+}
+/**
+ * 读升级配置：缺字段、类型不对一律回落默认值（与 effectiveTrialConfig 同一纪律：
+ * schema 的默认值只在官方 settings 解析过那份配置时成立；这两个字段决定要不要出网）。
+ *
+ * @param config - 任意形状的配置片段。
+ * @returns 补齐后的升级配置。
+ */
+export function effectiveUpgradeConfig(config) {
+    const fallback = DEFAULT_UPGRADE_CONFIG;
+    const raw = (config?.upgrade ?? {});
+    const interval = raw.interval === 'session' || raw.interval === '6h' || raw.interval === 'manual'
+        ? raw.interval
+        : 'daily';
+    return {
+        autoCheck: typeof raw.autoCheck === 'boolean' ? raw.autoCheck : fallback.autoCheck,
+        interval,
+        registryUrl: typeof raw.registryUrl === 'string' ? raw.registryUrl : fallback.registryUrl,
+    };
+}
+/** 最近一次配置降级的事实；null = 配置面正常。 */
+let lastConfigDegradation = null;
+/**
+ * 配置面的当前状态。
+ *
+ * 为什么是模块级：装配层用 ctx.inject(['settings'], …) 在 settings 就绪时才注册，
+ * 命名空间冲突发生在那个回调里；而这件事实必须能被 probeOfficialCapabilities 读到、
+ * 进而出现在用户可见的 capabilities 里（不能只在日志里）。
+ *
+ * @returns 当前配置面状态。
+ */
+export function configState() {
+    if (lastConfigDegradation === null)
+        return { writable: true, reason: null, detail: null };
+    return { writable: false, reason: lastConfigDegradation.reason, detail: lastConfigDegradation.detail };
+}
+/**
+ * 记录一次配置降级：写日志 + 留给 capabilities 呈现。
+ *
+ * @param ctx - host 上下文（用于日志）。
+ * @param reason - 稳定原因码。
+ * @param detail - 面向用户的原因。
+ */
+function noteConfigDegraded(ctx, reason, detail) {
+    lastConfigDegradation = { reason, detail };
+    ctx.logger?.warn?.('plugin-manager-companion: ' + detail);
+}
+/** 错误消息（本地小工具）。 */
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * 官方 settings 服务尚不可用时的**只读**降级句柄。
+ *
+ * 为什么需要它：settings 服务可能**晚于**本插件装配（服务挂载顺序不保证），
+ * 而配置句柄会被各模块长期持有。装配层先拿这个，等服务出现再换成真句柄。
+ *
+ * `update` 刻意**抛错**而不是静默返回默认值——静默丢写是最糟的失败形态：
+ * 用户改了配置、界面回显成功、实际什么都没发生（实测踩过，见 CONTEXT.md）。
+ *
+ * @returns 只读句柄；任何写入尝试都抛出可读错误。
+ */
+export function fallbackConfigHandle() {
+    return {
+        current: () => DEFAULT_CONFIG,
+        watch: () => () => { },
+        update: () => Promise.reject(new Error('配置服务（settings）尚未就绪；写入被拒绝而不是丢弃——请稍后重试')),
+    };
+}
+/**
+ * 注册本插件的 settings 命名空间。
+ *
+ * 官方 `register` 在命名空间已被占用时**抛错**。这里的立场是"任何宿主都能加载、
+ * 缺能力就如实降级"：冲突时退回只读的默认配置句柄，并把事实登记给 capabilities，
+ * 而不是让整个插件装配失败（那会让用户看到一个装不上、也没有可读原因的插件）。
+ *
+ * 不静默：降级句柄的 `update` 照旧**抛错**而不是丢写入，且 configState() 会让
+ * capabilities.missing 里出现一条"配置不可写"的说明。
+ *
+ * @param ctx - 本插件的 host 上下文。
+ * @returns 配置句柄；settings 不可用或命名空间冲突时返回只读的默认配置句柄。
+ */
+export function registerConfig(ctx) {
+    const settings = ctx.get('settings');
+    if (settings === undefined) {
+        noteConfigDegraded(ctx, 'settings-missing', 'settings 服务未就绪，配置降级为只读——装配层应改用 ctx.inject(["settings"])');
+        return fallbackConfigHandle();
+    }
+    let scope;
+    try {
+        scope = settings.register(SETTINGS_NAMESPACE, ConfigSchema);
+    }
+    catch (error) {
+        // 命名空间已被占用（同进程内另一个本插件实例）：不抛穿装配，退回只读句柄并登记事实。
+        noteConfigDegraded(ctx, 'namespace-conflict', 'settings 命名空间 "' + SETTINGS_NAMESPACE + '" 已被占用，配置降级为只读（正在用默认值）：'
+            + messageOf(error));
+        return fallbackConfigHandle();
+    }
+    // 注册成功：清掉可能残留的降级事实（例如重试装配）。
+    lastConfigDegradation = null;
+    return {
+        current: () => scope.get(),
+        watch: (listener) => scope.watch((next) => { listener(next); }),
+        update: async (patch) => {
+            await scope.update(patch);
+            return scope.get();
+        },
+    };
+}

package/dist/tags.d.ts

@@ -0,0 +1,119 @@
+/**
+ * tags.ts — 市场徽标模型与详情数据（纯函数，无 fs / 无 ctx / 无网络）。
+ *
+ * 归属：B 类·参考重写（旧 src/tags.ts 仅作意图参考，未复制代码）。
+ * 旧实现参考：dsh-web-plugin-manager/src/tags.ts（理解意图用，未复制代码）——它解决的是"卡片上的标签
+ *   按载荷顺序临时拼、顺序随实现漂移"；本模块继续承担"一处有序、去重的唯一来源"。
+ * 官方复用：无（官方没有市场概念）。
+ * 前提检查：**旧实现在这里被政策整体取代**（docs/private/market-tags-policy.md，task-45 全量 13,998 条实测）：
+ *   1) 旧实现的 status / verification / security 三类标签**从来没有数据源**（没有上游字段可映射）；
+ *   2) 政策实测出上游真正有值且值得展示的是另外几件事：风险（risk_tier，100% 覆盖）、可装性
+ *      （installable，12.4%）、编辑推荐（market_tags 的 community-pick，10.2%）、归档（archived，0.6%）、
+ *      分类（100%）、功能主题（过滤泛化词后 57.5% 有值）；
+ *   3) 去重必须**跨来源按归一化值**做：实测 499 条（3.6%）把自己的 category 又写进 topics
+ *      （liustack/modlens=vision、MemTensor/MemOS=memory…），只做来源内部去重挡不住这种"同一个词出现两次"。
+ *
+ * 顺序契约（重要性从高到低，渲染方按数组顺序画、绝不再排序）：
+ *   risk → caution → manual → pick → archived → category → topic
+ * 这份顺序就是政策 §3.2 的优先级；{@link BADGE_PRIORITY} 是它的机器可读形式。
+ */
+import type { MarketInstallable, MarketRiskFlag, MarketRiskTier } from './types.ts';
+/** 徽标类别（按 priority 排列的顺序见 {@link BADGE_PRIORITY}）。 */
+export type MarketTagKind = 
+/** 上游风险等级 = risk（danger）。 */
+'risk'
+/** 上游风险等级 = caution（warning）。 */
+ | 'caution'
+/** 上游标记需手动安装（installable = manual）。 */
+ | 'manual'
+/** 上游编辑推荐（market_tags 含 community-pick）。 */
+ | 'pick'
+/** 仓库已归档（archived）。 */
+ | 'archived'
+/** 上游分类（兜底槽）。 */
+ | 'category'
+/** 功能主题（最低优先级，最多 2 个）。 */
+ | 'topic';
+/** 卡片徽标的优先级契约（政策 §3.2）。 */
+export declare const BADGE_PRIORITY: readonly MarketTagKind[];
+/** 与语言无关的语义色调；client 映射到官方 --dsw-* token。 */
+export type MarketTagTone = 'neutral' | 'success' | 'warning' | 'danger';
+/** 一个展示徽标。`value` 是原始值或数据本身，由 client 侧字典决定文案。 */
+export interface MarketTag {
+    readonly kind: MarketTagKind;
+    readonly value: string;
+    readonly tone: MarketTagTone;
+    /** 完整的、未截断的文本（title 属性用）。 */
+    readonly title?: string;
+}
+/** 卡片徽标的默认上限：政策 §4「只能显示 3 个」的最小集合就是取前三个。 */
+export declare const TAG_SLOT_LIMIT = 3;
+/** 功能主题的默认上限：政策 §3.5（泛化词占 61.3%，只能当兜底槽）。 */
+export declare const TOPIC_SLOT_LIMIT = 2;
+/**
+ * 徽标构建器读取的字段（刻意保持窄接口）。
+ *
+ * 全部来自上游索引，**原样使用**：本模块不把 risk_flags 折算成分数、不把 stars 折算成质量，
+ * 也不发明"可疑/推荐"这类上游没有的结论。
+ */
+export interface MarketTagSource {
+    readonly category?: string;
+    readonly installable?: MarketInstallable;
+    readonly riskTier?: MarketRiskTier;
+    readonly marketTags?: readonly string[];
+    readonly archived?: boolean;
+    readonly topics?: readonly string[];
+}
+/**
+ * 构建一个条目的徽标列表（**按政策**：优先级取前 N、跨来源按归一化值去重）。
+ *
+ * @param item - 上游字段。
+ * @param options - slotLimit（卡片默认 3）与 topicLimit（默认 2）。
+ * @returns 按 {@link BADGE_PRIORITY} 排好的徽标；调用方**不得**再排序。
+ */
+export declare function buildMarketTags(item: MarketTagSource, options?: {
+    readonly slotLimit?: number;
+    readonly topicLimit?: number;
+}): MarketTag[];
+/** 徽标的稳定 key（React key / 去重标识用）。 */
+export declare function marketTagKey(tag: MarketTag): string;
+/** 详情区的一项（政策 §3.1 的八项）。`key` 由 client 侧字典翻译，本模块不产出文案。 */
+export interface MarketDetailItem {
+    /** 稳定 key，client 据此取字典（category / topics / riskFlags / verified / license / npm / version / kind）。 */
+    readonly key: string;
+    /** 原始值（未本地化）：分类 id、主题列表、flag 摘要、校验证据串、许可证 id、包名、版本、形态。 */
+    readonly value: string;
+    /** 可点外链（只可能是上游给的 https 报告地址）。 */
+    readonly href?: string;
+    readonly tone: MarketTagTone;
+}
+/** 详情构建器读取的字段。 */
+export interface MarketDetailSource extends MarketTagSource {
+    readonly kind?: string;
+    readonly license?: string;
+    readonly packageName?: string;
+    readonly latestVersion?: string;
+    readonly riskFlags?: readonly MarketRiskFlag[];
+    readonly reportUrl?: string;
+    readonly verifiedBy?: string;
+    readonly verifiedAt?: string;
+}
+/**
+ * 构建详情区的条目（政策 §3.1：分类、功能主题、风险明细、验证证据（含报告外链）、许可证、npm 包名、版本、形态）。
+ *
+ * 顺序是"身份 → 上游结论 → 证据 → 元数据"：用户从上往下读能先看到"这是什么"，再看到"上游怎么判的"。
+ * 空值一律不产出条目（详情区不留空行）。
+ *
+ * @param item - 上游字段 + 少量本地派生字段（kind / packageName / latestVersion）。
+ * @returns 详情项；调用方按 key 取字典文案。
+ */
+export declare function buildMarketDetail(item: MarketDetailSource): MarketDetailItem[];
+/**
+ * 统计每个上游分类的条目数，返回 JSON-safe 的 Record（写进 MarketplaceResult.categories）。
+ *
+ * key 的插入顺序 = 分类首次出现的顺序，同一份 listing 永远产出同一份对象。
+ * 分类为空的条目**不计入**任何桶——把"没分类"混进某个分类会让筛选器说谎。
+ */
+export declare function categoryCounts(items: readonly {
+    readonly category?: string;
+}[]): Record<string, number>;

package/dist/tags.js

@@ -0,0 +1,166 @@
+/**
+ * tags.ts — 市场徽标模型与详情数据（纯函数，无 fs / 无 ctx / 无网络）。
+ *
+ * 归属：B 类·参考重写（旧 src/tags.ts 仅作意图参考，未复制代码）。
+ * 旧实现参考：dsh-web-plugin-manager/src/tags.ts（理解意图用，未复制代码）——它解决的是"卡片上的标签
+ *   按载荷顺序临时拼、顺序随实现漂移"；本模块继续承担"一处有序、去重的唯一来源"。
+ * 官方复用：无（官方没有市场概念）。
+ * 前提检查：**旧实现在这里被政策整体取代**（docs/private/market-tags-policy.md，task-45 全量 13,998 条实测）：
+ *   1) 旧实现的 status / verification / security 三类标签**从来没有数据源**（没有上游字段可映射）；
+ *   2) 政策实测出上游真正有值且值得展示的是另外几件事：风险（risk_tier，100% 覆盖）、可装性
+ *      （installable，12.4%）、编辑推荐（market_tags 的 community-pick，10.2%）、归档（archived，0.6%）、
+ *      分类（100%）、功能主题（过滤泛化词后 57.5% 有值）；
+ *   3) 去重必须**跨来源按归一化值**做：实测 499 条（3.6%）把自己的 category 又写进 topics
+ *      （liustack/modlens=vision、MemTensor/MemOS=memory…），只做来源内部去重挡不住这种"同一个词出现两次"。
+ *
+ * 顺序契约（重要性从高到低，渲染方按数组顺序画、绝不再排序）：
+ *   risk → caution → manual → pick → archived → category → topic
+ * 这份顺序就是政策 §3.2 的优先级；{@link BADGE_PRIORITY} 是它的机器可读形式。
+ */
+/** 卡片徽标的优先级契约（政策 §3.2）。 */
+export const BADGE_PRIORITY = ['risk', 'caution', 'manual', 'pick', 'archived', 'category', 'topic'];
+/** 卡片徽标的默认上限：政策 §4「只能显示 3 个」的最小集合就是取前三个。 */
+export const TAG_SLOT_LIMIT = 3;
+/** 功能主题的默认上限：政策 §3.5（泛化词占 61.3%，只能当兜底槽）。 */
+export const TOPIC_SLOT_LIMIT = 2;
+/** 上游生态泛化主题词（与 registry.ts 的 ECO_GENERIC_TOPICS 同一判据：这个词能否区分两个插件）。 */
+const ECO_GENERIC_TOPICS = new Set([
+    'ai', 'llm', 'agent', 'agents', 'cli', 'cordis', 'cordis-plugin', 'deepseek', 'deepseek-harness',
+    'dsh', 'dsh-plugin', 'dsh-plugins', 'gui', 'javascript', 'plugin', 'plugins', 'python', 'react',
+    'skill', 'skills', 'tool', 'tools', 'tui', 'typescript', 'ui', 'web', 'web-ui',
+]);
+/** 上游收录标记里的编辑推荐。 */
+const COMMUNITY_PICK = 'community-pick';
+/**
+ * 构建一个条目的徽标列表（**按政策**：优先级取前 N、跨来源按归一化值去重）。
+ *
+ * @param item - 上游字段。
+ * @param options - slotLimit（卡片默认 3）与 topicLimit（默认 2）。
+ * @returns 按 {@link BADGE_PRIORITY} 排好的徽标；调用方**不得**再排序。
+ */
+export function buildMarketTags(item, options = {}) {
+    const slotLimit = Math.max(0, options.slotLimit ?? TAG_SLOT_LIMIT);
+    const topicLimit = Math.max(0, options.topicLimit ?? TOPIC_SLOT_LIMIT);
+    const out = [];
+    const seen = new Set();
+    /** 归一化值去重：跨来源（分类与主题同名时只留先出现的那次，即优先级更高的来源）。 */
+    const push = (tag) => {
+        if (out.length >= slotLimit)
+            return;
+        const key = tag.value.trim().toLowerCase();
+        if (key.length === 0 || seen.has(key))
+            return;
+        seen.add(key);
+        out.push(tag);
+    };
+    if (item.riskTier === 'risk')
+        push({ kind: 'risk', value: 'risk', tone: 'danger' });
+    else if (item.riskTier === 'caution')
+        push({ kind: 'caution', value: 'caution', tone: 'warning' });
+    if (item.installable === 'manual')
+        push({ kind: 'manual', value: 'manual', tone: 'neutral' });
+    if ((item.marketTags ?? []).some((tag) => tag.trim().toLowerCase() === COMMUNITY_PICK)) {
+        push({ kind: 'pick', value: COMMUNITY_PICK, tone: 'success' });
+    }
+    if (item.archived === true)
+        push({ kind: 'archived', value: 'archived', tone: 'warning' });
+    const category = item.category?.trim();
+    if (category !== undefined && category.length > 0)
+        push({ kind: 'category', value: category, tone: 'neutral' });
+    let topics = 0;
+    for (const raw of item.topics ?? []) {
+        if (topics >= topicLimit)
+            break;
+        const value = String(raw).trim();
+        if (value.length === 0 || ECO_GENERIC_TOPICS.has(value.toLowerCase()))
+            continue;
+        const before = out.length;
+        push({ kind: 'topic', value, tone: 'neutral' });
+        if (out.length > before)
+            topics += 1;
+    }
+    return out;
+}
+/** 徽标的稳定 key（React key / 去重标识用）。 */
+export function marketTagKey(tag) {
+    return tag.kind + ':' + tag.value;
+}
+/** 详情里风险明细的展示上限（与 registry 的透传上限一致）。 */
+const DETAIL_FLAG_LIMIT = 12;
+/** 详情里功能主题的展示上限（政策 §3.1：最多 8）。 */
+const DETAIL_TOPIC_LIMIT = 8;
+/**
+ * 构建详情区的条目（政策 §3.1：分类、功能主题、风险明细、验证证据（含报告外链）、许可证、npm 包名、版本、形态）。
+ *
+ * 顺序是"身份 → 上游结论 → 证据 → 元数据"：用户从上往下读能先看到"这是什么"，再看到"上游怎么判的"。
+ * 空值一律不产出条目（详情区不留空行）。
+ *
+ * @param item - 上游字段 + 少量本地派生字段（kind / packageName / latestVersion）。
+ * @returns 详情项；调用方按 key 取字典文案。
+ */
+export function buildMarketDetail(item) {
+    const out = [];
+    const kind = item.kind?.trim();
+    if (kind !== undefined && kind.length > 0)
+        out.push({ key: 'kind', value: kind, tone: 'neutral' });
+    const category = item.category?.trim();
+    if (category !== undefined && category.length > 0)
+        out.push({ key: 'category', value: category, tone: 'neutral' });
+    const topics = (item.topics ?? [])
+        .map((topic) => String(topic).trim())
+        .filter((topic) => topic.length > 0 && !ECO_GENERIC_TOPICS.has(topic.toLowerCase()))
+        .slice(0, DETAIL_TOPIC_LIMIT);
+    if (topics.length > 0)
+        out.push({ key: 'topics', value: topics.join(', '), tone: 'neutral' });
+    if (item.riskTier !== undefined && item.riskTier !== 'safe') {
+        out.push({ key: 'riskTier', value: item.riskTier, tone: item.riskTier === 'risk' ? 'danger' : 'warning' });
+        const flags = (item.riskFlags ?? []).slice(0, DETAIL_FLAG_LIMIT);
+        if (flags.length > 0) {
+            out.push({
+                key: 'riskFlags',
+                value: flags.map((flag) => flag.severity.length > 0 ? flag.id + '(' + flag.severity + ')' : flag.id).join(', '),
+                tone: item.riskTier === 'risk' ? 'danger' : 'warning',
+            });
+        }
+    }
+    if (item.installable === 'manual')
+        out.push({ key: 'manual', value: 'manual', tone: 'neutral' });
+    if (item.archived === true)
+        out.push({ key: 'archived', value: 'archived', tone: 'warning' });
+    // 独立校验证据：谁验的 + 何时验的 + 报告外链，三者绑成一条（政策 §3.3：不写成含糊的"已验证"）。
+    if (item.verifiedBy !== undefined || item.verifiedAt !== undefined) {
+        const parts = [item.verifiedBy, item.verifiedAt].filter((part) => part !== undefined && part.length > 0);
+        out.push({
+            key: 'verified',
+            value: parts.join(' · '),
+            tone: 'success',
+            ...(item.reportUrl === undefined ? {} : { href: item.reportUrl }),
+        });
+    }
+    const license = item.license?.trim();
+    if (license !== undefined && license.length > 0)
+        out.push({ key: 'license', value: license, tone: 'neutral' });
+    const packageName = item.packageName?.trim();
+    if (packageName !== undefined && packageName.length > 0)
+        out.push({ key: 'npm', value: packageName, tone: 'neutral' });
+    const version = item.latestVersion?.trim();
+    if (version !== undefined && version.length > 0)
+        out.push({ key: 'version', value: version, tone: 'neutral' });
+    return out;
+}
+/**
+ * 统计每个上游分类的条目数，返回 JSON-safe 的 Record（写进 MarketplaceResult.categories）。
+ *
+ * key 的插入顺序 = 分类首次出现的顺序，同一份 listing 永远产出同一份对象。
+ * 分类为空的条目**不计入**任何桶——把"没分类"混进某个分类会让筛选器说谎。
+ */
+export function categoryCounts(items) {
+    const counts = {};
+    for (const item of items) {
+        const id = item.category?.trim();
+        if (id === undefined || id.length === 0)
+            continue;
+        counts[id] = (counts[id] ?? 0) + 1;
+    }
+    return counts;
+}