versun/claude-code
1
0
Fork 0
mirror of https://github.com/claude-code-best/claude-code.git synced 2026-06-18 22:35:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: dynamic-workflow 来了 (#1271)

Browse Source 
* 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>
This commit is contained in:
claude-code-best
2026-06-14 18:13:49 +08:00
committed by GitHub
parent 3e3e1de81b
commit 58ee6419b1
130 changed files with 23347 additions and 885 deletions
Download Patch File Download Diff File Expand all files Collapse all files

231
docs/superpowers/specs/2026-06-12-workflow-engine-design.md Normal file
View File

@@ -0,0 +1,231 @@
# Workflow Engine — 重建设计
- 日期：2026-06-12
- 状态：已通过 brainstorming，待 writing-plans
- 范围：把被掏空的「清单推进」版 WorkflowTool 重建为**完整忠实的确定性 JS 脚本编排引擎**，并**独立成包**，解除与核心层的深度依赖。
## 1. 背景与现状
当前 `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts` 是个被阉割的版本：把 `.claude/workflows/` 里的 `.md`/`.yaml` 解析成清单，靠模型手动调用 `advance` 推进，**没有任何子 agent 编排能力**。
真正的 Workflow 能力是一个**确定性 JS 脚本编排引擎**：后台执行脚本，提供 `agent()`/`parallel()`/`pipeline()`/`phase()`/`log()` 钩子，真正 spawn 子 agent，支持 schema 校验、并发上限、journaling/resume、token budget、进度流。
### 可复用的现有基础设施
- `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts`：完整的后台任务生命周期（register/complete/fail/kill/skip/retry/orphan 清理）。**完好，复用**。
- `packages/builtin-tools/src/tools/AgentTool/runAgent.ts`：子 agent 执行核心（async generator，接收 `agentDefinition`+`promptMessages`+`toolUseContext`+`canUseTool`，运行完整 query 循环）。**作为 `agent()` 钩子后端**。
- `assembleToolPool`（`src/tools.ts`）：构建子 agent 工具池。
- `finalizeAgentTool` / `extractTextContent`（`agentToolUtils.ts`）：抽取 agent 最终消息 + usage。
- `WorkflowPermissionRequest.tsx`：权限 UI（核心侧 React，复用）。
- `tools.ts` 已用 `WORKFLOW_SCRIPTS` feature flag 接好注册位；`constants/tools.ts` 的 `CORE_TOOLS` 在 flag 开启时含 `workflow`。
## 2. 关键决策（brainstorming 结论）
1. **范围**：完整忠实引擎——全部钩子 + schema 结构化输出 + 并发上限（16/1000/4096）+ journaling/resume + token budget + worktree 隔离 + named-workflow 加载 + 进度流到 `/workflows`。
2. **包边界**：**严格端口适配（依赖倒置）**。`packages/workflow-engine/` 零 `src/*` / `builtin-tools` 运行时导入；只声明端口接口；核心侧提供一个 adapter 模块实现这些接口；`tools.ts` 装配时注入。
3. **文件模型**：`.claude/workflows/<name>.ts|.js|.mjs` 脚本文件 → 命名 workflow（`Workflow` 工具 `name` 参数解析到它）+ 生成 `/<name>` 斜杠命令；`/workflows` 变为实时进度查看器。**删除** 现有 `.md`/`.yaml` 清单逻辑。
4. **执行路径**：**async 函数包装 + 信号量 + 注入端口**（方案 A）。进程内 async 模型，与 `runAgent` 的 async generator 天然契合，端口可 mock 测试。不用 `vm` 沙箱或 worker 进程。
## 3. 架构与依赖方向
```
┌─────────────────────────────────────────────────────────────┐
│ packages/workflow-engine/ ← 新包，零 src/* 运行时导入 │
│ 声明端口（接口），持有引擎/钩子/并发/journal/budget/schema │
│ + 自包含的 WorkflowTool 描述符（zod schema/desc/prompt） │
└──────────────▲──────────────────────────▲───────────────────┘
│ 实现（implements） │ 注入（DI）
┌──────────────┴──────────────────────────┴───────────────────┐
│ src/workflow/ ← 核心侧薄层 │
│ adapter.ts: 用 runAgent/assembleToolPool/LocalWorkflowTask │
│ /AppState 实现端口 │
│ wiring.ts: createWorkflowTool(adapter) → 适配为 Tool │
│ 注册到 tools.ts（WORKFLOW_SCRIPTS flag 之后） │
└─────────────────────────────────────────────────────────────┘
```
包**不认识** `buildTool` / `toolUseContext` / `runAgent` / `Message` 类型。仅通过端口接口与不透明 host 句柄对话。
### 端口契约（包内 `ports.ts`）
| 端口 | 职责 | 核心侧 adapter 实现 |
|---|---|---|
| `AgentRunner` | `agent()` 后端：`runAgentToResult(params, hostHandle) → AgentRunResult` | 委托 `runAgent` + `assembleToolPool`；schema 时注入 StructuredOutput 工具；`finalizeAgentTool` 抽取最终消息 + usage |
| `ProgressEmitter` | `emit(event)` 推进度事件 | 写 `LocalWorkflowTaskState.progress` + `rootSetAppState` |
| `TaskRegistrar` | 后台任务生命周期 + 读 `pendingAgentAction` | 复用 `LocalWorkflowTask` API |
| `JournalStore` | journal 读写（按 runId） | 文件 fs（`.claude/workflow-runs/<runId>/journal.jsonl`），走端口便于 mock |
| `PermissionGate` | `agent()` 前置权限/取消检查 | abort signal + `pendingAgentAction` |
| `Logger` | 调试日志 + 遥测 | `logForDebugging` / `logEvent` |
**不透明 host 句柄**：`HostHandle = { readonly __workflowHost: unique symbol }`。核心侧每次工具调用构造一个句柄（内含 `toolUseContext`/`canUseTool`/`agentId` 等），包内绝不检视，只透传给 `AgentRunner`；adapter 把它 cast 回核心上下文。包对核心类型零依赖的唯一缝隙，且是不透明的。
### 包结构
```
packages/workflow-engine/
package.json @claude-code-best/workflow-engine (workspace:*)
tsconfig.json
src/
index.ts 公共导出
ports.ts 端口接口 + HostHandle
types.ts 纯类型（WorkflowInput/Run/JournalEntry/ProgressEvent/AgentRunParams…）
tool/
WorkflowTool.ts createWorkflowTool(ports) → 自包含描述符
schema.ts 输入 schema（script/name/scriptPath/args/resumeFromRunId/desc/title）
constants.ts WORKFLOW_TOOL_NAME 等
engine/
runWorkflow.ts 引擎入口：校验/包装/执行/journal/resume
context.ts 执行上下文（端口/信号量/budget/journal/计数器/host）
hooks.ts agent/parallel/pipeline/phase/log/workflow 实现
script.ts meta 字面量提取 + async 包装 + 沙箱 shim
concurrency.ts Semaphore + 上限（16 / 1000 总 / 4096 每次调用）
journal.ts hash + 读/写 journal
budget.ts budget 累加器（total/spent/remaining）
structuredOutput.ts JSON Schema → 结果校验（纯函数）
namedWorkflows.ts name → .claude/workflows/<name>.ts|js|mjs 解析（仅 fs）
constants.ts 目录/上限常量
progress/events.ts ProgressEvent 类型 + emit 委托
__tests__/ …
```
核心侧薄层：`src/workflow/adapter.ts` + `src/workflow/wiring.ts`；`packages/builtin-tools` 从新包 re-export 描述符。
## 4. 引擎内部
### 4.1 钩子语义
| 钩子 | 语义 | 失败行为 |
|---|---|---|
| `agent(prompt, opts?)` | 取信号量 → 查 journal（命中即返回缓存）→ 调 `AgentRunner` → 写 journal → 返回 | 终态 API 错耗尽重试 → `null`（不抛） |
| `parallel(thunks)` | **屏障**：`Promise.all` 所有 thunk（每个内部各自过信号量）；wall-clock = 最慢项 | 单项抛错/agent 错 → 该项 `null`；调用本身永不 reject |
| `pipeline(items, …stages)` | **无屏障**：每项跑 `stage1→stage2→…` 异步链，多链并发；stage 回调收 `(prevResult, originalItem, index)` | 某 stage 抛错 → 该项 `null`、跳过后续 stage |
| `phase(title)` | 开启新阶段，后续 agent/log 归入该组直到下次 `phase()` | — |
| `log(message)` | 向用户发一行旁白进度 | — |
| `workflow(nameOrRef, args?)` | 内联跑子 workflow，返回其返回值；共享并发/计数/budget；`/workflows` 显示为 `▸ name` 组 | 子 workflow 内再嵌套 → 抛错（仅一层） |
`agent` 的 `opts`：`label`、`phase`（显式分组）、`schema`（JSON Schema）、`model`、`isolation:'worktree'`、`agentType`（自定义子 agent 类型）、`allowedTools`。
- 无 schema 返回 `string`；有 schema 返回校验对象；用户 skip / agent 终态死亡 → 返回 `null`。
### 4.2 并发与上限（`concurrency.ts`）
- `Semaphore` 许可数 = `min(16, cpuCores - 2)`；`agent()` 取 1。
- 单个 workflow 生命周期**总 agent 数 ≤ 1000** → 超出抛错。
- 单次 `parallel`/`pipeline` 调用 **items ≤ 4096** → 超出抛错（显式错误，不静默截断）。
### 4.3 Journal / Resume（`journal.ts`）
- journal = 按**执行顺序**的 `{ key, result }` 列表，存 `.claude/workflow-runs/<runId>/journal.jsonl`。
- `key` = `hash(prompt + canonical(opts 去掉 label/phase 等纯展示字段))`。
- 命中：`agent()` 先算 key，与 journal 下一项 key 比对 → **匹配则返回缓存并前进**，不匹配则丢弃后续 journal、现场重跑。
- 因 JS 去掉 `Date.now`/`random` 后确定，执行顺序确定 → 自然得到「最长未变前缀命中、首个发散点之后全重跑」。
- `resumeFromRunId`：载入该 run 的 journal 重放。脚本源码 hash 一致 → 100% 命中；脚本改动 → 全重跑。脚本 hash 存入 run 记录。
### 4.4 Budget（`budget.ts`）
- `budget.total`：来自用户 `+500k` 式 turn 级 token 指令，由 **host/turn 上下文注入**（adapter 从 turn 的 token 指令读取，经 `HostHandle` 传入），**不是** 工具 input 参数。无指令则 `null`。
- `budget.spent()`：本 turn 所有 agent 输出 token 之和（`AgentRunResult.usage`，adapter 从 subagent usage 填）。
- `budget.remaining()`：`max(0, total - spent)`，无 total 则 `Infinity`。
- **硬上限**：`spent()` 达 `total` 后，`agent()` 抛错。预算是主循环与 workflow 共享池。
### 4.7 AgentRunResult 类型（`types.ts`）
`AgentRunner.runAgentToResult` 的返回，包内明确定义为联合类型：
```ts
type AgentRunResult =
| { kind: 'ok'; output: string | object; usage: { outputTokens: number } }
| { kind: 'skipped' } // 用户 skip → agent() 返回 null
| { kind: 'dead' } // 终态 API 错耗尽重试 → agent() 返回 null
```
`output` 为 `string`（无 schema）或已校验对象（有 schema）。`agent()` 据此映射：`ok`→返回 output，`skipped`/`dead`→返回 `null`。
### 4.5 脚本包装与沙箱（`script.ts`）
1. 提取 `export const meta = { … }`——**必须是纯字面量**（无变量/插值/展开），解析为对象；缺失或非字面量 → 抛错。
2. 剥离 `export const meta` 语句。
3. 剩余 body（含顶层 `return`）包进 `async function(agent, parallel, pipeline, phase, log, workflow, args, budget, Date, Math){ <body> }`。
4. 以**抛异常的 shim** 传入 `Date`（`now()`/无参 `new Date()` 抛）、`Math`（`random()` 抛）——靠函数参数 shadow 全局，使裸 `Date.now()` 命中 shim。这是确定性保障，非密码学级沙箱（与真实引擎意图一致：阻断 resume 破坏性的非确定性）。
5. meta 的 `phases` 可用于进度预声明（可选）。
### 4.6 进度事件（`progress/events.ts`）
`ProgressEmitter.emit(event)` 类型：`run_started`、`phase_started/done`、`agent_started/done{label,phase,result摘要}`、`log`、`run_done{returnValue/status}`。adapter 写入 task 进度结构 + AppState，`/workflows` 视图消费。
## 5. 错误处理
| 场景 | 行为 |
|---|---|
| 脚本无 `meta` / `meta` 非字面量 / 语法错 | 引擎抛错 → task `failed` → 通知带错误信息 |
| `Date.now`/`Math.random`/`new Date()` | shim 抛 → 冒泡为脚本错误 → task failed |
| `agent()` 终态 API 错（重试耗尽） | 返回 `null`，**不杀** workflow |
| `parallel`/`pipeline` 单项抛错 | 该项 `null`，workflow 继续 |
| budget 耗尽 | `agent()` 抛错（脚本可 try/catch） |
| 并发/1000/4096 上限 | 抛错 |
| kill（abort） | signal 传播；`agent()` 检查 signal；workflow 停；task `killed`；通知 partial |
| 工具调用层（`call`）脚本非法 | 直接返回错误给模型（不进后台） |
## 6. 测试策略
包内全量单测，**无需真实 LLM**（mock 端口——解耦的核心收益）：
- `engine.test.ts`：mock `AgentRunner`（按 prompt 返回预设结果）端到端跑脚本，断言返回值 + 进度事件序列。
- `hooks.test.ts`：parallel 单项错→null、pipeline 无屏障顺序、agent schema 校验、skip/dead→null。
- `concurrency.test.ts`：信号量限并发、1000/4096 上限抛错。
- `journal.test.ts`：hash 稳定、resume 命中前缀、脚本变更全重跑、中途发散重跑尾部。
- `budget.test.ts`：spent 累加、触顶抛错。
- `script.test.ts`：meta 字面量提取、非字面量/语法错、shim 抛。
- `structuredOutput.test.ts`、`namedWorkflows.test.ts`。
核心侧最小冒烟：adapter 用 `runAgent` 真接线的重 mock 测试；wiring 注册测试。重量级逻辑都在包内。可选：`tests/integration/` 加一个 workflow tool-chain 集成测试（feature-gated）。
## 7. 核心侧实现
### 7.1 adapter（`src/workflow/adapter.ts`）
`createWorkflowAdapter()` 返回端口实现：
- **AgentRunner.runAgentToResult(params, hostHandle)**：cast 句柄→`{toolUseContext, canUseTool, assistantMessage}`；按 `params.agentType` 从 registry 解析 agentDefinition（缺省=通用 workflow 子 agent）；`assembleToolPool`；有 schema→注入 StructuredOutput 工具+系统指令；调 `runAgent` 收消息→`finalizeAgentTool` 抽 text+usage；schema→解析校验返回对象；处理 `pendingAgentAction`(skip)→`null`、终态死亡→`null`；返回 `{kind:'ok', text/object, usage}`。
- **ProgressEmitter**：写 `LocalWorkflowTaskState.progress` + `rootSetAppState`。
- **TaskRegistrar**：复用现有 `registerLocalWorkflowTask/complete/fail/kill` + 读 `pendingAgentAction`。
- **JournalStore / Logger / PermissionGate**：fs / `logForDebugging`+`logEvent` / abort+pendingAction。
### 7.2 wiring（`src/workflow/wiring.ts`）
- `createWorkflowTool()`：建 adapter → 调包的 `createWorkflowTool(adapter)` 得描述符 → 包成 `buildTool` 兼容 `Tool` 返回。
- `tools.ts`：`const WorkflowTool = feature('WORKFLOW_SCRIPTS') ? require('./workflow/wiring.js').createWorkflowTool() : null`（替换现有清单版）。
`call` 流程：校验脚本（inline/file/named 解析）→ meta 校验失败直接返错给模型 → 持久化脚本 + 算 hash → resume 则载入 run+journal → 注册后台 task → **立即返回 `{runId, scriptPath}`** → 脱离执行引擎、流进度 → 完成时 complete + 通知（返回值/错误）。
## 8. 现有文件迁移
| 文件 | 处理 |
|---|---|
| `builtin-tools/.../WorkflowTool/WorkflowTool.ts`（清单版） | 删除，逻辑移入新包 |
| `constants.ts`（WORKFLOW_TOOL_NAME） | 移入包 `tool/constants.ts`，core 侧 re-export |
| `WorkflowPermissionRequest.tsx`（React UI） | 移到 `src/workflow/`（依赖 src 权限组件，属核心侧） |
| `createWorkflowCommand.ts`（.md/.yaml 扫描） | 改为扫 `.ts/.js/.mjs` → 生成 `/<name>` 命令，调用时以脚本启动引擎 |
| `bundled/index.ts`（no-op） | 保留为包的 bundled-workflow 扩展点 |
| `src/utils/workflowRuns.ts`（清单记录） | 重写为 run+journal 模型（或并入包 JournalStore） |
| `src/commands/workflows/index.ts` | 改为**实时进度查看器**，复用 `WorkflowDetailDialog.tsx` |
| `src/tasks.ts` LocalWorkflowTask 门控 | 保持不变 |
| `constants/tools.ts` CORE_TOOLS 含 `workflow` | 保持 |
## 9. 工作分解（writing-plans 将细化）
1. 新建包 `packages/workflow-engine/`（package.json/tsconfig/类型/端口/常量）。
2. 引擎核心：script 包装、concurrency、journal、budget、structuredOutput、namedWorkflows。
3. 钩子实现 + runWorkflow 编排 + 进度事件。
4. 自包含工具描述符（schema/desc/prompt/result 映射）。
5. 包内全量单测。
6. 核心侧 adapter + wiring + 句柄构造。
7. 迁移现有文件、改 `/workflows` 为进度查看器、改 named-workflow 命令。
8. `bun run precheck` 零错误；手动 dev 冒烟。
## 10. 非目标 / 风险
- **非密码学沙箱**：函数参数 shadow 全局 `Date`/`Math`，`globalThis.Date` 仍可达。可接受——目标是阻断 resume 破坏性的非确定性，不是隔离恶意代码。若未来需强隔离再上 `vm`/worker（方案 B/C）。
- **resume 正确性依赖确定性执行**：用户脚本若绕过 shim 用 `globalThis.Date` 制造非确定性，resume 可能命中错缓存。属可接受的边界，文档提示。
- **预算共享语义**：`budget.spent()` 与主循环的 token 计数共享，需 adapter 正确上报 subagent usage；若 provider 不报 usage 则 budget 降级为 `Infinity`。
- **StructuredOutput 工具**：核心侧需存在/实现一个按 JSON Schema 强制结构化输出的子 agent 工具（注入 + 解析）。若当前无现成实现，wiring 阶段补一个最小版本。

200
docs/superpowers/specs/2026-06-13-workflow-panel-redesign.md Normal file
View File

@@ -0,0 +1,200 @@
# `/workflows` 面板重设计：顶 tab + 左 phase 侧栏 + 右 agent 列表
> 状态：草案（待用户 review → writing-plans 产出实施计划）
> 日期：2026-06-13
> 关联：上一期整体设计 `docs/superpowers/specs/2026-06-13-workflow-tui-ultracode-design.md`（其 §9 双栏面板已实现，本 spec 取代该 §9 的面板部分）
---
## 1. 背景与现状
上一期整体设计已落地：`WorkflowService` 门面、`claude-code` AgentAdapter、进度 bus+store、引擎 `agentId` 关联、`/ultracode` skill 全部实现完成。`/workflows` 面板按旧 spec §9 实现为**双栏**：
- `src/workflow/panel/WorkflowsPanel.tsx`：左栏 `WorkflowList`（扁平 run 列表）+ 右栏 `WorkflowDetail`（phase 横条 + 扁平 agent 列表）。
- 键位 `j/k` 在左栏选 run，选中即聚焦、右栏随之切换。
**问题**：监控「单个 run 内多 phase / 多 agent」时，左右是「run 列表 vs 单 run 详情」——切换 run 与查看 agent 共用一对键位；phase 仅一行横条，无法按 phase 筛选 agent；多个 run 间切换要上下翻列表。
本 spec 把面板**原地重写**为三区焦点模型：**顶部 run tab + 左 phase 筛选侧栏 + 右 agent 列表**，贴合「聚焦一个 run → 按 phase 收窄 → 看 agent 状态」的实际监控动线。
## 2. 目标与非目标
**目标**
1. 顶 tab 按 **run**（同名脚本多次跑会多个 tab，标签附 runId 短码消歧如 `review-changes#a3f`）。
2. 左 phase 侧栏：合并 `meta` 声明 phase（pending `○`）与 store phase（running `●` / done `✓`）+ 一个固定 `All` 项；选中即决定右栏筛选。
3. 右 agent 列表：按选中 phase 过滤（`All` 则全显）；状态用颜色 + 文字标记（`object` / `text` / `dead`）。
4. 焦点轮转键位：`Tab`/`Shift+Tab` 切 run、`←/→` 切 phases↔agents、`↑/↓` 列内移动、`x` kill / `r` resume / `q`/`Esc` quit。
5. 视觉极简：无内框，左右栏中间**一条竖线**；选中/光标行用**底色条**（`backgroundColor`，非反白）；聚焦列标题橙粗、非聚焦灰。
6. 显示 **pending phase**（meta 声明但未启动）。
**非目标**
- 不改引擎包（`run_started` 已携带 `meta.phases`，见 §3）。
- 不动 `service`/`registry`/`backends`/`ports`/`wiring`/Workflow 工具/`/ultracode`。
- 不做 per-agent 操作 UI（仅 run 级 `kill`/`resume`）。
- 不改 `BackgroundTasksDialog`（Shift+Down）跳转协议。
- 不做 agent 输出详情抽屉（留未来）。
## 3. 关键发现：零引擎改动
`ProgressEvent.run_started` **已携带** `meta: WorkflowMeta | null`（`packages/workflow-engine/src/types.ts:60-66`，emit 点 `engine/runWorkflow.ts:72-77`），且 `WorkflowMeta.phases` 已是 `Array<{ title: string; detail?: string }>`（`types.ts:22-27`）。
→ pending phase 所需数据全在事件流里。面板只需让 store 在 `run_started` 时落地 `declaredPhases`，再与 store 的 `run.phases`（running/done）合并即可。**不触碰引擎包**。
## 4. 数据模型变更（`src/workflow/progress/store.ts`）
- `RunProgress` 新增字段：
```ts
declaredPhases: string[] // 来自 run_started.meta.phases[].title；无 meta → []
```
- reducer `run_started` 分支补一行（当前第 74-77 行只用 `event.workflowName`，忽略 `event.meta`）：
```ts
case 'run_started':
p.workflowName = event.workflowName
p.status = 'running'
p.declaredPhases = event.meta?.phases?.map(ph => ph.title) ?? []
break
```
- `ensure()` 初始化 `declaredPhases: []`。
- 其余 reducer 分支、`AgentProgress`、快照排序逻辑不变。
**测试**（`progress/store.test.ts` 或对应测试文件）：
- `run_started` 带 `meta.phases` → `declaredPhases` 落地且顺序保留。
- `run_started` 的 `meta` 为 `null` → `declaredPhases === []`。
- 已有 `agentId` 关联、phase 切换、`run_done` 终态用例保持绿。
## 5. 面板布局（定稿 ASCII）
焦点在 PHASES（默认进入态）：
```
╭─ Workflows ──────────────────────────── 2 running · 3 done ─╮
│ │
│ ● review-changes ✓ find-bugs ● migrate-auth │
│ ═════════════════ ← Tab / Shift+Tab 切 │
│ │
│ PHASES │ AGENTS · Review │
│ │ │
│ ✓ Find 3/3 │ ● review:bugs running │
│ ▓▶● Review 2/5▓ │ ● review:perf running │
│ ○ Verify 0/2 │ ✓ review:sec object │
│ │ ✗ review:api dead │
│ All 10 │ ✓ review:auth text │
│ │ │
│ Tab 切 run · ←/→ 切焦点 · ↑/↓ 移动 · x kill · q quit │
╰─────────────────────────────────────────────────────────────╯
```
按 `→` 焦点到 AGENTS（`PHASES` 标题变灰、`AGENTS` 变橙、光标行铺底色）：
```
phases (灰) │ AGENTS · Review (橙)
│
✓ Find 3/3 │ ● review:bugs running
● Review 2/5 │ ▓● review:perf running ▓ ← 光标行底色
○ Verify 0/2 │ ✓ review:sec object
All 10 │ ✗ review:api dead
```
## 6. 焦点与键位状态机
**面板状态**（`WorkflowsPanel` 内 `useState`）：
| 状态 | 含义 | 默认 |
|---|---|---|
| `activeRunId` | 当前 tab 的 runId | 首个 run（无则 null） |
| `focusColumn` | `'phases'` \| `'agents'` | `'phases'`（该 run 无任何 phase 则 `'agents'`） |
| `selectedPhaseIndex` | phase 侧栏选中项（`0` = `All`） | `0` |
| `selectedAgentIndex` | agent 列表光标行 | `0` |
**键位**：
| 键 | 作用 |
|---|---|
| `Tab` / `Shift+Tab` | 切顶部 run tab（正/反）；切 tab 时重置 `selectedPhaseIndex=0`、`selectedAgentIndex=0`、`focusColumn` 回默认 |
| `←` / `→` | `phases` ↔ `agents` 焦点切换（tabs 不参与左右，由 `Tab` 管） |
| `↑` / `↓` | 当前焦点列内移动选中（phase 改筛选；agent 滚光标） |
| `x` | kill 当前 tab 的 run |
| `r` | resume 当前 tab 的 run（缺 `canUseTool` 时 `onDone` 提示用 `/<name> resume`） |
| `q` / `Esc` | 退出面板 |
**夹紧**：复用 `WorkflowsPanel` 已导出的 `clampSelected`——切 tab / 列表变动后把 `selectedPhaseIndex`、`selectedAgentIndex` 夹到有效区间。
**筛选语义**：`selectedPhaseIndex===0`（`All`）→ 右栏显示全部 agent；否则按 `phase === 选中 phase title` 过滤。
## 7. 组件拆分（`src/workflow/panel/`）
| 文件 | 动作 | 职责 |
|---|---|---|
| `WorkflowsPanel.tsx` | 重写 | 订阅 store、持焦点状态、渲染 `TabsBar` + 左右双栏、绑 `useWorkflowKeyboard`；保留导出 `clampSelected` |
| `TabsBar.tsx` | 新建 | 顶部 run tab 行（状态点 + 名 + runId 短码；当前 tab 橙色 `═══` 下划线） |
| `PhaseSidebar.tsx` | 新建 | 左 phase 列表：`All` + 合并 `declaredPhases`（pending `○`）与 `run.phases`（`●`/`✓`），每行附 `done/total` agent 计数 |
| `AgentList.tsx` | 新建 | 右 agent 列表：按选中 phase 过滤；状态色 + 行尾 `object`/`text`/`dead` 文字标记 |
| `status.ts` | 新建 | 共享状态→字符/颜色映射（`STATUS_DOT`、phase/agent mark 函数），三组件复用 |
| `useWorkflowKeyboard.ts` | 改写 | 焦点模型键位（见 §6） |
| `WorkflowList.tsx` | 删除 | run 列表职责迁入 `TabsBar` |
| `WorkflowDetail.tsx` | 删除 | phase+agent 职责拆入 `PhaseSidebar`+`AgentList` |
| `panelCall.ts` | 不变 | local-jsx 入口仍渲染 `WorkflowsPanel` |
**外部接口不变**：`/workflows` 命令注册、`panelCall`、`getWorkflowService()` 订阅协议、`BackgroundTasksDialog` 跳转均不动。
## 8. 视觉规则
- **无内框**：左右两栏中间一条 `│` 竖线，仅此一条分割线；最外层保留最朴素的 round border 界定面板。
- **聚焦列**：标题 `claude` 橙粗体；非聚焦列标题 `subtle` 灰。
- **选中/光标行**：整行铺 `backgroundColor="claude"` 橙底（ASCII 用 `▓` 示意），**文字色不变**，状态点保留各自颜色。
- **状态色**（沿用现有 Ink theme token，无新增）：
| 元素 | 状态 | 字符 | 颜色 |
|---|---|---|---|
| Tab (run) | running | `●` | `warning` |
| | completed | `✓` | `success` |
| | failed | `✗` | `error` |
| | killed | `■` | `subtle` |
| | 当前 | `═══` | `claude` 下划线 |
| Phase | running | `●` | `warning` |
| | done | `✓` | `success` |
| | pending | `○` | `subtle` |
| | 选中 | `▶` | `claude` + 底色 |
| Agent | running | `●` | `warning` |
| | done·text | `✓` | `success` + 行尾 `text` |
| | done·object | `✓` | `success` + 行尾 `object` |
| | dead | `✗` | `error` + 行尾 `dead` |
- **object 标记**：行尾纯文字 `object`（不用 `◆` 符号）。
- **左窄右宽**：phase 栏约 20%、agent 栏约 80%（或固定 phase 栏 ~20 字符，agent 栏吃剩余宽度）。
## 9. 测试策略
- **store**：`declaredPhases` 落地 + null meta 回归（§4）。
- **面板**（`WorkflowsPanel.test.tsx`，ink-testing-library，遵循仓库 mock 规范）：
- 多 run → tab 渲染 + 当前 tab 下划线；`Tab`/`Shift+Tab` 切换且重置子选择。
- `←/→` 切 `focusColumn`（标题颜色 / 光标落点）。
- phase 侧栏选中 → 右栏 agent 按 phase 过滤；`All` 显全部。
- pending phase（`declaredPhases` 有、store 无）显示 `○`。
- 选中行/光标行底色条（断言对应 `<Text backgroundColor>`）。
- `x` kill、`r` resume（mock service）、`q`/`Esc` 退出。
- 空态（无 run）：占位文案 + `n` 提示。
- 订阅刷新：store 变更后面板重渲染（agent 状态 running→done）。
- **回归**：`bun run precheck` 零错误；现有 workflow 集成测试（canonical scripts / review / loop / resume）保持绿。
## 10. 里程碑与提交切分
每个里程碑结束 `bun run precheck` 必须零错误。
1. **M1 store**：`RunProgress.declaredPhases` + reducer `run_started` 落地 + 测试。
2. **M2 panel 组件**：新建 `status.ts` / `TabsBar` / `PhaseSidebar` / `AgentList`；`WorkflowsPanel` 重写为焦点状态机；`useWorkflowKeyboard` 改焦点模型；删除 `WorkflowList` / `WorkflowDetail`。
3. **M3 测试**：`WorkflowsPanel.test.tsx` 全量用例 + precheck 绿。
4. **M4 文档**：`docs/features/workflow-scripts.md` §六 更新为三区布局/键位；旧 spec §六/§9 加注「面板部分已被 `2026-06-13-workflow-panel-redesign.md` 取代」。
## 11. 未做 / 未来工作
- per-agent skip/retry 的 UI 接线（引擎 seam 已在）。
- agent 详情抽屉：选中 agent 后展开其 prompt/输出/token。
- 多 run 并排对比视图。
- `declaredPhases` 与实际 `phase()` 调用不一致时的告警（如脚本声明了 phase 却没调用）。

191
docs/superpowers/specs/2026-06-13-workflow-run-state-persistence-design.md Normal file
View File

@@ -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 时再引入

287
docs/superpowers/specs/2026-06-13-workflow-tui-ultracode-design.md Normal file
View File

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

394
docs/superpowers/specs/2026-06-14-effort-panel-design.md Normal file
View File

@@ -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` 零错误