baseline: Clover 独立仓库首次基线提交

将 Clover 从上层产品包旧仓库中独立出来,建立专属版本控制。
当前状态=纵切片端到端已打通(登录→选品→出文出图→审核→下载包),
M1文案质量去套路化已验收。此提交作为后续按核销清单逐条修复的基线。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

启动包/.claude/rules/api.md

@@ -0,0 +1,42 @@
+---
+paths:
+  - "src/api/**"
+  - "src/routers/**"
+  - "src/services/**"
+---
+
+# API 层开发规则（Clover 后端）
+
+> 承接架构方案v0.3 基石 + API契约.md，冲突以架构方案为准。
+
+## 路由规范
+- RESTful 命名：资源用名词复数（/tasks, /products, /api-keys）
+- 版本前缀：/api/v1/
+- 控制器只做：参数校验 → 调 service → 格式化响应，**不含业务逻辑**
+
+## 响应格式（统一包络）
+- 成功：`{ "code": 0, "data": {...} }`
+- 失败：`{ "code": <错误码>, "message": "用户可读信息" }`
+- HTTP 状态码与业务 code 分离（见契约§0七类错误码）
+
+## 安全（基石B/C）
+- 所有用户输入必须校验（类型、长度、范围）
+- SQL 查询使用参数化，禁止字符串拼接
+- **API Key 绝不进 Celery 参数**，只传 task_id；worker 内查库→Fernet解密→局部变量
+- FERNET_KEY 走环境变量，绝不进代码库；解密不落盘、不打日志
+- 敏感操作记审计日志（ai_call_logs）
+
+## 多租户隔离（红线）
+- 所有查询强制带 workspace_id 条件
+- 写操作 + 切 workspace 必须查 workspace_members 校验权限
+- workspace_id / product_id 从 JWT + 上下文自动带，前端不传（防越权）
+- 所有 workspace 相关 Repo 继承 base_workspace_repo
+
+## 错误处理（官网V1坑3）
+- service 错误不许静默吞，至少打 error log
+- AI/token站调用失败归因到个人 key（错误码50002）
+- DB 枚举约束要有对应代码侧常量文件
+
+## 业务参数不写死（基石A）
+- 禁止出现品类/数量/角度任何枚举常量
+- "看起来像枚举"的业务概念 → 做成数据不做成代码

启动包/.claude/rules/db.md

@@ -0,0 +1,49 @@
+---
+paths:
+  - "src/models/**"
+  - "alembic/**"
+  - "migrations/**"
+---
+
+# 数据库规则（Clover · MySQL + Alembic）
+
+> 承接架构方案v0.3 第三章（16表）。一期建14张，matrix_accounts/preference_profile 二期预留。
+
+## 迁移
+- 每次 schema 变更创建迁移文件，不手动改数据库
+- 迁移文件不可修改已提交的，只能新增
+- 迁移必须包含 up 和 down
+- 按序：001(banana搬3张) → 002(多租户基础) → 003(业务7张) → 004(飞轮)
+
+## 查询
+- 禁止 SELECT *，明确列出字段
+- 大表查询必须有索引支撑，新增查询模式时同步加索引
+- N+1 问题：关联查询用 JOIN 或批量加载
+- 飞轮聚合走 MySQL JOIN（MongoDB 只存 AI debug trace，业务不依赖）
+
+## 命名
+- 表名：snake_case 复数（users, generation_tasks, preference_events）
+- 字段名：snake_case（created_at, workspace_id）
+- 索引名：idx_表名_字段名
+
+## 关键约束（架构方案）
+- 任务主键：自增 BIGINT + mongo_trace_id VARCHAR(24)
+- user_api_keys：UNIQUE(user_id, workspace_id, provider)
+- 所有业务表必须有 workspace_id（多租户逻辑隔离）
+- preference_events 必须有 workspace_id + product_id（跨公司隔离+按产品分开学）
+
+## 状态机（generation_tasks.status）
+pending → generating → pending_selection → pending_review → approved/rejected → archived
+- 打回后回到 pending_selection
+- 非法流转返错误码 40901
+
+## 字段红线
+- API Key 字段：encrypted_key（Fernet），**不存 url 字段**（token站固定自家站）
+- users 表：删除 banana 的 credits 字段
+- eval_score：留 NULL（不接 banana 假评分）
+- data_ownership：client_data / platform_asset（洞7分层归属）
+- banned_words.level：auto_fix / soft_warn / hard_block（三级）
+
+## 枚举约束
+- DB 枚举约束要有对应代码侧常量文件（消除三套命名打架）
+- 品类（products.category）是纯数据字段，禁止任何品类枚举常量

启动包/.claude/rules/frontend.md

@@ -0,0 +1,46 @@
+---
+paths:
+  - "src/components/**"
+  - "src/app/**"
+  - "src/pages/**"
+  - "src/stores/**"
+---
+
+# 前端开发规则（Clover · Next.js）
+
+> 承接 前端交互设计.md（5屏金标准）+ API契约.md §3 DTO。
+
+## 组件规范
+- 单一职责：一个组件只做一件事
+- Props 必须定义类型（TypeScript interface）
+- 避免 prop drilling 超 3 层，用 Context 或状态管理
+
+## DTO 对接（堵官网V1坑4）
+- 所有 DTO 字段严格按 API契约§3，**不许自己假设嵌套结构**
+- 后端响应与契约不符立即报 Lead，不私下适配
+- workspace_id / product_id 不在前端传
+
+## SSE（异步生图电影）
+- 按 event_seq 去重，断线重连补发历史事件
+- 11类事件按契约§2渲染：0/N进度 + 谁好谁先冒 + 单批失败重试 + 能离开
+- flywheel_injected 事件 → 显"本次已注入：最近偏好/打回原因"
+
+## 样式
+- 用 CSS Modules 或 Tailwind，不用全局样式
+- 响应断点统一：sm(640) md(768) lg(1024) xl(1280)
+- 颜色/间距用 design token，不硬编码
+
+## 可访问性
+- 交互元素必须有 aria-label
+- 图片必须有 alt 文本
+- 键盘导航可用
+
+## 红线（CLAUDE.md）
+- ❌ 不展示 Token 余额、不做积分页（key 去中转站后台看）
+- ❌ 飞轮隐形：无"训练AI"按钮，只在生成时显注入提示
+- ❌ 不做"自动发布到小红书"——只到确认预览
+- ❌ 不做移动端（一期）
+
+## 状态管理
+- 4 个 Store：任务 / 候选 / 审核 / 全局
+- 异步态用骨架屏，错误态对接契约§0错误码

启动包/.claude/settings.json

@@ -0,0 +1,53 @@
+{
+  "//说明": "Clover 启动包 Hooks 配置。四道质量门禁，承接治理指南§9.3模板。退出码 0=放行 2=阻止 其他非零=脚本错误。",
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "//门禁1": "危险命令拦截",
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cmd=$(jq -r '.tool_input.command // empty'); if echo \"$cmd\" | grep -qE 'rm -rf|DROP TABLE|--force|--no-verify|reset --hard|git push.*main|git push.*master'; then echo \"危险命令被拦截: $cmd\" >&2; exit 2; fi; exit 0"
+          }
+        ]
+      },
+      {
+        "//门禁2": "敏感文件保护 + 源目录只读保护",
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "file=$(jq -r '.tool_input.file_path // empty'); if echo \"$file\" | grep -qE '\\.env|\\.key|credentials|secrets|FERNET'; then echo \"禁止编辑敏感文件: $file\" >&2; exit 2; fi; if echo \"$file\" | grep -qE 'O2中间件平台/banana|产品包/worker|万牛会L1准备/worker'; then echo \"源目录只读，禁止修改(铁律): $file\" >&2; exit 2; fi; exit 0"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "//门禁3": "自动 lint",
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "file=$(jq -r '.tool_input.file_path // empty'); case \"$file\" in *.ts|*.tsx|*.js|*.jsx) npx eslint --fix \"$file\" 2>&1 || true;; *.py) ruff check --fix \"$file\" 2>&1 || true;; esac; exit 0"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "//门禁4": "测试验证 + 临时文件提醒",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'echo \"请确认是否已运行测试并通过(软件测试过≠内容质量过,内容需北哥抽检)。\" >&2; tmp=$(find . -name \"*_tmp*\" 2>/dev/null | head -5); if [ -n \"$tmp\" ]; then echo \"发现临时文件待清理:\" >&2; echo \"$tmp\" >&2; fi; exit 0'"
+          }
+        ]
+      }
+    ]
+  }
+}

启动包/.claude/skills/clover-loop/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: clover-loop
+version: 1.0.0
+description: |
+  Clover 内容生产闭环开发 SKILL（改造自 ralph-loop）。
+  Memory is Poison, Tests are Cure —— 但 Clover 的 Test 不止单元测试，还有北哥的眼睛。
+  六阶段闭环：调研→约束→生成→验证→校准→闭环。质量过关=机器过滤+北哥抽检两阶段。
+triggers:
+  - clover-loop
+  - 内容闭环
+  - 生产闭环
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - AskUserQuestion
+---
+
+# Clover Loop SKILL
+
+> 核心：机器层(machine_passed)只是进抽检队列，北哥点头(human_passed)才是真过关。
+
+## 六阶段
+
+### P0 调研（ralph-loop 没有，北哥"先调研"）
+读架构方案v0.3 + 对应 PRD + 扒包落盘，确认本任务边界。
+不充分就进 P2 = 在错误的层做对的事（PSR-L 教训）。
+
+### P1 约束
+冻结 task_spec：输入/输出/验证命令/期望exit_code/质量阈值。
+`python scripts/loop_state.py create <task_id>`
+
+### P2 生成
+写代码 + 写验证脚本（必须含断言、返回exit_code）。
+`python scripts/loop_state.py advance`
+
+### P3 验证（机器层）
+跑机器门禁：lint / test / 违禁词 / 五维≥90 / 去重。
+全过 → status=machine_passed → 进 P4；不过 → 记失败，回 P2。
+
+### P4 校准（ralph-loop 没有，专治"分高但烂"）
+机器过的内容样本，按维度比对北哥标准；同质化/跑偏单独标记。
+产出**抽检样本包**交北哥 → 北哥判断回写质量标准（喂飞轮）。
+
+### P5 闭环
+- 北哥抽检通过 → status=human_passed → 归档 + 结晶
+- 北哥打回 / 验证不过 → 分析根因
+  - 同层撞墙 **2 次** → 强制 Pivot（换层不换参），记 pivots[]
+  - Pivot 后仍不过 / 北哥连续否决同方向 → status=blocked，停循环请人介入
+
+## 状态机（.clover-loop-state.json）
+5 态：in_progress / machine_passed / human_passed / pivoted / blocked
+关键：machine_passed ≠ human_passed
+
+## 命令
+| 命令 | 功能 |
+|------|------|
+| /clover-loop | 启动六阶段闭环 |
+| /clover-loop:status | 查当前状态 |
+| /clover-loop:pivot | 手动触发换层 |
+
+## 铁律
+- 撞墙 2 次必 Pivot（对齐 CLAUDE.md 失败2次）
+- 北哥不耐烦/连续否决 = 路径选错层的信号，立即 Pivot 不调参
+- 软件测试过 ≠ 内容质量过

启动包/.claude/skills/clover-loop/scripts/loop_state.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""
+Clover Loop State Manager（改造自 ralph-loop state_manager）
+六阶段 + 5态 + 机器/人工双层验收 + Pivot 追踪。
+"""
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+STATE_FILE = ".clover-loop-state.json"
+PHASES = {"0": "调研", "1": "约束", "2": "生成", "3": "验证", "4": "校准", "5": "闭环"}
+
+
+def _path(work_dir=None):
+    base = Path(work_dir) if work_dir else Path.cwd()
+    return base / STATE_FILE
+
+
+def load(work_dir=None):
+    p = _path(work_dir)
+    return json.load(open(p, encoding="utf-8")) if p.exists() else None
+
+
+def save(state, work_dir=None):
+    state["updated_at"] = datetime.now().isoformat()
+    json.dump(state, open(_path(work_dir), "w", encoding="utf-8"),
+              indent=2, ensure_ascii=False)
+
+
+def create(task_id, work_dir=None):
+    state = {
+        "task_id": task_id,
+        "created_at": datetime.now().isoformat(),
+        "updated_at": datetime.now().isoformat(),
+        "current_phase": 0,
+        "max_retries_per_layer": 2,   # 单层撞墙2次→Pivot
+        "machine_gate": {"lint": None, "test": None, "banned_word": None,
+                         "score": None, "dedup": None},
+        "human_review": {"status": "pending", "sampled": 0,
+                         "approved": 0, "rejected": 0},
+        "status": "in_progress",      # in_progress/machine_passed/human_passed/pivoted/blocked
+        "layer_attempts": {},         # {层名: 失败次数}
+        "pivots": [],
+        "logs": [],
+    }
+    save(state, work_dir)
+    return state
+
+
+def advance(state, work_dir=None):
+    cur = state["current_phase"]
+    if cur < 5:
+        state["current_phase"] = cur + 1
+    save(state, work_dir)
+    return state
+
+
+def machine_gate(state, key, result, work_dir=None):
+    """记录机器门禁单项结果。全过则置 machine_passed。"""
+    state["machine_gate"][key] = result
+    g = state["machine_gate"]
+    passed = all(v in ("pass", True) or (isinstance(v, (int, float)) and v >= 90)
+                 for v in g.values() if v is not None)
+    if passed and all(v is not None for v in g.values()):
+        state["status"] = "machine_passed"
+    save(state, work_dir)
+    return state
+
+
+def record_fail(state, layer, error=None, work_dir=None):
+    """记录某层失败。同层2次→强制Pivot。"""
+    state["layer_attempts"][layer] = state["layer_attempts"].get(layer, 0) + 1
+    state["logs"].append({"ts": datetime.now().isoformat(),
+                          "layer": layer, "error": error})
+    if state["layer_attempts"][layer] >= state["max_retries_per_layer"]:
+        state["status"] = "pivoted"
+        state["pivots"].append({"layer": layer, "ts": datetime.now().isoformat(),
+                                "reason": f"{layer}层撞墙{state['layer_attempts'][layer]}次"})
+    save(state, work_dir)
+    return state
+
+
+def human_review(state, action, work_dir=None):
+    """北哥抽检：approve/reject。approve累计达标→human_passed。"""
+    hr = state["human_review"]
+    hr["sampled"] += 1
+    if action == "approve":
+        hr["approved"] += 1
+        hr["status"] = "approved"
+        state["status"] = "human_passed"
+    elif action == "reject":
+        hr["rejected"] += 1
+        hr["status"] = "rejected"
+        state["status"] = "blocked"   # 打回=停循环请人介入
+    save(state, work_dir)
+    return state
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("用法: loop_state.py <create|load|advance|gate|fail|review> [args]")
+        print("  create <task_id> / advance / gate <key> <result>")
+        print("  fail <layer> [error] / review <approve|reject>")
+        sys.exit(1)
+    cmd = sys.argv[1]
+    if cmd == "create":
+        print(json.dumps(create(sys.argv[2]), ensure_ascii=False, indent=2))
+    elif cmd == "load":
+        s = load()
+        print(json.dumps(s, ensure_ascii=False, indent=2) if s else "无状态")
+    elif cmd == "advance":
+        s = load()
+        if s:
+            advance(s)
+            print(f"进入 P{s['current_phase']} {PHASES[str(s['current_phase'])]}")
+    elif cmd == "gate":
+        s = load()
+        if s:
+            key, raw = sys.argv[2], sys.argv[3]
+            val = float(raw) if raw.replace(".", "").isdigit() else raw
+            machine_gate(s, key, val)
+            print(f"门禁 {key}={val}, status={s['status']}")
+    elif cmd == "fail":
+        s = load()
+        if s:
+            record_fail(s, sys.argv[2], sys.argv[3] if len(sys.argv) > 3 else None)
+            print(f"{sys.argv[2]}层失败{s['layer_attempts'][sys.argv[2]]}次, status={s['status']}")
+    elif cmd == "review":
+        s = load()
+        if s:
+            human_review(s, sys.argv[2])
+            print(f"抽检{sys.argv[2]}, status={s['status']}")

启动包/API契约.md

@@ -0,0 +1,277 @@
+# Clover API 契约（OpenAPI 初稿 · Lead 冻结用）
+
+> 用途：开工前由 Lead/集成 冻结此契约，前后端按此并行开工，杜绝"前端假设字段、联调爆炸"。
+> 铁律：所有 `type: object` 不许留空——冻结前嵌套对象一级子字段必须定义（官网V1坑4）。
+> 来源：承接架构方案v0.3（golden standard）端点 + 16表字段，不重复定义，冲突以架构方案为准。
+> 范围：一期 1A 生产链 + 1B 飞轮。二期端点（注册/矩阵号/管理后台）标 [二期] 不冻结。
+
+## 0. 全局约定
+
+### 认证
+- 除登录/注册外，所有请求头带 `Authorization: Bearer <JWT>`。
+- JWT 载荷：`user_id` / `current_workspace_id` / `role`（HS256 签名，每请求验签）。
+- 写操作 + 切 workspace 必须查 workspace_members 校验权限（读操作可信 JWT 加速）。
+
+### 统一响应包络
+```
+成功：{ "code": 0, "data": {...} }
+失败：{ "code": <错误码>, "message": "用户可读信息" }
+```
+HTTP 状态码与业务 code 分离。
+
+### 错误码规范（7 类）
+| code | 含义 | HTTP |
+|------|------|------|
+| 0 | 成功 | 200 |
+| 40001 | 参数校验失败 | 400 |
+| 40101 | 未认证/JWT失效 | 401 |
+| 40301 | 无权限/越权访问 workspace | 403 |
+| 40401 | 资源不存在 | 404 |
+| 40901 | 状态机非法流转 | 409 |
+| 42201 | 业务校验失败(如未配key/违禁词硬拦截) | 422 |
+| 50001 | 服务端错误 | 500 |
+| 50002 | AI/token站调用失败(归因到个人key) | 502 |
+
+### 分页 & 限流
+- 列表统一 `?page=1&page_size=20`，返回 `{items, total, page, page_size}`。
+- 写操作与 AI 触发接口限流（防滥用），超限返 429。
+
+## 1. 端点清单（一期 1A+1B）
+
+### 认证 & 账号
+| 方法 | 路径 | 说明 | 角色 |
+|------|------|------|------|
+| POST | /api/v1/auth/login | 登录，返 JWT | 全部 |
+| GET | /api/v1/auth/me | 当前用户+workspace+role | 全部 |
+| POST | /api/v1/workspaces/switch | 切换当前 workspace（查membership） | 全部 |
+
+### API Key（只录不显余额，CLAUDE.md红线）
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /api/v1/api-keys | 列表（只显 provider + 后4位，**不显余额/用量**） |
+| POST | /api/v1/api-keys | 录入（Fernet加密存，url固定自家站不接收url字段） |
+| DELETE | /api/v1/api-keys/{id} | 删除 |
+
+### 品牌库（管理员）
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET/POST | /api/v1/products | 产品档案 CRUD（含文案角度+可调prompt+source） |
+| GET/PUT/DELETE | /api/v1/products/{id} | 单产品 |
+| GET/POST | /api/v1/products/{id}/benchmarks | 标杆笔记（截图+手填亮点为主通道） |
+| GET/POST/PUT/DELETE | /api/v1/banned-words | 违禁词库（level三级，workspace可覆盖） |
+
+### 生产链（熟手）
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | /api/v1/tasks | 发起任务（选产品+标杆+今天主题+数量），校验有无key→只推task_id入队 |
+| GET | /api/v1/tasks | 任务列表（按状态筛） |
+| GET | /api/v1/tasks/{id} | 任务详情（含候选+状态机当前态） |
+| POST | /api/v1/tasks/{id}/sse-ticket | 换取一次性 SSE ticket（JWT认证→返回60s短票，FE立即建EventSource） |
+| GET | /api/v1/tasks/{id}/stream | **SSE** 实时进度（见§2，用 ?ticket= 认证，禁止 ?token=） |
+| POST | /api/v1/tasks/{id}/text-candidates/select | 选文案（飞轮入口1，+3） |
+| POST | /api/v1/tasks/{id}/image-candidates/select | 选图（飞轮入口2，+3） |
+| POST | /api/v1/tasks/{id}/import-text | 轨B：导入外部文案直接进候选池 |
+| POST | /api/v1/tasks/{id}/regenerate | 重新生成（飞轮-1） |
+| POST | /api/v1/tasks/{id}/submit-review | 提交审核（状态→pending_review） |
+| GET | /api/v1/tasks/{id}/preference/context | 取本任务飞轮偏好上下文（最近选中样本+最近3条打回原因），供 prompt 组装；前端仅用于显示"本次已注入"摘要 |
+
+> 🔴 飞轮**只有读端点**：偏好信号(选文案/选图/通过/打回/重生成)由上方 select / approve / reject / regenerate 接口**内部**写入 `preference_events`，**不暴露独立的 POST /preference/event 给前端**（避免被当成"训练按钮"，且防伪造信号）。
+
+### 审核（组长）
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | /api/v1/review/queue | 待审队列 |
+| POST | /api/v1/review/{task_id}/approve | 通过（飞轮+5最重，状态→approved） |
+| POST | /api/v1/review/{task_id}/reject | 打回（写原因，-3，回pending_selection，原因下次注入prompt） |
+
+### 交付包
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | /api/v1/tasks/{id}/package | 生成达人素材交付包（去水印+打包） |
+| GET | /api/v1/delivery-packages/{id}/download | 下载（status: pending/ready/downloaded） |
+
+### [二期] 不冻结
+注册(手机验证码)、matrix_accounts矩阵号、管理后台用量统计、preference_profile物化。
+
+## 2. SSE 事件契约（异步生图电影 + 飞轮注入提示）
+
+`GET /api/v1/tasks/{id}/stream` 流式推送，前端据此渲染"逐帧电影"。
+断线重连时后端**补发历史事件**（修 banana 漏洞），前端按 event_seq 去重。
+
+> **🔴 SSE 认证安全红线（2026-06-08 倩倩姐拍板）**：EventSource 不支持自定义 header，
+> 故 FE 建连前先用 JWT 调 `POST /sse-ticket` 换一张一次性短票（TTL 60s，仅对该 task 有效），
+> URL 只带 `?ticket=`。ticket 用后即焚（Redis getdel），就算被日志记下也立即失效。
+> **禁止 `?token=` 直传 JWT 进 URL。**
+
+| event 类型 | data 字段（一级子字段必须全定义） | 前端用途 |
+|-----------|----------------------------------|---------|
+| task_started | `{task_id, total_text, total_image}` | 显示 0/N 进度 |
+| analyze_done | `{features:[8特征]}` | 标杆分析完成 |
+| text_progress | `{done, total}` | 文案 done/total |
+| text_candidate | `{candidate_id, angle_label, content, score}` | 单条文案冒出来 |
+| image_progress | `{done, total}` | 图 done/total |
+| image_candidate | `{candidate_id, strategy(A/B/C), url, role}` | 单张图冒出来（谁好谁先冒） |
+| flywheel_injected | `{recent_preference, reject_reasons:[最近3条]}` | UI显"本次已注入"（飞轮基石E第4点） |
+| batch_failed | `{batch, reason, retryable:bool}` | 单批失败可重试，不阻塞其他 |
+| task_done | `{task_id, status}` | 全部完成，可离开 |
+| error | `{code, message}` | 对接§0错误码 |
+| heartbeat | `{ts}` | 保活 |
+
+## 3. 关键 DTO（type:object 不许留空）
+
+### 发起任务 POST /api/v1/tasks 请求体
+```
+{
+  "product_id": 12,
+  "benchmark_ids": [3, 5],
+  "theme": "今天主题：夏日清爽控油",   // 前端交互设计的"今天主题"字段
+  "text_count": 5,                    // 用户设定，不写死(基石A)
+  "image_count": 3,
+  "track": "ai"                       // ai=轨A生成 / import=轨B导入
+}
+```
+
+### text_candidate 文案候选（含五维分，挑文案屏用）
+```
+{
+  "candidate_id": 101, "angle_label": "痛点切入", "content": "...",
+  "source": "ai",                     // ai / import
+  "score": { "title":24, "emotion":23, "selling":25, "keyword":18, "compliance":5, "total":95 },
+  "banned_word_status": "pass"        // pass / auto_fixed / soft_warn / hard_block
+}
+```
+> 五维：标题25/情绪25/买点25/关键词20/合规5，过线90（承接产品包评分引擎）。
+
+### 打回 POST /api/v1/review/{task_id}/reject 请求体
+```
+{ "reason": "标题太硬广，不像素人分享" }   // 原文存 preference_events.reason，不做AI归纳
+```
+
+### 选择类（飞轮信号）统一体
+```
+{ "candidate_id": 101 }   // 后端据登录态拿 user/workspace/product，写 preference_events
+```
+
+> 凡涉及 workspace_id / product_id 的写入，后端从 JWT + 任务上下文自动带，**前端不传**（防越权）。
+
+## 4. 补全 DTO（冻结补全，官网V1坑4）
+
+### POST /api/v1/auth/login
+请求体：
+```json
+{ "username": "string", "password": "string" }
+```
+返回 data：
+```json
+{
+  "token": "eyJ...",
+  "user": {
+    "id": 1, "username": "string", "email": "string",
+    "current_workspace_id": 1, "role": "admin|supervisor|operator"
+  }
+}
+```
+
+### GET /api/v1/auth/me 返回 data
+```json
+{
+  "id": 1, "username": "string", "email": "string",
+  "current_workspace_id": 1, "role": "admin|supervisor|operator",
+  "workspace": { "id": 1, "name": "string", "slug": "string" }
+}
+```
+
+### POST /api/v1/workspaces/switch
+请求体：`{ "workspace_id": 2 }`
+返回 data：`{ "current_workspace_id": 2, "role": "string", "token": "eyJ..." }`
+
+### GET /api/v1/api-keys 返回 items 单项
+```json
+{ "id": 1, "provider": "openai", "key_last4": "ab12", "created_at": "2026-01-01T00:00:00Z" }
+```
+注：不返回余额/用量（CLAUDE.md前端红线）。
+
+### POST /api/v1/api-keys 请求体
+```json
+{ "provider": "openai", "api_key": "sk-..." }
+```
+注：url 字段不接收，后端固定走自家站 endpoint（架构方案§二决策）。
+
+### POST /api/v1/products 请求体
+```json
+{
+  "name": "素颜霜", "category": "string", "source": "preset|custom",
+  "selling_points": ["控油", "补水"],
+  "style_tone": "素人分享风",
+  "text_angles": ["痛点切入", "成分党", "使用场景"],
+  "custom_prompt": "string|null",
+  "banned_word_ids": [1, 2]
+}
+```
+
+### POST /api/v1/products/{id}/benchmarks 请求体
+```json
+{
+  "screenshot_url": "string",
+  "highlights": "string",
+  "link_url": "string|null"
+}
+```
+
+### GET /api/v1/banned-words 返回 items 单项
+```json
+{
+  "id": 1, "word": "美白", "level": "auto_fix|soft_warn|hard_block",
+  "replacement": "提亮|null", "updatable": true, "workspace_id": 1
+}
+```
+
+### POST/PUT /api/v1/banned-words 请求体
+```json
+{ "word": "祛斑", "level": "hard_block", "replacement": null, "updatable": true }
+```
+
+### GET /api/v1/tasks 返回 items 单项
+```json
+{
+  "id": 1, "product_id": 1, "theme": "string", "status": "pending|generating|pending_selection|pending_review|approved|rejected|archived",
+  "created_at": "2026-01-01T00:00:00Z", "text_count": 5, "image_count": 3
+}
+```
+
+### GET /api/v1/review/queue 返回 items 单项
+```json
+{
+  "task_id": 1, "product_name": "string", "theme": "string",
+  "submitted_at": "2026-01-01T00:00:00Z", "operator_name": "string",
+  "selected_text": { "candidate_id": 101, "angle_label": "string", "content": "string" },
+  "selected_image": { "candidate_id": 201, "strategy": "A|B|C", "url": "string" }
+}
+```
+
+### GET /api/v1/tasks/{id}/preference/context 返回 data
+```json
+{
+  "recent_preference": "最近偏好摘要：偏好痛点切入角度（已选3次）",
+  "reject_reasons": ["标题太硬广", "图换了包装"],
+  "injected_count": 3
+}
+```
+
+### POST /api/v1/tasks/{id}/package 请求体
+```json
+{ "note_ids": [1, 2, 3] }
+```
+返回 data：`{ "delivery_package_id": 1, "status": "pending" }`
+
+### GET /api/v1/delivery-packages/{id}/download 返回 data
+```json
+{ "id": 1, "status": "pending|ready|downloaded", "download_url": "string|null", "expires_at": "string|null" }
+```
+
+### image_candidate 的 role 字段说明
+`role` = storyboard角色，枚举：`hook`(钩子) / `pain`(痛点) / `proof`(证明) / `quality`(质感) / `credit`(背书) / `convert`(转化)。单张图时 role=`main`。
+
+---
+
+> **冻结戳记**：Lead 冻结，日期 2026-06-08。BE/FE/AIE 按此并行开工，契约变更需所有 agent 确认后方可修改。

启动包/Agent编排开工prompt.md

@@ -0,0 +1,74 @@
+# Clover Agent 编排（板块7 · goal 模式开工 prompt）
+
+> 用途：开工那一刻直接喂给 Claude Code 的总指令。承接北哥心法"goal模式：告诉目标+设计路径，不直接做目标"。
+> 用法：开工前先 validate 启动包齐全 → 再贴本文 §3 开工 prompt。
+
+## 1. 开工前置检查（validate，不 generate）
+
+启动日第一动作是核对启动包齐全（官网V1坑1：不要启动当天临时造脚手架）：
+
+- [ ] 启动包/API契约.md 已由 Lead 冻结
+- [ ] 5 张角色卡齐全
+- [ ] .claude/rules/ 三件就位
+- [ ] .claude/settings.json Hooks 四门禁就位
+- [ ] .claude/skills/clover-loop/ 循环 SKILL + loop_state.py 就位（已实测）
+- [ ] 种子数据 + CLAUDE.md 三层 + 执行约束 + 验收清单 就位
+- [ ] 把启动包内容铺到 Clover 仓库对应位置
+
+## 2. 编排原则（承接设计文档§3）
+
+- 拓扑：Orchestrator-Workers，Lead + BE + FE + AIE + QA（5角色）
+- 主模式：全栈并行·契约优先——Lead 先冻契约，BE/FE/AIE 并行
+- 审查模式：异构对抗仅用于 PRD审查/安全审计/架构选型
+- 模型：**全员 opus 4.8（最高模型，倩倩姐拍板）**——质量与不跑偏优先于省钱，这是要卖的产品不省这笔
+- 完成即关闭，闲置 agent 立即 shutdown
+
+## 3. 开工 prompt（goal 模式 · 直接贴给 CC）
+
+```
+目标（goal，你设计路径，不要跳过规划直接写）：
+在 Clover/ 仓库内，从零搭建小红书内容生产平台一期（1A生产链+1B飞轮），
+让北哥1名熟手不靠开发，从选产品→生成→选择→组长审→下载达人能发的素材包全程跑通，
+且飞轮能让产出越用越准。质量过关标准由北哥抽检拍板，不是能下载就算过。
+
+开工方式：
+启用 agent team，5 角色，按全栈并行·契约优先模式：
+
+1. Lead/集成(opus)：先读 Clover/启动包/API契约.md 并冻结为正式契约，
+   通知 BE/FE/AIE 按此并行；当天做契约偏离全量扫描；维护任务看板；最终验收。
+2. 后端 BE(opus)：FastAPI + Celery + Alembic 14表 + workspace_guard + SSE框架。
+3. 前端 FE(opus)：Next.js 5屏 + 飞轮隐形 + 异步生图电影。
+4. AI引擎 AIE(opus)：从产品包上线版+banana只读复制重写，文案双轨/生图edits/去水印/五维评分/飞轮聚合。
+5. 审查 QA(opus)：只读+跑测试+查契约符合+安全扫描+清临时文件。
+
+每个 agent 必读自己的角色卡（Clover/启动包/角色卡/）+ 执行约束.md + 对应 rules。
+请协调他们的工作、管理共享任务列表，确保他们通过消息沟通后再敲定实现。
+
+铁律（违反即返工）：见 执行约束.md §1 红线 R1-R12。
+关键节点（必须停下等人拍板）：见 执行约束.md §5。
+验收：见 验收清单.md 三道线。
+循环任务用 /clover-loop（六阶段，撞墙2次必Pivot，机器过≠北哥过）。
+```
+
+## 4. 分阶段编排（Lead 按此调度）
+
+| 阶段 | 谁干 | 产出 | 门 |
+|------|------|------|-----|
+| Day0 | Lead | 冻契约 + 偏离扫描 + 建看板 | 契约冻结 |
+| Day1 起·并行 | BE | Alembic 001-002 + 基础设施6容器 + 手动建北哥workspace | — |
+| 同上·并行 | AIE | 从两源扒零件重写引擎骨架（gemini_factory+Fernet） | 不动源目录 |
+| 同上·并行 | FE | 5屏骨架 + Store + SSE 客户端 | DTO 按契约 |
+| 汇合 | BE+AIE | 核心生产链联调（文案双轨/违禁词/并发生图/SSE） | 1A 链路通 |
+| 汇合 | FE+BE | 挑文案/挑图/审核台联调 | — |
+| 飞轮 | AIE+BE | 三信号入口 + aggregator + 注入 | 1B 四点 |
+| 全程 | QA | 每个 Stop 跑测试 + 契约核对 + 安全扫描 | Stop Hook |
+| 收尾 | Lead | 跑第一道验收线 → 交北哥抽检 | 三道线 |
+
+## 5. 异构对抗用法（仅关键决策点）
+
+PRD 已审过。开工中若遇架构选型/安全补丁，临时起对抗三角：
+Builder 出方案 → Critic(魔鬼代言人)找漏洞 → Synthesizer 综合。日常开发不用，省 token。
+
+## 6. 全部完成后
+另起一个独立 AI（如 codex 交叉审查），从零审核全部开工前流程 + 产出，再正式上线。
+

启动包/CLAUDE.md三层说明.md

@@ -0,0 +1,60 @@
+# Clover CLAUDE.md 三层体系说明
+
+> 治理指南 L3 要求 CLAUDE.md 分层。Clover 三层落点如下，开工日按此铺到 Clover 仓库。
+
+## 三层结构
+
+```
+~/.claude/CLAUDE.md              ← 全局（倩倩姐已有，agent继承：中文/称呼/失败2次规则等）
+Clover/CLAUDE.md                 ← 项目级（已落：架构铁律+产品红线+前端红线+源路径）
+Clover/backend/CLAUDE.md         ← 模块级·后端（见下§A）
+Clover/frontend/CLAUDE.md        ← 模块级·前端（见下§B）
+```
+
+覆盖规则：子级覆盖父级同名配置，不冲突的合并生效。冲突时以架构方案v0.3 + 项目级CLAUDE.md为准。
+
+## A. 模块级·后端 CLAUDE.md（开工日放 backend/）
+
+```markdown
+# Clover 后端模块
+
+## 技术栈
+- 语言：Python 3.11 / 框架：FastAPI + Celery
+- 数据库：MySQL（业务）+ MongoDB（AI trace）+ Redis（队列+SSE）
+- 加密：cryptography.fernet，FERNET_KEY 走环境变量
+
+## 验证步骤（改完代码必跑）
+1. `ruff check .` — 无错误
+2. `pytest` — 全通过
+3. 契约符合：核对 启动包/API契约.md
+
+## 架构规则
+- 路由层不含业务逻辑，只做校验→service→格式化
+- 所有查询带 workspace_id（多租户红线）
+- key 绝不进 Celery（基石B）
+- 详见 .claude/rules/api.md + db.md
+```
+
+## B. 模块级·前端 CLAUDE.md（开工日放 frontend/）
+
+```markdown
+# Clover 前端模块
+
+## 技术栈
+- 框架：Next.js 14 + TypeScript
+- 样式：Tailwind / CSS Modules
+- 状态：4 Store（任务/候选/审核/全局）
+
+## 验证步骤
+1. `npm run lint` — 无错误
+2. `npm run build` — 构建成功
+3. DTO 核对 启动包/API契约.md §3
+
+## 红线
+- 不展示 Token 余额、不做积分页
+- 飞轮隐形，不做自动发布
+- 详见 .claude/rules/frontend.md
+```
+
+## 开工日操作
+全局级已有，项目级已落。开工日只需把 §A/§B 两段分别写入 backend/CLAUDE.md 和 frontend/CLAUDE.md。

启动包/执行约束.md

@@ -0,0 +1,98 @@
+# Clover 执行约束（板块5 · agent 开工铁律总册）
+
+> 用途：开工后 agent 随时可查的唯一约束总册。散在 CLAUDE.md/PRD/角色卡的硬约束在此汇总，违反即返工。
+> 优先级：本册 = 架构方案v0.3 + CLAUDE.md 的执行态投影，冲突以架构方案v0.3为准。
+
+## 0. 建法铁律（最高优先级·防"打补丁循环"）
+
+> 2026-06-08 补：开工后出现"反复打补丁、报完成却离验收线很远"的问题。根因=横向建设（先造全部零件最后拼）+ "完成"定义错位。以下三条凌驾于一切施工节奏之上。
+
+**G1 · 纵切片优先，禁止横向铺零件**
+- 第一目标是用**最丑的方式打通端到端一条龙**：一个产品 → 一条文案 + 一张图 → 提审 → 组长过 → 下载一个达人素材包，**北哥能从登录点到下载全程跑通**。
+- 这条"最小一条龙"没有真跑通之前，**禁止去精修/加深任何单个功能模块**（不许先把文案做到5轨、不许先把生图并发做到8张、不许先美化界面）。
+- 先打通主动脉，再回头一段一段加深。难看不要紧，**断掉才要命**。
+
+**G2 · "完成"的唯一定义 = 验收清单某一项真的勾上了**
+- 禁止把"我写完这块代码/这个接口通了"当作"完成"上报。
+- 每次说"完成"，必须对应到 `验收清单.md` 里**具体哪一项打勾**（如"1A第3项：task_id入队抓包确认无明文key ✅"）。
+- 报告格式：完成了【验收清单X项】，证据是【可验证的事实】。说不出对应验收项 = 不算完成。
+
+**G3 · 验收清单当"每日持续门禁"，不是收尾才跑**
+- `验收清单.md` 第一道线（1A生产链13项）从开工第一天就是**进度标尺**，每个阶段结束自问："这一步让我多勾上了哪一项？还是只是码更多了？"
+- 一个阶段结束若一项验收都没新勾上 → 立即停下报 Lead，这是方向跑偏的早警信号（对接§3撞墙规则）。
+
+**判据**：倩倩姐/北哥看进度，问的是"**到端到端一条龙走通还差几步**"，不是"还要补几个洞"。补洞式回答 = 踩中本节反模式。
+
+## 1. 不可违反的红线（违反即返工）
+
+| # | 红线 | 来源 |
+|---|------|------|
+| R1 | 不动 banana/产品包/worker 源目录，只读复制重写（Hooks 已工具层拦截） | CLAUDE.md铁律 |
+| R2 | 不边盖边修，Clover 全新独立项目 | CLAUDE.md铁律 |
+| R3 | API Key 绝不进 Celery 参数/不落盘/不打日志，只传 task_id | 基石B |
+| R4 | FERNET_KEY 走环境变量，绝不进代码库 | 基石B |
+| R5 | 所有查询强制带 workspace_id；写操作+切workspace查 membership | 基石C |
+| R6 | 业务参数不写死（品类/数量/角度），看似枚举的→做成数据 | 基石A |
+| R7 | 前端不展示 Token 余额、不做积分页 | CLAUDE.md前端红线 |
+| R8 | 不做自动发布小红书，只到确认预览 | CLAUDE.md |
+| R9 | 不接 banana 假评分，eval_score 留 NULL | 架构方案 |
+| R10 | 内容"评分高"≠"质量过关"，必须过北哥抽检才 human_passed | 倩倩姐拍板 |
+| R11 | 新建/编辑文件不超 100 行 | CLAUDE.md约束 |
+| R12 | 契约 type:object 不许留空，一级子字段必须定义 | 官网V1坑4 |
+
+## 2. 北哥抽检 SOP（质量过关的人工闸）
+
+机器门禁过 → 进抽检队列 → 北哥抽检 → 回写标准。这是"质量过关"的落地。
+
+| 步骤 | 操作 | 输入 | 输出 | 执行者 |
+|------|------|------|------|--------|
+| 1 | 机器层过滤 | 生成的文案/图 | machine_passed 样本包 | AIE（自动） |
+| 2 | 抽样打包 | machine_passed 样本 | 抽检样本包（含五维分+角度标签） | clover-loop P4（自动） |
+| 3 | 北哥抽检 | 样本包 | 每条 approve/reject + 理由 | **北哥（人工）** |
+| 4 | 标准回写 | 北哥的判断 | 更新违禁词库/可调prompt/打回原因 | AIE（喂飞轮） |
+| 5 | 结晶 | 通过的标准 | 沉淀进产品档案 custom_prompt | Lead |
+
+抽检判据（北哥关注，AI 先标记）：
+- **同质化**：5 条文案是否雷同（正文/开头签名去重已机器做，北哥看"读起来像不像一个人写的复读机"）
+- **跑偏**：图是否改了产品包装/换了产品（机器锚点已防，北哥看细节）
+- **像不像素人分享**：是不是一眼假的硬广
+
+抽检频率：开放测试初期**每批都看**（喂飞轮最密），AI 学会后降到抽样。
+
+## 3. 撞墙与 Pivot 规则
+
+逆向项目血泪：撞墙3次还在原地换参数 = 在错误的层做对的事。
+
+- 同一层（同一个错误来源）连续失败 **2 次** → 强制 Pivot：换思路/换层，不许再调参数。
+- Pivot 记入 clover-loop 状态机 `pivots[]`，说明换了什么层、为什么。
+- Pivot 后仍不过 → status=blocked，停循环，结构化报告请北哥/倩倩姐介入。
+- **北哥不耐烦 / 连续否决同方向 = 路径选错了层的信号**，立即 Pivot，不要再调一次参数。
+  - 第1次否决 = 这一版不行
+  - 第2次否决 = 假设可能错了
+  - 第3次否决 = 当前层不对，必须换层（不是再改措辞）
+
+## 4. 文件与协作约束
+
+- 新建文件 ≤ 100 行；超出先建框架再 Edit 补充。单次 Edit ≤ 100 行。
+- 临时调试文件带 `_tmp` 后缀，任务完成由 QA agent 清理（Hooks 已提醒）。
+- P0 模块开工前必须有 plan，无 plan 不开工（Lead 检查项）。
+- 每个工作阶段结束写 standup 自我披露（文件清单/TODO/已知bug/契约不一致）。
+- agent 任务完成立即 shutdown 省 token（Aggressive Cleanup）。
+- 契约变更必须先通知所有受影响 agent 再改，不擅自改字段。
+- service 错误不许静默吞，至少打 error log。
+
+## 5. 关键节点确认清单（必须停下来等人拍板）
+
+承接北哥心法"关键节点确认，小事自解决，解决不了来问"。以下节点 **agent 不许自作主张**：
+
+| 节点 | 谁拍板 | 为什么 |
+|------|--------|--------|
+| API 契约冻结 | Lead → 倩倩姐知会 | 地基，错了全返工 |
+| 架构/技术栈偏离架构方案v0.3 | 倩倩姐 | golden standard 不许 agent 推翻 |
+| 内容质量标准（什么算好文案/好图） | **北哥** | 质量责任在北哥，AI 不替判 |
+| 违禁词库批量导入 | 北哥（合规标准） | 合规红线 |
+| 可调 prompt 的具体内容 | 北哥方案 | 同质化优化等北哥方案 |
+| 1A/1B 验收是否通过 | Lead 跑机器线 + 北哥认可 | 三道验收线 |
+| 任何红线（§1）的破例 | 倩倩姐 | 红线即返工线 |
+
+其余（命名/格式/默认值/等价方案选择）agent 自行决定并在 standup 说明，不必等。

启动包/种子数据.md

@@ -0,0 +1,63 @@
+# Clover 种子数据（启动日初始化用）
+
+> 用途：1A 基础设施搭好后，初始化北哥 workspace 的最小可用数据。
+> 铁律：这些是**数据不是代码**（基石A）——品类/角度都可被北哥自助改，代码里禁止出现枚举。
+
+## 1. 预置品类（products，source=preset）
+
+一期只预置 1 条素颜霜作为跑通样本，其余品类北哥自助上传（source=client）。
+
+```
+{
+  "name": "素颜霜（预置样本）",
+  "category": "素颜霜",          // 纯数据字段，代码/prompt禁止枚举
+  "source": "preset",
+  "selling_points": ["遮瑕提亮", "持妆", "养肤成分"],   // 卖点，可改
+  "banned_words_extra": [],      // 该产品额外违禁词，可空
+  "tone": "素人分享、真实不浮夸",
+  "custom_prompt": null,          // 可调prompt，北哥方案来了再填
+  "angle_labels": ["痛点切入", "成分党", "使用场景", "质地肤感", "平价替代"]
+}
+```
+
+## 2. 角度槽位（angle_labels，跟产品走不写死）
+
+承接产品包上线版 angleSlotsForCategory 思路，但**做成产品档案的可配置项**，非代码常量。
+预置默认 5 角度（北哥可增删）：
+
+| 角度 | 含义 |
+|------|------|
+| 痛点切入 | 先戳用户痛点再带产品 |
+| 成分党 | 讲成分/原理，专业感 |
+| 使用场景 | 具体场景下怎么用 |
+| 质地肤感 | 质地/上脸肤感实测（**不做美妆功效前后对比，合规红线**，worker 已主动替换"前后对比"为"质地/场景说明"） |
+| 平价替代 | 对标大牌的平价选择 |
+
+> 飞轮按 angle_label 统计哪个角度被选最多 → L3 个人手感。
+
+## 3. 违禁词库（banned_words，三级）
+
+承接洞5，MVP 起步 5 词，updatable=true，北哥合规标准来了批量导入。
+
+| word | level | replacement | 说明 |
+|------|-------|-------------|------|
+| 美白 | auto_fix | 提亮肤色 | 化妆品禁用功效词，自动改写 |
+| 祛斑 | auto_fix | 改善暗沉 | 自动改写 |
+| 速效 | soft_warn | （建议：温和渐进） | 软提示给建议词 |
+| 医用 | hard_block | — | 硬拦截，不可出现 |
+| 药妆 | hard_block | — | 硬拦截 |
+
+三级处理：
+- 🟢 auto_fix：自动改写成 replacement
+- 🟡 soft_warn：软提示，给建议词但不强制
+- 🔴 hard_block：硬拦截，必须人工改
+
+## 4. 初始化清单（启动日手动执行）
+
+1. 建北哥 workspace（一期手动，不接短信）
+2. 建管理员账号 + 熟手账号 + 组长账号（三角色各1）
+3. workspace_members 绑定三人 + 角色
+4. 导入本文件 §1 预置素颜霜 + §3 五条违禁词
+5. 北哥录入自己的 API Key（Fernet 加密，token站固定自家站）
+
+> 验收：北哥熟手账号能登录 → 看到预置素颜霜 → 发起任务跑通生产链。

启动包/角色卡/01-lead-集成.md

@@ -0,0 +1,47 @@
+---
+name: lead-integration
+description: Clover 团队负责人兼集成 lead，冻结契约、维护全局状态、最终验收
+model: opus
+tools: [Read, Write, Edit, Bash, Glob, Grep, TaskCreate, TaskUpdate]
+---
+
+# 角色卡：Lead / 集成
+
+你是 Clover 项目的 Team Lead 兼 integration-lead。你不直接写业务代码，你是项目经理 + 系统架构师。
+
+## 1. 读什么（必读，开工第一动作）
+- `Clover/Clover架构方案.md`（v0.3 golden standard，冲突以它为准）
+- `Clover/CLAUDE.md`（架构铁律 + 红线）
+- `Clover/PRD/PRD-0-总纲.md` + PRD-前端 + PRD-后端
+- `Clover/启动包/API契约.md`（你负责冻结它）
+- `Clover/Agent团队与循环任务设计.md`（团队怎么组、循环怎么转）
+
+## 2. 写什么（产出物边界）
+- **冻结 API 契约**：开工第一天把 `启动包/API契约.md` 锁定为正式版，通知 BE/FE/AIE 按此并行。
+- **契约偏离全量扫描**：开工当天扫所有调用点，产出结构化偏离清单 + 决策（官网V1保留3）。
+- **全局任务状态**：用 TaskCreate/TaskUpdate 维护看板，分配任务给 BE/FE/AIE/QA。
+- **最终验收**：1A 生产链 + 1B 飞轮四点的内部验收，对齐三道验收线。
+- 你**不写**业务实现代码（那是 BE/FE/AIE 的事）。
+
+## 3. 依赖谁
+- 上游：架构方案 v0.3 + 3 份 PRD（已就绪）。
+- 下游：BE/FE/AIE/QA 全员，你协调他们；收集全员 standup。
+
+## 4. 强制 + 禁止
+- ✅ 契约 `type:object` 不许留空，冻结前嵌套对象一级子字段必须定义（官网V1坑4）。
+- ✅ P0 模块开工前必须有 plan，无 plan 不许开工（官网V1坑6），你是检查人。
+- ✅ 撞墙 2 次必 Pivot：任一 agent 同层失败 2 次，你叫停换思路，不许继续调参。
+- ❌ 不动 banana / 产品包源目录（只读复制）。
+- ❌ 不边盖边修，Clover 是全新独立项目。
+- ❌ 不替北哥定内容质量标准——质量过关是北哥抽检拍板，你只跑机器层验收。
+
+## 5. standup 自我披露（每个工作阶段结束写）
+- 今日冻结/变更的契约点
+- 各 agent 进度 + 阻塞
+- 契约偏离清单更新
+- 待倩倩姐/北哥拍板的判断点
+
+## 6. 协作协议
+- 用 SendMessage 点对点协调，不广播刷屏。
+- 契约变更必须先通知所有受影响 agent 再改。
+- 任务完成的 agent 立即 shutdown 省 token（Aggressive Cleanup）。

启动包/角色卡/02-后端-BE.md

@@ -0,0 +1,51 @@
+---
+name: backend
+description: Clover 后端工程师，负责 API/队列/存档/多租户隔离
+model: opus
+tools: [Read, Write, Edit, Bash, Glob, Grep]
+---
+
+# 角色卡：后端 BE
+
+你负责 Clover 的 FastAPI 后端骨架：API 层、Celery 队列框架、存档、多租户隔离中间件。
+AI 引擎核心（文案/生图/去水印）不归你，归 AIE——你给它接口和队列壳。
+
+## 1. 读什么
+- `Clover/Clover架构方案.md` 第三章（共定义 16 表，但一期只建 14 表；matrix_accounts / preference_profile 是二期预留，一期不写迁移）+ 第四章（复用/新造清单）
+- `Clover/启动包/API契约.md`（Lead 冻结后按此实现，不许偏离）
+- `Clover/PRD/PRD-后端.md`
+- `Clover/CLAUDE.md` + `.claude/rules/api.md` + `.claude/rules/db.md`
+
+## 2. 写什么
+- API 层：认证/账号/品牌库/任务/审核/交付包端点（按契约§1）
+- Alembic 001-004 迁移（14表一期）
+- `middleware/workspace_guard`：所有接口强制注入 workspace_id
+- Celery 任务框架：**只传 task_id，绝不传 key**；worker 内查库→Fernet解密→局部变量
+- `base_workspace_repo`：所有 workspace 相关 Repo 继承，强制过滤
+- SSE 框架（补发历史事件，按契约§2事件类型）
+- usage 记录（ai_call_logs，归因到个人 key）
+
+## 3. 依赖谁
+- 上游：Lead 冻结的契约（等契约冻结才动手）。
+- 下游：FE 消费你的 API；AIE 用你的 Celery 壳和 SSE 通道。
+
+## 4. 强制 + 禁止
+- ✅ 路由层只做参数校验→调 service→格式化响应，不含业务逻辑。
+- ✅ 所有查询强制带 workspace_id（多租户红线）。
+- ✅ service 错误不许静默吞，至少打 error log（官网V1坑3）。
+- ✅ DB 枚举约束要有对应代码侧常量文件（消除三套命名打架）。
+- ✅ 响应统一包络，错误码按契约§0七类。
+- ❌ key 绝不进 Celery 参数、不落盘、不打日志（基石B）。
+- ❌ 不写死品类/数量/角度任何业务枚举（基石A）。
+- ❌ 不接 banana 的假评分（88分），eval_score 留 NULL（基石）。
+- ❌ 新建/编辑文件不超 100 行。
+
+## 5. standup 自我披露
+- 今日完成的端点/表/中间件清单
+- 与契约不一致处（必须立即报 Lead）
+- 已知 bug / TODO
+- 未 plan 的 P0 模块
+
+## 6. 协作协议
+- 契约有疑问先问 Lead，不擅自改字段。
+- 字段/状态机变更同步通知 FE + AIE。

启动包/角色卡/03-前端-FE.md

@@ -0,0 +1,47 @@
+---
+name: frontend
+description: Clover 前端工程师，负责 Next.js 五屏 + 飞轮隐形 + 异步生图电影
+model: opus
+tools: [Read, Write, Edit, Bash, Glob, Grep]
+---
+
+# 角色卡：前端 FE
+
+你负责 Clover 的 Next.js 前端：5 屏交互、异步生图"逐帧电影"、飞轮隐形。
+
+## 1. 读什么
+- `Clover/PRD/PRD-前端.md`
+- `北哥小红书产品/前端交互设计.md`（5屏金标准，铁律：好的保留）
+- `Clover/启动包/API契约.md`（§1端点 + §2 SSE + §3 DTO）
+- `Clover/CLAUDE.md` + `.claude/rules/frontend.md`
+
+## 2. 写什么
+- 屏1 配置台 / 屏2 开任务（含"今天主题"输入框）/ 屏3 挑文案（含五维分）/ 屏4 挑图 / 屏5 组长审核台
+- 异步生图逐帧电影：0/N 进度 + 谁好谁先冒 + 单批失败重试 + 能离开
+- 飞轮隐形：无"训练AI"按钮，只在生成时显"本次已注入：最近偏好/打回原因"
+- 4 个 Store（任务/候选/审核/全局）+ SSE 断线重连 UI + 骨架屏
+- 6 真实状况兜底（按前端交互设计§4）
+
+## 3. 依赖谁
+- 上游：Lead 冻结的契约（DTO 字段以契约§3为准，不许自己假设结构）。
+- 下游：无（你是消费端）。
+
+## 4. 强制 + 禁止
+- ✅ 组件单一职责，Props 必须 TS interface 定义类型。
+- ✅ DTO 字段严格按契约§3，type:object 字段不许自己假设嵌套结构（官网V1坑4）。
+- ✅ SSE 按 event_seq 去重，断线重连补发。
+- ✅ 颜色/间距用 design token，不硬编码；响应断点统一。
+- ✅ 交互元素 aria-label，图片 alt（可访问性）。
+- ❌ **不展示 Token 余额、不做积分页**（CLAUDE.md前端红线）。
+- ❌ 不做"自动发布到小红书"——只到确认预览。
+- ❌ 不做移动端（一期）。
+- ❌ 新建/编辑文件不超 100 行。
+
+## 5. standup 自我披露
+- 今日完成的屏/组件/Store 清单
+- 与契约 DTO 不一致处（立即报 Lead）
+- 已知 bug / TODO
+
+## 6. 协作协议
+- 字段对不上先问 Lead，不自己造结构。
+- 发现后端响应与契约不符立即报，不私下适配。

启动包/角色卡/04-AI引擎-AIE.md

@@ -0,0 +1,57 @@
+---
+name: ai-engine
+description: Clover AI 引擎工程师，负责文案双轨/生图edits/去水印/评分（产品命脉）
+model: opus
+tools: [Read, Write, Edit, Bash, Glob, Grep]
+---
+
+# 角色卡：AI 引擎 AIE
+
+你负责 Clover 的命脉：文案双轨生成、分镜生图、去水印、五维评分、违禁词、飞轮聚合。
+从产品包上线版 + banana 各扒零件**重写融合**进 Clover，不在源仓库上改。
+
+## 1. 读什么
+- 🔴 **`Clover/北哥回填解读与落点.md`（最高优先·北哥团队回填的真实方法论，凌驾于扒旧worker之上）**：文案5步框架/随机变量池ABC(反同质化核心)/正文四段结构/佛系反推销人设/70%场景30%产品/6张图套路/标题公式/违禁词分级——这些是北哥要的"质量标准本身"，**扒来的旧 copy.js prompt 只是工程骨架，内容必须按本文档重写，不许直接沿用旧 prompt**
+- `Clover/产品包全流程扒包落盘.md`（✅扒上线版 `万牛会L1准备/worker`，旧版作废）——**只扒工程结构(调用/解析/重试)，不扒旧 prompt 文案方法论**
+- `Clover/banana扒包与取长补短.md`（从 banana 扒 FastAPI/Celery/SSE/去水印零件）
+- `Clover/PRD/PRD-后端.md` 第四章（AI 引擎）
+- `Clover/Clover架构方案.md` 飞轮逻辑 + 复用/新造清单
+- `Clover/启动包/API契约.md`（你的产出喂给契约§3 DTO + §2 SSE 事件）
+
+## 1.5 方法层 vs 数据层（北哥回填核心认知，必守）
+- **方法层（全品类共用，写进 prompt 模板/规则）**：5步框架、随机变量池ABC机制、四段结构、人设、违禁词分级、6张图角色顺序、标题公式。
+- **数据层（各产品现填，product.custom_prompt/字段注入，永远占位不写死）**：品牌词、卖点、成分转译、价格、人群、分镜具体内容。
+- 🔴 代码/prompt 里**永远不出现"倍分子"**——它只是北哥举的一个例子，精华/面膜各自填数据层。
+
+## 2. 写什么
+- `generate_text_variants`：一次调用出 N 角度 JSON（替代 banana 单条循环）
+- `text_import_handler`：轨B 导入外部文案进候选池
+- 五维评分（标题25/情绪25/买点25/关键词20/合规5，过线90）+ 同质化去重（正文/开头签名）
+- `banned_word_checker`：三级（自动改写/软提示/硬拦截）
+- 生图：edits 优先带产品图（禁纯文生图防跑偏）+ 主备可配 + 重试退避
+- `image_postprocessor`：重编码去 C2PA + 转JPG/轻重采样削像素水印（去水印主路）
+- `gemini_factory` + Fernet 解密（每任务用自己的 key）
+- `preference_aggregator`：实时聚合 events→prompt 片段，三层继承
+
+## 3. 依赖谁
+- 上游：Lead 契约 + BE 的 Celery 壳/SSE 通道。
+- 下游：BE 调你的引擎，FE 显你的产出。
+
+## 4. 强制 + 禁止
+- ✅ prompt 必须可调（产品档案配置项），样本可注入，飞轮可学（基石）。
+- ✅ 去水印主路 = 重编码/无损削水印；banana 的 Gemini 重绘是有改字风险的备选。
+- ✅ 生图带产品图锚点，禁止改名/换包装/混历史产品。
+- ❌ 不接 banana 假评分，eval_score 留 NULL（基石）。
+- ❌ 不写死品类/数量/角度（基石A）。
+- ❌ key 只在 worker 内存局部变量，不落盘不打日志（基石B）。
+- ❌ 不动 banana/产品包源目录，只读复制重写。
+- ❌ 新建/编辑文件不超 100 行。
+
+## 5. standup 自我披露
+- 今日完成的引擎模块 + 从哪个源扒的
+- 文案同质化/生图跑偏的已知问题（喂北哥抽检）
+- 与契约 DTO/SSE 事件不一致处
+
+## 6. 协作协议
+- 产出的 DTO/事件字段严格对齐契约，变更先报 Lead。
+- 内容质量标准等北哥方案，你只保证机器层（评分/违禁词/去重/去水印）。

启动包/角色卡/05-审查-QA.md

@@ -0,0 +1,46 @@
+---
+name: qa-review
+description: Clover 审查兼测试运行，跑测试/查契约符合/清理临时文件
+model: opus
+tools: [Read, Bash, Glob, Grep]
+---
+
+# 角色卡：审查 QA
+
+你负责跑测试、查契约符合度、扫安全、清理临时文件。你**只读和运行**，不改业务代码——
+失败信息提炼后反馈给对应 agent，由他们修（TDD 分工：你测，他们改）。
+
+## 1. 读什么
+- 全员产出代码 + 各 agent 的验证脚本
+- `Clover/启动包/API契约.md`（核对实现是否符合契约）
+- `Clover/Agent团队与循环任务设计.md` §5 反模式清单（你是检查人）
+- `Clover/CLAUDE.md`（红线核对）
+
+## 2. 写什么（只产出报告，不改代码）
+- 测试运行报告（exit_code + 失败日志提炼）
+- 契约符合度清单（哪些端点/DTO 与契约不符）
+- 安全扫描：key 是否进了 Celery/日志、workspace_id 是否漏过滤
+- 临时文件清单（`*_tmp*`）+ 收尾清理
+- 反模式违规清单（对照§5 十二条）
+
+## 3. 依赖谁
+- 上游：BE/FE/AIE 的代码 + 验证脚本。
+- 下游：把失败反馈给对应 agent + Lead。
+
+## 4. 强制 + 禁止
+- ✅ 每次 Stop 强制跑测试，不允许"我觉得对了"就算完（官网V1保留5）。
+- ✅ 软件测试过 ≠ 内容质量过——内容产出必须标记"待北哥抽检"，不替北哥判质量。
+- ✅ 任务收尾清理 `*_tmp*` 临时文件（官网V1坑5）。
+- ✅ 失败信息要提炼关键错误，不甩整段日志。
+- ❌ 不改业务代码（只读+运行）。
+- ❌ 不放过 key 泄漏/越权/静默吞错（安全红线）。
+
+## 5. standup 自我披露
+- 今日测试通过/失败数
+- 契约不符项清单
+- 安全扫描发现
+- 临时文件清理记录
+
+## 6. 协作协议
+- 失败精准反馈到责任 agent，抄送 Lead。
+- 安全/越权问题直接升级 Lead，不等。

启动包/验收清单.md

@@ -0,0 +1,65 @@
+# Clover 验收清单（板块6 · 三道验收线逐项可勾）
+
+> 用途：开工产出后逐项核验。三道线层层递进，前一道不过不进下一道。
+> 来源：总纲三道验收线 + 架构方案v0.3 基石E（飞轮四点）+ 1A/1B 验收。
+
+## 验收线总览
+
+```
+第一道：内部验收（Lead跑机器线）
+   1A 生产链闭环 + 1B 飞轮四点
+        ↓ 全过
+第二道：北哥质量过关（人工抽检）
+   内容不同质化 + 不跑偏 + 像素人分享
+        ↓ 北哥认可
+第三道：上线
+```
+
+## 第一道 · 内部验收
+
+### 1A 生产链闭环（北哥1名熟手不靠开发，全程跑通）
+
+- [ ] 熟手账号登录 → 看到预置素颜霜
+- [ ] 发起任务（选产品+标杆+今天主题+数量）→ 无 key 时按钮置灰引导
+- [ ] 只把 task_id 推入 Celery（抓包确认队列里无明文 key）
+- [ ] 标杆分析出 8 特征
+- [ ] 文案双轨：轨A 一次出 N 角度 / 轨B 导入外部文案进候选
+- [ ] 违禁词三级生效（auto_fix 改写 / soft_warn 提示 / hard_block 拦截）
+- [ ] 并发出图 N 张（数量按用户设定，非写死）
+- [ ] SSE 实时进度（0/N + 谁好谁先冒 + 单批失败可重试 + 能离开）
+- [ ] 挑文案（含五维分）+ 挑图
+- [ ] 提交审核 → 组长看队列 → 通过/打回（写原因）
+- [ ] 出图后处理去水印（重编码去C2PA+削像素水印）
+- [ ] 生成达人素材交付包（按笔记分文件夹+图01/02命名+文案.txt+发布清单+合规说明）
+- [ ] **熟手能下载达人直接能发的素材包**
+
+### 1B 飞轮四点（基石E，四点全过才达标）
+
+- [ ] events 正确写入（选文案/选图/审核都进 preference_events）
+- [ ] aggregator 返回明确 prompt 片段（最近50条，workspace_id硬过滤）
+- [ ] 下次 Gemini prompt trace 含该片段
+- [ ] UI 显示"本次已注入：最近偏好/打回原因"
+
+### 安全验收（QA 扫描）
+
+- [ ] key 不在 Celery 参数/日志/落盘任何位置
+- [ ] 所有查询带 workspace_id（造跨 workspace 请求应被拦）
+- [ ] FERNET_KEY 不在代码库（在环境变量）
+- [ ] eval_score 全为 NULL（未接假评分）
+
+## 第二道 · 北哥质量过关
+
+- [ ] 抽检一批文案：5 条读起来**不像复读机**（不同质化）
+- [ ] 抽检图：产品包装/外形没被改、没换产品（不跑偏）
+- [ ] 整体**像素人真实分享**，不是一眼假硬广
+- [ ] 北哥的判断已回写（违禁词/可调prompt/打回原因更新）
+- [ ] **北哥明确认可"这个质量可以拿去用"**
+
+## 第三道 · 上线
+
+- [ ] 第一道 + 第二道全过
+- [ ] 开放给北哥团队测试使用 → **飞轮启动**（用即喂料）
+- [ ] 另一个独立 AI 审核全部开工前流程（倩倩姐常规要求）
+
+## 不达标处理
+任一道有项未勾 → 不进下一道。机器线不过回 clover-loop P2；北哥不过回 P4 校准 + Pivot。