身份证识别

要解决的问题

把一张身份证图片变成可用的结构化数据，看起来只是调个 OCR 接口，真正麻烦的地方在后头：反光、手指遮挡、水印、裁边都会让某个字段读不出来；识别结果里姓名对了但身份证号多了一位，你很难判断是识别错还是本来就写错了。如果直接拿原始 OCR 文本去比对数据库做实名校验，错误会被放大成一次误判。手工誊抄虽然稳，但在批量录入场景下成本高得不划算。

技能如何工作

输入支持 1～2 张 JPG、JPEG、PNG 或 BMP 图片：只传一张时按单面处理，传两张时按你给的顺序当作正面与背面。重复文件或超过两张会被直接拒绝，不会静默挑一张跑。

核心入口是 scripts/generate.js，建议始终带上 --json 与独立的 --output-dir，这样输出只有一段可解析的 JSON，结果落在 id-card.json，同时目录里保留 SDK 请求与响应日志。--attachment 可以重复传两次来覆盖正反面，--lang 只影响展示用的语言标签，--timeout 与 --retries 用来控制超时和瞬时故障重试。

这个技能最重要的设计原则是不做二次加工。data 字段里是原样返回的 OCR 结果，localized fields 只用于界面展示，每个条目都保留原始 key。身份证号、姓名、出生日期、地址、有效期、民族、签发机关，任何一项缺失就留空或标记为 unknown，绝不从其他字段推导，也不做大小写归一、繁简转换、掩码或补全。

识别完成后会检查 missingCoreFields、qualityFlags 和 warnings。正面的 identity_name 与 identity_code 必须复核，背面的 issued_by 与有效期同样要复核，双面输入时两套都要看。身份证号如果不符合 15 位或 18 位的结构规则，只会被打上 identity_code_format 标记，数值本身不会被改动。

适用边界

这个技能只做 OCR。它不验证证件真伪，不判断活体，不确认持证人与证件的所有权关系，也不判断证件是否处于有效期或持有者是否有资格。因此不要拿它的输出单独做身份核验、门禁放行、招聘背调、信贷审批、保险投保、住房申请这类高影响决策，这些场景需要额外的人脸比对、官方接口或人工复核环节。

如果某个字段被遮挡或打码，技能会把它当作未知值而不是猜一个，这时更好的做法是重新提供一张清晰的正面照片，而不是反复重跑同一张图。API key 通过环境变量 UNITYCLAW_KEY 传入，需要自行向 UnityClaw 获取。