Overstory Integration — Overstory 集成

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

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

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

要求 Python 3.9+ overstory CLI 已安装并在 PATH 中（或设置 OVERSTORY_BIN） git（用于工作树管理） tmux（overstory 使用 tmux 进行代理会话） 无外部 Python 依赖项（仅 stdlib）

环境变量 变量 默认值 描述 OVERSTORY_BIN overstory overstory 二进制文件路径 OVERSTORY_WORKSPACE 当前目录 overstory 操作的工作区根目录

命令 初始化工作区 python3 scripts/overstory_wrapper.py init --workspace /path/to/project 启动代理 python3 scripts/overstory_wrapper.py sling --task-id TASK-42 --capability code --name builder-alice --description "实现 auth 模块" --worktree 检查状态 python3 scripts/overstory_wrapper.py status python3 scripts/overstory_wrapper.py status --agent builder-alice --verbose 检查代理转录 python3 scripts/overstory_wrapper.py inspect --agent builder-alice --lines 100 杀死代理 python3 scripts/overstory_wrapper.py kill --agent builder-alice 工作树管理 python3 scripts/overstory_wrapper.py list-worktrees python3 scripts/overstory_wrapper.py cleanup-worktree --agent builder-alice 代理生命周期 python3 scripts/agent_lifecycle.py spawn --task "修复登录 bug" --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 邮件桥接 python3 scripts/mail_bridge.py send --from orchestrator --to builder-alice --subject "优先级变化" --body "切换到 auth 模块" 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 "auth 设计" python3 scripts/mail_bridge.py reply --thread THREAD-ID --from builder-alice --body "完成第 1 阶段"

用法作为 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", "上下文", "这里是规格...")

数据库模式 agent_lifecycle.db (~/.nanobot/agent_lifecycle.db) 列 类型 描述 id INTEGER PRIMARY KEY 自增 agent_name TEXT UNIQUE 代理标识符 capability TEXT 代理能力（代码、研究等） status TEXT 已启动/运行/已完成/失败/终止 task TEXT 任务描述 result TEXT 最终输出（可为空） start_time REAL Unix 时间戳 end_time REAL Unix 时间戳（可为空） timeout INTEGER 最大运行时间（秒） mail.db (.overstory/mail.db) 列 类型 描述 id INTEGER PRIMARY KEY 自增 thread_id TEXT 线程标识符（可为空） from_agent TEXT 发送者代理名称 to_agent TEXT 接收者代理名称 subject TEXT 消息主题 body TEXT 消息体 priority TEXT 正常/高/紧急 read INTEGER 0=未读，1=已读 created_at REAL Unix 时间戳