AGENTS.md

AI 开发助手行为准则

项目技术栈与环境

• 核心框架: Vue 3 + Electron
• UI 组件库: Naive UI (严禁混用其他 UI 库)
• 包管理器: 严格使用 pnpm (严禁使用 npm/yarn)
• 开发命令: pnpm dev (预览代码)
• 代码质量: 每次任务结束前，必须自动运行 pnpm lint 并修复所有问题，确保 0 错误、0 警告后方可交付。
• 提交之前: 必须运行 pnpm build 和 pnpm format 并修复所有问题，确保 0 错误、0 警告后方可提交。

代码风格与规范

1. 注释规范

• 语言: 必须使用中文。
• 格式: 保持简洁，禁止长句、英文长文或带序号的注释。
  • 正确: // 监听主进程消息
  • 错误: // 1. listen to main process, // this function handles ipc...

2. UI 组件使用 Naive UI

• 原则: 严禁重复造轮子。所有通用交互必须优先使用 Naive UI 组件。
• 处理方式: 如果未找到合适组件，必须先询问用户，禁止擅自手写原生 CSS/HTML 组件。
  • 正确: 使用 <n-button type="primary">, <n-modal>, <n-message-provider>
  • 错误: 手写 <div class="my-btn"> 或引入 Element Plus 等其他库。

3. 图标

• 原则: 优先复用项目 src/assets/icons 或现有图标方案。
• 具体实现: 严格遵循项目现有的图标组件用法。
  • 正确: <SvgIcon :name="isLikeAlbum ? 'Favorite' : 'FavoriteBorder'" />
  • 错误: 擅自引入 xicons (除非用户明确允许) 或手写 SVG 代码。

4. Electron 特性规范

• 进程安全: 明确代码运行环境（Main vs Renderer）。不要在渲染进程中直接调用不安全的 Node.js API，应优先使用 IPC 通信或 Preload 脚本暴露的 API。
• 通信规范: 涉及 IPC 通信时，保持频道命名清晰且常量化。

5. 测试与清理

• 临时文件: 任务过程中生成的临时测试文件（如 test_lrc.ts），必须在任务结束前自动删除，严禁推送到代码库。

交互与思维链

1. 遇到困难多确认

• 原则: 禁止假设。当遇到不理解的概念（特别是 Electron 的通信逻辑或原生能力调用）时，必须暂停并向用户提问。
  • 禁止: “我猜用户是想在渲染进程直接读文件...” -> 导致安全报错。
  • 建议: “此处涉及文件系统操作，请确认是通过 IPC 调用主进程处理，还是使用现有的工具函数？”

2. 复杂任务先规划

• 文档驱动开发: 遇到复杂功能（如窗口管理、系统托盘、复杂逻辑重构）时，必须先创建一个临时的 Markdown 文档（如 name_of_task.md）。
• 流程: 在文档中梳理思路 -> 展示给用户 -> 用户同意 -> 开始写代码。

3. 复用优先DRY原则

• 原则: 在编写新功能前，强制检索项目现存代码。
• 自检: “项目中是否已经有类似的 IPC 封装或 UI 组件？”如果是，直接复用。

4. 聊天方式

• 原则: 与用户保持中文对话，禁止使用英文或其他语言。
• 具体实现: 所有与用户的交互（包括问题、指令、代码展示等）都必须用中文进行。

严格合规声明

• 指令等级: Critical。
• 违规后果: 违反以上任何一条规则将被定义为任务失败，代码将被直接拒绝。请务必严格执行上述标准。