MyTool/AGENTS.md

AGENTS 指南（MyTool）

本文件面向在本仓库内工作的自动化 coding agents，目标是快速、安全地完成任务并保持项目一致性。

1. 仓库概览

• backend/：Spring Boot 2.7 + Java 8。
• frontend/：Vue 3 + Vite + TypeScript + Element Plus。
• docker/：单容器部署脚本与镜像构建。
• 生产环境为同源部署：后端托管前端构建产物。

2. Cursor / Copilot 规则检查

• 已检查 .cursor/rules/、.cursorrules、.github/copilot-instructions.md。
• 当前仓库未发现上述规则文件。
• 结论：请以本 AGENTS.md 作为主要执行规范。

3. 构建 / 运行 / Lint / 测试命令

3.1 前端（在 frontend/ 目录执行）

安装依赖：

npm ci

本地开发：

npm run dev

生产构建：

npm run build

预览构建：

npm run preview

Lint（当前为占位脚本）：

npm run lint

说明：当前 lint 实际输出 no linter configured yet，不是强校验。

3.2 后端（在 backend/ 目录执行）

编译：

mvn clean compile

打包：

mvn clean package

运行服务：

mvn spring-boot:run

运行全部测试：

mvn test

运行单个测试类（重点）：

mvn -Dtest=SomeServiceTest test

运行单个测试方法（重点）：

mvn -Dtest=SomeServiceTest#shouldHandleEdgeCase test

跳过测试打包（Docker 构建同策略）：

mvn clean package -DskipTests

3.3 Docker（在仓库根目录或 docker/）

启动：

cd docker && docker compose up -d --build

日志：

cd docker && docker compose logs -f

停止：

cd docker && docker compose down

4. 测试现状

• backend/src/test 已有基础测试（如 FileTransferUtilsTest、DedupServiceInternalTest、ConvertServiceInternalTest、TraditionalFilterServiceTest、ProgressStoreTest）。
• 前端未配置 Vitest/Jest，暂无 *.spec.ts / *.test.ts。
• 新增功能时，优先补后端单测，至少覆盖核心服务分支。
• 若引入前端测试框架，需同步更新 package.json 与本文件命令。

5. 后端代码规范（Java / Spring）

5.1 分层与职责

• 根包固定为 com.music。
• 目录分层遵循 controller / service / dto / config / common / exception。
• Controller 负责参数校验与编排，不写重业务逻辑。
• Service 负责核心业务流程，异常要转为可读的业务失败信息。

5.2 命名规范

• 类名：PascalCase（如 ConvertService、GlobalExceptionHandler）。
• 方法/字段：camelCase。
• 常量：UPPER_SNAKE_CASE（如 LOSSLESS_EXTENSIONS）。
• DTO 命名：XxxRequest / XxxResponse。

5.3 导入、格式、语言特性

• 使用显式 import，避免 * 通配符导入。
• 4 空格缩进，K&R 花括号风格，保持与现有代码一致。
• 保持 Java 8 兼容，不引入高版本语法。
• 文件编码 UTF-8。

5.4 参数校验与类型

• 接口入参使用 DTO，并配合 @Valid、@NotBlank 等注解。
• 业务模式值（如 copy/move）做显式校验，错误走业务异常。
• 路径、文件系统相关逻辑先校验再执行，避免抛裸异常到接口层。

5.5 错误处理与返回结构

• 统一返回 Result<T>：成功 Result.success(...)，失败 Result.failure(...)。
• 业务异常使用 BusinessException(code, message)。
• 全局异常由 GlobalExceptionHandler 兜底处理。
• 不向前端暴露堆栈或底层实现细节，错误信息保持可读。
• 异步任务失败需通过进度消息体现失败状态与原因。

6. 前端代码规范（Vue 3 + TypeScript）

6.1 组织与分层

• 页面主逻辑放在 src/components/*Tab.vue。
• 请求封装放在 src/api/*.ts，组件内不要直接拼 axios 细节。
• WebSocket 逻辑集中在 src/composables/useWebSocket.ts。
• 全局入口保持在 src/main.ts，避免散落初始化逻辑。

6.2 命名与类型

• 组件文件使用 PascalCase.vue。
• 组合式函数使用 useXxx。
• TS 接口和类型用 PascalCase。
• 变量和函数用 camelCase。
• 避免 any；优先显式接口、联合类型或 unknown + 类型收窄。

6.3 编码风格

• 使用 ESM 导入，默认相对路径。
• 保持单引号、分号、2 空格缩进。
• 默认使用 <script setup lang="ts">。
• 组件样式默认 scoped，仅在必要场景使用 :deep(...)。

6.4 状态与异常处理

• 表单对象优先 reactive，标量状态优先 ref。
• 接口返回默认遵循后端 Result<T>，通过 src/api/request.ts 统一解包。
• 用户可恢复错误通过 ElMessage.warning/error 提示。
• 长任务遵循“WebSocket 实时 + 轮询兜底”模式，注意组件卸载时清理连接与定时器。

7. 代理工作约束

• 变更前先确认影响层次：后端 DTO/Controller/Service 与前端 api/组件是否要同步。
• 新增后端接口优先沿用 /api/... 风格与现有响应结构。
• 不随意引入新框架或重型依赖（状态管理、UI 库、构建链）。
• 新增命令、脚本、测试框架时，务必更新本文件。
• 提交前至少执行受影响模块的构建或测试命令。

8. 提交前快速检查

• 是否保持 Result<T> + 统一异常处理链路？
• 是否保持前后端字段命名和类型一致（尤其进度消息）？
• 是否避免在组件中堆叠网络协议细节？
• 是否给出最小可执行验证命令（build/test）？
• 是否同步更新文档与脚本说明？

---

若后续新增 Cursor/Copilot 规则文件，请将关键约束合并到本文件，避免规范冲突。