内容
# 代码范围 — 项目真实性引擎
**代码范围不理解代码。它验证代码。**
它将源代码转换为可验证的事实、可理解的模型和可检查的证据，使人工智能能够根据现实验证声明，而不是产生幻觉。
**版本**: v0.2.1 | **许可证**: Apache 2.0
---
## 1. 什么是代码范围？
代码范围是一个 **项目真实性引擎**，它回答一个问题：
> **"代码是否真正实现了你所声称的功能？"**
不是“这段代码是什么意思”，而是“代码是否真正实现了你所声称的功能？”
它将源代码索引到一个结构化的代码图（调用图 + 引用图 + 模块知识），然后公开 **37 个 MCP 工具**，让 AI 代理可以定位符号、跟踪调用路径、验证声明、检测文档漂移和分析架构 — 所有这些都与 **~98.9% 的 token 节省** 相比于读取原始源文件。
### 支持的语言（8种）
| 语言 | 解析器 | IR 翻译器 | 已验证 |
| --- | --- | --- | --- |
| Python | ✅ | ✅ | ✅ |
| Go | ✅ | ✅ | ✅ |
| C | ✅ | ✅ | ✅ |
| C++ | ✅ | ✅ | ✅ |
| Rust | ✅ | ✅ | ✅ |
| JavaScript | ✅ | ✅ | ✅ |
| TypeScript | ✅ | ✅ | ✅ |
| Java | ✅ | ✅ | ✅ |
### 技术栈
| 层 | 技术 |
| --- | --- |
| 解析器 | tree-sitter（统一 AST IR，8 种语言） |
| 索引器 | C++23（Clang 17+），SQLite（WAL 模式，FTS5） |
| 服务器 | Rust 2024 版，MCP 协议（JSON-RPC 2.0，stdio 传输） |
| 图形存储 | SQLite（主要）+ 可选 LadybugDB（Cypher 查询） |
| 调度器 | 内置多进程并行索引器（块级工作窃取） |
| 构建 | CMake 3.30+（C++），Cargo（Rust） |
---
## 2. 架构
```mermaid
graph TB
subgraph "AI 客户端"
Client["Claude Desktop / Cursor / 任意 MCP 客户端"]
end
subgraph "Rust MCP 服务器"
MCP["MCP 协议（JSON-RPC 2.0）<br/>37 种工具 / stdio 传输"]
DISPATCH["工具调度<br/>project_id 自动恢复"]
end
subgraph "C++ 核心引擎"
PARSER["解析器<br/>tree-sitter → 统一 IR<br/>8 种语言"]
FACTS["事实仓库<br/>实体 / 引用 / 范围 / 导入"]
RESOLVER["解析器管道<br/>约束链"]
MODEL["模型引擎<br/>工作流 / 能力 / 架构 / 合同"]
INSPECTOR["检查器<br/>死代码检查器 / 验证完整性"]
end
subgraph "SQLite（WAL 模式）"
F_STORE["事实存储<br/>实体 / 引用 / 范围 / 导入"]
S_STORE["语义存储<br/>已解析引用 / 关系"]
M_STORE["模型存储<br/>工作流 / 能力 / 架构 / 合同"]
E_STORE["证据存储<br/>声明 / 证据 / 发现"]
end
Client -->|"MCP stdio"| MCP
MCP --> DISPATCH
DISPATCH -->|"FFI"| PARSER
DISPATCH -->|"FFI"| FACTS
DISPATCH -->|"FFI"| RESOLVER
DISPATCH -->|"FFI"| MODEL
DISPATCH -->|"FFI"| INSPECTOR
PARSER -->|"写入"| F_STORE
F_STORE -->|"读取"| RESOLVER
RESOLVER -->|"写入"| S_STORE
S_STORE -->|"读取"| MODEL
MODEL -->|"写入"| M_STORE
M_STORE -->|"读取"| INSPECTOR
INSPECTOR -->|"写入"| E_STORE
```
### 管道
```
源代码
|
v
解析器 ------------ 实体 / 引用 / 范围 / 导入
|
v
解析器 ---------- 已解析引用 / 关系
|
v
模型引擎 ------ 工作流 / 能力 / 架构 / 合同
|
v
检查器 --------- 证据 / 发现
```
### 查询流程
```mermaid
flowchart LR
Q["MCP 客户端<br/>工具调用"] --> Q1["服务器接收<br/>project_id 自动恢复"]
Q1 --> Q2{"工具类型？"}
Q2 -->|"index_project"| Q3["启动工作进程<br/>→ 内存隔离<br/>→ 完成后退出"]
Q2 -->|"查询工具"| Q4["C++ FFI → SQLite 查询<br/>图节点，图边<br/>搜索索引，..."]
Q2 -->|"获取社区"| Q5["加载完整图<br/>标签传播<br/>→ JSON，最大社区限制"]
Q2 -->|"获取热点"| Q6["SQL：COUNT（ge.id）JOIN<br/>图边 edge_type=1<br/>ORDER BY 调用者计数"]
Q4 --> R["结果 JSON<br/>返回给 MCP 客户端"]
Q5 --> R
Q6 --> R
```
### 两阶段索引
```mermaid
flowchart LR
subgraph A["阶段 A：快速扫描（毫秒级）"]
S1["扫描项目"]
S2["总符号"]
S3["模块树"]
S4["入口点"]
end
subgraph B["阶段 B：后台增强（异步，秒级）"]
E1["增强项目"]
E2["完整树解析"]
E3["调用图"]
E4["复杂度指标"]
E5["嵌入 + FTS"]
end
A -->|"触发"| B
```
---
## 3. 快速入门
### prerequisites
| 平台 | 依赖项 |
| --- | --- |
| **macOS** | Xcode CLT，cmake，Rust（1.85+） |
| **Linux** | build-essential，cmake，Rust（1.85+） |
### 安装预构建二进制文件
```bash
curl -fsSL https://raw.githubusercontent.com/Timwood0x10/CodeScope/main/install.sh | bash
export PATH="$PATH:$HOME/.codescope/bin"
```
> **macOS 代码签名问题**：如果二进制文件在启动时立即被终止（退出代码 137 / SIGKILL），请本地重新签名：
> ```bash
> codesign --sign - --force ~/.codescope/bin/codescope
> ```
> 这是因为 CI 构建的二进制文件使用临时签名，新版本的 macOS 可能会拒绝。本地重新签名可以解决这个问题。
### 从源代码构建
```bash
git clone https://github.com/Timwood0x10/CodeScope.git
cd CodeScope
# macOS:
brew install llvm@21 cmake pkg-config
cargo build --release
# Linux (Ubuntu):
sudo apt-get install -y build-essential cmake llvm-dev libclang-dev
cargo build --release
```
### 索引和查询
```bash
# 索引一个项目
codescope cli index_project '{"project_path":"/path/to/your/project"}'
# 快速概览
codescope cli project_overview '{}'
# 启动 MCP 服务器（用于 AI 客户端）
codescope
```
### 大型项目
对于有成千上万个文件的项目，请使用内置的并行调度器：
```bash
codescope index-parallel /path/to/large/project
```
---
## 4. MCP 工具（37 种工具）
### 索引
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| `index_project` | 索引项目目录：解析所有源文件，构建 IR，并构造代码图。 | `{"project_path": "string (required)", "language_filter": "string (optional)"}` |
| `index_file` | 索引单个源文件。 | `{"file_path": "string (required)"}` |
| `force_index_files` | 强制索引文件/目录，绕过默认跳过规则（test/，docs/，node_modules/，.gitignore 等）。 | `{"paths": ["string (required)"], "language_filter": "string (optional)"}` |
### 项目概览
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| `project_overview` | **主要** — 全面的项目概览：语言、模块、符号、入口点、分析进度。 | `{}` |
| `get_graph_stats` | 快速统计：节点、边、文件。 | `{}` |
| `get_module_tree` | 分层模块/目录树。 | `{}` |
| `get_entry_points` | 查找入口点（main/init/setup/run/handler）。 | `{}` |
| `get_routes` | 获取已注册的 HTTP 路由（Gin/Echo/Chi/net/http）。 | `{}` |
| `get_type_info` | 查询类型定义（struct/enum/trait）及其引用计数。 | `{"type_name": "string (optional)"}` |
### 符号查找
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| `find_symbol` | **推荐** — 按确切名称（种类、文件、行/列）查找符号。 | `{"symbol_name": "string (required)"}` |
| `find_references` | 查找所有引用某个符号的位置。 | `{"symbol_name": "string (required)", "file_filter": "string (optional)"}` |
| `explain_symbol` | 获取综合符号信息：定义、调用者、被调用者、依赖项。 | `{"symbol_name": "string (required)"}` |
| `find_definition` | [已弃用 — 使用 find_symbol] | `{"symbol_name": "string (required)"}` |
### 调用图
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| `find_callers` | 查找调用某个函数的函数。 | `{"symbol_name": "string (required)", "file_filter": "string (optional)"}` |
| `find_callees` | 查找某个函数调用了哪些函数。 | `{"symbol_name": "string (required)", "file_filter": "string (optional)"}` |
| `codescope_trace` | 交互式递归调用探索（深度 + 方向）或最短路径。 | `{"function_name": "string", "depth": "integer (default 1, max 5)", "direction": "callers|callees|both", "from": "string", "to": "string"}` |
| `trace_flow` | 递归执行流跟踪（caller→callee 链）。 | `{"function_name": "string (required)", "depth": "integer (default 3, max 10)"}` |
| `shortest_path` | 两个函数之间的最短调用路径（BFS）。 | `{"from": "string", "to": "string", "from_id": "integer", "to_id": "integer"}` |
| `connected_components` | 调用图中的连通分量。 | `{}` |
### 图查询
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| `graph_query` | 类似 Cypher 的 DSL 查询：`MATCH (Function:main)-[Calls]->(Method)`。 | `{"dsl": "string (required)"}` |
| `get_graph` | 以分页页面形式检索完整的代码图。 | `{"node_offset": "integer", "node_limit": "integer (max 50000)", "edge_offset": "integer", "edge_limit": "integer (max 200000)", "node_types": "string", "edge_types": "string"}` |
| `get_subgraph` | 获取以节点为中心的本地区域（1-跳）。 | `{"node_id": "integer (required)", "radius": "integer", "node_types": "string", "edge_types": "string"}` |
| `get_neighbors` | 获取图节点的直接邻居（调用者 + 被调用者）。 | `{"node_id": "integer (required)", "edge_type": "integer (default -1)", "radius": "integer"}` |
### 搜索
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| `search` | **推荐** — 统一搜索（自动选择 FTS5 或语义）。 | `{"query": "string (required)", "limit": "integer (default 20, max 100)"}` |
| `search_code` | [已弃用 — 使用 search] | `{"query": "string (required)", "limit": "integer"}` |
### 验证
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| `verify_integrity` | 检查 README 中承诺的功能是否实际存在于代码中。 | `{}` |
| `verify_claim` | 验证单个声明（capability_exists / contract_holds / architecture_follows）。 | `{"claim": "string (required)"}` |
| `verify_summary` | 解析自然语言摘要并验证每个声明。 | `{"text": "string (required)"}` |
| `verify_review` | 验证代码审查评论声明。 | `{"text": "string (required)"}` |
| `verify_reality` | 验证单个 AI 声明是否与代码证据相符。 | `{"text": "string (required)"}` |
### 漂移检测
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| `detect_drift` | 扫描所有声明的能力和合约，检查文档与代码的漂移。 | `{}` |
| `detect_documentation_drift` | 检查 README 语言声明与实际代码实体是否一致。 | `{}` |
| `detect_capability_drift` | 检查声明的能力是否有实现实体。 | `{}` |
| `detect_architecture_drift` | 检查调用边是否存在层级违规（Repository→Controller）。 | `{}` |
### 影响和模块
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| `detect_changes` | 分析修改文件的 impact：直接/间接调用者。 | `{"modified_files": "string (required)"}` |
| `explain_module` | 构建模块知识卡：实体、能力、完整性得分。 | `{"module_name": "string (required)"}` |
### 实用工具
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| `detect_ffi_boundaries` | 检测 FFI 边界（extern/C、JNI、WASM、C ABI）。 | `{}` |
| `count_tokens` | 估计 token 计数（DeepSeek 公式）。 | `{"text": "string (required)"}` |
### 快速决策指南```
新项目 → project_overview
模块结构 → get_module_tree
入口点 → get_entry_points
搜索代码 → search
调用链 → find_callers / find_callees
深入符号 → explain_symbol
HTTP 路由 → get_routes
类型信息 → get_type_info
验证声明 → verify_claim
检测漂移 → detect_documentation_drift
影响 → detect_changes`
---
## 5. 知识图
代码范围构建 **模块级知识图** 作为验证管道的副产品。它学习有关项目组织结构、什么重要、什么冗余以及承诺的内容：
| 层 | 表 | 它告诉你 |
| --- | --- | --- |
| **调用图** | `relation`, `architecture_edge` | 跨模块调用依赖；驱动 `detect_architecture_drift` |
| **模块健康** | `module_summary` | 每模块 `incoming_count` / `outgoing_count` / `dead_entities` / `utilization` / `role` |
| **模块依赖** | `architecture_edge`, `module_edge` | “更改模块 A → 这些模块依赖于它” |
| **已文档化的功能** | `capability` + `document` | README 中提取的功能；驱动 `detect_capability_drift` / `verify_claim` |
所有知识层级的表格都可以通过 `get_knowledge_graph` 直接查询：
```jsonc
get_knowledge_graph {"table":"architecture_edge","limit":5}
// → {"table":"architecture_edge","rows":[...],"total":3351}
get_knowledge_graph {"table":"capability","limit":10}
// → {"table":"capability","rows":[...],"total":3}
```
## 6. 基准测试
所有基准测试均在 **Apple M3 Max（36 GB RAM）** 上进行。其他硬件将产生不同的结果 — 请期待在性能较差的机器上运行速度变慢。
### 索引时间
| 项目 | 文件 | 节点 | 索引时间 | 峰值 RSS |
| --- | ---: | ---: | ---: | ---: |
| **CodeScope** (自身，C++/Rust) | 168 | 1,001 | **1.3 秒** | ~150 MB |
| **memscope-rs** (Rust) | 215 | 4,344 | **~2 秒** | ~200 MB |
| **ARES_POLIS** | 105 | 1,531 | **~2 秒** | ~180 MB |
| **goagent** (Go) | 2,651 | 155K | **30 秒** | — |
| **rustc** (Rust 编译器，单体仓库) | 6,029 | 81,033 | **81 秒** | 5.9 GB |
| **Linux 内核** (完整) | 64,694 | 12M | **3 分 07 秒** | — |
### 微基准测试
| 指标 | 值 |
| --- | --- |
| 引擎初始化 | **14.6 毫秒** |
| 索引吞吐量 | **1,533 KB/s** |
| 符号定义查询 | **0.01–0.03 毫秒** |
| 调用者/被调用者查询 | **0.01–0.02 毫秒** |
| 9 次查询（总数） | **0.17 毫秒** |
| 查询延迟（stdio MCP，包括进程启动） | **~60 毫秒** |
### 跨文件解析
| 项目 | 跨文件调用 | 总调用的百分比 |
| --- | ---: | ---: |
| CodeScope (C++) | 23 | 0.1% |
| goagent (Go) | 49,258 | 86% |
| Linux 内核 (C) | 1,502,432 | 40% |
### 快速扫描（轻量级，毫秒级）
| 项目 | 时间 | 语言 | 符号 |
| --- | ---: | ---: | ---: |
| **CodeScope** (自身) | **32 毫秒** | cpp, rust, c | 2,902 |
| **goagent** (Go) | **493 毫秒** | go, c, cpp, python | 5,172 |
| **Linux 内核** (核心) | **360 毫秒** | c | 40,335 |
### token 节省
使用代码图代替原始源文件可节省 **~98.9% token**：
| 场景 | 原始源代码 | CodeScope | 节省 |
| --- | ---: | ---: | ---: |
| 查找函数定义 | ~2,265 tokens | ~21 tokens | **99.1%** |
| 跟踪函数调用者 | ~2,000 tokens | ~18 tokens | **99.1%** |
| 项目架构概览 | ~1,875 tokens | ~32 tokens | **98.3%** |
| USB 子系统概览 | ~24,000 tokens | ~250 tokens | **99.0%** |
| 调度器分析 | ~15,000 tokens | ~180 tokens | **98.8%** |
---
## 7. 技能（Shell 包装器）
`skills/` 目录提供 shell 脚本，封装常见的 CodeScope 查询，这样你就不需要记住 JSON 模式：
```bash
cd CodeScope
# 索引一个项目
./skills/index.sh ~/path/to/project
# 一次性完整分析报告
./skills/analyze.sh ~/path/to/project
# 图形统计
./skills/stats.sh
# 模块树
./skills/modules.sh
# 跟踪调用路径 A → B
./skills/trace.sh func_a func_b
# 查找前 20 个热点
./skills/hotspots.sh 20
# 浏览架构依赖
./skills/knowledge.sh architecture_edge 20
```
每个脚本内部调用 `codescope cli <tool_name> '<json_args>'`。有关完整参考，请参见 `skills/skills.md`。
---
## 5. 环境变量
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `CODESCOPE_DB_PATH` | `.codescope/codescope.db` | SQLite 数据库路径 |
| `CODESCOPE_INDEX_MODE` | `standard` | 索引模式：`fast` / `standard` / `strict` |
| `CODESCOPE_EXCLUDE_PATHS` | (未设置) | 以逗号分隔的 glob 模式，用于排除 |
| `CODESCOPE_WORKERS` | `4` | `index-parallel` 的总解析工作核心数 |
| `CODESCOPE_WORKER_TIMEOUT` | `300` | 工作进程超时时间（秒） |
| `CODESCOPE_MAX_FILE_SIZE` | (未设置) | 要索引的最大源文件大小（字节） |
| `CODESCOPE_MMAP_SIZE` | 256 MB | SQLite `mmap_size` 指令值 |
| `CODESCOPE_MEM_LIMIT_MB` | `4096` | 动态调度器内存上限 |
| `CODESCOPE_DYNAMIC_SCHED` | `auto` | 动态 CPU 调度：`1` 开启，`0` 关闭，未设置 = 自动 |
| `CODESCOPE_VERBOSE` | `0` | 设置为 `1` 以启用详细日志记录 |
| `CODESCOPE_LSP` | (未设置) | 类型增强的 LSP 服务器命令 |
---
## 9. 许可证
Apache 2.0 — 请参阅 [LICENSE](LICENSE)。
**CodeScope v0.2.1** — 使用 Rust 2024 + C++23 + tree-sitter + SQLite 构建。
连接信息
猜你喜欢
暂无推荐服务器