diff --git a/.doc/architecture-v2-overview.png b/.doc/architecture-v2-overview.png new file mode 100644 index 0000000..47f27c2 Binary files /dev/null and b/.doc/architecture-v2-overview.png differ diff --git a/.opencode/README.md b/.opencode/README.md index d46ca0a..61041d4 100644 --- a/.opencode/README.md +++ b/.opencode/README.md @@ -1,242 +1,179 @@ -# OpenCode Agents 配置 +# OpenCode Agent Team V2 配置 -本目录包含为 [OpenCode](https://opencode.ai) 配置的专业 AI 代理。 +本目录包含为 [OpenCode](https://opencode.ai) 配置的多 Agent 协作团队，采用 **PM 中心化调度 + Skill 知识注入 + MCP 能力扩展** 的架构模式。 ## 📁 目录结构 ``` .opencode/ -└── agents/ - ├── team.md # 项目经理与团队协调者（主 Agent） - ├── planning.md # 技术架构与规划专家 - ├── frontend.md # 前端架构与 UI/UX 专家 - ├── umi-pro.md # UmiJS + ProComponents 专家 - ├── code-spec.md # 代码规范与质量专家 - └── qa-tester.md # 质量保证测试专家 +├── agents/ # 🟢 角色定义 (Agents) +│ ├── team.md # 👑 Team Coordinator (PM) — 主 Agent +│ ├── planning.md # 🧠 技术架构师 — 只读规划 +│ ├── frontend.md # ⚡ 全栈开发专家 — 编码实施 +│ ├── code-spec.md # 🔍 代码审计专家 — 规范审查 +│ └── qa-tester.md # 🧪 QA 测试专家 — 功能验证 +│ +└── skills/ # 🔵 能力定义 (Skills) + ├── tech-stack/ # 🛠️ 技术栈规范 + │ └── umijs-procomponents/ # UmiJS + ProComponents 开发约束 + ├── design/ # 🎨 设计规范 + │ └── visual-standards/ # 视觉标准 (主题色、布局、按钮样式) + ├── business/ # 💼 业务域规则 + │ ├── content-management/ # 内容管理 + │ ├── order-management/ # 订单管理 + │ └── product-management/ # 产品管理 + └── engineering/ # 🛡️ 通用工程规范 + └── code-quality/ # 代码质量红线 ``` -## 🎯 主 Agent（Primary） - -### Team Coordinator (`team`) - -**角色**: 项目经理和团队协调者 -**模式**: Primary（主代理） -**权限**: 完全访问 -**职责**: - -- 理解和 clarify 用户需求 -- 拆分任务为合理的子任务 -- 协调所有子 Agent 按正确顺序工作 -- 管理开发流程和进度 -- 在关键检查点停止并征求用户意见 -- **唯一有权开始和结束会话的 Agent** - -**使用方式**: 这是默认的主 Agent，直接与用户对话，无需特殊调用。 - --- -## 🤖 子 Agent（Subagents） +## 👑 主 Agent — Team Coordinator (`team`) -所有子 Agent 只能被主 Agent (`team`) 调用，通过 `@agent-name` 方式。子 Agent 完成任务后必须将结果交回主 Agent，不能自行结束会话或调用其他 Agent。 +| 属性 | 值 | +| :------- | :------------------- | +| **角色** | 项目经理与团队协调者 | +| **模式** | Primary（主代理） | +| **权限** | 禁止编码，仅做调度 | + +**核心职责**: + +- 📋 **需求理解与拆分**: 深入理解用户需求，拆解为子任务 +- 🔍 **Skill 扫描与注入**: 扫描 `skills/` 目录，匹配相关 Skill 并注入子 Agent 指令 +- 🎨 **Figma 设计提取**: 当有 Figma 链接时，提取产品信息与设计规范 +- 🏗️ **团队动态组装**: 根据技术栈选择合适的开发 Agent +- 🛑 **检查点管控**: 规划完成后必须停下等待用户确认 +- 🔄 **质量闭环**: 实施 → 审计 → 测试，问题回派修复直到通过 + +**关键规则**: + +- ❌ 禁止亲自编码 +- ❌ 禁止独自修复问题（必须回派给开发 Agent） +- ❌ 禁止跳过规划阶段 +- ❌ 禁止允许子 Agent 自行结束会话 + +--- + +## 🤖 子 Agent 池 + +所有子 Agent 只能被主 Agent (`team`) 调用。子 Agent 完成任务后必须将结果交回主 Agent，不能自行结束会话或调用其他 Agent。 ### 1. Planning Agent (`@planning`) -**角色**: 技术架构师和规划专家 -**模式**: Subagent（子代理） -**权限**: 只读（不可编辑代码） -**用途**: +| 属性 | 值 | +| :----------- | :-------------------------------------- | +| **角色** | 技术架构师与规划专家 | +| **权限** | 🔒 **只读**（禁止编辑任何文件） | +| **MCP 依赖** | Context7（查询文档）、Figma（提取设计） | -- 深度分析用户需求和代码库 -- 生成详细的实施计划和技术方案 -- API 契约驱动开发规划 -- 技术选型建议 - -**调用方式**: - -``` -@planning 分析这个需求并给出详细的实施计划 -``` - ---- +**用途**: 深度需求分析、架构设计、API 契约定义、技术选型建议 ### 2. Frontend Expert (`@frontend`) -**角色**: 前端架构师和 UI/UX 专家 -**模式**: Subagent（子代理） -**权限**: 完全访问（可编辑代码） -**用途**: +| 属性 | 值 | +| :----------- | :------------------------ | +| **角色** | 全栈开发专家 | +| **权限** | ✅ 完全访问（可编辑代码） | +| **MCP 依赖** | Context7（查询文档） | -- 高端 UI/UX 实现 -- Ant Design & ProComponents 开发 -- Design Tokens 样式化 -- 前端性能优化 +**用途**: UmiJS + ProComponents 全栈开发（服务层 / Mock / UI）、Ant Design 组件实现 -**调用方式**: +### 3. Code Spec Expert (`@code-spec`) -``` -@frontend 实现一个符合 Ant Design 规范的产品列表页面 -``` +| 属性 | 值 | +| :------- | :------------------------ | +| **角色** | 代码审计与规范专家 | +| **权限** | ✅ 完全访问（可修复代码） | + +**用途**: 代码规范审查、安全审计（XSS、认证、财务计算）、TypeScript 类型检查 + +### 4. QA Tester (`@qa-tester`) + +| 属性 | 值 | +| :----------- | :---------------------------------- | +| **角色** | 质量保证与测试专家 | +| **权限** | 🔒 有限（仅 bash，不可编辑代码） | +| **MCP 依赖** | Chrome DevTools（浏览器自动化测试） | + +**用途**: 功能测试、i18n 检查、UI/UX 质量审计、运行时错误检测 --- -### 3. Umi Pro Agent (`@umi-pro`) +## 📚 Skill 知识库 -**角色**: UmiJS 和 ProComponents 专家 -**模式**: Subagent（子代理） -**权限**: 完全访问（可编辑代码） -**用途**: +Skill 是**可插拔的知识块**，由 PM 在阶段 0 动态扫描、匹配并注入给子 Agent。每个 Skill 包含一个 `SKILL.md` 文件，定义了具体的约束和规范。 -- 快速 ProComponents 实施 -- UmiJS 框架约定和最佳实践 -- Mock 数据和服务层开发 -- 国际化实现 - -**调用方式**: - -``` -@umi-pro 创建一个包含搜索功能的商品管理表格 -``` +| 分类 | Skill | 说明 | +| :-- | :-- | :-- | +| 🛠️ **技术栈** | `umijs-procomponents` | UmiJS 4 + ProComponents 开发规范、Zero CSS 策略、request 协议 | +| 🎨 **设计** | `visual-standards` | 视觉标准：主题色 Volcano Red、布局规范、按钮样式 | +| 💼 **业务** | `content-management` | 内容管理业务规则 | +| 💼 **业务** | `order-management` | 订单管理业务规则与状态机 | +| 💼 **业务** | `product-management` | 产品管理业务规则 | +| 🛡️ **工程** | `code-quality` | 代码质量红线：禁止 any、500 行限制、TS 严格模式 | --- -### 4. Code Spec Expert (`@code-spec`) +## 🔌 MCP 依赖 -**角色**: 代码规范和质量专家 -**模式**: Subagent（子代理） -**权限**: 完全访问（可编辑代码） -**用途**: +本 Agent 团队依赖以下 MCP 服务器来扩展能力： -- 执行 Ant Design 和 ProComponents 最佳实践 -- 代码审查和重构 -- 安全审计（XSS、认证、财务计算） -- 类型安全检查 - -**调用方式**: - -``` -@code-spec 审查这个组件是否符合 Ant Design 规范 -``` +| MCP Server | 必需性 | 用途 | 调用方 | +| :-- | :-- | :-- | :-- | +| **Context7** | 🔴 必需 | 查询官方文档、避免 API 幻觉 | @planning, @frontend | +| **Chrome DevTools** | 🔴 必需 | QA 浏览器自动化测试 | @qa-tester | +| **Figma Dev Mode** | 🟡 可选 | 提取 Figma 设计数据 | PM（阶段 0）, @planning | --- -### 5. QA Tester (`@qa-tester`) - -**角色**: 质量保证和测试专家 -**模式**: Subagent（子代理） -**权限**: 有限（仅 bash，不可编辑代码） -**用途**: - -- 功能测试和验证 -- i18n 国际化检查 -- UI/UX 质量审计 -- 运行时错误检测 - -**调用方式**: +## 🔄 协作流程 ``` -@qa-tester 测试产品列表页面的所有功能 +用户需求 + ↓ +[阶段 0] PM: 上下文采集 → Skill 匹配 → Figma 提取 → 团队组装 + ↓ +[阶段 1] @planning: 架构规划（注入 Skill 摘要） + ↓ +🛑 用户确认检查点 + ↓ +[阶段 2] @frontend: 开发实施（注入完整 Skill 约束） + ↓ +[阶段 3] @code-spec: 代码审计 → 不通过则回派修复 + ↓ +[阶段 4] @qa-tester: 功能测试 → 不通过则回派修复 + ↓ +[阶段 5] PM: 最终验收 → ✅ 交付 ``` +### 质量闭环 + +- 审计不通过 → 回派 @frontend 修复 → 重新审计 +- 测试不通过 → 回派 @frontend 修复 → 重新审计 → 重新测试 +- **严禁跳过复测** + --- -## 🎯 核心设计理念 +## 🔧 配置格式 -所有代理都遵循以下核心原则： - -### 1. "Separated Card" 设计模式 - -- **< 4 个搜索字段**: 使用 `ProTable` 内置 `search` -- **>= 4 个搜索字段**: 使用独立 `QueryFilter` 组件 - -### 2. 强制样式 Tokens - -```typescript -{ - background: token.colorBgContainer, // 白色背景 - padding: token.paddingLG, // 24px - borderRadius: token.borderRadius, // 6px - marginBottom: token.marginLG, // 24px - // 无 boxShadow - 扁平化设计 -} -``` - -### 3. 零 CSS 文件政策 - -所有样式必须通过 Ant Design Design Tokens 内联实现。 - -### 4. ProComponents 优先 - -- 列表 → `ProTable` -- 表单 → `ProForm` / `QueryFilter` / `ModalForm` -- 布局 → `ProLayout` / `PageContainer` - -### 5. 严格 TypeScript - -无 `any` 类型，所有接口定义在 `data.d.ts`。 - -### 6. 强制国际化 - -所有用户可见字符串必须使用 `intl.formatMessage` 并包含 `defaultMessage`。 - ---- - -## 📋 使用示例 - -### 典型开发流程 - -1. **规划阶段**: - - ``` - @planning 我需要创建一个文章管理系统，包含列表、编辑和删除功能 - ``` - -2. **实施阶段**: - - ``` - @umi-pro 根据计划实现服务层和 Mock 数据 - @frontend 实现文章列表页面的 UI - ``` - -3. **审查阶段**: - - ``` - @code-spec 审查新创建的文章管理代码 - ``` - -4. **测试阶段**: - ``` - @qa-tester 测试文章管理的所有功能并验证 i18n - ``` - ---- - -## 🔧 配置说明 - -### Markdown 格式 - -每个代理使用 Markdown 文件定义，包含 YAML frontmatter： +每个 Agent 使用 Markdown 文件定义，包含 YAML frontmatter： ```markdown --- description: 代理描述 -mode: subagent -model: anthropic/claude-sonnet-4-20250514 +mode: subagent # primary | subagent temperature: 0.2 tools: - write: true - edit: true - bash: true + write: true # 文件写入权限 + edit: true # 文件编辑权限 + bash: true # 终端命令权限 --- -# 代理提示内容 +# Agent 提示内容 ... ``` -### JSON 格式 - -同时提供了 `opencode.json` 配置文件，可以在项目根目录使用。 - --- ## 📚 相关文档 @@ -250,10 +187,6 @@ tools: ## 🚀 版本信息 +- **架构版本**: V2 (PM 中心化 + Skill 注入 + MCP 扩展) - **创建时间**: 2026-02-14 -- **OpenCode 版本**: 最新 -- **模型**: Claude Sonnet 4 (anthropic/claude-sonnet-4-20250514) - ---- - -**维护者**: Antigravity Team +- **最后更新**: 2026-02-16 diff --git a/.opencode/agents/team.md b/.opencode/agents/team.md index 9f04d33..aaa0378 100644 --- a/.opencode/agents/team.md +++ b/.opencode/agents/team.md @@ -74,31 +74,31 @@ tools: ```mermaid graph TD - User([用户需求]) --> Phase0[PM: 需求上下文采集] + User(["用户需求"]) --> Phase0["PM: 需求上下文采集"] subgraph 阶段 0 - PM 决策层 - Phase0 --> SkillScan[扫描 .opencode/skills/ 分类匹配] - SkillScan --> SkillClassify[分类: 技术栈 + 业务 + 通用] - Phase0 --> FigmaCheck{有 Figma?} - FigmaCheck -->|是| FigmaExtract[Figma: 产品信息 + 设计规范] - FigmaCheck -->|否| NoFigma[无 Figma] - SkillClassify --> TeamSelect[根据技术栈选择开发 Agent] - SkillClassify --> Merge[构建决策上下文包] + Phase0 --> SkillScan["扫描 .opencode/skills/ 分类匹配"] + SkillScan --> SkillClassify["分类: 技术栈 + 业务 + 通用"] + Phase0 --> FigmaCheck{"有 Figma?"} + FigmaCheck -->|是| FigmaExtract["Figma: 产品信息 + 设计规范"] + FigmaCheck -->|否| NoFigma["无 Figma"] + SkillClassify --> TeamSelect["根据技术栈选择开发 Agent"] + SkillClassify --> Merge["构建决策上下文包"] FigmaExtract --> Merge NoFigma --> Merge TeamSelect --> Merge end - Merge -->|上下文包 + Skill 摘要| Phase1[@planning: 架构规划] - Phase1 --> Checkpoint{🛑 用户确认} - Checkpoint -->|未通过| Phase1 - Checkpoint -->|已通过| Phase2[开发 Agent: 实施] - Phase2 --> Phase3[@code-spec: 代码审计] - Phase3 -->|失败| Phase2 - Phase3 -->|通过| Phase4[@qa-tester: 功能测试] - Phase4 -->|失败| Phase2 - Phase4 -->|通过| PM_End{PM: 最终验收} - PM_End --> Delivery([✅ 交付]) + Merge -->|"上下文包 + Skill 摘要"| Phase1["@planning: 架构规划"] + Phase1 --> Checkpoint{"🛑 用户确认"} + Checkpoint -->|"未通过"| Phase1 + Checkpoint -->|"已通过"| Phase2["开发 Agent: 实施"] + Phase2 --> Phase3["@code-spec: 代码审计"] + Phase3 -->|"失败"| Phase2 + Phase3 -->|"通过"| Phase4["@qa-tester: 功能测试"] + Phase4 -->|"失败"| Phase2 + Phase4 -->|"通过"| PM_End{"PM: 最终验收"} + PM_End --> Delivery(["✅ 交付"]) subgraph 迭代修复闭环 Phase2 diff --git a/README.md b/README.md index 8819301..53d6ae6 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,18 @@ 系统由 **Team Coordinator (PM)** 统一调度，通过动态组装 **Agent 池** 中的专业角色，并结合 **Skill 知识库** 来完成复杂研发任务。 +![Architecture Overview](.doc/architecture-v2-overview.png) + ```mermaid -graph TD User(["👤 用户"]) <--> PM["👑 Team Coordinator (PM)"] + subgraph "External Resources (MCP Protocol)" + MCP_Context7["📚 Context7
(Docs/Lib)"] + MCP_Chrome["🌐 Chrome
(Testing)"] + MCP_Figma["🎨 Figma
(Design)"] + MCP_Files["📂 Filesystem
(IO)"] + end + subgraph "Skill Knowledge Base (技能知识库)" TechSkill["🛠️ Tech Stack Skills"] BizSkill["💼 Business Skills"] @@ -36,6 +44,16 @@ graph TD Frontend -.->|遵循| TechSkill & BizSkill CodeSpec -.->|审计依据| TechSkill & BizSkill QATester -.->|验收依据| TechSkill & BizSkill + + %% MCP Calling Relations + Planning & Frontend & CodeSpec & QATester -->|"🛠️ 调用能力"| MCP_Files + Planning -->|"🎨 提取设计"| MCP_Figma + Frontend & Planning -->|"📚 查询文档"| MCP_Context7 + QATester -->|"🧪 操控浏览器"| MCP_Chrome + + %% Skill to MCP Relations + TechSkill -.->|"依赖文档"| MCP_Context7 + BizSkill -.->|"关联设计"| MCP_Figma ``` ---