企业官网建设流程全解析

Graphify 实战指南：把代码库、文档与 PDF 变成可查询的知识图谱

【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphify

Graphify 是一个 AI 编程助手技能：在 Claude Code、Codex、Cursor、Gemini CLI 等助手中输入/graphify，它会读取你的整个项目（代码、文档、PDF、图片、音视频），用本地 tree-sitter AST 确定性解析代码，构建出一张可查询的知识图谱，让你"查图"替代"翻文件"。本篇基于 Graphify 仓库中的波斯语版 README（README.fa-IR.md）及其英文主文档与源码实现，完整覆盖从安装、技能注册、平台适配、忽略规则、团队工作流、MCP 服务到无头提取（CI）与排障的全部技术细节，并附源码级证据。读完你应能独立完成：安装 CLI、为 20 余个助手平台注册技能、生成并查询graph.json、把图谱以 MCP/HTTP 形式共享给团队，以及在 CI 中运行graphify extract。

一、核心定位：图谱而非向量索引

Graphify 有三个与典型 RAG 方案不同的设计决策（见 README.md）：

• 代码免费本地映射：代码用 tree-sitter AST 解析，确定性、无 LLM、不离开你的机器；只有文档/PDF/图片/视频的语义抽取才调用模型 API；
• 每条边都有解释：每条连接被标记为EXTRACTED（源码中明确存在）或INFERRED（由 graphify 解析推断），你始终知道哪些是直接读到的、哪些是推断的；
• 不是向量索引：没有 embedding、没有向量库，而是一张真正可遍历的图——可以提问、追踪两个概念之间的最短路径、解释单个概念。

波斯语版 README 中引用了 Andrej Karpathy 的/raw文件夹场景（把文章、推文、截图、笔记往里扔），并给出 README 声称的指标：相比直接读原始文件，每次查询少约71.5 倍token，且在会话中保持稳定（这是项目 README 的宣传口径，实际效果因语料而异）。

一次/graphify .执行后你会得到三个文件：

graphify-out/ ├── graph.html 在任意浏览器打开 —— 点击节点、过滤、搜索 ├── GRAPH_REPORT.md 报告要点：核心概念、惊人连接、建议问题 └── graph.json 完整图谱 —— 随时查询，无需重读文件

二、前置条件与安装

2.1 环境要求

各平台快速安装：

# macOS (Homebrew) brew install python@3.12 uv # Windows (PowerShell) winget install astral-sh.uv # Ubuntu/Debian sudo apt install python3.12 python3-pip pipx # 或安装 uv： curl -LsSf https://astral.sh/uv/install.sh | sh

仓库 pyproject.toml 中声明requires-python = ">=3.10"，PyPI 包名为graphifyy（双 y），当前仓库版本为 0.9.52，核心依赖包含networkx、numpy、rapidfuzz和 20 余个tree-sitter-*语法包。

2.2 两步安装

官方包名提示：PyPI 上的包是graphifyy（双 y），其他graphify*包均与本项目无关。CLI 命令仍叫graphify。

第 1 步 —— 安装包：

# 推荐（uv 会自动把 graphify 放进 PATH）： uv tool install graphifyy # 替代方案： pipx install graphifyy pip install graphifyy # 可能需要手动配置 PATH，见下文排障

第 2 步 —— 在 AI 助手中注册技能：

graphify install

然后打开你的 AI 助手，输入/graphify .。若希望技能安装到当前仓库（项目级）而非用户主目录，加--project：

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

两个注意事项（来自文档与主 README）：

• PowerShell：使用graphify .而不是/graphify .——PowerShell 里开头的斜杠是路径分隔符；
• graphify: command not found：优先用uv tool install或pipx install，二者都会自动把 CLI 放进工具 bin 目录（~/.local/bin）；若 shell 找不到，运行uv tool update-shell或pipx ensurepath后重开终端。

2.3 平台选择表

graphify install按平台写入不同的技能文件与钩子。完整平台命令（继承自原文档）：

从源码结构看，各平台的差异集中在 graphify/install.py：claude_install写CLAUDE.md段落并注册PreToolUse钩子，gemini_install写GEMINI.md+BeforeTool钩子，vscode_install/_cursor_install写.cursor/rules/graphify.mdc，Kiro 写.kiro/skills/+.kiro/steering/，Antigravity 写.agents/rules+.agents/workflows——与文档中"每平台安装命令"注释一一对应。

2.4 可选扩展（只装需要的）

这些 extras 与 pyproject.toml 中的[project.optional-dependencies]一一对应：例如mcp = ["mcp>=1,<3", "starlette>=1.3.1,<2"]、video需要faster-whisper（Python ≥3.11）+yt-dlp、bedrock = ["boto3"]。

三、让助手始终优先查图

构建图谱后，在项目里运行一次对应平台的"常驻"安装命令（原文档全表）：

它会写入一个小配置文件，告诉助手：遇到代码库问题时先查知识图谱（优先graphify query "<问题>"这样的范围化查询），而不是直接 grep 原始文件。主 README 补充了实现机制的两类：

• 钩子平台（Claude Code、Gemini CLI）：钩子在搜索型工具调用（以及 Claude Code 中逐个 Read/Glob 源文件）之前自动触发，把助手引向查图路径；
• 指令文件平台（Codex、OpenCode、Cursor 等）：通过持久指令文件（AGENTS.md、.cursor/rules/等）提供同样的"先查图"引导。

要一次从所有平台移除：graphify uninstall（加--purge连graphify-out/一起删除）。

四、报告里有什么

GRAPH_REPORT.md的五类内容（原文档逐条继承）：

• 核心节点（God nodes）——项目中连接度最高的概念，一切都从它们经过；
• 惊人连接——位于不同文件/模块的实体之间的链接，按"意外程度"排序；
• "为什么"——行内注释（# NOTE:、# WHY:、# HACK:）、docstring 以及文档中的设计动机，作为独立节点被抽取出来，并链接到它们解释的代码；
• 建议问题——图谱独一无二能回答的 4~5 个问题；
• 置信度标签——每条推断关系都标记为EXTRACTED、INFERRED或AMBIGUOUS，随时知道哪些是找到的、哪些是猜的。

报告由 graphify/report.py 的generate()生成，God nodes / 惊人连接 / 建议问题分别来自 graphify/analyze.py 的god_nodes()、surprising_connections()、suggest_questions()；"为什么"节点在抽取阶段由 graphify/extract.py 的_extract_python_rationale()等函数从注释与 docstring 中提取。

五、支持的文件类型

波斯语文档称"36 种语言经 tree-sitter AST 支持"，主 README 更新为 37 个 tree-sitter 语法（另有 Terraform/HCL、OCaml、Common Lisp、Salesforce Apex 等可选或正则实现的扩展）。代码在本地用 tree-sitter 提取，零 API 调用；其余文件走你的 AI 助手模型 API。从 graphify/extractors/ 目录可以看到每种语言一个抽取器文件（rust.py、go.py、swift.py、sql.py、terraform.py等），engine.py提供通用 tree-sitter 遍历引擎，resolution.py负责跨文件 import 解析。

六、常用命令

/graphify . # 为当前目录构建图谱 /graphify ./docs --update # 只重新提取变更文件 /graphify . --cluster-only # 不重新提取，只重跑社区检测 /graphify . --no-viz # 只要报告 + JSON，不出 HTML /graphify . --wiki # 从图谱构建 Markdown 维基 graphify export callflow-html # 生成 Mermaid 架构/调用流 HTML /graphify query "什么把 auth 连到数据库？" /graphify path "UserService" "DatabasePool" /graphify explain "RateLimiter" /graphify add https://arxiv.org/abs/1706.03762 # 抓取一篇论文加入图谱 /graphify add <youtube-url> # 转录并加入视频 graphify hook install # 每次 commit 后自动重建 graphify merge-graphs a.json b.json # 合并两张图 graphify prs # PR 看板：CI 状态、评审状态、图谱影响面 graphify prs 42 # 深挖 PR #42 graphify prs --triage # AI 给评审队列排序

七、文件忽略规则

在项目根目录创建.graphifyignore——语法与.gitignore完全一致，包括!取反。.gitignore会被自动遵守：graphify 会读取各目录下的.gitignore，若同目录还有.graphifyignore，两者合并、后者优先。

# .graphifyignore node_modules/ dist/ *.generated.py # 只索引 src/，忽略其他一切 * !src/ !src/**

从源码看，忽略逻辑实现在 graphify/detect.py：_load_graphifyignore()加载两套规则，ignored_predicate()生成扫描用的谓词函数，子目录作用域规则与 git 相同（一个忽略文件只影响自己的子树）。

八、团队协作工作流

graphify-out/被设计为可以 commit 进 git，让团队所有人从同一张地图开始。

建议加入.gitignore：

graphify-out/cost.json # 仅本地 # graphify-out/cache/ # 可选：commit 它提速，或删除它保持仓库小巧

工作流（原文档四步）：

1. 一个人跑/graphify .并 commitgraphify-out/；
2. 所有人 pull——助手指针会立刻读到图谱；
3. 运行graphify hook install，让每次 commit 后自动重建；
4. 当文档或论文变化时，跑/graphify --update。

补充：主 README 指出manifest.json现已可移植（键以相对路径存储、加载时重新锚定），commit 它是安全的。主 README 的增强版工作流还给出一个 git alias 让 pull 自动同步图谱：

git config --global alias.gpull '!git pull && graphify update .'

钩子机制在 graphify/hooks.py：install()写入 post-commit 与 post-checkout 钩子脚本，并把当前解释器路径直接嵌入脚本（所以在 GUI git 客户端和 CI runner 中~/.local/bin不在 PATH 时钩子也能触发）；_register_merge_driver()注册自定义 merge driver，让graph.json在两人同时提交时自动 union 合并、不会出现冲突标记。graphify hook status可确认钩子是否生效。

九、直接查询图谱与 MCP 服务

9.1 终端查询

# 在终端查询图谱 graphify query "展示认证流程" graphify query "什么把 DigestAuth 连到 Response？" --graph graphify-out/graph.json

9.2 作为 MCP 服务器

# 把图谱暴露为 MCP 服务器（stdio） python -m graphify.serve graphify-out/graph.json # 或以 HTTP 服务供整个团队访问 python -m graphify.serve graphify-out/graph.json --transport http --port 8080 python -m graphify.serve graphify-out/graph.json --transport http --host 0.0.0.0 --api-key "$SECRET"

MCP 服务器提供结构化访问，七个工具为：query_graph、get_node、get_neighbors、shortest_path、list_prs、get_pr_impact、triage_prs。这可以在 graphify/serve.py 的list_tools()中逐一确认（query_graph等工具定义位于该文件 L1617 起）。

HTTP 模式的关键参数（默认值来自 serve.py 的serve_http()签名与文档）：

默认绑定127.0.0.1仅回环可用；在共享主机上暴露时必须同时设置--host 0.0.0.0和--api-key。HTTP 服务行为有测试覆盖，见 tests/test_serve_http.py。

十、环境变量（无头提取 / CI 专用）

这些变量只在无头/CI 提取（graphify extract）时需要；通过 IDE 内/graphify技能运行时，模型 API 由你的 IDE 会话提供，无需额外 key。

主 README 还列出一批补充变量，按需取用：OPENAI_BASE_URL/OPENAI_MODEL（任意 OpenAI 兼容服务器，如 llama.cpp、vLLM）、OLLAMA_MODEL、GRAPHIFY_OLLAMA_NUM_CTX/GRAPHIFY_OLLAMA_KEEP_ALIVE（控制本地推理显存）、GRAPHIFY_MAX_OUTPUT_TOKENS（稠密语料提高输出上限）、GRAPHIFY_MAX_RETRIES（429 重试次数，默认 6）、GRAPHIFY_MAX_RETRY_DEPTH（截断 chunk 的二分重提取深度，默认 3）、GRAPHIFY_MAX_GRAPH_BYTES（覆盖 512 MiB 的 graph.json 上限）等。

后端自动检测顺序：不显式传--backend时，graphify extract按设置好的 key 自动选后端。从 graphify/llm.py 的detect_backend()（L3106 起）docstring 与实现看，优先级为gemini → kimi → claude → openai → deepseek → azure → bedrock → ollama，且 Ollama 故意排在最后，避免环境里顺手设的OLLAMA_BASE_URL悄悄遮蔽已付费的后端。

十一、隐私边界

• 代码文件——本地 tree-sitter 处理，什么都不离开你的机器。纯代码语料不需要任何 API key，graphify extract可以完全离线跑；混合仓库可用--code-only只索引代码、跳过需要 LLM 的文档/PDF/图片；
• 视频/音频——本地用 faster-whisper 转录，什么都不离开机器（转录实现在 graphify/transcribe.py）；
• 文档、PDF、图片——发往你的 AI 助手模型做语义提取；
• 无遥测、无使用追踪、无分析统计；
• 查询日志：每次query/path/explain与 MCPquery_graph会写入~/.cache/graphify-queries.log（JSON Lines：时间戳、问题、语料、返回节点数、耗时），默认不保存完整子图响应；GRAPHIFY_QUERY_LOG_DISABLE=1可彻底关闭。日志逻辑见 graphify/querylog.py。

十二、完整命令参考

/graphify # 对当前目录运行 /graphify ./raw # 对指定目录运行 /graphify ./raw --mode deep # 更激进的关系提取 /graphify ./raw --update # 只重新提取变更文件 /graphify ./raw --directed # 保留边方向 /graphify ./raw --cluster-only # 在现有图上重跑社区检测 /graphify ./raw --no-viz # 不出 HTML /graphify ./raw --obsidian # 生成 Obsidian vault /graphify ./raw --wiki # 构建 agent 可爬的 Markdown 维基 /graphify ./raw --svg # 导出 graph.svg /graphify ./raw --graphml # 导出给 Gephi / yEd /graphify ./raw --neo4j # 生成给 Neo4j 的 cypher.txt /graphify ./raw --watch # 文件变化自动同步 /graphify ./raw --mcp # 启动 MCP stdio 服务器 /graphify add https://arxiv.org/abs/1706.03762 /graphify add <video-url> /graphify query "什么把 attention 连到 optimizer？" /graphify path "DigestAuth" "Response" /graphify explain "SwinTransformer" graphify uninstall # 一次从所有平台移除 graphify uninstall --purge # 连同 graphify-out/ 一起删除 graphify hook install # post-commit + post-checkout 钩子 graphify hook uninstall graphify hook status graphify claude install # CLAUDE.md + PreToolUse 钩子（Claude Code） graphify codex install # AGENTS.md + PreToolUse 钩子（Codex） graphify cursor install # .cursor/rules/graphify.mdc（Cursor） graphify gemini install # GEMINI.md + BeforeTool 钩子（Gemini CLI） graphify amp install # 技能文件（Amp） graphify kiro install # .kiro/skills/ + .kiro/steering/（Kiro） graphify devin install # 技能文件 + .windsurf/rules/（Devin CLI） graphify antigravity install # .agents/rules + .agents/workflows（Google Antigravity） graphify extract ./docs # CI 无头 LLM 提取（无需 IDE） graphify extract ./docs --backend gemini # 显式后端 graphify extract ./docs --backend ollama # 本地 Ollama，无需 API key graphify extract ./docs --backend bedrock # AWS Bedrock，走 IAM graphify extract --postgres "postgresql://user:pass@host/db" # 直接内省活 PostgreSQL schema graphify prs # PR 看板 graphify prs 42 # 深挖 PR #42 graphify prs --triage # AI 排序（按已配置后端） graphify prs --conflicts # 共享图谱社区的 PR（合并顺序风险） graphify export callflow-html # 架构/调用流 HTML graphify merge-graphs a.json b.json --out merged.json graphify --version

主 README 的参考还包括：graphify extract ./raw --code-only（纯本地 AST，无 API key）、--token-budget（本地小模型用更小的语义 chunk）、--max-concurrency（本地推理时减少并行 LLM 调用）、cluster-only --resolution 1.5（更多更小的社区）、global add/remove/list（跨项目全局图）、watch/update/check-update、label（用已配置后端重命名社区）等。

十三、排障手册

pip install graphifyy后graphify: command not foundpip 把脚本装进用户 bin 目录，它可能不在 PATH 里：

• macOS：把~/Library/Python/3.x/bin加入~/.zshrc的 PATH；
• Linux：把~/.local/bin加入~/.bashrc的 PATH；
• 或者直接用uv tool install graphifyy/pipx install graphifyy。

PowerShell 中/graphify .报 "path not recognized"PowerShell 把开头的/当路径分隔符。Windows 上用graphify .（不带斜杠）。

--update或重建后图谱节点变少若重构删除了文件，旧节点会残留。传--force（或GRAPHIFY_FORCE=1）强制覆盖：

graphify extract . --force

文档/PDF 提取返回空节点/边文档、PDF、图片需要 LLM 调用。确认 API key 已设置且后端正确：

ANTHROPIC_API_KEY=sk-... graphify extract ./docs --backend claude

补充两条主 README 的高频问题：

• uvx graphify …报找不到包：PyPI 包名是graphifyy，graphify只是它提供的命令。uv tool run把第一个词当包名，所以要写uvx --from graphifyy graphify install；
• Claude Code 提示缓存每次提取后失效：把graph.json和graphify-out/加进.claudeignore。

十四、开发环境搭建（贡献者向）

项目使用 uv 作为开发工作流，一次性安装后：

git clone https://gitcode.com/GitHub_Trending/graph/graphify.git cd graphify git checkout v8 # 活跃开发分支 uv sync --all-extras

运行测试：

uv run pytest tests/ -q # 全量 uv run pytest tests/test_extract.py -q # 单个模块

Git 工作流：活跃开发在v8分支；commit 风格为fix: <描述>/feat: <描述>/docs: <描述>；开 PR 前先跑uv run pytest tests/ -q并确认通过。

最有价值的贡献类型是真实语料样本（worked examples）：在一个真实 corpus 上跑/graphify，把输出存到worked/{slug}/，写一份诚实的review.md说明图谱哪里对了哪里错了，再开 PR。仓库里现成的示例可参考 worked/httpx/、worked/mixed-corpus/。提取类 bug 请附输入文件、缓存条目（graphify-out/cache/）以及具体错漏。

十五、延伸阅读

• docs/how-it-works.md —— 提取管线、社区检测、置信度评分、基准测试；
• ARCHITECTURE.md —— 模块划分、如何添加新语言；
• docs/docker-mcp-sqlite.md —— Docker MCP Toolkit + SQLite 可选集成；
• 波斯语版原文见 docs/translations/README.fa-IR.md，全部 30+ 种语言的 README 翻译在 docs/translations/ 目录下。

【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphify