项目介绍
Hyperion 项目 - 综合概述
概要
Hyperion（代码库：hyper）是一个统一的AI驱动的代码分析和协调平台，通过Model Context Protocol (MCP)与Claude Code集成。它提供智能代码索引、语义搜索以及通过单一Go二进制文件和多种运行模式实现的AI辅助开发工作流。
核心价值主张
- 单一统一的二进制文件 (
hyper)，具有三种运行模式
- AI驱动的代码理解，通过嵌入式和向量搜索实现
- Claude Code集成，通过MCP stdio协议
- REST API + Web UI，用于独立使用
- 实时文件监控和自动代码索引
- 多嵌入支持（Ollama, OpenAI, Voyage, TEI）
项目架构
高级概述
┌─────────────────────────────────────────────────────────────┐
│ Hyperion (hyper 二进制文件) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ HTTP 模式 │ │ MCP 模式 │ │ 两种模式 │ │
│ │ (REST + UI) │ │ (stdio) │ │ (默认) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ 端口 7095 Claude Code 两者同时激活 │
│ Web 浏览器 集成 │
│ │
├─────────────────────────────────────────────────────────────┤
│ 核心服务 │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 代码索引与分析 │ │
│ │ • 文件监控器 (fsnotify) │ │
│ │ • 代码解析器及标记器 │ │
│ │ • 语义索引 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 嵌入式与向量搜索 │ │
│ │ • 多个嵌入提供商 │ │
│ │ • Qdrant 向量数据库 │ │
│ │ • 语义相似性搜索 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ AI 集成 │ │
│ │ • LangChain 集成 │ │
│ │ • 工具定义 (JSON Schema) │ │
│ │ • MCP 协议处理器 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 存储层 │ │
│ │ • MongoDB (元数据、任务、历史) │ │
│ │ • Qdrant (向量嵌入) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
目录结构
hyper/
├── cmd/
│ └── coordinator/ # 统一的二进制入口点
│ └── main.go # --mode 标志: http|mcp|both
│
├── internal/
│ ├── server/ # HTTP 服务器 (Gin 框架)
│ │ ├── routes.go # REST API 端点
│ │ ├── handlers/ # HTTP 请求处理器
│ │ └── middleware/ # CORS, 认证, 日志记录
│ │
│ ├── mcp/ # Model Context Protocol
│ │ ├── handlers/ # MCP 工具实现
│ │ ├── storage/ # MongoDB + Qdrant 客户端
│ │ ├── embeddings/ # 嵌入提供商
│ │ ├── indexer/ # 代码索引逻辑
│ │ ├── watcher/ # 文件监控
│ │ └── protocol.go # MCP 协议处理
│ │
│ ├── ai-service/
│ │ ├── tools/ # 工具定义
│ │ └── llm/ # LLM 集成
│ │
│ └── middleware/ # 共享中间件
│
├── embed/ # 嵌入式UI (自动生成)
│ └── ui/ # 构建的React UI
│
├── go.mod # Go 依赖项
├── Makefile # 构建目标
└── .archived/ # 归档冗余二进制文件
├── cmd/bridge/
├── cmd/mcp-server/
├── cmd/indexer/
└── cmd/hyper/
coordinator/
└── ui/ # React UI 源码
├── src/
│ ├── components/ # React 组件
│ ├── pages/ # 页面组件
│ ├── services/ # API 客户端
│ └── App.tsx # 主应用
├── dist/ # 构建的UI (自动生成)
└── package.json
技术栈
后端 (Go)
| 组件 | 技术 | 目的 |
|---|
| 框架 | Gin Web Framework | HTTP 服务器及路由 |
| 协议 | MCP Go SDK | Claude Code 集成 |
| 数据库 | MongoDB | 元数据、任务、历史 |
| 向量数据库 | Qdrant | 语义搜索 |
| 文件监控 | fsnotify | 实时文件监控 |
| 嵌入 | 多个提供商 | 向量生成 |
| 日志记录 | Uber Zap | 结构化日志记录 |
| LLM 链 | LangChain Go | AI 编排 |
| JWT | golang-jwt | 认证 |
| WebSocket | Gorilla WebSocket | 实时更新 |
前端 (React)
| 组件 | 技术 | 目的 |
|---|
| 框架 | React 18+ | UI 库 |
| 构建工具 | Vite | 快速打包 |
| 样式 | 待定 | UI 样式 |
| API 客户端 | Fetch/Axios | REST API 通信 |
| 状态管理 | 待定 | 状态管理 |
嵌入提供商
| 提供商 | 模型 | 使用场景 |
|---|
| Ollama (推荐) | nomic-embed-text | 本地、GPU 加速、隐私优先 (默认) |
| OpenAI | text-embedding-_3-small | 云端、高质量 |
| Voyage AI | voyage-3 | 专用嵌入 |
| TEI | 自定义模型 | 自托管嵌入 |
建议：我们强烈建议使用 Ollama 进行嵌入，因为：
- 隐私：所有代码都留在您的机器上
- 成本：没有API费用或速率限制
- 性能：本地GPU加速处理
- 离线：无需互联网连接即可工作
- 质量：Nomic-embed-text 提供出色的代码嵌入
基础设施
| 组件 | 目的 |
|---|
| MongoDB Atlas | 云数据库 |
| Qdrant Cloud | 管理向量数据库 |
| Docker | 容器化 |
| Docker Compose | 本地开发 |
核心功能
1. 代码索引与分析
- 实时文件监控 使用 fsnotify
- 自动代码解析 和标记
- 语义索引 使用嵌入
- 增量更新 以提高性能
- 多语言支持 (Go, Python, JavaScript 等)
2. 语义搜索
- 基于向量的相似性搜索 通过 Qdrant
- 按语义意义检索代码片段
- 上下文感知搜索 使用嵌入
- 过滤和排名 功能
3. Claude Code 集成 (MCP)
- stdio 协议 直接集成 Claude
- 工具定义 在 JSON Schema 格式中
- 来自 Claude 的实时代码分析
- 与 Claude Code 的双向通信
4. REST API + Web UI
- RESTful 端点 用于所有操作
- 基于 React 的 Web 界面 在端口 7095 上
- 通过 WebSocket 实现实时更新
- 通过 JWT 令牌进行认证
- 跨域请求支持
5. 文件监控与自动索引
- 递归目录监控
- 文件更改时自动重新索引
- 批量处理 以提高效率
- 可配置的监控模式
6. AI 服务集成
- LangChain 集成 用于 AI 工作流
- 工具调用 用于结构化的 AI 交互
- 提示模板 用于一致的输出
- 令牌计数 和成本估算
运行模式
模式 1: HTTP 模式 (--mode=http)
./bin/hyper --mode=http
- REST API 在端口 7095 上
- Web UI 嵌入在二进制文件中
- 不依赖 Claude 的独立操作
- 使用场景：独立的代码分析工具
模式 2: MCP 模式 (--mode=mcp)
./bin/hyper --mode=mcp
- stdio 协议 用于 Claude Code
- 无运行中的 HTTP 服务器
- 直接 Claude 集成
- 使用场景：Claude Code 插件
模式 3: 两种模式 (--mode=both) - 默认
./bin/hyper --mode=both
./bin/hyper # 默认
- HTTP 服务器 在端口 7095 上
- MCP stdio 用于 Claude Code
- 同时激活两个接口
- 使用场景：全功能开发环境
配置
环境变量
# MongoDB
MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net"
MONGODB_DATABASE="coordinator_db1"
# Qdrant 向量数据库
QDRANT_URL="https://qdrant-instance.com"
QDRANT_KNOWLEDGE_COLLECTION="dev_squad_knowledge"
# 嵌入提供商 (ollama|openai|voyage|tei)
EMBEDDING="ollama"
# Ollama 配置
OLLAMA_URL="http://localhost:11434"
OLLAMA_MODEL="nomic-embed-text"
# OpenAI 配置
OPENAI_API_KEY="sk-..."
OPENAI_MODEL="text-embedding-3-small"
# Voyage AI 配置
VOYAGE_API_KEY="pa-..."
# 服务器配置
PORT="7095"
LOG_LEVEL="info"
# 代码索引
CODE_INDEX_AUTO_RECREATE="false"
配置文件
- 位置：
.env.hyper (在可执行目录或当前目录中)
- 优先级：自定义配置路径 > 可执行目录 > 当前目录
- 格式：标准
.env 格式
API 端点
代码索引
POST /api/index/scan - 扫描目录中的代码GET /api/index/status - 获取索引状态DELETE /api/index/clear - 清除所有已索引的代码
搜索
POST /api/search/semantic - 语义代码搜索GET /api/search/results/:id - 获取搜索结果
代码分析
GET /api/code/:fileId - 获取代码文件POST /api/analyze - 分析代码片段GET /api/dependencies/:fileId - 获取文件依赖
任务与历史
GET /api/tasks - 列出任务POST /api/tasks - 创建任务GET /api/history - 获取操作历史
MCP 工具
POST /api/mcp/tools - 列出可用工具POST /api/mcp/execute - 执行 MCP 工具
构建与部署
构建
# 构建带有嵌入式UI的统一二进制文件
make native
# 开发模式带热重载
make dev-hot
# 运行测试
make test
输出
- 二进制文件：
bin/hyper (~16MB 带有嵌入式UI)
- 平台：Linux, macOS, Windows
- 嵌入：React UI 包含在二进制文件中
Docker
# 构建 Docker 镜像
docker build -t hyperion:latest .
# 使用 Docker Compose 运行
docker-compose up
# 运行容器
docker run -p 7095:7095 \
-e MONGODB_URI="..." \
-e QDRANT_URL="..." \
hyperion:latest
使用场景
1. AI 辅助代码审查
- 使用 AI 分析代码变更
- 获取代码的语义理解
- 识别模式和问题
2. Claude Code 集成
- 作为 Claude Code 插件使用
- 在 Claude 中实现实时代码分析
- 从 Claude 进行语义搜索
3. 代码搜索与导航
4. 文档生成
- 从代码自动生成文档
- 创建 API 文档
- 生成架构图
5. 代码质量分析
6. 知识管理
开发工作流程
设置
# 安装依赖项
make install
# 安装 Air 以实现热重载
make install-air
# 配置环境
cp .env.example .env.hyper
开发
# 启动带热重载 (Go + UI)
make dev-hot
# 或仅 Go 热重载
make dev
# 运行测试
make test
# 构建用于分发
make native
测试
# 运行所有测试
make test
# 运行特定测试
go test ./internal/mcp/handlers -v
# 带覆盖率测试
go test -cover ./...
关键组件深入探讨
代码索引器
- 位置：
internal/mcp/indexer/
- 目的：解析并索引代码文件
- 特性：
嵌入服务
- 位置：
internal/mcp/embeddings/
- 目的：生成向量嵌入
- 提供商：
- Ollama (本地, GPU)
- OpenAI (云端)
- Voyage AI (专用)
- TEI (自托管)
存储层
- 位置：
internal/mcp/storage/
- 组件：
- MongoDB 客户端 (元数据)
- Qdrant 客户端 (向量)
- 集合管理
- 查询构建器
MCP 处理器
- 位置：
internal/mcp/handlers/
- 目的：实现 MCP 工具
- 工具：
HTTP 服务器
- 位置：
internal/server/
- 框架：Gin Web Framework
- 特性：
- RESTful 路由
- 中间件 (CORS, 认证)
- 错误处理
- 请求验证
性能特征
索引
- 速度：~1000 文件/秒 (取决于文件大小)
- 内存：~100MB 对于 10K 文件
- 存储：~1MB 对于 1000 文件 (元数据)
搜索
- 延迟：<100ms 对于语义搜索
- 吞吐量：每秒 100+ 查询
- 准确性：高 (基于向量的相似性)
API
- 响应时间：<50ms 对于大多数端点
- 吞吐量：每秒 1000+ 请求
- 并发：完全并发
安全考虑
认证
