Overstory

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

Overstory 通过在 tmux 的 git 工作树（worktree）中生成工作智能体，利用自定义的 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  --capability builder --name my-builder

# 查看智能体状态
ov status

# 实时监控集群的仪表盘
ov dashboard

# 催促卡顿的智能体
ov nudge 

# 查看来自智能体的邮件
ov mail check --inject

命令

所有标注支持 --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, --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	终止正在运行的智能体（支持 --clean-worktree, --json）
ov prime	为编排器/智能体加载上下文（支持 --agent, --compact）
ov spec write	编写任务规范（支持 --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	评估退出触发器，返回完成状态