Overstory

面向 AI 编码智能体的多智能体编排系统。

本项目已停止维护。 Overstory 不再进行主动维护，该代码仓库已归档（只读状态） —— 我不再审核 issue 或合并 pull request。感谢所有做出贡献的朋友。代码保持 MIT 开源协议，欢迎分叉（fork）并继续推进。当前开发工作已迁移至 Warren，这是一个用于沙箱云智能体的自托管控制平面，也是 Overstory 的精神续作 —— 若有新需求，请从那里开始。

Overstory 通过在隔离的 git worktree 中生成工作智能体，利用自定义的 SQLite 邮件系统进行协调，并通过分级冲突解决机制合并工作成果，从而将单次编码会话转变为多智能体团队协作。新项目会以无头（headless）模式生成 Claude 智能体，并通过 Web UI (ov serve) 进行展示；tmux attach 是用于实时操控的备选方案。可插拔的 AgentRuntime 接口支持在 11 种不同的运行时之间切换 —— 包括 Claude Code、Pi、Gemini CLI、Aider、Goose、Amp 或你自定义的适配器。

警告：智能体集群并非万能方案。 在未了解多智能体编排风险的情况下，请勿部署 Overstory —— 复合错误率、成本放大、调试复杂性和合并冲突是常态，而非边缘情况。在生产环境使用此工具前，请务必阅读 STEELMAN.md 获取完整的风险分析，并参考 Agentic Engineering Book（网页版）。

安装

需要 Bun v1.0+ 和 git。tmux 是可选的 —— 仅当你希望通过 --no-headless 生成工作智能体或直接连接到协调器/工作智能体面板时才需要。此外，必须安装至少一个受支持的智能体运行时：

• 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

# 打开 Web UI —— 这是集群的主要操作界面
ov serve   # 然后访问 http://localhost:7321

ov serve 是你监控集群、阅读邮件总线以及检查每个智能体执行时间线的地方。新项目默认以无头模式生成 Claude 工作智能体，因此 UI 可以以高保真的结构化事件流展示它们。

其他常用命令：

# 生成单个工作智能体（协调器通常会自动完成此操作）
ov sling  --capability builder --name my-builder

# 当你需要在会话中途介入时，强制将智能体接入 tmux
ov sling  --capability builder --name my-builder --no-headless
tmux attach -t ov-my-builder

# 从 CLI 检查状态（在 UI 中也可见）
ov status
ov dashboard          # Web UI 的实时 TUI 替代方案
ov mail check --inject
ov nudge  # 向停滞的智能体发送跟进指令

命令

凡注明的地方，所有命令均支持 --json。全局标志：-q/--quiet、--timing、--project。ANSI 颜色遵循 NO_COLOR 标准。

核心工作流

命令	描述
ov init	初始化 .overstory/ 并引导 os-eco 工具 (--yes, --name, --tools, --skip-mulch, --skip-seeds, --skip-canopy, --skip-onboard, --json)
ov sling	生成一个工作智能体 (--capability, --name, -)