@miravia_test/miravia-publish-skill 0.1.3 → 0.1.5

package/dist/SKILL.md

@@ -119,6 +119,7 @@ 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 重跑；不要绕过确认流程改走手动模式 |
 | `invalid_url` | 输入的 URL 无法抓取 | 提示检查 URL 后重试 |
 | `title_invalid` | 商品标题不符合规范（过短/过长/词数不足） | 提示具体错误 + 标题格式建议（Brand+Category+Model+Features+Scenario），阻断后续流程，禁止转 Draft |
 | `need_category_permission` | 卖家无该类目发布权限 | 询问是否以 Draft 模式发布（待审批通过后自动激活），提供类目权限申请链接 https://sellercenter.miravia.es/apps/setting/category；或更换类目后重跑 |

package/dist/VERSION

@@ -1 +1 @@
-0.1.3
+0.1.5

package/dist/reference_publish.md

@@ -249,7 +249,7 @@ PRD 中标记为新增 API，但当前 Miravia Open Platform 文档站点未上
 
 | Schema 字段（snake_case） | API 字段 / 位置 | 必填 | 说明 |
 |---|---|---|---|
-| `product_title` | `Attributes.name` | M | 商品标题，20~255 字符，≥5 个单词 |
+| `product_title` | `Attributes.name` | M | 商品标题，20~205 字符，≥5 个单词 |
 | `product_images` | `Images.Image[]` | M | 主图列表，第 1 张为主图 |
 | `product_long_description` | `Attributes.description` | O | 长描述，可含简单 HTML |
 | `category_id` | `PrimaryCategory` | M | 叶子类目 ID |

package/dist/scripts/extraction_engine.py

@@ -102,6 +102,20 @@ class MiraviaListingSchema:
 # ---------------------------------------------------------------------------
 
 
+class LLMNotConfiguredError(RuntimeError):
+    """Raised when AI extraction is requested but no LLM API key is configured.
+
+    Callers must surface this as a structured "llm_not_configured" status so
+    agents prompt for the key instead of silently bypassing the confirm-first
+    extraction flow.
+    """
+
+
+LLM_NOT_CONFIGURED_HINT = (
+    "No LLM API key configured. Set OPENAI_API_KEY or DASHSCOPE_API_KEY."
+)
+
+
 class LLMClient:
     """Minimal OpenAI-compatible LLM client."""
 
@@ -181,8 +195,12 @@ class ExtractionEngine:
 
     def extract(self, source_text: str) -> MiraviaListingSchema:
         if not self.client.is_configured():
-            logger.warning("LLM not configured; running heuristic extraction")
-            return self._heuristic_extract(source_text)
+            # Never silently degrade to heuristic extraction: without LLM the
+            # confirm-first flow (ctb → field summary → publish) breaks because
+            # agents judge the regex output unreliable and bypass the skill.
+            # Fail loudly so the caller returns a structured status instead.
+            logger.error("LLM not configured; refusing heuristic fallback")
+            raise LLMNotConfiguredError(LLM_NOT_CONFIGURED_HINT)
 
         schema_fields = "\n".join(f"- {f.name}" for f in fields(MiraviaListingSchema))
         messages = [

package/dist/scripts/field_definitions.py

@@ -16,7 +16,7 @@ FIELD_DEFINITIONS: Dict[str, Dict[str, str]] = {
         "mo": "Mandatory",
         "definition": "The title / name of the product.",
         "requirement": (
-            "Length must be greater than 20 characters and less than 255 characters. "
+            "Length must be greater than 20 characters and less than 205 characters. "
             "Suggested format: Brand + category + collection/model + key features + using scenarios."
         ),
     },
@@ -375,7 +375,7 @@ FIELD_DEFINITIONS: Dict[str, Dict[str, str]] = {
 
 FIELD_GUIDES: Dict[str, Dict[str, str]] = {
     "en": {
-        "product_title": "Product title (Mandatory): The title / name of the product. Must be 20-255 characters. Suggested format: Brand + category + collection/model + key features + using scenarios.",
+        "product_title": "Product title (Mandatory): The title / name of the product. Must be 20-205 characters. Suggested format: Brand + category + collection/model + key features + using scenarios.",
         "product_images": "Product images (Mandatory): Image URLs. The first image is the main image shown in search/home. First image must have white background, 1:1 aspect ratio, 330-5000px, <5MB, jpg/png/jpeg/webp. Max 8 images.",
         "product_long_description": "Product long description (Optional): May include simple HTML. 20-3000 characters; embedded HTML is not supported.",
         "category_id": "Category ID (Mandatory): The internal Miravia leaf category ID where the product will be listed.",
@@ -414,7 +414,7 @@ FIELD_GUIDES: Dict[str, Dict[str, str]] = {
         "selling_marketplace_aliexpress": "Selling marketplace - AliExpress (Optional): Selling status per country on the AliExpress platform.",
     },
     "zh": {
-        "product_title": "商品标题（必填）：商品的标题/名称。长度需大于 20 且小于 255 个字符。建议格式：品牌 + 类目 + 系列/型号 + 核心卖点 + 使用场景。",
+        "product_title": "商品标题（必填）：商品的标题/名称。长度需大于 20 且小于 205 个字符。建议格式：品牌 + 类目 + 系列/型号 + 核心卖点 + 使用场景。",
         "product_images": "商品图片（必填）：商品图片 URL。第一张图是在搜索/首页展示的主图，必须使用纯白背景、1:1 比例、330-5000px、<5MB，仅支持 jpg/png/jpeg/webp。最多 8 张。",
         "product_long_description": "商品长描述（选填）：可包含简单 HTML 的长描述。长度 20-3000 字符；不支持嵌套复杂 HTML，建议使用列表、加粗、字体等简单标签。",
         "category_id": "类目 ID（必填）：Miravia 叶子类目内部 ID，商品将挂靠在该类目下。",

package/dist/scripts/i18n.py

@@ -172,6 +172,8 @@ 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_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.",
@@ -807,6 +809,8 @@ 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_create_requires_category": "创建商品必须提供 --category-id（叶子类目 ID）",
         "pub_create_requires_name": "创建商品必须提供 --product-name（商品标题）",
         "pub_create_preview_message": "请检查以下商品信息，确认无误后我将创建商品。",

package/dist/scripts/product_client.py

@@ -240,12 +240,12 @@ class ProductClient:
         Returns:
             List of category candidates, each with category_id, name, confidence, etc.
         """
-        body: Dict[str, Any] = {}
+        params: Dict[str, Any] = {}
         if title:
-            body["title"] = title
+            params["title"] = title
         if image_urls:
-            body["imageUrls"] = image_urls
-        result = self.client.request("POST", "/product/category/recommend/get", body)
+            params["imageUrls"] = image_urls
+        result = self.client.request("GET", "/product/category/recommend/get", params)
         data = result.get("data", []) or []
         if isinstance(data, list):
             return data

package/dist/scripts/product_skill.py

@@ -327,6 +327,15 @@ def _print_conversational_result(result: Dict[str, Any]) -> None:
             print(f"• {action}")
         return
 
+    # LLM not configured — fail loudly so agents configure the key instead of
+    # bypassing the confirm-first flow with manual mode
+    if status == "llm_not_configured":
+        print(result.get("message", ""))
+        print()
+        for action in result.get("next_actions", []):
+            print(f"• {action}")
+        return
+
     # Invalid URL
     if status == "invalid_url":
         print(result.get("message", ""))

package/dist/scripts/publish_module.py

@@ -33,6 +33,7 @@ from extraction_engine import (
     CRITICAL_FIELDS,
     ExtractionEngine,
     LLMClient,
+    LLMNotConfiguredError,
     MiraviaListingSchema,
     check_missing,
     validate_title,
@@ -156,10 +157,25 @@ class PublishModule:
         category_id = self.args.category_id
         product_name = self.args.product_name
         if not category_id:
-            raise ValueError(i18n._("pub_create_requires_category"))
+            return {
+                "status": "need_category",
+                "message": i18n._("pub_create_requires_category"),
+                "next_actions": [i18n._("pub_ai_post_provide_category")],
+            }
         if not product_name:
-            raise ValueError(i18n._("pub_create_requires_name"))
-        _validate_title(product_name)
+            return {
+                "status": "title_invalid",
+                "message": i18n._("pub_create_requires_name"),
+                "next_actions": [i18n._("pub_ai_post_requires_source")],
+            }
+        title_err = validate_title(product_name)
+        if title_err:
+            return {
+                "status": "title_invalid",
+                "message": title_err,
+                "format_suggestion": i18n._("pub_title_format_suggestion"),
+                "next_actions": [i18n._("pub_ai_post_requires_source")],
+            }
 
         brand_resolution = self._resolve_brand_interactive()
         if brand_resolution.get("status") == "need_brand":
@@ -1095,7 +1111,11 @@ class PublishModule:
                 "next_actions": [i18n._("pub_ai_post_requires_source")],
             }
         if not content_items:
-            raise ValueError(i18n._("pub_ai_post_no_content"))
+            return {
+                "status": "file_empty_or_corrupted",
+                "message": i18n._("pub_file_empty_or_corrupted", source=sources[0] if sources else ""),
+                "next_actions": [i18n._("pub_ai_post_requires_source")],
+            }
 
         # Check for multiple products in Excel
         row_count = get_excel_row_count(content_items)
@@ -1115,7 +1135,18 @@ class PublishModule:
 
         source_text = extract_text(content_items)
         engine = ExtractionEngine(LLMClient())
-        schema = engine.extract(source_text)
+        try:
+            schema = engine.extract(source_text)
+        except LLMNotConfiguredError:
+            # Fail loudly instead of degrading to regex: without LLM the
+            # confirm-first order (title/brand/category before missing-field
+            # summary) cannot be guaranteed, so agents must configure the key
+            # rather than bypass the skill.
+            return {
+                "status": "llm_not_configured",
+                "message": i18n._("pub_llm_not_configured"),
+                "next_actions": [i18n._("pub_llm_not_configured_next")],
+            }
 
         if getattr(self.args, "output_schema", False):
             return {
@@ -1738,7 +1769,7 @@ class PublishModule:
 
         package_dims = ("package_weight", "package_length", "package_width", "package_height")
         for idx, sku in enumerate(skus, start=1):
-            if not sku.get("SellerSku"):
+            if not (sku.get("SellerSku") or sku.get("seller_sku")):
                 missing.append(f"Seller SKU (SKU #{idx})")
             for dim in package_dims:
                 val = sku.get(dim)
@@ -1809,7 +1840,7 @@ class PublishModule:
         if self._is_category_attribute_mandatory(category_attributes, "compliance_documents") and not schema.compliance_documents:
             missing.append("compliance_documents")
 
-        if not any(sku.get("SellerSku") for sku in skus):
+        if not any(sku.get("SellerSku") or sku.get("seller_sku") for sku in skus):
             missing.append("seller_sku")
 
         return missing
@@ -2727,6 +2758,11 @@ class PublishModule:
         skus: List[Dict[str, Any]] = []
         for idx, sku in enumerate(data):
             processed = dict(sku)
+            # Normalize seller_sku → SellerSku (accept both snake_case and PascalCase)
+            if "seller_sku" in processed and "SellerSku" not in processed:
+                processed["SellerSku"] = processed.pop("seller_sku")
+            elif "seller_sku" in processed:
+                processed.pop("seller_sku")  # SellerSku already set
             if not processed.get("SellerSku"):
                 raise ValueError(
                     i18n._("pub_seller_sku_required", idx=idx + 1)
@@ -2904,7 +2940,7 @@ def _validate_create_payload(payload: Dict[str, Any]) -> None:
         raise ValueError(i18n._("pub_ean_duplicate_in_product"))
 
     # Check Seller SKU duplicate within same product
-    seller_skus = [sku.get("SellerSku") for sku in skus if sku.get("SellerSku")]
+    seller_skus = [sku.get("SellerSku") or sku.get("seller_sku") for sku in skus if sku.get("SellerSku") or sku.get("seller_sku")]
     if len(seller_skus) != len(set(seller_skus)):
         raise ValueError(i18n._("pub_seller_sku_duplicate_in_product"))
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miravia_test/miravia-publish-skill",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Miravia Product Publish Skill installer — one command to install the Miravia AI product listing skill into any AI Agent (Qoder / Cursor / Claude Code). Upload materials and let the AI extract data and publish products automatically.",
   "bin": {
     "miravia-publish-skill": "bin/cli.js"