字体识别

概述

上传包含中文文字的图片，即可识别图中每行文字的字体名称、OCR 内容、置信度及候选字体列表，并生成一份可视化的 HTML 结果页。本技能仅做字体识别，不涉及字体版权或商用授权的判断。每次识别 ¥0.50。

支付前置检查

调用本技能前，先确认当前环境已接入微信支付：

• 已接入：正常提供付费识别服务。
• 未接入：提示用户「当前环境暂不支持微信支付」，终止流程。

未通过检查时，不得调用识别接口，也不得创建订单。

开始识别

请用户提供 JPEG、PNG 或 WebP 格式的图片。如果没有图片，请用户上传一张清晰、文字区域裁剪紧凑的图片；不要在没有图片时调用接口、创建订单或臆测字体。如果对话中已有附件（即使只显示了文件名），直接使用该附件，不要搜索工作区或要求重新上传。

同一次识别只生成一个规范的 UUID 作为 client_request_id。如果首次 POST 未收到任何 HTTP 响应（例如 DNS 解析失败、TLS 握手失败、连接断开或超时），请等待请求彻底结束后，至多串行重试一次，并复用同一个 UUID；禁止并发重复请求。

一旦收到任何 HTTP 响应，本次请求即告结束。此时：

• 只有 HTTP 402（需要支付）可以继续走下面的支付流程；
• 其他任何状态码都必须停止，不得自动重试、不得生成新的 client_request_id、不得创建新订单。
• 只有当用户后续明确再次发起识别时，才可以生成新的 UUID 开始新的一笔订单。

错误处理：

• HTTP 503 且响应体 code=DEPENDENCY_UNAVAILABLE：告知用户「支付服务暂时不可用，请稍后重试」，然后停止。如果响应中未包含 paymentCode 和 out_trade_no，要向用户说明：本次未发起支付，没有产生费用。
• HTTP 410 且 code=ORDER_EXPIRED：告知用户「识别会话已过期」，然后停止。
• 以上错误均不得推荐、切换或调起任何测试版技能。

支付与识别

按以下顺序严格操作：

1. 向 https://agentpay.hellofont.cn/v1/font-recognition 发起 multipart POST，只提交图片文件 file、前述的 client_request_id，以及可选参数 query。
2. 收到 HTTP 402 后，从响应头 WeixinPay-Required 中取出 paymentCode，同时保存响应体中的 out_trade_no。两者缺一不可；不得创建第二笔订单。
3. 告知用户本次识别费用为 ¥0.50，然后将保存的 paymentCode 传给 weixinpay_pay（同一次识别只调用一次支付）。等待支付工具返回明确结果；用户口头说「已支付」不等于支付工具成功。
4. 只有当 weixinpay_pay 明确返回支付成功时，使用之前保存的 out_trade_no，以请求头 X-Out-Trade-No 重新调用同一接口：
   • 不重传图片
   • 不再发送 client_request_id
   • 不再发起支付（支付只做一次）
5. 重试后必须得到 HTTP 200 且响应体 mode=real。将完整 JSON 保存到工作目录（如 hellofont-response.json），不得擅自改写 OCR 结果、候选顺序、置信度、字体 ID 或 webfonts 数据。

支付各状态的处理：

• 用户取消支付 → 立即停止，不重试、不再次支付。
• 支付失败 → 立即停止，不重试、不再次支付。
• 支付状态未知 → 停止，不再次支付、不再次调用 weixinpay_pay、不创建新订单。请用户先通过支付渠道核实该 out_trade_no 的状态。
• 没有支付工具返回的明确成功状态（或已支付订单的可靠执行记录），不能仅凭用户口述继续取结果。

已支付订单的结果回放：

• 如果取结果时发生网络传输失败，或返回 OCR_TIMEOUT，等待当前请求结束后，串行复用同一个 out_trade_no 重试。同样不重传图片、不创建订单、不再次支付。

生成结果页

收到 HTTP 200 且 mode=real 后，在本技能目录下运行渲染脚本：

python3 scripts/render_result.py 
  --image "/absolute/path/to/original-image" 
  --response "/absolute/path/to/hellofont-response.json" 
  --output "/absolute/path/to/hellofont-result.html"

渲染脚本仅使用响应中 webfonts 字段内经过安全校验的 HTTPS 字体链接，无需（也不应索取）本地的 WebFont 凭据。字体链接缺失或加载失败时，页面仍正常生成，并标注「系统字体回退」。只有当页面明确显示「已使用识别字体渲染」时，才可以声称启用了在线字体。

当前 API 不提供可验证的文字坐标，因此结果页只展示原图，不绘制文字标框。

结果呈现

结果页生成后，按以下顺序向用户呈现：

1. 告知用户可打开的 HTML 结果页路径（hellofont-result.html）。
2. 用表格简要列出每行文字的 OCR 内容、最佳匹配字体 best_font、全部候选字体 candidates 及其置信度 confidence。
3. 标注：所有字体匹配结果与置信度仅供参考，不承诺准确率。

特殊情况：

• NO_TEXT（未检测到文字）：告知用户未检测到文字，建议上传更清晰、文字区域裁剪更紧凑的图片。不编造 OCR 结果或字体名称。
• 图片损坏或格式不支持：根据实际错误说明原因，请用户提供 JPEG、PNG 或 WebP 格式的图片。不要仅凭文件名推测格式。
• 任何环节未实际完成（接口未返回、支付未成功、脚本未运行等），不得声称已完成识别。

⚠️ 识别结果不构成字体版权、商用或其他授权结论，请以字体权利方的正式授权条款为准。