🤖 系统全量用户使用手册

第 1 章 系统概述与架构

1.1 系统简介

本系统是基于 OpenClaw 和 Claude Code 两大核心 AI Agent 平台构建的端到端研发自动化系统。系统实现了从需求分析到最终部署验收的全流程自动化，支持多角色 Agents 协同工作，并在关键节点提供人机协同能力。

1.2 核心技术栈

1.3 系统架构图

1.4 部署模式

系统支持三种部署模式：

• 本地部署：在开发者笔记本或工作站上运行，适合个人开发者和小团队
• 私有云部署：在企业内部服务器或 VPS 上部署，数据完全可控
• 混合部署：核心服务私有化，部分 AI 能力调用云端 API

第 2 章 研发角色 Agents 体系

2.1 Agent 角色总览

系统定义了 8 个核心研发角色 Agent，每个 Agent 都有明确的职责边界和协作机制：

2.2 Agent 通信机制

各 Agent 之间通过以下方式进行通信和协作：

• 消息队列：使用 RabbitMQ/Kafka 进行异步消息传递
• 共享存储：通过 Git 仓库和对象存储共享文档和代码
• API 调用：RESTful API 进行同步请求响应
• IM 集成：通过 WhatsApp、Telegram、Discord、Slack 等发送通知

2.3 Agent 激活与调度

OpenClaw 负责任务的编排和调度，根据工作流状态自动激活相应的 Agent：

# 示例：通过 OpenClaw 激活 Product Agent
/openclaw activate --agent product --task "生成电商后台管理系统 PRD"
# 或通过聊天应用发送指令
"请为新的用户中心模块生成 PRD 文档"

第 3 章 需求分析与 PRD 设计阶段

3.1 需求输入方式

Product Agent 支持多种需求输入方式：

• 自然语言描述：直接输入需求描述文本
• 会议纪要上传：上传会议录音转文字或会议记录文档
• 竞品分析链接：提供竞品 URL，自动抓取分析
• 用户反馈汇总：导入客服工单、用户调研数据

3.2 PRD 生成流程

1. 需求解析：Product Agent 使用 Claude Code 分析输入内容，提取关键信息
2. 用户故事生成：按照"As a [角色], I want to [目标], so that [价值]"格式生成
3. 功能拆解：将大需求拆分为可独立开发的功能点
4. 优先级排序：使用 MoSCoW 法则（Must/Should/Could/Won't）排序
5. 验收标准定义：为每个功能点定义明确的验收条件
6. 文档格式化：生成标准 PRD 文档（Markdown/PDF/HTML）

3.3 PRD 文档结构

# 产品名称 PRD 文档

## 1. 文档信息
- 版本号：v1.0
- 创建日期：2026-03-14
- 最后更新：2026-03-14
- 负责人：Product Agent

## 2. 产品概述
### 2.1 背景与目标
### 2.2 用户群体
### 2.3 核心价值

## 3. 功能需求
### 3.1 功能清单
### 3.2 用户故事地图
### 3.3 功能详细说明

## 4. 非功能需求
### 4.1 性能要求
### 4.2 安全要求
### 4.3 兼容性要求

## 5. 验收标准
### 5.1 功能验收标准
### 5.2 性能验收标准

## 6. 附录
### 6.1 术语表
### 6.2 参考资料

3.4 人机协同审核

3.5 版本管理

所有 PRD 文档都纳入 Git 版本管理，每次修改都会生成新的 Commit，并附带变更说明：

git commit -m "docs(prd): 更新用户中心模块 v1.2
- 新增手机号登录功能
- 优化密码找回流程
- 调整权限模型"
git tag prd-v1.2

第 4 章 技术方案设计阶段

4.1 架构设计输入

Architecture Agent 接收以下输入：

• 审核通过的 PRD 文档
• 现有技术栈约束（如必须使用 Java Spring Boot）
• 基础设施限制（如只能部署在阿里云）
• 性能指标要求（如 QPS > 10000）

4.2 技术方案生成

Architecture Agent 按照以下步骤生成技术方案：

1. 需求映射：将 PRD 中的功能需求映射到技术组件
2. 架构模式选择：根据场景选择单体/微服务/Serverless 架构
3. 技术选型：推荐最适合的技术栈和第三方服务
4. 数据库设计：生成 ER 图和表结构定义
5. 服务拆分：定义微服务边界和依赖关系
6. 容量规划：估算资源需求和扩缩容策略

4.3 架构图自动生成

系统使用 Mermaid 语法自动生成各类架构图：

```mermaid
graph TB
    subgraph 前端层
        A[Web 前端] --> B[Mobile App]
    end
    
    subgraph 网关层
        C[API Gateway]
    end
    
    subgraph 服务层
        D[用户服务]
        E[订单服务]
        F[支付服务]
    end
    
    subgraph 数据层
        G[(MySQL)]
        H[(Redis)]
        I[(MongoDB)]
    end
    
    A --> C
    B --> C
    C --> D
    C --> E
    C --> F
    D --> G
    D --> H
    E --> G
    F --> I
```

4.4 技术方案文档结构

# 技术方案设计文档

## 1. 架构概述
### 1.1 整体架构图
### 1.2 架构决策记录 (ADR)

## 2. 技术选型
### 2.1 后端技术栈
### 2.2 前端技术栈
### 2.3 中间件选型
### 2.4 云服务选型

## 3. 数据库设计
### 3.1 ER 图
### 3.2 表结构定义
### 3.3 索引策略

## 4. 微服务设计
### 4.1 服务划分
### 4.2 服务间通信
### 4.3 数据一致性方案

## 5. 非功能性设计
### 5.1 高可用方案
### 5.2 性能优化策略
### 5.3 安全设计方案

## 6. 部署架构
### 6.1 环境规划
### 6.2 资源配置
### 6.3 监控方案

4.5 架构评审

技术方案生成后，系统会组织虚拟架构评审会：

• Architecture Agent 演示设计方案
• 其他 Agent 提出质询和建议
• 人类架构师进行最终决策
• 根据反馈迭代优化方案

第 5 章 API 接口协议设计

5.1 API 设计原则

API Agent 遵循以下设计原则：

• RESTful 风格：资源导向、无状态、统一接口
• 版本控制：URL 路径中包含版本号（如/api/v1/users）
• 统一响应格式：标准化的成功/错误响应结构
• 完善的文档：自动生成 OpenAPI/Swagger 文档
• 向后兼容：保证旧版本 API 持续可用

5.2 API 设计流程

1. 资源建模：根据业务实体定义 API 资源
2. 端点设计：设计 RESTful 端点和 HTTP 方法
3. 请求响应定义：定义请求参数、响应数据结构
4. 错误码设计：定义统一的错误码体系
5. 认证授权：设计 JWT/OAuth2 认证机制
6. 限流策略：定义 API 调用频率限制

5.3 OpenAPI 规范生成

API Agent 自动生成符合 OpenAPI 3.0 规范的 YAML 文件：

openapi: 3.0.3
info:
  title: 用户中心 API
  version: 1.0.0
  description: 用户管理相关接口

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: 获取用户列表
      tags: [用户管理]
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 20
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
    
    post:
      summary: 创建用户
      tags: [用户管理]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: 创建成功

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        username:
          type: string
        email:
          type: string
    CreateUserRequest:
      type: object
      required: [username, email, password]
      properties:
        username:
          type: string
        email:
          type: string
        password:
          type: string

5.4 Mock Server 启动

API 规范定义完成后，系统自动启动 Mock Server 供前后端并行开发：

# 使用 Prism 启动 Mock Server
npx prism mock openapi.yaml

# Mock Server 会自动根据 OpenAPI 规范
# 生成符合定义的模拟响应数据

5.5 Postman Collection 导出

系统自动生成 Postman Collection，方便开发和测试人员使用：

• 包含所有 API 端点的预定义请求
• 内置环境变量配置
• 预设测试断言脚本
• 支持一键导入 Postman

第 6 章 AI Coding 编码实现

6.1 Claude Code 核心能力

Claude Code 是系统的核心编码引擎，具备以下能力：

• 代码理解：快速理解现有代码库的架构和逻辑
• 代码生成：根据需求生成高质量的代码
• 代码重构：优化现有代码结构和性能
• Bug 修复：定位并修复代码缺陷
• Git 工作流：自动处理分支、提交、合并等操作
• 多语言支持：Python、JavaScript、Go、Java、Rust 等主流语言

6.2 后端开发流程

1. 项目初始化：根据技术选型创建项目骨架
2. 数据库迁移：生成并执行数据库迁移脚本
3. Model 层开发：实现数据模型和 ORM 映射
4. Service 层开发：实现业务逻辑
5. Controller 层开发：实现 API 端点
6. 单元测试编写：为每个模块编写测试用例

# 示例：使用 Claude Code 生成用户服务
claude "根据 API 规范生成用户服务的 CRUD 实现"
claude "为 UserService 添加邮箱验证功能"
claude "优化 getUserById 方法的查询性能"

6.3 前端开发流程

1. 项目脚手架：使用 Create React App/Vite/Nuxt 等初始化
2. 组件库搭建：生成基础 UI 组件（Button、Input、Table 等）
3. 页面开发：根据原型图生成页面组件
4. 状态管理：配置 Redux/Zustand/Pinia 等状态管理
5. API 对接：集成后端 API，处理数据交互
6. 样式优化：应用主题样式和响应式布局

# 示例：使用 Claude Code 生成 React 组件
claude "创建一个用户列表页面，包含搜索、分页、批量删除功能"
claude "为 UserForm 组件添加表单验证"
claude "使用 Tailwind CSS 优化登录页面样式"

6.4 代码审查

系统自动进行代码审查，检查以下方面：

• 代码规范：命名规范、缩进、注释等
• 安全漏洞：SQL 注入、XSS、CSRF 等常见漏洞
• 性能问题：N+1 查询、内存泄漏、循环复杂度
• 可维护性：代码重复率、函数长度、依赖耦合

6.5 Git 工作流自动化

Claude Code 自动处理 Git 操作：

# 自动创建功能分支
git checkout -b feature/user-authentication

# 智能提交信息生成
git commit -m "feat(user): 实现 JWT 认证功能

- 添加登录登出接口
- 实现 token 刷新机制
- 添加密码加密存储"

# 自动推送并创建 Pull Request
git push origin feature/user-authentication
gh pr create --title "feat: 用户认证功能" --body "实现完整的 JWT 认证流程"

第 7 章 单元测试与集成测试

7.1 测试策略

系统采用金字塔测试策略：

• 单元测试（70%）：针对最小可测试单元
• 集成测试（20%）：测试模块间交互
• E2E 测试（10%）：模拟真实用户场景

7.2 单元测试生成

Test Agent 自动为每个模块生成单元测试：

# Python pytest 示例
# test_user_service.py

import pytest
from services.user_service import UserService

class TestUserService:
    def test_create_user_success(self):
        service = UserService()
        user = service.create_user({
            'username': 'test',
            'email': 'test@example.com',
            'password': 'SecurePass123'
        })
        assert user.id is not None
        assert user.username == 'test'
    
    def test_create_user_duplicate_email(self):
        service = UserService()
        service.create_user({
            'username': 'user1',
            'email': 'duplicate@example.com',
            'password': 'Pass123'
        })
        
        with pytest.raises(ValueError) as exc_info:
            service.create_user({
                'username': 'user2',
                'email': 'duplicate@example.com',
                'password': 'Pass456'
            })
        assert '邮箱已存在' in str(exc_info.value)

7.3 集成测试配置

集成测试验证模块间的协作：

# 用户注册完整流程测试
def test_user_registration_flow():
    # 1. 调用注册 API
    response = client.post('/api/v1/users/register', json={
        'username': 'newuser',
        'email': 'new@example.com',
        'password': 'Password123'
    })
    assert response.status_code == 201
    
    # 2. 验证邮件发送
    assert mock_email_service.sent_count == 1
    
    # 3. 验证数据库记录
    user = db.query(User).filter_by(email='new@example.com').first()
    assert user is not None
    assert user.is_active == False  # 待邮箱验证
    
    # 4. 模拟邮箱验证
    verify_token = user.verify_token
    response = client.get(f'/api/v1/users/verify?token={verify_token}')
    assert response.status_code == 200
    
    # 5. 验证用户已激活
    db.session.refresh(user)
    assert user.is_active == True

7.4 测试执行与报告

Test Agent 自动执行测试并生成详细报告：

• 测试结果统计：通过/失败/跳过数量
• 代码覆盖率：行覆盖率、分支覆盖率、函数覆盖率
• 失败分析：失败用例的详细错误信息和堆栈跟踪
• 性能指标：测试执行时间、慢测试识别

7.5 自动修复建议

对于失败的测试，Claude Code 自动分析原因并提供修复建议：

❌ 测试失败：test_user_login_invalid_password

错误信息：AssertionError - 期望抛出 InvalidPasswordError，实际抛出 ValueError

分析结果：
- UserService.login() 方法对无效密码抛出 ValueError
- 根据设计规范应抛出 InvalidPasswordError

修复建议：
1. 在 UserService.login() 中添加密码验证逻辑
2. 当密码不匹配时抛出 InvalidPasswordError 异常
3. 更新相关单元测试断言

是否应用修复？[y/n]

第 8 章 CI/CD 自动部署流程

8.1 Jenkins 流水线配置

DevOps Agent 自动生成 Jenkins Pipeline 配置：

// Jenkinsfile 示例
pipeline {
    agent any
    
    environment {
        DOCKER_REGISTRY = 'registry.example.com'
        K8S_NAMESPACE = 'production'
    }
    
    stages {
        stage('代码检出') {
            steps {
                git branch: env.BRANCH_NAME, 
                    url: 'https://github.com/org/project.git'
            }
        }
        
        stage('代码质量检查') {
            steps {
                sh 'npm run lint'
                sh 'npm run sonarqube'
            }
        }
        
        stage('单元测试') {
            steps {
                sh 'npm run test:coverage'
            }
            post {
                always {
                    junit 'reports/test-results.xml'
                    publishCoverage adapters: [jacocoAdapter()], \
                        sourceFileResolver: sourceFiles('STORE_LAST_BUILD')
                }
            }
        }
        
        stage('构建 Docker 镜像') {
            steps {
                script {
                    docker.build("${DOCKER_REGISTRY}/app:${BUILD_ID}")
                }
            }
        }
        
        stage('推送镜像') {
            steps {
                script {
                    docker.withRegistry("https://${DOCKER_REGISTRY}", 'docker-credentials') {
                        docker.image("${DOCKER_REGISTRY}/app:${BUILD_ID}").push()
                    }
                }
            }
        }
        
        stage('部署到 K8S') {
            when {
                branch 'main'
            }
            steps {
                sh '''
                    kubectl set image deployment/app app=${DOCKER_REGISTRY}/app:${BUILD_ID} \
                        -n ${K8S_NAMESPACE}
                    kubectl rollout status deployment/app -n ${K8S_NAMESPACE}
                '''
            }
        }
        
        stage('健康检查') {
            steps {
                sh '''
                    curl -f https://app.example.com/health || exit 1
                '''
            }
        }
    }
    
    post {
        success {
            slackSend channel: '#deployments', 
                message: "✅ 部署成功：${env.JOB_NAME} ${env.BUILD_NUMBER}"
        }
        failure {
            slackSend channel: '#alerts', 
                message: "❌ 部署失败：${env.JOB_NAME} ${env.BUILD_NUMBER}\n${env.BUILD_URL}"
        }
    }
}

8.2 Docker 镜像构建

DevOps Agent 自动生成优化的 Dockerfile：

# 多阶段构建示例
# 构建阶段
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

# 生产阶段
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package.json ./

ENV NODE_ENV=production
EXPOSE 3000

USER node
CMD ["node", "dist/server.js"]

8.3 K8S 部署配置

自动生成 Kubernetes 资源清单：

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: app
        image: registry.example.com/app:latest
        ports:
        - containerPort: 3000
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 5

---
# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: app-service
  namespace: production
spec:
  selector:
    app: myapp
  ports:
  - port: 80
    targetPort: 3000
  type: LoadBalancer

---
# ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-ingress
  namespace: production
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  rules:
  - host: app.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app-service
            port:
              number: 80

8.4 KubeSphere 集成

系统支持与 KubeSphere 深度集成：

• 可视化部署：通过 KubeSphere UI 查看和管理应用
• 多环境管理：Dev/Test/Prod 环境隔离
• 灰度发布：金丝雀发布、蓝绿部署
• 可观测性：集成 Prometheus+Grafana 监控
• 日志聚合：集成 Fluent Bit+ELK 日志系统

8.5 部署策略

系统支持多种部署策略：

第 9 章 UI 自动化测试验收

9.1 测试框架选择

系统支持多种 UI 自动化测试框架：

• Playwright：跨浏览器、快速、可靠（推荐）
• Selenium：成熟稳定、生态丰富
• Cypress：开发者友好、调试便捷

9.2 测试用例生成

QA Agent 根据 PRD 和原型图自动生成测试用例：

// Playwright 测试示例
// tests/user-login.spec.ts

import { test, expect } from '@playwright/test';

test.describe('用户登录流程', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/login');
  });

  test('成功登录', async ({ page }) => {
    await page.fill('#email', 'user@example.com');
    await page.fill('#password', 'CorrectPassword123');
    await page.click('[type="submit"]');
    
    await expect(page).toHaveURL('/dashboard');
    await expect(page.locator('.welcome-message'))
      .toContainText('欢迎回来');
  });

  test('密码错误提示', async ({ page }) => {
    await page.fill('#email', 'user@example.com');
    await page.fill('#password', 'WrongPassword');
    await page.click('[type="submit"]');
    
    await expect(page.locator('.error-message'))
      .toContainText('密码错误');
  });

  test('邮箱格式验证', async ({ page }) => {
    await page.fill('#email', 'invalid-email');
    await page.fill('#password', 'Password123');
    await page.click('[type="submit"]');
    
    await expect(page.locator('#email-error'))
      .toContainText('请输入有效的邮箱地址');
  });

  test('记住我功能', async ({ page }) => {
    await page.fill('#email', 'user@example.com');
    await page.fill('#password', 'CorrectPassword123');
    await page.check('#remember-me');
    await page.click('[type="submit"]');
    
    // 关闭浏览器再打开
    await page.context().clearCookies();
    await page.goto('/login');
    
    // 邮箱应自动填充
    await expect(page.locator('#email'))
      .toHaveValue('user@example.com');
  });
});

9.3 视觉回归测试

系统集成 Percy 等工具进行视觉回归测试：

• 基准截图：首次运行保存页面截图作为基准
• 对比检测：每次变更后自动对比截图差异
• 差异高亮：标记像素级差异区域
• 阈值配置：允许一定范围内的正常波动

9.4 跨浏览器测试

自动在多个浏览器上执行测试：

// playwright.config.ts
export default {
  use: {
    headless: true,
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  projects: [
    {
      name: 'chromium',
      use: { browserName: 'chromium' },
    },
    {
      name: 'firefox',
      use: { browserName: 'firefox' },
    },
    {
      name: 'webkit',
      use: { browserName: 'webkit' },
    },
    {
      name: 'Mobile Chrome',
      use: {
        ...devices['Pixel 5'],
      },
    },
    {
      name: 'Mobile Safari',
      use: {
        ...devices['iPhone 12'],
      },
    },
  ],
};

9.5 验收报告

QA Agent 生成详细的验收报告：

• 测试概览：总用例数、通过数、失败数、跳过数
• 失败详情：每个失败用例的截图、视频、错误日志
• 性能指标：页面加载时间、交互响应时间
• 兼容性矩阵：各浏览器/设备的测试结果
• 视觉差异：UI 变更对比图
• 上线建议：基于测试结果的上线批准/拒绝建议

第 10 章 人机协同操作指南

10.1 人机协同场景

系统在以下关键节点支持人机协同：

10.2 人工介入方式

人类用户可以通过以下方式介入流程：

10.2.1 聊天应用交互

# 通过 WhatsApp/Telegram/Discord 发送指令
"/review prd-v1.2 需要调整用户权限模型"
"/approve deployment to production"
"/pause pipeline wait for security audit"

# 查询状态
"/status current-sprint"
"/logs build-123"
"/metrics api-response-time"

10.2.2 Web 控制台

系统提供 Web 控制台进行可视化管理：

• 工作流看板：查看当前各任务的进度状态
• 审批中心：处理待审批事项（PRD、架构、代码、部署）
• 日志查询：搜索和查看各环节的详细日志
• 指标仪表盘：查看效率、质量、成本等指标

10.2.3 IDE 插件

通过 VS Code/JetBrains 插件直接在 IDE 中协作：

• 查看 AI 生成的代码和建议
• 一键接受/拒绝/修改 AI 建议
• 发起代码审查请求
• 触发测试和部署

10.3 审批工作流

系统定义了多级审批机制：

1. PRD 审批：产品经理 → 技术负责人 → 业务方
2. 架构审批：架构师 → CTO（重大变更）
3. 代码审批：Tech Lead → 安全团队（敏感代码）
4. 部署审批：DevOps → 值班工程师 → 产品经理（生产环境）

# 审批配置示例
approvals:
  prd_review:
    required_approvers: 2
    approvers: ['product_manager', 'tech_lead']
    timeout: 48h
  
  production_deploy:
    required_approvers: 3
    approvers: ['devops', 'oncall_engineer', 'product_owner']
    manual_gate: true  # 必须人工确认
    deploy_window: 'Tue-Thu 02:00-06:00 UTC'

10.4 异常处理

当遇到以下情况时，系统会自动暂停并请求人工介入：

• 需求模糊：AI 无法理解或存在歧义的需求
• 技术风险：涉及核心业务逻辑或高风险变更
• 测试失败：关键测试用例连续失败 3 次以上
• 部署异常：健康检查失败、性能指标异常
• 安全告警：检测到潜在安全漏洞

10.5 反馈与持续改进

系统收集人类反馈用于持续改进：

• 代码采纳率：统计 AI 生成代码被接受的比例
• 修改模式：分析人类对 AI 输出的常见修改类型
• 满意度评分：用户对 AI 协助的满意度评价
• 效率提升：对比引入系统前后的交付周期变化