WORKFLOW_SCRIPTS — 确定性多 agent 工作流编排

Feature Flag：FEATURE_WORKFLOW_SCRIPTS=1 引擎包：@claude-code-best/workflow-engine（确定性 JS 脚本编排，零核心层运行时依赖）集成层：src/workflow/

一、功能概述

WORKFLOW_SCRIPTS 让 Claude Code 用确定性 JavaScript 脚本编排多个子 agent：可分解/并行、多视角置信、规模超单上下文、可 resume/可审计。

编排原语：agent / parallel / pipeline / phase / log / workflow（见引擎包）。
确定性：脚本在受限沙箱内执行，禁用 Date.now() / Math.random() / 无参 new Date()，保证 journal 可重放。
深度后端：单一 claude-code AgentAdapter 接入当前会话体系（provider / model / agentType / 工具），workflow 内的 agent() 调用真实子 agent。
监控面板：/workflows 双栏实时面板（见 §六）。
编排手册：/ultracode 注入编排工作法（见 §七）。

历史说明：早期版本为 YAML/JSON DSL + 全 Stub 实现（WorkflowDetailDialog 等），已全量重写为引擎驱动的 JS 方案。

二、实现架构

   .claude/workflows/<name>.ts        Workflow 工具（name/script/scriptPath/args/resumeFromRunId）
            │                                       │
            ▼                                       ▼
   namedWorkflowCommands.ts              src/workflow/wiring.ts (createWorkflowToolCore)
   （/<name> 命令发现）                              │
                                                   ▼
                                      WorkflowService（门面：launch/kill/subscribe/listRuns/listNamed）
                                                   │
                                  ┌────────────────┼─────────────────┐
                                  ▼                ▼                 ▼
                          ports.ts            registry.ts        progress/
                       （端口聚合）      （AgentAdapterRegistry）  bus + store
                                  │                │
                                  ▼                ▼
                      hostHandle.ts        backends/claudeCodeBackend.ts
                     （不透明 host）       （深度读会话体系，跑真实 agent）
                                  │
                                  ▼
                  @claude-code-best/workflow-engine
                  （runWorkflow / hooks / journal / budget / 并发信号量）

2.1 模块清单

层	文件	职责
引擎	`packages/workflow-engine/src/`	确定性脚本沙箱 + hooks + journal + budget + 信号量；导出 `createWorkflowTool`
工具装配	`src/workflow/wiring.ts`	`createWorkflowToolCore()` —— 用 `WorkflowService.ports` 组装 `Workflow` 工具
服务门面	`src/workflow/service.ts`	`WorkflowService` 单例：`launch` / `kill` / `subscribe` / `listRuns` / `listNamed` / `getWorkflowService()`
端口	`src/workflow/ports.ts`	`createWorkflowPorts()` 聚合所有端口（agentRunner/registry/progress/task/journal/permission/logger/hostFactory）
后端注册	`src/workflow/registry.ts`	`buildRegistry()` 注册 `claude-code` 后端并设为默认
深度后端	`src/workflow/backends/claudeCodeBackend.ts`	AgentAdapter：按 `agentType`/`model` 解析会话体系，跑真实子 agent，结构化输出
Host 句柄	`src/workflow/hostHandle.ts`	`buildHostBundle()` 不透明包装 `toolUseContext`/`canUseTool`/`parentMessage`
进度总线	`src/workflow/progress/bus.ts`	基于 Set 的进度事件发射
进度状态	`src/workflow/progress/store.ts`	reducer：按 `agentId` 精确关联 `agent_done`（修并发竞态）
监控面板	`src/workflow/panel/*.tsx`	`/workflows` 双栏 UI（见 §六）
命名命令	`src/workflow/namedWorkflowCommands.ts`	扫描 `.claude/workflows/` 生成 `/<name>` 命令
权限请求	`src/workflow/WorkflowPermissionRequest.tsx`	workflow 启动权限 UI

2.2 注册点

位置	内容
`src/tools.ts:152-153,254`	`createWorkflowToolCore()` 动态加载并注册 `Workflow` 工具（feature-gated）
`src/commands.ts:95-97,392`	`/workflows` 命令（local-jsx，加载 `panelCall.js`）
`src/skills/bundled/ultracode.ts` + `index.ts`	`/ultracode` 知识 skill（`registerBundledSkill`）

三、编排原语

workflow 脚本内可用的钩子（语义详见引擎包 engine/hooks.ts）：

原语	语义
`agent(prompt, opts?)`	派发一个子 agent；返回最终文本，或（带 `opts.schema`）结构化对象。opts：`model` / `agentType` / `label` / `phase` / `schema`
`parallel([() => …])`	并发跑 thunk 数组，barrier（等全部完成）；单项抛错 → 该项 `null`，其余保留
`pipeline(items, s1, s2, …)`	每个 item 链式过各 stage；item 间无 barrier，stage 内顺序；单 item 某 stage 抛错 → 该 item `null`
`phase(title)`	标记阶段（面板按此分组展示）
`log(msg)`	进度日志（面板展示，无状态变更）
`workflow(name \| { scriptPath }, args?)`	嵌套一层子 workflow（仅允许一层）

硬限：单次 parallel/pipeline ≤ MAX_ITEMS_PER_CALL（4096）；单 workflow 总 agent ≤ MAX_TOTAL_AGENTS（1000）；并发 cap 默认 = DEFAULT_MAX_CONCURRENCY（3），可经 Workflow 工具的 maxConcurrency 入参覆盖，绝对上限 MAX_CONCURRENCY_CAP（16）。

四、编写 workflow

脚本置于 .claude/workflows/<name>.js|.mjs（也接受 .ts，但引擎不转译 TS，含类型注解会报语法错——推荐 .js/.mjs），自动成为 /<name> 命令。

// .claude/workflows/review-changes.js
export const meta = {
  name: 'review-changes',
  description: '按维度审查改动并对抗式验证',
  phases: [{ title: 'Review' }, { title: 'Verify' }],
}

const DIMENSIONS = [
  { key: 'bugs', prompt: '找正确性 bug' },
  { key: 'perf', prompt: '找性能问题' },
]

const results = await pipeline(
  DIMENSIONS,
  d => agent(d.prompt, { label: `review:${d.key}`, phase: 'Review' }),
  review => parallel(
    (review.findings || []).map(f => () =>
      agent(`对抗式验证：${f.title}`, { phase: 'Verify' })
    )
  )
)
return results.flat().filter(Boolean)

脚本执行约束（引擎执行模型，违反直接报错）：脚本是 new AsyncFunction 的函数体，不是 ESM 模块：

禁 import：agent/parallel/pipeline/phase/log/workflow 与 args/budget 是注入的形参，直接用。
禁 TS 语法：不要类型注解（x: number）、interface、enum、as、泛型。引擎不转译，即便文件是 .ts 也会原样报语法错。
只允许一处 export const meta = {...}（引擎正则提取剥离）；不要 export 其他、不要 export default。
顶层 return 返回结果。

确定性约束（违反则 resume 失效）：

禁 Date.now() / Math.random() / 无参 new Date()（沙箱强制抛错）。需时间戳/随机种子经 args 传入。
export const meta = { ... } 必须是纯字面量（无变量、函数调用、模板插值）——加载期求值，否则抛 ScriptError。

五、Workflow 工具

模型通过 Workflow 工具启动 workflow（input schema 见引擎包 tool/schema.ts）：

字段	说明
`script`	内联脚本字符串
`name`	命名 workflow 名（对应 `.claude/workflows/<name>`）
`scriptPath`	脚本文件路径
`args`	透传给脚本的 `args`（任意 JSON 值）
`resumeFromRunId`	从既有 runId 重放（已完成 `agent()` 秒回，发散点后现场重跑）

六、监控面板：`/workflows`

/workflows 打开三区焦点面板（local-jsx，全屏）：

顶部 tabs：每个 run 一个 tab（状态圆点 + workflow 名 + #runId短码）；同名脚本多次跑会多个 tab。
左 phase 侧栏：All + 合并 meta 声明的 phase（未启动 ○ pending 灰）与实际 phase（● running / ✓ done）；选中即决定右栏筛选。
右 agent 列表：按选中 phase 过滤；状态色 + 行尾文字（running / object / text / dead）。

键位：Tab/Shift+Tab 切 run · ←/→ 切左右焦点列（phases ↔ agents）· ↑/↓ 列内移动 · r resume · x kill · n 新建提示 · q/Esc 退出。视觉：无内框，左右一条竖线分隔；聚焦列标题橙粗；选中/光标行铺橙底（backgroundColor），文字色不变。进度按引擎 agentId 精确关联 agent_done（解决并发 LIFO 竞态）。pending phase 来自 run_started 事件携带的 meta.phases，store 落地 declaredPhases，面板 mergePhases 合并。useSyncExternalStore 订阅 WorkflowService，稳定快照，无变更不重渲染。

七、`/ultracode` skill

/ultracode（src/skills/bundled/ultracode.ts）注入多 agent workflow 编排工作法：何时用 / 何时不用、编排原语速查、质量模式库（adversarial-verify / judge-panel / loop-until-dry / multi-modal-sweep / completeness-critic）、确定性约束、后端路由、resume/budget、文件与命令。 纯知识 prompt skill：零运行时副作用，不改主循环、不切换行为开关。调用即把手册注入上下文。

八、resume / journal / budget

journal：每次 run 记录到 .claude/workflow-runs/<runId>/journal.jsonl。resumeFromRunId 重放 journal，已完成 agent() 秒回缓存结果。
budget：budget.total 为 token 硬顶（默认 null = 无限）；budget.spent() / budget.remaining() 读实时消耗；耗尽后再发 agent() 抛错。
并发：引擎 Semaphore 默认许可 3（DEFAULT_MAX_CONCURRENCY），可经 Workflow 工具的 maxConcurrency 入参 per-run 覆盖（钳到 [1, MAX_CONCURRENCY_CAP=16]）。
错误：脚本语法/meta 错 → parseScript 即时返错（不进后台）；agent 抛错 → kind:'dead' → null，workflow 继续（parallel/pipeline 容错）；WorkflowAbortedError → killed。

九、文件索引

文件	职责
`src/workflow/wiring.ts`	`Workflow` 工具装配（`createWorkflowToolCore`）
`src/workflow/service.ts`	`WorkflowService` 门面
`src/workflow/ports.ts`	端口聚合（`createWorkflowPorts`）
`src/workflow/registry.ts`	`AgentAdapterRegistry` + 默认后端
`src/workflow/backends/claudeCodeBackend.ts`	深度后端 AgentAdapter
`src/workflow/hostHandle.ts`	不透明 host 句柄（`buildHostBundle`）
`src/workflow/progress/bus.ts`	进度事件总线
`src/workflow/progress/store.ts`	进度 reducer（`agentId` 关联）
`src/workflow/panel/*.tsx`	`/workflows` 双栏面板
`src/workflow/namedWorkflowCommands.ts`	`/<name>` 命令发现
`src/workflow/WorkflowPermissionRequest.tsx`	启动权限 UI
`src/skills/bundled/ultracode.ts`	`/ultracode` 知识 skill
`src/tools.ts:152-153,254`	工具注册
`src/commands.ts:95-97,392`	`/workflows` 命令注册
`packages/workflow-engine/`	引擎包（hooks / journal / budget / 并发）

开始

对话是如何运转的

工具：AI 的双手

上下文工程

多 Agent 协作

可扩展性

安全与权限

揭秘：隐藏功能与内部机制

隐藏功能详解

基础设施与依赖

Workflow scripts

WORKFLOW_SCRIPTS — 确定性多 agent 工作流编排

一、功能概述

二、实现架构

2.1 模块清单

2.2 注册点

三、编排原语

四、编写 workflow

五、Workflow 工具

六、监控面板：`/workflows`

七、`/ultracode` skill

八、resume / journal / budget

九、文件索引

​WORKFLOW_SCRIPTS — 确定性多 agent 工作流编排

​一、功能概述

​二、实现架构

​2.1 模块清单

​2.2 注册点

​三、编排原语

​四、编写 workflow

​五、Workflow 工具

​六、监控面板：/workflows

​七、/ultracode skill

​八、resume / journal / budget

​九、文件索引

WORKFLOW_SCRIPTS — 确定性多 agent 工作流编排

一、功能概述

二、实现架构

2.1 模块清单

2.2 注册点

三、编排原语

四、编写 workflow

五、Workflow 工具

六、监控面板：`/workflows`

七、`/ultracode` skill

八、resume / journal / budget

九、文件索引