Dynamic Workflows

一个代理不够

当任务大到单次对话装不下的时候，怎么办？

四种方式对比

Subagents、Skills、Agent Teams、Workflows 各有分工

架构概览

用户会话、Workflow Runtime 和子代理的三层关系

脚本怎么来的

从你输入提示词到 Workflow 运行，中间发生了什么

你输入：ultracode: 审查 src/routes/ 下每个路由文件是否缺少认证检查

Claude Code：检测到 "ultracode" 关键字 → 高亮显示 → 弹出确认提示
┌─────────────────────────────────────────────────┐
│  Dynamic workflow requested for this turn       │
│  Esc to ignore                                   │
│                                                 │
│  Phases:                                        │
│    1. Scan — 发现所有路由文件                     │
│    2. Review — 每个文件一个代理并行审查            │
│    3. Verify — 对抗性验证每个发现                 │
│    4. Report — 汇总报告                          │
│                                                 │
│  ⚠️ Token usage will be high                    │
│                                                 │
│  [Yes, run it] [View raw script] [No]           │
└─────────────────────────────────────────────────┘

你选择 "View raw script" → Claude 把生成的 JS 脚本展示给你
你选择 "Yes, run it"  → Workflow Runtime 在后台接管执行

你输入：/workflows    # 随时查看进度
# 你的会话保持响应，可以继续做其他事

脚本结构

Claude 生成的脚本长什么样

// 1. 元数据块（必须是纯字面量，不能有变量或计算）
export const meta = {
  name: 'my-workflow',
  description: '做什么事',
  phases: [
    { title: 'Phase1', detail: '描述' },
    { title: 'Phase2', detail: '描述' },
  ],
};

// 2. 脚本主体
phase('Phase1');
const results = await parallel(items.map(item => () =>
  agent(`处理 ${item}`, { schema: MY_SCHEMA, phase: 'Phase1' })
));

phase('Phase2');
const final = await agent('综合所有结果', { phase: 'Phase2' });

return { final, count: results.length };

agent() 原语

派生一个子代理执行任务，返回结果

// 最简用法：返回代理的文本输出
const result = await agent('审查 src/auth.ts 的安全性');

// 带 schema：强制返回结构化 JSON（模型会自动重试直到匹配）
const bugs = await agent('找出这个文件里的 bug', {
  schema: {
    type: 'object',
    properties: {
      bugs: { type: 'array', items: {
        type: 'object',
        properties: {
          file: { type: 'string' },
          line: { type: 'number' },
          severity: { type: 'string', enum: ['high','medium','low'] },
        }
      }}
    }
  }
});

// 常用选项
await agent('审查代码', {
  label: 'review:auth',       // 进度视图中的显示名
  phase: 'Review',            // 分配到进度组
  isolation: 'worktree',      // 在独立 git worktree 中运行
  agentType: 'general-purpose' // 使用自定义子代理类型
});

并行原语

parallel() 是屏障，pipeline() 是流水线——默认用 pipeline

const all = await parallel([
  () => agent('搜索角度A'),
  () => agent('搜索角度B'),
  () => agent('搜索角度C'),
]);
// 这里拿到全部 3 个结果
const deduped = dedup(all);

const results = await pipeline(
  files,
  (file) => agent(`审查 ${file}`),
  (review) => agent(`验证 ${review.file}`)
);
// 更快，因为没有等待屏障

选择决策

什么时候用 parallel，什么时候用 pipeline

辅助原语

phase、log、workflow、budget、args

// 按预算控制深度
const bugs = [];
while (budget.total && budget.remaining() > 50000) {
  const result = await agent('Find bugs', { schema: BUGS_SCHEMA });
  bugs.push(...result.bugs);
  log(`${bugs.length} found, ${Math.round(budget.remaining()/1000)}k remaining`);
}

// 嵌套调用内置工作流
const report = await workflow('deep-research', 'Claude Code hooks 原理');

对抗性验证

让 N 个"怀疑者"代理力图反驳每个发现

// 对每个发现，派 3 个独立怀疑者
const VOTES = 3;
const REFUTATIONS_TO_KILL = 2;

const verified = await parallel(findings.map(f => () =>
  parallel(Array.from({ length: VOTES }, (_, i) => () =>
    agent(`Be SKEPTICAL. Try to REFUTE this claim:
      "${f.claim}"
      Source: ${f.source}
      Return refuted: true/false with evidence.`, {
      schema: VERDICT_SCHEMA
    })
  )).then(verdicts => {
    const valid = verdicts.filter(Boolean);
    const refuted = valid.filter(v => v.refuted).length;
    const survives = valid.length >= REFUTATIONS_TO_KILL
                     && refuted < REFUTATIONS_TO_KILL;
    return { ...f, survives, refutedVotes: refuted };
  })
));

const confirmed = verified.filter(f => f.survives);

循环与多视角

Loop-Until-Dry + Perspective-Diverse Verify

const seen = new Set();
const confirmed = [];
let dry = 0;

while (dry < 2) {  // 连续 2 轮没新发现就停
  const found = (await parallel(FINDERS.map(f => () =>
    agent(f.prompt, { phase: 'Find', schema: BUGS })
  ))).filter(Boolean).flatMap(r => r.bugs);

  const fresh = found.filter(b => !seen.has(key(b)));
  if (!fresh.length) { dry++; continue; }
  dry = 0;
  fresh.forEach(b => seen.add(key(b)));

  // 每个发现用 3 个不同视角独立评判
  const judged = await parallel(fresh.map(b => () =>
    parallel(['correctness','security','repro'].map(lens => () =>
      agent(`Judge "${b.desc}" via the ${lens} lens`, {
        phase: 'Verify', schema: VERDICT
      })
    )).then(vs => ({
      b,
      real: vs.filter(Boolean).filter(v => v.real).length >= 2
    }))
  ));
  confirmed.push(...judged.filter(v => v.real).map(v => v.b));
}

质量模式总结

四种模式可以根据任务自由组合

/deep-research

Claude Code 内置的深度研究工作流——也是最好的学习范例

研究脚本详解

/deep-research 的核心逻辑拆解

// 阶段1：分解问题
phase("Scope");
const scope = await agent(
  "Decompose this question into 5 search angles...\n" + QUESTION,
  { schema: SCOPE_SCHEMA }  // 强制返回结构化角度列表
);

// 阶段2+3：搜索 + 获取（pipeline，无屏障延迟）
const searchResults = await pipeline(
  scope.angles,
  (angle) => agent(SEARCH_PROMPT(angle), { schema: SEARCH_SCHEMA }),
  (searchResult) => {
    // URL 去重 + 预算控制
    const novel = dedupAndBudget(searchResult.results);
    return parallel(novel.map(source => () =>
      agent(FETCH_PROMPT(source), { schema: EXTRACT_SCHEMA })
    ));
  }
);

// 阶段4：3 投对抗性验证
phase("Verify");
const voted = await parallel(rankedClaims.map(claim => () =>
  parallel([0,1,2].map(v => () =>
    agent(VERIFY_PROMPT(claim, v), { schema: VERDICT_SCHEMA })
  )).then(verdicts => ({
    ...claim,
    survives: valid >= 2 && refuted < 2
  }))
));

// 阶段5：综合报告
phase("Synthesize");
const report = await agent("Synthesize...", { schema: REPORT_SCHEMA });

触发方式

三种方式让 Claude 写出并运行一个 Workflow

ultracode: 审查 src/routes/ 下
每个端点是否缺少认证检查

/effort ultracode

# 内置
/deep-research Claude Code hooks 原理

# 保存过的自定义
/vue-newsletter {"weekStart":"2026-06-04"}

保存与复用

一次写好、反复运行的 Workflow 才是真正的价值

# 查看运行中的工作流
/workflows

# 选择一个成功的运行，按 s 保存
# 保存位置选择：
  .claude/workflows/   ← 项目级（团队共享，随仓库分发）
  ~/.claude/workflows/ ← 个人级（所有项目可用，仅自己可见）

# 保存后像 slash command 一样调用
/my-code-review

# 传入参数
/triage-issues issues 1024, 1025, and 1030

# 同名时，项目级优先于个人级

实战：代码审查

多维度审查 + 对抗性验证的完整 Workflow

export const meta = {
  name: 'review-changes',
  description: 'Review changed files across dimensions, verify each finding',
  phases: [
    { title: 'Review', detail: '三个维度并行审查' },
    { title: 'Verify', detail: '对抗性验证每个发现' },
  ],
};

const DIMENSIONS = [
  { key: 'bugs',     prompt: 'Review for correctness bugs...' },
  { key: 'perf',     prompt: 'Review for performance issues...' },
  { key: 'security', prompt: 'Review for security vulnerabilities...' },
];

const results = await pipeline(
  DIMENSIONS,
  (d) => agent(d.prompt, {
    label: `review:${d.key}`,
    phase: 'Review',
    schema: FINDINGS_SCHEMA
  }),
  (review) => parallel(review.findings.map(f => () =>
    agent(`Adversarially verify: ${f.title}`, {
      label: `verify:${f.file}`,
      phase: 'Verify',
      schema: VERDICT_SCHEMA
    }).then(v => ({ ...f, verdict: v }))
  ))
);

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

运行管理

查看进度、暂停恢复、成本控制

# 查看所有运行
/workflows

# 在进度视图中可用的快捷键：
↑/↓        选择阶段或代理
Enter/→    展开查看详细内容
p          暂停或恢复运行
x          停止选中的代理或整个工作流
s          保存脚本为命令
Esc        返回上一层

运行约束

Workflow Runtime 的安全边界

关闭 Workflow

三种方式禁用 Dynamic Workflows

关闭后：ultracode 关键字不再触发、/deep-research 不可用、/effort ultracode 从菜单中移除。

排错指南

动手练习

让 Claude 为你的项目生成一个 Workflow

1. 在 Claude Code 中输入带 ultracode 关键字的审查请求
2. 选择 "View raw script" 查看生成的脚本
3. 运行 Workflow，用 /workflows 监控进度
4. 运行完成后按 s 保存为可复用的命令

参考答案

一个典型的审查 Workflow 运行过程

# 步骤 1：触发 Workflow
> ultracode: 审查 src/ 下所有文件，从正确性、安全性、性能
> 三个维度并行审查，每个发现经过独立验证

# 步骤 2：Claude 生成脚本，确认运行
Dynamic workflow requested for this turn · Alt+W to ignore

# 步骤 3：查看运行进度
/workflows
# 输出示例：
┌─ Review ────────── 3/3 agents ──── 45,230 tokens ──
│  review:bugs     ✅ 12 findings
│  review:perf     ✅ 8 findings
│  review:security ✅ 5 findings
├─ Verify ────────── 25/25 agents ─── 183,400 tokens ─
│  verify:auth.ts:42   2-1 ✓ survives
│  verify:api.ts:108   1-2 ✗ killed
│  ...
└─ Complete ─ 11 confirmed findings

# 步骤 4：保存成功运行
Press s → save as "code-review" → .claude/workflows/

# 下次直接调用：
/code-review

课程总回顾

十一章走完，从入门到大规模编排

延伸阅读