Overstory 是一款面向 AI 编程代理（AI coding agents）的开源多智能体编排 CLI 工具：它在隔离的 git worktree 中生成多个 worker 代理，通过自研的 SQLite 邮件系统协调通信，并用分级冲突解决机制自动合并成果。本手册把全部 38 个ov命令按 7 大功能域整理成速查清单，并给出新手上手的典型实战流程，5 分钟即可完成第一次多智能体编排。

1. 安装与 60 秒上手

Overstory 基于 Bun 运行时，支持 Claude Code、Pi、Gemini CLI、Aider、Goose、Amp 等 11 种可插拔运行时适配器（源码见 src/runtimes/）。

# 全局安装 bun install -g @os-eco/overstory-cli # 在项目目录初始化 .overstory/ 目录 cd your-project ov init # 安装 hooks 到 .claude/settings.local.json ov hooks install # 启动常驻协调器 ov coordinator start # 打开 Web UI（默认端口 7321） ov serve

💡新手提示：ov serve是主要的操作面板，可以看代理舰队（fleet）、读邮件总线、检查每个代理的时间线。嫌 Web 界面麻烦时，ov dashboard提供终端 TUI 替代方案。

2. 全局标志：所有命令通用的 5 个开关

全局标志定义在 CLI 入口 src/index.ts，所有命令都接受这些标志，且位置灵活（ov --project /path status与ov status --project /path等价）。终端配色遵循NO_COLOR环境变量。

3. 🚀 核心工作流命令（7 个）

日常使用频率最高的一组命令，覆盖"初始化 → 派工 → 停止 → 刷新"全生命周期：

sling是核心中的核心（实现见 src/commands/sling.ts）。实战示例：

# 派一个 builder 代理去做任务 T-12 ov sling T-12 --capability builder --name my-builder # 想要中途实时接管？强制 tmux 模式 ov sling T-12 --capability builder --name my-builder --no-headless tmux attach -t ov-my-builder

⚠️坑位提醒：如果代理中途意外退出且任务已关闭，nudge和sling都会拒绝重新介入。此时用--recover跳过可工作状态检查：ov sling T-12 --capability lead --recover --name fresh-lead。

4. 🎯 协调层命令：coordinator / orchestrator / supervisor

Overstory 采用分层架构：Orchestrator（跨多仓库）→Coordinator（单项目常驻编排器）→Lead/Worker（scout、builder、reviewer、merger）。各角色定义见 agents/ 目录。

实现细节可参考 src/commands/coordinator.ts 的头部注释——它清楚解释了 coordinator 与普通 sling 代理的三大区别：没有 worktree、不认领任务、跨工作批次持久存在。

5. 📬 消息与协作命令：mail / nudge / group

代理间通信走自研 SQLite 邮件系统（WAL 模式，单次查询约 1-5ms），支持 8 种类型化协议消息和@all、@builders等群发地址，源码在 src/mail/。

实战示例：

ov mail check --inject # 检查未读并注入给代理 ov nudge my-builder "请继续，T-12 还差测试用例" ov group create sprint-42 && ov group add sprint-42 T-12 T-13

6. 🔀 合并命令：merge

底层是 FIFO 合并队列（SQLite 存储）+ 四级冲突解决 + 哨兵文件锁，源码见 src/merge/。建议先--dry-run预检冲突，再正式合并：

ov merge --dry-run # 只查冲突不合并 ov merge --all # 合并队列中所有待处理分支

7. 🔍 可观测性命令（11 个）：看懂你的蜂群

排障三板斧：ov status看全局 →ov inspect <agent>钻单点 →ov replay --run <id>还原现场。成本超预算时用ov costs --live实时盯梢。

8. 🏗️ 基础设施命令（12 个）

ov doctor内置 13 个检查模块（依赖、配置、目录结构、数据库、合并队列、providers、watchdog 等），注册表见 src/commands/doctor.ts：

ov doctor # 全量体检 ov doctor --category providers # 只查 API 网关配置 ov doctor --fix # 自动修复可修复项

ov serve默认端口是 7321 而非 8080——因为 8080 容易与 Colima/Docker 等工具冲突，这个细节写在 src/commands/serve.ts。

9. 🏃 实战演练：一天典型工作流

把上面的命令串起来，一个完整的编排日大概长这样：

# 早上：体检 + 启动 ov doctor --fix ov coordinator start ov serve # 浏览器打开 http://localhost:7321 # 上午：派工（通常由 coordinator 自动完成，这里手动演示） ov spec write T-12 --body "实现登录模块单元测试" ov sling T-12 --capability builder --name auth-builder # 下午：盯盘 ov status ov feed --follow # 实时事件流 ov costs --live # 成本监控 ov nudge auth-builder "进度如何？" # 收尾：合并 + 清理 ov merge --dry-run && ov merge --all ov stop auth-builder --clean-worktree ov clean --completed

全部 38 个命令的实现都放在 src/commands/ 目录（一文件一命令），命令路由与模糊纠错逻辑（打错命令名会提示"Did you mean ..."）在 src/index.ts。

10. 📌 速查：30 秒找命令

Overstory 命令虽多，但 80% 的场景只需记住init、sling、status、mail、merge、doctor六个动词。配合ov completions生成 shell 补全后，多智能体编排会像git一样自然上手。

📚 延伸阅读：完整的风险说明请阅读仓库根目录的 STEELMAN.md（多智能体的错误率叠加、成本放大是常态而非例外），架构细节见 CLAUDE.md，技术设计文档在 docs/。