heqiangdiao-wq / AI-Cross-Border-Ecommerce-Agent-Toolkit

# AI Cross Border Ecommerce Agent Toolkit
**AI 跨境电商运营智能体工具箱** · *Turn cross-border ecommerce SOPs into reusable AI Agent workflows.*
---
## 这是什么
把**跨境运营 SOP 里沉淀的经验**，翻译成**可复制的 AI Agent 工作流**：一个标准 Prompt + 一份输入模板 + 一个真实案例，任何人都能拿去直接跑出可发布的商品素材。
不是软件，不是 SaaS，只做四件事：
| 交付物 | 说明 |
|---|---|
| 📘 运营方法论 | SOP 章节 → Agent 模块的完整拆解表 |
| 🧠 AI Prompt | 角色 / 任务 / 输入契约 / 输出契约 / 自检 |
| 🔁 工作流程 | 什么顺序跑、什么条件进入下一步、什么条件回流重改 |
| 📄 模板 + 案例 | 标准输入格式 + 真实产品的完整跑通记录（含复测数据） |
**为什么做这个**：跨境运营的难点不是"不知道要做什么"，而是"知道但做不出稳定下限的产出"。同一个类目，老手写标题一次到位，新人写十遍还是堆词。这套工具箱的目标是把老手的**判断规则**结构化，让 AI 的产出稳定在老手水平线上。
---
## 📎 原始资料来源
本仓库的方法论拆解自一份 38 页的内部运营手册，原文已随仓库提供：
📄 **《Shopee 巴西站运营 SOP 总框架》（PDF · 38 页 · 29.7 MB）**
SOP 章节与 Agent 模块的逐条对应关系见 `docs/00_Architecture_SOP_to_Agent.md`。
> ⚠️ **请注意**：这份 PDF 是**未经删改的原始内部手册**，其中包含平台明确禁止的做法（如刷单、诱导评价、虚假举报、参数虚标等）。
>
> **本仓库的 7 个 Agent 模块均未实现这些做法**：已识别项及其合规替代方案见 `docs/03_Compliance_Guard.md`，未实现项逐条登记见 `docs/05_SOP_Gap_Register.md`。
>
> 换句话说 —— **这份 PDF 是「原料」，不是「产品」。** 本仓库的产出物只包含合规路径。
---
## 🗂 Agent 全景
7 个模块，**全部已完成**。
| # | Agent | 中文 | 一句话职责 | 版本 |
|---|---|---|---|---|
| **01** | Market Research Agent | 市场分析 | 前置判断 / 容量 / 集中度 / 价格带（波谷检测）/ 配置组合 · **带计算脚本** | ✅ v0.4 |
| **02** | Product Strategy Agent | 产品策略 | 定位 / 配置 / 主推卖点收敛 / 定价模型 / SKU 四角色 · **净利率/盈亏价/券余量矩阵** · Skill 化 | ✅ v0.4 |
| 03 | Listing Creative Agent | 商品内容生成 | 关键词分类 → 标题 → 详情页 → 卖点/参数 · **字符实测/参数溯源校验** · Skill 化 | ✅ v0.4 |
| 04 | Product Image Agent | 主图与详情图 | 9 图规划 → 出图 Prompt → **像素级合规校验** · Skill 化 | ✅ v0.4 |
| 05 | Product Video Agent | 短视频生成 | 脚本 → 分镜 → AI 视频 Prompt → 配音字幕 | ✅ v0.4 |
| 06 | Advertising Optimization Agent | 广告优化 | 四类漏斗诊断 + 盈亏线核算 + **P0/P1/P2 分级动作** · Skill 化 | ✅ v0.4 |
| 07 | Review Analysis Agent | 评论分析 | 八类归因 + 误解型识别 → 详情页修补建议 | ✅ v0.4 |
> **这七个模块构成一条完整链路，而且是闭环的**：
>
> [code] 
>
> **为什么按这个顺序编号**：`01-02` 分析簇（前置链路）→ `03-04-05` 创意簇（素材产出）→ `06-07` 运营簇（数据回流）。
>
> ✅ 编号方案已确认。原始规划为 `03` Listing / `04` Advertising / `05` Review / `06` Video（且无 Market Research 与 Product Strategy 的独立编号），本仓库按工作簇重排，变更记录见 CHANGELOG。
---
## 🚀 快速开始
不需要 API key，不需要装环境。**三个文件就能跑。**
 [code] 
**第一次跑，建议按这个顺序**（以 Patinete Elétrico 为例，见 `Examples/`）：
 [code] 
三个关键点：
1. **01 带脚本**。指标（集中度、价格带、配置交叉表）由 `scripts/` 计算，**Agent 只负责解读**——能算的别让模型猜。
2. **02 决定卖点，03/04/05 才能开工**。主卖点必须收敛成**唯一一句**，否则主图打两行字、视频开头讲两件事，两个都记不住。
3. **06 和 07 会把结论回流到 03/04**。这一步是整套工具箱和"一次性生成工具"的分界线——产出的 Listing 会随着真实数据变准。见 `Examples/03_Closed_Loop/`。
---
## 📁 目录结构
 [code] 
案例产品覆盖（制作说明指定的五款）：Electric Scooter · Power Bank · Pet Carrier · Air Fryer · Thermal Bag ✅
每个 Agent 模块固定四个子目录：`prompts/` + `templates/` + `examples/` + `README.md`。
---
## 📱 平台支持
| 平台 | 状态 | 标题上限 | 主图规范 | 输出语言 |
|---|---|---|---|---|
| **Shopee** | ✅ 一等支持 | 120 字符（前 30 字符权重最高） | 白底，最多 9 图 | PT-BR / EN / 本地语 |
| **Mercado Livre** | ✅ 一等支持 | 60 字符 | 背景干净（白/纯色/实景按类目），主体 85–95%，≥1200×1200 | PT-BR / ES |
| Amazon | 📄 字段已适配 | 200 字符（建议 80） | 纯白底，≥1000×1000 | EN |
| TikTok Shop | 📄 字段已适配 | 按站点 | 竖版 9:16 优先 | 本地语 |
| Shopify | 📄 字段已适配 | 建议 70 | 无硬限制 | EN / 本地语 |
详细字段规范见 `docs/02_Platform_Output_