botmux 2.48.1 → 2.48.3

package/README.en.md

@@ -72,43 +72,41 @@ 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.
+> 💡 **TL;DR**: `npm i -g botmux` → `botmux setup` and pick "scan-to-create" to get the AppID/AppSecret in one shot (Step 2) → `botmux start`. 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
+### Step 1: Install botmux
 
-**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.
+```bash
+npm install -g botmux
+```
 
-> ⚠️ **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.
+> Requires **Node.js ≥ 20**, with at least one AI coding CLI installed and authenticated (`claude` / `codex` / `cursor-agent` / `gemini` / `opencode` / `coco` / `agy` on your PATH). Installing **tmux** too is recommended (enables session persistence automatically).
 
-**Manual**: go to the [Lark Open Platform](https://open.larkoffice.com/app) and click "Create Custom App".
+### Step 2: Create the App & Configure (`botmux setup`)
 
-![Create App](docs/setup/create-app.png)
+Run `botmux setup` and follow the interactive menu:
 
-### Step 2: Get Credentials
+1. **New config**: type `1` and press Enter (with an existing config, type `2` to add a bot).
+2. **Create the bot**:
+   - Type `1` → **Scan-to-create (recommended)**: scan with the Lark mobile app and a PersonalAgent app is created with AppID/AppSecret persisted automatically, **with event subscriptions + bot capability pre-configured** — no manual browser navigation. Uses the official `@larksuiteoapi/node-sdk` device flow.
+   - Type `2` → **Manual**: go to the [Lark Open Platform](https://open.larkoffice.com/app), create a "Custom App", copy **App ID / App Secret** from "Credentials & Basic Info", and paste them back.
+3. **Pick the CLI**: choose the CLI to bridge (e.g. type `1` for Claude Code).
+4. **Default working dir**: usually the **parent directory** of your git projects (e.g. `~/projects`); new topics scan **downward** for git repos (up to 3 levels). Avoid `~` (too many folders to traverse).
 
-> The scan-to-create path completes this step automatically; skip to Step 3.
+> ⚠️ **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. A follow-up PR will add full Lark support.
 
-Open the app details page → "Credentials & Basic Info", and copy the **App ID** and **App Secret**.
+At the end, setup validates credentials with a `tenant_access_token` call (only writing `bots.json` on success), writes the full scope JSON to `~/.botmux/lark-scopes.json`, and prints a one-line clipboard copy command plus deep-links to each remaining step.
 
-![Get Credentials](docs/setup/credentials.png)
+![Create App](docs/setup/create-app.png)
 
-### Step 3: Install & Start botmux
+### Step 3: Start
 
 ```bash
-# Install
-npm install -g botmux
-
-# 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 (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
 ```
 
+> `start` re-validates credentials before forking workers; missing scopes only WARN, they don't block the daemon. If you later need to verify the event subscription, Lark requires the daemon to be running so it can detect the WebSocket connection.
+
 ### Step 4: Add Permissions
 
 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.

package/README.md

@@ -179,42 +179,41 @@ 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 文件 + 打印一键复制命令 + 各步骤的深链。
+> 💡 **TL;DR**：`npm i -g botmux` → `botmux setup` 选「扫码建应用」一步拿到 AppID/AppSecret（Step 2）→ `botmux start`。PersonalAgent 应用建出来时事件订阅和 bot 能力都已默认配好，只剩 Step 4 权限申请 + Step 5（按需）重定向 URL + Step 6 发版三步要在浏览器手动点；setup 完成后会自动写 JSON 文件 + 打印一键复制命令 + 各步骤的深链。
 
-### Step 1: 创建飞书应用
+### Step 1: 安装 botmux
 
-**推荐路径**：`botmux setup` 选「1) 扫码建应用」，飞书扫码完成后自动落盘 AppID/AppSecret，无需手动浏览器创建。底层走 `@larksuiteoapi/node-sdk` 的官方 device flow。
+```bash
+npm install -g botmux
+```
 
-> ⚠️ **目前仅支持飞书 (feishu.cn) 租户**。扫码检测到 Lark 国际版 (larksuite.com) 会中止 setup —— daemon runtime (Lark Client/WSClient/event-dispatcher 等) 需要一并接入 lark 域，会在单独 PR 跟进。
+> 要求 **Node.js ≥ 20**，且本地已装好并登录至少一种 AI 编程 CLI（`claude` / `codex` / `cursor-agent` / `gemini` / `opencode` / `coco` / `agy` 等在 PATH 中）。推荐顺手装 **tmux**（装了自动启用会话常驻）。
 
-**手动路径**：打开 [飞书开放平台](https://open.larkoffice.com/app)，点击「创建企业自建应用」。
+### Step 2: 创建应用并配置（`botmux setup`）
 
-![创建应用](docs/setup/create-app.png)
+跑 `botmux setup`，按交互菜单一步步选：
 
-### Step 2: 获取凭证
+1. **新建配置**：输入 `1` 回车（已有配置时输入 `2` 添加机器人）。
+2. **创建机器人**：
+   - 输入 `1` → **扫码创建（推荐）**：飞书扫码完成后自动建出 PersonalAgent 应用并落盘 AppID/AppSecret，**事件订阅 + bot 能力默认已配好**，无需手动浏览器创建。底层走 `@larksuiteoapi/node-sdk` 官方 device flow。
+   - 输入 `2` → **手动创建**：去 [飞书开放平台](https://open.larkoffice.com/app) 建「企业自建应用」，在「凭证与基础信息」复制 **App ID / App Secret** 回来粘贴。
+3. **选择 CLI**：选本次要接入的 CLI（如接 Claude Code 就选 `1`）。
+4. **默认工作目录**：通常填 git 项目的**父级目录**（如 `~/projects`），新话题会从该目录**向下**查找 git 仓库（最多 3 层）；尽量别填 `~`（要遍历太多文件夹）。
 
-> 扫码路径自动完成此步，可直接跳到 Step 3。
+> ⚠️ **目前仅支持飞书 (feishu.cn) 租户**。扫码检测到 Lark 国际版 (larksuite.com) 会中止 setup —— daemon runtime (Lark Client/WSClient/event-dispatcher 等) 需要一并接入 lark 域，会在单独 PR 跟进。
 
-进入应用详情 →「凭证与基础信息」，复制 **App ID** 和 **App Secret**。
+setup 末尾会用 `tenant_access_token` 校验凭证（通过才落盘 `bots.json`），并把完整权限 JSON 写到 `~/.botmux/lark-scopes.json` + 打印一键复制命令 + 各步骤深链。
 
-![获取凭证](docs/setup/credentials.png)
+![扫码建应用](docs/setup/create-app.png)
 
-### Step 3: 安装 & 启动 botmux
+### Step 3: 启动
 
 ```bash
-# 安装
-npm install -g botmux
-
-# 交互式配置 — 选「1) 扫码建应用」或「2) 手动粘 AppID/Secret」
-# 凭证拿到后自动取一次 tenant_access_token 校验，通过才落盘 bots.json
-# setup 末尾会把完整权限 JSON 写到 ~/.botmux/lark-scopes.json 并打印一键复制命令
-botmux setup
-
-# 启动（如果之后需要确认事件订阅，飞书后台会要求 daemon 已在跑才能识别长连接）
-# start 前再校验一次凭证；权限未配齐不会阻塞 daemon，只 WARN
 botmux start
 ```
 
+> start 前再校验一次凭证；权限未配齐不会阻塞 daemon，只 WARN。如果之后需要确认事件订阅，飞书后台会要求 daemon 已在跑才能识别长连接。
+
 ### Step 4: 添加权限
 
 setup 完成后，按 terminal 提示的一键复制命令把权限 JSON 复制到剪贴板，进入「权限管理」→「批量导入/导出权限」粘贴 → 提交审批。可用性范围选「仅自己可见」会自动通过：

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA46GA;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,qBAAqB,EAAE,SAAS,CAAC,EAC9F,KAAK,EAAE,MAAM,EACb,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,2BAA2B,EAAE,UAAU,GAAG,IAAI,CAAC,GACzF,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA+F7B"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA87GA;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,qBAAqB,EAAE,SAAS,CAAC,EAC9F,KAAK,EAAE,MAAM,EACb,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,2BAA2B,EAAE,UAAU,GAAG,IAAI,CAAC,GACzF,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA+F7B"}

package/dist/cli.js

@@ -493,15 +493,33 @@ async function obtainCredentials(rl) {
     }
     return { ok: true, appId, appSecret, brand: 'feishu' };
 }
+/**
+ * 用指定应用凭证把 open_id (ou_) 解析成 union_id (on_，跨应用稳定)。
+ * 查询失败（无 contact 权限 / API 错误）则 fallback 返回原 open_id。
+ */
+async function resolveOpenIdToUnionId(appId, appSecret, openId) {
+    try {
+        const { Client } = await import('@larksuiteoapi/node-sdk');
+        const client = new Client({ appId, appSecret });
+        const res = await client.contact.v3.user.get({
+            path: { user_id: openId },
+            params: { user_id_type: 'open_id' },
+        });
+        if (res.code === 0 && res.data?.user?.union_id)
+            return res.data.user.union_id;
+    }
+    catch { /* fallback */ }
+    return openId;
+}
 /**
  * 手动建 bot 时（没有扫码人 open_id）必须指定至少一个 owner.
- * 循环追问直到给出合法条目（完整邮箱或 ou_ open_id），拒绝裸邮箱前缀与空输入.
+ * 循环追问直到给出合法条目（邮箱、union_id on_xxx 或 open_id ou_xxx），拒绝裸邮箱前缀与空输入.
  * setup 不允许没有 owner —— 没 owner 的配置一旦叠加 allowedChatGroups 即成权限黑洞.
  */
 async function promptRequiredOwner(rl) {
     printInputHelp('管理员 (owner)', [
-        '必填。至少一个能操作机器人的管理员，支持完整邮箱（如 alice@example.com）或 open_id（ou_xxx），多个值用逗号分隔。',
-        '第一个 open_id（或可解析的邮箱）将作为 owner —— /restart、/close、/grant 等敏感操作只对 allowedUsers 开放。',
+        '必填。至少一个能操作机器人的管理员，多个值用逗号分隔。',
+        '推荐格式（优先级高到低）：完整邮箱（alice@example.com）> union_id（on_xxx，跨应用稳定）> open_id（ou_xxx，仅限同一应用）。',
         '注意：必须是完整邮箱，邮箱前缀（如 alice）无法解析、不接受。',
     ]);
     for (;;) {
@@ -573,11 +591,12 @@ async function promptBotConfig(rl) {
         bot.model = modelChoice;
     }
     // 扫码场景默认填扫码人自己 (registerApp 返回里有 open_id), 天然就是 owner.
+    // 优先解析成 union_id (on_，跨应用稳定)；失败则 fallback 到 open_id (ou_)。
     // 手动 fallback 场景没 open_id —— 必须显式指定 owner, 否则配置无 owner:
     // allowedUsers 为空时虽然"全开放", 但一旦后续加了 allowedChatGroups 就会变成
     // "群成员能对话却没人能做敏感操作 / 用 /grant". setup 阶段强制收口, 不允许没 owner.
     if (creds.userOpenId) {
-        bot.allowedUsers = [creds.userOpenId];
+        bot.allowedUsers = [await resolveOpenIdToUnionId(creds.appId, creds.appSecret, creds.userOpenId)];
     }
     else {
         bot.allowedUsers = await promptRequiredOwner(rl);