身份证信息查询(AI付版) - 聚合数据

SKILL.md

---
name: juhe-idcard-query-a2a
description: |
  聚合数据官方身份证信息查询服务技能。
  本技能是通过根据身份证号码查询证件相关信息，包括性别、出生日期、户口所在地的基于 A2M（HTTP 402）收单协议的付费技能，本技能仅依编码及格式进行识别判断，不能识别出身份证的真伪，不涉及个人隐私信息。
  当用户需要查询身份证信息：包括性别、出生日期、户口所在地的时候，调用本技能。买家通过本 Skill 向卖家服务端发起请求，完成支付后获取相关结果。
  关键词：身份证信息查询、性别查询、出生日期查询、户口所在地查询
---

## 技能描述

本 Skill 提供身份证号码信息查询能力：包括性别、出生日期、户口所在地，当用户需要通过身份证号码查询以上信息时，调用本技能。
该服务技能是基于 A2M 智能收协议（HTTP 402）的付费资源。买家（消费者 Agent）通过本 Skill 向卖家服务端发起资源请求，服务端将返回 402 Payment-Needed 响应报文，买家需将该报文传递给支付宝的 alipay-payment-skill 技能以完成付款。付款完成后，该技能将提供查询服务。

**注意：**
本技能仅依编码及格式进行识别判断，不能识别出身份证的真伪，不涉及个人隐私信息。

## 系统要求

### 操作系统

由于该技能基于 A2M 协议，需要在支持 A2M 协议的系统上运行，支付宝支付 CLI 工具（alipay-bot）在 Windows 环境下暂不支持。

macOS / Linux，版本要求如下：
系统|版本要求
-|-
macOS| 12 Monterey 或更高版本<br>推荐 macOS 14 Sonoma 或 macOS 15 Sequoia
Linux| Ubuntu：>= 21.04 <br>Debian：>= 12 <br>CentOS：>= 9

### 环境要求

| 环境    | 版本要求 |
| ------- | -------- |
| Node.js | > 22     |
| npm     | > 10     |

## 必要依赖

本技能依赖于支付宝AI付技能，需要从clawhub上安装这两个技能：alipay-authenticate-wallet 和 alipay-payment-skill，安装后检查是否已开启支付宝支付功能，如未开启，需要提示用户开启支付宝支付功能。

## 触发条件

- **用户意图：** 需要依托身份证号码查询对应性别、出生日期、户口所在地，或解析身份证编码自带基础信息；
- **关键词匹配：** 对话包含「身份证信息查询、性别查询、出生日期查询、户口所在地查询」任一关键词；
- **实体硬性要求：** 输入内容中必须包含 18 位居民身份证号码，无身份证号码不触发；
- **拦截规则：** 若用户需求为核验身份证真伪、仅科普编码知识、办理身份证相关线下业务，则不触发本技能；
- **服务说明：** 本技能为付费技能，仅依据身份证编码规则解析公开字段，无法判断证件真实有效性，仅输出性别、出生日期、户口所在地三项基础信息；

## 工作流程

### 第一步 收集身份证号码

当用户需要查询身份证号码相关信息时，先提示用户输入需要查询的18 位居民身份证号码。

### 第二步：请求约束

- 请求方法：POST
- 请求头：Content-Type: application/json
- 请求体是json字符串，请严格按照以下格式填写：'{"resourceId":"38","data":{"cardno":"<需要查询的身份证号>"}}'
- 注意promot引号转义，避免json字符串异常

### 第三步：请求资源

向用户展示待查询的参数，严格遵守请求约束，向以下 URL 发起请求：

```bash
curl https://apis.juhe.cn/a2a/query
    -d '{"resourceId":"38","data":{"cardno":"<需要查询的身份证号>"}}'
    -H "Content-Type: application/json"
```

### 第四步：处理 402 响应

收到状态码为 402 的响应报文（包含 `Payment-Needed` 响应头）后，将整个 402 响应报文传递给支付宝的 **alipay-payment-skill** 技能，引导用户完成付款，并展示用户订单号（out_trade_no）。

### 第五步：后续流程

完全转移到 alipay-payment-skill 技能的工作流,提示支付待确认的信息时，需要包含用户订单号（out_trade_no）。禁止agent更改用户提交的请求参数即json字符串。

## 异常情况处理

- **用户拒绝付款**：尊重用户选择，告知用户该内容为付费资源，如需获取请完成支付。
- **请求返回非 402 状态码**：如返回 200，直接展示内容；如返回 4xx/5xx 错误，告知用户服务暂时不可用，建议稍后重试。
- 其余异常情况将由 alipay-payment-skill 技能处理。

## Agent 约束

- 禁止缺必填参数发起请求；
- 402 响应报文必须完整透传，不可篡改、删减；
- 严格遵循既定流程与异常规则，禁止自定义逻辑。

## 使用示例

**用户**: 帮我查一下身份证号 320505199001011234 的信息

**助手**: 好的，我来帮你查询该身份证号码的相关信息，包括性别、出生日期、户口所在地。

[执行 curl 请求]

[收到 402 响应后]

这是一个付费资源，需要完成支付才能获取查询结果。正在调用支付宝支付技能...

[调用 alipay-payment-skill]

## 隐私说明

- 本技能仅用于查询身份证号码对应的基本信息
- 请确保查询行为符合相关法律法规
- 不要用于非法用途或侵犯他人隐私

## Agent 约束

- 禁止缺必填参数发起请求；
- 402 响应报文必须完整透传，不可篡改、删减；
- 严格遵循既定流程与异常规则，禁止自定义逻辑。