AGENTS.md
适用范围
本文件适用于当前仓库根目录及其所有子目录。
规则优先级
规则冲突时按以下顺序执行（从高到低）：
- 用户在当前任务中的明确指令
- 本文件（
AGENTS.md） - 仓库内其他说明文档（如
README.md、模块内注释约定） - 通用工程实践默认值
文档维护约定
- 仓库级 Agent 规范仅保留
AGENTS.md作为单一事实来源（Single Source of Truth）。 - 若新增其他工具专用说明文档，内容不得与
AGENTS.md冲突；冲突时以本文件为准。 - 更新规范时优先做“增量修改”，避免大段无语义改写导致历史难追踪。
项目定位
- 技术栈：
Vue 3+TypeScript+Vite+Pinia+Vue Router+Element Plus - 目标：后台管理系统前端（用户、角色、菜单、日志、系统监控等模块）
- 请求层统一入口：
src/utils/request.ts
目录约定
src/views/：页面模块（按业务目录组织）src/components/：可复用组件src/layouts/：布局组件（主布局：Main.vue）src/api/：接口定义，不在页面里直接写请求src/router/：路由和导航守卫src/stores/：Pinia 状态管理src/utils/：通用工具（鉴权、请求封装、响应码等）cypress/：E2E 测试
开发原则
- 保持小步改动，优先修复根因，避免无关重构。
- 新增业务逻辑时，优先放在
views + api + stores合理分层，不把逻辑塞进模板。 - 页面中禁止创建分散的 Axios 实例，统一使用
src/utils/request.ts。 - 优先复用现有组件和样式变量，避免重复实现。
- 保持与当前 UI 风格一致（Element Plus + 现有布局/表格/抽屉交互模式）。
- 接口相关改动必须同步更新
src/api层的类型与调用方，避免以any兜底掩盖问题。 - 单次任务优先保证单一目标，不跨业务模块做顺手重构；如需扩散改动，应先说明原因与影响。
代码风格
- 使用
script setup+ TypeScript。 - 缩进 2 空格、单引号、无分号、行宽 100（遵循 Prettier）。
- 组件文件名使用 PascalCase（如
UserDrawer.vue）。 - 业务页面目录名使用 kebab-case（如
operation-log）。 - 导入路径优先使用
@/别名。
命令规范
- 启动开发：
npm run dev - 类型检查 + 构建：
npm run build - 仅构建：
npm run build-only - 生产预览：
npm run preview - 类型检查：
npm run type-check - 单元测试：
npm run test:unit - E2E（preview）：
npm run test:e2e - E2E（dev）：
npm run test:e2e:dev - 代码检查（含自动修复）：
npm run lint - 代码格式化：
npm run format
实现约定补充
- 请求封装保持在
src/utils/request.ts，默认约定：基础 URL 为/api、超时 5000ms、withCredentials: true、Content-Type: application/json。 - 请求方法约定使用统一封装：
GET<T>、POST<T>、PUT<T>、DELETE<T>。 - 需要鉴权的请求通过
isToken控制是否附加 Bearer Token，Token 来源为getAccessToken()，本地存储 key 为accessToken。 - 认证守卫由
src/router/index.ts统一处理，受保护路由使用meta.requiresAuth。 - 路由定义位于
src/router/routes.ts；/login外路由与 tab 行为由现有menuTabsStore机制维护，禁止绕开。 - Pinia 中
menuTabsStore、menuCollapseStore使用持久化能力时，保持与现有 localStorage 行为一致。 - 路径别名统一使用
@/指向src/，新增代码优先使用该别名导入。
任务分级与最小校验矩阵
- 仅文档改动（如
*.md）：无需强制执行构建/测试命令，至少自检命令与路径引用准确性 - 文案/样式微调（无逻辑变化）：至少执行
npm run lint - 组件交互或页面逻辑改动：至少执行
npm run lint+npm run test:unit（无对应单测时执行npm run build） - 路由、鉴权、状态管理改动：至少执行
npm run build，并补充关键流程手工验证步骤 - API 结构或请求参数/响应处理改动：至少执行
npm run build，并验证对应页面主流程 - 构建配置改动（
vite.config.ts、tsconfig*、eslint.config.js）：至少执行npm run build+npm run lint
高优先级业务模块清单
- 登录与鉴权：
src/views/login/、src/utils/auth.ts、src/router/index.ts - 路由与权限入口：
src/router/、src/layouts/Main.vue - 全局请求与响应处理：
src/utils/request.ts、src/utils/responseCode.ts - 关键业务页面：
src/views/user/、src/views/role/、src/views/menu/ - 日志与审计相关：
src/views/login-log/、src/views/operation-log/、对应src/api/*
上述模块改动时额外要求：
- 在结果中单独标记“高优先级模块变更”及影响面。
- 至少执行
npm run build，并给出可复现的关键流程手工验证步骤。 - 若存在接口字段或权限行为变化，需明确前后端协作点和回滚注意事项。
变更执行清单
- 先阅读将要修改模块的现有实现，确认依赖关系（
api、store、router、组件复用点）。 - 实现最小闭环改动，避免顺手改动无关文件。
- 至少执行与改动匹配的校验：纯类型/逻辑改动执行
npm run build或npm run test:unit；UI/交互改动执行npm run lint，必要时补充截图说明。 - 输出变更说明时必须包含：修改文件、修改原因、验证方式、已知风险/后续建议。
异常处理约定
- 命令执行失败时，先检查是否为参数/环境问题并做一次有依据的重试。
- 若失败由外部条件导致（接口不可用、环境变量缺失、权限限制），需在结果中明确阻塞点与影响范围。
- 无法继续推进时，给出可选降级方案（如手工验证路径）并标注可信度边界。
- 不跳过关键校验且不说明理由。
测试要求
- 新增核心逻辑时补最小可验证单测（
*.test.ts/*.spec.ts）。 - 涉及关键主流程（登录、路由跳转、列表操作）变更时，补充或更新 Cypress 用例。
- 若当前任务无法补测，需明确说明未覆盖点和潜在风险。
- 若无法补充自动化测试，至少提供可复现的手工验证步骤和回归检查清单。
提交与 PR 规范
- Commit 信息使用简洁中文，建议格式：
模块: 变更内容- 示例：
用户管理: 修复编辑抽屉回填异常
- 示例：
- PR 描述至少包含：
- 变更背景
- 主要修改点
- 影响范围
- 验证方式
- 涉及 UI 调整附截图；涉及接口变更注明前后端协作点。
Agent 输出模板
每次任务完成后，按以下结构输出结果：
- 变更文件：列出具体文件路径
- 行为变化：说明用户可感知的变化与技术原因
- 验证结果：列出已执行命令与结论（通过/失败）
- 风险与未覆盖：说明未验证场景、潜在回归点
- 后续建议：仅在确有必要时给出
安全与配置
- 本地配置放
.env.development，严禁提交密钥、令牌、生产地址凭据。 - 不在日志中打印敏感信息（token、cookie、用户隐私字段）。
package.json、vite.config.ts、tsconfig*、.env*变更需在说明中单独标记影响范围。
禁止事项
- 未经说明，不修改与任务无关的大量格式或重命名。
- 未经确认，不升级核心依赖或切换构建工具链。
- 不绕开
router/store现有机制做临时硬编码。 - 不重新引入与
AGENTS.md重复且平级生效的仓库级规则文档（避免双份规范并存）。