botmux 2.26.0 → 2.27.1

package/dist/cli.js

@@ -17,7 +17,7 @@
  *   botmux autostart enable|disable|status — manage boot-time autostart (launchd / user systemd)
  */
 import { execSync, spawnSync, spawn } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync, readlinkSync, appendFileSync, statSync, unlinkSync } from 'node:fs';
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync, renameSync, readdirSync, readlinkSync, appendFileSync, statSync, unlinkSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -26,6 +26,7 @@ import { createRequire } from 'node:module';
 import { createHmac, randomBytes } from 'node:crypto';
 import { enableAutostart, disableAutostart, autostartStatus, refreshAutostart } from './autostart.js';
 import { tmuxEnv } from './setup/ensure-tmux.js';
+import { writeBotsJsonAtomic as writeBotsAtomic } from './setup/bots-store.js';
 import { logger } from './utils/logger.js';
 import { firstPositional } from './cli/arg-utils.js';
 // CLI subcommands (send/thread/bots/list/etc) print JSON to stdout for
@@ -144,28 +145,209 @@ function ask(rl, question) {
     return new Promise(resolve => rl.question(question, resolve));
 }
 // ─── Setup helpers ──────────────────────────────────────────────────────────
-function printLarkPermissions() {
-    console.log('请先在飞书开放平台创建应用: https://open.feishu.cn/app\n');
-    console.log('需要的权限:');
-    console.log('  - im:message (发送/接收消息)');
-    console.log('  - im:message.group_at_msg (群消息)');
-    console.log('  - im:resource (文件下载)');
-    console.log('  - im:chat (群信息)');
-    console.log('  - contact:user.base:readonly (用户信息)\n');
-    console.log('启用事件订阅 (WebSocket 模式):');
-    console.log('  - im.message.receive_v1');
-    console.log('  - card.action.trigger\n');
+// Thin wrapper around setup/bots-store.writeBotsJsonAtomic so call-sites keep
+// the same name without passing BOTS_JSON_FILE explicitly each time.
+function writeBotsJsonAtomic(bots) {
+    writeBotsAtomic(BOTS_JSON_FILE, bots);
 }
+/**
+ * 从 bot 配置里取 brand. 旧的 bots.json (1.0 之前) 没这个字段, default 到 feishu
+ * 保留向后兼容. cmdStart 凭证校验 + printRemainingSteps 深链都靠它选 host.
+ */
+function botBrand(b) {
+    return b?.brand === 'lark' ? 'lark' : 'feishu';
+}
+/**
+ * 把 botmux 推荐的完整 scope JSON (从 src/setup/lark-scopes.json) 写到
+ * 用户配置目录, 同时给出跨平台一键复制命令. JSON 长 (293 项, 297 行),
+ * terminal 直接打印用户也复制不了, 写文件 + pbcopy/xclip 才是顺手的姿势.
+ *
+ * Returns: 写出的 JSON 文件绝对路径.
+ */
+function writeScopesJsonToConfigDir() {
+    // build script 会把 src/setup/lark-scopes.json copy 到 dist/setup/.
+    // dist 模式下 __dirname 是 dist/, 找 ./setup/lark-scopes.json; dev (tsx)
+    // 模式找 src/setup/lark-scopes.json 在源码同目录也成立.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const srcCandidates = [
+        join(here, 'setup', 'lark-scopes.json'),
+        join(here, '..', 'src', 'setup', 'lark-scopes.json'),
+    ];
+    let scopesPath = srcCandidates[0];
+    for (const p of srcCandidates) {
+        if (existsSync(p)) {
+            scopesPath = p;
+            break;
+        }
+    }
+    const destPath = join(CONFIG_DIR, 'lark-scopes.json');
+    copyFileSync(scopesPath, destPath);
+    return destPath;
+}
+function printCopyHint(filePath) {
+    // 环境感知: SSH/headless 没有 X server, xclip 一定报 "Can't open display".
+    // 这种场景下"剪贴板"在用户本地 (运行 SSH 客户端的那台机器), 远程机上能做的:
+    //   - 直接 cat, 让用户在本地 terminal 鼠标选中 (SSH 选中即写本地剪贴板)
+    //   - OSC 52: terminal app 代写本地剪贴板, iTerm2 / kitty / WezTerm /
+    //     Alacritty / tmux 1.5+ 都支持, gnome-terminal / Terminal.app 不支持
+    // 检测 DISPLAY (X11) 或 WAYLAND_DISPLAY 都没有, 或 SSH_* 环境变量存在
+    // → 当作 SSH 场景, 不推荐 xclip / pbcopy.
+    const isSsh = !!(process.env.SSH_CONNECTION || process.env.SSH_CLIENT || process.env.SSH_TTY);
+    const hasLocalGui = !!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY) && !isSsh;
+    const isMacLocal = process.platform === 'darwin' && !isSsh;
+    console.log('  把 JSON 内容拷到本地剪贴板, 然后到飞书"批量导入/导出权限"页粘贴:');
+    if (isMacLocal) {
+        console.log(`    macOS 本地:  cat ${filePath} | pbcopy`);
+    }
+    else if (hasLocalGui) {
+        console.log(`    Linux 本地 (X 服务器):  cat ${filePath} | xclip -selection clipboard`);
+    }
+    else {
+        // SSH / headless: 鼠标选中是最稳的, OSC 52 作为高级选项
+        console.log(`    SSH 终端鼠标选中复制:  cat ${filePath}`);
+        console.log('       (终端把选中的字符直接写到你本地剪贴板, 不依赖远端剪贴板工具)');
+        console.log(`    或 OSC 52 (兼容 iTerm2 / kitty / WezTerm / Alacritty / tmux 1.5+):`);
+        console.log(`       base64 -w0 < ${filePath} | awk 'BEGIN{printf "\\033]52;c;"}{printf "%s",$0}END{printf "\\a"}'`);
+    }
+    console.log('');
+}
+function printRemainingSteps(appId, brand) {
+    // 数据源: 飞书内部 wiki UBOXwH01CixfxfkqxUpcKgvQnsg "[Botmux] 5分钟创建一个
+    // 真正好用的飞书助理" 的"权限申请"段, 加 botmux 维护者实测确认 PersonalAgent
+    // 应用扫码建出来时已经默认订阅 im.message.receive_v1 / card.action.trigger
+    // 事件并开通 bot 能力. 但 lark-channel-bridge README 当前仍要求用户手动补
+    // 事件订阅, 跟我们结论不一致 — 不排除飞书最近升级了 PersonalAgent 预配 (那个
+    // README 是旧版), 也不排除存在租户/版本差异让某些用户的 PersonalAgent 没预配.
+    //
+    // 折中: 主线流程只列"必须手动"的两步 (权限 + 重定向 URL), 末尾再给"如果
+    // bot 收不到消息" 的兜底 fallback 链接, 让用户能自查事件订阅 / bot 能力.
+    const host = brand === 'lark' ? 'open.larksuite.com' : 'open.feishu.cn';
+    const home = `https://${host}/app/${appId}`;
+    let scopesJsonPath = '';
+    try {
+        scopesJsonPath = writeScopesJsonToConfigDir();
+    }
+    catch (err) {
+        // 不应阻止 setup 完成, 只 WARN
+        console.log(`\n⚠️  写权限 JSON 失败 (${err.message}), 请手动从仓库源码 src/setup/lark-scopes.json 拷.`);
+    }
+    console.log('\n⚠️  扫码 / 粘贴只完成了"建应用 + 拿凭证". 还有这些步骤要在开放平台浏览器里点:\n');
+    console.log('  1. 申请权限 (一次性导入完整 JSON 提交审批)');
+    console.log(`     深链: ${home}/auth → 进入「权限管理」→「批量导入/导出权限」→ 粘贴 → 提交`);
+    if (scopesJsonPath) {
+        console.log(`     权限 JSON: ${scopesJsonPath}`);
+        printCopyHint(scopesJsonPath);
+    }
+    console.log('');
+    console.log('  2. 添加重定向 URL (用于 botmux 内 `/login` 拿用户 UAT 调云文档/日历等)');
+    console.log(`     深链: ${home}/safe → 进入「安全设置」→「重定向 URL」`);
+    console.log('     填入: http://127.0.0.1:9768/callback');
+    console.log('     不打算用 `/login` 跨用户调 API 的话, 这一步可以跳过.\n');
+    console.log('  完成后 `botmux start` (或 `botmux restart`)，启动检查不会卡住，');
+    console.log('  缺权限只 WARN，去开放平台补齐后 daemon 自动恢复。\n');
+    // Fallback 自查清单 — 维护者实测 PersonalAgent 默认配好下面两项, 但飞书
+    // 没承诺过这是稳定行为. 收不到消息时让用户能自查.
+    console.log('  ─── 如果机器人配置好后收不到消息, 自查下面两点 ───');
+    console.log('  a. 事件订阅: PersonalAgent 默认订阅 im.message.receive_v1 + card.action.trigger,');
+    console.log(`     如缺失, 请到 ${home}/dev-config/event-sub 手动添加`);
+    console.log('  b. 机器人能力: PersonalAgent 默认已开通,');
+    console.log(`     如缺失, 请到 ${home}/feature/bot 启用 (应用功能 → 机器人)`);
+    console.log('');
+}
+/**
+ * 让用户选"扫码建应用"还是"手动粘 AppID/Secret".
+ *
+ * 默认走扫码: 调 SDK `registerApp` → 拿 client_id/client_secret. 失败 (用户拒绝/
+ * 超时/网络/取消) 一律降级到手动, 不阻塞流程.
+ *
+ * Codex review 边界:
+ * - secret 不进 argv / 日志 / 错误链 (registerApp 内部 safeMsg 已做; 手动模式下
+ *   AppSecret 通过 rl.question 异步读取, 不会出现在 process.argv)
+ * - 任何失败都返回结构化对象, 不抛 (调用方根据 ok=false 回退)
+ */
+async function obtainCredentials(rl) {
+    console.log('── 飞书应用建立 ──\n');
+    console.log('1) 扫码建应用（推荐，一步拿到 AppID/Secret，需要飞书 App 扫码）');
+    console.log('2) 手动粘 AppID/Secret（已经在开放平台创建好应用了）\n');
+    const choice = (await ask(rl, '选择 [1]: ')).trim();
+    if (choice !== '2') {
+        // 动态导入避免冷启动加载 SDK
+        const { tryRegisterApp } = await import('./setup/register-app.js');
+        const result = await tryRegisterApp();
+        if (result.ok) {
+            // Lark 国际版需要 daemon 链路全程走 larksuite.com 域 (Client domain /
+            // WSClient / event-dispatcher 的 fetch URL / scope 深链 host). 当前
+            // botmux runtime 这几处都硬编码 feishu.cn, 所以即使扫码成功了也无法
+            // 真正跑起来. 干净做法是 setup 阶段就拒绝, 让用户用 feishu 租户. 单
+            // 独 PR 完整接入 lark 后再去掉这个分支.
+            if (result.brand === 'lark') {
+                console.log(`\n❌ 检测到 Lark 国际版 (larksuite.com) 租户。`);
+                console.log(`   botmux 当前 daemon 运行链路仅支持飞书 (feishu.cn) 租户,`);
+                console.log(`   Lark 国际版完整接入会在单独 PR 跟进 (BotConfig / Client domain /`);
+                console.log(`   WSClient / event-dispatcher 等需要一并支持).`);
+                console.log(`   请用飞书 (feishu.cn) 租户重试 setup。\n`);
+                return { ok: false, reason: 'lark_unsupported' };
+            }
+            console.log(`\n✅ 应用创建成功`);
+            console.log(`   App ID: ${result.appId}`);
+            console.log(`   租户类型: ${result.brand}`);
+            return { ok: true, appId: result.appId, appSecret: result.appSecret, brand: result.brand };
+        }
+        console.log(`\n⚠️  扫码失败 (${result.error}): ${result.message}`);
+        if (result.error === 'aborted') {
+            // 用户主动取消整个 setup, 不再问手动 fallback
+            return { ok: false, reason: 'cancelled' };
+        }
+        console.log('   降级到手动输入 AppID/Secret。\n');
+    }
+    else {
+        console.log('\n请在浏览器打开 https://open.feishu.cn/app 创建应用，然后回来粘 ID/Secret。\n');
+    }
+    // 手动 fallback. 不再提问租户类型 — 当前 daemon runtime 只支持 feishu,
+    // 让用户选 lark 是误导. 等 lark 完整接入再加回来.
+    const appId = (await ask(rl, 'AppID (cli_xxx): ')).trim();
+    const appSecret = (await ask(rl, 'AppSecret: ')).trim();
+    if (!appId || !appSecret) {
+        console.log('\n❌ AppID/AppSecret 不能为空，setup 中止。');
+        return { ok: false, reason: 'cancelled' };
+    }
+    return { ok: true, appId, appSecret, brand: 'feishu' };
+}
+/**
+ * 收集一个机器人完整配置 (凭证 + CLI/工作目录/allowedUsers).
+ *
+ * 顺序: 拿凭证 → tenant_access_token 验证 → 通过才返回 bot 对象. 验证失败
+ * 直接返回 null, 调用方负责"不写 bots.json". Codex review 边界 #2.
+ */
 async function promptBotConfig(rl) {
-    const appId = await ask(rl, 'LARK_APP_ID: ');
-    const appSecret = await ask(rl, 'LARK_APP_SECRET: ');
-    console.log('\n支持的 CLI: 1) claude-code  2) aiden  3) coco  4) codex  5) gemini  6) opencode');
+    const creds = await obtainCredentials(rl);
+    if (!creds.ok)
+        return null;
+    // 凭证立刻验证. 通不过不写 bots.json.
+    console.log('\n校验凭证（取 tenant_access_token）…');
+    const { validateCredentials } = await import('./setup/verify-permissions.js');
+    const v = await validateCredentials(creds.appId, creds.appSecret, creds.brand);
+    if (!v.ok) {
+        console.log(`\n❌ 凭证校验失败 (${v.error}): ${v.message}`);
+        console.log('   不写 bots.json。请重新运行 botmux setup。');
+        return null;
+    }
+    console.log('✅ 凭证有效（tenant_access_token 已成功获取）\n');
+    console.log('支持的 CLI: 1) claude-code  2) aiden  3) coco  4) codex  5) gemini  6) opencode');
     const cliChoice = await ask(rl, 'CLI 适配器 [1]: ');
     const cliIdMap = { '1': 'claude-code', '2': 'aiden', '3': 'coco', '4': 'codex', '5': 'gemini', '6': 'opencode' };
     const cliId = cliIdMap[cliChoice] ?? (cliChoice || 'claude-code');
     const workingDir = await ask(rl, '默认工作目录 [~]: ');
     const allowedUsers = await ask(rl, '允许的用户 (邮箱或 open_id，逗号分隔，留空=不限制): ');
-    const bot = { larkAppId: appId, larkAppSecret: appSecret, cliId };
+    // brand 必须持久化: cmdStart 的 validate / event-dispatcher 走的 deep link
+    // 都看这个字段; 不写就只能硬编码 feishu, lark 租户用户会被打成凭证无效.
+    // 为了向后兼容 (旧 bots.json 没 brand 字段), reader 应当 default 到 'feishu'.
+    const bot = {
+        larkAppId: creds.appId,
+        larkAppSecret: creds.appSecret,
+        brand: creds.brand,
+        cliId,
+    };
     if (workingDir)
         bot.workingDir = workingDir;
     if (allowedUsers)
@@ -203,18 +385,25 @@ function parseDotEnvToBotConfig() {
         bot.projectScanDir = vars.PROJECT_SCAN_DIR;
     return bot;
 }
-/** Write single-bot config to bots.json (fresh install or reconfigure) */
+/**
+ * 收集一个机器人配置并写盘 (单机器人 fresh install / 重新配置).
+ *
+ * 失败路径 (扫码取消 / 凭证校验不通过): 不创建任何配置文件, 不动旧 .env.
+ * Codex review 边界 #2: 中途失败一律不留半截 JSON.
+ */
 async function writeSingleBotConfig() {
-    console.log('── 飞书应用配置 ──\n');
-    printLarkPermissions();
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     const bot = await promptBotConfig(rl);
     rl.close();
-    writeFileSync(BOTS_JSON_FILE, JSON.stringify([bot], null, 2) + '\n');
+    if (!bot)
+        return false;
+    writeBotsJsonAtomic([bot]);
     console.log(`\n✅ 配置已写入: ${BOTS_JSON_FILE}`);
-    console.log(`\n下一步:`);
-    console.log(`  1. botmux start              启动 daemon（飞书后台配长连接前必须先启动）`);
+    printRemainingSteps(bot.larkAppId, botBrand(bot));
+    console.log(`下一步:`);
+    console.log(`  1. botmux start              启动 daemon`);
     console.log(`  2. botmux autostart enable   注册开机自启（推荐：${process.platform === 'darwin' ? 'mac launchd' : process.platform === 'linux' ? 'linux user systemd' : '当前平台暂不支持'}，无需 sudo）`);
+    return true;
 }
 // ─── Commands ────────────────────────────────────────────────────────────────
 async function cmdSetup() {
@@ -235,26 +424,36 @@ async function cmdSetup() {
         const rl = createInterface({ input: process.stdin, output: process.stdout });
         const action = await ask(rl, '操作: 1) 添加新机器人  2) 重新配置  (1/2) [1]: ');
         if (action === '2') {
-            renameSync(BOTS_JSON_FILE, BOTS_JSON_FILE + '.bak');
-            console.log(`旧配置已备份: ${BOTS_JSON_FILE}.bak\n`);
             console.log('\n── 重新配置 ──\n');
-            printLarkPermissions();
             const newBot = await promptBotConfig(rl);
             rl.close();
-            writeFileSync(BOTS_JSON_FILE, JSON.stringify([newBot], null, 2) + '\n');
-            console.log(`\n✅ 配置已写入: ${BOTS_JSON_FILE}`);
-            console.log(`\n下一步: botmux restart`);
+            if (!newBot) {
+                console.log('\n⚠️  setup 中止，旧配置保留不动。');
+                return;
+            }
+            // Codex review #1: 先 copyFileSync 备份, 再原子写新文件. 之前先 rename
+            // 旧文件再 write, 一旦 write 失败 (磁盘/权限/进程被 kill) 用户就丢了
+            // bots.json. copy 之后写失败旧文件原地不动, .bak 是无害的同名副本.
+            copyFileSync(BOTS_JSON_FILE, BOTS_JSON_FILE + '.bak');
+            console.log(`旧配置已备份: ${BOTS_JSON_FILE}.bak`);
+            writeBotsJsonAtomic([newBot]);
+            console.log(`✅ 配置已写入: ${BOTS_JSON_FILE}`);
+            printRemainingSteps(newBot.larkAppId, botBrand(newBot));
+            console.log(`下一步: botmux restart\n`);
             return;
         }
         console.log('\n── 添加新机器人 ──\n');
-        printLarkPermissions();
         const newBot = await promptBotConfig(rl);
         rl.close();
-        bots.push(newBot);
-        writeFileSync(BOTS_JSON_FILE, JSON.stringify(bots, null, 2) + '\n');
-        console.log(`\n✅ 已添加机器人 ${newBot.larkAppId}，共 ${bots.length} 个`);
+        if (!newBot) {
+            console.log('\n⚠️  setup 中止，bots.json 不动。');
+            return;
+        }
+        writeBotsJsonAtomic([...bots, newBot]);
+        console.log(`\n✅ 已添加机器人 ${newBot.larkAppId}，共 ${bots.length + 1} 个`);
         console.log(`   配置文件: ${BOTS_JSON_FILE}`);
-        console.log(`\n下一步: botmux restart`);
+        printRemainingSteps(newBot.larkAppId, botBrand(newBot));
+        console.log(`下一步: botmux restart\n`);
     }
     else if (hasEnv) {
         // --- Single-bot mode (.env exists) ---
@@ -263,9 +462,11 @@ async function cmdSetup() {
         const action = await ask(rl, '操作: 1) 添加新机器人  2) 覆盖当前配置  (1/2): ');
         if (action === '2') {
             rl.close();
-            await writeSingleBotConfig();
-            renameSync(ENV_FILE, ENV_FILE + '.bak');
-            console.log(`   旧 .env 已备份: ${ENV_FILE}.bak`);
+            const ok = await writeSingleBotConfig();
+            if (ok) {
+                renameSync(ENV_FILE, ENV_FILE + '.bak');
+                console.log(`   旧 .env 已备份: ${ENV_FILE}.bak`);
+            }
             return;
         }
         // Migrate .env → bots.json
@@ -278,16 +479,20 @@ async function cmdSetup() {
         }
         console.log(`\n当前机器人: ${existingBot.larkAppId} (${existingBot.cliId ?? 'claude-code'})`);
         console.log('\n── 添加新机器人 ──\n');
-        printLarkPermissions();
         const newBot = await promptBotConfig(rl);
         rl.close();
-        const bots = [existingBot, newBot];
-        writeFileSync(BOTS_JSON_FILE, JSON.stringify(bots, null, 2) + '\n');
+        if (!newBot) {
+            console.log('\n⚠️  setup 中止，.env 和 bots.json 都不动。');
+            return;
+        }
+        // 写新文件成功后才备份 .env. 失败不动两边.
+        writeBotsJsonAtomic([existingBot, newBot]);
         renameSync(ENV_FILE, ENV_FILE + '.bak');
         console.log(`\n✅ 已迁移到多机器人配置`);
         console.log(`   配置文件: ${BOTS_JSON_FILE}`);
         console.log(`   旧配置已备份: ${ENV_FILE}.bak`);
-        console.log(`\n下一步: botmux restart`);
+        printRemainingSteps(newBot.larkAppId, botBrand(newBot));
+        console.log(`下一步: botmux restart\n`);
     }
     else {
         // --- Fresh install ---
@@ -379,6 +584,40 @@ async function cmdStart() {
     ensureConfigDir();
     preflightNodeSanity();
     await ensureSystemDependencies();
+    // 启动前快速校验每个 bot 的凭证. Codex review 边界 #5: 凭证无效是
+    // 唯一应该阻塞 start 的情况; scope/event 缺失在 daemon 起来后用 WARN
+    // + 私信处理 (event-dispatcher.checkRequiredScopes).
+    //
+    // 失败时打印明确的 appId 前缀和错误码, 不打印 secret, 不 spawn pm2 进程.
+    const botsForCheck = loadBotsJson();
+    if (botsForCheck.length > 0) {
+        const { validateCredentials } = await import('./setup/verify-permissions.js');
+        const invalid = [];
+        for (const b of botsForCheck) {
+            if (!b.larkAppId || !b.larkAppSecret) {
+                invalid.push({ appId: b.larkAppId || '(空 appId)', reason: 'larkAppId/larkAppSecret 缺失' });
+                continue;
+            }
+            const v = await validateCredentials(b.larkAppId, b.larkAppSecret, botBrand(b));
+            if (!v.ok) {
+                if (v.error === 'invalid_credentials') {
+                    invalid.push({ appId: b.larkAppId, reason: v.message });
+                }
+                else {
+                    // network / unknown — 不应该拦下启动, 走 WARN
+                    console.warn(`⚠️  [${b.larkAppId}] 启动前凭证验证未成功（${v.error}）: ${v.message}`);
+                    console.warn(`   daemon 仍会启动；启动后 dispatcher 会自行重试。`);
+                }
+            }
+        }
+        if (invalid.length > 0) {
+            console.error('\n❌ 以下机器人凭证无效，botmux start 中止：\n');
+            for (const e of invalid)
+                console.error(`   - ${e.appId}: ${e.reason}`);
+            console.error('\n   修复方式: 运行 `botmux setup` 选 "重新配置" 重新走扫码/手动流程。');
+            process.exit(1);
+        }
+    }
     cleanupLegacyPm2();
     const cfg = ecosystemConfig();
     runPm2(['start', cfg]);