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/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
+- 不要把聊天平台当成主控制台
+- 不要让多个任务共用一个工作目录
+- 不要把审批做成“日志里提示一下”而不是显式状态