基于 OpenClaw + Claude Code 的端到端研发自动化系统使用手册

📖 第一章：系统概述

🎯 系统定位：本系统是基于 OpenClaw（开源 AI Agent 框架）与 Claude Code（Anthropic 代码智能体）深度融合的端到端研发自动化平台，实现从需求分析到生产部署的全流程智能化、自动化。

1.1 核心价值主张

效率提升 10 倍+：AI 驱动的代码生成、测试编写、文档产出
质量保障：自动化单元测试、集成测试、UI 测试全覆盖
人机协同：关键节点支持人工审核与干预，确保可控性
角色赋能：为产品、架构、开发、测试、运维各角色提供专属 Agents
持续交付：Jenkins + Docker + K8S(KubeSphere) 自动化部署流水线

1.2 适用场景

场景类型	描述	自动化程度
新功能开发	从需求 PRD 到上线部署的完整流程	90%+
Bug 修复	问题定位→代码修复→测试验证→热部署	85%+
代码重构	技术债务清理、性能优化、架构升级	80%+
接口开发	前后端 API 协议设计→实现→联调→测试	95%+
回归测试	全量自动化测试执行与报告生成	100%

1.3 技术栈总览

🛠️ 核心技术组件：
• AI Agent 层：OpenClaw v2026.3 + Claude Code Opus 4.6
• 代码管理层：GitHub/GitLab + MCP Server
• 构建部署层：Jenkins Pipeline + Docker + Kubernetes (KubeSphere)
• 测试框架层：JUnit/Pytest + Playwright/Selenium + Postman/Newman
• 监控反馈层：Prometheus + Grafana + ELK Stack

🏗️ 第二章：系统架构设计

2.1 整体架构图

需求管理
Jira/Tapd

→

PRD 设计 Agent
(产品经理)

→

架构设计 Agent
(技术架构师)

→

API 协议 Agent
(后端 + 前端)

→

AI Coding Agent
(Claude Code)

Unit Test Agent
(自动编写)

→

集成测试 Agent

→

CI/CD Pipeline
(Jenkins)

→

Docker + K8S
自动部署

→

UI 自动化验收
(Playwright)

2.2 OpenClaw 核心架构

┌─────────────────────────────────────────────────────────────┐
│                    OpenClaw Gateway Layer                    │
├─────────────────────────────────────────────────────────────┤
│  • Channel Adapters: Telegram/Discord/Slack/Feishu/WeChat   │
│  • Model Providers: Claude/GPT/Gemini/Local LLM             │
│  • Skill Executor: 13 类核心技能包                          │
│  • MCP Server: Model Context Protocol 服务                  │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   Agent Orchestration Layer                  │
├─────────────────────────────────────────────────────────────┤
│  • Planner Agent: 任务拆解与规划                            │
│  • Architect Agent: 技术方案设计                            │
│  • Developer Agent: 代码生成与实现                          │
│  • Tester Agent: 测试用例编写与执行                         │
│  • Reviewer Agent: 代码审查与安全审计                       │
│  • DevOps Agent: CI/CD 与部署                               │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   Execution & Tool Layer                     │
├─────────────────────────────────────────────────────────────┤
│  • Browser Automation: Playwright/Puppeteer                 │
│  • File Operations: 读写/搜索/批量处理                      │
│  • Shell Commands: Linux/Mac/Windows 命令执行               │
│  • API Calls: REST/GraphQL/gRPC                             │
│  • Database Ops: SQL/NoSQL 操作                             │
└─────────────────────────────────────────────────────────────┘

2.3 Claude Code 多智能体工作流

🧠Claude Code 核心 Agents

planner：需求分析与任务拆解专家
architect：系统架构与技术选型专家
tdd-guide：测试驱动开发指导专家
code-reviewer：代码质量审查专家
security-reviewer：安全漏洞扫描专家
build-error-resolver：编译错误修复专家
e2e-runner：端到端测试执行专家

2.4 数据流与状态管理

// 典型任务的数据流转示例
{
  "task_id": "TASK-2026-0314-001",
  "status": "in_progress",
  "current_stage": "api_development",
  "stages": [
    {"name": "requirement_analysis", "status": "completed", "agent": "prd-agent"},
    {"name": "technical_design", "status": "completed", "agent": "architect-agent"},
    {"name": "api_protocol", "status": "completed", "agent": "api-designer"},
    {"name": "backend_dev", "status": "in_progress", "agent": "backend-dev-agent"},
    {"name": "frontend_dev", "status": "pending", "agent": "frontend-dev-agent"},
    {"name": "unit_test", "status": "pending", "agent": "test-agent"},
    {"name": "integration_test", "status": "pending", "agent": "test-agent"},
    {"name": "ci_cd_deploy", "status": "pending", "agent": "devops-agent"},
    {"name": "ui_acceptance", "status": "pending", "agent": "ui-test-agent"}
  ],
  "artifacts": {
    "prd_doc": "/docs/prd/TASK-001-prd.md",
    "tech_design": "/docs/design/TASK-001-architecture.md",
    "api_spec": "/docs/api/TASK-001-openapi.yaml",
    "code_repo": "https://github.com/org/project",
    "test_report": "/reports/test/TASK-001-report.html"
  }
}

👥 第三章：各研发角色岗位 Agents 详解

3.1 产品经理 Agent (PRD Designer)

📋产品经理 Agent - PRD 设计师

职责定位：将模糊的需求转化为结构化的产品需求文档 (PRD)，包含功能列表、用户故事、验收标准。

核心技能包

# OpenClaw Skill: prd-designer
技能名称：prd-designer
触发命令：/create-prd [需求描述]
输出产物：Markdown 格式 PRD 文档

# 能力清单
- 需求澄清问答（主动提问补全信息）
- 用户故事地图绘制
- 功能优先级排序 (MoSCoW 法则)
- 验收标准定义 (Given-When-Then 格式)
- 竞品分析摘要生成
- 原型图文字描述生成

使用示例

# 命令行调用
openclaw run prd-designer \
  --input "需要一个用户积分系统，支持签到、任务、兑换" \
  --output docs/prd/points-system-prd.md

# Chat 界面交互
用户：/create-prd 我们需要一个会员等级系统
PRD-Agent: 收到！让我先确认几个关键问题：
  1. 会员等级分为几级？是否有升级规则？
  2. 会员权益包含哪些？（折扣/专属客服/优先发货等）
  3. 是否需要付费订阅还是成长值升级？
  4. 预期上线时间和优先级？
  
用户：分 5 级，按消费金额自动升级，权益包括...
PRD-Agent: 好的，正在生成 PRD 文档...
✅ PRD 已生成：docs/prd/membership-system-prd.md

输出模板

# 产品需求文档 (PRD)

## 1. 文档信息
- 项目名称：会员等级系统
- 版本号：v1.0
- 创建时间：2026-03-14
- 负责人：[产品经理姓名]

## 2. 背景与目标
### 2.1 业务背景
[描述为什么要做这个功能]

### 2.2 产品目标
- 提升用户复购率 20%
- 增加高价值用户粘性
- ...

## 3. 功能需求
### 3.1 功能列表
| 功能模块 | 优先级 | 描述 |
|---------|--------|------|
| 会员等级展示 | P0 | 用户中心显示当前等级 |
| 升级规则引擎 | P0 | 自动计算并升级 |
| ... | ... | ... |

### 3.2 用户故事
**US-001**: 作为普通用户，我希望查看我的会员等级，以便了解当前权益
- 验收标准：
  - Given 用户已登录
  - When 进入用户中心页面
  - Then 显示当前会员等级和进度条

## 4. 非功能需求
- 性能：等级计算响应时间 < 100ms
- 安全：防止等级数据篡改
- ...

3.2 技术架构师 Agent (System Architect)

🏛️技术架构师 Agent - 系统设计专家

职责定位：基于 PRD 设计技术架构方案，包括技术选型、系统分层、数据库设计、接口规范等。

核心技能包

# OpenClaw Skill: system-architect
技能名称：system-architect
触发命令：/design-architecture [PRD 文档路径]
输出产物：技术方案设计文档 + 架构图 (Mermaid)

# 能力清单
- 技术栈推荐与对比分析
- 微服务拆分建议
- 数据库 ER 图设计
- API 网关与路由规划
- 缓存策略设计
- 高可用与容灾方案
- 安全性设计（认证/授权/加密）

使用示例

# 命令行调用
openclaw run system-architect \
  --input docs/prd/membership-system-prd.md \
  --output docs/design/membership-architecture.md \
  --stack "Java,SpringBoot,MySQL,Redis,RabbitMQ"

# Chat 界面交互
用户：/design-architecture docs/prd/membership-system-prd.md
Architect-Agent: 正在分析 PRD 文档...
正在生成技术方案...

✅ 技术方案已生成：
- 总体架构：docs/design/membership-architecture.md
- 数据库设计：docs/design/membership-er-diagram.md
- API 规范：docs/design/membership-api-spec.yaml

输出模板

# 技术方案设计文档

## 1. 架构概览
```mermaid
graph TB
    subgraph 前端层
        Web[Web 应用] --> Gateway
        Mobile[移动端] --> Gateway
    end
    
    subgraph 网关层
        Gateway[API Gateway] --> Auth[认证服务]
    end
    
    subgraph 业务服务层
        Auth --> Member[会员服务]
        Auth --> Points[积分服务]
        Member --> DB[(MySQL)]
        Points --> Redis[(Redis)]
    end
```

## 2. 技术选型
| 层级 | 技术栈 | 选型理由 |
|-----|--------|---------|
| 后端框架 | Spring Boot 3.2 | 生态成熟、团队熟悉 |
| 数据库 | MySQL 8.0 | ACID 事务保证 |
| 缓存 | Redis 7.0 | 高性能、数据结构丰富 |
| 消息队列 | RabbitMQ | 可靠投递、延迟队列 |

## 3. 数据库设计
### 3.1 会员表 (t_member)
```sql
CREATE TABLE t_member (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    user_id BIGINT NOT NULL UNIQUE,
    level TINYINT DEFAULT 1,
    growth_value INT DEFAULT 0,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_user_id (user_id),
    INDEX idx_level (level)
);
```

## 4. 接口规范
- RESTful 风格
- JWT 认证
- 统一响应格式
- ...

3.3 后端开发工程师 Agent (Backend Developer)

⚙️后端开发工程师 Agent - API 实现专家

职责定位：根据技术方案和 API 协议，自动生成后端业务代码、数据访问层、服务层实现。

核心技能包

# OpenClaw Skill: backend-developer
技能名称：backend-developer
触发命令：/generate-backend [API 规范路径] --language [Java/Python/Go]
输出产物：完整的后端项目代码

# 能力清单
- Controller/Service/Repository 三层代码生成
- 数据库迁移脚本 (Flyway/Liquibase)
- 单元测试代码 (JUnit/Pytest)
- API 文档注解 (Swagger/OpenAPI)
- 异常处理与日志规范
- 配置管理 (多环境配置)

使用示例

# 命令行调用
openclaw run backend-developer \
  --input docs/design/membership-api-spec.yaml \
  --output src/backend/membership-service \
  --language Java \
  --framework SpringBoot \
  --with-tests true

# Chat 界面交互
用户：/generate-backend docs/design/membership-api-spec.yaml
Backend-Agent: 正在解析 API 规范...
正在生成 Spring Boot 项目结构...
正在编写业务逻辑代码...
正在生成单元测试...

✅ 后端代码已生成：
src/backend/membership-service/
├── src/main/java/com/example/membership/
│   ├── controller/
│   │   ├── MemberController.java
│   │   └── LevelController.java
│   ├── service/
│   │   ├── MemberService.java
│   │   └── impl/MemberServiceImpl.java
│   ├── repository/
│   │   └── MemberRepository.java
│   └── entity/
│       └── Member.java
├── src/test/java/
│   └── controller/MemberControllerTest.java
├── pom.xml
└── application.yml

3.4 前端开发工程师 Agent (Frontend Developer)

🎨前端开发工程师 Agent - UI 实现专家

职责定位：根据 API 协议和 UI 设计规范，自动生成前端页面组件、状态管理、API 调用层。

核心技能包

# OpenClaw Skill: frontend-developer
技能名称：frontend-developer
触发命令：/generate-frontend [API 规范路径] --framework [React/Vue/Angular]
输出产物：完整的前端项目代码

# 能力清单
- 页面组件生成 (JSX/Vue SFC)
- 状态管理 (Redux/Zustand/Pinia)
- API 客户端封装 (Axios/React Query)
- 路由配置 (React Router/Vue Router)
- 样式方案 (Tailwind/CSS Modules)
- 表单验证 (Yup/Zod)
- 国际化支持 (i18next)

使用示例

# 命令行调用
openclaw run frontend-developer \
  --input docs/design/membership-api-spec.yaml \
  --output src/frontend/membership-web \
  --framework React \
  --typescript true \
  --with-tailwind true

# Chat 界面交互
用户：/generate-frontend docs/design/membership-api-spec.yaml
Frontend-Agent: 正在解析 API 规范...
正在生成 React + TypeScript 项目...
正在编写组件代码...
正在配置 TailwindCSS...

✅ 前端代码已生成：
src/frontend/membership-web/
├── src/
│   ├── components/
│   │   ├── MemberCard.tsx
│   │   ├── LevelProgress.tsx
│   │   └── BenefitsList.tsx
│   ├── pages/
│   │   ├── MembershipPage.tsx
│   │   └── UpgradePage.tsx
│   ├── hooks/
│   │   └── useMembership.ts
│   ├── api/
│   │   └── membershipApi.ts
│   ├── store/
│   │   └── membershipStore.ts
│   └── styles/
│       └── globals.css
├── package.json
└── tailwind.config.js

3.5 测试工程师 Agent (QA Engineer)

🧪测试工程师 Agent - 质量保障专家

职责定位：自动生成单元测试、集成测试、E2E 测试用例，执行测试并生成质量报告。

核心技能包

# OpenClaw Skill: qa-engineer
技能名称：qa-engineer
触发命令：/generate-tests [代码路径] --type [unit/integration/e2e]
输出产物：测试代码 + 测试报告

# 能力清单
- 单元测试生成 (JUnit/Pytest/Jest)
- 集成测试场景设计
- E2E 测试脚本 (Playwright/Cypress)
- 接口自动化测试 (Postman/Newman)
- 性能测试脚本 (JMeter/k6)
- 测试覆盖率分析
- Bug 预测与风险识别

使用示例

# 命令行调用
# 生成单元测试
openclaw run qa-engineer \
  --input src/backend/membership-service \
  --type unit \
  --coverage-threshold 80

# 生成 E2E 测试
openclaw run qa-engineer \
  --input src/frontend/membership-web \
  --type e2e \
  --browser chromium \
  --headless false

# Chat 界面交互
用户：/generate-tests src/backend/membership-service --type unit
QA-Agent: 正在分析代码结构...
正在生成测试用例...
正在执行测试...

✅ 测试结果：
- 通过：45/48
- 失败：2
- 跳过：1
- 覆盖率：82.5%

详细报告：reports/test/unit-test-report.html

3.6 DevOps 工程师 Agent (DevOps Engineer)

🚀DevOps 工程师 Agent - 部署运维专家

职责定位：配置 CI/CD 流水线，管理 Docker 镜像，编排 K8S 部署，监控系统健康度。

核心技能包

# OpenClaw Skill: devops-engineer
技能名称：devops-engineer
触发命令：/setup-cicd [项目路径] --platform [Jenkins/GitLab CI/GitHub Actions]
输出产物：CI/CD 配置文件 + 部署脚本

# 能力清单
- Jenkins Pipeline 编写 (Declarative/Scripted)
- Dockerfile 优化与多阶段构建
- Docker Compose 编排
- Kubernetes YAML 生成 (Deployment/Service/Ingress)
- Helm Chart 打包
- KubeSphere 集成配置
- 监控告警配置 (Prometheus Rules)
- 日志收集配置 (Fluentd/ELK)

使用示例

# 命令行调用
# 配置 Jenkins Pipeline
openclaw run devops-engineer \
  --input src/backend/membership-service \
  --platform Jenkins \
  --output ci/jenkins/Jenkinsfile \
  --registry harbor.example.com \
  --k8s-cluster production

# Chat 界面交互
用户：/setup-cicd . --platform Jenkins
DevOps-Agent: 正在分析项目结构...
正在生成 Jenkinsfile...
正在配置 Docker 构建...
正在生成 K8S 部署配置...

✅ CI/CD 配置已生成：
ci/jenkins/
├── Jenkinsfile
├── docker-build.sh
└── k8s-deploy.sh

k8s/
├── deployment.yaml
├── service.yaml
├── ingress.yaml
└── configmap.yaml

🔄 第四章：端到端自动化流程详解

4.1 完整研发流程图谱

1️⃣ 需求输入
(自然语言)

→

2️⃣ PRD 设计
(Product Agent)

→

3️⃣ 技术架构
(Architect Agent)

→

4️⃣ API 协议
(API Designer)

→

5️⃣ AI Coding
(Claude Code)

6️⃣ Unit Test
(Auto Generate)

→

7️⃣ 集成测试
(Integration)

→

8️⃣ Code Review
(AI + Human)

→

9️⃣ CI/CD
(Jenkins)

→

🔟 Docker+K8S
自动部署

1️⃣1️⃣ UI 自动化
(Playwright)

→

1️⃣2️⃣ 验收报告
(Auto Generate)

→

✅ 上线完成
(Production)

4.2 阶段一：需求→PRD (1-2 小时)

# Step 1: 需求输入
用户输入："需要一个用户签到系统，连续签到 7 天送优惠券"

# Step 2: PRD Agent 启动
openclaw run prd-designer \
  --input "需要一个用户签到系统，连续签到 7 天送优惠券" \
  --output docs/prd/checkin-system-prd.md \
  --interactive true

# Step 3: PRD Agent 主动澄清（交互式）
PRD-Agent: 
  ❓ 问题 1: 签到时间范围是自然日还是 24 小时滚动？
  ❓ 问题 2: 优惠券类型和面额是多少？
  ❓ 问题 3: 断签后是否重新累计？
  ❓ 问题 4: 是否需要签到提醒（推送/短信）？

# Step 4: 生成 PRD 文档
✅ 输出：docs/prd/checkin-system-prd.md
  - 功能列表
  - 用户故事
  - 验收标准
  - 原型描述

4.3 阶段二：PRD→技术方案 (2-4 小时)

# Step 1: 架构师 Agent 读取 PRD
openclaw run system-architect \
  --input docs/prd/checkin-system-prd.md \
  --output docs/design/checkin-architecture.md \
  --stack "Java,SpringBoot,MySQL,Redis"

# Step 2: 生成技术方案
✅ 输出内容：
  - 系统架构图 (Mermaid)
  - 技术选型说明
  - 数据库 ER 图
  - API 接口清单
  - 缓存策略
  - 安全设计

# Step 3: 生成 API 协议 (OpenAPI 3.0)
openclaw run api-designer \
  --input docs/design/checkin-architecture.md \
  --output docs/api/checkin-openapi.yaml \
  --format openapi3

4.4 阶段三：API 协议→代码实现 (4-8 小时)

# Step 1: 并行启动前后端开发 Agents
# 后端开发
openclaw run backend-developer \
  --input docs/api/checkin-openapi.yaml \
  --output src/backend/checkin-service \
  --language Java \
  --framework SpringBoot \
  --with-tests true &

# 前端开发
openclaw run frontend-developer \
  --input docs/api/checkin-openapi.yaml \
  --output src/frontend/checkin-web \
  --framework React \
  --typescript true &

wait  # 等待两个任务完成

# Step 2: Claude Code 深度优化
cd src/backend/checkin-service
claude --prompt "优化代码质量，添加完善的错误处理和日志"

cd ../../frontend/checkin-web
claude --prompt "优化组件性能，添加加载状态和错误边界"

4.5 阶段四：自动化测试 (2-4 小时)

# Step 1: 生成并执行单元测试
openclaw run qa-engineer \
  --input src/backend/checkin-service \
  --type unit \
  --coverage-threshold 80 \
  --report reports/test/unit-report.html

# Step 2: 生成并执行集成测试
openclaw run qa-engineer \
  --input src/backend/checkin-service \
  --type integration \
  --database testdb \
  --report reports/test/integration-report.html

# Step 3: 生成并执行 E2E 测试
openclaw run qa-engineer \
  --input src/frontend/checkin-web \
  --type e2e \
  --browser chromium \
  --scenarios "签到流程，优惠券领取，连续签到奖励" \
  --report reports/test/e2e-report.html

4.6 阶段五：CI/CD + 自动部署 (1-2 小时)

# Step 1: 配置 CI/CD 流水线
openclaw run devops-engineer \
  --input . \
  --platform Jenkins \
  --output ci/jenkins/Jenkinsfile \
  --registry harbor.example.com \
  --k8s-namespace checkin-prod

# Step 2: 触发 Jenkins Pipeline
curl -X POST http://jenkins.example.com/job/checkin-service/build \
  -H "Authorization: Bearer $JENKINS_TOKEN"

# Step 3: 监控部署状态
kubectl get pods -n checkin-prod -w
kubectl logs -f deployment/checkin-service -n checkin-prod

4.7 阶段六：UI 自动化验收 (1-2 小时)

# Step 1: 执行 UI 自动化测试
openclaw run ui-tester \
  --base-url https://checkin.example.com \
  --scenarios tests/ui/checkin-flows.spec.ts \
  --browser chromium \
  --video true \
  --report reports/ui/acceptance-report.html

# Step 2: 生成验收报告
✅ 输出：
  - 测试通过率：98.5%
  - 截图证据：reports/ui/screenshots/
  - 录屏回放：reports/ui/videos/
  - 性能指标：LCP=1.2s, FID=50ms, CLS=0.05

# Step 3: 人工复核（可选）
如果通过率 < 95%，触发人工 review 流程

🦞 第五章：OpenClaw 安装与配置指南

5.1 系统要求

组件	最低要求	推荐配置
操作系统	Ubuntu 20.04 / macOS 12 / Windows 11	Ubuntu 22.04 LTS
CPU	4 核	8 核+
内存	8GB	16GB+
磁盘	20GB 可用空间	50GB+ SSD
Node.js	v22.x	v22.x LTS

5.2 快速安装（Linux/macOS）

# Step 1: 一键安装脚本
curl -fsSL https://openclaw.ai/install | bash

# Step 2: 启动配置向导
openclaw onboard

# Step 3: 配置 AI 模型 Provider
# 选择 Claude (推荐) 或 GPT-4/Gemini
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# Step 4: 配置通信渠道
# 选择 Telegram/Discord/Slack/飞书等
openclaw channel add telegram

# Step 5: 验证安装
openclaw --version
# 输出：OpenClaw v2026.3.7

# Step 6: 启动 OpenClaw
openclaw start

# 访问 Dashboard
# http://localhost:18789?token=your-token

5.3 Windows 安装（原生/WSL2）

# 方式一：原生 Windows 安装（PowerShell）
# Step 1: 安装 Node.js 22
winget install OpenJS.NodeJS.LTS

# Step 2: 安装 OpenClaw
npm install -g @openclaw/core

# Step 3: 配置环境变量
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-xxxxx", "User")

# Step 4: 启动
openclaw start

# 方式二：WSL2 安装（推荐）
# Step 1: 启用 WSL2
wsl --install -d Ubuntu-22.04

# Step 2: 进入 WSL 环境
wsl

# Step 3: 执行 Linux 安装脚本
curl -fsSL https://openclaw.ai/install | bash

5.4 核心技能包安装

# 安装研发自动化技能合集
openclaw skill install prd-designer
openclaw skill install system-architect
openclaw skill install backend-developer
openclaw skill install frontend-developer
openclaw skill install qa-engineer
openclaw skill install devops-engineer
openclaw skill install ui-tester

# 安装 MCP Servers（Model Context Protocol）
openclaw mcp install github      # GitHub 集成
openclaw mcp install filesystem  # 文件系统操作
openclaw mcp install postgres    # PostgreSQL 数据库
openclaw mcp install playwright  # 浏览器自动化

# 查看已安装技能
openclaw skill list

# 更新所有技能
openclaw skill update --all

5.5 配置文件详解

# ~/.openclaw/config.yaml
# OpenClaw 全局配置文件

# AI 模型配置
models:
  default: claude-opus-4.6
  providers:
    anthropic:
      api_key: ${ANTHROPIC_API_KEY}
      base_url: https://api.anthropic.com
    openai:
      api_key: ${OPENAI_API_KEY}
      base_url: https://api.openai.com/v1

# 通信渠道配置
channels:
  telegram:
    enabled: true
    bot_token: ${TELEGRAM_BOT_TOKEN}
  feishu:
    enabled: true
    app_id: ${FEISHU_APP_ID}
    app_secret: ${FEISHU_APP_SECRET}

# 技能配置
skills:
  prd-designer:
    model: claude-sonnet-4.6
    temperature: 0.7
    max_tokens: 8192
  backend-developer:
    model: claude-opus-4.6
    temperature: 0.3
    max_tokens: 16384

# MCP Servers 配置
mcp:
  servers:
    github:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_TOKEN: ${GITHUB_TOKEN}
    filesystem:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem"]
      config:
        allowed_paths: ["/home/user/projects"]

# 日志配置
logging:
  level: info
  file: /var/log/openclaw/openclaw.log
  max_size: 100MB
  retention_days: 30

🤖 第六章：Claude Code 深度集成指南

6.1 Claude Code 安装

# Step 1: 安装 Node.js 18+
node --version  # 确保 >= 18.x

# Step 2: 全局安装 Claude Code
npm install -g @anthropic-ai/claude-code

# Step 3: 配置 API Key
export CLAUDE_CODE_API_KEY="sk-ant-xxxxx"

# Step 4: 验证安装
claude --version
# 输出：Claude Code v2.1.51

# Step 5: 初始化项目
cd /path/to/your/project
claude init

6.2 多智能体工作流配置

# 创建 .claude/plugins/multi-agent-config.json
{
  "agents": {
    "planner": {
      "model": "claude-opus-4.6",
      "system_prompt": "你是一个专业的需求分析师，擅长将模糊需求拆解为可执行的任务清单",
      "tools": ["file_read", "file_write", "shell"],
      "temperature": 0.7
    },
    "architect": {
      "model": "claude-opus-4.6",
      "system_prompt": "你是资深系统架构师，负责设计高可用、可扩展的技术方案",
      "tools": ["file_read", "file_write", "mermaid_renderer"],
      "temperature": 0.5
    },
    "tdd-guide": {
      "model": "claude-sonnet-4.6",
      "system_prompt": "你是 TDD 专家，坚持'测试先行'原则，确保代码质量",
      "tools": ["file_read", "file_write", "test_runner"],
      "temperature": 0.3
    },
    "code-reviewer": {
      "model": "claude-opus-4.6",
      "system_prompt": "你是代码审查专家，关注代码质量、安全性和最佳实践",
      "tools": ["file_read", "git_diff"],
      "temperature": 0.2
    },
    "security-reviewer": {
      "model": "claude-opus-4.6",
      "system_prompt": "你是安全专家，负责识别 OWASP Top 10 等安全漏洞",
      "tools": ["file_read", "security_scanner"],
      "temperature": 0.2
    }
  },
  "workflow": {
    "sequence": ["planner", "architect", "tdd-guide", "code-reviewer", "security-reviewer"],
    "parallel_allowed": ["code-reviewer", "security-reviewer"]
  }
}

6.3 常用斜杠命令

# Claude Code 内置斜杠命令
/plan          # 生成任务规划
/tdd           # 测试驱动开发模式
/code-review   # 代码审查
/security-scan # 安全漏洞扫描
/multi-plan    # 多智能体协同规划
/instinct-status  # 查看学习到的模式

# 自定义斜杠命令（在 .claude/commands/ 目录下创建）
# 示例：.claude/commands/generate-api.md
---
name: generate-api
description: 根据 PRD 生成 API 设计
---
请根据以下 PRD 文档，设计 RESTful API 接口规范：
1. 列出所有资源 endpoint
2. 定义请求/响应 schema
3. 标注认证要求
4. 生成 OpenAPI 3.0 规范文件

6.4 Hooks 配置（自动化触发）

# .claude/hooks/before-commit.json
{
  "hook": "before-commit",
  "command": "claude",
  "args": [
    "--prompt",
    "检查暂存区的代码变更，进行代码审查并给出改进建议"
  ]
}

# .claude/hooks/after-merge.json
{
  "hook": "after-merge",
  "command": "openclaw",
  "args": [
    "run",
    "qa-engineer",
    "--type",
    "regression",
    "--branch",
    "${MERGE_BRANCH}"
  ]
}

6.5 Rules 配置（编码规范）

# CLAUDE.md (项目根目录)
# 项目级编码规范，Claude Code 会自动读取并遵守

# 技术栈
- Backend: Java 17, Spring Boot 3.2
- Frontend: React 18, TypeScript 5, TailwindCSS
- Database: MySQL 8.0, Redis 7.0
- Testing: JUnit 5, Playwright

# 代码规范
- 使用 4 空格缩进
- 函数长度不超过 50 行
- 所有公共方法必须有 Javadoc
- 禁止使用 System.out.println，使用 SLF4J 日志

# 提交规范
- Commit message 遵循 Conventional Commits
- 格式：(): 
- 示例：feat(member): 添加会员等级查询接口

# 安全要求
- 所有用户输入必须校验
- 密码必须 bcrypt 加密
- API 必须 JWT 认证
- 敏感配置从环境变量读取

🚀 第七章：CI/CD + Docker + K8S 自动化部署

7.1 Jenkins Pipeline 配置

// Jenkinsfile (声明式 Pipeline)
pipeline {
    agent any
    
    environment {
        DOCKER_REGISTRY = 'harbor.example.com'
        K8S_NAMESPACE = 'membership-prod'
        APP_NAME = 'membership-service'
    }
    
    stages {
        stage('Checkout') {
            steps {
                checkout scm
                echo "代码检出完成"
            }
        }
        
        stage('Code Quality') {
            steps {
                sh 'mvn checkstyle:check'
                sh 'mvn spotbugs:check'
                script {
                    def qualityGate = sh(script: 'mvn sonar:sonar', returnStatus: true)
                    if (qualityGate != 0) {
                        error 'SonarQube 质量门禁未通过'
                    }
                }
            }
        }
        
        stage('Unit Test') {
            steps {
                sh 'mvn clean test'
                junit '**/target/surefire-reports/*.xml'
                publishCoverage adapters: [jacocoAdapter()], sourceFileEncoding: 'UTF-8'
            }
        }
        
        stage('Build Docker Image') {
            steps {
                script {
                    def version = sh(script: 'mvn help:evaluate -Dexpression=project.version -q', returnStdout: true).trim()
                    def imageTag = "${DOCKER_REGISTRY}/${APP_NAME}:${version}-${BUILD_NUMBER}"
                    
                    sh """
                        docker build -t ${imageTag} .
                        docker push ${imageTag}
                    """
                    
                    env.DOCKER_IMAGE = imageTag
                }
            }
        }
        
        stage('Deploy to K8S') {
            steps {
                script {
                    sh """
                        kubectl set image deployment/${APP_NAME} \
                            ${APP_NAME}=${DOCKER_IMAGE} \
                            -n ${K8S_NAMESPACE}
                        
                        kubectl rollout status deployment/${APP_NAME} \
                            -n ${K8S_NAMESPACE} \
                            --timeout=300s
                    """
                }
            }
        }
        
        stage('Smoke Test') {
            steps {
                sh '''
                    curl -f http://${APP_NAME}.${K8S_NAMESPACE}.svc.cluster.local:8080/health || exit 1
                '''
            }
        }
        
        stage('Notify') {
            always {
                script {
                    if (currentBuild.result == 'SUCCESS') {
                        // 发送成功通知到飞书/钉钉
                        sh 'openclaw run notify --channel feishu --message "部署成功：${APP_NAME} v${DOCKER_IMAGE}"'
                    } else {
                        // 发送失败告警
                        sh 'openclaw run notify --channel feishu --message "部署失败：${APP_NAME}" --level critical'
                    }
                }
            }
        }
    }
    
    post {
        failure {
            echo '构建失败，正在回滚...'
            sh "kubectl rollout undo deployment/${APP_NAME} -n ${K8S_NAMESPACE}"
        }
    }
}

7.2 Dockerfile 最佳实践

# 多阶段构建 Dockerfile
# Stage 1: 构建阶段
FROM maven:3.9-eclipse-temurin-17 AS builder

WORKDIR /app

# 利用 Docker 缓存层加速构建
COPY pom.xml .
RUN mvn dependency:go-offline -B

COPY src ./src
RUN mvn clean package -DskipTests -B

# Stage 2: 运行阶段
FROM eclipse-temurin:17-jre-alpine

# 创建非 root 用户
RUN addgroup -S appgroup && adduser -S appuser -G appgroup

WORKDIR /app

# 从构建阶段复制 jar 包
COPY --from=builder /app/target/*.jar app.jar

# JVM 优化参数
ENV JAVA_OPTS="-Xms512m -Xmx1024m \
    -XX:+UseG1GC \
    -XX:MaxGCPauseMillis=200 \
    -XX:+HeapDumpOnOutOfMemoryError \
    -XX:HeapDumpPath=/logs/heapdump.hprof"

# 暴露端口
EXPOSE 8080

# 切换到非 root 用户
USER appuser

# 健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=60s --retries=3 \
    CMD wget -qO- http://localhost:8080/actuator/health || exit 1

ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]

7.3 Kubernetes 部署配置

# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: membership-service
  namespace: membership-prod
  labels:
    app: membership-service
    version: v1.0.0
spec:
  replicas: 3
  selector:
    matchLabels:
      app: membership-service
  template:
    metadata:
      labels:
        app: membership-service
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "8080"
        prometheus.io/path: "/actuator/prometheus"
    spec:
      containers:
      - name: membership-service
        image: harbor.example.com/membership-service:v1.0.0-123
        ports:
        - containerPort: 8080
          name: http
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "1Gi"
            cpu: "500m"
        env:
        - name: SPRING_PROFILES_ACTIVE
          value: "prod"
        - name: DB_HOST
          valueFrom:
            secretKeyRef:
              name: db-credentials
              key: host
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: db-credentials
              key: password
        livenessProbe:
          httpGet:
            path: /actuator/health/liveness
            port: 8080
          initialDelaySeconds: 60
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /actuator/health/readiness
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 5
        volumeMounts:
        - name: logs
          mountPath: /logs
      volumes:
      - name: logs
        emptyDir: {}
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            podAffinityTerm:
              labelSelector:
                matchLabels:
                  app: membership-service
              topologyKey: kubernetes.io/hostname

---
# k8s/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: membership-service
  namespace: membership-prod
spec:
  selector:
    app: membership-service
  ports:
  - port: 80
    targetPort: 8080
    protocol: TCP
  type: ClusterIP

---
# k8s/ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: membership-ingress
  namespace: membership-prod
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  tls:
  - hosts:
    - membership.example.com
    secretName: membership-tls
  rules:
  - host: membership.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: membership-service
            port:
              number: 80

7.4 KubeSphere 集成配置

# KubeSphere DevOps 项目配置
# 通过 KubeSphere Web Console 或 API 配置

# Step 1: 创建 DevOps 项目
ks create devops-project membership-devops \
  --description "会员系统 DevOps 项目"

# Step 2: 配置 Jenkins Pipeline
ks create pipeline membership-pipeline \
  --devops-project membership-devops \
  --jenkinsfile-file Jenkinsfile

# Step 3: 配置触发器
ks edit pipeline membership-pipeline \
  --scm-trigger \
  --cron-trigger "H */2 * * *"  # 每 2 小时轮询一次

# Step 4: 配置质量门禁
ks edit pipeline membership-pipeline \
  --quality-gate '{
    "sonarqube_condition_qualitygate": {
      "status": "OK",
      "metric": "coverage",
      "operator": ">=",
      "value": "80"
    }
  }'

# Step 5: 配置通知
ks edit pipeline membership-pipeline \
  --notification '{
    "feishu": {
      "webhook": "https://open.feishu.cn/open-apis/bot/v2/hook/xxx",
      "events": ["success", "failure"]
    }
  }'

7.5 Helm Chart 打包部署

# 创建 Helm Chart
helm create membership-chart

# 编辑 Chart.yaml
apiVersion: v2
name: membership-service
description: A Helm chart for Membership Service
type: application
version: 1.0.0
appVersion: "1.0.0"
dependencies:
- name: mysql
  version: 9.0.0
  repository: https://charts.bitnami.com/bitnami
  condition: mysql.enabled
- name: redis
  version: 18.0.0
  repository: https://charts.bitnami.com/bitnami
  condition: redis.enabled

# 编辑 values-prod.yaml (生产环境配置)
replicaCount: 3
image:
  repository: harbor.example.com/membership-service
  tag: "v1.0.0"
resources:
  limits:
    cpu: 500m
    memory: 1Gi
  requests:
    cpu: 250m
    memory: 512Mi
autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80
mysql:
  enabled: false  # 使用外部 RDS
redis:
  enabled: false  # 使用外部 Redis

# 安装 Chart
helm install membership-release ./membership-chart \
  -f values-prod.yaml \
  --namespace membership-prod \
  --create-namespace

# 升级部署
helm upgrade membership-release ./membership-chart \
  -f values-prod.yaml \
  --namespace membership-prod \
  --set image.tag=v1.0.1

# 回滚
helm rollback membership-release 1 --namespace membership-prod

🧪 第八章：UI 自动化测试验收

8.1 Playwright 测试框架配置

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests/ui',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [
    ['html', { outputFolder: 'reports/ui/html' }],
    ['junit', { outputFile: 'reports/ui/junit.xml' }],
    ['json', { outputFile: 'reports/ui/results.json' }]
  ],
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:3000',
    trace: 'on-first-retry',
    video: 'retain-on-failure',
    screenshot: 'only-on-failure',
    actionTimeout: 10000,
    navigationTimeout: 30000,
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
    {
      name: 'Mobile Chrome',
      use: { ...devices['Pixel 5'] },
    },
    {
      name: 'Mobile Safari',
      use: { ...devices['iPhone 12'] },
    },
  ],
  webServer: {
    command: 'npm run start',
    url: 'http://localhost:3000',
    timeout: 120000,
  },
});

8.2 测试用例示例

// tests/ui/checkin-flow.spec.ts
import { test, expect } from '@playwright/test';

test.describe('签到流程测试', () => {
  test.beforeEach(async ({ page }) => {
    // 前置条件：登录
    await page.goto('/login');
    await page.fill('[data-testid="username"]', 'testuser');
    await page.fill('[data-testid="password"]', 'Test@123456');
    await page.click('[data-testid="login-button"]');
    await expect(page).toHaveURL('/home');
  });

  test('普通签到成功', async ({ page }) => {
    await page.goto('/checkin');
    
    // 点击签到按钮
    await page.click('[data-testid="checkin-button"]');
    
    // 验证签到成功提示
    await expect(page.locator('.toast-success'))
      .toContainText('签到成功！获得 10 积分');
    
    // 验证积分变化
    const pointsText = await page.textContent('[data-testid="points-balance"]');
    expect(pointsText).toMatch(/今日积分：\d+/);
    
    // 验证签到状态
    await expect(page.locator('[data-testid="checkin-status"]'))
      .toHaveText('今日已签到');
  });

  test('连续签到 7 天领取优惠券', async ({ page }) => {
    // Mock API 返回连续签到 6 天的数据
    await page.route('**/api/checkin/status', async route => {
      await route.fulfill({
        json: {
          consecutiveDays: 6,
          hasCheckedInToday: false
        }
      });
    });

    await page.goto('/checkin');
    await page.click('[data-testid="checkin-button"]');
    
    // 验证第 7 天签到奖励
    await expect(page.locator('.coupon-modal'))
      .toBeVisible();
    
    await expect(page.locator('[data-testid="coupon-amount"]'))
      .toHaveText('¥20 优惠券');
    
    // 领取优惠券
    await page.click('[data-testid="claim-coupon"]');
    await expect(page.locator('.toast-success'))
      .toContainText('优惠券已发放至您的账户');
  });

  test('断签后重新累计', async ({ page }) => {
    // Mock 昨天未签到的数据
    await page.route('**/api/checkin/history', async route => {
      await route.fulfill({
        json: {
          lastCheckInDate: '2026-03-10', // 假设今天是 3 月 12 日
          consecutiveDays: 0
        }
      });
    });

    await page.goto('/checkin');
    await page.click('[data-testid="checkin-button"]');
    
    // 验证连续天数重置为 1
    await expect(page.locator('[data-testid="consecutive-days"]'))
      .toHaveText('连续签到：1 天');
  });
});

8.3 视觉回归测试

// tests/ui/visual-regression.spec.ts
import { test, expect } from '@playwright/test';

test.describe('视觉回归测试', () => {
  test('会员页面视觉对比', async ({ page }) => {
    await page.goto('/membership');
    
    // 截取全屏并与基准对比
    await expect(page).toHaveScreenshot('membership-page.png', {
      maxDiffPixels: 100,  // 允许的最大差异像素数
      threshold: 0.2,      // 颜色阈值
      fullPage: true,
    });
  });

  test('签到按钮状态对比', async ({ page }) => {
    await page.goto('/checkin');
    
    // 未签到状态
    await expect(page.locator('[data-testid="checkin-button"]'))
      .toHaveScreenshot('checkin-button-default.png');
    
    // 点击后禁用状态
    await page.click('[data-testid="checkin-button"]');
    await expect(page.locator('[data-testid="checkin-button"]'))
      .toHaveScreenshot('checkin-button-disabled.png');
  });
});

8.4 性能测试集成

// tests/ui/performance.spec.ts
import { test, expect } from '@playwright/test';

test.describe('性能测试', () => {
  test('首页加载性能', async ({ page }) => {
    const client = await page.context().newCDPSession(page);
    await client.send('Performance.enable');
    
    const startTime = Date.now();
    await page.goto('/');
    const loadTime = Date.now() - startTime;
    
    // 验证加载时间 < 2 秒
    expect(loadTime).toBeLessThan(2000);
    
    // 获取性能指标
    const metrics = await client.send('Performance.getMetrics');
    const fcp = metrics.metrics.find(m => m.name === 'DomContentLoaded');
    expect(fcp!.value).toBeLessThan(1.5);
  });

  test('API 响应时间', async ({ page }) => {
    const responseTimes: number[] = [];
    
    page.on('response', response => {
      if (response.url().includes('/api/')) {
        responseTimes.push(response.timing().receiveHeadersEnd);
      }
    });
    
    await page.goto('/membership');
    await page.waitForLoadState('networkidle');
    
    const avgResponseTime = responseTimes.reduce((a, b) => a + b, 0) / responseTimes.length;
    console.log(`平均 API 响应时间：${avgResponseTime.toFixed(2)}ms`);
    
    // 验证平均响应时间 < 500ms
    expect(avgResponseTime).toBeLessThan(500);
  });
});

8.5 测试报告生成

# 执行 UI 自动化测试并生成报告
npx playwright test \
  --config=playwright.config.ts \
  --reporter=html,junit,json \
  --project=chromium \
  --grep="签到流程"

# 查看 HTML 报告
npx playwright show-report reports/ui/html

# 生成 Allure 报告（可选）
npx playwright test --reporter=allure-playwright
allure serve allure-results

# 集成到 CI/CD
# 在 Jenkins Pipeline 中添加：
stage('UI Test') {
    steps {
        sh 'npx playwright test --reporter=junit'
        junit 'reports/ui/junit.xml'
        archiveArtifacts artifacts: 'reports/ui/**/*', allowEmptyArchive: true
    }
}

🤝 第九章：人机协同操作指南

9.1 人机协同节点设计

💡 设计原则：关键决策点保留人工审核，重复性工作完全自动化，形成"AI 执行→人工确认→AI 优化"的良性循环。

研发阶段	自动化程度	人工介入点	协同方式
需求分析	70%	需求优先级确认、范围界定	AI 生成 PRD→PM 审核修订
技术架构	60%	技术选型决策、架构评审	AI 设计方案→架构师评审会
代码开发	90%	核心算法、复杂业务逻辑	AI 生成代码→Developer 优化
代码审查	80%	高风险变更、安全敏感代码	AI 初审→Senior 复审
测试验证	95%	探索性测试、用户体验测试	AI 执行自动化→QA 补充手工
部署上线	85%	生产环境发布审批	AI 自动部署→TL 审批发布

9.2 人工审核工作流配置

# .openclaw/workflow-approval.yaml
# 人机协同审批流配置

approval_gates:
  prd_review:
    description: "PRD 文档审核"
    approvers:
      - role: product_manager
        required: true
      - role: tech_lead
        required: false
    conditions:
      - field: story_points
        operator: ">"
        value: 13  # 超过 13 点需要额外审核
    notification:
      channel: feishu
      template: "请审核 PRD 文档：{{prd_url}}"
    
  architecture_review:
    description: "技术方案评审"
    approvers:
      - role: architect
        required: true
      - role: security_officer
        required: true
    conditions:
      - field: involves_payment
        operator: "=="
        value: true
      - field: involves_pii_data
        operator: "=="
        value: true
    meeting_required: true
    meeting_duration_minutes: 60
    
  code_review:
    description: "代码合并审核"
    approvers:
      - role: senior_developer
        required: true
    conditions:
      - field: changed_files
        operator: ">"
        value: 10
      - field: lines_changed
        operator: ">"
        value: 500
    auto_approve_if:
      - condition: test_coverage >= 90
      - condition: security_scan_passed == true
      
  production_deploy:
    description: "生产环境部署审批"
    approvers:
      - role: tech_director
        required: true
      - role: ops_manager
        required: true
    conditions:
      - field: deploy_time
        operator: "not_in"
        value: ["02:00-06:00"]  # 禁止凌晨发布
      - field: day_of_week
        operator: "not_in"
        value: ["Friday", "Saturday"]  # 禁止周五周六发布
    rollback_plan_required: true

9.3 交互式确认机制

# OpenClaw 交互式确认配置
# 在执行关键操作前暂停并等待人工确认

openclaw run backend-developer \
  --input docs/api/openapi.yaml \
  --output src/backend/ \
  --confirm-before-execute \
  --confirmation-prompt "即将生成 {{estimated_files}} 个文件，预计耗时 {{estimated_time}} 分钟，是否继续？"

# 配置自动暂停点
# ~/.openclaw/pause-points.yaml
pause_points:
  - operation: "database_migration"
    reason: "数据库变更不可逆，需人工确认"
    timeout_minutes: 30
    
  - operation: "production_deploy"
    reason: "生产环境部署需审批"
    timeout_minutes: 60
    
  - operation: "delete_resource"
    reason: "删除操作需谨慎"
    timeout_minutes: 15
    
  - operation: "external_api_call"
    condition: "cost > 10"  # 单次调用成本超过$10 需确认
    reason: "高成本 API 调用"
    timeout_minutes: 10

9.4 异常处理与人工接管

# 异常处理配置
# ~/.openclaw/exception-handling.yaml

exception_handlers:
  - error_type: "compilation_error"
    max_auto_retries: 3
    after_retries: "notify_human"
    notification:
      channel: slack
      message: "编译失败，已尝试自动修复 {{retry_count}} 次，请人工介入"
      include_logs: true
      
  - error_type: "test_failure"
    failure_threshold: 0.2  # 失败率超过 20% 时告警
    action: "create_jira_ticket"
    ticket_template:
      project: "BUG"
      type: "Bug"
      priority: "High"
      description: |
        自动化测试发现失败：
        - 失败用例：{{failed_tests}}
        - 错误信息：{{error_message}}
        - 堆栈跟踪：{{stack_trace}}
        
  - error_type: "deployment_failure"
    action: "auto_rollback"
    rollback_timeout_seconds: 300
    notify_on_rollback: true
    escalation:
      if_rollback_fails: "page_oncall"
      
  - error_type: "ai_hallucination"
    detection_method: "consistency_check"
    action: "flag_for_review"
    reviewer_role: "tech_lead"

9.5 反馈循环与持续优化

# 人工反馈收集机制
# 每次人工审核后记录反馈用于优化 AI

openclaw collect-feedback \
  --task-id TASK-2026-0314-001 \
  --reviewer "张三" \
  --rating 4 \
  --comments "代码整体质量不错，但异常处理可以更完善" \
  --suggestions "建议增加全局异常处理器，统一错误响应格式"

# 定期生成优化报告
openclaw generate-optimization-report \
  --period "last_30_days" \
  --output reports/ai-optimization-2026-03.md

# 报告内容包括：
# - AI 生成代码采纳率统计
# - 人工修改热点分析
# - 常见错误模式识别
# - 技能包优化建议

✨ 第十章：最佳实践与常见问题

10.1 最佳实践清单

✅ 推荐做法：
1. 小步快跑：将大需求拆分为小任务，每个任务独立验证
2. 测试先行：始终先生成测试再实现功能
3. 渐进式自动化：从 50% 自动化开始，逐步提升到 90%+
4. 文档即代码：PRD、设计文档与代码同步维护
5. 安全左移：在设计和编码阶段就引入安全检查
6. 监控驱动：部署后立即验证监控告警是否正常
7. 回滚预案：每次发布前准备好一键回滚方案

❌ 避免陷阱：
1. 过度信任 AI：关键代码必须人工审查
2. 忽视测试覆盖：AI 生成的代码也需要充分测试
3. 一次性大重构：避免大规模改动，采用渐进式重构
4. 跳过文档：自动化不等于不需要文档
5. 忽略成本控制：监控 AI Token 消耗，设置预算告警

10.2 性能优化技巧

# 1. 并行化执行
# 同时启动多个 Agents 并行工作
openclaw run backend-developer &
openclaw run frontend-developer &
openclaw run qa-engineer --type unit &
wait

# 2. 增量构建
# 只重新生成变更部分的代码
openclaw run backend-developer \
  --incremental \
  --changed-files $(git diff --name-only HEAD~1)

# 3. 缓存优化
# 复用已生成的代码片段
openclaw run backend-developer \
  --use-cache \
  --cache-dir ~/.openclaw/cache

# 4. 模型选择优化
# 简单任务用 Sonnet，复杂任务用 Opus
if [[ $COMPLEXITY == "low" ]]; then
  MODEL="claude-sonnet-4.6"
else
  MODEL="claude-opus-4.6"
fi

10.3 常见问题 FAQ

Q1: AI 生成的代码质量不稳定怎么办？

A: 建立多层质量保障机制：

配置 ESLint/Checkstyle 等静态检查工具自动拦截低质量代码
设置代码审查门槛，AI 初审 + 高级开发复审
要求 AI 生成代码时必须附带单元测试
建立代码模板库，让 AI 基于模板生成而非从零开始

Q2: 如何处理 AI 的幻觉问题（生成不存在的 API）？

A: 实施一致性验证：

使用 MCP Server 实时查询真实 API 文档
编译时自动验证 API 调用是否存在
配置 AI 在不确定时主动提问而非猜测
建立知识库，让 AI 可以检索历史正确用法

Q3: CI/CD 流水线执行太慢如何优化？

A: 多维度优化策略：

并行化：单元测试、集成测试、E2E 测试并行执行
增量构建：只测试变更影响的模块
缓存依赖：Maven/npm 依赖缓存到共享存储
弹性资源：高峰期动态增加 Jenkins Agent 节点
分层测试：提交阶段只跑快速测试，夜间跑全量测试

Q4: 如何控制 AI Token 成本？

A: 成本优化措施：

设置每日/每月预算告警
简单任务使用更便宜的模型（Sonnet vs Opus）
压缩上下文：只传递必要的代码片段
复用历史对话：避免重复解释背景信息
本地模型：非关键任务使用本地部署的开源模型

Q5: K8S 部署失败如何快速定位问题？

A: 标准化排查流程：

# Step 1: 查看 Pod 状态
kubectl get pods -n  -o wide
kubectl describe pod  -n 

# Step 2: 查看容器日志
kubectl logs  -n  --previous
kubectl logs  -n  -c 

# Step 3: 进入容器调试
kubectl exec -it  -n  -- /bin/sh

# Step 4: 检查事件
kubectl get events -n  --sort-by='.lastTimestamp'

# Step 5: AI 辅助诊断
openclaw diagnose-k8s-issue \
  --namespace  \
  --pod  \
  --since 1h

10.4 监控与告警配置

# Prometheus 监控规则
# prometheus-rules.yaml
apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: ai-devops-alerts
  namespace: monitoring
spec:
  groups:
  - name: ai_pipeline_alerts
    rules:
    - alert: AIPipelineHighFailureRate
      expr: |
        sum(rate(jenkins_build_result_total{result="FAILURE"}[5m])) 
        / sum(rate(jenkins_build_result_total[5m])) > 0.2
      for: 5m
      labels:
        severity: warning
      annotations:
        summary: "AI 流水线失败率过高"
        description: "过去 5 分钟 AI 流水线失败率为 {{ $value | humanizePercentage }}"
        
    - alert: AITokenBudgetExceeded
      expr: |
        sum(openclaw_token_usage_total) > 1000000
      for: 1h
      labels:
        severity: critical
      annotations:
        summary: "AI Token 使用超出预算"
        description: "本月已使用 {{ $value }} tokens，预算 100 万"
        
    - alert: DeploymentRollbackDetected
      expr: |
        increase(kube_deployment_status_replicas_unavailable[5m]) > 0
      for: 2m
      labels:
        severity: critical
      annotations:
        summary: "检测到部署回滚"
        description: "部署 {{ $labels.deployment }} 发生回滚"

# 告警通知配置
# alertmanager-config.yaml
route:
  group_by: ['alertname', 'severity']
  receiver: 'feishu-notifications'
  routes:
  - match:
      severity: critical
    receiver: 'pagerduty-critical'
  - match:
      severity: warning
    receiver: 'feishu-warnings'

receivers:
- name: 'feishu-notifications'
  webhook_configs:
  - url: 'https://open.feishu.cn/open-apis/bot/v2/hook/xxx'
    send_resolved: true
    
- name: 'pagerduty-critical'
  pagerduty_configs:
  - service_key: 'your-pagerduty-key'
    description: '{{ .CommonAnnotations.summary }}'