dag-fleet

Fleet

一个可在 tmux 中并行运行 claude -p、codex exec 或 pi -p 工作器，并支持预算和 DAG 依赖的技能。支持 Claude、Codex 和 Pi 提供方，可按 Fleet 或工作器单独设置。所有终止、引导和重新定向操作均由操作员负责——不会自动重启、自动验证或循环监护。

前置条件

• bash >= 4.0——macOS 自带的是 bash 3.2（2007 年发布）。安装新版 bash：brew install bash
• flock——Linux 内置。macOS：brew install flock
• tmux——brew install tmux 或 apt install tmux
• jq——brew install jq 或 apt install jq

macOS 快速入门

brew install bash tmux jq flock
# Then invoke launch.sh explicitly with bash 4+:
/opt/homebrew/bin/bash /path/to/dag-fleet/scripts/launch.sh <fleet-root>

如果 flock 不可用，launch.sh 会跳过锁定并发出警告。传入 --no-lock 可屏蔽此警告。

何时使用此技能（以及何时不使用）

**首先：只要符合以下任一条件，请优先使用 Claude Code 内置的 Agent 工具。**它更简单、更快捷，也完全不需要 Fleet 机制。

• 工作可在当前对话中完成
• 所有子 Agent 都会在 10 分钟内完成
• 你会在同一会话中汇总结果
• 你不需要预算上限或依赖排序

仅在符合以下至少 1 个条件时才使用此技能：

• **持久运行：**运行时间会超出父 claude 进程的生命周期（例如，多小时的 Fleet，或用户合上笔记本电脑后仍需运行）
• **按工作器设置预算：**你需要为每个工作器强制执行 max_budget_usd: N
• **DAG 依赖：**工作器 D 必须等待 A、B、C 全部完成
• **为不同工作器混用模型：**同一 Fleet 中使用 Sonnet 研究员和 Haiku 验证员
• **查看 tmux 面板：**用户希望连接到各个工作器并查看其输出

如果以上条件都不符合，请停止阅读此技能，改用 Agent 工具。

此技能不是什么

• 不是自动恢复系统。如果工作器失败或卡住，由操作员决定如何处理。
• 不是监护程序。没有 orchestrate.sh，不会检测卡住并终止，也不会在运行过程中引导工作器。
• 不适用于“并行启动 3 个快速查询”——这正是 Agent 工具的用途。

可用脚本

脚本	调用时机	参数
launch.sh	根据 fleet.json 启动新的 Fleet	<fleet-root> [--force-relaunch] [--no-lock]
status.sh	显示正在运行和已完成的工作、实时费用以及每个工作器的最后一条消息	<fleet-name-or-root> [-v] [--watch] [--json]
kill.sh	停止单个工作器或整个 Fleet（操作员强制停止）	<fleet-name-or-root> <worker-id>|all [--force]
relaunch-worker.sh	编辑某个工作器的 prompt.md 后，仅重新运行该工作器	<fleet-name-or-root> <worker-id>
report.sh	Fleet 完成后生成 Markdown 摘要	<fleet-root>
view.sh	捕获单个工作器的 tmux 面板内容	<fleet-name-or-root> <worker-id>
feed.sh	汇总并实时输出所有工作器的事件流	<fleet-name-or-root> [--agent <id>]

实用工具（位于 lib/）：

实用工具	用途	用法
dag-viz.py	可视化 Fleet DAG 结构（ASCII 或 mermaid）	python3 ${AGENTS_SKILLS_DIR}/lib/dag-viz.py <fleet.json> [--mermaid]

所有脚本都接受绝对 Fleet 根目录路径或 Fleet 名称（通过 ~/.claude/fleet-registry.json 解析；该文件由 launch.sh 自动填充）。

启动流程（必须严格遵循）

当用户要求你启动一个工作集群时：

1. 将 FLEET_ROOT 设置为用户指定的目录。若未指定，则默认为当前工作目录。仅使用绝对路径。 1b. **macOS 检查：**如果使用 macOS，请确认 bash --version >= 4.0，并且 flock 可用。如果不可用，请通过 brew 安装或使用 --no-lock。
2. mkdir -p $FLEET_ROOT/workers
3. 生成 $FLEET_ROOT/fleet.json——完整架构请参见 references/fleet-json-schema.md。必需的顶层字段：fleet_name、config、workers[]。每个 worker 都需要 id、type、task、model、max_turns、max_budget_usd。使用 depends_on: [...] 指定 DAG 顺序。
4. **为每个 worker 创建 $FLEET_ROOT/workers/{id}/prompt.md。**提示词必须逐字包含以下行：

   Save ALL output files to $FLEET_ROOT/workers/{id}/output/ — use absolute paths.
   

   （替换为实际的工作集群根目录和 worker id。）
5. 运行：bash ${AGENTS_SKILLS_DIR}/scripts/launch.sh $FLEET_ROOT
6. 不要自行编写 tmux/claude 命令。launch.sh 会处理拓扑排序、创建 tmux 会话、启动各 worker、设置预算以及注册。
7. 务必告知用户确切的状态命令，以便他们手动监控：

   bash ${AGENTS_SKILLS_DIR}/scripts/status.sh <fleet-name-or-root>
   

   每次启动后都必须执行此操作。用户必须能够在不询问你的情况下检查状态。

重新运行一个 worker（补充工作流）

用户已有一个已完成的工作集群，并希望添加 1–2 个来源／修改一个 worker 的指令：

1. 编辑 $FLEET_ROOT/workers/{id}/prompt.md（添加新来源／指令）
2. 运行 bash ${AGENTS_SKILLS_DIR}/scripts/relaunch-worker.sh <fleet-name> {id}
3. worker 旧的 session.jsonl 会轮换为 .bak，并创建一个全新的 tmux 窗口；其他 worker 不受影响
4. **工作集群的 tmux 会话必须仍然存在。**如果已被终止，用户必须对整个工作集群运行 launch.sh --force-relaunch——relaunch-worker.sh 只能用于仍在运行的工作集群会话。

如果用户想重新运行多个 worker，请逐个进行。没有批量重新运行功能，这是有意设计的。

终止

有两种由操作员发起的终止方式，不会自动终止：

• kill.sh <fleet> <worker-id>——终止一个 worker。会清理其子进程后代。当你判定某个 worker 正在走错方向时使用。
• kill.sh <fleet> all --force——拆除整个工作集群，关闭所有 tmux 窗口，清理所有孤立子进程，将 worker 标记为 KILLED，并从注册表中注销。

没有 steer.sh。无法在运行过程中重定向。用户想让“这个 worker 改变方向”时，应采用的工作流是：对它运行 kill.sh，编辑 prompt.md，再运行 relaunch-worker.sh。共三个步骤，完全由操作员掌控。

重置部分运行的工作集群

当工作集群只运行了一部分（提示词有误、模型错误、遇到 bug），而你想从头重新启动且不产生状态冲突时使用。

bash ${AGENTS_SKILLS_DIR}/scripts/reset.sh <FLEET_ROOT> [--soft|--hard] [--dry-run] [--force]

保留（两个级别均如此）：fleet.json 结构、workers/{id}/prompt.md。 **使用 --soft 时清除（默认）：**先前的运行输出归档至 archive/<ts>/，tmux 会话被终止，fleet.json 中的状态字段被清除。 **使用 --hard 时清除：**工作集群根目录下的所有内容，但 fleet.json 和提示词除外；注册表条目也会被移除。

如果检测到正在运行的 worker，会以退出码 2 拒绝执行——先传入 --force 将其终止。使用 --dry-run 预览。

Worker 类型

每个 worker 上的 type 字段控制传递给 claude 的 --disallowed-tools 集合（对于 pi，则控制 --tools 允许列表；对于 codex，则控制沙盒模式）。请选择一种：

• read-only — 禁用：Bash、Edit、Write、Agent、WebFetch、WebSearch。**无法写入文件。**仅用于纯分析，且输出从 session.jsonl 中的助手消息捕获。
• write — 禁用：Bash、Agent、WebFetch、WebSearch。用于综合器以及任何会写入输出文件的 worker。
• code-run — 禁用：Agent、WebFetch、WebSearch（构建/测试 worker 通常使用此类型）
• research — 禁用：Bash、Edit、Agent（启用网页访问）。用于研究人员，而不是 read-only。
• reviewer — 禁用：Bash、Edit、Agent、WebFetch、WebSearch。仅可使用 Read + Write。用于会写入评审结论文件的评审人员。
• orchestrator — 禁用：Agent、WebFetch、WebSearch、Edit

警告：read-only 无法写入文件。如果 worker 需要保存输出（findings.md、synthesis.md 等），请使用 write、research、reviewer 或 code-run。将综合器设为 read-only 会让它耗尽全部预算来寻找 Write 工具。

完整权限矩阵请参阅 references/worker-types.md。

Provider 支持（Claude + Codex + Pi）

Worker 可使用 claude（默认）、codex（OpenAI Codex CLI）或 pi（pi.dev CLI）运行。可在 fleet 级别或单个 worker 上设置：

{
  "config": {
    "provider": "pi",
    "model": "kimi-for-coding",
    "reasoning_effort": "medium"
  },
  "workers": [
    { "id": "researcher", "type": "research", "provider": "pi", "model": "kimi-for-coding", "reasoning_effort": "high" },
    { "id": "writer", "type": "write", "provider": "claude", "model": "sonnet" }
  ]
}

{
  "config": {
    "provider": "codex",
    "model": "gpt-5.4",
    "reasoning_effort": "medium"
  },
  "workers": [
    { "id": "researcher", "type": "research", "provider": "codex", "model": "gpt-5.4", "reasoning_effort": "medium" },
    { "id": "writer", "type": "write", "provider": "claude", "model": "sonnet" }
  ]
}

Provider 专属字段

字段	值	默认值	范围
provider	"claude" | "codex" | "pi"	"claude"	配置 + 单个 worker
reasoning_effort	"low" | "medium" | "high"	（无）	配置 + 单个 worker，仅适用于 codex/pi

Codex 模型别名

模型	用途
gpt-5.5	最新旗舰模型 — 推理能力最强，有条件时优先使用
gpt-5.4	旗舰模型 — 推理能力强，是可靠的默认选择
gpt-5.4-mini	快速/低成本 — 验证器、简单任务
gpt-5.3-codex	专注编码（正在迁移到 gpt-5.4）

Pi 模型

Pi 是一个provider 执行框架，不是模型。实际使用的模型由 pi 配置中指定的 provider 决定。运行 pi --list-models 查看可用模型。

**示例：**配置 kimi-coding provider 时：

模型	用途
kimi-for-coding	默认/稳定 ID — 始终解析为最新的 Kimi Code 模型
kimi-k2-thinking	深度推理 — 研究类 worker

你在 model 中填写的字符串会原样传递给 pi -p --model。没有别名，也不会进行验证。

模型系列指南

当用户说“使用 [系列]”但未指定每个 worker 的具体模型时，请根据 worker 职责分配模型：

Claude 系列：

Worker 职责	模型
综合、架构、复杂推理	opus
通用 worker、研究人员、构建人员	sonnet
验证器、代码检查工具、简单检查	haiku

Pi / Kimi 系列：

Worker 职责	模型	reasoning_effort
综合、深度推理、复杂分析	kimi-k2-thinking	high（或 medium）
通用编码、研究、构建人员	kimi-for-coding	medium
简单检查、验证器	kimi-for-coding	low

Codex / GPT 系列：

Worker 职责	模型	reasoning_effort
复杂推理、旗舰级任务	gpt-5.5	high
通用 worker、研究	gpt-5.4	medium
验证器、简单任务	gpt-5.4-mini	medium 或 low

**规则：**根据任务复杂度匹配模型能力。不要把 opus 用于代码检查，也不要把 haiku 用于架构评审。

相较于 Claude 的提供方限制

Codex：

• 没有 --max-budget-usd — codex 没有单个工作线程的预算上限。仍可进行舰队级成本跟踪（根据令牌数量估算）。
• 没有 --fallback-model — codex 不支持自动模型回退。
• 无法禁用单个工具 — codex 使用沙箱模式（read-only、workspace-write），而不是 --disallowed-tools。工作线程类型会自动映射。
• Web 搜索 — 研究工作线程会自动获得 -c 'web_search="live"'。
• 所有输出工作线程都需要 workspace-write — codex 的 read-only 沙箱会阻止所有文件写入，包括输出写入。

Pi：

• 没有 --max-budget-usd — pi 没有单个工作线程的预算上限。舰队级成本跟踪通过令牌估算实现。
• 没有 --fallback-model — pi 不支持自动模型回退。
• --tools 允许列表 — pi 使用允许列表（而非阻止列表）。工作线程类型会自动映射到正确的工具集。
• 会话目录 — pi 将会话写入每个工作线程专属的 .pi-sessions/ 目录，并将 JSONL 日志符号链接到标准路径。

DAG 依赖关系

{
  "id": "synthesizer",
  "depends_on": ["researcher-01", "researcher-02"]
}

launch.sh 使用共享的 lib/dag.sh 原语（Kahn BFS 分层拓扑排序）对工作线程排序，并等待依赖项发出终态 result 事件后再启动依赖它们的工作线程。创建任何 tmux 状态之前就会检测循环依赖 — 舰队会以状态码 2 退出，并在 stderr 输出 CYCLE:a,b,...。同一层中的工作线程会并行运行，数量最多为 max_concurrent。启动前可使用 dag-viz.py 预览 DAG 结构。

预算

• worker.max_budget_usd: N — 单个工作线程的硬性上限，传递给 claude --max-budget-usd
• config.max_budget_fleet: N — 舰队总预算上限；超过后，launch.sh 会停止启动新工作线程（不会终止已在运行的工作线程；此上限的含义是“不再新增支出”）

严格规则

1. 每次操作都必须使用上述脚本。 切勿自行编写 tmux / claude 命令。
2. 切勿对 claude 使用 --bare 标志 — 这会导致身份验证失败。
3. 舰队根目录 = 用户目录。 默认使用当前工作目录。所有舰队文件都必须放在 $FLEET_ROOT 中。
4. 工作线程输出路径必须是绝对路径： $FLEET_ROOT/workers/{id}/output/。在其 prompt.md 中告知工作线程此路径。
5. 启动工作线程的唯一方式是 launch.sh。 有选择地重新运行单个工作线程的唯一方式是 relaunch-worker.sh。没有其他方式。
6. 终止工作线程和更改方向由操作员负责。 不要自动终止、自动重启或自动重定向。如果工作线程行为异常，请告知用户并由他们决定。
7. 不要臆造缺失的脚本。 如果你想使用 steer.sh、verify.sh、add-worker.sh 或 orchestrate.sh，请记住这些脚本已被有意移除。改用上述由操作员掌控的工作流。

应当驳回的自我辩解

Agent 的说法	驳斥
“任务足够简单，我可以自己编写 tmux 命令”	这项技能的存在就是为了避免你忘记那 15 件事（unset CLAUDECODE、--disallowed-tools、会话命名、注册表、拓扑排序）。使用 launch.sh。
“我会用 relaunch-worker.sh 一次性重启所有卡住的工作线程”	一次一个，有意为之。批量重启导致实验 001 损失了 $20 — 每个工作线程都重建缓存，累积起来造成了损失。
“工作线程好像卡住了 — 我应该终止并重启它”	长时间思考可能看起来像卡住了。先检查 status.sh 或 view.sh。只有操作员可以终止工作线程。
“每个工作线程完成后，我应该添加一个验证步骤”	没有验证步骤。操作员会读取输出并作出决定。自动验证在造成的损害超过其发现的故障后，已被移除。
“我就加上 --bare 来加快速度”	--bare 会导致身份验证失败。绝不要使用。这是严格规则 #2。

何时放弃使用此技能

如果用户要求的行为需要自动恢复、运行中途调整或逐个工作者进行验证循环，请告知他们，此技能经过设计后已不再提供这些功能。 建议：

• 对于自动恢复 → 他们应自行运行监视脚本，并从脚本中调用 kill.sh + relaunch-worker.sh
• 对于运行中途调整 → 终止 + 编辑 prompt.md + 重新启动工作者
• 对于验证 → 他们自行查看输出文件并作出判断

经过实验发现，自动化行为造成的损害比其试图恢复的故障更大，因此我们特意缩减了此技能的功能范围。

$ARGUMENTS