@bolloon/bolloon-agent 0.2.7 → 0.2.9

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/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'),
+    };
+}

package/dist/bootstrap/persona-loader.js

@@ -0,0 +1,94 @@
+/**
+ * Persona Documents Loader — ~/.bolloon/persona/<agentId>/*.md
+ *
+ * 失败静默: 文件不存在 → 字段 = '', 不抛错
+ * 安全: agentId sanitize (防路径穿越)
+ * 6 段输出顺序: identity → soul → project → user → agent → wiki
+ */
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+const FILE_KEYS = ['soul', 'identity', 'project', 'user', 'agent', 'wiki'];
+/**
+ * 安全转 agentId: 只保留 [a-zA-Z0-9_-], 限长 64
+ * 防止路径穿越 ('/', '..', '\\\\' 都变 '_')
+ */
+export function sanitizeAgentId(id) {
+    return id.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
+}
+/**
+ * 读 ~/.bolloon/persona/<sanitizedAgentId>/{6 files}
+ * 文件不存在 → 该字段 = ''
+ */
+export async function loadPersonaDocs(agentId, home) {
+    const safeId = sanitizeAgentId(agentId);
+    const root = home || os.homedir();
+    const baseDir = path.join(root, '.bolloon', 'persona', safeId);
+    const docs = {
+        agentId: safeId,
+        soul: '',
+        identity: '',
+        project: '',
+        user: '',
+        agent: '',
+        wiki: '',
+    };
+    await Promise.all(FILE_KEYS.map(async (key) => {
+        const file = path.join(baseDir, `${key}.md`);
+        try {
+            const content = await fs.readFile(file, 'utf-8');
+            docs[key] = content;
+        }
+        catch {
+            docs[key] = '';
+        }
+    }));
+    return docs;
+}
+const DEFAULT_MAX_CHARS = 4000;
+const SECTION_LABELS = {
+    identity: 'Identity',
+    soul: 'Soul',
+    project: 'Project',
+    user: 'User',
+    agent: 'Agent',
+    wiki: 'Wiki',
+};
+const OUTPUT_ORDER = ['identity', 'soul', 'project', 'user', 'agent', 'wiki'];
+/**
+ * 把 PersonaDocs 格式化成 markdown 段, 拼到 system prompt 头部.
+ *
+ * 超 maxChars 时按比例截断: 每个字段都保留头部,
+ * 保证 6 段标识都出现, 不砍段.
+ */
+export function formatPersonaForSystemPrompt(docs, maxChars) {
+    const cap = maxChars ?? DEFAULT_MAX_CHARS;
+    // 段: 标识 + 字段值 (空字段跳过)
+    const sections = [];
+    for (const key of OUTPUT_ORDER) {
+        const v = docs[key];
+        if (v && v.length > 0) {
+            sections.push({ key, text: `## ${SECTION_LABELS[key]}\n${v}` });
+        }
+    }
+    if (sections.length === 0)
+        return '';
+    // 预算每段 (去掉 ## 标识和换行的固定开销)
+    const header = `# Persona (agentId=${docs.agentId})\n\n`;
+    const fixedOverhead = header.length + (sections.length - 1) * 2;
+    const perSectionBudget = Math.max(50, Math.floor((cap - fixedOverhead) / sections.length));
+    const parts = [header.trim()];
+    for (const sec of sections) {
+        let body = sec.text;
+        if (body.length > perSectionBudget) {
+            body = body.substring(0, perSectionBudget) + '\n... (截断)';
+        }
+        parts.push(body);
+    }
+    let result = parts.join('\n\n');
+    if (result.length > cap) {
+        const truncateMarker = '\n... (截断)';
+        result = result.substring(0, Math.max(0, cap - truncateMarker.length)) + truncateMarker;
+    }
+    return result;
+}