mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-19 06:45:50 +00:00
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>
This commit is contained in:
claude-code-best
231
docs/superpowers/specs/2026-06-12-workflow-engine-design.md
Normal file
231
docs/superpowers/specs/2026-06-12-workflow-engine-design.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# Workflow Engine — 重建设计
|
||||
|
||||
- 日期：2026-06-12
|
||||
- 状态：已通过 brainstorming，待 writing-plans
|
||||
- 范围：把被掏空的「清单推进」版 WorkflowTool 重建为**完整忠实的确定性 JS 脚本编排引擎**，并**独立成包**，解除与核心层的深度依赖。
|
||||
|
||||
## 1. 背景与现状
|
||||
|
||||
当前 `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts` 是个被阉割的版本：把 `.claude/workflows/` 里的 `.md`/`.yaml` 解析成清单，靠模型手动调用 `advance` 推进，**没有任何子 agent 编排能力**。
|
||||
|
||||
真正的 Workflow 能力是一个**确定性 JS 脚本编排引擎**：后台执行脚本，提供 `agent()`/`parallel()`/`pipeline()`/`phase()`/`log()` 钩子，真正 spawn 子 agent，支持 schema 校验、并发上限、journaling/resume、token budget、进度流。
|
||||
|
||||
### 可复用的现有基础设施
|
||||
|
||||
- `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts`：完整的后台任务生命周期（register/complete/fail/kill/skip/retry/orphan 清理）。**完好，复用**。
|
||||
- `packages/builtin-tools/src/tools/AgentTool/runAgent.ts`：子 agent 执行核心（async generator，接收 `agentDefinition`+`promptMessages`+`toolUseContext`+`canUseTool`，运行完整 query 循环）。**作为 `agent()` 钩子后端**。
|
||||
- `assembleToolPool`（`src/tools.ts`）：构建子 agent 工具池。
|
||||
- `finalizeAgentTool` / `extractTextContent`（`agentToolUtils.ts`）：抽取 agent 最终消息 + usage。
|
||||
- `WorkflowPermissionRequest.tsx`：权限 UI（核心侧 React，复用）。
|
||||
- `tools.ts` 已用 `WORKFLOW_SCRIPTS` feature flag 接好注册位；`constants/tools.ts` 的 `CORE_TOOLS` 在 flag 开启时含 `workflow`。
|
||||
|
||||
## 2. 关键决策（brainstorming 结论）
|
||||
|
||||
1. **范围**：完整忠实引擎——全部钩子 + schema 结构化输出 + 并发上限（16/1000/4096）+ journaling/resume + token budget + worktree 隔离 + named-workflow 加载 + 进度流到 `/workflows`。
|
||||
2. **包边界**：**严格端口适配（依赖倒置）**。`packages/workflow-engine/` 零 `src/*` / `builtin-tools` 运行时导入；只声明端口接口；核心侧提供一个 adapter 模块实现这些接口；`tools.ts` 装配时注入。
|
||||
3. **文件模型**：`.claude/workflows/<name>.ts|.js|.mjs` 脚本文件 → 命名 workflow（`Workflow` 工具 `name` 参数解析到它）+ 生成 `/<name>` 斜杠命令；`/workflows` 变为实时进度查看器。**删除** 现有 `.md`/`.yaml` 清单逻辑。
|
||||
4. **执行路径**：**async 函数包装 + 信号量 + 注入端口**（方案 A）。进程内 async 模型，与 `runAgent` 的 async generator 天然契合，端口可 mock 测试。不用 `vm` 沙箱或 worker 进程。
|
||||
|
||||
## 3. 架构与依赖方向
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ packages/workflow-engine/ ← 新包，零 src/* 运行时导入 │
|
||||
│ 声明端口（接口），持有引擎/钩子/并发/journal/budget/schema │
|
||||
│ + 自包含的 WorkflowTool 描述符（zod schema/desc/prompt） │
|
||||
└──────────────▲──────────────────────────▲───────────────────┘
|
||||
│ 实现（implements） │ 注入（DI）
|
||||
┌──────────────┴──────────────────────────┴───────────────────┐
|
||||
│ src/workflow/ ← 核心侧薄层 │
|
||||
│ adapter.ts: 用 runAgent/assembleToolPool/LocalWorkflowTask │
|
||||
│ /AppState 实现端口 │
|
||||
│ wiring.ts: createWorkflowTool(adapter) → 适配为 Tool │
|
||||
│ 注册到 tools.ts（WORKFLOW_SCRIPTS flag 之后） │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
包**不认识** `buildTool` / `toolUseContext` / `runAgent` / `Message` 类型。仅通过端口接口与不透明 host 句柄对话。
|
||||
|
||||
### 端口契约（包内 `ports.ts`）
|
||||
|
||||
| 端口 | 职责 | 核心侧 adapter 实现 |
|
||||
|---|---|---|
|
||||
| `AgentRunner` | `agent()` 后端：`runAgentToResult(params, hostHandle) → AgentRunResult` | 委托 `runAgent` + `assembleToolPool`；schema 时注入 StructuredOutput 工具；`finalizeAgentTool` 抽取最终消息 + usage |
|
||||
| `ProgressEmitter` | `emit(event)` 推进度事件 | 写 `LocalWorkflowTaskState.progress` + `rootSetAppState` |
|
||||
| `TaskRegistrar` | 后台任务生命周期 + 读 `pendingAgentAction` | 复用 `LocalWorkflowTask` API |
|
||||
| `JournalStore` | journal 读写（按 runId） | 文件 fs（`.claude/workflow-runs/<runId>/journal.jsonl`），走端口便于 mock |
|
||||
| `PermissionGate` | `agent()` 前置权限/取消检查 | abort signal + `pendingAgentAction` |
|
||||
| `Logger` | 调试日志 + 遥测 | `logForDebugging` / `logEvent` |
|
||||
|
||||
**不透明 host 句柄**：`HostHandle = { readonly __workflowHost: unique symbol }`。核心侧每次工具调用构造一个句柄（内含 `toolUseContext`/`canUseTool`/`agentId` 等），包内绝不检视，只透传给 `AgentRunner`；adapter 把它 cast 回核心上下文。包对核心类型零依赖的唯一缝隙，且是不透明的。
|
||||
|
||||
### 包结构
|
||||
|
||||
```
|
||||
packages/workflow-engine/
|
||||
package.json @claude-code-best/workflow-engine (workspace:*)
|
||||
tsconfig.json
|
||||
src/
|
||||
index.ts 公共导出
|
||||
ports.ts 端口接口 + HostHandle
|
||||
types.ts 纯类型（WorkflowInput/Run/JournalEntry/ProgressEvent/AgentRunParams…）
|
||||
tool/
|
||||
WorkflowTool.ts createWorkflowTool(ports) → 自包含描述符
|
||||
schema.ts 输入 schema（script/name/scriptPath/args/resumeFromRunId/desc/title）
|
||||
constants.ts WORKFLOW_TOOL_NAME 等
|
||||
engine/
|
||||
runWorkflow.ts 引擎入口：校验/包装/执行/journal/resume
|
||||
context.ts 执行上下文（端口/信号量/budget/journal/计数器/host）
|
||||
hooks.ts agent/parallel/pipeline/phase/log/workflow 实现
|
||||
script.ts meta 字面量提取 + async 包装 + 沙箱 shim
|
||||
concurrency.ts Semaphore + 上限（16 / 1000 总 / 4096 每次调用）
|
||||
journal.ts hash + 读/写 journal
|
||||
budget.ts budget 累加器（total/spent/remaining）
|
||||
structuredOutput.ts JSON Schema → 结果校验（纯函数）
|
||||
namedWorkflows.ts name → .claude/workflows/<name>.ts|js|mjs 解析（仅 fs）
|
||||
constants.ts 目录/上限常量
|
||||
progress/events.ts ProgressEvent 类型 + emit 委托
|
||||
__tests__/ …
|
||||
```
|
||||
|
||||
核心侧薄层：`src/workflow/adapter.ts` + `src/workflow/wiring.ts`；`packages/builtin-tools` 从新包 re-export 描述符。
|
||||
|
||||
## 4. 引擎内部
|
||||
|
||||
### 4.1 钩子语义
|
||||
|
||||
| 钩子 | 语义 | 失败行为 |
|
||||
|---|---|---|
|
||||
| `agent(prompt, opts?)` | 取信号量 → 查 journal（命中即返回缓存）→ 调 `AgentRunner` → 写 journal → 返回 | 终态 API 错耗尽重试 → `null`（不抛） |
|
||||
| `parallel(thunks)` | **屏障**：`Promise.all` 所有 thunk（每个内部各自过信号量）；wall-clock = 最慢项 | 单项抛错/agent 错 → 该项 `null`；调用本身永不 reject |
|
||||
| `pipeline(items, …stages)` | **无屏障**：每项跑 `stage1→stage2→…` 异步链，多链并发；stage 回调收 `(prevResult, originalItem, index)` | 某 stage 抛错 → 该项 `null`、跳过后续 stage |
|
||||
| `phase(title)` | 开启新阶段，后续 agent/log 归入该组直到下次 `phase()` | — |
|
||||
| `log(message)` | 向用户发一行旁白进度 | — |
|
||||
| `workflow(nameOrRef, args?)` | 内联跑子 workflow，返回其返回值；共享并发/计数/budget；`/workflows` 显示为 `▸ name` 组 | 子 workflow 内再嵌套 → 抛错（仅一层） |
|
||||
|
||||
`agent` 的 `opts`：`label`、`phase`（显式分组）、`schema`（JSON Schema）、`model`、`isolation:'worktree'`、`agentType`（自定义子 agent 类型）、`allowedTools`。
|
||||
|
||||
- 无 schema 返回 `string`；有 schema 返回校验对象；用户 skip / agent 终态死亡 → 返回 `null`。
|
||||
|
||||
### 4.2 并发与上限（`concurrency.ts`）
|
||||
|
||||
- `Semaphore` 许可数 = `min(16, cpuCores - 2)`；`agent()` 取 1。
|
||||
- 单个 workflow 生命周期**总 agent 数 ≤ 1000** → 超出抛错。
|
||||
- 单次 `parallel`/`pipeline` 调用 **items ≤ 4096** → 超出抛错（显式错误，不静默截断）。
|
||||
|
||||
### 4.3 Journal / Resume（`journal.ts`）
|
||||
|
||||
- journal = 按**执行顺序**的 `{ key, result }` 列表，存 `.claude/workflow-runs/<runId>/journal.jsonl`。
|
||||
- `key` = `hash(prompt + canonical(opts 去掉 label/phase 等纯展示字段))`。
|
||||
- 命中：`agent()` 先算 key，与 journal 下一项 key 比对 → **匹配则返回缓存并前进**，不匹配则丢弃后续 journal、现场重跑。
|
||||
- 因 JS 去掉 `Date.now`/`random` 后确定，执行顺序确定 → 自然得到「最长未变前缀命中、首个发散点之后全重跑」。
|
||||
- `resumeFromRunId`：载入该 run 的 journal 重放。脚本源码 hash 一致 → 100% 命中；脚本改动 → 全重跑。脚本 hash 存入 run 记录。
|
||||
|
||||
### 4.4 Budget（`budget.ts`）
|
||||
|
||||
- `budget.total`：来自用户 `+500k` 式 turn 级 token 指令，由 **host/turn 上下文注入**（adapter 从 turn 的 token 指令读取，经 `HostHandle` 传入），**不是** 工具 input 参数。无指令则 `null`。
|
||||
- `budget.spent()`：本 turn 所有 agent 输出 token 之和（`AgentRunResult.usage`，adapter 从 subagent usage 填）。
|
||||
- `budget.remaining()`：`max(0, total - spent)`，无 total 则 `Infinity`。
|
||||
- **硬上限**：`spent()` 达 `total` 后，`agent()` 抛错。预算是主循环与 workflow 共享池。
|
||||
|
||||
### 4.7 AgentRunResult 类型（`types.ts`）
|
||||
|
||||
`AgentRunner.runAgentToResult` 的返回，包内明确定义为联合类型：
|
||||
|
||||
```ts
|
||||
type AgentRunResult =
|
||||
| { kind: 'ok'; output: string | object; usage: { outputTokens: number } }
|
||||
| { kind: 'skipped' } // 用户 skip → agent() 返回 null
|
||||
| { kind: 'dead' } // 终态 API 错耗尽重试 → agent() 返回 null
|
||||
```
|
||||
|
||||
`output` 为 `string`（无 schema）或已校验对象（有 schema）。`agent()` 据此映射：`ok`→返回 output，`skipped`/`dead`→返回 `null`。
|
||||
|
||||
### 4.5 脚本包装与沙箱（`script.ts`）
|
||||
|
||||
1. 提取 `export const meta = { … }`——**必须是纯字面量**（无变量/插值/展开），解析为对象；缺失或非字面量 → 抛错。
|
||||
2. 剥离 `export const meta` 语句。
|
||||
3. 剩余 body（含顶层 `return`）包进 `async function(agent, parallel, pipeline, phase, log, workflow, args, budget, Date, Math){ <body> }`。
|
||||
4. 以**抛异常的 shim** 传入 `Date`（`now()`/无参 `new Date()` 抛）、`Math`（`random()` 抛）——靠函数参数 shadow 全局，使裸 `Date.now()` 命中 shim。这是确定性保障，非密码学级沙箱（与真实引擎意图一致：阻断 resume 破坏性的非确定性）。
|
||||
5. meta 的 `phases` 可用于进度预声明（可选）。
|
||||
|
||||
### 4.6 进度事件（`progress/events.ts`）
|
||||
|
||||
`ProgressEmitter.emit(event)` 类型：`run_started`、`phase_started/done`、`agent_started/done{label,phase,result摘要}`、`log`、`run_done{returnValue/status}`。adapter 写入 task 进度结构 + AppState，`/workflows` 视图消费。
|
||||
|
||||
## 5. 错误处理
|
||||
|
||||
| 场景 | 行为 |
|
||||
|---|---|
|
||||
| 脚本无 `meta` / `meta` 非字面量 / 语法错 | 引擎抛错 → task `failed` → 通知带错误信息 |
|
||||
| `Date.now`/`Math.random`/`new Date()` | shim 抛 → 冒泡为脚本错误 → task failed |
|
||||
| `agent()` 终态 API 错（重试耗尽） | 返回 `null`，**不杀** workflow |
|
||||
| `parallel`/`pipeline` 单项抛错 | 该项 `null`，workflow 继续 |
|
||||
| budget 耗尽 | `agent()` 抛错（脚本可 try/catch） |
|
||||
| 并发/1000/4096 上限 | 抛错 |
|
||||
| kill（abort） | signal 传播；`agent()` 检查 signal；workflow 停；task `killed`；通知 partial |
|
||||
| 工具调用层（`call`）脚本非法 | 直接返回错误给模型（不进后台） |
|
||||
|
||||
## 6. 测试策略
|
||||
|
||||
包内全量单测，**无需真实 LLM**（mock 端口——解耦的核心收益）：
|
||||
|
||||
- `engine.test.ts`：mock `AgentRunner`（按 prompt 返回预设结果）端到端跑脚本，断言返回值 + 进度事件序列。
|
||||
- `hooks.test.ts`：parallel 单项错→null、pipeline 无屏障顺序、agent schema 校验、skip/dead→null。
|
||||
- `concurrency.test.ts`：信号量限并发、1000/4096 上限抛错。
|
||||
- `journal.test.ts`：hash 稳定、resume 命中前缀、脚本变更全重跑、中途发散重跑尾部。
|
||||
- `budget.test.ts`：spent 累加、触顶抛错。
|
||||
- `script.test.ts`：meta 字面量提取、非字面量/语法错、shim 抛。
|
||||
- `structuredOutput.test.ts`、`namedWorkflows.test.ts`。
|
||||
|
||||
核心侧最小冒烟：adapter 用 `runAgent` 真接线的重 mock 测试；wiring 注册测试。重量级逻辑都在包内。可选：`tests/integration/` 加一个 workflow tool-chain 集成测试（feature-gated）。
|
||||
|
||||
## 7. 核心侧实现
|
||||
|
||||
### 7.1 adapter（`src/workflow/adapter.ts`）
|
||||
|
||||
`createWorkflowAdapter()` 返回端口实现：
|
||||
|
||||
- **AgentRunner.runAgentToResult(params, hostHandle)**：cast 句柄→`{toolUseContext, canUseTool, assistantMessage}`；按 `params.agentType` 从 registry 解析 agentDefinition（缺省=通用 workflow 子 agent）；`assembleToolPool`；有 schema→注入 StructuredOutput 工具+系统指令；调 `runAgent` 收消息→`finalizeAgentTool` 抽 text+usage；schema→解析校验返回对象；处理 `pendingAgentAction`(skip)→`null`、终态死亡→`null`；返回 `{kind:'ok', text/object, usage}`。
|
||||
- **ProgressEmitter**：写 `LocalWorkflowTaskState.progress` + `rootSetAppState`。
|
||||
- **TaskRegistrar**：复用现有 `registerLocalWorkflowTask/complete/fail/kill` + 读 `pendingAgentAction`。
|
||||
- **JournalStore / Logger / PermissionGate**：fs / `logForDebugging`+`logEvent` / abort+pendingAction。
|
||||
|
||||
### 7.2 wiring（`src/workflow/wiring.ts`）
|
||||
|
||||
- `createWorkflowTool()`：建 adapter → 调包的 `createWorkflowTool(adapter)` 得描述符 → 包成 `buildTool` 兼容 `Tool` 返回。
|
||||
- `tools.ts`：`const WorkflowTool = feature('WORKFLOW_SCRIPTS') ? require('./workflow/wiring.js').createWorkflowTool() : null`（替换现有清单版）。
|
||||
|
||||
`call` 流程：校验脚本（inline/file/named 解析）→ meta 校验失败直接返错给模型 → 持久化脚本 + 算 hash → resume 则载入 run+journal → 注册后台 task → **立即返回 `{runId, scriptPath}`** → 脱离执行引擎、流进度 → 完成时 complete + 通知（返回值/错误）。
|
||||
|
||||
## 8. 现有文件迁移
|
||||
|
||||
| 文件 | 处理 |
|
||||
|---|---|
|
||||
| `builtin-tools/.../WorkflowTool/WorkflowTool.ts`（清单版） | 删除，逻辑移入新包 |
|
||||
| `constants.ts`（WORKFLOW_TOOL_NAME） | 移入包 `tool/constants.ts`，core 侧 re-export |
|
||||
| `WorkflowPermissionRequest.tsx`（React UI） | 移到 `src/workflow/`（依赖 src 权限组件，属核心侧） |
|
||||
| `createWorkflowCommand.ts`（.md/.yaml 扫描） | 改为扫 `.ts/.js/.mjs` → 生成 `/<name>` 命令，调用时以脚本启动引擎 |
|
||||
| `bundled/index.ts`（no-op） | 保留为包的 bundled-workflow 扩展点 |
|
||||
| `src/utils/workflowRuns.ts`（清单记录） | 重写为 run+journal 模型（或并入包 JournalStore） |
|
||||
| `src/commands/workflows/index.ts` | 改为**实时进度查看器**，复用 `WorkflowDetailDialog.tsx` |
|
||||
| `src/tasks.ts` LocalWorkflowTask 门控 | 保持不变 |
|
||||
| `constants/tools.ts` CORE_TOOLS 含 `workflow` | 保持 |
|
||||
|
||||
## 9. 工作分解（writing-plans 将细化）
|
||||
|
||||
1. 新建包 `packages/workflow-engine/`（package.json/tsconfig/类型/端口/常量）。
|
||||
2. 引擎核心：script 包装、concurrency、journal、budget、structuredOutput、namedWorkflows。
|
||||
3. 钩子实现 + runWorkflow 编排 + 进度事件。
|
||||
4. 自包含工具描述符（schema/desc/prompt/result 映射）。
|
||||
5. 包内全量单测。
|
||||
6. 核心侧 adapter + wiring + 句柄构造。
|
||||
7. 迁移现有文件、改 `/workflows` 为进度查看器、改 named-workflow 命令。
|
||||
8. `bun run precheck` 零错误；手动 dev 冒烟。
|
||||
|
||||
## 10. 非目标 / 风险
|
||||
|
||||
- **非密码学沙箱**：函数参数 shadow 全局 `Date`/`Math`，`globalThis.Date` 仍可达。可接受——目标是阻断 resume 破坏性的非确定性，不是隔离恶意代码。若未来需强隔离再上 `vm`/worker（方案 B/C）。
|
||||
- **resume 正确性依赖确定性执行**：用户脚本若绕过 shim 用 `globalThis.Date` 制造非确定性，resume 可能命中错缓存。属可接受的边界，文档提示。
|
||||
- **预算共享语义**：`budget.spent()` 与主循环的 token 计数共享，需 adapter 正确上报 subagent usage；若 provider 不报 usage 则 budget 降级为 `Infinity`。
|
||||
- **StructuredOutput 工具**：核心侧需存在/实现一个按 JSON Schema 强制结构化输出的子 agent 工具（注入 + 解析）。若当前无现成实现，wiring 阶段补一个最小版本。
|
||||
200
docs/superpowers/specs/2026-06-13-workflow-panel-redesign.md
Normal file
200
docs/superpowers/specs/2026-06-13-workflow-panel-redesign.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# `/workflows` 面板重设计：顶 tab + 左 phase 侧栏 + 右 agent 列表
|
||||
|
||||
> 状态：草案（待用户 review → writing-plans 产出实施计划）
|
||||
> 日期：2026-06-13
|
||||
> 关联：上一期整体设计 `docs/superpowers/specs/2026-06-13-workflow-tui-ultracode-design.md`（其 §9 双栏面板已实现，本 spec 取代该 §9 的面板部分）
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景与现状
|
||||
|
||||
上一期整体设计已落地：`WorkflowService` 门面、`claude-code` AgentAdapter、进度 bus+store、引擎 `agentId` 关联、`/ultracode` skill 全部实现完成。`/workflows` 面板按旧 spec §9 实现为**双栏**：
|
||||
|
||||
- `src/workflow/panel/WorkflowsPanel.tsx`：左栏 `WorkflowList`（扁平 run 列表）+ 右栏 `WorkflowDetail`（phase 横条 + 扁平 agent 列表）。
|
||||
- 键位 `j/k` 在左栏选 run，选中即聚焦、右栏随之切换。
|
||||
|
||||
**问题**：监控「单个 run 内多 phase / 多 agent」时，左右是「run 列表 vs 单 run 详情」——切换 run 与查看 agent 共用一对键位；phase 仅一行横条，无法按 phase 筛选 agent；多个 run 间切换要上下翻列表。
|
||||
|
||||
本 spec 把面板**原地重写**为三区焦点模型：**顶部 run tab + 左 phase 筛选侧栏 + 右 agent 列表**，贴合「聚焦一个 run → 按 phase 收窄 → 看 agent 状态」的实际监控动线。
|
||||
|
||||
## 2. 目标与非目标
|
||||
|
||||
**目标**
|
||||
|
||||
1. 顶 tab 按 **run**（同名脚本多次跑会多个 tab，标签附 runId 短码消歧如 `review-changes#a3f`）。
|
||||
2. 左 phase 侧栏：合并 `meta` 声明 phase（pending `○`）与 store phase（running `●` / done `✓`）+ 一个固定 `All` 项；选中即决定右栏筛选。
|
||||
3. 右 agent 列表：按选中 phase 过滤（`All` 则全显）；状态用颜色 + 文字标记（`object` / `text` / `dead`）。
|
||||
4. 焦点轮转键位：`Tab`/`Shift+Tab` 切 run、`←/→` 切 phases↔agents、`↑/↓` 列内移动、`x` kill / `r` resume / `q`/`Esc` quit。
|
||||
5. 视觉极简：无内框，左右栏中间**一条竖线**；选中/光标行用**底色条**（`backgroundColor`，非反白）；聚焦列标题橙粗、非聚焦灰。
|
||||
6. 显示 **pending phase**（meta 声明但未启动）。
|
||||
|
||||
**非目标**
|
||||
|
||||
- 不改引擎包（`run_started` 已携带 `meta.phases`，见 §3）。
|
||||
- 不动 `service`/`registry`/`backends`/`ports`/`wiring`/Workflow 工具/`/ultracode`。
|
||||
- 不做 per-agent 操作 UI（仅 run 级 `kill`/`resume`）。
|
||||
- 不改 `BackgroundTasksDialog`（Shift+Down）跳转协议。
|
||||
- 不做 agent 输出详情抽屉（留未来）。
|
||||
|
||||
## 3. 关键发现：零引擎改动
|
||||
|
||||
`ProgressEvent.run_started` **已携带** `meta: WorkflowMeta | null`（`packages/workflow-engine/src/types.ts:60-66`，emit 点 `engine/runWorkflow.ts:72-77`），且 `WorkflowMeta.phases` 已是 `Array<{ title: string; detail?: string }>`（`types.ts:22-27`）。
|
||||
|
||||
→ pending phase 所需数据全在事件流里。面板只需让 store 在 `run_started` 时落地 `declaredPhases`，再与 store 的 `run.phases`（running/done）合并即可。**不触碰引擎包**。
|
||||
|
||||
## 4. 数据模型变更（`src/workflow/progress/store.ts`）
|
||||
|
||||
- `RunProgress` 新增字段：
|
||||
|
||||
```ts
|
||||
declaredPhases: string[] // 来自 run_started.meta.phases[].title；无 meta → []
|
||||
```
|
||||
|
||||
- reducer `run_started` 分支补一行（当前第 74-77 行只用 `event.workflowName`，忽略 `event.meta`）：
|
||||
|
||||
```ts
|
||||
case 'run_started':
|
||||
p.workflowName = event.workflowName
|
||||
p.status = 'running'
|
||||
p.declaredPhases = event.meta?.phases?.map(ph => ph.title) ?? []
|
||||
break
|
||||
```
|
||||
|
||||
- `ensure()` 初始化 `declaredPhases: []`。
|
||||
- 其余 reducer 分支、`AgentProgress`、快照排序逻辑不变。
|
||||
|
||||
**测试**（`progress/store.test.ts` 或对应测试文件）：
|
||||
- `run_started` 带 `meta.phases` → `declaredPhases` 落地且顺序保留。
|
||||
- `run_started` 的 `meta` 为 `null` → `declaredPhases === []`。
|
||||
- 已有 `agentId` 关联、phase 切换、`run_done` 终态用例保持绿。
|
||||
|
||||
## 5. 面板布局（定稿 ASCII）
|
||||
|
||||
焦点在 PHASES（默认进入态）：
|
||||
|
||||
```
|
||||
╭─ Workflows ──────────────────────────── 2 running · 3 done ─╮
|
||||
│ │
|
||||
│ ● review-changes ✓ find-bugs ● migrate-auth │
|
||||
│ ═════════════════ ← Tab / Shift+Tab 切 │
|
||||
│ │
|
||||
│ PHASES │ AGENTS · Review │
|
||||
│ │ │
|
||||
│ ✓ Find 3/3 │ ● review:bugs running │
|
||||
│ ▓▶● Review 2/5▓ │ ● review:perf running │
|
||||
│ ○ Verify 0/2 │ ✓ review:sec object │
|
||||
│ │ ✗ review:api dead │
|
||||
│ All 10 │ ✓ review:auth text │
|
||||
│ │ │
|
||||
│ Tab 切 run · ←/→ 切焦点 · ↑/↓ 移动 · x kill · q quit │
|
||||
╰─────────────────────────────────────────────────────────────╯
|
||||
```
|
||||
|
||||
按 `→` 焦点到 AGENTS（`PHASES` 标题变灰、`AGENTS` 变橙、光标行铺底色）：
|
||||
|
||||
```
|
||||
phases (灰) │ AGENTS · Review (橙)
|
||||
│
|
||||
✓ Find 3/3 │ ● review:bugs running
|
||||
● Review 2/5 │ ▓● review:perf running ▓ ← 光标行底色
|
||||
○ Verify 0/2 │ ✓ review:sec object
|
||||
All 10 │ ✗ review:api dead
|
||||
```
|
||||
|
||||
## 6. 焦点与键位状态机
|
||||
|
||||
**面板状态**（`WorkflowsPanel` 内 `useState`）：
|
||||
|
||||
| 状态 | 含义 | 默认 |
|
||||
|---|---|---|
|
||||
| `activeRunId` | 当前 tab 的 runId | 首个 run（无则 null） |
|
||||
| `focusColumn` | `'phases'` \| `'agents'` | `'phases'`（该 run 无任何 phase 则 `'agents'`） |
|
||||
| `selectedPhaseIndex` | phase 侧栏选中项（`0` = `All`） | `0` |
|
||||
| `selectedAgentIndex` | agent 列表光标行 | `0` |
|
||||
|
||||
**键位**：
|
||||
|
||||
| 键 | 作用 |
|
||||
|---|---|
|
||||
| `Tab` / `Shift+Tab` | 切顶部 run tab（正/反）；切 tab 时重置 `selectedPhaseIndex=0`、`selectedAgentIndex=0`、`focusColumn` 回默认 |
|
||||
| `←` / `→` | `phases` ↔ `agents` 焦点切换（tabs 不参与左右，由 `Tab` 管） |
|
||||
| `↑` / `↓` | 当前焦点列内移动选中（phase 改筛选；agent 滚光标） |
|
||||
| `x` | kill 当前 tab 的 run |
|
||||
| `r` | resume 当前 tab 的 run（缺 `canUseTool` 时 `onDone` 提示用 `/<name> resume`） |
|
||||
| `q` / `Esc` | 退出面板 |
|
||||
|
||||
**夹紧**：复用 `WorkflowsPanel` 已导出的 `clampSelected`——切 tab / 列表变动后把 `selectedPhaseIndex`、`selectedAgentIndex` 夹到有效区间。
|
||||
|
||||
**筛选语义**：`selectedPhaseIndex===0`（`All`）→ 右栏显示全部 agent；否则按 `phase === 选中 phase title` 过滤。
|
||||
|
||||
## 7. 组件拆分（`src/workflow/panel/`）
|
||||
|
||||
| 文件 | 动作 | 职责 |
|
||||
|---|---|---|
|
||||
| `WorkflowsPanel.tsx` | 重写 | 订阅 store、持焦点状态、渲染 `TabsBar` + 左右双栏、绑 `useWorkflowKeyboard`；保留导出 `clampSelected` |
|
||||
| `TabsBar.tsx` | 新建 | 顶部 run tab 行（状态点 + 名 + runId 短码；当前 tab 橙色 `═══` 下划线） |
|
||||
| `PhaseSidebar.tsx` | 新建 | 左 phase 列表：`All` + 合并 `declaredPhases`（pending `○`）与 `run.phases`（`●`/`✓`），每行附 `done/total` agent 计数 |
|
||||
| `AgentList.tsx` | 新建 | 右 agent 列表：按选中 phase 过滤；状态色 + 行尾 `object`/`text`/`dead` 文字标记 |
|
||||
| `status.ts` | 新建 | 共享状态→字符/颜色映射（`STATUS_DOT`、phase/agent mark 函数），三组件复用 |
|
||||
| `useWorkflowKeyboard.ts` | 改写 | 焦点模型键位（见 §6） |
|
||||
| `WorkflowList.tsx` | 删除 | run 列表职责迁入 `TabsBar` |
|
||||
| `WorkflowDetail.tsx` | 删除 | phase+agent 职责拆入 `PhaseSidebar`+`AgentList` |
|
||||
| `panelCall.ts` | 不变 | local-jsx 入口仍渲染 `WorkflowsPanel` |
|
||||
|
||||
**外部接口不变**：`/workflows` 命令注册、`panelCall`、`getWorkflowService()` 订阅协议、`BackgroundTasksDialog` 跳转均不动。
|
||||
|
||||
## 8. 视觉规则
|
||||
|
||||
- **无内框**：左右两栏中间一条 `│` 竖线，仅此一条分割线；最外层保留最朴素的 round border 界定面板。
|
||||
- **聚焦列**：标题 `claude` 橙粗体；非聚焦列标题 `subtle` 灰。
|
||||
- **选中/光标行**：整行铺 `backgroundColor="claude"` 橙底（ASCII 用 `▓` 示意），**文字色不变**，状态点保留各自颜色。
|
||||
- **状态色**（沿用现有 Ink theme token，无新增）：
|
||||
|
||||
| 元素 | 状态 | 字符 | 颜色 |
|
||||
|---|---|---|---|
|
||||
| Tab (run) | running | `●` | `warning` |
|
||||
| | completed | `✓` | `success` |
|
||||
| | failed | `✗` | `error` |
|
||||
| | killed | `■` | `subtle` |
|
||||
| | 当前 | `═══` | `claude` 下划线 |
|
||||
| Phase | running | `●` | `warning` |
|
||||
| | done | `✓` | `success` |
|
||||
| | pending | `○` | `subtle` |
|
||||
| | 选中 | `▶` | `claude` + 底色 |
|
||||
| Agent | running | `●` | `warning` |
|
||||
| | done·text | `✓` | `success` + 行尾 `text` |
|
||||
| | done·object | `✓` | `success` + 行尾 `object` |
|
||||
| | dead | `✗` | `error` + 行尾 `dead` |
|
||||
|
||||
- **object 标记**：行尾纯文字 `object`（不用 `◆` 符号）。
|
||||
- **左窄右宽**：phase 栏约 20%、agent 栏约 80%（或固定 phase 栏 ~20 字符，agent 栏吃剩余宽度）。
|
||||
|
||||
## 9. 测试策略
|
||||
|
||||
- **store**：`declaredPhases` 落地 + null meta 回归（§4）。
|
||||
- **面板**（`WorkflowsPanel.test.tsx`，ink-testing-library，遵循仓库 mock 规范）：
|
||||
- 多 run → tab 渲染 + 当前 tab 下划线；`Tab`/`Shift+Tab` 切换且重置子选择。
|
||||
- `←/→` 切 `focusColumn`（标题颜色 / 光标落点）。
|
||||
- phase 侧栏选中 → 右栏 agent 按 phase 过滤；`All` 显全部。
|
||||
- pending phase（`declaredPhases` 有、store 无）显示 `○`。
|
||||
- 选中行/光标行底色条（断言对应 `<Text backgroundColor>`）。
|
||||
- `x` kill、`r` resume（mock service）、`q`/`Esc` 退出。
|
||||
- 空态（无 run）：占位文案 + `n` 提示。
|
||||
- 订阅刷新：store 变更后面板重渲染（agent 状态 running→done）。
|
||||
- **回归**：`bun run precheck` 零错误；现有 workflow 集成测试（canonical scripts / review / loop / resume）保持绿。
|
||||
|
||||
## 10. 里程碑与提交切分
|
||||
|
||||
每个里程碑结束 `bun run precheck` 必须零错误。
|
||||
|
||||
1. **M1 store**：`RunProgress.declaredPhases` + reducer `run_started` 落地 + 测试。
|
||||
2. **M2 panel 组件**：新建 `status.ts` / `TabsBar` / `PhaseSidebar` / `AgentList`；`WorkflowsPanel` 重写为焦点状态机；`useWorkflowKeyboard` 改焦点模型；删除 `WorkflowList` / `WorkflowDetail`。
|
||||
3. **M3 测试**：`WorkflowsPanel.test.tsx` 全量用例 + precheck 绿。
|
||||
4. **M4 文档**：`docs/features/workflow-scripts.md` §六 更新为三区布局/键位；旧 spec §六/§9 加注「面板部分已被 `2026-06-13-workflow-panel-redesign.md` 取代」。
|
||||
|
||||
## 11. 未做 / 未来工作
|
||||
|
||||
- per-agent skip/retry 的 UI 接线（引擎 seam 已在）。
|
||||
- agent 详情抽屉：选中 agent 后展开其 prompt/输出/token。
|
||||
- 多 run 并排对比视图。
|
||||
- `declaredPhases` 与实际 `phase()` 调用不一致时的告警（如脚本声明了 phase 却没调用）。
|
||||
@@ -0,0 +1,287 @@
|
||||
# Workflow 集成层重写 + `/workflows` 面板 + `/ultracode` skill 设计
|
||||
|
||||
> 状态：草案（待 writing-plans 据此产出实施计划）
|
||||
> 日期：2026-06-13
|
||||
> 关联：上一期引擎重建计划 `docs/superpowers/plans/2026-06-12-workflow-engine.md`、spec `docs/superpowers/specs/2026-06-12-workflow-engine-design.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景与现状
|
||||
|
||||
引擎包 `packages/workflow-engine/`（`@claude-code-best/workflow-engine`）已重建完成：`runWorkflow`、hooks（`agent`/`parallel`/`pipeline`/`phase`/`log`/`workflow`）、journal 确定性 resume、budget、concurrency、structuredOutput、`AgentAdapter` + `AgentAdapterRegistry`（commit `c2253dcb`）、端口契约（`WorkflowPorts`）与自包含工具描述符（`createWorkflowTool`），单测覆盖 99.65%。
|
||||
|
||||
`src/` 侧的集成层（`src/workflow/`）虽已接上引擎，但**没有用上引擎的全部能力**，且 TUI/命令层是占位质量：
|
||||
|
||||
- `src/workflow/adapter.ts`：硬编码单一 `WORKFLOW_AGENT`（不查 `AgentAdapterRegistry`，也没接真实 agent 注册表）；`taskRegistrar.pendingAction` 恒返回 `null`（skip/retry 未接线）；`permissionGate.isAborted` 恒 `false`；`budgetTotal` 恒 `null`；末尾有 `_AppStateUsed` 这类抑制未用导入的补丁。
|
||||
- `src/workflow/progressStore.ts`：`agent_done` 把"最后一个 running 的 agent"标完成——并发下会标错（真竞态）。
|
||||
- `/workflows`：`local` 命令，返回**纯文本**清单，不是监控面板——本设计将其原地重写为全屏面板。
|
||||
- `/ultracode`：**不存在**。
|
||||
|
||||
本设计把 `src/workflow/` 集成层**全量重写**，使其真正用上引擎能力，并交付全屏监控+控制面板与 ultracode 启动 skill。
|
||||
|
||||
## 2. 目标与非目标
|
||||
|
||||
**目标**
|
||||
|
||||
1. 全量重写 `src/workflow/` 集成层（引擎包为地基，不动其核心）。
|
||||
2. 后端为单一 `claude-code` `AgentAdapter`，但**深度接入会话体系**：provider/model/agentType/tools/telemetry 全从活的 `AppState` 解析。
|
||||
3. 把 `/workflows` **原地重写**为全屏**双栏**面板：左栏=各 workflow 的阶段树（光标移动），右栏=聚焦 workflow 的 agent 运行状况 + 基础信息；监控 + 控制（启动命名/resume/kill/展开）。
|
||||
4. 新增 `/ultracode` **纯知识 prompt skill**：把 workflow 编排工作法注入上下文，零运行时副作用。
|
||||
5. 旧 `/workflows` 文本命令重写为面板；接线点切换到新 wiring，外部 `Tool`/命令接口不变。
|
||||
|
||||
**非目标**
|
||||
|
||||
- 不改引擎包核心逻辑（唯一例外：给进度事件加 `agentId`，见 §5）。
|
||||
- 不实现多 provider adapter（v1 单后端；Registry 留扩展点但不预填路由规则）。
|
||||
- 不做 per-agent skip/retry 的 UI 接线（引擎 seam 保留，见 §12）。
|
||||
- 不翻转 `ultracode` 运行时行为开关（纯知识 skill）。
|
||||
- 不做跨进程持久化的进度恢复（live runs 留内存；resume 走 journal）。
|
||||
|
||||
## 3. 范围与迁移清单
|
||||
|
||||
**新建**
|
||||
|
||||
| 路径 | 职责 |
|
||||
|---|---|
|
||||
| `src/workflow/service.ts` | `WorkflowService` 单例门面 |
|
||||
| `src/workflow/registry.ts` | 建 `AgentAdapterRegistry`，注册单一 `claude-code` adapter |
|
||||
| `src/workflow/backends/claudeCodeBackend.ts` | 深度集成的 `AgentAdapter`（runAgent 委托 + 体系解析） |
|
||||
| `src/workflow/backends/types.ts` | 后端/host 解析类型 |
|
||||
| `src/workflow/ports.ts` | 组装 `WorkflowPorts`（registry + 任务生命周期 + journal + progress bus） |
|
||||
| `src/workflow/progress/bus.ts` | 类型化发布/订阅事件总线 |
|
||||
| `src/workflow/progress/store.ts` | reducer：`ProgressEvent` → `RunProgress[]`（按 `agentId` 关联） |
|
||||
| `src/workflow/panel/WorkflowsPanel.tsx` | 双栏全屏面板（local-jsx） |
|
||||
| `src/workflow/panel/WorkflowList.tsx` / `WorkflowDetail.tsx` / `useWorkflowKeyboard.ts` | 左栏 workflow 扁平列表 / 右栏 phase 条+agent 列表 / 键位 |
|
||||
| `src/skills/bundled/ultracode/SKILL.md` | `/ultracode` 知识 skill |
|
||||
|
||||
**重写（整体替换，非打补丁）**
|
||||
|
||||
- `src/workflow/adapter.ts` → 拆解进 `backends/`+`ports.ts`+`registry.ts`
|
||||
- `src/workflow/wiring.ts` → 薄包装，走 `service`
|
||||
- `src/workflow/progressStore.ts` → 拆进 `progress/{bus,store}.ts`
|
||||
- `src/workflow/hostHandle.ts` → 清理（保留不透明 bundle 语义）
|
||||
- `src/workflow/namedWorkflowCommands.ts` → 重写（扫 `.claude/workflows/` → `/<name>`）
|
||||
- `src/commands/workflows/index.ts` → 原地重写：`local` 文本命令 → `local-jsx` 面板入口（命令名仍为 `workflows`）
|
||||
|
||||
**改接线点（接口不变，换实现来源）**
|
||||
|
||||
`src/tools.ts`、`src/commands.ts`、`src/tasks.ts`、`src/constants/tools.ts`、`src/utils/permissions/classifierDecision.ts`、`src/components/permissions/PermissionRequest.tsx`、`src/components/tasks/BackgroundTasksDialog.tsx`（workflow 详情入口改为打开 `/workflows <runId>`）。
|
||||
|
||||
**删除**
|
||||
|
||||
- `src/components/tasks/WorkflowDetailDialog.tsx`（详情视图被 `/workflows` 右栏 `WorkflowDetail` 取代；逻辑并入，`BackgroundTasksDialog` 改为跳转 `/workflows`）。
|
||||
|
||||
**引擎微调**
|
||||
|
||||
- `packages/workflow-engine/src/types.ts`、`src/engine/hooks.ts`：`agent_started`/`agent_done` 加 `agentId: number`（见 §5）。
|
||||
|
||||
## 4. 架构总览
|
||||
|
||||
```
|
||||
src/workflow/
|
||||
├─ service.ts # launch/resume/kill/listRuns/getRun/subscribe/listNamed
|
||||
├─ registry.ts # AgentAdapterRegistry（单一 claude-code adapter，default 路由）
|
||||
├─ hostHandle.ts # 不透明 host bundle（toolUseContext/canUseTool/parentMessage/agentId）
|
||||
├─ ports.ts # WorkflowPorts = { hostFactory, agentRunner(registry), progressEmitter(bus+store), taskRegistrar, journalStore, permissionGate, logger }
|
||||
├─ backends/
|
||||
│ ├─ claudeCodeBackend.ts # AgentAdapter：深度解析 + runAgent 委托
|
||||
│ └─ types.ts
|
||||
├─ progress/
|
||||
│ ├─ bus.ts # emit→多订阅者（store / 面板 / 遥测）
|
||||
│ └─ store.ts # RunProgress[] reducer（agentId 关联）
|
||||
├─ panel/
|
||||
│ ├─ WorkflowsPanel.tsx # 双栏，useSyncExternalStore 订阅 store
|
||||
│ ├─ WorkflowList.tsx # 左栏：扁平 workflow 列表（名字+状态+当前 phase+计数）
|
||||
│ ├─ WorkflowDetail.tsx # 右栏：聚焦 workflow 的 phase 横条 + 扁平 agent 列表
|
||||
│ └─ useWorkflowKeyboard.ts
|
||||
├─ wiring.ts # createWorkflowToolCore(): buildTool(引擎描述符)
|
||||
└─ namedWorkflowCommands.ts # 扫描→/<name>
|
||||
```
|
||||
|
||||
**依赖方向**：`panel` 与 `wiring`（工具）只依赖 `service`；`service` 依赖 `registry`+`ports`+`progress`+引擎；`backends` 依赖 `hostHandle`+核心 `runAgent`。引擎包零 `src/*` 导入不变。
|
||||
|
||||
## 5. 引擎微调：进度事件加 `agentId`
|
||||
|
||||
当前 `agent_started`/`agent_done` 只带 `label`/`phase`，reducer 只能 LIFO 猜匹配。改为：
|
||||
|
||||
```ts
|
||||
// packages/workflow-engine/src/types.ts（变体加字段）
|
||||
| { type: 'agent_started'; runId: string; agentId: number; label?: string; phase?: string }
|
||||
| { type: 'agent_done'; runId: string; agentId: number; label?: string; phase?: string; result: AgentRunResult }
|
||||
```
|
||||
|
||||
`makeHooks`（`engine/hooks.ts`）维护引擎内递增计数器（非脚本沙箱内，可用普通计数器，不受 Date/Math 禁令影响），在 `agent()` 内为每次调用分配 `agentId`，同时盖戳 `agent_started` 与 `agent_done`。`pipeline`/`parallel` 内并发调用各自独立 id，reducer 按 id 精确落位。补 `hooks.test.ts`：并发 agent 的 started/done id 配对回归。
|
||||
|
||||
## 6. WorkflowService
|
||||
|
||||
```ts
|
||||
type HostContext = { handle: HostHandle; cwd: string; budgetTotal: number | null; toolUseId?: string }
|
||||
|
||||
type WorkflowService = {
|
||||
launch(opts: {
|
||||
source: { script: string } | { name: string } | { scriptPath: string }
|
||||
args?: unknown
|
||||
hostContext: HostContext // 调用方构造（工具/面板各自）
|
||||
description?: string
|
||||
resumeFromRunId?: string
|
||||
}): Promise<{ runId: string }> // 立即返回，后台 detached
|
||||
resume(runId: string, hostContext: HostContext): Promise<void>
|
||||
kill(runId: string): void // AbortController.abort() → WorkflowAbortedError → killed
|
||||
listRuns(): RunProgress[]
|
||||
getRun(runId: string): RunProgress | undefined
|
||||
subscribe(listener: () => void): () => void // 供 useSyncExternalStore
|
||||
listNamed(): Promise<string[]> // 委托 namedWorkflows
|
||||
}
|
||||
```
|
||||
|
||||
**数据流**：`launch` → 解析脚本源 → `parseScript` 快速校验 → 注册 `LocalWorkflowTask`（拿 runId + AbortSignal）→ `progress.bus.emit(run_started)` → `runWorkflow({ ports, host, signal, runId, ... })` detached → 引擎经 hooks 发 `ProgressEvent` → `ports.progressEmitter.emit` 同时喂 `bus`（订阅者）与 `store`（reducer）→ 面板 `useSyncExternalStore` 重渲染。
|
||||
|
||||
**host context 来源（关键解耦）**：service 不自造 host，由调用方传 `HostContext`：
|
||||
|
||||
- **工具路径**：`wiring.ts` 的 `call` 用引擎 `ports.hostFactory({ context, canUseTool, parentMessage })` 构造（沿用现状）。
|
||||
- **面板路径**：`/workflows` 是 local-jsx，回调拿 `ToolUseContext`；面板用它 + 会话 `canUseTool`（按当前权限模式）构造 host，使面板启动的 workflow 子 agent 享有与主会话一致的工具池与权限。
|
||||
|
||||
单例：`service`、`ports`、`registry`、`bus`、`store` 全进程共享，保证工具与面板同源（修掉旧"每实例一套 adapter/bindings"的隐患）。
|
||||
|
||||
## 7. 后端深度集成（depth B：单一 adapter，深度读体系）
|
||||
|
||||
`claudeCodeBackend.ts` 实现引擎 `AgentAdapter` 接口，`run(params, ctx)` 内**主动从活会话体系解析**，再委托核心 `runAgent`：
|
||||
|
||||
```ts
|
||||
// backends/claudeCodeBackend.ts（签名级草图）
|
||||
export const claudeCodeBackend: AgentAdapter = {
|
||||
id: 'claude-code',
|
||||
capabilities: { structuredOutput: true, modelOverride: true },
|
||||
async run(params: AgentRunParams, ctx: AgentAdapterContext): Promise<AgentRunResult> {
|
||||
const { toolUseContext, canUseTool } = unwrapHostBundle(ctx.host)
|
||||
const appState = toolUseContext.getAppState()
|
||||
|
||||
// 1) agentType → 真实 agent 注册表（不再硬编码 WORKFLOW_AGENT）
|
||||
const agentDef = resolveAgentDefinition(params.agentType, toolUseContext) // activeAgents 命中；WORKFLOW_AGENT 兜底
|
||||
|
||||
// 2) model → provider 模型映射
|
||||
const resolvedModel = params.model ? mapWorkflowModel(params.model, appState) : undefined
|
||||
|
||||
// 3) 工具池（活权限上下文）
|
||||
const tools = assembleToolPool(workerPermissionContext(appState, agentDef), appState.mcp.tools)
|
||||
|
||||
// 4) schema → StructuredOutput 指令；prompt 组装
|
||||
// 5) runAgent({ agentDefinition, promptMessages, toolUseContext, canUseTool,
|
||||
// isAsync: true, availableTools: tools, override: { agentId, model: resolvedModel } })
|
||||
// 6) finalizeAgentTool → 取 outputTokens / 文本 / 结构化对象 → AgentRunResult
|
||||
// 失败 → { kind: 'dead' }
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
要点：
|
||||
|
||||
- **provider 感知**：`mapWorkflowModel` 走 `src/utils/model/` 把 `claude-haiku-*` 这类别名解析为当前 provider 的实际 model id；provider 来自 `src/utils/model/providers.ts` 的会话判定。
|
||||
- **agentType → 真实注册表**：`resolveAgentDefinition` 查 `toolUseContext.options.agentDefinitions.activeAgents`，命中即用（Explore/code-reviewer 等内置 + 用户 agent）；未命中或无 `agentType` 退 `WORKFLOW_AGENT` 兜底。
|
||||
- **工具池/权限**：worker 权限上下文取 agent 定义或 `acceptEdits`，`assembleToolPool` 生成。
|
||||
- **遥测/token**：`finalizeAgentTool` 的 `usage.output_tokens` 喂 engine budget；`logEvent('tengu_workflow_agent', {…})` 逐 agent 计量。
|
||||
- **Registry**：`registry.ts` = `new AgentAdapterRegistry().register(claudeCodeBackend).default('claude-code')`。`ports.agentRunner.runAgentToResult = (params, host) => registry.resolve(params).run(params, { host })`。v1 不预填路由规则（depth B：单 adapter，不预留多 provider 路由）。
|
||||
|
||||
## 8. 进度模型（bus + store + agentId 关联）
|
||||
|
||||
- `progress/bus.ts`：`createProgressBus()` 返回 `{ emit(event), subscribe(fn) }`。emit 广播给所有订阅者（store、面板、遥测）。替换旧"只有 in-memory Map"的单消费者模型。
|
||||
- `progress/store.ts`：`RunProgress[]` reducer，沿用 `RunProgress` 形状（runId/status/phases/currentPhase/agents/logs/agentCount/returnValue/error/updatedAt）。新增 `AgentProgress.id: number`；`agent_done` 按 `event.agentId` 精确匹配 `agents[].id`（修掉旧 LIFO 竞态）。`subscribe()` 暴露给 React `useSyncExternalStore`。
|
||||
- 状态为进程内（live runs）；resume 读磁盘 journal（`.claude/workflow-runs/<runId>/journal.jsonl`）。
|
||||
|
||||
## 9. `/workflows` 双栏面板（左列表 / 右 phase+agent）
|
||||
|
||||
`/workflows` 命令**原地重写**为 `local-jsx`（替换原文本命令），渲染**双栏**面板：走 `FullscreenLayout.modal` 路径（底部锚定、向上生长，`maxHeight ≈ terminalRows`，留 2 行 transcript peek，与 `/model`、`/config` 一致），`useSyncExternalStore` 订阅 `service.subscribe` 实时刷新。**左栏=扁平 workflow 列表（极简），右栏=聚焦 workflow 的 phase 横条 + 扁平 agent 列表**。无树、无嵌套。
|
||||
|
||||
```
|
||||
Workflows · 2 running · 1 done q quit
|
||||
|
||||
▸ ● review-pipeline Verify 2/3 8/12
|
||||
● smoke-test Pong 3/3
|
||||
✓ code-audit done 11/11
|
||||
|
||||
Named: research-report · smoke
|
||||
|
||||
─────────────────────────────────────────────────
|
||||
review-pipeline ● running
|
||||
|
||||
Phases ✓Find ✓Review ●Verify
|
||||
● verify:api 1.2k · verify:db —
|
||||
✓ find:src 3.1k ✓ verify:auth 2.0k
|
||||
|
||||
j/k run · r resume · x kill · n new
|
||||
```
|
||||
|
||||
**导航模型**：左栏是扁平 workflow 列表——每行一个 run（状态点 + 名称 + 当前 phase + `done/total` agent 计数），光标 `▸` 用 `j/k` 上下选 run，选中即聚焦、右栏随之切换。底部 NAMED 区（`service.listNamed()`，`n` 启动）。无展开/收起、无嵌套。
|
||||
|
||||
**组件**
|
||||
|
||||
- `WorkflowList.tsx`：左栏。`service.listRuns()` → 每行 `●`/`✓` 状态点 + workflow 名 + 当前 phase + agent 计数；底部 NAMED。
|
||||
- `WorkflowDetail.tsx`：右栏。一行头（workflow 名 + 状态）+ **Phases 横条**（`✓`/`●`/`○` 内联）+ **扁平 agent 列表**（每项状态符 + label + token，自动换行排版，不嵌套）。终态显示 `returnValue`/`error`。
|
||||
- `useWorkflowKeyboard.ts`：键位见下。
|
||||
|
||||
**键位**：`j/k` 选 run · `r` resume 聚焦 workflow（读 journal）· `x` kill · `n` 选命名 workflow 启动 · `q`/`esc` 经 `onDone()` 关闭。空 run 时左栏聚焦 NAMED，右栏给"新建脚本到 `.claude/workflows/`"提示。
|
||||
|
||||
**颜色（Impeccable 体系）**：running = Claude Orange `#D77757` 动态点；done = 绿；failed = 红；killed = 灰；底栏键位 `subtle`。
|
||||
|
||||
**与 `WorkflowDetailDialog.tsx` 的关系**：该旧组件删除，详情逻辑并入右栏 `WorkflowDetail`；`BackgroundTasksDialog`（Shift+Down）保留为后台任务总览，其 workflow 详情跳转改为打开 `/workflows <runId>`，面板以该 run 为初始聚焦。
|
||||
|
||||
**命令注册**：`src/commands/workflows/index.ts` 导出 `local-jsx` 命令（`load: () => import('../../workflow/panel/WorkflowsPanel.js')`），在 `src/commands.ts` 经 `feature('WORKFLOW_SCRIPTS')` 条件注册（替换原文本 `workflowsCmd`）。
|
||||
|
||||
## 10. Workflow 工具 wiring
|
||||
|
||||
`wiring.ts` 仍薄：`createWorkflowToolCore(): Tool = buildTool(引擎描述符)`，描述符 = `createWorkflowTool(service.ports)`。保持 `Tool` 接口（name/inputSchema/isEnabled/isReadOnly/description/prompt/call/renderToolUseMessage/mapToolResultToToolResultBlockParam）。**关键变化**：描述符不再各自 `createWorkflowAdapter()`，统一走 `service` 单例。工具 `call` 返回 `run_id` + 提示"用 /workflows 查看实时进度"。工具仍在 `CORE_TOOLS`/`ALL_AGENT_DISALLOWED_TOOLS`，权限分类、`WorkflowPermissionRequest` 接新 wiring。
|
||||
|
||||
## 11. `/ultracode` skill
|
||||
|
||||
`src/skills/bundled/ultracode/SKILL.md`，`type: prompt`、`user-invocable: true`（自动成 `/ultracode`）。内容 = 蒸馏后的 workflow 编排 playbook：
|
||||
|
||||
- **frontmatter**：`name: ultracode`、`description: 进入多 agent workflow 编排模式：何时用、编排原语、质量模式、确定性约束、后端路由、resume/budget、文件与命令`、`user-invocable: true`。
|
||||
- **何时用 workflow**：可分解/并行、需多视角置信、规模超单上下文、需 resume/审计；何时**不**用（琐碎单文件、单次问答）。
|
||||
- **编排原语速查**：`agent`/`parallel`/`pipeline`/`phase`/`log`/`workflow` 语义与陷阱（pipeline 默认无 barrier、parallel 单项抛错→null、budget 硬上限、并发 cap、`MAX_TOTAL_AGENTS=1000`/`MAX_ITEMS_PER_CALL=4096`）。
|
||||
- **质量模式库**（每种给最小可运行片段）：adversarial-verify（多数票 refute）、perspective-diverse verify、judge panel、loop-until-dry、multi-modal sweep、completeness critic。
|
||||
- **确定性约束**：脚本内禁 `Date.now()`/`Math.random()`（经 `args` 传时间戳/种子）；`meta` 必须纯字面量。
|
||||
- **后端路由**：`AgentAdapterRegistry` 按 model/agentType 路由；v1 默认 `claude-code`，深度读会话 provider/model/agent 体系。
|
||||
- **resume/budget**：`resumeFromRunId` 重放 journal；`budget.total` 硬顶（默认无限）。
|
||||
- **文件与命令**：`.claude/workflows/`、`.claude/workflow-runs/<runId>/journal.jsonl`、`/workflows` 面板、`/<name>` 命名命令。
|
||||
|
||||
调用即注入上下文，**不改主循环、零运行时副作用**。
|
||||
|
||||
## 12. 错误处理 / 权限 / 生命周期 / 并发 / budget / skip-retry
|
||||
|
||||
- **错误**：脚本语法/meta 错 → `parseScript` 即时返错（不进后台）；agent 抛错 → `kind:'dead'`→`null`，workflow 继续（parallel/pipeline 容错）；`WorkflowAbortedError` → `killed`；其它 → `failed`+error。终态走 `run_done` + `LocalWorkflowTask` complete/fail/kill。
|
||||
- **权限**：worker 用 `assembleToolPool(workerPermissionContext, mcp.tools)`，权限模式取 agent 定义或 `acceptEdits`；面板启动的 run 用面板 `ToolUseContext` 的 `canUseTool`。`WorkflowPermissionRequest.tsx` 保留并接新 wiring。
|
||||
- **生命周期/并发/budget**：复用引擎 `Semaphore`（`min(16, cores-2)`）、`MAX_TOTAL_AGENTS=1000`、`MAX_ITEMS_PER_CALL=4096`、`Budget`（默认 `null` 无限；可经 settings/env 注入 turn 级上限，留参数）。
|
||||
- **skip/retry（per-agent）**：引擎 `taskRegistrar.pendingAction` seam 保留；v1 返 `null`。面板控制诉求由 kill/resume 覆盖。
|
||||
|
||||
## 13. 测试策略
|
||||
|
||||
- **引擎**：`hooks.test.ts` 加"并发 agent 的 started/done id 配对"回归。
|
||||
- **集成层**（`src/workflow/__tests__/`）：
|
||||
- `service.test.ts`：launch→completed/failed/killed、resume 走 journal、kill 中止、subscribe 通知（mock 端口，无 LLM）。
|
||||
- `registry.test.ts`：默认路由命中 `claude-code`；`resolve` 对未知规则回落默认。
|
||||
- `claudeCodeBackend.test.ts`：agentType→真实定义命中/兜底；model→映射；失败→`dead`（mock `runAgent`）。
|
||||
- `progressStore.test.ts`：**并发 `agent_done` 按 `agentId` 精确关联**（回归旧竞态）、phase 切换、`run_done` 终态。
|
||||
- `WorkflowsPanel.test.tsx`（ink-testing-library）：扁平列表渲染、光标 j/k 切换聚焦 workflow、右栏 phase 条+agent 列表、键位 x/r/n、空态、订阅刷新。
|
||||
- **回归**：`bun run precheck` 零错误；现有 workflow 集成测试（canonical scripts/review/loop/resume）仍绿。
|
||||
- 遵循仓库 mock 规范（共享 `tests/mocks/log.ts`、`debug.ts`；mock 底层 HTTP/副作用，不 mock 业务模块；注意 `mock.module` 进程全局污染，集成测试 mock axios 而非源 API 模块）。
|
||||
|
||||
## 14. 里程碑与提交切分
|
||||
|
||||
每个里程碑结束 `bun run precheck` 必须零错误。
|
||||
|
||||
1. **M1 引擎微调**：`ProgressEvent.agentId` + hooks 盖戳 + 单测。
|
||||
2. **M2 进度层**：`progress/bus.ts` + `store.ts`（agentId 关联）+ 测试。
|
||||
3. **M3 后端 + Registry + ports + hostHandle**：`claudeCodeBackend`（深度解析）、`registry`、`ports` 组装 + 测试。
|
||||
4. **M4 Service 门面**：`service.ts`（launch/resume/kill/subscribe/listNamed）+ 测试。
|
||||
5. **M5 工具 wiring 切换 + 接线点更新**：`wiring.ts` 走 service；更新 tools/commands/tasks/constants/classifier/PermissionRequest/BackgroundTasksDialog。`precheck` 绿。
|
||||
6. **M6 `/workflows` 面板（原地重写命令）**：panel 组件（`PhaseTree`/`AgentStatus`）+ 键位 + 把 `src/commands/workflows/` 重写为 local-jsx + 测试。
|
||||
7. **M7 `/ultracode` skill**：`SKILL.md` playbook。
|
||||
8. **M8 文档**：更新 `docs/features/workflow-scripts.md`，新增面板/skill 说明。
|
||||
|
||||
## 15. 未做 / 未来工作
|
||||
|
||||
- 多 provider adapter（OpenAI/Gemini/Grok/Bedrock/Vertex 等真后端 + model 路由分流）——引擎 Registry 机制本身在用（单 adapter），扩第二个 adapter 时再补 `route` 规则；本期按 depth B 不预填。
|
||||
- per-agent skip/retry 的 UI 接线（引擎 seam 已在）。
|
||||
- `ultracode` 运行时行为开关（默认倾向 Workflow 工具）——本期为纯知识 skill。
|
||||
- 跨进程/重启的 live 进度恢复（当前内存；resume 走 journal）。
|
||||
- `budgetTotal` 从 settings/env 注入 turn 级预算。
|
||||
Reference in New Issue
Block a user