基于AST的语义代码搜索，开箱即用

一款轻量级、高效的 (基于AST) 语义代码搜索工具，专为您的代码库设计。它构建于 CocoIndex 之上——一个基于Rust的超高效数据转换引擎。您可以通过CLI使用它，也可以通过 Skill 或 MCP 将其集成到Claude、Codex、Cursor等任何编码助手中。

• 立即节省70%的token消耗。
• 1分钟设置 — 安装即用，无需任何配置！

开始使用 — 无需配置，马上上手！

安装

使用 pipx：

pipx install cocoindex-code       # 首次安装
pipx upgrade cocoindex-code       # 升级

使用 uv：

uv tool install --upgrade cocoindex-code --prerelease explicit --with "cocoindex>=1.0.0a24"

默认嵌入模型在本地运行（sentence-transformers/all-MiniLM-L6-v2)——无需API密钥，完全免费。

接下来，设置您的 编码助手集成——或者如果您更喜欢直接控制，可以直接跳到 手动CLI使用。

编码助手集成

Skill（推荐）

安装 ccc 技能，这样您的编码助手会在需要时自动使用语义搜索：

npx skills add cocoindex-io/cocoindex-code

就这么简单——无需 ccc init 或 ccc index。该技能会教会助手自行完成初始化、索引和搜索。它会在您工作时自动保持索引最新。

当语义搜索有帮助时，助手会自动使用它。您也可以明确提示它——只需让它搜索代码库，例如“查找用户会话是如何管理的”，或者输入 /ccc 直接调用该技能。

适用于 Claude Code 及其他兼容技能的助手。

MCP服务器

或者，您可以使用 ccc mcp 作为MCP服务器运行：

claude mcp add cocoindex-code -- ccc mcp

codex mcp add cocoindex-code -- ccc mcp

opencode mcp add
输入MCP服务器名称：`cocoindex-code`
选择MCP服务器类型：`local`
输入要运行的命令：`ccc mcp`

或者使用 opencode.json：
```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cocoindex-code": {
      "type": "local",
      "command": [
        "ccc", "mcp"
      ]
    }
  }
}

一旦配置完毕，助手会自动判断何时使用语义代码搜索是有帮助的——根据描述查找代码、探索不熟悉的代码库、进行模糊或概念匹配，或者在不知道确切名称的情况下定位实现。

注意： cocoindex-code 命令（无子命令）仍然可以作为MCP服务器运行，以保持向后兼容性。首次运行时，它会根据环境变量自动创建设置。

search(
    query: str,                          # 自然语言查询或代码片段
    limit: int = 5,                      # 最大结果数（1-100）
    offset: int = 0,                     # 分页偏移量
    refresh_index: bool = True,          # 查询前刷新索引
    languages: list[str] | None = None,  # 按语言过滤（例如["python", "typescript"]）
    paths: list[str] | None = None,      # 按路径glob过滤（例如["src/utils/*"]）
)

手动CLI使用

您也可以直接使用CLI——这对于手动控制、更改设置后重新索引、检查状态，或在助手之外进行搜索非常有用。

ccc init                                # 初始化项目（创建设置）
ccc index                               # 构建索引
ccc search "authentication logic"       # 搜索！

后台守护进程会在首次使用时自动启动。

提示： 如果您尚未运行 ccc init，ccc index 会自动初始化，因此您可以直接跳到索引阶段。

CLI 参考

搜索选项

ccc search database schema                           # 基本搜索
ccc search --lang python --lang markdown schema      # 按语言过滤
ccc search --path 'src/utils/*' query handler        # 按路径过滤
ccc search --offset 10 --limit 5 database schema     # 分页
ccc search --refresh database schema                 # 先更新索引，再进行搜索

默认情况下，ccc search 的搜索范围限定在当前工作目录内（相对于项目根目录）。可以使用 --path 参数来覆盖此行为。

Docker

对于希望拥有可复现且无依赖环境的团队，我们提供了 Docker 镜像——宿主机上无需安装 Python、uv 或其他系统依赖。

推荐的做法是使用持久化容器：只需启动一次，然后通过 docker exec 来运行 CLI 命令或连接 MCP 会话。容器内的守护进程会在会话之间保持运行状态，因此嵌入模型只需加载一次。

步骤 1 — 启动容器

docker run -d --name cocoindex-code \
  --volume "$(pwd):/workspace" \
  --volume cocoindex-db:/db \
  --volume cocoindex-model-cache:/root/.cache \
  ghcr.io/cocoindex-io/cocoindex-code:latest

• /workspace — 将您的项目根目录挂载到这里
• cocoindex-db — 索引数据库存储在容器内部（本地 I/O 速度快，不存在跨操作系统卷的问题）
• cocoindex-model-cache — 在镜像升级时仍能保留嵌入模型

步骤 2 — 索引您的代码库

docker exec -it cocoindex-code ccc index

步骤 3 — 连接您的编码助手

claude mcp add cocoindex-code -- docker exec -i cocoindex-code ccc mcp

{
  "mcpServers": {
    "cocoindex-code": {
      "type": "stdio",
      "command": "docker",
      "args": ["exec", "-i", "cocoindex-code", "ccc", "mcp"]
    }
  }
}

codex mcp add cocoindex-code -- docker exec -i cocoindex-code ccc mcp

容器内的 CLI 使用

所有 ccc 命令都可以通过 docker exec 来执行：

docker exec -it cocoindex-code ccc index
docker exec -it cocoindex-code ccc search "authentication logic"
docker exec -it cocoindex-code ccc status

您也可以在宿主机上设置别名，使其使用起来更自然：

alias ccc='docker exec -it cocoindex-code ccc'

通过环境变量配置

使用 -e 参数将配置传递给 docker run：

# 额外的文件扩展名（例如 Typesafe Config、SBT 构建文件）
-e COCOINDEX_CODE_EXTRA_EXTENSIONS="conf,sbt"

# 排除构建产物（Scala/SBT 示例）
-e COCOINDEX_CODE_EXCLUDE_PATTERNS='["**/target/**","**/.bloop/**","**/.metals/**"]'

# 替换为针对代码优化的嵌入模型
-e COCOINDEX_CODE_EMBEDDING_MODEL=voyage/voyage-code-3
-e VOYAGE_API_KEY=your-key

在本地构建镜像

docker build -t cocoindex-code:local -f docker/Dockerfile .

功能

• 语义代码搜索：当 grep 效果不佳时，使用自然语言查询找到相关代码，同时立即节省 token。
• 超高效：⚡ 基于高性能的 Rust 索引引擎 构建。仅对更改的文件重新索引，实现快速更新。
• 多语言支持：Python、JavaScript/TypeScript、Rust、Go、Java、C/C++、C#、SQL、Shell 等。
• 嵌入式：便携易用，无需数据库设置！
• 灵活的嵌入模型：默认使用本地 SentenceTransformers（免费），也可通过 LiteLLM 调用 100 多家云服务提供商的模型。

配置

配置信息存储在两个 YAML 文件中，这两个文件都会由 ccc init 自动创建。

用户设置（~/.cocoindex_code/global_settings.yml）

在所有项目间共享。用于控制嵌入模型以及守护进程的环境变量。

embedding:
  provider: sentence-transformers                    # 或 "litellm"
  model: sentence-transformers/all-MiniLM-L6-v2
  device: mps                                        # 可选：cpu、cuda、mps（未指定时自动检测）

envs:                                                # 守护进程的额外环境变量
  OPENAI_API_KEY: your-key                           # 仅当您的 shell 环境中尚未设置时才需要

注意：守护进程会继承您的 shell 环境。如果某个 API 密钥（例如 OPENAI_API_KEY）已在您的 shell 环境中设置，则无需在 envs 中重复设置。envs 字段仅用于那些未包含在您环境中的值。

项目设置（<project>/.cocoindex_code/settings.yml）

按项目配置。用于控制要索引的文件。

include_patterns:
  - "**/*.py"
  - "**/*.js"
  - "**/*.ts"
  - "**/*.rs"
  - "**/*.go"
  # ... （针对28种以上文件类型的合理默认值）

exclude_patterns:
  - "**/.*"                # 隐藏目录
  - "**/__pycache__"
  - "**/node_modules"
  - "**/dist"
  # ...

language_overrides:
  - ext: inc               # 将 .inc 文件视为 PHP
    lang: php

chunkers:
  - ext: toml              # 对 .toml 文件使用自定义分块器
    module: example_toml_chunker:toml_chunker

.cocoindex_code/ 会在初始化时自动添加到 .gitignore 中。

当您希望在索引之前控制某种文件类型如何被分割成块时，可以使用 chunkers。

module: example_toml_chunker:toml_chunker 表示：

• example_toml_chunker 是一个本地 Python 模块
• toml_chunker 是该模块中的函数

实际操作中，通常意味着：

• 您在项目中创建一个 Python 文件，例如 example_toml_chunker.py
• 在该文件中添加一个函数
• 使用 module.path:function_name 将其指向 settings.yml

该函数应采用以下签名：

from pathlib import Path
from cocoindex_code.chunking import Chunk

def my_chunker(path: Path, content: str) -> tuple[str | None, list[Chunk]]:
    ...

• path 是正在索引的文件
• content 是该文件的完整文本
• 如果您想覆盖语言检测，请返回类似 "toml" 的字符串作为 language_override
• 如果您想保留检测到的语言，请将 language_override 设置为 None
• 返回一个包含您希望存储在索引中的分块的 list[Chunk]

有关公共类型，请参阅 src/cocoindex_code/chunking.py，完整的示例请参考 tests/example_toml_chunker.py。

嵌入模型

默认情况下，会使用本地 SentenceTransformers 模型（sentence-transformers/all-MiniLM-L6-v2），无需 API 密钥。若要使用其他模型，请编辑 ~/.cocoindex_code/global_settings.yml。

下面的 envs 条目仅在您的 shell 环境中尚未包含密钥时才需要——守护进程会自动继承您的环境变量。

embedding:
  model: ollama/nomic-embed-text

embedding:
  model: text-embedding-3-small
envs:
  OPENAI_API_KEY: your-api-key

embedding:
  model: azure/your-deployment-name
envs:
  AZURE_API_KEY: your-api-key
  AZURE_API_BASE: https://your-resource.openai.azure.com
  AZURE_API_VERSION: "2024-06-01"

embedding:
  model: gemini/gemini-embedding-001
envs:
  GEMINI_API_KEY: your-api-key

embedding:
  model: mistral/mistral-embed
envs:
  MISTRAL_API_KEY: your-api-key

embedding:
  model: voyage/voyage-code-3
envs:
  VOYAGE_API_KEY: your-api-key

embedding:
  model: cohere/embed-v4.0
envs:
  COHERE_API_KEY: your-api-key

embedding:
  model: bedrock/amazon.titan-embed-text-v2:0
envs:
  AWS_ACCESS_KEY_ID: your-access-key
  AWS_SECRET_ACCESS_KEY: your-secret-key
  AWS_REGION_NAME: us-east-1

embedding:
  model: nebius/BAAI/bge-en-icl
envs:
  NEBIUS_API_KEY: your-api-key

任何 LiteLLM 支持的模型 都可以使用。使用 LiteLLM 模型时，需设置 provider: litellm（或省略 provider——对于非 sentence-transformers 模型，默认为 LiteLLM）。

本地 SentenceTransformers 模型

设置 provider: sentence-transformers，并使用任何 SentenceTransformers 模型（无需 API 密钥）。

示例——通用文本模型：

embedding:
  provider: sentence-transformers
  model: nomic-ai/nomic-embed-text-v1.5

针对 GPU 优化的代码检索：

nomic-ai/CodeRankEmbed 提供的代码检索效果显著优于默认模型。该模型拥有 1.37 亿参数，需要约 1 GB 显存，并具有 8192 个标记的上下文窗口。

embedding:
  provider: sentence-transformers
  model: nomic-ai/CodeRankEmbed

注意： 更换模型需要重新索引您的代码库（ccc reset && ccc index），因为向量维度不同。

支持的语言

自定义数据库位置

默认情况下，索引数据库（cocoindex.db 和 target_sqlite.db）与设置文件一同位于 <project>/.cocoindex_code/。在 Docker 中运行时，为了性能考虑，您可能希望将数据库放在容器的原生文件系统上（LMDB 在挂载卷上表现不佳），同时将源代码和设置文件保留在挂载卷上。

通过设置 COCOINDEX_CODE_DB_PATH_MAPPING，可以根据路径前缀重新映射数据库位置：

COCOINDEX_CODE_DB_PATH_MAPPING=/workspace=/db-files

使用此映射后，位于 /workspace/myrepo 的项目会将其数据库存储在 /db-files/myrepo/，而不是 /workspace/myrepo/.cocoindex_code/。设置文件仍保留在原始位置。

多个映射之间用逗号分隔，并按顺序解析（以第一个匹配为准）：

COCOINDEX_CODE_DB_PATH_MAPPING=/workspace=/db-files,/workspace2=/db-files2

源路径和目标路径都必须是绝对路径。如果没有匹配的映射，则使用默认位置。

故障排除

运行 ccc doctor 可诊断常见问题。它会一次性检查您的设置、守护进程状态、嵌入模型、文件匹配情况以及索引状态。

sqlite3.Connection 对象没有属性 enable_load_extension

某些 Python 安装（例如 macOS 上预装的版本）附带的 SQLite 库不支持扩展。

macOS 解决方案： 通过 Homebrew 安装 Python：

brew install python3

然后重新安装 cocoindex-code（安装选项请参阅入门指南）：

使用 pipx：

pipx install cocoindex-code       # 首次安装
pipx upgrade cocoindex-code       # 升级

使用 uv（安装或升级）：

uv tool install --upgrade cocoindex-code --prerelease explicit --with "cocoindex>=1.0.0a24"

遗留：环境变量

如果您之前曾通过环境变量配置 cocoindex-code，则 cocoindex-code 的 MCP 命令仍会读取这些变量，并在首次运行时自动迁移到 YAML 配置文件。对于新项目，我们建议切换到 YAML 配置。

大型代码库 / 企业级应用

CocoIndex 是一款超高效的索引引擎，能够处理大规模的企业级代码库。在企业场景中，当存在大量或大型代码仓库时，与团队成员共享索引将更加高效。我们还为企业用户提供了分支去重等高级功能。

如果您需要远程部署方面的帮助，请发送邮件至我们的维护者 linghua@cocoindex.io，我们将竭诚为您服务！

贡献

我们欢迎社区贡献！在开始之前，请先安装 pre-commit 钩子，以便在每次提交前自动运行代码检查、格式化、类型检查和测试：

pip install pre-commit
pre-commit install

这将帮助您在代码进入 CI 流水线之前，及时发现常见的问题，例如尾随空格、代码风格错误（Ruff）、类型错误（mypy）以及测试失败。

更多详细信息，请参阅我们的贡献指南。

许可证

Apache-2.0

cocoindex-code 快速上手指南

cocoindex-code 是一款基于抽象语法树（AST）的轻量级语义代码搜索工具。它能帮助你在大型代码库中通过自然语言快速定位代码，显著减少 AI 编程助手的 Token 消耗（最高节省 70%）。无需复杂配置，安装即可使用。

环境准备

• 操作系统：Linux、macOS 或 Windows (WSL)
• 运行时依赖：
  • 推荐安装 pipx 用于隔离安装 Python 应用。
  • 或者使用 uv 进行更快速的包管理。
• 网络要求：首次运行时会自动下载默认的本地嵌入模型 (sentence-transformers/all-MiniLM-L6-v2)，请确保网络畅通。如需使用国内加速，可配置 Hugging Face 镜像环境变量。

安装步骤

你可以选择以下任意一种方式进行安装：

方式一：使用 pipx（推荐）

pipx install cocoindex-code       # 首次安装
pipx upgrade cocoindex-code       # 升级版本

方式二：使用 uv

uv tool install --upgrade cocoindex-code --prerelease explicit --with "cocoindex>=1.0.0a24"

提示：默认使用本地运行的嵌入模型，无需 API Key，完全免费。

基本使用

安装完成后，你可以通过命令行直接使用，或将其集成到 Claude Code、Cursor 等 AI 编程助手之中。

1. 命令行直接使用 (CLI)

这是最基础的使用方式，适用于手动搜索或脚本调用。

初始化与索引构建 进入你的项目根目录，运行以下命令。ccc index 会自动检测并创建必要的配置文件，若未初始化会自动执行初始化流程。

ccc index                               # 构建或更新代码索引（显示实时进度）

执行语义搜索 使用自然语言描述你要查找的功能，而非精确的关键字。

ccc search "用户会话是如何管理的"       # 搜索中文描述
ccc search "authentication logic"       # 搜索英文描述

常用搜索选项

# 按编程语言过滤
ccc search --lang python --lang markdown "数据库连接池"

# 按文件路径过滤
ccc search --path 'src/utils/*' "错误处理逻辑"

# 查看索引状态
ccc status

后台守护进程会在首次使用时自动启动，无需手动管理。

2. 集成到 AI 编程助手 (推荐)

让 AI 助手自动调用语义搜索，提升回答准确率并节省 Token。

方案 A：使用 Skill 模式 (最简单)

适用于支持 Skill 的 Agent（如 Claude Code）。只需运行一次，Agent 即可自动学会何时调用搜索。

npx skills add cocoindex-io/cocoindex-code

使用方法：在对话中直接询问 "查找项目中处理用户登录的代码"，或输入 /ccc 强制触发搜索。

方案 B：使用 MCP 服务器模式

适用于需要显式配置 MCP 的工具（如 Cursor, Codex, OpenCode）。

Claude Code 配置示例：

claude mcp add cocoindex-code -- ccc mcp

Cursor / 通用 MCP 配置： 在工具的 MCP 设置中添加以下配置：

• Command: ccc
• Args: mcp

配置完成后，AI 助手将自动决定何时进行语义搜索，以理解代码库结构或查找具体实现。

3. 高级用法：Docker 部署

如果你希望环境完全隔离且可复现，可以使用 Docker。

启动容器：

docker run -d --name cocoindex-code \
  --volume "$(pwd):/workspace" \
  --volume cocoindex-db:/db \
  --volume cocoindex-model-cache:/root/.cache \
  ghcr.io/cocoindex-io/cocoindex-code:latest

在容器内构建索引和搜索：

docker exec -it cocoindex-code ccc index
docker exec -it cocoindex-code ccc search "核心业务逻辑"

配置别名以便像本地命令一样使用：

alias ccc='docker exec -it cocoindex-code ccc'