港澳台通行证识别OCR

要解决的问题

港澳台通行证的字段录入是个典型的麻烦事：通行证号码、姓名、性别、出生日期、有效期、签发地点分散在卡片正面和背面的 MRZ 机读码里。手工抄录容易错位，通用 OCR 工具又不会专门解析 MRZ 区的固定格式。这个技能要做的是把整张证件图喂进去，一次性拿到结构化字段，而不是让用户对着卡片逐字敲。

工作方式

技能采用路由层架构：大模型负责理解意图、选择工具、提取参数，代码只负责调 API。

• 检查密钥：先读 scripts.config.settings.api_key，为空则通过 AskUserQuestion 向用户询问，再用 scripts.config.set_api_key(key) 保存
• 选择工具：根据用户输入形态，从三个函数中挑一个
• 提取参数：参数不完整时，用 AskUserQuestion 追问缺失项
• 调用工具：以关键字参数调用，例如 scripts.tools.ocr_pass(dataUrl=...)
• 返回结果：工具返回 result["raw"]、result["success"]、result["message"]，把 raw 数据整理后展示给用户

三个入口对应不同的输入形态：

• scripts.tools.ocr_pass：传图片链接，参数为 dataUrl
• scripts.tools.ocr_pass_for_data_base64：传 Base64 编码，参数为 dataBase64
• scripts.tools.ocr_pass_for_data_file：传本地文件路径

适用边界与注意点

• API 密钥是硬性前提：首次使用必须在 .env 或配置中填好 XBY_APIKEY，申请入口在小笨羊科技官网
• 不允许伪造结果：缺少密钥时禁止自行搜索或编造识别数据，只能停下来向用户要密钥
• 输入必须是图片：链接、Base64 或文件路径三选一，纯文本、PDF 等形态不在此技能能力范围内
• 证件类型限定：只覆盖港澳通行证和台湾通行证，护照、身份证等其他证件不在支持范围