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
@@ -1,102 +1,183 @@
|
||||
# WORKFLOW_SCRIPTS — 工作流自动化
|
||||
# WORKFLOW_SCRIPTS — 确定性多 agent 工作流编排
|
||||
|
||||
> Feature Flag: `FEATURE_WORKFLOW_SCRIPTS=1`
|
||||
> 实现状态：全部 Stub（7 个文件），布线完整
|
||||
> 引用数：10
|
||||
> Feature Flag：`FEATURE_WORKFLOW_SCRIPTS=1`
|
||||
> 引擎包：[`@claude-code-best/workflow-engine`](../../packages/workflow-engine/)（确定性 JS 脚本编排，零核心层运行时依赖）
|
||||
> 集成层：[`src/workflow/`](../../src/workflow/)
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
WORKFLOW_SCRIPTS 实现基于文件的多步自动化工作流。用户可以定义 YAML/JSON 格式的工作流描述文件，系统将其解析为可执行的多 agent 步骤序列。提供 `/workflows` 命令管理和触发工作流。
|
||||
WORKFLOW_SCRIPTS 让 Claude Code 用**确定性 JavaScript 脚本**编排多个子 agent：可分解/并行、多视角置信、规模超单上下文、可 resume/可审计。
|
||||
|
||||
- **编排原语**：`agent` / `parallel` / `pipeline` / `phase` / `log` / `workflow`（见引擎包）。
|
||||
- **确定性**：脚本在受限沙箱内执行，禁用 `Date.now()` / `Math.random()` / 无参 `new Date()`，保证 journal 可重放。
|
||||
- **深度后端**：单一 `claude-code` AgentAdapter 接入当前会话体系（provider / model / agentType / 工具），workflow 内的 `agent()` 调用真实子 agent。
|
||||
- **监控面板**：`/workflows` 双栏实时面板（见 §六）。
|
||||
- **编排手册**：`/ultracode` 注入编排工作法（见 §七）。
|
||||
|
||||
> 历史说明：早期版本为 YAML/JSON DSL + 全 Stub 实现（`WorkflowDetailDialog` 等），已全量重写为引擎驱动的 JS 方案。
|
||||
|
||||
## 二、实现架构
|
||||
|
||||
### 2.1 模块状态
|
||||
|
||||
| 模块 | 文件 | 状态 |
|
||||
|------|------|------|
|
||||
| WorkflowTool | `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts` | **部分实现** — tool schema + 渲染完整，call 返回运行时缺失提示 |
|
||||
| Workflow 权限 | `packages/builtin-tools/src/tools/WorkflowTool/WorkflowPermissionRequest.tsx` | **部分实现** — 权限请求组件 |
|
||||
| 常量 | `packages/builtin-tools/src/tools/WorkflowTool/constants.ts` | **实现** — 工具名 + 目录名 + 文件扩展名常量 |
|
||||
| 命令创建 | `packages/builtin-tools/src/tools/WorkflowTool/createWorkflowCommand.ts` | **实现** — 扫描 .claude/workflows/ 目录创建 Command 对象 |
|
||||
| 捆绑工作流 | `packages/builtin-tools/src/tools/WorkflowTool/bundled/index.ts` | **实现** — 内置工作流初始化 |
|
||||
| 本地工作流任务 | `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` | **Stub** — 类型 + 空操作 |
|
||||
| UI 任务组件 | `src/components/tasks/src/tasks/LocalWorkflowTask/` | **Stub** — 空导出 |
|
||||
| 详情对话框 | `src/components/tasks/WorkflowDetailDialog.ts` | **Stub** — 返回 null |
|
||||
| 任务注册 | `src/tasks.ts` | **布线** — 动态加载 |
|
||||
| 工具注册 | `src/tools.ts` | **布线** — 动态加载 + bundled 工作流初始化 (行 131-134,235) |
|
||||
| 命令注册 | `src/commands.ts` | **布线** — `/workflows` 命令 (行 93-95,395,460) |
|
||||
|
||||
### 2.2 预期数据流
|
||||
|
||||
```
|
||||
用户定义工作流（YAML/JSON 文件）
|
||||
│
|
||||
▼
|
||||
/workflows 命令发现工作流文件
|
||||
│
|
||||
▼
|
||||
createWorkflowCommand() 解析为 Command 对象 [需要实现]
|
||||
│
|
||||
▼
|
||||
WorkflowTool 执行工作流 [需要实现]
|
||||
│
|
||||
├── 步骤 1: Agent({ task: "..." })
|
||||
├── 步骤 2: Agent({ task: "..." })
|
||||
└── 步骤 N: Agent({ task: "..." })
|
||||
│
|
||||
▼
|
||||
LocalWorkflowTask 协调步骤执行 [需要实现]
|
||||
│
|
||||
▼
|
||||
WorkflowDetailDialog 显示进度 [需要实现]
|
||||
.claude/workflows/<name>.ts Workflow 工具（name/script/scriptPath/args/resumeFromRunId）
|
||||
│ │
|
||||
▼ ▼
|
||||
namedWorkflowCommands.ts src/workflow/wiring.ts (createWorkflowToolCore)
|
||||
（/<name> 命令发现） │
|
||||
▼
|
||||
WorkflowService（门面：launch/kill/subscribe/listRuns/listNamed）
|
||||
│
|
||||
┌────────────────┼─────────────────┐
|
||||
▼ ▼ ▼
|
||||
ports.ts registry.ts progress/
|
||||
（端口聚合） （AgentAdapterRegistry） bus + store
|
||||
│ │
|
||||
▼ ▼
|
||||
hostHandle.ts backends/claudeCodeBackend.ts
|
||||
（不透明 host） （深度读会话体系，跑真实 agent）
|
||||
│
|
||||
▼
|
||||
@claude-code-best/workflow-engine
|
||||
（runWorkflow / hooks / journal / budget / 并发信号量）
|
||||
```
|
||||
|
||||
### 2.3 预期工作流 DSL
|
||||
### 2.1 模块清单
|
||||
|
||||
```
|
||||
# workflow.yaml（预期格式，需要设计）
|
||||
name: "代码审查工作流"
|
||||
steps:
|
||||
- name: "静态分析"
|
||||
agent: { type: "general-purpose", prompt: "运行 lint 和类型检查" }
|
||||
- name: "测试"
|
||||
agent: { type: "general-purpose", prompt: "运行测试套件" }
|
||||
- name: "综合报告"
|
||||
agent: { type: "general-purpose", prompt: "综合分析结果写报告" }
|
||||
| 层 | 文件 | 职责 |
|
||||
|----|------|------|
|
||||
| 引擎 | `packages/workflow-engine/src/` | 确定性脚本沙箱 + hooks + journal + budget + 信号量；导出 `createWorkflowTool` |
|
||||
| 工具装配 | `src/workflow/wiring.ts` | `createWorkflowToolCore()` —— 用 `WorkflowService.ports` 组装 `Workflow` 工具 |
|
||||
| 服务门面 | `src/workflow/service.ts` | `WorkflowService` 单例：`launch` / `kill` / `subscribe` / `listRuns` / `listNamed` / `getWorkflowService()` |
|
||||
| 端口 | `src/workflow/ports.ts` | `createWorkflowPorts()` 聚合所有端口（agentRunner/registry/progress/task/journal/permission/logger/hostFactory） |
|
||||
| 后端注册 | `src/workflow/registry.ts` | `buildRegistry()` 注册 `claude-code` 后端并设为默认 |
|
||||
| 深度后端 | `src/workflow/backends/claudeCodeBackend.ts` | AgentAdapter：按 `agentType`/`model` 解析会话体系，跑真实子 agent，结构化输出 |
|
||||
| Host 句柄 | `src/workflow/hostHandle.ts` | `buildHostBundle()` 不透明包装 `toolUseContext`/`canUseTool`/`parentMessage` |
|
||||
| 进度总线 | `src/workflow/progress/bus.ts` | 基于 Set 的进度事件发射 |
|
||||
| 进度状态 | `src/workflow/progress/store.ts` | reducer：按 `agentId` 精确关联 `agent_done`（修并发竞态） |
|
||||
| 监控面板 | `src/workflow/panel/*.tsx` | `/workflows` 双栏 UI（见 §六） |
|
||||
| 命名命令 | `src/workflow/namedWorkflowCommands.ts` | 扫描 `.claude/workflows/` 生成 `/<name>` 命令 |
|
||||
| 权限请求 | `src/workflow/WorkflowPermissionRequest.tsx` | workflow 启动权限 UI |
|
||||
|
||||
### 2.2 注册点
|
||||
|
||||
| 位置 | 内容 |
|
||||
|------|------|
|
||||
| `src/tools.ts:152-153,254` | `createWorkflowToolCore()` 动态加载并注册 `Workflow` 工具（feature-gated） |
|
||||
| `src/commands.ts:95-97,392` | `/workflows` 命令（local-jsx，加载 `panelCall.js`） |
|
||||
| `src/skills/bundled/ultracode.ts` + `index.ts` | `/ultracode` 知识 skill（`registerBundledSkill`） |
|
||||
|
||||
## 三、编排原语
|
||||
|
||||
workflow 脚本内可用的钩子（语义详见引擎包 `engine/hooks.ts`）：
|
||||
|
||||
| 原语 | 语义 |
|
||||
|------|------|
|
||||
| `agent(prompt, opts?)` | 派发一个子 agent；返回最终文本，或（带 `opts.schema`）结构化对象。opts：`model` / `agentType` / `label` / `phase` / `schema` |
|
||||
| `parallel([() => …])` | 并发跑 thunk 数组，**barrier**（等全部完成）；单项抛错 → 该项 `null`，其余保留 |
|
||||
| `pipeline(items, s1, s2, …)` | 每个 item 链式过各 stage；**item 间无 barrier**，stage 内顺序；单 item 某 stage 抛错 → 该 item `null` |
|
||||
| `phase(title)` | 标记阶段（面板按此分组展示） |
|
||||
| `log(msg)` | 进度日志（面板展示，无状态变更） |
|
||||
| `workflow(name \| { scriptPath }, args?)` | 嵌套一层子 workflow（仅允许一层） |
|
||||
|
||||
**硬限**：单次 `parallel`/`pipeline` ≤ `MAX_ITEMS_PER_CALL`（4096）；单 workflow 总 agent ≤ `MAX_TOTAL_AGENTS`（1000）；并发 cap 默认 = `DEFAULT_MAX_CONCURRENCY`（3），可经 Workflow 工具的 `maxConcurrency` 入参覆盖，绝对上限 `MAX_CONCURRENCY_CAP`（16）。
|
||||
|
||||
## 四、编写 workflow
|
||||
|
||||
脚本置于 `.claude/workflows/<name>.js|.mjs`（也接受 `.ts`，但**引擎不转译 TS**，含类型注解会报语法错——推荐 `.js`/`.mjs`），自动成为 `/<name>` 命令。
|
||||
|
||||
```js
|
||||
// .claude/workflows/review-changes.js
|
||||
export const meta = {
|
||||
name: 'review-changes',
|
||||
description: '按维度审查改动并对抗式验证',
|
||||
phases: [{ title: 'Review' }, { title: 'Verify' }],
|
||||
}
|
||||
|
||||
const DIMENSIONS = [
|
||||
{ key: 'bugs', prompt: '找正确性 bug' },
|
||||
{ key: 'perf', prompt: '找性能问题' },
|
||||
]
|
||||
|
||||
const results = await pipeline(
|
||||
DIMENSIONS,
|
||||
d => agent(d.prompt, { label: `review:${d.key}`, phase: 'Review' }),
|
||||
review => parallel(
|
||||
(review.findings || []).map(f => () =>
|
||||
agent(`对抗式验证：${f.title}`, { phase: 'Verify' })
|
||||
)
|
||||
)
|
||||
)
|
||||
return results.flat().filter(Boolean)
|
||||
```
|
||||
|
||||
## 三、需要补全的内容
|
||||
**脚本执行约束**（引擎执行模型，违反直接报错）：
|
||||
|
||||
| 优先级 | 模块 | 工作量 | 说明 |
|
||||
|--------|------|--------|------|
|
||||
| 1 | `WorkflowTool.ts` call 方法 | 中 | 实际工作流执行逻辑（当前返回运行时缺失提示） |
|
||||
| 2 | `LocalWorkflowTask.ts` | 大 | 步骤协调、kill/skip/retry |
|
||||
| 3 | `WorkflowDetailDialog.ts` | 中 | 进度详情 UI |
|
||||
脚本是 `new AsyncFunction` 的**函数体**，不是 ESM 模块：
|
||||
|
||||
## 四、关键设计决策
|
||||
- **禁 `import`**：`agent`/`parallel`/`pipeline`/`phase`/`log`/`workflow` 与 `args`/`budget` 是注入的形参，直接用。
|
||||
- **禁 TS 语法**：不要类型注解（`x: number`）、`interface`、`enum`、`as`、泛型。引擎不转译，即便文件是 `.ts` 也会原样报语法错。
|
||||
- **只允许一处 `export const meta = {...}`**（引擎正则提取剥离）；不要 `export` 其他、不要 `export default`。
|
||||
- **顶层 `return` 返回结果**。
|
||||
|
||||
1. **基于文件的 DSL**：工作流定义为文件（YAML/JSON），版本控制友好
|
||||
2. **多 Agent 步骤**：每个步骤是独立的 agent 任务，支持并行/串行
|
||||
3. **内置工作流**：`bundled/` 目录提供开箱即用的常用工作流
|
||||
4. **/workflows 命令**：统一的发现和触发入口
|
||||
**确定性约束**（违反则 resume 失效）：
|
||||
- 禁 `Date.now()` / `Math.random()` / 无参 `new Date()`（沙箱强制抛错）。需时间戳/随机种子经 `args` 传入。
|
||||
- `export const meta = { ... }` 必须是**纯字面量**（无变量、函数调用、模板插值）——加载期求值，否则抛 `ScriptError`。
|
||||
|
||||
## 五、使用方式
|
||||
## 五、Workflow 工具
|
||||
|
||||
```bash
|
||||
# 启用 feature（需要补全后才能真正使用）
|
||||
FEATURE_WORKFLOW_SCRIPTS=1 bun run dev
|
||||
```
|
||||
模型通过 `Workflow` 工具启动 workflow（input schema 见引擎包 `tool/schema.ts`）：
|
||||
|
||||
## 六、文件索引
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `script` | 内联脚本字符串 |
|
||||
| `name` | 命名 workflow 名（对应 `.claude/workflows/<name>`） |
|
||||
| `scriptPath` | 脚本文件路径 |
|
||||
| `args` | 透传给脚本的 `args`（任意 JSON 值） |
|
||||
| `resumeFromRunId` | 从既有 runId 重放（已完成 `agent()` 秒回，发散点后现场重跑） |
|
||||
|
||||
## 六、监控面板：`/workflows`
|
||||
|
||||
`/workflows` 打开三区焦点面板（local-jsx，全屏）：
|
||||
|
||||
- **顶部 tabs**：每个 run 一个 tab（状态圆点 + workflow 名 + `#runId短码`）；同名脚本多次跑会多个 tab。
|
||||
- **左 phase 侧栏**：`All` + 合并 meta 声明的 phase（未启动 `○` pending 灰）与实际 phase（`●` running / `✓` done）；选中即决定右栏筛选。
|
||||
- **右 agent 列表**：按选中 phase 过滤；状态色 + 行尾文字（`running` / `object` / `text` / `dead`）。
|
||||
|
||||
**键位**：`Tab`/`Shift+Tab` 切 run · `←`/`→` 切左右焦点列（phases ↔ agents）· `↑`/`↓` 列内移动 · `r` resume · `x` kill · `n` 新建提示 · `q`/`Esc` 退出。
|
||||
|
||||
**视觉**：无内框，左右一条竖线分隔；聚焦列标题橙粗；选中/光标行铺橙底（`backgroundColor`），文字色不变。
|
||||
|
||||
进度按引擎 `agentId` 精确关联 `agent_done`（解决并发 LIFO 竞态）。pending phase 来自 `run_started` 事件携带的 `meta.phases`，store 落地 `declaredPhases`，面板 `mergePhases` 合并。`useSyncExternalStore` 订阅 `WorkflowService`，稳定快照，无变更不重渲染。
|
||||
|
||||
## 七、`/ultracode` skill
|
||||
|
||||
`/ultracode`（`src/skills/bundled/ultracode.ts`）注入多 agent workflow 编排工作法：何时用 / 何时不用、编排原语速查、质量模式库（adversarial-verify / judge-panel / loop-until-dry / multi-modal-sweep / completeness-critic）、确定性约束、后端路由、resume/budget、文件与命令。
|
||||
|
||||
**纯知识 prompt skill**：零运行时副作用，不改主循环、不切换行为开关。调用即把手册注入上下文。
|
||||
|
||||
## 八、resume / journal / budget
|
||||
|
||||
- **journal**：每次 run 记录到 `.claude/workflow-runs/<runId>/journal.jsonl`。`resumeFromRunId` 重放 journal，已完成 `agent()` 秒回缓存结果。
|
||||
- **budget**：`budget.total` 为 token 硬顶（默认 `null` = 无限）；`budget.spent()` / `budget.remaining()` 读实时消耗；耗尽后再发 `agent()` 抛错。
|
||||
- **并发**：引擎 `Semaphore` 默认许可 3（`DEFAULT_MAX_CONCURRENCY`），可经 Workflow 工具的 `maxConcurrency` 入参 per-run 覆盖（钳到 `[1, MAX_CONCURRENCY_CAP=16]`）。
|
||||
- **错误**：脚本语法/meta 错 → `parseScript` 即时返错（不进后台）；agent 抛错 → `kind:'dead'` → `null`，workflow 继续（`parallel`/`pipeline` 容错）；`WorkflowAbortedError` → `killed`。
|
||||
|
||||
## 九、文件索引
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `packages/builtin-tools/src/tools/WorkflowTool/WorkflowTool.ts` | 工具定义（部分实现） |
|
||||
| `packages/builtin-tools/src/tools/WorkflowTool/WorkflowPermissionRequest.tsx` | 权限请求组件 |
|
||||
| `packages/builtin-tools/src/tools/WorkflowTool/constants.ts` | 常量定义 |
|
||||
| `packages/builtin-tools/src/tools/WorkflowTool/createWorkflowCommand.ts` | 命令创建（已实现） |
|
||||
| `packages/builtin-tools/src/tools/WorkflowTool/bundled/index.ts` | 内置工作流初始化 |
|
||||
| `src/tasks/LocalWorkflowTask/LocalWorkflowTask.ts` | 任务协调（stub） |
|
||||
| `src/components/tasks/WorkflowDetailDialog.ts` | 详情对话框（stub） |
|
||||
| `src/tools.ts:131-134,235` | 工具注册 |
|
||||
| `src/commands.ts:93-95,395,460` | 命令注册 |
|
||||
| `src/workflow/wiring.ts` | `Workflow` 工具装配（`createWorkflowToolCore`） |
|
||||
| `src/workflow/service.ts` | `WorkflowService` 门面 |
|
||||
| `src/workflow/ports.ts` | 端口聚合（`createWorkflowPorts`） |
|
||||
| `src/workflow/registry.ts` | `AgentAdapterRegistry` + 默认后端 |
|
||||
| `src/workflow/backends/claudeCodeBackend.ts` | 深度后端 AgentAdapter |
|
||||
| `src/workflow/hostHandle.ts` | 不透明 host 句柄（`buildHostBundle`） |
|
||||
| `src/workflow/progress/bus.ts` | 进度事件总线 |
|
||||
| `src/workflow/progress/store.ts` | 进度 reducer（`agentId` 关联） |
|
||||
| `src/workflow/panel/*.tsx` | `/workflows` 双栏面板 |
|
||||
| `src/workflow/namedWorkflowCommands.ts` | `/<name>` 命令发现 |
|
||||
| `src/workflow/WorkflowPermissionRequest.tsx` | 启动权限 UI |
|
||||
| `src/skills/bundled/ultracode.ts` | `/ultracode` 知识 skill |
|
||||
| `src/tools.ts:152-153,254` | 工具注册 |
|
||||
| `src/commands.ts:95-97,392` | `/workflows` 命令注册 |
|
||||
| `packages/workflow-engine/` | 引擎包（hooks / journal / budget / 并发） |
|
||||
|
||||
Reference in New Issue
Block a user