feat(workflow): add workflow engine, /workflows panel, /ultracode skill

将 feat/sdk-backend 分支中 workflow 相关的 20 个 commit 压缩为单 commit： - 工作流引擎核心：phase / agent / parallel / pipeline 编排原语（packages/workflow-engine/） - /workflows 面板：三区焦点布局（顶部 run tabs + 左侧 phase 侧栏 + 右侧 agent 列表） - /ultracode skill：多 agent workflow 编排入口 - 进度存储 / journal / notification 系统 - WorkflowService 生命周期管理 + SentryErrorBoundary - 脚本沙箱：禁用 dynamic import()、JSON args 防御性归一化 - journal 与 named-workflow 路径统一在 projectRoot - 错误处理：parallel/pipeline hooks 错误日志、failure routing、semaphore abort - workflow 工具升级为 core 工具 + PascalCase 命名 Co-Authored-By: glm-5.1 <zai-org@claude-code-best.win>
2026-06-18 06:15:51 +00:00 · 2026-06-13 20:07:18 +08:00
parent 91cffe16e2
commit d236880bc3
106 changed files with 16127 additions and 834 deletions
--- a/docs/features/workflow-scripts.md
+++ b/docs/features/workflow-scripts.md
@@ -1,102 +1,183 @@
-# WORKFLOW_SCRIPTS — 工作流自动化
+# WORKFLOW_SCRIPTS — 确定性多 agent 工作流编排

-> Feature Flag: `FEATURE_WORKFLOW_SCRIPTS=1`
-> 实现状态：全部 Stub（7 个文件），布线完整
-> 引用数：10
+> Feature Flag：`FEATURE_WORKFLOW_SCRIPTS=1`
+> 引擎包：[`@claude-code-best/workflow-engine`](../../packages/workflow-engine/)（确定性 JS 脚本编排，零核心层运行时依赖）
+> 集成层：[`src/workflow/`](../../src/workflow/)

 ## 一、功能概述

-WORKFLOW_SCRIPTS 实现基于文件的多步自动化工作流。用户可以定义 YAML/JSON 格式的工作流描述文件，系统将其解析为可执行的多 agent 步骤序列。提供 `/workflows` 命令管理和触发工作流。
+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 方案。

 ## 二、实现架构

-### 2.1 模块状态
-
-| 模块 | 文件 | 状态 |
-|------|------|------|
-| WorkflowTool | `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts` | **部分实现** — tool schema + 渲染完整，call 返回运行时缺失提示 |
-| Workflow 权限 | `packages/builtin-tools/src/tools/WorkflowTool/WorkflowPermissionRequest.tsx` | **部分实现** — 权限请求组件 |
-| 常量 | `packages/builtin-tools/src/tools/WorkflowTool/constants.ts` | **实现** — 工具名 + 目录名 + 文件扩展名常量 |
-| 命令创建 | `packages/builtin-tools/src/tools/WorkflowTool/createWorkflowCommand.ts` | **实现** — 扫描 .claude/workflows/ 目录创建 Command 对象 |
-| 捆绑工作流 | `packages/builtin-tools/src/tools/WorkflowTool/bundled/index.ts` | **实现** — 内置工作流初始化 |
-| 本地工作流任务 | `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` | **Stub** — 类型 + 空操作 |
-| UI 任务组件 | `src/components/tasks/src/tasks/LocalWorkflowTask/` | **Stub** — 空导出 |
-| 详情对话框 | `src/components/tasks/WorkflowDetailDialog.ts` | **Stub** — 返回 null |
-| 任务注册 | `src/tasks.ts` | **布线** — 动态加载 |
-| 工具注册 | `src/tools.ts` | **布线** — 动态加载 + bundled 工作流初始化 (行 131-134,235) |
-| 命令注册 | `src/commands.ts` | **布线** — `/workflows` 命令 (行 93-95,395,460) |
-
-### 2.2 预期数据流
-
 ```
-用户定义工作流（YAML/JSON 文件）
-         │
-         ▼
-/workflows 命令发现工作流文件
-         │
-         ▼
-createWorkflowCommand() 解析为 Command 对象 [需要实现]
-         │
-         ▼
-WorkflowTool 执行工作流 [需要实现]
-         │
-         ├── 步骤 1: Agent({ task: "..." })
-         ├── 步骤 2: Agent({ task: "..." })
-         └── 步骤 N: Agent({ task: "..." })
-         │
-         ▼
-LocalWorkflowTask 协调步骤执行 [需要实现]
-         │
-         ▼
-WorkflowDetailDialog 显示进度 [需要实现]
+   .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.3 预期工作流 DSL
+### 2.1 模块清单

-```
-# workflow.yaml（预期格式，需要设计）
-name: "代码审查工作流"
-steps:
-  - name: "静态分析"
-    agent: { type: "general-purpose", prompt: "运行 lint 和类型检查" }
-  - name: "测试"
-    agent: { type: "general-purpose", prompt: "运行测试套件" }
-  - name: "综合报告"
-    agent: { type: "general-purpose", prompt: "综合分析结果写报告" }
+| 层 | 文件 | 职责 |
+|----|------|------|
+| 引擎 | `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 = `min(16, cores - 2)`。
+
+## 四、编写 workflow
+
+脚本置于 `.claude/workflows/<name>.js|.mjs`（也接受 `.ts`，但**引擎不转译 TS**，含类型注解会报语法错——推荐 `.js`/`.mjs`），自动成为 `/<name>` 命令。
+
+```js
+// .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)
 ```

-## 三、需要补全的内容
+**脚本执行约束**（引擎执行模型，违反直接报错）：

-| 优先级 | 模块 | 工作量 | 说明 |
-|--------|------|--------|------|
-| 1 | `WorkflowTool.ts` call 方法 | 中 | 实际工作流执行逻辑（当前返回运行时缺失提示） |
-| 2 | `LocalWorkflowTask.ts` | 大 | 步骤协调、kill/skip/retry |
-| 3 | `WorkflowDetailDialog.ts` | 中 | 进度详情 UI |
+脚本是 `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` 返回结果**。

-1. **基于文件的 DSL**：工作流定义为文件（YAML/JSON），版本控制友好
-2. **多 Agent 步骤**：每个步骤是独立的 agent 任务，支持并行/串行
-3. **内置工作流**：`bundled/` 目录提供开箱即用的常用工作流
-4. **/workflows 命令**：统一的发现和触发入口
+**确定性约束**（违反则 resume 失效）：
+- 禁 `Date.now()` / `Math.random()` / 无参 `new Date()`（沙箱强制抛错）。需时间戳/随机种子经 `args` 传入。
+- `export const meta = { ... }` 必须是**纯字面量**（无变量、函数调用、模板插值）——加载期求值，否则抛 `ScriptError`。

-## 五、使用方式
+## 五、Workflow 工具

-```bash
-# 启用 feature（需要补全后才能真正使用）
-FEATURE_WORKFLOW_SCRIPTS=1 bun run dev
-```
+模型通过 `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`（`min(16, cores - 2)`）限制同时运行的 agent 数。
+- **错误**：脚本语法/meta 错 → `parseScript` 即时返错（不进后台）；agent 抛错 → `kind:'dead'` → `null`，workflow 继续（`parallel`/`pipeline` 容错）；`WorkflowAbortedError` → `killed`。
+
+## 九、文件索引

 | 文件 | 职责 |
 |------|------|
-| `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts` | 工具定义（部分实现） |
-| `packages/builtin-tools/src/tools/WorkflowTool/WorkflowPermissionRequest.tsx` | 权限请求组件 |
-| `packages/builtin-tools/src/tools/WorkflowTool/constants.ts` | 常量定义 |
-| `packages/builtin-tools/src/tools/WorkflowTool/createWorkflowCommand.ts` | 命令创建（已实现） |
-| `packages/builtin-tools/src/tools/WorkflowTool/bundled/index.ts` | 内置工作流初始化 |
-| `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` | 任务协调（stub） |
-| `src/components/tasks/WorkflowDetailDialog.ts` | 详情对话框（stub） |
-| `src/tools.ts:131-134,235` | 工具注册 |
-| `src/commands.ts:93-95,395,460` | 命令注册 |
+| `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 / 并发） |