feat: dynamic-workflow 来了 (#1271)

* 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> * feat(workflow): 复刻 ultracode 手册并修复 worktree/inline/opt-in 三处缺口围绕 ultracode skill 审查 agent 系统一致性后： - ultracode.ts: 用系统提示版完整 Workflow 编排手册替换中文精简版 - HIGH#1 isolation:'worktree': claudeCodeBackend.run() 用 createAgentWorktree + runWithCwdOverride 包裹 runAgent + finally 清理实现真正的 cwd 隔离；slug 用 sha256(runId:agentId) 派生以匹配 cleanupStaleAgentWorktrees 清理正则（修 runId 为 w+base36 非 UUID 导致的泄漏盲区）；worktree.ts 注释同步修正 - HIGH#2 inline 持久化: 新增 persistInlineScript，WorkflowTool + service 两条 inline 路径对称持久化到 .claude/workflow-runs/<runId>/script.js，返回可复用 scriptPath（闭环 inline→编辑→scriptPath 重提迭代循环） - HIGH#3 opt-in 分工: ultracode/WorkflowTool/effort 注明 session reminder 由 harness 注入，repo 内无 ultracode 信号，保持 feature('WORKFLOW_SCRIPTS') + isEnabled 两层 gate，不自造注入 - 测试: 新增 persistInline.test.ts；扩展 claudeCodeBackend(isolation 4 用例)/ WorkflowTool(inline)/service(scriptPath)/ultracode(harness) 含配套 workflow engine/panel 完善与 run-state-persistence design doc。 Co-Authored-By: Claude <noreply@anthropic.com> * feat(workflow): run 终态落盘 state.json 支持跨重启恢复终态 RunProgress（含 returnValue/error）此前只在内存 ProgressStore，进程重启即丢失。本次让其落盘到 .claude/workflow-runs/<runId>/state.json，使 (a) 重启后可按 runId 取 return、(b) /workflows 面板跨重启展示历史 run。跨进程 resume 明确不在范围。 - persistence.ts: getRunsDir/writeRunState/readRunState/listPersistedRuns + attachRunStatePersistence；原子覆盖写（tmp+rename），读容错（缺文件/ 损坏/schemaVersion 不符 → null），写 best-effort（IO 失败只 log warn） - progress/store.ts: 加 hydrate(run) 直接注入磁盘 run（已存在 runId 跳过，内存优先） - service.ts: getWorkflowService() 接线 attachRunStatePersistence(bus, store) 订阅 run_done（completed/failed/killed 三态共用，shutdown-kill 也走同路径，无需额外钩子）；WorkflowService 加 getRunAsync(id) 内存 miss→读盘 fallback（不注入内存）+ loadPersistedRuns() 扫盘 hydrate （persistedLoaded flag 守护幂等） - panel/WorkflowsPanel.tsx: mount 时调一次 loadPersistedRuns（重 mount 不重复） - ports.ts: runsDir 改用 getRunsDir() 消除拼接重复 - 测试: persistence.test.ts(11)/runStatePersistence.test.ts(5)/ progressStore(2)/service(5)/WorkflowsPanel(1) 共 24 个新测试； precheck 5629 pass / 0 fail 设计偏离: 计划原写 monkey-patch getRunsDir 指向 tmpdir，Bun ESM namespace 不可变不可行；改用可选 runsDirProvider 参数（默认 getRunsDir）DI 注入，加到 attachRunStatePersistence 与 makeService（cwdOverride 之后第 4 参），与现有 cwdOverride 模式一致。makeService 的 cwdOverride 保持不变，不破坏 inline 持久化特性。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * feat(workflow): 默认并发降为 3 并支持 per-run maxConcurrency 注入 - DEFAULT_MAX_CONCURRENCY=3 替代旧的 min(16, cores-2)；MAX_CONCURRENCY_CAP=16 保留为用户输入的绝对上限 - 新增 clampMaxConcurrency() 处理 undefined/<1/>CAP 边界 - WorkflowInput schema 新增 maxConcurrency: number.int().min(1).max(16).optional() - 引擎层 context/runWorkflow 全链路透传：semaphore 容量来自 per-run 入参 - WorkflowTool prompt 增加指引：fan-out 场景先用 AskUserQuestion 与用户确认并发再启动 - 同步 ultracode skill + audit workflow spec 的并发文字（删 cpu-cores 公式） - 同步 docs/features/workflow-scripts.md 旧公式 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * fix(workflow): 面板 UI 字符串英文化 WorkflowsPanel 中 4 处面向用户的中文（onDone 错误消息、键位提示行）改为英文；其他面板组件（AgentList/TabsBar）原本已是英文。代码注释保留中文，与 workflow 模块惯例一致。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * feat(workflow): 中断系统（x 杀单 agent / K 杀整个 workflow，Dialog 二次确认） - claudeCodeBackend 桥接 ctx.signal → runAgent.override.abortController（修 'x' 无效根因：abort 到不了内部 fetch） - AbortError 识别为 throw WorkflowAbortedError（不再吞成 dead，workflow 能感知被 kill） - ports.taskRegistrar 加 registerAgentAbort/unregisterAgentAbort/killAgent；service.killAgent(runId, agentId) 精确中断 - 面板键位：'x' 杀当前 agent（agents 列聚焦时） / 'K' 杀整个 workflow；Dialog 二次确认 + confirm 模式吞导航键防误触 - 新增测试 8 项（backend signal bridge / hooks inject / ports killAgent / service killAgent） Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * docs(workflow): ultracode skill 加 model tier 选择指引（haiku/sonnet/opus/best 场景匹配）补足 agent() 已有 model 参数缺的判断依据：列出 4 个 tier 的成本/延迟量级和典型场景，明确"无法 articulate 为什么换 tier 就 omit"的 rule of thumb。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * feat(workflow): maxConcurrency≠3 必须先 AskUserQuestion（默认 3 推荐值）把 fan-out 时才问改成任何 maxConcurrency≠3 都必须问。唯一例外：用户在当前会话已明确说过并发数（"use 6" / "maxConcurrency 9"）。 prompt (WorkflowTool.ts) + skill (ultracode.ts) + audit spec 三处同步。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * feat(workflow): agent 失败自动重试一次（dead 或非 abort throw） - hooks.agent 包装 invokeBackend：第一次 dead 或非 abort throw → 重试一次 - WorkflowAbortedError（kill）不重试——是用户意图 - registry.resolve 配置错（AdapterNotFoundError 等）在 try 外直接上抛，不走重试—— 配置问题重试无意义且掩盖 bug - 重试仍失败：dead 保持 dead；throw 降级 dead（不击穿 workflow，与 parallel/pipeline null-on-error 契约一致） - budget 不重复扣：dead 不 addOutputTokens，重试 ok 才扣一次 - 新增 7 项 hooks 层重试测试 + 1 项 service 层降级测试 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * fix(workflow): 面板 label 截断保留 #数字后缀（同 dim 多 finding 可区分） audit workflow 用 verify:\${dim}#\${findingIdx} 命名 verify agent。旧逻辑 slice(0, 18) 从右切把 #idx 全吃了——同 dimension 多 finding 肉眼无法区分。新逻辑：含 #数字后缀时保留后缀，前缀截断 + … 省略号。例：verify:correctness#0 → verify:correctn…#0 verify:architecture#15 → verify:archite…#15 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * feat(workflow): kill 整个 workflow 后立即回主 chat run_done→store→notifications.ts 的通知路径已有，但 confirmYes 后面板继续挂着挡住主 chat，用户看不到"已停止"反馈。kill 后调 onDone() 立即退出面板，让主 chat 的 `Workflow "<name>" was stopped` 通知直接可见。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * fix(workflow): agent dead 带 reason/detail + prompt 加压 StructuredOutput 12 agent audit workflow 8 个 dead，journal 只记 {kind:"dead"} 无信息，事后无法区分 "agent 没产 StructuredOutput" vs "runAgent 抛错"。证据指向主因：sonnet 长 tool chain 后忘记调 StructuredOutput， extractStructuredOutput 返回 null 即降级 dead。 - types.ts: AgentRunResult.dead 加可选 reason/detail 字段（no-structured-output / runagent-threw / worktree-failed / unknown）兼容旧 journal（均 optional）。 - claudeCodeBackend.ts: 三处 dead 填 reason + detail； no-structured-output 把 finalized 文本前 200 字符做 detail，让日志/面板能立刻看到 agent 最后说了什么。 - claudeCodeBackend.ts: schema 模式 prompt 首尾各放一次 StructuredOutput 强制要求，针对 sonnet 长 tool chain 后忘记收尾。 - hooks.ts: retry 日志带 reason；retry 仍 throw 时降级 dead 也填 reason=runagent-threw + detail。 - types.test.ts: 加 reason JSON 往返 + 旧 journal 兼容测试。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * fix(workflow): schema 模式弃用 StructuredOutput 工具契约，改鲁棒 JSON 文本解析上一轮 70a2f76 把"agent 长 tool chain 后忘调 StructuredOutput"当作死因，加 prompt 头尾双强制。但实测跑 5 个 review agent 4 个 dead，detail 全是 "StructuredOutput tool is not available as a deferred tool"——根因是该工具从未注入 workflow sub-agent 的工具集（assembleToolPool 默认池不含，只有 stop_hook 路径 execAgentHook.ts 显式 createStructuredOutputTool()）。 prompt 反复要求调一个不可达的工具，agent 困扰、长篇辩解、最终没产 JSON。 - claudeCodeBackend.ts: - extractStructuredOutput 重写：括号栈扫描替代 indexOf/lastIndexOf，处理嵌套对象、字符串内的括号、转义符；新增 fenced code block 优先路径（```json / ```），多 JSON 块取第一个 parse 成功的；只返回 plain object（拒 array/number/string/null）。不做语法修复（尾逗号/单引号/注释）——避免在字符串内误改（如 "http://" 被 // 注释正则吃）。 - schema 模式 prompt 简化：删首尾双 STRUCTURED OUTPUT 强制（600+ token），改成指示 agent 在最后文本块 emit raw JSON；明确告知"StructuredOutput is not available in this environment"，消除调用幻觉。 - hooks.ts: detail.slice 用 typeof === 'string' 守卫；catch 块用 e instanceof Error ? e.message : String(e)（旧 journal / 第三方 adapter 可能写非 string detail，直接 .slice 会抛 TypeError 击穿日志）。 - claudeCodeBackend.test.ts: +9 测试覆盖 fenced / 嵌套 / 字符串内括号 / 转义引号 / 多块取首 / 类型守卫 / 损坏 JSON。 precheck: 5663 pass / 0 fail。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * docs(effort): 新增 /effort 交互面板设计 spec 设计要点： - /effort 无参 → 横向 slider 面板（low/medium/high/xhigh/max/ultracode） - ←/→ 移动光标，Enter 确认，Esc 取消 - ultracode 仅视觉占位，确认后提示走 /ultracode <context> - env override 时双标记 + 顶部警告 - 模型不支持时面板禁用 - 两阶段交付：先基础面板 commit，再做 ultracode 波纹动画 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * docs(effort): 新增 EffortPanel 基础面板实施计划（第一阶段）按 TDD 分 6 个 task：纯函数状态 → keybinding 注册 → 组件 → 命令挂载 → 分支测试 → precheck。波纹动画在第二阶段单独 commit。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * docs(effort): plan 补 q/ctrl+c 取消绑定，对齐 spec §5 状态机 verifier 抓到的 gap：spec §5 写明 Esc / Ctrl+C / q 都是取消事件，但 plan Task 2.3 只绑了 escape。补上 q 和 ctrl+c → effortPanel:cancel。同时把 Step 2.2 直接写成 6 个 action 版本（home/end），删除迂回表达。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * docs(effort): plan 修订执行前 review 发现的 5 处 gap - Task 3.3 EffortPanel.tsx 草稿：Faster/Smarter padEnd 语法错乱重写； useKeybindings import 路径从 @anthropic/ink 修正为 ../../keybindings/useKeybinding.js；移除冗余 renderSeparatorLine；保留 renderPaddedLine - Task 5.2 computeConfirmOutcome 改为注入 ApplyFn 模式：避免 effortPanelState → effort.tsx → EffortPanel 循环依赖；测试可注入 mockApply，无需 mock settings - Step 5.3 测试代码对齐注入版签名 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * feat(effort): 新增 EffortPanel 纯函数状态模块（PanelPosition + 移动/初始光标）仅含纯函数与类型，无 React/Ink 依赖，便于单测。 - PANEL_POSITIONS：low → medium → high → xhigh → max → ultracode - moveLeft/moveRight：边界钳制（low 不再左移、ultracode 不再右移） - getInitialCursor：env override > displayed level Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * feat(keybindings): 注册 EffortPanel context 与 6 个 action 绑定 ←/→/h/l/home/end/enter/escape/q/ctrl+c 到 effortPanel:* action。与 ModelPicker context 范式一致，避免左右键被全局 keybinding 拦截。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * feat(effort): 实现 EffortPanel 组件主体（渲染 + 键盘交互 + 确认/取消分支） - 横向 slider 布局：Faster ↔ Smarter 两极，6 档刻度 - useKeybindings 注册 EffortPanel context（←/→/h/l/home/end/enter/escape/q/ctrl+c） - Enter 在 5 档之一 → 调 executeEffort 写 settings + AppState - Enter 在 ultracode → 输出引导文案，不写状态 - Esc/q → "Effort unchanged." - env override 时顶部黄色警告 - computeConfirmOutcome 注入 ApplyFn，便于测试（Task 5 补测试） Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * feat(effort): /effort 无参时挂载 EffortPanel 交互面板 - 无参 → <EffortPanelWrapper> 透传 AppState.effortValue - current/status → 仍显示文本（不变） - 有参 → 直跳 executeEffort（不变） - help/-h/--help → 不变 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * test(effort): 补 computeConfirmOutcome 分支测试（注入 mockApply） - ultracode → kind=ultracode-hint，不调 applyFn - low → kind=apply，message/effortUpdate 来自 applyFn - applyFn 返回无 effortUpdate 时 outcome.effortUpdate 为 undefined - CANCEL_MESSAGE / ULTRACODE_HINT 常量 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * fix(effort): 测试里 cursor cast 为 EffortValue，避免 PanelPosition 含 ultracode 触发 TS 错误 computeConfirmOutcome 的 ApplyFn 契约要求 EffortValue，但测试 mockApply 接收 PanelPosition。实际运行时 computeConfirmOutcome 在 ultracode 档位走 hint 分支不会调 applyFn， cast 安全。precheck 全量通过：5688 tests / 0 fail。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * fix(effort): 面板对齐与配色修复 - 对齐：用 Box width={SEGMENT} + justifyContent="center" 让 ▲ 与档位名严格居中对齐，替代之前 string padEnd(11) 与 SEGMENT=12 不一致导致的 1 列偏移 - 配色：所有面板文字改用 theme.claude（Claude Orange rgb(215,119,87)），替代终端默认紫；分隔线/副标签/底栏用 theme.subtle；env 警告用 theme.warning - 光标档位的档位名也加粗，强化视觉焦点 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * fix(effort): 面板文字改紫色，ULTRACODE_HINT 英文化 - 颜色：theme.claude（橙）→ theme.purple_FOR_SUBAGENTS_ONLY（Purple 600, rgb(147,51,234)），覆盖标题、Faster/Smarter、▲、档位名 - ULTRACODE_HINT：中文 → 英文 "ultracode is not an effort level. Use /ultracode <context> to start a multi-agent workflow." Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * fix(effort): 统一用色版——选中 suggestion（蓝），未选中 subtle（灰）弃用 purple_FOR_SUBAGENTS_ONLY（subagent 专用）。改与项目其他面板一致： - 选中档位 + ▲：color="suggestion"（Medium blue rgb(87,105,247)）+ bold - 未选中档位 + 空 ▲ 占位：color="subtle"（Light gray rgb(175,175,175)） - 标题 / Faster / Smarter：color="suggestion" - 分隔线 / 副标签 / 底栏：color="subtle" Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * fix(workflow): 终态前补发 phase_done，面板自动退出 running→terminal 转换 runWorkflow：脚本结束时 hook.phase 不会触发最后一个 phase 的 phase_done， UI 左栏会永远显示 running。三路径（completed/killed/failed）统一在 run_done 之前补发 emitTerminalPhaseDone。 WorkflowsPanel：抽 isRunTerminatedTransition 纯函数判定 running → terminal，面板 useEffect 检测到转换后自动退出聚焦。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * feat(effort): 波纹动画纯函数 pickChar/computeRippleLine/mergeLayers + 18 测试 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * feat(effort): useRippleFrame hook 包装 useAnimationFrame，按需订阅时钟 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * feat(effort): EffortPanel 集成波纹背景——cursor 停在 ultracode 时切换波纹模式仅在 cursor === 'ultracode' 时启用 useRippleFrame，渲染 5 行波纹背景 + overlay 文字（Faster/Smarter、分隔线、▲、档位名、副标签）。其余档位保持原 PlainContent 渲染路径不动。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * refactor(effort): 波纹动画从字符密度改为颜色渐变按原版风格把波纹背景从 INTENSITY_CHARS 密度字符（'·∙░▒▓'）改为 suggestion 系颜色渐变（transparent → 暗深紫蓝 → suggestion → 高光）： rippleAnimation.ts: - 删除 pickChar / INTENSITY_CHARS / WAVE_PEAK_CHARS / mergeLayers - 新增 intensityToColor(intensity) → 'transparent' | '#xxxxxx' - 新增 computeRippleCells 返回 Cell[]（每位置 char+color） - 新增 applyOverlaysToCells(cells, overlays) 替代 mergeLayers - 新增 cellsToSegments(cells) 合并相邻同色段（减少 Text 节点） EffortPanel.tsx: - RippleContent 用 cells→segments→tokens 渲染 - 空格段用 BaseText backgroundColor 染色块（纯色块视觉） - 文字段用 Text color 染色（亮色突出） - tokens 按空格/文字二次拆分，避免混合段渲染歧义测试: 29 个 rippleAnimation 测试覆盖 intensityToColor 边界、 computeRippleCells 长度/震源/衰减、applyOverlaysToCells 覆盖/截断/ 防御式拷贝、cellsToSegments 合并逻辑。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * fix(effort): 波纹参数调优——铺满左侧 + 速度调慢 + 全面板有底色用户反馈三个问题： 1. "低峰部分没有颜色变化" → intensity ≤ 0.1 返回 transparent 导致波谷位置看不见。改为永不返回 transparent，最低档 #0a0d1a 作为面板底色（暗紫黑海洋），波峰在底色上流动。 2. "波浪速度太快" → time 系数 0.012 → 0.004（约 1/3 速）。波峰移动速度从 34 cell/s 降到 11 cell/s，每帧颜色变化从 45% 降到 36%。 3. "波浪只到中间部分，没覆盖左侧" → falloff 覆盖半径 40 → 90。震源 x=65，左侧 dist=65 < 90，波纹可达最左端（约 30-50% 覆盖）。色阶调整： - 删除 transparent 档，新增 #0a0d1a 作最暗档（底色） - 最高档从 #8aa0ff（高光）改为 #5769F7（suggestion），避免与文字 overlay 同色互相吞噬 - 7 档颜色：#0a0d1a → #15182b → #1f2543 → #2a3360 → #3a4582 → #4a5bb0 → #5769F7 测试：删除 transparent 期望，改为期望具体颜色（#0a0d1a 等）。新增"覆盖半径扩大"测试验证 dist=65 仍有非最暗颜色。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * fix(effort): 波纹 v3 — 去黑边 + 删中心高频涟漪 + y 轴覆盖快捷键行用户反馈三个问题： 1. "黑色边感觉不太对" — 最暗档 #0a0d1a (rgb 10,13,26) 太接近纯黑，远端波谷看起来像硬黑边。改为 #1a1f3a (rgb 26,31,58)，紫蓝感更强而非纯黑。 2. "中心的快速波纹有点奇怪" — 删除震源附近 dist<6 的高频涟漪叠加 (time*0.02，5 倍主波纹频率)。原本想让震源附近"水波感"更强，实际效果像"快速闪烁"反而突兀。主波纹已经足够，无需叠加。 3. "y 方向覆盖快捷键" — RippleContent 新增 y=2 行渲染快捷键 overlay ("←/→ adjust · Enter confirm · Esc cancel")。PlainContent 路径保持原 Box marginTop=1 + Text 渲染。色阶调整（紫蓝感更强）： - #1a1f3a (原 #0a0d1a) — 最暗档 - #1f2543 / #252c55 / #2e3870 / #3a4582 / #4a5bb0 / #5769F7 (中间档略调亮度，保持平滑过渡) 测试：震源点测试更新为"time=0 时波谷最暗，time 推进后扫过波峰变亮"，反映删除高频涟漪后的纯主波纹行为。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * chore(workflow): 工作流相关代码中文文案全部英文化源码（src/workflow/ + packages/workflow-engine/src/）的中文注释、用户可见错误消息、字符串字面量；测试文件的标题与注释；同步 6 条硬编码断言到英文化后的错误消息。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * feat(effort): 波纹 v4 — 平滑波 + 全色环旋转 + 淡入淡出 + 宽度自适应 - 波函数改 (sin+1)/2：消除 max(0,sin) 平直暗带（约 6 行宽） - 主色相连续旋转（0.03°/ms，12s/圈全色环）：蓝→紫→品红→红→橙→黄→绿→青 - 文字 overlay 同步色相旋转（rotateHue 应用到 Faster/▲/档位名/分隔线/副标签） - 淡入淡出动画：fadeColor/fadeCells + fade 状态机 ~300ms 进出过渡 - 副标签固定 ultracode 段下方，不跟随光标移动 - 顶部/底部各加一行纯波纹行，视觉一致 - 宽度自适应终端列数：窄则 72，宽则铺满（computeSegment/computeRippleSourceX） - 快捷键改 plain Text，不参与波纹背景渲染 - 新增 18 测试（fadeColor/fadeCells/rotateHue/getHueShiftAtTime） Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win> * refactor: remove CYBER_RISK_MITIGATION_REMINDER from FileReadTool Co-Authored-By: deepseek-v4-pro <deepseek-ai@claude-code-best.win> * fix: prevent ReDoS in extractMeta regex by anchoring to splice boundary Co-Authored-By: deepseek-v4-pro <deepseek-ai@claude-code-best.win> * chore: 更新脚本 --------- Co-authored-by: glm-5.1 <zai-org@claude-code-best.win> Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: deepseek-v4-pro <deepseek-ai@claude-code-best.win>
2026-06-15 12:55:51 +00:00 · 2026-06-14 18:13:49 +08:00
parent 3e3e1de81b
commit 58ee6419b1
130 changed files with 23347 additions and 885 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 默认 = `DEFAULT_MAX_CONCURRENCY`（3），可经 Workflow 工具的 `maxConcurrency` 入参覆盖，绝对上限 `MAX_CONCURRENCY_CAP`（16）。
+
+## 四、编写 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` 默认许可 3（`DEFAULT_MAX_CONCURRENCY`），可经 Workflow 工具的 `maxConcurrency` 入参 per-run 覆盖（钳到 `[1, MAX_CONCURRENCY_CAP=16]`）。
+- **错误**：脚本语法/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-run-state-persistence.md
+++ b/docs/superpowers/plans/2026-06-13-workflow-run-state-persistence.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/plans/2026-06-14-effort-panel-basic.md
+++ b/docs/superpowers/plans/2026-06-14-effort-panel-basic.md
@@ -0,0 +1,897 @@
+# EffortPanel 基础面板实施计划（第一阶段）
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 把 `/effort` 无参调用升级为横向 slider 选择面板，覆盖 `low/medium/high/xhigh/max/ultracode` 六档，`←/→` 移动光标、`Enter` 确认、`Esc` 取消。
+
+**Architecture:** 新增自包含 `EffortPanel` React 组件 + 纯函数状态模块；键盘交互走项目既有的 `useKeybindings` + 自定义 `EffortPanel` keybinding context（与 `ModelPicker` 范式一致）；不修改 `src/utils/effort.ts`，复用其纯函数；改造 `src/commands/effort/effort.tsx` 的 `call()`，仅无参时挂载面板。
+
+**Tech Stack:** Bun + TypeScript + React (Ink via `@anthropic/ink`) + `bun:test` + Biome
+
+**Spec:** `docs/superpowers/specs/2026-06-14-effort-panel-design.md`
+
+**范围：** 仅第一阶段（基础面板 + 键盘交互 + env override 警告 + ultracode 文案分支）。波纹动画在第二阶段单独 commit，不在本计划内。
+
+---
+
+## 文件结构
+
+| 文件 | 状态 | 责任 |
+|---|---|---|
+| `src/components/EffortPanel/effortPanelState.ts` | 新增 | `PanelPosition` 类型 + 纯函数（`moveLeft`/`moveRight`/`home`/`end`/`getInitialCursor`/`PANEL_POSITIONS`），可独立单测 |
+| `src/components/EffortPanel/EffortPanel.tsx` | 新增 | 面板 React 组件：渲染布局 + `useKeybindings` + Enter/Esc 分支 + 调 `executeEffort` |
+| `src/components/EffortPanel/__tests__/effortPanelState.test.ts` | 新增 | 纯函数单测 |
+| `src/components/EffortPanel/__tests__/EffortPanel.test.tsx` | 新增 | 组件渲染 + 分支测试 |
+| `src/keybindings/schema.ts` | 修改 | 在 `KeybindingAction` 联合类型里追加 4 个 `effortPanel:*` action |
+| `src/keybindings/defaultBindings.ts` | 修改 | 追加 `EffortPanel` context 绑定（`←/→/enter/escape/home/end`）|
+| `src/keybindings/__tests__/`（如已有 schema/defaultBindings 测试）| 修改（如有） | 追加新 context 的回归断言 |
+| `src/commands/effort/effort.tsx` | 修改 | `call()` 在 `args === ''` 时返回 `<EffortPanel>`；其他路径不变 |
+
+**不修改的文件：** `src/utils/effort.ts`、`src/commands/effort/index.ts`、`src/state/AppState.tsx`。
+
+---
+
+## Task 1：纯函数状态模块（TDD）
+
+**Files:**
+- Create: `src/components/EffortPanel/effortPanelState.ts`
+- Test: `src/components/EffortPanel/__tests__/effortPanelState.test.ts`
+
+- [ ] **Step 1.1: 写失败测试（基础导出与边界）**
+
+Create `src/components/EffortPanel/__tests__/effortPanelState.test.ts`:
+
+```ts
+import { describe, expect, test } from 'bun:test'
+import {
+  END_POSITION,
+  HOME_POSITION,
+  PANEL_POSITIONS,
+  type PanelPosition,
+  getInitialCursor,
+  isUltracode,
+  moveLeft,
+  moveRight,
+} from '../effortPanelState.js'
+
+describe('effortPanelState', () => {
+  test('PANEL_POSITIONS 顺序为 low → ultracode', () => {
+    expect(PANEL_POSITIONS).toEqual([
+      'low',
+      'medium',
+      'high',
+      'xhigh',
+      'max',
+      'ultracode',
+    ])
+  })
+
+  test('moveLeft 在 low 处保持 low', () => {
+    expect(moveLeft('low')).toBe('low')
+  })
+
+  test('moveLeft 正常左移', () => {
+    expect(moveLeft('high')).toBe('medium')
+    expect(moveLeft('ultracode')).toBe('max')
+  })
+
+  test('moveRight 在 ultracode 处保持 ultracode', () => {
+    expect(moveRight('ultracode')).toBe('ultracode')
+  })
+
+  test('moveRight 正常右移', () => {
+    expect(moveRight('medium')).toBe('high')
+    expect(moveRight('max')).toBe('ultracode')
+  })
+
+  test('HOME_POSITION 等于 low', () => {
+    expect(HOME_POSITION).toBe('low')
+  })
+
+  test('END_POSITION 等于 ultracode', () => {
+    expect(END_POSITION).toBe('ultracode')
+  })
+
+  test('isUltracode 守卫', () => {
+    expect(isUltracode('ultracode')).toBe(true)
+    expect(isUltracode('max')).toBe(false)
+  })
+
+  test('getInitialCursor：env override 存在时返回 env 值（若是合法档位）', () => {
+    expect(getInitialCursor({ envOverride: 'high', appStateEffort: 'medium', displayed: 'high' })).toBe('high')
+  })
+
+  test('getInitialCursor：env 为 null（unset）时用 displayed', () => {
+    expect(getInitialCursor({ envOverride: null, appStateEffort: undefined, displayed: 'medium' })).toBe('medium')
+  })
+
+  test('getInitialCursor：env undefined 时用 displayed', () => {
+    expect(getInitialCursor({ envOverride: undefined, appStateEffort: 'high', displayed: 'high' })).toBe('high')
+  })
+
+  test('getInitialCursor：env 是数值（ant-only）时落回 displayed', () => {
+    // 数值不是合法 PanelPosition，回退
+    expect(getInitialCursor({ envOverride: 75, appStateEffort: 'medium', displayed: 'medium' })).toBe('medium')
+  })
+
+  test('PanelPosition 类型编译期检查（隐式）', () => {
+    const p: PanelPosition = 'xhigh'
+    expect(p).toBe('xhigh')
+  })
+})
+```
+
+- [ ] **Step 1.2: 运行测试，确认失败**
+
+Run: `bun test src/components/EffortPanel/__tests__/effortPanelState.test.ts`
+Expected: FAIL，错误形如 `Cannot find module '../effortPanelState.js'`
+
+- [ ] **Step 1.3: 实现纯函数模块**
+
+Create `src/components/EffortPanel/effortPanelState.ts`:
+
+```ts
+import type { EffortValue } from '../../../utils/effort.js'
+
+/**
+ * 光标在面板上的位置。仅面板内部使用，不进入 AppState / settings / API。
+ * 'ultracode' 不是 EffortLevel；它在本面板里仅作视觉占位与文案引导。
+ */
+export type PanelPosition =
+  | 'low'
+  | 'medium'
+  | 'high'
+  | 'xhigh'
+  | 'max'
+  | 'ultracode'
+
+export const PANEL_POSITIONS: readonly PanelPosition[] = [
+  'low',
+  'medium',
+  'high',
+  'xhigh',
+  'max',
+  'ultracode',
+] as const
+
+export const HOME_POSITION: PanelPosition = 'low'
+export const END_POSITION: PanelPosition = 'ultracode'
+
+const NON_ULTRACODE_POSITIONS: readonly PanelPosition[] = PANEL_POSITIONS.filter(
+  p => p !== 'ultracode',
+)
+
+/**
+ * 判断一个 EffortValue 是否可作为面板光标位置。
+ * 数值（ant-only）和 ultracode 都不是合法 PanelPosition（ultracode 由面板内部产生）。
+ */
+function isPanelPosition(value: unknown): value is PanelPosition {
+  return typeof value === 'string' && (PANEL_POSITIONS as readonly string[]).includes(value)
+}
+
+/**
+ * 把非 ultracode 的 string EffortValue 收窄为 PanelPosition 的前 5 档。
+ * 用于 env override 与 appState 的归一化。
+ */
+function normalizeToPanelPosition(value: EffortValue | null | undefined): PanelPosition | undefined {
+  if (value === null || value === undefined) return undefined
+  if (typeof value === 'number') return undefined
+  if (isPanelPosition(value) && value !== 'ultracode') {
+    return value
+  }
+  return undefined
+}
+
+export function moveLeft(cursor: PanelPosition): PanelPosition {
+  const idx = PANEL_POSITIONS.indexOf(cursor)
+  if (idx <= 0) return PANEL_POSITIONS[0]
+  return PANEL_POSITIONS[idx - 1]
+}
+
+export function moveRight(cursor: PanelPosition): PanelPosition {
+  const idx = PANEL_POSITIONS.indexOf(cursor)
+  if (idx === -1 || idx >= PANEL_POSITIONS.length - 1) {
+    return PANEL_POSITIONS[PANEL_POSITIONS.length - 1]
+  }
+  return PANEL_POSITIONS[idx + 1]
+}
+
+export function isUltracode(cursor: PanelPosition): boolean {
+  return cursor === 'ultracode'
+}
+
+/**
+ * 决定面板挂载时的初始光标位置。
+ * 优先级：env override（若是合法档位）> displayed level（已是 fallback 'high' 之后）
+ *
+ * @param envOverride    getEffortEnvOverride() 的返回值：EffortValue | null | undefined
+ * @param appStateEffort AppState.effortValue
+ * @param displayed      getDisplayedEffortLevel(model, appStateEffort) —— 必传，避免此处再依赖 model
+ */
+export function getInitialCursor(args: {
+  envOverride: EffortValue | null | undefined
+  appStateEffort: EffortValue | undefined
+  displayed: PanelPosition
+}): PanelPosition {
+  const fromEnv = normalizeToPanelPosition(args.envOverride)
+  if (fromEnv !== undefined) return fromEnv
+  // displayed 已经是 EffortLevel（不含 ultracode），合法
+  return args.displayed
+}
+
+// 保留导出，便于将来测试扩展
+export { NON_ULTRACODE_POSITIONS }
+```
+
+- [ ] **Step 1.4: 运行测试，确认通过**
+
+Run: `bun test src/components/EffortPanel/__tests__/effortPanelState.test.ts`
+Expected: PASS（所有 11 个 test 通过）
+
+- [ ] **Step 1.5: 类型 + lint 检查**
+
+Run: `bunx tsc --noEmit && bunx biome check src/components/EffortPanel/`
+Expected: 0 errors
+
+- [ ] **Step 1.6: Commit**
+
+```bash
+git add src/components/EffortPanel/effortPanelState.ts src/components/EffortPanel/__tests__/effortPanelState.test.ts
+git commit -m "$(cat <<'EOF'
+feat(effort): 新增 EffortPanel 纯函数状态模块（PanelPosition + 移动/初始光标）
+
+仅含纯函数与类型，无 React/Ink 依赖，便于单测。
+- PANEL_POSITIONS：low → medium → high → xhigh → max → ultracode
+- moveLeft/moveRight：边界钳制（low 不再左移、ultracode 不再右移）
+- getInitialCursor：env override > displayed level
+
+Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win>
+EOF
+)"
+```
+
+---
+
+## Task 2：注册 EffortPanel keybinding context
+
+**Files:**
+- Modify: `src/keybindings/schema.ts`（在 `KeybindingAction` 联合类型追加 6 个 action）
+- Modify: `src/keybindings/defaultBindings.ts`（追加 `EffortPanel` context 块）
+
+- [ ] **Step 2.1: 检查 schema.ts 现有结构与校验测试**
+
+Run: `grep -n "modelPicker:" src/keybindings/schema.ts`
+Expected: 看到三行 `modelPicker:decreaseEffort/increaseEffort/toggle1M`，附近就是合适的插入位置。
+
+Run: `ls src/keybindings/__tests__/ 2>/dev/null`
+Expected: 查看是否有 schema/defaultBindings 的回归测试文件（决定是否需要补断言）。
+
+- [ ] **Step 2.2: 在 schema.ts 追加 6 个 action**
+
+打开 `src/keybindings/schema.ts`，找到 `// Model picker actions (ant-only)` 块（约 line 153-156），在它**后面**追加：
+
+```ts
+  // Effort panel actions (slash /effort without args)
+  'effortPanel:decrease',
+  'effortPanel:increase',
+  'effortPanel:home',
+  'effortPanel:end',
+  'effortPanel:confirm',
+  'effortPanel:cancel',
+```
+
+- [ ] **Step 2.3: 在 defaultBindings.ts 追加 EffortPanel context**
+
+打开 `src/keybindings/defaultBindings.ts`，找到 `ModelPicker` 块（约 line 320-328），在它**后面**（`Select` 块之前）追加：
+
+```ts
+  // Effort panel (slash /effort without args)
+  {
+    context: 'EffortPanel',
+    bindings: {
+      left: 'effortPanel:decrease',
+      right: 'effortPanel:increase',
+      h: 'effortPanel:decrease',
+      l: 'effortPanel:increase',
+      home: 'effortPanel:home',
+      end: 'effortPanel:end',
+      enter: 'effortPanel:confirm',
+      escape: 'effortPanel:cancel',
+      q: 'effortPanel:cancel',
+      'ctrl+c': 'effortPanel:cancel',
+    },
+  },
+```
+
+注意：
+- `q` 与 `escape` / `ctrl+c` 都映射到 `effortPanel:cancel`，与 spec §5 状态机一致。
+- Ink 的 useInput 默认在 ctrl+c 时退出进程；但项目 useKeybindings 系统会先拦截 ctrl+c（参考 `useInput` 源码中 `if (!(input === 'c' && key.ctrl) || !internal_exitOnCtrlC)` 分支）。若实施时发现 ctrl+c 仍直接退出进程，**降级为只绑 q + escape**，并在 commit message 里注明。
+- Step 2.2 的 6 个 action（含 `home/end`）与此处的 8 个绑定一一对应。
+
+- [ ] **Step 2.4: 类型 + lint 检查**
+
+Run: `bunx tsc --noEmit`
+Expected: 0 errors（如果 schema 校验是 type-level 的，新增 action 会被识别）
+
+Run: `bun test src/keybindings/ 2>/dev/null`
+Expected: 已有测试不破。
+
+- [ ] **Step 2.5: Commit**
+
+```bash
+git add src/keybindings/schema.ts src/keybindings/defaultBindings.ts
+git commit -m "$(cat <<'EOF'
+feat(keybindings): 注册 EffortPanel context 与 6 个 action
+
+绑定 ←/→/h/l/home/end/enter/escape 到 effortPanel:* action。
+与 ModelPicker context 范式一致，避免左右键被全局 keybinding 拦截。
+
+Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win>
+EOF
+)"
+```
+
+---
+
+## Task 3：实现 EffortPanel React 组件
+
+**Files:**
+- Create: `src/components/EffortPanel/EffortPanel.tsx`
+- Create: `src/components/EffortPanel/__tests__/EffortPanel.test.tsx`
+
+- [ ] **Step 3.1: 写失败测试（渲染基础形态）**
+
+Create `src/components/EffortPanel/__tests__/EffortPanel.test.tsx`:
+
+```tsx
+import { describe, expect, mock, test } from 'bun:test'
+import React from 'react'
+import { render } from '../../../test-utils/ink-render.js'
+import { EffortPanel } from '../EffortPanel.js'
+
+// 复用项目共享 mock（避免 bootstrap/state 副作用）
+mock.module('src/utils/log.ts', () => {
+  const { logMock } = require('../../../../tests/mocks/log')
+  return logMock()
+})
+
+const baseProps = {
+  model: 'claude-opus-4-7',
+  appStateEffort: undefined as undefined | string,
+  onDone: () => {},
+}
+
+describe('EffortPanel 渲染', () => {
+  test('显示标题 Effort、两极 Faster/Smarter、6 个档位、底栏提示', () => {
+    const { stdout } = render(<EffortPanel {...baseProps} appStateEffort={undefined} />)
+    const out = stdout.join('')
+    expect(out).toContain('Effort')
+    expect(out).toContain('Faster')
+    expect(out).toContain('Smarter')
+    expect(out).toContain('low')
+    expect(out).toContain('medium')
+    expect(out).toContain('high')
+    expect(out).toContain('xhigh')
+    expect(out).toContain('max')
+    expect(out).toContain('ultracode')
+    expect(out).toContain('xhigh + workflows')
+    expect(out).toContain('←/→ adjust')
+    expect(out).toContain('Enter confirm')
+    expect(out).toContain('Esc cancel')
+  })
+
+  test('光标 ▲ 初始指向当前生效档（high）', () => {
+    const { stdout } = render(<EffortPanel {...baseProps} appStateEffort="high" />)
+    // 找到 high 那一行上方有 ▲
+    expect(stdout.join('')).toContain('▲')
+  })
+})
+```
+
+> 注：`ink-render.js` 路径在 Step 3.2 探查；如项目无现成 helper，退化为不依赖渲染的纯逻辑测试（仅测 onDone 分支回调）。
+
+- [ ] **Step 3.2: 探查 Ink 测试 helper**
+
+Run:
+```bash
+find src packages -name "*.ts*" -path "*test*" -exec grep -l "render.*Ink\|@anthropic/ink" {} \; 2>/dev/null | head -5
+grep -rn "render(" src/components/**/__tests__/*.tsx 2>/dev/null | head -10
+```
+
+Expected：要么找到现成 helper（用之），要么确认项目里 Ink 组件测试都用"调用 onDone 回调断言"而非 ink render。如果后者，**Step 3.1 改写为回调断言式测试**（见 Step 3.3 备注）。
+
+- [ ] **Step 3.3: 实现组件**
+
+Create `src/components/EffortPanel/EffortPanel.tsx`:
+
+```tsx
+import * as React from 'react'
+import { Box, Text } from '@anthropic/ink'
+import { useKeybindings } from '../../keybindings/useKeybinding.js'
+import {
+  type EffortValue,
+  getDisplayedEffortLevel,
+  getEffortEnvOverride,
+} from '../../utils/effort.js'
+import {
+  type PanelPosition,
+  getInitialCursor,
+  isUltracode,
+  moveLeft,
+  moveRight,
+  PANEL_POSITIONS,
+} from './effortPanelState.js'
+import { executeEffort } from '../../commands/effort/effort.js'
+import { useMainLoopModel } from '../../hooks/useMainLoopModel.js'
+import { useSetAppState } from '../../state/AppState.js'
+
+// 终端 ≥ 80 cols 时使用；窄屏适配第二阶段处理
+const PANEL_WIDTH = 76
+
+type Props = {
+  appStateEffort: EffortValue | undefined
+  onDone: (message: string) => void
+}
+
+// ▲ 落在每档中心列：均匀分布
+function cursorColumn(cursor: PanelPosition): number {
+  const segment = Math.floor(PANEL_WIDTH / PANEL_POSITIONS.length)
+  const idx = PANEL_POSITIONS.indexOf(cursor)
+  return segment * idx + Math.floor(segment / 2)
+}
+
+function renderPaddedLine(cursor: PanelPosition): string {
+  const col = cursorColumn(cursor)
+  // ▲ 上方的"分隔线 + 光标"行：左侧 ─，到列处 ▲，右侧继续 ─
+  return `${'─'.repeat(col)}▲${'─'.repeat(Math.max(0, PANEL_WIDTH - col - 1))}`
+}
+
+export function EffortPanel({ appStateEffort, onDone }: Props): React.ReactNode {
+  const setAppState = useSetAppState()
+  const model = useMainLoopModel()
+
+  const envOverride = getEffortEnvOverride()
+  const displayed = getDisplayedEffortLevel(model, appStateEffort)
+  const initialCursor = getInitialCursor({ envOverride, appStateEffort, displayed })
+
+  const [cursor, setCursor] = React.useState<PanelPosition>(initialCursor)
+  const [done, setDone] = React.useState(false)
+
+  const handleConfirm = React.useCallback(() => {
+    if (done) return
+    setDone(true)
+
+    if (isUltracode(cursor)) {
+      onDone(
+        'ultracode 不是 effort 档位。请使用 /ultracode <context> 启动多 agent workflow。',
+      )
+      return
+    }
+
+    const result = executeEffort(cursor)
+    if (result.effortUpdate) {
+      setAppState(prev => ({
+        ...prev,
+        effortValue: result.effortUpdate!.value,
+      }))
+    }
+    onDone(result.message)
+  }, [cursor, done, onDone, setAppState])
+
+  const handleCancel = React.useCallback(() => {
+    if (done) return
+    setDone(true)
+    onDone('Effort unchanged.')
+  }, [done, onDone])
+
+  useKeybindings(
+    {
+      'effortPanel:decrease': () => setCursor(c => moveLeft(c)),
+      'effortPanel:increase': () => setCursor(c => moveRight(c)),
+      'effortPanel:home': () => setCursor('low'),
+      'effortPanel:end': () => setCursor('ultracode'),
+      'effortPanel:confirm': handleConfirm,
+      'effortPanel:cancel': handleCancel,
+    },
+    { context: 'EffortPanel' },
+  )
+
+  const envActive = envOverride !== null && envOverride !== undefined
+  const envRaw = process.env.CLAUDE_CODE_EFFORT_LEVEL
+
+  // 两极文字行：左 Faster + 中间空格 + 右 Smarter
+  const fasterLen = 'Faster'.length
+  const smarterLen = 'Smarter'.length
+  const gap = Math.max(0, PANEL_WIDTH - fasterLen - smarterLen)
+  const poleLine = `Faster${' '.repeat(gap)}Smarter`
+
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      <Text bold>Effort</Text>
+      {envActive && (
+        <Text color="yellow">
+          ⚠ CLAUDE_CODE_EFFORT_LEVEL={envRaw} overrides this session
+        </Text>
+      )}
+      <Box marginTop={1}>
+        <Text>{poleLine}</Text>
+      </Box>
+      <Text>{renderPaddedLine(cursor)}</Text>
+      <Text>
+        {PANEL_POSITIONS.map(p => (p as string).padEnd(11)).join('').trimEnd()}
+      </Text>
+      <Text dimColor>
+        {' '.repeat(Math.max(0, PANEL_WIDTH - 'xhigh + workflows'.length))}
+        xhigh + workflows
+      </Text>
+      <Box marginTop={1}>
+        <Text dimColor>←/→ adjust · Enter confirm · Esc cancel</Text>
+      </Box>
+    </Box>
+  )
+}
+```
+
+> ⚠️ 对齐是粗糙实现（padEnd 11 假设每档名宽度 ≤ 11；实际 'ultracode' = 9 字符，OK；'xhigh' = 5）。第一版允许略微错位，视觉精度在第二阶段调优。重点是：标题、6 档名、底栏提示、▲ 标记必须出现。
+
+> **Step 3.3 备注（如无 ink render helper）：** Step 5 走纯函数抽取方案测分支；渲染层只做"包含字符串"断言。
+
+- [ ] **Step 3.4: 运行测试，确认通过**
+
+Run: `bun test src/components/EffortPanel/__tests__/EffortPanel.test.tsx`
+Expected: PASS
+
+如失败：检查 `useKeybindings` import 路径、`executeEffort` 是否能从 effort.tsx 导出（必要时在 effort.tsx 加 `export`）、`useMainLoopModel` hook 是否在测试环境工作（可能需要 mock）。
+
+- [ ] **Step 3.5: 类型 + lint 检查**
+
+Run: `bunx tsc --noEmit && bunx biome check src/components/EffortPanel/`
+Expected: 0 errors（如有 lint 警告，按提示修；`useKeybindings` 未使用变量之类的需移除）
+
+- [ ] **Step 3.6: Commit**
+
+```bash
+git add src/components/EffortPanel/EffortPanel.tsx src/components/EffortPanel/__tests__/EffortPanel.test.tsx
+git commit -m "$(cat <<'EOF'
+feat(effort): 实现 EffortPanel 组件主体（渲染 + 键盘交互 + 确认/取消分支）
+
+- 横向 slider 布局：Faster ↔ Smarter 两极，6 档刻度
+- useKeybindings 注册 EffortPanel context，←/→/h/l/home/end/enter/escape
+- Enter 在 5 档之一 → 调 executeEffort 写 settings + AppState
+- Enter 在 ultracode → 输出引导文案，不写状态
+- Esc → "Effort unchanged."
+- env override 时顶部黄色警告
+
+Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win>
+EOF
+)"
+```
+
+---
+
+## Task 4：改造 `/effort` 命令挂载面板
+
+**Files:**
+- Modify: `src/commands/effort/effort.tsx`
+
+- [ ] **Step 4.1: 阅读现状**
+
+Run: `cat src/commands/effort/effort.tsx`
+确认 `call()` 当前签名与 `ShowCurrentEffort` / `ApplyEffortAndClose` 组件结构。无参分支当前走 `<ShowCurrentEffort>`。
+
+- [ ] **Step 4.2: 改造 call() 无参分支**
+
+打开 `src/commands/effort/effort.tsx`，找到 `call()` 函数（约 line 153-169）。在文件顶部新增 import：
+
+```tsx
+import { EffortPanel } from '../../components/EffortPanel/EffortPanel.js'
+```
+
+把 `call()` 改为（替换无参分支）：
+
+```tsx
+export async function call(
+  onDone: LocalJSXCommandOnDone,
+  _context: unknown,
+  args?: string,
+): Promise<React.ReactNode> {
+  args = args?.trim() || ''
+
+  if (COMMON_HELP_ARGS.includes(args)) {
+    onDone(
+      'Usage: /effort [low|medium|high|xhigh|max|auto]\n\nEffort levels:\n- low: Quick, straightforward implementation\n- medium: Balanced approach with standard testing\n- high: Comprehensive implementation with extensive testing\n- xhigh: Extended reasoning beyond high, short of max; including ChatGPT Codex models\n- max: Maximum capability with deepest reasoning; maps to xhigh for ChatGPT Codex models\n- auto: Use the default effort level for your model',
+    )
+    return
+  }
+
+  // 无参 / /effort current / /effort status：原行为是显示当前档位；
+  // 现在拆分：完全无参 → 打开面板；current/status → 仍显示文本
+  if (args === '') {
+    return <EffortPanelWrapper onDone={onDone} />
+  }
+
+  if (args === 'current' || args === 'status') {
+    return <ShowCurrentEffort onDone={onDone} />
+  }
+
+  const result = executeEffort(args)
+  return <ApplyEffortAndClose result={result} onDone={onDone} />
+}
+```
+
+在文件底部追加 `EffortPanelWrapper`（桥接面板到 AppState 与 onDone）：
+
+```tsx
+function EffortPanelWrapper({
+  onDone,
+}: {
+  onDone: (result: string) => void
+}): React.ReactNode {
+  const effortValue = useAppState(s => s.effortValue)
+  return <EffortPanel appStateEffort={effortValue} onDone={onDone} />
+}
+```
+
+注意：`EffortPanel` 内部已经自己读 model + env override + 写 AppState，所以 wrapper 只是把 `effortValue` 透传。
+
+- [ ] **Step 4.3: 类型 + lint 检查**
+
+Run: `bunx tsc --noEmit && bunx biome check src/commands/effort/`
+Expected: 0 errors
+
+- [ ] **Step 4.4: 手动验证（pipe mode 快速跑）**
+
+Run:
+```bash
+echo "/effort" | bun run src/entrypoints/cli.tsx -p 2>&1 | head -30
+```
+
+Expected：看到面板渲染输出（标题 Effort、6 档、底栏提示）。pipe 模式下键盘交互不能测，只验证渲染。
+
+> 如果 pipe 模式不渲染面板（因为非交互式 TTY），改成 `bun run dev` 手测。
+
+- [ ] **Step 4.5: 跑相关测试**
+
+Run:
+```bash
+bun test src/commands/effort/ 2>/dev/null
+bun test tests/integration/message-pipeline* 2>/dev/null
+```
+
+Expected: 已有测试不破。
+
+- [ ] **Step 4.6: Commit**
+
+```bash
+git add src/commands/effort/effort.tsx
+git commit -m "$(cat <<'EOF'
+feat(effort): /effort 无参时挂载 EffortPanel 交互面板
+
+- 无参 → <EffortPanelWrapper> 透传 AppState.effortValue
+- current/status → 仍显示文本（不变）
+- 有参 → 直跳 executeEffort（不变）
+- help/-h/--help → 不变
+
+Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win>
+EOF
+)"
+```
+
+---
+
+## Task 5：补集成测试（键盘交互 + 分支）
+
+**Files:**
+- Modify/Create: `src/components/EffortPanel/__tests__/EffortPanel.test.tsx`（在 Task 3 基础上追加）
+
+- [ ] **Step 5.1: 决定测试路径（二选一）**
+
+Ink 组件键盘测试在项目里没有现成 helper（已通过 Task 3.2 探查确认）。直接走 **Step 5.2 的纯函数抽取方案**——把确认/取消决策逻辑抽到 `effortPanelState.ts`，用纯函数测试覆盖分支。键盘 → handler 的连接由 `useKeybindings` 注册保证，**不**单独测（与 `ModelPicker` 测试策略一致）。
+
+- [ ] **Step 5.2: 抽取确认/取消为可测纯函数（注入 applyFn 避免循环依赖）**
+
+把 `handleConfirm`/`handleCancel` 的决策逻辑抽到 `effortPanelState.ts`，**接受 `applyFn` 作为参数注入**，避免 `effortPanelState.ts` → `effort.tsx` → `EffortPanel.tsx` → `effortPanelState.ts` 的循环依赖，也避免测试触碰真实 settings。
+
+在 `effortPanelState.ts` 末尾追加：
+
+```ts
+export type ConfirmOutcome =
+  | {
+      kind: 'apply'
+      message: string
+      effortUpdate?: { value: EffortValue | undefined }
+    }
+  | { kind: 'ultracode-hint'; message: string }
+
+export type ApplyFn = (
+  cursor: PanelPosition,
+) => { message: string; effortUpdate?: { value: EffortValue | undefined } }
+
+export const ULTRACODE_HINT =
+  'ultracode 不是 effort 档位。请使用 /ultracode <context> 启动多 agent workflow。'
+
+export const CANCEL_MESSAGE = 'Effort unchanged.'
+
+export function computeConfirmOutcome(cursor: PanelPosition, applyFn: ApplyFn): ConfirmOutcome {
+  if (isUltracode(cursor)) {
+    return { kind: 'ultracode-hint', message: ULTRACODE_HINT }
+  }
+  const result = applyFn(cursor)
+  return {
+    kind: 'apply',
+    message: result.message,
+    effortUpdate: result.effortUpdate,
+  }
+}
+```
+
+然后在 `EffortPanel.tsx` 里改用：
+
+```tsx
+// 顶部 import 新增
+import {
+  type PanelPosition,
+  computeConfirmOutcome,
+  getInitialCursor,
+  isUltracode,    // 不再需要，computeConfirmOutcome 内部已用
+  moveLeft,
+  moveRight,
+  PANEL_POSITIONS,
+} from './effortPanelState.js'
+import { executeEffort } from '../../commands/effort/effort.js'
+
+// handleConfirm 改为
+const handleConfirm = React.useCallback(() => {
+  if (done) return
+  setDone(true)
+  const outcome = computeConfirmOutcome(cursor, executeEffort)
+  if (outcome.kind === 'apply' && outcome.effortUpdate) {
+    setAppState(prev => ({
+      ...prev,
+      effortValue: outcome.effortUpdate!.value,
+    }))
+  }
+  onDone(outcome.message)
+}, [cursor, done, onDone, setAppState])
+
+// handleCancel 改为
+const handleCancel = React.useCallback(() => {
+  if (done) return
+  setDone(true)
+  onDone(CANCEL_MESSAGE)
+}, [done, onDone])
+```
+
+注意 import 里也加 `CANCEL_MESSAGE`。
+
+- [ ] **Step 5.3: 写分支测试（用注入版纯函数）**
+
+在 `effortPanelState.test.ts` 末尾追加：
+
+```ts
+import {
+  CANCEL_MESSAGE,
+  computeConfirmOutcome,
+  ULTRACODE_HINT,
+  type ApplyFn,
+} from '../effortPanelState.js'
+
+describe('computeConfirmOutcome', () => {
+  const mockApply: ApplyFn = cursor => ({
+    message: `applied:${cursor}`,
+    effortUpdate: { value: cursor as any },
+  })
+
+  test('ultracode → kind=ultracode-hint，含 /ultracode 引导', () => {
+    const out = computeConfirmOutcome('ultracode', mockApply)
+    expect(out.kind).toBe('ultracode-hint')
+    if (out.kind === 'ultracode-hint') {
+      expect(out.message).toBe(ULTRACODE_HINT)
+      expect(out.message).toContain('/ultracode')
+    }
+  })
+
+  test('low → kind=apply，message 来自 applyFn，effortUpdate 透传', () => {
+    const out = computeConfirmOutcome('low', mockApply)
+    expect(out.kind).toBe('apply')
+    if (out.kind === 'apply') {
+      expect(out.message).toBe('applied:low')
+      expect(out.effortUpdate?.value).toBe('low')
+    }
+  })
+
+  test('high → apply 路径不调 ultracode 分支', () => {
+    const out = computeConfirmOutcome('high', mockApply)
+    expect(out.kind).toBe('apply')
+  })
+})
+
+test('常量字符串', () => {
+  expect(CANCEL_MESSAGE).toBe('Effort unchanged.')
+  expect(ULTRACODE_HINT).toContain('/ultracode <context>')
+})
+```
+
+注意：因注入 mockApply，**完全不需要 mock settings**——这是注入方案的最大红利。
+
+- [ ] **Step 5.4: 跑测试**
+
+Run: `bun test src/components/EffortPanel/__tests__/`
+Expected: PASS
+
+- [ ] **Step 5.5: Commit**
+
+```bash
+git add src/components/EffortPanel/
+git commit -m "$(cat <<'EOF'
+test(effort): 补 EffortPanel 分支测试（ultracode 引导 / 取消文案 / apply 路径）
+
+抽 computeConfirmOutcome 为纯函数便于测试，避开 Ink 键盘事件模拟。
+
+Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win>
+EOF
+)"
+```
+
+---
+
+## Task 6：precheck 全量 + 验收
+
+**Files:** 无修改
+
+- [ ] **Step 6.1: 跑 precheck**
+
+Run: `bun run precheck`
+Expected: typecheck + lint fix + test 全绿，零错误
+
+如有失败：按错误信息修，**不要**用 `as any` 或 `// biome-ignore` 绕过（除非确实是反编译代码遗留问题）。
+
+- [ ] **Step 6.2: 手动验收**
+
+Run: `bun run dev`
+输入 `/effort`，确认：
+- 面板出现，光标 `▲` 停在当前生效档
+- `←` / `→` 移动光标，到边界（low / ultracode）不再继续
+- Enter 在 high 时输出 `Set effort level to high: ...`
+- 把光标移到 ultracode，Enter → 输出引导文案
+- Esc → 输出 `Effort unchanged.`
+- 设 `CLAUDE_CODE_EFFORT_LEVEL=high bun run dev`，再 `/effort` → 顶部黄色警告
+- `/effort low`、`/effort auto`、`/effort current`、`/effort help` 仍按原行为工作
+
+- [ ] **Step 6.3: 推送（可选，等用户决定）**
+
+Run: `git log --oneline -10` 检查 commit 历史
+Run: `git push` （**仅在用户确认后**）
+
+---
+
+## Self-Review 清单
+
+实施完毕后，对照 spec 自检：
+
+- [ ] §4 文件结构：`EffortPanel/`、`effortPanelState.ts`、测试文件都存在
+- [ ] §5 交互：←/→/Home/End/Enter/Esc/q 全部实现；触发与初始光标正确
+- [ ] §5 分支 A：5 档 Enter 调 executeEffort
+- [ ] §5 分支 B：ultracode Enter 输出引导文案
+- [ ] §5 取消：`Effort unchanged.`
+- [ ] §6 视觉：标题、Faster/Smarter、6 档、ultracode 副标签、底栏提示
+- [ ] §6 双标记：env override 时 cursor `▲` 与 active `(high) active` 同时显示（如未实现双标记，作为已知缺陷，第二阶段补）
+- [ ] §6 模型不支持：禁用面板，仅 Esc 可退出（如未实现，第二阶段补，但 spec 写明要实现）
+- [ ] §9 边界：env override、模型不支持、settings 写入失败（沿用 executeEffort 现有错误路径）
+- [ ] §10 测试：纯函数 + 组件 + 分支
+- [ ] precheck 零错误
+- [ ] 两阶段切分清晰：本计划只做基础，波纹动画第二阶段
+
+---
+
+## 已知首版可接受简化
+
+为了控制首版范围，以下细节**允许暂时不完美**，第二阶段或后续 commit 再调：
+
+1. `▲` 与档位文字的对齐（窄屏 / 不同终端宽度下可能错位）
+2. 双标记 `(high) active` 的精确渲染（首版可只显示 cursor `▲`，env override 顶部警告保证用户知情）
+3. 模型不支持时的禁用态（首版可允许面板仍可操作，但顶部加提示）
+4. 终端 < 60 cols 的垂直布局退化
+5. 数字键 1-6 快速跳转（spec 中标为可选增强，本计划不做）
+
+这些不影响主功能，第一版以"能用、稳定、可提交"为目标。
--- 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-run-state-persistence-design.md
+++ b/docs/superpowers/specs/2026-06-13-workflow-run-state-persistence-design.md
@@ -0,0 +1,191 @@
+# Workflow Run State Persistence — Design
+
+**Date**: 2026-06-13
+**Status**: Approved (brainstorming), pending implementation plan
+**Related**: `2026-06-12-workflow-engine-design.md`, `2026-06-13-workflow-panel-redesign.md`
+
+## 问题陈述
+
+Workflow 脚本的 `return` 值和终态 `RunProgress`（status / agents / phases / returnValue / error）只活在 `ProgressStore`（`src/workflow/progress/store.ts`）的内存 Map 里。一旦 Claude Code 进程关闭/重启，全部丢失。
+
+已落盘的 `.claude/workflow-runs/<runId>/journal.jsonl` 只记录每个 `agent()` 调用的结构化结果，**不**包含脚本顶层 `return` 值，也无法重建 `/workflows` 面板需要的 `RunProgress` 摘要。重启后面板为空，对话 agent 也无法按 runId 取回 return 值。
+
+## 目标
+
+- **(a) 重启后按 runId 取 return** — 对话 agent 在新进程里能拿到已完成 run 的 `returnValue` 与 `error`。
+- **(b) 面板跨重启展示历史** — `/workflows` 面板重启后能列出历史 run 及其状态/agents/phases/耗时。
+
+## 非目标
+
+- **(c) 跨进程 resume 明确排除** — 不重建 abort controller、agent binding、未完成 phase 的中间态。当前 resume 机制（同进程内 journal replay）保持不变；跨进程续跑是独立大特性，不在本 spec 范围。
+- **自动清理** — `.claude/workflow-runs/` 持续累积，依赖项目 `.gitignore` 与用户手动清理。生命周期管理是后续特性。
+
+## 架构
+
+新增一个 host 侧持久化模块 + 三处接入点。**引擎层 `@claude-code-best/workflow-engine` 零改动**——持久化是 host 侧关注，不污染引擎接口。
+
+### 组件
+
+| 文件 | 改动 | 职责 |
+|---|---|---|
+| `src/workflow/persistence.ts` | 新增 | `writeRunState` / `readRunState` / `listPersistedRuns`；原子覆盖写（tmp + rename）；`getRunsDir()` 统一 runsDir 来源 |
+| `src/workflow/progress/store.ts` | 改 | 新增 `hydrate(run: RunProgress): void` —— 绕过 bus 直接注入磁盘 run（用于 `loadPersistedRuns`） |
+| `src/workflow/service.ts` | 改 | 订阅 bus `run_done` → `writeRunState`；`getRun(id)` 内存 miss → `readRunState` fallback；新增 `loadPersistedRuns(): Promise<void>` |
+| `src/workflow/panel/WorkflowsPanel.tsx` | 改 | mount 时调一次 `svc.loadPersistedRuns()`（flag 在 service 单例内部守护，panel 无脑调，重复调用是 no-op） |
+| `src/workflow/ports.ts` | 改 | `${getProjectRoot()}/.claude/workflow-runs` 提取为 `getRunsDir()` 共享（消除重复拼接，与 persistence.ts 同源） |
+
+## 数据流
+
+### 写入（终态触发，单一入口覆盖 A+ 所有终态）
+
+```
+engine runWorkflow
+  └─ progressEmitter.emit({type:'run_done', status, returnValue, error})
+     └─ bus.emit
+        ├─ store.apply(event)            [store 先订阅，内存 RunProgress 已更新]
+        └─ service 订阅 listener          [后订阅，store.get(runId) 拿到最新快照]
+           └─ writeRunState(runsDir, runId, snapshot)
+              └─ writeFile(state.json.tmp) → rename(state.json)   [原子]
+```
+
+**订阅顺序**：bus 是 `Set<listener>`，注册顺序 = 触发顺序。`createProgressStoreFromBus(bus)` 在 service 创建之前先订阅 store；service 后订阅。因此 service 的 `run_done` listener 执行时，`store.get(event.runId)` 已是 apply 后的最新值，直接序列化写盘即可。
+
+**为什么不需要单独的 shutdown 钩子**：`taskRegistrar.kill` → `abortController.abort()` → `runWorkflow` 看到 signal → 发 `run_done killed` → 走同一个订阅。`service.shutdown()` 显式 kill running run 时同样触发 `run_done`。三种终态（completed / failed / killed）共用一个写盘入口。
+
+### 读取① — 面板跨重启展示
+
+```
+CLI 重启 → 用户 /workflows → WorkflowsPanel mount
+  └─ useEffect: svc.loadPersistedRuns()   [service 内部 persistedLoaded flag 守护，仅一次实际扫盘]
+     └─ listPersistedRuns(runsDir)         [扫所有子目录的 state.json]
+        └─ store.hydrate(run)              [已存在的 runId 跳过，内存优先]
+```
+
+**`persistedLoaded` flag 归属**：放在 `WorkflowService` 单例上（`makeService` 闭包变量），不是 panel 模块级。理由：service 是进程单例，flag 跟随单例生命周期最稳；panel 可能多次 mount/unmount，flag 在 service 上可避免重复扫盘。panel `useEffect` 无脑调 `loadPersistedRuns()`，service 内部判断"已加载过则立即返回 resolved Promise"。
+
+### 读取② — agent 按 runId 取 return
+
+```
+service.getRun(id)
+  ├─ store.get(id) 命中 → 返回（本次会话的 run）
+  └─ miss → readRunState(runsDir, id) → 返回（历史 run，不注入内存）
+```
+
+**不注入内存的取舍**：历史 run 进入内存会污染本次会话的 store / 面板列表语义（"内存 = 本次会话产生的 run"这条不变量要保留）。代价是同会话内反复查同一历史 run 会反复读盘——可接受（查询频率低，文件小）。
+
+## state.json 格式
+
+包一层 `schemaVersion` 留 migration 空间，payload 是终态 `RunProgress` 全字段：
+
+```json
+{
+  "schemaVersion": 1,
+  "run": {
+    "runId": "w12tp1rrk",
+    "workflowName": "audit-agent-system-vs-ultracode",
+    "status": "completed",
+    "phases": [
+      {"title": "Review", "status": "done"},
+      {"title": "Verify", "status": "done"}
+    ],
+    "declaredPhases": ["Review", "Verify"],
+    "currentPhase": null,
+    "agents": [
+      {
+        "id": 1,
+        "label": "review:hooks",
+        "phase": "Review",
+        "status": "done",
+        "outputShape": "object",
+        "tokenCount": 12345,
+        "toolCount": 3,
+        "model": "claude-sonnet-4-6"
+      }
+    ],
+    "agentCount": 11,
+    "returnValue": {"dimensionsAudited": 9, "confirmedCount": 2, "confirmed": []},
+    "startedAt": 1718277600000,
+    "updatedAt": 1718278000000,
+    "description": "Audit workflow engine against ultracode skill spec"
+  }
+}
+```
+
+### 字段决策
+
+- `agents[]` 写完整 `AgentProgress`（含 `label` / `phase` / `status` / `tokenCount` / `toolCount` / `model` / `outputShape` / `resultKind`），**不含 agent 实际 output 内容**——output 已在 `journal.jsonl`，避免冗余。
+- 失败 run 的 `error` 字段直接进 `run.error`（`RunProgress` 已有该字段）。
+- `returnValue?: unknown` 原样序列化，**不截断**。用户对自己的 return 大小负责（脚本若 return 整个数据库 dump，磁盘占用自负）。
+
+## 错误处理
+
+| 场景 | 行为 |
+|---|---|
+| `writeRunState` IO 失败（磁盘满 / 权限） | `logForDebugging('[workflow warn] ...')` 吞掉，**不阻断 workflow 完成**——workflow 本身已成功，持久化失败只意味着重启后取不到，可接受 |
+| `readRunState` 文件不存在 | 返回 `null`，调用方按 miss 处理 |
+| `readRunState` JSON 解析失败 | 返回 `null`，log warn，当 miss（不崩） |
+| `readRunState` schema 结构不匹配（缺字段/类型错） | 返回 `null`，log warn，当 miss |
+| `schemaVersion` 未来不匹配 | 当前是 `1`，无迁移链，任何非 1 的版本 → 返回 `null` 当 miss（向前兼容兜底）。未来升级版本时再引入迁移函数链 |
+| 原子写中途崩溃 | `writeFile(state.json.tmp)` + `rename(tmp, state.json)`，rename 原子；最坏留下 `.tmp` 文件，下次写覆盖 |
+| `loadPersistedRuns` 扫到子目录无 `state.json`（只有 journal） | 跳过，不报错（半残 run） |
+| `loadPersistedRuns` 扫到某 `state.json` 损坏 | 跳过该单个文件，继续扫其余（一个坏文件不阻塞整体加载） |
+
+## 关键不变量
+
+1. **内存 run 永远优先于磁盘 run** — `store.hydrate` 跳过已存在 runId；`getRun` 内存命中则不读盘。
+2. **磁盘是纯终态快照** — 本次会话 running 中的 run 不写盘；进程在 run 终态前被 SIGKILL/断电/crash，该 run 在磁盘上缺失（连 `run_done` 都来不及发）。这是 A+ 接受的边缘情况。
+3. **磁盘 run 不注入 `getRun` 路径的内存** — 只有 `loadPersistedRuns`（面板 mount）会 hydrate；`getRun` fallback 仅返回，不 hydrate。
+4. **持久化失败不阻断 workflow** — 写盘是 best-effort，IO 异常只 log 不抛。
+5. **引擎层零改动** — 所有持久化逻辑在 host 侧（`src/workflow/`），引擎 `@claude-code-best/workflow-engine` 接口不变。
+
+## 测试策略
+
+### `src/workflow/__tests__/persistence.test.ts`（新增）— 纯 fs，用 tmpdir
+
+- `writeRunState` → `readRunState` 往返一致（含 `returnValue` 为对象 / 数组 / 字符串 / null 各形态）
+- `writeRunState` 原子性：构造 tmp 残留场景，验证 `state.json` 要么完整要么不存在，无半写
+- `readRunState` 损坏 JSON / 缺文件 / schemaVersion 不符 / 必需字段缺失 → 均返回 `null`
+- `listPersistedRuns` 扫多子目录、跳过无 `state.json` 的目录、跳过损坏文件、按 `updatedAt` 降序返回
+
+### `src/workflow/__tests__/store.test.ts`（扩展）
+
+- `hydrate(run)` 注入新 runId → `get` 命中、`list` 含该项
+- `hydrate(run)` 已存在 runId → 跳过（内存值不被磁盘覆盖）
+- `hydrate` 后 `subscribe` listener 被通知
+
+### `src/workflow/__tests__/service.test.ts`（新增 / 扩展）— 注入 fake bus / ports / tmpdir
+
+- bus emit `run_done completed` + returnValue → `readRunState(runId)` 命中且 returnValue 一致
+- bus emit `run_done failed` + error → state.json 写入 status=failed + error 字段
+- bus emit `run_done killed` → state.json 写入 status=killed
+- bus emit `run_done` 但 `writeRunState` 抛 IO 错 → service 不抛、其他订阅者（store）仍正常
+- `getRun(id)` 内存命中 → 不读盘（spy 断言 readRunState 未被调）
+- `getRun(id)` 内存 miss + 磁盘命中 → 返回磁盘值；再次 `getRun(id)` 仍读盘（未注入内存）
+- `getRun(id)` 内存 miss + 磁盘 miss → 返回 undefined
+- `loadPersistedRuns()` 扫盘后 `listRuns()` 含历史 run；已有内存 runId 不被磁盘覆盖
+
+### `src/workflow/__tests__/WorkflowsPanel.test.tsx`（扩展）
+
+- WorkflowsPanel mount → 调一次 `loadPersistedRuns`（spy 断言调用次数 = 1）
+- 重复 mount / 重渲染 → 不重复调用（`persistedLoaded` flag 防重入）
+
+### 回归
+
+- `bun test src/workflow/` 全套通过
+- `bun run precheck` 零错误（typecheck + lint fix + test）
+
+## 实现顺序提示（供 writing-plans 展开）
+
+1. `persistence.ts` + 单测（最底层，无依赖）
+2. `store.ts` 加 `hydrate` + 单测
+3. `ports.ts` 提取 `getRunsDir()`
+4. `service.ts` 订阅 `run_done` + `getRun` fallback + `loadPersistedRuns` + 单测
+5. `WorkflowsPanel.tsx` mount 触发 + 测试
+6. 全量 `precheck`
+
+## 未来工作（明确不在本 spec）
+
+- **跨进程 resume (c)** — 需重建 agent binding / abort / 中间态，独立特性
+- **生命周期管理** — 数量 cap / 时间 cap / 手动清理命令
+- **return 值大小限制** — 若发现滥用，再加 schema 级 cap 与截断策略
+- **schema migration 链** — 当 `schemaVersion` 升到 2 时再引入
--- 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 级预算。
--- a/docs/superpowers/specs/2026-06-14-effort-panel-design.md
+++ b/docs/superpowers/specs/2026-06-14-effort-panel-design.md
@@ -0,0 +1,394 @@
+# Effort 交互面板（EffortPanel）设计
+
+**日期**: 2026-06-14
+**作者**: brainstorming session 产物
+**状态**: 待实施
+**关联**: `src/commands/effort/`、`src/utils/effort.ts`、`src/components/EffortPanel/`（新增）
+
+---
+
+## 1. 概述
+
+把当前的 `/effort` slash 命令从纯文本式交互升级为终端内的可视化选择面板。
+
+- 触发：`/effort`（无参）打开面板；`/effort <level>` 直跳路径保留
+- 视觉：横向 slider，两端标 `Faster` / `Smarter`，刻度为 `low / medium / high / xhigh / max / ultracode`
+- 交互：`←/→` 移动光标，`Enter` 确认，`Esc` 取消
+- ultracode 仅作视觉占位，确认后提示用户走 `/ultracode <context>` 启动
+- 第二阶段加波纹动画（详见 §6）
+
+## 2. 用户故事
+
+- 作为开发者，我希望按 `/effort` 就能可视化地选择努力等级，而不用记 5 个枚举值
+- 作为高频用户，我希望 `/effort high` 这种直跳仍可用，避免脚本/习惯被打断
+- 作为设置了 `CLAUDE_CODE_EFFORT_LEVEL` 的用户，我希望面板提示我"env 优先级更高"，而不是默默忽略我的选择
+- 作为想试 ultracode 的用户，我希望面板让我知道这个"档位"存在，但落地要走它自己的命令
+
+## 3. 不在本期范围
+
+- 不修改 `EffortValue` / `EffortLevel` 类型
+- 不修改 `src/utils/effort.ts` 的任何纯函数
+- 不新增专用全局热键（仅通过 `/effort` 触发）
+- 不在面板里包含 `auto` 选项（仍走 `/effort auto`）
+- 不真正"启用 ultracode"——面板对 ultracode 仅作视觉提示与文案引导
+
+## 4. 架构与文件结构
+
+```
+src/
+├── commands/effort/
+│   ├── effort.tsx              ← 改造：call() 在 args 为空时返回 <EffortPanel>，
+│   │                              有参时维持原 executeEffort() 路径
+│   └── index.ts                ← 不变
+├── components/EffortPanel/
+│   ├── EffortPanel.tsx         ← 新增：面板主体（渲染 + 键盘交互 + onDone 通道）
+│   ├── effortPanelState.ts     ← 新增：纯函数 reducer（移动光标、确定选项），
+│   │                              抽离便于单测
+│   └── __tests__/
+│       ├── EffortPanel.test.tsx        ← 渲染 / 键盘交互 / env 警告 / ultracode 提示
+│       └── effortPanelState.test.ts    ← reducer 纯函数测试
+```
+
+### 复用清单（不重写）
+
+- `executeEffort()` / `setEffortValue()` / `unsetEffortLevel()`：留在 `effort.tsx`，面板确认时调用
+- `EFFORT_LEVELS` / `getDisplayedEffortLevel()` / `getEffortEnvOverride()` / `getEffortValueDescription()` / `modelSupportsEffort()`：从 `src/utils/effort.ts` 直接 import
+- `useInput` 或 `useKeyboard`：从 `@anthropic/ink` 取
+- `<ApplyEffortAndClose>` 组件：作为面板 Enter 后的"写入并退出"流程组件复用（或迁入 EffortPanel 内部）
+
+### 类型层面
+
+不动 `EffortValue` / `EffortLevel`。面板内部用一个新类型 `PanelPosition` 表示光标位置：
+
+```ts
+type PanelPosition = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultracode';
+```
+
+它仅在面板内部使用，不进入 AppState、不进入 settings.json、不参与 API 调用。
+
+## 5. 交互流程
+
+### 触发与初始光标
+
+```
+/effort<回车>（无参）
+  → call() 检测 args === ''
+  → 渲染 <EffortPanel onDone={onDone} appStateEffort={effortValue} model={model} />
+  → 光标初始位置：
+       env override 存在时 → env 设定的档位（让用户立刻看到生效值）
+       否则 → getDisplayedEffortLevel(model, appStateEffort)
+```
+
+### 状态机
+
+```
+状态：{ cursor: PanelPosition }
+
+事件：
+  ← (ArrowLeft)    → cursor 左移一位（low 处不左移，保持 low）
+  → (ArrowRight)   → cursor 右移一位（ultracode 处不右移，保持 ultracode）
+  Home / h         → cursor = low
+  End / l          → cursor = ultracode
+  Enter            → 确认分支（见下）
+  Esc / Ctrl+C / q → 取消，onDone("Effort unchanged.")
+```
+
+### 确认后的两条分支
+
+**分支 A：cursor ∈ {low, medium, high, xhigh, max}**
+
+```
+调 executeEffort(cursor)
+  → setEffortValue 写 settings + AppState
+  → 拿到 result.message
+onDone(result.message)
+```
+
+（与现有 `/effort high` 完全一致的消息体例，含 env override 警告）
+
+**分支 B：cursor === 'ultracode'**
+
+```
+不调 executeEffort
+onDone("ultracode 不是 effort 档位。请使用 /ultracode <context> 启动多 agent workflow。")
+```
+
+### 取消路径
+
+不调 executeEffort、不写 AppState、不写 settings。`onDone("Effort unchanged.")`。
+
+### 不变路径（仍走原 effort.tsx 逻辑）
+
+- `/effort low|medium|high|xhigh|max`：直跳
+- `/effort auto|unset`：unsetEffortLevel
+- `/effort help|-h|--help`：help 文本
+- `/effort current|status`：ShowCurrentEffort
+
+### 焦点与键盘独占
+
+面板挂载时通过 Ink `useInput` 抢占键盘；卸载时自动释放（与 `AskUserQuestionPermissionRequest` 一致）。
+
+## 6. 视觉布局
+
+### 基本形态（无 env override）
+
+```
+Effort
+
+       Faster                                                          Smarter
+       ─────────────────────────▲──────────────────────────────────────────────
+       low        medium       high       xhigh        max        ultracode
+                                                      xhigh + workflows
+
+       ←/→ adjust · Enter confirm · Esc cancel
+```
+
+### 视觉规则
+
+| 元素 | 规则 |
+|---|---|
+| `▲` 光标 | 跟随 cursor 状态移动，永远指向当前 cursor 位置 |
+| 当前生效档位（active） | 当 cursor ≠ active 时，active 档渲染为加粗 + 旁标 `(active)`；当 cursor === active 时只显示 `▲`，避免双标记 |
+| ultracode 副标签 | 固定字符串 `xhigh + workflows`，dim 色 |
+| 两极文字 `Faster` / `Smarter` | 与面板等宽左右对齐；中间用一行 `─` 填充 |
+| 底栏提示 | `←/→ adjust · Enter confirm · Esc cancel`，dim 色 |
+| 标题 `Effort` | 加粗，居中或左对齐 |
+
+### 双标记渲染（cursor ≠ active）
+
+env override 时会出现，例如：
+
+```
+Effort
+⚠ CLAUDE_CODE_EFFORT_LEVEL=high overrides this session
+
+       Faster                                                          Smarter
+       ────────────────────────▲────────────────────────▲──────────────────────
+       low        medium      (high) active   xhigh        max        ultracode
+                                                      xhigh + workflows
+
+       ←/→ adjust · Enter confirm · Esc cancel
+```
+
+- `▲` 上方：cursor 位置（xhigh）
+- `(high) active`：env 锁定的真实生效档位
+
+两个标记视觉上必须区分：cursor 用三角符号，active 用括号文字 + 颜色。
+
+### 模型不支持 effort 时（`modelSupportsEffort(model) === false`）
+
+```
+Effort
+
+  当前模型 <model> 不支持 effort 参数。面板已禁用。
+
+       Faster                                                          Smarter
+       ────────────────────────────────────────────────────────────────────────
+       low        medium       high       xhigh        max        ultracode
+
+       Esc to close
+```
+
+光标不显示，左右键无效，Enter 无效，只能 Esc 退出。
+
+### 终端窄屏（< 60 cols）适配
+
+简化策略：宽度 < 60 时退化为垂直列表，每档一行；否则保持横向 slider。这一项**不阻塞首版**，先按横向渲染，必要时溢出，后续看实际效果再调。
+
+## 7. 背景波纹动画（第二阶段，单独 commit）
+
+### 触发条件
+
+仅在 cursor 停在 `ultracode` 时启动波纹；移开时立即停止（不淡出，干脆）。常态零干扰。
+
+### 视觉概念
+
+ultracode 是面板的"能量溢出口"。波纹从 ultracode 字符位置（右下区域）为震源，向左/向上辐射同心圆波，铺满整个面板的留白区域（文字字符之间的空隙、`─` 分隔线的空白段）。文字层永远清晰可读。
+
+### 字符集（强度 → 字符）
+
+| 强度 | 字符 |
+|---|---|
+| 0.0 | ` ` (空格) |
+| 0.1 | `·` |
+| 0.3 | `∙` |
+| 0.5 | `░` |
+| 0.7 | `▒` |
+| 0.9 | `▓` |
+| 波峰 | `~` → `◌` → `○` → `◑` → `●` 循环 |
+
+### 波纹数学
+
+```
+对每个字符格:
+  dx = x - sourceX
+  dy = (y - sourceY) * 1.5
+  dist = sqrt(dx*dx + dy*dy)
+  
+  phase = dist * 0.4 - time * 0.012
+  wave = sin(phase)
+  falloff = max(0, 1 - dist / 40)
+  intensity = max(0, wave) * falloff
+  
+  if (dist < 6):    // 震源附近高频涟漪
+    intensity = max(intensity, 0.5 + 0.5 * sin(time * 0.02 - dist * 1.2))
+  
+  char = pick(intensity)
+```
+
+参数上线后调。
+
+### 渲染策略（双层不冲突）
+
+Ink 不支持真正的 z-index 层叠，用**字符替换**模拟：
+
+1. 每帧生成 `height × width` 字符矩阵（背景层）
+2. 渲染每个面板行时，先取该行对应的波纹字符序列，然后在文字字符应该出现的位置**覆盖**背景字符
+3. 文字字符永远胜出，波纹只占空隙
+
+### 实现位置
+
+新增（第二阶段）：
+- `src/components/EffortPanel/rippleAnimation.ts` — `pickChar` / `computeRippleLine` / `mergeLayers` 纯函数
+- `src/components/EffortPanel/useRippleFrame.ts` — hook，内部调 `useAnimationFrame(60)` 返回当前帧矩阵
+- 在 `EffortPanel.tsx` 的 render 中叠加（仅 cursor === 'ultracode' 时启用）
+
+### 性能预算
+
+- 面板 80×10 = 800 格，每帧 800 次 sin/sqrt ≈ 0.05ms
+- Ink 重绘 10 行 `<Text>` 节点，与现有 Spinner 同量级
+- 帧率 16fps，`useAnimationFrame` 自带 viewport 不可见暂停 + 失焦减速
+
+### 风险与对策
+
+| 风险 | 对策 |
+|---|---|
+| 波纹干扰文字可读性 | 文字字符覆盖背景字符，永远胜出；波纹颜色用 `theme.textDisabled` |
+| 终端窄屏 < 60 cols | sourceX 跟随 ultracode 实际位置；窄屏时降级为单行波纹 |
+| 性能（旧机器） | `useAnimationFrame` 已自带暂停/减速 |
+| 测试稳定性 | 字符选择是纯函数，可固定 `time` 注入做帧快照测试 |
+
+## 8. 数据流
+
+### 状态来源
+
+```
+┌─────────────────────────────────────────────────┐
+│ src/state/AppState.tsx                          │
+│   effortValue: EffortValue | undefined          │
+└─────────────────────────────────────────────────┘
+              ▲
+              │ useAppState(s => s.effortValue)
+              │
+┌─────────────────────────────────────────────────┐
+│ EffortPanel.tsx                                 │
+│   props: appStateEffort, model, onDone          │
+│   local: cursor: PanelPosition                  │
+└─────────────────────────────────────────────────┘
+              │
+              │ Enter 确认
+              ▼
+┌─────────────────────────────────────────────────┐
+│ executeEffort(cursor)                           │
+│   → updateSettingsForSource('userSettings', …)  │
+│   → logEvent('tengu_effort_command', …)         │
+│   → 返回 { message, effortUpdate? }             │
+└─────────────────────────────────────────────────┘
+              │
+              │ <ApplyEffortAndClose> setAppState(...)
+              ▼
+┌─────────────────────────────────────────────────┐
+│ onDone(result.message)                          │
+│   → REPL 渲染 assistant 消息                    │
+└─────────────────────────────────────────────────┘
+```
+
+### 优先级链（不修改）
+
+```
+env CLAUDE_CODE_EFFORT_LEVEL  >  AppState.effortValue  >  model default
+```
+
+面板只写 AppState + settings.json，不直接操作 env。env 存在时，面板可操作但顶部警告（详见 §6 双标记）。
+
+## 9. 边界与错误处理
+
+| 场景 | 行为 |
+|---|---|
+| 模型不支持 effort | 面板挂载但禁用，文字提示 + 仅允许 Esc（详见 §6） |
+| env override 设定 | 顶部加黄色警告行 `⚠ CLAUDE_CODE_EFFORT_LEVEL=<value> overrides this session`；光标可移动；Enter 仍写 settings 但顶部警告解释生效值不变 |
+| cursor === 'ultracode' 时 Enter | 走分支 B，输出引导文案，不调 executeEffort |
+| settings 写入失败（磁盘满/权限） | `executeEffort` 现有错误路径会返回 `result.error`，面板沿用，onDone 输出错误消息 |
+| 终端窄屏 < 60 cols | 退化为垂直列表，不阻塞首版 |
+| 用户按 Ctrl+C 之外的中断信号 | 视同 Esc，`onDone("Effort unchanged.")` |
+| 面板挂载后 AppState 被外部改变（如 `/model` 切换） | cursor **不订阅** active 变化，挂载时计算一次初始值后只跟随用户操作。若用户切了 model 想看新档位，关掉面板重开即可。简化实现，行为可预测 |
+
+## 10. 测试计划
+
+### 纯函数（`effortPanelState.test.ts`）
+
+- `moveLeft(cursor)` 在 low 处保持 low
+- `moveRight(cursor)` 在 ultracode 处保持 ultracode
+- `home(cursor)` / `end(cursor)` 边界
+- `getInitialCursor(appStateEffort, envOverride, model)` 优先级
+- `isUltracode(cursor)` 守卫
+
+### 组件（`EffortPanel.test.tsx`）
+
+渲染：
+- 无 env 时显示基本形态
+- env override 时顶部警告 + 双标记
+- 模型不支持时禁用面板
+- ultracode 副标签 `xhigh + workflows` 出现
+
+键盘：
+- `←` 移动光标、`→` 移动光标、`Home/End` 跳转
+- Enter 在普通档位 → 调用 executeEffort、onDone 收到正确 message
+- Enter 在 ultracode → 不调 executeEffort、onDone 收到引导文案
+- Esc → 不调 executeEffort、onDone 收到 `"Effort unchanged."`
+
+集成（`effort.tsx` 的 call 函数）：
+- 无参 → 返回 `<EffortPanel>` JSX
+- 有参 → 不渲染面板，走 executeEffort
+
+### 波纹相关（第二阶段）
+
+- `pickChar(intensity)` 各强度边界
+- `computeRippleLine` 固定 time 快照
+- `mergeLayers` 文字覆盖背景、文字字符永远胜出
+- `useRippleFrame` 仅在 cursor === 'ultracode' 时订阅时钟
+
+## 11. 实现阶段划分（两个 commit）
+
+### Commit 1：基础面板（先做）
+
+- 新增 `src/components/EffortPanel/EffortPanel.tsx`
+- 新增 `src/components/EffortPanel/effortPanelState.ts`
+- 新增 `src/components/EffortPanel/__tests__/EffortPanel.test.tsx`
+- 新增 `src/components/EffortPanel/__tests__/effortPanelState.test.ts`
+- 改造 `src/commands/effort/effort.tsx`：无参时返回 `<EffortPanel>`，有参维持原状
+- 运行 `bun run precheck`，必须零错误通过
+- commit message: `feat(effort): /effort 无参时打开横向 slider 选择面板`
+
+### Commit 2：波纹动画（基础稳定后再做）
+
+- 新增 `src/components/EffortPanel/rippleAnimation.ts`
+- 新增 `src/components/EffortPanel/useRippleFrame.ts`
+- 新增对应测试
+- 在 `EffortPanel.tsx` 中叠加渲染（仅 cursor === 'ultracode' 时）
+- 运行 `bun run precheck`
+- commit message: `feat(effort): ultracode 档位铺满波纹背景动画`
+
+两阶段切开的好处：动画是创意工作，可能在调参上反复；基础功能稳定后即使动画翻车也能直接 revert 第二个 commit，不影响主功能。
+
+## 12. 验收清单
+
+- [ ] `/effort` 无参打开面板，光标停在当前生效档
+- [ ] `←/→` 移动光标，到边界不再继续
+- [ ] Enter 在 5 档之一时写 settings + AppState + 输出与 `/effort X` 同款消息
+- [ ] Enter 在 ultracode 时输出引导文案，不写任何状态
+- [ ] Esc 时不写任何状态，输出 `"Effort unchanged."`
+- [ ] env override 时顶部警告 + 双标记
+- [ ] 模型不支持时面板禁用，仅 Esc 可退出
+- [ ] `/effort low|auto|help|current` 等原有路径行为不变
+- [ ] `bun run precheck` 零错误