@bolloon/bolloon-agent 0.6.1 → 0.6.3

package/dist/kernel/session-lifecycle.js

@@ -0,0 +1,210 @@
+/**
+ * session-lifecycle.ts — K10 余项: **会话生命周期端口** (把 pi-sdk 的运行/通道接线继续薄化)
+ *
+ * 搬走的是**规则**, 不是 I/O:
+ *   · `save-session`    : 消息 → 落盘形态的映射 (role/content/toolCall/toolResult/toolCallId/timestamp/source) + key 校验
+ *   · `peek-history`    : 读回后的**过滤/水合规则** (合法 role · 剔污染消息 · **保留"只有 tool call 没有正文"的合法消息**)
+ *   · `resume-session`  : 同上 + 把水合结果**应用**回历史 (应用由端口做), 返回新增条数
+ *   · `seed-run`        : 新一次运行的上下文种子 —— runId 来自**内核的活跃运行** (单一来源), extra 覆盖它 (**合并顺序是规则**)
+ *
+ * I/O (store 读写 · actor 快照 · 上下文工厂) 全部**端口注入** ⇒ 换存储 / 换 actor 实现只改注入点一处。
+ *
+ * 形状照抄 `run-lifecycle.ts` / `transport.ts` / `control.ts` (同一个仓库里只该有一种端口写法):
+ *   端口注入 · **未注入即拒** (不静默降级) · 一律**返回结果对象不抛** · 端口用 `{ok:false}` 表达拒绝要被归一化 · 审计流水可读。
+ *
+ * 哪些**留在** pi-sdk: 谁在什么时候调 (入口/时机) + 端口实现 (真 store / 真 actor)。本文件不 import 任何 agent 侧模块。
+ */
+export const SESSION_OPS = ['save-session', 'peek-history', 'resume-session', 'seed-run'];
+/** 哪些操作必须有会话 key (seed-run 例外: 它要的是**活跃运行**, 不是会话 key) */
+export const SESSION_NEEDS_KEY = {
+    'save-session': true,
+    'peek-history': true,
+    'resume-session': true,
+    'seed-run': false,
+};
+/** 端口**不抛异常但明确拒绝** (`{ ok: false, reason }`) 的归一化 —— 与 `control.ts` / `run-lifecycle.ts` 同口径 */
+function portRefusal(res) {
+    if (res && typeof res === 'object' && 'ok' in res) {
+        const r = res;
+        if (r.ok === false)
+            return `端口拒绝: ${String(r.reason ?? '(未给原因)')}`;
+    }
+    return null;
+}
+const audit = [];
+const AUDIT_MAX = 200;
+/** 审计流水 (最近 N 条; 测试与运维可读) */
+export function sessionLifecycleAudit() {
+    return audit;
+}
+export function resetSessionLifecycleAudit() {
+    audit.length = 0;
+}
+function record(op, origin, target, ok, detail) {
+    audit.push({ at: Date.now(), op, origin, target, ok, detail });
+    if (audit.length > AUDIT_MAX)
+        audit.splice(0, audit.length - AUDIT_MAX);
+}
+// ── 纯规则 (可单独判: 不碰 I/O) ──────────────────────────────────────────────
+/** 会话 key 必须是非空字符串 —— 空 key 会让写入落到一个"共享黑洞"里, 必须当场拒 */
+export function isValidSessionKey(key) {
+    return typeof key === 'string' && key.trim().length > 0;
+}
+/** 合法角色 (拒绝旧 schema `{type:'user'}` 那种没有 role 字段的) */
+export const SESSION_ROLES = new Set(['user', 'assistant', 'tool', 'system']);
+/**
+ * 落盘映射: 实时消息 → 持久形态。
+ *   `timestamp` 取**写盘那一刻** (不是消息里的旧值) —— 迁移前就是这个口径, 明确保留。
+ *   `source` 标记写入方 (默认 'pi-session')。
+ */
+export function toPersistedMessages(source, sourceTag = 'pi-session', now = Date.now) {
+    const ts = now();
+    return (source ?? []).map((raw) => {
+        const m = (raw ?? {});
+        return {
+            role: m.role,
+            content: m.content,
+            toolCall: m.toolCall,
+            toolResult: m.toolResult,
+            toolCallId: m.toolCallId,
+            timestamp: ts,
+            source: sourceTag,
+        };
+    });
+}
+/**
+ * 读回水合 + 过滤规则 (逐字搬自 pi-sdk, 只去掉 instance 依赖)。
+ * 三条"必须保留"的坑都在这:
+ *   ① `content === ''` 但带 toolCall 的 assistant 消息**合法** (LLM 只输出工具调用没有正文) ⇒ 不许按"空内容"丢掉;
+ *   ② 「[AI 服务调用失败]」/「[错误:」开头的污染消息要剔;
+ *   ③ tool role 但没有 toolResult 的占位消息要剔。
+ */
+export function filterSessionMessages(loaded) {
+    if (!loaded)
+        return [];
+    const hydrated = [];
+    for (const m of loaded) {
+        if (!m || !SESSION_ROLES.has(String(m.role)))
+            continue;
+        if (typeof m.content === 'string' && m.content.startsWith('[AI 服务调用失败]'))
+            continue;
+        if (typeof m.content === 'string' && m.content.startsWith('[错误:'))
+            continue;
+        if (!m.content && !m.toolCall && !m.toolResult)
+            continue;
+        if (m.role === 'tool' && !m.toolResult)
+            continue;
+        hydrated.push({
+            role: m.role,
+            content: m.content ?? '',
+            toolCall: m.toolCall,
+            toolResult: m.toolResult,
+            toolCallId: m.toolCallId,
+        });
+    }
+    return hydrated;
+}
+/**
+ * 过滤 + 截断 (取**最近** maxMessages 条) —— 给"自己不做截断"的调用方用。
+ *   actor 的 `hydrateHistory(spec)` 管道自带截断 ⇒ 那边只该用 `filterSessionMessages` (别截两次)。
+ */
+export function hydrateSessionMessages(loaded, maxMessages = 30) {
+    const filtered = filterSessionMessages(loaded);
+    const max = Number.isFinite(maxMessages) && maxMessages > 0 ? Math.floor(maxMessages) : 0;
+    return max > 0 ? filtered.slice(-max) : [];
+}
+/**
+ * 运行种子 = 活跃运行的 runId 打底 + `extra` 覆盖它 (**合并顺序是规则, 所以它归内核**)。
+ *   与 `seed-run` 分支共用这一条规则; 同步调用点 (pi-sdk 的 `seedRunContext` 是同步签名) 直接调它, 不必为了合并一次规则绕异步端口。
+ */
+export function composeRunSeed(activeRunId, extra = {}) {
+    return { runId: activeRunId, ...extra };
+}
+// ── 派发 (唯一入口) ───────────────────────────────────────────────────────────
+const missing = (what) => `端口未注入: ${what} (拒绝静默降级)`;
+/**
+ * 会话生命周期的**唯一系统调用门**。
+ *   未注入端口 / 缺 key ⇒ `{ ok:false }` (不抛); 端口抛错 ⇒ 也归一化成 `{ ok:false, detail }` (调用方按自己的响亮口径处理)。
+ */
+export async function submitSessionOp(request, ports) {
+    const op = request?.op;
+    const origin = String(request?.origin ?? '').trim() || 'unknown';
+    const target = String(request?.key ?? '').trim() || '-';
+    const fail = (detail) => {
+        record(op, origin, target, false, detail);
+        return { ok: false, op, via: 'kernel-session-lifecycle', detail };
+    };
+    if (!SESSION_OPS.includes(op))
+        return fail(`未知会话操作: ${String(op)}`);
+    if (!origin || origin === 'unknown')
+        return fail('缺少 origin (审计要求, 不许匿名)');
+    if (SESSION_NEEDS_KEY[op] && !isValidSessionKey(request.key))
+        return fail(`缺少合法会话 key (op=${op})`);
+    try {
+        if (op === 'save-session') {
+            const key = request.key;
+            if (!ports.saveMessages)
+                return fail(missing('saveMessages'));
+            if (!ports.historySnapshot)
+                return fail(missing('historySnapshot'));
+            const source = (await ports.historySnapshot()) ?? [];
+            const persisted = toPersistedMessages(source);
+            const res = await ports.saveMessages(key, persisted);
+            const refusal = portRefusal(res);
+            if (refusal)
+                return fail(refusal);
+            record(op, origin, target, true);
+            return { ok: true, op, via: 'kernel-session-lifecycle', port: 'saveMessages', result: { count: persisted.length } };
+        }
+        if (op === 'peek-history') {
+            const key = request.key;
+            if (!ports.loadMessages)
+                return fail(missing('loadMessages'));
+            const loaded = await ports.loadMessages(key);
+            const hydrated = hydrateSessionMessages(loaded, request.maxMessages ?? 30);
+            record(op, origin, target, true);
+            return { ok: true, op, via: 'kernel-session-lifecycle', port: 'loadMessages', result: hydrated };
+        }
+        if (op === 'resume-session') {
+            const key = request.key;
+            if (!ports.loadMessages)
+                return fail(missing('loadMessages'));
+            if (!ports.applyHistory)
+                return fail(missing('applyHistory'));
+            const loaded = await ports.loadMessages(key);
+            const hydrated = hydrateSessionMessages(loaded, request.maxMessages ?? 30);
+            const applied = (await ports.applyHistory(hydrated)) ?? 0;
+            const refusal = portRefusal(applied);
+            if (refusal)
+                return fail(refusal);
+            record(op, origin, target, true, `应用 ${hydrated.length} 条`);
+            return { ok: true, op, via: 'kernel-session-lifecycle', port: 'applyHistory', result: Number(applied) || 0 };
+        }
+        // seed-run
+        if (!ports.activeRunId)
+            return fail(missing('activeRunId'));
+        if (!ports.newRunContext)
+            return fail(missing('newRunContext'));
+        const activeRun = ports.activeRunId();
+        const extra = (request.extra ?? {});
+        // 合并顺序是规则: 先放活跃运行得到的 runId, 再让 extra 覆盖 (调用方显式传的优先)
+        const seed = composeRunSeed(activeRun, extra);
+        const ctx = ports.newRunContext(seed.runId, extra);
+        const refusal = portRefusal(ctx);
+        if (refusal)
+            return fail(refusal);
+        record(op, origin, target, true, `runId=${String(seed.runId ?? '(无)')}`);
+        return { ok: true, op, via: 'kernel-session-lifecycle', port: 'newRunContext', result: ctx };
+    }
+    catch (err) {
+        return fail(`端口抛错: ${String(err?.message ?? err).slice(0, 200)}`);
+    }
+}
+/**
+ * 需要**响亮失败**的调用方 (写不进 = 事实层面没发生) 在派发后调它。
+ *   与 `assertLifecycleOk` 同口径: 把 `{ok:false}` 变成抛, 而不是让调用方忘掉检查。
+ */
+export function assertSessionOk(out) {
+    if (!out.ok)
+        throw new Error(`[kernel-session-lifecycle] ${out.op} 失败: ${out.detail ?? '(无原因)'}`);
+}

package/dist/kernel/turn-selfcheck.js

@@ -0,0 +1,60 @@
+/**
+ * turn-selfcheck.ts — K10 余项: **回合收尾自检的编排与政策** (从 pi-sdk 的方法体搬进内核)
+ *
+ * 搬走的是**政策** (不是 I/O):
+ *   ① 该不该跑 —— 由纯规则 `decideTypecheck` 决定 (改过 TS 且本回合没跑过), 规则本体在 `code-write-gate.ts`;
+ *   ② **系统自检也过门** —— 它不是模型发起的工具调用 (args 恒空, 是本回合改过 TS 后的收尾自检),
+ *      但**更不能例外**: 例外一旦靠"没人知道它绕过"活着, 门就不再是唯一的执行咽喉;
+ *   ③ **fail-closed**: 门被拒 **或门本身抛错** ⇒ **不执行**, 且要**可见地报出来** (拒绝不许静默);
+ *   ④ 执行抛错 ⇒ 报一行"没能跑起来" (附"改动已落盘, 记得自己跑一次"), **绝不让自检失败影响回合结果**。
+ *
+ * 为什么归内核: 这三条都是**政策**, 不是某个入口的私事 —— 换入口 (CLI/Web/cron) 时不许各写一份。
+ * I/O 全部端口注入: 取工具 · 问门 · 上报 (emit)。本模块不 import 任何 agent 侧模块。
+ */
+import { decideTypecheck, formatTypecheckResult } from './code-write-gate.js';
+/** 自检用的工具名 (与工具注册表里的名字一致) */
+export const TURN_SELFCHECK_TOOL = 'tsc_check';
+/**
+ * 回合收尾自检 —— **唯一入口**。语义与迁移前逐条一致:
+ *   不需要跑 ⇒ `{decided:false}`; 工具缺失 ⇒ 安静地不做 (迁移前也是静默);
+ *   门拒/门抛 ⇒ 不执行 + **上屏一行"被拒, 未执行: 原因"**; 执行成功 ⇒ 上屏一行结果;
+ *   执行抛错 ⇒ 上屏一行"没能跑起来"。**本函数从不抛**。
+ */
+export async function runTurnEndSelfCheck(spec, ports) {
+    if (!decideTypecheck([...spec.touched], spec.ranThisTurn)) {
+        return { ran: false, decided: false, line: '' };
+    }
+    const toolName = spec.toolName ?? TURN_SELFCHECK_TOOL;
+    const tool = ports.getTool(toolName);
+    if (!tool?.execute) {
+        return { ran: false, decided: true, line: '', reason: `工具缺失: ${toolName}` };
+    }
+    try {
+        let allowed = true;
+        let why = '';
+        try {
+            const d = await ports.askGate({ tool: toolName, args: {} });
+            allowed = d?.allow === true;
+            why = String(d?.reason || d?.rejectedBy || d?.source || '');
+        }
+        catch (gateErr) {
+            allowed = false;
+            why = `harness-error: ${String(gateErr?.message || gateErr)}`;
+        }
+        if (!allowed) {
+            const line = `🔎 类型检查被门拒绝, 未执行: ${why.slice(0, 120)}`;
+            ports.emit({ type: 'status', content: line, tool: 'system' });
+            return { ran: false, decided: true, rejected: true, line, reason: why };
+        }
+        const r = (await tool.execute({}));
+        const passed = r?.success !== false && !/error TS\d+/.test(String(r?.output || ''));
+        const line = `🔎 ${formatTypecheckResult(passed, String(r?.output || ''))}`;
+        ports.emit({ type: 'status', content: line, tool: 'system' });
+        return { ran: true, decided: true, passed, line };
+    }
+    catch (e) {
+        const line = `🔎 类型检查没能跑起来: ${String(e?.message || e).slice(0, 100)} (改动已落盘, 记得自己跑一次)`;
+        ports.emit({ type: 'status', content: line, tool: 'system' });
+        return { ran: false, decided: true, line, reason: String(e?.message || e).slice(0, 120) };
+    }
+}

package/dist/llm/config-store.js

@@ -161,8 +161,8 @@ export const PROVIDER_INFO = {
     // 2026-07-17: V3 系列 (deepseek-chat / deepseek-reasoner) 官方已下线, 改 V4
     deepseek: { name: 'DeepSeek', description: '深度求索大模型 (V4)', requiresApiKey: true, models: ['deepseek-v4-flash', 'deepseek-v4-pro'] },
     kimi: { name: 'Kimi (月之暗面)', description: 'Moonshot Kimi K 系列模型', requiresApiKey: true, models: ['kimi-k3', 'kimi-k2-0905', 'moonshot-v1-128k', 'moonshot-v1-32k'] },
-    glm: { name: 'GLM (智谱)', description: '智谱 GLM 系列模型', requiresApiKey: true, models: ['glm-5.2', 'glm-4.6', 'glm-4.5', 'glm-4-flash', 'glm-4'] },
-    qwen: { name: 'Qwen (通义千问)', description: '阿里云通义千问系列', requiresApiKey: true, models: ['qwen3-max', 'qwen-max', 'qwen-plus', 'qwen-turbo'] },
+    glm: { name: 'GLM (智谱)', description: '智谱 GLM 系列模型', requiresApiKey: true, models: ['glm-5.3-flash', 'glm-5.3', 'glm-5.2', 'glm-5', 'glm-4.6', 'glm-4.5', 'glm-4.7', 'glm-4-flash', 'glm-4'] },
+    qwen: { name: 'Qwen (通义千问)', description: '阿里云通义千问系列', requiresApiKey: true, models: ['qwen3.8-max', 'qwen3-max', 'qwen-max', 'qwen-plus', 'qwen-turbo'] },
     mimo: { name: 'MiMo (小米)', description: '小米 MiMo V2 系列 (openai 兼容)', requiresApiKey: true, models: ['mimo-v2.5-pro', 'mimo-v2-pro', 'mimo-v2-omni', 'mimo-v2-flash', 'mimo-v2.5-pro-ultraspeed'] },
     grok: { name: 'Grok (xAI)', description: 'xAI Grok 系列模型 (openai 兼容)', requiresApiKey: true, models: ['grok-4.5', 'grok-4', 'grok-4-fast'] },
     local: { name: '本地模型', description: '本地部署的模型服务', requiresApiKey: false }

package/dist/llm/model-selection.js

@@ -763,7 +763,21 @@ export function validateSelection(req, ctx) {
         return { ok: false, failureClass: 'invalid_model', message: `${provider} 没有可用模型 (配置为空且默认模型为空)` };
     }
     let baseUrl = base.baseUrl;
-    if (req.baseUrl !== undefined) {
+    const urlAction = req.baseUrlAction ?? (req.baseUrl !== undefined ? 'replace' : 'keep');
+    if (urlAction === 'clear') {
+        // 清除 URL 覆盖 → 回落**官方默认** (内置表/注册表声明的那个, 不含配置里覆盖过的值)。
+        //   leo 2026-10-05: 「展示的 URL 默认需要官方的来源」—— 清除 = 回到官方, 不是回到上一个手填值。
+        const official = baseDefaultsOf(provider, null);
+        baseUrl = normalizeBaseUrl(official?.baseUrl || '');
+        if (!baseUrl && regEntry && regEntry.origin === 'catalog') {
+            return {
+                ok: false,
+                failureClass: 'invalid_url',
+                message: `${provider} 在目录里没有官方 api 基址 → 无法回落官方默认, 必须自定义 baseUrl (加 --base-url <地址> 或写进配置)`,
+            };
+        }
+    }
+    else if (req.baseUrl !== undefined) {
         const shape = validateBaseUrlShape(req.baseUrl);
         if (!shape.ok) {
             return { ok: false, failureClass: 'invalid_url', message: `base URL 非法 — ${shape.reason}` };
@@ -974,7 +988,7 @@ export async function selectModel(req) {
         const p = await runConnectionProbe({
             provider: target.provider,
             model: target.model,
-            baseUrl: req.baseUrl, // 显式 --base-url (最高优先)
+            baseUrl: target.baseUrl, // 校验已按 URL 意图算好 (keep=当前 / replace=新值 / clear=官方默认)
             configuredBaseUrl: stored?.baseUrl, // 配置里这一家现在写的地址
             apiKey: target.apiKey,
         });

package/dist/llm/pi-ai.js

@@ -752,7 +752,7 @@ export class PiAIModel {
             // 2026-07-17: deepseek-chat (V3) 官方已下线, 迁 deepseek-v4-flash
             deepseek: this.config.model || process.env.DEEPSEEK_MODEL || 'deepseek-v4-flash',
             kimi: this.config.model || process.env.KIMI_MODEL || process.env.MOONSHOT_MODEL || 'kimi-k3',
-            glm: this.config.model || process.env.GLM_MODEL || process.env.ZHIPU_MODEL || 'glm-5.2',
+            glm: this.config.model || process.env.GLM_MODEL || process.env.ZHIPU_MODEL || 'glm-5.3-flash',
             qwen: this.config.model || process.env.QWEN_MODEL || process.env.DASHSCOPE_MODEL || 'qwen3-max',
             // 小米 MiMo (openai 兼容) — env override 优先, 默认 mimo-v2.5-pro
             mimo: this.config.model || process.env.MIMO_MODEL || 'mimo-v2.5-pro',
@@ -1375,7 +1375,7 @@ function detectModel(provider) {
         // 2026-07-17: V3 官方下线, 迁 V4
         deepseek: 'deepseek-v4-flash',
         kimi: 'kimi-k3',
-        glm: 'glm-5.2',
+        glm: 'glm-5.3-flash',
         qwen: 'qwen3-max',
         // 小米 MiMo 默认走最新旗舰版 (v2.5-Pro); 2026-06 当前公开版
         mimo: 'mimo-v2.5-pro',

package/dist/orbitdb/cid-database.js

@@ -44,6 +44,42 @@ import * as os from 'os';
  * 2026-09-24: 原来 `openStoreByAddress` 失败返回 null, 上游 (gateway-group) 把它当"空群",
  * 于是"读不到"被显示成"没有消息"。改成**抛**: 打不开 ≠ 没内容。
  */
+/**
+ * **有界等待** (2026-10-02): 没有它时"打不开"会变成**永远卡住** ——
+ *   实测直接调 `createGroup` 的探针 300s 都没返回 (进程被强杀)。
+ *   超时抛出的错误**带卡点** (哪一步 · 等了多久), 上游才能给出可行动的话术。
+ */
+export async function withStageTimeout(stage, ms, p) {
+    let timer;
+    try {
+        return await Promise.race([
+            p,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`[orbitdb] ${stage} 超时 (${ms}ms) —— 这一步没能在预算内完成`)), ms);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * 把底层错误翻成**可行动的原因** (2026-10-02)。
+ *   最常见的两种原文都毫无提示: `Database failed to open` 与裸的 `ELOCKED` ——
+ *   真身几乎总是"**另一个 bolloon 实例正握着 keystore 单写锁**"(同机同 dataDir 只允许一个进程写)。
+ */
+export function describeOrbitDbFailure(err) {
+    // 有些底层库抛的是**没有 message 的对象** (只有 code, 如 `{ code: 'ELOCKED' }`) ⇒ 别让 String() 把它变成 `[object Object]`
+    const raw = String(err?.message ?? err?.code ?? err ?? '');
+    if (/Resource temporarily unavailable|ELOCKED|lock .*LOCK|Database failed to open/i.test(raw)) {
+        return 'OrbitDB 库被另一个进程占着 (同机同一 dataDir 只允许一个进程写; 常见原因: 另有一个 bolloon 实例在跑)。'
+            + ' 处理: 退出其它实例, 或设 `BOLLOON_HOME=<独立目录>` 跑一个隔离实例。原始错误: ' + raw.slice(0, 160);
+    }
+    if (/超时 \(\d+ms\)/.test(raw))
+        return raw.slice(0, 220);
+    return raw.slice(0, 200) || '未知原因';
+}
 export class OrbitDBStoreUnreachableError extends Error {
     address;
     cause;
@@ -65,6 +101,11 @@ export async function contentToCid(obj) {
     const hash = await sha256.digest(bytes);
     return CID.createV1(0x71, hash).toString();
 }
+/** 2026-10-02: 原始字节 → CID (raw 0x55 + sha256, 与 `contentToCid` 同一套内容寻址口径) */
+export async function bytesToCid(bytes) {
+    const hash = await sha256.digest(bytes);
+    return CID.createV1(0x55, hash).toString();
+}
 const home = () => process.env.HOME || os.homedir() || '/tmp';
 /**
  * OrbitDB 身份在 keystore 里的槽名 (2026-09-24)。
@@ -95,7 +136,13 @@ export class OrbitDBAdapter {
     db = null;
     _orbitdb = null;
     orbitdb;
-    constructor(dataDir = path.join(home(), '.bolloon', 'orbitdb')) {
+    /**
+     * 2026-10-02: **必须认 `BOLLOON_HOME`** —— 原来只走 `home()` (≈ `$HOME`)，于是
+     *   `BOLLOON_HOME=/tmp/x` 的"隔离运行"其实还在开**真实** `~/.bolloon/orbitdb/…`
+     *   (实测: 隔离 HOME 下报的锁路径是 `/Users/apple/.bolloon/…`) ⇒ 隔离失效、测试会写真实库。
+     *   与仓里其它模块同一口径: `${BOLLOON_HOME:-~/.bolloon}`。
+     */
+    constructor(dataDir = path.join(process.env.BOLLOON_HOME || path.join(home(), '.bolloon'), 'orbitdb')) {
         this.dataDir = dataDir;
     }
     /** 落盘位置 (未初始化时 null; 诊断/验收用) */
@@ -161,24 +208,32 @@ export class OrbitDBAdapter {
     async ensure() {
         if (this.db)
             return;
-        this.node = await createBolloonIpfs(path.join(this.dataDir, 'ipfs'));
-        // 2026-09-24: 身份必须**跨进程稳定**。不给 id 时 @orbitdb/core 用 createId()
-        // (32 位随机串) 当 keystore 槽名 (src/orbitdb.js:43 `id = id || await createId()`
-        // → :61 `createIdentity({ id })`) → 每个进程一对新密钥 → 新身份 → 写自己的 store
-        // 会被访问控制拒掉 ("Key … is not allowed to write to the log")。
-        // 给固定槽名后, 密钥从 <dataDir>/stores/keystore 读出复用 → 同 dataDir 同身份。
-        // 类型注: `id` 是 @orbitdb/core 的真选项 (src/orbitdb.js:33), 但 TS7 从 JS 推断出的
-        // 参数类型漏了它 → 显式取 Parameters<typeof createOrbitDB>[0] 再补 { id }
-        // (不裸 any 掉整个入参)。
-        const init = {
-            ipfs: this.node.helia,
-            directory: path.join(this.dataDir, 'stores'),
-            id: ORBITDB_IDENTITY_ID,
-        };
-        this._orbitdb = await createOrbitDB(init);
-        this.db = await this._orbitdb.open('bolloon-cid-store', { type: 'keyvalue' });
-        // 共享底层实例 (只读暴露)
-        this.orbitdb = this._orbitdb;
+        // 2026-10-02: 默认 20s/步 —— 可调; 目的是"卡住"必须变成**可判定的失败**, 不许无声挂死
+        const stageMs = Number(process.env.BOLLOON_ORBITDB_STAGE_TIMEOUT_MS || 20_000);
+        try {
+            this.node = await withStageTimeout('启动 IPFS/helia 节点', stageMs, createBolloonIpfs(path.join(this.dataDir, 'ipfs')));
+            // 2026-09-24: 身份必须**跨进程稳定**。不给 id 时 @orbitdb/core 用 createId()
+            // (32 位随机串) 当 keystore 槽名 (src/orbitdb.js:43 `id = id || await createId()`
+            // → :61 `createIdentity({ id })`) → 每个进程一对新密钥 → 新身份 → 写自己的 store
+            // 会被访问控制拒掉 ("Key … is not allowed to write to the log")。
+            // 给固定槽名后, 密钥从 <dataDir>/stores/keystore 读出复用 → 同 dataDir 同身份。
+            // 类型注: `id` 是 @orbitdb/core 的真选项 (src/orbitdb.js:33), 但 TS7 从 JS 推断出的
+            // 参数类型漏了它 → 显式取 Parameters<typeof createOrbitDB>[0] 再补 { id }
+            // (不裸 any 掉整个入参)。
+            const init = {
+                ipfs: this.node.helia,
+                directory: path.join(this.dataDir, 'stores'),
+                id: ORBITDB_IDENTITY_ID,
+            };
+            this._orbitdb = await withStageTimeout('创建 OrbitDB 实例 (含 keystore)', stageMs, createOrbitDB(init));
+            this.db = await withStageTimeout('打开 CID 库', stageMs, this._orbitdb.open('bolloon-cid-store', { type: 'keyvalue' }));
+            // 共享底层实例 (只读暴露)
+            this.orbitdb = this._orbitdb;
+        }
+        catch (e) {
+            // 打不开 ⇒ 一句**可行动**的话 (锁被谁占着 / 卡在哪一步), 不再让 "Database failed to open" 误导人
+            throw new Error(describeOrbitDbFailure(e), { cause: e });
+        }
     }
     async save(data) {
         await this.ensure();
@@ -263,6 +318,25 @@ export class OrbitDBAdapter {
         })
             .sort((a, b) => a.timestamp - b.timestamp);
     }
+    async putBytes(bytes) {
+        await this.ensure();
+        const cid = await bytesToCid(bytes);
+        await this.node.helia.blockstore.put(CID.parse(cid), bytes);
+        return { cid, bytes: bytes.length };
+    }
+    async getBytes(cid) {
+        await this.ensure();
+        try {
+            const stream = this.node.helia.blockstore.get(CID.parse(cid));
+            let out = new Uint8Array(0);
+            for await (const chunk of stream)
+                out = uint8Concat([out, chunk]);
+            return out;
+        }
+        catch {
+            return null;
+        }
+    }
     async share(cid) {
         await this.ensure();
         const rec = await this.load(cid);
@@ -283,6 +357,8 @@ export class OrbitDBAdapter {
                 // events store 的 all() 返回 { hash, payload } — 统一成 { key, value }
                 return entries.map(e => ({
                     key: String(e.key ?? e.hash ?? ''),
+                    // 2026-10-02: 条目自带的 hash/id **透出来** —— 回复某条 / 建分支要的锚点 (拿不到才留空, 不假造)
+                    id: String((e.hash ?? e.id ?? e.payload?.key ?? '') || ''),
                     value: e.payload !== undefined ? e.payload : e.value,
                 }));
             },

package/dist/web/bolloon-web.json

@@ -1,10 +1,10 @@
 {
   "schema": "bolloon-mobile-web/1",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "channel": "stable",
   "build": "stable",
-  "commit": "18c1afa87b36043e6df5dc9ccef0417cdcf323da",
-  "builtAt": "2026-10-04T08:01:30.567Z",
+  "commit": "eb3ebe6fed23cb70e901ac8da92e6420bc0673ad",
+  "builtAt": "2026-10-05T06:24:49.679Z",
   "layer": "web",
   "note": "web 资源层构建戳 (手机端 OTA 的身份第 ③ 级回退; 装机后以 OTA state.json 为准)"
 }

package/dist/web/sw.js

@@ -6,7 +6,7 @@
  * 现在: 代码类资源 (html/js/css/json) 一律 **network-first** (拿不到网才回退缓存),
  *   缓存名带版本号, activate 时清掉所有旧缓存; 图标等静态资源仍 cache-first。
  */
-const CACHE = 'bolloon-mobile-v0.6.1';
+const CACHE = 'bolloon-mobile-v0.6.3';
 const SHELL = [
   './mobile.html',
   './mobile.css',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bolloon/bolloon-agent",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "type": "module",
   "description": "P2P AI Document Agent - 全局安装后执行 `bolloon` 启动产品",
   "main": "dist/cli-entry.js",