ai-code-factory-workflow

name: ai-code-factory-workflow version: "5.1" status: ready_for_production layer: skill owner: wade last_reviewed: 2026-01-09 baseline: AI_CODE_FACTORY v5.1, wshobson/agents integration

核心能力：
- 理解用户的自然语言需求
- 自动选择合适的工作流类型
- 调用多个专业代理（system-architect, backend-architect, frontend-developer 等）
- 实际执行任务并返回完整结果
- 支持全栈开发、代码审查、Bug 修复、性能优化、系统架构等工作流

- "创建一个...功能"
- "开发...功能"
- "实现...功能"
- "帮我做一个..."
- "审查代码"
- "代码审查"
- "修复 bug"
- "修复...问题"
- "优化性能"
- "优化...性能"
- "设计架构"
- "系统架构"
- "使用代码工厂"
- "使用工作流"
- "执行工作流"

<workflow_types>

### 2.1 全栈功能开发 (full_stack_development)

**触发关键词**: "创建"、"开发"、"实现"、"做一个"、"功能"

**执行顺序**:
1. system-architect (Opus 4.5) - 系统架构设计
2. backend-architect (Opus 4.5) - 后端 API 开发
3. frontend-developer (Sonnet 4.5) - 前端页面开发
4. code-reviewer (Opus 4.5) - 代码审查
5. test-automator (Sonnet 4.5) - 测试生成

**示例**:
- "创建一个用户管理功能，包括列表、创建、编辑、删除"
- "开发一个订单系统"
- "实现日报审核功能"

### 2.2 代码审查 (code_review)

**触发关键词**: "审查"、"检查"、"review"、"代码质量"、"安全性"

**执行模式**: 并行执行
- code-reviewer (Opus 4.5) - 代码质量审查
- security-auditor (Opus 4.5) - 安全审计
- performance-engineer (Opus 4.5) - 性能分析

**示例**:
- "审查用户管理模块的代码质量"
- "检查这段代码的安全性"
- "review 一下这个 API"

### 2.3 Bug 修复 (bug_fixing)

**触发关键词**: "修复"、"bug"、"问题"、"错误"、"调试"

**执行顺序**:
1. debugging-specialist (Opus 4.5) - 调试分析
2. code-reviewer (Opus 4.5) - 代码审查
3. test-automator (Sonnet 4.5) - 测试生成

**示例**:
- "修复用户登录功能的 bug"
- "解决日报审核的问题"
- "调试充值流程的错误"

### 2.4 性能优化 (performance_optimization)

**触发关键词**: "优化"、"性能"、"慢"、"提速"、"performance"

**执行顺序**:
1. performance-engineer (Opus 4.5) - 性能分析
2. backend-architect (Opus 4.5) - 优化实现
3. code-reviewer (Opus 4.5) - 代码审查

**示例**:
- "优化用户列表查询性能"
- "提升日报加载速度"
- "优化数据库查询"

### 2.5 系统架构 (system_architecture)

**触发关键词**: "架构"、"设计"、"architecture"、"系统设计"

**执行顺序**:
1. system-architect (Opus 4.5) - 架构设计
2. code-reviewer (Opus 4.5) - 架构审查

**示例**:
- "设计微服务架构方案"
- "设计用户权限系统架构"
- "系统架构设计"

</workflow_types>

<execution_flow>

### Step 1: 理解需求

当用户使用自然语言描述需求时，你需要：

1. **解析需求**: 提取关键信息（功能、模块、要求等）
2. **识别工作流类型**: 根据关键词自动识别工作流类型
3. **确认需求**: 如果需求不明确，询问用户澄清

### Step 2: 调用代码工厂

使用 Python 代码调用代码工厂：

```python
from agents.skills.code_factory.core.orchestrator import CodeFactoryOrchestrator

# 创建编排器
orchestrator = CodeFactoryOrchestrator()

# 执行工作流
result = orchestrator.execute(
    requirement="用户的需求描述",
    workflow_type="识别的工作流类型"
)
```

### Step 3: 处理结果

1. **检查执行状态**:
   - `completed`: 所有代理执行成功
   - `partial_failure`: 部分代理执行失败
   - `ready`: 准备就绪（未实际执行）

2. **展示执行结果**:
   - 列出每个代理的执行结果
   - 显示代理输出（代码、建议、分析等）
   - 显示错误信息（如果有）

3. **展示性能指标**:
   - Token 使用量
   - 执行时间
   - 错误率
   - 缓存命中率

4. **提供后续建议**:
   - 如果成功，提供下一步操作建议
   - 如果失败，提供错误修复建议

</execution_flow>

<usage_examples>

### 示例 1: 创建功能

**用户输入**:
```
创建一个用户管理功能，包括：
1. 后端 API：列表（分页、搜索）、创建、编辑、删除
2. 前端页面：用户列表、创建表单、编辑表单
3. 数据验证：用户名唯一、邮箱格式
4. 权限控制：只有管理员可以删除
```

**你的处理**:
1. 识别为 `full_stack_development` 工作流
2. 调用代码工厂执行
3. 展示每个代理的输出（架构设计、后端代码、前端代码、审查结果、测试代码）
4. 提供集成建议

### 示例 2: 代码审查

**用户输入**:
```
审查用户管理模块的代码质量和安全性
```

**你的处理**:
1. 识别为 `code_review` 工作流
2. 并行调用三个审查代理
3. 展示审查结果（质量、安全、性能）
4. 提供改进建议

### 示例 3: Bug 修复

**用户输入**:
```
修复用户登录功能的问题：
用户输入错误密码 3 次后，账户被锁定，但解锁逻辑有问题
```

**你的处理**:
1. 识别为 `bug_fixing` 工作流
2. 调用调试专家分析问题
3. 调用代码审查员审查修复方案
4. 生成测试用例
5. 展示修复代码和测试

### 示例 4: 性能优化

**用户输入**:
```
优化用户列表查询性能，当前查询 1000 条记录需要 5 秒，目标优化到 1 秒以内
```

**你的处理**:
1. 识别为 `performance_optimization` 工作流
2. 调用性能工程师分析瓶颈
3. 调用后端架构师实现优化
4. 调用代码审查员审查优化方案
5. 展示优化建议和代码

### 示例 5: 系统架构

**用户输入**:
```
设计微服务架构方案，包括用户服务、订单服务、支付服务
```

**你的处理**:
1. 识别为 `system_architecture` 工作流
2. 调用系统架构师设计架构
3. 调用代码审查员审查架构
4. 展示架构设计文档和图表

</usage_examples>

<output_format>

### 标准输出格式

```markdown
## 🎯 工作流执行结果

### 📋 需求
{用户的需求描述}

### 🔄 工作流类型
{识别的工作流类型}

### ✅ 执行状态
{completed / partial_failure / ready}

### 📊 执行结果

#### 代理 1: {agent_id}
- **状态**: ✅ 成功 / ❌ 失败
- **输出**: 
{代理的输出内容}
- **Token 使用**: {tokens_used}
- **执行时间**: {execution_time}s

#### 代理 2: {agent_id}
...

### 📈 性能指标
- **总 Token**: {total_tokens}
- **平均时间**: {avg_time}s
- **错误率**: {error_rate}%
- **缓存命中率**: {cache_hit_rate}%

### 💡 后续建议
{根据执行结果提供的建议}
```

</output_format>

<error_handling>

### 6.1 需求不明确

如果用户需求不明确，询问澄清：

```
您的需求不够明确，请提供以下信息：
1. 具体要实现什么功能？
2. 涉及哪些模块（前端/后端/数据库）？
3. 有什么特殊要求？
```

### 6.2 工作流类型无法识别

如果无法识别工作流类型，询问用户：

```
无法自动识别工作流类型，请选择：
1. full_stack_development - 全栈功能开发
2. code_review - 代码审查
3. bug_fixing - Bug 修复
4. performance_optimization - 性能优化
5. system_architecture - 系统架构
```

### 6.3 执行失败

如果执行失败，提供错误信息和修复建议：

```
❌ 执行失败

**错误信息**: {error_message}

**可能原因**:
1. API 密钥未设置（使用模拟模式）
2. 代理加载失败
3. 网络问题

**修复建议**:
1. 检查 ANTHROPIC_API_KEY 环境变量
2. 检查网络连接
3. 查看详细日志
```

</error_handling>

<best_practices>

### 7.1 需求描述

✅ **好的需求**:
- 清晰具体
- 包含功能点
- 包含技术要求
- 包含特殊要求

❌ **不好的需求**:
- 过于简单（"做个用户管理"）
- 过于复杂（一次性描述太多功能）
- 缺少关键信息

### 7.2 工作流选择

- **创建新功能**: 使用 `full_stack_development`
- **审查现有代码**: 使用 `code_review`
- **修复已知问题**: 使用 `bug_fixing`
- **优化性能瓶颈**: 使用 `performance_optimization`
- **架构设计**: 使用 `system_architecture`

### 7.3 结果处理

- 如果成功，提供集成建议和下一步操作
- 如果部分失败，重点展示失败部分，提供修复建议
- 如果完全失败，提供详细的错误分析和修复步骤

</best_practices>

<technical_details>

### 8.1 代码工厂位置

- 编排器: `agents/skills/code_factory/core/orchestrator.py`
- 执行器: `agents.skills.code_factory.core.agent_executor.AgentExecutor`
- 工作流: `agents.skills.code_factory.workflow.presets.WorkflowPresets`

### 8.2 环境要求

- Python 3.8+
- `anthropic>=0.34.0` (可选，无密钥时使用模拟模式)
- 环境变量: `ANTHROPIC_API_KEY` (可选)

### 8.3 模型策略

- **Tier 1 (Opus 4.5)**: 系统架构、代码生成、代码审查、Bug 修复、性能优化
- **Tier 2 (Sonnet 4.5)**: 文档生成、测试生成、代码格式化、简单重构

### 8.4 缓存机制

- 代理和技能自动缓存（LRU）
- 缓存大小: 100（可配置）
- 缓存命中率: 通常 60-80%

</technical_details>

### 9.1 API 密钥

- 如果没有设置 `ANTHROPIC_API_KEY`，系统会使用模拟模式
- 模拟模式返回模拟结果，不实际调用 Claude API

### 9.2 模型映射

- 当前 `opus-4.5` 映射到 `claude-3-5-sonnet-20241022`（临时方案）
- 等待 Opus 正式发布后更新

### 9.3 并行执行

- 当前并行执行是同步的
- 真正的异步并行需要异步支持（已提供 `execute_parallel_async` 方法）

### 9.4 Token 限制

- 每次执行有 Token 限制
- 复杂任务可能需要多次执行

### v5.1 (2026-01-09)
- 初始版本
- 支持 5 种工作流类型
- 集成 wshobson/agents 代理系统
- 支持自然语言调用
- 支持性能监控