Workflows

这是什么

Workflows（特性 WORKFLOW_SCRIPTS）让千手大师用确定性 JavaScript 脚本编排多个子 agent。模型通过 Workflow 工具提交脚本，工具把它交给引擎在 后台执行并立即返回一个 runId，完成时以 task 通知回传返回值。

脚本里可使用一组固定的编排原语：

• agent() —— 派发一个子 agent，无 schema 返回文本，带 schema 返回校验后的对象；
• parallel() —— 并发跑一组 thunk，屏障语义，等全部完成；
• pipeline() —— 每个 item 独立链式过各 stage，阶段间无屏障（默认推荐）；
• phase() / log() —— 标记阶段与输出进度旁白；
• workflow() —— 内联运行一层子 workflow；
• args / budget —— 透传参数与读取 token 预算。

引擎位于独立包 packages/workflow-engine/ （@claude-code-best/workflow-engine，对核心层零运行时依赖）， 核心侧的薄适配层在 src/workflow/：负责装配 Workflow 工具、 解析命名脚本、驱动进度、持久化运行状态。

前置条件

安装启用

1. 确认 Workflow 特性已开启

   Build 产物默认包含 WORKFLOW_SCRIPTS。dev 模式可显式开启：

   Terminal 复制

   # dev 模式手动开启工作流脚本特性
   FEATURE_WORKFLOW_SCRIPTS=1 bun run dev

2. 建立命名 workflow（可选）

   在项目根目录创建 .claude/workflows/，放入脚本。文件即命令： review-changes.mjs 会生成 /review-changes。

   Terminal 复制

   mkdir -p .claude/workflows
   # 放入 review-changes.mjs（见「实战示例」），即可用 /review-changes 调用

3. 启动一个 workflow

   三种入口：内联 script、命名 name、文件 scriptPath。

   qsdashi 会话 复制

   # 模型侧调用 Workflow 工具（示例）
   Workflow({ scriptPath: ".claude/workflows/review-changes.mjs", args: ["src/a.ts"] })
   
   # 或使用命名脚本生成的斜杠命令
   /review-changes

4. 用 /workflows 观察进度

   面板打开后按 Tab 切 run、←/→ 切左右列、q 退出。

编排 API 与约束

脚本内可用的钩子（注入为函数形参，直接调用，不要 import）：

硬限（超出直接抛错，不静默截断）：

脚本执行模型与确定性约束：

目录与持久化：

常用命令与参数

Workflow 工具输入字段（模型侧发起 workflow 时使用）：

斜杠命令：

/workflows 面板键位：

实战示例

一个「发现 → 改写 → 验证」的迁移类 workflow：改写阶段用 isolation: 'worktree' 隔离并行写，验证阶段读取原 item 定位文件。

export const meta = {
  name: 'migrate-api',
  description: '发现 legacyFetch 调用点，逐个改写并验证',
  phases: [
    { title: 'Discover', detail: 'grep 调用点' },
    { title: 'Transform', detail: '每处一个 agent（worktree 隔离）' },
    { title: 'Verify', detail: '逐处验证改写' },
  ],
}

const SITES_SCHEMA = {
  type: 'object',
  properties: {
    sites: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          file: { type: 'string' },
          line: { type: 'number' },
        },
        required: ['file', 'line'],
      },
    },
  },
  required: ['sites'],
}

const VERDICT_SCHEMA = {
  type: 'object',
  properties: { ok: { type: 'boolean' } },
  required: ['ok'],
}

phase('Discover')
const found = await agent(
  '列出仓库中所有对 legacyFetch 的调用点（file + line）',
  { label: 'discover:sites', schema: SITES_SCHEMA }
)

// Discover 之后需要全部调用点才能 fan-out，故此处显式屏障后的 pipeline 逐项处理
const results = await pipeline(
  found ? found.sites : [],
  site => agent(`把 ${site.file}:${site.line} 的 legacyFetch 改写为新 API`, {
    label: `transform:${site.file}`,
    phase: 'Transform',
    isolation: 'worktree',
  }),
  (_patch, site) => agent(`验证 ${site.file} 的改写是否正确`, {
    label: `verify:${site.file}`,
    phase: 'Verify',
    schema: VERDICT_SCHEMA,
  })
)

const verified = results.filter(Boolean).filter(v => v.ok)
log(`已验证 ${verified.length} 处改写`)
return { verified }

迭代与 resume：脚本改动后，用同一路径加 resumeFromRunId 重新发起， 未改动前缀里的 agent() 会命中 journal 直接返回缓存，只重跑首个发散点之后的部分。

# 首次运行后，工具结果里会给出 runId
Workflow({ scriptPath: ".claude/workflows/migrate-api.mjs" })

# 改脚本后从该 run 重放
Workflow({
  scriptPath: ".claude/workflows/migrate-api.mjs",
  resumeFromRunId: "<runId>",
})

# 也可在 /workflows 面板中对选中的 run 按 r 续跑

用预算控制深度：当用户在 turn 里给出 token 目标（如 +500k）时， budget.total 有值，可据此动态扩缩 fan-out。

// 无预算目标时 total 为 null，勿裸写 while（会一路跑到 1000 agent 硬顶）
// 需要动态循环时始终以 budget.total 为守卫
const found = []
while (budget.total && budget.remaining() > 50000) {
  const r = await agent('继续寻找遗漏的调用点', { schema: SITES_SCHEMA })
  found.push(...(r ? r.sites : []))
  log(`已收集 ${found.length} 处`)
}

常见问题排错