商品图自动上架（Product Image → Listing）
Overview
把"商品上架"这件繁琐事压成一步：丢一张（或一文件夹）商品图进来，技能先做视觉识别与文案生成，产出标准化商品数据 + 可视化详情页，再按你配置的 REST 适配器把数据推送到自建商城/ERP 完成上架。单图与批量均支持，上架前必须经人工确认。
When to use
- 用户提供商品图片（单张或文件夹），并希望自动生成商品信息/详情并上架
- 用户抱怨商品上架繁琐、想在多个商城/ERP 间批量铺货
- 触发语示例："这张图帮我上架""把这批商品图都上架到商城""看图生成商品详情"
前置条件（一次性配置）
首次使用前，准备一份上架适配器配置（REST）：
1. 复制 references/adapter_config.example.yaml 到工作区根目录，改名为 adapter_config.yaml
2. 按你的商城/ERP 实际接口填写：base_url / endpoint / method / auth / field_mapping / constants / response_id_path
3. 字段映射的"源路径"参见 references/product_schema.md 的标准结构；"目标字段"填你的接口字段名
4. 密钥一律用 ${环境变量} 占位（如 ${MAIN_MALL_TOKEN}），禁止明文
技能运行时优先在 {cwd}/adapter_config.yaml 查找配置；找不到则提示用户先创建。
工作流（严格按顺序）
Step 1 — 收集输入
- 接收图片路径（单张）或文件夹（批量）。确认路径存在、可读。
- 规划输出目录：
{cwd}/product-listing-output/，每个商品建子目录{safe_title}/，内含product.json与detail.html。
Step 2 — 视觉识别与结构化生成
- 用 Read 工具读取每张商品图（支持多图、批量逐张）。
- 依据
references/product_schema.md输出归一化product.json：标题、副标题、品牌、三级类目、标签、关键词、长短描述、卖点、使用方法、注意事项、SEO 三要素、SKU（规格/价格/库存/重量/条码）、属性表、媒体资源。 - 识别不确定的项，显式写入
meta.confidence，便于人工复核。 - SKU 编码按默认规则生成：
{品牌缩写}-{规格}-{YYMMDD}{序号}，可在配置或识别时覆盖。 - 把图片复制到对应商品子目录（主图
main.jpg、细节图detail_N.jpg），原始图只复制不删除。
Step 3 — 生成可视化商品详情页
- 参考
assets/detail_template.html的版式与样式生成detail.html： - 单图 / 少量：模型直接基于模板生成精修版 HTML（文案更灵活）；
- 批量：调用
scripts/generate_detail_html.py product.json程序化填充模板，保证一致性。 - 在回复中以文件卡片呈现，供用户预览核对。
Step 4 — 人工确认（关键闸门）
- 上架是对外动作，必须先与用户确认。 展示待推送摘要（标题 / SKU / 价格 / 目标适配器），询问是否执行。
- 默认先做 dry-run（Step 5），把实际请求体打印给用户核对，再正式推送。
Step 5 — 配置校验与推送
- 加载
adapter_config.yaml。 - 先校验：
scripts/push_to_erp.py --config adapter_config.yaml --input product.json --dry-run，预览请求体、确认字段映射无误。 - 用户确认后，去掉
--dry-run正式推送：对每个enabled适配器，按field_mapping+constants组装请求，处理鉴权并发送；解析response_id_path取得商品 ID，回写product.json的meta.listed_ids。 - 两步式接口（
two_step: true）先建 SPU 再建 SKU，按sku_endpoint中的{id}占位关联。
Step 6 — 结果汇报
- 逐商品 / 逐适配器汇报：成功（商品 ID）、失败（HTTP 状态码 + 响应摘要）。失败项不暴力重试，记录后交人工处理。
- 汇总输出目录位置与详情页预览。
资源
references/product_schema.md— 标准商品数据结构（生成与映射的契约）references/adapter_config.example.yaml— 上架适配器配置模板assets/detail_template.html— 商品详情页模板（单图精修 / 批量生成共用）scripts/push_to_erp.py— 通用 REST 推送（含 mini-YAML 解析、字段映射、两步式、dry-run，零三方依赖）scripts/generate_detail_html.py— 批量详情页程序化生成
注意事项
- 对外上架前必须人工确认，禁止静默自动推送。
- 绝不删除用户原始图片，只复制。
- 价格 / 库存等敏感字段以用户配置或明确确认为准，模型给出的价格仅为建议值。
- 配置中的密钥一律
${ENV}占位，禁止明文写入技能或打印到日志。 - 多平台铺货时，在
adapters下增配多个适配器即可，流程不变。
