meitu 图片换脸（image-face-swap）
Overview
双图换脸/换头合成，将源图人脸替换到目标场景图上。保留目标图的构图/身体/背景，自动肤色融合光影匹配；用于角色扮演、把自己的脸放到另一张图上、趣味合成。一次只换一张脸。
执行前应让用户清楚知道：本 Skill 会读取 Meitu 凭证、调用本地 meitu CLI、将两张人脸相关图片发送到 Meitu OpenAPI 处理，并把结果写入 ./output/ 或 $VISUAL/output/image-face-swap/。
API Mapping
- 双图换脸/换头合成：
image_face_swap
Dependencies
- meitu-cli:
>=2.0.6（npm install -g meitu-cli@latest） - 凭证：CONFIG AKSK →
meitu tools update；EXEC AKSK → 实际执行（见根CONFIG.md） - 环境变量：
MEITU_OPENAPI_TOOL_TASK_MODE=command
路径别名：
$VISUAL={OPENCLAW_HOME}/workspace/visual/
Core Workflow
Preflight → Execute → Deliver
Preflight
meitu --version≥ 2.0.6（否则npm install -g meitu-cli@latest）- 确认已跑过
meitu tools update（用 CONFIG AKSK） - 当前 AKSK = EXEC，且
MEITU_OPENAPI_TOOL_TASK_MODE=command - 解析 output_dir：openclaw.yaml →
./output/｜else →$VISUAL/output/image-face-swap/；mkdir -p
Execute
触发信号 / 路由规则
核心判断维度：图片数量 + head/sence 角色分配。
| 场景 | 判定 | 路由 |
|---|---|---|
| 双图换脸 | 提供 2 张图，意图换脸 | image_face_swap，head/sence 按规则分配 |
决策顺序：
- 图片数量：不足 2 张 → 提示补图；超过 2 张 → 取前 2 张并告知
- 角色分配：
- 用户明确指定 → 按指定分配 head / sence
- 未区分 → 第 1 张 = head（人脸源），第 2 张 = sence（场景底图）
- "用 B 换到 A" → B=head（源），A=sence
- 唯一路由：调用
image_face_swap
单 API 工具：参数齐全即调用，失败重试 1 次后返回错误；不做跨工具兜底。侧脸/遮挡严重不阻断调用，但告知效果可能受限。
参数定义
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
head_image_url |
STRING | 是 | -- | 人脸源图 URL |
sence_image_url |
STRING | 是 | -- | 场景底图 URL（保留构图/身体/背景） |
prompt |
STRING | 是 | -- | 附加提示词。缺失 → 提示"请描述换脸效果要求" |
工具调用
meitu image-face-swap \
--skill_name skill_image-face-swap \
--head_image_url <head_url> \
--sence_image_url <sence_url> \
--prompt "<effect_description>" \
--json \
--download-dir {output_dir}
错误降级
| 场景 | 处理方式 |
|---|---|
| 图片不足 2 张 | 提示"请提供两张图片：一张人脸源图，一张目标场景图" |
| 图片 3+ 张 | 取前 2 张（第 1=head，第 2=sence），告知用户 |
head_image_url / sence_image_url 不可访问 |
返回图片链接无效错误，不重试 |
| 未检测到人脸（head） | 返回错误：人脸源图需包含清晰正脸 |
image_face_swap 调用失败 |
重试 1 次，仍失败返回错误 |
| 内容合规拦截 | 返回合规提示，不重试 |
| 侧脸 / 遮挡严重 | 不阻断调用，告知效果可能受限 |
| 视频换脸 | 拒绝，仅支持图片 |
| 多人同时换脸 | 本工具一次只换一张脸 |
Deliver
- 直接使用 Preflight 解析的 output_dir
- 从
downloaded_files[0].saved_path读取已下载文件路径 mv {downloaded_files[0].saved_path} {output_dir}/{YYYY-MM-DD}_{descriptive}_image-face-swap.jpg
Output
- 格式：JPEG/PNG（保持原格式）
- 命名：
{YYYY-MM-DD}_{descriptive}_image-face-swap.jpg - 位置：项目 →
./output/，一次性 →$VISUAL/output/image-face-swap/
基线 Task ID
见 references/task-id-baseline.md 中对应行。