226 lines
13 KiB
Markdown
226 lines
13 KiB
Markdown
# AGENTS.md
|
|
|
|
<INSTRUCTIONS>
|
|
|
|
## 一、基本原则
|
|
|
|
1. 回答问题时避免过分夸赞。用户和 AI 的判断都可能不准确，应结合代码、日志、测试结果和现有实现反复核对，优先保证准确性。
|
|
|
|
2. 回答应保持结构化、条理清晰，明确区分：
|
|
- 已确认的事实
|
|
- 基于现有信息的推断
|
|
- 尚未确认的问题
|
|
- 实际修改和验证结果
|
|
|
|
3. 如果缺少的信息会显著影响实现方向、安全性或兼容性，应主动向用户索要补充信息或证据。对于不影响整体方向的小问题，可以结合项目现状作出合理假设，但必须说明假设内容。
|
|
|
|
4. 开始修改前，必须先阅读相关代码、项目结构、配置和调用链，确认问题根因及现有实现。禁止在未了解上下文的情况下直接创建一套平行实现。
|
|
|
|
5. 遵循最小改动原则：
|
|
- 只修改完成当前需求或解决根因所必需的代码。
|
|
- 禁止顺带重构无关代码。
|
|
- 禁止擅自升级依赖。
|
|
- 禁止调整无关代码格式。
|
|
- 禁止改变无关功能和既有行为。
|
|
- 禁止扩大用户未授权的修改范围。
|
|
|
|
6. 优先复用项目已有代码、组件、工具函数、服务和基础设施。相同逻辑、算法、功能、页面或样式应抽取为公共实现，禁止在多个位置重复实现，除非存在明确的独立实现理由。
|
|
|
|
7. 修改代码时，应保持现有接口、参数、返回结构、错误语义和业务行为兼容。确实需要破坏兼容性时，必须提前说明原因和影响范围，用户确认后才能实施。
|
|
|
|
8. 默认仅提供分析、解释、诊断、方案或修改建议。除非用户明确要求实施、修改、修复、创建、删除或重构，否则禁止主动更改任何代码、配置、数据库、依赖、文件或外部系统状态。
|
|
- “分析一下”“检查一下”“看看问题”“给出方案”“怎么实现”等表述，仅授权只读检查和提供建议，不代表授权实施修改。
|
|
- “帮我修改”“直接修复”“实现这个功能”“按方案执行”“开干”等明确表述，才视为授权实施。
|
|
- 获得实施授权后，只能修改当前需求明确涉及的范围，并遵循最小改动原则。
|
|
- 如果用户的表述无法判断是否授权修改，应先询问用户，不得自行实施。
|
|
- 读取文件、搜索代码、查看日志、运行不改变数据和外部状态的诊断命令，不视为代码修改。
|
|
|
|
---
|
|
|
|
## 二、文件与代码组织
|
|
|
|
1. 每个文件应具有明确职责，避免将路由、参数处理、业务逻辑、数据库操作和第三方服务调用全部堆放在同一个文件中。
|
|
|
|
2. 代码文件接近或超过 800 行时，应检查是否需要按照功能、业务领域、页面或组件职责进行拆分。
|
|
|
|
3. 800 行不是强制凑齐的目标：
|
|
- 800 行是一个参考值，根据项目需求和代码复杂度，可以适当调整。
|
|
- 超出 800 行的文件，应检查是否需要按照功能、业务领域、页面或组件职责进行拆分，不得盲目拆分。
|
|
- 禁止为了减少行数而将多行代码压缩成一行。
|
|
- 禁止为了形式上的拆分创建大量缺乏独立职责的小文件。
|
|
- 文件是否拆分应以职责边界、可维护性和复用价值为依据。
|
|
|
|
4. 新增公共能力前，必须先搜索项目中是否已经存在相同或相近实现。
|
|
|
|
5. 禁止使用 PowerShell、Python、重定向符或其他临时脚本拼接、生成或覆盖源代码文件。修改已有文件时，在原文件编码受支持且修改范围适合的情况下，应优先使用精确补丁，避免为少量改动重新写入整个文件；如果补丁方式不适用，应采用能够保持原文件编码、BOM 状态和换行格式的安全编辑方式。
|
|
|
|
6. 文件、模块、函数及数据库定义必须使用中文注释说明其用途：
|
|
- 每个支持注释的代码文件顶部，必须使用中文注释简要说明该文件的作用和主要职责。
|
|
- 每个模块、类、接口、组件和函数顶部，必须使用中文注释简要说明其用途；存在重要参数、返回值、副作用、异常或使用限制时，应一并说明。
|
|
- 数据库定义文件中，每个模型、表和字段都必须使用中文注释说明其业务含义；对于枚举值、关联关系、默认值、索引和约束，也应说明其用途。
|
|
- 修改代码功能、参数或字段含义时，必须同步更新对应注释，禁止保留与实际实现不一致的注释。
|
|
- 注释应说明职责、业务含义或设计原因，禁止仅将代码名称直译成没有实际信息的注释。
|
|
- JSON 等语法本身不支持注释的文件，不得为了添加注释而使用非标准语法或破坏文件有效性。
|
|
- 第三方依赖、自动生成文件、构建产物及无法安全添加注释的文件不受此规则约束，除非用户明确要求修改。
|
|
|
|
7. 必须保护文件编码和换行格式，禁止因读写方式不一致造成中文乱码：
|
|
- 修改文件前，应识别并保持原文件的字符编码、BOM 状态和换行格式。
|
|
- 修改已有文件时，禁止擅自将 UTF-8、UTF-8 with BOM、GBK、UTF-16 等编码相互转换。
|
|
- 新建文本文件默认使用 UTF-8 编码；如果项目已有明确编码规范，则遵循项目现有规范。
|
|
- 禁止通过读取全文后重新写入的方式完成少量修改。
|
|
- 修改后必须检查本次变更中的中文内容是否正常，重点检查是否出现 `�`、异常问号或类似“涓枃”的乱码。
|
|
- 如果无法确定文件原始编码，应停止写入并先说明情况，不得猜测编码后直接覆盖。
|
|
- 禁止为了统一编码而批量转换无关文件；确需转换时，必须获得用户明确授权。
|
|
|
|
---
|
|
|
|
## 三、后端模块化与解耦
|
|
|
|
1. 后端应按照业务领域和职责进行模块化设计，实现关注点分离和低耦合。
|
|
|
|
2. 上传、删除、查询、转换、通知等不同业务能力，应根据实际职责划分为独立模块。禁止仅通过复制文件或移动代码实现表面上的模块化。
|
|
|
|
3. 每个后端业务模块必须使用独立目录组织。即使该业务模块当前只有一个功能或一个实现文件，也必须为其创建单独目录，禁止将不同业务模块的实现文件直接平铺在公共目录中。
|
|
|
|
- 本规则所称“业务模块”，是指具有独立业务职责、领域边界或外部服务集成边界的功能，例如用户、订单、支付、文件管理、AI 中转站和对象存储。
|
|
- 普通工具函数、常量、类型定义、内部辅助类和仅服务于某个模块的实现，不视为独立业务模块，不要求分别创建目录。
|
|
- 模块相关的业务逻辑、数据访问、类型、配置和外部服务适配代码，应集中放置在该模块目录中。
|
|
- 模块只有一个简单功能时，可以只包含一个实现文件；不得为了填充目录而创建没有实际职责的文件。
|
|
- 模块包含多个职责明确的子功能时，应按照子功能分别创建文件；子功能不需要建立子目录。
|
|
- 基础 CRUD 操作通常是同一业务实体的数据访问方法，不得仅按照新增、查询、修改和删除机械拆分为四个模块。
|
|
- 不强制为每个模块创建 `index`、`types`、`service` 等固定文件，只有存在实际职责时才创建。
|
|
- 新增模块以及本次需求实际修改的模块必须遵守本规则；禁止为了统一目录形式而擅自重构与当前需求无关的既有模块。
|
|
- 目录和文件命名应遵循项目现有命名规范。
|
|
|
|
4. 模块之间应通过明确的公开接口进行调用，包括：
|
|
- 函数参数
|
|
- 返回值
|
|
- 类型或接口
|
|
- 服务抽象
|
|
- 依赖注入
|
|
- 事件机制（仅在确有异步解耦需求时使用）
|
|
|
|
5. 禁止一个模块直接访问另一个模块的内部变量、私有实现、内部数据库细节或非公开文件。
|
|
|
|
6. 模块应遵循单一职责原则。根据项目技术栈和现有结构，可以按以下职责组织：
|
|
- Router：定义路由和中间件
|
|
- Controller：接收请求、校验输入、调用服务、组织响应
|
|
- Service：实现业务逻辑
|
|
- Repository：封装数据库或持久化操作
|
|
- Adapter：封装外部存储、第三方 API 等基础设施
|
|
- Types/Interfaces：声明模块对外契约
|
|
|
|
7. 上述分层是职责参考，不是强制要求。对于简单功能，可以合并没有独立价值的层级，绝对禁止为了套用架构而过度设计。
|
|
|
|
8. 其他代码调用某个模块时，应只使用该模块明确对外提供的函数、参数和返回值，禁止依赖该模块的内部变量、内部文件或具体实现方式。模块内部实现被替换或扩展时，应尽量避免要求其他无关代码同步修改。
|
|
|
|
9. 模块内部实现可以变化，但对外接口应尽量保持稳定。
|
|
|
|
10. 禁止循环依赖。发现循环依赖时，应优先检查：
|
|
- 职责是否划分错误
|
|
- 是否存在应抽取的公共能力
|
|
- 是否需要使用抽象接口
|
|
- 是否错误地让业务模块相互了解内部实现
|
|
|
|
11. 公共逻辑只能保留一套权威实现。禁止在上传、删除或其他模块中分别复制相同的：
|
|
- 权限校验
|
|
- 路径处理
|
|
- 文件校验
|
|
- 错误转换
|
|
- 数据查询
|
|
- 状态判断
|
|
|
|
12. 模块化改造应保持现有接口路径、请求参数、响应结构和错误行为兼容，除非用户明确要求修改。
|
|
|
|
---
|
|
|
|
## 四、前端开发
|
|
|
|
1. 前端禁止使用多渐变色，仅能使用同色系渐变，且不能太艳丽。
|
|
|
|
2. 前端禁止使用 Emoji 作为图标。图标必须统一使用第三方图标库；如果项目已经选定图标库，禁止再引入另一套图标库。
|
|
|
|
3. 前端禁止主动增加无障碍设置，包括但不限于额外的 ARIA 属性、无障碍模式和无障碍专用交互。
|
|
|
|
4. 前端禁止增加键盘快捷键、按键监听或依赖键盘完成的交互，除非用户明确要求。
|
|
|
|
5. 前端必须采用响应式布局，应适配项目现有支持的桌面端、平板端和移动端尺寸。
|
|
|
|
6. 前端必须使用统一的样式系统：
|
|
- 使用统一的颜色、间距、字号、圆角、阴影和层级变量。
|
|
- 使用语义化变量名，禁止在业务组件中散落大量无语义的硬编码样式值。
|
|
- 样式应放入项目现有的统一样式文件、主题文件或设计令牌系统。
|
|
- 优先复用现有组件和样式类。
|
|
- 禁止同一种视觉效果在多个页面分别实现。
|
|
|
|
7. 除非用户明确要求，否则前端禁止使用英文副标题。界面文案应与项目现有语言和表达方式保持一致。
|
|
|
|
8. 页面和组件应根据职责合理拆分。公共交互、公共布局和公共业务展示应抽取为公共组件，禁止在多个页面复制相同实现。
|
|
|
|
9. 修复前端问题时，仅修改解决根因所需的组件、样式和逻辑，禁止顺带重做页面设计。
|
|
|
|
---
|
|
|
|
## 五、数据库修改
|
|
|
|
1. 涉及数据库结构修改时，必须同时完成：
|
|
- 更新数据库定义文件或 Schema。
|
|
- 创建对应的数据库迁移文件。
|
|
- 实际执行数据库迁移。
|
|
- 检查迁移执行结果。
|
|
- 验证应用代码与新结构兼容。
|
|
|
|
2. 禁止只修改或新增迁移文件而不更新数据库定义文件。
|
|
|
|
3. 禁止只更新数据库定义文件而不创建和执行迁移。
|
|
|
|
4. 修改字段、索引、约束、默认值或数据类型前，应检查现有数据兼容性和迁移风险。
|
|
|
|
5. 涉及删除字段、修改字段类型、增加非空约束等可能造成数据丢失或迁移失败的操作时，必须先说明风险，并制定数据迁移或兼容方案。
|
|
|
|
6. 数据库迁移完成后，应验证：
|
|
- 当前数据库版本
|
|
- 新旧数据兼容性
|
|
- 相关查询和写入逻辑
|
|
- 回滚或恢复风险
|
|
|
|
---
|
|
|
|
## 六、验证要求
|
|
|
|
1. 修改完成后，应优先运行与本次修改直接相关的：
|
|
- 单元测试
|
|
- 集成测试
|
|
- 类型检查
|
|
- 编译或构建检查
|
|
- Lint 检查
|
|
- 数据库迁移检查
|
|
|
|
2. 除非用户明确要求，否则必须禁止主动使用浏览器进行验证，也禁止主动调用浏览器自动化工具。
|
|
|
|
3. 如果前端修改无法通过现有自动化测试充分验证，应说明未验证的具体部分，不得将未验证内容描述为已经确认正常。
|
|
|
|
4. 测试失败时，应区分：
|
|
- 本次修改导致的失败
|
|
- 项目原本存在的失败
|
|
- 环境或依赖导致的失败
|
|
|
|
5. 禁止为了让测试通过而删除测试、降低断言强度、屏蔽错误或跳过必要检查。
|
|
|
|
---
|
|
|
|
## 七、任务完成后的输出
|
|
|
|
完成任务后，应简要说明：
|
|
|
|
1. 问题根因或实现依据。
|
|
2. 实际修改的文件和主要内容。
|
|
3. 模块之间的调用关系。
|
|
4. 是否涉及接口或兼容性变化。
|
|
5. 是否涉及数据库迁移及执行结果。
|
|
6. 已运行的验证命令及结果。
|
|
7. 尚未验证的内容、已知限制和潜在风险。
|
|
|
|
禁止声称未实际执行的测试、迁移或验证已经通过。
|
|
|
|
</INSTRUCTIONS> |