@bolloon/bolloon-agent 0.5.0 → 0.5.2

package/dist/cli/startup-notice.js

@@ -0,0 +1,160 @@
+/**
+ * startup-notice.ts — 启动**前言 / 就绪度报告**的上屏闸门 (2026-09-27)
+ *
+ * ## 这一层解决什么
+ *
+ * `src/cli/log-gate.ts` 盖的是**通用加载日志**(按行形状判: module tag / ISO 时间戳 / P2P 自述)。
+ * 但 `bolloon --cli` 启动前还有**另一条**刷屏路径, 它不带任何 tag, 所以上一轮没盖到:
+ *
+ *   ① `src/index.ts` 交互启动前的门禁检查 → `describeSetup(ev)` 整段
+ *      (`初始化状态: …  门禁: …` / `就绪度: basic=✗ …` / `已完成: …` / `配置来源: …` /
+ *       `已存输入: …` / `缺 (basic): …` / `下一步: …`);
+ *   ② `runSetupWizard` 的续跑前言 (那个 `╭─ Bolloon 初始化 …╮` 框 + `Onboard 模式: …` +
+ *      每步 `✓/✗` + `✅ 初始化完成 …` + 收尾再报一遍 `describeSetup`)。
+ *
+ * leo 口径 (2026-09-27): **打完 `bolloon --cli` 就该直接看到面板** —— 上面那些属于
+ * 「启动前的日志」, 默认一个字节都不该上屏; 但**没做好/要人下手的事不许被吞**。
+ *
+ * ## 三条出口 (与 log-gate 同构, 但对象是"前言"而不是"加载日志")
+ *
+ *   · 默认: 收进内存缓冲 → **不上屏**, 但**照抄进启动日志文件** (诊断不丢);
+ *   · `--verbose` / `BOLLOON_VERBOSE=1` / `BOLLOON_STARTUP_PREAMBLE=1`:
+ *     一行不改地写回 stderr (与修前逐字一致, 也是验收门的"修前对照");
+ *   · **失败 / 需人介入**: 由 `alertsFromSetup()` 折成**面板内一行提示**, 交给 Ink 渲染
+ *     (不是启动前大段刷屏)。判据复用 `log-gate.ts` 的 `carriesHumanSignal()` —— 只有一处。
+ *
+ * ## 什么时候必须**当场**把缓冲吐出来
+ *
+ * 前言被静默的前提是"后面有面板接着显示"。一旦流程变成**要人当场回答**(向导问问题)或者
+ * **根本走不到面板**(初始化中断/非零退出), 缓冲就必须先落屏 —— 否则就变成"信息被吞"。
+ * 这两条出口分别在 `runSetupWizard`(问问题前 `flushStartupNotices()`) 与
+ * `src/index.ts`(退出前) 显式调用。
+ */
+import { carriesHumanSignal, isStartupVerbose, logStartupLine, VERBOSE_ENV } from './log-gate.js';
+/** 显式要求"把启动前言打出来"(排查用; 语义 = 修前的默认行为) */
+export const PREAMBLE_ENV = 'BOLLOON_STARTUP_PREAMBLE';
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+/** 前言要不要上屏 */
+export function startupPreambleVisible(env = process.env, args = process.argv.slice(2)) {
+    const v = (env[PREAMBLE_ENV] ?? '').trim().toLowerCase();
+    if (TRUTHY.has(v))
+        return true;
+    return isStartupVerbose(args, env);
+}
+/** 缓冲里攒下的前言行 (默认模式的"没上屏但没丢"的那一份) */
+const buffer = [];
+/** 面板里要显示的就绪度行 (一行, 来自 `readinessLine()`) */
+let readiness = null;
+/** 面板里要显示的告警行 (失败/需人介入; 一条一行) */
+const alerts = [];
+/** 复位 (单测 / 同进程多次启动用) */
+export function resetStartupNotices() {
+    buffer.length = 0;
+    alerts.length = 0;
+    readiness = null;
+}
+/** 收/发一行前言: 可见模式写 stderr (与修前逐字一致), 默认模式进缓冲 + 落日志文件 */
+export function noticeLine(line, opts = {}) {
+    const visible = opts.visible ?? startupPreambleVisible();
+    for (const l of String(line).split('\n')) {
+        if (l === '' && line === '') { /* 空行也照收: 前言里有排版空行 */ }
+        logStartupLine(l); // 诊断不丢: 无论上不上屏都落盘
+        if (visible) {
+            process.stderr.write(l + '\n');
+            continue;
+        }
+        buffer.push(l);
+        // 失败/需人介入的行不许只躺在缓冲里 —— 同时折成面板告警 (去重)
+        if (carriesHumanSignal(l) && !alerts.includes(l))
+            alerts.push(l);
+    }
+}
+/** 缓冲里的前言行数 (验收门读它做对照) */
+export function bufferedNoticeLines() {
+    return [...buffer];
+}
+/** 把缓冲**当场**写到 stderr (要人回答 / 走不到面板时的兜底出口) */
+export function flushStartupNotices() {
+    if (buffer.length === 0)
+        return;
+    const payload = buffer.join('\n') + '\n';
+    buffer.length = 0;
+    process.stderr.write(payload);
+}
+/**
+ * 丢掉缓冲 (2026-09-27): **已经走到面板**时用 —— 剩下的纯前言不上屏 (它在 startup.log 里),
+ * 但它也就没必要继续留在内存里等下一次启动重放。
+ */
+export function clearBufferedNotices() {
+    buffer.length = 0;
+}
+/** 设置面板里的就绪度行 (一行) */
+export function setStartupReadiness(line) {
+    readiness = line;
+}
+/** 追加一条面板告警 (失败/需人介入) */
+export function pushStartupAlert(line) {
+    if (!line)
+        return;
+    if (!alerts.includes(line))
+        alerts.push(line);
+}
+/** 取走面板要显示的内容 (取走即清 —— 免得下次启动重复显示) */
+export function takeStartupPanelNotes() {
+    const notes = { readiness, alerts: [...alerts] };
+    readiness = null;
+    alerts.length = 0;
+    return notes;
+}
+// ---------------------------------------------------------------------------
+// 格式化 (纯函数 —— 单测与验收门直接喂它)
+// ---------------------------------------------------------------------------
+/** 详情查询命令 (面板提示里指的那个显式出口; 与 `cli-entry.ts` 的实现同一句) */
+export const SETUP_STATUS_CMD = 'bolloon setup status';
+const mark = (v) => (v ? '✓' : '✗');
+/**
+ * 一行就绪度: `就绪: basic ✓ · agent ✓ · durable ✗ · network ✓ · 详情: bolloon setup status`
+ *
+ * 为什么是"一行"而不是原来那 4 行明细: 面板里放得下, 一眼看得出来, 细节按需查
+ * (`bolloon setup status` 打全量 / `--verbose` 打修前那一段)。
+ */
+export function readinessLine(readiness, cmd = SETUP_STATUS_CMD) {
+    return `就绪: basic ${mark(!!readiness.basic)} · agent ${mark(!!readiness.agent)}`
+        + ` · durable ${mark(!!readiness.durable)} · network ${mark(!!readiness.network)}`
+        + ` · 详情: ${cmd}`;
+}
+/**
+ * 从门禁结论折出**面板告警行** (失败/需人介入才给, 就绪时给空数组)。
+ *
+ * 三条规矩:
+ *   ① 只在"真有事"时出声 (gate !== ready / 有 lastError) —— 就绪时面板不加噪音;
+ *   ② 每条都是**一行**, 且带上"下一步怎么办"或"去哪看全量";
+ *   ③ 不许只说"未就绪"三个字 —— 必须点出第一条具体原因 (`readinessWhy` 优先, 再退 `reasons`)。
+ */
+export function alertsFromSetup(ev) {
+    if (!ev)
+        return [];
+    const state = ev.state || {};
+    const out = [];
+    const why = state.readinessWhy || {};
+    const firstWhy = [why.basic, why.agent, why.durable].flatMap((a) => a || []).find((x) => !!x);
+    const firstReason = (ev.reasons || []).find((x) => !!x);
+    if (ev.gate !== 'ready') {
+        const detail = firstWhy || firstReason || '未说明 (跑 `' + SETUP_STATUS_CMD + '` 看全量)';
+        out.push(`⚠ 未就绪 (门禁: ${ev.gate}): ${detail}`);
+        const next = (ev.nextActions || [])[0];
+        if (next)
+            out.push(`  下一步: ${next} · 全量: ${SETUP_STATUS_CMD}`);
+    }
+    const le = state.lastError;
+    if (le && (le.message || le.stage)) {
+        out.push(`⛔ 上次初始化失败 [${le.errorClass || 'unknown'}] ${le.stage || ''}: ${String(le.message || '').slice(0, 160)}`);
+        out.push(`  处置: \`bolloon setup\` 会从失败阶段继续 · 全量: ${SETUP_STATUS_CMD}`);
+    }
+    return out;
+}
+/** verbose 模式下那句"现在是全量"的提示 (默认不出现) */
+export function preambleHintLine(env = process.env) {
+    return `[startup] 诊断模式 (--verbose / ${VERBOSE_ENV}=1 / ${PREAMBLE_ENV}=1): 启动前言全量输出`
+        + ' (默认模式下这部分只在面板里给一行就绪度 + 失败提示)';
+}

package/dist/cli/stores.js

@@ -54,11 +54,32 @@ export function replaceMarkerMsg(marker, line) {
     transcriptStore.set(n);
 }
 export function setUiStatus(status) {
+    // 2026-09-27: **同值不通知** —— 状态栏每秒 tick 一次 (时钟/上下文), 但值没变时重渲染 = Ink 整帧重画,
+    //   会把"用户正在框选复制"和"用户上滚暂停跟随"这两件事一起打断 (见 ink-app 的跟随冻结)。
+    if (uiStore.get().status === status)
+        return;
     uiStore.set({ ...uiStore.get(), status });
 }
 export function setUiThinking(thinking) {
+    if (uiStore.get().thinking === thinking)
+        return;
     uiStore.set({ ...uiStore.get(), thinking });
 }
 export function setUiTransient(v) {
-    uiStore.set({ ...uiStore.get(), transient: v === undefined ? null : v });
+    const next = v === undefined ? null : v;
+    if (uiStore.get().transient === next)
+        return;
+    uiStore.set({ ...uiStore.get(), transient: next });
+}
+/** transcript 里最后一条**非空**消息 (面板/`/copy` 都要"最近一条回复") */
+export function lastMsg() {
+    const c = transcriptStore.get();
+    for (let i = c.length - 1; i >= 0; i--)
+        if (String(c[i] ?? '').trim())
+            return c[i];
+    return '';
+}
+/** 整段会话文本 (`/copy all`) —— 内存里**完整**历史, 不裁剪 */
+export function allMsgsText() {
+    return transcriptStore.get().join('\n');
 }

package/dist/cli/theme.js

@@ -13,6 +13,15 @@ export const THEME = {
     warn: '#f59e0b', // 警告
     border: '#3a3a36', // 暗描边
     borderBright: '#8a8a7e', // 对话框边框提亮
+    /**
+     * 光标行的**字色** (2026-09-27 三改: 压在 accent 底上的近黑, 对比度 ~11:1)。
+     *
+     * 原来压在 accent 底上是 `muted` (#606058) —— 对比只有 ~3.9:1, 在真终端里看着"灰糊糊一片",
+     * 而且分组标题行当时**压根没进高亮分支** (leo 亲测: 光标停在标题上看不出选中)。
+     * 光标是"你在哪儿"的唯一指示, 必须一眼看到: 底色 = `accent` (主色块), 字色 = 本 token (近黑)。
+     * 仍然只有这一个色源 —— 组件里不许写第二份 RGB。
+     */
+    cursor: '#141410', // 光标行字色 (accent 底上的近黑)
 };
 /** '#c4d640' → '\x1b[38;2;196;214;64m' ANSI 前景色码 */
 export function fg(hex) {
@@ -21,3 +30,43 @@ export function fg(hex) {
     const b = parseInt(hex.slice(5, 7), 16);
     return `\x1b[38;2;${r};${g};${b}m`;
 }
+/**
+ * '#c4d640' → '\x1b[48;2;196;214;64m' ANSI **背景**色码 (2026-09-27)。
+ *
+ * 与 `fg()` 同一个调色板, 只换通道 —— 光标行要"accent 底色 + 深色字"就靠它,
+ * 不许在组件里再写一份 RGB (散落 hex 是这条线的病根)。
+ */
+export function bg(hex) {
+    const r = parseInt(hex.slice(1, 3), 16);
+    const g = parseInt(hex.slice(3, 5), 16);
+    const b = parseInt(hex.slice(5, 7), 16);
+    return `\x1b[48;2;${r};${g};${b}m`;
+}
+/** 调子 → 调色板 token (唯一映射) */
+export const TONE_TOKEN = {
+    accent: 'accent', // 主色: 光标底色 / 标题 / ← 当前
+    ok: 'ok', // 成功 / ● 可用
+    warn: 'warn', // 警告: special (未支持) / 无基址 / 探测异常
+    error: 'error', // 错误: 输入非法 / 切换失败
+    muted: 'muted', // 提示 / 头行 / 分组标题
+    dim: 'dim', // 更暗: ○ 未配置凭据 / 次要脚注
+    text: 'text', // 正文
+    plain: 'text', // 无调子 = 正文
+};
+/**
+ * 要不要上色 —— **唯一判据** (TUI 与主屏共用):
+ *   ① 输出得是真终端; ② 没设 `NO_COLOR`; ③ `TERM` 不是 `dumb`。
+ * 关掉颜色时**信息一点都不丢**: 所有语义都另有符号/文字 (●/○/→/›/▾/← 当前)。
+ */
+export function colorEnabled(isTTY, env = process.env) {
+    return !!isTTY && !env.NO_COLOR && env.TERM !== 'dumb';
+}
+/**
+ * 给**一整行**套上调子的前景色 (主屏/选择器都走这里)。
+ * `color === false` → 原样返回 (一个字节的 SGR 都不加)。
+ */
+export function tint(line, tone, color = true) {
+    if (!color)
+        return line;
+    return `${fg(THEME[TONE_TOKEN[tone] ?? 'text'])}${line}\x1b[0m`;
+}