Claude Code Workflow 多 Agent 编排深度实战

graph TB
    subgraph "Dynamic Workflow 架构"
        A[主会话 Claude] --> B[编写 Workflow 脚本]
        B --> C{脚本引擎执行}
        C --> D[子 Agent 1: 安全审计]
        C --> E[子 Agent 2: 性能审计]
        C --> F[子 Agent 3: 可维护性审计]
        D --> G[结果汇总]
        E --> G
        F --> G
        G --> H[结构化输出]
    end

    style A fill:#f9f,stroke:#333
    style C fill:#bbf,stroke:#333
    style G fill:#bfb,stroke:#333

// 脚本必须以 meta 声明开始
export const meta = {
  name: 'my-workflow',
  description: '描述这个 Workflow 做什么',
  phases: [
    { title: '扫描', detail: '扫描代码库' },
    { title: '验证', detail: '对抗性验证' }
  ]
}

// 脚本主体
phase('扫描')
const results = await parallel([
  () => agent('审计安全性', { label: '安全', phase: '扫描' }),
  () => agent('审计性能', { label: '性能', phase: '扫描' })
])

.claude/
├── workflows/                    # 持久化 Workflow 脚本
│   ├── my-audit-workflow.js      # 自定义脚本
│   └── saved-workflows/          # 可通过 name 调用的已保存 Workflow
└── sessions/
    └── <session-id>/
        └── workflow-*.js         # 自动保存的脚本副本

> Use a workflow to review my codebase for security issues, 
  performance problems, and code quality

> /ultracode Do a comprehensive code review of this repo

export const meta = {
  name: 'code-review',
  description: 'Comprehensive code review across multiple dimensions',
  phases: [
    { title: 'Review', detail: 'Review code across dimensions' },
    { title: 'Verify', detail: 'Adversarially verify findings' }
  ]
}

const DIMENSIONS = [
  { key: 'security', prompt: 'Review codebase for security vulnerabilities...' },
  { key: 'perf', prompt: 'Review codebase for performance issues...' },
  { key: 'quality', prompt: 'Review codebase for code quality issues...' }
]

const results = await pipeline(
  DIMENSIONS,
  d => agent(d.prompt, {
    label: `review:${d.key}`,
    phase: 'Review',
    schema: {
      type: 'object',
      properties: {
        findings: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              title: { type: 'string' },
              file: { type: 'string' },
              severity: { type: 'string' },
              description: { type: 'string' }
            }
          }
        }
      }
    }
  }),
  review => parallel(
    review.findings.map(f => () =>
      agent(`Verify this finding: ${f.title} in ${f.file}`, {
        label: `verify:${f.file}`,
        phase: 'Verify'
      })
    )
  )
)

const confirmed = results.flat().filter(Boolean)
  .filter(r => r.verdict?.isReal)
return { confirmed }

▸ Code Review Workflow
  ▸ Review (3 agents)
    ● review:security — running...
    ● review:perf — running...
    ● review:quality — running...
  ▸ Verify (pending)

// 基础用法 — 返回文本
const result = await agent('分析 src/auth.ts 的安全性')

// 带结构化输出 — 返回 JSON 对象
const findings = await agent('分析 src/auth.ts 的安全性', {
  schema: {
    type: 'object',
    properties: {
      vulnerabilities: {
        type: 'array',
        items: { type: 'string' }
      },
      riskLevel: { type: 'string' }
    }
  }
})

// 完整参数
const result = await agent('你的提示词', {
  label: 'auth-review',        // 显示标签
  phase: 'Security',           // 所属阶段
  schema: { /* JSON Schema */ }, // 强制结构化输出
  model: 'sonnet',             // 模型覆盖（慎用）
  isolation: 'worktree',       // 在独立 git worktree 中运行
  agentType: 'Explore'         // 使用特定 Agent 类型
})

const FILES = ['auth.ts', 'user.ts', 'payment.ts']

const results = await pipeline(
  FILES,
  // 阶段 1：扫描
  (file, originalItem, index) => agent(`扫描 ${file} 的安全问题`, {
    label: `scan:${file}`,
    phase: 'Scan'
  }),
  // 阶段 2：验证
  (scanResult, originalItem, index) => agent(
    `验证发现：${scanResult.summary}`,
    { label: `verify:${originalItem}`, phase: 'Verify' }
  ),
  // 阶段 3：生成修复建议
  (verifyResult, originalItem, index) => agent(
    `为 ${originalItem} 生成修复方案`,
    { label: `fix:${originalItem}`, phase: 'Fix' }
  )
)

gantt
    title Pipeline 执行时间线（非阻塞）
    dateFormat X
    axisFormat %s秒

    section auth.ts
    扫描       :a1, 0, 5
    验证       :a2, 5, 8
    修复       :a3, 8, 12

    section user.ts
    扫描       :b1, 1, 6
    验证       :b2, 6, 9
    修复       :b3, 9, 13

    section payment.ts
    扫描       :c1, 2, 7
    验证       :c2, 7, 10
    修复       :c3, 10, 14

// 场景：需要所有维度审计结果后才能去重
const allFindings = await parallel([
  () => agent('审计安全性', { schema: FINDINGS_SCHEMA }),
  () => agent('审计性能', { schema: FINDINGS_SCHEMA }),
  () => agent('审计可维护性', { schema: FINDINGS_SCHEMA })
])

// 去重（需要所有结果到齐）
const deduped = deduplicate(
  allFindings.filter(Boolean).flatMap(r => r.findings)
)

// 然后再验证
const verified = await parallel(
  deduped.map(f => () => agent(`验证: ${f.title}`, { schema: VERDICT_SCHEMA }))
)

phase('扫描')  // 后续 agent() 调用归入此阶段
log(`已扫描 ${scanned}/${total} 个文件`)  // 进度消息

phase('验证')
log(`发现 ${findings.length} 个待验证问题`)

phase('修复')
log(`已确认 ${confirmed.length} 个真实问题`)

export const meta = {
  name: 'adversarial-code-review',
  description: 'Adversarially verified code review',
  phases: [
    { title: 'Find' },
    { title: 'Verify' }
  ]
}

const FINDINGS_SCHEMA = {
  type: 'object',
  properties: {
    findings: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          title: { type: 'string' },
          file: { type: 'string' },
          line: { type: 'number' },
          description: { type: 'string' }
        }
      }
    }
  }
}

const VERDICT_SCHEMA = {
  type: 'object',
  properties: {
    refuted: { type: 'boolean' },
    reason: { type: 'string' }
  }
}

phase('Find')
const result = await agent(
  'Find all security vulnerabilities in the codebase',
  { schema: FINDINGS_SCHEMA }
)

phase('Verify')
const verified = await parallel(
  result.findings.map(f => () =>
    parallel([1, 2, 3].map(i => () =>
      agent(
        `Try to REFUTE this finding: "${f.title}" at ${f.file}:${f.line}. ` +
        `Description: ${f.description}. ` +
        `Default to refuted=true if uncertain.`,
        { label: `judge:${f.file}:${i}`, phase: 'Verify', schema: VERDICT_SCHEMA }
      )
    ))
    .then(votes => ({
      ...f,
      survived: votes.filter(Boolean).filter(v => !v.refuted).length >= 2
    }))
  )
)

const confirmed = verified.filter(v => v.survived)
log(`${confirmed.length}/${result.findings.length} findings survived adversarial verification`)
return { confirmed }

export const meta = {
  name: 'architecture-design',
  description: 'Multi-perspective architecture design with judge panel',
  phases: [
    { title: 'Design' },
    { title: 'Judge' },
    { title: 'Synthesize' }
  ]
}

const APPROACHES = [
  { lens: 'MVP-first', prompt: 'Design the simplest architecture that works...' },
  { lens: 'Scalability-first', prompt: 'Design for 100x scale from day one...' },
  { lens: 'Developer-experience', prompt: 'Design for maximum developer productivity...' }
]

phase('Design')
const designs = await parallel(
  APPROACHES.map(a => () =>
    agent(a.prompt, { label: `design:${a.lens}`, phase: 'Design' })
  )
)

phase('Judge')
const scores = await parallel(
  designs.map((d, i) => () =>
    agent(`Score this architecture design (1-10) on: scalability, simplicity, 
           maintainability, cost. Design:\n${d}`, {
      label: `judge:${APPROACHES[i].lens}`,
      phase: 'Judge',
      schema: {
        type: 'object',
        properties: {
          total: { type: 'number' },
          scalability: { type: 'number' },
          simplicity: { type: 'number' },
          maintainability: { type: 'number' },
          cost: { type: 'number' },
          strengths: { type: 'array', items: { type: 'string' } },
          weaknesses: { type: 'array', items: { type: 'string' } }
        }
      }
    })
  )
)

phase('Synthesize')
const winnerIdx = scores
  .filter(Boolean)
  .reduce((best, s, i) => s.total > scores[best].total ? i : best, 0)

const synthesis = await agent(
  `The winning approach is "${APPROACHES[winnerIdx].lens}" with score ${scores[winnerIdx].total}.
   Here are all designs:\n${designs.join('\n---\n')}
   Here are all scores:\n${JSON.stringify(scores)}
   Synthesize the final architecture: take the winning design as the base, 
   but graft in the best ideas from the other approaches.`,
  { label: 'synthesize', phase: 'Synthesize' }
)

return { winner: APPROACHES[winnerIdx].lens, synthesis }

export const meta = {
  name: 'exhaustive-bug-finder',
  description: 'Find bugs until the well runs dry',
  phases: [
    { title: 'Find' },
    { title: 'Verify' }
  ]
}

const seen = new Set()
const confirmed = []
let dry = 0
const MAX_DRY = 2  // 连续 2 轮无新发现则停止

while (dry < MAX_DRY) {
  phase('Find')
  const found = (await parallel([
    () => agent('Find correctness bugs', { phase: 'Find', schema: BUGS_SCHEMA }),
    () => agent('Find security bugs', { phase: 'Find', schema: BUGS_SCHEMA }),
    () => agent('Find edge case failures', { phase: 'Find', schema: BUGS_SCHEMA })
  ])).filter(Boolean).flatMap(r => r.bugs)

  const fresh = found.filter(b => !seen.has(`${b.file}:${b.line}:${b.title}`))

  if (!fresh.length) {
    dry++
    log(`No new findings (dry ${dry}/${MAX_DRY})`)
    continue
  }

  dry = 0
  fresh.forEach(b => seen.add(`${b.file}:${b.line}:${b.title}`))
  log(`${fresh.length} new findings (total seen: ${seen.size})`)

  phase('Verify')
  const judged = await parallel(
    fresh.map(b => () =>
      agent(`Is this a real, reproducible bug? "${b.title}" at ${b.file}:${b.line}`, {
        label: `verify:${b.file}`,
        phase: 'Verify',
        schema: { type: 'object', properties: { real: { type: 'boolean' }, reason: { type: 'string' } } }
      })
    )
  )

  confirmed.push(...judged.filter(Boolean).filter(v => v.real))
  log(`${confirmed.length} confirmed bugs so far`)
}

log(`Done! ${confirmed.length} confirmed bugs from ${seen.size} total findings`)
return { confirmed, totalSeen: seen.size }

export const meta = {
  name: 'budget-bounded-audit',
  description: 'Audit within token budget',
  phases: [{ title: 'Audit' }, { title: 'Verify' }]
}

const bugs = []

while (budget.total && budget.remaining() > 50000) {
  phase('Audit')
  const result = await agent('Find bugs in this codebase', {
    schema: BUGS_SCHEMA,
    phase: 'Audit'
  })

  bugs.push(...result.bugs)
  log(`${bugs.length} bugs found, ${Math.round(budget.remaining() / 1000)}k tokens remaining`)

  if (bugs.length >= 50) break  // 上限保护
}

return { bugs, tokensUsed: budget.spent() }

export const meta = {
  name: 'multi-modal-sweep',
  description: 'Sweep codebase from multiple angles',
  phases: [{ title: 'Sweep' }, { title: 'Merge' }]
}

phase('Sweep')
const sweeps = await parallel([
  () => agent('Find all API endpoints that lack authentication checks', { phase: 'Sweep' }),
  () => agent('Find all database queries vulnerable to SQL injection', { phase: 'Sweep' }),
  () => agent('Find all user inputs that are not properly sanitized', { phase: 'Sweep' }),
  () => agent('Find all places where secrets might be logged or exposed', { phase: 'Sweep' })
])

phase('Merge')
const allFindings = sweeps.filter(Boolean).flatMap(r => {
  try { return JSON.parse(r).findings || [] } catch { return [] }
})
// ... 后续去重和验证

// ... 前面的发现和验证逻辑 ...

phase('Completeness Check')
const critic = await agent(
  `You are a completeness critic. We just did a ${meta.name} workflow.
   We found ${confirmed.length} issues across these dimensions: ${DIMENSIONS.map(d => d.key).join(', ')}.

   What did we MISS? Consider:
   1. Dimensions we didn't check
   2. Files we might have skipped
   3. Claim types we didn't verify
   4. Edge cases unique to this codebase

   Be specific and actionable.`,
  { label: 'completeness-critic', phase: 'Completeness Check' }
)

return { confirmed, gaps: critic }

export const meta = {
  name: 'fullstack-adversarial-audit',
  description: 'Adversarial multi-dimensional code audit for full-stack applications',
  phases: [
    { title: 'Scan', detail: 'Scan codebase across 5 dimensions' },
    { title: 'Dedup', detail: 'Deduplicate findings across dimensions' },
    { title: 'Verify', detail: '3-judge adversarial verification' },
    { title: 'Report', detail: 'Generate final report' }
  ]
}

// Schema 定义
const FINDINGS = {
  type: 'object',
  properties: {
    findings: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          id: { type: 'string' },
          title: { type: 'string' },
          file: { type: 'string' },
          line: { type: 'number' },
          severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] },
          category: { type: 'string' },
          description: { type: 'string' },
          recommendation: { type: 'string' }
        },
        required: ['id', 'title', 'file', 'severity', 'description']
      }
    }
  }
}

const VERDICT = {
  type: 'object',
  properties: {
    isReal: { type: 'boolean' },
    confidence: { type: 'number' },
    reason: { type: 'string' }
  }
}

// 阶段 1：5 维度扫描
phase('Scan')
const dimensions = [
  { key: 'security', prompt: 'Scan for security vulnerabilities: injection, XSS, CSRF, auth bypass, secrets in code, insecure dependencies' },
  { key: 'performance', prompt: 'Scan for performance issues: N+1 queries, memory leaks, unoptimized loops, missing indexes, large bundle size' },
  { key: 'reliability', prompt: 'Scan for reliability issues: unhandled errors, race conditions, missing retries, data loss scenarios' },
  { key: 'accessibility', prompt: 'Scan for accessibility issues: missing ARIA labels, keyboard navigation, color contrast, screen reader support' },
  { key: 'maintainability', prompt: 'Scan for maintainability issues: code duplication, high coupling, missing tests, unclear naming' }
]

const scanResults = await parallel(
  dimensions.map(d => () =>
    agent(d.prompt, {
      label: `scan:${d.key}`,
      phase: 'Scan',
      schema: FINDINGS
    })
  )
)

// 阶段 2：跨维度去重
phase('Dedup')
const allFindings = scanResults
  .filter(Boolean)
  .flatMap(r => r.findings)

log(`Total raw findings: ${allFindings.length}`)

// 基于文件+行号+类别的简单去重
const seen = new Set()
const deduped = allFindings.filter(f => {
  const key = `${f.file}:${f.line}:${f.category}`
  if (seen.has(key)) return false
  seen.add(key)
  return true
})

log(`After dedup: ${deduped.length} unique findings`)

// 阶段 3：对抗性验证（每个发现 3 个评委）
phase('Verify')
const verified = await pipeline(
  deduped,
  // 每个发现被 3 个独立评委审查
  finding => parallel([1, 2, 3].map(i => () =>
    agent(
      `You are judge #${i}. Try to REFUTE this finding:
       Title: ${finding.title}
       File: ${finding.file}:${finding.line}
       Severity: ${finding.severity}
       Description: ${finding.description}

       Is this a REAL issue? Default to isReal=false if uncertain.
       Consider: Is the file path correct? Is the severity justified? Is this a false positive?`,
      {
        label: `judge:${finding.id}:${i}`,
        phase: 'Verify',
        schema: VERDICT
      }
    )
  )).then(votes => ({
    ...finding,
    votes: votes.filter(Boolean),
    confirmed: votes.filter(Boolean).filter(v => v.isReal).length >= 2
  }))
)

const confirmed = verified.filter(v => v.confirmed)
const rejected = verified.filter(v => !v.confirmed)
log(`Confirmed: ${confirmed.length}, Rejected: ${rejected.length}`)

// 阶段 4：生成报告
phase('Report')
const criticalCount = confirmed.filter(f => f.severity === 'critical').length
const highCount = confirmed.filter(f => f.severity === 'high').length

log(`🔴 Critical: ${criticalCount} | 🟠 High: ${highCount} | Total: ${confirmed.length}`)

return {
  summary: {
    total: confirmed.length,
    critical: criticalCount,
    high: highCount,
    medium: confirmed.filter(f => f.severity === 'medium').length,
    low: confirmed.filter(f => f.severity === 'low').length
  },
  findings: confirmed,
  rejected: rejected.length,
  rawTotal: allFindings.length
}

> Use a workflow to run a full adversarial code audit 
  across security, performance, reliability, accessibility, 
  and maintainability dimensions

> /ultracode Run the fullstack-adversarial-audit workflow

▸ fullstack-adversarial-audit
  ▸ Scan (5 agents) ✓
    ● scan:security — 23 findings
    ● scan:performance — 15 findings
    ● scan:reliability — 12 findings
    ● scan:accessibility — 8 findings
    ● scan:maintainability — 19 findings
  ▸ Dedup ✓ — 77 raw → 62 unique
  ▸ Verify (62 findings × 3 judges) ✓
    ● Confirmed: 41 | Rejected: 21
  ▸ Report ✓
    🔴 Critical: 3 | 🟠 High: 8 | Total: 41

// 方法 1：通过返回的 runId 恢复
const { runId } = await Workflow({ script: myScript })

// 如果中途中断，使用 runId 恢复
await Workflow({ 
  scriptPath: savedScriptPath, 
  resumeFromRunId: runId 
})

// ✅ 好的 schema：字段清晰，有约束
const GOOD_SCHEMA = {
  type: 'object',
  properties: {
    findings: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          title: { type: 'string' },
          severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] },
          file: { type: 'string' }
        },
        required: ['title', 'severity', 'file']
      }
    },
    summary: { type: 'string' }
  },
  required: ['findings']
}

// ❌ 差的 schema：过于宽泛
const BAD_SCHEMA = {
  type: 'object',
  properties: {
    data: { type: 'string' }  // 一个大字符串，失去了结构化优势
  }
}

const results = await parallel(
  files.map(f => () =>
    agent(`Refactor ${f} to use the new API`, {
      isolation: 'worktree',
      label: `migrate:${f}`
    })
  )
)

// 调用已保存的 Workflow
const auditResult = await workflow('security-audit')

// 或通过脚本路径调用
const report = await workflow({ 
  scriptPath: './.claude/workflows/generate-report.js' 
}, { findings: auditResult.findings })

// 根据预算动态调整 Agent 数量
const FLEET = budget.total ? Math.floor(budget.total / 100000) : 5

const results = await parallel(
  Array.from({ length: FLEET }, (_, i) => () =>
    agent(`Find bugs in section ${i + 1} of the codebase`, {
      schema: BUGS_SCHEMA
    })
  )
)

> /ultracode on

flowchart LR
    A[用户输入任务] --> B{Ultracode 开启?}
    B -->|是| C[自动生成 Workflow 脚本]
    B -->|否| D[单 Agent 处理]
    C --> E[多阶段并行执行]
    E --> F[对抗性验证]
    F --> G[综合输出]
    D --> G

    style B fill:#ff9,stroke:#333
    style C fill:#bbf,stroke:#333
    style F fill:#bfb,stroke:#333

# 在另一个终端查看运行中的 Workflow
/workflows

# 查看特定 Agent 的详细日志
/tasks

graph TB
    subgraph "Claude Code Workflow 系统"
        User[用户提示词] --> Trigger{触发判断}
        Trigger -->|关键词/ultracode| ScriptGen[Claude 生成 JS 脚本]
        Trigger -->|常规任务| SingleAgent[单 Agent 处理]

        ScriptGen --> Engine[脚本引擎]
        Engine --> Pipeline[pipeline 流水线]
        Engine --> Barrier[parallel 屏障]
        Engine --> Loop[loop-until-dry]

        Pipeline --> SA1[子 Agent 1]
        Pipeline --> SA2[子 Agent 2]
        Pipeline --> SA3[子 Agent 3]

        Barrier --> SB1[子 Agent A]
        Barrier --> SB2[子 Agent B]
        Barrier --> SB3[子 Agent C]

        SA1 & SA2 & SA3 --> Merge[结果汇总]
        SB1 & SB2 & SB3 --> Merge

        Merge --> Output[结构化输出]

        Budget[Budget 控制器] -.-> Engine
        Cache[结果缓存] -.-> Engine
        Resume[断点续跑] -.-> Engine
    end

    style Trigger fill:#ff9,stroke:#333
    style Engine fill:#bbf,stroke:#333
    style Merge fill:#bfb,stroke:#333
    style Output fill:#f9f,stroke:#333