beige/产品包全流程扒包落盘.md

# 产品包全流程扒包落盘

> 目的：把"产品包"的完整内容生产流程摸透，决定 Clover 复用什么、升级什么。
> 铁律：**好的保留，不好的优化升级**。
> 扒包日期：2026-06-05｜扒包人：CC

---

## 🔴 重大修正（2026-06-05·倩倩姐提醒）：存在两套代码！

产品包**上了两套**，我第一次扒错了源（扒的是旧的开发副本）：

| | 路径 | 性质 | 状态 |
|--|------|------|------|
| ❌旧版 | `万牛会L1准备/产品包/worker/src` | 开发副本/精简旧版 | 我首扒的(结论部分作废) |
| ✅上线版 | `万牛会L1准备/worker/src` | **真正部署上线**(有.wrangler/.dev.vars/线上域名wanniuxhs.super-n8n-agen.xyz) | **以此为准** |

两套差异（上线版更新更全）：
- copy.js 上线690行 vs 旧578行（差176行）
- image.js 上线871行 vs 旧656行（差311行）⚠️差异最大
- split.js 几乎一致（差8行）
- 上线版独有：ai-judge.js / sop-evaluate.js / feishu.js(飞书提交426行) / X-Auth-Token鉴权

**🔴 上线版已实现的"升级项"（我旧版结论里误判为"待升级"，实际早做了）：**
1. ✅生图主备**可配置**(imageProviderOrder读env.IMAGE_PROVIDER_PRIMARY/FALLBACK)——非写死
2. ✅GPT**带产品参考图edits**(requestGptImageWithReferences)，且**禁止纯文生图防产品跑偏**
3. ✅产品图作"**不可修改商品锚点**"强约束(禁改包装/换产品/混历史产品)——防串货
4. ✅文案**正文/开头去重**(splitPublishableContent/contentSignature/openingSignature)——直击同质化
5. ✅**角度槽位**(angleSlotsForCategory/angleSame)强制每条不同角度
6. ✅**内部提示剥离**(content只放可发布正文，配图建议挪imageBrief)

→ Clover 必须**扒上线版**，不是旧版。下面"四、好坏评估"的⚠️升级项已据此修正。

---

## 一、产品包是什么（以上线版为准）

北哥实际部署运行的小红书种草内容生产系统（CF Pages前端 + CF Worker后端）。
上线版后端入口 `万牛会L1准备/worker/src/index.js`，15个路由。核心引擎：

| 路由 | 文件 | 干什么 | 调用模型 |
|------|------|--------|----------|
| /api/generate-copy | copy.js | **文案引擎**(去重升级版) | Claude→Gemini→本地 |
| /api/generate-image + plan-images + generate-one-image | image.js | **生图引擎**(主备可配+edits) | 可配置主备 |
| /api/content-split + generate-complete-notes | split.js | **裂变+端到端编排** | Claude→生图 |
| /api/parse-xhs-reference | split.js | 链接解析(只扒meta) | - |
| /api/submit-to-feishu 等 | feishu.js | 飞书提交(上线版独有) | - |
| /api/ai-judge / evaluate-sop | ai-judge/sop | demo诊断(Clover用不上) | Claude |

> chat.js 是 demo 的"AI业务诊断"对话，Clover 用不上，**不复用**。
> 另有 product.js（产品图视觉分析，Gemini Vision 出 visualIdentity，带6大品类兜底）——**可复用**做"产品配置"。

---

## 二、完整流程拆解（生成文案→生成图→裂变→存档）

### 2.1 生成文案（copy.js · 最值钱的一块）
输入：产品名+卖点+人群+风格+数量+previousCopies(历史去重用)。
处理链路（三层兜底）：
1. **Claude 生成** → 失败 → **Gemini 生成** → 失败 → **本地模板兜底**(buildLocalDrafts，6品类×10角度，保证永不空手)
2. **五维打分**(scoreCopy，满分100，过线90)：标题吸引力25 / 情绪共鸣25 / 买点表达25 / 关键词覆盖20 / 合规性5
3. **自动优化循环**(maxOptimizeRounds默认2轮)：不达标→把"未达标原因"喂回prompt重新生成，避开已有标题/角度
4. **去重系统**(dedupeCopies+isSimilarCopy)：标题相似度≥0.82 或 (标题≥0.65且正文≥0.72) 判重，与历史和本轮都比
5. **违禁词处理**：BANNED_WORDS=[美白/祛斑/速效/医用/药妆] + BANNED_VISUAL=[前后对比/变白/before/after等]；sanitizePlanningText **自动改写**(变白→自然光泽感，前后对比→质地说明)；合规分含禁用词直接0分
输出：copies[]，每条={title,content,tags,angle,buyingPoint,coverTitle,imageBrief,score,passed,publishable}

### 2.2 生成图（image.js · 编排最复杂）
核心概念 **storyboard 分镜**：一套笔记的N张图，每张有固定"叙事角色"。
- PAGE_ROLES 10种角色：hook点击钩子/pain_scene痛点/applied_proof核心证明/texture质感/ingredient成分/social_proof背书/scenario场景/tutorial教程/closer软转化
- getNarrativeRoles：3张=钩子+证明+转化｜6张=钩子+痛点+证明+质感+背书+转化｜8张=+多场景+教程
- proofStrategy：按6品类给"证明页"定制画面策略(护肤=手背质地/食品=冲泡口感/服饰=上身材质)
- buildVisualSystem：成组视觉统一(主色/字体/贴纸/符号系统/质感)，从product.js的visualIdentity来
- 素材路由(imagePartsFromAssets)：产品图保包装准确 / 客户实拍图给肤感场景 / 爆款图只参考版式贴纸
- 每张图 prompt = basePrompt(全局规则+违禁限制) + promptFromStoryboard(本张角色/目标/图上文字/画面/禁止)
**生图通道(关键升级点)**：generateOneImage 先 Gemini(多model fallback) 后 GPT，用 `/images/generations` 纯文生图，size 1024x1536。

### 2.3 裂变（split.js · 真正的端到端编排器）
裂变 = 1条爆款参考 → N套**完整笔记包**(不是只换文案)。
- 输入：originalCopy(爆款)+产品信息+裂变维度(换角度/痛点/人群)+条数+每条图数+generateImages开关+referenceLevel(30-85)
- **爆款参考度** referenceStrategyFromLevel：低参考(只学结构)/中参考/高参考(学标题节奏但替换表达防抄袭)
- 每套笔记包含：标题+正文+标签+coverTitle+imagePlan(每张图分镜)+dimension+audience+scene+painPoint
- scoreCompleteNote：copy五维 + 图文完整度15分
- **generateImages=true 时直接串 image.js 出图**，readyToPublish=文案达标且图全部生成成功
- 链接解析 handleParseXhsReference：本地只能扒 og:title/og:description/og:image(meta)，扒不到正文和内页图 → **对应洞1结论：原始抓取死路**

### 2.4 存档
⚠️ **产品包没有真正的存档/数据库**。它是无状态 Worker，产出物直接返回前端，靠前端 localStorage 或人工保存。
→ 这正是 Clover 必须**新建**的环节(delivery_packages表+package_exporter+素材打包下载)，PRD不能漏。

---

## 三、数据流转（端到端）

```
产品配置(product.js分析产品图→visualIdentity)
   ↓
[路径A 从0生成]  generate-copy → N条文案(打分+优化+去重)
                    ↓ 选中1条
                 generate-image → 该文案的storyboard N张图
   ↓
[路径B 爆款裂变]  content-split(贴爆款链接/手填) → N套完整笔记包
                    ↓ generateImages=true
                 自动串 image.js → 每套笔记的N张图
   ↓
存档打包(❌产品包没有，Clover新建) → 按笔记分文件夹+图01/02命名+文案.txt+发布清单.txt
```

---

## 四、好/坏评估（铁律落地）

### ✅ 值得保留（设计得好，直接复用/微调）
1. **三层兜底**(Claude→Gemini→本地模板)：永不空手，生产级健壮 → 保留
2. **五维打分+90分过线**：质量可量化，前端能展示分数 → 保留，分值权重北哥可调
3. **自动优化循环**：不达标喂回原因重生成 → 保留，是飞轮的雏形
4. **去重系统**：相似度算法防重复发 → 保留，裂变刚需
5. **违禁词三级**(自动改写sanitize+硬扣分)：和洞5方案完全一致 → 保留，升级为可配置三级
6. **storyboard叙事分镜**(10角色+品类证明策略)：生图的灵魂，保证N张图各司其职不重复 → 保留
7. **素材路由**(产品图/实拍图/爆款图分工)：和达人交付定位契合 → 保留
8. **爆款参考度调节**(低/中/高防抄袭)：裂变合规关键 → 保留
9. **6品类自适应**(inferCategory+品类话术)：素颜霜只是其一，未来可扩品 → 保留

### ⚠️ 必须优化升级（基于✅上线版重新核对）
> 注：旧版结论里的"生图主备颠倒/无edits/无重试"上线版**已做**，下面已剔除/修正。

**A. 上线版已做好、Clover直接扒（不用重新发明）：**
- ✅生图主备可配置(imageProviderOrder) → Clover设 PRIMARY=gpt, FALLBACK=gemini 即可
- ✅GPT带产品图edits + 禁纯文生图防跑偏(requestGptImageWithReferences)
- ✅产品图"商品锚点"防串货约束
- ✅文案正文/开头去重 + 角度槽位(治同质化)
- ✅内部提示剥离(content只放可发布正文)

**B. 上线版仍缺、Clover必须新建（真正的升级项）：**
1. **重试退避**：上线版生图单次失败即记failure，无重试；gpt-image-2实测有502 → **加重试退避**(baseline验证必要)。⚠️注:上线版copy里有_retry思想但生图通道无，需补
2. **暗水印处理**：产出直接给前端，C2PA水印发小红书被识别 → **新增去水印工序**(洞3；可扒banana remove_watermark + re-encode安全档)
3. **存档/数据库**：无状态Worker → **新建delivery_packages+打包导出**(洞6/洞7)
4. **API Key硬编码**：旧PRD明文key、env散落 → **收口自家中转站url，key按账号隔离**(洞4)
5. **单租户无隔离**：无用户/租户/JWT → **新增多租户逻辑隔离**(扒banana JWT)(洞4/7基石)
6. **同步阻塞**：Worker同步等生图(每张~4min)串行会超时 → **改异步队列**(扒banana Celery)(洞3)
7. **无偏好飞轮**：优化循环不记忆用户选择 → **新增preference_events+三层偏好继承**(M9灵魂)
8. **链接解析空壳**：只扒meta → **接登录态采集插件**(洞1)
9. **质量同质化(根因)**：上线版去重/角度槽位是"机制"，但缺北哥真实优质样本和判断标准做"内容" → **架构留可调prompt+样本注入位，等北哥方案；飞轮学北哥审美**

---

## 五、给 Clover 的结论（修正版）
- **扒✅上线版** `万牛会L1准备/worker/src`，不是旧版。copy/image/split三件套算法内核(打分/优化/去重/角度槽位/storyboard/品类策略/违禁词/主备可配/edits/防串货)整体搬，是Clover最大存量资产。
- 真正要新建的升级点(B类9项)：重试/去水印/存档打包/Key收口/多租户/异步队列/飞轮/链接采集/质量样本位。
- chat.js + ai-judge.js + sop-evaluate.js 丢弃(都是万牛会demo诊断用)；feishu.js按需(飞书提交，Clover若要飞书通知可参考)；product.js改造成产品配置。
- 前端按"前端设计参考图.png"5步流程重做(产品包旧前端是demo展示页，不复用)。