botmux 2.9.1 → 2.9.3

package/README.en.md

@@ -48,7 +48,7 @@ Compared to OpenClaw-style approaches built on Agent SDKs:
 | Feature | botmux | OpenClaw-style |
 |---------|--------|---------------|
 | Architecture | Bridges full CLI processes directly | Rebuilds on Agent SDK |
-| CLI Capabilities | Full runtime (hooks, memory, plan mode, MCP ecosystem, `/` commands) | SDK API subset, missing features must be reimplemented |
+| CLI Capabilities | Full runtime (hooks, memory, plan mode, skills, `/` commands) | SDK API subset, missing features must be reimplemented |
 | CLI Upgrades | Zero-adaptation automatic benefit | Must track SDK version changes |
 | Memory / Context | Reuses CLI's built-in memory system, improves as the CLI evolves | Must build custom memory system, duplicating CLI-native capabilities |
 | Multi-CLI Support | 4 CLIs, switch with one config (Claude Code / Codex / Gemini / OpenCode) | Tied to a single SDK, cannot switch CLIs |
@@ -71,78 +71,73 @@ 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 (local)
+cat ~/.botmux/lark-scopes.json | pbcopy
+# Linux desktop (local X server)
+cat ~/.botmux/lark-scopes.json | xclip -selection clipboard
+# SSH / headless: just cat — selecting in your local terminal copies to your local clipboard
+cat ~/.botmux/lark-scopes.json
+# SSH via OSC 52 — write to local clipboard through terminal (iTerm2 / kitty / WezTerm / Alacritty / tmux 1.5+)
+base64 -w0 < ~/.botmux/lark-scopes.json | awk 'BEGIN{printf "\033]52;c;"}{printf "%s",$0}END{printf "\a"}'
+```
+
+> 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.
+
+### Step 5: Add Redirect URL (optional)
 
-![Add event](docs/setup/event-receive-msg.png)
+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":
 
-3. **Enable callback**: Switch to the "Callback Configuration" tab, turn on "Card action callback" (`card.action.trigger`)
+```
+http://127.0.0.1:9768/callback
+```
+
+Skip this step if you only need bot messaging.
 
 ### Step 6: Publish the App
 
@@ -158,6 +153,25 @@ 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: 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:
+
+```bash
+botmux autostart enable
+```
+
+This registers the daemon with your user's init system (launchd on macOS, user systemd on Linux). **No sudo required.** After a reboot — or after logging back in — the daemon comes up on its own. See [CLI Commands § Boot-time Autostart](#boot-time-autostart) below for the full reference.
+
 ---
 
 ## Features
@@ -182,7 +196,7 @@ On mobile/tablet, a floating shortcut toolbar provides Esc, Ctrl+C, Tab, arrow k
 
 ### Multi-Bot Collaboration
 
-Run multiple Lark bots on a single machine, each mapped to a different CLI. In the same group chat, messages are routed via @mention — each bot gets its own isolated CLI process. With a single bot in the group, it responds automatically without @.
+Run multiple Lark bots on a single machine, each mapped to a different CLI. In the same group chat, messages are routed via @mention — each bot gets its own isolated CLI process. With a single bot in the group, it responds automatically without @. In a regular (non-topic) group, `@<bot1> @<bot2> /t xxx` spawns one independent thread per mentioned bot anchored at the same message.
 
 ### Tmux Persistence
 
@@ -191,8 +205,8 @@ When tmux is installed, botmux automatically uses it. CLI processes persist insi
 **Key benefit: daemon restarts don't interrupt the CLI.** During `botmux restart`, the worker process exits but the tmux session (and the CLI inside it) keeps running. The next incoming message triggers a re-attach — no `--resume` context reload needed.
 
 ```bash
-# Recommended: interactive session picker — select and attach to tmux
-npx botmux list
+# Interactive session picker — select and attach to tmux (see § CLI Commands)
+botmux list
 
 # Or manually attach (session name = bmx-<first 8 chars of session ID>)
 tmux attach -t bmx-<first-8-chars-of-session-id>
@@ -202,10 +216,6 @@ tmux attach -t bmx-<first-8-chars-of-session-id>
 BACKEND_TYPE=pty botmux start
 ```
 
-`botmux list` provides an interactive TUI showing all active sessions with ID, title, working directory, PID, uptime, and status. Use arrow keys to select and Enter to attach. Use `botmux list --plain` for plain-text table output suitable for scripting.
-
-**Session naming:** `bmx-<first 8 chars of session UUID>`
-
 **Lifecycle:**
 
 | Event | tmux session | CLI process |
@@ -246,13 +256,28 @@ When a CLI spawns inside a botmux session it automatically gets
 `~/.botmux/bin` on PATH plus a set of ready-to-use Skills:
 
 - `botmux send` — send a message to the current thread (text, images, files, @mention)
-- `botmux thread messages` — fetch thread history
+- `botmux history` — fetch session history (topic groups → in-thread, regular groups → whole chat)
+- `botmux quoted <message_id>` — when the user @ed the bot via Lark's quote-reply UI, fetch the quoted message on demand
 - `botmux bots list` — discover bots + their `open_id`s
 - `botmux schedule` — manage scheduled tasks
 
 These capabilities are wired via `--append-system-prompt` and Skill
-descriptions, so the agent picks them up automatically. The pre-April-2026
-MCP entry point has been removed (stale config is auto-cleaned on upgrade).
+descriptions, so the agent picks them up automatically. Compared to
+Anthropic's official Telegram channel — which exposes each action as an
+MCP tool — the Skill + CLI combo skips the MCP handshake on every CLI
+launch, doesn't burn tool-list tokens, and works across every CLI that
+can read a system prompt and shell out (Claude Code / Codex / Gemini /
+OpenCode), with no MCP protocol support required.
+
+### Dashboard
+
+> `botmux dashboard` issues a one-time-token URL — manage every daemon/bot from the browser.
+
+- One-click locate back to the Feishu thread / open Web Terminal / multi-select batch close
+- Create a new group with auto owner-transfer + @-mention notification
+- Disband or leave a chat (associated sessions auto-closed)
+
+<img src="docs/dashboard.png" alt="botmux dashboard" width="800" />
 
 ---
 
@@ -260,8 +285,8 @@ MCP entry point has been removed (stale config is auto-cleaned on upgrade).
 
 ### Workflow
 
-1. Send a message in your Lark topic group to create a new thread
-2. The bot shows a repo selection card — pick a project or click "Start directly"
+1. Send a message in a Lark topic group to create a new thread; or in a regular group send `/t <prompt>` to force-open a new topic
+2. The bot shows a repo selection card — pick a project or click "Start directly" (chats bound via `/oncall bind` skip this step)
 3. The CLI spawns in the selected directory
 4. A live streaming card appears in the thread, showing real-time terminal output with markdown rendering
 5. Each reply creates a new streaming card for that turn; previous cards freeze at their last state
@@ -278,20 +303,21 @@ MCP entry point has been removed (stale config is auto-cleaned on upgrade).
 | `/cd <path>` | Change working directory |
 | `/status` | Show session info (uptime, terminal URL, etc.) |
 | `/restart` | Restart CLI process |
-| `/close` | Close session and terminate CLI |
+| `/close` | Close session and send a resumable card (with the CLI's native resume command) |
+| `/t <prompt>` / `/topic <prompt>` | Force-open a new topic from a non-topic group (shows the repo selector); empty prompt is allowed — fill it in after picking the repo |
+| `/oncall bind <path>` | Bind current chat to a project dir, skip the repo card (any group member can @ the bot; buttons / daemon commands still gated by `allowedUsers`) |
+| `/oncall unbind` / `/oncall status` | Unbind / inspect oncall binding |
 | `/adopt` | Adopt a running CLI session (tmux) |
 | `/schedule` | Manage scheduled tasks |
+| `/login` / `/login status` | Lark user OAuth (e.g. to download images from third-party cards) / show OAuth status |
 | `/help` | Show available commands |
 | `/compact` `/model` `/clear` `/plugin` `/usage` | Forwarded verbatim to the underlying CLI (e.g. Claude Code's built-in slash commands) |
 
 ### Scheduled Task Management
 
-**Recommended: talk to the agent**
-Just say "add a reminder to summarize yesterday's PRs every morning at 9:00" — the `botmux-schedule` Skill handles it and confirms with you.
+Two creation paths are covered above in [Scheduled Tasks](#scheduled-tasks); below is just the slash-command syntax and management commands.
 
-**Slash command (quick)**
-
-```
+```bash
 # Chinese NL
 /schedule 每日17:50 check AI news
 /schedule 工作日每天9:00 run health check
@@ -301,22 +327,14 @@ Just say "add a reminder to summarize yesterday's PRs every morning at 9:00" —
 /schedule 30分钟后 verify deployment
 /schedule 明天9:00 standup reminder
 
-# English
+# English / cron
 /schedule every 2h probe services
 /schedule 30m remind me to drink water
-
-# Cron
 /schedule 0 9 * * * good morning
-```
-
-Manage tasks:
 
-```
+# Manage
 /schedule list
-/schedule remove <id>
-/schedule enable <id>
-/schedule disable <id>
-/schedule run <id>
+/schedule remove|enable|disable|run <id>
 ```
 
 **Execution behavior**: the task fires inside the **original thread where it was created** — no new topic per run. Working directory is preserved. If the original session is still alive, the prompt is injected into it; otherwise a fresh worker spawns bound to the same thread root.
@@ -362,6 +380,7 @@ botmux setup
 | `workingDir` | No | Default working directory, supports comma-separated |
 | `allowedUsers` | No | Allowed users (email prefixes or open_ids) |
 | `projectScanDir` | No | Directory to scan for git repos |
+| `oncallChats` | No | Oncall bindings (written by `/oncall bind`), e.g. `[{ "chatId": "oc_xxx", "workingDir": "~/projects/foo" }]`; any group member can @ the bot |
 
 **Config priority:** `BOTS_CONFIG` env var > `~/.botmux/bots.json`
 
@@ -400,6 +419,22 @@ botmux setup
 | `botmux delete <id>` | Close a session by ID prefix (alias: `del`/`rm`) |
 | `botmux delete all` | Close all active sessions |
 | `botmux delete stopped` | Clean up zombie sessions with dead processes |
+| `botmux autostart enable` | Register boot-time autostart (macOS launchd / Linux user systemd, no sudo) |
+| `botmux autostart disable` | Unregister boot-time autostart |
+| `botmux autostart status` | Show autostart status |
+| `botmux dashboard` | Print a fresh Web Dashboard URL (rotates the token; previous URL becomes invalid) |
+
+### Boot-time Autostart
+
+`botmux autostart enable` registers the daemon with your user's init system so it comes back automatically after a reboot:
+
+- **macOS**: writes `~/Library/LaunchAgents/com.botmux.daemon.plist` and loads it via `launchctl bootstrap`. **No sudo required.**
+- **Linux**: writes `~/.config/systemd/user/botmux.service` and runs `systemctl --user enable --now`. **No sudo required.**
+  - On servers / headless boxes the user systemd manager stops when you log out. To survive logouts and reboots, also run `sudo loginctl enable-linger <your-user>` — `autostart enable` warns when linger is off.
+  - Containers / SSH-only sessions without a user DBus fall back to printing manual instructions.
+- The `node` and `cli.js` paths baked into the unit come from `process.execPath` at install time. After switching nvm/fnm versions, run `botmux autostart enable` once to rewrite. `botmux start`/`restart` also detect path drift and refresh the unit in place — no manual step needed.
+- `enable` / `disable` **only manage the autostart hook — they do not touch a running daemon**. To start the daemon right away run `botmux start`; to stop it run `botmux stop`. This avoids the "I just wanted to turn off autostart, why did my service also die" footgun.
+- If you prefer letting systemd own the lifecycle (`systemctl --user start/stop botmux`), that works too — the unit declares `ExecStop=botmux stop` for a clean shutdown path.
 
 ### Agent-facing subcommands
 
@@ -409,7 +444,8 @@ Run from inside a botmux-spawned CLI session — session context is auto-detecte
 |------------|-------------|
 | `botmux send [content]` | Send a message to the current thread (stdin / heredoc / `--content-file`; `--images` / `--files` / `--mention` flags) |
 | `botmux bots list` | List bots in the current chat (includes `open_id` for `--mention`) |
-| `botmux thread messages [--limit N]` | Fetch thread message history (JSON) |
+| `botmux history [--limit N]` | Fetch session message history (JSON); topic groups → in-thread, regular groups → whole chat |
+| `botmux quoted <message_id>` | Fetch a single quoted message (JSON); the ID comes from the daemon-injected `[用户引用了消息 用 botmux quoted om_xxx 查看]` prefix |
 | `botmux schedule add <schedule> <prompt>` | Create a scheduled task bound to the current thread |
 | `botmux schedule list/remove/pause/resume/run` | Manage scheduled tasks |
 
@@ -417,6 +453,34 @@ These require the `~/.botmux/bin/botmux` wrapper, which the daemon writes at sta
 
 ---
 
+## Web Dashboard
+
+botmux ships a LAN-accessible Web Dashboard for managing all sessions and scheduled tasks across every configured bot.
+
+```bash
+botmux dashboard
+# prints: http://<lan-ip>:7891/?t=<token>
+```
+
+Each invocation rotates the token — previous URLs are invalidated immediately. This is by design, so a leaked link stops working as soon as you fetch a new one.
+
+v1 features:
+- **Sessions board** — every active and closed session across every bot, filterable by CLI / status / adopt / free-text. The detail drawer exposes a "📍 定位到飞书话题" button that posts a marker into the original thread (workaround for Feishu having no public topic deep-link), then opens AppLink to the chat. Also: copy IDs, close session, open xterm.
+- **Schedules board** — every scheduled task across every bot, with Run-now / Pause / Resume actions.
+
+Environment variables (set in `~/.botmux/.env`):
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `BOTMUX_DASHBOARD_HOST` | `0.0.0.0` | Dashboard HTTP bind address |
+| `BOTMUX_DASHBOARD_PORT` | `7891` | Dashboard HTTP port |
+| `BOTMUX_DASHBOARD_EXTERNAL_HOST` | `WEB_EXTERNAL_HOST` or LAN-IP autodetect | Host used in the printed URL |
+| `BOTMUX_DAEMON_IPC_BASE_PORT` | `7892` | Per-daemon IPC port = base + botIndex |
+
+The dashboard runs as its own pm2 process (`botmux-dashboard`) — `pnpm daemon:restart` brings it up alongside every bot daemon. Each daemon exposes a localhost-only IPC at `127.0.0.1:7892+botIndex`; the dashboard process is a thin reverse proxy + token gate. The HMAC secret at `~/.botmux/.dashboard-secret` (mode `0600`) is generated on first start and is used only to sign `botmux dashboard` rotation requests — it never reaches the browser.
+
+---
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).