# teamhub

**Repository Path**: summor/teamhub

## Basic Information

- **Project Name**: teamhub
- **Description**: TeamHub — 团队知识枢纽，文档检索、经验管理、环境配置
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-07-24
- **Last Updated**: 2026-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TeamHub — 团队知识枢纽

为编码 Agent 提供文档检索、经验管理和环境配置的统一平台。支持 BM25 + 向量混合搜索、MCP 工具集成和 Web 管理界面。

## Architecture

```
                    ┌────────────────────┐
                    │   TeamHub Server   │
                    │  :3000 (Web + MCP) │
                    └────────┬───────────┘
                             │
          ┌──────────────────┼──────────────────┐
          ▼                  ▼                  ▼
    REST API (/api/*)   MCP HTTP (/api/mcp)  Vue 3 SPA
     (浏览器/curl)      (Hermes/OpenCode)    (Web UI)
```

支持两种 MCP 使用方式：

| 方式 | 适用场景 | 配置要点 |
|------|---------|---------|
| **HTTP 模式** (推荐) | 远程访问、多 Agent 共享 | 指向 `http://<服务器IP>:3000/api/mcp` |
| **stdio 模式** | 本地单进程使用 | `teamhub mcp` |

## Quick Start

### 从发布包启动（Windows）

```bash
start.bat
```

启动后访问终端打印的 IP 地址。

### 手动构建

```bash
# 后端
cd backend && cargo build --release

# 前端
cd frontend && npm install && npm run build

# 启动
./target/release/teamhub
```

打开 http://localhost:3000

## Configuration

配置文件 `teamhub.yaml` 放在可执行文件同目录：

```yaml
server:
  host: "0.0.0.0"       # 0.0.0.0 = 监听所有网络接口，允许远程访问
  port: 3000

embedding:
  api_base: "http://127.0.0.1:8002/v1"  # 向量化 API
  api_key: ""
  model: "bge-m3"
  batch_size: 64

reranker:
  api_base: ""        # 留空=禁用重排序
  api_key: ""
  model: ""
  threshold: 0.3
```

**关键配置项**：
- `server.host` — `0.0.0.0` 允许局域网/远程访问。`127.0.0.1` 只允许本机
- `embedding.api_base` — 必配，指向兼容 OpenAI Embedding API 的服务（如 llama.cpp GGUF）
- 路径字段可省略，默认在 exe 旁自动创建 `data/` 目录

## Remote MCP — 远程 Agent 调用

TeamHub 的 `POST /api/mcp` 是一个 HTTP JSON-RPC 端点。任何支持 HTTP MCP 的客户端（Hermes Agent、OpenCode 等）都可以通过网络远程调用 TeamHub 的能力。

### 前提条件

1. TeamHub 绑定 `0.0.0.0`（默认已在 `teamhub.yaml` 中配置）
2. 服务器防火墙开放 3000 端口
3. 知道 TeamHub 服务器的局域网 IP（`start.bat` 启动时会自动打印）

### 工具列表

通过 MCP 可调用的工具：

| 工具 | 说明 |
|------|------|
| `teamhub_search` | 混合搜索（BM25 + 向量 + RRF），返回 Top 10 chunk |
| `teamhub_get_chunk_context` | 获取 chunk 的上下文（前后相邻 chunk） |
| `teamhub_add_experience` | 创建经验记录（含标签关联 + 自动索引） |
| `teamhub_search_env` | 搜索环境配置（名称/备注/IP） |
| `teamhub_list_tags` | 列出全部标签 |

### 在 Hermes Agent 中配置远程 MCP

编辑 Hermes Agent 的 `config.yaml`，在 `mcpServers` 中添加：

```yaml
mcpServers:
  teamhub:
    transport: http
    url: "http://192.168.1.100:3000/api/mcp"   # 替换为 TeamHub 的实际 IP
```

配置后 Hermes Agent 会自动发现并注册 TeamHub 提供的 5 个工具，Agent 可在对话中按需调用。

### 在 OpenCode 中配置远程 MCP

编辑 OpenCode 配置文件（`~/.opencode/config.json` 或项目级 `.opencode.json`）：

```json
{
  "mcpServers": {
    "teamhub": {
      "url": "http://192.168.1.100:3000/api/mcp"
    }
  }
}
```

### 在 VSCode/IDE MCP 客户端中配置

```json
{
  "mcpServers": {
    "teamhub": {
      "url": "http://192.168.1.100:3000/api/mcp"
    }
  }
}
```

### stdio 模式（本地单进程）

如果 Agent 与 TeamHub 在同一台机器上，也可以直接用 stdio 模式：

```json
{
  "mcpServers": {
    "teamhub": {
      "command": "/path/to/teamhub",
      "args": ["mcp"]
    }
  }
}
```

### 安全说明

- TeamHub 当前无内置认证，建议在内网或 VPN 环境使用
- 如需公网暴露，请在反向代理（Nginx/Caddy）侧做认证

## API

### 文档库

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/folders | 文件夹目录树 |
| POST | /api/folders | 创建文件夹 |
| DELETE | /api/folders/:id | 删除文件夹 |
| PUT | /api/folders/:id | 重命名 |
| PATCH | /api/folders/:id/move | 移动到 |
| GET | /api/documents | 文档列表 (?folder_id=) |
| POST | /api/documents/upload | 上传文档 (multipart) |
| GET | /api/documents/:id | 文档详情 |
| PUT | /api/documents/:id | 更新元数据 |
| PATCH | /api/documents/:id/move | 移动到 |
| DELETE | /api/documents/:id | 删除文档 |

### 经验库

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/experiences | 经验列表 (?tag=&repo=) |
| POST | /api/experiences | 创建经验 |
| GET | /api/experiences/:id | 经验详情 |
| PUT | /api/experiences/:id | 编辑经验 |
| DELETE | /api/experiences/:id | 删除经验 |

### 环境管理

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/environments | 环境列表 (?q=) |
| POST | /api/environments | 添加环境 |
| GET | /api/environments/:id | 环境详情 |
| PUT | /api/environments/:id | 编辑环境 |
| DELETE | /api/environments/:id | 删除环境 |

### 搜索 & 管理

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/search | 统一搜索 (?q=&source=&limit=) |
| POST | /api/admin/reindex | 重建搜索索引 |

## Development

```bash
# 启动后端（开发模式）
cd backend && cargo run

# 启动前端（开发模式，代理到 :3000）
cd frontend && npm run dev
```

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Backend | Rust + axum + rusqlite + sqlite-vec |
| Search | Tantivy (BM25) + bge-m3 向量 (1024维, llama.cpp GGUF) |
| Fusion | RRF (Reciprocal Rank Fusion) |
| Storage | SQLite (rusqlite) + sqlite-vec (cosine, int8 量化) |
| Frontend | Vue 3 + TDesign + Vite |
| MCP | stdio JSON-RPC + HTTP JSON-RPC |
| PDF/DOCX | Docling (IBM) 引擎，降级到纯文本 |