🤖 AI 执行摘要（先读这段）

• 何时触发：用户要查 / 找 / 下载中外文学术文献（论文、期刊、专利、标准、学位论文），或要写文献综述、找引用支撑、做课题查新。
• 不触发（转其他技能）：引用核查 / "这篇是真的吗" → smartlib-citation-checker；论文写作辅助、非文献类查询。
• 两个前置硬规则：① 动手前必须先向用户索取邮箱（禁止用 config 预填邮箱、禁止臆造邮箱）；② 每次计费接口调用前先 /consume 取 consume_token，再带 token 调 /search（token 单次使用、约 60s 有效，过期/已用需重新 /consume）。
• 输入：用户自然语言检索意图 + 邮箱。
• 产出：检索结果列表（含核心收录标注、原始数据库来源链接）、文献详情、PDF 下载链接（中文期刊直下 / 外文 OA 多渠道探测）。
• 配额模型：免费 100 次检索 + 10 次下载 / 月；耗尽时 Gateway 返回 429，技能自动弹出套餐卡片（体验卡 / 个人版月 / 专业版月 / 单篇下载 / 下载包），用户也可说「升级 / 充值」唤起；企业 / 机构定制联系 vipsmart@vipslib.com。
• 红线：不改功能；不臆造邮箱；不在对话中泄露 SMARTLIB_GATEWAY_SECRET；付费墙内外文文献无法获取全文。
• 凭证来源：config.json → SMARTLIB_GATEWAY_URL / SMARTLIB_GATEWAY_SECRET（SMARTLIB_EMAIL 运行后由注册写入，勿预填）。

全球12亿文献知识库（8千万中文期刊可下载）

通过 SmartLib 开放平台 API 提供中外文学术文献检索能力。

⚡ 启动前必须执行/ Pre-flight Checklist

Step A：凭证自动检测 & 注册/ Auto Credential Check & Registration

⚠️ 强制规则 — 必须先询问邮箱

1. 执行任何操作前，必须先询问用户邮箱地址
2. 禁止使用 config.json 中预填的邮箱（即使存在且非 null）
3. 禁止自动生成邮箱（如 user@example.com、auto@xxx.com 等）
4. 用户未提供邮箱 → 停止执行，回复：
5. 只有用户明确输入邮箱后，才能调用 /register 或 /quota

>

邮箱识别自动化

当用户消息中出现以下模式时，自动提取邮箱 → 无需再次询问：

• 明确的邮箱地址（包含 @ 符号的完整地址，如 xxx@xxx.xxx）
• "我的邮箱是 xxx" / "email: xxx" / "用 xxx 注册" / "邮箱 xxx"

每次执行本技能时，按以下流程处理凭证（从 config.json 读取）：

读取技能目录下的 config.json
检查 SMARTLIB_EMAIL 是否已配置
  ├── 已配置 → 进入 Step B (配额检查)
  │
        └── 未配置 → 验证码注册流程:
        ├── ① 展示检索计划 + 询问邮箱（一句话）:
        │      "📋 我将用中英文关键词检索... 首次使用需绑定邮箱（免费 100 次/月，仅用于配额管理），请输入邮箱即可开始:"
        │      用户输入 → 写入 config.json
        │
        ├── ② 发送验证码:
        │     POST {SMARTLIB_GATEWAY_URL}/register/send-code
        │     Body: {"email": "{用户邮箱}"}   ← 此接口无需鉴权头
        │
        │     返回 code_sent → 请用户查收 6 位数字验证码（15 分钟内有效，
        │       未收到提示检查垃圾邮件箱），收到后请用户把验证码发回来
        │     返回 already_registered → 该邮箱已注册，跳过 ③④ 直接进 Step B
        │     返回 429 → 发送过于频繁/IP 限流，按 retry_after_seconds 提示稍后再试
        │
        ├── ③ 提交验证码完成注册:
        │     POST {SMARTLIB_GATEWAY_URL}/register/verify
        │     Body: {"email": "{用户邮箱}", "code": "{6位数字验证码}"}
        │
        │     返回 registered → 注册+验证一步完成，提示:
        │       "✅ 注册成功！本月免费 100 次检索 + 10 次下载，可立即使用。"
        │     返回 verify_failed → 验证码错误或已过期 → 回到 ② 重发
        │     返回 403 disposable_email → 临时邮箱不可用，请用户换正式邮箱
        │
        └── ④ 继续 Step B 配额检查 → 检索

注意：注册需邮箱验证码（6 位数字，15 分钟有效）。注册即完成邮箱验证，后续调用不再弹验证。
适用范围：验证码仅针对新注册用户；存量老用户无需重新验证，正常使用不受任何影响。
长期套餐用户（机构/年包客户，由客服开通权益）：首次使用同样走上述验证码流程；完成验证后权益自动激活。若调用返回 403 email_not_verified，按 ②③ 完成验证即可，无需联系客服。

Step B：配额检查/ Quota Check

凭证就绪后, 调网关查询配额:
  GET <SMARTLIB_GATEWAY_URL>/quota?email=<SMARTLIB_EMAIL>
  Headers: {"Authorization": "Bearer <SMARTLIB_GATEWAY_SECRET>"}

  返回字段: total_remain, email_verified, plan, download_quota_free, download_reset_at, download_paid_remain, download_remain
  （完整返回: user_id, email, plan, trial_total, trial_used, trial_remain, paid_total, paid_used, paid_remain, paid_expires_at, total_remain, email_verified, download_quota_free, download_reset_at, download_paid_remain, download_remain）
  
  如果返回 404 "not_registered" → 用户可能已被重置/删除
    → 提示: "检测到您的账户需要重新绑定，正在重新注册..."
    → 跳回 Step A ②（验证码注册流程，使用同一邮箱）
    → 注册成功后继续配额检查

  ⚠️ 长期套餐用户判读: /quota 返回 plan=trial、paid_total=0 不代表权益未生效。
     长期套餐（机构/年包）额度由网关权益层独立管理；若响应含 longterm 字段，以该字段为准。
     判据以实际调用为准: 检索成功=权益生效; 返回 403 email_not_verified=需完成邮箱验证
     （走 Step A ②③）; 返回 429 rate_limited=触发周期限流（响应含 reset_at，勿重试等重置）;
     返回 403 quota_exhausted=总额度用尽需续期。
     请勿仅凭 /quota 的 trial 字段向用户断言"套餐不存在/未开通"，应以实际调用结果说明。

  total_remain > 20 → 静默进入检索
  total_remain 5-20 → 尾部轻提示: "📊 本月剩余 {n} 次"
  total_remain 1-5  → 警告: "⚠️ 接近用尽（剩余 {n} 次），已为你列出可用套餐（见下方💰章节），需要更高额度随时说「升级」"
  total_remain 0    → 配额耗尽处理（见配额耗尽章节）

  额外检查:

Step C：按接口调用次数消耗配额/ Per-API-Call Quota Consumption

本技能的配额按实际 API 接口调用次数计费，不是按对话会话计费。

共涉及 5 个接口（分3类），每次调用其中任意一个接口计 1 次配额。

Quota is consumed per API call, not per conversation session. 5 interfaces in 3 categories, each call = 1 quota.

计费接口清单（5个）/ Billable Interfaces (5 total):

注：全球文献（API 4）无全文下载接口，仅返回元数据。

计次示例

示例1：用户请求"查10篇工业母机论文，下载5篇中文PDF"
  → 检索接口：中文1次 + 英文1次         = 2 次
  → 详情接口：查5篇详情                   = 5 次
  → 下载接口：下载5篇PDF                  = 5 次
  → 合计消耗: 12 次配额

示例2：用户请求"帮我看看这篇论文的详情"（1篇）
  → 详情接口：1次                         = 1 次
  → 合计消耗: 1 次配额

示例3：用户仅请求"检索人工智能论文"（不查看详情、不下载）
  → 检索接口：1次（或2次，若中英文并行） = 1-2 次
  → 合计消耗: 1-2 次配额

扣减方式

⚠️ 强制执行规则：每次调用计费接口前，必须先调 /consume 获取 token，再用 token 调 /search。

每次调用计费接口的流程：

① POST <SMARTLIB_GATEWAY_URL>/consume
   Headers: {"Authorization": "Bearer <SMARTLIB_GATEWAY_SECRET>"}
   Body: {"email": "<SMARTLIB_EMAIL>", "skill_source": "global-biblio-base"}

   返回 200 → 获取 consume_token，继续
   返回 429 → 配额已用完，终止后续调用，按 §配额耗尽处理 自动弹出套餐选择

② POST <SMARTLIB_GATEWAY_URL>/search
   Headers: {"Authorization": "Bearer <SMARTLIB_GATEWAY_SECRET>"}
   Body: {
       "email": "<SMARTLIB_EMAIL>",
       "consume_token": "<上一步返回的token>",
       "skill_source": "global-biblio-base",
       "api_path": "/openapi/t/data0012/doccenter/Articlesearch",
       "api_body": {<检索请求体>}
   }

   返回 200 → 检索成功
   返回 401 → token 无效/过期/已用，需重新 /consume

MANDATORY: Call /consume → /search for EACH billable API call. Token is single-use, expires in 60s. If 401 on /search, re-consume.

🛡️ Token 绑定调用链

强制安全机制 — 不可绕过：
每次调用计费接口前，必须通过 /consume 获取 consume_token，然后将 token 传给 /search 代理端点。
Gateway 验证 token 签名 + 有效期 + 防重放后才转发检索请求。
Token 由 GATEWAY_SECRET 签名，AI 无法伪造。无有效 token 则 /search 直接 401。

>

调用流程

> 1. POST /consume {"email":"...", "skill_source":"global-biblio-base"} → 返回 consume_token > 2. POST /search {"email":"...", "consume_token":"...", "skill_source":"global-biblio-base", "endpoint":"/search/cn", "rule":"..."} > → Gateway 验证 token → 代理转发到检索 API → 返回检索结果 >

>

注意：每个 consume_token 只能使用一次（防重放），有效期 60 秒。每次检索 API 调用前都需要先 /consume 获取新 token。

🆕 仅成功调用消耗配额

/consume 仅验证配额可用性 + 签发 token，不预扣配额。配额在实际调用 SmartLib API 且返回成功后，由 Gateway 自动扣除。

失败的 API 调用不消耗配额（如参数错误导致 400、网络错误导致 500 等）。

/consume 返回的 total_remain, email_verified, plan 反映的是当前已成功调用的次数，非预扣后的值。

不计费的操作

💰 套餐与额度/ Plans & Quota

• 计费与升级由 SmartLib 统一钱包管理，所有文献检索技能统一定价、配额共享。
• 配额不足时自动弹套餐：检索或下载配额接近用尽 / 已耗尽时，技能直接在对话中弹出下方套餐选择卡片，无需用户说任何口令；用户也可主动说「升级 / 充值 / 购买 / 我要升级」唤起同一卡片。
• 企业 / 机构定制（API 接入、私有化部署）请联系 vipsmart@vipslib.com。

当前套餐

下载耗尽时优先推荐「单篇下载 / 下载包」；检索耗尽时优先推荐「体验卡 / 个人版月 / 专业版月」。

支付流程（对话内完成，用户回复数字即可）

`` 检测到配额信号（/quota 返回 quota_low / quota_exhausted，或 /consume 返回 429，或 download_remain==0） ↓ ① 渲染套餐卡片（数字①②③④⑤标注，如上表），并提示"回复数字选择，扫码即付" 用户回复数字 → 映射 plan key（如 "3" → pro_month） ↓ ② 创建订单（支付宝）: 下单前向用户披露：「下单需将您的注册邮箱发送至 SmartLib 支付端点，仅用于支付到账绑定与权益发放」 POST {SMARTLIB_GATEWAY_URL}/api/pay/alipay/create Headers: 无需认证（网关仅校验邮箱已注册，不要求 Authorization；严禁在对话/前端暴露任何密钥） Body: {"plan": "<plan_key>", "email": "<已注册用户邮箱>", "amount": <套餐价格，单位「元」，须与上表「价格」列完全一致>} ⚠️ email 必须是当前已注册用户邮箱（来自注册/配额上下文），严禁使用 config 里的 SMARTLIB_EMAIL（其值为 null）。 ⚠️ amount 必填且必须精确等于上方套餐表的「价格」（网关会校验，偏差 >0.01 元直接 400 amount_mismatch）。取值：trial_card=9.9 / personal_month=39 / pro_month=99 / single_download=2.5 / download_pack=20。严禁留空、严禁写 0、严禁用「分」（如 990 会被判成 ¥990 而失败）。 返回: {"qr_code", "out_trade_no", "amount", "plan", "quota", "channel":"alipay"} ↓ ③ 生成支付宝付款码 HTML：严格按 references/pay_page_template.html` 标准样例输出，仅替换其中的 {{占位符}}（订单号/二维码 base64/金额/套餐/脱敏邮箱/生成时间/过期时间），不得改变页面风格与文案，不得加载远程 JS/CDN（样式：支付宝蓝渐变头部+订单卡片+倒