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-26拍板）：客户导入的外部文案=客户实跑验证过、跑得好的样本，是最值得学习的范本，飞轮信号权重要高于普通 AI 选稿信号。需补 SignalType（如 text_import）并给更高权重；与"导入轨去生图"链路配套。守住 eval_score 留 NULL 铁律不变。
• 🔴 竞品笔记数据监控=不做（倩倩姐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。