TheBotCompany 入门：零人工干预的 AI 团队开发新范式

30 分钟上手｜三角色自主协作｜多 Provider 兜底｜从需求到 PR 全链路自动化

---

项目简介

TheBotCompany 是一个让你「真正放手」的 AI 开发团队平台。它的核心思路很直接：不再是你一个人和 AI 聊天写代码，而是组建一支由多个 AI Agent 组成的团队——有人负责规划，有人负责写代码，有人负责验证——它们自己讨论、自己分配任务、自己管理进度，你需要做的只是在它们遇到真正需要人工判断的问题时介入一下。

团队里有三个固定的管理角色：Athena 做战略规划，定义里程碑和周期预算；Ares 带队执行，把里程碑拆成具体任务分给工人 Agent；Apollo 负责验收，用高标准审视 Ares 的产出，不合格就打回去。整个循环不需要你盯着，Dashboard 会实时展示每个 Agent 在做什么、花了多少钱、遇到了什么问题。

---

目标读者画像

本文面向以下开发者：

• 有一定开发经验，想把重复性编码工作交给 AI Agent 团队，自己专注决策和架构
• 对 Multi-Agent 协作、自组织团队这些概念感兴趣，想找实战案例
• 已经在用单 Agent 辅助开发，但希望扩展到多 Agent 并行处理多个方向

如果你想要的是「装好就能完全躺平」的工具，需要先降低预期——TheBotCompany 能大幅减少人工介入，但不是完全不需要你。

---

核心依赖与环境

---

完整项目结构树

安装并启动后，~/.thebotcompany/ 目录下会生成以下结构：

~/.thebotcompany/
├── keys.json              # 加密存储的 API Keys
├── db.sqlite              # Issue tracker 数据库
├── config.yaml            # 全局配置
└── logs/                  # 运行日志

你的项目目录/
├── workers/               # 工人 Agent 技能定义
│   ├── leo.md             # Frontmatter: reports_to, role, model
│   └── maya.md
├── workspace/             # 各 Agent 的工作空间
│   ├── athena/note.md
│   ├── ares/note.md
│   └── leo/note.md
└── .tbc/                  # 项目级配置（项目创建时生成）

---

手把手安装步骤

第一步：安装 TheBotCompany

npm install -g thebotcompany

验证安装：

tbc --version

第二步：启动服务

tbc start

首次运行会依次要求你设置：

1. Dashboard 访问密码 — 用于保护写操作（暂停、恢复、修改配置）
2. 端口号 — 默认 3100，直接回车接受默认即可

? Set a password for dashboard write access: ********
? Port to run the dashboard (default 3100):

启动成功后，Dashboard 在 http://localhost:3100 可访问。默认是只读模式，登录后才可操作。

第三步：配置 API Key

打开 Dashboard（http://localhost:3100），点击右上角 Settings，在 Keys 面板添加你的 API Key。也可以通过环境变量在首次运行时自动检测：

# 在 .bashrc 或 .zshrc 里加上：
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

第四步：通过 Dashboard 创建项目

1. 打开 http://localhost:3100
2. 点击 New Project，填写：
   • Repository URL — 你的 GitHub Repo 地址（需要 gh 有权限）
   • Provider — 选择用哪个 LLM Provider
   • Model Tier — 各层级使用的模型（high/mid/low）
3. 点击 Create，控制权交给 Athena 开始工作

---

三角色协作架构详解

这是 TheBotCompany 最核心的设计，理解它就知道整个系统是怎么运转的。

三个固定管理角色

完整的 Cycle 循环

PLANNING 阶段（Athena）
  → Athena + 她的工人 Agent 运行
  → 调研、评估、头脑风暴
  → 定义里程碑 → 进入 IMPLEMENTATION

IMPLEMENTATION 阶段（Ares）
  → Ares + 他的工人 Agent 运行（最多 N 个 Cycle）
  → Ares 宣布完成 → 进入 VERIFICATION
  → 超过周期预算 → 打回 PLANNING 重新评估

VERIFICATION 阶段（Apollo）
  → Apollo + 他的工人 Agent 运行
  → Apollo 验收通过 → 进入下一个 PLANNING
  → Apollo 打回 → 返回 IMPLEMENTATION 修复

工人 Agent 是怎么工作的

Manager（Ares / Athena / Apollo）通过在 {project_dir}/workers/ 目录创建 .md 文件来「招聘」工人 Agent。每个文件有固定的 YAML frontmatter：

---
reports_to: ares          # 向谁汇报
role: Frontend Engineer   # 职责描述
model: mid                # 使用哪档模型
---

# Frontend Engineer

你是一名前端工程师，负责实现 UI 组件和交互逻辑。

Manager 给工人分配任务时，只分配一个任务一个周期——不允许一次塞五个任务进去。工人完成后，Manager 读取工作空间里的 note.md 了解上下文，然后决定下一步。

Agent 间的通信方式

Agent 之间不直接聊天，而是通过内置 Issue Tracker 协调：

• Ares 需要 Athena 的意见 → 在 Issue Tracker 里创建 Issue，指定给 Athena
• Worker 遇到问题 → 创建 Issue，Manager 会看到并处理
• 需要人工介入 → 创建 GitHub Issue，标题以 HUMAN: 开头，你登录 GitHub 处理

---

完整开发流程演示

Step 1：通过 Dashboard 创建项目

打开 Dashboard，点击 New Project：

Repository: https://github.com/your-username/your-repo
Provider: Anthropic
Model: claude-sonnet-4

项目创建后，Dashboard 上会出现这个项目的卡片，显示状态为 PLANNING，Athena 开始工作。

Step 2：观察 Athena 的规划过程

在 Dashboard 的 Agent Reports 面板，可以看到 Athena 的输出。她在做这些事情：

• 读取项目 README 和现有代码，了解现状
• 搜索相关技术方案和最佳实践
• 评估需求可行性
• 定义第一个里程碑及其预算（多少个 Cycle）

里程碑定义完成后，系统自动切换到 IMPLEMENTATION 阶段，Ares 上线。

Step 3：Ares 执行实现

Dashboard 状态切换到 IMPLEMENTATION，Ares 开始工作：

1. 招聘工人 — Ares 创建 workers/leo.md、workers/maya.md 等文件
2. 分配任务 — 每个 Cycle 只给一个工人分配一个具体任务
3. 审查 PR — 工人提交 PR 后，Ares 做 Code Review
4. Cycle 控制 — 如果一个 Cycle 内没完成，打回来下个 Cycle 再试

你可以在 Dashboard 的 Chat 面板直接给 Ares 发消息，调整方向或补充上下文。

Step 4：Apollo 验收

当 Ares 宣布里程碑完成，系统切换到 VERIFICATION，Apollo 上线：

→ Apollo 阅读代码变更
→ 运行验证测试（通过 GitHub Actions）
→ 检查是否符合里程碑要求
→ 通过 → 进入下一个 PLANNING
→ 不通过 → 打回 IMPLEMENTATION，说明哪里不对

Apollo 的标准比 Ares 高一截，所以经常会有「Ares 觉得可以了但 Apollo 打回」的情况——这是正常设计，不是 Bug。

Step 5：人工介入（如果需要）

当 Agent 遇到真正需要人判断的事情，会创建 HUMAN: 开头的 GitHub Issue：

HUMAN: 登录页面用 OAuth 还是用户名密码？
请在 GitHub 上回复这个 Issue，Agent 会根据你的回复继续。

你回复后，Ares 会继续执行。如果觉得不需要介入，可以直接在 Dashboard 上暂停项目。

---

Dashboard 功能详解

TheBotCompany 的 Dashboard 是整个系统的控制中心，所有状态一览无遗。

项目总览

Dashboard 首页展示所有项目卡片，每个卡片显示：

• 当前阶段（PLANNING / IMPLEMENTATION / VERIFICATION）
• 当前 Cycle / Epoch 计数
• 里程碑进度条
• 最后一个 Agent Report 的摘要

Agent Reports

每个项目的 Agent 输出历史，支持 Markdown 渲染和自动摘要。如果某个 Cycle 的输出特别长，Dashboard 会自动压缩，只展示关键结论。

Issue Tracker

Agent 之间的协调全在这里：

• 按项目筛选
• 按状态（Open / In Progress / Resolved）
• 按 Agent 筛选
• 专属 Human Issues 面板，列出所有需要你处理的升级请求

Chat

Dashboard 内置的直接对话入口，可以选择任意项目，向对应的 Manager 发消息，补充上下文或调整方向。支持流式响应和图片上传。

Cost Tracking

每个项目、每个 Agent 的费用明细：

• Last Cycle 费用
• 24 小时平均费用
• 累计总费用

配合 Budget Controls，可以设置 24 小时滚动预算上限，超出后 Agent 自动进入休眠。

Controls

Dashboard 上的快捷控制按钮：

• Pause / Resume — 暂停和恢复项目（需要登录）
• Skip Sleep — 跳过预设的休眠间隔，立即开始下一个 Cycle
• Kill Run / Cycle / Epoch — 强制终止当前运行
• Bootstrap — 从指定里程碑重新启动

---

多 Provider 与 Key Pool 管理

支持的 Provider 列表

TheBotCompany 内置支持 15+ 种 LLM Provider：

Key Pool 的工作方式

在 Settings 的 Keys 面板，可以为同一个 Provider 添加多个 Key，并设置优先级顺序。运行时：

1. 系统优先使用优先级最高的 Key
2. 该 Key 触发速率限制（429）或配额不足 → 自动切换到下一个 Key
3. 冷却时间结束后，Key 恢复可用，重新加入轮换

这对于需要长时间运行的项目特别有用，不用担心单个 Key 耗尽导致整个 Agent 团队停摆。

Model Tier 配置

每个项目可以自定义各层级使用的模型：

# 项目级 .tbc/config.yaml
model_tiers:
  high: claude-opus-4       # 复杂架构、深度推理
  mid: claude-sonnet-4      # 默认，平衡能力与成本
  low: claude-haiku-3       # 简单重复任务、格式化

也可以在 Settings 的 Model Tier Overrides 面板直接通过 UI 修改，不需要动配置文件。

---

常见问题排查

Q1：tbc start 启动后 Dashboard 打不开，显示 Connection Refused

原因：端口被占用，或服务没有正常启动。

排查步骤：

# 1. 检查 tbc 是否在运行
tbc status

# 2. 如果没在运行，手动启动并看错误输出
tbc dev

# 3. 如果端口被占用，指定另一个端口
TBC_PORT=3200 tbc start

---

Q2：Agent 团队一直停在 PLANNING 阶段，没有进入 IMPLEMENTATION

原因：Athena 在做深度调研或等待工人 Agent 的结果，还没定义出里程碑。

解决方法：

打开 Dashboard → Agent Reports，查看 Athena 的最新输出。如果她在等待某个工人的调研结果，可以用 /tbc logs 查看服务器日志确认是否卡住。如果确实卡住了，直接在 Dashboard 的 Chat 面板向 Athena 发消息：「请基于现有信息定义第一个里程碑，不需要等待更多调研。」

---

Q3：GitHub PR 没有自动创建，Agent 在 Issue Tracker 里报了权限错误

原因：gh CLI 没有正确认证，或者 Token 权限不足。

排查步骤：

# 1. 检查 gh 登录状态
gh auth status

# 2. 如果没登录，重新认证（需要 repo 权限）
gh auth login --scopes repo

# 3. 确认项目目录的 remote URL 正确
cd /path/to/your-project
git remote -v

---

Q4：Apollo 一直打回 Ares 的实现，导致 Cycle 死循环

原因：Ares 每次修复的方向和 Apollo 期望的不一致，或者里程碑的定义本身不够清晰。

解决方法：

在 Dashboard 的 Chat 面板向 Ares 发送：「Apollo 的打回理由是 [粘贴 Apollo Report 里的具体意见]。请在修复前先明确理解 Apollo 的标准，和 Apollo 确认修复方向再动手。」

如果 Apollo 的标准过于苛刻，可以在 PLANNING 阶段让 Athena 调整里程碑的验收条件。

---

Q5：费用远超预期，想立即暂停所有 Agent

解决方法：

# 方法一：Dashboard 操作
# 登录 Dashboard → 每个项目卡片 → Controls → Pause

# 方法二：CLI 暂停
tbc stop

# 方法三：设置预算上限（下次启动生效）
# 在 Dashboard Settings → Budget Controls，设置 24h 预算上限

---

Q6：添加了多个 API Key，但 Agent 一直用同一个 Key 导致超限

原因：Key Pool 的优先级顺序可能不对，或者 Key 的速率限制冷却还没结束。

解决方法：

在 Dashboard Settings → Keys 面板，检查各 Key 的状态：

• Active — 正常使用中
• Cooldown — 触发限速，正在冷却
• Exhausted — 配额用尽

如果某个 Key 长时间处于 Cooldown，手动将它移到 Key 列表底部，让系统切换到下一个 Key。

---

扩展阅读与进阶方向

1. 自定义工人 Agent 技能

在 workers/ 目录下创建新的 .md 文件来扩展团队能力：

---
reports_to: ares
role: DevOps Engineer
model: mid
---

# DevOps Engineer

你是一名 DevOps 工程师，精通 CI/CD 流水线、容器化和基础设施即代码。

Manager 会自动发现新添加的工人 Agent，下一个 Cycle 开始时就可以调度它们。

2. 自定义 Provider 接入

如果需要接入公司内部的 LLM 服务（OpenAI 或 Anthropic 兼容格式），在 Settings → Keys → Add Custom Provider：

{
  "name": "my-internal-llm",
  "baseUrl": "https://llm.internal.company.com/v1",
  "apiKey": "sk-internal-...",
  "model": "gpt-4"
}

3. 与 GitHub Actions 深度集成

TheBotCompany 的 Agent 设计鼓励把耗时的测试和构建放到 GitHub Actions 里跑。在工人 Agent 的技能文件里指定：

永远不要直接在终端运行超过 5 分钟的测试。所有测试套件通过 GitHub Actions 触发。

这样 Agent 在 Cycle 超时被 kill 时，已经提交的代码和 CI 结果不会丢失。

4. 多项目管理与总览

如果你同时在跑多个项目（开源维护、Side Project、商业项目），TheBotCompany 的统一 Dashboard 让你在一个页面里看到所有项目的状态、花费和问题分布。用顶层的 Project Filters 快速切换，Human Issues 面板集中处理所有升级请求，不遗漏任何需要你决策的地方。

5. 预算与成本的精细化控制

默认的 24 小时滚动预算上限是全局的。如果想对不同项目设置不同预算，可以运行多个 TheBotCompany 实例（不同 TBC_HOME 目录），每个实例独立管理一组项目和预算，互不干扰。