Files

lzh 5d42c2bfe6 feat(iot-v2): 新增 AGENTS.md 跨 agent 通用规范（方案 C）

- 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) <noreply@anthropic.com>

2026-04-23 17:49:22 +08:00

6.2 KiB

Raw Blame History

AGENTS.md — IoT v2.0 升级（前端）

本文档给所有 AI Agent（Claude Code / Cursor / Windsurf / Codex CLI / Aider 等）看遵循 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

四、任务执行标准流程

Read 任务卡：14-任务执行卡/Fxx-*.md（绝对路径）
Read source_doc + CLAUDE.md（本目录）
Read depends_on 上游任务产出（含后端 VO 类型）
按 Known Pitfalls 规避
实现 + Vitest 单元测试

运行质检三连：

pnpm check:type
pnpm lint
pnpm test:unit

逐项 check Acceptance；未全通过不 commit

commit 规范（中文）：

[Fxx] 任务标题

- 主要文件 1
- 主要文件 2
- Known Pitfalls 落地：⚠️ 评审 Xx

Co-Authored-By: <AI 模型标识>

更新任务卡 frontmatter：status: completed + updated: <YYYY-MM-DD>
查 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 态线性展示。

六、测试与构建命令

# 类型检查
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 必做：

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 初建

6.2 KiB Raw Blame History Unescape Escape