@bolloon/bolloon-agent 0.5.3 → 0.5.5

package/dist/agents/skill-ledger.js

@@ -0,0 +1,129 @@
+/**
+ * 技能账本 + 单条回滚 + 写来源隔离 (2026-10-01, 按"账本而非闸门"的形态做)。
+ *
+ * 三件事:
+ *  ① **账本**: 每次技能变更追加一条 JSONL(前后清单 + 内容寻址备份)⇒ 可单条回滚 ✓。
+ *     放 JSONL 不放数据库: 耐久 · 可 grep · 数据库重置也不丢 ✓。
+ *  ② **单条回滚**: 按 id 还原那一次变更; **唯独回滚是 fail-closed** ✓(安全快照拿不到就拒绝回滚,
+ *     绝不"半还原"✗); 其余全部吞错只记日志(账本坏掉不该挡住干活 ✓)。
+ *  ③ **写来源隔离**: 用 AsyncLocalStorage 区分"用户点名要的写"(foreground ✓)与
+ *     "自审/复盘产生的写"(review ✓)⇒ 自审**只许治理自己造出来的技能** ✓, 用户要的归用户 ✓。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+const originStore = new AsyncLocalStorage();
+/** 在"自审"上下文里跑一段(其余一律按 foreground ✓) */
+export function runWithWriteOrigin(origin, fn) {
+    return originStore.run({ origin }, fn);
+}
+export function currentWriteOrigin() {
+    return originStore.getStore()?.origin ?? 'foreground';
+}
+export function isReviewWrite() {
+    return currentWriteOrigin() === 'review';
+}
+export function ledgerPath(home = os.homedir()) {
+    return path.join(home, '.bolloon', 'skills', '.skill-ledger.jsonl');
+}
+export function blobsDir(home = os.homedir()) {
+    return path.join(home, '.bolloon', 'skills', '.ledger-blobs');
+}
+function sha256(text) {
+    return crypto.createHash('sha256').update(text, 'utf-8').digest('hex');
+}
+/** 把内容按哈希存进 blobs(已存在则复用 ✓ 天然去重) */
+function putBlob(text, home) {
+    const h = sha256(text);
+    const p = path.join(blobsDir(home), h);
+    try {
+        if (!fs.existsSync(p)) {
+            fs.mkdirSync(path.dirname(p), { recursive: true });
+            fs.writeFileSync(p, text, { mode: 0o600 });
+        }
+    }
+    catch { /* 备份失败 ⇒ 由调用方决定是否允许这次变更(见 captureBefore) */ }
+    return h;
+}
+/** 变更前快照: 返回 beforeSha(拿不到安全快照时返回 undefined ⇒ 回滚能力缺失, 调用方须知道 ✓) */
+export function captureSkillBefore(file, home) {
+    try {
+        const text = fs.readFileSync(file, 'utf-8');
+        return { beforeSha: putBlob(text, home), bytesBefore: text.length };
+    }
+    catch {
+        return {}; // 文件不存在(新建)= 正常; 读不到 = 快照缺失
+    }
+}
+/** 追加一条账本(吞错只记日志 ✓ —— 账本坏掉不该挡住干活) */
+export function appendLedger(entry, home) {
+    const full = { id: entry.id || crypto.randomBytes(8).toString('hex'), at: entry.at ?? Date.now(), ...entry };
+    try {
+        const p = ledgerPath(home);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.appendFileSync(p, JSON.stringify(full) + '\n', { mode: 0o600 });
+    }
+    catch { /* telemetry, not a gate */ }
+    return full;
+}
+export function readLedger(home) {
+    try {
+        const raw = fs.readFileSync(ledgerPath(home), 'utf-8');
+        const out = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch { /* 坏行跳过 */ }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+/** 这个技能是不是"自审造出来的"?(决定自审有没有资格改它 ✓) */
+export function isAgentCreated(skill, home) {
+    return readLedger(home).some((e) => e.skill === skill && e.tool === 'create_skill' && e.origin === 'review');
+}
+/**
+ * 自审写前的资格检查(只读判断, 不改任何东西 ✓):
+ * 自审只许动**自己造出来**的技能 ✓; 用户点名要的归用户 ✓。
+ */
+export function reviewMayTouch(skill, home) {
+    if (!isReviewWrite())
+        return { ok: true, reason: 'foreground(用户点名要的写)' };
+    return isAgentCreated(skill, home)
+        ? { ok: true, reason: 'review(该技能由自审创建, 可治理)' }
+        : { ok: false, reason: '该技能不是自审创建的(用户点名要的归用户)⇒ 自审只记候选, 不动它' };
+}
+/**
+ * 单条回滚: 把某次变更前的快照还原回去 ✓。
+ * **fail-closed**: 快照缺失/内容哈希对不上 ⇒ 拒绝(绝不半还原 ✗)。
+ */
+export function rollbackEntry(id, home) {
+    const entry = readLedger(home).find((e) => e.id === id);
+    if (!entry)
+        return { ok: false, reason: `账本里没有 id=${id}` };
+    if (entry.tool === 'create_skill') {
+        // 创建类变更: 回滚 = 删掉那个文件(要用户明确同意 ⇒ 这里只报告, 不擅自删 ✗)
+        return { ok: false, reason: '该条是"新建技能"; 回滚等于删除文件 —— 需要你明确同意, 我不擅自删' };
+    }
+    if (!entry.beforeSha)
+        return { ok: false, reason: '该条没有变更前快照 ⇒ 拒绝回滚(fail-closed, 不做半还原)' };
+    try {
+        const blob = fs.readFileSync(path.join(blobsDir(home), entry.beforeSha), 'utf-8');
+        if (sha256(blob) !== entry.beforeSha)
+            return { ok: false, reason: '快照内容与哈希不符 ⇒ 拒绝回滚' };
+        fs.writeFileSync(entry.file, blob, { mode: 0o600 });
+        appendLedger({ origin: 'foreground', tool: 'rollback', skill: entry.skill, file: entry.file, beforeSha: entry.afterSha, afterSha: entry.beforeSha, note: `回到 ${entry.id}` }, home);
+        return { ok: true, reason: `已回滚到变更前(${entry.id})`, restored: entry.file };
+    }
+    catch (e) {
+        return { ok: false, reason: `回滚失败: ${String(e?.message || e).slice(0, 120)}` };
+    }
+}

package/dist/agents/tool-loop-guard.js

@@ -0,0 +1,303 @@
+/**
+ * tool-loop-guard.ts — 工具调用的**停滞观测与温和引导** (2026-10-01)
+ *
+ * 为什么需要它 (用户原话: 「一个简单的任务居然花这么多次工具调用」):
+ *   原先的防重只有一条「同工具连续 5 次 ⇒ 注入一条提示, 然后重置计数」。实测模型无视提示后
+ *   完全没刹车 —— 同一个 get_identity 连调 10 次 ✗; 而且**只看工具名**, 连"同工具换参数的正常
+ *   迭代"(逐文件读)也会被误判。
+ *   反过来"硬停"也不行 (用户明确否决): 那是在症状上下手, 而且会堵掉正当的重复轮询。
+ *
+ * 所以这里采用**分类 + 温和合成**的口径:
+ *   ① 工具先分类: 幂等读 / 有副作用 / 可重复轮询 (含命名约定 `_poll` / `_get_result`);
+ *   ② 判据看**签名** (工具名 + 参数的规范 JSON 的哈希), 不只看工具名 ⇒ 换参数不误伤;
+ *   ③ 命中停滞**不拒绝执行**, 而是产出一条**引导文本**追加在真结果后面 (保留模型的选择权);
+ *   ④ 完全相同的**结果**从第 2 次起用**引用 stub** 替代 (省上下文; 且明确告诉模型"与上次相同");
+ *   ⑤ 抓**循环** (A→B→A→B…, 周期 ≤4): 相邻重复计数会被交替调用清零, 只抓相邻的会漏;
+ *   ⑥ 失败宽容类工具 (跑测试红了 / grep 空 / 页面超时) 的"失败"是正常工作输出, 不参与停滞判定。
+ *
+ * 纯逻辑, 不碰 IO / 不发请求 —— 便于单测与变异验证。
+ */
+import { createHash } from 'node:crypto';
+/** 幂等只读类: 同参数重复调用不会产生新信息 (但允许换参数继续用) */
+/**
+ * **结果恒定**的工具 (2026-10-01): 同一会话内反复调, 返回**永远一样**, 且答案本身很短。
+ *   用户实测: `get_identity` 连调 3–4 次 ✗ —— 原有"引用 stub"有字符数门槛, 而它的输出才 ~90 字符
+ *   ⇒ 门槛拦不住 ⇒ 模型看不出"再问也一样"。
+ * 规矩 (工具设置层, 不做硬刹车): 从**第 2 次**完全相同的调用起, 直接把结果换成一句标准答复,
+ *   明确告诉模型"答案就在上面那次返回里, 再调不会变" ⇒ 去掉它重复调的理由。
+ */
+export const CONSTANT_RESULT_TOOLS = new Set([
+    'get_identity', 'bolloon_config_get', 'get_agent_info', 'whoami',
+]);
+export const IDEMPOTENT_TOOLS = new Set([
+    'read_file', 'list_files', 'search_files', 'get_identity', 'get_operation_logs',
+    'list_remote_channels', 'list_context_layers', 'read_context_assets', 'get_balance', 'wallet_list',
+    'web_search', 'web_extract', 'check_inbox',
+]);
+/** 有副作用类: 重复调用可能是正当的 (例如再跑一条命令), 由"同签名同结果"判定停滞 */
+export const MUTATING_TOOLS = new Set([
+    'terminal', 'shell_exec', 'execute_code', 'write_file', 'patch', 'set_persona', 'memory',
+    'todo_list', 'send_message', 'send_to_remote_channel', 'delegate_task', 'create_group', 'set_wallet',
+]);
+/** 轮询类: 同参数重复**本来就正当** (等异步任务), 永不触发相同调用提示 */
+export const REPEATABLE_TOOLS = new Set(['process_manage', 'check_task_status']);
+/** 生成/MCP 轮询工具的命名约定 (与上面同理) */
+export const REPEATABLE_SUFFIXES = ['_poll', '_get_result'];
+/** 失败的"正常输出"类: 红了/空结果/超时属于工作产出, 不参与停滞判定 */
+export const FAILURE_TOLERANT_TOOLS = new Set(['terminal', 'shell_exec', 'execute_code', 'web_search', 'web_extract']);
+/** 第几次**连续相同 (工具+参数+结果)** 触发引导 (3 = 容忍一次复核) */
+export const IDENTICAL_CALL_THRESHOLD = 3;
+/** 抓循环时最长的周期 (A→B→A→B 的周期是 2) */
+export const MAX_CYCLE_PERIOD = 4;
+/** 历史窗口: 够放最长的周期若干圈 + 余量 */
+export const CYCLE_HISTORY = 64;
+/** 结果达到这个字符数才值得用 stub 替代 (太短本来就省不了多少) */
+export const STUB_MIN_CHARS = 512;
+/**
+ * **同签名 + 同结果**的重复调用: 门槛降到这个值 (2026-10-01, 优化 #1 的收尾)。
+ * 为什么单独一条: 512 是"值不值得压缩"的门槛 ✗, 而"同一个调用又跑了一遍、结果一字不差"**本身就是浪费** ✓
+ *   —— 实测 `get_identity` 输出才 ~90 字符 ⇒ 卡在 512 门外, 于是被连调 3–4 次 ✓。
+ * 现在: 同签名重复 且 结果一致 且 ≥64 字符 ⇒ 从第 2 次起换引用 stub ✓ (少于 64 字符的本来也占不了多少上下文, 放行 ✓)。
+ */
+export const REPEAT_STUB_MIN_CHARS = 64;
+/** stub 里保留的参数预览长度 (万一压缩把原结果挤掉, 还能看出当初调了什么) */
+export const STUB_ARGS_PREVIEW_CHARS = 120;
+/** 参数的规范 JSON (键排序 + 紧凑分隔符) —— 让 {a,b} 与 {b,a} 同签名 */
+export function canonicalToolArgs(args) {
+    if (args === null || typeof args !== 'object' || Array.isArray(args))
+        return '';
+    const obj = args;
+    const keys = Object.keys(obj).sort();
+    const parts = keys.map((k) => `${JSON.stringify(k)}:${stableStringify(obj[k])}`);
+    return `{${parts.join(',')}}`;
+}
+function stableStringify(v) {
+    if (v === null || typeof v !== 'object')
+        return JSON.stringify(v) ?? 'null';
+    if (Array.isArray(v))
+        return `[${v.map(stableStringify).join(',')}]`;
+    const o = v;
+    return `{${Object.keys(o).sort().map((k) => `${JSON.stringify(k)}:${stableStringify(o[k])}`).join(',')}}`;
+}
+/** 调用签名: 不可逆 (只留哈希), 不泄漏参数原文 */
+export function toolCallSignature(toolName, args) {
+    return createHash('sha256').update(`${toolName}\u0000${canonicalToolArgs(args)}`).digest('hex').slice(0, 16);
+}
+/** 结果指纹 (判"完全相同的返回") */
+export function resultFingerprint(resultText) {
+    return createHash('sha256').update(String(resultText ?? '')).digest('hex').slice(0, 16);
+}
+export function isRepeatableTool(toolName) {
+    if (REPEATABLE_TOOLS.has(toolName))
+        return true;
+    return REPEATABLE_SUFFIXES.some((s) => toolName.endsWith(s));
+}
+/**
+ * 记录一次调用并给出观测。**纯函数式**: 调用方每次都要把上一次的 streak 传进来
+ * (见 `LoopStallState`), 这样状态归属清晰、也便于单测。
+ */
+export function observeToolCall(state, input) {
+    const ok = input.ok !== false;
+    const tolerant = FAILURE_TOLERANT_TOOLS.has(input.toolName);
+    const repeatable = isRepeatableTool(input.toolName);
+    const text = String(input.resultText ?? '');
+    const chars = input.resultChars ?? text.length;
+    // ① 轮询类: 同参数重复本就正当 ⇒ 只记录, 不出声
+    if (repeatable) {
+        state.push(input.toolName, input.args, text);
+        return { action: 'allow', code: 'allow', count: 0 };
+    }
+    const sig = toolCallSignature(input.toolName, input.args);
+    const fp = resultFingerprint(text);
+    const prev = state.last;
+    const sameAsPrev = !!prev && prev.sig === sig && prev.fp === fp;
+    // ② 连续相同 (工具 + 参数 + 结果): 每次 +1, 否则归 1
+    state.streak = sameAsPrev ? state.streak + 1 : 1;
+    state.push(input.toolName, input.args, text);
+    // ③ 失败宽容类工具的失败不参与停滞判定 (红测试/空 grep 是产出, 不是卡住)
+    if (!ok && tolerant) {
+        return { action: 'allow', code: 'allow', count: state.streak };
+    }
+    // ③.5 恒定结果工具 (get_identity 这类): 从第 2 次起换标准答复 —— 不管结果长短
+    if (sameAsPrev && CONSTANT_RESULT_TOOLS.has(input.toolName) && ok) {
+        return {
+            action: 'allow',
+            code: 'allow',
+            count: state.streak,
+            stub: `[已答] ${input.toolName} 的结果在本次会话内**恒定不变**(它读的是固定身份/配置, 不是活数据)。` +
+                `上面那一次返回就是答案, 直接用它作答即可; 再调一次只会得到同样的内容。` +
+                `若确实需要变化, 请改用写类工具(如 set_persona / 相应 update 工具)。`,
+        };
+    }
+    // ④ 结果引用 stub: 从**第 2 次**完全相同的返回起 (够长才替代; 失败永不替代)
+    let stub;
+    // 2026-10-01 (优化 #1 收尾): 同签名重复 + 结果一字不差 ⇒ 用更低门槛 (重复本身就是浪费, 不管长短)
+    const repeatFloor = input.sameSignatureBefore ? REPEAT_STUB_MIN_CHARS : STUB_MIN_CHARS;
+    if (ok && input.seenResultBefore && chars >= repeatFloor) {
+        stub = `[结果引用] 与本次会话中此前一次 ${input.toolName} 的返回**逐字相同** (${chars} 字符, 已折叠)。`
+            + `参数预览: ${canonicalToolArgs(input.args).slice(0, STUB_ARGS_PREVIEW_CHARS)}`;
+    }
+    if (state.streak >= IDENTICAL_CALL_THRESHOLD) {
+        // ⑤ 连续相同达阈值 ⇒ 温和引导 (不拒绝执行)
+        return {
+            action: 'warn',
+            code: 'identical_call_streak',
+            count: state.streak,
+            stub,
+            notice: `[系统提示] 这是第 ${state.streak} 次**用完全相同的参数**调用 ${input.toolName}, 且返回与上次完全相同。`
+                + `重复调用不会得到新信息 —— 请换参数、换工具, 或基于已有结果直接回答。`,
+        };
+    }
+    // ⑥ 循环检测: 最近 N 次里出现了周期 ≤4 的重复串 (相邻计数会被交替调用清零, 只抓相邻必漏)
+    const cycle = detectCycle(state.history);
+    if (cycle) {
+        return {
+            action: 'warn',
+            code: 'identical_cycle',
+            count: cycle.laps,
+            stub,
+            notice: `[系统提示] 检测到最近 ${cycle.laps} 圈重复同一组 ${cycle.period} 次调用`
+                + `(以 ${input.toolName} 结尾), 参数与返回都逐字相同。请不要重复这一组 —— 换参数、换工具, 或基于已有结果直接回答。`,
+        };
+    }
+    return { action: 'allow', code: 'allow', count: state.streak, stub };
+}
+/** 每轮 ReAct 循环一份的停滞状态 */
+export class LoopStallState {
+    streak = 0;
+    last = null;
+    history = [];
+    /** 已见过的结果指纹 (用于"完全相同返回"的 stub 判定) */
+    seenResults = new Set();
+    push(toolName, args, resultText) {
+        const step = { sig: toolCallSignature(toolName, args), fp: resultFingerprint(resultText) };
+        this.last = step;
+        this.history.push(step);
+        if (this.history.length > CYCLE_HISTORY)
+            this.history.shift();
+        this.seenResults.add(step.fp);
+    }
+    /** 这个结果指纹此前是否出现过 (供 observeToolCall 的 seenResultBefore) */
+    hasSeenResult(text) {
+        return this.seenResults.has(resultFingerprint(text));
+    }
+    reset() {
+        this.streak = 0;
+        this.last = null;
+        this.history.length = 0;
+        this.seenResults.clear();
+    }
+}
+/**
+ * 找"最近若干圈完全重复"的串: 对每个候选周期 p ∈ [1, MAX_CYCLE_PERIOD],
+ * 看末尾是否由同一个 p 长度的块**重复 ≥ THRESHOLD 次**组成 (块内每个 (签名,结果指纹) 都相同)。
+ * 返回圈数与周期, 没有则 null。
+ */
+export function detectCycle(history) {
+    const h = history;
+    for (let p = 1; p <= MAX_CYCLE_PERIOD; p++) {
+        const need = p * IDENTICAL_CALL_THRESHOLD;
+        if (h.length < need)
+            continue;
+        const tail = h.slice(-need);
+        let same = true;
+        for (let i = p; i < need && same; i++) {
+            if (tail[i].sig !== tail[i % p].sig || tail[i].fp !== tail[i % p].fp)
+                same = false;
+        }
+        if (same)
+            return { period: p, laps: IDENTICAL_CALL_THRESHOLD };
+    }
+    return null;
+}
+// ───────────────────────────────────────────────────────────────────────────
+// 2026-10-01 第二轮 (继续学): 三处补上
+//   ① **无进展**是独立一轴: 幂等工具即使**换了参数**, 只要结果与上次相同 ⇒ 也是无进展
+//      (原先只抓"同参数" ⇒ 换个措辞再问一遍就绕过去了)
+//   ② **进展的定义 = 有副作用的调用成功过** (纯读再多都不算) ⇒ 用它清零失败/无进展计数
+//   ③ 升级策略**按在场与否分流**: 有人在 ⇒ 只提醒(从不阻止执行); 无人值守 ⇒ 才允许拦/停
+//      (人在场时不该替用户做决定; 但 cron/supervisor 这种无人值守的场景, 该果断收)
+// ───────────────────────────────────────────────────────────────────────────
+/** 有副作用 = 会改变世界 (文件/进程/网络/资金/记忆). 唯一判据, 供"进展"与"无进展"用 */
+export function toolMayHaveSideEffect(toolName) {
+    if (MUTATING_TOOLS.has(toolName))
+        return true;
+    if (IDEMPOTENT_TOOLS.has(toolName))
+        return false;
+    if (isRepeatableTool(toolName))
+        return false;
+    // 未登记的工具按"可能有副作用"处理 (保守: 不轻易判定"它没改变世界")
+    return true;
+}
+export const DEFAULT_THRESHOLDS = {
+    exactFailureWarnAfter: 2,
+    exactFailureBlockAfter: 5,
+    sameToolFailureWarnAfter: 3,
+    sameToolFailureHaltAfter: 8,
+    noProgressWarnAfter: 2,
+    noProgressBlockAfter: 5,
+    hardStopEnabled: false,
+};
+/** 无人值守场景 (cron / supervisor / 非交互) —— 那里才默认允许拦与停 */
+export function defaultHardStopFor(context = {}) {
+    if (typeof context.unattended === 'boolean')
+        return context.unattended;
+    const env = context.env || process.env;
+    return env.BOLLOON_UNATTENDED === '1' || env.BOLLOON_CRON === '1' || env.BOLLOON_SUPERVISOR === '1';
+}
+export function newProgressBookkeeping() {
+    return { progressClearedSignatures: new Set(), noProgress: new Map() };
+}
+/**
+ * 记一次调用结果, 维护"进展 / 无进展"两本账。
+ * - 有副作用的调用**成功** ⇒ 视为进展: 清掉该签名的失败标记 + 清掉**所有**无进展记录
+ *   (世界变了 ⇒ 之前"读了没变化"的判定作废)
+ * - 幂等工具: 结果指纹与上次相同 ⇒ 无进展 +1 (**参数变没变不影响**), 不同 ⇒ 归 1
+ */
+export function trackProgress(book, input, thresholds = DEFAULT_THRESHOLDS) {
+    const ok = input.ok !== false;
+    const sig = toolCallSignature(input.toolName, input.args);
+    const fp = resultFingerprint(String(input.resultText ?? ''));
+    if (ok && toolMayHaveSideEffect(input.toolName)) {
+        book.progressClearedSignatures.add(sig);
+        if (book.noProgress.size > 0)
+            book.noProgress.clear();
+        return { action: 'allow', code: 'allow', count: 0 };
+    }
+    if (!toolMayHaveSideEffect(input.toolName)) {
+        const prev = book.noProgress.get(input.toolName);
+        const count = prev && prev.lastResultFp === fp ? prev.count + 1 : 1;
+        book.noProgress.set(input.toolName, { lastResultFp: fp, count });
+        if (count >= thresholds.noProgressWarnAfter) {
+            return {
+                action: 'warn',
+                code: 'idempotent_no_progress',
+                count,
+                notice: `[系统提示] 连续 ${count} 次读取类调用 (${input.toolName}) 返回的都是**同一份内容**`
+                    + `(参数不同也一样) —— 世界没有变化, 再读还是它。请基于已有内容作答, 或改去查别的来源。`,
+            };
+        }
+        return { action: 'allow', code: 'allow', count };
+    }
+    return { action: 'allow', code: 'allow', count: 0 };
+}
+/**
+ * 2026-10-01 (用户: 「为什么这么慢」): 量到的事实 —— 每次 LLM 往返平均 **3338ms**, 而
+ *   `toolCalls>1`(一轮发多个工具)**只占 12/63** ✗ ⇒ 回合时长 ≈ 往返次数 × 3.3s ✓;
+ *   也就是说"慢"主要不是工具慢(工具合计仅占 4% ✗), 而是**同一轮只干一件事**、来回跑 ✓。
+ * 做法: 一轮只调了一个**只读**工具时, 在结果后附一句**带代价**的提醒(不是口号 ✓)。
+ * 只读工具才提醒(写类工具串行更安全 ✓ 不催)。
+ */
+const BATCHABLE_HINT_TOOLS = new Set([
+    'read_file', 'grep_files', 'glob_files', 'list_files', 'read_document',
+    'git_status', 'git_log', 'git_diff', 'get_identity', 'list_tools', 'list_skills',
+    'process', 'list_local_channels', 'get_balance',
+]);
+export function batchHint(toolName, toolCallsThisRound) {
+    if (toolCallsThisRound !== 1)
+        return '';
+    if (!BATCHABLE_HINT_TOOLS.has(String(toolName || '')))
+        return '';
+    return '\n⚡ 若你接下来还要查别的(或还要读别的文件), **同一轮可以一次发多个工具** —— '
+        + '每次来回约 3.3 秒, 分成多轮就是纯等待; 独立的读操作请并成一轮发。';
+}

package/dist/agents/tool-path-args.js

@@ -0,0 +1,53 @@
+/**
+ * 工具参数里的 `~` 展开 (2026-10-01)。
+ *
+ * 用户实测: 智能体调 `list_files { path: "~/.bolloon" }` ⇒ `ENOENT: scandir '~/.bolloon'` ✗。
+ * 根因: 全仓**没有任何一处**做 `~` 展开 ⇒ 模型写的 `~/x` 原样进 fs, 变成字面目录名。
+ * 修法: 在**唯一分发点** (pi-sdk.ts 的 `tool.execute(...)`) 统一展开 —— 工具设置层修一次,
+ *   而不是每个工具各打一个补丁 (那样必然漏)。只碰已知的路径类参数, 其它参数一律不动。
+ */
+import os from 'node:os';
+import path from 'node:path';
+/** 会被当成路径的参数名 (只展开这些, 别的一律不碰) */
+export const PATH_ARG_KEYS = [
+    'path', 'paths', 'dir', 'directory', 'folder', 'file', 'file_path', 'filePath',
+    'from', 'to', 'target', 'source', 'src', 'dest', 'cwd', 'workdir', 'root', 'glob_dir',
+];
+/** 只展开**开头**的 `~` (单独的 `~` 或 `~/...`); `a~b` / `~user` 不碰 */
+export function expandTilde(p, home = os.homedir()) {
+    const s = String(p ?? '');
+    if (s === '~')
+        return home;
+    if (s.startsWith('~/') || s.startsWith('~' + path.sep))
+        return path.join(home, s.slice(2));
+    return s;
+}
+/**
+ * 已知别名: `.bolloon` 指的就是数据目录 (~/.bolloon)。
+ * 2026-10-01 用户实测: 智能体写 `list_files { path: ".bolloon" }` ⇒ `ENOENT: scandir '.bolloon'` ✗
+ *   (它连 `~` 都没写, 是相对路径 ⇒ 按 cwd 解析必然不存在)。只映射**恰好的**那个别名:
+ *   `.bolloon` / `.bolloon/...`; `foo/.bolloon` 之类一律不碰 (避免误伤真的同名目录)。
+ */
+export function expandKnownAliases(p, home = os.homedir()) {
+    const s = String(p ?? '');
+    if (s === '.bolloon')
+        return path.join(home, '.bolloon');
+    if (s.startsWith('.bolloon/') || s.startsWith('.bolloon' + path.sep))
+        return path.join(home, '.bolloon', s.slice('.bolloon/'.length));
+    return s;
+}
+export function expandHomeArgs(args, home) {
+    if (!args || typeof args !== 'object')
+        return args;
+    const out = { ...args };
+    for (const key of Object.keys(out)) {
+        if (!PATH_ARG_KEYS.includes(key))
+            continue;
+        const v = out[key];
+        if (typeof v === 'string')
+            out[key] = expandKnownAliases(expandTilde(v, home), home);
+        else if (Array.isArray(v))
+            out[key] = v.map((x) => (typeof x === 'string' ? expandKnownAliases(expandTilde(x, home), home) : x));
+    }
+    return out;
+}

package/dist/agents/tool-result-gate.js

@@ -0,0 +1,50 @@
+/**
+ * 工具结果的"进上下文"闸 (2026-10-01, 优化方向 #1)。
+ *
+ * 问题: 工具结果**没有上限** ✗ 就直接进 history, 而 history **每一轮都重放** ⇒ 一条大输出会持续吃上下文。
+ * 规矩: 超上限 ⇒ 保留**头 + 尾**(中段信息密度最低) + 把**完整结果落到文件**并把路径给模型
+ *   (要看细节就 read_file ⇒ 既省上下文, 又不丢信息 ✓)。
+ * 纯函数 + 一个落盘动作; 落盘失败就退化成"只截断"(绝不因此让工具失败 ✓)。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+/** 默认上限: 8000 字符 (够放下绝大多数结果; 超了才走落文件) */
+export const DEFAULT_RESULT_MAX_CHARS = 8000;
+export function resultsDir(home = os.homedir()) {
+    return path.join(home, '.bolloon', 'logs', 'tool-results');
+}
+/**
+ * 头尾保留: head 60% / tail 25%, 留 15% 给提示语 (与出口净化的省略口径一致, 免得两套规矩)。
+ */
+export function capToolResult(text, opts = { tool: '?' }) {
+    const s = String(text ?? '');
+    const max = opts.maxChars ?? DEFAULT_RESULT_MAX_CHARS;
+    const originalChars = s.length;
+    if (max <= 0 || s.length <= max)
+        return { text: s, capped: false, originalChars };
+    const head = Math.floor(max * 0.6);
+    const tail = Math.floor(max * 0.25);
+    let spilledTo;
+    if (opts.spill !== false) {
+        try {
+            const home = opts.home || os.homedir();
+            const dir = resultsDir(home);
+            fs.mkdirSync(dir, { recursive: true });
+            const safeTool = String(opts.tool || 'tool').replace(/[^a-zA-Z0-9_.-]/g, '_').slice(0, 40);
+            const file = path.join(dir, `${Date.now()}-${safeTool}.txt`);
+            fs.writeFileSync(file, s, 'utf-8');
+            spilledTo = file;
+        }
+        catch { /* 落盘失败就只截断 */ }
+    }
+    const notice = spilledTo
+        ? `\n…[结果过长已截断: 原文 ${originalChars} 字符, 完整内容已存到 ${spilledTo} —— 要看细节用 read_file 读它]…\n`
+        : `\n…[结果过长已截断: 原文 ${originalChars} 字符]…\n`;
+    return {
+        text: `${s.slice(0, head)}${notice}${s.slice(-tail)}`,
+        capped: true,
+        spilledTo,
+        originalChars,
+    };
+}

package/dist/agents/tool-subset.js

@@ -0,0 +1,109 @@
+/**
+ * 工具集合的"注入降噪" (2026-10-01, 优化 #2 v2)。
+ *
+ * 背景: 125 个工具一次性列出 ⇒ **选择过载**(实测两次错工具: terminal 拿去造文件 ✗ / list_files 当搜索 ✗)。
+ * 但注意两个约束(实测过):
+ *   ① 清单**本来就是紧凑的**(只列 `name(params)`, 不列描述) ⇒ 省上下文的价值有限, 主要价值在**选得准**;
+ *   ② 这份清单**被缓存**(每轮重建会顶大 prompt, 还有踩 max_tokens 的历史教训) ⇒ 默认**不做**每轮动态子集。
+ * 因此两档:
+ *   · 默认档: **分组列 + 末尾一句"未列出的工具也能直接按名字调用"** ⇒ 不丢能力, 且不破坏缓存;
+ *   · 开关档 (`BOLLOON_TOOL_SUBSET=on`): 按 intent 只列相关桶 + 永远带 `list_tools` ⇒ 最省认知。
+ * 纪律: **执行/校验永远用完整注册表** ⇒ 子集只影响"列给模型看的那份", 不影响能不能调 ✓。
+ */
+/** 分类: 名字 → 桶 (机械规则, 不猜) */
+export function bucketOf(name) {
+    const n = name.toLowerCase();
+    // 注意顺序: `list_tools` 会被 ^list 抢成"读/找文件" ⇒ 元工具先判 (2026-10-01 门抓到)
+    if (/^(get_identity|set_persona|persona|identity|list_tools|bolloon_config)/.test(n))
+        return '身份/元';
+    if (/wallet|chain|token|balance|^tx|polymarket|safe_|x402|erc20|escrow|treasury/.test(n))
+        return '链上/钱包';
+    if (/^(read|list|glob|grep|search|find)/.test(n) || /file|dir|document|doc$/.test(n))
+        return '读/找文件';
+    if (/^(write|edit|mkdir|move|delete|copy|patch|truncate)/.test(n))
+        return '写/改文件';
+    if (/task|plan|todo|goal|^run|queue|operation_log/.test(n))
+        return '任务/计划';
+    if (/peer|channel|friend|send|broadcast|group|inbox|p2p|contact|message/.test(n))
+        return 'P2P/沟通';
+    if (/web|fetch|http|url|search_web/.test(n))
+        return '网络';
+    if (/agent|delegate|registry|spawn|call_/.test(n))
+        return '智能体';
+    return '其它';
+}
+/** 核心桶: 任何任务都可能用到 ⇒ 默认档全部展开 */
+export const CORE_BUCKETS = ['读/找文件', '写/改文件', '任务/计划', '身份/元'];
+/** intent 关键词 → 额外展开的桶 */
+const INTENT_BUCKETS = [
+    [/钱包|链上|转账|余额|代币|合约|多签|gas|wallet|token|chain|tx/i, '链上/钱包'],
+    [/群|频道|好友|发消息|广播|节点|点对点|channel|group|friend|peer|p2p|broadcast/i, 'P2P/沟通'],
+    [/网页|抓取|搜索|下载|链接|url|web|fetch|http/i, '网络'],
+    [/智能体|子智能体|委派|agent|delegate/i, '智能体'],
+];
+/**
+ * 生成"工具清单"文本。**只影响列出来的那份**; 调用方必须保证执行侧仍用完整注册表。
+ */
+export function renderToolList(allNames, intentText = '', opts = {}) {
+    const total = allNames.length;
+    const byBucket = new Map();
+    for (const n of allNames) {
+        const b = bucketOf(n);
+        if (!byBucket.has(b))
+            byBucket.set(b, []);
+        byBucket.get(b).push(n);
+    }
+    const per = Math.max(1, opts.perBucket ?? 14);
+    // 哪些桶要"展开列出", 哪些只给名字(折叠)
+    const expanded = new Set();
+    if (!opts.subset) {
+        for (const b of byBucket.keys())
+            expanded.add(b);
+    }
+    else {
+        for (const b of CORE_BUCKETS)
+            expanded.add(b);
+        for (const [re, b] of INTENT_BUCKETS)
+            if (re.test(intentText))
+                expanded.add(b);
+    }
+    const lines = [];
+    let shown = 0;
+    const foldedBuckets = [];
+    for (const [b, names] of byBucket) {
+        if (!expanded.has(b)) {
+            foldedBuckets.push(`${b}(${names.length})`);
+            continue;
+        }
+        const head = names.slice(0, per).sort();
+        shown += head.length;
+        const rest = names.length - head.length;
+        lines.push(`【${b}】${head.join(' ')}${rest > 0 ? ` …还有${rest}个` : ''}`);
+    }
+    const folded = foldedBuckets.length ? `未列出的分类: ${foldedBuckets.join(' ')}` : '';
+    const footer = [
+        '**没找到合适的工具 ⇒ 用 `list_tools {keyword:"…"}` 查**; 未列出的工具也**可以直接按名字调用**(名字对了就能跑)。',
+        folded,
+    ].filter(Boolean).join('\n');
+    return { text: [lines.join('\n'), footer].filter(Boolean).join('\n'), shown, total };
+}
+/**
+ * 带参数名的完整清单 (= `getToolDefinitions` 真正注入的那份)。
+ * 单独抽出来是为了**可测**: 之前这个拼装写在 pi-sdk 里(私有方法 ✗ 测不到), 于是"渲染得对不对"只能靠眼看。
+ */
+export function renderToolListWithParams(tools, intentText = '', opts = {}) {
+    const paramOf = new Map(tools.map((t) => [t.name, Object.keys(t.parameters || {}).join(',')]));
+    const grouped = renderToolList(tools.map((t) => t.name), intentText, opts);
+    const body = grouped.text.split('\n').map((line) => {
+        if (!line.startsWith('【'))
+            return line;
+        const m = /^【([^】]+)】(.*)$/.exec(line);
+        if (!m)
+            return line;
+        const [, bucket, rest] = m;
+        const more = rest.includes('…') ? rest.slice(rest.indexOf('…')) : '';
+        const names = rest.replace(/….*$/, '').trim().split(/\s+/).filter(Boolean);
+        return `【${bucket}】` + names.map((n) => `${n}(${paramOf.get(n) ?? ''})`).join(' ') + (more ? ` ${more}` : '');
+    }).join('\n');
+    return { text: body, shown: grouped.shown, total: grouped.total };
+}