概述

将智能体的 Token 开销削减 80%。 Graphify Cloud 是一种始终在线的 Memory，可管理你的智能体、保持代码质量，并通过形式化验证证明正确性。 开始 14 天免费试用 →

在 AI 编程助手中输入 /graphify，它会将你的整个项目（代码、文档、PDF、图片、视频）映射为一张知识图谱，让你可以直接查询，而无需在文件中 grep。

• 代码映射免费且完全本地运行。 代码使用 tree-sitter AST 解析：确定性、无 LLM 参与，任何内容都不会离开你的机器。（文档、PDF、图片和视频会使用你助手的模型或已配置的 API key 进行语义处理。）
• 每条边都有解释。 每个连接都会被标记为 EXTRACTED（源代码中明确存在）或 INFERRED（由 graphify 推断得出），因此你能分辨出哪些是直接读取的、哪些是推断出来的。
• 不是向量索引。 没有嵌入向量，也没有向量存储：而是一张可遍历的真实图。你可以提问，追踪两个事物之间的路径，或解释某个概念。

[!NOTE] 希望它始终可用？ 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 版本。

一次安装，任何助手，任何操作系统。 Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot，以及 20 多种其他助手，支持 macOS、Linux 和 Windows：选择你的平台。

一睹为快¶

图谱构建完成后，你可以直接查询它，而无需阅读文件。以下是在上方 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 则追踪任意两个事物之间的连接路径。

它能做什么¶

开箱即用，你将获得：

[!TIP] 想在多个仓库或 monorepo 中运行？Graphify Cloud 可持续地执行此操作，并将智能体的 token 开销降低 80%，提供跨仓库链接、覆盖整个 SDLC 的代码审查、形式化验证，以及 Sentry/Jira 连接器。开始 14 天免费试用 →

基准测试：0.497 recall@10，0 LLM 额度¶

所有系统都在相同的测试框架上运行，使用相同的模型和预算，并由一名评审员评分，同时由第二名评审员进行盲审验证（一致率 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

Ubuntu/Debian：

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

安装¶

[!IMPORTANT] 官方软件包： 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。

[!TIP] 是否遇到了 command not found、Mac/Windows 上的 pip 问题、PowerShell 引号、uvx 用法、git-hook PATH 怪癖或严格模式？请参阅 安装 和 故障排查。

让你的助手始终使用图谱¶

在项目中构建图谱后，请运行一次以下命令：

在项目中运行 graphify <platform> install，例如 graphify claude install 或 graphify codex install（或 graphify install --platform <name>）。

这会写入一个小的配置文件，告诉你的助手在回答代码库问题时查阅知识图谱，优先使用类似 graphify query "<question>" 的限定范围查询，而不是通读完整报告或直接 grep 原始文件。

• 钩子平台（Claude Code、Gemini CLI）：钩子会在搜索类工具调用之前自动触发（对于 Claude Code，还会在通过 Read/Glob 工具逐个读取源文件之前触发），并引导你的助手优先使用图谱路径。
• 指令文件平台（Codex、OpenCode、Cursor 等）：持久化的指令文件（AGENTS.md、.cursor/rules/ 等）提供同样的“查询优先”引导。

GRAPH_REPORT.md 仍可用于广泛的架构审查。

每个平台具体写入哪些文件（CodeBuddy 的 CODEBUDDY.md + PreToolUse 钩子、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 汇总了 god nodes、社区和关键路径，用于广泛的架构审查。图谱的构建方式及其包含内容：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 缓存（以不同语言重新解析的文件绝不会复用旧条目），同一个 .graphifyrc 也会被 extract、update、钩子、MCP 服务器和 /graphify 技能读取。拼写错误会在 stderr 上报一次，然后扫描继续使用默认值。声明如何与缓存、增量重建和导入解析交互：配置。

团队设置¶

提交或共享图，以便整个团队查询相同的上下文，并在图上下文中审阅拉取请求。参见与团队共享上下文和审阅拉取请求。

直接使用图¶

除了你的 AI 助手之外，还可以通过 CLI 直接使用 graphify query、graphify path 和 graphify explain 查询 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 Cloud 是构建在 graphify 之上的常驻层。它不是为每个文件夹按需重建图，而是在你的整个软件开发生命周期中保持一个实时图：

• Token 减少 80%：常驻 Memory 意味着你的智能体无需在每次会话中重新阅读并反复解释代码库。
• Monorepo 与跨仓库：在所有服务和仓库之上构建一个互联的图，而非每个文件夹一张图。
• 形式化验证：对照实时图检查架构与依赖不变量。
• 从 SDLC 全局视角进行代码审查：在合并之前，看清一项变更如何波及整个系统。
• SDLC 连接器：接入 Sentry、Jira 等工具，让事故、工单和代码共存于同一个图。
• 始终在线：在后台持续更新，覆盖代码、文档和会议。

在 app.graphify.com 开启 14 天免费试用 →

贡献¶

欢迎贡献。请参阅 CONTRIBUTING.md 了解开发环境搭建、测试及 CI 一致性命令、Git 工作流，以及什么样的贡献更有价值（实际示例和提取 bug 报告最为有用）。架构说明及如何添加新语言支持：ARCHITECTURE.md。

新来的？到 Discord 或 GitHub Discussions 打个招呼吧。

贡献者¶

由 contrib.rocks 制作。

翻译¶

README 提供 32 种语言版本。使用本文件顶部的语言切换器切换到你需要的语言，或浏览 docs/translations/。要改进现有翻译或新增翻译，请针对相应文件发起 pull request。

基于 graphify 构建¶

想在 graphify 生态中构建点什么？非常欢迎。如果你的项目名称中使用了“graphify”（例如 graphify-dashboard 或 graphify-action），请在 README 中加一句简短说明，表明该项目由社区构建，与 Graphify Labs 无关联，也未获得其认可。“graphify”和 graphify 徽标是 Graphify Labs 的商标；请勿以暗示官方身份的方式使用它们。

社区与链接¶