dsh-m 0.4.2 → 0.5.0

package/lib/core/community-adapter.js

@@ -0,0 +1,181 @@
+/**
+ * 目录适配层（M1 Task 4 / DESIGN.md §2.5「目录适配层」/ Q40 / Q43）：
+ * 原生条目（宽松校验的字段袋）→ 收录条目 CommunityEntry。
+ * 条目层宽松语义（Q43）：单条不合格跳过 + 计数（skippedDirty / skippedSubpathNoNpm），不整份拒绝。
+ * id 合成：小写 `owner--name`，非法字符折叠为 `-`，超 64 截断加哈希尾缀，适配层内冲突追加序号。
+ * 旁路字段（stars/downloads/capabilities/capabilityRedLines/screenshots）不进 RegistryEntry
+ * 本体，仅随 CommunityEntry 透传、由市场层展示（Q44：卡片不打标，详情折叠区才展示）。
+ */
+import { createHash } from 'node:crypto';
+/** 与主清单 v1 同款约束（registry.ts MAX_ID / ID_RE / NPM_RE / GITHUB_RE 同语义，锚定不漂移）。 */
+const MAX_ID = 64;
+const MAX_DESCRIPTION = 500;
+const ID_ILLEGAL_RE = /[^a-z0-9._-]+/g;
+const ID_LEADING_ILLEGAL_RE = /^[._-]+/;
+const NPM_SHAPE_RE = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+const GITHUB_SHAPE_RE = /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/;
+/** 社区开放分类的安全 slug（计划 Task 4 契约；原生值保留不转译，Q40）。 */
+const COMMUNITY_CATEGORY_RE = /^[a-z0-9-]{1,32}$/;
+const HASH_SUFFIX_LEN = 8;
+const TRUNCATED_BODY_LEN = MAX_ID - (HASH_SUFFIX_LEN + 1);
+function isBlank(v) {
+    return typeof v !== 'string' || v.trim() === '';
+}
+function strArray(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((x) => typeof x === 'string' && x.trim() !== '');
+}
+function numOrNull(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+/** npm 形状成立（非空字符串且满足 npm 包名形状）→ source: npm。 */
+function npmShape(raw) {
+    if (typeof raw.npm !== 'string')
+        return null;
+    const v = raw.npm.trim();
+    return NPM_SHAPE_RE.test(v) ? v : null;
+}
+/** url → `owner/repo`（仅接受 github.com http(s) 链接；形状须满足 GITHUB_SHAPE_RE）。 */
+function githubFromUrl(url) {
+    if (typeof url !== 'string')
+        return null;
+    const m = url.match(/^https?:\/\/github\.com\/([^/?#\s]+)\/([^/?#\s]+)/i);
+    if (!m)
+        return null;
+    const candidate = `${m[1]}/${m[2]}`;
+    return GITHUB_SHAPE_RE.test(candidate) ? candidate : null;
+}
+/** 子包形态（Q43）：monorepo 子路径（url 含 `/tree/`）或上游 `name` 含 `#` 子包命名。 */
+function isSubpathShape(raw) {
+    const urlHasTree = typeof raw.url === 'string' && raw.url.includes('/tree/');
+    const nameHasHash = typeof raw.name === 'string' && raw.name.includes('#');
+    return urlHasTree || nameHasHash;
+}
+/** id 合成：小写 owner--name → 非法字符折叠 `-` → 剥前导非法段 → 超 64 截断加 sha256 尾缀。 */
+function synthesizeId(owner, name) {
+    let id = `${owner}--${name}`.toLowerCase().replace(ID_ILLEGAL_RE, '-').replace(ID_LEADING_ILLEGAL_RE, '');
+    if (id === '')
+        return '';
+    if (id.length > MAX_ID) {
+        const hash = createHash('sha256').update(id).digest('hex').slice(0, HASH_SUFFIX_LEN);
+        id = `${id.slice(0, TRUNCATED_BODY_LEN)}-${hash}`;
+    }
+    return id;
+}
+/** 适配层内冲突追加序号（-2/-3/…；追加后超长则截主体保序号完整）。 */
+function dedupeId(id, used) {
+    if (!used.has(id)) {
+        used.add(id);
+        return id;
+    }
+    for (let n = 2;; n++) {
+        const suffix = `-${n}`;
+        const candidate = id.length + suffix.length > MAX_ID ? id.slice(0, MAX_ID - suffix.length) + suffix : id + suffix;
+        if (!used.has(candidate)) {
+            used.add(candidate);
+            return candidate;
+        }
+    }
+}
+/**
+ * 适配入口：输入为已过容器校验的 CommunityCatalog（fetch 链产物）。
+ * 每条原生条目按序判定：name/owner/category/description 基础字段 → 子包两态 → 来源归一
+ * （npm 形状 → npm；否则 url → github；皆否跳过）→ id 合成去重。脏条目跳过计数，绝不中断整份。
+ */
+export function adaptCommunityCatalog(catalog) {
+    const entries = [];
+    const warnings = [];
+    const used = new Set();
+    let skippedDirty = 0;
+    let skippedSubpathNoNpm = 0;
+    let fallbackEn = 0;
+    let truncated = 0;
+    for (const raw of catalog.plugins) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            skippedDirty += 1;
+            continue;
+        }
+        if (isBlank(raw.name) || isBlank(raw.owner)) {
+            skippedDirty += 1;
+            continue;
+        }
+        const name = raw.name.trim();
+        const owner = raw.owner.trim();
+        if (typeof raw.category !== 'string' || !COMMUNITY_CATEGORY_RE.test(raw.category)) {
+            skippedDirty += 1;
+            continue;
+        }
+        // description：zh 优先，缺省回退 en；两者皆无 → 脏条目（>500 截断并计数，同 registry MAX_DESCRIPTION 口径）
+        const desc = raw.description;
+        const zh = typeof desc?.zh === 'string' ? desc.zh.trim() : '';
+        const en = typeof desc?.en === 'string' ? desc.en.trim() : '';
+        let description = zh !== '' ? zh : en;
+        if (description === '') {
+            skippedDirty += 1;
+            continue;
+        }
+        if (zh === '')
+            fallbackEn += 1;
+        if (description.length > MAX_DESCRIPTION) {
+            description = description.slice(0, MAX_DESCRIPTION);
+            truncated += 1;
+        }
+        const npm = npmShape(raw);
+        if (npm === null && isSubpathShape(raw)) {
+            // 无 npm 的 monorepo 子包：repo 根不是正确安装目标（Q43），跳过并计数
+            skippedSubpathNoNpm += 1;
+            continue;
+        }
+        let source;
+        let npmName;
+        let github;
+        if (npm !== null) {
+            source = 'npm';
+            npmName = npm;
+        }
+        else {
+            const gh = githubFromUrl(raw.url);
+            if (gh === null) {
+                skippedDirty += 1;
+                continue;
+            }
+            source = 'github';
+            github = gh;
+        }
+        const id = synthesizeId(owner, name);
+        if (id === '') {
+            skippedDirty += 1;
+            continue;
+        }
+        // url → homepage（仅 http(s)；github 源必有 url，npm 源可能缺省）
+        const rawUrl = typeof raw.url === 'string' ? raw.url.trim() : '';
+        const homepage = rawUrl.startsWith('https://') || rawUrl.startsWith('http://') ? rawUrl : undefined;
+        entries.push({
+            id: dedupeId(id, used),
+            name,
+            description,
+            category: raw.category,
+            tags: [],
+            source,
+            ...(npmName !== undefined ? { npm: npmName } : {}),
+            ...(github !== undefined ? { github } : {}),
+            ...(homepage !== undefined ? { homepage } : {}),
+            stars: numOrNull(raw.stars),
+            downloads: numOrNull(raw.downloads),
+            capabilities: strArray(raw.capabilities),
+            capabilityRedLines: strArray(raw.capabilityRedLines),
+            screenshots: strArray(raw.screenshots),
+            descriptionEn: en,
+        });
+    }
+    if (fallbackEn > 0)
+        warnings.push(`zh 描述缺省回退 en：${fallbackEn} 条`);
+    if (truncated > 0)
+        warnings.push(`描述超过 ${MAX_DESCRIPTION} 字符已截断：${truncated} 条`);
+    if (skippedSubpathNoNpm > 0)
+        warnings.push(`无 npm 的子包条目跳过：${skippedSubpathNoNpm} 条`);
+    if (skippedDirty > 0)
+        warnings.push(`脏条目跳过：${skippedDirty} 条（缺 name/owner/category/描述，或来源无法判定）`);
+    return { entries, warnings, skippedDirty, skippedSubpathNoNpm };
+}

package/lib/core/community.js

@@ -0,0 +1,433 @@
+/**
+ * 社区清单（DESIGN.md §2.5 / ADR-0003）：awesome-dsh-plugin 全量目录的只读叠加层。
+ * 容器层（常量/类型/校验/标签）+ 获取链（Task 3：版本探测 → 三线路正文 → 版本缓存）。
+ * 校验语义（Q43）：容器层严格；条目层宽松（适配层跳过计数，见 community-adapter.ts）。
+ * deadline 语义（v8-v10 定稿）：共享 flight 只受自身 30s hard cap 约束；
+ * 调用者 deadline/signal 不进入共享 loader——waiter 在调用层各自 race（本模块只接受
+ * 每调用者的 signal 用于取消「自己的等待」，最后一个 waiter 离开才 abort 共享加载）。
+ */
+import { mkdir, readFile, rm, rename, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative } from 'node:path';
+import { cacheDir } from './env.js';
+import { decodeUtf8Fatal, fetchBytesLimited, describeFetchFailure } from './httpx.js';
+import { isExactVersion, npmLatest } from './versions.js';
+import { communityOutcome } from './market.js';
+export const COMMUNITY_NPM_PACKAGE = 'dsh-plugin-catalog';
+export const MAX_COMMUNITY_BYTES = 32 * 1024 * 1024;
+export const MAX_COMMUNITY_ENTRIES = 30_000;
+export const CATALOG_BODY_TIMEOUT_MS = 15_000;
+export const COMMUNITY_CHAIN_BUDGET_MS = 30_000;
+/**
+ * 上游 23 个分类 id 的全量中文标签（以 fixture `categories` 键为准逐条核对）。
+ * 其中 ui/tools/market 与精选分类同名共享过滤桶、不进筛选栏社区组，标签供详情页等处使用。
+ */
+export const COMMUNITY_KNOWN_CATEGORIES = {
+    agi: 'AGI 架构探索',
+    ui: 'UI 增强',
+    usage: '用量与计费',
+    theme: '主题与外观',
+    model: '模型与账号接入',
+    identity: '身份与通信',
+    session: '会话与消息',
+    memory: '记忆',
+    tools: '工具与能力',
+    wsl: 'WSL 与 Windows 互操作',
+    browser: '浏览器与网页',
+    vision: '视觉与多模态',
+    voice: '语音与音频',
+    docs: '文档与渲染',
+    skill: '技能包',
+    workflow: '工作流与自动化',
+    git: 'Git 与代码评审',
+    notify: '通知与集成',
+    dev: '开发与运行时',
+    security: '安全与权限',
+    remote: '远程与移动端',
+    market: '插件市场与管理',
+    fun: '娱乐',
+};
+const TOP_LEVEL_KEYS = new Set(['name', 'url', 'source', 'updated', 'count', 'categories', 'plugins']);
+/**
+ * 容器层严格校验（条目层由适配层负责）：
+ * - 根必须是对象，未知顶层键报错；
+ * - `plugins` 缺失/非数组/超过 MAX_COMMUNITY_ENTRIES → 整份拒收（不截断、不部分加载）。
+ */
+export function validateCommunityContainer(raw) {
+    const errors = [];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, errors: ['社区目录根必须是对象'], catalog: null };
+    }
+    const obj = raw;
+    for (const key of Object.keys(obj)) {
+        if (!TOP_LEVEL_KEYS.has(key))
+            errors.push(`${key}: 未知顶层字段`);
+    }
+    const plugins = obj.plugins;
+    if (!Array.isArray(plugins)) {
+        errors.push('plugins: 必须是数组');
+        return { ok: false, errors, catalog: null };
+    }
+    if (plugins.length > MAX_COMMUNITY_ENTRIES) {
+        errors.push(`plugins: ${plugins.length} 条超过上限 ${MAX_COMMUNITY_ENTRIES}，拒绝整份目录`);
+        return { ok: false, errors, catalog: null };
+    }
+    for (let i = 0; i < plugins.length; i++) {
+        const item = plugins[i];
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            errors.push(`plugins[${i}]: 必须是对象`);
+        }
+    }
+    if (errors.length > 0)
+        return { ok: false, errors, catalog: null };
+    const categories = obj.categories && typeof obj.categories === 'object' && !Array.isArray(obj.categories)
+        ? obj.categories
+        : {};
+    return {
+        ok: true,
+        errors: [],
+        catalog: {
+            name: typeof obj.name === 'string' ? obj.name : '',
+            url: typeof obj.url === 'string' ? obj.url : '',
+            source: typeof obj.source === 'string' ? obj.source : '',
+            updated: typeof obj.updated === 'string' ? obj.updated : '',
+            count: typeof obj.count === 'number' ? obj.count : plugins.length,
+            categories,
+            plugins: plugins,
+        },
+    };
+}
+const DEFAULT_FILE_BASES = [
+    'https://cdn.jsdelivr.net/npm/dsh-plugin-catalog@{version}/plugins.json',
+    'https://registry.npmmirror.com/dsh-plugin-catalog/{version}/files/plugins.json',
+    'https://unpkg.com/dsh-plugin-catalog@{version}/plugins.json',
+];
+const ROUTE_LABELS = ['jsdelivr', 'npmmirror', 'unpkg'];
+const META_LATEST = 'meta.json';
+const metaPinName = (v) => `meta-pin-${v}.json`;
+const bodyName = (v) => `catalog-${v}.json`;
+function awesomeDir(namespace) {
+    return join(cacheDir(), namespace, 'awesome');
+}
+/** 路径 containment：目标必须仍在 dir 内（防御拼接穿越）。 */
+function contained(dir, p) {
+    const rel = relative(dir, p);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+async function atomicWrite(path, text) {
+    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+    await writeFile(tmp, text);
+    await rename(tmp, path);
+}
+/** 读取顺序（v8 定稿）：meta 结构校验 → isExactVersion(meta.version) → body containment → 才读正文；损坏文件清理。 */
+async function readCache(dir, pin) {
+    const metaPath = join(dir, pin ? metaPinName(pin) : META_LATEST);
+    let meta = null;
+    try {
+        const raw = JSON.parse(await readFile(metaPath, 'utf8'));
+        if (raw &&
+            typeof raw === 'object' &&
+            typeof raw.version === 'string' &&
+            typeof raw.checkedAt === 'string' &&
+            typeof raw.fetchedAt === 'string' &&
+            (raw.route === null || typeof raw.route === 'string')) {
+            meta = raw;
+        }
+    }
+    catch {
+        meta = null;
+    }
+    if (!meta) {
+        await rm(metaPath, { force: true }).catch(() => undefined);
+        return null;
+    }
+    if (!isExactVersion(meta.version)) {
+        await rm(metaPath, { force: true }).catch(() => undefined);
+        return null;
+    }
+    const bodyPath = join(dir, bodyName(meta.version));
+    if (!contained(dir, bodyPath))
+        return null;
+    let data;
+    try {
+        data = JSON.parse(await readFile(bodyPath, 'utf8'));
+    }
+    catch {
+        await rm(bodyPath, { force: true }).catch(() => undefined);
+        return null;
+    }
+    const v = validateCommunityContainer(data);
+    if (!v.ok || !v.catalog) {
+        await rm(bodyPath, { force: true }).catch(() => undefined);
+        return null;
+    }
+    return { meta, catalog: v.catalog };
+}
+async function writeMeta(dir, pin, meta) {
+    await mkdir(dir, { recursive: true });
+    await atomicWrite(join(dir, pin ? metaPinName(pin) : META_LATEST), JSON.stringify(meta, null, 2));
+}
+function withinTtl(cfg, meta) {
+    const t = Date.parse(meta.checkedAt || '');
+    if (!Number.isFinite(t))
+        return false; // checkedAt 非法 → 视为过期（⑪）
+    return Date.now() - t < Math.max(0, cfg.cacheTtlMin ?? 60) * 60_000;
+}
+function routeError(label, err, ms) {
+    return describeFetchFailure({ label, err, elapsedMs: ms });
+}
+function stateOf(partial) {
+    return {
+        enabled: true,
+        version: null,
+        checkedAt: null,
+        fetchedAt: null,
+        route: null,
+        count: 0,
+        errors: [],
+        warnings: [],
+        ...partial,
+    };
+}
+function disabledState() {
+    return stateOf({ enabled: false, status: 'disabled' });
+}
+function trimPin(cfg) {
+    const raw = typeof cfg.communityCatalogPin === 'string' ? cfg.communityCatalogPin.trim() : '';
+    return raw === '' ? null : raw;
+}
+async function runChain(cfg, opts, ctrl) {
+    const namespace = opts.namespace ?? 'host';
+    const dir = awesomeDir(namespace);
+    const pin = trimPin(cfg);
+    const budgetMs = opts.flightBudgetMs ?? COMMUNITY_CHAIN_BUDGET_MS;
+    const startedAt = Date.now();
+    const remaining = () => budgetMs - (Date.now() - startedAt);
+    // 缓存快速路径：pin 命中即用（版本不可变）；latest 需 TTL 内（checkedAt 新鲜）
+    if (!opts.force) {
+        const cached = await readCache(dir, pin);
+        if (cached && (pin !== null || withinTtl(cfg, cached.meta))) {
+            return {
+                state: stateOf({
+                    status: 'ready',
+                    version: cached.meta.version,
+                    checkedAt: cached.meta.checkedAt,
+                    fetchedAt: cached.meta.fetchedAt,
+                    route: cached.meta.route,
+                    count: cached.catalog.plugins.length,
+                }),
+                catalog: cached.catalog,
+            };
+        }
+    }
+    const errors = [];
+    let version = pin;
+    let probeFailed = false;
+    if (pin === null) {
+        const probeTimeout = Math.max(1, Math.min(8_000, remaining()));
+        const t0 = Date.now();
+        try {
+            const latest = await npmLatest(COMMUNITY_NPM_PACKAGE, probeTimeout, ctrl.signal, opts.routes?.registryBase);
+            if (!isExactVersion(latest.version))
+                throw new Error(`dist-tags 返回非精确版本: ${latest.version}`);
+            version = latest.version;
+        }
+        catch (err) {
+            probeFailed = true;
+            errors.push(routeError('版本探测', err, Date.now() - t0));
+        }
+    }
+    if (probeFailed || version === null) {
+        const cached = await readCache(dir, pin);
+        if (cached) {
+            return {
+                state: stateOf({
+                    status: 'stale',
+                    version: cached.meta.version,
+                    checkedAt: cached.meta.checkedAt,
+                    fetchedAt: cached.meta.fetchedAt,
+                    route: cached.meta.route,
+                    count: cached.catalog.plugins.length,
+                    errors,
+                }),
+                catalog: cached.catalog,
+            };
+        }
+        return { state: stateOf({ status: 'unavailable', errors }), catalog: null };
+    }
+    // 同版本短路（⑫）：探测成功但版本未变 → 只更新 checkedAt，不重拉正文
+    if (!opts.force) {
+        const cachedSame = await readCache(dir, pin);
+        if (cachedSame && cachedSame.meta.version === version) {
+            const checkedAt = new Date().toISOString();
+            await writeMeta(dir, pin, { ...cachedSame.meta, checkedAt });
+            return {
+                state: stateOf({
+                    status: 'ready',
+                    version,
+                    checkedAt,
+                    fetchedAt: cachedSame.meta.fetchedAt,
+                    route: cachedSame.meta.route,
+                    count: cachedSame.catalog.plugins.length,
+                }),
+                catalog: cachedSame.catalog,
+            };
+        }
+    }
+    const bases = opts.routes?.fileBases ?? DEFAULT_FILE_BASES;
+    for (let i = 0; i < bases.length; i++) {
+        if (remaining() <= 0) {
+            errors.push('社区目录加载预算耗尽，稍后重试可恢复');
+            break;
+        }
+        const label = ROUTE_LABELS[i] ?? `route${i}`;
+        const url = bases[i].replace('{version}', encodeURIComponent(version));
+        const t0 = Date.now();
+        try {
+            const { bytes } = await fetchBytesLimited(url, {
+                timeoutMs: Math.max(1, Math.min(CATALOG_BODY_TIMEOUT_MS, remaining())),
+                maxBytes: MAX_COMMUNITY_BYTES,
+                signal: ctrl.signal,
+            });
+            const text = decodeUtf8Fatal(bytes);
+            const data = JSON.parse(text);
+            const v = validateCommunityContainer(data);
+            if (!v.ok || !v.catalog)
+                throw new Error(`目录校验失败 — ${v.errors.slice(0, 3).join('; ')}`);
+            const now = new Date().toISOString();
+            await mkdir(dir, { recursive: true });
+            await atomicWrite(join(dir, bodyName(version)), text);
+            await writeMeta(dir, pin, { version, checkedAt: now, fetchedAt: now, route: label });
+            return {
+                state: stateOf({
+                    status: 'ready',
+                    version,
+                    checkedAt: now,
+                    fetchedAt: now,
+                    route: label,
+                    count: v.catalog.plugins.length,
+                }),
+                catalog: v.catalog,
+            };
+        }
+        catch (err) {
+            if (ctrl.signal.aborted && remaining() <= 0) {
+                errors.push('社区目录加载预算耗尽，稍后重试可恢复');
+                break;
+            }
+            errors.push(routeError(label, err, Date.now() - t0));
+        }
+    }
+    const cached = await readCache(dir, pin);
+    if (cached) {
+        return {
+            state: stateOf({
+                status: 'stale',
+                version: cached.meta.version,
+                checkedAt: cached.meta.checkedAt,
+                fetchedAt: cached.meta.fetchedAt,
+                route: cached.meta.route,
+                count: cached.catalog.plugins.length,
+                errors,
+            }),
+            catalog: cached.catalog,
+        };
+    }
+    return { state: stateOf({ status: 'unavailable', errors }), catalog: null };
+}
+const flights = new Map();
+function flightKey(opts, pin) {
+    const ns = opts.namespace ?? 'host';
+    const routesSig = opts.routes
+        ? `${opts.routes.registryBase ?? ''}|${(opts.routes.fileBases ?? []).join(',')}`
+        : 'default';
+    return [ns, pin ?? '', opts.force ? 'force' : 'normal', routesSig].join('§');
+}
+function abortError() {
+    const err = new Error('Aborted');
+    err.name = 'AbortError';
+    return err;
+}
+async function raceWithSignal(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        throw abortError();
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError());
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (err) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(err);
+        });
+    });
+}
+function releaseFlight(key, flight) {
+    flight.refs -= 1;
+    if (flight.refs <= 0) {
+        clearTimeout(flight.timer);
+        flight.ctrl.abort();
+        if (flights.get(key) === flight)
+            flights.delete(key);
+    }
+}
+/**
+ * 社区清单加载入口（Q39/Q43）：
+ * - disabled → 直接返回（不触网络）；
+ * - pin 非法 → unavailable（零网络零写入）；
+ * - in-flight 合并：key = namespace + 生效 pin + force + routes；各 waiter 的 signal 只取消各自等待。
+ */
+export async function fetchCommunityCatalog(cfg = {}, opts = {}) {
+    if (cfg.communityCatalog === false)
+        return { state: disabledState(), catalog: null };
+    const pin = trimPin(cfg);
+    if (pin !== null && !isExactVersion(pin)) {
+        return {
+            state: stateOf({
+                status: 'unavailable',
+                errors: [`communityCatalogPin 非法（需精确 semver）: ${pin}；请检查设置`],
+            }),
+            catalog: null,
+        };
+    }
+    const key = flightKey(opts, pin);
+    let flight = flights.get(key);
+    if (!flight) {
+        const ctrl = new AbortController();
+        const budgetMs = opts.flightBudgetMs ?? COMMUNITY_CHAIN_BUDGET_MS;
+        const timer = setTimeout(() => ctrl.abort(), budgetMs);
+        const runPromise = runChain(cfg, opts, ctrl);
+        const created = { refs: 0, ctrl, timer, promise: runPromise };
+        runPromise
+            .finally(() => {
+            clearTimeout(timer);
+            if (flights.get(key) === created && created.refs <= 0)
+                flights.delete(key);
+        })
+            .catch(() => undefined);
+        flights.set(key, created);
+        flight = created;
+    }
+    flight.refs += 1;
+    try {
+        return await raceWithSignal(flight.promise, opts.signal);
+    }
+    finally {
+        releaseFlight(key, flight);
+    }
+}
+/**
+ * 单一深接口（计划 Task 6）：fetch → adapt → merge 计数 → CommunityRegistrySummary。
+ * - primaryEntries 直接取本次 registry snapshot 的 primary plugins（displaced 与本次响应同代，
+ *   不重复加载主清单；内部禁止调用 loadRegistry——单一来源约束）；
+ * - 3s 是本 waiter 的等待上限（waiter-scoped race）：到点未 materialize → unavailable +
+ *   「社区目录状态获取超时」errors，调用方主响应照常；共享 flight 按 30s hard cap 继续；
+ * - 数据源 cache-first：fetchCommunityCatalog 的版本缓存 + TTL 保证 registry 刷新无重复网络压力。
+ */
+export async function getCommunitySummary(primaryEntries, cfg = {}, opts) {
+    const task = fetchCommunityCatalog(cfg, { signal: opts.signal, force: opts.force });
+    const outcome = await communityOutcome(task, opts.deadlineAt, primaryEntries);
+    return outcome.summary;
+}