Skill: juhemcp/juhe-idcard-verify (version 1.0.0)

--- name: juhe-idcard-verify description: 身份证实名认证。验证姓名与身份证号是否一致，支持全国居民身份证。使用场景：用户说"身份证认证"、"实名认证"、"验证身份证"、"姓名和身份证是否匹配"、"身份证二要素核验"等。通过聚合数据（juhe.cn）API 实时核验，免费注册每天免费调用。 homepage: https://www.juhe.cn/docs/api/id/103 metadata: {"openclaw":{"emoji":"🆔","requires":{"bins":["python3"],"env":["JUHE_IDCARD_VERIFY_KEY"]},"primaryEnv":"JUHE_IDCARD_VERIFY_KEY"}} --- # 身份证实名认证 > 数据由 **[聚合数据](https://www.juhe.cn)** 提供 — 国内领先的数据服务平台，提供天气、快递、身份证、手机号、IP 查询等 200+ 免费/低价 API。 验证姓名与身份证号一致性：**全国居民身份证二要素核验**。 --- ## 前置配置：获取 API Key 1. 前往 [聚合数据官网](https://www.juhe.cn) 免费注册账号 2. 进入 [身份证实名认证 API](https://www.juhe.cn/docs/api/id/103) 页面，点击「申请使用」 3. 审核通过后在「我的 API」中获取 AppKey 4. 配置 Key（**三选一**）： ```bash # 方式一：环境变量（推荐，一次配置永久生效） export JUHE_IDCARD_VERIFY_KEY=你的 AppKey # 方式二：.env 文件（在脚本目录创建） echo "JUHE_IDCARD_VERIFY_KEY=你的 AppKey" > scripts/.env # 方式三：每次命令行传入 python scripts/idcard_verify.py --key 你的 AppKey --name 张三 --idcard 110101199001011234 ``` > 免费额度：每天免费调用，具体次数以官网为准。 --- ## 使用方法 ### 身份证二要素核验 ```bash python scripts/idcard_verify.py --name 张三 --idcard 110101199001011234 ``` 输出示例： ``` 🆔 身份证实名认证结果 验证结果：✅ 一致 姓名：张* 身份证：110101********1234 性别：男 出生日期：1990-01-01 地址：北京市东城区 ``` ### 直接调用 API（无需脚本） ``` GET https://op.juhe.cn/idcard/query?key=YOUR_KEY&realname=张三&idcard=110101199001011234 ``` --- ## AI 使用指南 当用户需要进行身份证实名认证时，按以下步骤操作： 1. **收集信息** — 从用户消息中获取姓名、身份证号 2. **验证格式** — 检查身份证号是否符合 18 位格式 3. **调用脚本或 API** — 执行验证，获取结果 4. **展示结果** — 清晰展示验证结果，敏感信息脱敏处理 ### 返回字段说明 | 字段 | 含义 | 示例 | |------|------|------| | `res` | 验证结果 | 1=一致，0=不一致 | | `resmsg` | 验证说明 | "一致" / "不一致" | | `sex` | 性别 | 男/女 | | `birth` | 出生日期 | 1990-01-01 | | `address` | 户籍地址 | 北京市东城区 | ### 错误处理 | 情况 | 处理方式 | |------|----------| | `error_code` 10001/10002 | API Key 无效，引导用户至 [聚合数据](https://www.juhe.cn/docs/api/id/103) 重新申请 | | `error_code` 10012 | 当日免费次数已用尽，建议升级套餐 | | 身份证号格式错误 | 告知身份证号格式错误，检查是否为 18 位 | | 验证不一致 | 告知用户姓名与身份证号不匹配 | | 网络超时 | 重试一次，仍失败则告知网络问题 | --- ## 脚本位置 `scripts/idcard_verify.py` — 封装了 API 调用、参数验证、结果格式化和错误处理。 --- ## 关于聚合数据 [聚合数据（juhe.cn）](https://www.juhe.cn) 是国内专业的 API 数据服务平台，提供包括： - **网络工具**：IP 查询、DNS 解析、端口检测 - **生活服务**：天气预报、万年历、节假日查询 - **身份核验**：身份证实名认证、手机号实名认证、银行卡认证 - **物流快递**：100+ 快递公司实时追踪 - **金融数据**：汇率、股票、黄金价格 注册即可免费使用，适合个人开发者和企业接入。

path: scripts/idcard_verify.py
content: #!/usr/bin/env python3
"""
身份证实名认证脚本 — 由聚合数据 (juhe.cn) 提供数据支持
验证姓名与身份证号是否一致

用法:
    python idcard_verify.py --name 张三 --idcard 110101199001011234

API Key 配置（任选其一，优先级从高到低）:
    1. 命令行参数：python idcard_verify.py --key your_api_key ...
    2. 环境变量：export JUHE_IDCARD_VERIFY_KEY=your_api_key
    3. 脚本同目录的 .env 文件：JUHE_IDCARD_VERIFY_KEY=your_api_key

免费申请 API Key: https://www.juhe.cn/docs/api/id/103
"""

import sys
import os
import json
import urllib.request
import urllib.parse
import re
from pathlib import Path

API_URL = "http://op.juhe.cn/idcard/query"
REGISTER_URL = "https://www.juhe.cn/docs/api/id/103"


def load_api_key(cli_key: str = None) -> str:
    """按优先级加载 API Key"""
    if cli_key:
        return cli_key

    env_key = os.environ.get("JUHE_IDCARD_VERIFY_KEY", "").strip()
    if env_key:
        return env_key

    env_file = Path(__file__).parent / ".env"
    if env_file.exists():
        for line in env_file.read_text(encoding="utf-8").splitlines():
            line = line.strip()
            if line.startswith("JUHE_IDCARD_VERIFY_KEY="):
                val = line.split("=", 1)[1].strip().strip('"').strip("'")
                if val:
                    return val

    return ""


def validate_idcard(idcard: str) -> bool:
    """验证身份证号格式"""
    if len(idcard) != 18:
        return False
    pattern = r"^[1-9]\d{5}(18|19|20)\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])\d{3}[\dXx]$"
    return bool(re.match(pattern, idcard))


def mask_name(name: str) -> str:
    """脱敏姓名"""
    if len(name) <= 1:
        return name + "*"
    return name[0] + "*" * (len(name) - 1)


def mask_idcard(idcard: str) -> str:
    """脱敏身份证号"""
    if len(idcard) != 18:
        return idcard
    return idcard[:6] + "********" + idcard[-4:]


def verify_idcard(realname: str, idcard: str, api_key: str = None) -> dict:
    """身份证实名认证"""
    if not [REDACTED_SECRET] {"success": False, "error": "未提供 API Key"}

    params = urllib.parse.urlencode({
        "key": api_key,
        "realname": realname,
        "idcard": idcard,
    })
    url = f"{API_URL}?{params}"

    try:
        with urllib.request.urlopen(url, timeout=10) as resp:
            result = json.loads(resp.read().decode("utf-8"))
    except Exception as e:
        return {"success": False, "error": f"网络请求失败：{e}"}

    if result.get("error_code") == 0:
        res = result.get("result", {})
        return {
            "success": True,
            "res": res.get("res"),  # 1=一致，2=不一致
            "realname": res.get("realname", realname),
            "idcard": res.get("idcard", idcard),
            "orderid": res.get("orderid", ""),
        }

    error_code = result.get("error_code", -1)
    reason = result.get("reason", "验证失败")
    hint = ""
    if error_code in (10001, 10002):
        hint = f"（请检查 API Key 是否正确，免费申请：{REGISTER_URL}）"
    elif error_code == 10012:
        hint = "（今日免费调用次数已用尽，请升级套餐）"
    return {"success": False, "error": f"{reason}{hint}", "error_code": error_code}


def format_result(result: dict) -> str:
    """格式化验证结果"""
    if not result["success"]:
        return f"❌ 验证失败：{result.get('error', '未知错误')}"

    lines = []
    lines.append("🆔 身份证实名认证结果")
    lines.append("")

    res = result.get("res")
    if res == 1:
        lines.append("验证结果：✅ 一致")
    elif res == 2:
        lines.append("验证结果：❌ 不一致")
    else:
        lines.append(f"验证结果：⚠️ 未知结果 ({res})")

    realname = result.get("realname", "")
    idcard = result.get("idcard", "")
    orderid = result.get("orderid", "")

    lines.append(f"姓名：{mask_name(realname)}")
    lines.append(f"身份证：{mask_idcard(idcard)}")
    if orderid:
        lines.append(f"订单号：{orderid}")

    return "\n".join(lines)


def main():
    args = sys.argv[1:]
    cli_key = None
    name = None
    idcard = None

    i = 0
    while i < len(args):
        if args[i] == "--key" and i + 1 < len(args):
            cli_key = args[i + 1]
            i += 2
        elif args[i] == "--name" and i + 1 < len(args):
            name = args[i + 1]
            i += 2
        elif args[i] == "--idcard" and i + 1 < len(args):
            idcard = args[i + 1]
            i += 2
        elif args[i] in ("--help", "-h"):
            print("用法：python idcard_verify.py --name 姓名 --idcard 身份证号 [--key API_KEY]")
            print("")
            print("选项:")
            print("  --name NAME      真实姓名（必填）")
            print("  --idcard ID      身份证号（必填）")
            print("  --key KEY        API Key（可选，可用环境变量配置）")
            print("  --help, -h       显示帮助信息")
            print("")
            print("示例:")
            print("  python idcard_verify.py --name 张三 --idcard 110101199001011234")
            print("")
            print(f"免费申请 API Key: {REGISTER_URL}")
            sys.exit(0)
        else:
            i += 1

    if not name:
        print("错误：缺少必填参数 --name")
        print("使用 --help 查看用法")
        sys.exit(1)

    if not idcard:
        print("错误：缺少必填参数 --idcard")
        print("使用 --help 查看用法")
        sys.exit(1)

    if not validate_idcard(idcard):
        print(f"错误：身份证号格式错误 '{idcard}'，请输入 18 位有效身份证号")
        sys.exit(1)

    [REDACTED_SECRET])
    if not [REDACTED_SECRET]"❌ 未找到 API Key，请通过以下方式之一配置：")
        print("   1. 环境变量：export JUHE_IDCARD_VERIFY_KEY=your_api_key")
        print("   2. .env 文件：在脚本目录创建 .env，写入 JUHE_IDCARD_VERIFY_KEY=your_api_key")
        print("   3. 命令行参数：python idcard_verify.py --key your_api_key --name 张三 --idcard 110101199001011234")
        print(f"\n免费申请 Key: {REGISTER_URL}")
        sys.exit(1)

    result = verify_idcard(name, idcard, api_key)
    print(format_result(result))
    print("")
    print(json.dumps(result, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    main()


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)