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:
wangjia
2026-06-13 15:00:42 +08:00
parent f020e15137
commit 52c053baf4
2 changed files with 71 additions and 28 deletions
+15 -4
View File
@@ -4,8 +4,10 @@
按任务复杂度(Hard / Medium / Easy)分级驱动审批闸,用后台 agentClaude 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、
runnerexecutor run)、reviewer(双复审)、merge、模型分级
daemon/ maestrod 入口、编排器、macOS 通知、额度透传、配置
executor/ Agent SDK 封装(cc.ts)、worktree 管理、verify、runner、reviewer(双复审)、merge、模型分级
protocol.tsdaemon↔worker 文件协议:job/outbox/heartbeat/判活)
worker.ts(独立 worker 进程入口)、pipeline.ts(纯执行管线,不碰 DB
daemon/ maestrod 入口、编排器(监工:spawn/ingest/回收)、ingestoutbox→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,带 seqdaemon 按 `last_seq` 幂等 ingest/ `heartbeat`worker 每 10s 刷 mtimedaemon 判活)/ `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` |