beige/CLAUDE.md

# Clover 项目约束（CLAUDE.md）

> 本文件是 Clover 项目的事件级约束，agent 团队开工必读。
> 倩倩姐口头红线当场落盘，不写当不存在。

## 🔴 架构铁律（最高优先级，违反即返工）

### 1. Clover 是全新独立项目
- 所有代码在 `北哥小红书产品/Clover/` 下从头建立。
- **不在 banana 上盖、不在产品包上盖、绝不边盖边修。**

### 2. banana / 产品包 = 只读素材源
- 两个来源文件夹**只做读取和复制**，**禁止任何修改**：
  - banana：`/Users/qiyu/Documents/企业培训项目/O2中间件平台/banana`（只读）
  - 产品包✅上线版：`/Users/qiyu/Documents/企业培训项目/万牛会L1准备/worker`（**真正部署上线版,扒这个**）
  - 🔴产品包旧版 `万牛会L1准备/产品包/worker` 是开发副本/旧版,**不要扒**(copy/image比上线版旧100~200行)
- 工作方式：需要哪部分零件 → 复制出来 → 在 Clover 里结合本项目迭代/优化/重建。
- 不允许 `cd` 进这两个目录做 Edit/Write/git 操作。

### 3. 技术栈
- 后端统一 Python（FastAPI+Celery+双库+Redis），产品包的 JS 内核**重写成 Python** 融进 Clover。
- 重写必须仔细对照防逻辑走样（TDD + agent团队 + 另一AI审核兜底）。

## 🔴 已拍板的产品决策（不可推翻）
- 生图：**gpt-image-2 主**（codeproxy中转站），Gemini 备。
- 生图接口：优先 `/images/edits`（带产品参考图），加重试退避。
- token：统一走自家中转站 url；key 按账号隔离，各人自录自用各算各的。
- **模型只用最强档（倩倩姐2026-06-12拍板）**：Claude 系用 **4.8**（claude-opus-4-8），GPT 系用 **5.5**；通道目前仍只用 apiports 那一套（文案暂不补 codeproxy 第二路径，等真出现频繁挂再说）。
  - **模型兜底铁律（倩倩姐2026-06-12拍板）**：claude-opus-4-8 一定可用。**若 gpt-5.5 探活不可用，回落到 claude-opus-4-8（最强档），绝不降级到 sonnet 或任何弱档；绝不偷偷降级当没事，探活不可用立即回报。**
- **品牌词由客户输入**（产品级字段，随产品固定），植入文案每条+生图特写图（第2/6张）。
  - 🔴 **品牌词植入位置=文案+图片文字排版层，绝不P瓶身（倩倩姐2026-06-15拍板）**：瓶身=产品本身，忠于参考图原样，禁止改/加/P瓶身文字（合规+真实双重要求）。品牌词"倍分子"出现在①文案每条②图片的标题/贴纸/标注等文字排版层，不是非要印到瓶身上。AC9实测task61 hook图瓶身只印"素颜霜"=正确，不是bug。曾误判要去P瓶身被驳回。
- **每用户并发上限 5 个任务**（客户侧实际跑几个再观察调整）。
- **生图出3套**：套间差异按 ①文案角度 ②视觉风格 ③叙事结构（套1痛点先行/套2场景先行/套3成分背书先行）三个正交维度拉开，**不按封面分**，要不重复。
- **配图去AI化对齐大卫xhs（倩倩姐2026-06-15拍板）**：大卫 `小红书系统图片定制/xhs-tool/backend/infrastructure/imagePostProcess.js`（只读素材源）运营实测去AI化能力强，Clover 后处理对齐它：①**尺寸可选**(RATIO_MAP多比例，**±2%容差内不resize**避免无谓重采样)，常规默认 **3:4=1024×1536**(gpt原生尺寸，**不强缩1080×1440**，核销表原S4方向作废) ②SynthID破除(缩2px裁1px边+亮度/饱和微调，开关控制) ③高保真重编码(jpeg quality100/chroma4:4:4去元数据) ④重试里支持选尺寸。**先打通单套配图(含去AI化+尺寸可选)，再扩3套正交**。
- **配图三套叙事措辞=倩倩姐先起草**（2026-06-15）：痛点先行/场景先行/成分背书先行的具体prompt措辞由倩倩姐起草给北哥过目，不用临时占位糊弄；扩3套时填入。
- **文案待提质量项（倩倩姐2026-06-15）**：①80合格线是临时妥协，方向是提生成质量顶分数不降标准 ②生成文案每条套路化重复"买不买跟我没关系"收尾句式要去模板化。详见记忆 clover-quality-line-80-temp。
- 🔴 **合格线=80，禁止擅改（倩倩姐2026-06-15二次拍板）**：`constants.py QUALITY_PASS_SCORE=80`。coder 曾擅自改85被驳回。提质量靠优化生成prompt顶分数，**绝不靠提高门槛/降标准凑数**。改这个值必须倩倩姐当面拍板。
- 🔴 **卖点三套来源·系统通用化（倩倩姐2026-06-15拍板，P0）**：系统是通用的，**产品靠上传才有，绝不内置写死任何具体产品**(素颜霜只是北哥一个客户的一个产品)。卖点三套来源(产品包本有，Clover重写漏了)：①**从产品图片提取**(vision读图→卖点/人群/成分/视觉系统，**走GPT现有通道最强档，不补GEMINI_KEY**) ②**用户上传填写**(北哥文案3.txt即此套) ③**产品库内置**(fallback模板，留口即可)。成分(烟酰胺等)**并入selling_points不单列字段**。配图文字图片**先做一致**，后续留**canvas排版口子**(底图+代码叠字)。北哥禁AI是怕查重+AI化，**我们已做去AI化(对齐大卫xhs)，此担忧已解决，不再当决策点**。
- **文案过滤=先展示后台补（倩倩姐2026-06-12拍板）**：合格文案(passed且≥90分且非hard_block)立即展示不卡用户；合格数不足用户要的条数时，**后台异步补充生成**直到够数或达上限。不是"只展示不补"，也不是"凑不够就卡着不出"。
- **13环目标导向**：原始是13环（北哥回填解读与落点.md），banana本给了最硬4环引擎(找竞品/写文案/配图/裂变)。这轮**补全第2环竞品爆款分析(=标杆8特征)+第11环裂变**两个缺失引擎环；裂变单独做但在工作台内呈现（1爆款→N套完整笔记包，非只换文案）。
- 软件费：MVP 免费，收费逻辑后续单独讨论（先留接口关闭）。
- 飞轮：**开放给北哥测试使用即启动**（用即喂料，不是埋点不激活）。
- 🔴 **飞轮是产品最大亮点·必须做扎实+前端必须呈现（倩倩姐2026-06-16拍板）**：飞轮不是后台默默跑的暗功能，要让客户**直观感到"确实进入飞轮了、确实越用越好"**。两条入口都要做：
  - ①**改稿进飞轮（D1，最强信号，必做）**：运营改AI稿→diff喂回飞轮。**入飞轮时机=先激进(改了就入)跑一周，北哥用后按真实信号质量校准是否加"过审才入"闸门**（细案E18/E19）。需补 SignalType.text_edit + TextCandidate.edited字段 + 改稿端点(走task_actions不碰review.py)。
  - ②**AI评图分进飞轮（E12，做扎实版）**：AI评图分**只做"生成时筛选+前端展示"**，前端要呈现"这张图AI评了X分+已被选入飞轮"。**真正影响下次生成的飞轮权重只认真实信号（选了哪张/改了什么/过审与否），不拿AI主观分当权重**——守住eval_score留NULL铁律，AI分是展示层不是权重层。
  - ③**前端呈现=轻量化关键节点反馈（不做独立飞轮主视图大页E01）**：在生成/选择/改稿/审核节点即时提示"已学习你的偏好""本次参考了你上周改的稿""飞轮已积累N条信号"，嵌现有流程，纵切片友好。
- 🔴 **竞品笔记数据监控=不做（倩倩姐2026-06-16拍板）**：E04竞品数据全监控/反推关键词=自动抓小红书,命中合规反爬红线,直接砍,不进任何期。
- 发布：不自动发小红书，产出"达人素材交付包"人工发。
- 数据归属：原始数据(输入+产出+素材包)归客户可导出；飞轮偏好归平台。
- 违禁词：三级处理(自动改写🟢/软提示🟡/硬拦截🔴)，默认分级北哥可调。
- 链接采集：不做原始抓取（死路），走对外截图手填 / 内部登录态插件。

## 🔴 验收线
- **质量过关才算完，不是"能下载"就算完**，最终北哥认可。

## 🔴 前端红线
- **不展示 Token 余额/用量**：key 和用量去中转站后台看，前端只录 key 不显示余额。
- 不做积分中心/billing 页（MVP免费）。

## 🔴 安全红线
- **SSE 认证用一次性短票 ticket，绝不把 JWT 放进 URL**（倩倩姐2026-06-08拍板）：EventSource 不支持 header，故 SSE 连接前先用 JWT 调一个签发接口换一张只活 30-60 秒、仅对该 SSE 流有效的一次性 ticket，URL 只带 ticket（`?ticket=`）。就算被日志/浏览器历史记下也立即失效、换不了别的接口。禁止 `?token=` 直传 JWT。

## 🔴 执行约束
- 🔴 **建法铁律（防打补丁循环·先读 启动包/执行约束.md §0）**：①纵切片优先——先用最丑的方式打通端到端一条龙(登录→选品→出1文1图→审核→下载1个包)，这条没真跑通禁止精修任何单块功能 ②"完成"唯一定义=验收清单某项真勾上(非"代码写完")，报完成必附对应验收项 ③验收清单当每日门禁，每阶段自问"多勾上哪一项了还是只是码更多了"。看进度问的是"到一条龙走通还差几步"不是"还要补几个洞"。
- 新建文件**目标 ≤100 行、上限 200 行**（倩倩姐2026-06-08放宽：ORM模型/枚举常量/内聚算法硬拆反而割裂可读性，故放宽到200行内可接受，**超200行必须拆**）；单次编辑 ≤100 行（超了先建框架再Edit补）。
- 质量标准/优化prompt 等北哥方案到位再填，架构先留可调位。
- 🔴 **本轮交付层级=全量（倩倩姐2026-06-12拍板）**：终点线=一条龙过质量关 + 补全第2环标杆分析 + 第11环裂变。KR1链路连通/KR2质量达标/KR3自主可验/KR4引擎补全 全绿才算"全勾完"。
- 🔴 **打断节奏=攒批集中问（倩倩姐2026-06-12拍板）**：自主连续推进，把"只有倩倩姐能判断"的点（某条文案过不过关/某图品牌词够不够清晰/要不要砍需求）攒成批次，每完成一个环集中问一次，不一条条点yes。
- 🔴 **核销机制=孙总方法论（2026-06-12录音提炼，已结晶 ~/.claude/crystals/cc-methods/ai-collab-checkpoint-gating.md）**：①双层核销表(总核销表+每模块分核销表)，做完一项物理勾一项 ②每模块收尾产"压缩存档/end-of文件"记录做到什么程度，断点可续 ③小步快跑+高频check，不攒大块 ④**验收标准写到90分清晰度**(模糊=放水=AI按40分自认通过) ⑤标准做减法砍到最少步 ⑥门禁要硬,不通过物理卡死 ⑦**绝不信AI第一遍自评**(实测谎报"都做了"实际20-30%),必独立交叉核对。
- 🔴 **工作模式=自运行核销机器（倩倩姐2026-06-12拍板）**：①**强制用workflow的agent team执行,不许自己瞎干** ②**必做交叉验证**(另起独立agent重核,不信第一遍) ③规则/验收清单**先全部列出来**再做(你要先看到规则) ④做完一个勾一个、任务只减不增 ⑤倩倩姐**只验最后结果**,过程中要她判断的点**攒成批集中问**,不一条条点yes。