botmux 2.26.0 → 2.27.0

package/README.en.md

@@ -71,78 +71,71 @@ Compared to OpenClaw-style approaches built on Agent SDKs:
 
 ## 5-Minute Setup
 
+> 💡 **TL;DR**: run `botmux setup` and pick "scan-to-create" to finish Steps 1+2 in one shot (the official `@larksuiteoapi/node-sdk` device flow gives you the AppID/AppSecret). PersonalAgent apps come with event subscriptions and bot capability pre-configured, so only Step 4 (permissions) + Step 5 (optional redirect URL) + Step 6 (publish) require browser clicks; the setup wizard writes a JSON file with a one-line clipboard copy command and prints deep-links to each remaining step.
+
 ### Step 1: Create a Lark App
 
-Go to the [Lark Open Platform](https://open.larkoffice.com/app) and click "Create Custom App".
+**Recommended**: `botmux setup` → pick "1) Scan-to-create app". Scan with the Lark mobile app and the AppID/AppSecret are persisted automatically; no manual browser navigation. Falls back to manual paste on cancel/timeout/network error.
+
+> ⚠️ **Currently only Feishu (feishu.cn) tenants are supported.** If scan detects a Lark international (larksuite.com) tenant, setup aborts — the daemon runtime (Lark Client/WSClient/event-dispatcher) hasn't been wired up for the `larksuite.com` domain yet, so accepting Lark credentials would land users in a half-working state. A follow-up PR will add full Lark support.
+
+**Manual**: go to the [Lark Open Platform](https://open.larkoffice.com/app) and click "Create Custom App".
 
 ![Create App](docs/setup/create-app.png)
 
 ### Step 2: Get Credentials
 
+> The scan-to-create path completes this step automatically; skip to Step 3.
+
 Open the app details page → "Credentials & Basic Info", and copy the **App ID** and **App Secret**.
 
 ![Get Credentials](docs/setup/credentials.png)
 
-### Step 3: Add Permissions
-
-Go to "Permissions & Scopes" → "Batch Import/Export", and paste the following JSON to import all permissions at once:
-
-![Permissions](docs/setup/permissions.png)
-
-<details>
-<summary>Click to expand batch import JSON</summary>
-
-```json
-{
-  "scopes": {
-    "tenant": [
-      "contact:user.base:readonly",
-      "contact:user.id:readonly",
-      "im:chat:read",
-      "im:chat.members:bot_access",
-      "im:chat.members:read",
-      "im:message",
-      "im:message:readonly",
-      "im:message:send_as_bot",
-      "im:message:update",
-      "im:message.group_at_msg",
-      "im:message.group_at_msg:readonly",
-      "im:message.group_msg",
-      "im:message.p2p_msg:readonly",
-      "im:message.reactions:write_only",
-      "im:resource"
-    ]
-  }
-}
-```
-</details>
-
-### Step 4: Install & Start botmux
+### Step 3: Install & Start botmux
 
 ```bash
 # Install
 npm install -g botmux
 
-# Interactive setup — enter the App ID and App Secret from Step 2
+# Interactive setup — pick "1) Scan-to-create app" or "2) Paste AppID/Secret manually".
+# Credentials are validated with a tenant_access_token call before bots.json is written.
+# At the end of setup the wizard writes the full scope JSON to ~/.botmux/lark-scopes.json
+# and prints a one-line clipboard copy command for your platform.
 botmux setup
 
-# Start (must be running before configuring WebSocket subscription — Lark checks for an active connection)
+# Start (if you ever need to verify the event subscription, Lark requires the daemon to be running so it can detect the WebSocket connection)
+# Re-validates credentials before forking workers; missing scopes only WARN, do not block the daemon.
 botmux start
 ```
 
-### Step 5: Configure Event Subscription
+### Step 4: Add Permissions
 
-Back in the Lark Open Platform, go to "Events & Callbacks":
+Run the copy-to-clipboard command setup printed, then go to "Permissions & Scopes" → "Batch Import/Export" and paste. Submit for review — visibility "only me" auto-approves.
 
-1. **Subscription mode**: Click the edit icon, select "Receive events via persistent connection" (WebSocket) — requires botmux to be running so Lark can detect the connection
+![Permissions](docs/setup/permissions.png)
 
-![WebSocket subscription](docs/setup/event-websocket.png)
+The full JSON lives at `~/.botmux/lark-scopes.json` (also tracked in-repo at [src/setup/lark-scopes.json](src/setup/lark-scopes.json), kept in sync with the internal wiki, covers ~290 tenant + user scopes).
 
-2. **Add event**: Click "Add Event", search and add `im.message.receive_v1` (Receive messages v2.0)
+```bash
+# macOS
+cat ~/.botmux/lark-scopes.json | pbcopy
+# Linux X
+cat ~/.botmux/lark-scopes.json | xclip -selection clipboard
+# Wayland
+cat ~/.botmux/lark-scopes.json | wl-copy
+```
 
-![Add event](docs/setup/event-receive-msg.png)
+> Scan-created PersonalAgent apps have `im.message.receive_v1` + `card.action.trigger` subscribed and the bot capability enabled out of the box, per botmux maintainer testing. Lark hasn't documented this as stable behavior, so **if the bot receives no messages at all after setup**, see "Step 8: Troubleshoot — bot not receiving messages" below for a manual fallback.
 
-3. **Enable callback**: Switch to the "Callback Configuration" tab, turn on "Card action callback" (`card.action.trigger`)
+### Step 5: Add Redirect URL (optional)
+
+If you plan to use `/login` inside Lark to let botmux act on your behalf for docs / calendar / wiki / sheets, add a redirect URL under "Security Settings" → "Redirect URL":
+
+```
+http://127.0.0.1:9768/callback
+```
+
+Skip this step if you only need bot messaging.
 
 ### Step 6: Publish the App
 
@@ -158,7 +151,16 @@ Go to "Version Management & Release", click "Create Version" and publish. Set av
 
 ![Add bot to group](docs/setup/add-bot-to-group.png)
 
-### Step 8: Enable Boot-time Autostart (recommended)
+### Step 8: Troubleshoot — bot not receiving messages (fallback)
+
+PersonalAgent apps come with event subscriptions and bot capability pre-configured; in normal cases you don't touch this. If the bot **receives no messages at all** after setup (not even DMs), verify these two settings:
+
+- **Event subscription**: Open Platform → your app → Events & Callbacks → should be subscribed to `im.message.receive_v1` + `card.action.trigger`. If missing, add them manually. Subscription mode must be "Receive via persistent connection" (WebSocket), and the botmux daemon must be running.
+- **Bot capability**: Open Platform → your app → Features → Bot should be enabled (it is by default). Adjust name/avatar if needed.
+
+After verifying, restart: `botmux restart`.
+
+### Step 9: Enable Boot-time Autostart (recommended)
 
 Once the bot is sending and receiving messages cleanly, run:
 

package/README.md

@@ -173,78 +173,70 @@ CLI 进入 botmux 会话时自动获得 `~/.botmux/bin` 在 PATH 中，以及一
 
 ## 5 分钟快速接入
 
+> 💡 **TL;DR**：跑 `botmux setup` 选「扫码建应用」一步完成 Step 1+2（拿 AppID/AppSecret）。PersonalAgent 应用建出来时事件订阅和 bot 能力都已默认配好，只剩 Step 4 权限申请 + Step 5（按需）重定向 URL + Step 6 发版三步要在浏览器手动点；setup 完成后会自动写 JSON 文件 + 打印一键复制命令 + 各步骤的深链。
+
 ### Step 1: 创建飞书应用
 
-打开 [飞书开放平台](https://open.larkoffice.com/app)，点击「创建企业自建应用」。
+**推荐路径**：`botmux setup` 选「1) 扫码建应用」，飞书扫码完成后自动落盘 AppID/AppSecret，无需手动浏览器创建。底层走 `@larksuiteoapi/node-sdk` 的官方 device flow。
+
+> ⚠️ **目前仅支持飞书 (feishu.cn) 租户**。扫码检测到 Lark 国际版 (larksuite.com) 会中止 setup —— daemon runtime (Lark Client/WSClient/event-dispatcher 等) 需要一并接入 lark 域，会在单独 PR 跟进。
+
+**手动路径**：打开 [飞书开放平台](https://open.larkoffice.com/app)，点击「创建企业自建应用」。
 
 ![创建应用](docs/setup/create-app.png)
 
 ### Step 2: 获取凭证
 
+> 扫码路径自动完成此步，可直接跳到 Step 3。
+
 进入应用详情 →「凭证与基础信息」，复制 **App ID** 和 **App Secret**。
 
 ![获取凭证](docs/setup/credentials.png)
 
-### Step 3: 添加权限
-
-进入「权限管理」→「批量导入/导出权限」，粘贴以下 JSON 一次性导入所有权限：
-
-![权限管理](docs/setup/permissions.png)
-
-<details>
-<summary>点击展开批量导入 JSON</summary>
-
-```json
-{
-  "scopes": {
-    "tenant": [
-      "contact:user.base:readonly",
-      "contact:user.id:readonly",
-      "im:chat:read",
-      "im:chat.members:bot_access",
-      "im:chat.members:read",
-      "im:message",
-      "im:message:readonly",
-      "im:message:send_as_bot",
-      "im:message:update",
-      "im:message.group_at_msg",
-      "im:message.group_at_msg:readonly",
-      "im:message.group_msg",
-      "im:message.p2p_msg:readonly",
-      "im:message.reactions:write_only",
-      "im:resource"
-    ]
-  }
-}
-```
-</details>
-
-### Step 4: 安装 & 启动 botmux
+### Step 3: 安装 & 启动 botmux
 
 ```bash
 # 安装
 npm install -g botmux
 
-# 交互式配置 — 输入 Step 2 的 App ID 和 App Secret
+# 交互式配置 — 选「1) 扫码建应用」或「2) 手动粘 AppID/Secret」
+# 凭证拿到后自动取一次 tenant_access_token 校验，通过才落盘 bots.json
+# setup 末尾会把完整权限 JSON 写到 ~/.botmux/lark-scopes.json 并打印一键复制命令
 botmux setup
 
-# 启动（飞书后台配置长连接订阅前需要先启动，否则无法检测到连接）
+# 启动（如果之后需要确认事件订阅，飞书后台会要求 daemon 已在跑才能识别长连接）
+# start 前再校验一次凭证；权限未配齐不会阻塞 daemon，只 WARN
 botmux start
 ```
 
-### Step 5: 配置事件订阅
+### Step 4: 添加权限
 
-回到飞书开放平台，进入「事件与回调」：
+setup 完成后，按 terminal 提示的一键复制命令把权限 JSON 复制到剪贴板，进入「权限管理」→「批量导入/导出权限」粘贴 → 提交审批。可用性范围选「仅自己可见」会自动通过：
 
-1. **订阅方式**：点击编辑图标，选择「使用长连接接收事件」（需要 botmux 已启动，飞书会检测长连接是否建立）
+![权限管理](docs/setup/permissions.png)
 
-![配置长连接](docs/setup/event-websocket.png)
+完整 JSON 已经写到 `~/.botmux/lark-scopes.json`，源仓库版本在 [src/setup/lark-scopes.json](src/setup/lark-scopes.json)（与本仓库内部 wiki 文档同步，覆盖 tenant + user 双套域 ≈ 290 项）。
 
-2. **添加事件**：点击「添加事件」，搜索添加 `im.message.receive_v1`（接收消息 v2.0）
+```bash
+# macOS
+cat ~/.botmux/lark-scopes.json | pbcopy
+# Linux X
+cat ~/.botmux/lark-scopes.json | xclip -selection clipboard
+# Wayland
+cat ~/.botmux/lark-scopes.json | wl-copy
+```
 
-![添加事件](docs/setup/event-receive-msg.png)
+> 扫码建出来的 PersonalAgent 应用，botmux 维护者实测默认已订阅 `im.message.receive_v1` + `card.action.trigger` 并开通 bot 能力，所以主线流程不再要求手动配。但飞书没在公开文档里承诺这是稳定行为，**如果配好后机器人完全收不到消息**，参见下方「Step 8: 机器人收不到消息时的自查」。
 
-3. **启用回调**：切换到「回调配置」tab，开启「卡片回传交互」（`card.action.trigger`）
+### Step 5: 添加重定向 URL（按需）
+
+如果之后要在飞书里 `/login` 让 botmux 以你的身份调云文档/日历/Wiki 等 API，进入「安全设置」→「重定向 URL」填入：
+
+```
+http://127.0.0.1:9768/callback
+```
+
+只用 bot 收发消息的话这一步可以跳过。
 
 ### Step 6: 发版
 
@@ -260,7 +252,16 @@ botmux start
 
 ![添加机器人到群](docs/setup/add-bot-to-group.png)
 
-### Step 8: 开机自启（推荐）
+### Step 8: 机器人收不到消息时的自查（fallback）
+
+PersonalAgent 默认配好事件订阅 + bot 能力，正常情况下不用动。如果按上面步骤走完 bot **完全收不到任何消息**（连私聊都不回），分别确认这两项：
+
+- **事件订阅**：开放平台 → 你的应用 → 事件与回调 → 应当订阅 `im.message.receive_v1` + `card.action.trigger`（默认已订阅，如缺失就手动添加）。订阅方式必须是「使用长连接接收事件」(WebSocket)，且 botmux daemon 已经在跑。
+- **机器人能力**：开放平台 → 你的应用 → 应用功能 → 机器人 应当已开通（默认开通），名字/头像可以改。
+
+确认后重启 daemon：`botmux restart`。
+
+### Step 9: 开机自启（推荐）
 
 确认机器人能正常收发消息之后，跑一次：
 

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,189 @@ 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) {
+    console.log('  一键复制 JSON 到剪贴板:');
+    console.log(`    macOS:   cat ${filePath} | pbcopy`);
+    console.log(`    Linux:   cat ${filePath} | xclip -selection clipboard`);
+    console.log(`    Wayland: cat ${filePath} | wl-copy`);
+    console.log(`    远程 SSH: scp 拉到本地, 或 less ${filePath} 终端选中复制`);
+}
+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 +365,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 +404,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 +442,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 +459,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 +564,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]);