内容
<div align="center">
# Agenhood
### 自主托管的 AI 代理舰队基础设施
一次配置多个自主 AI 代理，然后分配、调度并链接它们 — 每个代理都运行在其独立的强化 Docker 容器中，拥有持久的工作空间、互联网访问权限和可插拔的“大脑”。通过精致的 Web 控制台或干净的 REST API 实时查看每条操作流。<br>**您拥有代理、数据和整个技术栈。**
[](LICENSE)
[](https://github.com/appssemble/agenhood/actions/workflows/ci.yml)
[](https://www.python.org/)
[](https://fastapi.tiangolo.com/)
[](https://react.dev/)
[](https://www.docker.com/)
[](#contributing)
</div>
<!-- 添加一个英雄截图或GIF到实时任务查看器/舰队网格： -->
<p align="center"><img src="docs/assets/hero.png" alt="Agenhood Fleet Console — live agent task viewer" width="820"></p>
---
## 为什么选择Agenhood？
聊天助手会忘记。代理CLI是临时性的。两者都无法在您控制的基础设施上无人值守运行。
Agenhood 介于 **聊天助手** （ChatGPT、Claude）和 **开发代理CLI** （Codex、opencode、Claude Code）之间，为它们提供了一个操作家园：一个持久的、多租户的、可观察的 **舰队** ，由 AI 代理组成，运行在 **您的** 服务器上。
- **长期运行，非临时** — 代理在重启、暂停和数周的空闲期间保持可写的 工作空间卷。文件、内存和历史记录持续存在。
- **默认隔离** — 每个代理都在其自己的强化容器中运行：只读根文件系统、删除的 Linux 功能、出口过滤（阻止私有范围和云元数据端点）和 CPU/内存限制。失控的代理无法损害主机或您的其他代理。
- **可插拔的大脑（驱动程序）** — 一个相同的 API，可互换的执行引擎。 为每个代理选择合适的大脑。
- **自主托管，您拥有** — 单个 VM 部署，您的密钥，您的数据。 无供应商锁定，无按席位 SaaS 税，无数据离开您的技术栈。
- **为人类和机器构建** — 控制台中的所有内容都是一个一级的 REST API + Server-Sent-Events 流。 控制台只是该 API 的一个客户端。
- **通用** — 研究、草稿、网页自动化、文档生成、数据处理 — 不仅仅是代码差异。
## 目录
- [功能](#功能)
- [架构](#架构)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [使用API](#使用API)
- [运行Agenhood：开发 vs 生产](#运行Agenhood：开发-vs-生产)
- [代码开发](#代码开发)
- [项目布局](#项目布局)
- [贡献](#贡献)
- [安全](#安全)
- [许可证](#许可证)
## 功能
### 🛰️ 代理舰队
从 **模板** 或从头开始在几秒钟内配置代理。 实时舰队网格显示每个代理及其状态、驱动程序、模型和最后活动。 清晰的生命周期状态 — `running`、`paused`、`archived`、`error` — 以及暂停（可选取消进行中的工作）、恢复、存档、恢复、恢复和删除的操作。 **空闲代理自动暂停** 以节省资源，并在下一个任务时 **自动唤醒**。
### 🧠 可插拔驱动程序 — 可互换的大脑
一个相同的 API，多个执行引擎，通过驱动程序注册表为每个代理热插拔：
| 驱动程序 | 它是什么 |
| --- | --- |
| **Vanilla** | 一个内置的工具使用循环，您可以完全控制 — 选择工具，编写系统，调整迭代/令牌预算。 |
| **Opencode** | 一个嵌入式编码工具包，管理其自己的工具和上下文。 |
| **Codex** | OpenAI 的 Codex 代理，支持技能。 |
| **Claude Code** | Anthropic 的代理，通过 `claude -p`，包括订阅 OAuth（“连接 Claude Code”）。 |
新的大脑可以直接集成，无需更改公共 API。
### 📡 任务 — 提交、流式传输、观察
通过干净的表单或流式聊天线程提交任务。 输出合约可以是自由文本或 **模式验证的 JSON** 。 **实时任务查看器** 通过 Server-Sent Events 流式传输代理的助手消息、工具调用、工具结果和文件更改 — 带有实时令牌表、迭代计数、经过的时间计时器和飞行中的取消。 重新连接会从停止的地方继续。
### 🔁 工作流和 ⏰ 调度
将任务链接成有序的 **工作流** ，跨一个或多个代理，带有可视化管道视图和每个运行的成功指标。 **调度** 提示或整个工作流，按类似 cron 的节奏（一次性或重复，时区感知），并在日历上查看即将到来的任务。
### 💾 持久工作空间、快照和 Git 备份
每个代理都拥有一个在重启、暂停和存档期间存活的 `/workspace` 卷 — 从控制台浏览、上传和下载文件。 **自动快照** 在每个任务后为您提供一个恢复点时间线，具有非破坏性回滚，以及可选的 **Git 备份远程** （SSH 部署密钥，在完成后推送）。
### 🧩 工具、技能和 MCP
Vanilla 驱动程序附带一个工具调色板：读取/写入/编辑/列出文件，运行 **bash** 和 **Python** ， **网络搜索** （默认情况下为自托管 [SearXNG](https://github.com/searxng/searxng) ）和 **网络获取** （文本或无头 Chromium 渲染）。 使用可重用的 **技能** （内联或从 Git 仓库获取）和 **[Model Context Protocol](https://modelcontextprotocol.io) (MCP)** 服务器扩展代理。
### 🏢 多租户工作空间
从一开始就是多租户的。 每个资源都限定在工作空间中；用户可以属于多个工作空间，并通过标头选择器切换。 按工作空间角色：**所有者 / 管理员 / 成员**。
### 🔐 凭证和安全
LLM 提供商密钥存储在服务器端，**加密（AES-GCM）且从不发送到浏览器** — UI 仅显示提供商 + 最后 4 位。 用于 Claude / ChatGPT 订阅的 OAuth 连接流（粘贴代码 PKCE）。 命名、可撤销的 **API 密钥** ，具有一次性密钥公开。
### 📊 仪表板、浏览器内 Shell 和命令调色板
使用仪表板（令牌、任务、成功率、趋势）、**浏览器内终端** （进入正在运行的代理的 xterm，基于 WebSocket）、**⌘K 命令调色板** 和实时 API 活动面板进行调试。
## 架构
Agenhood 是一个小型单体仓库，包含围绕共享核心库的独立部署服务。 代理是 **运行时配置的 Docker 容器** ，而不是 compose 服务 — 控制平面按需创建和驱动它们。
```mermaid
flowchart TB
U[Web 控制台 · React SPA] -->|REST + SSE + WebSocket| CP
API[您的代码 · REST API] -->|/v1| CP
subgraph Host["单个 Docker 主机"]
CP[控制平面 · FastAPI] --> PG[(Postgres)]
CP -->|Docker SDK: 配置 / 驱动| A1
CP --> CN[连接器 · GitHub / Slack]
subgraph internal["agent-runtime-internal （无网关）"]
A1[代理容器 · shim + 驱动程序] -->|仅出站路径| EP
EP[Egress 代理] --> SX[SearXNG]
end
end
EP -->|过滤出站| NET([Internet / LLM APIs])
```
- **`agentcore`** — 共享 Python 库：代理/任务模型、驱动程序和工具接口、提供商无关的 LLM 客户端、事件模式和沙盒限制。
- **Shim** — 每个代理容器中的 PID-1。 运行选定的驱动程序、执行工具并将事件流回控制平面。
- **控制平面** — 无状态 FastAPI 服务。 拥有公共 API、身份验证主体（租户 API 密钥、用户/工作人员会话）、持久化到 Postgres、驱动 Docker 守护进程以配置容器并代理/流式传输事件。
- **连接器** — 独立的 GitHub/Slack 服务，拥有自己的数据库和 OAuth。
- **Web 控制台** — React + TypeScript + Vite SPA；纯粹的控制平面 API 客户端。
- **出口代理 + SearXNG** — 单个、过滤的出站路径；代理附加到一个内部网络，**没有网关** ，因此代理只能通过它路由。
## 技术栈
**后端：** Python 3.12 · FastAPI · Pydantic · httpx · Postgres · Alembic · Docker SDK
**前端：** React 18 · TypeScript · Vite · TanStack Query · Tailwind · xterm.js
**基础设施：** Docker & Docker Compose（不需要 Kubernetes）· SearXNG · Traefik · 可选 [Coolify](https://coolify.io) 部署
**工具：** ruff · mypy（严格）· pytest · Vitest · Playwright
## 快速开始
**前提条件：** Docker（启用守护进程）和 Python 3.12+。
```bash
git clone https://github.com/appssemble/agenhood.git
cd agenhood
make dev
```
`make dev` 是开箱即用的：它构建代理镜像，在 **开发模式** 下启动堆栈（热重载、不安全的本地默认值 — 无需配置），运行迁移、播种租户、创建登录并打印 URL。 有关实际部署，请参阅 [运行Agenhood：开发 vs 生产](#运行Agenhood：开发-vs-生产)。
```
控制台： http://localhost:5173
登录： admin@example.com / devpassword123 （您将在第一次登录时更改它）
API 密钥： tk_live_seedkey （种子租户，用于 API 使用）
```
在 **设置 → 凭证** 中添加 **Anthropic API 密钥** （或连接订阅），配置代理并交给它一个任务。 配置需要 **不到 5 秒** 。
```bash
make logs # 尾随开发日志
make stop # 停止开发，保持数据，删除悬挂的代理容器
```
## 使用API
控制台做的所有事情都可以通过 REST API + SSE — 控制台只是其中一个客户端。 创建一个任务并实时流式传输其事件：
```bash
# 向代理提交任务（API 中的代理是“容器”）
curl -X POST http://localhost:5173/v1/containers/$AGENT_ID/tasks \
-H "Authorization: Bearer tk_live_seedkey" \
-H "Content-Type: application/json" \
-d '{"prompt": "Summarize the latest release notes and save them to notes.md"}'
# 流式传输实时事件流（助手消息、工具调用、文件更改）
curl -N http://localhost:5173/v1/containers/$AGENT_ID/tasks/$TASK_ID/events \
-H "Authorization: Bearer tk_live_seedkey"
```
## 运行Agenhood：开发 vs 生产
两种模式都由单个 `make` 命令驱动，该命令包装 Docker Compose。 它们在加载的环境文件、启动的服务拓扑结构以及访问控制台的方式上有所不同。 **两种模式都自动构建代理镜像，并在第一次运行和应用数据库迁移为您。**
| | **开发** — `make dev` | **生产** — `make prod` |
|---|---|---|
| 用于 | 尝试并本地开发 | 您的实际部署 |
| 环境文件 | `deploy/.env.dev` — 已提交，不安全的默认设置， **无需填写** | `deploy/.env` — **您创建**，从 `.env.example` 中填写实际机密 |
| 控制台 | Vite 开发服务器，热重载 — <http://localhost:5173> | 构建的 SPA 背后是 Traefik，位于 `https://$PUBLIC_HOST` |
| TLS 和路由 | 无；纯 HTTP 在 localhost 上 | Traefik + Let's Encrypt；API 在同一个源上，位于 `/v1` 下 |
| 首次登录 | 自动播种租户 + 管理员登录 | 您配置它（管理员/工作人员 — 无公开注册） |
| 反向代理/连接器 | 未启动 | Traefik + `连接器` 包含 |
| 撰写文件 | `docker-compose.yml` + `docker-compose.dev.yml` | `docker-compose.yml` |
### 开发 (`make dev`)
最快的路径 — [快速开始](#快速开始) 运行的内容。
```bash
make dev # 首次运行：构建代理镜像、启动堆栈、播种登录、打印 URL
make logs # 尾随开发日志
make stop # 停止开发，保持数据，清理悬挂的代理容器
```
控制平面以 `--reload` 运行，控制台是一个热重载的 Vite 开发服务器，位于 <http://localhost:5173> （它代理 `/v1` 和 `/admin` 到控制平面）。 所有机密信息都来自已提交的 `deploy/.env.dev` — **仅适用于本地使用，不适用于生产**。 在运行任务之前，请在 **设置 → 凭证** 中添加 **Anthropic API 密钥** 。
### 生产 (`make prod`)
在 **单个 VM 上运行纯 Docker** — 无 Kubernetes，无编排程序。 完整的堆栈在 Traefik 后面启动（使用 Let's Encrypt 进行 TLS），位于您的公共主机上。
```bash
cp deploy/.env.example deploy/.env # 1. 创建您的环境文件
# 2. 填写实际机密 — 每个“change-me”都必须替换。 内联命令：CREDENTIAL_ENCRYPTION_KEY，
# CONNECTORS_MASTER_KEY, ADMIN_API_KEY, DATABASE_URL 密码，
# SEARXNG_SECRET, 和 PUBLIC_HOST（您的 DNS 名称）。
make prod # 3. 构建 + 启动完整堆栈
make smoke # 4. 可选：健康和出口烟雾检查
```
`make prod` 如果 `deploy/.env` 丢失或仍包含任何 `change-me` 占位符，则拒绝启动。 将您的域 DNS 指向 VM 并打开端口 **80/443** ，以便 Traefik 可以获取证书；然后控制台在 `https://$PUBLIC_HOST` 处提供服务，API 在同一个源上位于 `/v1` 下。 使用 `make prod-stop` 停止 — 数据保存在 `pgdata` 卷中。
> [!IMPORTANT]
> Agenhood 是为可信的自托管部署而构建的。 在公开之前，请根据您的威胁模型审查沙盒、出口和凭证设置。 帐户由管理员/工作人员配置 — 没有公开的自我注册。
**更多部署细节：** [`deploy/README.md`](deploy/README.md) 中的组合拓扑和验证步骤， [`deploy/COOLIFY.md`](deploy/COOLIFY.md) 中的托管 [Coolify](https://coolify.io) 路径， [`deploy/SIZING.md`](deploy/SIZING.md) 中的 VM 大小调整。 代理镜像以 **两个变体** 交付 — `full` （带有无头 Chromium，用于 JS 渲染的 Web 抓取）和 `slim` 。
## 代码开发
Agenhood 本身的设置，用于贡献 — 校验器、类型检查和测试。 这与 *运行* 应用程序（上面）是分开的；您只需要编辑源代码时才需要它。
```bash
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e "packages/agentcore[dev]"
ruff check . # 校验
mypy packages/agentcore/agentcore # 类型（严格）
pytest -m unit # 快速测试，无需 Docker
pytest -m integration # 需要 Docker 守护进程
```
对于前端：
```bash
cd web/console
npm install
npm run dev # 或：npm test / npm run typecheck / npm run lint / npm run build
```
> [!TIP]
> 此处的 `npm run dev` 运行控制台的 Vite 服务器独立运行。 要将其连接到实时后端，请使用 `make dev` （它针对整个开发堆栈运行相同的服务器）。
## 项目布局
```
packages/agentcore # 共享库：模型、驱动程序/工具/LLM 接口、事件、限制
services/shim # 容器内的 PID-1 代理 shim
services/control_plane # FastAPI 控制平面（公共 API、身份验证、配置）
services/connectors # 独立的 GitHub/Slack 连接器服务（自己的 DB）
web/console # React SPA（舰队控制台）
images/ # 代理 + 出口代理镜像构建上下文
deploy/ # Docker Compose 拓扑结构、生产和测试堆栈、Coolify 运行手册
```
## 贡献
欢迎贡献。 请：
1. 首先打开问题讨论实质性更改。
2. 保持检查绿色： `ruff check .` 、 `mypy packages/agentcore/agentcore` 、 `pytest -m unit` 和 web-console `typecheck` / `lint` / `test` 。
3. 为新行为添加测试并保持 PRs 集中。
## 安全
请 **不要** 为安全漏洞公开问题。 私请维护者（参见存储库的安全政策 / 联系方式）。 LLM 提供商密钥在存储时加密，并且永远不会暴露到浏览器；代理在强化沙盒中运行，并带有过滤的出口。
## 许可证
在 [MIT 许可证](LICENSE) 下发布。
---
<div align="center>
**关键词：** 自托管 AI 代理 · 自主代理基础设施 · 沙盒 AI 代理 · 多租户代理平台 · 长期 AI 代理 · Docker AI 代理 · LLM 代理运行时 · Claude Code · OpenAI Codex · opencode · MCP · FastAPI · 代理编排 · AI 代理舰队 · 自托管 LLM 自动化
</div>
