Overstory

面向 AI 编码代理的多智能体编排工具。

Overstory 通过在 Git 工作树中利用 tmux 派生工作代理、借助自定义 SQLite 邮件系统进行协调，并以分层冲突解决机制合并它们的工作成果，将单个编码会话转变为一个多智能体团队。一个可插拔的 AgentRuntime 接口允许你在 11 种运行时之间切换——Claude Code、Pi、Gemini CLI、Aider、Goose、Amp，或你自己的适配器。

警告：智能体群并非万能解决方案。 在不了解多智能体编排的风险之前，请勿部署 Overstory——错误率叠加、成本放大、调试复杂性以及合并冲突都是常态，而非边缘情况。请在将此工具用于生产环境前阅读 STEELMAN.md 中的完整风险分析，以及 Agentic Engineering Book（网页版）。

安装

需要 Bun v1.0+、git 和 tmux。至少需安装一种受支持的代理运行时：

• Claude Code (claude CLI)
• Pi (pi CLI)
• GitHub Copilot (copilot CLI)
• Codex (codex CLI)
• Gemini CLI (gemini CLI)
• Cursor CLI (agent CLI)
• Sapling (sp CLI)
• OpenCode (opencode CLI)
• Aider (aider CLI)
• Goose (goose CLI)
• Amp (amp CLI)

bun install -g @os-eco/overstory-cli

或者无需安装直接试用：

npx @os-eco/overstory-cli --help

开发

git clone https://github.com/jayminwest/overstory.git
cd overstory
bun install
bun link              # 使 'ov' 全局可用

bun test              # 运行所有测试
bun run lint          # Biome 检查
bun run typecheck     # tsc --noEmit

快速入门

# 在你的项目中初始化 Overstory
cd your-project
ov init

# 将钩子安装到 .claude/settings.local.json
ov hooks install

# 启动协调器（持久化编排器）
ov coordinator start

# 或者派生独立的工作代理
ov sling <task-id> --capability builder --name my-builder

# 查看代理状态
ov status

# 实时仪表板，用于监控整个代理集群
ov dashboard

# 推动卡住的代理
ov nudge <agent-name>

# 查看来自代理的邮件
ov mail check --inject

命令

每个命令在标注处都支持 --json。全局标志：-q/--quiet、--timing、--project <path>。ANSI 颜色会尊重 NO_COLOR 设置。

核心流程

命令	描述
ov init	初始化 .overstory/ 并引导 os-eco 工具（--yes、--name、--tools、--skip-mulch、--skip-seeds、--skip-canopy、--skip-onboard、--json）
ov sling <task-id>	派生一个工作代理（--capability、--name、--spec、--files、--parent、--depth、--skip-scout、--skip-review、--max-agents、--dispatch-max-agents、--skip-task-check、--no-scout-check、--runtime、--base-branch、--profile、--json）
ov stop <agent-name>	终止正在运行的代理（--clean-worktree、--json）
ov prime	为编排器/代理加载上下文（--agent、--compact）
ov spec write <task-id>	编写任务规范（--body）
ov discover	通过协调驱动的侦察蜂群发现现有代码库（--skip、--name、--attach、--watchdog、--json）
ov update	从已安装包中刷新 .overstory/ 管理的文件（--agents、--manifest、--hooks、--dry-run、--json）

协调

命令	描述
ov coordinator start	启动持久化协调代理（--attach/--no-attach、--watchdog、--monitor、--profile）
ov coordinator stop	停止协调器
ov coordinator status	显示协调器状态
ov coordinator send	向协调器发送即发即弃的消息（--subject）
ov coordinator ask	向协调器发起同步请求与响应（--subject、--timeout）
ov coordinator output	显示协调器近期输出（--lines）
ov coordinator check-complete	评估退出触发条件，返回完成状态
ov orchestrator start	启动多仓库编排代理（--attach/--no-attach、--watchdog、--profile）
ov orchestrator stop	停止编排器
ov orchestrator status	显示编排器状态
ov orchestrator send	向编排器发送即发即弃的消息（--subject）
ov orchestrator ask	向编排器发起同步请求与响应（--subject、--timeout）
ov orchestrator output	显示编排器近期输出（--lines）
ov supervisor start	[已弃用] 启动项目级监督代理
ov supervisor stop	[已弃用] 停止监督代理
ov supervisor status	[已弃用] 显示监督代理状态

消息传递

命令	描述
ov mail send	发送消息（--to、--subject、--body、--type、--priority）
ov mail check	检查收件箱——未读消息（--agent、--inject、--debounce、--json）
ov mail list	列出带有筛选条件的消息（--from、--to、--unread）
ov mail read <id>	标记消息为已读
ov mail reply <id>	在同一对话线程中回复（--body）
ov nudge <agent> [message]	向代理发送简短提醒（--from、--force、--json）

任务组

命令	描述
ov group create <name>	创建用于批量跟踪的任务组
ov group status <name>	显示组进度
ov group add <name> <issue-id>	将问题添加到组
ov group list	列出所有组

合并

命令	描述
ov merge	将代理分支合并到主干（--branch、--all、--into、--dry-run、--json）

可观测性

命令	描述
ov status	显示所有活跃代理、工作树和跟踪器状态（--json、--verbose、--all）
ov dashboard	用于代理监控的实时 TUI 仪表板（--interval、--all）
ov inspect <agent>	对单个代理进行深度检查（--follow、--interval、--no-tmux、--limit、--json）
ov trace	查看代理/任务时间线（--agent、--run、--since、--until、--limit、--json）
ov errors	聚合显示跨代理的错误视图（--agent、--run、--since、--until、--limit、--json）
ov replay	按时间顺序交错回放（--run、--agent、--since、--until、--limit、--json）
ov feed	统一的实时事件流（--follow、--interval、--agent、--run、--json）
ov logs	查询跨代理的 NDJSON 日志（--agent、--level、--since、--until、--follow、--json）
ov costs	令牌/成本分析与细分（--live、--self、--agent、--run、--bead、--by-capability、--last、--json）
ov metrics	显示会话指标（--last、--json）
ov run list	列出编排运行记录（--last、--json）
ov run show <id>	显示运行详情
ov run complete	将当前运行标记为已完成

基础设施

命令	描述
ov hooks install	将编排器钩子安装到 .claude/settings.local.json 文件中（--force）
ov hooks uninstall	移除编排器钩子
ov hooks status	检查是否已安装钩子
ov worktree list	列出带有状态的工作树
ov worktree clean	清理已完成的工作树（--completed、--all、--force）
ov watch	启动看门狗守护进程 — 第 0 层（--interval、--background）
ov monitor start	启动第 2 层监控代理
ov monitor stop	停止监控代理
ov monitor status	显示监控状态
ov log <event>	记录钩子事件（--agent）
ov clean	清理工作树、会话和工件（--completed、--all、--run）
ov doctor	对 Overstory 部署执行健康检查 — 共 12 个类别（--category、--fix、--json）
ov ecosystem	显示操作系统生态工具的版本及健康状况（--json）
ov upgrade	将 Overstory 升级到最新的 npm 版本（--check、--all、--json）
ov agents discover	根据能力/状态/父代理发现代理（--capability、--state、--parent、--json）
ov completions <shell>	生成 shell 补全脚本（bash、zsh、fish）

架构

Overstory 使用指令叠加层和工具调用防护机制，将代理会话转化为编排式工作流。每个代理通过 tmux 在隔离的 Git 工作树中运行。代理间的消息传递由自定义的 SQLite 邮件系统（WAL 模式，每次查询约 1–5 毫秒）处理，支持类型化协议消息和广播功能。一个具有 4 层冲突解决机制的 FIFO 合并队列会将各代理分支合并回规范分支。分层看门狗系统（第 0 层机械守护进程、第 1 层 AI 辅助分流、第 2 层监控代理）确保整个集群的健康状态。完整技术细节请参阅 CLAUDE.md。

运行时适配器

Overstory 是运行时无关的。AgentRuntime 接口（src/runtimes/types.ts）定义了契约——每个适配器负责为其运行时环境启动进程、部署配置、实施防护机制、检测就绪状态以及解析会话日志。可在 config.yaml 中设置默认值，或使用 ov sling --runtime <name> 命令为特定代理覆盖设置。

运行时	CLI	防护机制	稳定性
Claude Code	claude	settings.local.json 钩子	稳定
Sapling	sp	.sapling/guards.json	稳定
Pi	pi	.pi/extensions/ 防护扩展	实验性
Copilot	copilot	（无 — --allow-all-tools）	实验性
Cursor	agent	（无 — --yolo）	实验性
Codex	codex	操作系统级别的沙箱（Seatbelt/Landlock）	实验性
Gemini	gemini	--sandbox 标志	实验性
Aider	aider	（无 — --yes-always）	实验性
Goose	goose	基于配置文件的权限	实验性
Amp	amp	内置审批系统	实验性
OpenCode	opencode	（无）	实验性

工作原理

指令叠加层 + 工具调用防护机制 + ov CLI 将您的编码会话转变为多代理编排系统。一个持久化的协调代理负责管理任务分解和调度，而机械看门狗守护进程则在后台监控代理的健康状况。

编排器（多仓库协调者的协调者）
  --> 协调器（项目根目录下的持久化编排者）
        --> 监督员 / 团队负责人（团队领导，第 1 层）
              --> 工人：侦察员、构建者、评审员、合并者（第 2 层）

代理类型

代理	角色	权限
编排器	多仓库协调者的协调者——为每个子仓库派遣协调器	只读
协调器	持久化编排者——分解目标、派遣代理、跟踪任务组	只读
监督员	项目级团队负责人——管理工人生命周期、处理提醒/升级	只读
侦察员	只读探索与研究	只读
构建者	实现与代码修改	读写
评审员	验证与代码审查	只读
领队	团队协调，可派生子工人	读写
合并者	分支合并专家	读写
监控员	第 2 层持续舰队巡逻——持续健康监测	只读

关键架构

• 代理定义：两层系统——基础 .md 文件定义 HOW（工作流程），每项任务的叠加层定义 WHAT（任务范围）。基础定义内容会自动注入到派生的代理叠加层中。
• 消息传递：自定义的 SQLite 邮件系统，采用类型化协议——8 种消息类型（worker_done、merge_ready、dispatch、escalation 等），用于结构化的代理协调，并支持带组地址的广播消息（@all、@builders 等）。
• 工作树：每个代理都拥有独立的 Git 工作树——避免代理之间的文件冲突。
• 合并：基于 SQLite 的 FIFO 合并队列，配备 4 层冲突解决机制。
• 看门狗：分层健康监测——第 0 层机械守护进程（tmux/PID 活性）、第 1 层 AI 辅助故障分流、第 2 层监控代理用于持续舰队巡逻。
• 工具强制执行：针对不同运行时的防护机制（Claude Code 的钩子、Pi 的扩展），可自动阻止非实现类代理的文件修改操作，以及所有代理的危险 Git 操作。
• 任务组：批量协调，当所有成员的任务完成后自动关闭。
• 会话生命周期：检查点保存/恢复以提高容错能力，交接编排用于崩溃恢复。
• 令牌监控：从运行时会话日志文件（JSONL）中提取会话指标。

项目结构

overstory/
  src/
    index.ts                      CLI 入口点（Commander.js 程序）
    types.ts                      共享类型和接口
    config.ts                     配置加载 + 验证
    errors.ts                     自定义错误类型
    json.ts                       标准化 JSON 封装辅助函数
    commands/                     每个 CLI 子命令一个文件（37 个命令）
      agents.ts                   代理发现与查询
      coordinator.ts              持久化编排器生命周期
      supervisor.ts               团队负责人管理 [已弃用]
      dashboard.ts                实时 TUI 仪表板（通过 Chalk 使用 ANSI）
      hooks.ts                    编排器钩子管理
      sling.ts                    代理启动
      group.ts                    任务组批量跟踪
      nudge.ts                    代理提醒
      mail.ts                     代理间消息传递
      monitor.ts                  第二层监控管理
      merge.ts                    分支合并
      status.ts                   舰队状态概览
      prime.ts                    上下文预热
      init.ts                     项目初始化
      worktree.ts                 工作树管理
      watch.ts                    看门狗守护进程
      log.ts                      钩子事件日志记录
      logs.ts                     NDJSON 日志查询
      feed.ts                     统一实时事件流
      run.ts                      编排运行生命周期
      trace.ts                    查看代理/任务时间线
      clean.ts                    清理工作树/会话
      doctor.ts                   健康检查执行者（12 个检查模块）
      inspect.ts                  深度代理检查
      spec.ts                     任务规范管理
      errors.ts                   聚合错误视图
      replay.ts                   交错事件回放
      stop.ts                     终止代理
      costs.ts                    Token/成本分析
      metrics.ts                  会话指标
      ecosystem.ts                os-eco 工具仪表板
      update.ts                   刷新管理文件
      upgrade.ts                  npm 版本升级
      discover.ts                 通过协调器驱动的侦察蜂群发现旧代码库
      orchestrator.ts             多仓库协调（PersistentAgentSpec）
      completions.ts              Shell 补全生成（bash/zsh/fish）
    canopy/
      client.ts                   Canopy 客户端（提示渲染、列表显示、事件发射）
    agents/                       代理生命周期管理
      manifest.ts                 代理注册表（加载 + 查询）
      overlay.ts                  动态 CLAUDE.md 叠加层生成器
      identity.ts                 代理持久化身份（简历）
      checkpoint.ts               会话检查点保存/恢复
      lifecycle.ts                交接编排
      hooks-deployer.ts           部署钩子 + 工具强制执行
      copilot-hooks-deployer.ts   将钩子配置部署到 Copilot 工作树
      guard-rules.ts              共享守卫常量（工具列表、bash 模式）
    worktree/                     Git 工作树 + tmux 管理
    mail/                         SQLite 邮件系统（类型化协议、广播）
    merge/                        FIFO 队列 + 冲突解决
    watchdog/                     分层健康监测（守护进程、分诊、健康）
    logging/                      多格式日志记录器 + 净化器 + 报告器 + 颜色控制 + 共享主题/格式
    metrics/                      SQLite 指标 + 定价 + 转录解析
    doctor/                       健康检查模块（12 个检查）
    utils/                        共享工具（二进制、文件系统、PID、时间、版本）
    insights/                     会话洞察分析器，用于自动专家化
    runtimes/                     代理运行时抽象（注册表 + 适配器：Claude、Pi、Copilot、Codex、Gemini、Sapling、OpenCode、Cursor、Aider、Goose、Amp）
    tracker/                      可插拔任务跟踪器（珠子 + 种子后端）
    mulch/                        mulch 客户端（程序化 API + CLI 包装）
    e2e/                          端到端生命周期测试
  agents/                         基础代理定义（.md，9 种角色）+ 技能定义
  templates/                      叠加层和钩子的模板

配置

网关提供商

将代理 API 调用路由到自定义网关端点（z.ai、OpenRouter、自托管代理）。在 .overstory/config.yaml 中配置提供商：

providers:
  anthropic:
    type: native
  zai:
    type: gateway
    baseUrl: https://api.z.ai/v1
    authTokenEnv: ZAI_API_KEY
  openrouter:
    type: gateway
    baseUrl: https://openrouter.ai/api/v1
    authTokenEnv: OPENROUTER_API_KEY
models:
  builder: zai/claude-sonnet-4-6
  scout: openrouter/openai/gpt-4o

工作原理： 模型引用使用 provider/model-id 格式。Overstory 将 ANTHROPIC_BASE_URL 设置为网关的 baseUrl，ANTHROPIC_AUTH_TOKEN 从 authTokenEnv 中指定的环境变量中获取，并将 ANTHROPIC_API_KEY="" 以防止直接调用 Anthropic API。代理接收到 "sonnet" 作为模型别名，而 Claude Code 的路由则通过环境变量进行。

环境变量说明：

• ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 在每个代理中是互斥的。
• 网关代理会获得 ANTHROPIC_API_KEY="" 和来自提供商配置的 ANTHROPIC_AUTH_TOKEN。
• 直接调用 Anthropic API（如合并解析器、看门狗分诊）仍需要在编排器环境中设置 ANTHROPIC_API_KEY。

验证： 运行 ov doctor --category providers 可检查可达性、认证令牌、模型-提供商引用以及工具使用兼容性。

ProviderConfig 字段：

字段	类型	必需	描述
type	native 或 gateway	是	提供商类型
baseUrl	字符串	仅网关	API 端点 URL
authTokenEnv	字符串	仅网关	存储认证令牌的环境变量名称

故障排除

协调器在启动过程中退出

此错误表示协调器 tmux 会话在 TUI 准备就绪之前就已退出。最常见的原因是 shell 初始化过慢。

步骤 1：测量 shell 启动时间

time zsh -i -c exit   # 对于 zsh
time bash -i -c exit  # 对于 bash

如果启动时间超过 1 秒，很可能是 shell 初始化过慢导致的。

步骤 2：常见的启动缓慢原因

原因	典型延迟	解决方法
oh-my-zsh 搭配大量插件	1–5秒	减少插件数量，改用更轻量级的框架（如 zinit 并启用懒加载）
nvm（Node 版本管理器）	1–3秒	使用 --no-use 并懒加载 nvm，或切换到 fnm/volta
pyenv init	0.5–2秒	懒加载 pyenv
rbenv init	0.5–1秒	懒加载 rbenv
starship 提示符	0.5–1秒	检查 starship 的耗时情况
conda 自动激活	1–3秒	在 .condarc 中设置 auto_activate_base: false
Homebrew shellenv	0.5–1秒	缓存输出结果，而非每次启动 shell 时都重新计算

步骤 3：配置 .overstory/config.yaml 中的 shellInitDelayMs：

runtime:
  shellInitDelayMs: 3000

• 默认值：0（无延迟）
• 常用值：根据 shell 启动时间，通常为 1000–5000
• 如果设置超过 30000（30秒），将触发警告
• 该设置会在 tmux 会话创建与 TUI 准备就绪轮询之间插入一段延迟

步骤 4：优化示例

懒加载 nvm（添加到 ~/.zshrc 或 ~/.bashrc）：

# 懒加载 nvm — 只有首次调用 nvm/node/npm 时才会激活
export NVM_DIR="$HOME/.nvm"
nvm() { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; nvm "$@"; }
node() { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; node "$@"; }
npm()  { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; npm  "$@"; }
npx()  { unset -f nvm node npm npx; [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"; npx  "$@"; }

减少 oh-my-zsh 插件（编辑 ~/.zshrc）：

# 修改前：plugins=(git zsh-autosuggestions zsh-syntax-highlighting node npm python ruby rbenv pyenv ...)
# 修改后：仅保留经常使用的插件
plugins=(git)

os-eco 的一部分

Overstory 是 os-eco AI 代理工具生态系统的一部分。

贡献说明

欢迎贡献！请参阅 CONTRIBUTING.md 获取相关指南。

许可证

MIT

Overstory 快速上手指南

Overstory 是一个用于 AI 编码代理的多智能体编排工具。它通过 tmux 在 Git worktree 中生成工作代理，利用自定义 SQLite 邮件系统进行协调，并将结果合并回主分支。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：支持 Linux 或 macOS（依赖 tmux 和 git）。
• 核心依赖：
  • Bun v1.0+ (运行时环境)
  • git (版本控制)
  • tmux (终端复用，用于隔离代理会话)
• AI 代理运行时：必须至少安装并配置好以下任一支持的 AI CLI 工具：
  • Claude Code (claude)
  • GitHub Copilot (copilot)
  • Cursor (agent)
  • Aider (aider)
  • Gemini CLI (gemini)
  • 或其他支持的工具 (Pi, Codex, Sapling, OpenCode, Goose, Amp)

注意：多智能体协作会带来成本增加、错误累积和合并冲突等风险。在生产环境使用前，请务必评估相关风险。

安装步骤

推荐使用 Bun 进行全局安装：

bun install -g @os-eco/overstory-cli

如果您不想全局安装，也可以直接使用 npx 运行：

npx @os-eco/overstory-cli --help

开发模式安装（可选）

如果您需要贡献代码或测试最新功能：

git clone https://github.com/jayminwest/overstory.git
cd overstory
bun install
bun link              # 使 'ov' 命令全局可用

基本使用

以下是启动 Overstory 并运行第一个多智能体任务的最简流程：

1. 初始化项目

进入您的代码项目目录并初始化 Overstory：

cd your-project
ov init

2. 安装钩子（推荐）

将编排钩子安装到 .claude/settings.local.json 中，以便更好地集成：

ov hooks install

3. 启动协调器

启动一个持久的协调器代理（Coordinator），它负责任务分解和调度：

ov coordinator start

提示：添加 --attach 参数可前台运行并查看实时日志。

4. 分发任务给工作代理

使用 sling 命令生成具体的工作代理（如构建者、审查者等）来执行任务：

# 示例：创建一个名为 my-builder 的代理来处理特定任务
ov sling <task-id> --capability builder --name my-builder

注：<task-id> 可以是具体的任务描述或 ID。

5. 监控与合并

• 查看状态：实时监控所有代理的状态和工作树。

  ov status
  # 或使用交互式仪表盘
  ov dashboard
  

• 合并代码：当代理完成任务后，将它们的分支合并回主分支（包含冲突解决机制）。

  ov merge
  

常用辅助命令

• 检查消息：查看代理间的通信邮件。

  ov mail check --inject
  

• 提醒卡住的代理：如果某个代理停滞不前，发送提醒。

  ov nudge <agent-name>
  

• 清理环境：清理已完成的工作树和会话。

  ov clean