mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-15 12:55:51 +00:00
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>
This commit is contained in:
claude-code-best
3388
docs/superpowers/plans/2026-06-12-workflow-engine.md
Normal file
3388
docs/superpowers/plans/2026-06-12-workflow-engine.md
Normal file
File diff suppressed because it is too large
Load Diff
1170
docs/superpowers/plans/2026-06-13-workflow-panel-redesign.md
Normal file
1170
docs/superpowers/plans/2026-06-13-workflow-panel-redesign.md
Normal file
File diff suppressed because it is too large
Load Diff
1113
docs/superpowers/plans/2026-06-13-workflow-run-state-persistence.md
Normal file
1113
docs/superpowers/plans/2026-06-13-workflow-run-state-persistence.md
Normal file
File diff suppressed because it is too large
Load Diff
2022
docs/superpowers/plans/2026-06-13-workflow-tui-ultracode.md
Normal file
2022
docs/superpowers/plans/2026-06-13-workflow-tui-ultracode.md
Normal file
File diff suppressed because it is too large
Load Diff
897
docs/superpowers/plans/2026-06-14-effort-panel-basic.md
Normal file
897
docs/superpowers/plans/2026-06-14-effort-panel-basic.md
Normal file
@@ -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 中标为可选增强，本计划不做）
|
||||
|
||||
这些不影响主功能，第一版以"能用、稳定、可提交"为目标。
|
||||
@@ -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`
|
||||
231
docs/superpowers/specs/2026-06-12-workflow-engine-design.md
Normal file
231
docs/superpowers/specs/2026-06-12-workflow-engine-design.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# Workflow Engine — 重建设计
|
||||
|
||||
- 日期：2026-06-12
|
||||
- 状态：已通过 brainstorming，待 writing-plans
|
||||
- 范围：把被掏空的「清单推进」版 WorkflowTool 重建为**完整忠实的确定性 JS 脚本编排引擎**，并**独立成包**，解除与核心层的深度依赖。
|
||||
|
||||
## 1. 背景与现状
|
||||
|
||||
当前 `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts` 是个被阉割的版本：把 `.claude/workflows/` 里的 `.md`/`.yaml` 解析成清单，靠模型手动调用 `advance` 推进，**没有任何子 agent 编排能力**。
|
||||
|
||||
真正的 Workflow 能力是一个**确定性 JS 脚本编排引擎**：后台执行脚本，提供 `agent()`/`parallel()`/`pipeline()`/`phase()`/`log()` 钩子，真正 spawn 子 agent，支持 schema 校验、并发上限、journaling/resume、token budget、进度流。
|
||||
|
||||
### 可复用的现有基础设施
|
||||
|
||||
- `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts`：完整的后台任务生命周期（register/complete/fail/kill/skip/retry/orphan 清理）。**完好，复用**。
|
||||
- `packages/builtin-tools/src/tools/AgentTool/runAgent.ts`：子 agent 执行核心（async generator，接收 `agentDefinition`+`promptMessages`+`toolUseContext`+`canUseTool`，运行完整 query 循环）。**作为 `agent()` 钩子后端**。
|
||||
- `assembleToolPool`（`src/tools.ts`）：构建子 agent 工具池。
|
||||
- `finalizeAgentTool` / `extractTextContent`（`agentToolUtils.ts`）：抽取 agent 最终消息 + usage。
|
||||
- `WorkflowPermissionRequest.tsx`：权限 UI（核心侧 React，复用）。
|
||||
- `tools.ts` 已用 `WORKFLOW_SCRIPTS` feature flag 接好注册位；`constants/tools.ts` 的 `CORE_TOOLS` 在 flag 开启时含 `workflow`。
|
||||
|
||||
## 2. 关键决策（brainstorming 结论）
|
||||
|
||||
1. **范围**：完整忠实引擎——全部钩子 + schema 结构化输出 + 并发上限（16/1000/4096）+ journaling/resume + token budget + worktree 隔离 + named-workflow 加载 + 进度流到 `/workflows`。
|
||||
2. **包边界**：**严格端口适配（依赖倒置）**。`packages/workflow-engine/` 零 `src/*` / `builtin-tools` 运行时导入；只声明端口接口；核心侧提供一个 adapter 模块实现这些接口；`tools.ts` 装配时注入。
|
||||
3. **文件模型**：`.claude/workflows/<name>.ts|.js|.mjs` 脚本文件 → 命名 workflow（`Workflow` 工具 `name` 参数解析到它）+ 生成 `/<name>` 斜杠命令；`/workflows` 变为实时进度查看器。**删除** 现有 `.md`/`.yaml` 清单逻辑。
|
||||
4. **执行路径**：**async 函数包装 + 信号量 + 注入端口**（方案 A）。进程内 async 模型，与 `runAgent` 的 async generator 天然契合，端口可 mock 测试。不用 `vm` 沙箱或 worker 进程。
|
||||
|
||||
## 3. 架构与依赖方向
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ packages/workflow-engine/ ← 新包，零 src/* 运行时导入 │
|
||||
│ 声明端口（接口），持有引擎/钩子/并发/journal/budget/schema │
|
||||
│ + 自包含的 WorkflowTool 描述符（zod schema/desc/prompt） │
|
||||
└──────────────▲──────────────────────────▲───────────────────┘
|
||||
│ 实现（implements） │ 注入（DI）
|
||||
┌──────────────┴──────────────────────────┴───────────────────┐
|
||||
│ src/workflow/ ← 核心侧薄层 │
|
||||
│ adapter.ts: 用 runAgent/assembleToolPool/LocalWorkflowTask │
|
||||
│ /AppState 实现端口 │
|
||||
│ wiring.ts: createWorkflowTool(adapter) → 适配为 Tool │
|
||||
│ 注册到 tools.ts（WORKFLOW_SCRIPTS flag 之后） │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
包**不认识** `buildTool` / `toolUseContext` / `runAgent` / `Message` 类型。仅通过端口接口与不透明 host 句柄对话。
|
||||
|
||||
### 端口契约（包内 `ports.ts`）
|
||||
|
||||
| 端口 | 职责 | 核心侧 adapter 实现 |
|
||||
|---|---|---|
|
||||
| `AgentRunner` | `agent()` 后端：`runAgentToResult(params, hostHandle) → AgentRunResult` | 委托 `runAgent` + `assembleToolPool`；schema 时注入 StructuredOutput 工具；`finalizeAgentTool` 抽取最终消息 + usage |
|
||||
| `ProgressEmitter` | `emit(event)` 推进度事件 | 写 `LocalWorkflowTaskState.progress` + `rootSetAppState` |
|
||||
| `TaskRegistrar` | 后台任务生命周期 + 读 `pendingAgentAction` | 复用 `LocalWorkflowTask` API |
|
||||
| `JournalStore` | journal 读写（按 runId） | 文件 fs（`.claude/workflow-runs/<runId>/journal.jsonl`），走端口便于 mock |
|
||||
| `PermissionGate` | `agent()` 前置权限/取消检查 | abort signal + `pendingAgentAction` |
|
||||
| `Logger` | 调试日志 + 遥测 | `logForDebugging` / `logEvent` |
|
||||
|
||||
**不透明 host 句柄**：`HostHandle = { readonly __workflowHost: unique symbol }`。核心侧每次工具调用构造一个句柄（内含 `toolUseContext`/`canUseTool`/`agentId` 等），包内绝不检视，只透传给 `AgentRunner`；adapter 把它 cast 回核心上下文。包对核心类型零依赖的唯一缝隙，且是不透明的。
|
||||
|
||||
### 包结构
|
||||
|
||||
```
|
||||
packages/workflow-engine/
|
||||
package.json @claude-code-best/workflow-engine (workspace:*)
|
||||
tsconfig.json
|
||||
src/
|
||||
index.ts 公共导出
|
||||
ports.ts 端口接口 + HostHandle
|
||||
types.ts 纯类型（WorkflowInput/Run/JournalEntry/ProgressEvent/AgentRunParams…）
|
||||
tool/
|
||||
WorkflowTool.ts createWorkflowTool(ports) → 自包含描述符
|
||||
schema.ts 输入 schema（script/name/scriptPath/args/resumeFromRunId/desc/title）
|
||||
constants.ts WORKFLOW_TOOL_NAME 等
|
||||
engine/
|
||||
runWorkflow.ts 引擎入口：校验/包装/执行/journal/resume
|
||||
context.ts 执行上下文（端口/信号量/budget/journal/计数器/host）
|
||||
hooks.ts agent/parallel/pipeline/phase/log/workflow 实现
|
||||
script.ts meta 字面量提取 + async 包装 + 沙箱 shim
|
||||
concurrency.ts Semaphore + 上限（16 / 1000 总 / 4096 每次调用）
|
||||
journal.ts hash + 读/写 journal
|
||||
budget.ts budget 累加器（total/spent/remaining）
|
||||
structuredOutput.ts JSON Schema → 结果校验（纯函数）
|
||||
namedWorkflows.ts name → .claude/workflows/<name>.ts|js|mjs 解析（仅 fs）
|
||||
constants.ts 目录/上限常量
|
||||
progress/events.ts ProgressEvent 类型 + emit 委托
|
||||
__tests__/ …
|
||||
```
|
||||
|
||||
核心侧薄层：`src/workflow/adapter.ts` + `src/workflow/wiring.ts`；`packages/builtin-tools` 从新包 re-export 描述符。
|
||||
|
||||
## 4. 引擎内部
|
||||
|
||||
### 4.1 钩子语义
|
||||
|
||||
| 钩子 | 语义 | 失败行为 |
|
||||
|---|---|---|
|
||||
| `agent(prompt, opts?)` | 取信号量 → 查 journal（命中即返回缓存）→ 调 `AgentRunner` → 写 journal → 返回 | 终态 API 错耗尽重试 → `null`（不抛） |
|
||||
| `parallel(thunks)` | **屏障**：`Promise.all` 所有 thunk（每个内部各自过信号量）；wall-clock = 最慢项 | 单项抛错/agent 错 → 该项 `null`；调用本身永不 reject |
|
||||
| `pipeline(items, …stages)` | **无屏障**：每项跑 `stage1→stage2→…` 异步链，多链并发；stage 回调收 `(prevResult, originalItem, index)` | 某 stage 抛错 → 该项 `null`、跳过后续 stage |
|
||||
| `phase(title)` | 开启新阶段，后续 agent/log 归入该组直到下次 `phase()` | — |
|
||||
| `log(message)` | 向用户发一行旁白进度 | — |
|
||||
| `workflow(nameOrRef, args?)` | 内联跑子 workflow，返回其返回值；共享并发/计数/budget；`/workflows` 显示为 `▸ name` 组 | 子 workflow 内再嵌套 → 抛错（仅一层） |
|
||||
|
||||
`agent` 的 `opts`：`label`、`phase`（显式分组）、`schema`（JSON Schema）、`model`、`isolation:'worktree'`、`agentType`（自定义子 agent 类型）、`allowedTools`。
|
||||
|
||||
- 无 schema 返回 `string`；有 schema 返回校验对象；用户 skip / agent 终态死亡 → 返回 `null`。
|
||||
|
||||
### 4.2 并发与上限（`concurrency.ts`）
|
||||
|
||||
- `Semaphore` 许可数 = `min(16, cpuCores - 2)`；`agent()` 取 1。
|
||||
- 单个 workflow 生命周期**总 agent 数 ≤ 1000** → 超出抛错。
|
||||
- 单次 `parallel`/`pipeline` 调用 **items ≤ 4096** → 超出抛错（显式错误，不静默截断）。
|
||||
|
||||
### 4.3 Journal / Resume（`journal.ts`）
|
||||
|
||||
- journal = 按**执行顺序**的 `{ key, result }` 列表，存 `.claude/workflow-runs/<runId>/journal.jsonl`。
|
||||
- `key` = `hash(prompt + canonical(opts 去掉 label/phase 等纯展示字段))`。
|
||||
- 命中：`agent()` 先算 key，与 journal 下一项 key 比对 → **匹配则返回缓存并前进**，不匹配则丢弃后续 journal、现场重跑。
|
||||
- 因 JS 去掉 `Date.now`/`random` 后确定，执行顺序确定 → 自然得到「最长未变前缀命中、首个发散点之后全重跑」。
|
||||
- `resumeFromRunId`：载入该 run 的 journal 重放。脚本源码 hash 一致 → 100% 命中；脚本改动 → 全重跑。脚本 hash 存入 run 记录。
|
||||
|
||||
### 4.4 Budget（`budget.ts`）
|
||||
|
||||
- `budget.total`：来自用户 `+500k` 式 turn 级 token 指令，由 **host/turn 上下文注入**（adapter 从 turn 的 token 指令读取，经 `HostHandle` 传入），**不是** 工具 input 参数。无指令则 `null`。
|
||||
- `budget.spent()`：本 turn 所有 agent 输出 token 之和（`AgentRunResult.usage`，adapter 从 subagent usage 填）。
|
||||
- `budget.remaining()`：`max(0, total - spent)`，无 total 则 `Infinity`。
|
||||
- **硬上限**：`spent()` 达 `total` 后，`agent()` 抛错。预算是主循环与 workflow 共享池。
|
||||
|
||||
### 4.7 AgentRunResult 类型（`types.ts`）
|
||||
|
||||
`AgentRunner.runAgentToResult` 的返回，包内明确定义为联合类型：
|
||||
|
||||
```ts
|
||||
type AgentRunResult =
|
||||
| { kind: 'ok'; output: string | object; usage: { outputTokens: number } }
|
||||
| { kind: 'skipped' } // 用户 skip → agent() 返回 null
|
||||
| { kind: 'dead' } // 终态 API 错耗尽重试 → agent() 返回 null
|
||||
```
|
||||
|
||||
`output` 为 `string`（无 schema）或已校验对象（有 schema）。`agent()` 据此映射：`ok`→返回 output，`skipped`/`dead`→返回 `null`。
|
||||
|
||||
### 4.5 脚本包装与沙箱（`script.ts`）
|
||||
|
||||
1. 提取 `export const meta = { … }`——**必须是纯字面量**（无变量/插值/展开），解析为对象；缺失或非字面量 → 抛错。
|
||||
2. 剥离 `export const meta` 语句。
|
||||
3. 剩余 body（含顶层 `return`）包进 `async function(agent, parallel, pipeline, phase, log, workflow, args, budget, Date, Math){ <body> }`。
|
||||
4. 以**抛异常的 shim** 传入 `Date`（`now()`/无参 `new Date()` 抛）、`Math`（`random()` 抛）——靠函数参数 shadow 全局，使裸 `Date.now()` 命中 shim。这是确定性保障，非密码学级沙箱（与真实引擎意图一致：阻断 resume 破坏性的非确定性）。
|
||||
5. meta 的 `phases` 可用于进度预声明（可选）。
|
||||
|
||||
### 4.6 进度事件（`progress/events.ts`）
|
||||
|
||||
`ProgressEmitter.emit(event)` 类型：`run_started`、`phase_started/done`、`agent_started/done{label,phase,result摘要}`、`log`、`run_done{returnValue/status}`。adapter 写入 task 进度结构 + AppState，`/workflows` 视图消费。
|
||||
|
||||
## 5. 错误处理
|
||||
|
||||
| 场景 | 行为 |
|
||||
|---|---|
|
||||
| 脚本无 `meta` / `meta` 非字面量 / 语法错 | 引擎抛错 → task `failed` → 通知带错误信息 |
|
||||
| `Date.now`/`Math.random`/`new Date()` | shim 抛 → 冒泡为脚本错误 → task failed |
|
||||
| `agent()` 终态 API 错（重试耗尽） | 返回 `null`，**不杀** workflow |
|
||||
| `parallel`/`pipeline` 单项抛错 | 该项 `null`，workflow 继续 |
|
||||
| budget 耗尽 | `agent()` 抛错（脚本可 try/catch） |
|
||||
| 并发/1000/4096 上限 | 抛错 |
|
||||
| kill（abort） | signal 传播；`agent()` 检查 signal；workflow 停；task `killed`；通知 partial |
|
||||
| 工具调用层（`call`）脚本非法 | 直接返回错误给模型（不进后台） |
|
||||
|
||||
## 6. 测试策略
|
||||
|
||||
包内全量单测，**无需真实 LLM**（mock 端口——解耦的核心收益）：
|
||||
|
||||
- `engine.test.ts`：mock `AgentRunner`（按 prompt 返回预设结果）端到端跑脚本，断言返回值 + 进度事件序列。
|
||||
- `hooks.test.ts`：parallel 单项错→null、pipeline 无屏障顺序、agent schema 校验、skip/dead→null。
|
||||
- `concurrency.test.ts`：信号量限并发、1000/4096 上限抛错。
|
||||
- `journal.test.ts`：hash 稳定、resume 命中前缀、脚本变更全重跑、中途发散重跑尾部。
|
||||
- `budget.test.ts`：spent 累加、触顶抛错。
|
||||
- `script.test.ts`：meta 字面量提取、非字面量/语法错、shim 抛。
|
||||
- `structuredOutput.test.ts`、`namedWorkflows.test.ts`。
|
||||
|
||||
核心侧最小冒烟：adapter 用 `runAgent` 真接线的重 mock 测试；wiring 注册测试。重量级逻辑都在包内。可选：`tests/integration/` 加一个 workflow tool-chain 集成测试（feature-gated）。
|
||||
|
||||
## 7. 核心侧实现
|
||||
|
||||
### 7.1 adapter（`src/workflow/adapter.ts`）
|
||||
|
||||
`createWorkflowAdapter()` 返回端口实现：
|
||||
|
||||
- **AgentRunner.runAgentToResult(params, hostHandle)**：cast 句柄→`{toolUseContext, canUseTool, assistantMessage}`；按 `params.agentType` 从 registry 解析 agentDefinition（缺省=通用 workflow 子 agent）；`assembleToolPool`；有 schema→注入 StructuredOutput 工具+系统指令；调 `runAgent` 收消息→`finalizeAgentTool` 抽 text+usage；schema→解析校验返回对象；处理 `pendingAgentAction`(skip)→`null`、终态死亡→`null`；返回 `{kind:'ok', text/object, usage}`。
|
||||
- **ProgressEmitter**：写 `LocalWorkflowTaskState.progress` + `rootSetAppState`。
|
||||
- **TaskRegistrar**：复用现有 `registerLocalWorkflowTask/complete/fail/kill` + 读 `pendingAgentAction`。
|
||||
- **JournalStore / Logger / PermissionGate**：fs / `logForDebugging`+`logEvent` / abort+pendingAction。
|
||||
|
||||
### 7.2 wiring（`src/workflow/wiring.ts`）
|
||||
|
||||
- `createWorkflowTool()`：建 adapter → 调包的 `createWorkflowTool(adapter)` 得描述符 → 包成 `buildTool` 兼容 `Tool` 返回。
|
||||
- `tools.ts`：`const WorkflowTool = feature('WORKFLOW_SCRIPTS') ? require('./workflow/wiring.js').createWorkflowTool() : null`（替换现有清单版）。
|
||||
|
||||
`call` 流程：校验脚本（inline/file/named 解析）→ meta 校验失败直接返错给模型 → 持久化脚本 + 算 hash → resume 则载入 run+journal → 注册后台 task → **立即返回 `{runId, scriptPath}`** → 脱离执行引擎、流进度 → 完成时 complete + 通知（返回值/错误）。
|
||||
|
||||
## 8. 现有文件迁移
|
||||
|
||||
| 文件 | 处理 |
|
||||
|---|---|
|
||||
| `builtin-tools/.../WorkflowTool/WorkflowTool.ts`（清单版） | 删除，逻辑移入新包 |
|
||||
| `constants.ts`（WORKFLOW_TOOL_NAME） | 移入包 `tool/constants.ts`，core 侧 re-export |
|
||||
| `WorkflowPermissionRequest.tsx`（React UI） | 移到 `src/workflow/`（依赖 src 权限组件，属核心侧） |
|
||||
| `createWorkflowCommand.ts`（.md/.yaml 扫描） | 改为扫 `.ts/.js/.mjs` → 生成 `/<name>` 命令，调用时以脚本启动引擎 |
|
||||
| `bundled/index.ts`（no-op） | 保留为包的 bundled-workflow 扩展点 |
|
||||
| `src/utils/workflowRuns.ts`（清单记录） | 重写为 run+journal 模型（或并入包 JournalStore） |
|
||||
| `src/commands/workflows/index.ts` | 改为**实时进度查看器**，复用 `WorkflowDetailDialog.tsx` |
|
||||
| `src/tasks.ts` LocalWorkflowTask 门控 | 保持不变 |
|
||||
| `constants/tools.ts` CORE_TOOLS 含 `workflow` | 保持 |
|
||||
|
||||
## 9. 工作分解（writing-plans 将细化）
|
||||
|
||||
1. 新建包 `packages/workflow-engine/`（package.json/tsconfig/类型/端口/常量）。
|
||||
2. 引擎核心：script 包装、concurrency、journal、budget、structuredOutput、namedWorkflows。
|
||||
3. 钩子实现 + runWorkflow 编排 + 进度事件。
|
||||
4. 自包含工具描述符（schema/desc/prompt/result 映射）。
|
||||
5. 包内全量单测。
|
||||
6. 核心侧 adapter + wiring + 句柄构造。
|
||||
7. 迁移现有文件、改 `/workflows` 为进度查看器、改 named-workflow 命令。
|
||||
8. `bun run precheck` 零错误；手动 dev 冒烟。
|
||||
|
||||
## 10. 非目标 / 风险
|
||||
|
||||
- **非密码学沙箱**：函数参数 shadow 全局 `Date`/`Math`，`globalThis.Date` 仍可达。可接受——目标是阻断 resume 破坏性的非确定性，不是隔离恶意代码。若未来需强隔离再上 `vm`/worker（方案 B/C）。
|
||||
- **resume 正确性依赖确定性执行**：用户脚本若绕过 shim 用 `globalThis.Date` 制造非确定性，resume 可能命中错缓存。属可接受的边界，文档提示。
|
||||
- **预算共享语义**：`budget.spent()` 与主循环的 token 计数共享，需 adapter 正确上报 subagent usage；若 provider 不报 usage 则 budget 降级为 `Infinity`。
|
||||
- **StructuredOutput 工具**：核心侧需存在/实现一个按 JSON Schema 强制结构化输出的子 agent 工具（注入 + 解析）。若当前无现成实现，wiring 阶段补一个最小版本。
|
||||
200
docs/superpowers/specs/2026-06-13-workflow-panel-redesign.md
Normal file
200
docs/superpowers/specs/2026-06-13-workflow-panel-redesign.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# `/workflows` 面板重设计：顶 tab + 左 phase 侧栏 + 右 agent 列表
|
||||
|
||||
> 状态：草案（待用户 review → writing-plans 产出实施计划）
|
||||
> 日期：2026-06-13
|
||||
> 关联：上一期整体设计 `docs/superpowers/specs/2026-06-13-workflow-tui-ultracode-design.md`（其 §9 双栏面板已实现，本 spec 取代该 §9 的面板部分）
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景与现状
|
||||
|
||||
上一期整体设计已落地：`WorkflowService` 门面、`claude-code` AgentAdapter、进度 bus+store、引擎 `agentId` 关联、`/ultracode` skill 全部实现完成。`/workflows` 面板按旧 spec §9 实现为**双栏**：
|
||||
|
||||
- `src/workflow/panel/WorkflowsPanel.tsx`：左栏 `WorkflowList`（扁平 run 列表）+ 右栏 `WorkflowDetail`（phase 横条 + 扁平 agent 列表）。
|
||||
- 键位 `j/k` 在左栏选 run，选中即聚焦、右栏随之切换。
|
||||
|
||||
**问题**：监控「单个 run 内多 phase / 多 agent」时，左右是「run 列表 vs 单 run 详情」——切换 run 与查看 agent 共用一对键位；phase 仅一行横条，无法按 phase 筛选 agent；多个 run 间切换要上下翻列表。
|
||||
|
||||
本 spec 把面板**原地重写**为三区焦点模型：**顶部 run tab + 左 phase 筛选侧栏 + 右 agent 列表**，贴合「聚焦一个 run → 按 phase 收窄 → 看 agent 状态」的实际监控动线。
|
||||
|
||||
## 2. 目标与非目标
|
||||
|
||||
**目标**
|
||||
|
||||
1. 顶 tab 按 **run**（同名脚本多次跑会多个 tab，标签附 runId 短码消歧如 `review-changes#a3f`）。
|
||||
2. 左 phase 侧栏：合并 `meta` 声明 phase（pending `○`）与 store phase（running `●` / done `✓`）+ 一个固定 `All` 项；选中即决定右栏筛选。
|
||||
3. 右 agent 列表：按选中 phase 过滤（`All` 则全显）；状态用颜色 + 文字标记（`object` / `text` / `dead`）。
|
||||
4. 焦点轮转键位：`Tab`/`Shift+Tab` 切 run、`←/→` 切 phases↔agents、`↑/↓` 列内移动、`x` kill / `r` resume / `q`/`Esc` quit。
|
||||
5. 视觉极简：无内框，左右栏中间**一条竖线**；选中/光标行用**底色条**（`backgroundColor`，非反白）；聚焦列标题橙粗、非聚焦灰。
|
||||
6. 显示 **pending phase**（meta 声明但未启动）。
|
||||
|
||||
**非目标**
|
||||
|
||||
- 不改引擎包（`run_started` 已携带 `meta.phases`，见 §3）。
|
||||
- 不动 `service`/`registry`/`backends`/`ports`/`wiring`/Workflow 工具/`/ultracode`。
|
||||
- 不做 per-agent 操作 UI（仅 run 级 `kill`/`resume`）。
|
||||
- 不改 `BackgroundTasksDialog`（Shift+Down）跳转协议。
|
||||
- 不做 agent 输出详情抽屉（留未来）。
|
||||
|
||||
## 3. 关键发现：零引擎改动
|
||||
|
||||
`ProgressEvent.run_started` **已携带** `meta: WorkflowMeta | null`（`packages/workflow-engine/src/types.ts:60-66`，emit 点 `engine/runWorkflow.ts:72-77`），且 `WorkflowMeta.phases` 已是 `Array<{ title: string; detail?: string }>`（`types.ts:22-27`）。
|
||||
|
||||
→ pending phase 所需数据全在事件流里。面板只需让 store 在 `run_started` 时落地 `declaredPhases`，再与 store 的 `run.phases`（running/done）合并即可。**不触碰引擎包**。
|
||||
|
||||
## 4. 数据模型变更（`src/workflow/progress/store.ts`）
|
||||
|
||||
- `RunProgress` 新增字段：
|
||||
|
||||
```ts
|
||||
declaredPhases: string[] // 来自 run_started.meta.phases[].title；无 meta → []
|
||||
```
|
||||
|
||||
- reducer `run_started` 分支补一行（当前第 74-77 行只用 `event.workflowName`，忽略 `event.meta`）：
|
||||
|
||||
```ts
|
||||
case 'run_started':
|
||||
p.workflowName = event.workflowName
|
||||
p.status = 'running'
|
||||
p.declaredPhases = event.meta?.phases?.map(ph => ph.title) ?? []
|
||||
break
|
||||
```
|
||||
|
||||
- `ensure()` 初始化 `declaredPhases: []`。
|
||||
- 其余 reducer 分支、`AgentProgress`、快照排序逻辑不变。
|
||||
|
||||
**测试**（`progress/store.test.ts` 或对应测试文件）：
|
||||
- `run_started` 带 `meta.phases` → `declaredPhases` 落地且顺序保留。
|
||||
- `run_started` 的 `meta` 为 `null` → `declaredPhases === []`。
|
||||
- 已有 `agentId` 关联、phase 切换、`run_done` 终态用例保持绿。
|
||||
|
||||
## 5. 面板布局（定稿 ASCII）
|
||||
|
||||
焦点在 PHASES（默认进入态）：
|
||||
|
||||
```
|
||||
╭─ Workflows ──────────────────────────── 2 running · 3 done ─╮
|
||||
│ │
|
||||
│ ● review-changes ✓ find-bugs ● migrate-auth │
|
||||
│ ═════════════════ ← Tab / Shift+Tab 切 │
|
||||
│ │
|
||||
│ PHASES │ AGENTS · Review │
|
||||
│ │ │
|
||||
│ ✓ Find 3/3 │ ● review:bugs running │
|
||||
│ ▓▶● Review 2/5▓ │ ● review:perf running │
|
||||
│ ○ Verify 0/2 │ ✓ review:sec object │
|
||||
│ │ ✗ review:api dead │
|
||||
│ All 10 │ ✓ review:auth text │
|
||||
│ │ │
|
||||
│ Tab 切 run · ←/→ 切焦点 · ↑/↓ 移动 · x kill · q quit │
|
||||
╰─────────────────────────────────────────────────────────────╯
|
||||
```
|
||||
|
||||
按 `→` 焦点到 AGENTS（`PHASES` 标题变灰、`AGENTS` 变橙、光标行铺底色）：
|
||||
|
||||
```
|
||||
phases (灰) │ AGENTS · Review (橙)
|
||||
│
|
||||
✓ Find 3/3 │ ● review:bugs running
|
||||
● Review 2/5 │ ▓● review:perf running ▓ ← 光标行底色
|
||||
○ Verify 0/2 │ ✓ review:sec object
|
||||
All 10 │ ✗ review:api dead
|
||||
```
|
||||
|
||||
## 6. 焦点与键位状态机
|
||||
|
||||
**面板状态**（`WorkflowsPanel` 内 `useState`）：
|
||||
|
||||
| 状态 | 含义 | 默认 |
|
||||
|---|---|---|
|
||||
| `activeRunId` | 当前 tab 的 runId | 首个 run（无则 null） |
|
||||
| `focusColumn` | `'phases'` \| `'agents'` | `'phases'`（该 run 无任何 phase 则 `'agents'`） |
|
||||
| `selectedPhaseIndex` | phase 侧栏选中项（`0` = `All`） | `0` |
|
||||
| `selectedAgentIndex` | agent 列表光标行 | `0` |
|
||||
|
||||
**键位**：
|
||||
|
||||
| 键 | 作用 |
|
||||
|---|---|
|
||||
| `Tab` / `Shift+Tab` | 切顶部 run tab（正/反）；切 tab 时重置 `selectedPhaseIndex=0`、`selectedAgentIndex=0`、`focusColumn` 回默认 |
|
||||
| `←` / `→` | `phases` ↔ `agents` 焦点切换（tabs 不参与左右，由 `Tab` 管） |
|
||||
| `↑` / `↓` | 当前焦点列内移动选中（phase 改筛选；agent 滚光标） |
|
||||
| `x` | kill 当前 tab 的 run |
|
||||
| `r` | resume 当前 tab 的 run（缺 `canUseTool` 时 `onDone` 提示用 `/<name> resume`） |
|
||||
| `q` / `Esc` | 退出面板 |
|
||||
|
||||
**夹紧**：复用 `WorkflowsPanel` 已导出的 `clampSelected`——切 tab / 列表变动后把 `selectedPhaseIndex`、`selectedAgentIndex` 夹到有效区间。
|
||||
|
||||
**筛选语义**：`selectedPhaseIndex===0`（`All`）→ 右栏显示全部 agent；否则按 `phase === 选中 phase title` 过滤。
|
||||
|
||||
## 7. 组件拆分（`src/workflow/panel/`）
|
||||
|
||||
| 文件 | 动作 | 职责 |
|
||||
|---|---|---|
|
||||
| `WorkflowsPanel.tsx` | 重写 | 订阅 store、持焦点状态、渲染 `TabsBar` + 左右双栏、绑 `useWorkflowKeyboard`；保留导出 `clampSelected` |
|
||||
| `TabsBar.tsx` | 新建 | 顶部 run tab 行（状态点 + 名 + runId 短码；当前 tab 橙色 `═══` 下划线） |
|
||||
| `PhaseSidebar.tsx` | 新建 | 左 phase 列表：`All` + 合并 `declaredPhases`（pending `○`）与 `run.phases`（`●`/`✓`），每行附 `done/total` agent 计数 |
|
||||
| `AgentList.tsx` | 新建 | 右 agent 列表：按选中 phase 过滤；状态色 + 行尾 `object`/`text`/`dead` 文字标记 |
|
||||
| `status.ts` | 新建 | 共享状态→字符/颜色映射（`STATUS_DOT`、phase/agent mark 函数），三组件复用 |
|
||||
| `useWorkflowKeyboard.ts` | 改写 | 焦点模型键位（见 §6） |
|
||||
| `WorkflowList.tsx` | 删除 | run 列表职责迁入 `TabsBar` |
|
||||
| `WorkflowDetail.tsx` | 删除 | phase+agent 职责拆入 `PhaseSidebar`+`AgentList` |
|
||||
| `panelCall.ts` | 不变 | local-jsx 入口仍渲染 `WorkflowsPanel` |
|
||||
|
||||
**外部接口不变**：`/workflows` 命令注册、`panelCall`、`getWorkflowService()` 订阅协议、`BackgroundTasksDialog` 跳转均不动。
|
||||
|
||||
## 8. 视觉规则
|
||||
|
||||
- **无内框**：左右两栏中间一条 `│` 竖线，仅此一条分割线；最外层保留最朴素的 round border 界定面板。
|
||||
- **聚焦列**：标题 `claude` 橙粗体；非聚焦列标题 `subtle` 灰。
|
||||
- **选中/光标行**：整行铺 `backgroundColor="claude"` 橙底（ASCII 用 `▓` 示意），**文字色不变**，状态点保留各自颜色。
|
||||
- **状态色**（沿用现有 Ink theme token，无新增）：
|
||||
|
||||
| 元素 | 状态 | 字符 | 颜色 |
|
||||
|---|---|---|---|
|
||||
| Tab (run) | running | `●` | `warning` |
|
||||
| | completed | `✓` | `success` |
|
||||
| | failed | `✗` | `error` |
|
||||
| | killed | `■` | `subtle` |
|
||||
| | 当前 | `═══` | `claude` 下划线 |
|
||||
| Phase | running | `●` | `warning` |
|
||||
| | done | `✓` | `success` |
|
||||
| | pending | `○` | `subtle` |
|
||||
| | 选中 | `▶` | `claude` + 底色 |
|
||||
| Agent | running | `●` | `warning` |
|
||||
| | done·text | `✓` | `success` + 行尾 `text` |
|
||||
| | done·object | `✓` | `success` + 行尾 `object` |
|
||||
| | dead | `✗` | `error` + 行尾 `dead` |
|
||||
|
||||
- **object 标记**：行尾纯文字 `object`（不用 `◆` 符号）。
|
||||
- **左窄右宽**：phase 栏约 20%、agent 栏约 80%（或固定 phase 栏 ~20 字符，agent 栏吃剩余宽度）。
|
||||
|
||||
## 9. 测试策略
|
||||
|
||||
- **store**：`declaredPhases` 落地 + null meta 回归（§4）。
|
||||
- **面板**（`WorkflowsPanel.test.tsx`，ink-testing-library，遵循仓库 mock 规范）：
|
||||
- 多 run → tab 渲染 + 当前 tab 下划线；`Tab`/`Shift+Tab` 切换且重置子选择。
|
||||
- `←/→` 切 `focusColumn`（标题颜色 / 光标落点）。
|
||||
- phase 侧栏选中 → 右栏 agent 按 phase 过滤；`All` 显全部。
|
||||
- pending phase（`declaredPhases` 有、store 无）显示 `○`。
|
||||
- 选中行/光标行底色条（断言对应 `<Text backgroundColor>`）。
|
||||
- `x` kill、`r` resume（mock service）、`q`/`Esc` 退出。
|
||||
- 空态（无 run）：占位文案 + `n` 提示。
|
||||
- 订阅刷新：store 变更后面板重渲染（agent 状态 running→done）。
|
||||
- **回归**：`bun run precheck` 零错误；现有 workflow 集成测试（canonical scripts / review / loop / resume）保持绿。
|
||||
|
||||
## 10. 里程碑与提交切分
|
||||
|
||||
每个里程碑结束 `bun run precheck` 必须零错误。
|
||||
|
||||
1. **M1 store**：`RunProgress.declaredPhases` + reducer `run_started` 落地 + 测试。
|
||||
2. **M2 panel 组件**：新建 `status.ts` / `TabsBar` / `PhaseSidebar` / `AgentList`；`WorkflowsPanel` 重写为焦点状态机；`useWorkflowKeyboard` 改焦点模型；删除 `WorkflowList` / `WorkflowDetail`。
|
||||
3. **M3 测试**：`WorkflowsPanel.test.tsx` 全量用例 + precheck 绿。
|
||||
4. **M4 文档**：`docs/features/workflow-scripts.md` §六 更新为三区布局/键位；旧 spec §六/§9 加注「面板部分已被 `2026-06-13-workflow-panel-redesign.md` 取代」。
|
||||
|
||||
## 11. 未做 / 未来工作
|
||||
|
||||
- per-agent skip/retry 的 UI 接线（引擎 seam 已在）。
|
||||
- agent 详情抽屉：选中 agent 后展开其 prompt/输出/token。
|
||||
- 多 run 并排对比视图。
|
||||
- `declaredPhases` 与实际 `phase()` 调用不一致时的告警（如脚本声明了 phase 却没调用）。
|
||||
@@ -0,0 +1,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 时再引入
|
||||
@@ -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
394
docs/superpowers/specs/2026-06-14-effort-panel-design.md
Normal 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` 零错误
|
||||
Reference in New Issue
Block a user