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

来源：[safishamsi/graphify](https://github.com/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、成本低），保持图谱不过期。