@bolloon/bolloon-agent 0.4.33 → 0.5.1

package/dist/cli/model-selector.js

@@ -0,0 +1,538 @@
+/**
+ * model-selector.ts — `/model` 的分步选择器 (2026-09-26)
+ *
+ * 流程 (与命令面同一条路, 只是把参数逐步问出来):
+ *
+ * ```
+ * 1 选择供应商 → 2 未配置则输 API key → 3 选择模型 (模糊搜索) → 4 reasoning/temperature
+ *   → 5 Session 还是 Global → 6 测试连接 → 7 确认切换
+ * ```
+ *
+ * ## 两条硬纪律
+ *
+ * ① **切换只有一次写盘动作, 且只走统一入口**。本文件不碰配置文件、不碰模型运行时 ——
+ *    前面六步全部是"收集意图", 第七步把收集到的东西**一次性**交给
+ *    `selectModel()` (`src/llm/model-selection.ts`)。理由: P0 之前 CLI 那条路
+ *    "只改配置文件不重建运行时", 于是出现"切了不生效"; 选择器如果自己写配置就会分叉出第二条路。
+ *    可核证据: `src/test/model-selector.test.ts` 有一条源码级门 —— 本文件里出现
+ *    `updateProvider(` / `setActiveProvider(` / `initMinimax(` / 直接写配置文件 就判红。
+ *
+ * ② **API key 只在内存里活到第七步**: 不打印、不回显、不落盘到别处 (第 2 步只回显尾 4 位),
+ *    由 `selectModel()` 在它自己的写盘路径里落进全局配置。用户在第二~六步取消 → 一个字节都没写。
+ *
+ * ## 元数据从哪来
+ *
+ * 列表与能力字段全部由 `src/llm/model-catalog.ts` 给 (那里定义了唯一填充点)。本文件**只做
+ * 三态到人话的翻译与排版**, 一个能力值都不产生 —— 拿不到真数据时列表上写的是"未知",
+ * 而不是一个看起来像真的常量。
+ */
+import { buildProviderSummaries, listModelsFor, formatModelMenuRow, providerGroupSummary, providerTierOf, providerTierCollapsedByDefault, orderProvidersForMenu, PROVIDER_GROUPS, providerRowTone, formatProviderMenuRow, unknownFootnote, searchModelEntries, resolvedApiKeyOf, } from '../llm/model-catalog.js';
+import { selectModel, probeSelection, credentialFingerprintOf, envKeyNamesOf as envKeysOf, } from '../llm/model-selection.js';
+import { admitManualModel } from '../llm/model-discovery.js';
+// 颜色只从 `theme.ts` 来 (唯一事实源): 调子→token 的映射与 `tint()` 都住在那边。
+import { tint } from './theme.js';
+// ============================================================
+// 选择原语 (choose → ask → 放弃)
+// ============================================================
+/**
+ * 主屏 (七步那些非选择器屏幕) 一行该用什么调子 —— 分类在**唯一一处**, 组件里不再散落判断。
+ * 只认行首的**符号/文字** (✓ ✗ ⚠ ● ○ 步骤 N/7 ──), 不认颜色 —— 所以无色环境下
+ * 同一张分类表照样成立, 屏幕只是少了颜色这一层。
+ */
+function mainLineTone(line) {
+    const s = line.trim();
+    if (/^(✗|错误|没有|非法|失败|无法)/.test(s))
+        return 'error';
+    if (/^(✓|●)/.test(s))
+        return 'ok';
+    if (/^○/.test(s))
+        return 'dim';
+    if (/^⚠/.test(s))
+        return 'warn';
+    if (/^步骤 \d\/7/.test(s))
+        return 'accent';
+    if (s.includes('special (需专用鉴权') || s.includes('无基址 (需自定义 baseUrl)'))
+        return 'warn';
+    if (/^──/.test(s))
+        return 'muted';
+    if (/^(已选|已收到|沿用|作用域|temperature|参数|模型|供应商|提示|用法|分组|目录|当前)/.test(s))
+        return 'muted';
+    return 'text';
+}
+function makeCtx(io, lines) {
+    /** 屏幕那一行上色 (只在 `print` 那一刻; `lines` 里留原文) */
+    const paint = (l) => (io.color ? tint(l, mainLineTone(l)) : l);
+    const push = (s) => { for (const l of String(s).split('\n')) {
+        lines.push(l);
+        io.print(paint(l));
+    } };
+    /**
+     * 把候选**逐条印出来再问** (leo 2026-09-27 硬要求)。
+     *
+     * 为什么单列一个函数: 曾经这里只印一句 `选择 (序号/值, 回车=1)`, 用户**无从知道 1 是谁** ——
+     * 序号与选项必须一起出现, 否则提示是空承诺。序号右对齐两位, 分组标题只在切换分组时印一次,
+     * 每条的 `label` 自带状态标记 (● 可用 / ○ 未配置凭据 / ← 当前), 不在这一层另编状态。
+     */
+    const printOptions = (items, title) => {
+        push(title);
+        let lastGroup;
+        items.forEach((c, i) => {
+            if (c.group && c.group !== lastGroup) {
+                push(`  ── ${c.group}`);
+                lastGroup = c.group;
+            }
+            push(`  ${String(i + 1).padStart(2)}) ${c.label}${c.hint ? ` — ${c.hint}` : ''}`);
+        });
+        push(`  [${items.length}]`);
+    };
+    /**
+     * 让用户从候选里挑一个; 返回 null = 取消 (或输入流结束)。
+     *
+     * 非法的输入**要说清为什么**再重问 (序号越界 → 报范围; 字母前缀没命中 → 报实际命中数),
+     * 而不是笼统一句"没对上"。**EOF (Ctrl-D)** 与"用户取消"分开: 前者印一行明确的取消理由。
+     */
+    const pick = async (items, title) => {
+        if (!items.length)
+            return null;
+        // 结构化选择器 (会话内 Ink) 自己渲染选项列表与当前光标 —— 这里不重复印一遍, 否则双份。
+        if (io.choose)
+            return await io.choose(items, title);
+        if (!io.ask)
+            return null;
+        printOptions(items, title);
+        for (let tries = 0; tries < 3; tries++) {
+            const ans = await io.ask(CH_PICK);
+            if (ans === null) {
+                push(EOF_CANCEL);
+                return null;
+            }
+            const raw = ans.trim();
+            if (raw === '')
+                return items[0].value;
+            if (/^\d+$/.test(raw)) {
+                const n = Number(raw);
+                const hit = items[n - 1];
+                if (hit)
+                    return hit.value;
+                push(`  ✗ 序号 ${n} 超出范围 (这里只有 1~${items.length} 项) — 重问`);
+                continue;
+            }
+            const exact = items.find((c) => c.value === raw);
+            if (exact)
+                return exact.value;
+            const lo = raw.toLowerCase();
+            const pref = items.filter((c) => c.value.toLowerCase().startsWith(lo) || c.label.includes(raw));
+            if (pref.length === 1)
+                return pref[0].value;
+            if (pref.length > 1) {
+                push(`  ✗ '${raw}' 对上 ${pref.length} 个候选, 请给序号: ${pref.slice(0, 6).map((c) => c.value).join(', ')}${pref.length > 6 ? ' …' : ''} — 重问`);
+                continue;
+            }
+            push(`  ✗ 没有候选的值或名字匹配 '${raw}' (可用值见上表) — 重问`);
+        }
+        push('  ✗ 连试 3 次都没对上 → 取消 (未改动任何配置)');
+        return null;
+    };
+    /** 是非确认 (一律先把两个选项印出来再问) */
+    const confirm = async (q, def = true) => {
+        const opts = [
+            { value: 'yes', label: def ? '确认 (默认)' : '确认' },
+            { value: 'no', label: def ? '取消' : '取消 (默认)' },
+        ];
+        if (io.ask) {
+            push(q);
+            opts.forEach((c, i) => push(`  ${i + 1}) ${c.label}`));
+            const ans = await io.ask(`${q} (y/n, 回车=${def ? 'y' : 'n'})`, { default: def ? 'y' : 'n' });
+            if (ans === null) {
+                push(EOF_CANCEL);
+                return false;
+            }
+            const a = ans.trim().toLowerCase();
+            return a === '' ? def : /^(y|yes|1|true|是|好|确认)$/.test(a);
+        }
+        if (io.choose) {
+            const v = await io.choose(opts, q);
+            return v === 'yes';
+        }
+        return false;
+    };
+    /** 文本输入 (没有该能力 → 返回 null, 由调用方决定退化行为; EOF 也返回 null) */
+    const text = async (q, def) => {
+        if (!io.ask)
+            return null;
+        const ans = await io.ask(q, def !== undefined ? { default: def } : undefined);
+        if (ans === null)
+            return null;
+        return ans.trim();
+    };
+    return { push, pick, confirm, text, printOptions };
+}
+/** 选择提示语 (每一步都用同一句, 方便验收按它数步骤) */
+const CH_PICK = '选择 (序号/值, 回车=1)';
+/** 输入流结束时的统一口径 (必须是"干净取消", 且不许写任何东西) */
+const EOF_CANCEL = '· 输入已结束 (Ctrl-D / EOF) → 取消本次切换, 一个字节都没写';
+// ============================================================
+// 主流程
+// ============================================================
+/**
+ * 跑一次分步选择器。**任何一步取消都不写任何东西**; 只有第 7 步会调 `selectModel()`。
+ */
+export async function runModelSelector(io, opts = {}) {
+    const lines = [];
+    const { push, pick, confirm, text } = makeCtx(io, lines);
+    const done = (r) => ({ ...r, lines });
+    /** 细节只给想看的人: 默认主屏不放 (`--verbose` 或交互里 `d` 才出) */
+    const verbose = (s) => { try {
+        if (opts.verbose)
+            push(s);
+    }
+    catch { /* 细节打不出不该中断主流程 */ } };
+    // ── 1) 供应商 ────────────────────────────────────────────
+    // 版面 (2026-09-27 二改, leo: "15 家登记…可以更多吗?" + "不用一下子全部显示, 可以有固定高度或者折叠"):
+    //   主屏 = **一行标题 + 候选行 + 一行状态**; 候选**是全部家** (内置 13 + 自定义 + 目录全部),
+    //   一屏画不完由全屏选择器用"固定高度视窗 (≤12 行) + 可折叠分组 + 搜索"消化 ——
+    //   **不是靠把家从候选集里藏掉** (藏了就搜不到、也数不出来)。分组计数/目录新鲜度仍退到 `--verbose`。
+    let summaries;
+    try {
+        summaries = await buildProviderSummaries({ sessionKey: opts.sessionKey });
+    }
+    catch (e) {
+        return done({ ok: false, reachedStep: 'provider', message: `读供应商列表失败: ${String(e?.message || e).slice(0, 160)}` });
+    }
+    const live = summaries.filter((s) => s.configured);
+    // "共 N 家" 从盘上真算 (内置 + 自定义 + 目录全部), 不写死 —— 验收门拿它跟盘上数字对。
+    push(`步骤 1/7 供应商 (共 ${summaries.length} 家登记: 内置+自定义+目录全部 · 可用 ${live.length} 家 · 分组可折叠)`);
+    verbose(`  ${providerGroupSummary(summaries)}`);
+    try {
+        // 动态 import: 选择器 → provider-catalog 是单向的 (目录层不 import 选择器), 不构成环;
+        // 用动态是为了让"目录读盘失败"不影响选择器本身能用。
+        const pc = await import('../llm/provider-catalog.js');
+        await pc.initializeProviderCatalog();
+        verbose(`  ${pc.catalogStatusLine()}`);
+        verbose(`  ${pc.catalogGroupLine()}`);
+        verbose('  看目录: /model catalog · 筛: /model catalog list <筛选词> · 拉最新: /model catalog refresh');
+    }
+    catch (e) {
+        verbose(`  ⚠ 目录状态读不出来: ${String(e?.message || e).slice(0, 120)} (目录层的问题, 不影响下面的选择)`);
+    }
+    if (!summaries.length)
+        return done({ ok: false, reachedStep: 'provider', message: '没有任何登记在册的供应商' });
+    // 排序 = 分组优先级 (当前 → 可用 → 未配置凭据 → 需专用鉴权 → 无 api 基址);
+    //   **全部家都在候选数组里** (包括后三组), 只是它们的分组**默认收起** (标题上照写家数)。
+    const ordered = orderProvidersForMenu(summaries);
+    const providerChoices = ordered.map((s) => {
+        const tier = providerTierOf(s);
+        return {
+            value: s.id,
+            label: formatProviderMenuRow(s),
+            hint: `${s.name}${s.providerReasoning === 'yes' ? ' · 登记支持 reasoning' : ''}${s.configuredModel ? ` · 配置里 model=${s.configuredModel}` : ''}`,
+            // 分组标题只在切换分组时印一次; 家数由选择器写在标题行上 (`── 名字 (N 家) ›`)
+            group: PROVIDER_GROUPS[tier],
+            // 后三组默认收起: 页面放得下, 而家数照样看得见 (`空格`/`→` 一键展开)
+            groupCollapsed: providerTierCollapsedByDefault(tier),
+            // 颜色只做**第二通道**: 语义本体是 label 里的符号 (●/○) 与分组标题 (special/无基址 → warn)
+            tone: providerRowTone(s),
+        };
+    });
+    const providerId = await pick(providerChoices, '选择供应商 (序号 / 供应商 id):');
+    if (!providerId)
+        return done({ ok: false, cancelled: true, reachedStep: 'provider', message: '已取消, 未改动任何配置' });
+    const summary = summaries.find((s) => s.id === providerId);
+    push(`已选供应商: ${providerId} (${summary.name})`);
+    // ── 2) 凭证 ──────────────────────────────────────────────
+    // 版面: 一行状态 + **四条路** (保持现有 / 替换 / 清除 / 改用环境变量)。有 key 也**不许静默跳过** ——
+    // 跳过时必须显式说"沿用现有 key (指纹 fp:xxxx)"。指纹只含长度+哈希, **不含明文**, 也不进日志。
+    let pendingKey;
+    let credentialAction = 'keep';
+    const fp = await credentialFingerprintOf(providerId).catch(() => undefined);
+    const keyZh = summary.keyState === 'not_required' ? '免 key'
+        : summary.keyState === 'missing' ? '缺 key'
+            : summary.keyState === 'env' ? '来自环境变量' : '已配置';
+    const envKeys = envKeysOf(providerId);
+    push(`步骤 2/7 凭证 — ${providerId}: ${keyZh}${fp ? ` (指纹 ${fp})` : ''}`);
+    if (summary.requiresApiKey && io.askHidden) {
+        const choices = [];
+        if (summary.keyState !== 'missing')
+            choices.push({ value: 'keep', label: `保持现有 (${fp || '已配置'})`, hint: '一个字节都不动', tone: 'ok' });
+        // 四条路的名字**在两种状态下保持一致** (只是 hint 不同): 用户/脚本答"替换"永远命中同一件事
+        choices.push({ value: 'replace', label: '替换 (重新输入, 掩码)', hint: summary.keyState === 'missing' ? '现在输入一个 key' : '覆盖存盘的这一份', tone: 'accent' });
+        if (summary.keyState === 'configured')
+            choices.push({ value: 'clear', label: '清除存盘的 key', hint: '删掉配置里这一格', tone: 'warn' });
+        if (envKeys.length)
+            choices.push({ value: 'env', label: `改用环境变量 (${envKeys[0]})`, hint: '不存盘, 从环境读' });
+        choices.push({ value: 'cancel', label: '取消 (什么都不改)', tone: 'dim' });
+        const act = await pick(choices, `凭证怎么处理 (${choices.length} 选 1):`);
+        // 未知答案一律当取消 —— 凭证这条路**只认四个明确动作**, 不猜
+        const known = act === 'keep' || act === 'replace' || act === 'clear' || act === 'env';
+        if (!act || !known)
+            return done({ ok: false, cancelled: true, reachedStep: 'key', message: '已取消, 未改动任何配置' });
+        if (act === 'replace') {
+            const ans = await io.askHidden(`粘贴 ${providerId} API key (输入掩码显示, 不回显明文)`);
+            if (ans === null) {
+                push(EOF_CANCEL);
+                return done({ ok: false, cancelled: true, reachedStep: 'key', message: '输入已结束 (EOF/Ctrl-D) —— 未改动任何配置' });
+            }
+            const k = ans.trim();
+            if (!k)
+                return done({ ok: false, cancelled: true, reachedStep: 'key', message: '没有收到 key, 未改动任何配置' });
+            pendingKey = k;
+            // 只回显尾 4 位 —— 全文不进任何输出/日志/报告
+            push(`已收到 key (****${k.slice(-4)}) — 只在第 7 步落盘, 中途取消则一个字节都不写`);
+        }
+        else {
+            credentialAction = act;
+            push(act === 'keep' ? `沿用现有 key (指纹 ${fp || '已配置'})`
+                : act === 'clear' ? '将清除存盘的 key (改用环境变量; 没有环境变量则这一步会拦下)'
+                    : `改用环境变量 (${envKeys[0] || 'env'})`);
+        }
+    }
+    else if (summary.requiresApiKey && summary.keyState === 'missing' && !io.askHidden) {
+        // 真缺凭证**且**这个环境收不了 key → 只能明说怎么办 (不再假装能继续)
+        return done({
+            ok: false,
+            reachedStep: 'key',
+            failureClass: 'missing_api_key',
+            message: `${providerId} 还没有凭证, 且当前环境不能安全地收 key —— 请在系统终端执行 \`bolloon model key ${providerId}\` (或打开 Web 配置页) 后再选。未改动任何配置。`,
+        });
+    }
+    else if (summary.requiresApiKey) {
+        push(`沿用现有 key (指纹 ${fp || '已配置'})`);
+    }
+    // ── 3) 模型 (模糊搜索 + 当前置顶) ─────────────────────────
+    let entries;
+    try {
+        entries = await listModelsFor(providerId, { sessionKey: opts.sessionKey });
+    }
+    catch (e) {
+        return done({ ok: false, reachedStep: 'model', message: `读模型列表失败: ${String(e?.message || e).slice(0, 160)}` });
+    }
+    if (!entries.length) {
+        return done({
+            ok: false, reachedStep: 'model',
+            message: `${providerId} 没有可用模型 (无内置目录且配置为空) —— 请用 \`/model ${providerId} <model>\` 直接指定, 或先配好目录`,
+        });
+    }
+    push(`步骤 3/7 模型 — ${providerId}, ${entries.length} 个候选`);
+    for (const f of unknownFootnote(entries))
+        verbose(`  ${f}`);
+    let candidates = entries;
+    let manualModel;
+    // 交互式 TUI 自带 `/` 实时筛选 —— 这里再问一句"搜索模型"就是同一件事问两遍 (用户要减到必要);
+    // 只有纯文本问答那条路 (io.ask) 才需要先问一次搜索词。
+    if (io.ask && !io.filterable && entries.length > 3) {
+        const q = await text('搜索模型 (模糊, 留空 = 全部)');
+        if (q === null) {
+            push(EOF_CANCEL);
+            return done({ ok: false, cancelled: true, reachedStep: 'model', message: '输入已结束 (EOF/Ctrl-D) —— 未改动任何配置' });
+        }
+        if (q) {
+            const hit = searchModelEntries(entries, q);
+            verbose(`筛选 '${q}' → ${hit.length} 个`);
+            candidates = hit;
+        }
+    }
+    if (!candidates.length) {
+        // 目录里没有匹配项也**允许手输** (实测: 目录不是可用模型的全集, 手输的名字常常真能用)
+        const manual = await text(`清单里没有匹配项。直接输入 ${providerId} 的原始 model ID (留空=取消)`);
+        if (manual === null) {
+            push(EOF_CANCEL);
+            return done({ ok: false, cancelled: true, reachedStep: 'model', message: '输入已结束 (EOF/Ctrl-D) —— 未改动任何配置' });
+        }
+        if (!manual)
+            return done({ ok: false, cancelled: true, reachedStep: 'model', message: '已取消, 未改动任何配置' });
+        manualModel = manual;
+        // 手输的模型顺手记进发现缓存 (`admitManualModel` 是唯一那处实现) —— 下次搜它就能搜到。
+        try {
+            const admitted = await admitManualModel(providerId, manual);
+            verbose(admitted.ok ? `已记进 ${providerId} 的发现缓存 (手输)` : `· 手工模型没记进缓存: ${admitted.reason}`);
+        }
+        catch (e) {
+            verbose(`· 手工模型没记进缓存: ${e.message}`);
+        }
+    }
+    const modelId = manualModel ?? await pick([
+        ...candidates.map((e) => ({
+            value: e.id,
+            label: formatModelMenuRow(e),
+            hint: e.current ? '当前生效' : undefined,
+            // 上游目录里没有的名字: 只作**提示**色, 不是拒用 (实测它常真能用)
+            tone: (e.upstreamSeen === false ? 'warn' : e.current ? 'accent' : 'plain'),
+        })),
+        // 清单里没有的模型也能手输 (实测目录不是全集) —— 末行固定放, 与其它步骤的"取消"行同一形态
+        ...(io.ask ? [{ value: '__manual__', label: '手输一个 model ID', hint: '目录没列出的名字也能试' }] : []),
+    ], `选择模型 (${providerId})`);
+    if (!modelId)
+        return done({ ok: false, cancelled: true, reachedStep: 'model', message: '已取消, 未改动任何配置' });
+    if (modelId === '__manual__') {
+        const manual = await text(`输入 ${providerId} 的原始 model ID (留空=取消)`);
+        if (manual === null) {
+            push(EOF_CANCEL);
+            return done({ ok: false, cancelled: true, reachedStep: 'model', message: '输入已结束 (EOF/Ctrl-D) —— 未改动任何配置' });
+        }
+        if (!manual)
+            return done({ ok: false, cancelled: true, reachedStep: 'model', message: '已取消, 未改动任何配置' });
+        manualModel = manual;
+        try {
+            await admitManualModel(providerId, manual);
+        }
+        catch { /* 缓存记不上不影响切换 */ }
+    }
+    const chosenModelId = manualModel ?? modelId;
+    const entry = candidates.find((e) => e.id === chosenModelId) || entries.find((e) => e.id === chosenModelId);
+    // 只回显**这一条真有**的事实; 未知的一律不写 (页脚统一说, 不逐行复读)。
+    //   来源一定要标出来 (live / 上游未见 / 手输) —— 用户要能看出"这个模型是从哪来的"。
+    const srcTag = manualModel ? ' · 手输 (目录未列出, 探测仍真跑一次)'
+        : entry?.upstreamSeen === false ? ' · 上游目录未列出 (探测仍真跑一次)'
+            : entry?.upstreamSeen === true ? ` · ${entry.upstreamOrigin === 'live' ? '上游目录' : '上游目录(缓存)'}`
+                : '';
+    push(`已选模型: ${chosenModelId}${srcTag}`);
+    // ── 4) 生成参数 (reasoning / temperature) ────────────────
+    const params = {};
+    push('步骤 4/7 生成参数');
+    // reasoning: 只有"登记为支持"时才提供开关; 能力未知就不给这一项 (不猜)
+    if (summary.providerReasoning === 'yes') {
+        const r = await pick([
+            { value: 'unset', label: '不设 (沿用配置里的值)' },
+            { value: 'on', label: '开 (请求推理/思考模式)' },
+            { value: 'off', label: '关' },
+        ], `${providerId} 登记支持 reasoning — 要不要开? (本机偏好, 不是模型能力数据)`);
+        if (r === 'on')
+            params.reasoningMode = true;
+        else if (r === 'off')
+            params.reasoningMode = false;
+    }
+    else {
+        verbose(`reasoning: 该供应商的模型级能力未知 → 不提供开关, 也不写默认值`);
+    }
+    const temp = await pick([
+        { value: 'skip', label: '不设 (沿用配置里的值)' },
+        { value: '0', label: 'temperature = 0' },
+        { value: '0.3', label: 'temperature = 0.3' },
+        { value: '0.7', label: 'temperature = 0.7' },
+        { value: '1.0', label: 'temperature = 1.0' },
+        { value: '1.5', label: 'temperature = 1.5' },
+        ...(io.ask ? [{ value: '__custom__', label: '手工输入 (0~2)' }] : []),
+    ], 'temperature (0~2)');
+    if (temp === null)
+        return done({ ok: false, cancelled: true, reachedStep: 'params', message: '已取消, 未改动任何配置' });
+    if (temp === '__custom__') {
+        const raw = await text('temperature (0~2)', '0.7');
+        if (raw === null) {
+            push(EOF_CANCEL);
+            return done({ ok: false, cancelled: true, reachedStep: 'params', message: '输入已结束 (EOF/Ctrl-D) —— 未改动任何配置' });
+        }
+        if (raw === '') {
+            push('没输入 → 本项不设');
+        }
+        else {
+            const n = Number(raw);
+            if (!Number.isFinite(n) || n < 0 || n > 2) {
+                return done({ ok: false, reachedStep: 'params', failureClass: 'invalid_temperature', message: `temperature 只接受 0~2 的数字, 收到 '${raw}' — 未改动任何配置` });
+            }
+            params.temperature = n;
+        }
+    }
+    else if (temp !== 'skip') {
+        params.temperature = Number(temp);
+    }
+    push(`temperature: ${params.temperature === undefined ? '不设' : params.temperature}`);
+    // ── 5) 作用域 ────────────────────────────────────────────
+    let scope = 'global';
+    push('步骤 5/7 作用域');
+    for (let round = 0; round < 2; round++) {
+        const s = await pick([
+            { value: 'global', label: '全局默认 (影响新会话 + 未绑定模型的任务)' },
+            { value: 'session', label: '仅当前会话 (不动全局默认)' },
+        ], '这次切换的作用域?');
+        if (s === null)
+            return done({ ok: false, cancelled: true, reachedStep: 'scope', message: '已取消, 未改动任何配置' });
+        scope = s === 'session' ? 'session' : 'global';
+        if (scope === 'session' && pendingKey) {
+            push('✗ 会话级切换只做路由、不写凭证 —— 要么改成全局默认, 要么先 `bolloon model key ' + providerId + '` 再回来只切路由。');
+            continue;
+        }
+        break;
+    }
+    if (scope === 'session' && pendingKey) {
+        return done({
+            ok: false, reachedStep: 'scope', failureClass: 'credential_scope_conflict',
+            message: '会话级切换不写凭证 — 未改动任何配置 (请先配全局凭证, 再用 --session 只切路由)',
+        });
+    }
+    push(`作用域: ${scope === 'global' ? '全局默认' : '仅当前会话'}`);
+    return await commit(done, push, confirm, verbose, {
+        providerId, summary, pendingKey, credentialAction, modelId: chosenModelId, baseUrl: summary.baseUrl, opts, params, scope,
+    });
+}
+async function commit(done, push, confirm, verbose, a) {
+    const params = a.params || {};
+    const scope = a.scope || 'global';
+    // ── 6) 测试连接 (对**候选**配置探测; 不写任何东西) ─────────
+    // 版面: **失败就直接停**, 一行说清"什么错 + 怎么办" —— 不再问"还要不要继续"
+    //   (那种问句按 y 也照样被第 7 步拦下, 是假选择)。
+    if (a.opts.verify === false) {
+        verbose('步骤 6/7 已按 --no-verify 跳过连通探测 (第 6 步预检与第 7 步切换前校验都关)');
+    }
+    else if (!a.opts.skipProbe) {
+        // 预检必须用**和落盘时同一份凭证**: 本次新输入的 key 优先, 否则用该供应商已配置/环境变量里的那一份。
+        //   (拿不到 key 就不带鉴权头 —— 那确实是"这个供应商现在用不了", 如实报 401, 不假装探测通过。)
+        const probeKey = a.pendingKey || await resolvedApiKeyOf(a.providerId).catch(() => undefined);
+        const t0 = Date.now();
+        const probe = await probeSelection({ provider: a.providerId, model: a.modelId, baseUrl: a.baseUrl, apiKey: probeKey });
+        const ms = Date.now() - t0;
+        if (!probe.ok) {
+            return done({
+                ok: false, reachedStep: 'test', failureClass: probe.failureClass,
+                message: `连不上/不认识这个模型 (${probe.failureClass || '未知'}): ${probe.detail} — 配置与运行时原样未动。`
+                    + (probe.failureClass === 'model_not_found' ? ` 换个模型, 或用 \`bolloon model ${a.providerId} <model>\` 直接指定。` : ''),
+            });
+        }
+        push(`步骤 6/7 连通测试通过 (${a.modelId} @ ${a.baseUrl}, ${ms} ms)`
+            + (probe.modelAcceptedOutsideCatalog ? ' — 上游目录未列出, 但端点接受' : ''));
+        // 第 7 步的"确认"必须先把**要提交的东西**印出来 —— 否则用户是在确认一份看不见的配置。
+        //   版面压到最少: 供应商/模型/作用域/参数 (探测结论上一步已说, 不重复; 基址只在 verbose)。
+        push('步骤 7/7 确认');
+        push(`  ${a.providerId} / ${a.modelId} · ${scope === 'global' ? '全局默认' : '仅当前会话'}`);
+        if (params.temperature !== undefined || params.reasoningMode !== undefined) {
+            push(`  参数: ${params.temperature === undefined ? '' : `temperature=${params.temperature}`}`
+                + `${params.reasoningMode === undefined ? '' : `${params.temperature === undefined ? '' : ' · '}reasoning=${params.reasoningMode ? '开' : '关'}`}`);
+        }
+        verbose(`  基址: ${a.baseUrl}`);
+        verbose(`  凭证: ${a.pendingKey ? '本次新输入的 key (掩码输入, 落盘为全局凭证)' : '沿用已配置 / 环境变量里的那一份'}`);
+        const proceed = a.opts.assumeYes ? true : await confirm('确认按上面的配置切换?', true);
+        if (!proceed)
+            return done({ ok: false, cancelled: true, reachedStep: 'test', message: '已取消, 未改动任何配置' });
+    }
+    else {
+        verbose('步骤 6/7 已跳过预检 (skipProbe) —— 第 7 步的切换前校验仍在');
+    }
+    // ── 7) 唯一写盘点 ───────────────────────────────────────
+    const req = {
+        provider: a.providerId,
+        model: a.modelId,
+        baseUrl: a.baseUrl,
+        scope,
+        ...(a.pendingKey ? { apiKey: a.pendingKey } : {}),
+        ...(a.credentialAction !== 'keep' ? { credentialAction: a.credentialAction } : {}),
+        ...(params.temperature !== undefined ? { temperature: params.temperature } : {}),
+        ...(params.reasoningMode !== undefined ? { reasoningMode: params.reasoningMode } : {}),
+        ...(a.opts.sessionKey ? { sessionKey: a.opts.sessionKey } : {}),
+        ...(a.opts.verify === false ? { verify: false } : {}),
+    };
+    verbose('交给统一入口 selectModel() (写配置 + 更新作用域 + 重建运行时 + 更新会话)');
+    const r = await selectModel(req);
+    // 逐项 ✓/✗ 事实默认**不刷屏** (成功一行, 失败一行); 想看细节走 `--verbose`。
+    for (const c of r.checks || [])
+        verbose(`  ${c}`);
+    if (!r.ok) {
+        return done({
+            ok: false, reachedStep: 'commit', failureClass: r.failureClass,
+            message: `${r.message || '切换失败'} — 配置与运行时保持原样`,
+            checks: r.checks,
+        });
+    }
+    push(`✓ 已切到 ${r.effective?.provider || a.providerId}/${r.effective?.model || a.modelId}`
+        + `${r.effective?.configHash ? ` (hash ${String(r.effective.configHash).slice(0, 12)})` : ''}`
+        + ` · ${scope === 'global' ? '全局默认' : '仅当前会话'}`);
+    return done({ ok: true, reachedStep: 'done', effective: r.effective, checks: r.checks });
+}

package/dist/cli/reply-hygiene.js

@@ -0,0 +1,54 @@
+/**
+ * reply-hygiene.ts — 「对话回复流」卫生: 内部运行日志不许当消息渲染 (2026-09-27)
+ *
+ * 起因 (leo): 会话里的**回复流**出现了给开发者看的运行日志 ——
+ *   `🔄 开始 ReAct 循环...` · `🧷 运行已登记 (run=…, 预算 60 步 / 30 分钟)` ·
+ *   `✅ 处理完成，共 N 次循环` · `🎯 目标仍在进行 (未判完成): …` …
+ * 这些行在 Web 面上有自己的去处 (状态栏 / workflow_step), 但 CLI 交互面的 `onStream`
+ * **就是对话回复流** —— 在那里它们和用户的结论混在一列消息里, 属于无关信息。
+ *
+ * 判据的落点 (为什么不在 CLI 里再写一张子串黑名单):
+ *   旧的写法是"按内容子串猜"(`content.includes('🔄 循环')`), 于是
+ *   `🔄 开始 ReAct 循环...` 这种**说得更早**的一句就漏了 —— 猜不完。
+ *   现在由**发送点 (emit) 自己声明** `internal: true` (见 `pi-sdk-types.StreamEvent`),
+ *   这里只做一件事: 把这个声明翻成"进不进回复流"的唯一判据。
+ *
+ * 进不进回复流 ≠ 删掉:
+ *   被搬走的行**同一个字**要落 `${BOLLOON_HOME:-~/.bolloon}/logs/startup.log`
+ *   (目的地走已有的 `startupLogPath()`, 不新开第二条落盘路径), 并且 `--verbose` / `BOLLOON_VERBOSE=1`
+ *   时原样回到屏上 —— 诊断能力一点不丢。
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { startupLogPath } from './log-gate.js';
+/** 内部运行日志在日志文件里的行首标记 (可 grep, 且明确区分于启动日志的其它行) */
+export const INTERNAL_RUN_LOG_PREFIX = '[运行] ';
+/**
+ * 把一行内部运行日志**落盘** (只落盘, 不管上不上屏)。
+ *
+ * 目的地由**已有**的 `startupLogPath()` 决定 —— 不新开第二条日志路径, 也不自己拼 HOME;
+ * 时间戳格式与启动日志保持一致, 于是 `grep '[运行] '` 就能把"从回复流搬走的那批行"原样捞回来。
+ */
+export function appendInternalRunLog(content, tool) {
+    try {
+        const p = startupLogPath();
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.appendFileSync(p, `[${new Date().toISOString()}] ${internalRunLogLine(content, tool)}\n`);
+    }
+    catch {
+        /* 落盘失败绝不影响对话本身 */
+    }
+}
+/**
+ * 这条 stream 事件是不是**内部运行日志** —— 是则不进对话回复流, 只落日志文件。
+ *
+ * 只认 emit 侧的显式声明 (`internal: true`), 不按内容猜:
+ * 缺省 (未声明) 一律当"用户可见", 保持既有行为不变。
+ */
+export function isInternalRunLog(e) {
+    return !!e && e.type === 'status' && e.internal === true;
+}
+/** 内部运行日志落盘时的那一行 (原文一字不改, 只加可 grep 的前缀与来源工具) */
+export function internalRunLogLine(content, tool) {
+    return `${INTERNAL_RUN_LOG_PREFIX}${tool ? `${tool} · ` : ''}${content}`;
+}