museum-treasures

概述

给定一座博物馆，返回其 3 件镇馆之宝：每张含 照片(imageUrl)、名称、简介，并标注 版权信息（权利类型 / 许可 / 署名 / 图片权利说明）。适合亲子参观前做攻略、写博物馆科普、做内容素材检索。

何时使用

• 用户想了解某座博物馆最值得看的 3 件藏品（"故宫有什么镇馆之宝？""陕历博必看什么？""给我列一下国博的镇馆之宝"）。
• 用户需要带图片、可溯源、标注了版权状态的文物介绍素材。
• 不适用于：要全馆藏品清单、要某一类文物（如"所有青铜器"）、要实时展览信息——本 skill 仅返回每馆精选的 3 件镇馆之宝。

输入

• museumName（字符串）：博物馆全称或常用别名。后端已内置别名归一表，v1 已收录（查询即有结果）：
  • 故宫 / 国博 / 陕历博 / 上博 / 南博（南京博物院）/ 豫博（河南博物院）/ 湘博（湖南博物院）/ 湖北省博物馆 / 辽博 / 川博。
  • 更多馆（首博、浙博、苏博、三星堆、兵马俑、天津、山东、广东 等）随数据收集持续扩充；暂未收录的馆查询会返回 404，请先确认馆名在上方支持列表中。
  • 也接受官方全称（如"故宫博物院""陕西历史博物馆"）。

调用流程（付费编排 · 严格遵守）

端点：POST https://museumcheck.cn/skillhub/museum-treasures（可用环境变量 TREASURE_API_BASE 覆盖）。

前置检查（必须，发起支付前执行）：先确认 weixinpay_pay 支付插件已在当前 Agent 环境安装并可用；若未安装或未授权，应明确提示用户先安装/授权 weixinpay 插件，再继续后续支付流程，切勿在缺少支付能力时直接重试原请求（否则只会反复拿到 402）。

1. 发起请求：带 JSON body {"museumName": "<名称>"} 调用上面端点。
2. 若返回 HTTP 402（PAYMENT_REQUIRED）：
   • 从响应头取 WeixinPay-Required（即 paymentCode）和 X-Out-Trade-No。
   • 通过平台微信支付能力（weixinpay_pay）以该 paymentCode 向用户发起 ¥0.01 授权，请用户用微信完成支付。
   • 支付成功后，用原请求体不变，加请求头 X-Out-Trade-No: <上面的值> 重新 POST 同一端点。
3. 若返回 HTTP 200：解析响应体 content，按「输出格式」呈现给用户（见下）。
4. 若返回 HTTP 404：馆名未收录或别名未命中。若响应带 candidates 可提示用户近似馆名；否则请用户换用官方全称，或告知我们补充该馆数据。

便捷方式：本 skill 附 scripts/query.js，可代为发起 POST 并解析 402/200/404；支付步骤仍由你（agent）通过 weixinpay_pay 完成后再带 --out-trade-no 重试。本地联调时可用 node scripts/query.js "故宫" 与 node scripts/query.js "故宫" --out-trade-no <no>。

输出格式（呈现给用户）

对返回的 3 件 treasure，逐件展示：

• 名称（含朝代/年代、类别如有）
• 照片：直接展示 imageUrl（公有领域/知识共享授权图片，可外链）
• 简介：description
• 版权信息：rights 字段——权利类型(rightsType ∈ OWNED/PD/CC/THIRD_PARTY)、许可(license)、权利人(copyrightHolder)、署名要求(attribution)、图片权利说明(imageRightsNote)。

末尾必须附免责声明（响应体已含 disclaimer，原样展示或转述）：

本服务收取的是信息检索与整理服务费，不包含任何图片版权授权。图片版权归原权利人所有，用户须自行确保对结果的后续使用符合相关法律规定。

版权与合规（重要）

• 我们收取的是 信息检索与整理服务费，不是图片售卖；图片版权与授权归原权利人。
• 每条结果都标注 rightsType 与许可信息，用户须自行对 后续使用（转载、商用、再创作）的合规性负责。
• 文物本体多为 公有领域(PD)；所链接图片的拍摄/上传者按 CC0 / CC BY / CC BY-SA 等许可署名。现代作品（如张大千临摹）仍在版权保护期，标记为 THIRD_PARTY，v1 暂不提供第三方图片。
• 我们正持续积累 自有版权(OWNED) 数据，未来收费会按是否为自有版权区别对待。

异常处理（必须覆盖，避免用户资损）

• 用户未支付 / 支付超时 / 支付失败：不要重复发起原请求，也不要静默重试；应明确提示用户支付未完成，引导其通过 weixinpay_pay 重新发起 ¥0.01 支付，拿到新的 WeixinPay-Required（即 paymentCode）后，用原请求体 + 新 X-Out-Trade-No 重试。
• 支付成功但同请求仍返回 402：说明 X-Out-Trade-No 未正确回传或订单号不匹配，先核对请求头是否携带正确值再重试；若连续失败应立即停止重试并告知用户，避免重复扣费。
• 退款：本服务按次计费，单笔 ¥0.01 为测试价。若用户重复支付、支付后未获得结果或对结果不满意，应协助用户在 skillhub 平台发起退款申请，退款按微信支付与平台规则处理；未经用户确认不得代为发起额外支付。
• 接口异常（5xx / 超时 / 网络错误）：采用有限次退避重试，超过阈值（建议 ≤3 次）则明确告知用户服务暂不可用，不可在无确认情况下反复扣款。

限制

• v1 收录范围：已收录馆（故宫、中国国家博物馆、陕西历史博物馆、上海博物馆、南京博物院、河南博物院、湖南博物院、辽宁省博物馆、四川博物院、湖北省博物馆、三星堆 等），每馆精选最多 3 件；名单随数据收集持续扩充。
• 单馆固定返回 3 件（不足 3 件时返回实际数量）。
• 价格为测试价 ¥0.01/次；正式定价以后续公告为准。