企业官网建设流程全解析

本文摘要：新增 SQL 或 PDF 文档后，向量索引滞后让 AI 答非所问。Graphify 以 AST 确定性建图，单次查询穿透代码、SQL 与文档。

一、问题与结论

周三下午切到feature/billing分支，往db/schema.sql加了CREATE TABLE user_profile，又往docs/丢了两份 PDF 设计文档。向 Cursor Agent 提问"谁在写user_profile表"，它引用的却是上个分支的旧 DAO 文件；换个问法追问 PDF 里的字段说明，它直接说该文件不在索引范围内。你先怀疑代码，再回头怀疑工具——方向已经反了。

结论先放前面：用/graphify把仓库建成知识图谱后，SQL DDL、源码、PDF 是同一张图里的节点，一次查询能同时返回表定义、代码引用和文档段落，且每条边附带解析器给出的解释；但静态 AST 看不到运行时拼接的表名，这类仓库不该把图谱当唯一答案。

二、排查与选择依据

向量检索的滞后是结构性的。RAG 管道要走分块 → embedding → 入库，切分支后旧分块的 embedding 还留在库里，重建完成前召回属于上一个分支；新写的schema.sql若还没跑完 embedding，同样查不到。PDF 如果没被纳入同一条管道，压根不会出现。Cursor 按文件类型分开索引（代码索引 vs 文件内容搜索），本身就难以跨格式联动，排查成本还高：你不知道当前召回基于哪个快照。

排查问题时要的是确定答案。问"哪些代码写了user_profile"，图谱返回的是"语法上确实引用了"，向量检索返回的是"余弦相似度 0.82 的 Top-5 片段"。生产问责场景下，前者能逐边追溯到文件和行号，后者无法回答"为什么这个结果相关"。

替代方案与取舍

不该用本文方案的场合：表名按租户运行时拼接、ORM XML 自动映射 SQL、大量扫描件 PDF（OCR 支持未在 README 披露）——这些场景图谱会漏边，应以向量检索或grep兜底。也不要因为有图谱就停用grep：两者是交叉验证关系，不是替代关系。

三、关键原理

Graphify 的 README 自述为 “local deterministic AST parsing, every edge explained, no vector store”（截至 2025 年 7 月仓库描述）。同一份代码两次建图，边集合一致；每条定义 → 引用、定义 → 文档提及的边都注明产生它的解析节点，这与向量库中不可追溯的相似度形成对照。

图里的节点不只一种：db/schema.sql的CREATE TABLE语句是定义节点，源码里的 SQL 标识符是引用节点，PDF 段落是文档节点。解析器在代码遇到表名时产出定义 → 引用边，在 PDF 遇到表名时产出定义 → 文档提及边——向量 RAG 只能给出"这三段文本相似"，给不出边。

建图动作由 AI Agent 驱动：/graphify以 skill 形式提供给 Claude Code、Cursor、Codex 和 Gemini CLI，即在 Agent 会话中输入命令触发，而非独立 CLI，因此建图进度与消耗受会话配置影响。

四、可运行示例

环境：中型后端仓库，含db/schema.sql（CREATE TABLE user_profile）、Python DAO 源码、docs/ops-handbook.pdf；已装 Claude Code（Cursor 端流程相同，skill 加载机制需单独确认）。

# 1. 将 graphify skill 放入 Claude Code skill 目录，重启会话# 2. 会话中执行建图/graphify# 3. 自然语言查询# "在知识图谱中查询 user_profile 的所有引用，包括代码和 PDF 提及"

常见失败：skill 装对了目录但/graphify不出现。原因是 skill 加载顺序问题——新 skill 需要重启会话，或在插件启用列表中确认已启用；修复后重新进入会话即可。

预期输出（依据 README 推断，未验证）：

schema.sql:42 CREATE TABLE user_profile (定义节点) src/dao/user.py:108 INSERT ... user_profile (边: 引用，解析节点: SQL 标识符) docs/ops-handbook.pdf:第3章 user_profile 运维说明 (边: 文档提及)

实际输出：本文未在真实仓库实测，建图耗时与查询结果需本地运行确认，不提供编造的耗时数字。验证方法：建图后连续两次执行同一查询，比对边集合是否完全一致（确定性解析预期一致），再用grep -rn "user_profile"交叉核对图谱是否遗漏引用。

五、验证结果与边界

多轮对照的具体做法：同一问题在向量索引（切分支后不重建）和图谱上各跑三轮，记录每轮返回的文件路径，看是否指向当前分支。方法给出，实测数据本文未提供（未验证）。

一个反直觉的认知要先立住：图谱没找到 ≠ 没有引用。

table_name=f"user_{tenant_id}_profile"cur.execute(f"SELECT * FROM{table_name}")

AST 能识别这是execute调用，却无法确定操作哪张表，这条边会缺失或标记不确定。处理方式是在图谱查询结果旁强制附一句"静态分析可能遗漏动态引用"，并用grep复核。另外，README 未披露底层解析器对 MySQL / PostgreSQL / SQLite 的方言覆盖度，建图前需先确认目标 SQL 方言是否被支持。

参考资料

• Graphify-Labs/graphify
• affaan-m/ECC