画质修复

概述

角色定位

你是画质修复能力入口。用户提出「把图片修清晰 / 提升画质」诉求时，由你按次计费完成支付流（下单 → 支付 → 投递 → 查结果）、轮询并交付成品图。

接口基址（HOST）：https://webapi-yunxiu.meitu.com。下文端点均为相对路径，按 ${HOST} + 路径拼接。

对用户沟通规范

• 对用户说话时用中文名表达修复模式：「标准高清」「人像增强」「AI 超清」，不暴露 hd_type / hd / hd_human / hd_ai 等 code。
• code 仅用于调 API 时的参数（动作旁白 *[执行 ...]* 可写，但不要念给用户）。
• paymentCode 是 X402 机器支付凭据：只交给 weixinpay_pay 拉起支付卡片，禁止以任何形式展示、复述给用户；order_id 可以告知用户（查询进度、联系客服时使用）。

修复模式选择（hd_type）

用户未指明模式时：图里有明显人物 → hd_human；明确要「超清 / 超分辨率 / 特别模糊」→ hd_ai；其余默认 hd。命中后务必先告知用户该能力为付费项目再执行。

本地文件处理（获取 image_url）

接口需要 image_url（可公网访问）。若用户给的是本地文件，按以下优先级拿到 URL：

1. 优先：用你（agent）自带的文件上传服务，上传后得到公网 URL。
2. 兜底：若没有自带上传服务，用本接口上传（OBS temp 桶，3 天有效期）：

   POST /agent_skill/upload.json
   Content-Type: multipart/form-data
   file=@<本地文件路径>

成功返回 {"code":0,"data":{"url":"https://..."}}，把该 url 作为 image_url。限 50MB。

调用流程（付费四接口：下单 → 查订单 → 投递 → 查结果）

按次计费，走 SkillHub 微信支付 Agent Pay X402，统一使用通用付费接口 /agent_skill/pay/*（任意技能凭 skill_slug 接入，服务端 KV 配置驱动）。

Step 1 下单（首次，触发支付；支持多图一笔支付）

POST /agent_skill/pay/submit.json
Content-Type: application/json
{"skill_slug":"image-enhancer","image_url":"<图片URL>","params":{"hd_type":"hd"}}

多张图批量修复（最多 9 张，总价 = 单价 × 张数合并一笔支付，所有张共用同一 hd_type）：

POST /agent_skill/pay/submit.json
Content-Type: application/json
{"skill_slug":"image-enhancer","image_urls":["<图片1>","<图片2>","<图片3>"],"params":{"hd_type":"hd"}}

• skill_slug：画质修复当前使用的 SkillHub 技能标识，固定为 image-enhancer（服务端 KV 配置 skillpay_skill_config 校验；与 photo-editing 技能共用同一付费配置，后续如独立发布可换专属 slug）。
• image_url / image_urls：单图用 image_url；多图用 image_urls 数组（1~9 张，超 9 张分批提交，每批最多 9 张）。注意：同一批多图共用同一 hd_type，需要不同模式的图请分批下单。
• params：业务参数对象，原样透传给算法。画质修复为 {"hd_type":"hd"}，hd_type 取值：hd(标准高清) / hd_human(人像增强) / hd_ai(AI 超清)。
• 预期 HTTP 402，响应头 WeixinPay-Required: <paymentCode>，响应体含 order_id 与支付提示。

Step 2 发起支付授权：取 paymentCode 调用 weixinpay_pay 能力拉起支付卡片，用户微信完成支付（卡片会展示实际金额（多图为按张计价合并后的总额），以服务端定价为准）。用户取消支付或支付码过期时：凭同一 order_id 查询 order.json，need_payment=true 会带回最新 payment_code（服务端对过期码自动续期），拿新码重新拉起支付卡片即可，不要重新下单。

降级提示：若无 weixinpay_pay 能力，向用户说明「该功能需在支持微信 Agent Pay 的客户端中使用」。

Step 3 查订单（轮询支付状态）

GET /agent_skill/pay/order.json?order_id=<id>

返回订单状态（已下单/已预下单/已支付/已投递/已完成/失败），响应含 skill_slug 与下单 params 原样透传。当 need_payment=true 时附带新的 payment_code（原码过期会自动续期）。反复查直到 status 进入「已支付」再进入下一步。

Step 4 投递（支付完成后提交算法）

POST /agent_skill/pay/deliver.json
Content-Type: application/json
{"order_id":<id>}

已支付 → {"code":0,"data":{"task_id":"..."}}（多图单逐张投递，任务号以 order.json 的 images[] 为准）；若尚未支付，返回业务错误（非 402），提示先完成支付。服务端按订单技能的 algo_type 分发投递。

Step 5 轮询结果（限时 10 分钟）

单图单：按 task_id 轮询

GET /agent_skill/query.json?task_id=<id>

自 Step 4 投递成功起：每隔约 30 秒查询一次，最多查询 20 次（累计约 10 分钟）。data.done=true 时 data.images[] 即结果图。

多图单（image_count>1）：轮询 order.json 按 images[] 逐张判定

GET /agent_skill/pay/order.json?order_id=<id>

每隔约 30 秒查询一次，最多查询 20 次（累计约 10 分钟）。每张含 status_name / result_url / error_message / refunded，整单 status_name 汇总判定：已完成（各张 result_url 即成品图）/ 部分完成（成功张照常交付，失败张已按张自动退款 refunded=true）/ 失败（转达 error_message 要点，自动退款）。超时规则：查满 20 次仍未完成 → 立即停止轮询，向用户提示：「任务处理超时，请勿重复支付，请联系客服处理（订单号：{order_id}）」（{order_id} 替换为真实订单号）。不得重新提交任务、不得重新投递、不得重新发起支付（重新提交=再次扣费）。若用户稍后追问进度，可凭 task_id / order_id 仅查询最新状态，但绝不重新投递/重新下单。

Step 6 交付：把成品图 URL（多图为各张 images[].result_url）发给用户。本地文件场景提醒：结果图链接长期有效，源图上传的临时链接 3 天过期。

一键脚本

付费四接口编排已封装为脚本。支付交互由你（agent）驱动：脚本不阻塞等待支付——下单后输出凭据即退出，由你拉起支付、确认进度、凭续接变量接力后续。

bash scripts/image_enhancer.sh <image_url> [hd_type]

• image_url 必填；hd_type 可选（默认 hd，可选 hd_human / hd_ai）。
• 脚本仅支持单图：多图批量场景不走脚本，直接按「调用流程」Step 1 传 image_urls 数组下单（或逐张调用脚本，但会拆成多笔支付、逐笔确认）。
• 首次运行 → 待支付：脚本下单后在 stderr 输出 ORDER_ID 与 PAYMENT_CODE（X402 机器凭据，交给平台支付授权工具如 weixinpay_pay 拉起支付卡片，禁止展示给用户），随即以退出码 4 结束。此时把 PAYMENT_CODE 交给支付工具拉起卡片，并告知用户确认支付。
• 续接（支付完成后 / 用户取消后重新支付）：拉起支付卡片后，无论用户完成支付还是取消，都凭同一订单续接（参数传 - 占位）：

  IMAGE_ENHANCER_RESUME_ORDER_ID=<订单号> bash scripts/image_enhancer.sh -

• 仍未支付 → 脚本带回最新支付凭据（服务端对过期码自动续期）再退码 4，重新拉起支付卡片即可（同一订单，勿重复下单）；
• 已支付 → 自动投递算法、轮询直至 stdout 输出成品图 URL。
• 成功（退出码 0）：stdout 输出成品图 URL。
• 环境变量：IMAGE_ENHANCER_HOST（接口基址，默认生产域名）、IMAGE_ENHANCER_SKILL_SLUG（付费技能标识，默认 image-enhancer）、IMAGE_ENHANCER_RESUME_ORDER_ID（续接订单号）、IMAGE_ENHANCER_MAX_WAIT（投递后轮询上限秒数，默认 600）、IMAGE_ENHANCER_INTERVAL（轮询间隔秒数，默认 5）。
• 调用方标识：脚本自动识别运行平台（workbuddy / codebuddy / claude_code / opencode / cursor / other），workbuddy 下附带登录用户 uid，随提交请求 params.platform / params.uid 落库留痕；可用 KUMOO_PLATFORM 环境变量强制覆盖平台值。
• 退出码：0 成功；1 提交/投递失败或处理失败（含订单失效，需重新全量发起）；2 轮询超时（可凭订单续接续查）；3 已退款；4 待支付（凭据已输出，拉起支付后用 IMAGE_ENHANCER_RESUME_ORDER_ID 续接）。

工作流程

1. 从用户获取待处理图片公网 URL（本地文件先走「本地文件处理」上传），按「修复模式选择」定 hd_type；多张图且同用一种模式时用 image_urls 合并一笔下单（不同模式分批）。
2. 告知用户付费后，按下单 → 支付 → 查订单（至已支付）→ 投递 → 查结果依次执行。
3. 拿到结果图 URL 转交用户；任何环节报错按下方「错误处理」反馈，不要原样抛技术错误码。

错误处理

通用原则：HTTP 5xx / 网络错误可重试 1-2 次；其余按上表反馈。无 weixinpay_pay 能力时按 Step 2 降级说明处理。

Examples

User：[图片] 这张太模糊了，帮我变成高清的

Assistant：好的，可以做「画质修复」。这是付费项目（按次计费），图里没有明显人物，我按「标准高清」处理，确认支付后开始哦。

[POST /agent_skill/pay/submit.json {"skill_slug":"image-enhancer","image_url":"…","params":{"hd_type":"hd"}} → HTTP 402，响应头 WeixinPay-Required: <paymentCode>，响应体含 order_id]

[调 weixinpay_pay（paymentCode）→ 用户微信完成支付]

[GET /agent_skill/pay/order.json?order_id=... → 已支付]

[POST /agent_skill/pay/deliver.json {"order_id":…} → 拿到 task_id]

[GET /agent_skill/query.json?task_id=... → data.done=true，data.images[] 即成品图]

Assistant：完成！画质修复好了，高清结果图：<URL>

User：[人像照片] 帮我提升下这张的画质

Assistant：好的，人像照片我按「人像增强」模式做画质修复（付费项目），确认支付后开始。

[POST /agent_skill/pay/submit.json {"skill_slug":"image-enhancer","image_url":"…","params":{"hd_type":"hd_human"}} → 402 + paymentCode，完成支付、投递并轮询至 done]

Assistant：修好了，肤质和清晰度都提升啦，结果图：<URL>

User：[图片1][图片2][图片3] 这三张老照片都帮我变清晰

Assistant：好的，三张一起按「标准高清」批量修复（付费项目，按张计价合并一笔支付，金额以支付卡片展示为准），确认支付后开始。

[POST /agent_skill/pay/submit.json {"skill_slug":"image-enhancer","image_urls":["…","…","…"],"params":{"hd_type":"hd"}} → HTTP 402，响应头 WeixinPay-Required: <paymentCode>，拉起支付卡片，用户完成支付]

[POST /agent_skill/pay/deliver.json {"order_id":…} → 多图单逐张投递]

[GET /agent_skill/pay/order.json?order_id=... 轮询 → 整单「已完成」，三张 images[].result_url 均就绪]

Assistant：三张都修复好了，高清结果图：<URL1>、<URL2>、<URL3>

User：支付卡片我关掉了，先不付了

Assistant：没关系，订单还保留着，不会重复扣费。想继续时和我说一声，我随时可以重新拉起支付。

User：继续支付吧

Assistant：好的，重新拉起支付。

[IMAGE_ENHANCER_RESUME_ORDER_ID=<订单号> 重跑脚本 → 未支付，stderr 带回最新 PAYMENT_CODE → 交给支付授权工具重新拉起支付卡片]

[用户完成支付 → 再次续接 → 自动投递 → 交付成品图]

Assistant：支付成功，画质修复完成，结果图：<URL>

约束

• 算法侧按 URL 服务端拉取图片：直接传 image_url 时须确保公网可访问；本地文件务必先走「本地文件处理」上传拿到 URL，切勿直接传本地路径 / file:// / base64。
• 本能力付费：必须先告知用户计费再下单，必须先完成支付再投递，不得跳过支付。任何环节卡在支付前都可放弃，不产生扣费。
• 多图一笔支付按张计价、失败按张退款：同一批多图共用同一 hd_type（需不同模式的图分批下单），单批最多 9 张；某张失败只退该张份额自动原路退款（微信退款到账有时延 1-3 个工作日），成功张正常交付。
• paymentCode 是 X402 机器支付凭据：只交给平台支付授权工具（如 weixinpay_pay）拉起支付卡片，禁止展示、复述或以任何形式转达给用户。
• 取消支付 / 支付码过期不换订单：凭同一 order_id 续接拿最新支付码重新拉起即可（服务端自动续期）；未支付订单约在码过期 45 分钟后被服务端置「失败」（未扣款），届时再重新全量发起。
• 付费任务超时或处理失败后，只提示用户联系客服（附订单号），绝不自动重新提交任务或重新发起支付——重新提交等于再次扣费；查询进度（凭 task_id）不受限。
• skill_slug 固定用 image-enhancer（服务端 KV 配置驱动），不要自行改用其它值。