6a2632da70
将 Clover 从上层产品包旧仓库中独立出来,建立专属版本控制。 当前状态=纵切片端到端已打通(登录→选品→出文出图→审核→下载包), M1文案质量去套路化已验收。此提交作为后续按核销清单逐条修复的基线。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
175 lines
11 KiB
Markdown
175 lines
11 KiB
Markdown
# 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）
|
||
|
||
```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 审核全部开工前流程，再开工。
|