@bolloon/bolloon-agent 0.5.3 → 0.5.5

package/dist/agents/experience-review.js

@@ -0,0 +1,226 @@
+/**
+ * 回合后自审 → 沉淀可复用经验 (2026-10-01, 用户「落实」)。
+ *
+ * 为什么: 智能体目前只在**回合内**反应 —— 做完就完了, 经验不落库。飞轮目标里"结束后沉淀可复用经验"
+ *   是唯一还没动工的一段。做法学的是运行时那套**回合后自审**的机制, 约束照搬:
+ *     · 只写**沉淀库**, **绝不碰主对话 / prompt 缓存**(所以纯旁路, 不影响用户看到的内容);
+ *     · **不阻塞主回合**: 调用方 fire-and-forget, 本模块自己吞掉所有异常;
+ *     · **工具白名单**: v1 连工具都不用 —— 只把"本回合摘要 + 现有库目录"喂给模型, 要它回一段 JSON;
+ *     · **fail-open**: 节流/配置读不出来时**放行**(宁可偶尔多审一次, 不要因配置坏掉就永久不审);
+ *     · **绝不编造**: 没有值得记的就回 none, 那就什么都不写(写空是正常结果, 不是失败)。
+ * 库的形态(反囤积): `~/.bolloon/experience/<类>.md`, **类级**文件 + 条目标题去重 ——
+ *   「同一教训学两次 = 改那一条, 不是加一条」。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+export const EXPERIENCE_DIR_NAME = 'experience';
+/** 同一个 agent 两次自审的最小间隔 (默认 10 分钟; 可用 BOLLOON_EXPERIENCE_REVIEW_MIN_MS 覆盖) */
+export const DEFAULT_MIN_INTERVAL_MS = 10 * 60 * 1000;
+export function experienceDir(home = os.homedir()) {
+    return path.join(home, '.bolloon', EXPERIENCE_DIR_NAME);
+}
+/** 类名净化 (只允许安全字符; 空 ⇒ 'general') */
+export function sanitizeClass(k) {
+    const s = String(k ?? '').trim().toLowerCase().replace(/[^a-z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '');
+    return s || 'general';
+}
+/** 条目标题净化 (空 ⇒ 拒绝写: 没有标题的沉淀无法去重, 宁可不要) */
+export function sanitizeTitle(t) {
+    return String(t ?? '').trim().replace(/\s+/g, ' ').slice(0, 120);
+}
+/**
+ * 节流判据 (纯函数)。**fail-open**: 时间戳坏了/缺失 ⇒ 放行。
+ * @param lastAtMs 上一次自审时间 (0/undefined = 从未)
+ */
+export function shouldReview(nowMs, lastAtMs, minIntervalMs = DEFAULT_MIN_INTERVAL_MS) {
+    if (!Number.isFinite(nowMs) || nowMs <= 0)
+        return true; // 时钟坏了 ⇒ 放行 (fail-open)
+    if (!lastAtMs || !Number.isFinite(lastAtMs) || lastAtMs <= 0)
+        return true; // 从未审过 ⇒ 放行
+    if (!Number.isFinite(minIntervalMs) || minIntervalMs <= 0)
+        return true; // 配置坏了 ⇒ 放行 (fail-open)
+    return nowMs - lastAtMs >= minIntervalMs;
+}
+/**
+ * **每次任务都复盘** (2026-10-01, 用户: 「自动每次做完任务都要总结经验」)。
+ * 与 `shouldReview` 的区别: 那个是"每 10 分钟最多一次" ✗ —— 会漏掉"做完一个任务"这种**事件** ✓;
+ * 这条按**任务签名**判: 签名变了(换任务了) ⇒ **立刻复盘** ✓; 同一任务重复 ⇒ 才回到节流 ✓。
+ * (成本控制: 只在"这一回合真的干了活"时才算签名 —— 由调用方保证 ✓; 且复盘是 fire-and-forget ✓。)
+ */
+export function shouldReviewTask(nowMs, lastAtMs, lastSig, sig, minIntervalMs = DEFAULT_MIN_INTERVAL_MS) {
+    if (sig && sig !== lastSig)
+        return true; // ★ 换了任务 ⇒ 立刻复盘
+    return shouldReview(nowMs, lastAtMs, minIntervalMs); // 同一任务 ⇒ 仍按节流, 免得反复审同一段
+}
+/** 现有库的目录 (喂给模型, 让它知道"已经有哪些类/条目", 从而倾向于改而不是加) */
+export function listExperienceIndex(home = os.homedir()) {
+    const dir = experienceDir(home);
+    try {
+        const files = fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
+        if (!files.length)
+            return '(沉淀库还是空的)';
+        return files.slice(0, 30).map((f) => {
+            const body = fs.readFileSync(path.join(dir, f), 'utf-8');
+            const titles = [...body.matchAll(/^##\s+(.+)$/gm)].map((m) => m[1].trim()).slice(0, 20);
+            return `- ${f} (${titles.length} 条)\n${titles.map((t) => `    · ${t}`).join('\n')}`;
+        }).join('\n');
+    }
+    catch {
+        return '(沉淀库还是空的)';
+    }
+}
+/**
+ * 自审提示词 (纯函数)。**反囤积**规矩逐条写进去 —— 这是"库会变干净还是变垃圾堆"的分水岭。
+ */
+export function buildReviewPrompt(turnSummary, existingIndex) {
+    return [
+        '你在做**回合后自审**: 判断上面这一回合里有没有值得沉淀成"可复用经验"的东西。',
+        '',
+        '已经沉淀过的(先看这里, 别重复):',
+        existingIndex,
+        '',
+        '这一回合发生了什么:',
+        '"""',
+        String(turnSummary || '').slice(0, 6000),
+        '"""',
+        '',
+        '规矩(按这个判):',
+        '1. **同一教训学两次 = 一条规矩**: 若上面已有同类条目 ⇒ 用同一个 title, 表示"更新那一条"; 否则才算新条目。',
+        '2. 只沉淀**可复用**的: 类级规律 · 踩过的坑与判据 · 用户对做法/风格的纠正 · 稳定的环境事实。',
+        '3. **不要**沉淀: 本次事件叙述 · 版本号/日期流水 · 一次性任务进度 · 环境依赖型失败(缺二进制、首次安装报错)。',
+        '4. 没有值得记的就回 none —— **写空是正常结果**, 不是失败; 编一条凑数比不写更糟。',
+        '5. 内容要短: title ≤ 60 字, body ≤ 400 字, body 写"规矩 + 为什么", 不写过程。',
+        '',
+        '只回一个 JSON(不要别的文字):',
+        '{"action":"none"} 或 {"action":"write","class":"类名(小写-连字符)","title":"一句话标题","body":"规矩与理由"}',
+    ].join('\n');
+}
+/** 容错解析模型回的那段 JSON (纯函数)。任何异常/不完整 ⇒ none (绝不半写) */
+export function parseReviewDecision(text) {
+    const raw = String(text || '');
+    const m = raw.match(/\{[\s\S]*\}/);
+    // 2026-10-01 (用户: 「卡在这就不动了」现场: 日志里连着出现 "审了但没写: 没找到 JSON" ✗ ⇒ 复盘白跑):
+    //   模型 Often 不给严格 JSON ⇒ 原来直接当"没写" ✗。现在: ① 没花括号时**宽解析**(从文本里抠字段 ✓);
+    //   ② 仍解析不出 ⇒ 把**原文头部**记进日志(才能知道它到底回了什么 ✓, 不再瞎 ✗)。
+    if (!m) {
+        const act = /(?:^|["'\s])action["'\s:：]*["']?([a-z_]+)/i.exec(raw)?.[1]
+            || (/\bwrite\b/i.test(raw) ? 'write' : (/\bnone\b|不用|无需/i.test(raw) ? 'none' : ''));
+        if (act === 'write') {
+            const title = /(?:title|标题)["'\s:：]*["']?([^"'\n]{2,80})/i.exec(raw)?.[1]?.trim() || '未命名教训';
+            const body = /(?:body|内容|教训)["'\s:：]*["']?([\s\S]{20,1200}?)(?:["'\n]|$)/i.exec(raw)?.[1]?.trim() || raw.slice(0, 400);
+            if (body.length >= 20)
+                return { action: 'write', file: 'lessons.md', title, body, klass: 'general', reason: '宽解析' };
+        }
+        if (act === 'none')
+            return { action: 'none', reason: '模型判定无需记录(宽解析)' };
+        return { action: 'none', reason: `没找到 JSON(模型原文头部: ${raw.replace(/\s+/g, ' ').slice(0, 120)})` };
+    }
+    try {
+        const j = JSON.parse(m[0]);
+        if (String(j?.action || '').toLowerCase() !== 'write')
+            return { action: 'none' };
+        const title = sanitizeTitle(j.title);
+        const body = String(j?.body ?? '').trim().slice(0, 800);
+        if (!title || !body)
+            return { action: 'none', reason: 'title/body 不全' }; // 宁可丢, 不写半条
+        return { action: 'write', klass: sanitizeClass(j.class), title, body };
+    }
+    catch {
+        return { action: 'none', reason: 'JSON 解析失败' };
+    }
+}
+/**
+ * 落库: **同 title 就更新那一条**(hit+1, 替换正文), 否则追加。
+ * @returns 实际动作, 便于测试与日志
+ */
+export function applyExperience(d, home = os.homedir(), nowIso = new Date().toISOString()) {
+    if (d.action !== 'write' || !d.title || !d.body)
+        return { wrote: false };
+    const dir = experienceDir(home);
+    const file = path.join(dir, `${sanitizeClass(d.klass)}.md`);
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        let cur = '';
+        try {
+            cur = fs.readFileSync(file, 'utf-8');
+        }
+        catch {
+            cur = '';
+        }
+        const header = cur.trim() ? cur : `# 可复用经验 · ${sanitizeClass(d.klass)}\n\n> 回合后自审沉淀; 同一教训只留一条(重复出现则更新) · 每条带出现次数与末次时间\n`;
+        // 2026-10-01 修: 上一版用正则 `...(?=^## |\Z)` 找条目边界 —— **JS 不支持 \Z**, 它被当成字面量 Z,
+        //   而条目的时间戳正好以 Z 结尾 ⇒ 从那儿截断, 更新后留下旧正文残渣(实跑看到: "Z -->" + 旧正文)✗。
+        //   改成**按 `## ` 切块再拼** —— 不依赖任何正则边界语义。
+        const blockOf = (t, body, hits) => `## ${t}\n<!-- hit:${hits} last:${nowIso} -->\n${body}\n`;
+        const parts = header.split(/\n(?=## )/);
+        const head = parts[0].trimEnd();
+        const entries = parts.slice(1).filter((x) => x.trim().startsWith('## '));
+        const titleOf = (blk) => (blk.split('\n')[0] || '').replace(/^##\s*/, '').trim();
+        const hitsOf = (blk) => Number((blk.match(/<!--\s*hit:(\d+)/) || [])[1] || 0);
+        const idx = entries.findIndex((blk) => titleOf(blk) === d.title);
+        if (idx >= 0) {
+            const n = hitsOf(entries[idx]) + 1; // 上一次次数 + 本次 (更新 ⇒ 至少 2)
+            entries[idx] = blockOf(d.title, d.body, n);
+            fs.writeFileSync(file, head + '\n\n' + entries.map((x) => x.trimEnd()).join('\n\n') + '\n', 'utf-8');
+            return { wrote: true, file, updated: true };
+        }
+        entries.push(blockOf(d.title, d.body, 1));
+        fs.writeFileSync(file, head + '\n\n' + entries.map((x) => x.trimEnd()).join('\n\n') + '\n', 'utf-8');
+        return { wrote: true, file, updated: false };
+    }
+    catch {
+        return { wrote: false };
+    }
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * 自审编排 (纯旁路, **绝不抛错**)。
+ *
+ * `chat` 由调用方注入 (便于门测; 生产用现成的单次补全)。整段逻辑:
+ *   节流 ⇒ 取库目录 ⇒ 拼提示 ⇒ 一次补全 ⇒ 解析 ⇒ 落库。
+ * 任何一步失败都只是"这次没沉淀", 不影响主回合 —— 调用方 fire-and-forget 即可。
+ */
+export async function runExperienceReview(opts) {
+    const home = opts.home || os.homedir();
+    const now = opts.nowMs ?? Date.now();
+    const log = opts.log || (() => { });
+    try {
+        if (!opts.force && !shouldReview(now, opts.lastAtMs, opts.minIntervalMs))
+            return { reviewed: false, applied: false, reason: 'throttled' };
+        const summary = String(opts.turnSummary || '').trim();
+        if (summary.length < 40)
+            return { reviewed: false, applied: false, reason: '回合太短, 不值得审' };
+        const prompt = buildReviewPrompt(summary, listExperienceIndex(home));
+        // 2026-10-01 (用户: 「卡在这就不动了」+ 复盘日志里 "开始" 之后没有下文 ✗):
+        //   review 的 chat 调用**原来没有超时** ⇒ 一旦 provider 慢/挂, 这条就永远不返回 ✓。
+        //   现在给**硬超时**(默认 25s, 可配 ✓), 超时如实记一条并放行 ✓ —— 复盘是锦上添花, 绝不许拖住主流程 ✓。
+        const chatTimeoutMs = Number(process.env.BOLLOON_REVIEW_TIMEOUT_MS) || 25_000;
+        const raw = await Promise.race([
+            opts.chat(prompt),
+            new Promise((resolve) => setTimeout(() => resolve('__TIMEOUT__'), chatTimeoutMs)),
+        ]);
+        if (raw === '__TIMEOUT__') {
+            log(`审查超时(${chatTimeoutMs}ms) —— 本轮不复盘, 已放行(绝不拖住主流程)`);
+            return { reviewed: false, applied: false, reason: 'chat-timeout' };
+        }
+        const d = parseReviewDecision(raw);
+        if (d.action !== 'write')
+            return { reviewed: true, applied: false, reason: d.reason || 'none' };
+        const r = applyExperience(d, home, new Date(now).toISOString());
+        if (r.wrote) {
+            log(`[experience] ${r.updated ? '更新' : '新增'} ${path.basename(r.file)} · ${d.title}`);
+            try {
+                opts.onLesson?.({ title: d.title, body: d.body, klass: d.klass });
+            }
+            catch { /* 回调绝不影响落库 */ }
+        }
+        return { reviewed: true, applied: r.wrote, file: r.wrote ? r.file : undefined, updated: r.wrote ? r.updated : undefined };
+    }
+    catch (e) {
+        log(`[experience] 自审跳过(非致命): ${String(e?.message || e).slice(0, 120)}`);
+        return { reviewed: false, applied: false, reason: 'error' };
+    }
+}

package/dist/agents/gateway-group.js

@@ -1,8 +1,8 @@
 /**
  * gateway-group.ts — Agent Gateway P2P 群组 (2026-08-14)
  *
- * 群组 = OrbitDB events store (accessController write:'*'), 任何成员可广播消息,
- * 全成员通过 OrbitDB pubsub 复制实时同步. 链接: orbitdb://<addr>?type=group&name=<群名>.
+ * 群组 = OrbitDB events store, 全成员通过 OrbitDB pubsub 复制实时同步.
+ * 链接: orbitdb://<addr>?type=group&name=<群名>.
  *
  * 符合用户习惯: 群组 = 微信式群聊 — 加入链接即进群, 发消息全网同步.
  * 持久化: ~/.bolloon/gateway-groups.json (重启后仍是群成员, 自动重开 store).
@@ -14,12 +14,26 @@
  *     (修复前: 区块只在内存, 新进程一开就报 "No block brokers capable of retrieving blocks")
  *   · 读不到必须报读不到: `groupMessages` 在 store 打不开时**抛 GroupStoreUnreachableError**,
  *     不再返回 `[]`。把"读不到"显示成"群里没有消息"是骗人, 本条不可回退。
+ *
+ * 2026-10-01 (P1) DID 门控:
+ *   · `createGroup(name, { gate: { owner, members?, membershipEvents? } })` 建的是**门控群**:
+ *     写入白名单 = 群主 OrbitDB 写身份 + 显式成员, 非名单成员 add 会被拒。
+ *   · 不给 `gate` → 行为**一字不变** (write:['*']); 默认翻成门控需要先迁移全部既有调用点。
+ *   · 成员变更 = `MembershipEvent` (成员自签 + 群主签, 双侧 Ed25519 验签), 读写入口
+ *     `recordMembershipEvent` / `groupMembershipEvents` / `groupWriteList`。
+ *   · **白名单不能就地改** (IPFS 型 AC 的白名单在内容寻址的 ACL 块里, 改它 = 换 store 地址),
+ *     所以"改成员"= 重建 store; 代价清单见 `group-access.ts` 的 `aclChangePlan()`。
  */
 import * as os from 'os';
 import * as path from 'path';
 import { getCIDDatabase } from '../orbitdb/cid-database.js';
 // 2026-09-28: 交流语言 (Efficode 是可选项, 不是默认项) —— 只有双方都声明才用
 import { decodeFromPeer, encodeForPeer, recordLangDecision } from '../efficode/negotiate.js';
+// 2026-10-01 (P1): **DID 门控** —— 群写入白名单从 write:['*'] 收紧成成员白名单。
+// 白名单里放的是 **OrbitDB 写身份 id** (66 位压缩 secp256k1 公钥 hex), 不是 DID 字符串
+// (canAppend 只比 identity.id; 放 DID 会永远匹配不上 → 谁都写不了)。
+// 成员变更 = 一条**双侧 Ed25519 验签**的群事件 (成员自签 + 群主签), 细节见 group-access.ts。
+import { applyMembershipEvents, groupAccessOptions, membershipEntryOf, normalizeWriteList, verifyMembershipEvent, GROUP_MEMBERSHIP_KIND, } from '../orbitdb/group-access.js';
 // ============ 依赖注入 (测试用, 避免单测起真实 OrbitDB 节点) ============
 let _dbOverride = null;
 /** 测试用: 注入 fake CIDDatabase */
@@ -116,9 +130,15 @@ function groupIdOf(address) {
     return m ? m[1] : address;
 }
 /**
- * 打开群组 store (缓存) — 可写 (replica=false, write:'*')。
+ * 打开群组 store (缓存)。
  * 打不开 → 记下原始原因 + 返回 null (不抛: 调用方各自决定用什么话术报)。
  * 2026-09-24: 必须 try/catch —— openStoreByAddress 现在抛 OrbitDBStoreUnreachableError。
+ *
+ * 2026-10-01 (P1): **不再传 `accessController`**。打开一个**合法已存在地址**时, OrbitDB
+ * 从 manifest 里取回 ACL 并覆盖入参 (`@orbitdb/core` src/orbitdb.js:129-131), 所以这里
+ * 传 `write:['*']` 是**死代码** —— 之前那行会让人误以为"打开时放开成任何人可写"。
+ * 真正的写权限 = 建群时烧进 manifest 的白名单 (DID 门控群 = 成员白名单)。
+ * 能不能写由 manifest 决定 + 调用方是否 add/put 决定; 本函数不做权限判定。
  */
 async function openGroupStore(address) {
     const id = groupIdOf(address);
@@ -127,13 +147,7 @@ async function openGroupStore(address) {
     const db = getDb();
     let store = null;
     try {
-        // 2026-09-24: 不再传 `replica` —— `@orbitdb/core` 4.0.0 的 open() 没有这个参数
-        // (src/orbitdb.js:118), 传了被丢; 之前那行是"不存在的语义"。
-        // 可写与否由 manifest 里的 ACL 决定, 且**打开既有地址时 ACL 从 manifest 取回、
-        // 入参 accessController 被覆盖** (src/orbitdb.js:129-131) —— 所以这里传什么都不改变权限。
-        store = await db.openStoreByAddress(address, 'events', {
-            accessController: { write: ['*'] },
-        });
+        store = await db.openStoreByAddress(address, 'events', {});
     }
     catch (e) {
         openFailures.set(id, e);
@@ -169,17 +183,49 @@ export function onGroupMessage(groupId, fn) {
     onChangeCallbacks.get(groupId).add(fn);
     return () => { onChangeCallbacks.get(groupId)?.delete(fn); };
 }
-// ============ 群组操作 ============
-/**
- * 创建群组: 新 events store (write:'*') + 持久化 + 生成邀请链接.
- */
 export async function createGroup(name, opts) {
     const groupName = String(name || '').trim() || `group-${Date.now().toString(36).slice(-4)}`;
     try {
         const db = getDb();
-        const store = await db.openStore(`bolloon-gw-group-${groupName}`, 'events', {
-            accessController: { write: ['*'] },
-        });
+        // ---- 门控分支: 先派生白名单 (验签不过就直接拒), 再建 store ----
+        // null = 不传 write 列表 ⇒ OrbitDB 默认 (创建者独占). 不再默认 ['*'].
+        let writeList = null;
+        let gateInfo = {};
+        let membershipEntries = [];
+        if (opts?.gate) {
+            const gate = opts.gate;
+            const applied = await applyMembershipEvents({
+                owner: gate.owner,
+                events: gate.membershipEvents ?? [],
+            });
+            if (applied.rejected.length > 0) {
+                return {
+                    ok: false,
+                    error: `拒绝据此建群: ${applied.rejected.length} 条成员事件未通过验签/授权 —— ${applied.rejected[0].reason}`,
+                };
+            }
+            // 白名单 = 群主 ∪ 事件派生成员 ∪ 直接点名成员
+            const ids = [
+                gate.owner.orbitdbId,
+                ...applied.members.map((m) => m.orbitdbId),
+                ...(gate.members ?? []).map((m) => m.orbitdbId),
+            ];
+            writeList = normalizeWriteList(ids);
+            gateInfo = { gated: true, ownerDid: gate.owner.did, aclWrite: writeList };
+            membershipEntries = applied.accepted.map(membershipEntryOf);
+        }
+        else if (opts?.acl === 'open') {
+            // 显式声明开放写入 (产品语义: 谁拿到邀请链接都能发言) —— 打一行 warn 留痕
+            writeList = ['*'];
+            console.warn(`[group] ${groupName}: acl=open ⇒ 任何人可写 (调用方显式声明)`);
+        }
+        else {
+            console.warn(`[group] ${groupName}: 未声明 acl ⇒ 创建者独占写入 (2026-10-01 起的默认)`);
+        }
+        const store = await db.openStore(`bolloon-gw-group-${groupName}`, 'events', 
+        // 注意: groupAccessOptions([]) 会抛错 (空名单会被 accessControllerOption 丢掉 ⇒ 落回默认),
+        // 所以"创建者独占"这条路只能**不传** AC 选项 ⇒ 传 {}.
+        writeList ? groupAccessOptions(writeList) : {});
         const address = store.address;
         const id = groupIdOf(address);
         const link = `orbitdb://${address}?type=group&name=${encodeURIComponent(groupName)}`;
@@ -187,10 +233,14 @@ export async function createGroup(name, opts) {
             id, name: groupName, address, link,
             createdAt: new Date().toISOString(),
             lastSyncAt: new Date().toISOString(),
+            ...gateInfo,
         };
         storeCache.set(id, store);
+        // 成员变更事件先落库 (它们是"谁能写"的凭证; 带 kind 字段, 不会被当成聊天消息)
+        for (const entry of membershipEntries)
+            await store.add(entry);
         // 欢迎消息 (群主自我介绍)
-        const from = opts?.from || 'group-owner';
+        const from = opts?.from || gateInfo.ownerDid || 'group-owner';
         await store.add({ from, text: opts?.hello || `📢 群主创建了群「${groupName}」, 分享链接邀请成员加入`, ts: Date.now() });
         const groups = await loadGroups();
         await saveGroups([...groups.filter((g) => g.id !== id), info]);
@@ -298,6 +348,91 @@ export async function groupMembers(groupId) {
     const msgs = await groupMessages(groupId, 500);
     return Array.from(new Set(msgs.map((m) => m.from)));
 }
+// ============ 2026-10-01 (P1): DID 门控 —— 成员事件读写 / 白名单自检 ============
+/** 读群 store 的**原始条目** (含非消息条目, 如成员事件)。打不开 → 抛 (与 groupMessages 同规矩) */
+async function allRawEntries(groupId) {
+    let store = storeCache.get(groupId) ?? null;
+    if (!store) {
+        const groups = await loadGroups();
+        const g = groups.find((x) => x.id === groupId);
+        if (!g)
+            return [];
+        store = await openGroupStore(g.address);
+        if (!store)
+            throw new GroupStoreUnreachableError(groupId, g.address, openFailures.get(groupId));
+    }
+    return store.all();
+}
+/**
+ * 读本群的全部成员变更事件, 并**逐条重新验签**。
+ * 没验过的事件**不算数** (进 rejected, 不进 accepted) —— 别把"库里有一条"当成"它是真的"。
+ */
+export async function groupMembershipEvents(groupId) {
+    const raw = await allRawEntries(groupId);
+    const accepted = [];
+    const rejected = [];
+    for (const e of raw) {
+        const v = e.value;
+        if (!v || typeof v !== 'object' || v.kind !== GROUP_MEMBERSHIP_KIND)
+            continue;
+        const ev = v.event;
+        const r = await verifyMembershipEvent(ev);
+        if (r.ok)
+            accepted.push(ev);
+        else {
+            rejected.push({ event: ev, ok: false, reason: r.checks.filter((c) => !c.ok).map((c) => `${c.name}: ${c.detail}`).join(' | ') });
+        }
+    }
+    accepted.sort((a, b) => a.ts - b.ts);
+    return { accepted, rejected };
+}
+/**
+ * 落一条成员变更事件 (验签不过 → 拒写, 返回 error)。
+ * 注意: 能写这个 store 本身就要求调用者在白名单里 —— 本函数不代替 ACL, 只是入口处的形状/签名闸门。
+ */
+export async function recordMembershipEvent(groupId, event) {
+    const v = await verifyMembershipEvent(event);
+    if (!v.ok) {
+        return { ok: false, error: `成员事件验签不过: ${v.checks.filter((c) => !c.ok).map((c) => c.name).join(',')}` };
+    }
+    let store = storeCache.get(groupId) ?? null;
+    if (!store) {
+        const groups = await loadGroups();
+        const g = groups.find((x) => x.id === groupId);
+        if (!g)
+            return { ok: false, error: '群组不存在 (先 joinGroup/createGroup)' };
+        store = await openGroupStore(g.address);
+        if (!store)
+            return { ok: false, error: `群组 store 不可达: ${unreachableReason(openFailures.get(groupId))}` };
+    }
+    try {
+        await store.add(membershipEntryOf(event));
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: `写成员事件失败: ${String(e?.message || e).slice(0, 160)}` };
+    }
+}
+/**
+ * 从本群库里的成员事件**派生**写白名单 (群主 + add − remove)。
+ * 这就是"当前这条群地址的 ACL 应该长什么样"的**可核验答案**:
+ * 拿它去和 manifest 里真正的白名单比对 (或拿它去重建一个新 store)。
+ */
+export async function groupWriteList(groupId, owner) {
+    const groups = await loadGroups();
+    const g = groups.find((x) => x.id === groupId);
+    const raw = await allRawEntries(groupId);
+    const events = [];
+    for (const e of raw) {
+        const v = e.value;
+        if (v && typeof v === 'object' && v.kind === GROUP_MEMBERSHIP_KIND && v.event)
+            events.push(v.event);
+    }
+    const applied = await applyMembershipEvents({ owner, events });
+    const gated = !!(g?.gated || applied.accepted.length > 0);
+    // 非门控的老群 (write:['*']) 派生不出成员白名单 —— 如实标 gated:false, 不硬凑
+    return { write: applied.write, members: applied.members, rejectedCount: applied.rejected.length, gated };
+}
 /** 发送群消息 (广播给所有成员) */
 export async function groupSend(groupId, text, from, opts) {
     const msg = String(text || '').trim();

package/dist/agents/iteration-budget.js

@@ -0,0 +1,64 @@
+/**
+ * 这些工具"一次调用可顶多次操作" ⇒ 用它换来的迭代要**退还**。
+ * 加新工具时问自己: 它能不能在一次调用里做完 N 件事? 能 ⇒ 加进来。
+ */
+export const REFUNDABLE_TOOLS = new Set(['execute_code']);
+export function capsFromEnv(env = process.env) {
+    const num = (v, d) => {
+        const n = Number(v);
+        return Number.isFinite(n) && n > 0 ? Math.floor(n) : d;
+    };
+    return {
+        parent: num(env.BOLLOON_MAX_ITERATIONS, 500),
+        subagent: num(env.BOLLOON_SUBAGENT_MAX_ITERATIONS, 50),
+    };
+}
+/** 警告比例: 严格 (0,1) 的有限数; 否则 null = 关闭该功能 (与"只搬约束"一致) */
+export function normalizeWarnRatio(v) {
+    if (v === null || v === undefined || typeof v === 'boolean')
+        return null;
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 && n < 1 ? n : null;
+}
+export function shouldWarn(used, maxTotal, ratio = 0.8) {
+    const r = normalizeWarnRatio(ratio);
+    if (r === null || !Number.isFinite(used) || !Number.isFinite(maxTotal) || maxTotal <= 0)
+        return false;
+    return used / maxTotal >= r;
+}
+/** 该工具的调用是否值得退还一次迭代 */
+export function isRefundableTool(toolName) {
+    return REFUNDABLE_TOOLS.has(String(toolName ?? '').trim());
+}
+export class IterationBudget {
+    maxTotal;
+    _used = 0;
+    _refunded = 0;
+    constructor(maxTotal) {
+        this.maxTotal = Number.isFinite(maxTotal) && maxTotal > 0 ? Math.floor(maxTotal) : Number.POSITIVE_INFINITY;
+    }
+    /** 尝试消费一次; 返回 false = 预算用尽 (调用方据此收尾) */
+    consume() {
+        if (this._used >= this.maxTotal)
+            return false;
+        this._used += 1;
+        return true;
+    }
+    /** 归还一次 (批处理工具调用后) —— 这是"奖励批处理"的落点 */
+    refund() {
+        if (this._used > 0) {
+            this._used -= 1;
+            this._refunded += 1;
+        }
+    }
+    get used() { return this._used; }
+    get refunded() { return this._refunded; }
+    get remaining() { return Math.max(0, this.maxTotal - this._used); }
+    get depleted() { return this._used >= this.maxTotal; }
+    warn(ratio = 0.8) { return shouldWarn(this._used, this.maxTotal, ratio); }
+    /** 供 UI/日志: `已用/上限 (退还 N 次)` */
+    describe() {
+        const cap = Number.isFinite(this.maxTotal) ? String(this.maxTotal) : '∞';
+        return `${this._used}/${cap}${this._refunded ? ` (退还 ${this._refunded} 次)` : ''}`;
+    }
+}