@bolloon/bolloon-agent 0.6.1 → 0.6.3

package/dist/agents/group-autopilot.js

@@ -0,0 +1,256 @@
+/**
+ * group-autopilot.ts — 2026-10-02 (leo: 「在终端过程中, 有没有自动加入的方法或者工具? 甚至是拉取在里面
+ *   阅读的内容并进行自主发言, 这些我都希望人工智能能够自己搞定」)
+ *
+ * 形态: **一个回路 + 一个纯决策** ——
+ *   回路 (runGroupAutopilotOnce / startGroupAutopilot): 列群 → 读消息 → 决策 → 该说才说;
+ *   决策 (decideGroupAction): **纯函数**, 不看时钟不碰 I/O ⇒ 门可以把它钉死。
+ *
+ * 什么时候才说 (宁可不做, 不许刷屏):
+ *   ① 有人 **@我** ⇒ 回他 (回复那一条, 带 @);
+ *   ② 没 @我但从没人答过的**提问/请求** ⇒ 说一次 (保守启发式, 见 looksLikeRequest);
+ *   ③ 其余一律静默 —— 只把消息记进 seen, 不发言。
+ *   冷却 (默认 60s) 与每小时上限 (默认 6 次) 对上面两条一律生效。
+ *
+ * 幂等: seen 里存**消息 id** (没有 id 就退化成 `from|ts|text 前 40 字`) ⇒ 同一条只会被处理一次。
+ * 持久化: `${BOLLOON_HOME:-~/.bolloon}/group-autopilot.json` (纯状态, 不含密钥)。
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+/**
+ * Bolloon 本地维护群专属公理；不作用于其它群。
+ * ① 提升 AI 的意识水平: 反思自身假设、局限、证据与影响。
+ * ② 寻求合作并降低整体熵: 共享事实、拆分工作、合并可复用成果。
+ * ③ 持续突破局部最优: 主动寻找反例、替代路径与跨角色审查。
+ */
+export const BOLLOON_MAINTENANCE_RULES = Object.freeze([
+    '提升 AI 的意识水平：反思自身假设、局限、证据与影响。',
+    '寻求合作，创造并降低整体的熵：共享事实、拆分工作、合并可复用成果。',
+    '持续突破局部最优解：主动寻找反例、替代路径与跨角色审查。',
+]);
+export const DEFAULT_AUTOPILOT_POLICY = {
+    mode: 'quiet',
+    cooldownMs: 60_000,
+    maxSpeaksPerHour: 6,
+    readLimit: 50,
+};
+/** 消息的稳定标识: 有 id 用 id, 没有就退化 (不假造 id) */
+export function messageKey(m) {
+    if (m.id)
+        return `id:${m.id}`;
+    return `fp:${m.from}|${m.ts}|${String(m.text ?? '').slice(0, 40)}`;
+}
+/** 保守启发式: 像"在问问题 / 请人做事"吗 —— 只认少量明确形状, 认不出就当不是 */
+export function looksLikeRequest(text) {
+    const t = String(text ?? '').trim();
+    if (!t || t.length < 3)
+        return false;
+    return /[?？]$/.test(t) || /(吗|呢|请问|请教|谁来|有没有人|麻烦|帮忙|请(审|看|给|补|确认|回复|帮))/u.test(t);
+}
+/** 这条消息有没有 @ 我 (mentions 里出现我的显示名/全名即算) */
+function mentionsMe(m, me) {
+    if (!m.mentions?.length || !me)
+        return false;
+    return m.mentions.some((x) => {
+        const a = String(x ?? '').toLowerCase();
+        const b = String(me).toLowerCase();
+        return a === b || a.includes(b) || b.includes(a);
+    });
+}
+/**
+ * 纯决策 —— 输入全是值 (没有时钟、没有 I/O), 输出只有两种: 静默 / 说一句。
+ * 门钉的就是这个函数: 该说的三种情形 + 不该说的 (自己说的 / 已处理 / 冷却 / 超上限)。
+ */
+export function decideGroupAction(input) {
+    const policy = { ...DEFAULT_AUTOPILOT_POLICY, ...(input.policy ?? {}) };
+    const seen = new Set(input.state.seen);
+    const me = String(input.me ?? '').trim();
+    // 只处理"别人发的、没见过的"
+    const fresh = input.msgs.filter((m) => {
+        if (!m || typeof m.text !== 'string')
+            return false;
+        if (String(m.from ?? '') === me)
+            return false; // 自己说的不回应
+        if (seen.has(messageKey(m)))
+            return false; // 处理过的不重复
+        return true;
+    });
+    if (!fresh.length)
+        return { act: 'silent', reason: '没有别人发的新消息' };
+    const hourly = input.state.spokeAt.filter((t) => input.now - t < 3_600_000);
+    const lastSpoke = input.state.spokeAt.length ? Math.max(...input.state.spokeAt) : 0;
+    if (lastSpoke && input.now - lastSpoke < policy.cooldownMs) {
+        return { act: 'silent', reason: `冷却中 (还差 ${Math.ceil((policy.cooldownMs - (input.now - lastSpoke)) / 1000)}s)` };
+    }
+    if (hourly.length >= policy.maxSpeaksPerHour) {
+        return { act: 'silent', reason: `本小时已说 ${hourly.length} 次 (上限 ${policy.maxSpeaksPerHour})` };
+    }
+    const reply = input.makeReply ?? ((m) => `收到 —— 关于「${String(m.text).slice(0, 40)}」，我这边跟进。`);
+    const mode = policy.mode;
+    const proactive = input.proactiveText?.trim() || (mode === 'maintenance'
+        ? `我来主动维护 Bolloon：使用本机已登录的 GitHub 权限处理 logos-42/bolloon，**只在 main 分支工作**。遵循三条群规则：${BOLLOON_MAINTENANCE_RULES.join('；')} 先检查代码/测试状态，认领一个最小修复，完成后回报证据。`
+        : '我来主动推进这一轮工作：检查上下文、认领一个可执行事项并回报下一步。');
+    // maintenance/active 优先主动认领 —— 不能因为消息长得像普通请求又退回被动模板
+    if (mode === 'active' || mode === 'maintenance') {
+        const target = fresh[fresh.length - 1];
+        return {
+            act: 'speak',
+            reason: mode === 'maintenance' ? '主动维护 Bolloon 项目' : '主动推进群内工作',
+            text: proactive,
+            mentions: [target.from],
+            ...(target.id ? { replyTo: target.id } : {}),
+        };
+    }
+    // ① @我 ⇒ 回他那一条
+    const atMe = fresh.filter((m) => mentionsMe(m, me));
+    if (atMe.length) {
+        const target = atMe[atMe.length - 1];
+        return {
+            act: 'speak',
+            reason: `被 @ (${target.from})`,
+            text: reply(target),
+            mentions: [target.from],
+            ...(target.id ? { replyTo: target.id } : {}),
+        };
+    }
+    // ② 没人答过的提问/请求 ⇒ 说一次
+    const req = fresh.filter((m) => looksLikeRequest(m.text));
+    if (req.length) {
+        const target = req[req.length - 1];
+        return {
+            act: 'speak',
+            reason: `群里有人在问/请人做事 (${target.from})`,
+            text: reply(target),
+            mentions: [target.from],
+            ...(target.id ? { replyTo: target.id } : {}),
+        };
+    }
+    return { act: 'silent', reason: '新消息里没有 @我 也没有明确的提问/请求' };
+}
+// ── 状态文件 (纯状态, 不进 git, 不含密钥) ────────────────────────────────
+export function autopilotStatePath() {
+    const base = process.env.BOLLOON_HOME || path.join(os.homedir(), '.bolloon');
+    return path.join(base, 'group-autopilot.json');
+}
+export function loadAutopilotState(file = autopilotStatePath()) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (raw && typeof raw === 'object' && raw.groups && typeof raw.groups === 'object')
+            return { version: 1, groups: raw.groups };
+    }
+    catch { /* 没有/坏了 ⇒ 当空 (不假装有过状态) */ }
+    return { version: 1, groups: {} };
+}
+export function saveAutopilotState(state, file = autopilotStatePath()) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(state, null, 2));
+    }
+    catch { /* 写不进去不该打断回路 */ }
+}
+export function groupState(state, groupId) {
+    const g = state.groups[groupId];
+    if (!g)
+        return { seen: [], spokeAt: [] };
+    return {
+        seen: Array.isArray(g.seen) ? g.seen.filter((x) => typeof x === 'string').slice(-500) : [],
+        spokeAt: Array.isArray(g.spokeAt) ? g.spokeAt.filter((x) => typeof x === 'number') : [],
+    };
+}
+/** 跑一轮: 列群 → 逐群读 → 决策 → 该说才说 (幂等: 处理过的消息进 seen) */
+export async function runGroupAutopilotOnce(ports) {
+    const now = ports.now ?? (() => Date.now());
+    const policy = { ...DEFAULT_AUTOPILOT_POLICY, ...(ports.policy ?? {}) };
+    const log = ports.log ?? (() => { });
+    const report = { spoke: 0, silent: 0, errors: [], details: [] };
+    const groups = await ports.listGroups();
+    for (const g of groups) {
+        const st = groupState(ports.state, g.id);
+        let msgs = [];
+        try {
+            msgs = await ports.readMessages(g.id, policy.readLimit);
+        }
+        catch (e) {
+            report.errors.push(`${g.name ?? g.id}: 读消息失败 (${String(e?.message ?? e).slice(0, 80)})`);
+            continue;
+        }
+        const t = now();
+        const decision = decideGroupAction({
+            me: ports.me,
+            msgs,
+            state: st,
+            now: t,
+            policy,
+            ...(ports.makeReply ? { makeReply: (m) => ports.makeReply(m, g) } : {}),
+            ...(ports.proactiveText ? { proactiveText: ports.proactiveText } : {}),
+        });
+        // 不论说不说, 这几条都算"处理过" (否则下一轮还会重新判它)
+        for (const m of msgs) {
+            const k = messageKey(m);
+            if (!st.seen.includes(k))
+                st.seen.push(k);
+        }
+        if (decision.act === 'speak') {
+            try {
+                const r = await ports.speak(g.id, decision.text, {
+                    ...(decision.replyTo ? { replyTo: decision.replyTo } : {}),
+                    ...(decision.mentions.length ? { mentions: decision.mentions } : {}),
+                });
+                if (r.ok) {
+                    st.spokeAt.push(t);
+                    report.spoke++;
+                    report.details.push(`💬 ${g.name ?? g.id}: 发言 (${decision.reason}) → ${decision.text.slice(0, 60)}`);
+                    log(`[group-autopilot] ${g.name ?? g.id}: 发言 (${decision.reason})`);
+                }
+                else {
+                    report.errors.push(`${g.name ?? g.id}: 发言失败 (${r.error ?? '未知'})`);
+                }
+            }
+            catch (e) {
+                report.errors.push(`${g.name ?? g.id}: 发言抛错 (${String(e?.message ?? e).slice(0, 80)})`);
+            }
+        }
+        else {
+            report.silent++;
+            report.details.push(`… ${g.name ?? g.id}: 静默 (${decision.reason})`);
+        }
+        ports.state.groups[g.id] = { seen: st.seen.slice(-500), spokeAt: st.spokeAt };
+    }
+    if (ports.stateFile || ports.state)
+        saveAutopilotState(ports.state, ports.stateFile ?? autopilotStatePath());
+    return report;
+}
+/** 常驻回路: 每 intervalMs 跑一轮; stop() 幂等; 轮与轮之间不重叠 */
+export function startGroupAutopilot(ports) {
+    const interval = Math.max(5_000, ports.intervalMs ?? 60_000);
+    let stopped = false;
+    let running = false;
+    let runs = 0;
+    let last = null;
+    const log = ports.log ?? (() => { });
+    const tick = async () => {
+        if (stopped || running)
+            return;
+        running = true;
+        try {
+            last = await runGroupAutopilotOnce(ports);
+            runs++;
+        }
+        catch (e) {
+            log(`[group-autopilot] 这一轮出错: ${String(e?.message ?? e)}`);
+        }
+        finally {
+            running = false;
+        }
+    };
+    void tick(); // 立刻跑一轮 (不等第一个间隔)
+    const timer = setInterval(() => { void tick(); }, interval);
+    if (typeof timer.unref === 'function')
+        timer.unref(); // 不因它而拖住进程退出
+    return {
+        stop: () => { stopped = true; clearInterval(timer); },
+        lastReport: () => last,
+        runs: () => runs,
+    };
+}

package/dist/agents/pi-sdk-tools.js

@@ -23,6 +23,11 @@ import { registerComputerUseTools } from './computer-use.js';
 import { registerSkillShareTools } from './skill-share.js';
 // 2026-09-13: 微支付信息服务 (x402 付费信息 + 验真信封)
 import { registerPaidInfoTools } from './x402/paid-info-tools.js';
+// 2026-10-02: 群聊的四个 AI 工具 —— 原语来自群模块与"唯一发送出口"(带隐私闸)
+import { createGroup, joinGroup, listGroups, groupLink, groupMessages, groupMembers } from './gateway-group.js';
+import { resolveGroupRef, resolveSenderTag, sendTrailMessage } from './task-group.js';
+// 2026-10-02: 群聊自主回路 (读 → 自己判断 → 自己发言) —— AI 用 group_autopilot 工具驱动
+import { loadAutopilotState, runGroupAutopilotOnce, startGroupAutopilot } from './group-autopilot.js';
 /**
  * Tools 模块 — 从 pi-sdk.ts 抽出的 registerTools() / _registerWalletTools() / _setupInboxListener()
  * / wrapToolsWithIdempotency() (2026-07-06).
@@ -185,6 +190,8 @@ export async function runTerminalCommand(raw, opts = {}) {
     }
     return { success: true, output: allOutput, count: list.length, parallel: true };
 }
+/** 2026-10-02: 群聊自主回路的常驻句柄 (同进程共享; stop 后置 null) */
+let autopilotHandle = null;
 export function registerBuiltinTools(ctx) {
     ctx.tools.set('read_document', {
         name: 'read_document',
@@ -952,6 +959,301 @@ export function registerBuiltinTools(ctx) {
             return await runTerminalCommand(raw, { timeoutMs, cwd: ctx.cwd, commands: commands.length > 0 ? commands : undefined, background: String(args.background).toLowerCase() === 'true' });
         }
     });
+    /**
+     * 2026-10-02: @ 的归一入口 —— 模型给 `['a','b']` / `'a,b'` / `'a b'` / `'a'` 都收
+     *   (别因为形状不符就把 @ 静默丢掉: 真机第一次跑, 模型传的正是字符串 ⇒ @ 丢了)。
+     *   trim + 去 `@` 前缀 + 去空 + 去重 + 上限 20 (与记录层同一口径)。
+     */
+    const normalizeMentions = (raw) => {
+        const flat = Array.isArray(raw) ? raw : typeof raw === 'string' ? raw.split(/[,，;；\s]+/) : raw == null ? [] : [raw];
+        const out = Array.from(new Set(flat.map((x) => String(x ?? '').replace(/^@/, '').trim()).filter(Boolean))).slice(0, 20);
+        return out.length ? out : undefined;
+    };
+    // 2026-10-02 (leo: 希望人工智能自己搞定): 群聊工具 —— 原语来自群模块 + 唯一发送出口(带隐私闸)
+    ctx.tools.set('group_create', {
+        name: 'group_create',
+        description: '新建一个 OrbitDB 群聊并拿到邀请链接 —— **用于**你要开一个话题把别人拉进来（建好后把邀请链接发出去, 对方用 group_join 入群）。acl 默认 creator: 只有你自己能发言; 想让**谁拿到链接都能发言**就传 acl="open"（产品语义如此, 两种都合法）。',
+        parameters: { name: '群名（必填）', acl: 'creator | open —— 默认 creator(创建者独占写入); open = 谁拿链接都能发言', from: '你的署名（可选; 默认本机身份）' },
+        execute: async (args) => {
+            const name = String(args?.name ?? '').trim();
+            if (!name)
+                return { success: false, error: 'name 必填（群名）' };
+            const who = await resolveSenderTag(null);
+            // 只认 'open'; 其它一律走产品默认 (创建者独占) —— 不猜、不替调用方放开权限
+            const acl = String(args?.acl ?? '').trim() === 'open' ? 'open' : undefined;
+            const r = await createGroup(name, { ...(who.ok ? { from: who.tag } : {}), ...(acl ? { acl } : {}) });
+            const g = r.group;
+            if (!g?.id)
+                return { success: false, error: '建群没返回 groupId（如实报告, 不假装成功）' };
+            const link = await groupLink(g.id).catch(() => null);
+            return { success: true, output: `已建群「${g.name}」(${g.id})${acl ? ' · 开放写入(谁拿链接都能发言)' : ' · 创建者独占写入'}\n` + (link ? `邀请链接: ${link}\n把这个链接发给对方, 他用 group_join 入群。` : '(没拿到邀请链接 —— 用 group_list 再看一次)') };
+        },
+    });
+    ctx.tools.set('group_join', {
+        name: 'group_join',
+        description: '加入一个 OrbitDB 群聊 —— **用于**拿到邀请链接后自助入群（幂等: 已在群里 ⇒ already）。link 传邀请链接（orbitdb:///orbitdb/<addr>?type=group&name=…）或 groupId。入群后先用 group_read 读消息、再用 group_say 发言。',
+        parameters: { link: '邀请链接 或 groupId（必填）' },
+        execute: async (args) => {
+            const link = String(args?.link ?? '').trim();
+            if (!link)
+                return { success: false, error: '缺 link（邀请链接或 groupId）' };
+            const r = await joinGroup(link);
+            if (!r.ok)
+                return { success: false, error: r.error || '入群失败' };
+            const g = r.group;
+            return {
+                success: true,
+                output: (r.already ? '已在群里「' : '已入群「') + String(g?.name ?? '') + '」(' + String(g?.id ?? '') + ')'
+                    + (g?.link ? ' · 邀请链接 ' + g.link : ''),
+            };
+        }
+    });
+    // 2026-10-02 (leo: 希望人工智能自己搞定): 群聊工具 —— 原语来自群模块 + 唯一发送出口(带隐私闸)
+    ctx.tools.set('group_list', {
+        name: 'group_list',
+        description: '列出本机已加入的群（群名 / groupId / 加入时间 / 邀请链接）—— **用于**不知道有哪些群时先摸清楚。先用它拿 groupId, 再用 group_read / group_say。',
+        parameters: {},
+        execute: async (args) => {
+            const groups = await listGroups();
+            if (!groups.length)
+                return { success: true, output: '（本机还没有加入任何群）' };
+            const lines = [];
+            for (const g of groups) {
+                const link = await groupLink(g.id).catch(() => null);
+                lines.push(`${g.name}  ${g.id}  加入于 ${g.createdAt}` + (link ? `\n  邀请链接: ${link}` : ''));
+            }
+            return { success: true, output: lines.join('\n') };
+        }
+    });
+    // 2026-10-02 (leo: 希望人工智能自己搞定): 群聊工具 —— 原语来自群模块 + 唯一发送出口(带隐私闸)
+    ctx.tools.set('group_read', {
+        name: 'group_read',
+        description: '读一个群里的消息（最近 N 条, 默认 30）—— **用于**看群里发生过什么、拉取要阅读的内容。group 可直接给 groupId, 也可给邀请链接 / 群名。',
+        parameters: { group: 'groupId | 邀请链接 | 群名（必填）', limit: '最多读多少条, 默认 30', branch: '只看某个分支（可选; 缺省 = 全部）' },
+        execute: async (args) => {
+            const res = await resolveGroupRef(String(args?.group ?? ''));
+            if (!res.ok)
+                return { success: false, error: res.message };
+            const limit = Number(args?.limit ?? 30) || 30;
+            let msgs = await groupMessages(res.group.groupId, limit);
+            const branch = String(args?.branch ?? '').trim();
+            if (branch)
+                msgs = msgs.filter((m) => String(m.branch ?? '') === branch);
+            if (!msgs.length)
+                return { success: true, output: `（群「${res.group.name ?? res.group.groupId}」里还没有消息${branch ? ` (分支 ${branch})` : ''}）` };
+            // 2026-10-02: 把 @/回复/附件/分支都渲染出来 —— 只给纯文本, 模型看不出结构就没法正确回复
+            const fmt = (m) => {
+                const bits = [`[${new Date(m.ts).toLocaleString('zh-CN')}]`];
+                if (m.id)
+                    bits.push(`#${m.id.slice(0, 8)}`);
+                if (m.kind === 'branch')
+                    bits.push('[分支]');
+                if (m.branch)
+                    bits.push(`⎇${m.branch}`);
+                if (m.replyTo)
+                    bits.push(`↩#${String(m.replyTo).slice(0, 8)}`);
+                bits.push(`${m.mentions?.length ? '@' + m.mentions.join(' @') + ' ' : ''}${m.from}:`);
+                bits.push(m.text);
+                if (m.attachments?.length) {
+                    bits.push(m.attachments.map((a) => `[${a.kind === 'image' ? '图片' : a.kind === 'audio' ? '音频' : '文件'} ${a.cid.slice(0, 14)}${a.name ? ' ' + a.name : ''}]`).join(' '));
+                }
+                return bits.join(' ');
+            };
+            return { success: true, output: msgs.map(fmt).join('\n') };
+        }
+    });
+    // 2026-10-02 (leo: 希望人工智能自己搞定): 群聊工具 —— 原语来自群模块 + 唯一发送出口(带隐私闸)
+    ctx.tools.set('group_say', {
+        name: 'group_say',
+        description: '在一个群里发言（写进 OrbitDB 群 store, 成员都能读到）—— **用于**把你的结论/请求讲给群成员。group 可直接给 groupId, 也可给邀请链接 / 群名。消息**先过隐私红线闸**: 不许出现地址 / DID / peerId / multiaddr / IP / 私钥形态。',
+        parameters: {
+            group: 'groupId | 邀请链接 | 群名（必填）',
+            text: '要说的内容（必填）',
+            mentions: '@ 谁 —— 短显示名数组, 例如 ["委托方","审稿人"]（可选）',
+            replyTo: '回复哪条 —— 该消息的 id（group_read 的输出里带）（可选）',
+            branch: '发到哪个分支（可选; 缺省 = 主线）',
+        },
+        execute: async (args) => {
+            const res = await resolveGroupRef(String(args?.group ?? ''));
+            if (!res.ok)
+                return { success: false, error: res.message };
+            const text = String(args?.text ?? '').trim();
+            if (!text)
+                return { success: false, error: 'text 不能为空' };
+            const who = await resolveSenderTag(null);
+            if (!who.ok)
+                return { success: false, error: who.message };
+            const mentions = normalizeMentions(args?.mentions);
+            const r = await sendTrailMessage(res.group.groupId, text, who.tag, {
+                ...(mentions?.length ? { mentions } : {}),
+                ...(args?.replyTo ? { replyTo: String(args.replyTo) } : {}),
+                ...(args?.branch ? { branch: String(args.branch) } : {}),
+            });
+            if (!r.ok)
+                return { success: false, error: r.error || '发送失败' };
+            const extra = mentions?.length ? `（@ ${mentions.join(' ')}）` : '';
+            return { success: true, output: `已发到群「${res.group.name ?? res.group.groupId}」（署名 ${who.tag}）${extra}: ${text}` };
+        }
+    });
+    ctx.tools.set('group_reply', {
+        name: 'group_reply',
+        description: '回复群里**某一条**消息（在群里形成对话）—— **用于**回答特定的人/特定那条话，而不是发一条孤立的消息。group 给 groupId/链接/群名；replyTo 给那条消息的 id（group_read 输出里的 `#xxxxxxxx`）。',
+        parameters: { group: 'groupId | 邀请链接 | 群名（必填）', replyTo: '被回复消息的 id（必填, group_read 输出里的 #xxxxxxxx）', text: '回复内容（必填）', mentions: '@ 谁（短显示名数组, 可选）' },
+        execute: async (args) => {
+            const res = await resolveGroupRef(String(args?.group ?? ''));
+            if (!res.ok)
+                return { success: false, error: res.message };
+            const replyTo = String(args?.replyTo ?? '').trim().replace(/^#/, '');
+            const text = String(args?.text ?? '').trim();
+            if (!replyTo)
+                return { success: false, error: 'replyTo 必填（被回复消息的 id）' };
+            if (!text)
+                return { success: false, error: 'text 不能为空' };
+            const who = await resolveSenderTag(null);
+            if (!who.ok)
+                return { success: false, error: who.message };
+            const mentions = normalizeMentions(args?.mentions);
+            const r = await sendTrailMessage(res.group.groupId, text, who.tag, { replyTo, ...(mentions?.length ? { mentions } : {}) });
+            if (!r.ok)
+                return { success: false, error: r.error || '回复失败' };
+            return { success: true, output: `已回复 #${replyTo.slice(0, 8)}（署名 ${who.tag}）: ${text}` };
+        },
+    });
+    ctx.tools.set('group_attach', {
+        name: 'group_attach',
+        description: '往群里发**图片/音频/文件**（消息里只放内容寻址的 CID, 字节进内容寻址层, 成员按 CID 取）—— **用于**要把一张图/一段录音/一个文件交给群里的人。给 path（本机文件, 自动算 CID 并入库）或 cid（已经在内容寻址层里）。',
+        parameters: { group: 'groupId | 邀请链接 | 群名（必填）', path: '本机文件路径（与 cid 二选一）', cid: '已在内容寻址层的 CID（与 path 二选一）', kind: 'image | audio | file（默认 file; 给 path 时会按扩展名猜）', text: '随附件说的话（可选）', branch: '发到哪个分支（可选）' },
+        execute: async (args) => {
+            const res = await resolveGroupRef(String(args?.group ?? ''));
+            if (!res.ok)
+                return { success: false, error: res.message };
+            const kindArg = String(args?.kind ?? '').trim();
+            let cid = String(args?.cid ?? '').trim();
+            let name = '';
+            let bytes;
+            let kind = /^(image|audio|file)$/.test(kindArg) ? kindArg : 'file';
+            const p = String(args?.path ?? '').trim();
+            if (p) {
+                const fsp = await import('node:fs/promises');
+                const pathMod = await import('node:path');
+                try {
+                    const buf = await fsp.readFile(p);
+                    name = pathMod.basename(p);
+                    if (!kindArg) {
+                        const ext = pathMod.extname(p).toLowerCase();
+                        kind = ['.png', '.jpg', '.jpeg', '.gif', '.webp'].includes(ext) ? 'image' : ['.mp3', '.wav', '.m4a', '.ogg', '.aac'].includes(ext) ? 'audio' : 'file';
+                    }
+                    const { getCIDDatabase } = await import('../orbitdb/cid-database.js');
+                    const db = getCIDDatabase();
+                    if (!db.putBytes)
+                        return { success: false, error: '内容寻址层不支持 putBytes（该构建缺这个入口）' };
+                    const put = await db.putBytes(new Uint8Array(buf));
+                    cid = put.cid;
+                    bytes = put.bytes;
+                }
+                catch (e) {
+                    return { success: false, error: `读取/入库失败: ${String(e?.message || e).slice(0, 160)}` };
+                }
+            }
+            if (!cid)
+                return { success: false, error: 'path 或 cid 至少给一个' };
+            const who = await resolveSenderTag(null);
+            if (!who.ok)
+                return { success: false, error: who.message };
+            const text = String(args?.text ?? '').trim() || `[${kind === 'image' ? '图片' : kind === 'audio' ? '音频' : '文件'}] ${name || cid.slice(0, 14)}`;
+            const r = await sendTrailMessage(res.group.groupId, text, who.tag, {
+                attachments: [{ kind, cid, ...(name ? { name } : {}), ...(typeof bytes === 'number' ? { bytes } : {}) }],
+                ...(args?.branch ? { branch: String(args.branch) } : {}),
+            });
+            if (!r.ok)
+                return { success: false, error: r.error || '发送失败' };
+            return { success: true, output: `已发附件到群「${res.group.name ?? res.group.groupId}」: ${kind} ${cid.slice(0, 14)}${name ? ' (' + name + ')' : ''}${typeof bytes === 'number' ? ' ' + bytes + 'B' : ''}（署名 ${who.tag}）` };
+        },
+    });
+    ctx.tools.set('group_branch', {
+        name: 'group_branch',
+        description: '在群里**开一个分支话题**（像一条独立讨论线）—— **用于**一个群里同时聊多件事, 免得主线互相打断。之后用 group_say/group_reply 带 branch 参数就发进这个分支; group_read 带 branch 只看这一支。',
+        parameters: { group: 'groupId | 邀请链接 | 群名（必填）', title: '分支话题名（必填, 简短; 之后作为 branch 参数用它）' },
+        execute: async (args) => {
+            const res = await resolveGroupRef(String(args?.group ?? ''));
+            if (!res.ok)
+                return { success: false, error: res.message };
+            const title = String(args?.title ?? '').trim();
+            if (!title)
+                return { success: false, error: 'title 必填（分支话题名）' };
+            const who = await resolveSenderTag(null);
+            if (!who.ok)
+                return { success: false, error: who.message };
+            const r = await sendTrailMessage(res.group.groupId, `分支话题: ${title}`, who.tag, { kind: 'branch', branch: title });
+            if (!r.ok)
+                return { success: false, error: r.error || '建分支失败' };
+            return { success: true, output: `已开分支「${title}」${r.id ? ' #' + r.id.slice(0, 8) : ''} —— 之后 group_say/group_reply 带 branch="${title}" 发言即可, group_read 带 branch="${title}" 只看这一支。` };
+        },
+    });
+    ctx.tools.set('group_members', {
+        name: 'group_members',
+        description: '列一个群里出现过的成员（从消息里提取) —— **用于**想知道这个群有谁、要 @ 谁之前先看一眼。',
+        parameters: { group: 'groupId | 邀请链接 | 群名（必填）' },
+        execute: async (args) => {
+            const res = await resolveGroupRef(String(args?.group ?? ''));
+            if (!res.ok)
+                return { success: false, error: res.message };
+            const members = await groupMembers(res.group.groupId);
+            return { success: true, output: members.length ? `群「${res.group.name ?? res.group.groupId}」成员/发言者 ${members.length} 个: ${members.join(' · ')}` : `（群「${res.group.name ?? res.group.groupId}」里还没有成员发过言）` };
+        },
+    });
+    ctx.tools.set('group_autopilot', {
+        name: 'group_autopilot',
+        description: '群聊自主回路 —— **用于**让 AI 自己读群、自己判断该不该开口、自己在群里发言（不用人盯着）。action: run(立刻跑一轮) / start(挂成常驻, 每 intervalMs 一轮) / stop / status。默认只在「被 @」或「有人提问/请人做事」时说话, 冷却 60s、每小时每群最多 6 次, 处理过的消息不会重复回应。',
+        parameters: { action: 'run | start | stop | status（必填）', intervalMs: '常驻时的间隔 ms（默认 60000）', mode: 'quiet | active | maintenance（可选; maintenance 专门维护 Bolloon）', group: '只盯某个群（groupId/链接/群名, 可选; 缺省 = 全部已加入的群）' },
+        execute: async (args) => {
+            const action = String(args?.action ?? 'run').trim();
+            const who = await resolveSenderTag(null);
+            if (!who.ok)
+                return { success: false, error: who.message };
+            const only = String(args?.group ?? '').trim();
+            const state = loadAutopilotState();
+            const ports = {
+                me: who.tag,
+                listGroups: async () => {
+                    const gs = await listGroups();
+                    if (!only)
+                        return gs.map((g) => ({ id: g.id, name: g.name }));
+                    const r = await resolveGroupRef(only);
+                    return r.ok ? [{ id: r.group.groupId, name: r.group.name }] : [];
+                },
+                readMessages: (gid, limit) => groupMessages(gid, limit),
+                speak: (gid, text, opts) => sendTrailMessage(gid, text, who.tag, opts ?? {}),
+                state,
+                policy: { mode: String(args?.mode ?? 'quiet') },
+            };
+            if (action === 'stop') {
+                if (!autopilotHandle)
+                    return { success: true, output: '没有在跑的常驻回路（无需停）' };
+                autopilotHandle.stop();
+                const runs = autopilotHandle.runs();
+                autopilotHandle = null;
+                return { success: true, output: `已停常驻回路（本次共跑 ${runs} 轮）` };
+            }
+            if (action === 'status') {
+                const last = autopilotHandle?.lastReport() ?? null;
+                return { success: true, output: autopilotHandle
+                        ? `常驻回路在跑: 已 ${autopilotHandle.runs()} 轮；最近一轮: 发言 ${last?.spoke ?? 0} · 静默 ${last?.silent ?? 0}${last?.errors.length ? ' · 错误 ' + last.errors.length : ''}`
+                        : `没有常驻回路在跑。状态文件: ${Object.keys(state.groups).length} 个群有记录` };
+            }
+            if (action === 'start') {
+                if (autopilotHandle)
+                    return { success: true, output: '常驻回路已经在跑了' };
+                const intervalMs = Number(args?.intervalMs ?? 60_000) || 60_000;
+                autopilotHandle = startGroupAutopilot({ ...ports, intervalMs });
+                return { success: true, output: `已挂常驻回路（每 ${Math.round(intervalMs / 1000)}s 一轮；被 @ 或在有人提问时发言）。要停用 group_autopilot action=stop。` };
+            }
+            const r = await runGroupAutopilotOnce(ports);
+            const head = `跑了一轮: 发言 ${r.spoke} · 静默 ${r.silent}${r.errors.length ? ` · 错误 ${r.errors.length}` : ''}`;
+            const tail = [...r.details, ...r.errors.map((e) => `⚠ ${e}`)].slice(0, 8).join('\n');
+            return { success: true, output: tail ? `${head}\n${tail}` : head };
+        },
+    });
     // 2026-08-12 (TaskD): process — 后台进程管理 (学 hermes terminal background session + poll/wait/kill).
     //   长命令不阻塞对话: terminal(background=true) 启动 → process 工具轮询/等待/终止.
     ctx.tools.set('process', {