@bolloon/bolloon-agent 0.2.11 → 0.2.13

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;
+}

package/dist/bootstrap/project-state.js

@@ -0,0 +1,159 @@
+/**
+ * project-state.ts — 项目当前状态 (Layer 3)
+ *
+ * 2026-07-07 新增. 解决:
+ *   - judgment 是"决策规则", 项目当前状态/目标/约束/待办没有结构化记录
+ *   - 用户开启新 session 时无法 auto-inject "上次我们做到哪"
+ *   - 远端/本地协作时, 双方项目状态不同步
+ *
+ * 设计:
+ *   - state.json: ~/.bolloon/project/<safe-channelId>/state.json
+ *   - 字段: goal / constraints / todos / done / updatedAt / updatedBy / version
+ *   - 写盘走 append-only diff (每次写盘生成新版本号, 不覆盖历史快照)
+ *   - 失败静默不阻塞主对话
+ *
+ * 触发:
+ *   - server.ts: LLM 回答完后, prompt 注入当前 state (LLM 不会自动改, 只读取)
+ *   - 用户可手动调 PATCH /api/state/:channelId 改写
+ *   - future: 加 LLM 自动建议更新 (UI 弹 confirm)
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+// ============== 路径 ==============
+function sanitize(s) {
+    return s.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 128);
+}
+function getStateDir(channelId, home) {
+    return path.join(home || os.homedir(), '.bolloon', 'project', sanitize(channelId));
+}
+export function getStatePath(channelId, home) {
+    return path.join(getStateDir(channelId, home), 'state.json');
+}
+export function getStateBackupPath(channelId, home) {
+    return path.join(getStateDir(channelId, home), 'state.backup.jsonl');
+}
+// ============== 默认 ==============
+export function defaultState(channelId) {
+    return {
+        goal: '',
+        constraints: [],
+        todos: [],
+        done: [],
+        updatedAt: new Date(0).toISOString(),
+        updatedBy: 'system',
+        version: 0,
+    };
+}
+// ============== 读取 ==============
+/**
+ * 读 state.json. 文件不存在 → 返回默认空 state.
+ * 损坏 → 返回默认 state + console.warn, 不抛错.
+ */
+export async function readState(opts) {
+    const filePath = getStatePath(opts.channelId, opts.home);
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || !parsed)
+            return defaultState(opts.channelId);
+        return {
+            goal: typeof parsed.goal === 'string' ? parsed.goal : '',
+            constraints: Array.isArray(parsed.constraints) ? parsed.constraints.filter((x) => typeof x === 'string') : [],
+            todos: Array.isArray(parsed.todos) ? parsed.todos.filter((x) => typeof x === 'string') : [],
+            done: Array.isArray(parsed.done) ? parsed.done.filter((x) => typeof x === 'string') : [],
+            updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+            updatedBy: typeof parsed.updatedBy === 'string' ? parsed.updatedBy : 'system',
+            version: typeof parsed.version === 'number' ? parsed.version : 0,
+        };
+    }
+    catch (e) {
+        if (e?.code !== 'ENOENT')
+            console.warn(`[project-state] ${opts.channelId} 损坏: ${e?.message || e}`);
+        return defaultState(opts.channelId);
+    }
+}
+// ============== 写 ==============
+/**
+ * 完整覆盖写入 state.json. 自动:
+ *   1. 备份当前 state 到 state.backup.jsonl (append-only)
+ *   2. 设置 updatedAt + version +1
+ *   3. done 数组截断到 20 条
+ */
+export async function writeState(opts) {
+    const filePath = getStatePath(opts.channelId, opts.home);
+    const backupPath = getStateBackupPath(opts.channelId, opts.home);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    // 备份当前 (append-only)
+    const cur = await readState(opts);
+    if (cur.version > 0) {
+        const line = JSON.stringify({ ...cur, backupAt: new Date().toISOString() }) + '\n';
+        try {
+            await fs.appendFile(backupPath, line, 'utf-8');
+        }
+        catch (e) {
+            console.warn(`[project-state] backup 失败: ${e?.message || e}`);
+        }
+    }
+    const next = {
+        goal: opts.state.goal,
+        constraints: opts.state.constraints || [],
+        todos: opts.state.todos || [],
+        done: (opts.state.done || []).slice(-20),
+        updatedAt: new Date().toISOString(),
+        updatedBy: opts.state.updatedBy || 'system',
+        version: cur.version + 1,
+    };
+    await fs.writeFile(filePath, JSON.stringify(next, null, 2), 'utf-8');
+    return { path: filePath, version: next.version };
+}
+/**
+ * 部分字段 patch. 合并现有 state + patch.
+ */
+export async function mergeState(opts) {
+    const cur = await readState(opts);
+    const merged = {
+        goal: opts.patch.goal ?? cur.goal,
+        constraints: opts.patch.constraints ?? cur.constraints,
+        todos: opts.patch.todos ?? cur.todos,
+        done: opts.patch.done ?? cur.done,
+        updatedBy: opts.updatedBy,
+    };
+    const r = await writeState({ channelId: opts.channelId, state: merged, home: opts.home });
+    return { ...merged, updatedAt: new Date().toISOString(), version: r.version };
+}
+// ============== 简易操作 ==============
+/** 加一条 todo */
+export async function addTodo(opts) {
+    const cur = await readState(opts);
+    const todos = [...cur.todos, opts.text];
+    return mergeState({ channelId: opts.channelId, patch: { todos }, updatedBy: 'user', home: opts.home });
+}
+/** 标记 todo 完成 (移到 done) */
+export async function markTodoDone(opts) {
+    const cur = await readState(opts);
+    const todos = cur.todos.filter(t => t !== opts.text);
+    const done = [opts.text, ...cur.done].slice(0, 20);
+    return mergeState({ channelId: opts.channelId, patch: { todos, done }, updatedBy: 'user', home: opts.home });
+}
+/** 清空所有 todos (批量完成) */
+export async function clearTodos(opts) {
+    return mergeState({ channelId: opts.channelId, patch: { todos: [] }, updatedBy: 'user', home: opts.home });
+}
+/** 格式化 state 为 LLM prompt 注入文本 (单段落, ≤ 600 字) */
+export function formatStateForPrompt(state) {
+    if (state.version === 0 && !state.goal)
+        return '';
+    const lines = [];
+    if (state.goal)
+        lines.push(`目标: ${state.goal}`);
+    if (state.constraints.length > 0)
+        lines.push(`约束: ${state.constraints.slice(0, 5).join('; ')}`);
+    if (state.todos.length > 0)
+        lines.push(`待办 (${state.todos.length}): ${state.todos.slice(0, 5).join('; ')}`);
+    if (state.done.length > 0)
+        lines.push(`已完成 (最近): ${state.done.slice(0, 3).join('; ')}`);
+    if (lines.length === 0)
+        return '';
+    return `## 项目当前状态 (v${state.version}, ${state.updatedBy} @ ${state.updatedAt.slice(0, 16)})\n${lines.join('\n')}`;
+}

package/dist/bootstrap/remote-mirror.js

@@ -0,0 +1,97 @@
+/**
+ * remote-mirror.ts — 远端 channel 历史镜像 (B 端本地副本)
+ *
+ * 2026-07-07 新增. 解决:
+ *   - 远端 channel 历史在 B 端零持久化, A 端 session 删/损坏即丢
+ *   - A 端下线/不再分享该 channel, B 端再拉就 15s timeout
+ *   - 切回远端 channel 每次都重新 RPC, 无 L0 缓存
+ *
+ * 设计:
+ *   - B 端收到 agent.history.get.reply 后, 立刻镜像到
+ *     ~/.bolloon/peers/<pk>/sessions/<channelId>.json (覆盖式 atomic)
+ *   - 同时维护窗口 <channelId>.window.json (复用 session-window LRU)
+ *   - loadRemoteHistory 优先读本地镜像, 文件不存在/陈旧才走 RPC
+ *
+ * 触发:
+ *   - server.ts: agent.history.get.reply handler 写完 → mirrorRemoteHistory
+ *   - client.ts: openRemoteChannelChat → loadRemoteHistory 优先读镜像
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { saveWindow as saveSessionWindow } from './session-window.js';
+// ============== 路径 ==============
+function sanitize(s) {
+    return s.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 128);
+}
+/** ~/.bolloon/peers/<pk>/sessions/<safe-channelId>.json */
+export function getRemoteMirrorPath(targetPublicKey, channelId, home) {
+    const root = path.join(home || os.homedir(), '.bolloon', 'peers', sanitize(targetPublicKey), 'sessions');
+    return path.join(root, `${sanitize(channelId)}.json`);
+}
+/** ~/.bolloon/peers/<pk>/sessions/<safe-channelId>.window.json — 复用 session-window 路径规则 */
+export function getRemoteMirrorWindowPath(targetPublicKey, channelId, home) {
+    const root = path.join(home || os.homedir(), '.bolloon', 'peers', sanitize(targetPublicKey), 'sessions');
+    return path.join(root, `${sanitize(channelId)}.window.json`);
+}
+// ============== 写入 ==============
+/**
+ * 把 A 端的 history 镜像到 B 端本地. atomic (单文件 writeFile, 中途崩溃顶多旧版本留下).
+ * 失败静默不阻塞 RPC reply 返回.
+ */
+export async function mirrorRemoteHistory(opts) {
+    try {
+        const home = opts.home || os.homedir();
+        const mirrorPath = getRemoteMirrorPath(opts.targetPublicKey, opts.channelId, home);
+        const windowPath = getRemoteMirrorWindowPath(opts.targetPublicKey, opts.channelId, home);
+        await fs.mkdir(path.dirname(mirrorPath), { recursive: true });
+        // 主体镜像
+        const payload = {
+            channelId: opts.channelId,
+            channelName: opts.channelName,
+            fromPublicKey: opts.targetPublicKey,
+            messages: opts.messages,
+            lastUpdated: opts.lastUpdated || new Date().toISOString(),
+            mirroredAt: new Date().toISOString(),
+        };
+        await fs.writeFile(mirrorPath, JSON.stringify(payload, null, 2), 'utf-8');
+        // 窗口联动
+        await saveSessionWindow(opts.channelId, `remote-${opts.targetPublicKey.slice(0, 12)}`, opts.messages, { home, windowSize: 30 });
+        return { ok: true, mirrorPath, windowPath };
+    }
+    catch (e) {
+        return { ok: false, error: e?.message || String(e) };
+    }
+}
+/**
+ * 读远端 channel 的本地镜像. 失败/不存在 → 返回 null.
+ */
+export async function loadRemoteMirror(targetPublicKey, channelId, home) {
+    const mirrorPath = getRemoteMirrorPath(targetPublicKey, channelId, home);
+    try {
+        const raw = await fs.readFile(mirrorPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.messages))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 删镜像 (远端 channel 在本地的 share 列表移除时调用).
+ */
+export async function deleteRemoteMirror(targetPublicKey, channelId, home) {
+    const mirrorPath = getRemoteMirrorPath(targetPublicKey, channelId, home);
+    const windowPath = getRemoteMirrorWindowPath(targetPublicKey, channelId, home);
+    for (const p of [mirrorPath, windowPath]) {
+        try {
+            await fs.unlink(p);
+        }
+        catch (e) {
+            if (e?.code !== 'ENOENT')
+                throw e;
+        }
+    }
+}

package/dist/bootstrap/session-window.js

@@ -0,0 +1,121 @@
+/**
+ * session-window.ts — 显式 LRU 窗口 (Layer 0 热缓存)
+ *
+ * 2026-07-07 新增. 解决:
+ *   - sessions/cache/<key>.json 单文件无限增长直到 50MB 拒加载
+ *   - loadSession 返回 null 后前端 fallback "你好! 我是 Bolloon Agent" 用户以为历史没了
+ *   - 切 channel 首屏读整文件慢
+ *
+ * 设计:
+ *   - 独立窗口文件 <key>.window.json, 永远保持最近 N 条 (默认 30) raw messages
+ *   - LRU 语义: saveSession 后同步调用 saveWindow, append 新消息、pop 最老的
+ *   - loadSession fallback 链: window (秒开) → full json → summary
+ *   - 窗口与 full json 用 lastUpdated 校验版本, 防重复显示
+ *
+ * 触发:
+ *   - server.ts: saveSession 之后调 saveWindow
+ *   - server.ts: loadSession 失败/超大时 fallback 到 loadWindow
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+// ============== 路径 ==============
+/** 跟 server-storage.ts:loadSession 完全一致的 key 计算 */
+export function getWindowKey(channelId, sessionId) {
+    return sessionId ? `${channelId}:${sessionId}` : channelId;
+}
+/** ~/.bolloon/sessions/cache/<key>.window.json — 跟 session 文件同目录, 前缀区分 */
+export function getWindowPath(channelId, sessionId, home) {
+    const root = path.join(home || os.homedir(), '.bolloon', 'sessions', 'cache');
+    const key = getWindowKey(channelId, sessionId);
+    // Windows 兼容: 转义 : → __
+    const safeKey = key.replace(/:/g, '__');
+    return path.join(root, `${safeKey}.window.json`);
+}
+// ============== 写入 ==============
+/**
+ * 保存最近 N 条消息到窗口文件. LRU 语义.
+ *
+ * @param channelId   channel id
+ * @param sessionId   session id (没有就用 'default')
+ * @param messages    session 完整消息列表 (任意长度, 内部取尾 N 条)
+ * @param opts        窗口容量配置
+ */
+export async function saveWindow(channelId, sessionId, messages, opts = {}) {
+    const windowSize = opts.windowSize ?? 30;
+    const winPath = getWindowPath(channelId, sessionId, opts.home);
+    // LRU: 取尾 N 条
+    const windowMessages = messages.length > windowSize
+        ? messages.slice(-windowSize)
+        : messages.slice();
+    const win = {
+        channelId,
+        sessionId,
+        windowSize,
+        lastUpdated: new Date().toISOString(),
+        messages: windowMessages,
+        totalBehind: Math.max(0, messages.length - windowMessages.length),
+    };
+    await fs.mkdir(path.dirname(winPath), { recursive: true });
+    await fs.writeFile(winPath, JSON.stringify(win, null, 2), 'utf-8');
+    return {
+        windowPath: winPath,
+        windowSize: win.windowSize,
+        totalBehind: win.totalBehind,
+    };
+}
+// ============== 读取 ==============
+/**
+ * 读窗口文件. 文件不存在 / 损坏 → 返回 null (调用方应 fallback 到 full session 或 summary).
+ *
+ * @param channelId
+ * @param sessionId
+ * @param opts.windowSize 期望窗口大小, 跟落盘不一致时按期望截断
+ */
+export async function loadWindow(channelId, sessionId, opts = {}) {
+    const winPath = getWindowPath(channelId, sessionId, opts.home);
+    let raw;
+    try {
+        raw = await fs.readFile(winPath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    // 防御: 字段缺失/类型不对
+    if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.messages)) {
+        return null;
+    }
+    // 期望容量调整
+    const wantSize = opts.windowSize ?? parsed.windowSize ?? 30;
+    if (parsed.messages.length > wantSize) {
+        const dropped = parsed.messages.length - wantSize;
+        parsed = {
+            ...parsed,
+            windowSize: wantSize,
+            messages: parsed.messages.slice(-wantSize),
+            totalBehind: parsed.totalBehind + dropped,
+        };
+    }
+    return parsed;
+}
+// ============== 删除 ==============
+/**
+ * 删窗口文件 (跟 session 文件一起删). 文件不存在不报错.
+ */
+export async function deleteWindow(channelId, sessionId, home) {
+    const winPath = getWindowPath(channelId, sessionId, home);
+    try {
+        await fs.unlink(winPath);
+    }
+    catch (e) {
+        if (e?.code !== 'ENOENT')
+            throw e;
+    }
+}