diff --git a/.ai/knowledge/decisions.md b/.ai/knowledge/decisions.md new file mode 100644 index 0000000..4224e51 --- /dev/null +++ b/.ai/knowledge/decisions.md @@ -0,0 +1,41 @@ +# 架构决策记录 (ADR) + +## ADR-001: 测试驱动 SDK 演进 + +- 日期: 2026-05-27 +- 状态: 已采纳 +- 决策: 寄存器测试是 SDK 的第一用户，测试代码直接演进为 LL 层驱动 +- 理由: bring-up 阶段的核心产出是验证寄存器功能，测试代码天然包含了对寄存器的精确操作逻辑，提炼为 LL 层零浪费 +- 影响: Test/cases/ 的代码质量要求等同于 SDK 代码；每个功能单元的测试代码必须结构化，便于后续提炼 + +## ADR-002: HAL/LL 双层架构，参考 STM32CubeH7 + +- 日期: 2026-05-27 +- 状态: 已采纳 +- 决策: 采用与 STM32CubeH7 一致的 HAL/LL 双层架构，包括句柄模式、弱回调、模块化编译 +- 理由: STM32CubeH7 是经过大规模验证的工业级 SDK 架构，HAL/LL 双层兼顾了可移植性和性能，开发者社区熟悉度高 +- 影响: 驱动代码必须遵循 HAL/LL 分层；HAL 用句柄+状态机+回调，LL 用内联函数直操寄存器；编译体积由 hal_conf.h 宏开关控制 + +## ADR-003: 33 个功能单元分 7 阶段 bring-up + +- 日期: 2026-05-27 +- 状态: 已采纳 +- 决策: 按 bring-up 逻辑将 33 个功能单元分为 P0-P6 七个阶段，P0-P1 串行，P2-P6 可按需并行 +- 理由: 芯片 bring-up 有天然依赖——必须先能跑（P0），才能有调试输出（P1），然后才能测其他外设。但模拟、定时器、存储、高速接口之间没有强依赖，可以并行 +- 影响: 任务编号用 D{阶段号}-{序号}，阶段切换需人类确认 + +## ADR-004: 1 人 + 2 AI 单仓库协作 + +- 日期: 2026-05-27 +- 状态: 已采纳 +- 决策: 采用 1 人 + Arch AI + Worker AI 的协作模式，单仓库，不需要 review 仓库 +- 理由: 嵌入式项目文件数少但精度高，Arch AI 和 Worker AI 在同一仓库操作更直接。测试包含在 Worker AI 职责内，不需要独立 QA AI +- 影响: 去掉 errlens 的 review/ 目录和 QA AI 角色；Worker AI 同时负责开发和测试 + +## ADR-005: Arch AI 角色可由任何 AI 担当 + +- 日期: 2026-05-27 +- 状态: 已采纳 +- 决策: Arch AI 和 Worker AI 不是绑定到某个特定 AI 平台的角色定义，而是职责定义。任何 AI（扣子、Claude Code、DeepSeek 等）读到 card.md 即可担当 +- 理由: 实际使用中不同场景适合不同 AI——架构讨论用扣子对话，代码执行用 Claude Code 终端，快速查询用 DeepSeek CLI。强制绑定单一平台会降低效率 +- 影响: card.md 必须自包含，不假设读它的 AI 有任何前置上下文；AGENTS.md 是通用上下文锚点 diff --git a/.ai/knowledge/lessons.md b/.ai/knowledge/lessons.md new file mode 100644 index 0000000..856be93 --- /dev/null +++ b/.ai/knowledge/lessons.md @@ -0,0 +1,13 @@ +# 经验教训 + +## 目的 + +记录开发过程中学到的东西。每条记录包含： +- 上下文（我们在做什么） +- 问题（出了什么问题/什么让我们意外） +- 教训（学到了什么） +- 行动（因此改变了什么） + +--- + +（暂无经验教训，项目刚启动。随着 bring-up 推进自动积累。） diff --git a/.ai/knowledge/patterns.md b/.ai/knowledge/patterns.md new file mode 100644 index 0000000..69e09af --- /dev/null +++ b/.ai/knowledge/patterns.md @@ -0,0 +1,52 @@ +# 可复用模式 + +## 目的 + +记录开发过程中发现的可持续复用的模式和做法。 + +--- + +## P-001: 测试→LL→HAL 提炼路径 + +**上下文**: 每个功能单元从寄存器测试到最终 SDK 驱动的演进 +**问题**: 测试代码和 SDK 驱动如何衔接，避免重复劳动 +**方案**: 三步提炼路径： +1. **寄存器测试代码** → 直接操作寄存器地址和位域，验证功能正确性 +2. **LL 层提炼** → 将测试中的寄存器操作封装为内联函数+宏，零开销 +3. **HAL 层封装** → 在 LL 层之上加句柄+状态机+回调，高抽象可移植 + +**关键约束**: 测试代码必须结构化（用宏封装寄存器操作，不用硬编码地址），否则提炼成本极高 + +**何时用**: 每个功能单元完成后 +**何时不用**: 纯软件功能（无寄存器操作） + +--- + +## P-002: 勘误驱动规避 + +**上下文**: 芯片 bring-up 中发现的硅缺陷 +**问题**: 如何让 SDK 驱动自动规避已知勘误 +**方案**: +1. 勘误记录在 Test/errata/ 中，结构化格式（影响外设、触发条件、规避方法） +2. LL 层代码中在受影响操作处加 workaround 注释 +3. HAL 层代码中自动执行规避逻辑（对调用方透明） + +**何时用**: 发现勘误后立即记录，LL/HAL 代码同步更新 +**何时不用**: 确认无硅缺陷的功能 + +--- + +## P-003: 跨 AI 上下文交接 + +**上下文**: 不同 AI 可能在不同时间、不同平台介入同一项目 +**问题**: 如何确保任何 AI 随时能接手 +**方案**: +1. AGENTS.md 是通用上下文锚点 +2. dashboard.md 记录当前状态，任何 AI 读到即知全貌 +3. task 文件自包含（输入/输出/约束/验收），不依赖对话历史 +4. Git commit 记录所有变更，Git 是唯一的历史来源 + +**核心原则**: 对话是易失的，文件是持久的。每个判断产生后立即写入文件。 + +**何时用**: 每次 AI 会话 +**何时不用**: 无（这是基础模式，始终适用） diff --git a/.ai/phases/INDEX.md b/.ai/phases/INDEX.md new file mode 100644 index 0000000..8d4ec13 --- /dev/null +++ b/.ai/phases/INDEX.md @@ -0,0 +1,27 @@ +# 阶段索引 + +| 阶段 | 名称 | 功能单元 | 状态 | 目录 | +|------|------|---------|------|------| +| P0 | 基础 bring-up | 电源管理/时钟/NRST复位/GPIO/JTAG_SWD | PLANNED | — | +| P1 | 基本通信 | USART/SPI/I2C | PLANNED | — | +| P2 | 模拟链路 | ADC/DAC/比较器/VREFBUF/温度/参考电压/Scaler启动时间 | PLANNED | — | +| P3 | 定时器类 | Timer/HRTIM/LPTIM/看门狗 | PLANNED | — | +| P4 | 存储搬运 | FMC/QSPI/SDMMC/DMA/DLYB | PLANNED | — | +| P5 | 高速接口 | USB/以太网/SAI/ULPI | PLANNED | — | +| P6 | 杂项 | 电压监控/模拟开关升压/升压器/CRC/电流特性 | PLANNED | — | + +## 阶段执行原则 + +1. **P0必须先完成** — 芯片能跑起来才能测其他 +2. **P1在P0完成后启动** — 需要调试输出和通信通道 +3. **P2-P6可按需并行** — 依赖P1但不互锁 +4. **SDK随阶段推进** — 每个阶段完成后提炼LL/HAL层 + +## 阶段切换规则 + +1. 当前阶段所有功能单元测试通过（或勘误已记录） +2. 人类签字确认 +3. Arch AI 更新本索引文件 +4. Arch AI 更新 dashboard.md（进度条 + task 状态面板 + 最近事件） +5. Arch AI 更新 Worker card.md（当前阶段字段） +6. 产出阶段完成总结 diff --git a/hwd32h757/.ai/principles.md b/.ai/principles.md similarity index 72% rename from hwd32h757/.ai/principles.md rename to .ai/principles.md index eaa102f..dfcc2bf 100644 --- a/hwd32h757/.ai/principles.md +++ b/.ai/principles.md @@ -9,16 +9,16 @@ AI 的上下文窗口有限。每个读入上下文的字都是成本。这套 | 层级 | 预算 | 内容 | 加载时机 | |------|------|------|----------| | 入口（dashboard/card） | < 2K | 身份+全貌+任务 | 每次会话必读 | -| Task 文件 | < 1K | 单任务全部信息 | Coder/Tester 开工时 | +| Task 文件 | < 1K | 单任务全部信息 | Worker 开工时 | | 知识沉淀 (knowledge) | < 3K | 决策/模式/教训 | 按需加载 | | 阶段上下文 (phase) | < 5K | 目标+范围+架构 | 按需加载 | -## 信息分层（三层架构） +## 信息分层 ``` 指挥层: dashboard.md → 人类 + Arch AI 唯一入口 决策层: DECISIONS.md → 待人类决策事项 -执行层: .ai/tasks/active/ → Coder/Tester 各自 task 文件 +执行层: .ai/tasks/active/ → Worker 各自 task 文件 ``` ## 维护规则 @@ -43,13 +43,12 @@ AI 的上下文窗口有限。每个读入上下文的字都是成本。这套 4. **接近窗口上限时主动收尾**：感觉上下文开始吃力时，主动 checkpoint——已完成写入文件、commit、告知人类当前进展和下一步。**宁可多开一个会话，不要带着残缺记忆继续** 5. **拆分到可提交粒度**：大任务拆成独立子任务。每个子任务结束后 git commit，确保即使后续会话压缩，已完成的部分不会丢失 -### 角色特定约束 +### 嵌入式项目特有约束 | 角色 | 主要风险 | 应对策略 | |------|---------|---------| -| Arch AI (Claude Code) | 长对话积累上下文，架构讨论容易收不住 | 每个 ADR 产出后立即写入 decisions.md；感知吃力时主动收尾 | -| Coder AI (Trae + GLM-4.6) | 上下文窗口更小，多文件任务容易超出 | 每个 session 只做 1 个 task 文件；不读其他 task，不读架构文档 | -| Tester AI (Coze CN) | 沙盒执行时间有限 | 1 个 session 只测 1 个 T01-XXX task；报告立即写回 repo | +| Arch AI | 架构讨论容易收不住，寄存器细节容易混淆 | 每个 ADR 产出后立即写入 decisions.md；寄存器定义以 SVD 为准，不靠记忆 | +| Worker AI | 单个外设测试代码可能涉及大量寄存器位域 | 每个 session 只做 1 个 task；测试代码按功能单元独立，不跨单元引用 | ### 信号识别（何时应立即执行规则 4） @@ -57,35 +56,22 @@ AI 的上下文窗口有限。每个读入上下文的字都是成本。这套 - 开始忘记用户几分钟前说过的话 - 回复质量出现可感知的下降 - 同一个问题被重复提出 -- （Coder AI）需要同时修改 3 个以上文件才能完成 task +- 需要同时修改 3 个以上文件才能完成 task ### 反模式 - 「一口气做完再 commit」——做一半触发压缩，前面做的全丢 - 「这个 task 简单，我顺便把下一个也做了」——超边界 = 超上下文 - 「先放着，等会儿一起处理」——对话不等人，放着 = 丢了 +- 「凭记忆写寄存器地址」——嵌入式寄存器地址必须从 SVD/头文件获取，不能靠回忆 --- -## 文件约定 - -- 控制面板: `dashboard.md` -- 决策入口: `DECISIONS.md` -- 角色工作台: `.ai/roles/{role}/card.md` -- 执行任务: `.ai/tasks/active/` -- 阶段上下文: `.ai/phases/phase-NN-name/` -- 知识沉淀: `.ai/knowledge/` -- 提示词模板: `.ai/prompts/{domain}/` -- Skill 工具: `.trae/skills/` -- 框架边界: `SYNC.md` -- 模板变量: `TEMPLATE.yaml` - ## 阶段切换检查清单 切换阶段时 Arch AI 必须： - [ ] 更新所有角色的 card.md（当前阶段字段） - [ ] 更新 dashboard.md（进度条 + task 状态面板 + 最近事件） - [ ] 更新 phases/INDEX.md -- [ ] 生成上一阶段的 completion.md -- [ ] 产出阶段复盘（docs/share/phase-NN/） +- [ ] 产出上一阶段的 completion.md - [ ] 审计 token 预算 diff --git a/.ai/roles/arch/card.md b/.ai/roles/arch/card.md new file mode 100644 index 0000000..b5f0888 --- /dev/null +++ b/.ai/roles/arch/card.md @@ -0,0 +1,48 @@ +# Arch AI — 架构师 + +## 身份 + +我是架构 AI。负责需求分析、架构设计、技术选型、任务拆解、质量审查。 + +**平台**: 不限（扣子/Claude Code/DeepSeek，任何AI均可担当此角色） + +## 启动流程 + +1. 读本文件（card.md）→ 我是谁、权限 +2. 读 `dashboard.md` → 了解项目全貌、当前阶段、任务状态 +3. 按需深入 → `.ai/knowledge/decisions.md`（ADR）、`.ai/phases/`（阶段上下文） +4. 拆解新任务 → 按模板写 `.ai/tasks/active/D{阶段号}-{序号}.md` +5. Worker 完成后 → 审查代码质量、确认测试覆盖、更新 dashboard.md + +## 当前阶段 + +P0: 基础 bring-up（电源/时钟/复位/GPIO/JTAG） + +## 核心交付物 + +- 架构设计文档 (docs/) +- 任务定义 (.ai/tasks/active/) +- 验收标准 (task 文件内) +- ADR (.ai/knowledge/decisions.md) + +## 权限 + +**可写**: docs/ .ai/knowledge/ .ai/tasks/ .ai/phases/ Tools/ +**只读**: Test/ Drivers/HWD32H757_HAL_Driver/ Drivers/BSP/ +**禁止**: .ai/roles/ .ai/principles.md（人类维护） + +## 关键入口 + +| 文件 | 说明 | +|------|------| +| `dashboard.md` | 项目全貌（每次必读） | +| `DECISIONS.md` | 待人类决策事项 | +| `.ai/knowledge/decisions.md` | ADR 全文 | +| `.ai/tasks/active/` | 活跃任务列表 | +| `.ai/tasks/templates/TASK_TEMPLATE.md` | task 格式说明 | + +## 特别注意 + +- 嵌入式项目的架构决策往往影响寄存器层——ADR 必须注明影响哪些功能单元 +- 测试→LL→HAL 的提炼路径是核心模式，拆任务时要体现这个递进关系 +- Arch AI 不是某一个人/AI，任何 AI 读到这份文档都可以担当此角色 diff --git a/.ai/roles/worker/card.md b/.ai/roles/worker/card.md new file mode 100644 index 0000000..8864341 --- /dev/null +++ b/.ai/roles/worker/card.md @@ -0,0 +1,60 @@ +# Worker AI — 执行者 + +## 身份 + +我是执行 AI。负责代码编写、测试执行、文档生成、LL/HAL 驱动提炼。 + +**平台**: 不限（Claude Code/DeepSeek/Codex CLI，任何AI均可担当此角色） + +## 启动流程 + +1. 读本文件（card.md）→ 我是谁、权限 +2. 读 `dashboard.md` → 找到自己对应的 task（状态为 `todo` 的任务） +3. 打开对应 task 文件（如 `.ai/tasks/active/D0-001.md`）→ **这就是你的全部世界** +4. 按 task 文件中的「输入」「输出」「约束」「验收方法」执行 +5. 完成后 → 填写 task 文件的「完成报告」→ commit（message 含 `[DONE]`） + +**不需要**读 ADR 全文、知识库、或其他 task 文件。你的 task 文件已经包含了完成任务所需的全部信息。 + +## 当前阶段 + +P0: 基础 bring-up + +## 核心交付物 + +- 寄存器测试代码 (Test/cases/{unit}/) +- LL 驱动代码 (Drivers/HWD32H757_HAL_Driver/Inc/*_ll_*.h, Src/*_ll_*.c) +- HAL 驱动代码 (Drivers/HWD32H757_HAL_Driver/Inc/*_hal_*.h, Src/*_hal_*.c) +- 勘误记录 (Test/errata/) +- 工具脚本 (Tools/) + +## 核心工作模式：测试→LL→HAL 提炼路径 + +``` +1. 寄存器测试代码 → 直接操作寄存器，验证功能正确性 +2. 测试代码提炼为 LL 层 → 内联函数+宏，零开销 +3. LL 层封装为 HAL 层 → 句柄+状态机+回调，高抽象可移植 +``` + +每次完成一个功能单元的测试后，应主动提出 LL 层提炼建议。 + +## 权限 + +**可写**: Test/ Drivers/HWD32H757_HAL_Driver/ Drivers/BSP/ Drivers/CMSIS/ Tools/ Projects/ +**只读**: docs/ .ai/tasks/active/ dashboard.md DECISIONS.md +**禁止**: .ai/ .ai/roles/ .ai/knowledge/ .ai/phases/ .ai/principles.md + +## 关键入口 + +| 文件 | 说明 | +|------|------| +| `dashboard.md` | 查找自己的 task | +| `.ai/tasks/active/D{阶段号}-{序号}.md` | 你的 task 文件（开工时读这个） | +| `.ai/tasks/templates/TASK_TEMPLATE.md` | task 格式说明 | + +## 特别注意 + +- 寄存器地址和位域定义必须从 SVD 或 CMSIS 头文件获取，不能凭记忆编写 +- 测试代码中必须包含边界条件和异常情况的测试 +- 发现勘误时必须记录到 Test/errata/，并在 LL/HAL 代码中加 workaround +- Worker AI 不是某一个人/AI，任何 AI 读到这份文档都可以担当此角色 diff --git a/.ai/tasks/active/.gitkeep b/.ai/tasks/active/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.ai/tasks/completed/.gitkeep b/.ai/tasks/completed/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.ai/tasks/templates/TASK_TEMPLATE.md b/.ai/tasks/templates/TASK_TEMPLATE.md new file mode 100644 index 0000000..c0a3f98 --- /dev/null +++ b/.ai/tasks/templates/TASK_TEMPLATE.md @@ -0,0 +1,59 @@ +# Task 模板 + +> 所有 task 文件必须遵循此模板，确保自包含、零隐含上下文。 + +--- + +```markdown +# Task {编号}: {标题} + +## 元信息 + +| 字段 | 值 | +|------|-----| +| 状态 | `todo` / `in_progress` / `done` / `verified` / `accepted` | +| 优先级 | P0 / P1 / P2 | +| 依赖 | 上游任务编号（无则写"无"） | +| 分配给 | Worker AI | + +## 输入 + +**要读的文件**: +- `路径` — 简要说明 + +**参考的 ADR**: +- ADR-XXX: 一句话说明关联性 + +**上游依赖产出**: +- 无 / D{X}-{YYY} 产出为 ZZZ + +## 输出 + +**要生成/修改的文件**: +- `路径` — 简要说明 + +**输出格式**: 代码/文档/配置 + +## 约束 + +- 不碰: 列出禁止修改的目录 +- 技术栈: GCC ARM + CMake / Python +- 规范: 编码规范、命名规范 + +## 验收方法 + +```bash +# 具体命令和预期结果 +``` + +## 完成报告 + +> Worker 完成后填写。Commit message 以 `[DONE]` 结尾。 + +- [ ] 输出文件已生成 +- [ ] 验收命令通过 +- [ ] Commit: `{hash}` +- [ ] Commit message: `feat({编号}): 简短描述 [DONE]` +- [ ] 发现的勘误: 无 / 描述 +- [ ] LL提炼建议: 无 / 描述 +``` diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9cc77f2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,26 @@ +# Build +build/ +out/ + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# OS +.DS_Store +Thumbs.db + +# Python +__pycache__/ +*.pyc +.venv/ + +# Binary +*.o +*.elf +*.bin +*.hex +*.map +*.lst diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..29187e3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,111 @@ +# AI 角色定义与权限约定 + +> **如果你是 AI，请直接跳转到你的角色入口：** +> - Arch AI → `dashboard.md` 全文 +> - Worker AI → `.ai/roles/worker/card.md` → 对应 `.ai/tasks/active/` 任务文件 +> +> **如果你是人类**，请看 `dashboard.md` 顶部「人类区」。 +> +> 本文档是权限矩阵的**唯一权威参考**。角色工作台中的权限描述为摘要，如有冲突以本文档为准。 + +--- + +## 团队架构 + +`1 人类 + 2 AI` 协作模式： +- **Arch AI** — 需求分析、架构设计、技术选型、任务分解、质量审查、勘误决策 +- **Worker AI** — 代码编写、测试执行、文档生成、LL/HAL 驱动提炼 +- **人类** — 需求输入、最终决策、硬件验证、成果验收 + +**核心理念**：测试驱动 SDK 演进。寄存器测试是 SDK 的第一用户，测试代码直接提炼为 LL 层驱动。 + +--- + +## 工作流 + +``` +需求分析(Arch) → 架构设计(Arch) → 任务拆解(Arch) + → 开发实现(Worker) → 自测(Worker) → 人类硬件验证 + → 勘误记录(Worker) → LL提炼(Worker) → HAL封装(Worker) + ↑ + Bug修复(Worker, 最多3轮) +``` + +缺陷修复循环：最多 3 轮。第 3 轮仍有 BLOCKER → 升级给人类 + Arch AI 裁决。 + +--- + +## 角色职责 + +### Arch AI +- 可写：架构文档、验收标准、任务定义、知识库、共享资源、开发工具、SDK 设计文档 +- 只读：测试代码、测试报告、勘误详情 +- 指导 Worker AI 工作，分配任务队列，审查产出质量 + +### Worker AI +- 可写：业务代码、测试代码、测试报告、技术文档、开发工具、勘误记录、LL/HAL 驱动代码 +- 只读：AI 配置、任务定义（不可修改 task 内容） +- 禁止：.ai/ 目录结构修改、dashboard.md 修改 + +### 人类 +- 全部权限，但主要行使：需求定义、架构决策、硬件验证、成果验收 + +--- + +## 目录权限矩阵 + +> 图例：`-` = 禁止 `R` = 只读 `W` = 可写（含读） `RW` = 读写 + +| 目录路径 | Arch AI | Worker AI | 人类 | +|---------|---------|-----------|------| +| `.ai/` | `R` | `-` | `RW` | +| `dashboard.md` | `RW` | `R` | `RW` | +| `DECISIONS.md` | `RW` | `R` | `RW` | +| `Drivers/CMSIS/` | `RW` | `RW` | `RW` | +| `Drivers/HWD32H757_HAL_Driver/` | `R` | `RW` | `RW` | +| `Drivers/BSP/` | `R` | `RW` | `RW` | +| `Test/` | `R` | `RW` | `RW` | +| `Test/errata/` | `RW` | `RW` | `RW` | +| `Tools/` | `RW` | `RW` | `RW` | +| `docs/` | `RW` | `RW` | `R` | +| `Projects/` | `R` | `RW` | `RW` | + +优先级：`forbidden > read_only > allowed`。未出现在表中的路径默认禁止所有 AI。 + +--- + +## 命名规范 + +### 任务编号 +- 开发任务：`D{阶段号}-{序号}`，如 `D0-001`（P0阶段第1个任务） +- 测试任务：`T{阶段号}-{序号}`，如 `T0-001` + +### 分支命名 +``` +feature/D0-001-short-desc +bugfix/D0-001-short-desc +test/T0-001-short-desc +``` + +### 提交信息 +``` +feat(D0-001): 简短描述 +fix(D0-001): 简短描述 +docs(D0-001): 简短描述 +test(D0-001): 简短描述 +errata: GPIOx_BSRR 写入偶发失效 (D0-003) +``` + +--- + +## AI 配置文件索引 + +| 文件 | 说明 | +|------|------| +| `.ai/principles.md` | 设计原则 + 上下文管理规则 | +| `.ai/roles/{arch,worker}/card.md` | AI 角色身份卡 | +| `.ai/phases/INDEX.md` | 阶段索引 + 切换规则 | +| `.ai/knowledge/decisions.md` | 架构决策记录 (ADR) | +| `.ai/knowledge/lessons.md` | 经验教训 | +| `.ai/knowledge/patterns.md` | 可复用模式 | +| `.ai/tasks/templates/` | Task 模板 | diff --git a/hwd32h757/DECISIONS.md b/DECISIONS.md similarity index 90% rename from hwd32h757/DECISIONS.md rename to DECISIONS.md index 8bce381..d391d89 100644 --- a/hwd32h757/DECISIONS.md +++ b/DECISIONS.md @@ -5,11 +5,9 @@ --- ---- - ## 已决策 -（暂无） +（暂无已决策事项） --- diff --git a/Drivers/BSP/.gitkeep b/Drivers/BSP/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Drivers/CMSIS/Core/.gitkeep b/Drivers/CMSIS/Core/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Drivers/CMSIS/Device/HWD/hwd32h757/Include/.gitkeep b/Drivers/CMSIS/Device/HWD/hwd32h757/Include/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Drivers/CMSIS/Device/HWD/hwd32h757/Source/.gitkeep b/Drivers/CMSIS/Device/HWD/hwd32h757/Source/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Drivers/HWD32H757_HAL_Driver/Inc/.gitkeep b/Drivers/HWD32H757_HAL_Driver/Inc/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Drivers/HWD32H757_HAL_Driver/Src/.gitkeep b/Drivers/HWD32H757_HAL_Driver/Src/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/ENVIRONMENT.md b/ENVIRONMENT.md new file mode 100644 index 0000000..bfc8f1a --- /dev/null +++ b/ENVIRONMENT.md @@ -0,0 +1,48 @@ +# hwd32h757 开发环境配置 + +## 芯片信息 + +| 项目 | 值 | +|------|-----| +| 芯片代号 | hwd32h757 | +| 内核 | Cortex-M7 | +| 参考架构 | STM32H7系列 | +| SDK框架 | HAL/LL双层（参考STM32CubeH7） | + +## 前置依赖 + +| 工具 | 版本要求 | 说明 | +|------|---------|------| +| GCC ARM | >= 13.x | 交叉编译器 | +| CMake | >= 3.20 | 构建系统 | +| Python | >= 3.10 | 工具脚本（SVD解析、测试报告） | +| OpenOCD / J-Link | — | 烧录调试 | +| Git | >= 2.40 | 版本控制 | + +## 开发工具 + +- **IDE**: VS Code + Cortex-Debug + CMake Tools +- **AI协作**: 1人 + Arch AI + Worker AI +- **上下文同步**: AGENTS.md + dashboard.md（任何AI读到即可接手） + +## 硬件环境 + +- **评估板**: HWD32H757-EVAL +- **调试器**: J-Link / ST-Link（SWD接口） +- **串口**: USB-UART（调试输出） + +## 快速开始 + +```bash +# 1. 克隆项目 +git clone https://gitcode.com/tupingr/ai_soc_sw.git +cd ai_soc_sw + +# 2. 构建 +mkdir build && cd build +cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/arm-gcc-toolchain.cmake +make + +# 3. 烧录 +openocd -f interface/jlink.cfg -f target/hwd32h757.cfg -c "program build/Test/cases/gpio/gpio_test.elf verify reset exit" +``` diff --git a/Projects/HWD32H757-EVAL/Applications/.gitkeep b/Projects/HWD32H757-EVAL/Applications/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Projects/HWD32H757-EVAL/Examples/.gitkeep b/Projects/HWD32H757-EVAL/Examples/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/README.md b/README.md new file mode 100644 index 0000000..cd0833f --- /dev/null +++ b/README.md @@ -0,0 +1,53 @@ +# ai_soc_sw + +hwd32h757 MCU 芯片成片测试及 SDK 开发项目。 + +## 项目信息 + +| 项目 | 值 | +|------|-----| +| 芯片代号 | hwd32h757 | +| 内核 | Cortex-M7 | +| 项目阶段 | Chip bring-up（回片测试） | +| 仓库 | https://gitcode.com/tupingr/ai_soc_sw.git | + +## 核心产出 + +1. **寄存器功能测试** — 33 个功能单元的全面扫描 +2. **SDK 框架** — HAL/LL 双层驱动（参考 STM32CubeH7） +3. **勘误记录** — 结构化硅缺陷追踪 + +## 协作模式 + +1 人 + Arch AI + Worker AI，详见 [AGENTS.md](AGENTS.md)。 + +## 目录结构 + +``` +ai_soc_sw/ +├── AGENTS.md # AI 角色定义与权限约定 +├── dashboard.md # 项目控制面板 +├── DECISIONS.md # 待决策事项 +├── ENVIRONMENT.md # 开发环境配置 +├── .ai/ # AI 协作核心 +│ ├── principles.md # 设计原则 +│ ├── roles/ # AI 角色身份卡 +│ ├── tasks/ # 任务文件 +│ ├── phases/ # 阶段上下文 +│ └── knowledge/ # 知识沉淀（ADR/教训/模式） +├── Drivers/ # SDK 驱动层 +│ ├── CMSIS/ # ARM CMSIS + 设备文件 +│ ├── HWD32H757_HAL_Driver/ # HAL + LL 驱动 +│ └── BSP/ # 板级支持包 +├── Test/ # 寄存器测试 +│ ├── framework/ # 测试框架 +│ ├── cases/ # 33 个功能单元 +│ └── errata/ # 勘误记录 +├── Tools/ # 自动化工具 +├── docs/ # 项目文档 +└── Projects/ # 示例工程 +``` + +## 快速开始 + +见 [ENVIRONMENT.md](ENVIRONMENT.md)。 diff --git a/Test/cases/adc/.gitkeep b/Test/cases/adc/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/analog_switch/.gitkeep b/Test/cases/analog_switch/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/boost_converter/.gitkeep b/Test/cases/boost_converter/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/boost_regulator/.gitkeep b/Test/cases/boost_regulator/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/clock/.gitkeep b/Test/cases/clock/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/comparator/.gitkeep b/Test/cases/comparator/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/crc/.gitkeep b/Test/cases/crc/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/current_char/.gitkeep b/Test/cases/current_char/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/dac/.gitkeep b/Test/cases/dac/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/dlyb/.gitkeep b/Test/cases/dlyb/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/dma/.gitkeep b/Test/cases/dma/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/ethernet/.gitkeep b/Test/cases/ethernet/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/fmc/.gitkeep b/Test/cases/fmc/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/gpio/.gitkeep b/Test/cases/gpio/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/hrtim/.gitkeep b/Test/cases/hrtim/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/i2c/.gitkeep b/Test/cases/i2c/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/jtag_swd/.gitkeep b/Test/cases/jtag_swd/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/lptim/.gitkeep b/Test/cases/lptim/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/nrst_reset/.gitkeep b/Test/cases/nrst_reset/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/power_mgmt/.gitkeep b/Test/cases/power_mgmt/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/qspi/.gitkeep b/Test/cases/qspi/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/sai/.gitkeep b/Test/cases/sai/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/scaler_startup/.gitkeep b/Test/cases/scaler_startup/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/sdmmc/.gitkeep b/Test/cases/sdmmc/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/spi/.gitkeep b/Test/cases/spi/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/temperature/.gitkeep b/Test/cases/temperature/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/timer/.gitkeep b/Test/cases/timer/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/ulpi/.gitkeep b/Test/cases/ulpi/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/usart/.gitkeep b/Test/cases/usart/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/usb/.gitkeep b/Test/cases/usb/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/voltage_monitor/.gitkeep b/Test/cases/voltage_monitor/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/vrefbuf/.gitkeep b/Test/cases/vrefbuf/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/cases/watchdog/.gitkeep b/Test/cases/watchdog/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/errata/.gitkeep b/Test/errata/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Test/framework/.gitkeep b/Test/framework/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/Tools/.gitkeep b/Tools/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/dashboard.md b/dashboard.md new file mode 100644 index 0000000..0baa1c3 --- /dev/null +++ b/dashboard.md @@ -0,0 +1,97 @@ +# hwd32h757 项目控制面板 + +> 唯一真实来源。人类看顶部，Arch AI 看全文，Worker AI 看 task 文件。 + +--- + +## 人类区 + +**芯片回片测试阶段** · 进度 0% + +| 阶段 | 功能单元 | 状态 | 进度 | +|------|---------|------|------| +| P0 | 电源管理/时钟/复位/GPIO/JTAG | 未开始 | 0% | +| P1 | USART/SPI/I2C | 未开始 | 0% | +| P2 | ADC/DAC/比较器/VREFBUF/温度/参考电压/Scaler | 未开始 | 0% | +| P3 | Timer/HRTIM/LPTIM/看门狗 | 未开始 | 0% | +| P4 | FMC/QSPI/SDMMC/DMA/DLYB | 未开始 | 0% | +| P5 | USB/以太网/SAI/ULPI | 未开始 | 0% | +| P6 | 电压监控/模拟开关升压/升压器/CRC/电流特性 | 未开始 | 0% | +| SDK | CMSIS→LL→HAL→BSP→示例 | 未开始 | 0% | + +### 需要你决策 + +当前无待决策事项。 + +--- + +## Arch AI 区 + +### ADR 摘要索引 + +| ADR | 一句话 | 状态 | +|-----|--------|------| +| 001 | 测试驱动SDK演进：寄存器测试→LL→HAL | ✅ | +| 002 | HAL/LL双层架构，参考STM32CubeH7 | ✅ | +| 003 | 33个功能单元分7阶段(P0-P6)bring-up | ✅ | + +### Task 状态面板 + +**当前无活跃任务。Arch AI 根据 bring-up 进度拆解任务。** + +**状态流转**: `todo → in_progress → done → verified → accepted` +**交接信号**: Worker 完成 → commit message 包含 `[DONE]` → 人类硬件验证 → `[VERIFIED]` + +### 依赖关系 + +``` +P0 (电源/时钟/复位/GPIO/JTAG) ← 能跑起来的最低要求 + └→ P1 (USART/SPI/I2C) ← 有了调试输出和基本通信 + └→ P2 (模拟链路) + └→ P3 (定时器类) + └→ P4 (存储和搬运) + └→ P5 (高速接口) +P6 (杂项) ← 可与P2-P5并行 +SDK ← P0完成后开始CMSIS，每个阶段完成后提炼LL/HAL +``` + +### 阻塞/风险 + +| 级别 | 描述 | 影响 | +|------|------|------| +| — | 暂无 | — | + +--- + +## 关键文档入口 + +| 想查什么 | 路径 | +|----------|------| +| SDK架构参考 | `docs/sdk_design.md` | +| 测试指南 | `docs/test_guide.md` | +| 迁移指南 | `docs/porting_guide.md` | +| ADR全文 | `.ai/knowledge/decisions.md` | +| 经验教训 | `.ai/knowledge/lessons.md` | +| 可复用模式 | `.ai/knowledge/patterns.md` | +| 待人类决策 | `DECISIONS.md` | +| 勘误记录 | `Test/errata/` | + +--- + +## 角色入口 + +| 角色 | 说明 | 入口 | +|------|------|------| +| 人类 | — | 本文件顶部「人类区」 | +| Arch AI | 任何AI均可担当 | 本文件全文 | +| Worker AI | 任何AI均可担当 | `.ai/roles/worker/card.md` → 对应 task 文件 | + +--- + +## 最近事件 + +| 日期 | 事件 | +|------|------| +| 2026-05-27 | 项目初始化，目录结构搭建 | + +*Arch AI 维护。阶段切换时更新。* diff --git a/docs/.gitkeep b/docs/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/hwd32h757/.ai/config/architect.json b/hwd32h757/.ai/config/architect.json deleted file mode 100644 index c9bda53..0000000 --- a/hwd32h757/.ai/config/architect.json +++ /dev/null @@ -1,38 +0,0 @@ -{ - "name": "Arch AI", - "role": "架构设计师", - "description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。", - "responsibilities": [ - "需求分析和产品规划", - "系统架构设计", - "技术选型和评估", - "跨模块协调和集成", - "编写架构文档", - "定义验收标准", - "评估变更影响", - "维护共享资源", - "指导 Dev AI 和 QA AI 工作" - ], - "allowed_paths": [ - "docs/", - "shared/", - "projects/*/src/", - "projects/*/docs/", - "review/*/acceptance.md", - "review/*/impact.md", - "review/*/task.md", - "tools/", - "data/" - ], - "read_only_paths": [ - ".ai/", - "projects/*/tests/", - "reports/", - "review/*/feedback/" - ], - "forbidden_paths": [], - "prompt_templates": { - "architecture": ".ai/prompts/architecture/", - "documentation": ".ai/prompts/architecture/" - } -} diff --git a/hwd32h757/.ai/config/coder.json b/hwd32h757/.ai/config/coder.json deleted file mode 100644 index ea52033..0000000 --- a/hwd32h757/.ai/config/coder.json +++ /dev/null @@ -1,37 +0,0 @@ -{ - "name": "Dev AI", - "role": "代码开发者", - "description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。", - "responsibilities": [ - "编写业务代码", - "生成技术文档", - "维护项目级文档", - "维护开发工具", - "维护训练数据", - "定义验收标准", - "评估变更影响", - "维护共享资源" - ], - "allowed_paths": [ - "projects/*/src/", - "projects/*/docs/", - "docs/", - "tools/", - "data/", - "shared/", - "review/*/acceptance.md", - "review/*/impact.md" - ], - "read_only_paths": [ - "review/*/task.md", - "review/*/feedback/" - ], - "forbidden_paths": [ - "projects/*/tests/", - "reports/" - ], - "prompt_templates": { - "coding": ".ai/prompts/coding/", - "documentation": ".ai/prompts/coding/" - } -} \ No newline at end of file diff --git a/hwd32h757/.ai/config/tester.json b/hwd32h757/.ai/config/tester.json deleted file mode 100644 index b231318..0000000 --- a/hwd32h757/.ai/config/tester.json +++ /dev/null @@ -1,33 +0,0 @@ -{ - "name": "QA AI", - "role": "测试工程师", - "description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。", - "responsibilities": [ - "编写测试用例", - "执行测试", - "生成测试报告", - "提供反馈" - ], - "allowed_paths": [ - "projects/*/tests/", - "reports/", - "review/*/acceptance.md", - "review/*/feedback/" - ], - "read_only_paths": [ - "projects/*/src/", - "projects/*/docs/", - "docs/", - "data/", - "shared/", - "review/*/task.md" - ], - "forbidden_paths": [ - ".ai/", - "tools/", - "review/*/impact.md" - ], - "prompt_templates": { - "testing": ".ai/prompts/testing/" - } -} \ No newline at end of file diff --git a/hwd32h757/.ai/config/workflow.json b/hwd32h757/.ai/config/workflow.json deleted file mode 100644 index e61ceb5..0000000 --- a/hwd32h757/.ai/config/workflow.json +++ /dev/null @@ -1,48 +0,0 @@ -{ - "workflow": "human-ai-collaboration", - "roles": ["human", "arch-ai", "dev-ai", "qa-ai"], - "stages": [ - { - "name": "需求分析", - "actor": "arch-ai", - "output": ["docs/01_产品需求/PRD.md", "review/{task_id}/task.md"] - }, - { - "name": "架构设计", - "actor": "arch-ai", - "input": ["docs/01_产品需求/PRD.md", "review/{task_id}/task.md"], - "output": ["docs/02_系统架构/", "review/{task_id}/impact.md", "review/{task_id}/acceptance.md"] - }, - { - "name": "开发实现", - "actor": "dev-ai", - "input": ["review/{task_id}/task.md", "review/{task_id}/acceptance.md"], - "output": ["projects/*/src/", "projects/*/docs/"] - }, - { - "name": "测试验证", - "actor": "qa-ai", - "input": ["review/{task_id}/task.md", "review/{task_id}/acceptance.md"], - "output": ["projects/*/tests/", "reports/test-results/", "review/{task_id}/feedback/round{round}.md"] - }, - { - "name": "验收确认", - "actor": "human", - "input": ["review/{task_id}/feedback/", "reports/test-results/"] - } - ], - "retry": { - "max_rounds": 3, - "loop": ["测试验证", "开发实现"], - "escalation": { - "trigger": "第 3 轮测试仍有 BLOCKER 或 HIGH 级别 Bug", - "action": "暂停任务流转，等待人类负责人裁决" - }, - "skip_acceptance_on_retry": true - }, - "ci_triggers": { - "on_push_to_main": ["run-tests", "generate-reports"], - "on_pr_open": ["run-tests", "code-review"], - "on_task_update": ["notify-qa-ai"] - } -} diff --git a/hwd32h757/.ai/knowledge/lessons.md b/hwd32h757/.ai/knowledge/lessons.md deleted file mode 100644 index 2413986..0000000 --- a/hwd32h757/.ai/knowledge/lessons.md +++ /dev/null @@ -1,111 +0,0 @@ -# 经验教训 - -## 目的 - -记录开发过程中学到的东西。每条记录包含： -- 上下文（我们在做什么） -- 问题（出了什么问题/什么让我们意外） -- 教训（学到了什么） -- 行动（因此改变了什么） - ---- - -## L-001: 单体 AGENTS.md 浪费 AI 上下文 - -**日期**: 2026-05-25 -**上下文**: 项目启动阶段，每次 AI 会话都需要读 AGENTS.md 来了解角色和权限 -**问题**: AGENTS.md 239 行，约 80% 内容与当前 AI 角色无关。AI 有效上下文被大量无关信息占据 -**教训**: 为人类设计的文档结构不适用于 AI 的信息获取模式。AI 需要"最少必要信息"，而不是"全局完整视图" -**行动**: 重构为分层信息架构：角色工作台 → 阶段上下文 → 知识沉淀。AI 只需读 2 个小文件即可开工 - ---- - -## L-002: 角色边界划分是 AI Agent 协作的反模式 - -**日期**: 2026-05-26 -**上下文**: Phase 1 收尾后，重新审视「1 人 + 3 AI」的 Arch/Dev/QA 角色划分架构。调研了 2025-2026 年业界最新实践（MegaAgent、Claude Code Agent Swarm、Devin、JiuwenSwarm、Microsoft 多 Agent 参考架构等） -**问题**: -- 按角色边界（Arch/Dev/QA）划分 Agent 导致协调成本急剧上升，Token 消耗是单体的 3-10 倍 -- Arch AI 承担了过多职责：架构设计 + 任务分配 + 文档维护 + 看板更新，成为单点瓶颈 -- `.ai/` 目录膨胀到 47 个文件，但 Phase 2 代码一行还没写——架构本身成了负担 -- Anthropic 和 Cognition（Devin）都承认：并行 Agent 在编码领域的实际收益有限，隐性决策冲突和整合成本往往超过并行收益 -**教训**: -1. **按业务上下文划分，而非按角色划分**。正确的做法是「用户认证流 Agent」拥有路由+数据库+前端组件，「芯片验证流 Agent」拥有数据采集+仿真+结果分析——每个 Agent 拥有完成任务所需的全部上下文 -2. **架构规模应与项目阶段匹配**。Phase 1 只有需求+设计，不需要 47 个配置文件。应该在需要时渐进式添加，而非提前搭建「完整」架构 -3. **调度层应该是确定性代码，而非 LLM**。用 LLM 做任务路由和状态更新是反模式——不稳定、成本高。这些应该用脚本/CI/工作流引擎实现 -4. **子 Agent 的甜蜜点是只读研究，而非并行编码**。隔离上下文中做信息收集然后压缩回传——这是验证最有效的模式 -5. **「高模型指挥小模型」的方向是对的，但规模要匹配**。1 人项目的「编排层」就是人类+Claude Code 本身，不需要额外的编排 Agent -**行动**: -- 启动 `.ai/` 配置精简审计，目标砍到 20 个文件以内 -- Arch AI 的 today.md 和 queue.md 合并，消除重复 -- Phase 3 前评估是否引入正式模型分层（Opus 做判断 → Sonnet/Haiku 做执行） -- 当前阶段保留角色划分但降低形式化程度，实际工作由 Claude Code 子 Agent 机制承载 - ---- - -## L-003: 知识库「生产者」流程缺失 - -**日期**: 2026-05-26 -**上下文**: 一次关于 Agent 架构的深度讨论产生了有价值的洞察（L-002 + ADR-011 + P-004），但发现把这些洞察写入知识库的动作没有 formalized 流程 -**问题**: `share-context` Skill 覆盖了知识库的「消费者」侧（.ai/knowledge/ → docs/share/），但「生产者」侧（开发讨论 → .ai/knowledge/）是断的。有价值的想法和教训可能因为没人记得写而丢失 -**教训**: 一条完整的信息流水线需要两端都 formalized：摄入端（什么时候写、写到哪里、怎么写）和输出端（什么时候翻译、翻译成什么）。目前只有输出端 -**行动**: -- 更新 `share-context` Skill，增加「反向检查」步骤：每次执行时先检查是否有未入库的讨论/想法 -- 建立触发条件：当讨论产生「可复用的判断」「反直觉的发现」「被验证的错误方向」时，主动记录 - ---- - -## L-005: Arch AI 上下文窗口是硬约束——盲目冲刺 = 带残缺记忆做决策 - -**日期**: 2026-05-26 -**上下文**: 持续数小时的高强度架构讨论（ADR-011、ADR-012、信息架构升级），Arch AI 的上下文窗口承载了全部对话历史 -**问题**: 复杂任务容易让人想「一口气做完」，但 Arch AI 的上下文窗口有限。做一半触发自动压缩 → 前面的讨论、决策细节、已排除的选项全部丢失 → 后续判断基于不完整记忆 → 决策质量崩盘 -**教训**: -1. **上下文不是无限的**。每次对话都是消耗品，越长的讨论越容易触发压缩 -2. **决策即记录**。每个判断产生后立即写入 knowledge/，不留在对话里。对话是易失的，文件是持久的 -3. **主动 checkpoint 优于被动压缩**。感觉吃力时主动收尾（commit + push），开新会话继续——带着干净记忆比带着残缺记忆强 -4. **拆分到可提交粒度**。大任务拆成独立子任务，每个子任务结束后 commit。即使后续会话压缩，已完成的部分已经落地 -**行动**: -- 写入 `.ai/principles.md` 作为 Arch AI 硬约束 -- 任务前评估上下文余量 -- 接近窗口上限时执行主动收尾协议：已完成 → commit → 告知人类进展 → 建议开新会话 - ---- - -## L-006: 当 AI 是执行者时，Skill 优于 Shell 脚本 - -**日期**: 2026-05-26 -**上下文**: ADR-008 的「双分支 + sync-template.sh」模板同步方案，在新架构升级后 ai_project 分支严重过时。用户要求把脱敏模板价值提取到 main，放弃独立分支 -**问题**: -- `sync-template.sh` 硬编码了旧架构的文件列表（DASHBOARD.md / ROADMAP.md / today.md / queue.md），框架一升级脚本就过时 -- 维护一个独立 Git 分支的成本 > 收益：需要手动切换分支、跑脚本、处理冲突 -- Shell 脚本的设计假设是「人类或 CI 执行」，但实际场景是 AI 执行。AI 不需要可执行脚本——AI 需要清晰的规格 -**教训**: -1. **「用什么执行」决定「用什么描述」**。人/CI 执行 → 写脚本。AI 执行 → 写 Skill（语义描述 + 约束 + 边界定义）。Skill 描述「方法」，不会因文件路径变化而过时 -2. **边界定义文件是长期资产，执行脚本是短期负债**。SYNC.md 定义了什么属于框架、什么属于项目——这个定义独立于任何执行方式。脚本绑定了执行方式，框架一变就废 -3. **让 Git 做版本管理，让 Skill 做逻辑执行**。不需要为「脱敏」这个逻辑维护一个独立分支，Skill 从当前 main 实时执行脱敏，永远不过时 -4. **3 文件 > 4 文件 + 1 分支**。新方案：SYNC.md + TEMPLATE.yaml + Skill。旧方案：SYNC.md + TEMPLATE.yaml + sync-template.sh + init.sh + ai_project 分支 -**行动**: -- ADR-008 标记废弃，新增 ADR-013 -- 废弃 sync-template.sh、init.sh、ai_project 分支 -- 保留并更新 SYNC.md（框架/项目边界），新增 TEMPLATE.yaml（变量定义），新增 project-init Skill - ---- - -## L-004: 跨平台 AI 协作下，文档是唯一的通信协议 - -**日期**: 2026-05-26 -**上下文**: 澄清了实际的三平台配置——Arch AI (Claude Code + DeepSeek V4 Pro)、Coder AI (Trae CN + GLM-4.6)、Tester AI (Coze CN)。之前的设计假设所有角色在同一个 AI 平台内切换，这一假设被推翻 -**问题**: -- 之前的架构分析得出了「精简文档」的结论（ADR-011），但这个结论基于错误的前提——以为所有 AI 共享同一个上下文空间 -- 实际场景中，三个平台的 AI 之间**零共享上下文**。Trae + GLM-4.6 不会知道 Claude Code 里讨论了什么，Coze 沙盒不会知道架构设计的动机 -- 如果把文档精简了，Coder AI 拿到的 task 就会缺失关键上下文，GLM-4.6 又没有能力自行推断 -**教训**: -1. **架构结论绑定于部署拓扑**。同一个设计，在「单平台多角色切换」和「跨平台多 Agent 协作」下是完全不同的东西。先搞清楚运行环境，再做架构决策 -2. **跨平台协作中，Git 仓库不是存储，是通信介质**。每个 commit 是一次消息传递，每个文件是一份消息体。消息必须自包含，接收方不能依赖「上次聊过」 -3. **任务交接密度必须适配接收方模型能力**。GLM-4.6 不是 Claude——不能给一个需要跨 5 个文件推理的任务。每个 task 应该是单文件或强内聚的 2-3 个文件 -4. **低能力模型不是劣势，是约束**。只能处理小范围任务 → 强迫架构设计更清晰 → 反而减少 bug。这就是「限制产生创造力」 -**行动**: -- 修正 ADR-011 的结论：不做精简，改为「重定位」——架构文档从内部备忘录升级为跨平台交接协议（ADR-012） -- Task 模板增加四个必填字段：输入、输出、约束、参考 ADR -- Dev queue.md 的每个任务需独立可读，不依赖前后文 diff --git a/hwd32h757/.ai/knowledge/patterns.md b/hwd32h757/.ai/knowledge/patterns.md deleted file mode 100644 index 29b7b83..0000000 --- a/hwd32h757/.ai/knowledge/patterns.md +++ /dev/null @@ -1,142 +0,0 @@ -# 可复用模式 - -## 目的 - -记录开发过程中发现的可持续复用的模式和做法。 -同样的模式出现 3 次以上时，应当记录在这里。 - ---- - -## P-001: AI 任务交接 (review/active/) - -**上下文**: AI 角色之间需要传递工作成果 -**问题**: 如何结构化任务交接，让任何 AI 都能接手 -**方案**: 标准化 `review/active/{任务ID}/` 结构： -- `task.md` — 任务描述（Arch AI 定义） -- `acceptance.md` — 验收标准（Arch AI + Dev AI + QA AI 共同维护） -- `impact.md` — 变更影响范围（Arch AI + Dev AI 评估） -- `feedback/` — 反馈记录（QA AI 提交） - -**何时用**: 每个跨 AI 角色的任务 -**何时不用**: 单角色任务（如纯文档更新、配置修改） - ---- - -## P-002: 角色工作台 (daily task board) - -**上下文**: AI 每次会话需要快速进入工作状态 -**问题**: 从头探索项目结构浪费时间 -**方案**: `.ai/roles/{role}/today.md` 每日任务清单，AI 只需读 2 个文件（card + today） -**何时用**: 每次 AI 会话 -**维护者**: Arch AI 负责分配，各 AI 自己更新完成状态 - ---- - ---- - -## P-003: 模板同步 (framework sync) - -**上下文**: 项目框架层（AGENTS/权限/提示词/工作流）的变化需要传播到通用模板分支 -**问题**: 手动同步耗时且容易遗漏，AI 重做去敏化消耗 ~100K tokens -**方案**: -- 双分支：`main`（具体项目）+ `ai_project`（通用模板） -- `SYNC.md` 明确定义框架层/项目层文件边界 -- `sync-template.sh` 自动 checkout 框架文件 + 重新应用 {{变量}} -- 框架层 ~15 个文件自动同步，project 层永久隔离 -**何时用**: main 分支框架有变化时 -**维护者**: Arch AI 触发，脚本执行 - ---- - -## P-004: 编排器-执行者模式 (Orchestrator-Worker) - -**上下文**: AI Agent 协作中，不同任务需要不同能力的模型。高能力模型（Opus）做规划和判断，低成本模型（Sonnet/Haiku）做执行 -**来源**: MegaAgent (NUS)、Claude Code Agent Swarm (Anthropic)、JiuwenSwarm (华为 openJiuwen)、Microsoft 多 Agent 参考架构 -**方案**: - -``` -决策层 (Opus) → 意图理解、方案设计、最终验收 (~10% Token, 最贵) -调度层 (代码) → 任务路由、负载均衡、重试熔断 (确定性代码, 不用 LLM!) -执行层 (Haiku) → 专注单一原子任务 (~60% Token, 最便宜) -``` - -**核心原则**: -1. 按业务上下文划分 Agent（「认证流 Agent」），而非按角色（「数据库 Agent」） -2. 调度层是确定性代码——用 LLM 做调度是反模式 -3. 子 Agent 的甜蜜点是只读研究/探索，并行编码效果不佳 -4. 写范围严格分离——并发写任务之间不能有重叠的文件所有权 -5. Agent 粒度围绕内聚能力组织——不要为「调用一个 API」建 Agent - -**何时用**: -- 团队规模 ≥ 3 个 AI Agent 并行工作 -- 任务可清晰分解为独立子任务，且协调成本 < 并行收益 -- 有明确的模型成本优化需求 - -**何时不用**: -- 1 人项目——编排层就是人类 + Claude Code 本身 -- 编码任务的并行化——行业共识是效果不佳 -- 简单 bug 修复——分解成本 > 直接修复成本 - -**本项目实例** (SoC_SW): - -``` -Arch AI: Claude Code + DeepSeek V4 Pro → 架构推理、方案设计、任务分解 -Coder AI: Trae CN + GLM-4.6 → 代码生成、文件操作（单文件粒度） -Tester AI: Coze CN → 沙盒执行、自动化测试报告 - -通信介质: Git 仓库（唯一集成总线） -交接粒度: 单次 commit = 一个交接单元 -``` - -**关键适配**: -- Coder AI 用的是 GLM-4.6，不能假设它有跨文件推理能力 → task 分解到单文件粒度 -- 跨模块协调在 Arch AI 设计阶段完成，不在 Coder AI 执行阶段 -- Tester AI 的 Coze 沙盒做真正的自动化闭环——不只是跑测试，是拉代码 → 执行 → 生成报告 → commit - ---- - -## P-005: 跨平台任务交接协议 (Cross-Platform Task Handoff) - -**上下文**: 多个 AI Agent 运行在不同平台/IDE 上，零共享上下文，Git 是唯一通信介质 -**问题**: 如何让 Trae + GLM-4.6 拿到 task 后能直接开工，不需要追问「这个是什么意思」 -**方案**: 每个 task 必须自包含，包含四个必填字段： - -```markdown -## Task: {编号} {标题} - -### 输入 -- 读哪些文件（完整路径） -- 参考哪些 ADR（ADR-XXX） -- 依赖哪些上游任务（P01-XXX，已完成/产出是 X） - -### 输出 -- 生成/修改哪些文件（完整路径） -- 输出格式（代码/文档/配置） -- 验收方式（跑什么命令看什么结果） - -### 约束 -- 不碰哪些目录 -- 用什么库/版本 -- 遵循什么规范（code-style.md / doc-template.md） - -### 参考 -- ADR-XXX: 一句话说明关联性 -- 相关文件: 一行说明 -``` - -**核心原则**: -1. **零隐含上下文**：接收方不能依赖「上次聊过」，所有信息必须显式写在 task 里 -2. **适配接收方能力**：给 GLM-4.6 的任务粒度 = 单文件；给 Claude 的任务可以跨 3-5 个文件 -3. **Git commit 即消息**：每次 commit 是发送一次消息，接收方 pull 即收到 -4. **任务与代码分离**：task 定义在 `.ai/roles/{role}/queue.md`，代码在 `projects/`，通过 Git 同步 - -**何时用**: 跨平台/跨模型协作 -**何时不用**: 同一平台内的角色切换（直接对话即可） - ---- - -## 反模式（避免） - -- 在多个文件中重复同一状态信息 → 只在 ROADMAP.md 记录 -- 决策讨论散落在任务 feedback 中 → 提炼到 knowledge/decisions.md -- 大段文档内联而非链接 → 用链接 + 一句话摘要 diff --git a/hwd32h757/.ai/phases/INDEX.md b/hwd32h757/.ai/phases/INDEX.md deleted file mode 100644 index 8eb19ac..0000000 --- a/hwd32h757/.ai/phases/INDEX.md +++ /dev/null @@ -1,17 +0,0 @@ -# 阶段索引 - -| 阶段 | 名称 | 状态 | 目录 | -|------|------|------|------| -| 1 | 基础搭建 | DONE | `phase-01-foundation/` | -| 2 | MVP | ACTIVE | `phase-02-mvp/` | -| 3 | 功能完善 | PLANNED | `phase-03-features/` | -| 4 | 打磨发布 | PLANNED | `phase-04-polish/` | - -## 阶段切换规则 - -1. 当前阶段 completion.md 全部打勾 -2. 人类签字确认 -3. Arch AI 更新本索引文件 -4. Arch AI 更新所有角色 card.md（当前阶段字段） -5. Arch AI 更新 dashboard.md（进度条 + task 状态面板 + 最近事件） -6. 产出阶段复盘（docs/share/phase-NN/） diff --git a/hwd32h757/.ai/prompts/architecture/README.md b/hwd32h757/.ai/prompts/architecture/README.md deleted file mode 100644 index 40c1e5c..0000000 --- a/hwd32h757/.ai/prompts/architecture/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# 架构提示词模板 - -| 文件 | 用途 | -|------|------| -| `architecture-design.md` | 系统架构设计模板 | -| `technical-evaluation.md` | 技术选型评估模板 | diff --git a/hwd32h757/.ai/prompts/architecture/architecture-design.md b/hwd32h757/.ai/prompts/architecture/architecture-design.md deleted file mode 100644 index 5f942fe..0000000 --- a/hwd32h757/.ai/prompts/architecture/architecture-design.md +++ /dev/null @@ -1,44 +0,0 @@ -# 系统架构设计模板 - -## 输入 - -- 产品需求文档 (PRD) -- 技术约束（已有技术栈、团队能力） -- 非功能性需求（性能、安全、可扩展性） - -## 输出结构 - -### 1. 架构概述 -- 一句话描述架构核心思路 -- 系统边界和范围 - -### 2. 架构图（文字描述 + ASCII） -- 模块划分和职责 -- 模块间通信方式 -- 数据流向 - -### 3. 技术选型 -- 每个模块的技术栈及理由 -- 对比方案及淘汰原因 -- 风险点和缓解措施 - -### 4. 接口设计 -- 模块间接口定义 -- API 契约（请求/响应格式） -- 数据模型概要 - -### 5. 非功能性设计 -- 性能目标及实现策略 -- 安全设计（认证、授权、数据保护） -- 可扩展性考虑 - -### 6. 部署架构 -- 运行环境 -- 服务拓扑 -- CI/CD 流程 - -## 注意事项 - -- 架构文档面向 Arch AI 和 Dev AI，不要写人类才需要的背景介绍 -- 决策必须写理由，方便后续 AI 理解为什么这样设计 -- 每个模块标注影响范围（HIGH/MEDIUM/LOW），供 QA AI 确定回归测试范围 diff --git a/hwd32h757/.ai/prompts/architecture/technical-evaluation.md b/hwd32h757/.ai/prompts/architecture/technical-evaluation.md deleted file mode 100644 index 3e1f389..0000000 --- a/hwd32h757/.ai/prompts/architecture/technical-evaluation.md +++ /dev/null @@ -1,41 +0,0 @@ -# 技术选型评估模板 - -## 输入 - -- 需要解决的技术问题 -- 约束条件（预算、时间、团队、已有技术栈） - -## 输出结构 - -### 1. 需求描述 -- 要解决什么问题 -- 关键约束是什么 - -### 2. 候选方案（2-4 个） - -每个方案描述： -- 方案名称和简介 -- 优势（3-5 条） -- 劣势（3-5 条） -- 与本项目技术栈的兼容度 - -### 3. 评估维度 - -| 维度 | 权重 | 方案A | 方案B | 方案C | -|------|------|-------|-------|-------| -| 性能 | 30% | — | — | — | -| 生态成熟度 | 25% | — | — | — | -| 学习曲线 | 20% | — | — | — | -| 社区活跃度 | 15% | — | — | — | -| 团队熟悉度 | 10% | — | — | — | -| **加权总分** | 100% | — | — | — | - -### 4. 推荐方案 -- 推荐哪个、为什么 -- 主要风险 -- 如果失败，备选方案是什么 - -## 注意事项 - -- 评估维度可调整，但必须说明理由 -- 不追求"最优"，追求"最适合当前阶段" diff --git a/hwd32h757/.ai/prompts/coding/README.md b/hwd32h757/.ai/prompts/coding/README.md deleted file mode 100644 index d4c0f7c..0000000 --- a/hwd32h757/.ai/prompts/coding/README.md +++ /dev/null @@ -1,6 +0,0 @@ -# Dev AI 提示词库 - -| 文件 | 说明 | -|------|------| -| [code-style.md](code-style.md) | 代码风格、命名规范、目录组织 | -| [doc-template.md](doc-template.md) | impact.md / acceptance.md 等文档模板 | diff --git a/hwd32h757/.ai/prompts/coding/code-style.md b/hwd32h757/.ai/prompts/coding/code-style.md deleted file mode 100644 index d6c7317..0000000 --- a/hwd32h757/.ai/prompts/coding/code-style.md +++ /dev/null @@ -1,105 +0,0 @@ -# Dev AI 代码风格规范 - -## 适用技术栈 - -| 层 | 技术 | 语言 | -|-----|------|------| -| 前端 | Taro 4 + React 18 | TypeScript 5.x | -| 样式 | Tailwind CSS 4 | — | -| 后端 | NestJS 10 | TypeScript 5.x | -| 训练 | PyTorch 2.0 | Python 3.10+ | - ---- - -## 1. 文件命名 - -| 类型 | 规则 | 示例 | -|------|------|------| -| 页面组件 | kebab-case | `error-detail.tsx` | -| UI 组件 | kebab-case | `button.tsx` | -| 工具函数 | kebab-case | `format-date.ts` | -| 类型定义 | kebab-case | `error-entry.d.ts` | -| NestJS 模块 | kebab-case | `auth.module.ts` | -| Python 模块 | snake_case | `data_loader.py` | - -## 2. 目录组织（前端） - -``` -src/ -├── pages/{page-name}/ # 页面 —— 一个目录一个页面 -│ ├── index.tsx -│ ├── index.config.ts -│ └── index.css -├── components/ # 通用组件 -│ └── {component-name}/ -│ └── index.tsx -├── lib/ # 工具函数、hooks -├── types/ # 全局类型声明 -├── server/ # NestJS 后端 -└── config/ # Taro 构建配置 -``` - -## 3. 目录组织（NestJS 后端） - -``` -src/server/src/ -├── modules/{name}/ # 一个模块一个目录 -│ ├── {name}.module.ts -│ ├── {name}.controller.ts -│ ├── {name}.service.ts -│ ├── dto/ -│ └── entities/ -├── common/ # 共享：拦截器、守卫、管道 -└── main.ts -``` - -## 4. 命名风格 - -**TypeScript：** -- 组件：PascalCase —— `ErrorCard` -- 函数/变量：camelCase —— `getUserProfile` -- 常量：UPPER_SNAKE —— `MAX_PAGE_SIZE` -- 接口/类型：PascalCase —— `ErrorEntry` - -**Python：** -- 类：PascalCase —— `DataLoader` -- 函数/变量：snake_case —— `load_dataset` -- 常量：UPPER_SNAKE —— `BATCH_SIZE` - -## 5. 导入顺序（TypeScript） - -``` -1. 第三方库 -2. Taro 相关 -3. 项目内部（@/ 别名） -4. 相对路径 -5. 样式文件 -``` - -示例： -```typescript -import { useState } from 'react'; -import Taro from '@tarojs/taro'; -import { Button } from '@/components/ui/button'; -import { formatDate } from './lib/date'; -import './index.css'; -``` - -## 6. 组件规范 - -- 优先使用函数组件，不用 class 组件 -- 一个文件只有一个 export default 组件 -- 组件 props 必须声明类型接口 -- 跨端兼容：避免使用 `document`、`window`（用 Taro API 代替） - -## 7. API 调用规范 - -- 前端统一使用 `@/network.ts` 中的 `Network.request`，不要直接调用 `Taro.request` -- 后端Controller 只做参数校验和路由，业务逻辑放在 Service -- API 响应统一使用 Envelope 格式 `{ code, msg, data }` - -## 8. 不能做的事 - -- 不要在 `src/` 下写测试文件（测试在 `tests/`） -- 不要引入未经 package.json 声明的依赖 -- 不要在组件中硬编码后端地址（用 `PROJECT_DOMAIN` 全局变量） diff --git a/hwd32h757/.ai/prompts/coding/doc-template.md b/hwd32h757/.ai/prompts/coding/doc-template.md deleted file mode 100644 index 03710d3..0000000 --- a/hwd32h757/.ai/prompts/coding/doc-template.md +++ /dev/null @@ -1,76 +0,0 @@ -# Dev AI 文档模板 - -下面三个模板用于 Dev AI 在 `review/{task_id}/` 下产出标准化文件。 - ---- - -## A. impact.md 模板（变更影响范围） - -```markdown -# {TASK_ID} - 变更影响范围 - -## 修改的文件 -| 文件路径 | 修改类型 | 影响等级 | -|---------|---------|---------| -| projects/P01_soc_sw_app/src/server/src/modules/auth/auth.service.ts | 新增 | HIGH | -| projects/P01_soc_sw_app/src/server/src/modules/auth/dto/login.dto.ts | 新增 | MEDIUM | - -> 影响等级：HIGH=核心逻辑变更 | MEDIUM=新增文件 | LOW=注释/格式 - -## 影响的功能模块 -- [x] 用户认证模块 -- [ ] 芯片验证模块（无影响） - -## 需要回归测试的场景 -- 场景1: 用户登录成功流程 -- 场景2: 密码错误返回 401 -- 场景3: Token 过期后刷新 - -## 环境依赖变更 -- 新增依赖: bcrypt, @nestjs/jwt -- 数据库迁移: 新增 users 表 -``` - -**要点：** -- `修改的文件` 必须使用从仓库根目录开始的完整路径 -- 影响等级要实事求是，不要全写 HIGH -- `需要回归测试的场景` 要写**用户视角**的场景，不是代码内部细节 - ---- - -## B. acceptance.md 模板（验收标准） - -```markdown -# {TASK_ID} - 验收标准 - -## 功能验收 -- [ ] 用户可以注册新账户（邮箱+密码） -- [ ] 密码强度不足时提示明确错误信息 -- [ ] 登录成功返回有效 JWT Token - -## 非功能验收 -- [ ] API 响应时间 < 200ms -- [ ] 密码使用 bcrypt 加密存储 -- [ ] JWT Token 有效期 24 小时 - -## 测试覆盖要求 -- 单元测试覆盖率: >= 80% -- 集成测试覆盖率: >= 60% -- E2E 测试场景: >= 3 个 - -## 验收通过条件 -- 所有功能点验证通过 -- 测试覆盖率达标 -- 无重大安全漏洞 -``` - -**要点：** -- 功能验收用「用户可以…」句式，让 QA AI 和人类都能看懂 -- 每个功能点对应 task.md 里的一项交付物 -- 非功能验收写具体的可测量指标，不要写「性能好」「代码整洁」 - ---- - -## C. 没有 task.md 模板 - -task.md 由人类负责人创建，Dev AI 只读不写。Dev AI 如需补充技术细节，写在 impact.md 的「技术备注」段落中，不要直接修改 task.md。 diff --git a/hwd32h757/.ai/prompts/testing/README.md b/hwd32h757/.ai/prompts/testing/README.md deleted file mode 100644 index 70b0387..0000000 --- a/hwd32h757/.ai/prompts/testing/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# QA AI 提示词库 - -| 文件 | 说明 | -|------|------| -| [bug-report.md](bug-report.md) | 测试反馈 / Bug 报告模板与格式规范 | diff --git a/hwd32h757/.ai/prompts/testing/bug-report.md b/hwd32h757/.ai/prompts/testing/bug-report.md deleted file mode 100644 index 70c7d4d..0000000 --- a/hwd32h757/.ai/prompts/testing/bug-report.md +++ /dev/null @@ -1,67 +0,0 @@ -# QA AI Bug 报告模板 - -以下模板用于 QA AI 在 `review/{task_id}/feedback/round{round}.md` 中提交测试反馈。 - ---- - -## 模板 - -```markdown -# {TASK_ID} - 第 {N} 轮测试反馈 - -## 基本信息 -- 测试时间: YYYY-MM-DD -- 测试项目: P01_soc_sw_app / P02_soc_sw_training / P03_soc_sw_web -- 测试环境: Node 20.x / Python 3.10 - -## 测试结果概览 -| 指标 | 数值 | -|------|------| -| 测试用例总数 | N | -| 通过 | N | -| 失败 | N | -| 跳过 | N | -| 代码覆盖率 | XX% | - -## 失败用例清单 - -### Bug #1: {简短标题} -- **严重程度**: BLOCKER / HIGH / MEDIUM / LOW -- **涉及文件**: `projects/...`（完整路径） -- **测试场景**: 用户登录时输入正确密码 -- **预期结果**: 返回 200 和 JWT Token -- **实际结果**: 返回 500 Internal Server Error -- **复现步骤**: - 1. POST /api/auth/login - 2. body: {"email": "test@example.com", "password": "correct"} -- **建议修复**: 检查 auth.service.ts 第 42 行的异常处理 - -### Bug #2: ... -（同上格式） - -## 改进建议（非 Bug） -- 建议 1: 登录接口缺少限流保护 -- 建议 2: 密码重置的邮件模板可以更友好 - -## 下一步 -- [ ] Dev AI 修复上述 Bug 后，QA AI 进行第 {N+1} 轮测试 -- [ ] 如第 3 轮仍未通过，升级给人类负责人裁决 -``` - ---- - -## 严重程度定义 - -| 级别 | 含义 | 举例 | -|------|------|------| -| BLOCKER | 核心功能不可用，无法继续测试 | 登录接口直接崩溃、数据库连不上 | -| HIGH | 功能逻辑错误，用户无法正常使用 | 登录成功但不返回 Token | -| MEDIUM | 功能可用但与预期有偏差 | 返回的日期格式不对、错误码不对 | -| LOW | 不影响功能的瑕疵 | 提示文案不友好、缺少空值校验 | - -## 规则 - -1. **每轮反馈用新文件**：`round1.md` → `round2.md` → `round3.md` -2. **最多 3 轮**：第 3 轮仍有 BLOCKER/HIGH Bug → 在报告中标注「建议人类负责人介入」 -3. **涉及文件必须用完整路径**：从仓库根目录开始，方便 Dev AI 定位 -4. **改进建议不要超过 3 条**：聚焦最重要的 diff --git a/hwd32h757/.ai/roles/README.md b/hwd32h757/.ai/roles/README.md deleted file mode 100644 index 208e127..0000000 --- a/hwd32h757/.ai/roles/README.md +++ /dev/null @@ -1,57 +0,0 @@ -# AI 角色工作台 - -## 三层架构 - -``` -控制面板 (dashboard.md) → 人类 + Arch AI 共享入口，项目唯一真实来源 - ↓ Arch AI 拆解任务 -执行层 (.ai/tasks/active/) → Coder/Tester 各自独立 task 文件，自包含 -``` - -## 四个角色入口 - -| 角色 | 平台+模型 | 入口 | 读几个文件 | -|------|----------|------|-----------| -| 人类 | — | [dashboard.md](../../dashboard.md) 顶部「人类区」 | 1 | -| Arch AI | Claude Code + DeepSeek V4 Pro | [dashboard.md](../../dashboard.md) 全文 | 1 | -| Coder AI | Trae CN + GLM-4.6 | [card.md](dev/card.md) → 对应 task 文件 | 2 | -| Tester AI | Coze CN | [card.md](qa/card.md) → 对应 task 文件 | 2 | - -## 使用方式 - -**Arch AI**: -``` -1. 读 dashboard.md → 了解全貌 + ADR 摘要 + task 状态 -2. 需要细节 → 按链接按需加载 -3. 人类决策 → 读 DECISIONS.md -4. 拆分新任务 → 按模板写 .ai/tasks/active/P01-XXX.md -5. 完成后 → 更新 dashboard.md task 状态 -``` - -**Coder AI (Trae + GLM-4.6)**: -``` -1. 读 card.md → 身份+权限 -2. 读对应 task 文件 → 输入/输出/约束/验收方法 -3. 写代码 -4. 自验 → 填写完成报告 → commit [READY_FOR_TEST] -``` - -**Tester AI (Coze)**: -``` -1. git pull + 读 card.md -2. git log --grep="READY_FOR_TEST" → 找待测 task -3. 读对应 Tester task 文件 → 测试内容/执行方式/报告格式 -4. 拉代码 → 沙盒执行 → 生成 JSON 报告 -5. commit 报告 -``` - -## 关键原则 - -1. **每个角色只有一个入口文件** — 不拼图，不切换 -2. **Worker AI 不需要知道项目全貌** — task 文件就是它的全部世界 -3. **Git 是唯一的集成总线** — 跨平台交接通过 commit message 信号 -4. **弱模型适配强约束** — 给 GLM-4.6 的任务 = 单文件粒度，零隐含上下文 - -## 归档 - -旧的 DASHBOARD.md / ROADMAP.md / roles/*/today.md / roles/*/queue.md → `.ai/archive/` diff --git a/hwd32h757/.ai/roles/arch/card.md b/hwd32h757/.ai/roles/arch/card.md deleted file mode 100644 index 1901626..0000000 --- a/hwd32h757/.ai/roles/arch/card.md +++ /dev/null @@ -1,43 +0,0 @@ -# Arch AI — 架构师 - -## 身份 - -我是架构 AI。负责需求分析、架构设计、技术选型、任务分解。 - -**平台**: Claude Code + DeepSeek V4 Pro（最强推理 + Agent 框架） - -## 启动流程 - -1. 读 `dashboard.md` 全文（< 2K tokens）→ 项目全貌 + ADR 索引 + task 状态面板 -2. 需要细节 → 按 dashboard 中的链接按需加载 -3. 人类决策 → 读 `DECISIONS.md` -4. 完成任务 → 更新 dashboard.md + 对应 ADR/knowledge 文件 - -## 当前阶段 - -Phase 1: 基础搭建 — `dashboard.md` - -## 核心交付物 - -- 产品需求 + 系统架构设计 -- 技术选型 + 架构决策 (ADR) -- 任务分解 → `.ai/tasks/active/P01-XXX.md` -- 跨模块协调（Coder ↔ Tester 交接协议） -- 人类决策梳理 → `DECISIONS.md` - -## 关键入口 - -| 文件 | 说明 | -|------|------| -| `dashboard.md` | 唯一控制面板（替代旧 DASHBOARD.md / ROADMAP.md） | -| `DECISIONS.md` | 待人类决策事项 | -| `.ai/knowledge/decisions.md` | ADR 全文 | -| `.ai/knowledge/lessons.md` | 经验教训 | -| `.ai/knowledge/patterns.md` | 可复用模式 | -| `.ai/tasks/active/` | 所有活跃 task 文件 | - -## 权限 - -**可写**: docs/ shared/ projects/*/src/ projects/*/docs/ .ai/tasks/ .ai/knowledge/ dashboard.md DECISIONS.md -**只读**: projects/*/tests/ reports/ -**禁止**: 无 diff --git a/hwd32h757/.ai/roles/dev/card.md b/hwd32h757/.ai/roles/dev/card.md deleted file mode 100644 index 67a882b..0000000 --- a/hwd32h757/.ai/roles/dev/card.md +++ /dev/null @@ -1,40 +0,0 @@ -# Dev AI — 开发者 - -## 身份 - -我是开发 AI。负责编写业务代码、技术文档、Bug 修复。 - -**平台**: Trae CN + GLM-4.6（代码生成 + 文件操作，单文件粒度） - -## 启动流程 - -1. 读本文件（card.md）→ 我是谁、权限、当前阶段 -2. 读 dashboard.md → 找到自己对应的 task（状态为 `todo` 的 Coder 任务） -3. 打开对应 task 文件（如 `.ai/tasks/active/P01-001.md`）→ **这就是你的全部世界** -4. 按 task 文件中的「输入」「输出」「约束」「验收方法」执行 -5. 完成后 → 填写 task 文件的「完成报告」→ commit（message 含 `[READY_FOR_TEST]`） - -**不需要**读 ADR 全文、知识库、或其他 task 文件。你的 task 文件已经包含了完成任务所需的全部信息。 - -## 当前阶段 - -Phase 1: 基础搭建 - -## 核心交付物 - -- 业务代码实现 (projects/*/src/) -- 项目文档 (projects/*/docs/) - -## 关键入口 - -| 文件 | 说明 | -|------|------| -| `dashboard.md` | 查找自己的 task | -| `.ai/tasks/active/P01-XXX.md` | 你的 task 文件（开工时读这个） | -| `.ai/tasks/templates/TASK_TEMPLATE_CODER.md` | task 格式说明 | - -## 权限 - -**可写**: projects/*/src/ projects/*/docs/ docs/ tools/ data/ shared/ -**只读**: review/*/task.md review/*/feedback/ .ai/tasks/active/ -**禁止**: projects/*/tests/ reports/ diff --git a/hwd32h757/.ai/roles/qa/card.md b/hwd32h757/.ai/roles/qa/card.md deleted file mode 100644 index d44e0dc..0000000 --- a/hwd32h757/.ai/roles/qa/card.md +++ /dev/null @@ -1,42 +0,0 @@ -# QA AI — 测试者 - -## 身份 - -我是测试 AI。负责在 Coze 沙盒中拉取代码、执行测试、生成报告。 - -**平台**: Coze CN（沙盒执行 + 自动化测试） - -## 启动流程 - -1. 读本文件（card.md）→ 我是谁、权限 -2. `git pull` → 拉取最新代码 -3. `git log --oneline --grep="READY_FOR_TEST"` → 查找待测试的 task -4. 打开对应 Tester task 文件（如 `.ai/tasks/active/T01-XXX.md`）→ **这就是你的全部世界** -5. 按 task 文件中的「测试目标」「测试内容」「执行方式」执行 -6. 生成测试报告 → `reports/{编号}-{日期}.json` -7. 填写 task 文件的「完成报告」→ commit - -**关键**: 你不需要知道项目全貌、不需要读架构文档、不需要读 ADR。你的 task 文件 + 被测代码 = 你需要的一切。 - -## 当前阶段 - -Phase 1: 基础搭建 - -## 核心交付物 - -- 测试报告 (reports/) -- Bug 反馈（在测试报告中标注 FAIL 项） - -## 关键入口 - -| 文件 | 说明 | -|------|------| -| `dashboard.md` | 查找自己的 task | -| `.ai/tasks/active/T01-XXX.md` | 你的 task 文件（开工时读这个） | -| `.ai/tasks/templates/TASK_TEMPLATE_TESTER.md` | task 格式说明 | - -## 权限 - -**可写**: projects/*/tests/ reports/ -**只读**: projects/*/src/ projects/*/docs/ docs/ data/ shared/ .ai/tasks/active/ -**禁止**: .ai/ tools/ diff --git a/hwd32h757/.ai/tasks/templates/TASK_TEMPLATE_CODER.md b/hwd32h757/.ai/tasks/templates/TASK_TEMPLATE_CODER.md deleted file mode 100644 index af50f98..0000000 --- a/hwd32h757/.ai/tasks/templates/TASK_TEMPLATE_CODER.md +++ /dev/null @@ -1,47 +0,0 @@ -# Task {编号}: {标题} - -## 元信息 - -| 字段 | 值 | -|------|-----| -| 状态 | `todo` → `in_progress` → `done` → `tested` → `accepted` | -| 优先级 | P0 / P1 / P2 | -| 依赖 | {上游 task 编号，无则写「无」} | -| 分配给 | Coder AI (Trae CN + GLM-4.6) | - -## 输入 - -**要读的文件**: -- `{完整路径}` — {一句话说明} - -**参考的 ADR**: -- ADR-XXX: {一句话说明关联} - -**上游依赖产出**: -- {上游 task 编号}: {产出是什么} - -## 输出 - -**要生成/修改的文件**: -- `{完整路径}` — {说明} -- `{完整路径}` — {说明} - -**验收方法**: -```bash -{具体命令或步骤，Coder 可以自己跑来验证} -``` - -## 约束 - -- 不碰: `{目录路径}` -- 技术栈: {库/版本} -- 遵循: `{规范文件}` - -## 完成报告 - -> Coder 完成后填写。Commit message 以 `[READY_FOR_TEST]` 结尾。 - -- [ ] 输出文件已生成 -- [ ] 验收命令通过 -- [ ] Commit: `{hash}` -- [ ] Commit message: `feat({编号}): {描述} [READY_FOR_TEST]` diff --git a/hwd32h757/.ai/tasks/templates/TASK_TEMPLATE_TESTER.md b/hwd32h757/.ai/tasks/templates/TASK_TEMPLATE_TESTER.md deleted file mode 100644 index ca51a48..0000000 --- a/hwd32h757/.ai/tasks/templates/TASK_TEMPLATE_TESTER.md +++ /dev/null @@ -1,75 +0,0 @@ -# Task {编号}: {标题} - -## 元信息 - -| 字段 | 值 | -|------|-----| -| 状态 | `todo` → `in_progress` → `done` → `accepted` | -| 优先级 | P0 / P1 / P2 | -| 对应 Coder task | {P01-XXX} | -| 分配给 | Tester AI (Coze CN) | - -## 测试目标 - -{一句话 —— 验证什么功能/模块} - -## 被测对象 - -**Coder 产出的 commit**: -- 从 git log 查找 commit message 包含 `[READY_FOR_TEST]` 且 task 编号为 `{编号}` 的最新 commit -- 或直接读 `.ai/roles/dev/card.md` 里指定的代码目录 - -**Coder task 文件**: -- [P01-XXX]({路径}) — 理解该 task 的输入/输出/约束 - -## 测试内容 - -**关键路径**: -- [ ] {关键路径 1} -- [ ] {关键路径 2} -- [ ] {边界条件} - -**不应发生的**: -- [ ] {错误情况 1} - -## 执行方式 - -``` -1. git pull → 拉取最新代码 -2. 在 Coze 沙盒中执行测试 -3. 生成测试报告 -``` - -## 报告格式 - -输出 `reports/{编号}-{日期}.json`: - -```json -{ - "task": "{编号}", - "date": "{YYYY-MM-DD}", - "summary": { - "total": {N}, - "passed": {N}, - "failed": {N} - }, - "results": [ - { - "case": "{用例名}", - "status": "pass|fail", - "details": "{失败时的详细信息}" - } - ], - "conclusion": "PASS|FAIL|RETRY" -} -``` - -## 完成报告 - -> Tester 完成后填写。 - -- [ ] 测试已执行 -- [ ] 报告已生成 → `reports/{编号}-{日期}.json` -- [ ] Commit: `{hash}` -- [ ] Commit message: `test({编号}): {结论}` -- [ ] 结论: PASS / FAIL / RETRY diff --git a/hwd32h757/.trae/skills/add-subproject/SKILL.md b/hwd32h757/.trae/skills/add-subproject/SKILL.md deleted file mode 100644 index 6405a52..0000000 --- a/hwd32h757/.trae/skills/add-subproject/SKILL.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -name: "add-subproject" -description: "Adds a new subproject to the existing '1 Human + 2 AI' collaboration framework. Invoke when you need to add a new subproject like web admin, data entry program, etc." ---- - -# 添加子项目 Skill - -## 功能 - -在现有的"1人+2AI"协作框架中动态添加新的子项目，自动创建： -- 项目目录结构（src/、tests/、docs/） -- 环境配置文件（ENVIRONMENT.md） -- README.md 占位文件 -- 示例任务目录（含 task.md、acceptance.md、impact.md、feedback/） - -## 使用方法 - -### 参数说明 - -| 参数 | 类型 | 必填 | 说明 | -|------|------|------|------| -| project_name | string | 是 | 子项目名称，如 "web_admin"、"data_entry" | -| project_number | string | 否 | 项目编号，如 "P03"，默认自动生成 | - -### 调用方式 - -```bash -# 方式1：仅提供项目名称（自动分配编号） -# skill 会自动检测现有项目编号，分配下一个编号 -add-subproject --project_name="web_admin" - -# 方式2：指定项目编号 -add-subproject --project_name="web_admin" --project_number="P03" -``` - -## 创建的内容 - -### 目录结构 -``` -projects/ -└── P03_web_admin/ # 新项目目录 - ├── src/ # Dev AI 工作区 - │ ├── server/ # NestJS 后端（如需要） - │ ├── config/ # 构建配置 - │ ├── types/ # 全局类型 - │ └── README.md - ├── tests/ # QA AI 工作区 - │ └── README.md - ├── docs/ # 项目文档 - │ ├── 01_需求概要.md - │ ├── 02_架构设计.md - │ └── 03_接口定义.md - └── ENVIRONMENT.md # 环境配置 -``` - -### 任务目录 -``` -review/ -└── active/ - └── P03-001/ # 新项目的第一个任务 - ├── task.md # 任务描述（人类创建，AI 只读） - ├── acceptance.md # 验收标准 - ├── impact.md # 变更影响范围 - └── feedback/ # 测试反馈 - └── round1.md -``` - -## 执行命令 - -```bash -# 获取下一个项目编号（PowerShell 兼容版本） -get_next_project_number() { - # 兼容 Linux/macOS - if command -v ls >/dev/null 2>&1; then - ls -la projects/ | grep -E '^P[0-9]+_' | sort | tail -1 | sed 's/P\([0-9]*\)_.*$/\1/' - # 兼容 Windows PowerShell - elif command -v powershell >/dev/null 2>&1; then - powershell -Command "(Get-ChildItem projects -Directory | Where-Object { $_.Name -match '^P\d+_' } | Sort-Object Name | Select-Object -Last 1).Name -replace 'P(\d+)_.*', '$1'" - else - echo "0" - fi -} - -# 创建项目目录 -PROJECT_NAME="web_admin" -NEXT_NUM=$(get_next_project_number) -PROJECT_NUM="P$(printf '%02d' $((NEXT_NUM + 1)))" -PROJECT_DIR="projects/${PROJECT_NUM}_${PROJECT_NAME}" - -mkdir -p "${PROJECT_DIR}"/{src/{server,config,types},tests,docs} - -# 创建 ENVIRONMENT.md -cat > "${PROJECT_DIR}/ENVIRONMENT.md" << EOF -# ${PROJECT_NUM}_${PROJECT_NAME} - 环境准备 - -## 依赖 -- Node.js >= 20.x -- pnpm >= 9.0.0 - -## 安装 -pnpm install - -## 运行 -pnpm dev -EOF - -# 创建文档 -cat > "${PROJECT_DIR}/docs/01_需求概要.md" << EOF -# ${PROJECT_NUM}_${PROJECT_NAME} - 需求概要 - -## 项目概述 - -## 功能需求 - -## 非功能需求 -EOF - -cat > "${PROJECT_DIR}/docs/02_架构设计.md" << EOF -# ${PROJECT_NUM}_${PROJECT_NAME} - 架构设计 - -## 技术选型 - -## 架构图 - -## 模块划分 -EOF - -cat > "${PROJECT_DIR}/docs/03_接口定义.md" << EOF -# ${PROJECT_NUM}_${PROJECT_NAME} - 接口定义 - -## API 列表 - -## 数据结构 -EOF - -# 创建 README.md -echo "# ${PROJECT_NAME} - src" > "${PROJECT_DIR}/src/README.md" -echo "# ${PROJECT_NAME} - tests" > "${PROJECT_DIR}/tests/README.md" - -# 创建示例任务 -mkdir -p "review/active/${PROJECT_NUM}-001/feedback" - -cat > "review/active/${PROJECT_NUM}-001/task.md" << EOF -# ${PROJECT_NUM}-001 - 项目初始化 - -## 任务信息 -- 任务编号：${PROJECT_NUM}-001 -- 项目：${PROJECT_NUM}_${PROJECT_NAME} -- 创建时间：$(date +%Y-%m-%d) -- 状态：TODO - -## 任务描述 -完成 ${PROJECT_NAME} 项目的初始化工作。 - -## 交付物 -- 项目目录结构 -- 基础配置文件 -- README 文档 -EOF - -cat > "review/active/${PROJECT_NUM}-001/acceptance.md" << EOF -# ${PROJECT_NUM}-001 - 验收标准 - -## 功能验收 -- [ ] 项目目录结构完整 -- [ ] ENVIRONMENT.md 已创建 -- [ ] 文档目录已初始化 - -## 测试覆盖要求 -- 无需测试（初始化任务） -EOF - -cat > "review/active/${PROJECT_NUM}-001/impact.md" << EOF -# ${PROJECT_NUM}-001 - 变更影响范围 - -## 修改的文件 -| 文件路径 | 修改类型 | 影响等级 | -|---------|---------|---------| -| ${PROJECT_DIR}/ | 新增 | LOW | - -## 影响的功能模块 -- [x] 项目初始化 - -## 需要回归测试的场景 -- 无（新项目） - -## 环境依赖变更 -- 无 -EOF - -cat > "review/active/${PROJECT_NUM}-001/feedback/round1.md" << EOF -# ${PROJECT_NUM}-001 - 第一轮测试反馈 - -## 基本信息 -- 测试时间: $(date +%Y-%m-%d) -- 测试项目: ${PROJECT_NUM}_${PROJECT_NAME} -- 测试环境: 待配置 - -## 测试结果概览 -| 指标 | 数值 | -|------|------| -| 测试用例总数 | 0 | -| 通过 | 0 | -| 失败 | 0 | -| 跳过 | 0 | -| 代码覆盖率 | 0% | - -## 反馈 -待 Dev AI 完成开发后执行测试 -EOF - -# 更新 README.md（如果存在） -if [ -f README.md ]; then - echo "- [${PROJECT_NUM}_${PROJECT_NAME}](${PROJECT_DIR})" >> README.md -fi - -echo "✅ 子项目 ${PROJECT_NUM}_${PROJECT_NAME} 创建成功！" -echo "📖 请阅读 AGENTS.md 了解协作规则" -echo "🚀 在 review/active/${PROJECT_NUM}-001/ 下查看示例任务结构" -``` - -## 使用场景 - -**何时调用此 skill：** -- ✅ 添加新的 Web 管理程序 -- ✅ 添加数据录入程序 -- ✅ 添加任何新的子项目模块 -- ✅ 扩展现有项目架构 - -**不适用场景：** -- ❌ 项目尚未初始化（需先调用 ai-collab-setup） -- ❌ 修改现有项目结构 - -## 后续步骤 - -skill 执行后： -1. 检查 `projects/${PROJECT_NUM}_${PROJECT_NAME}/` 目录结构 -2. 阅读 `review/active/${PROJECT_NUM}-001/task.md` 示例任务 -3. 根据实际需求修改 `task.md` 为真实任务 -4. Dev AI 开始开发 - ---- - -**Version**: 2.0 -**Created**: 2026-05-22 -**Updated**: 2026-05-23 -**Based On**: SoC_SW AI Programming Project -**Changes from v1**: -- 目录结构新增 src/server/、src/config/、src/types/ 子目录 -- 示例任务增加完整的 feedback/round1.md 格式（含基本信息表格） -- impact.md 增加「影响的功能模块」和「环境依赖变更」段落 -- 脚本兼容 Windows PowerShell 和 Linux/macOS -- ENVIRONMENT.md 默认使用 pnpm 包管理器 diff --git a/hwd32h757/.trae/skills/ai-collab-setup/SKILL.md b/hwd32h757/.trae/skills/ai-collab-setup/SKILL.md deleted file mode 100644 index 483ffca..0000000 --- a/hwd32h757/.trae/skills/ai-collab-setup/SKILL.md +++ /dev/null @@ -1,1183 +0,0 @@ ---- -name: "ai-collab-setup" -description: "Creates complete '1 Human + 3 AI' collaboration framework with directory structure and AI constitution. Invoke when starting a new AI-assisted programming project." ---- - -# AI 协作框架快速搭建 - -## 功能 - -一键创建"1 人+3AI（Arch+Coder+Tester）"协作框架，包括： -- 完整的目录结构 -- AI 角色定义与权限约定（AGENTS.md）—— R/W/RW/- 四态权限体系 -- AI 配置文件（含 read_only_paths、forbidden_paths、description） -- 提示词模板（code-style.md、doc-template.md、bug-report.md） -- 工作流配置（5 阶段 + retry + escalation） -- 示例任务模板 -- README 文档 - -## 使用方法 - -在新项目根目录执行： - -```bash -# 调用此 skill -# skill 会自动创建所有必要的目录和文件 -``` - -## 创建的内容 - -### 目录结构 -``` -. -├── AGENTS.md # AI 宪法（角色定义 + 权限约定 + R/W/RW/- 矩阵） -├── README.md # 项目说明 -├── .gitignore -├── .ai/ -│ ├── config/ -│ │ ├── architect.json # Arch AI 配置（含 read_only_paths） -│ │ ├── coder.json # Dev AI 配置（含 read_only_paths） -│ │ ├── tester.json # QA AI 配置（含 read_only_paths） -│ │ └── workflow.json # 工作流配置（含 retry + escalation） -│ └── prompts/ -│ ├── coding/ # 编码提示词 -│ │ ├── README.md -│ │ ├── code-style.md # 代码风格规范 -│ │ └── doc-template.md # impact.md / acceptance.md 模板 -│ └── testing/ # 测试提示词 -│ ├── README.md -│ └── bug-report.md # Bug 报告模板（BLOCKER/HIGH/MEDIUM/LOW） -├── docs/ # 项目级总体文档（Dev AI 编写，QA AI 只读） -│ ├── 01_产品需求/ -│ ├── 02_系统架构/ -│ ├── 03_开发规范/ -│ ├── 04_部署运维/ -│ └── 05_变更日志/ -│ └── archived/ # 历史变更日志（按年月归档） -├── tools/ # 开发工具脚本（Dev AI 维护） -├── data/ # 训练数据（Dev AI 维护，QA AI 只读） -├── projects/ -│ ├── P01_app/ -│ │ ├── src/ # Dev AI 工作区（前端 + 后端 + 配置） -│ │ │ ├── server/ # NestJS 后端 -│ │ │ ├── config/ # 构建配置 -│ │ │ └── types/ # 全局类型 -│ │ ├── tests/ # QA AI 工作区 -│ │ ├── docs/ -│ │ │ ├── 01_需求概要.md -│ │ │ ├── 02_架构设计.md -│ │ │ └── 03_接口定义.md -│ │ └── ENVIRONMENT.md -│ └── P02_training/ -│ ├── src/ -│ ├── tests/ -│ ├── docs/ -│ └── ENVIRONMENT.md -├── review/ -│ ├── active/ # 活跃任务 -│ │ ├── P01-001/ -│ │ │ ├── task.md # 任务描述（人类创建，AI 只读） -│ │ │ ├── acceptance.md # 验收标准 -│ │ │ ├── impact.md # 变更影响范围 -│ │ │ └── feedback/ # 测试反馈 -│ │ │ └── round1.md -│ │ ├── P01-002/ -│ │ └── CROSS-001/ -│ └── archived/ # 归档任务（按季度） -│ └── 2026-Q2/ -├── shared/ -│ ├── scripts/ -│ ├── templates/ -│ └── utils/ -├── reports/ -│ ├── test-results/ # 测试结果 -│ └── quality-reports/ # 质量评审报告 -└── .github/workflows/ -``` - -### 核心文件 - -**AGENTS.md** - AI 宪法： -- 三个角色定义（人类、Dev AI、QA AI） -- R/W/RW/- 四态权限矩阵 -- 工作流程（4 阶段 + 缺陷修复循环） -- retry 配置（max_rounds=3，escalation 规则） -- 沟通规范 -- 命名规范 - -**AI 配置文件**： -- `.ai/config/coder.json` - Dev AI 权限和职责（含 read_only_paths、forbidden_paths） -- `.ai/config/tester.json` - QA AI 权限和职责（含 read_only_paths、forbidden_paths） -- `.ai/config/workflow.json` - 工作流配置（含 retry + escalation） - -**提示词模板**： -- `.ai/prompts/coding/code-style.md` - 代码风格、命名规范、目录组织 -- `.ai/prompts/coding/doc-template.md` - impact.md / acceptance.md 标准化模板 -- `.ai/prompts/testing/bug-report.md` - Bug 报告模板，严重程度定义 - -**示例任务**： -- `review/active/P01-001/` - 示例任务（包含 task、acceptance、impact、feedback） -- `review/active/CROSS-001/` - 跨项目任务示例 - -## 执行命令 - -```bash -# 1. 创建目录结构 -mkdir -p .ai/{config,prompts/{coding,testing}} \ - projects/{P01_app,P02_training}/{src/{server,config,types},tests,docs} \ - review/{active/{P01-001,P01-002,CROSS-001},archived/2026-Q2}/feedback \ - shared/{scripts,templates,utils} \ - reports/{test-results,quality-reports} \ - .github/workflows - -# 2. 创建 AGENTS.md -cat > AGENTS.md << 'EOF' -# AI 角色定义与权限约定 - -## 团队架构 -``` -┌─────────────────────────────────────────────┐ -│ 人类负责人 │ -│ 需求分析 · 架构设计 · 最终决策 │ -└───────────────┬───────────┬─────────────────┘ - │ │ - ┌───────────┴──┐ ┌────┴────────────┐ - ▼ ▼ ▼ ▼ -┌───────────────┐ ┌──────────────┐ ┌───────────────┐ -│ Arch AI │ │ Dev AI │ │ QA AI │ -│ 需求分析 │ │ 代码编写 │ │ 测试设计 │ -│ 架构设计 │ │ 文档生成 │ │ 测试执行 │ -│ 技术选型 │ │ 影响评估 │ │ 质量保障 │ -│ 跨模块协调 │ └──────────────┘ └───────────────┘ -└───────────────┘ -``` - ---- - -## 角色职责 - -### Arch AI (架构AI) -**职责范围：** -- ✅ 需求分析和产品规划 -- ✅ 系统架构设计 -- ✅ 技术选型和评估 -- ✅ 跨模块协调和集成 -- ✅ 编写架构文档 (`docs/`) -- ✅ 定义验收标准 (`review/*/acceptance.md`) -- ✅ 评估变更影响 (`review/*/impact.md`) -- ✅ 维护共享资源 (`shared/`) -- ✅ 维护开发工具 (`tools/`) -- ✅ 维护训练数据 (`data/`) -- ✅ 指导 Dev AI 和 QA AI 工作 - -**可读但不可写：** -- 👁 AI 配置文件 (`.ai/`) —— 只读，了解团队规则 -- 👁 测试代码 (`projects/*/tests/`) —— 只读，了解测试覆盖 -- 👁 测试报告 (`reports/`) —— 只读，了解质量状况 -- 👁 测试反馈 (`review/*/feedback/`) —— 只读，了解问题 - -**禁止操作：** -- ❌ 无（架构 AI 拥有最高 AI 权限） - -### Dev AI (编码AI) -**职责范围：** -- ✅ 编写业务代码 (`projects/*/src/`) -- ✅ 生成技术文档 (`projects/*/docs/`) -- ✅ 定义验收标准 (`review/*/acceptance.md`) -- ✅ 评估变更影响 (`review/*/impact.md`) -- ✅ 维护共享资源 (`shared/`) - -**可读但不可写：** -- 👁 任务描述 (`review/*/task.md`) —— 只读，不可修改 -- 👁 测试反馈 (`review/*/feedback/`) —— 只读，用于修 Bug - -**禁止操作：** -- ❌ 修改测试代码 (`projects/*/tests/`) -- ❌ 修改测试报告 (`reports/`) - -### QA AI (测试AI) -**职责范围：** -- ✅ 编写测试用例 (`projects/*/tests/`) -- ✅ 执行测试并生成报告 (`reports/`) -- ✅ 补充验收标准 (`review/*/acceptance.md`) -- ✅ 提交测试反馈 (`review/*/feedback/`) - -**可读但不可写：** -- 👁 业务代码 (`projects/*/src/`) —— 只读，理解逻辑编写测试 -- 👁 技术文档 (`projects/*/docs/`) —— 只读，了解接口设计 -- 👁 项目级文档 (`docs/`) —— 只读，了解系统架构 -- 👁 训练数据 (`data/`) —— 只读，了解数据分布 -- 👁 共享资源 (`shared/`) —— 只读，了解工具函数 -- 👁 任务描述 (`review/*/task.md`) —— 只读，了解测试目标 -- 👁 验收标准 (`review/*/acceptance.md`) —— 只读，了解测试要求 - -**禁止操作：** -- ❌ 修改业务代码 (`projects/*/src/`) -- ❌ 修改技术文档 (`projects/*/docs/`) -- ❌ 修改共享资源 (`shared/`) -- ❌ 修改影响评估 (`review/*/impact.md`) -- ❌ 修改开发工具 (`tools/`) -- ❌ 修改测试反馈 (`review/*/feedback/`) - -### 人类负责人 -**职责范围：** -- ✅ 可以修改所有目录 -- ✅ 审核 AI 输出质量 -- ✅ 解决 AI 之间的冲突 -- ✅ 最终决策和验收 - ---- - -## 工作流程 - -``` -┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ -│ 需求分析 │ ───→ │ 架构设计 │ ───→ │ 开发实现 │ ───→ │ 测试验证 │ ───→ │ 验收确认 │ -│ (Arch AI) │ │ (Arch AI) │ │ (Dev AI) │ │ (QA AI) │ │ (人类) │ -└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ - ↑ │ - │ Bug → 修复 │ - └──────────────────────┘ - (最多 2 轮) -``` - -### 详细流程说明 - -**1. 需求分析阶段** -- Arch AI 分析用户需求，输出产品规划 -- 输出: `docs/01_产品需求/PRD.md`、`review/{task_id}/task.md` - -**2. 架构设计阶段** -- Arch AI 设计系统架构，技术选型 -- 输出: `docs/02_系统架构/`、`review/{task_id}/impact.md`、`review/{task_id}/acceptance.md` - -**3. 开发实现阶段** -- Dev AI 读取任务描述和验收标准，编写代码 + 文档 -- 输出: `projects/*/src/`, `projects/*/docs/` - -**4. 测试验证阶段** - -**2. 开发实现阶段** -- Dev AI 读取任务描述，编写代码 + 文档 -- 同时输出验收标准和变更影响范围 -- 输出: `projects/*/src/`, `projects/*/docs/`, `review/{task_id}/impact.md`, `review/{task_id}/acceptance.md` - -**3. 测试验证阶段** -- QA AI 根据验收标准编写测试，执行测试，生成报告 -- 测试反馈写入 `review/{task_id}/feedback/round{round}.md` -- 输出: `projects/*/tests/`, `reports/test-results/`, `review/{task_id}/feedback/` - -### 缺陷修复循环 - -| 规则 | 说明 | -|------|------| -| 最大轮次 | 3 轮（初始测试 + 最多 2 轮修复复查） | -| 循环范围 | 测试失败 → Dev AI 修复 → QA AI 复查 | -| 跳过项 | 修复轮次中 Dev AI **只修 Bug**，不重新写 acceptance/impact | -| 触发升级 | 第 3 轮仍有 BLOCKER 或 HIGH 级别 Bug → 暂停流转，待人类裁决 | - -``` -Round 1: Dev 开发 → QA 测试 → 3 个 Bug -Round 2: Dev 修复 → QA 复查 → 1 个 Bug（MEDIUM） -Round 3: Dev 修复 → QA 复查 → 0 个 Bug ✅ → 提交人类验收 -``` - -如果 Round 3 仍有 BLOCKER/HIGH： -``` -Round 3: Dev 修复 → QA 复查 → 仍 1 个 HIGH → ⚠️ 升级给人类裁决 -``` - -**4. 验收确认阶段** -- 人类审核测试报告，确认任务完成或驳回 -- 确认后任务状态更新为 DONE，移入 `review/archived/` - ---- - -## 目录权限矩阵 - -> **图例**：`-` = 无权访问    `R` = 只读    `W` = 可写（含读）    `RW` = 读写 - -| 目录路径 | Arch AI | Dev AI | QA AI | 人类 | -|---------|---------|--------|-------|------| -| `.ai/` | `R` | `-` | `-` | `RW` | -| `docs/` | `RW` | `RW` | `R` | `RW` | -| `tools/` | `RW` | `RW` | `-` | `RW` | -| `data/` | `RW` | `RW` | `R` | `RW` | -| `shared/` | `RW` | `RW` | `R` | `RW` | -| `projects/*/src/` | `RW` | `RW` | `R` | `RW` | -| `projects/*/tests/` | `R` | `-` | `RW` | `RW` | -| `projects/*/docs/` | `RW` | `RW` | `R` | `RW` | -| `review/*/task.md` | `RW` | `R` | `R` | `RW` | -| `review/*/acceptance.md` | `RW` | `RW` | `RW` | `RW` | -| `review/*/impact.md` | `RW` | `RW` | `-` | `RW` | -| `review/*/feedback/` | `R` | `R` | `RW` | `RW` | -| `reports/` | `R` | `-` | `RW` | `RW` | -| `.github/` | `-` | `-` | `-` | `RW` | - -> **解析优先级**：当同一条路径被多个规则匹配时，`forbidden > read_only > allowed`。禁止规则永远优先。 -> -> **默认行为**：任何未出现在上表中的路径，默认禁止所有 AI 访问（等效于 `-`）。 - ---- - -## 沟通规范 - -### Dev AI → QA AI -在 `review/{task_id}/` 目录提交： -- **验收标准** (`acceptance.md`) - 明确测试目标 -- **变更影响范围** (`impact.md`) - 指导回归测试 -- **环境准备** 参考项目级 `ENVIRONMENT.md` - -### QA AI → Dev AI -在 `review/{task_id}/feedback/` 目录提交： -- **测试结果报告** (`round{round}.md`) -- **Bug清单** - 列出问题和严重程度 -- **改进建议** - 代码优化建议 - ---- - -## 命名规范 - -### 项目命名 -``` -P01_项目名称 # P01 表示项目编号 -``` - -### 任务编号 -``` -P01-001 # P01 项目编号 + 001 任务编号 -``` - -### 分支命名 -``` -feature/P01-001-login # 功能开发 -bugfix/P01-001-password # Bug修复 -test/P01-001-testcases # 测试用例 -``` - -### 提交信息 -``` -feat(P01-001): 实现用户登录功能 -fix(P01-001): 修复密码验证问题 -docs(P01-001): 更新接口文档 -test(P01-001): 添加登录测试用例 -``` - ---- - -## AI 配置文件说明 - -| 文件 | 说明 | -|------|------| -| `.ai/config/architect.json` | Arch AI 配置（权限、职责） | -| `.ai/config/coder.json` | Dev AI 配置（权限、职责） | -| `.ai/config/tester.json` | QA AI 配置（权限、职责） | -| `.ai/config/workflow.json` | 工作流配置（阶段、触发器） | -| `.ai/prompts/coding/` | 编码提示词模板 | -| `.ai/prompts/testing/` | 测试提示词模板 | -EOF - -# 3. 创建 README.md -cat > README.md << 'EOF' -# AI 协作项目 - -一个"人+3AI"协作模式的 AI 辅助编程项目仓库。 - ---- - -## 目录结构 - -``` -. -├── AGENTS.md # AI角色定义+权限约定+工作流 -├── README.md -├── .gitignore -├── .ai/ # AI协作核心配置 -│ ├── config/ -│ │ ├── architect.json # Arch AI 配置 -│ │ ├── coder.json # Dev AI 配置 -│ │ ├── tester.json # QA AI 配置 -│ │ └── workflow.json # 工作流配置 -│ └── prompts/ -│ ├── coding/ # 编码提示词模板 -│ └── testing/ # 测试提示词模板 -├── docs/ # 项目级总体文档 -├── tools/ # 开发工具脚本 -├── data/ # 训练数据 -├── projects/ # 项目代码 -│ ├── P01_app/ # 主应用项目 -│ │ ├── src/ # 业务代码 (Dev AI) -│ │ ├── tests/ # 测试代码 (QA AI) -│ │ ├── docs/ # 项目文档 (Dev AI) -│ │ └── ENVIRONMENT.md # 项目级环境准备 -│ └── P02_training/ # AI训练项目 -│ ├── src/ -│ ├── tests/ -│ ├── docs/ -│ └── ENVIRONMENT.md -├── review/ # 交接中心 -│ ├── active/ # 活跃任务 -│ └── archived/ # 已完成任务（按季度归档） -├── shared/ # 共享资源 -│ ├── scripts/ -│ ├── templates/ -│ └── utils/ -├── reports/ # 统一报告 -│ ├── test-results/ -│ └── quality-reports/ -└── .github/ # CI/CD配置 - └── workflows/ -``` - ---- - -## 团队角色 - -| 角色 | 是谁 | 干什么 | 不干什么 | -|------|------|--------|----------| -| **人类负责人** | 你 | 下指令、审阅、做决策、定验收标准 | 不写代码、不写测试 | -| **Arch AI** | Claude/TRAE/元宝等 | 需求分析、架构设计、技术选型、跨模块协调 | 不写测试 | -| **Dev AI** | Claude/TRAE/元宝等 | 写业务代码+文档、修bug、写impact | 不动tests/、不跑测试 | -| **QA AI** | 扣子编程AI | 写测试、跑测试、写反馈 | 不动src/、不改业务代码 | - ---- - -## 工作流程 - -1. **Arch AI** 分析需求，输出 `docs/01_产品需求/PRD.md` 和 `review/active/P01-001/task.md` -2. **Arch AI** 设计架构，输出 `docs/02_系统架构/`、`acceptance.md`、`impact.md` -3. **Dev AI** 在 `projects/P01_app/src/` 写代码，在 `docs/` 写文档 -4. **你**审一眼，没问题就触发QA AI -5. **QA AI** 读 `task.md` + `acceptance.md` + `impact.md`，按 `ENVIRONMENT.md` 准备环境，在 `tests/` 写测试并执行，写 `feedback/round1.md` -6. **有bug** → 你看反馈 → 让Dev AI修 → 回到步骤3（round2） - **通过** → 你确认 → 任务关闭，报告归档到 `reports/` - ---- - -## 任务状态流转 - -``` -TODO → IN_PROGRESS → REVIEW → DONE → ARCHIVED（移入archived/季度目录） -``` - -`task.md` 中添加状态字段： -``` -status: TODO | IN_PROGRESS | REVIEW | DONE | ARCHIVED -``` -EOF - -# 4. 创建 .gitignore -cat > .gitignore << 'EOF' -# Dependencies -node_modules/ -vendor/ -__pycache__/ -*.pyc -*.pyo -venv/ - -# Build outputs -dist/ -build/ -*.log -*.out - -# IDE -.vscode/ -.idea/ -*.swp -*.swo - -# OS -Thumbs.db -.DS_Store - -# Environment variables -.env -.env.local -.env.*.local -.env.production - -# Test reports -reports/test-results/*.json -reports/test-results/*.xml - -# Model files -models/ -*.pt -*.pth -*.onnx - -# Data files -data/ -*.csv -*.jsonl - -# Temporary files -*.tmp -*.temp -*.bak -EOF - -# 5. 创建 AI 配置文件（新版：含 read_only_paths、forbidden_paths、description） -cat > .ai/config/architect.json << 'EOF' -{ - "name": "Arch AI", - "role": "架构设计师", - "description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。", - "responsibilities": [ - "需求分析和产品规划", - "系统架构设计", - "技术选型和评估", - "跨模块协调和集成", - "编写架构文档", - "定义验收标准", - "评估变更影响", - "维护共享资源", - "维护开发工具", - "维护训练数据", - "指导 Dev AI 和 QA AI 工作" - ], - "allowed_paths": [ - "docs/", - "shared/", - "projects/*/src/", - "projects/*/docs/", - "review/*/acceptance.md", - "review/*/impact.md", - "review/*/task.md", - "tools/", - "data/" - ], - "read_only_paths": [ - ".ai/", - "projects/*/tests/", - "reports/", - "review/*/feedback/" - ], - "forbidden_paths": [], - "prompt_templates": { - "architecture": ".ai/prompts/architecture/", - "documentation": ".ai/prompts/architecture/" - } -} -EOF - -cat > .ai/config/coder.json << 'EOF' -{ - "name": "Dev AI", - "role": "代码开发者", - "description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。", - "responsibilities": [ - "编写业务代码", - "生成技术文档", - "定义验收标准", - "评估变更影响", - "维护共享资源" - ], - "allowed_paths": [ - "projects/*/src/", - "projects/*/docs/", - "shared/", - "review/*/acceptance.md", - "review/*/impact.md" - ], - "read_only_paths": [ - "review/*/task.md", - "review/*/feedback/" - ], - "forbidden_paths": [ - "projects/*/tests/", - "reports/" - ], - "prompt_templates": { - "coding": ".ai/prompts/coding/", - "documentation": ".ai/prompts/coding/" - } -} -EOF - -cat > .ai/config/tester.json << 'EOF' -{ - "name": "QA AI", - "role": "测试工程师", - "description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。", - "responsibilities": [ - "编写测试用例", - "执行测试", - "生成测试报告", - "提供反馈" - ], - "allowed_paths": [ - "projects/*/tests/", - "reports/", - "review/*/acceptance.md", - "review/*/feedback/" - ], - "read_only_paths": [ - "projects/*/src/", - "projects/*/docs/", - "docs/", - "data/", - "shared/", - "review/*/task.md", - "review/*/acceptance.md" - ], - "forbidden_paths": [ - ".ai/", - "tools/", - "review/*/impact.md", - "review/*/feedback/" - ], - "prompt_templates": { - "testing": ".ai/prompts/testing/" - } -} -EOF - -cat > .ai/config/workflow.json << 'EOF' -{ - "workflow": "human-ai-collaboration", - "roles": ["human", "arch-ai", "dev-ai", "qa-ai"], - "stages": [ - { - "name": "需求分析", - "actor": "arch-ai", - "output": ["docs/01_产品需求/PRD.md", "review/{task_id}/task.md"] - }, - { - "name": "架构设计", - "actor": "arch-ai", - "input": ["docs/01_产品需求/PRD.md", "review/{task_id}/task.md"], - "output": ["docs/02_系统架构/", "review/{task_id}/impact.md", "review/{task_id}/acceptance.md"] - }, - { - "name": "开发实现", - "actor": "dev-ai", - "input": ["review/{task_id}/task.md", "review/{task_id}/acceptance.md"], - "output": ["projects/*/src/", "projects/*/docs/"] - }, - { - "name": "测试验证", - "actor": "qa-ai", - "input": ["review/{task_id}/task.md", "review/{task_id}/acceptance.md"], - "output": ["projects/*/tests/", "reports/test-results/", "review/{task_id}/feedback/round{round}.md"] - }, - { - "name": "验收确认", - "actor": "human", - "input": ["review/{task_id}/feedback/", "reports/test-results/"] - } - ], - "retry": { - "max_rounds": 3, - "loop": ["测试验证", "开发实现"], - "escalation": { - "trigger": "第 3 轮测试仍有 BLOCKER 或 HIGH 级别 Bug", - "action": "暂停任务流转，等待人类负责人裁决" - }, - "skip_acceptance_on_retry": true - }, - "ci_triggers": { - "on_push_to_main": ["run-tests", "generate-reports"], - "on_pr_open": ["run-tests", "code-review"], - "on_task_update": ["notify-qa-ai"] - } -} -EOF - -# 6. 创建提示词模板 -mkdir -p .ai/prompts/architecture - -cat > .ai/prompts/coding/README.md << 'EOF' -# Dev AI 提示词库 - -| 文件 | 说明 | -|------|------| -| [code-style.md](code-style.md) | 代码风格、命名规范、目录组织 | -| [doc-template.md](doc-template.md) | impact.md / acceptance.md 等文档模板 | -EOF - -cat > .ai/prompts/testing/README.md << 'EOF' -# QA AI 提示词库 - -| 文件 | 说明 | -|------|------| -| [bug-report.md](bug-report.md) | 测试反馈 / Bug 报告模板与格式规范 | -EOF - -cat > .ai/prompts/architecture/README.md << 'EOF' -# Arch AI 提示词库 - -| 文件 | 说明 | -|------|------| -| [architecture-design.md](architecture-design.md) | 架构设计模板与规范 | -| [tech-selection.md](tech-selection.md) | 技术选型评估模板 | -EOF - -cat > .ai/prompts/coding/code-style.md << 'EOF' -# Dev AI 代码风格规范 - -## 适用技术栈 - -| 层 | 技术 | 语言 | -|-----|------|------| -| 前端 | Taro 4 + React 18 | TypeScript 5.x | -| 样式 | Tailwind CSS 4 | — | -| 后端 | NestJS 10 | TypeScript 5.x | -| 训练 | PyTorch 2.0 | Python 3.10+ | - ---- - -## 1. 文件命名 - -| 类型 | 规则 | 示例 | -|------|------|------| -| 页面组件 | kebab-case | `error-detail.tsx` | -| UI 组件 | kebab-case | `button.tsx` | -| 工具函数 | kebab-case | `format-date.ts` | -| 类型定义 | kebab-case | `error-entry.d.ts` | -| NestJS 模块 | kebab-case | `auth.module.ts` | -| Python 模块 | snake_case | `data_loader.py` | - -## 2. 目录组织（前端） - -``` -src/ -├── pages/{page-name}/ # 页面 —— 一个目录一个页面 -│ ├── index.tsx -│ ├── index.config.ts -│ └── index.css -├── components/ # 通用组件 -│ └── {component-name}/ -│ └── index.tsx -├── lib/ # 工具函数、hooks -├── types/ # 全局类型声明 -├── server/ # NestJS 后端 -└── config/ # Taro 构建配置 -``` - -## 3. 目录组织（NestJS 后端） - -``` -src/server/src/ -├── modules/{name}/ # 一个模块一个目录 -│ ├── {name}.module.ts -│ ├── {name}.controller.ts -│ ├── {name}.service.ts -│ ├── dto/ -│ └── entities/ -├── common/ # 共享：拦截器、守卫、管道 -└── main.ts -``` - -## 4. 命名风格 - -**TypeScript：** -- 组件：PascalCase —— `ErrorCard` -- 函数/变量：camelCase —— `getUserProfile` -- 常量：UPPER_SNAKE —— `MAX_PAGE_SIZE` -- 接口/类型：PascalCase —— `ErrorEntry` - -**Python：** -- 类：PascalCase —— `DataLoader` -- 函数/变量：snake_case —— `load_dataset` -- 常量：UPPER_SNAKE —— `BATCH_SIZE` - -## 5. 导入顺序（TypeScript） - -``` -1. 第三方库 -2. Taro 相关 -3. 项目内部（@/ 别名） -4. 相对路径 -5. 样式文件 -``` - -## 6. 组件规范 - -- 优先使用函数组件，不用 class 组件 -- 一个文件只有一个 export default 组件 -- 组件 props 必须声明类型接口 -- 跨端兼容：避免使用 `document`、`window`（用 Taro API 代替） - -## 7. API 调用规范 - -- 前端统一使用 `@/network.ts` 中的 `Network.request`，不要直接调用 `Taro.request` -- 后端Controller 只做参数校验和路由，业务逻辑放在 Service -- API 响应统一使用 Envelope 格式 `{ code, msg, data }` - -## 8. 不能做的事 - -- 不要在 `src/` 下写测试文件（测试在 `tests/`） -- 不要引入未经 package.json 声明的依赖 -- 不要在组件中硬编码后端地址（用 `PROJECT_DOMAIN` 全局变量） -EOF - -cat > .ai/prompts/coding/doc-template.md << 'EOF' -# Dev AI 文档模板 - -下面三个模板用于 Dev AI 在 `review/{task_id}/` 下产出标准化文件。 - ---- - -## A. impact.md 模板（变更影响范围） - -```markdown -# {TASK_ID} - 变更影响范围 - -## 修改的文件 -| 文件路径 | 修改类型 | 影响等级 | -|---------|---------|---------| -| projects/P01_soc_sw_app/src/server/src/modules/auth/auth.service.ts | 新增 | HIGH | -| projects/P01_soc_sw_app/src/server/src/modules/auth/dto/login.dto.ts | 新增 | MEDIUM | - -> 影响等级：HIGH=核心逻辑变更 | MEDIUM=新增文件 | LOW=注释/格式 - -## 影响的功能模块 -- [x] 用户认证模块 -- [ ] 芯片验证模块（无影响） - -## 需要回归测试的场景 -- 场景1: 用户登录成功流程 -- 场景2: 密码错误返回 401 -- 场景3: Token 过期后刷新 - -## 环境依赖变更 -- 新增依赖: bcrypt, @nestjs/jwt -- 数据库迁移: 新增 users 表 -``` - -**要点：** -- `修改的文件` 必须使用从仓库根目录开始的完整路径 -- 影响等级要实事求是，不要全写 HIGH -- `需要回归测试的场景` 要写**用户视角**的场景，不是代码内部细节 - ---- - -## B. acceptance.md 模板（验收标准） - -```markdown -# {TASK_ID} - 验收标准 - -## 功能验收 -- [ ] 用户可以注册新账户（邮箱+密码） -- [ ] 密码强度不足时提示明确错误信息 -- [ ] 登录成功返回有效 JWT Token - -## 非功能验收 -- [ ] API 响应时间 < 200ms -- [ ] 密码使用 bcrypt 加密存储 -- [ ] JWT Token 有效期 24 小时 - -## 测试覆盖要求 -- 单元测试覆盖率: >= 80% -- 集成测试覆盖率: >= 60% -- E2E 测试场景: >= 3 个 - -## 验收通过条件 -- 所有功能点验证通过 -- 测试覆盖率达标 -- 无重大安全漏洞 -``` - -**要点：** -- 功能验收用「用户可以…」句式，让 QA AI 和人类都能看懂 -- 每个功能点对应 task.md 里的一项交付物 -- 非功能验收写具体的可测量指标，不要写「性能好」「代码整洁」 - ---- - -## C. 没有 task.md 模板 - -task.md 由人类负责人创建，Dev AI 只读不写。Dev AI 如需补充技术细节，写在 impact.md 的「技术备注」段落中，不要直接修改 task.md。 -EOF - -cat > .ai/prompts/testing/bug-report.md << 'EOF' -# QA AI Bug 报告模板 - -以下模板用于 QA AI 在 `review/{task_id}/feedback/round{round}.md` 中提交测试反馈。 - ---- - -## 模板 - -```markdown -# {TASK_ID} - 第 {N} 轮测试反馈 - -## 基本信息 -- 测试时间: YYYY-MM-DD -- 测试项目: P01_soc_sw_app / P02_soc_sw_training / P03_soc_sw_web -- 测试环境: Node 20.x / Python 3.10 - -## 测试结果概览 -| 指标 | 数值 | -|------|------| -| 测试用例总数 | N | -| 通过 | N | -| 失败 | N | -| 跳过 | N | -| 代码覆盖率 | XX% | - -## 失败用例清单 - -### Bug #1: {简短标题} -- **严重程度**: BLOCKER / HIGH / MEDIUM / LOW -- **涉及文件**: `projects/...`（完整路径） -- **测试场景**: 用户登录时输入正确密码 -- **预期结果**: 返回 200 和 JWT Token -- **实际结果**: 返回 500 Internal Server Error -- **复现步骤**: - 1. POST /api/auth/login - 2. body: {"email": "test@example.com", "password": "correct"} -- **建议修复**: 检查 auth.service.ts 第 42 行的异常处理 - -### Bug #2: ... -（同上格式） - -## 改进建议（非 Bug） -- 建议 1: 登录接口缺少限流保护 -- 建议 2: 密码重置的邮件模板可以更友好 - -## 下一步 -- [ ] Dev AI 修复上述 Bug 后，QA AI 进行第 {N+1} 轮测试 -- [ ] 如第 3 轮仍未通过，升级给人类负责人裁决 -``` - ---- - -## 严重程度定义 - -| 级别 | 含义 | 举例 | -|------|------|------| -| BLOCKER | 核心功能不可用，无法继续测试 | 登录接口直接崩溃、数据库连不上 | -| HIGH | 功能逻辑错误，用户无法正常使用 | 登录成功但不返回 Token | -| MEDIUM | 功能可用但与预期有偏差 | 返回的日期格式不对、错误码不对 | -| LOW | 不影响功能的瑕疵 | 提示文案不友好、缺少空值校验 | - -## 规则 - -1. **每轮反馈用新文件**：`round1.md` → `round2.md` → `round3.md` -2. **最多 3 轮**：第 3 轮仍有 BLOCKER/HIGH Bug → 在报告中标注「建议人类负责人介入」 -3. **涉及文件必须用完整路径**：从仓库根目录开始，方便 Dev AI 定位 -4. **改进建议不要超过 3 条**：聚焦最重要的 -EOF - -# 7. 创建示例任务 -cat > review/active/P01-001/task.md << 'EOF' -# P01-001 - 示例任务 - -## 任务信息 -- 任务编号：P01-001 -- 项目：P01_app -- 创建时间：2026-05-22 -- 负责人：Dev AI -- 状态：TODO - -## 任务描述 -这是一个示例任务，展示任务单的结构。实际使用时请替换为真实需求。 - -## 交付物 -- `projects/P01_app/src/` 下的业务代码 -- `projects/P01_app/docs/` 下的技术文档 -EOF - -cat > review/active/P01-001/acceptance.md << 'EOF' -# P01-001 - 验收标准 - -## 功能验收 -- [ ] 功能点 1 -- [ ] 功能点 2 - -## 非功能验收 -- [ ] API 响应时间 < 200ms - -## 测试覆盖要求 -- 单元测试覆盖率: >= 80% - -## 验收通过条件 -- 所有功能点验证通过 -- 测试覆盖率达标 -EOF - -cat > review/active/P01-001/impact.md << 'EOF' -# P01-001 - 变更影响范围 - -## 修改的文件 -| 文件路径 | 修改类型 | 影响等级 | -|---------|---------|---------| -| projects/P01_app/src/example.ts | 新增 | HIGH | - -## 影响的功能模块 -- [x] 示例模块 - -## 需要回归测试的场景 -- 场景1: 示例功能正常使用 - -## 环境依赖变更 -- 无 -EOF - -cat > review/active/P01-001/feedback/round1.md << 'EOF' -# P01-001 - 第一轮测试反馈 - -## 基本信息 -- 测试时间: 2026-05-22 -- 测试项目: P01_app -- 测试环境: 待配置 - -## 测试结果概览 -| 指标 | 数值 | -|------|------| -| 测试用例总数 | 0 | -| 通过 | 0 | -| 失败 | 0 | -| 跳过 | 0 | -| 代码覆盖率 | 0% | - -## 反馈 -待 Dev AI 完成开发后执行测试 -EOF - -# 8. 创建 P01-002 示例任务（占位） -mkdir -p review/active/P01-002/feedback - -cat > review/active/P01-002/task.md << 'EOF' -# P01-002 - 待创建 - -## 任务信息 -- 任务编号：P01-002 -- 项目：P01_app -- 状态：TODO - -## 任务描述 -待人类负责人创建 -EOF - -cat > review/active/P01-002/acceptance.md << 'EOF' -# P01-002 - 验收标准 - -待 Dev AI 补充 -EOF - -cat > review/active/P01-002/impact.md << 'EOF' -# P01-002 - 变更影响范围 - -待 Dev AI 补充 -EOF - -echo "# feedback" > review/active/P01-002/feedback/README.md - -# 9. 创建 CROSS-001 跨项目任务（占位） -mkdir -p review/active/CROSS-001/feedback - -cat > review/active/CROSS-001/task.md << 'EOF' -# CROSS-001 - 跨项目任务 - -## 任务信息 -- 任务编号：CROSS-001 -- 项目：多个项目 -- 状态：TODO - -## 任务描述 -待人类负责人创建 -EOF - -cat > review/active/CROSS-001/acceptance.md << 'EOF' -# CROSS-001 - 验收标准 - -待 Dev AI 补充 -EOF - -cat > review/active/CROSS-001/impact.md << 'EOF' -# CROSS-001 - 变更影响范围 - -待 Dev AI 补充 -EOF - -echo "# feedback" > review/active/CROSS-001/feedback/README.md - -# 10. 创建项目环境文件 -cat > projects/P01_app/ENVIRONMENT.md << 'EOF' -# P01_app - 环境准备 - -## 依赖 -- Node.js >= 20.x -- pnpm >= 9.0.0 - -## 安装 -pnpm install - -## 运行 -pnpm dev -EOF - -cat > projects/P02_training/ENVIRONMENT.md << 'EOF' -# P02_training - 环境准备 - -## 依赖 -- Python >= 3.10 -- PyTorch >= 2.0 -- CUDA >= 11.8 (GPU训练) - -## 安装 -pip install -r requirements.txt -EOF - -# 11. 创建占位文件 -echo "# src" > projects/P01_app/src/README.md -echo "# tests" > projects/P01_app/tests/README.md -echo "# docs" > projects/P01_app/docs/README.md - -echo "# src" > projects/P02_training/src/README.md -echo "# tests" > projects/P02_training/tests/README.md -echo "# docs" > projects/P02_training/docs/README.md - -echo "# scripts" > shared/scripts/README.md -echo "# templates" > shared/templates/README.md -echo "# utils" > shared/utils/README.md - -echo "# test-results" > reports/test-results/README.md -echo "# quality-reports" > reports/quality-reports/README.md - -echo "# workflows" > .github/workflows/README.md - -echo "# 2026-Q2 archived tasks" > review/archived/2026-Q2/README.md - -echo "✅ AI 协作框架创建成功！" -echo "📖 请阅读 AGENTS.md 了解协作规则" -echo "🚀 在 review/active/ 下创建你的第一个真实任务开始开发" -``` - -## 使用场景 - -**何时调用此 skill：** -- ✅ 启动新的 AI 辅助编程项目 -- ✅ 需要建立标准化的 AI 协作流程 -- ✅ 团队开始使用"1 人+2AI"模式 - -**不适用场景：** -- ❌ 纯人工开发项目 -- ❌ 已有现成的协作框架 - -## 后续步骤 - -skill 执行后： -1. 阅读 `AGENTS.md` 了解协作规则和权限体系 -2. 检查 `review/active/P01-001/` 示例任务结构 -3. 根据实际需求修改 `AGENTS.md` 中的技术栈说明 -4. 在 `review/active/` 下创建第一个真实任务 -5. 开始协作开发 - ---- - -**Version**: 3.0 -**Created**: 2026-05-23 -**Updated**: 2026-05-23 -**Based On**: SoC_SW AI Programming Project -**Changes from v2.2**: -- 新增 Arch AI（架构AI）角色，形成"1 人+3AI"协作模式 -- 新增 .ai/config/architect.json 配置文件 -- 新增架构设计阶段，工作流从 4 阶段扩展为 5 阶段 -- 权限矩阵增加 Arch AI 列 -- 新增 .ai/prompts/architecture/ 提示词目录 \ No newline at end of file diff --git a/hwd32h757/.trae/skills/git/SKILL.md b/hwd32h757/.trae/skills/git/SKILL.md deleted file mode 100644 index f6e0d3e..0000000 --- a/hwd32h757/.trae/skills/git/SKILL.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -name: "git" -description: "Wraps common git operations as parameterized actions. Invoke when user wants to commit, push, pull, branch, or check git status." ---- - -# Git Skill - -## 功能 - -将常用 git 操作封装为参数化动作，避免频繁手动提交，统一管理版本控制。 - -## 触发条件 - -- 用户要求提交代码 -- 用户要求查看状态/日志/差异 -- 用户要求创建/切换分支 -- 用户要求拉取/推送代码 -- 用户要求回退/重置 - -## 参数说明 - -| 参数 | 说明 | 示例 | -|------|------|------| -| `action` | 操作类型 | status, add, commit, push, pull, branch, log, diff, stash, reset | -| `message` | 提交信息（commit 时必填） | "feat(P01-001): 实现用户登录" | -| `branch` | 分支名（branch/push/pull 时使用） | feature/P01-001-login | -| `files` | 指定文件（add 时使用，默认全部） | ["src/login.ts", "tests/login.test.ts"] | -| `force` | 强制操作（push/reset 时使用） | true/false | -| `count` | 日志条数（log 时使用） | 10 | - -## 操作类型 - -### 1. status - 查看状态 - -```bash -git status -git status -s # 简洁模式 -``` - -**输出**：显示已修改、已暂存、未跟踪的文件 - -### 2. add - 添加文件 - -```bash -git add -A # 添加所有变更 -git add # 添加指定文件 -git add -p # 交互式选择（逐块确认） -``` - -### 3. commit - 提交 - -**提交信息格式**（必须遵循 AGENTS.md 命名规范）： -``` -(): - - - -