智能体工作流图 justdeko/zopf

zopf

把智能体工作流当作图来跑的 macOS 应用。

zopf 让你把多个 claude、codex 或 deepseek harness 会话连成一张图，一起跑，而不是一次只开一个终端会话。你还能跨多个目录铺开，顺手调用技能和其他上下文。

它用 claude -p 以非交互模式跑 claude code，不过你也可以改用 codex 或 deepseek harness。另外还有一个命令行，让你无头运行 zopf 工作流。

功能

* 实时输出，附带成本和耗时
* 在终端里接管会话
* 菜单栏，一览你的运行和工作区
* 闸门，暂停运行等你批准
* 连接器，与外部组件通信

快速上手

你需要 Apple Silicon 上的 macOS，并安装且登录下面任意一个：

| 命令行 | provider: | zopf 运行什么 |
| Claude Code | claude | claude -p，流式 JSON |
| Codex | codex | codex exec --json |
| DeepSeek Harness | dsh | dsh --profile headless |

[!NOTE]
zopf 目前支持 claude code、codex 和 dsh，但我只大量测试过 claude code，因为它是我日常主力。

claude 和 codex 按官方说明安装即可。dsh 要多一步：全局安装，因为 zopf 会在你的登录 PATH 上找 dsh 二进制。之后照他们的指南添加服务商，因为 dsh 自身不带模型。注意 dsh 本身还是 0.1.x 开发者预览版。

应用

从最新发布下载 zopf-<version>.dmg，拖进 Applications。首次启动会创建 ~/.zopf 作为你的工作区。

命令行

curl -fsSL https://raw.githubusercontent.com/justdeko/zopf/main/install.sh | sh
它会把最新版本解压到 ~/.local/opt，链接 ~/.local/bin/zopf，如果这个目录还不在 PATH 里，就把它加进你的 shell rc。

命令行确实需要 PATH 里有 JDK 21 或更新版本，你可以用 homebrew 装一个：

brew install --cask temurin

从源码构建

git clone https://github.com/justdeko/zopf && cd zopf
basic run
./gradlew :desktopApp:run
build the .app and open it from finder
./gradlew :desktopApp:runMacApp
cli/build/install/zopf-cli/bin/zopf
./gradlew :cli:installDist

工作流

工作流就是一个 YAML 文件。举个例子，下面这个跑测试套件，只在失败时才调用智能体：

name: verify
repos:
- id: app
path: ~/dev/app
defaults:
repo: app
nodes:
- id: tests
type: shell
title: Run the suite
command: npm test
- id: diagnose
type: agent
title: Fix what broke
permissionMode: acceptEdits
prompt: |
npm test just failed. Its output:

${tests.result}

Find the cause and fix it, then re-run the suite and report what is green.
edges:
- from: tests
to: diagnose
on: failure

要理解工作流节点，有几件事很关键：

- 边上的数据是隐式的，你可以在下一个节点执行时用字面量嵌入：${tests.result}
- 边可以带条件：例子里的 on: failure，或者分支节点用 when: true / when: false
- on: failure 的边不会让整次运行失败（节点仍然显示为失败）
- 有多条入边的节点会等所有入边都结束
- 一般来说，照着 schema 参考 来写

编辑器会读写工作流文件，所以你可以手动改，也可以在画布上画。你还可以描述它该做什么，让智能体帮你起草整张图。或者调用 claude 技能 来构建一个。要添加它们：

/plugin marketplace add justdeko/zopf
/plugin install zopf@zopf

你可以用它做什么

* 把一次迁移并行铺到十几个仓库，再从每个仓库收集 diff
* 用贵的模型做审查，再用便宜的模型应用修复
* 并行总结一文件夹文档，再让第二个智能体写摘要
* 在一次本来无人值守的运行中途，请求你的批准或输入

节点类型

| 类型 | 作用 |
| agent | 无头智能体会话。设置 provider: codex 或 provider: dsh 来切换命令行（或改默认值） |
| shell | 在你指定的仓库里，于你的登录 shell 中运行的命令 |
| connector | 与外部系统通信的脚本 |
| gate | 停下来等你批准或拒绝 |
| input | 向你提问，并把答案作为 ${ask.result} 传下去 |
| branch | 按条件选择一个出口，例如："${build.exitCode} == 0"。 |

步骤用 ${step.result} 读取上一步的输出。除此之外没有表达式语言。

工作区

工作区就是一个 .zopf/ 文件夹，类似 git 的 .git。任何地方都能用一个，否则其他所有内容默认放在 ~/.zopf。

<repo>/.zopf/ or ~/.zopf/ workflows/, connectors/, optional zopf.yaml
~/Library/Application Support/zopf/ settings.json, runs/ (every run, as replayable JSONL)
~/Library/Logs/zopf/zopf.log what to send with a bug report

zopf.yaml 是可选的。它给工作区命名，并为其中每个工作流设置默认值，用的键和工作流的 defaults 相同：

name: Payments
defaults:
model: sonnet
repo: self

运行归档会不断变大，所以一个话多的构建步骤可能跑出相当大的体积。想限制它，去 Settings → History，或者执行 zopf prune --keep 50。

命令行用法

zopf run ship-feature --on-gate approve --answer env=staging
only prints order of workflow execution
zopf run ship-feature --dry-run
list workflows in a given folder
zopf list
check workflow validity
zopf validate
show past runs
zopf runs --last 5
resume the last run from where it stopped
zopf run --resume last

退出码：

- 0 正常
- 1 某个步骤失败且未被捕获
- 2 已停止
- 3 从未启动

zopf run 在启动任何东西之前会先校验工作流，所以文件里出错就意味着退出码 3，没有任何节点会运行。

命令行和 app 有两处略有不同：

- 没有 gate，运行就停在那里，除非你指定 --on-gate approve
- 内联批准是关闭的，所以更严格的权限模式可能挡住运行

安全

zopf 在你的笔记本上、用你自己的账号和登录运行。每个步骤都是一个子进程，拥有你的文件权限。

除了你自己用 connector、脚本等搭出来的东西，没有任何外部工具或连接。app 每周检查一次这个 GitHub 页面，判断有没有更新的版本。想关掉更新检查：ZOPF_NO_UPDATE_CHECK=1 或 DO_NOT_TRACK=1。

把工作流指向你本来就愿意在那里运行的位置，并且只有在你确信智能体输出的内容时，才把它送进 shell 执行。

商标

zopf 是独立的个人项目。它不隶属于 Anthropic、OpenAI、DeepSeek、Apple 或 GitHub，也不受其赞助或背书。Claude 和 Claude Code 是 Anthropic PBC 的商标；Codex 是 OpenAI 的商标； DeepSeek 是杭州深度求索人工智能有限公司的商标；macOS 和 Finder 是 Apple Inc. 的商标。这里提到它们，只是为了说明 zopf 用了哪些工具。