@miravia_test/miravia-publish-skill 0.0.0-stage → 0.1.1

package/bin/cli.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * Miravia Publish Skill — CLI Installer
+ *
+ * Usage:
+ *   npx @miravia_test/miravia-publish-skill install [--target <path>] [--agent <qoder|cursor|claude>]
+ *   npx @miravia_test/miravia-publish-skill upgrade
+ *   npx @miravia_test/miravia-publish-skill auth
+ *   npx @miravia_test/miravia-publish-skill --version
+ */
+
+'use strict';
+
+const { install, upgrade, runAuth, showVersion, showHelp } = require('../lib/installer');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--target' && args[i + 1]) {
+      flags.target = args[++i];
+    } else if (args[i] === '--agent' && args[i + 1]) {
+      flags.agent = args[++i];
+    } else if (args[i] === '--no-venv') {
+      flags.noVenv = true;
+    } else if (args[i] === '--help' || args[i] === '-h') {
+      flags.help = true;
+    }
+  }
+  return flags;
+}
+
+const flags = parseFlags(args);
+
+switch (command) {
+  case 'install':
+    install(flags);
+    break;
+  case 'upgrade':
+    upgrade(flags);
+    break;
+  case 'auth':
+    runAuth(flags);
+    break;
+  case '--version':
+  case '-v':
+    showVersion();
+    break;
+  case '--help':
+  case '-h':
+  case undefined:
+    showHelp();
+    break;
+  default:
+    console.error(`\x1b[31mUnknown command: ${command}\x1b[0m`);
+    showHelp();
+    process.exit(1);
+}

package/dist/.keypair.json

@@ -0,0 +1,6 @@
+{
+  "skill_code": "miravia_product_listing",
+  "privateKey": "MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCYZ20McHks1z3Rj9daM0SX1zt+aJwqABv6pMvap4ucalhAJvrxIhQ+ulNFW9zZHAj1cdXZV6QmVEcHXDEKgXpiltWbx9nxnGK5YYaJnevHG77pCsVhtjG5mzmd4ahT8v85txU2+F7ScuYUMfREzy3bFtlSI0wJAwVrFk9/+GuJBlRgneIPgemQOEfHHcVn4dkTiVlKNXi/ZSfet+MZ6RQlje3NChQgckiTX7jVIcQtKVSrW+HB1E/hFqIjihfUYV+wciF7cdBlzqctlmDjWZhhV/iq1XrTKL5xZ1vKLu9KpRaTLqP4pUX/GBsnssWbFWaqPxq3Nqkt3znwggMAB7r7AgMBAAECggEAM4jdrhQmVYxfIgrixmSJsFKekosrK2SoEWRCbqizI+wt9Vt5BasBb4iv+ccrcdryCJU6u+jP4Aoljo6VIrlPuiDJEIlO4E2CcK9SwBw/iy+Nqd3ziqwCOoILxKB2vBRyS4DmUpU/8yfZN0EBGXd5SRl72TOIVY/I+EIuFdbZ/hY4x1aC232d6KEDbCifeebbAKUXQ0dK14dyQuM27qi7GSPGkzNev9hTC/iGSWLh/O04/15qk1FfvUh3iiCL3SxljX6hzWP5q2FN3v/KWoVwgIbmtLBhYVURM+4CCnOFSvFUPhft8kspq7AgPadEI3RCJ6sz4Zr8+NyLA7t1tyZj4QKBgQDW/zHHmKAcGYfL4ujnoTBSrriqbLxYxP+oe81vpT8y88x82CI80fI6UNq8Z0lJbqikWOLKdVvedWVQ+U9cOc7uwP0qW2uorKCLUgADfd5RW4I0WP5/xjNvt6m425EKYCT7W9r0RXi2Ttgp1AJ7Ifvy3GX8hOues+B1OpJZ1RFr6wKBgQC1eEHDgJGMJZLImuje/pyszzTWpTWXcAZ/cLb6Z9VaG9rV36mWvbJ+AkAEyDauJufY8W7Sc/GTJ+1ghaNVr25+usFdnNUg51dtQo19LACHCCb8LXBgZenmUffhj4/Wrcbe4zpFmAOz8JiF3OJBRPwLwfUISOy2rmxH+IzRdxB5MQKBgG7BHgLFhE2VdVg592NDrSIa8fSReWF9cnp39He8N9dmsoPpz5FnUhJqjpQZ3S4f/G5Vf9duJ7ps3ZmeJRzMhuaFsqV8XPSSoU3EG0+xKrLcojGXWtu13c+CXMNnEMu4hbSbOCs4EpxP95lspy6JbkJI+ZzhWIP0BABAAR6X3ZarAoGAczgusT3Rq+UzZHGPB/8rZUGOr/Znp4Z2abYcR7NjsHndIUyIdfBuAznUgfTJWxvSu1jX34HEUYXZXx6azU2833QeUBzC6chZJ0NJaL9melX/wr/rCRnMP/OtaqbnUgw2J9CocAWL3FUX0m6jrYNqcOCufpsmyPrIP44dguWRLRECgYBwfM4FBFjGdynUVlFrTvCvo1J4ZSkh9uVx6Fch7QNDBQIr1/Fbp4jGEQj/yeRWVORJlIGyEiubn+Zc5noieUtHdy36Rfar7UoBdSvbcPSgbESx2DIt1Wf/DQIzBXO0JdYwZYauBs0Gy3sD/H/rapEd9TvDzMqDUA56PgtCixp1Eg==",
+  "publicKey": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAmGdtDHB5LNc90Y/XWjNEl9c7fmicKgAb+qTL2qeLnGpYQCb68SIUPrpTRVvc2RwI9XHV2VekJlRHB1wxCoF6YpbVm8fZ8ZxiuWGGiZ3rxxu+6QrFYbYxuZs5neGoU/L/ObcVNvhe0nLmFDH0RM8t2xbZUiNMCQMFaxZPf/hriQZUYJ3iD4HpkDhHxx3FZ+HZE4lZSjV4v2Un3rfjGekUJY3tzQoUIHJIk1+41SHELSlUq1vhwdRP4RaiI4oX1GFfsHIhe3HQZc6nLZZg41mYYVf4qtV60yi+cWdbyi7vSqUWky6j+KVF/xgbJ7LFmxVmqj8atzapLd858IIDAAe6+wIDAQAB",
+  "signMethod": "SHA256withRSA"
+}

package/dist/README.md

@@ -0,0 +1,133 @@
+# Miravia Publish Skill · 商品发布（Product Publish）
+
+> Miravia Skill Hub · 官方维护
+> 让 AI Agent 直接帮助 Miravia 卖家发布商品：手动创建或上传文件/URL 由 AI 自动抽取字段后发布。
+
+---
+
+## 1. 这个 Skill 能做什么
+
+在任意支持 Skill 的 AI Agent（Cursor / Qoder / Claude Code）中输入自然语言，Skill 会引导完成商品创建：
+
+| 方式 | 输入 | 典型输出 |
+|------|------|----------|
+| 手动创建 | CLI 参数（类目、标题、品牌、图片、SKU 等） | 商品 ID、PDP 链接、审核提示 |
+| AI 自动发品 | 文件/文件夹/URL（PDF/Word/Excel/图片/网页） | 抽取摘要 → 多阶段确认 → 发布结果 |
+
+无需登录 Seller Center，无需手写 API 调用。
+
+---
+
+## 2. 安装
+
+### 方式一：手动安装（zip）
+
+1. 下载 `miravia_product_listing.zip`。
+2. 解压到 Agent 的 Skill 目录，例如 `~/.qoder/skills/miravia_product_listing`。
+3. 在 Skill 根目录安装依赖：
+
+   ```bash
+   cd miravia_product_listing
+   pip install -r requirements.txt
+   ```
+
+> 本文档所有命令均在 **Skill 根目录** 下执行，路径使用相对形式。
+
+### 方式二：命令安装
+
+在 Agent 对话框中输入：
+
+```
+请使用 npx miravia-skill install miravia_product_listing 安装商品发布 Skill
+```
+
+---
+
+## 3. 授权
+
+> **授权端点**：`https://sellercenter.miravia.es/apps/seller/skill/auth`
+
+本 Skill 不内置任何 `appKey` / `appSecret` / `accessToken`，必须通过 Skill Hub 完成授权。
+
+> ❗ **重要：凭证不可跨 Skill 复制。**
+> 每个 Skill 有独立的 `skill_code`（本 Skill 为 `miravia_product_listing`），
+> 密钥派生和加密均与其绑定。从其他 Skill（如 `manage-stock-management`）复制
+> `credentials.json` 或 `.keypair.json` 将导致解密失败。必须在每个 Skill 目录独立运行授权。
+
+```bash
+python scripts/auth_cli.py login
+```
+
+流程：
+
+1. CLI 在本地生成 RSA 密钥对，写入 `.keypair.json`。
+2. 浏览器打开 Skill Hub 授权页，卖家点击同意。
+3. 授权页把加密后的凭证通过 redirect_uri 传回本地回调。
+4. CLI 用私钥解密，加密存储到 `credentials.json`。
+
+> `.keypair.json` 与 `credentials.json` 已写入 `.gitignore`，**禁止**提交或随压缩包分发。
+
+---
+
+## 4. 快速开始
+
+### 4.1 查看问候语
+
+```bash
+python scripts/product_skill.py --agent-type qoder --greeting
+```
+
+### 4.2 手动创建商品
+
+```bash
+python scripts/product_skill.py --agent-type qoder --scenario create_product \
+  --category-id 62198631 \
+  --product-name "Nike Women's White Running Shoes" \
+  --brand-name Nike \
+  --image-urls "https://example.com/1.jpg" \
+  --sku-data '[{"seller_sku":"NK-W-37","price":59.99,"quantity":100}]'
+```
+
+### 4.3 AI 抽取并查看结构
+
+```bash
+python scripts/product_skill.py --agent-type qoder --scenario create_product \
+  --source ./product_info.pdf --output-schema
+```
+
+### 4.4 AI 抽取后直接发布流程
+
+```bash
+python scripts/product_skill.py --agent-type qoder --scenario create_product \
+  --source ./product_info.pdf
+```
+
+后续按返回的 `ctb_confirm_token`、`field_summary_token`、`publish_preview_token` 分阶段确认。
+
+---
+
+## 5. 核心设计
+
+- **唯一入口**：所有商品创建必须经 `scripts/product_skill.py` 执行，上层 Agent 禁止直接调用 Miravia 开放平台商品创建接口。
+- **三阶段确认**：类目/标题/品牌确认 → 字段摘要/草稿确认 → 最终发布预览确认。
+- **pre-check 集中**：品牌/类目权限等校验统一在 `/product/batchValidate` 提交前完成。
+- **必填项阻断**：图片、常规价格、重量、长/宽/高缺失时不能直接发布。
+- **草稿模式**：关键字段缺失或品牌权限不足（`BRAND_PENDING` / `BRAND_PERMISSION_DENIED`）时，商家可选择 `--draft` 发布为 `inactive`，待审核通过后自动激活。
+- **品牌创建后重跑**：品牌未找到时不自动轮询，给出 Seller Center 创建链接，创建完成后商家重跑命令。
+
+---
+
+## 6. 文档索引
+
+| 文件 | 说明 |
+|------|------|
+| `SKILL.md` | Skill 契约：场景、路由规则、CLI 参数、字段术语 |
+| `TECHNICAL.md` | 技术配置、授权、打包、FAQ |
+| `reference_publish.md` | 商品发布 API 字段映射与示例 |
+
+---
+
+## 7. 支持
+
+- 语言：`en` / `es` / `it` / `zh`（通过 `--lang` 切换）
+- Python 版本：3.9+

package/dist/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: miravia_product_listing
+description: Miravia 商品发布 AI Skill。仅负责商品创建（手动一次性录入或 AI 从文件/URL 抽取后发布），不包含库存管理。与库存 Skill 共用同一套 Miravia Skill Hub 授权机制。
+---
+
+# Miravia Publish Skill
+
+> 面向 Miravia 卖家的 AI Agent Skill，专注于商品发布（Product Publish）。
+> **本 Skill 的鉴权机制与库存/订单 Skill 完全一致**：复用同一套 Skill Hub 授权流程、本地凭证加密存储与开放平台 API 签名方式。
+
+---
+
+## 1. 模块架构
+
+| Domain | 模块 | 说明 |
+|--------|------|------|
+| `publish` | Product Publish | 商品创建；支持手动录入与 AI 自动抽取两种模式 |
+
+### 1.1 入口脚本
+
+- `scripts/product_skill.py` — 商品发布唯一入口。
+
+### 1.2 核心子模块
+
+| 文件 | 职责 |
+|------|------|
+| `scripts/modules/publish_module.py` | 发布流程主控（类目/品牌/属性/图片/SKU/合规/确认/创建） |
+| `scripts/modules/extraction_engine.py` | 从源文本抽取 `MiraviaListingSchema` |
+| `scripts/modules/file_reader.py` | 读取本地文件、文件夹或网页 URL |
+| `scripts/field_definitions.py` | 商品字段定义与术语说明，供 LLM 抽取与提示使用 |
+| `scripts/product_client.py` | Miravia 商品/图片/类目/品牌/合规 API 封装 |
+| `scripts/miravia_client.py` | 开放平台请求签名、重试、埋点 |
+| `scripts/auth_cli.py` | Skill Hub 授权登录 |
+| `scripts/config.py` | 凭证与 API 配置 |
+
+---
+
+## 2. 路由规则
+
+1. 商家提到「发布商品」「创建商品」「上传产品」「AI 发品」等意图时，必须路由到本 Skill 的 `publish` 域。
+2. 上层 Agent **禁止**直接调用 Miravia 开放平台商品创建接口，否则类目属性查询、图片迁移、品牌/合规确认等安全流程会失效。
+3. 库存相关请求（查库存、改库存、缺货预警等）应路由到独立的库存 Skill。
+
+---
+
+## 3. 场景
+
+| Scenario | 用户意图 | 典型输出 |
+|----------|----------|----------|
+| `create_product` | 创建新商品 | 商品 ID、PDP 链接、审核提示 |
+
+`create_product` 有两种使用方式：
+
+- **手动模式**：通过 CLI 参数传入 `--category-id`、`--product-name`、`--brand-name`、属性、图片、SKU 等。
+- **AI 抽取模式**：通过 `--source` 传入文件/文件夹/URL，Skill 自动读取并抽取字段，再按多阶段确认流程发布。
+
+---
+
+## 4. 创建商品流程
+
+### 4.1 手动模式
+
+1. 校验 `--category-id` 与 `--product-name`。
+2. 解析品牌（`--brand-name`），歧义时返回候选让商家确认。
+3. 构建类目属性（`--attribute-data`）。
+4. 处理图片（`--image-urls` 外部 URL 自动迁移）。
+5. 构建 SKU（`--sku-data`）。
+6. 生成 `publish_preview_token`，返回 `status: preview`。
+7. 商家回传 token 后执行 `/product/batchValidate` 预校验。
+8. 调用 `/product/create` 创建商品，返回 `item_id` 与 PDP 链接。
+
+### 4.2 AI 抽取模式
+
+0. **Stage 0 - 授权确认**：
+   - 首次操作时，Skill 返回 `status: need_authorization`，列出三项授权请求（读取卖家资料、访问商品数据、更新商品数据）。
+   - 卖家确认后，加 `--authorized` 重新运行命令，进入后续流程。
+1. 读取 `--source` 指定的文件/文件夹/URL。
+2. 使用 LLM 抽取 `MiraviaListingSchema`；可通过 `--output-schema` 仅查看抽取结果。
+3. **Stage 1 - 类目/标题/品牌确认（CTB）**：
+   - 解析 category / brand，返回候选供确认。
+   - 生成 `ctb_confirm_token`，返回 `status: need_ctb_confirm`。
+4. **Stage 2 - 拉取上下文**：
+   - `/category/attributes/get` 获取类目属性。
+   - `/seller/shipping_permission/get` 决定默认物流方式（DBS/DBM）。
+   - `/manufacturer/get`、`/eu/responsible/person/get` 匹配制造商/EU 负责人。
+5. **Stage 3 - 关键字段检查**：
+   - 缺少图片、价格、重量、长宽高时直接阻断（`status: need_mandatory_fields`）。
+6. **Stage 4 - 字段摘要/草稿确认**：
+   - 汇总已抽取字段与缺失字段。
+   - 关键字段缺失时询问是否以 `--draft` 模式发布为 `inactive`。
+   - 生成 `field_summary_token`，返回 `status: need_field_summary`。
+7. **Stage 5 - 最终确认与创建**：
+   - 回传 `field_summary_token` 后生成最终 `publish_preview_token`。
+   - 执行 `/product/batchValidate`。
+   - 调用 `/product/create`。
+
+### 4.3 特殊状态
+
+| 状态 | 含义 | 处理方式 |
+|------|------|----------|
+| `need_authorization` | 需要卖家授权三项操作权限 | 卖家确认后加 `--authorized` 重新运行 |
+| `need_category` | 类目未找到或存在多个候选 | 让用户提供正确的类目 ID（`--category-id`）或从候选中选择一个（`--confirmed-category-id`），**禁止重复搜索同一关键词** |
+| `need_brand` | 品牌未找到或存在多个候选 | 让用户提供正确的品牌名（`--brand-name`）或从候选中选择一个（`--confirmed-brand-id`），**禁止重复搜索同一关键词** |
+| `need_ctb_confirm` | 需要确认类目/标题/品牌 | 回传 `ctb_confirm_token` |
+| `need_brand_create` | 品牌未找到，需去 Seller Center 创建 | 创建后重新运行命令 |
+| `need_mandatory_fields` | 缺少必填字段（图片/价格/重量/尺寸） | 补充字段后重跑 |
+| `need_category_attributes` | 类目必填属性缺失（AI抽取模式） | 通过 `--attribute-data` 补充或使用 `--draft` |
+| `need_field_summary` | 需要确认字段摘要或选择草稿模式 | 回传 `field_summary_token`，可加 `--draft` |
+| `need_compliance` | 制造商/EU 负责人匹配失败 | 按返回候选选择或补充信息后重跑 |
+| `need_images` | 部分图片迁移失败 | 替换图片后重跑 |
+| `preview` | 最终发布预览 | 回传 `publish_preview_token` |
+| `success` | 创建成功 | 返回 `item_id`、`pdp_url`、审核提示 |
+| `brand_permission_failed` | 品牌权限不足/待审批 (BRAND_PENDING / BRAND_PERMISSION_DENIED) | 加 `--draft` 发布为草稿，或在 Seller Center 申请品牌权限后重跑 |
+
+---
+
+## 5. 核心约束
+
+| ID | 规则 | 说明 |
+|----|------|------|
+| P1 | **sellerId 自动注入** | 从开放平台鉴权上下文读取，禁止用户传入。 |
+| P2 | **类目决定属性** | 创建前必须先确定叶子类目，再调 `/category/attributes/get`。 |
+| P3 | **图片先迁移** | 外部图片 URL 必须经 `/image/migrate` 迁移到 Miravia CDN。 |
+| P4 | **三阶段确认** | CTB 确认 → 字段摘要确认 → 最终发布预览确认。 |
+| P5 | **pre-check 集中** | 品牌/类目权限等校验统一在 `/product/batchValidate` 提交前完成。 |
+| P6 | **必填项阻断** | 图片、常规价格、重量、长/宽/高缺失时不能直接发布。 |
+| P7 | **草稿模式** | 关键字段缺失时，商家可选择 `--draft` 发布为 `inactive`。 |
+| P8 | **品牌创建后重跑** | 品牌未找到时不自动轮询，给出 Seller Center 创建链接，创建完成后商家重跑命令。 |
+| P9 | **默认物流** | 通过 `/seller/shipping_permission/get` 的 `DBS_permission` 决定默认 `DBS` 或 `DBM`。 |
+| P10 | **合规匹配** | 制造商与 EU 负责人名称必须与接口返回精确匹配，否则返回候选列表。 |
+| P11 | **API 重试** | 每个 API 调用最多重试 3 次。 |
+| P12 | **埋点与审计** | 记录 Skill 调用与商品操作审计日志。 |
+| P13 | **创建前必须确认** | AI Agent **禁止**在收集完信息后直接调用 `/product/create`。必须先向卖家展示完整字段摘要（标题、类目、品牌、价格、SKU、包装、图片、GPSR、Safety warning 等所有已填字段），明确标注缺失字段，等卖家回复「确认」后才能执行创建。无论手动模式还是 AI 抽取模式均适用。 |
+
+---
+
+## 6. CLI 参考
+
+入口脚本：`scripts/product_skill.py`
+
+```bash
+# 查看问候语
+python scripts/product_skill.py --agent-type qoder --greeting
+
+# 手动创建商品
+python scripts/product_skill.py --agent-type qoder --scenario create_product \
+  --category-id 62198631 --product-name "Nike Women's White Running Shoes" \
+  --brand-name Nike --image-urls "https://example.com/1.jpg" \
+  --sku-data '[{"seller_sku":"NK-W-37","price":59.99,"quantity":100}]'
+
+# AI 抽取并查看 schema
+python scripts/product_skill.py --agent-type qoder --scenario create_product \
+  --source ./product_info.pdf --output-schema
+
+# AI 抽取发品
+python scripts/product_skill.py --agent-type qoder --scenario create_product \
+  --source ./product_info.pdf
+
+# 关键字段缺失时以草稿模式发布
+python scripts/product_skill.py --agent-type qoder --scenario create_product \
+  --source ./product_info.docx --draft
+```
+
+### 6.1 常用参数
+
+| Flag | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `--scenario` | 否 | `create_product` | 场景，当前仅支持 `create_product` |
+| `--source` | 否 | — | 文件/文件夹/URL，可多次指定 |
+| `--category-id` | 否 | — | 叶子类目 ID |
+| `--confirmed-category-id` | 否 | — | 确认后的类目 ID |
+| `--product-name` | 否 | — | 商品标题 |
+| `--brand-name` | 否 | — | 品牌名 |
+| `--confirmed-brand-id` | 否 | — | 确认后的品牌 ID |
+| `--description` | 否 | — | 商品描述 |
+| `--attribute-data` | 否 | — | 类目属性 JSON |
+| `--image-urls` | 否 | — | 逗号分隔的图片 URL |
+| `--sku-data` | 否 | — | SKU JSON 或文件路径 |
+| `--draft` | 否 | false | 关键字段缺失时发布为 draft |
+| `--authorized` | 否 | false | 卖家已确认授权，跳过授权步骤 |
+| `--output-schema` | 否 | false | 仅输出抽取结构，不发布 |
+| `--ctb-confirm-token` | 否 | — | CTB 阶段返回的 HMAC token |
+| `--field-summary-token` | 否 | — | 字段摘要阶段返回的 HMAC token |
+| `--publish-preview-token` | 否 | — | 最终发布预览的 HMAC token |
+| `--lang` | 否 | `auto` | 输出语言：en / es / it / zh |
+| `--output` | 否 | `./out` | 输出目录 |
+| `--format` | 否 | `conversational` | 输出格式：json / conversational |
+
+---
+
+## 7. 首次激活问候语
+
+```text
+只需在此处上传您产品的所有资料，例如上传源文件，或选择产品信息所在的文件夹位置，或输入产品信息的网页 URL，本技能将相应地提取信息并将产品发布到 Miravia。
+```
+
+问候语支持 `zh` / `en` / `es` / `it`，见 `scripts/i18n.py` 中的 `pub_greeting`。
+
+---
+
+## 8. 字段与术语定义
+
+- 完整字段定义：`scripts/field_definitions.py`
+- 接口字段映射与示例：`reference_publish.md`
+
+主要术语：
+
+| 术语 | 含义 |
+|------|------|
+| CRO | Conversion Rate Optimization，平台对类目图片/描述的优化要求 |
+| DBM | Drop Shipping by Merchant，商家自发货 |
+| DBS | Drop Shipping by Seller（平台物流），需卖家具备 DBS 权限 |
+| Draft | 草稿状态商品，创建后 `Status: inactive`，可后续补充再上架 |
+
+---
+
+## 9. 文件清单
+
+```
+SKILL.md
+requirements.txt
+.gitignore
+reference_publish.md
+scripts/product_skill.py
+scripts/auth_cli.py
+scripts/cli_common.py
+scripts/config.py
+scripts/cred_crypto.py
+scripts/error_logger.py
+scripts/field_definitions.py
+scripts/i18n.py
+scripts/miravia_client.py
+scripts/product_client.py
+scripts/skill_crypto.py
+scripts/skill_keypair.py
+scripts/skill_logger.py
+scripts/telemetry.py
+scripts/trace_logger.py
+scripts/modules/__init__.py
+scripts/modules/publish_module.py
+scripts/modules/extraction_engine.py
+scripts/modules/file_reader.py
+```

package/dist/TECHNICAL.md

@@ -0,0 +1,126 @@
+# Miravia Publish Skill — 技术配置与部署文档
+
+> 本文档面向：负责 Skill 平台配置、商家授权、联调测试的同学。
+
+---
+
+## 1. Skill 概述
+
+| 项目 | 内容 |
+|---|---|
+| Skill Code | `miravia_publish_skill` |
+| 业务域 | Product Publish（商品发布） |
+| 入口脚本 | `scripts/product_skill.py` |
+| 授权脚本 | `scripts/auth_cli.py` |
+| 支持语言 | `en` / `es` / `it` / `zh`（通过 `--lang` 切换） |
+
+---
+
+## 2. 前置条件
+
+### 2.1 开放平台 API 权限
+
+本 Skill 调用 Miravia 商品类开放平台 API，需要先在 [Miravia Open Platform](https://open.miravia.com) 完成准入。
+
+| 权限组 | 典型接口 | 用途 |
+|---|---|---|
+| `PRODUCT_API` | `/product/create` | 创建商品 |
+| `PRODUCT_API` | `/product/batchValidate` | 发布前批量校验 |
+| `PRODUCT_API` | `/category/tree/get`, `/category/search/keyword` | 类目树/关键词搜索 |
+| `PRODUCT_API` | `/category/attributes/get` | 类目属性查询 |
+| `PRODUCT_API` | `/category/brand/search` | 品牌搜索 |
+| `PRODUCT_API` | `/image/migrate`, `/image/upload`, `/image/response/get` | 图片迁移/上传/结果查询 |
+| `SELLER_API` | `/seller/shipping_permission/get` | 物流权限查询 |
+| `SELLER_API` | `/eu/responsible/person/get`, `/manufacturer/get` | 欧盟负责人、制造商信息 |
+
+### 2.2 Python 环境
+
+- Python 3.9+
+- 安装依赖：`pip install -r requirements.txt`
+
+---
+
+## 3. 授权流程
+
+与库存/订单 Skill 共用同一套 Skill Hub 授权：
+
+```bash
+python scripts/auth_cli.py login
+```
+
+流程：
+
+1. 生成本地 RSA 密钥对，写入 `.keypair.json`。
+2. 浏览器跳转 Skill Hub 授权页。
+3. 授权成功后，前端用公钥加密凭证，通过 redirect_uri 传回本地回调。
+4. CLI 用私钥解密，加密存储到 `credentials.json`。
+
+> `.keypair.json` 与 `credentials.json` 已写入 `.gitignore`，**禁止**提交到代码仓库或随压缩包分发。
+
+---
+
+## 4. 运行示例
+
+### 4.1 手动创建
+
+```bash
+python scripts/product_skill.py --agent-type qoder --scenario create_product \
+  --category-id 62198631 \
+  --product-name "Nike Women's White Running Shoes" \
+  --brand-name Nike \
+  --image-urls "https://example.com/1.jpg,https://example.com/2.jpg" \
+  --sku-data '[{"seller_sku":"NK-W-37","price":59.99,"quantity":100}]'
+```
+
+### 4.2 AI 抽取发品
+
+```bash
+python scripts/product_skill.py --agent-type qoder --scenario create_product \
+  --source ./product_info.pdf
+```
+
+### 4.3 仅查看抽取结构
+
+```bash
+python scripts/product_skill.py --agent-type qoder --scenario create_product \
+  --source ./product_info.pdf --output-schema
+```
+
+---
+
+## 5. 打包规范
+
+上传 Skill 平台的压缩包应至少包含：
+
+- `SKILL.md`
+- `requirements.txt`
+- `.gitignore`
+- `scripts/` 下所有运行所需文件
+
+不包含：
+
+- `.keypair.json`
+- `credentials.json`
+- `logs/`, `out/`, `.venv/`, `__pycache__/`
+
+打包命令示例：
+
+```bash
+zip -r miravia_product_listing.zip . \
+  -x miravia_product_listing.zip \
+     .keypair.json credentials.json \
+     'logs/*' 'out/*' '.venv/*' '*.DS_Store' '*.pyc' '__pycache__/*'
+```
+
+---
+
+## 6. 常见问题
+
+**Q: 运行时报 `CredentialMissingError`？**
+A: 尚未完成授权，请先执行 `python scripts/auth_cli.py login`。
+
+**Q: AI 抽取效果差？**
+A: 配置 `OPENAI_API_KEY` 或 `DASHSCOPE_API_KEY` 环境变量，使 `modules/extraction_engine.py` 走 LLM 抽取；否则 fallback 到 heuristic 规则，准确度有限。
+
+**Q: 品牌未找到怎么办？**
+A: Skill 会返回 `need_brand_create` 状态与 Seller Center 创建链接。卖家创建品牌后，重新运行相同命令即可继续。

package/dist/VERSION

@@ -0,0 +1 @@
+0.1.1