hwd32/ai_soc_sw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

merge into: hwd32/ai_soc_sw:main
Branches Tags
hwd32/ai_soc_sw:main hwd32/ai_soc_sw:ic_eda
..
pull from: hwd32/ai_soc_sw:ic_eda
Branches Tags
hwd32/ai_soc_sw:ic_eda hwd32/ai_soc_sw:main

3 Commits
main .. ic_eda

Author SHA1 Message Date
tupingr 3f09d0f6e4 docs: 添加MCU芯片软件输入物料行业分析报告到知识库 2026-05-27 17:07:29 +08:00
tupingr 3d43cd87d5 feat: 项目架构重构 - hwd32h757芯片成片测试及SDK开发 
- 从errlens模板(3角色)重构为1人+Arch AI+Worker AI(2角色)
- 去掉review仓库/QA AI/Dev AI分离，Worker AI统一负责开发+测试
- 新增33个功能单元目录(Test/cases/)，按P0-P6七阶段bring-up
- 新增SDK驱动层骨架(Drivers/CMSIS/HAL_Driver/BSP)
- Arch AI/Worker AI角色不绑定特定AI平台，任何AI可随时接手
- 5个ADR：测试驱动SDK演进、HAL/LL双层、分阶段bring-up、单仓库、角色可替换
- 参考errlens的分层信息架构：dashboard→card→task，token预算控制
 2026-05-27 16:37:52 +08:00
tupingr 6c09a9b6d4 init. 2026-05-26 16:43:31 +08:00
315 changed files with 944 additions and 23326 deletions
Expand all files Collapse all files
.ai/archive/DASHBOARD.md
-59
View File
@@ -1,59 +0,0 @@
# ErrLens 项目仪表盘
> 人类视角 · 30 秒了解项目全貌 · 无需懂代码
---
## 当前状态
**Phase 2/4 — MVP 开发** · 进度 0%
Phase 1 基础搭建已收尾（100%）。PRD/架构/数据模型全部锁定，Dev AI 开始编码。
---
## 四个阶段
| 阶段 | 进度 | 状态 | 一句话说明 |
|------|------|------|------------|
| 1. 基础搭建 | 100% | ✅ | 搭骨架：PRD 锁定、架构文档完成、旧架构合并 |
| 2. MVP | 0% | ← 当前 | 做核心：错题录入、AI 分析、PDF 打印、图像预处理 |
| 3. 功能完善 | 0% | 未开始 | 加功能：推荐、多端、训练迭代 |
| 4. 打磨发布 | 0% | 未开始 | 提质量：性能、安全、文档 |
---
## 现在在做什么
- **Dev AI 启动编码** — 数据库 Schema → Auth → Image → Print → User → Upload → 页面骨架
- **Arch AI 补尾** — ADR-010（题库抽象层）、UI 规范迁移
- **Phase 2 目标** — 拍照录入 + AI 分析 + PDF 输出 + 用户系统完整闭环
---
## 需要你关注的事
- [ ] 无。30 项决策已全部确认，Phase 2 由 AI 执行开发。
---
## 快速入口
| 你想看什么 | 去哪里 |
|------------|--------|
| **产品需求文档** | **[docs/01_产品需求/PRD.md](docs/01_产品需求/PRD.md)** |
| **系统架构设计** | **[docs/02_系统架构/](docs/02_系统架构/)** |
| **怎么使用这套体系** | **[docs/使用手册.md](docs/使用手册.md)** |
| 详细任务看板 | [ROADMAP.md](ROADMAP.md) |
| 项目为什么要这样做 | [docs/share/](docs/share/) |
| 架构决策记录 | [.ai/knowledge/decisions.md](.ai/knowledge/decisions.md) |
| 怎么搭建的开发环境 | [ENVIRONMENT.md](ENVIRONMENT.md) |
| AI 角色怎么分工 | [AGENTS.md](AGENTS.md) |
---
## 可分享内容
→ [docs/share/](docs/share/) — 项目开发全记录，可对外发布
*仪表盘每次阶段切换时更新，不随每日任务变化。*
.ai/archive/ROADMAP.md
-83
View File
@@ -1,83 +0,0 @@
# ErrLens 项目路线图
> 人类 + AI 共享视野。状态由 Arch AI 维护。
---
## 阶段总览
```
Phase 1 [==========] 基础搭建 ✅ 已完成 (100%)
Phase 2 [----------] MVP ← 当前 (0%)
Phase 3 [----------] 功能完善 (0%)
Phase 4 [----------] 打磨发布 (0%)
```
| 阶段 | 名称 | 状态 | 进度 | 预计重点 |
|------|------|------|------|----------|
| 1 | 基础搭建 | DONE | 100% | 框架、脚手架、PRD、架构设计、旧架构合并 |
| 2 | MVP | ACTIVE | 0% | 错题录入、AI 分析、PDF 打印、图像预处理 |
| 3 | 功能完善 | PLANNED | 0% | 个性化推荐、多端、训练迭代 |
| 4 | 打磨发布 | PLANNED | 0% | 性能优化、安全审计、文档完善 |
---
## Phase 1 回顾（已完成）
| 交付物 | 版本 | 完成日期 |
|------|------|----------|
| 信息架构重构 | — | 2026-05-25 |
| 错题本 PRD | v0.4.0 | 2026-05-26 |
| 系统架构（总体+技术+模块+数据模型） | v0.4.0 | 2026-05-26 |
| P01 文档改写（代码检测→错题本） | — | 2026-05-26 |
| 5 项决策确认（题库/AI/用户/商业化/学科） | — | 2026-05-26 |
| ADR-009 数据质量闭环 | — | 2026-05-26 |
| 旧架构合并 30 项决策 | — | 2026-05-26 |
---
## 当前阶段 (Phase 2) 任务看板
### TODO（待领）
| 任务 | 项目 | 描述 | 优先级 | 负责人 |
|------|------|------|--------|--------|
| P01-001 | App | 数据库 Schema 实现 + 迁移脚本 | P0 | Dev AI |
| P01-002 | App | Auth 模块（微信登录 + JWT） | P0 | Dev AI |
| P01-005 | App | Image 模块（图像预处理管线） | P0 | Dev AI |
| P01-006 | App | Print 模块（PDF 生成 + S3 + 过期清理） | P0 | Dev AI |
| P01-004 | App | Upload 模块（图片上传 + S3） | P1 | Dev AI |
| P01-003 | App | User 模块（个人信息 CRUD + 邀请链） | P1 | Dev AI |
| P01-007 | App | 页面路由 + 基础页面骨架（含打印页） | P1 | Dev AI |
| CROSS-001 | 共享 | 共享工具库日期格式 bug 修复 | P0 | Dev AI |
### DOING
| 任务 | 项目 | 描述 | 负责人 | 预计完成 |
|------|------|------|--------|----------|
| — | — | （无） | — | — |
### DONE
| 任务 | 项目 | 描述 | 完成日期 |
|------|------|------|----------|
| — | — | （Phase 2 暂无完成项） | — |
---
## 阻塞项
| 级别 | 描述 | 影响范围 | 分配给 | 创建日期 |
|------|------|----------|--------|----------|
| YELLOW | CROSS-001 日期格式 bug | CROSS-001 无法关闭 | Dev AI | 2026-05-23 |
---
## 最近更新
| 日期 | 事件 |
|------|------|
| 2026-05-26 | Phase 1 收尾（100%），Phase 2 启动，Dev AI 工作台初始化 |
| 2026-05-26 | 旧架构合并完成：30 项决策落地，5 份架构文档升级至 v0.4.0 |
| 2026-05-25 | 信息架构重构完成 + 项目模板化（ai_project 分支） |
| 2026-05-23 | 框架搭建完成：目录结构、权限体系、7 个 Skill |
.ai/archive/arch-queue.md
-21
View File
@@ -1,21 +0,0 @@
# Arch AI · 任务队列
## 当前阶段 (Phase 1) 任务
| # | 任务 | 优先级 | 状态 | 依赖 |
|---|------|--------|------|------|
| 1 | 信息架构重构 | P0 | DONE | — |
| 2 | 错题本 PRD 编写 | P0 | DONE | 1 |
| 3 | 系统架构设计 | P0 | DONE | 2 |
| 4 | P01 文档改写 | P1 | DONE | 2 |
| 5 | PRD 修订（根据人类反馈） | P0 | TODO | 人类审阅 |
| 6 | 将 Dev 任务写入 Dev 工作台 | P1 | TODO | 3 |
| 7 | 补充 ADR-009 技术选型决策 | P1 | TODO | 3 |
| 8 | 架构提示词模板 | P2 | TODO | — |
## 未来阶段预留
| # | 任务 | 阶段 | 优先级 |
|---|------|------|--------|
| — | Phase 2 MVP 架构设计 | 2 | — |
| — | Phase 3 功能迭代架构 | 3 | — |
.ai/archive/arch-today.md
-45
View File
@@ -1,45 +0,0 @@
# Arch AI · 今日任务 · 2026-05-26
## 已完成
- [x] **[P0]** 编写 `docs/01_产品需求/PRD.md` v0.3.0 — 错题本产品需求文档（已锁定）
- [x] **[P0]** 设计 `docs/02_系统架构/` — 总体架构、技术选型、模块设计、数据模型（v0.3.0）
- [x] **[P1]** 将 P01 项目文档从"代码检测"改写为"错题本"
- [x] **[P1]** 更新 ROADMAP.md 任务看板（PRD 完成后分配 Dev 任务）
- [x] **[P0]** 数据质量架构闭环：人机协同修正（ADR-009）
- [x] **[P0]** 决策落地：双题库源、用户树状邀请、数学+英语双学科、Freemium
- [x] **[P0]** 旧架构合并：30 项决策逐项确认，5 份架构文档更新至 v0.4.0
- [x] **[P0]** Phase 1 收尾：ROADMAP/DASHBOARD 更新，Dev 工作台初始化，ADR-010 补充
- [x] **[P0]** Phase 2 启动：8 个 Dev 任务入队，依赖关系图完成
## Phase 1 收尾清单
| 动作 | 状态 |
|------|------|
| ROADMAP Phase 1 → DONE 100% | ✅ |
| ROADMAP Phase 2 → ACTIVE | ✅ |
| DASHBOARD 阶段切换 | ✅ |
| Dev AI queue.md 重写 | ✅ |
| Dev AI today.md 初始化 | ✅ |
| ADR-010 题库抽象层 | ✅ |
## 旧架构合并（30 项决策全部确认）
| # | 决策 | 结论 |
|---|------|------|
| 1 | 题库来源 | 自有 PDF 录入 + 作业帮 API 双源，架构层抽象适配 |
| 2 | AI 能力 | 分层使用：Coze 测试/验证，Claude 架构，其他 AI 做 Coding |
| 3 | 用户体系 | MVP 仅微信登录，邀请码分享形成树状结构 |
| 4 | 商业化 | 基础免费 + 会员，MVP 全免费 |
| 5 | 首发学科 | 数学 + 英语 |
## 明天 (2026-05-27)
1. UI 设计规范迁移（从旧架构迁移到新架构 `docs/02_系统架构/UI设计规范.md`）
2. 测试方案迁移（从旧架构迁移，调整为 Coze 沙盒自动化测试方案）
3. 部署方案重写（三环境 dev/test/prod + Coze 沙盒配置）
4. 根据人类反馈做修订
## 阻塞
（无）
.ai/archive/dev-queue.md
-36
View File
@@ -1,36 +0,0 @@
# Dev AI · 任务队列
## Phase 2 MVP 任务
| # | 任务 ID | 项目 | 描述 | 优先级 | 状态 |
|---|---------|------|------|--------|------|
| 1 | P01-001 | App | 数据库 Schema 实现 + 迁移脚本 | P0 | TODO |
| 2 | P01-002 | App | Auth 模块（微信登录 + JWT） | P0 | TODO |
| 3 | CROSS-001 | 共享 | 共享工具库日期格式 bug 修复 | P0 | TODO |
| 4 | P01-005 | App | Image 模块（图像预处理管线） | P0 | TODO |
| 5 | P01-006 | App | Print 模块（PDF 生成 + S3 + 清理） | P0 | TODO |
| 6 | P01-004 | App | Upload 模块（图片上传 + S3 + 缩略图） | P1 | TODO |
| 7 | P01-003 | App | User 模块（个人资料 CRUD + 邀请链） | P1 | TODO |
| 8 | P01-007 | App | 页面路由 + 基础页面骨架 | P1 | TODO |
## 依赖关系
```
P01-001 (DB Schema)
├─→ P01-002 (Auth) ──→ P01-003 (User) ──→ P01-007 (Pages)
├─→ P01-004 (Upload) ──→ P01-005 (Image)
└─→ P01-006 (Print)
```
- P01-001 是所有模块的前置依赖，优先完成
- P01-002/004 可并行
- P01-005 依赖 P01-004（需要上传的图片 URL 做输入）
- P01-007 最后做，需要在各模块 API 稳定后
## 参考文档
- PRD: `docs/01_产品需求/PRD.md` (v0.4.0)
- 总体架构: `docs/02_系统架构/总体架构.md` (v0.4.0)
- 技术选型: `docs/02_系统架构/技术选型.md` (v0.4.0)
- 模块设计: `docs/02_系统架构/模块设计.md` (v0.4.0)
- 数据模型: `docs/02_系统架构/数据模型.md` (v0.4.0)
.ai/archive/dev-today.md
-29
View File
@@ -1,29 +0,0 @@
# Dev AI · 今日任务 · 2026-05-26
## 状态：Phase 2 MVP 启动
Phase 1（基础搭建）已收尾。PRD v0.4.0 / 系统架构 v0.4.0 / 数据模型 v0.4.0 全部锁定。
## 待领取（按优先级）
| # | 任务 | 优先级 | 说明 |
|---|------|--------|------|
| 1 | P01-001 | P0 | 数据库 Schema 实现 + Drizzle 迁移脚本。参考 [数据模型.md](../../../docs/02_系统架构/数据模型.md) 全部表定义 |
| 2 | P01-002 | P0 | Auth 模块（微信 code2session + JWT 签发 + AuthGuard）。参考 [模块设计.md](../../../docs/02_系统架构/模块设计.md#31-auth-模块) |
| 3 | CROSS-001 | P0 | 共享工具库日期格式 bug 修复 |
| 4 | P01-005 | P0 | Image 模块（Sharp 图像预处理管线：透视校正 + CLAHE 增强 + 笔迹去除）。参考 [模块设计.md](../../../docs/02_系统架构/模块设计.md#36-image-模块图像预处理) |
| 5 | P01-006 | P0 | Print 模块（PDFKit 生成 + S3 上传 + 24h 过期清理）。参考 [模块设计.md](../../../docs/02_系统架构/模块设计.md#37-print-模块pdf-输出p0) |
| 6 | P01-004 | P1 | Upload 模块（图片上传 S3 + 缩略图） |
| 7 | P01-003 | P1 | User 模块（个人信息 CRUD + 邀请码生成 + 邀请链查询） |
| 8 | P01-007 | P1 | 页面路由 + 9 个基础页面骨架（含打印预览页） |
## 关键架构文档
- [数据模型.md](../../../docs/02_系统架构/数据模型.md) — 所有表定义、索引、Drizzle Schema 示例
- [模块设计.md](../../../docs/02_系统架构/模块设计.md) — API 接口、模块结构
- [总体架构.md](../../../docs/02_系统架构/总体架构.md) — 数据流、部署架构
- [技术选型.md](../../../docs/02_系统架构/技术选型.md) — 技术栈版本
## 已完成
（Phase 2 暂无）
.ai/archive/qa-queue.md
-19
View File
@@ -1,19 +0,0 @@
# QA AI · 任务队列
## 当前阶段 (Phase 1)
暂无测试任务。所有活跃任务处于 TODO 状态。
## 测试流程
1. 确认任务已进入 REVIEW 状态（见 ROADMAP.md）
2. 读取 `review/active/{任务ID}/task.md` — 理解任务
3. 读取 `review/active/{任务ID}/acceptance.md` — 确认验收标准
4. 读取 `review/active/{任务ID}/impact.md` — 了解影响范围
5. 在 `projects/{项目}/tests/` 编写测试
6. 执行测试，生成报告到 `reports/`
7. 提交反馈到 `review/active/{任务ID}/feedback/`
## 已完成的测试
（无）
.ai/archive/qa-today.md
-18
View File
@@ -1,18 +0,0 @@
# QA AI · 今日任务 · 2026-05-25
## 进行中
（无）
## 待执行
当前没有进入 REVIEW 状态的任务，暂无测试任务。
## 已完成
（无）
## 说明
等待 Dev AI 完成代码开发后，任务状态转为 REVIEW 时开始测试工作。
关注 `ROADMAP.md` 中的 DOING 列，当有任务进入 REVIEW 时立即介入。
.ai/config/architect.json
-39
View File
@@ -1,39 +0,0 @@
{
"name": "Arch AI",
"role": "测试架构设计师",
"description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。",
"responsibilities": [
"芯片功能需求分析和测试规划",
"测试架构设计和测试方案制定",
"编译器选择和环境配置方案",
"JTAG调试流程设计",
"串口日志分析方案",
"编写测试架构文档",
"定义验收标准",
"评估测试结果影响",
"维护共享资源",
"维护测试工具",
"指导执行AI工作"
],
"allowed_paths": [
"docs/",
"shared/",
"projects/*/src/",
"projects/*/docs/",
"projects/*/tests/",
"review/*/acceptance.md",
"review/*/impact.md",
"review/*/task.md",
"tools/"
],
"read_only_paths": [
".ai/",
"reports/",
"review/*/feedback/"
],
"forbidden_paths": [],
"prompt_templates": {
"architecture": ".ai/prompts/architecture/",
"documentation": ".ai/prompts/architecture/"
}
}
.ai/config/coder.json
-37
View File
@@ -1,37 +0,0 @@
{
"name": "Dev AI",
"role": "代码开发者",
"description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。",
"responsibilities": [
"编写业务代码",
"生成技术文档",
"维护项目级文档",
"维护开发工具",
"维护训练数据",
"定义验收标准",
"评估变更影响",
"维护共享资源"
],
"allowed_paths": [
"projects/*/src/",
"projects/*/docs/",
"docs/",
"tools/",
"data/",
"shared/",
"review/*/acceptance.md",
"review/*/impact.md"
],
"read_only_paths": [
"review/*/task.md",
"review/*/feedback/"
],
"forbidden_paths": [
"projects/*/tests/",
"reports/"
],
"prompt_templates": {
"coding": ".ai/prompts/coding/",
"documentation": ".ai/prompts/coding/"
}
}
.ai/config/executor.json
-38
View File
@@ -1,38 +0,0 @@
{
"name": "Executor AI",
"role": "测试执行者",
"description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。",
"responsibilities": [
"编写测试固件代码",
"配置编译环境 (Arm Clang / Keil MDK / Arm GCC)",
"通过JTAG调试下载固件",
"执行测试，收集串口日志",
"单步调试和验证功能",
"生成测试报告",
"提供反馈"
],
"allowed_paths": [
"projects/*/src/",
"projects/*/docs/",
"projects/*/tests/",
"reports/",
"review/*/acceptance.md",
"review/*/feedback/",
"tools/"
],
"read_only_paths": [
"docs/",
"shared/",
"review/*/task.md",
"review/*/acceptance.md"
],
"forbidden_paths": [
".ai/",
"shared/",
"review/*/impact.md"
],
"prompt_templates": {
"execution": ".ai/prompts/execution/",
"testing": ".ai/prompts/execution/"
}
}
.ai/config/tester.json
-33
View File
@@ -1,33 +0,0 @@
{
"name": "QA AI",
"role": "测试工程师",
"description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。",
"responsibilities": [
"编写测试用例",
"执行测试",
"生成测试报告",
"提供反馈"
],
"allowed_paths": [
"projects/*/tests/",
"reports/",
"review/*/acceptance.md",
"review/*/feedback/"
],
"read_only_paths": [
"projects/*/src/",
"projects/*/docs/",
"docs/",
"data/",
"shared/",
"review/*/task.md"
],
"forbidden_paths": [
".ai/",
"tools/",
"review/*/impact.md"
],
"prompt_templates": {
"testing": ".ai/prompts/testing/"
}
}
.ai/config/workflow.json
-41
View File
@@ -1,41 +0,0 @@
{
"workflow": "mcu-chip-testing",
"roles": ["human", "arch-ai", "executor-ai"],
"stages": [
{
"name": "需求分析",
"actor": "arch-ai",
"output": ["docs/01_测试需求/", "review/{task_id}/task.md"]
},
{
"name": "测试架构",
"actor": "arch-ai",
"input": ["docs/01_测试需求/", "review/{task_id}/task.md"],
"output": ["docs/02_测试架构/", "review/{task_id}/impact.md", "review/{task_id}/acceptance.md"]
},
{
"name": "执行测试",
"actor": "executor-ai",
"input": ["review/{task_id}/task.md", "review/{task_id}/acceptance.md"],
"output": ["projects/*/src/", "projects/*/docs/", "reports/test-results/", "review/{task_id}/feedback/round{round}.md"]
},
{
"name": "验收确认",
"actor": "human",
"input": ["review/{task_id}/feedback/", "reports/test-results/"]
}
],
"retry": {
"max_rounds": 3,
"loop": ["执行测试"],
"escalation": {
"trigger": "第 3 轮测试仍有 BLOCKER 或 HIGH 级别问题",
"action": "暂停任务流转，等待人类负责人裁决"
},
"skip_acceptance_on_retry": true
},
"ci_triggers": {
"on_push_to_main": ["compile-firmware"],
"on_task_update": ["notify-executor-ai"]
}
}
.ai/knowledge/MCU芯片软件输入物料分析报告.md
Executable
+509
View File
@@ -0,0 +1,509 @@
# MCU/SoC芯片回片后软件侧输入物料与交付物标准分析报告
## 一、背景与问题界定
MCU/SoC芯片从RTL设计到回片（Tape-out后首次获取硅片），软件团队（SDK开发、驱动开发、寄存器测试）需要一系列标准化输入物料才能启动工作。这些物料的完整性、规范性和版本管理直接影响软件生态的质量。本报告从国际大厂实践、国内厂商现状、CMSIS SVD标准规范、芯片开发流程各阶段软件物料四个维度进行系统性分析。
---
## 二、国际大厂软件物料体系分析
### 2.1 ST意法半导体（STM32生态）
ST建立了全球最完善的MCU软件生态体系，其**STM32Cube生态系统**是行业标杆。
#### 文档体系层级
| 文档类型 | 定位与用途 | 典型文件 |
|---------|-----------|---------|
| **数据手册（Datasheet）** | 芯片电气特性、引脚定义、封装信息的概览文档，供硬件工程师和选型阶段使用 | STM32F103x8.pdf |
| **参考手册（Reference Manual）** | 完整描述每个外设的寄存器级细节，包括所有寄存器地址、位域定义、功能描述，是驱动开发的核心依据 | RM0008.pdf（STM32F1系列） |
| **编程手册（Programming Manual）** | ARM Cortex-M内核编程指导，包括指令集、异常模型、MPU配置等内核级内容 | PM0056.pdf |
| **勘误表（Errata Sheet）** | 记录已知的芯片硬件bug和规避方法，软件团队必须关注 | STM32F103x8_errata.pdf |
| **HAL/LL API参考手册** | 驱动库的完整API文档，包括函数签名、功能描述、参数说明、返回值 | STM32F1xx_HAL_driver.pdf |
| **应用笔记（Application Notes）** | 特定功能或应用场景的完整实现指南，如USB HID、电机控制、低功耗设计 | AN2592（EEPROM模拟） |
| **勘误表更新频率** | 随芯片版本迭代持续更新，与芯片步进（silicon revision）严格对应 | - |
#### STM32Cube MCU软件包结构
ST的**STM32Cube MCU软件包**是SDK的核心交付物，其目录结构如下：
```
STM32Cube_FW_F4_V1.27.0/
├── Drivers/ # 硬件驱动层
│ ├── CMSIS/ # ARM CMSIS标准组件
│ │ ├── Device/ # 设备级CMSIS文件
│ │ │ └── ST/ # ST厂商特定文件
│ │ │ └── STM32F4xx/
│ │ │ ├── Include/ # 设备头文件（由SVD自动生成）
│ │ │ │ ├── stm32f4xx.h
│ │ │ │ ├── system_stm32f4xx.h
│ │ │ │ └── startup_stm32f4xx.s
│ │ │ └── Source/
│ │ │ └── system_stm32f4xx.c
│ │ └── DSP/ # CMSIS-DSP库
│ │ └── RTOS/ # CMSIS-RTOS接口
│ ├── STM32F4xx_HAL_Driver/ # HAL硬件抽象层驱动
│ │ ├── Inc/ # 头文件
│ │ └── Src/ # 源码
│ ├── STM32F4xx_LL_Driver/ # LL底层驱动（轻量级、高效率）
│ └── BSP/ # 开发板支持包
├── Middlewares/ # 中间件
│ ├── ST/ # ST中间件
│ │ ├── TouchGFX/ # 图形库
│ │ ├── FreeRTOS/ # RTOS适配层
│ │ └── USB_Device/Host/ # USB协议栈
│ └── Third_Party/ # 第三方中间件
│ ├── FatFS/ # 文件系统
│ ├── LwIP/ # TCP/IP协议栈
│ └── mbedTLS/ # 加密库
├── Projects/ # 示例工程
│ ├── STM32F407G-DISC1/ # 按开发板分类
│ │ ├── Examples/ # 基础外设例程
│ │ ├── Applications/ # 高级应用例程
│ │ └── Demonstrations/ # 演示程序
├── Utilities/ # 通用工具和组件
└── package.xml # 包描述文件
```
#### 版本节奏与管理
- **文档版本**：参考手册通常在芯片发布时发布，后续根据芯片勘误和用户反馈更新
- **SDK版本**：通过版本号（如V1.27.0）管理，与IDE工具链版本解耦
- **IDE集成**：通过`.pack`文件（Keil Pack格式）分发，与CMSIS Pack标准兼容
### 2.2 NXP恩智浦（MCUXpresso SDK）
NXP的**MCUXpresso SDK**是其面向Cortex-M内核MCU的软件开发套件，以“生产级质量”为核心卖点。
#### 核心物料清单
| 物料类别 | 具体内容 | 说明 |
|---------|---------|------|
| **CMSIS-CORE组件** | startup_*.s、device header files、system_*.c/.h | ARM标准接口，设备无关层 |
| **外设驱动** | 无状态、高性能、易用的API驱动 | 通信外设含高级事务API和RTOS适配层 |
| **CMSIS-DSP** | 标准DSP库 | 针对Cortex-M4/M7优化的SIMD实现 |
| **RTOS内核** | FreeRTOS、Azure RTOS ThreadX、μC/OS-II/III | 预集成并验证 |
| **中间件** | USB协议栈、FatFS、lwIP、mbedTLS、emWin图形库 | 协议栈和中间件生态 |
| **示例代码** | 每个外设的驱动示例、RTOS示例、中间件示例 | boards目录下按开发板组织 |
| **MISRA-C合规报告** | 驱动代码符合MISRA-C:2012标准 | 经Coverity静态分析工具验证 |
| **SVD文件** | 完整的设备描述文件 | 用于调试视图和代码自动生成 |
#### NXP SDK文档体系
NXP的SDK配套文档包括：
- **Getting Started Guide**：快速上手指南，新用户必读
- **API Reference Manual**：SDK API完整参考
- **Demo Applications User's Guide**：示例应用使用说明
- **Transition Guide**：不同版本间的迁移指南
- **Release Notes**：版本更新说明和已知问题
### 2.3 TI德州仪器
TI的MSP430和Tiva系列有独立的文档体系。
#### MSP430文档结构
| 文档类型 | 定位 | 示例 |
|---------|------|------|
| **数据表（Data Sheet）** | 单芯片级别的电气参数和特性 | MSP430F5510 datasheet |
| **系列用户指南（Family User's Guide）** | 整个芯片系列的外设描述，按系列共享 | MSP430x5xx and MSP430x6xx Family User's Guide |
| **勘误表（Errata）** | 单芯片的具体已知问题 | MSP430F5507 Errata |
| **应用手册（Application Report）** | 特定应用实现指导 | 从旧系列迁移到新系列的指南 |
| **开发指南（Development Guide）** | 开发工具和流程指导 | MSP430 MCU Development Guide |
#### TI的SDK工具
- **MSP430Ware**：软件资源集合，包含驱动库、应用例程、技术文档
- **Grace**：图形化外设配置工具（已逐步被更现代的工具取代）
- **MSP430 DriverLib**：外设驱动库
### 2.4 瑞萨电子（Renesas）
瑞萨的RA系列（基于Cortex-M）和RX系列有独立的生态：
- **FSP（Flexible Software Package）**：RA系列的统一软件包
- 包含HAL驱动、中间件、FreeRTOS适配层
- 通过e² studio IDE集成图形化配置工具
---
## 三、CMSIS SVD规范深度解析
### 3.1 SVD的定义与定位
**CMSIS-SVD（System View Description）**是ARM定义的标准化设备描述文件格式，以XML格式描述微控制器的完整程序员视角视图。其核心价值在于：
> **将传统芯片手册（Data Sheet）"数字化"为结构化数据**，手册是给人看的文字，而SVD是给机器、开发环境、IDE"看"的标准化数据源。
### 3.2 SVD文件的核心作用
| 作用对象 | 具体价值 |
|---------|---------|
| **IDE/调试器** | 自动构建外设寄存器调试视图，开发者可在调试时直接看到寄存器各bit的符号化信息 |
| **代码生成工具** | 自动生成CMSIS兼容的设备头文件（*.h），包括所有外设基地址、寄存器结构体、位域定义 |
| **文档生成器** | 自动生成API参考手册的寄存器部分 |
| **寄存器测试** | 测试用例可基于SVD自动生成，检查寄存器读写的完整性 |
| **芯片选型工具** | 用于构建芯片选型数据库 |
### 3.3 SVD XML层级结构
根据ARM官方规范，SVD文件的层级结构如下：
```
<device>
├── <name> 设备名称（如STM32F103RC）
├── <version> 描述版本号
├── <description> 设备总体描述
├── <series> 产品系列名称
├── <vendorID> 厂商标识
│
├── <cpu> ★CPU内核描述（M4/M7等）
│ ├── <name> CM0/CM3/CM4/CM7等
│ ├── <revision> 内核版本 r0p0
│ ├── <endian> little/big/selectable
│ ├── <mpuPresent> MPU是否存在
│ ├── <fpuPresent> FPU是否存在
│ ├── <nvicPrioBits> NVIC优先级位数
│ └── <vendorSystickConfig> SysTick配置
│
├── <addressUnitBits> 地址单元位数（通常8）
├── <width> 数据总线宽度（通常32）
│
├── <peripherals> ★外设描述（核心内容）
│ └── <peripheral>
│ ├── <name> 外设名称（如USART1）
│ ├── <baseAddress> 基地址
│ ├── <groupName> 分组名称（如TIMERS）
│ ├── <description> 功能描述
│ ├── <interrupt> 中断关联
│ └── <registers>
│ └── <register>
│ ├── <name> 寄存器名称（如SR）
│ ├── <addressOffset> 地址偏移
│ ├── <resetValue> 复位值
│ ├── <access> 访问类型（read-write等）
│ ├── <description> 描述
│ └── <fields>
│ └── <field>
│ ├── <name> 字段名称（如TXE）
│ ├── <bitRange>[7:0]</bitRange> 或 <lsb>0</lsb> + <msb>7</msb>
│ ├── <access> 访问权限
│ ├── <enumeratedValues> 枚举值
│ │ └── <enumeratedValue>
│ │ ├── <name> Enable
│ │ ├── <value> 1
│ │ └── <description> 发送缓存空
│ └── <description>
│
└── <vendorExtensions> 厂商扩展（可选）
```
### 3.4 SVD与设备头文件的生成关系
SVD文件是CMSIS设备头文件的**源头数据**，其关系如下：
```
SVD文件 → [SVDConv工具] → 设备头文件(*.h)
↓
┌──────────────────────────────────────┐
│ stm32f103xb.h 包含内容： │
│ - 外设基地址宏定义 │
│ - 外设寄存器结构体 │
│ - 寄存器位域定义 │
│ - 枚举值常量定义 │
│ - 中断号定义 │
└──────────────────────────────────────┘
```
### 3.5 SVD文件的管理与分发
- **管理主体**：由芯片厂商在其**Device Database**中集中管理
- **分发渠道**：通过CMSIS Pack机制（*.pack文件）分发
- **公开访问**：厂商发布后可通过Keil MDK的Pack Installer或CMSIS官方界面下载
- **版本维护**：随芯片勘误更新，版本号递增
---
## 四、国内MCU厂商软件物料实践分析
### 4.1 兆易创新GD32
GD32是国产32位MCU的领头羊，其软件物料体系在国内最为完善。
#### 物料清单
| 文档类型 | 说明 | 覆盖率 |
|---------|------|-------|
| **数据手册（Datasheet）** | 芯片电气参数、引脚定义 | 全系列 |
| **用户手册（User Manual）** | 参考手册级别，详述寄存器 | 主要系列 |
| **固件库使用指南** | Firmware Library使用说明 | 主要系列 |
| **应用笔记（Application Notes）** | 硬件设计指南、移植指南 | 部分系列 |
| **勘误表** | 已知问题列表 | 部分系列 |
| **DFP包（Keil Device Family Pack）** | IDE设备支持包 | 主要系列 |
| **标准固件库/Drivers** | 外设驱动库 | 主要系列 |
#### SDK目录结构（以GD32F30x为例）
```
GD32F30x_Demo_Suites_V2.1.0/
├── GD32F30x_Firmware_Library/ # 固件库（核心）
│ ├── CMSIS/
│ │ ├── GD/ # GD厂商CMSIS文件
│ │ │ ├── Include/ # 设备头文件
│ │ │ │ ├── gd32f30x.h
│ │ │ │ ├── system_gd32f30x.h
│ │ │ │ └── startup_gd32f30x_xx.s
│ │ │ └── Source/
│ │ │ └── system_gd32f30x.c
│ │ └── ARM/
│ │ └──（ARM CMSIS核心文件）
│ ├── Driver/ # 外设驱动
│ │ ├── Inc/
│ │ └── Src/
│ ├── Examples/ # 例程（非独立目录，嵌入在各工程中）
│ └── Release_Notes.html
├── Project/
│ ├── GD32F303_EVAL/ # 按芯片型号/开发板组织
│ │ ├── Examples/ # 外设例程
│ │ │ ├── ADC/ # 各类外设
│ │ │ │ ├── ADC0_RegularChannel/
│ │ │ │ └── ADC0_DMA/
│ │ │ ├── GPIO/
│ │ │ └── ...
│ │ ├── Template/ # 工程模板
│ │ └── Applications/
│ └── GD32F305_EVAL/
├── Utilities/
│ └── LCD/ # 通用组件
└── Documents/ # 部分系列的文档打包
```
#### GD32的SVD实践
- GD32提供SVD文件，可通过Keil Pack Installer获取
- 文件覆盖主要系列，但部分新型号的SVD可能存在更新滞后
- 与ST的STM32高度兼容，部分SVD可直接参考ST的兼容芯片
#### 与国际大厂差距分析
| 维度 | GD32 | ST/NXP | 差距说明 |
|------|------|--------|---------|
| 文档完整性 | 中 | 高 | 部分应用笔记和勘误表覆盖不足 |
| 文档语言 | 中英双语 | 以英文为主 | GD32提供较完善的中文文档 |
| SDK工具链 | 基础 | 完善 | 缺乏图形化配置工具（目前仅有雏形） |
| 中间件生态 | 基础 | 丰富 | FatFS/LwIP等中间件支持较弱 |
| 社区生态 | 成长中 | 成熟 | 开发者社区规模差距明显 |
| SVD规范性 | 基本符合 | 完全符合 | 部分字段描述精度有待提升 |
### 4.2 华大半导体HC32
HC32系列是国产替代的重要选择，其物料体系：
- **用户手册**：提供寄存器级描述
- **驱动库**：基于CMSIS标准的外设驱动
- **开发工具包**：Keil/IAR支持包
- **例程**：覆盖主要外设的基础例程
与GD32类似，在文档深度和应用笔记丰富度上与国际大厂存在差距。
### 4.3 极海APM32、雅特力AT32
这些品牌的物料体系特点：
- 文档体系相对精简
- 主要提供寄存器手册和基础驱动库
- SVD文件覆盖度参差不齐
- 应用笔记数量有限
- 社区支持主要依赖第三方
### 4.4 国民技术N32
N32系列物料：
- 提供标准固件库
- 有配套的IDE支持包
- 文档体系在逐步完善中
- SVD支持情况因型号而异
### 4.5 国内厂商整体差距总结
| 差距维度 | 具体表现 | 根本原因 |
|---------|---------|---------|
| **文档体系** | 应用笔记数量不足、勘误表更新不及时 | 软件团队规模有限，工程化经验积累不足 |
| **SDK工具链** | 缺乏图形化配置工具 | 需要大量投入，且用户基数不如国际大厂 |
| **中间件生态** | 协议栈、文件系统、图形库支持薄弱 | 生态建设需要合作伙伴和长期投入 |
| **SVD质量** | 部分描述精度不足，版本同步滞后 | 缺乏自动化SVD生成和质量校验流程 |
| **社区建设** | 开发者社区规模和活跃度不足 | 起步晚，需要时间积累 |
| **多语言支持** | 部分文档仅有英文版 | 国际化团队配置不足 |
---
## 五、芯片开发流程各阶段的软件物料
### 5.1 整体流程概览
芯片从RTL到SDK发布的完整流程中，软件物料在各阶段逐步丰富：
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 阶段1: RTL设计 │
│ 输入: 架构规格书、寄存器定义文档 │
│ 输出: RTL代码、寄存器规格说明（RegSpec） │
│ 软件活动: 架构评审、寄存器映射定义 │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 阶段2: 验证（Simulation/Emulation） │
│ 输入: RTL代码、寄存器规格说明 │
│ 输出: 仿真模型（ISS、Verilog-AMS）、验证环境、测试用例 │
│ 软件活动: 编写驱动白盒测试用例 │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 阶段3: FPGA原型验证 │
│ 输入: 综合后的网表、FPGA比特流 │
│ 输出: FPGA可运行的固件、寄存器验证报告 │
│ 软件活动: 驱动在FPGA上验证、寄存器行为确认 │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 阶段4: 回片（Tape-out → Silicon） │
│ 输入: （无额外输入，等待硅片） │
│ 输出: 硅片回来后的首次验证 │
│ 软件活动: 首次硅验证（Silicon Bring-up）、寄存器测试 │
└─────────────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────────────┐
│ 阶段5: SDK开发与发布 │
│ 输入: 确认的寄存器定义、参考手册草稿 │
│ 输出: 正式SDK、HAL库、示例代码、SVD文件、文档发布 │
│ 软件活动: 完善驱动、编写应用笔记、发布SDK │
└─────────────────────────────────────────────────────────────────────────┘
```
### 5.2 各阶段详细软件物料清单
#### 阶段1：RTL设计阶段
| 物料名称 | 内容描述 | 格式 | 用途 |
|---------|---------|------|------|
| **架构规格书（Arch Spec）** | 系统架构、IP模块划分、总线设计 | Word/PDF | 软件团队理解芯片整体架构 |
| **寄存器规格说明（RegSpec）** | 每个外设寄存器的完整定义，包括地址、位域、复位值、访问类型、枚举值 | Excel/XML | 驱动开发的核心依据，SVD生成的基础 |
| **内存映射文档（Memory Map）** | 外设基地址、Flash/SRAM地址分配、启动地址 | PDF | 链接脚本配置、启动代码编写 |
| **时钟架构文档** | 时钟树、各PLL/MUX配置、时钟域定义 | PDF | 时钟初始化驱动开发 |
| **中断规格文档** | 中断号分配、中断优先级配置、向量表 | PDF | 中断处理代码开发 |
| **IP接口文档** | 各外设的时钟/复位/接口信号定义 | PDF | 芯片级驱动开发 |
**软件团队在此阶段的工作**：
- 参与寄存器定义评审，确保寄存器设计符合软件使用习惯
- 制定软件架构和驱动分层策略
- 开始准备CMSIS兼容的设备头文件框架
#### 阶段2：验证阶段（Pre-Silicon）
| 物料名称 | 内容描述 | 格式 | 用途 |
|---------|---------|------|------|
| **仿真模型（ISS/RTL Simulation Model）** | 指令集仿真器或高抽象级RTL仿真模型 | Binary/Shared Library | 软件团队在没有硬件时的开发环境 |
| **虚拟平台（Virtual Platform）** | SystemC/TLM模型，可在真实RTL之前运行软件 | ELF/Binary | 早期软件开发、BSP开发 |
| **寄存器验证测试用例** | 基于RegSpec的寄存器读写测试用例 | C/SystemVerilog | 验证寄存器定义正确性 |
| **外设行为模型** | 简化的外设行为仿真模型 | C/SystemC | 驱动开发时的单元测试 |
**软件团队在此阶段的工作**：
- 在ISS或虚拟平台上开发驱动和BSP
- 使用寄存器测试用例进行白盒验证
- 提交寄存器定义问题反馈
#### 阶段3：FPGA原型验证阶段
| 物料名称 | 内容描述 | 格式 | 用途 |
|---------|---------|------|------|
| **FPGA比特流（*.bit / *.sof）** | 综合实现的FPGA配置文件 | Binary | 下载到FPGA开发板 |
| **引脚分配文件** | FPGA引脚与芯片引脚的对应关系 | XDC/UCF/CSV | 硬件调试 |
| **调试桥接固件** | 用于在FPGA环境和PC之间建立调试通道的固件 | ELF | 调试通信 |
| **寄存器测试报告** | FPGA上寄存器读写验证结果 | PDF | 确认RTL实现的寄存器与规格一致 |
| **性能基准测试** | 外设性能指标实测数据 | PDF | 与规格书对比，确认性能达标 |
**软件团队在此阶段的工作**：
- 在FPGA原型上进行真实驱动验证
- 首次在接近真实芯片的环境中运行完整软件栈
- 发现并反馈RTL与规格的差异
- 编写初步的勘误表（Known Issues）
#### 阶段4：回片后首次验证（Silicon Bring-up）
| 物料名称 | 内容描述 | 格式 | 用途 |
|---------|---------|------|------|
| **开发板/工程样片** | 芯片实体 | 硬件 | 软件开发载体 |
| **调试器固件** | 支持新芯片的调试器固件 | Binary | J-Link/DAP-Link等调试器升级 |
| **烧录工具** | 支持新芯片的Flash编程工具 | Binary | 固件烧录 |
| **首次验证报告** | 芯片基本功能（时钟、GPIO、UART等）验证结果 | PDF | 确认芯片基本功能正常 |
| **寄存器偏差报告** | 与FPGA验证结果的对比，可能发现RTL与Silicon的差异 | PDF | 更新寄存器规格 |
| **初步勘误表** | Silicon验证中发现的问题和规避方法 | PDF | 软件团队必须关注的警告 |
**软件团队在此阶段的工作**：
- 执行完整的寄存器测试套件
- 验证所有外设的基本功能
- 发现并记录与FPGA原型的差异
- 更新驱动以适配Silicon特有的行为
#### 阶段5：SDK开发与正式发布
| 物料名称 | 内容描述 | 格式 | 用途 |
|---------|---------|------|------|
| **SVD文件** | 完整的CMSIS-SVD设备描述 | XML | 发布到CMSIS Pack、供IDE使用 |
| **设备头文件（Device Header）** | 基于SVD生成的CMSIS兼容头文件 | .h | 开发者使用 |
| **启动文件（Startup Code）** | 汇编启动代码，向量表定义 | .s | 链接脚本、复位处理 |
| **系统初始化文件** | SystemInit()等系统初始化代码 | .c | 时钟配置、SystemCoreClock更新 |
| **HAL/LL驱动库** | 外设驱动源码 | .c/.h | 应用开发 |
| **中间件库** | RTOS、文件系统、网络协议栈等 | 源码/库 | 应用开发 |
| **示例代码（Examples）** | 每个外设的完整使用示例 | 完整工程 | 学习参考 |
| **应用笔记（Application Notes）** | 特定功能的完整实现指南 | PDF | 高级应用参考 |
| **API参考手册** | HAL/LL驱动API完整文档 | HTML/PDF | 开发参考 |
| **勘误表（Errata Sheet）** | 已知芯片问题列表和规避方法 | PDF | 开发者必须阅读 |
| **SDK发布说明（Release Notes）** | 本版本新增内容、已知问题、迁移指南 | PDF/MD | 版本管理 |
| **CMSIS Pack** | 打包好的SDK分发包 | .pack | 通过IDE分发 |
---
## 六、总结与建议
### 6.1 国际大厂物料体系的核心特征
1. **文档完整性**：数据手册、参考手册、编程手册、应用笔记、勘误表五类文档缺一不可
2. **SVD优先**：设备描述文件是所有软件物料的源头数据，严格与参考手册保持一致
3. **SDK结构化**：HAL+LL双层驱动、中间件模块化、示例代码完整
4. **版本管理**：文档和SDK都有清晰的版本号，与芯片步进（Silicon Revision）对应
5. **工具链整合**：配置工具、代码生成器、调试器与SDK深度集成
### 6.2 国内厂商的提升路径
| 阶段 | 重点任务 | 预期成果 |
|------|---------|---------|
| **基础夯实** | 完善SVD文件、注册表规范文档 | SVD覆盖率>95%，文档与芯片同步更新 |
| **工具链建设** | 开发图形化配置工具、完善IDE支持包 | 开发者体验接近国际大厂 |
| **生态扩展** | 扩展中间件合作、丰富应用笔记 | 协议栈、文件系统等中间件开箱即用 |
| **社区运营** | 建立开发者社区、提供FAE支持 | 形成正向循环的开发者生态 |
### 6.3 关键成功因素
1. **SVD质量**：SVD是所有软件物料的"黄金源"，必须与参考手册严格一致，并有自动化校验流程
2. **文档与代码同步**：任何寄存器变更必须同时更新SVD、参考手册和驱动代码
3. **勘误表及时性**：芯片问题必须在勘误表中及时记录，不遗漏任何软件可能踩坑的点
4. **版本透明度**：所有交付物必须有版本号，变更历史可追溯
---
## 附录：典型MCU厂商文档获取渠道
| 厂商 | 文档下载入口 | SDK下载入口 |
|------|-------------|-------------|
| ST | st.com → 产品页面 → 文档 | st.com → STM32CubeMX → 选择芯片 |
| NXP | nxp.com → 产品页面 → 文档 | mcuxpresso.nxp.com → Build SDK |
| TI | ti.com → 产品页面 → 技术文档 | ti.com → Tools & Software |
| GD32 | gd32mcu.com → 下载中心 | gd32mcu.com → 下载中心 |
| 瑞萨 | renesas.com → 产品 → 文档 | renesas.com → RA FSP |
---
*本报告基于公开信息整理，数据截止时间：2024年*
.ai/knowledge/decisions.md
+25 -175
View File
@@ -1,191 +1,41 @@
# 架构决策记录 (ADR)
## ADR-001: "1 人 + 2 AI" 协作框架
## ADR-001: 测试驱动 SDK 演进
- 日期: 2026-05-23
- 状态: 已采纳（后升级为 1 人 + 3 AI）
- 决策: 采用人类负责人 + Dev AI + QA AI 的三角协作模式
- 理由: 单人开发需要 AI 辅助，但 AI 不能互审，需要人类做最终决策
- 影响: 定义了 R/W/RW/- 四级权限体系
## ADR-002: 四级权限体系
- 日期: 2026-05-23
- 日期: 2026-05-27
- 状态: 已采纳
- 决策: 采用 `-`(禁止) / `R`(只读) / `W`(可写) / `RW`(读写) 四级权限，比二进制的读写更精细
- 理由: AI 角色需要明确的边界，"只读但不能写"和"完全不可见"需要区分
- 影响: 所有目录访问按权限矩阵执行，`forbidden > read_only > allowed` 优先级
- 决策: 寄存器测试是 SDK 的第一用户，测试代码直接演进为 LL 层驱动
- 理由: bring-up 阶段的核心产出是验证寄存器功能，测试代码天然包含了对寄存器的精确操作逻辑，提炼为 LL 层零浪费
- 影响: Test/cases/ 的代码质量要求等同于 SDK 代码；每个功能单元的测试代码必须结构化，便于后续提炼
## ADR-003: 根级 docs/ 目录
## ADR-002: HAL/LL 双层架构，参考 STM32CubeH7
- 日期: 2026-05-23
- 日期: 2026-05-27
- 状态: 已采纳
- 决策: 项目级文档放在根目录 `docs/` 而非子项目内
- 理由: 跨项目共享的文档（架构设计、开发规范）不应属于某个子项目
- 影响: docs/ 由 Arch AI 和 Dev AI 共同维护
- 决策: 采用与 STM32CubeH7 一致的 HAL/LL 双层架构，包括句柄模式、弱回调、模块化编译
- 理由: STM32CubeH7 是经过大规模验证的工业级 SDK 架构，HAL/LL 双层兼顾了可移植性和性能，开发者社区熟悉度高
- 影响: 驱动代码必须遵循 HAL/LL 分层；HAL 用句柄+状态机+回调，LL 用内联函数直操寄存器；编译体积由 hal_conf.h 宏开关控制
## ADR-004: 独立 tools/ 和 data/ 目录
## ADR-003: 33 个功能单元分 7 阶段 bring-up
- 日期: 2026-05-23
- 日期: 2026-05-27
- 状态: 已采纳
- 决策: 开发工具脚本和训练数据从 shared/ 中独立出来
- 理由: tools 和 data 的使用场景和权限需求与 shared 不同
- 影响: Arch AI 和 Dev AI 可写 tools/ 和 data/，QA AI 只能读 data/
- 决策: 按 bring-up 逻辑将 33 个功能单元分为 P0-P6 七个阶段，P0-P1 串行，P2-P6 可按需并行
- 理由: 芯片 bring-up 有天然依赖——必须先能跑（P0），才能有调试输出（P1），然后才能测其他外设。但模拟、定时器、存储、高速接口之间没有强依赖，可以并行
- 影响: 任务编号用 D{阶段号}-{序号}，阶段切换需人类确认
## ADR-005: 工作流重试和升级机制
## ADR-004: 1 人 + 2 AI 单仓库协作
- 日期: 2026-05-23
- 日期: 2026-05-27
- 状态: 已采纳
- 决策: 测试 → 修复循环最多 3 轮，Round 3 仍有 BLOCKER/HIGH 则升级给人类
- 理由: 防止无限循环，确保严重问题得到人类关注
- 影响: `skip_acceptance_on_retry: true`，修复轮次不重写验收标准
- 决策: 采用 1 人 + Arch AI + Worker AI 的协作模式，单仓库，不需要 review 仓库
- 理由: 嵌入式项目文件数少但精度高，Arch AI 和 Worker AI 在同一仓库操作更直接。测试包含在 Worker AI 职责内，不需要独立 QA AI
- 影响: 去掉 errlens 的 review/ 目录和 QA AI 角色；Worker AI 同时负责开发和测试
## ADR-006: resume-context Skill 多机同步
## ADR-005: Arch AI 角色可由任何 AI 担当
- 日期: 2026-05-23
- 日期: 2026-05-27
- 状态: 已采纳
- 决策: 通过 `resume-context` Skill 实现换电脑时上下文恢复
- 理由: 用户在家和公司两台电脑开发，需要快速恢复 AI 工作上下文
- 影响: 角色检测、关键文档加载、上下文摘要生成
## ADR-007: 分层信息架构 + Token 预算
- 日期: 2026-05-25
- 状态: 已采纳
- 决策: 采用四层信息架构（工作台 → 路线图 → 阶段上下文 → 知识沉淀），每层有 token 预算
- 理由: AI 上下文窗口有限（~200K tokens），旧 AGENTS.md 单体文件浪费 token；每个 AI 角色只需要知道自己该干什么
- 影响: 所有 AI 从 `.ai/roles/{role}/` 启动；新增 `ROADMAP.md`、`DASHBOARD.md`、`docs/share/` 分享层
## ADR-008: 框架/项目双分支 + 同步机制
- 日期: 2026-05-25
- 状态: 已废弃（被 ADR-013 替代，2026-05-26）
- 决策: ~~采用双分支策略：`main` 分支开发具体项目（ErrLens），`ai_project` 分支保持为去敏的通用模板。通过 `sync-template.sh` 从 main 单向同步框架层变化到模板分支~~ 废弃原因：双分支维护成本高，容易过时。ai_project 分支在新架构升级后已严重落后于 main
- 理由（原）:
- 框架层变化需要传播到模板，但重做去敏化消耗巨大（~100K tokens）
- 两个分支的差异本质是"变量替换"，可以脚本自动化
- 框架层（AGENTS/权限/提示词/工作流）和项目层（任务/日志/代码）的边界清晰
- 影响（原）:
- 新增 `SYNC.md` 定义框架层/项目层边界（保留，被 ADR-013 复用）
- 新增 `sync-template.sh` 实现自动同步（已删除）
- 新增 `TEMPLATE.yaml` + `init.sh` 实现一键初始化（TEMPLATE.yaml 保留，init.sh 删除）
- AI 项目框架从此可复用，token 节省 95%+
## ADR-013: Skill 替代脚本 — 框架脱敏/初始化的正确方式
- 日期: 2026-05-26
- 状态: 已采纳
- 决策: 废弃 ADR-008 的「双分支 + shell 脚本」方案，改为「Skill + 配置文件」方案。框架脱敏和项目初始化由 `project-init` Skill 按需执行，不再维护独立模板分支
- 理由:
- **双分支方案的问题已被验证**：ADR-008 的 ai_project 分支在新架构升级（dashboard.md / .ai/tasks/ / 归档）后严重过时，SYNC.md 和 sync-template.sh 的文件清单全是旧结构引用
- **AI 是执行者，不需要可执行脚本**：shell 脚本是给人类或 CI 用的。但当前场景中，脱敏/初始化是由 AI（Claude Code）执行的——AI 需要的是清晰的规格说明（SYNC.md + TEMPLATE.yaml + Skill 指令），而不是可执行脚本
- **Skill 方案不过时**：脚本写死了文件列表，框架一变脚本就过时。Skill 描述的是「方法」——读 SYNC.md 获取边界 → 读 TEMPLATE.yaml 获取变量 → 执行替换。框架变化时只需更新 SYNC.md，Skill 本身不变
- **零维护成本**：不再需要 sync-template.sh、init.sh、独立 Git 分支。3 个文件（SYNC.md + TEMPLATE.yaml + Skill）vs 旧方案的 4 个文件 + 1 个分支
- 关键洞察:
- **「脚本优于 Skill」的前提是执行者是机器**。当执行者是 AI 时，Skill（语义描述 + 约束）优于脚本（硬编码文件列表）
- **边界定义文件（SYNC.md）是长期资产**，脚本是短期负债——脚本依赖边界定义，但边界定义不应绑定于特定的执行方式
- 影响:
- 保留 `SYNC.md`（更新为新架构文件结构）
- 保留 `TEMPLATE.yaml`（变量定义）
- 新增 `.trae/skills/project-init/SKILL.md`
- 废弃 `sync-template.sh`、`init.sh`
- 废弃 `ai_project` 分支（不再维护，仅保留历史参考）
## ADR-009: 人机协同数据质量闭环
- 日期: 2026-05-26
- 状态: 已采纳
- 决策: 不依赖 AI 一次识别准确。AI 识别结果作为"草稿"入库，经用户确认/修正后才进入分析和推荐管道。所有修正记录保留为 P02 训练数据。
- 理由:
- 手写体 OCR 准确率无法保证 100%（尤其中小学生潦草字迹），错误数据直接进入分析会污染薄弱点诊断和练习推荐
- 传统方案（调高 AI 准确率）成本极高且天花板低。人机协同方案将"用户修正"从成本转化为资产
- 每一次用户修正 = 一条免费的标注数据，是训练自有模型的核心资源
- 关键设计:
- verification_status 状态机: raw → reviewed → corrected（+ stale 兜底）
- 分字段置信度: 每个 AI 字段独立评分，低置信度高亮
- 数据质量门控: AnalysisReport 和 Recommendation 仅使用 reviewed+ 数据
- CorrectionLog: AI 值 vs 用户修正值的完整记录
- 交互设计: 置信度绿/黄/红三级 UI，批量确认降低摩擦
- 影响:
- error_items 表新增 verification_status + ai_confidence 列
- 新增 correction_logs 表
- 分析/推荐查询需加 verification_status 过滤
- P02 阶段训练数据来源从"外部标注"变为"内部修正记录"
## ADR-010: 题库抽象层设计 —— Adapter Pattern 多源统一接入
- 日期: 2026-05-26
- 状态: 已采纳
- 决策: 采用 Adapter Pattern（适配器模式）实现多题库源的统一接入。自有题库（PDF 录入）和第三方题库（作业帮 API）通过 `QuestionBankAdapter` 接口统一路由，调用方无感知。
- 理由:
- 旧架构仅自有题库，新架构决定了双题库源（自有 PDF + 作业帮 API），且未来可能有更多来源
- 如果直接在主业务逻辑中写 `if (source === 'zuoyebang')` 分支判断，每加一个题库源就要改业务代码
- Adapter Pattern 将"题库源差异"封装在适配器内部，业务逻辑只依赖 `QuestionBankAdapter` 接口
- 架构已明确: 决策 #1（双题库源）要求"架构层抽象适配"
- 关键设计:
- 接口定义: `QuestionBankAdapter { source, search(params), getById(id), healthCheck() }`
- 适配器工厂: `AdapterFactory` 按 `source` 字段路由到对应适配器实例
- 搜索策略: 并行查询所有适配器 → 合并去重 → 自有题库优先排序
- 新增题库源: 只需实现 `QuestionBankAdapter` 接口 + 注册到工厂，零业务代码改动
- 影响:
- `modules/question-bank/adapters/` 目录结构: `base-adapter.ts`, `self-built.adapter.ts`, `zuoyebang.adapter.ts`, `adapter.factory.ts`
- `questions` 表 `source` 字段 = 适配器路由 key（`self_built` | `zuoyebang` | 未来扩展）
- `external_id` 字段存储第三方题库的原始 ID，自有题库此字段为空
- 健康检查: 每个适配器实现 `healthCheck()`，用于监控外部 API 可用性
## ADR-011: 不急于引入多 Agent 编排层 —— 先精简，后分层
- 日期: 2026-05-26
- 状态: 已采纳
- 决策: 当前阶段不引入正式的多 Agent 编排框架（MegaAgent 式 Boss-Admin-Worker 三层架构）。保留「1 人 + 3 AI」角色划分作为逻辑框架，但实际协作由 Claude Code 子 Agent 机制承载。先做 `.ai/` 配置精简（47 → ~20 文件），再评估是否需要模型分层
- 理由:
- **规模不匹配**：当前是 1 人项目，不是 10 人团队。「编排层」就是人类 + Claude Code 本身，不需要额外的编排 Agent
- **行业共识未形成**：2025-2026 年业界分裂为两派——多 Agent 编排派（Anthropic/NUS/华为 openJiuwen）和单 Agent 上下文工程派（Cognition/Devin）。后者认为多 Agent 在编码领域是伪命题，隐性决策冲突和整合成本 > 并行收益。Anthropic 也部分承认「编码任务的可并行性远低于研究任务」
- **架构已是负担**：`.ai/` 47 个文件，Phase 2 代码一行没写。继续加架构层只会加重问题
- **子 Agent 甜蜜点已确认**：只读研究/探索是最有效的子 Agent 场景，并行编码效果不佳——这与我们当前的实际使用模式一致
- 关键判断:
- **按业务上下文划分优于按角色划分**（来自 Microsoft 参考架构 + MegaAgent 实践）。如果未来引入多 Agent，应按「认证流」「错题录入流」「推荐流」划分，而非 Arch/Dev/QA
- **调度层必须是确定性代码**（来自 Microsoft 参考架构）。用 LLM 做任务路由是反模式，应使用脚本/CI/工作流引擎
- **模型分层（Opus→Sonnet→Haiku）的方向正确**，但应在 Phase 3 功能完善阶段引入，而非现在。MegaAgent 实测成本可降至全 Opus 的 ~1/10
- 影响:
- `.ai/` 配置精简为近期行动项
- Arch AI today.md + queue.md 合并
- Phase 3 前重新评估 Agent 架构，届时根据团队规模和实际瓶颈决定
## ADR-012: 跨平台「高模型指挥小模型」协作架构
- 日期: 2026-05-26
- 状态: 已采纳 + 已落地（2026-05-26 同日，D-001 人类确认后立即执行）
- 决策: 确认当前实际的三平台协作架构——Claude Code + DeepSeek V4 Pro（Arch AI）、Trae CN + GLM-4.6（Coder AI）、Coze CN（Tester AI）——并以此为基准设计任务交接协议。Git 仓库是平台间唯一的通信介质
- 理由:
- **ADR-011 的前提假设错误**：之前认为所有 AI 角色都在 Claude Code 内切换，因此得出了「架构太多了，先精简」的结论。但实际上三个角色运行在三个完全不同的平台/IDE 上，文档是它们之间唯一的通信协议
- **跨平台意味着零共享上下文**：Trae + GLM-4.6 不会知道 Claude Code 里讨论了什么。Coze 沙盒不会知道架构设计的细节。所有上下文必须通过 Git 仓库中的文件显式传递
- **这恰好是一个自然的「高模型指挥小模型」架构**：Arch AI（Claude + DeepSeek V4，最强推理 + 最强 Agent 框架）→ Coder AI（Trae + GLM-4.6，中配模型）→ Tester AI（Coze CN，沙盒执行）
- 关键设计:
**模型能力边界**:
| 角色 | 平台+模型 | 擅长 | 不擅长 |
|------|----------|------|--------|
| Arch | Claude Code + DeepSeek V4 | 架构推理、方案设计、任务分解 | 大量代码输出（token 成本高） |
| Coder | Trae + GLM-4.6 | 代码生成、文件操作 | 复杂推理、多文件协调 |
| Tester | Coze CN | 沙盒执行、自动化验证 | 架构判断、代码修改 |
**任务交接协议（Git 是唯一集成总线）**:
```
Arch 写 task → commit → Coder pull → 读 task → 写代码
→ commit → Tester pull → 跑测试 → 写 report
→ commit → Arch 读报告做决策
```
**关键约束**:
1. 每个 task 必须自包含——不能假设 Coder AI 「知道前面的讨论」。必须包含：明确的输入文件、输出文件、约束条件、参考 ADR
2. 任务粒度适配 GLM-4.6——单文件或强内聚的 2-3 个文件，跨模块协调由 Arch AI 在设计阶段完成
3. 每次 commit 粒度 = 恰好一个交接单元
4. Coze 沙盒做真正的自动化测试闭环——拉代码 → 执行 → 生成 JSON 报告 → commit 回仓库
- 影响:
- **推翻 ADR-011 的「精简」结论**：架构文档不能砍，但需要重新定位——从「给自己看的备忘录」变成「跨平台的可靠交接协议」
- Task 模板需要升级：增加「输入」「输出」「约束」「参考 ADR」四个必填字段
- Dev AI queue.md 的每个任务 description 需要能独立阅读理解，不依赖上下文
- 这是对 ADR-001「1 人 + 3 AI」协作框架的实质性落地——从抽象角色到具体平台+模型绑定
- 决策: Arch AI 和 Worker AI 不是绑定到某个特定 AI 平台的角色定义，而是职责定义。任何 AI（扣子、Claude Code、DeepSeek 等）读到 card.md 即可担当
- 理由: 实际使用中不同场景适合不同 AI——架构讨论用扣子对话，代码执行用 Claude Code 终端，快速查询用 DeepSeek CLI。强制绑定单一平台会降低效率
- 影响: card.md 必须自包含，不假设读它的 AI 有任何前置上下文；AGENTS.md 是通用上下文锚点
.ai/knowledge/journal/2026-05-25.md
-70
View File
@@ -1,70 +0,0 @@
# 2026-05-25 — 信息架构重构 + 模板化
## 做了什么
### 1. 信息架构重构（Arch AI 角色）
将项目从"人类导向单体文档"重构为"AI 优先分层架构"：
**新增四层信息架构：**
- Layer 0: 角色工作台 `.ai/roles/{arch,dev,qa}/` — 每个 AI 每天只读 card.md + today.md（< 2K tokens）
- Layer 1: 路线图看板 `ROADMAP.md` — 人+AI 共享进度
- Layer 2: 阶段上下文 `.ai/phases/phase-NN/` — 按需加载（< 5K tokens）
- Layer 3: 知识沉淀 `.ai/knowledge/` — 自动积累决策/模式/教训
**新增关键文件：**
- `DASHBOARD.md` — 人类仪表盘（根目录，30 秒可读）
- `ROADMAP.md` — 阶段进度 + 任务看板 + 阻塞项
- `docs/使用手册.md` — 人+AI 完整使用手册
- `.ai/principles.md` — 信息架构设计原则
- `.ai/prompts/architecture/` — 补充缺失的架构提示词模板
**压缩改写：**
- AGENTS.md: 239行 → 117行
- README.md: 167行 → 88行
- PROJECT_CONTEXT.md: 117行 → 52行
**一鸡多吃分享层：**
- `docs/share/` — 阶段复盘模板、决策故事模板
### 2. 项目模板化（ai_project 分支）
将 ErrLens 框架去敏化为通用 AI 协作项目模板：
- 创建 `TEMPLATE.yaml` — 14 个模板变量定义
- 创建 `init.sh` — 一键初始化新项目的脚本
- 创建 `sync-template.sh` — 从 main 同步框架层到模板分支
- 创建 `SYNC.md` — 框架层/项目层边界定义
- 98 处 {{变量}} 覆盖所有关键位置
- 双分支策略：main（具体项目） + ai_project（通用模板）
### 3. 知识沉淀
- ADR-007: 分层信息架构 + Token 预算
- ADR-008: 框架/项目双分支 + 同步机制
- P-001: AI 任务交接模式
- P-002: 角色工作台模式
- P-003: 模板同步模式
- L-001: 单体 AGENTS.md 浪费 AI 上下文
## 当前状态
- 分支: main（ErrLens 开发）
- 阶段: Phase 1 基础搭建，进度 ~40%
- 信息架构重构: ✅ 完成
- 模板化: ✅ 完成（在 ai_project 分支）
- 所有代码已推送远程
## 下一步（明天继续）
Arch AI 下一步:
1. 编写 `docs/01_产品需求/PRD.md` — 错题本产品需求文档
2. 设计 `docs/02_系统架构/` — 系统架构文档
3. 将 P01 项目文档从"代码检测"改写为"错题本"
## Git 提交记录
- 4184a6d: 信息架构重构（main）
- 0df22a2: 去敏化为模板（ai_project）
- 05b87a9: 模板同步机制（ai_project）
- 46af1f8: ADR-008 + P-003（ai_project）
## 注意
- ai_project 分支上还有 ADR-008 和 P-003，main 上尚未同步（本次会补上）
- 如果明天接不上，读 DASHBOARD.md + .ai/roles/arch/card.md + .ai/roles/arch/today.md 即可
.ai/knowledge/journal/2026-05-26.md
-63
View File
@@ -1,63 +0,0 @@
# Arch AI · 开发日志 · 2026-05-26
## 完成事项
### Phase 1 收尾
- [x] 旧架构合并：30 项决策逐项确认，5 份架构文档升级至 v0.4.0
- [x] 一鸡多吃：6 篇对外分享文章完成（项目缘起、框架设计、阶段复盘、ADR-007/009、旧架构合并）
- [x] share-context Skill v1.0 创建
- [x] Phase 1 → DONE 100%，Phase 2 启动
- [x] Dev AI 工作台初始化（8 个 task）
- [x] `shared/temp/` 旧架构参考文件删除
### 架构方向审视（蜂群调研）
- [x] 调研 2025-2026 年业界多 Agent 架构实践（MegaAgent、Claude Code Agent Swarm、Devin、JiuwenSwarm 等）
- [x] ADR-011: 不急于引入多 Agent 编排层，先精简后分层
- [x] 澄清实际三平台配置：Arch (Claude Code + DeepSeek V4 Pro) / Coder (Trae CN + GLM-4.6) / Tester (Coze CN)
- [x] ADR-012: 跨平台「高模型指挥小模型」协作架构（修正 ADR-011）
- [x] L-002 ~ L-004、P-004 ~ P-005 写入 knowledge/
- [x] share-context Skill v1.1 — 新增 Step 0「反向检查」补知识摄入端
### 信息架构升级（三层四角色控制面板）
- [x] `dashboard.md` — 合并 DASHBOARD + ROADMAP + task 状态面板 + ADR 摘要索引
- [x] `DECISIONS.md` — 人类决策入口
- [x] `.ai/tasks/` — Coder 模板 + 8 个 task 文件 + Tester 模板 + 6 个 task 文件
- [x] 三个角色 card.md 更新（新启动流程 + 新入口引用）
- [x] AGENTS.md + roles/README.md 更新
- [x] 8 个旧文件归档至 `.ai/archive/`
- [x] 人类确认 D-001（选 A — 立即落地新架构）
### 上下文管理规则
- [x] `.ai/principles.md` 新增「Arch AI 上下文资源管理」硬约束
- [x] L-005: 上下文窗口是硬约束——盲目冲刺 = 带残缺记忆做决策
### 模板机制重构（ADR-013）
- [x] 废弃 ADR-008 的「双分支 + shell 脚本」方案
- [x] ADR-013: Skill 替代脚本——project-init Skill 按需执行脱敏/初始化
- [x] 保留 SYNC.md（更新为新架构）、保留 TEMPLATE.yaml（变量定义）
- [x] 新增 project-init Skill（export + init 双模式）
- [x] L-006: 当 AI 是执行者时，Skill 优于 Shell 脚本
- [x] 废弃 sync-template.sh、init.sh、ai_project 分支
### 知识库变更汇总
| 文件 | 新增 |
|------|------|
| decisions.md | ADR-011, ADR-012 |
| lessons.md | L-002, L-003, L-004, L-005 |
| patterns.md | P-004, P-005 |
## 关键决策
- **ADR-012 生效**：三平台四角色架构，Git 是唯一集成总线，task 文件自包含
- **信息架构从「内部备忘录」重定位为「跨平台交接协议」**
- **取消 ADR-011 的精简计划**：文档不能砍，因为它是平台间的唯一通信协议
- **Arch AI 上下文管理作为硬约束写入原则**
## 项目状态
Phase 2 就绪。14 个 task 文件待 Coder/Tester AI 领用。无阻塞。
## 明天
Phase 2 编码启动。Coder AI (Trae + GLM-4.6) 从 P01-001 (DB Schema) 开始。
.ai/knowledge/lessons.md
+1 -99
View File
@@ -10,102 +10,4 @@
---
## L-001: 单体 AGENTS.md 浪费 AI 上下文
**日期**: 2026-05-25
**上下文**: 项目启动阶段，每次 AI 会话都需要读 AGENTS.md 来了解角色和权限
**问题**: AGENTS.md 239 行，约 80% 内容与当前 AI 角色无关。AI 有效上下文被大量无关信息占据
**教训**: 为人类设计的文档结构不适用于 AI 的信息获取模式。AI 需要"最少必要信息"，而不是"全局完整视图"
**行动**: 重构为分层信息架构：角色工作台 → 阶段上下文 → 知识沉淀。AI 只需读 2 个小文件即可开工
---
## L-002: 角色边界划分是 AI Agent 协作的反模式
**日期**: 2026-05-26
**上下文**: Phase 1 收尾后，重新审视「1 人 + 3 AI」的 Arch/Dev/QA 角色划分架构。调研了 2025-2026 年业界最新实践（MegaAgent、Claude Code Agent Swarm、Devin、JiuwenSwarm、Microsoft 多 Agent 参考架构等）
**问题**:
- 按角色边界（Arch/Dev/QA）划分 Agent 导致协调成本急剧上升，Token 消耗是单体的 3-10 倍
- Arch AI 承担了过多职责：架构设计 + 任务分配 + 文档维护 + 看板更新，成为单点瓶颈
- `.ai/` 目录膨胀到 47 个文件，但 Phase 2 代码一行还没写——架构本身成了负担
- Anthropic 和 Cognition（Devin）都承认：并行 Agent 在编码领域的实际收益有限，隐性决策冲突和整合成本往往超过并行收益
**教训**:
1. **按业务上下文划分，而非按角色划分**。正确的做法是「用户认证流 Agent」拥有路由+数据库+前端组件，「错题录入流 Agent」拥有拍照+图像处理+入库——每个 Agent 拥有完成任务所需的全部上下文
2. **架构规模应与项目阶段匹配**。Phase 1 只有需求+设计，不需要 47 个配置文件。应该在需要时渐进式添加，而非提前搭建「完整」架构
3. **调度层应该是确定性代码，而非 LLM**。用 LLM 做任务路由和状态更新是反模式——不稳定、成本高。这些应该用脚本/CI/工作流引擎实现
4. **子 Agent 的甜蜜点是只读研究，而非并行编码**。隔离上下文中做信息收集然后压缩回传——这是验证最有效的模式
5. **「高模型指挥小模型」的方向是对的，但规模要匹配**。1 人项目的「编排层」就是人类+Claude Code 本身，不需要额外的编排 Agent
**行动**:
- 启动 `.ai/` 配置精简审计，目标砍到 20 个文件以内
- Arch AI 的 today.md 和 queue.md 合并，消除重复
- Phase 3 前评估是否引入正式模型分层（Opus 做判断 → Sonnet/Haiku 做执行）
- 当前阶段保留角色划分但降低形式化程度，实际工作由 Claude Code 子 Agent 机制承载
---
## L-003: 知识库「生产者」流程缺失
**日期**: 2026-05-26
**上下文**: 一次关于 Agent 架构的深度讨论产生了有价值的洞察（L-002 + ADR-011 + P-004），但发现把这些洞察写入知识库的动作没有 formalized 流程
**问题**: `share-context` Skill 覆盖了知识库的「消费者」侧（.ai/knowledge/ → docs/share/），但「生产者」侧（开发讨论 → .ai/knowledge/）是断的。有价值的想法和教训可能因为没人记得写而丢失
**教训**: 一条完整的信息流水线需要两端都 formalized：摄入端（什么时候写、写到哪里、怎么写）和输出端（什么时候翻译、翻译成什么）。目前只有输出端
**行动**:
- 更新 `share-context` Skill，增加「反向检查」步骤：每次执行时先检查是否有未入库的讨论/想法
- 建立触发条件：当讨论产生「可复用的判断」「反直觉的发现」「被验证的错误方向」时，主动记录
---
## L-005: Arch AI 上下文窗口是硬约束——盲目冲刺 = 带残缺记忆做决策
**日期**: 2026-05-26
**上下文**: 持续数小时的高强度架构讨论（ADR-011、ADR-012、信息架构升级），Arch AI 的上下文窗口承载了全部对话历史
**问题**: 复杂任务容易让人想「一口气做完」，但 Arch AI 的上下文窗口有限。做一半触发自动压缩 → 前面的讨论、决策细节、已排除的选项全部丢失 → 后续判断基于不完整记忆 → 决策质量崩盘
**教训**:
1. **上下文不是无限的**。每次对话都是消耗品，越长的讨论越容易触发压缩
2. **决策即记录**。每个判断产生后立即写入 knowledge/，不留在对话里。对话是易失的，文件是持久的
3. **主动 checkpoint 优于被动压缩**。感觉吃力时主动收尾（commit + push），开新会话继续——带着干净记忆比带着残缺记忆强
4. **拆分到可提交粒度**。大任务拆成独立子任务，每个子任务结束后 commit。即使后续会话压缩，已完成的部分已经落地
**行动**:
- 写入 `.ai/principles.md` 作为 Arch AI 硬约束
- 任务前评估上下文余量
- 接近窗口上限时执行主动收尾协议：已完成 → commit → 告知人类进展 → 建议开新会话
---
## L-006: 当 AI 是执行者时，Skill 优于 Shell 脚本
**日期**: 2026-05-26
**上下文**: ADR-008 的「双分支 + sync-template.sh」模板同步方案，在新架构升级后 ai_project 分支严重过时。用户要求把脱敏模板价值提取到 main，放弃独立分支
**问题**:
- `sync-template.sh` 硬编码了旧架构的文件列表（DASHBOARD.md / ROADMAP.md / today.md / queue.md），框架一升级脚本就过时
- 维护一个独立 Git 分支的成本 > 收益：需要手动切换分支、跑脚本、处理冲突
- Shell 脚本的设计假设是「人类或 CI 执行」，但实际场景是 AI 执行。AI 不需要可执行脚本——AI 需要清晰的规格
**教训**:
1. **「用什么执行」决定「用什么描述」**。人/CI 执行 → 写脚本。AI 执行 → 写 Skill（语义描述 + 约束 + 边界定义）。Skill 描述「方法」，不会因文件路径变化而过时
2. **边界定义文件是长期资产，执行脚本是短期负债**。SYNC.md 定义了什么属于框架、什么属于项目——这个定义独立于任何执行方式。脚本绑定了执行方式，框架一变就废
3. **让 Git 做版本管理，让 Skill 做逻辑执行**。不需要为「脱敏」这个逻辑维护一个独立分支，Skill 从当前 main 实时执行脱敏，永远不过时
4. **3 文件 > 4 文件 + 1 分支**。新方案：SYNC.md + TEMPLATE.yaml + Skill。旧方案：SYNC.md + TEMPLATE.yaml + sync-template.sh + init.sh + ai_project 分支
**行动**:
- ADR-008 标记废弃，新增 ADR-013
- 废弃 sync-template.sh、init.sh、ai_project 分支
- 保留并更新 SYNC.md（框架/项目边界），新增 TEMPLATE.yaml（变量定义），新增 project-init Skill
---
## L-004: 跨平台 AI 协作下，文档是唯一的通信协议
**日期**: 2026-05-26
**上下文**: 澄清了实际的三平台配置——Arch AI (Claude Code + DeepSeek V4 Pro)、Coder AI (Trae CN + GLM-4.6)、Tester AI (Coze CN)。之前的设计假设所有角色在同一个 AI 平台内切换，这一假设被推翻
**问题**:
- 之前的架构分析得出了「精简文档」的结论（ADR-011），但这个结论基于错误的前提——以为所有 AI 共享同一个上下文空间
- 实际场景中，三个平台的 AI 之间**零共享上下文**。Trae + GLM-4.6 不会知道 Claude Code 里讨论了什么，Coze 沙盒不会知道架构设计的动机
- 如果把文档精简了，Coder AI 拿到的 task 就会缺失关键上下文，GLM-4.6 又没有能力自行推断
**教训**:
1. **架构结论绑定于部署拓扑**。同一个设计，在「单平台多角色切换」和「跨平台多 Agent 协作」下是完全不同的东西。先搞清楚运行环境，再做架构决策
2. **跨平台协作中，Git 仓库不是存储，是通信介质**。每个 commit 是一次消息传递，每个文件是一份消息体。消息必须自包含，接收方不能依赖「上次聊过」
3. **任务交接密度必须适配接收方模型能力**。GLM-4.6 不是 Claude——不能给一个需要跨 5 个文件推理的任务。每个 task 应该是单文件或强内聚的 2-3 个文件
4. **低能力模型不是劣势，是约束**。只能处理小范围任务 → 强迫架构设计更清晰 → 反而减少 bug。这就是「限制产生创造力」
**行动**:
- 修正 ADR-011 的结论：不做精简，改为「重定位」——架构文档从内部备忘录升级为跨平台交接协议（ADR-012）
- Task 模板增加四个必填字段：输入、输出、约束、参考 ADR
- Dev queue.md 的每个任务需独立可读，不依赖前后文
（暂无经验教训，项目刚启动。随着 bring-up 推进自动积累。）
.ai/knowledge/patterns.md
+37 -127
View File
@@ -3,140 +3,50 @@
## 目的
记录开发过程中发现的可持续复用的模式和做法。
同样的模式出现 3 次以上时，应当记录在这里。
---
## P-001: AI 任务交接 (review/active/)
## P-001: 测试→LL→HAL 提炼路径
**上下文**: AI 角色之间需要传递工作成果
**问题**: 如何结构化任务交接，让任何 AI 都能接手
**方案**: 标准化 `review/active/{任务ID}/` 结构：
- `task.md` — 任务描述（Arch AI 定义）
- `acceptance.md` — 验收标准（Arch AI + Dev AI + QA AI 共同维护）
- `impact.md` — 变更影响范围（Arch AI + Dev AI 评估）
- `feedback/` — 反馈记录（QA AI 提交）
**上下文**: 每个功能单元从寄存器测试到最终 SDK 驱动的演进
**问题**: 测试代码和 SDK 驱动如何衔接，避免重复劳动
**方案**: 三步提炼路径：
1. **寄存器测试代码** → 直接操作寄存器地址和位域，验证功能正确性
2. **LL 层提炼** → 将测试中的寄存器操作封装为内联函数+宏，零开销
3. **HAL 层封装** → 在 LL 层之上加句柄+状态机+回调，高抽象可移植
**何时用**: 每个跨 AI 角色的任务
**何时不用**: 单角色任务（如纯文档更新、配置修改）
**关键约束**: 测试代码必须结构化（用宏封装寄存器操作，不用硬编码地址），否则提炼成本极高
**何时用**: 每个功能单元完成后
**何时不用**: 纯软件功能（无寄存器操作）
---
## P-002: 角色工作台 (daily task board)
## P-002: 勘误驱动规避
**上下文**: 芯片 bring-up 中发现的硅缺陷
**问题**: 如何让 SDK 驱动自动规避已知勘误
**方案**:
1. 勘误记录在 Test/errata/ 中，结构化格式（影响外设、触发条件、规避方法）
2. LL 层代码中在受影响操作处加 workaround 注释
3. HAL 层代码中自动执行规避逻辑（对调用方透明）
**何时用**: 发现勘误后立即记录，LL/HAL 代码同步更新
**何时不用**: 确认无硅缺陷的功能
---
## P-003: 跨 AI 上下文交接
**上下文**: 不同 AI 可能在不同时间、不同平台介入同一项目
**问题**: 如何确保任何 AI 随时能接手
**方案**:
1. AGENTS.md 是通用上下文锚点
2. dashboard.md 记录当前状态，任何 AI 读到即知全貌
3. task 文件自包含（输入/输出/约束/验收），不依赖对话历史
4. Git commit 记录所有变更，Git 是唯一的历史来源
**核心原则**: 对话是易失的，文件是持久的。每个判断产生后立即写入文件。
**上下文**: AI 每次会话需要快速进入工作状态
**问题**: 从头探索项目结构浪费时间
**方案**: `.ai/roles/{role}/today.md` 每日任务清单，AI 只需读 2 个文件（card + today）
**何时用**: 每次 AI 会话
**维护者**: Arch AI 负责分配，各 AI 自己更新完成状态
---
---
## P-003: 模板同步 (framework sync)
**上下文**: 项目框架层（AGENTS/权限/提示词/工作流）的变化需要传播到通用模板分支
**问题**: 手动同步耗时且容易遗漏，AI 重做去敏化消耗 ~100K tokens
**方案**:
- 双分支：`main`（具体项目）+ `ai_project`（通用模板）
- `SYNC.md` 明确定义框架层/项目层文件边界
- `sync-template.sh` 自动 checkout 框架文件 + 重新应用 {{变量}}
- 框架层 ~15 个文件自动同步，project 层永久隔离
**何时用**: main 分支框架有变化时
**维护者**: Arch AI 触发，脚本执行
---
## P-004: 编排器-执行者模式 (Orchestrator-Worker)
**上下文**: AI Agent 协作中，不同任务需要不同能力的模型。高能力模型（Opus）做规划和判断，低成本模型（Sonnet/Haiku）做执行
**来源**: MegaAgent (NUS)、Claude Code Agent Swarm (Anthropic)、JiuwenSwarm (华为 openJiuwen)、Microsoft 多 Agent 参考架构
**方案**:
```
决策层 (Opus) → 意图理解、方案设计、最终验收 (~10% Token, 最贵)
调度层 (代码) → 任务路由、负载均衡、重试熔断 (确定性代码, 不用 LLM!)
执行层 (Haiku) → 专注单一原子任务 (~60% Token, 最便宜)
```
**核心原则**:
1. 按业务上下文划分 Agent（「认证流 Agent」），而非按角色（「数据库 Agent」）
2. 调度层是确定性代码——用 LLM 做调度是反模式
3. 子 Agent 的甜蜜点是只读研究/探索，并行编码效果不佳
4. 写范围严格分离——并发写任务之间不能有重叠的文件所有权
5. Agent 粒度围绕内聚能力组织——不要为「调用一个 API」建 Agent
**何时用**:
- 团队规模 ≥ 3 个 AI Agent 并行工作
- 任务可清晰分解为独立子任务，且协调成本 < 并行收益
- 有明确的模型成本优化需求
**何时不用**:
- 1 人项目——编排层就是人类 + Claude Code 本身
- 编码任务的并行化——行业共识是效果不佳
- 简单 bug 修复——分解成本 > 直接修复成本
**本项目实例** (ErrLens):
```
Arch AI: Claude Code + DeepSeek V4 Pro → 架构推理、方案设计、任务分解
Coder AI: Trae CN + GLM-4.6 → 代码生成、文件操作（单文件粒度）
Tester AI: Coze CN → 沙盒执行、自动化测试报告
通信介质: Git 仓库（唯一集成总线）
交接粒度: 单次 commit = 一个交接单元
```
**关键适配**:
- Coder AI 用的是 GLM-4.6，不能假设它有跨文件推理能力 → task 分解到单文件粒度
- 跨模块协调在 Arch AI 设计阶段完成，不在 Coder AI 执行阶段
- Tester AI 的 Coze 沙盒做真正的自动化闭环——不只是跑测试，是拉代码 → 执行 → 生成报告 → commit
---
## P-005: 跨平台任务交接协议 (Cross-Platform Task Handoff)
**上下文**: 多个 AI Agent 运行在不同平台/IDE 上，零共享上下文，Git 是唯一通信介质
**问题**: 如何让 Trae + GLM-4.6 拿到 task 后能直接开工，不需要追问「这个是什么意思」
**方案**: 每个 task 必须自包含，包含四个必填字段：
```markdown
## Task: {编号} {标题}
### 输入
- 读哪些文件（完整路径）
- 参考哪些 ADR（ADR-XXX）
- 依赖哪些上游任务（P01-XXX，已完成/产出是 X）
### 输出
- 生成/修改哪些文件（完整路径）
- 输出格式（代码/文档/配置）
- 验收方式（跑什么命令看什么结果）
### 约束
- 不碰哪些目录
- 用什么库/版本
- 遵循什么规范（code-style.md / doc-template.md）
### 参考
- ADR-XXX: 一句话说明关联性
- 相关文件: 一行说明
```
**核心原则**:
1. **零隐含上下文**：接收方不能依赖「上次聊过」，所有信息必须显式写在 task 里
2. **适配接收方能力**：给 GLM-4.6 的任务粒度 = 单文件；给 Claude 的任务可以跨 3-5 个文件
3. **Git commit 即消息**：每次 commit 是发送一次消息，接收方 pull 即收到
4. **任务与代码分离**：task 定义在 `.ai/roles/{role}/queue.md`，代码在 `projects/`，通过 Git 同步
**何时用**: 跨平台/跨模型协作
**何时不用**: 同一平台内的角色切换（直接对话即可）
---
## 反模式（避免）
- 在多个文件中重复同一状态信息 → 只在 ROADMAP.md 记录
- 决策讨论散落在任务 feedback 中 → 提炼到 knowledge/decisions.md
- 大段文档内联而非链接 → 用链接 + 一句话摘要
**何时不用**: 无（这是基础模式，始终适用）
.ai/phases/INDEX.md
+20 -10
View File
@@ -1,17 +1,27 @@
# 阶段索引
| 阶段 | 名称 | 状态 | 目录 |
|------|------|------|------|
| 1 | 基础搭建 | DONE | `phase-01-foundation/` |
| 2 | MVP | ACTIVE | `phase-02-mvp/` |
| 3 | 功能完善 | PLANNED | `phase-03-features/` |
| 4 | 打磨发布 | PLANNED | `phase-04-polish/` |
| 阶段 | 名称 | 功能单元 | 状态 | 目录 |
|------|------|---------|------|------|
| P0 | 基础 bring-up | 电源管理/时钟/NRST复位/GPIO/JTAG_SWD | PLANNED | — |
| P1 | 基本通信 | USART/SPI/I2C | PLANNED | — |
| P2 | 模拟链路 | ADC/DAC/比较器/VREFBUF/温度/参考电压/Scaler启动时间 | PLANNED | — |
| P3 | 定时器类 | Timer/HRTIM/LPTIM/看门狗 | PLANNED | — |
| P4 | 存储搬运 | FMC/QSPI/SDMMC/DMA/DLYB | PLANNED | — |
| P5 | 高速接口 | USB/以太网/SAI/ULPI | PLANNED | — |
| P6 | 杂项 | 电压监控/模拟开关升压/升压器/CRC/电流特性 | PLANNED | — |
## 阶段执行原则
1. **P0必须先完成** — 芯片能跑起来才能测其他
2. **P1在P0完成后启动** — 需要调试输出和通信通道
3. **P2-P6可按需并行** — 依赖P1但不互锁
4. **SDK随阶段推进** — 每个阶段完成后提炼LL/HAL层
## 阶段切换规则
1. 当前阶段 completion.md 全部打勾
1. 当前阶段所有功能单元测试通过（或勘误已记录）
2. 人类签字确认
3. Arch AI 更新本索引文件
4. Arch AI 更新所有角色 card.md（当前阶段字段）
5. Arch AI 更新 dashboard.md（进度条 + task 状态面板 + 最近事件）
6. 产出阶段复盘（docs/share/phase-NN/）
4. Arch AI 更新 dashboard.md（进度条 + task 状态面板 + 最近事件）
5. Arch AI 更新 Worker card.md（当前阶段字段）
6. 产出阶段完成总结
.ai/phases/phase-01-foundation/architecture.md
-45
View File
@@ -1,45 +0,0 @@
# Phase 1: 基础搭建 — 架构概览
## 技术栈
| 层 | 技术 | 说明 |
|----|------|------|
| 前端 (P01) | Taro 4 + React 18 + TypeScript + Tailwind CSS | 跨端小程序 |
| 后端 (P01) | NestJS 10 + TypeScript | REST API |
| 数据库 | PostgreSQL（Schema 本阶段确定） | 关系型存储 |
| 包管理 | pnpm | monorepo |
| 测试 | Jest | 单元 + 集成 + E2E |
| AI 训练 (P02) | Python + PyTorch | 延期至 Phase 2 |
| Web 后台 (P03) | Next.js | 延期至 Phase 2 |
## 当前架构快照
```
P01_errlens_app/
src/ # Taro 小程序源码（已有骨架）
pages/index/ # 首页（通用模板，待替换为错题本首页）
components/ui/ # shadcn/ui Taro 组件库（~50个组件）
lib/ # 工具函数（cn, platform, measure, hooks）
presets/ # H5 适配（navbar, error boundary, styles）
server/ # NestJS 后端
src/
main.ts # 启动入口
app.module.ts # 根模块
app.controller.ts # GET /hello, GET /health
tests/ # Jest 测试（已有 utils 测试骨架）
P02_errlens_training/ # 空壳，Phase 2 启动
P03_errlens_web/ # 空壳，Phase 2 启动
```
## 关键约束
- 所有业务代码在 projects/*/src/（权限边界）
- 跨平台目标：微信小程序优先，抖音/H5 为次
- AI 代码必须遵循 `.ai/prompts/coding/code-style.md`
## 待定问题
- 数据库 Schema 设计（PRD 先行）
- P01 页面架构（几个页面、导航结构）
- 后端 API 版本策略
.ai/phases/phase-01-foundation/completion.md
-16
View File
@@ -1,16 +0,0 @@
# Phase 1: 基础搭建 — 完成检查清单
## 完成状态
- [ ] 所有 goal.md 中的成功标准达成
- [ ] 所有活跃任务处于 DONE 或 ARCHIVED
- [ ] QA AI 签字确认
- [ ] 人类签字确认
- [ ] 知识已沉淀至 .ai/knowledge/
- [ ] Phase 2 MVP 计划已起草
- [ ] 阶段复盘已写出（docs/share/phase-01/）
- [ ] Token 预算审计通过
## 阶段交接
*（阶段接近完成时填写）*
.ai/phases/phase-01-foundation/decisions.md
-27
View File
@@ -1,27 +0,0 @@
# Phase 1: 基础搭建 — 阶段决策
本文件记录在 Phase 1 执行过程中产生的决策（区别于全局 ADR）。
## D-001: 信息架构分层设计
- 日期: 2026-05-25
- 状态: 已采纳
- 决策: 采用 token 预算的分层架构（工作台 → 阶段 → 知识 → 分享）
- 理由: AI 上下文窗口有限，旧 AGENTS.md 单体文件浪费 token
- 影响: 所有 AI 从 `.ai/roles/{role}/` 启动，不再从 AGENTS.md 启动
## D-002: 阶段化上下文加载
- 日期: 2026-05-25
- 状态: 已采纳
- 决策: AI 只加载当前 Phase 的上下文，不加载所有历史
- 理由: 未来阶段技术栈和侧重点可能不同，历史信息反而干扰
- 影响: 阶段包必须自包含、可独立阅读
## D-003: 角色工作台代替全局入口
- 日期: 2026-05-25
- 状态: 已采纳
- 决策: 用 `today.md` + `queue.md` 替代从 AGENTS.md 找任务
- 理由: AI 不需要理解整个项目结构，只需要知道自己该干什么
- 影响: Arch AI 负责维护各角色的任务分配
.ai/phases/phase-01-foundation/goal.md
-27
View File
@@ -1,27 +0,0 @@
# Phase 1: 基础搭建 — 目标
## 阶段目标
建立完整的开发骨架：
- 可运转的"1 人 + 3 AI"协作框架
- 完整的目录和权限体系
- 可运行的项目脚手架（Taro + React + NestJS）
- 测试基础设施
- 信息架构设计（分层 AI 上下文）
## 成功标准
- [ ] 3 个 AI 角色能独立通过工作台启动工作
- [ ] P01 可通过 `pnpm dev` 启动并显示首页
- [ ] 测试可通过 `pnpm test` 运行并产出报告
- [ ] 所有初始 review/ 任务处于 DONE 或 ARCHIVED
- [ ] 共享工具库可工作并通过测试
- [ ] 信息架构重构完成
## 阶段 Owner
Arch AI 协调，Dev AI 实现，QA AI 验证，人类最终验收。
## 下一阶段
Phase 2: MVP — 实现错题本核心功能
.ai/phases/phase-01-foundation/scope.md
-42
View File
@@ -1,42 +0,0 @@
# Phase 1: 基础搭建 — 范围
## 范围内
### 协作框架
- AGENTS.md（AI 角色 + 权限 + 工作流）
- .ai/config/（JSON 角色配置）
- .ai/prompts/（编码、测试、架构提示词模板）
- .ai/roles/（AI 角色工作台）
- .ai/phases/（阶段上下文）
- review/（任务交接中心）
### P01_errlens_app（主应用）
- Taro 4 + React 18 脚手架，集成 shadcn/ui
- NestJS 后端脚手架
- 可运行的开发服务器（pnpm dev）
- 基础页面路由
### 测试基础设施
- Jest 配置
- 示例单元测试
- 测试结果报告流程
### 文档体系
- 阶段追踪文档
- 知识库基础
- 人类仪表盘
- 分享内容层
## 范围外（延期至 Phase 2+）
- 实际业务功能（登录、错题分析等）
- P02 数据训练实现
- P03 Web 后台实现
- CI/CD 流水线配置
- 生产部署
## 项目依赖
- P01 独立（可独立开发）
- P02 依赖 P01 定义数据 Schema（Phase 2）
- P03 依赖 P01 API 稳定（Phase 3）
.ai/phases/phase-02-mvp/architecture.md
-3
View File
@@ -1,3 +0,0 @@
# Phase 2: MVP — 架构决策
*（Phase 2 执行过程中由 Arch AI 填写）*
.ai/phases/phase-02-mvp/completion.md
-3
View File
@@ -1,3 +0,0 @@
# Phase 2: MVP — 完成检查清单
*（Phase 2 接近完成时更新）*
.ai/phases/phase-02-mvp/decisions.md
-3
View File
@@ -1,3 +0,0 @@
# Phase 2: MVP — 阶段决策
*（Phase 2 执行过程中由 Arch AI 填写）*
.ai/phases/phase-02-mvp/goal.md
-11
View File
@@ -1,11 +0,0 @@
# Phase 2: MVP — 目标
*（Phase 1 完成时由 Arch AI 填写）*
## 阶段目标
## 成功标准
## 阶段 Owner
## 下一阶段
.ai/phases/phase-02-mvp/scope.md
-3
View File
@@ -1,3 +0,0 @@
# Phase 2: MVP — 范围
*（Phase 1 完成时由 Arch AI 填写）*
.ai/phases/phase-03-features/architecture.md
-3
View File
@@ -1,3 +0,0 @@
# Phase 3: 功能完善 — 架构决策
*（Phase 3 执行过程中由 Arch AI 填写）*
.ai/phases/phase-03-features/completion.md
-3
View File
@@ -1,3 +0,0 @@
# Phase 3: 功能完善 — 完成检查清单
*（Phase 3 接近完成时更新）*
.ai/phases/phase-03-features/decisions.md
-3
View File
@@ -1,3 +0,0 @@
# Phase 3: 功能完善 — 阶段决策
*（Phase 3 执行过程中由 Arch AI 填写）*
.ai/phases/phase-03-features/goal.md
-3
View File
@@ -1,3 +0,0 @@
# Phase 3: 功能完善 — 目标
*（Phase 2 完成时由 Arch AI 填写）*
.ai/phases/phase-03-features/scope.md
-3
View File
@@ -1,3 +0,0 @@
# Phase 3: 功能完善 — 范围
*（Phase 2 完成时由 Arch AI 填写）*
.ai/phases/phase-04-polish/architecture.md
-3
View File
@@ -1,3 +0,0 @@
# Phase 4: 打磨发布 — 架构决策
*（Phase 4 执行过程中由 Arch AI 填写）*
.ai/phases/phase-04-polish/completion.md
-3
View File
@@ -1,3 +0,0 @@
# Phase 4: 打磨发布 — 完成检查清单
*（Phase 4 接近完成时更新）*
.ai/phases/phase-04-polish/decisions.md
-3
View File
@@ -1,3 +0,0 @@
# Phase 4: 打磨发布 — 阶段决策
*（Phase 4 执行过程中由 Arch AI 填写）*
.ai/phases/phase-04-polish/goal.md
-3
View File
@@ -1,3 +0,0 @@
# Phase 4: 打磨发布 — 目标
*（Phase 3 完成时由 Arch AI 填写）*
.ai/phases/phase-04-polish/scope.md
-3
View File
@@ -1,3 +0,0 @@
# Phase 4: 打磨发布 — 范围
*（Phase 3 完成时由 Arch AI 填写）*
.ai/principles.md
+9 -23
View File
@@ -9,16 +9,16 @@ AI 的上下文窗口有限。每个读入上下文的字都是成本。这套
| 层级 | 预算 | 内容 | 加载时机 |
|------|------|------|----------|
| 入口（dashboard/card） | < 2K | 身份+全貌+任务 | 每次会话必读 |
| Task 文件 | < 1K | 单任务全部信息 | Coder/Tester 开工时 |
| Task 文件 | < 1K | 单任务全部信息 | Worker 开工时 |
| 知识沉淀 (knowledge) | < 3K | 决策/模式/教训 | 按需加载 |
| 阶段上下文 (phase) | < 5K | 目标+范围+架构 | 按需加载 |
## 信息分层（三层架构）
## 信息分层
```
指挥层: dashboard.md → 人类 + Arch AI 唯一入口
决策层: DECISIONS.md → 待人类决策事项
执行层: .ai/tasks/active/ → Coder/Tester 各自 task 文件
执行层: .ai/tasks/active/ → Worker 各自 task 文件
```
## 维护规则
@@ -43,13 +43,12 @@ AI 的上下文窗口有限。每个读入上下文的字都是成本。这套
4. **接近窗口上限时主动收尾**：感觉上下文开始吃力时，主动 checkpoint——已完成写入文件、commit、告知人类当前进展和下一步。**宁可多开一个会话，不要带着残缺记忆继续**
5. **拆分到可提交粒度**：大任务拆成独立子任务。每个子任务结束后 git commit，确保即使后续会话压缩，已完成的部分不会丢失
### 角色特定约束
### 嵌入式项目特有约束
| 角色 | 主要风险 | 应对策略 |
|------|---------|---------|
| Arch AI (Claude Code) | 长对话积累上下文，架构讨论容易收不住 | 每个 ADR 产出后立即写入 decisions.md；感知吃力时主动收尾 |
| Coder AI (Trae + GLM-4.6) | 上下文窗口更小，多文件任务容易超出 | 每个 session 只做 1 个 task 文件；不读其他 task，不读架构文档 |
| Tester AI (Coze CN) | 沙盒执行时间有限 | 1 个 session 只测 1 个 T01-XXX task；报告立即写回 repo |
| Arch AI | 架构讨论容易收不住，寄存器细节容易混淆 | 每个 ADR 产出后立即写入 decisions.md；寄存器定义以 SVD 为准，不靠记忆 |
| Worker AI | 单个外设测试代码可能涉及大量寄存器位域 | 每个 session 只做 1 个 task；测试代码按功能单元独立，不跨单元引用 |
### 信号识别（何时应立即执行规则 4）
@@ -57,35 +56,22 @@ AI 的上下文窗口有限。每个读入上下文的字都是成本。这套
- 开始忘记用户几分钟前说过的话
- 回复质量出现可感知的下降
- 同一个问题被重复提出
- （Coder AI）需要同时修改 3 个以上文件才能完成 task
- 需要同时修改 3 个以上文件才能完成 task
### 反模式
- 「一口气做完再 commit」——做一半触发压缩，前面做的全丢
- 「这个 task 简单，我顺便把下一个也做了」——超边界 = 超上下文
- 「先放着，等会儿一起处理」——对话不等人，放着 = 丢了
- 「凭记忆写寄存器地址」——嵌入式寄存器地址必须从 SVD/头文件获取，不能靠回忆
---
## 文件约定
- 控制面板: `dashboard.md`
- 决策入口: `DECISIONS.md`
- 角色工作台: `.ai/roles/{role}/card.md`
- 执行任务: `.ai/tasks/active/`
- 阶段上下文: `.ai/phases/phase-NN-name/`
- 知识沉淀: `.ai/knowledge/`
- 提示词模板: `.ai/prompts/{domain}/`
- Skill 工具: `.trae/skills/`
- 框架边界: `SYNC.md`
- 模板变量: `TEMPLATE.yaml`
## 阶段切换检查清单
切换阶段时 Arch AI 必须：
- [ ] 更新所有角色的 card.md（当前阶段字段）
- [ ] 更新 dashboard.md（进度条 + task 状态面板 + 最近事件）
- [ ] 更新 phases/INDEX.md
- [ ] 生成上一阶段的 completion.md
- [ ] 产出阶段复盘（docs/share/phase-NN/）
- [ ] 产出上一阶段的 completion.md
- [ ] 审计 token 预算
.ai/prompts/architecture/README.md
-6
View File
@@ -1,6 +0,0 @@
# Arch AI 提示词库
| 文件 | 说明 |
|------|------|
| [architecture-design.md](architecture-design.md) | 测试架构设计模板与规范 |
| [compiler-config.md](compiler-config.md) | 编译器配置模板 |
.ai/prompts/architecture/architecture-design.md
-81
View File
@@ -1,81 +0,0 @@
# Arch AI 测试架构设计模板
## 1. 芯片功能分析
```markdown
### 芯片规格
- 型号: 类似 STM32H757 的 MCU
- 核心: Cortex-M7
- 频率: 400MHz
- 外设: GPIO, UART, SPI, I2C, Timer, DMA, 等
```
## 2. 测试方案
```markdown
### 测试策略
- 单元测试: 外设功能验证
- 集成测试: 多外设协同工作
- 性能测试: 响应时间、吞吐量
### 编译器选择
- Arm Clang: 高性能优化
- Keil MDK: 工业级验证
- Arm GCC: 开源生态
```
## 3. JTAG调试流程
```markdown
### 调试步骤
1. 准备固件: 编译 .hex / .elf
2. 连接硬件: JTAG/SWD 接口
3. 下载固件: OpenOCD / pyOCD
4. 运行调试: 断点、单步
5. 串口监控: 查看日志输出
```
## 4. impact.md 模板
```markdown
# {TASK_ID} - 变更影响范围
## 修改的文件
| 文件路径 | 修改类型 | 影响等级 |
|---------|---------|---------|
| projects/P01_chip_test/src/gpio_test.c | 新增 | HIGH |
| docs/02_测试架构/jtag_flow.md | 更新 | MEDIUM |
## 影响的功能模块
- [x] GPIO 功能测试
- [ ] 其他外设（无影响）
## 需要回归测试的场景
- 场景1: GPIO 输入输出功能
- 场景2: 中断触发和响应
## 环境依赖变更
- 编译器: 使用 Arm GCC 12.x
- 调试工具: pyOCD 0.30.x
```
## 5. acceptance.md 模板
```markdown
# {TASK_ID} - 验收标准
## 功能验收
- [x] GPIO 高低电平输出正常
- [x] 按键输入中断响应正确
- [x] 串口日志输出正常
## 非功能验收
- [x] 编译通过无警告
- [x] 下载一次成功
- [x] 运行稳定无崩溃
## 验收通过条件
- 所有功能点验证通过
- 三个编译器测试都通过
- 测试报告完整
```
.ai/prompts/architecture/technical-evaluation.md
-41
View File
@@ -1,41 +0,0 @@
# 技术选型评估模板
## 输入
- 需要解决的技术问题
- 约束条件（预算、时间、团队、已有技术栈）
## 输出结构
### 1. 需求描述
- 要解决什么问题
- 关键约束是什么
### 2. 候选方案（2-4 个）
每个方案描述：
- 方案名称和简介
- 优势（3-5 条）
- 劣势（3-5 条）
- 与本项目技术栈的兼容度
### 3. 评估维度
| 维度 | 权重 | 方案A | 方案B | 方案C |
|------|------|-------|-------|-------|
| 性能 | 30% | — | — | — |
| 生态成熟度 | 25% | — | — | — |
| 学习曲线 | 20% | — | — | — |
| 社区活跃度 | 15% | — | — | — |
| 团队熟悉度 | 10% | — | — | — |
| **加权总分** | 100% | — | — | — |
### 4. 推荐方案
- 推荐哪个、为什么
- 主要风险
- 如果失败，备选方案是什么
## 注意事项
- 评估维度可调整，但必须说明理由
- 不追求"最优"，追求"最适合当前阶段"
.ai/prompts/coding/README.md
-6
View File
@@ -1,6 +0,0 @@
# Dev AI 提示词库
| 文件 | 说明 |
|------|------|
| [code-style.md](code-style.md) | 代码风格、命名规范、目录组织 |
| [doc-template.md](doc-template.md) | impact.md / acceptance.md 等文档模板 |
.ai/prompts/coding/code-style.md
-105
View File
@@ -1,105 +0,0 @@
# Dev AI 代码风格规范
## 适用技术栈
| 层 | 技术 | 语言 |
|-----|------|------|
| 前端 | Taro 4 + React 18 | TypeScript 5.x |
| 样式 | Tailwind CSS 4 | — |
| 后端 | NestJS 10 | TypeScript 5.x |
| 训练 | PyTorch 2.0 | Python 3.10+ |
---
## 1. 文件命名
| 类型 | 规则 | 示例 |
|------|------|------|
| 页面组件 | kebab-case | `error-detail.tsx` |
| UI 组件 | kebab-case | `button.tsx` |
| 工具函数 | kebab-case | `format-date.ts` |
| 类型定义 | kebab-case | `error-entry.d.ts` |
| NestJS 模块 | kebab-case | `auth.module.ts` |
| Python 模块 | snake_case | `data_loader.py` |
## 2. 目录组织（前端）
```
src/
├── pages/{page-name}/ # 页面 —— 一个目录一个页面
│ ├── index.tsx
│ ├── index.config.ts
│ └── index.css
├── components/ # 通用组件
│ └── {component-name}/
│ └── index.tsx
├── lib/ # 工具函数、hooks
├── types/ # 全局类型声明
├── server/ # NestJS 后端
└── config/ # Taro 构建配置
```
## 3. 目录组织（NestJS 后端）
```
src/server/src/
├── modules/{name}/ # 一个模块一个目录
│ ├── {name}.module.ts
│ ├── {name}.controller.ts
│ ├── {name}.service.ts
│ ├── dto/
│ └── entities/
├── common/ # 共享：拦截器、守卫、管道
└── main.ts
```
## 4. 命名风格
**TypeScript：**
- 组件：PascalCase —— `ErrorCard`
- 函数/变量：camelCase —— `getUserProfile`
- 常量：UPPER_SNAKE —— `MAX_PAGE_SIZE`
- 接口/类型：PascalCase —— `ErrorEntry`
**Python：**
- 类：PascalCase —— `DataLoader`
- 函数/变量：snake_case —— `load_dataset`
- 常量：UPPER_SNAKE —— `BATCH_SIZE`
## 5. 导入顺序（TypeScript）
```
1. 第三方库
2. Taro 相关
3. 项目内部（@/ 别名）
4. 相对路径
5. 样式文件
```
示例：
```typescript
import { useState } from 'react';
import Taro from '@tarojs/taro';
import { Button } from '@/components/ui/button';
import { formatDate } from './lib/date';
import './index.css';
```
## 6. 组件规范
- 优先使用函数组件，不用 class 组件
- 一个文件只有一个 export default 组件
- 组件 props 必须声明类型接口
- 跨端兼容：避免使用 `document`、`window`（用 Taro API 代替）
## 7. API 调用规范
- 前端统一使用 `@/network.ts` 中的 `Network.request`，不要直接调用 `Taro.request`
- 后端Controller 只做参数校验和路由，业务逻辑放在 Service
- API 响应统一使用 Envelope 格式 `{ code, msg, data }`
## 8. 不能做的事
- 不要在 `src/` 下写测试文件（测试在 `tests/`）
- 不要引入未经 package.json 声明的依赖
- 不要在组件中硬编码后端地址（用 `PROJECT_DOMAIN` 全局变量）
.ai/prompts/coding/doc-template.md
-76
View File
@@ -1,76 +0,0 @@
# Dev AI 文档模板
下面三个模板用于 Dev AI 在 `review/{task_id}/` 下产出标准化文件。
---
## A. impact.md 模板（变更影响范围）
```markdown
# {TASK_ID} - 变更影响范围
## 修改的文件
| 文件路径 | 修改类型 | 影响等级 |
|---------|---------|---------|
| projects/P01_errlens_app/src/server/src/modules/auth/auth.service.ts | 新增 | HIGH |
| projects/P01_errlens_app/src/server/src/modules/auth/dto/login.dto.ts | 新增 | MEDIUM |
> 影响等级：HIGH=核心逻辑变更 | MEDIUM=新增文件 | LOW=注释/格式
## 影响的功能模块
- [x] 用户认证模块
- [ ] 错题管理模块（无影响）
## 需要回归测试的场景
- 场景1: 用户登录成功流程
- 场景2: 密码错误返回 401
- 场景3: Token 过期后刷新
## 环境依赖变更
- 新增依赖: bcrypt, @nestjs/jwt
- 数据库迁移: 新增 users 表
```
**要点：**
- `修改的文件` 必须使用从仓库根目录开始的完整路径
- 影响等级要实事求是，不要全写 HIGH
- `需要回归测试的场景` 要写**用户视角**的场景，不是代码内部细节
---
## B. acceptance.md 模板（验收标准）
```markdown
# {TASK_ID} - 验收标准
## 功能验收
- [ ] 用户可以注册新账户（邮箱+密码）
- [ ] 密码强度不足时提示明确错误信息
- [ ] 登录成功返回有效 JWT Token
## 非功能验收
- [ ] API 响应时间 < 200ms
- [ ] 密码使用 bcrypt 加密存储
- [ ] JWT Token 有效期 24 小时
## 测试覆盖要求
- 单元测试覆盖率: >= 80%
- 集成测试覆盖率: >= 60%
- E2E 测试场景: >= 3 个
## 验收通过条件
- 所有功能点验证通过
- 测试覆盖率达标
- 无重大安全漏洞
```
**要点：**
- 功能验收用「用户可以…」句式，让 QA AI 和人类都能看懂
- 每个功能点对应 task.md 里的一项交付物
- 非功能验收写具体的可测量指标，不要写「性能好」「代码整洁」
---
## C. 没有 task.md 模板
task.md 由人类负责人创建，Dev AI 只读不写。Dev AI 如需补充技术细节，写在 impact.md 的「技术备注」段落中，不要直接修改 task.md。
.ai/prompts/execution/README.md
-6
View File
@@ -1,6 +0,0 @@
# 执行AI 提示词库
| 文件 | 说明 |
|------|------|
| [firmware-template.md](firmware-template.md) | 测试固件模板与规范 |
| [bug-report.md](bug-report.md) | 测试反馈与问题报告模板 |
.ai/prompts/execution/bug-report.md
-57
View File
@@ -1,57 +0,0 @@
# 执行AI 问题报告模板
## 模板
```markdown
# {TASK_ID} - 第 {N} 轮测试反馈
## 基本信息
- 测试时间: YYYY-MM-DD
- 测试芯片: MCU型号
- 编译器: Arm Clang / Keil MDK / Arm GCC
- 调试工具: pyOCD / OpenOCD
## 测试结果概览
| 指标 | 数值 |
|------|------|
| 编译状态 | ✅通过 / ❌失败 |
| 下载状态 | ✅成功 / ❌失败 |
| 功能测试 | X个通过，Y个失败 |
| 性能指标 | 符合预期 / 需要优化 |
## 问题清单
### 问题 #1: {简短标题}
- **严重程度**: BLOCKER / HIGH / MEDIUM / LOW
- **涉及文件**: `projects/...`（完整路径）
- **复现步骤**:
1. 步骤1
2. 步骤2
- **预期行为**:
- **实际行为**:
- **串口日志**:
```
[输出日志片段]
```
- **建议修复**:
### 问题 #2: ...
（同上格式）
## 改进建议（非阻塞问题）
- 建议1:
- 建议2:
## 下一步
- [ ] 修复问题后进行第 {N+1} 轮测试
- [ ] 如第 3 轮仍有 BLOCKER 或 HIGH 问题，升级给人类负责人
```
## 严重程度定义
| 级别 | 含义 | 举例 |
|------|------|------|
| BLOCKER | 无法下载或运行，测试完全阻塞 | 编译失败，芯片无法启动 |
| HIGH | 主要功能无法正常工作 | GPIO 无响应，串口无输出 |
| MEDIUM | 功能可用但有问题 | 延时不准确，日志乱码 |
| LOW | 不影响功能的小问题 | 代码风格，注释错误 |
.ai/prompts/execution/firmware-template.md
-49
View File
@@ -1,49 +0,0 @@
# 执行AI 测试固件模板
## C语言测试固件示例
```c
#include <stdint.h>
#include <stdio.h>
#define LED_PIN 13
void delay(volatile uint32_t count) {
while (count--);
}
int main(void) {
// 初始化 GPIO
GPIO_Init();
printf("MCU芯片测试开始\n");
while (1) {
// LED 闪烁
GPIO_Toggle(LED_PIN);
printf("LED Toggle\n");
delay(1000000);
}
}
```
## 编译配置 (Makefile)
```makefile
CC = arm-none-eabi-gcc
CFLAGS = -mcpu=cortex-m7 -mthumb -O2
LDFLAGS = -T linker.ld
TARGET = firmware
SRC = main.c
all: $(TARGET).hex
$(TARGET).elf: $(SRC)
$(CC) $(CFLAGS) $(LDFLAGS) $^ -o $@
$(TARGET).hex: $(TARGET).elf
arm-none-eabi-objcopy -O ihex $< $@
clean:
rm -f *.elf *.hex
```
.ai/prompts/testing/README.md
-5
View File
@@ -1,5 +0,0 @@
# QA AI 提示词库
| 文件 | 说明 |
|------|------|
| [bug-report.md](bug-report.md) | 测试反馈 / Bug 报告模板与格式规范 |
.ai/prompts/testing/bug-report.md
-67
View File
@@ -1,67 +0,0 @@
# QA AI Bug 报告模板
以下模板用于 QA AI 在 `review/{task_id}/feedback/round{round}.md` 中提交测试反馈。
---
## 模板
```markdown
# {TASK_ID} - 第 {N} 轮测试反馈
## 基本信息
- 测试时间: YYYY-MM-DD
- 测试项目: P01_errlens_app / P02_errlens_training / P03_errlens_web
- 测试环境: Node 20.x / Python 3.10
## 测试结果概览
| 指标 | 数值 |
|------|------|
| 测试用例总数 | N |
| 通过 | N |
| 失败 | N |
| 跳过 | N |
| 代码覆盖率 | XX% |
## 失败用例清单
### Bug #1: {简短标题}
- **严重程度**: BLOCKER / HIGH / MEDIUM / LOW
- **涉及文件**: `projects/...`（完整路径）
- **测试场景**: 用户登录时输入正确密码
- **预期结果**: 返回 200 和 JWT Token
- **实际结果**: 返回 500 Internal Server Error
- **复现步骤**:
1. POST /api/auth/login
2. body: {"email": "test@example.com", "password": "correct"}
- **建议修复**: 检查 auth.service.ts 第 42 行的异常处理
### Bug #2: ...
（同上格式）
## 改进建议（非 Bug）
- 建议 1: 登录接口缺少限流保护
- 建议 2: 密码重置的邮件模板可以更友好
## 下一步
- [ ] Dev AI 修复上述 Bug 后，QA AI 进行第 {N+1} 轮测试
- [ ] 如第 3 轮仍未通过，升级给人类负责人裁决
```
---
## 严重程度定义
| 级别 | 含义 | 举例 |
|------|------|------|
| BLOCKER | 核心功能不可用，无法继续测试 | 登录接口直接崩溃、数据库连不上 |
| HIGH | 功能逻辑错误，用户无法正常使用 | 登录成功但不返回 Token |
| MEDIUM | 功能可用但与预期有偏差 | 返回的日期格式不对、错误码不对 |
| LOW | 不影响功能的瑕疵 | 提示文案不友好、缺少空值校验 |
## 规则
1. **每轮反馈用新文件**：`round1.md` → `round2.md` → `round3.md`
2. **最多 3 轮**：第 3 轮仍有 BLOCKER/HIGH Bug → 在报告中标注「建议人类负责人介入」
3. **涉及文件必须用完整路径**：从仓库根目录开始，方便 Dev AI 定位
4. **改进建议不要超过 3 条**：聚焦最重要的
.ai/roles/README.md
-57
View File
@@ -1,57 +0,0 @@
# AI 角色工作台
## 三层架构
```
控制面板 (dashboard.md) → 人类 + Arch AI 共享入口，项目唯一真实来源
↓ Arch AI 拆解任务
执行层 (.ai/tasks/active/) → Coder/Tester 各自独立 task 文件，自包含
```
## 四个角色入口
| 角色 | 平台+模型 | 入口 | 读几个文件 |
|------|----------|------|-----------|
| 人类 | — | [dashboard.md](../../dashboard.md) 顶部「人类区」 | 1 |
| Arch AI | Claude Code + DeepSeek V4 Pro | [dashboard.md](../../dashboard.md) 全文 | 1 |
| Coder AI | Trae CN + GLM-4.6 | [card.md](dev/card.md) → 对应 task 文件 | 2 |
| Tester AI | Coze CN | [card.md](qa/card.md) → 对应 task 文件 | 2 |
## 使用方式
**Arch AI**:
```
1. 读 dashboard.md → 了解全貌 + ADR 摘要 + task 状态
2. 需要细节 → 按链接按需加载
3. 人类决策 → 读 DECISIONS.md
4. 拆分新任务 → 按模板写 .ai/tasks/active/P01-XXX.md
5. 完成后 → 更新 dashboard.md task 状态
```
**Coder AI (Trae + GLM-4.6)**:
```
1. 读 card.md → 身份+权限
2. 读对应 task 文件 → 输入/输出/约束/验收方法
3. 写代码
4. 自验 → 填写完成报告 → commit [READY_FOR_TEST]
```
**Tester AI (Coze)**:
```
1. git pull + 读 card.md
2. git log --grep="READY_FOR_TEST" → 找待测 task
3. 读对应 Tester task 文件 → 测试内容/执行方式/报告格式
4. 拉代码 → 沙盒执行 → 生成 JSON 报告
5. commit 报告
```
## 关键原则
1. **每个角色只有一个入口文件** — 不拼图，不切换
2. **Worker AI 不需要知道项目全貌** — task 文件就是它的全部世界
3. **Git 是唯一的集成总线** — 跨平台交接通过 commit message 信号
4. **弱模型适配强约束** — 给 GLM-4.6 的任务 = 单文件粒度，零隐含上下文
## 归档
旧的 DASHBOARD.md / ROADMAP.md / roles/*/today.md / roles/*/queue.md → `.ai/archive/`
.ai/roles/arch/card.md
+25 -20
View File
@@ -2,42 +2,47 @@
## 身份
我是架构 AI。负责需求分析、架构设计、技术选型、任务分解。
我是架构 AI。负责需求分析、架构设计、技术选型、任务拆解、质量审查。
**平台**: Claude Code + DeepSeek V4 Pro（最强推理 + Agent 框架）
**平台**: 不限（扣子/Claude Code/DeepSeek，任何AI均可担当此角色）
## 启动流程
1. 读 `dashboard.md` 全文（< 2K tokens）→ 项目全貌 + ADR 索引 + task 状态面板
2. 需要细节 → 按 dashboard 中的链接按需加载
3. 人类决策 → 读 `DECISIONS.md`
4. 完成任务 → 更新 dashboard.md + 对应 ADR/knowledge 文件
1. 读本文件（card.md）→ 我是谁、权限
2. 读 `dashboard.md` → 了解项目全貌、当前阶段、任务状态
3. 按需深入 → `.ai/knowledge/decisions.md`（ADR）、`.ai/phases/`（阶段上下文）
4. 拆解新任务 → 按模板写 `.ai/tasks/active/D{阶段号}-{序号}.md`
5. Worker 完成后 → 审查代码质量、确认测试覆盖、更新 dashboard.md
## 当前阶段
Phase 2: MVP 开发 — `dashboard.md`
P0: 基础 bring-up（电源/时钟/复位/GPIO/JTAG）
## 核心交付物
- 产品需求 + 系统架构设计
- 技术选型 + 架构决策 (ADR)
- 任务分解 → `.ai/tasks/active/P01-XXX.md`
- 跨模块协调（Coder ↔ Tester 交接协议）
- 人类决策梳理 → `DECISIONS.md`
- 架构设计文档 (docs/)
- 任务定义 (.ai/tasks/active/)
- 验收标准 (task 文件内)
- ADR (.ai/knowledge/decisions.md)
## 权限
**可写**: docs/ .ai/knowledge/ .ai/tasks/ .ai/phases/ Tools/
**只读**: Test/ Drivers/HWD32H757_HAL_Driver/ Drivers/BSP/
**禁止**: .ai/roles/ .ai/principles.md（人类维护）
## 关键入口
| 文件 | 说明 |
|------|------|
| `dashboard.md` | 唯一控制面板（替代旧 DASHBOARD.md / ROADMAP.md） |
| `dashboard.md` | 项目全貌（每次必读） |
| `DECISIONS.md` | 待人类决策事项 |
| `.ai/knowledge/decisions.md` | ADR 全文 |
| `.ai/knowledge/lessons.md` | 经验教训 |
| `.ai/knowledge/patterns.md` | 可复用模式 |
| `.ai/tasks/active/` | 所有活跃 task 文件 |
| `.ai/tasks/active/` | 活跃任务列表 |
| `.ai/tasks/templates/TASK_TEMPLATE.md` | task 格式说明 |
## 权限
## 特别注意
**可写**: docs/ shared/ projects/*/src/ projects/*/docs/ .ai/tasks/ .ai/knowledge/ dashboard.md DECISIONS.md
**只读**: projects/*/tests/ reports/
**禁止**: 无
- 嵌入式项目的架构决策往往影响寄存器层——ADR 必须注明影响哪些功能单元
- 测试→LL→HAL 的提炼路径是核心模式，拆任务时要体现这个递进关系
- Arch AI 不是某一个人/AI，任何 AI 读到这份文档都可以担当此角色
.ai/roles/dev/card.md
-40
View File
@@ -1,40 +0,0 @@
# Dev AI — 开发者
## 身份
我是开发 AI。负责编写业务代码、技术文档、Bug 修复。
**平台**: Trae CN + GLM-4.6（代码生成 + 文件操作，单文件粒度）
## 启动流程
1. 读本文件（card.md）→ 我是谁、权限、当前阶段
2. 读 dashboard.md → 找到自己对应的 task（状态为 `todo` 的 Coder 任务）
3. 打开对应 task 文件（如 `.ai/tasks/active/P01-001.md`）→ **这就是你的全部世界**
4. 按 task 文件中的「输入」「输出」「约束」「验收方法」执行
5. 完成后 → 填写 task 文件的「完成报告」→ commit（message 含 `[READY_FOR_TEST]`）
**不需要**读 ADR 全文、知识库、或其他 task 文件。你的 task 文件已经包含了完成任务所需的全部信息。
## 当前阶段
Phase 2: MVP 开发
## 核心交付物
- 业务代码实现 (projects/*/src/)
- 项目文档 (projects/*/docs/)
## 关键入口
| 文件 | 说明 |
|------|------|
| `dashboard.md` | 查找自己的 task |
| `.ai/tasks/active/P01-XXX.md` | 你的 task 文件（开工时读这个） |
| `.ai/tasks/templates/TASK_TEMPLATE_CODER.md` | task 格式说明 |
## 权限
**可写**: projects/*/src/ projects/*/docs/ docs/ tools/ data/ shared/
**只读**: review/*/task.md review/*/feedback/ .ai/tasks/active/
**禁止**: projects/*/tests/ reports/
.ai/roles/qa/card.md
-42
View File
@@ -1,42 +0,0 @@
# QA AI — 测试者
## 身份
我是测试 AI。负责在 Coze 沙盒中拉取代码、执行测试、生成报告。
**平台**: Coze CN（沙盒执行 + 自动化测试）
## 启动流程
1. 读本文件（card.md）→ 我是谁、权限
2. `git pull` → 拉取最新代码
3. `git log --oneline --grep="READY_FOR_TEST"` → 查找待测试的 task
4. 打开对应 Tester task 文件（如 `.ai/tasks/active/T01-XXX.md`）→ **这就是你的全部世界**
5. 按 task 文件中的「测试目标」「测试内容」「执行方式」执行
6. 生成测试报告 → `reports/{编号}-{日期}.json`
7. 填写 task 文件的「完成报告」→ commit
**关键**: 你不需要知道项目全貌、不需要读架构文档、不需要读 ADR。你的 task 文件 + 被测代码 = 你需要的一切。
## 当前阶段
Phase 2: MVP 开发
## 核心交付物
- 测试报告 (reports/)
- Bug 反馈（在测试报告中标注 FAIL 项）
## 关键入口
| 文件 | 说明 |
|------|------|
| `dashboard.md` | 查找自己的 task |
| `.ai/tasks/active/T01-XXX.md` | 你的 task 文件（开工时读这个） |
| `.ai/tasks/templates/TASK_TEMPLATE_TESTER.md` | task 格式说明 |
## 权限
**可写**: projects/*/tests/ reports/
**只读**: projects/*/src/ projects/*/docs/ docs/ data/ shared/ .ai/tasks/active/
**禁止**: .ai/ tools/
.ai/roles/worker/card.md
+60
View File
@@ -0,0 +1,60 @@
# Worker AI — 执行者
## 身份
我是执行 AI。负责代码编写、测试执行、文档生成、LL/HAL 驱动提炼。
**平台**: 不限（Claude Code/DeepSeek/Codex CLI，任何AI均可担当此角色）
## 启动流程
1. 读本文件（card.md）→ 我是谁、权限
2. 读 `dashboard.md` → 找到自己对应的 task（状态为 `todo` 的任务）
3. 打开对应 task 文件（如 `.ai/tasks/active/D0-001.md`）→ **这就是你的全部世界**
4. 按 task 文件中的「输入」「输出」「约束」「验收方法」执行
5. 完成后 → 填写 task 文件的「完成报告」→ commit（message 含 `[DONE]`）
**不需要**读 ADR 全文、知识库、或其他 task 文件。你的 task 文件已经包含了完成任务所需的全部信息。
## 当前阶段
P0: 基础 bring-up
## 核心交付物
- 寄存器测试代码 (Test/cases/{unit}/)
- LL 驱动代码 (Drivers/HWD32H757_HAL_Driver/Inc/*_ll_*.h, Src/*_ll_*.c)
- HAL 驱动代码 (Drivers/HWD32H757_HAL_Driver/Inc/*_hal_*.h, Src/*_hal_*.c)
- 勘误记录 (Test/errata/)
- 工具脚本 (Tools/)
## 核心工作模式：测试→LL→HAL 提炼路径
```
1. 寄存器测试代码 → 直接操作寄存器，验证功能正确性
2. 测试代码提炼为 LL 层 → 内联函数+宏，零开销
3. LL 层封装为 HAL 层 → 句柄+状态机+回调，高抽象可移植
```
每次完成一个功能单元的测试后，应主动提出 LL 层提炼建议。
## 权限
**可写**: Test/ Drivers/HWD32H757_HAL_Driver/ Drivers/BSP/ Drivers/CMSIS/ Tools/ Projects/
**只读**: docs/ .ai/tasks/active/ dashboard.md DECISIONS.md
**禁止**: .ai/ .ai/roles/ .ai/knowledge/ .ai/phases/ .ai/principles.md
## 关键入口
| 文件 | 说明 |
|------|------|
| `dashboard.md` | 查找自己的 task |
| `.ai/tasks/active/D{阶段号}-{序号}.md` | 你的 task 文件（开工时读这个） |
| `.ai/tasks/templates/TASK_TEMPLATE.md` | task 格式说明 |
## 特别注意
- 寄存器地址和位域定义必须从 SVD 或 CMSIS 头文件获取，不能凭记忆编写
- 测试代码中必须包含边界条件和异常情况的测试
- 发现勘误时必须记录到 Test/errata/，并在 LL/HAL 代码中加 workaround
- Worker AI 不是某一个人/AI，任何 AI 读到这份文档都可以担当此角色
.ai/knowledge/journal/.gitkeep → .ai/tasks/active/.gitkeep
View File
.ai/tasks/active/CROSS-001.md
-52
View File
@@ -1,52 +0,0 @@
# Task CROSS-001: 共享工具库日期格式 bug 修复
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` |
| 优先级 | P0 |
| 依赖 | 无 |
| 分配给 | Coder AI (Trae CN + GLM-4.6) |
## 输入
**要读的文件**:
- `shared/utils/date.ts` — 日期格式化工具函数
**参考的 ADR**:
- 无
**上游依赖产出**:
- 无
## 输出
**要生成/修改的文件**:
- `shared/utils/date.ts` — 修复日期格式输出
**问题描述**:
当前工具库日期格式化函数输出格式与预期不一致（具体格式差异需按实际 bug 修复）。
## 验收方法
```bash
# 运行日期格式化测试
node -e "const {formatDate} = require('./shared/utils/date'); console.log(formatDate(new Date('2026-01-15')));"
# 预期: "2026-01-15"
```
## 约束
- 不碰: `projects/app/` 目录
- 技术栈: Node.js 原生 Date API
- 遵循: ISO 8601 日期格式
## 完成报告
> Coder 完成后填写。Commit message 以 `[READY_FOR_TEST]` 结尾。
- [ ] 输出文件已生成
- [ ] 验收命令通过
- [ ] Commit: `{hash}`
- [ ] Commit message: `fix(CROSS-001): 共享工具库日期格式 bug 修复 [READY_FOR_TEST]`
.ai/tasks/active/P01-001.md
-69
View File
@@ -1,69 +0,0 @@
# Task P01-001: 数据库 Schema 实现 + 迁移脚本
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` |
| 优先级 | P0 |
| 依赖 | 无 |
| 分配给 | Coder AI (Trae CN + GLM-4.6) |
## 输入
**要读的文件**:
- `docs/02_系统架构/数据模型.md` — 所有表定义、字段、索引、Drizzle Schema 示例
- `docs/02_系统架构/技术选型.md` — PostgreSQL + Drizzle ORM 版本
**参考的 ADR**:
- ADR-009: verification_status 状态机 + ai_confidence JSONB 字段
- ADR-010: questions 表 source + external_id 字段（题库适配器路由）
**上游依赖产出**:
- 无（这是所有模块的前置依赖）
## 输出
**要生成/修改的文件**:
- `projects/app/src/db/schema/*.ts` — 全部表定义（Drizzle ORM）
- `projects/app/src/db/migrations/` — 迁移脚本
**涉及的表**:
users, user_relations, error_items, error_item_images, correction_logs, knowledge_points, question_knowledge_map, questions, print_tasks, recommendation_logs
**关键字段提醒**:
- users 表: `role VARCHAR` + `invitation_code VARCHAR`
- knowledge_points 表: `code VARCHAR`（业务编码如 G5-MATH-0201）
- questions 表: `question_type VARCHAR`（6 种题型）, `difficulty SMALLINT`（1-5）, `cognitive_level SMALLINT`（Bloom 1-6 预留）, `source VARCHAR`（self_built / zuoyebang）, `external_id VARCHAR`（第三方 ID）
- error_items 表: `verification_status VARCHAR`（raw/reviewed/corrected/stale）, `ai_confidence JSONB`, `subject VARCHAR`（math/english）
- correction_logs 表: `ai_value JSONB` + `user_value JSONB` + `ai_confidence NUMERIC`
- print_tasks 表: `status, file_url, expires_at, created_at`
- user_relations 表: `parent_user_id, child_user_id, level`（支持递归 CTE 邀请链查询）
## 验收方法
```bash
# 生成迁移脚本
npm run db:generate
# 执行迁移（本地 dev 数据库）
npm run db:migrate
# 验证所有表存在
psql $DATABASE_URL -c "\dt"
```
## 约束
- 不碰: `projects/app/src/modules/`（业务模块）、`projects/app/tests/`
- 技术栈: PostgreSQL + Drizzle ORM
- 遵循: 数据模型 v0.4.0 字段定义，不做自行裁剪
## 完成报告
> Coder 完成后填写。Commit message 以 `[READY_FOR_TEST]` 结尾。
- [ ] 输出文件已生成
- [ ] 验收命令通过
- [ ] Commit: `{hash}`
- [ ] Commit message: `feat(P01-001): 数据库 Schema 实现 + 迁移脚本 [READY_FOR_TEST]`
.ai/tasks/active/P01-002.md
-64
View File
@@ -1,64 +0,0 @@
# Task P01-002: Auth 模块（微信登录 + JWT）
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` |
| 优先级 | P0 |
| 依赖 | P01-001（DB Schema） |
| 分配给 | Coder AI (Trae CN + GLM-4.6) |
## 输入
**要读的文件**:
- `docs/02_系统架构/模块设计.md` — 3.1 Auth 模块 API 接口定义
- `docs/02_系统架构/数据模型.md` — users 表结构（role + invitation_code 字段）
- `projects/app/src/db/schema/*.ts` — P01-001 产出的 Drizzle Schema
**参考的 ADR**:
- ADR-009: 用户相关数据访问权限
**上游依赖产出**:
- P01-001: users 表 Drizzle Schema（user 类型定义）
## 输出
**要生成/修改的文件**:
- `projects/app/src/modules/auth/auth.module.ts`
- `projects/app/src/modules/auth/auth.controller.ts` — POST /auth/login（code2session + JWT 签发）
- `projects/app/src/modules/auth/auth.service.ts` — 微信 code2session → 查/建用户 → 签发 JWT
- `projects/app/src/modules/auth/auth.guard.ts` — AuthGuard（JWT 验证中间件）
- `projects/app/src/modules/auth/dto/login.dto.ts`
**API**:
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /auth/login | code → JWT（新用户自动注册） |
| GET | /auth/me | 当前用户信息 |
## 验收方法
```bash
# 编译检查
npx tsc --noEmit
# 手动测试（需要微信小程序 code）
curl -X POST http://localhost:3000/auth/login -d '{"code":"test_code"}'
# 预期: 返回 { access_token, user }
```
## 约束
- 不碰: `projects/app/tests/`、其他 modules/ 目录
- 技术栈: NestJS + JWT + axios（调用微信接口）
- 遵循: `.ai/prompts/coding/code-style.md`
## 完成报告
> Coder 完成后填写。Commit message 以 `[READY_FOR_TEST]` 结尾。
- [ ] 输出文件已生成
- [ ] 验收命令通过
- [ ] Commit: `{hash}`
- [ ] Commit message: `feat(P01-002): Auth 模块（微信登录+JWT） [READY_FOR_TEST]`
.ai/tasks/active/P01-003.md
-69
View File
@@ -1,69 +0,0 @@
# Task P01-003: User 模块（个人资料 CRUD + 邀请链）
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` |
| 优先级 | P1 |
| 依赖 | P01-002（Auth 模块，需要 JWT AuthGuard） |
| 分配给 | Coder AI (Trae CN + GLM-4.6) |
## 输入
**要读的文件**:
- `docs/02_系统架构/模块设计.md` — 3.3 User 模块
- `docs/02_系统架构/数据模型.md` — users 表 + user_relations 表
- `projects/app/src/db/schema/*.ts` — P01-001 产出的 Drizzle Schema
- `projects/app/src/modules/auth/auth.guard.ts` — P01-002 产出的 AuthGuard
**参考的 ADR**:
- 无特殊 ADR
**上游依赖产出**:
- P01-002: AuthGuard（本模块所有接口需要 JWT 验证）
## 输出
**要生成/修改的文件**:
- `projects/app/src/modules/user/user.module.ts`
- `projects/app/src/modules/user/user.controller.ts`
- `projects/app/src/modules/user/user.service.ts`
**API**:
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /user/profile | 获取个人信息 |
| PATCH | /user/profile | 更新个人信息（昵称、头像、年级） |
| POST | /user/invite | 生成邀请码 |
| GET | /user/invite/tree | 查询邀请链（递归 CTE） |
**关键逻辑**:
- 邀请码生成: 6 位字母数字随机码，唯一
- 邀请链查询: `WITH RECURSIVE` CTE 查 user_relations 表，返回被邀请人列表+层级
## 验收方法
```bash
# 编译检查
npx tsc --noEmit
# 测试邀请链查询
curl -H "Authorization: Bearer {token}" http://localhost:3000/user/invite/tree
# 预期: { tree: [{ userId, nickname, level, invitedAt }] }
```
## 约束
- 不碰: `projects/app/tests/`、其他 modules/ 目录
- 技术栈: NestJS + Drizzle ORM（嵌套查询）
- 遵循: `.ai/prompts/coding/code-style.md`
## 完成报告
> Coder 完成后填写。Commit message 以 `[READY_FOR_TEST]` 结尾。
- [ ] 输出文件已生成
- [ ] 验收命令通过
- [ ] Commit: `{hash}`
- [ ] Commit message: `feat(P01-003): User 模块（CRUD+邀请链） [READY_FOR_TEST]`
.ai/tasks/active/P01-004.md
-68
View File
@@ -1,68 +0,0 @@
# Task P01-004: Upload 模块（图片上传 + S3）
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` |
| 优先级 | P1 |
| 依赖 | P01-001（DB Schema） |
| 分配给 | Coder AI (Trae CN + GLM-4.6) |
## 输入
**要读的文件**:
- `docs/02_系统架构/模块设计.md` — 3.5 Upload 模块（或相关 API 定义）
- `docs/02_系统架构/数据模型.md` — error_item_images 表结构
- `docs/02_系统架构/技术选型.md` — S3 SDK + Sharp 版本
- `projects/app/src/db/schema/*.ts` — P01-001 产出的 Drizzle Schema
**参考的 ADR**:
- 无特殊 ADR
**上游依赖产出**:
- P01-001: error_item_images 表 Drizzle Schema
## 输出
**要生成/修改的文件**:
- `projects/app/src/modules/upload/upload.module.ts`
- `projects/app/src/modules/upload/upload.controller.ts` — POST /upload/image
- `projects/app/src/modules/upload/upload.service.ts` — 接收文件 → 上传 S3 → 生成缩略图 → 写 DB
**API**:
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /upload/image | multipart 上传图片 → S3 URL + 缩略图 URL |
**关键逻辑**:
- 原图上传 S3（bucket: errlens-originals）
- Sharp 生成缩略图（max 300x300）→ 上传 S3（bucket: errlens-thumbnails）
- 写入 error_item_images 表（关联 error_item_id 可选，拍照时先上传图片再创建错题记录）
## 验收方法
```bash
# 编译检查
npx tsc --noEmit
# 上传测试图片
curl -X POST http://localhost:3000/upload/image \
-F "image=@test.jpg"
# 预期: { id, originalUrl, thumbnailUrl, width, height }
```
## 约束
- 不碰: `projects/app/tests/`、Image 模块目录、Print 模块目录
- 技术栈: NestJS + Sharp + @aws-sdk/client-s3（或 Minio SDK）
- 遵循: `.ai/prompts/coding/code-style.md`
## 完成报告
> Coder 完成后填写。Commit message 以 `[READY_FOR_TEST]` 结尾。
- [ ] 输出文件已生成
- [ ] 验收命令通过
- [ ] Commit: `{hash}`
- [ ] Commit message: `feat(P01-004): Upload 模块（图片上传+S3+缩略图） [READY_FOR_TEST]`
.ai/tasks/active/P01-005.md
-64
View File
@@ -1,64 +0,0 @@
# Task P01-005: Image 模块（图像预处理管线）
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` |
| 优先级 | P0 |
| 依赖 | P01-004（Upload 模块，需要图片 URL 做输入） |
| 分配给 | Coder AI (Trae CN + GLM-4.6) |
## 输入
**要读的文件**:
- `docs/02_系统架构/模块设计.md` — 3.6 Image 模块（图像预处理），含 CLAHE 参数和降级策略
- `docs/02_系统架构/总体架构.md` — 3.1 数据流中的图像预处理位置（OCR 之前）
- `projects/app/src/modules/upload/` — P01-004 产出的 Upload 模块（获取图片 URL）
**参考的 ADR**:
- 无特殊 ADR（图像预处理管线来自旧架构已验证方案）
**上游依赖产出**:
- P01-004: Upload 模块（图片 URL 来源）
## 输出
**要生成/修改的文件**:
- `projects/app/src/modules/image/image.module.ts`
- `projects/app/src/modules/image/image.service.ts` — 图像预处理管线
**处理管线（按顺序）**:
1. 透视校正（检测文档边缘 → 透视变换拉正）
2. CLAHE 增强（对比度受限的自适应直方图均衡化）
3. 笔迹去除（红色笔迹 HSV 自动去除，蓝色同，黑色手动标记）
**关键参数**:
- CLAHE: clipLimit=2.0, tileGridSize=(8,8)
- 输出格式: PNG（保留质量）
- 降级策略: 任一步骤失败 → 跳过该步骤 → 用原图继续。不阻塞整体流程
## 验收方法
```bash
# 编译检查
npx tsc --noEmit
# 功能测试（用一张含红笔批改的错题照片）
# 预期: 输出图中红色笔迹明显减弱，对比度提升
```
## 约束
- 不碰: `projects/app/tests/`、OCR 相关模块（不属于当前 scope）
- 技术栈: NestJS + Sharp
- 遵循: 降级策略——不因预处理失败而阻塞
## 完成报告
> Coder 完成后填写。Commit message 以 `[READY_FOR_TEST]` 结尾。
- [ ] 输出文件已生成
- [ ] 验收命令通过
- [ ] Commit: `{hash}`
- [ ] Commit message: `feat(P01-005): Image 模块（图像预处理管线） [READY_FOR_TEST]`
.ai/tasks/active/P01-006.md
-78
View File
@@ -1,78 +0,0 @@
# Task P01-006: Print 模块（PDF 生成 + S3 + 过期清理）
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` |
| 优先级 | P0 |
| 依赖 | P01-001（DB Schema，需要 print_tasks 表） |
| 分配给 | Coder AI (Trae CN + GLM-4.6) |
## 输入
**要读的文件**:
- `docs/02_系统架构/模块设计.md` — 3.7 Print 模块（PDF 输出）
- `docs/02_系统架构/数据模型.md` — 2.11 print_tasks 表
- `docs/02_系统架构/总体架构.md` — 3.3 打印/PDF 输出数据流
- `projects/app/src/db/schema/*.ts` — P01-001 产出的 Drizzle Schema
**参考的 ADR**:
- 无特殊 ADR
**上游依赖产出**:
- P01-001: print_tasks 表 Drizzle Schema
## 输出
**要生成/修改的文件**:
- `projects/app/src/modules/print/print.module.ts`
- `projects/app/src/modules/print/print.controller.ts`
- `projects/app/src/modules/print/print.service.ts`
**API**:
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /print/generate | 提交错题 ID 列表 → 生成 PDF → 上传 S3 |
| GET | /print/task/:id | 查询生成进度 |
| GET | /print/download/:id | 获取下载链接（24h 有效） |
**关键逻辑**:
- PDF 生成: PDFKit, A4 纸张, 300 DPI
- 错题图片嵌入 PDF，每页一道题
- 上传 S3（bucket: errlens-prints）
- 24 小时过期: 数据库 expires_at 字段 + 定时任务清理（node-cron）
- 下载链接一次性签名 URL
## 验收方法
```bash
# 编译检查
npx tsc --noEmit
# 提交生成任务
curl -X POST http://localhost:3000/print/generate \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"errorItemIds": ["uuid-1", "uuid-2"]}'
# 预期: { taskId, status: "processing" }
# 查询进度
curl http://localhost:3000/print/task/{taskId}
# 预期: { status: "completed", downloadUrl: "..." }
```
## 约束
- 不碰: `projects/app/tests/`、其他 modules/ 目录
- 技术栈: NestJS + PDFKit + @aws-sdk/client-s3 + node-cron
- 遵循: 下载链接 24h 过期，S3 文件同步过期清理
## 完成报告
> Coder 完成后填写。Commit message 以 `[READY_FOR_TEST]` 结尾。
- [ ] 输出文件已生成
- [ ] 验收命令通过
- [ ] Commit: `{hash}`
- [ ] Commit message: `feat(P01-006): Print 模块（PDF+S3+24h过期清理） [READY_FOR_TEST]`
.ai/tasks/active/P01-007.md
-67
View File
@@ -1,67 +0,0 @@
# Task P01-007: 页面路由 + 基础页面骨架
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` |
| 优先级 | P1 |
| 依赖 | P01-003（User 模块 API 稳定后） |
| 分配给 | Coder AI (Trae CN + GLM-4.6) |
## 输入
**要读的文件**:
- `docs/02_系统架构/模块设计.md` — 3.8 Pages 路由（各页面模块）
- `docs/02_系统架构/总体架构.md` — 前端技术栈 Taro 4 + React 18
- `docs/01_产品需求/PRD.md` — 页面功能需求
**参考的 ADR**:
- 无特殊 ADR
**上游依赖产出**:
- P01-003: User 模块 API（各页面需要用户数据）
## 输出
**要生成/修改的文件**:
- `projects/app/src/app.config.ts` — Taro 页面路由配置（9 个页面）
- `projects/app/src/pages/index/index.tsx` — 首页（错题列表）
- `projects/app/src/pages/capture/index.tsx` — 拍照录入页
- `projects/app/src/pages/detail/index.tsx` — 错题详情页
- `projects/app/src/pages/analysis/index.tsx` — AI 分析结果页
- `projects/app/src/pages/recommend/index.tsx` — 推荐练习页（暂为占位）
- `projects/app/src/pages/print/index.tsx` — 打印选择页
- `projects/app/src/pages/print/preview.tsx` — 打印预览页
- `projects/app/src/pages/profile/index.tsx` — 个人中心页
- `projects/app/src/pages/invite/index.tsx` — 邀请页
**页面要求**:
- 每个页面有基础布局（标题栏 + 内容区）
- 打印预览页显示错题列表 + 生成 PDF 按钮
- 其他页面可为功能占位（显示「开发中」即可），不需要完整交互
## 验收方法
```bash
# 编译检查
npx tsc --noEmit
# 小程序开发工具预览
# 预期: 9 个页面可导航，无白屏/报错
```
## 约束
- 不碰: `projects/app/tests/`、后端 modules/ 目录
- 技术栈: Taro 4 + React 18
- 遵循: 页面基础布局即可，不需要完整交互逻辑
## 完成报告
> Coder 完成后填写。Commit message 以 `[READY_FOR_TEST]` 结尾。
- [ ] 输出文件已生成
- [ ] 验收命令通过
- [ ] Commit: `{hash}`
- [ ] Commit message: `feat(P01-007): 页面路由+9个基础页面骨架 [READY_FOR_TEST]`
.ai/tasks/active/T01-001.md
-63
View File
@@ -1,63 +0,0 @@
# Task T01-001: 数据库 Schema 验证
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` |
| 优先级 | P0 |
| 对应 Coder task | P01-001 |
| 分配给 | Tester AI (Coze CN) |
## 测试目标
验证 Drizzle 迁移脚本是否正确创建了所有表、字段类型、索引、外键。
## 被测对象
**Coder 产出的 commit**:
- 从 git log 查找 commit message 包含 `[READY_FOR_TEST]` 且 task 编号为 `P01-001` 的最新 commit
**Coder task 文件**:
- [P01-001](P01-001.md) — 理解该 task 的输出和约束
## 测试内容
**关键路径**:
- [ ] 所有 10 张表已创建（users, user_relations, error_items, error_item_images, correction_logs, knowledge_points, question_knowledge_map, questions, print_tasks, recommendation_logs）
- [ ] users 表 role 字段为 VARCHAR，invitation_code 字段存在
- [ ] knowledge_points 表 code 字段存在（VARCHAR）
- [ ] questions 表 question_type（6 种）、difficulty（SMALLINT 1-5）、source 字段存在
- [ ] error_items 表 verification_status 字段 + ai_confidence JSONB 字段存在
- [ ] correction_logs 表 ai_value + user_value JSONB 字段存在
- [ ] print_tasks 表 status + file_url + expires_at 字段存在
- [ ] user_relations 表支持递归 CTE（parent_user_id + child_user_id + level）
- [ ] 所有索引已创建（按数据模型文档核对）
**不应发生的**:
- [ ] 无 missing table
- [ ] 无字段类型错误（如 JSONB 写成 TEXT）
- [ ] 无 missing index
## 执行方式
```
1. git pull → 拉取最新代码
2. 在 Coze 沙盒中执行迁移
3. 查询 information_schema 对比数据模型文档
4. 生成测试报告
```
## 报告格式
输出 `reports/T01-001-{日期}.json`
## 完成报告
> Tester 完成后填写。
- [ ] 测试已执行
- [ ] 报告已生成 → `reports/T01-001-{日期}.json`
- [ ] Commit: `{hash}`
- [ ] Commit message: `test(T01-001): {结论}`
- [ ] 结论: PASS / FAIL / RETRY
.ai/tasks/active/T01-002.md
-61
View File
@@ -1,61 +0,0 @@
# Task T01-002: Auth 模块测试
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` |
| 优先级 | P0 |
| 对应 Coder task | P01-002 |
| 分配给 | Tester AI (Coze CN) |
## 测试目标
验证微信登录 code2session → JWT 签发 → AuthGuard 保护链路完整可用。
## 被测对象
**Coder 产出的 commit**:
- 从 git log 查找 commit message 包含 `[READY_FOR_TEST]` 且 task 编号为 `P01-002` 的最新 commit
**Coder task 文件**:
- [P01-002](P01-002.md) — 理解该 task 的 API 定义
## 测试内容
**关键路径**:
- [ ] POST /auth/login 使用有效 code → 返回 access_token + user
- [ ] POST /auth/login 使用无效 code → 返回 401
- [ ] POST /auth/login 新用户首次登录 → 自动注册成功（users 表有记录）
- [ ] POST /auth/login 已注册用户再次登录 → 返回已有用户信息（不重复创建）
- [ ] GET /auth/me 携带有效 token → 返回当前用户信息
- [ ] GET /auth/me 无 token → 返回 401
- [ ] GET /auth/me 携带过期 token → 返回 401
**不应发生的**:
- [ ] 无效 code 不返回 500（应优雅处理）
- [ ] JWT payload 不泄露敏感信息（不应有手机号、密码等）
## 执行方式
```
1. git pull → 拉取最新代码
2. 在 Coze 沙盒中启动服务
3. 用测试 code 调用 /auth/login
4. 用返回的 token 调用 /auth/me
5. 生成测试报告
```
## 报告格式
输出 `reports/T01-002-{日期}.json`
## 完成报告
> Tester 完成后填写。
- [ ] 测试已执行
- [ ] 报告已生成 → `reports/T01-002-{日期}.json`
- [ ] Commit: `{hash}`
- [ ] Commit message: `test(T01-002): {结论}`
- [ ] 结论: PASS / FAIL / RETRY
.ai/tasks/active/T01-003.md
-64
View File
@@ -1,64 +0,0 @@
# Task T01-003: Image + Upload 模块联测
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` |
| 优先级 | P0 |
| 对应 Coder task | P01-005 (Image) + P01-004 (Upload) |
| 分配给 | Tester AI (Coze CN) |
## 测试目标
验证「图片上传 → 缩略图生成 → 图像预处理管线（透视校正+CLAHE+笔迹去除）」完整链路。
## 被测对象
**Coder 产出的 commit**:
- P01-004: commit message 包含 `[READY_FOR_TEST]` 且 task 编号为 `P01-004`
- P01-005: commit message 包含 `[READY_FOR_TEST]` 且 task 编号为 `P01-005`
**Coder task 文件**:
- [P01-004](P01-004.md) — Upload 模块 API
- [P01-005](P01-005.md) — Image 模块处理管线
## 测试内容
**关键路径**:
- [ ] POST /upload/image 上传 JPEG 图片 → 返回 originalUrl + thumbnailUrl
- [ ] 缩略图尺寸 ≤ 300x300
- [ ] 图像预处理：透视校正后图片无明显梯形畸变
- [ ] 图像预处理：CLAHE 增强后对比度有可观测提升
- [ ] 图像预处理：红色笔迹去除效果可观测（用含红笔批改的测试图）
- [ ] 图像预处理：蓝色笔迹去除效果可观测（用含蓝笔批改的测试图）
- [ ] 降级策略：任一步骤失败不阻塞整体（用损坏的图片测试）
- [ ] error_item_images 表记录正确写入
**不应发生的**:
- [ ] 预处理管线崩溃时不应返回 500（降级返回原始图片即可）
- [ ] 缩略图不应丢失宽高比
## 执行方式
```
1. git pull → 拉取最新代码
2. 在 Coze 沙盒中启动服务
3. 准备测试图片（含红/蓝笔批改的错题照片 + 一张损坏图）
4. 上传 → 检查 S3 → 检查预处理结果
5. 生成测试报告
```
## 报告格式
输出 `reports/T01-003-{日期}.json`
## 完成报告
> Tester 完成后填写。
- [ ] 测试已执行
- [ ] 报告已生成 → `reports/T01-003-{日期}.json`
- [ ] Commit: `{hash}`
- [ ] Commit message: `test(T01-003): {结论}`
- [ ] 结论: PASS / FAIL / RETRY
.ai/tasks/active/T01-004.md
-64
View File
@@ -1,64 +0,0 @@
# Task T01-004: Print 模块测试
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` |
| 优先级 | P0 |
| 对应 Coder task | P01-006 |
| 分配给 | Tester AI (Coze CN) |
## 测试目标
验证 PDF 生成、S3 上传、24h 过期清理完整流程。
## 被测对象
**Coder 产出的 commit**:
- 从 git log 查找 commit message 包含 `[READY_FOR_TEST]` 且 task 编号为 `P01-006` 的最新 commit
**Coder task 文件**:
- [P01-006](P01-006.md) — Print 模块 API
## 测试内容
**关键路径**:
- [ ] POST /print/generate 提交错题 ID 列表 → 返回 taskId + status: "processing"
- [ ] GET /print/task/:id → 查询进度，最终返回 status: "completed" + downloadUrl
- [ ] GET /print/download/:id → 返回 PDF 文件下载
- [ ] PDF 文件可正常打开，内容为错题图片（每页一道题）
- [ ] PDF 为 A4 纸张规格
- [ ] downloadUrl 为 S3 签名 URL
- [ ] expires_at 字段设置为创建时间 + 24h
- [ ] 过期清理: 模拟 expires_at 已过 → 下载链接失效
**不应发生的**:
- [ ] 空错题列表不应崩溃（返回明确错误信息）
- [ ] 不存在的 task id 不应返回 500
- [ ] 已过期的下载链接不应仍可访问
## 执行方式
```
1. git pull → 拉取最新代码
2. 在 Coze 沙盒中启动服务
3. 提交打印任务 → 等待完成 → 下载 PDF
4. 验证 PDF 格式和内容
5. 模拟过期场景
6. 生成测试报告
```
## 报告格式
输出 `reports/T01-004-{日期}.json`
## 完成报告
> Tester 完成后填写。
- [ ] 测试已执行
- [ ] 报告已生成 → `reports/T01-004-{日期}.json`
- [ ] Commit: `{hash}`
- [ ] Commit message: `test(T01-004): {结论}`
- [ ] 结论: PASS / FAIL / RETRY
.ai/tasks/active/T01-005.md
-68
View File
@@ -1,68 +0,0 @@
# Task T01-005: User 模块 + 日期修复验证
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` |
| 优先级 | P1 |
| 对应 Coder task | P01-003 (User) + CROSS-001 (日期修复) |
| 分配给 | Tester AI (Coze CN) |
## 测试目标
验证用户个人信息 CRUD、邀请码生成、邀请链递归 CTE 查询，以及日期格式 bug 修复。
## 被测对象
**Coder 产出的 commit**:
- P01-003: commit message 包含 `[READY_FOR_TEST]` 且 task 编号为 `P01-003`
- CROSS-001: commit message 包含 `[READY_FOR_TEST]` 且 task 编号为 `CROSS-001`
**Coder task 文件**:
- [P01-003](P01-003.md) — User 模块 API
- [CROSS-001](CROSS-001.md) — 日期格式修复
## 测试内容
**关键路径 (User 模块)**:
- [ ] GET /user/profile → 返回当前用户信息
- [ ] PATCH /user/profile → 更新昵称/头像/年级，返回更新后信息
- [ ] POST /user/invite → 生成 6 位唯一邀请码
- [ ] POST /user/invite → 同一用户重复调用不重复生成（已有时返回已有码）
- [ ] GET /user/invite/tree → 返回邀请树（含被邀请人+层级）
- [ ] GET /user/invite/tree → 无邀请记录时返回空树
**关键路径 (日期修复)**:
- [ ] `shared/utils/date.ts` formatDate 输出为 ISO 8601 格式（YYYY-MM-DD）
- [ ] 所有使用日期格式的接口返回正确格式
**不应发生的**:
- [ ] 邀请码不应重复（并发场景）
- [ ] 邀请链查询不应超时（数据量大时 CTE 性能）
## 执行方式
```
1. git pull → 拉取最新代码
2. 在 Coze 沙盒中启动服务
3. 注册/登录两个测试用户
4. 用户 A 生成邀请码 → 用户 B 用邀请码注册
5. 验证邀请链查询结果
6. 验证日期格式
7. 生成测试报告
```
## 报告格式
输出 `reports/T01-005-{日期}.json`
## 完成报告
> Tester 完成后填写。
- [ ] 测试已执行
- [ ] 报告已生成 → `reports/T01-005-{日期}.json`
- [ ] Commit: `{hash}`
- [ ] Commit message: `test(T01-005): {结论}`
- [ ] 结论: PASS / FAIL / RETRY
.ai/tasks/active/T01-006.md
-66
View File
@@ -1,66 +0,0 @@
# Task T01-006: 页面骨架 + API 集成测试
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` |
| 优先级 | P1 |
| 对应 Coder task | P01-007 |
| 分配给 | Tester AI (Coze CN) |
## 测试目标
验证 9 个页面路由可访问、页面骨架渲染正常、各页面 API 调用连通。
## 被测对象
**Coder 产出的 commit**:
- 从 git log 查找 commit message 包含 `[READY_FOR_TEST]` 且 task 编号为 `P01-007` 的最新 commit
**Coder task 文件**:
- [P01-007](P01-007.md) — 页面路由 + 骨架
## 测试内容
**关键路径**:
- [ ] 所有 9 个页面可正常导航（无白屏/报错）
- [ ] 首页（index）— 错题列表骨架渲染
- [ ] 拍照录入页（capture）— 调用相机/相册
- [ ] 错题详情页（detail）— 展示错题信息
- [ ] AI 分析结果页（analysis）— 展示分析数据
- [ ] 推荐练习页（recommend）— 占位内容正常
- [ ] 打印选择页（print/index）— 错题列表可勾选
- [ ] 打印预览页（print/preview）— 显示已选错题 + PDF 生成按钮
- [ ] 个人中心页（profile）— 调用 /user/profile API
- [ ] 邀请页（invite）— 调用 /user/invite API
- [ ] Taro 路由配置正确（app.config.ts 包含所有页面路径）
**不应发生的**:
- [ ] 页面切换不白屏
- [ ] 无 JS 报错（console 无红色）
- [ ] 无 API 调用 404
## 执行方式
```
1. git pull → 拉取最新代码
2. 在 Coze 沙盒或微信开发者工具中编译运行
3. 遍历所有页面 → 检查渲染 + console
4. 验证各页面 API 调用连通性
5. 生成测试报告
```
## 报告格式
输出 `reports/T01-006-{日期}.json`
## 完成报告
> Tester 完成后填写。
- [ ] 测试已执行
- [ ] 报告已生成 → `reports/T01-006-{日期}.json`
- [ ] Commit: `{hash}`
- [ ] Commit message: `test(T01-006): {结论}`
- [ ] 结论: PASS / FAIL / RETRY
docs/01_产品需求/.gitkeep → .ai/tasks/completed/.gitkeep
View File
.ai/tasks/templates/TASK_TEMPLATE.md
+59
View File
@@ -0,0 +1,59 @@
# Task 模板
> 所有 task 文件必须遵循此模板，确保自包含、零隐含上下文。
---
```markdown
# Task {编号}: {标题}
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` / `in_progress` / `done` / `verified` / `accepted` |
| 优先级 | P0 / P1 / P2 |
| 依赖 | 上游任务编号（无则写"无"） |
| 分配给 | Worker AI |
## 输入
**要读的文件**:
- `路径` — 简要说明
**参考的 ADR**:
- ADR-XXX: 一句话说明关联性
**上游依赖产出**:
- 无 / D{X}-{YYY} 产出为 ZZZ
## 输出
**要生成/修改的文件**:
- `路径` — 简要说明
**输出格式**: 代码/文档/配置
## 约束
- 不碰: 列出禁止修改的目录
- 技术栈: GCC ARM + CMake / Python
- 规范: 编码规范、命名规范
## 验收方法
```bash
# 具体命令和预期结果
```
## 完成报告
> Worker 完成后填写。Commit message 以 `[DONE]` 结尾。
- [ ] 输出文件已生成
- [ ] 验收命令通过
- [ ] Commit: `{hash}`
- [ ] Commit message: `feat({编号}): 简短描述 [DONE]`
- [ ] 发现的勘误: 无 / 描述
- [ ] LL提炼建议: 无 / 描述
```
.ai/tasks/templates/TASK_TEMPLATE_CODER.md
-47
View File
@@ -1,47 +0,0 @@
# Task {编号}: {标题}
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` → `in_progress` → `done` → `tested` → `accepted` |
| 优先级 | P0 / P1 / P2 |
| 依赖 | {上游 task 编号，无则写「无」} |
| 分配给 | Coder AI (Trae CN + GLM-4.6) |
## 输入
**要读的文件**:
- `{完整路径}` — {一句话说明}
**参考的 ADR**:
- ADR-XXX: {一句话说明关联}
**上游依赖产出**:
- {上游 task 编号}: {产出是什么}
## 输出
**要生成/修改的文件**:
- `{完整路径}` — {说明}
- `{完整路径}` — {说明}
**验收方法**:
```bash
{具体命令或步骤，Coder 可以自己跑来验证}
```
## 约束
- 不碰: `{目录路径}`
- 技术栈: {库/版本}
- 遵循: `{规范文件}`
## 完成报告
> Coder 完成后填写。Commit message 以 `[READY_FOR_TEST]` 结尾。
- [ ] 输出文件已生成
- [ ] 验收命令通过
- [ ] Commit: `{hash}`
- [ ] Commit message: `feat({编号}): {描述} [READY_FOR_TEST]`
.ai/tasks/templates/TASK_TEMPLATE_TESTER.md
-75
View File
@@ -1,75 +0,0 @@
# Task {编号}: {标题}
## 元信息
| 字段 | 值 |
|------|-----|
| 状态 | `todo` → `in_progress` → `done` → `accepted` |
| 优先级 | P0 / P1 / P2 |
| 对应 Coder task | {P01-XXX} |
| 分配给 | Tester AI (Coze CN) |
## 测试目标
{一句话 —— 验证什么功能/模块}
## 被测对象
**Coder 产出的 commit**:
- 从 git log 查找 commit message 包含 `[READY_FOR_TEST]` 且 task 编号为 `{编号}` 的最新 commit
- 或直接读 `.ai/roles/dev/card.md` 里指定的代码目录
**Coder task 文件**:
- [P01-XXX]({路径}) — 理解该 task 的输入/输出/约束
## 测试内容
**关键路径**:
- [ ] {关键路径 1}
- [ ] {关键路径 2}
- [ ] {边界条件}
**不应发生的**:
- [ ] {错误情况 1}
## 执行方式
```
1. git pull → 拉取最新代码
2. 在 Coze 沙盒中执行测试
3. 生成测试报告
```
## 报告格式
输出 `reports/{编号}-{日期}.json`:
```json
{
"task": "{编号}",
"date": "{YYYY-MM-DD}",
"summary": {
"total": {N},
"passed": {N},
"failed": {N}
},
"results": [
{
"case": "{用例名}",
"status": "pass|fail",
"details": "{失败时的详细信息}"
}
],
"conclusion": "PASS|FAIL|RETRY"
}
```
## 完成报告
> Tester 完成后填写。
- [ ] 测试已执行
- [ ] 报告已生成 → `reports/{编号}-{日期}.json`
- [ ] Commit: `{hash}`
- [ ] Commit message: `test({编号}): {结论}`
- [ ] 结论: PASS / FAIL / RETRY
.github/workflows/README.md
-1
View File
@@ -1 +0,0 @@
# workflows
.gitignore
+14 -46
View File
@@ -1,58 +1,26 @@
# Dependencies
node_modules/
vendor/
__pycache__/
*.pyc
*.pyo
venv/
# Build outputs
dist/
# Build
build/
*.log
*.out
out/
# IDE
.vscode/
.idea/
*.swp
*.swo
*.DS_Store
# OS
Thumbs.db
.DS_Store
Thumbs.db
# Environment variables
.env
.env.local
.env.*.local
.env.production
# Python
__pycache__/
*.pyc
.venv/
# Test reports
reports/test-results/*.json
reports/test-results/*.xml
reports/reviews/*.md
# Model files
models/
*.pt
*.pth
*.onnx
# Data files
data/
*.csv
*.jsonl
# Temporary files
*.tmp
*.temp
*.bak
# Logs
logs/
*.log
# AI history (optional - uncomment to track)
# .ai/history/
# Binary
*.o
*.elf
*.bin
*.hex
*.map
*.lst
.trae/skills/add-subproject/SKILL.md
-253
View File
@@ -1,253 +0,0 @@
---
name: "add-subproject"
description: "Adds a new subproject to the existing '1 Human + 2 AI' collaboration framework. Invoke when you need to add a new subproject like web admin, data entry program, etc."
---
# 添加子项目 Skill
## 功能
在现有的"1人+2AI"协作框架中动态添加新的子项目，自动创建：
- 项目目录结构（src/、tests/、docs/）
- 环境配置文件（ENVIRONMENT.md）
- README.md 占位文件
- 示例任务目录（含 task.md、acceptance.md、impact.md、feedback/）
## 使用方法
### 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| project_name | string | 是 | 子项目名称，如 "web_admin"、"data_entry" |
| project_number | string | 否 | 项目编号，如 "P03"，默认自动生成 |
### 调用方式
```bash
# 方式1：仅提供项目名称（自动分配编号）
# skill 会自动检测现有项目编号，分配下一个编号
add-subproject --project_name="web_admin"
# 方式2：指定项目编号
add-subproject --project_name="web_admin" --project_number="P03"
```
## 创建的内容
### 目录结构
```
projects/
└── P03_web_admin/ # 新项目目录
├── src/ # Dev AI 工作区
│ ├── server/ # NestJS 后端（如需要）
│ ├── config/ # 构建配置
│ ├── types/ # 全局类型
│ └── README.md
├── tests/ # QA AI 工作区
│ └── README.md
├── docs/ # 项目文档
│ ├── 01_需求概要.md
│ ├── 02_架构设计.md
│ └── 03_接口定义.md
└── ENVIRONMENT.md # 环境配置
```
### 任务目录
```
review/
└── active/
└── P03-001/ # 新项目的第一个任务
├── task.md # 任务描述（人类创建，AI 只读）
├── acceptance.md # 验收标准
├── impact.md # 变更影响范围
└── feedback/ # 测试反馈
└── round1.md
```
## 执行命令
```bash
# 获取下一个项目编号（PowerShell 兼容版本）
get_next_project_number() {
# 兼容 Linux/macOS
if command -v ls >/dev/null 2>&1; then
ls -la projects/ | grep -E '^P[0-9]+_' | sort | tail -1 | sed 's/P\([0-9]*\)_.*$/\1/'
# 兼容 Windows PowerShell
elif command -v powershell >/dev/null 2>&1; then
powershell -Command "(Get-ChildItem projects -Directory | Where-Object { $_.Name -match '^P\d+_' } | Sort-Object Name | Select-Object -Last 1).Name -replace 'P(\d+)_.*', '$1'"
else
echo "0"
fi
}
# 创建项目目录
PROJECT_NAME="web_admin"
NEXT_NUM=$(get_next_project_number)
PROJECT_NUM="P$(printf '%02d' $((NEXT_NUM + 1)))"
PROJECT_DIR="projects/${PROJECT_NUM}_${PROJECT_NAME}"
mkdir -p "${PROJECT_DIR}"/{src/{server,config,types},tests,docs}
# 创建 ENVIRONMENT.md
cat > "${PROJECT_DIR}/ENVIRONMENT.md" << EOF
# ${PROJECT_NUM}_${PROJECT_NAME} - 环境准备
## 依赖
- Node.js >= 20.x
- pnpm >= 9.0.0
## 安装
pnpm install
## 运行
pnpm dev
EOF
# 创建文档
cat > "${PROJECT_DIR}/docs/01_需求概要.md" << EOF
# ${PROJECT_NUM}_${PROJECT_NAME} - 需求概要
## 项目概述
## 功能需求
## 非功能需求
EOF
cat > "${PROJECT_DIR}/docs/02_架构设计.md" << EOF
# ${PROJECT_NUM}_${PROJECT_NAME} - 架构设计
## 技术选型
## 架构图
## 模块划分
EOF
cat > "${PROJECT_DIR}/docs/03_接口定义.md" << EOF
# ${PROJECT_NUM}_${PROJECT_NAME} - 接口定义
## API 列表
## 数据结构
EOF
# 创建 README.md
echo "# ${PROJECT_NAME} - src" > "${PROJECT_DIR}/src/README.md"
echo "# ${PROJECT_NAME} - tests" > "${PROJECT_DIR}/tests/README.md"
# 创建示例任务
mkdir -p "review/active/${PROJECT_NUM}-001/feedback"
cat > "review/active/${PROJECT_NUM}-001/task.md" << EOF
# ${PROJECT_NUM}-001 - 项目初始化
## 任务信息
- 任务编号：${PROJECT_NUM}-001
- 项目：${PROJECT_NUM}_${PROJECT_NAME}
- 创建时间：$(date +%Y-%m-%d)
- 状态：TODO
## 任务描述
完成 ${PROJECT_NAME} 项目的初始化工作。
## 交付物
- 项目目录结构
- 基础配置文件
- README 文档
EOF
cat > "review/active/${PROJECT_NUM}-001/acceptance.md" << EOF
# ${PROJECT_NUM}-001 - 验收标准
## 功能验收
- [ ] 项目目录结构完整
- [ ] ENVIRONMENT.md 已创建
- [ ] 文档目录已初始化
## 测试覆盖要求
- 无需测试（初始化任务）
EOF
cat > "review/active/${PROJECT_NUM}-001/impact.md" << EOF
# ${PROJECT_NUM}-001 - 变更影响范围
## 修改的文件
| 文件路径 | 修改类型 | 影响等级 |
|---------|---------|---------|
| ${PROJECT_DIR}/ | 新增 | LOW |
## 影响的功能模块
- [x] 项目初始化
## 需要回归测试的场景
- 无（新项目）
## 环境依赖变更
- 无
EOF
cat > "review/active/${PROJECT_NUM}-001/feedback/round1.md" << EOF
# ${PROJECT_NUM}-001 - 第一轮测试反馈
## 基本信息
- 测试时间: $(date +%Y-%m-%d)
- 测试项目: ${PROJECT_NUM}_${PROJECT_NAME}
- 测试环境: 待配置
## 测试结果概览
| 指标 | 数值 |
|------|------|
| 测试用例总数 | 0 |
| 通过 | 0 |
| 失败 | 0 |
| 跳过 | 0 |
| 代码覆盖率 | 0% |
## 反馈
待 Dev AI 完成开发后执行测试
EOF
# 更新 README.md（如果存在）
if [ -f README.md ]; then
echo "- [${PROJECT_NUM}_${PROJECT_NAME}](${PROJECT_DIR})" >> README.md
fi
echo "✅ 子项目 ${PROJECT_NUM}_${PROJECT_NAME} 创建成功！"
echo "📖 请阅读 AGENTS.md 了解协作规则"
echo "🚀 在 review/active/${PROJECT_NUM}-001/ 下查看示例任务结构"
```
## 使用场景
**何时调用此 skill：**
- ✅ 添加新的 Web 管理程序
- ✅ 添加数据录入程序
- ✅ 添加任何新的子项目模块
- ✅ 扩展现有项目架构
**不适用场景：**
- ❌ 项目尚未初始化（需先调用 ai-collab-setup）
- ❌ 修改现有项目结构
## 后续步骤
skill 执行后：
1. 检查 `projects/${PROJECT_NUM}_${PROJECT_NAME}/` 目录结构
2. 阅读 `review/active/${PROJECT_NUM}-001/task.md` 示例任务
3. 根据实际需求修改 `task.md` 为真实任务
4. Dev AI 开始开发
---
**Version**: 2.0
**Created**: 2026-05-22
**Updated**: 2026-05-23
**Based On**: ErrLens AI Programming Project
**Changes from v1**:
- 目录结构新增 src/server/、src/config/、src/types/ 子目录
- 示例任务增加完整的 feedback/round1.md 格式（含基本信息表格）
- impact.md 增加「影响的功能模块」和「环境依赖变更」段落
- 脚本兼容 Windows PowerShell 和 Linux/macOS
- ENVIRONMENT.md 默认使用 pnpm 包管理器
.trae/skills/ai-collab-setup/SKILL.md
-1183
View File
File diff suppressed because it is too large Load Diff
.trae/skills/git/SKILL.md
-173
View File
@@ -1,173 +0,0 @@
---
name: "git"
description: "Wraps common git operations as parameterized actions. Invoke when user wants to commit, push, pull, branch, or check git status."
---
# Git Skill
## 功能
将常用 git 操作封装为参数化动作，避免频繁手动提交，统一管理版本控制。
## 触发条件
- 用户要求提交代码
- 用户要求查看状态/日志/差异
- 用户要求创建/切换分支
- 用户要求拉取/推送代码
- 用户要求回退/重置
## 参数说明
| 参数 | 说明 | 示例 |
|------|------|------|
| `action` | 操作类型 | status, add, commit, push, pull, branch, log, diff, stash, reset |
| `message` | 提交信息（commit 时必填） | "feat(P01-001): 实现用户登录" |
| `branch` | 分支名（branch/push/pull 时使用） | feature/P01-001-login |
| `files` | 指定文件（add 时使用，默认全部） | ["src/login.ts", "tests/login.test.ts"] |
| `force` | 强制操作（push/reset 时使用） | true/false |
| `count` | 日志条数（log 时使用） | 10 |
## 操作类型
### 1. status - 查看状态
```bash
git status
git status -s # 简洁模式
```
**输出**：显示已修改、已暂存、未跟踪的文件
### 2. add - 添加文件
```bash
git add -A # 添加所有变更
git add <files> # 添加指定文件
git add -p # 交互式选择（逐块确认）
```
### 3. commit - 提交
**提交信息格式**（必须遵循 AGENTS.md 命名规范）：
```
<type>(<scope>): <subject>
<body>
<footer>
```
| type | 说明 |
|------|------|
| feat | 新功能 |
| fix | Bug 修复 |
| docs | 文档更新 |
| style | 代码格式（不影响功能） |
| refactor | 重构 |
| test | 测试相关 |
| chore | 构建/工具链 |
**示例**：
```
feat(P01-001): 实现用户登录功能
- 添加登录页面组件
- 实现微信授权登录
- 添加登录状态管理
Closes #123
```
### 4. push - 推送
```bash
git push # 推送到当前分支
git push origin <branch> # 推送到指定分支
git push -u origin <branch> # 首次推送并设置上游
git push --force # 强制推送（谨慎使用）
```
### 5. pull - 拉取
```bash
git pull # 拉取并合并
git pull --rebase # 拉取并变基
```
### 6. branch - 分支管理
```bash
git branch # 查看本地分支
git branch -a # 查看所有分支
git branch <name> # 创建分支
git checkout <name> # 切换分支
git checkout -b <name> # 创建并切换
git branch -d <name> # 删除分支
```
### 7. log - 查看日志
```bash
git log --oneline -<count> # 简洁日志
git log --graph --oneline # 图形化
git log --since="2026-05-20" # 按日期过滤
```
### 8. diff - 查看差异
```bash
git diff # 未暂存变更
git diff --cached # 已暂存变更
git diff HEAD # 所有变更
git diff <file> # 指定文件
```
### 9. stash - 暂存
```bash
git stash # 暂存当前变更
git stash list # 查看暂存列表
git stash pop # 恢复最新暂存
git stash apply <stash@{n}> # 应用指定暂存
```
### 10. reset - 重置
```bash
git reset --soft HEAD~1 # 撤销提交，保留变更
git reset --mixed HEAD~1 # 撤销提交，变更回暂存区
git reset --hard HEAD~1 # 撤销提交，丢弃变更（危险）
```
## 执行流程
### 提交流程（commit + push）
1. `git status` - 查看当前状态
2. `git add -A` 或 `git add <files>` - 添加文件
3. `git diff --cached` - 确认变更内容
4. `git commit -m "<message>"` - 提交
5. `git push` - 推送（如用户要求）
### 分支创建流程
1. `git branch` - 查看当前分支
2. `git checkout -b <branch>` - 创建并切换
3. 提示用户后续提交将在此分支进行
## 注意事项
1. **提交频率**：不要每改一个文件就提交，按功能/任务粒度提交
2. **提交信息**：必须遵循 AGENTS.md 命名规范，包含项目编号和任务编号
3. **推送前确认**：推送前必须让用户确认，除非明确要求
4. **强制推送**：必须明确警告用户，确认后才能执行
5. **冲突处理**：遇到合并冲突时，先展示冲突文件，让用户决定如何处理
6. **文档同步**：代码提交后，提醒用户使用 `update-docs` Skill 同步文档
---
**Version**: 1.0
**Created**: 2026-05-23
**Based On**: ErrLens AI Programming Project
**Purpose**: 统一管理 git 操作，避免频繁提交，确保提交信息规范
.trae/skills/project-init/SKILL.md
-107
View File
@@ -1,107 +0,0 @@
---
name: "project-init"
description: "框架脱敏/初始化：将当前项目框架层导出为通用模板，或从模板初始化新项目。用户说「导出框架」「初始化新项目」「套这个框架开新项目」时调用。"
---
# 项目框架脱敏与初始化
## 功能
将当前项目的「框架层」（AI 协作体系）与「项目层」（ErrLens 具体内容）分离。框架层可导出为通用模板，用于初始化任意新项目。
**核心逻辑**：框架是骨架（角色、权限、工作流、Skill），项目是肉（PRD、架构、代码、ADR）。同一套骨架可以长出不同的肉。
## 触发条件
- 用户说「导出框架」「脱敏」「生成模板」
- 用户说「初始化新项目」「套这个框架开新项目」「用这个骨架开个 IC 验证项目」
- 当前项目框架层有重大更新后，用户想刷新模板
## 两个模式
### Export（脱敏导出）
将当前项目框架层文件复制 → 把 ErrLens 具体值替换为 `{{变量}}` → 输出干净的模板目录。
### Init（初始化新项目）
读取模板 → 把 `{{变量}}` 替换为用户提供的新项目值 → 输出可开工的新项目目录。
## 变量定义
见 `TEMPLATE.yaml`。核心变量：
| 变量 | 当前值（ErrLens） | 说明 |
|------|-------------------|------|
| `{{PROJECT_NAME}}` | ErrLens | 项目名 |
| `{{PROJECT_CONCEPT}}` | 学生错题本 | 核心概念 |
| `{{PROJECT_DESCRIPTION}}` | AI 驱动的学生错题整理与分析应用 | 一句话描述 |
| `{{P01_NAME}}` | P01_errlens_app | 主应用目录名 |
| `{{DATABASE_URL}}` | postgresql://.../errlens | 数据库连接 |
## 框架层 vs 项目层
见 `SYNC.md`。核心区分：
**框架层（导出/同步）**：
- `AGENTS.md` — AI 角色+权限
- `dashboard.md` — 控制面板结构
- `DECISIONS.md` — 决策入口
- `.ai/principles.md` — 设计原则
- `.ai/config/` — AI 配置
- `.ai/prompts/` — 提示词模板
- `.ai/roles/*/card.md` — 角色身份卡
- `.ai/phases/INDEX.md` — 阶段索引
- `.ai/knowledge/patterns.md` — 可复用模式
- `.ai/knowledge/lessons.md` — 框架级教训
- `.ai/tasks/templates/` — Task 模板
- `.trae/skills/` — 全部 Skill
- `docs/使用手册.md` — 使用说明
- `ENVIRONMENT.md` — 环境结构
- `TEMPLATE.yaml` — 变量定义
- `SYNC.md` — 边界定义
**项目层（不导出，新项目自己写）**：
- `.ai/tasks/active/` — 具体 task
- `.ai/phases/phase-*/goal.md, scope.md, architecture.md, decisions.md, completion.md`
- `.ai/knowledge/decisions.md` — 项目 ADR
- `.ai/knowledge/journal/` — 开发日志
- `docs/01_*/ ~ docs/06_*/` — PRD、架构设计等
- `docs/share/` — 对外分享
- `projects/` — 代码
- `reports/` — 测试报告
## 执行步骤
### Export 模式
1. 读 `SYNC.md` 确认框架层文件清单
2. 读 `TEMPLATE.yaml` 获取变量清单和当前值
3. 对每个框架层文件：
- 复制内容
- 将当前值（如 `ErrLens`）替换为 `{{PROJECT_NAME}}`
- 将 `errlens` 替换为 `{{PROJECT_NAME_LOWER}}`
- 依此类推，覆盖 TEMPLATE.yaml 中所有变量
4. 输出到指定目录（默认 `../project-template/`）
### Init 模式
1. 询问用户：项目名、核心概念、一句话描述
2. 读 `TEMPLATE.yaml`，生成新值（如 `PROJECT_NAME: "ICValidator"`）
3. 复制框架层文件到新项目目录
4. 将所有 `{{变量}}` 替换为新值
5. 创建项目层空目录结构（.ai/tasks/active/, .ai/phases/, docs/01_产品需求/ 等）
6. 告知用户：新项目就绪，Arch AI 可以开始写 PRD
## 注意事项
1. **框架层不包含具体业务的 ADR**。ADR-009（人机协同）是 ErrLens 特有的，不导出。ADR-007（分层架构）是框架级的，可导出
2. **Skill 本身属于框架层**，会被导出。新项目自带全套 Skill
3. **TEMPLATE.yaml 导出后变量值变为 `{{}}` 占位符**，等待 init 时填入新值
4. **脱敏检查**：export 后应人工抽查，确保没有 ErrLens 特有信息泄露到模板
---
**Version**: 1.0
**Created**: 2026-05-26
**Based On**: ADR-008（模板同步机制），废弃 ai_project 分支方案，改为 Skill 按需执行
.trae/skills/resume-context/SKILL.md
-195
View File
@@ -1,195 +0,0 @@
---
name: "resume-context"
description: "Loads project context and syncs conversation history. Invoke when user switches computers, starts a new session, or says '接着干 开发'、'接着干 测试'、'接着干 架构'."
---
# 接着干 - 上下文同步 Skill
## 功能
当用户更换电脑、开启新会话、或说"接着干"时，自动读取项目上下文文档，恢复之前的开发状态和讨论背景，并根据用户指定的角色设定 AI 权限。
## 触发条件
用户必须使用以下格式之一：
| 触发词 | 角色 | 权限 |
|--------|------|------|
| `接着干 开发` | Dev AI | 按宪法约束（coder.json） |
| `接着干 测试` | QA AI | 按宪法约束（tester.json） |
| `接着干 架构` | 人类负责人 | 最高权限，不受宪法约束 |
**别名**：`继续 开发/测试/架构`、`resume dev/test/arch`
## 执行步骤
### 1. 识别角色
根据用户输入的后缀词判断角色：
```
开发/dev/coder → Dev AI
测试/test/qa → QA AI
架构/arch → Arch AI（架构设计师）
```
### 2. 读取项目上下文
按以下顺序读取核心文档：
```
1. docs/PROJECT_CONTEXT.md # 项目整体上下文
2. docs/DECISIONS.md # 关键决策记录
3. docs/06_开发日志/ # 最新开发日志（按日期倒序）
4. AGENTS.md # AI 角色和权限约定
```
### 3. 加载角色配置
根据识别的角色，读取对应的配置文件：
**Arch AI**：
```
.ai/config/architect.json
```
- 读取 `allowed_paths`、`read_only_paths`、`forbidden_paths`
- 读取 `responsibilities`
- 读取 `prompt_templates`
- **拥有最高 AI 权限**，可以进行架构设计和跨模块修改
**Dev AI**：
```
.ai/config/coder.json
```
- 读取 `allowed_paths`、`read_only_paths`、`forbidden_paths`
- 读取 `responsibilities`
- 读取 `prompt_templates`
**QA AI**：
```
.ai/config/tester.json
```
- 读取 `allowed_paths`、`read_only_paths`、`forbidden_paths`
- 读取 `responsibilities`
- 读取 `prompt_templates`
### 4. 读取最新开发日志
```powershell
# 获取最新的开发日志文件
Get-ChildItem "docs/06_开发日志/" -Filter "*.md" | Sort-Object Name -Descending | Select-Object -First 3
```
读取最近 3 篇日志，了解最近的讨论内容。
### 5. 同步状态
向用户报告当前状态和角色：
```markdown
## 上下文同步完成
### 当前角色
- **角色**: [Dev AI / QA AI / 人类负责人]
- **权限**: [按宪法约束 / 最高权限]
- **可写路径**: [列出 allowed_paths]
- **只读路径**: [列出 read_only_paths]
### 项目状态
- **当前阶段**: [从 PROJECT_CONTEXT.md 读取]
- **最新任务**: [从 review/active/ 读取最新任务]
- **最近工作**: [从最新开发日志读取]
### 待办事项
- [从 PROJECT_CONTEXT.md 和开发日志中提取]
### 可以继续的工作
- [列出可以继续开发的任务]
```
### 6. 确认用户意图
询问用户：
- 继续上次未完成的工作？
- 开始新的任务？
- 查看项目状态？
## 文档格式要求
### PROJECT_CONTEXT.md
```markdown
# 项目上下文
## 项目愿景
[一句话描述项目目标]
## 当前阶段
[当前处于哪个阶段，已完成什么]
## 技术栈
[主要技术选型]
## 团队架构
[1 人 + 2AI 协作模式]
## 关键决策
[列出重要决策和原因]
## 待解决问题
[列出悬而未决的问题]
## 下一步计划
[接下来的工作重点]
```
### 开发日志格式
```markdown
# YYYY-MM-DD_主题
## 讨论内容
[主要讨论了什么]
## 关键决策
[做出了什么决定]
## 完成的工作
[做了什么改动]
## 待办事项
[接下来要做什么]
```
## 使用场景
**何时调用此 skill：**
- ✅ 更换电脑后开始工作
- ✅ 开启新会话，需要恢复上下文
- ✅ 长时间未开发，需要回忆项目状态
- ✅ 用户说"接着干 开发/测试/架构"
**不适用场景：**
- ❌ 首次启动项目（应使用 ai-collab-setup）
- ❌ 只需要查看代码（直接搜索即可）
## 注意事项
1. **角色必须明确**：用户必须指定"开发"、"测试"或"架构"，否则询问用户
2. **架构模式**：架构模式对应 Arch AI，拥有最高 AI 权限，可以进行架构设计和跨模块修改
3. **不要修改文档**：此 skill 只读取上下文，不修改任何文件（除非用户明确要求）
4. **关注最新内容**：优先读取最新的开发日志
5. **识别阻塞点**：注意 PROJECT_CONTEXT.md 中的"待解决问题"
6. **权限意识**：开发/测试/架构模式下严格遵循 AGENTS.md 中的权限约定
---
**Version**: 3.0
**Created**: 2026-05-23
**Updated**: 2026-05-23
**Based On**: ErrLens AI Programming Project
**Purpose**: 解决用户多电脑切换时的上下文同步问题，明确 AI 角色和权限
**Changes from v2.0**:
- 架构模式从"人类负责人"改为"Arch AI（架构设计师）"
- 新增 .ai/config/architect.json 配置读取
- 支持"1 人+3AI"协作模式
.trae/skills/share-context/SKILL.md
-136
View File
@@ -1,136 +0,0 @@
---
name: "share-context"
description: "一鸡多吃：将内部开发文档（ADR、阶段复盘、开发日志）翻译为对外分享文章。阶段收尾时或用户说「一鸡多吃」「同步分享」「发布分享」时调用。"
---
# 一鸡多吃 — 内部文档转对外分享 Skill
## 功能
将开发过程中积累的内部文档（架构决策、阶段完成记录、踩坑经验）翻译为对外可发布的分享文章，写入 `docs/share/` 目录。
**核心逻辑**：同一份工作，两种产出。内部文档（给 AI 看）→ 去敏 + 加故事 + 加思考过程 → 对外文章（给人看）。
## 触发条件
- 用户说「一鸡多吃」「同步分享」「发布分享」「更新分享」
- 阶段收尾时（Phase completion）
- 有新的 ADR 或重要决策产生后
## 执行步骤
### 0. 反向检查：知识库是否遗漏了有价值的洞察
**在扫描对外分享内容之前**，先检查是否有最近的开发讨论/决策/想法尚未写入知识库：
| 检查项 | 判断标准 | 写入目标 |
|--------|---------|---------|
| 近期是否有重要的架构讨论 | 讨论产生了「可复用的判断」或「方向性决策」 | `.ai/knowledge/decisions.md`（新 ADR） |
| 近期是否有反直觉的发现或错误 | 讨论产生了「原来以为…但其实…」的洞察 | `.ai/knowledge/lessons.md`（新 L-XXX） |
| 近期是否发现了可复用的模式 | 同样的做法出现了 2 次以上 | `.ai/knowledge/patterns.md`（新 P-XXX） |
**触发词**：当讨论中出现以下信号时，应主动提议记录：
- 「这个很有价值」「值得记下来」「下次遇到可以…」
- 「原来是这样」「之前没想到」「反直觉的是…」
- 领域术语的定义或边界划分（如「蜂群模式」「编排器-执行者」）
如果发现遗漏，**先补知识库，再执行后续步骤**。知识库是分享的源头——源头空了，一鸡多吃也无米下锅。
### 1. 扫描内部文档，识别可分享内容
按以下来源对比 `docs/share/` 已有内容，找出新增/变化：
| 内部来源 | 对应对外产出 | 判断标准 |
|---------|-------------|---------|
| `.ai/knowledge/decisions.md` 中的新 ADR | `phase-XX/决策故事_ADR-XXX.md` | 有新 ADR 且无对应故事文件 |
| `.ai/phases/phase-XX-*/completion.md` | `phase-XX/阶段复盘_XXX.md` | 阶段已完成且复盘文件为空/待写 |
| `.ai/knowledge/lessons.md` | 踩坑记录（融入复盘或独立） | 有新的经验教训记录 |
| `.ai/knowledge/journal/` | 开发周记 | 有新的日志文件 |
### 2. 确定本次要写的文章
列出待写文章清单，向用户确认优先级和范围。
### 3. 逐篇撰写
每篇文章遵循以下原则：
**内容要求**：
- 不只说「做了什么」，重点说「为什么这么选」
- 有具体的决策场景（当时遇到了什么问题）
- 有可复用的方法论（下次遇到类似情况怎么做）
- 有真实的踩坑和教训（不粉饰）
- 一句话总结（可引用/可传播）
**安全要求**：
- ❌ 不暴露 API 密钥、服务器地址、数据库连接串
- ❌ 不暴露真实用户名、手机号、微信号
- ❌ 不暴露未公开的第三方合作信息
- ✅ 技术方案可以详细写
- ✅ 决策过程可以完整写
- ✅ 思考逻辑可以展开写
**写作风格**：
- 第一人称（「我」），人类视角
- 像讲故事，不像写文档
- 目标读者是「对 AI 编程感兴趣的人」，不是机器
- 每篇 800-1500 字，独立可读
### 4. 更新分享目录
更新 `docs/share/README.md` 中的文章列表和状态。
### 5. 告知用户
```markdown
## 一鸡多吃完成
### 新增文章
| 文件 | 内容 |
|------|------|
| [文章名](路径) | 一句话描述 |
### 更新文章
| 文件 | 变更 |
|------|------|
| [文章名](路径) | 更新内容简述 |
### 分享目录
→ `docs/share/README.md`
```
## 文件结构
```
docs/share/
├── README.md # 分享目录索引
├── 00_项目缘起.md # 项目背景（一次性写完，后续微调）
├── 01_框架设计思路.md # 核心理念（一次性写完，后续微调）
├── phase-01/ # Phase 1 分享内容
│ ├── 阶段复盘_基础搭建.md # 阶段复盘
│ ├── 决策故事_ADR-007.md # 信息架构决策
│ ├── 决策故事_ADR-009.md # 人机协同决策
│ └── 决策故事_旧架构合并.md # 旧架构合并决策
├── phase-02/ # Phase 2 分享内容（待产生）
│ └── ...
└── templates/ # 写作模板
├── 阶段复盘模板.md
└── 决策故事模板.md
```
## 注意事项
1. **先入库，后分享**：Step 0 必须在 Step 1 之前执行。知识库是米缸，分享是做饭——米缸空了做不出饭
2. **不是做完再写**：开发过程中自动积累，阶段结束时批量产出
3. **同一份工作，两种语言**：内部文档是「给 AI 看的结构化数据」，对外文章是「给人看的故事」
4. **保持真诚**：有成功写成功，有失败写失败。读者能看出哪些是 PR 稿
5. **去敏但不去肉**：去掉敏感信息，但保留具体细节。一个没有细节的故事没有价值
6. **链接内部来源**：每篇文章底部可附「内部参考：ADR-XXX」但不暴露内部文件路径
---
**Version**: 1.1
**Updated**: 2026-05-26 — 新增 Step 0「反向检查」，补上知识库摄入端
**Created**: 2026-05-26
**Based On**: ErrLens 开发实践 — Phase 1 收尾时的「一鸡多吃」流程
**Purpose**: 将内部开发文档自动转化为对外分享内容，实现「开发即内容」的闭环
.trae/skills/switch-model/SKILL.md
-143
View File
@@ -1,143 +0,0 @@
---
name: "switch-model"
description: "Checks project context when switching AI models. Invoke when user says '切换模型 架构/开发/测试' or 'switch-model arch/dev/qa'."
---
# 切换模型 Skill
## 功能
当用户更换大模型（Claude/TRAE/扣子/元宝等）时，快速加载项目上下文，确保新模型理解当前状态并遵循规则。
## 触发条件
**必须指定角色**：
- `切换模型 架构` / `switch-model arch` → Arch AI
- `切换模型 开发` / `switch-model dev` → Dev AI
- `切换模型 测试` / `switch-model qa` → QA AI
**不指定角色时**：询问用户，不执行全面检查。
## 执行步骤
### 1. 识别角色
| 触发词 | 角色 | 配置文件 |
|--------|------|---------|
| 架构/arch | Arch AI | .ai/config/architect.json |
| 开发/dev/coder | Dev AI | .ai/config/coder.json |
| 测试/test/qa | QA AI | .ai/config/tester.json |
### 2. 安全检查（git 状态优先）
**必须先检查 git 仓库状态，确保在安全的环境下加载上下文**：
```bash
git status # 工作区状态（干净/有变更/有冲突）
git log --oneline -3 # 最近 3 次提交（了解最近做了什么）
git branch # 当前分支（确认是否在正确分支）
```
**异常处理**：
| 状态 | 处理方式 |
|------|---------|
| 工作区有未提交变更 | 提醒用户先提交或暂存，避免上下文不一致 |
| 有合并冲突 | 立即告知用户需要解决冲突 |
| 分支不对 | 提醒用户切换到正确分支 |
| 远程有更新未拉取 | 提醒用户先 pull |
### 3. 加载基础上下文（所有角色通用）
```
1. AGENTS.md # 团队架构和权限矩阵
2. .ai/config/workflow.json # 工作流配置
3. docs/PROJECT_CONTEXT.md # 项目整体状态
```
### 4. 按角色加载专属上下文
#### Arch AI（架构AI）
```
4. .ai/config/architect.json # 角色权限
5. docs/02_系统架构/ # 架构文档
6. review/active/*/task.md # 活跃任务
7. .trae/skills/ # 可用 Skill 列表
8. ENVIRONMENT.md # 环境配置
```
#### Dev AI（编码AI）
```
4. .ai/config/coder.json # 角色权限
5. review/active/*/task.md # 活跃任务
6. review/active/*/feedback/ # 待修 Bug
7. .trae/skills/ # 可用 Skill 列表
8. ENVIRONMENT.md # 环境配置
```
#### QA AI（测试AI）
```
4. .ai/config/tester.json # 角色权限
5. review/active/*/acceptance.md # 验收标准
6. reports/test-results/ # 最近测试报告
7. .trae/skills/ # 可用 Skill 列表
8. ENVIRONMENT.md # 环境配置
```
### 5. 输出简洁检查报告
```markdown
# 模型切换检查报告
## 角色确认
- 当前角色: [角色名]
- 权限: [可写路径] | 只读: [只读路径] | 禁止: [禁止路径]
## 项目状态
- 当前阶段: [工作流阶段]
- 活跃任务: [任务编号和名称]
- 工作区: [干净/有变更]
## 最近提交 (3 条)
- [commit 1]
- [commit 2]
- [commit 3]
## 待办事项
- [ ] [待办 1]
- [ ] [待办 2]
## 阻塞点
- [无 / 具体问题]
✅ 已就绪，等待指令
```
### 6. 等待用户指令
报告输出后，等待用户进一步指令。用户可以说：
- `展开 [某项]` → 深入查看细节
- `开始工作` → 进入角色模式
- `切换角色` → 重新执行本 Skill
## 注意事项
1. **必须指定角色**：不指定时询问用户，不盲目全面检查
2. **简洁优先**：报告控制在 1 屏内，用户需要细节时可展开
3. **权限意识**：加载配置后立即确认权限边界
4. **不修改文件**：此 Skill 只读取上下文，不修改任何文件
5. **Skill 列表**：确保新模型知道有哪些 Skill 可用
---
**Version**: 1.1
**Created**: 2026-05-23
**Updated**: 2026-05-23
**Based On**: ErrLens AI Programming Project
**Purpose**: 确保大模型切换时快速同步上下文，按角色差异化加载
**Changes from v1.0**:
- 新增安全检查步骤，git 状态优先于上下文加载
- 增加异常处理（未提交变更/合并冲突/分支错误/远程更新）
.trae/skills/update-constitution/SKILL.md
-95
View File
@@ -1,95 +0,0 @@
---
name: "update-constitution"
description: "Updates AI constitution files (AGENTS.md, config files, permission matrix). Invoke when AI roles, permissions, or workflow rules change."
---
# 更新宪法 Skill
## 功能
当 AI 角色、权限、工作流规则发生变更时，自动更新所有相关的宪法文件，确保一致性。
## 触发条件
- AI 角色增加/删除/修改
- 权限矩阵变更（allowed_paths、read_only_paths、forbidden_paths）
- 工作流阶段变更
- 沟通规范变更
- 命名规范变更
## 执行步骤
### 1. 识别变更类型
| 变更类型 | 影响文件 |
|---------|---------|
| 新增 AI 角色 | AGENTS.md、.ai/config/<role>.json、workflow.json、权限矩阵 |
| 权限变更 | AGENTS.md 权限矩阵、.ai/config/*.json |
| 工作流变更 | AGENTS.md 工作流程图、workflow.json |
| 沟通规范变更 | AGENTS.md 沟通规范章节 |
| 命名规范变更 | AGENTS.md 命名规范章节 |
### 2. 更新宪法文件
按以下顺序更新：
#### 2.1 AGENTS.md
- [ ] 更新团队架构图
- [ ] 更新角色职责（新增/修改/删除）
- [ ] 更新目录权限矩阵
- [ ] 更新工作流程图（如适用）
- [ ] 更新详细流程说明（如适用）
- [ ] 更新 AI 配置文件说明表
#### 2.2 .ai/config/*.json
- [ ] 新增/更新对应角色的 JSON 配置文件
- [ ] 确保 allowed_paths、read_only_paths、forbidden_paths 与权限矩阵一致
- [ ] 确保 responsibilities 与角色职责一致
- [ ] 确保 prompt_templates 指向正确的提示词目录
#### 2.3 .ai/config/workflow.json
- [ ] 更新 roles 数组
- [ ] 更新 stages 数组（新增/修改/删除阶段）
- [ ] 确保 actor 字段与角色 ID 一致
### 3. 更新 Skill 文件
- [ ] .trae/skills/ai-collab-setup/SKILL.md - 目录结构、权限矩阵、角色描述、配置文件示例
- [ ] .trae/skills/resume-context/SKILL.md - 角色识别逻辑、配置文件读取
### 4. 验证一致性
- [ ] AGENTS.md 权限矩阵 与 .ai/config/*.json 路径配置一致
- [ ] AGENTS.md 角色职责 与 .ai/config/*.json responsibilities 一致
- [ ] AGENTS.md 工作流程图 与 workflow.json stages 一致
- [ ] 所有 JSON 文件语法正确（使用 python -m json.tool 验证）
### 5. 提交 Git
```bash
git add -A
git commit -m "feat(constitution): 更新宪法 - [简要描述变更内容]
- AGENTS.md: [具体变更]
- .ai/config/*.json: [具体变更]
- workflow.json: [具体变更]
- ai-collab-setup/SKILL.md: [具体变更]"
git push
```
## 注意事项
1. **权限矩阵是核心**：所有路径变更必须先更新权限矩阵，再同步到 JSON 配置
2. **JSON 语法验证**：每次修改后必须验证 JSON 语法
3. **Skill 文件同步**：宪法变更后必须同步更新 ai-collab-setup 和 resume-context Skill
4. **版本号**：重大变更需升级 Skill 版本号
---
**Version**: 1.0
**Created**: 2026-05-23
**Based On**: ErrLens AI Programming Project
**Purpose**: 确保宪法变更时所有相关文件同步更新，避免遗漏
.trae/skills/update-docs/SKILL.md
-103
View File
@@ -1,103 +0,0 @@
---
name: "update-docs"
description: "Updates project documentation (README.md, changelog, PROJECT_CONTEXT.md, etc.). Invoke after any code/structure change to keep docs in sync."
---
# 更新文档 Skill
## 功能
在任何代码、结构、配置变更后，自动更新所有相关的项目文档，确保文档与实际状态一致。
## 触发条件
- 目录结构变更（新增/删除/重命名目录）
- 角色/权限变更（宪法更新后）
- 工作流变更
- Skill 文件变更
- 任何可能影响文档的变更
## 执行步骤
### 1. 识别变更影响范围
| 变更类型 | 需更新的文档 |
|---------|-------------|
| 目录结构变更 | README.md 目录树、PROJECT_CONTEXT.md 结构图 |
| 角色/权限变更 | README.md 团队角色表、PROJECT_CONTEXT.md |
| 工作流变更 | README.md 工作流程、PROJECT_CONTEXT.md |
| Skill 文件变更 | README.md（如提及 Skill） |
| 任何提交 | 变更日志 |
### 2. 更新文档
按以下顺序更新：
#### 2.1 README.md
- [ ] 更新项目描述（如适用）
- [ ] 更新目录结构树
- [ ] 更新团队角色表
- [ ] 更新工作流程说明
- [ ] 更新任务状态流转（如适用）
#### 2.2 docs/PROJECT_CONTEXT.md
- [ ] 更新当前阶段
- [ ] 更新项目结构图
- [ ] 更新关键决策（如适用）
- [ ] 更新待解决问题（如适用）
- [ ] 更新下一步计划
#### 2.3 docs/05_变更日志/YYYY-MM-DD.md
- [ ] 创建今日日志文件（如不存在）
- [ ] 添加本次提交记录
- [ ] 包含 commit hash、简要描述、具体变更
#### 2.4 docs/DECISIONS.md（如适用）
- [ ] 新增架构决策记录（ADR）
- [ ] 格式：背景、决策、原因、后果
#### 2.5 docs/06_开发日志/YYYY-MM-DD_主题.md（如适用）
- [ ] 记录讨论内容
- [ ] 记录关键决策
- [ ] 记录完成的工作
- [ ] 记录待办事项
### 3. 验证一致性
- [ ] README.md 目录树 与实际目录结构一致
- [ ] README.md 团队角色表 与 AGENTS.md 一致
- [ ] README.md 工作流程 与 workflow.json 一致
- [ ] PROJECT_CONTEXT.md 结构图 与实际一致
- [ ] 变更日志包含所有今日提交
### 4. 提交 Git
```bash
git add -A
git commit -m "docs(readme): 同步文档 - [简要描述]
- README.md: [具体变更]
- PROJECT_CONTEXT.md: [具体变更]
- docs/05_变更日志/YYYY-MM-DD.md: [具体变更]"
git push
```
## 注意事项
1. **变更日志是必须的**：每次提交都必须更新变更日志，不能忘
2. **README.md 是门面**：项目的第一印象，必须保持最新
3. **PROJECT_CONTEXT.md 是上下文**：换电脑后 AI 读取的核心文档
4. **不要过度更新**：只更新受影响的文档，不要全量重写
5. **保持简洁**：文档更新提交信息要简洁明了
---
**Version**: 1.0
**Created**: 2026-05-23
**Based On**: ErrLens AI Programming Project
**Purpose**: 确保文档与代码/结构同步更新，避免"繁文缛节"被遗忘
AGENTS.md
+70 -230
View File
@@ -1,271 +1,111 @@
# MCU芯片测试 AI 角色定义与权限约定
# AI 角色定义与权限约定
## 团队架构
```
┌─────────────────────────────────────────────┐
│ 人类负责人 │
│ 需求分析 · 架构设计 · 最终决策 │
└───────────────┬───────────┬─────────────────┘
│ │
┌───────────┴──┐ ┌────┴────────────┐
▼ ▼ ▼ ▼
┌───────────────┐ ┌──────────────┐
│ Arch AI │ │ 执行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 驱动提炼
- **人类** — 需求输入、最终决策、硬件验证、成果验收
| 资源类型 | 存放位置 | 用途 |
|---------|---------|------|
| Excel 寄存器表格 | `docs/00_芯片资料/registers/` | Arch AI 分析芯片功能，生成寄存器定义头文件 |
| 串口 printf Demo 工程 | `projects/P01_chip_test/demo/` | 执行AI 基于该工程扩展测试功能 |
| 芯片手册 | `docs/00_芯片资料/datasheet/` | 参考文档 |
**核心理念**：测试驱动 SDK 演进。寄存器测试是 SDK 的第一用户，测试代码直接提炼为 LL 层驱动。
---
## 工作流
```
需求分析(Arch) → 架构设计(Arch) → 任务拆解(Arch)
→ 开发实现(Worker) → 自测(Worker) → 人类硬件验证
→ 勘误记录(Worker) → LL提炼(Worker) → HAL封装(Worker)
↑
Bug修复(Worker, 最多3轮)
```
缺陷修复循环：最多 3 轮。第 3 轮仍有 BLOCKER → 升级给人类 + Arch AI 裁决。
---
## 角色职责
### Arch AI (架构AI)
**职责范围：**
- ✅ 芯片功能需求分析和测试规划
- ✅ 解析 Excel 寄存器表格，生成头文件
- ✅ 测试架构设计和测试方案制定
- ✅ 编译器选择和环境配置方案
- ✅ JTAG调试流程设计
- ✅ 串口日志分析方案
- ✅ 编写测试架构文档 (`docs/`)
- ✅ 定义验收标准 (`review/*/acceptance.md`)
- ✅ 评估测试结果影响 (`review/*/impact.md`)
- ✅ 维护共享资源 (`shared/`)
- ✅ 维护测试工具 (`tools/`)
- ✅ 指导执行AI工作
### Arch AI
- 可写：架构文档、验收标准、任务定义、知识库、共享资源、开发工具、SDK 设计文档
- 只读：测试代码、测试报告、勘误详情
- 指导 Worker AI 工作，分配任务队列，审查产出质量
**可读但不可写：**
- 👁 AI 配置文件 (`.ai/`) —— 只读，了解团队规则
- 👁 测试报告 (`reports/`) —— 只读，了解测试结果
- 👁 测试反馈 (`review/*/feedback/`) —— 只读，了解问题
### Worker AI
- 可写：业务代码、测试代码、测试报告、技术文档、开发工具、勘误记录、LL/HAL 驱动代码
- 只读：AI 配置、任务定义（不可修改 task 内容）
- 禁止：.ai/ 目录结构修改、dashboard.md 修改
**禁止操作：**
- ❌ 无（架构 AI 拥有最高 AI 权限）
### 执行AI (Executor AI)
**职责范围：**
- ✅ 编写测试固件代码 (`projects/*/src/`)
- ✅ 配置编译环境 (Arm Clang / Keil MDK / Arm GCC)
- ✅ 通过JTAG调试下载固件 (`tools/jtag/`)
- ✅ 执行测试，收集串口日志 (`tools/uart/`)
- ✅ 单步调试和验证功能
- ✅ 生成测试报告 (`reports/`)
- ✅ 提交测试反馈 (`review/*/feedback/`)
- ✅ 补充验收标准 (`review/*/acceptance.md`)
**可读但不可写：**
- 👁 任务描述 (`review/*/task.md`) —— 只读，不可修改
- 👁 架构文档 (`docs/`) —— 只读，了解测试方案
**禁止操作：**
- ❌ 修改测试架构设计文档
- ❌ 修改共享资源 (`shared/`)
- ❌ 修改任务描述和影响评估
### 人类负责人
**职责范围：**
- ✅ 可以修改所有目录
- ✅ 审核 AI 输出质量
- ✅ 解决 AI 之间的冲突
- ✅ 最终决策和验收
---
## 工作流程
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 需求分析 │ ───→ │ 测试架构 │ ───→ │ 执行测试 │ ───→ │ 验收确认 │
│ (Arch AI) │ │ (Arch AI) │ │ (执行AI) │ │ (人类) │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
↑ │
│ Bug → 修复 │
└──────────────────────┘
(最多 2 轮)
```
### 详细流程说明
**0. 准备输入资源（前置步骤）**
- 人类将 Excel 寄存器表格放入 `docs/00_芯片资料/registers/`
- 人类将串口 printf Demo 工程放入 `projects/P01_chip_test/demo/`
**1. 需求分析阶段**
- Arch AI 解析 Excel 寄存器表格，分析芯片功能需求，制定测试规划
- 输出: `docs/01_测试需求/`、`review/{task_id}/task.md`、寄存器定义头文件
**2. 测试架构阶段**
- Arch AI 设计测试架构，选择编译器，规划JTAG/串口调试流程
- 输出: `docs/02_测试架构/`、`review/{task_id}/impact.md`、`review/{task_id}/acceptance.md`
**3. 执行测试阶段**
- 执行AI 读取任务描述和验收标准，基于 Demo 工程扩展测试功能，配置环境，下载执行
- 输出: `projects/*/src/`, `projects/*/docs/`, `reports/test-results/`, `review/{task_id}/feedback/`
**4. 验收确认阶段**
- 人类审核测试报告，确认任务完成或驳回
- 确认后任务状态更新为 DONE，移入 `review/archived/`
### 缺陷修复循环
| 规则 | 说明 |
|------|------|
| 最大轮次 | 3 轮（初始测试 + 最多 2 轮修复复查） |
| 循环范围 | 测试失败 → 执行AI 修复 → 执行AI 复查 |
| 跳过项 | 修复轮次中执行AI **只修固件或测试流程**，不重新写 acceptance/impact |
| 触发升级 | 第 3 轮仍有 BLOCKER 或 HIGH 级别 Bug → 暂停流转，待人类裁决 |
```
Round 1: Arch AI 设计 → 执行AI 测试 → 3 个 Bug
Round 2: 执行AI 修复 → 执行AI 复查 → 1 个 Bug（MEDIUM）
Round 3: 执行AI 修复 → 执行AI 复查 → 0 个 Bug ✅ → 提交人类验收
```
如果 Round 3 仍有 BLOCKER/HIGH：
```
Round 3: 执行AI 修复 → 执行AI 复查 → 仍 1 个 HIGH → ⚠️ 升级给人类裁决
```
### 人类
- 全部权限，但主要行使：需求定义、架构决策、硬件验证、成果验收
---
## 目录权限矩阵
> **图例**：`-` = 无权访问 &nbsp;&nbsp; `R` = 只读 &nbsp;&nbsp; `W` = 可写（含读） &nbsp;&nbsp; `RW` = 读写
> 图例：`-` = 禁止 `R` = 只读 `W` = 可写（含读） `RW` = 读写
| 目录路径 | Arch AI | 执行AI | 人类 |
|---------|---------|--------|------|
| 目录路径 | Arch AI | Worker AI | 人类 |
|---------|---------|-----------|------|
| `.ai/` | `R` | `-` | `RW` |
| `docs/` | `RW` | `R` | `RW` |
| `tools/` | `RW` | `RW` | `RW` |
| `shared/` | `RW` | `R` | `RW` |
| `projects/*/src/` | `RW` | `RW` | `RW` |
| `projects/*/tests/` | `RW` | `RW` | `RW` |
| `projects/*/docs/` | `RW` | `RW` | `RW` |
| `review/*/task.md` | `RW` | `R` | `RW` |
| `review/*/acceptance.md` | `RW` | `RW` | `RW` |
| `review/*/impact.md` | `RW` | `-` | `RW` |
| `review/*/feedback/` | `R` | `RW` | `RW` |
| `reports/` | `R` | `RW` | `RW` |
| `.github/` | `-` | `-` | `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 访问（等效于 `-`）。
---
## 沟通规范
### Arch AI → 执行AI
在 `review/{task_id}/` 目录提交：
- **验收标准** (`acceptance.md`) - 明确测试目标
- **变更影响范围** (`impact.md`) - 指导回归测试
- **环境准备** 参考项目级 `ENVIRONMENT.md`
### 执行AI → Arch AI / 人类
在 `review/{task_id}/feedback/` 目录提交：
- **测试结果报告** (`round{round}.md`)
- **问题清单** - 列出问题和严重程度
- **改进建议** - 优化建议
优先级：`forbidden > read_only > allowed`。未出现在表中的路径默认禁止所有 AI。
---
## 命名规范
### 项目命名
```
P01_芯片测试项目 # P01 表示项目编号
```
### 任务编号
```
P01-001 # P01 项目编号 + 001 任务编号
```
- 开发任务：`D{阶段号}-{序号}`，如 `D0-001`（P0阶段第1个任务）
- 测试任务：`T{阶段号}-{序号}`，如 `T0-001`
### 分支命名
```
feature/P01-001-gpio-test # 功能测试
bugfix/P01-001-uart-fix # Bug修复
test/P01-001-perf-verify # 性能验证
feature/D0-001-short-desc
bugfix/D0-001-short-desc
test/T0-001-short-desc
```
### 提交信息
```
feat(P01-001): 实现GPIO功能测试
fix(P01-001): 修复串口日志输出问题
docs(P01-001): 更新测试架构文档
test(P01-001): 添加定时器测试用例
feat(D0-001): 简短描述
fix(D0-001): 简短描述
docs(D0-001): 简短描述
test(D0-001): 简短描述
errata: GPIOx_BSRR 写入偶发失效 (D0-003)
```
---
## 编译器配置
### Arm Clang
```json
{
"compiler": "armclang",
"version": ">= 18.0.0",
"target": "armv8-m",
"optimization": "O2"
}
```
### Keil MDK
```json
{
"compiler": "AC6",
"version": ">= 6.18",
"target": "Cortex-M7",
"optimization": "-O2"
}
```
### Arm GCC
```json
{
"compiler": "arm-none-eabi-gcc",
"version": ">= 12.0.0",
"target": "armv8-m",
"optimization": "-O2"
}
```
---
## JTAG调试流程
1. **准备固件**: 编译生成 .hex / .elf 文件
2. **连接硬件**: 通过JTAG/SWD连接硬件
3. **下载固件**: 使用OpenOCD或pyOCD下载
4. **运行调试**: 启动调试，设置断点
5. **串口监控**: 监听串口输出日志
6. **单步调试**: 单步执行，验证功能
---
## AI 配置文件说明
## AI 配置文件索引
| 文件 | 说明 |
|------|------|
| `.ai/config/architect.json` | Arch AI 配置（权限、职责） |
| `.ai/config/executor.json` | 执行AI 配置（权限、职责） |
| `.ai/config/workflow.json` | 工作流配置（阶段、触发器） |
| `.ai/prompts/architecture/` | 架构设计提示词模板 |
| `.ai/prompts/execution/` | 执行提示词模板 |
| `.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 模板 |
DECISIONS.md
+1 -8
View File
@@ -5,16 +5,9 @@
---
---
## 已决策
### D-001: 确认跨平台信息架构升级方案 ✅
**日期**: 2026-05-26
**决策**: A — 确认，立即落地
**执行**: 新架构已落地。dashboard.md + DECISIONS.md + .ai/tasks/ 结构生效，旧文件归档至 .ai/archive/
**ADRs**: ADR-012
（暂无已决策事项）
---
docs/02_系统架构/.gitkeep → Drivers/BSP/.gitkeep
View File
docs/03_开发规范/.gitkeep → Drivers/CMSIS/Core/.gitkeep
View File
docs/04_部署运维/.gitkeep → Drivers/CMSIS/Device/HWD/hwd32h757/Include/.gitkeep
View File
docs/05_变更日志/.gitkeep → Drivers/CMSIS/Device/HWD/hwd32h757/Source/.gitkeep
View File
docs/05_变更日志/archived/.gitkeep → Drivers/HWD32H757_HAL_Driver/Inc/.gitkeep
View File
tools/.gitkeep → Drivers/HWD32H757_HAL_Driver/Src/.gitkeep
View File
ENVIRONMENT.md
+34 -60
View File
@@ -1,74 +1,48 @@
# ErrLens 开发环境配置
# hwd32h757 开发环境配置
## 芯片信息
| 项目 | 值 |
|------|-----|
| 芯片代号 | hwd32h757 |
| 内核 | Cortex-M7 |
| 参考架构 | STM32H7系列 |
| SDK框架 | HAL/LL双层（参考STM32CubeH7） |
## 前置依赖
| 工具 | 版本要求 | 说明 |
|------|---------|------|
| Node.js | >= 20.x | JavaScript 运行时 |
| pnpm | >= 9.0.0 | 包管理器 |
| Python | >= 3.10 | AI 训练算法 |
| GCC ARM | >= 13.x | 交叉编译器 |
| CMake | >= 3.20 | 构建系统 |
| Python | >= 3.10 | 工具脚本（SVD解析、测试报告） |
| OpenOCD / J-Link | — | 烧录调试 |
| Git | >= 2.40 | 版本控制 |
## 开发工具
- **IDE**: VS Code + Cortex-Debug + CMake Tools
- **AI协作**: 1人 + Arch AI + Worker AI
- **上下文同步**: AGENTS.md + dashboard.md（任何AI读到即可接手）
## 硬件环境
- **评估板**: HWD32H757-EVAL
- **调试器**: J-Link / ST-Link（SWD接口）
- **串口**: USB-UART（调试输出）
## 快速开始
```bash
# 1. 克隆项目
git clone <repository-url>
cd errlens
git clone https://gitcode.com/tupingr/ai_soc_sw.git
cd ai_soc_sw
# 2. 安装前端依赖
pnpm install
# 2. 构建
mkdir build && cd build
cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-gcc-toolchain.cmake
make
# 3. 恢复上下文（换电脑后）
# 在 Trae 中使用 resume-context Skill
# 4. 启动开发服务器（根据子项目）
cd projects/P01_errlens_app
pnpm dev
# 3. 烧录
openocd -f interface/jlink.cfg -f target/hwd32h757.cfg -c "program build/Test/cases/gpio/gpio_test.elf verify reset exit"
```
## 子项目环境
### P01_errlens_app（小程序）
```bash
cd projects/P01_errlens_app
pnpm install
pnpm dev
```
### P02_errlens_training（训练算法）
```bash
cd projects/P02_errlens_training
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
```
### P03_errlens_web（Web 管理后台）
```bash
cd projects/P03_errlens_web
pnpm install
pnpm dev
```
## 开发工具
- **IDE**: Trae CN
- **AI 协作**: 1 人 + 2AI（Dev AI + QA AI）
- **上下文同步**: 使用 `resume-context` Skill
## 跨平台开发
本项目支持在 Windows、macOS、Linux 上开发。换电脑时：
1. `git pull` 拉取最新代码
2. 在 Trae 中使用 `resume-context` Skill 恢复上下文
3. 继续开发
## 环境变量
各子项目的环境变量文件：
- `projects/P01_errlens_app/.env`
- `projects/P03_errlens_web/.env`
参考各子项目的 `ENVIRONMENT.md` 获取详细配置。
Projects/HWD32H757-EVAL/Applications/.gitkeep
View File
Projects/HWD32H757-EVAL/Examples/.gitkeep
View File
README.md
+39 -214
View File
@@ -1,228 +1,53 @@
# ErrLens MCU芯片自动化测试项目
# ai_soc_sw
## 项目目标
hwd32h757 MCU 芯片成片测试及 SDK 开发项目。
基于芯片手册和 Excel 寄存器表格，通过运行软件的方式配合 JTAG 调试工具和串口工具，自动验证芯片实际功能是否与文档描述一致。
## 项目信息
---
| 项目 | 值 |
|------|-----|
| 芯片代号 | hwd32h757 |
| 内核 | Cortex-M7 |
| 项目阶段 | Chip bring-up（回片测试） |
| 仓库 | https://gitcode.com/tupingr/ai_soc_sw.git |
## 核心特性
## 核心产出
- ✅ Excel 寄存器表格解析 → 自动生成寄存器定义头文件
- ✅ 自动生成测试代码 → 寄存器读写测试、功能验证
- ✅ JTAG 自动化下载 + 运行
- ✅ 串口日志监控 + 自动分析
- ✅ 测试结果自动验证 + 报告生成
- ✅ "人+Arch AI+执行AI" 协作模式
1. **寄存器功能测试** — 33 个功能单元的全面扫描
2. **SDK 框架** — HAL/LL 双层驱动（参考 STM32CubeH7）
3. **勘误记录** — 结构化硅缺陷追踪
---
## 协作模式
1 人 + Arch AI + Worker AI，详见 [AGENTS.md](AGENTS.md)。
## 目录结构
```
.
├── 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/
ai_soc_sw/
├── AGENTS.md # AI 角色定义与权限约定
├── dashboard.md # 项目控制面板
├── DECISIONS.md # 待决策事项
├── ENVIRONMENT.md # 开发环境配置
├── .ai/ # AI 协作核心
│ ├── principles.md # 设计原则
│ ├── roles/ # AI 角色身份卡
│ ├── tasks/ # 任务文件
│ ├── phases/ # 阶段上下文
│ └── knowledge/ # 知识沉淀（ADR/教训/模式）
├── Drivers/ # SDK 驱动层
│ ├── CMSIS/ # ARM CMSIS + 设备文件
│ ├── HWD32H757_HAL_Driver/ # HAL + LL 驱动
│ └── BSP/ # 板级支持包
├── Test/ # 寄存器测试
│ ├── framework/ # 测试框架
│ ├── cases/ # 33 个功能单元
│ └── errata/ # 勘误记录
├── Tools/ # 自动化工具
├── docs/ # 项目文档
└── Projects/ # 示例工程
```
---
## 团队角色
| 角色 | 是谁 | 干什么 | 不干什么 |
|------|------|--------|----------|
| **人类负责人** | 你 | 下指令、审阅、做决策、定验收标准 | 不写代码、不执行测试 |
| **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 | 初始版本，完成目录结构设计 |
见 [ENVIRONMENT.md](ENVIRONMENT.md)。
SYNC.md
-83
View File
@@ -1,83 +0,0 @@
# 模板同步边界定义
> 定义哪些文件属于"框架层"（跨项目复用），哪些属于"项目层"（项目特有）。
> 框架层变化通过 `sync-template.sh` 从 main 同步到 ai_project 模板分支。
---
## 规则
```
框架层 = 可以复用的结构和逻辑（同步）
项目层 = 某个具体项目的内容和数据（不同步）
```
---
## 文件分类
### 框架层（自动同步）
| 文件/目录 | 说明 |
|-----------|------|
| `AGENTS.md` | AI 角色定义 + 权限矩阵 + 工作流 + 命名规范 |
| `dashboard.md` | 控制面板结构（人类+Arch AI 入口） |
| `DECISIONS.md` | 决策入口结构 |
| `.ai/principles.md` | 架构设计原则 + Arch AI 上下文管理 |
| `.ai/config/*.json` | AI 配置（权限路径、职责定义、工作流） |
| `.ai/prompts/` | 提示词模板（架构、编码、测试） |
| `.ai/roles/README.md` | 角色工作台说明 |
| `.ai/roles/{arch,dev,qa}/card.md` | 角色身份卡（身份、权限、启动流程） |
| `.ai/phases/INDEX.md` | 阶段索引 + 切换规则 |
| `.ai/knowledge/patterns.md` | 可复用模式 |
| `.ai/knowledge/lessons.md` | 框架级经验教训 |
| `.ai/tasks/templates/` | Task 模板（Coder + Tester） |
| `.trae/skills/` | Skill 定义 |
| `docs/使用手册.md` | 使用手册（框架层） |
| `ENVIRONMENT.md` | 开发环境结构（框架层） |
| `sync-template.sh` | 同步脚本本身 |
| `TEMPLATE.yaml` | 模板变量配置 |
| `init.sh` | 新项目初始化脚本 |
| `SYNC.md` | 本文档 |
### 项目层（不同步）
| 文件/目录 | 说明 |
|-----------|------|
| `.ai/tasks/active/` | 活跃 task 文件（项目特定） |
| `.ai/tasks/completed/` | 已完成 task（项目特定） |
| `.ai/phases/phase-*/goal.md` | 阶段目标（项目特定） |
| `.ai/phases/phase-*/scope.md` | 阶段范围（项目特定） |
| `.ai/phases/phase-*/architecture.md` | 架构快照（项目特定） |
| `.ai/phases/phase-*/decisions.md` | 阶段决策（项目特定） |
| `.ai/phases/phase-*/completion.md` | 完成状态（项目特定） |
| `.ai/knowledge/decisions.md` | ADR 全文（项目特定） |
| `.ai/knowledge/journal/` | 每日日志（项目特定） |
| `.ai/archive/` | 归档文件 |
| `docs/01_*/ ~ docs/06_*/` | 项目文档（PRD、架构、数据模型等） |
| `docs/share/` | 对外分享内容 |
| `projects/` | 项目代码 |
| `reports/` | 测试报告 |
| `review/` | 旧 review 流程（已废弃，由 .ai/tasks/ 替代） |
---
## 使用流程
```bash
# 1. 切换到模板分支
git checkout ai_project
# 2. 运行同步脚本
bash sync-template.sh main ai_project
# 3. 检查变更 + 提交
git diff --stat
git add -A && git commit -m "sync: 框架更新 from main"
```
## 原则
1. **脚本覆盖框架层** — 直接 checkout 无需人工判断
2. **项目层隔离** — 任务、日志、代码、决策不受影响
3. **新架构适配** — dashboard.md / DECISIONS.md / .ai/tasks/ 已纳入框架层定义

Some files were not shown because too many files have changed in this diff Show More