@zhangheteng/skill-hub 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,127 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { skillList } from "#skill-hub/router";
+import { SkillHubError } from "#skill-hub/shared";
+import { printJson, printLines } from "../output.js";
+const PAGE_SIZE = 100;
+export async function runManifest(options) {
+    const apply = options.apply === true && options.dryRun !== true;
+    const outputPath = options.outputPath?.trim() ? path.resolve(options.outputPath) : undefined;
+    if (apply && !options.yes) {
+        throw new SkillHubError({
+            code: "E_CONFIG",
+            message: "写入 manifest 需要同时指定 --apply --yes",
+        });
+    }
+    if (apply && !outputPath) {
+        throw new SkillHubError({
+            code: "E_CONFIG",
+            message: "写入 manifest 需要 --out <path>",
+        });
+    }
+    const skills = [];
+    let offset = 0;
+    while (true) {
+        const page = await skillList({
+            offset,
+            limit: PAGE_SIZE,
+            catalogPath: options.catalogPath,
+            configPath: options.configPath,
+        });
+        skills.push(...page.skills);
+        if (page.nextOffset === null)
+            break;
+        offset = page.nextOffset;
+    }
+    const content = renderAvailableSkillsManifest(skills);
+    if (apply)
+        await writeManifestAtomically(outputPath, content);
+    if (options.json) {
+        printJson({
+            skillCount: skills.length,
+            outputPath: outputPath ?? null,
+            dryRun: !apply,
+            ...(outputPath ? {} : { content }),
+        });
+    }
+    else if (!outputPath) {
+        process.stdout.write(content);
+    }
+    else {
+        printLines([
+            `manifest skills=${skills.length} ${apply ? "written" : "dry-run"}`,
+            `path: ${outputPath}`,
+        ]);
+    }
+    return 0;
+}
+export function renderAvailableSkillsManifest(skills) {
+    const entries = skills
+        .slice()
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+        .map((skill) => [
+        "  <skill>",
+        `    <name>${escapeXml(skill.name)}</name>`,
+        `    <description>${escapeXml(skill.description)}</description>`,
+        "  </skill>",
+    ].join("\n"));
+    return [
+        '<skills_system priority="1">',
+        "",
+        "## Available Skills",
+        "",
+        "<usage>",
+        "For an unknown task, use Skill Hub `skill_search`; for a known name, use `skill_read` directly.",
+        "Use `skill_files` and `skill_read` to load attachments. Read the selected skill before following it.",
+        "</usage>",
+        "",
+        "<available_skills>",
+        ...entries,
+        "</available_skills>",
+        "",
+        "</skills_system>",
+        "",
+    ].join("\n");
+}
+function escapeXml(value) {
+    const validXmlText = [...value]
+        .filter((character) => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return (codePoint === 0x09 ||
+            codePoint === 0x0a ||
+            codePoint === 0x0d ||
+            (codePoint >= 0x20 && codePoint <= 0xd7ff) ||
+            (codePoint >= 0xe000 && codePoint <= 0xfffd) ||
+            (codePoint >= 0x10000 && codePoint <= 0x10ffff));
+    })
+        .join("");
+    return validXmlText.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+async function writeManifestAtomically(filePath, content) {
+    try {
+        const target = await lstat(filePath);
+        if (!target.isFile()) {
+            throw new SkillHubError({
+                code: "E_PATH",
+                message: "manifest 输出目标必须是普通文件，不能是目录或符号链接",
+                details: { path: filePath },
+            });
+        }
+    }
+    catch (err) {
+        if (!err || typeof err !== "object" || !("code" in err) || err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+    const directory = path.dirname(filePath);
+    await mkdir(directory, { recursive: true });
+    const temporary = path.join(directory, `.skill-hub-manifest-${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, content, { encoding: "utf8", flag: "wx" });
+        await rename(temporary, filePath);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

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

@@ -0,0 +1,37 @@
+import { restoreFromBackup } from "#skill-hub/sync";
+import { SkillHubError } from "#skill-hub/shared";
+import { printJson, printLines } from "../output.js";
+/**
+ * 恢复 backup。破坏性操作，要求 --yes。
+ * 默认 dry-run；真正写入还需 --apply（与 sync 对称，避免误触）。
+ */
+export async function runRestore(options) {
+    if (!options.from) {
+        throw new SkillHubError({
+            code: "E_CONFIG",
+            message: "restore 需要 --from <backupDir|manifest.json>",
+        });
+    }
+    const wantWrite = options.apply && !options.dryRun;
+    if (wantWrite && !options.yes) {
+        throw new SkillHubError({
+            code: "E_BACKUP",
+            message: "restore 会覆盖 skills 目录，请同时传入 --yes --apply（建议先 --dry-run）",
+        });
+    }
+    const result = await restoreFromBackup(options.from, {
+        dryRun: !wantWrite,
+        agents: options.agents,
+    });
+    if (options.json)
+        printJson(result);
+    else {
+        printLines([
+            `restore ${result.dryRun ? "(dry-run)" : "APPLIED"}`,
+            `  from: ${result.manifest.backupDir}`,
+            `  restored: ${result.restored.join(", ") || "(none)"}`,
+            ...result.skipped.map((s) => `  skip ${s.id}: ${s.reason}`),
+        ]);
+    }
+    return 0;
+}

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

@@ -0,0 +1,92 @@
+import { routeWithProfile, skillSearch } from "#skill-hub/router";
+import { SkillHubError } from "#skill-hub/shared";
+import { printJson, printLines } from "../output.js";
+export async function runRoute(options) {
+    if (!options.query.trim()) {
+        throw new SkillHubError({
+            code: "E_CONFIG",
+            message: "route 需要查询字符串",
+        });
+    }
+    const result = await skillSearch({
+        query: options.query,
+        topK: options.topK,
+        profile: options.profile,
+        engine: options.engine,
+        catalogPath: options.catalogPath,
+        configPath: options.configPath,
+        indexDir: options.indexDir,
+        profilesDir: options.profilesDir,
+        scope: options.scopes,
+    });
+    const payload = {
+        query: result.query,
+        top_k: result.top_k,
+        engine: result.engineId,
+        degraded: result.degraded,
+        degrade_reason: result.degradeReason ?? null,
+        profile: result.profile,
+        profile_matched: result.profileMatched,
+        profile_fallback: result.profileFallback,
+        scope: result.scope,
+        scope_matched: result.scopeMatched,
+        candidate_count: result.candidateCount,
+        index_fresh: result.indexFresh,
+        index_rebuild_recommended: result.indexRebuildRecommended,
+        index_source: result.indexSource,
+        index_reason: result.indexReason,
+        decision: result.decision
+            ? {
+                kind: result.decision.kind,
+                model: result.decision.model,
+                selected: result.decision.selected,
+                confidence: Number(result.decision.confidence.toFixed(4)),
+                selected_probability: Number(result.decision.selectedProbability.toFixed(4)),
+                none_probability: Number(result.decision.noneProbability.toFixed(4)),
+                threshold: Number(result.decision.threshold.toFixed(4)),
+                escalation_recommended: result.decision.escalationRecommended,
+                probabilities: Object.fromEntries(Object.entries(result.decision.probabilities).map(([name, value]) => [
+                    name,
+                    Number(value.toFixed(4)),
+                ])),
+            }
+            : null,
+        results: result.results.map((r) => ({
+            name: r.name,
+            score: Number(r.score.toFixed(4)),
+            description: r.description,
+            path: r.path,
+            provenance: r.provenance ?? null,
+            reasons: r.reasons,
+        })),
+    };
+    if (options.json)
+        printJson(payload);
+    else {
+        const head = [
+            `route top-${options.topK}  engine=${payload.engine}${payload.degraded ? " (degraded)" : ""}  q="${options.query}"`,
+            `  index=${payload.index_source} fresh=${payload.index_fresh === null ? "unknown" : payload.index_fresh}${payload.index_rebuild_recommended ? " → 请运行 index --rebuild" : ""}`,
+        ];
+        if (payload.profile) {
+            head.push(`  profile=${payload.profile} matched=${payload.profile_matched ?? 0} fallback=${payload.profile_fallback} candidates=${payload.candidate_count}`);
+        }
+        if (payload.scope?.length) {
+            head.push(`  scope=${payload.scope.join(",")} matched=${payload.scope_matched ?? 0} candidates=${payload.candidate_count}`);
+        }
+        if (payload.decision) {
+            head.push(`  decision selected=${payload.decision.selected ?? "none"} confidence=${payload.decision.confidence.toFixed(3)}${payload.decision.escalation_recommended ? " → 建议升级判断" : ""}`);
+        }
+        if (payload.results.length === 0) {
+            printLines([...head, "  (无结果)"]);
+        }
+        else {
+            printLines([
+                ...head,
+                ...payload.results.map((r, i) => `  ${String(i + 1).padStart(2)}. ${r.name.padEnd(28)} ${r.score.toFixed(3)}  ${r.description.slice(0, 56)}`),
+            ]);
+        }
+    }
+    void options.includeBody;
+    void routeWithProfile;
+    return 0;
+}

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

@@ -0,0 +1,89 @@
+import { skillFiles, skillList, skillRead } from "#skill-hub/router";
+import { SkillHubError } from "#skill-hub/shared";
+import { printJson, printLines } from "../output.js";
+export async function runBrowse(options) {
+    const result = await skillList({
+        query: options.query,
+        offset: options.offset,
+        limit: options.limit,
+        catalogPath: options.catalogPath,
+        configPath: options.configPath,
+    });
+    if (options.json) {
+        printJson(result);
+        return 0;
+    }
+    printLines([
+        `browse total=${result.total} offset=${result.offset}`,
+        ...(result.skills.length
+            ? result.skills.map((skill) => `  ${skill.name}  ${skill.description}`)
+            : ["  (无结果)"]),
+    ]);
+    printNextOffset("browse", options.query, result.nextOffset);
+    return 0;
+}
+export async function runFiles(options) {
+    requireName(options.name, "files");
+    const result = await skillFiles({
+        name: options.name,
+        path: options.path,
+        offset: options.offset,
+        limit: options.limit,
+        catalogPath: options.catalogPath,
+        configPath: options.configPath,
+    });
+    if (options.json) {
+        printJson(result);
+        return 0;
+    }
+    printLines([
+        `files ${result.name} path=${result.path || "."} total=${result.total} offset=${result.offset}`,
+        ...(result.files.length
+            ? result.files.map((file) => {
+                const size = file.size === undefined ? "" : ` size=${file.size}`;
+                const reason = file.reason ? ` ${file.reason}` : "";
+                return `  ${file.type.padEnd(9)} ${file.path}${size}${reason}`;
+            })
+            : ["  (空目录)"]),
+    ]);
+    printNextOffset("files", options.name, result.nextOffset, options.path);
+    return 0;
+}
+export async function runRead(options) {
+    requireName(options.name, "read");
+    const result = await skillRead({
+        name: options.name,
+        file: options.file,
+        offset: options.offset,
+        maxChars: options.maxChars,
+        catalogPath: options.catalogPath,
+        configPath: options.configPath,
+    });
+    if (options.json) {
+        printJson(result);
+        return 0;
+    }
+    // 正文可直接管道给 Agent；分页说明始终写 stderr，避免混入正文。
+    process.stdout.write(result.body);
+    if (result.nextOffset !== null) {
+        const file = result.file === "SKILL.md" ? "" : ` --file ${quote(result.file)}`;
+        console.error(`\n续读: skill-hub read ${quote(result.name)}${file} --offset ${result.nextOffset}`);
+    }
+    return 0;
+}
+function requireName(name, command) {
+    if (!name.trim()) {
+        throw new SkillHubError({ code: "E_CONFIG", message: `${command} 需要 skill name` });
+    }
+}
+function printNextOffset(command, nameOrQuery, nextOffset, path) {
+    if (nextOffset === null)
+        return;
+    const target = nameOrQuery?.trim() ? ` ${quote(nameOrQuery)}` : "";
+    const pathFlag = path?.trim() ? ` --path ${quote(path)}` : "";
+    console.error(`续读: skill-hub ${command}${target}${pathFlag} --offset ${nextOffset}`);
+}
+function quote(value) {
+    // POSIX 单引号可防止 $(), 反引号和空白在复制续读命令时被 shell 解释。
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}

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

@@ -0,0 +1,195 @@
+import { lstat } from "node:fs/promises";
+import { appendHistoryBatch, catalogToSkillMetas, loadHubConfig, readCatalog, resolveHubConfigPaths, scanSkills, } from "#skill-hub/core";
+import { applySync, assertBackupReady, filterGlobalSyncSkills, planSync } from "#skill-hub/sync";
+import { SkillHubError, getDefaultHubHome, hubLayout, resolveAbsolutePath, } from "#skill-hub/shared";
+import path from "node:path";
+import { printJson, printLines } from "../output.js";
+export async function runSync(options) {
+    const wantApply = options.apply && !options.dryRun;
+    if (options.createOnly && options.replaceReal) {
+        throw new SkillHubError({
+            code: "E_SYNC",
+            message: "--create-only 与 --replace-real 互斥，请只选其一。",
+        });
+    }
+    // 生产写入双重闸门：--apply --yes --allow-write
+    if (wantApply) {
+        if (!options.yes || !options.allowWrite) {
+            throw new SkillHubError({
+                code: "E_SYNC",
+                message: "sync --apply 需要同时提供 --yes --allow-write（将修改各 Agent skills 目录的 symlink）。可先 --dry-run。",
+            });
+        }
+    }
+    const dryRun = !wantApply;
+    const config = resolveHubConfigPaths(options.configPath ? await loadHubConfig(options.configPath) : await loadHubConfig());
+    const requireBackup = options.requireBackup ||
+        (wantApply && config.sync.require_backup) ||
+        (wantApply && options.replaceReal);
+    if (wantApply && requireBackup) {
+        const backupDir = options.backupDir;
+        if (!backupDir) {
+            throw new SkillHubError({
+                code: "E_BACKUP",
+                message: "sync --apply 要求备份：请先 skill-hub backup，并用 --backup-dir <path> 指向含 manifest.json 的备份目录（replace-real 强制需要）",
+            });
+        }
+        await assertBackupReady(backupDir, {
+            ...config,
+            agents: config.agents.filter((a) => !options.agents?.length || options.agents.includes(a.id)),
+        });
+    }
+    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)}`,
+            });
+    }
+    // project/workspace source 是盘点/项目路由输入，不默认投影到全局 Agent。
+    // 旧 catalog 无 provenance 时按 user 兼容处理。
+    const filteredByScope = filterGlobalSyncSkills(skills);
+    const excludedByScope = filteredByScope.excluded;
+    skills = filteredByScope.skills;
+    const plan = await planSync(config, skills, {
+        dryRun,
+        agents: options.agents,
+        createOnly: options.createOnly,
+        replaceReal: options.replaceReal,
+    });
+    const modeNote = [
+        options.agents?.length ? `agents=${options.agents.join(",")}` : "agents=all-enabled",
+        options.createOnly ? "create-only" : options.replaceReal ? "replace-real" : "full-actions",
+    ].join(" ");
+    const replaceStashDir = options.backupDir
+        ? path.join(resolveAbsolutePath(options.backupDir), "replaced-real")
+        : undefined;
+    if (!wantApply) {
+        const createItems = plan.items.filter((i) => i.action === "create_symlink" || i.action === "create_copy");
+        const replaceItems = plan.items.filter((i) => i.action === "replace_real" || i.action === "replace_real_copy");
+        const updateItems = plan.items.filter((i) => i.action === "update_symlink" || i.action === "update_copy");
+        const skippedItems = plan.items.filter((i) => i.action === "skipped");
+        const result = {
+            dryRun: true,
+            require_backup: requireBackup,
+            createOnly: options.createOnly,
+            replaceReal: options.replaceReal,
+            agents: options.agents ?? null,
+            replace_stash_dir: replaceStashDir ?? null,
+            summary: plan.summary,
+            mode: plan.mode,
+            itemCount: plan.items.length,
+            createCount: createItems.length,
+            replaceCount: replaceItems.length,
+            updateCount: updateItems.length,
+            skippedCount: skippedItems.length,
+            excludedByScope,
+            items: plan.items,
+            note: `dry-run (${modeNote})：未修改任何路径。apply 需 --apply --yes --allow-write --backup-dir${options.replaceReal ? " --replace-real" : ""}${options.createOnly ? " --create-only" : ""}`,
+        };
+        if (options.json)
+            printJson(result);
+        else {
+            printLines([
+                `sync plan (dry-run=true mode=${plan.mode} ${modeNote})`,
+                `  create=${plan.summary.create} update=${plan.summary.update} replace=${plan.summary.replace} conflict=${plan.summary.conflict} noop=${plan.summary.noop} skipped=${skippedItems.length}`,
+                ...replaceItems
+                    .slice(0, 30)
+                    .map((i) => `  [replace] ${i.agentId}:${i.skillName} → stash then → ${i.source}`),
+                replaceItems.length > 30 ? `  ... +${replaceItems.length - 30} more replaces` : "",
+                ...createItems
+                    .slice(0, 20)
+                    .map((i) => `  [create] ${i.agentId}:${i.skillName} → ${i.target}`),
+                createItems.length > 20 ? `  ... +${createItems.length - 20} more creates` : "",
+                options.replaceReal
+                    ? `  note: replace-real 将把真实目录/文件迁入 ${replaceStashDir ?? "<backup-dir>/replaced-real"}`
+                    : "",
+                options.createOnly ? `  note: create-only 已将非 create 项标为 skipped` : "",
+                excludedByScope.length > 0
+                    ? `  note: 已排除 ${excludedByScope.length} 个 project/workspace Skill（默认不投影到全局 Agent）`
+                    : "",
+                result.note,
+            ].filter(Boolean));
+        }
+        if (options.createOnly)
+            return 0;
+        return plan.summary.conflict > 0 ? 2 : 0;
+    }
+    const applied = await applySync(plan, {
+        dryRun: false,
+        createOnly: options.createOnly,
+        replaceStashDir: options.replaceReal ? replaceStashDir : undefined,
+    });
+    const result = {
+        dryRun: false,
+        require_backup: requireBackup,
+        backup_dir: options.backupDir ?? null,
+        replace_stash_dir: options.replaceReal ? (replaceStashDir ?? null) : null,
+        createOnly: options.createOnly,
+        replaceReal: options.replaceReal,
+        mode: plan.mode,
+        agents: options.agents ?? null,
+        plan_summary: plan.summary,
+        excludedByScope,
+        apply: {
+            applied: applied.applied,
+            skipped: applied.skipped,
+            failed: applied.failed,
+        },
+        items: applied.items,
+    };
+    if (applied.applied > 0) {
+        await appendHistoryBatch(layout.history, applied.items
+            .filter((item) => item.result === "applied")
+            .map((item) => ({
+            at: new Date().toISOString(),
+            type: "sync",
+            name: item.skillName,
+            action: item.action,
+            agentId: item.agentId,
+            target: item.target,
+            path: item.source,
+            detail: { mode: plan.mode },
+        })));
+    }
+    if (options.json)
+        printJson(result);
+    else {
+        printLines([
+            `sync APPLY (mode=${plan.mode} ${modeNote})`,
+            `  plan: create=${plan.summary.create} update=${plan.summary.update} replace=${plan.summary.replace} conflict=${plan.summary.conflict} noop=${plan.summary.noop}`,
+            `  result: applied=${applied.applied} skipped=${applied.skipped} failed=${applied.failed}`,
+            options.replaceReal && replaceStashDir ? `  stash: ${replaceStashDir}` : "",
+            ...applied.items
+                .filter((i) => i.result === "applied")
+                .slice(0, 40)
+                .map((i) => `  + ${i.action} ${i.agentId}:${i.skillName}`),
+            applied.applied > 40 ? `  ... +${applied.applied - 40} more` : "",
+            ...applied.items
+                .filter((i) => i.result === "failed")
+                .map((i) => `  FAIL ${i.agentId}:${i.skillName} ${i.error ?? ""}`),
+        ].filter(Boolean));
+    }
+    if (applied.failed > 0)
+        return 1;
+    if (!options.createOnly && plan.summary.conflict > 0)
+        return 2;
+    return 0;
+}

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

@@ -0,0 +1,45 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { inspectTakeover, loadHubConfig, resolveHubConfigPaths, } from "#skill-hub/core";
+import { printJson, printLines } from "../output.js";
+export async function runTakeover(options) {
+    const config = resolveHubConfigPaths(await loadHubConfig(options.configPath));
+    const roots = [
+        { id: "hub", path: config.canonical_dir, ownership: "canonical" },
+        ...config.agents
+            .filter((a) => a.enabled)
+            .map((a) => ({ id: a.id, path: a.skills_dir, ownership: "agent" })),
+        ...(config.sources ?? [])
+            .filter((s) => s.enabled)
+            .map((s) => ({ id: s.id, path: s.path, ownership: "source" })),
+    ];
+    if (options.includePlugins) {
+        for (const relative of [
+            ".codex/plugins/cache",
+            ".claude/plugins/cache",
+            ".codex/skills/.system",
+        ]) {
+            roots.push({ id: relative, path: path.join(homedir(), relative), ownership: "external" });
+        }
+    }
+    const report = await inspectTakeover(roots, config.canonical_dir);
+    if (options.out) {
+        const output = path.resolve(options.out);
+        await mkdir(path.dirname(output), { recursive: true });
+        await writeFile(output, `${JSON.stringify(report, null, 2)}\n`);
+    }
+    if (options.json)
+        printJson(report);
+    else
+        printLines([
+            "takeover（只读接管预览）",
+            JSON.stringify(report.summary, null, 2),
+            report.note,
+            ...report.skills
+                .filter((s) => s.action === "conflict" || s.action === "blocked")
+                .map((s) => `  ${s.action}: ${s.name}`),
+            ...(options.out ? [`报告: ${path.resolve(options.out)}`] : []),
+        ]);
+    return report.summary.conflicts || report.summary.issues ? 2 : 0;
+}

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

@@ -0,0 +1,55 @@
+import path from "node:path";
+import { readUsageReport } from "#skill-hub/core";
+import { skillContextCost } from "#skill-hub/router";
+import { SkillHubError, getDefaultHubHome } from "#skill-hub/shared";
+import { printJson, printLines } from "../output.js";
+function integer(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)))
+        throw new SkillHubError({ code: "E_CONFIG", message: "数值参数须为非负安全整数" });
+    return Number(value);
+}
+export async function runUsage(options) {
+    const file = options.file ??
+        process.env.SKILL_HUB_USAGE_LOG ??
+        path.join(getDefaultHubHome(), "usage.jsonl");
+    const report = {
+        ...(await readUsageReport({
+            file,
+            days: integer(options.days),
+            name: options.name,
+            origin: options.origin,
+        })),
+        recordingEnabled: Boolean(process.env.SKILL_HUB_USAGE_LOG),
+    };
+    if (options.json)
+        printJson(report);
+    else
+        printLines([
+            `Hub使用观测 complete=${report.complete} exists=${report.exists} recordingEnabled=${report.recordingEnabled}`,
+            `日志: ${report.file}；最早可见记录: ${report.recordedSince ?? "未知"}`,
+            `search=${report.searchCalls} read=${report.readCalls} errors=${report.errors}`,
+            ...report.skills.map((s) => `${s.name} [${s.origin}] 候选出现=${s.appearances} 正文首段=${s.initialBodyReads} 续读=${s.continuationBodyReads} 附件=${s.attachmentReads} 错误=${s.errors} 返回文本粗估tokens=${s.estimatedReturnedTokens} 最近读取=${s.lastReadAt ?? "未知"}`),
+            ...report.issues.map((i) => `日志第${i.line}行 ${i.code}`),
+            "仅代表Hub服务调用；未记录历史未知，首段次数不等于唯一任务数。Token为启发式估算，模型真实Token和费用未知。",
+        ]);
+    return report.complete ? 0 : 3;
+}
+export async function runContextCost(options) {
+    const report = await skillContextCost({
+        ...options,
+        maxChars: integer(options.maxChars),
+        contextWindow: integer(options.contextWindow),
+    });
+    if (options.json)
+        printJson(report);
+    else
+        printLines([
+            `静态上下文粗估 (${report.method}) complete=${report.complete}`,
+            `元数据合计≈${report.metadataTotalEstimatedTokens} tokens；首段maxChars=${report.maxChars}；contextWindow=${report.contextWindow ?? "未指定"}`,
+            ...report.items.map((s) => `${s.name} 元数据≈${s.metadata.estimatedTokens} 正文全文≈${s.fullBody?.estimatedTokens ?? "未知"} 首段≈${s.initialPage?.estimatedTokens ?? "未知"} tokens${s.initialPageContextPercent === null ? "" : ` 首段占窗口≈${s.initialPageContextPercent}%`}${s.errorCode ? ` ${s.errorCode}` : ""}`),
+            "粗略比较值，不是tokenizer/模型账单。附件、工具定义、封装、历史与缓存不计；不代表全库会被注入。",
+        ]);
+    return report.complete ? 0 : 3;
+}