3218485270
f493bde8a9
- 缓存热点批量流程（有采集缓存不触发 Google） - 简报不足直接从采集缓存生成（轻量补齐） - 三图合成（模特/印花/底图）+ 底图压缩 <2MB - 热点去重→风格去重自动切换 + 不适合类目 review 兜底 - 透明背景（background=transparent）+ 提示词清洗（敏感词/背景描述） - 任务前 basemap 校验 + 模板国家校验 + 模特任务级分配
148 lines
9.6 KiB
Markdown
148 lines
9.6 KiB
Markdown
# POD 热点抓取 Agent（LangGraph 工程化版）
|
||
|
||
自动抓取海外各国（US / GB / JP / AU）实时热点 + 风格趋势，过滤侵权风险，产出可直接用于
|
||
AI 生图的印花设计提示词。本版本用 **LangGraph** 重写，强调**工程化、节点兜底、可插拔**。
|
||
|
||
## 架构：LangGraph 状态图
|
||
|
||
```
|
||
START → seed → fetch → filter → score → screen → prompt_build → compose → END
|
||
```
|
||
|
||
| 节点 | 职责 | 可插拔点 / 兜底 |
|
||
|---|---|---|
|
||
| `seed` | 动态生成种子词（trending 派生 + 历史热点 + 月份/节日 → LLM） | 策略可插拔（`graph/seeds/`）；LLM 失败回退静态种子 |
|
||
| `fetch` | 抓取热点（多数据源汇总） | 数据源可插拔（`graph/sources/`）；单源失败不影响其它源 |
|
||
| `filter` | 黑名单 + 真实人物 + 设计相关性三级过滤 | 各级独立 try，单级失败不影响其它级 |
|
||
| `score` | 归一化 + 跨源融合 + 综合分 | 纯逻辑，空数据返回空 |
|
||
| `screen` | LLM 合规筛查 + 结构化四要素 | LLM 后端可插拔（`graph/llms/`）；调用失败降级 Mock |
|
||
| `prompt_build` | 用固定模板装配 image/wearable/composite 提示词 | 四要素缺失时动态推导兜底 |
|
||
| `compose` | 写 `output/<country>/` 产物；可选印图 | 图像后端可插拔（`graph/backends/`）；无底图只导出 |
|
||
|
||
**每个节点都用 `graph/validate.with_fallback` 包裹**：任何未预料异常都被捕获、记入
|
||
`state['errors']`、返回最小更新，整图继续往下走，单点故障不中断流水线。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
pod_trend_agent/
|
||
├── cli.py # 命令行入口（替代旧 run/screen/compose）
|
||
├── config.yaml # 全局配置（数据源、权重、黑名单、LLM、模板、compose）
|
||
├── configs/countries/ # 各国专属数据源种子（US|GB|JP|AU.yaml）
|
||
├── prompts/<country>/ # ★ 每个国家不同的提示词单独文件夹
|
||
│ ├── system_prompt.md # 该国 LLM 系统提示（补充段，叠加到默认规则）
|
||
│ └── aesthetics.yaml # 审美 hint + 风格-配色 extra 规则 + 额外黑名单
|
||
├── graph/
|
||
│ ├── state.py # AgentState（共享状态）
|
||
│ ├── validate.py # with_fallback 兜底 + 数据校验
|
||
│ ├── loader.py # 配置/提示词加载与合并
|
||
│ ├── scoring.py # 归一化/融合/过滤（纯逻辑）
|
||
│ ├── style_rules.py # 动态风格/配色推导
|
||
│ ├── templates.py # 固定提示词模板（按国家区分，30×38cm 上限，文字敏感规则）
|
||
│ ├── classify.py # 热点分类
|
||
│ ├── sources/ # 数据源可插拔（google_trends / pinterest + 注册表）
|
||
│ ├── llms/ # LLM 后端可插拔（mock / openai_compat + 注册表）
|
||
│ ├── backends/ # 图像后端可插拔（openai）
|
||
│ ├── seeds/ # 种子词策略可插拔（static / dynamic + holidays 月份节日）
|
||
│ ├── nodes/ # 7 个流水线节点（含 seed）
|
||
│ └── agent.py # 构建并编译 StateGraph，run_country()
|
||
└── output/<country>/ # ★ 每个国家的产物独立文件夹
|
||
├── design_briefs.json # 含 国家/热点词/类别/风险/设计稿提示词/完整印图提示词
|
||
├── design_briefs.md
|
||
├── composite_prompts.json/md # 封装提示词包（印到底图用）
|
||
└── report.md # 各阶段统计 + 兜底错误记录
|
||
```
|
||
|
||
## 可插拔指南
|
||
|
||
- **加数据源**：在 `graph/sources/` 新建类继承 `DataSource` 实现 `fetch()`，在
|
||
`graph/sources/__init__.py` 的 `SOURCES` 登记；在 `config.yaml` 的 `sources:` 加入。
|
||
- **加 LLM 后端**：在 `graph/llms/` 新建类继承 `LLMBackend` 实现 `screen()`，在
|
||
`LLM_BACKENDS` 登记；`llm_screen.provider` 选择（openai/deepseek/qwen/moonshot 走 openai_compat）。
|
||
- **改种子词策略**：`seed_provider` 选 `static`（仅 yaml）/ `mock`（规则生成，零成本）/ `openai_compat`（真 LLM）。
|
||
动态策略收集 trending 派生 + 上轮 safe 历史热点 + 月份/临近节日上下文，由 LLM 后端生成种子词，
|
||
与 yaml 静态种子合并后注入 `style.seeds` / `related.seed_keywords`（`config.yaml` 的 `seed_provider_cfg` 限量）。
|
||
- **加国家**：建 `configs/countries/<CODE>.yaml`（种子词）与 `prompts/<CODE>/`（提示词），
|
||
在 `config.yaml` 的 `countries:` 加入即可，无需改代码。
|
||
- **加图像后端**：在 `graph/backends/` 实现 `ImageBackend`，`compose.backend` 配置后
|
||
用 `cli.py -c <国家> --base 底图.png` 印图。
|
||
|
||
## 用法
|
||
|
||
```bash
|
||
# 跑全部国家（默认 US GB JP AU）
|
||
python cli.py
|
||
|
||
# 只跑英国，Mock 兜底 LLM
|
||
python cli.py -c GB --provider mock
|
||
|
||
# 跑美国 + 真实 LLM（provider 已在 config.llm_screen 配好时可不传）
|
||
python cli.py -c US
|
||
|
||
# 提供平铺衣服底图，把设计印上去（需 config.compose.backend + api_key）
|
||
python cli.py -c US --base path/to/flatlay.png
|
||
```
|
||
|
||
## 桌面 UI（Tkinter 轻量版）
|
||
|
||
```bash
|
||
# 开发模式直接跑
|
||
python ui_app.py
|
||
|
||
# 无 GUI 自检（验证环境/核心链路，结果写入运行根 self_test_result.txt）
|
||
python ui_app.py --self-test
|
||
|
||
# 打包 exe（单文件、无控制台；数据文件打进 _MEIPASS，output/.cache 写在 exe 旁）
|
||
.venv/Scripts/pyinstaller -F -w --name PODTrendAgent \
|
||
--add-data "config.yaml;." --add-data "configs;configs" --add-data "prompts;prompts" \
|
||
--hidden-import pytrends --hidden-import pytrends.request ui_app.py
|
||
# 产物：dist/PODTrendAgent.exe
|
||
```
|
||
|
||
UI 功能：国家多选、LLM 后端选择（mock/static/openai_compat...）、种子上限、**SPU/颜色选品**、运行（后台线程 + 实时日志）、
|
||
结果表格（国家/热点/类别/风险/分数，双击看完整提示词）、打开产物目录。
|
||
打包后首次运行自动在 exe 旁创建 `output/` 与 `.cache/`，并生成一份**可编辑的默认配置**
|
||
（`config.yaml` / `configs/` / `prompts/`）；exe 运行时**优先读 exe 旁这份配置**（改了就生效），
|
||
exe 内置的作为兜底默认。想恢复默认：删掉 exe 旁对应文件即可。
|
||
|
||
## 产品图生成（product）
|
||
|
||
热点提示词 → SPU/颜色选品 → basemap 底图 → 印花图 → 模特试穿合成图，产物在 `output/<country>/product/`。
|
||
|
||
```bash
|
||
# 查看 db 可选款号 / 某款颜色
|
||
python cli.py --list-spus
|
||
python cli.py --list-colors DG004
|
||
|
||
# 指定款号+颜色跑流水线（product.backend=mock 占位 / openai 真生图需 compose.api_key）
|
||
python cli.py -c GB --spu DG004 --sku DG004-BL01
|
||
```
|
||
|
||
- 数据关系：`SPU.code`=款号，`SKU.code`=`款号-颜色编码`（如 DG004-BL01）；底图在 `basemap/<款号>/<SKU.code>/`，模特图在 `material_library/<品类>/`。
|
||
- 缺底图/模特图时对应步骤自动跳过并提示；`product.backend` 留空则仅存底图。
|
||
- **商品上传模板自动导出**：生成产品图后，从 db 读该 SPU/SKU 信息（材质/成分/图案/领型/面料/克重/印花类型/尺码表/边长/包装重量…），经 `templates/template_router.py` 的路由函数填入商品上传模板，
|
||
输出 `<SKU>_已填写.xlsx` 到 `output/<国家>/product/`。模板已自包含在项目 `templates/`（`config.product.template_path`，可改为自由上传）。
|
||
- 数据从模板第 6 行（数据区空行）开始填，SPU 与各尺码 SKU 紧邻；
|
||
- SKC货号：SPU 行=SPU.code、SKU 行=SKU.code；SKU货号暂不填；
|
||
- 规格类型2 = `{size}*{color}`；币种=CNY；发货仓1~N 取模板顶头按「、」分隔，库存均 200；
|
||
- 商品轮播图列名中/英/日变体均可模糊匹配；SPU 行轮播图1=生成首图，SKU 行轮播图2~5=db `img_url_2~5`（无则回退生成图）；
|
||
- 模板文件被占用（打开中）时自动换名 `<SKU>_已填写_N.xlsx`，不中断导出；
|
||
- **多颜色 + 模式**：`sku_code` 支持逗号分隔多颜色（如 `DG015-VT01,DG015-DARK HEATHER`）；`spu_per_color`（true=每颜色一个 SPU 块 / false=单 SPU 挂多颜色变体）；CLI 用 `--single-spu` 切单 SPU 模式，UI 用「颜色多选 + 模板模式」。
|
||
- UI 打开时**默认加载勾选国家的热点缓存**（`output/<国家>/design_briefs.json`）直接展示，点「运行」刷新最新。
|
||
|
||
## 数据流要点
|
||
|
||
0. `seed`（动态种子词）：收集 trending 派生（去噪 + 人名 + 风险护栏过滤）、上轮 safe 历史热点、
|
||
当前月份/临近节日，由 LLM 后端（mock 规则 / 真 LLM）生成动态种子词，与 yaml 静态种子合并注入抓取配置。
|
||
1. `fetch` 抓 `gt_trending`（国家 RSS 实时榜）+ `gt_style`/`gt_related`（风格/行业种子关联词，种子来自 seed 节点）。
|
||
2. `filter` 三级过滤：合规黑名单（全局 + 各国 `extra_blacklist`）→ 真实人物 → 泛新闻/科技/赛事词。
|
||
3. `score` 按 (source,kind) 分组 min-max 归一化、跨源融合加权重。
|
||
4. `screen` LLM 合规筛查，产出 risk_level / 四要素；`keep_review=false` 时丢弃待复核。
|
||
5. `prompt_build` 用四要素 + 固定模板装配 image/wearable/composite 提示词（结构一致、可复用 img2img）。
|
||
6. `product`（可选）SPU/颜色选品 → basemap 底图 → 印花图 → 模特试穿合成（`output/<country>/product/`）。
|
||
7. `compose` 写各国 `output/<country>/`；给底图则调图像后端印图。
|
||
|
||
> 合规红线（最重要）：版权/商标/真实人物/敏感内容一律拦截或降级；二创/重绘仍有风险，
|
||
> 拿不准进"待复核"。各国侵权盲区不同（如英国 WWE/游戏/乐队、日本动漫 IP），放在
|
||
> `prompts/<country>/aesthetics.yaml` 的 `extra_blacklist` 按国家隔离。
|