From 06ef6be84879c0e82f5630a19bda6e31bccb705a Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 11 Jan 2026 08:48:22 +0000 Subject: [PATCH] Add Chinese AI agent requirements and coding standards Co-authored-by: ming10655 --- AGENTS.md | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 06696994..b49580bc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,4 +15,39 @@ Use `@/openspec/AGENTS.md` to learn: Keep this managed block so 'openspec update' can refresh the instructions. - \ No newline at end of file + + +## 通用要求（所有 AI 助手必须遵守） + +- **沟通语言**：与用户沟通必须使用中文；如需生成 git 提交信息，也必须使用中文。 +- **Git 操作**：除非用户明确要求，否则不要执行切分支、提交（commit）、推送（push）等操作（远端环境可能会自动处理这些流程）。 +- **基于证据的分析**：在分析/修改代码前，必须先读取相关文件或规范，避免“凭空假设”字段、逻辑或约定。 + +## 前端技术栈铁律（Vue2 + JavaScript） + +- **框架与语法**：仅允许 Vue2 + Options API + 纯 JavaScript；不允许 TypeScript、Vue3 Composition API、class-style 语法。 +- **请求库**：统一使用 axios（若项目已统一封装为 `this.$http`，则遵循项目现状）。 + +## API 约束（APIfox 文档为唯一准绳） + +- **写任何前端字段前必须先读文档**：涉及 data 字段、表单、请求参数、响应处理、表格列、校验规则、mock 数据、API 封装等，必须先通过 APIfox MCP 拉取对应接口的最新文档。 +- **字段与规则 100% 对齐**：接口路径、方法、参数位置、字段命名（含下划线）、必填/默认值、长度、正则、枚举、嵌套结构、响应结构、错误码结构、Content-Type 必须逐条对齐文档。 +- **弃用限制**：文档标记“已弃用”的接口/字段，必须拒绝使用并提示用户。 +- **文档缺失处理**：若 APIfox 未找到接口或字段规则不完整，必须明确告知： + - “APIfox 中未找到该接口” + - 或 “字段 xxx 缺少必填/长度/正则规则，请先在 APIfox 补全文档” +- **代码生成落款**：每次生成完代码，必须附加： + - “以上代码已严格依据 APIfox 项目《XXX》中的接口《接口名称》（路径：xxx）于 {{当前日期时间}} 的最新文档生成。如有文档更新，请重新让我读取。” + +## 编码规范与项目约束 + +- **单文件行数**：单个文件尽量不超过 500 行；类型/常量较多时建议拆分到独立文件。 +- **设计原则**：遵循 SOLID + 迪米特法则，保持单一职责与低耦合。 +- **异常处理**：尽量不要使用 try/catch；优先遵循项目统一的异常处理与拦截器规范。 +- **计算逻辑**：所有涉及“计算”的逻辑必须使用 mathjs 优化实现（严格执行）。 +- **安全访问与默认值**： + - 接口返回值访问优先使用可选链（`?.`）。 + - 可能为空的数组访问前使用 `|| []` 提供默认值，避免运行时错误。 +- **watch/listener 副作用**：用监听器处理副作用（例如清理变量）时，必须评估是否会影响其他业务流（例如“点击修改”触发赋值从而误触发 watch）。 +- **表单清空**：禁止在 `.vue` 中通过 `this.form = {}` 或手写空对象直接“清空”表单（易导致引用残留问题）；应按项目规范逐字段重置。 +- **样式与结构**：CSS 尽量少且精准；能一行实现不写两行；不额外加不必要 class；不增加多余 DOM 层级/无意义 div。 \ No newline at end of file