lark-agent-bridge 0.1.39

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lark Channel Bridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+# lark-agent-bridge
+
+A lightweight bot that bridges Feishu / Lark messenger with your local coding-agent CLI (Claude Code, Cursor Agent, or another compatible wrapper). Run one command, scan a QR code to bind a Lark app, and talk to the agent from chat — read screenshots, edit code, anything you'd do at the terminal.
+
+[中文 README](./README.zh.md)
+
+## What it does
+
+- Forwards Feishu / Lark messages (DM directly, or `@bot` in a group) to your local coding agent, running in a working directory you control.
+- **Streaming card**: the agent's text and tool calls update on a single Lark card in real time — no waiting for the final reply.
+- **Resilient run UI**: failed or timed-out runs show a one-click retry button; card update failures degrade to a plain markdown fallback instead of leaving a stale running card.
+- **Per-chat sessions**: each chat keeps its own agent session, so conversations resume where they left off.
+- **Preempt + batch**: a new message interrupts the running run; rapid-fire messages get coalesced into one request.
+- **Multiple workspaces**: `/ws` switches between named project directories, with sessions tracked per workspace.
+- **Images and files**: send them to the bot directly — the agent reads the locally downloaded paths.
+- **Interactive cards**: `/help`, `/ws list`, `/status` return cards with buttons you can click.
+
+## Prerequisites
+
+- Node.js **>= 20**
+- A supported coding-agent command installed and logged in. By default the bridge runs `claude`; it can also use compatible wrappers through `agentCommand`, or Cursor CLI's `agent` command.
+- A Lark / Feishu **PersonalAgent** app (the QR-code wizard on first launch can create one for you).
+
+## Install
+
+```bash
+npm i -g lark-agent-bridge
+# or
+pnpm add -g lark-agent-bridge
+```
+
+Run without installing:
+
+```bash
+npx -y lark-agent-bridge@latest start
+```
+
+## First run
+
+```bash
+lark-agent-bridge start
+```
+
+The first run detects there's no app configured and **opens a QR-code wizard**:
+
+1. A QR code renders in your terminal.
+2. Scan it with the Feishu / Lark app.
+3. Pick or create a PersonalAgent app.
+4. Credentials are written to `~/.lark-channel/config.json`.
+
+### Granting scopes and event subscriptions
+
+The wizard creates the app shell, but you still need to confirm a few things on the Lark Developer Console:
+
+**Permission scopes:**
+- `im:message`
+- `im:message:send_as_bot`
+- `im:resource`
+
+**Event subscriptions (over long-lived WebSocket):**
+- `im.message.receive_v1`
+- `card.action.trigger`
+- `im.message.reaction.created_v1` / `deleted_v1` (optional)
+- `im.chat.member.bot.added_v1` (optional)
+
+After enabling those, run `lark-agent-bridge start` again. Once you see `✓ Connected`, find the bot in Feishu / Lark and start chatting.
+
+## Commands
+
+### Host CLI
+
+```
+lark-agent-bridge start [-c <config>]   Start the bot
+lark-agent-bridge ps                    List all running start processes on this machine
+lark-agent-bridge stop <id|#>           Stop a start process (SIGTERM, SIGKILL after 2s)
+lark-agent-bridge --help                List all commands
+```
+
+> When the same app is started multiple times, Lark's open platform routes events to one of the live WebSocket connections at random. `start` detects existing processes for the same app and (in a TTY) prompts: `[c]ontinue / [k]ill old / [a]bort`. In non-TTY mode it warns and continues.
+
+`handover` / `workspace` / `service` are placeholders, planned for later releases.
+
+### Slash commands inside Feishu / Lark
+
+| Command | Effect |
+|---|---|
+| `/new`, `/reset` | Clear the current chat's session |
+| `/cd <path>` | Switch working directory (resets session) |
+| `/ws list` | List named workspaces (card + buttons) |
+| `/ws save <name>` | Save current cwd as a named workspace |
+| `/ws use <name>` | Switch to a named workspace |
+| `/ws remove <name>` | Delete a named workspace |
+| `/status` | Current cwd / session / agent (card + buttons) |
+| `/config` | Adjust preferences (reply style, tool-call display, ...) |
+| `/stop` | Stop the run in progress (also the `⏹` button on the card) |
+| `/timeout [N\|off\|default]` | Idle-watchdog (minutes) for the current session. `/config` sets the global default. See FAQ below. |
+| `/retry <run-id>` | Replay a recent failed or timed-out run. Failed cards include a one-click retry button. |
+| `/shell <command>` | Run a shell command in the current cwd and return stdout/stderr. Admin-only when admins are configured; capped at 30s and 12k chars. |
+| `/workers` | Show Cursor SDK worker-pool health: status, queue count, current run, session/cwd, and recent error. |
+| `/ps` | List all `start` processes on this host, marking the one replying |
+| `/exit <id\|#>` | Stop a `start` process (your own → graceful; another's → SIGTERM) |
+| `/reconnect` | Force a WebSocket reconnect (use when the bot stops responding after a network blip) |
+| `/doctor [description]` | Feed recent logs, run timeline, and your description back to the agent for self-diagnosis |
+| `/doctor workers` | Shortcut for the live SDK worker-pool view |
+| `/help` | Help card |
+| Any other `/xxx` | Forwarded verbatim to the agent |
+
+**Reply policy**: in a DM, the bot replies to anything. In a **group (including topic groups), the bot only replies when `@`-mentioned** (default since 0.1.22); unmentioned messages are ignored. `@all` is never answered. Cloud-doc comments must mention the bot. To restore the older "always answer in groups" behaviour: `/config` → "Require @bot in groups" → No.
+
+## Data directories
+
+| Path | Content |
+|---|---|
+| `~/.lark-channel/config.json` | App credentials (App ID / Secret), mode 600 |
+| `~/.lark-channel/sessions.json` | Agent session id + cwd per chat / topic (+ optional `/timeout` override) |
+| `~/.lark-channel/workspaces.json` | Named-workspace map |
+| `~/.lark-channel/processes.json` | Process registry for live `start` instances (used by `ps`/`stop`); dead PIDs are auto-pruned |
+| `~/.lark-channel/media/<chatId>/` | Downloaded images / files, cleaned up after 24h |
+| `~/.lark-channel/logs/YYYY-MM-DD.log` | Structured run logs (JSONL), rotated daily; older than 7 days are pruned at startup (`LARK_CHANNEL_LOG_DAYS` env var overrides). `/doctor` reads these. |
+
+> Upgrading from before 0.1.11? Run `lark-agent-bridge migrate` once — it moves anything under the legacy `~/.config/lark-channel-bridge/` and `~/.cache/lark-channel-bridge/` paths to the new location and upgrades `config.json` to the new schema.
+
+### Custom agent command
+
+By default the bridge uses the Claude backend and appends Claude Code arguments to `claude`. To use a compatible wrapper, add `preferences.agentCommand` to `~/.lark-channel/config.json`:
+
+```json
+{
+  "preferences": {
+    "agentCommand": {
+      "backend": "claude",
+      "command": "my-claude-wrapper",
+      "args": ["--model", "gpt-5.5"],
+      "claudeArgsOption": "--claude-args"
+    }
+  }
+}
+```
+
+With `claudeArgsOption`, the bridge safely joins Claude Code arguments and runs commands like `my-claude-wrapper --model gpt-5.5 --claude-args "-p ... --output-format stream-json --verbose ..."`. Without `claudeArgsOption`, it appends Claude args as normal argv entries. If `agentCommand` is omitted, it keeps using plain `claude`.
+
+### Cursor backend (`@cursor/sdk` or CLI)
+
+To use Cursor Agent, configure the Cursor backend. The default runtime is `@cursor/sdk`: the bridge keeps a small LRU pool of persistent SDK agents, resumes the original Cursor session across messages, and exposes `/workers` plus `/doctor workers` for worker-pool diagnosis.
+
+```json
+{
+  "preferences": {
+    "agentCommand": {
+      "backend": "cursor",
+      "command": "agent"
+    },
+    "agentCursorRuntime": "sdk",
+    "agentSessionPoolSize": 10,
+    "agentCursorApiKey": "${CURSOR_API_KEY}",
+    "agentCursorModel": "gpt-5.5-extra-high-fast"
+  }
+}
+```
+
+For SDK mode, provide a Cursor API key with `CURSOR_API_KEY`, or store it encrypted with `lark-agent-bridge secrets set --id cursor-api-key` and reference it from `agentCursorApiKey`. `agentCursorModel` uses Cursor CLI-style model ids; the bridge maps known variants to the SDK model-selection shape. For full control, set `agentCursorSdkModel` directly:
+
+```json
+{
+  "preferences": {
+    "agentCursorSdkModel": {
+      "id": "gpt-5.5",
+      "params": [{ "id": "reasoning", "value": "extra-high" }]
+    }
+  }
+}
+```
+
+Set `"agentCursorRuntime": "cli"` to force the legacy Cursor CLI path. In CLI mode, make sure the `agent` command is installed, logged in, and available on `PATH`; the bridge runs `agent -p --output-format stream-json --trust --workspace <cwd> ...`. If you intentionally want Cursor to auto-allow commands, add `"-f"` or `"--force"` to `agentCommand.args`.
+
+## Access control (optional)
+
+Out of the box the bot is **open**: anyone who can find it can DM it, any group member can `@`-mention it to trigger a run, and commands like `/account` or `/cd` are usable by all. **That's fine for personal use** — but for a shared team setup, or anywhere you don't want strangers calling `/cd /`, you can tighten three allowlists by sending `/config` inside Feishu.
+
+### Common scenarios
+
+**Just me**
+
+In the `/config` form:
+- **Allowed users**: your own `open_id`
+- Leave the other two blank
+
+Messages from anyone else are silently dropped — no denial reply, since that would just confirm the bot exists to outsiders.
+
+**A small team**
+
+- **Allowed users**: comma-separated `open_id`s of team members
+- Other two blank
+
+**Bot only responds in specific work groups**
+
+DMs are unaffected; only listed groups trigger responses:
+- **Allowed chats**: comma-separated `chat_id`s of the groups
+- DMs are **always** exempt from this list — so you can always DM the bot to change config later.
+
+**Anyone can chat with the bot, but only I can change settings**
+
+- **Admins**: your own `open_id`
+- Other two blank
+
+Others running `/account`, `/config`, `/exit`, `/reconnect`, `/doctor`, `/workers`, `/shell`, `/cd`, or `/ws` get a `❌ 此命令仅管理员可用` reply. Normal conversation (asking the bot to do things) is unaffected.
+
+**Lock everything down**
+
+Fill all three. The `/config` form catches common mistakes — e.g. if your admin list doesn't include yourself, or your chat allowlist doesn't include the chat you're submitting from, the submit is rejected with a message explaining why, so you can't accidentally lock yourself out.
+
+### Finding `open_id` and `chat_id`
+
+Easiest path: have the target user send the bot a message (or `@`-mention it in the target group), then in your terminal:
+
+```bash
+grep '"event":"enter"' ~/.lark-channel/logs/$(date +%Y-%m-%d).log | tail -5
+```
+
+Every line carries `chatId` (group or DM id) and `senderId` (the user's `open_id`). Copy them from there.
+
+The Feishu open-platform "Get user info" API also works but needs the `contact:user` scope, which is overkill if you just need a couple of IDs.
+
+### Worth knowing
+
+- Changes take effect on the **next message** — no restart needed.
+- An empty field means **unrestricted**, not "nobody allowed".
+- To revert a restricted list back to fully open, clear that field in `/config` and submit.
+- DMs are deliberately exempt from the chat allowlist — meaning if you ever accidentally restrict the bot out of every group, **DM the bot and send `/config`** to recover.
+
+### Advanced: editing the config file directly
+
+The `/config` form writes to `~/.lark-channel/config.json` under `preferences.access`:
+
+```json
+{
+  "preferences": {
+    "access": {
+      "allowedUsers": ["ou_xxxxxxxxxxxxx"],
+      "allowedChats": ["oc_xxxxxxxxxxxxx"],
+      "admins":       ["ou_xxxxxxxxxxxxx"]
+    }
+  }
+}
+```
+
+After a manual edit, **restart the bridge** or send **`/reconnect`** from any allowed chat to pick up the changes. The form is usually faster; direct edits make sense mostly for deployment scripts where you want to pre-seed access policy.
+
+## FAQ
+
+**The bot stays silent / Claude never replies.** Usually the `claude` CLI itself is not logged in, or the session points to a cwd that no longer exists. Send `/status` to inspect; `/new` to start a fresh session.
+
+**Claude subprocess looks frozen (card stuck on the last frame).** Since 0.1.20 there's an idle watchdog: if Claude emits nothing for N minutes the process is killed and the card is annotated `⏱ N min no response, auto-terminated`. Disabled by default. Enable with `/config` (global, in minutes), or `/timeout 10` to set it on the current session; `/timeout off` disables for the session; `/timeout default` clears the session override.
+
+**The card says the agent failed. Can I retry?** Failed and idle-timeout run cards include a one-click retry button when the bridge has the original run in recent history. You can also run `/retry <run-id>` in the same chat/topic. Retries are scoped to the original conversation so a failed task cannot be replayed from another chat by accident.
+
+**How do I debug a stuck card or Cursor SDK worker?** Run `/doctor <what happened>` to analyze recent structured logs. The doctor prompt includes a run timeline covering `intake -> queue -> session -> agent -> card update -> done`, which helps identify whether the run stopped in Lark updates, session setup, or the agent. For Cursor SDK worker health only, run `/workers` or `/doctor workers`.
+
+**Cursor SDK returns `status=error` with no detail.** The bridge treats opaque Cursor SDK run failures as fatal to that SDK worker: it surfaces the final reason, discards the worker, and creates a fresh worker/session on the next run. Recoverable rate-limit, network, and stale-session paths record how many automatic recovery steps happened before the final failure.
+
+**Claude says it can't see the image I sent.** Upgrade to the latest version — releases before 0.1.0 had a filename-dedup bug.
+
+## License
+
+[MIT](./LICENSE)

package/README.zh.md

@@ -0,0 +1,265 @@
+# lark-agent-bridge
+
+把飞书 / Lark 消息和本地 coding-agent CLI（Claude Code、Cursor Agent，或其它兼容包装命令）打通的轻量 bot，用一条命令起服务，扫码绑应用，在飞书里和 agent 对话、让它读图 / 改代码。
+
+[English README](./README.md)
+
+## 能干什么
+
+- 在飞书（私聊直接发；群里 `@bot`）把消息转给本地 agent，agent 在你指定的工作目录里工作
+- **流式卡片**：agent 的文本和工具调用实时出现在同一张卡片上，不用傻等
+- **可靠的运行 UI**：失败或超时的任务会显示一键重试；卡片更新失败时会降级成普通 markdown，避免一直卡在“运行中”
+- **会话延续**：每个 chat 独立 session，对话能接着上次说
+- **抢占 + 批处理**：中途发新消息会打断旧任务；快速连发几条会合并成一次请求
+- **多工作空间**：`/ws` 切换不同项目，session 自己重置
+- **图片 / 文件**：直接发给 bot，agent 会读本地下载的文件路径
+- **卡片按钮**：`/help` `/ws list` `/status` 返回交互卡片，点按钮直接操作
+
+## 前置条件
+
+- Node.js **≥ 20**
+- 已安装并登录一个受支持的 coding-agent 命令。默认运行 `claude`；也可以通过 `agentCommand` 使用兼容包装命令，或使用 Cursor CLI 的 `agent` 命令。
+- 一个飞书 / Lark PersonalAgent 应用（首次启动的扫码向导能帮你创建）
+
+## 安装
+
+```bash
+npm i -g lark-agent-bridge
+# 或
+pnpm add -g lark-agent-bridge
+```
+
+也可以不安装直接运行：
+
+```bash
+npx -y lark-agent-bridge@latest start
+```
+
+## 首次启动
+
+```bash
+lark-agent-bridge start
+```
+
+第一次跑会检测到没配置应用，**自动进入扫码向导**：
+
+1. 终端渲染一个二维码
+2. 用飞书 App 扫码
+3. 选择 / 创建 PersonalAgent 应用
+4. 成功后凭据写入 `~/.lark-channel/config.json`
+
+### 开放平台补齐 scope 和事件订阅
+
+向导只负责创建应用，平台侧还需要手动确认：
+
+**权限 scope**：
+- `im:message`
+- `im:message:send_as_bot`
+- `im:resource`
+
+**事件订阅（使用长连接接收）**：
+- `im.message.receive_v1`
+- `card.action.trigger`
+- `im.message.reaction.created_v1` / `deleted_v1`（可选）
+- `im.chat.member.bot.added_v1`（可选）
+
+启用以后再次 `lark-agent-bridge start`，看到 `✓ 已连接` 就可以在飞书里找 bot 对话了。
+
+## 命令速查
+
+### 宿主 CLI
+
+```
+lark-agent-bridge start [-c <config>]   启动 bot
+lark-agent-bridge ps                    列出本机所有正在跑的 start 进程
+lark-agent-bridge stop <id|#>           终止指定 start 进程（SIGTERM，2s 后 SIGKILL）
+lark-agent-bridge --help                列所有命令
+```
+
+> 多开同一个 app 时，开放平台会把事件随机推到其中一个长连接。`start` 启动前会检测同 app 已有的进程，TTY 下提示 `[c]ontinue / [k]ill old / [a]bort` 三选；非 TTY 只 warn 并继续。
+
+其它命令（`status` / `doctor` / `handover` / `workspace` / `service`）是占位，后续版本补。
+
+### 在飞书里用的斜杠命令
+
+| 命令 | 作用 |
+|---|---|
+| `/new` `/reset` | 清空当前 chat 的会话 |
+| `/cd <path>` | 切换工作目录（会重置 session） |
+| `/ws list` | 列所有命名工作空间（卡片 + 按钮） |
+| `/ws save <name>` | 把当前 cwd 存为命名工作空间 |
+| `/ws use <name>` | 切换到命名工作空间 |
+| `/ws remove <name>` | 删除命名工作空间 |
+| `/status` | 当前 cwd / session / agent（卡片 + 按钮） |
+| `/config` | 调整偏好（消息回复方式、工具调用显示等） |
+| `/stop` | 终止当前正在跑的 run（也可点卡片底部 ⏹ 终止 按钮） |
+| `/timeout [N\|off\|default]` | 当前 session 的 idle 探活（分钟）；`/config` 改全局默认。详见下方"常见问题 — Claude 子进程假死" |
+| `/retry <run-id>` | 重放最近失败或超时的任务；失败卡片里也有一键重试按钮 |
+| `/shell <command>` | 在当前 cwd 执行 shell 命令并回传 stdout/stderr。配置管理员后仅管理员可用；限制 30 秒和 12k 字符输出 |
+| `/workers` | 查看 Cursor SDK worker pool 健康状态：状态、队列、当前 run、session/cwd 和最近错误 |
+| `/ps` | 列出本机所有 start 进程，标识当前回复的是哪个 |
+| `/exit <id\|#>` | 终止指定 start 进程（自己 = graceful 退出；他人 = SIGTERM） |
+| `/reconnect` | 强制重连 WebSocket（网络抖动后 bot 没反应时用） |
+| `/doctor [描述]` | 把最近运行日志和你的描述喂给 agent，自助诊断卡住 / 异常的原因 |
+| `/doctor workers` | 直接查看当前 SDK worker pool 状态 |
+| `/help` | 帮助卡片 |
+| 其它 `/xxx` | 原样交给 agent |
+
+**消息策略**：私聊 = 不需要 @，任何消息都回；**群（含话题群）= 默认要 @bot 才回**（0.1.22 起的新默认），不 @ 时 bot 完全沉默；@全员永远不响应；云文档评论必须 @bot。要恢复"群里也不强制 @"的老行为：`/config` → "群里需要 @ bot" → 选"否"。
+
+## 数据目录
+
+| 路径 | 内容 |
+|---|---|
+| `~/.lark-channel/config.json` | 应用凭据（App ID / Secret），权限 600 |
+| `~/.lark-channel/sessions.json` | 每个 chat / 话题 的 agent session id + cwd（+ 可选的 `/timeout` 覆盖） |
+| `~/.lark-channel/workspaces.json` | 工作空间映射 |
+| `~/.lark-channel/processes.json` | 当前在跑的 start 进程注册中心（`ps`/`stop` 用），死进程会被自动清理 |
+| `~/.lark-channel/media/<chatId>/` | 下载的图片 / 文件，24h 自动清理 |
+| `~/.lark-channel/logs/YYYY-MM-DD.log` | 结构化运行日志（JSON line），按天滚动；启动时清理超过 7 天的老文件（`LARK_CHANNEL_LOG_DAYS` 环境变量可改）；`/doctor` 命令读它做诊断 |
+
+> 升级自 0.1.11 之前的版本？跑一次 `lark-agent-bridge migrate` —— 自动把旧路径 `~/.config/lark-channel-bridge/` 和 `~/.cache/lark-channel-bridge/` 下的内容搬到新位置，并把 `config.json` 升级到新结构。
+
+### 自定义 agent 命令
+
+默认情况下 bridge 使用 Claude backend，并把 Claude Code 参数追加到 `claude` 后面。要使用兼容包装命令，可以在 `~/.lark-channel/config.json` 里加入 `preferences.agentCommand`：
+
+```json
+{
+  "preferences": {
+    "agentCommand": {
+      "backend": "claude",
+      "command": "my-claude-wrapper",
+      "args": ["--model", "gpt-5.5"],
+      "claudeArgsOption": "--claude-args"
+    }
+  }
+}
+```
+
+配置 `claudeArgsOption` 后，bridge 会把 Claude Code 参数安全拼成一个字符串，运行类似 `my-claude-wrapper --model gpt-5.5 --claude-args "-p ... --output-format stream-json --verbose ..."` 的命令。不配置 `claudeArgsOption` 时会把 Claude 参数作为普通 argv 追加；不配置 `agentCommand` 时仍然使用默认的 `claude`。
+
+### Cursor backend（`@cursor/sdk` 或 CLI）
+
+要接入 Cursor Agent，配置 Cursor backend。默认 runtime 是 `@cursor/sdk`：bridge 会维护一个小型 LRU 的持久 SDK agent 池，在多轮消息之间 resume 原 Cursor session，并提供 `/workers` 和 `/doctor workers` 用于诊断 worker pool。
+
+```json
+{
+  "preferences": {
+    "agentCommand": {
+      "backend": "cursor",
+      "command": "agent"
+    },
+    "agentCursorRuntime": "sdk",
+    "agentSessionPoolSize": 10,
+    "agentCursorApiKey": "${CURSOR_API_KEY}",
+    "agentCursorModel": "gpt-5.5-extra-high-fast"
+  }
+}
+```
+
+SDK 模式需要 Cursor API key：可以通过环境变量 `CURSOR_API_KEY` 提供，也可以用 `lark-agent-bridge secrets set --id cursor-api-key` 加密保存后，在 `agentCursorApiKey` 里引用。`agentCursorModel` 使用 Cursor CLI 风格的模型 id；bridge 会把已知变体映射到 SDK model-selection 结构。如果想完全手写 SDK 选择，可以直接配置 `agentCursorSdkModel`：
+
+```json
+{
+  "preferences": {
+    "agentCursorSdkModel": {
+      "id": "gpt-5.5",
+      "params": [{ "id": "reasoning", "value": "extra-high" }]
+    }
+  }
+}
+```
+
+如果要强制使用旧的 Cursor CLI 路径，把 `"agentCursorRuntime"` 设为 `"cli"`。CLI 模式下需要确认 `agent` 命令已安装、已登录，并且在 `PATH` 中可用；bridge 会用类似 `agent -p --output-format stream-json --trust --workspace <cwd> ...` 的方式运行。如果你明确希望 Cursor 自动允许命令，可以把 `"-f"` 或 `"--force"` 加到 `agentCommand.args`。
+
+## 访问控制（可选）
+
+默认 bot 是"开放"的：任何能找到它的人都能私聊它，群里 @bot 就触发响应。**个人自己用 / 给朋友用，这就够了**——但如果想给团队用、或者怕在大群里被滥用，可以在飞书里发 `/config`，调下面三栏中的一栏或几栏。
+
+### 几种典型用法
+
+**只让我自己用**
+
+`/config` 表单里：
+- "用户白名单"：填你自己的 `open_id`
+- 其它两栏留空
+
+之后非你发的消息会被 bot 静默丢弃——bot 不会回"你没权限"之类的话，免得暴露它存在。
+
+**只让一小群同事用**
+
+- "用户白名单"：填同事们的 `open_id`，英文逗号分隔
+- 其它两栏留空
+
+**bot 只在指定工作群里干活**
+
+私聊不受影响；群里只有名单上的群才触发响应：
+- "群白名单"：填想让 bot 工作的群 `chat_id`，英文逗号分隔
+- 私聊**永远**不受此约束——意味着你随时能 DM bot 调配置
+
+**谁都能跟 bot 聊，但只有我能改设置**
+
+- "管理员"：填你自己的 `open_id`
+- 其它两栏留空
+
+下次别人发 `/account` `/config` `/exit` `/reconnect` `/doctor` `/workers` `/shell` `/cd` `/ws` 这些敏感命令，会收到 `❌ 此命令仅管理员可用`。普通对话（让 bot 帮忙做事）不受影响。
+
+**完全收紧**
+
+三栏全填。`/config` 表单会拦下常见误配——比如管理员名单里没把你自己加进去、群白名单里没包含当前会话，提交时会被拒绝并提示原因，不会让你不小心把自己锁在外面。
+
+### 怎么找 `open_id` 和 `chat_id`
+
+最快的办法：让目标用户给 bot 发一条任意消息（群的话就 @bot 一下），然后在终端：
+
+```bash
+grep '"event":"enter"' ~/.lark-channel/logs/$(date +%Y-%m-%d).log | tail -5
+```
+
+每一行都带 `chatId`（= 群或私聊 ID）和 `senderId`（= 用户 `open_id`），照着复制就行。
+
+也可以查飞书开放平台的"获取用户信息"API，但要先给你的应用加 `contact:user` scope，没必要为了几个 ID 折腾。
+
+### 几点提醒
+
+- 改完 `/config` **下一条消息**就生效，不用重启
+- 把任何一栏设成**空字符串** = 不限制（不是"一个都不允许"）
+- 想从某种受限状态回到"完全开放"，把对应栏目清空再提交即可
+- 私聊不受"群白名单"约束——这是设计上故意的：万一你不小心把所有群都锁死了，**回到 bot 的私聊里发 `/config` 就能解锁**
+
+### 高级：直接改配置文件
+
+不太想登飞书也可以，`/config` 表单背后写的是 `~/.lark-channel/config.json` 的 `preferences.access`：
+
+```json
+{
+  "preferences": {
+    "access": {
+      "allowedUsers": ["ou_xxxxxxxxxxxxx"],
+      "allowedChats": ["oc_xxxxxxxxxxxxx"],
+      "admins":       ["ou_xxxxxxxxxxxxx"]
+    }
+  }
+}
+```
+
+手改完之后**重启 bridge** 或者**找一个被允许的会话发 `/reconnect`** 让新配置生效。日常调整还是用 `/config` 表单更省事，直接改文件主要用在"部署脚本里预填"之类的场景。
+
+## 常见问题
+
+**Claude 挂住不回复**：通常是 `claude` CLI 本身没登录，或者 session 指向了不存在的 cwd。发 `/status` 看当前状态；`/new` 重开会话往往就好。
+
+**Claude 子进程假死（卡片停在最后一帧不动）**：从 0.1.20 起支持 idle 探活：claude 一段时间没输出就被 SIGTERM kill，卡片末尾会标 "⏱ N 分钟无响应，已自动终止"。默认关闭。开启方式：`/config` 设全局值（分钟），或 `/timeout 10` 只对当前 session 生效；`/timeout off` 关掉某个 session 的探活；`/timeout default` 清掉 session 覆盖回退到全局。
+
+**卡片显示 agent 失败，可以重试吗？** 失败和 idle-timeout 卡片会在 bridge 保存了原始 run 的情况下显示一键重试按钮。也可以在同一个 chat / 话题里运行 `/retry <run-id>`。重试只允许在原会话范围内触发，避免一个失败任务被别的 chat 误重放。
+
+**怎么排查卡片卡住或 Cursor SDK worker 异常？** 运行 `/doctor <现象描述>`，它会把最近结构化日志和 run timeline 喂给 agent 自诊断。timeline 覆盖 `intake -> queue -> session -> agent -> card update -> done`，能帮助判断问题停在 Lark 更新、session 准备还是 agent 本身。只看 Cursor SDK worker 状态可以运行 `/workers` 或 `/doctor workers`。
+
+**Cursor SDK 返回没有细节的 `status=error` 怎么办？** bridge 会把这类不透明 Cursor SDK run 失败视为当前 SDK worker 的 fatal 错误：展示最终原因、丢弃该 worker，并在后续运行中使用新 worker/session。限流、网络和 stale-session 等可恢复路径会记录自动恢复步骤和最终失败原因。
+
+**图片发过去 Claude 说看不到**：升级到最新版，0.1.0 之前的版本有文件名去重 bug。
+
+## 许可
+
+[MIT](./LICENSE)

package/bin/lark-agent-bridge.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';