@zhangheteng/skill-hub 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,48 @@
+import { lstat } from "node:fs/promises";
+import { catalogToSkillMetas, loadHubConfig, readCatalog, resolveHubConfigPaths, scanSkills, } from "#skill-hub/core";
+import { verifySync } from "#skill-hub/sync";
+import { SkillHubError, getDefaultHubHome, hubLayout, resolveAbsolutePath, } from "#skill-hub/shared";
+import { printJson, printLines } from "../output.js";
+export async function runVerify(options) {
+    const config = resolveHubConfigPaths(options.configPath ? await loadHubConfig(options.configPath) : await loadHubConfig());
+    const layout = hubLayout(getDefaultHubHome());
+    const catalogPath = options.catalogPath
+        ? resolveAbsolutePath(options.catalogPath)
+        : layout.catalog;
+    let skills = [];
+    try {
+        skills = catalogToSkillMetas(await readCatalog(catalogPath));
+    }
+    catch (err) {
+        const exists = await lstat(catalogPath).catch((e) => {
+            if (e.code === "ENOENT")
+                return null;
+            throw e;
+        });
+        if (exists)
+            throw err;
+        const issues = [];
+        skills = await scanSkills(config.canonical_dir, { onIssue: (issue) => issues.push(issue) });
+        if (issues.length)
+            throw new SkillHubError({
+                code: "E_SYNC",
+                message: `canonical 扫描不完整: ${JSON.stringify(issues)}`,
+            });
+    }
+    const report = await verifySync(config, skills);
+    if (options.json)
+        printJson(report);
+    else {
+        const s = report.summary;
+        printLines([
+            `verify ${report.ok ? "OK" : "ISSUES"}  mode=${config.sync.mode}  skills×agents=${report.items.length}`,
+            `  ok=${s.ok} missing=${s.missing} not_symlink=${s.not_symlink} not_copy=${s.not_copy} broken=${s.broken_symlink} wrong=${s.wrong_target} mismatch=${s.content_mismatch}`,
+            ...report.items
+                .filter((i) => i.kind !== "ok")
+                .slice(0, 40)
+                .map((i) => `  [${i.kind}] ${i.agentId}:${i.skillName} ${i.detail ?? ""}${i.suggestion ? ` → ${i.suggestion}` : ""}`),
+            report.items.filter((i) => i.kind !== "ok").length > 40 ? `  ... more issues` : "",
+        ].filter(Boolean));
+    }
+    return report.ok ? 0 : 1;
+}

package/apps/cli/dist/index.js

@@ -0,0 +1,468 @@
+#!/usr/bin/env node
+/**
+ * skill-hub CLI
+ */
+import { SKILL_HUB_VERSION, SkillHubError, createLogger, toSkillHubError, } from "#skill-hub/shared";
+import { agentSkillSources, loadHubConfig, resolveHubConfigPaths } from "#skill-hub/core";
+import { flagBool, flagString, parseArgs } from "./args.js";
+import { printJson, printLines } from "./output.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runInventory } from "./commands/inventory.js";
+import { runInit } from "./commands/init.js";
+import { runIngest } from "./commands/ingest.js";
+import { runIndex } from "./commands/index-cmd.js";
+import { runRoute } from "./commands/route.js";
+import { runSync } from "./commands/sync.js";
+import { runBackup } from "./commands/backup.js";
+import { runVerify } from "./commands/verify.js";
+import { runRestore } from "./commands/restore.js";
+import { runExplain, runHistory, runPath } from "./commands/inspect.js";
+import { runTakeover } from "./commands/takeover.js";
+import { runManage } from "./commands/manage.js";
+import { runBrowse, runFiles, runRead } from "./commands/runtime.js";
+import { runAudit } from "./commands/audit.js";
+import { runManifest } from "./commands/manifest.js";
+import { withUsageScope } from "#skill-hub/router";
+import { runContextCost, runUsage } from "./commands/usage.js";
+const log = createLogger({ name: "cli" });
+async function main() {
+    const argv = process.argv.slice(2);
+    let parsed;
+    try {
+        parsed = parseArgs(argv);
+    }
+    catch (err) {
+        const e = toSkillHubError(err, "参数错误");
+        fail(e, false);
+        return;
+    }
+    try {
+        const code = await withUsageScope("cli", () => dispatch(parsed));
+        process.exitCode = code;
+    }
+    catch (err) {
+        const e = toSkillHubError(err);
+        fail(e, parsed.json);
+    }
+}
+async function dispatch(parsed) {
+    const { command, json, positionals, flags, config } = parsed;
+    switch (command) {
+        case "usage":
+        case "context-cost": {
+            const allowed = command === "usage"
+                ? ["log", "days", "origin"]
+                : ["catalog", "max-chars", "context-window"];
+            if (positionals.length > 1)
+                throw new SkillHubError({ code: "E_CONFIG", message: `${command}最多接受一个Skill名称` });
+            for (const key of Object.keys(flags)) {
+                if (!allowed.includes(key) || flags[key] === true)
+                    throw new SkillHubError({ code: "E_CONFIG", message: `${command}参数无效: --${key}` });
+            }
+            return command === "usage"
+                ? runUsage({
+                    json,
+                    name: positionals[0],
+                    file: flagString(flags, "log"),
+                    days: flagString(flags, "days"),
+                    origin: flagString(flags, "origin"),
+                })
+                : runContextCost({
+                    json,
+                    name: positionals[0],
+                    catalogPath: flagString(flags, "catalog"),
+                    configPath: config,
+                    maxChars: flagString(flags, "max-chars"),
+                    contextWindow: flagString(flags, "context-window"),
+                });
+        }
+        case "version":
+            if (json)
+                printJson({ version: SKILL_HUB_VERSION });
+            else
+                console.log(SKILL_HUB_VERSION);
+            return 0;
+        case "help":
+            printHelp();
+            return 0;
+        case "doctor":
+            return runDoctor({ json, configPath: config });
+        case "takeover":
+            return runTakeover({
+                json,
+                configPath: config,
+                out: flagString(flags, "out"),
+                includePlugins: flagBool(flags, "include-plugins"),
+            });
+        case "install":
+        case "adopt":
+        case "update":
+        case "check-updates":
+        case "list": {
+            if (command === "check-updates") {
+                for (const key of Object.keys(flags)) {
+                    if (!["skill", "dry-run"].includes(key)) {
+                        throw new SkillHubError({ code: "E_CONFIG", message: `check-updates 不接受 --${key}` });
+                    }
+                }
+                if (flags.skill === true) {
+                    throw new SkillHubError({ code: "E_CONFIG", message: "--skill 需要 Skill 名称" });
+                }
+            }
+            const named = flagString(flags, "skill")
+                ?.split(",")
+                .map((s) => s.trim())
+                .filter(Boolean);
+            return runManage({
+                action: command,
+                json,
+                configPath: config,
+                source: command === "install" || command === "adopt" ? positionals[0] : undefined,
+                names: named ??
+                    (command === "update" || command === "list" || command === "check-updates"
+                        ? positionals.length
+                            ? positionals.flatMap((s) => s.split(","))
+                            : undefined
+                        : undefined),
+                ref: flagString(flags, "ref"),
+                planToken: flags["plan-token"] === true ? "" : flagString(flags, "plan-token"),
+                overlayOf: flags["overlay-of"] === true ? "" : flagString(flags, "overlay-of"),
+                apply: flagBool(flags, "apply"),
+                yes: flagBool(flags, "yes"),
+                dryRun: flagBool(flags, "dry-run"),
+            });
+        }
+        case "migrate-source": {
+            for (const key of Object.keys(flags)) {
+                if (!["source", "ref", "plan-token", "apply", "yes", "dry-run"].includes(key)) {
+                    throw new SkillHubError({ code: "E_CONFIG", message: `migrate-source 不接受 --${key}` });
+                }
+            }
+            if (positionals.length !== 1 || !flagString(flags, "source") || flags.ref === true) {
+                throw new SkillHubError({
+                    code: "E_CONFIG",
+                    message: "migrate-source <name> 需要 --source <新来源>；--ref 需要值",
+                });
+            }
+            return runManage({
+                action: "migrate-source",
+                names: positionals,
+                source: flagString(flags, "source"),
+                ref: flagString(flags, "ref"),
+                planToken: flags["plan-token"] === true ? "" : flagString(flags, "plan-token"),
+                json,
+                configPath: config,
+                apply: flagBool(flags, "apply"),
+                yes: flagBool(flags, "yes"),
+                dryRun: flagBool(flags, "dry-run"),
+            });
+        }
+        case "rollback": {
+            const name = commandName(positionals, flags, "rollback");
+            return runManage({
+                action: "rollback",
+                json,
+                configPath: config,
+                names: name ? [name] : [],
+                backupPath: flagString(flags, "from"),
+                planToken: flags["plan-token"] === true ? "" : flagString(flags, "plan-token"),
+                apply: flagBool(flags, "apply"),
+                yes: flagBool(flags, "yes"),
+                dryRun: flagBool(flags, "dry-run"),
+            });
+        }
+        case "inventory": {
+            const agents = flagString(flags, "agents");
+            const sources = flagString(flags, "sources");
+            const scopes = parseScopes(flagString(flags, "scope"));
+            return runInventory({
+                json,
+                configPath: config,
+                agentFilter: agents ? agents.split(",").map((s) => s.trim()) : undefined,
+                sourceFilter: sources ? sources.split(",").map((s) => s.trim()) : undefined,
+                scopeFilter: scopes,
+                outPath: flagString(flags, "out"),
+            });
+        }
+        case "init":
+            return runInit({ json, force: flagBool(flags, "force") });
+        case "ingest": {
+            const sourcesRaw = flagString(flags, "sources") ??
+                (positionals[0] && !positionals[0].startsWith("-") ? positionals[0] : undefined);
+            const configured = resolveHubConfigPaths(config ? await loadHubConfig(config) : await loadHubConfig());
+            const sources = sourcesRaw
+                ? sourcesRaw
+                    .split(",")
+                    .map((s) => s.trim())
+                    .filter(Boolean)
+                : (configured.sources ?? []).filter((s) => s.enabled).map((s) => s.id);
+            // 默认物化到 canonical；--no-materialize 仅写 catalog 元数据
+            const noMaterialize = flagBool(flags, "no-materialize");
+            return runIngest({
+                json,
+                sources,
+                dryRun: flagBool(flags, "dry-run"),
+                prefer: flagString(flags, "prefer"),
+                conflictMode: flagString(flags, "conflict") === "skip" ? "skip" : "report",
+                catalogPath: flagString(flags, "catalog"),
+                materialize: !noMaterialize,
+                forceMaterialize: flagBool(flags, "force"),
+                sourceMappings: agentSkillSources(configured),
+                canonicalDir: configured.canonical_dir,
+                backupDir: configured.backup_dir,
+            });
+        }
+        case "index":
+            return runIndex({
+                json,
+                configPath: config,
+                rebuild: flagBool(flags, "rebuild"),
+                catalogPath: flagString(flags, "catalog"),
+                indexDir: flagString(flags, "index-dir"),
+            });
+        case "route": {
+            const q = positionals.join(" ").trim() || flagString(flags, "query") || "";
+            const topK = parseIntegerFlag(flags, "top-k", 5);
+            const scopes = parseScopes(flagString(flags, "scope"));
+            return runRoute({
+                json,
+                query: q,
+                topK,
+                profile: flagString(flags, "profile"),
+                includeBody: flagBool(flags, "include-body"),
+                catalogPath: flagString(flags, "catalog"),
+                configPath: config,
+                indexDir: flagString(flags, "index-dir"),
+                engine: flagString(flags, "engine"),
+                profilesDir: flagString(flags, "profiles-dir"),
+                scopes,
+            });
+        }
+        case "audit":
+            return runAudit({
+                json,
+                name: positionals.join(" ").trim() || flagString(flags, "name"),
+                catalogPath: flagString(flags, "catalog"),
+                configPath: config,
+                failOn: flagString(flags, "fail-on"),
+            });
+        case "manifest":
+            return runManifest({
+                json,
+                outputPath: flagString(flags, "out"),
+                apply: flagBool(flags, "apply"),
+                yes: flagBool(flags, "yes"),
+                dryRun: flagBool(flags, "dry-run"),
+                catalogPath: flagString(flags, "catalog"),
+                configPath: config,
+            });
+        case "browse":
+            return runBrowse({
+                json,
+                query: positionals.join(" ").trim() || flagString(flags, "query"),
+                offset: parseOptionalIntegerFlag(flags, "offset"),
+                limit: parseOptionalIntegerFlag(flags, "limit"),
+                catalogPath: flagString(flags, "catalog"),
+                configPath: config,
+            });
+        case "files":
+            return runFiles({
+                json,
+                name: commandName(positionals, flags, "files"),
+                path: flagString(flags, "path"),
+                offset: parseOptionalIntegerFlag(flags, "offset"),
+                limit: parseOptionalIntegerFlag(flags, "limit"),
+                catalogPath: flagString(flags, "catalog"),
+                configPath: config,
+            });
+        case "read":
+            return runRead({
+                json,
+                name: commandName(positionals, flags, "read"),
+                file: flagString(flags, "file"),
+                offset: parseOptionalIntegerFlag(flags, "offset"),
+                maxChars: parseOptionalIntegerFlag(flags, "max-chars"),
+                catalogPath: flagString(flags, "catalog"),
+                configPath: config,
+            });
+        case "explain":
+            return runExplain({
+                json,
+                name: positionals.join(" ").trim() || flagString(flags, "name") || "",
+                catalogPath: flagString(flags, "catalog"),
+                configPath: config,
+                historyPath: flagString(flags, "history"),
+            });
+        case "path":
+            return runPath({
+                json,
+                name: positionals.join(" ").trim() || flagString(flags, "name") || "",
+                catalogPath: flagString(flags, "catalog"),
+                configPath: config,
+            });
+        case "history": {
+            return runHistory({
+                json,
+                name: positionals.join(" ").trim() || flagString(flags, "name"),
+                historyPath: flagString(flags, "history"),
+                limit: parseOptionalIntegerFlag(flags, "limit"),
+            });
+        }
+        case "backup":
+            return runBackup({
+                json,
+                configPath: config,
+                out: flagString(flags, "out"),
+                notes: flagString(flags, "notes"),
+                dryRun: flagBool(flags, "dry-run"),
+                includeCanonical: !flagBool(flags, "no-canonical"),
+            });
+        case "verify":
+            return runVerify({
+                json,
+                configPath: config,
+                catalogPath: flagString(flags, "catalog"),
+            });
+        case "restore": {
+            const agents = flagString(flags, "agents");
+            return runRestore({
+                json,
+                from: flagString(flags, "from") ?? positionals[0] ?? "",
+                yes: flagBool(flags, "yes"),
+                apply: flagBool(flags, "apply"),
+                dryRun: flagBool(flags, "dry-run") || !flagBool(flags, "apply"),
+                agents: agents ? agents.split(",").map((s) => s.trim()) : undefined,
+            });
+        }
+        case "sync": {
+            const agentsFlag = flagString(flags, "agents");
+            return runSync({
+                json,
+                apply: flagBool(flags, "apply"),
+                dryRun: flagBool(flags, "dry-run") || !flagBool(flags, "apply"),
+                requireBackup: flagBool(flags, "require-backup"),
+                yes: flagBool(flags, "yes"),
+                allowWrite: flagBool(flags, "allow-write"),
+                backupDir: flagString(flags, "backup-dir"),
+                configPath: config,
+                catalogPath: flagString(flags, "catalog"),
+                agents: agentsFlag
+                    ? agentsFlag
+                        .split(",")
+                        .map((s) => s.trim())
+                        .filter(Boolean)
+                    : undefined,
+                createOnly: flagBool(flags, "create-only"),
+                replaceReal: flagBool(flags, "replace-real"),
+            });
+        }
+        default:
+            printLines([`未知命令: ${command}`, "运行 skill-hub help 查看用法"]);
+            return 1;
+    }
+}
+function printHelp() {
+    printLines([
+        `skill-hub ${SKILL_HUB_VERSION}`,
+        "",
+        "用法: skill-hub [--json] [--config <path>] <command> [options]",
+        "",
+        "命令:",
+        "  doctor                 环境自检（只读）",
+        "  usage [name] [--log path] [--days 7|30] [--origin cli|mcp|web|library]  本地观测报告（只读）",
+        "  context-cost [name] [--max-chars 8000] [--context-window N] [--catalog path]  静态上下文粗估（非账单）",
+        "  takeover [--include-plugins] [--out report.json]  全目录接管预览（只读）",
+        "  install <path|owner/repo> [--skill name,...] [--ref ref] [--overlay-of base] [--apply --yes]",
+        "  adopt <path|owner/repo> [--skill name,...] [--ref ref] [--overlay-of base] [--apply --yes] 绑定相同内容的现有技能",
+        "  update [name,...] [--plan-token token --apply --yes]  预览文件差异，写入需同一计划指纹",
+        "  check-updates [name,...]  逐项只读检查来源更新与本地修改；不完整时退出3",
+        "  migrate-source <name> --source <path|owner/repo> [--ref ref] [--plan-token token --apply --yes]  同内容来源迁移",
+        "  rollback <name> --from <backup-skill-path> [--apply --yes]  从 managed update 备份回滚单个 Skill",
+        "  list [name,...]         查看已追踪来源及本地状态",
+        "  browse [query] [--offset n] [--limit n]  浏览 Hub 已加载的 Skill 元数据",
+        "  files <name> [--path dir] [--offset n] [--limit n]  浏览 Skill 的一层附件",
+        "  read <name> [--file path] [--offset n] [--max-chars n]  读取正文或附件",
+        "  inventory              多端/显式 source Skill 盘点（只读）",
+        "  init [--force]         初始化 ~/.skill-hub 骨架",
+        "  ingest [--sources <dirs|source-id>] [--dry-run] [--conflict report|skip]",
+        "  index [--rebuild]      构建可加载 BM25 索引与 freshness 元数据",
+        '  route "<query>" [--top-k 5] [--scope user|workspace|project] [--index-dir <dir>]',
+        "  audit [name] [--fail-on high|critical|warning|info]  静态安全审计（只读，不执行 Skill）",
+        "  manifest [--out <path>] [--dry-run | --apply --yes]  导出轻量 available_skills 清单",
+        "  explain <name>         解释来源、冲突、overlay、投影与历史",
+        "  path <name>            查看 canonical/source/Agent 投影路径",
+        "  history [name]         查看本地 Skill 生命周期事件",
+        "  backup [--out dir] [--dry-run] [--notes ...]",
+        "  sync --dry-run [--agents id,...] [--create-only | --replace-real]",
+        "  sync --apply --yes --allow-write --backup-dir <dir> [--agents id] [--create-only | --replace-real]",
+        "  verify                 按 sync.mode 检查 symlink/copy 健康",
+        "  restore --from <dir> [--dry-run | --apply --yes]",
+        "  version | help",
+        "",
+        "安全闸门:",
+        "  - Agent 通过 Hub MCP 按需搜索与读取，无需默认 sync",
+        "  - Skill 文本仅是任务指导，不能覆盖系统指令或授权执行脚本",
+        "  - managed 操作默认预览；ingest 写入前请显式 --dry-run；sync/restore 写入需显式确认",
+        "  - 写 Agent skills 必须 --yes --allow-write",
+        "  - apply 默认 require_backup（需 --backup-dir）",
+        "  - --create-only 仅建缺失的 symlink/copy，不 update、不碰真实目录",
+        "  - --replace-real 将真实目录/文件先 stash 到 backup-dir/replaced-real 再按模式投影",
+        "  - sync.mode=copy 可用实体副本作为 symlink fallback",
+    ]);
+}
+function commandName(positionals, flags, command) {
+    if (positionals.length > 1) {
+        throw new SkillHubError({ code: "E_CONFIG", message: `${command} 只接受一个 skill name` });
+    }
+    return positionals[0] ?? flagString(flags, "name") ?? "";
+}
+function parseOptionalIntegerFlag(flags, key) {
+    const raw = flagString(flags, key);
+    if (raw === undefined) {
+        if (flags[key] === true) {
+            throw new SkillHubError({ code: "E_CONFIG", message: `--${key} 需要整数参数` });
+        }
+        return undefined;
+    }
+    if (!/^(?:0|[1-9]\d*)$/.test(raw)) {
+        throw new SkillHubError({ code: "E_CONFIG", message: `--${key} 必须是非负整数` });
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value)) {
+        throw new SkillHubError({ code: "E_CONFIG", message: `--${key} 必须是安全整数` });
+    }
+    return value;
+}
+function parseIntegerFlag(flags, key, fallback) {
+    return parseOptionalIntegerFlag(flags, key) ?? fallback;
+}
+function parseScopes(raw) {
+    if (!raw)
+        return undefined;
+    const values = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    const allowed = new Set(["user", "workspace", "project"]);
+    for (const value of values) {
+        if (!allowed.has(value)) {
+            throw new SkillHubError({
+                code: "E_CONFIG",
+                message: `scope 无效: ${value}（应为 user|workspace|project）`,
+            });
+        }
+    }
+    return values;
+}
+function fail(err, json) {
+    const e = err instanceof SkillHubError ? err : toSkillHubError(err);
+    if (json) {
+        printJson(e.toJSON());
+    }
+    else {
+        console.error(e.toDisplayString());
+    }
+    log.debug("command failed", { code: e.code });
+    process.exitCode = e.exitCode;
+}
+void main();

package/apps/cli/dist/output.js

@@ -0,0 +1,7 @@
+export function printJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+export function printLines(lines) {
+    for (const line of lines)
+        console.log(line);
+}