# POD 趋势感知 Agent · 对接文档

> 面向开发者/维护者的适配与扩展指南。覆盖：项目架构、**如何适配新国家**、核心流程、缓存机制、合规红线、常见问题与打包发布。
> 适用版本：dist_v67 / 源码 `pod_trend_agent/`

---

## 1. 项目概览

**目标**：为 POD（Print on Demand）出海业务自动捕捉海外热点 → 生成可打印的 T 恤印花设计 → 三图合成模特图 → 多语言标题 → 导出商品上传模板。

**技术栈**：Python 3.13 · LangGraph（7 节点流水线）· tkinter 桌面 UI · requests · Pillow · PyInstaller 打包

**两条运行路径**：

| 路径 | 触发条件 | 行为 |
|---|---|---|
| **缓存热点模式**（日常） | `output/<国>/collected_keywords.json` 存在 | 直接用采集缓存分配热点；简报不足时**从采集缓存自动生成简报**（轻量补齐），**绝不触发 Google** |
| **完整流水线**（首次） | 完全无缓存 | `seed → fetch → filter → score → screen → prompt_build → compose → product → seed_shot → template_export → oss_upload` |

---

## 2. 目录结构

```
pod_trend_agent/
├── ui_app.py                  # 桌面 UI：选品/采集/运行/模板/结果表格
├── cli.py                     # 命令行入口
├── config.yaml                # 全局配置（countries/sources/llm_screen/prompt_templates/compose/oss/product…）
├── configs/countries/<CC>.yaml# ★每国独立配置：种子词/related 种子/采集限额
├── prompts/<CC>/              # ★每国提示词：system_prompt.md + aesthetics.yaml
├── graph/
│   ├── agent.py               # LangGraph 流水线编排（START→seed→fetch→…→END）
│   ├── nodes/                 # 各节点实现（seed/fetch/filter/score/screen/prompt/compose/product/seed_shot/template/oss）
│   ├── product_batch.py       # 缓存热点批量流程：分配/三级去重/review 兜底/轻量补齐
│   ├── backends/              # 图像后端：openai_image_backend / mock_image_backend
│   ├── llms/                  # LLM 后端：openai_compat_backend（多模态标题）/ mock_backend
│   ├── seeds/                 # 种子策略：dynamic_strategy（统一池+加权随机）/ static / holidays
│   ├── sources/               # 数据源注册表：google_trends（pytrends，429 兜底）/ pinterest
│   ├── product.py             # 底图/模特查找（IMG_EXTS 全格式）、SKU 逻辑
│   ├── style_rules.py         # 风格/配色/构图规则 + sanitize_image_prompt + review 魔改引导
│   ├── paths.py               # config_root / project_root / runtime_root 路径解析
│   └── validate.py            # 校验 + with_fallback 兜底装饰器
├── templates/                 # 商品上传模板 + template_router.py（模板读写）
├── basemap/<款号>/<颜色>/     # 平铺底图（jpg/png…）
├── material_library/<品类>/   # 模特图（webp/jpg/png/avif…）
├── db/                        # 商品数据库（sqlite）
└── dist_vNN/                  # PyInstaller 打包产物（含全部数据）
```

---

## 3. ★适配新国家（核心章节）

以新增 **DE（德国）** 为例，完整步骤：

### 3.1 国家代码入列

`config.yaml`：
```yaml
countries:
  - US
  - GB
  - JP
  - AU
  - MX
  - DE        # ← 新增
```

### 3.2 每国配置 `configs/countries/DE.yaml`

```yaml
# 德国专属数据源配置
trending:
  enabled: true
  limit: 40            # Google Trends 抓取上限

style:
  enabled: true
  seeds:               # ★印花风格种子词（重点，越多越好，20~30 个）
    - lederhosen
    - alpine
    - berlin street art
    - bauhaus pattern
    - autobahn
    - ...

related:
  enabled: true
  seed_keywords:
    - ...

exclude_topics: []     # 黑名单热点（已用过/明确不分配的词，可选）
```

**种子词选词红线**（写配置时注意）：
- ❌ 会被 `review 兜底 _UNSUITABLE` 剔除的类目：`nails / recipes / lottery / weather / results / prices / jobs / mortgage / election…`（见 `graph/product_batch.py`）
- ❌ 品牌/版权/真实人物：`nike / disney / margot robbie / prison break…`
- ❌ 图像策略敏感词：`skull / skeleton / blood / gun / demon…`（生成时会被 `sanitize_image_prompt` 替换，主题会变味）
- ✅ 用各国**本土流行 + 全球趋势**的印花主题（2026 参考：retro vintage / 极简 typography / 自然户外 / 手绘涂鸦 / Y2K / coquette / western / 幽默 quote / 星座塔罗 / 植物线稿）

### 3.3 每国提示词 `prompts/DE/`

- **`system_prompt.md`**：screen 阶段 LLM 的角色/输出规则（风险判定、motif/art_style/color_palette/composition 四要素），**必须包含 "Return JSON…" 字样**（阿里云 MaaS 的 `response_format=json_object` 硬性要求）。
- **`aesthetics.yaml`**：
  ```yaml
  extra_style_rules: [...]     # 该国风格倾向（配色/构图/审美）
  extra_blacklist: [...]       # 该国合规红线词（德国：纳粹符号等）
  ```

### 3.4 节假日 `graph/seeds/holidays.py`

`_HOLIDAYS_BY_COUNTRY` 增加国家节日（名称/月/日/规则/窗口），节日种子词自动带权重 3.0 进入统一池：
```python
"DE": [
    ("Oktoberfest", 9, 21, "third_saturday", 30),   # 啤酒节（9 月）
    ("Weihnachten", 12, 25, "fixed", 25),           # 圣诞节
    ...
]
```

### 3.5 国家模板站点校验 `ui_app.py`

`_check_template_site` 的 `country_sites` 字典加国家→站点关键词：
```python
country_sites = {
    ...
    "DE": ("德国站", "德国"),
}
```
（模板「模版」sheet 第 1 行定位「经营站点」列 → 第 2 行站点名 → 与所选国家不匹配则**导入失败**，提示重新导入）

### 3.6 图像提示词模板 `config.yaml → prompt_templates`

`image_prompt` / `wearable_prompt` / `composite_prompt` 各加国家版本（`{motif}` 等占位符保持不变），注意：
- **提示词中不得出现任何背景描述**（"isolated on … background"、"no background scene"）——透明背景只由 `background="transparent"` 参数控制（官方要求）
- 不含安全规则段（"no politics / no religion / no hate / no violence / no sexual"——这些词本身会触发图像 API 内容政策拦截）

### 3.7 验证清单

```bash
python cli.py -c DE --provider mock          # mock 跑通全流程（不花钱）
python -c "from graph.seeds.dynamic_strategy import DynamicStrategy; ..."  # 验证种子池
# UI 打开 → 切 DE → 采集 → 运行
```

---

## 4. 核心流程详解

### 4.1 完整流水线（LangGraph 7 节点）

```
START → seed(种子词) → fetch(采集) → filter(过滤) → score(打分) → screen(风险筛选+简报)
      → prompt_build(提示词) → compose(设计稿) → product(合成/标题) → seed_shot(种草图)
      → template_export(模板) → oss_upload(压缩上传) → END
```
每个节点均套 `with_fallback` 兜底（失败不中断整体流程）。

### 4.2 缓存热点模式（日常入口，`ui_app` / `run_product_batch`）

```
判断：output/<国>/ 有 collected_keywords.json 或 design_briefs.json → 缓存模式
  → load 简报（简报不足 → _rebuild_briefs_from_cache 从采集缓存生成，不碰 Google）
  → assign_hotspots 分配（三级去重 + review 兜底）
  → product 节点批量处理（并发 ≤5，每 SPU 一线程）
  → 模板导出
```

### 4.3 热点分配与去重（`assign_hotspots`）

| 层级 | 逻辑 |
|---|---|
| ① 热点去重 | 本批优先不同 topic（热点1-风格1、热点2-风格1…） |
| ② 风格去重 | 热点用完后自动切：热点1-风格2、热点2-风格2…（同 topic 不同 art_style） |
| ③ 兜底 | 剩余未用指纹（低分热点也可）；**历史已用 (topic, style) 指纹绝不重复出** |
| review 兜底 | `_UNSUITABLE` 正则剔除不适合类目（美甲/食谱/彩票/天气/比分…），日志提示 |

### 4.4 种子词机制（`dynamic_strategy.py`）

- **统一池**：静态 style + 静态 related + 月份主题 + 节日 + LLM 动态 → 全部合并去重（跨类型同词权重累加）
- **权重**：节日 3.0 > 月份主题 2.0 > 静态/动态 1.0（加权随机抽取）
- **每次随机取**（加权不重复）；**用完全用**（池 ≤ 需要数时全部使用，不随机限量）
- 每国独立配置（`configs/countries/<CC>.yaml`），种子缓存 `.cache/seeds/`（按 国家+provider+日期，防 Google 429）

---

## 5. 缓存文件

| 文件 | 位置 | 作用 |
|---|---|---|
| `collected_keywords.json` | `output/<国>/` | 采集热点池（关键词列表） |
| `design_briefs.json` | `output/<国>/` | 简报池（topic/motif/risk/score/image_prompt…） |
| `used_designs.json` | `output/<国>/` | 已用 (topic, art_style) 指纹（成功生成才写入） |
| `.cache/seeds/` | 项目根 | 种子词日缓存（防 429 重采集） |
| `.cache/llm_screen/` | 项目根 | LLM 筛查缓存 |

> 注意：**失败产品不写 used_designs**（合成/设计失败的，热点下次仍可用）。
> 已用过不要的热点：直接从 `collected_keywords.json` / `design_briefs.json` 物理删除即可（如 8-22 的 18 个 GB 热点处理方式）。

---

## 6. 合规红线（最重要）

1. **review 判定**：screen 阶段 LLM 判定疑似商标/版权/真实人物 → `risk_level=review`；openai 模式下生成设计时**自动注入原创化魔改引导**（`REVIEW_REBRAND_HINT`：只做风格参考、禁止复刻 logo/商标/角色、换名换细节）
2. **提示词清洗** `sanitize_image_prompt`（生成设计前必过）：
   - 删除一切背景描述（透明背景由参数控制）
   - 删除内容策略触发段（`any text must be safe: no politics/religion/hate/violence/sexual…`）
   - 21+ 个敏感词安全替换（skull→smiley mascot、gun→star…）
3. **各国红线**：美国慎政治/宗教；德国慎纳粹符号（`aesthetics.yaml extra_blacklist` 扩展）；中东整体保守；真实人物一律不进
4. **review 兜底 `_UNSUITABLE`**：不适合类目自动剔除（分配源头拦截）

---

## 7. 图像生成与合成

### 7.1 设计稿生成（`compose` / `product` 的 `generate`）
- **透明背景**：`background="transparent"` 参数（compose/product 配置均已设）；**提示词不得提背景**
- 并发：compose 并发生成（`compose.design_workers` 默认 5）；product 阶段每 SPU 一线程，并发上限 5
- 底图/模特/设计 >2MB → 自动压缩到 <2MB 再上传网关（`_shrink_blob_to_2mb`）

### 7.2 三图合成（`product` 的 `print`，mark=1）
- 上传顺序：**图1 模特图 → 图2 印花设计稿 → 图3 衣服平铺底图**（与提示词角色一一对应）
- 图3 只提取衣服本身底色与面料材质（忽略平铺图背景/桌面/场景）
- 合成失败 → 退避重试 3 次（5/20/40s）；仍失败 → 跳过该产品（不生成标题、不写模板）
- 网关处理约 2-6 分钟属正常（重负载 img2img）

---

## 8. 模型与网络配置（`config.yaml`）

```yaml
llm_screen:          # LLM（screen/种子/标题共用）
  model: "qwen3.7-..."    # ★标题生成需视觉模型（qwen-vl 系列）；纯文本模型会 400
  base_url: "https://...maas.aliyuncs.com/compatible-mode/v1"
  api_key: "sk-..."       # 或环境变量 LLM_API_KEY

compose:             # 设计稿图像网关
  backend: "openai"
  model: "gpt-image-2"    # 支持 background=transparent
  base_url: "https://api.tofastcode.xyz"
  background: "transparent"

product:
  backend: "mock"         # openai / mock
  background: "transparent"
  concurrency: 5          # 合成并发上限（默认 min(任务数,5)）
```

**代理策略**：模型调用（LLM + 图像）一律直连（`NO_PROXY` + 环境变量级 `no_proxy=*`，用户挂 VPN 也不走代理）；**Google 采集（pytrends）走系统代理**（需要 VPN）。

---

## 9. 打包发布（每版流程）

```bash
# 1. 打包（不跑 self-test：会撞 Google 429，浪费 7-10 分钟）
pyinstaller -y PODTrendAgent.spec --distpath dist_vNN --workpath build_cleanNN

# 2. 补齐 dist 数据（必须，否则 exe 缺资源）
cp -r templates db basemap material_library configs prompts .cache dist_vNN/
cp config.yaml dist_vNN/

# 3. 拷贝最近缓存（output/<国>/*.json），避免 exe 首次运行重新采集
# 4. 验证：find_first_model_folder 能查到模特（material_library 拷贝不完整是常见坑）
```

---

## 10. 常见问题（FAQ）

| 现象 | 根因 | 解决 |
|---|---|---|
| 有缓存还去采集（Google 429 刷屏） | UI 判断只看 design_briefs，忽略 collected | v60+ 已修：有 collected 即缓存模式，绝不触发 seed/fetch |
| Google 429 / SSL EOF | 限流 | 换 VPN 节点；已采集后运行走缓存不再碰 Google |
| 三图合成全部超时 | 并发过高压垮网关 / 底图过大 | 并发上限 5 + 输入图压缩 <2MB + 退避重试 |
| 生成设计全是商标侵权 | review 简报未魔改 | v57+ 自动注入 REVIEW_REBRAND_HINT |
| 内容政策拦截频繁 | 提示词含敏感词/安全规则段/背景描述 | sanitize_image_prompt 自动清理 |
| 设计稿不透明（RGB 白底） | product 后端未配 background | `product.background: transparent` |
| 标题 400 | 模型不支持图片输入（非视觉模型） | 换 qwen-vl 系列视觉模型 |
| 模特找不到 | material_library 拷贝不全 / avif 不识别 | 全量拷贝；IMG_EXTS 已含 avif/gif/tiff |
| 生成的设计 6 个重复 | compose 只生成 safe 简报的设计 | v48+ 为全部简报（含 review）生成设计 |

---

## 11. 开发环境

```bash
python -m venv .venv
.venv/Scripts/pip install -r requirements.txt   # 或 uv sync（uv.lock 已锁定）
# 环境变量：LLM_API_KEY / LLM_BASE_URL / OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET
```

**对接新国家一句话总结**：`configs/countries/<CC>.yaml`（种子词）+ `prompts/<CC>/`（提示词）+ `holidays.py`（节日）+ `config.yaml countries 列表` + UI 国家下拉 + 模板站点映射 → mock 跑通 → 真 LLM 验证。