wehub-resource-sync
2eb041bed8
CI / test (1.26, macos-latest) (push) Has been cancelled
CI / test (1.26, ubuntu-latest) (push) Has been cancelled
Scorecard supply-chain security / Scorecard analysis (push) Has been cancelled
CI / build-windows (push) Has been cancelled
CI / lint (push) Has been cancelled
CI / build-onnx (push) Has been cancelled
CI / benchmark (push) Has been cancelled
security / govulncheck (push) Has been cancelled
security / trivy-fs (push) Has been cancelled
195 lines
13 KiB
Markdown
195 lines
13 KiB
Markdown
<!-- 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 单静态二进制 — 无依赖链，安装与使用简单。
|
||
|
||
---
|
||
[](https://github.com/zzet/gortex/actions/workflows/ci.yml)
|
||
[](https://github.com/zzet/gortex/releases/latest)
|
||
[](docs/installation.md#verifying-releases-supply-chain-security)
|
||
[](https://slsa.dev/spec/v1.0/levels#build-l3)
|
||
[](https://www.virustotal.com/gui/url/00e1094b39c9bd7db4d5a179b1d56173f85c915075057fd3cc64bfbb9b735b11/detection)
|
||
[](#)
|
||
[](#)
|
||
[](#)
|
||
|
||
[](https://scorecard.dev/viewer/?uri=github.com/zzet/gortex)
|
||
[](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>
|
||
|
||
|
||
|
||
</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)。
|