企业官网建设流程全解析

bb Agent IDE 核心架构深度解析：Server、Host Daemon、App、CLI 四大组件如何协同工作

【免费下载链接】bbThe agent IDE that builds itself项目地址: https://gitcode.com/gh_mirrors/bb14/bb

bb是一个"自己构建自己"的 Agent IDE（AI 编程智能体集成开发环境）。它的核心由四大组件构成：Server（中心枢纽）、Host Daemon（主机守护进程）、App（Web 界面）和CLI（命令行工具）。本文用一张图带你读懂这套架构：每个组件负责什么、彼此如何通信、以及你该从哪个源码目录入手阅读。

🗺️ 一图看懂：四大组件的职责分工

先看 bb 运行起来后的真实界面——左侧是线程列表，中间是与 AI 智能体的对话，右侧是任务面板：

在这个界面背后，四大组件各司其职：

这套分工的精妙之处在于：App 和 CLI 只是"遥控器"，Server 是"大脑"，Host Daemon 是"手"。你的电脑、远程服务器、甚至手机，都可以是"手"，而大脑只有一个。

🖥️ Server：所有状态的唯一真相来源

Server 是整个系统的中枢（Hub），入口在 apps/server/src/start-server.ts。它做三件事：

1. 存状态：所有数据都落在 SQLite 数据库里（packages/db/），Server 本身无状态——数据库才是唯一真相来源；
2. 接请求：通过 HTTP API 响应 App 和 CLI（apps/server/src/routes/）；
3. 推通知：通过 WebSocket 向所有客户端实时推送变更（apps/server/src/ws/hub.ts）。

当某个操作需要"动手干活"（比如启动一个线程）时，Server 不会自己做，而是把工作路由给对应主机上的 Host Daemon——通过常驻的守护进程 WebSocket 通道下发 RPC 命令。

核心数据模型有四个概念（详见 docs/system-overview.md）：

• Project（项目）：顶层容器，通常对应一个代码仓库；
• Thread（线程）：工作单元，一次与智能体的对话，产生只追加的事件流；
• Environment（环境）：线程的执行上下文，把工作区目录绑定到某台主机；
• Host（主机）：一台长驻守护进程的执行机器。

⚙️ Host Daemon：每台机器上的"执行引擎"

Host Daemon 是 bb 真正"干活"的地方，入口在 apps/host-daemon/src/daemon.ts。每台被纳管（enroll）的机器上跑一个，职责包括：

• 连接 Server：建立并保持与中心 Server 的守护进程 WebSocket 通道；
• 处理 RPC 命令：预置环境、启动/停止线程等生命周期操作（apps/host-daemon/src/command-dispatch.ts）；
• 运行智能体进程：实际拉起 Codex、Claude Code 等 Agent Provider 进程（适配器在 packages/agent-runtime/）；
• 回传事件：把智能体的消息、工具调用、文件变更作为事件批次上报；
• 提供本地 API：给同机的 App 和 CLI 提供打开编辑器、选择文件夹等本地操作。

这意味着一个 Project 的代码可以分布在多台机器上——同一个项目在 Mac 上是本地目录，在 Linux 服务器上可以是另一个路径，Host 边界天然隔离了这一切。

🌐 App 与 CLI：两个"遥控器"

App（apps/app/）是浏览器里的 Web UI，负责查看项目、跟踪线程进度、指导任务执行。它是一个"瘦客户端"：所有数据来自 Server 的 HTTP API，实时性靠 WebSocket 推送。

CLI（apps/cli/）则是一等公民而非附属工具，入口在 apps/cli/src/index.ts。它和 App 能力对等，额外提供：

• 可脚本化：适合写进 CI 和自动化流程；
• 智能体友好：Agent 本身也能通过bb命令操作系统；
• 插件命令代理：未知命令会自动查询插件贡献的命令（apps/cli/src/plugin-cli-proxy.ts）。

典型工作流：

bb status bb project list bb thread spawn --project <id> --provider codex --prompt "..."

🔗 协同全流程：一次线程生命周期的完整旅程

把四大组件串起来，看看你发起一个任务时发生了什么：

1. 你通过 App 或 CLI 发起"启动线程"请求 → 请求到达Server；
2. Server校验参数，在 SQLite 中写入线程记录（状态：starting）；
3. Server通过守护进程 WebSocket 向目标Host Daemon下发 RPC 命令；
4. Host Daemon预置工作区（Environment），拉起智能体 Provider 进程；
5. 智能体开始干活，Host Daemon把消息、工具调用、文件变更等事件批次持续上报；
6. Server落库事件流，并通过 WebSocket 实时推送给App和CLI；
7. 你在界面中看到进度实时更新——闭环完成。

线程状态机（pending → starting → active → idle/error）由 packages/domain/ 定义，可视化见 docs/lifecycle-diagrams.md。

📐 架构护栏：契约包如何锁死组件边界

bb 用两个契约包（Contract Package）保证组件之间"各说各话"，防止架构腐化：

规则很简单：实现代码永远不跨边界 import。Server 不知道工作区如何预置，Daemon 不知道线程和项目的细节——它只执行命令里告诉它的事。这种"契约先行"的设计，是大型多进程系统保持可维护性的关键。

📚 延伸阅读与源码导航

想深入阅读，建议按这个顺序：

1. 概念总览：docs/system-overview.md —— 运行时组件、数据模型、契约边界一页讲清；
2. 仓库结构：docs/repository-overview.md —— 所有包和 App 的角色速查表；
3. 生命周期状态机：docs/lifecycle-diagrams.md —— 线程与环境的状态流转图；
4. Server 启动流程：apps/server/src/start-server.ts；
5. Daemon 进程管理：apps/host-daemon/src/daemon.ts；
6. CLI 命令注册：apps/cli/src/index.ts。

一句话总结：bb 的架构是典型的"中心状态 + 分布式执行"模式——Server 守住唯一真相，Host Daemon 分布式执行，App 和 CLI 双入口协同。理解了这四者关系，你就掌握了读懂整个代码库的地图。

【免费下载链接】bbThe agent IDE that builds itself项目地址: https://gitcode.com/gh_mirrors/bb14/bb