# AgentHive

**Repository Path**: agent_26/agent-hive

## Basic Information

- **Project Name**: AgentHive
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-13
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AgentHive

开源的 Managed Agents 平台。将编码 Agent 变成真正的队友——分配任务、跟踪进度、积累技能。

## 技术栈

- **前端**：Next.js 16（React 19）、TypeScript、Tailwind CSS 4、TanStack Query、Zustand —— pnpm monorepo，用 Turborepo 管理
- **后端**：Go 1.26、chi 路由、PostgreSQL
- **包管理器**：pnpm（workspaces：`apps/*`、`packages/*`）
- **E2E 测试**：Playwright
- **单元测试**：Vitest（TS）、`go test`（Go）

## 快速开始

> 以下命令均在**项目根目录**（本文件所在目录）下执行，不要在 `server/` 等子目录下执行。

> **前置条件（macOS）**：需要 Docker 可用。如果没有 Docker Desktop，用 [Colima](https://github.com/abiosoft/colima) 时先执行 `colima start` 启动虚拟机，再运行下面的命令；否则会报 `dial unix .../docker.sock: connect: no such file or directory`。

```bash
# 1. 复制环境变量配置
cp .env.example .env

# 2. 一键启动：安装依赖、确保 Postgres 运行、执行迁移、启动前后端
make dev
```

前端：http://localhost:3000
后端：http://localhost:8080

## 常用命令

```bash
make setup     # 安装依赖 + 确保数据库存在 + 执行迁移（不启动服务）
make start     # 启动前后端（假设已执行过 setup）
make stop      # 停止前后端进程
make check     # 运行 typecheck、TS 测试、Go 测试和 Playwright E2E
make server    # 只运行 Go 后端
make cli       # 从源码运行 agenthive CLI

pnpm dev:web       # 只启动前端（通过 Turborepo）
pnpm build         # 构建所有 apps/packages
pnpm test          # 运行 TS 测试套件
pnpm typecheck     # 对所有 workspace 做类型检查
```

## 自部署（Docker）

```bash
make selfhost        # 拉取官方镜像并通过 Docker Compose 启动
make selfhost-build   # 从源码构建镜像，而不是拉取
make selfhost-stop    # 停止自部署的服务栈
```

详见 [SELF_HOSTING.md](SELF_HOSTING.md)。

## 手动执行的后端/数据库命令

```bash
cd server && go run ./cmd/migrate up     # 执行数据库迁移
cd server && go run ./cmd/server         # 直接运行后端服务
cd server && go test ./...               # 运行 Go 测试
```

## 常见问题（启动排查）

按报错关键字对号入座：

### 1. `No rule to make target 'dev'` / `cp: .env.example: No such file or directory`

命令执行目录不对。`make dev`、`cp .env.example .env` 等命令必须在**项目根目录**（本文件所在目录）执行，不能在 `server/` 等子目录下执行——子目录里没有 `Makefile` 和 `.env.example`。

```bash
cd <项目根目录>   # 例如 /path/to/AgentHive
cp .env.example .env
make dev
```

### 2. `dial unix .../docker.sock: connect: no such file or directory`

Docker daemon 没有运行。`make dev` 需要 Docker 来启动 PostgreSQL 容器。

- 用 Docker Desktop：启动 Docker Desktop 应用。
- 用 [Colima](https://github.com/abiosoft/colima)（macOS 常见）：先执行 `colima start`，再重跑 `make dev`。

### 3. `failed SASL auth: FATAL: password authentication failed for user "agenthive"`

PostgreSQL 数据卷里持久化的密码与 `.env` 中的 `POSTGRES_PASSWORD` 不一致。`POSTGRES_PASSWORD` 只在数据卷**首次初始化**时生效，之后改 `.env` 不会自动同步到已存在的数据库。

两种解决办法，任选其一：

```bash
# 办法 A：重置数据库用户密码，使其与 .env 一致（保留现有数据）
docker exec agenthive-postgres-1 sh -c \
  "PGPASSWORD=<数据库当前密码> psql -U agenthive -d agenthive -h 127.0.0.1 \
   -c \"ALTER USER agenthive WITH PASSWORD 'agenthive';\""

# 办法 B：清空并重建数据库卷（会丢失本地数据库数据）
docker compose down -v && make dev
```

### 4. `address already in use` / `EADDRINUSE`（端口 8080 或 3000 被占用）

端口被其他进程占用，常见于以下两种情况：

- **Docker 自部署容器还在跑**：`make dev`（本机直跑模式）与 Docker 容器模式互斥，不能同时用。先停掉容器：
  ```bash
  docker stop agenthive-backend-1 agenthive-frontend-1
  ```
- **上一次 `make dev` 的残留进程没退干净**：找到并结束占用端口的进程：
  ```bash
  lsof -nP -iTCP:8080 -sTCP:LISTEN   # 查后端端口占用
  lsof -nP -iTCP:3000 -sTCP:LISTEN   # 查前端端口占用
  kill <PID>                          # 结束对应进程
  ```

### 运行模式说明

- **本机直跑（开发调试用）**：`make dev` / `make start`，直接跑源码，改代码即时生效。
- **Docker 自部署**：`make selfhost`，跑容器镜像。

两种模式都会占用 8080/3000 端口，同一时间只能用一种。切换模式前先停掉另一种模式的进程/容器。