joey5628/ozon-seller-kit

Fork 0

Files

T

R524809 a925283bf7 feat: 加入插件开发计划

2026-08-07 17:37:16 +08:00

22 KiB

Raw Blame History

Seller Helper 方案设计 V2

面向 Ozon 跨境电商的 AI 选品搬运工具文档状态：方案探讨阶段（未开始编码）最后更新：2026-08-06 V1 见 方案设计.md，本文档为架构调整后的新版，V1 保留作为历史记录。

1. 背景与目标

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

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

目标工作流

① 浏览 1688/淘宝/拼多多商品页
      ↓ 插件侧边栏点「收集」（可指定文件夹）
② 素材汇入同一「文件夹」（文本 + 图片，可来自多个页面多次收集）
      ↓ 打开发布管理系统
③ 选择文件夹 → 进入该文件夹的发布页
      ↓ 左侧素材 → 加入对话框 → 写要求 → 调大模型
④ 右侧结构化表单被逐字段填充（俄文标题/描述/标签/规格）
      ↓ 图片：白底、图内翻译（按钮式）；AI 生图（对话式）
⑤ 挑选图片与头图、填价格 → 一键提交 Ozon 草稿

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

2. 与 V1 的核心差异

维度	V1	V2
插件职责	抓取当前页 → POST 后端	纯采集器：识别页面 + 归入文件夹 + 去重
采集单位	单次抓取 = 一个商品	文件夹：多页面多次收集汇入同一文件夹
发布页宿主	独立 Web 预览页	后端托管的发布管理系统，按文件夹进入
编辑交互	点选区域 → 弹对话框局部重生成	左素材 / 右表单 / 底对话框三栏工作台
AI 输出形态	生成文本填入预览	结构化字段补丁，逐字段接受/丢弃 + 版本历史
图片操作	统一走处理管线	确定性操作按钮化，AI 生图走对话
模型选择	固定 Claude	多模型可配置（文本/视觉/图像三类槽位）
Ozon 类目	上传前匹配	进入发布页即先定类目，用于渲染规格表单

未变化的部分：Python 图片微服务、对象存储、异步任务队列、Ozon 类目属性字典校验层。

3. 整体架构

浏览器
├─ Chrome 扩展（瘦客户端，只做采集）
│   ├─ Content Script    识别商品页 → 提取 {标题, 参数, 卖点, 图片URL[], 价格, 详情图文}
│   ├─ Side Panel        当前文件夹 ▾ / 本页抓到什么 / 「收集」按钮 / 最近素材
│   └─ Service Worker    唯一出网口：带 token 调后端；图片取不到时兜底抓字节
│                                     │ HTTPS
└─ 发布管理系统（普通 Web 应用，新标签页打开）
        ├─ 文件夹列表页    进度状态 / 素材数 / 创建时间
        └─ 发布页          左素材 · 右表单 · 底对话框
                                      │
后端服务（Next.js）                    │
├─ /api/folder            文件夹 CRUD、列表
├─ /api/material          写入素材（接受 URL 或二进制）+ 排队预下载图片
├─ /api/draft             草稿字段读写、字段版本历史、补丁接受/丢弃
├─ /api/chat              对话 → 调用可配置 LLM → 返回字段补丁
├─ /api/image/op          白底 / 图内翻译 / 生图（异步任务，返回 jobId）
├─ /api/job/:id           任务状态与进度（轮询或 SSE）
├─ /api/ozon/category     类目推荐 + 属性字典拉取与缓存
├─ /api/ozon/publish      属性字典校验 → 图片上传 → 建草稿
├─ 任务队列
└─ 凭证保管（各模型 key、Ozon Client-Id / Api-Key，加密存储）
      │
      ├─ Python 图片微服务   OCR / inpaint / 抠图白底 / 图生图编排
      ├─ 对象存储            原图 + 各衍生版本
      └─ 数据库              文件夹、素材、草稿、任务、Ozon 字典缓存
                                      │
                                      ▼
                             Ozon Seller API

设计原则：插件不持有任何密钥、不直接访问 Ozon 与模型服务；所有算力与凭证集中在后端。

4. 插件端设计

4.1 职责边界

插件只做四件事：识别页面、提取素材、归入文件夹、去重。不做生成、不做图片处理、不碰 Ozon。

预计代码量很小（几百行），好处是迭代频率低、无需频繁重新发布扩展；重逻辑全在后端和 Web 端，正常部署即可更新。

4.2 侧边栏（Side Panel）

用 Chrome Side Panel（Chrome 114+）而非 popup，浏览时可常驻不消失。

┌ Seller Helper ──────────────┐
│ 当前文件夹：儿童保温杯 ▾ [+新建] │
│ ─────────────────────────── │
│ 本页识别到：                  │
│  标题   儿童316不锈钢保温杯…  │
│  参数   12 项                │
│  卖点   3 段                 │
│  图片   9 张 [预览]           │
│ ─────────────────────────── │
│  [ 全部收集 ]  [ 选择性收集 ] │
│ ─────────────────────────── │
│ 该文件夹已收集：3 个来源 · 12 图 │
│  [ 打开发布页 ↗ ]             │
└─────────────────────────────┘

「当前文件夹」是载荷概念：多页收集必须先明确归属，否则容易串。支持在侧边栏直接新建。

4.3 与后端通信

必须走 Service Worker 转发。MV3 下 Content Script 发出的跨域请求受页面 CORS 约束；Service Worker 只要在 host_permissions 声明了后端域名即可直连。
鉴权：自用阶段用后端签发的长期 token，插件 options 页填一次存入 chrome.storage.local。后续如需多用户再换 OAuth。

4.4 图片获取的两条路

路径	场景	说明
优先：只传 URL	1688 主图 CDN（`cbu01.alicdn.com`）等公开可取	后端直接下载，插件负担最小
兜底：传二进制	需要 referer / 登录态才能取的图	插件在页面上下文 `fetch` 成 blob 后上传

因此 /api/material 接口需同时接受 URL 列表与二进制上传两种输入。

4.5 去重

多个来源页大概率有重复图。两级去重：

URL 归一化去重（去掉尺寸后缀等 query 参数）——插件侧即可完成。
感知哈希去重（pHash/dHash）——后端下载后计算，相似度超阈值的标记为疑似重复，发布页折叠展示。

4.6 预热

素材写入后端后立即排队预下载图片，并可选预跑一遍白底/OCR。用户还在浏览其他页面时后台就处理完了，进发布页时图片即时可用，不用干等。

5. 数据模型

Folder  文件夹
  id, name, status(collecting|editing|published), ozonCategoryId, createdAt

  └─ Material  素材
       id, folderId, type(text|image), sourceUrl, sourcePlatform, capturedAt
       ── type=text  : textKind(title|params|selling_point|desc|price), content
       ── type=image : originalUrl, storageKey, width, height, phash, dupOfId

       └─ Variant  图片衍生版本
            id, materialId, kind(original|whitebg|translated|aigen|upscaled)
            storageKey, params(JSON), jobId, createdAt

  └─ Draft  发布草稿（每个文件夹一份）
       id, folderId, fields(JSON), selectedVariantIds[], heroVariantId
       price, currency, ozonCategoryId, updatedAt

       └─ FieldVersion  字段版本历史
            id, draftId, field, value(JSON), source(ai|manual), messageId, createdAt

       └─ Message  对话记录
            id, draftId, role(user|assistant), content
            attachedMaterialIds[], attachedVariantIds[]
            modelUsed, resultPatch(JSON), patchStatus(pending|accepted|discarded)

  └─ Job  异步任务
       id, folderId, type(download|whitebg|translate|aigen|ozon_upload)
       status(queued|running|done|failed), progress, input(JSON), output(JSON), error

要点：

一张图 = 一个 Material + 多个 Variant。右侧挑图时是从所有 Variant 里挑，原图和白底图、翻译图、AI 图平级可选。
FieldVersion 独立成表，支撑逐字段回退。
Message 记录 resultPatch 与其接受状态，可追溯每个字段值是哪一轮对话产生的。

6. 发布页交互设计

6.1 布局

┌──────────────────────────────────────────────────────────────────────┐
│ 文件夹：儿童保温杯 · 3个来源 · 12张图     Ozon类目：保温杯 ▾  [发布]   │
├────────────────────────────┬─────────────────────────────────────────┤
│ 左：收集的素材               │ 右：生成结果（= Ozon 字段结构化表单）    │
│ ┌ 文本 ─────────────────┐  │ 标题(ru)          v3  ⟲历史             │
│ │ ☑ 标题 · 1688         │  │ ──────────────────────────────────      │
│ │ ☐ 参数表 · 1688       │  │ 简介/描述(ru)     待生成                │
│ │ ☐ 卖点 · 淘宝         │  │ ──────────────────────────────────      │
│ │ ☐ 详情文案 · 拼多多    │  │ 关键词标签        v1                    │
│ └───────────────────────┘  │ ──────────────────────────────────      │
│ ┌ 图片 ─────────────────┐  │ 规格属性（按类目字典渲染）               │
│ │ [□][□][□][□]          │  │   颜色▾ 材质▾ 容量▾ 尺寸 重量 …         │
│ │ [□][□][□] …           │  │ ──────────────────────────────────      │
│ │ 选中 → [白底][翻译]    │  │ 图片 [头图][2][3][4]  可拖拽排序         │
│ │        [加入对话]      │  │ ──────────────────────────────────      │
│ └───────────────────────┘  │ 价格  [____] ₽                          │
├────────────────────────────┴─────────────────────────────────────────┤
│ @标题·1688 @参数表 @img_03            模型: Claude Sonnet 4.5 ▾       │
│ 整理成符合 Ozon SEO 的俄文标题和描述…                        [发送]   │
└──────────────────────────────────────────────────────────────────────┘

左侧按「文本在上、图片在下」排列，均可多选并「加入对话」，在对话框上方以 chip 形式展示引用（类似 Cursor 的 @ 上下文引用）。

6.2 右侧是结构化表单，不是聊天输出区

这决定了接口契约：LLM 不返回自由文本，而返回字段补丁。

{
  "patches": [
    { "field": "title_ru",    "value": "Детский термос из стали 316...", "reason": "含核心关键词，58字符符合Ozon标题建议长度" },
    { "field": "tags",        "value": ["термос детский", "поилка", "316 сталь"] },
    { "field": "attributes.color",    "value": "Синий",  "dictValueId": 61234 },
    { "field": "attributes.material", "value": "Сталь",  "dictValueId": 58901 },
    { "field": "attributes.weight_g", "value": 320 }
  ],
  "notes": "参数表里未给出杯口直径，规格中该必填项仍需补充"
}

右侧对涉及字段展示新旧对比 + 逐字段「接受 / 丢弃」。

为什么必须这样：如果 AI 每次返回一整份内容整体覆盖右侧，用户手改过的标题会在下一轮对话被抹掉。补丁 + 逐字段接受是保护手工编辑的必要设计。

配套 字段级版本历史：每个字段保留若干版本（含 source=ai|manual），随时回退。

6.3 Ozon 类目先行

进入发布页的第一步是确认类目，因为右侧「规格属性」区的字段构成完全由类目字典决定——哪些必填、哪些是枚举、枚举有哪些合法值。

流程：

后端根据文件夹内已收集的标题/参数，让 LLM 推荐 3–5 个候选 Ozon 类目。
用户确认一个（可手动搜索改选）。
拉取该类目的属性字典（/v2/category/attribute，结果缓存）。
右侧按字典渲染表单：枚举项渲染为下拉、必填项标红。
之后 LLM 生成规格时，候选值被约束在字典内（见 §7.3），而不是自由生成完再去匹配。

6.4 图片：两类操作分开

类型	操作	交互方式	原因
确定性管线	抠图白底、图内中文→俄文、放大、裁剪	选中图片 → 点按钮 → 出新 Variant	参数化即可，无需自然语言
开放式生成	AI 生图 / 改图（"换成户外草地背景"）	加入对话框 → 写要求 → 发送	需求无法枚举，必须自然语言

两类操作产出统一落为 Variant，右侧挑图时平级可选。处理中的 Variant 显示占位与进度（来自 Job）。

6.5 对话框

上方 chip 区展示已引用的文本素材与图片素材，可逐个移除。
右侧下拉可临时切换本次调用的模型。
发送后流式返回，先出 notes 说明，再出 patches 落到右侧待接受状态。
图片素材送入视觉模型前先降采样，控制 token 成本。

7. 各模块技术方案

7.1 采集（数据入口）

沿用 V1 决策：浏览器插件，借用户真人登录态与真实环境，最不易被封。MVP 只支持 1688。

官方 API（1688 开放平台等）对个人几乎不开放；Playwright 无头浏览器最易触发风控。插件方案同时天然契合"多网站补充信息"场景。

7.2 文案生成（俄文标题/描述/标签）

引用的中文素材 → LLM → 俄文字段补丁，并按 Ozon 习惯做本地化 SEO。

用 structured output / tool calling 约束返回为补丁 JSON schema，不用自由文本再解析。
标题长度、关键词密度等 Ozon 规则写进 system prompt 与校验层双重保障。

7.3 规格属性映射（最容易翻车的一环）

难点：LLM 生成的颜色/材质/容量等值必须落到 Ozon 字典的合法枚举 id 上。

三步兜底：

召回：属性字典可能有上千个枚举值，先按关键词/向量召回 Top-N 候选塞进 prompt。
约束选择：让 LLM 从候选中选 dictValueId，而非自由生成字符串。
人工兜底：匹配不到或置信度低时，右侧该字段标记为"需人工选择"，提供搜索下拉。

发布前做一次必填项与字典合法性全量校验，不通过则阻止提交并高亮问题字段。

7.4 图片处理

能力	方案	难度
抠图白底	抠图模型（如 RMBG / SAM 系）+ 合成白底	🟢 低
图内中文→俄文 · 路线A	OCR 定位（PaddleOCR）→ inpaint 抹除 → 按原版式重排俄文	🟡 中，版式还原需调试
图内中文→俄文 · 路线B	多模态图像编辑模型直改	🟡 中，自然但版式可能偏移
AI 生图 / 改图	图生图，对话驱动	🟡 中，需控成本

沿用 V1 决策：A/B 两条路线都接，各产出一个 Variant，发布页对比挑选。

7.5 Ozon 上传

走 Seller API 商品导入流程（/v2/product/import、图片上传、类目属性）。上传为草稿，用户再去 Ozon 后台正式发布。

顺序：图片先上传拿到 Ozon 侧 URL → 组装商品 JSON（含校验通过的属性）→ import → 轮询 import 任务状态 → 回写结果到 Draft。

7.6 视频（三期）

硬字幕：逐帧 OCR + 抹除 + 重排，效果不稳定。
配音：STT → 翻译 → TTS 重配，相对可控。
一期不做。

8. 多模型配置

模型不是一类，至少三个槽位，各自独立配置 provider / model / key：

槽位	用途	候选
文本 LLM	生成俄文文案、规格映射、类目推荐	Claude / GPT / DeepSeek / Qwen 等
视觉 LLM	读图理解、从图里补参数、辅助 OCR 校对	Claude / GPT-4o / Qwen-VL 等
图像生成/编辑	生图、改图、白底、图内改字（路线B）	按需可插拔

要求：

全局默认 + 发布页对话框内临时切换。
密钥加密存储在后端，插件与前端均不接触。
抽象一层统一调用接口，避免绑死单一 provider。技术上倾向 Vercel AI SDK 之类的多 provider 统一层。

关于 Pi SDK（V1 §6 的待决策）：V2 下编辑循环的输出被收敛为"结构化字段补丁"，本质是 structured output + 工具调用，不是开放式 agent 任务；加上多模型可配置的需求，多 provider 统一层比 agent 框架更贴合。结论：一期不引入 Pi，用统一 SDK 自行实现对话循环；未来若确实需要 session 树 fork / 多方案分支，再评估引入。

9. 技术栈

Chrome 扩展   WXT（或 Plasmo）+ React + TailwindCSS，Manifest V3 + Side Panel
后端 / Web    Next.js（前后端一体，App Router）
数据库        PostgreSQL + Prisma
对象存储      S3 兼容（本地开发用 MinIO）
任务队列      MVP 用数据库任务表 + worker 轮询；并发上来再换 BullMQ + Redis
图片微服务    Python（FastAPI）：OCR / inpaint / 抠图 / 图生图编排
模型接入      统一多 provider SDK
进度推送      MVP 轮询 /api/job/:id；发布页体验优化时换 SSE
环境          Node 22 + Python 3.14（本机已就绪）

队列选型说明：一期刻意不上 Redis，用数据库任务表 + 单 worker 轮询即可满足单人使用的并发量，少一个部署组件。

10. 分阶段路线

一期 MVP

主链路：1688 多页收集到同一文件夹 → 发布页对话生成俄文文案 → 白底处理 → 挑图填价 → 推 Ozon 草稿。

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

脚手架：Next.js + Prisma + 数据模型建表 + MinIO 本地对象存储。
插件采集：WXT 脚手架 + 1688 页面识别 + 文件夹选择 + 收集到后端，打通原始数据。（无需任何密钥即可验证）
文件夹列表页 + 发布页骨架：左素材 / 右表单 / 底对话框三栏布局，素材可引用。
对话生成文案：对话 → LLM → 字段补丁 → 右侧逐字段接受 + 版本历史。
Ozon 类目层：类目推荐 → 拉属性字典 → 右侧规格表单按字典渲染 → 字典约束的规格映射。
Ozon 提交：图片上传 + 商品 import + 状态回写。先把纯文案（原图直搬）商品推成功。
图片白底：抠图管线 + Variant 机制 + 异步任务与进度。

二期

图内中文翻译双路线（A/B 对比）、AI 生图改图、多平台采集（淘宝/拼多多）、感知哈希去重、SSE 进度、类目属性智能映射优化。

三期

视频处理。

11. 关键风险与坑

风险	级别	应对
1688/淘宝/拼多多反爬	🔴 高	插件借真人登录态，已是最稳路线；仍需容忍页面改版导致选择器失效，做好降级提示
Ozon 类目属性字典匹配	🔴 高	召回 + 约束选择 + 人工兜底三层；提交前全量校验
右侧手工编辑被 AI 覆盖	🟡 中	字段补丁 + 逐字段接受 + 版本历史（§6.2）
图片 Variant 存储膨胀	🟡 中	定期清理未被选中的 Variant；原图按需保留
视觉模型调用成本	🟡 中	图片送模型前降采样；对话上下文限制引用图片数量
页面 DOM 提取不可信输入	🟡 中	采集内容视为不可信，进 LLM 前做清洗；后端不给模型任何文件/命令执行能力
图内翻译版式还原	🟡 中	A/B 双路线并存，人工挑选

12. 已确认决策 / 待办

已确认

采集方式：浏览器插件，只做采集，先支持 1688。
采集单位：文件夹，多页面多次收集汇入同一文件夹。
发布页宿主：后端托管的发布管理系统（Web 应用），不打包进插件。
发布页布局：左素材（文本上 / 图片下）· 右结构化表单 · 底对话框。
右侧形态：Ozon 字段结构化表单，AI 返回字段补丁，逐字段接受，带版本历史。
图片操作：确定性操作按钮化，AI 生图走对话；结果统一为 Variant。
图内文字翻译：A/B 两条路线都接，发布页挑选。
模型：多模型可配置，文本 / 视觉 / 图像三类槽位，密钥仅存后端。
编辑循环：不引入 Pi SDK，用多 provider 统一 SDK 自行实现。
Ozon 交互：插件不直接访问 Ozon，全部经后端。

待用户提供（不阻塞前 4 步）

Ozon Seller API 的 Client-Id / Api-Key（沙箱或正式）——用于第 5–6 步。
模型 API Key（文本 / 视觉 / 图像各一）——用于第 4 步及图片处理。
富文本描述模板（哪怕草稿版）——用于描述字段的结构设计。
图像编辑模型偏好（无偏好则做成可插拔，白底先用开源抠图模型跑通）。

待决策

文件夹与 SKU 的关系：一个文件夹固定产出一个商品，还是允许拆成多个变体商品（多颜色/多规格）？
素材是否需要跨文件夹复用（如通用尾图、品牌图）？
是否需要发布历史与"再次编辑已发布商品"的能力。

22 KiB Raw Blame History Unescape Escape