Hyperion项目-综合概述
Hyperion是一个基于人工智能的代码索引和分析平台，与Claude code的MCP集成。
安装并尝试（第一次）
这是从源代码到正在运行的Hyperion实例的最快验证路径。
先决条件
- 转到1.21+
- Node.js 18+
- Docker+Docker组合
1.克隆并安装依赖项
git clone https://github.com/HyperionWave-AI/dev-squad.git
cd dev-squad
make install2.构建Hyperion二进制文件
cd hyper
go build -tags dev -o ../bin/hyper ./cmd/coordinator
cd ..
export HYPER_BIN="$(pwd)/bin/hyper"
$HYPER_BIN --help3.创建项目工作区并初始化Hyperion
使用 hyper init 在您希望Hyperion管理的文件夹中。
mkdir -p ~/hyperion-demo
cd ~/hyperion-demo
$HYPER_BIN init -provider ollamahyper init 创建：
docker-compose.yml.env.hyperlitellm.config.yamlHYPER_README.md
4.启动本地服务
docker compose up -d
docker compose logs -f ollama-pull5.运行Hyperion
$HYPER_BIN --mode=http6.打开并验证
- Web用户界面：http://localhost:7095
- 健康终点：http://localhost:7095/api/v1/health
curl http://localhost:7095/api/v1/health有关特定于提供商的设置，请参阅 HYPER_README.md 由...生成 hyper init 或 docs/setup/HYPER_INIT_WITH_PROVIDER.md. 有关Ollama+Qwen Coder的集中本地设置，请参阅 docs/setup/QUICK_START.md.
桌面应用程序（Tauri）
Hyper还包括一个用Tauri构建的原生桌面shell desktop-app/. 桌面shell启动本地 hyper 后端作为sidecar进程，并自动打开现有的UI。
先决条件
- 防锈工具链(
rustup,cargo) - Tauri CLI(
cargo install tauri-cli) - Tauri的平台依赖关系（Linux上的WebKitGTK，macOS上的Xcode CLT，Windows上的WebView2）
在开发模式下运行桌面应用程序
make desktop构建桌面捆绑包
make desktop-build跨平台示例：
make desktop-build PLATFORMS="macos-arm64 windows-amd64 linux-amd64"捆绑输出如下：
- macOS：
desktop-app/src-tauri/target//release/bundle/macos/ - 窗户：
desktop-app/src-tauri/target//release/bundle/msi/ - Linux：
desktop-app/src-tauri/target//release/bundle/appimage/
执行摘要
亥伯龙 （代码库： hyper)是一个统一的AI驱动的代码分析和协调平台，通过模型上下文协议（MCP）与Claude code集成。它通过一个具有多种运行时模式的Go二进制文件提供智能代码索引、语义搜索和人工智能辅助开发工作流。
核心价值主张
- 单一统一二进制 (
hyper)具有三种运行时模式 - 人工智能驱动的代码理解 通过嵌入和向量搜索
- Claude代码集成 通过MCP stdio协议
- REST API+Web用户界面 用于独立使用
- 实时文件查看 以及自动代码索引
- 多嵌入支持 （Ollama、OpenAI、Voyage、TEI）
______________________________________________________________________
项目架构
高级概述
┌─────────────────────────────────────────────────────────────┐
│ Hyperion (hyper binary) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ HTTP Mode │ │ MCP Mode │ │ Both Mode │ │
│ │ (REST + UI) │ │ (stdio) │ │ (default) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ Port 7095 Claude Code Both Active │
│ Web Browser Integration │
│ │
├─────────────────────────────────────────────────────────────┤
│ Core Services │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Code Indexing & Analysis │ │
│ │ • File watcher (fsnotify) │ │
│ │ • Code parser & tokenizer │ │
│ │ • Semantic indexing │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Embedding & Vector Search │ │
│ │ • Multiple embedding providers │ │
│ │ • Qdrant vector database │ │
│ │ • Semantic similarity search │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ AI Integration │ │
│ │ • LangChain integration │ │
│ │ • Tool definitions (JSON Schema) │ │
│ │ • MCP protocol handlers │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Storage Layer │ │
│ │ • MongoDB (metadata, tasks, history) │ │
│ │ • Qdrant (vector embeddings) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘目录结构
hyper/
├── cmd/
│ └── coordinator/ # Unified binary entry point
│ └── main.go # --mode flag: http|mcp|both
│
├── internal/
│ ├── server/ # HTTP server (Gin framework)
│ │ ├── routes.go # REST API endpoints
│ │ ├── handlers/ # HTTP request handlers
│ │ └── middleware/ # CORS, auth, logging
│ │
│ ├── mcp/ # Model Context Protocol
│ │ ├── handlers/ # MCP tool implementations
│ │ ├── storage/ # MongoDB + Qdrant clients
│ │ ├── embeddings/ # Embedding providers
│ │ ├── indexer/ # Code indexing logic
│ │ ├── watcher/ # File watching
│ │ └── protocol.go # MCP protocol handling
│ │
│ ├── ai-service/
│ │ ├── tools/ # Tool definitions
│ │ └── llm/ # LLM integrations
│ │
│ └── middleware/ # Shared middleware
│
├── embed/ # Embedded UI (auto-generated)
│ └── ui/ # Built React UI
│
├── go.mod # Go dependencies
├── Makefile # Build targets
└── .archived/ # Archived redundant binaries
├── cmd/bridge/
├── cmd/mcp-server/
├── cmd/indexer/
└── cmd/hyper/
coordinator/
└── ui/ # React UI source
├── src/
│ ├── components/ # React components
│ ├── pages/ # Page components
│ ├── services/ # API clients
│ └── App.tsx # Main app
├── dist/ # Built UI (auto-generated)
└── package.json______________________________________________________________________
技术栈
后端（Go）
| 组件 | 技术 | 目的 |
|---|---|---|
| 框架 | Gin Web框架 | HTTP服务器和路由 |
| 协议 | MCP Go SDK | 克劳德代码集成 |
| 数据库 | MongoDB | 元数据、任务、历史 |
| 矢量数据库 | Qdrant | 语义搜索 |
| 文件监视 | fsnotify | 实时文件监控 |
| 嵌入 | 多个提供者 | 矢量生成 |
| 日志记录 | Uber Zap | 结构化日志记录 |
| LLM链 | LangChain Go | 人工智能编排 |
| JWT公司 | golang jwt | 身份验证 |
| WebSocket | Gorilla WebSocket | 实时更新 |
前端（React）
| 组件 | 技术 | 目的 |
|---|---|---|
| 框架 | React 18+ | 用户界面库 |
| 构建工具 | Vite | 快速捆绑 |
| 样式 | TBD | UI样式 |
| API客户端 | Fetch/Axios | REST API通信 |
| 状态 | TBD | 状态管理 |
嵌入提供者
| 提供者 | 模型 | 用例 |
|---|---|---|
| 奥拉玛 （推荐） | nomic嵌入文本 | 本地，GPU加速，隐私优先（默认） |
| 开放人工智能 | text-embedding-3-small | 基于云，高质量 |
| Voyage AI | voyage-3 | 专业嵌入 |
| 电话 | 自定义模型 | 自托管嵌入 |
推荐：我们强烈建议使用 奥拉玛 由于以下原因导致的嵌入： - 隐私：所有代码都保留在您的计算机上 - 成本：无API费用或费率限制 - 演出：GPU加速本地处理 - 离线：无需互联网连接即可工作 - 质量：Nomic嵌入文本提供了出色的代码嵌入
基础设施
| 组件 | 目的 |
|---|---|
| MongoDB 阿特拉斯 | 云数据库 |
| Qdrant云 | 管理向量数据库 |
| 码头工人 | 集装箱化 |
| Docker Compose | 地方发展 |
______________________________________________________________________
核心功能
1. 代码索引与分析
- 实时文件查看 使用fsnotify
- 自动代码解析 以及标记化
- 语义索引 有嵌入
- 增量更新 为了表现
- 多语言支持 （Go、Python、JavaScript等）
2. 语义搜索
- 基于向量的相似性搜索 通过Qdrant
- 代码段检索 按语义意义
- 上下文感知搜索 使用嵌入
- 过滤和排名 能力
3. 克劳德代码集成（MCP）
- stdio协议 用于直接克劳德集成
- 工具定义 JSON模式格式
- 实时代码分析 来自克劳德
- 双向通信 克劳德代码
4. REST API+Web用户界面
- RESTful端点 对于所有操作
- 基于React的web界面 在7095端口
- 实时更新 通过WebSocket
- 认证 通过JWT代币
- CORS支持 用于跨来源请求
5. 文件监视和自动索引
- 递归目录监视
- 自动重新索引 文件更改
- 批处理 为了提高效率
- 可配置的手表图案
6. AI服务集成
- LangChain集成 用于AI工作流程
- 工具调用 用于结构化AI交互
- 提示模板 实现一致的输出
- 代币计数 成本估算
______________________________________________________________________
运行时模式
模式1:HTTP模式(--mode=http)
./bin/hyper --mode=http- REST API 在7095端口
- 网页用户界面 嵌入二进制
- 独立操作 没有克劳德
- 用例：独立代码分析工具
模式2:MCP模式(--mode=mcp)
./bin/hyper --mode=mcp- stdio协议 克劳德代码
- 没有HTTP服务器 跑步
- 直接克劳德集成
- 用例：克劳德代码插件
模式3：两种模式(--mode=both)-默认值
./bin/hyper --mode=both
./bin/hyper # Default- HTTP服务器 在7095端口
- MCP 标准 克劳德代码
- 两个接口 同时活动
- 用例：功能齐全的开发环境
______________________________________________________________________
配置
环境变量
# MongoDB
MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net"
MONGODB_DATABASE="coordinator_db1"
# Qdrant Vector Database
QDRANT_URL="https://qdrant-instance.com"
QDRANT_KNOWLEDGE_COLLECTION="dev_squad_knowledge"
# Embedding Provider (ollama|openai|voyage|tei)
EMBEDDING="ollama"
# Ollama Configuration
OLLAMA_URL="http://localhost:11434"
OLLAMA_MODEL="nomic-embed-text"
# OpenAI Configuration
OPENAI_API_KEY="sk-..."
OPENAI_MODEL="text-embedding-3-small"
# Voyage AI Configuration
VOYAGE_API_KEY="pa-..."
# Server Configuration
PORT="7095"
LOG_LEVEL="info"
# Code Indexing
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工具
______________________________________________________________________
构建和部署
建筑
# Build unified binary with embedded UI
make native
# Development with hot reload
make dev-hot
# Run tests
make test输出
- 二进制:
bin/hyper（约16MB，带嵌入式UI） - 平台：Linux、macOS、Windows
- 嵌入式：二进制文件中包含React UI
码头工人
# Build Docker image (release Dockerfile)
docker build -f Dockerfile.release -t hyperion:latest .
# Run with Docker Compose
docker-compose up
# Run container
docker run -p 7095:7095 \
-e MONGODB_URI="..." \
-e QDRANT_URL="..." \
hyperion:latestGitHub发布和多平台Docker镜像通过以下方式实现自动化：
.github/workflows/release.yml（通过推送标签触发，如v1.2.3)- 已发布图片：
ghcr.io//:
______________________________________________________________________
用例
1. 人工智能辅助代码审查
- 使用AI分析代码更改
- 获得代码的语义理解
- 识别模式和问题
2. Claude代码集成
- 用作克劳德代码插件
- Claude中的实时代码分析
- 克劳德的语义搜索
3. 代码搜索和导航
- 查找类似的代码模式
- 发现相关文件
- 浏览大型代码库
4. 文档生成
- 从代码自动生成文档
- 创建API文档
- 生成架构图
5. 代码质量分析
- 检测代码气味
- 识别重构机会
- 执行编码标准
6. 知识管理
- 索引项目知识
- 商店架构决策
- 维护代码文档
______________________________________________________________________
开发工作流程
设置
# Install dependencies
make install
# Install Air for hot reload
make install-air
# Configure environment
cp .env.example .env.hyper发展
# Start with hot reload (Go + UI)
make dev-hot
# Or just Go hot reload
make dev
# Run tests
make test
# Build for distribution
make native测试
# Run all tests
make test
# Run specific test
go test ./internal/mcp/handlers -v
# Test with coverage
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框架
- 特性:
- RESTful路由 - 中间件（CORS、auth） - 错误处理 - 请求验证
______________________________________________________________________
性能特征
索引
- 速度：~1000个文件/秒（取决于文件大小）
- 记忆：10K文件约100MB
- 存储：每1000个文件约1MB（元数据）
搜索
- 延迟：语义搜索小于100ms
- 吞吐量：100+查询/秒
- 准确度：高（基于向量的相似性）
API
- 响应时间：大多数端点\ a+b, 0); }",
}
resp, _ := client.Embeddings(context.Background(), req) // resp.Embedding contains 768-dimensional vector }
### 高级Olama配置
#### 使用不同的模型
Try other embedding models
ollama pull mxbai-embed-large # 335M params, 1024 dimensions ollama pull all-minilm # 22M params, 384 dimensions
Update .env.hyper
OLLAMA_MODEL=mxbai-embed-large EMBEDDING_DIMENSION=1024
#### GPU加速
Ollama会自动使用GPU（如果可用）：
Check GPU usage
nvidia-smi # NVIDIA GPUs
or
metal-smi # Apple Silicon
#### 性能调优
Adjust Ollama settings for performance
In ~/.ollama/config.json
{ "num_gpu": 1, # Number of GPUs to use "num_thread": 8, # CPU threads "num_parallel": 4 # Parallel requests }
### Olama故障排除
#### Olama服务未运行
macOS
brew services restart ollama
Linux
killall ollama && ollama serve &
Check status
curl http://localhost:11434/api/tags
#### 未找到型号
Re-pull the model
ollama pull nomic-embed-text
Verify it's available
ollama list
#### 尺寸不匹配错误
Hyperion will detect dimension mismatch and offer to recreate collection
Or manually set auto-recreate:
export CODE_INDEX_AUTO_RECREATE=true ./bin/hyper --mode=http
#### 缓慢的嵌入生成
Ensure GPU is being used
ollama ps # Should show GPU memory usage
If CPU-only, check GPU drivers
nvidia-smi # NVIDIA system_profiler SPDisplaysDataType # macOS
### 从其他提供商迁移
#### 从OpenAI到Ollama
1. Install and configure Ollama (see above)
2. Update .env.hyper
EMBEDDING=ollama OLLAMA_URL=http://localhost:11434 OLLAMA_MODEL=nomic-embed-text EMBEDDING_DIMENSION=768
3. Recreate code index (dimensions changed from 1536 to 768)
export CODE_INDEX_AUTO_RECREATE=true ./bin/hyper --mode=http
4. Re-index your code
The system will automatically use Ollama for new embeddings
#### 从旅行到Ollama
Similar process, just update EMBEDDING variable
EMBEDDING=ollama
Rest of the steps are the same
### 成本比较
|提供商|每100万代币的成本|备注|
|----------|-------------------|-------|
| **奥拉玛** | **自由** |无限本地使用|
|OpenAI |约0.13美元|文本嵌入3-small|
|航行AI |约0.12美元|航行3|
|TEI |基础设施成本|自托管|
对于一个典型的中型代码库（10K个文件），您可能会生成5000万个嵌入令牌，对于云提供商来说，这将花费约6.50美元，但 **完全免费** 与Ollama。
______________________________________________________________________
## 建筑亮点
### 单二进制方法
- **一个可执行文件** 具有所有功能
- **没有单独的服务** 需要
- **轻松部署** 和分配
- **降低复杂性** 和维护
### 模块化设计
- **明确区分关注点**
- **可插拔组件** （嵌入、存储）
- **易于扩展** 并定制
- **可测试架构**
### 云就绪
- **MongoDB 阿特拉斯** 可扩展性
- **Qdrant云** 用于矢量搜索
- **Docker支持** 集装箱化
- **基于环境的配置**
______________________________________________________________________
*最后更新日期：2026年2月22日*
*项目：Hyperion（超级）*