docs: 更新 DESIGN.md/README 到 Phase 3 多进程执行架构 [tsk_-HYVwxzHIbrS]
- 写清工作模式:daemon=唯一 DB 写者+监工;worker=哑执行器(不碰 DB) - 通讯协议:job.json / outbox.ndjson(幂等 ingest)/ heartbeat / SIGTERM - 重启语义:reconcile 按 worker_pid+心跳判活 → re-adopt 或回收重试 + 持久化退避 - 同步更新系统总览图、数据模型(worker_pid/last_seq/next_eligible_at)、后端架构、风险、Phase 进度、env 表 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -4,8 +4,10 @@
|
||||
|
||||
按任务复杂度(Hard / Medium / Easy)分级驱动审批闸,用后台 agent(Claude Code)在隔离 git worktree 自动执行可执行任务,执行后自动跑 code review + 安全审计,accept 时 `--no-ff` 自动合并,改动不自动 push。
|
||||
|
||||
执行是**多进程解耦**的:daemon 是唯一 DB 写者兼监工,每个执行任务 spawn 一个**独立 worker 进程**(哑执行器,完全不碰 DB),二者只经文件 + 进程信号通讯(`job.json` / `outbox.ndjson` / `heartbeat` / `SIGTERM`),daemon 重启可按心跳判活 re-adopt 仍在跑的 worker。详见 [DESIGN.md](./DESIGN.md) §7。
|
||||
|
||||
- 完整设计见 **[DESIGN.md](./DESIGN.md)**。
|
||||
- 当前状态:**Phase 1 + Phase 2 + Phase 3 核心均已落地**(编排器 + score 调度 + 双复审 + 自动合并 + macOS 通知 + 额度透传 + 归档)。
|
||||
- 当前状态:**Phase 1 + Phase 2 + Phase 3 核心均已落地**(编排器 + score 调度 + 双复审 + 自动合并 + 多进程执行解耦 + macOS 通知 + 额度透传 + 归档)。
|
||||
|
||||
## 结构
|
||||
```
|
||||
@@ -14,9 +16,11 @@ src/
|
||||
store/ SQLite schema + 访问层(状态机守卫 + 审批闸)
|
||||
api/ REST + WebSocket API + logo 解析
|
||||
mcp/ MCP server(给 Claude Code)
|
||||
executor/ Agent SDK 封装(cc.ts)、worktree 管理、verify、
|
||||
runner(executor run)、reviewer(双复审)、merge、模型分级
|
||||
daemon/ maestrod 入口、编排器、macOS 通知、额度透传、配置
|
||||
executor/ Agent SDK 封装(cc.ts)、worktree 管理、verify、runner、reviewer(双复审)、merge、模型分级
|
||||
protocol.ts(daemon↔worker 文件协议:job/outbox/heartbeat/判活)
|
||||
worker.ts(独立 worker 进程入口)、pipeline.ts(纯执行管线,不碰 DB)
|
||||
daemon/ maestrod 入口、编排器(监工:spawn/ingest/回收)、ingest(outbox→DB)、
|
||||
macOS 通知、额度透传、配置
|
||||
sync/ 旧 todo.json → maestro 单向同步引擎
|
||||
web/ 看板(多项目·实时 WS·内联审批·归档详情)
|
||||
scripts/ poc-exec.mjs(执行闭环验证脚本)
|
||||
@@ -52,6 +56,12 @@ MCP 工具:`list_projects` / `create_project` / `list_tasks` / `get_task` / `c
|
||||
|
||||
## 核心功能速览
|
||||
|
||||
### 多进程执行(监工 + worker)
|
||||
- **daemon = 唯一 DB 写者 + 监工**:领任务 → 写 `job.json` → spawn worker → ingest 其 outbox → 回收死 worker。每轮 tick 顺序 `ingest → reap → claim`。
|
||||
- **worker = 哑执行器**:`node dist/executor/worker.js <runId>`,每任务一个独立进程,跑 worktree→执行→verify→双复审→产出,**完全不碰 DB**,进度/结果只追加进 `outbox.ndjson`。
|
||||
- **通讯**:`runs/<runId>/job.json`(daemon→worker 唯一输入)/ `outbox.ndjson`(worker→daemon,带 seq,daemon 按 `last_seq` 幂等 ingest)/ `heartbeat`(worker 每 10s 刷 mtime,daemon 判活)/ `SIGTERM`(取消/超时)。
|
||||
- **重启 re-adopt**:daemon 启动 `reconcileInterrupted()` 按 `worker_pid + 心跳`判活——活则 re-adopt 续 ingest(不打断 agent),死则回收重试(持久化退避 `next_eligible_at = min(30s·2^(n-1), 10min)`,超 `maxRetries` → `needs_attention`)。
|
||||
|
||||
### Score 调度
|
||||
编排器按 score 降序领任务(不抢占,领取时现算):
|
||||
```
|
||||
@@ -95,6 +105,7 @@ exec_review accept 时自动 `--no-ff` 合并:若 defaultBranch 在主检出
|
||||
| `MAESTRO_PORT` | daemon 监听端口 | `4517` |
|
||||
| `MAESTRO_DATA_DIR` | SQLite + worktree 数据目录 | `~/.maestro` |
|
||||
| `MAESTRO_ORCH_INTERVAL` | 编排器轮询间隔(秒),`0`=关闭 | `15` |
|
||||
| `MAESTRO_WORKER_CMD` | 覆盖 worker 进程启动命令(空格分隔),供 tsx 跑 .ts 入口/测试用 | `node dist/executor/worker.js` |
|
||||
| `MAESTRO_NOTIFY` | `0` 关闭 macOS 通知 | 开启 |
|
||||
| `MAESTRO_MODEL_EASY` | executor Easy 模型覆盖 | `claude-sonnet-4-6` |
|
||||
| `MAESTRO_MODEL_MEDIUM` | executor Medium 模型覆盖 | `claude-opus-4-8` |
|
||||
|
||||
Reference in New Issue
Block a user