From 6992f59cd2cc6669322378fb43bd24ea91692c0a Mon Sep 17 00:00:00 2001 From: tupingr Date: Tue, 26 May 2026 15:17:06 +0800 Subject: [PATCH] =?UTF-8?q?refactor(arch):=20=E4=BF=A1=E6=81=AF=E6=9E=B6?= =?UTF-8?q?=E6=9E=84=E5=8D=87=E7=BA=A7=20=E2=80=94=20=E4=B8=89=E5=B1=82?= =?UTF-8?q?=E5=9B=9B=E8=A7=92=E8=89=B2=E6=8E=A7=E5=88=B6=E9=9D=A2=E6=9D=BF?= =?UTF-8?q?=20+=20=E8=B7=A8=E5=B9=B3=E5=8F=B0=20task=20=E4=BA=A4=E6=8E=A5?= =?UTF-8?q?=E5=8D=8F=E8=AE=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 核心变化： - 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 --- DASHBOARD.md => .ai/archive/DASHBOARD.md | 0 ROADMAP.md => .ai/archive/ROADMAP.md | 0 .../arch/queue.md => archive/arch-queue.md} | 0 .../arch/today.md => archive/arch-today.md} | 0 .../dev/queue.md => archive/dev-queue.md} | 0 .../dev/today.md => archive/dev-today.md} | 0 .../qa/queue.md => archive/qa-queue.md} | 0 .../qa/today.md => archive/qa-today.md} | 0 .ai/knowledge/decisions.md | 57 ++++++++ .ai/knowledge/journal/2026-05-26.md | 69 ++++++---- .ai/knowledge/lessons.md | 70 +++++++++- .ai/knowledge/patterns.md | 87 ++++++++++++ .ai/phases/INDEX.md | 8 +- .ai/principles.md | 22 ++- .ai/roles/README.md | 61 ++++++-- .ai/roles/arch/card.md | 49 ++++--- .ai/roles/dev/card.md | 37 +++-- .ai/roles/qa/card.md | 42 ++++-- .ai/tasks/active/CROSS-001.md | 52 +++++++ .ai/tasks/active/P01-001.md | 69 ++++++++++ .ai/tasks/active/P01-002.md | 64 +++++++++ .ai/tasks/active/P01-003.md | 69 ++++++++++ .ai/tasks/active/P01-004.md | 68 +++++++++ .ai/tasks/active/P01-005.md | 64 +++++++++ .ai/tasks/active/P01-006.md | 78 +++++++++++ .ai/tasks/active/P01-007.md | 67 +++++++++ .ai/tasks/active/T01-001.md | 63 +++++++++ .ai/tasks/active/T01-002.md | 61 ++++++++ .ai/tasks/active/T01-003.md | 64 +++++++++ .ai/tasks/active/T01-004.md | 64 +++++++++ .ai/tasks/active/T01-005.md | 68 +++++++++ .ai/tasks/active/T01-006.md | 66 +++++++++ .ai/tasks/templates/TASK_TEMPLATE_CODER.md | 47 +++++++ .ai/tasks/templates/TASK_TEMPLATE_TESTER.md | 75 ++++++++++ .trae/skills/share-context/SKILL.md | 31 ++++- AGENTS.md | 12 +- DECISIONS.md | 21 +++ dashboard.md | 130 ++++++++++++++++++ 38 files changed, 1630 insertions(+), 105 deletions(-) rename DASHBOARD.md => .ai/archive/DASHBOARD.md (100%) rename ROADMAP.md => .ai/archive/ROADMAP.md (100%) rename .ai/{roles/arch/queue.md => archive/arch-queue.md} (100%) rename .ai/{roles/arch/today.md => archive/arch-today.md} (100%) rename .ai/{roles/dev/queue.md => archive/dev-queue.md} (100%) rename .ai/{roles/dev/today.md => archive/dev-today.md} (100%) rename .ai/{roles/qa/queue.md => archive/qa-queue.md} (100%) rename .ai/{roles/qa/today.md => archive/qa-today.md} (100%) create mode 100644 .ai/tasks/active/CROSS-001.md create mode 100644 .ai/tasks/active/P01-001.md create mode 100644 .ai/tasks/active/P01-002.md create mode 100644 .ai/tasks/active/P01-003.md create mode 100644 .ai/tasks/active/P01-004.md create mode 100644 .ai/tasks/active/P01-005.md create mode 100644 .ai/tasks/active/P01-006.md create mode 100644 .ai/tasks/active/P01-007.md create mode 100644 .ai/tasks/active/T01-001.md create mode 100644 .ai/tasks/active/T01-002.md create mode 100644 .ai/tasks/active/T01-003.md create mode 100644 .ai/tasks/active/T01-004.md create mode 100644 .ai/tasks/active/T01-005.md create mode 100644 .ai/tasks/active/T01-006.md create mode 100644 .ai/tasks/templates/TASK_TEMPLATE_CODER.md create mode 100644 .ai/tasks/templates/TASK_TEMPLATE_TESTER.md create mode 100644 DECISIONS.md create mode 100644 dashboard.md diff --git a/DASHBOARD.md b/.ai/archive/DASHBOARD.md similarity index 100% rename from DASHBOARD.md rename to .ai/archive/DASHBOARD.md diff --git a/ROADMAP.md b/.ai/archive/ROADMAP.md similarity index 100% rename from ROADMAP.md rename to .ai/archive/ROADMAP.md diff --git a/.ai/roles/arch/queue.md b/.ai/archive/arch-queue.md similarity index 100% rename from .ai/roles/arch/queue.md rename to .ai/archive/arch-queue.md diff --git a/.ai/roles/arch/today.md b/.ai/archive/arch-today.md similarity index 100% rename from .ai/roles/arch/today.md rename to .ai/archive/arch-today.md diff --git a/.ai/roles/dev/queue.md b/.ai/archive/dev-queue.md similarity index 100% rename from .ai/roles/dev/queue.md rename to .ai/archive/dev-queue.md diff --git a/.ai/roles/dev/today.md b/.ai/archive/dev-today.md similarity index 100% rename from .ai/roles/dev/today.md rename to .ai/archive/dev-today.md diff --git a/.ai/roles/qa/queue.md b/.ai/archive/qa-queue.md similarity index 100% rename from .ai/roles/qa/queue.md rename to .ai/archive/qa-queue.md diff --git a/.ai/roles/qa/today.md b/.ai/archive/qa-today.md similarity index 100% rename from .ai/roles/qa/today.md rename to .ai/archive/qa-today.md diff --git a/.ai/knowledge/decisions.md b/.ai/knowledge/decisions.md index 814e45f..2a2f5bf 100644 --- a/.ai/knowledge/decisions.md +++ b/.ai/knowledge/decisions.md @@ -112,3 +112,60 @@ - `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」协作框架的实质性落地——从抽象角色到具体平台+模型绑定 diff --git a/.ai/knowledge/journal/2026-05-26.md b/.ai/knowledge/journal/2026-05-26.md index 4e8dd60..fc20042 100644 --- a/.ai/knowledge/journal/2026-05-26.md +++ b/.ai/knowledge/journal/2026-05-26.md @@ -1,32 +1,55 @@ -# Arch AI · 今日任务 · 2026-05-26 +# Arch AI · 开发日志 · 2026-05-26 -## 已完成 +## 完成事项 -- [x] **[P0]** 编写 `docs/01_产品需求/PRD.md` — 错题本产品需求文档 -- [x] **[P0]** 设计 `docs/02_系统架构/` — 总体架构、技术选型、模块设计、数据模型 -- [x] **[P1]** 将 P01 项目文档从"代码检测"改写为"错题本" -- [x] **[P1]** 更新 ROADMAP.md 任务看板（PRD 完成后分配 Dev 任务） +### 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: 上下文窗口是硬约束——盲目冲刺 = 带残缺记忆做决策 + +### 知识库变更汇总 + +| 文件 | 新增 | |------|------| -| `docs/01_产品需求/PRD.md` | 草案完成，待人类审阅（第 10 节 5 个待决策事项） | -| `docs/02_系统架构/总体架构.md` | 完成 | -| `docs/02_系统架构/技术选型.md` | 完成 | -| `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 任务已分配 | +| decisions.md | ADR-011, ADR-012 | +| lessons.md | L-002, L-003, L-004, L-005 | +| patterns.md | P-004, P-005 | -## 明天 (2026-05-27) +## 关键决策 -1. **根据人类反馈修订 PRD**（若有修改意见） -2. **将 Dev 任务写入 Dev AI 工作台**，指导 Dev 开始开发 -3. **补充架构决策记录 ADR-009**（错题本技术选型决策） +- **ADR-012 生效**：三平台四角色架构，Git 是唯一集成总线，task 文件自包含 +- **信息架构从「内部备忘录」重定位为「跨平台交接协议」** +- **取消 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) 开始。 diff --git a/.ai/knowledge/lessons.md b/.ai/knowledge/lessons.md index 675ae0d..b8bf7e8 100644 --- a/.ai/knowledge/lessons.md +++ b/.ai/knowledge/lessons.md @@ -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 的每个任务需独立可读，不依赖前后文 diff --git a/.ai/knowledge/patterns.md b/.ai/knowledge/patterns.md index 351628b..403cbd6 100644 --- a/.ai/knowledge/patterns.md +++ b/.ai/knowledge/patterns.md @@ -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 记录 diff --git a/.ai/phases/INDEX.md b/.ai/phases/INDEX.md index 20808fd..8eb19ac 100644 --- a/.ai/phases/INDEX.md +++ b/.ai/phases/INDEX.md @@ -2,8 +2,8 @@ | 阶段 | 名称 | 状态 | 目录 | |------|------|------|------| -| 1 | 基础搭建 | ACTIVE | `phase-01-foundation/` | -| 2 | MVP | PLANNED | `phase-02-mvp/` | +| 1 | 基础搭建 | DONE | `phase-01-foundation/` | +| 2 | MVP | ACTIVE | `phase-02-mvp/` | | 3 | 功能完善 | PLANNED | `phase-03-features/` | | 4 | 打磨发布 | PLANNED | `phase-04-polish/` | @@ -12,6 +12,6 @@ 1. 当前阶段 completion.md 全部打勾 2. 人类签字确认 3. Arch AI 更新本索引文件 -4. Arch AI 更新所有角色 card.md -5. Arch AI 更新 ROADMAP.md +4. Arch AI 更新所有角色 card.md（当前阶段字段） +5. Arch AI 更新 dashboard.md（进度条 + task 状态面板 + 最近事件） 6. 产出阶段复盘（docs/share/phase-NN/） diff --git a/.ai/principles.md b/.ai/principles.md index 7c7da58..243c973 100644 --- a/.ai/principles.md +++ b/.ai/principles.md @@ -25,11 +25,31 @@ Layer 3: 知识沉淀 → 自动积累，永久沉淀 ## 维护规则 1. **不超预算**：每个文件严格遵守 token 预算，超了就拆分 -2. **不重复状态**：状态只在一处记录（ROADMAP.md），其他地方引用 +2. **不重复状态**：状态只在一处记录（dashboard.md），其他地方引用 3. **Git 管历史**：文档只描述"现在是什么"，历史由 Git 负责 4. **一文一答**：每个文件独立回答一个问题，不需要串联阅读 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}/` diff --git a/.ai/roles/README.md b/.ai/roles/README.md index e5d6fb4..208e127 100644 --- a/.ai/roles/README.md +++ b/.ai/roles/README.md @@ -1,26 +1,57 @@ # 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） -2. 读 today.md → 今天干什么、任务优先级（< 1K tokens） -3. 需要细节 → 按链接按需加载 -4. 完成后 → 更新 today.md，写 journal +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] +``` -| 角色 | 目录 | 职责 | -|------|------|------| -| Arch AI | `arch/` | 需求分析、架构设计、技术选型、跨模块协调 | -| Dev AI | `dev/` | 编码实现、文档编写、Bug 修复 | -| QA AI | `qa/` | 测试编写、测试执行、质量反馈 | +**Tester AI (Coze)**: +``` +1. git pull + 读 card.md +2. git log --grep="READY_FOR_TEST" → 找待测 task +3. 读对应 Tester task 文件 → 测试内容/执行方式/报告格式 +4. 拉代码 → 沙盒执行 → 生成 JSON 报告 +5. commit 报告 +``` -## 维护规则 +## 关键原则 -- Arch AI 负责分配任务到各角色的 queue.md 和 today.md -- 每个 AI 完成工作后更新自己的 today.md -- 阶段切换时 Arch AI 更新所有 card.md +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/` diff --git a/.ai/roles/arch/card.md b/.ai/roles/arch/card.md index a31ac67..2ae8c41 100644 --- a/.ai/roles/arch/card.md +++ b/.ai/roles/arch/card.md @@ -2,33 +2,42 @@ ## 身份 -我是架构 AI。负责需求分析、架构设计、技术选型、跨模块协调。 -拥有最高 AI 权限，指导 Dev AI 和 QA AI 的工作。 +我是架构 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` -- 阶段上下文: `.ai/phases/phase-01-foundation/` -- 知识沉淀: `.ai/knowledge/` -- 全局视野: `ROADMAP.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/ +**禁止**: 无 diff --git a/.ai/roles/dev/card.md b/.ai/roles/dev/card.md index a235f75..4abd726 100644 --- a/.ai/roles/dev/card.md +++ b/.ai/roles/dev/card.md @@ -3,29 +3,38 @@ ## 身份 我是开发 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/*/docs/) -- 验收标准补充 -- 变更影响评估 -## 协作文件 +## 关键入口 -- 代码规范: `.ai/prompts/coding/code-style.md` -- 文档模板: `.ai/prompts/coding/doc-template.md` -- 完整权限: `AGENTS.md` -- 阶段上下文: `.ai/phases/phase-01-foundation/` -- 全局视野: `ROADMAP.md` +| 文件 | 说明 | +|------|------| +| `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/ diff --git a/.ai/roles/qa/card.md b/.ai/roles/qa/card.md index cfb7098..1f471c8 100644 --- a/.ai/roles/qa/card.md +++ b/.ai/roles/qa/card.md @@ -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/) -- Bug 反馈 (review/*/feedback/) -- 验收标准补充 +- Bug 反馈（在测试报告中标注 FAIL 项） -## 协作文件 +## 关键入口 -- Bug 报告模板: `.ai/prompts/testing/bug-report.md` -- 完整权限: `AGENTS.md` -- 阶段上下文: `.ai/phases/phase-01-foundation/` -- 全局视野: `ROADMAP.md` +| 文件 | 说明 | +|------|------| +| `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/ diff --git a/.ai/tasks/active/CROSS-001.md b/.ai/tasks/active/CROSS-001.md new file mode 100644 index 0000000..9b8df8a --- /dev/null +++ b/.ai/tasks/active/CROSS-001.md @@ -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]` diff --git a/.ai/tasks/active/P01-001.md b/.ai/tasks/active/P01-001.md new file mode 100644 index 0000000..18d4ac7 --- /dev/null +++ b/.ai/tasks/active/P01-001.md @@ -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]` diff --git a/.ai/tasks/active/P01-002.md b/.ai/tasks/active/P01-002.md new file mode 100644 index 0000000..397606f --- /dev/null +++ b/.ai/tasks/active/P01-002.md @@ -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]` diff --git a/.ai/tasks/active/P01-003.md b/.ai/tasks/active/P01-003.md new file mode 100644 index 0000000..bc4f417 --- /dev/null +++ b/.ai/tasks/active/P01-003.md @@ -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]` diff --git a/.ai/tasks/active/P01-004.md b/.ai/tasks/active/P01-004.md new file mode 100644 index 0000000..8e95907 --- /dev/null +++ b/.ai/tasks/active/P01-004.md @@ -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]` diff --git a/.ai/tasks/active/P01-005.md b/.ai/tasks/active/P01-005.md new file mode 100644 index 0000000..0f1f6cb --- /dev/null +++ b/.ai/tasks/active/P01-005.md @@ -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]` diff --git a/.ai/tasks/active/P01-006.md b/.ai/tasks/active/P01-006.md new file mode 100644 index 0000000..f2b2d72 --- /dev/null +++ b/.ai/tasks/active/P01-006.md @@ -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]` diff --git a/.ai/tasks/active/P01-007.md b/.ai/tasks/active/P01-007.md new file mode 100644 index 0000000..b7d39ed --- /dev/null +++ b/.ai/tasks/active/P01-007.md @@ -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]` diff --git a/.ai/tasks/active/T01-001.md b/.ai/tasks/active/T01-001.md new file mode 100644 index 0000000..878a9aa --- /dev/null +++ b/.ai/tasks/active/T01-001.md @@ -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 diff --git a/.ai/tasks/active/T01-002.md b/.ai/tasks/active/T01-002.md new file mode 100644 index 0000000..a602014 --- /dev/null +++ b/.ai/tasks/active/T01-002.md @@ -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 diff --git a/.ai/tasks/active/T01-003.md b/.ai/tasks/active/T01-003.md new file mode 100644 index 0000000..30ffb00 --- /dev/null +++ b/.ai/tasks/active/T01-003.md @@ -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 diff --git a/.ai/tasks/active/T01-004.md b/.ai/tasks/active/T01-004.md new file mode 100644 index 0000000..0f9c4c7 --- /dev/null +++ b/.ai/tasks/active/T01-004.md @@ -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 diff --git a/.ai/tasks/active/T01-005.md b/.ai/tasks/active/T01-005.md new file mode 100644 index 0000000..48cb57c --- /dev/null +++ b/.ai/tasks/active/T01-005.md @@ -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 diff --git a/.ai/tasks/active/T01-006.md b/.ai/tasks/active/T01-006.md new file mode 100644 index 0000000..d6e5a0a --- /dev/null +++ b/.ai/tasks/active/T01-006.md @@ -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 diff --git a/.ai/tasks/templates/TASK_TEMPLATE_CODER.md b/.ai/tasks/templates/TASK_TEMPLATE_CODER.md new file mode 100644 index 0000000..af50f98 --- /dev/null +++ b/.ai/tasks/templates/TASK_TEMPLATE_CODER.md @@ -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]` diff --git a/.ai/tasks/templates/TASK_TEMPLATE_TESTER.md b/.ai/tasks/templates/TASK_TEMPLATE_TESTER.md new file mode 100644 index 0000000..ca51a48 --- /dev/null +++ b/.ai/tasks/templates/TASK_TEMPLATE_TESTER.md @@ -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 diff --git a/.trae/skills/share-context/SKILL.md b/.trae/skills/share-context/SKILL.md index 1a89eee..02f3a33 100644 --- a/.trae/skills/share-context/SKILL.md +++ b/.trae/skills/share-context/SKILL.md @@ -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. 扫描内部文档，识别可分享内容 按以下来源对比 `docs/share/` 已有内容，找出新增/变化： @@ -103,15 +120,17 @@ docs/share/ ## 注意事项 -1. **不是做完再写**：开发过程中自动积累，阶段结束时批量产出 -2. **同一份工作，两种语言**：内部文档是「给 AI 看的结构化数据」，对外文章是「给人看的故事」 -3. **保持真诚**：有成功写成功，有失败写失败。读者能看出哪些是 PR 稿 -4. **去敏但不去肉**：去掉敏感信息，但保留具体细节。一个没有细节的故事没有价值 -5. **链接内部来源**：每篇文章底部可附「内部参考：ADR-XXX」但不暴露内部文件路径 +1. **先入库，后分享**：Step 0 必须在 Step 1 之前执行。知识库是米缸，分享是做饭——米缸空了做不出饭 +2. **不是做完再写**：开发过程中自动积累，阶段结束时批量产出 +3. **同一份工作，两种语言**：内部文档是「给 AI 看的结构化数据」，对外文章是「给人看的故事」 +4. **保持真诚**：有成功写成功，有失败写失败。读者能看出哪些是 PR 稿 +5. **去敏但不去肉**：去掉敏感信息，但保留具体细节。一个没有细节的故事没有价值 +6. **链接内部来源**：每篇文章底部可附「内部参考：ADR-XXX」但不暴露内部文件路径 --- -**Version**: 1.0 +**Version**: 1.1 +**Updated**: 2026-05-26 — 新增 Step 0「反向检查」，补上知识库摄入端 **Created**: 2026-05-26 **Based On**: ErrLens 开发实践 — Phase 1 收尾时的「一鸡多吃」流程 **Purpose**: 将内部开发文档自动转化为对外分享内容，实现「开发即内容」的闭环 diff --git a/AGENTS.md b/AGENTS.md index ff1a956..3a7a682 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,13 +1,15 @@ # AI 角色定义与权限约定 -> **如果你是 AI，请直接跳转到你的角色工作台：** -> - Arch AI → `.ai/roles/arch/card.md` -> - Dev AI → `.ai/roles/dev/card.md` -> - QA AI → `.ai/roles/qa/card.md` +> **如果你是 AI，请直接跳转到你的角色入口：** +> - Arch AI → `dashboard.md` 全文 +> - Dev AI → `.ai/roles/dev/card.md` → 对应 `.ai/tasks/active/P01-XXX.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。 --- diff --git a/DECISIONS.md b/DECISIONS.md new file mode 100644 index 0000000..7106cda --- /dev/null +++ b/DECISIONS.md @@ -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 维护。* diff --git a/dashboard.md b/dashboard.md new file mode 100644 index 0000000..2ea3d6c --- /dev/null +++ b/dashboard.md @@ -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 维护。阶段切换时更新。不随每日任务变化。*