@zhangheteng/skill-hub 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skill Hub contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,7 @@
+# Third-party notices and scope
+
+The MIT license covers Skill Hub's own source and documentation. Dependency packages retain their licenses; package names and locked versions are listed in `package.json`, workspace manifests and `pnpm-lock.yaml`.
+
+The Agent Skills format is an open ecosystem specification: [agentskills.io](https://agentskills.io/specification). Skill Hub is an independent project, not an official product of Anthropic, OpenAI, Vercel, TypeSafe, WorkBuddy, Qoder or OpenCode.
+
+Research documents link to public project documentation; links do not imply endorsement or a dependency on those projects. Skill Hub does not redistribute a user's production Skills. Test fixture instructions are synthetic and intended only for validation. Installed Skills, assets, scripts, plugins and model services keep their original licenses and terms.

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# Skill Hub
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One Skill store for multiple agents: task-based search, progressive text/attachment reads, managed updates, and optional local usage insights.
+
+This is the npm distribution candidate for [983033995/skill-hub](https://github.com/983033995/skill-hub). A generated tarball is not proof of registry publication. Requires Node.js >=20; Git is needed for GitHub-backed Skill installation.
+
+## Install a local release candidate
+
+```bash
+npm install --prefix ./hub-trial /absolute/path/to/zhangheteng-skill-hub-0.2.0.tgz
+./hub-trial/node_modules/.bin/skill-hub version
+```
+
+After a version has actually been published to npm, install the verified package/version using your npm client. For multiple binaries, use `npm exec --package=<verified-package>@<version> -- <binary>` and choose a command below. No package install hook creates or migrates your Skill store.
+
+| Command | Purpose |
+|---|---|
+| `skill-hub` | CLI; use `help` to discover commands |
+| `skill-hub-mcp` | Read-only stdio MCP; full by default, optional runtime |
+| `skill-hub-mcp-http` | Bearer-authenticated Streamable HTTP MCP; three runtime tools |
+| `skill-hub-web` | Local, unauthenticated read-only Web viewer |
+
+## New isolated store
+
+Set `SKILL_HUB_HOME` to a new absolute directory, then run `skill-hub init`. Use the existing CLI's preview/confirmation workflow to install or update Skills. Never run `init --force` over an existing store without understanding the replacement behavior. `skill-hub help` describes the installed CLI.
+
+Configure stdio MCP hosts to execute `skill-hub-mcp` from the installed bin path. Set `SKILL_HUB_MCP_MODE=runtime` for the optional three-tool mode; this does not disable the host's native Skill discovery.
+
+For HTTP, inject `SKILL_HUB_HTTP_TOKEN` (at least 32 random Bearer-token characters) into the process environment, select the server-side `SKILL_HUB_HOME`, and run `skill-hub-mcp-http`. Default listener: `127.0.0.1:8788/mcp`. Every request requires `Authorization: Bearer <token>`. Exposing a non-loopback listener requires explicit `SKILL_HUB_HTTP_ALLOWED_HOSTS`. Use HTTPS ingress and persistent storage on a hosting platform. Static Bearer authentication is not OAuth or multi-tenant isolation.
+
+The npm registry distributes the program; it does not run your HTTP service. Skill text remains untrusted task guidance and never authorizes script execution. Optional Jev transmits task queries/metadata only through the configured/requested provider route; default BM25 works without a model key. Usage observation is disabled unless explicitly configured.
+
+See the source repository's [hosting guide](https://github.com/983033995/skill-hub/blob/main/docs/ops/REMOTE_MCP.md), [API](https://github.com/983033995/skill-hub/blob/main/docs/architecture/API.md), [security policy](https://github.com/983033995/skill-hub/blob/main/SECURITY.md), and [license](https://github.com/983033995/skill-hub/blob/main/LICENSE). Local candidates may contain changes not yet merged into main.

package/apps/cli/dist/args.js

@@ -0,0 +1,111 @@
+/**
+ * 轻量 argv 解析：
+ * skill-hub [--json] [--verbose] [--config path] <command> [args] [--flag value]
+ */
+export function parseArgs(argv) {
+    const booleanFlags = new Set([
+        "dry-run",
+        "apply",
+        "yes",
+        "allow-write",
+        "force",
+        "rebuild",
+        "include-body",
+        "include-plugins",
+        "create-only",
+        "replace-real",
+        "no-materialize",
+        "no-canonical",
+        "require-backup",
+    ]);
+    const flags = {};
+    const positionals = [];
+    let json = false;
+    let verbose = false;
+    let config;
+    let command = "";
+    let i = 0;
+    const takeValue = (cur, next) => {
+        if (next && !next.startsWith("-"))
+            return next;
+        return true;
+    };
+    while (i < argv.length) {
+        const a = argv[i];
+        if (a === "--json") {
+            json = true;
+            i += 1;
+            continue;
+        }
+        if (a === "--verbose" || a === "-v") {
+            verbose = true;
+            i += 1;
+            continue;
+        }
+        if (a === "--config") {
+            const v = argv[i + 1];
+            if (!v || v.startsWith("-")) {
+                throw new Error("--config 需要路径参数");
+            }
+            config = v;
+            i += 2;
+            continue;
+        }
+        if (a === "--version" || a === "-V") {
+            command = "version";
+            i += 1;
+            continue;
+        }
+        if (a === "--help" || a === "-h") {
+            command = "help";
+            i += 1;
+            continue;
+        }
+        if (a.startsWith("--")) {
+            const eq = a.indexOf("=");
+            if (eq > 2) {
+                flags[a.slice(2, eq)] = a.slice(eq + 1);
+                i += 1;
+                continue;
+            }
+            const key = a.slice(2);
+            if (booleanFlags.has(key)) {
+                flags[key] = true;
+                i += 1;
+                continue;
+            }
+            const val = takeValue(a, argv[i + 1]);
+            if (val === true) {
+                flags[key] = true;
+                i += 1;
+            }
+            else {
+                flags[key] = val;
+                i += 2;
+            }
+            continue;
+        }
+        if (!command) {
+            command = a;
+            i += 1;
+            continue;
+        }
+        positionals.push(a);
+        i += 1;
+    }
+    if (!command)
+        command = "help";
+    return { json, verbose, config, command, positionals, flags };
+}
+export function flagBool(flags, key) {
+    const v = flags[key];
+    if (v === true || v === "true" || v === "1")
+        return true;
+    return false;
+}
+export function flagString(flags, key) {
+    const v = flags[key];
+    if (typeof v === "string")
+        return v;
+    return undefined;
+}

package/apps/cli/dist/commands/audit.js

@@ -0,0 +1,38 @@
+import { skillAudit } from "#skill-hub/router";
+import { SkillHubError } from "#skill-hub/shared";
+import { printJson, printLines } from "../output.js";
+const SEVERITIES = ["info", "warning", "high", "critical"];
+export async function runAudit(options) {
+    const failOn = parseFailOn(options.failOn);
+    const report = await skillAudit({
+        name: options.name,
+        catalogPath: options.catalogPath,
+        configPath: options.configPath,
+    });
+    const failedByPolicy = report.skills.some((skill) => !skill.complete || skill.findings.some((finding) => SEVERITIES.indexOf(finding.severity) >= SEVERITIES.indexOf(failOn)));
+    const payload = { ...report, fail_on: failOn, failed_by_policy: failedByPolicy };
+    if (options.json) {
+        printJson(payload);
+    }
+    else {
+        printLines([
+            `audit ${options.name ?? "(all skills)"}  passed=${report.summary.passed} failed=${report.summary.failed}`,
+            `  findings critical=${report.summary.critical} high=${report.summary.high} warning=${report.summary.warning} info=${report.summary.info}`,
+            ...report.skills.flatMap((skill) => [
+                `  ${skill.passed ? "PASS" : "FAIL"} ${skill.name} files=${skill.summary.filesScanned}`,
+                ...skill.findings.map((finding) => `    [${finding.severity}] ${finding.file}:${finding.line} ${finding.ruleId} — ${finding.message}`),
+            ]),
+        ]);
+    }
+    return failedByPolicy ? 2 : 0;
+}
+function parseFailOn(raw) {
+    const value = raw?.trim() || "high";
+    if (!SEVERITIES.includes(value)) {
+        throw new SkillHubError({
+            code: "E_CONFIG",
+            message: `--fail-on 无效: ${value}（应为 info|warning|high|critical）`,
+        });
+    }
+    return value;
+}

package/apps/cli/dist/commands/backup.js

@@ -0,0 +1,34 @@
+import { loadHubConfig, resolveHubConfigPaths } from "#skill-hub/core";
+import { createBackup } from "#skill-hub/sync";
+import { getDefaultHubHome, hubLayout } from "#skill-hub/shared";
+import { printJson, printLines } from "../output.js";
+export async function runBackup(options) {
+    const config = resolveHubConfigPaths(options.configPath ? await loadHubConfig(options.configPath) : await loadHubConfig());
+    if (options.out) {
+        config.backup_dir = options.out;
+    }
+    const layout = hubLayout(getDefaultHubHome());
+    const manifest = await createBackup(config, {
+        notes: options.notes ?? "skill-hub backup",
+        includeCanonical: options.includeCanonical,
+        dryRun: options.dryRun,
+        hubMeta: { catalogPath: layout.catalog, configPath: layout.config },
+    });
+    if (options.json) {
+        printJson(manifest);
+    }
+    else {
+        printLines([
+            `backup ${options.dryRun ? "(dry-run)" : "written"}`,
+            `  dir: ${manifest.backupDir}`,
+            ...manifest.agents.map((a) => `  agent ${a.id.padEnd(12)} ${a.skipped ? "SKIP" : "OK"}  entries=${a.entryCount}  ${a.path}`),
+            manifest.canonical
+                ? `  canonical ${manifest.canonical.exists ? "OK" : "MISS"}  ${manifest.canonical.path}`
+                : "",
+            options.dryRun
+                ? "  note: dry-run 未复制文件"
+                : `  manifest: ${manifest.backupDir}/manifest.json`,
+        ].filter(Boolean));
+    }
+    return 0;
+}

package/apps/cli/dist/commands/doctor.js

@@ -0,0 +1,86 @@
+import { access, readdir } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { defaultHubConfig, loadHubConfig, resolveHubConfigPaths, scanSkills, } from "#skill-hub/core";
+import { SKILL_HUB_VERSION, expandUserPath, getDefaultHubHome, hubLayout, } from "#skill-hub/shared";
+import { printJson, printLines } from "../output.js";
+export async function runDoctor(options) {
+    const hubHome = getDefaultHubHome();
+    const layout = hubLayout(hubHome);
+    let config;
+    try {
+        config = resolveHubConfigPaths(options.configPath
+            ? await loadHubConfig(options.configPath)
+            : await loadHubConfig().catch(() => defaultHubConfig()));
+    }
+    catch {
+        config = resolveHubConfigPaths(defaultHubConfig());
+    }
+    const agents = [];
+    for (const a of config.agents) {
+        const p = expandUserPath(a.skills_dir);
+        let exists = false;
+        let count = 0;
+        try {
+            await access(p, fsConstants.R_OK);
+            exists = true;
+            // 只统计一级子目录中有 SKILL.md 的数量（轻量）；完整 scan 留给 inventory
+            try {
+                const skills = await scanSkills(p, { agentId: a.id, maxDepth: 3 });
+                count = skills.length;
+            }
+            catch {
+                const entries = await readdir(p).catch(() => []);
+                count = entries.length;
+            }
+        }
+        catch {
+            exists = false;
+        }
+        agents.push({
+            id: a.id,
+            path: p,
+            enabled: a.enabled,
+            exists,
+            count,
+        });
+    }
+    const issues = [];
+    let canonicalExists = false;
+    try {
+        await access(layout.home, fsConstants.R_OK);
+        canonicalExists = true;
+    }
+    catch {
+        issues.push(`hub home 不存在（可运行 skill-hub init）: ${layout.home}`);
+    }
+    for (const a of agents) {
+        if (a.enabled && !a.exists) {
+            issues.push(`agent ${a.id} skills 目录不存在: ${a.path}`);
+        }
+    }
+    const result = {
+        ok: issues.length === 0,
+        version: SKILL_HUB_VERSION,
+        node: process.version,
+        canonical: { path: layout.home, exists: canonicalExists },
+        catalog: layout.catalog,
+        agents,
+        issues,
+    };
+    if (options.json) {
+        printJson(result);
+    }
+    else {
+        printLines([
+            `skill-hub doctor  v${SKILL_HUB_VERSION}`,
+            `node: ${process.version}`,
+            `hub:  ${layout.home}  (${canonicalExists ? "exists" : "missing"})`,
+            "",
+            "agents:",
+            ...agents.map((a) => `  - ${a.id.padEnd(12)} ${a.exists ? "OK" : "MISS"}  count≈${a.count}  ${a.path}`),
+            "",
+            issues.length === 0 ? "issues: (none)" : `issues:\n${issues.map((i) => `  - ${i}`).join("\n")}`,
+        ]);
+    }
+    return result.ok ? 0 : 3;
+}

package/apps/cli/dist/commands/index-cmd.js

@@ -0,0 +1,122 @@
+import { mkdir, writeFile, lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+import { appendHistory, loadHubConfig, resolveHubConfigPaths, catalogToSkillMetas, catalogHash, createEmptyCatalog, readCatalog, scanSkills, skillMetaToCatalogEntry, writeCatalog, } from "#skill-hub/core";
+import { createBm25Router } from "#skill-hub/router";
+import { SkillHubError, getDefaultHubHome, hubLayout, resolveAbsolutePath, isPathInside, } from "#skill-hub/shared";
+import { printJson, printLines } from "../output.js";
+export async function runIndex(options) {
+    const layout = hubLayout(getDefaultHubHome());
+    const config = resolveHubConfigPaths(await loadHubConfig(options.configPath));
+    const catalogPath = options.catalogPath
+        ? resolveAbsolutePath(options.catalogPath)
+        : layout.catalog;
+    const indexDir = options.indexDir ? resolveAbsolutePath(options.indexDir) : config.index_dir;
+    let catalog;
+    try {
+        catalog = await readCatalog(catalogPath);
+    }
+    catch (err) {
+        const exists = await lstat(catalogPath).catch((e) => {
+            if (e.code === "ENOENT")
+                return null;
+            throw e;
+        });
+        if (exists)
+            throw err;
+        if (!options.rebuild) {
+            throw new SkillHubError({
+                code: "E_INDEX",
+                message: `catalog 不存在，请先 ingest 或 index --rebuild 从 canonical 扫描: ${catalogPath}`,
+                details: { path: catalogPath },
+            });
+        }
+        catalog = createEmptyCatalog();
+    }
+    let skills = catalogToSkillMetas(catalog);
+    if (options.rebuild || skills.length === 0) {
+        {
+            const issues = [];
+            skills = await scanSkills(config.canonical_dir, {
+                onIssue: (issue) => issues.push(issue),
+                source: config.canonical_dir,
+                provenance: {
+                    scope: "user",
+                    sourceType: "local",
+                    sourceRef: config.canonical_dir,
+                },
+            });
+            if (issues.length)
+                throw new SkillHubError({
+                    code: "E_INDEX",
+                    message: `canonical 扫描不完整: ${JSON.stringify(issues)}`,
+                });
+            const previousEntries = catalog.skills;
+            const physicalCanonical = await realpath(config.canonical_dir);
+            catalog = {
+                version: 1,
+                updatedAt: new Date().toISOString(),
+                skills: Object.fromEntries([
+                    ...Object.entries(previousEntries).filter(([, entry]) => !isPathInside(entry.path, config.canonical_dir) &&
+                        !isPathInside(entry.path, physicalCanonical)),
+                    ...skills.map((s) => {
+                        const entry = skillMetaToCatalogEntry(s);
+                        const previous = previousEntries[s.name];
+                        if (previous?.provenance)
+                            entry.provenance = { ...previous.provenance };
+                        if (previous?.source)
+                            entry.source = previous.source;
+                        return [s.name, entry];
+                    }),
+                ]),
+            };
+            await writeCatalog(catalogPath, catalog);
+            skills = catalogToSkillMetas(catalog);
+        }
+    }
+    const router = createBm25Router();
+    await router.build(skills);
+    await mkdir(indexDir, { recursive: true });
+    const currentCatalogHash = catalogHash(catalog);
+    const artifactPath = path.join(indexDir, "bm25.json");
+    await writeFile(artifactPath, `${JSON.stringify(router.toArtifact(), null, 2)}\n`);
+    const meta = {
+        version: 1,
+        engine: "bm25",
+        builtAt: new Date().toISOString(),
+        skillCount: skills.length,
+        catalogHash: currentCatalogHash,
+        artifact: path.basename(artifactPath),
+        artifactFormat: "skill-hub.bm25.v2",
+    };
+    await writeFile(path.join(indexDir, "index-meta.json"), `${JSON.stringify(meta, null, 2)}\n`);
+    await appendHistory(layout.history, {
+        at: meta.builtAt,
+        type: "index",
+        action: options.rebuild ? "rebuild" : "build",
+        detail: {
+            engine: meta.engine,
+            skillCount: meta.skillCount,
+            catalogHash: meta.catalogHash,
+            artifact: artifactPath,
+        },
+    });
+    const result = {
+        ok: true,
+        ...meta,
+        catalogPath,
+        indexDir,
+    };
+    if (options.quiet)
+        return 0;
+    if (options.json)
+        printJson(result);
+    else {
+        printLines([
+            `index built  engine=bm25  skills=${meta.skillCount}`,
+            `  catalog: ${catalogPath}`,
+            `  meta:    ${path.join(indexDir, "index-meta.json")}`,
+            `  artifact: ${artifactPath}`,
+        ]);
+    }
+    return 0;
+}

package/apps/cli/dist/commands/ingest.js

@@ -0,0 +1,198 @@
+import { lstat } from "node:fs/promises";
+import { appendHistoryBatch, createEmptyCatalog, detectConflicts, hashSkillTree, materializeToCanonical, readCatalog, scanSkills, sourceMappingToProvenance, upsertSkills, writeCatalog, } from "#skill-hub/core";
+import { getDefaultHubHome, hubLayout, resolveAbsolutePath, isPathInside, } from "#skill-hub/shared";
+import { printJson, printLines } from "../output.js";
+export async function runIngest(options) {
+    if (options.sources.length === 0) {
+        throw new Error("ingest 需要 --sources <dir>[,<dir>...]");
+    }
+    const layout = hubLayout(getDefaultHubHome());
+    const catalogPath = options.catalogPath
+        ? resolveAbsolutePath(options.catalogPath)
+        : layout.catalog;
+    let catalog;
+    try {
+        catalog = await readCatalog(catalogPath);
+    }
+    catch (err) {
+        const exists = await lstat(catalogPath).catch((e) => {
+            if (e.code === "ENOENT")
+                return null;
+            throw e;
+        });
+        if (exists)
+            throw err;
+        catalog = createEmptyCatalog();
+    }
+    const previousCatalog = catalog;
+    const canonicalDir = resolveAbsolutePath(options.canonicalDir ?? layout.skills);
+    const scanned = [];
+    const resolvedSources = [];
+    for (const requested of options.sources) {
+        const mapping = (options.sourceMappings ?? []).find((s) => s.id === requested || resolveAbsolutePath(s.path) === resolveAbsolutePath(requested));
+        const abs = resolveAbsolutePath(mapping?.path ?? requested);
+        const provenance = mapping
+            ? sourceMappingToProvenance(mapping, abs)
+            : { scope: "user", sourceType: "local", sourceRef: abs };
+        const scanIssues = [];
+        const skills = await scanSkills(abs, {
+            onIssue: (issue) => scanIssues.push(issue),
+            source: abs,
+            provenance,
+            maxDepth: 5,
+        });
+        if (scanIssues.length)
+            throw new Error(`来源扫描不完整: ${JSON.stringify(scanIssues)}`);
+        scanned.push(...skills);
+        resolvedSources.push({ requested, path: abs, sourceId: mapping?.id });
+    }
+    // 附件参与冲突检测；同名冲突未明确选源时不导入任何一方。
+    const trees = new Map();
+    for (const skill of scanned)
+        trees.set(skill.path, await hashSkillTree(skill.path));
+    const conflicts = detectConflicts(scanned.map((skill) => ({ ...skill, hash: trees.get(skill.path) })));
+    const conflictNames = new Set(conflicts.map((c) => c.name));
+    const groups = new Map();
+    for (const skill of scanned)
+        groups.set(skill.name, [...(groups.get(skill.name) ?? []), skill]);
+    const selected = [];
+    const unresolved = [];
+    for (const [name, variants] of groups) {
+        if (!conflictNames.has(name)) {
+            selected.push(variants[0]);
+            continue;
+        }
+        const preferred = options.prefer
+            ? variants.filter((skill) => isPathInside(skill.path, options.prefer))
+            : [];
+        if (preferred.length && new Set(preferred.map((skill) => trees.get(skill.path))).size === 1) {
+            selected.push(preferred[0]);
+        }
+        else
+            unresolved.push(name);
+    }
+    // report 模式整个批次不写；skip 模式仅导入无冲突项。
+    if (unresolved.length && options.conflictMode === "report" && !options.dryRun) {
+        if (options.json)
+            printJson({
+                dryRun: false,
+                applied: false,
+                conflicts,
+                unresolved,
+                note: "未写入：请 --prefer 选择来源或 --conflict skip",
+            });
+        else
+            printLines([`导入已停止：${unresolved.length} 个未解决冲突`, ...unresolved]);
+        return 2;
+    }
+    let materializeSummary = null;
+    let catalogSkills = selected;
+    let skippedUpsert = [];
+    let updated = [];
+    if (options.materialize) {
+        const mat = await materializeToCanonical(selected, canonicalDir, {
+            force: options.forceMaterialize === true,
+            dryRun: options.dryRun,
+            backupDir: options.backupDir,
+        });
+        materializeSummary = { copied: mat.copied, skipped: mat.skipped, failed: mat.failed };
+        catalogSkills = mat.skills;
+        const upserted = upsertSkills(catalog, catalogSkills, { skipOnHashConflict: false });
+        catalog = upserted.catalog;
+        updated = upserted.updated;
+        skippedUpsert = [
+            ...unresolved,
+            ...mat.skipped.filter((s) => s.reason.includes("冲突")).map((s) => s.name),
+        ];
+        if (!options.dryRun && updated.length)
+            await writeCatalog(catalogPath, catalog);
+    }
+    else {
+        const upserted = upsertSkills(catalog, selected, {
+            skipOnHashConflict: !options.prefer || options.conflictMode === "skip",
+        });
+        catalog = upserted.catalog;
+        updated = upserted.updated;
+        skippedUpsert = [...unresolved, ...upserted.skipped];
+        if (!options.dryRun && updated.length)
+            await writeCatalog(catalogPath, catalog);
+    }
+    const preview = catalog;
+    if (!options.dryRun && updated.length > 0) {
+        const now = new Date().toISOString();
+        await appendHistoryBatch(layout.history, updated.flatMap((name) => {
+            const next = catalog.skills[name];
+            if (!next)
+                return [];
+            const previous = previousCatalog.skills[name];
+            const type = next.provenance?.overlayOf ? "overlay" : "ingest";
+            return [
+                {
+                    at: now,
+                    type,
+                    name,
+                    action: previous ? "update" : "create",
+                    previousHash: previous?.hash,
+                    hash: next.hash,
+                    revision: next.provenance?.revision,
+                    source: next.source ?? next.provenance?.sourceRef,
+                    provenance: next.provenance,
+                    path: next.path,
+                    detail: { catalogPath, materialize: options.materialize },
+                },
+            ];
+        }));
+    }
+    const result = {
+        dryRun: options.dryRun,
+        materializeEnabled: options.materialize && !options.dryRun,
+        sources: resolvedSources,
+        prefer: options.prefer ? resolveAbsolutePath(options.prefer) : null,
+        scanned: scanned.length,
+        selected: selected.length,
+        updated: updated.length,
+        skipped: skippedUpsert,
+        conflicts,
+        materialize: materializeSummary,
+        catalogPath,
+        catalogSkillCount: Object.keys(preview.skills).length,
+        canonicalDir,
+        note: options.dryRun
+            ? "dry-run：未写入 catalog / canonical"
+            : options.materialize
+                ? "已物化到 canonical 并写入 catalog（未修改各 Agent skills 目录）"
+                : "已写入 catalog（未复制 skill 文件；路径仍指向源目录）",
+    };
+    if (options.json)
+        printJson(result);
+    else {
+        printLines([
+            `ingest ${options.dryRun ? "(dry-run)" : ""}`.trim(),
+            `  scanned:   ${result.scanned}`,
+            `  selected:  ${result.selected}`,
+            `  updated:   ${result.updated}`,
+            `  skipped:   ${result.skipped.length}`,
+            `  conflicts: ${result.conflicts.length}`,
+            `  catalog:   ${catalogPath} (${result.catalogSkillCount} skills)`,
+            materializeSummary
+                ? `  materialize: copied=${materializeSummary.copied.length} skipped=${materializeSummary.skipped.length} failed=${materializeSummary.failed.length}`
+                : `  materialize: ${options.dryRun ? "n/a (dry-run)" : options.materialize ? "requested" : "off"}`,
+            `  note:      ${result.note}`,
+        ]);
+        if (result.conflicts.length > 0 && result.conflicts.length <= 30) {
+            printLines([
+                "  conflict names:",
+                ...result.conflicts.map((c) => `    - ${c.name} (${c.variants.length} variants)`),
+            ]);
+        }
+        if (materializeSummary?.failed.length) {
+            printLines([
+                "  materialize failed:",
+                ...materializeSummary.failed.slice(0, 20).map((f) => `    - ${f.name}: ${f.error}`),
+            ]);
+        }
+    }
+    if (materializeSummary && materializeSummary.failed.length > 0)
+        return 3;
+    return skippedUpsert.length > 0 ? 2 : 0;
+}