From af3ce43e42705792b1dd072a3bcb894920e81e3a Mon Sep 17 00:00:00 2001
From: xudan <staysky25@outlook.com>
Date: Fri, 12 Dec 2025 16:42:28 +0800
Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E6=96=B0=E5=A2=9EAI=E7=BC=96?=
 =?UTF-8?q?=E7=A8=8B=E6=8C=87=E5=AF=BC=E6=96=87=E6=A1=A3=EF=BC=8C=E8=A7=84?=
 =?UTF-8?q?=E8=8C=83Vue=E9=A1=B9=E7=9B=AE=E5=BC=80=E5=8F=91=E6=B5=81?=
 =?UTF-8?q?=E7=A8=8B=E4=B8=8E=E4=BB=A3=E7=A0=81=E9=A3=8E=E6=A0=BC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 183 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 183 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 596b3a6..b825884 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -44,3 +44,186 @@
 
 -Always reply to me in Chinese
 文件编码使用 UTF‑8
+
+
+---
+
+# web-amr 项目 AI 编程指导（Vue 3 + Vite + TS + Ant Design Vue + Pinia）
+
+本指南用于约束 AI 在本项目中新增功能/修复 Bug 的方式，目标是：代码优雅、可维护、可读、符合主流 Vue 生态实践，并与仓库现有风格一致。
+
+---
+
+## 1. 总体原则
+
+1. **先理解再动手**  
+   - 先搜索仓库已有实现（同类页面/组件/Store/接口封装），优先复用现成模式。  
+   - 不引入新范式/新库，除非明确要求；避免“为了重构而重构”。
+
+2. **最小必要改动（Minimal Diff）**  
+   - 只改与需求直接相关的文件和逻辑。  
+   - 不随意改命名、格式、结构；不顺手修“无关的”问题。
+
+3. **分层清晰、职责单一**  
+   - UI 逻辑、业务逻辑、数据访问、状态管理分离。  
+   - 一个文件/组件只负责一类事情。
+
+4. **可读性优先于“聪明”**  
+   - 选择易懂的实现而非炫技。  
+   - 复杂逻辑拆分为可测试的小函数/Hook/Store action。
+
+---
+
+## 2. 项目结构与放置规范
+
+- 页面：`src/pages/**`  
+  - 每个页面一个文件夹，包含 `index.vue`、子组件、局部 hooks、局部类型。
+- 组件：`src/components/**`  
+  - 复用组件放这里；页面私有组件放页面目录内。
+- 状态：`src/stores/**`（Pinia）  
+  - 全局/跨页面状态必须放 Store。
+- 接口：  
+  - `src/apis/**`：接口定义、类型、路径、参数；  
+  - `src/services/**`：Axios 实例、拦截器、通用请求工具。
+- Hooks：`src/hooks/**`  
+  - 复用的组合式逻辑；页面私有 hooks 放页面目录。
+- 静态资源：`src/assets/**`、`public/**`
+
+**放置判定：**  
+跨页面复用 → `components/stores/hooks/apis`；仅当前页面使用 → 页面目录内。
+
+---
+
+## 3. Vue 组件设计（主流实践）
+
+1. **Composition API + `<script setup lang="ts">`**
+   - 使用 `ref/reactive/computed/watch` 等组合式 API。
+   - 逻辑块按：`props -> emits -> state -> computed -> watchers -> methods -> lifecycle` 顺序组织。
+
+2. **组件拆分规则**
+   - 当组件出现以下任一情况必须拆分：  
+     - 文件 > 200 行且含多个业务区域；  
+     - 同一文件里出现多个“独立区域”的 UI/逻辑；  
+     - 有可复用的表单、表格、弹窗、卡片、列表项等。
+   - 拆分后：父组件负责**数据/状态/事件串联**，子组件负责**局部展示与交互**。
+
+3. **Props/Emits 约束**
+   - Props 必须有 TS 类型且语义清晰；不要透传大对象导致耦合。  
+   - 子组件通过 `emit` 通知父组件，不直接改父组件状态。
+
+4. **避免反模式**
+   - 不在模板中写复杂表达式（>1 行逻辑移到 computed）。  
+   - 不在组件内手动维护“全局状态影子副本”。  
+   - 不把 API 请求散落在多个子组件中。
+
+---
+
+## 4. 状态管理（Pinia）
+
+1. **什么时候用 Store**
+   - 跨组件/跨页面共享；  
+   - 需要缓存/持久化；  
+   - 逻辑复杂、含多处读写；  
+   - 与权限、用户、全局配置、设备/机器人状态相关。
+
+2. **Store 设计**
+   - `state`：只放数据，不放派生值。  
+   - `getters`：派生/只读视图。  
+   - `actions`：异步与业务逻辑（含 API 调用、数据归一化）。
+   - **禁止在组件里复制一份全局状态再手动同步。**
+
+3. **调用方式**
+   - 页面进入时 `store.actionFetch()` 拉取，组件只消费 store。  
+   - 需要局部临时状态（表单草稿、展开折叠）放组件内。
+
+---
+
+## 5. 接口与数据层
+
+1. **接口位置**
+   - 接口定义放 `src/apis/**`，按领域/模块拆文件。  
+   - 组件/页面不直接写 URL 字符串或 Axios 逻辑。
+
+2. **类型先行**
+   - 所有请求/响应必须有 TS 类型；  
+   - 类型从后端字段映射后再进入 UI（必要时做 `transform`）。
+
+3. **错误与边界处理**
+   - 接口失败要有可预期的 UI 反馈（message/notification/empty）。  
+   - 不吞异常；在 action 层统一 try/catch。
+
+---
+
+## 6. 类型与可维护性
+
+- 组件 props、emits、store state/action、API 入参/出参必须显式类型。  
+- 避免 `any`；需要时用更窄的 `unknown` + 类型守卫。  
+- 公共类型放 `src/apis/types` 或模块 `types.ts`。  
+- 复杂对象优先 `interface/type` 命名清晰。
+
+---
+
+## 7. UI 与 Ant Design Vue 规范
+
+- 组件命名、用法遵循 Ant Design Vue 官方 API。  
+- 表单使用 `a-form`/`a-form-item` + 规则校验，不手写校验状态。  
+- 表格分页、排序、筛选走 Ant 事件与参数，不做自定义混乱实现。  
+- 弹窗/抽屉优先抽成可复用组件。
+
+---
+
+## 8. 样式与布局
+
+- 统一 SCSS，缩进 2 空格。  
+- 样式尽量局部作用（`scoped` 或 BEM 风格）。  
+- 不在模板内写行内样式，除非是动态且非常简单。  
+- 顺序遵循 Recess/Stylelint 推荐（位置/盒模型/排版/视觉/动画）。
+
+---
+
+## 9. 性能与体验
+
+- 列表/表格大数据注意：分页、虚拟滚动（如已有方案则复用）。  
+- 计算量大逻辑放 `computed`，避免频繁 `watch`。  
+- 路由懒加载、组件按需引入遵循现有配置。  
+- 避免无意义的深拷贝和 watch 深度监听。
+
+---
+
+## 10. 代码风格（必须遵守）
+
+- UTF-8 编码；TS + Vue SFC；2 空格缩进；**单引号**；**必须分号**；`max-len 120`。  
+- 导入排序使用 `eslint-plugin-simple-import-sort`，不要手动乱序。  
+- 组件命名帕斯卡；公共组件文件名语义化。  
+- 禁止一字母变量名（循环计数 i/j/k 除外）。
+
+---
+
+## 11. 提交前自检清单（AI 输出代码前需自查）
+
+- 是否复用/延续了仓库已有模式？  
+- 是否把共享状态放进 Pinia，而非组件“手动同步”？  
+- 是否按职责拆分组件，父管业务/子管展示？  
+- API 是否全部走 `apis/services`，且有类型？  
+- 代码是否仅包含本需求相关改动？  
+- ESLint/Stylelint/Prettier 风格是否一致？
+
+---
+
+## 12. AI 禁止事项（Hard Don’ts）
+
+- 不引入新状态库/新架构（除非明确要求）。  
+- 不在组件中复制全局状态再手动维护一致性。  
+- 不把业务逻辑硬塞进模板/样式/子组件里。  
+- 不做无关重构、无关格式化、无关命名调整。  
+- 不输出“看似能跑但难维护”的临时方案。
+
+---
+
+## 13. 推荐的开发步骤（AI 应遵循）
+
+1. 明确需求与边界 → 列出影响的页面/Store/API。  
+2. 搜索现有相似实现 → 决定复用与扩展点。  
+3. 先设计数据流/状态流 → 再落地 UI 与组件拆分。  
+4. 先写 types + apis + store actions → 再写页面/组件。  
+5. 最后补齐异常处理、空态、加载态与交互细节。