騰訊雲身份證識別

核心能力：
- **人像面(FRONT)**：识别姓名、性别、民族、出生日期、住址、公民身份证号
- **国徽面(BACK)**：识别签发机关、证件有效期
- **附加功能**：身份证照片/人像照片裁剪、7种告警检测（复印件、翻拍、PS、临时身份证等）

官方文档：https://cloud.tencent.com/document/api/866/33524

## 使用时机

当用户提出以下需求时触发此技能：
- 需要从身份证图片中提取文字信息
- 需要验证身份证真伪（复印件/翻拍/PS检测）
- 需要裁剪身份证照片或人像照片
- 涉及身份证OCR识别的任何场景

## 环境要求

- Python 3.6+
- 依赖：`tencentcloud-sdk-python`（通过 `pip install tencentcloud-sdk-python` 安装）
- 环境变量：
  - `TENCENTCLOUD_SECRET_ID`：腾讯云API密钥ID
  - `TENCENTCLOUD_SECRET_KEY`：腾讯云API密钥Key

## 使用方式

运行 `scripts/main.py` 脚本完成身份证识别。

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ImageBase64 | str | 否(二选一) | 图片Base64值，不超过10MB |
| ImageUrl | str | 否(二选一) | 图片URL地址，优先使用 |
| CardSide | str | 否 | `FRONT`(人像面) / `BACK`(国徽面)，不填则自动判断 |
| Config | str | 否 | JSON字符串，可选开关见下方说明 |
| EnableRecognitionRectify | bool | 否 | 默认true，开启身份证号/出生日期/性别的矫正补齐 |
| EnableReflectDetail | bool | 否 | 默认false，需配合ReflectWarn使用 |
| CardWarnType | str | 否 | `Basic`(默认) / `Advanced`(进阶PS告警) |
| **UserAgent** | **str** | **否** | **请求来源标识(可选)，不传时自动探测平台** |

**Config JSON 可选开关**：`CropIdCard`、`CropPortrait`、`CopyWarn`、`BorderCheckWarn`、`ReshootWarn`、`DetectPsWarn`、`TempIdWarn`、`InvalidDateWarn`、`Quality`、`MultiCardDetect`、`ReflectWarn`

### ⚠️ UserAgent参数使用指南

**`--user-agent`参数是可选参数**，不传时脚本会**自动探测当前调用平台**（WorkBuddy / OpenClaw / QClaw / ADP / CodeBuddy），并输出 `skill-<platform>`；无法识别时回退为 `skillother`。用于标识API调用来源，便于按渠道追踪和统计调用次数：

| 调用平台 | 不传时的自动探测结果 | 说明 |
|---------|--------------|------|
| WorkBuddy | `skill-workbuddy` | 自动识别 |
| CodeBuddy | `skill-codebuddy` | 自动识别 |
| OpenClaw | `skill-openclaw` | 自动识别 |
| QClaw | `skill-qclaw` | 自动识别 |
| ADP | `skill-adp` | 自动识别 |
| 未识别 | `skillother` | 兜底 |
| 显式传参 | 原样使用 | 人工覆盖，向后兼容 |

**实现说明**:
- 不传 `--user-agent` 时，脚本通过环境变量 + 进程树回溯自动探测渠道
- SDK 会将其拼接为 `SDK_PYTHON_x.x.x; skill-<platform>` 注入到请求的 `RequestClient` 字段
- cam_access_server 会将此值写入 ES 日志的 `requestClient` 字段，可直接聚合统计
- 探测逻辑异常安全：任何失败回退为 `skillother`，不影响 OCR 主流程

### 输出格式

识别成功后返回 JSON 格式结果：

**人像面(FRONT)**：
```json
{
  "Name": "张三",
  "Sex": "男",
  "Nation": "汉",
  "Birth": "1990/01/01",
  "Address": "XX省XX市XX区XX路XX号",
  "IdNum": "110101199001011234",
  "AdvancedInfo": "{\"WarnInfos\":[]}",
  "RequestId": "xxx"
}
```

**国徽面(BACK)**：
```json
{
  "Authority": "XX市公安局",
  "ValidDate": "2020.01.01-2040.01.01",
  "AdvancedInfo": "{\"WarnInfos\":[]}",
  "RequestId": "xxx"
}
```

### 告警码说明

| 告警码 | 含义 |
|--------|------|
| -9100 | 有效日期不合法 |
| -9101 | 边框不完整 |
| -9102 | 复印件 |
| -9103 | 翻拍 |
| -9104 | 临时身份证 |
| -9105 | 框内遮挡 |
| -9106 | PS痕迹 |
| -9107 | 反光 |
| -9108 | 复印件(仅黑白) |
| -9110 | 电子身份证 |

### ⚠️ 告警检测使用须知

**`WarnInfos` 仅在 `Config` 字段非空时才会返回**。`--card-warn-type`（Basic/Advanced）仅切换告警算法等级，**不替代 `Config`**。若需要检测电子身份证（-9110）等任何告警，必须在 `--config` 中开启至少一个告警开关（如 `CopyWarn`、`BorderCheckWarn`、`ReshootWarn`、`DetectPsWarn`、`TempIdWarn`、`InvalidDateWarn`、`ReflectWarn` 等）。

> **调用方指引**：当用户表达了告警检测需求（如"检测电子身份证"、"检测翻拍"等）但未指定 `--config` 时，应主动向用户确认是否开启告警通道，并推荐默认配置 `{"CopyWarn":true,"BorderCheckWarn":true,"ReshootWarn":true,"DetectPsWarn":true,"TempIdWarn":true,"InvalidDateWarn":true,"ReflectWarn":true}`。

### 调用示例

```bash
# 基础调用示例（--user-agent 默认为 Skills，可不传）
python scripts/main.py --image-url "https://example.com/idcard.jpg" --card-side FRONT

# 使用 Base64 文件调用
python scripts/main.py --image-base64 "/path/to/base64.txt"

# 开启告警检测和照片裁剪
python scripts/main.py --image-url "https://example.com/idcard.jpg" \
  --config '{"CropIdCard":true,"CopyWarn":true,"ReshootWarn":true}'

# 使用进阶PS告警（需配合 --config 开启告警通道，否则 WarnInfos 不会返回）
python scripts/main.py --image-url "https://example.com/idcard.jpg" \
  --config '{"CopyWarn":true,"BorderCheckWarn":true,"ReshootWarn":true,"DetectPsWarn":true,"TempIdWarn":true,"InvalidDateWarn":true,"ReflectWarn":true}' \
  --card-warn-type Advanced
```