vaelor

# Vaelor **给你的代码代理一个无法从 grep 获取的代码库记忆。** <p align="center"> <img src="docs/hero-demo.gif" width="820" alt="Vaelor 了解 ParseFile：在代理编辑核心函数之前，它会看到爆炸半径——跨三个包的生产调用者、顶级 1% 结构中心性和覆盖它的测试。"> </p> Vaelor 是 [Krolik](https://krolik.tools) 背后的开源引擎：一个自托管的 [MCP](https://modelcontextprotocol.io/) 服务器，它解析、绘制和监视代码库，以便 AI 代理不必每次会话都重新发现它。 tree-sitter AST 解析支持 16 种语言，为调用图提供类型感知的 Go 解析（`go/types`）、持久的 Apache AGE 知识图和混合语义搜索。 `review_pr` 记录上次审查符号时出了什么问题。 `debug_investigate` 将 Prometheus 警报和 Jaeger 跟踪关联回导致问题的函数。 [](LICENSE) [](go.mod) [快速开始](#快速开始) 只需三个命令。如果它有用，一颗星可以帮助下一个人找到它。 ## 为什么不直接使用 grep 或代码索引？ 每个代码搜索工具都能找到函数。较少的工具能告诉代理更改时还会有什么问题，而更少的工具能记住您上次审查或生产事件的情况。 | | 组织范围的代码搜索 | 会话范围的代理工具 | 主机 PR 审查机器人 | Vaelor | |---|---|---|---|---| | 用途 | 跨索引组织进行全文和符号搜索，为代理提供上下文 | 导航和在一个代理会话内编辑 | 自动审查 PR 评论，作为托管服务 | 通过一个 MCP 端点运行您自己的搜索、调用图、爆炸半径和实时事件 | Vaelor 的 Apache AGE 图包含从实际调用图计算的 PageRank、社区和惊喜分数，这些分数直接馈送到 `understand`、`prepare_change` 和 `review_pr`。 `review_pr` 还保留了每个符号的实际 GitHub 审查结果的裁决，并且 `understand` 会在下次有人触摸该符号时自动显示它，从而使“这次审查失败”的事实随着代码一起移动，而不是存储在某人的记忆中。 `debug_investigate` 更进一步：它将实时 Prometheus 警报和 Jaeger 跟踪与同一个调用图融合，生成一个排名的 `file:function` 假设，以便问题解决为代码，而不仅仅是仪表板警报。 代理对哪个更改有风险的感知来自实际代码库的形状，并在每次图更新时重新计算。 ## 快速开始 ### Docker（推荐） ```bash docker build -t go-code . docker run -p 8897:8897 \ -e LLM_API_BASE=http://host.docker.internal:8317/v1 \ -e LLM_API_KEY=your-key \ go-code ``` ### 从源代码 需要 Go 1.24+ 和 C 编译器（用于 tree-sitter 语法中的 CGO）。 ```bash make build # → bin/go-code ./bin/go-code ``` ### 注册为 MCP 服务器 ```bash claude mcp add -s user -t http go-code http://127.0.0.1:8897/mcp ``` ### 试用 不需要本地克隆：`understand` 和 `call_trace` 直接获取 GitHub 仓库，并在第一次调用时获取它。该第一次调用会索引仓库，因此需要几秒钟；之后会缓存它。从一个小仓库开始： ```json { "tool": "call_trace", "arguments": { "repo": "gorilla/mux", "symbol": "ServeHTTP", "direction": "callees", "depth": 2 } } ``` 遍历 `Router.ServeHTTP` 通过路由路径并检测循环 - 无需 Docker 卷挂载和 `DATABASE_URL`。 如果没有 `LLM_API_KEY`？大多数工具仍然运行；它们只跳过叙述层和排名层。参见 [LLM 依赖](#llm-依赖) 以了解确切的降级内容。 ## 它能做什么 ### 了解代码库 `explore`: 远程仓库的快速、无克隆概览。 `understand`: 符号深入解析，涵盖调用者、被调用者、复杂度、死代码分数和任何先前的审查裁决。 `code_research`: 适用于 10k+ 文件 monorepos 的 BM25F + 嵌入 + 图扩展。 ### 知道更改会破坏什么 `impact_analysis`: 可配置的爆炸半径深度（默认为 5）。 `prepare_change`: 影响分析和死代码检查合并。 `call_trace`: 双向调用链，带有循环检测和 LLM 叙述。 ### 按含义搜索，而不是关键字 `semantic_search`: pgvector + 混合 RRF + 1 跳图扩展。 `symbol_search`、`code_search`、`github_code_search`（无需克隆）。 ### 审查和记住 `review_pr` / `review_delta`: git refs 之间的差异化爆炸半径，发布到 GitHub 并持久化每个符号的学习。 `code_compare`: 两个仓库之间的结构差异，涵盖架构、API 设计、质量。 `rewrite`: 跨 16 种语言的结构 AST 搜索替换，干预运行。 ### 调试实际运行的程序，而不仅仅是 diff 中的程序 `debug_investigate`: 7 阶段的生产事件根本原因，从指标峰值和失败跟踪到符号解析、调用图遍历、LLM 融合和运行时二进制漂移，排名到 `file:function`。 `fleet_versions`: 差异化源码中固定的镜像标签和实际部署的镜像。 `dataflow`: 污点跟踪、死存储、SQL/命令注入接收器。 `dead_code` 和 `code_health`: 涵盖复杂性、测试覆盖率、依赖新鲜度、OSV 漏洞的 A-F 等级。 ### 其他值得了解的内容 `find_duplicates`: 通过语义相似性查找仓库中的近似重复符号（需要 `EMBED_URL` + `DATABASE_URL`）。 `suggest_reviewers`: 根据作者身份、共同更改耦合性和最近性对 PR 的文件路径进行排名。 这是一组主要的工具，而不是全部工具。下表记录了稳定的工具；运行服务器上的 `tools/list` 以获取完整、当前的工具列表。 ## 工具参考 稳定的、文档化的工具集。服务器还公开了几个工具；运行实例上的 `tools/list` 是权威的、当前的工具列表。 | 工具 | 描述 | |------|-------------| | `repo_analyze` | 分析仓库。深层模式（AST + LLM）、快速模式（GitHub 代码搜索）或问题/拉取请求搜索 | | `repo_search` | 通过并行网络搜索 + GitHub/GitLab API、LLM 排名，在-forge 中发现仓库 | | `github_code_search` | 通过代码搜索 API 在 GitHub 上搜索代码。返回文件路径和匹配片段 | | `file_parse` | 使用 tree-sitter 解析单个文件。返回符号表或原始 AST | | `code_compare` | 在结构上比较两个仓库：架构、API 设计、代码质量 | | `dep_graph` | 构建依赖图。以 Mermaid、Graphviz DOT 或 JSON 输出 | | `symbol_search` | 按名称模式跨仓库搜索符号（函数、类型、常量） | | `code_search` | 类似 grep 的搜索，带有正则表达式和路径全局过滤，包含上下文行 | | `call_trace` | 跟踪调用链：被调用者（正向）或调用者（反向），具有深度控制 | | `code_graph` | 通过自然语言查询持久代码知识图（Apache AGE） | | `debug_investigate` | 7 阶段的生产事件根本原因：Prom 峰值 + Jaeger 失败跟踪 + 符号解析 + 调用图遍历 + LLM 融合 + 运行时二进制漂移，排名到 `file:function` | | `semantic_search` | 混合 RRF：BM25F + pgvector + 1 跳 AGE 图扩展。按概念而非关键字查找 | | `understand` | 类型感知的符号深入解析。聚合 `call_trace` + `symbol_search` + 复杂度 + `tested_by` + 死代码分数 + 先前学习 | | `impact_analysis` | 可配置的爆炸半径深度（默认为 5）。直接调用者、传递调用者、按更改热度排序的热点 | | `prepare_change` | 更改前风险：影响分析 + 死代码检查合并 | | `dead_code` | 置信度评分的未使用符号检测，而非平面列表 | | `dataflow` | IL/CFG 污点跟踪、死存储、SQL/命令注入接收器 | | `rewrite` | 跨 16 种语言的结构 AST 搜索替换，带有 `$WILDCARDS`，干预运行 | | `review_pr` | git refs 之间的差异化爆炸半径；持久化每个符号的学习 | | `review_delta` | 两个 git refs 之间的差异化爆炸半径 | | `code_research` | 适用于 10k+ 文件 monorepos 的 BM25F + 嵌入 + DAG 扩展 | | `design_search` | 通过 UI 描述查找 `DESIGN.md` 系统（多语言-e5-large，1024-dim） | | `resolve_frame` | 通过源映射取消 JS 堆栈帧的压缩 | | `site_analyze` | 技术栈和 SEO 审计、BFS 爬虫 | | `site_crawl` | BFS 网络爬虫 | | `code_health` | 仓库评分 A-F：复杂度、测试覆盖率、依赖新鲜度、OSV 漏洞 | | `explore` | 快速仓库概览，无 LLM，无克隆远程仓库 | | `fleet_versions` | 差异化源码中固定的容器镜像引用和部署的运行时容器。捕获“配置对齐、源码看起来正确、行为错误”的 bug 类 | | `find_duplicates` | 通过语义相似性查找仓库中的近似重复符号。需要 `EMBED_URL` + `DATABASE_URL` | | `suggest_reviewers` | 根据作者身份、共同更改耦合性和最近性对 PR 的文件路径进行排名 | | `remember_graph_insights` | 持久化学习，以便在未来的 `understand` 调用中显示 | | `wp_plugin_search` | 搜索 WordPress.org 插件目录 | > **可选边车。** `dead_code` 和 `code_health` 从 AST-only 启发式方法改进为置信度评分的结果，当 [ox-codes](https://github.com/anatolykoptev/ox-codes) （Rust）与 Vaelor 一起运行时。 `semantic_search` 需要嵌入式服务端； [ox-embed-server](https://github.com/anatolykoptev/ox-embed-server) （ONNX 嵌入、交叉编码器重排序、SPLADE）是参考服务端。两者都不需要运行 Vaelor，每个工具在没有它们的情况下仍然返回实际结果，只是粗糙一些。 ## 学习循环 `review_pr`（使用 `dry_run=false`）在完成的 GitHub 审查时为每个更改的符号写入一个学习：`APPROVE` 映射到 `good`、`REQUEST_CHANGES` 映射到 `bad`，其他所有情况都是 `neutral`。干预路径写入同一个记录的风险级别。下次有人调用该符号的 `understand` 时，`Store.Nearest` 查找最近的学习并将它们附加为 `prior_learnings` 在结果上，无需额外调用。循环以 `LEARNINGS_DATABASE_URL` 为条件（默认为 `DATABASE_URL`）；如果两者都没有设置，它会静默跳过而不是出错。 ## 图信号生态系统 两个图表示通过 `internal/graphx` 合作，而不让任何包了解另一个包，因此在没有图快照的情况下，每个消费者都会降级为字节相同的输出。 | 信号（AGE 计算） | 被消费 | |---|---| | PageRank、社区 | `understand`（`graph_analytics`）、`prepare_change`（`communities_crossed`、`high_pagerank_callers`） | | 惊喜分数 | `review_pr`（≥0.5 的 `high_surprise` 标志） | | 处理/获取（跨语言路由） | `call_trace`（在 +1 深度跨服务边界获取节点） | ## 运行时版本感知 当生产错误发生在部署的二进制级别而不是源代码时（固定标签漂移、主机分歧、静默自动更新），Vaelor 可以探测正在运行的容器并将它们与索引仓库固定的内容进行差异。 - `fleet_versions`: 显式工具。传递 `host`（默认为本地 Docker 套接字）和可选的 `service` 过滤器。返回每个目标的差异：`Match` / `TagDrift` / `DigestDrift` / `OnlySource` / `OnlyRuntime` / `Unresolved`。 - `debug_investigate` 阶段 7：当启动调查时自动运行 `host` 设置。漂移进入 LLM 提示，优先级上限为前 20 个非 `Match` 差异，按 `TagDrift` > `DigestDrift` > `Unresolved` > `OnlyRuntime` > `OnlySource` 排序。 ### SSH 探针 到达远程主机直接使用系统 `ssh` 二进制文件，因此 Vaelor 不维护自己的 SSH 堆栈，因此 `~/.ssh/config`（ProxyJump、代理、身份、端口、known_hosts）是唯一的真相来源。驱动程序默认为关闭；启用 `GOCODE_FLEET_SSH_ENABLE=true`。远程主机上的命令仅限于内部允许列表，确切地说是 `docker ps --no-trunc --format={{json .}}`，并在 exec 调用之前对过滤值进行正则表达式验证。 | 环境变量 | 默认值 | 用途 | |---|---|---| | `GOCODE_FLEET_DEFAULT_HOST` | `""` | `debug_investigate` 阶段 7 的默认主机。空 = 跳过 | | `GOCODE_FLEET_DOCKER_SOCKET` | `/var/run/docker.sock` | 本地 Docker 引擎套接字路径 | | `GOCODE_FLEET_SSH_ENABLE` | `false` | 必须为 `true` 使用 `ssh://` 目标 | | `GOCODE_FLEET_SSH_BINARY` | `ssh` | 系统 ssh 二进制文件，默认为 PATH 解析 | | `GOCODE_FLEET_TIMEOUT` | `10s` | 每个探针超时 | ## 配置 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `MCP_PORT` | `8897` | HTTP 服务器端口 | | `LLM_API_BASE` | `http://127.0.0.1:8317/v1` | OpenAI 兼容的 LLM 端点 | | `LLM_API_KEY` | *(可选)* | 参见 [LLM 依赖](#llm-依赖) 以下 | | `LLM_MODEL` | `cerebras-gpt-oss-120b` | 模型名称（新鲜部署的后备；部署时重写） | | `GITHUB_TOKEN` | *(可选)* | 更高的 API 速率限制、私有仓库 | | `WORKSPACE_DIR` | `/tmp/go-code-workspace` | 克隆仓库的临时目录 | | `MAX_FILE_KB` | `512` | 要解析的最大文件大小（KB） | | `MAX_REPO_MB` | `200` | 要接受的最大仓库大小（MB） | | `REDIS_URL` | *(可选)* | L2 解析/LLM 缓存的 Redis URL | | `DATABASE_URL` | *(可选)* | Apache AGE 代码图的 PostgreSQL DSN（`code_graph`、`learning loop` 和上面的图信号需要） | | `EMBED_URL` | *(可选)* | 嵌入式服务端端点（`semantic_search` 需要） | | `GITHUB_WEBHOOK_SECRET` | *(可选)* | 设置以启用 `/webhook/github` PR 审查接收器 | 完整的环境变量参考（SearXNG、GitLab、备用模型链、fleet SSH、索引调优）：[CLAUDE.md](CLAUDE.md). ### LLM 依赖 `LLM_API_KEY` 是可选的。服务器启动时，大多数工具都运行而无需它： | 类别 | 工具 | 无 `LLM_API_KEY` 行为 | |----------|-------|-------------------------------| | **Hard** | `code_graph`（NL 查询）、 `repo_search` | 返回一个 MCP 错误：*"requires LLM_API_KEY to be set"* | | **Soft** | `repo_analyze`（快速/原始模式）、问题/拉取请求搜索 | 返回确定性结果加 `(LLM unavailable)` 标记 | | **Augment** | `call_trace`、`dead_code`、`impact_analysis` | 完整核心输出；叙述/增强字段为空 | | **Debug** | `debug_investigate` | 运行确定性阶段（跟踪分析、指标分析、报警违规、警报违规）；LLM 假设排名被跳过并设置 `LLMSkippedReason` 设置 `LLM_API_BASE` + `LLM_API_KEY` + `LLM_MODEL` 以全功能运行每个工具。任何 OpenAI 兼容的端点都有效：OpenAI、Anthropic 通过代理、本地 Ollama 实例。 ## 架构 ``` cmd/go-code/ : MCP 服务器、工具处理程序（每个工具一个文件） internal/ parser/ : tree-sitter AST 解析，16 种语言处理程序 ingest/ : 仓库克隆、文件遍历、gitignore 过滤 clean/ : 代码清理以获取 LLM 上下文 render/ : 渲染模式（签名、骨架、聚焦） analyze/ : 分析编排 compare/ : 结构差异引擎 callgraph/ : 调用链跟踪（BFS/DFS，双向），Go 类型感知 codegraph/ : Apache AGE 知识图 embeddings/ : 语义搜索：pgvector 存储、嵌入管道、混合 RRF、图扩展 learnings/ : pgvector 支持的先前审查发现存储 investigate/ : Prometheus + Jaeger `debug_investigate` 相关性 fleet/ : 部署与源代码的容器镜像漂移 github/ : GitHub API（搜索代码/问题/仓库、元数据） llm/ : 带有重试和备用密钥的 LLM 客户端 cache/ : 通用 LRU 缓存，带有 Redis L2 ``` ## 分析模式 **深度模式（默认）。** 克隆仓库，遍历文件树，使用 tree-sitter 解析 AST，构建符号表，并通过 LLM 回答问题。`depth` 控制上下文大小（概述/模块/深度），`mode` 控制渲染（签名/骨架/聚焦）。 **快速模式（`mode=quick`）。** GitHub 代码搜索 API，无克隆。返回匹配的代码片段，可选地由 LLM 总结。`mode=raw` 完全跳过 LLM 步骤。 **问题/拉取请求模式（`type=issue` 或 `type=pr`）。** 搜索 GitHub 问题/拉取请求。结构化结果包含状态、标签、作者和趋势的 LLM 读取。 ## Webhook `POST /webhook/github` 在 MCP 端口（`:8897`）处理 `pull_request` 事件（打开/同步/重新打开）。需要 `X-GitHub-Event` 和 `X-Hub-Signature-256` 头部以及 `GITHUB_WEBHOOK_SECRET` 设置。`REVIEW_POST_ENABLED=true` 将评论发布到 GitHub；否则它会干预日志。通过现有的隧道暴露它，并在仓库的 webhook 设置中注册它。 ## 传输 - **HTTP**（默认）：`MCP_PORT` 上的流式 HTTP - **stdio**： `./go-code --stdio` 用于管道/SSH 访问 ## 构建 ```bash make build # 构建二进制文件（需要 CGO） make lint # 运行 golangci-lint make test # 运行测试 make deploy # Docker 构建 + 部署 ``` ## 许可证 [](LICENSE) Apache 2.0 版权 2026 Anatoly Koptev. ## 贡献 参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以添加新工具或新语言。 有关安全漏洞，请参见 [SECURITY.md](SECURITY.md)。请不要为这些漏洞公开问题。