@bolloon/bolloon-agent 0.1.42 → 0.2.1

package/dist/agents/pi-sdk.js

@@ -963,7 +963,32 @@ class PiAgentSession {
                 const cmd = String(args.command || '').trim();
                 if (!cmd)
                     return { success: false, error: 'command 必填' };
-                const argList = String(args.args || '').split(',').map(s => s.trim()).filter(Boolean);
+                // 2026-06-19: 支持多种 args 格式
+                //   1. JSON 数组: ["checkout", "-b", "branch"] (LLM 偏好)
+                //   2. 逗号分隔: "checkout,-b,branch" (旧格式)
+                //   3. 字符串: "checkout -b branch" (单参数)
+                let argList = [];
+                const rawArgs = args.args;
+                if (Array.isArray(rawArgs)) {
+                    argList = rawArgs.map((s) => String(s).trim()).filter(Boolean);
+                }
+                else if (typeof rawArgs === 'string') {
+                    const trimmed = rawArgs.trim();
+                    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+                        // JSON 数组字符串
+                        try {
+                            const parsed = JSON.parse(trimmed);
+                            if (Array.isArray(parsed)) {
+                                argList = parsed.map((s) => String(s).trim()).filter(Boolean);
+                            }
+                        }
+                        catch { /* fall through to comma split */ }
+                    }
+                    if (argList.length === 0) {
+                        // 逗号分隔 或 单字符串
+                        argList = trimmed.split(',').map(s => s.trim()).filter(Boolean);
+                    }
+                }
                 const timeoutMs = Number(args.timeoutMs) || 30000;
                 const result = await shellExec(cmd, argList, { timeoutMs });
                 if (result.deniedByGuard) {
@@ -989,6 +1014,10 @@ class PiAgentSession {
                 return await runSelfImproveLoop(goal);
             }
         });
+        // 2026-06-24: Wallet + Polymarket + Safe 工具集 (基于 constraint-runtime/src/tools/)
+        //   真实可用实现: ethers v6 + JsonRpcProvider, 默认走 eth.llamarpc.com
+        //   agent 可以创建/导入/查询 EVM 钱包, 查余额, 签名, 转账, 部署 Safe 多签钱包
+        this._registerWalletTools();
         // list_skills 工具: 列出当前 session 已加载的 skills
         // 加载源: ~/.bolloon/skills/ → <cwd>/.bolloon/skills/ → ~/.boll/skills/
         this.tools.set('list_skills', {
@@ -1416,7 +1445,7 @@ class PiAgentSession {
             description: '跑 vitest 测试. 自动 bail (失败就停). 默认 60s timeout.',
             parameters: { pattern: '可选, 文件 glob e.g. "src/agents/pi-sdk.test.ts"', timeoutMs: '可选, 默认 60000' },
             execute: async (args) => {
-                const argv = ['vitest', 'run', '--reporter=basic', '--no-color', '--bail=1'];
+                const argv = ['vitest', 'run', '--reporter=default', '--no-color', '--bail=1'];
                 if (args.pattern)
                     argv.push(String(args.pattern));
                 const timeoutMs = parseInt(String(args.timeoutMs || '60000')) || 60000;
@@ -1634,10 +1663,13 @@ class PiAgentSession {
         // M2.4 (2026-06-17): 缓存 tool 定义 — registerTools() 在构造时调一次, 此后不变
         if (this.cachedToolDefinitions)
             return this.cachedToolDefinitions;
-        const defs = ['可用工具:'];
+        const defs = ['可用工具 (name(params) - 简介):'];
         for (const tool of this.tools.values()) {
-            const params = Object.entries(tool.parameters).map(([k, v]) => `${k}: ${v}`).join(', ');
-            defs.push(`- ${tool.name}(${params}) - ${tool.description}`);
+            // 2026-06-19: 压缩 tool 定义 — 只显示参数名 (不显示描述, 减少 60% 长度)
+            //   完整 description 在 history 第一轮注入 (getToolDefinitionsFull 调用), 后续轮只看简短
+            //   避免 system prompt 太大导致 minimax 撞 max_tokens 输出空
+            const paramNames = Object.keys(tool.parameters).join(',');
+            defs.push(`- ${tool.name}(${paramNames})`);
         }
         this.cachedToolDefinitions = defs.join('\n');
         return this.cachedToolDefinitions;
@@ -2995,6 +3027,10 @@ Workspace root folder: ${this.cwd}
             /\btool\s*=>\s*["'](\w+)["']/,
             // 兼容: [TOOL_CALL] 块内 JSON 形式 {"name": "x", "args": {...}}
             /\[TOOL_CALL\][\s\S]*?\{\s*"name"\s*:\s*"(\w+)"\s*,\s*"args"\s*:\s*(\{[\s\S]*?\})/i,
+            // 2026-06-19: 兼容 LLM 输出 "tool_name {json_args}" 形式 (单行, 无 name 字段)
+            //   实际输出: write_file {"path":"docs/test.md","content":"..."}
+            //   只在行首/新行匹配, 避免误匹配普通文本里的 "foo {...}"
+            /(?:^|\n)(\w+)\s+(\{[\s\S]*?\})(?=\n|$)/,
             // 2026-06-15 修: 兼容 LLM 输出的 XML 格式 <tool_name>...<arg>value</arg>...</tool_name>
             //   实际 LLM 习惯: <shell_exec>\n<command>ls</command>\n<args>["-la", "..."]</args>\n</shell_exec>
             /<(\w+)>([\s\S]*?)<\/\1>/,
@@ -3026,15 +3062,28 @@ Workspace root folder: ${this.cwd}
                 else if (rawArgs && /<\w+>[\s\S]*<\/\w+>/.test(rawArgs)) {
                     // 2026-06-15 修: XML 格式, 解析内嵌子标签 <argname>value</argname>
                     //   例: <command>ls</command>\n<args>["-la","~/.bolloon/skills"]</args>
-                    const xmlArgPattern = /<(\w+)>([\s\S]*?)<\/\1>/g;
-                    let xmlMatch;
-                    while ((xmlMatch = xmlArgPattern.exec(rawArgs)) !== null) {
-                        const argName = xmlMatch[1];
-                        const argValue = xmlMatch[2].trim();
+                    // 2026-06-19 修: 也支持 <parameter name="X">value</parameter> 形式 (OpenAI Hermes function_call)
+                    const paramRe = /<parameter\s+name=["'](\w+)["']>([\s\S]*?)<\/parameter>/g;
+                    let pMatch;
+                    while ((pMatch = paramRe.exec(rawArgs)) !== null) {
+                        const argName = pMatch[1];
+                        const argValue = pMatch[2].trim();
                         if (argName && argValue) {
                             args[argName] = argValue;
                         }
                     }
+                    // 如果没匹配到 <parameter>, 用普通 XML 子标签
+                    if (Object.keys(args).length === 0) {
+                        const xmlArgPattern = /<(\w+)>([\s\S]*?)<\/\1>/g;
+                        let xmlMatch;
+                        while ((xmlMatch = xmlArgPattern.exec(rawArgs)) !== null) {
+                            const argName = xmlMatch[1];
+                            const argValue = xmlMatch[2].trim();
+                            if (argName && argValue) {
+                                args[argName] = argValue;
+                            }
+                        }
+                    }
                 }
                 else if (rawArgs) {
                     // 形参串, 形如 key: value, key2: value2
@@ -3062,6 +3111,251 @@ Workspace root folder: ${this.cwd}
         console.log('[DBG parseToolCall] result:', JSON.stringify(r), 'content head:', JSON.stringify(content.substring(0, 200)));
         return r;
     }
+    /**
+     * 2026-06-24: 注册 Wallet + Polymarket + Safe 工具
+     *   真实实现 (ethers v6 + JsonRpcProvider) — agent 可以创建 EVM 钱包, 查余额, 转账, 签名, Polymarket 下单
+     *   工具来源: src/constraint-runtime/src/tools/{WalletTools,PolymarketSDK,SafeSDK}/
+     */
+    _registerWalletTools() {
+        // === WalletTools (EVM 钱包) ===
+        this.tools.set('wallet_create', {
+            name: 'wallet_create',
+            description: '创建新 EVM 钱包 (BIP-39 12 词助记词 + 私钥 + 地址). 私钥会在响应中返回, agent 应当保存到 ~/.bolloon/wallets/<address>.json',
+            parameters: {},
+            execute: async () => {
+                try {
+                    const { createWallet } = await import('../constraint-runtime/dist/tools/WalletTools/createWallet.js').catch(() => import('../constraint-runtime/src/tools/WalletTools/createWallet.js'));
+                    const r = await createWallet();
+                    return { success: true, output: `✅ 钱包创建成功:\n  address: ${r.address}\n  privateKey: ${r.privateKey}\n  mnemonic: ${r.mnemonic}\n  createdAt: ${r.createdAt}\n\n⚠️ 请 agent 立即把私钥保存到 ~/.bolloon/wallets/${r.address}.json` };
+                }
+                catch (e) {
+                    return { success: false, error: `创建失败: ${String(e.message || e)}` };
+                }
+            }
+        });
+        this.tools.set('wallet_import', {
+            name: 'wallet_import',
+            description: '导入已有 EVM 钱包 (用助记词或私钥)',
+            parameters: { mnemonic: '可选, 12/15/18/21/24 词助记词', privateKey: '可选, 0x 开头的私钥' },
+            execute: async (args) => {
+                try {
+                    const { importWallet } = await import('../constraint-runtime/dist/tools/WalletTools/importWallet.js').catch(() => import('../constraint-runtime/src/tools/WalletTools/importWallet.js'));
+                    const r = await importWallet({ mnemonic: args.mnemonic, privateKey: args.privateKey });
+                    return { success: true, output: `✅ 钱包导入成功:\n  address: ${r.address}\n  privateKey: ${r.privateKey}\n  source: ${r.source}` };
+                }
+                catch (e) {
+                    return { success: false, error: `导入失败: ${String(e.message || e)}` };
+                }
+            }
+        });
+        this.tools.set('wallet_get_balance', {
+            name: 'wallet_get_balance',
+            description: '查 EVM 钱包 ETH 余额. 默认 RPC = https://eth.llamarpc.com, 可指定其他 RPC URL',
+            parameters: { address: '0x 开头的 EVM 地址 (必填)', rpcUrl: '可选 RPC URL (默认 eth.llamarpc.com)' },
+            execute: async (args) => {
+                try {
+                    const { getBalance } = await import('../constraint-runtime/dist/tools/WalletTools/getBalance.js').catch(() => import('../constraint-runtime/src/tools/WalletTools/getBalance.js'));
+                    const r = await getBalance({ address: String(args.address), rpcUrl: args.rpcUrl });
+                    return { success: true, output: `💰 ${r.address}\n  ${r.balanceEth} ${r.symbol} (${r.balance} wei)` };
+                }
+                catch (e) {
+                    return { success: false, error: `查余额失败: ${String(e.message || e)}` };
+                }
+            }
+        });
+        this.tools.set('wallet_sign_message', {
+            name: 'wallet_sign_message',
+            description: '用私钥对消息做 EIP-191 personal_sign 签名',
+            parameters: { message: '要签名的消息 (必填)', privateKey: '0x 开头的私钥 (必填)' },
+            execute: async (args) => {
+                try {
+                    const { signMessage } = await import('../constraint-runtime/dist/tools/WalletTools/signMessage.js').catch(() => import('../constraint-runtime/src/tools/WalletTools/signMessage.js'));
+                    const r = await signMessage({ message: String(args.message), privateKey: String(args.privateKey) });
+                    return { success: true, output: `✅ 签名完成:\n  address: ${r.address}\n  message: ${r.message}\n  signature: ${r.signature}` };
+                }
+                catch (e) {
+                    return { success: false, error: `签名失败: ${String(e.message || e)}` };
+                }
+            }
+        });
+        this.tools.set('wallet_send_tx', {
+            name: 'wallet_send_tx',
+            description: '用 EVM 钱包发送交易 (转账 ETH 或调用合约). 走 EIP-1559, 默认 RPC = eth.llamarpc.com',
+            parameters: { privateKey: '私钥 (必填)', to: '接收地址 (必填)', value: '发送 wei 数量 (必填)', data: '可选 0x 开头的 calldata', rpcUrl: '可选 RPC URL' },
+            execute: async (args) => {
+                try {
+                    const { sendTransaction } = await import('../constraint-runtime/dist/tools/WalletTools/sendTransaction.js').catch(() => import('../constraint-runtime/src/tools/WalletTools/sendTransaction.js'));
+                    const r = await sendTransaction({
+                        privateKey: String(args.privateKey),
+                        to: String(args.to),
+                        value: String(args.value),
+                        data: args.data ? String(args.data) : undefined,
+                        rpcUrl: args.rpcUrl,
+                    });
+                    return { success: true, output: `✅ 交易已发送:\n  hash: ${r.hash}\n  from: ${r.from} → to: ${r.to}\n  value: ${r.value} wei\n  status: ${r.status}\n  blockNumber: ${r.blockNumber || '(pending)'}\n  gasUsed: ${r.gasUsed || '?'}` };
+                }
+                catch (e) {
+                    return { success: false, error: `交易失败: ${String(e.message || e)}` };
+                }
+            }
+        });
+        this.tools.set('wallet_transfer_token', {
+            name: 'wallet_transfer_token',
+            description: '用 EVM 钱包转 ERC20 token (需要 token 合约地址)',
+            parameters: { privateKey: '私钥 (必填)', tokenAddress: 'ERC20 合约地址 (必填)', to: '接收地址 (必填)', amount: 'token 数量 (人类可读, 自动按 decimals 转换)', decimals: '可选 token decimals (默认查合约)', rpcUrl: '可选 RPC URL' },
+            execute: async (args) => {
+                try {
+                    const { transferToken } = await import('../constraint-runtime/dist/tools/WalletTools/transferToken.js').catch(() => import('../constraint-runtime/src/tools/WalletTools/transferToken.js'));
+                    const r = await transferToken({
+                        privateKey: String(args.privateKey),
+                        tokenAddress: String(args.tokenAddress),
+                        to: String(args.to),
+                        amount: String(args.amount),
+                        decimals: args.decimals ? Number(args.decimals) : undefined,
+                        rpcUrl: args.rpcUrl,
+                    });
+                    return { success: true, output: `✅ Token 转账完成:\n  hash: ${r.hash}\n  ${r.amount} ${r.tokenAddress.substring(0, 10)}...\n  from: ${r.from} → to: ${r.to}\n  status: ${r.status}` };
+                }
+                catch (e) {
+                    return { success: false, error: `转账失败: ${String(e.message || e)}` };
+                }
+            }
+        });
+        this.tools.set('wallet_autopay', {
+            name: 'wallet_autopay',
+            description: '设置自动付款 (订阅/定期扣款, 用 SafeSDK 自动执行). 实际能力取决于 SafeSDK autopay 实现',
+            parameters: { from: '付款方地址 (必填)', to: '收款方地址 (必填)', amount: '金额 (必填)', interval: '周期 (e.g. daily/weekly/monthly)', token: '可选, 默认 ETH' },
+            execute: async (args) => {
+                try {
+                    const mod = await import('../constraint-runtime/dist/tools/WalletTools/autoPay.js').catch(() => import('../constraint-runtime/src/tools/WalletTools/autoPay.js'));
+                    const fn = mod.autoPay || mod.setAutoPay || mod.default;
+                    if (!fn)
+                        return { success: false, error: 'autoPay 接口未找到' };
+                    const r = await fn({
+                        from: String(args.from), to: String(args.to), amount: String(args.amount),
+                        interval: String(args.interval || 'monthly'), token: args.token,
+                    });
+                    return { success: true, output: `✅ 自动付款已设置: ${JSON.stringify(r)}` };
+                }
+                catch (e) {
+                    return { success: false, error: `设置失败: ${String(e.message || e)}` };
+                }
+            }
+        });
+        // === PolymarketSDK (预测市场) ===
+        this.tools.set('polymarket_list_markets', {
+            name: 'polymarket_list_markets',
+            description: '列出 Polymarket 预测市场 (用 Polymarket CLOB API). limit 默认 50',
+            parameters: { limit: '可选 数量 (默认 50)', offset: '可选 偏移', closed: '可选 是否只显示已关闭 (默认 false = 只显示活跃)' },
+            execute: async (args) => {
+                try {
+                    const { listMarkets } = await import('../constraint-runtime/dist/tools/PolymarketSDK/listMarkets.js').catch(() => import('../constraint-runtime/src/tools/PolymarketSDK/listMarkets.js'));
+                    const markets = await listMarkets({
+                        limit: args.limit ? Number(args.limit) : 50,
+                        offset: args.offset ? Number(args.offset) : 0,
+                        closed: args.closed ? String(args.closed) === 'true' : false,
+                    });
+                    if (!markets || markets.length === 0) {
+                        return { success: true, output: '📊 Polymarket 当前没有活跃市场 (或 API 不可达, 因为 constraint-runtime 是占位实现, 需要装 polymarket-sdk 包)' };
+                    }
+                    const lines = markets.slice(0, 10).map((m, i) => `  ${i + 1}. [${m.id}] ${m.question}\n     vol=${m.volume} active=${m.active}`);
+                    return { success: true, output: `📊 Polymarket 找到 ${markets.length} 个市场 (前 10):\n${lines.join('\n')}` };
+                }
+                catch (e) {
+                    return { success: false, error: `查询失败: ${String(e.message || e)}` };
+                }
+            }
+        });
+        this.tools.set('polymarket_get_market', {
+            name: 'polymarket_get_market',
+            description: '获取单个 Polymarket 市场的详情 (id/conditionId 都可)',
+            parameters: { marketId: '市场 ID (必填)' },
+            execute: async (args) => {
+                try {
+                    const mod = await import('../constraint-runtime/dist/tools/PolymarketSDK/getMarket.js').catch(() => import('../constraint-runtime/src/tools/PolymarketSDK/getMarket.js'));
+                    const fn = mod.getMarket || mod.default;
+                    const m = await fn(String(args.marketId));
+                    if (!m)
+                        return { success: false, error: '市场不存在' };
+                    return { success: true, output: `📊 市场详情:\n  ${JSON.stringify(m, null, 2).substring(0, 1500)}` };
+                }
+                catch (e) {
+                    return { success: false, error: `查询失败: ${String(e.message || e)}` };
+                }
+            }
+        });
+        this.tools.set('polymarket_get_orders', {
+            name: 'polymarket_get_orders',
+            description: '查询 Polymarket 订单 (需要 CLOB client + auth, 当前 constraint-runtime 是占位实现)',
+            parameters: { marketId: '可选 按市场 ID 过滤' },
+            execute: async (args) => {
+                try {
+                    const { getOrders } = await import('../constraint-runtime/dist/tools/PolymarketSDK/getOrders.js').catch(() => import('../constraint-runtime/src/tools/PolymarketSDK/getOrders.js'));
+                    const orders = await getOrders(args.marketId ? { marketId: String(args.marketId) } : {});
+                    return { success: true, output: `📋 订单列表: ${JSON.stringify(orders, null, 2).substring(0, 1500)}` };
+                }
+                catch (e) {
+                    return { success: false, error: `查询失败: ${String(e.message || e)}` };
+                }
+            }
+        });
+        this.tools.set('polymarket_create_order', {
+            name: 'polymarket_create_order',
+            description: '在 Polymarket 下单 (BUY/SELL, price 0-1, size USDC). 当前 constraint-runtime 是占位实现, 实际下单需要 CLOB client + 私钥签名',
+            parameters: { marketId: '市场 ID (必填)', side: 'BUY 或 SELL (必填)', price: '价格 0-1 (必填)', size: '数量 USDC (必填)' },
+            execute: async (args) => {
+                try {
+                    const { createOrder } = await import('../constraint-runtime/dist/tools/PolymarketSDK/createOrder.js').catch(() => import('../constraint-runtime/src/tools/PolymarketSDK/createOrder.js'));
+                    const r = await createOrder({
+                        marketId: String(args.marketId),
+                        side: String(args.side).toUpperCase() === 'SELL' ? 'SELL' : 'BUY',
+                        price: Number(args.price),
+                        size: Number(args.size),
+                    });
+                    if (r.success)
+                        return { success: true, output: `✅ 订单: ${r.message}` };
+                    return { success: false, error: r.message, output: r.message };
+                }
+                catch (e) {
+                    return { success: false, error: `下单失败: ${String(e.message || e)}` };
+                }
+            }
+        });
+        this.tools.set('polymarket_cancel_order', {
+            name: 'polymarket_cancel_order',
+            description: '取消 Polymarket 订单 (order ID)',
+            parameters: { orderId: '订单 ID (必填)' },
+            execute: async (args) => {
+                try {
+                    const { cancelOrder } = await import('../constraint-runtime/dist/tools/PolymarketSDK/cancelOrder.js').catch(() => import('../constraint-runtime/src/tools/PolymarketSDK/cancelOrder.js'));
+                    const r = await cancelOrder({ orderId: String(args.orderId) });
+                    if (r.success)
+                        return { success: true, output: `✅ 取消订单: ${r.message}` };
+                    return { success: false, error: r.message, output: r.message };
+                }
+                catch (e) {
+                    return { success: false, error: `取消失败: ${String(e.message || e)}` };
+                }
+            }
+        });
+        // === SafeSDK (多签钱包) ===
+        this.tools.set('safe_deploy', {
+            name: 'safe_deploy',
+            description: '部署 Safe 多签钱包 (需要 owners/threshold 参数)',
+            parameters: { owners: 'JSON 数组 owner 地址 (必填)', threshold: '需要几个签名 (必填, e.g. 2)' },
+            execute: async (args) => {
+                try {
+                    const { deploySafe } = await import('../constraint-runtime/dist/tools/SafeSDK/deploySafe.js').catch(() => import('../constraint-runtime/src/tools/SafeSDK/deploySafe.js'));
+                    const owners = Array.isArray(args.owners) ? args.owners : JSON.parse(String(args.owners));
+                    const r = await deploySafe({ owners, threshold: Number(args.threshold) });
+                    return { success: true, output: `✅ Safe 部署: ${JSON.stringify(r)}` };
+                }
+                catch (e) {
+                    return { success: false, error: `部署失败: ${String(e.message || e)}` };
+                }
+            }
+        });
+    }
     /**
      * 2026-06-19: 工具名大小写不敏感 + Claude Code 风格别名映射
   

package/dist/electron/config.js

@@ -0,0 +1,16 @@
+/**
+ * 常量配置 (env 解析在这里集中, 不散在 main 流程)
+ */
+import { app } from 'electron';
+export const DEFAULT_PORT = 54188;
+/** Hard-pin to loopback; LAN exposure must be explicit. */
+export const DEFAULT_HOST = '127.0.0.1';
+export const WEB_SERVER_STARTUP_TIMEOUT_MS = 15_000;
+export const MAIN_WINDOW_DEFAULT = { width: 1200, height: 800 };
+export const MAIN_WINDOW_MIN = { width: 800, height: 600 };
+export function preferredPort() {
+    const raw = process.env.ELECTRON_PORT || process.env.PORT;
+    const n = parseInt(raw || '', 10);
+    return Number.isFinite(n) && n > 0 && n < 65536 ? n : DEFAULT_PORT;
+}
+export const isDev = process.env.NODE_ENV === 'development' || !app.isPackaged;

package/dist/electron/dialogs.js

@@ -0,0 +1,71 @@
+/**
+ * 文件 dialog 桥 (open / save / dir) + 安全的 fs 桥 (read / write / exists)
+ *
+ * 5MB read 上限保护 — 渲染进程直接 fs.readFile 没法做限制, 走主进程就有界
+ * 所有 handler 解析 event.sender 拿到 window, 让 dialog 模态在该窗口上
+ */
+import { BrowserWindow, dialog, ipcMain } from 'electron';
+import * as fs from 'fs';
+import * as path from 'path';
+import { log } from './logger';
+const MAX_READ_BYTES = 5 * 1024 * 1024; // 5MB
+function windowFor(event) {
+    return BrowserWindow.fromWebContents(event.sender);
+}
+function resolveSafe(target) {
+    // 不去硬限制路径 — user 给 renderer 暴露 fs 已经信任了, 这里只 normalize
+    return path.resolve(target);
+}
+export function registerDialogIpc() {
+    ipcMain.handle('dialog:open-file', async (event, opts = {}) => {
+        const win = windowFor(event);
+        const result = await dialog.showOpenDialog(win, {
+            title: opts.title,
+            defaultPath: opts.defaultPath,
+            filters: opts.filters,
+            properties: opts.properties ?? ['openFile'],
+        });
+        return { canceled: result.canceled, filePaths: result.filePaths };
+    });
+    ipcMain.handle('dialog:save-file', async (event, opts = {}) => {
+        const win = windowFor(event);
+        const result = await dialog.showSaveDialog(win, {
+            title: opts.title,
+            defaultPath: opts.defaultPath,
+            filters: opts.filters,
+        });
+        return { canceled: result.canceled, filePath: result.filePath };
+    });
+    ipcMain.handle('dialog:open-directory', async (event, opts = {}) => {
+        const win = windowFor(event);
+        const result = await dialog.showOpenDialog(win, {
+            title: opts.title,
+            defaultPath: opts.defaultPath,
+            properties: ['openDirectory', 'createDirectory'],
+        });
+        return { canceled: result.canceled, filePaths: result.filePaths };
+    });
+    ipcMain.handle('fs:read-text-file', async (_event, opts) => {
+        const target = resolveSafe(opts.path);
+        const stat = fs.statSync(target);
+        if (stat.size > MAX_READ_BYTES) {
+            throw new Error(`文件过大: ${stat.size} > ${MAX_READ_BYTES} bytes`);
+        }
+        return fs.readFileSync(target, { encoding: opts.encoding ?? 'utf8' });
+    });
+    ipcMain.handle('fs:write-text-file', async (_event, opts) => {
+        const target = resolveSafe(opts.path);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, opts.content, { encoding: opts.encoding ?? 'utf8' });
+    });
+    ipcMain.handle('fs:path-exists', async (_event, opts) => {
+        try {
+            fs.accessSync(resolveSafe(opts.path));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    log('dialog + fs IPC handlers registered');
+}

package/dist/electron/first-run.js

@@ -0,0 +1,129 @@
+/**
+ * 首启检测 + 引导浮层
+ *
+ * 标记文件写在 userData (不是 ~/.bolloon/), 卸载 app 自然清掉
+ * 引导窗是父主窗的 modal, frame=false, 透明背景; 关闭时标记写入
+ */
+import { BrowserWindow, app, ipcMain } from 'electron';
+import * as fs from 'fs';
+import * as path from 'path';
+import { firstRunFlagPath, dataDir, logsDir } from './paths';
+import { log } from './logger';
+const OVERLAY_HTML = `
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8" />
+<style>
+  :root { color-scheme: light dark; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    margin: 0; padding: 32px 28px;
+    background: rgba(245,245,247,0.97);
+    color: #1d1d1f;
+    height: 100vh; box-sizing: border-box;
+  }
+  @media (prefers-color-scheme: dark) {
+    body { background: rgba(28,28,30,0.97); color: #f5f5f7; }
+  }
+  h1 { font-size: 18px; margin: 0 0 14px; font-weight: 600; }
+  p  { font-size: 13px; line-height: 1.55; margin: 8px 0; }
+  code {
+    font-family: ui-monospace, "SF Mono", Menlo, monospace;
+    font-size: 12px; padding: 1px 5px;
+    background: rgba(0,0,0,0.06); border-radius: 3px;
+  }
+  @media (prefers-color-scheme: dark) {
+    code { background: rgba(255,255,255,0.08); }
+  }
+  .btn {
+    display: inline-block; margin-top: 18px; padding: 8px 18px;
+    background: #007aff; color: #fff; border: none; border-radius: 6px;
+    font-size: 13px; font-weight: 500; cursor: pointer;
+  }
+  .btn:hover { background: #0066d6; }
+  ul { padding-left: 20px; }
+  li { font-size: 13px; line-height: 1.7; }
+</style>
+</head>
+<body>
+<h1>欢迎使用 Bolloon Agent</h1>
+<p>你的数据存放在本地, 不上传:</p>
+<ul>
+  <li>配置 / 频道 / P2P 密钥: <code id="data"></code></li>
+  <li>运行日志: <code id="logs"></code></li>
+</ul>
+<p>所有数据在卸载后仍保留 — 想清理就手动删除 ~/.bolloon/。</p>
+<button class="btn" id="ok">知道了</button>
+<script>
+  const ok = document.getElementById('ok');
+  ok.addEventListener('click', () => window.electronAPI.markFirstRunSeen());
+  document.getElementById('data').textContent = window.electronAPI.getDataPathSync?.() || '';
+  document.getElementById('logs').textContent = window.electronAPI.getLogsPathSync?.() || '';
+</script>
+</body>
+</html>
+`;
+export function hasSeenFirstRun() {
+    try {
+        return fs.existsSync(firstRunFlagPath());
+    }
+    catch {
+        return false;
+    }
+}
+export function markFirstRunSeen() {
+    try {
+        fs.mkdirSync(path.dirname(firstRunFlagPath()), { recursive: true });
+        fs.writeFileSync(firstRunFlagPath(), new Date().toISOString());
+    }
+    catch (err) {
+        log(`写入首启标记失败: ${err.message}`, 'warn');
+    }
+}
+export function showFirstRunOverlay(parent) {
+    return new Promise((resolve) => {
+        const overlay = new BrowserWindow({
+            parent,
+            modal: true,
+            frame: false,
+            transparent: true,
+            width: 520,
+            height: 360,
+            resizable: false,
+            movable: false,
+            minimizable: false,
+            maximizable: false,
+            title: 'Welcome',
+        });
+        const dataUrl = 'data:text/html;charset=utf-8,' + encodeURIComponent(OVERLAY_HTML);
+        overlay.loadURL(dataUrl);
+        // 一次性的 IPC handler, 关闭后清掉避免累积
+        const handler = () => {
+            markFirstRunSeen();
+            overlay.close();
+        };
+        ipcMain.once('first-run:ack', handler);
+        overlay.on('closed', () => {
+            ipcMain.removeListener('first-run:ack', handler);
+            resolve();
+        });
+    });
+}
+/** 注册 IPC handlers (给 preload 桥用) */
+export function registerFirstRunIpc() {
+    ipcMain.handle('first-run:seen', () => hasSeenFirstRun());
+    ipcMain.handle('first-run:mark-seen', () => { markFirstRunSeen(); });
+    // 同步值 (不用 ipcRenderer.invoke 的 await) — 用 exposeInMainWorld 的 sync getter 更顺
+    ipcMain.handle('first-run:data-dir', () => dataDir());
+    ipcMain.handle('first-run:logs-dir', () => logsDir());
+    log('first-run IPC handlers registered');
+}
+/** 包装 — 决定要不要弹 overlay */
+export async function maybeShowFirstRun(parent) {
+    if (hasSeenFirstRun())
+        return;
+    log('首启 — 弹出引导');
+    await showFirstRunOverlay(parent);
+    app.addRecentDocument(firstRunFlagPath()); // 跟踪最近文档, 让 user 知道有这文件
+}

package/dist/electron/ipc.js

@@ -0,0 +1,16 @@
+/**
+ * IPC handler 集中注册 — version / userData path / open-external (legacy 3 个)
+ * dialog/fs 的注册在 dialogs.ts; updater 的注册在 updater.ts
+ */
+import { app, ipcMain, shell } from 'electron';
+import { userDataDir, dataDir } from './paths';
+import { log } from './logger';
+export function registerCoreIpc() {
+    ipcMain.handle('get-version', () => app.getVersion());
+    ipcMain.handle('get-user-data-path', () => userDataDir());
+    ipcMain.handle('get-data-path', () => dataDir()); // 跟 userData 分开, 渲染层要用
+    ipcMain.handle('open-external', async (_event, url) => {
+        await shell.openExternal(url);
+    });
+    log('core IPC handlers registered');
+}