Dev Squad

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）

前端（React）

嵌入提供者

推荐：我们强烈建议使用 奥拉玛 由于以下原因导致的嵌入： - 隐私：所有代码都保留在您的计算机上 - 成本：无API费用或费率限制 - 演出：GPU加速本地处理 - 离线：无需互联网连接即可工作 - 质量：Nomic嵌入文本提供了出色的代码嵌入

基础设施

______________________________________________________________________

核心功能

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（超级）*