ssh-manager/AGENTS.md

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 行为

• 先阅读现有代码，再决定采用什么模式
• 匹配周边代码风格，不要强行套用新偏好
• 优先做手术式修改，而不是大范围重写
• 当改动会让相邻文档或类型失真时，一并更新它们
• 只在任务范围内把工作区变得更整洁
• 输出结果时优先说明实际改动、验证情况以及仍未覆盖的风险点