anyixing-verify 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# anyixing-verify
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+核验中国居民**身份证号、银行卡号、手机号**的实名信息 —— 判断姓名与证件／卡号／号码是否属于同一人。
+
+可以一键装成 AI 技能（Claude Code / Cursor / WorkBuddy），也能直接在命令行里用。
+
+## 装成 AI 技能
+
+```bash
+npx -y anyixing-verify@latest install
+```
+
+装好后你的 AI 就懂怎么核验了，直接说「帮我核验这个身份证和姓名是不是同一个人」即可。
+
+装的时候顺便把密钥配好：
+
+```bash
+npx -y anyixing-verify@latest install --key 你的Key
+```
+
+## 配置密钥
+
+到 <https://smrz.anyixing.com.cn/login.php> 手机号验证码登录（未注册自动开户），
+控制台「概览」页复制 API Key。**新用户赠送 2 元测试额度**，够跑十几次身份证核验。
+
+```bash
+npx -y anyixing-verify@latest config --key 你的Key   # 保存并免费校验
+npx -y anyixing-verify@latest config --show          # 查看（脱敏）
+npx -y anyixing-verify@latest config --clear         # 清除
+```
+
+也可以用环境变量：`ANYIXING_API_KEY=你的Key`。
+
+## 直接核验
+
+```bash
+# 身份证二要素
+npx -y anyixing-verify@latest idcard --name 张三 --idcard 330102199001010012
+
+# 银行卡四要素（手机号是银行预留号，不是用户现在的号）
+npx -y anyixing-verify@latest bank --name 张三 --idcard 330102199001010012 \
+    --bankcard 6222021234567894 --mobile 13800138000
+
+# 手机号二要素
+npx -y anyixing-verify@latest mobile --name 张三 --mobile 13800138000
+
+# 手机号三要素
+npx -y anyixing-verify@latest mobile --name 张三 --mobile 13800138000 --idcard 330102199001010012
+```
+
+输出：
+
+```
+✅ 核验一致
+   信息属于同一人
+   费用 ¥0.20   余额 ¥9985.12   耗时 295ms
+   流水号 6aeaf4e60e6e5315
+```
+
+加 `--json` 输出接口原始报文。
+
+## 返回结果
+
+| result | 含义 | 是否计费 |
+|---|---|---|
+| `MATCH` | 一致 | 计费 |
+| `NO_MATCH` | 不一致（正常业务结论，不是故障） | 计费 |
+| `NO_ID` | 证件号无记录 | 计费 |
+| `NO_CARD` | 卡号无记录 | 计费 |
+| `NO_NUMBER` | 号码无记录 | 计费 |
+
+参数错误、余额不足、频控、上游异常不扣费。
+
+## 计费
+
+按次扣费，标准档起步：身份证 ¥0.20、银行卡 ¥0.35、手机号 ¥0.25。
+充值越多单价越低，额度 2 年有效。详见 <https://smrz.anyixing.com.cn/price.php>。
+
+## 安全
+
+密钥是长期凭证，别写进代码仓库、前端代码或公开文档。
+脚本保存在 `~/.config/smrz/api_key`（Windows 为 `%APPDATA%\smrz\api_key`），权限 600。
+
+## 许可
+
+MIT

package/bin/cli.js

@@ -0,0 +1,372 @@
+#!/usr/bin/env node
+/**
+ * 安宜星实名认证 —— 命令行工具 / AI 技能安装器
+ *
+ * 用法：
+ *   npx -y anyixing-verify@latest install            # 装成 AI 技能
+ *   npx -y anyixing-verify@latest install --key xxx   # 装好并配好密钥
+ *   npx -y anyixing-verify@latest config --key xxx    # 只配密钥
+ *   npx -y anyixing-verify@latest idcard --name 张三 --idcard 3301...
+ *   npx -y anyixing-verify@latest bank   --name 张三 --idcard 3301... --bankcard 6222... --mobile 138...
+ *   npx -y anyixing-verify@latest mobile --name 张三 --mobile 138...
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const https = require('https');
+
+const SITE = 'https://smrz.anyixing.com.cn';
+const NAME = 'anyixing-verify';
+const PKG_ROOT = path.join(__dirname, '..');
+const SKILL_SRC = path.join(PKG_ROOT, 'skill');
+
+const C_RESET = '\x1b[0m';
+const C_DIM = '\x1b[2m';
+const C_GREEN = '\x1b[32m';
+const C_RED = '\x1b[31m';
+const C_YEL = '\x1b[33m';
+const C_BLUE = '\x1b[34m';
+const tty = process.stdout.isTTY;
+const paint = (c, s) => (tty ? c + s + C_RESET : s);
+
+const TARGETS = [
+  ['WorkBuddy', path.join(os.homedir(), '.workbuddy', 'skills')],
+  ['Claude Code', path.join(os.homedir(), '.claude', 'skills')],
+  ['Cursor', path.join(os.homedir(), '.cursor', 'skills')],
+];
+
+const GUIDE_NO_KEY = `
+${paint(C_YEL, '⚠️  还没有配置 API Key')}
+
+这个工具本身免费，调用核验接口按次计费，需要一个 API Key：
+  1. 打开 ${SITE}/login.php ，手机号验证码登录（未注册会自动开户）
+  2. 控制台「概览」页复制 API Key
+  3. 新用户注册赠送 2 元测试额度，够跑十几次身份证核验
+
+配置方式：
+  npx -y ${NAME}@latest config --key 你的Key
+  或设置环境变量 ANYIXING_API_KEY=你的Key
+
+接口与计费：${SITE}/price.php
+`;
+
+function keyFile() {
+  if (process.platform === 'win32' && process.env.APPDATA) {
+    return path.join(process.env.APPDATA, 'smrz', 'api_key');
+  }
+  return path.join(os.homedir(), '.config', 'smrz', 'api_key');
+}
+
+function loadKey(explicit) {
+  if (explicit && explicit.trim()) return explicit.trim();
+  const env = (process.env.ANYIXING_API_KEY || process.env.SMRZ_API_KEY || '').trim();
+  if (env) return env;
+  try {
+    const t = fs.readFileSync(keyFile(), 'utf8').trim();
+    if (t) return t;
+  } catch (e) { /* 没配过 */ }
+  return '';
+}
+
+function mask(k) {
+  if (!k || k.length <= 12) return '***';
+  return k.slice(0, 6) + '…' + k.slice(-4);
+}
+
+function api(endpoint, payload, key, timeout = 20000) {
+  return new Promise((resolve) => {
+    const body = JSON.stringify(payload || {});
+    const req = https.request(
+      {
+        hostname: 'smrz.anyixing.com.cn',
+        path: '/api/v1/' + endpoint,
+        method: 'POST',
+        timeout,
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(body),
+          'X-Api-Key': key,
+          'User-Agent': 'anyixing-verify-npm/1.0',
+        },
+      },
+      (res) => {
+        let buf = '';
+        res.setEncoding('utf8');
+        res.on('data', (d) => (buf += d));
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(buf));
+          } catch (e) {
+            resolve({ code: -1, msg: 'HTTP ' + res.statusCode + ': ' + buf.slice(0, 200) });
+          }
+        });
+      }
+    );
+    req.on('timeout', () => req.destroy(new Error('请求超时')));
+    req.on('error', (e) => resolve({ code: -1, msg: '网络错误：' + e.message }));
+    req.write(body);
+    req.end();
+  });
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  let count = 0;
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      count += copyDir(s, d);
+    } else {
+      fs.copyFileSync(s, d);
+      count++;
+    }
+  }
+  return count;
+}
+
+const ERR = {
+  1001: '参数错误（未计费）',
+  1002: 'API Key 无效',
+  1003: '余额不足',
+  1004: '频率超限',
+  1005: '接口不可用',
+  1006: '触发防刷（未计费）',
+  2001: '上游超时（未计费）',
+  2002: '上游异常（未计费）',
+  2003: '核验未完成（已计费）',
+};
+
+const RESULT = {
+  MATCH: ['✅ 核验一致', '信息属于同一人'],
+  NO_MATCH: ['❌ 核验不一致', '信息对不上，这是正常业务结论'],
+  NO_ID: ['⚠️  查无此身份证', '证件号在数据源无记录'],
+  NO_CARD: ['⚠️  查无此银行卡', '卡号在数据源无记录'],
+  NO_NUMBER: ['⚠️  查无此手机号', '号码在数据源无记录'],
+};
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const k = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        out[k] = true;
+      } else {
+        out[k] = next;
+        i++;
+      }
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+async function cmdInstall(args) {
+  const key = loadKey(args.key);
+  let targets = TARGETS.filter(([, p]) => {
+    try { return fs.statSync(p).isDirectory(); } catch (e) { return false; }
+  });
+
+  if (args.to) {
+    targets = [['指定目录', path.resolve(String(args.to))]];
+  } else if (!targets.length) {
+    targets = [['新建目录', path.join(os.homedir(), '.workbuddy', 'skills')]];
+  }
+
+  console.log(paint(C_BLUE, '安装安宜星实名认证技能'));
+
+  const installed = [];
+  for (const [label, root] of targets) {
+    try {
+      const dest = path.join(root, NAME);
+      const n = copyDir(SKILL_SRC, dest);
+      console.log(`  ${paint(C_GREEN, '✅')} ${label}：${n} 个文件 → ${dest}`);
+      installed.push(dest);
+    } catch (e) {
+      console.log(`  ${paint(C_RED, '❌')} ${label} 失败：${e.message}`);
+    }
+  }
+
+  if (!installed.length) return 1;
+
+  if (key) {
+    const fromArg = args.key && String(args.key).trim();
+    if (fromArg) {
+      fs.mkdirSync(path.dirname(keyFile()), { recursive: true });
+      fs.writeFileSync(keyFile(), key, 'utf8');
+      try { fs.chmodSync(keyFile(), 0o600); } catch (e) { /* windows 忽略 */ }
+    }
+
+    const probe = await api('idcard', {}, key);
+    if (probe.code === 1001) {
+      console.log(`  ${paint(C_GREEN, '✅')} ${fromArg ? 'API Key 已保存并校验通过' : '检测到已配置的 Key，校验通过'}`);
+    } else if (probe.code === 1002) {
+      console.log(`  ${paint(C_RED, '❌')} API Key 校验未通过，请确认是否完整复制`);
+    } else {
+      console.log(`  ${paint(C_YEL, '⚠️')} Key 校验返回 ${probe.code} ${probe.msg || ''}`);
+    }
+  } else {
+    console.log('');
+    console.log(paint(C_YEL, '下一步：配好 API Key 才能核验'));
+    console.log(`  1. 打开 ${SITE}/login.php ，手机号验证码登录（未注册会自动开户）`);
+    console.log('  2. 控制台「概览」页复制 API Key，新用户送 2 元测试额度');
+    console.log(`  3. 回来执行：npx -y ${NAME}@latest config --key 你的Key`);
+    console.log('');
+    console.log(paint(C_DIM, '  如果你是在 Agent 会话里看到这段：直接把 Key 发给 Agent，让它帮你跑这一步。'));
+  }
+
+  console.log('');
+  console.log('装好了。有些客户端需要重启才认出新技能，重启后直接说「帮我核验这个人」。');
+  return 0;
+}
+
+async function cmdConfig(args) {
+  if (args.clear) {
+    try { fs.unlinkSync(keyFile()); console.log('已清除本地保存的 Key'); }
+    catch (e) { console.log('本地本来就没有保存 Key'); }
+    return 0;
+  }
+
+  if (args.show || !args.key) {
+    const k = loadKey('');
+    if (!k) {
+      console.log(GUIDE_NO_KEY.trim());
+      return 1;
+    }
+    console.log('配置文件：' + keyFile());
+    console.log('当前 Key：' + mask(k));
+    return 0;
+  }
+
+  const key = String(args.key).trim();
+  fs.mkdirSync(path.dirname(keyFile()), { recursive: true });
+  fs.writeFileSync(keyFile(), key, 'utf8');
+  try { fs.chmodSync(keyFile(), 0o600); } catch (e) { /* ignore */ }
+  console.log(`✅ Key 已保存到 ${keyFile()}`);
+
+  const probe = await api('idcard', {}, key);
+  if (probe.code === 1001) {
+    console.log('✅ Key 有效，已连上安宜星接口');
+    return 0;
+  }
+  if (probe.code === 1002) {
+    console.log('❌ Key 无效，请确认完整复制（控制台「概览」页可重新复制）');
+    return 1;
+  }
+  console.log(`⚠️  校验返回 ${probe.code}：${probe.msg || ''}`);
+  return 0;
+}
+
+async function cmdVerify(kind, args) {
+  const key = loadKey(args.key);
+  if (!key) {
+    console.log(GUIDE_NO_KEY.trim());
+    return 2;
+  }
+
+  let payload = {};
+  let endpoint = kind;
+  if (args.name) payload.name = String(args.name).trim();
+
+  if (kind === 'idcard') {
+    if (!args.name || !args.idcard) return usage('身份证核验需要 --name 与 --idcard');
+    payload.idcard = String(args.idcard).trim();
+  } else if (kind === 'bank') {
+    const miss = [];
+    if (!args.name) miss.push('--name');
+    if (!args.idcard) miss.push('--idcard');
+    if (!args.bankcard) miss.push('--bankcard');
+    if (!args.mobile) miss.push('--mobile');
+    if (miss.length) return usage('银行卡四要素核验缺少：' + miss.join(' '));
+    payload.idcard = String(args.idcard).trim();
+    payload.bankcard = String(args.bankcard).trim();
+    payload.mobile = String(args.mobile).trim();
+    endpoint = 'bankcard';
+  } else {
+    if (!args.name || !args.mobile) return usage('手机号核验需要 --name 与 --mobile');
+    payload.mobile = String(args.mobile).trim();
+    if (args.idcard) payload.idcard = String(args.idcard).trim();
+  }
+
+  const r = await api(endpoint, payload, key);
+
+  if (args.json) {
+    console.log(JSON.stringify(r, null, 2));
+    return r.code === 0 ? 0 : 1;
+  }
+
+  if (r.code !== 0) {
+    console.log(paint(C_RED, '❌ ' + (ERR[r.code] || '调用失败') + `（code ${r.code}）`));
+    if (r.msg) console.log('   ' + r.msg);
+    if (r.code === 1002) console.log(`\n   Key 可能失效，去 ${SITE}/user/index.php 重新复制`);
+    if (r.code === 1003) console.log(`\n   余额不足，去 ${SITE}/buy.php 充值（50 元起）`);
+    return 1;
+  }
+
+  const d = r.data || {};
+  const [head, desc] = RESULT[d.result] || ['结果：' + d.result, ''];
+  console.log(head);
+  if (desc) console.log('   ' + desc);
+
+  const facts = [];
+  if (d.fee !== undefined) facts.push('费用 ¥' + Number(d.fee).toFixed(2));
+  if (d.balance !== undefined) facts.push('余额 ¥' + Number(d.balance).toFixed(2));
+  if (d.cost_ms !== undefined) facts.push('耗时 ' + d.cost_ms + 'ms');
+  if (facts.length) console.log('   ' + facts.join('   '));
+
+  const extra = [];
+  if (d.card_mask) extra.push('卡号 ' + d.card_mask);
+  if (d.bank_name) extra.push('开户行 ' + d.bank_name);
+  if (d.card_type) extra.push('卡类型 ' + d.card_type);
+  if (d.carrier) extra.push('运营商 ' + d.carrier);
+  if (d.city) extra.push('归属地 ' + d.city);
+  if (extra.length) console.log('   ' + extra.join('   '));
+
+  if (d.req_id) console.log(paint(C_DIM, '   流水号 ' + d.req_id));
+  return 0;
+}
+
+function usage(msg) {
+  console.error('用法错误：' + msg);
+  return 1;
+}
+
+function help() {
+  console.log(`
+${paint(C_BLUE, '安宜星实名认证')} · 证件 / 银行卡 / 手机号实名核验
+
+  npx -y ${NAME}@latest install                 装成 AI 技能
+  npx -y ${NAME}@latest install --key 你的Key    装好并配好密钥
+  npx -y ${NAME}@latest config --key 你的Key     只配密钥（会免费校验一次）
+  npx -y ${NAME}@latest config --show            查看当前 Key
+  npx -y ${NAME}@latest config --clear           清除 Key
+
+  npx -y ${NAME}@latest idcard --name 张三 --idcard 330102199001010012
+  npx -y ${NAME}@latest bank   --name 张三 --idcard 330102199001010012 \\
+                              --bankcard 6222021234567894 --mobile 13800138000
+  npx -y ${NAME}@latest mobile --name 张三 --mobile 13800138000 [--idcard ...]
+
+加 --json 输出接口原始报文。密钥在 ${SITE} 获取，新用户送 2 元。
+`);
+}
+
+(async () => {
+  const args = parseArgs(process.argv.slice(2));
+  const cmd = args._[0] || 'help';
+
+  let code = 0;
+  if (cmd === 'install') code = await cmdInstall(args);
+  else if (cmd === 'config') code = await cmdConfig(args);
+  else if (cmd === 'idcard' || cmd === 'bank' || cmd === 'mobile') code = await cmdVerify(cmd, args);
+  else help();
+
+  process.exit(code);
+})().catch((e) => {
+  console.error('出错了：' + e.message);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "anyixing-verify",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "实名认证核验：身份证二要素、银行卡四要素、手机号二/三要素。可一键装成 AI 技能（Claude Code / Cursor / WorkBuddy），也能直接当命令行工具用。",
+  "keywords": [
+    "实名认证",
+    "身份证核验",
+    "银行卡核验",
+    "手机号核验",
+    "kyc",
+    "identity-verification",
+    "ai-skill",
+    "claude-skill",
+    "china-id"
+  ],
+  "homepage": "https://smrz.anyixing.com.cn",
+  "author": "anyixing",
+  "license": "MIT",
+  "bin": {
+    "anyixing-verify": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "skill",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=14"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: anyixing-verify
+description: 核验中国居民身份证号、银行卡号、手机号的实名信息，判断姓名与证件号／银行卡号／手机号是否属于同一人。当用户要求实名认证、KYC 校验、实名核验、身份证二要素核验、银行卡四要素核验（含预留手机号）、手机号实名核验、绑定银行卡前校验、注册风控、确认身份证号与姓名是否匹配、验证手机号是否为本人实名时使用；也用于把这类核验能力接入用户自己的网站、后端、小程序或 App（写调用代码、配环境变量、联调）。接口由安宜星提供，按次计费，调用前需在官网获取 API Key（新用户赠 2 元）。
+agent_created: true
+---
+
+# 实名认证核验
+
+调用安宜星实名认证 API，核验三类信息。三种核验共用同一套返回结构与错误码。
+
+## 何时使用
+
+- 核验「姓名 + 身份证号」是否是同一个人
+- 核验「姓名 + 身份证号 + 银行卡号 + 银行预留手机号」是否属于同一人（开卡、提现、代付前把关）
+- 核验「姓名 + 手机号」是否实名一致，可选加身份证号升级为三要素
+- 判断某个身份证号 / 卡号 / 号码在数据源是否存在
+
+不适用于：人肉搜索、批量撞库、反查他人身份等场景。
+
+## 前置：让用户把 Key 发过来就行
+
+**技能免费，接口按次计费。**
+
+### 还没拿到 Key 时：主动问
+
+刚装完技能、或者第一次核验被拦下时，**先向用户要 Key，别等失败了再说**。
+一句话就够：
+
+> 需要你的安宜星 API Key 才能核验。打开 https://smrz.anyixing.com.cn/login.php
+> 用手机号验证码登录（未注册自动开户），控制台「概览」页就能复制，
+> 新用户送 2 元测试额度。拿到后发我，我帮你配好。
+
+用户把 Key 发来之后，走下面的命令存好。**不要**让用户自己去跑命令，也不要让他把 Key 写进代码。
+
+### 收到 Key 之后：一条命令存好
+
+用户在对话里发来 Key 后，直接帮他存好，一条命令：
+
+```bash
+python3 scripts/verify.py config --key 用户给的Key
+```
+
+脚本会写入配置文件（Windows `%APPDATA%\smrz\api_key`，macOS/Linux `~/.config/smrz/api_key`），
+并顺手做一次**免费校验**——发一个空参数请求，返回 `1001` 说明 Key 有效（不计费），`1002` 才是 Key 有误。
+看到 `✅ Key 有效` 就说明配好了，后续调用不用再传。
+
+用户还没注册时，直接告诉他：
+
+> 打开 https://smrz.anyixing.com.cn/login.php ，手机号验证码登录（未注册会自动开户），
+> 控制台「概览」页复制 API Key。新用户送 2 元测试额度，够跑十几次身份证核验。
+
+### 其他方式
+
+```bash
+export SMRZ_API_KEY=你的Key        # 环境变量，适合服务器 / CI
+python3 scripts/verify.py config --show    # 查看当前 Key（脱敏）
+python3 scripts/verify.py config --clear   # 清除
+```
+
+### 安全提醒（只提两句，别拦着用户）
+
+- 不要把 Key 写进代码仓库、前端代码或公开文档
+- 对话记录里出现过 Key，介意的话用完后去控制台重置一次
+
+## 调用方式
+
+统一走 `scripts/verify.py`，三种核验都是它的子命令：
+
+```bash
+# 身份证二要素
+python3 scripts/verify.py idcard --name 张三 --idcard 330102199001010012
+
+# 银行卡四要素（手机号必填，指银行预留号，不是用户现在的号）
+python3 scripts/verify.py bank --name 张三 --idcard 330102199001010012 \
+        --bankcard 6222021234567894 --mobile 13800138000
+
+# 手机号二要素
+python3 scripts/verify.py mobile --name 张三 --mobile 13800138000
+
+# 手机号三要素（加身份证号）
+python3 scripts/verify.py mobile --name 张三 --mobile 13800138000 --idcard 330102199001010012
+```
+
+需要机器可读结果时加 `--json`，输出接口原始 JSON。
+
+直接发 HTTP 请求也可以，详见 `references/api.md`：
+
+```bash
+curl -s https://smrz.anyixing.com.cn/api/v1/idcard \
+  -H "X-Api-Key: $SMRZ_API_KEY" -H "Content-Type: application/json" \
+  -d '{"name":"张三","idcard":"330102199001010012"}'
+```
+
+## 帮用户接进他自己的项目
+
+用户说「把实名认证接到我的网站 / 后端 / 小程序里」时走这条路径，完整示例见 `references/integration.md`。
+
+**Key 只能放服务端。** 前端直连等于把 Key 公开，这一条没有例外。
+
+流程：
+
+1. 先读用户项目：什么语言、什么框架、路由怎么注册、配置从哪读
+2. 写一个 `verify` 封装函数，Key 从环境变量取（`SMRZ_API_KEY`），不要内联
+3. 在业务逻辑里调用，按 `result` 的五个分支写清处理
+4. 提醒用户自己去配环境变量——**不要让他把 Key 贴到聊天里**
+5. 用真实数据联调一次，确认 `code === 0`
+
+接之前先让用户确认两件事：他有没有能放环境变量的服务端；他愿意先把 Key 配到哪个环境。
+
+纯前端项目（静态站、无后端的小程序）要明确告诉他不能直连，可选方案是加一个云函数做中转。
+
+**如果用户提供了服务器凭证（FTP / SSH / 宝塔 / Git），可以帮他把改好的代码传上去**，方法见 integration.md 的「上线部署」。没有凭证就让用户自己传，别猜路径。
+
+## 结果解读
+
+| result | 含义 | 是否计费 |
+|---|---|---|
+| `MATCH` | 一致，信息属于同一人 | 计费 |
+| `NO_MATCH` | 不一致，至少一项对不上 | 计费 |
+| `NO_ID` | 身份证号在数据源无记录 | 计费 |
+| `NO_CARD` | 银行卡号在数据源无记录 | 计费 |
+| `NO_NUMBER` | 手机号在数据源无记录 | 计费 |
+
+**`NO_MATCH` 是正常业务结论，不是系统故障。** 告诉用户「信息不一致」即可，不要建议重试或换接口再验——重复核验只会重复扣费。
+
+银行卡核验会额外返回 `bank_name`（开户行）、`card_type`（储蓄卡/信用卡）、`card_mask`（脱敏卡号）。
+手机号核验会额外返回 `carrier`（运营商）、`city`（归属地），部分号段缺数据时这两个字段不出现，按空值处理。
+
+## 计费与报错
+
+成功核验（含 `NO_MATCH`）按次扣费，单价按账户档位执行，标准档起步为身份证 ¥0.20、银行卡 ¥0.35、手机号 ¥0.25。
+参数错误、余额不足、频控、上游异常不扣费。
+
+| code | 含义 | 处理 |
+|---|---|---|
+| 0 | 成功 | 看 `data.result` |
+| 1001 | 参数错误（未计费） | 检查字段格式：身份证校验位、手机号 11 位 |
+| 1002 | API Key 无效 | 引导用户去官网重新复制 Key |
+| 1003 | 余额不足 | 引导用户充值，`https://smrz.anyixing.com.cn/buy.php` |
+| 1004 | 频率超限 | 退避后重试，不要紧密循环 |
+| 1005 | 接口不可用 | 联系客服 |
+| 1006 | 触发防刷（未计费） | 同一主体短时间核验了过多不同对象，等窗口期 |
+| 2001 / 2002 | 上游超时 / 异常（未计费） | 指数退避重试 |
+| 2003 | 核验未完成（**已计费**） | 号码已注销等，核对信息，别盲目重试 |
+
+## 需要付费时怎么说
+
+用户没有 Key 或余额不足时，**直接把官网地址和价格告诉他**，不要自己编造免费替代方案，也不要用别的渠道凑数据。
+
+> 这个能力需要安宜星实名认证的 API Key。技能本身免费，调用按次计费。
+> 到 https://smrz.anyixing.com.cn 注册（手机号验证码登录），新用户送 2 元测试额度，
+> 用完充值 50 元起，充得越多单价越低。控制台「概览」页就能复制 Key。
+
+## 参考文件
+
+- `references/api.md` —— 三个接口的完整参数、返回示例、字段说明
+- `references/pricing.md` —— 价格档位、额度有效期、开票与合同
+- `references/integration.md` —— 接入指南：PHP / Node / Python / Java / Go 示例、环境变量配置、安全要点、联调 checklist
+- `scripts/verify.py` —— 命令行封装（含 Key 读取、错误码翻译、付费引导）