@bolloon/bolloon-agent 0.4.25 → 0.4.26

package/dist/cli/setup-wizard.js

@@ -12,10 +12,12 @@
  *   - io 可注入 → 单测不碰真实 stdin/stdout
  */
 import * as readline from 'readline';
+import { evaluateSetup, providerUsable, readConfigFacts, resolveBolloonHome, } from '../setup/setup-store.js';
+import { runOnboard } from '../setup/onboard.js';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as os from 'os';
-import { llmConfigStore, PROVIDER_INFO, DEFAULT_PROVIDER_CONFIGS } from '../llm/config-store.js';
+import { llmConfigStore, PROVIDER_INFO } from '../llm/config-store.js';
 /** 向导推荐的供应商顺序 (第一个是最省事的国内直连) */
 export const RECOMMENDED_PROVIDERS = [
     'deepseek', 'minimax', 'openai', 'anthropic', 'openrouter', 'gemini',
@@ -108,149 +110,116 @@ export async function writeUserIdentity(name, home = os.homedir()) {
     return { identity, created, file };
 }
 // ---------------------------------------------------------------- 首次运行判断
-function providerUsable(p) {
-    if (!p?.enabled)
-        return false;
-    if (p.apiKey)
-        return true;
-    return p.requiresApiKey === false; // 本地模型 (ollama/local) 不需要 key
-}
+// providerUsable 只有一份实现 (setup-store)
 /** 首次运行: 没有可用供应商, 或还没有用户身份 */
 export async function isFirstRun(home = os.homedir()) {
+    // 2026-09-16 (Phase 1/3): 不再有独立判断 —— 是否"需要引导"由 setup-store 唯一决定。
+    //   fail-closed: 评估不出来 → 视为"需要引导"。
     try {
-        await llmConfigStore.initialize();
-        const cfg = await llmConfigStore.getConfig();
-        const usable = Object.values(cfg.providers || {}).some((p) => providerUsable(p));
-        if (!usable)
-            return true;
-        const user = await readUserIdentity(home);
-        return !user;
+        const ev = await evaluateSetup({ bolloonHome: resolveBolloonHome(process.env, home), light: true });
+        return ev.gate !== 'ready';
     }
-    catch {
-        return false; // 判断失败不阻塞启动
+    catch (e) {
+        console.warn('[setup] 初始化状态评估失败, 按"需要引导"处理 (fail-closed):', String(e?.message || e).slice(0, 160));
+        return true;
     }
 }
-/** 运行初始化向导 (交互式或参数式) */
+/** WizardIO → OnboardIO 适配 (select/confirm 用编号或值回答) */
+function onboardIO(io) {
+    return {
+        print: (m) => io.print(m),
+        ask: async (q, opts) => {
+            for (let i = 0; i < 3; i++) {
+                const v = await io.ask(q, opts?.defaultValue ? { default: opts.defaultValue } : undefined);
+                const val = String(v ?? '').trim() || String(opts?.defaultValue ?? '');
+                if (!opts?.validate)
+                    return val;
+                const r = opts.validate(val);
+                if (r.ok)
+                    return val;
+                io.print(`  ✗ ${r.error || '输入无效'}`);
+            }
+            return String(opts?.defaultValue ?? '');
+        },
+        askHidden: async (q) => {
+            const { askHiddenLine } = await import('./setup-wizard.js').catch(() => ({ askHiddenLine: null }));
+            return io.ask(q, { hidden: true }); // WizardIO 已支持 hidden (不回显)
+        },
+        confirm: async (q, d = true) => {
+            const a = String(await io.ask(`${q} (y/n)`, { default: d ? 'y' : 'n' })).trim().toLowerCase();
+            return a === '' ? d : /^(y|yes|1|true|是)$/.test(a);
+        },
+        select: async (q, choices) => {
+            io.print(q);
+            choices.forEach((c, i) => io.print(`  ${i + 1}) ${c.label}${c.hint ? ` — ${c.hint}` : ''}`));
+            const a = String(await io.ask(`选择 (序号或名称)`, { default: '1' })).trim();
+            if (!a)
+                return choices[0]?.value || '';
+            if (/^\d+$/.test(a) && choices[Number(a) - 1])
+                return choices[Number(a) - 1].value;
+            const hit = choices.find((c) => c.value === a) || choices.find((c) => a && c.value.startsWith(a)) || choices.find((c) => a && c.label.includes(a));
+            return hit?.value || a;
+        },
+    };
+}
+/**
+ * 运行初始化向导 —— 现在是**可恢复阶段执行器**的薄包装 (Phase 2):
+ *   load state → 显示已有 → 收集修改 → 校验 → 真实验证 → 原子提交阶段 → 推进
+ * 失败: 保留已完成步骤 · 不清配置 · 标失败分类 · 给重试/修改/回退入口 · **不显示配置完成**
+ */
 export async function runSetupWizard(opts = {}) {
     const io = opts.io ?? defaultWizardIO();
     const home = opts.home ?? os.homedir();
-    const interactive = opts.interactive !== false;
+    const bolloonHome = resolveBolloonHome(process.env, home);
     const P = (s) => io.print(s);
+    const mode = opts.mode || 'setup';
+    P('');
+    P('╭─ Bolloon 初始化 (可中断, 下次从失败阶段继续) ─────╮');
+    P('│ 身份 → 供应商 → 凭证 → 模型 → 连通性 → 运行时   │');
+    P('╰──────────────────────────────────────────────────╯');
+    // 参数式输入 (非交互/脚本): 先落盘再跑阶段, 保证"输入已保存"
     try {
-        await llmConfigStore.initialize();
+        if (opts.name)
+            await writeUserIdentity(opts.name, home);
+        const prov = opts.provider;
+        if (prov) {
+            const store = llmConfigStore;
+            await store.initialize();
+            await store.updateProvider(prov, { enabled: true });
+            if (opts.apiKey)
+                await store.updateProvider(prov, { apiKey: opts.apiKey });
+            if (opts.model)
+                await store.updateProvider(prov, { model: opts.model });
+            if (mode !== 'reconfigure')
+                await store.setActiveProvider(prov);
+        }
     }
     catch (e) {
-        return { ok: false, error: `读取配置失败: ${String(e?.message || e).slice(0, 200)}` };
-    }
-    P('');
-    P('╭─ Bolloon 初始化 ─────────────────────────────╮');
-    P('│ 三步: 你的称呼 → 模型供应商 → API key + 模型 │');
-    P('╰──────────────────────────────────────────────╯');
-    // ---- 1) 用户称呼 ----
-    const existingUser = await readUserIdentity(home);
-    let name = String(opts.name || '').trim();
-    if (!name && interactive) {
-        name = await io.ask('① 我该怎么称呼你?', { default: existingUser?.name || os.userInfo().username });
+        return { ok: false, error: `参数落盘失败: ${String(e?.message || e).slice(0, 160)}` };
     }
-    if (!name)
-        name = existingUser?.name || os.userInfo().username;
-    const idWrite = await writeUserIdentity(name, home);
-    P(`   身份: ${idWrite.identity.name}${idWrite.created ? ' (已生成新 DID)' : ' (复用已有 DID)'}`);
-    P(`   DID:  ${idWrite.identity.did.slice(0, 42)}...`);
-    P(`   文件: ${idWrite.file}`);
-    // ---- 2) 供应商 ----
-    const cfg = await llmConfigStore.getConfig();
-    const providers = cfg.providers;
-    let provider = String(opts.provider || '').toLowerCase().trim();
-    if (!provider && interactive) {
-        P('');
-        P('② 选一个模型供应商:');
-        RECOMMENDED_PROVIDERS.forEach((p, i) => {
-            const info = PROVIDER_INFO[p] || {};
-            const st = providers[p];
-            const mark = providerUsable(st) ? '🔑 已配置' : (st?.requiresApiKey === false ? '免 key' : '');
-            P(`   ${String(i + 1).padStart(2)}. ${p.padEnd(11)} ${String(info.name || '').padEnd(16)} ${mark}`);
-        });
-        const ans = await io.ask('   序号或名字', { default: cfg.activeProvider });
-        const idx = Number(ans);
-        provider = Number.isFinite(idx) && idx >= 1 && idx <= RECOMMENDED_PROVIDERS.length
-            ? RECOMMENDED_PROVIDERS[idx - 1]
-            : ans.trim().toLowerCase();
-    }
-    if (!provider)
-        provider = cfg.activeProvider;
-    if (!providers[provider]) {
-        return { ok: false, error: `未知供应商 '${provider}'. 可用: ${Object.keys(providers).join(', ')}` };
-    }
-    const info = PROVIDER_INFO[provider] || {};
-    const current = providers[provider];
-    const needsKey = current?.requiresApiKey !== false;
-    // ---- 3) API key ----
-    let apiKey = String(opts.apiKey || '').trim();
-    if (!apiKey)
-        apiKey = String(current?.apiKey || '').trim(); // 已配置的沿用
-    if (!apiKey && needsKey && interactive) {
-        P('');
-        P(`③ ${info.name || provider} 需要 API key (输入不回显, 只写本地 ~/.bolloon/bolloon-config.json)`);
-        apiKey = await io.ask(`   粘贴 ${provider} API key`, { hidden: true });
-        if (!apiKey)
-            P('   ⚠ 未输入 key — 该供应商会保持不可用 (可用 bolloon model key <provider> 之后再补)');
-    }
-    // ---- 4) 模型 ----
-    const models = Array.isArray(info.models) ? info.models : [];
-    let model = String(opts.model || '').trim();
-    if (!model && interactive) {
-        if (models.length > 0)
-            P(`   可选模型: ${models.slice(0, 8).join(' / ')}`);
-        model = await io.ask('④ 用哪个模型?', { default: current?.model || models[0] || '' });
-    }
-    if (!model)
-        model = current?.model || models[0] || '';
-    // ---- 5) 落盘 ----
-    const patch = { enabled: true };
-    if (apiKey)
-        patch.apiKey = apiKey;
-    if (model)
-        patch.model = model;
-    if (!current?.baseUrl)
-        patch.baseUrl = DEFAULT_PROVIDER_CONFIGS[provider]?.baseUrl;
-    await llmConfigStore.updateProvider(provider, patch);
-    const usableNow = apiKey || !needsKey;
-    if (usableNow) {
-        await llmConfigStore.setActiveProvider(provider);
-    }
-    // ---- 6) 连通性测试 ----
-    let test;
-    if (!opts.skipTest && usableNow) {
-        P('');
-        P('⑤ 测试连通性...');
-        try {
-            const r = await llmConfigStore.testProvider(provider);
-            test = { success: !!r.success, latency: r.latency, error: r.error };
-            P(r.success ? `   ✅ 连通 (${r.latency ?? '?'} ms)` : `   ⚠ 未通过: ${String(r.error || '').slice(0, 160)}`);
-        }
-        catch (e) {
-            test = { success: false, error: String(e?.message || e).slice(0, 200) };
-            P(`   ⚠ 测试失败: ${test.error}`);
-        }
-    }
-    P('');
-    P(`✅ 配置完成 — 当前供应商: ${provider}${model ? `, 模型: ${model}` : ''}`);
-    P(`   配置文件: ${path.join(home, '.bolloon', 'bolloon-config.json')}`);
-    P('   开始对话: bolloon --cli');
-    P('');
+    const res = await runOnboard({
+        mode,
+        io: onboardIO(io),
+        home,
+        bolloonHome,
+        targets: opts.targets,
+        skipSteps: opts.skipTest ? ['connectivity'] : undefined,
+        oneShot: opts.interactive === false,
+    });
+    const cfg = await readConfigFacts(bolloonHome).catch(() => null);
     return {
-        ok: true,
-        userName: idWrite.identity.name,
-        provider,
-        model,
-        identityFile: idWrite.file,
-        identityCreated: idWrite.created,
-        test,
+        ok: res.ok,
+        userName: res.state.inputs.name,
+        provider: res.state.inputs.provider,
+        model: res.state.inputs.model,
+        identityFile: getUserIdentityFile(home),
+        identityCreated: !!res.state.inputs.identityDid,
+        test: res.state.checks.connectivityOk ? { success: true } : { success: false, error: res.state.lastError?.message },
+        error: res.ok ? undefined : (res.message || res.actions[0]),
+        // 新增: 结构化状态 (旧调用方看不到也不影响)
+        ...{ gate: res.gate, stage: res.state.stage, summary: res.summary },
     };
 }
-// ---------------------------------------------------------------- /model 命令
-/** 配置状态一览 (供 CLI 会话内 /model 与 bolloon model 共用) */
 export async function formatProviderStatus() {
     await llmConfigStore.initialize();
     const cfg = await llmConfigStore.getConfig();

package/dist/electron/first-run.js

@@ -6,6 +6,7 @@
  */
 import { BrowserWindow, app, ipcMain } from 'electron';
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { firstRunFlagPath, dataDir, logsDir } from './paths';
 import { log } from './logger';
@@ -64,6 +65,26 @@ const OVERLAY_HTML = `
 </body>
 </html>
 `;
+/**
+ * 2026-09-16 (Phase 3): 首启**事实**来自 SetupStore 的状态文件 (setup-state.json),
+ * first-run flag 只决定"要不要自动弹窗"。Electron 不能用 flag 当初始化事实。
+ */
+export function readSetupFact() {
+    try {
+        const p = path.join(os.homedir(), '.bolloon', 'setup-state.json');
+        const js = JSON.parse(fs.readFileSync(p, 'utf8'));
+        const stage = String(js?.stage || 'uninitialized');
+        const ready = stage === 'ready';
+        return { ready, stage, gate: ready ? 'ready' : (stage === 'needs_repair' ? 'repair' : stage === 'blocked' ? 'blocked' : 'setup') };
+    }
+    catch {
+        return { ready: false, stage: 'uninitialized', gate: 'setup' };
+    }
+}
+/** 未 ready → 显示 Onboard (无论 flag 是否已看过) */
+export function shouldShowOnboard() {
+    return !readSetupFact().ready;
+}
 export function hasSeenFirstRun() {
     try {
         return fs.existsSync(firstRunFlagPath());
@@ -120,10 +141,20 @@ export function registerFirstRunIpc() {
     log('first-run IPC handlers registered');
 }
 /** 包装 — 决定要不要弹 overlay */
+/**
+ * 2026-09-16 (Phase 3): 是否弹引导 —— **事实来自 SetupStore** (setup-state.json), flag 只控制"已 ready 后是否还提示"。
+ * 未 ready 时无论 flag 有没有都弹 (初始化没完成的机器不能装作已配置)。
+ */
 export async function maybeShowFirstRun(parent) {
-    if (hasSeenFirstRun())
+    const fact = readSetupFact();
+    if (fact.ready && hasSeenFirstRun())
         return;
-    log('首启 — 弹出引导');
+    if (!fact.ready) {
+        log(`初始化未就绪 (stage=${fact.stage}, gate=${fact.gate}) — 弹出引导 (flag=${hasSeenFirstRun() ? '已看过' : '未看过'})`);
+    }
+    else {
+        log('首启 — 弹出引导');
+    }
     await showFirstRunOverlay(parent);
     app.addRecentDocument(firstRunFlagPath()); // 跟踪最近文档, 让 user 知道有这文件
 }

package/dist/electron-build/electron/first-run.js

@@ -33,6 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSetupFact = readSetupFact;
+exports.shouldShowOnboard = shouldShowOnboard;
 exports.hasSeenFirstRun = hasSeenFirstRun;
 exports.markFirstRunSeen = markFirstRunSeen;
 exports.showFirstRunOverlay = showFirstRunOverlay;
@@ -46,6 +48,7 @@ exports.maybeShowFirstRun = maybeShowFirstRun;
  */
 const electron_1 = require("electron");
 const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const paths_1 = require("./paths");
 const logger_1 = require("./logger");
@@ -104,6 +107,26 @@ const OVERLAY_HTML = `
 </body>
 </html>
 `;
+/**
+ * 2026-09-16 (Phase 3): 首启**事实**来自 SetupStore 的状态文件 (setup-state.json),
+ * first-run flag 只决定"要不要自动弹窗"。Electron 不能用 flag 当初始化事实。
+ */
+function readSetupFact() {
+    try {
+        const p = path.join(os.homedir(), '.bolloon', 'setup-state.json');
+        const js = JSON.parse(fs.readFileSync(p, 'utf8'));
+        const stage = String(js?.stage || 'uninitialized');
+        const ready = stage === 'ready';
+        return { ready, stage, gate: ready ? 'ready' : (stage === 'needs_repair' ? 'repair' : stage === 'blocked' ? 'blocked' : 'setup') };
+    }
+    catch {
+        return { ready: false, stage: 'uninitialized', gate: 'setup' };
+    }
+}
+/** 未 ready → 显示 Onboard (无论 flag 是否已看过) */
+function shouldShowOnboard() {
+    return !readSetupFact().ready;
+}
 function hasSeenFirstRun() {
     try {
         return fs.existsSync((0, paths_1.firstRunFlagPath)());
@@ -160,10 +183,20 @@ function registerFirstRunIpc() {
     (0, logger_1.log)('first-run IPC handlers registered');
 }
 /** 包装 — 决定要不要弹 overlay */
+/**
+ * 2026-09-16 (Phase 3): 是否弹引导 —— **事实来自 SetupStore** (setup-state.json), flag 只控制"已 ready 后是否还提示"。
+ * 未 ready 时无论 flag 有没有都弹 (初始化没完成的机器不能装作已配置)。
+ */
 async function maybeShowFirstRun(parent) {
-    if (hasSeenFirstRun())
+    const fact = readSetupFact();
+    if (fact.ready && hasSeenFirstRun())
         return;
-    (0, logger_1.log)('首启 — 弹出引导');
+    if (!fact.ready) {
+        (0, logger_1.log)(`初始化未就绪 (stage=${fact.stage}, gate=${fact.gate}) — 弹出引导 (flag=${hasSeenFirstRun() ? '已看过' : '未看过'})`);
+    }
+    else {
+        (0, logger_1.log)('首启 — 弹出引导');
+    }
     await showFirstRunOverlay(parent);
     electron_1.app.addRecentDocument((0, paths_1.firstRunFlagPath)()); // 跟踪最近文档, 让 user 知道有这文件
 }

package/dist/electron-build/electron/first-run.js.map

@@ -1 +1 @@
-{"version":3,"file":"first-run.js","sourceRoot":"","sources":["../../../src/electron/first-run.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;GAKG;AACH,uCAAuD;AACvD,MAAY,EAAE,+BAAW;AACzB,MAAY,IAAI,iCAAa;AAC7B,mCAA6D;AAC7D,qCAA+B;AAE/B,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsDpB,CAAC;AAEF;IACE,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,UAAU,CAAC,IAAA,wBAAgB,GAAE,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;IACE,IAAI,CAAC;QACH,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAA,wBAAgB,GAAE,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACpE,EAAE,CAAC,aAAa,CAAC,IAAA,wBAAgB,GAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IACjE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAA,YAAG,EAAC,aAAc,GAAa,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC,CAAC;IACrD,CAAC;AACH,CAAC;AAED,6BAAoC,MAAqB;IACvD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,OAAO,GAAG,IAAI,wBAAa,CAAC;YAChC,MAAM;YACN,KAAK,EAAE,IAAI;YACX,KAAK,EAAE,KAAK;YACZ,WAAW,EAAE,IAAI;YACjB,KAAK,EAAE,GAAG;YACV,MAAM,EAAE,GAAG;YACX,SAAS,EAAE,KAAK;YAChB,OAAO,EAAE,KAAK;YACd,WAAW,EAAE,KAAK;YAClB,WAAW,EAAE,KAAK;YAClB,KAAK,EAAE,SAAS;SACjB,CAAC,CAAC;QAEH,MAAM,OAAO,GAAG,+BAA+B,GAAG,kBAAkB,CAAC,YAAY,CAAC,CAAC;QACnF,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAEzB,8BAA8B;QAC9B,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,gBAAgB,EAAE,CAAC;YACnB,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC,CAAC;QACF,kBAAO,CAAC,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QAEvC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE;YACxB,kBAAO,CAAC,cAAc,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;YACjD,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,qCAAqC;AACrC;IACE,kBAAO,CAAC,MAAM,CAAC,gBAAgB,EAAE,GAAG,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC;IAC1D,kBAAO,CAAC,MAAM,CAAC,qBAAqB,EAAE,GAAG,EAAE,GAAG,gBAAgB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACrE,6EAA6E;IAC7E,kBAAO,CAAC,MAAM,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAAC,IAAA,eAAO,GAAE,CAAC,CAAC;IACtD,kBAAO,CAAC,MAAM,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAAC,IAAA,eAAO,GAAE,CAAC,CAAC;IACtD,IAAA,YAAG,EAAC,mCAAmC,CAAC,CAAC;AAC3C,CAAC;AAED,0BAA0B;AACnB,KAAK,4BAA4B,MAAqB;IAC3D,IAAI,eAAe,EAAE;QAAE,OAAO;IAC9B,IAAA,YAAG,EAAC,WAAW,CAAC,CAAC;IACjB,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAClC,cAAG,CAAC,iBAAiB,CAAC,IAAA,wBAAgB,GAAE,CAAC,CAAC,CAAC,wBAAwB;AACrE,CAAC"}
+{"version":3,"file":"first-run.js","sourceRoot":"","sources":["../../../src/electron/first-run.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1449,6 +1449,46 @@ async function processInputInner(input, comm) {
         }
         return;
     }
+    // 2026-09-16 (2-F): /criteria <goalId> [confirm|propose <text...>] —— 判据：看/确认/改/让 agent 提候选
+    if (cmd === '/criteria' || cmd.startsWith('/criteria ')) {
+        const rest = trimmed.slice('/criteria'.length).trim();
+        try {
+            const { longTermStatus, confirmCriteria, proposeForGoal } = await import('./agents/goal-criteria.js');
+            const { readGoal } = await import('./agents/goal-store.js');
+            const [goalId, action, ...words] = rest.split(/\s+/).filter(Boolean);
+            if (!goalId) {
+                appendLine(`${C_DIM}用法: /criteria <goalId> [confirm | propose | set <判据用;分>]${RESET}`);
+                return;
+            }
+            const g = await readGoal(goalId);
+            if (!g) {
+                appendLine(`${C_ERROR}没有这个目标: ${goalId}${RESET}`);
+                return;
+            }
+            if (action === 'propose') {
+                const p = await proposeForGoal(goalId);
+                appendLine(p.ok ? `${C_DIM}候选判据 (待确认):\n${p.criteria.map((c, i) => `  [${i}] ${c}`).join('\n')}${RESET}` : `${C_ERROR}无法生成判据: ${p.reason}${RESET}`);
+                return;
+            }
+            const list = action === 'set' && words.length ? words.join(' ').split(';').map((x) => x.trim()).filter(Boolean) : undefined;
+            if (action === 'confirm' || list) {
+                const r = await confirmCriteria(goalId, { criteria: list, by: 'cli' });
+                appendLine(r.ok ? `${C_DIM}判据已确认 (v${r.goal?.criteriaVersion}): ${(r.goal?.successCriteria || []).join(' | ')}${RESET}` : `${C_ERROR}${r.reason}${RESET}`);
+                return;
+            }
+            const st = await longTermStatus(goalId);
+            appendLine(`${C_DIM}goal ${g.goalId} [${g.status}] 判据来源=${g.criteriaSource || 'unknown'} 已确认=${g.criteriaConfirmed === true} v${g.criteriaVersion || 1}${RESET}`);
+            g.successCriteria.forEach((c, i) => appendLine(`  ${g.completedCriteria.includes(i) ? '✓' : '·'} [${i}] ${c}`));
+            if (g.proposedCriteria?.length)
+                appendLine(`  ${C_DIM}候选 (未确认): ${g.proposedCriteria.join(' | ')}${RESET}`);
+            appendLine(`  长期完成: ${st.canComplete ? '✅ 可判完成' : `❌ ${st.reason}`}`);
+            appendLine(`  ${C_DIM}检查: ${Object.entries(st.checks).map(([k, v]) => `${k}=${v ? '✓' : '✗'}`).join(' ')}${RESET}`);
+        }
+        catch (e) {
+            appendLine(`${C_ERROR}/criteria 失败: ${String(e?.message || e).slice(0, 200)}${RESET}`);
+        }
+        return;
+    }
     // 2026-09-16 (M2-B): /supervise — 长期执行层 (状态/唤醒原因/手动推进一个周期) · /wake <goalId> — 外部事件唤醒
     if (cmd === '/supervise' || cmd.startsWith('/supervise ')) {
         const arg = trimmed.slice('/supervise'.length).trim();
@@ -3901,6 +3941,21 @@ function parseArgs() {
             case '--supervise':
                 result.supervise = true;
                 break;
+            case '--setup-status':
+                result.setupStatus = true;
+                break;
+            case '--setup-resume':
+                result.setupResume = true;
+                break;
+            case '--setup-repair':
+                result.setupRepair = true;
+                break;
+            case '--setup-reconfigure':
+                result.setupReconfigure = true;
+                break;
+            case '--setup-test':
+                result.setupTest = true;
+                break;
             case '--supervise-once':
                 result.supervise = true;
                 result.superviseOnce = true;
@@ -4333,6 +4388,45 @@ async function main() {
         const mode = args.web ? 'web' : 'cli';
         // 2026-09-16 (2-C.1): 独立 Supervisor 宿主 —— `bolloon --supervise [--supervise-once|--supervise-dry-run]`
         //   长期执行不再依附 web 进程 (页面关掉/CLI 没开也能继续推进 Goal)。
+        // 2026-09-16 (Phase 4): Onboard 统一入口 —— CLI / Web 共用同一条执行器 (src/setup/onboard.ts)
+        //   --setup-status 只读; --setup-resume 从失败阶段继续; --setup-repair 迁移/备份坏文件后就地修;
+        //   --setup-reconfigure 只改选中项 (新配置测通才切 active); --setup-test 重跑连通性 + 运行时。
+        if (args.setupStatus || args.setupResume || args.setupRepair || args.setupReconfigure || args.setupTest) {
+            const mode = args.setupStatus ? 'status' : args.setupRepair ? 'repair' : args.setupReconfigure ? 'reconfigure' : args.setupTest ? 'test' : 'resume';
+            if (mode === 'status') {
+                const { evaluateSetup, describeSetup } = await import('./setup/setup-store.js');
+                const ev = await evaluateSetup();
+                process.stdout.write(describeSetup(ev) + '\n');
+                process.exit(ev.gate === 'ready' ? 0 : 1);
+            }
+            const { defaultWizardIO } = await import('./cli/setup-wizard.js');
+            const { runOnboard } = await import('./setup/onboard.js');
+            const wizIO = defaultWizardIO();
+            const res = await runOnboard({
+                mode: mode,
+                io: {
+                    print: (m) => process.stdout.write(m + '\n'),
+                    ask: async (q, o) => wizIO.ask(q, o?.defaultValue ? { default: o.defaultValue } : undefined),
+                    askHidden: async (q) => wizIO.ask(q, { hidden: true }),
+                    confirm: async (q, d = true) => {
+                        const a = String(await wizIO.ask(`${q} (y/n)`, { default: d ? 'y' : 'n' })).trim().toLowerCase();
+                        return a === '' ? d : /^(y|yes|1|true|是)$/.test(a);
+                    },
+                    select: async (q, choices) => {
+                        process.stdout.write(q + '\n');
+                        choices.forEach((c, i) => process.stdout.write(`  ${i + 1}) ${c.label}${c.hint ? ` — ${c.hint}` : ''}\n`));
+                        const a = String(await wizIO.ask('选择 (序号或名称)', { default: '1' })).trim();
+                        if (!a)
+                            return choices[0]?.value || '';
+                        if (/^\d+$/.test(a) && choices[Number(a) - 1])
+                            return choices[Number(a) - 1].value;
+                        const hit = choices.find((c) => c.value === a) || choices.find((c) => a && c.value.startsWith(a));
+                        return hit?.value || a;
+                    },
+                },
+            });
+            process.exit(res.ok ? 0 : 1);
+        }
         if (args.supervise) {
             const { runStandaloneSupervisorHost } = await import('./agents/supervisor-host.js');
             const res = await runStandaloneSupervisorHost({
@@ -4381,14 +4475,37 @@ async function main() {
         // 2026-09-13: 首次运行引导 — 没有可用模型供应商 / 还没有用户身份时, 先走初始化向导
         //   (放在 CLI 启动前: 用户先回答"你是谁 / 用哪个模型", 再进 TUI 面板)
         if (isCLIInteractive) {
+            // 2026-09-16 (M4 启动硬门禁): 先把初始化事实读出来 —— 未就绪就**先修**, 修不好就非零退出。
+            //   旧行为是"向导失败也只 warn, 照常进对话", 结果是半成品配置能进运行态 (看起来启动成功、实际不可执行)。
+            const w = (m) => process.stderr.write(m.endsWith('\n') ? m : m + '\n');
+            let gateEv = null;
             try {
-                const { isFirstRun, runSetupWizard } = await import('./cli/setup-wizard.js');
-                if (await isFirstRun()) {
-                    await runSetupWizard({ interactive: true });
+                const { refreshSetupState, describeSetup } = await import('./setup/setup-store.js');
+                gateEv = await refreshSetupState({ light: true });
+                if (gateEv.gate !== 'ready') {
+                    w(describeSetup(gateEv));
+                    if (process.env.BOLLOON_SKIP_SETUP === '1') {
+                        w('⚠ BOLLOON_SKIP_SETUP=1 → 诊断模式: 可以看状态/修配置, 但 agent 执行被门禁拦住 (不能绕过)');
+                    }
+                    else {
+                        const { runSetupWizard } = await import('./cli/setup-wizard.js');
+                        await runSetupWizard({ interactive: true });
+                        const after = await refreshSetupState({});
+                        if (after.gate !== 'ready') {
+                            w(describeSetup(after));
+                            w('⛔ 初始化未完成 → 退出 (不会以"看起来能跑"的状态进入对话)');
+                            process.exit(1);
+                        }
+                        w('✅ 初始化完成, 进入正常模式');
+                    }
                 }
             }
             catch (e) {
-                console.warn('[setup] 初始化向导失败 (不阻塞启动):', String(e?.message || e).slice(0, 200));
+                // 评估/向导自身异常: fail-closed —— 不假装就绪
+                w(`⛔ 初始化流程失败 (fail-closed): ${String(e?.message || e).slice(0, 200)}`);
+                w(`   当前状态评估: ${gateEv ? gateEv.gate : '未知 (评估都没跑通)'}`);
+                w('   排查: `bolloon setup --status` (或删掉 ~/.bolloon/setup-state.json 后重跑 setup)');
+                process.exit(1);
             }
         }
         if (isNonInteractive) {

package/dist/llm/config-store.js

@@ -4,11 +4,19 @@
  */
 import * as fs from 'fs/promises';
 import * as path from 'path';
-const CONFIG_DIR = path.join(process.env.HOME || '/tmp', '.bolloon');
+import * as os from 'os';
+import * as fsSync from 'fs';
+/** 2026-09-16 (M1): 不再在模块加载时固定 HOME —— 独立宿主/测试注入/长驻进程都走同一个解析 */
+function configDir() {
+    const env = process.env.BOLLOON_HOME?.trim();
+    if (env)
+        return env;
+    return path.join(process.env.HOME || os.homedir() || '/tmp', '.bolloon');
+}
 // 2026-08-07: llm-config.json → bolloon-config.json (统一配置文件名, Bolloon 自己有写权限)
 //   initialize() 会做一次迁移: 旧文件存在且新文件不存在 → 复制旧内容, 之后统一读写新文件
-const CONFIG_PATH = path.join(CONFIG_DIR, 'bolloon-config.json');
-const LEGACY_CONFIG_PATH = path.join(CONFIG_DIR, 'llm-config.json');
+const CONFIG_PATH = path.join(configDir(), 'bolloon-config.json');
+const LEGACY_CONFIG_PATH = path.join(configDir(), 'llm-config.json');
 export const DEFAULT_PROVIDER_CONFIGS = {
     openai: {
         enabled: false,
@@ -231,6 +239,10 @@ function getDefaultConfig() {
 class LLMConfigStore {
     config = null;
     initialized = false;
+    /** 2026-09-16: 记住加载时用的配置目录 —— 目录变了必须丢弃缓存, 否则会把 A 目录的配置写到 B 目录 */
+    loadedDir = null;
+    /** 2026-09-16: 记住加载时的文件签名 —— 外部改了配置 (repair/agent 工具/用户手改) 必须重新读, 不能一直用旧值 */
+    loadedSig = null;
     // v0.2.15: single-flight lock around read-modify-write of `~/.bolloon/llm-config.json`.
     // Prevents concurrent save() calls from clobbering each other when the user
     // configures two providers back-to-back (e.g. saving gemini, then anthropic, in
@@ -244,10 +256,19 @@ class LLMConfigStore {
         return next;
     }
     async initialize() {
+        // 目录变了 (换 HOME / 独立宿主 / 测试注入): 内存缓存作废, 重新读盘
+        const dir = configDir();
+        const sig = this.fileSignature();
+        if (this.initialized && (this.loadedDir !== dir || this.loadedSig !== sig)) {
+            this.initialized = false;
+            this.config = null;
+        }
         if (this.initialized)
             return;
+        this.loadedDir = dir;
+        this.loadedSig = sig;
         try {
-            await fs.mkdir(CONFIG_DIR, { recursive: true });
+            await fs.mkdir(configDir(), { recursive: true });
             // 2026-08-07: 迁移 — 旧 llm-config.json 存在且新 bolloon-config.json 不存在时复制旧内容
             try {
                 await fs.access(CONFIG_PATH);
@@ -289,6 +310,16 @@ class LLMConfigStore {
         // 2026-08-07: mode 0o600 — 仅当前用户可读写 (含 API key 的敏感配置); Bolloon 自身进程可写
         await fs.writeFile(CONFIG_PATH, JSON.stringify(this.config, null, 2), { mode: 0o600 });
     }
+    /** 配置文件签名 (mtime+size); 不存在时返回 'missing' */
+    fileSignature() {
+        try {
+            const st = fsSync.statSync(configDir() + '/bolloon-config.json');
+            return `${st.mtimeMs}:${st.size}`;
+        }
+        catch {
+            return 'missing';
+        }
+    }
     async getConfig() {
         await this.initialize();
         return { ...this.config };

package/dist/network/agent-network.js

@@ -619,6 +619,16 @@ export class AgentMessaging {
                 console.warn(`[Messaging] Signature verification failed for ${signedMsg.from.substring(0, 20)}`);
                 return false;
             }
+            // 2026-09-16 (2-C.4): 目标关联的真实外部事件 —— 签名已通过校验, 这里再按
+            //   来源 / correlation / 过期 / eventId 去重做一次严格匹配, 只唤醒"正在等这个事件"的 Goal。
+            //   **不在这里启动 agent**: 只写事实 + 唤醒, 由 Supervisor 下一轮继续。
+            try {
+                const { tryDeliverGoalEvent } = await import('./goal-event-bridge.js');
+                await tryDeliverGoalEvent(signedMsg, fromPeerId);
+            }
+            catch (e) {
+                console.warn(`[Messaging] goal event bridge 失败 (不影响普通消息):`, e?.message);
+            }
             const handler = this.messageHandlers.get(signedMsg.type);
             if (handler) {
                 handler(data, fromPeerId, signedMsg.from);