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 / 并发） |
--- a/docs/superpowers/plans/2026-06-12-workflow-engine.md
+++ b/docs/superpowers/plans/2026-06-12-workflow-engine.md
--- a/docs/superpowers/plans/2026-06-13-workflow-panel-redesign.md
+++ b/docs/superpowers/plans/2026-06-13-workflow-panel-redesign.md
--- a/docs/superpowers/plans/2026-06-13-workflow-tui-ultracode.md
+++ b/docs/superpowers/plans/2026-06-13-workflow-tui-ultracode.md
--- a/docs/superpowers/reviews/2026-06-13-workflow-engine-commit-0768d4dc-review.md
+++ b/docs/superpowers/reviews/2026-06-13-workflow-engine-commit-0768d4dc-review.md
@@ -0,0 +1,159 @@
+# Commit 审查报告：0768d4dc8f69023b55adf2f5c176c766640600cb
+
+- **Commit**: `0768d4dc8f69023b55adf2f5c176c766640600cb`
+- **Title**: `feat(workflow): add workflow engine, /workflows panel, /ultracode skill`
+- **Author**: claude-code-best <claude-code-best@proton.me>
+- **Date**: 2026-06-13
+- **规模**: 90 文件，+12925 / -833
+- **审查日期**: 2026-06-13
+- **审查方法**: 多视角对抗式 workflow 编排（7 个并行 reviewer → consolidator 合并 → refuter 反驳 → final judge），journal `run_id = wtujwahzf`
+
+---
+
+## TL;DR
+
+这个 commit 引入的 workflow engine **架构干净、引擎层测试覆盖率高**，但**脚本沙箱和路径校验存在真实漏洞**，并且在本次审查过程中**我亲身实证发现了多个 judge report 没覆盖的 host 集成 bug**（其中包括 workflow 状态变更通知根本没有接进 host 通知系统，导致"完成时自动通知"承诺落空）。受信 LLM 威胁模型下无严格 blocker，但建议合并前修 4 项。
+
+**严重度计数**（综合 judge + 我的实证）：
+- CRITICAL: 0
+- HIGH: 2
+- MEDIUM: 9
+- LOW: 4
+- INFO: 6
+
+---
+
+## 审查方法
+
+用 commit 自身引入的 workflow engine 跑了一个对抗式审查 workflow：
+
+1. **Phase 1 — MultiPerspectiveScan**: 7 个并行 reviewer（architecture / runtime / types / test-quality / integration / security / removal-docs），用 Explore agentType，独立扫各自维度
+2. **Phase 2 — Consolidation**: opus consolidator 合并去重，按主题归类
+3. **Phase 3 — AdversarialRefutation**: general-purpose refuter 对每个 CRITICAL/HIGH 用新证据反驳
+4. **Phase 4 — FinalReport**: opus judge 综合输出最终报告
+
+journal 完整 10 条 agent 记录在 `.claude/workflow-runs/wtujwahzf/journal.jsonl`。
+
+**审查过程中实证发现的额外 bug**（judge 没覆盖，因为我正好用这个引擎跑审查才暴露）：见下一节。
+
+---
+
+## 我实证发现的 bug（judge report 之外）
+
+这些是跑审查过程中亲身踩到的，judge 的 7 个 reviewer 没看到，因为这些 bug 涉及 host 集成层（`src/workflow/*`、`src/tasks/LocalWorkflowTask/*`）和实际工具调用语义，需要"真正用一次"才能暴露。
+
+### [HIGH] `args` schema 回归：旧 `z.string()` → 新 `z.unknown()`，prompt 未同步
+
+- **文件**: `packages/workflow-engine/src/tool/schema.ts:14-19`、`packages/workflow-engine/src/tool/WorkflowTool.ts:38-49, 114`
+- **现象**: 调用 Workflow 工具传 `args: {"commit": "..."}`，脚本里 `args.commit === undefined`。子 agent 端到端复现：当 args 是 object 时全链路 OK；是 string 时丢字段。
+- **根因**: 旧 `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts`（本 commit 删除）的 schema 是 `args: z.string().optional()`，模型按旧契约发字符串。本 commit 改成 `z.unknown().optional()` 但 prompt 没强约束"必须传对象"，模型继续按旧契约发字符串 → 运行时 `args` 是 string → 脚本里 `args.commit` 拿不到。
+- **影响**: 任何依赖 `args` 透传的命名 workflow 都会拿到 undefined 字段，直接 throw 或 silently 拿不到参数。我不得不在脚本里把 commit hash 写死绕过。
+- **修复方向**:
+  - `WorkflowTool.call` 加防御：`if (typeof input.args === 'string') input.args = JSON.parse(input.args)`
+  - 或 schema 用 `z.preprocess((v) => typeof v === 'string' ? JSON.parse(v) : v, z.unknown())`
+  - 同步 prompt：明确"args 必须是 JSON 对象，禁止传字符串化的 JSON"
+
+### [HIGH] Workflow 状态变更通知未接入 host 通知系统
+
+- **文件**: `packages/workflow-engine/src/tool/WorkflowTool.ts:127-140`、`src/workflow/ports.ts:84-135`、`src/workflow/wiring.ts`
+- **现象**: WorkflowTool 的工具返回文本承诺"完成时会自动通知。用 /workflows 查看实时进度。"，但本次审查中：
+  - smoke test (`w17jmnsq3`) 完成时，我没收到任何 task-notification
+  - review-commit (`wtujwahzf`) 完成时，我没收到任何 task-notification，是用户手动告诉我"结束了"我才知道
+  - 失败的 review-commit (`wpv9nu2eo`、`w2tvwj0ka`) 也没收到失败通知
+  - 同期启动的 Agent 工具（非 workflow）完成时**有**收到 `<task-notification>`
+- **根因**: 引擎确实通过 `ports.progressEmitter.emit({ type: 'run_done', ... })` 发了事件，`taskRegistrar.complete/fail/kill` 也被调了，但**没有任何代码把这些事件桥接到 host 的通知机制**（AgentTool 完成时通过 `runAgent.ts` 的 finally 触发 task-notification）。Workflow tool detached 执行后，host 没有订阅 taskRegistrar 的状态变更。
+- **影响**: 任何 workflow（特别是耗时长的）跑完用户都不知道；用户必须主动 `/workflows` 查看；workflow 失败时用户完全感知不到。这直接违背了 commit message 和 prompt 中"完成时会自动通知"的承诺。
+- **修复方向**:
+  - 在 `src/workflow/wiring.ts`（或 host bundle 构造处）订阅 `WorkflowService.subscribe`，对 `status` 从 `running` → `completed/failed/killed` 的转换发 host 通知
+  - 或在 `WorkflowTool.ts:124` 的 `.then(result => onFinish(...))` 内，根据 result.status 触发 host notification（参考 `runAgent.ts` 的 task-notification 路径）
+
+### [MEDIUM] `failWorkflowTask` 丢弃 error message
+
+- **文件**: `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts:96-107`
+- **现象**: workflow 失败时 progress store 的 `RunProgress.error` 字段在 `/workflows` 面板能看到（`WorkflowDetail.tsx:63-67` 渲染 `run.error`），但 `BackgroundTasksDialog` 用的 `LocalWorkflowTask` 状态对象没有 error 字段——`failWorkflowTask(taskId, setAppState)` 完全丢弃 error。两套状态系统不一致。
+- **影响**: 用户在 `BackgroundTasksDialog` 看到 workflow 标记为 failed，但不知道为什么 failed；必须切到 `/workflows` panel 才能看到 error 文字。
+- **修复方向**: `failWorkflowTask` 签名加 `error?: string` 参数，存入 `LocalWorkflowTaskState`，并在 `BackgroundTasksDialog` 渲染。
+
+### [LOW] WorkflowTool 的 run_id 提示与实际 run 目录解析路径不一致
+
+- **文件**: `src/workflow/ports.ts:69`、`packages/workflow-engine/src/tool/WorkflowTool.ts:121`
+- **现象**: `WorkflowTool.ts:121` 的 `cwd: host.cwd` 来自 `getCwd()`（运行时 cwd，可能在 worktree 切换时变化）；而 `ports.ts:69` 的 `runsDir = ${getProjectRoot()}/.claude/workflow-runs` 用的是 session 启动时的 project root。两者在某些路径下不一致（如 mid-session `EnterWorktreeTool`）。
+- **影响**: 命名 workflow 文件解析（用 cwd）和 journal 持久化路径（用 projectRoot）可能落到不同目录，调试时混乱。
+- **修复方向**: 统一用 `getProjectRoot()`，或在文档里明确两者的语义差异。
+
+---
+
+## Judge 报告核心 finding
+
+### HIGH：脚本沙箱可被动态 `import()` 绕过
+
+- **文件**: `packages/workflow-engine/src/engine/script.ts:166-221`
+- **问题**: `assertScriptBody` 只屏蔽**静态** `import` 语句（regex `/^\s*import\b/m`），但 `new AsyncFunction()` 体内可 `await import('node:child_process')`、可直接访问 `process.env` / `Buffer` / `globalThis`。Node 和 Bun 实测都能逃逸。
+- **降级理由**: LLM 本就有 `BashTool`（`src/constants/tools.ts:139`），沙箱逃逸不扩大能力；但破坏了 resume 的确定性假设 + 未来若引入半信任脚本源会致命。
+- **修复**: `import(` 加进 regex 黑名单 + 文档明确"沙箱保确定性，不保安全"。
+
+### MEDIUM（7 项，按价值排序）
+
+1. **`scriptPath` 任意文件读，无路径校验** — `WorkflowTool.ts:184-188`、`service.ts:104-109`。`input.scriptPath` 来自 LLM，无 containment check，可读 `/etc/passwd`、`~/.ssh/id_rsa`。`FileReadTool` 已有此能力，但 `scriptPath` 绕过权限提示。
+2. **命名 workflow 路径遍历** — `namedWorkflows.ts:18-19`。`name` 参数未过滤 `../`，`name = "../../etc/passwd"` 可逃出 `workflowDir`（虽然 `.ts/.js/.mjs` 扩展名限制缓解了利用）。
+3. **Budget 检查竞态** — `hooks.ts:53, 95-106`。`assertCanSpend()` 在 semaphore 之前，N 个并发都能过检 → 实测 4 并发 100 token budget 实花 200（100% 超支）。默认 `budget = null` 时不触发，显式设 budget 才暴露。
+4. **`parallel`/`pipeline` 静默吞错** — `hooks.ts:126-134, 148-160`。`catch {}` 完全无日志，workflow 作者无法知道 agent 为何失败。"null on error"契约本身是对的，但应该 log。
+5. **双重类型断言掩盖 schema/type 漂移** — `WorkflowTool.ts:56`。`workflowInputSchema as unknown as z.ZodType<WorkflowInput>`，应该 `export type WorkflowInput = z.infer<typeof workflowInputSchema>`。
+6. **Service 层测试 mock adapter 永远返回 ok** — `service.test.ts:39-68`。`fakePorts()` 永远返回 `{kind: 'ok', output: 'mock-out'}`，service 层的失败路由（`service.ts:164-173`）未测。
+7. **Journal 并发写入顺序非确定** — `hooks.ts:111-113`。`push` + `index++` 同步原子，但 `await append()` 落盘顺序是完成顺序而非调用顺序。resume 时若并发完成顺序不同，key 不匹配 → journal 失效 → 全重跑。**对 parallel workflow 来说 resume 几乎无效**。
+
+### LOW / INFO
+
+- LOW: Semaphore permit 在 abort 时延迟释放（queued waiter 阻塞至 permit 到来）
+- LOW: `WorkflowsPanel.tsx:40-45` 的 `useSyncExternalStore` 无 error boundary
+- LOW: WorkflowService singleton 无 shutdown 清理
+- INFO: `AgentRunParams.schema` 用 `object` 而非 `Record<string, unknown>`
+- INFO: `WorkflowInputSchema` 类型未从 package index 导出
+- INFO: 旧 `builtin-tools/WorkflowTool` 删除干净，无残留 import
+- INFO: workflow-engine 包零 host 依赖（只 ajv + zod）
+- INFO: HostHandle 用 Symbol-based opacity 是合理的 seam
+
+### 被反驳的发现（refuter 用新证据推翻）
+
+- ~~**CRITICAL**: 并发 journal 索引腐蚀~~ — 误判 JS 单线程执行模型。`push` 和 `index++` 之间无 `await`，不可被抢占。
+- ~~**HIGH**: 键盘 stale reference 竞态~~ — 误判 `useEventCallback` 语义。`usehooks-ts` 的 ref 在 layout phase 同步更新，键盘 handler 总能拿到最新 `focused`。
+- ~~**HIGH**: sub-agent 默认 `acceptEdits` 权限~~ — 全代码库约定（`resumeAgent.ts:161` 同样写法），非 workflow 特有漏洞。
+
+---
+
+## 做得好的地方
+
+1. **架构干净**：workflow-engine 包零 host 依赖（只 ajv + zod），教科书级 hexagonal。所有 host 交互通过注入的 `Ports` / `HostHandle`。
+2. **Journal 离散检测健壮**：`hooks.ts:65-81` 的 key mismatch → 优雅降级到全重跑，不会产生错误结果。
+3. **Budget API 设计良好**：`Budget` 类的 `assertCanSpend` / `addOutputTokens` / `remaining` API 表面正确（虽然实现有竞态），后续加 reservation 机制容易。
+4. **Engine 层测试覆盖扎实**：`hooks.test.ts` 覆盖 dead / skipped / budget exhaust / abort / adapter 错误 / parallel-pipeline error suppression，这是 engine 层该有的覆盖深度。
+5. **旧代码删除干净**：commit 正确删除 `builtin-tools/WorkflowTool`，保留 `bundled/` 作为扩展点，更新 `biome.json` 排除项匹配新架构，无残留 import。
+6. **设计文档完备**：`docs/features/workflow-scripts.md`、`docs/superpowers/specs/2026-06-12-workflow-engine-design.md`、`docs/superpowers/plans/2026-06-12-workflow-engine.md` 配套齐全。
+
+---
+
+## 推荐 merge 前修复（按优先级）
+
+1. **[HIGH] Workflow 状态变更通知接入 host** — 在 `src/workflow/wiring.ts` 订阅 `WorkflowService.subscribe`，对 status 转换发 host notification；这是 commit message 和 prompt 已承诺但未实现的功能。
+2. **[HIGH] `args` schema 防御性 parse** — `WorkflowTool.call` 加 `if (typeof input.args === 'string') JSON.parse(...)` + 同步 prompt。
+3. **[HIGH] 脚本沙箱黑名单加 `import(`** — `script.ts:166` 一行修复 + 文档明确"沙箱保确定性不保安全"。
+4. **[MEDIUM] `scriptPath` / `name` 路径校验** — containment check，拒绝 `../`、绝对路径越界。
+5. **[MEDIUM] `failWorkflowTask` 保存 error** — 签名加 error 参数，存入 task state，与 progress store 对齐。
+6. **[MEDIUM] `assertCanSpend()` 挪到 semaphore critical section 内** — 关闭 budget 超支竞态。
+7. **[MEDIUM] service.test.ts 加 dead/skipped 路由测试** — 关闭 service 层失败路由覆盖盲区。
+8. **[MEDIUM] `WorkflowInput = z.infer<typeof workflowInputSchema>`** — 消除双重断言，防 schema/type 漂移。
+
+前 5 项都是几行到几十行的小改动，建议合并前完成。第 6-8 项可以 follow-up。
+
+---
+
+## 审查过程的元观察（dogfooding 发现）
+
+用 commit 自身引入的 workflow engine 跑这个审查，等于把引擎当 dogfood。除了上述具体 bug，还有一些元观察：
+
+- **"完成时自动通知"承诺落空**是最影响用户体验的一条——workflow 跑完了用户不知道，跑挂了用户也不知道，必须主动 `/workflows`。这违背了工具描述里写的契约。
+- **journal 落盘路径与命名 workflow 解析路径用了不同根**（`getProjectRoot()` vs `getCwd()`），调试时容易找不到 journal 文件。
+- **smoke test 能跑通、review-commit 不能跑通**——区别在于 review-commit 读 `args.commit`，这暴露了 schema 回归。说明现有测试覆盖（即使是 99.65% 的引擎覆盖率）无法替代真实使用场景的 dogfooding。
+- **refuter 反驳掉 2 个 CRITICAL/HIGH** 是对抗式审查的价值证明：单 reviewer 视角会基于错误假设（JS 并发模型、React ref 语义）报假阳性，多一层反驳能纠偏。
+
+完整 journal（10 条 agent 输出）：`.claude/workflow-runs/wtujwahzf/journal.jsonl`
--- a/docs/superpowers/specs/2026-06-12-workflow-engine-design.md
+++ b/docs/superpowers/specs/2026-06-12-workflow-engine-design.md
@@ -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 阶段补一个最小版本。
--- a/docs/superpowers/specs/2026-06-13-workflow-panel-redesign.md
+++ b/docs/superpowers/specs/2026-06-13-workflow-panel-redesign.md
@@ -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 却没调用）。
--- a/docs/superpowers/specs/2026-06-13-workflow-tui-ultracode-design.md
+++ b/docs/superpowers/specs/2026-06-13-workflow-tui-ultracode-design.md
@@ -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 级预算。