svn-log-tool/AGENTS.md

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 工作台（Docker，推荐）：
  • make up
  • make status
  • make down
  • 启动后访问：http://localhost:18088
• 运行 Web 工作台（本机 Java + Maven，备用）：
  • mvn spring-boot:run -Dspring-boot.run.mainClass=com.svnlog.web.WebApplication

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

• 不新增通配符导入（*），使用明确导入。
• 按三组排序并空行分隔：
  1. java.* / javax.*
  2. 第三方库
  3. 本项目包（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 compile
  • mvn 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/自动化中使用真实密钥做在线调用。
• 最终在变更说明中记录验证命令与结果。