AI Collaboration System / 智能协作系统

面向 Codex / Claude / Gemini 的终端多 Agent 协作编排框架。

本框架将真实开发流程中的规划、实现、审查与交付环节拆分至不同模型，并提供可观测、可回放、可降级的协作机制。

English Documentation

核心特性

1. 主控优先：先规划再执行，避免单 Agent 盲目推进
2. 配置驱动：模型与角色通过配置文件管理，无硬编码依赖
3. 双执行后端：direct 适合当前终端顺序执行，tmux 适合可视化协作、日志记录与会话回放
4. 故障可控：针对命令不可用、权限受限、子 Agent 失败等场景提供显式降级策略

统一命令接口

项目采用单一命令入口：ai-collab

• 执行任务：ai-collab "<task>"
• 管理操作：ai-collab <subcommand>（如 init、status、config）

查看完整执行参数：

ai-collab run --help

安装方式

从源码安装

git clone https://github.com/skyhua0224/ai-collab.git
cd ai-collab
python3 -m pip install -e .

从 PyPI 安装

pip install ai-collab

快速开始

1. 初始化配置

ai-collab init
ai-collab status

2. 执行协作任务

ai-collab "设计并实现一个带鉴权的 REST API，并给出测试与发布建议"

说明：默认 direct 语义是“单终端执行后端”。

• 单 Agent 计划：直接由当前 Agent 在当前终端执行
• 多 Agent 计划：仍在当前终端执行，但按 workflow 阶段顺序调用不同 Agent，不创建 tmux pane

3. 启用 tmux 可视化协作

ai-collab detect "实现一个包含前端与后端的最小业务功能，并完成审查" --output json

ai-collab \
  --provider codex \
  --execution-mode tmux \
  --tmux-target inline \
  --tmux-prewarm-subagents \
  "实现一个包含前端与后端的最小业务功能，并完成审查"

说明：tmux 只用于“可执行的多 Agent 可视化编排”。 如果计划编辑后变成单 Agent，或所有步骤都落到同一个 Agent，执行目标页会禁用 tmux；这时仍可继续使用“直接执行”在当前终端运行。

常用子命令

命令	功能说明
ai-collab init	初始化配置文件模板
ai-collab status	查看当前配置与 Agent 可用性状态
ai-collab detect	检测协作需求并生成编排建议
ai-collab monitor	手动启动 tmux 协作工作区
ai-collab config	管理配置项
ai-collab select	根据任务复杂度选择模型策略

可观测性与故障排查

日志目录结构

.ai-collab/logs/<session>/

常用排查命令

# 实时查看日志
tail -f .ai-collab/logs/<session>/*.log

# 检测任务编排建议（JSON 格式）
ai-collab detect "<task>" --output json

# 模拟执行（不实际运行）
ai-collab --dry-run --output json "<task>"

文档导航

• 快速开始指南
• 详细使用文档
• vNext Rust 平台架构基准
• 版本发布流程

开发与验证

# 运行测试
pytest -q

# 构建分发包
python3 -m build

# 验证分发包
python3 -m twine check dist/*

联系方式

• 📧 Email: dev@sky-hua.xyz
• 💬 Telegram: @skyhua
• 🐧 QQ: 2110591491
• 🔗 GitHub Issues: 提交 Issue

开源协议

MIT License