@bolloon/bolloon-agent 0.2.11 → 0.2.13

package/dist/bootstrap/chat-archiver.js

@@ -0,0 +1,276 @@
+/**
+ * chat-archiver.ts — 按 peer 月度归档聊天记录 + 接 memory 摘要
+ *
+ * 设计目的 (2026-07-05):
+ *   解决"对方不在线也能看到历史"的核心问题.
+ *   sessions/cache/<channelId>.json 单文件无限增长, 超过 50MB 直接拒绝加载.
+ *
+ *   新方案:
+ *     - 每次 /message 处理后, 同时写到 3 个地方:
+ *       ① sessions/cache/<channelId>.json (原有, 最近窗口用)
+ *       ② ~/.bolloon/peers/<pk>/chat-<YYYY-MM>.md (按 peer 月度归档)
+ *       ③ ~/.bolloon/memory/<agentId>/peers/<pk>/<YYYY-MM>.summary.md (月度摘要)
+ *
+ *   触发时机:
+ *     - appendChatArchive(): 每次保存远端/本地 user + ai 消息后立即调用 (高频)
+ *     - compressMonthlyArchive(): 月底 / 90 天滚动 / 显式调用 (低频, 调 LLM 摘要)
+ *
+ *   peer 维度 而不是 channel 维度: 同一个远端节点可能跨多个 channel 协作,
+ *   按 peer 归档才能完整还原"与对方的对话历史".
+ */
+import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as peerFs from '../network/peer-fs.js';
+// ============== 路径 ==============
+const HOME = process.env.BOLLOON_HOME || path.join(os.homedir(), '.bolloon');
+export function getPeerSummaryDir(agentId, publicKey) {
+    const safeAgent = sanitizeId(agentId);
+    const safePeer = sanitizeId(publicKey);
+    return path.join(HOME, 'memory', safeAgent, 'peers', safePeer);
+}
+export function getPeerSummaryPath(agentId, publicKey, yearMonth) {
+    return path.join(getPeerSummaryDir(agentId, publicKey), `${yearMonth}.summary.md`);
+}
+export function getPeerSummaryCursorPath(agentId, publicKey, yearMonth) {
+    return path.join(getPeerSummaryDir(agentId, publicKey), `${yearMonth}.cursor`);
+}
+function sanitizeId(s) {
+    return s.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
+}
+// ============== appendChatArchive — 高频, 每次 message 都调 ==============
+/**
+ * 追加一条 chat entry 到 peer 的月度归档.
+ * 不依赖 LLM, 纯文件 IO; 失败静默不阻塞主对话.
+ */
+export async function appendChatArchive(opts) {
+    try {
+        await peerFs.appendChat(opts.publicKey, opts.entry);
+        return { ok: true, path: peerFs.getPeerChatPath(opts.publicKey) };
+    }
+    catch (err) {
+        return { ok: false, error: err?.message || String(err) };
+    }
+}
+// ============== compressMonthlyArchive — 低频, 月底/显式调 ==============
+/**
+ * 读取月度 markdown 归档, 调 LLM 摘要, append 写到 memory.
+ * 用 cursor 跟踪已摘要到第几行, 增量压缩.
+ */
+async function readArchiveLines(publicKey, yearMonth) {
+    const file = peerFs.getPeerChatPath(publicKey, yearMonth);
+    try {
+        const raw = await fs.readFile(file, 'utf-8');
+        return raw.split('\n');
+    }
+    catch {
+        return [];
+    }
+}
+async function readSummaryCursor(cursorPath) {
+    try {
+        const raw = await fs.readFile(cursorPath, 'utf-8');
+        const n = parseInt(raw.trim(), 10);
+        return Number.isFinite(n) && n >= 0 ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+async function writeSummaryCursor(cursorPath, value) {
+    await fs.mkdir(path.dirname(cursorPath), { recursive: true });
+    await fs.writeFile(cursorPath, String(value), 'utf-8');
+}
+/**
+ * 尝试调 LLM 生成月度摘要. 失败 → 抛错, 由 caller fallback 到模板.
+ */
+async function tryMonthlyLlm(systemPrompt, userPrompt) {
+    try {
+        const piAi = await import('../llm/pi-ai.js');
+        const generateText = piAi.generateText;
+        if (typeof generateText !== 'function')
+            throw new Error('generateText not exported');
+        const result = await generateText({
+            messages: [
+                { role: 'system', content: systemPrompt },
+                { role: 'user', content: userPrompt },
+            ],
+            temperature: 0.2,
+            maxTokens: 1000,
+        });
+        const text = result?.reply || result?.text || '';
+        if (typeof text !== 'string' || text.length < 20)
+            throw new Error('LLM returned too-short text');
+        return text;
+    }
+    catch (e) {
+        throw new Error(`LLM call failed: ${e?.message || String(e)}`);
+    }
+}
+/**
+ * 模板 fallback: 简单统计 user/ai 数量, 列前 5 条关键内容.
+ */
+function templateMonthlySummary(opts) {
+    const user = opts.entries.filter(e => e.msgType === 'user' || e.source === 'local' || e.source === 'remote');
+    const ai = opts.entries.filter(e => e.msgType === 'ai' || e.source?.startsWith('ai-mention'));
+    const channelSet = new Set(opts.entries.map(e => e.channelName).filter(Boolean));
+    const sampleUser = user.slice(0, 5).map(e => `  - [${e.ts}] ${e.text.slice(0, 80)}`).join('\n');
+    const sampleAi = ai.slice(0, 5).map(e => `  - [${e.ts}] ${e.text.slice(0, 80)}`).join('\n');
+    return `# 月度对话摘要 — ${opts.yearMonth} (peer ${opts.publicKey.slice(0, 12)}…)
+
+时间: ${opts.timestamp}
+对话轮次: ${opts.entries.length} (user=${user.length}, ai=${ai.length})
+涉及 channel: ${Array.from(channelSet).slice(0, 10).join(', ') || '(无)'}
+
+## 用户关键提问
+${sampleUser || '  (无)'}
+
+## AI 关键回答
+${sampleAi || '  (无)'}
+
+## 备注
+- 此摘要由模板生成 (LLM 调用失败 fallback)
+`;
+}
+/**
+ * 解析 markdown 归档为 entries (用 "### " 切分)
+ */
+function parseArchiveEntries(lines) {
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        if (lines[i].startsWith('### ')) {
+            const header = lines[i];
+            // 解析 "### 2026-07-05 10:30:45 UTC [channelName] — source"
+            const m = header.match(/^### (.+?)\s*(?:\[(.+?)\])?\s*—\s*(\S+?)(?:\s+\(.+?\))?$/);
+            if (m) {
+                const ts = m[1].replace(/\s+UTC$/, '').trim();
+                const channelName = m[2];
+                const source = m[3];
+                // 找下一段 "### " 或 "---" 之间的内容
+                let j = i + 1;
+                const bodyLines = [];
+                while (j < lines.length && !lines[j].startsWith('### ') && !lines[j].startsWith('---')) {
+                    bodyLines.push(lines[j]);
+                    j++;
+                }
+                const text = bodyLines.join('\n').trim();
+                out.push({
+                    startLine: i,
+                    entry: {
+                        ts: ts.includes('T') ? ts : ts.replace(' ', 'T') + 'Z',
+                        source,
+                        channelName,
+                        text,
+                    }
+                });
+                i = j;
+                continue;
+            }
+        }
+        i++;
+    }
+    return out;
+}
+/**
+ * 主入口: 压缩月度归档到 memory.
+ */
+export async function compressMonthlyArchive(opts) {
+    const agentId = sanitizeId(opts.agentId);
+    const publicKey = opts.publicKey;
+    const yearMonth = opts.yearMonth || peerFs.currentYearMonth();
+    const home = opts.home || HOME;
+    const summaryPath = getPeerSummaryPath(agentId, publicKey, yearMonth);
+    const cursorPath = getPeerSummaryCursorPath(agentId, publicKey, yearMonth);
+    const archivePath = peerFs.getPeerChatPath(publicKey, yearMonth);
+    // 读归档
+    const lines = await readArchiveLines(publicKey, yearMonth);
+    if (lines.length === 0) {
+        return { summaryPath, cursorPath, entriesCount: 0, bytesWritten: 0, skipped: 'no-archive' };
+    }
+    // 解析 entries
+    const allEntries = parseArchiveEntries(lines);
+    const cursor = await readSummaryCursor(cursorPath);
+    const newEntries = allEntries.slice(cursor);
+    const minNew = opts.minNewEntries ?? 20;
+    if (newEntries.length < minNew) {
+        return { summaryPath, cursorPath, entriesCount: newEntries.length, bytesWritten: 0, skipped: 'too-few-entries' };
+    }
+    const timestamp = new Date().toISOString();
+    let summaryBody;
+    try {
+        const sysPrompt = '你是 bolloon 月度记忆压缩助手. 输入是按 peer 月度归档的聊天记录 markdown, 输出 400-800 字中文摘要, 包含: 1) 关键合作主题; 2) 共同完成的成果; 3) 待跟进事项; 4) 对方能力偏好. 不要寒暄, 不复述已知.';
+        const recentSnippet = newEntries.slice(-30).map(e => {
+            const ts = e.entry.ts;
+            const chan = e.entry.channelName ? `[${e.entry.channelName}]` : '';
+            return `[${ts}]${chan} ${e.entry.source}: ${e.entry.text}`;
+        }).join('\n').slice(0, 8000);
+        const userPrompt = `Peer: ${publicKey}\n月份: ${yearMonth}\n时间: ${timestamp}\n新增条数: ${newEntries.length}\n\n最近对话:\n${recentSnippet}`;
+        summaryBody = await tryMonthlyLlm(sysPrompt, userPrompt);
+    }
+    catch (e) {
+        summaryBody = templateMonthlySummary({
+            publicKey,
+            yearMonth,
+            entries: newEntries.map(e => e.entry),
+            timestamp,
+        });
+    }
+    const block = `\n\n---\n\n## 增量摘要 @ ${timestamp} (${newEntries.length} entries)\n\n${summaryBody.trim()}\n`;
+    await fs.mkdir(path.dirname(summaryPath), { recursive: true });
+    await fs.appendFile(summaryPath, block, 'utf-8');
+    await writeSummaryCursor(cursorPath, allEntries.length);
+    return {
+        summaryPath,
+        cursorPath,
+        entriesCount: newEntries.length,
+        bytesWritten: Buffer.byteLength(block, 'utf-8'),
+    };
+}
+/**
+ * 把 session.json 中的所有消息按 peer 切分, 一次性 archive 到各 peer 月度文件.
+ * 用于: ① 启动时迁移已有 session 历史到 peer archive; ② 兜底补档.
+ */
+export async function archiveSessionMessagesForPeer(opts) {
+    let written = 0;
+    let errors = 0;
+    for (const m of opts.messages) {
+        const ts = m.timestamp || new Date().toISOString();
+        const entry = {
+            ts,
+            source: m.source || (m.type === 'user' ? 'remote' : 'ai-mention'),
+            channelId: m.channelId,
+            channelName: m.channelName,
+            text: m.content,
+            fromPublicKey: m.fromPublicKey || opts.publicKey,
+            msgType: m.type,
+        };
+        const r = await appendChatArchive({ publicKey: opts.publicKey, entry });
+        if (r.ok)
+            written++;
+        else
+            errors++;
+    }
+    return { written, errors };
+}
+/**
+ * 列出指定 peer 所有可用的月度摘要 (按月份倒序)
+ */
+export async function listPeerSummaries(agentId, publicKey) {
+    const dir = getPeerSummaryDir(agentId, publicKey);
+    try {
+        const entries = await fs.readdir(dir);
+        return entries
+            .filter(e => /^\d{4}-\d{2}\.summary\.md$/.test(e))
+            .map(e => ({
+            yearMonth: e.replace(/\.summary\.md$/, ''),
+            path: path.join(dir, e),
+            size: fsSync.statSync(path.join(dir, e)).size,
+        }))
+            .sort((a, b) => b.yearMonth.localeCompare(a.yearMonth));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/bootstrap/context-collector.js

@@ -136,10 +136,13 @@ async function collectJudgmentsSummary(topN) {
         topValues,
     };
 }
-async function collectSkills() {
+async function collectSkills(projectCwd) {
     const home = process.env.HOME || os.homedir() || '/tmp';
     const userSkillsDir = path.join(home, '.bolloon', 'skills');
-    const projectSkillsDir = path.join(process.cwd(), '.bolloon', 'skills');
+    // 2026-07-04: 用 opts.cwd 而不是 process.cwd(), 让 collectBolloonContext({cwd})
+    //   在测试或子进程里能正确隔离项目级 skill 目录 (之前 process.cwd() 会读到
+    //   caller 的 cwd, 测试空目录时泄漏真实项目 skills).
+    const projectSkillsDir = path.join(projectCwd || process.cwd(), '.bolloon', 'skills');
     const out = [];
     const seen = new Set();
     for (const dir of [userSkillsDir, projectSkillsDir]) {
@@ -273,7 +276,7 @@ export async function collectBolloonContext(opts) {
         collectProject(cwd, bolloonMdMaxBytes),
         collectGit(cwd, gitCommitLimit),
         collectPersona(),
-        collectSkills(),
+        collectSkills(cwd),
         Promise.resolve(collectEnv()),
         collectPending(opts),
         collectHierarchy(cwd),

package/dist/bootstrap/event-log.js

@@ -0,0 +1,160 @@
+/**
+ * event-log.ts — 项目事件日志 (Layer 2)
+ *
+ * 2026-07-07 新增. 解决:
+ *   - 当前 judgment 是"决策规则", 项目状态/feature 生命周期没有结构化记录
+ *   - 用户问"这个项目我们做了什么"时无法结构化回放
+ *   - LLM prompt 缺少"最近变更"上下文
+ *
+ * 设计:
+ *   - JSONL 格式 (append-only), 路径: ~/.bolloon/project/<safe-channelId>/events.jsonl
+ *   - 5 类事件: project_created / feature_added / feature_removed / requirement_changed / task_completed
+ *   - 每条带 schema_version, 便于后续演化
+ *   - 不依赖 LLM, 纯文件 IO; 失败静默不阻塞主对话
+ *
+ * 触发:
+ *   - server.ts: /message 处理后根据用户/AI 内容检测事件关键词 → appendEvent
+ *   - server.ts: LLM prompt 装配 → getRecentEvents(channelId, 5)
+ *   - client.ts: channel 头部 → 显示事件时间线折叠块
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+// ============== 类型 ==============
+export const EVENT_SCHEMA_VERSION = 1;
+export const EVENT_TYPES = [
+    'project_created',
+    'feature_added',
+    'feature_removed',
+    'requirement_changed',
+    'task_completed',
+];
+// ============== 路径 ==============
+function sanitize(s) {
+    return s.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 128);
+}
+/** ~/.bolloon/project/<safe-channelId>/events.jsonl */
+export function getEventLogPath(channelId, home) {
+    const root = path.join(home || os.homedir(), '.bolloon', 'project', sanitize(channelId));
+    return path.join(root, 'events.jsonl');
+}
+// ============== 追加 ==============
+/**
+ * 追加一条事件. JSONL 格式 (1 行 1 JSON).
+ * 失败抛错 — 由 caller 决定是否静默.
+ */
+export async function appendEvent(opts) {
+    const filePath = getEventLogPath(opts.channelId, opts.home);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    const event = {
+        schema_version: EVENT_SCHEMA_VERSION,
+        type: opts.type,
+        ts: new Date().toISOString(),
+        channelId: opts.channelId,
+        agentId: opts.agentId,
+        summary: opts.summary,
+        detail: opts.detail || {},
+        source: opts.source || 'system',
+    };
+    const line = JSON.stringify(event) + '\n';
+    await fs.appendFile(filePath, line, 'utf-8');
+    return { path: filePath, bytesWritten: Buffer.byteLength(line, 'utf-8') };
+}
+// ============== 读取 ==============
+/**
+ * 列出事件. 倒序 (最新在前), 可选 limit / type 过滤.
+ * 文件不存在 → 返回 []. 单行损坏 → 跳过, 不抛错.
+ */
+export async function listEvents(opts) {
+    const filePath = getEventLogPath(opts.channelId, opts.home);
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const events = [];
+    const lines = raw.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const ev = JSON.parse(trimmed);
+            if (opts.type && ev.type !== opts.type)
+                continue;
+            if (typeof ev !== 'object' || !ev.type || !ev.ts)
+                continue;
+            events.push(ev);
+        }
+        catch {
+            // 跳过损坏行
+        }
+    }
+    // 倒序 (最新在前)
+    events.reverse();
+    if (opts.limit && opts.limit > 0) {
+        return events.slice(0, opts.limit);
+    }
+    return events;
+}
+/**
+ * 取最近 N 条事件 (alias for listEvents, 默认 limit=5, 给 prompt 注入用).
+ */
+export async function getRecentEvents(channelId, limit = 5, home) {
+    return listEvents({ channelId, home, limit });
+}
+// ============== 删除 ==============
+/**
+ * 删事件日志 (channel 删除时调用). 文件不存在不报错.
+ */
+export async function deleteEventLog(channelId, home) {
+    const filePath = getEventLogPath(channelId, home);
+    try {
+        await fs.unlink(filePath);
+    }
+    catch (e) {
+        if (e?.code !== 'ENOENT')
+            throw e;
+    }
+}
+// ============== 简易事件检测 (heuristic) ==============
+/**
+ * 从用户消息中检测可能的事件 (基于关键词). 返回最多 N 条事件.
+ * LLM 检测更准, 但本函数作为 fallback / 实时检测用, 不阻塞主对话.
+ */
+export function detectEventsFromText(opts) {
+    const text = opts.text.toLowerCase();
+    const out = [];
+    // project_created: "建项目" / "create project" / "new project" / "新项目"
+    if (/(建项目|创建项目|新项目|create\s*project|new\s*project)/i.test(text)) {
+        out.push({ type: 'project_created', summary: opts.text.slice(0, 80), detail: { raw: opts.text.slice(0, 200) } });
+    }
+    // feature_added: "加入" / "增加" / "添加" + 跟一个 "功能/feature" 关键字
+    if (/(加入|增加|添加|添加了|加\s*一个|add\s*feature|add\s*function)/i.test(text)) {
+        const m = text.match(/(加入|增加|添加|添加了|加\s*一个|add\s*feature|add\s*function)\s*[:：]?\s*([^。.!?\n]{2,40})/i);
+        if (m) {
+            out.push({ type: 'feature_added', summary: `+ ${m[2].trim()}`, detail: { name: m[2].trim(), raw: opts.text.slice(0, 200) } });
+        }
+    }
+    // feature_removed: "不要" / "去掉" / "删除" + "功能"
+    if (/(不要|去掉|删除|移除|remove|delete|drop)\s*(这个|该|那)?\s*(功能|特性|feature)/i.test(text)) {
+        const m = text.match(/(不要|去掉|删除|移除|remove|delete|drop)\s*(?:了)?\s*[:：]?\s*([^。.!?\n]{2,40})/i);
+        if (m) {
+            out.push({ type: 'feature_removed', summary: `- ${m[2].trim()}`, detail: { name: m[2].trim(), raw: opts.text.slice(0, 200) } });
+        }
+    }
+    // requirement_changed: "改成" / "修改" / "调整为"
+    if (/(改成|修改|调整|需求变更|change\s*to|update\s*to|revise)/i.test(text)) {
+        const m = text.match(/(改成|修改|调整|change\s*to|update\s*to|revise)\s*[:：]?\s*([^。.!?\n]{2,60})/i);
+        if (m) {
+            out.push({ type: 'requirement_changed', summary: `Δ ${m[2].trim()}`, detail: { target: m[2].trim(), raw: opts.text.slice(0, 200) } });
+        }
+    }
+    // task_completed: "完成" / "搞定" / "done" / "shipped"
+    if (/(完成了?|搞定了?|做完了?|done|finished|shipped|closed)/i.test(text)) {
+        out.push({ type: 'task_completed', summary: opts.text.slice(0, 80), detail: { raw: opts.text.slice(0, 200) } });
+    }
+    return out.slice(0, 3); // 一次最多 3 条 (避免 spam)
+}

package/dist/bootstrap/lifecycle-hooks.js

@@ -9,6 +9,7 @@ import * as os from 'os';
 import * as path from 'path';
 import { getCachedBolloonContext, clearBolloonContextCache } from './context-collector.js';
 import { formatContextForSystemPrompt } from './project-context.js';
+import { loadPersonaDocs, formatPersonaForSystemPrompt } from './persona-loader.js';
 let lastSessionStartAt = 0;
 const MIN_INTERVAL_MS = 5000; // 同一进程 5s 内最多触发一次, 防止循环
 export async function onSessionStart(opts = {}) {
@@ -25,10 +26,23 @@ export async function onSessionStart(opts = {}) {
         if (opts.channelId) {
             systemAddition = `# 当前 channel: ${opts.channelId}\n\n` + systemAddition;
         }
+        // 在头部最前拼 persona 文档 (如果 agentId 存在)
+        if (opts.agentId) {
+            try {
+                const docs = await loadPersonaDocs(opts.agentId);
+                const personaText = formatPersonaForSystemPrompt(docs);
+                if (personaText) {
+                    systemAddition = personaText + '\n\n' + systemAddition;
+                }
+            }
+            catch (err) {
+                console.warn('[lifecycle-hooks] loadPersonaDocs failed (silent):', err);
+            }
+        }
         return {
             systemAddition,
             collectMs: Date.now() - start,
-            truncated: systemAddition.length > 0 && systemAddition.includes('截断模式'),
+            truncated: systemAddition.length > 0 && systemAddition.includes('截断'),
         };
     }
     catch (err) {

package/dist/bootstrap/memory-compressor.js

@@ -0,0 +1,170 @@
+/**
+ * Memory Compressor — session 消息 → LLM 摘要 → ~/.bolloon/memory/<agentId>/sessions/
+ *
+ * 触发: 每次 /message 处理后, saveSession 之后 (server.ts:2073 之后)
+ * 行为:
+ *   - 读 session messages
+ *   - 只压缩 cursor 之后的增量 (≥ 4 条新 messages 才压缩, 防频繁)
+ *   - 调 LLM 生成中文摘要 (失败 fallback 到纯模板)
+ *   - append 模式写入 <safe-channelId>__<safe-sessionId>.summary.md
+ *   - 维护 cursor 文件 <safe-channelId>__<safe-sessionId>.cursor
+ *
+ * 失败静默: 调用方 try/catch 后 console.warn, 不阻塞主对话.
+ */
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+export function sanitizeAgentId(id) {
+    return id.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
+}
+export function sanitizeKey(id) {
+    return id.replace(/[^a-zA-Z0-9_.-]/g, '_').slice(0, 128);
+}
+/**
+ * ~/.bolloon/memory/<sanitizedAgentId>/
+ */
+export function getMemoryDir(agentId, home) {
+    return path.join(home || os.homedir(), '.bolloon', 'memory', sanitizeAgentId(agentId));
+}
+/**
+ * ~/.bolloon/memory/<agentId>/sessions/<safe-channelId>__<safe-sessionId>.summary.md
+ */
+export function getSessionSummaryPath(agentId, channelId, sessionId, home) {
+    const key = `${sanitizeKey(channelId)}__${sanitizeKey(sessionId)}`;
+    return path.join(getMemoryDir(agentId, home), 'sessions', `${key}.summary.md`);
+}
+export function getSessionCursorPath(agentId, channelId, sessionId, home) {
+    const key = `${sanitizeKey(channelId)}__${sanitizeKey(sessionId)}`;
+    return path.join(getMemoryDir(agentId, home), 'sessions', `${key}.cursor`);
+}
+/**
+ * Session 缓存文件路径 (跟 server.ts:1806 sessionKey 规则一致)
+ */
+function getSessionCacheFile(channelId, sessionId, home) {
+    const root = path.join(home || os.homedir(), '.bolloon', 'sessions', 'cache');
+    const safeChannel = sanitizeKey(channelId);
+    const safeSession = sanitizeKey(sessionId).replace(/:/g, '__');
+    return path.join(root, `${safeChannel}__${safeSession}.json`);
+}
+async function readCursor(cursorPath) {
+    try {
+        const raw = await fs.readFile(cursorPath, 'utf-8');
+        const n = parseInt(raw.trim(), 10);
+        return Number.isFinite(n) && n >= 0 ? n : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+async function writeCursor(cursorPath, value) {
+    await fs.mkdir(path.dirname(cursorPath), { recursive: true });
+    await fs.writeFile(cursorPath, String(value), 'utf-8');
+}
+async function readSessionMessages(sessionCacheFile) {
+    try {
+        const raw = await fs.readFile(sessionCacheFile, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed))
+            return parsed;
+        if (Array.isArray(parsed.messages))
+            return parsed.messages;
+        return [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * 纯模板摘要 (LLM 失败 fallback, 不依赖外部调用)
+ */
+function templateSummary(opts) {
+    const userMsgs = opts.newMessages.filter(m => m.type === 'user');
+    const aiMsgs = opts.newMessages.filter(m => m.type === 'ai');
+    const userSnippet = userMsgs.slice(0, 3).map(m => `  - ${m.content.slice(0, 80)}`).join('\n');
+    const aiSnippet = aiMsgs.slice(0, 3).map(m => `  - ${m.content.slice(0, 80)}`).join('\n');
+    return `# Session 摘要 — ${opts.channelId} / ${opts.sessionId}
+
+时间: ${opts.timestamp}
+新增消息数: ${opts.newMessages.length} (user=${userMsgs.length}, ai=${aiMsgs.length})
+
+## 用户关键提问
+${userSnippet || '  (无)'}
+
+## AI 关键回答
+${aiSnippet || '  (无)'}
+
+## 备注
+- 此摘要由模板生成 (LLM 调用失败 fallback)
+`;
+}
+/**
+ * 尝试调 LLM 生成更精炼的中文摘要. 失败 → 抛错, 由 caller fallback.
+ *
+ * 用动态 import + 失败静默 — 不引入 pi-ai 强依赖 (避免循环).
+ */
+async function tryLlmSummary(systemPrompt, userPrompt) {
+    try {
+        const piAi = await import('../llm/pi-ai.js');
+        const generateText = piAi.generateText;
+        if (typeof generateText !== 'function')
+            throw new Error('generateText not exported');
+        const result = await generateText({
+            messages: [
+                { role: 'system', content: systemPrompt },
+                { role: 'user', content: userPrompt },
+            ],
+            temperature: 0.2,
+            maxTokens: 800,
+        });
+        const text = result?.reply || result?.text || '';
+        if (typeof text !== 'string' || text.length < 20)
+            throw new Error('LLM returned too-short text');
+        return text;
+    }
+    catch (e) {
+        throw new Error(`LLM call failed: ${e?.message || String(e)}`);
+    }
+}
+export async function compressSessionToMemory(opts) {
+    const agentId = sanitizeAgentId(opts.agentId);
+    const home = opts.home || os.homedir();
+    const summaryPath = getSessionSummaryPath(agentId, opts.channelId, opts.sessionId, home);
+    const cursorPath = getSessionCursorPath(agentId, opts.channelId, opts.sessionId, home);
+    const sessionCacheFile = getSessionCacheFile(opts.channelId, opts.sessionId, home);
+    const allMessages = await readSessionMessages(sessionCacheFile);
+    const cursor = await readCursor(cursorPath);
+    const newMessages = allMessages.slice(cursor);
+    const minNew = opts.minNewMessages ?? 4;
+    if (allMessages.length === 0) {
+        return { summaryPath, cursorPath, messagesCount: 0, bytesWritten: 0, skipped: 'no-new-messages' };
+    }
+    if (newMessages.length < minNew) {
+        return { summaryPath, cursorPath, messagesCount: newMessages.length, bytesWritten: 0, skipped: 'too-few-messages' };
+    }
+    const timestamp = new Date().toISOString();
+    let summaryBody;
+    try {
+        const sysPrompt = '你是 bolloon 记忆压缩助手. 输入是一段 session 消息历史 (用户问题 + AI 回答), 输出 200-400 字中文摘要, 包含 3-5 条关键发现和未完成事项. 不要寒暄, 不要复述已知. 格式: ## 关键发现 / ## 待办.';
+        const recentSnippet = newMessages.slice(-10).map(m => `[${m.type}] ${m.content}`).join('\n---\n').slice(0, 6000);
+        const userPrompt = `Channel: ${opts.channelId}\nSession: ${opts.sessionId}\n时间: ${timestamp}\n新增消息数: ${newMessages.length}\n\n最近消息:\n${recentSnippet}`;
+        summaryBody = await tryLlmSummary(sysPrompt, userPrompt);
+    }
+    catch (e) {
+        summaryBody = templateSummary({
+            channelId: opts.channelId,
+            sessionId: opts.sessionId,
+            newMessages,
+            timestamp,
+        });
+    }
+    const block = `\n\n---\n\n## 增量摘要 @ ${timestamp} (${newMessages.length} messages)\n\n${summaryBody.trim()}\n`;
+    await fs.mkdir(path.dirname(summaryPath), { recursive: true });
+    await fs.appendFile(summaryPath, block, 'utf-8');
+    await writeCursor(cursorPath, allMessages.length);
+    return {
+        summaryPath,
+        cursorPath,
+        messagesCount: newMessages.length,
+        bytesWritten: Buffer.byteLength(block, 'utf-8'),
+    };
+}