Orca DAG：将 Agent 规划与可视化执行拆分的新范式

Fen9Pi2026/8/11大约 11 分钟

前言：Agent 编排的困境

用 Agent 编排多个任务时，常见的问题是：

规划在哪里？

内嵌在应用里？
写死在代码里？
还是交给第三方？

执行怎么管？

手动启动每个任务？
用统一的调度器？
还是让 Agent 自己决定？

可视化怎么办？

看不到依赖关系？
看不到执行状态？
调不动单个节点？ " 今天介绍一个优雅的解决方案——Orca DAG，将"和 Agent 聊天规划"与"可视化+执行"拆成两个独立模块。

一、项目概览

Orca DAG 是一个开源工具，用于可视化 Orca 编排的 DAG（有向无环图）。

一句话说清楚：

把"和 agent 聊天规划"与"可视化+执行"拆成两个独立模块——skill 教你的 agent 建图，viewer 实时可视化并按 DAG 并行执行。

项目地址：https://github.com/ZinkLu/Orca-Orchestration 作者：ZinkLu 开源协议：未明确（开源仓库）依赖：Orca ≥ 1.4.160

两个核心模块

模块 1：skill

教你自己的 agent（Claude Code/kimi/…）如何把需求拆成 Orca orchestration 的任务 DAG
提供建图规范
不内嵌 Claude Agent SDK

模块 2：viewer

连到 Orca 的编排状态
实时可视化 DAG
每个节点各自选 harness（claude/kimi/opencode/grok/…）
点 "▶ 让 Orca 执行"
内置自驱动 coordinator 按依赖把 ready 任务并行派发给按需拉起的自主 worker

核心流程

agent 建图 → viewer 选 Run + 选 harness → Run → 按 DAG 并行自动执行

要改某个任务或依赖：让 agent 重绘 DAG —— Orca 没有改单个任务的接口。

二、核心架构

它是怎么工作的

   你的 agent（加载 orca-dag skill）                 orca-dag viewer（全局二进制）
 ┌───────────────────────────────┐             ┌──────────────────────────────┐
 │  和你聊需求 → 拆解 → 建图        │             │  轮询 task-list → 画 DAG        │
 │  Bash: orca orchestration      │             │  每节点选 harness              │
 │        task-create / gate-*    │             │  ▶ Run → 自驱动 coordinator     │
 └───────────────┬───────────────┘             └───────────────┬──────────────┘
                 │  写编排状态                                     │  轮询 + dispatch --inject（并行）
                 ▼                                               ▼
        ┌──────────────────────────  Orca 编排状态  ──────────────────────────┐
        │  tasks / deps / gates   ·   按需拉起的自主 worker（各节点的 harness）    │
        └──────────────────────────────────────────────────────────────────┘

工作流程：

1. 建图（在 agent 里）

你在自己的 agent 里聊需求
agent 加载 orca-dag skill
先 orca orchestration run-create 开一个 Run
再用 task-create --deps … 把任务与依赖建进这个 Run

2. 可视化（在 viewer 里）

打开 viewer（orca-dag）
顶栏选 Run
每 2 秒轮询 orca orchestration task-list --run <id> --json
用 dagre 布局、React Flow 渲染
状态实时变色

3. 执行（viewer 的 coordinator）

给节点选 harness（或用默认 harness）
设置"最多并行"
点 "▶ 让 Orca 执行"
viewer 的 coordinator 循环接管

4. 自驱动执行

viewer 先把自己的一个 Orca 终端绑定为该 Run 的 coordinator
每轮找出所有 ready 任务
并行调 orca orchestration worker-start --task <id> --agent <harness>
由 Orca 自己创建 worker 终端、等就绪、注入 dispatch
worker 干完发 worker_done --outcome
Orca 自动把 task 和 dispatch 置为完成/失败
依赖转 ready → 继续，直到全跑完

5. 修改

回到 agent 对话让它重绘 DAG

Run / Task / Dispatch 三层

层	是什么	谁维护
Run	命名空间 + coordinator 收件箱；同一时刻只有一个绑定的 coordinator（`consumer_generation` 做 fencing）	Orca
Task	工作项；`deps` 定义 DAG 边，`run_id` 归属 Run	Orca
Dispatch	一次尝试（id 形如 `ctx_*`）；带 `failure_count`（3 次熔断）、心跳、pane 身份、能力凭证。重试产生新的 Dispatch	Orca
每节点 harness、画布坐标、默认 harness、最大并行、当前 Run	viewer 自己的偏好	`.orca-dag.config.json`

重要：Run 是命名空间，不等于 DAG —— 一个 Run 里可以躺多张互不相连的图。"一个 Run 一张图"是 skill/SKILL.md 里的约定，不是 Orca 的约束。

三、为什么这样设计？

大脑外移

规划由你已有的 agent 承担。

为什么不内嵌 Claude Agent SDK？

原因 1：灵活性

你可以用任何 agent（Claude Code、kimi、或其他）
不被绑定到某个 AI 提供商
可以随时切换

原因 2：控制权

你控制规划逻辑
你控制任务拆解方式
你控制建图规范

原因 3：成本

不用为每个 viewer 实例付 API 费用
agent 和 viewer 分离，可以复用

viewer 自己当 coordinator

为什么不让 orca orchestration run 来执行？

Orca 官方的立场：

"Agents still choose placement and concurrency; Orca does not schedule workers."

Orca 是故意不做调度器的。

orca orchestration run 不会真派发任务
coordinator-start 已被正式退休
Orca 只提供 Run / Task / Dispatch 原语

所以 viewer 自己实现了 coordinator：

用 dispatch --inject 自驱动
并行度由 DAG 决定（同时 ready 的任务一起派）
受 maxConcurrency 上限约束
worker 按需拉起、空闲复用、跑完回收

权限模型

为什么 viewer 要占一个终端？

Orca 的所有编排调用都过 resolveRunScope：

读操作：

task-list / gate-list
只要带 --run <id> 就跳过 consumer 检查
任何进程都能读
viewer 的轮询只需要这个

写操作：

dispatch / gate-resolve / task-create / worker-start
要求调用方就是当前绑定该 Run 的那个 Orca 终端
靠 --from <handle> 解析出 pane 来比对

viewer 是个普通进程，没有终端身份，所以写操作一律 run_required。

解法：

viewer 自己开一个标题为 orca-dag coordinator 的 Orca 终端
run-use 绑定
所有写操作带 --from

绑定会 fence 掉原来的 coordinator（通常就是给你画图的那个 agent 终端）。

所以点执行前 viewer 会明确确认一次；agent 随时可以用 orca orchestration run-use --id <run> 抢回去。

停止执行时 viewer 会关掉这个终端，把 Run 让出来。

四、viewer 能做什么

核心功能

1. 实时可视化 DAG

节点状态 pending / ready / dispatched / completed / failed / blocked 映射颜色
每个节点角上标着它的 harness
每 2 秒轮询刷新

2. 布局算法切换

横向分层（dagre LR）
纵向分层（dagre TB + Sugiyama）
力导向（Fruchterman–Reingold）
↻ 重排 一键重新自动布局（清除手动拖拽）
选择记忆到 localStorage

3. 拖拽布局

节点可自由拖动
位置在实时轮询刷新中保持不变
只有没有手动动过的节点跟随自动布局

4. 执行动画

dispatched（执行中）节点用蜡笔斜纹从左上到右下一遍遍"涂鸦"
从执行中节点流出的连线先是游动的虚线草稿
再有铅笔笔触从本节点向下游一遍遍"描"成实线

5. 每节点选 harness

点节点在面板里选 claude / kimi / opencode / grok / codex
或自定义命令
持久化到 workspace 的 .orca-dag.config.json
没单独设的节点用顶栏的默认 harness 兜底

6. ▶ 让 Orca 执行 / ⏹ 停止

启动/停止 viewer 内置的自驱动 coordinator
worker 数由 DAG 并行度决定
按需拉起、空闲复用、跑完回收
不用手动加 worker
执行中显示"N worker"

7. 审批门

agent gate-create 后，DAG 上浮出「批准 / 驳回」
人工介入点

8. 节点详情（只读 spec）

点节点看 spec / 状态 / 结果
改描述或依赖 → 让 agent 重绘 DAG

9. 手绘蜡笔风

🖍️ SVG feTurbulence 波动描边
米色速写本画布
艺术感 + 专业感

HTTP 接口

方法	路径	作用
`GET`	`/api/dag`	当前 DAG：`{ nodes, edges, gates, generatedAt }`
`POST`	`/api/run`	`{ harnessByTask?, defaultHarness?, maxConcurrency? }`：启动自驱动 coordinator
`POST`	`/api/run-stop`	停止 coordinator 并回收已拉起的 worker
`GET`	`/api/run-status`	coordinator 实时状态：`{ running, busy, workers, error }`
`POST`	`/api/gates/:id/resolve`	`{ resolution }`：解决审批门
`POST`	`/api/reset`	`orca orchestration reset --tasks` 清空任务
`GET`	`/api/config`	viewer 配置（harness 选择 / 最多并行 / 布局），存在 workspace 的 `.orca-dag.config.json`
`PUT`	`/api/config`	合并写入 viewer 配置
`GET`	`/api/health`	健康检查（返回 workspace 目录）

五、前置条件

必须满足：

Orca ≥ 1.4.160
- orca status --json 里的 result.runtime.appVersion
- Run/Dispatch 契约是 1.4.160 引入的
- 更老的版本没有 run-create / worker-start
编排实验特性已开启
- Settings → Experimental
Orca 运行中
- orca status --json 的 result.runtime.state 应为 "ready"
- 否则先 orca open
项目是 Orca 管理的 worktree
- 加 worker / 执行都要求当前目录是 Orca 注册的 repo/worktree
- 用 orca repo add <path> 或 orca worktree … 先纳管
一个能跑 skill 的 agent（建图侧）
- Claude Code
- 或任何能读 SKILL.md 并执行 Bash 的 agent
viewer 侧只依赖 orca CLI
- 不需要 claude
- 不需要 ANTHROPIC_API_KEY
Bun（可选，仅打二进制时需要）
- Node.js ≥ 20（跑 dev / npm start 时需要）

六、安装和使用

模块 1：安装 skill

ln -s "$PWD/skill" ~/.claude/skills/orca-dag
# 或直接拷贝到 agent 的 skills 目录

使用：

在 agent 里聊需求
它会按 SKILL.md 的规范把 DAG 建进 Orca
提示你运行 orca-dag 打开 viewer

模块 2：运行 viewer

开发模式（前端 5173 + 后端 8787，vite 代理 /api）：

npm install
npm run dev
# 打开 http://localhost:5173

打成全局二进制（推荐）：

npm run build:binary
# 产出 dist/orca-dag（约 60 MB，前端已内嵌）

cp dist/orca-dag /usr/local/bin
# 装到 PATH

cd ~/any/orca-managed/project
orca-dag
# 起在 http://localhost:8787，自动开浏览器
# 用当前目录当工作区

交叉编译（目标机自带 orca 即可）：

TARGET=bun-linux-x64 npm run build:binary

开关：

PORT（默认 8787）
NO_OPEN=1（不自动开浏览器）
WORKSPACE_DIR（覆盖 active worktree）

七、代码结构

skill/SKILL.md            建图规范 + spec 写作约定 + 如何执行（选 harness + Run）+ 边界

server/src/
  index.ts                Express：DAG / run / run-stop / run-status / gates / reset；托管 SPA
  coordinator.ts          自驱动 coordinator 循环：轮询 DAG，并行 dispatch --inject 到按需/复用的 worker
  orca.ts                 orca CLI 封装：task-list→DAG、spawnWorker(自主 agent)、dispatchTask、close
  config.ts               viewer 配置持久化：workspace 下 .orca-dag.config.json 的读写（/api/config）
  webAssets.ts            编译期内嵌前端资源的加载器（生产二进制用）

web/src/
  App.tsx                 全宽 DAG 主壳、每 2s 轮询
  components/DagView.tsx     React Flow 图 + 状态节点（含 harness 标签）
  components/ExecControls.tsx 默认 harness + 最多并行 + Run/Stop + 实时状态
  components/NodePanel.tsx    节点详情 + 每节点 harness 选择
  components/GatePanel.tsx    审批门浮层
  harness.ts                响应式配置 store：每节点 harness / 默认 harness / 最多并行 / 布局（/api/config 持久化）
  layout.ts                 布局算法：dagre 分层（LR/TB）+ 力导向（Fruchterman–Reingold）
  types.ts / api.ts

scripts/build-binary.mjs  vite build → 内嵌资源 → bun --compile → dist/orca-dag