@bolloon/bolloon-agent 0.4.25 → 0.4.26

package/dist/agents/skill-readiness.js

@@ -0,0 +1,133 @@
+/**
+ * skill-readiness.ts — Goal 级技能快照 + 执行前就绪门禁 (批次 2-G.2, 2026-09-16)
+ *
+ * 定位 (与 leo 的规格一致): 这属于**执行前准备**, 由 Supervisor / runner resolver 负责 ——
+ * **不放进 PiAgentHarness** (Harness 只管"这一段能不能安全执行")。
+ *
+ * 规则:
+ *   · Goal 首次执行时把 requiredSkills 解析成 snapshot (name/version/contentHash/source/resolvedAt) 并冻结;
+ *   · 后续 Run 只认快照: 缺技能 / 未启用 / 损坏 / hash 漂移 / 版本变化 → **不启动 Run**, Goal → needs_human;
+ *   · 前缀 '?' 的技能算可选: 缺失不阻塞, 但写一条 degradation;
+ *   · **不允许静默用新版本** —— 漂移必须人工批准 (approve) 才会更新快照。
+ */
+import * as os from 'os';
+import { SkillsManager } from './skills-manager.js';
+import { readGoal, setContinuation, updateGoal, addEvidence, } from './goal-store.js';
+import { recordDegradation } from './run-store.js';
+export function parseSkillSpecs(list = []) {
+    const required = [];
+    const optional = [];
+    for (const raw of list) {
+        const n = String(raw || '').trim();
+        if (!n)
+            continue;
+        if (n.startsWith('?'))
+            optional.push(n.slice(1).trim());
+        else
+            required.push(n);
+    }
+    return { required, optional };
+}
+function userHome(home) {
+    return home || process.env.HOME || os.homedir();
+}
+function manager(home) {
+    return new SkillsManager({ home: userHome(home), cwd: process.cwd() });
+}
+/** 冻结技能快照 (首次执行时调用; 已冻结则不重复解析) */
+export async function freezeGoalSkills(goal, opts = {}) {
+    const { required } = parseSkillSpecs(goal.requiredSkills || []);
+    if (!required.length)
+        return { ok: true, snapshot: goal.skillSnapshot || [], missing: [], notEnabled: [] };
+    if (goal.skillSnapshot?.length && !opts.force)
+        return { ok: true, snapshot: goal.skillSnapshot, missing: [], notEnabled: [] };
+    const sm = manager(opts.home);
+    const res = await sm.snapshot(required, { home: userHome(opts.home) });
+    if (!res.ok || res.missing.length) {
+        return { ok: false, missing: res.missing, notEnabled: [], reason: `必需技能缺失: ${res.missing.join(', ')}` };
+    }
+    const snapshot = res.entries.map((e) => ({ name: e.name, version: e.version, contentHash: e.contentHash, source: e.source, resolvedAt: e.resolvedAt }));
+    await updateGoal(goal.goalId, { skillSnapshot: snapshot });
+    await addEvidence(goal.goalId, [`技能快照已冻结: ${snapshot.map((x) => `${x.name}@${x.version}:${x.contentHash.slice(0, 8)}`).join(', ')}`]).catch(() => { });
+    return { ok: true, snapshot, missing: [], notEnabled: [] };
+}
+/** 执行前就绪门禁 (Supervisor 每次准备起 Run 之前调) */
+export async function ensureGoalSkillsReady(goal, opts = {}) {
+    const { required, optional } = parseSkillSpecs(goal.requiredSkills || []);
+    const out = { ok: true, missing: [], notEnabled: [], invalid: [], drift: [], degradations: [] };
+    if (!required.length && !optional.length)
+        return out;
+    const frozen = await freezeGoalSkills(goal, opts);
+    if (!frozen.ok) {
+        out.ok = false;
+        out.missing = frozen.missing;
+        out.reason = frozen.reason || '技能快照无法冻结';
+        return out;
+    }
+    const snapshot = frozen.snapshot || [];
+    out.snapshot = snapshot;
+    // 逐个校验快照 (真实 registry + 真实文件 hash)
+    const sm = manager(opts.home);
+    const home = userHome(opts.home);
+    for (const entry of snapshot) {
+        const rec = await sm.inspect(entry.name, { home });
+        if (!rec) {
+            out.missing.push(entry.name);
+            continue;
+        }
+        if (rec.status !== 'enabled' && rec.status !== 'installed')
+            out.notEnabled.push(`${entry.name}(${rec.status})`);
+        if (rec.contentHash !== entry.contentHash)
+            out.drift.push({ name: entry.name, expected: entry.contentHash, actual: rec.contentHash });
+        if (rec.version !== entry.version)
+            out.drift.push({ name: entry.name, expected: entry.version, actual: rec.version });
+        const v = await sm.validate(entry.name, { home }).catch(() => null);
+        if (v && !v.ok)
+            out.invalid.push(`${entry.name}: ${(v.issues || []).slice(0, 2).join('; ')}`);
+    }
+    // 可选技能: 缺失/未启用 → 只记 degradation (不阻塞)
+    for (const name of optional) {
+        const rec = await sm.inspect(name, { home });
+        if (!rec) {
+            out.degradations.push(`可选技能 ${name} 不存在 → 继续执行 (已记降级)`);
+            continue;
+        }
+        if (rec.status !== 'enabled' && rec.status !== 'installed')
+            out.degradations.push(`可选技能 ${name} 未启用 (${rec.status}) → 继续执行`);
+    }
+    if (out.missing.length)
+        out.reason = `必需技能缺失: ${out.missing.join(', ')}`;
+    else if (out.notEnabled.length)
+        out.reason = `必需技能未启用: ${out.notEnabled.join(', ')}`;
+    else if (out.invalid.length)
+        out.reason = `必需技能损坏: ${out.invalid.join(', ')}`;
+    else if (out.drift.length)
+        out.reason = `技能内容漂移 (需人工批准才能升级): ${out.drift.map((d) => `${d.name} ${String(d.expected).slice(0, 8)}→${String(d.actual).slice(0, 8)}`).join(', ')}`;
+    out.ok = !(out.missing.length || out.notEnabled.length || out.invalid.length || out.drift.length);
+    return out;
+}
+/** 门禁不过 → 写清事实并把 Goal 交给人 (不启动 Run, 不伪造失败) */
+export async function blockGoalOnSkills(goalId, res) {
+    const reason = res.reason || '技能未就绪';
+    await setContinuation(goalId, {
+        wakeReason: 'needs_human', autoContinue: false, needsExternal: undefined,
+        skillReadiness: { ok: false, at: new Date().toISOString(), reason, missing: res.missing, drift: res.drift, degradations: res.degradations },
+    });
+    await updateGoal(goalId, { status: 'needs_human' }).catch(() => { });
+    await addEvidence(goalId, [`技能门禁拦截: ${reason}`]).catch(() => { });
+    for (const d of res.degradations)
+        await recordDegradation({ kind: 'observational', op: 'skill-readiness', message: d }).catch(() => { });
+}
+/** 人工批准技能升级: 重新冻结快照 (显式动作, 不隐式切换) */
+export async function approveSkillUpgrade(goalId, opts = {}) {
+    const goal = await readGoal(goalId);
+    if (!goal)
+        return { ok: false, reason: 'Goal 不存在' };
+    const frozen = await freezeGoalSkills(goal, { ...opts, force: true });
+    if (!frozen.ok)
+        return { ok: false, reason: frozen.reason };
+    await setContinuation(goalId, { skillReadiness: { ok: true, at: new Date().toISOString(), reason: '人工批准技能升级' }, wakeReason: 'active', autoContinue: true });
+    await updateGoal(goalId, { status: 'active' }).catch(() => { });
+    await addEvidence(goalId, [`技能升级已被人工批准: ${(frozen.snapshot || []).map((s) => `${s.name}@${s.version}`).join(', ')}`]).catch(() => { });
+    return { ok: true, snapshot: frozen.snapshot };
+}

package/dist/agents/skill-supervisor-link.js

@@ -0,0 +1,70 @@
+/**
+ * skill-supervisor-link.ts — 技能状态与长期执行的联动 (批次 2-G.4, 2026-09-16)
+ *
+ * 规则 (与 leo 的规格一致):
+ *   · 技能导入成功 / 又能用了 → 被它拦住的 Goal 重新冻结快照并回到 active (等 Supervisor 继续调度);
+ *   · 技能被禁用 / 隔离 / 内容漂移 → **不打断正在跑的 Run**, 但下一次 Run 之前 readiness 必然失败 (2-G.2 门禁) → needs_human;
+ *   · 漂移**不允许隐式切换版本**: 继续固定旧快照, 或等人工 approve 升级 (approveSkillUpgrade)。
+ *
+ * 这里只改"该不该继续"的事实, 不直接启动执行 —— 执行权始终在 Supervisor。
+ */
+import { listGoals } from './goal-store.js';
+import { ensureGoalSkillsReady, blockGoalOnSkills, approveSkillUpgrade, parseSkillSpecs } from './skill-readiness.js';
+import { SkillsManager } from './skills-manager.js';
+import { recordDegradation } from './run-store.js';
+/**
+ * 重评所有"因技能被拦"的 Goal。
+ * @param opts.action 触发原因 (import / enable / disable / quarantine / drift) —— 只用于事实记录
+ */
+export async function reconsiderSkillBlockedGoals(opts = {}) {
+    const out = { rechecked: 0, resumed: [], stillBlocked: [] };
+    const home = opts.home;
+    const goals = await listGoals({ limit: 200 });
+    const interesting = goals.filter((g) => {
+        const r = g.continuation?.skillReadiness;
+        const specs = parseSkillSpecs(g.requiredSkills || []);
+        return (r && r.ok === false) || specs.required.length > 0;
+    });
+    for (const g of interesting) {
+        // 只处理"被技能拦住"的 Goal: 其它原因等人的不要乱动
+        const blockedBySkill = g.continuation?.skillReadiness?.ok === false;
+        if (!blockedBySkill)
+            continue;
+        // 若是被人工标记 needs_human 且与技能无关, 跳过
+        out.rechecked++;
+        const res = await ensureGoalSkillsReady(g, { home });
+        if (res.ok) {
+            // 技能恢复了 → 重新冻结快照 + 回 active (Supervisor 下一轮继续)
+            const approved = await approveSkillUpgrade(g.goalId, { home });
+            if (approved.ok) {
+                out.resumed.push(g.goalId);
+                console.log(`[skill-link] ${g.goalId} 技能已恢复 (${opts.action || 'unknown'}${opts.name ? `:${opts.name}` : ''}) → 重新冻结快照并回到 active`);
+            }
+            else {
+                out.stillBlocked.push(g.goalId);
+            }
+        }
+        else {
+            await blockGoalOnSkills(g.goalId, res);
+            out.stillBlocked.push(g.goalId);
+        }
+    }
+    return out;
+}
+/** 技能被禁用/隔离/漂移时, 把依赖它的活跃 Goal 标清事实 (不打断当前 Run) */
+export async function markDependentsOfSkill(name, opts = { reason: '技能不可用' }) {
+    const sm = new SkillsManager({ home: opts.home, cwd: process.cwd() });
+    const health = await sm.health({ home: opts.home }).catch(() => null);
+    const goals = await listGoals({ limit: 200 });
+    const affected = [];
+    for (const g of goals) {
+        const { required } = parseSkillSpecs(g.requiredSkills || []);
+        if (!required.includes(name))
+            continue;
+        if (['completed', 'failed', 'abandoned'].includes(g.status))
+            continue;
+        affected.push(g.goalId);
+        await recordDegradation({ kind: 'observational', op: 'skill-link', message: `Goal ${g.goalId} 依赖的技能 ${name} 状态: ${JSON.stringify(health?.byStatus || {})} (${opts.reason}) — 下一次 Run 前会重新门禁` }).catch(() => { });
+    }
+    return affected;
+}

package/dist/agents/skills-manager.js

@@ -19,6 +19,10 @@ import * as os from 'os';
 import * as path from 'path';
 import * as fsp from 'fs/promises';
 import * as crypto from 'crypto';
+// 2026-09-16 (2-G.3): 事务型导入复用底层真实实现 (别名避免与上面重名)
+import { parseSkillBundle as parseBundleLoose, parseSkillRef as parseSkillRefLoose, fetchSkillBundle as fetchBundleLoose } from './skill-share.js';
+import { sanitizeSkillName as sanitizeNameLoose, getUserSkillsDir as userSkillsDirLoose, getProjectSkillsDir as projectSkillsDirLoose } from './skill-writer.js';
+import { parseSkillFile as parseSkillFileLoose } from './skill-loader.js';
 import { parseSkillFile, defaultSkillPaths } from './skill-loader.js';
 import { getUserSkillsDir } from './skill-writer.js';
 import { collectSkillBundle, parseSkillBundle, parseSkillRef, fetchSkillBundle, installSkillBundle, } from './skill-share.js';
@@ -319,6 +323,8 @@ export class SkillsManager {
         if (rec.issues.length)
             return { ok: false, reason: `技能不合格, 不能启用: ${rec.issues.join('; ')}` };
         const skill = await this.patchRegistry(name, { status: 'enabled' }, opts.home);
+        // 2-G.4: 技能又能用了 → 重评被它拦住的 Goal (回 active, 等 Supervisor 继续)
+        await this.onRegistryChanged({ home: opts.home ?? this.home, action: 'enable', name }).catch(() => null);
         return { ok: true, skill: skill || undefined };
     }
     async disable(name, opts = {}) {
@@ -326,6 +332,14 @@ export class SkillsManager {
         if (!rec)
             return { ok: false, reason: `没有这个技能: ${name}` };
         const skill = await this.patchRegistry(name, { status: 'disabled' }, opts.home);
+        // 2-G.4: 记录"谁依赖它" (不打断当前 Run; 下一次 Run 前由 2-G.2 门禁拦)
+        try {
+            const { markDependentsOfSkill } = await import('./skill-supervisor-link.js');
+            const affected = await markDependentsOfSkill(name, { home: opts.home ?? this.home, reason: '技能被禁用' });
+            if (affected.length)
+                console.warn(`[skills] ${name} 被禁用; 依赖它的 Goal: ${affected.join(', ')} (下一次 Run 前会门禁)`);
+        }
+        catch { /* 联动失败不影响禁用结果 */ }
         return { ok: true, skill: skill || undefined };
     }
     /** 人工批准 (信任等级 verified); 2-G.3 的 import 事务会要求它才算"可用" */
@@ -349,6 +363,14 @@ export class SkillsManager {
         };
         await writeRegistry(reg, opts.home ?? this.home);
         this.cache = null;
+        // 2-G.4: 隔离 = 不再可信 → 依赖它的 Goal 下一次 Run 前必然门禁失败
+        try {
+            const { markDependentsOfSkill } = await import('./skill-supervisor-link.js');
+            const affected = await markDependentsOfSkill(name, { home: opts.home ?? this.home, reason: `技能被隔离: ${reason}` });
+            if (affected.length)
+                console.warn(`[skills] ${name} 被隔离; 依赖它的 Goal: ${affected.join(', ')}`);
+        }
+        catch { /* 联动失败不影响隔离结果 */ }
         return { ok: true, skill: (await this.inspect(name, opts)) || undefined };
     }
     /** 结构校验: 重算问题清单并把状态落成 invalid (或从 invalid 恢复) */
@@ -372,6 +394,14 @@ export class SkillsManager {
      * 事务化 (临时目录 + 原子移动 + hash 校验) 属 2-G.3。
      */
     async import(ref, opts = {}) {
+        // 2026-09-16 (2-G.3): 统一走事务版 (暂存 → 原子替换 → 校验 → 回滚), 失败不污染当前技能环境
+        const tx = await this.importTransactional({ ref }, opts);
+        if (tx.ok)
+            await this.onRegistryChanged({ home: opts.home ?? this.home, action: 'import', name: tx.name }).catch(() => null);
+        return { ok: tx.ok, name: tx.name, version: tx.version, error: tx.error, skill: tx.skill };
+    }
+    /** @deprecated 保留旧签名以兼容; 内部已走事务版 */
+    async importLegacy(ref, opts = {}) {
         const cid = parseSkillRef(ref);
         if (!cid)
             return { ok: false, error: `无法识别的技能引用 (要 bolloon://skill/<cid> / ipfs://<cid> / 裸 CID): ${ref.slice(0, 60)}` };
@@ -395,6 +425,14 @@ export class SkillsManager {
     }
     /** 从已解析的技能包装入 (本地文件/已取到的包) */
     async install(bundleJson, opts = {}) {
+        // 2026-09-16 (2-G.3): 同样走事务 (install 的默认来源保持 'imported')
+        const tx = await this.importTransactional({ bundleJson }, { ...opts, source: opts.source || 'imported' });
+        if (tx.ok)
+            await this.onRegistryChanged({ home: opts.home ?? this.home, action: 'install', name: tx.name }).catch(() => null);
+        return { ok: tx.ok, name: tx.name, error: tx.error, skill: tx.skill };
+    }
+    /** @deprecated 旧的"直接写正式目录"实现 (保留对照, 不再被 import/install 调用) */
+    async installLegacy(bundleJson, opts = {}) {
         const parsed = parseSkillBundle(bundleJson);
         if (!parsed.ok || !parsed.bundle)
             return { ok: false, error: parsed.error || '包格式非法' };
@@ -412,6 +450,203 @@ export class SkillsManager {
         }
         return { ok: true, name: parsed.bundle.name, skill: (await this.inspect(parsed.bundle.name, { home: h })) || undefined };
     }
+    // ── 事务型导入 (2-G.3, 2026-09-16) ───────────────────────────────────────
+    /**
+     * 把 import/install 变成**事务**:
+     *   读来源 → 预备校验 (名字/路径穿越/SKILL.md frontmatter/版本门) → 写暂存目录
+     *   → 原子替换 (旧目录先改名保留) → 校验落地结果 → 更新 registry
+     * 任何一步失败: 正式目录不变 · registry 不变 · 暂存清理 · 失败原因可查询 (importHistory)。
+     * 中途被 SIGKILL: 只可能留下 `.<name>-staging-*` 暂存或 `.<name>.bak-*` 备份 →
+     *   recoverInterruptedImports() 会清理暂存并把备份恢复回正式位置。
+     */
+    async importTransactional(input, opts = {}) {
+        const h = opts.home ?? this.home;
+        const started = Date.now();
+        const fail = async (step, error, name) => {
+            await this.recordImportFailure({ step, error, name, ref: input.ref, at: new Date().toISOString() });
+            return { ok: false, error, step, name };
+        };
+        // 0) 先清上一次中断留下的暂存/备份, 避免互相干扰
+        await this.recoverInterruptedImports({ home: h }).catch(() => null);
+        // 1) 取包 (ref 走 IPFS; bundleJson 直接用)
+        let bundle = null;
+        let sourceRef = 'local-bundle';
+        if (input.bundleJson) {
+            const parsed = parseBundleLoose(input.bundleJson);
+            if (!parsed?.ok || !parsed.bundle)
+                return await fail('parse', parsed?.error || '包格式非法 (不是 bolloon-skill-bundle/1 JSON)');
+            bundle = parsed.bundle;
+            sourceRef = 'local-bundle';
+        }
+        else if (input.ref) {
+            const cid = parseSkillRefLoose(input.ref);
+            if (!cid)
+                return await fail('parse', `无法识别的技能引用: ${String(input.ref).slice(0, 60)}`);
+            const fetched = await fetchBundleLoose(cid);
+            if (!fetched?.ok || !fetched.bundle)
+                return await fail('fetch', fetched?.error || '取包失败');
+            bundle = fetched.bundle;
+            sourceRef = cid;
+        }
+        else {
+            return await fail('parse', '必须给 ref 或 bundleJson');
+        }
+        // 2) 预备校验 (全部发生在动正式目录之前)
+        if (!bundle || typeof bundle !== 'object')
+            return await fail('parse', '包内容不是对象');
+        const name = sanitizeNameLoose(bundle.name);
+        if (!name)
+            return await fail('validate', '技能名非法 (清洗后为空)');
+        if (!bundle.files || typeof bundle.files !== 'object')
+            return await fail('validate', '包内没有 files', name);
+        const skillMd = bundle.files['SKILL.md'];
+        if (typeof skillMd !== 'string' || !skillMd.trim())
+            return await fail('validate', '包内缺少 SKILL.md', name);
+        const fm = parseFrontmatterLoose(skillMd);
+        if (!fm)
+            return await fail('validate', 'SKILL.md 缺少合法 frontmatter (--- 包裹)', name);
+        if (!fm.name)
+            return await fail('validate', 'SKILL.md frontmatter 缺 name', name);
+        for (const rel of Object.keys(bundle.files)) {
+            const norm = path.normalize(rel).replace(/^([/\\])+/, '');
+            if (norm.startsWith('..') || path.isAbsolute(norm))
+                return await fail('validate', `技能包含非法路径 (路径穿越): ${rel}`, name);
+        }
+        const base = opts.scope === 'project' ? projectSkillsDirLoose(opts.cwd ?? this.cwd) : userSkillsDirLoose(h);
+        const targetDir = path.join(base, name);
+        const existingMeta = await parseSkillFileLoose(path.join(targetDir, 'SKILL.md'));
+        const existingVersion = String(existingMeta?.frontmatter?.version ?? '0.0.0');
+        const incomingVersion = String(bundle.version || fm.version || '0.0.0');
+        if (existingMeta && cmpVersionLoose(existingVersion, incomingVersion) >= 0 && !opts.force) {
+            return await fail('version', `本地已有 ${name}@${existingVersion}, 来的是 ${incomingVersion} (不更新; force=true 可强制)`, name);
+        }
+        // 3) 写暂存目录 (同名 . 前缀 → discover 不会当成技能)
+        const staging = path.join(base, `.${name}-staging-${started}`);
+        await fsp.mkdir(staging, { recursive: true });
+        try {
+            for (const [rel, content] of Object.entries(bundle.files)) {
+                const norm = path.normalize(rel).replace(/^([/\\])+/, '');
+                const abs = path.join(staging, norm);
+                await fsp.mkdir(path.dirname(abs), { recursive: true });
+                await fsp.writeFile(abs, String(content), 'utf-8');
+            }
+        }
+        catch (err) {
+            await fsp.rm(staging, { recursive: true, force: true }).catch(() => { });
+            return await fail('stage', `写暂存失败: ${String(err?.message || err).slice(0, 160)}`, name);
+        }
+        // 4) 原子替换: 旧目录改名保留 (备份), 暂存改名就位
+        let backup;
+        try {
+            const exists = await fsp.stat(targetDir).then(() => true).catch(() => false);
+            if (exists) {
+                backup = path.join(base, `.${name}.bak-${started}`);
+                await fsp.rename(targetDir, backup);
+            }
+            await fsp.rename(staging, targetDir);
+        }
+        catch (err) {
+            // 回滚: 备份放回, 暂存清掉
+            await fsp.rm(staging, { recursive: true, force: true }).catch(() => { });
+            if (backup)
+                await fsp.rename(backup, targetDir).catch(() => { });
+            return await fail('swap', `原子替换失败 (已回滚): ${String(err?.message || err).slice(0, 160)}`, name);
+        }
+        // 5) 校验落地结果 (读回来再确认一次)
+        //    回滚条件只看**结构性失败** (SKILL.md 解析不出来); 内容质量类提示 (如正文过少) 只记警告 ——
+        //    否则用户自己的"简洁技能"永远装不回来 (导出→安装 自洽被打破)。
+        this.cache = null;
+        const parsedBack = await parseSkillFileLoose(path.join(targetDir, 'SKILL.md')).catch(() => null);
+        const after = await this.inspect(name, { home: h }).catch(() => null);
+        if (!parsedBack) {
+            await fsp.rm(targetDir, { recursive: true, force: true }).catch(() => { });
+            if (backup)
+                await fsp.rename(backup, targetDir).catch(() => { });
+            return await fail('verify', `落地校验失败 (已回滚): SKILL.md 装完解析不出来`, name);
+        }
+        if (after && (after.issues || []).length) {
+            await appendImportHistory(h, { at: new Date().toISOString(), ok: true, kind: 'warning', name, step: 'verify', warning: (after.issues || []).slice(0, 3).join('; ') }).catch(() => { });
+        }
+        // 6) registry 更新 (失败不致命: 下次 discover 会重建)
+        try {
+            await this.patchRegistry(name, {
+                status: 'installed', source: opts.source || 'shared', sourceRef,
+                trust: 'unverified', contentHash: after?.contentHash || '', version: after?.version || incomingVersion,
+            }, h);
+        }
+        catch (err) {
+            await this.recordImportFailure({ step: 'registry', error: `registry 更新失败: ${String(err?.message || err).slice(0, 140)}`, name, ref: input.ref, at: new Date().toISOString() });
+        }
+        await this.recordImportSuccess({ name, version: after?.version || incomingVersion, ref: input.ref, backup, at: new Date().toISOString() });
+        return { ok: true, name, version: after?.version || incomingVersion, backup, skill: after || undefined };
+    }
+    // ── 与 Supervisor 的长期联动 (2-G.4, 2026-09-16) ────────────────────────
+    /**
+     * 技能注册表发生变化 (导入成功 / 启用 / 禁用 / 隔离 / 漂移) → 重新评估**被技能拦住的 Goal**:
+     *   · 技能又能用了 → 重新冻结快照 + Goal 回 active (等 Supervisor 下一轮继续)
+     *   · 技能被禁用/隔离/漂移 → 交给 2-G.2 的执行前门禁拦 (这里只把状态标清, 不抢执行权)
+     */
+    async onRegistryChanged(opts = { action: 'unknown' }) {
+        const h = opts.home ?? this.home;
+        try {
+            const { reconsiderSkillBlockedGoals } = await import('./skill-supervisor-link.js');
+            const res = await reconsiderSkillBlockedGoals({ home: h, action: opts.action, name: opts.name });
+            return res;
+        }
+        catch (err) {
+            console.warn(`[skills] 联动重评失败 (不影响导入结果): ${String(err?.message || err).slice(0, 140)}`);
+            return { rechecked: 0, resumed: [], stillBlocked: [] };
+        }
+    }
+    /** 清理中断残留: 暂存目录删掉; 备份且正式目录缺失 → 恢复备份 (不丢已装技能) */
+    async recoverInterruptedImports(opts = {}) {
+        const h = opts.home ?? this.home;
+        const removedStaging = [];
+        const restored = [];
+        for (const base of [userSkillsDirLoose(h), projectSkillsDirLoose(opts.cwd ?? this.cwd)]) {
+            let entries = [];
+            try {
+                entries = await fsp.readdir(base);
+            }
+            catch {
+                continue;
+            }
+            for (const e of entries) {
+                if (/^\..*-staging-\d+$/.test(e)) {
+                    await fsp.rm(path.join(base, e), { recursive: true, force: true }).catch(() => { });
+                    removedStaging.push(e);
+                    continue;
+                }
+                const m = /^\.(.+)\.bak-(\d+)$/.exec(e);
+                if (m) {
+                    const live = path.join(base, m[1]);
+                    const liveExists = await fsp.stat(live).then(() => true).catch(() => false);
+                    if (!liveExists) {
+                        await fsp.rename(path.join(base, e), live).catch(() => { });
+                        restored.push(`${m[1]} (from ${e})`);
+                    }
+                }
+            }
+        }
+        return { removedStaging, restored };
+    }
+    /** 导入历史/失败原因 (CLI/Web 可查) */
+    async importHistory(opts = {}) {
+        const h = opts.home ?? this.home;
+        try {
+            const raw = JSON.parse(await fsp.readFile(importHistoryPath(h), 'utf8'));
+            return (Array.isArray(raw) ? raw : []).slice(-1 * (opts.limit || 20));
+        }
+        catch {
+            return [];
+        }
+    }
+    async recordImportSuccess(rec) {
+        await appendImportHistory(this.home, { ...rec, ok: true, kind: 'success' }).catch(() => { });
+    }
+    async recordImportFailure(rec) {
+        await appendImportHistory(this.home, { ...rec, ok: false, kind: 'failure' }).catch(() => { });
+    }
     // ── 视图 ─────────────────────────────────────────────────────────────────
     /** 给 CLI / Web / agent 的同一份列表 (字段一致, 顺序一致: name 升序) */
     async view(opts = {}) {
@@ -433,3 +668,50 @@ export function resetSkillsManagerForTest() {
 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} 个问题` : ''}`;
 }
+// ── 事务型导入的小工具 (2-G.3) ───────────────────────────────────────────────
+function importHistoryPath(home) {
+    return path.join(home, '.bolloon', 'skill-imports.json');
+}
+async function appendImportHistory(home, rec) {
+    const p = importHistoryPath(home);
+    await fsp.mkdir(path.dirname(p), { recursive: true });
+    let arr = [];
+    try {
+        const raw = JSON.parse(await fsp.readFile(p, 'utf8'));
+        if (Array.isArray(raw))
+            arr = raw;
+    }
+    catch { /* 首次 */ }
+    arr.push(rec);
+    await fsp.writeFile(p, JSON.stringify(arr.slice(-50), null, 2), 'utf8');
+}
+/** 极简 frontmatter 解析 (只要 name/version, 用于预备校验) */
+export function parseFrontmatterLoose(text) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(String(text || ''));
+    if (!m)
+        return null;
+    const out = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        const kv = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.+)$/.exec(line.trim());
+        if (!kv)
+            continue;
+        const key = kv[1].toLowerCase();
+        const val = kv[2].replace(/^["']|["']$/g, '').trim();
+        if (key === 'name')
+            out.name = val;
+        if (key === 'version')
+            out.version = val;
+    }
+    return out;
+}
+/** 版本比较 (semver 数字段; 非法段当 0) */
+export function cmpVersionLoose(a, b) {
+    const pa = String(a).split('.').map((x) => Number(String(x).replace(/[^0-9]/g, '')) || 0);
+    const pb = String(b).split('.').map((x) => Number(String(x).replace(/[^0-9]/g, '')) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] || 0) - (pb[i] || 0);
+        if (d !== 0)
+            return d > 0 ? 1 : -1;
+    }
+    return 0;
+}