feat: bootstrap boss control plane prototype

2026-03-23 12:43:39 +08:00
commit 0ab83990b2
24 changed files with 5534 additions and 0 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,42 @@
+# Boss 项目设计文档
+
+更新日期：2026-03-23
+
+## 文档导航
+
+- [竞品对比](./competitor-comparison.md)
+- [系统架构](./system-architecture.md)
+- [MVP 功能清单](./mvp-feature-plan.md)
+- [技术选型](./technical-selection.md)
+- [消息协议与状态机](./message-protocol-and-state-machine.md)
+- [实施路线图](./implementation-roadmap.md)
+
+## 项目一句话定义
+
+`Boss` 是一个面向多设备开发协作的 agent control plane。
+
+它让用户通过对话入口或独立 App，持续管理多台 Windows、Mac 上的编码代理，支持：
+
+- 协同开发
+- 独立开发
+- 子任务拆分
+- 实时进度播报
+- 中途变更需求
+- 审批高风险操作
+- 审计和会话恢复
+
+## 当前建议的产品定位
+
+- 不是单一编码助手
+- 不是单机 IDE 插件
+- 不是单纯云端沙箱代理
+- 而是“主控端 + 多设备 worker + 对话式任务系统”
+
+## 建议阅读顺序
+
+1. [竞品对比](./competitor-comparison.md)
+2. [系统架构](./system-architecture.md)
+3. [MVP 功能清单](./mvp-feature-plan.md)
+4. [技术选型](./technical-selection.md)
+5. [消息协议与状态机](./message-protocol-and-state-machine.md)
+6. [实施路线图](./implementation-roadmap.md)
--- a/docs/competitor-comparison.md
+++ b/docs/competitor-comparison.md
@@ -0,0 +1,216 @@
+# 多设备编码代理主控平台竞品对比
+
+更新日期：2026-03-23
+
+## 目标定义
+
+本对比只关注和下面目标相关的产品或框架：
+
+- 主控端统一管理多个编码代理
+- 支持多入口触发，如聊天工具、Web、IDE、CLI
+- 能把任务拆成子任务并持续回传进度
+- 最好能兼容或借鉴本地设备 worker，而不只是云沙箱
+
+不纳入重点范围的产品：
+
+- 只做本地单机结对编程
+- 只做代码补全
+- 只做通用办公 agent，不强调编码任务编排
+
+## 一页结论
+
+- 最接近企业级成品中控：Devin、Factory
+- 最适合搬运和二次开发：OpenHands
+- 最适合作为主账号大脑：OpenAI Codex
+- 最适合作为设备侧 worker：Claude Code、Codex CLI、Aider、Cline、Roo Code
+- 最适合作为协议层：MCP
+- 最适合作为 agent-to-agent 通信层：A2A
+
+## 竞品对比表
+
+| 产品/方案 | 类型 | 中控能力 | 子任务/多代理 | 多设备本地 worker 适配 | 聊天入口 | 自建/二开友好度 | 适合借鉴的点 | 主要短板 | 结论 |
+|---|---|---|---|---|---|---|---|---|---|
+| Devin Enterprise | 商业成品 | 很强 | 强 | 弱到中 | 强 | 低 | 企业级组织管理、RBAC、API、调度、外部集成 | 更偏云环境，不是为本地多设备编队设计 | 可参考“成品控制台” |
+| OpenAI Codex | 商业成品 + 平台能力 | 强 | 强 | 中 | 强 | 中 | 主账号统一对话、多入口、云并行任务 | 不是现成的多物理设备 fleet 管理器 | 可作为 manager brain |
+| Factory | 商业成品 | 很强 | 很强 | 中 | 很强 | 低到中 | Subagents、Missions、多入口控制 | 生态较新，闭源较重 | 值得重点借鉴交互与控制面 |
+| OpenHands Cloud / SDK | 开源平台 + 托管服务 | 强 | 强 | 中到强 | 强 | 很高 | Cloud UI、SDK、远程沙箱、权限、可自建 | 仍需自己补产品化细节 | 最适合做底座 |
+| GitHub Copilot coding agent | 商业成品 | 中到强 | 中 | 弱 | 中 | 低 | Issue/PR 驱动、GitHub 闭环、组织策略 | 太 GitHub-centric | 只适合借鉴局部流程 |
+| Cursor Background Agents | 商业成品 | 中 | 中 | 中 | 强 | 低 | 远程 agent + Slack 入口 | 更偏账号级，不像团队总控台 | 值得借鉴轻量远程协作 |
+| Claude Code | 本地 agent | 弱 | 中 | 很强 | 中 | 中 | 本地终端执行、开发体验强 | local-first，不是中控台 | 非常适合当 worker |
+| Sourcegraph + Batch Changes + MCP | 平台底座 | 中 | 弱到中 | 弱 | 弱 | 中 | 批量改仓、代码搜索、分析能力 | 不是 agent control plane | 可作为代码情报层 |
+| LangGraph | 编排框架 | 中到强 | 很强 | 中 | 弱 | 很高 | 状态机、工作流、持久状态 | UI、权限、执行层都要自建 | 适合完全自研时使用 |
+| AutoGen | 多代理框架 | 中 | 很强 | 中 | 弱 | 高 | 多代理协作范式成熟 | 产品化要自己做 | 适合研究协作逻辑 |
+| CrewAI | 工作流框架 | 中 | 很强 | 中 | 弱 | 中到高 | Flow、观测、流程编排 | 编码执行层不够强 | 可借鉴业务流程层 |
+| MCP | 工具协议 | 不适用 | 不适用 | 强 | 不适用 | 很高 | 工具统一接入标准 | 不是 agent 调度协议 | 必须纳入架构 |
+| A2A | agent 通信协议 | 不适用 | 强 | 强 | 不适用 | 高 | 跨 agent 通信和任务协作 | 生态仍在发展 | 建议前瞻纳入 |
+
+## 重点产品拆解
+
+### 1. Devin Enterprise
+
+适合借鉴：
+
+- 企业级组织、权限、审计、API
+- 从 Slack、Teams、GitHub、Linear、Jira 等入口发起任务
+- 定时 session 和共享工作流
+
+不完全适合直接照搬的点：
+
+- 更偏云端 Devin machine
+- 对本地 Windows/Mac 设备级 agent 编队支持不是它的核心卖点
+
+适合你们的参考角色：
+
+- 作为“企业中控台形态”参考
+
+来源：
+
+- https://docs.devin.ai/enterprise/get-started
+- https://docs.devin.ai/release-notes
+
+### 2. OpenAI Codex
+
+适合借鉴：
+
+- 主账号统一发起和跟踪任务
+- 跨 App、CLI、IDE、GitHub、Slack、Linear 协作
+- 云端并行任务和账户级工作台体验
+
+不完全适合直接照搬的点：
+
+- 更像围绕账户和任务的 agent 工作台
+- 不是专门面向“多台真实开发设备”的设备编排系统
+
+适合你们的参考角色：
+
+- 作为 manager brain
+- 作为主对话入口和任务拆分层
+
+来源：
+
+- https://openai.com/index/codex-now-generally-available/
+- https://help.openai.com/en/articles/11369540-codex-in-chatgpt
+
+### 3. Factory
+
+适合借鉴：
+
+- Missions 和 Custom Droids 的任务拆解思路
+- Slack、Teams、GitHub App、IDE、CLI、Web 的多入口控制
+- 远程和本地结合的控制面叙事
+
+不完全适合直接照搬的点：
+
+- 闭源较重
+- 需要较多逆向产品层理解，难直接搬运技术实现
+
+适合你们的参考角色：
+
+- 作为“多入口 + 子代理协同”交互范式参考
+
+来源：
+
+- https://docs.factory.ai/
+- https://docs.factory.ai/user-guides/droids/creating-custom-droids
+
+### 4. OpenHands Cloud / SDK
+
+适合借鉴：
+
+- OpenHands SDK 已经是 CLI 和 Cloud 的底层引擎
+- 有 Cloud UI、Cloud API、权限、预算、远程沙箱
+- 自建和二开空间大
+
+不完全适合直接照搬的点：
+
+- 如果要做极强的多设备本地 worker 编排，仍需扩展 agent server 和 worker registry
+
+适合你们的参考角色：
+
+- 最优先底座候选
+
+来源：
+
+- https://docs.openhands.dev/sdk
+- https://docs.openhands.dev/usage/cloud/cloud-ui
+
+### 5. Claude Code
+
+适合借鉴：
+
+- 本地执行体验强
+- 非常适合挂在 Windows/Mac 上做 worker
+- 终端型编码任务执行成熟
+
+不完全适合直接照搬的点：
+
+- 官方定位是 local-first，不是统一云端中控
+
+适合你们的参考角色：
+
+- 设备侧 worker 执行器
+
+来源：
+
+- https://claude.com/product/claude-code
+
+## 我们的推荐路线
+
+### 路线 A：最快做出产品
+
+- 底座：OpenHands SDK
+- Manager：Codex
+- 设备侧 worker：Claude Code / Codex CLI
+- 对话入口：Web 为主，Slack/Telegram 为辅
+
+适合：
+
+- 先把真实可用的多设备协作跑起来
+
+### 路线 B：完全自研控制面
+
+- 编排：LangGraph 或 AutoGen
+- Manager：Codex
+- 工具层：MCP
+- agent 协作层：A2A
+- 设备侧 worker：你们自己的 daemon，内部再调 Claude Code / Codex CLI
+
+适合：
+
+- 你们希望最终拥有自己的协议、调度和产品层壁垒
+
+### 路线 C：先验证，再重构
+
+- 第一阶段用 OpenHands 风格快速拼装 MVP
+- 第二阶段把设备注册、任务队列、审计、聊天入口收回自研
+
+适合：
+
+- 你们既想快，又不想被单一底座绑死
+
+## 对你这个产品最关键的判断
+
+如果目标是：
+
+- 主账号持续对话
+- 实时调整需求
+- 控制多台真实 Windows/Mac
+- 支持协同开发和独立开发两种模式
+
+那么最好的产品结构不是“一个超强 agent”，而是：
+
+- 一个 control plane
+- 一个 manager agent
+- 多个设备侧 worker
+- 一套可中断、可续跑、可审计的任务系统
+
+也就是说，真正应该对标的不是“谁最会写代码”，而是“谁最会调度一群会写代码的代理”。
+
+## 下一步建议
+
+完成第 1 项后，建议继续做：
+
+1. 系统架构图
+2. MVP 功能清单
+3. 技术选型建议
+4. 消息协议与任务状态机
--- a/docs/implementation-roadmap.md
+++ b/docs/implementation-roadmap.md
@@ -0,0 +1,174 @@
+# Boss 实施路线图
+
+更新日期：2026-03-23
+
+## 路线目标
+
+把 Boss 从概念验证推进到可长期迭代的产品原型。
+
+## 阶段划分
+
+### Phase 0：项目底座
+
+目标：
+
+- 建立基础仓库结构
+- 搭建前后端骨架
+- 建立数据库和基础实体
+
+完成标准：
+
+- 有 Web 控制台壳子
+- 有后端 API 壳子
+- 有 Postgres 和 Redis
+- 能创建 session
+
+### Phase 1：多设备接入
+
+目标：
+
+- 让 2 台 Windows 和 1 台 Mac 成为可调度 worker
+
+完成标准：
+
+- worker 可以注册
+- worker 有心跳
+- 控制台能看到在线状态
+- 可以手工下发简单任务
+
+### Phase 2：对话驱动任务拆分
+
+目标：
+
+- 用户一句话创建任务
+- manager 生成任务树
+
+完成标准：
+
+- 对话生成主任务和子任务
+- 子任务可以指派到不同 worker
+- UI 能看到任务树
+
+### Phase 3：执行、事件和审批
+
+目标：
+
+- worker 真正执行开发动作
+- 中途回传结构化进度
+- 高风险动作需要审批
+
+完成标准：
+
+- worker 能跑 git、terminal、测试
+- 进度能在 UI 和聊天入口显示
+- 审批可以打断并恢复流程
+
+### Phase 4：中途变更需求和重规划
+
+目标：
+
+- 支持用户实时改变需求
+- manager 能生成新计划
+
+完成标准：
+
+- 用户可在原会话继续说话
+- 系统可 pause/cancel/replan
+- 能展示计划差异
+
+### Phase 5：协同开发增强
+
+目标：
+
+- 支持研究、实现、测试分工协作
+
+完成标准：
+
+- 一个任务可以拆成研究和实现链路
+- 子任务之间可引用共享上下文
+- manager 能输出阶段性总结
+
+## 推荐开发顺序
+
+1. 建库和实体
+2. worker daemon
+3. Web 控制台基础页
+4. manager 集成
+5. 子任务调度
+6. 事件流和实时订阅
+7. 审批
+8. 聊天入口
+9. 需求变更与重规划
+
+## 每阶段产物
+
+### Phase 0 产物
+
+- API skeleton
+- DB schema
+- 基础 UI
+
+### Phase 1 产物
+
+- `boss-worker`
+- worker registry
+- 设备管理页
+
+### Phase 2 产物
+
+- manager planning adapter
+- task tree UI
+- assignment service
+
+### Phase 3 产物
+
+- executor adapter
+- event stream
+- approval flow
+
+### Phase 4 产物
+
+- plan diff engine
+- pause/resume/cancel controls
+- session replay
+
+### Phase 5 产物
+
+- collaborative mode
+- shared artifacts
+- richer progress summaries
+
+## 里程碑定义
+
+### 里程碑 A：可看见
+
+- 能看到 3 台机器在线
+- 能创建任务
+
+### 里程碑 B：可调度
+
+- 能把任务分发给不同设备
+- 能看到执行状态
+
+### 里程碑 C：可对话改需求
+
+- 执行中可重规划
+- 任务不会失控
+
+### 里程碑 D：可协同开发
+
+- 多台设备能并行分工
+- 主控端能统一总结
+
+## 当前最建议的首版交付
+
+如果你现在就准备开工，建议首版目标定成：
+
+- Web 控制台
+- 3 台 worker
+- manager 拆分最多 3 个子任务
+- worker 支持 git、terminal、test
+- 支持审批
+- 支持需求变更后重规划
+
+做到这里，这个产品就已经不是 demo，而是一个真正可试用的原型。
--- a/docs/message-protocol-and-state-machine.md
+++ b/docs/message-protocol-and-state-machine.md
@@ -0,0 +1,419 @@
+# Boss 消息协议与任务状态机
+
+更新日期：2026-03-23
+
+## 设计目标
+
+这份文档定义 Boss 内部最小可用消息模型，确保系统支持：
+
+- 实时对话
+- 子任务拆分
+- 中途改需求
+- 暂停和恢复
+- 审批
+- 事件回放
+
+## 核心原则
+
+- 所有关键变化都事件化
+- 会话状态来自事件流和状态快照
+- 用户消息和系统动作统一进入同一条项目时间线
+- worker 回传必须结构化，不能只传纯文本
+
+## 会话模型
+
+### 层级
+
+```text
+Project Session
+  -> Conversation Thread
+  -> Task Tree
+  -> Worker Assignments
+  -> Approval Requests
+  -> Artifacts
+```
+
+### 对象定义
+
+#### project_session
+
+```json
+{
+  "id": "ps_001",
+  "title": "修复登录与缓存问题",
+  "status": "active",
+  "active_objective": "先定位根因，再决定是否修改代码",
+  "created_at": "2026-03-23T12:00:00Z"
+}
+```
+
+#### message
+
+```json
+{
+  "id": "msg_001",
+  "session_id": "ps_001",
+  "role": "user",
+  "channel": "web",
+  "content": "先排查登录失败，不要急着改代码",
+  "created_at": "2026-03-23T12:00:05Z"
+}
+```
+
+#### task
+
+```json
+{
+  "id": "task_001",
+  "session_id": "ps_001",
+  "parent_task_id": null,
+  "title": "定位登录失败根因",
+  "kind": "investigation",
+  "status": "planning",
+  "priority": "high",
+  "risk_level": "medium"
+}
+```
+
+#### worker_assignment
+
+```json
+{
+  "id": "wa_001",
+  "task_id": "task_002",
+  "worker_id": "worker_win_a",
+  "status": "assigned"
+}
+```
+
+## 事件模型
+
+### 统一事件格式
+
+```json
+{
+  "id": "evt_001",
+  "session_id": "ps_001",
+  "task_id": "task_002",
+  "source": "worker",
+  "type": "task.step.started",
+  "timestamp": "2026-03-23T12:10:00Z",
+  "payload": {
+    "step": "run_tests",
+    "summary": "开始运行登录相关测试"
+  }
+}
+```
+
+字段说明：
+
+- `source` 可取 `user`, `manager`, `system`, `worker`
+- `type` 是事件名
+- `payload` 是结构化内容
+
+### 推荐事件类型
+
+#### 会话事件
+
+- `session.created`
+- `session.objective.updated`
+- `session.message.added`
+
+#### 规划事件
+
+- `plan.created`
+- `plan.updated`
+- `plan.diff.generated`
+
+#### 任务事件
+
+- `task.created`
+- `task.assigned`
+- `task.started`
+- `task.progress`
+- `task.blocked`
+- `task.paused`
+- `task.resumed`
+- `task.cancelled`
+- `task.completed`
+- `task.failed`
+
+#### worker 事件
+
+- `worker.heartbeat`
+- `worker.capabilities.updated`
+- `worker.assignment.accepted`
+- `worker.assignment.rejected`
+
+#### 执行步骤事件
+
+- `task.step.started`
+- `task.step.finished`
+- `task.step.failed`
+- `tool.call.requested`
+- `tool.call.finished`
+
+#### 审批事件
+
+- `approval.requested`
+- `approval.approved`
+- `approval.rejected`
+
+## 任务状态机
+
+### 主状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> planning
+    planning --> queued
+    queued --> assigned
+    assigned --> running
+    running --> blocked
+    running --> paused
+    running --> waiting_approval
+    running --> completed
+    running --> failed
+    running --> cancelled
+    blocked --> running
+    paused --> running
+    waiting_approval --> running
+    waiting_approval --> cancelled
+    failed --> queued
+```
+
+### 状态说明
+
+| 状态 | 含义 |
+|---|---|
+| `planning` | manager 正在生成任务计划 |
+| `queued` | 已创建，等待调度 |
+| `assigned` | 已分配给某个 worker |
+| `running` | worker 正在执行 |
+| `blocked` | 因外部条件缺失而卡住 |
+| `paused` | 被用户或系统暂停 |
+| `waiting_approval` | 等待用户审批 |
+| `completed` | 成功完成 |
+| `failed` | 执行失败 |
+| `cancelled` | 被取消 |
+
+## 需求变更协议
+
+### 为什么需要单独协议
+
+用户在对话里改需求，不应该等于简单新增一句聊天消息。系统需要知道这条消息是否会：
+
+- 改变当前目标
+- 废弃现有子任务
+- 新增任务
+- 触发审批
+
+### 建议流程
+
+1. 用户消息进入 session
+2. manager 判断该消息是否属于 `objective change`
+3. 如果是，生成 `plan.diff`
+4. Task Service 根据 diff 执行状态迁移
+
+### plan diff 示例
+
+```json
+{
+  "session_id": "ps_001",
+  "change_reason": "用户要求先修接口重试，不处理缓存",
+  "cancel_tasks": ["task_cache_001"],
+  "pause_tasks": ["task_ui_003"],
+  "continue_tasks": ["task_api_002"],
+  "create_tasks": [
+    {
+      "title": "修复接口重试逻辑",
+      "kind": "implementation",
+      "priority": "high"
+    }
+  ]
+}
+```
+
+## 审批协议
+
+### 审批请求格式
+
+```json
+{
+  "id": "apr_001",
+  "session_id": "ps_001",
+  "task_id": "task_009",
+  "kind": "dangerous_command",
+  "summary": "准备执行 rm -rf build-cache",
+  "risk_level": "high",
+  "status": "pending"
+}
+```
+
+### 审批动作
+
+支持：
+
+- `approve`
+- `reject`
+- `approve_once`
+- `approve_for_session`
+
+MVP 建议只做：
+
+- `approve`
+- `reject`
+
+## Worker 协议
+
+### worker 注册
+
+```json
+{
+  "worker_id": "worker_mac_001",
+  "hostname": "mac-studio",
+  "os": "macos",
+  "shell": "zsh",
+  "capabilities": [
+    "git",
+    "terminal",
+    "playwright",
+    "xcode"
+  ]
+}
+```
+
+### heartbeat
+
+```json
+{
+  "worker_id": "worker_mac_001",
+  "status": "idle",
+  "current_task_id": null,
+  "load": 0.25,
+  "timestamp": "2026-03-23T12:15:00Z"
+}
+```
+
+### 任务执行请求
+
+```json
+{
+  "task_id": "task_102",
+  "session_id": "ps_001",
+  "workspace": {
+    "repo": "git@github.com:org/repo.git",
+    "branch": "boss/task-102",
+    "worktree_path": "/workers/worktrees/task-102"
+  },
+  "execution_mode": "independent",
+  "goal": "排查登录失败，输出根因和修复建议",
+  "constraints": [
+    "先不要改代码",
+    "优先跑测试和读日志"
+  ]
+}
+```
+
+## 进度摘要协议
+
+worker 和 manager 都不应该只回长文本。
+
+推荐维护一份结构化摘要：
+
+```json
+{
+  "task_id": "task_102",
+  "summary": "已定位到接口重试在 401 时进入死循环",
+  "progress_percent": 60,
+  "current_step": "analyze_retry_logic",
+  "next_step": "补充最小修复方案并跑测试",
+  "risk": "medium"
+}
+```
+
+这个结构化摘要可以直接喂给：
+
+- Web 控制台右侧面板
+- 聊天入口状态播报
+- manager 汇总器
+
+## 协同开发协议
+
+### 模式字段
+
+任务可声明：
+
+- `independent`
+- `collaborative`
+- `research_only`
+
+### collaborative 模式下增加字段
+
+```json
+{
+  "shared_context_refs": [
+    "artifact_001",
+    "task_202.summary"
+  ],
+  "handoff_expected": true
+}
+```
+
+用于支持：
+
+- 研究任务把结论交给实现任务
+- 后端任务把 API 变更交给前端任务
+
+## UI 实时订阅模型
+
+控制台建议订阅三个流：
+
+- `session_feed`
+- `task_feed`
+- `worker_feed`
+
+这样可以避免一个超大流承载所有内容。
+
+## 失败处理策略
+
+### 可重试失败
+
+- 网络抖动
+- worker 短时离线
+- tool call 超时
+
+### 不可重试失败
+
+- 权限不足
+- 任务目标冲突
+- 用户明确取消
+
+### 推荐策略
+
+- 每个任务记录 `retry_count`
+- 重试必须带原因
+- 多次失败要自动升级为 `blocked`
+
+## MVP 最小协议集
+
+第一版只需要支持这些事件：
+
+- `session.message.added`
+- `plan.created`
+- `task.created`
+- `task.assigned`
+- `task.started`
+- `task.progress`
+- `task.paused`
+- `task.cancelled`
+- `task.completed`
+- `task.failed`
+- `worker.heartbeat`
+- `approval.requested`
+- `approval.approved`
+- `approval.rejected`
+
+## 一句话总结
+
+Boss 的协议核心不是“消息收发”，而是“让对话、任务、worker、审批都落在同一个可追踪状态机里”。
--- a/docs/mvp-feature-plan.md
+++ b/docs/mvp-feature-plan.md
@@ -0,0 +1,269 @@
+# Boss MVP 功能清单
+
+更新日期：2026-03-23
+
+## MVP 目标
+
+用最小可用范围验证下面三件事：
+
+- 用户能持续通过对话管理一个项目
+- 主控端能把任务拆给多台设备并持续汇报进度
+- 用户能在中途改变需求，系统能安全重规划
+
+MVP 不追求：
+
+- 多租户企业 SaaS
+- 完整计费系统
+- 支持所有聊天平台
+- 自动解决所有冲突
+
+## MVP 范围定义
+
+### 必须有
+
+- 单用户项目会话
+- 3 台设备接入
+- manager 拆任务
+- worker 在线心跳
+- 实时进度事件
+- 任务暂停、继续、取消
+- 高风险审批
+- Git worktree 隔离
+- 测试结果回传
+- 基础审计
+
+### 可以延后
+
+- 多组织管理
+- 向量记忆优化
+- 多模型自动路由
+- 自动 PR 审核
+- 自动成本优化
+- 丰富报表
+
+## 用户故事
+
+### 用户故事 1：发起项目任务
+
+作为用户，我希望在一个对话里描述需求，让系统自动拆任务给不同设备执行。
+
+验收标准：
+
+- 用户说一句自然语言需求即可创建 project session
+- manager 能生成主任务和子任务
+- 子任务能分配到不同设备
+
+### 用户故事 2：查看实时进度
+
+作为用户，我希望随时看到每台设备当前做到了哪里，而不是只在结束时知道结果。
+
+验收标准：
+
+- 每个子任务有状态、最近一步、最近日志摘要
+- UI 能看到设备在线状态
+- 聊天入口能返回汇总版进度
+
+### 用户故事 3：中途改需求
+
+作为用户，我希望在任务执行中直接说“改一下方向”，系统就能调整任务，而不是重新开一个新会话。
+
+验收标准：
+
+- 新需求追加到同一个 session
+- manager 能触发 replan
+- 正在运行的子任务可安全暂停或取消
+- 用户能看到新旧计划差异
+
+### 用户故事 4：审批危险操作
+
+作为用户，我希望对删文件、强推分支、运行危险命令等行为进行确认。
+
+验收标准：
+
+- worker 可发起审批请求
+- 控制台和聊天入口都能完成审批
+- 审批前任务挂起
+- 审批结果可审计
+
+### 用户故事 5：协同开发
+
+作为用户，我希望多台设备能分别做调研、编码和测试，并由主账号统一汇总。
+
+验收标准：
+
+- 至少支持 2 个并行子任务
+- manager 可汇总结果
+- 同一项目下子任务之间可引用共享上下文
+
+## MVP 模块清单
+
+### 1. Web 控制台
+
+必须页面：
+
+- 会话页
+- 任务树页
+- 设备页
+- 审批页
+
+最小功能：
+
+- 发消息
+- 看任务树
+- 看设备在线状态
+- 审批和取消任务
+
+### 2. 聊天入口
+
+第一阶段建议只接一个平台：
+
+- Slack 或 Telegram 二选一
+
+最小功能：
+
+- 新建任务
+- 查看状态
+- 审批
+- 取消任务
+
+不建议第一阶段做：
+
+- 复杂文件浏览
+- 终端实时流
+
+### 3. Session Service
+
+最小职责：
+
+- 创建会话
+- 保存消息
+- 返回会话历史
+- 标记当前 active objective
+
+### 4. Task Service
+
+最小职责：
+
+- 创建任务树
+- 更新任务状态
+- 管理依赖关系
+- 触发重规划
+
+### 5. Scheduler
+
+最小职责：
+
+- 根据能力分配 worker
+- 处理重试和超时
+- 维护 assignment 状态
+
+### 6. Worker Daemon
+
+最小职责：
+
+- 注册设备
+- 心跳
+- 拉取任务
+- 执行命令
+- 回传结构化事件
+
+### 7. 审批系统
+
+最小职责：
+
+- 定义危险动作
+- 创建审批请求
+- 接收审批结果
+- 恢复或终止工作流
+
+## MVP 页面草图
+
+### 会话页
+
+区域：
+
+- 左侧项目和会话列表
+- 中间对话流
+- 右侧任务树与设备执行摘要
+
+### 任务页
+
+区域：
+
+- 主任务卡片
+- 子任务列表
+- 当前负责设备
+- 状态与最近事件
+
+### 设备页
+
+区域：
+
+- 设备名称
+- OS
+- 在线状态
+- 当前任务
+- 最近心跳
+- 工具能力
+
+## MVP 指标
+
+### 产品指标
+
+- 任务可创建成功率
+- 子任务成功分配率
+- 需求变更后的重规划成功率
+- 审批往返耗时
+
+### 系统指标
+
+- worker 心跳在线率
+- 事件回传延迟
+- 任务平均完成时间
+- 失败重试成功率
+
+### 体验指标
+
+- 用户查看进度时的响应时间
+- 对话到任务树生成耗时
+- 需求变更到新计划生效耗时
+
+## MVP 版本边界
+
+### V0.1
+
+- Web 控制台
+- 单聊天入口
+- 3 台设备
+- manager 拆 2 到 3 个子任务
+- 手动审批
+
+### V0.2
+
+- 任务模板
+- 更细的设备能力调度
+- GitHub PR 集成
+- 更丰富的任务摘要
+
+### V0.3
+
+- 协同开发模式增强
+- 共享上下文管理
+- 更细粒度权限
+
+## MVP 不做清单
+
+- 不做跨团队权限模型
+- 不做复杂订阅体系
+- 不做自动跨仓库大规模变更
+- 不做完整 IDE 插件矩阵
+- 不做长周期自主运行无需监督的全自动模式
+
+## 开工优先级
+
+1. 设备接入和心跳
+2. 对话到任务树
+3. 子任务分发
+4. worker 执行与事件回传
+5. 审批与中断恢复
+6. 聊天入口
--- a/docs/system-architecture.md
+++ b/docs/system-architecture.md
@@ -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 执行权限过大
+
+规避方式：
+
+- 把危险命令纳入审批
+- 工具分级授权
+- 关键操作记录审计日志
--- a/docs/technical-selection.md
+++ b/docs/technical-selection.md
@@ -0,0 +1,314 @@
+# Boss 技术选型建议
+
+更新日期：2026-03-23
+
+## 选型原则
+
+- 先保证系统能跑，再追求最优雅
+- 持久状态优先于纯内存编排
+- 结构化事件优先于拼字符串日志
+- 尽量复用成熟 agent 运行时，而不是自己重写编码 agent
+
+## 总体选型建议
+
+| 层 | 推荐 | 备选 | 原因 |
+|---|---|---|---|
+| 前端控制台 | Next.js | Remix, Nuxt | 适合快速做管理台和流式 UI |
+| Desktop | Tauri | Electron | 后续需要时再补，Tauri 更轻 |
+| 后端 API | NestJS 或 Fastify | Express, Go Fiber | 结构清晰，适合长期维护 |
+| 工作流引擎 | Temporal | Inngest, BullMQ + 自建状态机 | 长任务、中断、审批、恢复是核心需求 |
+| 队列/事件 | Redis Streams | NATS, Kafka | MVP 阶段足够轻，开发快 |
+| 主数据库 | Postgres | MySQL | 事务、JSON、查询能力更适合控制平面 |
+| 缓存 | Redis | KeyDB | 用于会话热数据、限流、事件流 |
+| Manager Agent | Codex | Claude API, GPT-5.x Responses | 适合做规划、汇总、重规划 |
+| Worker Runtime | Codex CLI + Claude Code | OpenHands agent runtime | 直接复用成熟编码 agent |
+| 工具协议 | MCP | 自定义 tool API | 标准化工具接入 |
+| 浏览器自动化 | Playwright | Puppeteer | 成熟稳定，适合 agent 使用 |
+| 聊天入口 | Slack 或 Telegram | 飞书, 企业微信 | 文档、生态和迭代速度更合适 |
+| 身份认证 | Clerk 或 Auth.js | 自建 OAuth | MVP 快速起步 |
+| 监控 | OpenTelemetry + Grafana | Datadog, Sentry | 方便追踪任务链路 |
+
+## 为什么推荐这个技术组合
+
+### 1. Next.js 作为控制台前端
+
+原因：
+
+- 适合做 dashboard、对话界面、任务树、设备面板
+- 容易做流式更新和服务端渲染
+- 与 TypeScript 一体化
+
+不建议现在单独起 React Native：
+
+- 当前核心不是移动端，而是 control plane
+
+### 2. NestJS 或 Fastify 作为后端
+
+如果团队偏工程化：
+
+- 选 NestJS
+
+如果你想更轻更快：
+
+- 选 Fastify
+
+建议：
+
+- 先用 Fastify 或 NestJS 中你更熟的那个
+- 关键是把服务边界拆干净
+
+### 3. Temporal 作为工作流引擎
+
+这是当前最关键的选型之一。
+
+Boss 不是短请求系统，而是长任务系统。你需要天然支持：
+
+- 几分钟到几小时的任务
+- 中途暂停
+- 审批等待
+- worker 断线重连
+- 任务恢复
+
+如果不用工作流引擎，后面会自己补很多分布式状态机逻辑。
+
+如果 MVP 阶段不想上 Temporal：
+
+- 可以先用 `BullMQ + Postgres 状态表`
+- 但要尽快收敛到真正可恢复的工作流模型
+
+### 4. Postgres 作为主数据库
+
+Boss 的核心不是海量日志，而是：
+
+- 会话
+- 任务树
+- 审批
+- worker 注册
+- 状态快照
+
+这些都非常适合 Postgres。
+
+### 5. Codex 作为 manager
+
+原因：
+
+- 你希望主账号持续对话和重规划
+- manager 不需要最强本地执行，它更需要任务理解、拆解和汇总
+- Codex 在多入口和云任务语境里更契合 manager 角色
+
+推荐职责：
+
+- 规划
+- 重规划
+- 汇总
+- 风险解释
+
+不建议让 manager 干太多底层执行：
+
+- 容易把规划和执行耦合死
+
+### 6. Claude Code / Codex CLI 作为 worker runtime
+
+原因：
+
+- 本地设备执行体验成熟
+- 适合接 terminal、filesystem、git、browser
+- 真实开发环境兼容性更好
+
+建议策略：
+
+- Mac 和 Windows worker 都先抽象成统一 `executor`
+- 底层可配置使用 `codex` 或 `claude`
+
+## 服务拆分建议
+
+### 第一阶段服务
+
+- `api-gateway`
+- `session-service`
+- `task-service`
+- `scheduler-service`
+- `worker-gateway`
+- `notification-service`
+
+### 第二阶段可拆
+
+- `approval-service`
+- `memory-service`
+- `git-integration-service`
+- `chat-connector-service`
+
+## 数据存储建议
+
+### Postgres 表
+
+建议至少有：
+
+- `users`
+- `project_sessions`
+- `messages`
+- `tasks`
+- `task_dependencies`
+- `worker_nodes`
+- `worker_capabilities`
+- `worker_assignments`
+- `task_events`
+- `approval_requests`
+- `artifacts`
+
+### Redis 用途
+
+- worker 在线状态
+- 事件总线
+- UI 实时订阅
+- 节流和限流
+
+## Worker 设计建议
+
+### worker 进程结构
+
+组成：
+
+- `boss-worker` 守护进程
+- `executor` 适配层
+- `tool adapters`
+- `sandbox policy`
+- `event reporter`
+
+### worker 本地目录策略
+
+建议：
+
+- 一个统一工作根目录
+- 每个任务一个独立 workspace
+- 每个任务一个独立 git worktree
+
+示例：
+
+```text
+~/boss-worker/
+  repos/
+  worktrees/
+  cache/
+  artifacts/
+```
+
+### worker 能力声明
+
+每个 worker 启动时上报：
+
+- OS
+- shell
+- 是否支持浏览器自动化
+- 是否支持特定 IDE
+- 是否有移动端模拟器
+- 是否具备 repo 热缓存
+
+## 协议选型建议
+
+### MCP
+
+用途：
+
+- 统一工具调用
+
+适合接：
+
+- Git
+- 文件系统
+- 浏览器
+- Issue 系统
+- CI
+
+### A2A
+
+用途：
+
+- 中长期用于 agent 之间通信
+
+建议：
+
+- MVP 不强依赖
+- 但内部消息模型尽量向 agent-to-agent 协作靠拢
+
+## 前后端通信建议
+
+### 控制台实时能力
+
+推荐：
+
+- WebSocket 或 Server-Sent Events
+
+用途：
+
+- 推送任务状态
+- 推送审批请求
+- 推送设备在线变化
+
+### worker 连接方式
+
+推荐：
+
+- WebSocket 长连接
+
+原因：
+
+- 需要双向通信
+- 需要下发中断和恢复命令
+
+## 安全建议
+
+### 最小权限原则
+
+- worker 不要默认拥有所有仓库权限
+- 每种工具调用都要有权限分级
+
+### 高风险动作审批
+
+必须纳入审批的动作：
+
+- 删除大量文件
+- 强推分支
+- 执行危险 shell
+- 访问敏感路径
+
+### 审计
+
+必须记录：
+
+- 谁发起了什么
+- 哪个 worker 执行了什么
+- 哪个 agent 建议了什么
+- 审批前后状态
+
+## 推荐的 MVP 技术栈
+
+### MVP 最稳组合
+
+- 前端：Next.js
+- 后端：NestJS
+- 数据库：Postgres
+- 缓存和事件：Redis
+- 工作流：BullMQ，后续升级 Temporal
+- Manager：Codex
+- Worker：Codex CLI + Claude Code
+- 聊天入口：Telegram 或 Slack
+
+### 如果你要一步到位更稳
+
+- 前端：Next.js
+- 后端：NestJS
+- 数据库：Postgres
+- 缓存：Redis
+- 工作流：Temporal
+- Manager：Codex
+- Worker：Codex CLI + Claude Code
+- 监控：OpenTelemetry
+
+## 不推荐的坑
+
+- 不要一开始就全微服务
+- 不要一开始就自研完整 agent runtime
+- 不要把聊天平台当成主控制台
+- 不要让多个任务共用一个工作目录
+- 不要把审批做成“日志里提示一下”而不是显式状态