diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..2aca4f2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,159 @@
+# AGENTS 指南（ssh-manager）
+
+本文件面向在本仓库工作的自动化 coding agents。
+目标：快速、安全、风格一致地完成改动。
+
+## 1) 仓库概览
+
+- Monorepo：`backend`（Spring Boot 2.7 + Java 8）+ `frontend`（Vue 3 + TS + Vite）
+- 默认后端端口：`48080`（见 `backend/src/main/resources/application.yml`）
+- 前端开发端口：`5173`，通过 Vite 代理 `/api` 和 `/ws`
+- 数据库：H2 文件库（`./data/sshmanager`）
+- 认证：JWT（HTTP Header Bearer + WebSocket query token）
+
+## 2) 环境与依赖
+
+- JDK：8+
+- Maven：3.6+
+- Node.js：18+
+- npm：与 `frontend/package-lock.json` 配套
+
+## 3) 常用命令（构建 / 检查 / 测试）
+
+### 3.1 后端（在 `backend/` 目录）
+
+- 启动开发服务：`mvn spring-boot:run`
+- 打包：`mvn package`
+- 仅运行测试：`mvn test`
+- 跳过测试打包：`mvn -DskipTests package`
+- 运行单个测试类：`mvn -Dtest=ConnectionServiceTest test`
+- 运行单个测试方法：`mvn -Dtest=ConnectionServiceTest#shouldCreateConnection test`
+
+说明：
+- 当前仓库可能暂无 `src/test` 用例；上述命令是 Maven 标准入口。
+- 新增测试时优先使用 Surefire 默认命名约定（`*Test`、`*Tests`）。
+
+### 3.2 前端（在 `frontend/` 目录）
+
+- 安装依赖：`npm install`
+- 启动开发服务：`npm run dev`
+- 生产构建：`npm run build`
+- 本地预览构建产物：`npm run preview`
+
+说明：
+- 当前 `package.json` 未配置独立 lint/test script。
+- `npm run build` 会先执行 `vue-tsc -b`，可视为类型检查关卡。
+
+### 3.3 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`
+
+## 4) 单测执行策略（重点）
+
+- 后端单测首选：`mvn -Dtest=类名#方法名 test`
+- 多方法可用逗号：`mvn -Dtest=ClassTest#testA,testB test`
+- 若测试依赖 Spring 上下文，优先在类级隔离，避免全量启动过慢
+- 修改 Service/Controller 后，至少补一条对应单元或集成测试（若仓库开始建设测试）
+- 前端若后续引入 Vitest，建议约定：
+  - 全量：`npm run test`
+  - 单文件：`npm run test -- src/views/ConnectionsView.test.ts`
+  - 单用例：`npm run test -- -t "case name"`
+
+## 5) 代码风格总则
+
+- 小步提交：改动聚焦，避免“顺手重构”无关文件
+- 保持现有技术栈，不随意引入新框架/重依赖
+- 默认不修改对外 API 语义；若必须修改，同步更新调用侧
+- 安全优先：严禁提交真实密钥、密码、token、私钥
+- 可观测性：失败路径要返回可诊断信息（但不能泄露敏感数据）
+
+## 6) 后端风格（Java / Spring）
+
+### 6.1 导入与结构
+
+- 包名固定前缀：`com.sshmanager`
+- import 分组遵循现有习惯：
+  - 先项目内 `com.sshmanager...`
+  - 再第三方/框架 `org...` / `javax...`
+  - 最后 `java...`
+- 避免通配符 import（`*`）
+
+### 6.2 格式与命名
+
+- 4 空格缩进，左花括号同行
+- 类名 `PascalCase`，方法/变量 `camelCase`
+- Controller 以 `*Controller`，Service 以 `*Service`，Repository 以 `*Repository`
+- DTO 放 `dto` 包，实体放 `entity` 包
+- 常量使用 `UPPER_SNAKE_CASE`
+
+### 6.3 类型与注解
+
+- Java 8 语法兼容（不要引入更高版本语法特性）
+- 优先构造器注入（本仓库已有统一做法）
+- 合理使用 Lombok（当前主要在 Entity 使用）
+- 对外接口返回 `ResponseEntity<...>` 保持一致
+
+### 6.4 异常与错误处理
+
+- 与现有代码一致：业务错误返回 JSON（`message` 或 `error` 字段）
+- 鉴权失败返回 401；参数错误返回 400；服务异常返回 500
+- 记录日志时避免输出明文凭据（password/privateKey/passphrase/token）
+- SFTP 相关改动需考虑并发安全：`ChannelSftp` 非线程安全
+
+### 6.5 安全相关
+
+- JWT 校验逻辑位于过滤器与握手流程，改动需覆盖 HTTP + WS 场景
+- 允许跨域来源在 `SecurityConfig` 中集中维护
+- 加密逻辑统一走 `EncryptionService`，禁止绕过直接落库明文
+
+## 7) 前端风格（Vue 3 / TS / Tailwind）
+
+### 7.1 导入与模块组织
+
+- 使用 `<script setup lang="ts">`
+- import 优先级参考现有文件：
+  - Vue 核心库
+  - 路由 / store
+  - 本地 API / type / 组件
+  - 图标或其他第三方
+- 相对路径保持简洁，避免无必要跨层引用
+
+### 7.2 格式与命名
+
+- 2 空格缩进
+- TypeScript 与 Vue 脚本保持“无分号 + 单引号”风格
+- 组件文件名 `PascalCase.vue`
+- store 命名：`useXxxStore`
+- 方法变量 `camelCase`，常量 `UPPER_SNAKE_CASE`
+
+### 7.3 类型与状态
+
+- API 类型定义集中在 `frontend/src/api/*.ts`
+- 对可空值显式标注（如 `Connection | null`）
+- Pinia store 负责状态与数据同步，视图层尽量避免重复请求逻辑
+- 新增接口先补类型，再写调用
+
+### 7.4 UI 与交互
+
+- 延续 Tailwind 工具类写法，不引入额外 CSS 框架
+- 保持现有深色主题语言（`slate/cyan`）与可访问性属性（如 `aria-label`）
+- 交互失败要有可感知反馈（至少日志或错误提示）
+- 注意终端/SFTP页面的响应性能，避免不必要重渲染
+
+## 8) 提交前自检清单
+
+- 后端改动：至少运行 `mvn test`（若存在测试）或最小可行编译验证
+- 前端改动：运行 `npm run build`（包含 `vue-tsc`）
+- 手工验证登录流程、连接列表、终端或 SFTP 关键路径（按改动范围）
+- 检查未提交敏感信息与本地配置
+- 仅提交与需求直接相关的文件
+
+## 9) 文档与规则文件检查结果
+
+- `AGENTS.md`：本文件为新建（仓库根目录）
+- Cursor 规则：未发现 `.cursor/rules/` 或 `.cursorrules`
+- Copilot 规则：未发现 `.github/copilot-instructions.md`
+
+若未来新增上述规则文件，agents 必须先读取并将其视为高优先级约束。