6.2 KiB
6.2 KiB
AGENTS 指南（svn-log-tool）
本文件提供给自动化编码代理（Agent）使用。 目标：在不破坏现有行为的前提下，安全、可复现地修改本仓库。
1. 项目概览
- 语言与构建：Java 8 + Maven（
pom.xml）。 - 打包产物：可执行 fat jar（
jar-with-dependencies）。 - 统一入口：
com.svnlog.web.WebApplication（前后端一体，静态页面 + REST API）。 - 核心目录：
src/main/java/com/svnlog/docs/- SVN 预设地址：
src/main/resources/application.properties（svn.presets[*]）
2. 常用命令（Build / Lint / Test / Run）
以下命令默认在仓库根目录执行。
2.1 Build
- 仅编译（推荐快速检查）：
mvn clean compile - 打包（跳过测试）：
mvn clean package -DskipTests - 打包（执行测试）：
mvn clean package - 产物（通常）：
target/svn-log-tool-1.0.0-jar-with-dependencies.jar
2.2 Lint / 静态检查
- 当前仓库未配置 Checkstyle / SpotBugs / PMD。
- 将
mvn clean compile作为基础语法与依赖检查。 - 若需更严格检查，可使用
mvn -DskipTests verify。
2.3 Test
- 运行全部测试：
mvn test - 运行单个测试类（重点）：
mvn -Dtest=ClassName test - 单测类示例：
mvn -Dtest=SVNLogFetcherTest test - 运行单个测试方法（重点）：
mvn -Dtest=ClassName#methodName test - 单测方法示例：
mvn -Dtest=SVNLogFetcherTest#shouldFilterByUser test - 调试失败测试（输出更完整）：
mvn -Dtest=ClassName test -e - 说明：当前
src/test/java为空；新增测试时采用 Surefire 默认约定。
2.4 Run
- 运行 Web 工作台（推荐）：
mvn spring-boot:run -Dspring-boot.run.mainClass=com.svnlog.web.WebApplication- 启动后访问：
http://localhost:8080
3. 代码结构与职责边界
SVNLogFetcher.java：SVN 连接、版本区间处理、日志抓取、用户过滤。LogEntry.java：日志数据模型（POJO）。web/controller/*：REST API（SVN、AI、任务、文件、设置）。web/service/*：异步任务与业务编排（SVN 抓取、AI 分析、输出目录管理）。src/main/resources/static/*：Web 前端页面与交互脚本。- 变更原则：
- 抓取逻辑改在
SVNLogFetcher。 - AI/Excel 逻辑改在
web/service/AiWorkflowService。 - 不把多种职责混入同一方法。
- 抓取逻辑改在
4. 代码风格规范（必读）
4.1 Java 与兼容性
- 严格保持 Java 8 兼容（
source/target=1.8）。 - 避免引入仅 Java 9+ 可用 API。
4.2 Imports
- 不新增通配符导入（
*），使用明确导入。 - 按三组排序并空行分隔：
java.*/javax.*- 第三方库
- 本项目包（
com.svnlog.*）
- 删除未使用 import。
4.3 格式与排版
- 缩进使用 4 个空格，不用 Tab。
- 单行长度建议 <= 120。
if/for/while必须使用大括号（即使单行语句）。- 方法间保留一个空行；逻辑块间适度空行。
4.4 类型与数据结构
- 优先使用接口类型声明：
List/Map，实现类写在右侧。 - 泛型必须写完整，避免原生类型。
- 可变共享状态最小化；能用
final的局部变量尽量用final。 - 使用
SimpleDateFormat等对象时，注意线程安全作用域。
4.5 命名规范
- 类名：
UpperCamelCase（示例：SVNLogFetcher）。 - 方法/变量：
lowerCamelCase（示例：fetchLogs）。 - 常量：
UPPER_SNAKE_CASE（示例：DEEPSEEK_API_URL）。 - 名称应表达业务意图，避免无语义缩写（如
tmp、data1）。
4.6 异常与错误处理
- 不吞异常；至少记录错误上下文。
- CLI 提示要清晰，并给出可执行下一步。
- 能在边界处校验输入时，尽早校验并快速失败。
- 不要仅
printStackTrace；优先输出结构化错误信息。 - 外部调用（SVN/API/文件）必须处理失败分支与空响应。
4.7 I/O 与资源管理
- 文件与网络资源统一使用 try-with-resources。
- 路径与编码显式声明，默认 UTF-8。
- 大文本拼接优先
StringBuilder。
4.8 注释与文档
- 注释解释“为什么”，避免重复“做了什么”。
- 对外可见方法或复杂逻辑可补充简短 Javadoc。
- 修改行为时同步更新
docs/下文档。
5. 安全与敏感信息
- 严禁提交真实密钥、口令、Token、内网敏感地址。
- Web 端 AI 分析涉及 API Key；新增改动时应：
- 优先从环境变量读取（如
DEEPSEEK_API_KEY）。 - 回退到交互输入。
- 不把真实值写入源码或日志。
- 优先从环境变量读取（如
- 日志中避免打印完整凭据与隐私信息。
6. 测试与验收建议
- 功能变更后至少执行：
mvn clean compilemvn test（若已有测试）
- 新增测试建议目录：
src/test/java/com/svnlog/ - 测试命名建议：
- 类名：
<被测类名>Test - 方法名：
should<行为>When<条件>
- 类名：
7. Git 与提交建议（给 Agent）
- 小步提交，标题建议使用动词前缀：
fix:、feat:、refactor:、docs:。 - 一次提交只做一类改动（功能/重构/文档分离）。
- 不顺手修改无关文件。
- 提交前确认构建产物（
target/）不入库。
8. Cursor / Copilot 规则检查结果
- 未发现
.cursorrules。 - 未发现
.cursor/rules/目录。 - 未发现
.github/copilot-instructions.md。 - 若后续新增这些规则文件，应同步更新本 AGENTS，并以更具体规则优先。
9. 给自动化代理的执行清单
- 先读
pom.xml与目标类，再动代码。 - 先最小改动实现需求，再补测试与文档。
- 变更命令、入口、参数时必须更新本文档。
- 无测试时至少确保
mvn clean compile成功。 - 输出结论时写明：改了什么、为什么、如何验证。
10. 最小验证流程（建议）
- 仅修改文档：至少检查 Markdown 渲染与命令可复制执行。
- 修改 Java 代码：执行
mvn clean compile。 - 涉及测试逻辑：执行
mvn test或目标单测命令。 - 涉及打包/入口：执行
mvn clean package -DskipTests并验证产物。 - 涉及 DeepSeek 调用：避免在 CI/自动化中使用真实密钥做在线调用。
- 最终在变更说明中记录验证命令与结果。