npm package: @ian2018cs/agenthub
Description: A web-based UI for AI Agents
Author: IAn2018cs
Latest version: 0.2.18

<div align="center">
  <img src="public/logo.svg" alt="AgentHub" width="64" height="64">
  <h1>AgentHub</h1>
  <p>基于 Web 的 AI Agent 管理平台，支持桌面与移动端</p>
</div>

---

## 简介

AgentHub 是一个全功能的 AI Agent Web UI，可本地或远程部署，让你随时随地（手机、电脑）管理和使用 AI Agent 会话。支持 Claude、Gemini、Codex 多种 AI 引擎，并提供飞书 IM 集成、多用户管理、工具安全守卫等企业级特性。

## 功能特性

### 核心对话
- **Claude Agent 对话** — 基于 `@anthropic-ai/claude-agent-sdk`，支持流式响应、工具调用、会话续接
- **Gemini Shell** — node-pty 驱动 Gemini CLI，xterm.js 渲染真实终端体验
- **Codex Shell** — node-pty 驱动 Codex CLI，xterm.js 渲染，独立会话隔离
- **WebSocket 实时通信** — 前后端通过 WebSocket 双向通信，响应实时推送

### 项目与文件管理
- **项目管理** — 自动发现 Agent 会话，按项目分组，支持重命名、删除
- **文件浏览器** — 交互式文件树，支持展开/折叠导航
- **文件编辑器** — CodeMirror 6 驱动，多语言语法高亮、实时编辑保存
- **MCP 服务器支持** — 通过 UI 添加、管理自定义 MCP 服务器，自动同步到 Codex

### 多用户与权限
- **多用户系统** — 注册/登录，JWT 认证，每用户数据完全隔离（独立 UUID 目录）
- **三级角色** — `super_admin`（首个注册用户）、`admin`（受限管理员）、`user`（普通用户）
- **限额管理** — 按用户设置每日使用限额，管理员面板实时查看用量
- **邮箱域名白名单** — 限制注册邮箱域名范围

### 飞书 IM 集成
- **WebSocket 长连接** — 通过 `@larksuiteoapi/node-sdk` 接收飞书消息
- **单聊对话** — 在飞书直接与 AI Agent 对话
- **工具审批卡片** — Agent 执行危险操作时，飞书推送审批卡片
- **语音转文字** — 支持语音消息（需配置 ffmpeg + Whisper）
- **文件/图片发送** — Agent 可将生成文件自动发送到飞书聊天

### 安全
- **工具安全守卫（Tool Guard）** — 双层检测：正则规则快速拦截 + LLM 兜底审查
- **路径隔离** — 阻止访问用户目录之外的文件系统路径
- **危险命令拦截** — 阻止 rm -rf、系统文件修改、全局包安装等高危操作

### Agent 商店
- **系统 Agent 仓库** — 发布、安装、管理预置 Agent
- **版本管理** — 支持 Agent 版本控制与更新
- **管理员审核** — Agent 提交需管理员审核后才能上架

### 其他
- **图片持久化** — 聊天图片 SHA-256 去重存储，30 天自动清理
- **计费统计** — 按模型精确计算 token 用量和费用
- **响应式设计** — 桌面、平板、手机全端适配，支持添加到主屏幕

---

## 快速开始

### 环境要求

- [Node.js](https://nodejs.org/) v20 或更高版本
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) 已安装并配置

### 一键运行（推荐）

无需安装，直接运行：

```bash
npx agenthub
```

服务启动后访问 `http://localhost:3001`（或你配置的端口）。

### 全局安装

```bash
npm install -g agenthub
agenthub
```

更新到最新版本：

```bash
agenthub update
```

### CLI 命令

| 命令 / 选项 | 简写 | 说明 |
|------------|------|------|
| `agenthub` | | 启动服务（默认） |
| `agenthub start` | | 显式启动服务 |
| `agenthub status` | | 显示配置和数据目录信息 |
| `agenthub update` | | 更新到最新版本 |
| `agenthub help` | | 显示帮助信息 |
| `agenthub version` | | 显示版本信息 |
| `--port <port>` | `-p` | 指定端口（默认：3001） |
| `--database-path <path>` | | 指定数据库存储路径 |

示例：

```bash
agenthub -p 8080          # 在 8080 端口启动
agenthub status           # 查看当前配置
```

### 后台服务（生产环境推荐）

使用 PM2 作为进程管理器：

```bash
npm install -g pm2

# 启动后台服务
pm2 start agenthub --name "agenthub"

# 在指定端口启动
pm2 start agenthub --name "agenthub" -- --port 8080

# 开机自启
pm2 startup
pm2 save
```

---

## 本地开发

```bash
# 克隆仓库
git clone git@git.amberweather.com:share/agenthub.git
cd agenthub

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 填写所需配置

# 开发模式（React 热重载 + Node 服务器）
npm run dev
```

其他开发命令：

```bash
npm run build    # 生产构建
npm run start    # 构建 + 启动服务器
npm run server   # 仅启动 Node 服务器
npm run client   # 仅启动 Vite dev 服务器
```

---

## 环境变量配置

在 `.env` 文件中配置以下变量：

### 基础配置

| 变量 | 说明 |
|------|------|
| `PORT` | 服务端口，默认 `3001` |
| `JWT_SECRET` | JWT 签名密钥（必填） |
| `ANTHROPIC_API_KEY` | Anthropic API Key |

### 飞书集成（可选）

| 变量 | 说明 |
|------|------|
| `FEISHU_APP_ID` | 飞书应用 App ID |
| `FEISHU_APP_SECRET` | 飞书应用 App Secret |
| `FEISHU_MENU_KEY_MAP` | JSON 格式，event_key → 斜杠命令映射 |
| `FEISHU_CARD_*_ID` | 各类消息卡片模板 ID |

设置 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 即可自动启用飞书集成。

### 语音转文字（可选，需飞书集成）

| 变量 | 说明 |
|------|------|
| `WHISPER_*` | Whisper 语音识别相关配置 |

### 工具安全守卫（可选）

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `TOOL_GUARD_ENABLED` | 总开关 | `false` |
| `TOOL_GUARD_LLM_ENABLED` | LLM 审查开关 | `false` |
| `TOOL_GUARD_LLM_MODEL` | LLM 审查模型 | `gemini-3.1-flash-lite-preview` |
| `TOOL_GUARD_LLM_TIMEOUT_MS` | LLM 超时时间（毫秒） | `5000` |
| `TOOL_GUARD_VERBOSE` | 详细日志 | `false` |

### LLM 通用配置（Tool Guard LLM 审查用）

| 变量 | 说明 |
|------|------|
| `OPENAI_API_KEY` | OpenAI 兼容 API Key |
| `OPENAI_BASE_URL` | OpenAI 兼容 API Base URL |

---

## 架构概览

```
┌──────────────────────┐    ┌──────────────────────┐    ┌──────────────────────┐
│  前端 (React + Vite)  │◄──►│  后端 (Express + WS)  │◄──►│  AI 引擎集成          │
│                      │    │                      │    │  Claude / Gemini     │
│  - ChatInterface     │    │  - claude-sdk.js     │    │  / Codex             │
│  - GeminiShell       │    │  - WebSocket 路由     │    │                      │
│  - CodexShell        │    │  - REST API          │    └──────────────────────┘
│  - CodeEditor        │    │  - SQLite (DB)       │
│  - AdminPanel        │    │  - Tool Guard        │    ┌──────────────────────┐
└──────────────────────┘    │  - 飞书 IM 服务       │◄──►│  飞书 IM              │
                            └──────────────────────┘    │  (长连接 WS)          │
                                                        └──────────────────────┘
```

### 技术栈

| 层级 | 技术 |
|------|------|
| 前端框架 | React 18 + Vite 7 |
| 样式 | Tailwind CSS 3.4 |
| 文件编辑器 | CodeMirror 6 |
| 终端 | xterm.js |
| 后端框架 | Node.js 20+ + Express 4 |
| 实时通信 | WebSocket (`ws`) |
| 数据库 | better-sqlite3 |
| 终端进程 | node-pty |
| AI SDK | `@anthropic-ai/claude-agent-sdk` |
| 飞书 SDK | `@larksuiteoapi/node-sdk` |

---

## 工具设置

> **注意**：所有 Agent 工具默认关闭，防止自动执行高风险操作。

开启工具步骤：
1. 点击侧边栏齿轮图标打开设置
2. 进入"工具设置"
3. 按需开启所需工具
4. 设置会自动保存

建议从基础工具开始，按需逐步开启。

---

## 常见问题

**无项目显示**
- 确认至少初始化了一个项目
- 检查 `~/.claude/projects/` 目录是否存在且有读取权限

**文件浏览器无法加载**
- 检查项目目录权限（`ls -la`）
- 确认项目路径存在且可访问
- 查看服务器控制台日志获取详细错误信息

**飞书集成不工作**
- 确认 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 已正确设置
- 检查飞书应用是否已开启事件订阅
- 确认机器人已被添加到对应群/单聊

---

## 许可证

MIT License — 详见 [LICENSE](LICENSE) 文件。

---

<div align="center">
  <strong>为 AI 开发者打造的一站式 Agent 管理平台</strong>
</div>