Skip to content

Commit b3a9ee7

Browse files
binarywangbinarywang
committed
📝 完善 AGENTS.md 开发与 Review 指南
1 parent d60cd85 commit b3a9ee7

1 file changed

Lines changed: 127 additions & 2 deletions

File tree

‎AGENTS.md‎

Lines changed: 127 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,130 @@
1-
## Review guidelines
1+
# WxJava Agent 指南
2+
3+
## 适用范围与指令优先级
4+
5+
- 本文件适用于整个仓库，供本地编码 Agent、自动化 Agent 和 Pull Request Review Agent 使用。
6+
- 开始工作前先阅读与任务直接相关的 `README.md`、`CONTRIBUTING.md`、模块 `pom.xml`、现有实现和测试；不要仅凭通用经验推断项目约定。
7+
- 若子目录存在更具体的 `AGENTS.md`，处理该目录文件时优先遵循距离目标文件最近的说明。
8+
- 用户的明确要求优先于本文件；若要求与兼容性、安全性或仓库约定冲突，应先说明风险，不要静默偏离。
9+
- 只修改完成任务所必需的文件，不处理无关格式、重构或历史遗留问题。
10+
11+
## 项目概览
12+
13+
- WxJava 是面向微信生态的 Java SDK，采用 Maven 多模块结构。
14+
- 当前根项目要求 Java 8（`maven.compiler.source` 和 `maven.compiler.target` 均为 `1.8`）。除非任务明确要求升级，否则新增代码、依赖和 API 必须保持 Java 8 兼容。
15+
- 主要 SDK 模块包括：
16+
- `weixin-java-common`：各模块共用的基础类型、工具、异常、HTTP 与配置能力。
17+
- `weixin-java-mp`：微信公众号。
18+
- `weixin-java-miniapp`：微信小程序。
19+
- `weixin-java-pay`：微信支付。
20+
- `weixin-java-cp`：企业微信。
21+
- `weixin-java-open`：微信开放平台。
22+
- `weixin-java-channel`：微信视频号、微信小店。
23+
- `weixin-java-qidian`：微信客服相关能力。
24+
- `weixin-java-aispeech`：微信智能语音。
25+
- `weixin-graal`：GraalVM 相关支持。
26+
- 集成模块主要位于：
27+
- `spring-boot-starters`：Spring Boot Starter 及多账号 Starter。
28+
- `solon-plugins`：Solon 插件及多账号插件。
29+
- `wx-java-bom`：统一管理对外模块版本的 BOM。
30+
- `README.md` 说明整体能力和使用方式，`CONTRIBUTING.md` 规定代码贡献要求，`docs` 保存补充文档。
31+
32+
## 开发流程
33+
34+
1. 确认任务涉及的微信产品和 Maven 模块，先查找同模块中的相似接口、Bean、实现类和测试。
35+
2. 阅读目标模块及其父级 `pom.xml`，确认依赖、测试框架和已有实现方式。
36+
3. 优先沿用现有的包结构、命名、序列化、HTTP 执行器、异常处理及配置模式。
37+
4. 以最小变更完成任务；不要在功能修改中夹带依赖升级、全局格式化或无关重构。
38+
5. 为修复或新增行为添加有针对性的测试，并先运行受影响模块的验证。
39+
6. 交付前检查 diff、测试结果、兼容性和文档影响，明确报告未执行或无法执行的验证。
40+
41+
## 代码风格与兼容性
42+
43+
- 遵循 `.editorconfig`：使用空格缩进、缩进宽度为 2、UTF-8、LF、文件末尾保留换行，并清除非 Markdown 文件的行尾空格。
44+
- 保持目标文件现有代码风格；避免仅为个人偏好调整 import、换行、注释或成员顺序。
45+
- 不使用 Java 9 及以上语言特性或仅在新版本 JDK 中存在的 API。
46+
- 项目使用 Lombok；新增或修改 Lombok 用法时遵循相邻代码模式，不要在同一变更中无理由改写为手工样板代码。
47+
- 公共 API、序列化字段、枚举值、常量、默认实现和依赖范围都可能影响下游用户，修改时优先保持源码、二进制和行为兼容。
48+
- 不要随意改变已有异常类型、空值语义、默认 HTTP 客户端、JSON/XML 映射或配置加载行为。
49+
- 新增依赖前先确认现有依赖能否满足需求；依赖版本应在合适的父 POM 或 BOM 中统一管理，避免模块间版本漂移。
50+
51+
## API 与实现约定
52+
53+
- 对接微信接口时，以对应产品的官方接口定义和仓库内现有同类实现为依据，核对请求路径、HTTP 方法、字段名、必填项和返回结构。
54+
- Java 字段名可以符合项目命名习惯，但传输层字段名必须与微信接口保持一致；需要时使用项目现有的 Gson、Jackson 或 XStream 映射方式。
55+
- 新增 Service API 时同步检查接口、实现类、请求/响应 Bean、URL 常量、序列化适配器和测试是否都需要更新。
56+
- 涉及多个 HTTP 客户端实现时，保持 Apache HttpClient、HttpComponents、OkHttp 和 Jodd 等现有实现的能力一致；不要只修复其中一种而遗漏其他可选实现。
57+
- 涉及 Starter 或插件时，检查单账号与多账号版本以及自动配置、配置属性和示例测试是否需要同步。
58+
- 公共方法需要清晰的 Javadoc，至少准确描述参数、返回值、异常和必要约束；不要编写与实现不一致的模板化注释。
59+
- 不吞掉异常，不使用空 `catch`，不在日志中泄露 token、secret、密钥、签名原文或用户敏感数据。
60+
61+
## 测试与验证
62+
63+
- 项目测试主要使用 TestNG；沿用目标模块已有测试基类、数据提供器、Mock 方式和资源布局。
64+
- 修复 bug 时应添加能够复现旧行为并验证修复结果的回归测试；新增公共方法必须配套单元测试。
65+
- 优先执行受影响模块及其依赖的测试：
66+
67+
```shell
68+
mvn -pl <module> -am test
69+
```
70+
71+
- 运行单个测试类时，可在对应模块范围内执行：
72+
73+
```shell
74+
mvn -pl <module> -am -Dtest=<TestClass> -Dsurefire.failIfNoSpecifiedTests=false test
75+
```
76+
77+
- 跨公共模块、父 POM、BOM 或多个产品模块的变更应扩大验证范围；条件允许时执行：
78+
79+
```shell
80+
mvn test
81+
```
82+
83+
- 对仅需确认编译且测试依赖外部凭据的场景，可执行模块级编译或打包，但不得把跳过测试的构建描述为“测试通过”。
84+
- 部分测试可能依赖微信凭据、网络或本地配置。不得提交真实凭据；无法运行时应说明原因以及已完成的替代验证。
85+
- 完成前至少运行 `git diff --check`，并人工检查 `git diff`，确认没有意外文件、调试代码、生成物或敏感信息。
86+
87+
## 文档与依赖变更
88+
89+
- 用户可见的 API、配置项、模块使用方式或兼容性发生变化时，同步更新相关 Javadoc、README 或 `docs` 文档。
90+
- 示例中的版本号、模块名和配置键应与当前项目保持一致；不要复制未经验证的外部示例。
91+
- 修改根 POM、父 POM 或 `wx-java-bom` 时，检查所有子模块和对外依赖管理的影响。
92+
- 不提交构建输出、IDE 临时文件、测试报告、真实配置文件或本地备份文件。
93+
94+
## Git 与 Pull Request 规范
95+
96+
- 贡献目标分支为 `develop`；`release` 用于正式版本发布，不应作为常规 Pull Request 的目标分支。
97+
- 提交前保持工作区变更聚焦，不覆盖或回退用户已有的无关修改。
98+
- Commit 和 Pull Request 应说明变更动机、影响模块、兼容性风险和验证方式；关联已有 Issue 时写明编号。
99+
- 不得在未经用户明确授权的情况下执行 `git push`、创建或合并 Pull Request、改写历史或执行破坏性 Git 操作。
100+
- 不要使用 `git reset --hard`、强制 checkout 等方式清理不属于当前任务的改动。
101+
102+
## 安全与敏感数据
103+
104+
- 禁止提交 AppID 对应的 secret、access token、API v3 密钥、商户私钥、证书私钥、用户数据或其他真实凭据。
105+
- 测试和文档使用明显的占位值或脱敏数据；日志应避免输出查询串、请求体或响应体中的敏感字段。
106+
- 涉及签名、验签、加解密、证书、回调通知和支付金额时，重点检查字符编码、字段排序、精度、时区、重放风险和资源关闭。
107+
- 涉及网络请求、文件或流时，检查超时、异常路径、资源释放、响应关闭和大数据量下的内存行为。
108+
109+
## Review 指南
2110

3111
- 重点检查空指针、并发、资源释放、兼容性问题。
4112
- 不要只做代码风格建议，优先指出真实 bug 和回归风险。
5-
- 中文回复 review 结论。
113+
- 所有 Pull Request Review 的总结、结论和行内评论必须使用简体中文。
114+
- 技术标识符、类名、方法名、变量名、日志、错误信息及代码片段保持原文，不要翻译。
115+
- 严重程度标识可以保留 `P0`、`P1`、`P2` 等英文缩写。
116+
- 如果没有发现需要阻止合并的问题，也必须使用简体中文给出结论。
117+
- Review 结论必须基于当前 diff 和仓库中可验证的行为；不确定时明确说明假设，不要把推测写成确定缺陷。
118+
- 仅报告由本次变更引入或暴露、且作者可以采取行动的问题，并指出具体文件、位置、触发条件和影响。
119+
- 重点关注微信接口契约、Java 8 兼容性、公共 API 兼容性、序列化字段、HTTP 客户端实现一致性、Starter 多账号场景及敏感信息泄露。
120+
- 不要仅因缺少全仓库测试、个人风格偏好或与本次变更无关的历史代码而阻止合并。
121+
122+
## Agent 完成检查清单
123+
124+
- 已确认并遵循相关模块、相邻代码和更具体的 `AGENTS.md`。
125+
- 变更范围与任务直接相关，没有覆盖用户的无关修改。
126+
- 新增代码保持 Java 8、公共 API 和序列化兼容性。
127+
- 必要的测试与文档已经更新。
128+
- 已执行与风险匹配的构建或测试，并如实记录结果。
129+
- 已检查完整 diff、格式、生成物和敏感信息。
130+
- 最终回复使用简体中文，简要列出修改内容、验证结果和任何剩余风险。

0 commit comments

Comments
 (0)