graphify 扩展导出完全指南：Wiki、Neo4j/FalkorDB 推送、SVG/GraphML、MCP 服务与 Token 缩减基准测试

graphify 将代码库及其文档、SQL schema、配置和 PDF 解析为可查询的知识图谱，而"导出"环节决定这张图谱能以什么形态被消费。本文以 graphify 官方技能参考 exports.md 为主体，逐步骤拆解 --wiki、--neo4j、--falkordb、--svg、--graphml、--mcp 各标志位对应的导出操作，并深入 cli.py、export.py、exporters/graphdb.py 与 serve.py 的源码实现，说明每个子命令的默认路径、幂等语义、凭据处理方式与前置依赖，让读者既会操作、也知其所以然。

一、导出步骤在 /graphify 流水线中的位置：标志位驱动，各跑各的

exports.md 是 graphify 面向 pi 等 Agent 平台的技能参考文档，其触发条件在开篇就写得很清楚：

当用户传入了任一导出标志位（--wiki、--neo4j、--neo4j-push、--falkordb、--falkordb-push、--svg、--graphml、--mcp），或语料规模足以运行 token 缩减基准测试时加载本文档。每个步骤只在自己的标志位出现时才执行。

这种"一步一标志位"的设计意味着 /graphify 流水线的尾部是可组合的：一次构建可以同时产出 Wiki、数据库脚本和 MCP 服务，也可以什么都不导出。从源码结构看，所有静态格式导出最终都汇聚到 graphify export <format> 这一个分发点。cli.py 中定义了合法子命令集合与用法提示：

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)

各导出子命令共享同一组默认值（cli.py）：

参数	默认值	说明
--graph	graphify-out/graph.json	待导出的图文件
--labels	graphify-out/.graphify_labels.json	社区标签映射（int 社区号 → 名称）
--report	graphify-out/GRAPH_REPORT.md	分析报告
分析侧车	graphify-out/.graphify_analysis.json	社区/内聚度/god nodes 数据

--graph 一旦显式指定，--labels 和 --report 会自动跟随到该图所在目录（cli.py）。若图文件不存在，CLI 会直接报错 Run /graphify <path> first.——所有导出步骤的前提是先完成一次完整构建。

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

graphify export wiki

参考文档特别强调时序约束：该步骤必须跑在 Step 9（清理）之前，此时 .graphify_labels.json 仍然可用，Wiki 中的社区才能带上可读名称。

从 cli.py 的实现看，Wiki 导出有两个硬性前置：

1. .graphify_analysis.json 必须存在且非空，否则直接拒绝导出并提示 Run graphify extract . (or graphify cluster-only .) to regenerate community data first.——这是为了防止生成没有社区结构的残缺 Wiki；
2. 若该文件中缺少 god nodes 数据，会用 analyze.py 的 god_nodes() 现场补算。

导出成功后写入 graphify-out/wiki/ 目录，其中 wiki/index.md 是设计给 Agent 的入口文件。社区标签（来自 --labels）与内聚度数据（来自 .graphify_analysis.json）都会随文章一并生成。

三、Step 7：Neo4j 导出（仅当传入 --neo4j 或 --neo4j-push）

3.1 生成 Cypher 脚本（--neo4j）

graphify export neo4j

产出 graphify-out/cypher.txt，可用 cypher-shell < graphify-out/cypher.txt 批量导入。to_cypher 的生成逻辑值得注意：

• 每个节点按 file_type（缺失时为 Entity）打成 label，例如 MERGE (n:Python {id: '...', label: '...'})；
• 每条边按 relation（缺失时为 RELATES_TO）打成关系类型，并保留 confidence 属性（EXTRACTED/INFERRED/AMBIGUOUS）；
• 全部使用 MERGE 语义，重复执行不会产生重复数据。

3.2 直推到运行中的 Neo4j（--neo4j-push ）

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

默认 URI 为 bolt://localhost:7687，默认用户为 neo4j；凭据未提供时，Agent 应向用户索取。push_to_neo4j 通过官方 Python driver（需要 pip install neo4j）连接，同样采用 MERGE 做 upsert，执行完毕打印推送的节点/边数量。

一个容易被忽略的安全细节：密码除了 --password 之外还支持 NEO4J_PASSWORD 环境变量（cli.py）。注释中的理由很直白——--password 会出现在进程 argv 里，会被 ps 输出和 shell history 捕获，生产环境更建议用环境变量。--push 模式下若既没有 --password 也没有环境变量，CLI 会显式报错 --password required for --push（cli.py）。

四、Step 7a：FalkorDB 导出（仅当传入 --falkordb 或 --falkordb-push）

4.1 生成 OpenCypher 文件（--falkordb）

graphify export falkordb

同样产出 cypher.txt。参考文档对 FalkorDB 与 Neo4j 的关键差异给出了明确指引：FalkorDB 的 GRAPH.QUERY 一次只能执行一条语句，没有 Neo4j cypher-shell 那样的批量脚本导入能力，所以"装载"一张图应优先使用 --falkordb-push；仅当你需要一份可移植的 cypher.txt 工件时才用裸导出。CLI 在裸导出成功后也会主动打印这条建议（cli.py）。

4.2 直推到运行中的 FalkorDB（--falkordb-push ）

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

push_to_falkordb 的 docstring 把与 Neo4j 路径的差异讲得非常完整，这里逐条整理为可操作的要点：

维度	Neo4j 路径	FalkorDB 路径
连接方式	bolt driver（pip install neo4j）	FalkorDB Python SDK（pip install falkordb）
URI 解析	bolt://host:port	只解析 host/port，scheme 仅是信息性的：falkordb://localhost:6379、redis://localhost:6379、裸 localhost:6379 三者等价，默认端口 6379
图选择	—	db.select_graph(graph_name)，目标图名默认 graphify
认证	必须提供用户/密码	可选——FalkorDB 默认无凭据运行，user/password 可以为 None
语句执行	session 批量提交	graph.query(cypher, params) 单条执行
幂等性	MERGE upsert	同为 MERGE upsert，重复执行安全

凭据处理与 Neo4j 对称：支持 --password 或 FALKORDB_PASSWORD 环境变量二选一（cli.py）。由于认证本身可选，Agent 只在实例确实要求认证时才向用户索取凭据——这正是参考文档"Credentials are optional; ask the user only if the instance requires auth"的落地方式。集成行为由 test_falkordb_integration.py 覆盖。

五、Step 7b 与 7c：SVG 与 GraphML 静态图导出

graphify export svg      # --svg 标志位
graphify export graphml  # --graphml 标志位

SVG：写入 graphify-out/graph.svg，可直接嵌入 Obsidian 笔记、Notion 或 GitHub README，纯静态、无 JavaScript 依赖。to_svg 使用 matplotlib 的 spring 布局（seed=42 保证每次生成结果可复现），节点大小随度数缩放，社区配色与 HTML 视图一致；EXTRACTED 置信度的边画实线，INFERRED 等低置信边画虚线且透明度更低——图例即置信度。

GraphML：写入 graphify-out/graph.graphml，面向 Gephi、yEd 等桌面分析工具。to_graphml 做了两处面向工具生态的加固：社区 ID 写成节点属性便于 Gephi 按社区着色，边置信度保留为边属性；同时剥离内部标记属性（_origin、_src/_tgt 等）、剔除 XML 1.0 不合法的 C0 控制字符，并把 None/字典值强制转为标量，避免单个脏标签导致整份导出失败。

两者共同的边界条件是：若 graph.json 超过安全尺寸上限，除 html 子命令会降级为社区聚合视图外，其余子命令会直接报错退出（cli.py）。

六、Step 7d：MCP 服务器（仅当传入 --mcp）

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

这条命令启动一个 stdio 传输的 MCP 服务器，把图谱变成 Agent 可以实时查询的"活"服务。工具清单在 serve.py 中注册，恰好是参考文档列出的七个：query_graph、get_node、get_neighbors、get_community、god_nodes、graph_stats、shortest_path；另外还提供 graphify://report、graphify://stats、graphify://god-nodes、graphify://surprises、graphify://audit、graphify://questions 六个只读资源（serve.py），其中 graphify://audit 会给出 EXTRACTED/INFERRED/AMBIGUOUS 三类边的占比。

6.1 为什么 command 必须写绝对解释器路径

参考文档给出了两个具体原因，两者都能在对应当前仓库中找到印证：

1. Claude Desktop 配置里无法执行 $(...) 这类 shell 命令替换，所以必须把 cat graphify-out/.graphify_python 打印出来的绝对解释器路径硬编码进配置；
2. 若 graphify 是通过 uv tool install 安装的隔离环境，系统 python3 根本导入不了 graphify 包。

对应的 claude_desktop_config.json 配置：

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

配置进 Claude Desktop 或任何支持 MCP 的 Agent 编排器后，其他 Agent 就能实时查询这张图，而不是每次重新解析源码。

6.2 服务端的查询机制速览

从 serve.py 的源码结构看，stdio 服务之外还内置了 Streamable HTTP 传输（serve_http），支持 --api-key（或 GRAPHIFY_API_KEY）鉴权、--stateless 无状态模式与空闲会话回收，适合团队共享一个常驻图谱服务。查询路径本身有一套完整的检索机制：trigram 倒排索引做候选预筛、IDF 加权的多级标签匹配（精确 1000 分 > 前缀 100 分 > 子串 1 分，见 serve.py）、以及带 hub 节点跳过的 BFS 遍历。服务端还支持多项目上下文：GRAPHIFY_MAX_CONTEXTS（默认 8）控制 LRU 缓存容量，每个 tool 调用都可以通过 project_path 参数切换目标图（serve.py）。注意 MCP 依赖属于可选 extra：缺 mcp 包时会提示 pip install "graphifyy[mcp]"（serve.py）。

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

判断依据是 graphify-out/.graphify_detect.json 中的 total_words 字段：

graphify benchmark

输出应直接贴进对话。cli.py 中 benchmark 命令会自动从 detect 输出读取语料词数并传入 run_benchmark。基准测试的口径在 benchmark.py 里定义得非常具体：

• 朴素基线：语料词数按 100 words ≈ 133 tokens 折算（corpus_tokens = corpus_words * 100 // 75）；
• 查询成本：内置五个样本问题（如 "how does authentication work"、"what connects the data layer to the api"，见 benchmark.py），对每个问题从最匹配的 3 个节点出发做 3 层 BFS，统计子图渲染成 NODE/EDGE 文本后的 token 数（按 4 字符/token 估算）；
• 输出：corpus_tokens、avg_query_tokens、reduction_ratio（每次查询比朴素方案少多少倍 token）及逐问题的明细。

参考文档同时划定了适用边界：total_words <= 5000 时静默跳过——对小语料而言，图谱的价值在于结构性清晰而非 token 压缩，此时跑基准测试没有意义。这提示读者把 benchmark 结果理解为"大语料下图查询相对全量上下文的成本优势"，而不是普适的性能指标。

八、导出标志位速查表

标志位	命令	产物	幂等/前置依赖
--wiki	graphify export wiki	graphify-out/wiki/（含 index.md）	需 .graphify_analysis.json；须在 Step 9 清理前运行
--neo4j	graphify export neo4j	graphify-out/cypher.txt	MERGE 语义，可重复执行
--neo4j-push <uri>	graphify export neo4j --push bolt://... --user neo4j --password ...	直推 Neo4j	默认 bolt://localhost:7687；需 neo4j driver；支持 NEO4J_PASSWORD
--falkordb	graphify export falkordb	graphify-out/cypher.txt（OpenCypher）	无批量导入，装载请用 push
--falkordb-push <uri>	graphify export falkordb --push falkordb://localhost:6379	直推 FalkorDB	默认图名 graphify；认证可选；支持 FALKORDB_PASSWORD
--svg	graphify export svg	graphify-out/graph.svg	需 matplotlib；边样式编码置信度
--graphml	graphify export graphml	graphify-out/graph.graphml	社区/置信度作为属性导出
--mcp	$(cat graphify-out/.graphify_python) -m graphify.serve graphify-out/graph.json	stdio MCP 服务（7 个工具）	command 必须为绝对解释器路径
（自动）	graphify benchmark	控制台报告	仅当 total_words > 5000

九、小结

graphify 的导出层遵循"标志位驱动、各步独立"的原则：Wiki 面向 Agent 阅读（index.md 为入口），Neo4j/FalkorDB 面向图数据库查询（均以 MERGE 保证幂等，且都提供"生成脚本"与"直推"两种形态），SVG/GraphML 面向静态嵌入与桌面工具，MCP 服务则把图谱变成可被任意 Agent 编排器实时查询的接口，benchmark 则为大语料给出量化依据。所有子命令共享 graphify-out/graph.json 及 --graph/--labels 覆盖机制，凭据统一支持环境变量以规避 argv 泄露。深入实现时，建议从 cli.py 的 export 分发段 切入，配合 export.py 与 exporters/graphdb.py 的对应函数，再辅以 test_export.py、test_serve.py、test_falkordb_integration.py 与 test_benchmark.py 中的测试用例验证行为边界。