内容
# 上下文零引擎
[](https://github.com/Classevelabs/context-zero-engine/releases/latest) [](LICENSE)
**适用于AI智能体的本地代码智能引擎** 上下文零索引仓库到PostgreSQL支持的代码图，并通过MCP和HTTP提供结构化、按令牌预算的上下文 — 符号、依赖项、效果、合约、类似代码和爆炸半径。所有操作都在您的机器上运行；不会有任何数据离开。
由 [ClassEve](https://classeve.com) 构建。遵循Apache-2.0许可证。
> **官方仓库**。这是上下文零引擎的唯一官方仓库。
> ClassEve的官方账户完整列表请参见 [classeve.com/official](https://classeve.com/official)。
> GitHub账户 `github.com/ClassEve` 是无关的第三方，不隶属于ClassEve。
---
## 问题
编码智能体和开发者工具通常一次检查一个文件。对于非琐碎的代码库，这意味着打开数十个文件，重复阅读相同的代码，手动跟踪传递影响 — 但仍然会错过合约假设或行为类似的代码。
上下文零索引仓库一次，并通过有针对性的查询回答相同的调查：*给我这个符号及其依赖项和合约*，*如果我改变它，会发生什么*，*这个逻辑在哪里还存在*，*哪些测试涵盖它*。在记录的基准测试中，这将智能体消耗的令牌减少了 **63–92%，取决于仓库大小** （VS Code上12.4倍，七个多语言仓库上12.9倍）。有关完整的测试方法、结果和诚实的注意事项，请参见 [BENCHMARKS.md](BENCHMARKS.md)。
---
## 计算内容
| 功能 | 描述 |
|-----------|-------------|
| **上下文胶囊** | 按令牌预算的上下文包：源、依赖项、合约和效果，一次调用，带有5级降级梯度。 |
| **爆炸半径** | 5维影响分析（结构、行为、合约、同源、历史）带有严重性和置信度评分。 |
| **行为分析** | 每个函数分类：纯/只读/读写/有副作用。TS/JS外部效果 **类型解析** — 每个调用跟踪到其源模块（pg、fs、axios等），而不是模式猜测。纯度通过调用图传播；资源列表保持每个符号。测得100%/100%精度召回率在已发布的真实性测试套件上（参见 [BENCHMARKS.md](BENCHMARKS.md)）。 |
| **效果签名** | 9种类型效果（读取、写入、打开、抛出、调用外部、日志、发出、规范化、获取锁），带有来源标签（`直接` vs `传递`带有跳数）和有界、按种类过滤的策略传播。 |
| **合约提取** | 输入/输出类型、错误合约、安全合约、守卫子句、派生不变量 — 从代码本身挖掘。 |
| **同源检测** | 通过7维证据评分查找行为等效代码（不仅是文本克隆），带有矛盾标志。 |
| **智能上下文** | 一次调用：源 + 爆炸半径 + 调用者 + 测试 + 合约。替换8+单独的查找。 |
| **调度解析** | 类层次结构、虚拟调用解析、C3线性化、字段敏感点到点分析。 |
| **概念族** | 相关符号的自动分组，带有示例识别、异常检测和矛盾标记。 |
| **时间智能** | Git衍生的共同变化分析、时间风险评分、变化指标。 |
| **符号血统** | 跨快照身份跟踪，通过重命名和重构。 |
| **事务编辑** | 9状态更改生命周期，带有DB支持的回滚和6级渐进验证。 |
| **语义搜索** | 按代码功能查找：TF-IDF + MinHash LSH相似性。无需外部API，无嵌入服务。 |
| **不确定性跟踪** | 12源不确定性模型，带有每个符号的置信度评分 — 引擎告诉你它 *不* 确定的内容。 |
## 15种语言
TypeScript、JavaScript、Python、C、C++、CUDA风格的`.cu`/`.cuh`、Go、Rust、
Java、C#、Ruby、Kotlin、Swift、PHP、Bash。
TypeScript和JavaScript使用TypeScript编译器API进行完整的AST分析。Python使用LibCST，带有60+行为模式。其余语言使用tree-sitter，带有语言特定的遍历器。
## 工作原理
```
MCP兼容客户端（Claude Desktop、Claude Code、Codex、Cursor、...）
|
| MCP协议（stdio） HTTP客户端
| |
上下文零MCP桥接器（61种工具） REST API（60个路由）
| |
+------------------+------------------+
|
+-- 摄入器（15种语言，增量摄入）
+-- 13个分析引擎
| 行为 | 合约 | 深度合约 | 爆炸半径
| 效果 | 调度 | 概念族 | 时间
| 符号血统 | 运行时证据 | 不确定性
| 结构图 | 胶囊编译器
+-- 语义引擎（TF-IDF、MinHash LSH、余弦相似度）
+-- 同源引擎（7维评分）
+-- 事务编辑器（沙盒验证、回滚）
+-- 服务层（传输无关的服务）
+-- 数据库驱动程序（电路中断器、批量加载器、咨询锁）
|
PostgreSQL 16（所有数据本地，不会离开您的机器）
```
`scg_`前缀用于工具和环境变量，源自引擎的内部名称 — 结构化代码图。
深入了解： [ARCHITECTURE.md](ARCHITECTURE.md)（子系统和工具注册表）和 [TECHNICAL_DESIGN.md](TECHNICAL_DESIGN.md)（数据结构、算法、引擎内部）。
---
## 安装
### 先决条件
- **Node.js** 20+（推荐22）
- **PostgreSQL** 14+（推荐16）带有`pg_trgm`扩展
- **Python 3** 带有`libcst`（可选 — 仅用于Python源代码分析）
### 引导（推荐）
```bash
git clone https://github.com/Classevelabs/context-zero-engine.git context-zero-engine
cd context-zero-engine
```
Windows:
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\bootstrap.ps1 -Client claude
```
macOS / Linux:
```bash
scripts/bootstrap.sh --client claude
```
引导程序安装依赖项、创建`.env`、构建、运行数据库迁移、运行诊断（`npm run doctor`），并可选地为您的客户端编写MCP配置（`claude`、`codex`、`cursor`或`all`）。
### 手动安装
```bash
npm install
createdb scg_v2
psql -d scg_v2 -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
cp .env.example .env # 设置DB_USER / DB_PASSWORD / SCG_ALLOWED_BASE_PATHS
npm run build
npm run db:migrate
npm run doctor # 验证node、数据库、python、环境
```
完整的选项、客户端配置文件路径和故障排除方法请参见 [docs/INSTALL.md](docs/INSTALL.md) 和 [docs/OPERATIONS.md](docs/OPERATIONS.md)。
---
## 快速入门
### 1. 连接到MCP客户端
捆绑的安装程序为Claude Desktop、Codex或Cursor编写配置文件（带有时间戳备份的现有文件）：
```bash
npm run mcp:install -- --client claude
```
或者在不触摸客户端文件的情况下生成配置文件片段（`npm run mcp:config`），或手动注册 — 例如使用Claude Code CLI：
```bash
claude mcp add contextzero -s user \
-e CONTEXTZERO_ENV_FILE=/absolute/path/to/context-zero-engine/.env \
-- node /absolute/path/to/context-zero-engine/dist/mcp-bridge/index.js
```
任何支持stdio的MCP客户端都可以使用：服务器是 `node dist/mcp-bridge/index.js`，带有`DB_*`/`SCG_*`环境（或指向您的`.env`的单个`CONTEXTZERO_ENV_FILE`）。
### 2. 索引仓库
从MCP客户端调用：
```text
scg_health_check → 应报告状态：healthy
scg_register_repo / scg_ingest_repo → 在SCG_ALLOWED_BASE_PATHS下索引仓库
```
然后开始提问：`scg_smart_context`、`scg_blast_radius`、`scg_compile_context_capsule`、`scg_find_homologs`、`scg_semantic_search`，...
三个原生工具（`scg_native_codebase_overview`、`scg_native_symbol_search`、`scg_native_search_code`）无需数据库即可立即工作 — 它们直接分析文件系统。
### 3. 或作为HTTP服务器运行
```bash
npm run build
npm start # HTTP服务器在端口3100上
```
```bash
curl http://localhost:3100/health
curl -X POST http://localhost:3100/scg_codebase_overview \
-H "X-API-Key: <your key>" -H "Content-Type: application/json" \
-d '{"repo_id": "..."}'
```
60个路由（7个GET + 53个POST）镜像MCP工具表面，加上健康状态、就绪状态、Prometheus指标、缓存和管理员端点。所有POST路由都需要API密钥身份验证（`X-API-Key`或`Authorization: Bearer`）。
### Docker（自托管服务器 + 捆绑PostgreSQL）
```bash
cp .env.docker.example .env
# 将DB_PASSWORD和SCG_API_KEYS设置为强秘密。
docker compose up -d
```
在Docker中注册仓库时，请使用`/repos`下的路径 — 这是`SCG_REPOS_PATH`在容器内挂载的位置。
---
## MCP工具表面（61种工具）
| 类别 | 数量 | 示例 |
|----------|------:|----------|
| 核心 | 8 | `scg_health_check`、`scg_ingest_repo`、`scg_incremental_index`、`scg_codebase_overview` |
| 符号智能 | 8 | `scg_resolve_symbol`、`scg_read_source`、`scg_semantic_search`、`scg_get_tests` |
| 行为和合约 | 8 | `scg_get_behavioral_profile`、`scg_get_invariants`、`scg_get_effect_signature` |
| 影响分析 | 8 | `scg_blast_radius`、`scg_compile_context_capsule`、`scg_smart_context`、`scg_find_homologs` |
| 变更规划 | 4 | `scg_plan_change`、`scg_prepare_change`、`scg_apply_propagation` |
| 代码图 | 8 | `scg_get_class_hierarchy`、`scg_get_symbol_lineage`、`scg_get_co_change_partners` |
| 事务编辑 | 6 | `scg_create_change_transaction`、`scg_validate_change`、`scg_rollback_change` |
| 数据管理 | 3 | `scg_list_snapshots`、`scg_batch_embed`、`scg_ingest_runtime_trace` |
| 原生工作区（无DB） | 3 | `scg_native_codebase_overview`、`scg_native_symbol_search`、`scg_native_search_code` |
| 管理员 | 5 | `scg_admin_run_retention`、`scg_admin_db_stats`、`scg_admin_system_info` |
完整的注册表在 [ARCHITECTURE.md](ARCHITECTURE.md) 中。
---
## 安全
- **设计本地** — 无遥测，无外部API；分析和存储在您的机器上
- **SQL注入保护** — 参数化查询 + 表/列允许列表用于动态查询
- **5层路径遍历保护** — 空字节、URL编码、反斜杠处理、符号链接逃逸检查、基准路径边界强制执行
- **失败关闭身份验证** — 计时安全比较、32字符最小密钥、每IP的暴力锁定，带有指数反弹
- **沙盒验证** — 资源限制、进程组、SIGKILL升级、环境净化
- **强化HTTP表面** — 每路由速率限制和正文大小限制、每个路由输入验证、净化错误响应（无堆栈跟踪、路径或SQL）
有关部署强化检查清单和漏洞报告方法，请参见 [SECURITY.md](SECURITY.md)。
---
## 基准测试
| 基准测试 | 规模 | 令牌减少（确切符号基线） |
|---|---|---:|
| 引擎自摄入 | 105个文件 / 7,753个符号 | 2.71倍（63.1%节省） |
| VS Code | 10,386个文件 / 125,777个符号版本 | 12.44倍（91.96%节省） |
| 7个多语言仓库 | Django、Prometheus、Tokio、Commons Lang、Serilog、OkHttp、Alamofire | 12.86倍（92.2%节省） |
方法论、每个仓库的表格、重现脚本和增益小的案例： [BENCHMARKS.md](BENCHMARKS.md)。
---
## 测试
```bash
npm test # 完整的单元测试套件（40个套件，1,400+测试）
npm run test:db # 对真实PostgreSQL进行集成测试
npm run test:ci # 带有覆盖率
npm run typecheck # TypeScript严格模式
npm run lint
```
---
## 文档
| 文档 | 描述 |
|----------|-------------|
| [docs/INSTALL.md](docs/INSTALL.md) | 安装路径、MCP客户端配置、诊断 |
| [docs/OPERATIONS.md](docs/OPERATIONS.md) | 日常操作、索引、网络服务器模式 |
| [ARCHITECTURE.md](ARCHITECTURE.md) | 系统架构、子系统、工具注册表 |
| [TECHNICAL_DESIGN.md](TECHNICAL_DESIGN.md) | 数据结构、算法、引擎内部 |
| [BENCHMARKS.md](BENCHMARKS.md) | 基准测试方法论和结果 |
| [SECURITY.md](SECURITY.md) | 强化检查清单和漏洞报告 |
---
## 关于
由 [ClassEve](https://classeve.com) 构建和维护 — 面向AI智能体和开发者工具的工程。项目页面： [classeve.com/public/context-zero-engine](https://classeve.com/public/context-zero-engine)。
## 许可证
Apache License 2.0 — 参见 [LICENSE](LICENSE)。版权所有 2026 [ClassEve](https://classeve.com)。
