README.cs CZ

将智能体的 Token 消耗降低 80%。 Graphify Cloud 是一款始终开启的 Memory，它驱动你的智能体、保持代码高质量，并通过形式化验证证明正确性。 启动免费 14 天试用 →

在你的 AI 编程助手中输入 /graphify，它会把你的整个项目（代码、文档、PDF、图片、视频）映射为知识图谱，你可以查询它，而不是在文件里 grep。

• 免费、完全本地的代码映射。 代码通过 tree-sitter AST 进行解析：确定性，无需 LLM，任何数据都不会离开你的电脑。（文档、PDF、图片和视频会使用你助手的模型或已配置的 API 密钥进行语义遍历。）
• 每条边都有解释。 每个连接都会被标记为 EXTRACTED（源码中显式存在）或 INFERRED（由 graphify 工具推导得到），因此你能区分哪些是直接读取的，哪些是推断出来的。
• 不是向量索引。 没有 embedding，没有向量存储：这是一个真实可遍历的图。你可以提出问题、追踪两条内容之间的路径，或解释单个概念。

[!NOTE] 想让它一直开着吗？ Graphify Cloud 会在你的整个 SDLC 中保持图谱实时更新：支持 monorepo 及跨仓库，提供形式化验证和对 SDLC 的全景式代码审查，还有 Sentry、Jira 等连接器，让事件和工单与你的代码处于同一张图谱中。在 app.graphify.com 启动免费 14 天试用。

FastAPI 代码库由 graphify 工具映射。每个节点都是一个概念，颜色是检测到的社区，整体可在 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 可以持续为你处理，并将 agent 的 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/ sidecar），并输出可提交文件的 git add 提示。支持项目级安装的各个平台命令都接受相同的开关，例如 graphify claude install --project 或 graphify codex install --project。

[!TIP] 遇到 command not found、Mac/Windows 上的 pip 问题、PowerShell 中的引号转义、uvx 的使用、git hooks 中的 PATH 怪癖或 strict mode？请参阅 安装 和 故障排除。

| office | .docx 和 .xlsx 支持 | uv tool install "graphifyy[office]" | | google | Google Sheets 渲染 | uv tool install "graphifyy[google]" | | video | 视频/音频转录（faster-whisper + yt-dlp） | uv tool install "graphifyy[video]" | | mcp | MCP stdio 服务器 | uv tool install "graphifyy[mcp]" | | neo4j | Neo4j 推送支持 | uv tool install "graphifyy[neo4j]" | | falkordb | FalkorDB 推送支持 | uv tool install "graphifyy[falkordb]" | | svg | 将图谱导出为 SVG | uv tool install "graphifyy[svg]" | | leiden | Leiden 社区检测（Python < 3.13 使用 graspologic；3.13+ 使用原生后端） | uv tool install "graphifyy[leiden]" | | ollama | Ollama 本地推理 | uv tool install "graphifyy[ollama]" | | openai | OpenAI / 兼容 OpenAI 的 API | uv tool install "graphifyy[openai]" | | gemini | Google Gemini API | uv tool install "graphifyy[gemini]" | | anthropic | Anthropic Claude API（--backend claude，使用 ANTHROPIC_API_KEY） | uv tool install "graphifyy[anthropic]" | | bedrock | AWS Bedrock（使用 IAM，无需 API 密钥） | uv tool install "graphifyy[bedrock]" | | azure | Azure OpenAI Service（--backend azure，使用 AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT） | uv tool install "graphifyy[openai]" | | sql | SQL 模式提取 | uv tool install "graphifyy[sql]" | | postgres | PostgreSQL 实时内省（--postgres DSN） | uv tool install "graphifyy[postgres]" | | dm | BYOND DreamMaker .dm/.dme 的 AST 提取（如果没有与您的平台匹配的 wheel，可能需要 C 编译器 + python3-dev） | uv tool install "graphifyy[dm]" | | terraform | Terraform / HCL .tf/.tfvars/.hcl 的 AST 提取 | uv tool install "graphifyy[terraform]" | | pascal | Pascal / Delphi .pas/.dpr/.dpk/.inc 的 AST 提取（提供更精确的 calls/inherits 边；缺失时回退到正则表达式提取器） | uv tool install "graphifyy[pascal]" | | ocaml | OCaml .ml/.mli 的 AST 提取 | uv tool install "graphifyy[ocaml]" | | commonlisp | Common Lisp .lisp/.cl/.lsp/.asd 的 AST 提取 | uv tool install "graphifyy[commonlisp]" | | robot | Robot Framework .robot/.resource 提取（套件、测试用例、关键字、关键字调用边以及 resource/library 导入边） | uv tool install "graphifyy[robot]" | | chinese | 中文查询分词（jieba） | uv tool install "graphifyy[chinese]" | | all | 上述全部功能 | uv tool install "graphifyy[all]" |

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

在图谱构建完成后，在您的项目中运行一次以下命令：

在您的项目中运行一次 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（如需同时删除 graphify-out/，可添加 --purge）。或者使用单平台命令（例如 graphify claude uninstall）。

CLI skills 还是 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、Git hooks、MCP 服务器和 /graphify skill 都会读取同一个 .graphifyrc。拼写错误会在 stderr 上报告一次，然后扫描继续使用默认值。关于声明如何与缓存、增量重建和导入解析交互：配置。

团队设置¶

提交或共享图谱，让整个团队查询相同的上下文，并在图谱上下文中审阅 Pull Request。参见 与团队共享上下文 和 审阅 Pull Request。

直接使用图谱¶

除了 AI 助手之外，还可以通过 graphify query、graphify path 和 graphify explain 直接从 CLI 查询 graph.json。如果名称匹配多个节点，则会被拒绝并列出候选，而不是猜测。脚本可以通过返回码读取结果：0 表示有答案，3 表示名称有歧义，4 表示没有匹配的节点。参见 提出更好的图谱问题 和 查询参考。

环境变量¶

后端、API 密钥、hooks 行为和调试均由环境变量控制。完整表格：配置。

隐私¶

• 代码文件：通过 tree-sitter 在本地处理。没有任何内容离开你的计算机。仅包含代码的语料库不需要任何 API 密钥：graphify extract 可完全离线运行。对于混合仓库，如果你只想索引代码而跳过本来需要 LLM 的文档/PDF/图片，请添加 --code-only。
• 视频 / 音频：使用 faster-whisper 在本地转写。没有任何内容离开你的计算机。
• 文档、PDF、图片：会发送给你的 AI 助手进行语义提取（通过 /graphify skill，使用你 IDE 会话中运行的任何模型）。无头（headless）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 ollama（完全本地）或传入显式的 --backend 开关。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%：常驻记忆意味着你的智能体不再需要在每个会话中重新阅读和重新解释代码库。
• Monorepo 与跨仓库：跨每个服务和仓库的单一互联图，而不是每个文件夹一个图。
• 形式化验证：对照实时图检查架构和依赖不变量。
• 以 SDLC 的鸟瞰视角进行代码审查：在合并之前就能看到变更如何在整个系统中传播。
• 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"（例如 graphify-dashboard 或 graphify-action），请在 README 中添加一条简短说明，明确该项目为社区创建，与 Graphify Labs 无关且未获其认可。"graphify" 和 graphify 徽标是 Graphify Labs 的商标；请不要以暗示官方身份的方式使用它们。

社区与链接¶