claude-code/docs/superpowers/specs/2026-06-13-workflow-tui-ultracode-design.md

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 猜匹配。改为：

// 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

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：

// 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 级预算。