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>
This commit is contained in:
claude-code-best
2026-06-13 20:07:18 +08:00
parent 91cffe16e2
commit d236880bc3
106 changed files with 16127 additions and 834 deletions

View File

@@ -0,0 +1,74 @@
# 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`
## 运行
```bash
ANTHROPIC_API_KEY=sk-... \
bun run packages/workflow-engine/examples/research-report/run.ts "Edge Computing"
```
环境变量:
- `ANTHROPIC_API_KEY`(必填)
- `ANTHROPIC_MODEL`:默认 `claude-sonnet-4-5`
- `WORKFLOW_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_LOG` env。否则 SDK 会打 `[log_xxxxx] sending request {…}` 这种完整请求 JSON。
- **错误摘要精简**:失败只打 `HTTP 429 rate_limit_error` 这种短行,不打印含 request body 的整段 message。
- **synthesize 防 JSON**prompt 明确禁止把输入的 `deepFindings` JSON 原样粘进报告。
排错速查:
| 现象 | 原因 / 处理 |
|------|------|
| `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 searchresearch 角度即可联网。
- **命名命令复用**:把 `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 测试兜底,可作为基础继续建。