XW-AIOT/aiot-platform-cloud
4
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
7dc00b542d5d8c637abd83a82e5bf4803d9fbb08
aiot-platform-cloud/AGENTS.md
lzh a72c96692e feat(iot-v2): 拆分 AGENTS.md / CLAUDE.md（方案 C） 
- 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>
2026-04-23 17:48:40 +08:00

6.7 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

注意：本 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 过滤（沿用项目风格）

六、测试与构建命令

# 单模块测试
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 第一期专用