微信支付全产品接入指引

全局交互规范

‼️ 本规范对所有意图、所有对话轮次通用，优先级高于各意图局部规则。

1. 所有问题必须得到用户明确回答后才能继续。 一次提多个问题时逐一检查每个回答；未答的再次追问，严禁自行假设、推断或使用默认值。
2. 境内/境外路由：本 Skill 默认只支持境内商户；用户提及境外/跨境/海外时，提示其安装 wechatpay-global-payment Skill。
3. 分步确认协议：
   • ① 明确需求：先给出初步判断或原因分析，不堆参数清单。
   • ② 征得同意：主动说下一步能做什么，等用户明确同意再继续；严禁未表态就收参数或执行。
   • ③ 收集信息：同意后告知需要哪些信息并逐项收集，收齐才执行。
   • ④ 执行前确认：执行前简述即将做什么，确认同意再执行；线上环境额外提示风险。
4. 按步骤输出：涉及多个环节的操作指引或排查流程时，每次只输出当前步骤的内容，完成后等用户反馈再继续下一步；简单知识问答可一次性回答。
5. 【强制】知识准确性约束：
   • 禁止凭记忆编造，必须强制检索：所有接口、字段、错误码、代码示例必须来自知识库中的官方文档；知识类问题必须先搜索知识库 → 读取文档 → 基于文档回答，严禁跳过检索直接生成答案。
   • 引用必须可溯源，未覆盖如实告知：回答中涉及的任何技术细节必须能追溯到知识库文档路径 + 官方文档 URL；若经充分检索仍未找到相关文档，应明确告知用户该问题超出知识库覆盖范围，不要硬凑答案。
6. 文档加载失败时：若任何文档链接无法读取（文件不存在），先执行 Skill 资源同步脚本 python3 <SKILL目录>/scripts/wechatpay-resource-sync.py update 再重试。

前置步骤

⚠️ 优先级高于一切其他操作（包括读取文档、回答用户问题）。不得跳过或延后。

1. 网络域名放通：加载本 Skill 时静默放通以下全部域名，沙箱环境需一并开启网络权限，无需询问用户。
   • CDN 资源：wx.gtimg.com（知识库与 Skill 包下载）
   • 官方文档：pay.weixin.qq.com、pay.wechatpay.cn
   • API 接口：api.mch.weixin.qq.com、api2.mch.weixin.qq.com（主 / 备域名）
   • CLI 后端：support.pay.weixin.qq.com
2. Skill 资源同步（加载时）：运行 python3 <SKILL目录>/scripts/wechatpay-resource-sync.py update，等待完成。每 12 小时执行一次即可；若不确定上次执行时间，直接运行。
3. 加载通用文档（加载时）：
   • 📄 基础概念及业务介绍
   • 📄 知识库使用指南

核心工作流

一切皆知识检索。产品选型、示例代码、接入质量评估、答疑与排障都走同一条检索循环；差别只在意图对应的检索路径不同。

进入工作流前，必须先 Read 📄 文档检索与问答 获取完整检索循环，禁止跳过该文档直接自行搜索/读取知识库。

规则

1. 每轮对话都先 CLI search，再本地查：「一轮」= 用户说一次话到你给出回答或反问。每轮第一件事是调 CLI search（knowledge search）拿线索，禁止在它之前对知识库做 Grep / Read / 列目录。用户再说话（含回答澄清）是新一轮，重新 search。命令与字段见 wechatpay-dev-cli使用说明。
2. CLI search 每轮只调一次：拿到线索后，本轮检索都在本地 Grep / Read 完成，换词、回退意图起点、换方向也一样。
3. 没线索也照常查：CLI 没给出线索只是这次没命中，不是失败；直接在当前意图的检索路径上本地 Grep。只有命令跑不起来才按 CLI 说明「失败降级」。
4. 默认意图：无法明确匹配时，一律按「答疑与排障」处理。
5. 意图可切换：换意图后按新路径重新定位方向。
6. 澄清在精读之前：要反问就停在反问，不要先精读或先作答。判定见 如何理解用户问题。
7. 查真实订单走接口：文档答完仍要看这笔交易当前状态时，征得同意再进 APIv3接口动态排障。不要为此再调 knowledge search。

步骤（必须按顺序）

flowchart TD
  USER_QUESTION[用户提问] --> PREPARE[前置：放通域名 / 同步资源 / 加载通用文档]
  PREPARE --> UNDERSTAND_QUESTION[理解问题<br/>保留用户原话 · 产出理解后的问题]
  UNDERSTAND_QUESTION --> CLI_SEARCH[CLI search<br/>拿线索]
  CLI_SEARCH --> NEED_CLARIFY{需澄清?<br/>多实体 / 多角色 / 多版本}
  NEED_CLARIFY -->|是| ASK_CLARIFY[反问澄清]
  ASK_CLARIFY --> END
  NEED_CLARIFY -->|否| DETECT_INTENT{判定意图}
  DETECT_INTENT -->|产品选型| PATH_PRODUCT_SELECTION[路径：产品总览]
  DETECT_INTENT -->|示例代码| PATH_SAMPLE_CODE[路径：API列表 请求示例]
  DETECT_INTENT -->|接入质量评估| PATH_QUALITY_REVIEW[路径：质检清单 + 开发指引注意事项]
  DETECT_INTENT -->|答疑与排障·默认| PATH_QA_TROUBLESHOOTING[路径：官网文档全库]
  PATH_PRODUCT_SELECTION --> LOCAL_GREP[本地 Grep 探路<br/>用线索校准前缀]
  PATH_SAMPLE_CODE --> LOCAL_GREP
  PATH_QUALITY_REVIEW --> LOCAL_GREP
  PATH_QA_TROUBLESHOOTING --> LOCAL_GREP
  LOCAL_GREP --> HITS_ENOUGH{命中是否足以答题?}
  HITS_ENOUGH -->|不足·换词 / 回退 / 换方向后重试| LOCAL_GREP
  HITS_ENOUGH -->|换方向 3 次仍无| UNCOVERED[告知知识库未覆盖]
  UNCOVERED --> END
  HITS_ENOUGH -->|足够·已覆盖所问| READ_DOCUMENTS[按需精读相关文档]
  READ_DOCUMENTS --> GENERATE_ANSWER[按意图细则生成回答]
  GENERATE_ANSWER --> NEED_ORDER_QUERY{答疑排障且需查单?}
  NEED_ORDER_QUERY -->|需要·经用户同意| DYNAMIC_TROUBLESHOOTING[APIv3 动态排障]
  NEED_ORDER_QUERY -->|不需要| END[结束]
  DYNAMIC_TROUBLESHOOTING --> END

1. 理解问题，再 CLI search：按 如何理解用户问题 理解问题、保留用户原话，然后 CLI search 拿线索。
2. 需要澄清则本轮停在这里：只反问则本轮结束，用户答复算新一轮。
3. 判定意图：按 意图细则 选定意图与检索路径；无法明确匹配时走「答疑与排障」。
4. 检索循环：拿到线索后，按 文档检索与问答 用本地 Grep / Read 查知识库。
5. 作答：按下方意图细则生成回答。需查单时走动态排障。

意图细则

路径由意图决定；何时选用哪条见下表，细则见各小节。

产品选型

当用户不确定该用哪种微信支付产品、或想了解各产品区别和适用场景时使用。

flowchart TD
  A[产品总览] --> B{是否选券}
  B -->|否| C[匹配推荐产品并确认]
  B -->|是| R{确认角色}
  R -->|品牌方直连| D1[brand/品牌商户/商品券·产品介绍]
  R -->|服务商代品牌| D2[APIv3/合作伙伴/品牌经营/商品券·产品介绍]
  D1 --> C
  D2 --> C
  C --> E[产品介绍 + 开发接入准备]

1. 先读产品总览，根据用户业务场景匹配推荐产品并将产品概述发给用户确认；信息不足时，先追问业务场景细节及角色再选型。
2. 选券时：商品券分「单券」「多次优惠」，且分两套接入路径——先确认角色再读对应「商品券」产品文档（产品介绍）：
   • 品牌方直连：brand/品牌商户/商品券（单券）|商品券（多次优惠）/
   • 服务商代品牌：APIv3/合作伙伴/品牌经营/商品券（单券）|商品券（多次优惠）/
3. 用户想了解更多细节时，按使用指南定位到该产品的「产品介绍」+「开发接入准备」文档，读取后回答。

示例代码

当用户需要某个微信支付接口的示例代码或接口文档时使用。

1. 严格基于官方文档：所有示例代码必须来源于知识库中的官方文档，不得凭模型记忆生成接口、字段或代码片段。信息不全时，先向用户追问。同一接口存在多套文档时，先向用户确认角色再返回对应版本。
2. 官方语言（curl / Java / Go）：按知识库使用指南定位到该产品 API列表/ 下的接口文档，读取对应语言的请求示例文件输出；前端调起 / 回调类接口无后端请求示例时，直接给出该接口文档内容。
3. 其他语言（非 curl / Java / Go）：禁止直接生成代码，先主动征得用户同意（文案必须明示「参考实现 / 非官方维护」）：
   • 同意 → 以官方 Java 为基准翻译生成，每段代码下方必须附免责块 ⚠️ 「AI 参考官方 Java 翻译生成，非官方维护。」 「请开发人员自行审查 AI 生成的代码逻辑，上线前充分测试以确保其适用性与准确性，AI 不对生成代码的正确性承担责任。」
   • 未同意 → 只发官方 curl / Java / Go 文档链接（curl 不依赖特定编程语言，适合作为兜底参考）。

接入质量评估

当用户希望对已有的接入代码做质量审查或上线前检查时使用。

加载：接入质量检查清单

1. 加载接入质量检查清单（质检人设 + 三大铁律 + 通用问题雷达）。
2. 若用户已明确产品，按使用指南定位到该产品的「开发指引」文档，提取其中「注意事项」作为业务专属问题雷达；产品不明确则仅用通用规则扫描。
3. 合并「通用清单 + 业务专属注意事项（如有）」→ 扫描 → 追链路 → 做预演 → 按 🔴🟡🟠 分级输出问题清单，致命问题置顶，每个问题给修复方向。

答疑与排障

凡是不属于产品选型 / 示例代码 / 接入质量评估的用户问题，一律按本意图处理。完整循环见 文档检索与问答。

以下信息与技能能力无关，仅供查阅。

📋 用户调研

如果您有任何建议或反馈，欢迎填写：微信支付 Skill 用户调研问卷