feat: bootstrap boss control plane prototype
This commit is contained in:
Codex
342
docs/system-architecture.md
Normal file
342
docs/system-architecture.md
Normal file
@@ -0,0 +1,342 @@
|
||||
# Boss 系统架构
|
||||
|
||||
更新日期：2026-03-23
|
||||
|
||||
## 架构目标
|
||||
|
||||
Boss 要解决的问题不是“如何让一个 agent 写代码”，而是“如何让一个主控端持续调度多个运行在不同设备上的编码 agent，并保持对话、状态和审计一致”。
|
||||
|
||||
核心目标：
|
||||
|
||||
- 用户始终只和一个主账号对话
|
||||
- 主账号能把任务拆给多个 worker
|
||||
- 每个 worker 可以运行在真实 Windows 或 Mac 设备上
|
||||
- 用户可以随时改变需求
|
||||
- 系统支持中断、续跑、审批、回滚、审计
|
||||
|
||||
## 总体架构图
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
User["用户"] --> Chat["聊天入口<br/>Slack / Telegram / 飞书 / 企业微信"]
|
||||
User --> App["独立控制台<br/>Web / Desktop"]
|
||||
|
||||
Chat --> Gateway["API Gateway"]
|
||||
App --> Gateway
|
||||
|
||||
Gateway --> Session["Session Service"]
|
||||
Gateway --> Task["Task Service"]
|
||||
Gateway --> Notify["Notification Service"]
|
||||
|
||||
Session --> Planner["Manager Agent<br/>Codex"]
|
||||
Task --> Planner
|
||||
Planner --> Queue["Queue / Workflow Engine"]
|
||||
Queue --> Scheduler["Scheduler"]
|
||||
|
||||
Scheduler --> Worker1["Windows Worker A"]
|
||||
Scheduler --> Worker2["Windows Worker B"]
|
||||
Scheduler --> Worker3["Mac Worker"]
|
||||
|
||||
Worker1 --> Runtime1["Agent Runtime<br/>Codex CLI / Claude Code / MCP Tools"]
|
||||
Worker2 --> Runtime2["Agent Runtime<br/>Codex CLI / Claude Code / MCP Tools"]
|
||||
Worker3 --> Runtime3["Agent Runtime<br/>Codex CLI / Claude Code / MCP Tools"]
|
||||
|
||||
Session --> Store["Postgres"]
|
||||
Task --> Store
|
||||
Queue --> Store
|
||||
Worker1 --> EventBus["Event Bus"]
|
||||
Worker2 --> EventBus
|
||||
Worker3 --> EventBus
|
||||
EventBus --> Notify
|
||||
EventBus --> Store
|
||||
|
||||
Planner --> Memory["Project Memory / Vector Store"]
|
||||
Worker1 --> Git["Git Provider"]
|
||||
Worker2 --> Browser["Browser / Playwright"]
|
||||
Worker3 --> IDE["Local IDE / Terminal / Filesystem"]
|
||||
```
|
||||
|
||||
## 分层设计
|
||||
|
||||
### 1. 入口层
|
||||
|
||||
职责：
|
||||
|
||||
- 接收用户自然语言
|
||||
- 展示项目进度、任务树、审批请求
|
||||
- 承载多端对话入口
|
||||
|
||||
组成：
|
||||
|
||||
- Web 控制台
|
||||
- Desktop 控制台
|
||||
- Slack / Telegram / 飞书 / 企业微信 Bot
|
||||
|
||||
设计原则：
|
||||
|
||||
- 独立 App 是主控制面
|
||||
- 聊天工具只做轻入口和通知审批
|
||||
- 所有入口共享同一个会话和任务状态
|
||||
|
||||
### 2. 会话与任务层
|
||||
|
||||
职责：
|
||||
|
||||
- 维护项目级会话
|
||||
- 存储用户意图、任务树、依赖关系
|
||||
- 接收需求变更并触发重规划
|
||||
|
||||
核心对象：
|
||||
|
||||
- `project_session`
|
||||
- `task`
|
||||
- `subtask`
|
||||
- `message`
|
||||
- `approval_request`
|
||||
- `worker_assignment`
|
||||
|
||||
设计原则：
|
||||
|
||||
- 任何需求变更都不是覆盖旧状态，而是追加一条事件
|
||||
- 主控 agent 根据最新状态决定继续、暂停、取消还是重规划
|
||||
|
||||
### 3. Manager Agent 层
|
||||
|
||||
职责：
|
||||
|
||||
- 读取当前上下文
|
||||
- 把用户自然语言翻译成任务树
|
||||
- 给不同 worker 分派工作
|
||||
- 汇总各 worker 回传结果
|
||||
- 把技术执行过程重新组织成面向用户的进度播报
|
||||
|
||||
建议实现：
|
||||
|
||||
- 首选 Codex 作为 manager brain
|
||||
- manager 不直接执行重活，主要负责规划、协调和总结
|
||||
|
||||
为什么 manager 要单独存在：
|
||||
|
||||
- 用户说的是需求语言，不是底层执行语言
|
||||
- 设备 worker 报的是技术状态，不是业务状态
|
||||
- manager 负责在这两者之间做翻译
|
||||
|
||||
### 4. 调度与工作流层
|
||||
|
||||
职责：
|
||||
|
||||
- 排队
|
||||
- 优先级控制
|
||||
- 并发控制
|
||||
- 超时重试
|
||||
- 中断恢复
|
||||
- 审批等待
|
||||
|
||||
设计原则：
|
||||
|
||||
- 长任务必须通过工作流引擎或持久队列驱动
|
||||
- 不能靠单个进程中的内存状态维持任务
|
||||
|
||||
推荐能力：
|
||||
|
||||
- 任务可挂起
|
||||
- 任务可人工恢复
|
||||
- 子任务状态独立
|
||||
- 支持依赖关系图
|
||||
|
||||
### 5. Worker 层
|
||||
|
||||
职责：
|
||||
|
||||
- 在真实设备上执行具体开发动作
|
||||
- 拉代码、建 worktree、改文件、跑测试、创建 PR
|
||||
- 上报结构化事件和心跳
|
||||
|
||||
部署方式：
|
||||
|
||||
- 每台设备安装一个 `boss-worker`
|
||||
- worker 持久连接到 control plane
|
||||
- worker 内部再调用 Codex CLI、Claude Code、Playwright、MCP 工具等
|
||||
|
||||
为什么 worker 必须是 daemon：
|
||||
|
||||
- 需要持续在线状态
|
||||
- 需要接收取消和暂停命令
|
||||
- 需要中途回传事件
|
||||
- 需要在主控端丢线后继续执行
|
||||
|
||||
### 6. 工具层
|
||||
|
||||
职责：
|
||||
|
||||
- 提供标准化工具访问
|
||||
- 屏蔽不同设备的具体环境差异
|
||||
|
||||
建议接入：
|
||||
|
||||
- Git
|
||||
- Filesystem
|
||||
- Terminal
|
||||
- Browser automation
|
||||
- Issue tracker
|
||||
- Chat connector
|
||||
- CI / Test runner
|
||||
|
||||
建议协议：
|
||||
|
||||
- 工具接入优先使用 MCP
|
||||
- agent-to-agent 通信前瞻引入 A2A
|
||||
|
||||
### 7. 存储与审计层
|
||||
|
||||
职责：
|
||||
|
||||
- 保存消息、任务、事件、状态快照
|
||||
- 为用户提供会话恢复与审计追踪
|
||||
|
||||
必须保存的内容：
|
||||
|
||||
- 用户消息
|
||||
- manager 规划结果
|
||||
- worker 事件流
|
||||
- 审批记录
|
||||
- 高风险工具调用
|
||||
- Git 变更摘要
|
||||
|
||||
## 关键交互路径
|
||||
|
||||
### 路径 1：用户发起新任务
|
||||
|
||||
1. 用户在 Web 或聊天入口发起需求
|
||||
2. Session Service 追加消息
|
||||
3. Manager 生成任务树
|
||||
4. Task Service 创建主任务和子任务
|
||||
5. Scheduler 根据设备能力分配 worker
|
||||
6. worker 执行并回传事件
|
||||
7. manager 定期汇总进度给用户
|
||||
|
||||
### 路径 2：用户中途改需求
|
||||
|
||||
1. 用户说“先暂停 A，改成先修登录问题”
|
||||
2. 新消息进入当前 project session
|
||||
3. manager 读取活动中的任务树
|
||||
4. manager 标记哪些子任务失效，哪些继续保留
|
||||
5. Task Service 下发 `pause / cancel / replan`
|
||||
6. worker 接收并安全停止当前步骤
|
||||
7. manager 输出新的计划和最新进度
|
||||
|
||||
### 路径 3：高风险审批
|
||||
|
||||
1. worker 申请执行高风险操作
|
||||
2. control plane 生成审批请求
|
||||
3. 用户在 App 或聊天入口确认
|
||||
4. 工作流恢复执行或终止
|
||||
|
||||
## 协同开发模式
|
||||
|
||||
### 模式 A：独立开发
|
||||
|
||||
- 一个子任务绑定一个 worker
|
||||
- worker 自己完成从理解、编码到测试的闭环
|
||||
- manager 只做验收和汇总
|
||||
|
||||
适合：
|
||||
|
||||
- 低耦合功能开发
|
||||
- 单一 bug 修复
|
||||
|
||||
### 模式 B：协同开发
|
||||
|
||||
- manager 先做任务拆解
|
||||
- 不同 worker 分别负责不同模块或阶段
|
||||
- 通过 shared context 和中间产物衔接
|
||||
|
||||
适合：
|
||||
|
||||
- 横跨前后端的需求
|
||||
- 需要并行研究和实现
|
||||
|
||||
### 模式 C：研究先行
|
||||
|
||||
- 多个 worker 先做调研、复现、定位
|
||||
- manager 再决定由哪台设备进入实现
|
||||
|
||||
适合：
|
||||
|
||||
- 不确定问题根因
|
||||
- 风险较高的问题
|
||||
|
||||
## 设备调度策略
|
||||
|
||||
推荐调度维度：
|
||||
|
||||
- OS 能力
|
||||
- 当前负载
|
||||
- 工具能力
|
||||
- 项目亲和性
|
||||
- 上下文热度
|
||||
- 风险等级
|
||||
|
||||
示例：
|
||||
|
||||
- 需要 Xcode 的任务优先给 Mac
|
||||
- 需要 Windows 原生应用自动化的任务优先给 Windows
|
||||
- 同一 repo 的后续任务优先分给最近处理过该 repo 的 worker
|
||||
|
||||
## 为什么不建议一开始就做的东西
|
||||
|
||||
- 不建议一开始做跨团队多租户 SaaS
|
||||
- 不建议一开始做复杂计费系统
|
||||
- 不建议一开始就做完整 A2A 联邦网络
|
||||
- 不建议一开始支持太多聊天平台
|
||||
|
||||
第一阶段只要把下面几件事跑通：
|
||||
|
||||
- 主账号持续对话
|
||||
- 三台机器在线
|
||||
- 子任务拆分
|
||||
- 实时进度回传
|
||||
- 可暂停、可继续、可取消
|
||||
- 可审批高风险操作
|
||||
|
||||
## 当前推荐架构决策
|
||||
|
||||
- 主控面：Web 优先，后续补 Desktop
|
||||
- Manager：Codex
|
||||
- Worker runtime：Codex CLI + Claude Code 混合
|
||||
- 工具协议：MCP
|
||||
- 任务编排：持久队列或工作流引擎
|
||||
- 存储：Postgres
|
||||
- 事件流：Redis Streams 或消息队列
|
||||
|
||||
## 架构风险
|
||||
|
||||
### 风险 1：多个 worker 改同一仓库互相踩踏
|
||||
|
||||
规避方式：
|
||||
|
||||
- 每个任务独立 worktree
|
||||
- 每个任务独立分支
|
||||
- 合并前必须做 diff 汇总和冲突检查
|
||||
|
||||
### 风险 2：需求变化导致长任务上下文混乱
|
||||
|
||||
规避方式：
|
||||
|
||||
- 所有需求变化事件化
|
||||
- manager 在重规划前必须读取当前状态快照
|
||||
|
||||
### 风险 3：聊天入口承载太多复杂交互
|
||||
|
||||
规避方式：
|
||||
|
||||
- 长会话、文件树、终端流只放在独立 App
|
||||
- 聊天入口只承担轻操作
|
||||
|
||||
### 风险 4：worker 执行权限过大
|
||||
|
||||
规避方式：
|
||||
|
||||
- 把危险命令纳入审批
|
||||
- 工具分级授权
|
||||
- 关键操作记录审计日志
|
||||
Reference in New Issue
Block a user