# Seller Helper 方案设计

> 面向 Ozon 跨境电商的 AI 选品搬运工具
> 文档状态：方案探讨阶段（未开始编码）
> 最后更新：2026-08-05

---

## 1. 背景与目标

在 Ozon 做跨境电商，货源来自 1688 / 淘宝 / 拼多多。当前痛点：

- 单个门店的商品图片、信息往往不完善，需要**跨多个网站抓取**补齐。
- **图片最麻烦**：图里的中文需要转成俄文，甚至需要 AI 美化重做。
- 信息要**一条条手动填进 Ozon 商品编辑页**，耗时。
- 部分商品带**视频**，视频里的中文也可能需要替换成俄文。

### 目标效果

粘贴一个或多个卖家网站 URL → 程序自动：

1. 抓取商品信息、图片、包装信息等资源；
2. 生成**俄文标题、标签、简介、富文本**（富文本用固定模板，图文内容由程序生成）；
3. 抓取合适的图片并**翻译中文 / AI 美化**；
4. 提供**预览页面**，可点选某区域，通过**与 AI 对话**修改选中内容（文本或图片）；
5. 满意后提交，调用 **Ozon Seller API** 上传到后台（用户再去 Ozon 后台正式发布）。

Ozon Seller API 文档：https://docs.ozon.ru/api/seller/zh/

---

## 2. 可行性总览

**结论：能实现，大部分模块是成熟技术。** 全流程真正的难点只有两个：

- 🔴 **从 1688/淘宝/拼多多稳定抓取**（反爬）
- 🔴 **视频里的中文替换**（工程量大、效果不稳定）

其余模块可靠可控。

| 模块 | 难度 | 说明 |
|---|---|---|
| ① 抓取商品信息/图片 | 🔴 高（反爬） | 三个平台都有强反爬，最脆弱的一环 |
| ② 生成俄文标题/标签/简介 | 🟢 低 | LLM 直接做，质量高，可顺带做 Ozon SEO |
| ③ 图片中文→俄文 | 🟡 中 | OCR 定位 + 抹字 + 重排，或图像编辑模型直改 |
| ④ 图片 AI 美化 | 🟡 中 | 图生图，效果好但要控成本 |
| ⑤ 富文本内容生成（模板+图文） | 🟢 低 | 模板注入 + LLM 填内容 |
| ⑥ 预览 + 点选对话式编辑 | 🟡 中 | 标准 Web 应用 + AI 编辑循环，工程量在交互 |
| ⑦ 上传 Ozon | 🟢 低-中 | API 清晰，难在**类目属性字典**要匹配对 |
| ⑧ 视频中文替换 | 🔴 高 | 建议放到二期/三期，单独立项评估 |

---

## 3. 各模块技术方案

### ① 抓取（数据入口）

官方 API（1688 开放平台、淘宝开放平台、多多进宝）对个人几乎不开放。三条可选路线，从稳到脆：

1. **浏览器插件方案（✅ 已选定）**：Chrome 扩展，用户正常登录浏览时点「抓取」，插件读取当前页面已渲染的 DOM/接口数据发给后端。**借用用户真人登录态与真实环境，最不易被封**，且多网站补充信息的场景天然契合——在哪个页面就抓哪个。
2. 第三方"商品详情"数据 API：按次收费，省心但有费用、字段可能不全、依赖第三方稳定性。
3. Playwright 后端无头浏览器：灵活但最易触发风控，维护成本高。

> **决策：MVP 采用浏览器插件抓取，先只支持 1688。**

### ② 文案生成（俄文标题/标签/简介）

用 Claude 把抓取的中文信息 → 生成俄文标题/关键词标签/卖点简介，并按 Ozon 习惯做本地化 SEO。质量最有保证，是核心价值区。

### ③ 图片文字翻译（中文→俄文）

两条路线，**已决定都接，预览页让用户对比挑选**：

- **路线 A · 传统管线（版式高度还原）**：OCR 定位中文（如 PaddleOCR）→ inpaint 抹除 → 按原版式重排俄文。可控、可批量，适合规格参数图，排版还原需调试。
- **路线 B · 图像编辑模型直改（效果自然美观）**：用多模态图像编辑模型直接"把图里中文换成俄文/美化"。上手快、出图自然，但排版可能与原图有差异，需控成本与一致性。

### ④ 图片 AI 美化

图生图，效果好但要控成本。与路线 B 共用图像编辑模型能力。

### ⑤ 富文本内容生成

用户提供固定模板（含占位符），程序把生成好的图文填进模板。

### ⑥ 预览 + 点选对话式编辑

Web 页面渲染最终商品卡；每个可编辑区域（某段文字、某张图）可点选 → 弹出对话框 → 用户下指令 → 局部重生成。标准的"AI 编辑循环"，工程量在交互设计。（Pi SDK 的适用性见第 6 节。）

### ⑦ Ozon 上传

Ozon Seller API 有完整的商品导入流程（`/v2/product/import`、图片上传、类目属性）。**核心坑是类目属性字典**：每个类目有强制属性，值必须来自 Ozon 字典（`/v2/category/attribute` 拉取），不能随便填。需做"属性映射 + 字典校验"层。上传后用户在后台正式发布。

### ⑧ 视频中文替换（二期/三期）

- 硬字幕（烧进画面的中文）：逐帧 OCR + 抹除 + 重排，效果不稳定。
- 配音：STT → 翻译 → TTS 重配，相对可控。
- **建议一期先不做，或只做"音频重配"子集，单独立项评估。**

---

## 4. 推荐架构 / 技术栈

```
┌─ Chrome 扩展（抓取，借用户登录态）
│      │ { 标题, 参数, 图片URL[], 价格, 详情图文 }
▼
Next.js 后端（前后端一体）
  ├─ /extract   规整原始数据
  ├─ /generate  Claude → 俄文标题/标签/简介 + 富文本(模板占位)
  ├─ /image     队列任务：路线A(OCR+抹字+重排) / 路线B(图像编辑模型) 两版都出
  ├─ 图片服务   Python 微服务：OCR/inpaint + 图像编辑模型
  ├─ 任务队列   图片/视频异步处理（BullMQ）
  └─ /ozon      类目属性字典校验 + 上传草稿
▼
对象存储（图片/视频）
▼
前端预览页（React）：点选区域 + 对话式编辑；图片 A/B 两版切换
```

- **主栈 Next.js**（前后端一体）。
- **图像/OCR 用 Python 微服务**（生态最好）。
- 长任务用队列（BullMQ）。
- 环境：Node 22 + Python 3.14（本机均已就绪）。

---

## 5. 分阶段路线

### 一期 MVP（已选：文案为主链路）

**主链路目标**：1688 商品页点插件「抓取」→ 后端生成俄文文案+富文本 → 预览页可对话改文案 → 一键推 Ozon 草稿。图片一期先"原样搬运 + 可选翻译/美化"，两条路线并存供挑选。

落地顺序（每步可独立验证）：

1. **脚手架**：Next.js 项目 + 目录结构 + 环境变量（Claude key、Ozon key、图片模型 key）。
2. **Chrome 扩展**：先只做 1688，抓取当前页 → POST 到本地后端，打通原始 JSON。
3. **文案生成**：Claude 中文数据 → 俄文标题/标签/简介 + 富文本（占位符注入）。
4. **预览页 + 对话式改文案**：渲染商品卡，点选文字区域 → 对话局部重生成。
5. **Ozon 适配层**：拉类目属性字典 → 校验 → 上传草稿。**先把纯文案（无图）商品推成功。**
6. **图片双路线**：接 OCR 抹字重排（A）+ 图像编辑模型（B），预览页出两版供选。

> 步骤 1、2 无需任何密钥即可先跑起来看到效果。

### 二期

多平台抓取（淘宝/拼多多）、图片美化、点选对话式改图、类目属性智能映射。

### 三期

视频处理。

---

## 6. Pi SDK 适用性评估

**Pi**（Earendil 出品，MIT 开源，`@earendil-works/pi-coding-agent`）是可嵌入的 **AI 编码 Agent 框架**（TS/JS）。核心：Session + 事件流、自定义工具 `defineTool()`、内置工具 `read/bash/edit/write/grep/find/ls`、消息队列 `steer()`/`followUp()`、Session 树 fork/clone、子 agent、可切换模型（能接 Claude）。文档：https://pi.dev/docs/latest/sdk

### 判断：外科手术式使用——只用在一个地方

**✅ 强契合：预览页「对话式编辑」循环**

该交互本质是带工具的 agent 会话，Pi 能力几乎量身定做：

| 需求 | Pi 对应能力 |
|---|---|
| 点选区域后对话改内容 | `AgentSession` + 自定义工具 `editText`/`regenText`/`editImage`/`swapImageVariant` |
| 改到一半想换方向 | `steer()` 打断当前回合 |
| 改完这段再改那段 | `followUp()` 排队 |
| 回退 / 多方案对比 | **Session 树 fork/clone**（天然 undo + A/B 分支） |
| 前端实时看 AI 在改什么 | 事件流喂 UI |
| 长对话不爆上下文 | 内置 compaction |

自己用 Anthropic SDK 手撸需实现打断、排队、分支、压缩——Pi 白送。

**❌ 不建议：抓取→文案→图片→上传 主管线**

这是确定性 ETL，非开放式 agent 任务。用 agent 框架包会引入不必要的非确定性，**上传 Ozon 那步尤其不能让 agent 自由发挥**。用普通代码 + 直接 Claude API 更可控、好测。

> 原则：**流程固定的用管线代码；开放式、要来回对话的用 Pi。** 只有编辑循环属于后者。

### 两个坑

1. **默认内置工具含 `bash/edit/write`，服务端必须关掉。** 抓取来的网页内容是不可信输入（提示注入风险），若 agent 带 bash/写文件能力，可能被诱导在服务器执行命令。**用 Pi 时禁用全部内置工具，只暴露自定义业务工具，并做沙箱。**
2. **依赖成熟度**：Earendil 较新，把产品核心交互绑上去有第三方风险。好在能接 Claude，LLM 层不锁定；真不行可退回自己用 Anthropic SDK 撸编辑循环。

### 待定决策

编辑循环实现方式：

- **A) 用 Pi**：省事，白送打断/分支/压缩。
- **B) 用 Anthropic SDK 自撸**：少一个第三方依赖，需自己实现打断/分支。

**倾向建议**：一期先用 Anthropic SDK 把编辑循环跑通（简单版），Pi 作为二期需要 undo/多方案分支时的增强再引入，避免一上来被新框架卡住。**（未最终拍板）**

---

## 7. 已确认决策 / 待办

### 已确认

- 抓取方式：**浏览器插件**（先支持 1688）。
- 一期 MVP：**文案为主链路**。
- 图片文字翻译：**A/B 两条路线都接，预览页挑选**。

### 待用户提供（不阻塞脚手架）

- **Ozon Seller API 的 Client-Id / Api-Key**（沙箱或正式）——用于步骤 5。
- **富文本模板**（哪怕草稿版）——用于步骤 3 占位符设计。
- **图像编辑模型偏好**（无偏好则做成可插拔，A 路线先用开源 OCR 跑通）。

### 待决策

- 编辑循环：用 Pi（A）还是 Anthropic SDK 自撸（B）。