codeindex

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

codeindex - Semantic Code Search & Indexing

codeindex - 语义代码搜索与索引

codeindex

is a semantic code search CLI that indexes codebases and provides fast, concept-based search over the current project.

codeindex

是一款语义代码搜索CLI工具，可对代码库建立索引，并为当前项目提供基于概念的快速搜索功能。

Ownership

所有权

The agent owns the

codeindex

lifecycle for the current project — initialization, indexing, and searching. Do not ask the user to perform these steps; handle them automatically.

Initialization: If
```
codeindex search
```
or
```
codeindex index
```
fails with an initialization error (e.g., "Not in an initialized project directory"), run
```
codeindex init
```
from the project root directory, then
```
codeindex index
```
to build the index, then retry the original command.
Index freshness: Keep the index up to date by running
```
codeindex index
```
when the index may be stale — e.g., at the start of a session, or after making significant code changes (new files, refactors, renamed modules). There is no need to re-index between consecutive searches if no code was changed in between.
Installation: If
```
codeindex
```
itself is not found (command not found), refer to management.md for installation instructions and inform the user.

Agent 负责当前项目中

codeindex

的生命周期——初始化、索引和搜索。请勿要求用户执行这些步骤；请自动处理。

初始化：如果
```
codeindex search
```
或
```
codeindex index
```
因初始化错误（例如“Not in an initialized project directory”）失败，请从项目根目录运行
```
codeindex init
```
，然后运行
```
codeindex index
```
构建索引，之后重试原命令。
索引新鲜度：当索引可能过期时（例如会话开始时，或进行重大代码变更后，如新增文件、重构、重命名模块），运行
```
codeindex index
```
以保持索引最新。如果两次连续搜索之间没有修改代码，则无需重新索引。
安装：如果未找到
```
codeindex
```
（command not found），请参考 management.md 获取安装说明并告知用户。

Searching the Codebase

搜索代码库

To perform a semantic search:

bash

codeindex search <query terms>

To perform a sematic search filter by path:

bash

codeindex search -path . "authentication logic"

Note: Flags must precede the query string.

The query should describe the concept, functionality, or behavior to find, not exact code syntax. For example:

bash

codeindex search database connection pooling
codeindex search user authentication flow
codeindex search error handling retry logic

执行语义搜索：

bash

codeindex search <query terms>

按路径过滤执行语义搜索：

bash

codeindex search -path . "authentication logic"

注意：标志必须位于查询字符串之前。

查询应描述要查找的概念、功能或行为，而非确切的代码语法。例如：

bash

codeindex search database connection pooling
codeindex search user authentication flow
codeindex search error handling retry logic

Filtering Results

过滤结果

By language (
```
-lang
```
): restrict results to specific languages (comma-separated).
bash
```
codeindex search -lang python,markdown database schema
```
By path (
```
-glob
```
): restrict results to files matching glob patterns (comma-separated).
bash
```
codeindex search -glob 'src/api/**' request validation
```
Limit results (
```
-limit
```
): maximum number of results (default: from config
```
search_limit
```
).
bash
```
codeindex search -limit 10 database schema
```
Files only (
```
-files
```
): show only file paths and metadata without content.
bash
```
codeindex search -files database schema
```
Hybrid search (
```
-hybrid
```
): combine vector embeddings with keyword matching (TF-IDF) for better precision with technical terms.
bash
```
codeindex search -hybrid "EmbeddingProvider interface"
```
Score threshold: Results below
```
score_threshold
```
(from config) are automatically filtered out.

Hybrid Search:

Hybrid search combines semantic vector search with keyword matching:

Vector search: Understands semantic meaning ("database connection" → connection pooling code)
Keyword matching: Finds exact terms ("EmbeddingProvider" → exact interface name)

Combined score:

vector_weight * vector_score + keyword_weight * keyword_score

Enable in config:

json

{
  "hybrid_search": true,
  "vector_weight": 0.7,
  "keyword_weight": 0.3
}

Or use per-query with

-hybrid

flag.

按语言 (
```
-lang
```
)：将结果限制为特定语言（逗号分隔）。
bash
```
codeindex search -lang python,markdown database schema
```
按路径 (
```
-glob
```
)：将结果限制为匹配glob模式的文件（逗号分隔）。
bash
```
codeindex search -glob 'src/api/**' request validation
```
限制结果数量 (
```
-limit
```
)：结果的最大数量（默认值：来自配置
```
search_limit
```
）。
bash
```
codeindex search -limit 10 database schema
```
仅显示文件 (
```
-files
```
)：仅显示文件路径和元数据，不显示内容。
bash
```
codeindex search -files database schema
```
混合搜索 (
```
-hybrid
```
)：将向量嵌入与关键词匹配（TF-IDF）相结合，提高技术术语的搜索精度。
bash
```
codeindex search -hybrid "EmbeddingProvider interface"
```
分数阈值：低于配置中
```
score_threshold
```
的结果会被自动过滤掉。

混合搜索：

混合搜索结合了语义向量搜索与关键词匹配：

向量搜索：理解语义含义（例如“database connection”会找到连接池代码）
关键词匹配：查找确切术语（例如“EmbeddingProvider”会找到确切的接口名称）

综合分数：

vector_weight * vector_score + keyword_weight * keyword_score

在配置中启用：

json

{
  "hybrid_search": true,
  "vector_weight": 0.7,
  "keyword_weight": 0.3
}

或在每次查询时使用

-hybrid

标志。

Pagination

分页

Results default to the first page (limit: 5). To retrieve additional results:

bash

codeindex search -offset 5 -limit 5 database schema

If all returned results look relevant, use

-offset

to fetch the next page — there are likely more useful matches beyond the first page.

结果默认显示第一页（限制：5条）。要获取更多结果：

bash

codeindex search -offset 5 -limit 5 database schema

如果返回的所有结果看起来都相关，请使用

-offset

获取下一页——第一页之外可能还有更多有用的匹配项。

Working with Search Results

处理搜索结果

Search results include file paths and line ranges. To explore a result in more detail:

Use the editor's built-in file reading capabilities (e.g., the
```
Read
```
tool) to load the matched file and read lines around the returned range for full context.
When working in a terminal without a file-reading tool, use
```
sed -n '<start>,<end>p' <file>
```
to extract a specific line range.

搜索结果包含文件路径和行范围。要更详细地查看结果：

使用编辑器内置的文件读取功能（例如
```
Read
```
工具）加载匹配的文件，并读取返回范围周围的行以获取完整上下文。
在没有文件读取工具的终端中，使用
```
sed -n '<start>,<end>p' <file>
```
提取特定行范围。

Settings

设置

To view or edit embedding model configuration, include/exclude patterns, or language overrides, see settings.md.

要查看或编辑嵌入模型配置、包含/排除模式或语言覆盖设置，请参阅 settings.md。

Management & Troubleshooting

管理与故障排除

For installation, initialization, troubleshooting, and cleanup commands, see management.md.

有关安装、初始化、故障排除和清理命令，请参阅 management.md。