xdz-pc/AGENTS.md

全局规则概览

• 这是面向 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 的适用性
• 新工具/新框架出现时，更新本文件的版本兼容性条款
• 提交变更时附带简短的变更说明，方便团队理解