rhanka / engram

rhanka/engram

open_in_new前往仓库

AI编程助手技能（支持Claude Code、Codex、OpenCode、OpenClaw、Factory Droid、Trae），可将任意代码、文档、论文或图片文件夹转化为可查询的知识图谱。

项目概览

项目概述

graphify 是一个 AI 编程助手技能（支持 Claude Code、Codex、OpenCode、OpenClaw、Factory Droid、Trae 等），能够将任意文件夹中的代码、文档、论文或图片转化为可查询的知识图谱。它提取规范实体和类型化关系，在可配置本体下跨来源去重与调和，并提供查询界面供助手或终端用户推理。项目由 rhanka 维护，使用 TypeScript 编写，采用 MIT 许可证。

核心功能

  • 知识图谱构建：从代码、文档、论文、图片、音视频等语料中提取实体和关系，生成持久化的 graph.json。
  • 本体配置：支持自定义本体配置文件（graphify.yaml），定义节点类型、关系类型、视觉编码（形状和颜色）等。
  • 实体调和：将同一实体的不同提及（如别名、变体）合并为规范实体，支持候选生成、补丁生命周期（提议、验证、试运行、应用）和审计追踪。
  • 查询与可视化：提供 graphify query、graphify path、graphify explain 等命令，以及静态的 Ontology Studio 可视化界面。
  • 多模态输入：支持文档（Markdown、HTML 等）、Office 文件、PDF（含 OCR）、图片、音视频（本地转写）。
  • 代码知识图谱：通过 tree-sitter 进行无 LLM 的 AST 解析，支持约 20 种编程语言，提取类、函数、调用图等。
  • 代理统计：graphify agent-stats 索引代理 CLI 对话记录，基于证据归属分支、提交和工作包。
  • 存储镜像：可将图镜像到 Postgres 等数据库后端，加速分组计数。

适用与不适用场景

适用场景：

  • 大型代码库理解：快速回答“什么调用了这个？”、“修改这个会破坏什么？”等问题。
  • 跨文档知识整合：将多本书、手册、注册表中的实体和关系统一为知识图谱。
  • 研究论文分析：提取概念、关系和设计原理。
  • 多代理协作：跟踪不同 AI 代理在仓库中的工作归属。

不适用场景：

  • 小型语料库：当语料很小且已能放入上下文时，token 节省不明显，价值主要在于结构清晰。
  • 需要实时更新的场景：文档或图片变更后需要手动运行 --update 进行 LLM 重提取。
  • 对隐私要求极高的场景：文档、论文、图片的内容会发送到模型 API 进行语义提取（代码文件除外）。

技术架构与依赖

  • 语言：TypeScript
  • 核心依赖：Graphology（图数据结构）、Louvain 社区检测（graphology-communities-louvain）、tree-sitter（AST 解析）、vis-network（旧版可视化，已移除）、unpdf（PDF 处理）、officeparser（Office 文件）、turndown（HTML 转 Markdown）、yt-dlp + ffmpeg + faster-whisper-ts（音视频转写）、Vercel AI SDK（可选直接后端）。
  • 可选依赖：tree-sitter 语法包（部分语言）、faster-whisper-ts（音视频）、@sentropic/design-system（设计系统令牌）。
  • 架构：确定性结构解析（无 LLM）+ 模型支持的语义解析，结果合并到 Graphology 图，使用 Louvain 聚类，导出多种格式。

安装与快速开始

要求：Node.js 20+ 和受支持的 AI 编程助手（Claude Code、Codex、Gemini CLI 等）。

npm install -g @sentropic/graphify
graphify install

在助手内构建第一个图：

/graphify .                        # Claude Code / Gemini CLI / Copilot / Aider / OpenCode 等
$graphify .                        # Codex

输出位于 .graphify/ 目录，包含 graph.json、GRAPH_REPORT.md、studio/（静态可视化）、wiki/（可选）和 cache/。

典型使用方法

从终端查询图：

graphify query "what connects attention to the optimizer?" --graph .graphify/graph.json
graphify path "DigestAuth" "Response" --graph .graphify/graph.json
graphify explain "SwinTransformer" --graph .graphify/graph.json
graphify summary --graph .graphify/graph.json

构建选项：

/graphify ./raw --directed         # 保留方向
/graphify ./raw --mode deep        # 更激进的推断边提取
/graphify ./raw --update           # 仅重新提取变更文件
/graphify ./raw --cluster-only     # 仅重新聚类
/graphify ./raw --svg              # 导出 SVG
/graphify ./raw --graphml          # 导出 GraphML
/graphify ./raw --neo4j-push bolt://localhost:7687   # 推送到 Neo4j

本体调和工作流：

graphify ontology candidates --profile-state .graphify/profile/profile-state.json --out .graphify/ontology/candidates.json
graphify ontology patch validate --profile-state .graphify/profile/profile-state.json --patch patch.json
graphify ontology patch apply --profile-state .graphify/profile/profile-state.json --patch patch.json --dry-run
graphify ontology patch apply --profile-state .graphify/profile/profile-state.json --patch patch.json --write

配置与部署要点

  • 本体配置：在 graphify.yaml 中指定本体配置文件路径、输入语料、注册表等。
  • 环境变量：API 密钥仅从环境变量读取，如 MISTRAL_API_KEY、ANTHROPIC_BASE_URL 等。
  • PDF OCR：通过 GRAPHIFY_PDF_OCR 控制，auto 模式本地预检，必要时调用 Mistral OCR。
  • 音视频转写：使用 faster-whisper-ts，可通过 GRAPHIFY_WHISPER_MODEL 等变量覆盖。
  • 存储镜像：配置 GRAPHIFY_STORE=postgres 和 GRAPHIFY_POSTGRES_URL 以使用 Postgres 后端。
  • 安全：代码文件本地处理，不上传；文档等发送到模型 API。无遥测。

限制、风险与许可证

  • 限制：语义提取依赖模型 API，可能产生幻觉；调和算法在大规模语料上可能不终止（已知问题）；token 指标为估计值，除非有真实模型调用。
  • 风险：存在已知 npm 安全公告（如 ws、hono 等），但多数不可达或为可选依赖；ollama-ai-provider 存在无修复的低危漏洞，需正式接受或移除。
  • 许可证：MIT。

官方链接

信息来源和分析时间

  • 信息来源：GitHub 仓库 README、CHANGELOG、安全文档、研究文档。
  • 分析时间：2026-07-31（基于仓库内容中的日期）。