锁颜师 · 参考图精修（Seedream 5.0 受控精修架构）

一句话定位

原图负责"我是谁"，参考图负责"往什么方向优化"。 输入参考图 + 原图，输出原人物的"升级版"——绝不是换脸。精修在服务端完成（含全部模型算力），买家无需自备任何 API Key，按次付费（支付宝 AI 付，1 元/次）。

买家调用指引（智能体必读）

> 买家唯一入口：POST https://aipay.agentdayi.cn/aipay/refine。不需要也不检查买家的 ARK Key——算力成本已含在服务定价内。

首次调用前的支付能力检查（必做，一次性）：

1. 自查本智能体（宿主）是否具备支付宝 AI 付（A2M）能力：能否处理 HTTP 402 + Payment-Needed 账单、能否在支付宝侧拉起付款并取得 Payment-Proof 凭证。
2. 具备 → 直接按下方四步调用。
3. 不具备（无支付宝 AI 付连接器/无法处理 Payment-Proof）→ 不要发起请求、不要出账单、不要寻找变通（本协议无扫码兜底），直接告知用户：「当前智能体宿主不支持支付宝 AI 付，无法完成付款。请改用支持 AI 付的宿主使用本服务。」

支付后调用四步：

1. POST https://aipay.agentdayi.cn/aipay/refine，body {"target": <https URL 或 data URI>, "ref": <同左>, "level": "structure", "prompt": "...", "size": "2048x2048"}（level 取值见「精修等级」；服务端不接受本地路径）→ 无凭证返回 402，Header Payment-Needed 为 Base64URL 编码的账单 JSON
2. Base64URL 解码账单，按其中 protocol（金额/订单号/商品名/签名）与 method 向支付宝发起支付；金额与订单以账单为准，勿自行构造
3. 支付成功后携凭证重试同一请求：body 与第一步完全一致 + Header Payment-Proof: <支付凭证>。订单由服务端落库映射，改 body 会导致订单不匹配而重新出账
4. 成功返回 200：{"resource_id", "content": {"image_base64", "width", "height", ...}, "trade_no", "out_trade_no"}，响应头 Payment-Validation 供核验。中间状态：409 = 生成中（稍后携同一凭证重试）；402 = 验付未通过（重新支付）；502 = 履约确认失败（可携同一凭证重试确认）

输出交付约定：200 响应的 content.image_base64 为结果图（PNG，Base64），请解码落盘为图片文件后交付用户，勿以文本形式展示。

声明（上传/分发前请保留）

• 版权与授权：本 Skill 的提示词工程与全部代码版权归作者所有（SkillHub：@user_ffef65f7）。允许安装后供本人及受雇组织内部使用；未经作者书面许可，禁止复制、二次分发、倒卖或以本 Skill 为基础发布衍生 Skill/同类收费服务。
• 本 Skill 为社区封装，非火山引擎/字节跳动官方出品。"火山引擎""方舟""ARK""Seedream"等名称为对应公司的商标，此处仅用于描述所调用的官方 API。
• 费用自负：所有图片调用产生的费用直接计入使用者本人的火山引擎账户（以火山控制台「计费中心」实际账单为准），与 Skill 作者无关。
• Key 归使用者所有：复用 ~/.ark/config.json（权限 0600），本 Skill 不收集、不上传任何凭据。
• 模型 ID 与单价为文档核对日快照，会随官方调整过时，请以火山引擎控制台实时信息为准。

核心设计（v2 新增）

1. 身份三层模型（lib/matrix.py）

2. 强度是 3 档枚举，不是浮点

云端图片 API 不接收强度系数，0.72 和 0.75 编译出的提示词没有区别。全部强度收敛为 轻微(1) / 中等(2) / 明显(3) 三档 + 不迁移(0)，诚实面对接口的可控粒度。

3. 决策由规则引擎做，不让 LLM 自由发挥

plan 子命令纯本地计算（不扣费）：差异分析 → 负迁移保护（参考图某属性质量分低于原图时直接 不迁移）→ 冲突降档（性别/族裔冲突时中身份层自动降档防换脸）→ 产出结构化 Edit Plan。

4. 重试策略表（lib/policy.py）

失败模式 → 参数调整的硬编码映射，最多 3 次尝试：

硬中止：VLM 评身份相似度 ≤4 或 ArcFace < 0.55 时立即停，不再烧钱重试。降级跨轮累积（plan 写回 RunState）。

命令速查

推荐流程：analyze → plan（人工过目 Edit Plan）→ 确认后 auto。这与"付费前必须用户确认"的硬规则一致。

典型用法

场景一（推荐）：闭环自动精修

# ① 分析双图（小额 VLM 费用）
python3 "$SKILL_PATH/scripts/refine.py" analyze \
  --ref 参考图.png --target 原图.png --task demo

# ② 本地出 Edit Plan，人工过目（不扣费）
python3 "$SKILL_PATH/scripts/refine.py" plan \
  --analysis ~/WorkBuddy/ArkGen/demo/analysis.json \
  --level structure --show-prompt

# ③ 确认后跑完整闭环（生成+验证+重试，最多 3 次尝试）
python3 "$SKILL_PATH/scripts/refine.py" auto \
  --analysis ~/WorkBuddy/ArkGen/demo/analysis.json \
  --level structure --yes

场景二：只想要决策，自己执行

python3 "$SKILL_PATH/scripts/refine.py" plan \
  --analysis analysis.json --level structure \
  --prompt "只要光影和肤质，脸别动" --show-prompt

意图解析会把"脸别动"落为显式约束（脸型/下颌线等中身份属性全部强制不迁移），"修眼睛"会被强身份层拒绝并告警。
注意：意图解析只认明确属性词（光影/肤色/脸型等），不含裸词"脸"——"脸部光照"指的是光照而非脸型，避免脸型被静默迁移。要精确控制某属性档位用 --attr 属性 --attr-strength 1-3。

场景三：一张参考图批量修多张原图（v2.4.0）

# 完整闭环批量（每张最多 3 次尝试，最坏约 2 元/张）
python3 "$SKILL_PATH/scripts/refine.py" batch \
  --targets 原图1.jpg 原图2.jpg 原图3.jpg \
  --ref 参考图.png --level structure --size original --task 批量修图 --yes

# 低成本预览档：每张只出一轮（成本约 1/3），满意后对不满意的挑出来单独跑 auto
python3 "$SKILL_PATH/scripts/refine.py" batch \
  --targets 原图1.jpg 原图2.jpg --ref 参考图.png \
  --level structure --size original --max-attempts 1 --yes

要点：每张原图独立做两两对比分析，迁移计划自适应（某张图某属性已接近参考图就自动少迁移一项）——这是特性不是漂移；要整套统一口径就锁定相同 --level + 相同 --attr 白名单。--size original 时各张跟随各自原图像素。失败隔离：单张分析失败或硬中止只记入汇总，不中断整批。输出 <task>/batch-<时间戳>/，含每张独立 run 目录与 batch.json 汇总。

场景四（legacy）：v1.x 直出，行为不变

python3 "$SKILL_PATH/scripts/refine.py" refine \
  --ref 参考图.png --target 待精修图.png --mode style \
  --preset 日系剧场版写实动漫 --size 2048x2048 --yes

精修等级（3 级）

首次使用

1. 依赖

Python 3 + requests。WorkBuddy 受管环境示例：~/.workbuddy/binaries/python/envs/default/bin/python（缺包时 pip install requests，勿污染全局环境）。可选：insightface + opencv（ArcFace 精确身份比对）。

2. 配置 Key（仅限开发者自部署本地管线；付费买家无需此步）

> 付费买家请忽略本节——走「买家调用指引」的付费服务即可，无需任何 Key。以下仅适用于持有火山 ARK Key、要在本地自行运行精修管线的开发者（费用自负，见声明）。

python3 "$SKILL_PATH/scripts/refine.py" init --api-key sk-你的Key

Key 读取优先级：--api-key > ARK_API_KEY 环境变量 > ~/.ark/config.json。

3. 验证（不扣费）

python3 "$SKILL_PATH/scripts/refine.py" list-modes
python3 "$SKILL_PATH/scripts/refine.py" policy      # 看重试策略表
python3 "$SKILL_PATH/scripts/refine.py" models

硬性规则：付费调用前必须用户确认

任何真实扣费的提交（analyze / auto / batch / verify / refine），执行前必须先向用户展示完整命令、所用模式、模型、张数、尺寸与参考费用估算，获得明确同意后才能加 --yes（脚本强制拦截，无 --yes 退出码 6）。

• 免确认操作：plan --analysis / show-prompt / list-modes / policy / models / init
• 费用估算：2K（2048x2048）约 0.6 元/张，1.5K（1536x1536）约 0.3 元/张；VLM 分析每次约几厘（以火山计费中心为准）
• auto 每次重试都扣费——这就是为什么重试上限和硬中止必须存在
• 输出尺寸：扩散模型会整体重绘画面，输出尺寸由 API 的 size 参数决定、不会自动继承原图。要求"原图像素尺寸不变"时必须传 --size original：脚本按原图宽高比生成（≈400 万像素），出图后自动重采样回原图精确像素（lib/executor.py resolve_original_size / resize_to_exact）。直接用默认 2048x2048 会把竖图变方图。

核心机制

1. 图序约定：原图恒为第 1 张，参考图依次排后，提示词统一「原图 / 参考图」术语。
2. 七段编译：Edit Plan 编译为「图序 → 任务目标 → 身份保护 → 修改内容 → 保持不变 → 参考图作用 → 输出要求」七段提示词（lib/compiler.py）。Edit Plan 是决策语言，Prompt 只是执行语言。
3. 同步接口：POST /images/generations 同步返回，直接下载到 output_dir/<task>/refine/。
4. 可追溯：每轮尝试写 task.json / run.json（含最终 plan、评分、参数），run 目录归档可复现。
5. 人物修图四原则：五官锁身份，轮廓做迁移，幅度可控制（3 档枚举），结果做校验（VLM 三维 + 可选 ArcFace）——v2 起四原则全部有代码落地，不再是文档口号。

常见故障

项目结构

seedream-refine/
├── SKILL.md
├── scripts/
│   ├── refine.py                # 薄 CLI：analyze/plan/auto/batch/verify + legacy 四命令
│   ├── aipay_server.py          # ★ A2M 按量付费资源服务（402 → 验付 → 履约确认）
│   └── lib/
│       ├── config.py            # Key / 模型 ID / base_url
│       ├── ark.py               # 方舟 HTTP 客户端（chat+images）
│       ├── models.py            # legacy 七段式模式模板资产（v1 保留）
│       ├── matrix.py            # ★ 身份迁移矩阵：四层模型 + 3 档枚举 + 层级封顶
│       ├── analyzer.py          # ★ VLM 双图分析（属性 + 质量分 + 意图解析）
│       ├── planner.py           # ★ 规则引擎：差异→负迁移保护→冲突降档→Edit Plan
│       ├── compiler.py          # ★ Edit Plan → 七段式提示词
│       ├── executor.py          # 图片生成执行
│       ├── validator.py         # ★ VLM 三维打分 + 可选 ArcFace
│       ├── policy.py            # ★ 重试策略表（失败模式→参数调整→收敛上限）
│       ├── aipay.py             # ★ A2M 核心：账单签名 / 验付 / 履约确认
│       └── aipay_store.py       # ★ A2M 订单库（SQLite：幂等履约 + 防串单）
├── tests/                       # unittest 回归（python3 -m unittest discover -s tests）
└── references/
    ├── mode-library.md          # legacy 7 模式完整提示词模板
    ├── prompt-principles.md     # 参考图修图 Prompt 设计原则
    ├── portrait-refine.md       # 人物修图方法论
    └── style-presets.md         # 风格预设完整文本

AI 按量付费资源服务（Pay Skill）

本 skill 内置 A2M（支付宝 AI 按量付费）服务端，可把「单张参考图精修」发布为按次收费的 HTTP 资源（SkillHub SkillPay 改造规范）。协议只含三步：402 出账 → payment.verify 验付 → fulfillment.confirm 履约确认，不含通用收单。

服务端（卖家，部署一次）

• 启动：python3 scripts/aipay_server.py --host 127.0.0.1 --port 8080 --price 1.00（外层套 nginx HTTPS 反代 + 限流）
• 前置：支付宝开放平台签约「AI 按量付费」→ 服务注册拿真实 serviceId（API_ 开头）；生产配置环境变量两套命名均可——SkillHub 教程命名 AIPAY_APP_ID / AIPAY_PRIVATE_PKCS_KEY / AIPAY_ALIPAY_PUBLIC_KEY / AIPAY_SELLER_ID / AIPAY_GATEWAY / AIPAY_SERVICE_ID，或等价旧名 ALIPAY_*（见 lib/aipay.py）；私钥用 PKCS#1 格式（非 Java）
• 订单库：SQLite，默认 ~/.alipay_aipay/aipay_orders.db；沙箱配置文件存在时优先生效，生产机不要放置 .alipay-sandbox.json

Agent 调用（买家侧）：见「买家调用指引」章节——含首次调用前的支付能力检查与支付后四步。

> 发布状态（2026-09-08）：① 服务地址已落定为 https://aipay.agentdayi.cn；② 已完成一笔第三方真实交易的线上验证（aipay.alipay.com 接入成功）。服务端代码可随包分发（买不到密钥——配置全在部署机环境变量，不入库不入包）。

更新记录

• v2.4.9：买家体验重塑——① description 去除"需自备 ARK Key"旧门槛（付费买家无需任何 Key，算力含在服务定价内），description 明示按次付费定位与宿主要求；② 新增「买家调用指引」章节：首次调用前必做支付能力检查（宿主无支付宝 AI 付能力时明确告知用户，不出账单不找变通），支付后四步从 Pay Skill 章节合并至此；③ 本地管线降级为"开发者自部署选项"，付费服务成为默认路径。
• v2.4.8：品牌重塑为「锁颜师 · 参考图精修」，slug 更换为 suoyanshi（首次发布用旧 slug 的 listing 独立存在，互不影响），新配锻造工作台风图标；能力、接口与 A2M 收款配置无任何变化。
• v2.4.7：技能更名为「修颜匠 · 参考图精修」（slug 保持 seedream-refine 不变），配套发布图标；声明段新增版权与禁止二次分发条款；能力与接口无任何变化。
• v2.4.6：A2M 线上验证通过（aipay.alipay.com「接入成功」），正式发布就绪。两点平台侧实测经验：① 支付宝有两层交易号——payment.verify 返回的 32 位是 AI 付协议层交易号，商家中心「我卖出的交易」展示的是 28 位结算层交易号，AI 付站点线上验证只认后者（填错层号报「未查询到交易」）；② 线上验证与常规列表会过滤同主体自付交易，验证必须用不同主体的真实付款。服务地址占位符替换为公网地址。
• v2.4.5：真实付款验付打通当日两处根因修复——① SDK 响应形态误判：alipay-sdk-python 的 execute() 返回的是剥离响应节点外壳的内层扁平 JSON（DefaultAlipayClient.__parse_response 只截取节点内部对象），此前按官方文档假设完整包裹结构、只认 alipay_aipay_agent_payment_verify_response 嵌套节点，导致支付宝返回 Success + 全部契约字段全对仍被误判为"无响应节点"→ 验付失败回 402（真实事故：同一凭证验付实际通过却被重复出账）。新增 _extract_response 兼容三种形态（业务节点 → error_response → 内层扁平），verify 与 fulfillment.confirm 两处统一；② 已付订单被付款截止期阻断：验付期间 pay_before 已过 → prepare_fulfillment 拒绝已真实付款的订单。新增 store.mark_paid()，验付通过、契约校验后即落 PAID，pay_before 从此只约束未支付订单。tests/test_aipay.py 19 例。
• v2.4.4：A2M 上线首日实战修复三处——① 验付接口异常原来无日志直接 500（真实事故：私钥误用 PKCS#8 格式导致 SDK 请求签名抛异常，仅能在响应体看到错误），改为 stderr 详细日志 + 显式 502 PAYMENT_VERIFY_FAILED（幂等凭证可重试），验付结果（通过与否，不含凭证内容）落日志；② 安全 R1 收口：target/ref 仅接受 https:// URL 或 data: URI，拒绝本地路径与其他协议（此前代码与 SKILL.md「服务端不接受本地路径」声明不一致，存在任意文件读取风险）；③ 安全 R2：过期未支付订单自动清理（启动时 + 每 6 小时，过期超 24h 才删，已进入履约的订单保留对账），防 402 探价订单无限膨胀。tests/test_aipay.py 16 例。线上实战定位结论：非 Java 服务必须用 PKCS#1 私钥，pycryptodome 两种格式都认而支付宝 SDK 不认——账单签名正常但验付必挂，是最隐蔽的坑。
• v2.4.3：集成支付宝 AI 按量付费（A2M），对接 SkillHub SkillPay 改造规范——新增 scripts/aipay_server.py（HTTP 资源服务：/aipay/refine 单张精修 + /aipay/health，402 出账 → payment.verify 验付 → fulfillment.confirm 履约确认）、scripts/lib/aipay.py（账单 RSA2 本地签名、验付、履约确认、沙箱/生产配置加载）、scripts/lib/aipay_store.py（SQLite 订单库：402 前落单、原子认领、幂等履约、trade_no 唯一索引防串单、崩溃恢复）；tests/test_aipay.py 15 例。生产配置兼容 SkillHub 教程命名（AIPAY_*）与 ALIPAY_* 旧命名。计费口径：一单 = 一次单张精修（1 次 VLM 分析 + 1 张出图），无重试闭环；ARK Key 缺失时 503 不出账单不收钱。
• v2.4.2：修复三处——① estimate_cost 的 max(1, batch) 使 analyze/verify（纯 VLM、0 张出图）在付费确认时虚报 0.60 元出图费，改为按实际张数计（0 即 0）——「付费前展示真实费用」硬规则的口径修正；② 测试硬编码部署路径 ~/.workbuddy/skills/... 导致本地改动永远测不到，改为基于 __file__ 相对路径并迁移 unittest 风格（python3 -m unittest discover -s tests 可用，20 例全过）；③ 意图解析裸词「嘴」过度触发（「嘴角的光影」被误判为嘴型并告警），改为 嘴型/嘴唇/嘴巴 精确词，与 v2.1.0 裸词「脸」同例。新增 tests/test_analyzer.py 固化意图解析回归。
• v2.4.1：新增 --preserve（点名保留属性，强制不迁移）——意图解析只有"点名迁移"没有"点名保留"，用户说"保持黑发"时发型仍会被自动计划迁走（实测）。--preserve hair 在规则引擎里以最高优先级硬锁定该属性（高于 force_attrs/意图解析/自动差异分析），plan/auto/batch 三个子命令均支持。
• v2.4.0：新增 batch 子命令——一张参考图批量精修多张原图。每张独立两两对比分析 + 独立闭环（plan 自适应各张差异），失败隔离（单张异常只记入汇总，不中断整批），结束输出汇总表与 batch.json。--max-attempts 1/2/3 可按张降低尝试上限（1 = 低成本预览档，成本约 1/3）。RunState 支持按次运行覆盖 max_attempts（默认仍为 3，行为不变）。闭环核心从 cmd_auto 抽为 _auto_loop 供 auto/batch 复用。注意：VLM 两两对比分析无法拆分缓存（v2.3.0 实证教训），参考图每张都要参与分析调用，批量成本随张数线性增长。
• v2.3.1：首轮尝试使用显式随机种子并记录到 run.json（此前首轮 API 端随机、无法复现）；auto 结束自动生成 原图|结果 并排对比图 compare.png（Pillow，失败不影响主流程）；验证层新增第 4 维 scene 场景保持度（观测项，只记录不参与通过判定——场景漂移暂无对应的重试调整动作，先观测）。决策层/分析层测试固化 tests/test_planner.py。
• v2.3.0：分析层 v2——逐属性两两相对对比替代绝对分差推档（实证：v1 的 5 分制被 VLM 压缩到只有 ±1 分辨率，"分差≥2→中档"从未触发）。comparison 输出 direction（reference_better/original_better/tie）× degree（much/moderate/slight），三程度直接映射 3 档枚举；v1 analysis.json 无 comparison 时自动回退分差推算。验证层升级三图判卷（原图+参考图+结果）：goal 维度改为「是否朝参考图方向改善」，identity 判卷锚定原图人物、明确把"五官向参考图靠拢"判为换脸重罚——实测打分从 10/10/10 校准到 7/8/10。新增强制迁移告警（点名属性但参考图并不更好时提示负迁移风险）；HTTP 5xx 纳入自动重试（服务端明确失败、无重复计费风险）。
• v2.2.0：新增 --size original（原图尺寸跟随）——扩散模型输出尺寸永远由 API size 参数决定、不会继承原图，此模式按原图宽高比生成（≈400 万像素）后用 sips 精确重采样回原图像素（executor.resolve_original_size / resize_to_exact，重采样后自验证尺寸，不符抛错）；伪影重试的降尺寸支持自定义非方形尺寸（等比 ×0.75）；run.json 记录 size_requested / gen_size / final_dims；回归测试归位 tests/test_policy.py（8/8）。用户图片管理约定：收图第一动作 cp 到 ~/WorkBuddy/ArkGen/originals|references/，微信 RWTemp 临时路径按小时失效。
• v2.1.0：新增 --attr-strength 1/2/3（点名属性直接定档，绕过分差推算）；修复意图解析裸词「脸」过度触发（"脸部光照"会误迁移脸型）；补充 光照/采光/肤色 关键词；适配 doubao-seedream-5-0-pro-260628 不支持 guidance_scale 的问题（重试自动跳过 guidance 调整）；修复 analyze 命令 args.size 崩溃。
• v2.0.0：架构重构为「分析→决策→编译→执行→验证→重试」完整闭环。新增 lib 模块层（matrix/analyzer/planner/compiler/validator/policy/executor）、analyze/plan/auto/verify 四个子命令、身份四层模型、3 档强度枚举、负迁移保护、冲突自动降档（性别/族裔冲突防换脸）、重试策略表与硬中止、run.json 归档。legacy refine/show-prompt 行为保持 v1.x 不变。
• v1.3.0：移除 character（角色一致性/身份替换）模式，避免与 face（保身份改轮廓）语义混淆；现有模式收敛为 7 种。
• v1.2.0：新增 face 模式 + --strength + --face-part，落地人物修图原则；新增 references/portrait-refine.md。
• v1.1.0：按「参考图修图 Prompt 设计原则」重写 7 种模式提示词（七段结构）；新增 references/prompt-principles.md。
• v1.0.0：首个版本。7 种模式、5 组风格预设、show-prompt 不扣费预览、付费确认 + 费用估算。