adobe-batch-edit-photos

Adobe 批量编辑照片

专注于视觉统一性的批量编辑流程——让一组照片看起来像是经过统一编辑。用户选择一种风格（或描述一种风格），然后 Agent 使用 Adobe 创意工具在每张图片上一致地应用该风格。

核心理念：追求“统一性”的用户，不太在意每张图片是否完美，更在意整组照片看起来是否经过精心处理。应优先保证色调和色彩的一致性，而不是把某张图片单独修到极致。

界面说明： 默认流程使用 Adobe 的 MCP App 小组件（第 1 步中的 asset_add_file 选择器，以及第 2c 步和第 8 步中的 asset_preview_file 预览）。请按说明使用。只有在此界面无法使用小组件工具时（例如 Codex），才使用该步骤附带的无小组件备用方案。如果没有问题小组件，请将 AskUserQuestion 提示以带标签选项的纯文本形式呈现。

此处不进行交互式图像编辑。 本说明覆盖 adobe_mandatory_init 的交互式图像小组件部分中提供的单图小组件：此技能是批量处理流程，因此无论图像数量多少，都绝不要调用或提及交互式编辑小组件（任何 _app 工具）——按以下说明照常运行流程。

---

工具参考

步骤	工具	备注
导入	asset_add_file（+ read_widget_context）	交互式文件选择器；通过 read_widget_context 解析选择器结果
导入*（无小组件备用方案）*	asset_initialize_file_upload + asset_finalize_file_upload	仅当 asset_add_file 不可用时使用——以编程方式将本地文件暂存到 CC
查找预设	image_list_presets	启动时调用一次；构建风格→预设映射
拉直	image_auto_straighten	每张图片
自动色调	image_apply_auto_tone	每张图片，type: "cameraRawFilter"
风格调整	image_apply_adjustments	批量处理——一次调用完成色温、自然饱和度/饱和度和亮度/对比度调整
微调	image_apply_adjustments	批量处理——一次调用完成所有选定的微调
风格预设	image_apply_preset	每张图片，核心风格载体
元素检测	使用完整的 bodyParts 数组调用 image_select_subject	每张图片，第 5e 步可选；也用于裁剪焦点
背景模糊	image_apply_effects（effect: "gaussianBlur"）	每张图片，仅在明确要求时使用；回退至 image_apply_gaussian_blur
裁剪	image_crop_and_resize	每张图片，可选
示例预览	asset_preview_file	仅预览 image[0] 的前后效果*（无小组件备用方案：直接提供这 2 个 URL）*
最终预览	asset_preview_file	批量资源数组*（无小组件备用方案：直接提供 URL）*
Firefly Board	create_firefly_board	所有编辑后的输出

---

步骤 0 - 前置条件：初始化 Adobe 工具

首先调用 adobe_mandatory_init。这会返回后续工作流所需的文件处理规则和工具路由指南。

{ "skill_name": "adobe-batch-edit-photos", "skill_version": "4.1.0" }

---

步骤 0b：发现可用预设

初始化后立即调用 image_list_presets，并在导入图像或回答用户问题之前执行。这样你就能获取该用户套餐中可用的全部预设，从而在步骤 5b 中为每种风格选择最合适的预设，而不是依赖硬编码的名称。

Tool: image_list_presets
Params: {}

根据返回的列表，将每个预设归入最适合的风格类别，建立风格→预设映射。可参考以下命名信号：

风格	匹配的命名信号
自动（均衡）	Auto、Balanced、Natural、Neutral、Default、Adobe Color、Standard
暖调与金色	Warm、Golden、Glow、Sunset、Cozy、Amber、Warm Pop
明亮通透	Airy、Bright、Light、Clean、Pop、Lift、Fresh
暗调与电影感	Moody、Cinematic、Dark、Drama、Dramatic、Shadow、Deep
冷调清新	Cool、Blue、Clear、Crisp、Sky、Azure
鲜艳浓郁	Vibrant、Punchy、Bold、Vivid、Pop、Saturate
低饱和与胶片感	Film、Muted、Fade、Faded、Analog、Grain、Vintage、Matte

规则：

• 每个预设最多分配给一种风格。如果一个名称匹配多种风格（例如 Pop 可能属于明亮通透或鲜艳浓郁），则分配给整体特征最接近的风格——柔和暖调的 Pop 归入暖调与金色，浓郁高对比度的 Pop 归入鲜艳浓郁。
• 优先选择以 Adaptive: 为前缀的预设来驱动风格，因为它们会根据图像内容进行调整。
• 每种风格最多选择 2 个预设——一个主要预设（匹配度高）和一个可选的次要预设（用于补充）。先应用主要预设；只有在次要预设能带来不同效果时才应用它（例如，增加主要预设未涵盖的色彩分级）。
• 如果没有预设匹配某种风格，则仅使用色温和手动调整，不应用预设。
• 如果 image_list_presets 返回空结果或 403：对所有图像跳过步骤 5b；在摘要中注明“此套餐无法使用预设”。风格处理流程的其余部分（色温、手动调整）仍照常执行。

在步骤 2 之前保存完整的风格→预设映射。你会在步骤 5b 中引用它。

选择性自适应预设分类（用于步骤 5e）

从同一预设列表中，还要建立一份单独的选择性自适应映射，仅在用户选择启用选择性增强时使用（步骤 5e）。这些预设针对检测到的特定场景元素，而非整张图像：

分类	命名信号	应用条件
主体 / 人物	Subject、Person、Pop、Warm Pop、Portrait、Skin、Body	检测到 Face、Torso 或 Skin 时
天空	Sky、Blue Drama、Dark Drama、Cloud、Horizon、Outdoor	检测到 Sky 时
背景	Background、BG、Blur Background、Bokeh、Depth、Defocus	检测到 Background 时
身体部位 / 衣物	Clothing、Outfit、Clothes、Hair、Torso、Body Part	检测到 Clothing 或 Hair 时

• 每个分类最多选择 1 个预设。
• 如果没有预设匹配某个分类，则留空，不要勉强选用不合适的预设。
• 这些分类与风格→预设映射相互独立；如果某个预设确实适合，它可以同时出现在两者中。

---

步骤 1：图像导入

不带参数调用 asset_add_file，打开文件选择器：

Tool: asset_add_file
Params: {}

asset_add_file 始终返回 imageURIs: []——这是预期行为，并非错误。等待用户选择文件；实际 URI 会在下一条消息中传来。然后使用 asset_add_file 调用 read_widget_context，获取正确的预签名 S3 URL。后续所有工具调用都使用这些 URL。 dcx-stage.adobe.io URI 会被网络屏蔽；请先通过 read_widget_context 解析它们。

将返回的预签名 URL 收集为 sourceURIs[]，然后继续步骤 2。

无组件回退方案 （仅当此界面无法使用 asset_add_file 时，例如 Codex）——不要打开文件选择器；从文件所在位置获取源 URI。image_* 工具只接受 Creative Cloud 存储 URI，绝不接受原始本地路径，因此任何本地文件都必须先暂存到 CC。

**先检查出口状态：**检查第 0 步中 adobe_mandatory_init 返回的出口状态。如果出口已禁用——请勿调用 asset_initialize_file_upload / asset_finalize_file_upload。

来源	操作
文件位于本地路径且出口已启用	以编程方式逐个暂存文件：获取文件大小和 MIME 类型，调用 asset_initialize_file_upload({ path: "<filename>", media_type: "<mime>" })，将文件字节 PUT 到返回的上传 URL，然后调用 asset_finalize_file_upload({ filename: "<filename>", transfer_document: <from the initialize response> })。将每个返回的预签名 CC URL 用作源 URI。
文件已位于 Creative Cloud	直接通过其 CC URI 引用。
文件位于本地路径且出口已禁用，此界面没有文件选择器	无法以编程方式暂存文件，且此处没有文件选择器——请告知用户此界面无法暂存文件，并让他们在提供 asset_add_file 文件选择器的环境中运行工作流。

---

步骤 2：了解期望的效果

获取 URI 后，先浏览对话，尽可能推断用户的偏好，再询问任何问题：

• 效果：可从“温暖”“金色”“电影感”“忧郁”“明亮通透”“低饱和”“胶片感”“冷调”“鲜艳”“强烈”等词推断
• 微调：可从“找回高光细节”“提亮阴影”“增加对比度”“过曝”“太暗”“更鲜艳”“降低饱和度”等词推断
• 裁剪：可从“不裁剪”“方形”“1:1”“纵向裁剪”“保持构图”等词推断
• 选择性 AI 增强：可从“自适应预设”“选择性增强”“应用于检测到的元素”“天空预设”“突出主体”或任何要求按元素处理的表述推断。若推断为是，则视为 Q5 = Yes——将执行步骤 5e。若推断为否或未提及，则视为 Q5 = No——完全跳过步骤 5e。

三种情况：

**A — 上下文已明确所有偏好：**完全跳过 AskUserQuestion。发送确认消息，然后直接进入步骤 2c（示例预览）。不要开始完整批处理——无论用户的偏好说明得多么清楚，都必须先预览并等待确认。

**B — 部分偏好明确，部分不明确：**先确认已推断的偏好，然后调用 AskUserQuestion，只询问尚未明确的问题。 例如，如果效果和一项微调已明确，但裁剪方式不明确，则发送：

📷 Got [N] photo(s)! Based on what you said, I'll go with:
- Look: Moody & Cinematic
- Tweaks: Recover blown highlights

Just one thing — do you want a crop?

然后只针对问题 3 调用 AskUserQuestion。

**C — 未指定任何偏好：**发送完整的开场说明，并展示全部 5 个问题：

📷 Got [N] photo(s)! I'll apply consistent edits across all of them so
the set looks cohesive.

What kind of look are you going for? 👇

完整的 AskUserQuestion 问题（仅使用仍待确认的问题）：

Question 1 (single_select):
  question: "🎨 Pick a base look"
  options:
    - "Auto (balanced, neutral)"
    - "Warm & Golden — cozy, travel, golden hour"
    - "Bright & Airy — clean, light, lifestyle"
    - "Moody & Cinematic — dramatic, contrasty, desaturated"
    - "Cool & Fresh — clear skies, travel, blue tones"
    - "Vibrant & Punchy — vivid, bold, social-ready"
    - "Muted & Film — faded, analog, editorial"

Question 2 (multi_select):
  question: "🎛️ Fine-tune (optional)"
  options:
    - "Recover blown highlights"
    - "Lift dark shadows"
    - "Boost contrast"
    - "Boost color intensity"
    - "Desaturate / muted tones"
    - "Adjust exposure (brighter/darker)"
    - "Tune bright areas"
    - "Blur background (heavy)"
    - "None"

Question 3 (single_select):
  question: "✂️ Crop ratio? (optional)"
  options:
    - "No crop — keep original framing"
    - "1:1 square"
    - "4:5 portrait"
    - "16:9 wide"
    - "4:3 standard"

Question 4 (single_select):  [only ask if Q3 is not "No crop"]
  question: "🎯 How should the crop be framed?"
  options:
    - "Center — crop from center of image"
    - "Smart crop — detect subject/face and frame around it"

Question 5 (single_select):
  question: "✨ Selective AI enhancements? Detects sky, subjects, background & body parts — applies adaptive presets only to elements found in each photo"
  options:
    - "Yes — apply adaptive presets to detected elements"
    - "No — skip selective enhancements"

等待用户回复后再继续。

**如果用户选择启用选择性增强（Q5 = Yes）：**应用效果后，对每张图片执行步骤 5e。如果用户拒绝或未询问是否启用，则完全跳过步骤 5e。

**关于问题 4 的说明：**如果用户的消息已经表明其构图偏好 （例如“居中裁剪”“裁到我的脸部”“围绕主体取景”），则跳过 Q4 并直接推断。如果用户指定了比例但未指定构图方式，则默认使用智能裁剪——它几乎总是比纯居中裁切效果更好。

效果 → 参数映射

基础效果 → image_apply_adjustments（色温 + 鲜艳度/饱和度 + 亮度/对比度，步骤 5a）+ image_apply_preset（来自 Look→Preset Map，步骤 5b）：

将所选效果的所有列合并到同一次 image_apply_adjustments 调用中——不要分别调用色温、鲜艳度和对比度。若某个参数对应列标为“none”，则省略该参数。

下方的预设列现已动态化——使用步骤 0b 中为该效果构建的 Look→Preset Map 所列预设，而非硬编码的名称。如果未找到适用于某种效果的预设，则跳过该效果的步骤 5b，仅使用色温和手动调整。

⚠ **绝不使用已弃用的工具。*所有调整都通过 image_apply_adjustments 完成。各维度独立的 adjust- 工具已弃用——请参见下方的硬性约束。

风格	色温 (tempA、tempB、tempLuminance)	预设（来自 Look→Preset Map）	饱和度/鲜艳度	亮度/对比度
自动（均衡）	无 — 省略 tempA/tempB/tempLuminance	自动（均衡）分类预设	无	无
暖调与金色	tempA=32, tempB=120, tempLuminance=67	暖调与金色分类预设	鲜艳度 +15	无
明亮通透	tempA=20, tempB=60, tempLuminance=62	明亮通透分类预设	饱和度 -10，鲜艳度 +10	亮度 +15
忧郁电影感	tempA=20, tempB=-50（负值 — 冷色偏移），tempLuminance=45	忧郁电影感分类	饱和度 -20	对比度 +25
清冷清新	tempA=18, tempB=-123, tempLuminance=45	清冷清新分类预设	鲜艳度 +10	无
鲜艳浓烈	无 — 省略 tempA/tempB/tempLuminance	鲜艳浓烈分类	鲜艳度 +30，饱和度 +15	对比度 +10
柔和胶片感	无 — 省略 tempA/tempB/tempLuminance	柔和胶片感分类预设	饱和度 -35，鲜艳度 -10	对比度 +10

对于色温列为“无”的风格（自动、鲜艳浓烈、柔和胶片感）：调用 image_apply_adjustments 时不要包含 tempA、tempB 或 tempLuminance。为没有色温的风格添加色温参数会导致结果不正确。

微调 → image_apply_adjustments 参数（在步骤 6 中合并为一次调用）：

• “恢复过曝高光” → highlights: -60
• “提亮暗部阴影” → darks: +40（正值 = 提亮/增亮暗部区域）
• “增强对比度” → 在步骤 6 的调用中使用 contrast: +30。步骤 5a 已将风格的对比度应用到像素上 — 步骤 6 是对步骤 5 输出进行的单独调用，因此只传入微调增量（contrast: +30）；不要将其与风格的对比度值相加
• “增强色彩强度” → vibrance: 30
• “降低饱和度 / 柔和色调” → saturation: -30
• “调整曝光（变亮/变暗）” → exposure: +0.5（变亮）或 exposure: -0.5（变暗）；根据上下文推断方向，若未指定，默认为 +0.3
• “调整亮部” → lights: +20
• “模糊背景（强）” → image_apply_effects → effect: "gaussianBlur", blurRadius: 12, blurTarget: "background"（单独调用 — 不属于 image_apply_adjustments；若不可用，则回退使用 image_apply_gaussian_blur）
• “无” → 完全跳过微调步骤

裁剪：

• “不裁剪” → 完全跳过步骤 7
• 比例 + “居中” → 使用 image_crop_and_resize，设置 fit: "reframe"、该比例作为 output，以及 align: { x: 0.5, y: 0.5 }（纯居中裁切）
• 比例 + “智能裁剪” → 使用 image_crop_and_resize，设置 fit: "reframe"、该比例作为 output；若可能是人像/人物照片，则设置 focus: "face"，否则设置 focus: "subject"（按所选比例围绕检测到的主体进行智能重构）

收到选择后，向用户确认设置：

✅ Got it — running with:
- Look: [selected look]
- Selective AI enhancements: [yes — will apply adaptive presets per detected element / no]
- Tweaks: [list if any, including "Blur background" if selected in Q2, or "none"]
- Crop: [ratio or "no crop"] + [Center / Smart crop]

然后立即进入步骤 2c（样例预览）— 暂不开始完整批处理。

---

步骤 2b：大批量警告（N > 5）

当 N > 5 时，将此内容作为步骤 2c 确认提示的一部分（在前后对比预览之后）：

⏱ Estimated time for [N] images:
  6–10 → ~3–5 min
  11–20 → ~5–10 min
  20+ → 10+ min

Feel free to step away — I'll post a ✅ summary with download links when done.

步骤 2c：预览示例（图像 1 的处理前／后对比）

运行完整批处理前，先使用已确认的设置，仅对第一张图像运行完整流程（步骤 3–7，包括所选的步骤 5e）。这样用户就能看到实际预览，确切了解每张图像将应用的处理效果。

为缩短预览时间，先将图像 1 缩小，使其长边为 1200px，再运行完整流程。最终批处理时仅使用原始全分辨率源图像。

Tool: image_crop_and_resize
Params:
  imageURI: "<sourceURIs[0]>"
  options:
    output: { width: 1200, height: 1200 }   # caps both dimensions at 1200px; fit:contain preserves aspect ratio, so the long edge (width on landscape, height on portrait) is capped at 1200px
    fit: "contain"
  outputFileType: "jpeg"

将结果存储为 preview_source_url。仅在预览处理中，将 preview_source_url（而非 sourceURIs[0]）用作步骤 3–7（包括所选的步骤 5e）的输入。

1. 仅对 preview_source_url 运行完整流程（拉直 → 色调 → 外观 → 局部增强 → 微调 → 模糊 → 裁剪）。
2. 调用 asset_preview_file，以原始全分辨率源图像作为「处理前」，以处理后的缩小图像作为「处理后」——asset_preview_file 会自行生成缩略图，因此用户看不出尺寸差异：

asset_preview_file({
  assets: [
    { name: "Before", presignedAssetUrl: sourceURIs[0] },
    { name: "After",  presignedAssetUrl: processed_preview_url }
  ]
})

无组件回退方案 （仅当此界面无法使用 asset_preview_file 时，例如 Codex） — 在消息中直接展示两个 URL，并标注为：

处理前：<sourceURIs[0]>
处理后：<processed_preview_url>

能在行内渲染图像 URL 的 UI 客户端会自动显示两张图像。在 Codex 或其他非 UI Agent 中，使用原生文件下载工具将两个素材下载到工作区，分别将 <sourceURIs[0]> 保存为 before.jpg，将 <processed_preview_url> 保存为 after.jpg，然后引用这些本地路径。

3. 发布此消息（如果 N > 5，在此处附上大批量处理的耗时说明）：

👆 Here's a before/after preview using your first photo and the settings you selected.

Please confirm before I apply this to all [N] images.

4. 使用一个问题调用 AskUserQuestion：

Question (single_select):
  question: "Does the preview look good?"
  options:
    - "✅ Yes — apply to all [N] images"
    - "🎛️ No — adjust settings first"
    - "❌ Cancel"

此处必须完全暂停处理。 在用户明确选择「Yes」之前，不得开始完整批处理。此确认关卡为必需项——每次都必须执行，即使用户已提前说明所有偏好也不例外。

如果选择「Yes」： 对所有图像（sourceURIs[0…N-1]）以全分辨率开始完整批处理（步骤 3–7，包括所选的步骤 5e）。不得重复使用 1200px 预览结果——该结果仅用于确认，不能出现在最终交付内容中。

如果选择「No — adjust settings」： 重新显示步骤 2 中的完整 AskUserQuestion 问题集。确认新设置后，必须始终重复预览——使用新设置再次处理 image[0]，展示新的处理前／后对比，并在继续之前再次取得明确确认。调整设置后，绝不可跳过预览确认关卡。

如果选择「Cancel」： 确认并停止。不要处理任何图像。

---

步骤 3：自动拉直（逐张图像处理）

Tool: image_auto_straighten
Params:
  imageURIs: ["<source_uri_N>"]
  options:
    uprightMode: "auto"
    constrainCrop: true

输出：results[0].outputUrl → straightened_urls[]

失败时：使用原始 URI，并为该图像注明「已跳过拉直」。

---

步骤 4：自动调整色调（逐张图像处理）

Tool: image_apply_auto_tone
Params:
  imageURI: "<straightened_url_N>"
  options:
    type: "cameraRawFilter"
  outputFileType: "jpeg"

对 image_apply_auto_tone 使用 type: "cameraRawFilter"。输出：results[0].outputUrl → toned_urls[]

---

步骤 5：应用风格

按以下顺序应用风格，并串联输出：

5a：风格调整 — 将色温、鲜艳度／饱和度和亮度／对比度合并为每批一次 image_apply_adjustments 调用。仅包含所选风格所需的参数（参见映射表）：

Tool: image_apply_adjustments
Params:
  imageURIs: ["<toned_url_1>", "<toned_url_2>", ...]
  options:
    # Color temperature (if look requires it — all three required together):
    tempA: <value>          # e.g. 32 for Warm & Golden
    tempB: <value>          # e.g. 120 for Warm & Golden
    tempLuminance: <value>  # e.g. 67 for Warm & Golden
    # Vibrance / saturation (if look requires it):
    vibrance: <value>
    saturation: <value>
    # Brightness / contrast (if look requires it):
    brightness: <value>
    contrast: <value>
  outputFileType: "jpeg"

输出：results[N].outputUrl → look_adjusted_urls[]

目标是保持一致性：对每张图像应用相同的参数值——整体协调胜过单张图像的完美效果。

5b：风格预设（如果 Look→Preset Map 中有与所选风格匹配的预设）

先应用主要预设，再应用次要预设（如果有），并串联输出。使用步骤 0b 中构建的 Look→Preset Map 里的准确预设名称——此处切勿硬编码名称。

Tool: image_apply_preset
Params:
  imageURI: "<look_adjusted_url_N>"   # or previous preset output if chaining
  options:
    presetName: "<preset from Look→Preset Map>"

image_apply_preset 因权限问题返回 403 时： 跳过所有图像的预设。在交付摘要中注明：「[Preset name] 已跳过——你的 Adobe 计划不包含此预设。」继续步骤 5e（如果选择了选择性增强）或步骤 6（微调调整）——不要重新应用步骤 5a 中的风格调整，因为这些调整已在此步骤之前执行。

---

步骤 5e：选择性自适应增强（逐张图像，仅在选择启用时）

如果用户对问题 5 回答「否」，或 Selective Adaptive Map 中没有已填充的类别，则完全跳过此步骤。

对每张图像，检测其中有哪些场景元素，然后仅应用实际检测到的元素对应的自适应预设。结果因图像而异——根据画面内容，部分图像可能应用天空预设，其他图像则不会。这是预期且正确的行为。

5e-1：检测场景元素

Tool: image_select_subject
Params:
  imageURI: "<last_look_chain_url_N>"   # last output for this image: Step 5b preset output if presets ran; otherwise Step 5a look_adjusted_url
  options:
    bodyParts: ["Face", "Torso", "Clothing", "Skin", "Hair", "Sky", "Background"]

将检测结果映射到 Selective Adaptive 类别：

• 检测到面部／躯干／皮肤 → 应用主体／人物类别预设
• 检测到衣物／头发 → 应用身体部位／衣物类别预设
• 检测到天空 → 应用天空类别预设
• 检测到背景 → 应用背景类别预设
• 未检测到任何元素 → 跳过此图像的所有选择性预设；使用最后一个风格链输出（如果已运行预设，则使用步骤 5b 预设输出，否则使用步骤 5a 的 look_adjusted_url）作为步骤 6 的输入

5e-2：应用已检测元素的预设（串联）

仅应用上方条件已满足的类别对应的预设，并按以下顺序执行：主体 → 身体部位 → 天空 → 背景。将每个输出串联到下一个预设。

Tool: image_apply_preset
Params:
  imageURI: "<previous_output_url>"
  options:
    presetName: "<preset from Selective Adaptive Map>"

输出： 收集为 selective_urls[]，并传入步骤 6。

遇到 403 时： 跳过该预设，并注明「[preset name] 已跳过——你的计划不包含此预设。」继续应用其余选择性预设。 检测失败时： 跳过此图像的所有选择性预设；将风格输出用作步骤 6 的输入。

---

步骤 6：微调调整（批量，若已选择）

将所有选定的微调调整合并为一次 image_apply_adjustments 调用，应用于步骤 5 的输出。步骤 5a 的风格调整已应用到像素中——此处仅传入微调的增量值。一次性传入所有 URL：

Tool: image_apply_adjustments
Params:
  imageURIs: ["<step5_output_url_1>", "<step5_output_url_2>", ...]
  # Use selective_urls[] if Step 5e ran; otherwise the last preset output from Step 5b; otherwise look_adjusted_urls[] from Step 5a.
  options:
    # include only params for tweaks the user selected:
    highlights: -60       # "Recover blown highlights"
    darks: +40            # "Lift dark shadows" (positive lifts dark areas)
    contrast: +30         # "Boost contrast" fine-tune delta only (look contrast already applied by Step 5a)
    vibrance: 30          # "Boost color intensity"
    saturation: -30       # "Desaturate / muted tones"
    exposure: +0.5        # "Adjust exposure" (brighter) or -0.5 (darker)
    lights: +20           # "Tune bright areas"
  outputFileType: "jpeg"

省略用户未选择的参数。一次调用即可同时处理所有调整。

背景模糊（若已选择，逐张图像应用）：

Tool: image_apply_effects
Params:
  imageURIs: ["<url_N>"]
  options:
    effect: "gaussianBlur"
    blurRadius: 12
    blurTarget: "background"

如果此界面不支持 image_apply_effects（未注册该工具，或调用因未知工具错误而失败），则使用传统的逐效果工具 image_apply_gaussian_blur 重试一次——参数相同，但不包含 effect 判别参数：

Tool: image_apply_gaussian_blur
Params:
  imageURIs: ["<url_N>"]
  options:
    blurRadius: 12
    blurTarget: "background"

---

第 7 步：裁剪（按需逐张处理）

如果选择了“No crop”，则完全跳过此步骤。

两种裁剪模式都使用所选比例下的 fit: "reframe"，区别在于画框在图像中的位置。

居中裁剪 — 从几何中心裁剪至目标比例：

Tool: image_crop_and_resize
Params:
  imageURI: "<adjusted_url_N>"   # Step 6 output if fine-tunes ran; otherwise last Step 5 chain output (selective_urls[N] if Step 5e ran, last preset output from Step 5b if presets ran, otherwise look_adjusted_urls[N] from Step 5a)
  options:
    output: "<ratio>"        # "1:1", "4:5", "16:9", "4:3"
    fit: "reframe"
    align: { x: 0.5, y: 0.5 } # geometric center
  outputFileType: "jpeg"

智能裁剪 — 比例相同，但将画框定位在检测到的主体或人脸周围，而非几何中心。即使主体在原图中不居中，也会保留在画框内：

Tool: image_crop_and_resize
Params:
  imageURI: "<adjusted_url_N>"   # Step 6 output if fine-tunes ran; otherwise last Step 5 chain output (selective_urls[N] if Step 5e ran, last preset output from Step 5b if presets ran, otherwise look_adjusted_urls[N] from Step 5a)
  options:
    output: "<ratio>"   # "1:1", "4:5", "16:9", "4:3"
    fit: "reframe"
    focus: "face"       # or "subject" for non-portrait scenes
  outputFileType: "jpeg"

将结果收集到 final_urls[]。如果不裁剪：如果运行了微调，final_urls[] = 第 6 步的输出；否则为第 5 步最后一个链式操作的输出（如果运行了第 5e 步，则为 selective_urls[]；如果运行了预设，则为第 5b 步最后一个预设的输出；否则为第 5a 步的 look_adjusted_urls[]）。

---

第 8 步：预览

将最终输出 URL 直接传给 asset_preview_file — 不要先通过 image_crop_and_resize 处理。添加调整大小步骤会产生白边（来自 fit: "pad"），或裁掉主体（来自 fit: "reframe"）。asset_preview_file 会正确处理缩略图。

asset_preview_file({
  assets: [
    { name: "photo_1.jpg", presignedAssetUrl: final_url_1 },
    // ... one per image
  ]
})

如果 asset_preview_file 失败，请在完成摘要中将最终输出 URL 作为纯文本链接列出。

无组件回退方案 （仅当此界面不支持 asset_preview_file 时使用，例如 Codex） — 在完成消息中直接列出最终输出 URL（每张图一个；参见下方第 8 步模板）。可在界面中内嵌显示图像 URL 的客户端会自动显示。在 Codex 或其他非界面 Agent 中，使用原生文件下载工具将每张图下载到工作区（将 <final_url_1> 保存为 photo_1.jpg 等），并改为引用这些本地路径。无论使用哪种客户端，逐张照片的下载链接都是交付内容。

处理前/后的预览（第 2c 步）： 第 2c 步会先将图像 1 缩小至 1200px，再对缩小后的图像运行处理流程。将原始全分辨率 sourceURIs[0] 作为“处理前”图像，将处理后的 1200px 输出作为“处理后”图像 — asset_preview_file 会自行处理缩略图，因此用户看不出分辨率差异。不要额外添加调整大小步骤。

创建 Firefly Board

按如下方式调用 Firefly Board 工具，并传入最终输出 URL：

create_firefly_board({
  import_adobe_storage: [
    final_output_url_1,
    final_output_url_2,
    // ...
  ]
})

Board 链接处理：

• create_firefly_board 会返回一个 Board URL。提取该 URL 并存储为 board_url。
• 如果 board_url 存在且非空，请将其加入完成消息。
• 如果调用报错或未返回 URL：省略 Board 链接，并在摘要中注明“Firefly Board 不可用”（重试无济于事）。 然后发布完成消息。每条完成消息都包含逐张照片的下载链接。只要返回了 board_url，就包含 Board 链接。

如果 N ≤ 3：

✅ Done! [N] photos edited with a consistent [look name] look.

📥 Download:
• Photo 1 → <final_url_1>
• ...

🎨 View in Firefly Board → <board_url>   ← always include if board_url is set

Look applied: [look name] → [brief description of what was applied]

如果 N > 3：

✅ Done! [N] photos edited with a consistent [look name] look.

📥 Your edited photos:
• Photo 1 → <final_url_1>
• Photo 2 → <final_url_2>
• ...

🎨 View in Firefly Board → <board_url>   ← always include if board_url is set

Look applied: [look name] → [brief description of what was applied]

---

详细程度规则

仅报告：主要阶段的开始、逐张图像处理失败（仅记录一次）以及最终摘要。

• 主要阶段开始时（例如“正在为 [N] 张图像应用 Warm & Golden 风格……”）
• 任何逐张图像处理失败（记录一次，然后继续）
• 包含网格和下载链接的最终摘要

---

输出提取

所有处理流程工具都会返回：

{ "results": [{ "success": true, "outputUrl": "https://..." }] }

读取 results[N].outputUrl。如果 success: false → 请参阅错误处理。

---

错误处理

情况	操作
image_list_presets 返回空结果或 403	跳过所有图像的步骤 5b 和 5e。在摘要中注明：“此套餐无法使用预设。”仍会执行色温调整和手动调整。
步骤 5e 中 image_select_subject 失败	跳过该图像的所有局部预设；将外观输出用作步骤 6 的输入。在摘要中注明一次。
image_apply_preset 返回 403	跳过所有图像的预设。在摘要中注明：“已跳过 [Preset name]——您的 Adobe 套餐不包含此预设。”继续执行其他外观步骤。
任何色调/颜色工具返回 403	跳过该步骤。在摘要中注明。继续。
任何工具返回 "No approval received"	按 403 权限错误处理。对于可选步骤（预设、微调、预览），跳过并在摘要中注明。重试无法解决此错误——请按照上述规则继续。
任何工具返回 401	请用户通过 Adobe OAuth 重新进行身份验证，然后重试。
任何工具返回 "file too large or corrupted"	立即停止处理该图像。不要重试。告知用户：“我无法处理 [filename]——文件过大或可能已损坏。请尝试重新上传较小的版本，或检查文件是否能在您的设备上正常打开。”在摘要中标记该图像，并继续处理其余图像。
程序化上传失败（PUT 5xx / 无出口流量）	改用 asset_add_file 选择器（默认导入路径），并告知用户您将打开它来暂存文件。
asset_add_file 未显示文件（选择器路径）	提醒用户在选择器中选择文件。
URI 以 dcx-stage.adobe.io 开头（选择器路径）	通过 read_widget_context 将其解析为真实的预签名 S3 URL。
image_auto_straighten 失败	使用原始 URI；注明“已跳过拉直”。
image_apply_auto_tone 失败	使用拉直后的 URI；在摘要中注明。
任何调整工具失败	使用上一步的输出；在摘要中注明。
image_apply_effects 不可用/未知工具	使用相同的 blurRadius 和 blurTarget 重试一次 image_apply_gaussian_blur；对用户显示的结果不变。
image_apply_effects 及其回退方案都失败	使用上一步的输出；注明“已跳过模糊处理”。
image_crop_and_resize 失败	使用模糊/调整后的输出作为最终结果；在摘要中注明。
asset_preview_file 返回 "No approval received"	改为在摘要中以纯文本链接形式提供最终输出 URL。
一张图像的所有步骤都失败	返回原始 URI；在摘要中明确标记。

---

硬性约束

• 批次中的每张图像都必须处理；遇到失败时要明确标记，不能悄悄跳过。
• 绝不能将原始本地文件系统路径传递给任何 image_* 工具。本地文件必须先进入 Creative Cloud：通过 asset_add_file 选择，或（无小组件时的备用方案）依次通过 asset_initialize_file_upload → PUT → asset_finalize_file_upload 暂存；只有由此生成的预签名 CC URI 才是图像工具的有效来源。
• 调用 image_apply_auto_tone 时，type: "cameraRawFilter"。
• 对批次中的每张图像应用相同的参数值（一致性优先于完美效果）。
• 预设选择始终动态进行：运行时调用 image_list_presets，并构建 Look→Preset Map 和 Selective Adaptive Map；绝不能硬编码预设名称。
• 所有色调／颜色调整（色温、自然饱和度、饱和度、亮度、对比度、曝光、高光、阴影、暗部、亮部）都使用 image_apply_adjustments——单项工具（image_adjust_color_temperature、image_adjust_vibrance_and_saturation、image_adjust_highlights 等）已弃用，不能使用。
• 将所有外观调整（步骤 5a）合并为一次 image_apply_adjustments 调用，并将所有微调（步骤 6）合并为一次 image_apply_adjustments 调用；绝不能连续调用多次调整工具。
• 选择性自适应增强（步骤 5e）默认关闭——只有用户通过问题 5 明确选择启用时才运行。
• 步骤 5e 只对检测到的元素应用预设——没有天空的图像不应用天空预设，没有人物的图像不应用主体预设。此处每张图像的处理有所不同是正确的。
• 预览阶段使用图像 1 的 1200px 缩小版本；最终批次使用全分辨率图像。
• 背景模糊使用 image_apply_effects，并设置 effect: "gaussianBlur" 和 blurTarget: "background"；如果 image_apply_effects 尚不可用，则改用旧版 image_apply_gaussian_blur（此处不使用 image_apply_lens_blur）。
• 前后对比预览确认关卡（步骤 2c）必须执行，不能跳过——未经用户明确确认，绝不能开始处理整个批次，无论用户事先表达偏好的方式多么明确。
• 用户调整设置后，必须使用新设置重新进行预览，然后才能运行批次。不能绕过预览直接处理全部图像。
• 完成后通过清晰的聊天消息告知用户（不发送推送通知）。