📝 #4071 新增 WxJava 用户技能(SKILL)指南

Author: binarywang

README.md

@@ -29,6 +29,7 @@
 
 ### 目录索引
 - [快速开始（3分钟）](#快速开始3分钟)
+- [AI 编程智能体 SKILL 安装](#ai-编程智能体-skill-安装)
 - [我该选哪个模块？](#我该选哪个模块)
 - [Maven 引用方式](#maven-引用方式)
 - [最小示例](#最小示例)
@@ -45,6 +46,41 @@
 2. 引入 Maven 依赖并选择对应模块
 3. 参考最小示例完成初始化并调用 API
 
+### AI 编程智能体 SKILL 安装
+
+仓库的 [`skills`](skills) 目录提供面向 WxJava 用户和贡献者的通用 SKILL，包括模块选择、接入、排障、接口贡献和升级迁移。每个 SKILL 都以 `SKILL.md` 为入口，可用于支持该约定的 AI 编程智能体。
+
+支持远程安装 SKILL 的智能体，可以直接使用自然语言指令安装所需目录。例如：
+
+> 安装 https://github.com/binarywang/WxJava/tree/develop/skills/wxjava-integration-guide 中的技能。
+
+可安装的 SKILL 包括：
+
+- [模块选择](https://github.com/binarywang/WxJava/tree/develop/skills/wxjava-module-selector)
+- [接入指南](https://github.com/binarywang/WxJava/tree/develop/skills/wxjava-integration-guide)
+- [故障排查](https://github.com/binarywang/WxJava/tree/develop/skills/wxjava-troubleshooter)
+- [接口贡献](https://github.com/binarywang/WxJava/tree/develop/skills/wxjava-api-contributor)
+- [升级迁移](https://github.com/binarywang/WxJava/tree/develop/skills/wxjava-upgrade-guide)
+
+不支持远程安装时，可将所需的 `skills/wxjava-*` 目录复制到智能体的 SKILL 目录或工作区配置目录；不同智能体的目录和启用方式请以其官方文档为准。
+
+以 Codex 为例，可复制到个人 SKILL 目录：
+
+```shell
+git clone https://github.com/binarywang/WxJava.git
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R WxJava/skills/wxjava-* "${CODEX_HOME:-$HOME/.codex}/skills/"
+```
+
+如果已在本仓库根目录，可直接执行：
+
+```shell
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R skills/wxjava-* "${CODEX_HOME:-$HOME/.codex}/skills/"
+```
+
+重启或新建智能体会话后，即可按需使用。例如：`使用 wxjava-integration-guide 为我的 Spring Boot 项目接入微信支付。`
+
 ### 我该选哪个模块？
 
 | 业务场景 | 模块 | artifactId |

skills/wxjava-api-contributor/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: wxjava-api-contributor
+description: 按 WxJava 的 Maven 多模块、Java 8、公共 API 兼容性和 TestNG 约定，为微信官方接口新增或维护 SDK 支持。适用于新增 Service API、请求响应 Bean、序列化、HTTP 实现、Starter 配置或回归测试时。
+---
+
+# WxJava 接口贡献
+
+1. 先搜索开放与已关闭 Issue，确认需求是否已有讨论、实现、回归用例或官方接口变动；再确认微信产品和目标模块。
+2. 阅读对应 README、POM、相似接口、实现与测试，并读取 [贡献约定](references/contribution.md)。
+3. 将官方接口契约映射到 Service、实现、Bean、URL、序列化和测试；列出所有可能受影响的 HTTP 客户端和 Starter。
+4. 只做完成需求所需的最小改动；更新必要 Javadoc、测试与用户可见文档。
+5. 执行 `mvn -pl <module> -am test`，并检查 `git diff --check`。
+
+保持 Java 8 与公共 API、异常语义、JSON/XML 字段兼容性。涉及多 HTTP 客户端、单/多账号 Starter 或 Solon 插件时，检查等价实现是否需要同步。PR 应关联对应 Issue，目标分支为 `develop`。

skills/wxjava-api-contributor/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "WxJava 接口贡献"
+  short_description: "按 WxJava 项目约定新增或维护 SDK 接口能力"
+  default_prompt: "使用 $wxjava-api-contributor 为 WxJava 新增微信接口支持。"

skills/wxjava-api-contributor/references/contribution.md

@@ -0,0 +1,19 @@
+# 贡献约定
+
+以微信官方接口定义和本仓库同类实现为准，核对路径、方法、字段名、必填项和响应结构。优先复用既有 HTTP 执行器、异常、配置、Gson/Jackson/XStream 映射和 TestNG 测试模式。
+
+公共方法需要准确 Javadoc。不要吞异常、记录敏感值或无关重构。新增公开方法和 bug 修复均应有针对性测试；涉及公共模块、BOM 或多模块时扩大验证范围。
+
+## 接口增量检查表
+
+1. 从微信官方文档和相关 Issue 中确认接口可用条件、HTTP 方法、URL、必填字段、签名/加密要求和响应示例。
+2. 搜索同产品的相邻能力，复用其 Service 分层、Bean 命名、请求执行和错误处理模式；不要只新增 Bean 而遗漏 Service 暴露。
+3. 若接口尚未支持，优先使用现有通用执行能力；MP/CP Wiki 说明通用执行器会处理 access token 刷新及 `errcode` 到异常的转换。
+4. 为字段边界、空值、JSON/XML 映射和异常路径添加 TestNG 回归测试。API 路径或字段问题是历史 bug 的高频来源，例如 [#3982](https://github.com/binarywang/WxJava/issues/3982)、[#4000](https://github.com/binarywang/WxJava/issues/4000)。
+5. 按 [贡献指南](https://github.com/binarywang/WxJava/blob/develop/CONTRIBUTING.md) 使用 `develop` 作为 PR 目标；说明 Issue、兼容性影响和验证命令。
+
+## 一手资料入口
+
+- [如何调用 MP 未支持接口](https://github.com/binarywang/WxJava/wiki/MP_%E5%A6%82%E4%BD%95%E8%B0%83%E7%94%A8%E6%9C%AA%E6%94%AF%E6%8C%81%E7%9A%84%E6%8E%A5%E5%8F%A3)
+- [如何调用 CP 未支持接口](https://github.com/binarywang/WxJava/wiki/CP_%E5%A6%82%E4%BD%95%E8%B0%83%E7%94%A8%E6%9C%AA%E6%94%AF%E6%8C%81%E7%9A%84%E6%8E%A5%E5%8F%A3)
+- [关闭的新接口 Issue](https://github.com/binarywang/WxJava/issues?q=is%3Aissue%20state%3Aclosed%20label%3A%E6%96%B0%E6%8E%A5%E5%8F%A3)

skills/wxjava-integration-guide/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: wxjava-integration-guide
+description: 为 Java、Spring Boot 或 Solon 项目生成可验证的 WxJava 接入方案，包括模块选择、BOM、配置、最小调用代码以及单/多账号集成。适用于用户要求接入公众号、小程序、支付、企业微信、开放平台、视频号或微信小店时。
+---
+
+# WxJava 接入指南
+
+1. 确认微信产品、框架、单/多账号、部署形态和首个 API 调用。
+2. 读取 [接入约束](references/integration.md)，选择模块和配置方式。
+3. 先输出依赖与配置，再输出最小调用；每段示例注明应放置的位置和所依赖的模块。
+4. 输出脱敏配置和最小服务端代码；凭据一律用占位符。
+5. 给出本地验证步骤与安全提醒；支付、回调和证书示例不得直接用于生产。
+
+保持 Java 8 兼容。生产集群必须使用可共享的配置存储或 token 存储；不要把内存实现当作多节点部署方案。引用已有 Demo、Wiki 或 README 作为继续阅读入口；不虚构配置键、SDK 方法或版本号。

skills/wxjava-integration-guide/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "WxJava 接入指南"
+  short_description: "生成可验证的 WxJava 最小接入方案与配置示例"
+  default_prompt: "使用 $wxjava-integration-guide 为我的项目生成 WxJava 接入代码。"

skills/wxjava-integration-guide/references/integration.md

@@ -0,0 +1,22 @@
+# 接入约束
+
+优先通过 `wx-java-bom` 统一管理多个 WxJava 模块版本。核心 SDK 模块是 MP、MiniApp、Pay、CP、Open、Channel、Qidian、Aispeech；框架集成模块位于 `spring-boot-starters` 与 `solon-plugins`。
+
+查阅相应模块 README、根目录 [demo.md](https://github.com/binarywang/WxJava/blob/develop/demo.md) 和目标模块测试中的示例，确认配置属性与初始化模式。所有 `appId`、`secret`、商户私钥、API v3 密钥和证书均使用占位符，不得输出到日志。
+
+## 实施检查表
+
+1. 先完成一条只读或低风险 API 调用，再接入消息、支付或异步回调。
+2. 单实例可使用默认配置存储；多实例或集群需使用共享的 token/config storage，避免节点各自刷新 access token。
+3. 公众号、企业微信等回调必须先按平台要求校验消息合法性，再进入业务路由；支付回调还必须按商户单号实现幂等。
+4. 需要代理或私有网络出口时，明确区分正向代理与反向代理。支付 V3 的签名路径不能因反向代理路径前缀而被错误改写。
+5. HTTP 客户端类型、Starter 配置键和 Service 实现必须取自目标模块的当前 README、POM 或相邻 Demo；不要混用不同产品模块的配置前缀。
+6. Starter 自动配置与 Demo 手动初始化必须二选一后再给示例。发生空 key、注入为空或 NPE 时，先核对启动模块、profile、配置前缀和当前 `*Properties` 类；历史 [#2177](https://github.com/binarywang/WxJava/issues/2177) 是混用两种配置模型的案例。
+7. Quarkus 或 GraalVM 场景转到 [Quarkus 支持文档](https://github.com/binarywang/WxJava/blob/develop/docs/QUARKUS_SUPPORT.md)，不要套用 Spring Boot Starter 配置。
+
+## 一手资料入口
+
+- [MP Quick Start](https://github.com/binarywang/WxJava/wiki/MP_Quick-Start)
+- [微信支付说明](https://github.com/binarywang/WxJava/wiki/%E5%BE%AE%E4%BF%A1%E6%94%AF%E4%BB%98)
+- [SDK 正反向代理支持](https://github.com/binarywang/WxJava/wiki/SDK-%E9%92%88%E5%AF%B9%E5%BE%AE%E4%BF%A1-%E6%AD%A3%E5%90%91%E4%BB%A3%E7%90%86%E5%92%8C%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86%E6%94%AF%E6%8C%81)
+- [HTTP 客户端升级指南](https://github.com/binarywang/WxJava/blob/develop/docs/HTTPCLIENT_UPGRADE_GUIDE.md)

skills/wxjava-module-selector/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: wxjava-module-selector
+description: 根据微信公众号、小程序、微信支付、企业微信、开放平台、视频号或微信小店、腾讯企点和微信智能对话等业务场景，为用户选择合适的 WxJava Maven 模块、BOM 和示例入口。适用于用户询问“该用哪个模块”、依赖坐标、产品边界或单/多账号 Starter 选择时。
+---
+
+# WxJava 模块选择
+
+1. 识别微信产品、服务端框架、是否多账号、是否包含支付或回调；信息不足时只询问必要问题。
+2. 读取 [模块映射](references/modules.md)，给出一个主推荐，以及组合模块的理由。
+3. 先区分产品边界，再选择核心 SDK；仅当项目确实依赖框架自动配置时才额外推荐 Starter 或 Solon 插件。
+4. 优先推荐 BOM；给出准确的 `groupId`、`artifactId`、相应 Demo、Wiki 或仓库文档入口。
+5. 说明服务端 SDK 的边界：移动端登录、分享等能力仍需微信官方客户端 SDK。
+6. 不臆测版本号；建议以 Maven Central 或项目 README 的当前版本为准。
+
+使用“场景 → 模块 → 集成选项 → 下一步”的简短结构。涉及多账号时说明单账号与 multi Starter 的区别；不要在示例中泄露凭据。支付和回调场景必须提醒用户验证通知 URL、验签与幂等处理。

skills/wxjava-module-selector/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "WxJava 模块选择"
+  short_description: "按微信业务场景选择 WxJava 模块、依赖与示例"
+  default_prompt: "使用 $wxjava-module-selector 为我的微信业务选择合适的 WxJava 模块。"

skills/wxjava-module-selector/references/modules.md

@@ -0,0 +1,37 @@
+# WxJava 模块映射
+
+| 场景 | 核心模块 |
+| --- | --- |
+| 微信公众号 | `weixin-java-mp` |
+| 微信小程序 | `weixin-java-miniapp` |
+| 微信支付 | `weixin-java-pay` |
+| 企业微信 | `weixin-java-cp` |
+| 微信开放平台／第三方平台 | `weixin-java-open` |
+| 视频号／微信小店 | `weixin-java-channel` |
+| 腾讯企点／微信客服 | `weixin-java-qidian` |
+| 微信智能对话／智能语音 | `weixin-java-aispeech` |
+
+多个模块并用时优先使用 `com.github.binarywang:wx-java-bom`。Spring Boot 集成从 `spring-boot-starters` 选择；Solon 集成从 `solon-plugins` 选择。
+
+## 多账号集成范围
+
+只有多个独立微信应用配置时才选择 multi 集成，并先按框架与产品核对目录是否存在：
+
+- Spring Boot：MP、MiniApp、CP、自建/第三方 CP、Pay、Open、Channel 都有相应 multi Starter。
+- Solon：仅 MP、MiniApp、CP、Channel 有 multi 插件；Pay、Open、Qidian 目前只有单账号插件，不要推荐不存在的 multi artifact。
+
+## 选择检查点
+
+- 公众号、小程序和企业微信的消息回调、token 与加解密配置彼此独立；不要因同属一个公司而复用不兼容的凭据或配置对象。
+- 企业微信的多应用应使用独立的 `WxCpConfigStorage` 与 `WxCpServiceImpl`；Wiki 明确指出复用 token、AES key 和 URL 会造成安全边界问题。
+- 支付能力通常与 MP、MiniApp 或 Open 同时使用：前者处理业务身份和消息，`weixin-java-pay` 处理商户签名、证书与支付回调。
+- 视频号／微信小店接口属于 `weixin-java-channel`；不要误归入 MP 或 Pay。
+- 腾讯企点与微信智能对话是独立 SDK 模块；不要将客服或智能对话需求默认归入 MP、CP 或 Channel。
+- 当能力在 MP 与 Open 等模块可能重叠时，按授权主体、官方 API 域和回调场景选择，不要只按“移动端”或“登录”字样判断。先在当前源码和 Issue 中确认覆盖状态，并标注“已确认 / 待查 / 需自行调用底层接口”。
+- BOM 适合同时使用多个 WxJava 模块。若项目还导入 Spring Boot 等上游 BOM，升级后执行 `mvn help:effective-pom` 与 `mvn dependency:tree`；历史 [#4058](https://github.com/binarywang/WxJava/issues/4058) 表明依赖管理顺序可能影响 Spring Data Redis 等依赖。
+
+## 一手资料入口
+
+- [WxJava Wiki 首页](https://github.com/binarywang/WxJava/wiki)
+- [企业微信多应用配置](https://github.com/binarywang/WxJava/wiki/CP_%E5%A6%82%E4%BD%95%E6%94%AF%E6%8C%81%E5%A4%9A%E4%B8%AA%E4%BC%81%E4%B8%9A%E5%8F%B7%E5%BA%94%E7%94%A8%E6%88%96%E4%BC%81%E4%B8%9A%E5%8F%B7)
+- [视频号／微信小店开发文档](https://github.com/binarywang/WxJava/wiki/0_%E8%A7%86%E9%A2%91%E5%8F%B7_%E5%BE%AE%E4%BF%A1%E5%B0%8F%E5%BA%97%E5%BC%80%E5%8F%91%E6%96%87%E6%A1%A3)