beige/Agent团队与循环任务设计.md

Clover Agent 团队 + 循环任务设计（开工质量把关）

用途：开工前把"agent 怎么组队、循环任务怎么保质量"定死，作为 board 4 启动包 + board 7 编排的地基。 决策人：倩倩姐拍板机制，北哥定内容质量标准。

0. 三方源材料对照（逐字读完）

来源	给了什么	对 Clover 的用法
官方《Agent Team 详解》17页	架构原理 + 4 协作模式 + Hooks 门禁 + 成本控制	团队拓扑 + 主协作模式
官方《项目治理指南》41页	四级治理 + 质量四件套 + 全套可抄模板	Clover 定级 L3 + 模板直接套
ralph-loop 源码	循环任务最小实现(4Phase+状态机+重试)	循环任务骨架
逆向项目档案(真跑过的6角色team)	PSR-L + 撞墙血泪 + 角色卡三段式	循环升级 + 角色卡规范
北哥会议录音	goal模式 + 闭环架构 + 判断力锚架构	循环任务的"魂"
官网V1经验萃取(自产)	6保留 + 6坑	规避坑 + 继承机制

1. 把关结论速览

源材料读完，对 Clover 最关键的迭代是 3 条：

1. 循环任务从 ralph-loop 的"测试即真理"升级成北哥的"闭环架构"——ralph-loop 只认 exit_code（能跑就过），北哥要"调研→生成→验证→校准→不过返工"，且质量过关的最终拍板权在人不在机器。
2. agent team 主模式定为"全栈并行·契约优先"——integration-lead 先冻结 OpenAPI 契约，前后端再并行开工，堵住官网 V1"前端假设字段、联调爆炸"的坑。
3. 启动包必须提前备好，启动日只 validate 不 generate——官网 V1 最大的坑是脚手架启动当天临时造、第一天下午才能安全开发；这次源材料给了全套可抄模板，彻底规避。

定级：Clover 属治理指南的 L3 协作级（5-15 人体量、多模块、有质量要求），继承 L3 全套（质量四件套 + Agent Team + CI）。

两个已拍板决策：

• 循环任务质量判断 = 机器过滤 + 北哥抽检两阶段
• 团队规模 = 精简 5 角色

2. 循环任务设计（loop task）

ralph-loop 骨架能用，但直接套到 Clover 有 3 个质量漏洞，补 3 道闸。

2.1 三个漏洞 → 三道闸

ralph-loop 原版	Clover 场景漏洞	补的闸
exit_code=0 就算过	文案能生成≠不同质化；图能出≠不跑偏	验收两层：机器先过滤(违禁词/五维评分≥90/去重) → 北哥人工抽检定标准
4 Phase 无"调研/校准"	上来就生成，不先看清全流程	补成北哥闭环：调研→生成→验证→校准→返工
max_retries=3 硬切	撞墙3次还在原地换参数	逆向铁律：撞墙2次必 Pivot(换层不换参)，对齐 CLAUDE.md 失败2次规则

核心一句："Memory is Poison, Tests are Cure"是对的，但 Clover 的 Test 不止单元测试，还有北哥的眼睛——落在架构方案 v0.3 基石 D"人工判断标准落点"和飞轮四点验收。

2.2 Clover 闭环六阶段（升级版 ralph-loop）

P0 调研   → 读架构方案v0.3 + PRD + 扒包落盘，确认本任务边界（对应北哥"先调研"）
P1 约束   → 冻结 task_spec：输入/输出/验证命令/期望exit_code/质量阈值
P2 生成   → 写代码 + 写验证脚本（验证脚本必须含断言、返回exit_code）
P3 验证   → 跑验证脚本：机器层（lint/test/违禁词/五维≥90/去重）
P4 校准   → ⭐新增：机器过的样本，按维度比对北哥标准；同质化/跑偏单独标记
P5 闭环   → 通过→归档+结晶；不过→分析根因，撞墙2次换层(Pivot)，超限暂停请人介入

P4 校准是 ralph-loop 没有的，专治"分数高但实际烂"。校准产出抽检样本包交北哥，北哥的判断回写成质量标准（喂飞轮）。

2.3 状态机（沿用 ralph-loop 的 .clover-loop-state.json）

{
  "task_id": "TASK-xxx", "current_phase": 2, "attempts": 1,
  "max_retries_per_layer": 2,          // 单层撞墙上限2次→Pivot
  "machine_gate": {"lint":"pass","test":"pass","banned_word":"pass","score":92,"dedup":"pass"},
  "human_review": {"status":"pending","sampled":0,"approved":0,"rejected":0},
  "status": "in_progress",             // in_progress / machine_passed / human_passed / pivoted / blocked
  "pivots": [], "logs": []
}

关键差异：状态从 ralph-loop 的 2 态（completed/max_retries_exceeded）扩成 5 态，machine_passed ≠ human_passed——机器过只是进抽检队列，北哥点头才是真过。这就是"质量过关不是能下载"的落地。

2.4 触发与人介入

• 单层（同一个错误层）连续失败 2 次 → 不再换参数，强制 Pivot 换思路/换层，记 pivots[]。
• Pivot 后仍不过 或 北哥抽检打回 → status=blocked，停循环，结构化报告请北哥/倩倩姐介入。
• 北哥不耐烦/连续否决同方向 = 路径选错了层的信号（逆向项目血泪），立即 Pivot 不要再调参。

3. Agent 团队编排（agent team）

3.1 拓扑：Orchestrator-Workers，精简 5 角色

                  ┌─────────────┐
                  │ Lead/集成    │  冻结契约+全局状态+最终验收（兼 integration-lead）
                  └──────┬──────┘
        ┌────────────────┼────────────────┐
   ┌────▼────┐     ┌─────▼─────┐     ┌────▼─────┐
   │ 后端 BE  │     │ 前端 FE   │     │ 审查 QA   │  审查兼测试运行
   └─────────┘     └───────────┘     └──────────┘
        └────────────────┬────────────────┘
                  ┌──────▼──────┐
                  │ AI引擎 AIE   │  文案/生图/去水印核心（产品命脉，单列）
                  └─────────────┘

砍掉官网 V1 的独立"文档 agent"，文档并入各 agent 的 standup 自我披露。AI 引擎从后端拆出来单列——它是 Clover 的命脉（文案内核/分镜/去水印），值得一个专人。

3.2 主协作模式：全栈并行·契约优先（Contract First）

1. Lead 先冻结接口契约（OpenAPI + TS 类型），契约里 type:object 不许留空（官网 V1 坑4）。
2. 契约冻结后，BE / FE / AIE 并行开工，互相不等。
3. integration-lead（=Lead）开工当天做契约偏离全量扫描，产出结构化偏离清单（官网 V1 保留3）。

3.3 审查模式：异构对抗（仅用于关键决策点）

PRD 审查、安全审计、架构选型用对抗三角：Builder 出方案 → Critic（魔鬼代言人）找漏洞 → Synthesizer 综合。日常开发不用，避免 token 浪费。

3.4 成本控制（混合模型）

角色/任务	模型	理由
Lead / AI引擎核心 / 架构决策	opus	命脉，要最强推理
后端 / 前端 日常编码	sonnet	平衡
QA 跑测试/分析日志 / 违禁词/评分	haiku	量大、逻辑简单、省钱

完成即关闭（Aggressive Cleanup）：agent 干完任务立即 shutdown，闲置 agent 维持上下文也烧 token。

3.5 质量门禁（继承 + 叠加）

• Stop Hook 强制跑测试（官网 V1 保留5）：不允许"我觉得对了"就算完。
• 但软件测试过 ≠ 内容质量过：循环任务的内容产出叠加 §2 的机器过滤 + 北哥抽检。

4. 角色卡规范（5 角色）

吸收逆向项目比官网 V1 更狠的"三段式 + 反模式"，每张角色卡含 5 块：

1. 读什么（必读文档，精确到文件路径）
2. 写什么（产出物边界）
3. 依赖谁（上游契约 / 下游消费方）
4. 强制 + 禁止（禁止项极具体，如"❌ api 层不能 import 基础设施层"而非"别写坏代码"）
5. standup 自我披露（每天写：文件清单/TODO/已知bug/契约不一致处）

角色	读	写	依赖	模型
Lead/集成	架构方案v0.3 + 3份PRD + CLAUDE.md	契约冻结 + 偏离清单 + 最终验收	全员 standup	opus
后端 BE	PRD-后端 + rules/api.md + rules/db.md	API + 队列 + 存档 + 多租户	Lead契约	sonnet
前端 FE	PRD-前端 + 前端交互设计.md + rules/frontend.md	5屏 + 飞轮隐形 + 异步生图电影	Lead契约	sonnet
AI引擎 AIE	产品包扒包落盘 + banana扒包 + PRD-后端Ch4	文案双轨/生图edits/去水印/评分	Lead契约	opus
审查 QA	全员产出 + 验证脚本	跑测试 + 契约符合 + 清理临时文件	全员代码	haiku

5. 反模式清单（agent 必须 NOT 做）

吸收逆向项目的"反模式10条"思路，结合 Clover 红线：

1. ❌ 不动 banana / 产品包源目录（只读复制，不 cd 进去 Edit/Write）——CLAUDE.md 铁律。
2. ❌ 不边盖边修：Clover 是全新独立项目，不在 banana 上建。
3. ❌ 契约 type:object 不许留空——冻结前所有嵌套对象一级子字段必须定义（官网V1坑4）。
4. ❌ service 错误不许静默吞——至少打 error log（官网V1坑3）。
5. ❌ 同一层撞墙超 2 次还在调参——必须 Pivot 换层（逆向血泪 + CLAUDE.md失败2次）。
6. ❌ 前端不展示 Token 余额 / 不做积分页（CLAUDE.md前端红线）。
7. ❌ 不自动发布到小红书——只到"确认预览"，发布是人的动作。
8. ❌ 内容"评分高"不等于"质量过关"——必须过北哥抽检才算 human_passed。
9. ❌ 临时调试文件不许留——带 _tmp 后缀，QA agent 收尾清理（官网V1坑5）。
10. ❌ P0 模块不许无 plan 就开工——integration-lead 检查项，standup 报"未plan的P0"（官网V1坑6）。
11. ❌ 新建文件不超 100 行，单次编辑不超 100 行（CLAUDE.md 约束）。
12. ❌ key 不进 Celery、不落盘明文——Fernet 加密只传 task_id（架构方案基石B）。

6. 落到 board 的下一步

本文档把"怎么组队、循环怎么保质量"定死了，接下来：

• board 4 启动包（启动前一天备好，启动日只 validate）：
  • 5 张角色卡 .md（按 §4 规范展开）
  • 契约 OpenAPI 初稿（Lead 冻结用）
  • CLAUDE.md 三层（全局/项目/模块）+ rules/(api/frontend/db)
  • Hooks 配置（危险命令拦截/自动lint/Stop测试/敏感文件保护，模板已从源材料抄到）
  • 循环任务 SKILL（按 §2 六阶段，改造 ralph-loop）+ state_manager
  • 种子数据（品类/角度槽位/违禁词三级表）
• board 5 执行约束：把 §5 反模式 + 北哥抽检 SOP 固化。
• board 6 验收清单：三道验收线（内部1A生产链+1B飞轮四点 → 北哥质量过关 → 上线）。
• board 7 Agent 编排：把 §3 拓扑 + 协作模式写成可执行的开工 prompt（goal 模式）。

全部作业包完成后，按倩倩姐的常规要求：另起一个独立 AI 审核全部开工前流程，再开工。