@bolloon/bolloon-agent 0.4.24 → 0.4.25

package/dist/agents/runner-resolver.js

@@ -0,0 +1,225 @@
+/**
+ * runner-resolver.ts — 独立宿主的**分阶段**执行器解析 (2026-09-16, 批次 2-C.2)
+ *
+ * 起因: 独立宿主"没有 tick 日志、没有建 Run"这种故障无法定位 —— 20 秒超时只能说"超时",
+ * 说不出卡在哪。这一层把解析拆成有序阶段, 每阶段记 开始/结束/耗时/失败分类/超时原因:
+ *
+ *   resolve_goal → resolve_agent → load_identity → load_session → load_skills
+ *                → init_llm → create_session → prepare_resume → ready
+ *
+ * 任一必需阶段失败 → `{ ok:false, kind:'unresolved', reason:'<阶段>: <原因>', stages }`
+ *  → Supervisor **只诊断**: 不建 Run、不改 Goal 状态、不伪造失败; 原因进 wakeReport/宿主状态。
+ *
+ * 顺带修一个真根因: 独立宿主此前**没有初始化 LLM 层**, 于是 `PiAgentSession.prompt()` 判定
+ * `minimaxAvailable=false` 走 fallback 提前返回 —— 既不调模型也不建 Run, 上层只看到"执行完成但没有 Run"。
+ * 现在 `init_llm` 是必需阶段, LLM 不可用直接 unresolved (而不是偷偷退化成 fallback)。
+ */
+import * as os from 'os';
+import * as path from 'path';
+import * as fsp from 'fs/promises';
+import { readGoal } from './goal-store.js';
+import { buildContinuationPlan } from './run-store.js';
+export const RESOLVE_STAGES = [
+    'resolve_goal',
+    'resolve_agent',
+    'load_identity',
+    'load_session',
+    'load_skills',
+    'init_llm',
+    'create_session',
+    'prepare_resume',
+    'ready',
+];
+function classify(err, stage) {
+    const m = String(err?.message || err || '').toLowerCase();
+    if (m.includes('超时') || m.includes('timeout'))
+        return 'timeout';
+    if (stage === 'init_llm')
+        return 'config';
+    if (m.includes('eacces') || m.includes('enoent') || m.includes('eperm'))
+        return 'io';
+    return 'unknown';
+}
+/** 读本机 LLM 配置摘要 (只看结构与有无, 不打印任何密钥) */
+export async function probeLlmConfig(home = os.homedir()) {
+    try {
+        const raw = JSON.parse(await fsp.readFile(path.join(home, '.bolloon', 'llm-config.json'), 'utf8'));
+        const active = raw.activeProvider || raw.provider;
+        const providers = raw.providers || {};
+        const p = providers[active] || {};
+        const needsKey = p.requiresApiKey !== false;
+        const hasKey = !!(p.apiKey || p.api_key || process.env[`${String(active).toUpperCase()}_API_KEY`]);
+        if (!active)
+            return { ok: false, reason: 'llm-config.json 没有 activeProvider' };
+        if (needsKey && !hasKey)
+            return { ok: false, provider: active, model: p.model, hasKey: false, reason: `provider ${active} 需要 apiKey 但没配` };
+        return { ok: true, provider: active, model: p.model, hasKey };
+    }
+    catch (err) {
+        return { ok: false, reason: `llm-config.json 不可读: ${String(err?.message || err).slice(0, 100)}` };
+    }
+}
+async function stage(stages, name, required, timeoutMs, fn, log, noteOf) {
+    const t0 = Date.now();
+    log?.(`[resolver] ${name} 开始`);
+    try {
+        const value = await Promise.race([
+            fn(),
+            new Promise((_r, rej) => {
+                const t = setTimeout(() => rej(new Error(`${name} 超时 (${timeoutMs}ms)`)), timeoutMs);
+                t.unref?.();
+            }),
+        ]);
+        const report = { stage: name, ok: true, ms: Date.now() - t0, required, note: noteOf?.(value) };
+        stages.push(report);
+        log?.(`[resolver] ${name} 完成 ${report.ms}ms`);
+        return { ok: true, value, report };
+    }
+    catch (err) {
+        const report = {
+            stage: name, ok: false, ms: Date.now() - t0, required,
+            error: String(err?.message || err).slice(0, 200),
+            errorClass: classify(err, name),
+        };
+        stages.push(report);
+        log?.(`[resolver] ${name} 失败 ${report.ms}ms: ${report.error}`);
+        return { ok: false, report };
+    }
+}
+/** 阶段报告一行摘要 (CLI / 日志 / wakeReport 用) */
+export function formatStages(stages) {
+    return stages.map((s) => `${s.stage}${s.ok ? '✓' : '✗'}${s.ms}ms`).join(' → ');
+}
+/**
+ * 分阶段解析"谁来执行这个 Goal"。
+ * 与 web 宿主同构: 都返回一个 runner; 差别只在"用什么上下文建 session"。
+ */
+export async function resolveGoalRunner(req, opts = {}) {
+    const home = opts.home ?? os.homedir();
+    const cwd = opts.cwd ?? process.cwd();
+    const log = opts.log;
+    const stageTimeout = opts.stageTimeoutMs ?? 30_000;
+    const createTimeout = opts.createTimeoutMs ?? (Number(process.env.BOLLOON_SUPERVISE_CREATE_TIMEOUT_MS) || 20_000);
+    const stages = [];
+    const fail = (report, reason) => ({
+        ok: false, kind: 'none', reason, stages, failedStage: report.stage,
+    });
+    if (opts.allow === false) {
+        return fail({ stage: 'resolve_goal', ok: false, ms: 0, required: true, error: '本地执行被显式关闭' }, 'resolve_goal: 本地执行被显式关闭 (BOLLOON_SUPERVISE_AGENT=0) → 只诊断');
+    }
+    // 1. resolve_goal —— 目标是否可执行
+    const g = req.goal;
+    const goalCheck = await stage(stages, 'resolve_goal', true, stageTimeout, async () => {
+        if (!g?.goalId)
+            throw new Error('没有 goalId');
+        const fresh = await readGoal(g.goalId);
+        if (!fresh)
+            throw new Error(`Goal 不存在: ${g.goalId}`);
+        if (fresh.status === 'paused' || fresh.status === 'needs_human')
+            throw new Error(`Goal 状态 ${fresh.status} 不允许自动执行`);
+        return fresh;
+    }, log);
+    if (!goalCheck.ok)
+        return fail(goalCheck.report, `resolve_goal: ${goalCheck.report.error} → 只诊断, Goal 状态未改动`);
+    const goal = goalCheck.value;
+    // 2. resolve_agent —— 用哪个 agent 身份执行
+    const agentCheck = await stage(stages, 'resolve_agent', true, stageTimeout, async () => {
+        if (!goal.channelId && !req.prevRunId)
+            throw new Error('Goal 没有 channelId (无法确定 agent 上下文)');
+        return { channelId: goal.channelId || '', agentId: goal.agentId || '' };
+    }, log);
+    if (!agentCheck.ok)
+        return fail(agentCheck.report, `resolve_agent: ${agentCheck.report.error} → 只诊断 (不建 Run)`);
+    const { channelId, agentId } = agentCheck.value;
+    // 3. load_identity —— 身份可读性 (缺身份不致命, 但要留痕)
+    await stage(stages, 'load_identity', false, stageTimeout, async () => {
+        const files = ['keypair.json', 'agent-registry.json'].map((f) => path.join(home, '.bolloon', f));
+        const found = [];
+        for (const f of files)
+            if (await fsp.stat(f).then(() => true).catch(() => false))
+                found.push(path.basename(f));
+        return found;
+    }, log, (found) => (found.length ? `身份文件: ${found.join(', ')}` : '无身份文件 (用系统临时身份)'));
+    // 4. load_session —— 会话存储可读性
+    await stage(stages, 'load_session', false, stageTimeout, async () => {
+        const dir = path.join(home, '.bolloon', 'sessions');
+        return fsp.stat(dir).then((st) => st.isDirectory()).catch(() => false);
+    }, log, (ok) => (ok ? `会话目录可读: ${path.join(home, '.bolloon', 'sessions')}` : '会话目录不存在 (将新建)'));
+    // 5. load_skills —— 技能视图可读性 (2-G.2 起会变成必需阶段)
+    await stage(stages, 'load_skills', false, stageTimeout, async () => {
+        const { getSkillsManager } = await import('./skills-manager.js');
+        const list = await getSkillsManager({ home, cwd }).view();
+        return { total: list.length, enabled: list.filter((s) => s.status === 'enabled').length, invalid: list.filter((s) => s.status === 'invalid').length };
+    }, log, (r) => `技能视图: ${r.total} 个 (enabled ${r.enabled}, invalid ${r.invalid})`);
+    // 6. init_llm —— **必需**: LLM 可用 (否则 agent 会退化成 fallback, 既不调模型也不建 Run)
+    const llmCheck = await stage(stages, 'init_llm', true, stageTimeout, async () => {
+        const probe = opts.probeLlm ? await opts.probeLlm() : await probeLlmConfig(home);
+        if (!probe.ok)
+            throw new Error(probe.reason || 'LLM 不可用');
+        const { initMinimax } = await import('../constraints/index.js');
+        initMinimax();
+        return probe;
+    }, log, (probe) => `provider=${probe.provider} model=${probe.model ?? '(默认)'} key=${probe.hasKey ? '有' : '免'}`);
+    if (!llmCheck.ok) {
+        return fail(llmCheck.report, `init_llm: ${llmCheck.report.error} → 只诊断 (不发起会退化成 fallback 的执行)`);
+    }
+    // 7. create_session —— 真 agent session
+    let agent;
+    const sessCheck = await stage(stages, 'create_session', true, createTimeout, async () => {
+        if (opts.createAgent) {
+            agent = await opts.createAgent(channelId, goal.goalId);
+            return true;
+        }
+        const { createAgentSession } = await import('./pi-sdk.js');
+        agent = await createAgentSession({ cwd, peerId: `supervise:${channelId || agentId}`, channelId: channelId || undefined }, true);
+        return !!agent;
+    }, log);
+    if (!sessCheck.ok || !agent)
+        return fail(sessCheck.report, `create_session: ${sessCheck.report.error} → 只诊断 (不建 Run)`);
+    // 8. prepare_resume —— 恢复计划 (只读; 真正 prepareResume 由 runner 在运行时做, 保证状态迁移与执行同一时刻)
+    let resumeNote = '新 Run (无历史)';
+    if (req.prevRunId) {
+        const planCheck = await stage(stages, 'prepare_resume', false, stageTimeout, async () => {
+            const plan = await buildContinuationPlan(req.prevRunId);
+            if (!plan)
+                throw new Error(`读不到上一条 Run: ${req.prevRunId}`);
+            resumeNote = `已完成 ${plan.completedSteps.length} 步, 非幂等守卫 ${plan.replayGuards.length} 条`;
+            return plan;
+        }, log);
+        if (!planCheck.ok)
+            resumeNote = `恢复计划读取失败: ${planCheck.report.error}`;
+    }
+    stages.push({ stage: 'ready', ok: true, ms: 0, required: true, note: `runner 就绪 (channel=${channelId || '-'}, ${resumeNote})` });
+    const runner = async (r) => {
+        if (r.kind === 'resume' && r.prevRunId && typeof agent.resumeRun === 'function') {
+            const res = await agent.resumeRun(r.prevRunId);
+            return { runId: r.prevRunId, status: res?.ok ? 'done' : 'failed', error: res?.ok ? undefined : res?.reason };
+        }
+        agent.setGoalId?.(goal.goalId);
+        agent.setContinuationGuards?.(r.guards || []);
+        const reply = await agent.prompt(r.instruction);
+        const runId = agent.getLastRunId?.() || agent.getRunId?.() || '';
+        // 没有 Run = 这次执行没有事实记录: 如实报告, 不让上层把"没跑"当"跑完"
+        if (!runId) {
+            return { status: 'failed', error: `执行没有产生 Run 记录 (agent 可能走了 fallback/未初始化路径): ${String(reply || '').slice(0, 120)}` };
+        }
+        return { runId, status: 'done', reply: typeof reply === 'string' ? reply.slice(0, 500) : undefined };
+    };
+    return { ok: true, kind: 'standalone', runner, stages };
+}
+/** 已启动的独立宿主把最近一次解析报告写给上层 (wakeReport / API / CLI 用) */
+export function latestFailedStage(res) {
+    return { stage: res.failedStage, reason: res.ok ? undefined : res.reason };
+}
+/** 供 CLI/诊断: 一次解析的完整人类可读报告 */
+export function describeResolution(res) {
+    const failed = res.stages.find((s) => !s.ok);
+    const head = res.ok ? '✅ 可执行' : `⛔ 不可执行 (卡在 ${res.failedStage})`;
+    const lines = [`${head}${res.reason ? ` — ${res.reason}` : ''}`, `阶段: ${formatStages(res.stages)}`];
+    for (const s of res.stages)
+        if (s.note)
+            lines.push(`  · ${s.stage}: ${s.note}`);
+    if (failed?.error)
+        lines.push(`  ✗ 失败分类=${failed.errorClass} 原因=${failed.error}`);
+    return lines.join('\n');
+}

package/dist/agents/skills-manager.js

@@ -0,0 +1,435 @@
+/**
+ * skills-manager.ts — Skills Manager Runtime 的统一门面 (2026-09-16, 批次 2-G.1)
+ *
+ * 之前的问题: 技能能力被拆成四个各自为政的入口 (skill-loader 扫描 / skill-share 打包分享 /
+ * skill-writer 生成 / skill-organizer 整理), 谁也不知道"这个技能现在到底是什么状态、来自哪里、能不能用",
+ * CLI / Web / agent 各看各的。长期执行的 Goal 因此无法固定"我依赖的技能是哪一版"。
+ *
+ * 这一层做的事 (2-G.1 范围):
+ *   - **统一事实模型**: 每个技能一条 `SkillRecord` (skillId/name/version/contentHash/source/sourceRef/
+ *     status/trust/compatibility/installedAt/updatedAt);
+ *   - **统一入口**: discover / inspect / install / import / enable / disable / validate / resolve /
+ *     snapshot / health / export —— CLI / Web / Supervisor / agent 都只走这里, 不再各自直调底层模块;
+ *   - **内容真值仍是 SKILL.md**, 管理元数据落在 `~/.bolloon/skills-registry.json` (不让 loader/share/writer 各自推断)。
+ *
+ * 2-G.1 **刻意不改执行行为**: enable/disable/status 只被记录与展示; 真正用它拦执行 (readiness gate)
+ * 与 Goal 级 skill snapshot 属 2-G.2/2-G.4。
+ */
+import * as os from 'os';
+import * as path from 'path';
+import * as fsp from 'fs/promises';
+import * as crypto from 'crypto';
+import { parseSkillFile, defaultSkillPaths } from './skill-loader.js';
+import { getUserSkillsDir } from './skill-writer.js';
+import { collectSkillBundle, parseSkillBundle, parseSkillRef, fetchSkillBundle, installSkillBundle, } from './skill-share.js';
+// ─────────────────────────────────────────────────────────────────────────────
+export function registryPath(home = os.homedir()) {
+    return path.join(home, '.bolloon', 'skills-registry.json');
+}
+async function readRegistry(home) {
+    try {
+        const raw = JSON.parse(await fsp.readFile(registryPath(home), 'utf8'));
+        if (raw && typeof raw.skills === 'object' && raw.skills)
+            return raw;
+    }
+    catch { /* 缺文件/坏文件 → 空 registry (不阻挡发现) */ }
+    return { schema: 'bolloon-skills-registry/1', skills: {}, updatedAt: new Date(0).toISOString() };
+}
+async function writeRegistry(reg, home) {
+    const p = registryPath(home);
+    await fsp.mkdir(path.dirname(p), { recursive: true });
+    reg.updatedAt = new Date().toISOString();
+    const tmp = `${p}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(reg, null, 2), 'utf8');
+    await fsp.rename(tmp, p); // 原子替换
+}
+/** 技能目录内容摘要: 排序后逐文件 sha256 → 再摘要一次 (目录整体指纹) */
+export async function hashSkillDir(dir) {
+    const issues = [];
+    const files = [];
+    let bytes = 0;
+    const walk = async (d, prefix) => {
+        let entries;
+        try {
+            entries = await fsp.readdir(d, { withFileTypes: true });
+        }
+        catch (err) {
+            issues.push(`目录不可读: ${String(err?.message || err).slice(0, 80)}`);
+            return;
+        }
+        for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (e.name.startsWith('.'))
+                continue;
+            const abs = path.join(d, e.name);
+            const rel = prefix ? `${prefix}/${e.name}` : e.name;
+            if (e.isSymbolicLink()) {
+                issues.push(`符号链接被跳过 (避免越界): ${rel}`);
+                continue;
+            }
+            if (e.isDirectory()) {
+                await walk(abs, rel);
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            try {
+                const buf = await fsp.readFile(abs);
+                bytes += buf.length;
+                files.push({ rel, content: buf });
+            }
+            catch (err) {
+                issues.push(`文件不可读: ${rel} (${String(err?.message || err).slice(0, 60)})`);
+            }
+        }
+    };
+    await walk(dir, '');
+    const h = crypto.createHash('sha256');
+    for (const f of files) {
+        h.update(f.rel);
+        h.update('\0');
+        h.update(crypto.createHash('sha256').update(f.content).digest());
+    }
+    return { hash: h.digest('hex').slice(0, 32), fileCount: files.length, bytes, issues };
+}
+/** 单条记录的结构校验 (纯函数, 可单测) */
+export function validateSkillRecord(input) {
+    const issues = [...(input.issues || [])];
+    if (!input.name || !/^[a-z0-9_-]{1,64}$/i.test(input.name))
+        issues.push('技能名非法 (只允许字母数字下划线连字符, ≤64)');
+    if (!input.description || input.description.trim().length < 4)
+        issues.push('缺少 description (SKILL.md frontmatter)');
+    if (!input.body || input.body.trim().length < 20)
+        issues.push('正文内容过少 (可能不是有效的 SKILL.md)');
+    if (input.bytes > 2 * 1024 * 1024)
+        issues.push(`技能体积过大 (${Math.round(input.bytes / 1024)}KB > 2MB)`);
+    const fmStatus = String(input.frontmatter?.status ?? 'active');
+    if (!['active', 'archived', 'draft'].includes(fmStatus))
+        issues.push(`frontmatter.status 非法: ${fmStatus}`);
+    return issues;
+}
+export class SkillsManager {
+    home;
+    cwd;
+    cache = null;
+    /** 同名技能出现在哪些目录 (discover 时记录; 同名会被覆盖成一条记录, 重复必须单独留痕) */
+    dirsByName = new Map();
+    constructor(opts = {}) {
+        this.home = opts.home ?? os.homedir();
+        this.cwd = opts.cwd ?? process.cwd();
+    }
+    /** 技能搜索路径 (去重, 顺序 = 优先级从低到高) */
+    skillDirs() {
+        const out = [
+            { dir: path.join(this.cwd, '.bolloon', 'skills'), source: 'project' },
+            { dir: getUserSkillsDir(this.home), source: 'user' },
+        ];
+        for (const p of defaultSkillPaths(this.home, this.cwd)) {
+            if (!out.some((x) => x.dir === p))
+                out.push({ dir: p, source: 'user' });
+        }
+        return out;
+    }
+    /** 扫描所有技能目录 + registry → 统一视图 (同名: 后者覆盖前者, 与 loader 语义一致) */
+    async discover(opts = {}) {
+        const home = opts.home ?? this.home;
+        const reg = await readRegistry(home);
+        const byName = new Map();
+        const dirsByName = new Map();
+        for (const { dir, source } of this.skillDirs()) {
+            let entries;
+            try {
+                entries = await fsp.readdir(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const e of entries) {
+                if (!e.isDirectory() || e.name.startsWith('.'))
+                    continue;
+                const skillDir = path.join(dir, e.name);
+                const skillFile = path.join(skillDir, 'SKILL.md');
+                const meta = await parseSkillFile(skillFile).catch(() => null);
+                const counted = await hashSkillDir(skillDir);
+                if (!meta) {
+                    // 目录在但不是有效技能: 也进视图 (状态 invalid), 不许静默消失
+                    const rec = this.buildRecord({
+                        name: e.name, description: '', version: '0.0.0', frontmatter: {}, body: '',
+                        dir: skillDir, skillFile, source, hash: counted.hash, fileCount: counted.fileCount,
+                        bytes: counted.bytes, issues: [`SKILL.md 缺失或无法解析`, ...counted.issues], reg,
+                    });
+                    byName.set(rec.name, rec);
+                    dirsByName.set(rec.name, [...(dirsByName.get(rec.name) || []), skillDir]);
+                    continue;
+                }
+                const rec = this.buildRecord({
+                    name: meta.name || e.name, description: meta.description, version: String(meta.frontmatter?.version ?? '0.0.0'),
+                    frontmatter: meta.frontmatter, body: meta.body, dir: skillDir, skillFile, source,
+                    hash: counted.hash, fileCount: counted.fileCount, bytes: counted.bytes, issues: counted.issues, reg, tier: meta.tier, triggers: meta.triggers,
+                });
+                byName.set(rec.name, rec);
+                dirsByName.set(rec.name, [...(dirsByName.get(rec.name) || []), skillDir]);
+            }
+        }
+        const records = Array.from(byName.values());
+        this.cache = records;
+        this.dirsByName = dirsByName;
+        if (opts.writeRegistry !== false) {
+            // 首次发现把缺记录补进 registry (内容 hash 作为基线), 以后才能检出漂移
+            let changed = false;
+            for (const r of records) {
+                if (!reg.skills[r.name]) {
+                    reg.skills[r.name] = {
+                        skillId: r.skillId, name: r.name, version: r.version, contentHash: r.contentHash,
+                        source: r.source, sourceRef: r.dir, status: r.status, trust: r.trust,
+                        installedAt: r.installedAt, updatedAt: r.updatedAt,
+                    };
+                    changed = true;
+                }
+            }
+            if (changed)
+                await writeRegistry(reg, home).catch(() => { });
+        }
+        return records;
+    }
+    buildRecord(input) {
+        const prior = input.reg.skills[input.name];
+        const issues = validateSkillRecord({
+            name: input.name, description: input.description, body: input.body,
+            frontmatter: input.frontmatter, bytes: input.bytes, issues: input.issues,
+        });
+        const fmStatus = String(input.frontmatter?.status ?? 'active');
+        // 状态优先级: 结构坏 → invalid; registry 显式停用/隔离/归档 → 尊重; 否则按 frontmatter/来源推导
+        let status;
+        if (issues.length)
+            status = 'invalid';
+        else if (prior?.status === 'disabled' || prior?.status === 'quarantined' || prior?.status === 'archived')
+            status = prior.status;
+        else if (fmStatus === 'archived')
+            status = 'archived';
+        else if (fmStatus === 'draft')
+            status = 'discovered';
+        else
+            status = prior?.status === 'installed' ? 'installed' : 'enabled';
+        const source = prior?.source
+            || (input.source === 'project' ? 'project' : 'user');
+        const now = new Date().toISOString();
+        return {
+            skillId: prior?.skillId || input.name,
+            name: input.name,
+            description: input.description,
+            version: input.version,
+            contentHash: input.hash,
+            source,
+            sourceRef: prior?.sourceRef || input.dir,
+            status,
+            trust: prior?.trust || 'unverified',
+            compatibility: input.frontmatter?.compatibility ? String(input.frontmatter.compatibility) : undefined,
+            tier: input.tier || 'utility',
+            triggers: input.triggers || [],
+            skillFile: input.skillFile,
+            dir: input.dir,
+            fileCount: input.fileCount,
+            bytes: input.bytes,
+            installedAt: prior?.installedAt || now,
+            updatedAt: now,
+            issues,
+            registryHash: prior?.contentHash,
+            approvedBy: prior?.approvedBy,
+            approvedAt: prior?.approvedAt,
+        };
+    }
+    /** 单技能详情 (含正文长度与漂移判定) */
+    async inspect(name, opts = {}) {
+        const all = this.cache && !opts.home ? this.cache : await this.discover(opts);
+        return all.find((s) => s.name === name) || null;
+    }
+    /** 解析一组技能名 → 记录 (缺哪个说清); 2-G.2 的 readiness gate 就用这个 */
+    async resolve(names, opts = {}) {
+        const all = await this.discover(opts);
+        const resolved = [];
+        const missing = [];
+        const notEnabled = [];
+        for (const n of names) {
+            const hit = all.find((s) => s.name === n);
+            if (!hit) {
+                missing.push(n);
+                continue;
+            }
+            if (hit.status !== 'enabled' && hit.status !== 'installed')
+                notEnabled.push(n);
+            resolved.push(hit);
+        }
+        return { ok: missing.length === 0 && notEnabled.length === 0, resolved, missing, notEnabled };
+    }
+    /** 版本固定的技能快照 (Goal 级固定版本用; resolvedAt 记录解析时刻) */
+    async snapshot(names, opts = {}) {
+        const r = await this.resolve(names, opts);
+        const resolvedAt = new Date().toISOString();
+        return {
+            ok: r.missing.length === 0,
+            missing: r.missing,
+            entries: r.resolved.map((s) => ({ name: s.name, version: s.version, contentHash: s.contentHash, source: s.source, resolvedAt })),
+        };
+    }
+    /** 健康检查: 状态/来源分布 + 漂移 + 不合格 + 重复 + registry 缺盘 */
+    async health(opts = {}) {
+        const home = opts.home ?? this.home;
+        const all = await this.discover(opts);
+        const reg = await readRegistry(home);
+        const byStatus = {};
+        const bySource = {};
+        const drifted = [];
+        const invalid = [];
+        const duplicates = [];
+        for (const s of all) {
+            byStatus[s.status] = (byStatus[s.status] || 0) + 1;
+            bySource[s.source] = (bySource[s.source] || 0) + 1;
+            if (s.issues.length)
+                invalid.push({ name: s.name, issues: s.issues });
+            const prior = reg.skills[s.name];
+            if (prior?.contentHash && prior.contentHash !== s.contentHash) {
+                drifted.push({ name: s.name, expected: prior.contentHash, actual: s.contentHash });
+            }
+        }
+        for (const [name, dirs] of this.dirsByName) {
+            const uniq = Array.from(new Set(dirs));
+            if (uniq.length > 1)
+                duplicates.push({ name, dirs: uniq });
+        }
+        const missing = Object.keys(reg.skills).filter((n) => !all.some((s) => s.name === n));
+        return { total: all.length, byStatus, bySource, drifted, invalid, duplicates, missing };
+    }
+    // ── 管理动作 (2-G.1: 只改状态与账, 不改执行行为) ──────────────────────────
+    async patchRegistry(name, patch, home) {
+        const h = home ?? this.home;
+        const rec = await this.inspect(name, { home: h });
+        if (!rec)
+            return null;
+        const reg = await readRegistry(h);
+        reg.skills[name] = { ...(reg.skills[name] || {}), ...patch, name };
+        await writeRegistry(reg, h);
+        this.cache = null;
+        const after = await this.inspect(name, { home: h });
+        return after;
+    }
+    async enable(name, opts = {}) {
+        const rec = await this.inspect(name, opts);
+        if (!rec)
+            return { ok: false, reason: `没有这个技能: ${name}` };
+        if (rec.issues.length)
+            return { ok: false, reason: `技能不合格, 不能启用: ${rec.issues.join('; ')}` };
+        const skill = await this.patchRegistry(name, { status: 'enabled' }, opts.home);
+        return { ok: true, skill: skill || undefined };
+    }
+    async disable(name, opts = {}) {
+        const rec = await this.inspect(name, opts);
+        if (!rec)
+            return { ok: false, reason: `没有这个技能: ${name}` };
+        const skill = await this.patchRegistry(name, { status: 'disabled' }, opts.home);
+        return { ok: true, skill: skill || undefined };
+    }
+    /** 人工批准 (信任等级 verified); 2-G.3 的 import 事务会要求它才算"可用" */
+    async approve(name, by = 'human', opts = {}) {
+        const rec = await this.inspect(name, opts);
+        if (!rec)
+            return { ok: false, reason: `没有这个技能: ${name}` };
+        const skill = await this.patchRegistry(name, { trust: 'verified', approvedBy: by, approvedAt: new Date().toISOString() }, opts.home);
+        return { ok: true, skill: skill || undefined };
+    }
+    /** 隔离 (损坏/不可信来源); 被隔离的技能不允许长期 Goal 自动使用 */
+    async quarantine(name, reason, opts = {}) {
+        const rec = await this.inspect(name, opts);
+        if (!rec)
+            return { ok: false };
+        const reg = await readRegistry(opts.home ?? this.home);
+        reg.skills[name] = {
+            ...(reg.skills[name] || {}), name,
+            status: 'quarantined', trust: 'quarantined',
+            quarantineReason: reason.slice(0, 200), quarantinedAt: new Date().toISOString(),
+        };
+        await writeRegistry(reg, opts.home ?? this.home);
+        this.cache = null;
+        return { ok: true, skill: (await this.inspect(name, opts)) || undefined };
+    }
+    /** 结构校验: 重算问题清单并把状态落成 invalid (或从 invalid 恢复) */
+    async validate(name, opts = {}) {
+        const rec = await this.inspect(name, opts);
+        if (!rec)
+            return { ok: false, issues: [`没有这个技能: ${name}`] };
+        const skill = await this.patchRegistry(name, { status: rec.issues.length ? 'invalid' : (rec.status === 'invalid' ? 'enabled' : rec.status) }, opts.home);
+        return { ok: rec.issues.length === 0, issues: rec.issues, skill: skill || undefined };
+    }
+    /** 导出技能包 (复用 skill-share 的打包, 不重复实现) */
+    async export(name, opts = {}) {
+        const rec = await this.inspect(name, opts);
+        if (!rec)
+            return { ok: false, error: `没有这个技能: ${name}` };
+        return collectSkillBundle(rec.dir, { name: rec.name });
+    }
+    /**
+     * 导入技能 (对话/链接/CID 三种写法都支持)。
+     * **2-G.1 只做统一入口 + 记账**: 下载 → 安装仍走现有 installSkillBundle (已有路径穿越校验 / 版本门 / 备份),
+     * 事务化 (临时目录 + 原子移动 + hash 校验) 属 2-G.3。
+     */
+    async import(ref, opts = {}) {
+        const cid = parseSkillRef(ref);
+        if (!cid)
+            return { ok: false, error: `无法识别的技能引用 (要 bolloon://skill/<cid> / ipfs://<cid> / 裸 CID): ${ref.slice(0, 60)}` };
+        const fetched = await fetchSkillBundle(cid);
+        if (!fetched.ok || !fetched.bundle)
+            return { ok: false, error: fetched.error || '取包失败' };
+        const inst = await installSkillBundle(fetched.bundle, { home: opts.home ?? this.home, cwd: opts.cwd ?? this.cwd, force: opts.force, scope: opts.scope });
+        if (!inst.ok)
+            return { ok: false, error: inst.error };
+        const h = opts.home ?? this.home;
+        const name = fetched.bundle.name;
+        this.cache = null;
+        const after = await this.inspect(name, { home: h });
+        if (after) {
+            await this.patchRegistry(name, {
+                status: 'installed', source: opts.source || 'shared', sourceRef: cid, trust: 'unverified',
+                contentHash: after.contentHash, version: after.version,
+            }, h);
+        }
+        return { ok: true, name, version: fetched.bundle.version, skill: (await this.inspect(name, { home: h })) || undefined };
+    }
+    /** 从已解析的技能包装入 (本地文件/已取到的包) */
+    async install(bundleJson, opts = {}) {
+        const parsed = parseSkillBundle(bundleJson);
+        if (!parsed.ok || !parsed.bundle)
+            return { ok: false, error: parsed.error || '包格式非法' };
+        const inst = await installSkillBundle(parsed.bundle, { home: opts.home ?? this.home, cwd: opts.cwd ?? this.cwd, force: opts.force });
+        if (!inst.ok)
+            return { ok: false, error: inst.error };
+        const h = opts.home ?? this.home;
+        this.cache = null;
+        const after = await this.inspect(parsed.bundle.name, { home: h });
+        if (after) {
+            await this.patchRegistry(parsed.bundle.name, {
+                status: 'installed', source: opts.source || 'imported', sourceRef: opts.sourceRef || 'local-bundle',
+                trust: 'unverified', contentHash: after.contentHash, version: after.version,
+            }, h);
+        }
+        return { ok: true, name: parsed.bundle.name, skill: (await this.inspect(parsed.bundle.name, { home: h })) || undefined };
+    }
+    // ── 视图 ─────────────────────────────────────────────────────────────────
+    /** 给 CLI / Web / agent 的同一份列表 (字段一致, 顺序一致: name 升序) */
+    async view(opts = {}) {
+        const all = await this.discover(opts);
+        return [...all].sort((a, b) => a.name.localeCompare(b.name));
+    }
+}
+let singleton = null;
+/** 进程内单例 (CLI / Web / Supervisor 共用同一个视图实现) */
+export function getSkillsManager(opts = {}) {
+    if (!singleton)
+        singleton = new SkillsManager(opts);
+    return singleton;
+}
+export function resetSkillsManagerForTest() {
+    singleton = null;
+}
+/** 一行摘要 (CLI / 日志用) */
+export function formatSkillLine(s) {
+    return `${s.name.padEnd(28)} ${String(s.status).padEnd(11)} ${String(s.source).padEnd(9)} ${String(s.trust).padEnd(10)} v${s.version.padEnd(8)} ${s.contentHash.slice(0, 10)}${s.issues.length ? `  ⚠ ${s.issues.length} 个问题` : ''}`;
+}