架构设计 · ARCHITECTURE DESIGN v2.0 DRAFT
全景架构 · SYSTEM OVERVIEW
前端层 · FRONTEND — React 18 + TypeScript + Vite
Design System 组件从 claude.ai/design 迁移 · TSX
三栏看板Sidebar · Main · EventPanel · 拖拽宽度
Mobile Tab390px · 底部四 Tab 导航
Zustand客户端状态管理
i18n · 5 语言zh / en / es / ja / fr
WebSocket Client实时看板刷新
Vite Dev Server开发时 API 代理 · HMR
dist/web/构建产物 → Fastify 托管
REST · /api/*
WebSocket · /ws
Auth Token（预留）
API 层 · Fastify（路由拆分 + Schema 校验）
routes/projectsCRUD · logo · sync · reorder
routes/tasksCRUD · decide · requeue · transition
routes/runstranscript · active runs
routes/approvalspendingApprovals
routes/metrics健康度 · 成本聚合
ws.tsStore 事件 → 广播所有客户端
middleware/auth.tsno-op · 预留 JWT 插槽
schemas/Fastify JSON Schema 请求校验
数据层 · DB ABSTRACTION
DBAdapter 接口统一抽象
SqliteAdapter当前实现
PostgresAdapter未来多租户
ProjectRepo
TaskRepo
RunRepo
ApprovalRepo
EventRepo
MetricsRepo
读写 DB
事件订阅 → WS 推送
调度查询
Daemon 层（拆分 4 职责）
Orchestrator协调者 · tick 主循环
Scheduler纯调度逻辑 · score → 选任务
WorkerManagerspawn / reap / pid 管理
Ingestoroutbox.ndjson → DB · 幂等摄取
MergeCoordinatormerge-resolve 池 + settle
config.ts
notify.ts
Worker 进程（按类型拆分）
pipelines/executor
pipelines/planner
pipelines/conflict
pipelines/merge-resolve
runners/executorprompt + runTask
runners/plannerprompt + runPlanner
runners/conflict
runners/merge-resolve
文件协议（保留不变）job.json → outbox.ndjson → heartbeat
任务执行数据流 · EXECUTION FLOW
01 · 触发
用户 / API
POST /api/.../tasks
创建任务 → init 态
›
02 · 调度
Scheduler
score 排序 → claimable
ready → queued → executing
›
03 · 起进程
WorkerManager
spawn worker 进程
写 job.json · 记 pid
›
04 · 执行
Worker Pipeline
CC Agent 执行任务
追加 outbox.ndjson
›
05 · 摄取
Ingestor
outbox → DB
→ WS 推送 → 审核闸
重构变更对照 · WHAT CHANGES

✕ 删除

  • web/app.js (2473 行)替换为 React + TypeScript 前端
  • web/style.css (1333 行)设计 token 迁移到 frontend/src/tokens/
  • web/index.htmlVite 入口替代

✓ 保留不动

  • 文件协议 — job.json / outbox.ndjson / heartbeat
  • 状态机 — src/model/status.ts · TRANSITIONS
  • Score 调度算法 — src/model/scoring.ts
  • CC 封装 — src/executor/cc.ts
  • Schema SQL — src/store/schema.sql
  • MCP server — src/mcp/
  • CLI — src/cli/

⟳ 拆分重构

  • store.ts (1227行) → 6 Repo + DBAdapter 接口
  • orchestrator.ts (426行) → Scheduler + WorkerManager + Ingestor + MergeCoordinator
  • runner.ts (353行) → runners/ 4 个独立文件
  • pipeline.ts (358行) → pipelines/ 4 个独立文件
  • server.ts (401行) → routes/ 5 个路由模块 + Schema

✦ 新增

  • frontend/ — React + TypeScript + Vite 工程
  • frontend/components/ — claude design → TSX 组件库
  • src/store/db.ts — DBAdapter 抽象接口
  • src/store/repos/ — 6 个职责单一的 Repository
  • src/api/middleware/auth.ts — Auth 插槽（no-op）
  • src/api/schemas/ — Fastify JSON Schema 校验
目录结构 · FILE STRUCTURE
frontend/ ← 全新
src/
main.tsx
App.tsx 三栏布局 · 状态根
components/ ← claude design 迁移
core/ Button · StatusChip · ...
forms/ Input · Select · ...
surfaces/ Panel · GateCard · ...
ui/ 页面级组件
Sidebar.tsx
Topbar.tsx
GateSection.tsx
TaskTree.tsx
EventPanel.tsx
ArchiveSection.tsx
api/ HTTP + WS 客户端
store/ Zustand 状态管理
i18n/ 5 语言字符串
tokens/ CSS 自定义属性
index.html
vite.config.ts
tsconfig.json

web/ 整体删除
app.js 2473 行
style.css 1333 行
index.html
src/
api/
server.ts 入口（精简为注册插件）
routes/ ← 拆分
projects.ts · tasks.ts · runs.ts
approvals.ts · metrics.ts
schemas/ JSON Schema 请求校验
middleware/auth.ts no-op 插槽

store/
db.ts DBAdapter 接口
sqlite.ts 当前实现
repos/ ← 拆分自 store.ts
ProjectRepo · TaskRepo · RunRepo
ApprovalRepo · EventRepo · MetricsRepo
index.ts Store 聚合（外部接口不变）
mappers.ts 保留

daemon/
scheduler.ts ← 拆分 · 纯调度逻辑
worker-manager.ts ← 拆分 · 进程管理
ingest.ts 保留接口不变
merge-coordinator.ts ← 拆分
orchestrator.ts 精简为协调者

executor/
runners/ ← 拆分自 runner.ts
executor · planner · conflict · merge-resolve
pipelines/ ← 拆分自 pipeline.ts
executor · planner · conflict · merge-resolve
cc.ts · models.ts · worktree.ts 保留
MAESTRO ARCHITECTURE · v2.0 DRAFT · 仅设计文档，尚未实现 · 保留 · 拆分重构 · 新增 · 删除