ai_soc_sw/README.md

# ErrLens MCU芯片自动化测试项目

## 项目目标

基于芯片手册和 Excel 寄存器表格，通过运行软件的方式配合 JTAG 调试工具和串口工具，自动验证芯片实际功能是否与文档描述一致。

---

## 核心特性

- ✅ Excel 寄存器表格解析 → 自动生成寄存器定义头文件
- ✅ 自动生成测试代码 → 寄存器读写测试、功能验证
- ✅ JTAG 自动化下载 + 运行
- ✅ 串口日志监控 + 自动分析
- ✅ 测试结果自动验证 + 报告生成
- ✅ "人+Arch AI+执行AI" 协作模式

---

## 目录结构

```
.
├── AGENTS.md                      # AI角色定义+权限约定+工作流
├── README.md
├── .gitignore
├── .ai/                           # AI协作核心配置
│   ├── config/
│   │   ├── architect.json         # Arch AI 配置
│   │   ├── executor.json          # 执行AI 配置
│   │   └── workflow.json          # 工作流配置
│   └── prompts/
│       ├── architecture/          # 架构设计提示词模板
│       └── execution/             # 执行提示词模板
├── docs/                          # 全局文档 (Arch AI 编写，执行AI 只读)
│   ├── 00_芯片资料/               # 芯片资料（Excel寄存器表、手册）
│   │   ├── registers/             # Excel寄存器表格
│   │   └── datasheet/             # 芯片手册
│   ├── 01_测试需求/               # 芯片功能需求分析
│   ├── 02_测试架构/               # 测试架构设计和编译器方案
│   ├── 03_开发规范/               # 开发规范和最佳实践
│   └── 04_变更日志/               # 变更记录
├── tools/                         # 测试工具 (Arch AI 和执行AI 可写)
│   ├── jtag/                      # JTAG调试工具脚本
│   └── uart/                      # 串口监控工具脚本
├── projects/                      # 芯片测试项目
│   ├── P01_chip_test/             # 主芯片测试项目
│   │   ├── demo/                  # 串口printf Demo工程（起点）
│   │   ├── src/                   # 测试固件代码 (执行AI 可写)
│   │   ├── tests/                 # 测试用例 (执行AI 可写)
│   │   ├── docs/                  # 项目文档 (执行AI 可写)
│   │   └── ENVIRONMENT.md         # 项目级环境准备
│   └── P02_ext_test/              # 扩展测试项目
│       ├── src/
│       ├── tests/
│       ├── docs/
│       └── ENVIRONMENT.md
├── review/                        # 交接中心
│   ├── active/                    # 活跃任务
│   │   ├── P01-001/               # 项目1-任务1
│   │   │   ├── task.md            # 任务描述
│   │   │   ├── acceptance.md      # 验收标准
│   │   │   ├── impact.md          # 变更影响范围
│   │   │   └── feedback/          # 反馈记录
│   │   │       └── round1.md
│   │   └── ...
│   └── archived/                  # 已完成任务（按季度归档）
│       └── 2026-Q2/
├── shared/                        # 共享资源 (Arch AI 可写，执行AI 只读)
│   ├── scripts/                   # 共享脚本
│   │   └── parse_registers.py     # Excel寄存器表格解析工具
│   ├── templates/                 # 固件代码模板
│   └── utils/                     # 工具函数
├── reports/                       # 统一报告 (执行AI 可写)
│   ├── test-results/              # 测试结果报告
│   └── quality-reports/           # 质量分析报告
└── .github/                       # CI/CD配置
    └── workflows/
```

---

## 团队角色

| 角色 | 是谁 | 干什么 | 不干什么 |
|------|------|--------|----------|
| **人类负责人** | 你 | 下指令、审阅、做决策、定验收标准 | 不写代码、不执行测试 |
| **Arch AI** | Claude/TRAE/元宝等 | 需求分析、测试架构设计、编译器选择、JTAG调试流程设计 | 不直接执行硬件测试 |
| **执行AI** | Claude/TRAE/扣子等 | 写测试固件、编译下载、JTAG调试、串口监控、写测试报告 | 不修改测试架构、不动 shared/ |

---

## 工作流程

### 0. 准备输入资源（前置步骤）
- 将 **Excel 寄存器表格** 放入 `docs/00_芯片资料/registers/`
- 将 **串口 printf Demo 工程** 放入 `projects/P01_chip_test/demo/`

### 1-4. 正式工作流程
1. **Arch AI** 解析 Excel 寄存器表格，分析芯片功能需求，制定测试规划，输出 `docs/01_测试需求/` 和 `review/active/P01-001/task.md`
2. **Arch AI** 设计测试架构，选择编译器，规划JTAG/串口调试流程，输出 `docs/02_测试架构/`、`acceptance.md`、`impact.md`
3. **执行AI** 读取任务描述和验收标准，基于 Demo 工程扩展测试功能，配置环境，通过JTAG下载执行，收集串口日志，写 `feedback/round1.md`
4. **你**审一眼测试报告，确认任务完成或要求修复
5. **有问题** → 执行AI 修复 → 回到步骤3（round2）
6. **通过** → 你确认 → 任务关闭，报告归档到 `reports/`

---

## 编译器支持

| 编译器 | 版本要求 | 适用场景 |
|--------|---------|---------|
| Arm Clang | >= 18.0.0 | 高性能开发 |
| Keil MDK (AC6) | >= 6.18 | 工业级应用 |
| Arm GCC | >= 12.0.0 | 开源生态 |

## 调试方式

- **JTAG/SWD**: 下载固件、单步调试
- **串口**: 监控日志输出、查看测试结果

---

## 任务状态流转

```
TODO → IN_PROGRESS → REVIEW → DONE → ARCHIVED（移入archived/季度目录）
```

`task.md` 中添加状态字段：
```
status: TODO | IN_PROGRESS | REVIEW | DONE | ARCHIVED
```

---

## 参考文档

| 文件 | 说明 |
|------|------|
| [AGENTS.md](AGENTS.md) | AI角色定义与权限约定 |
| [docs/02_测试架构/automated_test_architecture.md](docs/02_测试架构/automated_test_architecture.md) | 自动化测试架构详细设计 |
| [workflow.json](.ai/config/workflow.json) | 工作流配置 |
| [P01-001 任务](review/active/P01-001/task.md) | 示例任务单 |

---

## 快速开始：自动化测试

### 0. 准备输入资源

```bash
# 1. 将 Excel 寄存器表格放入
#    docs/00_芯片资料/registers/

# 2. 将 Demo 工程放入
#    projects/P01_chip_test/demo/
```

### 1. 解析寄存器表格，生成测试代码

```bash
cd /home/ydp/work/errlens
python3 shared/scripts/parse_registers.py
```

输出：
- `projects/P01_chip_test/inc/registers.h` - 寄存器定义
- `projects/P01_chip_test/src/registers_test.c` - 自动生成的测试代码
- `projects/P01_chip_test/tests/registers_spec.json` - 测试描述

### 2. 编译测试固件

```bash
# 使用 Arm GCC
cd projects/P01_chip_test
make
```

### 3. JTAG 下载并运行

```bash
cd /home/ydp/work/errlens
# 脚本待完善: ./tools/jtag/flash.sh
# 或使用 pyocd:
pyocd flash projects/P01_chip_test/build/firmware.hex
```

### 4. 监控串口并捕获日志

```bash
# 脚本待完善: ./tools/uart/monitor.sh -o test_log.txt
# 或使用 minicom 记录日志
minicom -D /dev/ttyUSB0 -b 115200 -C test_log.txt
```

### 5. 分析日志，生成报告

```bash
python3 shared/scripts/analyze_log.py test_log.txt -o test_report.txt
```

查看报告：`cat test_report.txt`

---

## 快速开始

```bash
# 克隆仓库
git clone <repository-url>
cd errlens

# 阅读协作规则
cat AGENTS.md

# 查看当前任务
ls -la review/active/
```

---

## 版本历史

| 版本 | 日期 | 说明 |
|------|------|------|
| v2.0 | 2026-05-22 | 重构为MCU芯片测试架构，三角色：人+Arch AI+执行AI |
| v1.0 | 2026-05-22 | 初始版本，完成目录结构设计 |