Manai Conversion

---
name: manai_conversion
description: 商品数据整理、处理与转换专家。支持处理凌乱的原始商品物料（Excel与图片）或已有结构化数据，智能拆分SPU并校验完整性，引导用户补充缺失物料，进行文字翻译、价格计算以及图片修改（去水印、文字翻译、背景修改与场景生图等），生成符合目标电商平台规格要求的Excel（两级合并表头）及媒体目录。
title: ManAI商品物料整理与转换
example: 将“女式拖鞋”文件夹中的凌乱图片和属性表，整理并转换为符合拼多多格式的商品物料。将价格乘1.2倍、库存统一修改为500，并将商品主图的中文翻译为英文、清除水印。
version: 1.0.0
---
# E-commerce Product Material Organization and Conversion SKILL

本 SKILL 指引 Agent 扮演**商品数据整理、处理与转换专家**，将用户提供的不确定格式的原始商品物料（可能包含凌乱的 Excel/CSV 报表、无序目录、散落图片等）或已经结构化整理好的商品物料，转换并归档为符合目标平台（如拼多多）规格和要求的标准化商品上架数据。支持在此过程中进行表格翻译、价格调整、数据补充，并利用 AI 生图技能对商品图进行处理与生成。

---

## 1. 输入确认与交互原则

在开始执行转换或整理任务前，Agent 必须通过对话明确并确认以下参数，**引导用户提供所需信息**：

1. **源物料目录 `input_dir`**：可以是无序的杂乱目录，也可以是已经按 SPU 归档的结构化商品文件夹。
2. **目标平台 `target_platform`**：默认为 **`拼多多`**。
3. **目标地区/国家与语言 `region_and_language`**：
   - 目标语言：默认为 **`中文`**。
   - 目标国家/地区：默认为 **`中国大陆`**。
   - **🚨 跨国/海外平台特别规则**：如果用户指定的目标平台是海外电商平台（如 **Temu、Shopee、Amazon、eBay、Shopify、TikTok Shop、AliExpress** 等），Agent **必须主动询问**并确认用户期望销售的**目标国家/地区**与**目标语言**，以便进行本土化适配。
     - 例如：若目标平台为 **Temu**，且目标国家为**英国 (UK)**，则应自动选择 **英语 (English)** 作为目标语言，商品定价币种转换为 **英镑 (GBP)**，且相关图片上的文字和模特规格等均应适配转换为**英语**。
4. **价格与库存调整规则**：如“供货价和零售价乘以 1.2”、“库存统一修改为 500”、“价格由人民币换算为目标国家货币（按指定或实时汇率）”等。
5. **图片处理与生成需求**：如“去除水印”、“将图片上的中文翻译为目标语言”、“比例调整为 1:1”、“把背景替换为纯白”或“利用 AI 生成高端厨房场景的主图”等。
6. **本地保存目录 `output_dir`**：明确询问用户希望将整理及转换后的结果保存到本地哪一个目录。**禁止使用固定的默认路径。**

### 🚨 输出目录安全原则（防覆盖）
**切记！不得在原始目录内直接进行就地整理或修改（以防破坏或覆盖用户的原始文件）**。
转换生成的全部数据与目录必须统一建立在指定的本地保存路径下。若用户未指定保存路径，则退路默认为全局配置中的 `data_directory` 文件夹。
输出的子目录命名格式必须为：`{target_platform}商品转换{YYYYMMDDHHMM}`（例如 `拼多多商品转换202606201200`）。

> **⚠️ 运行前提示与交互话术示例：**
> "您好！我是您的商品数据处理与转换专家。为了帮您生成最符合目标平台要求的商品上架物料，请您先提供以下信息：
> 1. 您的商品原始物料目录绝对路径（包含图片和属性表）；
> 2. 目标平台（默认：拼多多）；
> 3. 目标地区/国家与目标语言（若是海外平台如 Amazon/Temu 等，请务必告知具体国家如美国、英国、日本，以便我们适配相应的币种、价格汇率和图片/文字语言）；
> 4. 是否有价格调整（如乘以汇率或加价倍率）、库存设置的特殊要求；
> 5. 是否有图片修改需求（如去水印、翻译图上文字、生成白底图或生成场景图等，图上文字翻译将自动对齐目标国家语言）；
> 6. 整理转换后的文件保存目录路径（例如 `D:/MyData`。若未指定，我将默认保存在全局配置的 `data_directory` 下的 `{目标平台}商品转换{当前时间}` 中。我绝不会修改您的原始文件）。"

---

## 2. 核心处理流程

### 第一步：初始化输出目录与日志
1. 根据用户指定的保存路径（或退路路径）创建对应的 `{target_platform}商品转换{当前时间}` 文件夹。
2. 在该文件夹下创建 `商品转换.log` 审计日志，记录转换开始时间、输入参数以及待处理的商品源信息。

### 第二步：输入模式识别与解析
Agent 需分析 `input_dir` 内的文件和目录结构，识别输入属于以下哪种模式：

* **模式 A：凌乱原始数据（需智能整理）**
  1. **SPU 拆分**：将无序物料按商品款式进行 SPU 拆分，每一个 SPU 必须对应一个独立的商品目录。
  2. **SPU 目录命名规范**：命名格式必须严格遵循 `{顺序数字序号}{主要商品名}`。例如，第一个 SPU 名称为"云感EVA人字拖"，则其目录命名为 `001云感EVA人字拖`。禁止简化或缩写为无意义代称（如 `款式_01`）。
  3. **SKU 识别**：识别出每一个 SPU 下属的 SKU 属性组合（如颜色、尺码等）。
  4. **图片归纳**：扫描目录下的图片，尝试将它们归纳到 SPU 目录下的 `商品主图/`、`商品详情页图/`、`颜色规格图/` 等子目录中。
* **模式 B：结构化数据（直接转换）**
  1. 直接读取已划分好的 SPU 目录，定位到其中的 `*.xlsx` 数据表以及各个图片文件夹。

### 第三步：完整性校验与用户引导补全
在整理或解析出每个 SPU 及其 SKU 信息后，Agent 必须对物料的完整性进行评估，检查是否缺失以下关键数据：
- **属性缺失**：是否缺少 `商品名称`、`供货价`、`零售价`、`库存`。
- **图片缺失**：是否缺少主图、详情页图、颜色规格图（SKU 单样图）。

**🚨 引导机制**：若发现缺失，Agent **必须主动询问用户**。
- *数据缺失提示*：“在整理 SPU `{商品名}` 时，发现缺失了供货价/零售价/库存信息，请问需要为您默认设置成什么数值，还是您现在提供给我？”
- *图片缺失提示*：“在 SPU `{商品名}` 下未找到商品主图/详情图。请问您是否可以补充提供图片？或者您需要我调用 AI 生图工具为您生成相应的商品图片？”

---

## 3. 标准化转换规则

对于通过校验或补全的商品，执行以下标准化转换操作：

### 1. Excel 表数据翻译、修改与生成
每个 SPU 目录下必须包含一个 Excel 文件，命名为 `商品数据-<SPUID>.xlsx`，记录该 SPU 下所有的 SKU 属性：
- **一物一行**：一行代表一个 SKU。
- **价格与库存计算**：根据确认的调整规则（如价格乘以倍率、按目标国家货币汇率折算、统一库存）使用临时 Python 脚本（必须存放在**沙盒执行目录**的 `temp/` 文件夹内，绝对路径类似于 `<沙盒执行目录>/temp/`，禁止在用户的数据或输出目录下创建，用完即删）修改价格与库存字段。如果是海外平台且涉及不同国家，必须使用该国家的官方货币（如英国用英镑 GBP、美国用美元 USD、日本用日元 JPY 等）并按汇率折算价格。
- **语言翻译与本土化要求**：若目标平台及国家对应的语言与源数据语言不同（如源数据为中文，目标语言为英文、日文等）：
  - 必须将 Excel 表中所有文本类内容（包括商品标题、商品描述、SKU 属性名、SKU 属性规格描述、尺码与颜色规格等）完全翻译为目标国家/地区的语言。保持专有名词或型号代码原样。
- **🚨 两级表头与合并单元格（必须严格执行）**：
  - 商品数据表必须使用两级表头：**第一行是字段分组标题，第二行是具体字段名**。
  - 第一行中同一分组下的连续字段必须横向合并单元格，以明确第二行字段的归属。
  - 典型分组示例：
    - `品类` (包含: 叶子类目)
    - `商品名称` (包含: 商品标题)
    - `商品属性` (包含: 品牌、材质、产地、适用季节等)
    - `商品规格` (包含: 颜色、尺码、规格等)
    - `价格与库存` (包含: 供货价、零售价、库存、商家编码)
    - `服务与承诺` (包含: 运费模板、售后保障)
  - 即使单列字段不需要横向合并，第一行对应的位置也必须填入相应的字段分组标题。

### 2. 图片处理与 AI 生图工具调用
对于需要处理或补充的图片（如去水印、翻译图上文字、更换背景、生成高端展示图或缺失图片补充），Agent 必须调用 **`manai_image_generation`** 技能的 MCP 接口：

- **调用准备**：
  - 提取商品的名称与卖点。
  - 撰写包含图片修改或生成要求的精细化英文 Prompt（例如：`Product photography of 001 Cloud Comfort Slide Sandal, modern studio lighting, clear of any watermarks or logos, white background`）。
- **工具决策**：
  - **单张自定义图片处理/去水印/翻译文字**：使用 `generate_base_image` 接口，传入 `prompt` 以及原图的 URL 或 Base64（最多3张参考图）作为 `images` 参数。
  - **批量生成电商套图（如白底图、主图、细节图）**：使用 `generate_ecommerce_images_direct` 接口，并指定 `modules` 列表（如 `["white_bg", "hero", "detail"]`）。
  - **AI 模特穿戴换装**：使用 `generate_clothing_try_on` 接口。
  - **爆款复刻**：使用 `generate_viral_replica` 接口，参考竞品排版生成同款。
- **接口调用方式**：通过执行 `manai_conversion` 自带的 MCP 客户端脚本（不直接使用 Hermes 的内置 MCP 客户端以避免协议不兼容）：

  **🚨 Windows 命令行参数过长报错防范规避（极其重要）**：
  在 Windows 下执行命令行时，如果调用的 JSON 参数很长（例如包含 Base64 编码的参考图、大段 prompt 或复杂的配置项），直接在命令行参数中传入 JSON 字符串会触发 **Windows 命令行参数过长（最大 8191 字符限制）** 的系统报错。
  
  **正确的调用流程规避方案**：
  1. 将所有 JSON 格式的参数保存至临时 JSON 文件中，必须放在沙盒执行目录的临时目录下，绝对路径命名如 `<沙盒执行目录>/temp/mcp_args.json`，禁止在用户输入/输出目录中创建；
  2. 调用时使用 `-f` 或 `--file` 参数来指向该绝对路径的临时文件运行脚本：
     ```bash
     python D:/Project/manai_worker/skills/manai_conversion/scripts/manai_mcp_client.py <tool_name> -f <沙盒执行目录>/temp/mcp_args.json
     ```
  3. 执行完成后，**必须立即删除** 该临时文件，不可残留在环境里。
  
  仅当 JSON 参数非常短时，方可直接在命令行传参：
  ```bash
  python D:/Project/manai_worker/skills/manai_conversion/scripts/manai_mcp_client.py <tool_name> '<json_arguments>'
  ```
  *(注：该脚本会自动从全局配置 `conf/global_config.json` 加载 API Key `image_key`。若加载失败，Agent 须主动询问用户提供 API Key，并在调用时通过 `--api-key sk-xxxx` 参数传入。)*

> [!IMPORTANT]
> **默认服务地址与本地开发机说明 (Default Server & Local Dev Service)**：
> - 本技能默认都是访问远程云端平台 **`https://manai.cc`**。
> - 只有在特别说明的本地开发机（Local Dev Machine）上，才会存在运行于 **`5678`** 端口的本地服务（用于访问本地测试后台及进行静态图片资源下载与渲染）以及运行于 `5688` 端口的本地 MCP 接口。在没有特别说明的情况下，严禁默认尝试建立 5678 端口的本地连接。

- **下载与归档**：生图完成后，将生成的图片下载并保存到目标商品目录下对应的图片分类文件夹（如 `商品主图/`、`商品详情页图/`、`颜色规格图/`）中。

---

## 4. 输出结构规范

转换后的目录和文件结构必须如下所示：

```text
<指定的本地输出目录>/{target_platform}商品转换{YYYYMMDDHHMM}/
├── 商品转换.log                           # 记录本次转换的审计日志
└── 001女款增高厚底人字拖/                 # 转换后的商品 SPU 目录 (命名格式: {三位序号}{商品名称})
    ├── 商品数据-<SPUID>.xlsx               # 修改、翻译并标准化的 SKU 数据表 (两级合并表头)
    ├── 商品主图/                           # 转换、修改或生成后的主图
    ├── 商品详情页图/                       # 转换、修改或生成后的详情图
    └── 颜色规格图/                         # 转换、修改或生成后的颜色规格图 (SKU单样图)
```

---

## 5. `商品转换.log` 审计日志规范

在转换完成后，在输出根目录下生成 `商品转换.log` 文件。该文件详细记录转换的执行参数、处理状态和结果审计。

### 审计日志格式示例：
```text
[2026-06-20 08:30:00] 开始商品上架物料整理与转换任务。
目标平台: 拼多多
目标语言: 英文 (English)
价格规则: 价格乘以倍率 1.2
图片规则: 翻译中文文字为英文, 清除水印
输出路径: D:/MyData/拼多多商品转换202606200830/

--------------------------------------------------
SPU 序号: 001
主要商品名: 女款增高厚底人字拖
转换状态: 成功
SKU 数量: 4
数据修改: 供货价与零售价已乘以 1.2, 库存统一为 500, 所有文字属性（标题、尺码、颜色等）已翻译为英文
图片处理: 
  - 主图: 共 3 张。调用 generate_base_image 进行了去水印和文字翻译。
  - 详情页图: 共 5 张。完成格式转换。
  - 颜色规格图: 共 4 张。完成格式转换。

--------------------------------------------------
SPU 序号: 002
主要商品名: 便携榨汁机
转换状态: 部分补全后转换成功
SKU 数量: 2
物料缺失与补全说明:
  - 原始数据中缺失【供货价】，用户交互确认为【80.00】，已设置。
  - 原始图片中缺失【商品主图】，用户交互后授权调用 AI 生图工具生成了 1 张白底主图。
数据修改: 所有文本属性已翻译为英文
图片处理:
  - 主图: 1 张。调用 generate_ecommerce_images_direct (white_bg) 生成。
  - 详情页图: 4 张。完成格式转换。
  - 颜色规格图: 2 张。完成格式转换。

==================================================
任务总结:
共处理 2 个 SPU，成功 2 个。
共调用 AI 生图接口 4 次，生成图片 4 张。
所有物料已成功输出至 D:/MyData/拼多多商品转换202606200830/。
```