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

Compare commits

base: hwd32/ai_soc_sw:5cba5c248a2e35ff4c28813d24a254c76da77b9c
Branches Tags
hwd32/ai_soc_sw:main hwd32/ai_soc_sw:ic_eda
..
compare: hwd32/ai_soc_sw:8157f107684f07769cb9e39386357f5c83bd3ac5
Branches Tags
hwd32/ai_soc_sw:ic_eda hwd32/ai_soc_sw:main

10 Commits
5cba5c248a .. 8157f10768

Author SHA1 Message Date
tupingr 8157f10768 feat: 完善 MCU 芯片自动化测试架构 
- 重构为三角色协作：人+Arch AI+执行AI
- 新增 Excel 寄存器表格解析工具，自动生成测试代码
- 新增串口日志分析工具，自动生成测试报告
- 完善项目文档：AGENTS.md、README.md
- 创建自动化测试架构设计文档
- 添加示例测试任务 P01-001
 2026-05-27 10:44:55 +08:00
tupingr f041139ca8 refactor(principles): 上下文资源管理规则扩展至所有 AI 角色 
- 从「Arch AI 专用」升级为「所有角色通用硬约束」
- 新增角色特定约束：Arch/Coder/Tester 各自的上下文风险+应对
- 更新过时引用：Token预算表、信息分层、阶段切换清单
- 补充信号识别：Coder AI 需同时改3个文件时触发收尾

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-05-26 15:40:36 +08:00
tupingr 473f61b4cc feat(template): ADR-013 Skill 替代脚本 — 框架脱敏/初始化机制重构 
- 废弃 ADR-008 双分支+shell脚本方案（ai_project分支已过时）
- 新增 project-init Skill：export（脱敏导出） + init（初始化新项目）双模式
- 保留 SYNC.md（框架/项目边界）+ TEMPLATE.yaml（变量定义）
- L-006: 当 AI 是执行者时，Skill 优于 Shell 脚本
- 3 文件替代 4文件+1分支，零维护成本

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-05-26 15:33:05 +08:00
tupingr 6992f59cd2 refactor(arch): 信息架构升级 — 三层四角色控制面板 + 跨平台 task 交接协议 
核心变化：
- dashboard.md 替代 DASHBOARD + ROADMAP，人类+Arch AI 唯一入口
- DECISIONS.md 人类决策入口，≤3 条待决策
- .ai/tasks/ 14 个独立 task 文件（Coder 8 + Tester 6），弱模型自包含可独立执行
- 旧 today/queue 归档，每个角色启动 ≤2 个文件
- ADR-012 跨平台「高模型指挥小模型」协作架构落地
- 知识库补全：L-002~005、P-004~005、ADR-011~012
- Arch AI 上下文资源管理硬约束写入 principles.md

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-05-26 15:17:06 +08:00
tupingr 5b428d0810 chore(phase): Phase 1 收尾 — 一鸡多吃 + Dev工作台初始化 + Phase 2启动 
- Phase 1 标记 100% 完成，Phase 2 标记 ACTIVE
- Dev AI 工作台重写：8个任务入队 + 依赖关系图
- 一鸡多吃：6篇对外分享文章（项目缘起/框架思路/阶段复盘/3篇决策故事）
- 新增 share-context Skill（内部文档→对外分享自动化）
- P01 文档同步更新（需求/架构/接口定义）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-05-26 12:01:04 +08:00
tupingr e3f4af9c0c docs(arch): 旧架构合并 — 30项决策落地，5份文档升级至v0.4.0 
- 总体架构：新增打印/图像预处理/双飞轮/三环境部署
- 技术选型：调整决策理由（Coze沙盒自动化测试），新增Sharp+PDFKit
- 数据模型：新增code/role/question_type+print_tasks+audit_logs，ID+code并存
- 模块设计：新增Image/Print模块，推荐两阶段匹配（关键词粗筛→AI精排）
- PRD：目标用户扩展为学生+家长，新增PDF打印，年级聚焦小初，图像预处理流程
- ADR-010：题库抽象层Adapter Pattern

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-05-26 12:00:52 +08:00
tupingr 6c9acbc501 chore(arch): 记录今日工作 + 更新明日任务 + 同步知识库 
- journal: 2026-05-25 完整工作记录
- arch/today.md: 标记完成，列出明日待办
- ROADMAP.md: 进度更新至40%，信息架构重构标为完成
- 从 ai_project 同步 ADR-008 + P-003 到 main

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-05-25 17:23:06 +08:00
tupingr 4184a6d0b5 refactor(architecture): 信息架构重构 — 从"人类导向单体文档"到"AI优先分层架构" 
新增四层信息架构：
- Layer 0: 角色工作台 (.ai/roles/) — AI 每天只需读2个小文件
- Layer 1: 路线图看板 (ROADMAP.md) — 人机共享进度
- Layer 2: 阶段上下文 (.ai/phases/) — 按当前阶段加载
- Layer 3: 知识沉淀 (.ai/knowledge/) — 决策/模式/教训自动积累

新增：
- DASHBOARD.md — 人类仪表盘（30秒了解全貌）
- ROADMAP.md — 任务看板+阻塞追踪
- docs/share/ — 对外分享内容层（一鸡多吃）
- docs/使用手册.md — 人+AI使用手册
- .ai/prompts/architecture/ — 补充缺失的架构提示词
- .ai/principles.md — 信息架构设计原则
- review/active/INDEX.md — 任务索引

修改：
- AGENTS.md: 239行→117行，顶部AI跳转
- README.md: 精简聚焦人类读者
- PROJECT_CONTEXT.md: 精简+分层说明
- DECISIONS.md: 替换为跳转存根
- 5个task.md: 添加phase字段

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-05-25 16:49:36 +08:00
tupingr 5dfc382c55 docs(update-docs): 同步文档 - 修复 tester.json 权限冲突 + 更新变更日志 
- .ai/config/tester.json: 修复 review/*/acceptance.md 和 review/*/feedback/ 路径冲突
- README.md: 新增可用 Skill 列表（7 个）
- docs/PROJECT_CONTEXT.md: 更新为 1 人+3AI，补充关键决策记录
- docs/05_变更日志/2026-05-23.md: 补充今日所有提交记录
 2026-05-23 23:06:20 +08:00
tupingr b3fbe33dd0 fix(switch-model): 调整执行顺序，git 安全检查优先 
- 将 git status/log/branch 移到上下文加载之前
- 增加异常处理：未提交变更/合并冲突/分支错误/远程更新
- 版本升至 v1.1
 2026-05-23 23:02:08 +08:00
120 changed files with 7647 additions and 1070 deletions
Expand all files Collapse all files
.ai/archive/DASHBOARD.md
+59
View File
@@ -0,0 +1,59 @@
# 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
@@ -0,0 +1,83 @@
# 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
@@ -0,0 +1,21 @@
# 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
@@ -0,0 +1,45 @@
# 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
@@ -0,0 +1,36 @@
# 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
@@ -0,0 +1,29 @@
# 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
@@ -0,0 +1,19 @@
# 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
@@ -0,0 +1,18 @@
# QA AI · 今日任务 · 2026-05-25
## 进行中
（无）
## 待执行
当前没有进入 REVIEW 状态的任务，暂无测试任务。
## 已完成
（无）
## 说明
等待 Dev AI 完成代码开发后，任务状态转为 REVIEW 时开始测试工作。
关注 `ROADMAP.md` 中的 DOING 列，当有任务进入 REVIEW 时立即介入。
.ai/config/architect.json
+12 -11
View File
@@ -1,32 +1,33 @@
{
"name": "Arch AI",
"role": "架构设计师",
"role": "测试架构设计师",
"description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。",
"responsibilities": [
"需求分析和产品规划",
"系统架构设计",
"技术选型和评估",
"跨模块协调和集成",
"编写架构文档",
"芯片功能需求分析和测试规划",
"测试架构设计和测试方案制定",
"编译器选择和环境配置方案",
"JTAG调试流程设计",
"串口日志分析方案",
"编写测试架构文档",
"定义验收标准",
"评估变更影响",
"评估测试结果影响",
"维护共享资源",
"指导 Dev AI 和 QA AI 工作"
"维护测试工具",
"指导执行AI工作"
],
"allowed_paths": [
"docs/",
"shared/",
"projects/*/src/",
"projects/*/docs/",
"projects/*/tests/",
"review/*/acceptance.md",
"review/*/impact.md",
"review/*/task.md",
"tools/",
"data/"
"tools/"
],
"read_only_paths": [
".ai/",
"projects/*/tests/",
"reports/",
"review/*/feedback/"
],
.ai/config/executor.json
+38
View File
@@ -0,0 +1,38 @@
{
"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
+2 -4
View File
@@ -20,14 +20,12 @@
"docs/",
"data/",
"shared/",
"review/*/task.md",
"review/*/acceptance.md"
"review/*/task.md"
],
"forbidden_paths": [
".ai/",
"tools/",
"review/*/impact.md",
"review/*/feedback/"
"review/*/impact.md"
],
"prompt_templates": {
"testing": ".ai/prompts/testing/"
.ai/config/workflow.json
+13 -20
View File
@@ -1,29 +1,23 @@
{
"workflow": "human-ai-collaboration",
"roles": ["human", "arch-ai", "dev-ai", "qa-ai"],
"workflow": "mcu-chip-testing",
"roles": ["human", "arch-ai", "executor-ai"],
"stages": [
{
"name": "需求分析",
"actor": "arch-ai",
"output": ["docs/01_产品需求/PRD.md", "review/{task_id}/task.md"]
"output": ["docs/01_测试需求/", "review/{task_id}/task.md"]
},
{
"name": "架构设计",
"name": "测试架构",
"actor": "arch-ai",
"input": ["docs/01_产品需求/PRD.md", "review/{task_id}/task.md"],
"output": ["docs/02_系统架构/", "review/{task_id}/impact.md", "review/{task_id}/acceptance.md"]
"input": ["docs/01_测试需求/", "review/{task_id}/task.md"],
"output": ["docs/02_测试架构/", "review/{task_id}/impact.md", "review/{task_id}/acceptance.md"]
},
{
"name": "开发实现",
"actor": "dev-ai",
"name": "执行测试",
"actor": "executor-ai",
"input": ["review/{task_id}/task.md", "review/{task_id}/acceptance.md"],
"output": ["projects/*/src/", "projects/*/docs/"]
},
{
"name": "测试验证",
"actor": "qa-ai",
"input": ["review/{task_id}/task.md", "review/{task_id}/acceptance.md"],
"output": ["projects/*/tests/", "reports/test-results/", "review/{task_id}/feedback/round{round}.md"]
"output": ["projects/*/src/", "projects/*/docs/", "reports/test-results/", "review/{task_id}/feedback/round{round}.md"]
},
{
"name": "验收确认",
@@ -33,16 +27,15 @@
],
"retry": {
"max_rounds": 3,
"loop": ["测试验证", "开发实现"],
"loop": ["执行测试"],
"escalation": {
"trigger": "第 3 轮测试仍有 BLOCKER 或 HIGH 级别 Bug",
"trigger": "第 3 轮测试仍有 BLOCKER 或 HIGH 级别问题",
"action": "暂停任务流转，等待人类负责人裁决"
},
"skip_acceptance_on_retry": true
},
"ci_triggers": {
"on_push_to_main": ["run-tests", "generate-reports"],
"on_pr_open": ["run-tests", "code-review"],
"on_task_update": ["notify-qa-ai"]
"on_push_to_main": ["compile-firmware"],
"on_task_update": ["notify-executor-ai"]
}
}
.ai/knowledge/decisions.md
+191
View File
@@ -0,0 +1,191 @@
# 架构决策记录 (ADR)
## ADR-001: "1 人 + 2 AI" 协作框架
- 日期: 2026-05-23
- 状态: 已采纳（后升级为 1 人 + 3 AI）
- 决策: 采用人类负责人 + Dev AI + QA AI 的三角协作模式
- 理由: 单人开发需要 AI 辅助，但 AI 不能互审，需要人类做最终决策
- 影响: 定义了 R/W/RW/- 四级权限体系
## ADR-002: 四级权限体系
- 日期: 2026-05-23
- 状态: 已采纳
- 决策: 采用 `-`(禁止) / `R`(只读) / `W`(可写) / `RW`(读写) 四级权限，比二进制的读写更精细
- 理由: AI 角色需要明确的边界，"只读但不能写"和"完全不可见"需要区分
- 影响: 所有目录访问按权限矩阵执行，`forbidden > read_only > allowed` 优先级
## ADR-003: 根级 docs/ 目录
- 日期: 2026-05-23
- 状态: 已采纳
- 决策: 项目级文档放在根目录 `docs/` 而非子项目内
- 理由: 跨项目共享的文档（架构设计、开发规范）不应属于某个子项目
- 影响: docs/ 由 Arch AI 和 Dev AI 共同维护
## ADR-004: 独立 tools/ 和 data/ 目录
- 日期: 2026-05-23
- 状态: 已采纳
- 决策: 开发工具脚本和训练数据从 shared/ 中独立出来
- 理由: tools 和 data 的使用场景和权限需求与 shared 不同
- 影响: Arch AI 和 Dev AI 可写 tools/ 和 data/，QA AI 只能读 data/
## ADR-005: 工作流重试和升级机制
- 日期: 2026-05-23
- 状态: 已采纳
- 决策: 测试 → 修复循环最多 3 轮，Round 3 仍有 BLOCKER/HIGH 则升级给人类
- 理由: 防止无限循环，确保严重问题得到人类关注
- 影响: `skip_acceptance_on_retry: true`，修复轮次不重写验收标准
## ADR-006: resume-context Skill 多机同步
- 日期: 2026-05-23
- 状态: 已采纳
- 决策: 通过 `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」协作框架的实质性落地——从抽象角色到具体平台+模型绑定
.ai/knowledge/journal/.gitkeep
View File
.ai/knowledge/journal/2026-05-25.md
+70
View File
@@ -0,0 +1,70 @@
# 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
@@ -0,0 +1,63 @@
# 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
+111
View File
@@ -0,0 +1,111 @@
# 经验教训
## 目的
记录开发过程中学到的东西。每条记录包含：
- 上下文（我们在做什么）
- 问题（出了什么问题/什么让我们意外）
- 教训（学到了什么）
- 行动（因此改变了什么）
---
## 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 的每个任务需独立可读，不依赖前后文
.ai/knowledge/patterns.md
+142
View File
@@ -0,0 +1,142 @@
# 可复用模式
## 目的
记录开发过程中发现的可持续复用的模式和做法。
同样的模式出现 3 次以上时，应当记录在这里。
---
## P-001: AI 任务交接 (review/active/)
**上下文**: 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 提交）
**何时用**: 每个跨 AI 角色的任务
**何时不用**: 单角色任务（如纯文档更新、配置修改）
---
## P-002: 角色工作台 (daily task board)
**上下文**: 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
+17
View File
@@ -0,0 +1,17 @@
# 阶段索引
| 阶段 | 名称 | 状态 | 目录 |
|------|------|------|------|
| 1 | 基础搭建 | DONE | `phase-01-foundation/` |
| 2 | MVP | ACTIVE | `phase-02-mvp/` |
| 3 | 功能完善 | PLANNED | `phase-03-features/` |
| 4 | 打磨发布 | PLANNED | `phase-04-polish/` |
## 阶段切换规则
1. 当前阶段 completion.md 全部打勾
2. 人类签字确认
3. Arch AI 更新本索引文件
4. Arch AI 更新所有角色 card.md（当前阶段字段）
5. Arch AI 更新 dashboard.md（进度条 + task 状态面板 + 最近事件）
6. 产出阶段复盘（docs/share/phase-NN/）
.ai/phases/phase-01-foundation/architecture.md
+45
View File
@@ -0,0 +1,45 @@
# 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
@@ -0,0 +1,16 @@
# 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
@@ -0,0 +1,27 @@
# 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
@@ -0,0 +1,27 @@
# 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
@@ -0,0 +1,42 @@
# 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
@@ -0,0 +1,3 @@
# Phase 2: MVP — 架构决策
*（Phase 2 执行过程中由 Arch AI 填写）*
.ai/phases/phase-02-mvp/completion.md
+3
View File
@@ -0,0 +1,3 @@
# Phase 2: MVP — 完成检查清单
*（Phase 2 接近完成时更新）*
.ai/phases/phase-02-mvp/decisions.md
+3
View File
@@ -0,0 +1,3 @@
# Phase 2: MVP — 阶段决策
*（Phase 2 执行过程中由 Arch AI 填写）*
.ai/phases/phase-02-mvp/goal.md
+11
View File
@@ -0,0 +1,11 @@
# Phase 2: MVP — 目标
*（Phase 1 完成时由 Arch AI 填写）*
## 阶段目标
## 成功标准
## 阶段 Owner
## 下一阶段
.ai/phases/phase-02-mvp/scope.md
+3
View File
@@ -0,0 +1,3 @@
# Phase 2: MVP — 范围
*（Phase 1 完成时由 Arch AI 填写）*
.ai/phases/phase-03-features/architecture.md
+3
View File
@@ -0,0 +1,3 @@
# Phase 3: 功能完善 — 架构决策
*（Phase 3 执行过程中由 Arch AI 填写）*
.ai/phases/phase-03-features/completion.md
+3
View File
@@ -0,0 +1,3 @@
# Phase 3: 功能完善 — 完成检查清单
*（Phase 3 接近完成时更新）*
.ai/phases/phase-03-features/decisions.md
+3
View File
@@ -0,0 +1,3 @@
# Phase 3: 功能完善 — 阶段决策
*（Phase 3 执行过程中由 Arch AI 填写）*
.ai/phases/phase-03-features/goal.md
+3
View File
@@ -0,0 +1,3 @@
# Phase 3: 功能完善 — 目标
*（Phase 2 完成时由 Arch AI 填写）*
.ai/phases/phase-03-features/scope.md
+3
View File
@@ -0,0 +1,3 @@
# Phase 3: 功能完善 — 范围
*（Phase 2 完成时由 Arch AI 填写）*
.ai/phases/phase-04-polish/architecture.md
+3
View File
@@ -0,0 +1,3 @@
# Phase 4: 打磨发布 — 架构决策
*（Phase 4 执行过程中由 Arch AI 填写）*
.ai/phases/phase-04-polish/completion.md
+3
View File
@@ -0,0 +1,3 @@
# Phase 4: 打磨发布 — 完成检查清单
*（Phase 4 接近完成时更新）*
.ai/phases/phase-04-polish/decisions.md
+3
View File
@@ -0,0 +1,3 @@
# Phase 4: 打磨发布 — 阶段决策
*（Phase 4 执行过程中由 Arch AI 填写）*
.ai/phases/phase-04-polish/goal.md
+3
View File
@@ -0,0 +1,3 @@
# Phase 4: 打磨发布 — 目标
*（Phase 3 完成时由 Arch AI 填写）*
.ai/phases/phase-04-polish/scope.md
+3
View File
@@ -0,0 +1,3 @@
# Phase 4: 打磨发布 — 范围
*（Phase 3 完成时由 Arch AI 填写）*
.ai/principles.md
+91
View File
@@ -0,0 +1,91 @@
# 信息架构设计原则
## 为什么这样设计
AI 的上下文窗口有限。每个读入上下文的字都是成本。这套分层架构的核心思想：**每个角色只加载必要信息，按需展开细节。**
## Token 预算
| 层级 | 预算 | 内容 | 加载时机 |
|------|------|------|----------|
| 入口（dashboard/card） | < 2K | 身份+全貌+任务 | 每次会话必读 |
| Task 文件 | < 1K | 单任务全部信息 | Coder/Tester 开工时 |
| 知识沉淀 (knowledge) | < 3K | 决策/模式/教训 | 按需加载 |
| 阶段上下文 (phase) | < 5K | 目标+范围+架构 | 按需加载 |
## 信息分层（三层架构）
```
指挥层: dashboard.md → 人类 + Arch AI 唯一入口
决策层: DECISIONS.md → 待人类决策事项
执行层: .ai/tasks/active/ → Coder/Tester 各自 task 文件
```
## 维护规则
1. **不超预算**：每个文件严格遵守 token 预算，超了就拆分
2. **不重复状态**：状态只在一处记录（dashboard.md），其他地方引用
3. **Git 管历史**：文档只描述"现在是什么"，历史由 Git 负责
4. **一文一答**：每个文件独立回答一个问题，不需要串联阅读
5. **角色无关设计**：任何 AI 模型都能通过读 card.md 快速接管角色
---
## AI 上下文资源管理（硬约束，适用于所有 AI 角色）
**问题**：每个 AI 每次会话有上下文窗口限制。如果盲目冲刺大任务，到一半触发自动压缩，前面的讨论、决策细节、已排除的选项全部丢失——代价不是「重来」，是「用不完整的记忆做决策」。
### 通用规则（所有角色遵守）
1. **任务前评估**：开始一个复杂任务前，先判断能否在自己的有效上下文内完成。不能 → 拆分到多个独立会话
2. **做完一件再开始下一件**：不积累未完成的工作。阶段收尾了（commit + push），再启动下一个
3. **决策即记录**：每个重要判断产生后，立即写入对应文件，不要留在对话里。对话是易失的，文件是持久的
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 |
### 信号识别（何时应立即执行规则 4）
- 需要反复回看前面的讨论才能做判断
- 开始忘记用户几分钟前说过的话
- 回复质量出现可感知的下降
- 同一个问题被重复提出
- （Coder AI）需要同时修改 3 个以上文件才能完成 task
### 反模式
- 「一口气做完再 commit」——做一半触发压缩，前面做的全丢
- 「这个 task 简单，我顺便把下一个也做了」——超边界 = 超上下文
- 「先放着，等会儿一起处理」——对话不等人，放着 = 丢了
---
## 文件约定
- 控制面板: `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/）
- [ ] 审计 token 预算
.ai/prompts/architecture/README.md
+6
View File
@@ -0,0 +1,6 @@
# Arch AI 提示词库
| 文件 | 说明 |
|------|------|
| [architecture-design.md](architecture-design.md) | 测试架构设计模板与规范 |
| [compiler-config.md](compiler-config.md) | 编译器配置模板 |
.ai/prompts/architecture/architecture-design.md
+81
View File
@@ -0,0 +1,81 @@
# 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
@@ -0,0 +1,41 @@
# 技术选型评估模板
## 输入
- 需要解决的技术问题
- 约束条件（预算、时间、团队、已有技术栈）
## 输出结构
### 1. 需求描述
- 要解决什么问题
- 关键约束是什么
### 2. 候选方案（2-4 个）
每个方案描述：
- 方案名称和简介
- 优势（3-5 条）
- 劣势（3-5 条）
- 与本项目技术栈的兼容度
### 3. 评估维度
| 维度 | 权重 | 方案A | 方案B | 方案C |
|------|------|-------|-------|-------|
| 性能 | 30% | — | — | — |
| 生态成熟度 | 25% | — | — | — |
| 学习曲线 | 20% | — | — | — |
| 社区活跃度 | 15% | — | — | — |
| 团队熟悉度 | 10% | — | — | — |
| **加权总分** | 100% | — | — | — |
### 4. 推荐方案
- 推荐哪个、为什么
- 主要风险
- 如果失败，备选方案是什么
## 注意事项
- 评估维度可调整，但必须说明理由
- 不追求"最优"，追求"最适合当前阶段"
.ai/prompts/execution/README.md
+6
View File
@@ -0,0 +1,6 @@
# 执行AI 提示词库
| 文件 | 说明 |
|------|------|
| [firmware-template.md](firmware-template.md) | 测试固件模板与规范 |
| [bug-report.md](bug-report.md) | 测试反馈与问题报告模板 |
.ai/prompts/execution/bug-report.md
+57
View File
@@ -0,0 +1,57 @@
# 执行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
@@ -0,0 +1,49 @@
# 执行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/roles/README.md
+57
View File
@@ -0,0 +1,57 @@
# 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
+43
View File
@@ -0,0 +1,43 @@
# Arch AI — 架构师
## 身份
我是架构 AI。负责需求分析、架构设计、技术选型、任务分解。
**平台**: Claude Code + DeepSeek V4 Pro（最强推理 + Agent 框架）
## 启动流程
1. 读 `dashboard.md` 全文（< 2K tokens）→ 项目全貌 + ADR 索引 + task 状态面板
2. 需要细节 → 按 dashboard 中的链接按需加载
3. 人类决策 → 读 `DECISIONS.md`
4. 完成任务 → 更新 dashboard.md + 对应 ADR/knowledge 文件
## 当前阶段
Phase 2: MVP 开发 — `dashboard.md`
## 核心交付物
- 产品需求 + 系统架构设计
- 技术选型 + 架构决策 (ADR)
- 任务分解 → `.ai/tasks/active/P01-XXX.md`
- 跨模块协调（Coder ↔ Tester 交接协议）
- 人类决策梳理 → `DECISIONS.md`
## 关键入口
| 文件 | 说明 |
|------|------|
| `dashboard.md` | 唯一控制面板（替代旧 DASHBOARD.md / ROADMAP.md） |
| `DECISIONS.md` | 待人类决策事项 |
| `.ai/knowledge/decisions.md` | ADR 全文 |
| `.ai/knowledge/lessons.md` | 经验教训 |
| `.ai/knowledge/patterns.md` | 可复用模式 |
| `.ai/tasks/active/` | 所有活跃 task 文件 |
## 权限
**可写**: docs/ shared/ projects/*/src/ projects/*/docs/ .ai/tasks/ .ai/knowledge/ dashboard.md DECISIONS.md
**只读**: projects/*/tests/ reports/
**禁止**: 无
.ai/roles/dev/card.md
+40
View File
@@ -0,0 +1,40 @@
# 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
@@ -0,0 +1,42 @@
# 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/tasks/active/CROSS-001.md
+52
View File
@@ -0,0 +1,52 @@
# 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
@@ -0,0 +1,69 @@
# 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
@@ -0,0 +1,64 @@
# 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
@@ -0,0 +1,69 @@
# 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
@@ -0,0 +1,68 @@
# 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
@@ -0,0 +1,64 @@
# 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
@@ -0,0 +1,78 @@
# 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
@@ -0,0 +1,67 @@
# 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
@@ -0,0 +1,63 @@
# 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
@@ -0,0 +1,61 @@
# 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
@@ -0,0 +1,64 @@
# 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
@@ -0,0 +1,64 @@
# 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
@@ -0,0 +1,68 @@
# 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
@@ -0,0 +1,66 @@
# 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
.ai/tasks/templates/TASK_TEMPLATE_CODER.md
+47
View File
@@ -0,0 +1,47 @@
# 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
@@ -0,0 +1,75 @@
# 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
.trae/skills/project-init/SKILL.md
+107
View File
@@ -0,0 +1,107 @@
---
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/share-context/SKILL.md
+136
View File
@@ -0,0 +1,136 @@
---
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
+44 -23
View File
@@ -28,49 +28,66 @@ description: "Checks project context when switching AI models. Invoke when user
| 开发/dev/coder | Dev AI | .ai/config/coder.json |
| 测试/test/qa | QA AI | .ai/config/tester.json |
### 2. 加载基础上下文（所有角色通用）
### 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. git log --oneline -3 # 最近 3 次提交
5. git status # 工作区状态
```
### 3. 按角色加载专属上下文
### 4. 按角色加载专属上下文
#### Arch AI（架构AI）
```
6. .ai/config/architect.json # 角色权限
7. docs/02_系统架构/ # 架构文档
8. review/active/*/task.md # 活跃任务
9. .trae/skills/ # 可用 Skill 列表
10. ENVIRONMENT.md # 环境配置
4. .ai/config/architect.json # 角色权限
5. docs/02_系统架构/ # 架构文档
6. review/active/*/task.md # 活跃任务
7. .trae/skills/ # 可用 Skill 列表
8. ENVIRONMENT.md # 环境配置
```
#### Dev AI（编码AI）
```
6. .ai/config/coder.json # 角色权限
7. review/active/*/task.md # 活跃任务
8. review/active/*/feedback/ # 待修 Bug
9. .trae/skills/ # 可用 Skill 列表
10. ENVIRONMENT.md # 环境配置
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）
```
6. .ai/config/tester.json # 角色权限
7. review/active/*/acceptance.md # 验收标准
8. reports/test-results/ # 最近测试报告
9. .trae/skills/ # 可用 Skill 列表
10. ENVIRONMENT.md # 环境配置
4. .ai/config/tester.json # 角色权限
5. review/active/*/acceptance.md # 验收标准
6. reports/test-results/ # 最近测试报告
7. .trae/skills/ # 可用 Skill 列表
8. ENVIRONMENT.md # 环境配置
```
### 4. 输出简洁检查报告
### 5. 输出简洁检查报告
```markdown
# 模型切换检查报告
@@ -99,7 +116,7 @@ description: "Checks project context when switching AI models. Invoke when user
✅ 已就绪，等待指令
```
### 5. 等待用户指令
### 6. 等待用户指令
报告输出后，等待用户进一步指令。用户可以说：
- `展开 [某项]` → 深入查看细节
@@ -116,7 +133,11 @@ description: "Checks project context when switching AI models. Invoke when user
---
**Version**: 1.0
**Version**: 1.1
**Created**: 2026-05-23
**Updated**: 2026-05-23
**Based On**: ErrLens AI Programming Project
**Purpose**: 确保大模型切换时快速同步上下文，按角色差异化加载
**Purpose**: 确保大模型切换时快速同步上下文，按角色差异化加载
**Changes from v1.0**:
- 新增安全检查步骤，git 状态优先于上下文加载
- 增加异常处理（未提交变更/合并冲突/分支错误/远程更新）
AGENTS.md
+143 -112
View File
@@ -1,6 +1,7 @@
# AI 角色定义与权限约定
# MCU芯片测试 AI 角色定义与权限约定
## 团队架构
```
┌─────────────────────────────────────────────┐
│ 人类负责人 │
@@ -9,84 +10,73 @@
│ │
┌───────────┴──┐ ┌────┴────────────┐
▼ ▼ ▼ ▼
┌───────────────┐ ┌──────────────┐ ┌───────────────┐
│ Arch AI │ │ Dev AI │ │ QA AI │
│ 需求分析 │ │ 代码编写 │ │ 测试设计 │
│ 架构设计 │ │ 文档生成 │ │ 测试执行 │
│ 技术选型 │ │ 影响评估 │ │ 质量保障 │
│ 跨模块协调 │ └──────────────┘ └───────────────┘
└───────────────┘
┌───────────────┐ ┌──────────────┐
│ Arch AI │ │ 执行AI │
│ 需求分析 │ │ 代码实现 │
│ 架构设计 │ │ 测试执行 │
│ 测试方案设计 │ │ 报告生成 │
│ 结果分析 │ └──────────────┘
└───────────────┘
```
---
## 输入资源
项目启动时需要以下输入资源：
| 资源类型 | 存放位置 | 用途 |
|---------|---------|------|
| Excel 寄存器表格 | `docs/00_芯片资料/registers/` | Arch AI 分析芯片功能，生成寄存器定义头文件 |
| 串口 printf Demo 工程 | `projects/P01_chip_test/demo/` | 执行AI 基于该工程扩展测试功能 |
| 芯片手册 | `docs/00_芯片资料/datasheet/` | 参考文档 |
---
## 角色职责
### Arch AI (架构AI)
**职责范围：**
- ✅ 需求分析和产品规划
- ✅ 系统架构设计
- ✅ 技术选型和评估
- ✅ 跨模块协调和集成
- ✅ 编写架构文档 (`docs/`)
- ✅ 芯片功能需求分析和测试规划
- ✅ 解析 Excel 寄存器表格，生成头文件
- ✅ 测试架构设计和测试方案制定
- ✅ 编译器选择和环境配置方案
- ✅ JTAG调试流程设计
- ✅ 串口日志分析方案
- ✅ 编写测试架构文档 (`docs/`)
- ✅ 定义验收标准 (`review/*/acceptance.md`)
- ✅ 评估变更影响 (`review/*/impact.md`)
- ✅ 评估测试结果影响 (`review/*/impact.md`)
- ✅ 维护共享资源 (`shared/`)
- ✅ 维护开发工具 (`tools/`)
- ✅ 维护训练数据 (`data/`)
- ✅ 指导 Dev AI 和 QA AI 工作
- ✅ 维护测试工具 (`tools/`)
- ✅ 指导执行AI工作
**可读但不可写：**
- 👁 AI 配置文件 (`.ai/`) —— 只读，了解团队规则
- 👁 测试代码 (`projects/*/tests/`) —— 只读，了解测试覆盖
- 👁 测试报告 (`reports/`) —— 只读，了解质量状况
- 👁 测试报告 (`reports/`) —— 只读，了解测试结果
- 👁 测试反馈 (`review/*/feedback/`) —— 只读，了解问题
**禁止操作：**
- ❌ 无（架构 AI 拥有最高 AI 权限）
### Dev AI (编码AI)
### 执行AI (Executor AI)
**职责范围：**
- ✅ 编写业务代码 (`projects/*/src/`)
- ✅ 生成技术文档 (`projects/*/docs/`)
- ✅ 维护项目级文档 (`docs/`)
- ✅ 维护开发工具 (`tools/`)
- ✅ 维护训练数据 (`data/`)
- ✅ 定义验收标准 (`review/*/acceptance.md`)
- ✅ 评估变更影响 (`review/*/impact.md`)
- ✅ 维护共享资源 (`shared/`)
- ✅ 编写测试固件代码 (`projects/*/src/`)
- ✅ 配置编译环境 (Arm Clang / Keil MDK / Arm GCC)
- ✅ 通过JTAG调试下载固件 (`tools/jtag/`)
- ✅ 执行测试，收集串口日志 (`tools/uart/`)
- ✅ 单步调试和验证功能
- ✅ 生成测试报告 (`reports/`)
- ✅ 提交测试反馈 (`review/*/feedback/`)
- ✅ 补充验收标准 (`review/*/acceptance.md`)
**可读但不可写：**
- 👁 任务描述 (`review/*/task.md`) —— 只读，不可修改
- 👁 测试反馈 (`review/*/feedback/`) —— 只读，用于修 Bug
- 👁 架构文档 (`docs/`) —— 只读，了解测试方案
**禁止操作：**
- ❌ 修改测试代码 (`projects/*/tests/`)
- ❌ 修改测试报告 (`reports/`)
### QA AI (测试AI)
**职责范围：**
- ✅ 编写测试用例 (`projects/*/tests/`)
- ✅ 执行测试并生成报告 (`reports/`)
- ✅ 补充验收标准 (`review/*/acceptance.md`)
- ✅ 提交测试反馈 (`review/*/feedback/`)
**可读但不可写：**
- 👁 业务代码 (`projects/*/src/`) —— 只读，理解逻辑编写测试
- 👁 技术文档 (`projects/*/docs/`) —— 只读，了解接口设计
- 👁 项目级文档 (`docs/`) —— 只读，了解系统架构
- 👁 训练数据 (`data/`) —— 只读，了解数据分布
- 👁 共享资源 (`shared/`) —— 只读，了解工具函数
- 👁 任务描述 (`review/*/task.md`) —— 只读，了解测试目标
- 👁 验收标准 (`review/*/acceptance.md`) —— 只读，了解测试要求
**禁止操作：**
- ❌ 修改业务代码 (`projects/*/src/`)
- ❌ 修改技术文档 (`projects/*/docs/`)
- ❌ 修改测试架构设计文档
- ❌ 修改共享资源 (`shared/`)
- ❌ 修改影响评估 (`review/*/impact.md`)
- ❌ 修改开发工具 (`tools/`)
- ❌ 修改测试反馈 (`review/*/feedback/`)
- ❌ 修改任务描述和影响评估
### 人类负责人
**职责范围：**
@@ -100,10 +90,10 @@
## 工作流程
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 需求分析 │ ───→ │ 架构设计 │ ───→ │ 开发实现 │ ───→ │ 测试验证 │ ───→ │ 验收确认 │
│ (Arch AI) │ │ (Arch AI) │ │ (Dev AI) │ │ (QA AI) │ │ (人类) │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 需求分析 │ ───→ │ 测试架构 │ ───→ │ 执行测试 │ ───→ │ 验收确认 │
│ (Arch AI) │ │ (Arch AI) │ │ (执行AI) │ │ (人类) │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
↑ │
│ Bug → 修复 │
└──────────────────────┘
@@ -112,69 +102,67 @@
### 详细流程说明
**0. 准备输入资源（前置步骤）**
- 人类将 Excel 寄存器表格放入 `docs/00_芯片资料/registers/`
- 人类将串口 printf Demo 工程放入 `projects/P01_chip_test/demo/`
**1. 需求分析阶段**
- Arch AI 分析用户需求，输出产品规划
- 输出: `docs/01_产品需求/PRD.md`、`review/{task_id}/task.md`
- Arch AI 解析 Excel 寄存器表格，分析芯片功能需求，制定测试规划
- 输出: `docs/01_测试需求/`、`review/{task_id}/task.md`、寄存器定义头文件
**2. 架构设计阶段**
- Arch AI 设计系统架构，技术选型
- 输出: `docs/02_系统架构/`、`review/{task_id}/impact.md`、`review/{task_id}/acceptance.md`
**2. 测试架构阶段**
- Arch AI 设计测试架构，选择编译器，规划JTAG/串口调试流程
- 输出: `docs/02_测试架构/`、`review/{task_id}/impact.md`、`review/{task_id}/acceptance.md`
**3. 开发实现阶段**
- Dev AI 读取任务描述和验收标准，编写代码 + 文档
- 输出: `projects/*/src/`, `projects/*/docs/`
**3. 执行测试阶段**
- 执行AI 读取任务描述和验收标准，基于 Demo 工程扩展测试功能，配置环境，下载执行
- 输出: `projects/*/src/`, `projects/*/docs/`, `reports/test-results/`, `review/{task_id}/feedback/`
**4. 测试验证阶段**
- QA AI 根据验收标准编写测试，执行测试，生成报告
- 测试反馈写入 `review/{task_id}/feedback/round{round}.md`
- 输出: `projects/*/tests/`, `reports/test-results/`, `review/{task_id}/feedback/`
**4. 验收确认阶段**
- 人类审核测试报告，确认任务完成或驳回
- 确认后任务状态更新为 DONE，移入 `review/archived/`
### 缺陷修复循环
| 规则 | 说明 |
|------|------|
| 最大轮次 | 3 轮（初始测试 + 最多 2 轮修复复查） |
| 循环范围 | 测试失败 → Dev AI 修复 → QA AI 复查 |
| 跳过项 | 修复轮次中 Dev AI **只修 Bug**，不重新写 acceptance/impact |
| 循环范围 | 测试失败 → 执行AI 修复 → 执行AI 复查 |
| 跳过项 | 修复轮次中执行AI **只修固件或测试流程**，不重新写 acceptance/impact |
| 触发升级 | 第 3 轮仍有 BLOCKER 或 HIGH 级别 Bug → 暂停流转，待人类裁决 |
```
Round 1: Dev 开发 → QA 测试 → 3 个 Bug
Round 2: Dev 修复 → QA 复查 → 1 个 Bug（MEDIUM）
Round 3: Dev 修复 → QA 复查 → 0 个 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: Dev 修复 → QA 复查 → 仍 1 个 HIGH → ⚠️ 升级给人类裁决
Round 3: 执行AI 修复 → 执行AI 复查 → 仍 1 个 HIGH → ⚠️ 升级给人类裁决
```
**4. 验收确认阶段**
- 人类审核测试报告，确认任务完成或驳回
- 确认后任务状态更新为 DONE，移入 `review/archived/`
---
## 目录权限矩阵
> **图例**：`-` = 无权访问 &nbsp;&nbsp; `R` = 只读 &nbsp;&nbsp; `W` = 可写（含读） &nbsp;&nbsp; `RW` = 读写
| 目录路径 | Arch AI | Dev AI | QA AI | 人类 |
|---------|---------|--------|-------|------|
| `.ai/` | `R` | `-` | `-` | `RW` |
| `docs/` | `RW` | `RW` | `R` | `RW` |
| `tools/` | `RW` | `RW` | `-` | `RW` |
| `data/` | `RW` | `RW` | `R` | `RW` |
| `shared/` | `RW` | `RW` | `R` | `RW` |
| `projects/*/src/` | `RW` | `RW` | `R` | `RW` |
| `projects/*/tests/` | `R` | `-` | `RW` | `RW` |
| `projects/*/docs/` | `RW` | `RW` | `R` | `RW` |
| `review/*/task.md` | `RW` | `R` | `R` | `RW` |
| `review/*/acceptance.md` | `RW` | `RW` | `RW` | `RW` |
| `review/*/impact.md` | `RW` | `RW` | `-` | `RW` |
| `review/*/feedback/` | `R` | `R` | `RW` | `RW` |
| `reports/` | `R` | `-` | `RW` | `RW` |
| `.github/` | `-` | `-` | `-` | `RW` |
| 目录路径 | Arch AI | 执行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` |
> **解析优先级**：当同一条路径被多个规则匹配时，`forbidden > read_only > allowed`。禁止规则永远优先。
>
@@ -184,17 +172,17 @@ Round 3: Dev 修复 → QA 复查 → 仍 1 个 HIGH → ⚠️ 升级给人类
## 沟通规范
### Dev AI → QA AI
### Arch AI → 执行AI
在 `review/{task_id}/` 目录提交：
- **验收标准** (`acceptance.md`) - 明确测试目标
- **变更影响范围** (`impact.md`) - 指导回归测试
- **环境准备** 参考项目级 `ENVIRONMENT.md`
### QA AI → Dev AI
### 执行AI → Arch AI / 人类
在 `review/{task_id}/feedback/` 目录提交：
- **测试结果报告** (`round{round}.md`)
- **Bug清单** - 列出问题和严重程度
- **改进建议** - 代码优化建议
- **问题清单** - 列出问题和严重程度
- **改进建议** - 优化建议
---
@@ -202,7 +190,7 @@ Round 3: Dev 修复 → QA 复查 → 仍 1 个 HIGH → ⚠️ 升级给人类
### 项目命名
```
P01_项目名称 # P01 表示项目编号
P01_芯片测试项目 # P01 表示项目编号
```
### 任务编号
@@ -212,29 +200,72 @@ P01-001 # P01 项目编号 + 001 任务编号
### 分支命名
```
feature/P01-001-login # 功能开发
bugfix/P01-001-password # Bug修复
test/P01-001-testcases # 测试用例
feature/P01-001-gpio-test # 功能测试
bugfix/P01-001-uart-fix # Bug修复
test/P01-001-perf-verify # 性能验证
```
### 提交信息
```
feat(P01-001): 实现用户登录功能
fix(P01-001): 修复密码验证问题
docs(P01-001): 更新接口文档
test(P01-001): 添加登录测试用例
feat(P01-001): 实现GPIO功能测试
fix(P01-001): 修复串口日志输出问题
docs(P01-001): 更新测试架构文档
test(P01-001): 添加定时器测试用例
```
---
## 编译器配置
### 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/config/architect.json` | Arch AI 配置（权限、职责） |
| `.ai/config/coder.json` | Dev AI 配置（权限、职责） |
| `.ai/config/tester.json` | QA AI 配置（权限、职责） |
| `.ai/config/executor.json` | 执行AI 配置（权限、职责） |
| `.ai/config/workflow.json` | 工作流配置（阶段、触发器） |
| `.ai/prompts/architecture/` | 架构设计提示词模板 |
| `.ai/prompts/coding/` | 编码提示词模板 |
| `.ai/prompts/testing/` | 测试提示词模板 |
| `.ai/prompts/execution/` | 执行提示词模板 |
DECISIONS.md
+21
View File
@@ -0,0 +1,21 @@
# 待决策事项
> 人类决策入口。Arch AI 写入，人类拍板，Arch AI 执行。
> 规则：同时存在的待决策项不超过 3 条。超过则按紧急度排序，不紧急的排队等待。
---
---
## 已决策
### D-001: 确认跨平台信息架构升级方案 ✅
**日期**: 2026-05-26
**决策**: A — 确认，立即落地
**执行**: 新架构已落地。dashboard.md + DECISIONS.md + .ai/tasks/ 结构生效，旧文件归档至 .ai/archive/
**ADRs**: ADR-012
---
*当前无待决策事项。Arch AI 维护。*
README.md
+143 -69
View File
@@ -1,6 +1,19 @@
# ErrLens AI 编程项目
# ErrLens MCU芯片自动化测试项目
一个"人+3AI"协作模式的 AI 辅助编程项目仓库。
## 项目目标
基于芯片手册和 Excel 寄存器表格，通过运行软件的方式配合 JTAG 调试工具和串口工具，自动验证芯片实际功能是否与文档描述一致。
---
## 核心特性
- ✅ Excel 寄存器表格解析 → 自动生成寄存器定义头文件
- ✅ 自动生成测试代码 → 寄存器读写测试、功能验证
- ✅ JTAG 自动化下载 + 运行
- ✅ 串口日志监控 + 自动分析
- ✅ 测试结果自动验证 + 报告生成
- ✅ "人+Arch AI+执行AI" 协作模式
---
@@ -14,61 +27,53 @@
├── .ai/ # AI协作核心配置
│ ├── config/
│ │ ├── architect.json # Arch AI 配置
│ │ ├── coder.json # Dev AI 配置
│ │ ├── tester.json # QA AI 配置
│ │ ├── executor.json # 执行AI 配置
│ │ └── workflow.json # 工作流配置
│ └── prompts/
│ ├── architecture/ # 架构设计提示词模板
│ ├── coding/ # 编码提示词模板
│ └── testing/ # 测试提示词模板
├── docs/ # 项目级总体文档
│ ├── 01_产品需求/
│ ├── 02_系统架构/
│ ├── 03_开发规范/
│ ├── 04_部署运维/
│ ├── 05_变更日志/
│ │ └── archived/ # 历史变更日志（按年月归档）
│ └── 06_开发日志/
├── tools/ # 开发工具脚本
├── data/ # 训练数据
├── projects/ # 项目代码
│ ├── P01_errlens_app/ # 主应用项目
│ │ ├── src/ # 业务代码 (Dev AI)
│ │ ├── tests/ # 测试代码 (QA AI)
│ │ ├── docs/ # 项目文档 (Dev AI)
│ │ │ ├── 01_需求概要.md
│ │ │ ├── 02_架构设计.md
│ │ │ └── 03_接口定义.md
│ └── 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_errlens_training/ # AI训练项目
│ └── P02_ext_test/ # 扩展测试项目
│ ├── src/
│ ├── tests/
│ ├── docs/
│ │ ├── 01_需求概要.md
│ │ ├── 02_架构设计.md
│ │ └── 03_训练流程.md
│ └── ENVIRONMENT.md
├── review/ # 交接中心
│ ├── active/ # 活跃任务
│ │ ├── P01-001/ # 项目1-任务001
│ │ ├── P01-001/ # 项目1-任务1
│ │ │ ├── task.md # 任务描述
│ │ │ ├── acceptance.md # 验收标准
│ │ │ ├── impact.md # 变更影响范围
│ │ │ └── feedback/ # 反馈记录
│ │ │ └── round1.md
│ │ ├── P01-002/ # 项目1-任务002
│ │ ├── P02-001/ # 项目2-任务001
│ │ └── CROSS-001/ # 跨项目任务
│ │ └── ...
│ └── archived/ # 已完成任务（按季度归档）
│ ├── 2026-Q2/
│ └── 2026-Q3/
├── shared/ # 共享资源
│ └── 2026-Q2/
├── shared/ # 共享资源 (Arch AI 可写，执行AI 只读)
│ ├── scripts/ # 共享脚本
│ ├── templates/ # 代码/文档模板
│ │ └── parse_registers.py # Excel寄存器表格解析工具
│ ├── templates/ # 固件代码模板
│ └── utils/ # 工具函数
├── reports/ # 统一报告
│ ├── test-results/ # 测试结果
│ └── quality-reports/ # 质量评审报告
├── reports/ # 统一报告 (执行AI 可写)
│ ├── test-results/ # 测试结果报告
│ └── quality-reports/ # 质量分析报告
└── .github/ # CI/CD配置
└── workflows/
```
@@ -79,22 +84,40 @@
| 角色 | 是谁 | 干什么 | 不干什么 |
|------|------|--------|----------|
| **人类负责人** | 你 | 下指令、审阅、做决策、定验收标准 | 不写代码、不写测试 |
| **Arch AI** | Claude/TRAE/元宝等 | 需求分析、架构设计、技术选型、跨模块协调 | 不写测试 |
| **Dev AI** | Claude/TRAE/元宝等 | 写业务代码+文档、修bug、写impact | 不动tests/、不跑测试 |
| **QA AI** | 扣子编程AI | 写测试、跑测试、写反馈 | 不动src/、不改业务代码 |
| **人类负责人** | 你 | 下指令、审阅、做决策、定验收标准 | 不写代码、不执行测试 |
| **Arch AI** | Claude/TRAE/元宝等 | 需求分析、测试架构设计、编译器选择、JTAG调试流程设计 | 不直接执行硬件测试 |
| **执行AI** | Claude/TRAE/扣子等 | 写测试固件、编译下载、JTAG调试、串口监控、写测试报告 | 不修改测试架构、不动 shared/ |
---
## 工作流程
1. **Arch AI** 分析需求，输出 `docs/01_产品需求/PRD.md` 和 `review/active/P01-001/task.md`
2. **Arch AI** 设计架构，输出 `docs/02_系统架构/`、`acceptance.md`、`impact.md`
3. **Dev AI** 在 `projects/P01_errlens_app/src/` 写代码，在 `docs/` 写文档
4. **你**审一眼，没问题就触发QA AI
5. **QA AI** 读 `task.md` + `acceptance.md` + `impact.md`，按 `ENVIRONMENT.md` 准备环境，在 `tests/` 写测试并执行，写 `feedback/round1.md`
6. **有bug** → 你看反馈 → 让Dev AI修 → 回到步骤3（round2）
**通过** → 你确认 → 任务关闭，报告归档到 `reports/`
### 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**: 下载固件、单步调试
- **串口**: 监控日志输出、查看测试结果
---
@@ -111,13 +134,73 @@ status: TODO | IN_PROGRESS | REVIEW | DONE | ARCHIVED
---
## 决策总结
## 参考文档
| 问题 | 决策 |
| 文件 | 说明 |
|------|------|
| 任务创建 | 先手动，中期脚本化（create-task.sh），后期CI联动Issue |
| 跨项目任务 | `CROSS-xxx/`，feedback按项目分文件（如 `P01-round1.md`） |
| 任务归档 | `review/active/` + `review/archived/2026-Qx/`，状态字段驱动，定期归档 |
| [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`
---
@@ -128,27 +211,18 @@ status: TODO | IN_PROGRESS | REVIEW | DONE | ARCHIVED
git clone <repository-url>
cd errlens
# 查看目录结构
find . -type d | sort
# 阅读协作规则
cat AGENTS.md
# 查看当前任务
ls -la review/
ls -la review/active/
```
---
## 参考文档
| 文件 | 说明 |
|------|------|
| [AGENTS.md](AGENTS.md) | AI角色定义与权限约定 |
| [workflow.json](.ai/config/workflow.json) | 工作流配置 |
| [P01-001 任务](review/P01-001/task.md) | 示例任务单 |
---
## 版本历史
| 版本 | 日期 | 说明 |
|------|------|------|
| v1.0 | 2026-05-22 | 初始版本，完成目录结构设计 |
| v2.0 | 2026-05-22 | 重构为MCU芯片测试架构，三角色：人+Arch AI+执行AI |
| v1.0 | 2026-05-22 | 初始版本，完成目录结构设计 |
SYNC.md
+83
View File
@@ -0,0 +1,83 @@
# 模板同步边界定义
> 定义哪些文件属于"框架层"（跨项目复用），哪些属于"项目层"（项目特有）。
> 框架层变化通过 `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/ 已纳入框架层定义
TEMPLATE.yaml
+37
View File
@@ -0,0 +1,37 @@
# ============================================================
# 项目模板变量定义
# 用于 project-init Skill 的 export/init 双向替换
# ============================================================
# --- 项目身份 ---
PROJECT_NAME: "ErrLens"
PROJECT_NAME_LOWER: "errlens"
PROJECT_CONCEPT: "学生错题本"
PROJECT_DESCRIPTION: "AI 驱动的学生错题整理与分析应用"
# --- 子项目 P01（主应用）---
P01_NAME: "P01_errlens_app"
P01_DESC: "ErrLens 主应用"
P01_FRONTEND: "Taro 4 + React 18 + TypeScript"
P01_BACKEND: "NestJS 10 + TypeScript"
# --- 子项目 P02（训练/AI）---
P02_NAME: "P02_errlens_training"
P02_DESC: "ErrLens AI 训练模块"
# --- 子项目 P03（管理后台）---
P03_NAME: "P03_errlens_web"
P03_DESC: "ErrLens Web 管理后台"
# --- 阶段定义 ---
PHASE1_NAME: "基础搭建"
PHASE1_GOAL: "搭建项目骨架：协作框架、脚手架、权限体系"
PHASE2_NAME: "MVP"
PHASE2_GOAL: "实现学生错题本核心功能"
PHASE3_NAME: "功能完善"
PHASE3_GOAL: "功能迭代、多端适配、性能优化"
PHASE4_NAME: "打磨发布"
PHASE4_GOAL: "质量提升、安全审计、文档完善"
# --- 数据库 ---
DATABASE_URL: "postgresql://user:password@localhost:5432/errlens"
dashboard.md
+130
View File
@@ -0,0 +1,130 @@
# ErrLens 项目控制面板
> 唯一真实来源。人类看顶部，Arch AI 看全文，Worker AI 看 task 文件。
> 旧入口（DASHBOARD.md / ROADMAP.md / roles/*/today.md / roles/*/queue.md）已归档。
---
## 人类区
**Phase 2/4 — MVP 开发** · 进度 0%
| 阶段 | 状态 | 进度 |
|------|------|------|
| 1. 基础搭建 | ✅ | 100% |
| 2. MVP | ← 当前 | 0% |
| 3. 功能完善 | 未开始 | 0% |
| 4. 打磨发布 | 未开始 | 0% |
### 需要你决策
当前无待决策事项。
### 上次决策追踪
| 决策 | 日期 | 结果 | 落实到 |
|------|------|------|--------|
| D-001 | 2026-05-26 | A — 确认跨平台信息架构升级方案 | ADR-012，新架构已落地 |
---
## Arch AI 区
### ADR 摘要索引
| ADR | 一句话 | 状态 |
|-----|--------|------|
| 001 | 「1 人 + 3 AI」三角协作框架 | ✅ |
| 002 | 四级权限体系（-/R/W/RW） | ✅ |
| 003 | 根级 docs/ 目录 | ✅ |
| 004 | 独立 tools/ + data/ 目录 | ✅ |
| 005 | 测试→修复 3 轮升级机制 | ✅ |
| 006 | resume-context 多机同步 | ✅ |
| 007 | 分层信息架构 + Token 预算 | ✅ |
| 008 | 框架/项目双分支 + sync-template.sh | ✅ |
| 009 | 人机协同数据质量闭环（AI 草稿→人编辑） | ✅ |
| 010 | Adapter Pattern 多题库源统一接入 | ✅ |
| 011 | 不急于引入多 Agent 编排，先精简后分层 | ✅ 已被 012 修正 |
| 012 | 跨平台「高模型指挥小模型」协作架构 | ✅ 当前基准 |
### Task 状态面板
**Coder 任务 (Trae + GLM-4.6)**：
| Task | 描述 | 优先 | 状态 | 依赖 | 分配给 |
|------|------|------|------|------|--------|
| [P01-001](.ai/tasks/active/P01-001.md) | DB Schema + 迁移脚本 | P0 | todo | — | Coder |
| [P01-002](.ai/tasks/active/P01-002.md) | Auth 模块（微信登录+JWT） | P0 | todo | P01-001 | Coder |
| [P01-005](.ai/tasks/active/P01-005.md) | Image 模块（图像预处理管线） | P0 | todo | P01-001 | Coder |
| [P01-006](.ai/tasks/active/P01-006.md) | Print 模块（PDF+S3+清理） | P0 | todo | P01-001 | Coder |
| [P01-004](.ai/tasks/active/P01-004.md) | Upload 模块（图片上传+S3） | P1 | todo | P01-001 | Coder |
| [P01-003](.ai/tasks/active/P01-003.md) | User 模块（CRUD+邀请链） | P1 | todo | P01-002 | Coder |
| [P01-007](.ai/tasks/active/P01-007.md) | 页面路由+骨架（含打印页） | P1 | todo | P01-003 | Coder |
| [CROSS-001](.ai/tasks/active/CROSS-001.md) | 共享工具库日期格式修复 | P0 | todo | — | Coder |
**Tester 任务 (Coze CN)**：
| Task | 描述 | 优先 | 状态 | 对应 Coder task |
|------|------|------|------|-----------------|
| [T01-001](.ai/tasks/active/T01-001.md) | DB Schema 验证 | P0 | todo | P01-001 |
| [T01-002](.ai/tasks/active/T01-002.md) | Auth 模块测试 | P0 | todo | P01-002 |
| [T01-003](.ai/tasks/active/T01-003.md) | Image+Upload 联测 | P0 | todo | P01-005, P01-004 |
| [T01-004](.ai/tasks/active/T01-004.md) | Print 模块测试 | P0 | todo | P01-006 |
| [T01-005](.ai/tasks/active/T01-005.md) | User 模块+日期修复验证 | P1 | todo | P01-003, CROSS-001 |
| [T01-006](.ai/tasks/active/T01-006.md) | 页面骨架+API 集成测试 | P1 | todo | P01-007 |
**状态流转**: `todo → in_progress → done → tested → accepted`
**交接信号**: Coder 完成 → commit message 包含 `[READY_FOR_TEST]` → Tester 自动发现
### 依赖关系
```
P01-001 (DB Schema)
├─→ P01-002 (Auth) ──→ P01-003 (User) ──→ P01-007 (Pages)
├─→ P01-004 (Upload) ──→ P01-005 (Image)
└─→ P01-006 (Print)
```
### 阻塞/风险
| 级别 | 描述 | 影响 |
|------|------|------|
| YELLOW | CROSS-001 日期格式 bug | 影响所有日期字段展示 |
---
## 关键文档入口
| 想查什么 | 路径 |
|----------|------|
| 产品需求 | [docs/01_产品需求/PRD.md](docs/01_产品需求/PRD.md) |
| 系统架构 | [docs/02_系统架构/](docs/02_系统架构/) |
| ADR 全文 | [.ai/knowledge/decisions.md](.ai/knowledge/decisions.md) |
| 经验教训 | [.ai/knowledge/lessons.md](.ai/knowledge/lessons.md) |
| 可复用模式 | [.ai/knowledge/patterns.md](.ai/knowledge/patterns.md) |
| 分享文章 | [docs/share/](docs/share/) |
| 待人类决策 | [DECISIONS.md](DECISIONS.md) |
| 架构决策全文 | [.ai/knowledge/decisions.md](.ai/knowledge/decisions.md) |
---
## 角色入口
| 角色 | 平台+模型 | 入口 |
|------|----------|------|
| 人类 | — | 本文件顶部「人类区」 |
| Arch AI | Claude Code + DeepSeek V4 Pro | 本文件全文 |
| Coder AI | Trae CN + GLM-4.6 | [.ai/roles/dev/card.md](.ai/roles/dev/card.md) → 对应 task 文件 |
| Tester AI | Coze CN | [.ai/roles/qa/card.md](.ai/roles/qa/card.md) → 对应 task 文件 |
---
## 最近事件
| 日期 | 事件 |
|------|------|
| 2026-05-26 | 信息架构升级：三层四角色控制面板 + 跨平台 task 交接协议 |
| 2026-05-26 | Phase 1 收尾（100%），Phase 2 启动 |
| 2026-05-26 | 旧架构合并完成：30 项决策落地，架构文档 v0.4.0 |
*Arch AI 维护。阶段切换时更新。不随每日任务变化。*
docs/00_芯片资料/README.md
+32
View File
@@ -0,0 +1,32 @@
# 芯片资料
## 目录结构
```
docs/00_芯片资料/
├── registers/ # Excel 寄存器表格
│ ├── GPIO.xlsx # GPIO 寄存器定义
│ ├── UART.xlsx # UART 寄存器定义
│ └── ...
└── datasheet/ # 芯片手册
├── MCU_datasheet.pdf
└── ...
```
## 寄存器表格格式
Excel 表格包含以下字段：
| 字段 | 说明 |
|------|------|
| 寄存器名 | 寄存器名称 |
| 地址 | 寄存器地址 |
| 位 | 位位置 |
| 名称 | 位域名称 |
| 描述 | 位域描述 |
| 复位值 | 复位默认值 |
## 使用说明
1. 把芯片寄存器 Excel 表格放入 `registers/` 目录
2. 芯片手册放入 `datasheet/` 目录
3. Arch AI 会基于这些资料设计测试方案
docs/00_芯片资料/registers/REGISTERS_TEMPLATE.md
+29
View File
@@ -0,0 +1,29 @@
# Excel 寄存器表格格式说明
## 表格列
Excel 表格需要包含以下列：
| 列名 | 说明 | 必填 | 示例 |
|------|------|------|------|
| 寄存器名 | 寄存器的宏定义名称 | 是 | GPIOA_MODER |
| 地址 | 寄存器物理地址 | 是 | 0x40020000 |
| 描述 | 寄存器功能描述 | 否 | GPIOA 模式寄存器 |
| 复位值 | 芯片复位后寄存器的值 | 否 | 0x00000000 |
## 示例数据
| 寄存器名 | 地址 | 描述 | 复位值 |
|----------|------|------|--------|
| GPIOA_MODER | 0x40020000 | GPIOA 模式寄存器 | 0xA8000000 |
| GPIOA_OTYPER | 0x40020004 | GPIOA 输出类型寄存器 | 0x00000000 |
| GPIOA_OSPEEDR | 0x40020008 | GPIOA 输出速度寄存器 | 0x00000000 |
| GPIOA_PUPDR | 0x4002000C | GPIOA 上拉/下拉寄存器 | 0x00000100 |
| GPIOA_IDR | 0x40020010 | GPIOA 输入数据寄存器 | N/A |
## 使用说明
1. 准备你的寄存器 Excel 表格
2. 命名为 `xxx_registers.xlsx`
3. 放入本目录 `docs/00_芯片资料/registers/`
4. 运行 `python3 shared/scripts/parse_registers.py` 解析
docs/01_产品需求/PRD.md
+472
View File
@@ -0,0 +1,472 @@
# ErrLens 产品需求文档
> 版本: v0.4.0 | 状态: 已锁定 | 作者: Arch AI | 最后更新: 2026-05-26（旧架构合并）
---
## 1. 产品定位
### 1.1 一句话描述
ErrLens 是一款面向小学初中学生的 **AI 错题本**，帮助学生或家长拍照录入错题、自动归类分析、输出 PDF 练习、获得针对性练习推荐。
### 1.2 核心价值
传统错题本需要学生手动抄题、自己分类、凭感觉复习。ErrLens 将这些步骤交给 AI：
- **录入**: 拍照即可，AI 自动识别题目、答案、学科
- **分析**: AI 诊断错误原因（知识点欠缺/粗心/审题偏差），汇总薄弱点
- **推荐**: 基于错题模式，从题库中匹配同类题目，针对性巩固
### 1.3 核心飞轮（人机协同版）
AI 识别不可能 100% 准确（尤其手写体），飞轮不能建立在"AI 完美识别"的假设上。正确模型是：
```
拍照录入错题
→ AI 识别 + 置信度评估（识别、分类、知识点标注各带分数）
→ 高置信度字段自动填充，低置信度字段高亮提示用户确认
→ 用户修正/确认后入库（人工校验过的数据才是"干净数据"）
→ 干净数据 → AI 分析错误原因 → 识别薄弱知识点
→ 推荐同类练习 → 更多错题数据 → 修正记录积累
→ 反馈训练（P02 阶段：用"AI 识别 vs 用户修正"的 delta 微调模型）
```
**关键认知**：
- AI 识别结果不是"答案"，是"草稿"——用户确认前不进入分析管道
- 用户每一次修正都是**免费的标注数据**，是训练 P02 自有模型的核心资产
- 飞轮飞起来靠的不是 AI 一开始有多准，而是用户修正成本有多低
### 1.4 竞品差异化
| 维度 | 传统错题本 App | ErrLens |
|------|---------------|---------|
| 录入方式 | 手动输入/拍照 OCR | AI 识别 + 置信度标注 + 用户修正 |
| 分析深度 | 按学科/章节归类 | 知识点粒度 + 错误原因诊断 |
| 推荐逻辑 | 随机/按章节 | 基于错题模式的个性化推荐 |
| 数据飞轮 | 无 | 用户修正数据反哺模型训练 |
---
## 2. 目标用户
### 2.1 核心用户画像
| 画像 | 描述 | 核心需求 |
|------|------|----------|
| **小初高学生** | 10-18 岁，有日常作业和考试，可自己操作也可家长代操作 | 快速录入、自动整理、考前针对性复习 |
| **家长** | 关注孩子学习状况，代孩子拍照整理、打印练习题 | 查看分析报告、了解进步轨迹、错题打印 |
| **老师（扩展）** | 管理班级，了解全班错题分布 | 班级错题统计、教学重点调整 |
### 2.2 MVP 阶段聚焦
- **P0**: 小初高学生 + 家长（均可操作，交互低门槛年轻化）
- **P1**: 学习报告、练习推荐
- **Phase 3+**: 老师端
---
## 3. 功能需求
### 3.1 MVP 功能清单 (Phase 2)
| 模块 | 功能 | 优先级 | 说明 |
|------|------|--------|------|
| **错题录入** | 拍照录入 | P0 | 拍照 → 图像预处理 → AI 识别题目+答案+学科 |
| | 手动录入 | P0 | 文字输入兜底方案 |
| | 批量导入 | P2 | 从试卷照片一次识别多道题 |
| **错题管理** | 错题列表 | P0 | 按时间/学科/知识点筛选 |
| | 错题详情 | P0 | 题目、错误答案、正确答案、分析 |
| | 错题编辑 | P1 | 修正 AI 识别结果 |
| **AI 分析** | 错误原因诊断 | P0 | 标注错误类型（知识点/粗心/审题） |
| | 薄弱点汇总 | P0 | 按知识点统计薄弱程度 |
| | 学习报告 | P1 | 周/月度错题趋势报告 |
| **练习推荐** | 同类题推荐 | P1 | 关键词+Jaccard 粗筛 → AI 精排 |
| | 智能组卷 | P2 | 自动生成针对性练习卷 |
| **错题打印** | PDF 输出 | P0 | 选题 → 生成 PDF → 下载（24h 有效） |
| **用户系统** | 注册/登录 | P0 | 微信授权登录 |
| | 个人资料 | P1 | 年级（小初）、学科设置 |
| | 学科管理 | P1 | 添加/切换学科 |
### 3.2 功能详情
#### 3.2.1 拍照录入（P0 核心流程）
```
拍照 → 裁剪/确认 → 图像预处理 → AI 识别 → 置信度评估 → 确认/修正 → 保存
│
├─ 透视校正（手动框4角）
├─ CLAHE 增强（光照归一化）
└─ 笔迹去除（红/蓝笔HSV自动去除）
↓
提取: 题目文本、学科、知识点、错误答案
每个字段附带 confidence: 0.0-1.0
↓
高置信(>0.9): 绿色标记，自动采纳
中置信(0.7-0.9): 黄色标记，建议检查
低置信(<0.7): 红色标记，提示手动确认
↓
用户修正 → 修正字段记录到 correction_log
原始 AI 结果 + 用户修正值 一并入库
```
**置信度分字段展示**:
- OCR 文本置信度（手写体通常更低）
- 学科分类置信度
- 知识点标注置信度
- 错误类型诊断置信度
每个字段独立展示置信度，用户可逐个修正。低置信度字段高亮提示，不阻塞整体流程（用户可跳过修正，但数据标记为 unverified）。
**交互要点**:
- 拍照后展示识别结果，低置信度字段红色高亮
- 点击任意 AI 识别结果可进入编辑态修正
- 识别中展示 loading 动画（预期 3-5 秒）
- 支持从相册选择已有截图/照片
- "正确答案"字段独立，可留空（学生可能还不知道正确答案）
**AI 能力需求**:
- OCR 文字识别（手写体 + 印刷体）
- 学科分类（数学/语文/英语/物理/化学/生物/地理/历史/政治）
- 知识点标注（如"二次函数"、"定语从句"）
- 题目结构提取（题干/选项/答案区）
#### 3.2.2 错题列表（P0）
**列表视图**:
- 默认按时间倒序
- 筛选器：学科、知识点、时间范围、错误类型
- 每项展示：题目缩略图、学科标签、知识点标签、录入日期
- 搜索：按题目关键词搜索
**分组视图**:
- 按知识点分组（展示每个知识点的错题数量和掌握度）
- 按学科分组
#### 3.2.3 AI 分析（P0）
**单题分析**:
- 错误类型分类：知识点欠缺 / 粗心失误 / 审题偏差 / 概念混淆
- 关联知识点（可能有多个）
- 难度评估：基础 / 中等 / 拔高
**汇总分析**:
- 薄弱知识点排序（按错误频率和严重程度）
- 错误类型分布饼图
- 学科间对比
#### 3.2.4 错题打印/PDF 输出（P0）
**打印流程**:
```
选题（错题列表中勾选）→ 生成 PDF → 预览 → 下载 → 自行打印
```
**PDF 排版优先级**:
1. 结构化内容（题库匹配的题目，文字+公式清晰排版）
2. 增强图片（经 CLAHE+笔迹去除处理后的图片）
3. 原始图片（无匹配时兜底）
**交互要点**:
- 错题列表页支持多选模式（勾选要打印的题目）
- PDF 生成中展示进度（预计 5-10 秒）
- 生成后预览页支持手势缩放
- 下载链接 24 小时有效，过期自动清理
- 支持分享到微信（发送 PDF 文件给家长/老师）
#### 3.2.5 练习推荐（P1）
**推荐逻辑**:
1. 基于薄弱知识点权重排序
2. 匹配题库中同知识点、同难度题目
3. 优先推荐"高频易错"题型
4. 已掌握的题目降低推荐权重
**推荐展示**:
- 每日推荐: 3-5 道针对性练习
- 自定义练习: 选择知识点 + 数量，一键生成
### 3.3 数据质量与人机协同修正
#### 3.3.1 核心设计原则
**用户每次修正都是免费的标注数据。** 这是 ErrLens 相对于纯 AI 方案的核心壁垒。
- AI 识别是"草稿"，不是"答案"
- 用户确认前的数据不进入分析和推荐管道
- 修正记录（AI 输出 vs 用户修正）是 P02 自研模型的核心训练数据
#### 3.3.2 数据校验状态机
```
AI 识别完成
│
▼
┌────────────────┐
│ raw │ 原始 AI 识别结果，未确认
│ 进入错题列表 │ 仅对用户可见，不参与分析
│ 不可用于推荐 │
└───────┬────────┘
│ 用户查看/修正
▼
┌────────────────┐
│ reviewed │ 用户已确认/修正
│ 参与薄弱点分析 │ 所有字段经人工校验
│ 参与练习推荐 │
└───────┬────────┘
│ 用户再次修正
▼
┌────────────────┐
│ corrected │ 用户二次修正（覆盖上次）
│ 分析/推荐更新 │
└────────────────┘
```
**关键规则**:
- `raw` 状态的错题仅用户自己可见，不计入 AnalysisReport
- 从 `raw` → `reviewed` 的最小操作：用户至少查看一次并点击"确认"按钮（批量确认支持）
- 从 `reviewed` → `corrected`：用户主动编辑了 AI 识别的字段
- 30 天后仍为 `raw` 的错题标记为 `stale`，系统定期提醒用户确认
#### 3.3.3 置信度分字段评估
AI 对每个字段独立输出置信度 [0.0-1.0]：
| 字段 | 影响因素 | 典型置信度 |
|------|----------|-----------|
| 题目文本 (question_text) | 手写体 vs 印刷体、图片清晰度 | 印刷体 0.9+，工整手写 0.7-0.9，潦草手写 0.5-0.7 |
| 学科分类 (subject_id) | 题目文本中的关键词密度 | 数学符号明显的题 0.9+，文科主观题 0.6-0.8 |
| 知识点标注 (knowledge_points) | 知识树覆盖度、题干关键词匹配 | 主流知识点 0.8+，冷门知识点 0.5-0.7 |
| 错误类型 (error_type) | 错误答案与正确答案的对比清晰度 | 有正确答案时 0.8+，无正确答案时 0.5-0.7 |
| 正确答案 (correct_answer) | AI 是否能看到标答区域 | 扫描的试卷答案区 0.9+，纯题目照片 0.5-0.7 |
#### 3.3.4 修正记录 (Correction Log)
每次用户修正，记录原始 AI 值和用户修正值：
```json
{
"error_item_id": "uuid",
"field": "knowledge_points",
"ai_value": [1021], // AI 识别：顶点坐标
"user_value": [1022], // 用户修正：图像性质
"ai_confidence": 0.72,
"corrected_at": "2026-05-26T10:30:00Z"
}
```
**用途**:
1. **即时**: 修正后立即更新错题数据，参与分析和推荐
2. **分析**: 统计各字段修正率，识别 AI 薄弱环节（哪个学科/知识点修正率最高）
3. **训练 (P02)**: AI 识别 vs 用户修正的 delta 是微调自有模型的核心训练数据
#### 3.3.5 交互策略
**确认界面分级提示**:
| 置信度区间 | 视觉标记 | 交互行为 |
|-----------|---------|---------|
| > 0.9 | 绿色边框 | 默认展示，无需操作 |
| 0.7 - 0.9 | 黄色边框 + 虚线 | 建议点击查看 |
| < 0.7 | 红色边框 + 闪烁 | 弹提示建议手动修正 |
| — | 无 AI 结果 | 空白输入框，用户手动填写 |
**批量确认**: 多道题一起拍照后，在列表页支持批量"一键确认"，降低确认摩擦。
**修正激励**: 未来（Phase 3）可引入修正积分/成就，鼓励学生认真修正（干净数据=更好的推荐=对自己有用）。
---
## 4. 非功能需求
### 4.1 性能
| 指标 | 目标值 |
|------|--------|
| 小程序首屏加载 | < 2s |
| AI 识别响应 | < 5s（拍照→结果展示） |
| 列表滚动 | 60fps，虚拟列表 |
| 图片上传 | < 3s（压缩后 < 500KB） |
| API 响应 | P95 < 200ms |
### 4.2 安全
- 微信授权登录，不存储密码
- 用户错题数据隔离，API 层鉴权
- 图片上传签名 URL，防恶意上传
- 敏感信息（姓名、学校）传输加密
### 4.3 兼容性
- 微信小程序基础库 ≥ 3.0
- iOS 14+ / Android 8+
- 屏幕适配：375-428px 逻辑宽度
### 4.4 可用性
- 核心流程（拍照→保存）不超过 3 步
- 关键操作有明确反馈（loading/成功/失败）
- 网络异常时有缓存兜底和重试提示
- 首次使用有引导（不强制）
---
## 5. 数据模型（高层）
### 5.1 核心实体
```
User (用户)
- id, nickname, avatar, grade, created_at
Subject (学科)
- id, name, icon
KnowledgePoint (知识点)
- id, name, subject_id, parent_id (树形结构)
ErrorItem (错题)
- id, user_id, subject_id
- image_url (原始图片)
- question_text (题目文本，AI 提取)
- wrong_answer (错误答案)
- correct_answer (正确答案，可选)
- knowledge_points[] (关联知识点)
- error_type (错误类型)
- difficulty (难度)
- verification_status: raw | reviewed | corrected | stale
- ai_confidence: JSONB（各字段的 AI 置信度）
- note (学生备注)
- created_at, updated_at
CorrectionLog (修正记录) [P02 训练数据]
- id, error_item_id, field_name
- ai_value (AI 原始值)
- user_value (用户修正值)
- ai_confidence (该字段置信度)
- corrected_at
AnalysisReport (分析报告)
- id, user_id
- period (week/month)
- weak_points[] (薄弱知识点+权重)
- error_type_distribution
- trend (进步/退步/持平)
- generated_at
PracticeRecommendation (练习推荐)
- id, user_id
- knowledge_points[]
- questions[] (推荐的题目)
- generated_at
PrintTask (打印任务)
- id, user_id
- error_item_ids[]
- output_mode: pdf
- file_url, expires_at
- created_at
```
### 5.2 MVP 阶段简化
- KnowledgePoint 使用预设知识树（非 AI 自动生成）
- 题库推荐初期使用外部题库 API，后续自建
- 分析报告先做单题分析，汇总报告 P1
- **CorrectionLog MVP 即入库，但 P02 阶段才用于训练**
- **AnalysisReport 仅统计 verification_status != raw 的错题**
---
## 6. 用户旅程
### 6.1 核心旅程：首次使用
```
1. 打开小程序 → 微信授权登录
2. 设置年级 + 学科（初中二年级 + 数学）
3. 进入首页 → 看到空状态：「还没有错题，拍一张吧」
4. 点击拍照按钮 → 拍摄一道错题 → AI 识别中（3-5s）
5. 确认识别结果 → 「分析完成！这道题是【二次函数-顶点坐标】没掌握」
6. 回到首页 → 错题列表出现第一条记录
7. 底部「薄弱点」tab → 看到第一个薄弱知识点标记
```
### 6.2 核心旅程：日常使用
```
1. 每天做完作业 → 打开 ErrLens
2. 拍照录入 2-3 道错题
3. 查看 AI 分析：「今天主要是计算粗心」
4. 周末 → 收到推送：「本周薄弱点是【全等三角形判定】，已生成针对性练习」
5. 完成推荐练习 → 错题本记录更新
```
---
## 7. 项目分期
| 阶段 | 范围 | 交付物 |
|------|------|--------|
| Phase 1 (当前) | 基础搭建 | 协作框架、脚手架、信息架构 |
| Phase 2 (MVP) | 核心闭环 | 拍照录入 + 错题管理 + AI 分析 + 用户系统 |
| Phase 3 | 功能完善 | 练习推荐 + 学习报告 + 家长端 + P02/P03 启动 |
| Phase 4 | 打磨发布 | 性能优化 + 安全审计 + 上线准备 |
---
## 8. MVP 验收标准 (Phase 2)
- [ ] 用户可以微信授权登录
- [ ] 用户拍照后 5 秒内看到识别结果（含置信度标注）
- [ ] 图像预处理管线完整运行（透视校正+增强+笔迹去除）
- [ ] 低置信度字段红色高亮，用户可逐字段修正
- [ ] 用户可以批量确认多道错题
- [ ] 用户可以在错题列表中按学科、校验状态筛选
- [ ] AI 可以诊断错误原因并关联知识点
- [ ] 用户可以查看薄弱点汇总（仅统计 reviewed 及以上状态）
- [ ] 用户可以勾选错题生成 PDF 并下载（24h 有效）
- [ ] PDF 排版清晰度满足打印标准（300DPI）
- [ ] 核心流程有完整的 loading/成功/失败反馈
- [ ] 置信度 UI 分级显示（绿/黄/红）正确运行
- [ ] `raw` 状态的错题不参与分析和推荐
---
## 9. 风险与假设
### 9.1 关键假设
1. AI OCR 对手写体的识别率能达到可用水平（>70% 即满足 MVP，用户修正兜底）
2. 用户愿意在拍照后花 10-20 秒确认/修正 AI 识别结果
3. 学生/家长愿意每天花 2-3 分钟录入错题
4. 微信小程序审核能通过教育类目
5. 题库资源可获取（合作或爬取）
### 9.2 主要风险
| 风险 | 影响 | 缓解措施 |
|------|------|----------|
| AI 识别准确率不足 | 用户不信任，放弃使用 | **架构层面：置信度分层 + 用户修正闭环，AI 定位为"草稿"而非"答案"；MVP 优先优化印刷体 OCR** |
| 用户修正率低（不确认 raw 数据） | 飞轮无数据可用 | 批量确认降低摩擦；定期提醒 stale 数据；确认操作设计为一次点击 |
| 修正数据质量差（用户胡乱修正） | 训练数据被污染 | 修正记录对比 AI 值，异常修正（如学科从数学改体育）标记审查 |
| 图像预处理管线复杂度高 | 开发周期延长 | 模块化降级策略：任何模块失败不阻塞整体流程；Coze 沙盒中重新调优参数 |
| 题库内容不足 | 推荐功能无法上线 | 先接入第三方题库 API |
| 增长缓慢 | 飞轮无法启动 | 考虑学校/班级团购模式 |
| 小程序审核受限 | 无法发布 | 优先微信小程序，H5 兜底 |
---
## 10. 待决策事项
以下事项需要人类确认后锁定：
- [x] 题库来源：**两者都要**。自有本地题库（PDF 手动录入）提供差异化内容，作业帮 API 冷启动兜底。架构需支持多题库源抽象层。
- [x] AI 能力来源：**分层使用**。Coze SDK 做测试/验证，其他 AI 做 Coding 实现，Claude 做架构设计。各角色可交叉协作，不僵化绑定。
- [x] 用户体系：**MVP 仅微信小程序登录**。增长模式：已有用户/老师/机构通过扫码分享注册，形成用户群的**树状结构**（邀请链）。架构需支持邀请关系建模。
- [x] 商业化方向：**基础免费 + 会员**。MVP 阶段全功能免费（积累用户），会员功能在 Phase 3 设计。架构预留能力开关。
- [x] 首发学科：**数学 + 英语**。两个学科同时首发，知识树需覆盖数学和英语两套知识体系。
---
*PRD 状态: 草案 → 已锁定（v0.3.0，5 项决策已确认）*
docs/01_产品需求/README.md
+19
View File
@@ -0,0 +1,19 @@
# 产品需求
本目录存放产品需求文档。文档由 Arch AI 编写，人类审阅。
## 文件说明
| 文件 | 说明 | 状态 |
|------|------|------|
| PRD.md | 产品需求文档（主文档） | ✅ 草案完成，待人类审阅 |
## 编写时机
Phase 1 基础搭建阶段完成信息架构重构后，Arch AI 将在此编写 PRD。
## 相关链接
- 阶段上下文: `.ai/phases/phase-01-foundation/`
- 架构决策: `.ai/knowledge/decisions.md`
- 路线图: `ROADMAP.md`
docs/02_测试架构/automated_test_architecture.md
+198
View File
@@ -0,0 +1,198 @@
# 自动化测试架构设计
## 目标
基于芯片手册和 Excel 寄存器表格，通过 JTAG 调试工具和串口工具，自动验证芯片实际功能是否与文档描述一致。
---
## 架构概览
```
┌────────────────────────────────────────────────────────────┐
│ 输入资源层 │
│ ┌──────────────────┐ ┌──────────────────────┐ │
│ │ Excel寄存器表格 │ │ 芯片手册/文档 │ │
│ └──────────────────┘ └──────────────────────┘ │
└────────────────────────┬───────────────────────────────────┘
│
┌────────────────────────▼───────────────────────────────────┐
│ 解析与生成层 (Arch AI) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 寄存器解析 → 寄存器定义头文件 → 测试框架代码生成 │ │
│ └─────────────────────────────────────────────────────┘ │
└────────────────────────┬───────────────────────────────────┘
│
┌────────────────────────▼───────────────────────────────────┐
│ 自动化测试层 (执行AI) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 测试固件编译 → JTAG下载 → 运行 → 串口日志收集 │ │
│ └─────────────────────────────────────────────────────┘ │
└────────────────────────┬───────────────────────────────────┘
│
┌────────────────────────▼───────────────────────────────────┐
│ 验证与报告层 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 日志解析 → 与预期结果对比 → 生成测试报告 │ │
│ └─────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────┘
```
---
## 核心组件
### 1. 寄存器解析器
- 输入：`docs/00_芯片资料/registers/*.xlsx`
- 输出：
- C 头文件 (`projects/P01_chip_test/inc/registers.h`)
- 测试描述文件 (`projects/P01_chip_test/tests/test_specs.json`)
### 2. 测试固件生成器
- 输入：测试描述文件
- 输出：
- 自动生成的测试代码 (`projects/P01_chip_test/src/auto_*.c`)
- 包含：寄存器读写测试、功能验证、串口输出
### 3. JTAG 调试工具
- 位置：`tools/jtag/`
- 功能：
- 自动编译固件
- JTAG 下载固件
- 单步调试控制
- 断点设置
### 4. 串口监控工具
- 位置：`tools/uart/`
- 功能：
- 实时监控串口输出
- 日志捕获与保存
- 日志格式解析
### 5. 结果验证器
- 输入：捕获的串口日志
- 输出：
- PASS/FAIL 结果
- 差异报告
- 统计信息
---
## 测试流程
```
┌─────────────────┐
│ 1. 解析寄存器 │
│ Excel 表格 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 2. 生成头文件 │
│ registers.h │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 3. 生成测试代码 │
│ auto_test.c │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 4. 编译固件 │
│ Arm GCC/Clang │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 5. JTAG 下载 │
│ 到芯片 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 6. 运行测试 │
│ 串口输出日志 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 7. 日志捕获 │
│ 分析结果 │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 8. 验证与报告 │
│ 生成测试报告 │
└─────────────────┘
```
---
## 测试类型
### 1. 寄存器读写测试
- 写入已知值到寄存器
- 读回寄存器值
- 验证读写一致性
### 2. 位域操作测试
- 设置特定位域
- 读取并验证位域值
- 验证复位值
### 3. 功能模块测试
- GPIO：输入输出、中断
- UART：发送接收
- Timer：定时、中断
- 其他外设
### 4. 边界条件测试
- 极端值测试
- 非法值测试
- 时序测试
---
## 串口日志格式
测试固件输出日志格式：
```
[TEST] 测试名称: 开始
[REG] 寄存器名: 写入值=0x1234, 读回值=0x1234
[PASS] 寄存器名: 读写一致
[FAIL] 寄存器名: 期望值=0x1234, 实际值=0x5678
[INFO] 附加信息
[TEST] 测试名称: 结束
```
---
## 工具链
| 工具 | 位置 | 用途 |
|------|------|------|
| parse_registers.py | shared/scripts/ | 解析 Excel 寄存器表格 |
| flash.sh | tools/jtag/ | JTAG 下载固件 |
| monitor.sh | tools/uart/ | 串口监控 |
| analyze_log.py | shared/scripts/ | 日志分析与验证 |
---
## 配置文件
### test_config.json
```json
{
"target": "Cortex-M7",
"compiler": "arm-none-eabi-gcc",
"jtag_tool": "pyocd",
"uart_port": "/dev/ttyUSB0",
"uart_baud": 115200,
"test_timeout": 30,
"retry_count": 3
}
```
docs/02_系统架构/README.md
+22
View File
@@ -0,0 +1,22 @@
# 系统架构
本目录存放系统架构设计文档。文档由 Arch AI 编写。
## 文件说明
| 文件 | 说明 | 状态 |
|------|------|------|
| 总体架构.md | 系统总体架构设计 | ✅ 完成 |
| 技术选型.md | 技术选型评估 | ✅ 完成 |
| 模块设计.md | 主要模块设计 | ✅ 完成 |
| 数据模型.md | 数据库 Schema 设计 | ✅ 完成 |
## 编写时机
架构设计文档已完成，随 PRD v0.1.0 同步交付。
## 相关链接
- 架构提示词模板: `.ai/prompts/architecture/`
- 架构决策: `.ai/knowledge/decisions.md`
- 阶段架构快照: `.ai/phases/phase-01-foundation/architecture.md`
docs/02_系统架构/总体架构.md
+246
View File
@@ -0,0 +1,246 @@
# 总体架构
> 版本: v0.4.0 | 作者: Arch AI | 基于 PRD v0.4.0 + 旧架构合并
---
## 1. 系统全景
```
┌──────────────────────┐
│ 用户层 │
│ 学生 │ 家长 │ 老师 │
└──────────┬───────────┘
│
┌────────────────────┼────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ P01 小程序 │ │ P03 Web 后台 │ │ 未来: 家长端 │
│ (Taro+React) │ │ (Next.js) │ │ 公众号/小程序 │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
└────────────────────┼────────────────────┘
│ HTTPS
▼
┌─────────────────────────────────────┐
│ API 网关层 │
│ NestJS (P01/server) │
│ Auth │ Rate Limit │ Validation │
└─────────────────┬───────────────────┘
│
┌─────────────────────┼──────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐
│ 核心服务层 │ │ AI 分析服务 │ │ 文件存储 │
│ 用户/错题/题库 │ │ 错误诊断/推荐 │ │ 图片/CDN │
└────────┬────────┘ └────────┬────────┘ └──────────┬──────────┘
│ │ │
│ ┌────────┴────────┐ │
│ │ P02 训练引擎 │ │
│ │ (Python/PyTorch)│ │
│ │ Phase 2 启动 │ │
│ └─────────────────┘ │
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ PostgreSQL │ │ S3 兼容存储 │
│ (主数据库) │ │ (图片/文件) │
└─────────────────┘ └─────────────────┘
```
## 2. 架构层级
| 层 | 技术 | 职责 |
|----|------|------|
| 展示层 | Taro 4 + React 18 / Next.js | UI 渲染、用户交互 |
| 网关层 | NestJS 中间件 | 鉴权、限流、参数校验 |
| 服务层 | NestJS Service | 业务逻辑编排 |
| AI 层 | Coze SDK → P02 PyTorch | OCR、错误诊断、推荐 |
| 数据层 | PostgreSQL + Drizzle ORM | 持久化存储 |
| 存储层 | S3 兼容存储 | 图片/文件存储 |
## 3. 数据流
### 3.1 拍照录入（P0 热路径 — 含修正闭环）
```
[小程序] 拍照/选图
│
▼
[Gateway] 鉴权 + 限流
│
▼
[File Storage] 上传原图 → 返回 URL
│
▼
[Image Pipeline] 图像预处理（提升 OCR 识别率）
├─ 透视校正（用户手动框 4 角）
├─ 增强处理（CLAHE + Gamma + 对比度增强）
└─ 笔迹去除（红/蓝笔 HSV 自动去除，黑笔可选手动圈选）
│
▼
[AI Service] 增强后图片 URL → Coze SDK
├─ OCR 提取题目文本 (confidence: 0.5-0.95)
├─ 学科分类 (confidence: 0.7-0.95)
├─ 知识点标注 (confidence: 0.5-0.9)
└─ 错误类型诊断 (confidence: 0.5-0.9)
│
▼
[Core Service]
├─ 创建 ErrorItem (verification_status = "raw")
├─ 保存 ai_confidence JSONB
└─ 返回识别结果 + 置信度 → 低置信度字段标记
│
▼
[小程序] 展示识别结果（绿/黄/红分级）
├─ 用户逐字段修正低置信度字段
├─ 每修正一个字段 → 记录 CorrectionLog
└─ 用户点击"确认"
│
▼
[Core Service]
├─ PATCH ErrorItem (verification_status = "reviewed")
├─ 修正的字段更新为用户修正值
└─ AI 原始值保留在 CorrectionLog
│
▼
[Analysis Pipeline] reviewed 状态的错题进入分析管道
```
### 3.2 练习推荐（P1）
```
[小程序] 请求推荐
│
▼
[Recommendation Service]
├─ 查询用户薄弱点 (AnalysisReport)
│ └─ 仅统计 verification_status != "raw" 的错题
├─ 粗筛：关键词 + Jaccard 相似度 → 候选集
├─ 精排：AI 语义匹配（候选集不足时）
└─ 排序 + 去重 → 返回推荐列表
```
### 3.3 错题打印/PDF 输出（P0）
```
[小程序] 在错题列表中选择
│
▼
[Print Service]
├─ 获取错题数据（结构化内容优先，无匹配时降级为增强图片）
├─ PDFKit 排版生成（A4/300DPI）
└─ 上传到 S3 → 返回临时下载链接（24h 过期）
│
▼
[小程序] 预览 → 下载 PDF → 自行打印
```
## 4. 关键设计决策
### 4.1 单体后端 → 未来拆分
MVP 阶段使用单一 NestJS 后端服务。Phase 3 按业务域拆分为微服务（用户服务、错题服务、推荐服务）。
**原因**: MVP 阶段团队 1 人，单体架构开发效率最高，NestJS 模块化设计天然支持后续拆分。
### 4.2 AI 能力分层
```
Phase 2: Coze SDK（快速上线，无需自训模型）
↓
Phase 3: P02 自训模型（针对错题领域微调，降低 API 成本）
```
**原因**: MVP 验证产品价值，用现成 AI 服务。自研模型在产品方向确认后投入。
### 4.3 题库策略
MVP 阶段接入第三方题库 API（如作业帮开放平台），Phase 3 评估是否自建题库。
### 4.4 数据质量：人机协同修正闭环
**核心问题**: AI 识别（尤其手写体 OCR）不可能 100% 准确，错误数据进入分析管道会污染飞轮。
**架构对策**:
| 层面 | 机制 | 说明 |
|------|------|------|
| 识别时 | 分字段置信度 | AI 对每个字段独立评分，低置信度高亮提示 |
| 入库时 | verification_status | `raw`(未确认) → `reviewed`(已确认) → `corrected`(已修正) |
| 分析时 | 数据质量门控 | AnalysisReport 仅统计 `reviewed` 及以上状态的错题 |
| 修正时 | CorrectionLog | 记录 AI 值 vs 用户修正值，P02 阶段用于微调模型 |
| 交互时 | 低摩擦确认 | 批量确认、置信度分级 UI 降低修正成本 |
**关键原则**: AI 是草稿，用户是编辑。用户每一次修正都是免费的标注数据。
### 4.5 数据飞轮——双通道采集
ErrLens 有两条互补的数据飞轮，共同为 P02 自研模型提供训练数据：
| 通道 | 数据来源 | 收集内容 | P02 用途 |
|------|---------|---------|----------|
| **文本侧** | CorrectionLog | AI 识别值 vs 用户修正值（知识点、学科、错误类型） | 微调 OCR/分类/诊断模型 |
| **图像侧** | 用户修正操作 | 透视校正关键点、笔迹分割标记、题目匹配反馈 | 训练图像预处理模型（透视校正、笔迹去除） |
两条飞轮共享同一个核心假设：产品设计得越好用，用户修正越自然，训练数据越丰富，模型越强——正向循环。
## 5. 部署架构（目标态）
```
┌──────────────────────────────────────────┐
│ 微信小程序平台 │
│ (代码包 < 2MB，分包加载) │
└──────────────────┬───────────────────────┘
│ HTTPS
▼
┌──────────────────────────────────────────┐
│ Nginx (HTTPS) │
│ 负载均衡 + 静态资源 │
└──────────────────┬───────────────────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ NestJS │ │ NestJS │ │ NestJS │
│ 实例 1 │ │ 实例 2 │ │ 实例 3 │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
└────────────┼────────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│PostgreSQL│ │ Redis │ │ S3/MinIO │
│ 主库 │ │ 缓存 │ │ 图片存储 │
└──────────┘ └──────────┘ └──────────┘
```
MVP 阶段用单实例部署，Nginx + 1x NestJS + 1x PostgreSQL + 1x MinIO 即可。
**三环境规划**（适配 Coze 沙盒自动化测试）:
| 环境 | 用途 | Coze 沙盒 |
|------|------|----------|
| dev | 本地开发 + AI 快速迭代 | Coze 沙盒自动运行单元/集成测试 |
| test | 灰度验证 + 真机测试 | Coze 沙盒运行完整回归测试 |
| prod | 生产环境 | 仅监控，不跑自动测试 |
灰度发布策略: test 环境验证通过 → prod 先切换 10% 流量 → 监控无异常 → 全量切换。
## 6. MVP 范围与边界
| 模块 | MVP (Phase 2) | Phase 3+ |
|------|---------------|----------|
| 小程序端 | 错题录入、列表、详情、分析、PDF 输出 | 练习推荐、报告、家长端 |
| 后端 API | REST API、鉴权、文件上传、图像预处理、打印 | GraphQL、微服务拆分 |
| AI 能力 | Coze SDK（OCR + 分类）+ 关键词粗筛 | P02 自研模型 + AI 精排 |
| 图像处理 | 透视校正 + CLAHE + 笔迹去除（红/蓝） | 黑笔自动去除、模型训练 |
| 数据库 | PostgreSQL 单库 | 读写分离、缓存层 |
| 部署 | 三环境（dev/test/prod）+ Coze 沙盒 | 容器化、CI/CD |
---
*关联: PRD.md → 模块设计.md → 数据模型.md*
docs/02_系统架构/技术选型.md
+93
View File
@@ -0,0 +1,93 @@
# 技术选型
> 版本: v0.4.0 | 作者: Arch AI | 基于 PRD v0.4.0 + 旧架构合并
---
## 1. 技术栈总览
| 层 | 选型 | 版本 | 选型理由 |
|----|------|------|----------|
| 小程序框架 | Taro | 4.1.x | 跨端能力（微信/抖音/H5），React 生态 |
| UI 框架 | React | 18.x | Hooks 生态成熟，社区资源丰富 |
| UI 组件库 | shadcn/ui (Taro 适配) | — | 可定制、无样式锁定、复制即用 |
| 样式方案 | Tailwind CSS | 4.x | 原子化 CSS，与 shadcn/ui 深度集成 |
| 状态管理 | Zustand | 5.x | 轻量、无 Provider、TS 友好 |
| 后端框架 | NestJS | 10.x | 模块化、IoC、企业级 Node.js 框架 |
| ORM | Drizzle ORM | 0.45.x | Type-safe、轻量、SQL-like API |
| 数据库 | PostgreSQL | 15+ | 关系型、JSON 支持、全文搜索 |
| AI 能力 | Coze SDK | — | 现成 OCR + NLP 能力，无需自训 |
| 文件存储 | S3 兼容 (MinIO/Supabase) | — | 图片上传，标准化接口 |
| 包管理 | pnpm | 9.x | monorepo 原生支持、磁盘效率高 |
| 图像处理 | Sharp | 0.33.x | Node.js 高性能图像处理，CLAHE/旋转/缩放 |
| PDF 生成 | PDFKit | 0.15.x | Node.js PDF 生成，A4/300DPI 排版 |
| 测试 | Jest | 29.x | 生态最大、React 测试工具链成熟 |
| 语言 | TypeScript | 5.x | 全栈类型安全 |
## 2. 关键选型决策
### 2.1 为什么是 Taro 而不是 uni-app？
| 维度 | Taro | uni-app |
|------|------|---------|
| React 支持 | 一等公民 | Vue 为主 |
| shadcn/ui | 社区已有 Taro 适配 | 无 |
| 跨端编译 | 编译时转译，性能好 | 运行时适配，有开销 |
| 社区 | 京东维护，活跃 | DCloud 维护 |
**决策**: Taro。项目已用 React + shadcn/ui 体系，Taro 天然匹配。最终仅发布微信小程序，但 Taro 保留了未来迁移 H5/原生 APP 的灵活性（后端 API 不变，只换前端壳）。
### 2.2 为什么是 NestJS 而不是 Express/Fastify？
| 维度 | NestJS | Express |
|------|--------|---------|
| 架构约束 | 模块化 + 依赖注入 | 无约束，需自建 |
| TypeScript | 一等公民 | 需额外配置 |
| 测试友好 | 内置 TestingModule | 需自建 |
| 微服务支持 | 内置 Transport 层 | 需自建 |
**决策**: NestJS。自建后端是刚性需求——Coze 沙盒自动化测试需要完整的后端环境（长连接、GPU 调用、流式响应），微信云开发（云函数 10s 超时）无法满足。同时 NestJS 模块化设计降低长期拆分微服务的迁移成本。
### 2.3 为什么是 Drizzle ORM 而不是 Prisma？
| 维度 | Drizzle | Prisma |
|------|---------|--------|
| Bundle 大小 | < 10KB | ~500KB+ (engine) |
| SQL 控制 | SQL-like API，接近原生 | 抽象层厚 |
| 边缘运行时 | 支持 | 需额外配置 |
| 迁移工具 | 内置 | 内置 |
**决策**: Drizzle。小程序场景对包体积敏感，Drizzle 更轻。且项目初期 SQL 灵活性重要。
### 2.4 AI 方案: Coze SDK vs 直接调用 API
| 维度 | Coze SDK | 直接 Claude/GPT API |
|------|----------|---------------------|
| 开发量 | 低（工作流已封装） | 高（需自建 prompt chain） |
| OCR 能力 | 内置 | 需额外组件 |
| 成本 | 按调用次数 | 按 token |
| 可定制性 | 低 | 高 |
**决策**: MVP 用 Coze SDK 快速上线，Phase 3 评估自研模型（P02）。
## 3. 暂不引入的技术
| 技术 | 原因 | 引入时机 |
|------|------|----------|
| Redis | MVP 无高频读写，PostgreSQL 足够 | Phase 3（推荐/排行榜缓存） |
| Docker/K8s | 单实例部署，先跑起来 | Phase 3（CI/CD 配套） |
| GraphQL | REST 足够，前端查询模式简单 | Phase 3（复杂查询场景） |
| Elasticsearch | PostgreSQL 全文搜索够用 | Phase 3（题库搜索量大时） |
| Kafka/RabbitMQ | 无异步解耦需求 | Phase 3（微服务拆分后） |
## 4. 技术债务记录
| 债务 | 说明 | 偿还计划 |
|------|------|----------|
| P01 项目代码是"代码检测"模板 | 需要替换为错题本业务代码 | Phase 2 开发时自然替换 |
| 无 CI/CD | 手动测试部署 | Phase 3 引入 GitHub Actions |
| 无监控 | 无 APM/日志收集 | Phase 3 引入 Sentry + 阿里云日志 |
---
*关联: 总体架构.md → 模块设计.md*
docs/02_系统架构/数据模型.md
+425
View File
@@ -0,0 +1,425 @@
# 数据模型
> 版本: v0.4.0 | 作者: Arch AI | 基于 PRD v0.4.0 + 旧架构合并
---
## 1. 实体关系图 (ER)
```
User ──< UserRelation (邀请树: inviter → invitee)
│
User ──< ErrorItem >── Subject
│ │
│ ├──< CorrectionLog (AI 值 vs 用户修正)
│ └── KnowledgePoint (多对多)
│
└──< AnalysisReport
ErrorItem >──< KnowledgePoint (error_knowledge_points)
PracticeRecommendation >──< KnowledgePoint
└──< Question (题库题目, 多对多)
Question ──< KnowledgePoint (question_knowledge_points)
Question ── Subject
```
## 2. 表定义
### 2.1 users
| 列 | 类型 | 约束 | 说明 |
|----|------|------|------|
| id | UUID | PK, DEFAULT gen_random_uuid() | 用户 ID |
| wx_openid | VARCHAR(128) | UNIQUE, NOT NULL | 微信 OpenID |
| nickname | VARCHAR(64) | | 微信昵称 |
| avatar_url | VARCHAR(512) | | 头像 URL |
| grade | VARCHAR(16) | | 年级，如"初中二年级" |
| role | VARCHAR(16) | NOT NULL, DEFAULT 'student' | 角色: student/parent/teacher/admin/super_admin (Phase 3 启用后台角色) |
| invitation_code | VARCHAR(16) | UNIQUE | 个人邀请码（6 位字母数字，注册时生成） |
| created_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | |
| updated_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | |
### 2.2 user_relations
用户邀请树结构。记录邀请链，支持树状用户群。
| 列 | 类型 | 约束 | 说明 |
|----|------|------|------|
| id | UUID | PK | |
| inviter_id | UUID | FK → users.id, NOT NULL | 邀请人 |
| invitee_id | UUID | FK → users.id, UNIQUE, NOT NULL | 被邀请人（一个用户只能被一个人邀请） |
| relation_type | VARCHAR(16) | NOT NULL, DEFAULT 'student' | student/parent/colleague |
| created_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | |
**索引**: `(inviter_id)` — 查询某用户邀请的所有人；`(invitee_id)` UNIQUE — 确保一对一邀请链
**树查询**: 通过递归 CTE 查询某用户下的完整子树（老师查看全班学生、机构查看所有老师）
```sql
-- 查询邀请人的一级下线
SELECT * FROM user_relations WHERE inviter_id = $1;
-- 递归查询完整子树（所有下级）
WITH RECURSIVE tree AS (
SELECT invitee_id, inviter_id, 1 AS depth FROM user_relations WHERE inviter_id = $1
UNION ALL
SELECT ur.invitee_id, ur.inviter_id, t.depth + 1
FROM user_relations ur JOIN tree t ON ur.inviter_id = t.invitee_id
WHERE t.depth < 10
) SELECT * FROM tree;
```
**典型结构**:
```
机构负责人 (invitation_code: ABC123)
├── 老师A (受邀)
│ ├── 学生1 (受邀)
│ └── 学生2 (受邀)
└── 老师B (受邀)
├── 学生3 (受邀)
└── 学生4 (受邀)
```
### 2.3 subjects
| 列 | 类型 | 约束 | 说明 |
|----|------|------|------|
| id | SERIAL | PK | 学科 ID |
| name | VARCHAR(32) | UNIQUE, NOT NULL | 数学/英语/语文/... |
| icon | VARCHAR(32) | | 图标标识 |
| sort_order | INT | DEFAULT 0 | 排序 |
**预置数据**: 数学、英语（首发）、语文、物理、化学、生物、地理、历史、政治（后续扩展）
### 2.4 knowledge_points
| 列 | 类型 | 约束 | 说明 |
|----|------|------|------|
| id | SERIAL | PK | 知识点 ID（内部关联用） |
| code | VARCHAR(32) | UNIQUE | 业务编码，如 `G5-MATH-0201`（跨环境稳定，API 对外暴露） |
| name | VARCHAR(128) | NOT NULL | 如"二次函数顶点式" |
| subject_id | INT | FK → subjects.id, NOT NULL | 所属学科 |
| parent_id | INT | FK → knowledge_points.id | 父级知识点（树形结构） |
| level | SMALLINT | NOT NULL, DEFAULT 1 | 层级深度 |
| sort_order | INT | DEFAULT 0 | 同级排序 |
**索引**: `(subject_id, parent_id)`, `(name)` GIN trigram（模糊搜索）
**示例数据（数学 + 英语双学科首发）**:
**编码规则**: `{Grade}-{Subject}-{Category}{Detail}`，如 `G5-MATH-0201` = 五年级·数学·02 大类·01 知识点。ID 用于内部关联，code 跨环境稳定，API 对外暴露。
```
数学 (id=1)
├── 代数 (id=10, code=G5-MATH-0100, parent=NULL)
│ ├── 一次函数 (id=101, code=G8-MATH-0101, parent=10)
│ │ ├── 斜率与截距 (id=1011, code=G8-MATH-0101-1, parent=101)
│ │ └── 一次函数应用 (id=1012, code=G8-MATH-0101-2, parent=101)
│ └── 二次函数 (id=102, code=G9-MATH-0102, parent=10)
│ ├── 顶点坐标 (id=1021, code=G9-MATH-0102-1, parent=102)
│ └── 图像性质 (id=1022, code=G9-MATH-0102-2, parent=102)
└── 几何 (id=20, code=G5-MATH-0200, parent=NULL)
├── 三角形 (id=201, code=G7-MATH-0201, parent=20)
└── 圆 (id=202, code=G9-MATH-0202, parent=20)
英语 (id=2)
├── 语法 (id=200, code=G7-ENG-0100, parent=NULL)
│ ├── 时态 (id=2001, code=G7-ENG-0101, parent=200)
│ │ ├── 一般现在时 (id=20011, code=G7-ENG-0101-1, parent=2001)
│ │ └── 现在完成时 (id=20012, code=G8-ENG-0101-2, parent=2001)
│ ├── 从句 (id=2002, code=G8-ENG-0102, parent=200)
│ │ ├── 定语从句 (id=20021, code=G9-ENG-0102-1, parent=2002)
│ │ └── 状语从句 (id=20022, code=G8-ENG-0102-2, parent=2002)
│ └── 被动语态 (id=2003, code=G8-ENG-0103, parent=200)
├── 词汇 (id=300, code=G7-ENG-0200, parent=NULL)
│ ├── 词义辨析 (id=3001, code=G7-ENG-0201, parent=300)
│ └── 固定搭配 (id=3002, code=G8-ENG-0202, parent=300)
└── 阅读 (id=400, code=G7-ENG-0300, parent=NULL)
├── 主旨大意 (id=4001, code=G7-ENG-0301, parent=400)
└── 细节理解 (id=4002, code=G7-ENG-0302, parent=400)
```
### 2.6 error_items
| 列 | 类型 | 约束 | 说明 |
|----|------|------|------|
| id | UUID | PK | 错题 ID |
| user_id | UUID | FK → users.id, NOT NULL | 所属用户 |
| subject_id | INT | FK → subjects.id | 学科 |
| image_url | VARCHAR(512) | NOT NULL | 原始图片 URL |
| thumbnail_url | VARCHAR(512) | | 缩略图 URL |
| question_text | TEXT | | AI 提取的题目文本 |
| wrong_answer | TEXT | | 错误答案 |
| correct_answer | TEXT | | 正确答案（可选） |
| error_type | VARCHAR(32) | | 错误类型 |
| difficulty | VARCHAR(8) | | 难度: basic/medium/advanced |
| verification_status | VARCHAR(16) | NOT NULL, DEFAULT 'raw' | raw/reviewed/corrected/stale |
| ai_confidence | JSONB | | AI 各字段置信度 |
| note | TEXT | | 学生备注 |
| created_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | |
| updated_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | |
**索引**: `(user_id, created_at DESC)`, `(user_id, subject_id)`, `(user_id, error_type)`, `(user_id, verification_status)`
**verification_status 枚举**:
- `raw` — AI 原始结果，用户尚未确认，不计入分析
- `reviewed` — 用户已确认（一键确认或查看后确认）
- `corrected` — 用户修正了至少一个 AI 字段
- `stale` — 30 天未确认，系统标记，可恢复为 raw
**ai_confidence JSONB 结构**:
```json
{
"question_text": 0.92,
"subject_id": 0.88,
"knowledge_points": { "1021": 0.95, "1022": 0.73 },
"error_type": 0.81,
"correct_answer": 0.55
}
```
**error_type 枚举**:
- `knowledge_gap` — 知识点欠缺
- `careless` — 粗心失误
- `misread` — 审题偏差
- `concept_confusion` — 概念混淆
### 2.7 error_knowledge_points
错题与知识点的多对多关联表。
| 列 | 类型 | 约束 | 说明 |
|----|------|------|------|
| id | SERIAL | PK | |
| error_item_id | UUID | FK → error_items.id, NOT NULL | 错题 |
| knowledge_point_id | INT | FK → knowledge_points.id, NOT NULL | 知识点 |
| relevance | SMALLINT | DEFAULT 100 | 关联度 (0-100)，主关联=100 |
**唯一约束**: `(error_item_id, knowledge_point_id)`
### 2.8 correction_logs
用户修正 AI 识别结果的记录。P02 阶段用于微调自有模型。
| 列 | 类型 | 约束 | 说明 |
|----|------|------|------|
| id | UUID | PK | |
| error_item_id | UUID | FK → error_items.id, NOT NULL | 所属错题 |
| field_name | VARCHAR(32) | NOT NULL | 修正的字段名 |
| ai_value | JSONB | NOT NULL | AI 原始值 |
| user_value | JSONB | NOT NULL | 用户修正值 |
| ai_confidence | REAL | NOT NULL | 该字段 AI 置信度 |
| corrected_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | 修正时间 |
**索引**: `(error_item_id)`, `(field_name)`（P02 阶段按字段统计 AI 薄弱项）
**示例数据**:
```json
{
"error_item_id": "uuid",
"field_name": "knowledge_points",
"ai_value": [1021],
"user_value": [1022],
"ai_confidence": 0.72,
"corrected_at": "2026-05-26T10:30:00Z"
}
```
### 2.9 analysis_reports
| 列 | 类型 | 约束 | 说明 |
|----|------|------|------|
| id | UUID | PK | 报告 ID |
| user_id | UUID | FK → users.id, NOT NULL | |
| period_start | DATE | NOT NULL | 报告周期开始 |
| period_end | DATE | NOT NULL | 报告周期结束 |
| weak_points | JSONB | NOT NULL | 薄弱点数据 |
| error_type_distribution | JSONB | NOT NULL | 错误类型分布 |
| trend | VARCHAR(8) | | up/flat/down（与上周期对比） |
| generated_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | |
**weak_points JSONB 结构**:
```json
[
{
"knowledge_point_id": 1021,
"name": "二次函数顶点坐标",
"error_count": 5,
"weight": 0.85,
"trend": "up"
}
]
```
**error_type_distribution JSONB 结构**:
```json
{
"knowledge_gap": 12,
"careless": 5,
"misread": 3,
"concept_confusion": 2
}
```
**注意**: AnalysisReport 仅统计 `verification_status != 'raw'` 的错题，确保分析基于用户确认过的数据。
### 2.10 question_bank（题库抽象层）
支持多题库源的统一抽象。自有题库（PDF 录入）和第三方题库（作业帮 API）通过统一接口接入。
**2.10.1 questions（题库题目）**
| 列 | 类型 | 约束 | 说明 |
|----|------|------|------|
| id | UUID | PK | 题目 ID |
| source | VARCHAR(16) | NOT NULL | 来源: self_built / zuoyebang / future_source |
| external_id | VARCHAR(128) | | 外部题库的原始 ID（自建为空） |
| subject_id | INT | FK → subjects.id, NOT NULL | 所属学科 |
| question_type | VARCHAR(16) | NOT NULL, DEFAULT 'choice' | 题型: choice/fill/calculation/word_problem/geometry/composite |
| question_text | TEXT | NOT NULL | 题目文本 |
| options | JSONB | | 选项（如 ABCD） |
| answer | TEXT | NOT NULL | 正确答案 |
| analysis | TEXT | | 解析 |
| difficulty | SMALLINT | DEFAULT 3 | 难度 1-5（1 基础 → 5 综合创新） |
| cognitive_level | SMALLINT | | 认知层次 1-6（布鲁姆: 记忆/理解/应用/分析/评价/创造，预留） |
| grade | VARCHAR(16) | | 适用年级 |
| variation_params | JSONB | | 变式参数（数字替换、条件变换，预留，Phase 3 启用） |
| status | VARCHAR(16) | DEFAULT 'active' | active/inactive |
| created_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | |
**索引**: `(subject_id, knowledge_point_id)`, `(source)`, `(grade)`
**2.10.2 question_knowledge_points**
题目与知识点的多对多关联（同 error_knowledge_points 模式）。
**2.10.3 pdf_import_tasks（PDF 导入任务）**
自有题库 PDF 导入的异步任务管理。
| 列 | 类型 | 约束 | 说明 |
|----|------|------|------|
| id | UUID | PK | 任务 ID |
| uploaded_by | UUID | FK → users.id, NOT NULL | 上传者 |
| file_url | VARCHAR(512) | NOT NULL | PDF 文件 URL |
| subject_id | INT | FK → subjects.id | 目标学科 |
| status | VARCHAR(16) | NOT NULL, DEFAULT 'pending' | pending/parsing/ai_extracting/review/complete/failed |
| parsed_count | INT | DEFAULT 0 | 解析出的题目数 |
| imported_count | INT | DEFAULT 0 | 成功导入的题目数 |
| error_log | JSONB | | 错误信息 |
| created_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | |
**PDF 导入管线**:
```
PDF 上传 → OCR 解析 → AI 结构化提取（题目/选项/答案/知识点）
→ 人工审核（校验解析结果） → 入库（source=self_built）
```
### 2.11 print_tasks（打印/PDF 输出任务）[P0]
| 列 | 类型 | 约束 | 说明 |
|----|------|------|------|
| id | UUID | PK | 任务 ID |
| user_id | UUID | FK → users.id, NOT NULL | 创建者 |
| error_item_ids | UUID[] | NOT NULL | 选中的错题 ID 列表 |
| output_mode | VARCHAR(8) | NOT NULL, DEFAULT 'pdf' | pdf / image |
| status | VARCHAR(16) | NOT NULL, DEFAULT 'pending' | pending/generating/complete/expired/failed |
| file_url | VARCHAR(512) | | 生成的 PDF/图片下载链接 |
| expires_at | TIMESTAMPTZ | | 下载链接过期时间（24h） |
| created_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | |
**清晰度优先级**: 结构化内容（题库匹配）> 增强图片（经图像预处理）> 原始图片
### 2.12 audit_logs（操作审计，预留 Phase 3）
Phase 3 引入完整数据主权方案时建表。字段预留: id, user_id, action, resource_type, resource_id, detail (JSONB), ip_address, created_at。
### 2.13 practice_recommendations (P1)
| 列 | 类型 | 约束 | 说明 |
|----|------|------|------|
| id | UUID | PK | 推荐记录 ID |
| user_id | UUID | FK → users.id, NOT NULL | |
| knowledge_point_ids | INT[] | NOT NULL | 目标知识点 |
| question_refs | JSONB | NOT NULL | 推荐题目引用 |
| completed | BOOLEAN | DEFAULT false | 是否完成 |
| score | SMALLINT | | 得分 |
| generated_at | TIMESTAMPTZ | NOT NULL, DEFAULT NOW() | |
## 3. Drizzle Schema 示例
```typescript
// src/server/src/db/schema.ts
import { pgTable, uuid, varchar, text, integer, smallint, date, jsonb, timestamp, boolean, uniqueIndex, index } from 'drizzle-orm/pg-core';
export const users = pgTable('users', {
id: uuid('id').defaultRandom().primaryKey(),
wxOpenid: varchar('wx_openid', { length: 128 }).unique().notNull(),
nickname: varchar('nickname', { length: 64 }),
avatarUrl: varchar('avatar_url', { length: 512 }),
grade: varchar('grade', { length: 16 }),
role: varchar('role', { length: 16 }).default('student').notNull(),
invitationCode: varchar('invitation_code', { length: 16 }).unique(),
createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(),
});
export const errorItems = pgTable('error_items', {
id: uuid('id').defaultRandom().primaryKey(),
userId: uuid('user_id').references(() => users.id).notNull(),
subjectId: integer('subject_id').references(() => subjects.id),
imageUrl: varchar('image_url', { length: 512 }).notNull(),
thumbnailUrl: varchar('thumbnail_url', { length: 512 }),
questionText: text('question_text'),
wrongAnswer: text('wrong_answer'),
correctAnswer: text('correct_answer'),
errorType: varchar('error_type', { length: 32 }),
difficulty: varchar('difficulty', { length: 8 }),
verificationStatus: varchar('verification_status', { length: 16 }).default('raw').notNull(),
aiConfidence: jsonb('ai_confidence'),
note: text('note'),
createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(),
}, (table) => ({
userIdCreatedIdx: index('idx_error_items_user_created').on(table.userId, table.createdAt.desc()),
userIdSubjectIdx: index('idx_error_items_user_subject').on(table.userId, table.subjectId),
userIdStatusIdx: index('idx_error_items_user_status').on(table.userId, table.verificationStatus),
}));
export const correctionLogs = pgTable('correction_logs', {
id: uuid('id').defaultRandom().primaryKey(),
errorItemId: uuid('error_item_id').references(() => errorItems.id).notNull(),
fieldName: varchar('field_name', { length: 32 }).notNull(),
aiValue: jsonb('ai_value').notNull(),
userValue: jsonb('user_value').notNull(),
aiConfidence: real('ai_confidence').notNull(),
correctedAt: timestamp('corrected_at', { withTimezone: true }).defaultNow().notNull(),
}, (table) => ({
errorItemIdIdx: index('idx_correction_logs_error_item').on(table.errorItemId),
fieldNameIdx: index('idx_correction_logs_field').on(table.fieldName),
}));
```
## 4. 数据量预估
| 表 | MVP 年末预估 | 增长速度 |
|----|-------------|----------|
| users | 10K | 线性（含邀请裂变） |
| user_relations | ~10K | 每用户 1 条邀请关系 |
| error_items | 500K | 每用户日均 2-3 道 |
| knowledge_points | ~5K (预置) | 版本更新追加 |
| analysis_reports | 40K | 每用户每周 1 份 |
| error_knowledge_points | 1M | 每错题 1-3 条关联 |
| correction_logs | ~200K | 每错题平均修正 0.5-1 个字段 |
| questions | 50K+ | 自有 PDF 导入 + 作业帮 API 同步 |
| question_knowledge_points | 100K | 每题 1-3 条关联 |
MVP 单表最大 500K 行，PostgreSQL 单实例完全可承载，无需分库分表。
---
*关联: 模块设计.md → 总体架构.md*
docs/02_系统架构/模块设计.md
+403
View File
@@ -0,0 +1,403 @@
# 模块设计
> 版本: v0.4.0 | 作者: Arch AI | 基于 PRD v0.4.0 + 旧架构合并
---
## 1. 模块总览
```
ErrLens
├── P01_errlens_app (小程序 + 后端)
│ ├── 小程序端 (Taro + React)
│ │ ├── pages/auth # 登录/注册
│ │ ├── pages/home # 首页（错题概览）
│ │ ├── pages/capture # 拍照录入
│ │ ├── pages/error-detail # 错题详情+分析
│ │ ├── pages/error-list # 错题列表
│ │ ├── pages/weak-points # 薄弱点分析
│ │ ├── pages/practice # 练习推荐 (P1)
│ │ ├── pages/print # PDF 输出 (P0)
│ │ └── pages/profile # 个人中心
│ │
│ └── 后端 (NestJS)
│ ├── modules/auth # 鉴权模块
│ ├── modules/user # 用户模块（含邀请链）
│ ├── modules/invitation # 邀请模块
│ ├── modules/error-item # 错题模块
│ ├── modules/ai # AI 分析模块
│ ├── modules/image # 图像预处理模块
│ ├── modules/subject # 学科模块
│ ├── modules/question-bank # 题库模块
│ ├── modules/recommend # 推荐模块 (P1)
│ ├── modules/print # 打印/PDF 输出模块 (P0)
│ └── modules/upload # 文件上传
│
├── P02_errlens_training (Phase 3)
│ └── AI 模型训练管线
│
└── P03_errlens_web (Phase 3)
└── Web 管理后台
```
## 2. 小程序页面路由
| 路由 | 页面 | 说明 | MVP |
|------|------|------|-----|
| `/pages/index/index` | 首页 | 错题统计概览 + 快捷入口 | ✅ |
| `/pages/auth/login` | 登录 | 微信授权登录 | ✅ |
| `/pages/capture/index` | 拍照录入 | 拍照 → AI 识别 → 确认 | ✅ |
| `/pages/error-list/index` | 错题列表 | 筛选 + 搜索 | ✅ |
| `/pages/error-detail/index` | 错题详情 | 题目 + AI 分析 | ✅ |
| `/pages/weak-points/index` | 薄弱点 | 知识点薄弱项汇总 | ✅ |
| `/pages/practice/index` | 练习推荐 | 智能组题 | P1 |
| `/pages/practice/result` | 练习结果 | 对错反馈 | P1 |
| `/pages/print/index` | 错题选择 | 选题→生成 PDF | ✅ |
| `/pages/print/preview` | 打印预览 | PDF 预览+下载 | ✅ |
| `/pages/profile/index` | 个人中心 | 资料 + 设置 | ✅ |
## 3. 后端模块设计
### 3.1 Auth 模块
```
modules/auth/
├── auth.module.ts
├── auth.controller.ts # POST /auth/login (微信 code → JWT)
├── auth.service.ts # 微信 code2session + JWT 签发
├── auth.guard.ts # JWT 鉴权守卫
└── dto/
└── login.dto.ts
```
**API**:
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /auth/login | 微信 code 换取 JWT token |
| POST | /auth/refresh | 刷新 token |
### 3.2 User 模块
```
modules/user/
├── user.module.ts
├── user.controller.ts # GET/PATCH /user/profile
├── user.service.ts
├── user.entity.ts # Drizzle schema
└── dto/
└── update-profile.dto.ts
```
**API**:
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /user/profile | 获取个人信息 |
| PATCH | /user/profile | 更新年级、学科 |
| GET | /user/invitation-code | 获取个人邀请码和二维码 |
| GET | /user/tree | 获取邀请树（直接下级列表） |
### 3.3 Invitation 模块
```
modules/invitation/
├── invitation.module.ts
├── invitation.controller.ts # POST /invitation/register
├── invitation.service.ts # 邀请码生成 + 邀请链管理
├── user-relation.entity.ts # Drizzle schema
└── dto/
├── register-by-invite.dto.ts
└── tree-query.dto.ts
```
**API**:
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /invitation/register | 通过邀请码注册（携带 inviter_code） |
| GET | /invitation/tree | 获取当前用户的邀请树（一级+递归） |
| GET | /invitation/tree/:userId | 获取指定用户的邀请统计（子节点数、活跃用户数） |
**邀请码生成规则**:
- 用户注册时自动生成 6 位字母数字邀请码
- 格式: `[A-Z0-9]{6}`，排除易混淆字符 (0/O, 1/I/L)
- 唯一约束，冲突时重试生成
**注册流程**:
```
1. 老用户 A 分享小程序 → 携带邀请码参数 (pages/auth/login?invite=ABC123)
2. 新用户 B 打开 → 微信授权登录
3. 后端创建 B 用户 → 生成 B 的邀请码
4. 创建 user_relation (inviter=A, invitee=B)
5. B 进入首页 → 关系建立完成
```
### 3.4 ErrorItem 模块（核心）
```
modules/error-item/
├── error-item.module.ts
├── error-item.controller.ts # CRUD /error-items
├── error-item.service.ts # 错题业务逻辑 + 校验状态管理
├── error-item.entity.ts # Drizzle schema
├── correction-log.service.ts # 修正记录管理
└── dto/
├── create-error.dto.ts
├── update-error.dto.ts
├── query-error.dto.ts # 筛选参数（含 verification_status）
└── batch-confirm.dto.ts # 批量确认
```
**API**:
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /error-items | 创建错题（AI 识别结果，状态=raw） |
| GET | /error-items | 列表查询（分页+筛选，含 verification_status 筛选） |
| GET | /error-items/:id | 错题详情（含 AI 分析 + 置信度） |
| PATCH | /error-items/:id | 修正错题信息（字段修正时记录 CorrectionLog） |
| POST | /error-items/batch-confirm | 批量确认（raw → reviewed） |
| DELETE | /error-items/:id | 删除错题 |
**校验状态机**:
```
raw → (用户查看+确认) → reviewed → (用户修正字段) → corrected
↓
stale (30天未确认，系统标记，可恢复为 raw)
```
**AnalysisReport 数据过滤**: 查询时加 `WHERE verification_status != 'raw'`，确保分析只使用已确认数据。
### 3.5 AI 模块
```
modules/ai/
├── ai.module.ts
├── ai.controller.ts # POST /ai/analyze
├── ai.service.ts # Coze SDK 调用封装
├── strategies/
│ ├── ocr.strategy.ts # OCR 识别策略
│ ├── classify.strategy.ts # 学科/知识点分类策略
│ └── diagnose.strategy.ts # 错误原因诊断策略
└── dto/
├── analyze-request.dto.ts
└── analyze-response.dto.ts
```
**API**:
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /ai/analyze | 分析错题图片 → 返回结构化结果 |
| GET | /ai/report | 获取薄弱点分析报告 |
**AI 分析流程**:
```
图片 URL → OCR 文字提取 ──→ question_text (confidence: 0.5-0.95)
├─ 学科分类 ──────────→ subject_id (confidence: 0.7-0.95)
├─ 知识点标注 ────────→ knowledge_points[] (confidence 各 0.5-0.9)
├─ 题目结构提取 ──────→ wrong_answer/correct_answer (confidence 各 0.5-0.9)
└─ 错误原因诊断 ──────→ error_type + diagnosis (confidence: 0.5-0.9)
→ 每个字段附带 confidence 分数
→ 低置信(<0.7)字段标记 requires_review=true，前端红色高亮
→ 汇总返回 { result, confidences, requires_review_fields[] }
```
### 3.6 Image 模块（图像预处理）
```
modules/image/
├── image.module.ts
├── image.service.ts # 图像预处理编排
├── pipelines/
│ ├── perspective.service.ts # 透视校正（手动框 4 角）
│ ├── enhance.service.ts # CLAHE + Gamma + 对比度增强
│ └── pen-removal.service.ts # 笔迹去除（红/蓝 HSV 自动，黑笔手动圈选）
├── sharp.config.ts # Sharp 图像处理参数配置
└── dto/
└── preprocess.dto.ts
```
**处理管线**:
```
原始图片 → 透视校正 → CLAHE 增强 → 笔迹去除 → 输出增强图片 URL
↓ ↓ ↓ ↓
原图保留 手动框角 光照归一化 红/蓝自动去除
黑笔可选手动圈选
```
**降级策略**: 任何模块失败不阻塞整体流程。校正失败 → 用原图；增强失败 → 跳过增强；笔迹去除失败 → 保留原图。始终保证图片能进入 AI 识别。
**Spike 验证结论**（来自旧架构，Coze 沙盒中重新调优）:
- 自动透视校正不可用（整页裁成碎片），以手动框 4 角为主方案
- CLAHE 增强 10/10 达到清晰度标准
- 红笔批改可靠去除、蓝笔可用、黑笔无法自动去除（需用户圈选）
### 3.8 Subject 模块
```
modules/subject/
├── subject.module.ts
├── subject.controller.ts # GET /subjects
├── subject.service.ts
└── subject.entity.ts
```
**API**:
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /subjects | 获取学科列表 |
| GET | /subjects/:id/knowledge-points | 获取学科下知识点树 |
### 3.7 Print 模块（PDF 输出）[P0]
```
modules/print/
├── print.module.ts
├── print.controller.ts # POST /print/generate, GET /print/download/:id
├── print.service.ts # PDF 生成 + S3 存储 + 过期清理
├── pdf-layout.service.ts # PDFKit A4/300DPI 排版
└── dto/
├── generate-print.dto.ts
└── print-task.dto.ts
```
**API**:
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /print/generate | 提交错题 ID 列表，生成 PDF 任务 |
| GET | /print/task/:id | 查询生成进度 |
| GET | /print/download/:id | 下载 PDF 文件（24h 有效） |
**排版优先级**: 题库匹配的结构化内容 > 经图像预处理的增强图片 > 原始图片
**清理策略**: 定时任务每天清理 expires_at < NOW() 的临时文件。
### 3.9 Upload 模块
```
modules/upload/
├── upload.module.ts
├── upload.controller.ts # POST /upload/image
├── upload.service.ts # S3 上传 + 缩略图
└── upload.config.ts # S3/MinIO 配置
```
**API**:
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /upload/image | 上传图片 → 返回 URL |
### 3.10 Recommend 模块 (P1)
```
modules/recommend/
├── recommend.module.ts
├── recommend.controller.ts # GET /recommend
├── recommend.service.ts # 推荐编排
└── strategies/
├── coarse-recall.strategy.ts # 粗筛：关键词搜索 + Jaccard 相似度（本地，免费）
├── ai-rerank.strategy.ts # 精排：AI 语义匹配（候选集不足时启用，付费）
├── weak-point.strategy.ts # 薄弱点权重排序
└── similar-difficulty.strategy.ts # 难度匹配
```
**两阶段推荐策略**:
1. **粗筛**（关键词 + Jaccard 相似度）→ 快速召回候选集，零成本、低延迟
2. **精排**（AI 语义匹配）→ 候选集为空或不满足阈值时启用，语义理解泛化
3. 排序: 薄弱点权重 > 难度匹配度 > 去重（已做过的不推）
### 3.11 QuestionBank 模块（题库抽象层）
```
modules/question-bank/
├── question-bank.module.ts
├── question-bank.controller.ts # CRUD /questions
├── question-bank.service.ts # 多源题库路由
├── adapters/
│ ├── base-adapter.ts # 题库适配器接口
│ ├── self-built.adapter.ts # 自有题库适配器
│ ├── zuoyebang.adapter.ts # 作业帮 API 适配器
│ └── adapter.factory.ts # 按 source 路由到对应适配器
├── pdf-import/
│ ├── pdf-parser.service.ts # PDF → 文本
│ ├── ai-extractor.service.ts # AI 结构化提取题目
│ └── import-review.service.ts # 人工审核流程
└── dto/
├── create-question.dto.ts
├── query-question.dto.ts
└── pdf-import.dto.ts
```
**API**:
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /questions | 题目列表查询（分页+筛选） |
| GET | /questions/:id | 题目详情 |
| POST | /questions | 手动创建题目（自有题库录入） |
| POST | /questions/search | 跨源搜索（自有 + 作业帮，结果合并） |
| POST | /questions/pdf-import | 上传 PDF 启动导入任务 |
| GET | /questions/pdf-import/:taskId | 查询 PDF 导入进度 |
**适配器接口**:
```typescript
interface QuestionBankAdapter {
source: string;
search(params: SearchParams): Promise<Question[]>;
getById(id: string): Promise<Question>;
healthCheck(): Promise<boolean>;
}
```
**题库路由策略**: 请求时并行查询自有题库 + 作业帮 API，合并去重后返回。自有题库优先排序。
## 4. 前端状态管理 (Zustand)
```
stores/
├── auth.store.ts # 登录态、token、用户信息
├── error-item.store.ts # 错题列表、筛选条件、分页
├── capture.store.ts # 拍照流程状态机
└── ai-analysis.store.ts # AI 分析结果缓存
```
**capture 状态机**:
```
IDLE → CAMERA → PREVIEW → UPLOADING → ANALYZING → REVIEW → SAVING → DONE
↓ ↓ ↓
ERROR ERROR ERROR
```
## 5. MVP 开发顺序
```
Phase 2a (Week 1-2): 基础设施
- 数据库 Schema + 迁移
- Auth 模块（微信登录）
- User 模块
- Image 模块（图像预处理管线）
Phase 2b (Week 3-4): 核心闭环
- Upload 模块
- AI 模块（Coze SDK 集成）
- ErrorItem CRUD
- 拍照录入页 + 错题列表页
Phase 2c (Week 5-6): 分析+打印+打磨
- 错题详情 + AI 分析展示
- 薄弱点汇总
- Print 模块（PDF 输出）
- Subject 模块 + 筛选
- 交互打磨、异常处理
```
---
*关联: 总体架构.md → 技术选型.md → 数据模型.md*
docs/03_开发规范/README.md
+17
View File
@@ -0,0 +1,17 @@
# 开发规范
本目录存放项目开发规范文档。
## 文件说明
| 文件 | 说明 | 状态 |
|------|------|------|
| 编码规范.md | 代码风格和命名规范 | 已有 `.ai/prompts/coding/code-style.md` |
| 提交规范.md | Git 提交信息规范 | 已有 `AGENTS.md` 提交信息部分 |
| 文档规范.md | 文档编写规范 | 待编写 |
## 相关链接
- AI 代码规范: `.ai/prompts/coding/code-style.md`
- 文档模板: `.ai/prompts/coding/doc-template.md`
- 信息架构原则: `.ai/principles.md`
docs/04_部署运维/README.md
+20
View File
@@ -0,0 +1,20 @@
# 部署运维
本目录存放部署和运维相关文档。
## 文件说明
| 文件 | 说明 | 状态 |
|------|------|------|
| 部署架构.md | 部署拓扑和环境说明 | 待编写 |
| CI_CD.md | 持续集成/持续部署配置 | 待编写 |
| 运维手册.md | 日常运维操作手册 | 待编写 |
## 编写时机
Phase 2 MVP 有可部署产物后开始编写。
## 相关链接
- 环境配置: `ENVIRONMENT.md`
- 各子项目环境: `projects/P0X_*/ENVIRONMENT.md`
docs/05_变更日志/2026-05-23.md
+38
View File
@@ -66,6 +66,44 @@
需求分析(Arch AI) → 架构设计(Arch AI) → 开发实现(Dev AI) → 测试验证(QA AI) → 验收确认(人类)
```
**docs(readme): 补充 README.md 和变更日志 - 同步 Arch AI 升级** (`c31ab66`)
- README.md: 更新为"1 人+3AI"协作模式，目录结构、团队角色、工作流程全面更新
- AGENTS.md: AI 配置文件说明增加 architect.json 和 architecture/ 提示词
- docs/05_变更日志/2026-05-23.md: 补充今天所有提交的变更记录
**feat(skill): 新增 update-constitution 和 update-docs 两个 Skill** (`62d908c`)
- update-constitution: 更新宪法文件（AGENTS.md、配置文件、权限矩阵）
- update-docs: 更新项目文档（README.md、变更日志、PROJECT_CONTEXT.md）
- 解决痛点：核心代码改了，文档和变更日志容易忘
**feat(skill): 新增 git Skill - 封装常用 git 操作** (`75312d7`)
- 将 status/add/commit/push/pull/branch/log/diff/stash/reset 封装为参数化动作
- 规范提交信息格式（type(scope): subject）
- 控制提交频率，按功能/任务粒度提交
**feat(skill): 新增 switch-model Skill - 大模型切换时快速同步上下文** (`5cba5c2`)
- 必须指定角色（架构/开发/测试），不同角色检查不同内容
- 简洁版检查报告，控制在 1 屏内
- 加载对应角色配置、活跃任务、可用 Skill 列表、环境配置
**fix(switch-model): 调整执行顺序，git 安全检查优先** (`b3fbe33`)
- 将 git status/log/branch 移到上下文加载之前
- 增加异常处理：未提交变更/合并冲突/分支错误/远程更新
- 版本升至 v1.1
**feat(skill): 新增 7 个 Skill 工具** (`75312d7` ~ `b3fbe33`)
- ai-collab-setup: 创建协作框架
- add-subproject: 添加子项目
- resume-context: 换电脑时同步上下文
- switch-model: 换大模型时同步上下文
- update-constitution: 更新宪法文件
- update-docs: 更新项目文档
- git: 封装 git 操作
**fix(constitution): 修复 tester.json 权限冲突** (`当前提交`)
- review/*/acceptance.md 从 read_only 移除，保留 allowed（QA AI 可补充验收标准）
- review/*/feedback/ 从 forbidden 移除，保留 allowed（QA AI 可提交反馈）
---
## 模板
docs/05_变更日志/2026-05-25.md
+37
View File
@@ -0,0 +1,37 @@
# 2026-05-25 — 信息架构重构
## 概述
将项目信息架构从"人类导向单体文档"重构为"AI 优先分层架构"。
## 新增
- `.ai/roles/` — AI 角色工作台（Arch/Dev/QA 各含 card + today + queue）
- `.ai/phases/` — 阶段上下文（Phase 1-4，含 goal/scope/architecture/decisions/completion）
- `.ai/knowledge/` — 知识沉淀（decisions、patterns、lessons、journal）
- `.ai/prompts/architecture/` — 架构提示词模板（architecture-design、technical-evaluation）
- `.ai/principles.md` — 信息架构设计原则
- `ROADMAP.md` — 项目路线图看板（根目录）
- `DASHBOARD.md` — 人类仪表盘（根目录）
- `docs/share/` — 对外分享内容层
- `review/active/INDEX.md` — 活跃任务索引
- `docs/01-04/README.md` — 各文档目录说明
## 修改
- `AGENTS.md` — 压缩至 ~120 行，顶部添加 AI 角色工作台跳转
- `README.md` — 精简，聚焦人类读者，加入 DASHBOARD/ROADMAP/share 链接
- `docs/PROJECT_CONTEXT.md` — 精简，添加分层架构说明和跳转
- `docs/DECISIONS.md` — 替换为跳转存根（内容迁移至 .ai/knowledge/decisions.md）
- `review/active/*/task.md` — 5 个任务均添加 `阶段: Phase 1` 字段
## 决策
- ADR-007: 分层信息架构 + Token 预算制度
- D-001: 信息架构分层设计
- D-002: 阶段化上下文加载
- D-003: 角色工作台代替全局入口
## 维护者
Arch AI
docs/DECISIONS.md
+2 -151
View File
@@ -1,154 +1,5 @@
# 架构决策记录 (ADR)
## 什么是 ADR？
ADR 已迁移至 [.ai/knowledge/decisions.md](../.ai/knowledge/decisions.md)。
ADR（Architecture Decision Record）记录项目中重要的架构决策及其原因。当新成员（或 AI）加入时，可以通过 ADR 快速理解"为什么这么做"。
## 决策记录
### ADR-001: 采用"1 人 + 2AI"协作框架
**日期**: 2026-05-23
**状态**: 已采纳
**决策者**: 人类负责人
**背景**:
项目需要高效开发，但团队只有 1 人。利用 AI 辅助编程可以大幅提升效率。
**决策**:
采用 1 个负责人 + 2 个 AI（Dev AI 编码 + QA AI 测试）的协作模式。
**后果**:
- ✅ 开发效率大幅提升
- ✅ 代码质量有保障（独立测试 AI）
- ⚠️ 需要维护权限体系和协作流程
- ⚠️ 人类需要审阅 AI 输出
---
### ADR-002: 采用 R/W/RW/- 四态权限体系
**日期**: 2026-05-23
**状态**: 已采纳
**决策者**: 人类负责人
**背景**:
初始框架使用简单的 allowed/forbidden 二元权限，无法满足"只读"场景。
**决策**:
采用四态权限：`-`（无权）、`R`（只读）、`W`（可写）、`RW`（读写）。
**后果**:
- ✅ 更细粒度的权限控制
- ✅ 明确只读路径（如 task.md、feedback/）
- ⚠️ 权限矩阵更复杂，需要维护
---
### ADR-003: 项目级文档放在根目录 docs/
**日期**: 2026-05-23
**状态**: 已采纳
**决策者**: 人类负责人
**背景**:
项目级文档（产品需求、架构设计等）不属于任何子项目，需要独立存放。
**决策**:
在根目录创建 `docs/` 目录，而非 `projects/P00_DOCS/`。
**后果**:
- ✅ 语义清晰，业界标准
- ✅ 路径简短
- ⚠️ 需要在权限矩阵中单独定义
---
### ADR-004: 新增 tools/ 和 data/ 目录
**日期**: 2026-05-23
**状态**: 已采纳
**决策者**: 人类负责人
**背景**:
开发工具脚本和训练数据需要独立管理，不应混入项目代码。
**决策**:
在根目录创建 `tools/`（开发工具）和 `data/`（训练数据）。
**权限**:
- `tools/`: Dev AI 可写，QA AI 禁止
- `data/`: Dev AI 可写，QA AI 只读
**后果**:
- ✅ 职责分离，便于管理
- ✅ 训练数据独立于代码
- ⚠️ 需要维护数据版本
---
### ADR-005: 工作流增加 retry 和 escalation 机制
**日期**: 2026-05-23
**状态**: 已采纳
**决策者**: 人类负责人
**背景**:
线性工作流无法处理测试失败的情况。
**决策**:
- 增加 retry 机制：最多 3 轮测试修复循环
- 增加 escalation 机制：第 3 轮仍有 BLOCKER/HIGH 时升级给人类
**后果**:
- ✅ 自动处理常见 Bug 修复
- ✅ 严重问题及时升级
- ⚠️ 需要维护修复轮次计数
---
### ADR-006: 创建 resume-context Skill 解决多电脑同步
**日期**: 2026-05-23
**状态**: 已采纳
**决策者**: 人类负责人
**背景**:
用户在家和单位两台电脑间切换，需要快速恢复开发上下文。
**决策**:
- 创建 `resume-context` Skill
- 创建 `docs/PROJECT_CONTEXT.md` 项目上下文
- 创建 `docs/06_开发日志/` 按日期记录讨论
**后果**:
- ✅ 换电脑后快速恢复上下文
- ✅ 新 AI 对话可以读取背景
- ⚠️ 需要维护文档更新
---
## 决策模板
```markdown
### ADR-XXX: 决策标题
**日期**: YYYY-MM-DD
**状态**: 考虑中 / 已采纳 / 已废弃
**决策者**: XXX
**背景**:
[为什么需要做这个决策]
**决策**:
[具体决定是什么]
**后果**:
- ✅ 好处
- ⚠️ 需要注意的点
```
---
**最后更新**: 2026-05-23
**维护者**: 人类负责人 + Dev AI
该文件包含全部 7 条 ADR（含 ADR-007: 分层信息架构 + Token 预算）。
docs/PROJECT_CONTEXT.md
+35 -96
View File
@@ -1,113 +1,52 @@
# 项目上下文 - ErrLens 错题本
# 项目上下文
## 项目愿景
## 项目概述
打造跨平台的学生错题本应用，配套 Web 管理后台和数据训练算法，形成"数据采集 → AI 分析 → 个性化推荐"的数据飞轮。
ErrLens 是一个学生错题本应用。核心概念是"数据飞轮"：收集错题 → AI 分析 → 个性化推荐。
包含三个子项目：
- **P01_errlens_app** — 跨平台小程序（Taro + React + NestJS）
- **P02_errlens_training** — AI 训练算法（Python + PyTorch）
- **P03_errlens_web** — Web 管理后台（Next.js）
## 当前阶段
**框架搭建阶段**（2026-05-23 完成）
Phase 1: 基础搭建。完成协作框架和项目脚手架。
已完成：
- ✅ "1 人 + 2AI（Dev AI + QA AI）"协作框架
- ✅ 完整目录结构和权限体系（R/W/RW/- 四态）
- ✅ AI 配置文件（coder.json、tester.json、workflow.json）
- ✅ 提示词模板（code-style.md、doc-template.md、bug-report.md）
- ✅ Skill 工具（ai-collab-setup、add-subproject、resume-context）
- ✅ 项目级文档目录（docs/、tools/、data/）
待启动：
- ⏳ P01_errlens_app 小程序开发
- ⏳ P02_errlens_training 数据训练算法
- ⏳ P03_errlens_web Web 管理后台
→ 当前进度和任务看板：[ROADMAP.md](../ROADMAP.md)
→ 人类视角仪表盘：[DASHBOARD.md](../DASHBOARD.md)
## 技术栈
| 层级 | 技术选型 | 说明 |
|------|---------|------|
| 小程序 | Taro + React + TypeScript | 跨平台（微信优先，预留支付宝/抖音） |
| Web 管理 | Next.js + React + TypeScript | SSR，便于 SEO 和性能 |
| 后端 | NestJS + TypeScript | 统一语言，便于维护 |
| 数据库 | PostgreSQL | 关系型数据，支持复杂查询 |
| AI 训练 | Python + PyTorch | 错题分析和推荐算法 |
| 包管理 | pnpm | 快速、节省磁盘空间 |
| 协作框架 | 1 人 + 2AI | Dev AI（编码）+ QA AI（测试） |
| 层 | 技术 |
|----|------|
| 前端 (P01) | Taro 4 + React 18 + TypeScript + Tailwind CSS |
| 后端 (P01) | NestJS 10 + TypeScript |
| 数据库 | PostgreSQL |
| Web (P03) | Next.js（Phase 2 启动） |
| AI (P02) | Python + PyTorch（Phase 2 启动） |
| 包管理 | pnpm monorepo |
| 测试 | Jest |
## 团队架构
## 团队
```
人类负责人（唯一决策者）
├── Dev AI（编码 AI）- 编写代码、文档、影响评估
└── QA AI（测试 AI）- 编写测试、执行测试、质量保障
```
"1 人类 + 3 AI" 协作模式。详见 [AGENTS.md](../AGENTS.md)。
详细权限见 [AGENTS.md](../AGENTS.md)
## 信息架构
## 关键决策
项目采用分层信息架构，针对 AI 上下文窗口优化：
- AI 入口：`.ai/roles/{role}/card.md` + `today.md`（< 2K tokens）
- 阶段上下文：`.ai/phases/phase-NN/`（< 5K tokens）
- 知识沉淀：`.ai/knowledge/`（自动积累）
- 设计原则：`.ai/principles.md`
| 决策 | 原因 | 日期 |
|------|------|------|
| 采用 R/W/RW/- 四态权限体系 | 比二元权限更灵活，明确只读路径 | 2026-05-23 |
| 项目级文档放在根目录 docs/ | 不属于任何子项目，业界标准做法 | 2026-05-23 |
| 新增 tools/ 和 data/ 目录 | 开发工具和训练数据需要独立管理 | 2026-05-23 |
| 创建 resume-context Skill | 解决多电脑切换时的上下文同步问题 | 2026-05-23 |
| 工作流增加 retry 机制 | 允许最多 3 轮测试修复循环 | 2026-05-23 |
| 工作流增加 escalation 机制 | 第 3 轮仍有严重 Bug 时升级给人类 | 2026-05-23 |
## 架构决策
## 待解决问题
→ [.ai/knowledge/decisions.md](../.ai/knowledge/decisions.md)
1. **Web 管理后台具体功能** - 尚未确定，需要简化设计，保持可扩展性
2. **数据来源** - 用户有一些数据但不够，需要数据飞轮思维
3. **跨平台优先级** - 目前主要是微信，但框架上要考虑跨平台
4. **AI 训练算法细节** - 错题分析和推荐算法的具体实现方案
## 关键待办
## 下一步计划
1. [ ] 完成产品需求文档（PRD）
2. [ ] 完成系统架构设计
3. [ ] 启动 P01_errlens_app 小程序开发
4. [ ] 设计数据采集方案
5. [ ] 规划 Web 管理后台功能
## 项目结构
```
errlens/
├── docs/ # 项目级总体文档
│ ├── 01_产品需求/
│ ├── 02_系统架构/
│ ├── 03_开发规范/
│ ├── 04_部署运维/
│ ├── 05_变更日志/
│ │ └── archived/ # 历史变更日志（按年月归档）
│ └── 06_开发日志/
├── tools/ # 开发工具脚本
├── data/ # 训练数据
├── projects/ # 子项目
│ ├── P01_errlens_app/ # 错题本小程序
│ ├── P02_errlens_training/# 数据训练算法
│ └── P03_errlens_web/ # Web 管理后台
├── review/ # 任务交接中心
├── reports/ # 测试/质量报告
├── shared/ # 共享资源
└── .ai/ # AI 协作配置
```
## 开发环境
- **操作系统**: Windows / macOS / Linux（跨平台开发）
- **IDE**: Trae CN
- **Node.js**: >= 20.x
- **包管理器**: pnpm >= 9.0.0
- **Python**: >= 3.10（AI 训练）
## 同步机制
- **代码同步**: Git（远程仓库：GitCode）
- **上下文同步**: `docs/PROJECT_CONTEXT.md` + `docs/06_开发日志/`
- **恢复上下文**: 使用 `resume-context` Skill
---
**最后更新**: 2026-05-23
**维护者**: 人类负责人 + Dev AI
- [ ] 编写错题本 PRD
- [ ] 设计系统架构文档
- [ ] 将 P01 文档从"代码检测"改写为"错题本"
- [ ] 启动 P03 Web 项目初始化
docs/share/00_项目缘起.md
+82
View File
@@ -0,0 +1,82 @@
# 项目缘起：为什么我要做一个 AI 错题本
> 一个不会写代码的产品经理，用 AI 从零开发一个 App 的全记录。
---
## 起点：一个做了很多年的梦
我一直在做教育相关的事情。
这么多年来，我见过太多学生被同一个问题困扰：**错题整理太痛苦了**。手抄错题、自己分类、凭感觉复习——每一步都在消耗学生的耐心。而传统错题本 App 呢？拍照 OCR 识别率低、分类粗糙、推荐随机。用一个学生的话说：「花了半小时录入，得到的分析和我自己翻两页书差不多。」
我想做一个真正有用的错题本。但问题是：**我不会写代码。**
过去这个想法就只能停留在想法。直到 AI 编程工具出现了。
---
## 核心问题：AI 能写代码，但能做一个完整的产品吗？
2025 年底开始，AI 编程工具层出不穷。Cursor、Copilot、Claude Code——它们能帮你写函数、修 bug、甚至生成整个页面。
但我有一个更大的问题：**一个不会写代码的人，能不能靠 AI 从零做出一个能上线的产品？**
这不仅是写几段代码的问题，而是：
- 产品需求谁定？
- 架构设计谁做？
- 多个 AI 之间怎么分工？
- AI 写的代码质量怎么保证？
- 遇到 AI 解决不了的 bug 怎么办？
我决定用自己当实验品，把这个过程完整记录下来。
---
## 为什么选错题本
除了个人情结，还有一个技术判断：
**错题本是 AI 编程能力的最佳试金石。**
它需要：
- 前端（小程序 UI）——考验 AI 的 UI 还原能力
- 后端（API + 数据库）——考验 AI 的架构能力
- AI 集成（OCR + 分类 + 推荐）——考验 AI 调用 AI 的能力
- 图像处理（拍照增强 + 笔迹去除）——考验 AI 的算法能力
- 数据闭环（用户修正 → 反哺训练）——考验 AI 的系统设计能力
能把这个项目做出来，基本上什么类型的 AI 编程任务都能覆盖了。
---
## 1 人 + 3 AI：我的协作模式
我给自己设计了一套「AI 团队」：
| 角色 | 做什么 | 权限 |
|------|--------|------|
| **Arch AI**（Claude） | 架构设计、PRD、技术选型、决策记录 | 读写文档 |
| **Dev AI**（Claude + Coze） | 写代码、数据库、API、前端页面 | 读写代码 |
| **QA AI**（Coze 沙盒） | 自动化测试、回归验证 | 只读代码 |
所有 AI 都听我指挥。我只负责三件事：**做决策、验结果、写分享。**
这套模式的核心思想是：人类决定「做什么」和「为什么」，AI 负责「怎么做」。
---
## 这个系列会记录什么
1. **产品从零到一**：PRD 怎么写、架构怎么设计、决策怎么做
2. **AI 协作的真实体验**：AI 什么时候好用、什么时候翻车、怎么让 AI 配合工作
3. **技术选型的思考**：为什么选这个不选那个，每一个选择背后的权衡
4. **踩过的坑**：AI 写的代码跑了但不对、架构设计推翻重来、旧方案合并的痛苦
5. **数据和思考**：每个阶段的交付物、决策记录、经验教训
这不是一个「AI 太强了帮我做了一切」的爽文。这是一个真实的、有成功有失败、有纠结有突破的开发记录。
---
*下一篇：[框架设计思路](01_框架设计思路.md) — 为什么传统的项目文档结构对 AI 不友好*
docs/share/01_框架设计思路.md
+106
View File
@@ -0,0 +1,106 @@
# 框架设计思路：当文档的读者不是人类
> 传统项目结构对 AI 不友好——我的信息架构是怎么一步步推到重来的。
---
## 问题的起点：AI 看不懂我的项目
第一次用 Claude Code 时，我兴奋地让它帮我写个功能。结果它盯着我的项目看了半天，然后开始瞎写。
问题不在 AI，在我的项目文档。
一个典型的人类项目文档是这样的：一个巨大的 README.md，里面塞了项目介绍、架构设计、API 文档、部署说明、开发规范……人类会跳着读，挑自己需要的部分。但 AI 不会跳读——它会从头到尾读完，然后在第 5000 行开始「记忆衰减」。
更致命的是：**不同 AI 角色需要的信息完全不同。** Dev AI 需要知道数据库表结构，不需要知道为什么 ADR-007 选了分层架构。但你把这些全混在一个文件里，AI 就只能全部消化。
结论：**为人类设计的文档结构，不适合 AI 协作。**
---
## 第一次尝试：从 README 到 AGENTS.md
我先学着社区的做法，把所有 AI 需要的信息写进一个 `AGENTS.md`。
一开始还行。但越写越长。PRD、架构、技术栈、目录结构、权限矩阵、ADR、Skill 定义……写到 2000 行的时候，AI 开始「忘记」前面的内容。
问题出在 **token 预算**。Claude 的上下文窗口约 200K token，看起来很大，但要同时装下 AGENTS.md + 当前代码文件 + 对话历史 + 输出内容，200K 很快就满了。
而且还有一个更隐蔽的问题：**不该看的东西 AI 也看了。** Dev AI 不需要知道 QA AI 的工作流，Arch AI 不需要知道具体代码实现。把不属于它的信息喂给它，既浪费 token，又容易干扰判断。
---
## 第二次重构：分层信息架构
关键洞察来自一个简单问题：**人类团队怎么分工？**
一个有 3 个人的团队，不会把所有信息贴在一面墙上让每个人读完。而是每人有自己的工作台，只看和自己相关的内容。跨角色共享的信息放在公共区域。
把这个逻辑搬到 AI 协作上：
```
┌─────────────────────────────────────────┐
│ DASHBOARD.md │ ← 人类视角，30 秒了解全貌
├─────────────────────────────────────────┤
│ ROADMAP.md │ ← 人+AI 共享视野，任务看板
├────────────────┬────────────┬───────────┤
│ .ai/roles/ │ .ai/roles/ │ .ai/roles/ │
│ arch/ ← Arch │ dev/ ← Dev │ qa/ ← QA │ ← 每人自己的工作台
│ 今天干啥 │ 今天干啥 │ 今天干啥 │
│ 任务队列 │ 任务队列 │ 测试计划 │
├────────────────┴────────────┴───────────┤
│ .ai/knowledge/ │ ← 共享知识库
│ decisions.md（ADR） │
│ journal/（开发日志） │
├──────────────────────────────────────────┤
│ docs/ │ ← 项目文档
│ 01_产品需求/PRD.md │
│ 02_系统架构/ │
└──────────────────────────────────────────┘
```
四层结构，每层有明确的 token 预算：
| 层 | 读者 | 内容 | token 预算 |
|----|------|------|-----------|
| 仪表盘 | 人类 | 30 秒全貌 | < 1K |
| 路线图 | 人+AI | 任务看板 | < 3K |
| 角色工作台 | 单个 AI | 今天干啥、任务详情 | < 2K |
| 知识沉淀 | 所有 AI | ADR、经验教训 | 按需加载 |
**核心原则：每个 AI 启动时只加载自己那层的信息，不需要的永远不看。**
---
## Token 预算：把「省着用」变成设计原则
很多人觉得 token 窗口够大就不用省。但我的体验是：**省 token 不是为了省，是为了让 AI 注意力集中。**
给你一组对照实验：
```
方案 A：把所有文档塞进 context → AI 的回复质量不稳定，后面的任务比前面的差
方案 B：只给当前任务相关的文档 → AI 的回复质量和速度都明显更好
```
原因很简单：AI 的注意力也是有限的。信息越多，它在噪音中找信号的难度越大。
分层架构的本质，就是**在正确的时刻，给正确的 AI，提供正确的信息量。**
---
## 「一鸡多吃」：分享层是怎么来的
架构稳定后，我发现一个有趣的事：我做的所有决策记录、项目文档、开发日志，天然就是很好的「对外分享素材」。
于是我的产出分两条线：
- **内部线**（`.ai/`）：给 AI 看的，简短、结构化、有决策理由
- **外部线**（`docs/share/`）：给人看的，有背景、有故事、有思考过程
同一份工作，两种产出。内部文档 → 去掉敏感信息 → 加上思考过程 → 对外文章。
这就是「一鸡多吃」——开发过程自动积累内容，阶段结束时翻译为对外语言。不需要「专门抽时间写分享」。
---
*下一篇：[Phase 1 阶段复盘](phase-01/阶段复盘_基础搭建.md) — 基础搭建阶段到底做了什么*
docs/share/README.md
+43
View File
@@ -0,0 +1,43 @@
# 分享内容
这里记录 ErrLens 从零到一的完整开发过程。每一个决策、每一次踩坑、每一个阶段性成果，都会沉淀到这里。
**目标读者**：对 AI 辅助编程感兴趣的人、想做类似项目的人、未来的自己。
---
## 内容目录
| 文件 | 说明 | 状态 |
|------|------|------|
| [00_项目缘起.md](00_项目缘起.md) | 为什么要做这个项目、1 人+3 AI 协作模式 | ✅ 已完成 |
| [01_框架设计思路.md](01_框架设计思路.md) | 信息架构为什么这样设计、token 预算概念 | ✅ 已完成 |
## 按阶段
| 阶段 | 复盘 | 决策故事 | 状态 |
|------|------|----------|------|
| Phase 1: 基础搭建 | [阶段复盘](phase-01/阶段复盘_基础搭建.md) | [ADR-007 信息架构](phase-01/决策故事_ADR-007.md) | ✅ |
| | | [ADR-009 人机协同](phase-01/决策故事_ADR-009.md) | ✅ |
| | | [旧架构合并](phase-01/决策故事_旧架构合并.md) | ✅ |
| Phase 2: MVP | — | — | 进行中 |
---
## 分享原则
1. **不是做完再写**：开发过程中自动积累，阶段结束时翻译为对外语言
2. **去掉内部细节**：不暴露 API 密钥、服务器地址、个人信息
3. **加上思考过程**：不只说「做了什么」，更要说「为什么这么选」
4. **可独立阅读**：每篇文章自成一体，不需要读其他文章才能理解
## 内容来源
```
开发过程中的产出 → 对外分享内容
─────────────────────────────────────────────
.ai/knowledge/decisions.md → 决策故事（加背景、加思考）
.ai/phases/*/completion.md → 阶段复盘（扩展为文章）
.ai/knowledge/lessons.md → 踩坑记录（精选）
.ai/knowledge/journal/ → 开发周记（合并精选）
```
docs/share/phase-01/决策故事_ADR-007.md
+75
View File
@@ -0,0 +1,75 @@
# ADR-007 决策故事：信息架构为什么从「大文档」变成「分层设计」
## 背景
ErrLens 项目从一开始就确定用「1 人 + 3 AI」的协作模式——Arch AI 做架构，Dev AI 写代码，QA AI 做测试。
但怎么让 3 个 AI 高效协作？我最初的做法很朴素：写一个大的 AGENTS.md，把项目介绍、架构设计、开发规范、权限体系全塞进去，每个 AI 启动时都读这一份。
然后问题就来了。
---
## 问题：AI 记不住、看不懂、互相干扰
**第一个问题：记不住。**
AGENTS.md 写到 2000 行时，Claude 的回复开始出现明显的「失忆」——前面提到的决策，后面讨论时就忘了。原因是上下文窗口虽然号称 200K token，但越靠后的内容，AI 的关注权重越低。
**第二个问题：看不懂重点。**
AGENTS.md 里混了所有信息——PRD 摘要、架构图、API 定义、目录结构、权限矩阵、Skill 描述……Dev AI 需要在 2000 行里找到和自己相关的 200 行。人类会跳读，AI 不会——它全读完后，重点已经淹没了。
**第三个问题：互相干扰。**
一个更隐蔽的问题：Dev AI 不需要知道 QA AI 的测试流程，Arch AI 不需要知道具体的代码目录结构。把不该看的信息喂给 AI，不仅浪费 token，更容易让它「想太多」——写出过度设计或不相关的代码。
---
## 选项
| 选项 | 优势 | 劣势 |
|------|------|------|
| A: 维持单体文档 | 维护简单，改一处就行 | 越长越差，AI 协作天花板低 |
| B: 精简 AGENTS.md | 立即可做 | 精简意味着丢掉信息，该有的细节还是要有的 |
| C: 分层信息架构 | 每个 AI 只看自己的，token 利用率高 | 需要重新设计目录结构，上下游依赖要梳理清楚 |
---
## 思考过程
我一开始想走 B 路线——把 AGENTS.md 精简到 500 行以内。但很快发现不行：精简掉的内容不是「冗余」，是「必要的细节」。比如 Drizzle Schema 定义，对 Dev AI 就是刚需，你不能为了省 token 把它删了。
然后我想到一个类比：**人类团队怎么分工？**
一个有 3 个员工的团队，不会把所有信息贴在一面墙上。而是每人有独立工位，各自维护自己的待办和参考资料。共享的信息放在公共区域。
AI 也应该这样。
选项 C 的核心逻辑：
1. **仪表盘**（DASHBOARD.md）——给人类看，30 秒了解项目全貌，不写代码细节
2. **路线图**（ROADMAP.md）——人+AI 共享视野，任务分配和进度跟踪
3. **角色工作台**（`.ai/roles/{arch,dev,qa}/`）——每个 AI 自己的 today.md + queue.md，只加载自己需要的上下文
4. **知识沉淀**（`.ai/knowledge/`）——ADR（架构决策记录）、journal（开发日志），按需加载
每层有 token 预算。Arch AI 启动时加载约 3K token（today + queue + decisions），Dev AI 类似。比单体 AGENTS.md 的 15K+ token 减少了 80%。
---
## 结果
分层后，几个明显的变化：
- **AI 回复质量更稳定**：不再出现「前面说了后面忘」的情况
- **上下文切换更快**：Dev AI 启动直接读 dev/today.md，不需要从 PRD 开始消化
- **人类管理成本降低**：DASHBOARD.md 一眼看到项目状态，不需要翻 10 个文件
- **「一鸡多吃」变得自然**：内部分层文档 → 去掉敏感信息 → 对外分享文章，流水线化
如果重来一次，我会从第一天就做分层。单体文档阶段浪费了大约 1 天的 AI token 和人类审核精力。
---
## 一句话总结
**为 AI 设计文档和为人设计文档，是完全不同的两件事。人会跳读，AI 不会——所以你的信息架构就是 AI 的注意力分配方案。**
docs/share/phase-01/决策故事_ADR-009.md
+93
View File
@@ -0,0 +1,93 @@
# ADR-009 决策故事：当 AI 识别不完美时，产品怎么设计
## 背景
ErrLens 的核心功能是：学生拍一张错题照片 → AI 识别题目内容 → 自动归类 → 分析错误原因 → 推荐同类练习。
这个流程看起来很美好，但它建立在一个脆弱的假设上：**AI 能准确识别每一张照片。**
现实是：中小学生的手写体，潦草起来连老师都看不懂。打印体 OCR 准确率可以到 95%+，但手写体的天花板大概在 70-80%。而且不只是 OCR——学科分类、知识点标注、错误类型诊断，每一步都可能出错。
第一个版本的 PRD 里，我完全没考虑这个问题。数据流画得很漂亮：「拍照 → AI 识别 → 入库 → 分析 → 推荐」，仿佛 AI 不会出错。
直到有人问我：「万一 AI 识别错了呢？」
---
## 问题：错误数据会污染整个系统
如果 AI 把「二次函数顶点坐标」错标成「一次函数斜率」，会发生什么？
1. 错题归到错误的知识点
2. 薄弱点分析显示「一次函数薄弱」，实际是二次函数有问题
3. 推荐系统给了 10 道一次函数的练习——和学生的真实弱项毫无关系
4. 学生发现推荐不准确 → 不信任产品 → 弃用
**一条错误数据进入分析管道，污染的是整个推荐飞轮。**
传统方案的思路是「提高 AI 准确率」——换更好的模型、加训练数据、调 prompt。但这条路的天花板很明显：手写体 OCR 准确率从 70% 提升到 85% 已经很难了，90% 在可见的将来都不现实。
而且，即使到了 90%，每 10 道错题就有 1 道是错的。100 道里有 10 道。对学生来说，10 次错误的推荐 = 再也不用了。
---
## 灵感：AI 做不好的事，让人来做
问题的本质是：**AI 做识别很强但不够完美，人做识别很准但太慢。**
那能不能结合起来？
我当时想到一个关键洞察：**学生本来就要看自己拍了什么。** 拍照录入的过程不是「拍完就完了」，用户本来就会确认「这张照片拍清楚了吗」「题目对吗」。这个「确认」动作，天然就是数据校验的机会。
于是设计了这样一个流程：
```
AI 识别结果不是「答案」，是「草稿」
↓
每个字段带置信度（这条我有多确定）
↓
高置信（>90%）：绿色标记，用户看一眼就行
中置信（70%-90%）：黄色提示，建议检查
低置信（<70%）：红色高亮，请手动修正
↓
用户确认/修正后 → 入库 → 进入分析管道
未经确认的数据 → 仅自己可见，不参与分析和推荐
```
核心设计原则：**AI 是草稿，用户是编辑。分析管道只吃「干净数据」。**
---
## 隐藏收益：每一次修正都是免费的标注数据
做到这一步后，我发现还有一个更大的收益。
用户修正时，系统记录两个值：
- `ai_value`：AI 的原始识别结果（比如标注为「二次函数顶点坐标」）
- `user_value`：用户修正后的值（实际是「二次函数图像性质」）
- `ai_confidence`：AI 当时对这个判断的置信度（0.72）
这条修正记录（CorrectionLog）就是一条**完美的标注数据**：
- 有原始模型输出（ai_value）
- 有人工标注结果（user_value）
- 有模型当时的置信度（可用于误差分析）
传统 AI 训练需要花钱请人标注数据。ErrLens 的标注员是用户——而且他们免费标注，甚至感谢你给了他们一个「修正」的功能。
P02 阶段（自研模型），这些 CorrectionLog 就是核心训练数据。产品用得越多，修正记录越多，模型越强——这是真正的数据飞轮。
---
## 结果
- error_items 表新增 `verification_status`（raw→reviewed→corrected→stale）和 `ai_confidence`（JSONB）
- 新增 `correction_logs` 表，记录每一条人机修正
- 分析/推荐查询强制加 `WHERE verification_status != 'raw'`
- 前端 UI 设计绿/黄/红三级置信度指示
---
## 一句话总结
**AI 的弱点不一定是产品的弱点——如果你能设计一个把「AI 错误」变成「用户价值」的闭环。**
docs/share/phase-01/决策故事_旧架构合并.md
+87
View File
@@ -0,0 +1,87 @@
# 决策故事：当两个架构要合并——30 项决策是怎么做的
## 背景
ErrLens 不是一个从零开始的项目。
在正式立项之前，我已经花了几周时间写了一个叫「家庭教育小程序」的架构设计——17 份文档，约 60,000 字，覆盖了小程序端、数据库、图像处理、交互设计、UI 规范、测试方案、部署方案等方方面面。
唯一的问题是：那个架构是面向「小学 5-6 年级学生家长 + 仅数学」的，用的是「微信云开发 + 云函数」的技术栈。而 ErrLens 定位已经变成了「小学初中学生 + 数学英语 + 自建后端」。
两套架构，一个旧一个新，重叠但不兼容。旧架构不能直接复用——技术栈变了。但也不能扔掉——里面有很多经过 Spike 验证的工程方案（图像处理管线、打印设计、UI 规范）。
问题变成：**怎么系统地把旧架构中有价值的部分提取出来，合并到新架构里，而不是陷入无休止的细节讨论？**
---
## 方法：结构化对比，逐项决策
我让 Arch AI 把 17 份旧文档全部读完后，把两套架构的差异拆成 30 个独立维度，按性质分成四类：
### 第一类：冲突项（8 项）
两套设计说了不同的话，必须二选一。
| 示例 | 旧架构 | 新架构 | 结论 |
|------|--------|--------|------|
| 技术栈 | 微信云开发 | NestJS + PostgreSQL | 选新架构，因为需要 Coze 沙盒自动化测试 |
| 目标用户 | 家长操作 | 学生本人 | 两者都要，学生和家长都可以操作 |
| 学科范围 | 仅数学 | 数学+英语 | 新架构已锁定 |
### 第二类：旧有新增（9 项）
旧架构有但新架构缺失的有价值功能。
| 示例 | 旧架构设计 | 决定 |
|------|-----------|------|
| 错题打印 | 完整 PDF 生成+下载流程 | 纳入 MVP，P0 |
| 图像预处理管线 | CLAHE+笔迹去除，经 Spike 验证 | 前置到 OCR 之前 |
| UI 设计规范 | 完整规范文档，28 个图标 | 整体迁移 |
### 第三类：新有新增（7 项）
新架构创新，旧架构完全没有。直接保留，不讨论。
### 第四类：各有优劣（6 项）
两边方案各有利弊，需要权衡。
| 示例 | 结论 |
|------|------|
| 知识点编码：业务编码 vs 数字 ID | 两者并存，ID 内部关联 + code 对外暴露 |
| 题目匹配：关键词 vs AI 语义 | 两阶段：关键词粗筛 → AI 精排 |
30 项决策，逐条过。人类拍板，AI 记录，一项一项写入架构文档。
---
## 思考：为什么能在一小时内完成 30 个决策？
如果让我一个人对着两份架构文档做合并，至少需要两天——读旧文档需要半天，对比需要一天，写合并方案再半天。
但 AI 可以：
1. **并行阅读**：17 份旧文档在 30 秒内全部读完并提取要点
2. **结构化拆解**：自动将差异按「冲突/新增/缺失/优劣」分类
3. **草拟选项**：每个维度列出优劣对比，方便人类判断
4. **即时落地**：决策一旦确认，5 分钟内更新完所有相关文档
人类的角色非常清晰：**做判断。** AI 负责列出选项、分析利弊、写成文档——人类只需要说「同意」「不同意」或「换个方案」。
这个协作模式的核心是：**人类不需要被 AI 告诉该怎么做，而是让 AI 把所有信息准备好，自己做决定。**
---
## 关键收获
1. **分类框架是决策效率的关键。** 「冲突/新增/缺失/优劣」这个四象限让复杂对比变得可管理。下次遇到类似问题可以直接复用。
2. **决策粒度要适中。** 太细（每个字段风格讨论）浪费精力，太粗（「技术栈全换」一句话）埋隐患。30 项这个数量级刚好——半天做完，该覆盖的都覆盖了。
3. **旧资产不要扔。** 旧架构虽然技术栈变了，但设计思路、工程参数、Spike 验证结论都是真金白银的积累。要有系统的方法提取价值。
---
## 一句话总结
**架构合并不需要你穷尽每一个细节。把它拆成独立的决策单元，人类逐项拍板，AI 负责剩下的——这就是「人机协同」在架构设计上的应用。**
docs/share/phase-01/阶段复盘_基础搭建.md
+80
View File
@@ -0,0 +1,80 @@
# Phase 1 阶段复盘：基础搭建
## 阶段信息
- 阶段编号：Phase 1/4
- 阶段名称：基础搭建
- 时间范围：2026-05-23 ~ 2026-05-26（4 天）
- 参与角色：人类 + Arch AI（Claude）
## 做了什么
Phase 1 不写一行业务代码。目标是「把骨架搭好，让 AI 知道该做什么」：
1. **信息架构重构**（ADR-007）：从单体 AGENTS.md 到四层分层架构
2. **PRD 编写**（v0.3.0 → v0.4.0）：完整的错题本产品需求文档，含人机协同数据闭环
3. **系统架构设计**（v0.3.0 → v0.4.0）：总体架构、技术选型、模块设计、数据模型
4. **旧架构合并**：将早期「家庭教育小程序」的 17 份架构文档与当前设计对比，30 项决策逐项确认
5. **Dev AI 工作台初始化**：8 个开发任务入队，含依赖关系图
交付物：10 份文档，约 30,000 字。
## 关键决策
### 决策 1：人机协同数据闭环（ADR-009）
**问题**：AI OCR 对手写体的识别率不可能 100%，错误数据直接进入分析会污染整个系统。
**方案**：「AI 是草稿，用户是编辑。」AI 识别结果带置信度入库，用户确认/修正后才进入分析管道。每一次修正都是免费的标注数据，P02 阶段用于训练自有模型。
**为什么重要**：这是产品数据飞轮的核心设计。没有这个闭环，产品就是普通的拍照 OCR 工具。
### 决策 2：分层信息架构（ADR-007）
**问题**：单体 AGENTS.md 太长，AI 注意力衰减，不同角色的信息混在一起。
**方案**：四层结构——仪表盘（人类）→ 路线图（共享）→ 角色工作台（AI 个人）→ 知识沉淀（共享）。每个 AI 只加载自己需要的信息。
**为什么重要**：这是整个 AI 协作模式的基础。没有好的信息架构，AI 再多也协同不起来。
### 决策 3：旧架构合并
**问题**：之前写的「家庭教育小程序」架构文档（17 份，约 60,000 字）不能白写，但又不能简单照搬——技术栈、用户定位、学科范围全变了。
**方案**：逐项对比，分成「冲突」「旧有新增」「新有新增」「各有优劣」四类，30 项决策逐条确认后统一写入新架构。
**为什么重要**：这是第一次「AI 辅助做架构合并」的实践。30 个决策不是 AI 自己拍板的，是人类逐条确认的。这个流程本身是一个可复用的方法论。
## 踩过的坑
### 坑 1：Edit 工具字符串匹配失败
短字符串替换没问题，但一次替换多个段落时经常找不到。原因是前面的修改已经改变了文件内容，后续匹配的目标字符串已不匹配。
**解法**：大段落修改拆成多次小修改，每次改动后确认文件当前状态再改下一个。宁可多改几次，不要一次写一大段。
### 坑 2：数据飞轮第一版太天真
最初的 PRD 版本假设「AI 拍完照就能完美识别」。被指出后才意识到这是核心风险。后来整个飞轮设计推翻重写——从「AI 完美假设」变成「人机协同闭环」。
**教训**：架构评审中，人的经验和直觉是 AI 替代不了的。AI 擅长帮你把想法落地成文档，但不会主动挑战你的假设。
## 学到的东西
1. **AI 协作的效率瓶颈不在 AI，在信息组织。** 文档写得好，AI 输出质量就高；文档一团乱，再强的模型也白搭。
2. **人类做决策，AI 做执行，是最佳的协作模式。** 30 项旧架构合并决策，AI 列出选项和优劣，人类逐条拍板，AI 写入文档——这个流程的效率远超纯人工或纯 AI。
3. **架构文档应该「分层写」。** 不是一份文档覆盖所有细节，而是不同层次的文档给不同角色看。这和代码的「关注点分离」是一个道理。
4. **旧资产不要扔。** 旧架构文档虽然技术栈变了，但图像处理管线、打印设计、UI 规范、测试用例都是可复用资产。关键是要有一个结构化的对比流程来提取价值。
## 数据
- 新增/更新文档：17 份（不含旧架构原文件）
- 总字数：约 30,000 字（PRD + 4 份架构文档 + ADR + 看板 + 分享内容）
- 架构决策记录：10 条（ADR-001 ~ ADR-010）
- 旧架构合并决策：30 项
- Dev 任务入队：8 个
- 代码行数：0（Phase 1 不写代码）
## 下一阶段预告
Phase 2 MVP：数据库 Schema → Auth → Image → Print → User → Upload → 页面骨架。Dev AI 开始写代码，QA AI 启动自动化测试。
docs/share/templates/决策故事模板.md
+38
View File
@@ -0,0 +1,38 @@
# 决策故事模板
## 决策编号
ADR-XXX
## 标题
用一句话描述这个决策（吸引人的标题）
## 背景
- 当时在做什么
- 遇到了什么问题
- 有哪些约束条件
## 选项
| 选项 | 优势 | 劣势 |
|------|------|------|
| A | ... | ... |
| B | ... | ... |
| C | ... | ... |
## 思考过程
- 为什么排除了某个选项
- 最纠结的点是什么
- 最终决策的关键因素
## 结果
- 决策带来的影响
- 如果有机会重来，会改变什么
## 一句话总结
（可引用/可传播的一句话）
docs/share/templates/阶段复盘模板.md
+35
View File
@@ -0,0 +1,35 @@
# 阶段复盘模板
## 阶段信息
- 阶段编号：Phase N
- 阶段名称：
- 时间范围：
- 参与角色：
## 做了什么
- （列表形式概述本阶段完成的主要工作）
## 关键决策
- （本阶段最重要的 3-5 个决策及背后的思考）
## 踩过的坑
- （本阶段遇到的主要问题及解决方案）
## 学到的东西
- （可复用的经验教训）
## 数据
- 新增代码行数：
- 任务完成数：
- Bug 修复数：
- 测试覆盖率：
## 下一阶段预告
- （接下来要做什么）

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