adobe-retouch-portraits

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Adobe Retouch Portraits

A walk-away bulk retouching pipeline for photographers. The user selects their images, optionally adds tweaks, and Claude runs the full batch using Adobe for creativity tools.

面向摄影师的可脱离操作批量修图流程。用户选择图片，可选择性添加调整项，由Claude借助Adobe创意工具完成全批量处理。

Tool Reference (Adobe for creativity connector)

工具参考（Adobe创意连接器）

Step	Tool	Notes
Ingest	`asset_add_file`	Interactive file picker
Straighten	`image_auto_straighten`	Per image
Auto-Tone	`image_apply_auto_tone` (cameraRawFilter)	Per image
Exposure	`image_adjust_exposure`	Batch ( `imageURIs` array)
Highlights	`image_adjust_highlights`	Batch
Shadows	`image_adjust_dark_portions`	Batch
Brightness/Contrast	`image_adjust_brightness_and_contrast`	Batch
Vibrance/Saturation	`image_adjust_vibrance_and_saturation`	Batch
Face detection	`image_select_subject` with `bodyParts: ["Face"]`	To check for face presence
Adaptive Enhancements	`image_apply_preset`	Per image, opt-in (see Step 6)
Adaptive Blur BG	`image_apply_preset` ("Adaptive: Blur Background - Subtle")	Replaces `image_apply_lens_blur` when selected
Heavy blur	`image_apply_gaussian_blur`	Per image (if user requests, no adaptive selected)
Crop	`image_crop_and_resize`	Per image
Sample preview	`asset_preview_file`	Before/after on image[0] only
Final preview	`asset_preview_file`	All final URLs directly, no resize step
Firefly Board	`create_firefly_board`	Source presigned URLs from ingestion

步骤	工具	说明
图片导入	`asset_add_file`	交互式文件选择器
自动拉直	`image_auto_straighten`	逐张图片处理
自动调色	`image_apply_auto_tone` (cameraRawFilter)	逐张图片处理
曝光调整	`image_adjust_exposure`	批量处理（ `imageURIs` 数组）
高光调整	`image_adjust_highlights`	批量处理
阴影调整	`image_adjust_dark_portions`	批量处理
亮度/对比度调整	`image_adjust_brightness_and_contrast`	批量处理
自然饱和度/饱和度调整	`image_adjust_vibrance_and_saturation`	批量处理
人脸检测	`image_select_subject` 搭配 `bodyParts: ["Face"]`	用于检测是否有人脸
自适应增强	`image_apply_preset`	逐张图片处理，需用户选择开启（见步骤6）
自适应背景模糊	`image_apply_preset` （"Adaptive: Blur Background - Subtle"）	用户选择时替代 `image_apply_lens_blur`
重度模糊	`image_apply_gaussian_blur`	逐张图片处理（仅当用户要求且未选择自适应模糊时）
裁剪	`image_crop_and_resize`	逐张图片处理
样本预览	`asset_preview_file`	仅对第一张图片展示前后对比
最终预览	`asset_preview_file`	直接展示所有最终URL，无需调整尺寸步骤
Firefly画板	`create_firefly_board`	从导入环节获取预签名URL

Step 0 - prereq: Initialize Adobe Tools

步骤0 - 前置要求：初始化Adobe工具

Call

adobe_mandatory_init

first. This returns file handling rules and tool routing guidance required for the rest of the workflow.

json

{ "skill_name": "adobe-retouch-portraits", "skill_version": "1.0.1" }

首先调用

adobe_mandatory_init

。该接口会返回后续工作流程所需的文件处理规则和工具路由指引。

json

{ "skill_name": "adobe-retouch-portraits", "skill_version": "1.0.1" }

Step 1 — Entitlement Check

步骤1 — 权限校验

Now that

adobe_mandatory_init

confirmed that the "Adobe for creativity" connector is live, check which tools are available through the "Adobe for creativity" connector by cross checking against the Tool Reference table above.

在

adobe_mandatory_init

确认“Adobe创意”连接器可用后，对照上方的工具参考表格，检查该连接器可使用的工具。

Step 2: Image Ingestion

步骤2：图片导入

Call

asset_add_file

with no parameters. This renders an interactive UI where the user can:

Browse CC storage and select a folder or individual files
Upload from device (local files)
In Cowork: select a local folder path directly

Tool: asset_add_file
Params: {}

Important:

asset_add_file

returns

imageURIs: []

— this is expected and NOT an error. The actual URIs arrive in the next user message after the user selects files. Wait for that follow-up before continuing.

调用无参数的

asset_add_file

。该工具会生成交互式UI，用户可：

浏览CC存储并选择文件夹或单个文件
从设备上传（本地文件）
在Cowork中：直接选择本地文件夹路径

Tool: asset_add_file
Params: {}

重要提示：

asset_add_file

会返回

imageURIs: []

— 这是正常现象，并非错误。实际的URI会在用户选择文件后的下一条消息中返回。等待该消息后再继续操作。

Step 3: Announce Pipeline + Offer Options

步骤3：告知流程并提供选项

Once URIs are obtained, check whether the user's message already fully specifies their enhancement, tweak, and crop preferences.

If preferences are fully stated upfront (e.g. "retouch with subject pop, no tweaks, crop 1:1"), skip

AskUserQuestion

entirely and go straight to the confirmation message. Map their stated preferences using the button→parameter table below.

If preferences are not fully stated (e.g. "please retouch them" with no further detail), post this message first:

📸 Got [N] photo(s)! The default pipeline will auto-straighten and auto-tone every image.

Let me know if you'd like any extras 👇

Then call

AskUserQuestion

with these three questions:

Question 1 (multi_select):
  question: "✨ Adaptive AI enhancements (select any — or none to skip)"
  options:
    - "All"
    - "Subject Pop — boost contrast & vibrance on the person"
    - "Warm Pop — warm, glowing subject lift"
    - "Whiten Teeth — brightens teeth (smiles only)"
    - "Blur Background — subtle bg blur, respects edges"
    - "Sky Drama (Blue) — deepen sky blue, outdoor only"
    - "Sky Drama (Dark) — moody dramatic sky, outdoor/editorial"
    - "None"

Question 2 (multi_select):
  question: "🎛️ Manual tweaks (select any — or none to skip)"
  options:
    - "Recover highlights"
    - "Lift shadows"
    - "More contrast"
    - "More vibrant"
    - "Desaturate (muted tones)"
    - "Heavy background blur"
    - "None"

Question 3 (single_select):
  question: "✂️ Crop ratio"
  options:
    - "Auto (landscape→4:3, portrait→3:4)"
    - "1:1 square"
    - "4:5 portrait"
    - "16:9 wide"

Hold processing until the user replies with their selections.

获取URI后，检查用户的消息是否已明确说明他们的增强、调整和裁剪偏好。

如果偏好已提前明确说明（例如：“用主体突出效果修图，无需额外调整，裁剪为1:1比例”），则直接跳过

AskUserQuestion

，进入确认消息环节。使用下方的按钮→参数映射表，将用户说明的偏好转换为对应参数。

如果偏好未明确说明（例如：“请帮我修图”且无更多细节），则先发送以下消息：

📸 已获取[N]张照片！默认流程会对每张图片应用自动拉直和自动调色。

如果需要额外调整，请告知我👇

然后调用

AskUserQuestion

，提出以下三个问题：

问题1（多选）：
  question: "✨ 自适应AI增强效果（可多选——或选无跳过）"
  options:
    - "全部"
    - "主体突出——提升人物的对比度和自然饱和度"
    - "暖调突出——为主体添加温暖明亮的效果"
    - "美白牙齿——提亮牙齿（仅针对微笑的照片）"
    - "背景模糊——柔和的背景模糊，保留边缘细节"
    - "天空增强（蓝色）——加深天空蓝色，仅适用于户外照片"
    - "天空增强（深色）——营造氛围感深色天空，适用于户外/编辑类照片"
    - "无"

问题2（多选）：
  question: "🎛️ 手动调整（可多选——或选无跳过）"
  options:
    - "恢复高光"
    - "提亮阴影"
    - "增加对比度"
    - "提高自然饱和度"
    - "降低饱和度（柔和色调）"
    - "重度背景模糊"
    - "无"

问题3（单选）：
  question: "✂️ 裁剪比例"
  options:
    - "自动（横图→4:3，竖图→3:4）"
    - "1:1正方形"
    - "4:5竖图"
    - "16:9宽屏"

等待用户回复选择后再继续处理。

Mapping button selections to parameters

按钮选择与参数映射

Adaptive enhancements:

"All" → run all six presets (apply skip conditions as normal: Whiten Teeth requires face, Sky presets require outdoor context)
"Subject Pop" →
```
Adaptive: Subject - Pop
```
"Warm Pop" →
```
Adaptive: Subject - Warm Pop
```
"Whiten Teeth" →
```
Adaptive: Portrait - Whiten Teeth
```
(skip if no face detected)
"Blur Background" →
```
Adaptive: Blur Background - Subtle
```
(skip Step 7 for that image)
"Sky Drama (Blue)" →
```
Adaptive: Sky - Blue Drama
```
"Sky Drama (Dark)" →
```
Adaptive: Sky - Dark Drama
```
"None" → skip Step 6 entirely Manual tweaks:
"Recover highlights" →
```
image_adjust_highlights
```
→
```
amount: -60
```
"Lift shadows" →
```
image_adjust_dark_portions
```
→
```
amount: -40
```

"More contrast" →

image_adjust_brightness_and_contrast

→

contrast: 30

"More vibrant" →

image_adjust_vibrance_and_saturation

→

vibrance: 30

"Desaturate" →

image_adjust_vibrance_and_saturation

→

saturation: -30

"Heavy background blur" →
```
image_apply_gaussian_blur
```
→
```
blurRadius: 12, blurTarget: "background"
```
(do not combine with Blur Background adaptive preset)
"None" → skip Step 5b entirely Crop:
"Auto" → landscape →
```
"4:3"
```
, portrait →
```
"3:4"
```
, focus:
```
"face"
```
"1:1 square" →
```
output: "1:1"
```
, focus:
```
"face"
```
"4:5 portrait" →
```
output: "4:5"
```
, focus:
```
"face"
```
"16:9 wide" →
```
output: "16:9"
```
, focus:
```
"face"
```
All crop modes use
```
focus: "face"
```
. If no face is detected, fall back to
```
focus: "subject"
```
.

After receiving button selections, confirm the settings back to the user:

✅ Got it — running with:
- Auto-straighten + auto-tone + auto-light
- Adaptive enhancements: [list selected, or "none"]
- Manual tweaks: [list if any, or "none"]
- Crop: [ratio or "auto 4:3/3:4"]
- Blur: [adaptive / heavy / none]

自适应增强效果：

"全部" → 运行全部6种预设效果（按常规跳过条件执行：美白牙齿需检测到人脸，天空预设需户外场景）
"主体突出" →
```
Adaptive: Subject - Pop
```
"暖调突出" →
```
Adaptive: Subject - Warm Pop
```
"美白牙齿" →
```
Adaptive: Portrait - Whiten Teeth
```
（未检测到人脸则跳过）
"背景模糊" →
```
Adaptive: Blur Background - Subtle
```
（该图片跳过步骤7）
"天空增强（蓝色）" →
```
Adaptive: Sky - Blue Drama
```
"天空增强（深色）" →
```
Adaptive: Sky - Dark Drama
```
"无" → 完全跳过步骤6 手动调整：
"恢复高光" →
```
image_adjust_highlights
```
→
```
amount: -60
```
"提亮阴影" →
```
image_adjust_dark_portions
```
→
```
amount: -40
```

"增加对比度" →

image_adjust_brightness_and_contrast

→

contrast: 30

"提高自然饱和度" →

image_adjust_vibrance_and_saturation

→

vibrance: 30

"降低饱和度" →

image_adjust_vibrance_and_saturation

→

saturation: -30

"重度背景模糊" →
```
image_apply_gaussian_blur
```
→
```
blurRadius: 12, blurTarget: "background"
```
（不可与自适应背景模糊预设同时使用）
"无" → 完全跳过步骤5b 裁剪：
"自动" → 横图 →
```
"4:3"
```
，竖图 →
```
"3:4"
```
，焦点：
```
"face"
```
"1:1正方形" →
```
output: "1:1"
```
，焦点：
```
"face"
```
"4:5竖图" →
```
output: "4:5"
```
，焦点：
```
"face"
```
"16:9宽屏" →
```
output: "16:9"
```
，焦点：
```
"face"
```
所有裁剪模式均使用
```
focus: "face"
```
。若裁剪工具未检测到人脸，则 fallback 为
```
focus: "subject"
```
。

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

✅ 已确认——将按照以下设置运行：
- 自动拉直 + 自动调色 + 自动补光
- 自适应增强效果：[列出所选效果，或“无”]
- 手动调整：[列出所选调整项，或“无”]
- 裁剪：[比例或“自动4:3/3:4”]
- 模糊效果：[自适应/重度/无]

Step 3a: Large Batch Warning (N > 5)

步骤3a：大批次提示（N > 5）

Include this in the confirmation when N > 5:

⏱ 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 ✅ completion summary with your
download links when done. (No Slack/email notifications available from here.)

当照片数量N > 5时，在确认消息中添加以下内容：

⏱ [N]张图片的预计处理时间：
  6–10张 → ~3–5分钟
  11–20张 → ~5–10分钟
  20张以上 → 10分钟以上

您可以先去处理其他事情——完成后我会发送✅完成总结和下载链接。（暂不支持Slack/邮件通知。）

Step 3b: Sample Preview (Before/After on Image 1)

步骤3b：样本预览（第一张图片的前后对比）

Before running the full batch, process the first image only through the complete pipeline (Steps 4–8) using the confirmed settings. This gives the user a real preview of exactly what will be applied to every image.

Run the full pipeline on
```
sourceURIs[0]
```
only (straighten → tone → tweaks → adaptive → blur → crop).
Call
```
asset_preview_file
```
directly with the original source URL and the processed output — do NOT resize either through
```
image_crop_and_resize
```
first, as that introduces white bars or unwanted cropping:

javascript

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

Post this message:

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

How does it look?

Call
```
AskUserQuestion
```
with a single question:

Question (single_select):
  question: "Ready to run the full batch?"
  options:
    - "✅ Looks great — run all [N] images"
    - "🎛️ Adjust settings first"
    - "❌ Cancel"

Processing pauses here until the user responds — the gate catches issues before time is spent on the full batch.

If "Looks great": proceed to Step 4 for the remaining images. Reuse the already-processed image 1 result — do not reprocess it.

If "Adjust settings": return to Step 3 (

AskUserQuestion

) to re-collect preferences. Once new settings are confirmed, ask:

Question (single_select):
  question: "Want to preview the new settings first, or run all images now?"
  options:
    - "👁 Preview first"
    - "🚀 Run all [N] images now"

If "Preview first": repeat Step 3b with the new settings (reprocess image 1, show before/after, offer the gate again).
If "Run all now": start the full batch immediately on all images with the new settings. Do not reuse the earlier image 1 result — reprocess it with the updated settings. If "Cancel": stop and let the user know they can restart any time.

在运行全批次处理前，仅对第一张图片使用已确认的设置完成完整流程（步骤4–8）。这样用户可以预览即将应用到所有图片的效果。

仅对
```
sourceURIs[0]
```
运行完整流程（拉直→调色→调整→自适应增强→模糊→裁剪）。
直接调用
```
asset_preview_file
```
，传入原始图片URL和处理后的输出——不要先通过
```
image_crop_and_resize
```
调整尺寸，否则会出现白边或不必要的裁剪：

javascript

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

发送以下消息：

👆 这是使用您的第一张照片和所选设置生成的前后对比预览。

效果如何？

调用
```
AskUserQuestion
```
，提出一个问题：

问题（单选）：
  question: "是否准备好运行全批次处理？"
  options:
    - "✅ 效果很好——处理所有[N]张图片"
    - "🎛️ 先调整设置"
    - "❌ 取消"

处理会在此处暂停，等待用户回复——这一环节可在花费时间处理全批次前发现问题。

如果选择“效果很好”： 继续处理剩余图片的步骤4。复用已处理好的第一张图片结果——无需重新处理。

如果选择“先调整设置”： 返回步骤3（

AskUserQuestion

）重新收集偏好。确认新设置后，询问：

问题（单选）：
  question: "是否需要先预览新设置的效果，还是直接处理所有图片？"
  options:
    - "👁 先预览"
    - "🚀 立即处理所有[N]张图片"

如果选择“先预览”：使用新设置重复步骤3b（重新处理第一张图片，展示前后对比，再次提供确认选项）。
如果选择“立即处理所有图片”：立即使用新设置处理所有图片。不要复用之前的第一张图片结果——需用新设置重新处理。 如果选择“取消”： 停止处理，并告知用户可随时重启。

Step 4: Auto-Straighten (per image)

步骤4：自动拉直（逐张图片）

Loop one image at a time (no batch support):

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

Output:

results[0].outputUrl

→ collect as

straightened_urls[]

On failure: use original URI, note "straighten skipped" for that image.

逐张处理图片（不支持批量）：

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

输出：

results[0].outputUrl

→ 存入

straightened_urls[]

若处理失败：使用原始URI，并记录该图片“已跳过拉直步骤”。

Step 5: Auto-Tone (per image)

步骤5：自动调色（逐张图片）

Tool: image_apply_auto_tone
Params:
  imageURIs: ["<straightened_url_N>"]

Output:

results[0].outputUrl

→ collect as

toned_urls[]

Tool: image_apply_auto_tone
Params:
  imageURIs: ["<straightened_url_N>"]

输出：

results[0].outputUrl

→ 存入

toned_urls[]

Step 5b: Optional Tone Adjustments (batch)

步骤5b：可选色调调整（批量）

If the user requested tonal tweaks, apply in this order using batch arrays, chaining each step's output into the next:

image_adjust_exposure

— pass

imageURIs: [all toned_urls]

```
image_adjust_highlights
```
```
image_adjust_dark_portions
```
```
image_adjust_light_portions
```
```
image_adjust_brightness_and_contrast
```
```
image_adjust_vibrance_and_saturation
```

如果用户要求色调调整，按以下顺序使用批量数组应用，将每一步的输出作为下一步的输入：

image_adjust_exposure

— 传入

imageURIs: [所有toned_urls]

```
image_adjust_highlights
```
```
image_adjust_dark_portions
```
```
image_adjust_light_portions
```
```
image_adjust_brightness_and_contrast
```
```
image_adjust_vibrance_and_saturation
```

Step 6: Adaptive Enhancements (per image, opt-in only)

步骤6：自适应增强效果（逐张图片，仅用户选择时运行）

Only run this step if the user selected one or more adaptive enhancements. Run each selected preset in sequence, chaining outputs. The order below is recommended but not required by the tools:

```
Adaptive: Subject - Pop
```
(if selected)
```
Adaptive: Subject - Warm Pop
```
(if selected — do not combine with Subject Pop; pick one or let user decide)

Adaptive: Portrait - Whiten Teeth

(if selected AND face detected via

image_select_subject

)

```
Adaptive: Blur Background - Subtle
```
(if selected — skip Step 7 entirely for this image)
```
Adaptive: Sky - Blue Drama
```
(if selected AND not skipped due to indoor context)
```
Adaptive: Sky - Dark Drama
```
(if selected AND not skipped due to indoor context)

Tool: image_apply_preset
Params:
  imageURI: "<toned_url_N>"   # chain from previous step's output
  options:
    presetName: "<exact preset name from list above>"

Output:

results[0].outputUrl

→ chain as input to next preset or Step 7.

Skip conditions:

Whiten Teeth: skip if
```
image_select_subject
```
face check returned no face
Sky presets: skip if session context suggests indoor/studio (user said "headshots", "studio", "office", etc.). If ambiguous, attempt — no visible effect on indoor shots.
Subject Pop + Warm Pop: these serve similar purposes. If the user selected both, apply both. But if the result looks over-processed, note in the summary that combining them may be heavy-handed. On 403 (entitlement): Skip the preset, note it in the delivery summary ("Adaptive [name] was skipped — not included in your Adobe plan"). Continue with other presets and the rest of the pipeline.

仅当用户选择了一种或多种自适应增强效果时才运行此步骤。按顺序运行所选预设，将输出作为下一个预设或步骤7的输入。以下顺序为推荐顺序，工具无强制要求：

```
Adaptive: Subject - Pop
```
（若已选择）
```
Adaptive: Subject - Warm Pop
```
（若已选择——不可与主体突出同时使用；选择其一或由用户决定）

Adaptive: Portrait - Whiten Teeth

（若已选择且通过

image_select_subject

检测到人脸）

```
Adaptive: Blur Background - Subtle
```
（若已选择——该图片完全跳过步骤7）
```
Adaptive: Sky - Blue Drama
```
（若已选择且未因室内场景跳过）
```
Adaptive: Sky - Dark Drama
```
（若已选择且未因室内场景跳过）

Tool: image_apply_preset
Params:
  imageURI: "<toned_url_N>"   # 从上一步的输出传入
  options:
    presetName: "<上述列表中的准确预设名称>"

输出：

results[0].outputUrl

→ 作为下一个预设或步骤7的输入。

跳过条件：

美白牙齿：若
```
image_select_subject
```
人脸检测未返回人脸则跳过
天空预设：若会话上下文显示为室内/工作室场景（用户提到“头像照”“工作室”“办公室”等）则跳过。若场景不明确，可尝试运行——对室内照片无明显效果。
主体突出+暖调突出：二者功能类似。若用户同时选择了两者，则均应用。但如果处理结果看起来过度加工，需在总结中说明同时使用两者可能效果过重。 若返回403（权限不足）： 跳过该预设，在交付总结中记录“自适应[预设名称]已跳过——您的Adobe计划不包含此功能”。继续运行其他预设和剩余流程。

Step 7: Background Blur (per image)

步骤7：背景模糊（逐张图片）

Skip this step entirely if the user selected "Blur Background" in Step 6 — the adaptive preset already handled it.

No blur selected: skip this step entirely.

Heavy blur (if user explicitly requested and did NOT select adaptive blur):

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

On failure: use previous step's output, note "blur skipped" for that image.

Output:

results[0].outputUrl

如果用户在步骤6中选择了“背景模糊”，则完全跳过此步骤——自适应预设已完成该操作。

未选择模糊效果： 完全跳过此步骤。

重度模糊（仅当用户明确要求且未选择自适应模糊时）：

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

若处理失败：使用上一步的输出，并记录该图片“已跳过模糊步骤”。

输出：

results[0].outputUrl

Step 8: Crop (per image)

步骤8：裁剪（逐张图片）

Default behavior:

Landscape image → crop to
```
"4:3"
```
, focus:
```
"face"
```
Portrait image → crop to
```
"3:4"
```
, focus:
```
"face"
```
User-specified ratio (1:1, 4:5, 16:9, etc.) → use that, focus:
```
"face"
```
If no face is detected by the crop tool, fall back to
```
focus: "subject"
```

Tool: image_crop_and_resize
Params:
  imageURI: "<blur_url_N>"
  options:
    output: "4:3"          # or "3:4" / user choice
    fit: "reframe"
    focus: "face"          # falls back to "subject" if no face detected
  outputFileType: "jpeg"

These are the final full-resolution deliverables. Collect as

final_urls[]

默认行为：

横图 → 裁剪为
```
"4:3"
```
，焦点：
```
"face"
```
竖图 → 裁剪为
```
"3:4"
```
，焦点：
```
"face"
```
用户指定比例（1:1、4:5、16:9等） → 使用该比例，焦点：
```
"face"
```
若裁剪工具未检测到人脸，则 fallback 为
```
focus: "subject"
```

Tool: image_crop_and_resize
Params:
  imageURI: "<blur_url_N>"
  options:
    output: "4:3"          # 或"3:4"/用户选择的比例
    fit: "reframe"
    focus: "face"          # 未检测到人脸时自动 fallback 为"subject"
  outputFileType: "jpeg"

这些是最终的全分辨率交付文件。 存入

final_urls[]

。

Step 9: Final Preview + Download Links + Firefly Board

步骤9：最终预览 + 下载链接 + Firefly画板

Pass the final output URLs directly to

asset_preview_file

— do NOT run them through

image_crop_and_resize

first, as that introduces white bars or unwanted cropping.

asset_preview_file

handles its own thumbnailing correctly.

Call

asset_preview_file

for every run, regardless of batch size:

javascript

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

直接将最终输出URL传入

asset_preview_file

——不要先通过

image_crop_and_resize

处理，否则会出现白边或不必要的裁剪。

asset_preview_file

会正确生成缩略图。

无论批次大小，每次运行都需调用

asset_preview_file

：

javascript

asset_preview_file({
  assets: [
    { name: "portrait_1.jpg", presignedAssetUrl: final_url_1 },
    { name: "portrait_2.jpg", presignedAssetUrl: final_url_2 },
    // ... 每张图片对应一个条目
  ]
})

Create Firefly Board

创建Firefly画板

Call the firefly board tool with the final output urls as follows:

javascript

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

Board link handling:

Extract the returned URL and store as
```
board_url
```
.
If
```
board_url
```
is present and non-empty, include it in the completion message.
If the call fails or returns no URL: note "Firefly Board unavailable" in the summary (retrying does not help). Then post the completion message. The preview grid is included in every completion message. The board link is included whenever
```
board_url
```
was returned.

If N ≤ 3 — list individual links:

✅ All done! [N] portraits retouched and ready.

📥 Download your full-resolution portraits:
• Portrait 1 → <final_url_1>
• Portrait 2 → <final_url_2>

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

Pipeline applied: Auto-straighten → Auto-tone (Camera Raw) → [tweaks if any]
→ [adaptive enhancements if any] → [blur if any] → Crop [ratio]

If N > 3 — list all links:

✅ All done! [N] portraits retouched and ready.

📥 Your retouched portraits:
• Portrait 1 → <final_url_1>
• Portrait 2 → <final_url_2>
• ...

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

Pipeline applied: Auto-straighten → Auto-tone (Camera Raw) → [tweaks if any]
→ [adaptive enhancements if any] → [blur if any] → Crop [ratio]

使用最终输出URL调用Firefly画板工具：

javascript

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

画板链接处理：

提取返回的URL并保存为
```
board_url
```
。
若
```
board_url
```
存在且非空，将其包含在完成消息中。
若调用失败或未返回URL：在总结中记录“Firefly画板不可用”（重试无效）。然后发送完成消息。所有完成消息均需包含预览网格。若获取到
```
board_url
```
，则需包含画板链接。

若N ≤ 3 — 列出单个链接：

✅ 全部完成！[N]张人像照片已修图完毕，可供使用。

📥 下载全分辨率人像照片：
• 照片1 → <final_url_1>
• 照片2 → <final_url_2>

🎨 在Firefly画板中查看 → <board_url>   ← 若获取到board_url则始终包含

应用的流程：自动拉直 → 自动调色（Camera Raw） → [若有调整项] → [若有自适应增强效果] → [若有模糊效果] → 裁剪[比例]

若N > 3 — 列出所有链接：

✅ 全部完成！[N]张人像照片已修图完毕，可供使用。

📥 已修图的人像照片：
• 照片1 → <final_url_1>
• 照片2 → <final_url_2>
• ...

🎨 在Firefly画板中查看 → <board_url>   ← 若获取到board_url则始终包含

应用的流程：自动拉直 → 自动调色（Camera Raw） → [若有调整项] → [若有自适应增强效果] → [若有模糊效果] → 裁剪[比例]

Verbosity Rule

日志简洁规则

Built for large batches — report only: per-stage start, individual failures (logged once), and the final summary.

When a pipeline stage begins for the whole batch (e.g. "Straightening [N] images...")
If an individual image fails (log once, continue)
Final completion summary with grid + download links

针对大批次处理设计——仅报告：各阶段开始、单个图片处理失败（仅记录一次）、最终总结。

当整个批次的某个流程阶段开始时（例如：“正在拉直[N]张图片...”）
若单个图片处理失败（记录一次，继续处理其他图片）
包含预览网格和下载链接的最终完成总结

Output Extraction Reference

输出提取参考

All pipeline tools return:

json

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

Output is read from

results[N].outputUrl

. On

success: false

see Error Handling.

所有流程工具均返回：

json

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

从

results[N].outputUrl

读取输出。若

success: false

，请参考错误处理部分。

Error Handling

错误处理

Situation	Action
`image_apply_preset` (adaptive) returns 403 (entitlement)	Skip that preset (Pattern 1). Note in delivery summary: "[Preset name] was skipped — your Adobe plan does not include this feature." Retrying does not resolve a 403 entitlement — note the skip in the summary.
Any tool returns 401 (not authenticated)	Ask the user to re-authenticate via Adobe OAuth and retry
`asset_add_file` shows no files	Wait; remind user to select files in the picker
`image_auto_straighten` fails	Pass original URI to Step 5; note "straighten skipped"
`image_apply_auto_tone` fails	Pass straightened URI forward; note in summary
Any tone adjustment fails	Log and continue with previous step's output
`image_select_subject` (face check) fails	Skip Whiten Teeth preset for that image; continue
`image_apply_preset` (adaptive) fails	Use previous step's output; note "[preset name] skipped" in summary
`image_apply_gaussian_blur` fails	Use previous step's output; note "blur skipped"
`image_crop_and_resize` fails	Use blur output as final; note in summary
`asset_preview_file` fails	Present final output URLs as plain text links in the summary.
All steps fail on one image	Return original URI; flag clearly in summary
Dead end	Report the failure clearly and offer to retry.

场景	处理方式
`image_apply_preset` （自适应）返回403（权限不足）	跳过该预设（模式1）。在交付总结中记录：“[预设名称]已跳过——您的Adobe计划不包含此功能。” 重试无法解决403权限问题——需在总结中记录跳过情况。
任意工具返回401（未认证）	请用户通过Adobe OAuth重新认证后重试
`asset_add_file` 未显示文件	等待；提醒用户在选择器中选择文件
`image_auto_straighten` 处理失败	将原始URI传入步骤5；记录“已跳过拉直步骤”
`image_apply_auto_tone` 处理失败	将拉直后的URI传入下一步；在总结中记录
任意色调调整处理失败	记录日志并继续使用上一步的输出
`image_select_subject` （人脸检测）处理失败	跳过该图片的美白牙齿预设；继续处理
`image_apply_preset` （自适应）处理失败	使用上一步的输出；在总结中记录“[预设名称]已跳过”
`image_apply_gaussian_blur` 处理失败	使用上一步的输出；记录“已跳过模糊步骤”
`image_crop_and_resize` 处理失败	将模糊处理后的输出作为最终文件；在总结中记录
`asset_preview_file` 处理失败	在总结中将最终输出URL作为纯文本链接展示。
某张图片的所有步骤均处理失败	返回原始URI；在总结中明确标记
进入死胡同	清晰报告失败情况并提供重试选项。

Hard Constraints

硬性约束

Every image in the batch is processed; failures are flagged rather than silently skipped.

image_apply_auto_tone

is called with

type: "cameraRawFilter"

Adaptive enhancements are off by default — only run them if the user explicitly selects them.
Background blur is handled by the "Adaptive: Blur Background - Subtle" preset (or
```
image_apply_gaussian_blur
```
for heavy blur);
```
image_apply_lens_blur
```
is not used here.
When "Blur Background" adaptive preset is selected, Step 7 is skipped for that image (the two steps are mutually exclusive).
Whiten Teeth preset only runs when a face is detected via
```
image_select_subject
```
.
Push notifications (Slack/email/text) are not available from here; completion is communicated through an in-chat summary.

批次中的每张图片都会被处理；处理失败会被标记，而非静默跳过。

image_apply_auto_tone

需传入

type: "cameraRawFilter"

。

自适应增强效果默认关闭——仅当用户明确选择时才运行。
背景模糊由“Adaptive: Blur Background - Subtle”预设处理（或重度模糊使用
```
image_apply_gaussian_blur
```
）；此处不使用
```
image_apply_lens_blur
```
。
当选择“Adaptive: Blur Background - Subtle”自适应预设时，该图片跳过步骤7（两个步骤互斥）。
美白牙齿预设仅在
```
image_select_subject
```
检测到人脸时运行。
暂不支持推送通知（Slack/邮件/短信）；完成情况通过聊天内的总结告知用户。