Graphify 用本地语法解析构建代码知识图谱

English | 简体中文 | 日本語 | 한국어 | Deutsch | Français | Español | हिन्दी | Português | Русский | العربية | فارسی | Italiano | Polski | Nederlands | Türkçe | Українська | Tiếng Việt | Bahasa Indonesia | Svenska | Ελληνικά | Română | Čeština | Suomi | Dansk | Norsk | Magyar | ภาษาไทย | Oʻzbekcha | 繁體中文 | Filipino | עברית

将智能体的 Token 开销降低 80%。Graphify Cloud 提供始终在线的记忆，管控智能体行为，保持高代码质量，并通过形式化验证证明正确性。开启 14 天免费试用 →

在 AI 编程助手中输入 /graphify，它就会将整个项目（代码、文档、PDF、图片、视频）映射为可查询的知识图谱，让你通过查询获取信息，无须再用 grep 在文件中搜索。

代码映射免费，完全在本地运行。代码通过 tree-sitter AST 解析：结果确定、不使用 LLM，任何内容都不会离开你的机器。（文档、PDF、图片和视频则使用助手的模型或配置的 API 密钥进行语义分析。）

每条边都有说明。每个连接都会标记为 EXTRACTED（源内容中明确存在）或 INFERRED（由 graphify 解析推断），让你能够区分哪些信息是直接读取的，哪些是推断得到的。

这不是向量索引。没有嵌入向量，也没有向量存储：它是可以遍历的真正图结构。你可以提问、追踪两个事物之间的路径，或让它解释某个概念。

希望它始终在线？Graphify Cloud 让图谱在整个软件开发生命周期（SDLC）中持续更新：支持 monorepo 和跨仓库关联、形式化验证，以及能够纵览整个 SDLC 的代码审查；还提供 Sentry、Jira 等连接器，让事件和工单与你的代码处于同一张图谱中。前往 app.graphify.com 开启 14 天免费试用。

graphify 映射出的 FastAPI 代码库。每个节点代表一个概念，颜色表示检测到的社群，所有内容都可以在 graph.html 中点击查看。

快速上手（30 秒）。需要 Python 3.10+ 和 uv（或 pipx）：

uv tool install graphifyy      # install the CLI (or: pipx install graphifyy)
graphify install               # detects your assistant and registers the skill

然后，在 AI 助手中输入：

/graphify .

就这么简单。你会得到三个文件：

graphify-out/
├── graph.html       open in any browser: click nodes, filter, search
├── GRAPH_REPORT.md  the highlights: key concepts, surprising connections, suggested questions
└── graph.json       the full graph: query it anytime without re-reading your files

持久化保存的图谱包含 graph.schema_version，便于集成工具检测不兼容的格式变更；还包含 graph.graphify_version，用于标识生成该图谱的 Graphify 版本。

一次安装，适配各种助手和操作系统。在 macOS、Linux 和 Windows 上支持 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot，以及另外 20 多种助手：选择你的平台即可。

图谱构建完成后，你就可以查询图谱，无须读取文件。以下是在上面展示的 FastAPI 代码库上运行 graphify 的实际输出：

$ graphify explain "APIRouter"
Node: APIRouter
  Source:    routing.py L2210
  Community: 2
  Degree:    47

Connections (47):
  --> RequestValidationError [uses] [INFERRED]
  --> Dependant [uses] [INFERRED]
  --> .get() [method] [EXTRACTED]
  <-- __init__.py [imports] [EXTRACTED]
  ...

$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

每条边都带有置信度标签（EXTRACTED = 源内容中明确存在，INFERRED = 通过解析推导得出），让你能够区分哪些信息是直接读取的，哪些是推断得到的。graphify query "<question>" 会针对自然语言问题返回限定范围的子图，graphify path A B 则会追踪任意两个事物之间的连接方式。

开箱即用的功能：

需要在多个仓库或 monorepo 中运行？Graphify Cloud 可以持续完成这些工作，将智能体的 Token 开销降低 80%，并提供跨仓库关联、覆盖整个 SDLC 的代码审查、形式化验证，以及 Sentry/Jira 连接器。开启 14 天免费试用 →

基准测试：recall@10 为 0.497，LLM 额度消耗为 0

所有系统都在同一套测试框架中运行，使用相同的模型和预算，由一个评判模型打分，并通过第二个评判模型进行盲法验证（一致率为 90.6%，Cohen's kappa 为 0.81）。各系统的完整结果表、代码智能评测结果和复现命令见 BENCHMARKS.md。

完整指南和参考文档位于 docs.graphify.com：

快速入门：构建你的第一张图谱

CLI 参考：所有命令和参数选项

提出更好的图谱问题：查询模式

配置：环境变量与调优

支持的输入：语言与文件类型

团队工作流与 PR 审查

故障排查与工作原理

macOS 快速安装（Homebrew）：

brew install python@3.12 uv

Windows 快速安装：

winget install astral-sh.uv

sudo apt install python3.12 python3-pip pipx
# or install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

官方软件包：PyPI 包名为 graphifyy（两个 y）。PyPI 上其他 graphify* 软件包与本项目无关。CLI 命令仍为 graphify。

官方源码仓库是 Graphify-Labs/graphify。

本 README 顶部提供了只需两条命令的快速入门步骤。本节介绍安装方式、项目范围内的安装，以及所有受支持的平台。

安装方式（任选一种）：

uv tool install graphifyy   # recommended, isolated env (if 'graphify' isn't found after, run: uv tool update-shell)
pipx install graphifyy      # alternative
pip install graphifyy       # may need PATH setup, see Troubleshooting below

然后运行一次 graphify install。它会检测你使用的助手并注册技能，因此无须针对每个助手单独配置。打开 AI 助手并输入 /graphify .。

如果要将助手技能安装到当前仓库，而不是用户配置目录，请添加 --project：

graphify install --project
graphify install --project --platform codex

项目级安装会将文件写入当前目录，例如 .claude/skills/graphify/SKILL.md 或 .agents/skills/graphify/SKILL.md（以及一个由技能按需加载的 references/ 配套目录），并针对可提交的文件输出 git add 提示。支持项目级安装的各平台命令都接受同一个标志，例如 graphify claude install --project 或 graphify codex install --project。

遇到 command not found、Mac/Windows 上的 pip 问题、PowerShell 引号问题、uvx 用法问题、git hook 的 PATH 问题，或严格模式问题？请参阅“安装与故障排查”。

Codex 用户还需要在 ~/.codex/config.toml 的 [features] 下设置 multi_agent = true，才能进行并行提取。CodeBuddy 使用与 Claude Code 相同的 Agent 工具和 PreToolUse hook 机制。Factory Droid 使用 Task 工具并行调度子智能体。OpenClaw 和 Aider 使用串行提取（这些平台对并行智能体的支持仍处于早期阶段）。Trae 使用 Agent 工具并行调度子智能体，但不支持 PreToolUse hook，因此通过 AGENTS.md 实现始终生效的指导机制。

--platform agents（别名为 --platform skills）面向通用的跨框架 Agent-Skills 目录：全局安装使用规范定义的用户级全局目录 ~/.agents/skills/（由 npx skills 和符合规范的框架读取），项目级安装（--project）则使用 ./.agents/skills/。不带平台参数的 graphify install 按设计仅面向单个平台（Claude Code）：如果希望任何读取 .agents/skills 的框架都能发现该技能，请显式指定 agents 平台。

Pi 没有 PreToolUse hook，因此 graphify pi guard install 会注册一个原生 Pi 扩展（通过 Pi 自身的 pi install <package directory>），在 Pi 调用 read、grep、find 以及用于搜索的 bash 命令之前，运行已安装的 graphify hook-guard。图谱是否最新的判断，以及 GRAPHIFY_HOOK_STRICT=1 在每个会话中对索引内文件读取实施一次拒绝的行为，都来自同一套策略，因此 Pi 的行为与 Claude Code 的 hook 一致；指导信息以 <system-reminder source="graphify"> 引导消息的形式传递。这需要 Pi 0.58.4 或更高版本：更早的版本会因一条引导消息而跳过当前并行工具调用批次中的其余调用。该扩展包随 Graphify 安装一起提供，因此请持久安装 Graphify（使用 uv tool install graphifyy 或 pipx install graphifyy，而不是 uvx），并在安装或升级后重启 Pi；卸载时使用 graphify pi guard uninstall。它只检查本地文件目标；该 hook 要求 graphify 位于项目之外的绝对 PATH 条目中，单次调用限制为两秒、256 KiB 输入和 64 KiB 输出，并在失败时放行。同一个扩展包也可在 Oh My Pi 中加载：omp plugin install "$(graphify pi guard path)"。注册的路径包含 Python 版本和虚拟环境，因此更改其中任意一项后，都需要重新运行 graphify pi guard install，并使用 pi remove <old path> 移除旧条目。

Codex 使用 $graphify，而不是 /graphify。

让你的助手始终使用图谱

构建图谱后，在项目中执行一次以下操作：

在项目中运行一次 graphify <platform> install，例如 graphify claude install 或 graphify codex install（也可以使用 graphify install --platform <name>）。

这会写入一个小型配置文件，告诉助手在回答代码库相关问题时查阅知识图谱，并优先使用 graphify query "<question>" 这样的限定范围查询，而不是读取完整报告或对原始文件执行 grep。

支持 hook 的平台（Claude Code、Gemini CLI）：hook 会在搜索类工具调用之前自动触发（在 Claude Code 中，也会在通过 Read/Glob 工具逐个读取源文件之前触发），引导助手使用图谱查询路径。

使用指令文件的平台（Codex、OpenCode、Cursor 等）：持久化指令文件（AGENTS.md、.cursor/rules/ 等）会提供相同的“查询优先”指导。

GRAPH_REPORT.md 仍可用于整体架构审查。

各平台具体写入哪些文件（CodeBuddy 的 CODEBUDDY.md 和 PreToolUse hook、Codex 的 AGENTS.md、Kilo 的原生 .kilo 插件、Cursor 的 alwaysApply 规则等），请参阅“始终生效的配置”。

要一次性从所有平台移除 graphify，请运行 graphify uninstall（添加 --purge 还会删除 graphify-out/）。也可以使用各平台专用的命令（例如 graphify claude uninstall）。

CLI 技能还是 MCP 指令？

graphify install 安装的指令与 Graphify MCP 连接提供的指令，描述的是查询图谱的不同方式：

两者都鼓励先进行限定范围的图谱查询，再开展大范围源码搜索。请选择与你的助手实际可访问的工具相匹配的指令；这两套指令都没有为助手的指令文件确立通用的优先级规则。如果同时使用这两种集成，请明确各自查询的是哪个图谱，并选择一条主要查询路径，而不是将两段无条件生效的指令都复制到 AGENTS.md 中。

graphify install 安装的是本地助手集成，并不会建立 MCP 连接。MCP 客户端无需运行本地 CLI 查询，就能使用其连接的服务器。本地托管的服务器仍然需要独立的 Graphify 安装和图谱，而托管连接提供的图谱可能并不存在于客户端的工作目录中。如果缺少预期的工具，请检查对应的 CLI 安装或 MCP 连接，而不要将另一套配置的指令视为可以互换。

GRAPH_REPORT.md 汇总了超级节点、社区和关键路径，供整体架构审查使用。关于图谱的构建方式及其包含的内容，请参阅“graphify 的工作原理”。

支持处理哪些文件：约 40 种语言

graphify 使用 tree-sitter AST 在本地解析约 40 种编程语言，并通过可选的语义处理步骤，将文档、PDF、图像和音视频映射到图谱中。完整列表请参阅“支持的输入”。

/graphify .                        # build graph for current folder
/graphify ./docs --update          # re-extract only changed files
/graphify . --cluster-only         # rerun clustering without re-extracting
/graphify . --cluster-only --resolution 1.5      # more granular communities
/graphify . --cluster-only --exclude-hubs 99     # suppress utility super-hubs from god-node rankings
/graphify . --no-viz               # skip the HTML, just the report + JSON
/graphify . --wiki                 # build a markdown wiki from the graph
graphify export callflow-html      # Mermaid architecture/call-flow HTML (auto-regenerates on every git commit if hook is installed)

/graphify query "what connects auth to the database?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"

/graphify add https://arxiv.org/abs/1706.03762   # fetch a paper and add it
/graphify add <youtube-url>                       # transcribe and add a video

graphify hook install              # auto-rebuild on commit + branch checkout (run `graphify update .` after `git pull`: see "Recommended workflow" below)
graphify merge-graphs a.json b.json              # combine two graphs

graphify prs                       # PR dashboard: CI state, review status, worktree mapping
graphify prs 42                    # deep dive on PR #42 with graph impact
graphify prs --triage              # AI ranks your review queue (uses whatever backend is configured)
graphify prs --conflicts           # PRs sharing graph communities: merge-order risk

请参阅下方的完整命令参考。

graphify 遵循 .gitignore，并支持 --exclude 模式和项目级 .graphifyignore。详情请参阅“配置”。

项目配置

在扫描根目录创建 .graphifyrc，用于保存属于项目本身、而非某次运行的设置。每行一个 key=value；以 # 开头的行是注释。

存在歧义的扩展名。 某些扩展名在不同项目中代表不同的语言：.inc 在 pfSense 中是 PHP，在 Delphi 代码树中是 Pascal，在其他项目中可能是 SQL 或汇编；.h 可能是 C 或 C++；.m 可能是 Objective-C 或 MATLAB。graphify 必须选择一个全局默认值，而选错时文件并不会报错：它会按错误的语言解析，只产出少量偶然识别到的节点，导致图谱看似已有内容，实际符号却缺失。请声明这些扩展名在你的仓库中代表什么：

# .graphifyrc
# A language name:
language.inc=php
# Or an extension graphify already knows:
language.tpl=.ts
# Baked into the git hooks (see Team setup):
viz_node_limit=0

这项声明会贯穿文件分类、提取器选择、语法与解析、导入、graphify watch 和 AST 缓存（文件按另一种语言重新解析时，绝不会复用旧缓存条目），而且 extract、update、hook、MCP 服务器和 /graphify 技能都会读取同一份 .graphifyrc。拼写错误会在 stderr 中报告一次，随后扫描继续使用默认值。关于这些声明如何与缓存、增量重建及导入解析交互，请参阅“配置”。

提交或共享图谱，让整个团队基于相同的上下文进行查询，并结合图谱上下文审查拉取请求。请参阅“与团队共享上下文”和“审查拉取请求”。

直接使用图谱

除了通过 AI 助手，你还可以使用 graphify query、graphify path 和 graphify explain，直接在 CLI 中查询 graph.json。如果一个名称匹配到多个节点，工具会拒绝执行并列出候选节点，而不会自行猜测。脚本可以通过退出码读取执行结果：0 表示返回了答案，3 表示名称存在歧义，4 表示没有匹配的节点。参见“提出更好的图谱问题”和查询参考文档。

环境变量

后端、API 密钥、钩子行为和调优参数均通过环境变量控制。完整列表参见“配置”。

代码文件：通过 tree-sitter 在本地处理。任何内容都不会离开你的机器。仅包含代码的语料库不需要 API 密钥：graphify extract 可以完全离线运行。对于包含多种文件类型的仓库，添加 --code-only 即可仅索引代码，跳过原本需要 LLM 处理的文档、PDF 和图片。

视频 / 音频：使用 faster-whisper 在本地转录。任何内容都不会离开你的机器。

文档、PDF、图片：发送给你的 AI 助手进行语义提取（通过 /graphify 技能，使用 IDE 会话当前运行的模型）。以无界面方式运行 graphify extract 时，需要具备以下条件之一：GEMINI_API_KEY / GOOGLE_API_KEY（Gemini）、MOONSHOT_API_KEY（Kimi）、ANTHROPIC_API_KEY（Claude）、OPENAI_API_KEY（OpenAI）、DEEPSEEK_API_KEY（DeepSeek）、正在运行的 Ollama 实例（OLLAMA_BASE_URL）、通过标准凭证提供程序链获取的 AWS 凭证（Bedrock，无需 API 密钥，使用 IAM），或 claude CLI 可执行文件（Claude Code，无需 API 密钥，使用你的 Claude 订阅）。--dedup-llm 标志使用相同的密钥。

数据驻留：graphify extract 会根据已设置的 API 密钥自动检测应使用的提供商（优先级：Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama）。自动检测时，它会打印出决定所用提供商的具体环境变量，确保每次运行所用的提供商都清楚可见。要明确指定提供商，请传入 --backend，或设置 GRAPHIFY_BACKEND=<name>；设置 GRAPHIFY_BACKEND=none 可禁用所有 LLM 后端（包括语义提取和 claude -p 标签生成回退机制），仅保留代码图谱。对于有数据驻留要求的代码，请使用 GRAPHIFY_BACKEND=ollama / --backend ollama（完全在本地运行）。Kimi（MOONSHOT_API_KEY）会将请求发送至 Moonshot AI 位于中国的服务器。

无遥测、无使用情况跟踪、无分析数据收集。

查询日志：每次 graphify query、graphify path、graphify explain 和 MCP query_graph 调用都会以 JSON Lines 格式记录到 ~/.cache/graphify-queries.log 中（包含时间戳、问题、语料库、返回的节点、耗时）。默认不保存完整的子图响应。设置 GRAPHIFY_QUERY_LOG_DISABLE=1 可关闭日志记录，或设置 GRAPHIFY_QUERY_LOG=/dev/null，在保留日志代码路径的同时丢弃日志输出。

常见安装和提取问题及其解决方法：参见“故障排查”。

完整命令参考

所有命令和标志及其示例：参见“CLI 参考”。

docs.graphify.com：完整文档，包含指南、命令参考和集成说明

工作原理：提取流水线、社区检测、置信度评分、基准测试

ARCHITECTURE.md：模块划分、如何添加一种语言

可选集成：Docker MCP Toolkit + SQLite

The Memory Layer：介绍 graphify 背后理念及其端到端架构的书籍

Graphify Cloud 是构建在 graphify 之上的持续运行层。它不再是按需为每个文件夹重新构建图谱，而是在整个软件开发生命周期中维护一张实时图谱：

Token 用量减少 80%：持续可用的记忆让你的智能体无需在每次会话中重新阅读和解释代码库。

Monorepo 与跨仓库支持：用一张互联的图谱覆盖所有服务和仓库，无需为每个文件夹单独建立图谱。

形式化验证：基于实时图谱，检查架构和依赖关系中的不变条件。

纵览整个软件开发生命周期的代码审查：在合并之前，了解一项变更会如何影响整个系统。

SDLC 连接器：接入 Sentry、Jira 等工具，让事件、工单和代码共存于一张图谱中。

持续运行：在后台持续更新代码、文档和会议相关内容。

前往 app.graphify.com，开启 14 天免费试用 →

欢迎贡献。有关开发环境搭建、测试及与 CI 保持一致的命令、git 工作流程，以及什么样的贡献最有价值，请参阅 CONTRIBUTING.md（完整的使用示例和提取错误报告最有帮助）。架构及如何添加一种语言：参见 ARCHITECTURE.md。

刚来这里？欢迎到 Discord 或 GitHub Discussions 打个招呼。

使用 contrib.rocks 制作。

README 提供 32 种语言版本。你可以使用本文件顶部的语言切换器，选择自己的语言阅读，也可以浏览 docs/translations/。如需改进翻译或添加新译文，请针对该目录中的相应文件提交拉取请求。

正在 graphify 生态中构建项目？我们鼓励这样做。如果你的项目名称中使用了“graphify”（例如 graphify-dashboard 或 graphify-action），请在 README 中添加一段简短说明，明确该项目由社区构建，与 Graphify Labs 无关联，也未获得其背书。“graphify”和 graphify 标志属于 Graphify Labs 的标识；请勿以暗示官方身份的方式使用它们。

![The Memory Layer](https://camo.githubusercontent.com/1d139456665889f9