ContextZero
AI代理的代码认知引擎。 将代码库索引到结构化图中，并通过MCP提供精确的令牌预算上下文。一次调用替换24次文件读取。
使用 克劳德代码, 光标, 帆板运动，以及任何 MCP兼容 AI工具。
______________________________________________________________________
为什么存在ContextZero
AI编码代理一次读取一个文件。为了理解一个函数更改，他们打开16个文件，读取10000多行，消耗40000多个令牌，但仍然会错过传递性副作用、合约违规和重复代码模式。
ContextZero消除了这一点。 它对代码库进行一次索引，然后在一次调用中提供精确、结构化的上下文。
______________________________________________________________________
测量结果：5个真实任务，面对面
相同的代码库（91个文件，4374个符号）。同样的5个任务。传统文件读取与ContextZero。真实数字。
任务1：“了解此功能及其所依赖的一切”
||文件读取|ContextZero| |--|-------------|-------------| |已打开的文件|6| 0 | |已消耗线路|2731| 0 | |消耗的代币|10924| 7,999 | |工具调用|9| 1 | |你得到了什么|原始源代码，自己弄清楚|源代码+13个预组装的依赖项+效果签名+每个决策的包含理由|
任务2：“如果我更改此功能，会出现什么问题？”
||文件读取|ContextZero| |--|-------------|-------------| |已打开的文件|4| 0 | |消耗的线路|4823| 0 | |消耗的代币|19292| ~600 | |工具调用|7| 1 | |得到的内容|提到函数名的文件列表| 8合同影响 具有严重性评分、不变违规预测、置信水平和推荐的验证范围|
代币数量减少32倍。 文件读取 *不能* 告诉你哪些合约不变量会被打破。
任务3：“此函数是否写入数据库？”
||文件读取|ContextZero| |--|-------------|-------------| |已打开的文件|9| 0 | |消耗的线路|6195| 0 | |代币消费量|24780| ~400 | |工具调用|14| 1 | |你得到了什么|手动跟踪9个文件，希望你能抓住每一个电话| 13种类型效果：DB读取、DB写入、文件I/O、HTTP调用、锁获取、事件发射——具有可传递的调用链跟踪和0.95的置信度|
代币减少62倍。 人类读取文件将错过一个可传递的数据库写入，该写入埋在3个调用级别深处。
任务4：“查找所有与此函数类似的代码”
||文件读取|ContextZero| |--|-------------|-------------| |已打开的文件|8| 0 | |消耗的线路|4968| 0 | |消费的代币|19872| ~2,000 | |工具调用|11| 2 | |你会得到什么|为相似的名字（嘈杂的，错过不同的名字）找到结果| 31个同源物 具有7维相似性评分：语义、逻辑、签名、行为、契约、测试和历史，以及矛盾标志|
代币数量减少10倍。 Grep找不到具有不同名称的行为相似的代码。
任务5：“给我安全修改此功能所需的一切”
||文件读取|ContextZero| |--|-------------|-------------| |已打开的文件|16| 0 | |消耗的线路|10246| 0 | |消耗的代币|40984| 11,057 | |工具调用|24| 1 | |你得到了什么|转储了16个原始文件，95%与你的更改无关|令牌预算胶囊：源+调用者+ 31次爆炸半径影响 +严重性得分+契约不变量，全部在一个调用中|
代币减少3.7倍。通话次数减少24倍。 一个电话取代了整个调查。
全部5个任务总计
||文件读取|ContextZero |差异| |--|-------------|-------------|-----------| | 打开的文件 | 43 | 0 |-43个文件| | 消耗的线路 | 28,963 | 0 |-29000条线路| | 消耗的代币 | 115,852 | 22,056 | 减少5.3倍 | | 工具调用 | 65 | 6 | 减少10.8倍 |
______________________________________________________________________
什么上下文零计算
| 能力 | 描述 |
|---|---|
| 胶囊汇编 | 令牌预算上下文包——一次调用中的源+deps+合约+效果。5级降级阶梯。 |
| 爆炸半径 | 具有严重性和置信度评分的5维影响分析（结构、行为、契约、同源物、历史） |
| 行为分析 | 每个分类的函数：纯/只读/读写/侧效。通过拓扑排序进行传递传播 |
| 效果签名 | 具有传递传播的9种类型化效果（读取、写入、打开、抛出、调用外部、记录、发出、规范化、获取锁定）。 |
| 合同提取 | 输入/输出类型、错误契约、安全契约、保护子句、派生不变量。 |
| 同源物检测 | 7维证据评分，4种矛盾标志类型。至少需要2个证据家庭。 |
| 智能上下文 | 一个调用：源+爆炸半径+调用者+测试+合约。替换8+个单独的查找。 |
| 调度决议 | 类层次结构、虚拟呼叫解析、C3线性化、现场敏感点分析。 |
| 概念家庭 | 10种具有样本识别、异常值检测和矛盾标记的家庭类型。 |
| 时间智能 | Git衍生的共同变化分析、时间风险评分、流失指标。 |
| 符号谱系 | 通过重命名和重构进行跨快照身份跟踪。 |
| 事务编辑 | 9状态生命周期，支持数据库回滚。6级渐进验证。 |
| 语义搜索 | 根据代码的功能查找代码：TF-IDF+MinHash LSH相似性。没有外部API。 |
| 不确定性跟踪 | 12源不确定性模型，具有每个符号的置信度评分和证据建议。 |
13种语言
TypeScript、JavaScript、Python、C++、Go、Rust、Java、C#、Ruby、Kotlin、Swift、PHP、Bash。
TypeScript/JavaScript:通过TypeScript编译器API进行完整的AST分析。Python：具有60多种行为模式的LibCST。所有其他人：有特定语言步行者的树保姆。
建筑
AI Agent (Claude Code, Cursor, Windsurf, etc.)
|
| MCP protocol (stdio)
|
ContextZero MCP Bridge (56 tools)
|
+-- Ingestor (13 languages, delta ingestion)
+-- 13 Analysis Engines
| Behavioral | Contract | Deep Contract | Blast Radius
| Effect | Dispatch | Concept Families | Temporal
| Symbol Lineage | Runtime Evidence | Uncertainty
| Structural Graph | Capsule Compiler
+-- Semantic Engine (TF-IDF, MinHash LSH, cosine similarity)
+-- Homolog Engine (7-dimensional scoring, 5 candidate buckets)
+-- Transactional Editor (9-state lifecycle, sandbox execution)
+-- Service Layer (8 transport-agnostic services)
+-- Database Driver (circuit breaker, batch loader, advisory locks)
|
PostgreSQL 16 (all data local, nothing leaves your machine)______________________________________________________________________
设置
先决条件
- Node.js 20+（建议22人）
- PostgreSQL 14+（推荐16人）
pg_trgm扩展
安装
git clone https://github.com/Ranjitbarnala0/ContextZero.git
cd ContextZero
npm install数据库
createdb scg_v2
psql -d scg_v2 -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;"设置环境变量：
export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=scg_v2
export DB_USER=your_user
export DB_PASSWORD=your_password
export NODE_ENV=development
export LOG_LEVEL=info
export SCG_ALLOWED_BASE_PATHS=/your/code/directory构建和启动：
npm run build
npm start # HTTP server on port 3100
# or
npm run mcp # MCP stdio bridge连接到克劳德代码
claude mcp add contextzero -s user \
-e DB_HOST=localhost \
-e DB_PORT=5432 \
-e DB_NAME=scg_v2 \
-e DB_USER=your_user \
-e DB_PASSWORD=your_password \
-e NODE_ENV=development \
-e LOG_LEVEL=warn \
-e SCG_ALLOWED_BASE_PATHS=/your/code/directory \
-- node /path/to/ContextZero/dist/mcp-bridge/index.js码头工人
docker compose up -d验证
让Claude Code运行 scg_health_check你应该看看 status: healthy 数据库延迟和版本。
______________________________________________________________________
56个MCP工具
| 类别 | 工具 | 计数 |
|---|---|---|
| 核心 | scg_health_check scg_register_repo scg_list_repos scg_ingest_repo scg_incremental_index scg_codebase_overview scg_snapshot_stats scg_cache_stats | 8 |
| 符号智能 | scg_resolve_symbol scg_get_symbol_details scg_get_symbol_relations scg_read_source scg_search_code scg_semantic_search scg_get_tests scg_get_neighbors | 8 |
| 行为与合同 | scg_get_behavioral_profile scg_get_contract_profile scg_get_invariants scg_get_uncertainty scg_get_effect_signature scg_diff_effects scg_explain_relation scg_find_concept | 8 |
| 影响分析 | scg_blast_radius scg_compile_context_capsule scg_smart_context scg_find_homologs scg_persist_homologs scg_propagation_proposals scg_semantic_diff scg_contract_diff | 8 |
| 变更计划 | scg_plan_change scg_prepare_change scg_apply_propagation scg_review_homolog | 4 |
| 代码图 | scg_get_dispatch_edges scg_get_class_hierarchy scg_get_symbol_lineage scg_get_co_change_partners scg_get_temporal_risk scg_get_runtime_evidence scg_get_concept_family scg_list_concept_families | 8 |
| 事务编辑 | scg_create_change_transaction scg_get_transaction scg_apply_patch scg_validate_change scg_commit_change scg_rollback_change | 6 |
| 数据管理 | scg_list_snapshots scg_batch_embed scg_ingest_runtime_trace | 3 |
| 本地工作区 | scg_native_codebase_overview scg_native_symbol_search scg_native_search_code | 3 |
The 3 本地工作区 工具在没有数据库的情况下工作——它们直接分析文件系统，无需摄入即可立即使用。
______________________________________________________________________
HTTP API
55条路线（4条GET+51条POST） http://localhost:3100/与MCP工具具有相同的功能。
| 终点 | 目的 |
|---|---|
GET /health | 使用数据库统计数据进行活体检查 |
GET /ready | 准备就绪检查（迁移状态） |
GET /metrics | 普罗米修斯指标 |
GET /scg_cache_stats | 缓存命中/未命中统计数据 |
POST /scg_* | 所有51个工具端点（与MCP参数相同） |
所有POST路由都需要API密钥身份验证（承载令牌或X-API-key头）。
______________________________________________________________________
安全
- 零SQL注入表面 --100%参数化查询，表/列分配列表
- 5层路径穿越保护 --空字节、URL编码、反斜杠、符号链接转义、边界强制
- 关闭身份验证失败 --定时安全比较，最小32个字符，每个IP暴力锁定，指数回退
- 沙盒执行 --ulimit、进程组、SIGKILL升级、环境净化
- 没有数据离开您的机器 --无遥测，无外部API，完全本地
- 断路器 在具有指数回退重试的数据库连接上
- 输入验证 在每条路由上--UUID、有界整数、字符串长度、补丁大小限制
- 错误清理 --错误响应中没有堆栈跟踪、内部路径或SQL
______________________________________________________________________
测试
npm test # Full test suite
npm run test:ci # With coverage
npm run typecheck # TypeScript strict mode与真实PostgreSQL的集成测试。所有分析引擎、适配器、处理程序、安全性和缓存的单元测试。
______________________________________________________________________
文档
______________________________________________________________________
许可证
国际学生委员会