diff --git a/.gitignore b/.gitignore
index b132b37f..c36ceaf1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -76,7 +76,7 @@ sessionStore
 .claude/
 .claude/
 openspec/
-AGENTS.md
+# AGENTS.md 允许追踪（跨 agent 通用规范，方案 C）
 CLAUDE.md
 docs/
 .qoder/repowiki/
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..110fb74f
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,179 @@
+# 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 第一期专用