Code Context Hologres用户手册

环境要求

阿里云百炼DashScope配置

您需要获取DashScope的API Key来使用嵌入模型。

1. 注册阿里云账号。

2. 开通百炼服务。

3. 在百炼控制台创建API Key。Key格式以sk-开头。

可用的DashScope嵌入模型：

Hologres实例配置

您需要一个Hologres实例来存储向量数据。请记录以下信息：

AI编程助手安装

根据您使用的编程助手，完成对应安装：

• Qwen Code：参考Qwen Code官方文档完成安装。

• Claude Code：参考Claude Code文档完成安装。

在Claude Code中配置

claude mcp add code-context-hologres \
    -e EMBEDDING_PROVIDER=DashScope \
    -e DASHSCOPE_API_KEY=sk-your-dashscope-api-key \
    -e EMBEDDING_MODEL=text-embedding-v4 \
    -e EMBEDDING_BATCH_SIZE=10 \
    -e HOLOGRES_HOST=your-hologres-instance.hologres.aliyuncs.com \
    -e HOLOGRES_PORT=80 \
    -e HOLOGRES_DATABASE=your-database-name \
    -e HOLOGRES_USER=your-access-id \
    -e HOLOGRES_PASSWORD=your-access-secret \
  -- npx code-context-mcp-hologres@latest

{
  "mcpServers": {
    "code-context-hologres": {
      "command": "npx",
      "args": ["-y", "code-context-mcp-hologres@latest"],
      "env": {
        "EMBEDDING_PROVIDER": "DashScope",
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key",
        "EMBEDDING_MODEL": "text-embedding-v4",
        "EMBEDDING_BATCH_SIZE": "10",
        "HOLOGRES_HOST": "your-hologres-instance.hologres.aliyuncs.com",
        "HOLOGRES_PORT": "80",
        "HOLOGRES_DATABASE": "your-database-name",
        "HOLOGRES_USER": "your-access-id",
        "HOLOGRES_PASSWORD": "your-access-secret"
      }
    }
  }
}

claude mcp list

在Qwen Code中配置

qwen mcp add \
    -t stdio \
    -e EMBEDDING_PROVIDER=DashScope \
    -e DASHSCOPE_API_KEY=sk-your-dashscope-api-key \
    -e EMBEDDING_MODEL=text-embedding-v4 \
    -e EMBEDDING_BATCH_SIZE=10 \
    -e HOLOGRES_HOST=your-hologres-instance.hologres.aliyuncs.com \
    -e HOLOGRES_PORT=80 \
    -e HOLOGRES_DATABASE=your-database-name \
    -e HOLOGRES_USER=your-access-id \
    -e HOLOGRES_PASSWORD=your-access-secret \
    code-context-hologres \
    npx -y code-context-mcp-hologres@latest

{
  "mcpServers": {
    "code-context-hologres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "code-context-mcp-hologres@latest"],
      "env": {
        "EMBEDDING_PROVIDER": "DashScope",
        "DASHSCOPE_API_KEY": "sk-your-dashscope-api-key",
        "EMBEDDING_MODEL": "text-embedding-v4",
        "EMBEDDING_BATCH_SIZE": "10",
        "HOLOGRES_HOST": "your-hologres-instance.hologres.aliyuncs.com",
        "HOLOGRES_PORT": "80",
        "HOLOGRES_DATABASE": "your-database-name",
        "HOLOGRES_USER": "your-access-id",
        "HOLOGRES_PASSWORD": "your-access-secret"
      }
    }
  }
}

全局配置文件方式（通用）

如果您同时在多个MCP客户端中使用Code Context Hologres，可以通过全局配置文件统一管理凭据，无需在每个客户端重复设置环境变量。

创建~/.context/.env文件，写入以下内容：

# DashScope 嵌入模型配置
EMBEDDING_PROVIDER=DashScope
DASHSCOPE_API_KEY=sk-your-dashscope-api-key
EMBEDDING_MODEL=text-embedding-v4
EMBEDDING_BATCH_SIZE=10

# Hologres 数据库配置
HOLOGRES_HOST=your-hologres-instance.hologres.aliyuncs.com
HOLOGRES_PORT=80
HOLOGRES_DATABASE=your-database-name
HOLOGRES_USER=your-access-id
HOLOGRES_PASSWORD=your-access-secret

使用全局配置文件后，MCP注册命令可以大幅简化：

Claude Code：

claude mcp add code-context-hologres -- npx code-context-mcp-hologres@latest

Qwen Code：

qwen mcp add \
    -t stdio \
    code-context-hologres \
    npx -y code-context-mcp-hologres@latest

DashScope嵌入模型配置

Hologres数据库配置

高级配置

基本工作流程

1. 在项目的目录中打开AI编程助手（Qwen Code或Claude Code）。

2. 让AI索引您的代码库。

3. 查看索引状态，等待索引完成。

4. 使用自然语言搜索代码。

索引代码库

索引代码库会将项目文件分块、生成向量嵌入，并存入Hologres。索引在后台异步运行，启动后会立即返回响应。

您只需用自然语言告诉AI：

> 索引这个代码库

AI会自动调用index_codebase工具。该工具支持以下参数：

示例：索引时包含额外的文件类型。

> 索引这个代码库，并包含 .vue 和 .svelte 文件

示例：强制重新索引。

> 强制重新索引当前代码库

查看索引状态

索引进度可以在后台运行时随时查看。AI会调用get_indexing_status工具。

> 查看索引状态

可能的状态：

搜索代码

使用自然语言查询即可搜索已索引的代码库。AI会调用search_code工具。

> 查找处理用户认证的函数

search_code工具支持以下参数：

更多搜索示例：

> 找到所有与数据库连接相关的代码

> 搜索错误处理逻辑，只看 .py 文件

> 查找与支付流程相关的代码片段

> 搜索 Hologres 向量检索的实现代码

清除索引

如果需要清除代码库的索引数据（例如切换了嵌入模型），可以：

> 清除当前代码库的索引

AI会调用clear_index工具，删除Hologres中的索引数据。

完整使用示例（Claude Code）

$ cd /path/to/your-project
$ claude

> 索引这个代码库
code-context-hologres: Started background indexing for codebase '/path/to/your-project'
using AST splitter. Indexing is running in the background.

> 查看索引状态
code-context-hologres: Codebase '/path/to/your-project' is currently being indexed.
Progress: 45.2% (Processing files and generating embeddings...)

> 查看索引状态
code-context-hologres: Codebase '/path/to/your-project' is fully indexed and ready
for search. Statistics: 128 files, 1,536 chunks.

> 查找处理用户登录认证的函数
code-context-hologres: Found 5 results for query "用户登录认证":
1. Code snippet (TypeScript) [your-project]
   Location: src/auth/login.ts:15-42
   ...

完整使用示例（Qwen Code）

$ cd /path/to/your-project
$ qwen

> 索引这个代码库
code-context-hologres: Started background indexing for codebase '/path/to/your-project'
using AST splitter. Indexing is running in the background.

> 查看索引状态
code-context-hologres: Codebase '/path/to/your-project' is fully indexed and ready
for search. Statistics: 128 files, 1,536 chunks.

> 查找处理用户登录认证的函数
code-context-hologres: Found 5 results for query "用户登录认证":
1. Code snippet (TypeScript) [your-project]
   Location: src/auth/login.ts:15-42
   ...

切换DashScope模型

您可以通过修改EMBEDDING_MODEL环境变量来切换DashScope嵌入模型。

例如，使用text-embedding-v3模型：

# 在 MCP 注册命令中修改
-e EMBEDDING_MODEL=text-embedding-v3

或在~/.context/.env中修改：

EMBEDDING_MODEL=text-embedding-v3

自定义文件扩展名

默认情况下，Code Context Hologres支持常见的编程语言文件。如果您需要索引额外的文件类型（如.vue、.svelte、.astro），有两种方式：

方式一：通过环境变量CUSTOM_EXTENSIONS全局配置。

CUSTOM_EXTENSIONS=.vue,.svelte,.astro

方式二：在索引时通过自然语言指定。

> 索引这个代码库，包含 .vue 和 .svelte 文件

自定义忽略规则

Code Context Hologres会自动读取项目中的.gitignore、.contextignore文件以及~/.context/.contextignore全局忽略文件。您还可以通过以下方式添加额外的忽略规则：

方式一：通过环境变量CUSTOM_IGNORE_PATTERNS。

CUSTOM_IGNORE_PATTERNS=*.test.ts,__mocks__,*.generated.ts

方式二：在索引时通过自然语言指定。

> 索引这个代码库，忽略 .test.ts 和 __mocks__ 目录

代码分割器选择

Code Context Hologres支持两种代码分割器：

通常无需手动指定，系统默认使用ast分割器并自动回退。

混合搜索配置

Code Context Hologres默认启用混合搜索（BM25稀疏向量 + 稠密向量），搜索准确性更高。如果需要关闭混合搜索（仅使用稠密向量），可以设置：

HYBRID_MODE=false