# HIVE

**Repository Path**: delldeng/hive

## Basic Information

- **Project Name**: HIVE
- **Description**: 适用于所有CLI AI ide的Agent Swarm功能，实现多agent并行协作、讨论、点对点通讯，自我进化，顶级思维模型，IDE性能提升、token消耗优化、三层验证确保执行质量等功能。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-02-14
- **Last Updated**: 2026-03-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# HIVE Agent Teams

> 基于 MCP 的多 Agent 协作系统，可接入 Codex、Cursor、Claude Desktop、iflow 等 AI IDE。

HIVE Agent Teams 让你在 IDE 聊天界面里，用自然语言创建团队、分配任务、查看 Agent 进度，并把多 Agent 协作能力暴露为标准 MCP 工具。

## 项目定位

HIVE 不是一个单独的聊天应用，而是一个 MCP Server：

- 通过 `Model Context Protocol` 暴露多 Agent 工具
- 让支持 MCP 的 IDE 直接调用这些工具
- 适合把产品、架构、前端、后端、测试等角色组织成一个可调度的团队
- 支持从简单的团队创建，到通信记录、进度追踪、卡住检测等高级观测能力

## 核心能力

### 1. 多 Agent 团队协作

- 内置 10 种团队模板
- 支持创建、切换、销毁多个团队实例
- 可按角色分配任务给不同 Agent
- 支持查看单个 Agent 视角
- 支持验证并行工作、查看通信记录和进度状态

### 2. MCP 标准集成

- 基于 `@modelcontextprotocol/sdk`
- 通过 `stdio` 方式运行，兼容主流 MCP 客户端
- 适合接入 `Codex`、`Cursor`、`Claude Desktop`、`iflow`
- 支持按客户端选择不同工具暴露策略

### 3. 面向 Codex 的兼容模式

HIVE 现已内置 `Codex` 友好模式：

- 使用更短的服务器名
- 默认关闭启动横幅，减少 `stderr` 噪声
- 默认仅暴露 8 个核心工具，降低模型选错工具的概率
- 如有需要，可切回完整 17 个工具集

### 4. 知识与运行时观测

- 支持团队状态查询
- 支持 Agent 活动日志查看
- 支持团队通信记录与双 Agent 会话查看
- 支持团队进度、实时状态和卡住检测

## 环境要求

- `Node.js >= 20`
- `npm` 或兼容的包管理器
- 任意支持 MCP 的客户端

## 安装

### 方式一：全局安装

```bash
npm install -g hive-agent-teams
```

安装后会提供一个可执行命令：

```bash
hive-mcp
```

### 方式二：按需使用 `npx`

如果你希望在任何设备上都避免依赖本机全局路径，推荐直接使用：

```bash
npx -y hive-agent-teams
```

这也是本文档中推荐给 `Codex`、`Cursor`、`Claude Desktop` 等客户端的默认配置方式。

## 在 Codex 中使用

### 推荐命令

这是最适合跨设备迁移的接入方式：

```bash
codex mcp add hive -- npx -y hive-agent-teams --client codex
```

### 手动配置 `~/.codex/config.toml`

```toml
[mcp_servers.hive]
type = "stdio"
command = "npx"
args = ["-y", "hive-agent-teams", "--client", "codex"]
```

### 使用完整工具集

`Codex` 模式默认只暴露核心工具。如果你需要完整 17 个工具，可以改成：

```bash
codex mcp add hive -- npx -y hive-agent-teams --client codex --tool-profile full
```

或：

```toml
[mcp_servers.hive]
type = "stdio"
command = "npx"
args = ["-y", "hive-agent-teams", "--client", "codex", "--tool-profile", "full"]
```

更多说明见 `docs/adapters/codex-adapter.md`。

## 在其他 MCP 客户端中使用

### Cursor

配置文件：

- Windows: `%APPDATA%\Cursor\User\mcp.json`
- macOS / Linux: `~/.cursor/mcp.json`

推荐配置：

```json
{
  "mcpServers": {
    "hive": {
      "command": "npx",
      "args": ["-y", "hive-agent-teams"]
    }
  }
}
```

### Claude Desktop

配置文件：

- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

推荐配置：

```json
{
  "mcpServers": {
    "hive": {
      "command": "npx",
      "args": ["-y", "hive-agent-teams"]
    }
  }
}
```

### iflow

配置文件：

- Windows: `%APPDATA%\iflow\mcp.json`
- macOS / Linux: `~/.iflow/mcp.json`

推荐配置：

```json
{
  "mcpServers": {
    "hive": {
      "command": "npx",
      "args": ["-y", "hive-agent-teams"]
    }
  }
}
```

### 修改配置后

完成配置后，请重启对应客户端，让 MCP Server 重新加载。

## 使用方式

HIVE 的典型工作流很简单：

1. 创建一个团队
2. 把任务分配给某个角色
3. 查看团队状态或某个 Agent 的视角
4. 如有需要，再查看进度、通信和卡住状态

### 示例对话

```text
创建一个 fullstack 团队
让 backend-architect 设计用户认证 API
查看当前团队状态
查看 backend-architect 的工作视角
```

### 常见自然语言指令

```text
创建一个后端团队
创建一个前端团队
列出所有模板
列出当前所有团队
切换到 backend-team
销毁当前团队
```

```text
让 backend-dev 实现登录接口
让 frontend-dev 实现登录页面
让 qa 编写测试用例
查看当前团队状态
查看 frontend-dev 的工作进度
```

## 工具集说明

### Codex 默认核心工具（8 个）

- `create_team`
- `assign_task`
- `get_status`
- `list_templates`
- `list_teams`
- `switch_team`
- `destroy_team`
- `get_agent_view`

### 完整工具集（17 个）

除以上核心工具外，还包括：

- `verify_parallel_work`
- `list_all_agents`
- `get_team_communications`
- `get_agent_conversation`
- `get_agent_messages`
- `get_team_progress`
- `get_agent_progress`
- `get_realtime_status`
- `detect_stuck_agents`

### 何时使用完整工具集

如果你主要是在 `Codex` 中进行常规团队协作，默认核心工具通常就够用。

如果你需要：

- 调试团队协作过程
- 查看 Agent 间通信细节
- 追踪团队进度演化
- 检测 Agent 是否卡住

那么更适合启用 `--tool-profile full`。

## 内置团队模板

HIVE 当前内置 10 个团队模板：

| 模板 | 规模 | 说明 |
| --- | ---: | --- |
| `fullstack` | 8 | 全栈开发团队 |
| `backend` | 5 | 后端开发团队 |
| `frontend` | 5 | 前端开发团队 |
| `mobile` | 6 | 移动开发团队 |
| `research` | 5 | 调研分析团队 |
| `design` | 4 | 设计团队 |
| `architecture` | 4 | 架构团队 |
| `validation` | 4 | MVP / 验证团队 |
| `small` | 3 | 小型快速开发团队 |
| `large` | 12 | 大型完整配置团队 |

如需查看完整角色列表，直接调用 `list_templates` 即可。

## 通过代码调用

如果你不想通过 MCP 客户端使用，也可以直接在代码中调用：

```ts
import { quickStart } from 'hive-agent-teams'

const hive = await quickStart({
  template: 'fullstack',
  teamName: 'my-team',
  enableKnowledge: true
})

await hive.sendTask('backend-architect', '设计用户认证 API')

const status = await hive.getStatus()
console.log(status)

await hive.destroy()
```

## 从源码运行

```bash
git clone https://gitee.com/delldeng/hive.git
cd hive
npm install
npm run build
node ./dist/mcp-server.js --client codex
```

如果你要把源码构建结果接入 `Codex`：

```bash
codex mcp add hive -- node ./dist/mcp-server.js --client codex
```

## 开发命令

```bash
npm run build
npm run typecheck
npm test
npm run lint
npm run format
```

## 相关文档

- `docs/mcp-installation.md`：MCP 安装说明
- `docs/adapters/codex-adapter.md`：Codex 使用指南
- `docs/adapters/cursor-adapter.md`：Cursor 说明
- `docs/adapters/iflow-adapter.md`：iflow 说明
- `docs/agent-view-guide.md`：Agent 视角查看
- `docs/agent-communications-guide.md`：团队通信记录说明
- `docs/quick-start-guide.md`：快速启动说明
- `docs/phase3-knowledge-system.md`：知识系统设计

## 故障排查

### 1. 客户端里看不到 HIVE 工具

按顺序检查：

- 确认 Node.js 版本：`node --version`
- 确认 `npx` 可用：`npx --version`
- 确认客户端 MCP 配置路径正确
- 重启客户端

在 `Codex` 中还可以检查：

```bash
codex mcp list
codex mcp get hive
```

### 2. Codex 能连上，但工具太多、不好用

请优先使用：

```bash
codex mcp add hive -- npx -y hive-agent-teams --client codex
```

这会自动启用更适合 Codex 的核心工具集。

### 3. 需要更多调试信息

启用完整工具集：

```bash
codex mcp add hive -- npx -y hive-agent-teams --client codex --tool-profile full
```

### 4. 想完全避免本机绝对路径

使用 `npx` 启动，而不是手写 `C:/Users/.../dist/mcp-server.js` 这类路径。

## 常见问题

### 支持哪些平台？

支持 `Windows`、`macOS`、`Linux`，前提是本机可运行 `Node.js 20+`。

### 支持哪些客户端？

当前重点支持：

- `Codex`
- `Cursor`
- `Claude Desktop`
- `iflow`
- 其他兼容 MCP 的客户端

### 必须全局安装吗？

不是。跨设备场景更推荐使用 `npx -y hive-agent-teams`。

### Codex 模式和默认模式有什么区别？

`Codex` 模式会：

- 默认使用更短的服务器名
- 默认关闭启动横幅
- 默认只暴露核心 8 个工具

默认模式会保留完整 17 个工具，适合更高级的调试和观测场景。

## License

MIT