zzet/gortex

# Gortex [](https://github.com/zzet/gortex/actions/workflows/ci.yml) [](https://goreportcard.com/report/github.com/zzet/gortex) 代码智能引擎，将代码库索引到内存知识图谱中，并通过 CLI、MCP 服务器和 Web UI 暴露。 专为 AI 编码代理（Claude Code、Kiro、Cursor、Windsurf、Copilot、Continue.dev、Cline、OpenCode、Antigravity）设计 —— 一个 `smart_context` 调用可替代 5-10 次文件读取，减少约 94% 的 Token 使用。  ## 功能特性 - **知识图谱** — 在一个可查询的结构中统一管理每个文件、符号、导入、调用链和类型关系 - **多仓库工作区** — 将多个仓库索引到单个图谱中，支持跨仓库符号解析、项目分组、引用标签和每个仓库的作用域隔离 - **33 种语言** — Go、TypeScript、JavaScript、Python、Rust、Java、C#、Kotlin、Swift、Scala、PHP、Ruby、Elixir、C、C++、Dart、OCaml、Lua、Zig、Haskell、Clojure、Erlang、R、Bash/Zsh、SQL、Protobuf、Markdown、HTML、CSS、YAML、TOML、HCL/Terraform、Dockerfile - **47 个 MCP 工具** — 符号查找、调用链、冲击范围分析、社群/流程发现、契约检测、统一 `analyze`（死代码、热区、环路）、脚手架、内联编辑、符号重命名、多仓库管理、代理反馈循环、上下文导出、图谱验证配置健康检查（`audit_agent_config`）、开局走子路由（`plan_turn`）、叙事仓库概览（`get_repo_outline`）、测试覆盖缺口（`get_untested_symbols`）以及 18 个代理优化工具 - **语义搜索** — 混合 BM25 + 向量搜索与 RRF 融合。Hugot（纯 Go ONNX 运行时搭配 MiniLM-L6-v2）默认捆绑并自动下载模型，首次使用零配置、无原生依赖；GloVe 词向量作为回退。可选构建标签切换至 ONNX 或 GoMLX 以获得更高吞吐量 - **LSP 增强调用图层级** — 每条边携带 `origin` 层级（`lsp_resolved` / `lsp_dispatch` / `ast_resolved` / `ast_inferred` / `text_matched`）；通过 `min_tier` 参数限制 `get_callers`、`find_usages`、`find_implementations` 等的结果，仅使用编译器验证的边进行高风险重构 - **MCP 进度通知** — 长时间运行的索引与 `track_repository` 调用会发出 `notifications/progress` 阶段消息（遍历文件 → 解析 → 解析 → 语义增强 → 搜索索引 → 契约 → 完成），让主机在大型仓库中显示实时进度条 - **类型感知解析** — 从变量声明、复合字面量和 Go 构造函数惯例推断接收者类型，以区分同名方法 - **磁盘持久化** — 退出时拍摄图谱快照，启动时恢复并仅对变更文件增量重新索引（约 200ms，相比 3-5 秒全量重新索引） - **桥接模式** — 通过 HTTP/JSON API 暴露所有 MCP 工具，支持 IDE 插件、CI 工具与 Web UI，并具备 CORS 支持和工具发现端点 - **语义增强** — 可插拔的 SCIP、go/types 和 LSP 提供者，将边置信度从约 70-85%（tree-sitter）提升至 95-100%（编译器验证）。可优雅降级，当外部工具不可用时仍保持可用 - **代理反馈循环** — 统一的 `feedback` 工具（`action: "record"` / `"query"`）允许代理报告哪些符号有用/缺失，跨会话持久化以通过反馈感知重排序提升后续 `smart_context` 质量 - **上下文导出** — `export_context` 工具与 `gortex context` CLI 命令将图谱上下文导出为可移植的 Markdown/JSON 简报，便于在 MCP 外部共享（Slack、PR、文档、非 MCP AI 工具） - **ETag 条件获取** — 基于内容哈希的 `if_none_match` 在读取源文件工具中避免在迭代编辑期间重复传输未变更的符号 - **Token 节省追踪** — 每个源读取工具的 `tokens_saved` 字段 + 会话级 `graph_stats`（调用计数、返回 Token、节省 Token、效率比值） - **7 个 MCP 资源** — 无需工具调用即可获取轻量级图谱上下文 - **3 个 MCP 提示** — `pre_commit`、`orientation`、`safe_to_change`，用于引导工作流 - **双层配置** — 全局配置（`~/.config/gortex/config.yaml`）用于项目与仓库列表，每个仓库的 `.gortex.yaml` 用于防护规则、排除与本地覆盖 - **防护规则** — 项目级约束（协同变更、边界）通过 `check_guards` 执行 - **观察模式** — 对所有追踪仓库的文件变更进行外科手术式图谱更新，并与代理实时同步 - **Web UI** — 基于 Sigma.js 的力导向可视化，节点大小与重要性成正比 - **IMPLEMENTS 推理** — 对 Go、TypeScript、Java、Rust、C#、Scala、Swift、Protobuf 实现结构接口满足性 - **PreToolUse + PreCompact + Stop 钩子** — PreToolUse 为 Read/Grep/Glob 注入图谱上下文并重定向至 Gortex MCP 工具；匹配 `Task` 同时为派生子代理提供内联工具交换表 + 任务作用域 `smart_context`，避免回退到 grep/Read。PreCompact 在 Claude Code 压缩对话前注入浓缩的方向快照（索引统计、最近修改符号、Top 热区、反馈加权符号）。Stop 在任务后运行诊断（`detect_changes` → `get_test_targets`、`check_guards`、`analyze dead_code`、对变更符号执行 `contracts check`），使代理在交接前自我纠正。所有钩子在桥接不可达时静默降级 - **长期运行守护进程（可选）** — `gortex daemon start` 运行单个共享进程，为每个追踪仓库持有图谱。每个 Claude Code / Cursor / Kiro 窗口通过 Unix 套接字以精简 stdio 代理连接，获得每客户端会话隔离（最近活动、Token 统计） + 默认跨仓库查询。实时 fsnotify 监听每个追踪仓库，文件编辑直接流入图谱而无需手动重载。`gortex init --global` 设置用户级配置；`gortex daemon install-service` 安装 LaunchAgent（macOS）或 systemd `--user` 单元（Linux），由操作系统监督生命周期并自动登录启动 —— 无需 sudo。若守护进程未运行，功能会回退到嵌入式模式；此特性为可添加项 - **基准测试** — 每种语言的解析、查询引擎与索引器基准测试 - **社群技能** — `gortex skills` 自动为每个检测到的社群生成 SKILL.md，包含关键文件、入口点、跨社群连接以及 Claude Code 自动发现的 MCP 工具调用 - **评估框架** — 基于 Docker 的环境与多模型支持，用于 A/B 测试工具有效性的 SWE-bench 框架 - **零依赖** — 全程在进程内、内存中运行，不依赖外部服务 ## 安装 预编译二进制文件发布于 [GitHub Releases](https://github.com/zzet/gortex/releases)，支持 linux/amd64、linux/arm64、darwin/amd64（Intel Mac）与 darwin/arm64（Apple Silicon）。Windows 支持计划中。 **初次使用 Gortex？** 安装后请查阅 [docs/onboarding.md](docs/onboarding.md) 进行 15 分钟引导：`gortex init` → 启动服务 → 验证 AI 助手是否使用图谱工具 → 若未生效的处理方式。 ### macOS — Homebrew ``` brew install zzet/tap/gortex ``` Homebrew 会从 tap 仓库中剥离 `homebrew-` 前缀，因此 `zzet/homebrew-tap` 安装为 `zzet/tap`。更新通过 `brew upgrade`。无 Gatekeeper 提示 —— `brew` 不会在下载时设置 quarantine 属性。 ### Linux — Debian / Ubuntu (.deb) ``` ARCH=$(dpkg --print-architecture) # amd64 or arm64 curl -LO "https://github.com/zzet/gortex/releases/latest/download/gortex_linux_${ARCH}.deb" sudo dpkg -i "gortex_linux_${ARCH}.deb" ``` ### Linux — RHEL / Fedora / CentOS (.rpm) ``` ARCH=$(uname -m); [ "$ARCH" = x86_64 ] && ARCH=amd64; [ "$ARCH" = aarch64 ] && ARCH=arm64 curl -LO "https://github.com/zzet/gortex/releases/latest/download/gortex_linux_${ARCH}.rpm" sudo rpm -ivh "gortex_linux_${ARCH}.rpm" ``` ### Linux — Alpine (.apk) ``` ARCH=$(uname -m); [ "$ARCH" = x86_64 ] && ARCH=amd64; [ "$ARCH" = aarch64 ] && ARCH=arm64 curl -LO "https://github.com/zzet/gortex/releases/latest/download/gortex_linux_${ARCH}.apk" sudo apk add --allow-untrusted "gortex_linux_${ARCH}.apk" ``` ### 直接下载二进制（ Linux 或 macOS） ``` # 选择适合您操作系统/架构的资源 OS=$(uname -s | tr '[:upper:]' '[:lower:]') # linux or darwin ARCH=$(uname -m) case $ARCH in x86_64) ARCH=amd64 ;; aarch64|arm64) ARCH=arm64 ;; esac curl -LO "https://github.com/zzet/gortex/releases/latest/download/gortex_${OS}_${ARCH}.tar.gz" tar -xzf "gortex_${OS}_${ARCH}.tar.gz" sudo mv gortex /usr/local/bin/ ``` 在 macOS 上，若通过浏览器（而非 `curl`）下载，请一次性移除检疫标识： ``` xattr -d com.apple.quarantine /usr/local/bin/gortex ``` ### 验证安装 ``` gortex version ``` ### 从源码构建 需要 Go 1.25+ 以及 C 工具链（tree-sitter 提取器依赖 CGO — 无法绕过）。 ``` git clone https://github.com/zzet/gortex.git cd gortex go build -o gortex ./cmd/gortex/ sudo mv gortex /usr/local/bin/ ``` 或无需克隆： ``` go install github.com/zzet/gortex/cmd/gortex@latest ``` `go install` 会将二进制文件放置到 `$(go env GOBIN)`（默认为 `~/go/bin`）——请确保该路径已在 `PATH` 中。 ## 快速启动 `gortex init` 在终端中启动交互式向导，询问是否使用全局守护进程或每个项目设置，以及是否追踪当前仓库并立即启动服务。脚本或 CI 可使用以下标志跳过提示。 ### 全局模式（推荐用于跨多仓库工作） ``` # 交互模式：引导您选择模式并跟进 cd ~/projects/myapp gortex init # 非交互等效模式（CI / 脚本）： gortex init --global --start --track # 守护进程生命周期： gortex daemon start --detach # spawn in background gortex daemon status # PID, uptime, memory, tracked repos, sessions gortex daemon stop # graceful shutdown + final snapshot gortex daemon restart # stop + start gortex daemon reload # re-read config, pick up new/removed repos gortex daemon logs -n 50 # tail the log file # 登录时自动启动（macOS 上的 launchd，Linux 上的 systemd --user）： gortex daemon install-service gortex daemon service-status gortex daemon uninstall-service # 跟踪 / 不跟踪仓库（守护进程优先调度；当没有守护进程时回退到仅配置模式）： gortex track ~/projects/backend gortex untrack backend # 每个仓库状态与守护进程全局状态共享同一命令 — 它会自动选择： gortex status ``` ### 每个仓库模式 ``` # 在向导中选择 [2]，或省略 --global 标志以保持配置本地化： gortex init /path/to/repo # creates .mcp.json, CLAUDE.md, hooks, commands gortex init --analyze /path/to/repo # indexes first for a richer CLAUDE.md gortex init --hooks /path/to/repo # (re)install hooks only # 独立运行 MCP 服务器（自动通过 stdio 检测守护进程；--no-daemon 强制使用嵌入式模式）： gortex serve --index /path/to/repo --watch gortex serve --no-daemon --watch # explicit embedded mode ``` ### 其他命令 ``` gortex skills /path/to/repo # generate per-community SKILL.md files for Claude Code gortex bridge --index . --web # HTTP bridge API + web graph UI at :4747 gortex savings # cumulative tokens saved + $ avoided across sessions gortex version ``` ## 多仓库工作区 Gortex 可将多个仓库索引到单个共享图谱中，实现跨仓库符号解析、影响分析与导航。 ### 配置 双层配置层级： - **全局配置**（`~/.config/gortex/config.yaml`）— 项目、仓库列表、活动项目、引用标签 - **工作区配置**（每个仓库的 `.gortex.yaml`）— 防护规则、排除项与本地覆盖（工作区设置优先） ``` # ~/.config/gortex/config.yaml active_project: my-saas repos: - path: /home/user/projects/gortex name: gortex projects: my-saas: repos: - path: /home/user/projects/frontend name: frontend ref: work - path: /home/user/projects/backend name: backend ref: work - path: /home/user/projects/shared-lib name: shared-lib ref: opensource ``` ### CLI ``` gortex track /path/to/repo # Add a repo to the workspace gortex untrack /path/to/repo # Remove a repo from the workspace gortex serve --track /path/to/repo # Track additional repos on startup gortex serve --project my-saas # Set active project scope gortex index repo-a/ repo-b/ # Index multiple repos gortex status # Per-repo and per-project stats ``` ### MCP 工具 代理可在运行时无需 CLI 即可管理仓库： | 工具 | 描述 | |------|------| | `track_repository` | 添加仓库并立即索引，持久化至配置 | | `untrack_repository` | 移除仓库并清除节点/边，持久化至配置 | | `set_active_project` | 切换后续查询的作用域项目 | | `get_active_project` | 返回当前项目名称与仓库列表 | 所有查询工具（`search_symbols`、`get_symbol`、`find_usages`、`get_file_summary`、`get_call_chain`、`smart_context`）均支持可选的 `repo`、`project` 与 `ref` 参数用于作用域限定。设置活动项目后，其将作为默认作用域。 ### 工作原理 - **合格节点 ID** — 多仓库模式下，ID 变为 `/::`（例如 `frontend/src/app.ts::App`）；单仓库模式保留原有 `::` 格式 - **跨仓库边** — 解析器在跨仓库边界链接符号，优先同仓库匹配；跨仓库边携带 `cross_repo: true` 标记 - **影响分析** — `explain_change_impact`、`verify_change` 与 `get_test_targets` 会自动沿跨仓库边遍历，按仓库分组结果 - **共享仓库** — 同一仓库可在多个项目中出现，仅索引一次并在项目间共享 - **自动发现** — 在 `.gortex.yaml` 中设置 `workspace.auto_detect: true` 可自动发现父目录中的 Git 仓库 ## 与 Claude Code 配合使用 运行 `gortex init` 后，Claude Code 会自动通过 `.mcp.json` 启动 Gortex。代理可获得： - **斜杠命令**：`/gortex-guide`、`/gortex-explore`、`/gortex-debug`、`/gortex-impact`、`/gortex-refactor` - **全局技能**：安装至 `~/.claude/skills/`，跨仓库可用 - **PreToolUse 钩子**：自动注入图谱上下文与图谱工具建议（Read/Grep/Glob） - **PreCompact 钩子**：在上下文压缩前注入浓缩的方向快照，使代理无需重新探索即可继续 - **Stop 钩子**：任务后诊断 — 待运行测试、防护规则违规、死代码及变更符号的契约问题 — 作为上下文注入代理交接前 - **CLAUDE.md 指令**：强制工具使用表与工作流 ## 与 Kiro 配合使用 `gortex init` 同样会自动设置 Kiro IDE 集成： - **MCP 服务器**：`.kiro/settings/mcp.json` — 40 个只读工具已自动批准（写入工具如 `edit_symbol` 与 `rename_symbol` 需审批） - **导向文件**：`.kiro/steering/gortex-workflow.md`（始终生效）引导 Kiro 优先使用图谱查询而非文件读取。额外的手动导向文件可用于探索、调试、影响分析与重构工作流，通过聊天中的 `#` 访问 - **代理钩子**： - `gortex-smart-context` — 每次提示时从图谱一次性组装任务相关上下文 - `gortex-post-edit` — 保存源文件后显示冲击范围及应运行的测试 - `gortex-pre-read` — 读取源文件前，使用图谱中的符号上下文进行增强 ## 与 Antigravity 配合使用 `gortex init` 同样会自动将项目智能指令加载到 Antigravity 代理： - **知识项（KI）**：在全局 `~/.gemini/antigravity/knowledge/gortex-workflow/` 创建专用 KI - **工作流指令**：指导 Antigropy 助理优先执行 AST 感知的 Gortex CLI 查询（`./gortex query symbol`、`./gortex query dependents`），覆盖通用 `grep` 与文件读取流程 - **Token 效率** — 显著减少上下文 Token 消耗，将 AI 读取严格限制在已验证的依赖路径与函数定义上 ## 与 Cursor 配合使用 `gortex init` 会检测 Cursor（通过 `.cursor/` 目录、`~/.cursor/` 或 PATH 中的 `cursor`）并创建： - **MCP 配置**：`.cursor/mcp.json` — 项目级配置，可提交至仓库，使整个团队自动获得 Gortex ## 与 VS Code / GitHub Copilot 配合使用 `gortex init` 会检测 VS Code（通过 `.vscode/` 目录、`code` 命令或 VS Code 应用数据目录）并创建： - **MCP 配置**：`.vscode/mcp.json` — 项目级 Copilot Chat 代理模式配置。所有 Gortex 工具在 Copilot 代理模式下均可用 ## 与 Windsurf 配合使用 `gortex init` 会检测 Windsurf（通过 `windsurf` 命令或 `~/.codeium/windsurf/` 目录）并创建： - **MCP 配置**：`~/.codeium/windsurf/mcp_config.json` — 全局配置（Windsurf 仅从此位置读取）。合并至现有配置而不覆盖其他服务 ## 与 Continue.dev 配合使用 `gortex init` 会检测 Continue.dev（通过项目中的 `.continue/` 目录或 `~/.continue/`）并创建： - **MCP 配置**：`.continue/mcpServers/gortex.json` — 项目级配置。Continue 从 `.continue/mcpServers/` 目录读取 JSON 格式的 MCP 配置，兼容 Claude/Cursor 格式 ## 与 Cline 配合使用 `gortex init` 会检测 Cline（通过 VS Code 或 Cursor 的全局存储目录）并创建： - **MCP 配置**：`cline_mcp_settings.json` — Cline 扩展的全局存储目录中的配置。包含 `alwaysAllow` 列表用于只读的 Gortex 工具 ## 与 OpenCode 配合使用 `gortex init` 会检测 OpenCode（通过项目中的 `.opencode/` 目录、PATH 中的 `opencode` 或 `~/.config/opencode/`）并创建： - **MCP 配置**：`.opencode/config.json` — 项目级配置，使用 OpenCode 本地格式（`"type": "local"`、`"command"` 作为数组、`"environment"` 用于环境变量）。合并至现有配置而不覆盖其他服务 ## CLI 命令 ``` gortex init [path] Set up Gortex for a project + install global skills gortex serve [flags] Start the MCP server (--bridge to add HTTP API) gortex bridge [flags] Start standalone HTTP bridge API gortex eval-server [flags] Start eval HTTP server for benchmarking gortex skills [path] Generate per-community SKILL.md files gortex context [flags] Generate portable context briefing for a task gortex savings [flags] Show cumulative token savings + cost avoided across sessions gortex index [path...] Index one or more repositories and print stats gortex status [flags] Show index status (per-repo and per-project in multi-repo mode) gortex track Add a repository to the tracked workspace gortex untrack Remove a repository from the tracked workspace gortex query Query the knowledge graph gortex clean Remove Gortex files from a project gortex claude-md [flags] Generate CLAUDE.md block gortex version Print version ``` ### 查询子命令 ``` gortex query symbol Find symbols matching name gortex query deps Show dependencies gortex query dependents Show blast radius gortex query callers Show who calls a function gortex query calls Show what a function calls gortex query implementations Show interface implementations gortex query usages Show all usages gortex query stats Show graph statistics ``` 所有查询命令均支持 `--format text|json|dot`（DOT 输出用于 Graphviz 可视化） ## MCP 工具（44 个） ### 核心导航 | 工具 | 描述 | |------|------| | `graph_stats` | 按类型、语言统计节点/边数量，提供每仓库统计与会级 Token 节省 | | `search_symbols` | 按名称查找符号（取代 Grep）。支持 `repo`、`project`、`ref` 参数 | | `get_symbol` | 符号位置与签名（取代 Read）。支持 `repo`、`project`、`ref` 参数 | | `get_file_summary` | 文件内所有符号与导入。支持 `repo`、`project`、`ref` 参数 | | `get_editing_context` | **主要预编辑工具** — 符号、签名、调用者、被调用者 | ### 图谱遍历 | 工具 | 描述 | |------|------| | `get_dependencies` | 某符号所依赖的内容 | | `get_dependents` | 依赖某符号的内容（冲击范围） | | `get_call_chain` | 调用链（正向） | | `get_callers` | 调用者（反向） | | `find_usages` | 符号的所有引用位置 | | `find_implementations` | 实现某接口的类型 | | `get_cluster` | 双向邻域 | ### 编码工作流 | 工具 | 描述 | |------|------| | `get_symbol_source` | 单个符号的源代码（比 Read 节省约 80% Token）。返回每个调用包含 `tokens_saved` 字段 | | `batch_symbols` | 批量获取多个符号及其源码/调用者/被调用者 | | `find_import_path` | 符号的正确导入路径 | | `explain_change_impact` | 风险分级冲击范围与受影响流程 | | `get_recent_changes` | 自时间戳以来的文件/符号变更 | | `edit_symbol` | 直接通过 ID 编辑符号源码（无需先 Read） | | `rename_symbol` | 跨文件协调重命名并更新所有引用 | ### 代理优化（Token 效率） | 工具 | 描述 | |------|------| | `smart_context` | 任务感知的最小上下文 — 替代 5-10 次探索调用 | | `get_edit_plan` | 依赖有序的多文件重构编辑计划 | | `get_test_targets` | 将变更符号映射到测试文件与运行命令 | | `suggest_pattern` | 从示例提取代码模式（源码、注册、测试） | | `export_context` | 可移植的 Markdown/JSON 上下文简报，供 MCP 外部共享 | | `feedback` | `action: "record"` 报告有用/缺失符号；`action: "query"` 聚合统计（最常用、最遗漏、准确率） | ### 分析 | 工具 | 描述 | |------|------| | `get_communities` | 功能聚类（Louvain）。无 `id` 时列出所有；带 `id` 时返回成员与凝聚度 | | `get_processes` | 发现的执行流程。无 `id` 时列出所有；带 `id` 时返回逐步跟踪 | | `detect_changes` | 将 Git 差异映射到受影响符号 | | `index_repository` | 索引或重新索引仓库路径 | | `contracts` | API 契约。`action: "list"`（默认）检测 HTTP/gRPC/GraphQL/主题/WebSocket/env/OpenAPI；`action: "check"` 检测孤立提供者/消费者 | ### 主动防护 | 工具 | 描述 | |------|------| | `verify_change` | 检查提议的签名变更与所有调用者及接口实现者的兼容性 | | `check_guards` | 评估项目防护规则（`.gortex.yaml`）与变更符号的符合性 | | `audit_agent_config` | 扫描 CLAUDE.md / AGENTS.md / `.cursor/rules` / `.github/copilot-instructions.md` / `.windsurf/rules` / `.antigravity/rules` 中的陈旧符号引用、失效路径与臃肿配置，并通过图谱验证（竞品未提供） | ### 代码质量 | 工具 | 描述 | |------|------| | `analyze` | 统一图谱分析。`kind: "dead_code"`：零入边的符号；`kind: "hotspots"`：高入/出度符号；`kind: "cycles"`：Tarjan 强连通分量；`kind: "would_create_cycle"`：检测新依赖是否形成环路 | | `index_health` | 健康度评分、解析失败、滞留文件、语言覆盖率 | | `get_symbol_history` | 本会话内修改的符号及其变更次数；标记高频变更（3 次以上） | ### 代码生成 | 工具 | 描述 | |------|------| | `scaffold` | 从示例符号生成代码、注册逻辑与测试桩 | | `batch_edit` | 按依赖顺序应用多文件编辑，并在步骤间重新索引 | | `diff_context` | Git 差异增强版（调用者、被调用者、社群、流程、每个文件的风险） | | `prefetch_context` | 根据任务描述与近期活动预测所需符号 | ### 多仓库管理 | 工具 | 描述 | |------|------| | `track_repository` | 运行时添加仓库 — 立即索引并持久化至配置 | | `untrack_repository` | 移除仓库 — 清除节点/边并持久化至配置 | | `set_active_project` | 切换后续查询的活动项目作用域 | | `get_active_project` | 返回当前项目名称及其成员仓库列表 | ## MCP 资源（7 个） | 资源 | 描述 | |------|------| | `gortex://session` | 当前会话状态与活动 | | `gortex://stats` | 图谱统计（节点/边数量） | | `gortex://schema` | 图谱模式参考 | | `gortex://communities` | 社群列表与凝聚度 | | `gortex://community/{id}` | 单个社群详情 | | `gortex://processes` | 执行流程列表 | | `gortex://process/{id}` | 单个流程跟踪 | ## MCP 提示（3 个） | 提示 | 描述 | |------|------| | `pre_commit` | 审查未提交变更 — 显示变更符号、冲击范围、风险等级与受影响测试 | | `orientation` | 在陌生代码库中定位 — 图谱统计、社群、执行流程、关键符号 | | `safe_to_change` | 分析修改特定符号的安全性 — 冲击范围、编辑计划、影响测试 | ## Web UI Gortex 包含一个独立的 Next.js Web 应用（`web/` 目录），共 10 个页面： ``` # 启动后端 gortex bridge --index /path/to/repo --web --port 4747 # 启动 Web UI cd web && npm run dev # 打开 http://localhost:3000 ``` | 页面 | 功能 | |------|------| | **仪表盘** | 健康度、统计数据、语言饼图、节点类型柱状图 | | **图谱探索器** | 基于 Sigma.js + ForceAtlas2 的交互式可视化，支持节点过滤与选择、详情面板 | | **搜索** | 语义搜索通过桥接 API，返回按类型分组的结果 | | **符号详情** | 源码、签名、调用者/被调用者/用法/依赖页签 | | **社群** | 社群卡片展示凝聚度，展开查看成员 | | **流程** | 执行流程表格与步骤列表 | | **分析** | 死代码、热区、环路、索引健康（4 个页签） | | **契约** | API 契约（HTTP/gRPC/GraphQL/主题/WebSocket/env/OpenAPI），提供者/消费者匹配 | | **服务** | 服务级图谱可视化与每仓库统计 | | **AI 聊天** | 带有代码上下文的 LLM 聊天（占位） | 旧版嵌入式 Web UI（Sigma.js 在 `:8765`）仍可通过 `gortex serve --web` 访问。 ## 桥接模式 `gortex bridge` 命令将所有 MCP 工具以 HTTP/JSON API 形式暴露，供外部集成： ``` # 带有 Web UI 的独立桥接 gortex bridge --index /path/to/repo --web --port 4747 # 与 MCP stdio 并行桥接 gortex serve --index /path/to/repo --bridge --port 8765 ``` **端点：** | 端点 | 方法 | 描述 | |------|------|------| | `/health` | GET | 状态、节点/边数量、运行时长 | | `/tools` | GET | 列出所有可用工具及其描述 | | `/tool/{name}` | POST | 调用任意 MCP 工具并传入 JSON 参数 | | `/stats` | GET | 按类型与语言划分的图谱统计 | 默认启用 CORS（`--cors-origin '*'`）。可通过 `--web` 在同一端口提供 UI。 ## 跨仓库 API 契约 Gortex 会检测各仓库中的 API 契约并在提供者与消费者间进行匹配： ``` # 索引完成后会自动检测合约 gortex bridge --index . --web # 通过 MCP 工具 contracts # list all detected contracts (default action) contracts {action: "check"} # find mismatches and orphans ``` | 契约类型 | 检测方式 | 提供者 | 消费者 | |----------|----------|--------|----------| | **HTTP 路由** | 框架注解（gin、Express、FastAPI、Spring 等） | 路由处理器 | HTTP 客户端调用（fetch、http.Get） | | **gRPC** | Proto 服务定义 | 服务 RPC | 客户端存根调用 | | **GraphQL** | Schema 类型/字段定义 | Schema | 查询/变更字符串 | | **消息主题** | 发布/订阅模式（Kafka、NATS、RabbitMQ） | 发布调用 | 订阅调用 | | **WebSocket** | 事件监听/触发模式 | emit() | on() | | **环境变量** | os.Getenv、process.env、.env 文件 | Setenv / .env | Getenv / process.env | | **OpenAPI** | Swagger/OpenAPI 规范文件 | 规范路径 | （关联至 HTTP 路由） | 契约统一规范为规范 ID（如 `http::GET::/api/users/{id}`），跨仓库匹配以检测孤立提供者/消费者与不匹配项。 ## 每社群技能 `gortex skills` 分析代码库，通过 Louvain 聚类检测功能社群，并生成针对性的 SKILL.md 文件，供 Claude Code 自动发现： ``` # 为当前仓库生成技能 gortex skills . # 自定义设置 gortex skills . --min-size 5 --max-communities 10 --output-dir .claude/skills/generated/ ``` 每个生成的技能包含： - **社群元数据** — 大小、文件数量、凝聚度分数 - **关键文件表** — 文件及其符号 - **入口点** — 主函数、处理器、控制器（通过流程分析检测） - **跨社群连接** — 与其他社群的交互 - **MCP 工具调用** — 预编写的 `get_communities`、`smart_context`、`find_usages` 调用 技能写入 `.claude/skills/generated/`，并在 `CLAUDE.md` 的 `` 标记间插入路由表。 ## 语义搜索 混合 BM25 + 向量搜索与 RRF 融合。多级嵌入： ``` # 内置词向量（始终可用，无需设置） gortex serve --index . --embeddings # Ollama（最佳质量，本地） ollama pull nomic-embed-text gortex serve --index . --embeddings-url http://localhost:11434 # OpenAI（最佳质量，云端） gortex serve --index . --embeddings-url https://api.openai.com/v1 \ --embeddings-model text-embedding-3-small ``` | 层级 | 标志 | 质量 | 离线 | 默认构建？ | |------|------|------|------|------------| | Hugot（纯 Go） | `--embeddings` | 良好（MiniLM-L6-v2） | 是（模型自动下载） | **是** | | 内置 | `--embeddings`（Hugot 不可用时） | 基础（GloVe 词平均） | 是 | 是 | | API | `--embeddings-url` | 最佳（变换器模型） | 否 | 是 | | ONNX | `--embeddings` + 构建标签 | 最佳 | 是（模型 + libonnxruntime） | 否 | | GoMLX | `--embeddings` + 构建标签 | 良好 | 是（XLA 插件自动下载） | 否 | 默认构建附带 Hugot，使用纯 Go ONNX 运行时 —— 无原生依赖、无需手动模型放置。MiniLM-L6-v2 模型在首次使用时下载至 `~/.cache/gortex/models/`（约 90 MB）。 按需选择更快后端（通过构建标签）： ``` go build -tags embeddings_onnx ./cmd/gortex/ # needs: brew install onnxruntime go build -tags embeddings_gomlx ./cmd/gortex/ # auto-downloads XLA plugin ``` ## Token 节省 Gortex 追踪相比朴素文件读取节省的 Token 数 —— 每次调用、会话级及跨会话累计： - **每次调用**：`get_symbol_source` 等源读取工具在响应中包含 `tokens_saved` 字段，显示读取完整文件与目标符号的差异 - **会话级**：`graph_stats` 返回 `token_savings` 对象（含 `calls_counted`、`tokens_returned`、`tokens_saved`、`efficiency_ratio`） - **跨会话（累计）**：`graph_stats` 在启用持久化时返回 `cumulative_savings`（含 `first_seen`、`last_updated`、`cost_avoided_usd`，按 Claude Opus/Sonnet/Haiku、GPT-4o、GPT-4o-mini 等模型统计）。数据保存在 `~/.cache/gortex/savings.json` Token 计数使用 **tiktoken (`cl100k_base`)** —— Claude 与 GPT-4 实际使用的分词器，通过 `github.com/pkoukk/tiktoken-go` 提供内联离线 BPE 加载器；首次调用时惰性加载。若初始化失败，组件会回退到遗留的 `chars/4` 启发式算法以保持指标可用。 ## 图谱持久化 Gortex 在关闭时拍摄图谱快照，启动时恢复并仅对变更文件增量重新索引： ``` # 默认缓存目录：~/.cache/gortex/ gortex serve --index /path/to/repo # 自定义缓存目录 gortex serve --index /path/to/repo --cache-dir /tmp/gortex-cache # 禁用缓存 gortex serve --index /path/to/repo --no-cache ``` 持久化层使用可插拔后端接口（`persistence.Store`）。默认后端以 gob+gzip 序列化。缓存键为仓库路径 + Git 提交哈希，并在二进制升级时失效。 ## 架构 ``` gortex binary CLI (cobra) ──> MultiIndexer ──> In-Memory Graph (shared, per-repo indexed) MCP Server ──────────────────────> Query Engine (repo/project/ref scoping) Bridge API ──────────────────────> (HTTP/JSON over MCP tools) Web Server ──────────────────────> (Nodes + Edges + byRepo index) MCP Prompts ─────────────────────> (pre_commit, orientation, safe_to_change) MCP Resources ───────────────────> (session, stats, schema, communities, processes) MultiWatcher <── filesystem events (fsnotify, per-repo) CrossRepoResolver ──> cross-repo edge creation (type-aware) Persistence ──> gob+gzip snapshot (pluggable backend) ``` **数据流：** 1. 启动时加载缓存图谱快照（若可用），否则执行全量索引 2. MultiIndexer 并发遍历每个仓库目录，分派文件至语言特定提取器（tree-sitter） 3. 提取器生成节点（文件、函数、类型等）与边（调用、导入、定义等），并携带类型环境元数据 4. 多仓库模式下，节点携带 `RepoPrefix`，ID 变为 `/::` 5. 解析器以类型感知方式链接跨文件引用；CrossRepoResolver 以同仓库优先原则链接跨仓库引用，并标记 `cross_repo: true` 6. 查询引擎响应遍历查询，支持 `repo`、`project`、`ref` 作用域限定 7. MultiWatcher 检测各仓库变更并以去抖方式修补图谱，随后重新解析跨仓库边 8. 关闭时持久化图谱快照以实现快速重启 ## 图谱模式 **节点类型：** `file`、`function`、`method`、`type`、`interface`、`variable`、`import`、`package` **边类型：** `calls`、`imports`、`defines`、`implements`、`extends`、`references`、`member_of`、`instantiates` **多仓库字段：** 节点携带 `repo_prefix`（单仓库模式下为空）。边携带 `cross_repo`（连接不同仓库时为 `true`）。节点 ID 在多仓库模式下采用 `/::` 格式。 ## 语言支持（33 种） ### 代码语言 | 语言 | 函数 | 方法 + MemberOf | 类型 | 接口 | 导入 | 调用 | 变量 | |------|------|-----------------|------|------|------|------|------| | Go | 完整 | 完整（含接收者） | 完整 | 完整 + Meta["methods"] | 完整 | 完整 | 完整 | | TypeScript | 完整 | 完整 | 完整 | 完整 + Meta["methods"] | 完整 | 完整 | 完整 | | JavaScript | 完整 | 完整 | 完整 | - | 完整 | 完整 | 完整 | | Python | 完整 | 完整 | 完整 | - | 完整 | 完整 | 部分 | | Rust | 完整 | 完整（含 impl 块） | 完整 | 完整 + Meta["methods"] | 完整 | 完整 | 完整 | | Java | 完整 | 完整 | 完整 | 完整 + Meta["methods"] | 完整 | 完整 | 字段 | | C# | 完整 | 完整 | 完整 | 完整 + Meta["methods"] | 完整 | 完整 | 字段 | | Kotlin | 完整 | 完整 | 完整 | 完整 | 完整 | 完整 | 属性 | | Scala | 完整 | 完整 | 完整 | 完整 + Meta["methods"] | 完整 | 完整 | - | | Swift | 完整 | 完整 | 完整 | 完整 + Meta["methods"] | 完整 | 完整 | - | | PHP | 完整 | 完整 | 完整 | 完整 | 完整 | 完整 | - | | Ruby | 完整 | 完整 | 完整 | - | 完整 | 完整 | 常量 | | Elixir | 完整 | 完整（defmodule） | 模块 | - | 完整 | 完整 | 属性 | C | 完整 | - | 结构体/枚举 | - | 完整 | 完整 | 全局变量 | | C++ | 完整 | 完整 | 类/结构体 | - | 完整 | 完整 | - | | Dart | 完整 | 完整 | 类/枚举/混入/扩展 | 抽象接口 | 完整 | 完整 | 完整 | | OCaml | 完整 | 完整（类） | 类型/模块 | 模块类型 | open | 完整 | 完整 | | Lua | 完整 | 完整（M.func/M:method） | - | - | require() | 完整 | 完整 | | Zig | 完整 | - | 结构体/枚举/联合 | - | @import | 完整 | 完整 | | Haskell | 完整 | - | data/newtype/type | class | import | 完整 | - | | Clojure | 完整（defn） | - | defrecord/deftype | defprotocol | require/use | 完整 | def | | Erlang | 完整 | - | -type/-record | - | -import | 完整 | - | | R | 完整 | - | - | - | library/require/source | 完整 | 完整 | | Bash/Zsh | 完整 | - | - | - | source/. | 完整 | 出口 | ### 数据与配置语言 | 语言 | 提取内容 | |------|----------| | SQL | 表（含列）、视图、函数、索引、触发器 | | Protobuf | 消息（含字段）、服务 + RPC、枚举、导入 | | Markdown | 标题、本地文件链接、代码块语言 | | HTML | 脚本/链接引用、元素 ID | | CSS | 类选择器、ID 选择器、自定义属性、@import | | YAML | 顶层键 | | TOML | 表、键值对 | | HCL/Terraform | 资源/数据/模块/变量/输出块（.tf、.tfvars、.hcl） | | Dockerfile | FROM（基础镜像）、ENV/ARG 变量 | ## 构建 ``` make build # Build with version from git tags make test # go test -race ./... make bench # Run all benchmarks make lint # golangci-lint make fmt # gofmt -s make install # go install with version ldflags ``` 需要 Go 1.21+ 并启用 CGO（tree-sitter C 绑定依赖 CGO — 无法绕过）。 ## 许可证 Gortex 在 **源代码可用** 许可下发布，基于 PolyForm Small Business 定制许可。参见 [LICENSE.md](LICENSE.md) 获取完整条款。 **免费用于：** 个人、开源项目、少于 50 名员工或年收入低于 50 万美元的小型企业、非营利组织、教育机构、政府机构、社会关键组织。 **商业许可要求：** 拥有 50 名以上员工或年收入 50 万美元以上的组织、竞争产品、转售/捆绑。联系 [license@zzet.org](mailto:license@zzet.org)。 **贡献者：** 活跃贡献者可在 [CONTRIBUTORS.md](CONTRIBUTORS.md) 中获得其雇主的免费非竞争商业许可。 ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解添加语言提取器、提交 PR 的指南。活跃贡献者可获得 [贡献商业许可](LICENSE.md#part-3-contributor-license)。

标签：Agent反馈循环, AI编码代理, Anchore, BM25, C++, CNCF毕业项目, DNS解析, GloVe, Go, Hugo, MCP服务器, MiniLM, ONNX, Python, RRF融合, Ruby工具, Rust, SEO, TCP SYN 扫描, Token压缩, TypeScript, Web UI, 上下文智能获取, 代码导航, 代码智能引擎, 内存图数据库, 叙事型仓库概览, 向量搜索, 多语言支持, 安全插件, 安全测试框架, 客户端加密, 开源项目, 循环检测, 数据擦除, 无后门, 日志审计, 死代码检测, 测试覆盖率, 热点分析, 符号查找, 索引引擎, 编辑上下文, 网络流量审计, 语义搜索, 调用链分析, 跨仓库解析, 重命名符号, 重构工具