Code Context V2

Semantic code search for CLI-driven agent workflows. Index your codebases, search with natural language, get precise results.

专为本地代理工作流而构建 克劳德代码 以及类似的CLI环境。

为什么

LLM在正确的环境中工作得更好。Grep找到文本；这发现 意义.请求“身份验证中间件”并获取实际的身份验证逻辑，而不是每个提到“auth”的文件。

它是如何工作的：

1. 索引 使用树型AST解析的代码库（函数、类、方法——不是任意的行分割）
2. 嵌入 与Voyage AI合作(voyage-4-large 对于文档， voyage-4-lite 对于查询——相同的嵌入空间，非对称检索）
3. 搜索 使用时默认为PostgreSQL/pgvector+pgvectorscale .env.example （或嵌入LanceDB/SQLite替代方案），然后 rerank-2.5 为了精确
4. 查询 使用语义搜索命令从CLI索引内容

建筑

Agent / CLI
    │
    ├── cc2.sh
    └── uv run code-context-manage
             │
      RetrievalPipeline
        │            │
        ▼            ▼
   Voyage AI    local vector store
 voyage-4-lite  Postgres/pgvector
  (query embed) LanceDB/SQLite fallback
 rerank-2.5
  (reranking)

回收管道：

1. 嵌入查询 voyage-4-lite （带有索引文档的快速共享空间）
2. 从嵌入式LanceDB、实验性SQLite+FTS5+SQLite-vec检索候选者(CC2_CODE_BACKEND=sqlite)，或PostgreSQL/pgvector(CC2_CODE_BACKEND=postgres)
3. 重新排名： rerank-2.5 +相对阈值(max(score_floor, top_score * factor))
4. 重复：重叠/包含+Jaccard相似性过滤
5. 返回：带有文件路径、行号、相关性得分的Markdown格式块

代码布局：

• src/code_context/retrieval/ --检索外观加上用于意图解析、结果控制、跨文件上下文和质量日志记录的专注助手
• src/code_context/db/ — DatabasePool facade将代码、项目、内存和书籍委托给特定领域的存储
• src/code_context/chunking/ --树保姆解析、块模型和后处理/拆分助手
• src/code_context/indexing/ --文件系统和索引支持助手 Indexer
• src/code_context/cli/ --面向用户的入口点加上共享的运行时/搜索/同步/观察者帮助程序

公共API主要集中在 RetrievalPipeline, DatabasePool, Indexer，以及CLI入口点；内部模块被分开，以保持这些表面的稳定，同时减少耦合。

快速开始

先决条件

• 紫外线 （Python包管理器）
• Voyage AI API键 （免费版可用）
• 码头工人 只有当你选择进入PostgreSQL支持的内存/书籍/遗留代码搜索时

1.克隆和配置

git clone https://github.com/YOUR_USER/code-context-v2.git
cd code-context-v2

cp .env.example .env
# Edit .env — set CC2_VOYAGE_API_KEY

推荐的本地后端是PostgreSQL/pgvector+pgvectorscale通过Docker(CC2_CODE_BACKEND=postgres)，在上使用compose服务 127.0.0.1:25432嵌入式LanceDB仍然可用作无Docker回退，实验性SQLite+FTS5+SQLite-vec可用于 CC2_CODE_BACKEND=sqlite.

PostgreSQL数据存储在外部Docker卷中 code-context-pgdata，安装在图像的活动位置 PGDATA 路径(/home/postgres/pgdata/data).这可以保护cc2索引免受正常的组合生命周期命令的影响，包括 docker compose down -v。不要用以下方式卸下音量 docker volume rm code-context-pgdata 除非您有意删除索引。跑 scripts/backup_cc2_postgres.sh 创建压缩文件 pg_dump 备份下 ~/.local/share/cc2/backups/postgres.

2.安装依赖项

uv sync

3.为项目编制索引

uv run code-context-manage --index /path/to/your/project

4.使用搜索命令

使用Python直接入口点或shell包装器：

# List indexed projects
uv run code-context-manage --list

# Semantic search from inside an indexed repo (project inferred from cwd)
./cc2.sh search "auth middleware"

# Explicit project override when running outside the repo or targeting another project
./cc2.sh search "auth middleware" -p my-project

# Opt in to graph expansion from dense chunk hits
./cc2.sh search "auth middleware" -p my-project --graph

# Search within one file (also infers project from cwd)
./cc2.sh search-file src/auth.ts "token validation"

# Search indexed literature
./cc2.sh search-lit "dependency injection"

搜索控件

CLI搜索命令支持可选的输出整形控件：

代理工作流的推荐默认值：

• 保持 include_tests=false 除非用户明确询问测试。
• 从...开始 --max-tokens 之间 1800 和 3200 用于典型的编码任务。
• 使用 --json 当另一个工具或代理对结果进行后处理时。

项目决议

对于CLI代码搜索命令， -p/--project 当您当前的工作目录位于索引项目根目录内时，它是可选的。

• cc2.sh 将调用者cwd传递给Python CLI。
• cc2通过查找索引来解决项目 project_root 其中包含cwd。
• 如果多个索引根匹配，cc2将选择最长的匹配根。
• 使用 -p 在仓库外运行时，针对另一个索引项目，或覆盖基于cwd的解析。

搜索意向指南

使用 --intent 控制重新分级精度：

默认意图为 implementation 当省略时。

基准测试

检索更改应使用可用的本地基准套件进行测量。套件定义已上线 benchmarks/retrieval/*.json，但这些JSON文件会被忽略，因为它们经常引用本地索引项目ID和私有存储库路径。

# List local benchmark-enabled projects
uv run python -m scripts.benchmark_retrieval --list

# Run one local project suite
uv run python -m scripts.benchmark_retrieval my-project

# Compare against a saved local baseline
uv run python -m scripts.benchmark_retrieval my-project --compare baseline-v1

# Run all local benchmark suites and save a combined baseline
uv run python -m scripts.benchmark_retrieval all --save hybrid-v1

# Run with graph expansion enabled
uv run python -m scripts.benchmark_retrieval my-project --graph

# A/B compare dense-only vs dense + graph expansion in one run
# Prints graph-derived candidate/final counts, added/removed expected files,
# worsened top results, surviving edge types, and token impact.
uv run python -m scripts.benchmark_retrieval my-project --compare-graph

看 benchmarks/retrieval/README.md 对于本地套件模式。

命令行界面

# Index a project (auto-generates ID from folder name)
uv run code-context-manage --index /path/to/project

# Index with custom ID
uv run code-context-manage --index /path/to/project --id my-project

# Check what changed (dry-run)
uv run code-context-manage --check my-project

# Sync only changed files
uv run code-context-manage --sync my-project

# Force full reindex
uv run code-context-manage --index /path/to/project --force

# Show statistics
uv run code-context-manage --stats

# Watch for changes (background daemon)
uv run code-context-manage --watch /path/to/project

# List indexed books
uv run code-context-manage --list-books

# Initialize additive graph tables (does not reindex code)
uv run code-context-manage graph init

# Build the phase-1 graph from the existing code index
uv run code-context-manage graph build --project my-project
uv run code-context-manage graph build --project my-project --phase existing-index

# Add Phase 2 deterministic source relations incrementally (no code reindex)
uv run code-context-manage graph build --project my-project --phase deterministic

# Check graph backfill status and edge counts by type
uv run code-context-manage graph status --project my-project

# Create a project memory root with a MEMORY.md hub
./cc2.sh memory init

# Index a Markdown memory root
./cc2.sh memory index .pi/memory --project my-project

# Search indexed memory
./cc2.sh memory search "refresh token rotation" --project my-project

独立内存入口点也存在：

uv run code-context-memory init
uv run code-context-memory index .pi/memory --project my-project
uv run code-context-memory search "refresh token rotation" --project my-project

看 docs/memory.md 对于存储器布局， MEMORY.md 集线器模式和过滤器。

有关完整的文档索引，请参阅 docs/README.md.

还有 cc2.sh --一个bash包装器，带有基于gum的TUI和非交互式命令，如 search, search-file，以及 search-lit.

支持的语言

添加新语言需要在中使用树型语法和块类型映射 src/code_context/chunking/parser.py.

配置

所有设置都使用 CC2_ 通过环境变量或存储库添加前缀 .env 文件：

看 src/code_context/config.py 对于所有可用设置。

演出

• 矢量搜索： \<50ms
• 重新排名： \<100ms
• CLI搜索响应总数： \<200ms
• 初始索引： 1000个文件大约需要5-10分钟
• 增量同步： 每个更改的文件\<2s
• 储存： 每100k块约100MB

索引如何工作

1. 浏览项目树（跳过 node_modules, vendor, .git, distLaravel运行时/生成的dirs等）
2. 使用BLAKE3对每个文件进行哈希处理——跳过未更改的文件
3. 使用树状图将其解析为语义块（函数、类、方法）
4. 小文件（\<200行）仍然提取符号级块；当符号块存在时，通用文件块会被丢弃
5. 嵌入块 voyage-4-large 分批
6. 将块元数据和向量存储在所选后端； .env.example 使用PostgreSQL/pgvector，并提供LanceDB和SQLite替代方案
7. 文件重新索引操作在添加新块之前替换旧块；重播 cc2 sync 如果中断的流程使项目部分索引

支持的代码语言包括TypeScript、JavaScript、Python、Java、Go、Rust、SQL、PHP和Vue单文件组件。PHP文件获取类/函数/方法块；Vue SFC被索引为文件级块。

Laravel默认跳过Composer依赖关系、运行时/缓存输出、构建的前端资产、PHPUnit缓存文件、Pi/本地MCP划痕和生成的Wayfinder路线/动作文件。

发展

该项目使用uv进行依赖管理，使用Ruff进行linting。ty仅被配置为在迁移现有类型积压时发出快速类型检查信号的警告。

uv sync --dev
uv run ruff check .
uv run ty check
uv run pytest

维护者和编码代理指南 AGENTS.md.

许可证

麻省理工学院