第 12 集：从 Vibe Coding 到 Agentic Engineering

你：帮我设计积分表结构
AI：[给出表结构]
你：好，帮我生成 Prisma Schema
AI：[生成 Schema]
你：帮我生成 PointsService
AI：[生成 Service]
你：帮我生成测试
AI：[生成测试]
你：测试失败了，帮我修复
AI：[修复]
... 共 10 轮对话

你：实现用户积分系统，字段参考 PRD.md，需要完整的 CRUD、单元测试、Swagger 文档
Agent 系统：[自动完成以下步骤]
  1. 需求分析 Agent 读取 PRD.md，生成任务清单
  2. 代码生成 Agent 生成 Schema、Service、Controller
  3. 测试 Agent 生成并运行测试
  4. 测试失败 → 代码修复 Agent 自动修复 → 重新运行测试
  5. 全绿后，Review Agent 做安全扫描
  6. 所有步骤完成，向你汇报
你：[去干别的事，回来看结果]

需求分析 Agent 的 Goal：
- 输入：原始需求文档（自然语言）
- 职责：识别模糊需求、拆解成具体任务、输出任务清单
- 成功标准：输出的任务清单包含所有功能点，每条任务边界清晰，可以直接交给代码生成 Agent 执行
- 失败处理：如果需求里有无法确定的部分，标记出来，等待人工确认

需求分析 Agent 的 Goal：分析需求

// 文件操作工具
readFile(path: string): string
writeFile(path: string, content: string): void
listFiles(directory: string): string[]

// 代码执行工具
executeCommand(command: string): { stdout: string, stderr: string, exitCode: number }
runTests(pattern?: string): TestResult

// 搜索工具
searchCode(query: string, directory: string): SearchResult[]
searchDocs(query: string): string

// 外部 API 工具
callApi(url: string, method: string, body?: object): ApiResponse
sendNotification(message: string, channel: string): void

把以下内容存入向量数据库：
- 项目规范文档（.cursorrules、code-style.md）
- 历史上出现过的 Bug 和解决方案
- 架构设计决策文档

Agent 需要时通过语义搜索检索相关内容

Agent A → Agent B → Agent C → Agent D

需求分析 Agent
    ↓ 输出：任务清单
代码生成 Agent
    ↓ 输出：代码文件
测试生成 Agent
    ↓ 输出：测试文件
安全扫描 Agent
    ↓ 输出：扫描报告

┌──→ Agent B ──┐
Agent A ─┤              ├─→ Agent D（合并结果）
         └──→ Agent C ──┘

生成的代码
    ├──→ 安全扫描 Agent（扫描漏洞）
    ├──→ 性能检查 Agent（扫描 N+1 查询）
    └──→ 规范检查 Agent（检查代码风格）
          ↓
    汇总报告 Agent（合并三份报告）

Agent A → [判断结果] ──成功──→ Agent B
                    └──失败──→ 修复 Agent → 重试 Agent A（最多 N 次）

async function codeGenerationWithRetry(task: string, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const code = await codeGenerationAgent(task);
    const testResult = await testRunnerAgent(code);

    if (testResult.passed) {
      return code;  // 测试通过，返回代码
    }

    // 测试失败，把错误信息传给修复 Agent，重试
    task = `修复以下代码的问题：\n${testResult.errors}\n原始代码：\n${code}`;
  }

  throw new Error(`代码生成失败，已重试 ${maxRetries} 次`);
}

Agent A → [需要确认] → 暂停，等待人工输入 → Agent B

// 非幂等（危险）：多次调用会创建多条记录
async createOrder(dto: CreateOrderDto) {
  return await this.prisma.order.create({ data: dto });
}

// 幂等（安全）：先查是否存在，存在则返回已有记录
async createOrderIdempotent(dto: CreateOrderDto, idempotencyKey: string) {
  const existing = await this.prisma.order.findUnique({
    where: { idempotencyKey },
  });
  if (existing) return existing;

  return await this.prisma.order.create({
    data: { ...dto, idempotencyKey },
  });
}

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
  delayMs = 1000,
): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;

      // 指数退避：第 1 次等 1 秒，第 2 次等 2 秒，第 3 次等 4 秒
      await new Promise(resolve => setTimeout(resolve, delayMs * Math.pow(2, attempt)));
    }
  }
  throw new Error('Max retries exceeded');
}

async function orchestrator(requirement: string) {
  this.logger.log(`[Orchestrator] 开始处理需求：${requirement}`);

  const tasks = await requirementAgent(requirement);
  this.logger.log(`[需求 Agent] 拆解出 ${tasks.length} 个任务`);

  for (const task of tasks) {
    this.logger.log(`[代码 Agent] 开始处理任务：${task.description}`);
    const code = await codeGenerationAgent(task);
    this.logger.log(`[代码 Agent] 任务完成，生成文件：${code.files.join(', ')}`);
  }
}

// src/agent-demo/pipeline.ts

interface Task {
  id: string;
  description: string;
  type: 'schema' | 'service' | 'controller' | 'test';
}

interface AgentResult {
  success: boolean;
  output: string;
  nextAction?: 'continue' | 'retry' | 'human_review';
  error?: string;
}

// Agent 1：需求分析
async function requirementAgent(rawRequirement: string): Promise<Task[]> {
  // 调用 LLM，把需求拆解成任务列表
  const prompt = `
    把以下需求拆解成具体的开发任务，每个任务类型是以下之一：schema、service、controller、test
    需求：${rawRequirement}
    输出格式：JSON 数组，每项包含 id、description、type
  `;
  // const result = await llm.invoke(prompt);
  // return JSON.parse(result);

  // 模拟输出
  return [
    { id: '1', description: '创建 Points Prisma Schema', type: 'schema' },
    { id: '2', description: '实现 PointsService，包含 addPoints 和 deductPoints', type: 'service' },
    { id: '3', description: '实现 PointsController，包含 Swagger 注解', type: 'controller' },
    { id: '4', description: '为 PointsService 生成单元测试', type: 'test' },
  ];
}

// Agent 2：代码生成
async function codeGenerationAgent(task: Task): Promise<AgentResult> {
  // 根据任务类型，生成对应的代码
  const prompt = `
    生成以下任务的 NestJS 代码：
    ${task.description}
    技术约束：Prisma ORM、TypeScript strict、返回 ResponseDto
  `;
  // const code = await llm.invoke(prompt);
  return { success: true, output: '// 生成的代码...', nextAction: 'continue' };
}

// Agent 3：测试执行和验证
async function testAgent(code: string): Promise<AgentResult> {
  // 实际运行测试命令
  // const result = await exec('npm test -- --passWithNoTests');
  // if (result.exitCode !== 0) {
  //   return { success: false, output: result.stderr, nextAction: 'retry', error: result.stderr };
  // }
  return { success: true, output: '所有测试通过', nextAction: 'continue' };
}

// Orchestrator：协调所有 Agent
async function orchestrator(requirement: string) {
  console.log('Step 1: 需求分析...');
  const tasks = await requirementAgent(requirement);

  console.log(`Step 2: 代码生成（共 ${tasks.length} 个任务）...`);
  const generatedCode: string[] = [];

  for (const task of tasks) {
    let result: AgentResult;
    let retries = 0;
    const MAX_RETRIES = 3;

    do {
      result = await codeGenerationAgent(task);

      if (!result.success && retries < MAX_RETRIES) {
        console.log(`任务 ${task.id} 失败，第 ${retries + 1} 次重试...`);
        retries++;
      }
    } while (!result.success && retries < MAX_RETRIES);

    if (!result.success) {
      console.error(`任务 ${task.id} 重试 ${MAX_RETRIES} 次后仍失败，需要人工介入`);
      // 触发人工干预节点
      break;
    }

    generatedCode.push(result.output);
  }

  console.log('Step 3: 运行测试验证...');
  const testResult = await testAgent(generatedCode.join('\n'));

  if (!testResult.success) {
    console.log('测试失败，代码需要修复...');
    // 触发修复循环
  }

  console.log('完成！所有步骤执行成功。');
  return { tasks, generatedCode, testResult };
}

// 使用示例
orchestrator('实现用户积分系统，支持积分发放、扣减、查询余额和查询历史');

mkdir -p src/agent-pipeline
touch src/agent-pipeline/pipeline.ts

左侧：Vibe Coding
人 → [描述] → AI → [结果] → 人 → [描述] → AI → [结果] → ...
（人在每一步都参与）

右侧：Agentic Engineering
人 → [高层目标] → Orchestrator → 需求 Agent → 代码 Agent → 测试 Agent
                                                              ↓
                      [有问题？] ← 修复 Agent ←─────────────┘
                          ↓否
                      [汇报结果] → 人
（人只在开始和结束参与）

interface Task {
  id: string;
  description: string;
  type: 'schema' | 'service' | 'controller' | 'test';
}

do {
  result = await codeGenerationAgent(task);
  retries++;
} while (!result.success && retries < MAX_RETRIES);

if (!result.success) {
  console.error(`任务 ${task.id} 需要人工介入`);
  // 触发人工干预节点
  break;
}

async function orchestrator(requirement: string) {
  // 1. 分解任务
  // 2. 调度各个 Agent
  // 3. 处理失败和重试
  // 4. 决定什么时候需要人工介入
}

你：帮我写一个创建用户的 API
AI：[给代码]
你：加一下参数校验
AI：[改代码]
你：再加一下重复邮箱的校验
AI：[再改]
...（重复 10 轮）

你：按照 @spec/user.md 实现用户模块，
    包括完整的参数校验、业务逻辑、单元测试，
    最后运行测试确认通过

AI：
  → 读取 spec/user.md
  → 分析项目结构（src/modules/）
  → 生成 DTOs
  → 生成 Service（含错误处理）
  → 生成 Controller
  → 生成单元测试
  → 执行 npm test
  → 发现 2 个测试失败
  → 定位问题、修复
  → 重新运行测试
  → 全部通过，返回结果

你：有一个 bug，用户列表页在搜索时偶尔会崩溃

AI：
  → 搜索代码库里的 user.service.ts
  → 读取 findAll 方法
  → 识别到问题：search 参数未做 SQL 特殊字符转义
  → 查看测试文件，确认没有覆盖这个场景
  → 修复代码
  → 补充测试用例
  → 执行测试验证
  → 报告完成

> 帮我实现用户搜索功能，写完后跑单元测试，
  如果测试失败自己分析原因并修复，直到全部通过

需求 Agent    → 读取 PRD，生成 spec.md
架构 Agent    → 读取 spec，设计系统结构、数据模型
开发 Agent    → 按架构文档实现代码
测试 Agent    → 读取实现，生成并执行测试
Review Agent  → 扫描代码，输出安全和质量报告

前端 Agent  ┐
后端 Agent  ┼→ 最终合并到主分支
测试 Agent  ┘

# 终端1：Claude Code 做后端
cd backend
claude "按照 @spec/user.md 实现用户模块"

# 终端2：Claude Code 做前端
cd frontend
claude "按照 @spec/user.md 实现用户管理页面，接口格式参考 spec 文档"

# 你：偶尔巡逻，解决卡住的问题，最后做集成验证