Cocoindex Code

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

一款轻量、高效的**（基于 AST）**语义代码搜索工具，适用于你的代码库。基于 CocoIndex 构建——一款基于 Rust 的超高性能数据转换引擎。可通过命令行使用，也可通过 Skill 或 MCP 与 Claude、Codex、Cursor 等任意编码 Agent 集成。

• 立即节省 70% 的 token。
• 1 分钟完成设置——安装后即可使用，无需任何配置！

快速开始——无需配置，马上开始！

安装

使用 pipx：

pipx install 'cocoindex-code[full]'          # batteries included (local embeddings)
pipx upgrade cocoindex-code                  # upgrade

使用 uv：

uv tool install --upgrade 'cocoindex-code[full]'

两种安装方式——对应同名的 Docker 镜像变体：

• cocoindex-code[full] — 功能齐全。会安装 sentence-transformers，因此本地嵌入（无需 API 密钥）开箱即用。ccc init 交互式提示默认使用 Snowflake/snowflake-arctic-embed-xs。
• cocoindex-code（精简版）— 仅包含 LiteLLM；需要云端嵌入服务提供商和 API 密钥。如果你不需要本地嵌入依赖（约 1 GB 的 torch 和 transformers），可使用此版本。

接下来，设置你的编码 Agent 集成；如果你更喜欢直接控制，也可以跳转到手动使用命令行。

编码 Agent 集成

此仓库是一个单一插件市场（.claude-plugin/marketplace.json），供 Claude Code 和 Grok 共用——使用相同的插件 ID cocoindex-code 和相同的 ccc Skill。Grok 可通过 --trust 选择启用捆绑的钩子和 MCP 服务；Claude Code 用户可以安装同一个市场，仅使用 Skill，也可以按需加载插件中的钩子和 MCP。

技能（推荐）

安装 ccc 技能，让你的编码 Agent 在需要时自动使用语义搜索：

npx skills add cocoindex-io/cocoindex-code

就这么简单——无需运行 ccc init 或 ccc index。该技能会教 Agent 自行处理初始化、索引和搜索。它会在你工作时自动保持索引为最新。

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

兼容 Claude Code 及其他兼容技能的 Agent。

Claude Code 插件市场

对于 Claude Code 用户，此仓库也是一个插件市场。在 Claude Code 中安装该技能：

/plugin marketplace add cocoindex-io/cocoindex-code
/plugin install cocoindex-code@cocoindex-code

此安装包包含相同的 ccc 技能，并提供版本锁定以及用于更新的 /plugin marketplace update。此仓库还附带 hooks/hooks.json 和 .mcp.json，供 Grok 使用（以及会加载这些文件的 Claude Code 插件安装使用）；只想使用技能进行搜索的 Claude 用户可仅使用该技能，并在下方的 MCP 服务部分手动添加 MCP，而非使用随附的 .mcp.json。

Grok 插件

对于 Grok 用户，可通过 Grok 的插件系统安装。该插件包含三个组件：

Grok 不会导入 Claude 的 enabledPlugins 或插件缓存；即使你已在 Claude Code 中使用 cocoindex，也需要单独安装。

完整安装（技能 + 钩子 + MCP）：

grok plugin marketplace add cocoindex-io/cocoindex-code
grok plugin install cocoindex-io/cocoindex-code --trust
grok plugin enable cocoindex-code

安装时优先使用 GitHub 简写形式（cocoindex-io/cocoindex-code）——如果没有与该名称匹配的市场插件，grok plugin install cocoindex-code 可能会失败。

必须使用 --trust，这样 Grok 才会激活插件的钩子和 MCP 服务（启用插件后会加载技能）。

仅安装技能（与 Claude Code 相同——无自动索引钩子，无 MCP 工具）：

按上述步骤安装并启用，然后禁用可选组件：

1. 钩子——打开 /hooks，选择来自 cocoindex-code 的 SessionStart / PostToolUse 钩子，按 Space 禁用。
2. MCP——打开 /mcps，选择 cocoindex-code，按 Space 禁用；或者在 ~/.grok/config.toml 中持久化设置：

[mcp_servers.cocoindex-code]
enabled = false

索引仍由 Agent 通过 ccc 技能负责（过期时运行 ccc index / ccc search --refresh），与 Claude Code 相同。

若要避免从 Claude/Cursor 用户配置中导入 MCP 服务（与此插件无关）：

[compat.claude]
mcps = false

[compat.cursor]
mcps = false

Oh My Pi 插件

Oh My Pi 会读取 .omp-plugin/marketplace.json（优先），若不存在则回退到 .claude-plugin/marketplace.json。

omp plugin marketplace add cocoindex-io/cocoindex-code
omp plugin install cocoindex-code@cocoindex-code --scope project

然后重启会话（/reload-plugins 不会重新加载扩展）。需要在 PATH 中找到 ccc（uv tool install --upgrade 'cocoindex-code[full]'）。

OMP 不会执行 Claude hooks/hooks.json 命令钩子。TypeScript 扩展相当于 OMP 版本的 Claude/Grok SessionStart + PostToolUse 组合。

仅安装 Skill（无 MCP、无自动索引）：通过 npx skills add cocoindex-io/cocoindex-code 安装 Skill，或在 shell 中运行 ccc search / ccc index。

MCP 服务端

或者，使用 ccc mcp 作为 MCP 服务运行：

claude mcp add cocoindex-code -- ccc mcp

codex mcp add cocoindex-code -- ccc mcp

opencode mcp add

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

{
  "mcp": {
    "cocoindex-code": {
      "type": "local",
      "command": ["ccc", "mcp"],
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "cocoindex-code": {
      "command": "ccc",
      "args": ["mcp"]
    }
  }
}

配置完成后，Agent 会自动判断何时适合进行语义代码搜索，例如按描述查找代码、探索不熟悉的代码库、查找模糊或概念性匹配项，或在不知道确切名称时定位实现。

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

search(
    query: str,                          # Natural language query or code snippet
    limit: int = 5,                      # Maximum results (1-100)
    offset: int = 0,                     # Pagination offset
    refresh_index: bool = True,          # Refresh index before querying
    languages: list[str] | None = None,  # Filter by language (e.g. ["python", "typescript"])
    paths: list[str] | None = None,      # Filter by path glob (e.g. ["src/utils/*"])
)

手动使用 CLI

你也可以直接使用 CLI，适用于手动控制、修改设置后运行索引、检查状态，或在 Agent 之外进行搜索。

ccc init                                # initialize project (creates settings)
ccc index                               # build the index
ccc search "authentication logic"       # search!

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

提示： 可以跳过 ccc init，直接运行 ccc index——它会使用默认设置自动初始化新项目。如果全局设置也缺失（在这台机器上首次使用），交互式运行时会引导你完成与 ccc init 相同的模型设置；非交互式运行（脚本、钩子）仍需先运行一次 ccc init。

注意： ccc index 绝不会自动初始化存放 ccc 用户设置的目录：默认是你的主目录（~/.cocoindex_code 存放全局设置和守护进程文件）；如果 $COCOINDEX_CODE_DIR 指向的目录名为 .cocoindex_code，则该目录的父目录也属于此范围。在那里创建项目会覆盖其下的所有代码库。即使该目录已经是项目，编辑器钩子也会跳过它。如果旧版 ccc 曾将你的主目录设为项目（存在 ~/.cocoindex_code/settings.yml），请在主目录中运行 ccc reset --all：这会移除该项目的设置和索引，同时保留全局设置。若确实要索引整个主目录，请在其中运行 ccc init。

CLI 参考

搜索选项

ccc search database schema                           # basic search
ccc search --lang python --lang markdown schema      # filter by language
ccc search --path 'src/utils/*' query handler        # filter by path
ccc search --offset 10 --limit 5 database schema     # pagination
ccc search --refresh database schema                 # update index first, then search

默认情况下，ccc search 会将结果限定在当前工作目录中（相对于项目根目录）。使用 --path 可覆盖此范围。

结构化搜索（ccc grep）

ccc grep 按结构而非文本查找代码——你编写一个基于示例的模式， 它会匹配语法树（通过 cocoindex 的 code_match），因此格式、空白字符 和中间的标记都不会影响匹配。它完全在本地运行：无需索引、守护进程或嵌入。

ccc grep 'def \NAME(\(ARGS*\)):'                      # every Python function def under the cwd
ccc grep 'foo(\(ARGS*\))' src/                        # calls to foo(...) anywhere under src/
ccc grep 'fn \NAME(\(A*\))' --lang rust               # restrict to one language
ccc grep 'class \NAME:' --path 'tests/**'            # restrict to a path glob
ccc grep 'TODO(\(A*\))' path/to/file.py               # a single file

元变量使用 \ 符号：\NAME 捕获一个节点，\(NAME*\) 捕获一组 同级节点，\_/\* 匿名匹配。模式会针对每种语言进行匹配，因此一次 调用即可扫描所有受支持的源文件（其他文件会被跳过）。在已初始化的项目中， ccc grep 会遵循项目的包含/排除模式和 .gitignore；否则，它会扫描指定路径下 所有受支持的源文件。

找到匹配项后，结果会逐个文件实时输出到终端（由于文件是并行匹配的，输出 顺序取决于完成顺序），而不是等到最后一次性输出。每个匹配文件都会显示匹配的 行范围；在 TTY 下，路径会以彩色显示，行号会变暗，匹配项周围未匹配的上下文 也会变暗，以突出匹配内容。

注意： ccc grep 依赖 cocoindex 的结构化 code_match 功能。 在该功能随正式发布版 cocoindex 发布之前，请使用本地构建的 cocoindex 运行。

Docker

我们提供 Docker 镜像，适合需要可复现、无需安装依赖环境的团队——主机上无需 安装 Python、uv 或系统依赖。

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

选择镜像

每个发行版都会发布两个变体：

本节其余内容均使用 :latest——如果要使用完整变体，请在 image: / docker run 命令中将其替换为 :full。

在 Mac 上运行 :full 变体的用户： Docker 内的本地嵌入推理 只能使用 CPU，因为 macOS 上的 Docker 无法访问 Apple Metal（MPS） GPU。如果你希望使用本地嵌入并实现快速推理，请改为原生安装： pipx install 'cocoindex-code[full]'。:latest （精简版）变体不受影响——LiteLLM 会在服务提供商端运行模型，因此 Docker 与原生运行没有区别。

快速开始 — docker compose up -d

一行命令即可启动——无需克隆（bash / zsh）：

# macOS / Windows
docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex-code/refs/heads/main/docker/docker-compose.yml) up -d

# Linux (aligns file ownership on bind-mounted paths with your host user)
PUID=$(id -u) PGID=$(id -g) docker compose -f <(curl -L https://raw.githubusercontent.com/cocoindex-io/cocoindex-code/refs/heads/main/docker/docker-compose.yml) up -d

或者获取 docker/docker-compose.yml，并在该文件所在目录运行 docker compose up -d（适用于任何 Shell，包括 Windows cmd / PowerShell）。

默认情况下，容器会挂载你的主目录（设置 COCOINDEX_HOST_WORKSPACE 可将范围缩小到特定代码文件夹）。索引 数据和嵌入模型缓存会保存在 Docker 卷中，并在重启后保留。主机上可以查看和编辑位于 $HOME/.cocoindex_code/global_settings.yml 的全局设置文件；所做更改会在你下次运行 ccc 命令时生效。

选择其他镜像： 设置 COCOINDEX_CODE_IMAGE 以覆盖 默认镜像。例如，使用 :full 变体或 GHCR：

COCOINDEX_CODE_IMAGE=cocoindex/cocoindex-code:full docker compose up -d
COCOINDEX_CODE_IMAGE=ghcr.io/cocoindex-io/cocoindex-code:latest docker compose up -d

或者：docker run

docker run -d --name cocoindex-code \
  --volume "$HOME:/workspace" \
  --volume cocoindex-data:/var/cocoindex \
  -e COCOINDEX_CODE_HOST_PATH_MAPPING="/workspace=$HOME" \
  cocoindex/cocoindex-code:latest

docker run -d --name cocoindex-code \
  -e PUID=$(id -u) -e PGID=$(id -g) \
  --volume "$HOME:/workspace" \
  --volume cocoindex-data:/var/cocoindex \
  -e COCOINDEX_CODE_HOST_PATH_MAPPING="/workspace=$HOME" \
  cocoindex/cocoindex-code:latest

用于 ccc 命令的 Shell 包装器

将以下内容粘贴到 ~/.bashrc / ~/.zshrc，这样就能在主机上像使用原生命令一样使用 ccc，并根据当前目录选中正确的项目：

ccc() {
  docker exec -it -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc "$@"
}

现在，进入工作区中的任意项目，运行 ccc init、ccc index、 ccc search ...、ccc status 等命令即可。

连接你的编码 Agent

claude mcp add cocoindex-code -- docker exec -i \
  -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc mcp

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

codex mcp add cocoindex-code -- docker exec -i \
  -e COCOINDEX_CODE_HOST_CWD="$PWD" cocoindex-code ccc mcp

从旧版镜像升级

早期镜像使用单独的 cocoindex-db 和 cocoindex-model-cache 卷；当前镜像将它们合并到单个 cocoindex-data 卷中。拉取新镜像前，删除旧容器和卷——索引会在你下次运行 ccc index 时重建，嵌入模型则会在首次启动时自动重新填充：

docker rm -f cocoindex-code
docker volume rm cocoindex-db cocoindex-model-cache

通过环境变量配置

使用 -e 将配置传递给 docker run / compose：

# Extra extensions (e.g. Typesafe Config, SBT build files)
-e COCOINDEX_CODE_EXTRA_EXTENSIONS="conf,sbt"

# Exclude build artefacts (Scala/SBT example)
-e COCOINDEX_CODE_EXCLUDE_PATTERNS='["**/target/**","**/.bloop/**","**/.metals/**"]'

# Set an API key
-e VOYAGE_API_KEY=your-key

安全提示： 挂载 $HOME 会让容器获得对其下所有内容的读写权限。 如果权限范围过大，请改为绑定挂载范围更小的目录 （COCOINDEX_HOST_WORKSPACE=/path/to/code）。

在本地构建镜像

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

功能

• 语义代码搜索：当 grep 效果不佳时，使用自然语言查询查找相关代码，并立即节省 Token。
• 超高性能：⚡ 基于超高性能的 Rust 索引引擎 构建。仅对发生更改的文件重新建立索引，实现快速更新。
• 多语言支持：Python、JavaScript/TypeScript、Rust、Go、Java、C/C++、C#、SQL、Shell 等。
• 嵌入式：可移植且开箱即用，无需设置数据库！
• 灵活的嵌入模型：通过 [full] extra 使用本地 SentenceTransformers（免费，无需 API 密钥！），或通过 LiteLLM 使用 100 多家云服务提供商。

配置

有关如何选择和配置嵌入模型的详细指南，请参阅 EMBEDDINGS.md。

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

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

所有项目共用。用于配置嵌入模型和守护进程的环境变量。

embedding:
  provider: sentence-transformers                    # or "litellm"
  model: Snowflake/snowflake-arctic-embed-xs
  device: mps                                        # optional: cpu, cuda, mps (auto-detected if omitted)
  min_interval_ms: 300                               # optional: pace LiteLLM embedding requests to reduce 429s; defaults to 5 for LiteLLM
  mps_low_watermark_ratio: 0.4                       # optional: PyTorch allocator soft limit
  mps_high_watermark_ratio: 0.5                      # optional: PyTorch allocator hard limit

  # Optional extra kwargs passed to the embedder, separately for indexing vs query.
  # `ccc init` auto-populates these for known models (e.g. Cohere, Voyage, Nvidia NIM,
  # nomic-ai code-retrieval models, Snowflake arctic-embed).
  # indexing_params:
  #   input_type: search_document        # litellm: input_type
  # query_params:
  #   input_type: search_query           # sentence-transformers: prompt_name

envs:                                                # extra environment variables for the daemon
  OPENAI_API_KEY: your-key                           # only needed if not already in your shell environment

daemon:
  idle_timeout_minutes: 180                          # optional: exit the daemon after this long without client activity (default 180, 0 = never)
  keep_alive_with_mcp: true                          # optional: keep the daemon warm while an MCP client is connected (default true)

注意： 守护进程会继承你的 shell 环境。如果某个 API 密钥（例如 OPENAI_API_KEY）已设置为环境变量，就无需在 envs 中重复配置。envs 字段仅用于设置环境中尚未存在的值。

Apple Silicon 内存安全： MPS SentenceTransformer 调用使用 CocoIndex 的隔离 GPU 子进程，在保持模型加载的同时，将 Metal 内存分配与守护进程隔离。低水位线和高水位线是 PyTorch 建议的最大工作集的比例，此处默认值分别为 0.4 和 0.5。CocoIndex 会在 MPS 内存不足时逐步缩小批次并重试，而 cocoindex-code 会在每次索引运行后释放未使用的分配器缓存。显式设置的 COCOINDEX_RUN_GPU_IN_SUBPROCESS、PYTORCH_MPS_LOW_WATERMARK_RATIO 和 PYTORCH_MPS_HIGH_WATERMARK_RATIO 环境变量优先于这些默认值。

索引并发： 多个项目可以同时准备索引，而 CocoIndex 会通过单个 MPS 子进程串行处理它们的 GPU 调用。只有当搜索所属的项目仍需创建初始索引时，搜索才会等待。

空闲超时： 后台守护进程会将嵌入模型保留在 RAM 中，因此在没有客户端活动达到 daemon.idle_timeout_minutes 指定的时长后会退出，并在你下次运行 ccc 命令或进行 MCP 搜索时自动重启。默认情况下，活跃的 MCP 会话会定期发送心跳，因此在编码 Agent 连接期间，守护进程会保持运行状态。设置 daemon.keep_alive_with_mcp: false，即可让守护进程在长期运行的 MCP 会话期间空闲退出，并在实际请求之间释放模型。设置 idle_timeout_minutes: 0 可使守护进程始终运行。

自定义位置： 将 COCOINDEX_CODE_DIR 设置为其他路径，即可将 global_settings.yml 放在 ~/.cocoindex_code/ 以外的位置；如果你希望将该文件与项目放在一起（例如放在同步文件夹中），此选项会很有用。

indexing_params / query_params

一些嵌入模型会针对文档和查询提供不同模式（非对称检索）。例如，Cohere 的 v3 模型在嵌入语料内容时要求使用 input_type: search_document，在嵌入用户查询时则要求使用 input_type: search_query；一些 SentenceTransformers 模型也会出于同样目的使用 prompt_name: passage / prompt_name: query。这些参数位于 indexing_params 和 query_params 下：

embedding:
  provider: litellm
  model: cohere/embed-english-v3.0
  indexing_params:
    input_type: search_document
  query_params:
    input_type: search_query

对于可识别的模型，ccc init 会自动填充这些参数——包括所有 Cohere v3、Voyage、Nvidia NIM、Gemini 嵌入模型（gemini/gemini-embedding-*、gemini/text-embedding-*、gemini/embedding-*——LiteLLM 会自动将 input_type 映射为 Gemini 的 task_type）、nomic-ai/CodeRankEmbed、nomic-ai/nomic-embed-code、nomic-ai/nomic-embed-text-v1/v1.5、mixedbread-ai/mxbai-embed-large-v1，以及 Snowflake/snowflake-arctic-embed-* 系列，并会打印所选默认值。对于其他模型，它会在 embedding: 下保留一份注释掉的模板，供你手动填写。

OpenAI 嵌入模型（text-embedding-3-*、text-embedding-ada-002）特意未列入其中：它们是对称的，没有对应的参数。

接受的键： prompt_name（sentence-transformers）和 input_type（litellm）。其他键会在守护进程启动时被拒绝，并显示清晰的错误信息。注意：这里不会提供 dimensions，因为索引和查询的输出维度必须相同，因此它是模型级设置，而非针对不同场景的参数。

Doctor 会检查两侧。 ccc doctor 会分别使用 indexing_params 和 query_params 对模型进行测试，并将结果分别报告为 Model Check (indexing) / Model Check (query) 条目，因此即使另一侧正常，也能诊断出其中一侧的配置错误。

旧版兼容警告： 如果你从早期版本升级，且 global_settings.yml 使用了 nomic-ai/CodeRankEmbed 或 nomic-ai/nomic-embed-code，但没有配置 indexing_params / query_params，守护进程会继续沿用先前的行为（查询时使用 prompt_name: query），并仅显示一次警告，要求你明确设置该参数。添加空代码块（例如 query_params: {}）即可关闭此警告。

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

每个项目各自设置。用于控制要索引哪些文件。

include_patterns:
  - "**/*.py"
  - "**/*.js"
  - "**/*.ts"
  - "**/*.rs"
  - "**/*.go"
  # ... (sensible defaults for 28+ file types)

exclude_patterns:
  - "**/.*"                # hidden directories
  - "**/__pycache__"
  - "**/node_modules"
  - "**/dist"
  # ...

max_file_size: 500KB       # skip files larger than this (default: no limit)

language_overrides:
  - ext: inc               # treat .inc files as PHP
    lang: php

chunkers:
  - ext: toml              # use a custom chunker for .toml files
    module: example_toml_chunker:toml_chunker

初始化期间，.cocoindex_code/ 会自动添加到 .gitignore。

max_file_size 可将捆绑文件或生成文件排除在索引之外，无需在 exclude_patterns 中逐一列出。它接受普通字节数（1048576），或带二进制单位后缀的大小：B、KB、MB、GB（不区分大小写，因此 500KB 和 500 kb 表示相同大小）。该限制包含边界值；省略此键时，任何大小的文件都会被索引。凡是项目文件匹配规则适用的地方，此设置也会生效，因此 ccc grep 会跳过相同的文件。

编辑 include_patterns、exclude_patterns、max_file_size 或 language_overrides 后：

• 运行 ccc doctor，预览匹配的文件。
• 运行 ccc index 或 ccc search --refresh ...，更新现有索引。
• 对于这些文件匹配规则的更改，无需删除索引或重启守护进程。
• 更改 language_overrides 后，下次运行会对所有文件重新分块，包括内容未更改的文件；运行报告会将它们标记为重新处理。文本未更改的块会保留缓存的嵌入向量。

如果添加或更改自定义 chunkers，或编辑分块器模块，请重启守护进程（ccc daemon restart），然后运行 ccc index。守护进程只会在启动时导入分块器，因此在重启之前，它会继续运行旧版分块器代码。重启后的首次运行会对所有文件重新分块，而不只是更改后的条目适用的文件；文本未更改的块会保留缓存的嵌入向量。当分块器的 module: 值发生变化，或其指定模块所在的文件发生变化时，分块器会被视为已更改。不会检测该文件导入的其他模块是否被编辑：进行此类编辑后，也要更改分块器自身的模块文件（例如，在其中更新版本注释）。

如果要控制索引前某种文件类型如何拆分为块，请使用 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 是该文件的完整文本
• 如果要覆盖语言检测结果，请将 language_override 作为字符串返回，例如 "toml"
• 如果要保留检测到的语言，请将 language_override 设为 None
• 返回一个包含要存入索引的块的 list[Chunk]

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

嵌入模型

安装 [full] 扩展后，ccc init 默认使用本地 SentenceTransformers 模型（Snowflake/snowflake-arctic-embed-xs），无需 API 密钥。若要使用其他模型，请编辑 ~/.cocoindex_code/global_settings.yml。

仅当密钥尚未设置在 shell 环境中时，才需要配置以下 envs 条目——守护进程会自动继承你的环境变量。

embedding:
  model: ollama/nomic-embed-text

embedding:
  model: text-embedding-3-small
  min_interval_ms: 300                               # optional: override the 5ms LiteLLM default
envs:
  OPENAI_API_KEY: your-api-key

embedding:
  model: openai/your-model-name
envs:
  OPENAI_BASE_URL: https://your-endpoint/v1
  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）。如需查看各提供商读取的全部环境变量（API 密钥、基础 URL、区域等），请参阅 LiteLLM 的设置 API 密钥。

本地 SentenceTransformers 模型

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

示例 — 通用文本模型：

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

针对 GPU 优化的代码检索：

nomic-ai/CodeRankEmbed 的代码检索效果显著优于默认模型。它有 137M 个参数，需要约 1 GB VRAM，上下文窗口为 8192 个 token。

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 object has no attribute enable_load_extension

某些 Python 安装（例如 macOS 预装的 Python）附带的 SQLite 库未启用扩展。

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

brew install python3

然后重新安装 cocoindex-code（安装选项请参阅开始使用）：

使用 pipx：

pipx install cocoindex-code       # first install
pipx upgrade cocoindex-code       # upgrade

使用 uv（安装或升级）：

uv tool install --upgrade cocoindex-code

MDB_MAP_FULL: Environment mapsize limit reached

索引存储在 LMDB 数据库中，其最大容量会在守护进程启动时固定。默认上限为 4 GiB，对大多数项目来说绰绰有余，但非常庞大的代码库（数万个文件）可能会耗尽空间，尤其是使用 nomic-ai/CodeRankEmbed 这类高维嵌入模型时。

使用 COCOINDEX_LMDB_MAP_SIZE 环境变量（值以字节为单位）提高上限。LMDB 只会在写入数据时扩展文件，因此设置较高的上限不会预先分配磁盘空间，可以放心设置为较大的值：

# ~/.cocoindex_code/global_settings.yml
envs:
  COCOINDEX_LMDB_MAP_SIZE: "34359738368"   # 32 GiB (= 32 * 1024^3)

或者，如果你更愿意在 shell 环境中设置（守护进程会继承该设置）：

export COCOINDEX_LMDB_MAP_SIZE=$((32 * 1024 * 1024 * 1024))   # 32 GiB

映射大小会在守护进程启动时读取，因此请重启守护进程以应用更改，然后重新建立索引：

ccc daemon restart
ccc index

此手动步骤只是临时方案。待 cocoindex#2108 合并后，映射大小会在需要时自动增长，无需再设置 COCOINDEX_LMDB_MAP_SIZE。

旧版：环境变量

如果你之前通过环境变量配置了 cocoindex-code，cocoindex-code MCP 命令仍会读取这些变量，并在首次运行时自动迁移到 YAML 设置。对于新的配置，我们建议改用 YAML 设置。

遥测

cocoindex-code 会通过 CocoIndex 发送匿名使用遥测数据，以便我们了解工具的总体使用情况并确定改进优先级。事件会标记为 application: cocoindex-code。

我们不会收集你的源代码、文件路径、查询、搜索结果、嵌入向量、设置，或代码库及环境中的任何其他内容。

如需选择退出，请设置：

export COCOINDEX_DISABLE_USAGE_TRACKING=1

大型代码库 / 企业

CocoIndex 是一款超高效的索引引擎，也能在企业场景中大规模处理大型代码库。在企业场景中，如果仓库较大或数量较多，与团队成员共享索引会高效得多。我们还提供分支去重等高级功能，专为企业用户设计。

为超大型代码库建立索引时遇到 MDB_MAP_FULL？请调大 LMDB 映射大小——参见故障排除中的 MDB_MAP_FULL: Environment mapsize limit reached。

如果您需要远程配置方面的帮助，请发送邮件至我们的维护者 [email protected]，我们很乐意提供帮助！

贡献

欢迎贡献！本项目使用 uv 进行开发，每个 PR 在 CI 中都会运行相同的 lint、格式检查、类型检查和测试套件。提交 PR 前请在本地运行这些检查——未通过 pre-commit 检查是新 PR 导致 CI 报错的最常见原因。

1. 安装开发依赖

安装 uv 后，同步项目。此操作会安装检查所需的所有内容，包括 prek（快速的 pre-commit 运行器）、Ruff、mypy 和 pytest：

uv sync

2. 每次提交 PR 前运行所有检查

对所有文件运行完整的钩子套件——这与 CI 运行的内容完全相同：

uv run prek run --all-files

它会修复行尾空格和文件末尾格式，运行 Ruff lint（--fix）和格式检查，验证 uv.lock，运行 mypy 类型检查和 pytest 测试套件。请修复报告的所有问题（Ruff 会自动修复大多数 lint 和格式问题），反复运行直至通过，然后推送。

3. （可选）在每次提交时自动运行

要让相同的检查在每次 git commit 时运行，请安装一次 git 钩子：

uv run prek install

更多详情请参阅我们的贡献指南。

许可证

Apache-2.0