berry-agent 0.1.0-alpha.1

package/dist/host/testkit/harness.js

@@ -0,0 +1,283 @@
+/**
+ * testkit 假宿主装配件（03 §9.5——生态启动批 eco-3c）。
+ *
+ * 铁律（真装载器——deepseek-harness「真入口路径」教训照搬）：一切断言经
+ * 真装载整体走真——installPlugin/mountRow/toggleRow/bootPlugins 全是真身
+ * 直调（真 jiti 求值、真审计词、真 enabled.yaml/账本落盘），本件只提供
+ * 假宿主受局面（runtime 替身 + 注入式注册账 + 内存审计汇）。手工拼
+ * ctx.plugin 的套件不算数。
+ *
+ * 消费位：作者测试文件经 `berry-agent/testkit` 子路径导入（作者侧 devDep
+ * 消费——非装载器 jiti 注入面，03 §8.2 第七真相源「宿主主包子路径导出面」）。
+ */
+import { execFile } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { parseManifest } from '../manifest.js';
+import { installPlugin } from '../plugin-install.js';
+import { bootPlugins } from '../plugin-boot.js';
+import { mountRow, readEnabledRowsForEdit, toggleRow } from '../plugin-store.js';
+import { EventDispatch, Scope } from '../../context/index.js';
+import { stringify as stringifyYaml } from 'yaml';
+/** 内存审计汇（AuditFace 真形实现——append/lastOf/listRecent 三法 + 断言器扩展读面） */
+export class MemoryAuditSink {
+    seq = 0;
+    rows = [];
+    /** 直写落账（真词面由调用方保证——本汇不做词汇闸，断言器锁真词） */
+    append(type, data) {
+        this.rows.push({ id: ++this.seq, time: Date.now(), type, data: { ...data } });
+    }
+    /** 尾读：该词最近一条（从未落过 = undefined） */
+    lastOf(type) {
+        for (let i = this.rows.length - 1; i >= 0; i--) {
+            if (this.rows[i].type === type)
+                return this.rows[i];
+        }
+        return undefined;
+    }
+    /** 逆序近期清单（id 降序——与真源同序律） */
+    listRecent(limit = 100) {
+        return [...this.rows].reverse().slice(0, limit);
+    }
+    /* ---------------- 断言器扩展读面（testkit 专属——不进 AuditFace 契约） ---------------- */
+    /** 全量快照（正序——残留检查/白名单对账的数据源） */
+    all() {
+        return [...this.rows];
+    }
+    /** 词计数（可选拘载荷谓词——「恰一笔」断言的数据源） */
+    countOf(type, matches) {
+        return this.rows.filter((r) => r.type === type && (matches === undefined || matches(r.data))).length;
+    }
+}
+/** 命令注册账铸造（disposer 出账——换代 dispose 后单注可证） */
+export function createCommandAccount() {
+    const counts = new Map();
+    return {
+        registry: {
+            register: (name, _handler, _description) => {
+                counts.set(name, (counts.get(name) ?? 0) + 1);
+                return () => counts.set(name, (counts.get(name) ?? 0) - 1);
+            },
+        },
+        counts: () => new Map(counts),
+    };
+}
+/** 分派器监听器探针铸造（on 注册 +1、退订 −1；onWaterfall 腿 v1 未观察——注释明示） */
+export function instrumentDispatchListeners(dispatch) {
+    const net = new Map();
+    const origOn = dispatch.on.bind(dispatch);
+    // 实例属性包壳（真身在原型——不替换派发语义，只在注册/退订两点记账）
+    dispatch.on = ((name, listener) => {
+        net.set(name, (net.get(name) ?? 0) + 1);
+        const off = origOn(name, listener);
+        return () => {
+            off();
+            net.set(name, (net.get(name) ?? 0) - 1);
+        };
+    });
+    return { netCounts: () => new Map(net) };
+}
+/** 假宿主真盘数据面（PluginStoreFs 真身适配——node:fs 直连，无内存仿真） */
+export function realStoreFs() {
+    return {
+        read: (path) => {
+            try {
+                return readFileSync(path, 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        write: (path, text) => writeFileSync(path, text, 'utf8'),
+        rename: (from, to) => renameSync(from, to),
+        mkdir: (path, options) => mkdirSync(path, options),
+        rm: (path, options) => rmSync(path, options),
+        readdir: (path) => {
+            try {
+                return readdirSync(path);
+            }
+            catch {
+                return null;
+            }
+        },
+        size: (path) => {
+            try {
+                return statSync(path).size;
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}
+/** HostRuntime 结构化替身（装配序只消费 dataDir/registerCloser——同 plugin-boot.test 形） */
+function createHarnessRuntime(dataDir) {
+    return {
+        memory: false,
+        dataDir,
+        persistence: {},
+        abortSignal: new AbortController().signal,
+        disclosure: () => null,
+        registerCloser: () => undefined,
+        registerShutdownHook: () => undefined,
+        registerDisposer: () => undefined,
+        shutdown: async () => undefined,
+        writeCrashLog: () => undefined,
+    };
+}
+/** llm 注册账（Pick 受局面最小形——provider 注册动词真达即净计；出账可证） */
+function createLlmAccount() {
+    let net = 0;
+    return {
+        registerProvider: () => {
+            net += 1;
+            return () => {
+                net -= 1;
+            };
+        },
+        netCount: () => net,
+    };
+}
+/** 装配假宿主（构造即读清单定 id——坏清单构造即红，坏样本由矩阵层收面） */
+export function createPluginHarness(options) {
+    const pluginDir = options.pluginDir;
+    const pkgText = realStoreFs().read(join(pluginDir, 'package.json'));
+    if (pkgText === null) {
+        throw new Error(`testkit：${pluginDir} 缺 package.json（插件清单缺席——非插件目录）`);
+    }
+    let pkgJson;
+    try {
+        pkgJson = JSON.parse(pkgText);
+    }
+    catch (err) {
+        throw new Error(`testkit：package.json 非合法 JSON（${pluginDir}）：${err instanceof Error ? err.message : String(err)}`);
+    }
+    const parsedManifest = parseManifest(pkgJson, { official: false });
+    if (!parsedManifest.ok) {
+        throw new Error(`testkit：清单校验失败（${pluginDir}）：${parsedManifest.message}`);
+    }
+    const ownsDataDir = options.dataDir === undefined;
+    const dataDir = options.dataDir ?? mkdtempSync(join(tmpdir(), 'berry-testkit-'));
+    const storeFs = realStoreFs();
+    const audit = new MemoryAuditSink();
+    const commands = createCommandAccount();
+    const dispatch = new EventDispatch();
+    const listeners = instrumentDispatchListeners(dispatch);
+    const runtime = createHarnessRuntime(dataDir);
+    const scope = Scope.createRoot();
+    const lifecycleSink = (type, data) => audit.append(type, data);
+    let currentBoot = null;
+    // 本代完整卸载序（unloadRef 槽——apply disposer LIFO + fork 逆序 dispose
+    // 两腿全跑；report.unload() 只是 disposeStack 单腿，ctx.effect 注册回卷
+    // 在 fork 腿，故换代/收场必须走槽不走 report）
+    let currentUnload = null;
+    return {
+        dataDir,
+        pluginDir,
+        pluginId: parsedManifest.manifest.id,
+        manifest: parsedManifest.manifest,
+        packageJson: pkgJson,
+        audit,
+        commands,
+        dispatch,
+        listeners,
+        async install() {
+            const outcome = await installPlugin({
+                dataDir,
+                fs: storeFs,
+                // local: 源零 spawn 调用——占位 fail-loud（若未来装机编舞对 local
+                // 源触网，此占位当场红——testkit 断言面禁网）
+                spawn: {
+                    run: async (cmd) => {
+                        throw new Error(`testkit install 走 local: 源——不应触达执行器（${cmd}）`);
+                    },
+                },
+                onLifecycleAudit: lifecycleSink,
+            }, `local:${pluginDir}`);
+            return outcome.ok
+                ? { ok: true, id: outcome.entry.id, installPath: outcome.entry.installPath }
+                : { ok: false, message: outcome.message };
+        },
+        mountRow() {
+            return mountRow(dataDir, parsedManifest.manifest.id, undefined, storeFs, lifecycleSink);
+        },
+        toggleRow() {
+            return toggleRow(dataDir, parsedManifest.manifest.id, storeFs, lifecycleSink);
+        },
+        async boot() {
+            // 换代前置回卷（/reload 同语义：先卸旧代再起新代——不并代；完整卸载
+            // 序含 fork dispose，ctx.effect 注册在换代时自动撤注）
+            if (currentUnload !== null)
+                await currentUnload();
+            // 每代独立槽（bootPlugins 重跑即覆写槽——旧代卸载序须先行持走）
+            const unloadRef = { current: null };
+            const bootOptions = {
+                runtime,
+                scope,
+                dispatch,
+                commands: commands.registry,
+                llm: createLlmAccount(),
+                version: options.hostVersion ?? '0.0.0-testkit',
+                warn: options.warn ?? (() => undefined),
+                audit,
+                unloadRef,
+            };
+            currentBoot = await bootPlugins(bootOptions);
+            currentUnload = unloadRef.current;
+            return currentBoot;
+        },
+        async unloadCurrent() {
+            const unload = currentUnload;
+            currentUnload = null;
+            currentBoot = null;
+            return unload === null ? null : await unload();
+        },
+        grantOpens(opens) {
+            // 手编 enabled.yaml 形（03 §5.3 用户可编辑面的文档形——行级 opens 授予
+            // 无 CLI 动词，宿主真源路径即手编；此处以同形 yaml 重写全文件）
+            const read = readEnabledRowsForEdit(dataDir, storeFs);
+            if (!read.ok)
+                throw new Error(`testkit：enabled.yaml 坏形（${read.message}）`);
+            const rows = read.rows.map((row) => row.id === parsedManifest.manifest.id ? { ...row, opens: [...opens] } : row);
+            storeFs.write(join(dataDir, 'enabled.yaml'), stringifyYaml({ plugins: rows, ...((read.doors ?? []).length > 0 ? { doors: read.doors } : {}) }));
+        },
+        dataFiles() {
+            const top = (storeFs.readdir(dataDir) ?? []).filter((name) => name !== '.DS_Store');
+            const under = [];
+            for (const name of top) {
+                if (name === 'plugins') {
+                    for (const child of storeFs.readdir(join(dataDir, 'plugins')) ?? []) {
+                        under.push(`plugins/${child}`);
+                    }
+                }
+                else {
+                    under.push(name);
+                }
+            }
+            return under;
+        },
+        async dispose() {
+            try {
+                if (currentUnload !== null)
+                    await currentUnload();
+            }
+            finally {
+                if (ownsDataDir)
+                    rmSync(dataDir, { recursive: true, force: true });
+            }
+        },
+    };
+}
+/** npm pack 文件清单探测（--dry-run 零 tarball 落盘；60s 帽防挂） */
+export async function npmPackFiles(pluginDir) {
+    const run = promisify(execFile);
+    const { stdout } = await run('npm', ['pack', '--dry-run', '--json'], {
+        cwd: pluginDir,
+        maxBuffer: 16 * 1024 * 1024,
+        timeout: 60_000,
+    });
+    const parsed = JSON.parse(stdout);
+    return (parsed[0]?.files ?? []).map((f) => f.path);
+}

package/dist/host/testkit/index.js

@@ -0,0 +1,14 @@
+/**
+ * `berry-agent/testkit` 主包子路径公开面（03 §9.5——生态启动批 eco-3c）。
+ *
+ * 消费位：插件作者的 devDep 测试文件（`import { proveLifecycleMatrix } from
+ * 'berry-agent/testkit'`）——作者侧消费，非装载器 jiti 注入进插件沙箱
+ * （故不入 VIRTUAL_API_KEYS 六键表——03 §8.2 第七真相源独立子路径域）。
+ *
+ * 首版导出面：
+ * - proveLifecycleMatrix / formatMatrixReceipt —— 生命周期证明矩阵 + README 回执；
+ * - createPluginHarness 及配套件 —— 矩阵底座（假宿主装配），作者自定义
+ *   断言场景亦可直用（全部动词真身直调）。
+ */
+export { createPluginHarness, createCommandAccount, instrumentDispatchListeners, MemoryAuditSink, npmPackFiles, realStoreFs, } from './harness.js';
+export { proveLifecycleMatrix, formatMatrixReceipt } from './matrix.js';

package/dist/host/testkit/matrix.js

@@ -0,0 +1,302 @@
+/**
+ * testkit 生命周期证明矩阵（03 §9.5 首版断言矩阵——生态启动批 eco-3c）。
+ *
+ * 列 = 纯函数断言 / 假宿主断言（真宿主层延后随金样轨并轨——首版锁假宿主
+ * 层 + 真装载器两件防范围膨胀）。行 = install/mount/unmount/事件面必进；
+ * toggle/开门面/幂等负向顺手进；update/审批面/真宿主层延后（规范表同序）。
+ *
+ * 全部断言经 harness 真装载整体走真（installPlugin/mountRow/toggleRow/
+ * bootPlugins/report.unload 真身直调）——手工拼 ctx.plugin 的证明不算数。
+ * 产出可贴 README 的 markdown 回执（formatMatrixReceipt）。
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { createJiti } from 'jiti';
+import { createPluginHarness, npmPackFiles } from './harness.js';
+/** 宿主记账方白名单（审计词面——宿主自身记账是合法残留，dsh 快照 diff 同律） */
+const HOST_AUDIT_WHITELIST = new Set([
+    'plugin/installed',
+    'plugin/mounted',
+    'plugin/unmounted',
+    'plugin/toggled',
+    'plugin/updated',
+    'plugin/opens',
+    'doors/updated',
+]);
+/** skipped 行信号（runRow 识别后落 skipped 态——环境不适用非放行冒充） */
+class SkippedRow extends Error {
+}
+/**
+ * 数据面合法文件集（装机/启用/boot 记账三源落盘——其余即残留；local 源直引
+ * 不拷贝故无 node_modules）。boot-failures.json = 绿 boot 也触写（装载成功对
+ * activated 逐行 clearBootFailure）——宿主记账方合法残留，dsh 白名单同律。
+ */
+const HOST_DATAFILE_WHITELIST = new Set(['enabled.yaml', 'plugins/ledger.json', 'boot-failures.json']);
+/** 开门面样本授予（USER_GRANTABLE_CAPABILITIES 首枚——行校验值域内样本） */
+const OPENS_SAMPLE = 'channels.ui-backend';
+/**
+ * 生命周期证明矩阵主入口——一站式可召唤（作者测试一行起跑）：
+ *
+ * ```ts
+ * const report = await proveLifecycleMatrix({ pluginDir: __dirname });
+ * expect(report.ok).toBe(true);
+ * ```
+ *
+ * 收场自动回卷在飞代 + 清理自建临时目录（报告先行返回——dispose 失败不折损证明）。
+ */
+export async function proveLifecycleMatrix(options) {
+    const rows = [];
+    const expectCommands = options.expect?.commands ?? [];
+    let harness = null;
+    /** 单行跑手（红 = 该行 fail；SkippedRow = 环境不适用；异常讯息即 detail） */
+    const runRow = async (row, fn) => {
+        try {
+            await fn();
+            rows.push({ row, status: 'pass' });
+        }
+        catch (err) {
+            if (err instanceof SkippedRow) {
+                rows.push({ row, status: 'skipped', detail: err.message });
+                return;
+            }
+            rows.push({ row, status: 'fail', detail: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    try {
+        try {
+            harness = createPluginHarness(options);
+        }
+        catch (err) {
+            // 构造即红（缺清单/坏清单）——install 行收面，矩阵不整体炸
+            rows.push({
+                row: 'install（装机 + pack 完整性）',
+                status: 'fail',
+                detail: err instanceof Error ? err.message : String(err),
+            });
+            return { pluginId: '(unknown)', ok: false, rows };
+        }
+        const h = harness;
+        /* ---------------- install（必进） ---------------- */
+        await runRow('install（装机 + pack 完整性）', async () => {
+            const outcome = await h.install();
+            if (!outcome.ok)
+                throw new Error(`装机拒：${outcome.message}`);
+            if (outcome.id !== h.pluginId)
+                throw new Error(`装机账本 id（${outcome.id}）≠ 清单 id（${h.pluginId}）`);
+            // default-export 陷阱正向探针（纯声明包 main 带 default export 函数 = 永不执行的死代码作者陷阱）
+            const mainFile = resolvePackageMain(h.pluginDir, h.packageJson);
+            if (h.manifest.entryPlan.kind === 'declared-payload' && mainFile !== null) {
+                const namespace = await jitiProbe(mainFile);
+                if (namespace !== null && typeof namespace.default === 'function') {
+                    throw new Error(`纯声明包 main（${mainFile}）带 default export 函数——declared-payload 形包主入口不执行（要么声明 berryAgent.entry 走代码插件，要么移除 default export）`);
+                }
+            }
+            if (options.packCheck === false)
+                return;
+            let packed;
+            try {
+                packed = await npmPackFiles(h.pluginDir);
+            }
+            catch (err) {
+                // npm 缺席（ENOENT）= 环境位 skipped；其余 npm 报错照红（fail-loud 不吞）
+                if (err instanceof Error && err.code === 'ENOENT') {
+                    throw new SkippedRow('npm pack 探测不可用（环境无 npm）——pack 完整性未证');
+                }
+                throw err;
+            }
+            const referenced = packReferencedFiles(h.pluginDir, h.manifest);
+            const missing = referenced.filter((ref) => !packed.includes(ref));
+            if (missing.length > 0) {
+                throw new Error(`npm pack 产物缺插件引用文件（files 白名单漏收）：${missing.join('、')}——发布物将不含装载必需文件`);
+            }
+        });
+        /* ---------------- mount（必进） ---------------- */
+        await runRow('mount（真装载 activated + 注册账在场）', async () => {
+            const mounted = h.mountRow();
+            if (!mounted.ok)
+                throw new Error(`启用行拒：${mounted.message}`);
+            const boot = await h.boot();
+            const activated = boot.report.activated.find((a) => a.id === h.pluginId);
+            if (activated === undefined) {
+                const failed = boot.report.failed.find((f) => f.id === h.pluginId);
+                throw new Error(failed === undefined
+                    ? `装载计划面缺席（activated/failed 皆无 ${h.pluginId}）`
+                    : `装载失败（${failed.code}）：${failed.message}`);
+            }
+            // 注册账在场（作者声明面）：命令名净计数 ≥ 1
+            for (const name of expectCommands) {
+                const count = h.commands.counts().get(name) ?? 0;
+                if (count < 1)
+                    throw new Error(`期望命令 /${name} 未注册（注册账缺席）`);
+            }
+            // 纯声明形：技能/agents 目录账与清单声明同长
+            if (h.manifest.entryPlan.kind === 'declared-payload') {
+                const declaredSkills = h.manifest.skills?.length ?? 0;
+                if (activated.skillDirs.length !== declaredSkills) {
+                    throw new Error(`技能目录账（${activated.skillDirs.length}）≠ 清单声明（${declaredSkills}）`);
+                }
+            }
+        });
+        /* ---------------- 事件面（必进——审计不 mock 真词面） ---------------- */
+        await runRow('事件面（plugin/mounted 恰一笔）', async () => {
+            const mountedCount = h.audit.countOf('plugin/mounted', (data) => data['id'] === h.pluginId);
+            if (mountedCount !== 1) {
+                throw new Error(`plugin/mounted 笔数 = ${mountedCount}（期 1——mountRow 一笔、boot diff 不重放）`);
+            }
+        });
+        /* ---------------- 幂等/负向（顺手进） ---------------- */
+        await runRow('幂等/负向（换代不双注 + mountRow 撞名拒）', async () => {
+            await h.boot(); // 换代（harness 内先卸旧代再起新代——/reload 同语义）
+            const mountedCount = h.audit.countOf('plugin/mounted', (data) => data['id'] === h.pluginId);
+            if (mountedCount !== 1)
+                throw new Error(`换代后 plugin/mounted 笔数 = ${mountedCount}（期 1——幂等 diff 不重放）`);
+            for (const name of expectCommands) {
+                const count = h.commands.counts().get(name) ?? 0;
+                if (count !== 1)
+                    throw new Error(`换代后命令 /${name} 净计数 = ${count}（期 1——旧代出账后新代单注）`);
+            }
+            const dup = h.mountRow();
+            if (dup.ok)
+                throw new Error('mountRow 重复调用未被拒（撞名拒缺席——幂等执法失守）');
+        });
+        /* ---------------- toggle（顺手进——行翻转两断言） ---------------- */
+        await runRow('toggle（行翻转两断言）', async () => {
+            const off = h.toggleRow();
+            if (!off.ok)
+                throw new Error(`禁用翻转拒：${off.message}`);
+            const offBoot = await h.boot();
+            if (!offBoot.report.skipped.some((s) => s.id === h.pluginId)) {
+                throw new Error('禁用行不在 skipped 面（disabled 旗标未生效）');
+            }
+            // boot diff 五形：enabled→disabled 时尾态已同（toggleRow 笔在前）→ 一致零落
+            const offToggled = h.audit.countOf('plugin/toggled', (data) => data['id'] === h.pluginId && data['disabled'] === true);
+            if (offToggled !== 1)
+                throw new Error(`禁用后 plugin/toggled{true} 笔数 = ${offToggled}（期 1）`);
+            const on = h.toggleRow();
+            if (!on.ok)
+                throw new Error(`回启用翻转拒：${on.message}`);
+            const onBoot = await h.boot();
+            if (!onBoot.report.activated.some((a) => a.id === h.pluginId)) {
+                throw new Error('回启用行不在 activated 面（旗标撤除未生效）');
+            }
+        });
+        /* ---------------- 开门面（顺手进——幂等 diff） ---------------- */
+        await runRow('开门面（plugin/opens 幂等 diff）', async () => {
+            h.grantOpens([OPENS_SAMPLE]);
+            await h.boot();
+            const opensRows = h.audit.all().filter((r) => r.type === 'plugin/opens' && r.data['pluginId'] === h.pluginId);
+            if (opensRows.length !== 1)
+                throw new Error(`plugin/opens 笔数 = ${opensRows.length}（期 1）`);
+            const recorded = opensRows[0].data['opens'];
+            if (JSON.stringify(recorded) !== JSON.stringify([OPENS_SAMPLE])) {
+                throw new Error(`plugin/opens 载荷 ${JSON.stringify(recorded)} ≠ 授予面 [${OPENS_SAMPLE}]`);
+            }
+            await h.boot(); // 幂等：同面再 boot 不重放
+            const after = h.audit.countOf('plugin/opens', (data) => data['pluginId'] === h.pluginId);
+            if (after !== 1)
+                throw new Error(`幂等再 boot 后 plugin/opens 笔数 = ${after}（期 1——有变才落失守）`);
+        });
+        /* ---------------- unmount（必进——absent 与 present 同重） ---------------- */
+        await runRow('unmount（disposer 回卷 + 注册账缺席）', async () => {
+            const receipt = await h.unloadCurrent();
+            // 回执两查：有在飞代可回卷（null = 无代可卸——装载从未成）+ 回卷零失败
+            //（receipt.disposed 只列 apply 返回清理函数的插件——ctx.effect 形注册
+            // 走 fork dispose 腿不进 disposed 清单，故「已卸载」的真证明在下方账面）
+            if (receipt === null)
+                throw new Error('回卷回执 null（无在飞代可卸——装载从未成）');
+            if (receipt.failed.length > 0) {
+                throw new Error(`回卷失败面非空：${receipt.failed.map((f) => f.id).join('、')}`);
+            }
+            for (const name of expectCommands) {
+                const count = h.commands.counts().get(name) ?? 0;
+                if (count !== 0)
+                    throw new Error(`回卷后命令 /${name} 净计数 = ${count}（期 0——absent 断言同重）`);
+            }
+            for (const [word, net] of h.listeners.netCounts()) {
+                if (net !== 0)
+                    throw new Error(`回卷后事件词 ${word} 净监听数 = ${net}（期 0——零注册残留）`);
+            }
+        });
+        /* ---------------- 残留检查（白名单豁免——宿主记账方是合法残留） ---------------- */
+        await runRow('残留检查（审计词 + 数据面双白名单）', async () => {
+            const strayWords = [...new Set(h.audit.all().map((r) => r.type))].filter((t) => !HOST_AUDIT_WHITELIST.has(t));
+            if (strayWords.length > 0)
+                throw new Error(`审计流出现白名单外词：${strayWords.join('、')}`);
+            const strayFiles = h.dataFiles().filter((f) => !HOST_DATAFILE_WHITELIST.has(f));
+            if (strayFiles.length > 0)
+                throw new Error(`数据目录出现白名单外文件：${strayFiles.join('、')}`);
+        });
+        return { pluginId: h.pluginId, ok: rows.every((r) => r.status !== 'fail'), rows };
+    }
+    finally {
+        // 收场恒跑（证明先行——dispose 异常不折损已得报告）
+        await harness?.dispose().catch(() => undefined);
+    }
+}
+/**
+ * pack 引用集（装载必需文件的清单侧全集）：entry-file 入口 + skills/agents
+ * 声明目录下全部文件（相对包根 posix 形——npm pack 产物路径同形比对）。
+ */
+function packReferencedFiles(pluginDir, manifest) {
+    const refs = [];
+    // entry-file 形入口在场（entryPlan 判据同源——entry 字段类型可选故判空防）
+    if (manifest.entryPlan.kind === 'entry-file' && manifest.entry !== undefined) {
+        refs.push(posix.normalize(manifest.entry));
+    }
+    for (const dir of [...(manifest.skills ?? []), ...(manifest.agents ?? [])]) {
+        const abs = join(pluginDir, dir);
+        if (!statSync(abs).isDirectory())
+            throw new Error(`声明载荷目录缺席：${dir}`);
+        // 基 = 包根（npm pack 产物路径相对包根——目录基会推成目录内相对形比对永错）
+        collectFiles(pluginDir, abs, refs);
+    }
+    return refs;
+}
+/** 目录递归收文件（rel 基 = 包根——与 npm pack 产物路径同形） */
+function collectFiles(base, dir, out) {
+    for (const name of readdirSync(dir)) {
+        const abs = join(dir, name);
+        if (statSync(abs).isDirectory())
+            collectFiles(base, abs, out);
+        else
+            out.push(posix.normalize(abs.slice(base.length + 1)));
+    }
+}
+/** 包主入口解析（main/module 字段 → 存在的文件；缺席 = null） */
+function resolvePackageMain(pluginDir, pkg) {
+    const candidate = typeof pkg['main'] === 'string' ? pkg['main'] : typeof pkg['module'] === 'string' ? pkg['module'] : null;
+    if (candidate === null)
+        return null;
+    const abs = join(pluginDir, candidate);
+    try {
+        return statSync(abs).isFile() ? abs : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** main 模块求值探针（求值失败 = null 非红——失败证据缺席不冒充在场） */
+async function jitiProbe(mainPath) {
+    try {
+        const jiti = createJiti(mainPath);
+        return (await jiti.import(mainPath));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 可贴 README 的 markdown 回执（「产出可贴 README 的证明」——03 §9.5 定位段）。
+ */
+export function formatMatrixReceipt(report) {
+    const lines = [
+        `## berry-agent 插件生命周期证明 —— ${report.pluginId}`,
+        '',
+        '| 检查行 | 结果 |',
+        '| --- | --- |',
+        ...report.rows.map((r) => `| ${r.row} | ${r.status === 'pass' ? '✅' : r.status === 'skipped' ? '⏭️' : '❌'}${r.detail === undefined ? '' : `（${r.detail}）`} |`),
+        '',
+        ` berry-agent testkit · 共 ${report.rows.length} 行`,
+    ];
+    return lines.join('\n');
+}