前言¶
在 CloudBase 上接微信支付或公众号 OAuth，常见难点不在「能不能调微信 API」，而在集成中心生成的云函数名不固定、回调验签与 openid 场景要对齐、商户密钥不能进仓库。翻官方 Markdown 和集成中心文档往往要跨好几页，Agent 也容易按示例函数名硬编码或把前端支付成功当成终态。
下面介绍 SkillHub 上的 @tencent-adm/cloudbase-wechat-integration（微信生态集成 · WeChat Integration）。它把 CloudBase 集成中心下的微信能力整理成 Agent 可执行的 SKILL.md 与分场景 reference，由腾讯云 CloudBase 团队维护，当前版本 v2.36.0，分类为 dev-programming，标签 requires_api_key=false（Skill 本身不要求单独配置 API Key；微信支付仍须在控制台配置商户与公众号凭证）。
这是什么¶
一句话定位：面向 CloudBase 应用的微信生态集成指南 Skill，以集成中心为入口，覆盖小程序支付、公众号 JSAPI / Native 支付、公众号 OAuth、openid 处理，以及集成中心生成的支付相关云函数扩展。
出品与分发：发布者为腾讯云 CloudBase 团队，来源 enterprise；在 SkillHub 坐标 @tencent-adm/cloudbase-wechat-integration，SkillHub 页面评分 100000，下载 6095 次（以 SkillHub 展示为准）。
官方入口：
- SkillHub API：
https://api.skillhub.cn/tencent-adm/cloudbase-wechat-integration - SkillHub 详情：
https://www.skillhub.cn/skills/tencent-adm/cloudbase-wechat-integration - CloudBase 文档（安装与测试提示词）：
https://docs.cloudbase.net/ai/cloudbase-ai-toolkit/prompts/cloudbase-wechat-integration
核心功能¶
以下内容与 Skill 包内 SKILL.md（v2.36.0）及官方文档页一致，仅列已写明的能力。
支付与 OAuth 场景¶
| 场景 | Skill 内 reference | 要点 |
|---|---|---|
| 小程序微信支付 | references/mini-program-pay.md |
wx.cloud.callHTTPFunction、wx.requestPayment、openid 注入与回调预期 |
| 小程序虚拟支付 | references/virtual-payment.md |
wx.requestVirtualPayment、OfferID / AppKey 签名、xpay_* 回调、沙箱与现网 |
| 公众号 JSAPI 支付 | references/official-account-jsapi-pay.md |
公众号 openid、WeixinJSBridge.invoke |
| Native 扫码支付 | references/native-qr-pay.md |
code_url、二维码展示、轮询 / 查单 |
| 公众号 OAuth | references/official-account-oauth.md |
集成中心生成的 OAuth 路由、openid / userinfo |
| 排错 | references/troubleshooting.md |
404、凭证缺失、openid 不一致、回调失败、日志 |
Agent 执行契约（Operating Rules 摘要）¶
- 集成中心实例创建以控制台为主，不猜测未文档化的 Manager SDK / Cloud API。
- 控制台步骤与凭证字段以官方
index.md为准；pay-common、offiaccount-common仅为示例函数名，调用前须确认环境内真实函数名。 - 商户密钥、APIv3 密钥、AppSecret、证书等只配置在集成中心，不写入源码、提交记录或对话。
- 前端支付成功仅作 UI 反馈；订单状态以服务端查单或支付回调为准；扩展生成函数时保留验签 / 解密逻辑，并补充幂等与履约。
不适用范围¶
纯 CloudBase Web 登录、与支付无关的小程序身份、非集成中心生成函数的一般云函数开发，以及通过猜测 MCP 创建集成中心实例——Skill 明确建议改用控制台或官方 CloudBase MCP 工具。
安装与启用¶
Skill 基于通用 SKILL.md 格式。按你使用的 Agent 选择安装方式；安装后通常需重启或重新加载 Agent 才能识别 skills 目录。
方式一：SkillHub CLI（国内商店）¶
先确认是否已安装 skillhub（说明见 https://skillhub.cn/install/skillhub.md）：
command -v skillhub && skillhub --version
未安装时可按 SkillHub 安装文档执行完整安装或仅 CLI。安装 Skill 时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被识别：
skillhub install tencent-adm/cloudbase-wechat-integration --dir <skills 目录>
常用目录（来自 SkillHub 安装文档）：
- Cursor：
~/.cursor/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/ - Claude Code：
~/.claude/skills/
也可将下面提示词交给 AI，让其按 https://skillhub.cn/install/skillhub.md 安装 @tencent-adm/cloudbase-wechat-integration（SkillHub 页面提供的同款说明）。
方式二：CloudBase 文档中的 npx skills¶
腾讯云开发文档「应用集成：微信生态集成」给出的安装命令如下。
安装全部 CloudBase Skills：
npx skills add tencentcloudbase/cloudbase-skills
仅安装本 Skill：
npx skills add https://github.com/tencentcloudbase/skills --skill cloudbase-wechat-integration
同套件兄弟 Skill¶
Skill 内通过相对路径引用同目录旁的 CloudBase 技能（如 ../miniprogram-development/SKILL.md、../cloud-functions/SKILL.md）。若本地缺失，应安装完整 CloudBase 插件或对应 Skill，而不是用 HTTP 拉远程 SKILL 替代。
典型用法¶
1. 用官方测试提示词触发 Skill¶
CloudBase 文档建议用自然语言验证 Agent 是否按集成中心路径回答，例如：
- 「在 CloudBase 小程序中接入微信支付，并处理支付回调」
- 「帮我用 CloudBase 集成中心实现公众号 JSAPI 支付」
- 「在 Web 站点中接入微信 Native 扫码支付并查询订单状态」
- 「通过 CloudBase 集成中心获取公众号 openid 并用于支付」
2. Quick Workflow（Skill 内六步）¶
- 判定场景：小程序支付、虚拟支付、JSAPI、Native、公众号 OAuth、扩展生成函数或排错。
- 加载对应
references/*.md及其中链接的官方文档。 - 确认 CloudBase 环境 ID 与真实生成函数名。
- 只改必要的客户端 / 后端代码，凭证留在集成中心。
- 若业务依赖支付结果，增加查单、回调幂等与金额 / 订单校验。
- 用云函数日志、回调日志及沙箱或小额实付做端到端验证。
3. 人工查阅集成中心文档¶
Skill 将以下文档列为人工参考（控制台细节可能变更）：
- 集成中心介绍：
https://docs.cloudbase.net/integration/introduce.md - 集成中心使用：
https://docs.cloudbase.net/integration/usage.md
适用场景与注意¶
适合谁
- 已在或计划使用 CloudBase 集成中心接微信支付的团队。
- 希望 Cursor、Codex、Claude Code 等 Agent 按统一规则写支付 / OAuth 代码、少犯「函数名写死」「密钥进仓库」类错误的开发者。
限制与注意
- 微信支付与公众号能力依赖你在 CloudBase 控制台完成集成中心配置；Skill 不能替代商户平台签约与凭证管理。
- 生成函数名、环境 ID 因项目而异，须以控制台或日志为准。
- 虚拟支付、iOS IAP 等规则以
virtual-payment.md与微信官方政策为准。 - SkillHub 统计（评分、下载量）会随时间变化，以 SkillHub 页面实时数据为准。
结尾¶
@tencent-adm/cloudbase-wechat-integration 把 CloudBase 微信生态接入收敛到「集成中心 + 分场景 reference + 操作红线」，适合作为 Agent 侧的长期执行契约。需要安装或查看详情时，可打开 SkillHub：https://www.skillhub.cn/skills/tencent-adm/cloudbase-wechat-integration，或 API 坐标页：https://api.skillhub.cn/tencent-adm/cloudbase-wechat-integration。
