overstory 集成

描述

将 overstory 的 Claude Code 代理集群系统与 nanobot 编排器集成。提供代理生命周期管理、代理间 SQLite 邮件桥接以及用于并行代理工作流的 git 工作树协调。

架构

┌──────────────┐ ┌───────────────────┐
│ nanobot │──────▶│ overstory_wrapper │──▶ overstory CLI (tmux 会话)
│ 编排器 │ └───────────────────┘
│ │ ┌───────────────────┐
│ │──────▶│ agentlifecycle │──▶ SQLite (agentlifecycle.db)
│ │ └───────────────────┘
│ │ ┌───────────────────┐
│ │──────▶│ mail_bridge │──▶ SQLite (.overstory/mail.db)
└──────────────┘ └───────────────────┘

• - overstorywrapper.py — 围绕 overstory CLI 的轻量封装。通过 tmux 生成代理、管理工作树、安装钩子。
• agentlifecycle.py — 在本地 SQLite 数据库中跟踪代理状态（已生成 → 运行中 → 已完成/失败/已终止）。提供异步监控和清理功能。
• mail_bridge.py — 使用 overstory 原生 SQLite 邮件格式的线程安全消息桥接。支持直接消息、广播和线程化对话。

要求

• - Python 3.9+
• 已安装 overstory CLI 并配置在 PATH 中（或设置 OVERSTORY_BIN）
• git（用于工作树管理）
• tmux（overstory 使用 tmux 管理代理会话）
• 无外部 Python 依赖（仅使用标准库）

环境变量

命令

初始化工作空间

bash
python3 scripts/overstory_wrapper.py init --workspace /path/to/project

生成代理

bash
python3 scripts/overstory_wrapper.py sling \
--task-id TASK-42 \
--capability code \
--name builder-alice \
--description 实现认证模块 \
--worktree

检查状态

bash
python3 scripts/overstory_wrapper.py status
python3 scripts/overstory_wrapper.py status --agent builder-alice --verbose

查看代理记录

bash
python3 scripts/overstory_wrapper.py inspect --agent builder-alice --lines 100

终止代理

bash
python3 scripts/overstory_wrapper.py kill --agent builder-alice

工作树管理

bash
python3 scripts/overstory_wrapper.py list-worktrees
python3 scripts/overstory_wrapper.py cleanup-worktree --agent builder-alice

代理生命周期

bash
python3 scripts/agent_lifecycle.py spawn --task 修复登录错误 --capability code --name bug-fixer
python3 scripts/agent_lifecycle.py list-active --json
python3 scripts/agent_lifecycle.py wait --agent bug-fixer --timeout 1800
python3 scripts/agent_lifecycle.py cleanup --max-age 24

邮件桥接

bash
python3 scripts/mail_bridge.py send --from orchestrator --to builder-alice --subject 优先级变更 --body 切换到认证模块
python3 scripts/mail_bridge.py read --agent builder-alice --unread
python3 scripts/mail_bridge.py broadcast --from orchestrator --channel @all --message 停止工作
python3 scripts/mail_bridge.py create-thread --agents orchestrator,builder-alice --subject 认证设计
python3 scripts/mail_bridge.py reply --thread THREAD-ID --from builder-alice --body 第一阶段已完成

作为 Python 模块使用

python
from overstory_wrapper import OverstoryWrapper
from agent_lifecycle import AgentLifecycle
from mail_bridge import MailBridge

wrapper = OverstoryWrapper(/path/to/workspace)
wrapper.init()

lifecycle = AgentLifecycle()
agent = lifecycle.spawn_agent(task=构建 API, capability=code, name=api-builder)

bridge = MailBridge(/path/to/workspace)
bridge.send(orchestrator, api-builder, 上下文, 以下是规格说明...)

数据库模式

agentlifecycle.db (~/.nanobot/agentlifecycle.db)

mail.db (.overstory/mail.db)