妙手ERP-图片处理

概述

妙手 ERP 图片处理

通过妙手 ERP OpenAPI 处理远程商品图片 URL，返回原图到结果图的映射。

工作流

1. 根据下方操作路由表对请求进行分类。
2. 在使用具体端点、字段、枚举、响应结构或签名细节之前，先阅读 references/api.md。
3. 按以下优先级解析图片输入：
   1. 复用当前任务中采集箱商品信息 API 或采集箱编辑 skill 已返回的有效 HTTP(S) 图片 URL。
   2. 使用用户提供的直接图片 URL。
   3. 仅当以上两种来源都不存在时，通过可用的安全上传/托管能力将本地附件转换为临时公共 URL。如果没有可用的上传方式，说明一次妙手端点无法读取本地路径，并请求用户提供直接 URL；永远不要编造或暴露仅限本地的 URL。
4. 当已有可用的上游 URL 时，不要要求用户上传图片。保持上游图片顺序，对 URL 去重，并丢弃空白或非 HTTP(S) 值。当存在多个 URL 且请求范围不明确时，在预览中包含有序 URL 集合或图片数量，以便用户确认确切的处理范围。
5. 对于翻译操作，除非在同一任务中已获取当前响应，否则在提交前先获取实时的支持语言配置。
6. 任何处理操作在提交前均需预览。搜索和语言查询为只读操作，可立即执行。
7. 仅在用户确认确切预览后才提交处理操作。"把这些图翻译成英文"等直接请求仅授权准备预览，不授权消耗 API 配额。
8. 在确认处理时，当用户需要持久本地副本时传入 --output-dir。汇总原始 URL、状态、结果 URL、本地路径和失败原因。保留部分成功的结果。

操作路由

不要将商品图片包生成请求路由到此处。当用户需要新生成营销图片集而非对已有图片进行变换时，请使用 miaoshouerp-product-image-generator。

安全与数据规则

• 将 remove、white-bg、watermark 和 translate 视为消耗配额的处理操作。先不带 --confirm 运行，展示预览，然后在用户明确批准后使用相同命令加 --confirm 重新运行。
• 永远不要覆盖原图或声称原始 ERP 商品已被编辑。这些 API 返回的是派生图片 URL。
• 永远不要要求用户在聊天中粘贴 AppSecret、Cookie、访问令牌或授权头。从本地配置、环境变量或安全主机连接器中读取。
• 永远不要打印密钥、签名、Cookie、授权头或包含完整凭证的请求。
• 不要在生产环境中发送仅用于 Apifox 的 X-Apifox-Debug 头。将导出文档中的 timerToken 和示例 Cookie 视为调试上下文，而非正常签名 OpenAPI 契约。
• 对于水印输出，要求用户在保留源尺寸比例和固定 800x800 输出之间做出明确选择。
• 对于智能消除，要求至少一个消除目标和至少一个区域。强制执行 references/api.md 中记录的 trace 字段依赖关系。
• 一次提交失败后即停止。不要自动重试可能消耗配额的处理请求。
• 将上传视为单独的预处理步骤。不要将本地附件上传到未经批准的公共主机，也不要暗示妙手接受文件系统路径。
• 将从上游采集箱读取中获取的图片 URL 视为任务本地输入。无需要求用户重新粘贴或上传相同图片即可复用，但不要静默扩展处理范围到当前任务范围之外的不相关商品或 URL。
• 保留确切的预览参数以供确认。预览包含图片数量和是否消耗配额；将面向用户的确认限制在这些要点以及操作和场景/选项上。

认证

使用签名 JSON POST 请求。本地配置方式：

• MIAOSHOU_APP_KEY 和 MIAOSHOU_APP_SECRET；或
• resources/config.json，从 resources/config.json.example 复制到本地。

可选环境变量包括 MIAOSHOU_BASE_URL、MIAOSHOU_TIMEOUT、MIAOSHOU_ACCOUNT_ID、MIAOSHOU_AUTHORIZATION 和 MIAOSHOU_COOKIE。不要分发已填入凭证的 resources/config.json。

当配置未知时，运行一次本地诊断：

python scripts/miaoshou_image_processing.py check-config

仅在凭证变更或认证失败后重新检查。

脚本用法

使用 scripts/miaoshou_image_processing.py 作为唯一 CLI 入口。运行 python scripts/miaoshou_image_processing.py --help 查看完整参数列表。

预览智能消除：

python scripts/miaoshou_image_processing.py remove --image-url "https://example.com/a.jpg" --source common_collect_box --common-collect-box-detail-id 123 --remove-watermark --area background

确认后，在相同命令后追加 --confirm。

预览白底处理：

python scripts/miaoshou_image_processing.py white-bg --image-url "https://example.com/a.jpg" --image-scene 1

确认后，提交时同时保存派生图片到本地：

python scripts/miaoshou_image_processing.py white-bg --image-url "https://example.com/a.jpg" --image-scene 1 --output-dir "C:/path/to/results" --confirm

搜索水印模板：

python scripts/miaoshou_image_processing.py search-watermarks --subtype normal --name "品牌" --page-no 1 --page-size 20

预览水印应用（保留源尺寸比例）：

python scripts/miaoshou_image_processing.py watermark --image-url "https://example.com/a.jpg" --watermark-id "wm-123" --auto-match-image-size

查询语言支持：

python scripts/miaoshou_image_processing.py languages

预览图片翻译（保留品牌文字）：

python scripts/miaoshou_image_processing.py translate --image-url "https://example.com/a.jpg" --source-lang zh --target-lang en --platform aeAi --exclude-brand

结果处理

• 根成功为 result=success；根失败可能包含 code 和 reason。
• 不要仅凭 HTTP 200 推断批量成功。检查每个图片的 result 字段。
• 智能消除返回使用计数。报告计数但不要承诺剩余配额。
• 翻译将正常结果与分组错误结果分开。展示时将失败项展开为每 URL 一行。
• 如果响应中缺少结果 URL，报告为不可用，而不是猜测。
• 当存在 --output-dir 时，读取 localArtifacts[]。下载失败不改变成功的 API 处理结果；分别报告远程 URL 和本地下载失败。

失败处理

• signMissing：签名头缺失。
• signExpired：检查时钟偏移和秒级时间戳。
• signInvalid：验证精确的紧凑 JSON body、路径、AppKey 和 AppSecret。
• appNotFound：AppKey 错误、已禁用或未审批。
• appNoPermission：应用缺少该端点的权限。
• ipNotInWhitelist：将调用方 IP 添加到妙手账户白名单。
• 不支持的语言对：从实时配置中展示可用的平台/源语言/目标语言组合，不提交翻译。
• 批量部分失败：保留成功的结果 URL，报告失败的 URL 及 API 原因。