@bolloon/bolloon-agent 0.4.17 → 0.4.19

package/dist/agents/agent-registry.js

@@ -13,6 +13,8 @@ import * as path from 'path';
 import { getCIDDatabase } from '../orbitdb/cid-database.js';
 const home = () => process.env.HOME || os.homedir() || '/tmp';
 export const REGISTRY_ORBIT_KEY = 'services';
+/** 网络启动包 meta 键 (networkId/name/version/capacityOfMembers/sharedContextCid) */
+export const REGISTRY_ORBIT_META_KEY = 'meta';
 /** OrbitDB store 名 (按 did 短名确定性) */
 export function registryStoreName(did) {
     const short = String(did || 'local').replace(/[^a-zA-Z0-9-]/g, '_').slice(0, 40) || 'local';
@@ -118,6 +120,28 @@ export class OrbitDBAgentRegistry {
             return orbit;
         return this.loadLocalFromDisk();
     }
+    async writeMeta(meta) {
+        if (!this.ready || !this._store)
+            return { ok: false, error: 'registry store 未就绪 (离线模式)' };
+        try {
+            await this._store.put(REGISTRY_ORBIT_META_KEY, meta);
+            return { ok: true };
+        }
+        catch (e) {
+            return { ok: false, error: String(e?.message || e).slice(0, 120) };
+        }
+    }
+    async readMeta() {
+        if (!this.ready || !this._store)
+            return null;
+        try {
+            const v = await this._store.get(REGISTRY_ORBIT_META_KEY);
+            return v && typeof v === 'object' ? v : null;
+        }
+        catch {
+            return null;
+        }
+    }
     async discover(query) {
         const all = await this.list();
         const q = String(query || '').trim().toLowerCase();

package/dist/agents/gateway-network.js

@@ -182,30 +182,34 @@ export async function joinNetwork(link, deps) {
     // 合并到本地 registry (按 agentId + service.name 去重)
     const registry = deps?.registry ?? getAgentRegistry();
     const local = await registry.list();
-    let joined = 0;
-    for (const svc of remote) {
-        if (!svc?.agentId || !svc?.service?.name)
-            continue;
-        const exists = local.some((l) => l.agentId === svc.agentId && l.service?.name === svc.service?.name);
-        if (!exists) {
+    const remoteServices = Array.isArray(remote) ? remote : [];
+    const { merged, joined } = mergeRemoteServices(remoteServices, local);
+    for (const svc of merged) {
+        if (!local.some((l) => l.agentId === svc.agentId && l.service?.name === svc.service?.name)) {
             await registry.register(svc).catch(() => { });
-            joined++;
         }
     }
-    // 记录成员身份 (持久化 → 重启后自动恢复)
+    // ① 网络启动包 (meta): 拉网络声明 (networkId/名称/版本/容量/共享context CID), 尽力而为
+    const meta = await fetchNetworkMeta(parsed).catch(() => null);
+    const bootstrap = buildNetworkBootstrap(meta);
+    // 记录成员身份 (持久化 → 重启后自动恢复) + 网络启动包信息
     await saveNetworks([
         ...existing,
         {
             link: norm,
             linkKey: identityKey,
             kind: parsed.kind,
-            name: parsed.networkName,
+            name: bootstrap.name || parsed.networkName,
             joinedAt: new Date().toISOString(),
-            serviceCount: remote.length,
+            serviceCount: remoteServices.length,
             lastSyncAt: new Date().toISOString(),
+            networkId: bootstrap.networkId,
+            version: bootstrap.version,
+            capacityOfMembers: bootstrap.capacityOfMembers,
+            sharedContextCid: bootstrap.sharedContextCid,
         },
     ]);
-    return { ok: true, joined, total: remote.length, linkKind: parsed.kind, networkName: parsed.networkName };
+    return { ok: true, joined, total: remoteServices.length, linkKind: parsed.kind, networkName: bootstrap.name || parsed.networkName, networkId: bootstrap.networkId, sharedContextCid: bootstrap.sharedContextCid };
 }
 /** 启动恢复: 重拉所有已加入网络 (失败静默, 保留记录). 返回恢复统计. */
 export async function restoreJoinedNetworks() {
@@ -228,6 +232,156 @@ export async function restoreJoinedNetworks() {
     }
     return { restored, failed, total: nets.length };
 }
+/** 把任意 meta 对象规整成 NetworkBootstrap (纯函数, 容错) */
+export function buildNetworkBootstrap(meta) {
+    const m = meta && typeof meta === 'object' ? meta : {};
+    const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+    return {
+        networkId: str(m.networkId),
+        name: str(m.name),
+        version: str(m.version),
+        capacityOfMembers: typeof m.capacityOfMembers === 'number' ? m.capacityOfMembers : undefined,
+        sharedContextCid: str(m.sharedContextCid),
+    };
+}
+/** 拉取网络 meta (尽力而为, 失败返回 null): orbitdb('meta' 键) / ipns(network.json) / http(doc.meta) */
+async function fetchNetworkMeta(parsed) {
+    try {
+        if (parsed.kind === 'http') {
+            const r = await fetch(parsed.url, { signal: AbortSignal.timeout(15000) });
+            if (!r.ok)
+                return null;
+            const d = await r.json();
+            return d?.meta ?? null;
+        }
+        if (parsed.kind === 'ipns') {
+            const r = await fetch(`http://127.0.0.1:8080/ipns/${parsed.name}/network.json`, { signal: AbortSignal.timeout(15000) });
+            if (!r.ok)
+                return null;
+            const d = await r.json();
+            return d?.meta ?? d;
+        }
+        if (parsed.kind === 'orbitdb') {
+            const { getCIDDatabase } = await import('../orbitdb/cid-database.js');
+            const db = getCIDDatabase();
+            const store = await db.openStoreByAddress(parsed.address, 'keyvalue');
+            if (!store)
+                return null;
+            const v = await store.get('meta').catch(() => null);
+            return v ?? null;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 纯函数: 远端服务并入本地 (按 agentId + service.name 去重), 返回合并结果 + 新增数 */
+export function mergeRemoteServices(remote, local) {
+    const out = local.slice();
+    let joined = 0;
+    for (const svc of remote) {
+        if (!svc?.agentId || !svc?.service?.name)
+            continue;
+        const exists = out.some((l) => l.agentId === svc.agentId && l.service?.name === svc.service?.name);
+        if (!exists) {
+            out.push(svc);
+            joined++;
+        }
+    }
+    return { merged: out, joined };
+}
+/** ② 拉取网络画像 (只读, 不落盘): 供 on-join 告知 agent "网络里有什么" */
+export async function pullNetworkProfile(link) {
+    const parsed = parseNetworkLink(link);
+    if (!parsed)
+        return null;
+    let services = null;
+    if (parsed.kind === 'http')
+        services = await fetchRemoteRegistry(parsed.url);
+    else if (parsed.kind === 'ipns')
+        services = await fetchIpnsRegistry(parsed.name);
+    else if (parsed.kind === 'orbitdb')
+        services = await fetchOrbitdbRegistry(parsed.address);
+    const meta = await fetchNetworkMeta(parsed).catch(() => null);
+    if (!services || services.length === 0)
+        return null;
+    return { bootstrap: buildNetworkBootstrap(meta), members: services };
+}
+/**
+ * ③ 成员自描述广播: 把本机服务声明(list .agentId 匹配 self)写回共享网络 store ('services' 合并 self).
+ *   ① ipns/http 无回写 → 只本地登记 (返回 note); ② orbitdb replica 只读时写穿失败 → 非致命 (返回 note).
+ *   opts.members: 本机要广播的成员声明 (通常 = 自己注册的 AgentService 列表).
+ */
+export async function networkShareSelf(link, members, opts) {
+    if (!members || members.length === 0)
+        return { ok: true, note: '无本机成员声明可广播' };
+    const parsed = parseNetworkLink(link);
+    if (!parsed)
+        return { ok: false, error: '链接无法解析' };
+    if (parsed.kind !== 'orbitdb') {
+        return { ok: true, note: `${parsed.kind} 无回写能力, 已本地登记 (发起方自托管 registry 应含本机)` };
+    }
+    try {
+        const { getCIDDatabase } = await import('../orbitdb/cid-database.js');
+        const db = getCIDDatabase();
+        const store = await db.openStoreByAddress(parsed.address, 'keyvalue');
+        if (!store)
+            return { ok: false, error: '网络 store 不可达' };
+        const cur = (await store.get('services').catch(() => null));
+        const arr = Array.isArray(cur) ? cur.slice() : [];
+        for (const m of members) {
+            const i = arr.findIndex((s) => s.agentId === m.agentId && s.service?.name === m.service?.name);
+            const entry = { ...m, updatedAt: new Date().toISOString(), registeredAt: m.registeredAt || new Date().toISOString() };
+            if (i >= 0)
+                arr[i] = entry;
+            else
+                arr.push(entry);
+        }
+        await store.put('services', arr);
+        return { ok: true, note: `已广播 ${members.length} 条本机声明到网络` };
+    }
+    catch (e) {
+        return { ok: false, error: `写穿失败(疑似只读 replica): ${String(e?.message || e).slice(0, 120)}`, note: '已在本地登记, 可在你的分享链接中带上本机' };
+    }
+}
+/**
+ * ① 拉取共享 context (由启动包 sharedContextCid 指向): 从本地 IPFS 网关读文本返回,
+ *   调用方负责注入本地 context (了解"所有信息"的最后一段).
+ */
+export async function pullNetworkSharedContext(cid) {
+    try {
+        const r = await fetch(`http://127.0.0.1:8080/ipfs/${cid}`, { signal: AbortSignal.timeout(15000) });
+        if (!r.ok)
+            return null;
+        return await r.text();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * ① 发布共享 context 到 OrbitDB (内容寻址), 返回 CID — 供 shareNetworkLink 的 sharedContextCid,
+ *   手机/PC 入网后拉取即"近期上下文同步". opts.share=true 时把块放入 helia blockstore 供网络拉取.
+ */
+export async function publishNetworkSharedContext(text, opts) {
+    try {
+        const { getCIDDatabase } = await import('../orbitdb/cid-database.js');
+        const db = getCIDDatabase();
+        const rec = await db.save({ agentId: opts?.agentId || 'bolloon-network', type: 'context', content: text });
+        let cid = rec.id;
+        if (opts?.share !== false) {
+            try {
+                cid = await db.share(cid);
+            }
+            catch { /* 分享失败仍可用 CID 读 */ }
+        }
+        return { ok: true, cid };
+    }
+    catch (e) {
+        return { ok: false, error: String(e?.message || e).slice(0, 140) };
+    }
+}
 // ============ 分享链接 ============
 /**
  * 生成本机可分享的网络链接: orbitdb://<registry storeAddress>?name=<网络名>.
@@ -244,8 +398,24 @@ export async function shareNetworkLink(opts) {
         if (!registry.ready || !registry.storeAddress) {
             return { ok: false, error: 'OrbitDB registry 未就绪 (离线模式). 备选: 把 registry 列表发布成 https://.../registry 端点分享' };
         }
-        const name = encodeURIComponent(String(opts?.name || registry.storeName || 'bolloon-network'));
-        return { ok: true, link: `orbitdb://${registry.storeAddress}?name=${name}` };
+        // ① 全量启动包: 把 networkId/名称/版本/容量/共享context CID 写进共享 store (尽力而为, 失败仍分享)
+        const networkId = opts?.meta?.networkId || registry.storeName;
+        const name = String(opts?.name || opts?.meta?.name || registry.storeName || 'bolloon-network');
+        const metaObj = {
+            networkId,
+            name,
+            version: opts?.meta?.version,
+            capacityOfMembers: opts?.meta?.capacityOfMembers,
+            sharedContextCid: opts?.meta?.sharedContextCid,
+        };
+        let note;
+        if (registry.writeMeta) {
+            const w = await registry.writeMeta(metaObj).catch(() => ({ ok: false, error: 'writeMeta 异常' }));
+            if (!w.ok)
+                note = `meta 写共享库失败 (${w.error || '未知'}) — 读方仍可拉到服务, 但拿不到启动包`;
+        }
+        const encodedName = encodeURIComponent(name);
+        return { ok: true, link: `orbitdb://${registry.storeAddress}?name=${encodedName}`, note };
     }
     catch (e) {
         return { ok: false, error: `生成分享链接失败: ${String(e?.message || e).slice(0, 160)}` };
@@ -268,7 +438,15 @@ export async function maybeAutoJoinGateway(text, deps) {
             return null; // 已在网络, 静默
         if (r.ok) {
             const netName = r.networkName ? `「${r.networkName}」` : ''; // URLSearchParams 已 decode
-            return `🆕 已自动加入 Agent 网络${netName} (${r.linkKind}): 拉取 ${r.total} 个服务, 新增 ${r.joined} 个。用 gateway_status 查看, gateway_call 调用网络里的服务。`;
+            // ② on-join 广播: 写入自己的服务声明 (orbitdb 可回写时), 非致命
+            let selfNote = '';
+            if (deps?.self && deps.self.length > 0) {
+                const s = await networkShareSelf(link, deps.self, deps).catch(() => null);
+                selfNote = s?.ok ? ' · 已广播本机声明' : (s?.note ? ` · ${s.note}` : ' · 本机声明广播失败');
+            }
+            const bootPart = r.networkId ? ` (net=${String(r.networkId).slice(0, 16)})` : '';
+            const ctxPart = r.sharedContextCid ? ` · 共享ctx:${String(r.sharedContextCid).slice(0, 12)}` : '';
+            return `🆕 已自动加入 Agent 网络${netName}${bootPart} (${r.linkKind}): 拉取 ${r.total} 个服务, 新增 ${r.joined} 个${ctxPart}${selfNote}。用 gateway_status 查看, gateway_call 调用网络里的服务。`;
         }
         return `⚠️ 检测到 Agent 网络链接 (${r.linkKind || 'unknown'}) 但加入失败: ${r.error}`;
     }

package/dist/agents/network-link.js

@@ -0,0 +1,33 @@
+// ─── 网络链接纯函数 (无 Node 依赖, 桌面/手机浏览器共用) ────────────────────
+//   parseNetworkLink / detectGatewayLink 从 gateway-network.ts 抽出,
+//   供 browser 端 (mobile-gateway) 复用, 不拖 OrbitDB/fs 进 WebView.
+/** 解析链接字符串 → ParsedNetworkLink (剥离 ?name= query) */
+export function parseNetworkLink(link) {
+    const l = String(link || '').trim();
+    if (!l)
+        return null;
+    const [base, query] = l.split('?');
+    let networkName;
+    try {
+        networkName = query ? (new URLSearchParams(query).get('name') || undefined) : undefined;
+    }
+    catch { /* 忽略坏 query */ }
+    if (base.startsWith('ipns://'))
+        return { kind: 'ipns', value: base.slice('ipns://'.length), url: base, networkName };
+    if (base.startsWith('orbitdb://')) {
+        let address = base.slice('orbitdb://'.length);
+        if (!address.startsWith('/'))
+            address = `/${address}`;
+        return { kind: 'orbitdb', value: address, url: base, networkName };
+    }
+    if (base.startsWith('http://') || base.startsWith('https://'))
+        return { kind: 'http', value: base, url: base, networkName };
+    return null;
+}
+/** 从消息文本检测 gateway 链接 (自动加入触发器用) */
+export function detectGatewayLink(text) {
+    const t = String(text || '');
+    const re = /(orbitdb:\/\/\/?orbitdb\/[^\s)'"<>，。；]+|ipns:\/\/[^\s)'"<>，。；]+|https?:\/\/[^\s)'"<>，。；]*\/registry(?:\?[^\s)'"<>，。；]*)?)/;
+    const m = re.exec(t);
+    return m ? m[1].trim() : null;
+}

package/dist/cli/content.js

@@ -0,0 +1,10 @@
+/**
+ * content.ts — TUI 文案/提示 与组件解耦 (内容层分离, 便于统一改文案/多语言)
+ */
+export const COMPOSER_PLACEHOLDER = '输入消息... @智能体 /命令 #文件 · Esc 双击退出 · /queue 排队 · !终端命令';
+export const POPUP_TITLE_TAB = 'Tab 补齐';
+export const POPUP_TITLE_AGENT = '@ 智能体';
+export const POPUP_TITLE_FILE = '# 文件';
+export const POPUP_TITLE_COMMAND = '/ 命令 · 技能 · 插件';
+export const CHAR_EXIT_HINT = '再按一次 Esc 退出当前进程';
+export const CHAR_LOADING = ['(｀・ω・´)', '(´･_･`)', '(｡•́︿•̀｡)', 'ᕙ(▀̿̿Ĺ̯̿̿▀̿ ̿)ᕗ', '(◕‿◕)', 'ヽ(´▽｀)/'];

package/dist/cli/ink-app.js

@@ -7,39 +7,45 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * 2026-08-05: @ / # 弹出选择窗 — 输入 @ 命中智能体, / 命中命令+技能+插件, # 命中文件
  *   ↑/↓ 导航, Tab/Enter 选中, Esc 关闭, 弹出窗打开时 TextInput 让出焦点 (focus=false)
  */
-import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
-import { render, Box, Text, useInput, useApp } from 'ink';
+import React, { useState, useEffect, useCallback, useRef, useMemo } from 'react';
+import { render, Box, Text, useInput, useApp, useStdout } from 'ink';
 import TextInput from 'ink-text-input';
-import { brandArtLines, boxTop, boxRow, boxBottom, dispWidth } from './loading-tui.js';
+import { dispWidth, LOADING_FRAMES as KAOMOJI } from './loading-tui.js';
+import { THEME, fg } from './theme.js';
+import { COMPOSER_PLACEHOLDER, POPUP_TITLE_TAB, POPUP_TITLE_AGENT, POPUP_TITLE_FILE, POPUP_TITLE_COMMAND } from './content.js';
+import { DOUBLE_ESC_MS, STATUS_TICK_MS, THINK_FRAME_MS } from './timing.js';
+import { resolveNormalKey, applyScroll } from './keymap.js';
+import { useWidgets } from './widget-host.js';
+import { useStore, transcriptStore, uiStore, appendMsg, replaceLastMsg, replaceMarkerMsg, setUiStatus, setUiThinking, setUiTransient } from './stores.js';
 import { loadAgents, loadCommands, loadSkills, loadPlugins, loadFiles, getMention, matchFileScore, } from './mention-data.js';
-// ─── 组件: Logo Box ──────────────────────────────────────────────────────────
-const LogoBox = ({ width }) => {
-    const art = brandArtLines();
-    const mw = Math.max(40, ...art.map(l => dispWidth(l))) + 4;
-    const bw = Math.min(width - 2, mw);
-    const rows = [boxTop('Bolloon Agent', bw)];
-    for (const l of art)
-        rows.push(boxRow(l, bw, 'center'));
-    rows.push(boxBottom(bw));
-    return (_jsx(Box, { flexDirection: "column", children: rows.map((r, i) => _jsx(Text, { children: r }, i)) }));
-};
 // ─── 组件: 消息列表 ──────────────────────────────────────────────────────────
-const Messages = ({ msgs }) => (_jsx(Box, { flexDirection: "column", flexGrow: 1, justifyContent: "flex-start", children: msgs.map((m, i) => {
+/** 消息显示行数 (ANSI 剥离后按宽度 wrap 估行; 与 Ink 按父宽 wrap 近似一致) */
+function msgVisualLines(text, width) {
+    let n = 0;
+    const clean = text.replace(/\x1b\[[0-9;]*m/g, '');
+    for (const line of clean.split('\n')) {
+        const w = dispWidth(line);
+        n += Math.max(1, Math.ceil(w / Math.max(10, width - 1)));
+    }
+    return n;
+}
+// 2026-09-08: React.memo — msgs 引用不变时跳过重渲染 (配合虚拟化 slice, status tick 不再整表重绘)
+const Messages = React.memo(({ msgs }) => (_jsx(Box, { flexDirection: "column", flexGrow: 1, justifyContent: "flex-start", children: msgs.map((m, i) => {
         const clean = m.replace(/\x1b\[[0-9;]*m/g, '');
         return clean.trim() ? _jsx(Text, { children: clean ? m : '' }, i) : null;
-    }) }));
+    }) })));
 const MentionPopup = ({ title, items, sel, width, loading }) => {
     const MAX_ROWS = 8;
     // 2026-08-08: 滑动窗口 — 选中项始终可见 (原实现 fix 屏幕顶部, sel 超窗口时无高亮行)
     const offset = Math.max(0, Math.min(sel - Math.floor(MAX_ROWS / 2), Math.max(0, items.length - MAX_ROWS)));
     const shown = items.slice(offset, offset + MAX_ROWS);
     const innerW = Math.max(width - 2, 10);
-    return (_jsxs(Box, { flexDirection: "column", width: width, children: [_jsx(Text, { color: "cyan", bold: true, children: `╭─ ${title} ${'─'.repeat(Math.max(2, innerW - dispWidth(title) - 4))}╮` }), loading && items.length === 0 ? (_jsx(Text, { color: "dim", children: "\u2502 \u626B\u63CF\u4E2D..." })) : !loading && items.length === 0 ? (_jsx(Text, { color: "dim", children: "\u2502 \u65E0\u5339\u914D" })) : (shown.map((it, i) => {
+    return (_jsxs(Box, { flexDirection: "column", width: width, children: [_jsx(Text, { color: THEME.accent, bold: true, children: `╭─ ${title} ${'─'.repeat(Math.max(2, innerW - dispWidth(title) - 4))}╮` }), loading && items.length === 0 ? (_jsx(Text, { color: "dim", children: "\u2502 \u626B\u63CF\u4E2D..." })) : !loading && items.length === 0 ? (_jsx(Text, { color: "dim", children: "\u2502 \u65E0\u5339\u914D" })) : (shown.map((it, i) => {
                 const active = i === sel;
                 const label = it.kind === 'file' ? it.label : `${it.kind === 'skill' ? '⚡' : it.kind === 'plugin' ? '🔌' : ''}${it.label}`;
                 const hint = it.hint ? `${it.hint}` : it.kind === 'file' ? '文件' : '';
                 return (_jsxs(Box, { width: innerW, children: [_jsx(Text, { color: active ? 'black' : undefined, backgroundColor: active ? 'cyan' : undefined, children: `${active ? '❯ ' : '  '}${label}` }), _jsx(Text, { color: active ? 'black' : 'dim', backgroundColor: active ? 'cyan' : undefined, dimColor: !active, children: `  ${hint}` })] }, `${it.kind}:${it.label}`));
-            })), items.length > MAX_ROWS && (_jsxs(Text, { color: "dim", children: ["\u2502 ", offset + 1, "-", offset + shown.length, "/", items.length, " \u00B7 \u8FD8\u6709 ", items.length - (offset + shown.length), " \u9879..."] })), _jsx(Text, { color: "cyan", children: `╰${'─'.repeat(innerW)}╯` })] }));
+            })), items.length > MAX_ROWS && (_jsxs(Text, { color: "dim", children: ["\u2502 ", offset + 1, "-", offset + shown.length, "/", items.length, " \u00B7 \u8FD8\u6709 ", items.length - (offset + shown.length), " \u9879..."] })), _jsx(Text, { color: THEME.accent, children: `╰${'─'.repeat(innerW)}╯` })] }));
 };
 const InkApp = ({ onPrompt, initialStatus, getStatusUpdate, terminalW, terminalH }) => {
     const [input, setInput] = useState('');
@@ -50,17 +56,23 @@ const InkApp = ({ onPrompt, initialStatus, getStatusUpdate, terminalW, terminalH
     }, [input]);
     // 2026-08-07: 提交防重 (InkApp \n/\r 兜底 + TextInput 双触发场景)
     const lastSubmitRef = useRef({ t: 0, v: '' });
-    const [msgs, setMsgs] = useState([]);
-    const [status, setStatus] = useState(initialStatus);
+    const msgs = useStore(transcriptStore); // #2 状态外置: transcript 来自外部 store
+    const ui = useStore(uiStore); // #2 status/thinking/transient 外置
+    const status = ui.status || initialStatus;
+    const thinking = ui.thinking;
+    const transient = ui.transient;
+    // #8 占用槽: 右侧 rails (有 widget 占宽, 无则布局不变)
+    const widgets = useWidgets();
+    const railNames = Object.keys(widgets);
+    const hasRails = railNames.length > 0;
     const { exit } = useApp();
-    const [thinking, setThinking] = useState(false);
-    // 2026-08-10: 临时状态行 (自动整理心跳/run-end 经验整理用) — 显示在颜文字行位置,
-    //   结束后设 null 即清空 (显示为空). 不进入消息历史, 不会残留显示效果.
-    const [transient, setTransient] = useState(null);
+    // 虚拟化滚动: 行窗口 top + 是否跟随底部 (用户上滚后自动跟随关闭, End 恢复)
+    const [scrollTop, setScrollTop] = useState(0);
+    const stickRef = useRef(true);
     const thinkingIdx = useRef(0);
     // 双击 Esc 退出当前进程 (500ms 窗口内第二次按下)
     const lastEscRef = useRef(0);
-    const C_WARN_ANSI = '\x1b[38;2;245;158;11m'; // #f59e0b
+    const C_WARN_ANSI = fg(THEME.warn); // #f59e0b
     // ── @ / # 弹出窗状态 ──────────────────────────────────────────────────────
     const mention = useMemo(() => getMention(input), [input]);
     const mentionKey = mention ? `${mention.kind}:${mention.start}` : null;
@@ -179,10 +191,10 @@ const InkApp = ({ onPrompt, initialStatus, getStatusUpdate, terminalW, terminalH
     }, [items, mention, tabState]);
     const popupOpen = !!(tabState || (mention && dismissed !== mentionKey));
     const safeSel = Math.min(sel, Math.max(0, filtered.length - 1));
-    const popupTitle = tabState ? 'Tab 补齐'
-        : mention?.kind === 'agent' ? '@ 智能体'
-            : mention?.kind === 'file' ? '# 文件'
-                : '/ 命令 · 技能 · 插件';
+    const popupTitle = tabState ? POPUP_TITLE_TAB
+        : mention?.kind === 'agent' ? POPUP_TITLE_AGENT
+            : mention?.kind === 'file' ? POPUP_TITLE_FILE
+                : POPUP_TITLE_COMMAND;
     // 在指定 start 位置插入补齐文本 (函数式更新, 闭包安全)
     const insertAt = useCallback((start, it) => {
         setInput(cur => {
@@ -276,34 +288,52 @@ const InkApp = ({ onPrompt, initialStatus, getStatusUpdate, terminalW, terminalH
         }
     }, [input, insertAt]);
     const [tiKey, setTiKey] = useState(0);
+    // 2026-09-08 (Hermes TUI 学习落地): 实时终端尺寸 — 原来 terminalW/H 在 mount 时冻结,
+    //   终端 resize 后分隔线/logo 宽度全错位 (Hermes 用 resizeCoalescer + 实时 layout)。
+    //   订阅 stdout resize, 每次渲染用最新列数。
+    const { stdout } = useStdout();
+    const [termSize, setTermSize] = useState({ w: terminalW, h: terminalH });
+    useEffect(() => {
+        // resizeCoalescer (#9): 拖拽终端时会连发 resize — 聚合到 80ms 空闲后一次性应用, 避免中间态跳帧
+        let raf = null;
+        let pending = null;
+        const apply = () => {
+            if (pending) {
+                const p = pending;
+                pending = null;
+                setTermSize(p);
+            }
+            raf = null;
+        };
+        const update = () => {
+            pending = { w: stdout?.columns || terminalW, h: stdout?.rows || terminalH };
+            if (raf)
+                clearTimeout(raf);
+            raf = setTimeout(apply, 80);
+        };
+        update();
+        stdout?.on?.('resize', update);
+        return () => { stdout?.removeListener?.('resize', update); if (raf)
+            clearTimeout(raf); };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [stdout]);
+    const W = termSize.w;
     // 全局: 思考动画控制
     useEffect(() => {
         // 2026-08-06: 防御 — 某些环境 (tsx/完整 CLI 初始化) 下 stdin 会处于 paused,
         // 不恢复则 useInput 收不到任何输入 (实测 isPaused=true, listeners=0)
         if (process.stdin.isPaused())
             process.stdin.resume();
-        globalThis.__inkSetThinking = (v) => setThinking(v);
-        globalThis.__inkAppend = (line) => {
-            setMsgs(prev => [...prev, line]);
-        };
-        globalThis.__inkSetStatus = (s) => {
-            setStatus(s);
-        };
+        globalThis.__inkSetThinking = (v) => setUiThinking(v);
+        globalThis.__inkAppend = (line) => appendMsg(line);
+        globalThis.__inkSetStatus = (s) => setUiStatus(s);
         // 2026-08-10: 临时状态行 (自动整理/经验整理): 传字符串显示, 传 null 清空 (显示为空)
-        globalThis.__inkSetTransient = (v) => {
-            setTransient(v === undefined ? null : v);
-        };
-        // 2026-08-12 (Task4): 原地替换最后一条消息 (命令加载态 → 完成态用).
-        //   不命中则追加 (兼容旧逻辑).
-        globalThis.__inkReplaceLast = (line) => {
-            setMsgs(prev => {
-                if (prev.length === 0)
-                    return [...prev, line];
-                const next = prev.slice();
-                next[next.length - 1] = line;
-                return next;
-            });
-        };
+        globalThis.__inkSetTransient = (v) => setUiTransient(v);
+        // 2026-08-12 (Task4): 原地替换最后一条消息 (命令加载态 → 完成态用). 不命中则追加.
+        globalThis.__inkReplaceLast = (line) => replaceLastMsg(line);
+        // 2026-09-08: 按内容匹配替换 — 占位框可能在 P2P/连接消息之后才被替换,
+        //   __inkReplaceLast 会覆盖错一条; 用字符串标记精确定位要替换的消息.
+        globalThis.__inkReplaceMatching = (marker, line) => replaceMarkerMsg(marker, line);
         return () => {
             delete globalThis.__inkAppend;
             delete globalThis.__inkSetStatus;
@@ -443,6 +473,18 @@ const InkApp = ({ onPrompt, initialStatus, getStatusUpdate, terminalW, terminalH
             return; // 其余键忽略 (return/tab/esc 等由 TextInput 或上层处理)
         }
         // ── 正常模式 ──
+        // #7 输入层: 滚动键走数据化 keymap (Ctrl+U/D / PgUp/PgDn / Home-End / Alt+↑↓ / Ctrl+Home-End)
+        if (totalLines > availH) {
+            const pg = Math.max(6, availH - 2);
+            const maxT = Math.max(0, totalLines - availH);
+            const act = resolveNormalKey(key, { scrollable: true, input: _input });
+            if (act !== 'none') {
+                const r = applyScroll(act, stickRef.current ? maxT : (scrollTop || 0), pg, maxT);
+                stickRef.current = r.stick;
+                setScrollTop(r.next);
+                return;
+            }
+        }
         // 2026-08-07: Enter 兜底 — pty/管道下 termios 可能把 \r 转 \n 且 node 把整 chunk
         //   当一次 keypress (key.return=false), TextInput 的 onSubmit 永不触发 → 消息发不出去.
         //   应用层把 \n/\r 一律视为提交 (兼容 raw/cooked 两种模式, 不依赖 termios).
@@ -488,7 +530,7 @@ const InkApp = ({ onPrompt, initialStatus, getStatusUpdate, terminalW, terminalH
         // 双击 Esc 退出当前进程: 第一击提示, 500ms 内第二击退出
         if (key.escape) {
             const now = Date.now();
-            if (now - lastEscRef.current < 500) {
+            if (now - lastEscRef.current < DOUBLE_ESC_MS) {
                 requestExit();
             }
             else {
@@ -522,17 +564,17 @@ const InkApp = ({ onPrompt, initialStatus, getStatusUpdate, terminalW, terminalH
         try {
             const s0 = getStatusUpdate();
             if (s0)
-                setStatus(s0);
+                setUiStatus(s0);
         }
         catch { /* 状态栏更新失败不致命 */ }
         const timer = setInterval(() => {
             try {
                 const s = getStatusUpdate();
                 if (s)
-                    setStatus(s);
+                    setUiStatus(s);
             }
             catch { /* 状态栏更新失败不致命 */ }
-        }, 1000);
+        }, STATUS_TICK_MS);
         return () => clearInterval(timer);
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, []);
@@ -549,17 +591,40 @@ const InkApp = ({ onPrompt, initialStatus, getStatusUpdate, terminalW, terminalH
             items: filtered.slice(0, 5).map(i => i.kind + ':' + i.label),
         });
     }, [popupOpen, mentionKey, filtered]);
-    // 思考动画 — kaomoji 旋转
-    const KAOMOJI = ['(｀・ω・´)', '(´･_･`)', '(｡•́︿•̀｡)', 'ᕙ(▀̿̿Ĺ̯̿̿▀̿ ̿)ᕗ', '(◕‿◕)'];
+    // 思考动画 — kaomoji 旋转 (帧序列单一来源: loading-tui LOADING_FRAMES, 2026-09-08)
     useEffect(() => {
         if (!thinking)
             return;
         const timer = setInterval(() => {
             thinkingIdx.current = (thinkingIdx.current + 1) % KAOMOJI.length;
-        }, 600);
+        }, THINK_FRAME_MS);
         return () => clearInterval(timer);
     }, [thinking]);
-    return (_jsxs(Box, { flexDirection: "column", height: "100%", children: [_jsxs(Box, { flexGrow: 1, flexDirection: "column", justifyContent: "flex-start", children: [_jsx(LogoBox, { width: terminalW }), _jsx(Messages, { msgs: msgs }), thinking && (_jsx(Box, { children: _jsxs(Text, { color: "yellow", children: [KAOMOJI[thinkingIdx.current], " \u601D\u8003\u4E2D..."] }) })), transient && (_jsx(Box, { children: _jsx(Text, { children: transient }) }))] }), _jsx(Box, { children: _jsx(Text, { bold: true, color: "#c4d640", children: '─'.repeat(terminalW) }) }), _jsx(Box, { children: _jsx(Text, { children: status }) }), _jsx(Box, { children: _jsx(Text, { bold: true, color: "#c4d640", children: '─'.repeat(terminalW) }) }), popupOpen && (tabState || mention) && (_jsx(MentionPopup, { title: popupTitle, items: filtered, sel: safeSel, width: terminalW, loading: loadingFiles })), picker && (_jsx(MentionPopup, { title: picker.title, items: picker.items, sel: Math.min(picker.sel, picker.items.length - 1), width: terminalW })), _jsxs(Box, { children: [_jsx(Text, { bold: true, color: "#c4d640", children: "\u276F " }), _jsx(TextInput, { value: input, onChange: setInput, onSubmit: onSubmit, focus: !popupOpen && !picker, placeholder: "\u8F93\u5165\u6D88\u606F... @\u667A\u80FD\u4F53 /\u547D\u4EE4 #\u6587\u4EF6 \u00B7 Esc \u53CC\u51FB\u9000\u51FA \u00B7 /queue \u6392\u961F \u00B7 !\u7EC8\u7AEF\u547D\u4EE4" }, tiKey)] }), _jsx(Box, { children: _jsx(Text, { bold: true, color: "#c4d640", children: '─'.repeat(terminalW) }) })] }));
+    // ── 虚拟化 transcript (消息级窗口 + 自动跟随底部) ───────────────────────────
+    // #1 分区预留: chrome 固定行 = 分隔线×3 + 状态栏 + 输入栏 = 5; transcript 严格不超区
+    //   (content Box flexGrow=1 但内容超宽会把 status/composer 挤走 → 可见窗口行数钳制 ≤ availH)
+    const availH = Math.max(6, termSize.h - 5);
+    const heights = useMemo(() => msgs.map(m => msgVisualLines(m, W)), [msgs, W]);
+    const cumulative = useMemo(() => {
+        const c = [0];
+        for (const h of heights)
+            c.push(c[c.length - 1] + h);
+        return c;
+    }, [heights]);
+    const totalLines = cumulative[cumulative.length - 1] || 0;
+    const maxTop = Math.max(0, totalLines - availH);
+    const sticky = stickRef.current;
+    const top = sticky ? maxTop : Math.min(scrollTop, maxTop);
+    let start = 0;
+    while (start < msgs.length && cumulative[start + 1] <= top + 0.5)
+        start++;
+    let end = start;
+    // 严格钳制: 端界不越过 availH, 保证 transcript 内容行数 ≤ 分区高度 (互不覆盖)
+    while (end + 1 < msgs.length && cumulative[end + 1] <= top + availH)
+        end++;
+    const visible = useMemo(() => msgs.slice(start, end + 1), [msgs, start, end]);
+    const scrolledOut = maxTop > 0 && !sticky;
+    return (_jsxs(Box, { flexDirection: "column", height: "100%", children: [_jsxs(Box, { flexGrow: 1, flexDirection: hasRails ? 'row' : 'column', children: [_jsxs(Box, { flexGrow: 1, flexDirection: "column", justifyContent: "flex-start", children: [_jsx(Messages, { msgs: visible }), scrolledOut && (_jsxs(Text, { color: THEME.muted, children: ["\u25BE \u4E0A\u6EDA ", top, " \u884C \u00B7 Ctrl+U/D \u7FFB\u9875 \u00B7 Home \u9876 \u00B7 End \u56DE\u5E95"] })), thinking && (_jsx(Box, { children: _jsxs(Text, { color: "yellow", children: [KAOMOJI[thinkingIdx.current], " \u601D\u8003\u4E2D..."] }) })), transient && (_jsx(Box, { children: _jsx(Text, { children: transient }) }))] }), hasRails && (_jsx(Box, { width: 36, marginLeft: 1, flexDirection: "column", justifyContent: "flex-start", children: railNames.map((n) => _jsxs(Text, { color: THEME.muted, children: [n, "\\n", widgets[n]] }, n)) }))] }), _jsx(Box, { children: _jsx(Text, { bold: true, color: THEME.accent, children: '─'.repeat(W) }) }), _jsx(Box, { children: _jsx(Text, { children: status }) }), _jsx(Box, { children: _jsx(Text, { bold: true, color: THEME.accent, children: '─'.repeat(W) }) }), popupOpen && (tabState || mention) && (_jsx(MentionPopup, { title: popupTitle, items: filtered, sel: safeSel, width: W, loading: loadingFiles })), picker && (_jsx(MentionPopup, { title: picker.title, items: picker.items, sel: Math.min(picker.sel, picker.items.length - 1), width: W })), _jsxs(Box, { children: [_jsx(Text, { bold: true, color: THEME.accent, children: "\u276F " }), _jsx(TextInput, { value: input, onChange: setInput, onSubmit: onSubmit, focus: !popupOpen && !picker, placeholder: COMPOSER_PLACEHOLDER }, tiKey)] }), _jsx(Box, { children: _jsx(Text, { bold: true, color: THEME.accent, children: '─'.repeat(W) }) })] }));
 };
 export { InkApp };
 // ─── 启动 ────────────────────────────────────────────────────────────────────
@@ -582,15 +647,15 @@ export function stopInk() {
     }
 }
 export function inkAppendLine(line) {
-    const fn = globalThis.__inkAppend;
-    if (fn)
-        fn(line);
+    appendMsg(line);
 }
 /** 2026-08-12 (Task4): 原地替换最后一条消息 (命令加载态 → 完成态). 无消息时追加. */
 export function inkReplaceLastLine(line) {
-    const fn = globalThis.__inkReplaceLast;
-    if (fn)
-        fn(line);
+    replaceLastMsg(line);
+}
+/** 2026-09-08: 按内容标记原地替换一条消息 (占位框 → 启动面板完整内容). */
+export function inkReplaceMatchingLine(marker, line) {
+    replaceMarkerMsg(marker, line);
 }
 export function inkSetStatus(s) {
     const fn = globalThis.__inkSetStatus;
@@ -598,13 +663,9 @@ export function inkSetStatus(s) {
         fn(s);
 }
 export function inkSetThinking(v) {
-    const fn = globalThis.__inkSetThinking;
-    if (fn)
-        fn(v);
+    setUiThinking(v);
 }
 /** 2026-08-10: 设置/清除临时状态行 (自动整理/经验整理). 传 null 清空 → 显示为空 */
 export function inkSetTransient(v) {
-    const fn = globalThis.__inkSetTransient;
-    if (fn)
-        fn(v);
+    setUiTransient(v);
 }