# `sftp-manager` AGENTS 指南 本文件面向在本仓库内执行任务的自动化 Coding Agent。 请将其作为本项目在构建、测试、编码规范方面的本地权威说明。 ## 1）项目概览 - 技术栈：Spring Boot 2.7.18、Java 8、Maven、Spring Data JPA、H2、JSch、原生 HTML/CSS/JS。 - 启动入口：`src/main/java/com/sftp/manager/SftpManagerApplication.java`。 - 主要目录结构： - `src/main/java/com/sftp/manager/controller/`：HTTP 控制器 - `src/main/java/com/sftp/manager/service/`：业务逻辑（SFTP、本地文件） - `src/main/java/com/sftp/manager/model/`：实体模型 - `src/main/java/com/sftp/manager/repository/`：JPA 仓库 - `src/main/java/com/sftp/manager/dto/`：接口请求/响应 DTO - `src/main/resources/static/`：前端静态资源 - `src/main/resources/application*.yml`：运行配置 - 默认端口：`48081`（见 `application.yml`）。 - 生产环境可启用 `prod` profile（见 `application-prod.yml`）。 ## 2）Cursor / Copilot 规则检查结果 已检查以下路径，当前未发现规则文件： - `.cursor/rules/` - `.cursorrules` - `.github/copilot-instructions.md` 若后续新增上述文件，请立即同步更新本 `AGENTS.md`。 新增规则应视为更高优先级约束并优先遵循。 ## 3）构建、运行、测试命令 默认在仓库根目录执行命令。 ### 3.1 Maven 构建与打包 - 仅编译：`mvn clean compile` - 完整打包（含测试）：`mvn clean package` - 跳过测试打包：`mvn clean package -DskipTests` - 安装到本地仓库：`mvn clean install` ### 3.2 本地运行 - 开发运行：`mvn spring-boot:run` - 运行 JAR：`java -jar target/sftp-manager-1.0.0.jar` - 生产配置运行：`java -jar target/sftp-manager-1.0.0.jar --spring.profiles.active=prod` ### 3.3 Docker 运行 - Linux/Mac 一键启动：`./run.sh` - Windows 一键启动：`run.bat` - 手动启动：`docker compose up -d --build` - 手动停止：`docker compose down` ### 3.4 测试命令（重点：单测定向执行） 当前仓库尚无 `src/test/**/*.java` 文件。 当新增测试后，按以下方式执行： - 执行全部测试：`mvn test` - 执行单个测试类：`mvn -Dtest=ConnectionServiceTest test` - 执行单个测试方法：`mvn -Dtest=ConnectionServiceTest#connect_success test` - 执行多个测试类：`mvn -Dtest=ConnectionServiceTest,FileControllerTest test` 若出现“测试未执行”，优先检查命名是否满足 Surefire 默认规则： - `*Test` - `*Tests` - `*TestCase` ### 3.5 Lint / 质量门禁 `pom.xml` 当前未配置 Checkstyle、Spotless、PMD 等专用 lint 插件。 因此以“编译 + 测试”作为质量门禁： - 快速门禁：`mvn clean compile` - 完整门禁：`mvn clean test` ### 3.6 当前测试覆盖（供 Agent 参考） 目前已存在以下单测类，可按需定向执行： - `ConnectionControllerTest` - `FileControllerTest` - `ConnectionServiceTest` - `SessionManagerTest` - `LocalFileServiceTest` 示例： - 执行单个测试类：`mvn -Dtest=LocalFileServiceTest test` - 执行单个测试方法：`mvn -Dtest=LocalFileServiceTest#renameFile_shouldAllowRenameInSameDirectory test` ## 4）代码风格与工程约定 ## 4.1 Java / Spring 通用约定 - 必须保持 Java 8 兼容，不使用 Java 9+ 语法。 - 包路径维持在 `com.sftp.manager` 下。 - 控制器保持轻量，核心逻辑放到 `service` 层。 - API 返回统一使用 `ApiResponse`。 - 延续既有接口前缀： - `/api/connection/*` - `/api/files/*` - 沿用已有术语命名：`sessionId`、`sourcePath`、`targetPath`、`recursive`。 ## 4.2 依赖注入风格 - 现有代码大量使用字段注入 `@Autowired`，修改旧文件时保持一致。 - 新增类可用构造器注入，但同一类内不要混用多种注入风格。 - 避免“仅改一点却全文件重构注入方式”的无关变更。 ## 4.3 Imports 与格式 - 保持文件现有 import 分组习惯，尽量与周边代码一致。 - 一般顺序：项目/第三方 → Spring → `javax.*` → `java.*`。 - 避免通配符导入（`*`），优先显式导入。 - 使用 4 空格缩进，不使用 Tab。 - 保持现有大括号、注解换行和空行风格。 ## 4.4 类型、DTO 与实体 - 避免原始类型集合，优先使用泛型（如 `List`）。 - DTO/实体中，允许为空的数值或布尔优先用包装类型（`Integer`、`Long`、`Boolean`）。 - DTO 只做传输，不承载业务逻辑。 - 若同类文件已使用 Lombok `@Data`，新增同类对象可延续该模式。 ## 4.5 命名规范 - 类名：PascalCase（如 `ConnectionService`）。 - 方法/变量/参数：camelCase（如 `getFileInfo`）。 - 常量：UPPER_SNAKE_CASE（如 `API_BASE`）。 - REST 路径：小写，必要时使用连字符，优先复用已有路径。 - Service 方法名优先“动词 + 对象”（如 `uploadToSftp`、`downloadFromSftp`）。 ## 4.6 错误处理规范 - 先做参数校验，再执行核心逻辑。 - 控制器边界统一捕获异常，并映射为 `ApiResponse.error(...)`。 - 错误信息要包含上下文（路径、会话、操作类型），但不得泄露敏感信息。 - 清理流程中的异常可按现有模式忽略，但主流程异常不可静默吞掉。 - 保持面向用户的提示语风格与现有代码一致（当前以中文提示为主）。 ## 4.7 文件与流处理 - 所有 `InputStream` / `OutputStream` 优先使用 `try-with-resources`。 - 明确“由谁负责关闭流”，避免重复关闭或泄漏。 - 递归文件操作需考虑部分失败、非法路径、权限不足等场景。 - 跨平台路径处理继续使用现有模式（`File.separator`、路径规范化）。 - 本地路径处理应统一规范化（`getCanonicalFile`），拒绝 `..` 上级目录穿越。 - 删除操作应防护根目录与系统关键目录（Windows 与 Unix 路径均需考虑）。 - 重命名默认按“同目录重命名”语义实现，不在重命名接口里隐式做跨目录移动。 ## 4.8 持久化与配置约定 - 实体默认值与时间戳钩子（`@PrePersist` / `@PreUpdate`）保持一致。 - 不提交 `data/` 下数据库产物（`.gitignore` 已忽略相关文件）。 - 生产配置中的环境变量占位符应保留（如 `DB_USERNAME`、`DB_PASSWORD`）。 - 非需求驱动情况下，不扩展 Actuator 暴露范围。 ## 4.9 前端静态资源约定 - 项目未配置 Node 构建链路，前端资源直接编辑 `static` 目录。 - 保持当前 jQuery 风格与状态驱动结构（见 `static/js/app.js`）。 - 保持双面板交互和响应式行为，不破坏现有 UX。 - 保持 CSS 变量与设计令牌风格，不做大规模 UI 体系替换。 ## 5）Agent 工作流程建议 - 开始改动前，先阅读目标文件及相邻文件风格。 - 以最小必要改动为原则，避免无关重构。 - 未明确要求时，不更改端口、context-path、profile 行为。 - 新增功能优先补充可验证逻辑；有测试目录后优先补单元测试。 - 完成后至少运行一次编译校验；如有测试则执行相关测试。 - 若新增关键命令或流程，请同步更新本 `AGENTS.md`。 - 涉及安全边界（认证、文件系统、CORS、主机密钥）变更后，必须补至少一条对应单测。 ## 6）常用命令速查 - `mvn clean compile` - `mvn test` - `mvn -Dtest=ClassName test` - `mvn -Dtest=ClassName#methodName test` - `mvn spring-boot:run` - `mvn clean package -DskipTests` - `java -jar target/sftp-manager-1.0.0.jar --spring.profiles.active=prod` - `docker compose up -d --build` 请随项目演进持续维护本文件，确保其内容始终与仓库实际配置一致。