@bolloon/bolloon-agent 0.4.33 → 0.5.1

package/dist/llm/tool-name.js

@@ -0,0 +1,220 @@
+/**
+ * tool-name.ts — 工具名「出网前的唯一净化边界」(2026-09-26)
+ *
+ * 为什么要这个文件:
+ *   OpenAI 兼容 API 对 `tools[i].function.name` 有硬约束 —— 必须匹配
+ *   `^[a-zA-Z0-9_-]{1,64}$`. 只要**第 121 个**工具的名字里有一个非法字符 (`.` `:` `/`
+ *   空格 / 中文 ...), 整个请求就被 400 拒掉:
+ *
+ *     Invalid 'tools[120].function.name': string does not match pattern.
+ *     Expected a string that matches the pattern '^[a-zA-Z0-9_-]+$'.
+ *
+ *   表现是「网页端明明配好了 API, 一跑就失败」—— 根因在**发包形状**, 不在凭据。
+ *   本仓曾注册 6 个带点的工具名 (`contact.list_authorized` 一族), 命中这个坑。
+ *
+ * 设计铁律:
+ *   1. **唯一边界**: 净化只在 `pi-ai.ts` 的 `generateText()` 里做一次 (那里是全仓唯一
+ *      产出 wire 形状 tools 数组的地方). 业务代码一个都不许自己做净化 —— 否则同一次改动
+ *      要有 N 个调用点跟着改, 迟早漏一个.
+ *   2. **确定性, 不是随机**: 非法字符 → `_`; 超长 → 前 55 字符 + `_` + 原名 sha256 前 8 位
+ *      (同一次运行里同一原名永远得到同一个 API 名).
+ *   3. **派发不断**: 净化时把 `原名 → API 名` 同时反向登记 (原名 ↔ API 名双射), 回程
+ *      (`resolveApiToolName`) 把 LLM 回吐的 API 名还原成原名, 再交给 `this.tools.get()`.
+ *      LLM 也可能照 system prompt 里的原名回吐 —— 原名在表里就直接穿透.
+ *   4. **碰撞不许静默**: 两个**不同**原名净化后同名 → 抛 `ToolNameCollisionError`, 消息里
+ *      把两个原名都点名. 绝不悄悄合并或悄悄改名 (那会让 LLM 调到的工具和它以为的不是一个).
+ *   5. **不猜**: 没有名字 / 空名字的工具也是非法形状 → 抛错点名, 不静默丢掉.
+ *
+ * 真正「覆盖所有入口」的依据: CLI / Web / MCP / 技能 / 子 Agent / 长期任务全都走
+ * `getMinimax().chat(..., tools)` → `PiAIModel.generateText()` → `callOpenAI()`,
+ * 全仓只有这一条产出 tools 的路径 (见 `scripts/verify-tool-names.ts` 的源码级断言).
+ */
+import * as crypto from 'crypto';
+/** OpenAI 兼容 API 对 function.name 的硬约束 */
+export const TOOL_NAME_MAX_LENGTH = 64;
+/** 允许的字符集: 字母 / 数字 / 下划线 / 连字符 */
+export const TOOL_NAME_CHAR_CLASS = 'a-zA-Z0-9_-';
+/** 完整形状约束 (1..64, 只含安全字符) */
+export const TOOL_NAME_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
+/** 太长时的截断长度: 55 + '_' + 8 位 hash = 64, 正好贴着上限 */
+const TRUNCATE_KEEP = 55;
+/** 严格形状校验 (不做任何修补) */
+export function isValidToolName(name) {
+    return typeof name === 'string' && TOOL_NAME_PATTERN.test(name);
+}
+/** 名字里的非法字符 (去重, 按出现顺序) —— 给探针/门报「违规字符是什么」用 */
+export function illegalCharsOf(name) {
+    const out = [];
+    for (const ch of String(name ?? '')) {
+        if (!/[a-zA-Z0-9_-]/.test(ch) && !out.includes(ch))
+            out.push(ch);
+    }
+    return out;
+}
+/** 原名指纹 (sha256 前 8 位 hex) —— 超长截断的去碰撞后缀 */
+export function toolNameFingerprint(name) {
+    return crypto.createHash('sha256').update(String(name), 'utf8').digest('hex').slice(0, 8);
+}
+/**
+ * 纯函数净化: 非法字符 → `_`; 超长 → 截断 + 稳定 hash 后缀.
+ * 已经是合法名的原样返回 (幂等, 再跑一次不变).
+ */
+export function sanitizeToolName(name) {
+    const raw = String(name ?? '');
+    let s = raw.replace(new RegExp(`[^${TOOL_NAME_CHAR_CLASS}]`, 'g'), '_');
+    if (s.length > TOOL_NAME_MAX_LENGTH) {
+        s = `${s.slice(0, TRUNCATE_KEEP)}_${toolNameFingerprint(raw)}`;
+    }
+    // 空名 / 全非法字符且被清空 (理论上不会, 上面都是替换成 '_') —— 兜底成可派发的稳定名
+    if (s.length === 0)
+        s = `tool_${toolNameFingerprint(raw)}`;
+    return s;
+}
+/** 两个不同原名净化后撞名 —— 点名两方, 拒绝发包 */
+export class ToolNameCollisionError extends Error {
+    apiName;
+    names;
+    constructor(apiName, names) {
+        super(`工具名净化后撞名: ${names.map((n) => `"${n}"`).join(' 与 ')} 都会净化为 "${apiName}" —— ` +
+            `拒绝发包 (两个不同工具共用一个 API 名会让 LLM 调到的实现不可知). ` +
+            `请给其中一个改名, 只剩安全字符 [${TOOL_NAME_CHAR_CLASS}] 且 ≤64 字符.`);
+        this.name = 'ToolNameCollisionError';
+        this.apiName = apiName;
+        this.names = names;
+    }
+}
+/**
+ * 原名 ↔ API 名 双射表.
+ *   正向: 出网时把原名登记进来拿 API 名 (碰撞 → 抛错, 不静默).
+ *   反向: 回程把 LLM 回吐的 API 名还原成原名 (未知名原样穿透, 由业务侧报「未知工具」).
+ */
+export class ToolNameRouteTable {
+    byApi = new Map();
+    byOriginal = new Map();
+    /** 登记一个原名, 返回它的 API 名. 撞名 → ToolNameCollisionError. */
+    register(original) {
+        const orig = String(original ?? '');
+        if (isValidToolName(orig)) {
+            // 合法名不动: 但也要防「另一个原名净化成它」的撞名 (下面 byApi 会处理)
+            const api = orig;
+            const holder = this.byApi.get(api);
+            if (holder !== undefined && holder !== orig) {
+                throw new ToolNameCollisionError(api, [holder, orig]);
+            }
+            this.byApi.set(api, orig);
+            this.byOriginal.set(orig, api);
+            return api;
+        }
+        const api = sanitizeToolName(orig);
+        const holder = this.byApi.get(api);
+        if (holder !== undefined && holder !== orig) {
+            throw new ToolNameCollisionError(api, [holder, orig]);
+        }
+        this.byApi.set(api, orig);
+        this.byOriginal.set(orig, api);
+        return api;
+    }
+    /** 批量登记 */
+    registerAll(originals) {
+        return originals.map((n) => this.register(n));
+    }
+    /** 原名 → API 名 (没登记过就现算, 不登记 —— 给纯查询用) */
+    apiNameOf(original) {
+        const known = this.byOriginal.get(String(original ?? ''));
+        if (known !== undefined)
+            return known;
+        return isValidToolName(original) ? original : sanitizeToolName(original);
+    }
+    /**
+     * API 名 → 原名 (回程派发用).
+     * 不在表里 (LLM 照 system prompt 里的原名回吐 / 编了个名字) → 原样返回,
+     * 交给业务侧 `tools.get()` 走「未知工具」分支 — 不在这里吞掉.
+     */
+    resolveToOriginal(apiName) {
+        const hit = this.byApi.get(String(apiName ?? ''));
+        return hit !== undefined ? hit : String(apiName ?? '');
+    }
+    /** 是否知道这个 API 名 */
+    knows(apiName) {
+        return this.byApi.has(String(apiName ?? ''));
+    }
+    /** 全部映射 (原名 → API 名), 按登记顺序 */
+    get mappings() {
+        const seen = new Set();
+        const out = [];
+        for (const [api, original] of this.byApi.entries()) {
+            if (seen.has(original))
+                continue;
+            seen.add(original);
+            out.push({ original, api, changed: original !== api });
+        }
+        return out;
+    }
+    /** 被改写过的部分 (改名清单) */
+    get changed() {
+        return this.mappings.filter((m) => m.changed);
+    }
+    /** 表里已知的原名个数 */
+    get size() {
+        return this.byApi.size;
+    }
+    /** 清空 (测试用; 业务路径不该调) */
+    clear() {
+        this.byApi.clear();
+        this.byOriginal.clear();
+    }
+}
+/**
+ * 进程级单例: 出网净化与回程派发共用同一张表.
+ * (出网在 pi-ai.ts, 派发在 pi-sdk.ts / workflow-pivot-loop.ts —— 只有共享一份才保证还原得到真名)
+ */
+export const globalToolNameRoutes = new ToolNameRouteTable();
+/**
+ * **唯一**的出网净化入口: 把 wire 形状的 tools 数组里的 `function.name` 逐个净化,
+ * 顺便把映射登记进 `globalToolNameRoutes` 供回程派发还原.
+ *
+ * - 不改入参 (返回新数组 / 新对象), 调用方拿去发包即可;
+ * - 没名字 / 空名字 → 抛错 (说不出名字的工具本来就是坏形状, 不许静默丢);
+ * - 撞名 → ToolNameCollisionError (点名两个原名).
+ */
+export function sanitizeToolsForApi(tools, table = globalToolNameRoutes) {
+    if (!Array.isArray(tools))
+        return tools;
+    const out = new Array(tools.length);
+    for (let i = 0; i < tools.length; i++) {
+        const tool = tools[i];
+        const original = tool?.function?.name;
+        if (typeof original !== 'string' || original.length === 0) {
+            throw new Error(`工具 #${i} 没有可用的 function.name (拿到 ${JSON.stringify(original)}) —— 拒绝发包: ` +
+                `OpenAI 兼容 API 要求每个工具都有 name 且匹配 /^[a-zA-Z0-9_-]{1,64}$/`);
+        }
+        const api = table.register(original);
+        out[i] = api === original ? tool : { ...tool, function: { ...tool.function, name: api } };
+    }
+    return out;
+}
+/** 回程: LLM 回吐的名字 → 注册表真名 (未知名原样穿透) */
+export function resolveApiToolName(apiName, table = globalToolNameRoutes) {
+    return table.resolveToOriginal(apiName);
+}
+/**
+ * 给「文本解析」路径用的已知名集合: 原名 + 它们的 API 名.
+ * LLM 在文本里回吐的可能是净化后的名字 (prompt/工具面里给的是 API 名),
+ * 只用原名集合过滤会把这类调用直接丢掉.
+ */
+export function expandKnownToolNames(names, table = globalToolNameRoutes) {
+    const out = new Set();
+    for (const n of names) {
+        out.add(n);
+        const api = table.apiNameOf(n);
+        out.add(api);
+        // 预登记, 保证回程还原得到
+        try {
+            table.register(n);
+        }
+        catch {
+            // 撞名: 交给出网时的 sanitizeToolsForApi 抛 (那里能给出「拒绝发包」的上下文)
+        }
+    }
+    return out;
+}

package/dist/orbitdb/cid-database.js

@@ -23,9 +23,41 @@ import * as dagCbor from '@ipld/dag-cbor';
 import { sha256 } from 'multiformats/hashes/sha2';
 import { concat as uint8Concat } from 'uint8arrays/concat';
 import { createOrbitDB } from '@orbitdb/core';
+import * as orbitdbCoreNs from '@orbitdb/core';
+/**
+ * 运行时取 `IPFSAccessController` (2026-09-24)。
+ *
+ * 它在运行时是**真具名导出** (`@orbitdb/core` 4.0.0 `src/index.js:26`, 经
+ * `./access-controllers/index.js` 二级再导出), 但该包是**纯 JS 包**: `package.json`
+ * 既无 `types` 也无 `exports`、包内没有任何 `.d.ts` —— TS7 从 JS 推断导出集时看不见
+ * 这个二级再导出, `import { IPFSAccessController }` 直接 TS2305。
+ * 所以从命名空间按需取一次并显式收窄到已知形状; 不给整个模块上 `any`
+ * (createOrbitDB / OrbitDB / KeyValue 仍照旧受类型检查)。
+ */
+const IPFSAccessController = orbitdbCoreNs.IPFSAccessController;
 import { createBolloonIpfs } from './ipfs-node.js';
 import * as path from 'path';
 import * as os from 'os';
+/**
+ * store 打不开 (地址不可解析 / 区块不在本地且没有 block broker 能去网上取)。
+ *
+ * 2026-09-24: 原来 `openStoreByAddress` 失败返回 null, 上游 (gateway-group) 把它当"空群",
+ * 于是"读不到"被显示成"没有消息"。改成**抛**: 打不开 ≠ 没内容。
+ */
+export class OrbitDBStoreUnreachableError extends Error {
+    address;
+    cause;
+    dataDir;
+    code = 'STORE_UNREACHABLE';
+    constructor(address, cause, dataDir) {
+        const why = String(cause?.message ?? cause ?? '未知原因').slice(0, 200);
+        super(`store 不可达 (${address}): ${why}`);
+        this.address = address;
+        this.cause = cause;
+        this.dataDir = dataDir;
+        this.name = 'OrbitDBStoreUnreachableError';
+    }
+}
 /** 内容 → CID (dag-cbor, sha2-256, codec 0x71); 先 JSON 清洗 (dag-cbor 不支持 undefined) */
 export async function contentToCid(obj) {
     const cleaned = JSON.parse(JSON.stringify(obj)); // 丢弃 undefined 字段
@@ -34,6 +66,26 @@ export async function contentToCid(obj) {
     return CID.createV1(0x71, hash).toString();
 }
 const home = () => process.env.HOME || os.homedir() || '/tmp';
+/**
+ * OrbitDB 身份在 keystore 里的槽名 (2026-09-24)。
+ * 固定槽名 = 同一 dataDir 下每个进程读到**同一对密钥 / 同一个身份**。
+ * 不固定 (@orbitdb/core 默认 createId() 随机 32 位) 会让每个进程变成新写入者,
+ * 于是 `canAppend` 拿新身份去比对老 manifest 的 write 列表 → 一律拒绝。
+ */
+const ORBITDB_IDENTITY_ID = 'bolloon';
+/**
+ * `opts.accessController.write` → OrbitDB v4 的大写 `AccessController` 工厂 (2026-09-24)。
+ *
+ * @orbitdb/core v4 的 `open(address, options)` **只认大写 `AccessController`** (一个构造函数),
+ * 小写 `accessController: { write: [...] }` 会被静默丢弃 → 新 store 落回默认策略
+ * (`IPFSAccessController`: `write = write || [创建者身份 id]`, 即创建者独占写)。
+ * 于是 gateway-group 一直传的 `write:['*']` (「群成员可广播」) **从来没生效过**。
+ * 这里把已成文的选项接上; 对已存在的地址, manifest 里的 AC 仍优先 (这里不改变既有群)。
+ */
+function accessControllerOption(opts) {
+    const write = opts?.accessController?.write;
+    return Array.isArray(write) && write.length ? { AccessController: IPFSAccessController({ write }) } : {};
+}
 /**
  * OrbitDB 后端实现。单例: 同一进程只建一个 (helia/OrbitDB 都是重量级节点)。
  */
@@ -46,15 +98,29 @@ export class OrbitDBAdapter {
     constructor(dataDir = path.join(home(), '.bolloon', 'orbitdb')) {
         this.dataDir = dataDir;
     }
+    /** 落盘位置 (未初始化时 null; 诊断/验收用) */
+    get ipfsPaths() {
+        return this.node?.paths ?? null;
+    }
     /** 懒初始化: 首次使用时启动 helia + OrbitDB + 打开 keyvalue store */
     async ensure() {
         if (this.db)
             return;
         this.node = await createBolloonIpfs(path.join(this.dataDir, 'ipfs'));
-        this._orbitdb = await createOrbitDB({
+        // 2026-09-24: 身份必须**跨进程稳定**。不给 id 时 @orbitdb/core 用 createId()
+        // (32 位随机串) 当 keystore 槽名 (src/orbitdb.js:43 `id = id || await createId()`
+        // → :61 `createIdentity({ id })`) → 每个进程一对新密钥 → 新身份 → 写自己的 store
+        // 会被访问控制拒掉 ("Key … is not allowed to write to the log")。
+        // 给固定槽名后, 密钥从 <dataDir>/stores/keystore 读出复用 → 同 dataDir 同身份。
+        // 类型注: `id` 是 @orbitdb/core 的真选项 (src/orbitdb.js:33), 但 TS7 从 JS 推断出的
+        // 参数类型漏了它 → 显式取 Parameters<typeof createOrbitDB>[0] 再补 { id }
+        // (不裸 any 掉整个入参)。
+        const init = {
             ipfs: this.node.helia,
             directory: path.join(this.dataDir, 'stores'),
-        });
+            id: ORBITDB_IDENTITY_ID,
+        };
+        this._orbitdb = await createOrbitDB(init);
         this.db = await this._orbitdb.open('bolloon-cid-store', { type: 'keyvalue' });
         // 共享底层实例 (只读暴露)
         this.orbitdb = this._orbitdb;
@@ -192,33 +258,32 @@ export class OrbitDBAdapter {
      */
     async openStore(name, type = 'keyvalue', opts) {
         await this.ensure();
-        const options = { type };
-        if (opts?.accessController)
-            options.accessController = opts.accessController;
+        const options = { type, ...accessControllerOption(opts) };
         const raw = (await this._orbitdb.open(name, options));
         return this.wrapStore(raw);
     }
     /**
      * 2026-08-14: 按地址打开远端 store (Agent Gateway 共享网络 / 群组)。
-     * replica=true → 只读副本: 拉取复制但不写回 (自动加入网络不污染他人 registry)。
-     * replica=false → 可写 (群组: events store 配 write:'*' 时成员可广播)。
+     *
+     * 2026-09-24: 失败改为**抛 OrbitDBStoreUnreachableError** (含原始错误原因),
+     * 不再 `console.warn` + return null —— 那让"整个群读不到"在上层显示成"群里没有消息"。
+     *
+     * 2026-09-24 (修正既有错述): **不再往 OrbitDB 传 `replica`** ——
+     * `@orbitdb/core` 4.0.0 的 `open()` 参数表里没有它 (src/orbitdb.js:118), 传了也被丢,
+     * 之前的"replica=true 只读副本"是**不存在的语义**(等于什么都没做)。入参保留以兼容
+     * 既有调用点, 但不再冒充 OrbitDB 选项。可写与否由 manifest 里的 ACL + 调用方是否 `put` 决定。
+     * `opts.accessController` 在**打开既有地址**时同样不生效 (见接口注释: AC 由 manifest 决定)。
      */
     async openStoreByAddress(address, type = 'keyvalue', opts) {
         await this.ensure();
         try {
-            const options = { type };
-            if (opts?.replica === false)
-                options.replica = false;
-            else
-                options.replica = true;
-            if (opts?.accessController)
-                options.accessController = opts.accessController;
+            const options = { type, ...accessControllerOption(opts) };
             const raw = (await this._orbitdb.open(address, options));
             return this.wrapStore(raw);
         }
         catch (err) {
-            console.warn(`[orbitdb] openStoreByAddress 失败: ${String(err?.message || err).slice(0, 160)}`);
-            return null;
+            // 大声失败: 带上地址 + 原始原因 (最常见: "No block brokers capable of retrieving blocks ...")
+            throw new OrbitDBStoreUnreachableError(address, err, this.dataDir);
         }
     }
     async close() {

package/dist/orbitdb/ipfs-node.js

@@ -1,5 +1,5 @@
 /**
- * ipfs-node.ts — Bolloon 的 OrbitDB 底层 IPFS 节点工厂 (2026-08-06)
+ * ipfs-node.ts — Bolloon 的 OrbitDB 底层 IPFS 节点工厂 (2026-08-06; 落盘 2026-09-24)
  *
  * 基于 helia 7:
  *   - createHelia() 内部已 withLibp2p 但**不传 opts** → 无法自定义 services
@@ -10,10 +10,26 @@
  *     必须显式列出要保留的默认服务 (dht/identify/keychain/...)
  *   - withLibp2p().start() 之后 libp2p getter 才可用 (之前抛 NotStartedError)
  *
+ * 2026-09-24 **区块/datastore 落盘修复** (跨进程可重开的根因):
+ *   原来 createHeliaLight 只传 codecs/hashers → helia 用默认 MemoryBlockstore / MemoryDatastore,
+ *   而 OrbitDB 的 manifest 与 oplog 条目都走 IPFSBlockStorage(ipfs.blockstore) 存
+ *   (@orbitdb/core/src/storage/ipfs-block.js)。于是 `~/.bolloon/orbitdb/` 下只有 stores/
+ *   (keystore + log/_heads 的 LevelDB), 没有 ipfs/ 块存储 —— store 只活在创建它的那个进程里。
+ *   新进程用地址重开必挂在 manifestStore.get():
+ *     "No block brokers capable of retrieving blocks are configured, the CID bafyrei… cannot be fetched"
+ *   现在: FsBlockstore(dataDir/blocks) + FsDatastore(dataDir/datastore) 真落盘。
+ *   · datastore 顺带持久化 pin (helia pins) 与 libp2p 私钥
+ *     (@helia/libp2p: loadOrCreateSelfKey(helia.datastore) + opts.datastore ??= helia.datastore)
+ *     → 同一 dataDir 的 peerId 跨进程稳定。
+ *   · 这两个包是 Node 专用 (node:fs / node:path); 本文件只被 Node 侧 import,
+ *     浏览器入口 (client.ts / mobile-core.ts / a2ui-client.tsx) 到不了这里 —— 不伤 Web 包。
+ *
  * 跑法: npx tsx scripts/smoke-orbitdb.ts
  */
 import { createHeliaLight } from 'helia';
 import { withLibp2p } from '@helia/libp2p';
+import { FsBlockstore } from 'blockstore-fs';
+import { FsDatastore } from 'datastore-fs';
 import * as dagCbor from '@ipld/dag-cbor';
 import * as dagJson from '@ipld/dag-json';
 import * as json from 'multiformats/codecs/json';
@@ -37,13 +53,25 @@ import * as os from 'os';
 /**
  * 创建 Bolloon 用的 helia 节点 (libp2p 完整默认服务 + gossipsub pubsub)。
  * dataDir 持久化节点身份/数据 (默认 ~/.bolloon/orbitdb-ipfs)。
+ *
+ * 2026-09-24: dataDir 下真落两个目录 —— `blocks/` (区块) 与 `datastore/` (pin + peerkey)。
+ * 目录不可写时**直接抛** (不退回内存: 静默退回正好是"新进程读不到群"的根因)。
  */
 export async function createBolloonIpfs(dataDir) {
-    const dir = dataDir ?? path.join(process.env.HOME || os.homedir() || '/tmp', '.bolloon', 'orbitdb-ipfs');
+    const dir = path.resolve(dataDir ?? path.join(process.env.HOME || os.homedir() || '/tmp', '.bolloon', 'orbitdb-ipfs'));
+    const blocksDir = path.join(dir, 'blocks');
+    const datastoreDir = path.join(dir, 'datastore');
+    // 落盘存储: 不传这两个, helia 默认 MemoryBlockstore/MemoryDatastore → 进程退出即丢区块
+    const blockstore = new FsBlockstore(blocksDir);
+    const datastore = new FsDatastore(datastoreDir);
+    await blockstore.open(); // 建目录 + F_OK|W_OK 探测, 失败抛 OpenFailedError (不静默)
+    await datastore.open();
     // createHeliaLight 无 libp2p → withLibp2p 手动装配 (可传 services)
     // codecs/hashers 照抄 createHelia 默认: OrbitDB 的 log entry 用 dag-cbor (codec 113),
     // 不注册会报 "Could not load codec for 113"
     const helia = withLibp2p(createHeliaLight({
+        blockstore,
+        datastore,
         codecs: [dagCbor, dagJson, json],
         hashers: [sha512],
     }), {
@@ -71,6 +99,7 @@ export async function createBolloonIpfs(dataDir) {
     return {
         helia,
         peerId,
+        paths: { dataDir: dir, blocksDir, datastoreDir },
         start: async () => { await helia.start(); },
         stop: async () => { await helia.stop(); },
     };

package/dist/setup/onboard.js

@@ -104,9 +104,9 @@ const stepProvider = {
         }
         try {
             await store.updateProvider(picked, { enabled: true });
-            // setup 模式直接激活; reconfigure 要等测试通过才切换 active (失败不破坏旧配置)
-            if (c.mode !== 'reconfigure')
-                await store.setActiveProvider(picked);
+            // 2026-09-26 (P6): 这里**不再**直接 `setActiveProvider` —— 激活是"切换", 只能走统一入口,
+            //   而且必须等 key/模型齐了、连通实测过了才切 (见 stepConnectivity 的成功分支)。
+            //   早切的问题: 那时还没有 key, 切过去等于把 effective 配置指到一个用不了的供应商。
         }
         catch (err) {
             return { ok: false, errorClass: 'io', message: `写配置失败: ${String(err?.message || err).slice(0, 120)}` };
@@ -114,7 +114,7 @@ const stepProvider = {
         return {
             ok: true,
             patch: { inputs: { provider: picked }, checks: { providerSelected: true } },
-            note: `${picked} 已 ${c.mode === 'reconfigure' ? '标记为候选 (测试通过后切换)' : '激活'}`,
+            note: `${picked} 已 ${c.mode === 'reconfigure' ? '标记为候选 (测试通过后切换)' : '标记为待启用 (连通实测通过后由统一入口切换)'}`,
         };
     },
 };
@@ -202,7 +202,30 @@ const stepConnectivity = {
         c.io.print(`用最终保存的 provider/key/baseUrl/model 真实测试 ${provider} …`);
         const res = await store.testProvider(provider);
         if (res?.success) {
-            return { ok: true, patch: { checks: { connectivityOk: true, connectivityAt: new Date().toISOString(), connectivityErrorClass: undefined } }, note: `通过 (${res.latency ?? '?'}ms)` };
+            // 2026-09-26 (P6): 测试通过之后**才**真正切换 —— 而且只有一处实现: 统一入口 `selectModel()`。
+            //   此前 setup 模式在 stepProvider 里直接 `setActiveProvider` (那时还没有 key, 也没探测过),
+            //   reconfigure 模式则根本不切换 —— 两个都不算"同一语义"。
+            //   这里 `verify:false`: 刚在上面真测过一次, 入口不用再打一次上游 (重复探测是浪费, 不是严谨)。
+            try {
+                const { selectModel } = await import('../llm/model-selection.js');
+                const sw = await selectModel({ provider, model: c.state.inputs.model, scope: 'global', verify: false });
+                if (!sw.ok) {
+                    return {
+                        ok: false,
+                        errorClass: sw.failureClass === 'missing_api_key' ? 'auth' : 'config',
+                        message: `连接是通的, 但切换没有落盘 [${sw.failureClass}]: ${sw.message}`,
+                        retryable: false,
+                    };
+                }
+                return {
+                    ok: true,
+                    patch: { checks: { connectivityOk: true, connectivityAt: new Date().toISOString(), connectivityErrorClass: undefined } },
+                    note: `通过 (${res.latency ?? '?'}ms) · 已由统一入口切到 ${sw.effective.provider}/${sw.effective.model}`,
+                };
+            }
+            catch (err) {
+                return { ok: false, errorClass: 'runtime', message: `连通但切换失败: ${String(err?.message || err).slice(0, 160)}` };
+            }
         }
         const raw = String(res?.error || '未知错误');
         const cls = /401|403|key/i.test(raw) ? 'auth' : /429|限流/i.test(raw) ? 'network' : /404|端点|baseUrl/i.test(raw) ? 'config' : /timeout|超时/i.test(raw) ? 'timeout' : /fetch|network|ECONN/i.test(raw) ? 'network' : 'unknown';
@@ -220,11 +243,14 @@ const stepRuntime = {
         const details = [];
         try {
             const mod = await import('../llm/pi-ai.js');
-            mod.initMinimax?.();
+            // 2026-09-26 (P6): 运行时**只由统一入口装配** —— `installRuntime` 是唯一那个 initMinimax 调用点,
+            //   这里不再自己 `initMinimax()` (那会让"按配置文件装配"和"按有效配置装配"分叉成两条)。
+            const { applyEffectiveToRuntime } = await import('../llm/model-selection.js');
+            const eff = await applyEffectiveToRuntime();
             const model = mod.getMinimax?.() || mod.getModel?.();
             if (!model)
-                return { ok: false, errorClass: 'runtime', message: 'initMinimax 之后仍拿不到模型对象' };
-            details.push('initMinimax ✓');
+                return { ok: false, errorClass: 'runtime', message: '统一入口装配之后仍拿不到模型对象' };
+            details.push(`统一入口装配 ✓ (${eff.provider}/${eff.model})`);
             const chat = model.chat || model.generate || model.complete || model.call;
             if (typeof chat !== 'function') {
                 return { ok: false, errorClass: 'runtime', message: '运行时对象没有可调用的 chat/generate 接口 —— 只有 singleton 不算 ready' };