lzh
a72c96692e
- AGENTS.md 作为 agents.md 标准通用规范（所有 AI agent 可读） - .gitignore 放开 AGENTS.md（删除 AGENTS.md 忽略规则） - CLAUDE.md 保持 gitignored（Claude Code 本地配置） 用于 IoT v2.0 第一期任务的跨 agent 规范： - 项目背景 / 任务卡系统 / 硬约束 / 技术约定 / 测试命令 → AGENTS.md - /loop / subagent 并行 / checkpoint / PushNotification → CLAUDE.md Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
180 lines
6.7 KiB
Markdown
180 lines
6.7 KiB
Markdown
# 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`
|
||
|
||
> **注意**：本 worktree **不走 OpenSpec 流程**（主仓 master 的 AGENTS.md 指向 OpenSpec，与本升级无关）。
|
||
> 本升级的权威 spec = `14-任务执行卡/` 下的任务卡。
|
||
|
||
---
|
||
|
||
## 一、项目背景
|
||
|
||
AIoT 平台 IoT 模块（`viewsh-module-iot`）v2.0 升级实施：
|
||
|
||
- **技术栈**：Spring Boot 3.5.9 + Spring Cloud 2025 + MyBatis Plus 3.5.15 + JDK 17+
|
||
- **目标**：规则引擎从硬编码演进为 DAG + 子系统模型 + 告警状态机 + 设备影子
|
||
- **范围**：89 个任务分 3 期，当前第一期 B1-B19（19 个后端任务）
|
||
- **前端配对**：`C:\workspace\vue\aiot-platform-ui-iot`（分支 `feat/iot-2.0`，承接 F1-F11）
|
||
|
||
---
|
||
|
||
## 二、任务卡系统（权威 spec）
|
||
|
||
所有任务的需求 / 验收 / 约束均在任务卡：
|
||
|
||
| 资源 | 绝对路径 |
|
||
|------|---------|
|
||
| 任务卡目录 | `C:\document\AIOT\开发者文档\03-IoT领域\升级设计方案\14-任务执行卡\` |
|
||
| 编写指南 | `14-任务执行卡\00-任务卡编写指南.md` |
|
||
| 目录说明 + Wave 依赖 | `14-任务执行卡\README.md` |
|
||
| 评审档案（决策背景） | `13-评审记录\01-10` + `11-决策记录` + `12-ACP调研` |
|
||
| 原始设计方案 | `C:\document\AIOT\开发者文档\03-IoT领域\升级设计方案\00-12.md` |
|
||
|
||
**本 worktree 任务范围**：仅 **B 开头后端任务**，第一期 B1-B19。
|
||
第二期 B20+、B29（RPC Outbox 样板）、第三期 B44（脚本沙箱样板）**本期禁止做**。
|
||
|
||
---
|
||
|
||
## 三、硬约束（所有 Agent 共守）
|
||
|
||
### 3.1 Git 边界
|
||
|
||
- **分支**：必须在 `feat/iot-2.0` 分支提交
|
||
- 每次任务开始前 `git branch --show-current` 核对
|
||
- **禁止**：`git push`（任何远程推送）、`git push --force`、`git commit --no-verify`、`git commit --amend` 已推送的 commit
|
||
- **禁止**：`git checkout` 切换到其他分支
|
||
- **禁止**：在 `master` / `main` / 其他分支 commit
|
||
|
||
### 3.2 任务范围
|
||
|
||
- 第一期仅 B1-B19
|
||
- **禁止做** B20+、B29、B44（非第一期）
|
||
- 任务卡 `Files §2.3 不可修改` 里的文件**绝不触碰**
|
||
|
||
### 3.3 代码边界
|
||
|
||
- **禁止**修改 `viewsh-module-iot-server/**/rule/**` 旧规则代码（v1 保留到观察期后由 B67 清理）
|
||
- **禁止**让 `viewsh-module-iot-rule` 模块依赖 `viewsh-module-iot-server` 或 `viewsh-module-iot-gateway`
|
||
- 依赖方向：`rule → core → api`（单向）
|
||
|
||
### 3.4 质量门槛
|
||
|
||
- Acceptance Criteria 任一项未通过 → **不允许 commit**
|
||
- 测试必须全部通过（`mvn test`）
|
||
- 不跳过 pre-commit hook
|
||
|
||
---
|
||
|
||
## 四、任务执行标准流程
|
||
|
||
每个任务逐项遵循：
|
||
|
||
1. **Read 任务卡**：`14-任务执行卡/Bxx-*.md`（绝对路径）
|
||
2. **Read source_doc**：任务卡列出的原方案章节
|
||
3. **Read depends_on**：上游任务**实际代码产出**（不只看任务卡文字）
|
||
4. **按 Known Pitfalls 规避**已知问题
|
||
5. **TDD**：先写测试骨架，再写实现
|
||
6. **运行测试**：`mvn test -pl <相关模块>`
|
||
7. **逐项 check Acceptance Criteria**；任一未通过不 commit
|
||
8. **commit 规范**：
|
||
```
|
||
[Bxx] 任务标题
|
||
|
||
- 主要文件 1
|
||
- 主要文件 2
|
||
- Known Pitfalls 落地：⚠️ 评审 Xx
|
||
|
||
Co-Authored-By: <AI 模型标识>
|
||
```
|
||
9. **更新任务卡** frontmatter：`status: completed` + `updated: <YYYY-MM-DD>`
|
||
10. 查 `README.md §3.3` 确认下游 Wave
|
||
|
||
---
|
||
|
||
## 五、关键技术约定（源自第 8 轮评审规范清单）
|
||
|
||
| 约定 | 规则 |
|
||
|------|------|
|
||
| SPI Provider 注册 | Spring `@Component` + `getType()` 索引；**禁用** `ServiceLoader` / `@SPI` |
|
||
| 模板变量格式 | `${data.x}` / `${meta.x}` / `${alarm.x}` / `${trigger.x}`；**禁用** `$[...]` 旧语法 |
|
||
| 分布式锁 | Redis `SET NX PX` + Lua 原子解锁；**禁用** `SETNX` 老语法 |
|
||
| RPC 状态更新 | **Outbox Pattern**（见 B29 样板）；禁止同事务内 send + update DB |
|
||
| 告警状态模型 | `ack_state` + `clear_state` + `archived` 三字段正交；**禁用**线性 4 枚举 |
|
||
| 规则链匹配 | 三层 key 查询后 **LinkedHashMap 去重** |
|
||
| Aviator 脚本 | **8 层沙箱防护**（见 B44 样板） |
|
||
| Agent 调用协议 | **A2A**（JSON-RPC 2.0 over HTTPS）；**禁用** "ACP" 命名（已合并到 A2A，见 12 号调研） |
|
||
| 枚举 DB 存储 | `TINYINT` + Java Enum 映射；**禁用** VARCHAR 枚举字符串 |
|
||
| JSON 字段查询 | 关键维度建关联表；**禁用** `JSON_CONTAINS` 高频查询 |
|
||
| 主键 | `BIGINT AUTO_INCREMENT`（与其他 module 一致） |
|
||
| 多租户 | 所有 DAO 带 `tenant_id` 过滤（沿用项目风格） |
|
||
|
||
---
|
||
|
||
## 六、测试与构建命令
|
||
|
||
```bash
|
||
# 单模块测试
|
||
mvn test -pl viewsh-module-iot/viewsh-module-iot-rule
|
||
|
||
# 整仓构建（验证依赖）
|
||
mvn clean install -DskipTests -pl viewsh-module-iot/viewsh-module-iot-rule -am
|
||
|
||
# 依赖树（验证 rule 模块不依赖 gateway/server）
|
||
mvn dependency:tree -pl viewsh-module-iot/viewsh-module-iot-rule
|
||
|
||
# 启动开发服务
|
||
cd viewsh-module-iot/viewsh-module-iot-server
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
---
|
||
|
||
## 七、环境要求
|
||
|
||
- JDK 17+
|
||
- Maven 3.6+
|
||
- MySQL 5.7+ / 8.0+
|
||
- Redis 5.0+
|
||
- Nacos 2.0+（服务注册 / 配置中心）
|
||
|
||
任务卡 `启动前自检` 会要求 Agent 核对以上环境。
|
||
|
||
---
|
||
|
||
## 八、需要人工决策的场景
|
||
|
||
Agent 遇到以下情况**不得自动判断**，需停下通知人类：
|
||
|
||
- 测试连续失败 3 次
|
||
- Acceptance Criteria 有无法自动验证的项（如"文档可读性"）
|
||
- 任务卡 Known Pitfalls 中的取舍点
|
||
- 依赖任务实际产出与任务卡预期不符
|
||
- 单任务执行超过 2 小时
|
||
- 上游任务 status 未 verified
|
||
|
||
具体通知机制由各 Agent 工具决定（Claude Code 用 PushNotification，其他工具按各自机制）。
|
||
|
||
---
|
||
|
||
## 九、相关文档索引
|
||
|
||
| 文档 | 用途 |
|
||
|------|------|
|
||
| `CLAUDE.md`（同目录） | Claude Code 专有机制（/loop、subagent、checkpoint） |
|
||
| `14-任务执行卡/README.md` | 目录构成 + Wave 依赖图 |
|
||
| `14-任务执行卡/00-任务卡编写指南.md` | 任务卡字段规范 |
|
||
| `14-任务执行卡/01-Claude-Code执行设置指南.md` | 完整执行设置（含 worktree / 权限 / 并行） |
|
||
| `13-评审记录/08-轮次8-...md` | 系统边界 + 规范清单 + 55 patch |
|
||
| `13-评审记录/11-未决议题的用户决策记录.md` | 6 项用户决策（含双入口）|
|
||
| `13-评审记录/12-ACP协议与Agent调用方案调研.md` | A2A 选型依据 |
|
||
| `C:\workspace\vue\aiot-platform-ui-iot\AGENTS.md` | 前端对照 |
|
||
|
||
---
|
||
|
||
## 十、变更日志
|
||
|
||
- 2026-04-23 初建；IoT v2.0 第一期专用
|