docs: update README, .opencode README and fix mermaid syntax in team agent

2026-02-16 13:48:30 +08:00
parent aae9eb9aea
commit 44246bbe50
4 changed files with 162 additions and 211 deletions
--- a/.doc/architecture-v2-overview.png
+++ b/.doc/architecture-v2-overview.png
--- 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
--- 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
--- 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<br>(Docs/Lib)"]
+        MCP_Chrome["🌐 Chrome<br>(Testing)"]
+        MCP_Figma["🎨 Figma<br>(Design)"]
+        MCP_Files["📂 Filesystem<br>(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
 ```

 ---