# 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 执行权限过大

规避方式：

- 把危险命令纳入审批
- 工具分级授权
- 关键操作记录审计日志