> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Botmux 能力地图：Lark 里的 AI CLI Runtime

**一句话结论：**Botmux 的强点不是“把 AI 接到群聊”，而是把 Lark
私聊、群聊、话题、引用、附件和按钮交互映射成一个个可恢复、可观察、可切换的
AI CLI session。它保留 Claude Code、Codex、Cursor、Gemini、OpenCode 等
CLI 的原生能力，同时把执行过程实时流式回传到 Lark。

所以 Botmux 更像一个 Lark-native AI CLI runtime，而不是 LLM SDK
wrapper。它解决的是“AI agent
在哪里活着、怎么被人叫、怎么持续执行、怎么回报进度、怎么多 bot 协作”。

# 0. 我读了什么

| 来源          | 内容                                                                                                                                                            | 用于判断什么                                       |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| GitHub repo | `deepcoldy/botmux`，本地克隆 SHA `ef4514ec55b271681837b2b1adc17d1c20842fe6`                                                                                        | 真实功能、架构、命令、边界                                |
| README      | “飞书 + AI 编程 CLI”，每个会话一个独立 CLI 进程，流式回传，Web terminal，多 bot，multi-topic，scheduler。                                                                               | 产品定位和用户可见能力                                  |
| 源码          | `src/worker.ts`, `src/daemon.ts`, `src/core/session-manager.ts`, `src/core/worker-pool.ts`, `src/adapters/cli/registry.ts`, `src/workflows/*`, `src/skills/*` | runtime、session、CLI adapter、workflow、人类 gate |
| 本地补丁文档      | 你之前的 Botmux patch 说明和本地 `local-patches` drift 信息。                                                                                                             | fork/patch 治理风险                              |

***

# 1. 正确心智模型

```mermaid
flowchart LR
  Lark[Lark Message or Thread] --> Daemon[Botmux Daemon]
  Daemon --> Session[Session Manager]
  Session --> Worker[Worker Process]
  Worker --> Backend[PTY or tmux or zellij]
  Backend --> CLI[Claude Code, Codex, Cursor, Gemini]
  CLI --> Stream[Stream Card]
  Stream --> Lark
  Worker --> Terminal[Web Terminal]
  Human[Human Reviewer] --> Terminal
  Human --> Lark
```

## 它是什么

- Lark event daemon：接收私聊、群聊、话题、引用、按钮交互。
- session router：把不同 chat/thread/root message 映射到不同工作
  session。
- CLI process manager：为每个会话启动一个独立 CLI 进程。
- terminal bridge：提供 read-only 或 write-enabled 的 web terminal。
- multi-agent coordinator：支持多个
  bot、多个话题、dispatch/report/handoff。

## 它不是什么

- 不是 Lark API 全能力操作层；那是 `lark-cli` 的位置。
- 不是业务任务数据库；它能保存 session，但不是任务 source of truth。
- 不是企业权限系统；它有 allowedUsers/oncall/grants，但产品化还要
  tenant/policy/audit。
- 不是只面向 coding 的产品；它当前最自然用于 coding CLI，但 runtime
  形态可以承载 research/PM/BD。

**核心差异：**很多 bot 是“消息进来 - 调 LLM API - 回一段文字”。Botmux
是“消息进来 - 找到/启动一个真实 CLI session - CLI 在 shell/tmux 里工作 -
过程通过 Lark card 和 terminal 暴露给人”。这保留了 CLI 的
memory、hooks、skills、resume、sandbox、slash commands 和工具生态。

***

# 2. 架构拆解

| 模块                   | 源码观察                                                                                                                                         | 能力含义                                                 |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Daemon               | `src/daemon.ts` 负责连接 Lark event、worker pool、scheduler、dashboard IPC、workflow、permission evaluator。                                           | Botmux 的主进程，像 agent runtime 的 control loop。          |
| Session Manager      | `src/core/session-manager.ts` 构造 prompt，把 sender、attachments、session id、routing hints、identity、mentions、available bots 注入给 CLI。              | 把 Lark 上下文变成 CLI 能理解的任务上下文。                          |
| Worker               | `src/worker.ts` fork 后 spawn CLI，通过 `CliAdapter + PtyBackend` 管理 PTY/tmux/zellij/herdr，支持 HTTP/WebSocket terminal。                           | 每个会话一个真实工作进程，可恢复、可杀、可重启。                             |
| CLI Adapter Registry | `src/adapters/cli/registry.ts` 注册多种 CLI adapter，包括 `claude-code`、`codex`、`codex-app`、`cursor`、`gemini`、`opencode`、`antigravity`、`copilot` 等。 | Botmux 不绑定单一模型或单一 coding CLI；它桥接整个 CLI ecosystem。    |
| Worker Pool          | `src/core/worker-pool.ts` 管 active sessions、stream cards、terminal links、parking/recalling cards、serialized latest-wins card PATCH。           | 多会话并发和 Lark 展示稳定性。                                   |
| Event Dispatcher     | `src/im/lark/event-dispatcher.ts` 区分 `canTalk` 和 `canOperate`，allowedUsers、allowedChatGroups、grants、known peer bots 不同语义。                    | 不是所有能和 bot 说话的人都能触发状态改变。                             |
| Scheduler            | `src/core/scheduler.ts` 用 Croner，支持自然语言、interval、cron、ISO 时间，能回到原 thread 继续。                                                                 | 让 agent 从“被动回答”变成“定时工作”。                             |
| Workflow Runtime     | `src/workflows/*` 有 event-log runtime、subagent、hostExecutor、loop、decision、humanGate、retry/reconcile。                                         | 已经有从单 bot 到多步骤 agent workflow 的雏形。                   |
| Built-in Skills      | `src/skills/definitions.ts` 定义 schedule/history/quoted/send/bots/handoff/workflow-create/worker-budget/orchestrate/ask。                      | 让 Claude Code 等 CLI 在 session 内知道如何和 Botmux/Lark 互动。 |

***

# 3. 用户可见功能清单

| 功能                      | 能做什么                                                                       | 为什么重要                                         |
| ----------------------- | -------------------------------------------------------------------------- | --------------------------------------------- |
| 私聊/群聊/话题 session        | 不同会话独立 CLI process；thread/root message 可以作为 session key。                   | 避免多人、多任务上下文互相污染。                              |
| 实时流式 Lark card          | CLI 输出实时更新到 Lark card，支持过程中查看进度。                                           | 人不用等最终答案，可以 review agent 做到哪里。                |
| Web terminal            | 生成 read-only 或 write-enabled terminal link，可查看或接管。                         | 关键时刻人类可以介入真实 shell。                           |
| tmux/zellij/PTy backend | 默认可使用 tmux；支持 session reattach/resume。                                     | 长任务不因 Lark 消息生命周期结束而消失。                       |
| 多 CLI runtime           | 支持 Claude Code、Codex、Cursor、Gemini、OpenCode、Antigravity、Copilot 等 adapter。 | 把供应商选择变成配置，而不是产品锁死。                           |
| 多 bot 协作                | 不同 bot 可有不同品牌、模型、sandbox、workingDir、allowedUsers、reply modes。              | 可以做“前端 bot/后端 bot/reviewer bot/research bot”。 |
| Multi-topic dispatch    | `botmux dispatch` 可拆分子项目、开话题、分配 bot；`botmux report` 汇报。                    | 让 orchestrator 把大任务拆成并行 worker。               |
| Schedule                | `/schedule` 或 `botmux-schedule` 创建定时任务。                                    | 研究、巡检、日报、周报可以自动运行。                            |
| 引用和历史                   | `botmux-quoted`、`botmux-history` 读取引用消息和历史上下文。                             | 让 agent 不只看最后一条消息。                            |
| Ask / human choice      | `botmux ask` 可发交互卡片让人选择。                                                   | 重要分支可以让人类批准，而不是 agent 自己猜。                    |
| Send / reply            | `botmux-send` 让 CLI 主动发 Lark 消息；workflow subagent 中有安全限制。                  | agent 可以主动沟通，但必须避免绕过审计。                       |
| Workflow                | 支持 `subagent`、`hostExecutor`、`loop`、`decision`、`humanGate`。                | 是未来“AI employee workflow engine”的核心种子。        |
| Dashboard               | 提供 session/dashboard 视图，默认 public read-only，写操作需要 token。                   | 管理者能看 agent 在跑什么。                             |

***

# 4. CLI 命令能力

Botmux 自带 CLI 命令不是给 end user
聊天用，而是给部署者、operator、agent runtime 和 workflow 使用。

| 命令组                                                      | 说明                                               | 产品意义                                |
| -------------------------------------------------------- | ------------------------------------------------ | ----------------------------------- |
| `setup/start/stop/restart/status/logs/upgrade/autostart` | 安装、启动、停止、升级、查看状态和日志。                             | 部署运维。                               |
| `dashboard/list/delete/resume/term-link/session-ready`   | 管理 session，恢复 session，生成 terminal link，标记 ready。 | 可观察、可恢复、可接管。                        |
| `ask/send/history/quoted/bots`                           | session 内对话、发消息、查历史、查引用、列 bot。                   | agent 和 Lark 的交互 API。               |
| `dispatch/report/handoff`                                | 拆任务给其他 bot，汇报结果，转交会话。                            | 多 agent 编排。                         |
| `schedule`                                               | 定时/周期任务。                                         | 从 reactive bot 变成 proactive worker。 |
| `workflow`                                               | 创建/运行 workflow。                                  | 从单次调用升级到可审计流程。                      |
| `worker-budget`                                          | 限制 worker 预算。                                    | 成本和失控风险控制。                          |
| `create-group/voice/lang/preset`                         | 群组、语音、语言、preset 相关。                              | 产品体验和配置入口。                          |

***

# 5. Built-in skills：Botmux 给 CLI agent 的“身体语言”

| Skill                    | 能力            | 典型用途                                     |
| ------------------------ | ------------- | ---------------------------------------- |
| `botmux-schedule`        | 创建定时或周期任务。    | 明早继续研究、每周生成报告、定时巡检。                      |
| `botmux-history`         | 读取会话历史。       | 恢复上下文、避免重复问。                             |
| `botmux-quoted`          | 读取被引用消息。      | 准确理解“这个/上面那段/引用里的需求”。                    |
| `botmux-send`            | 主动向 Lark 发消息。 | 报告进度、通知人、发送结果。                           |
| `botmux-bots`            | 列出可用 bot。     | 找合适专家 bot 协作。                            |
| `botmux-handoff`         | 会话转交。         | 把前端问题转给 frontend bot，把研究转给 research bot。 |
| `botmux-workflow-create` | 创建 workflow。  | 把临时流程沉淀成可复用流程。                           |
| `botmux-worker-budget`   | 限制 worker 预算。 | 防止长任务烧 token/时间。                         |
| `botmux-orchestrate`     | 编排多个 bot/任务。  | 大任务拆解并行执行。                               |
| `botmux-ask`             | 向人类发选择卡片。     | 审批、分支选择、确认外部发送。                          |

源码里 installer 会把这些 skills 写到每个 session 的 plugin
目录，而不是污染全局 `~/.claude/skills`。这点重要：不同 Botmux session
可以带不同能力和安全边界。

***

# 6. Workflow 与 humanGate

**关键点：**Botmux 不是只有“开一个 CLI”。它已经有 workflow runtime
的雏形：`subagent` 执行、`hostExecutor` 调宿主动作、`loop`
循环、`decision` 分支、`humanGate` 人类确认。

| 节点/机制             | 意思                                                                               | 为什么对 AI employee 重要              |
| ----------------- | -------------------------------------------------------------------------------- | -------------------------------- |
| `subagent`        | 启动一个 bot worker 执行 prompt。                                                       | 可把大任务拆给不同专业 agent。               |
| `hostExecutor`    | 调用宿主注册的执行器。                                                                      | 把 Lark、GitHub、邮件、部署等外部动作纳入流程。    |
| `loop`            | 循环执行直到条件满足。                                                                      | 适合持续研究、重试、巡检。                    |
| `decision`        | 根据结果分支。                                                                          | 适合 triage、风险分流、是否开 PR。           |
| `humanGate`       | 在关键动作前等待人类审批。                                                                    | 产品化必须有，不然就是远程 shell + 外发消息风险。    |
| side-effect guard | `feishu-send`、`feishu-reply`、`botmux-schedule` 等副作用 executor 需要 gate 或显式 unsafe。 | 说明作者已经意识到 agent side effect 的风险。 |

***

# 7. Botmux 的强点

## 工程强点

- **CLI fidelity：**不重写 Claude/Codex/Cursor
  能力，直接复用它们的原生能力。
- **Session isolation：**一个 Lark 会话对应一个 CLI
  process，天然隔离上下文。
- **Terminal observability：**人能看真实 terminal，不只看最终总结。
- **Runtime persistence：**tmux/resume 让长任务可恢复。
- **Adapter extensibility：**支持多 CLI，未来可以接更多 worker。

## 产品强点

- **Lark-native：**用户无需换工具，在群、话题、文档讨论里直接叫 agent。
- **Human-in-the-loop：**card、terminal、ask、humanGate 都适合人类监督。
- **Multi-agent：**dispatch/report/handoff 适合从单 bot 走向 agent
  team。
- **Proactive：**schedule 让 agent 可以定时工作。
- **Low integration friction：**现有 CLI 升级，Botmux 可直接受益。

***

# 8. 边界和风险

| 边界/风险            | 具体表现                                                                                                    | 建议                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Lark-specific    | 当前产品形态深度绑定 Lark event、Lark card、Lark topic。                                                             | 短期把 Lark 做深；长期抽象 `ChatPlatformAdapter`，再接 Slack/Teams。                       |
| 不是业务 SoT         | session 状态不是完整任务生命周期；不能替代 Beads/Base/CRM。                                                               | Botmux 管 runtime，Beads/devbot DB 管 task state，Lark Doc/Base 管 projection。    |
| 远程 shell 风险      | write terminal、CLI session、workingDir、env secret 都可能带来破坏性影响。                                            | 默认 read-only、sandbox、hide paths、allowedUsers、audit log、production gate。      |
| 权限模型仍需产品化        | `canTalk` 和 `canOperate` 已有区分，但多客户 tenant、角色、审计、审批还不完整。                                                 | 建立 org/project/user/bot/workspace 四层 permission model。                       |
| 副作用动作要 gate      | 主动发消息、创建 schedule、workflow side effects 如果不控会造成越权。                                                      | 沿用 humanGate，把 mail/send/deploy/merge/payment 都纳入高风险。                        |
| 运行环境复杂           | Node 版本、tmux、web terminal、Cloudflare tunnel/access、PM2、Lark app scopes 都要配置。                            | 做 installer、doctor、deployment checklist、smoke tests。                         |
| fork/patch drift | 你本地 fork 和 `botmux-local-patches` 有重复 patch；Lark 文档说 6 个 patch / 2.33.0，本地 README 说 7 个 patch / 2.43.0。 | 先定义 patch source of truth：要么 upstream PR，要么独立 patch repo，要么 fork 内目录，不要三者漂移。 |

**最危险的误解：**“Botmux 已经能跑 CLI，所以它就是 AI employee
产品。”还差 task source of truth、tenant isolation、policy
engine、audit、measurement、customer onboarding、connectors 和
billing。Botmux 是强 runtime，不是完整企业产品。

***

# 9. 我会怎么用它

1. **短期：**把 Botmux 当作 AI CLI runtime。所有 coding/research worker
   都通过 Botmux 跑，Lark 只是人类入口和展示层。
2. **中期：**把 Botmux workflow/humanGate 和 Lark CLI
   结合，形成可审批的 agent workflow。
3. **长期：**把 Botmux 的 Lark-specific 部分抽象出来，支持
   Slack/Teams/Linear/GitHub Issue 等入口，但 runtime 核心仍保留
   CLI-first。

***

# 10. 来源链接

- [deepcoldy/botmux GitHub Repository](https://github.com/deepcoldy/botmux)