# `ssh-manager` AGENTS 指南
本文件用于指导在本仓库中执行任务的 agentic coding assistants。
目标是在保证安全、可验证和风格统一的前提下，以尽量小的意外完成聚焦改动。
## 1. 仓库结构
- Monorepo，包含：
  - `backend/`：Spring Boot 2.7、Java 8、Maven、H2、WebSocket、JWT
  - `frontend/`：Vue 3、TypeScript、Vite、Pinia、Tailwind、Axios
- 后端默认端口：`48080`
- 前端开发服务端口：`5173`
- 前端开发时会将 `/api` 和 `/ws` 代理到后端
- 数据库：文件型 H2，路径为 `./data/sshmanager`
- 认证方式：HTTP 使用 Bearer JWT，终端相关 WebSocket 流程在 query 中携带 token
## 2. 需优先检查的规则文件
- 主要仓库规范来源：本 `AGENTS.md`
- Cursor 规则：未发现 `.cursor/rules/` 目录，也未发现 `.cursorrules`
- Copilot 规则：未发现 `.github/copilot-instructions.md`
- 如果未来新增这些文件，编辑前应先读取，并将其视为高优先级约束
## 3. 工具链
- JDK：`8+`
- Maven：`3.6+`
- Node.js：`18+`
- npm：使用与 `frontend/package-lock.json` 兼容的版本
- Docker Compose：通过 `docker compose` 使用
## 4. 构建 / 运行 / 测试命令
### 后端（`backend/`）
- 启动开发服务：`mvn spring-boot:run`
- 打包应用：`mvn package`
- 跳过测试打包：`mvn -DskipTests package`
- 运行全部测试：`mvn test`
- 运行单个测试类：`mvn -Dtest=ConnectionServiceTest test`
- 运行单个测试方法：`mvn -Dtest=ConnectionServiceTest#shouldCreateConnection test`
- 运行同一类中的多个方法：`mvn -Dtest=ConnectionServiceTest#testA,testB test`
### 前端（`frontend/`）
- 安装依赖：`npm install`
- 启动开发服务：`npm run dev`
- 生产构建：`npm run build`
- 预览构建产物：`npm run preview`
- 当前没有独立的 `lint` script
- 当前没有独立的前端测试 script
- `npm run build` 会先执行 `vue-tsc -b`，因此它也是主要的前端类型检查入口
### Docker / 根目录（`./`）
- 构建镜像：`docker compose -f docker/docker-compose.yml build`
- 前台启动：`docker compose -f docker/docker-compose.yml up`
- 后台启动：`docker compose -f docker/docker-compose.yml up -d`
- Make 快捷命令：
  - `make build`
  - `make up`
  - `make down`
  - `make restart`
  - `make logs`
  - `make ps`
## 5. 测试策略
- 优先选择能覆盖改动的最小测试命令
- 对后端改动，先运行受影响的单个测试，再按需要扩大范围
- 现有后端测试位于 `backend/src/test/java`
- 当前后端测试类包括控制器和服务测试，如 `ConnectionControllerTest`、`SftpControllerTest`、`ConnectionServiceTest`、`SftpServiceTest`
- 如果改动涉及 Spring MVC、安全、WebSocket、SSH 或 SFTP 流程，优先补充或运行定向回归测试，而不只是编译通过
- 前端当前没有提交测试套件；对前端改动，至少运行 `npm run build`
## 6. 改动范围规则
- 保持改动小且聚焦任务本身
- 实现需求时不要顺手重构无关文件
- 除非任务明确要求，否则不要静默改变 API 语义
- 如果后端契约发生变化，需要在同一改动中同步更新前端 API / 类型
- 严禁提交 secrets、密码、token、私钥或带环境属性的敏感凭据
## 7. Git 与提交规范
- 开始修改前先查看工作区状态，识别是否存在与当前任务无关的脏变更
- 不要回退、覆盖或格式化并非由当前任务引入的用户改动
- 除非用户明确要求，否则不要主动创建 commit、tag、分支或 PR
- 避免使用 `git reset --hard`、`git checkout --`、强制推送等破坏性命令
- 若需要提交，提交内容应仅包含与当前任务直接相关的文件
- 提交说明建议简洁描述“为什么改”，而不只是罗列“改了什么”
- 若因 hooks 或生成步骤导致文件变动，应先确认内容合理，再决定是否纳入同一提交
## 8. 后端约定（`backend/`）
### import 与文件结构
- 包名前缀固定为 `com.sshmanager`
- 保持显式 import，不使用通配符 import
- 遵循仓库现有 import 分组风格：
  - 先项目内 import：`com.sshmanager...`
  - 再框架 / 第三方：`org...`、`javax...` 等
  - 最后 JDK：`java...`
- 控制器放在 `controller`，服务放在 `service`，仓库层放在 `repository`，DTO 放在 `dto`，实体放在 `entity`，安全相关代码放在 `security`
### 格式与命名
- 使用 4 空格缩进
- 左花括号与声明同行
- 类名使用 `PascalCase`
- 方法名和字段名使用 `camelCase`
- 常量使用 `UPPER_SNAKE_CASE`
- Spring 类型命名后缀保持一致：`*Controller`、`*Service`、`*Repository`
### 类型与 Spring 用法
- 保持 Java 8 兼容，不要引入更高版本语言特性
- 优先使用构造器注入
- 控制器返回 `ResponseEntity<?>` 或 `ResponseEntity<T>`，与现有代码保持一致
- 请求 / 响应边界优先使用 DTO；除非某文件本来就是如此，否则不要直接从控制器暴露实体
- 持久化操作应保留在 service / repository 边界内，不要堆进 controller
- 对需要原子性的写操作使用 `@Transactional`
### 错误处理与安全
- 维持现有 JSON 错误格式，使用 `message` 或 `error` 字段
- HTTP 状态码保持一致：
  - `400`：参数或输入错误
  - `401`：认证 / 授权失败
  - `500`：未预期的服务端异常
- 不要在日志中输出明文密码、私钥、口令、JWT 或解密后的凭据
- 加解密逻辑统一集中在 `EncryptionService`
- 修改认证逻辑时，要同时验证 HTTP 与 WebSocket token 处理
- 注意 `ChannelSftp` 不是线程安全的，不要在并发场景共享实例
## 9. 前端约定（`frontend/`）
### Vue 与 TypeScript 结构
- Vue 单文件组件使用 `<script setup lang="ts">`
- 新增前端逻辑时优先使用 TypeScript
- ref、路由参数、API payload 尽量强类型化，不要随手使用 `any`
- 先新增或更新 API 层类型，再接入 UI 行为
- 有状态的数据流应保留在 Pinia store 或 API 模块中，不要在多个视图里重复维护
### import 与命名
- 遵循当前观察到的 import 顺序：
  - Vue 核心包
  - router / store
  - 本地 API / 类型 / 组件
  - 未与核心库归组时的第三方 UI / 图标库
- 组件文件名使用 `PascalCase.vue`
- Store 命名使用 `useXxxStore`
- 变量 / 函数名使用 `camelCase`
- 常量使用 `UPPER_SNAKE_CASE`
### 格式与界面模式
- 使用 2 空格缩进
- TS / Vue script 块保持现有的无分号、单引号风格
- 优先使用 Tailwind 工具类，不引入新的样式体系
- 除非任务明确要求改版，否则保留当前 `slate` / `cyan` 视觉语言
- 保持基础可访问性：表单标签、按钮状态、必要的 `aria-*` 属性，以及键盘可操作性
### 错误处理与性能
- 重要操作失败时要给用户可见反馈，不要静默失败
- 除非明确要改认证流程，否则保留当前 Axios 拦截器中的登录失效处理逻辑
- 对终端和 SFTP 视图要特别注意，避免不必要重渲染和高成本响应式循环
- 对可选后端数据优先做空值安全处理，如 `string | null` 与可选响应字段
## 10. 完成前验证
- 仅后端改动：至少运行最相关的 `mvn -Dtest=... test` 或 `mvn test`
- 仅前端改动：运行 `npm run build`
- 全栈改动：运行最窄范围的后端测试，再运行 `npm run build`
- 如果运行时行为发生变化，在可能时手工检查受影响流程，如登录、连接 CRUD、终端或 SFTP
- 最终说明中应明确写出已验证内容与未验证内容
## 11. 仓库特定说明
- 后端配置文件位于 `backend/src/main/resources/application.yml`
- 与安全相关的环境变量包括 `SSHMANAGER_JWT_SECRET` 和 `SSHMANAGER_ENCRYPTION_KEY`
- 生产部署必须提供真实有效的这些密钥
- 前端认证 token 当前存储在 `localStorage`
- `frontend/src/api/client.ts` 在收到 `401` 响应时会跳转到 `/login`
## 12. 在本仓库中的良好 agent 行为
- 先阅读现有代码，再决定采用什么模式
- 匹配周边代码风格，不要强行套用新偏好
- 优先做手术式修改，而不是大范围重写
- 当改动会让相邻文档或类型失真时，一并更新它们
- 只在任务范围内把工作区变得更整洁
- 输出结果时优先说明实际改动、验证情况以及仍未覆盖的风险点