<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/zzet/gortex) · [上游 README](https://github.com/zzet/gortex/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

<div align="center">
<p align="center">
  <img src="assets/wall.svg" alt="Gortex" width="500">
</p>


### 面向 AI 智能体与 IDE 的高性能高效代码智能引擎
#### 将代码索引为图结构，并通过 CLI、MCP Server 与 Web UI 暴露。默认支持多仓库。
#### macOS、Linux 与 Windows 单静态二进制 — 无依赖链，安装与使用简单。

---
[![CI](https://github.com/zzet/gortex/actions/workflows/ci.yml/badge.svg)](https://github.com/zzet/gortex/actions/workflows/ci.yml)
[![Latest release](https://img.shields.io/github/v/release/zzet/gortex?logo=github&sort=semver)](https://github.com/zzet/gortex/releases/latest)
[![Sigstore signed](https://img.shields.io/badge/sigstore-signed-66D4FF?logo=sigstore&logoColor=white)](docs/installation.md#verifying-releases-supply-chain-security)
[![SLSA 3](https://img.shields.io/badge/SLSA-Level%203-green)](https://slsa.dev/spec/v1.0/levels#build-l3)
[![VirusTotal](https://img.shields.io/badge/VirusTotal-0%2F91-brightgreen?logo=virustotal)](https://www.virustotal.com/gui/url/00e1094b39c9bd7db4d5a179b1d56173f85c915075057fd3cc64bfbb9b735b11/detection)
[![macOS](https://img.shields.io/badge/macOS-supported-blue.svg)](#)
[![Linux](https://img.shields.io/badge/Linux-supported-blue.svg)](#)
[![Windows](https://img.shields.io/badge/Windows-supported-blue.svg)](#)

[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/zzet/gortex/badge)](https://scorecard.dev/viewer/?uri=github.com/zzet/gortex)
[![Go Reference](https://pkg.go.dev/badge/github.com/zzet/gortex.svg)](https://pkg.go.dev/github.com/zzet/gortex)
  <br />
  <a href="https://trendshift.io/repositories/36832" target="_blank"><img src="https://trendshift.io/api/badge/repositories/36832" alt="zzet%2Fgortex | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
</div>

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


> 开箱即用支持 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](docs/agents.md)。

<details>
<summary>Gortex Web UI — 力导向知识图谱可视化</summary>

![Gortex Web UI — 力导向知识图谱可视化](assets/graph.png)

</details>

## 为何重要

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

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

## 安装

```bash
# 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](docs/installation.md)。

## 快速开始

```bash
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](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](docs/contracts.md)。

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

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

| 仓库 | 文件数 | 节点数 | 边数 | 索引时间 | 吞吐量 | 峰值堆内存 |
| ---------- | ----: | ----: | ----: | ---------: | ---------: | --------: |
| [torvalds/linux](https://github.com/torvalds/linux) | 70,333 | 1,690,174 | 6,239,570 | ~3 min | 300 files/s | 5.07 GB |
| [microsoft/vscode](https://github.com/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）以美元计价。

```text
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](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](docs/architecture.md)。

## 文档

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

## 从源码构建

```bash
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](LICENSE.md)。Copyright 2024-2026 Andrey Kumanyaev <me@zzet.org>。

## 贡献

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