@bolloon/bolloon-agent 0.4.25 → 0.4.27

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;
+}

package/dist/agents/trace-export.js

@@ -0,0 +1,125 @@
+/**
+ * trace-export.ts — 智能体**工具执行轨迹**的导出/解析 (2026-09-18)
+ *
+ * 定位: Run 的 steps[] 就是这台机器上真实发生过的工具调用事实
+ *   (n / ts / tool / argsDigest / ok / ms / summary / error)。
+ * 这一层只做一件事: 把这份事实变成**可读、可交换、可再解析**的文本/JSON,
+ * 好让 App、CLI、Web 与外部工具(如小红书小工具)看到同一份轨迹。
+ *
+ * 文本格式 (小工具侧解析器依赖, 改前先看 minitools/agent-card/src/assets/app.js 的 parseTraceText):
+ *   # Bolloon 执行轨迹 · run <runId> (<N> 步)
+ *   1. [ok] 2026-09-18T08:46:15.093Z shell_exec — ls -la /tmp (12ms)
+ *   2. [fail] 2026-09-18T08:46:17.001Z write_file — EACCES: permission denied (3ms)
+ *   规则: "<n>. [ok|fail] <无空格时间戳> <工具名> — <细节>" —— 时间戳与工具名不能含空格。
+ */
+export const TRACE_HEADER_PREFIX = '# Bolloon 执行轨迹';
+function stepDetail(s) {
+    const base = String(s.summary || s.error || (s.ok ? '完成' : '失败')).replace(/\s+/g, ' ').trim();
+    const ms = s.ms ? ` (${s.ms}ms)` : '';
+    const args = s.argsDigest ? ` [args:${String(s.argsDigest).slice(0, 8)}]` : '';
+    return `${base}${args}${ms}`.slice(0, 400);
+}
+/** Run → 轨迹 JSON (机器可读; 所有消费方都应基于这个结构, 而不是各自解析文本) */
+export function runToTraceJson(run) {
+    const steps = (run.steps || []).map((s) => ({
+        n: s.n,
+        ts: s.ts,
+        tool: s.tool,
+        ok: !!s.ok,
+        ms: s.ms,
+        summary: s.summary,
+        error: s.error,
+        argsDigest: s.argsDigest,
+    }));
+    const ok = steps.filter((s) => s.ok).length;
+    const byTool = new Map();
+    for (const s of steps) {
+        const cur = byTool.get(s.tool) || { tool: s.tool, count: 0, fail: 0 };
+        cur.count += 1;
+        if (!s.ok)
+            cur.fail += 1;
+        byTool.set(s.tool, cur);
+    }
+    return {
+        schema: 'bolloon-agent-trace/1',
+        runId: run.runId,
+        goalId: run.goalId,
+        surface: run.surface,
+        status: run.status,
+        goal: run.goal,
+        startedAt: run.startedAt || (run.steps || [])[0]?.ts,
+        updatedAt: run.updatedAt,
+        steps,
+        counts: { total: steps.length, ok, fail: steps.length - ok, totalMs: steps.reduce((a, s) => a + (s.ms || 0), 0) },
+        tools: Array.from(byTool.values()).sort((a, b) => b.count - a.count),
+        evidence: run.evidence,
+        error: run.error,
+    };
+}
+/** Run → 轨迹文本 (人可读 + 可被小工具解析; 供 CLI / 复制粘贴) */
+export function runToTraceText(run, opts = {}) {
+    const steps = (run.steps || []).slice(opts.limit ? Math.max(0, (run.steps || []).length - opts.limit) : 0);
+    const lines = [];
+    lines.push(`${TRACE_HEADER_PREFIX} · run ${run.runId} (${(run.steps || []).length} 步)`);
+    if (run.goal)
+        lines.push(`# 目标: ${String(run.goal).replace(/\s+/g, ' ').slice(0, 160)}`);
+    lines.push(`# 状态: ${run.status}${run.goalId ? ` · goal ${run.goalId}` : ''}${run.surface ? ` · surface ${run.surface}` : ''}`);
+    if (!steps.length)
+        lines.push('# (这次运行没有工具步骤)');
+    for (const s of steps) {
+        lines.push(`${s.n}. [${s.ok ? 'ok' : 'fail'}] ${s.ts} ${s.tool} — ${stepDetail(s)}`);
+    }
+    if (run.error)
+        lines.push(`# 结束原因: ${String(run.error).replace(/\s+/g, ' ').slice(0, 200)}`);
+    return lines.join('\n');
+}
+/**
+ * 解析轨迹文本 (容错: 只认 "<n>. [ok|fail] <ts> <tool> — <detail>" 这一行格式)。
+ * 用于: 把别处(小工具/别的机器)的轨迹读回来, 以及本模块的自校验往返。
+ */
+export function parseTraceText(text) {
+    const out = { steps: [] };
+    const lines = String(text || '').split('\n');
+    const re = /^\s*(\d+)\.\s*\[(ok|fail)\]\s*(\S+)\s+(\S+)\s*(?:—\s*)?([\s\S]*)$/;
+    for (const raw of lines) {
+        const line = raw.replace(/\r$/, '');
+        if (line.startsWith(TRACE_HEADER_PREFIX)) {
+            out.header = line;
+            continue;
+        }
+        if (line.startsWith('# 目标:')) {
+            out.goal = line.slice(5).trim();
+            continue;
+        }
+        if (line.startsWith('# 状态:')) {
+            out.status = line.slice(5).trim();
+            continue;
+        }
+        if (line.startsWith('# 结束原因:')) {
+            out.errorLine = line.slice(7).trim();
+            continue;
+        }
+        if (!line.trim() || line.startsWith('#'))
+            continue;
+        const m = re.exec(line);
+        if (!m)
+            continue;
+        const detail = String(m[5] || '');
+        const msMatch = /\s*\((\d+)ms\)\s*$/.exec(detail);
+        out.steps.push({
+            n: Number(m[1]),
+            ok: m[2] === 'ok',
+            ts: m[3],
+            tool: m[4],
+            ms: msMatch ? Number(msMatch[1]) : undefined,
+            summary: msMatch ? detail.slice(0, msMatch.index).trim() : detail.trim(),
+        });
+    }
+    return out;
+}
+/** 一行摘要 (CLI 列表/日志用) */
+export function summarizeTrace(run) {
+    const j = runToTraceJson(run);
+    const tools = j.tools.slice(0, 3).map((t) => `${t.tool}×${t.count}`).join(' ');
+    return `${j.counts.total} 步 (✓${j.counts.ok}/✗${j.counts.fail}, ${j.counts.totalMs}ms)${tools ? ` · ${tools}` : ''}`;
+}

package/dist/agents/write-staging.js

@@ -18,9 +18,16 @@ const home = () => process.env.HOME || os.homedir() || '/tmp';
 export function writeLogDir(homeDir = home()) {
     return path.join(homeDir, '.bolloon', 'write-log');
 }
-/** 生成唯一 stage id */
+/**
+ * 生成唯一 stage id。
+ * ★ 2026-09-18: 加**进程内单调序号** —— 原来只有 `Date.now()-随机`, 同一毫秒内的两次写入
+ * 顺序由随机后缀决定, `listStagedWrites` 的"最新在前"就不成立了 (真跑: 同毫秒 a.txt/b.txt 偶发反序,
+ * 让 write-staging 单测在全量跑时随机变红)。序号按 3 位 36 进制, 与时间戳一起保证字典序 == 发生顺序。
+ */
+let stageSeq = 0;
 function genId() {
-    return `${Date.now()}-${Math.random().toString(36).substring(2, 8)}`;
+    const seq = (stageSeq++ % 46656).toString(36).padStart(3, '0');
+    return `${Date.now()}-${seq}-${Math.random().toString(36).substring(2, 8)}`;
 }
 /**
  * 写前暂存: 记录一次写操作 (准备阶段). 返回记录; 失败静默返回 null.
@@ -54,13 +61,14 @@ export async function listStagedWrites(homeDir = home()) {
         return [];
     }
     const out = [];
-    for (const f of files.filter(f => f.endsWith('.json')).sort().reverse()) {
+    for (const f of files.filter(f => f.endsWith('.json'))) {
         try {
             out.push(JSON.parse(await fs.readFile(path.join(dir, f), 'utf-8')));
         }
         catch { /* 坏文件跳过 */ }
     }
-    return out;
+    // 最新在前: 先按 createdAt, 同一毫秒再按 id (id 内含单调序号) —— 确定性, 不看 readdir 顺序
+    return out.sort((a, b) => (b.createdAt - a.createdAt) || String(b.id).localeCompare(String(a.id)));
 }
 /** 撤销最近一次写 (若文件内容仍等于 afterContent → 恢复 beforeContent). 返回是否撤销. */
 export async function undoLastWrite(homeDir = home()) {

package/dist/agents/x402/goal-run-bridge.js

@@ -0,0 +1,105 @@
+/**
+ * goal-run-bridge.ts — 交易证据接入 Run / Goal (Phase 3, 2026-09-16)
+ *
+ * 支付不能只是工具副作用: 一次 Run 必须能回答 —— 为什么付款、买了什么、花了多少、
+ * 是否真结算、拿到什么、资源是否验证通过、结果对 Goal 有没有帮助。
+ *
+ * 事件映射 (与 leo 的规格一致):
+ *   discovered → transaction.discovered · quoted → transaction.quoted · policy_denied → transaction.policy_denied
+ *   paying → transaction.paying · settled → transaction.settled · delivered → transaction.delivered
+ *   verified → transaction.verified · delivery_failed/verification_failed → 同名
+ *
+ * Goal 侧只在 **交易 verified + 资源执行成功 + 命中判据** 时累计成功证据;
+ * 仅付款成功或仅拿到内容 **不能**满足 Goal 判据。
+ */
+import { recordStep, addRunEvidence } from '../run-store.js';
+import { addEvidence as addGoalEvidenceViaStore } from '../goal-store.js';
+import { aggregateMilestones, milestoneGoalEligibility } from './milestone-settlement.js';
+export function bridgeEventFor(status) {
+    switch (status) {
+        case 'discovered': return 'transaction.discovered';
+        case 'quoted': return 'transaction.quoted';
+        case 'policy_denied': return 'transaction.policy_denied';
+        case 'paying':
+        case 'payment_required': return 'transaction.paying';
+        case 'settled': return 'transaction.settled';
+        case 'delivered': return 'transaction.delivered';
+        case 'verified': return 'transaction.verified';
+        case 'delivery_failed': return 'transaction.delivery_failed';
+        case 'verification_failed': return 'transaction.verification_failed';
+        default: return 'transaction.quoted';
+    }
+}
+/** 一次交易的证据行 (写进 Run evidence / Goal evidence 的同一组字段) */
+export function transactionEvidenceLines(rec) {
+    return [
+        `transactionId=${rec.transactionId}`,
+        `itemId=${rec.itemId}`,
+        `paymentMode=${rec.paymentMode}`,
+        `chainSettled=${rec.chainSettled}`,
+        `settlementFact=${rec.settlementFact || '(legacy-未记)'}`, // 两层状态: 钱到底动没动, 审计一眼可见
+        `protocolVerified=${rec.protocolVerified === true}`,
+        `txHash=${rec.txHash || '(none)'}`,
+        `receiptHash=${rec.receiptHash || '(none)'}`,
+        `contentHash=${rec.contentHash || '(none)'}`,
+        `verificationTrust=${rec.verificationTrust || 'unverified'}`,
+        `transactionStatus=${rec.status}`,
+        ...(rec.responsibility ? [`responsibility=${rec.responsibility.type}(${rec.responsibility.reason})`] : []),
+        ...(rec.milestones?.length ? (() => { const a = aggregateMilestones(rec.milestones); return [`milestones=${a.verified}/${a.total}`, `milestoneSettlement=${a.settlementFact}`]; })() : []),
+        ...(rec.dispute ? [`dispute=opened(${rec.dispute.reason})`, `disputeResolved=${rec.dispute.resolution ? rec.dispute.resolution.decision : 'no'}`] : []),
+        ...(rec.execution ? [`executionOk=${rec.execution.ok === true} schemaOk=${rec.execution.schemaOk === true}`] : []),
+    ];
+}
+/**
+ * 把一笔交易写进 Run (step + evidence) 与 Goal (仅在满足条件时)。
+ * @param opts.goalCriteriaHit 资源执行结果是否命中 Goal 判据 (由调用方判定, 默认 false)
+ * @param opts.executionOk 资源是否被实际执行且符合契约
+ */
+export async function bridgeTransactionToRunGoal(rec, opts = {}) {
+    const out = { runId: opts.runId, goalId: opts.goalId, stepWritten: false, evidenceWritten: false, goalEvidenceWritten: false };
+    const lines = transactionEvidenceLines(rec);
+    const ok = rec.status === 'verified' || rec.status === 'delivered';
+    if (opts.runId) {
+        try {
+            const step = {
+                tool: 'x402_transaction',
+                ok,
+                summary: `${bridgeEventFor(rec.status)} · ${opts.summary || rec.itemId} (${rec.amount || rec.price || '?'} ${rec.currency || ''} via ${rec.paymentMode} · 结算 ${rec.settlementFact || '?'})`,
+                error: ok ? undefined : (rec.failureReason || rec.status),
+                args: { itemId: rec.itemId, amount: rec.amount, currency: rec.currency, network: rec.network, requestId: rec.requestId },
+            };
+            await recordStep(opts.runId, step);
+            out.stepWritten = true;
+            await addRunEvidence(opts.runId, lines);
+            out.evidenceWritten = true;
+        }
+        catch { /* 记账失败不改变交易事实, 但上面会让 out.* 保持 false (调用方可见) */ }
+    }
+    // Goal 侧: 只有 verified + 执行成功 + 命中判据 才计入成功证据
+    if (opts.goalId) {
+        // 纵深防御 + Phase 4 门槛: 链上结算 + 全部里程碑完成 + 无争议 + 执行成功 + 命中判据
+        // (partially_settled 一律不算 —— leo: 不要让 partially_settled 直接进 Goal 成功证据)
+        const elig = milestoneGoalEligibility(rec, { executionOk: opts.executionOk, goalCriteriaHit: opts.goalCriteriaHit });
+        const eligible = elig.eligible;
+        try {
+            if (eligible) {
+                await addGoalEvidenceViaStore(opts.goalId, [
+                    `付费资源已执行并命中判据: ${lines.join(' ')}`,
+                ]);
+                out.goalEvidenceWritten = true;
+            }
+            else if (rec.status === 'verified' || (rec.milestones?.length || 0) > 0) {
+                await addGoalEvidenceViaStore(opts.goalId, [
+                    `付费资源未达成功证据门槛 (${elig.reason}): ${lines.join(' ')}`,
+                ]);
+            }
+            else {
+                await addGoalEvidenceViaStore(opts.goalId, [
+                    `交易未成立 (${rec.status}): ${lines.join(' ')}`,
+                ]);
+            }
+        }
+        catch { /* 同上 */ }
+    }
+    return out;
+}