# AI 角色定义与权限约定

> **如果你是 AI，请直接跳转到你的角色入口：**
> - Arch AI → `dashboard.md` 全文
> - Worker AI → `.ai/roles/worker/card.md` → 对应 `.ai/tasks/active/` 任务文件
>
> **如果你是人类**，请看 `dashboard.md` 顶部「人类区」。
>
> 本文档是权限矩阵的**唯一权威参考**。角色工作台中的权限描述为摘要，如有冲突以本文档为准。

---

## 团队架构

`1 人类 + 2 AI` 协作模式：
- **Arch AI** — 需求分析、架构设计、技术选型、任务分解、质量审查、勘误决策
- **Worker AI** — 代码编写、测试执行、文档生成、LL/HAL 驱动提炼
- **人类** — 需求输入、最终决策、硬件验证、成果验收

**核心理念**：测试驱动 SDK 演进。寄存器测试是 SDK 的第一用户，测试代码直接提炼为 LL 层驱动。

---

## 工作流

```
需求分析(Arch) → 架构设计(Arch) → 任务拆解(Arch)
    → 开发实现(Worker) → 自测(Worker) → 人类硬件验证
    → 勘误记录(Worker) → LL提炼(Worker) → HAL封装(Worker)
                                       ↑
                                   Bug修复(Worker, 最多3轮)
```

缺陷修复循环：最多 3 轮。第 3 轮仍有 BLOCKER → 升级给人类 + Arch AI 裁决。

---

## 角色职责

### Arch AI
- 可写：架构文档、验收标准、任务定义、知识库、共享资源、开发工具、SDK 设计文档
- 只读：测试代码、测试报告、勘误详情
- 指导 Worker AI 工作，分配任务队列，审查产出质量

### Worker AI
- 可写：业务代码、测试代码、测试报告、技术文档、开发工具、勘误记录、LL/HAL 驱动代码
- 只读：AI 配置、任务定义（不可修改 task 内容）
- 禁止：.ai/ 目录结构修改、dashboard.md 修改

### 人类
- 全部权限，但主要行使：需求定义、架构决策、硬件验证、成果验收

---

## 目录权限矩阵

> 图例：`-` = 禁止  `R` = 只读  `W` = 可写（含读）  `RW` = 读写

| 目录路径 | Arch AI | Worker AI | 人类 |
|---------|---------|-----------|------|
| `.ai/` | `R` | `-` | `RW` |
| `dashboard.md` | `RW` | `R` | `RW` |
| `DECISIONS.md` | `RW` | `R` | `RW` |
| `Drivers/CMSIS/` | `RW` | `RW` | `RW` |
| `Drivers/HWD32H757_HAL_Driver/` | `R` | `RW` | `RW` |
| `Drivers/BSP/` | `R` | `RW` | `RW` |
| `Test/` | `R` | `RW` | `RW` |
| `Test/errata/` | `RW` | `RW` | `RW` |
| `Tools/` | `RW` | `RW` | `RW` |
| `docs/` | `RW` | `RW` | `R` |
| `Projects/` | `R` | `RW` | `RW` |

优先级：`forbidden > read_only > allowed`。未出现在表中的路径默认禁止所有 AI。

---

## 命名规范

### 任务编号
- 开发任务：`D{阶段号}-{序号}`，如 `D0-001`（P0阶段第1个任务）
- 测试任务：`T{阶段号}-{序号}`，如 `T0-001`

### 分支命名
```
feature/D0-001-short-desc
bugfix/D0-001-short-desc
test/T0-001-short-desc
```

### 提交信息
```
feat(D0-001): 简短描述
fix(D0-001): 简短描述
docs(D0-001): 简短描述
test(D0-001): 简短描述
errata: GPIOx_BSRR 写入偶发失效 (D0-003)
```

---

## AI 配置文件索引

| 文件 | 说明 |
|------|------|
| `.ai/principles.md` | 设计原则 + 上下文管理规则 |
| `.ai/roles/{arch,worker}/card.md` | AI 角色身份卡 |
| `.ai/phases/INDEX.md` | 阶段索引 + 切换规则 |
| `.ai/knowledge/decisions.md` | 架构决策记录 (ADR) |
| `.ai/knowledge/lessons.md` | 经验教训 |
| `.ai/knowledge/patterns.md` | 可复用模式 |
| `.ai/tasks/templates/` | Task 模板 |