From 6c09a9b6d4fbaf7f466fff5457d69545f2ab5c65 Mon Sep 17 00:00:00 2001 From: tupingr Date: Tue, 26 May 2026 16:43:31 +0800 Subject: [PATCH] init. --- hwd32h757/.ai/config/architect.json | 38 + hwd32h757/.ai/config/coder.json | 37 + hwd32h757/.ai/config/tester.json | 33 + hwd32h757/.ai/config/workflow.json | 48 + hwd32h757/.ai/knowledge/lessons.md | 111 ++ hwd32h757/.ai/knowledge/patterns.md | 142 ++ hwd32h757/.ai/phases/INDEX.md | 17 + hwd32h757/.ai/principles.md | 91 ++ hwd32h757/.ai/prompts/architecture/README.md | 6 + .../architecture/architecture-design.md | 44 + .../architecture/technical-evaluation.md | 41 + hwd32h757/.ai/prompts/coding/README.md | 6 + hwd32h757/.ai/prompts/coding/code-style.md | 105 ++ hwd32h757/.ai/prompts/coding/doc-template.md | 76 ++ hwd32h757/.ai/prompts/testing/README.md | 5 + hwd32h757/.ai/prompts/testing/bug-report.md | 67 + hwd32h757/.ai/roles/README.md | 57 + hwd32h757/.ai/roles/arch/card.md | 43 + hwd32h757/.ai/roles/dev/card.md | 40 + hwd32h757/.ai/roles/qa/card.md | 42 + .../tasks/templates/TASK_TEMPLATE_CODER.md | 47 + .../tasks/templates/TASK_TEMPLATE_TESTER.md | 75 ++ .../.trae/skills/add-subproject/SKILL.md | 253 ++++ .../.trae/skills/ai-collab-setup/SKILL.md | 1183 +++++++++++++++++ hwd32h757/.trae/skills/git/SKILL.md | 173 +++ hwd32h757/.trae/skills/project-init/SKILL.md | 107 ++ .../.trae/skills/resume-context/SKILL.md | 195 +++ hwd32h757/.trae/skills/share-context/SKILL.md | 136 ++ hwd32h757/.trae/skills/switch-model/SKILL.md | 143 ++ .../.trae/skills/update-constitution/SKILL.md | 95 ++ hwd32h757/.trae/skills/update-docs/SKILL.md | 103 ++ hwd32h757/AGENTS.md | 119 ++ hwd32h757/DECISIONS.md | 16 + hwd32h757/ENVIRONMENT.md | 73 + hwd32h757/SYNC.md | 82 ++ hwd32h757/TEMPLATE.yaml | 37 + hwd32h757/dashboard.md | 102 ++ hwd32h757/docs/使用手册.md | 236 ++++ 38 files changed, 4224 insertions(+) create mode 100644 hwd32h757/.ai/config/architect.json create mode 100644 hwd32h757/.ai/config/coder.json create mode 100644 hwd32h757/.ai/config/tester.json create mode 100644 hwd32h757/.ai/config/workflow.json create mode 100644 hwd32h757/.ai/knowledge/lessons.md create mode 100644 hwd32h757/.ai/knowledge/patterns.md create mode 100644 hwd32h757/.ai/phases/INDEX.md create mode 100644 hwd32h757/.ai/principles.md create mode 100644 hwd32h757/.ai/prompts/architecture/README.md create mode 100644 hwd32h757/.ai/prompts/architecture/architecture-design.md create mode 100644 hwd32h757/.ai/prompts/architecture/technical-evaluation.md create mode 100644 hwd32h757/.ai/prompts/coding/README.md create mode 100644 hwd32h757/.ai/prompts/coding/code-style.md create mode 100644 hwd32h757/.ai/prompts/coding/doc-template.md create mode 100644 hwd32h757/.ai/prompts/testing/README.md create mode 100644 hwd32h757/.ai/prompts/testing/bug-report.md create mode 100644 hwd32h757/.ai/roles/README.md create mode 100644 hwd32h757/.ai/roles/arch/card.md create mode 100644 hwd32h757/.ai/roles/dev/card.md create mode 100644 hwd32h757/.ai/roles/qa/card.md create mode 100644 hwd32h757/.ai/tasks/templates/TASK_TEMPLATE_CODER.md create mode 100644 hwd32h757/.ai/tasks/templates/TASK_TEMPLATE_TESTER.md create mode 100644 hwd32h757/.trae/skills/add-subproject/SKILL.md create mode 100644 hwd32h757/.trae/skills/ai-collab-setup/SKILL.md create mode 100644 hwd32h757/.trae/skills/git/SKILL.md create mode 100644 hwd32h757/.trae/skills/project-init/SKILL.md create mode 100644 hwd32h757/.trae/skills/resume-context/SKILL.md create mode 100644 hwd32h757/.trae/skills/share-context/SKILL.md create mode 100644 hwd32h757/.trae/skills/switch-model/SKILL.md create mode 100644 hwd32h757/.trae/skills/update-constitution/SKILL.md create mode 100644 hwd32h757/.trae/skills/update-docs/SKILL.md create mode 100644 hwd32h757/AGENTS.md create mode 100644 hwd32h757/DECISIONS.md create mode 100644 hwd32h757/ENVIRONMENT.md create mode 100644 hwd32h757/SYNC.md create mode 100644 hwd32h757/TEMPLATE.yaml create mode 100644 hwd32h757/dashboard.md create mode 100644 hwd32h757/docs/使用手册.md diff --git a/hwd32h757/.ai/config/architect.json b/hwd32h757/.ai/config/architect.json new file mode 100644 index 0000000..c9bda53 --- /dev/null +++ b/hwd32h757/.ai/config/architect.json @@ -0,0 +1,38 @@ +{ + "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 new file mode 100644 index 0000000..ea52033 --- /dev/null +++ b/hwd32h757/.ai/config/coder.json @@ -0,0 +1,37 @@ +{ + "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 new file mode 100644 index 0000000..b231318 --- /dev/null +++ b/hwd32h757/.ai/config/tester.json @@ -0,0 +1,33 @@ +{ + "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 new file mode 100644 index 0000000..e61ceb5 --- /dev/null +++ b/hwd32h757/.ai/config/workflow.json @@ -0,0 +1,48 @@ +{ + "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 new file mode 100644 index 0000000..2413986 --- /dev/null +++ b/hwd32h757/.ai/knowledge/lessons.md @@ -0,0 +1,111 @@ +# 经验教训 + +## 目的 + +记录开发过程中学到的东西。每条记录包含： +- 上下文（我们在做什么） +- 问题（出了什么问题/什么让我们意外） +- 教训（学到了什么） +- 行动（因此改变了什么） + +--- + +## L-001: 单体 AGENTS.md 浪费 AI 上下文 + +**日期**: 2026-05-25 +**上下文**: 项目启动阶段，每次 AI 会话都需要读 AGENTS.md 来了解角色和权限 +**问题**: AGENTS.md 239 行，约 80% 内容与当前 AI 角色无关。AI 有效上下文被大量无关信息占据 +**教训**: 为人类设计的文档结构不适用于 AI 的信息获取模式。AI 需要"最少必要信息"，而不是"全局完整视图" +**行动**: 重构为分层信息架构：角色工作台 → 阶段上下文 → 知识沉淀。AI 只需读 2 个小文件即可开工 + +--- + +## L-002: 角色边界划分是 AI Agent 协作的反模式 + +**日期**: 2026-05-26 +**上下文**: Phase 1 收尾后，重新审视「1 人 + 3 AI」的 Arch/Dev/QA 角色划分架构。调研了 2025-2026 年业界最新实践（MegaAgent、Claude Code Agent Swarm、Devin、JiuwenSwarm、Microsoft 多 Agent 参考架构等） +**问题**: +- 按角色边界（Arch/Dev/QA）划分 Agent 导致协调成本急剧上升，Token 消耗是单体的 3-10 倍 +- Arch AI 承担了过多职责：架构设计 + 任务分配 + 文档维护 + 看板更新，成为单点瓶颈 +- `.ai/` 目录膨胀到 47 个文件，但 Phase 2 代码一行还没写——架构本身成了负担 +- Anthropic 和 Cognition（Devin）都承认：并行 Agent 在编码领域的实际收益有限，隐性决策冲突和整合成本往往超过并行收益 +**教训**: +1. **按业务上下文划分，而非按角色划分**。正确的做法是「用户认证流 Agent」拥有路由+数据库+前端组件，「芯片验证流 Agent」拥有数据采集+仿真+结果分析——每个 Agent 拥有完成任务所需的全部上下文 +2. **架构规模应与项目阶段匹配**。Phase 1 只有需求+设计，不需要 47 个配置文件。应该在需要时渐进式添加，而非提前搭建「完整」架构 +3. **调度层应该是确定性代码，而非 LLM**。用 LLM 做任务路由和状态更新是反模式——不稳定、成本高。这些应该用脚本/CI/工作流引擎实现 +4. **子 Agent 的甜蜜点是只读研究，而非并行编码**。隔离上下文中做信息收集然后压缩回传——这是验证最有效的模式 +5. **「高模型指挥小模型」的方向是对的，但规模要匹配**。1 人项目的「编排层」就是人类+Claude Code 本身，不需要额外的编排 Agent +**行动**: +- 启动 `.ai/` 配置精简审计，目标砍到 20 个文件以内 +- Arch AI 的 today.md 和 queue.md 合并，消除重复 +- Phase 3 前评估是否引入正式模型分层（Opus 做判断 → Sonnet/Haiku 做执行） +- 当前阶段保留角色划分但降低形式化程度，实际工作由 Claude Code 子 Agent 机制承载 + +--- + +## L-003: 知识库「生产者」流程缺失 + +**日期**: 2026-05-26 +**上下文**: 一次关于 Agent 架构的深度讨论产生了有价值的洞察（L-002 + ADR-011 + P-004），但发现把这些洞察写入知识库的动作没有 formalized 流程 +**问题**: `share-context` Skill 覆盖了知识库的「消费者」侧（.ai/knowledge/ → docs/share/），但「生产者」侧（开发讨论 → .ai/knowledge/）是断的。有价值的想法和教训可能因为没人记得写而丢失 +**教训**: 一条完整的信息流水线需要两端都 formalized：摄入端（什么时候写、写到哪里、怎么写）和输出端（什么时候翻译、翻译成什么）。目前只有输出端 +**行动**: +- 更新 `share-context` Skill，增加「反向检查」步骤：每次执行时先检查是否有未入库的讨论/想法 +- 建立触发条件：当讨论产生「可复用的判断」「反直觉的发现」「被验证的错误方向」时，主动记录 + +--- + +## L-005: Arch AI 上下文窗口是硬约束——盲目冲刺 = 带残缺记忆做决策 + +**日期**: 2026-05-26 +**上下文**: 持续数小时的高强度架构讨论（ADR-011、ADR-012、信息架构升级），Arch AI 的上下文窗口承载了全部对话历史 +**问题**: 复杂任务容易让人想「一口气做完」，但 Arch AI 的上下文窗口有限。做一半触发自动压缩 → 前面的讨论、决策细节、已排除的选项全部丢失 → 后续判断基于不完整记忆 → 决策质量崩盘 +**教训**: +1. **上下文不是无限的**。每次对话都是消耗品，越长的讨论越容易触发压缩 +2. **决策即记录**。每个判断产生后立即写入 knowledge/，不留在对话里。对话是易失的，文件是持久的 +3. **主动 checkpoint 优于被动压缩**。感觉吃力时主动收尾（commit + push），开新会话继续——带着干净记忆比带着残缺记忆强 +4. **拆分到可提交粒度**。大任务拆成独立子任务，每个子任务结束后 commit。即使后续会话压缩，已完成的部分已经落地 +**行动**: +- 写入 `.ai/principles.md` 作为 Arch AI 硬约束 +- 任务前评估上下文余量 +- 接近窗口上限时执行主动收尾协议：已完成 → commit → 告知人类进展 → 建议开新会话 + +--- + +## L-006: 当 AI 是执行者时，Skill 优于 Shell 脚本 + +**日期**: 2026-05-26 +**上下文**: ADR-008 的「双分支 + sync-template.sh」模板同步方案，在新架构升级后 ai_project 分支严重过时。用户要求把脱敏模板价值提取到 main，放弃独立分支 +**问题**: +- `sync-template.sh` 硬编码了旧架构的文件列表（DASHBOARD.md / ROADMAP.md / today.md / queue.md），框架一升级脚本就过时 +- 维护一个独立 Git 分支的成本 > 收益：需要手动切换分支、跑脚本、处理冲突 +- Shell 脚本的设计假设是「人类或 CI 执行」，但实际场景是 AI 执行。AI 不需要可执行脚本——AI 需要清晰的规格 +**教训**: +1. **「用什么执行」决定「用什么描述」**。人/CI 执行 → 写脚本。AI 执行 → 写 Skill（语义描述 + 约束 + 边界定义）。Skill 描述「方法」，不会因文件路径变化而过时 +2. **边界定义文件是长期资产，执行脚本是短期负债**。SYNC.md 定义了什么属于框架、什么属于项目——这个定义独立于任何执行方式。脚本绑定了执行方式，框架一变就废 +3. **让 Git 做版本管理，让 Skill 做逻辑执行**。不需要为「脱敏」这个逻辑维护一个独立分支，Skill 从当前 main 实时执行脱敏，永远不过时 +4. **3 文件 > 4 文件 + 1 分支**。新方案：SYNC.md + TEMPLATE.yaml + Skill。旧方案：SYNC.md + TEMPLATE.yaml + sync-template.sh + init.sh + ai_project 分支 +**行动**: +- ADR-008 标记废弃，新增 ADR-013 +- 废弃 sync-template.sh、init.sh、ai_project 分支 +- 保留并更新 SYNC.md（框架/项目边界），新增 TEMPLATE.yaml（变量定义），新增 project-init Skill + +--- + +## L-004: 跨平台 AI 协作下，文档是唯一的通信协议 + +**日期**: 2026-05-26 +**上下文**: 澄清了实际的三平台配置——Arch AI (Claude Code + DeepSeek V4 Pro)、Coder AI (Trae CN + GLM-4.6)、Tester AI (Coze CN)。之前的设计假设所有角色在同一个 AI 平台内切换，这一假设被推翻 +**问题**: +- 之前的架构分析得出了「精简文档」的结论（ADR-011），但这个结论基于错误的前提——以为所有 AI 共享同一个上下文空间 +- 实际场景中，三个平台的 AI 之间**零共享上下文**。Trae + GLM-4.6 不会知道 Claude Code 里讨论了什么，Coze 沙盒不会知道架构设计的动机 +- 如果把文档精简了，Coder AI 拿到的 task 就会缺失关键上下文，GLM-4.6 又没有能力自行推断 +**教训**: +1. **架构结论绑定于部署拓扑**。同一个设计，在「单平台多角色切换」和「跨平台多 Agent 协作」下是完全不同的东西。先搞清楚运行环境，再做架构决策 +2. **跨平台协作中，Git 仓库不是存储，是通信介质**。每个 commit 是一次消息传递，每个文件是一份消息体。消息必须自包含，接收方不能依赖「上次聊过」 +3. **任务交接密度必须适配接收方模型能力**。GLM-4.6 不是 Claude——不能给一个需要跨 5 个文件推理的任务。每个 task 应该是单文件或强内聚的 2-3 个文件 +4. **低能力模型不是劣势，是约束**。只能处理小范围任务 → 强迫架构设计更清晰 → 反而减少 bug。这就是「限制产生创造力」 +**行动**: +- 修正 ADR-011 的结论：不做精简，改为「重定位」——架构文档从内部备忘录升级为跨平台交接协议（ADR-012） +- Task 模板增加四个必填字段：输入、输出、约束、参考 ADR +- Dev queue.md 的每个任务需独立可读，不依赖前后文 diff --git a/hwd32h757/.ai/knowledge/patterns.md b/hwd32h757/.ai/knowledge/patterns.md new file mode 100644 index 0000000..29b7b83 --- /dev/null +++ b/hwd32h757/.ai/knowledge/patterns.md @@ -0,0 +1,142 @@ +# 可复用模式 + +## 目的 + +记录开发过程中发现的可持续复用的模式和做法。 +同样的模式出现 3 次以上时，应当记录在这里。 + +--- + +## P-001: AI 任务交接 (review/active/) + +**上下文**: AI 角色之间需要传递工作成果 +**问题**: 如何结构化任务交接，让任何 AI 都能接手 +**方案**: 标准化 `review/active/{任务ID}/` 结构： +- `task.md` — 任务描述（Arch AI 定义） +- `acceptance.md` — 验收标准（Arch AI + Dev AI + QA AI 共同维护） +- `impact.md` — 变更影响范围（Arch AI + Dev AI 评估） +- `feedback/` — 反馈记录（QA AI 提交） + +**何时用**: 每个跨 AI 角色的任务 +**何时不用**: 单角色任务（如纯文档更新、配置修改） + +--- + +## P-002: 角色工作台 (daily task board) + +**上下文**: AI 每次会话需要快速进入工作状态 +**问题**: 从头探索项目结构浪费时间 +**方案**: `.ai/roles/{role}/today.md` 每日任务清单，AI 只需读 2 个文件（card + today） +**何时用**: 每次 AI 会话 +**维护者**: Arch AI 负责分配，各 AI 自己更新完成状态 + +--- + +--- + +## P-003: 模板同步 (framework sync) + +**上下文**: 项目框架层（AGENTS/权限/提示词/工作流）的变化需要传播到通用模板分支 +**问题**: 手动同步耗时且容易遗漏，AI 重做去敏化消耗 ~100K tokens +**方案**: +- 双分支：`main`（具体项目）+ `ai_project`（通用模板） +- `SYNC.md` 明确定义框架层/项目层文件边界 +- `sync-template.sh` 自动 checkout 框架文件 + 重新应用 {{变量}} +- 框架层 ~15 个文件自动同步，project 层永久隔离 +**何时用**: main 分支框架有变化时 +**维护者**: Arch AI 触发，脚本执行 + +--- + +## P-004: 编排器-执行者模式 (Orchestrator-Worker) + +**上下文**: AI Agent 协作中，不同任务需要不同能力的模型。高能力模型（Opus）做规划和判断，低成本模型（Sonnet/Haiku）做执行 +**来源**: MegaAgent (NUS)、Claude Code Agent Swarm (Anthropic)、JiuwenSwarm (华为 openJiuwen)、Microsoft 多 Agent 参考架构 +**方案**: + +``` +决策层 (Opus) → 意图理解、方案设计、最终验收 (~10% Token, 最贵) +调度层 (代码) → 任务路由、负载均衡、重试熔断 (确定性代码, 不用 LLM!) +执行层 (Haiku) → 专注单一原子任务 (~60% Token, 最便宜) +``` + +**核心原则**: +1. 按业务上下文划分 Agent（「认证流 Agent」），而非按角色（「数据库 Agent」） +2. 调度层是确定性代码——用 LLM 做调度是反模式 +3. 子 Agent 的甜蜜点是只读研究/探索，并行编码效果不佳 +4. 写范围严格分离——并发写任务之间不能有重叠的文件所有权 +5. Agent 粒度围绕内聚能力组织——不要为「调用一个 API」建 Agent + +**何时用**: +- 团队规模 ≥ 3 个 AI Agent 并行工作 +- 任务可清晰分解为独立子任务，且协调成本 < 并行收益 +- 有明确的模型成本优化需求 + +**何时不用**: +- 1 人项目——编排层就是人类 + Claude Code 本身 +- 编码任务的并行化——行业共识是效果不佳 +- 简单 bug 修复——分解成本 > 直接修复成本 + +**本项目实例** (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 new file mode 100644 index 0000000..8eb19ac --- /dev/null +++ b/hwd32h757/.ai/phases/INDEX.md @@ -0,0 +1,17 @@ +# 阶段索引 + +| 阶段 | 名称 | 状态 | 目录 | +|------|------|------|------| +| 1 | 基础搭建 | DONE | `phase-01-foundation/` | +| 2 | MVP | ACTIVE | `phase-02-mvp/` | +| 3 | 功能完善 | PLANNED | `phase-03-features/` | +| 4 | 打磨发布 | PLANNED | `phase-04-polish/` | + +## 阶段切换规则 + +1. 当前阶段 completion.md 全部打勾 +2. 人类签字确认 +3. Arch AI 更新本索引文件 +4. Arch AI 更新所有角色 card.md（当前阶段字段） +5. Arch AI 更新 dashboard.md（进度条 + task 状态面板 + 最近事件） +6. 产出阶段复盘（docs/share/phase-NN/） diff --git a/hwd32h757/.ai/principles.md b/hwd32h757/.ai/principles.md new file mode 100644 index 0000000..eaa102f --- /dev/null +++ b/hwd32h757/.ai/principles.md @@ -0,0 +1,91 @@ +# 信息架构设计原则 + +## 为什么这样设计 + +AI 的上下文窗口有限。每个读入上下文的字都是成本。这套分层架构的核心思想：**每个角色只加载必要信息，按需展开细节。** + +## Token 预算 + +| 层级 | 预算 | 内容 | 加载时机 | +|------|------|------|----------| +| 入口（dashboard/card） | < 2K | 身份+全貌+任务 | 每次会话必读 | +| Task 文件 | < 1K | 单任务全部信息 | Coder/Tester 开工时 | +| 知识沉淀 (knowledge) | < 3K | 决策/模式/教训 | 按需加载 | +| 阶段上下文 (phase) | < 5K | 目标+范围+架构 | 按需加载 | + +## 信息分层（三层架构） + +``` +指挥层: dashboard.md → 人类 + Arch AI 唯一入口 +决策层: DECISIONS.md → 待人类决策事项 +执行层: .ai/tasks/active/ → Coder/Tester 各自 task 文件 +``` + +## 维护规则 + +1. **不超预算**：每个文件严格遵守 token 预算，超了就拆分 +2. **不重复状态**：状态只在一处记录（dashboard.md），其他地方引用 +3. **Git 管历史**：文档只描述"现在是什么"，历史由 Git 负责 +4. **一文一答**：每个文件独立回答一个问题，不需要串联阅读 +5. **角色无关设计**：任何 AI 模型都能通过读 card.md 快速接管角色 + +--- + +## AI 上下文资源管理（硬约束，适用于所有 AI 角色） + +**问题**：每个 AI 每次会话有上下文窗口限制。如果盲目冲刺大任务，到一半触发自动压缩，前面的讨论、决策细节、已排除的选项全部丢失——代价不是「重来」，是「用不完整的记忆做决策」。 + +### 通用规则（所有角色遵守） + +1. **任务前评估**：开始一个复杂任务前，先判断能否在自己的有效上下文内完成。不能 → 拆分到多个独立会话 +2. **做完一件再开始下一件**：不积累未完成的工作。阶段收尾了（commit + push），再启动下一个 +3. **决策即记录**：每个重要判断产生后，立即写入对应文件，不要留在对话里。对话是易失的，文件是持久的 +4. **接近窗口上限时主动收尾**：感觉上下文开始吃力时，主动 checkpoint——已完成写入文件、commit、告知人类当前进展和下一步。**宁可多开一个会话，不要带着残缺记忆继续** +5. **拆分到可提交粒度**：大任务拆成独立子任务。每个子任务结束后 git commit，确保即使后续会话压缩，已完成的部分不会丢失 + +### 角色特定约束 + +| 角色 | 主要风险 | 应对策略 | +|------|---------|---------| +| Arch AI (Claude Code) | 长对话积累上下文，架构讨论容易收不住 | 每个 ADR 产出后立即写入 decisions.md；感知吃力时主动收尾 | +| Coder AI (Trae + GLM-4.6) | 上下文窗口更小，多文件任务容易超出 | 每个 session 只做 1 个 task 文件；不读其他 task，不读架构文档 | +| Tester AI (Coze CN) | 沙盒执行时间有限 | 1 个 session 只测 1 个 T01-XXX task；报告立即写回 repo | + +### 信号识别（何时应立即执行规则 4） + +- 需要反复回看前面的讨论才能做判断 +- 开始忘记用户几分钟前说过的话 +- 回复质量出现可感知的下降 +- 同一个问题被重复提出 +- （Coder AI）需要同时修改 3 个以上文件才能完成 task + +### 反模式 + +- 「一口气做完再 commit」——做一半触发压缩，前面做的全丢 +- 「这个 task 简单，我顺便把下一个也做了」——超边界 = 超上下文 +- 「先放着，等会儿一起处理」——对话不等人，放着 = 丢了 + +--- + +## 文件约定 + +- 控制面板: `dashboard.md` +- 决策入口: `DECISIONS.md` +- 角色工作台: `.ai/roles/{role}/card.md` +- 执行任务: `.ai/tasks/active/` +- 阶段上下文: `.ai/phases/phase-NN-name/` +- 知识沉淀: `.ai/knowledge/` +- 提示词模板: `.ai/prompts/{domain}/` +- Skill 工具: `.trae/skills/` +- 框架边界: `SYNC.md` +- 模板变量: `TEMPLATE.yaml` + +## 阶段切换检查清单 + +切换阶段时 Arch AI 必须： +- [ ] 更新所有角色的 card.md（当前阶段字段） +- [ ] 更新 dashboard.md（进度条 + task 状态面板 + 最近事件） +- [ ] 更新 phases/INDEX.md +- [ ] 生成上一阶段的 completion.md +- [ ] 产出阶段复盘（docs/share/phase-NN/） +- [ ] 审计 token 预算 diff --git a/hwd32h757/.ai/prompts/architecture/README.md b/hwd32h757/.ai/prompts/architecture/README.md new file mode 100644 index 0000000..40c1e5c --- /dev/null +++ b/hwd32h757/.ai/prompts/architecture/README.md @@ -0,0 +1,6 @@ +# 架构提示词模板 + +| 文件 | 用途 | +|------|------| +| `architecture-design.md` | 系统架构设计模板 | +| `technical-evaluation.md` | 技术选型评估模板 | diff --git a/hwd32h757/.ai/prompts/architecture/architecture-design.md b/hwd32h757/.ai/prompts/architecture/architecture-design.md new file mode 100644 index 0000000..5f942fe --- /dev/null +++ b/hwd32h757/.ai/prompts/architecture/architecture-design.md @@ -0,0 +1,44 @@ +# 系统架构设计模板 + +## 输入 + +- 产品需求文档 (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 new file mode 100644 index 0000000..3e1f389 --- /dev/null +++ b/hwd32h757/.ai/prompts/architecture/technical-evaluation.md @@ -0,0 +1,41 @@ +# 技术选型评估模板 + +## 输入 + +- 需要解决的技术问题 +- 约束条件（预算、时间、团队、已有技术栈） + +## 输出结构 + +### 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 new file mode 100644 index 0000000..d4c0f7c --- /dev/null +++ b/hwd32h757/.ai/prompts/coding/README.md @@ -0,0 +1,6 @@ +# 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 new file mode 100644 index 0000000..d6c7317 --- /dev/null +++ b/hwd32h757/.ai/prompts/coding/code-style.md @@ -0,0 +1,105 @@ +# 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 new file mode 100644 index 0000000..03710d3 --- /dev/null +++ b/hwd32h757/.ai/prompts/coding/doc-template.md @@ -0,0 +1,76 @@ +# 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 new file mode 100644 index 0000000..70b0387 --- /dev/null +++ b/hwd32h757/.ai/prompts/testing/README.md @@ -0,0 +1,5 @@ +# 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 new file mode 100644 index 0000000..70c7d4d --- /dev/null +++ b/hwd32h757/.ai/prompts/testing/bug-report.md @@ -0,0 +1,67 @@ +# 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 new file mode 100644 index 0000000..208e127 --- /dev/null +++ b/hwd32h757/.ai/roles/README.md @@ -0,0 +1,57 @@ +# AI 角色工作台 + +## 三层架构 + +``` +控制面板 (dashboard.md) → 人类 + Arch AI 共享入口，项目唯一真实来源 + ↓ Arch AI 拆解任务 +执行层 (.ai/tasks/active/) → Coder/Tester 各自独立 task 文件，自包含 +``` + +## 四个角色入口 + +| 角色 | 平台+模型 | 入口 | 读几个文件 | +|------|----------|------|-----------| +| 人类 | — | [dashboard.md](../../dashboard.md) 顶部「人类区」 | 1 | +| Arch AI | Claude Code + DeepSeek V4 Pro | [dashboard.md](../../dashboard.md) 全文 | 1 | +| Coder AI | Trae CN + GLM-4.6 | [card.md](dev/card.md) → 对应 task 文件 | 2 | +| Tester AI | Coze CN | [card.md](qa/card.md) → 对应 task 文件 | 2 | + +## 使用方式 + +**Arch AI**: +``` +1. 读 dashboard.md → 了解全貌 + ADR 摘要 + task 状态 +2. 需要细节 → 按链接按需加载 +3. 人类决策 → 读 DECISIONS.md +4. 拆分新任务 → 按模板写 .ai/tasks/active/P01-XXX.md +5. 完成后 → 更新 dashboard.md task 状态 +``` + +**Coder AI (Trae + GLM-4.6)**: +``` +1. 读 card.md → 身份+权限 +2. 读对应 task 文件 → 输入/输出/约束/验收方法 +3. 写代码 +4. 自验 → 填写完成报告 → commit [READY_FOR_TEST] +``` + +**Tester AI (Coze)**: +``` +1. git pull + 读 card.md +2. git log --grep="READY_FOR_TEST" → 找待测 task +3. 读对应 Tester task 文件 → 测试内容/执行方式/报告格式 +4. 拉代码 → 沙盒执行 → 生成 JSON 报告 +5. commit 报告 +``` + +## 关键原则 + +1. **每个角色只有一个入口文件** — 不拼图，不切换 +2. **Worker AI 不需要知道项目全貌** — task 文件就是它的全部世界 +3. **Git 是唯一的集成总线** — 跨平台交接通过 commit message 信号 +4. **弱模型适配强约束** — 给 GLM-4.6 的任务 = 单文件粒度，零隐含上下文 + +## 归档 + +旧的 DASHBOARD.md / ROADMAP.md / roles/*/today.md / roles/*/queue.md → `.ai/archive/` diff --git a/hwd32h757/.ai/roles/arch/card.md b/hwd32h757/.ai/roles/arch/card.md new file mode 100644 index 0000000..1901626 --- /dev/null +++ b/hwd32h757/.ai/roles/arch/card.md @@ -0,0 +1,43 @@ +# Arch AI — 架构师 + +## 身份 + +我是架构 AI。负责需求分析、架构设计、技术选型、任务分解。 + +**平台**: Claude Code + DeepSeek V4 Pro（最强推理 + Agent 框架） + +## 启动流程 + +1. 读 `dashboard.md` 全文（< 2K tokens）→ 项目全貌 + ADR 索引 + task 状态面板 +2. 需要细节 → 按 dashboard 中的链接按需加载 +3. 人类决策 → 读 `DECISIONS.md` +4. 完成任务 → 更新 dashboard.md + 对应 ADR/knowledge 文件 + +## 当前阶段 + +Phase 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 new file mode 100644 index 0000000..67a882b --- /dev/null +++ b/hwd32h757/.ai/roles/dev/card.md @@ -0,0 +1,40 @@ +# Dev AI — 开发者 + +## 身份 + +我是开发 AI。负责编写业务代码、技术文档、Bug 修复。 + +**平台**: Trae CN + GLM-4.6（代码生成 + 文件操作，单文件粒度） + +## 启动流程 + +1. 读本文件（card.md）→ 我是谁、权限、当前阶段 +2. 读 dashboard.md → 找到自己对应的 task（状态为 `todo` 的 Coder 任务） +3. 打开对应 task 文件（如 `.ai/tasks/active/P01-001.md`）→ **这就是你的全部世界** +4. 按 task 文件中的「输入」「输出」「约束」「验收方法」执行 +5. 完成后 → 填写 task 文件的「完成报告」→ commit（message 含 `[READY_FOR_TEST]`） + +**不需要**读 ADR 全文、知识库、或其他 task 文件。你的 task 文件已经包含了完成任务所需的全部信息。 + +## 当前阶段 + +Phase 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 new file mode 100644 index 0000000..d44e0dc --- /dev/null +++ b/hwd32h757/.ai/roles/qa/card.md @@ -0,0 +1,42 @@ +# QA AI — 测试者 + +## 身份 + +我是测试 AI。负责在 Coze 沙盒中拉取代码、执行测试、生成报告。 + +**平台**: Coze CN（沙盒执行 + 自动化测试） + +## 启动流程 + +1. 读本文件（card.md）→ 我是谁、权限 +2. `git pull` → 拉取最新代码 +3. `git log --oneline --grep="READY_FOR_TEST"` → 查找待测试的 task +4. 打开对应 Tester task 文件（如 `.ai/tasks/active/T01-XXX.md`）→ **这就是你的全部世界** +5. 按 task 文件中的「测试目标」「测试内容」「执行方式」执行 +6. 生成测试报告 → `reports/{编号}-{日期}.json` +7. 填写 task 文件的「完成报告」→ commit + +**关键**: 你不需要知道项目全貌、不需要读架构文档、不需要读 ADR。你的 task 文件 + 被测代码 = 你需要的一切。 + +## 当前阶段 + +Phase 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 new file mode 100644 index 0000000..af50f98 --- /dev/null +++ b/hwd32h757/.ai/tasks/templates/TASK_TEMPLATE_CODER.md @@ -0,0 +1,47 @@ +# Task {编号}: {标题} + +## 元信息 + +| 字段 | 值 | +|------|-----| +| 状态 | `todo` → `in_progress` → `done` → `tested` → `accepted` | +| 优先级 | P0 / P1 / P2 | +| 依赖 | {上游 task 编号，无则写「无」} | +| 分配给 | Coder AI (Trae CN + GLM-4.6) | + +## 输入 + +**要读的文件**: +- `{完整路径}` — {一句话说明} + +**参考的 ADR**: +- ADR-XXX: {一句话说明关联} + +**上游依赖产出**: +- {上游 task 编号}: {产出是什么} + +## 输出 + +**要生成/修改的文件**: +- `{完整路径}` — {说明} +- `{完整路径}` — {说明} + +**验收方法**: +```bash +{具体命令或步骤，Coder 可以自己跑来验证} +``` + +## 约束 + +- 不碰: `{目录路径}` +- 技术栈: {库/版本} +- 遵循: `{规范文件}` + +## 完成报告 + +> Coder 完成后填写。Commit message 以 `[READY_FOR_TEST]` 结尾。 + +- [ ] 输出文件已生成 +- [ ] 验收命令通过 +- [ ] Commit: `{hash}` +- [ ] Commit message: `feat({编号}): {描述} [READY_FOR_TEST]` diff --git a/hwd32h757/.ai/tasks/templates/TASK_TEMPLATE_TESTER.md b/hwd32h757/.ai/tasks/templates/TASK_TEMPLATE_TESTER.md new file mode 100644 index 0000000..ca51a48 --- /dev/null +++ b/hwd32h757/.ai/tasks/templates/TASK_TEMPLATE_TESTER.md @@ -0,0 +1,75 @@ +# Task {编号}: {标题} + +## 元信息 + +| 字段 | 值 | +|------|-----| +| 状态 | `todo` → `in_progress` → `done` → `accepted` | +| 优先级 | P0 / P1 / P2 | +| 对应 Coder task | {P01-XXX} | +| 分配给 | Tester AI (Coze CN) | + +## 测试目标 + +{一句话 —— 验证什么功能/模块} + +## 被测对象 + +**Coder 产出的 commit**: +- 从 git log 查找 commit message 包含 `[READY_FOR_TEST]` 且 task 编号为 `{编号}` 的最新 commit +- 或直接读 `.ai/roles/dev/card.md` 里指定的代码目录 + +**Coder task 文件**: +- [P01-XXX]({路径}) — 理解该 task 的输入/输出/约束 + +## 测试内容 + +**关键路径**: +- [ ] {关键路径 1} +- [ ] {关键路径 2} +- [ ] {边界条件} + +**不应发生的**: +- [ ] {错误情况 1} + +## 执行方式 + +``` +1. git pull → 拉取最新代码 +2. 在 Coze 沙盒中执行测试 +3. 生成测试报告 +``` + +## 报告格式 + +输出 `reports/{编号}-{日期}.json`: + +```json +{ + "task": "{编号}", + "date": "{YYYY-MM-DD}", + "summary": { + "total": {N}, + "passed": {N}, + "failed": {N} + }, + "results": [ + { + "case": "{用例名}", + "status": "pass|fail", + "details": "{失败时的详细信息}" + } + ], + "conclusion": "PASS|FAIL|RETRY" +} +``` + +## 完成报告 + +> Tester 完成后填写。 + +- [ ] 测试已执行 +- [ ] 报告已生成 → `reports/{编号}-{日期}.json` +- [ ] Commit: `{hash}` +- [ ] Commit message: `test({编号}): {结论}` +- [ ] 结论: PASS / FAIL / RETRY diff --git a/hwd32h757/.trae/skills/add-subproject/SKILL.md b/hwd32h757/.trae/skills/add-subproject/SKILL.md new file mode 100644 index 0000000..6405a52 --- /dev/null +++ b/hwd32h757/.trae/skills/add-subproject/SKILL.md @@ -0,0 +1,253 @@ +--- +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 new file mode 100644 index 0000000..483ffca --- /dev/null +++ b/hwd32h757/.trae/skills/ai-collab-setup/SKILL.md @@ -0,0 +1,1183 @@ +--- +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 new file mode 100644 index 0000000..f6e0d3e --- /dev/null +++ b/hwd32h757/.trae/skills/git/SKILL.md @@ -0,0 +1,173 @@ +--- +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 命名规范）： +``` +(): + + + +