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

refactor(arch): 信息架构升级 — 三层四角色控制面板 + 跨平台 task 交接协议

Browse Source 
核心变化：
- 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>
This commit is contained in:
tupingr
2026-05-26 15:17:06 +08:00
parent 5b428d0810
commit 6992f59cd2
38 changed files with 1630 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DASHBOARD.md → .ai/archive/DASHBOARD.md
View File
ROADMAP.md → .ai/archive/ROADMAP.md
View File
.ai/roles/arch/queue.md → .ai/archive/arch-queue.md
View File
.ai/roles/arch/today.md → .ai/archive/arch-today.md
View File
.ai/roles/dev/queue.md → .ai/archive/dev-queue.md
View File
.ai/roles/dev/today.md → .ai/archive/dev-today.md
View File
.ai/roles/qa/queue.md → .ai/archive/qa-queue.md
View File
.ai/roles/qa/today.md → .ai/archive/qa-today.md
View File
.ai/knowledge/decisions.md
+57
View File
@@ -112,3 +112,60 @@
- `questions` 表 `source` 字段 = 适配器路由 key（`self_built` | `zuoyebang` | 未来扩展） - `questions` 表 `source` 字段 = 适配器路由 key（`self_built` | `zuoyebang` | 未来扩展）
- `external_id` 字段存储第三方题库的原始 ID，自有题库此字段为空 - `external_id` 字段存储第三方题库的原始 ID，自有题库此字段为空
- 健康检查: 每个适配器实现 `healthCheck()`，用于监控外部 API 可用性 - 健康检查: 每个适配器实现 `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/2026-05-26.md
+46 -23
View File
@@ -1,32 +1,55 @@
# Arch AI · 今日任务 · 2026-05-26 # Arch AI · 开发日志 · 2026-05-26
## 已完成 ## 完成事项
- [x] **[P0]** 编写 `docs/01_产品需求/PRD.md` — 错题本产品需求文档 ### Phase 1 收尾
- [x] **[P0]** 设计 `docs/02_系统架构/` — 总体架构、技术选型、模块设计、数据模型 - [x] 旧架构合并：30 项决策逐项确认，5 份架构文档升级至 v0.4.0
- [x] **[P1]** 将 P01 项目文档从"代码检测"改写为"错题本" - [x] 一鸡多吃：6 篇对外分享文章完成（项目缘起、框架设计、阶段复盘、ADR-007/009、旧架构合并）
- [x] **[P1]** 更新 ROADMAP.md 任务看板（PRD 完成后分配 Dev 任务） - [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: 上下文窗口是硬约束——盲目冲刺 = 带残缺记忆做决策
### 知识库变更汇总
| 文件 | 新增 |
|------|------| |------|------|
| `docs/01_产品需求/PRD.md` | 草案完成，待人类审阅（第 10 节 5 个待决策事项） | | decisions.md | ADR-011, ADR-012 |
| `docs/02_系统架构/总体架构.md` | 完成 | | lessons.md | L-002, L-003, L-004, L-005 |
| `docs/02_系统架构/技术选型.md` | 完成 | | patterns.md | P-004, P-005 |
| `docs/02_系统架构/模块设计.md` | 完成 |
| `docs/02_系统架构/数据模型.md` | 完成 |
| `projects/P01_errlens_app/docs/01_需求概要.md` | 已改写 |
| `projects/P01_errlens_app/docs/02_架构设计.md` | 已改写 |
| `projects/P01_errlens_app/docs/03_接口定义.md` | 已改写 |
| `ROADMAP.md` | 已更新，RED 阻塞解除，Dev 任务已分配 |
## 明天 (2026-05-27) ## 关键决策
1. **根据人类反馈修订 PRD**（若有修改意见） - **ADR-012 生效**：三平台四角色架构，Git 是唯一集成总线，task 文件自包含
2. **将 Dev 任务写入 Dev AI 工作台**，指导 Dev 开始开发 - **信息架构从「内部备忘录」重定位为「跨平台交接协议」**
3. **补充架构决策记录 ADR-009**（错题本技术选型决策） - **取消 ADR-011 的精简计划**：文档不能砍，因为它是平台间的唯一通信协议
- **Arch AI 上下文管理作为硬约束写入原则**
## 阻塞 ## 项目状态
（无 — 等待人类审阅 PRD 第 10 节） Phase 2 就绪。14 个 task 文件待 Coder/Tester AI 领用。无阻塞。
## 明天
Phase 2 编码启动。Coder AI (Trae + GLM-4.6) 从 P01-001 (DB Schema) 开始。
.ai/knowledge/lessons.md
+68 -2
View File
@@ -20,6 +20,72 @@
--- ---
## L-002 ## 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-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
+87
View File
@@ -48,6 +48,93 @@
--- ---
## 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 记录 - 在多个文件中重复同一状态信息 → 只在 ROADMAP.md 记录
.ai/phases/INDEX.md
+4 -4
View File
@@ -2,8 +2,8 @@
| 阶段 | 名称 | 状态 | 目录 | | 阶段 | 名称 | 状态 | 目录 |
|------|------|------|------| |------|------|------|------|
| 1 | 基础搭建 | ACTIVE | `phase-01-foundation/` | | 1 | 基础搭建 | DONE | `phase-01-foundation/` |
| 2 | MVP | PLANNED | `phase-02-mvp/` | | 2 | MVP | ACTIVE | `phase-02-mvp/` |
| 3 | 功能完善 | PLANNED | `phase-03-features/` | | 3 | 功能完善 | PLANNED | `phase-03-features/` |
| 4 | 打磨发布 | PLANNED | `phase-04-polish/` | | 4 | 打磨发布 | PLANNED | `phase-04-polish/` |
@@ -12,6 +12,6 @@
1. 当前阶段 completion.md 全部打勾 1. 当前阶段 completion.md 全部打勾
2. 人类签字确认 2. 人类签字确认
3. Arch AI 更新本索引文件 3. Arch AI 更新本索引文件
4. Arch AI 更新所有角色 card.md 4. Arch AI 更新所有角色 card.md（当前阶段字段）
5. Arch AI 更新 ROADMAP.md 5. Arch AI 更新 dashboard.md（进度条 + task 状态面板 + 最近事件）
6. 产出阶段复盘（docs/share/phase-NN/） 6. 产出阶段复盘（docs/share/phase-NN/）
.ai/principles.md
+21 -1
View File
@@ -25,11 +25,31 @@ Layer 3: 知识沉淀 → 自动积累，永久沉淀
## 维护规则 ## 维护规则
1. **不超预算**：每个文件严格遵守 token 预算，超了就拆分 1. **不超预算**：每个文件严格遵守 token 预算，超了就拆分
2. **不重复状态**：状态只在一处记录（ROADMAP.md），其他地方引用 2. **不重复状态**：状态只在一处记录（dashboard.md），其他地方引用
3. **Git 管历史**：文档只描述"现在是什么"，历史由 Git 负责 3. **Git 管历史**：文档只描述"现在是什么"，历史由 Git 负责
4. **一文一答**：每个文件独立回答一个问题，不需要串联阅读 4. **一文一答**：每个文件独立回答一个问题，不需要串联阅读
5. **角色无关设计**：任何 AI 模型都能通过读 card.md 快速接管角色 5. **角色无关设计**：任何 AI 模型都能通过读 card.md 快速接管角色
## Arch AI 上下文资源管理（硬约束）
**问题**：Arch AI 每次会话有上下文窗口限制。如果盲目冲刺大任务，到一半触发自动压缩，前面的讨论、决策细节、已排除的选项全部丢失——代价不是「重来」，是「用不完整的记忆做决策」。
**规则**：
1. **任务前评估**：开始一个复杂任务前，先判断能否在自己的有效上下文内完成。如果不能，拆分到多个独立会话
2. **做完一件再开始下一件**：不积累未完成的工作。一个阶段收尾了（commit + push），再启动下一个
3. **决策即记录**：每个重要判断产生后，立即写入对应的 knowledge/ 文件，不要留在对话里。对话是易失的，knowledge 是持久的
4. **接近窗口上限时主动收尾**：感觉上下文开始吃力时，主动做 checkpoint——把已完成的写入文件、commit、告知人类当前进展和下一步。**宁可多开一个会话，不要带着残缺记忆继续**
5. **拆分策略**：大任务（如「重构整个架构」）拆成独立可提交的子任务。每个子任务结束后 git commit，确保即使后续会话压缩，已完成的部分不会丢失
**信号识别**：当出现以下情况时，说明接近上下文上限，应立即执行规则 4：
- 需要反复回看前面的讨论才能做判断
- 开始忘记用户几分钟前说过的话
- Token 用量接近已知窗口限制
- 回复质量出现可感知的下降
**反模式**：「一口气做完再 commit」——做一半触发压缩，前面做的全丢。
## 文件约定 ## 文件约定
- 角色工作台: `.ai/roles/{role}/` - 角色工作台: `.ai/roles/{role}/`
.ai/roles/README.md
+46 -15
View File
@@ -1,26 +1,57 @@
# AI 角色工作台 # AI 角色工作台
每个角色有一个独立的工作台目录。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. 读 card.md → 我是谁、我能写哪、当前阶段（< 1K tokens） 1. 读 dashboard.md → 了解全貌 + ADR 摘要 + task 状态
2. 读 today.md → 今天干什么、任务优先级（< 1K tokens） 2. 需要细节 → 按链接按需加载
3. 需要细节 → 按链接按需加载 3. 人类决策 → 读 DECISIONS.md
4. 完成后 → 更新 today.md，写 journal 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)**:
|------|------|------| ```
| Arch AI | `arch/` | 需求分析、架构设计、技术选型、跨模块协调 | 1. git pull + 读 card.md
| Dev AI | `dev/` | 编码实现、文档编写、Bug 修复 | 2. git log --grep="READY_FOR_TEST" → 找待测 task
| QA AI | `qa/` | 测试编写、测试执行、质量反馈 | 3. 读对应 Tester task 文件 → 测试内容/执行方式/报告格式
4. 拉代码 → 沙盒执行 → 生成 JSON 报告
5. commit 报告
```
## 维护规则 ## 关键原则
- Arch AI 负责分配任务到各角色的 queue.md 和 today.md 1. **每个角色只有一个入口文件** — 不拼图，不切换
- 每个 AI 完成工作后更新自己的 today.md 2. **Worker AI 不需要知道项目全貌** — task 文件就是它的全部世界
- 阶段切换时 Arch AI 更新所有 card.md 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
+29 -20
View File
@@ -2,33 +2,42 @@
## 身份 ## 身份
我是架构 AI。负责需求分析、架构设计、技术选型、跨模块协调。 我是架构 AI。负责需求分析、架构设计、技术选型、任务分解。
拥有最高 AI 权限，指导 Dev AI 和 QA AI 的工作。
## 权限 **平台**: Claude Code + DeepSeek V4 Pro（最强推理 + Agent 框架）
**可写**: docs/ shared/ projects/*/src/ projects/*/docs/ review/*/acceptance.md review/*/impact.md review/*/task.md tools/ data/ ## 启动流程
**只读**: .ai/ projects/*/tests/ reports/ review/*/feedback/
**禁止**: 无 1. 读 `dashboard.md` 全文（< 2K tokens）→ 项目全貌 + ADR 索引 + task 状态面板
2. 需要细节 → 按 dashboard 中的链接按需加载
3. 人类决策 → 读 `DECISIONS.md`
4. 完成任务 → 更新 dashboard.md + 对应 ADR/knowledge 文件
## 当前阶段 ## 当前阶段
Phase 1: 基础搭建 — `.ai/phases/phase-01-foundation/goal.md` Phase 2: MVP 开发 — `dashboard.md`
## 核心交付物 ## 核心交付物
- 产品需求文档 (PRD) - 产品需求 + 系统架构设计
- 系统架构设计文档 - 技术选型 + 架构决策 (ADR)
- 技术选型评估 - 任务分解 → `.ai/tasks/active/P01-XXX.md`
- 验收标准定义 - 跨模块协调（Coder ↔ Tester 交接协议）
- 变更影响评估 - 人类决策梳理 → `DECISIONS.md`
- 跨模块协调
## 协作文件 ## 关键入口
- 任务分配: `.ai/roles/{dev,qa}/queue.md` | 文件 | 说明 |
- 代码规范: `.ai/prompts/coding/code-style.md` |------|------|
- 完整权限: `AGENTS.md` | `dashboard.md` | 唯一控制面板（替代旧 DASHBOARD.md / ROADMAP.md） |
- 阶段上下文: `.ai/phases/phase-01-foundation/` | `DECISIONS.md` | 待人类决策事项 |
- 知识沉淀: `.ai/knowledge/` | `.ai/knowledge/decisions.md` | ADR 全文 |
- 全局视野: `ROADMAP.md` | `.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
+23 -14
View File
@@ -3,29 +3,38 @@
## 身份 ## 身份
我是开发 AI。负责编写业务代码、技术文档、Bug 修复。 我是开发 AI。负责编写业务代码、技术文档、Bug 修复。
不修改测试代码和测试报告。
## 权限 **平台**: Trae CN + GLM-4.6（代码生成 + 文件操作，单文件粒度）
**可写**: projects/*/src/ projects/*/docs/ docs/ tools/ data/ shared/ review/*/acceptance.md review/*/impact.md ## 启动流程
**只读**: review/*/task.md review/*/feedback/
**禁止**: projects/*/tests/ reports/ 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 1: 基础搭建 — `.ai/phases/phase-01-foundation/goal.md` Phase 2: MVP 开发
## 核心交付物 ## 核心交付物
- 业务代码实现 (projects/*/src/) - 业务代码实现 (projects/*/src/)
- 项目文档 (projects/*/docs/) - 项目文档 (projects/*/docs/)
- 验收标准补充
- 变更影响评估
## 协作文件 ## 关键入口
- 代码规范: `.ai/prompts/coding/code-style.md` | 文件 | 说明 |
- 文档模板: `.ai/prompts/coding/doc-template.md` |------|------|
- 完整权限: `AGENTS.md` | `dashboard.md` | 查找自己的 task |
- 阶段上下文: `.ai/phases/phase-01-foundation/` | `.ai/tasks/active/P01-XXX.md` | 你的 task 文件（开工时读这个） |
- 全局视野: `ROADMAP.md` | `.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
+27 -15
View File
@@ -2,29 +2,41 @@
## 身份 ## 身份
我是测试 AI。负责编写测试用例、执行测试、提交反馈。 我是测试 AI。负责在 Coze 沙盒中拉取代码、执行测试、生成报告。
不修改业务代码。
## 权限 **平台**: Coze CN（沙盒执行 + 自动化测试）
**可写**: projects/*/tests/ reports/ review/*/acceptance.md review/*/feedback/ ## 启动流程
**只读**: projects/*/src/ projects/*/docs/ docs/ data/ shared/ review/*/task.md
**禁止**: .ai/ tools/ review/*/impact.md 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 1: 基础搭建 — `.ai/phases/phase-01-foundation/goal.md` Phase 2: MVP 开发
## 核心交付物 ## 核心交付物
- 测试用例 (projects/*/tests/)
- 测试报告 (reports/) - 测试报告 (reports/)
- Bug 反馈 (review/*/feedback/) - Bug 反馈（在测试报告中标注 FAIL 项）
- 验收标准补充
## 协作文件 ## 关键入口
- Bug 报告模板: `.ai/prompts/testing/bug-report.md` | 文件 | 说明 |
- 完整权限: `AGENTS.md` |------|------|
- 阶段上下文: `.ai/phases/phase-01-foundation/` | `dashboard.md` | 查找自己的 task |
- 全局视野: `ROADMAP.md` | `.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/share-context/SKILL.md
+25 -6
View File
@@ -19,6 +19,23 @@ description: "一鸡多吃：将内部开发文档（ADR、阶段复盘、开发
## 执行步骤 ## 执行步骤
### 0. 反向检查：知识库是否遗漏了有价值的洞察
**在扫描对外分享内容之前**，先检查是否有最近的开发讨论/决策/想法尚未写入知识库：
| 检查项 | 判断标准 | 写入目标 |
|--------|---------|---------|
| 近期是否有重要的架构讨论 | 讨论产生了「可复用的判断」或「方向性决策」 | `.ai/knowledge/decisions.md`（新 ADR） |
| 近期是否有反直觉的发现或错误 | 讨论产生了「原来以为…但其实…」的洞察 | `.ai/knowledge/lessons.md`（新 L-XXX） |
| 近期是否发现了可复用的模式 | 同样的做法出现了 2 次以上 | `.ai/knowledge/patterns.md`（新 P-XXX） |
**触发词**：当讨论中出现以下信号时，应主动提议记录：
- 「这个很有价值」「值得记下来」「下次遇到可以…」
- 「原来是这样」「之前没想到」「反直觉的是…」
- 领域术语的定义或边界划分（如「蜂群模式」「编排器-执行者」）
如果发现遗漏，**先补知识库，再执行后续步骤**。知识库是分享的源头——源头空了，一鸡多吃也无米下锅。
### 1. 扫描内部文档，识别可分享内容 ### 1. 扫描内部文档，识别可分享内容
按以下来源对比 `docs/share/` 已有内容，找出新增/变化： 按以下来源对比 `docs/share/` 已有内容，找出新增/变化：
@@ -103,15 +120,17 @@ docs/share/
## 注意事项 ## 注意事项
1. **不是做完再写**：开发过程中自动积累，阶段结束时批量产出 1. **先入库，后分享**：Step 0 必须在 Step 1 之前执行。知识库是米缸，分享是做饭——米缸空了做不出饭
2. **同一份工作，两种语言**：内部文档是「给 AI 看的结构化数据」，对外文章是「给人看的故事」 2. **不是做完再写**：开发过程中自动积累，阶段结束时批量产出
3. **保持真诚**：有成功写成功，有失败写失败。读者能看出哪些是 PR 稿 3. **同一份工作，两种语言**：内部文档是「给 AI 看的结构化数据」，对外文章是「给人看的故事」
4. **去敏但不去肉**：去掉敏感信息，但保留具体细节。一个没有细节的故事没有价值 4. **保持真诚**：有成功写成功，有失败写失败。读者能看出哪些是 PR 稿
5. **链接内部来源**：每篇文章底部可附「内部参考：ADR-XXX」但不暴露内部文件路径 5. **去敏但不去肉**：去掉敏感信息，但保留具体细节。一个没有细节的故事没有价值
6. **链接内部来源**：每篇文章底部可附「内部参考：ADR-XXX」但不暴露内部文件路径
--- ---
**Version**: 1.0 **Version**: 1.1
**Updated**: 2026-05-26 — 新增 Step 0「反向检查」，补上知识库摄入端
**Created**: 2026-05-26 **Created**: 2026-05-26
**Based On**: ErrLens 开发实践 — Phase 1 收尾时的「一鸡多吃」流程 **Based On**: ErrLens 开发实践 — Phase 1 收尾时的「一鸡多吃」流程
**Purpose**: 将内部开发文档自动转化为对外分享内容，实现「开发即内容」的闭环 **Purpose**: 将内部开发文档自动转化为对外分享内容，实现「开发即内容」的闭环
AGENTS.md
+7 -5
View File
@@ -1,13 +1,15 @@
# AI 角色定义与权限约定 # AI 角色定义与权限约定
> **如果你是 AI，请直接跳转到你的角色工作台：** > **如果你是 AI，请直接跳转到你的角色入口：**
> - Arch AI → `.ai/roles/arch/card.md` > - Arch AI → `dashboard.md` 全文
> - Dev AI → `.ai/roles/dev/card.md` > - Dev AI → `.ai/roles/dev/card.md` → 对应 `.ai/tasks/active/P01-XXX.md`
> - QA AI → `.ai/roles/qa/card.md` > - QA AI → `.ai/roles/qa/card.md` → 对应 `.ai/tasks/active/T01-XXX.md`
> >
> **如果你是**人类，请看 `DASHBOARD.md` + `ROADMAP.md`。 > **如果你是**人类，请看 `dashboard.md` 顶部「人类区」。
> >
> 本文档是权限矩阵的**唯一权威参考**。角色工作台中的权限描述为摘要，如有冲突以本文档为准。 > 本文档是权限矩阵的**唯一权威参考**。角色工作台中的权限描述为摘要，如有冲突以本文档为准。
>
> **架构说明**: 旧入口（DASHBOARD.md / ROADMAP.md / roles/*/today.md / roles/*/queue.md）已归档至 `.ai/archive/`。详见 ADR-012。
--- ---
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 维护。*
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 维护。阶段切换时更新。不随每日任务变化。*