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 install

2.构建Hyperion二进制文件

cd hyper
go build -tags dev -o ../bin/hyper ./cmd/coordinator
cd ..
export HYPER_BIN="$(pwd)/bin/hyper"
$HYPER_BIN --help

3.创建项目工作区并初始化Hyperion

使用 hyper init 在您希望Hyperion管理的文件夹中。

mkdir -p ~/hyperion-demo
cd ~/hyperion-demo
$HYPER_BIN init -provider ollama

hyper init 创建：

docker-compose.yml
.env.hyper
litellm.config.yaml
HYPER_README.md

4.启动本地服务

docker compose up -d
docker compose logs -f ollama-pull

5.运行Hyperion

$HYPER_BIN --mode=http

6.打开并验证

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:latest

GitHub发布和多平台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（超级）*

Dev Ex MCP

快速接入

详细介绍

Hyperion项目-综合概述

安装并尝试（第一次）

先决条件

1.克隆并安装依赖项

2.构建Hyperion二进制文件

3.创建项目工作区并初始化Hyperion

4.启动本地服务

5.运行Hyperion

6.打开并验证

桌面应用程序（Tauri）

先决条件

在开发模式下运行桌面应用程序

构建桌面捆绑包

执行摘要

核心价值主张

项目架构

高级概述

目录结构

技术栈

后端（Go）

前端（React）

嵌入提供者

基础设施

核心功能

1. 代码索引与分析

2. 语义搜索

3. 克劳德代码集成（MCP）

4. REST API+Web用户界面

5. 文件监视和自动索引

6. AI服务集成

运行时模式

模式1:HTTP模式(--mode=http)

模式2:MCP模式(--mode=mcp)

模式3：两种模式(--mode=both)-默认值

配置

环境变量

配置文件

API终点

代码索引

搜索

代码分析

任务和历史

MCP工具

构建和部署

建筑

输出

码头工人

用例

1. 人工智能辅助代码审查

2. Claude代码集成

3. 代码搜索和导航

4. 文档生成

5. 代码质量分析

6. 知识管理

开发工作流程

设置

发展

测试

关键组件深潜

代码索引器

嵌入服务

存储层

MCP 处理器

HTTP服务器

性能特征

索引

搜索

API

Try other embedding models

Update .env.hyper

Check GPU usage

or

Adjust Ollama settings for performance

In ~/.ollama/config.json

macOS

Linux

Check status

模式1:HTTP模式(`--mode=http`)

模式2:MCP模式(`--mode=mcp`)

模式3：两种模式(`--mode=both`)-默认值