justdeko/zopf

zopf

一款将智能体工作流以图的形式运行的 macOS 应用。

zopf 允许你将多个 claude、codex 或 deepseek harness 会话连接成一张图并一起运行，而不是一次只运行一个终端会话。你还可以将其扩展到多个目录，并在旁边调用技能和其他上下文。

它使用 claude -p 以非交互模式运行 claude code，但你也可以改用 codex 或 deepseek harness。此外还有一个 CLI，可以让你以无头方式运行 zopf 工作流。

功能特性

* 实时输出，包含成本和已用时间
* 在终端中接管会话
* 菜单栏作为你的运行和工作区概览
* 门控（Gates），可暂停运行以等待你的批准
* 连接器（Connectors），用于与外部组件通信

快速开始

你需要 Apple Silicon 上的 macOS，并安装并登录以下之一：

| CLI                                                                 | 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 二进制文件。之后，按照他们的指南添加一个 provider，因为 dsh 本身不附带任何模型。请注意，dsh 本身仍是一个 0.1.x 开发者预览版。

应用

从最新版本下载 zopf-.dmg 并将其拖到 Applications。首次启动时，它会创建 ~/.zopf 作为你的工作区。

CLI

curl -fsSL https://raw.githubusercontent.com/justdeko/zopf/main/install.sh | sh
这会将最新版本解压到 ~/.local/opt，链接 ~/.local/bin/zopf，并将该目录添加到你的 shell rc 中（如果它尚未在 PATH 上）。

CLI 确实需要在你的 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 文件。举个例子，下面这个运行测试套件，并且只在失败时调用一个 agent：

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 参考

编辑器会读写工作流文件，所以你可以手动编辑它，或者在画布上绘制它。你也可以描述它应该做什么，然后让一个 agent 为你起草图。或者你可以调用 claude skills 来构建一个。要添加它们：

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

你可以用它构建什么

* 将一次迁移并行地铺开到十几个仓库，并从每个仓库收集一个 diff
* 用一个昂贵的模型进行审查，然后用一个便宜的模型应用修复
* 并行地总结一个文件夹中的文档，然后让第二个 agent 撰写摘要
* 在一次原本无人值守的运行中途请求你的批准或输入

节点类型

| 类型        | 它做什么                                                                                               |
|-------------|------------------------------------------------------------------------------------------------------------|
| agent     | 一个无头 agent 会话。设置 provider: codex 或 provider: dsh 来切换 CLI（或更改你的默认值） |
| shell     | 一个在你所指向的仓库中、在你的登录 shell 里运行的命令                                        |
| connector | 一个与外部某物通信的脚本                                                                   |
| gate      | 停止并等待你批准或拒绝                                                               |
| input     | 向你提问并将答案作为 ${ask.result} 传递下去                                            |
| branch    | 根据条件选择一个出站分支，例如："${build.exitCode} == 0"。                                 |

步骤通过 ${step.result} 读取先前的输出。在此之上没有表达式语言。

工作区

工作区是一个 .zopf/ 文件夹，类似于 git 的 .git。可以在任何地方使用一个，否则 ~/.zopf 是其他所有内容的默认位置。

/.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。

CLI 用法

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 且不会运行任何节点。

CLI 与应用程序中有两点略有不同：

- 没有 gate，除非你指定 --on-gate approve，否则运行会就此停止
- 内联批准是关闭的，因此更严格的权限模式可能会阻止运行

安全

zopf 在你自己的账户和登录下在你的笔记本电脑上运行。每个步骤都是一个具有你的文件权限的子进程。

除了你自己使用连接器、脚本等构建的内容之外，没有外部工具或连接。该应用每周检查一次此 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使用了哪些工具。