企业官网建设流程全解析

graphify 知识图谱导出与基准测试完整指南：Wiki、Neo4j、FalkorDB、SVG、GraphML 与 MCP 服务

【免费下载链接】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 在把代码、文档、SQL、配置与 PDF 解析为可查询知识图谱后，还提供了一整套"按需导出"能力：生成 Wiki 文档站、向 Neo4j/FalkorDB 推送图谱、输出 SVG/GraphML 可视化文件、以 MCP（Model Context Protocol）服务把图谱实时开放给其他 Agent，并对大语料执行 token 压缩基准测试。本文以 graphify 为 Trae 等 Agent 平台内置的 skill 参考文档（graphify/skills/trae/references/exports.md 及 skillgen 生成物 tools/skillgen/expected/graphify__skills__trae__references__exports.md）为主干，逐一说明每个导出 flag 的触发条件、命令格式、默认参数与底层实现原理，帮助你真正掌握这套多格式导出管线。

适用前提：这些步骤只在显式传入对应 flag 时执行

该参考文档属于 graphify skill 的多步工作流的一部分，其核心约束是：每个步骤只针对自己的 flag 运行，没有传入该 flag 就不执行对应导出。当用户在原始命令中传入了以下任一导出 flag，或语料规模满足 token 缩减基准的触发条件时，Agent 才会加载本参考并依次执行：

--wiki、--neo4j、--neo4j-push、--falkordb、--falkordb-push、--svg、--graphml、--mcp

以 trae 为例，同一份参考以近似形式被同步到 agents/amp/claude/claw/codex/copilot 等多个平台的 skill 目录（如 graphify/skills/agents/references/exports.md）。skillgen 工具（tools/skillgen）会根据 fragments 与 platforms.toml 生成每个平台的实际 skill 文件，本主题对应的期望产物即 tools/skillgen/expected/graphify__skills__trae__references__exports.md。

需要理解两个贯穿全文的前提约定：

• 输出目录：默认输出到graphify-out/（可通过环境变量GRAPHIFY_OUT覆盖，见 graphify/paths.py），graph.json、.graphify_labels.json、.graphify_detect.json、.graphify_python等中间产物都在该目录下；
• 前置条件：所有导出都假定已完成/graphify <path>的建图流程，graph.json存在（CLI 在导出前会做存在性与尺寸上限检查，graphify/cli.py），社区、标签、cohesion 等分析数据来自.graphify_analysis.json与.graphify_labels.json。

Step 6b：Wiki 导出（--wiki）——先于清理步骤的关键时序

只在原始命令中显式给出--wiki时才运行此步。参考文档特别强调一个时序约束：Wiki 导出必须放在Step 9（cleanup 清理）之前，因为导出需要读取当时仍存在的.graphify_labels.json（人工或 LLM 生成的社区命名）。一旦清理步骤将其删除，Wiki 中的社区命名信息就会丢失。

graphify export wiki

命令内部实际执行to_wiki（实现见 graphify/wiki.py），默认把产物写到graphify-out/wiki/，其中wiki/index.md是面向 Agent 的入口页（CLI 会打印该提示，graphify/cli.py）：

• 社区文章：每个社区生成一篇条目，列出成员节点，并统计与其它社区的连接边数与桥接节点；
• God-node 文章：为高连通度的关键节点生成单独条目（数据来自.graphify_analysis.json的gods，缺失时用god_nodes(G)现算）；
• 索引页：汇总社区、god nodes 与全图节点/边规模。

一个值得注意的保护逻辑：若.graphify_analysis.json缺失或为空，CLI 会拒绝导出并提示先运行graphify extract .或graphify cluster-only .重新生成社区数据，以避免导出退化的空 Wiki（graphify/cli.py）。对应的测试可在 tests/test_cli_export.py 中看到（test_export_wiki_creates_articles）。

Step 7：Neo4j 导出（--neo4j / --neo4j-push）

生成 Cypher 文件供手动导入（--neo4j）

仅传--neo4j时，不要求有运行中的 Neo4j 实例，只生成一个可供cypher-shell批量执行的 Cypher 文件：

graphify export neo4j

产物为graphify-out/cypher.txt，文件头标注// Neo4j Cypher import - generated by /graphify。每个节点写成一条MERGE，每条边先MATCH两端节点再MERGE关系，见 graphify/export.py：

• 节点按file_type（首字母大写）打标签，例如Python、Markdown，携带id与label两个属性；
• 边以relation大写形式作为关系类型，并保留confidence属性；
• 字符安全：_cypher_escape对反斜杠、单引号、换行与 C0 控制字符做转义，防止字段内容破坏语句边界；处于标识符位置的标签/关系类型经_cypher_label白名单清洗（仅保留[A-Za-z0-9_]且必须以字母开头），不合法时回退到Entity/RELATES_TO。

导入到 Neo4j：

cypher-shell < graphify-out/cypher.txt

直接推送到运行中的实例（--neo4j-push ）

graphify export neo4j --push bolt://localhost:7687 --user neo4j --password PASSWORD

参数默认值与安全要点：

• 默认 URI 为bolt://localhost:7687，默认用户为neo4j；若凭据未提供，Agent 应主动询问用户；
• 为避免密码出现在 shell 历史与进程列表（ps可见），CLI 还支持用环境变量NEO4J_PASSWORD替代--password，显式 flag 优先于环境变量（graphify/cli.py）；
• 使用 MERGE 语义，可安全重复执行：节点与边均为 upsert，不会产生重复数据。

push 路径需要安装驱动pip install neo4j，其实现push_to_neo4j（graphify/exporters/graphdb.py）通过 Python 驱动逐条执行：

• 每个节点MERGE (n:Label {id: $id}) SET n += $props，props只保留字符串/数值/布尔标量属性并剔除_前缀的内部标记，社区 ID 会作为community属性写入；
• 每条边MATCH (a {id: $src}), (b {id: $tgt}) MERGE (a)-[r:REL]->(b) SET r += $props；
• 关系类型与标签同样经过注入清洗（_safe_rel/_safe_label），完成后返回{"nodes": ..., "edges": ...}计数，CLI 打印Pushed to Neo4j: N nodes, M edges。

Step 7a：FalkorDB 导出（--falkordb / --falkordb-push）

FalkorDB 兼容 OpenCypher，因此导出的语句与 Neo4j 完全相同，但两者存在一个关键差异：FalkorDB 的GRAPH.QUERY一次只能执行一条语句，没有类似 Neo4jcypher-shell的批量脚本导入机制。

因此参考文档的建议是：

• --falkordb只在你需要那个可移植的cypher.txt产物时使用；
• 要真正把图载入数据库，优先使用--falkordb-push。

graphify export falkordb # 生成 OpenCypher 语句的 cypher.txt graphify export falkordb --push falkordb://localhost:6379

参数约定（graphify/cli.py）：

• 默认 URI 为falkordb://localhost:6379，且scheme 仅是提示性的——redis://localhost:6379或裸的host:port都可用（实现会先补上redis://再urlparse，graphify/exporters/graphdb.py）；
• 认证是可选的：FalkorDB 默认无凭据运行，只在实例要求认证时才询问用户；同理可用环境变量FALKORDB_PASSWORD；
• 目标图默认名为graphify（FalkorDB 在同一实例内按名区分图，通过select_graph("graphify")选择）；
• 同样基于MERGE upsert，重复执行安全。

push 实现push_to_falkordb（graphify/exporters/graphdb.py）与 Neo4j 路径的结构差异：用FalkorDB(host, port, username, password)建立连接、用db.select_graph()选图、用graph.query(cypher, params)执行语句、无 session 对象。凭据优先级为「URI 内嵌凭据 > 命令行参数」。集成测试可参考 tests/test_falkordb_integration.py。

Step 7b：SVG 导出（--svg）

graphify export svg

产物为graphify-out/graph.svg。该格式轻量且可直接嵌入 Markdown——Obsidian 笔记、Notion、GitHub README 都能渲染，无需 JavaScript。

实现to_svg（graphify/export.py）基于 matplotlib + spring layout（固定seed=42，保证重复导出布局稳定）：

• 节点大小随度数缩放（300 + 1200 * degree/max_degree），Hub 节点视觉突出；
• 节点颜色与社区对应，色板COMMUNITY_COLORS与 HTML 导出一致；
• 边按置信度区分：EXTRACTED为实线且透明度更高，INFERRED/AMBIGUOUS等为虚线、低透明度；
• 左下角绘制社区图例（含成员数），字体、底色针对深色背景设计；
• 依赖matplotlib，未安装时抛错并提示pip install matplotlib。

Step 7c：GraphML 导出（--graphml）

graphify export graphml

产物为graphify-out/graph.graphml，可直接在Gephi、yEd 或任意 GraphML 兼容工具中打开。实现to_graphml（graphify/export.py）在写入前做了一系列工程化处理：

• 社区信息：把communityID 写为节点属性，Gephi 可直接按社区着色；
• 置信度保留：边上的EXTRACTED/INFERRED/AMBIGUOUS作为边属性保留；
• 剔除内部标记：所有_前缀属性（如 AST 溯源_origin、方向标记_src/_tgt）不泄漏到导出文件；
• 标量净化_graphml_safe：None转空串、非标量（dict/list）序列化为 JSON 字符串、字符串先过_strip_xml_illegal剔除 XML 1.0 无法表示的 C0 控制字符，避免一个异常标签导致整次导出失败；
• 原子写入：先写.tmp再os.replace，防止序列化中途出错留下 0 字节文件被下游误判为成功导出。

Step 7d：MCP server（--mcp）——把图谱开放给其它 Agent

--mcp会启动一个基于stdio的 MCP server，供 Claude Desktop 等任意 MCP 兼容编排器挂载。关键点在于：启动用的解释器必须是从graphify-out/.graphify_python中读取的虚拟环境 Python，而不是系统python3：

$(cat graphify-out/.graphify_python) -m graphify.serve graphify-out/graph.json

该 server 对 Agent 暴露以下工具，支持对已建图进行实时查询：

query_graph、get_node、get_neighbors、get_community、god_nodes、graph_stats、shortest_path

工具层实现在 graphify/serve.py（list_tools与各_tool_*处理器），底层复用同一套基于关键词打分、BFS/DFS 子图抽取、社区过滤与诱导边补全的图谱问答逻辑。

在 Claude Desktop 中注册

参考文档特别提示了两个 Claude Desktop 的限制，并给出了对应配置：

1. Claude Desktop 无法执行$(...)命令替换，所以command必须写成字面量；
2. 在uv tool install安装方式下，系统python3无法 import graphify，所以必须指向 graphify 虚拟环境中的解释器。

因此配置claude_desktop_config.json时，先执行cat graphify-out/.graphify_python拿到绝对解释器路径，再填入：

{ "mcpServers": { "graphify": { "command": "<absolute path from: cat graphify-out/.graphify_python>", "args": ["-m", "graphify.serve", "/absolute/path/to/graphify-out/graph.json"] } } }

其中command必须替换为上一步打印的绝对解释器路径，args中的graph.json同样建议使用绝对路径，避免 MCP 子进程的当前工作目录与预期不一致导致加载失败。挂载完成后，其它 Agent 就能以"工具调用"的方式直接对这张已经过 AST 解析与语义标注的知识图谱发起结构化查询。

Step 8：Token 缩减基准（total_words > 5000 时）

graphify benchmark

触发条件由建图阶段的检测结果决定：读取graphify-out/.graphify_detect.json中的total_words（语料总词数，累计逻辑见 graphify/detect.py，它同时对视频之外的各类文件计数并决定是否需要建图的告警阈值）：

• total_words > 5000：运行graphify benchmark，并把输出直接打印在对话中交给用户查看；
• total_words <= 5000：静默跳过。参考文档给出的理由非常明确——对于小语料，"图的价值在于结构清晰（structural clarity），而不是 token 压缩（token compression）"，没必要为一个本可整段塞进上下文窗口的小项目做基准。

graphify benchmark（实现见 graphify/benchmark.py）衡量的是"用图谱回答问题时节省的上下文量"：

• 按chars/4 = 1 token的通用近似估算 token（_CHARS_PER_TOKEN，见 graphify/benchmark.py）；
• 从问题中提取查询词并对节点打分，选取最佳匹配节点作为种子；
• 以种子为中心做深度受限的 BFS，得到返回的子图并估算其 token 数，与朴素"全语料进上下文"方案对比，量化图谱检索的压缩收益。

结果经print_benchmark以等宽表格输出（并对非 UTF-8 控制台做了字符回退），CLI 会尝试从graphify-out/.graphify_detect.json自动读取total_words作为语料规模参数（graphify/cli.py）。CLI 分发见 graphify/cli.py 的graphify export <format>帮助文本。

导出矩阵速查与使用建议

综合参考文档与源码，将各导出方式的使用要点汇总如下：

实践建议：由于每个导出步骤只针对自己的 flag 运行、且都以graphify-out/下的graph.json为唯一事实来源，你完全可以在一次/graphify命令中组合多个 flag（例如同时要 Wiki、SVG 与 MCP 服务），各步骤互不干扰；只要牢记——Wiki 必须在清理步骤之前导出以保证社区标签可用，FalkorDB 尽量用--push而非文件导入，MCP 场景务必使用.graphify_python提供的虚拟环境解释器。测试覆盖可在 tests/test_cli_export.py（wiki/graphml/neo4j/falkordb 产物）与 tests/test_export_path_length.py（长路径 vault/wiki 导出的健壮性）中继续深入验证。

【免费下载链接】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