@miravia_test/miravia-publish-skill 0.1.4 → 0.1.6

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 封装 |
@@ -75,7 +75,7 @@ description: Miravia 商品发布 AI Skill。仅负责商品创建（手动一
    - 首次操作时，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`。
@@ -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` | 非表格源（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；或更换类目后重跑 |

package/dist/VERSION

@@ -1 +1 @@
-0.1.4
+0.1.6

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 = [
@@ -318,3 +336,246 @@ 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()
+
+
+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 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]] = {}
+
+    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))
+
+    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)
+
+    # 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,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_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,8 +33,10 @@ from extraction_engine import (
     CRITICAL_FIELDS,
     ExtractionEngine,
     LLMClient,
+    LLMNotConfiguredError,
     MiraviaListingSchema,
     check_missing,
+    extract_schema_from_tables,
     validate_title,
 )
 from file_reader import extract_text, read_sources, get_excel_row_count
@@ -1134,7 +1136,25 @@ class PublishModule:
 
         source_text = extract_text(content_items)
         engine = ExtractionEngine(LLMClient())
-        schema = engine.extract(source_text)
+
+        # Excel/CSV are structured tables: extract by header rules first so
+        # the mainstream flow never needs an LLM API key. Fall back to LLM
+        # only when rule extraction matches nothing usable (non-table or
+        # unrecognized headers).
+        schema = extract_schema_from_tables(content_items)
+        if schema is None:
+            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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miravia_test/miravia-publish-skill",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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"