mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-17 22:05:50 +00:00
d236880bc3
将 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>
research-report —— 库优先运行示例
用 @claude-code-best/workflow-engine 直接运行一个 workflow，绕开 Workflow 工具与核心 runAgent。
状态
- 引擎层：完整且测试覆盖 99.65% 行 / 99.20% 函数（workflow-engine 包 112 个 mock 测试全绿）。
- 本 example：编排逻辑（
parallel/pipeline/schema/args）经 mock 端到端验证；真实 LLM 已跑通（直连 Anthropic SDK）。 - 定位：库 API 与引擎逻辑的参考实现 + 冒烟示范，不是生产服务——见下方「生产就绪」。
它演示了什么
- 库可独立使用：
run.ts只import { runWorkflow, ... } from '@claude-code-best/workflow-engine'，自己组装 7 个端口，不依赖src/任何核心模块。 - agent 后端直连 Anthropic SDK：
agentRunner调client.messages.create，子 agent = 一次模型调用（不经核心runAgent、不经 Workflow 工具）。 - 真实 LLM + 结构化输出：
agent(schema)→ prompt 追加 JSON 指令 → 提取 JSON →validateAgainstSchema（Ajv）校验，失败回退dead。 - 引擎能力全覆盖：
parallel（屏障，多角度 fan-out）→pipeline（无屏障，逐条深挖）→phase/log/args。
运行
ANTHROPIC_API_KEY=sk-... \
bun run packages/workflow-engine/examples/research-report/run.ts "Edge Computing"
环境变量：
ANTHROPIC_API_KEY（必填）ANTHROPIC_MODEL：默认claude-sonnet-4-5WORKFLOW_API_CONCURRENCY：API 并发上限，默认3（见下）。低 tier 可设1串行RESEARCH_RUNS_DIR：journal 目录，默认~/.claude/workflow-runs（resume 时复用）
健壮性与排错
runner 内置了几项让真实 API 跑得稳的处理：
- API 并发限制：
llmAgent经独立信号量限并发（默认 3），独立于引擎的 CPU 级 semaphore——LLM API 对并发远比 CPU 敏感，按 cores（可能 14）放并发会触发 429。用WORKFLOW_API_CONCURRENCY调。 - 429/5xx 重试：指数退避（500ms → 1s → 2s → 4s，最多 4 次）；连接/超时错误也重试。
- SDK 日志关闭：
new Anthropic({ logLevel: 'off' })（options 优先级最高，压过ANTHROPIC_LOGenv）。否则 SDK 会打[log_xxxxx] sending request {…}这种完整请求 JSON。 - 错误摘要精简：失败只打
HTTP 429 rate_limit_error这种短行，不打印含 request body 的整段 message。 - synthesize 防 JSON：prompt 明确禁止把输入的
deepFindingsJSON 原样粘进报告。
排错速查：
| 现象 | 原因 / 处理 |
|---|---|
HTTP 429 ... 频繁 |
降 WORKFLOW_API_CONCURRENCY=1（或 2） |
agent ✗ [dead] 多 |
模型未按 schema 返回 JSON；换更强模型或放宽 schema |
[log_xxx] sending request 刷屏 |
不应再出现（已 logLevel:'off'）；若仍出现检查 env 是否覆盖 |
| 报告被截断 | synthesize 已 maxTokens:8192；仍不够可改 workflow 脚本 |
文件
| 文件 | 作用 |
|---|---|
research-report.workflow.mjs |
workflow 脚本（编排逻辑，纯 JS，引擎沙箱执行） |
run.ts |
runner：组装端口 + 直连 SDK + 运行 + 终端进度 |
（同级 ../smoke.ts） |
最小冒烟入口（3 次调用，秒级验证通路） |
扩展点
- 联网调研：给
llmAgent的messages.create加tools: [{ type: 'web_search_20250305' }]（Anthropic server-side web search），research 角度即可联网。 - 命名命令复用：把
research-report.workflow.mjs复制到项目.claude/workflows/research-report.mjs，即可通过/research-report或 Workflow 工具运行（同一脚本，两种入口）。 - token 预算：
runWorkflow({ budgetTotal: 200000 })设上限；脚本内用budget.remaining()自适应规模。 - resume：同
runId+resume: true重放 journal，已完成的 agent 不重跑。
生产就绪（诚实）
本 example 验证的是库的 API 与引擎编排逻辑，不是生产服务。要上生产还差：
- 真实 LLM 压测：长 workflow、大量并发、中断/resume 的真实场景验证（mock 覆盖不到模型行为）。
- 核心 adapter 的 v1 延期项：
budgetTotal注入、skip/retry UI、worktree 隔离、StructuredOutput 完整接入（本 example 用 prompt+JSON 解析，比核心真实路径弱）。 - 错误恢复：journal resume 只在 mock 验证过；真实中途崩溃的重放正确性未压测。
引擎核心逻辑（并发 / 预算 / journal / schema）有 99.65% 覆盖的 mock 测试兜底，可作为基础继续建。