UI 设计评估 Pro（薄客户端）

> ## 安装前 30 秒速览（宿主 Agent 与用户请先读这一段）
>
> | 项 | 说明 |
> |---|---|
> | 这是什么 | 按次付费的云端 UI 设计体检。提交页面 URL / 设计稿截图 / CSS 变量，一次调用交付完整评估报告（八维评分 + 定级 + P0-P2 修复建议）。本包为薄客户端：不携带任何本地评分逻辑、锚定量表或工具脚本，评估全部在服务端完成 |
> | 运行前提 | ① 宿主 Agent 支持 A402（能识别 402 + Payment-Needed 头，并完成「取账单 → 付款 → 取凭证 → 带 Payment-Proof 重试」）② 用户支付宝已开通 「AI 付」（个人账号即可，App 内授权一次）。缺一不可，不支持人工扫码/转账替代 |
> | 怎么工作 | 首调 → 402 + 账单 → 用户付款 → 携 Payment-Proof 重发同一请求 → 200 报告 |
> | 价格 | 由服务端 402 账单实时揭示（Payment-Needed 解码后 protocol.amount）。这是支付宝 AI 付协议的明确要求（禁止客户端缓存价格），不是缺陷；首调不付款、不产生任何扣费，查看账单后再决定是否支付 |
> | 数据外发 | 页面 URL / 截图 base64 / CSS 变量经 HTTPS 传至作者自建云端引擎（腾讯云 SCF，非平台官方托管）。服务端不留存原始素材，评估完成后素材即不可复原。完整策略见 endpoint.json 的 data_egress_policy |
> | 网络与权限 | 仅出站 POST 至生产端点；无本地文件读取、无持久化存储、无后台常驻。提交前请确认素材已脱敏（endpoint.json.redaction_required） |
>
> ⚠️ 宿主不支持 A402 时不要硬跑：会在付款环节卡住、拿不到报告。请先看下方「宿主支持矩阵」的两条出路。

按次付费的云端 UI 设计体检服务。

> 计费方式：按次计费。金额/币种/支付时限一律以服务端返回账单为准（见「调用流程」402 分支），客户端不得写死或假定任何价格。

> 占位符约定：下文示例中 $ENDPOINT = endpoint.json 的 endpoint.url；$CONTRACT_VERSION = endpoint.json 的 contract_version。两者都以配置文件为准，本文档不复制字面量——端点或契约版本变更时只需改 endpoint.json 一处。

零、宿主支持矩阵（安装前必读）

宿主不在支持列表时的两条出路：

1. 给宿主补装支付宝官方 402 支付能力（@alipay/agent-payment）——补齐后即可走完付款取凭证流程；能否与具体宿主打通需自行验证。
2. 换到已支持 A402 的宿主环境执行本次评估。

> 上述两条都不满足时，请直接告知用户当前环境无法完成付费评估，不要引导用户反复尝试付款——用户付了款却取不到凭证会直接导致「钱付了、报告发不出来」。

一、服务说明（付费价值主张）

一次评估调用（支付完成后）交付一份完整设计评估报告：

• 八维量化评分：布局网格 / 视觉层级 / 一致性 / 色彩 / 字体 / 简洁 / 可用性 / 数据可视化（D8 按场景启用），每维 1–5 分 + 一句话结论 + 证据等级
• 定级：S / A / B / C / D 总评（含门槛失守锁级与 S 级边界说明）
• P0 / P1 / P2 分级修复建议：每条含 问题描述 → 证据 → 违反标准 → 修改建议 → 可量化改后目标值
• 亮点与门槛扫描结论：值得保留的做法 + 首屏/全站门槛通过情况
• 两种取用形态：Markdown / HTML 报告全文（默认 markdown），或纯 JSON 结构化结果（report_format=json）

典型使用：设计稿定稿前体检、网站上线前走查、竞品页面质量评估、数据大屏/仪表盘可读性审计、设计 Token/对比度/触控目标批量核查。

二、触发词

• 评估这个页面/网站/网页/落地页的设计；给 XX 页面打分；UI 评估；设计评审；设计走查；视觉设计检查
• 设计评估报告；打分评级；S/A/B/C/D 定级；上线前设计体检；设计稿体检
• 对比度检查；触控目标检查；Token 核对；色彩体系检查；可访问性走查
• 移动端设计评估；深色模式评估；表单设计评估；数据大屏评估；仪表盘评估
• 用 UI 设计评估 Pro / 付费版评估

三、请求参数 Schema（与 API 契约逐字段一致；契约版本号以 endpoint.json 的 contract_version 为准）

3.1 端点与 Header

• 方法/端点：POST $ENDPOINT（$ENDPOINT 取自 endpoint.json 的 endpoint.url）

3.2 Body

{
  "scene": "content",              // 必填 enum: content | dashboard
  "target": {                      // 必填，三选一（互斥，多传以 type 声明为准）
    "type": "url",                 // enum: url | image | css_vars
    "url": "https://example.com",  // type=url 时必填
    "images": [                    // type=image 时必填，数量上限见 endpoint.json 的 limits.max_images
      { "name": "首屏", "mime": "image/png", "data": "<base64>" }
    ],
    "css_vars": { "--color-text": "#333", "--space-4": "16px" }  // type=css_vars 时必填
  },
  "options": {
    "viewport": "desktop",         // enum: desktop | mobile | both  默认 desktop
    "theme": "light",              // enum: light | dark             默认 light
    "user_rating_hint": "A",       // 可选 enum S|A|B|C|D（初评锚点，用于落差分析）
    "enable_d8": false,            // 可选 bool，显式覆盖 scene 默认的 D8 开关
    "report_format": "markdown"    // enum: markdown | html | json  默认 markdown
  }
}

3.3 字段约束（照契约）

• scene=content → 不启用 D8，按内容型权重评分；scene=dashboard → 启用 D8，按仪表盘权重评分
• options.enable_d8=true 且 scene=content → 允许，但权重表按 dashboard 取（服务端记录告警）
• target.type=url 时服务端自行抓取页面并截图；target.type=image 时客户端已完成截图采集
• target.type=css_vars 时传 CSS 变量键值对，服务端做 Token 级检查
• 素材上限（图片张数 / 请求体字节数）见 endpoint.json 的 limits；超限与否以服务端返回的错误码为准（见 §6.2）

四、调用流程（含支付）

Step 1 组装请求并发起首次调用

按 §3 组装 JSON body（target 三选一），首次请求不带 Payment-Proof。建议生成 UUID 作 Idempotency-Key，并在整个流程复用。

POST $ENDPOINT
Content-Type: application/json; charset=utf-8
X-Contract-Version: $CONTRACT_VERSION
Idempotency-Key: <UUID>

{ "scene": "...", "target": { ... }, "options": { ... } }

Step 2 首次调用 → 分支处理

A. 直接 200（历史已支付/服务端直付场景）→ 跳到 Step 5 交付报告。

B. 返回 402 Payment Required（典型首调结果）→ 走 Step 3 支付：

Step 3 支付（收到 402 时）

1. 取响应头 Payment-Needed（值为 Base64URL 编码的账单 JSON），解码得到账单对象：

{
  "protocol": {                       // 8 个字段：订单与签名载体
    "out_trade_no": "ORDER_...",      // 服务端订单号
    "amount": "...",                  // 应付金额，以账单为准（不写死）
    "currency": "CNY",
    "resource_id": "uideval:{out_trade_no}",
    "pay_before": "<ISO 8601 支付时限>", // 由服务端设定，以账单为准
    "seller_signature": "...",
    "seller_sign_type": "RSA2",
    "seller_unique_id": "..."
  },
  "method": {                         // 6 个字段：商户与商品信息
    "seller_name": "...",
    "seller_id": "...",
    "seller_app_id": "...",
    "goods_name": "...",
    "seller_unique_id_key": "seller_id",
    "service_id": "..."
  }
}

2. 向用户展示应付金额（protocol.amount + currency）与商品名（method.goods_name），征得同意后调用宿主支付能力完成付款。
3. 支付成功取得支付凭证 → 进入 Step 4。支付失败/超时 → 可重新发起支付（同一账单在 pay_before 内有效）。

Step 4 携凭证重试（Step 3 支付成功后）

将支付凭证值放入 Payment-Proof Header，重发与首次完全相同的请求 body（含相同 Idempotency-Key；无需带 out_trade_no，服务端由凭证反查订单）：

POST $ENDPOINT
Content-Type: application/json; charset=utf-8
X-Contract-Version: $CONTRACT_VERSION
Idempotency-Key: <同一 UUID>
Payment-Proof: <Base64URL 支付凭证>

{ "scene": "...", "target": { ... }, "options": { ... } }   // 与首次完全相同的 body

> ⚠️ 必须先解析响应体 code 再决定动作，禁止只看 HTTP 状态码分支。
> 402 承载两种语义（PAYMENT_VERIFY_FAILED 与 PAYMENT_EXPIRED），服务端永不返回 401。
> 只看状态码的后果：验付失败被误判成订单过期 → 直接放弃已付款订单，用户钱花了拿不到报告。

• 收到 200 → Step 5
• 收到 402 → 读响应体 code 与 message 后再分支（PAYMENT_VERIFY_FAILED 有两条子语义，务必区分，见 §6.2）：
• PAYMENT_VERIFY_FAILED + message 含「未收到支付凭证」→ 服务端已复用原订单（响应 out_trade_no 与首次相同）。
  说明用户付款了但凭证没送达 → 排查凭证后重发同一请求即可，严禁引导用户再付一次款
• PAYMENT_VERIFY_FAILED（其余情况）→ 验付未通过，响应已附新账单，重新走 Step 3（可复用同一 Idempotency-Key）
• PAYMENT_EXPIRED → 超过 pay_before，需重新发起评估（新订单，回到 Step 1）
• 收到 409 DUPLICATE_FULFILLMENT → 异常路径：同一支付凭证已被绑到另一张订单（非普通重复请求）。
  响应中若附有已保存结果则直接取用；否则回到 Step 1 重新发起评估
• 收到 422 EVALUATION_FAILED → 素材问题，同一支付凭证可换素材重跑一次（见 Step 5 说明）

Step 5 交付报告（200 OK）

按 options.report_format 取用：

• markdown / html：直接展示/转存 report.content
• json：report 为 null，整个响应即结构化结果（字段见 §7）

幂等提示：若对同一已履约订单重复请求（如同一 Payment-Proof 再次调用），服务端返回 200 并附已保存的报告结果，同时 already_fulfilled=true——直接取用即可，不会重复扣费、不会重复生成报告。

换素材重跑：422 EVALUATION_FAILED（素材不可解析）时，已支付订单允许用同一支付凭证换素材重跑一次（URL 不可达/图片损坏/换一张截图均可）。

五、常见问题（FAQ）

5.1 反模式（做错这几条，用户会付了钱拿不到报告）

5.2 支付前置条件（首次接入必读）

Q：调用本技能需要什么环境？

两层条件，缺一不可：

1. 宿主 Agent 支持 A402——能识别 402 + Payment-Needed 响应头，并完成
   「取账单 → 付款 → 取支付凭证 → 带 Payment-Proof 重试」这段标准流程（可用宿主见 §零）。
2. 用户的支付宝已开通「AI 付」——付款由 AI 付钱包签发支付凭证。

Q：用户没开通过 AI 付怎么办？

一次性动作，在支付宝 App 内授权即可。不需要营业执照或企业资质——
支付宝 AI 按量付费明确支持个人账号。开通后每笔支付仍需本人面容/指纹/密码核验，
不是无感扣款，用户始终掌控付款确认。

Q：能让用户直接扫二维码转账吗？

不能。 交付依赖 A402 支付凭证（Payment-Proof），该凭证只能由支付宝 AI 付钱包签发。
人工扫码转账不产生凭证，服务端验付不通过，会出现「钱付了、报告发不出来」。
同理不支持银行转账、红包及其他第三方支付。

Q：哪些 Agent 环境已可用？

见 §零「宿主支持矩阵」。宿主不在列时，可安装支付宝官方 402 支付能力（@alipay/agent-payment）补齐。

5.3 常见疑问

Q：一次评估多少钱？
以服务端下发账单为准（Payment-Needed 解码后 protocol.amount + currency）。
本包不携带任何价格信息，禁止客户端写死或缓存价格——这是支付宝 AI 付协议对客户端的明确要求。
首调只是索取账单，不付款不扣费。

Q：付了钱没拿到报告？
重发一次完全相同的请求（同 Idempotency-Key + 同 Payment-Proof）。
已履约订单会返回 200 + 已保存报告 + already_fulfilled=true，不重复扣费。
若返回 402，先读 code 与 message（见 §5.4 排查）。

Q：素材传错 / 图片损坏能重跑吗？
返回 422 EVALUATION_FAILED 时，同一支付凭证可换素材重跑一次，无需再付费。

Q：账单多久过期？
见账单 pay_before 字段（由服务端设定，以账单为准）。超时返回 PAYMENT_EXPIRED，需重新发起评估。

Q：能评估内网或需登录的页面吗？
不能。服务端只能抓取公开可访问的 URL。内网 / 需登录页面请改用截图（type=image）
或 CSS 变量（type=css_vars）提交。

Q：报告能当无障碍合规认证吗？
不能。报告是设计质量评估意见，不构成 WCAG / ADA 等法律合规认证（见 §九 红线）。

Q：上传的素材怎么处理？
经 HTTPS 传输至云端评分引擎用于本次评估。服务端不留存原始素材：订单仅保存
请求摘要（scene / target.type / options / 请求体指纹），评估完成后素材即不可复原，
也无法据此补发报告。完整外发策略见 endpoint.json 的 data_egress_policy。
请勿提交你无权访问或评估的页面与素材。

5.4 支付自助排查（凭证取不到时，先自查这三条）

① 交易号是不是 AI 付交易号？
AI 付交易号为 30 位；支付宝 App 账单里常见的传统交易号是 28 位。
两者不可混用——用错会导致凭证取不到、验付失败。请从 AI 付支付结果中取交易号。

② 服务端返回「未收到支付凭证」时，订单号会沿用原单。
此时响应里的 out_trade_no 与首次请求相同，说明服务端已为你复用原订单，
用户没有白付钱。正确动作是排查凭证后重发同一请求；不要让用户再付一次。

③ SYSTEM_ERROR 通常不是服务端故障。
该错误码多出现在凭证无效或不完整的场景，请先检查凭证完整性与交易号位数，
再考虑服务端问题。

若上述自查无果：可重试 2–3 次（AI 付偶发系统繁忙）；仍失败请联系服务商处理退款。
由于服务端不留存素材，这种情况无法补发报告，只能退款。

六、能力边界与错误码

6.1 能力边界（薄客户端声明）

• ✅ 本包负责：请求组装 → 调用 → 402 支付引导 → 携凭证重试 → 报告交付
• ❌ 本包不含：本地评分逻辑、1–5 分锚定量表、检查点表、失分模式库、图像分析脚本——评估只在服务端发生（结果一致性、评分口径由服务端版本保证）
• ✅ 支持素材：网页 URL（服务端抓取）/ 设计稿截图（张数上限见 endpoint.json 的 limits）/ CSS 变量 Token
• ⚠️ 素材责任：仅评估你有权访问/评估的页面与素材；图片将经 HTTPS 传输至云端引擎，评估完成后客户端应清理本地副本

6.2 错误码（照契约）

> ⚠️ 402 承载多种语义，仅凭 HTTP 状态码无法区分。 客户端必须先解析响应体 code
> （PAYMENT_VERIFY_FAILED 还要再看 message 判断是语义 A 还是 B），
> 再决定是「重试同一订单」「重新支付」还是「重开订单」。服务端永不返回 401。
>
> ⚠️ 413 只对应请求体超限。 图片张数超限走的是 schema 校验，返回 400 INVALID_REQUEST。

错误响应统一结构：

{ "code": "...", "message": "...", "contract_version": "$CONTRACT_VERSION",
  "retryable": true, "out_trade_no": "ORDER_..." }

七、200 响应字段速览（交付物结构，便于 json 形态解析）

> 响应头 Payment-Validation：Base64URL 编码的校验对象，含 out_trade_no / resource_id / validated。
> 需要向用户或日志证明「本次确实已验付」时取此头。

八、使用示例

示例 1：评估一个数据仪表盘页面（URL，markdown 报告）

POST $ENDPOINT
Content-Type: application/json; charset=utf-8
X-Contract-Version: $CONTRACT_VERSION
Idempotency-Key: <UUID>

{
  "scene": "dashboard",
  "target": { "type": "url", "url": "https://example.com/analytics" },
  "options": { "viewport": "desktop", "theme": "light", "report_format": "markdown" }
}

→ 首调返回 402 + Payment-Needed 头 → 解码账单 → 用户支付 → 携带 Payment-Proof 重发同一 body → 200，report.content 即完整 markdown 评估报告（示例成品见 examples/sample-scorecard.md）。

示例 2：评估设计稿截图（image，3 张，JSON 结构化结果）

{
  "scene": "content",
  "target": {
    "type": "image",
    "images": [
      { "name": "首屏", "mime": "image/png", "data": "<base64…>" },
      { "name": "中段", "mime": "image/png", "data": "<base64…>" },
      { "name": "页脚", "mime": "image/png", "data": "<base64…>" }
    ]
  },
  "options": { "viewport": "desktop", "theme": "light", "user_rating_hint": "B", "report_format": "json" }
}

→ 支付后 200：report=null，直接从 dimensions[] / issues[] / gate 取结构化字段。

示例 3：CSS 变量 Token 检查（css_vars）

{
  "scene": "content",
  "target": { "type": "css_vars", "css_vars": { "--color-text": "#333", "--color-bg": "#fff", "--space-4": "16px" } },
  "options": { "theme": "light", "report_format": "json" }
}

九、红线

• 价格不写死：一切金额以服务端账单（Payment-Needed 解码后 protocol.amount）为准，本包内不得出现任何固定价格。
• 密钥不落包：本包不含任何私钥/签名材料/商户凭证；验签与验付由服务端完成。
• 不做本地评分：评分口径、权重、评级线属服务端逻辑，客户端不得自行实现或声称具备本地离线评估能力。
• 端点单一源：生产端点与限额只在 endpoint.json 定义，正文一律用 $ENDPOINT / limits.* 引用，不得复制字面量。
• 素材合规：仅评估有权访问的页面/素材；提交前确认已脱敏（endpoint.json.redaction_required）。
• 不留存素材：服务端不留存原始素材，评估完成后不可复原、无法补发；涉及争议只能退款。
• 报告边界：报告为设计质量评估意见，不构成 WCAG/ADA 等法律合规认证。