agent/.opencode/README.md

# OpenCode Agent Team V2 配置

本目录包含为 [OpenCode](https://opencode.ai) 配置的多 Agent 协作团队，采用 **PM 中心化调度 + Skill 知识注入 + MCP 能力扩展** 的架构模式。

## 📁 目录结构

```
.opencode/
├── 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 — Team Coordinator (`team`)

| 属性     | 值                   |
| :------- | :------------------- |
| **角色** | 项目经理与团队协调者 |
| **模式** | Primary（主代理）    |
| **权限** | 禁止编码，仅做调度   |

**核心职责**:

- 📋 **需求理解与拆分**: 深入理解用户需求，拆解为子任务
- 🔍 **Skill 扫描与注入**: 扫描 `skills/` 目录，匹配相关 Skill 并注入子 Agent 指令
- 🎨 **Figma 设计提取**: 当有 Figma 链接时，提取产品信息与设计规范
- 🏗️ **团队动态组装**: 根据技术栈选择合适的开发 Agent
- 🛑 **检查点管控**: 规划完成后必须停下等待用户确认
- 🔄 **质量闭环**: 实施 → 审计 → 测试，问题回派修复直到通过

**关键规则**:

- ❌ 禁止亲自编码
- ❌ 禁止独自修复问题（必须回派给开发 Agent）
- ❌ 禁止跳过规划阶段
- ❌ 禁止允许子 Agent 自行结束会话

---

## 🤖 子 Agent 池

所有子 Agent 只能被主 Agent (`team`) 调用。子 Agent 完成任务后必须将结果交回主 Agent，不能自行结束会话或调用其他 Agent。

### 1. Planning Agent (`@planning`)

| 属性         | 值                                      |
| :----------- | :-------------------------------------- |
| **角色**     | 技术架构师与规划专家                    |
| **权限**     | 🔒 **只读**（禁止编辑任何文件）         |
| **MCP 依赖** | Context7（查询文档）、Figma（提取设计） |

**用途**: 深度需求分析、架构设计、API 契约定义、技术选型建议

### 2. Frontend Expert (`@frontend`)

| 属性         | 值                        |
| :----------- | :------------------------ |
| **角色**     | 全栈开发专家              |
| **权限**     | ✅ 完全访问（可编辑代码） |
| **MCP 依赖** | Context7（查询文档）      |

**用途**: UmiJS + ProComponents 全栈开发（服务层 / Mock / UI）、Ant Design 组件实现

### 3. Code Spec Expert (`@code-spec`)

| 属性     | 值                        |
| :------- | :------------------------ |
| **角色** | 代码审计与规范专家        |
| **权限** | ✅ 完全访问（可修复代码） |

**用途**: 代码规范审查、安全审计（XSS、认证、财务计算）、TypeScript 类型检查

### 4. QA Tester (`@qa-tester`)

| 属性         | 值                                  |
| :----------- | :---------------------------------- |
| **角色**     | 质量保证与测试专家                  |
| **权限**     | 🔒 有限（仅 bash，不可编辑代码）    |
| **MCP 依赖** | Chrome DevTools（浏览器自动化测试） |

**用途**: 功能测试、i18n 检查、UI/UX 质量审计、运行时错误检测

---

## 📚 Skill 知识库

Skill 是**可插拔的知识块**，由 PM 在阶段 0 动态扫描、匹配并注入给子 Agent。每个 Skill 包含一个 `SKILL.md` 文件，定义了具体的约束和规范。

| 分类 | Skill | 说明 |
| :-- | :-- | :-- |
| 🛠️ **技术栈** | `umijs-procomponents` | UmiJS 4 + ProComponents 开发规范、Zero CSS 策略、request 协议 |
| 🎨 **设计** | `visual-standards` | 视觉标准：主题色 Volcano Red、布局规范、按钮样式 |
| 💼 **业务** | `content-management` | 内容管理业务规则 |
| 💼 **业务** | `order-management` | 订单管理业务规则与状态机 |
| 💼 **业务** | `product-management` | 产品管理业务规则 |
| 🛡️ **工程** | `code-quality` | 代码质量红线：禁止 any、500 行限制、TS 严格模式 |

---

## 🔌 MCP 依赖

本 Agent 团队依赖以下 MCP 服务器来扩展能力：

| MCP Server | 必需性 | 用途 | 调用方 |
| :-- | :-- | :-- | :-- |
| **Context7** | 🔴 必需 | 查询官方文档、避免 API 幻觉 | @planning, @frontend |
| **Chrome DevTools** | 🔴 必需 | QA 浏览器自动化测试 | @qa-tester |
| **Figma Dev Mode** | 🟡 可选 | 提取 Figma 设计数据 | PM（阶段 0）, @planning |

---

## 🔄 协作流程

```
用户需求
    ↓
[阶段 0] PM: 上下文采集 → Skill 匹配 → Figma 提取 → 团队组装
    ↓
[阶段 1] @planning: 架构规划（注入 Skill 摘要）
    ↓
🛑 用户确认检查点
    ↓
[阶段 2] @frontend: 开发实施（注入完整 Skill 约束）
    ↓
[阶段 3] @code-spec: 代码审计 → 不通过则回派修复
    ↓
[阶段 4] @qa-tester: 功能测试 → 不通过则回派修复
    ↓
[阶段 5] PM: 最终验收 → ✅ 交付
```

### 质量闭环

- 审计不通过 → 回派 @frontend 修复 → 重新审计
- 测试不通过 → 回派 @frontend 修复 → 重新审计 → 重新测试
- **严禁跳过复测**

---

## 🔧 配置格式

每个 Agent 使用 Markdown 文件定义，包含 YAML frontmatter：

```markdown
---
description: 代理描述
mode: subagent # primary | subagent
temperature: 0.2
tools:
  write: true # 文件写入权限
  edit: true # 文件编辑权限
  bash: true # 终端命令权限
---

# Agent 提示内容

...
```

---

## 📚 相关文档

- [OpenCode 官方文档](https://opencode.ai/docs/zh-cn/agents/)
- [Ant Design 官方文档](https://ant.design/)
- [ProComponents 官方文档](https://procomponents.ant.design/)
- [UmiJS 官方文档](https://umijs.org/)

---

## 🚀 版本信息

- **架构版本**: V2 (PM 中心化 + Skill 注入 + MCP 扩展)
- **创建时间**: 2026-02-14
- **最后更新**: 2026-02-16