photo-editor

MPSTATS Photo Editor

用于为电商平台商品卡片生成 AI 视觉内容的 MPSTATS 内部服务：移除／替换背景、放大、改色、「产品使用场景」、提示词编辑、产品拍摄、信息图。

所有请求都通过 scripts/ 中现成的脚本发起（Bash 工具，不要重写代码）。端点采用异步方式：每个脚本都会处理提交 → 轮询 → 保存文件。脚本会对图像进行 Base64 编码。

两种运行模式

请谨慎选择——这会影响后续所有行为。

A. 技术操作（单步）——remove-background、upscale、replace-background、in-action、recolor、freeform。运行脚本 → 获取结果 → 交付。无需调研／简报。适用于用户提出具体操作请求时（例如「移除背景」「放大」「改成蓝色」）。

B. 设计任务（多阶段）——infographics 和 photoshoot。完整设计工作：以电商平台设计师的角度思考。适用于与买家价值相关的请求（例如「制作信息图」「优化商品卡片」「我需要一组产品照片」）。使用 references/ 中的阶段指南——这些是思考指南，不是检查清单：

阶段	文件	适用时机
1. 调研	references/01-research.md	模式 B 的默认步骤，除非用户选择「不调研」。
2. 简报	references/02-brief.md	模式 B 中生成前必做。还涵盖所有提示词设计：提示词结构、幻灯片系列、长度限制、内容过滤器。
3. 生成	references/03-generate.md	必做。运行前，询问：「立即生成完整批次，还是先生成测试帧？」
4. 交付	references/04-deliver.md	必做，展示结果前阅读。 通过 Read 展示每一帧，并配上锚点说明，而不是列出路径。

模式 B 启动——必须先提问

确定任务属于模式 B 后，第一步必须提出一个问题：

要进行完整调研（竞品分析、评论、视觉基准），还是直接根据你的提示词／描述生成？

可能的回答及对应操作：

用户回答	操作
「进行调研」／「完整分析」／未明确拒绝（保持沉默）	完整执行阶段 1 → 2 → 3 → 4
「不调研」／「直接生成」／「根据我的提示词」	跳过阶段 1，直接进入阶段 2（根据用户描述撰写简报）→ 3 → 4。明确说明：「跳过调研——质量可能较低，但速度更快。」
用户在消息中提供了现成提示词	澄清：是原样使用，还是先按简报流程处理（检查长度、区块结构、产品锁定）？

**例外：**如果用户在第一条消息中已明确表示「不分析」／「不调研」，则不要提问，直接进入阶段 2。

配置

凭据位于 config/.env（已加入 gitignore）：PHOTO_EDITOR_TOKEN（请求头 X-Mpstats-TOKEN）以及可选的 PHOTO_EDITOR_BASE_URL（默认值为 https://mpstats.io/api/big_data/proxy）。设置方法和变量说明：config/README.md。

如果缺少令牌（或其值为 your_token_here），Agent 必须询问：

I need an MPSTATS API token (X-Mpstats-TOKEN) for Photo Editor — get it from your MPSTATS account → API and send it over, I'll write it into config/.env.

输出位置

不要将结果放在技能文件夹中——技能是代码，输出是数据。默认路径为 ~/.claude/output/photo-editor/<event_id>/，也可通过 PHOTO_EDITOR_OUTPUT_DIR 覆盖。

对于模式 B，生成后将文件复制到一个整洁的 SKU 专属文件夹中，并使用有意义的名称（如 slide_1_hero.png）——event_id 中包含 :，某些 UI 客户端无法正确渲染这类文件名；按 SKU 分类也更方便用户浏览。

多角度输入：wb:<sku>

在 infographics.sh 和 photoshoot.sh 中，第一个参数可以是 wb:<sku> 或 wb:<wb-url>，而不是文件路径。该技能会从 WB CDN 下载所有产品照片（wb-fetch-photos.sh，缓存于 ~/.claude/cache/photo-editor/wb-photos/<sku>/）：第一张 → main_image，其余 → reference_images（最多 5 张，API 不接受更多）。

infographics.sh generate wb:164419278 "$PROMPT" 5

对于多角度输入，在产品锁定指令中写“保留产品的身份”，而不是“保持相同的方向”——否则模型会将第一张照片的角度复制到每张幻灯片上。关于提示词的更多信息 — references/02-brief.md。

信息图：一组包含 N 张幻灯片的系列

infographics.sh generate <img> "<prompt>" <count> 会在单次调用中创建一组包含 count 张幻灯片的系列（1..6）。流程：test（试验帧）→ 批准 → generate <N>；或者使用 auto（一次完成 test + generate）。

最少输出 4 帧。 该端点始终返回 max(4, image_count) 张图片——即使请求的 count=1..3，也仍会得到 4 张。Photoshoot 没有此限制。

提示词用于设定整体方向和每帧的主题，而不是每张幻灯片的布局——否则你会在单个画布上得到 2×3 拼贴图。提示词编写详情 — references/02-brief.md。

模型

掩码	层级	默认	宽高比	适用于
model_1	标准	✅ 除信息图外均为默认	1:1, 3:4, 4:3, 2:3, 3:2	所有端点
model_2	PRO	✅ 信息图默认	1:1, 3:4, 4:3, 2:3, 3:2	所有端点
model_3	PRO	—	1:1, 3:4, 4:3, 2:3, 3:2	所有端点
model_4	PRO	—	1:1, 3:4, 4:3, 2:3, 3:2	所有端点
model_5	PRO	—	1:1, 3:4, 4:3	freeform, photoshoot

后端不接受 model=auto——该技能会将其解析为 model_1（标准）。信息图的默认模型固定为 model_2（PRO）——西里尔字母质量最佳。只有在你有明确理由时才指定模型。

脚本

脚本	使用场景
remove-background.sh <img>	移除背景
upscale.sh <img>	提高分辨率
replace-background.sh <img> <template_key>	将产品置于图库背景上
in-action.sh <img> <template_key>	将产品置于现成的使用场景中
recolor.sh <img> <#hex>	为产品重新着色
freeform.sh <img> "<prompt>" [model] [ar] [refs]	自由编辑（单步）
photoshoot.sh auto <img> "<prompt>" <count>	产品摄影（通过一条命令完成 test → generate）
photoshoot.sh test | generate	需要单独审核试验帧时使用
infographics.sh auto <img> "<prompt>" <count>	信息图（test → generate）
infographics.sh test | generate	与产品摄影相同
templates.sh backgrounds [key]	列出 replace-background 使用的 template_key
templates.sh in-action [key]	列出 in-action 使用的 template_key
wb-fetch-photos.sh <sku-or-url> [max=8]	下载 WB 产品照片。输入 wb:<sku> 时会自动调用
health.sh	检查服务状态
run.sh <endpoint> <body_json>	通用提交 + 轮询
poll.sh <event_id>	等待 event_id 就绪

决策指南

• “清理背景” → A，remove-background.sh
• “放大 / 提高清晰度” → A，upscale.sh
• “将背景换成影棚 / 大理石背景” → A，templates.sh backgrounds → replace-background.sh
• “展示产品的使用场景” → A，templates.sh in-action → in-action.sh
• “重新着色为 #hex” → A，recolor.sh
• “调整光线 / 去除眩光 / 添加阴影” → A，freeform.sh
• “制作信息图 / 产品摄影”、“更新产品卡片 X” → B，从 references/01-research.md 开始

错误

消息	处理方法
process_completed	已完成，文件已保存
process_completed + output.image: []	内容过滤器拦截 → 重新措辞提示词（references/02-brief.md）
process_error	读取 error.message，并显示给用户
process_timeout	服务未能及时完成；减少数量或更换模型
Prompt size exceeds maximum allowed length	最常见的原因是提示词中的换行符（\n），而非实际超出长度限制。将提示词作为单行传递。如果此后错误仍然存在，请缩短提示词：references/02-brief.md → Technical limits。
AUTH_ERROR	凭据无效 — 请参阅 Config 部分
本地轮询超时	脚本已停止轮询；event_id 仍然有效 — poll.sh <event_id>