shanxia/docs/graphify-学习总结.md

Graphify 学习总结（面向本仓库落地）

来源：safishamsi/graphify —— 给 AI 编程助手用的“知识图谱层（Memory Layer）”：把代码/文档/多媒体抽取成 可查询的知识图谱，让助手优先“沿着图导航理解项目”，而不是靠全仓库 grep 或随机读文件。

---

1. Graphify 解决什么问题

• 项目理解成本高：大型仓库里“关键概念/模块边界/调用路径”很难靠短上下文快速建立全局认知。
• 跨域资产割裂：应用代码、数据库 schema、基础设施脚本、设计文档、PDF、图片/视频往往分散，难以统一检索与关联。
• AI 上下文不稳定：聊天上下文会被挤出窗口，Graphify 用 graphify-out/graph.json 做“可重复查询”的项目记忆。

---

2. 运行后生成的产物（关键）

在目标目录执行（在支持 slash command 的工具里可用 /graphify .）后，会生成：

graphify-out/
├── graph.html       # 浏览器可视化：点选节点、过滤、搜索
├── GRAPH_REPORT.md  # 高层摘要：god nodes、惊喜连接、建议问题
└── graph.json       # 全量图：可离线查询/做二次分析/供 MCP 使用

本仓库现状：已存在 bx/graphify-out/（含 GRAPH_REPORT.md 与缓存），说明至少对 bx/ 子系统已经跑过一次图谱构建。

---

3. Graphify 的“报告”里有什么（为什么有用）

GRAPH_REPORT.md 的信息密度最高，常见内容：

• God nodes：连接度最高的概念/模块（项目主干与流量枢纽）。
• Surprising connections：跨模块的“意外关联”，按意外程度排序。
• Why / Rationale：会把注释里的意图（如 NOTE: / WHY: / HACK:）抽成节点并关联回代码/文档。
• Suggested questions：适合直接问助手的 4–5 个问题模板。
• Confidence tags：关系标注 EXTRACTED / INFERRED / AMBIGUOUS，区分“抽取到的事实”与“推断”。

---

4. 支持的内容类型与隐私边界（README 要点）

支持的输入范围很广：代码（多语言 AST）、常见文档、PDF、图片、音视频、以及外部 URL（论文/YouTube 等）。

隐私与处理方式要点：

• 代码文件：本地 tree-sitter AST 抽取（不走 API）。
• 音视频：本地转写（faster-whisper）。
• 文档/PDF/图片等语义抽取：通过你的 AI 助手会话模型完成（也可用 headless graphify extract 配合各类后端/密钥）。
• 无遥测：README 标注不做 telemetry/usage tracking。

---

5. 常用命令（最常用一组）

• 构建图谱（工具内 slash command）：
  • /graphify .
• 增量更新（只重抽变更文件）：
  • /graphify ./docs --update
• 只重做聚类（不重抽取）：
  • /graphify . --cluster-only
• 生成 wiki（把图谱转成可爬的 markdown 目录）：
  • /graphify . --wiki
• 查询与路径：
  • /graphify query "what connects auth to the database?"
  • /graphify path "UserService" "DatabasePool"
  • /graphify explain "RateLimiter"

CI/无 IDE 场景（headless）：

• graphify extract ./docs ...

---

6. 安装与平台集成（README 要点）

• 运行环境：Python 3.10+
• PyPI 官方包名：graphifyy（double-y），CLI 仍叫 graphify
• 常见安装：
  • uv tool install graphifyy && graphify install
  • 或 pipx install graphifyy && graphify install

Cursor 集成命令（README）：

• graphify cursor install（安装对 Cursor 的指令/集成）
• graphify cursor uninstall（卸载）

---

7. 团队协作建议（README 要点）

Graphify 推荐 提交 graphify-out/ 到 git，让团队成员拉取即获得“项目地图”。

同时建议在 .gitignore 里忽略一些机器相关/本地成本文件：

graphify-out/manifest.json  # mtime-based，clone 后不稳定
graphify-out/cost.json      # 本地成本统计
# graphify-out/cache/       # 可选：提交可加速，不提交可减小仓库体积

并可启用 hook：

• graphify hook install：在 commit 等动作后自动更新图谱（AST-only 时无 API 成本），并提供 merge driver 来避免 graph.json 冲突标记。

---

8. 在本仓库的推荐用法（最小落地）

如果你的目标是“让 AI 更懂仓库结构”，建议固定两条习惯：

1. 回答架构/代码库问题前优先阅读 graphify-out/GRAPH_REPORT.md（先看 god nodes 与社区划分）。
2. 改动代码后跑一次图谱更新（AST-only、成本低），保持图谱不过期。