---
name: id-card-ocr
description: 身份证OCR识别。使用多模态大模型识别中国居民身份证正反面信息，支持图片URL和base64输入，输出姓名、身份证号、性别、民族、出生、住址、签发机关、有效期；不需要百度OCR API Key。
license: MIT
metadata:
  version: "1.1.0"
  category: ocr
  skillType: compute-entry
  tags: ["ocr", "id-card", "身份证", "多模态", "投保审核"]
---

# 身份证OCR识别

当需要从身份证正面或反面图片中提取结构化字段时使用本技能。本技能不调用百度 OCR，也不需要配置百度 API Key。

推荐流程：

1. 让多模态大模型直接查看 `imageUrl` 或 `imageBase64` 中的身份证图片。
2. 按本技能输出 schema 让模型只返回 JSON。
3. 将模型返回 JSON 作为 `modelResult` 传入本技能，做字段归一化和稳定输出。

```json
{
  "name": "id-card-ocr",
  "input": {
    "imageUrl": "https://example.com/id-card-front.jpg",
    "side": "front",
    "modelResult": {
      "fields": {
        "name": "张三",
        "idNumber": "110101199001011234",
        "gender": "男",
        "ethnicity": "汉",
        "birthDate": "1990-01-01",
        "address": "北京市东城区..."
      }
    }
  }
}
```

如果没有传 `modelResult`，本技能会返回 `needsModelVision:true` 和一段可直接给多模态模型使用的 `prompt`。

## 输入

- `imageUrl`: 图片URL，和 `imageBase64` 二选一；用于给多模态模型查看。
- `imageBase64`: 图片base64，支持带 `data:image/...;base64,` 前缀；用于给多模态模型查看。
- `side`: `front` 或 `back`，默认 `front`。`front` 识别姓名、身份证号等；`back` 识别签发机关和有效期。
- `modelResult`: 可选，多模态模型识别后的 JSON 对象或 JSON 字符串。
- `ocrResult`: 可选，等同于 `modelResult`。
- `mockResult`: 可选，联调用 JSON 对象或 JSON 字符串。
- `fields`: 可选，直接传入已识别字段对象。

## 输出

成功时输出：

```json
{
  "success": true,
  "side": "front",
  "fields": {
    "name": "张三",
    "idNumber": "110101199001011234",
    "gender": "男",
    "ethnicity": "汉",
    "birthDate": "1990-01-01",
    "address": "北京市东城区...",
    "issueAuthority": "",
    "validFrom": "",
    "validTo": ""
  },
  "quality": {},
  "risk": {},
  "raw": {}
}
```

未传模型识别结果时输出 `success:false`、`needsModelVision:true`、`prompt`，不会向 stdout 输出非 JSON 内容。

## 注意

- 本技能只负责身份证识别结果归一化，不做投保业务审核。
- 在 TYCM AI 审核链路中，如果本技能返回 `success:false` 或执行异常，后续编排仍应调用 `tycm-callback`，向 TYCM 的 `/agent-invoke-callback` 回推 `status:"failed"` 和失败原因。
- 字段和提示词细节见 `references/multimodal_id_card_ocr.md`。