zzet--gortex/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

面向 AI 智能体与 IDE 的高性能高效代码智能引擎

将代码索引为图结构，并通过 CLI、MCP Server 与 Web UI 暴露。默认支持多仓库。

macOS、Linux 与 Windows 单静态二进制 — 无依赖链，安装与使用简单。

---

通过 tree-sitter AST 分析、进程内解析器，并借助 编译器级解析)（适用于 Python、TypeScript / JavaScript、PHP、C#、Go、C、C++、Java、Kotlin、Swift、Zig、Rust、Ruby、Elixir、Ocaml、Haskell 及其他语言)），高质量解析 257 种语言/语法，生成函数、类、调用链、HTTP 路由以及跨服务契约与调用的持久化、来源分级知识图谱，并具备强置信度模型。175 个（可配置）MCP 工具 — 按需使用即可。零依赖。即插即用，支持 18 种编程智能体。每次响应最多可减少 50× token。可复现的基准测试。

开箱即用支持 18 种 AI 编程智能体（Claude Code、Kiro、Cursor、Windsurf、VS Code / Copilot、Continue.dev、Cline、OpenCode、Antigravity、Codex CLI、Gemini CLI、Zed、Aider、Kilo Code、OpenClaw、Hermes、Oh My Pi、Pi）。

一次安装即可配置本机检测到的所有智能体 — 参见 docs/agents.md。

Gortex Web UI — 力导向知识图谱可视化

为何重要

• 每次响应减少 50× token — 基于图谱的原生查询优于朴素的文件读取。智能体只读取所需内容，而非整个文件，也不是其周围那 500 行。
• 完整开发周期 — 无需「先读文件再编辑」。智能体查询源码、说明要改什么，不会因阅读噪音浪费上下文。
• 257 种语言/语法 — 仓库中每个文件均可触达；无需混用多种工具，避免智能体臃肿与幻觉。三层机制（定制 tree-sitter、正则、forest 支撑签名）外加 Jupyter 与 Databricks 笔记本 → docs/languages.md
• 默认跨仓库 — N 个仓库纳入同一图谱；契约、引用与调用链跨越仓库边界，具备证据门控解析、契约匹配、影响分析与会话级隔离 → docs/multi-repo.md
• 极速分析 — 预计算的深度 3 可达索引将爆炸半径查询转化为 O(seeds × reach) 的映射查找。每次编辑都可安全地问「若我改这里，什么会坏？」。无需数十次工具调用来把握上下文。
• 零外部依赖 — 单一二进制，一切在进程内完成。无需网络，无需下载模型即可起步。安装、启动守护进程、使用。
• 智能体集成（17） — gortex init 为本机检测到的每个编程助手完成配置 → docs/agents.md
• 100+ MCP 工具、16 个资源、3 个提示 — 符号查找、调用链、爆炸半径、数据流、克隆检测、重构、代码操作 → docs/mcp.md
• 语义搜索默认开启 — 内置 GloVe-50d（嵌入 3.8 MB），混合 BM25 + 向量 + RRF，零依赖；可选 MiniLM / Ollama / OpenAI → docs/semantic-search.md
• 推测执行 — preview_edit / simulate_chain 在不触碰磁盘的情况下回答「若我应用此 WorkspaceEdit，会发生什么变化？」
• 实时编辑器叠加层 — 将未保存缓冲区推送为影子图谱；工具透过它读取。支持并行推测会话的分支
• GCX1 线格式 — 已发布、可往返。相同保真度下比 JSON 再少 27% token → docs/wire-format.md
• 长驻守护进程 — 单一进程服务所有 IDE 窗口；实时 fsnotify、磁盘快照、重启、操作系统监管生命周期
• 9 个 LLM 提供商（可选） — 本地 llama.cpp、Anthropic、OpenAI、Ollama、Claude / Codex CLI 子进程、Gemini、Bedrock、DeepSeek → docs/llm.md
• 可组合安全 — verify_change、check_guards、audit_agent_config 在问题上线前标记损坏的调用方、守卫违规与过时文档
• PR 审查，端到端 — gortex prs 对开放 PR 进行分诊（按 PR 的爆炸半径、通过共享社区检测合并顺序冲突、AI 排序队列、审查者建议）；gortex review 输出锚定到行的发现，并给出基于图谱规则包的 BLOCK/REVIEW/APPROVE 裁决；MCP 工具（pr_risk、get_pr_impact、review、review_pack、post_review、…）向智能体暴露上述能力 → docs/cli.md
• HTTP 服务器 + Web UI — 版本化 /v1/* API + MCP 2026 Streamable HTTP；独立 Next.js 15 UI，含五种 3D 图谱模式 → docs/server.md
• 遥测默认关闭 — 仅可选匿名工具/命令计数（不含代码、路径、名称或精确计数）；除非你配置端点，否则不传输任何数据。gortex telemetry on|off|status；遵循 DO_NOT_TRACK → docs/telemetry.md

完整功能目录：docs/features.md。完整 CLI 参考：docs/cli.md。

安装

# macOS / Linux
curl -fsSL https://get.gortex.dev | sh

# Windows (PowerShell)
irm https://get.gortex.dev/install.ps1 | iex

检测 OS/架构，校验 SHA256 + cosign，安装到 PATH。重新运行即可升级。Homebrew、.deb / .rpm / .apk、scoop、签名二进制及源码构建：docs/installation.md。

快速开始

gortex install                          # one-time machine setup (MCP, skills, slash commands)
gortex daemon start --detach            # background daemon
gortex track ~/projects/myapp           # add a repo
cd ~/projects/myapp && gortex init      # per-repo: .mcp.json, hooks, community routing

你的 AI 助手现已使用图谱查询。完整 15 分钟入门：docs/onboarding.md。

跨仓库 API 契约

Gortex 自动检测跨仓库 API 契约并将提供方与消费者匹配，通过 contracts MCP 工具及 Web UI 契约页面呈现。

契约类型	检测方式	提供方	消费方
HTTP 路由	框架注解（gin、Express、FastAPI、Spring、…）	路由处理器	HTTP 客户端调用（fetch、http.Get）
gRPC	Proto 服务定义	服务 RPC	客户端桩调用
GraphQL	Schema 类型/字段定义	Schema	查询/变更字符串
消息主题	Kafka / RabbitMQ / NATS / Redis pub/sub	发布调用	订阅调用
WebSocket	事件 emit/listen 模式	emit()	on()
环境变量	os.Getenv、process.env、.env 文件	Setenv / .env	Getenv / process.env
OpenAPI	Swagger / OpenAPI 规范文件	规范路径	（关联至 HTTP 路由）
Temporal 工作流	Go / Java SDK 注解	Activity / 工作流函数	ExecuteActivity / ExecuteChildWorkflow

合约（Contracts）会被规范化为规范 ID（canonical IDs，例如 http::GET::/api/users/{id}），并在各仓库之间进行匹配，以检测孤立的提供方（providers）/ 消费方（consumers）和不一致项。详见 docs/contracts.md。

规模 — 在大型仓库上久经考验

在 Apple Silicon 笔记本电脑上使用默认 CGO 构建测得。

仓库	文件数	节点数	边数	索引时间	吞吐量	峰值堆内存
torvalds/linux	70,333	1,690,174	6,239,570	~3 min	300 files/s	5.07 GB
microsoft/vscode	10,762	204,501	808,902	~1 min	143 files/s	580 MB
zzet/gortex (self)	430	5,583	53,830	3.4s	127 files/s	52 MB

解析占用了绝大部分墙上时钟时间（wall time，65–80%）；引用解析与搜索索引构建的扩展呈次线性（sub-linear）。

Token 节省仪表盘

gortex savings 会报告相较朴素文件读取（naive file reads）所节省的 token——按每次调用、按会话，以及跨重启的累计值，并按头条模型（headline model）以美元计价。

Gortex Token Savings
====================
Cost avoided:   $168.69 (claude-opus-4) across 1,878 calls · 11,246,094 tokens saved

Today       ████████░░░░░░░░   50.0%  saved 9,200 / 18,400 tokens   $0.14
Last 7 days ██████████░░░░░░   62.5%  saved 60,100 / 96,200 tokens  $0.90
All time    ███████████████░   93.3%  saved 11,246,094 / 12,050,716 tokens  $168.69

--verbose 提供按工具（per-tool）的细分；--json 为机器可读格式。完整参考：docs/savings.md。

架构

gortex binary
  CLI (cobra)    ──> MultiIndexer ──> In-Memory Graph (shared, per-repo indexed)
  MCP (stdio)    ──────────────────> Query Engine (repo/project/ref scoping)
  HTTP /v1/*     ──────────────────> same tools + /v1/graph + /v1/events (SSE)
  Daemon (unix)  ──────────────────> shared graph for every MCP client, session isolation
                  MultiWatcher    <── filesystem events (fsnotify, per-repo)
                  CrossRepoResolver ──> cross-repo edge creation (type-aware)
                  Persistence     ──> gob+gzip snapshot (pluggable backend)

数据流、图模式（graph schema，节点与边类型、多仓库字段、测试分类法）以及持久化模型：docs/architecture.md。

文档

主题	参考
首次使用 walkthrough	onboarding.md
安装与供应链验证	installation.md
完整功能目录	features.md
CLI 参考	cli.md
MCP 工具、资源与提示词	mcp.md
多仓库工作区	multi-repo.md
HTTP 服务器 + Web UI + MCP 2026 传输层	server.md
跨仓库 API 合约	contracts.md
语义搜索	semantic-search.md
可选 LLM 功能	llm.md
LSP 集成	lsp.md
各社区技能与 agent 用法	skills.md
AI agent 适配器（17）	agents.md
支持的语言（257）	languages.md
Token 节省	savings.md
GCX1 线格式（wire format）	wire-format.md
架构与图模式	architecture.md
评估方法论	04-evaluation/
遥测与隐私	telemetry.md
版本策略	versioning.md

从源码构建

make build          # binary with version stamping
make test           # go test -race ./...
make lint           # golangci-lint

需要 Go 1.26+ 与 CGO（用于 tree-sitter C 绑定）。

许可证

Apache License 2.0。详见 LICENSE.md。Copyright 2024-2026 Andrey Kumanyaev me@zzet.org。

贡献

有关添加功能、语言提取器（language extractors）以及提交 PR 的指南，请参见 CONTRIBUTING.md。