# Agent Team V2 架构视图

本文档描述了当前 Agent 团队的协作模式、核心机制与防护体系。

## 1. 宏观架构视图

系统由 **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"]
        EngSkill["🛡️ Engineering Skills"]
    end

    subgraph "Agent Pool (能力池)"
        Planning["🧠 @planning<br>技术架构师"]
        Frontend["⚡ @frontend<br>全栈开发专家"]
        CodeSpec["🔍 @code-spec<br>代码审计专家"]
        QATester["🧪 @qa-tester<br>QA 测试专家"]
    end

    PM -- "1. 扫描与提取" --> TechSkill
    PM -- "1. 扫描与提取" --> BizSkill
    PM -- "1. 扫描与提取" --> EngSkill

    PM -- "2. 动态组装 & 任务委派" --> Planning
    PM -- "3. 任务委派" --> Frontend
    PM -- "4. 任务委派" --> CodeSpec
    PM -- "5. 任务委派" --> QATester

    Planning -.->|遵循| TechSkill & BizSkill
    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
```

---

## 2. 全生命周期协作流

采用 **"PM 中心化调度 + 阶段性闭环"** 的工作流。PM 负责上下文流转，杜绝子 Agent 直接通信。

```mermaid
sequenceDiagram
    participant User as 👤 User
    participant PM as 👑 Team Coordinator
    participant Skill as 📚 Skill System
    participant Planning as 🧠 @planning
    participant Dev as ⚡ @frontend
    participant Review as 🔍 @code-spec
    participant QA as 🧪 @qa-tester

    Note over PM: Phase 0: 上下文采集
    User->>PM: 提出需求
    PM->>Skill: 扫描 .opencode/skills/
    Skill-->>PM: 返回匹配的 Skill (例如 UmiJS, 订单管理)
    PM->>PM: 构建「决策上下文包」

    Note over PM, Planning: Phase 1: 架构规划
    PM->>Planning: 委派规划 (注入 Skill 摘要 + Figma)
    Planning-->>PM: 返回架构设计方案
    PM->>User: 🛑 检查点：展示方案并确认
    User->>PM: 批准继续

    Note over PM, Dev: Phase 2: 实施开发
    PM->>Dev: 委派开发 (注入完整 Skill 约束)
    Dev->>Dev: 查询 Context7 / 编写代码
    Dev-->>PM: 提交代码与实施报告

    loop 质量闭环 (Phase 3 & 4)
        PM->>Review: 委派代码审计
        Review-->>PM: 返回审计报告 (P0/P1 问题)

        alt 审计不通过
            PM->>Dev: 回派修复问题
            Dev-->>PM: 修复完成
        else 审计通过
            PM->>QA: 委派功能测试
            QA-->>PM: 返回测试报告

            alt 测试不通过
                PM->>Dev: 回派修复 Bug
                Dev-->>PM: 修复完成
                Note right of PM: 修复后必须重新审计
            end
        end
    end

    Note over PM: Phase 5: 交付
    PM->>User: ✅ 最终交付 (代码 + 测试报告)
```

---

## 3. 三层防护体系

通过三层机制确保 AI 行为可控、代码质量达标、技术规范落地。

```mermaid
graph BT
    subgraph "Layer 3: 协议控制层 (Protocol Layer)"
        L3_1[统一汇报格式]
        L3_2[禁止子Agent结束会话]
        L3_3[PM 终审权]
        L3_4[Skill 注入协议]
    end

    subgraph "Layer 2: 动态规范层 (Skill Layer)"
        L2_1[Tech: UmiJS/ProComponents 规范]
        L2_2[Biz: 业务状态机/数据模型]
        L2_3[Eng: 组件500行/TS严格模式]
    end

    subgraph "Layer 1: 静态红线层 (Redline Layer)"
        L1_1["禁止 API 幻觉 (Context7 强制)"]
        L1_2["禁止 XSS / 浮点金额计算"]
        L1_3["禁止直接修改非代码文件"]
        L1_4["只读模式 (@planning)"]
    end

    L1_1 --> L2_1
    L1_2 --> L2_3
    L2_1 --> L3_4
```

### 每一层的职责：

1.  **Layer 1: 静态红线层 (Redlines)**

    - **定义位置**: Agent Prompt 文件本身 (e.g., `frontend.md`)。
    - **作用**: 绝对底线，无论什么任务都必须遵守。
    - **例子**: "编码前必须查 Context7"、"禁止 any 类型"。

2.  **Layer 2: 动态规范层 (Skills)**

    - **定义位置**: `.opencode/skills/` 目录。
    - **作用**: 可插拔的知识块，根据任务动态加载。
    - **例子**: "使用 ProTable"、"搜索栏 >=4 个字段用 QueryFilter"、"订单状态机定义"。

3.  **Layer 3: 协议控制层 (Protocols)**
    - **定义位置**: `team.md` 和各子 Agent 的交互指令。
    - **作用**: 确保协作顺畅，防止 Agent "失控"或"偷懒"。
    - **例子**: "PM 必须将 Skill 摘要写入委派指令"、"子 Agent 必须用指定格式汇报"。

---

## 4. 目录结构映射

```text
.opencode/
├── agents/                  # 🟢 角色定义 (Agents)
│   ├── team.md              # 👑 Coordinator
│   ├── planning.md          # 🧠 Architect
│   ├── frontend.md          # ⚡ Developer
│   ├── code-spec.md         # 🔍 Reviewer
│   └── qa-tester.md         # 🧪 Tester
│
└── skills/                  # 🔵 能力定义 (Skills)
    ├── business/            # 💼 业务域
    │   ├── order-management/
    │   └── product-management/
    ├── design/              # 🎨 设计规范
    │   └── visual-standards/
    ├── tech-stack/          # 🛠️ 技术栈
    │   └── umijs-procomponents/
    └── engineering/         # 🛡️ 通用工程
        └── code-quality/
```