trustbase-seller-backend 0.1.5

package/.agents/skills/wechatpay-payment-integration/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: wechatpay-payment-integration
+description: 微信支付（WeChat Pay）相关问题的统一入口，处理与微信支付接入、产品、开发、运营、品牌经营相关的咨询，提供产品选型、官方示例代码、接入质量评估、答疑与排障。Use when user mentions "微信支付", "微信收款", "WeChat Pay", "JSAPI", "APP支付", "H5支付", "Native支付", "扫码支付", "付款码", "小程序支付", "合单支付", "医保支付", "微信支付分", "分账", "转账", "委托代扣", "周期扣款", "代金券", "商家券", "特约商户进件", "服务商", "sub_mchid", "APIv2", "APIv3", "回调", "签名", "证书", "错误码", "OpenID", "品牌经营", "品牌经营平台", "品牌门店", "商家名片", "名片会员", "商品券", "摇一摇有优惠", "摇优惠", "品牌入驻", or asks to "推荐支付方式/产品选型", "要接口或示例代码", "做接入代码质量审查/上线前检查", "解释字段含义或接口规则", "排查报错/查单/支付问题".
+author: wechatpay
+version: "1.2"
+disable: false
+---
+
+# 微信支付全产品接入指引
+
+## 全局交互规范
+
+> ‼️ 本规范对所有意图、所有对话轮次通用，优先级高于各意图局部规则。
+
+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. **加载通用文档**（加载时）：
+   - [📄 基础概念及业务介绍](./references/基础概念及业务介绍.md)
+   - [📄 知识库使用指南](./assets/wechatpay-docs-guide.md)
+
+---
+
+## 核心工作流
+
+> 一切皆知识检索。产品选型、示例代码、接入质量评估、答疑与排障都走同一条检索循环；差别只在**意图对应的检索路径**不同。
+>
+> 进入工作流前，必须先 `Read` [📄 文档检索与问答](./references/文档检索与问答.md) 获取完整检索循环，**禁止跳过该文档直接自行搜索/读取知识库**。
+
+### 规则
+
+1. **每轮对话都先 CLI search，再本地查**：「一轮」= 用户说一次话到你给出回答或反问。每轮**第一件事**是调 CLI search（`knowledge search`）拿线索，**禁止**在它之前对知识库做 `Grep` / `Read` / 列目录。用户再说话（含回答澄清）是新一轮，重新 search。命令与字段见 [wechatpay-dev-cli使用说明](./references/wechatpay-dev-cli使用说明.md)。
+2. **CLI search 每轮只调一次**：拿到线索后，本轮检索都在本地 `Grep` / `Read` 完成，换词、回退意图起点、换方向也一样。
+3. **没线索也照常查**：CLI 没给出线索只是这次没命中，不是失败；直接在当前意图的检索路径上本地 `Grep`。只有命令跑不起来才按 CLI 说明「失败降级」。
+4. **默认意图**：无法明确匹配时，一律按「答疑与排障」处理。
+5. **意图可切换**：换意图后按新路径重新定位方向。
+6. **澄清在精读之前**：要反问就停在反问，不要先精读或先作答。判定见 [如何理解用户问题](./references/如何理解用户问题.md)。
+7. **查真实订单走接口**：文档答完仍要看这笔交易当前状态时，征得同意再进 [APIv3接口动态排障](./references/APIv3接口动态排障.md)。不要为此再调 `knowledge search`。
+
+### 步骤（必须按顺序）
+
+```mermaid
+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**：按 [如何理解用户问题](./references/如何理解用户问题.md) 理解问题、保留用户原话，然后 CLI search 拿线索。
+2. **需要澄清则本轮停在这里**：只反问则本轮结束，用户答复算新一轮。
+3. **判定意图**：按 [意图细则](#意图细则) 选定意图与检索路径；无法明确匹配时走「答疑与排障」。
+4. **检索循环**：拿到线索后，按 [文档检索与问答](./references/文档检索与问答.md) 用本地 `Grep` / `Read` 查知识库。
+5. **作答**：按下方意图细则生成回答。需查单时走动态排障。
+
+---
+
+## 意图细则
+
+路径由意图决定；何时选用哪条见下表，细则见各小节。
+
+| 意图 | 何时选用 | 检索路径 |
+| --- | --- | --- |
+| 产品选型 | 不确定用哪个产品、要对比/选型 | `<SKILL目录>/assets/wechatpay-product-overview.md`；选券时再按角色读对应「商品券」产品文档 |
+| 示例代码 | 要某接口的示例代码或接口文档 | 目标产品 `API列表/` 下请求示例 |
+| 接入质量评估 | 审查已有接入代码 / 上线前检查 | [接入质量检查清单](./references/接入质量检查清单.md) + 目标产品「开发指引」中的注意事项 |
+| 答疑与排障 | **默认**。知识查询、字段含义、错误码、规则、流程等 | `<SKILL目录>/assets/微信支付官网文档/` 全库 |
+
+### 产品选型
+
+> 当用户不确定该用哪种微信支付产品、或想了解各产品区别和适用场景时使用。
+
+```mermaid
+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）**：按[知识库使用指南](./assets/wechatpay-docs-guide.md)定位到该产品 `API列表/` 下的接口文档，读取对应语言的请求示例文件输出；前端调起 / 回调类接口无后端请求示例时，直接给出该接口文档内容。
+3. **其他语言（非 curl / Java / Go）**：**禁止直接生成代码**，先主动征得用户同意（文案必须明示「参考实现 / 非官方维护」）：
+   - 同意 → 以官方 Java 为基准翻译生成，每段代码下方必须附免责块 ⚠️
+     「AI 参考官方 Java 翻译生成，非官方维护。」
+     「请开发人员自行审查 AI 生成的代码逻辑，上线前充分测试以确保其适用性与准确性，AI 不对生成代码的正确性承担责任。」
+   - 未同意 → 只发官方 curl / Java / Go 文档链接（curl 不依赖特定编程语言，适合作为兜底参考）。
+
+### 接入质量评估
+
+> 当用户希望对已有的接入代码做质量审查或上线前检查时使用。
+
+加载：[接入质量检查清单](./references/接入质量检查清单.md)
+
+1. 加载接入质量检查清单（质检人设 + 三大铁律 + 通用问题雷达）。
+2. 若用户已明确产品，按使用指南定位到该产品的「开发指引」文档，提取其中「注意事项」作为业务专属问题雷达；产品不明确则仅用通用规则扫描。
+3. 合并「通用清单 + 业务专属注意事项（如有）」→ 扫描 → 追链路 → 做预演 → 按 🔴🟡🟠 分级输出问题清单，致命问题置顶，每个问题给修复方向。
+
+### 答疑与排障
+
+凡是不属于产品选型 / 示例代码 / 接入质量评估的用户问题，一律按本意图处理。完整循环见 [文档检索与问答](./references/文档检索与问答.md)。
+
+---
+
+> 以下信息与技能能力无关，仅供查阅。
+
+## 📋 用户调研
+
+如果您有任何建议或反馈，欢迎填写：[微信支付 Skill 用户调研问卷](https://wj.qq.com/s2/26981880/3d9d/)
+

package/.agents/skills/wechatpay-payment-integration/references/APIv3/346/216/245/345/217/243/345/212/250/346/200/201/346/216/222/351/232/234.md

@@ -0,0 +1,234 @@
+# APIv3 接口动态排障
+
+> **定位**：本流程是 `SKILL.md` 核心工作流的**下游动作**（实时查单），不是一条知识检索路径。仅在检索作答后仍需验证交易状态、且用户明确同意时进入；不要用 `knowledge search` 把查单登记成知识检索。
+
+## 前置依赖
+
+进入本流程前，须确认 **`wechatpay-dev-cli` 已安装且可用**（安装详见 [wechatpay-dev-cli使用说明](./wechatpay-dev-cli使用说明.md)）。
+
+**未安装时**：按使用说明安装（公网 `npm install -g @tenpay/wechatpay-dev-cli`），安装后再次执行 `--version` 确认。
+
+校验通过后再执行后续的流程。
+
+## 流程
+
+```mermaid
+flowchart LR
+  A[1. 收集信息] --> B[2. api build 生成 signMessage]
+  B --> C[3. 获取签名/鉴权信息]
+  C --> C1[方式A：开发者自行提供鉴权要素]
+  C --> C2[方式B：本地 extract_and_sign 签名]
+  C1 --> D[4. api call]
+  C2 --> D
+```
+
+### 核心约定（流程编排，勿写入脚本输出）
+
+| 步骤 | 职责 |
+| ------ | ------ |
+| **Step 1 `api list`** | 确认 `mode`（merchant/partner）、接口ID 与查单参数，组装 `--params` JSON |
+| **Step 2 `api build`** | 用 Step 1 的 `--params` 生成 `signMessage`；缺参会报错，补全后重试；**Agent 从 CLI 输出的 JSON 中保存 `signMessage` 原文（禁止篡改）** |
+| **Step 3 方式 A** | 开发者回传 `Authorization` 头，或 `serial_no` + `timestamp` + `nonce_str` + `signature` |
+| **Step 3 方式 B** | 本机 `extract_and_sign` 对 Step 2 的 `signMessage` 签名，回传脚本结果 |
+| **Step 4 `api call`** | **仅使用 Step 3 回传**的 `serial_no` / `timestamp` / `nonce_str` / `signature` 拼 `Authorization`；可与 Step 2 嵌入的 timestamp/nonce **不一致**（方式 A 常见） |
+
+> 方式 B 须对 Step 2 的 `signMessage` **原样**签名，故回传的 `timestamp`/`nonce_str` 应与该串内一致。
+
+### CLI 与参数约定
+
+- 命令入口：`wechatpay-dev-cli`
+- **模式**：`--mode merchant`（普通商户）或 `--mode partner`（服务商/合作伙伴）
+- **业务参数**：`--params` 传 inline JSON 或 `@文件路径`（推荐 Windows 用 `@file`，避免 shell 剥引号）
+- **输出**：`list` / `build` / `call` 默认输出 JSON
+- **`api build` 示例**（`payment.QueryByOutTradeNo`，merchant）：
+
+**macOS / Linux**：
+
+```bash
+wechatpay-dev-cli api build payment.QueryByOutTradeNo \
+  --mode merchant \
+  --params '{"path":{"out_trade_no":"20260101001"},"query":{"mchid":"1900007291"}}'
+```
+
+**Windows PowerShell**（用 `@file` 传参，一行；Agent 终端下 inline JSON 易报 `CLIXML`）：
+
+```powershell
+[IO.File]::WriteAllText("$env:TEMP\wechatpay-params.json",'{"path":{"out_trade_no":"20260101001"},"query":{"mchid":"1900007291"}}'); wechatpay-dev-cli api build payment.QueryByOutTradeNo --mode merchant --params "@$env:TEMP\wechatpay-params.json"
+```
+
+## Step 1: 收集 API 请求信息
+
+### 1.1 确认身份类型
+
+请开发者确认身份（二选一）：
+
+- **普通商户** → `--mode merchant`
+- **合作伙伴（服务商）** → `--mode partner`
+
+> **勿泛化收集**：不要提前索要 `mchid` / `sp_mchid` / `sub_mchid`；先确定要排查的**接口ID**，再按 1.3 脚本输出逐项收集。
+
+### 1.2 查询接口目录
+
+在 1.1 确定 `--mode` 后，列出当前身份下支持的查单接口，供开发者选择要排查的接口ID：
+
+```bash
+wechatpay-dev-cli api list --mode <merchant|partner>
+```
+
+将 CLI 输出的接口列表展示给开发者，由其选定一个 **接口ID**（如 `payment.QueryByOutTradeNo`）。
+
+### 1.3 查询接口所需参数并收集
+
+针对选定的接口ID，查看该接口在对应 `mode` 下需要填写的 Path / Query 参数：
+
+```bash
+wechatpay-dev-cli api list <接口ID> --mode <merchant|partner>
+```
+
+根据 CLI 输出 JSON 中的 `parameters` 字段（`in=path` / `in=query` 且 `required=true`），向开发者**逐项**索要实际值，并组装为 `--params` JSON（path 参数放 `path`，query 参数放 `query`）。参数是否齐全在 Step 2 的 `api build` 中校验——缺参时 CLI 会报错（如 `错误: 缺少必填参数: mchid`），按提示补全后重试即可。
+
+---
+
+## Step 2: 生成待签名串（`api build`）
+
+Agent **在本地执行** `api build`（使用 Step 1 组装的 `--params`，传参方式见「CLI 与参数约定」），从 CLI 输出的 JSON 中读取并保存 **`signMessage` 原文**（**禁止篡改**）。若报缺参错误，回到 Step 1.3 向开发者补要对应字段后重试：
+
+```bash
+wechatpay-dev-cli api build <接口ID> \
+  --mode <merchant|partner> \
+  --params '<JSON>'
+```
+
+CLI 输出示例：
+
+```json
+{
+  "id": "payment.QueryByWxTradeNo",
+  "mode": "merchant",
+  "signMessage": "GET\n/v3/pay/transactions/id/4200003100202606015015753674?mchid=1900007291\n1554208460\n593BEC0C930BF1AFEB40B4A08C8FB242\n\n",
+  "timestamp": "1554208460",
+  "nonce_str": "593BEC0C930BF1AFEB40B4A08C8FB242"
+}
+```
+
+---
+
+## Step 3: 获取签名 / 鉴权信息
+
+### Step 3 开场话术
+
+```text
+Step 2 完成，待签名串已生成。
+
+---
+
+Step 3：获取签名值
+
+请选择一种方式：
+
+【方式 A】你已有签名结果，请任选一种回传：
+
+  1) 完整 Authorization 请求头（推荐）
+     示例：Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1900007291",nonce_str="593BEC0C930BF1AFEB40B4A08C8FB242",signature="...",timestamp="1554208460",serial_no="408B07E79B8269FEC3D5D3E6AB8ED163A6A380DB"
+
+  2) 分别提供以下 4 项（与请求头中字段一致）：
+     · API 证书序列号（serial_no）
+     · 时间戳（timestamp，秒级 Unix 时间）
+     · 随机串（nonce_str）
+     · 签名值（signature，Base64）
+
+【方式 B】还没有签名
+     我将提供一条可在本机终端执行的命令；执行后，把输出里「签名结果开始」到「签名结果结束」之间的内容整段复制回传即可。
+```
+
+> **流程约束**：Step 3 未拿到签名 / 鉴权信息前，不得进入 Step 4。
+
+### 方式 A：开发者自行提供
+
+- **选项 1**：原样粘贴完整 `Authorization` 请求头。
+- **选项 2**：分别提供 **API 证书序列号、时间戳、随机串、签名值**（对应 `serial_no`、`timestamp`、`nonce_str`、`signature`）。
+- **禁止**对开发者说「四元组」「鉴权四元组」等术语。
+- 回传的 `timestamp` / `nonce_str` 可与 Step 2 串内值不一致；Step 4 **只使用 Step 3 回传值**。
+- **不输出**本地脚本。
+
+### 方式 B：本地 `extract_and_sign`
+
+开发者选择方式 B 时：
+
+- **只输出一个命令代码块**（可选一句「请在本机终端执行」）；收尾说明：**将终端里「签名结果开始」到「签名结果结束」之间的内容整段复制回传**。
+- **禁止**：附「执行步骤」列表；在对话中出现「P12」「证书路径」「终端会提示输入密码」等；向开发者索要真实证书路径。
+
+拼接规则：
+
+| 参数 | Agent 如何填写 |
+| ------ | ---------------- |
+| `--signString` / `-SignString` | Step 2 保存的 `signMessage` 原文（单引号包裹） |
+| `--filePath` / `-FilePath` | 占位路径 `/path/to/apiclient_cert.p12` 或 `C:\path\to\apiclient_cert.p12` |
+| `--password` / `-Password` | Step 1 的 `mchid`（merchant）或 `sp_mchid`（partner） |
+
+**macOS / Linux 示例**（`mchid=1900007291`）：
+
+```bash
+bash <SKILL目录>/scripts/bash/extract_and_sign.sh \
+  --filePath "/path/to/apiclient_cert.p12" \
+  --password "1900007291" \
+  --signString 'GET\n/v3/pay/transactions/id/4200003100202606015015753674?mchid=1900007291\n1554208460\n593BEC0C930BF1AFEB40B4A08C8FB242\n\n'
+```
+
+**Windows 示例**（若报编码相关 `ParserError`，改用 `pwsh` 重试）：
+
+```powershell
+powershell -ExecutionPolicy Bypass -File "<SKILL目录>\scripts\powershell\extract_and_sign.ps1" `
+  -FilePath "C:\path\to\apiclient_cert.p12" `
+  -Password "1900007291" `
+  -SignString 'GET\n/v3/pay/transactions/out-trade-no/202606021034379036?mchid=1900006891\n1780912534\n05E839355D63BAB809D98A41D6210F24\n\n'
+```
+
+Agent 从开发者回传内容中，在 **「签名结果开始」与「签名结果结束」** 标识之间提取下列字段，供 Step 4 使用：
+
+| 终端行前缀 | 用途 |
+| ------------ | ------ |
+| `API 证书序列号（serial_no）:` | Step 4 `--serial_no` |
+| `时间戳（timestamp）:` | Step 4 `--timestamp` |
+| `随机串（nonce_str）:` | Step 4 `--nonce_str` |
+| `签名值（signature）:` | Step 4 `--signature` |
+| `API 证书中的商户号:` | Step 4.1 与 Step 1 商户号比对 |
+
+### 方式 B 预期输入（开发者从终端复制回传）
+
+开发者在本地执行方式 B 命令后，终端打印类似以下内容；**复制「签名结果开始」到「签名结果结束」整段回传给 Agent**：
+
+```
+---------- 签名结果开始 ----------
+API 证书序列号（serial_no）: 408B07E79B8269FEC3D5D3E6AB8ED163A6A380DB
+时间戳（timestamp）: 1554208460
+随机串（nonce_str）: 593BEC0C930BF1AFEB40B4A08C8FB242
+API 证书中的商户号: 1900007291
+签名值（signature）: ...
+---------- 签名结果结束 ----------
+```
+
+> 时间戳、随机串已包含在上述回传块内（与 Step 2 待签名串中一致），开发者**无需**单独回贴 JSON 中的 `timestamp` / `nonce_str` 字段。
+
+---
+
+## Step 4: 发起查询（`api call`）
+
+### 4.1 证书商户号校验（方式 B）
+
+比对 Step 1 收集的商户号与 **API 证书中的商户号** 是否一致：merchant 模式对 `mchid`；partner 模式对 `sp_mchid`（即服务商商户号）。
+
+### 4.2 发起 api call
+
+`--mode`、`--params`（传参方式见「CLI 与参数约定」）与 Step 1 / Step 2 相同；`--mchid`、`--serial_no`、`--timestamp`、`--nonce_str`、`--signature` 一律取自 Step 3 回传。响应为 JSON，解析 `status` 与 `body` 分析结果。
+
+```bash
+wechatpay-dev-cli api call <接口ID> \
+  --mode <merchant|partner> \
+  --mchid "<Authorization 中的 mchid>" \
+  --params '<JSON>' \
+  --serial_no "<Step3>" \
+  --timestamp "<Step3>" \
+  --nonce_str "<Step3>" \
+  --signature "<Step3>"
+```

package/.agents/skills/wechatpay-payment-integration/references/wechatpay-dev-cli/344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -0,0 +1,74 @@
+# wechatpay-dev-cli 使用说明
+
+> 本 Skill 用 CLI search（`wechatpay-dev-cli knowledge search`）拿检索线索；「APIv3 接口动态排障」另需 `api` 系列命令。何时调用见 `SKILL.md` 与 [文档检索与问答](./文档检索与问答.md)；本文件只讲命令怎么跑。CLI 缺参不报错；命令不可用时按下方「失败降级」，不阻塞作答。
+
+## 前置步骤
+
+> 本会话**第一次**跑 CLI 前做一次即可，已确认过就直接用命令。本步只确认 CLI 能跑，**不要**顺带 `Grep` 知识库或列目录。
+
+```bash
+wechatpay-dev-cli --version   # 依赖 Node.js ≥ 20，包名 @tenpay/wechatpay-dev-cli
+```
+
+- **跑通且 ≥ 基线版本 `1.2.0`（2026-09-14）**：直接用命令，不要反复覆盖安装。
+- **跑不通或低于基线**：执行一次 `npm install -g @tenpay/wechatpay-dev-cli@latest`（一律装 `@latest`）后重跑 `--version`。
+- **仍失败**：按下方「失败降级」，仅用本地 `Grep` / `Read` 继续，照常作答。
+
+> 基线是本 Skill 发版时 npm 上的 `latest`，本地更高属正常；CLI 发新版后同步更新此处版本与日期。
+
+---
+
+## 规则
+
+1. **【红线】使用 `search` 参数时禁止夹带敏感信息**：APIv2 / APIv3 密钥、API 证书与私钥、`AppSecret` 这类密钥凭据，以及身份证、手机号、银行卡号这类个人敏感信息，**即使用户主动给出也不要带**——换成占位符或直接删掉。
+2. **参数尽量传全，缺参不重试**：每次 `search` 都带用户原话、`--query-rewrite`、`--context`、`--model-name`。缺字段 CLI 也会继续执行，**不要为补参重跑同一条命令**。
+3. **一轮只调一次**：本轮开头调一次 `search` 拿线索即可，后续检索全在本地 `Grep` / `Read`（见 `SKILL.md`）。
+
+### 失败降级
+
+缺参不是失败。**没返回线索也不是失败**——只是这次没命中，命令已经成功；直接在当前意图的检索路径上本地 `Grep`。
+
+只有命令不可用（`command not found`、未知命令 `knowledge`、超时、进程报错）时，才执行一次 `npm install -g @tenpay/wechatpay-dev-cli@latest` 重跑；仍失败就跳过 CLI，仅用本地 `Grep` / `Read` 继续。
+
+---
+
+## 命令释义 & 示例
+
+### `knowledge search`
+
+拿「该往哪个产品 / 目录查」的线索。**本轮进入本地 Grep / Read 之前必须先跑完本次命令**（或已失败降级）；不要先本地探路再补 CLI search。
+
+```bash
+wechatpay-dev-cli knowledge search "<用户问题的原文>" \
+  --query-rewrite "<理解后的问题>" \
+  --context "<当前项目的背景与任务>" \
+  --model-name "<当前模型名称>"
+```
+
+| 参数 | 含义 |
+| --- | --- |
+| 位置参数 `query` | **用户问题的原文**，只按[规则 1](#规则)去掉密钥凭据与个人敏感信息，其余不作改写；含双引号时做转义 |
+| `--query-rewrite` | **理解后的问题**（口语→可检索表述、指代消解）。原话中的 URL、接口路径、错误码、字段名原样保留 |
+| `--context` | **当前项目的背景与任务**：工程 / 任务上下文，例如「普通商户的 Node + Express 服务，正在接 JSAPI 支付的支付结果通知」。**不是**思考链，也不要传「产品选型 / 答疑与排障」这类分类名 |
+| `--model-name` | 执行本 Skill 的**模型名称**，按下方「`--model-name` 怎么填」自报 |
+
+**响应**：返回 `hint` / `keywords` 线索，用来校准 Grep 前缀；没有线索就按无线索本地 `Grep`，**不要**走失败降级。
+
+#### `--model-name` 怎么填
+
+你就是那个模型，直接写出自己的名称，这不属于猜测或编造。格式 `<系列>-<版本>`，例如 `claude-sonnet-4.5`、`gpt-5`、`gemini-2.5-pro`。记得完整版本就写完整；只确定系列就写到系列（如 `claude-sonnet`）。不得编造不存在的模型名，也不得填 `AI`、`assistant`、`模型` 这类无信息值。
+
+---
+
+## 常见问题
+
+| 现象 | 可能原因 | 处理 |
+| --- | --- | --- |
+| `wechatpay-dev-cli: command not found` | 未安装，或 npm 全局 bin 不在 PATH | 覆盖安装；确认 `npm config get prefix` 下的 bin 已加入 PATH |
+| `error: unknown command 'knowledge'` | 本地 CLI 版本过旧，尚无 `knowledge` 命令 | 执行 `npm install -g @tenpay/wechatpay-dev-cli@latest` 升级后重试 |
+| 未知选项 `--query-rewrite` / `--context` / `--model-name` | 本地 CLI 版本过旧，不认识这些参数 | 不要当成缺参。升级 CLI 后再试；升级失败则跳过 CLI、仅用本地 `Grep`。|
+| 没返回线索（无 `hint` / `keywords`） | 这次没命中目录线索 | **不是失败**。直接在当前意图的检索路径上本地 `Grep` |
+| `npm: command not found` | 未装 Node | 安装 Node.js 20+ |
+| 安装成功但 `--version` 仍报错 | Node 版本过低 | `node --version` 需 ≥ 20 |
+| Windows 下 `api build` 参数异常 | PowerShell 剥引号 | 按排障文档用 `@$env:TEMP\xxx.json` 传 `--params`，勿 inline 复杂 JSON |
+| 401 SIGN_ERROR | 非安装问题 | 回到排障文档 Step 2/3，检查 `signMessage` 是否原样签名 |

package/.agents/skills/wechatpay-payment-integration/references//345/237/272/347/241/200/346/246/202/345/277/265/345/217/212/344/270/232/345/212/241/344/273/213/347/273/215.md

@@ -0,0 +1,109 @@
+# 基础概念及业务介绍
+
+## 一、角色（接入模式）
+
+| | 普通商户 | 服务商 | 平台服务商（收付通） | 品牌商户 | 特约商户 |
+| --- | --- | --- | --- | --- | --- |
+| **一句话介绍** | 自己申请商户号，自己对接微信支付 API 收款 | 代特约商户对接微信支付；也可受品牌方委托代调品牌经营平台接口 | 先成为服务商，且底下不能有子商户，然后申请收付通权限；适用于电商/O2O 等平台类业务 | 拥有 `brand_id`，通过品牌经营平台（商家名片 / 摇优惠 / 商品券等）做用户运营 | 由服务商进件创建，获得 `sub_mchid`。特约商户可自行登录商户平台申请证书和密钥，用 `sub_mchid` 调用普通商户接口收款（电商子商户、小微/小商户、间连子商户除外） |
+| **商户号** | `mchid` | `sp_mchid` | `sp_mchid` | 无独立商户号，标识为 `brand_id` | `sub_mchid` |
+| **资金关系** | 结算到自己的商户账户 | 资金结算到特约商户，服务商通过分账获取佣金 | 资金先进入平台待分账账户，由平台发起分账到二级商户 | 品牌经营不涉及资金结算，属营销与用户运营 | 结算到自己的账户 |
+| **角色关系** | 独立运作，无上下级 | 一个服务商可管理多个特约商户；也可受多个品牌方委托 | 一个平台服务商下有多个二级商户 | 可由品牌独立接入，也可委托服务商代接（需在品牌经营平台授权） | 归属于某个服务商，由服务商进件创建 |
+
+---
+
+## 二、API 版本
+
+微信支付有三个文档/接口体系，各自独立鉴权：
+
+| 文档分支 | API 版本 | 鉴权方式 |
+| --- | --- | --- |
+| **APIv2** | V2（存量维护） | API 密钥签名（MD5 / HMAC-SHA256），XML 报文 |
+| **APIv3** | V3（主力版本） | 签名：商户API证书或私钥（`WECHATPAY2-SHA256-RSA2048`）；验签：微信支付公钥（推荐）或平台证书。JSON 报文 |
+| **brand** | 品牌经营专用 | 签名：品牌API证书或私钥（`WECHATPAY-BRAND-SHA256-RSA2048`）；验签：微信支付公钥（推荐）或平台证书。JSON 报文 |
+
+V2 存量维护，不再新增功能，V3 是主力版本。**默认使用 V3**，仅当产品/接口只有 V2 版本时才用 V2。若用户未指定版本，一律按 V3 提供，**严禁主动推荐或引导用户使用 V2**。
+
+---
+
+## 三、产品版本偏好
+
+除 API 版本（V2/V3）外，部分产品本身也存在新旧版本迭代（如商家转账升级版、移动医保支付 2.0 等）。**当同一产品存在多个版本时，默认按最新版本提供文档**；若用户使用旧版本，提示有新版本可升级。
+
+---
+
+## 四、核心 ID 及其关系
+
+| ID | 含义 | 归属 | 获取方式 | 与其他 ID 的关系 | 绑定操作 | 注意事项 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `mchid` | 普通商户号 | 普通商户 | 在商户平台自行申请 | 与 `appid` **多对多**绑定，绑定后方可发起支付 | 商户平台「账户中心-账户设置-APPID授权管理」发起绑定，appid 所在平台确认后生效 | 绑定后**不可解绑** |
+| `sp_mchid` | 服务商商户号 | 服务商 / 平台服务商 | 在商户平台申请服务商资质 | 与 `sub_mchid` 一对多；与 `mchid` 一对多（一个服务商可管理多个特约商户和普通商户） | 服务商平台「产品中心-APPID账号管理-我关联的APPID账号」新增关联 | — |
+| `sub_mchid` | 特约商户号 | 特约商户 | 由服务商通过进件接口创建 | 归属于 `sp_mchid`（一对多） | 服务商调用进件接口时自动创建归属关系，无需手动操作 | — |
+| `appid` | 应用 ID | 公众号 / 小程序 / 移动应用 / 网站应用 | 在公众平台或开放平台创建应用获得 | 与 `mchid` 多对多；与 `brand_id` **多对多**（一个品牌可关联多个 appid，一个 appid 也可关联多个品牌） | 品牌关联：品牌经营平台「账号管理-下单appid管理」；服务商关联：服务商平台「产品中心-APPID账号管理-我关联的APPID账号」 | appid 需先完成认证才能关联；未关联时调接口报 `AppID非法` |
+| `brand_id` | 品牌 ID | 品牌商户 | 在品牌经营平台申请/创建 | 与 `appid` 多对多；与 `mchid` 多对多（服务商代接时，一个服务商可服务多个品牌，一个品牌也可授权多个服务商） | 服务商代接：品牌在品牌经营平台授权服务商 | 未授权报 `NO_AUTH` |
+| `openid` | 用户标识 | 用户 × appid | 用户授权某个 appid 后生成 | 同一用户在不同 appid 下 openid 不同；与 `appid` 一一对应，下单时 openid 必须属于所传的 appid | 通过用户授权获取：H5/JSAPI 走网页授权、小程序走 `wx.login`、App 走开放平台授权 | openid 与 appid 不匹配会报错 |
+
+---
+
+## 五、证书与密钥
+
+| 维度 | 商户 API 证书 | 平台证书 | 微信支付公钥 | APIv3 密钥 | APIv2 密钥 | 品牌 API 证书 |
+| --- | --- | --- | --- | --- | --- | --- |
+| **概述** | 证明商户身份，生成请求签名 | 验证微信支付身份、加密敏感字段 | 平台证书的替代方案，功能一致，长期有效更易维护，推荐使用 | 解密 V3 回调通知数据 | V2 请求签名与验签（对称加密，MD5/HMAC-SHA256） | 证明品牌商户身份，生成 brand 接口请求签名。在品牌经营平台申请，与商户 API 证书是两套独立的证书和私钥，**不能混用** |
+| **数据形式** | apiclient_cert.pem + apiclient_key.pem + .p12 | wechatpay_xxx.pem（带有效期） | pub_key.pem（无有效期） | 32 位字母数字字符串 | 32 位字母数字字符串 | pem 格式（独立的证书序列号和私钥） |
+| **适用场景** | V3/V2 普通商户及服务商接口 | V3 验签应答/回调、加密姓名证件号等敏感字段（与微信支付公钥二选一） | V3 验签应答/回调、加密敏感字段（与平台证书二选一） | V3 回调通知解密 | V2 全部接口签名验签 | 仅用于 brand 品牌经营接口（签名类型 `WECHATPAY-BRAND-SHA256-RSA2048`），不能调 V3/V2 普通接口 |
+
+V2 和 V3 是两套独立体系，同一个商户号，两套体系可并存：
+
+- V2：APIv2 密钥 + 商户 API 证书
+- V3：APIv3 密钥 + 商户 API 证书 + 平台证书/微信支付公钥
+
+---
+
+## 六、营销业务全景与选型
+
+微信支付营销的核心是三大券能力，配合发券/投放工具触达用户：
+
+| 维度 | 商品券 | 代金券 | 商家券 |
+| --- | --- | --- | --- |
+| **定位** | 品牌优惠券全链路方案；单券（`stock`，单次核销）与多次优惠（`stock_bundle`，3-15 次阶梯核销）两种券型；可投放平台流量与商家自有流量 | 官方满减/单品换购工具；支付前发放、支付中自动核销（实付=订单金额−券额）；分预充值与免充值；支持全员/新人/抽奖等场景；卡包过期提醒+防刷 | 满减/换购/折扣三种券型；券码可微信生成或商户自定义（适配已有 Code 体系）；支持线上小程序核销与线下扫码核销。**已存量维护、不再迭代**（2025-12-15 起不受理新接入） |
+| **发券工具/渠道** | 摇一摇有优惠（平台流量）；向用户发放商品券 API 或小程序发券组件（商品券独有，和小程序发券插件是两套API）（自有流量） | 商户自有任意场景 API 发券（小程序/H5/App）、小程序发券插件 | H5发券、小程序发券插件、支付有礼（已升级至摇一摇） |
+| **区别点** | 微信平台流量、支付完成页互动领券；含单券/多次优惠 | 官方满减/折扣券，支付前发放、**支付中自动核销**（无需主动核销） | 已被商品券替代 |
+| **接口版本（接入模式）** | APIv3（服务商）/ brand（品牌） | APIv3（普通商户 / 服务商） | APIv3（普通商户 / 服务商） |
+| **功能状态** | **主力**（新接入推荐） | 在用 | **存量·不再迭代** |
+
+---
+
+## 七、重点：商品券
+
+### 7.1 两种发放场景
+
+商品券有两种发放场景，共享同一套品牌经营底座（`brand_id` + 商品券券源），区别在于触达入口与所需功能：
+
+**摇一摇有优惠（平台流量）**：用户支付完成后在微信侧"摇一摇·支付完成页"曝光领券。
+
+- 前置：品牌入驻(`brand_id`) + 商家名片或品牌门店（二选一，决定用户入口/按位置投放）+ 投放计划（选商品券 + 价格批次）
+- 服务商模式额外前提：品牌服务商授权(BM)
+- 接入流程：品牌入驻拿 `brand_id` → 建商家名片或品牌门店（二选一）→ 创建商品券 → 建投放计划（选券 + 价格批次）→ 摇一摇支付完成页曝光领券
+
+**商户API发券（自有流量）**：商户在小程序/H5/App 等场景主动发券，核心只需 `品牌入驻(brand_id)` + 创建商品券；无需投放计划，商家名片/品牌门店仅按需（按指定门店投放时才需建门店并关联批次）。
+
+- 接入流程：品牌入驻拿 `brand_id` → 创建商品券 → 自有场景调用「向用户发放商品券 API」或「小程序发券组件」发放 → 用户使用后调用「核销商品券」核销
+
+> 两种场景均可按「品牌直连」或「服务商代运营」接入：
+>
+> - 品牌直连：品牌用自己的 `brand_id` 操作，仅需关联下单 appid（BA 关系），无需 BM 授权。
+> - 服务商代运营：服务商用自己的 `mchid` 调用 APIv3 合作伙伴接口、请求携带目标 `brand_id` 代品牌操作；必须先经品牌授权（BM 关系）。
+
+### 7.2 核心概念
+
+**商品信息 vs 批次信息**：商品券由两层组成，首次创建会**同时创建**商品信息及第一个批次，后续可在同一商品券下追加批次（多批次属同一商品券，一个批次仅属一个商品券）。
+
+- **商品信息**（跨批次共享）：基础信息（券名称、商品图片、原价、展示信息）+ 优惠模式（优惠范围：全场/部分商品可用；券类型：满减/折扣/兑换；使用模式：单券/多次优惠）。
+- **批次信息**（每次投放可变）：优惠规则（可用时间、力度）+ 发放规则（券码分配、发放规则、可用门店范围）+ 使用展示规则。
+
+> 修改：商品层改用「修改商品券」，批次层改用「修改商品券批次」/「修改商品券批次组」；修改仅对新发券生效。
+
+**批次 vs 批次组**：
+
+- **批次**（仅单券模式）：一个批次发一张券、用一次即失效。有效期按单批次维度、各批次可独立设置。
+- **批次组**（仅多次优惠模式）：多个批次的有序集合，一次发放含多张券的"券组"。按顺序核销 3-15 次，每核销一轮微信侧再发下一轮券并回调领券结果。

package/.agents/skills/wechatpay-payment-integration/references//345/246/202/344/275/225/347/220/206/350/247/243/347/224/250/346/210/267/351/227/256/351/242/230.md

@@ -0,0 +1,55 @@
+# 如何理解用户问题
+
+## 概述
+
+对用户输入做**润色、纠错、指代消解**，全程保持原意，不增删关键事实。本步负责**理解用户要问什么**，并识别商户角色与 API 版本。
+
+## 原则
+
+- **忠实**：不改变用户要问什么。
+- **清晰**：消除歧义，多轮对话补全省略信息。
+- **节制**：能推断的不反复追问；不过度改写。
+
+## 多轮：指代消解
+
+当前问题依赖前文时：
+
+- 将「它 / 这个接口 / 上面那种」等还原为具体对象（产品名、接口名、错误现象等）。
+- 继承前文已确定的商户角色、API 版本、业务场景，避免答非所问。
+- 消解后仍须遵守「保留的技术原文」规则。
+
+## 单轮：润色与纠错
+
+**目标**：把零散、口语、含糊的表述整理成适合检索的规范问句。
+
+- **明确所问**：补全隐含条件，描述清楚「要什么、在什么场景下」。
+- **规范用语**：纠正错别字与明显笔误；口语可改为书面语，但不改变技术含义。
+- **去冗余**：删掉重复寒暄，保留与问题相关的关键实体与动作。
+
+### 保留的技术原文
+
+润色只整理表述，不改动用户已给出的技术细节。下列片段须**原样保留**（不得改写、替换或「纠正」字面内容，即使看起来像笔误）；仅可在其前后补充说明性文字：
+
+- 官方文档或接口 URL（含文档 `doc_id`）
+- 接口路径与 HTTP Method
+- 错误码、错误报文片段
+- 字段名、参数名、枚举值
+- 支付产品名、API 证书等官方术语
+
+## 角色与 API 版本判定
+
+供后续检索收敛范围。**多实体**（券 / 证书 / 密钥等）走知识库使用指南「用户描述模糊时的澄清话术」，与本节无关。
+
+**对比类**（如「V2 和 V3 的分账有什么区别」）本节不适用，用户要对比的各侧全部保留。
+
+判定顺序：**`AGENTS.md` → 用户原文 → 命中路径分布**。前两档能定就停；第三档只看路径落在哪一侧，不精读、不作答。商户身份与 API 版本均**无默认值**，歧义必须停下来问。
+
+1. 读项目根目录 `AGENTS.md`，已记录则直接采用。
+2. 否则从用户原文识别：角色对照 `<SKILL目录>/assets/wechatpay-docs-guide.md` 的「角色与文档路径对照」（`mchid`→普通商户、`sp_mchid`→服务商、`brand_id`→品牌商户等）；版本看是否点名 `APIv2` / `APIv3`。
+3. 仍无法确定则看命中路径：集中于单一角色或单一版本则按该侧收敛；跨多角色或 `APIv2`/`APIv3` 两侧都有则立即停止，只输出对应话术：
+
+     > 找到了以下角色下的相关文档：[列出命中的角色]。请问您需要全部查看，还是只看某个角色的文档？
+
+     > 找到了 APIv2 和 APIv3 下的相关文档。请问您需要全部查看，还是只看某个版本的文档？
+
+用户选定后，先问是否写入 `AGENTS.md`（同意则写入，后续自动采用，用户可随时自行修改），确认完再继续检索。本轮原文已明确指定的，可在作答后再问是否写入，不阻塞作答。