@bolloon/bolloon-agent 0.5.2 → 0.5.4

package/dist/cli/input-history.js

@@ -0,0 +1,119 @@
+/**
+ * input-history.ts — 输入历史落盘 (leo 2026-09-30: 「输入历史有落盘文件夹吗，要实现一下」)
+ *
+ * 之前: 历史只在内存 (`ink-app.tsx` 的 historyRef, 上限 100, **重启即失**)。
+ * 现在: 落 `~/.bolloon/history/`, **一渠道一文件** `input-<channelId>.jsonl` (0600) ——
+ *   渠道隔离 (不同 agent/channel 的输入不该互相串), 重启后 ↑ 还能翻出来。
+ *
+ * 四条纪律:
+ *   1. **秘密不入历史** —— 64 位 hex 私钥 / `privateKey` / 助记词形态 (12+ 个小写词) 一律不写盘。
+ *      输入历史是纯文本、会被翻出来、也可能被贴出去; 钱包助记词进去就是事故。
+ *   2. **不打断输入** —— 落盘失败只记日志 (console.error), 绝不让打字报错。
+ *   3. **去重** —— 连续重复的同一行不重复写 (↑ 翻起来不烦)。
+ *   4. **有上限** —— 内存 200 / 文件 500 (超了重写成最后 500, 原子写)。
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+/** 内存里最多留多少条 (CLI 进程内) */
+export const MEMORY_CAP = 200;
+/** 文件里最多留多少条 (超了裁剪) */
+export const FILE_CAP = 500;
+let scope = 'default';
+/** 由 CLI 在切渠道时调用 (index.ts), 决定写哪个文件 */
+export function setHistoryScope(channel) {
+    scope = sanitizeChannel(channel) || 'default';
+}
+export function historyScope() { return scope; }
+function sanitizeChannel(channel) {
+    return String(channel || '').replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 64);
+}
+export function historyDir() {
+    return path.join(process.env.HOME || '/tmp', '.bolloon', 'history');
+}
+export function historyFile(channel) {
+    const ch = sanitizeChannel(channel) || scope || 'default';
+    return path.join(historyDir(), `input-${ch}.jsonl`);
+}
+/**
+ * 看着像秘密的输入 —— **不写历史**。
+ * 判据刻意保守 (宁可漏存一条普通输入, 也不能把私钥/助记词写进历史文件):
+ *   · 64 位 hex (可带 0x) / 40 位 hex 地址不拦 (地址是公开的)
+ *   · 出现 privateKey / private_key / mnemonic / 助记词 字样
+ *   · 12 个以上连续小写单词 (助记词形态)
+ */
+export function looksSecret(line) {
+    const s = String(line || '');
+    if (/0x[0-9a-fA-F]{64}\b/.test(s))
+        return true;
+    if (/\b(privateKey|private_key|mnemonic|助记词|seedPhrase|seed_phrase)\b/i.test(s))
+        return true;
+    // 助记词形态: 整行 (去掉常见前缀/标点) 是 12/15/18/21/24 个小写词
+    const words = s.replace(/^[^A-Za-z]*/, '').trim().split(/\s+/);
+    if (words.length >= 12 && words.length <= 30 && words.every(w => /^[a-z]{3,8}$/.test(w)))
+        return true;
+    return false;
+}
+/** 读历史 (新→旧? 不, 这里按**旧→新**返回: 与内存数组同序, ↑ 取最后一条) */
+export async function loadInputHistory(channel) {
+    try {
+        const text = await fs.readFile(historyFile(channel), 'utf-8');
+        const out = [];
+        for (const raw of text.split('\n')) {
+            const line = raw.trim();
+            if (!line)
+                continue;
+            try {
+                const v = JSON.parse(line);
+                if (typeof v === 'string' && v.trim())
+                    out.push(v);
+            }
+            catch { /* 坏行跳过 (历史坏了不该让 CLI 起不来) */ }
+        }
+        return out.slice(-MEMORY_CAP);
+    }
+    catch (e) {
+        if (e?.code === 'ENOENT')
+            return [];
+        console.error(`[input-history] 读不了 ${historyFile(channel)}: ${String(e?.message || e).slice(0, 120)}`);
+        return [];
+    }
+}
+/**
+ * 追加一条 (去重: 与最后一条相同则不写)。
+ * 返回 true = 真写了; false = 跳过了 (秘密/空/重复) —— 调用方可以据此决定是否提示。
+ */
+export async function appendInputHistory(line, channel) {
+    const v = String(line || '').trim();
+    if (!v)
+        return false;
+    if (looksSecret(v)) {
+        console.error(`[input-history] 这行看着像密钥/助记词, **不写历史** (长度 ${v.length})`);
+        return false;
+    }
+    const file = historyFile(channel);
+    try {
+        await fs.mkdir(historyDir(), { recursive: true });
+        // 去重: 看最后一条
+        const existing = await loadInputHistory(channel);
+        if (existing.length && existing[existing.length - 1] === v)
+            return false;
+        await fs.appendFile(file, JSON.stringify(v) + '\n', { encoding: 'utf-8', mode: 0o600 });
+        try {
+            await fs.chmod(file, 0o600);
+        }
+        catch { /* 已足够 */ }
+        if (existing.length + 1 > FILE_CAP + 300) {
+            // 裁剪: 原子重写成最后 FILE_CAP 条
+            const kept = [...existing, v].slice(-FILE_CAP);
+            const tmp = `${file}.tmp`;
+            await fs.writeFile(tmp, kept.map(x => JSON.stringify(x) + '\n').join(''), { encoding: 'utf-8', mode: 0o600 });
+            await fs.rename(tmp, file);
+        }
+        return true;
+    }
+    catch (e) {
+        // 不打断输入: 只记日志
+        console.error(`[input-history] 写不了 ${file}: ${String(e?.message || e).slice(0, 120)}`);
+        return false;
+    }
+}

package/dist/cli/loading-tui.js

@@ -71,6 +71,17 @@ export const BOLLOON_BANNER = [
     `${C_TEXT}${BOLD}╚═════╝  ╚═════╝ ╚══════╝╚══════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═══╝${RESET}`,
     `${C_DIM}Bolloon Agent v${BOLLOON_VERSION}${RESET}`,
 ].join('\n');
+/**
+ * 窄终端档: 同一套风格的小号艺术字 (leo 2026-09-30: 「我看不到我的 logo」).
+ *   原来宽 < ~97 列时整块 87 列艺术字被丢掉、只剩一行文字 —— 那不是 logo.
+ *   现在按"装得下就上"挑档: 大(87) → 小(37) → 文字(兜底), 保证任何宽度都有字标.
+ */
+export const BOLLOON_BANNER_SMALL = [
+    `${C_TEXT}${BOLD} ___  ___  _    _    ___   ___  _  _${RESET}`,
+    `${C_TEXT}${BOLD}| _ )/ _ \\| |  | |  / _ \\ / _ \\| \\| |${RESET}`,
+    `${C_TEXT}${BOLD}| _ \\ (_) | |__| |_| (_) | (_) | .\` |${RESET}`,
+    `${C_TEXT}${BOLD}|___/\\___/|____|____\\___/ \\___/|_|\\_|${RESET}`,
+].join('\n');
 /** 艺术字全部行 (机器人头在左, BOLLOON 艺术字在右), 供框内渲染 */
 export function brandArtLines() {
     // 2026-08-09: icon 只取机器人头 (裁掉末行 BOLLOON 文字), 避免和右侧 banner 双 logo
@@ -114,6 +125,52 @@ export function termWidth() {
     const c = process.stdout.columns;
     return typeof c === 'number' && c > 24 ? c : 80;
 }
+/**
+ * 等真实终端尺寸就位 (2026-09-30, leo 报「TUI 渲染有问题: 顶框被重复打印 + 宽度一路涨」).
+ *
+ * 真 pty 下 `process.stdout.columns` 在启动最初那一刻可能**还没被写进来** ⇒ 面板先按兜底的 80 列
+ * 渲染一次; 等真尺寸到位后又渲染一次 —— 而面板落在 Ink 的静态输出(scrollback)里, 重画覆盖不掉旧内容,
+ * 于是**每渲染一次就多留一条顶框**, 宽度还在变 (实测 24x120: 110 → 120; 12x80: 80 → 76).
+ * 所以: 出任何一帧之前先等尺寸就位 (通常下一个 tick 或一次 resize 事件就到; 上限 timeoutMs).
+ */
+export async function waitForTermSize(timeoutMs = 600) {
+    const ok = () => {
+        const c = process.stdout.columns;
+        return typeof c === 'number' && c > 24;
+    };
+    if (ok())
+        return;
+    await new Promise((resolve) => {
+        let done = false;
+        const finish = () => {
+            if (done)
+                return;
+            done = true;
+            clearInterval(iv);
+            clearTimeout(t);
+            try {
+                process.stdout.off('resize', finish);
+            }
+            catch { /* 老 Node 没有 off */ }
+            resolve();
+        };
+        const iv = setInterval(() => { if (ok())
+            finish(); }, 20);
+        const t = setTimeout(finish, timeoutMs);
+        try {
+            process.stdout.once('resize', finish);
+        }
+        catch { /* 忽略 */ }
+    });
+}
+/**
+ * 终端行数 (拿不到就按 24 —— 与 termWidth 同一套兜底口径).
+ * 2026-09-30 新增: 面板/盒子必须**知道自己有多少行可用**, 否则会长过屏幕把输入行顶出视野.
+ */
+export function termHeight() {
+    const r = process.stdout.rows;
+    return typeof r === 'number' && r > 8 ? r : 24;
+}
 function stripAnsi(s) {
     return s.replace(/\x1b\[[0-9;]*m/g, '');
 }
@@ -160,8 +217,8 @@ function fitLeft(text, inner) {
     }
     return out + '…';
 }
-/** 按显示宽度截断并加省略号 */
-function truncate(text, max) {
+/** 按显示宽度截断并加省略号 (导出: 调用方要自己把内容裁进盒子, 见 buildBootBox) */
+export function truncate(text, max) {
     if (dispWidth(text) <= max)
         return text;
     let out = '';
@@ -201,12 +258,15 @@ export function renderDashboard(opts) {
     const maxTitle = dispWidth(opts.title ?? 'Bolloon Agent · 仪表盘') + 4;
     const inner = Math.max(40, maxArt, maxRow, maxTitle);
     const width = Math.min(termWidth() - 2, opts.width ?? inner + 4);
+    // 2026-09-30: width 被夹到 termWidth()-2 之后, 内宽可能**小于**艺术字宽度 ——
+    //   那种情况下 boxRow 装不下, 终端会把每行折成两截 (实测: 艺术字裂成两列错位).
+    //   宁可不显示艺术字, 也不让它被折行.
+    const innerW = Math.max(0, width - 4);
+    const useArt = showBrand && maxArt <= innerW ? art : [];
     const lines = [];
     lines.push(boxTop(opts.title ?? 'Bolloon Agent · 仪表盘', width));
-    if (showBrand) {
-        for (const l of art)
-            lines.push(boxRow(l, width, 'center'));
-    }
+    for (const l of useArt)
+        lines.push(boxRow(l, width, 'center'));
     for (const r of opts.rows) {
         const sym = STATUS_SYMBOL[r.status ?? 'info'];
         const detail = r.detail ? `  ${C_DIM}${r.detail}${RESET}` : '';

package/dist/cli/log-gate.js

@@ -79,11 +79,49 @@ export function isStartupLogLine(line) {
         || UNTAGGED_STARTUP_NARRATION.some((re) => re.test(line));
     // inspect dump 的续行 (纯数字/逗号) 由 filterText 的 dump 状态机处理, 这里不判
 }
+/**
+ * 「可选启动富化」任务的失败 —— **落日志, 但默认不占屏**。
+ *
+ * 2026-09-30 (leo: 「都是启动期可选富化任务失败, 却用带时间戳的'失败'打在屏上」):
+ *   `[warn]: ⚠️ 本地 IPNS 发布失败: TimeoutError … ❌ 失败 (30003ms)` 这类来自 SDK / 内部后台任务,
+ *   用户启动时**无可行动**(看见了也没法处理), 但句子带'失败' ⇒ 按'错误不许被吞'被放上屏 = 纯噪音。
+ *   它们仍然**一字不漏落 startup.log**, `--verbose` 照原样上屏 ⇒ 诊断能力一点不丢。
+ *   这是把「要不要占屏」和「要不要留痕」分开, 不是把错误藏起来。
+ *
+ * 判据要求**同时**命中「上面这条窄规则」+「失败词」; 只命中一个照旧按人味信号上报。
+ *   **刻意只覆盖这两类**: SDK 的 IPNS 发布重试行 + 上下文扫描超时。
+ *   不收 `ipfs daemon 启动超时, 可稍后手动运行` 这类**可行动**提示 —— 门自己的契约测试
+ *   (`log-gate.test.ts` 的"信号行"用例) 就是拿它当反例, 第一版规则太宽时被它判红。
+ */
+const OPTIONAL_BOOT_TASK = /(?:本地\s*IPNS\s*发布失败|IPNS\s*发布失败[，,]\s*尝试备用发布|上下文扫描\s*未完成|上下文扫描\s*超时|Bolloon 上下文扫描)/;
+/**
+ * SDK(winston) 的**进度诊断**行形状: `2026-09-30T09:27:03.848Z [info]: 结果: ❌ 失败 (30004ms)`。
+ *
+ * 2026-09-30 (leo): 这类行来自 @diap/sdk 的 logger —— 它**直写控制台、绕过日志门**, 句子里带
+ *   "失败/❌" ⇒ 按"错误不许被吞"被放上屏, 但它是 `[info]` 级**进度尾巴**(IPNS 发布 30s 超时), 启动时不可行动。
+ *
+ * **只吞 info/debug, 绝不吞 warn/error** —— 这条收窄是门自己的契约测试逼出来的:
+ *   `log-gate.test.ts` 断言 `… [warn]: ⚠️ 守护进程启动超时, 可稍后手动运行 ipfs daemon` 必须算人味信号
+ *   (它确实可行动)。第一版规则连 warn 一起吞 ⇒ 被那条测试判红, 于是收窄。
+ */
+// 2026-09-30 真机修正: 原来只认"以 ISO 时间戳开头 + 未染色的 [info]:"。
+//   实测真身是 `[2026-…] 2026-…Z [info]: …` —— 行首可能有日志器加的 `[ts] ` 前缀,
+//   `[info]` 里的 info 还会被 ANSI 染色 ⇒ 两条都让旧规则漏网, 于是
+//   `2026-09-30T10:22:44.768Z [info]:   结果: ❌ 失败 (30004ms)` 照样上屏 (leo 报过多次)。
+const SDK_DIAG_LINE = /^(?:\[[^\]]*\]\s*)?\d{4}-\d{2}-\d{2}T[\d:.]+Z?\s*\[(?:\x1b\[[0-9;]*m)*(?:info|debug)(?:\x1b\[[0-9;]*m)*\]:/i;
 /** 这一行是不是「错误 / 降级 / 需人介入」—— 是则任何模式下都不许被静默 */
 export function carriesHumanSignal(line) {
     if (!line)
         return false;
-    return HUMAN_SIGNAL.test(line.replace(BENIGN_COUNT, ' '));
+    const l = line.replace(BENIGN_COUNT, ' ');
+    const isSignal = HUMAN_SIGNAL.test(l);
+    // SDK 诊断行 (info/warn/debug): 只落日志, 不占屏 —— error 级不在其中, 照旧上报
+    if (SDK_DIAG_LINE.test(l))
+        return false;
+    // 可选启动富化的失败: 留痕(日志)但默认不占屏 —— 见 OPTIONAL_BOOT_TASK 的说明
+    if (isSignal && OPTIONAL_BOOT_TASK.test(l))
+        return false;
+    return isSignal;
 }
 // ---------------------------------------------------------------------------
 // verbose / disabled / 日志路径

package/dist/cli/protocol-envelope.js

@@ -75,6 +75,10 @@ const OPTIONS_WITH_VALUE = new Set([
     '--announcement-id',
     // 2026-09-23 (C7): 群聊通道 `bolloon task announce|trail|post` 的群链接/groupId + 极短事实字段
     '--group', '--round', '--criteria', '--kind', '--hash', '--bytes', '--checks', '--verdict', '--limit', '--from',
+    // 2026-09-29: `bolloon identity bind-address|bindings` 的显式路径与声明字段
+    //   (名字先查过全仓: `--address/--label/--out/--chain-id/--bindings-dir/--address-key-file/--did-key-file/--expires-at`
+    //    在其他 cli-entry 命令里都没有被当布尔开关用过 ⇒ 加进"带值选项"不会改变既有解析)
+    '--address', '--label', '--out', '--chain-id', '--bindings-dir', '--address-key-file', '--did-key-file', '--expires-at',
 ]);
 export function parseFlags(args) {
     const flags = { json: false, quiet: false, positionals: [], options: new Map(), raw: args };

package/dist/cli/session-summary.js

@@ -0,0 +1,129 @@
+/**
+ * session-summary.ts — 用 AI 给**会话**起标题 + 一句话摘要 (leo 2026-09-30)
+ *
+ * 起因: `/sessions` 表格里 Title 那列原来只能显示会话 key (`20260930_171712_840093`),
+ *   Preview 常常是 `—` —— leo: 「Title, Preview 要有内容, 使用 AI 来总结进去」。
+ *
+ * 三条纪律:
+ *   1. **只算一次** —— 结果写回会话文件 `metadata.{title,preview,summarizedAt}`; 下次直接读, 不再花钱。
+ *   2. **不编** —— AI 不可用/输出不合规时, 退回"真实首条用户消息"当 preview, title 保持 key,
+ *      并把 `source` 如实标出来 (调用方据此决定要不要提示用户)。
+ *   3. **不卡** —— 单条会话有超时 (默认 12s), 失败不留半截标题 (整条要么写成功要么不写)。
+ */
+import { SessionStore } from '../agents/session-store.js';
+import { getMinimax } from '../llm/pi-ai.js';
+/**
+ * 自动注入的上下文块 (不是用户说的话)。
+ *   ⚠ 2026-09-30 真机发现 (leo: 「结束进程的时候没有加载 title 和总结」): CLI 把**用户那句话
+ *   **附在注入块末尾**, 用 `\n---\n` 分隔 —— 实测长这样:
+ *       <!-- current-turn: … -->
+ *       # 你的项目上下文 (自动 bootstrap …)
+ *       … [预算截断]
+ *
+ *       ---
+ *
+ *       你好
+ *   ⇒ 整块丢掉的话, 所有 CLI 会话都"没有用户内容" (标题永远出不来)。
+ *   正确做法: **取末尾那一段**当用户输入 (见 userTextFrom), 只把真正的上下文头当注入。
+ */
+const isInjected = (x) => /^<!--/.test(x.trim()) || /^#\s*你的项目上下文/.test(x.trim()) || /^\[cron\]/.test(x.trim()) || /^<!-- current-turn/.test(x.trim());
+/**
+ * 从一条 user 消息里取"真正属于用户的那句话":
+ *   · 普通消息 → 原样
+ *   · 注入块 → 取最后一个 `---` 分隔线之后的尾巴 (那是用户的输入)
+ *   · 拿不到有效尾巴 (还是上下文/太短) → 返回空串 (调用方跳过)
+ */
+export function userTextFrom(content) {
+    const c = String(content || '').trim();
+    if (!c)
+        return '';
+    if (!isInjected(c))
+        return c;
+    const parts = c.split(/\n\s*-{3,}\s*\n/);
+    const tail = (parts[parts.length - 1] || '').trim();
+    if (!tail || isInjected(tail))
+        return '';
+    // 尾巴太短 (一两个字符) 多半是分隔符残渣, 不算用户内容
+    return tail.length >= 2 ? tail : '';
+}
+const clip = (s, n) => s.replace(/\s+/g, ' ').trim().slice(0, n);
+const SYS = '你是终端会话的命名器。只输出一行 JSON, 不要解释、不要代码块、不要多余文字。';
+const buildPrompt = (head, tail) => `下面是同一个终端会话的「开头」和「结尾」。请用中文输出一行 JSON:\n` +
+    `{"title":"不超过 20 个字的标题, 说清这次会话在做什么", "preview":"不超过 40 个字, 一句话摘要, 最有信息量的那件事"}\n\n` +
+    `【开头】\n${head}\n\n【结尾】\n${tail}\n`;
+/** 从模型输出里抠出第一个 JSON 对象 (抗代码块/前后废话) */
+function parseDigest(raw) {
+    const m = raw.match(/\{[\s\S]*?\}/);
+    if (!m)
+        return null;
+    try {
+        const o = JSON.parse(m[0]);
+        const title = clip(String(o.title ?? ''), 28);
+        const preview = clip(String(o.preview ?? ''), 56);
+        if (!title)
+            return null;
+        return { title, preview };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 给一条会话生成标题 + 摘要。已经算过 (metadata.title) 就直接返回, 不再调模型。
+ * 失败时不抛错 —— 返回 raw/none, 让调用方如实显示。
+ */
+export async function summarizeSession(key, opts = {}) {
+    const store = opts.store ?? new SessionStore();
+    let msgs = [];
+    let meta = {};
+    try {
+        const raw = JSON.parse(await (await import('fs/promises')).readFile(store.pathFor(key), 'utf-8'));
+        msgs = Array.isArray(raw) ? raw : (raw?.messages || []);
+        meta = (!Array.isArray(raw) && raw?.metadata) || {};
+    }
+    catch {
+        return { title: key, preview: '', source: 'none' };
+    }
+    if (!opts.force && typeof meta.title === 'string' && meta.title.trim()) {
+        return { title: String(meta.title), preview: String(meta.preview ?? ''), source: 'ai' };
+    }
+    // 2026-09-30: 用 userTextFrom 而不是"整块丢掉" —— 用户的话在注入块末尾 (见上面注释)
+    const userTexts = msgs
+        .filter(m => m?.role === 'user' && typeof m.content === 'string')
+        .map(m => userTextFrom(String(m.content)))
+        .filter(t => t.length > 0);
+    const userMsgs = userTexts.map(t => ({ content: t }));
+    const rawPreview = userMsgs.length ? clip(String(userMsgs[0].content), 56) : '';
+    if (!userMsgs.length)
+        return { title: key, preview: '', source: 'none' };
+    const head = userMsgs.slice(0, 2).map(m => clip(String(m.content), 300)).join('\n');
+    const tailFrom = msgs.filter(m => typeof m?.content === 'string' && m.content.trim()).slice(-2);
+    const tail = tailFrom.map(m => `${m.role}: ${clip(String(m.content), 300)}`).join('\n');
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), Math.max(2000, opts.timeoutMs ?? 12_000));
+    try {
+        const llm = getMinimax();
+        const res = await llm.chat(buildPrompt(head, tail), SYS, ac.signal, undefined, 'auto-compact', 'session-summary');
+        // 2026-09-30 实测: chat() 返回的是**对象** `{reply, reasoningContent, toolCalls, messages, usage}`
+        //   —— 文本在 `reply` (第一版写成 String(raw) ⇒ 拿到 "[object Object]" ⇒ 总结永远退回 raw)。
+        const text = typeof res === 'string'
+            ? res
+            : String(res?.reply ?? res?.content ?? res?.text ?? '');
+        const parsed = parseDigest(text);
+        if (parsed) {
+            // 整条写回 (要么全写, 要么不写) —— 下次 /sessions 直接读, 不再调模型
+            try {
+                await store.updateMetadata(key, { title: parsed.title, preview: parsed.preview, summarizedAt: Date.now() });
+            }
+            catch { /* 写不进也不影响这次显示 */ }
+            return { title: parsed.title, preview: parsed.preview, source: 'ai' };
+        }
+        return { title: key, preview: rawPreview, source: 'raw' };
+    }
+    catch {
+        return { title: key, preview: rawPreview, source: 'raw' };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/cli/session-tree.js

@@ -0,0 +1,141 @@
+/**
+ * session-tree.ts — 会话树: 用 git 管理 fork 分支 (leo 2026-09-30)
+ *
+ * 语义 (leo 确认, 标准 branch 语义):
+ *   · `/fork <#|id>` 从某条会话**分叉出一条新会话**: 新会话**继承 fork 点之前的全部历史**,
+ *     之后两条各自独立 (各自继续写自己的文件)。
+ *   · 树用 **git** 管: `~/.bolloon/sessions/` 变成一个仓库, 每次 fork / 退出存档 = 一次 commit,
+ *     commit 里带 `session: <key>` 与 `parent: <源 key>` ⇒ `git log --graph` 就是会话树。
+ *
+ * 三条纪律:
+ *   1. **不吞 git 的输出** —— 成功给 commit 短哈希, 失败给原因 (调用方如实显示)。
+ *   2. **仓库是用户的会话历史** —— 只 init (无仓库时) + add/commit; **绝不** reset/checkout/clean。
+ *   3. **不阻塞对话** —— git 不可用/失败时, fork 本身仍然成功 (文件已写好), 只是树没记上, 如实标注。
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+const pexec = promisify(execFile);
+/** 会话仓库根 = sessions 目录 (里面 cache/ 与 channels.json 都进树) */
+function repoDir(store) {
+    return path.dirname(store.dir);
+}
+async function git(cwd, args) {
+    try {
+        const { stdout, stderr } = await pexec('git', args, { cwd, timeout: 20_000, maxBuffer: 8 * 1024 * 1024 });
+        return { ok: true, out: String(stdout), err: String(stderr) };
+    }
+    catch (e) {
+        return { ok: false, out: String(e?.stdout || ''), err: String(e?.stderr || e?.message || e).slice(0, 300) };
+    }
+}
+/** 仓库不存在就建 (并设本地 user.name/email, 不依赖用户全局 git 配置) */
+export async function ensureTree(store) {
+    const dir = repoDir(store);
+    try {
+        await fs.mkdir(dir, { recursive: true });
+    }
+    catch { /* 已存在 */ }
+    const inside = await git(dir, ['rev-parse', '--git-dir']);
+    if (!inside.ok) {
+        const init = await git(dir, ['init', '-q', '-b', 'main']);
+        if (!init.ok)
+            return { ok: false, error: `git init 失败: ${init.err}` };
+        await git(dir, ['config', 'user.name', 'bolloon']);
+        await git(dir, ['config', 'user.email', 'bolloon@localhost']);
+        // 忽略半截临时文件 (session-store 的原子写会留 .tmp 一瞬间)
+        try {
+            await fs.writeFile(path.join(dir, '.gitignore'), '*.tmp\n', { flag: 'wx' });
+        }
+        catch { /* 已存在 */ }
+    }
+    return { ok: true };
+}
+/**
+ * 把当前状态提交进树。
+ * @param subject 形如 `session: <key> · fork from <src>` —— 树里一眼能看出发生了什么
+ */
+export async function commitTree(store, subject, body) {
+    const ens = await ensureTree(store);
+    if (!ens.ok)
+        return ens;
+    const dir = repoDir(store);
+    const add = await git(dir, ['add', '-A', '--', '.']);
+    if (!add.ok)
+        return { ok: false, error: `git add 失败: ${add.err}` };
+    const args = ['commit', '-q', '--no-verify', '-m', subject];
+    if (body)
+        args.push('-m', body);
+    const c = await git(dir, args);
+    if (!c.ok) {
+        // 没有变化 (nothing to commit) 不算失败 —— 如实区分
+        if (/nothing to commit|no changes added/i.test(c.err) || /nothing to commit/i.test(c.out))
+            return { ok: true, commit: '(无变化)' };
+        return { ok: false, error: `git commit 失败: ${c.err}` };
+    }
+    const rev = await git(dir, ['rev-parse', '--short', 'HEAD']);
+    return { ok: true, commit: rev.ok ? rev.out.trim() : '' };
+}
+/**
+ * fork 一条会话: 继承 fork 点之前的全部历史 + 记 parent 关系 + 落一次 commit。
+ * 标准 branch 语义: 之后两条会话各自独立 (各写各的文件)。
+ */
+export async function forkSession(store, srcKey) {
+    let raw;
+    let srcPath = '';
+    for (const cand of [store.pathFor(srcKey), path.join(store.dir, `${srcKey}.json`)]) {
+        try {
+            raw = JSON.parse(await fs.readFile(cand, 'utf-8'));
+            srcPath = cand;
+            break;
+        }
+        catch { /* 试下一个 */ }
+    }
+    if (!raw)
+        return { ok: false, error: `源会话读不到: ${srcKey}` };
+    const msgs = Array.isArray(raw) ? raw : (raw?.messages || []);
+    const ts = new Date();
+    const p = (n) => String(n).padStart(2, '0');
+    const base = `${ts.getFullYear()}${p(ts.getMonth() + 1)}${p(ts.getDate())}_${p(ts.getHours())}${p(ts.getMinutes())}${p(ts.getSeconds())}`;
+    let newKey = `${base}_fork`;
+    for (let i = 2; i < 50; i++) {
+        try {
+            await fs.access(store.pathFor(newKey));
+            newKey = `${base}_fork${i}`;
+        }
+        catch {
+            break;
+        }
+    }
+    const out = {
+        key: newKey,
+        messages: msgs, // ← 共享 fork 点之前的全部历史 (标准 branch 语义)
+        metadata: {
+            ...(Array.isArray(raw) ? {} : (raw?.metadata || {})),
+            forkedFrom: srcKey,
+            forkPoint: msgs.length,
+            forkedAt: Date.now(),
+            savedAt: Date.now(),
+            cwd: process.cwd(),
+            totalCount: msgs.length,
+            // 继承来的标题加前缀, /sessions 里一眼看出它是分支
+            title: `↳ ${String((Array.isArray(raw) ? {} : raw?.metadata?.title) || srcKey)}`,
+            preview: `从 ${srcKey} 分叉 (fork 点 ${msgs.length} 条)`,
+        },
+    };
+    await fs.writeFile(store.pathFor(newKey), JSON.stringify(out, null, 2), 'utf-8');
+    const committed = await commitTree(store, `session: ${newKey} · fork from ${srcKey} @${msgs.length}`, `fork 点: ${msgs.length} 条消息\n源文件: ${path.relative(repoDir(store), srcPath) || srcKey}`);
+    return { ...committed, newKey, inherited: msgs.length, from: srcKey };
+}
+/** 会话树概览 (给 `/fork --tree` / 诊断用): 最近 N 次提交 + 分支名 */
+export async function treeLog(store, limit = 12) {
+    const ens = await ensureTree(store);
+    if (!ens.ok)
+        return { ok: false, text: '', error: ens.error };
+    const dir = repoDir(store);
+    const log = await git(dir, ['log', `-n${Math.max(1, limit)}`, '--pretty=format:%h %ad | %s', '--date=format:%m-%d %H:%M']);
+    if (!log.ok)
+        return { ok: false, text: '', error: log.err };
+    return { ok: true, text: log.out };
+}

package/dist/cli/status-segments.js

@@ -0,0 +1,70 @@
+import { dispWidth } from './loading-tui.js';
+/** 字节 → token 的估算比 (只有这一步是估, 所以显示时标 ≈) */
+export const BYTES_PER_TOKEN = 3.5;
+/** 返回"标签 值"对 (无 ANSI, 调用方拼颜色) —— 顺序: ◷ ↑ ⚙ ✓ */
+export function statusSegments(f) {
+    const out = [];
+    if (f.running) {
+        const secs = Math.max(0.1, f.turnElapsedMs / 1000);
+        out.push(`◷ ${secs.toFixed(1)}s`);
+        const ti = f.aiTiming;
+        if (ti && ti.ms > 0 && ti.bytes > 0 && (!f.turnStartedAt || ti.at >= f.turnStartedAt)) {
+            const tps = Math.round(ti.bytes / BYTES_PER_TOKEN / (ti.ms / 1000));
+            if (tps > 0)
+                out.push(`↑ ≈${tps} t/s`);
+        }
+    }
+    else if (f.lastTurnMs > 0) {
+        out.push(`✓ ${(f.lastTurnMs / 1000).toFixed(1)}s`);
+        if (f.lastTurnReplyBytes > 0) {
+            const tps = Math.round(f.lastTurnReplyBytes / BYTES_PER_TOKEN / Math.max(0.1, f.lastTurnMs / 1000));
+            if (tps > 0)
+                out.push(`↑ ≈${tps} t/s`);
+        }
+    }
+    // ◎ 缓存命中率 = cached / prompt (provider 给的实测值; 没记录/没 prompt 就不显示)
+    const u = f.aiUsage;
+    if (u && u.prompt > 0) {
+        const pct = (u.cached / u.prompt) * 100;
+        out.push(`◎ ${pct.toFixed(1)}%`);
+    }
+    out.push(`⚙ ${f.toolCount}`); // 常显
+    // 会话 Title 不在这里拼 —— leo: 「这个 title 需要顶格右侧」⇒ 由 CLI 右对齐 (见 rightAlignPad)。
+    return out;
+}
+/**
+ * 按可用宽度取舍 (2026-09-30, 真机抓包照出来的问题):
+ *   整行 ~130 字符, 112 列终端里**右边的段直接被截掉** ⇒ 看着像"没出现"。
+ *   规则: 丢的顺序 = ↑ → ◎ → ✓ → ◷ (⚙ 永不丢 —— 它最短, 且"有没有在跑工具"最有信息量);
+ *   每一段都按显示宽算 (中文 2 列)。
+ */
+export function fitSegments(segs, avail) {
+    // 2026-09-30: 宽度一律用 loading-tui 的 dispWidth (按 East Asian Width 表) ——
+    //   之前这里和 getStatus 各写了一份 "charCode > 255 ⇒ 2" 的启发式, 它把 `│ ░ ◷ ▸ ◎ ✓ ↑ ⚙`
+    //   这些**单宽**符号都算成 2 列 ⇒ 右对齐时每行凭空多占十几列 (leo: 「没有完全右对齐」)。
+    const w = (s) => dispWidth(s);
+    const dropOrder = ['↑', '◎', '✓', '◷']; // 先丢谁 (从重要性的低到高; ⚙ 永不丢)
+    let cur = [...segs];
+    const total = () => cur.reduce((n, s) => n + w(s), 0) + Math.max(0, cur.length - 1) * 3; // 3 = ' │ '
+    for (const tag of dropOrder) {
+        if (total() <= avail)
+            break;
+        const i = cur.findIndex(s => s.startsWith(tag));
+        if (i >= 0)
+            cur.splice(i, 1);
+    }
+    return cur;
+}
+/**
+ * 右对齐一段注释 (会话 Title) 需要的**左填充空格数** (纯函数, 可确定性验证)。
+ *
+ * leo 2026-09-30: 「这个 title 需要顶格右侧」= 贴终端右边缘, 不在段后面跟着走。
+ * 规则:
+ *   · 目标右边缘 = width - 1 (**绝不出正好等于终端宽度的行** —— 终端自动换行会把版面撑歪);
+ *   · 至少留 1 个空格与左边内容分开 (挨着就分不清是标题还是段);
+ *   · 放不下 (pad < 1) 返回 null ⇒ 调用方**不显示**标题 (宁可没有, 不挤坏这一行)。
+ */
+export function rightAlignPad(usedWidth, noteWidth, width) {
+    const pad = (width - 1) - usedWidth - noteWidth;
+    return pad >= 1 ? pad : null;
+}

package/dist/cli/stores.js

@@ -28,11 +28,27 @@ export function useStore(s) {
 /** transcript: 消息列表 (agent/用户/系统行) — 供虚拟化/滚动/桥接读写 */
 export const transcriptStore = createStore([]);
 export const uiStore = createStore({ status: '', thinking: false, transient: null });
+/**
+ * panel: **固定区**内容 (启动面板等) —— 与会话区**分开**存放.
+ *   2026-09-30 (leo: 「没有做切分区域, 导致顶部面板在回复的时候也被 AI 内容挤坏了」):
+ *   原来面板和会话共用一个 transcript 缓冲 ⇒ 回复一来窗口一滚, 面板就被挤烂/切掉.
+ *   现在面板活在独立 store, 渲染成"上半块固定区", 有自己的高度, 不随会话滚动.
+ */
+export const panelStore = createStore([]);
 // ── 纯函数 action (bridge 与组件都走这里) ────────────────────────────────────
 export function appendMsg(line) {
     const c = transcriptStore.get();
     transcriptStore.set([...c, line]);
 }
+export function appendPanelMsg(line) {
+    const c = panelStore.get();
+    panelStore.set([...c, line]);
+}
+/** 清空固定区 (面板重打时用; 保证"只一块") */
+export function clearPanelMsg() {
+    if (panelStore.get().length)
+        panelStore.set([]);
+}
 export function replaceLastMsg(line) {
     const c = transcriptStore.get();
     if (c.length === 0) {