## 全局规则概览
- 这是面向 agentic coding agents 的工作指引，覆盖构建、质量、风格、流程与协作。
- 文件应保持最新，优先在仓库根目录维护。
- 如遇新工具/工作流，应扩展本文件并在 PR 中同步讨论。 

## 构建/ lint/ 测试
- 常用命令：
  - 构建: `npm run build` / `pnpm build` / `yarn build`
  - 静态检查: `npm run lint` / `pnpm lint` / `yarn lint`
  - 单元测试: `npm test` 或 `npm run test`，可用 `-t` 指定测试名称
  - 集成测试: `npm run test:integration`（若存在）
  - 生成报告: `npm run build -- --report`
- 单个测试定位与执行
  - 按关键字定位：`npm test -- -t "<testName>"`
  - 指定文件：`npx vitest run path/to/file.test.ts -t "<testName>"`，Jest: `npm test -- path/to/file.test.ts -t "<testName>"`
  - PNPM/Yarn 资源：`pnpm test -- -t "<testName>"` / `yarn test -- -t "<testName>"`
  - Vitest 的完整 CLI：`npx vitest run -t "<testName>"` 或 `npx vitest run path/to/file.test.ts`
- 运行快速片段测试
  - 通过关键字快速定位：`npm test -- -t "keyword"`
- 持续集成与日志
  - CI 应锚定一次完整测试：测试完成后再进行打包与部署
  - 日志输出应明确包含：时间戳、测试名称、通过/失败、覆盖率（如有）
- 提交与钩子
  - 本地执行前请确保已安装依赖，`node_modules` 不应缺失
  - 使用 lint/test 流程，确保提交前通过静态检查与测试

## 代码风格指南
- 导入与模块组织
  - 外部依赖放在顶部，内部/本地导入放在后
  - 使用路径别名时，优先正式路径，避免跨根引用
  - 未使用的导入应清理，静态分析应通过
  - 使用 `import type` 显式标注类型导入以减少运行时开销
- 格式化与排版
  - 统一使用 2 空格缩进
  - 语句结尾使用分号，除非项目规定不使用
  - 行宽约 80-120 字符，超出时换行
  - 尾随逗号可在导入/对象字面量中使用，便于 diff
- TypeScript 类型
  - 首选 interface，联合类型使用判别性联合
  - 使用 readonly 保护不可变数据
  - 避免 any；若必要，尽量用 unknown，逐步收窄
  - 函数参数与返回值提供明确的类型签名
- 命名与风格
  - 变量与函数采用 camelCase
  - 类型/类使用 PascalCase，常量使用 UPPER_SNAKE
  - 避免无意义缩写，含义清晰
- 错误处理
  - 不吞错，抛出有意义的错误信息
  - 自定义错误类型，提供上下文
  - 保留原始堆栈便于调试
  - catch 中避免抛出模糊错误
- 异常与边界
  - 输入要严格校验，错误信息要具备帮助性
  - 未覆盖的分支显式抛出未实现错误
- 日志与追踪
  - 生产环境应统一日志组件，避免裸 console.log
  - 日志包含时间戳、级别、信息、上下文
- 测试友好性
  - 测试应可重复、可预测，避免随机性
  - 覆盖边界的测试用例命名应描述性
  - fixtures 放在 test/fixtures，测试后清理
- 依赖与版本
  - 锁定版本，避免不可预测更新
  - 使用 lock 文件管理依赖
- 代码审查与提交
  - 提交前本地执行 lint/test，确保通过
  - 提交信息遵循一致的风格，可通过 Conventional Commits 风格
  - 合并冲突后给出清晰的上下文注释
- 结构与可维护性
  - 遵循单一职责原则，模块职责清晰
  - 设计对扩展友好，遵循开闭原则
  - 重要逻辑应有文档注释
- 安全性
  - 不将敏感信息提交到仓库
  - 使用环境变量来管理机密
- 性能意识
  - 延迟加载、按需初始化
  - 缓存可重复计算结果
  - 避免在渲染周期执行昂贵计算
- 兼容性
  - 兼容主流运行环境，必要时使用 polyfill
- 可访问性
  - 考虑无障碍与测试性
- 组合与模块化
  - 目录结构应清晰，循环依赖最小化
  - 模块通过接口通信，隐藏实现细节
- 注释与文档
  - 关键逻辑提供 JSDoc / TSDoc
  - 重要行为描述清晰，避免歧义
- 测试约定
  - 测试名称具描述性，覆盖边界
  - fixtures 放 test/fixtures
  - 使用 setup/teardown 钩子清理环境
- 运行环境与依赖
  - 锁定版本，使用 lock 文件
  - 构建/测试所需的依赖要在 package.json 中明确
- 代码审查与协作
  - 提交前本地运行 lint/test，确保通过
  - 处理冲突时提供可追踪的复核信息

## 项目结构与约定
- 代码分层
  - api/ 数据接入接口
  - store/ 全局状态管理
  - components/ 可复用 UI 组件
  - hooks/ 自定义 Hook
  - views/ 业务页面
  - plugins/ 插件封装
  - types/ 公共类型定义
- 命名约定
  - 文件/目录使用小写+连字符命名
  - 变量、函数遵循 camelCase
  - 类型/类遵循 PascalCase
- 导出与导入
  - 默认导出尽量少，命名导出优先
  - 按功能模块导出，避免跨模块耦合
- 测试结构
  - 单元测试靠近实现、集成测试覆盖路由/接口
  - 端到端测试放在 test/e2e

## Cursor 规则
- 如存在 Cursor 规则，请放在 .cursor/rules/，并在此处合并引用
- 当前仓库未发现实际 Cursor 规则文件，将在发现后集成

## Copilot 规则
- 如存在 Copilot 规则，请放在 .github/copilot-instructions.md，合并引用
- 当前仓库未发现 Copilot 指令文件，将在发现后集成

## 质量信号与改进计划
- 发现的常见信号：console/log 调试信息、TODO/FIXME、any 的使用、@ts-ignore、未使用变量
- 针对这些信号，提出逐步改进计划（以 PR 形式提出）
- 成功落地后标记该任务为已完成，更新计划

## 维护与更新
- 定期回顾 AGENTS.md 的适用性
- 新工具/新框架出现时，更新本文件的版本兼容性条款
- 提交变更时附带简短的变更说明，方便团队理解