Wiki AI

源码架构总览

5分钟阅读

botmux 是一个薄编排层：把飞书事件翻译成 CLI 进程的输入/输出，不重造 Agent 能力。官方定位（README.md）：一条飞书消息启动一个会话，每个会话一个独立 CLI 进程，输出实时流式回传为飞书卡片。

进程模型：三层

飞书长连接事件 (WSClient)
      │
      ▼
 daemon（一个 bot 一个进程，pm2 托管，常驻）
      │  每个会话 fork 一个
      ▼
 worker（一会话一进程）── HTTP+WS 提供 Web 终端
      │  适配器 + 后端（PTY/tmux/zellij/...）拉起
      ▼
 CLI 进程（Claude Code / Codex / ... 完整运行时）
  • 一个 bot 一个 daemon：多机器人 = 多 daemon，进程完全隔离（ecosystem.config.cjs + src/cli.ts 的 pm2 编排；startDaemon(botIndex) 按 BOTMUX_BOT_INDEX 认领 bots.json 中的一个 bot，见 src/daemon.ts:19954）。
  • 一个会话一个 worker：daemon 通过 child_process.fork() 拉起 worker.js（src/core/worker-pool.ts:6257），worker 管一个 CLI PTY 会话 + Web 终端；tmux 后端下 CLI 可脱离 worker 常驻（见 tmux）。

入口文件

文件角色
src/cli.tsbotmux bin（package.json bin）。setup/start/stop/restart/logs/status/list/delete/autostart/device/whiteboard 等命令；start 经 pm2 拉起 fleet（每 bot 一个 daemon + dashboard）
src/index-daemon.tsdaemon 进程入口（package.json main）。加载 ~/.botmux/.env、scrub 会话级环境变量（daemon 永远不是会话）、读全局 locale，然后 startDaemon(botIndex)
src/index-core-only.tscore-only（apiOnly）入口：单进程、无飞书凭证、无 bots.json，只在 127.0.0.1 提供 HTTP 控制 API（BOTMUX_API_PORT），供沙盒内任务运行器经 POST /api/trigger 驱动（见 api-core-only）
src/worker.ts会话 worker 进程：管理单个 CLI PTY 会话 + xterm.js Web 终端（详见 daemon-worker）
src/worker-ipc-preload.tsworker fork 后、正式 IPC 处理器注册前暂存 daemon 消息并为首轮输入回 ACK，ready 后按序重放

src/ 子目录职责地图

目录职责（一句话）
core/daemon 侧核心域：worker-pool（fork/IPC/卡片刷新）、command-handler（斜杠命令）、scheduler（croner 定时）、session-store 相关、ask 协议、plugins（MCP gateway）等 160+ 个文件（递归统计，含子目录）
im/lark/飞书侧：event-dispatcher（WSClient + 路由准入）、client（API 封装）、card-builder/card-handler（卡片）、message-parser 等
adapters/cli/CLI 适配器，每种 CLI 一个文件（claude-code/codex/cursor/gemini/opencode/kimi/grok/riff 等 20+），registry.ts 工厂分发（见 adapters）
adapters/backend/会话后端：pty/tmux/tmux-pipe/zellij/herdr/riff 等，worker 与 CLI 经后端解耦
services/持久化/策略服务 160+（递归统计，含子目录）：session-store、message-queue、schedule-store、usage-ledger、hook-runner、各 CLI transcript 解析、vc-meeting 系列等
workflows/Workflow DAG 编排引擎：v3/（DAG、distillation、goal-mode）、events/（事件溯源）、hostExecutors/（feishu-send 等宿主执行器）（见 workflow-engine）
dashboard/Dashboard 管控面服务端：聚合器、认证、联邦、飞书登录、Web 终端代理（见 dashboard）
setup/botmux setup：飞书应用创建、权限自动化（open-platform-automation）、CLI 选择、tmux/字体依赖保障
skills/随包内置的 CLI 侧 Skill 定义（botmux-send/schedule/history/bots/quoted 等）与注入器（见 skills）
platform/设备凭证/绑定/隧道（device-enroll、device-isolation、tunnel-client）
vc-agent/飞书会议智能体：会议状态机、轮询/推送事件源、实时语音（见 vc-agent）
cli/CLI 子命令辅助模块：pm2 事务、会话 picker（TUI）、send-dispatch、saved-workflow 等
desktop/Electron 桌面端（main/preload/renderer，独立打包管线）
utils/通用设施：logger、idle-detector、terminal-renderer（xterm 截屏）、file-lock、atomic-write 等
features/场景特性，目前含 codex-notifier（Codex 桌面通知接管）

顶层还有：daemon.ts（编排组装，2.1 万行）、bot-registry.ts（多 bot 配置与状态）、config.ts/global-config.ts、codex-app-runner.ts/mira-runner.ts/mir-local-runtime.ts（特定 CLI 的子 runner）、dashboard.ts（dashboard HTTP 静态/代理服务）。

数据流

  1. 飞书推送 im.message.receive_v1 → im/lark/event-dispatcher.ts 解析归属（@mention / 话题 / 群权限）
  2. core/command-handler.ts 拦截 /xxx 斜杠命令；非命令消息进入会话路由（handleNewTopic / handleThreadReply）
  3. 新话题 → worker-pool fork 一个 worker；已有会话 → 复用，消息经 IPC 写进 CLI stdin
  4. worker 持续读 PTY 输出 → terminal-renderer 转 Markdown → 流式卡片回传（见 card-streaming）
  5. CLI 通过注入的 Skill（botmux send 等）主动向话题发消息

技术栈

  • 语言/运行时：TypeScript（ESM），Node >= 22，pnpm；vitest 单测/e2e
  • 飞书：@larksuiteoapi/node-sdk（WSClient 长连接 + REST），proxy-agent 代理支持
  • 进程/终端：node-pty（PTY）、pm2（daemon 托管）、tmux/zellij（外部后端，setup 自动安装）
  • Web 终端：ws + @xterm/headless（服务端渲染/截屏）
  • 定时：croner（cron 解析）
  • Dashboard：React 19 前端（scripts/build-dashboard.mjs 打包进 dist）
  • 其他：zod（校验）、markdown-it、@napi-rs/canvas（截图）、@modelcontextprotocol/sdk（MCP gateway）、qrcode-terminal（setup 扫码）

更多背景：overview、architecture。

关系图谱

反向链接