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
.ai/roles/README.md
+46 -15
View File
@@ -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/`
.ai/roles/arch/card.md
+29 -20
View File
@@ -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/
**禁止**: 无
.ai/roles/arch/queue.md
-21
View File
@@ -1,21 +0,0 @@
# Arch AI · 任务队列
## 当前阶段 (Phase 1) 任务
| # | 任务 | 优先级 | 状态 | 依赖 |
|---|------|--------|------|------|
| 1 | 信息架构重构 | P0 | DONE | — |
| 2 | 错题本 PRD 编写 | P0 | DONE | 1 |
| 3 | 系统架构设计 | P0 | DONE | 2 |
| 4 | P01 文档改写 | P1 | DONE | 2 |
| 5 | PRD 修订（根据人类反馈） | P0 | TODO | 人类审阅 |
| 6 | 将 Dev 任务写入 Dev 工作台 | P1 | TODO | 3 |
| 7 | 补充 ADR-009 技术选型决策 | P1 | TODO | 3 |
| 8 | 架构提示词模板 | P2 | TODO | — |
## 未来阶段预留
| # | 任务 | 阶段 | 优先级 |
|---|------|------|--------|
| — | Phase 2 MVP 架构设计 | 2 | — |
| — | Phase 3 功能迭代架构 | 3 | — |
.ai/roles/arch/today.md
-45
View File
@@ -1,45 +0,0 @@
# Arch AI · 今日任务 · 2026-05-26
## 已完成
- [x] **[P0]** 编写 `docs/01_产品需求/PRD.md` v0.3.0 — 错题本产品需求文档（已锁定）
- [x] **[P0]** 设计 `docs/02_系统架构/` — 总体架构、技术选型、模块设计、数据模型（v0.3.0）
- [x] **[P1]** 将 P01 项目文档从"代码检测"改写为"错题本"
- [x] **[P1]** 更新 ROADMAP.md 任务看板（PRD 完成后分配 Dev 任务）
- [x] **[P0]** 数据质量架构闭环：人机协同修正（ADR-009）
- [x] **[P0]** 决策落地：双题库源、用户树状邀请、数学+英语双学科、Freemium
- [x] **[P0]** 旧架构合并：30 项决策逐项确认，5 份架构文档更新至 v0.4.0
- [x] **[P0]** Phase 1 收尾：ROADMAP/DASHBOARD 更新，Dev 工作台初始化，ADR-010 补充
- [x] **[P0]** Phase 2 启动：8 个 Dev 任务入队，依赖关系图完成
## Phase 1 收尾清单
| 动作 | 状态 |
|------|------|
| ROADMAP Phase 1 → DONE 100% | ✅ |
| ROADMAP Phase 2 → ACTIVE | ✅ |
| DASHBOARD 阶段切换 | ✅ |
| Dev AI queue.md 重写 | ✅ |
| Dev AI today.md 初始化 | ✅ |
| ADR-010 题库抽象层 | ✅ |
## 旧架构合并（30 项决策全部确认）
| # | 决策 | 结论 |
|---|------|------|
| 1 | 题库来源 | 自有 PDF 录入 + 作业帮 API 双源，架构层抽象适配 |
| 2 | AI 能力 | 分层使用：Coze 测试/验证，Claude 架构，其他 AI 做 Coding |
| 3 | 用户体系 | MVP 仅微信登录，邀请码分享形成树状结构 |
| 4 | 商业化 | 基础免费 + 会员，MVP 全免费 |
| 5 | 首发学科 | 数学 + 英语 |
## 明天 (2026-05-27)
1. UI 设计规范迁移（从旧架构迁移到新架构 `docs/02_系统架构/UI设计规范.md`）
2. 测试方案迁移（从旧架构迁移，调整为 Coze 沙盒自动化测试方案）
3. 部署方案重写（三环境 dev/test/prod + Coze 沙盒配置）
4. 根据人类反馈做修订
## 阻塞
（无）
.ai/roles/dev/card.md
+23 -14
View File
@@ -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/
.ai/roles/dev/queue.md
-36
View File
@@ -1,36 +0,0 @@
# Dev AI · 任务队列
## Phase 2 MVP 任务
| # | 任务 ID | 项目 | 描述 | 优先级 | 状态 |
|---|---------|------|------|--------|------|
| 1 | P01-001 | App | 数据库 Schema 实现 + 迁移脚本 | P0 | TODO |
| 2 | P01-002 | App | Auth 模块（微信登录 + JWT） | P0 | TODO |
| 3 | CROSS-001 | 共享 | 共享工具库日期格式 bug 修复 | P0 | TODO |
| 4 | P01-005 | App | Image 模块（图像预处理管线） | P0 | TODO |
| 5 | P01-006 | App | Print 模块（PDF 生成 + S3 + 清理） | P0 | TODO |
| 6 | P01-004 | App | Upload 模块（图片上传 + S3 + 缩略图） | P1 | TODO |
| 7 | P01-003 | App | User 模块（个人资料 CRUD + 邀请链） | P1 | TODO |
| 8 | P01-007 | App | 页面路由 + 基础页面骨架 | P1 | TODO |
## 依赖关系
```
P01-001 (DB Schema)
├─→ P01-002 (Auth) ──→ P01-003 (User) ──→ P01-007 (Pages)
├─→ P01-004 (Upload) ──→ P01-005 (Image)
└─→ P01-006 (Print)
```
- P01-001 是所有模块的前置依赖，优先完成
- P01-002/004 可并行
- P01-005 依赖 P01-004（需要上传的图片 URL 做输入）
- P01-007 最后做，需要在各模块 API 稳定后
## 参考文档
- PRD: `docs/01_产品需求/PRD.md` (v0.4.0)
- 总体架构: `docs/02_系统架构/总体架构.md` (v0.4.0)
- 技术选型: `docs/02_系统架构/技术选型.md` (v0.4.0)
- 模块设计: `docs/02_系统架构/模块设计.md` (v0.4.0)
- 数据模型: `docs/02_系统架构/数据模型.md` (v0.4.0)
.ai/roles/dev/today.md
-29
View File
@@ -1,29 +0,0 @@
# Dev AI · 今日任务 · 2026-05-26
## 状态：Phase 2 MVP 启动
Phase 1（基础搭建）已收尾。PRD v0.4.0 / 系统架构 v0.4.0 / 数据模型 v0.4.0 全部锁定。
## 待领取（按优先级）
| # | 任务 | 优先级 | 说明 |
|---|------|--------|------|
| 1 | P01-001 | P0 | 数据库 Schema 实现 + Drizzle 迁移脚本。参考 [数据模型.md](../../../docs/02_系统架构/数据模型.md) 全部表定义 |
| 2 | P01-002 | P0 | Auth 模块（微信 code2session + JWT 签发 + AuthGuard）。参考 [模块设计.md](../../../docs/02_系统架构/模块设计.md#31-auth-模块) |
| 3 | CROSS-001 | P0 | 共享工具库日期格式 bug 修复 |
| 4 | P01-005 | P0 | Image 模块（Sharp 图像预处理管线：透视校正 + CLAHE 增强 + 笔迹去除）。参考 [模块设计.md](../../../docs/02_系统架构/模块设计.md#36-image-模块图像预处理) |
| 5 | P01-006 | P0 | Print 模块（PDFKit 生成 + S3 上传 + 24h 过期清理）。参考 [模块设计.md](../../../docs/02_系统架构/模块设计.md#37-print-模块pdf-输出p0) |
| 6 | P01-004 | P1 | Upload 模块（图片上传 S3 + 缩略图） |
| 7 | P01-003 | P1 | User 模块（个人信息 CRUD + 邀请码生成 + 邀请链查询） |
| 8 | P01-007 | P1 | 页面路由 + 9 个基础页面骨架（含打印预览页） |
## 关键架构文档
- [数据模型.md](../../../docs/02_系统架构/数据模型.md) — 所有表定义、索引、Drizzle Schema 示例
- [模块设计.md](../../../docs/02_系统架构/模块设计.md) — API 接口、模块结构
- [总体架构.md](../../../docs/02_系统架构/总体架构.md) — 数据流、部署架构
- [技术选型.md](../../../docs/02_系统架构/技术选型.md) — 技术栈版本
## 已完成
（Phase 2 暂无）
.ai/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/)
- 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/
.ai/roles/qa/queue.md
-19
View File
@@ -1,19 +0,0 @@
# QA AI · 任务队列
## 当前阶段 (Phase 1)
暂无测试任务。所有活跃任务处于 TODO 状态。
## 测试流程
1. 确认任务已进入 REVIEW 状态（见 ROADMAP.md）
2. 读取 `review/active/{任务ID}/task.md` — 理解任务
3. 读取 `review/active/{任务ID}/acceptance.md` — 确认验收标准
4. 读取 `review/active/{任务ID}/impact.md` — 了解影响范围
5. 在 `projects/{项目}/tests/` 编写测试
6. 执行测试，生成报告到 `reports/`
7. 提交反馈到 `review/active/{任务ID}/feedback/`
## 已完成的测试
（无）
.ai/roles/qa/today.md
-18
View File
@@ -1,18 +0,0 @@
# QA AI · 今日任务 · 2026-05-25
## 进行中
（无）
## 待执行
当前没有进入 REVIEW 状态的任务，暂无测试任务。
## 已完成
（无）
## 说明
等待 Dev AI 完成代码开发后，任务状态转为 REVIEW 时开始测试工作。
关注 `ROADMAP.md` 中的 DOING 列，当有任务进入 REVIEW 时立即介入。