内容
# 代码范围
[](https://crates.io/crates/codescope)
[](#license)
[](https://github.com/adventurewave-labs/codescope/actions)
> ⭐ 如果codescope为您节省了上下文令牌，[给仓库点赞](https://github.com/adventurewave-labs/codescope)可以帮助其他人发现它。
**一款单二进制文件、极速的代码智能引擎，适用于AI编码代理。**
`codescope`将任何仓库索引到一个精确的、可查询的结构化图，并通过 **MCP** （和CLI/JSON）为AI代理提供服务。 与其让代理在文件中进行盲目搜索，浪费上下文窗口，不如在毫秒内回答 *"谁调用这个，改变它会破坏什么，它在哪里定义，这个模块依赖什么"* —— 输出符合 **token-budget**。
其精度媲美Sourcegraph，安装 footprint 类似 ripgrep，接口类似 MCP 服务器，而且无需云服务、无需数据库、无需 Python。
## 演示
> 📹 **演示GIF即将到来。** 使用[`vhs`](https://github.com/charmbracelet/vhs)或`asciinema` + [`agg`](https://github.com/asciinema/agg）捕获：运行 `codescope index` 然后 `codescope callers <symbol>` 以显示结构化查询。
## 功能
| 功能 | CLI | MCP 工具 |
|---|---|---|
| 构建/刷新索引（增量） | `codescope index` | `cs_index` |
| 谁调用一个符号（传递） | `codescope callers X --depth N` | `cs_callers` |
| 一个符号调用什么（传递） | `codescope callees X --depth N` | `cs_callees` |
| 更改的爆炸半径 | `codescope blast-radius X` | `cs_blast_radius` |
| 符号定义位置 | `codescope def X` | `cs_definition` |
| 符号的所有引用 | `codescope refs X` | `cs_references` |
| 文件/模块导入图 + 环 | `codescope deps` | `cs_dependency_graph` |
| 结构化搜索 | `codescope search "kind:function calls:db_query"` | `cs_structural_search` |
| 架构概述 | `codescope summary` | `cs_repo_summary` |
**语言：** Rust、TypeScript、JavaScript、Python、Go（tree-sitter）。
每个查询都是 **token-budgeted** （ `--max-tokens`，默认为4000）：结果是紧凑的JSON，包含 `symbol`、`kind`、`file`、`line_start/line_end`、边列表和 `truncated` 标志，而不是转储整个图。
## 安装
```sh
cargo install --path . # from this checkout
# 或，一旦发布：
# cargo install codescope
```
## 使用
```sh
codescope index # 为当前工作目录构建/刷新索引
codescope -p /path/to/repo index # 索引特定仓库
codescope callers my_func --depth 2
codescope blast-radius src/auth.rs
codescope refs UserSession
codescope summary --max-tokens 4000
codescope search "kind:function calls:db.query returns:Result"
codescope callees do_thing --json # 可机器读取的输出
```
### 结构化搜索
空格分隔的术语； `key:value` 是过滤器，裸词匹配名称/签名：
- `kind:function|method|struct|enum|trait|interface|class|module|type|constant|field`
- `lang:rust|typescript|javascript|python|go`
- `file:<substr>` · `name:<substr>` · `calls:<callee>` · `returns:<type-substr>`
```sh
codescope search "kind:method lang:rust calls:spawn returns:Result"
```
## MCP 服务器（适用于代理）
`codescope` 通过 stdio （换行符分隔的 JSON-RPC）支持 MCP。 使用以下命令启动它：
```sh
codescope serve --mcp
```
将其注册到任何支持MCP的代理（Claude Code、Cursor、Windsurf、VS Code/Copilot、Cline、Zed、Continue）。 示例配置：
```json
{
"mcpServers": {
"codescope": {
"command": "codescope",
"args": ["serve", "--mcp", "-p", "/abs/path/to/your/repo"]
}
}
}
```
然后代理可以调用 `cs_index` 一次并查询 `cs_callers`、`cs_blast_radius`、`cs_structural_search` 等。 有关完整的工具参考，请参见 [`docs/mcp.md`](docs/mcp.md)。
## 性能
在 4 核容器（发布构建）上测量 - 参见 [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md)：
- 冷索引 **100k LOC 约 0.2 秒**； **~1M LOC 约 1.6 秒**。
- 单个更改文件的增量重新索引，耗时 **~55 毫秒**。
- 进程内查询延迟 **< 2 毫秒**，适用于每种查询类型。
- 磁盘索引大小是未达到的 PRD 目标之一（~75% vs. <15%）；原因和补救措施在基准测试文档和 ADR-0005 中有诚实的记录。
## 工作原理
```
仓库 → Walker（忽略感知）→ tree-sitter 解析器 → 符号/边提取
→ CodeGraph（内存中，索引）→ redb（嵌入式，磁盘上）
→ 查询 API → CLI / JSON / MCP
```
- **解析：** tree-sitter（强大的错误恢复，增量）。
- **解析：** 两层 —— 现在快速的 tree-sitter 名称/作用域启发式（标记为 `heuristic`），并设计了 SCIP 精确度层（标记为 `precise`）。
- **存储：** 嵌入式、单文件、内存映射 redb。 无外部数据库。
- **并发：** 使用 rayon 进行并行解析/提取。
## 文档
- **架构决策记录：** [`docs/adr/`](docs/adr/) （14 个 ADR）。
- **领域驱动设计：** [`docs/ddd/`](docs/ddd/) —— 普遍语言、有界上下文、领域模型、服务和仓库。
- **基准测试和验证：** [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md)。
- **产品需求：** [`plans/codescope.prd`](plans/codescope.prd)。
## 生态系统
| 仓库 | 功能 |
|------|-------------|
| [**secret-scan**](https://github.com/adventurewave-labs/secret-scan) | Rust 秘密扫描器 — 51k 文件/秒，99% 准确率，混淆检测 |
| [**Sentinel**](https://github.com/marcuspat/Sentinel) | 默认拒绝的代理系统管理员：调查 → 计划 → 批准 → 执行 |
| [**spacelift-intent**](https://github.com/marcuspat/spacelift-intent) | 自然语言 → 云基础设施，通过 Terraform 提供商，无 HCL |
| [**turbo-flow**](https://github.com/adventurewave-labs/turbo-flow) | 代理开发环境 — 600+ AI 子代理，SPARC 方法论 |
## 许可证
在 [MIT](LICENSE-MIT) 或 [Apache-2.0](LICENSE-APACHE) 下双重许可，您可任选其一。
