系统架构

整体架构

VAI TEAM 采用 分层解耦 的微服务架构，核心理念是"人类决策，AI 执行"：

┌─────────────────────────────────────────────────────────────┐
│                    Human Interface Layer                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │    Web UI   │  │  REST API   │  │   Webhook   │        │
│  │  (Vue.js)   │  │  (FastAPI)  │  │ (Git/CI/CD) │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Orchestration Layer                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │ Dispatcher  │  │  Scheduler  │  │ AI Leader   │        │
│  │ (Core API)  │  │ (Task Queue)│  │ (Planning)  │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Execution Layer                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Agent 1   │  │   Agent 2   │  │   Agent N   │        │
│  │ (Frontend)  │  │ (Backend)   │  │ (DevOps)    │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Infrastructure Layer                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │  Database   │  │ AI Models   │  │ Git Repos   │        │
│  │ (Postgres)  │  │ (Multi-LLM) │  │ (Workspace) │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
└─────────────────────────────────────────────────────────────┘

核心组件详解

1. Web UI（人机交互层）

技术栈：Vue 3 + Naive UI + TypeScript

职责：

项目管理界面（创建、配置、监控）
阶段推进控制（审核、确认、打回）
任务看板（状态跟踪、代码审核）
文档查看编辑（Markdown 渲染）
Agent 和模型管理

关键特性：

响应式设计，支持桌面和平板
实时状态更新（WebSocket/SSE）
代码高亮和 Diff 显示
拖拽式任务管理

2. Dispatcher（调度中心）

技术栈：Python + FastAPI + SQLAlchemy

职责：

RESTful API 服务
项目生命周期管理
阶段文档生成与存储
任务分解与分配调度
用户认证与权限控制

核心模块：

python

# 项目管理
/api/projects/          # CRUD 项目
/api/stages/            # 阶段推进
/api/documents/         # 文档管理

# 任务调度
/api/tasks/             # 任务 CRUD
/api/agents/            # Agent 管理
/api/models/            # 模型配置

# 系统管理
/api/auth/              # 认证授权
/api/health/            # 健康检查

3. AI Leader（智能规划）

集成在 Dispatcher 中，负责高层决策：

需求分析 — 将用户输入转化为结构化需求
架构设计 — 生成技术方案和接口定义
任务分解 — 将大目标拆解为可执行的小任务
质量评估 — 审核 Agent 产出，提出改进建议

模型选择：使用强推理模型（Claude Sonnet / GPT-4o）

4. Agent（执行节点）

技术栈：Python + Docker + Git

职责：

接收并执行具体编码任务
调用 AI 模型生成代码
管理独立的 Git 工作区
提交代码变更（一任务一提交）
向 Dispatcher 汇报执行状态

Agent 工作流：

python

def execute_task(task):
    # 1. 准备上下文
    context = load_project_context(task.project_id)
    
    # 2. 调用 AI 模型
    response = ai_model.generate(
        prompt=build_prompt(task, context),
        role=task.assigned_role
    )
    
    # 3. 应用代码变更
    apply_changes(response.code_changes)
    
    # 4. Git 提交
    git_commit(f"feat: {task.title}")
    
    # 5. 汇报结果
    report_completion(task.id, response)

5. 数据存储层

主数据库（PostgreSQL/SQLite）：

sql

-- 核心实体关系
Projects (项目)
├── Stages (阶段)
│   └── StageDocuments (阶段文档)
├── Tasks (任务)
│   ├── TaskDocuments (过程文档)
│   └── TaskAssignments (分配记录)
└── Checkpoints (快照备份)

Users (用户)
├── Projects (关联项目)
└── AuditLogs (操作日志)

Models (模型配置)
├── Providers (供应商)
└── RoleAssignments (角色分配)

Agents (执行节点)
├── Heartbeats (心跳记录)
└── TaskExecutions (执行历史)

文件存储：

Agent 工作区：/workspaces/{agent_id}/
项目备份：/backups/{project_id}/
上传文件：/uploads/{project_id}/

设计原则

1. 人类决策，AI 执行

决策层 (Human)     执行层 (AI)
├── 需求确认  ────▶ 需求分析
├── 架构审核  ────▶ 代码实现  
├── 质量把控  ────▶ 测试执行
└── 发布决策  ────▶ 部署操作

关键设计：

每个阶段都有人类审核节点
AI 不能跳过审核自动推进
重要决策（架构、发布）必须人工确认

2. 能力完备，角色约束

所有 Agent 使用相同的代码和模型调用能力，通过 角色 Prompt 约束行为：

python

# 所有 Agent 的能力都相同
class Agent:
    def call_ai_model(self, prompt, context): ...
    def execute_git_operations(self): ...
    def read_write_files(self): ...

# 通过角色 Prompt 约束行为
ROLE_PROMPTS = {
    "frontend": "你是前端开发专家，只关注 UI/UX 实现...",
    "backend": "你是后端开发专家，只关注 API 和业务逻辑...",
    "tester": "你是测试工程师，只关注测试用例和质量保证..."
}

3. 阶段门控流程

8 个阶段严格按序推进，每个阶段有明确的准入和准出条件：

python

STAGE_FLOW = {
    0: {"name": "业务方案", "requires": ["需求描述"], "produces": ["业务文档"]},
    1: {"name": "需求分析", "requires": ["业务文档"], "produces": ["功能清单"]},
    2: {"name": "产品原型", "requires": ["功能清单"], "produces": ["页面结构"]},
    3: {"name": "技术方案", "requires": ["页面结构"], "produces": ["架构设计"]},
    4: {"name": "任务分解", "requires": ["架构设计"], "produces": ["任务列表"]},
    5: {"name": "编码实现", "requires": ["任务列表"], "produces": ["代码仓库"]},
    6: {"name": "集成测试", "requires": ["代码仓库"], "produces": ["测试报告"]},
    7: {"name": "部署交付", "requires": ["测试报告"], "produces": ["部署包"]}
}

交互流程

典型项目开发流程

mermaid

sequenceDiagram
    participant U as User
    participant W as Web UI
    participant D as Dispatcher
    participant L as AI Leader
    participant A as Agent
    participant M as AI Model

    U->>W: 创建项目
    W->>D: POST /api/projects
    D->>D: 初始化项目数据

    U->>W: 开始阶段 0
    W->>D: POST /api/stages/0/start
    D->>L: 调用 AI Leader
    L->>M: 生成业务方案
    M-->>L: 返回方案文档
    L-->>D: 保存阶段文档
    D-->>W: 返回文档内容

    U->>W: 审核并推进
    W->>D: POST /api/stages/0/approve
    D->>D: 推进到阶段 1

    Note over U,M: 重复阶段 1-4...

    U->>W: 开始阶段 5 (编码)
    W->>D: POST /api/stages/5/start
    D->>D: 分解任务并分配
    D->>A: 分配编码任务
    A->>M: 调用模型生成代码
    M-->>A: 返回代码
    A->>A: Git 提交
    A-->>D: 汇报完成
    D-->>W: 更新任务状态

    U->>W: 审核代码
    W->>D: POST /api/tasks/{id}/review
    D->>D: 更新任务状态

模型调用流程

mermaid

graph TD
    A[任务分配] --> B{任务类型}
    B -->|阶段 0-4| C[Dispatcher 调用 Leader]
    B -->|阶段 5-7| D[Agent 调用执行模型]
    
    C --> E[选择强推理模型]
    D --> F[选择角色对应模型]
    
    E --> G[生成文档/方案]
    F --> H[生成代码/测试]
    
    G --> I[保存到数据库]
    H --> J[提交到 Git]
    
    I --> K[等待人类审核]
    J --> K

扩展性设计

水平扩展

Agent 扩展 — 通过 Docker Compose scale 增加 Agent 实例
数据库扩展 — 支持 PostgreSQL 主从复制
模型扩展 — 支持多供应商、多模型并行调用

插件化架构

python

# 角色插件
class RolePlugin:
    def get_prompt_template(self): ...
    def validate_output(self, result): ...

# 模型插件  
class ModelPlugin:
    def call_api(self, prompt, config): ...
    def parse_response(self, response): ...

# 工具插件
class ToolPlugin:
    def execute(self, command, context): ...

多租户支持

为 SaaS 部署预留的架构扩展：

python

# 租户隔离
class TenantContext:
    tenant_id: str
    database_url: str  # 租户独立数据库
    model_config: dict # 租户独立模型配置
    agent_pool: list   # 租户独立 Agent 池

技术栈选择理由

组件	技术选择	理由
前端	Vue 3 + Naive UI	组件丰富、中文友好、TypeScript 支持好
后端	FastAPI	自动 API 文档、异步支持、Python 生态
数据库	PostgreSQL	JSON 支持、全文搜索、事务可靠性
容器化	Docker Compose	简单部署、环境一致性
AI 调用	OpenAI 兼容接口	标准化、供应商无关

安全架构

认证授权

python

# JWT 认证
@app.middleware("http")
async def auth_middleware(request, call_next):
    if request.url.path.startswith("/api/"):
        token = extract_token(request)
        user = verify_jwt(token)
        request.state.user = user
    return await call_next(request)

# 权限控制
@require_permission("project:read")
async def get_project(project_id: str, user: User):
    return project_service.get(project_id, user)

数据隔离

用户级隔离：每个用户只能访问自己的项目
项目级隔离：Agent 工作区相互独立
模型调用隔离：API Key 按用户/项目隔离

代码安全

Agent 工作区沙箱化（Docker 容器）
Git 操作限制在指定目录
文件上传类型和大小限制
SQL 注入防护（SQLAlchemy ORM）

更多安全细节将在后续版本中补充。

系统架构 ​

整体架构 ​

核心组件详解 ​

1. Web UI（人机交互层） ​

2. Dispatcher（调度中心） ​

3. AI Leader（智能规划） ​

4. Agent（执行节点） ​

5. 数据存储层 ​

设计原则 ​

1. 人类决策，AI 执行 ​

2. 能力完备，角色约束 ​

3. 阶段门控流程 ​

交互流程 ​

典型项目开发流程 ​

模型调用流程 ​

扩展性设计 ​

水平扩展 ​

插件化架构 ​

多租户支持 ​

技术栈选择理由 ​

安全架构 ​

认证授权 ​

数据隔离 ​

代码安全 ​

系统架构

整体架构

核心组件详解

1. Web UI（人机交互层）

2. Dispatcher（调度中心）

3. AI Leader（智能规划）

4. Agent（执行节点）

5. 数据存储层

设计原则

1. 人类决策，AI 执行

2. 能力完备，角色约束

3. 阶段门控流程

交互流程

典型项目开发流程

模型调用流程

扩展性设计

水平扩展

插件化架构

多租户支持

技术栈选择理由

安全架构

认证授权

数据隔离

代码安全