1. 项目概述
一个场景无关的通用主Agent调度提示词模板，用于驱动多智能体（Multi-Agent）协作系统完成复杂任务的自动化开发与质量验证。经过30+轮设计评审和11项工程缺陷修复，形成了一套可复用的编排骨架。
核心命题：在主Agent上下文窗口有限的约束下，如何安全、可靠、可恢复地调度多个子Agent完成”计划→执行→验证→修正”闭环。
2. 技术栈
2.1 运行时平台
| 组件 | 技术 | 说明 |
|---|---|---|
| Agent 框架 | Claude Agent SDK / Claude Code | 多Agent启动、resume、后台运行 |
| 语言模型 | DeepSeek-v4-pro / DeepSeek-v4-flash | 主Agent用pro做调度决策，CHECK用falsh降本 |
| 操作系统 | Windows（bash 环境） | Git Bash 提供 GNU 工具链 |
| Shell | GNU Bash | find / sed / grep / ls / mkdir / stat |
| 文件系统 | NTFS | 标记文件、日志、报告、产物均落盘 |
2.2 核心CLI依赖
| 工具 | 用途 | 关键参数 |
|---|---|---|
find | Agent ID 探测 | -newer 时间过滤、-printf 时间排序 |
sed | plan.md 状态标记更新（兜底） | -i 原地替换，捕获组保留标题 |
grep | 测试报告判定提取 | pattern="^### 判定" 只取第一行 |
ls / Glob | 标记文件扫描 | status/*.done / status/*.pass |
mkdir | 初始化目录结构 | status/ / reports/ |
2.3 文件体系
| 文件 | 生产者 | 消费者 | 主Agent权限 |
|---|---|---|---|
plan.md | PLAN | DO, CHECK, MASTER | 只读状态行 |
guide.md | PLAN | DO, CHECK | 不读 |
lessons.md | PLAN→DO | DO, PLAN | 不读 |
log.md | MASTER | MASTER | 读写 |
reports/{单元}-{维度}.md | CHECK | DO(全读), MASTER(判定行) | Grep 判定行 |
status/{单元}.done | DO | MASTER | Glob 文件名 |
status/{单元}-{维度}.pass | CHECK | MASTER, DO | Glob 文件名 / DO删除 |
| 主产物 | DO | CHECK, DO | 不读 |
2.4 角色体系
| 角色 | 引用名 | 模型建议 | 工具权限 | 上下文策略 |
|---|---|---|---|---|
| 主调度Agent | MASTER | Opus | Bash, Glob, Grep, Agent | 持久会话 |
| 计划Agent | {PLAN} | Opus/Sonnet | Read, Write, Bash, Glob, Grep | 独立窗口，每次新建 |
| 执行Agent | {DO} | Sonnet | Read, Edit, Write, Bash, Glob, Grep | 独立窗口，同批 resume 复用 |
| 验证Agent | {CHECK} | Haiku | Read, Write, Glob, Grep | Phase 0新建 / Phase 2 resume |
2.5 设计模式
| 模式 | 应用位置 | 说明 |
|---|---|---|
| 编排者-执行者分离 | MASTER vs PLAN/DO/CHECK | 主Agent只调不干，全权委托 |
| 上下文隔离 | 绝对禁止清单 | 主Agent不Read任何子Agent产出 |
| 乐观批处理 | Phase 2 BATCH_SIZE | 批量开发+批量测试，减少调度轮次 |
| 重试循环 | Phase 0/2 修正循环 | 最多3轮，每轮 resume 而非新建 |
| 检查点 | .done / .pass | 落盘标记，支撑断点续跑 |
| 乐观并发 | Phase 2 CHECK修正轮 | 已有ID后并行resume，上限由PLAN设定 |
| 串行取号 | Phase 2 CHECK首轮 | 逐个前台阻塞，防竞态 |
| 兜底策略 | Step 4 sed | 无DO可用时主Agent机械替换状态标记 |
3. 架构详解
3.1 整体流程
INPUT_PATH │ ▼Phase 0: 计划审查（PLAN → CHECK ⇄ 修正≤3轮） │ ├─ PLAN: 读素材 → 出 plan.md + guide.md + 主产物骨架 + lessons.md + [PARAMS] │ ├─ CHECK: 审计划（任务分解/执行顺序/认知目标/格式合规/标记唯一性） │ └─ 修正: resume PLAN 修 plan/guide → 新建 CHECK 重审 │ ▼Phase 1: 计划确认 │ └─ MASTER 读 plan.md 状态行，使用 [PARAMS] 中的 BATCH_SIZE / 维度 / 并发上限 │ ▼Phase 2: 批量开发循环（逐批） │ ├─ Step 1: DO(后台) → 查重→追加→写.done → MASTER Glob汇总 │ ├─ Step 2: CHECK逐个前台(串行取ID) → 写报告+写.pass │ ├─ Step 3: FAIL? → resume DO修+删.pass+更新lessons → CHECK重测全批 │ │ 循环≤3轮 → 全PASS: DO改plan.md✅ / 仍FAIL: sed改⚠️ │ └─ Step 4: 首次全PASS兜底 → sed改✅ │ ▼Phase 3: 收尾统计 → log.md3.2 中断恢复链路
MASTER 重启 │ ├─ 1. Glob status/*.done → 哪些单元已写入主产物 ├─ 2. Glob status/*.pass → 哪些单元-维度已通过测试 ├─ 3. Read plan.md 状态行 → 交叉校验 │ ├─ .done✅ + .pass完整 → 跳过（已完成） ├─ .done✅ + .pass不全 → 从缺失维度重测 ├─ .done❌ → 从该单元重新开发 │ └─ DO_ID/CHECK_ID 全部失效 → 强制重启（不复用 resume）3.3 Agent ID 生命周期
Step 1: 启动 DO(后台) → 等待完成 → find + 重试(2s/3s/4s) → 写入 log.mdStep 2: 启动 CHECK_1(前台) → 完成 → 取ID_1 启动 CHECK_2(前台) → 完成 → 取ID_2 ...Step 3: resume DO_ID(修) → resume CHECK_ID(重测，可并发)Step 4: resume DO_ID(改状态) 或 sed下一批: 所有 ID 失效，重新获取4. 工程特性
4.1 竞态保护
- 首轮CHECK逐个前台阻塞启动，完成一个取一个ID再启下一个
- find 使用
-newer log.md过滤其他项目历史残留 - find 无结果时启用3次递增间隔重试（2s/3s/4s）
4.2 防重复追加
- DO 追加前按 guide.md 定义的标记格式 Grep 主产物，已存在则跳过
- guide.md 标记格式（如
<!-- UNIT_MARKER:u01 -->）由 Phase 0 作为最高优先级审查项校验
4.3 防状态污染
- Step 3 DO修正环节严禁修改 plan.md
- plan.md ✅ 只在重测全部 PASS 之后才写入
- DO修正时删除受影响单元的 .pass 文件，确保恢复时重测
4.4 解析鲁棒性
- CHECK 返回使用
|||分隔符（非逗号/换行），主Agent按分隔符切割 - PLAN 返回使用
[PARAMS]标记行，主Agent正则精确提取 - 测试报告写入规定目录+规定命名（
reports/{单元}-{维度}.md），Grep 判定行做二次校验
4.5 上下文保护
- 主Agent永远只用 Grep/Glob/Bash，绝不用 Read 读子Agent产出
- 后台通知只回复”已确认”，不复述内容
- Agent ID 立即写入 log，不依赖记忆
sed仅用于元数据标记替换，不加载文件进入上下文
5. 性能模型
| 指标 | 估算 |
|---|---|
| 主Agent单批调度开销 | ~500-1000 tokens（路径传递+判定解析+日志写入） |
| CHECK 单维度测试延迟 | 30-90s（Haiku，前台阻塞） |
| DO 单批开发延迟 | 2-5min（Sonnet，后台，与单元数正比） |
| 修正轮额外开销 | DO修 ~1-2min + CHECK重测 ~30-90s |
| ID 获取重试上限 | 9s（2+3+4s，3次全失败则暂停） |
| 中断恢复时间 | <30s（Glob扫描+.done/.pass交叉校验） |
6. 适用场景与局限
适用：
- 复杂任务需分解为独立单元逐批开发
- 主Agent上下文预算紧张，需要严格隔离
- 需要N维质量验证和修正闭环
- 运行环境不稳定，需要中断恢复
不适用：
- 单次简单任务（杀鸡用牛刀）
- 子Agent能力边界不清晰
- 任务间强依赖、无法批处理
7. 版本演进
| 版本 | 日期 | 核心变更 |
|---|---|---|
| v1.0（通用版） | 2026-05-02 | 抽离场景名词，PLAN/DO/CHECK角色槽，新增Phase 0计划审查+中断恢复，N维验证 |
| v1.1.0 | 2026-05-02 | 修复竞态/时序/解析等11项缺陷，引入.done/.pass标记文件体系，重试机制，状态更新链路优化 |
8. 已知问题
问题：前端生成的视觉效果不理想——说白了就是不好看。
目前已定位到 4 个原因：
-
增量拼装与视觉设计天然冲突 每个 DO 只看到自己负责的那一小块需求，从头到尾没有任何一个角色看过全貌。各自做对，拼起来不对。
-
CHECK 的验证维度偏机械合规 当前三维度（学术规范、信息传达、视觉一致性）验的是”有没有 3 条虚线""中文标签是否存在""颜色是不是指定色值”——不是”这张图放在学术论文里好不好看”。一个通过全部测试的图，技术上合规，但依然可以很丑。
-
缺少整体审美的验证维度 学术图表真正重要的是比例、留白、层次、信息节奏。这些东西在当前体系里三处缺席：plan.md 的备注断言里没有、CHECK 的三维度里没有、guide.md 的认知目标里也没有。
-
PLAN 骨架没有约束”好不好看” PLAN 设计了 CSS Design System（配色、字体、间距）和单元拆分，但没有定义”最终组装完应该是什么样”的整体蓝图。每批 DO 对着自己的验收标准做完就交差了，没人对最终视觉效果负责。
总结：这个系统擅长”做对”，不擅长”做好”。
“对”是离散可测的断言，“好”是整体感知判断。当前 CHECK 没有审美的维度，此为根本原因
解决方案待选项
-
增加Agent种类 由PLAN来判断这是什么项目，前端还是后端，如果是前端就在流程中添加一个美化检查子Agent来进行修正
-
修改现有子Agent CHECK的维度名就是检查方向，PLAN 在 guide.md 里定义每个维度检查什么，CHECK 照章办事
-
添加Skill 前端项目给 DO 绑一个”前端设计规范”skill，里面写：栅格系统、配色比例、留白节奏、组件间距基准。DO 执行前三问时对照 skill 作答 后端项目给 DO 绑”代码规范”skill 学术图表给 CHECK 绑”图表设计评审”skill
-
利用lessons.md进行修正 本架构里添加了lessons.md经验库，LLM会自动把项目中踩的坑或者项目经验写入lessons.md，在 DO 提示词执行前三问里加一句：“读 lessons.md 后，大声说出本单元需要警惕的经验条目”，强制 LLM 分配注意力
——THE END——
如果这篇文章对你有帮助，欢迎分享给更多人！
部分信息可能已经过时