Retaintive

    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 repodeepcoldy/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. 正确心智模型

    它是什么

    • 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. 架构拆解

    模块源码观察能力含义
    Daemonsrc/daemon.ts 负责连接 Lark event、worker pool、scheduler、dashboard IPC、workflow、permission evaluator。Botmux 的主进程，像 agent runtime 的 control loop。
    Session Managersrc/core/session-manager.ts 构造 prompt，把 sender、attachments、session id、routing hints、identity、mentions、available bots 注入给 CLI。把 Lark 上下文变成 CLI 能理解的任务上下文。
    Workersrc/worker.ts fork 后 spawn CLI，通过 CliAdapter + PtyBackend 管理 PTY/tmux/zellij/herdr，支持 HTTP/WebSocket terminal。每个会话一个真实工作进程，可恢复、可杀、可重启。
    CLI Adapter Registrysrc/adapters/cli/registry.ts 注册多种 CLI adapter，包括 claude-code、codex、codex-app、cursor、gemini、opencode、antigravity、copilot 等。Botmux 不绑定单一模型或单一 coding CLI；它桥接整个 CLI ecosystem。
    Worker Poolsrc/core/worker-pool.ts 管 active sessions、stream cards、terminal links、parking/recalling cards、serialized latest-wins card PATCH。多会话并发和 Lark 展示稳定性。
    Event Dispatchersrc/im/lark/event-dispatcher.ts 区分 canTalk 和 canOperate，allowedUsers、allowedChatGroups、grants、known peer bots 不同语义。不是所有能和 bot 说话的人都能触发状态改变。
    Schedulersrc/core/scheduler.ts 用 Croner，支持自然语言、interval、cron、ISO 时间，能回到原 thread 继续。让 agent 从“被动回答”变成“定时工作”。
    Workflow Runtimesrc/workflows/* 有 event-log runtime、subagent、hostExecutor、loop、decision、humanGate、retry/reconcile。已经有从单 bot 到多步骤 agent workflow 的雏形。
    Built-in Skillssrc/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 cardCLI 输出实时更新到 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 dispatchbotmux dispatch 可拆分子项目、开话题、分配 bot；botmux report 汇报。让 orchestrator 把大任务拆成并行 worker。
    Schedule/schedule 或 botmux-schedule 创建定时任务。研究、巡检、日报、周报可以自动运行。
    引用和历史botmux-quoted、botmux-history 读取引用消息和历史上下文。让 agent 不只看最后一条消息。
    Ask / human choicebotmux ask 可发交互卡片让人选择。重要分支可以让人类批准，而不是 agent 自己猜。
    Send / replybotmux-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/botssession 内对话、发消息、查历史、查引用、列 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 guardfeishu-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。
    不是业务 SoTsession 状态不是完整任务生命周期；不能替代 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. 来源链接