From 5d42c2bfe6399dfbf4ff118b31b5518ede9b9731 Mon Sep 17 00:00:00 2001 From: lzh Date: Thu, 23 Apr 2026 17:49:22 +0800 Subject: [PATCH] =?UTF-8?q?feat(iot-v2):=20=E6=96=B0=E5=A2=9E=20AGENTS.md?= =?UTF-8?q?=20=E8=B7=A8=20agent=20=E9=80=9A=E7=94=A8=E8=A7=84=E8=8C=83?= =?UTF-8?q?=EF=BC=88=E6=96=B9=E6=A1=88=20C=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AGENTS.md 作为 agents.md 标准规范文件（Claude Code/Cursor/Codex 等通用） - .gitignore 补充 .claude/ 和 CLAUDE.md 忽略规则 - AGENTS.md 追踪进入 git（团队共享） 涵盖： - 项目背景（IoT v2.0 前端升级） - 任务卡系统引用（14-任务执行卡/Fxx） - 硬约束（分支 feat/iot-2.0 / 禁止 push / 决策 5 双入口） - 前端约定（TS 严格 / pnpm catalog / i18n / 模板变量） - 告警正交状态 5 种组合展示（评审 C1） Co-Authored-By: Claude Opus 4.7 (1M context) --- .gitignore | 5 ++ AGENTS.md | 215 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 220 insertions(+) create mode 100644 AGENTS.md diff --git a/.gitignore b/.gitignore index 3399f39c0..351a4836d 100644 --- a/.gitignore +++ b/.gitignore @@ -50,3 +50,8 @@ vite.config.ts.* *.sw? .history .cursor + +# AI Agent 本地配置 +.claude/ +CLAUDE.md +# AGENTS.md 允许追踪（跨 agent 通用规范，方案 C） diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..7b3850600 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,215 @@ +# AGENTS.md — IoT v2.0 升级（前端） + +> 本文档给所有 AI Agent（Claude Code / Cursor / Windsurf / Codex CLI / Aider 等）看 +> 遵循 [agents.md](https://agents.md/) 标准 +> 本 worktree 专用于 IoT 模块 v2.0 升级前端实施 +> 对应分支：`feat/iot-2.0` + +--- + +## 一、项目背景 + +AIoT 前端（vben-admin 5.5.9 monorepo）IoT v2.0 升级前端： + +- **技术栈**：Vue 3 + Ant Design Vue + Vben Admin 5.5.9 + pnpm 10+ + Node 20.19+ + Turborepo +- **目标**：规则链 DAG 画布 + 子系统管理 + 告警正交状态机展示 + 派生物模型 +- **范围**：第一期 F1-F11（11 个前端任务） +- **后端配对**：`C:\workspace\java17\aiot-platform-cloud-iot`（分支 `feat/iot-2.0`，承接 B1-B19） +- **主工作应用**：`apps/web-antd/`（生产使用） + +--- + +## 二、任务卡系统（权威 spec） + +所有任务的需求 / 验收 / 约束在任务卡： + +| 资源 | 绝对路径 | +|------|---------| +| 任务卡目录 | `C:\document\AIOT\开发者文档\03-IoT领域\升级设计方案\14-任务执行卡\` | +| 目录说明 + Wave 依赖 | `14-任务执行卡\README.md` | +| 评审档案 | `13-评审记录\01-10-轮次报告` + `11-决策记录` | + +**本 worktree 任务范围**：仅 **F 开头前端任务**，第一期 F1-F11。 + +--- + +## 三、硬约束（所有 Agent 共守） + +### 3.1 Git 边界 + +- **分支**：`feat/iot-2.0`（worktree 绑定） +- **禁止**：`git push`、`git push --force`、`--no-verify`、`--amend` 已推送的 commit +- **禁止**：`git checkout` 切换分支（worktree 固定） +- 本地 commit 即可，等人工 review 后再推送 + +### 3.2 任务范围 + +- 第一期仅 F1-F11 +- 禁止做 F12+（第二期起） + +### 3.3 决策 5 双入口路由（**不可违反**） + +- **保留**现有 `/iot/rule/scene/*`（v1 场景规则表单页）—— 不改不删 +- **新增** `/iot/rule/chain/*`（v2 DAG 画布） +- 两入口平级共存，不做自动跳转 +- 灰度全量切换后再 `hidden: true`（v2.1 阶段处理） + +### 3.4 代码边界 + +- **禁止**修改 `apps/web-antd/src/views/iot/rule/scene/*` +- **禁止**修改 `apps/web-antd/src/router/routes/modules/iot.ts` 中现有 `scene` 路由项 + +### 3.5 质量门槛 + +- `pnpm check:type` 必须通过（TS 严格模式，**禁用 `any`**） +- `pnpm lint` 必须通过 +- `pnpm test:unit` 必须通过 +- Acceptance Criteria 逐项通过才 commit + +--- + +## 四、任务执行标准流程 + +1. **Read 任务卡**：`14-任务执行卡/Fxx-*.md`（绝对路径） +2. **Read source_doc** + CLAUDE.md（本目录） +3. **Read depends_on** 上游任务产出（含后端 VO 类型） +4. **按 Known Pitfalls 规避** +5. **实现 + Vitest 单元测试** +6. **运行质检三连**： + ```bash + pnpm check:type + pnpm lint + pnpm test:unit + ``` +7. **逐项 check Acceptance**；未全通过不 commit +8. **commit 规范**（中文）： + ``` + [Fxx] 任务标题 + + - 主要文件 1 + - 主要文件 2 + - Known Pitfalls 落地：⚠️ 评审 Xx + + Co-Authored-By: + ``` +9. **更新任务卡** frontmatter：`status: completed` + `updated: ` +10. 查 `README.md §3.3` 下游 Wave + +--- + +## 五、关键前端约定（第 8 轮评审 + 决策 5） + +| 约定 | 规则 | +|------|------| +| **TypeScript 严格** | 不用 `any`；与后端 VO 类型对齐手动同步 `.d.ts` | +| **依赖管理** | pnpm catalog（`pnpm-workspace.yaml`），**禁止**子 `package.json` 硬编码版本 | +| **HTTP 请求** | `@vben/request`，**禁用** 原生 `fetch` / `axios` | +| **状态管理** | Pinia | +| **动态表单** | `@form-create/ant-design-vue`（已集成） | +| **DAG 画布** | `@vue-flow/core`（F1 引入） | +| **i18n** | 所有文案走 `t('iot.xxx')`，**禁止**硬编码中文；zh-CN / en-US 同步 | +| **模板变量** | `${data.x}` / `${meta.x}` / `${alarm.x}` / `${trigger.x}`（与后端对齐），**禁用** `$[...]` | +| **文件命名** | 组件 PascalCase（`DagCanvas.vue`），Composable `useXxx.ts` | + +### 告警正交状态展示（评审 C1） + +告警列表必须展示 **5 种组合**： + +| 组合 | 颜色 | +|------|------| +| 活跃·未确认（ack=0, clear=0, archived=0） | 红 | +| 活跃·已确认 | 橙 | +| 已清除·未确认（关键运维场景） | **黄**（醒目） | +| 已清除·已确认 | 绿 | +| 已归档 | 灰 | + +**禁止**退化为 3 态线性展示。 + +--- + +## 六、测试与构建命令 + +```bash +# 类型检查 +pnpm check:type + +# Lint +pnpm lint + +# 单元测试（Vitest） +pnpm test:unit + +# E2E（Playwright） +pnpm test:e2e + +# 开发服务器（端口 5666） +pnpm dev:antd + +# 生产构建 +pnpm build:antd +``` + +--- + +## 七、环境要求 + +- Node.js 20.19.0+ +- pnpm 10.0.0+ + +**首次进入 worktree 必做**： +```bash +pnpm install +``` + +node_modules 不跨 worktree 共享。 + +--- + +## 八、后端 API 前置依赖 + +前端 F 任务多数依赖后端 API： + +| 前端任务 | 依赖后端 API（来自 Bxx） | +|---------|---------------------| +| F3 属性面板 | B4/B5/B6 Provider metadata API | +| F4 触发器表单 | B4 TriggerProvider metadata | +| F5 条件表单 | B5 ConditionEvaluator metadata | +| F6 动作表单 | B6 ActionProvider metadata | +| F7 规则链列表 | B2 /iot/rule-chain/* API | +| F9 子系统管理 | B10/B11 | +| F10 告警列表 | B12 /iot/alarm-record/* | +| F11 设备筛选 | B10/B11 | + +若后端相关 B 任务未 completed： +- F1/F2/F8 可独立开发 +- F3-F7/F9-F11 可先做 UI 骨架 + mock 数据，等后端就绪联调 + +--- + +## 九、需要人工决策的场景 + +Agent 遇以下情况不得自动判断，需停下通知： + +- `pnpm check:type` / `lint` / `test:unit` 连续 3 次失败 +- Acceptance 有主观项（如 "UI 美观度"） +- Known Pitfalls 的设计取舍 +- 上游后端 API schema 与任务卡预期不符 +- 视觉决策（颜色 / 布局细节未在任务卡规定） + +--- + +## 十、相关文档索引 + +| 文档 | 用途 | +|------|------| +| `CLAUDE.md`（同目录） | Claude Code 专有机制 | +| `14-任务执行卡/README.md` | 目录构成 | +| `14-任务执行卡/01-Claude-Code执行设置指南.md` | 完整执行设置 | +| `13-评审记录/11-未决议题的用户决策记录.md` | 决策 5 双入口 | +| `C:\workspace\java17\aiot-platform-cloud-iot\AGENTS.md` | 后端对照 | + +--- + +## 十一、变更日志 + +- 2026-04-23 初建