graphify 导出链路实战：Wiki、Neo4j/FalkorDB、SVG/GraphML 与 MCP 服务及 Token 缩减基准

graphify 导出链路实战：Wiki、Neo4j/FalkorDB、SVG/GraphML 与 MCP 服务及 Token 缩减基准

【免费下载链接】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 在完成 AST 抽取、社区聚类和标注之后，真正让知识图谱"走出去"的环节是导出（export）体系。本文以 graphify 的技能参考文档 exports.md 为主线，逐条拆解其中的 7 个导出分支（--wiki、--neo4j、--neo4j-push、--falkordb、--falkordb-push、--svg、--graphml、--mcp）和 Token 缩减基准测试，并结合 graphify/export.py、graphify/exporters/graphdb.py、graphify/cli.py 等源码，说明每个命令的实际行为、默认值与工程细节（如幂等 MERGE、密码环境变量、Cypher 注入防护），帮助你在 Agent 工作流中正确配置和运行这些导出步骤。

一、导出步骤的触发模型：每个步骤只响应自己的 Flag

参考文档开头明确了加载时机：当用户命令中携带任一导出 Flag（--wiki、--neo4j、--neo4j-push、--falkordb、--falkordb-push、--svg、--graphml、--mcp）时加载该参考，或者当语料规模大到值得跑 Token 缩减基准时加载。每个导出步骤只为自己的 Flag 执行，未传 Flag 的步骤一律跳过。

对应到 CLI 实现，graphify/cli.py 中cmd == "export"分支（约 L2624）校验子命令白名单：

Usage: graphify export <format> html [--graph PATH] [--labels PATH] [--node-limit N] [--no-viz] obsidian [--graph PATH] [--labels PATH] [--dir PATH] wiki [--graph PATH] [--labels PATH] svg [--graph PATH] [--labels PATH] graphml [--graph PATH] neo4j [--graph PATH] [--push URI] [--user U] [--password P] (or set NEO4J_PASSWORD instead of --password to keep it off argv) falkordb [--graph PATH] [--push URI] [--user U] [--password P] (or set FALKORDB_PASSWORD instead of --password to keep it off argv)

几个值得注意的实现细节：

• 默认路径：--graph默认读graphify-out/graph.json，--labels默认读graphify-out/.graphify_labels.json（社区标签）。
• 密码不落 argv：源码注释标注了 F-031 设计——优先读取环境变量NEO4J_PASSWORD/FALKORDB_PASSWORD，避免密码出现在ps输出和 shell 历史里；显式--password仍然优先覆盖环境变量。
• --push要求密码：neo4j --push时若密码未提供会直接报错退出（graphify/cli.py L2904-L2908）；FalkorDB 的 push 则允许无凭据连接。

下文按参考文档的步骤编号（Step 6b / 7 / 7a / 7b / 7c / 7d / 8）逐一展开。

二、Step 6b：Wiki 导出（仅当传入 --wiki）

参考文档要求：只在原始命令显式带了--wiki时执行，并且要在 Step 9（清理）之前运行，因为清理会删掉.graphify_labels.json，而 Wiki 导出依赖社区标签文件：

graphify export wiki

从源码看，graphify/cli.py 的subcmd == "wiki"分支（约 L2874）有两个前置校验：

1. 社区数据缺失即拒绝：.graphify_analysis.json缺失或为空时直接报错退出，提示先运行graphify extract .重建社区数据，防止导出"空 Wiki"造成数据损失假象；
2. God Nodes 兜底：分析文件中没有 god node 数据时，调用 graphify/analyze.py 的god_nodes(G)现场计算。

最终调用 graphify/wiki.py 的to_wiki()，产出结构为：每个社区一篇_COMMUNITY_*.md概览文章、每个 god node 一篇文章，外加wiki/index.md作为 Agent 的入口页。运行成功时输出形如：

Wiki: N articles written to graphify-out/wiki/ graphify-out/wiki/index.md -> agent entry point

Wiki 中的社区标签是 LLM 生成（非确定性）的，因此--labels显式指定标签文件是保证输出稳定的关键。

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

3.1 生成 Cypher 文件：--neo4j

graphify export neo4j

产出graphify-out/cypher.txt，用于手动批量导入。CLI 输出的提示即导入方式：

cypher.txt written - import with: cypher-shell < graphify-out/cypher.txt

生成逻辑在 graphify/export.py 的to_cypher()（L474-L498）：

• 每个节点输出一行MERGE (n:<FileType> {id: ..., label: ...});，节点 Label 取自节点的file_type（首字母大写）；
• 每条边输出一行MATCH ... MERGE (a)-[:<RELATION> {confidence: ...}]->(b);，关系类型取边的relation大写形式，并保留confidence属性（EXTRACTED / INFERRED / AMBIGUOUS）。

安全性上，_cypher_escape()与_cypher_label()（graphify/export.py L429-L471）做了双层防护：字符串值转义反斜杠、单引号和换行（防止突破cypher-shell的按行分句边界，对应 F-008）；标识符位置（Label、关系类型）无法转义，只能白名单化——剔除非[A-Za-z0-9_]字符，不合法时回退到Entity/RELATES_TO。

3.2 直推运行中的实例：--neo4j-push <uri>

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

• 默认 URI 为bolt://localhost:7687，默认用户neo4j；
• 凭据未提供时应向用户询问；推荐用NEO4J_PASSWORD环境变量代替--password。

推送实现在 graphify/exporters/graphdb.py 的push_to_neo4j()（L9-L78）：通过官方 Python 驱动（pip install neo4j）逐节点、逐边执行参数化Cypher：

MERGE (n:{FileType} {id: $id}) SET n += $props MATCH (a {id: $src}), (b {id: $tgt}) MERGE (a)-[r:{REL}]->(b) SET r += $props

这里正是参考文档所说"Uses MERGE - safe to re-run without creating duplicates"的落地：节点和边都是 upsert 语义，重复推送不会产生重复数据。属性只保留str/int/float/bool标量且排除下划线前缀的内部键，节点还会带上所属community编号。完成后打印Pushed to Neo4j: N nodes, M edges。

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

4.1 生成 Cypher 文件：--falkordb

graphify export falkordb

语句同样是 OpenCypher，但 CLI 明确给出取舍建议：FalkorDB 的GRAPH.QUERY逐条执行语句，没有 Neo4jcypher-shell那样的批量脚本导入通道，因此装图优先用--falkordb-push，只在需要可移植的cypher.txt产物时才用文件形式：

cypher.txt written (graphify-out/cypher.txt) - statements are OpenCypher. FalkorDB's GRAPH.QUERY runs one statement at a time (no bulk script import), so load a graph with: graphify export falkordb --push falkordb://localhost:6379

4.2 直推实例：--falkordb-push <uri>

graphify export falkordb --push falkordb://localhost:6379

• 默认 URIfalkordb://localhost:6379；scheme 仅是信息性的——redis://或裸host:port都可以，源码 graphify/exporters/graphdb.py 的push_to_falkordb()（L80-L173）里urlparse只取 host/port，缺省端口 6379；
• 认证可选：FalkorDB 默认无凭据运行，凭据只在实例要求认证时才需要；
• 目标图名默认为graphify，通过db.select_graph("graphify")选中；
• 同样使用 MERGE，可重复执行不产生重复。

从源码还可以确认一个细节：URI 中内嵌的凭据优先于--user/--password参数；无密码时不发送用户名，避免 FalkorDB 把 Neo4j 风格的默认用户名当作未知 ACL 用户拒绝。

五、Step 7b / 7c：SVG 与 GraphML 导出

graphify export svg

graphify export graphml

SVG（graphify/export.pyto_svg()，L1282 起）：基于 matplotlib（Agg 后端）+spring_layout（固定seed=42，布局可复现），深色背景#1a1a2e，节点大小按度数缩放，社区颜色与 HTML 输出共用同一调色板；EXTRACTED 置信度边画实线、其余画虚线并降低透明度；有社区标签时自动带图例。产出graphify-out/graph.svg，CLI 提示其可直接嵌入 Obsidian、Notion、GitHub README 等任意 Markdown 渲染环境，无 JavaScript 依赖。matplotlib 缺失时会给出pip install matplotlib的提示。

GraphML（to_graphml()，L1205 起）：产出graphify-out/graph.graphml，可用 Gephi、yEd 等任何 GraphML 兼容工具打开。实现上有几处工程化处理：

• 社区 ID 作为节点属性写入，Gephi 可据此着色；边保留confidence属性；
• 内部标记（_origin、_src/_tgt等）被剥离，不泄漏到导出文件；
• None转空串、非标量（dict/list）转 JSON 字符串，规避 networkx 对非标量属性值的限制；XML 非法控制字符被清除；
• 原子写：先写临时文件再os.replace，避免中途失败留下 0 字节的.graphml被下游误认为完整导出。

六、Step 7d：MCP 服务（--mcp）——把图谱变成可查询工具

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

这会启动一个stdio MCP 服务器，把图谱包装成 7 个工具供外部 Agent 实时查询。graphify/serve.py 中注册的工具名（L1617-L1681）正是：

把该服务接入 Claude Desktop 或任意 MCP 兼容的 Agent 编排器后，其他 Agent 就能"活"地查询这张图。参考文档特别指出两个常见坑及解法：

1. Claude Desktop 不执行$(...)命令替换；
2. 若 graphify 通过uv tool install安装，系统python3无法 import graphify。

因此command必须填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"] } } }

实现层面，graphify/serve.py 的_load_graph()对输入做了防御：强制.json后缀、执行文件大小上限检查、兼容links/edges两种键名，并对旧版节点 ID 方案输出升级提示——这些保证 MCP 服务加载graph.json时不会因损坏文件或超大文件崩溃。服务端还维护一个带 LRU 的项目上下文缓存（GRAPHIFY_MAX_CONTEXTS，默认 8、最小 1），支持多图谱场景下的并发查询。

七、Step 8：Token 缩减基准（仅当 total_words > 5000）

参考文档的判定条件是：读取graphify-out/.graphify_detect.json中的total_words，大于 5000 才运行基准；<= 5000时静默跳过——小语料上图谱的价值是结构性清晰而非 Token 压缩。

graphify benchmark

运行时把输出直接贴到对话中。CLI 侧（graphify/cli.pycmd == "benchmark"分支，L2931 起）会先做文件大小上限检查，再从.graphify_detect.json读取corpus_words传入基准函数；读取失败则退回 graphify/benchmark.py 中的估算（每节点约 50 词）。

graphify/benchmark.py 的测量方法透明可复核：

• 基线：corpus_tokens = corpus_words × 100 / 75（即 100 词 ≈ 133 tokens 的朴素全量塞入方案）；
• 图谱侧：对 5 个内置示例问题（如 "how does authentication work"）分别做查询——按标签匹配选出 top 3 起始节点、BFS 展开 3 层子图，把NODE .../EDGE ...行按每 4 字符 1 token 估算；
• 输出：语料总 Token、节点/边数、平均查询成本、缩减倍数（reduction_ratio），以及每个问题各自的[Nx]缩减明细。

输出报告形如：

graphify token reduction benchmark -------------------------------------------------- Corpus: 12,000 words -> ~16,000 tokens (naive) Graph: 340 nodes, 812 edges Avg query cost: ~420 tokens Reduction: 38.1x fewer tokens per query Per question: [41.2x] how does authentication work ...

若 5 个示例问题都匹配不到节点，基准返回 "Build the graph first" 错误，提示先建图。

八、小结：Flag 与命令的完整对照

掌握以上内容后，你可以按语料规模和下游工具链（Obsidian/Neo4j/FalkorDB/MCP 客户端）组合选择导出分支：所有命令都以graphify-out/下的graph.json为唯一输入源，导出分支之间相互独立，任一失败不影响其他产物；而 MERGE 幂等、原子写与参数化查询等实现细节，则保证了重复运行和增量重建场景下的数据安全。

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