@miravia_test/miravia-publish-skill 0.1.5 → 0.1.7

package/dist/SKILL.md

@@ -25,7 +25,7 @@ description: Miravia 商品发布 AI Skill。仅负责商品创建（手动一
 | 文件 | 职责 |
 |------|------|
 | `scripts/publish_module.py` | 发布流程主控（类目/品牌/属性/图片/SKU/合规/确认/创建） |
-| `scripts/extraction_engine.py` | 从源文本抽取 `MiraviaListingSchema` |
+| `scripts/extraction_engine.py` | 从源文本抽取 `MiraviaListingSchema`；Excel/CSV 按表头规则抽取（无需 LLM key） |
 | `scripts/file_reader.py` | 读取本地文件、文件夹或网页 URL |
 | `scripts/field_definitions.py` | 商品字段定义与术语说明，供 LLM 抽取与提示使用 |
 | `scripts/product_client.py` | Miravia 商品/图片/类目/品牌/合规 API 封装 |
@@ -71,11 +71,16 @@ description: Miravia 商品发布 AI Skill。仅负责商品创建（手动一
 
 ### 4.2 AI 抽取模式
 
+> **⚠️ Agent 行为准则（必须遵守，禁止绕过）**
+> 1. 卖家上传文件/文件夹/URL 后，Agent **必须**带 `--source` 调用本 Skill 完成读取与抽取，**禁止**自己读取/解析文件内容后改走手动模式（手动模式仅用于卖家直接以 CLI 参数逐项提供的场景）。
+> 2. **Excel/CSV 源按表头规则抽取，完全不需要 LLM key**；只有 PDF/Word/图片/URL 等非表格源才需要 LLM。Agent **不得**以「未配置 LLM key、正则抽取靠不住」为由绕过 Skill——该前提对 Excel/CSV 不成立。
+> 3. 上传文件后的**第一步固定为 CTB 确认**：先向卖家展示抽取到的**标题、品牌、类目预测**并等待确认（`need_ctb_confirm` / 必要时 `need_category` / `need_brand`）。**在 CTB 确认通过之前，禁止进入后续字段抽取与缺字段（EAN / GPSR / 合规等）校验提示**。CTB 确认之后才依次做关键字段与字段摘要检查。
+
 0. **Stage 0 - 授权确认**：
    - 首次操作时，Skill 返回 `status: need_authorization`，列出三项授权请求（读取卖家资料、访问商品数据、更新商品数据）。
    - 卖家确认后，加 `--authorized` 重新运行命令，进入后续流程。
 1. 读取 `--source` 指定的文件/文件夹/URL。
-2. 使用 LLM 抽取 `MiraviaListingSchema`；可通过 `--output-schema` 仅查看抽取结果。
+2. 抽取 `MiraviaListingSchema`；可通过 `--output-schema` 仅查看抽取结果。**Excel/CSV 源按表头规则直接抽取，无需 LLM key**；PDF/Word/图片/URL 源使用 LLM 抽取（需配置 OPENAI_API_KEY 或 DASHSCOPE_API_KEY）。
 3. **Stage 1 - 类目/标题/品牌确认（CTB）**：
    - 解析 category / brand，返回候选供确认。
    - 生成 `ctb_confirm_token`，返回 `status: need_ctb_confirm`。
@@ -84,7 +89,8 @@ description: Miravia 商品发布 AI Skill。仅负责商品创建（手动一
    - `/seller/shipping_permission/get` 决定默认物流方式（DBS/DBM）。
    - `/manufacturer/get`、`/eu/responsible/person/get` 匹配制造商/EU 负责人。
 5. **Stage 3 - 关键字段检查**：
-   - 缺少图片、价格、重量、长宽高时直接阻断（`status: need_mandatory_fields`）。
+   - **主图/SKU 图全空 → 硬阻断且不可转 Draft**（`status: need_mandatory_fields`，`draft_mode_available: false`）：Miravia `/product/create` 要求至少一张图片，缺失会以 `4224 MAIN_IMAGE_OR_SKU_IMAGE_EMPTY` 被平台硬拒，草稿也绕不过。
+   - 缺价格/重量/长宽高等（接口判定必填时）→ 阻断，但允许 `--draft` 降级发布。
 6. **Stage 4 - 字段摘要/草稿确认**：
    - 汇总已抽取字段与缺失字段。
    - 关键字段缺失时询问是否以 `--draft` 模式发布为 `inactive`。
@@ -103,8 +109,8 @@ description: Miravia 商品发布 AI Skill。仅负责商品创建（手动一
 | `need_category` | 类目未找到、类目 ID 无效、推荐多候选或预测失败 | 让用户提供正确的类目 ID（`--category-id`）或从候选中选择一个（`--confirmed-category-id`），**禁止重复搜索同一关键词**；所有 ID 均校验类目树；关键词搜索失败后调 `/product/category/recommend/get` 推荐，Top1 自动选中，TopN 展示候选，空结果展示全量类目树 |
 | `need_brand` | 品牌未找到或存在多个候选 | 让用户提供正确的品牌名（`--brand-name`）或从候选中选择一个（`--confirmed-brand-id`），**禁止重复搜索同一关键词** |
 | `need_ctb_confirm` | 需要确认类目/标题/品牌 | 回传 `ctb_confirm_token` |
-| `need_brand_create` | 品牌未找到，需去 Seller Center 创建 | 创建后重新运行命令 |
-| `need_mandatory_fields` | 缺少必填字段（图片/价格/重量/尺寸） | 补充字段后重跑 |
+| `need_brand_create` | 品牌未找到，需去 Seller Center 处理 | 先引导查看已有品牌及审核状态（https://sellercenter.miravia.es/apps/setting/seller/brandlist，可能已在审核中），确无再创建（https://sellercenter.miravia.es/apps/product/publish/brand）；创建后重新运行命令 |
+| `need_mandatory_fields` | 缺少必填字段；**图片缺失为硬阻断（不可 Draft）**，价格/重量/尺寸缺失可 `--draft` | 补充字段后重跑 |
 | `need_category_attributes` | 类目必填属性缺失（AI抽取模式） | 通过 `--attribute-data` 补充或使用 `--draft` |
 | `need_field_summary` | 需要确认字段摘要或选择草稿模式 | 回传 `field_summary_token`，可加 `--draft` |
 | `need_compliance` | 制造商/EU 负责人匹配失败 | 按返回候选选择或补充信息后重跑 |
@@ -119,12 +125,14 @@ description: Miravia 商品发布 AI Skill。仅负责商品创建（手动一
 | `need_images` | 部分图片迁移失败 | 替换图片后重跑 |
 | `unsupported_format` | 上传了不支持的文件格式（zip/txt/psd 等） | 提示仅支持 PDF/Word/Excel/Image/URL，允许重新上传 |
 | `file_empty_or_corrupted` | 文件内容为空或损坏（0KB PDF / 乱码 Word） | 提示文件内容为空或损坏，允许重新上传 |
-| `llm_not_configured` | 未配置 LLM API key（OPENAI_API_KEY / DASHSCOPE_API_KEY），AI 抽取不可用 | 提示配置 key 后带 --source 重跑；不要绕过确认流程改走手动模式 |
+| `llm_not_configured` | 非表格源（PDF/Word/图片/URL）走 LLM 抽取时未配置 LLM API key（OPENAI_API_KEY / DASHSCOPE_API_KEY）；Excel/CSV 源不会触发此状态 | 提示配置 key 后带 --source 重跑，或改用 Excel/CSV 上传；不要绕过确认流程改走手动模式 |
 | `invalid_url` | 输入的 URL 无法抓取 | 提示检查 URL 后重试 |
 | `title_invalid` | 商品标题不符合规范（过短/过长/词数不足） | 提示具体错误 + 标题格式建议（Brand+Category+Model+Features+Scenario），阻断后续流程，禁止转 Draft |
 | `need_category_permission` | 卖家无该类目发布权限 | 询问是否以 Draft 模式发布（待审批通过后自动激活），提供类目权限申请链接 https://sellercenter.miravia.es/apps/setting/category；或更换类目后重跑 |
 | `preview` | 最终发布预览 | 回传 `publish_preview_token` |
-| `success` | 创建成功 | 返回 `item_id`、`pdp_url`、审核提示 |
+| `success` | 创建成功（必须返回 `item_id`，无 `item_id` 一律视为失败） | 返回 `item_id`、`pdp_url`、审核提示 |
+| `draft_created_with_issues` | 草稿创建成功（接口返回了 `item_id`）但必填字段/权限待补全 | 在 Seller Center 草稿中补全字段后激活，禁止当作完全成功 |
+| `create_failed` | `/product/create` 失败或未返回 `item_id`（含 4234 无 `item_id` 的场景，草稿并未创建） | 展示错误码/message/trace_id 定位根因，修复后重跑；重跑前先在 Seller Center 确认是否已有重复草稿 |
 | `brand_permission_failed` | 品牌权限不足/待审批 (BRAND_PENDING / BRAND_PERMISSION_DENIED) | 加 `--draft` 发布为草稿，或在 Seller Center 申请品牌权限后重跑 |
 
 ---
@@ -134,11 +142,11 @@ description: Miravia 商品发布 AI Skill。仅负责商品创建（手动一
 | ID | 规则 | 说明 |
 |----|------|------|
 | P1 | **sellerId 自动注入** | 从开放平台鉴权上下文读取，禁止用户传入。 |
-| P2 | **类目决定属性** | 创建前必须先确定叶子类目，再调 `/category/attributes/get`。 |
+| P2 | **必填判定统一入口** | 所有必填/条件必填检查都走同一规则（`_field_is_required`）：**我们的规则优先命中→否则以 `/category/attributes/get` 的 `is_mandatory` 为准**；接口未返回该属性等同选填。创建前必须先确定叶子类目并拉取类目属性。 |
 | P3 | **图片先迁移** | 外部图片 URL 必须经 `/image/migrate` 迁移到 Miravia CDN。 |
 | P4 | **三阶段确认** | CTB 确认 → 字段摘要确认 → 最终发布预览确认。 |
 | P5 | **pre-check 集中** | 品牌/类目权限等校验统一在 `/product/batchValidate` 提交前完成。 |
-| P6 | **必填项阻断** | 图片、常规价格、重量、长/宽/高缺失时不能直接发布。 |
+| P6 | **必填项阻断** | 仅结构核心字段（图片、常规价格、库存、标题、类目、品牌、物流）恒定阻断；重量/长宽高为 SKU 级类目属性，仅当接口标 `is_mandatory=1` 时阻断；Seller SKU 非必填（空时接口自动生成）。batchValidate 为最终权威兜底。 |
 | P7 | **草稿模式** | 关键字段缺失时，商家可选择 `--draft` 发布为 `inactive`。 |
 | P8 | **品牌创建后重跑** | 品牌未找到时不自动轮询，给出 Seller Center 创建链接，创建完成后商家重跑命令。 |
 | P9 | **默认物流** | 通过 `/seller/shipping_permission/get` 的 `DBS_permission` 决定默认 `DBS` 或 `DBM`。 |
@@ -146,6 +154,7 @@ description: Miravia 商品发布 AI Skill。仅负责商品创建（手动一
 | P11 | **API 重试** | 每个 API 调用最多重试 3 次。 |
 | P12 | **埋点与审计** | 记录 Skill 调用与商品操作审计日志。 |
 | P13 | **创建前必须确认** | AI Agent **禁止**在收集完信息后直接调用 `/product/create`。必须先向卖家展示完整字段摘要（标题、类目、品牌、价格、SKU、包装、图片、GPSR、Safety warning 等所有已填字段），明确标注缺失字段，等卖家回复「确认」后才能执行创建。无论手动模式还是 AI 抽取模式均适用。 |
+| P14 | **文件上传必走 Skill + CTB 优先** | 卖家上传文件/URL 后，Agent 必须带 `--source` 调用 Skill，禁止自己读文件转手动模式；Excel/CSV 无需 LLM key。抽取后第一步固定为 CTB（标题/品牌/类目）确认，CTB 确认前不得提示 EAN/GPSR 等缺字段。 |
 
 ---
 

package/dist/VERSION

@@ -1 +1 @@
-0.1.5
+0.1.7

package/dist/scripts/extraction_engine.py

@@ -87,6 +87,12 @@ class MiraviaListingSchema:
 
     raw_skus: List[Dict[str, Any]] = field(default_factory=list)
 
+    # Excel/CSV columns whose header did not match any known field in
+    # _TABLE_FIELD_SYNONYMS. Kept verbatim (header -> value) so the publish
+    # flow can bind them against the category attribute definitions returned
+    # by /category/attributes/get instead of silently dropping them.
+    unmatched_columns: Dict[str, str] = field(default_factory=dict)
+
     def to_dict(self) -> Dict[str, Any]:
         return asdict(self)
 
@@ -336,3 +342,280 @@ def validate_title(title: Optional[str]) -> Optional[str]:
     if len(title.split()) < 5:
         return "Title should contain at least 5 words"
     return None
+
+
+# ---------------------------------------------------------------------------
+# Rule-based table extraction (Excel/CSV) — no LLM key required
+# ---------------------------------------------------------------------------
+
+
+# Header synonym map: schema field -> candidate header spellings (zh/en/es).
+# Headers are normalized (lowercase, spaces/punctuation stripped) before
+# matching; each field may bind to multiple columns (e.g. several image
+# columns all feed product_images).
+_TABLE_FIELD_SYNONYMS: Dict[str, tuple] = {
+    # Keep more specific fields BEFORE generic ones (matching runs
+    # exact -> prefix -> substring, but dict order breaks exact ties).
+    "discounted_price": ("折扣价", "活动价", "促销价", "折后价", "specialprice", "discountprice", "saleprice", "preciodescuento", "preciorebajado"),
+    "general_price": ("价格", "售价", "原价", "价格€", "price", "generalprice", "precio"),
+    "product_title": ("标题", "商品标题", "产品名称", "品名", "title", "producttitle", "productname", "titulo", "nombre"),
+    "brand_name": ("品牌", "brand", "brandname", "marca"),
+    "category_name": ("类目", "类目名", "叶子类目", "category", "categoryname", "categoria"),
+    "category_id": ("类目id", "类目id", "categoryid", "categoryid"),
+    "product_long_description": ("描述", "详情", "商品描述", "description", "descripcion"),
+    "product_images": ("图片", "主图", "细节图", "image", "images", "imageurl", "picture", "photo", "imagen", "imagenes", "foto"),
+    "seller_sku": ("sellersku", "sku", "商家编码", "商品编码", "skucode", "reference", "referencia"),
+    "ean_code": ("ean", "eancode", "条码", "条形码", "barcode", "codigodebarras"),
+    "stock": ("库存", "数量", "stock", "quantity", "qty", "inventario", "cantidad"),
+    "weight_kg": ("重量", "包裹重量", "weight", "peso"),
+    "length_cm": ("长度", "长cm", "长", "length", "largura"),
+    "width_cm": ("宽度", "宽cm", "宽", "width", "ancho"),
+    "height_cm": ("高度", "高cm", "高", "height", "altura"),
+    "manufacturer_name": ("制造商", "厂家", "manufacturer", "fabricante"),
+    "eu_responsible_person_name": ("欧盟负责人", "欧代", "euresponsibleperson", "eurp"),
+    "variation_1": ("颜色", "color", "colour", "variation1", "variation", "款式"),
+    "variation_2": ("尺寸", "尺码", "size", "talla", "variation2"),
+}
+
+# Fields that describe the product as a whole (first non-empty row wins);
+# everything else is SKU-level and collected per row into raw_skus.
+_PRODUCT_LEVEL_FIELDS = {
+    "product_title",
+    "brand_name",
+    "category_name",
+    "category_id",
+    "product_long_description",
+    "weight_kg",
+    "length_cm",
+    "width_cm",
+    "height_cm",
+    "manufacturer_name",
+    "eu_responsible_person_name",
+}
+# Row-level columns whose header name doubles as the variation dimension name.
+_VARIATION_SOURCE_FIELDS = {"variation_1": "variation_name_1", "variation_2": "variation_name_2"}
+
+
+def _norm_header(header: Any) -> str:
+    """Normalize a table header for synonym matching."""
+    return re.sub(r"[\s_\-—·（）()【】\[\].,，、:：]+", "", str(header)).lower()
+
+
+# Overly generic single-word synonyms. These are allowed to match a header by
+# equality or as a prefix (e.g. "Image", "Product name") but must NOT match by
+# substring, otherwise a compound header such as "Package/Label Photo(EU)"
+# (normalized "packagelabelphotoeu") is greedily absorbed by "photo" and
+# reported as a main product image instead of binding to its real category
+# attribute Package_Label_Photo_EU.
+_GENERIC_SUBSTRING_SYNONYMS = frozenset({
+    "image", "images", "photo", "photos", "picture", "pictures",
+    "name", "names", "size", "color", "colour", "talla", "nombre",
+})
+
+
+def _match_table_field(header_norm: str) -> Optional[str]:
+    """Resolve a normalized header to a schema field via 3-pass matching
+    (exact -> prefix -> substring) to keep specific fields from being
+    shadowed by generic synonyms (e.g. "special price" vs "price")."""
+    for pass_kind in ("exact", "prefix", "contains"):
+        for field_name, synonyms in _TABLE_FIELD_SYNONYMS.items():
+            for syn in synonyms:
+                if pass_kind == "exact" and header_norm == syn:
+                    return field_name
+                if pass_kind == "prefix" and header_norm.startswith(syn):
+                    return field_name
+                if (
+                    pass_kind == "contains"
+                    and syn not in _GENERIC_SUBSTRING_SYNONYMS
+                    and syn in header_norm
+                ):
+                    return field_name
+    return None
+
+
+def _clean_numeric(value: Any) -> Optional[str]:
+    """Extract a plain number string from a cell (handles €10,99 / 10.99 / 10)."""
+    if value is None:
+        return None
+    s = str(value).strip()
+    if not s:
+        return None
+    m = re.search(r"(\d+(?:[.,]\d+)?)", s)
+    if not m:
+        return None
+    return m.group(1).replace(",", ".")
+
+
+def _clean_cell(value: Any) -> Optional[str]:
+    """Non-empty string view of a cell."""
+    if value is None:
+        return None
+    s = str(value).strip()
+    return s or None
+
+
+def _extract_image_urls(value: Any) -> List[str]:
+    """Collect http(s) image URLs from a cell (may hold several)."""
+    if value is None:
+        return []
+    return re.findall(r"https?://[^\s,;]+", str(value), re.IGNORECASE)
+
+
+def extract_schema_from_tables(content_items: List[Dict[str, Any]]) -> Optional[MiraviaListingSchema]:
+    """Extract a listing schema from structured Excel/CSV tables by rule.
+
+    Uses header synonyms instead of an LLM, so sellers never need an LLM
+    API key for the mainstream Excel/CSV flow. Returns None when no table
+    data is present or nothing useful was matched, letting the caller fall
+    back to LLM extraction for non-structured sources.
+    """
+    tables: List[Dict[str, Any]] = []
+    for item in content_items or []:
+        if item.get("type") != "table":
+            continue
+        content = item.get("content")
+        if not content:
+            continue
+        for table in (content if isinstance(content, list) else [content]):
+            if isinstance(table, dict) and table.get("rows"):
+                tables.append(table)
+
+    if not tables:
+        return None
+
+    schema = MiraviaListingSchema()
+    # column plans: field -> (table_index, header) pairs, preserving order
+    column_plan: Dict[str, List[tuple]] = {}
+    # Headers that matched no known field, kept in order for later binding.
+    unmatched_headers: List[str] = []
+    seen_unmatched: set = set()
+
+    for t_idx, table in enumerate(tables):
+        for header in table.get("headers", []):
+            field_name = _match_table_field(_norm_header(header))
+            if field_name:
+                column_plan.setdefault(field_name, []).append((t_idx, header))
+            else:
+                hkey = _clean_cell(header)
+                if hkey and hkey not in seen_unmatched:
+                    seen_unmatched.add(hkey)
+                    unmatched_headers.append(hkey)
+
+    if not column_plan:
+        return None
+
+    all_rows: List[tuple] = []  # (t_idx, row_dict)
+    for t_idx, table in enumerate(tables):
+        for row in table.get("rows", []):
+            if isinstance(row, dict):
+                all_rows.append((t_idx, row))
+    if not all_rows:
+        return None
+
+    def first_non_empty(field_name: str) -> Optional[str]:
+        for t_idx, header in column_plan.get(field_name, []):
+            for r_idx, row in all_rows:
+                if r_idx == t_idx:
+                    value = _clean_cell(row.get(header))
+                    if value:
+                        return value
+        return None
+
+    # Product-level fields: first non-empty cell wins.
+    for field_name in _PRODUCT_LEVEL_FIELDS:
+        value = first_non_empty(field_name)
+        if value:
+            setattr(schema, field_name, value)
+
+    # Price/stock need plain numbers. Weight/dimensions keep their original
+    # string (e.g. "250g", "15cm"): the caller's _convert_weight/_convert_length
+    # normalize units, and stripping the unit here would misread grams as kg.
+    for field_name in ("general_price", "discounted_price", "stock"):
+        value = _clean_numeric(first_non_empty(field_name))
+        if value:
+            setattr(schema, field_name, value)
+
+    # Category/brand IDs keep raw values when present.
+    cat_id = _clean_cell(first_non_empty("category_id"))
+    if cat_id and str(cat_id).isdigit():
+        schema.category_id = str(cat_id)
+
+    # Images: product-level union of all image columns across rows.
+    seen_urls: set = set()
+    for t_idx, header in column_plan.get("product_images", []):
+        for r_idx, row in all_rows:
+            if r_idx == t_idx:
+                for url in _extract_image_urls(row.get(header)):
+                    if url not in seen_urls:
+                        seen_urls.add(url)
+                        schema.product_images.append(url)
+
+    # Variations: dimension name from header, options from distinct row values.
+    for src_field, name_field in _VARIATION_SOURCE_FIELDS.items():
+        if src_field not in column_plan:
+            continue
+        first_t_idx, first_header = column_plan[src_field][0]
+        dim_name = _clean_cell(first_header)
+        options: List[str] = []
+        for t_idx, header in column_plan[src_field]:
+            for r_idx, row in all_rows:
+                if r_idx == t_idx:
+                    value = _clean_cell(row.get(header))
+                    if value and value not in options:
+                        options.append(value)
+        if options:
+            setattr(schema, name_field, dim_name)
+            if name_field == "variation_name_1":
+                schema.variation_options_1 = options
+            else:
+                schema.variation_options_2 = options
+
+    # SKU rows: one raw_skus entry per data row.
+    for t_idx, row in all_rows:
+        sku: Dict[str, Any] = {}
+        for field_name, sku_key in (
+            ("seller_sku", "seller_sku"),
+            ("ean_code", "ean_code"),
+            ("variation_1", "variation_1"),
+            ("variation_2", "variation_2"),
+        ):
+            for c_t_idx, header in column_plan.get(field_name, []):
+                if c_t_idx == t_idx:
+                    value = _clean_cell(row.get(header))
+                    if value:
+                        sku[sku_key] = value
+                        break
+        for field_name, sku_key in (("general_price", "price"), ("discounted_price", "special_price"), ("stock", "quantity")):
+            for c_t_idx, header in column_plan.get(field_name, []):
+                if c_t_idx == t_idx:
+                    value = _clean_numeric(row.get(header))
+                    if value:
+                        sku[sku_key] = value
+                        break
+        sku_images: List[str] = []
+        for c_t_idx, header in column_plan.get("product_images", []):
+            if c_t_idx == t_idx:
+                sku_images.extend(_extract_image_urls(row.get(header)))
+        if sku_images:
+            sku["sku_images"] = sku_images
+        if sku:
+            schema.raw_skus.append(sku)
+
+    # Keep every non-whitelisted column (first non-empty value) so the publish
+    # flow can bind it against the category attribute definitions instead of
+    # dropping it. Keyed by the original header text.
+    for header in unmatched_headers:
+        for t_idx, row in all_rows:
+            value = _clean_cell(row.get(header))
+            if value:
+                schema.unmatched_columns[header] = value
+                break
+
+    # Only claim success when something meaningful was extracted; otherwise
+    # the caller falls back to LLM extraction.
+    if schema.product_title or schema.general_price or schema.raw_skus:
+        # Mirror single-SKU price/stock to top-level convenience fields.
+        if not schema.general_price and schema.raw_skus:
+            schema.general_price = schema.raw_skus[0].get("price")
+        return schema
+    return None

package/dist/scripts/i18n.py

@@ -172,14 +172,21 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_unsupported_format": "Unsupported file format: {source}. Only PDF, Word, Excel, Image, and URL are supported.",
         "pub_invalid_url": "Failed to fetch URL: {source}. Please check the URL and try again.",
         "pub_url_fetch_failed": "Failed to fetch content from {source}: {error}. Please check the URL and try again.",
-        "pub_llm_not_configured": "AI extraction is unavailable: no LLM API key is configured (OPENAI_API_KEY or DASHSCOPE_API_KEY).",
-        "pub_llm_not_configured_next": "Configure the LLM API key in the environment, then rerun with --source. Do not bypass the confirm-first flow with manual mode.",
+        "pub_llm_not_configured": "LLM extraction is unavailable: no LLM API key is configured (OPENAI_API_KEY or DASHSCOPE_API_KEY). This only applies to non-table sources (PDF/Word/image/URL); Excel/CSV sources are extracted by header rules and need no LLM key.",
+        "pub_llm_not_configured_next": "If the source is Excel/CSV, just rerun with --source (no key needed). For PDF/Word/image/URL, configure the LLM API key and rerun with --source. Do NOT read the file yourself or switch to manual mode; the first step must be CTB (title/brand/category) confirmation.",
         "pub_create_requires_category": "create_product requires --category-id (leaf category)",
         "pub_create_requires_name": "create_product requires --product-name",
         "pub_create_preview_message": "Please review the product creation details below and confirm before I create the product.",
         "pub_create_preview_next": "If the details are correct, rerun with --publish-preview-token {token} to execute.",
         "pub_create_success": "Product created successfully.",
         "pub_create_success_next": "Ask the seller if they need to view the created product or make further edits.",
+        "pub_draft_created_with_issues": "Draft created, but some required fields or authorizations are missing. Complete them in Seller Center to activate the product.",
+        "pub_draft_update_hint": "Fill in the missing fields in Seller Center draft list, then activate the product.",
+        "pub_create_failed_title": "Product creation failed",
+        "pub_create_failed_message": "Product was NOT created (including as draft): error code {code}, reason: {reason}.",
+        "pub_create_failed_no_item_id": "The create API returned success but no item_id, so the product was not actually created.",
+        "pub_create_failed_check_and_rerun": "Check whether a duplicate draft already exists in Seller Center, fix the reported issue, then rerun.",
+        "pub_create_failed_trace_hint": "When contacting platform support, provide trace_id {trace_id} / request_id {request_id} to locate the root cause.",
         "pub_title_too_short": "Product title is too short (minimum {min} characters, got {actual}).",
         "pub_title_too_long": "Product title is too long (maximum {max} characters, got {actual}).",
         "pub_title_too_few_words": "Product title must have at least {min} words (got {actual}).",
@@ -234,6 +241,7 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_summary_conditional_section": "[Conditional Fields]",
         "pub_field_status_filled": "Filled",
         "pub_field_status_missing": "MISSING",
+        "pub_field_status_optional": "Optional",
         "pub_mandatory_missing_block": "Cannot publish: missing mandatory fields [{fields}]. Please fill them and rerun.",
         "pub_conditional_missing_draft": "Missing conditional fields [{fields}]. The product will be saved as Inactive (Draft) and auto-activated once completed. Confirm to proceed?",
         # DBM/DBS auto-switch
@@ -302,6 +310,7 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_ctb_confirm_next": "If correct, rerun with --ctb-confirm-token {token} to continue.",
         "pub_brand_not_found_title": "Brand not found",
         "pub_brand_not_found_message": "No brand matching \"{brand_name}\" was found in Miravia. Would you like to create a new brand?",
+        "pub_brand_list_link": "Check your existing brands and their approval status here: https://sellercenter.miravia.es/apps/setting/seller/brandlist",
         "pub_brand_create_link": "Create a new brand here: https://sellercenter.miravia.es/apps/product/publish/brand",
         "pub_brand_create_next": "After creating the brand in Seller Center, rerun this command with --brand-name <brand_name> or --confirmed-brand-id <brand_id>.",
         "pub_brand_reconfirm_or_choose": "If you do not want to create a brand, please re-enter the brand name or choose one from the matched list below.",
@@ -310,7 +319,10 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_field_summary_description": "Review which fields have been filled and which are still missing.",
         "pub_field_status_filled": "filled",
         "pub_field_status_missing": "missing",
+        "pub_field_status_optional": "optional",
         "pub_mandatory_fields_missing": "The following required fields are missing and must be provided before continuing: {fields}",
+        "pub_image_required_no_draft": "At least one image (main image or a SKU image) is required. This is a Miravia platform requirement that cannot be bypassed even by publishing as Draft; missing: {fields}.",
+        "pub_add_images_and_rerun": "Add at least one product image (URL or local file) and rerun the command.",
         "pub_key_fields_missing_draft_question": "Some key fields are missing. You can publish as a draft and complete them later. To publish as draft, rerun with --draft.",
         "pub_manufacturer_eurp_mismatch": "The manufacturer / EU responsible person does not match an approved record. Please choose a valid one or publish as draft.",
         "pub_seller_sku_recommended": "Seller SKU is strongly recommended as the internal identifier for this SKU. Please provide one if available.",
@@ -473,6 +485,13 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_create_preview_next": "Si los detalles son correctos, vuelve a ejecutar con --publish-preview-token {token}.",
         "pub_create_success": "Producto creado correctamente.",
         "pub_create_success_next": "Pregunta al vendedor si necesita ver el producto creado o hacer más ediciones.",
+        "pub_draft_created_with_issues": "Borrador creado, pero faltan campos obligatorios o autorizaciones. Complételos en Seller Center para activar el producto.",
+        "pub_draft_update_hint": "Complete los campos faltantes en la lista de borradores de Seller Center y active el producto.",
+        "pub_create_failed_title": "Error al crear el producto",
+        "pub_create_failed_message": "El producto NO se creó (tampoco como borrador): código {code}, motivo: {reason}.",
+        "pub_create_failed_no_item_id": "La API de creación devolvió éxito pero no incluyó item_id, por lo que el producto no se creó.",
+        "pub_create_failed_check_and_rerun": "Compruebe en Seller Center si ya existe un borrador duplicado, corrija el problema y vuelva a ejecutar.",
+        "pub_create_failed_trace_hint": "Al contactar con el soporte, indique trace_id {trace_id} / request_id {request_id}.",
         "pub_title_too_short": "El título del producto es demasiado corto (mínimo {min} caracteres, tiene {actual}).",
         "pub_title_too_long": "El título del producto es demasiado largo (máximo {max} caracteres, tiene {actual}).",
         "pub_title_too_few_words": "El título del producto debe tener al menos {min} palabras (tiene {actual}).",
@@ -496,6 +515,7 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_need_attributes_field_item": "{idx}. {label} ({en_name}) - {input_type}, {mandatory}",
         "pub_attribute_data_next": "Vuelve a ejecutar con --attribute-data '<json>' para proporcionar los valores de atributos.",
         "pub_image_migration_partial": "Algunas imágenes no se migraron: {failed}. Reemplázalas o vuelve a ejecutar sin esas URLs.",
+        "pub_field_status_optional": "Opcional",
     },
     "it": {
         "greeting": "Cosa vorresti fare con la skill di inventario? Rispondi con la lettera dell'opzione o descrivi la tua richiesta:",
@@ -640,6 +660,13 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_create_preview_next": "Se i dettagli sono corretti, riesegui con --publish-preview-token {token}.",
         "pub_create_success": "Prodotto creato con successo.",
         "pub_create_success_next": "Chiedi al venditore se ha bisogno di visualizzare il prodotto creato o apportare modifiche.",
+        "pub_draft_created_with_issues": "Bozza creata, ma mancano campi obbligatori o autorizzazioni. Completali in Seller Center per attivare il prodotto.",
+        "pub_draft_update_hint": "Compila i campi mancanti nell'elenco bozze di Seller Center e attiva il prodotto.",
+        "pub_create_failed_title": "Creazione del prodotto non riuscita",
+        "pub_create_failed_message": "Il prodotto NON è stato creato (nemmeno come bozza): codice {code}, motivo: {reason}.",
+        "pub_create_failed_no_item_id": "L'API di creazione ha restituito successo ma senza item_id; il prodotto non è stato creato.",
+        "pub_create_failed_check_and_rerun": "Verifica in Seller Center se esiste già una bozza duplicata, correggi il problema e riesegui.",
+        "pub_create_failed_trace_hint": "Contattando il supporto, indica trace_id {trace_id} / request_id {request_id}.",
         "pub_title_too_short": "Il titolo del prodotto è troppo corto (minimo {min} caratteri, ha {actual}).",
         "pub_title_too_long": "Il titolo del prodotto è troppo lungo (massimo {max} caratteri, ha {actual}).",
         "pub_title_too_few_words": "Il titolo del prodotto deve avere almeno {min} parole (ha {actual}).",
@@ -663,6 +690,7 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_need_attributes_field_item": "{idx}. {label} ({en_name}) - {input_type}, {mandatory}",
         "pub_attribute_data_next": "Riesegui con --attribute-data '<json>' per fornire i valori degli attributi.",
         "pub_image_migration_partial": "Alcune immagini non sono state migrate: {failed}. Sostituiscile o riesegui senza quegli URL.",
+        "pub_field_status_optional": "Opzionale",
     },
     "zh": {
         "greeting": "您想使用库存分析 Skill 做什么？请直接回复选项字母，或输入你的需求：",
@@ -809,14 +837,21 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_unsupported_format": "不支持的文件格式：{source}。仅支持 PDF、Word、Excel、图片和 URL。",
         "pub_invalid_url": "无法获取 URL：{source}。请检查 URL 后重试。",
         "pub_url_fetch_failed": "无法从 {source} 获取内容：{error}。请检查 URL 后重试。",
-        "pub_llm_not_configured": "AI 抽取不可用：未配置 LLM API key（OPENAI_API_KEY 或 DASHSCOPE_API_KEY）。",
-        "pub_llm_not_configured_next": "请在环境中配置 LLM API key 后，带 --source 重新运行；不要绕过确认流程改走手动模式。",
+        "pub_llm_not_configured": "LLM 抽取不可用：未配置 LLM API key（OPENAI_API_KEY 或 DASHSCOPE_API_KEY）。此状态仅针对非表格源（PDF/Word/图片/URL）；Excel/CSV 源按表头规则抽取，无需 LLM key。",
+        "pub_llm_not_configured_next": "若源为 Excel/CSV，直接带 --source 重跑即可（无需 key）；若为 PDF/Word/图片/URL，请配置 LLM API key 后带 --source 重跑。不要自己读文件改走手动模式；第一步必须是 CTB（标题/品牌/类目）确认。",
         "pub_create_requires_category": "创建商品必须提供 --category-id（叶子类目 ID）",
         "pub_create_requires_name": "创建商品必须提供 --product-name（商品标题）",
         "pub_create_preview_message": "请检查以下商品信息，确认无误后我将创建商品。",
         "pub_create_preview_next": "如果信息正确，请加上 --publish-preview-token {token} 重新执行。",
         "pub_create_success": "商品创建成功。",
         "pub_create_success_next": "询问商家是否需要查看已创建的商品或进一步编辑。",
+        "pub_draft_created_with_issues": "草稿已创建，但部分必填字段或权限缺失。请在 Seller Center 补全后激活商品。",
+        "pub_draft_update_hint": "在 Seller Center 草稿列表中补全缺失字段后激活商品。",
+        "pub_create_failed_title": "商品创建失败",
+        "pub_create_failed_message": "商品未创建成功（含草稿）：错误码 {code}，原因：{reason}。",
+        "pub_create_failed_no_item_id": "创建接口返回成功但未返回 item_id，商品实际未创建。",
+        "pub_create_failed_check_and_rerun": "请先在 Seller Center 确认是否已存在重复草稿，修复报错问题后重新运行。",
+        "pub_create_failed_trace_hint": "如需平台排查，请提供 trace_id {trace_id} / request_id {request_id} 定位根因。",
         "pub_title_too_short": "商品标题过短（最少 {min} 个字符，当前 {actual} 个）。",
         "pub_title_too_long": "商品标题过长（最多 {max} 个字符，当前 {actual} 个）。",
         "pub_title_too_few_words": "商品标题至少需要 {min} 个单词（当前 {actual} 个）。",
@@ -871,6 +906,7 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_summary_conditional_section": "【条件必填字段】",
         "pub_field_status_filled": "已填写",
         "pub_field_status_missing": "缺失",
+        "pub_field_status_optional": "选填",
         "pub_mandatory_missing_block": "无法发布：缺少必填字段 [{fields}]。请补充后重新运行。",
         "pub_conditional_missing_draft": "缺少条件必填字段 [{fields}]。商品将以未激活（Draft）状态保存，待补全后自动激活。是否确认？",
         # DBM/DBS auto-switch
@@ -904,6 +940,7 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_ctb_confirm_next": "如果无误，请使用 --ctb-confirm-token {token} 继续。",
         "pub_brand_not_found_title": "未找到品牌",
         "pub_brand_not_found_message": "在 Miravia 中未找到与 \"{brand_name}\" 匹配的品牌。您是否想创建新品牌？",
+        "pub_brand_list_link": "点此查看已有品牌及审核状态：https://sellercenter.miravia.es/apps/setting/seller/brandlist",
         "pub_brand_create_link": "点此创建新品牌：https://sellercenter.miravia.es/apps/product/publish/brand",
         "pub_brand_create_next": "在 Seller Center 创建品牌后，请使用 --brand-name <brand_name> 或 --confirmed-brand-id <brand_id> 重新运行命令。",
         "pub_brand_reconfirm_or_choose": "如果您不想创建品牌，请重新输入品牌名称，或从下方匹配列表中选择一个。",
@@ -912,7 +949,10 @@ TRANSLATIONS: Dict[str, Dict[str, str]] = {
         "pub_field_summary_description": "查看哪些字段已填写，哪些字段仍缺失。",
         "pub_field_status_filled": "已填写",
         "pub_field_status_missing": "未填写",
+        "pub_field_status_optional": "选填",
         "pub_mandatory_fields_missing": "以下必填字段缺失，必须补充后才能继续：{fields}",
+        "pub_image_required_no_draft": "至少需要一张图片（主图或 SKU 图）。这是 Miravia 平台硬性要求，即使发草稿也无法绕过；缺失：{fields}。",
+        "pub_add_images_and_rerun": "请至少补充一张商品图片（URL 或本地文件）后重新运行命令。",
         "pub_key_fields_missing_draft_question": "部分关键字段缺失。您可以选择以草稿模式发布，稍后再补充。如需发布为草稿，请加上 --draft 重新运行。",
         "pub_manufacturer_eurp_mismatch": "制造商 / 欧盟负责人与已审核记录不匹配。请选择有效的记录，或以草稿模式发布。",
         "pub_seller_sku_recommended": "强烈建议填写商家 SKU，作为该 SKU 的内部标识符，方便后续查找。如有请补充。",

package/dist/scripts/miravia_client.py

@@ -80,6 +80,12 @@ _BUSINESS_ERROR_HINTS = {
     "BRAND_PERMISSION_DENIED": "Your seller account does not have permission for this brand.",
     "BRAND_PENDING": "Brand is pending approval. Use --draft to publish as inactive draft until the brand permission is granted.",
     "PARAM_ILLEGAL": "Request parameter validation failed. Please check the input fields.",
+    "4234": (
+        "Draft-mode creation reported missing required fields or authorizations. "
+        "If no product ID is returned, the draft was NOT created: complete the "
+        "missing fields/permissions (e.g. brand or category authorization) in "
+        "Seller Center and resubmit."
+    ),
 }
 
 _RETRYABLE_ERROR_CODES = {

package/dist/scripts/product_client.py

@@ -360,6 +360,14 @@ class ProductClient:
 
         # GPSR compliance fields are injected at SKU level (see below).
 
+        # Delivery method -> Miravia create field ``Attributes.deliverySof``
+        # ("DBM" or "DBS"). Only written when the seller explicitly chose one;
+        # when absent, publish_module._check_dbm_limits applies the default
+        # (DBM generally, DBS if the seller has DBS permission).
+        _dm = str(data.get("delivery_method") or "").strip().upper()
+        if _dm in ("DBM", "DBS"):
+            attributes["deliverySof"] = _dm
+
         product_payload: Dict[str, Any] = {
             "PrimaryCategory": category_id,
             "Attributes": attributes,
@@ -379,10 +387,19 @@ class ProductClient:
                         sku["EU_Responsible"] = eurp_name
             product_payload["Skus"] = {"Sku": skus}
 
-        # Sales-property variation definition (optional, only when variations exist)
-        variation = self._build_variation_definition(data)
-        if variation:
-            product_payload["variation"] = variation
+        # Sales-property variation definition — NOT sent.
+        # Verified against ``/product/create``: including a product-level
+        # ``variation`` node ({"variation1": {...}}) makes Miravia reject the
+        # whole request with E005 Invalid Request Format, while the identical
+        # payload WITHOUT it creates successfully (draft item_id
+        # 1374866769737415). Miravia derives sale properties from the flat
+        # per-SKU fields (e.g. ``color: "Blue"``), so the separate node is both
+        # redundant and unsupported by this endpoint. ``_build_variation_definition``
+        # is retained in case a correctly-shaped multi-variation contract is
+        # confirmed later, but we must not inject it here.
+        # variation = self._build_variation_definition(data)
+        # if variation:
+        #     product_payload["variation"] = variation
 
         # Draft mode
         if draft: