Skip to content

AGENTS.md

Latest commit

 

History

History
58 lines (36 loc) · 3.73 KB

AGENTS.md

File metadata and controls

58 lines (36 loc) · 3.73 KB
Raw

AI 开发助手行为准则

项目技术栈与环境

  • 核心框架: React + Chromium Embedded Framework
  • UI 组件库: MUI
  • 包管理器: bun (不要使用 npm 或其他包管理器)
  • 构建命令: bun run build
  • 测试: 让用户运行 bun dev 然后打开网易云人工测试

代码风格与规范

1. Chromium Embedded Framework 框架特性规范

  • 固定的环境: 此插件固定运行在 Chromium 91.2.2.0 上，必须使用支持的最新的 JS 语法、方法等，尽可能遵循支持范围内的最佳实践，无需考虑其他浏览器的兼容性。避免使用较新的、不支持的方法或 CSS 样式等。
  • 原生桥梁: 全局环境中存在 window.channel，网易云音乐客户端使用它来进行前后端通信，legacyNativeCmder 或 v3 特有的 bridge 模块是对其的高层封装。更多注意事项参考 global.d.ts

2. BetterNCM 环境相关

  • 顶层 await: BetterNCM 会将编译后的 JS 代码放在异步函数中，于网易云音乐的主页面（网易云音乐是一个单页应用）执行，因此你可以使用顶层 await 或者其他可以在异步函数体内使用的语法。
  • 文件系统 API: BetterNCM 向全局的 betterncm.fs 下注入了文件系统相关的 API，因此你可以在浏览器环境中直接操作用户电脑上的文件，详情参考 betterncm.d.ts
  • 全局 React 实例: 网易云使用的 React 版本 16.14 较旧，一般建议手动打包一个 React 进去以便和新的 UI 库兼容。除非不需要任何较新的 UI 库，此时才应该使用全局的 React 实例

3. 逆向相关

由于此项目是一个注入到网易云音乐内的插件，因此不可避免地要进行逆向工程。若要进行任何逆向工程请务必询问用户是否有完成逆向，应如何实现。或只写一个桩函数，待用户逆向完毕后再填充。禁止随意猜测逆向细节。

访问网易云内部的对象或方法时，必须判空、使用可选链或空值合并操作符。定义 TS 类型时，尽量声明为可空的，除非它确实不可能不存在。

4. TS 类型相关

尽量定义良好的 TS 接口或类型，避免使用 any。unknown 也尽量避免，除非输入的数据确实是未知的。如果必须使用（例如信息不足等），在附近添加注释以说明为什么要使用。如果可能，提示之后完善此处的类型。

交互与思维链

1. 遇到困难多确认

  • 原则: 禁止假设。当遇到不理解的概念（特别是网易云音乐内部的架构）时，必须暂停并向用户提问。
    • 禁止: “假设我应该直接使用 window.channel 上的 registerCall 方法向后端注册回调...” -> 绕过并和高层封装产生冲突
    • 建议: “此处涉及调用网易云音乐后端，应该使用 window.legacyNativeCmder 还是 v3 特有的 bridge 模块？”

2. 复杂任务先规划

  • 文档驱动开发: 遇到复杂功能（如需要大量耦合网易云音乐的内部实现）时，必须先写一个临时的 Markdown 文档。
  • 流程: 在文档中梳理思路 -> 展示给用户 -> 用户同意 -> 开始写代码。

3. 复用优先DRY原则

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

4. 聊天方式

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