Disentinel/grafema

# Grafema [](https://github.com/Disentinel/grafema/actions/workflows/ci.yml) [](https://github.com/Disentinel/grafema/actions/workflows/ci.yml) [](https://github.com/Disentinel/grafema/actions/workflows/benchmark.yml) 基于图的代码分析。AI 应该查询图，而不是阅读代码。 Grafema 通过静态分析从你的代码库构建一个可查询的图。与其阅读成千上万个文件，不如直接提问：“谁调用了这个？”、“这个数据从哪里来？”、“这个文件做什么？” —— 并获得结构化的答案。 ## 快速开始 ``` npm install grafema grafema init grafema analyze ``` ### 探索你的代码 ``` # 这个文件做什么？（紧凑 DSL 概览，比源代码小 10-20 倍） grafema tldr src/server.ts # 谁调用了这个函数？ grafema who handleRequest # 这些数据来自哪里？（反向数据流追踪） grafema wtf req.user # 为什么要这样构建？（知识库决策） grafema why auth-middleware ``` ### 与 AI (MCP) 配合使用 在项目根目录下的 `.mcp.json` 中添加： ``` { "mcpServers": { "grafema": { "command": "npx", "args": ["grafema-mcp", "--project", "."] } } } ``` 对于 Claude Desktop（macOS 上位于 `~/Library/Application Support/Claude/claude_desktop_config.json`）： ``` { "mcpServers": { "grafema": { "command": "npx", "args": ["grafema-mcp", "--project", "/path/to/project"] } } } ``` 提供 24+ MCP 工具：`find_nodes`、`find_calls`、`trace_dataflow`、`get_file_overview`、`describe`、`query_graph` 等等。AI agent 直接查询图而不是读取文件 —— 更快、更便宜、更完整。 ## 为什么选择 Grafema？ **对于 AI agents：** 一次 `describe` 调用返回的文件概览，其 token 消耗比读取源码少 10-20 倍。`find_calls` 通过一次查询即可在整个代码库中找到所有调用者 —— 无需 grep，也不会遗漏引用。 **对于遗留代码库：** Grafema 针对无类型/弱类型代码，类型系统无法提供帮助。它为没有类型的语言构建类型系统级别的理解。 **为了理解代码：** 从前端 `fetch()` 到后端 handler 追踪数据流。反向追踪 `res.json(data)` 直到数据的来源。跨越文件，跨越服务。 ## 语言支持 | 语言 | 解析 (Parse) | 分析 (Analyze) | 解析 (Resolve) | 数据流 | 状态 | |----------|-------|---------|---------|----------|--------| | JavaScript/TypeScript | 完整 | 完整 | 完整 | 完整 | 生产环境 | | Rust | 完整 | 完整 | 完整 | 部分 | Beta | | Haskell | 完整 | 完整 | 完整 | 部分 | Beta | | Java | 完整 | 完整 | 完整 | 部分 | Beta | | Kotlin | 完整 | 完整 | 完整 | 部分 | Beta | | Python | 完整 | 完整 | 完整 | 部分 | Beta | | C/C++ | 完整 | 完整 | 完整 | 部分 | Beta | | Go | 完整 | 完整 | 完整 | 部分 | Alpha | | PHP | - | - | 仅解析 | - | Stub (存根) | JS/TS 是主要支持的语言，提供完整的数据流支持。其他语言通过基于 Haskell 的分析 pipeline 提供解析器、分析器和 resolver。详情请参阅 [已知限制](./KNOWN_LIMITATIONS.md)。 ## CLI 命令 | 命令 | 回答的问题 | 作用 | |---------|-------------------|--------------| | `grafema tldr ` | “这个文件里有什么？” | 紧凑的 DSL 概览（节省 10-20 倍 token） | | `grafema wtf ` | “这是从哪里来的？” | 反向数据流追踪 | | `grafema who ` | “谁在使用这个？” | 查找所有调用者/引用 | | `grafema why ` | “为什么是这样的？” | 知识库决策 | | `grafema init` | | 在项目中初始化 Grafema | | `grafema analyze` | | 构建/重建代码图 | | `grafema doctor` | | 检查系统健康状况 | | `grafema overview` | | 高层级项目统计 | ## VS Code 扩展 具有 7 个基于树的面板的交互式图导航。 ``` # 从源代码安装 cd packages/vscode && pnpm install && pnpm build # VS Code: Cmd+Shift+P > "Extensions: Install from VSIX..." ``` - **Cmd+Shift+G** — 查找光标处的图节点 - 探索入边/出边 - 点击节点跳转到源码 ## 架构 Grafema 使用基于 Rust 的分析 pipeline 和自定义图数据库： ``` grafema analyze → Rust orchestrator → Haskell analyzers → RFDB graph database ↓ grafema tldr / MCP query ← @grafema/util query layer ← unix socket ``` - **RFDB** — 针对代码分析工作负载优化的列式图数据库 - **Orchestrator** — 协调跨语言分析的 Rust 二进制文件 - **Analyzers** — 每种语言（JS/TS, Rust, Java 等）的 Haskell 二进制文件 - **MCP Server** — 用于 AI agent 集成的 24+ 工具 ## 环境变量 | 变量 | 用途 | |----------|---------| | `GRAFEMA_ORCHESTRATOR` | Orchestrator 二进制文件的路径（自动检测） | | `GRAFEMA_RFDB_SERVER` | RFDB 服务器二进制文件的路径（自动检测） | 通常不需要 —— 二进制文件包含在 npm 包中。在开发 Grafema 或使用自定义构建时使用这些变量。 ## 平台支持 | 平台 | 状态 | |----------|--------| | macOS ARM (Apple Silicon) | 完全支持 | | macOS Intel (x64) | 完全支持 | | Linux x64 | 完全支持 | | Linux ARM64 | 计划中 (v0.4) | | Windows | 未计划 | ## 软件包 | 包 | 描述 | |---------|-------------| | [grafema](./packages/grafema) | 统一包 (CLI + MCP + binaries) | | [@grafema/cli](./packages/cli) | 命令行接口 | | [@grafema/mcp](./packages/mcp) | 用于 AI 助手的 MCP 服务器 | | [@grafema/util](./packages/util) | 查询层，配置，RFDB 生命周期 | | [@grafema/types](./packages/types) | 类型定义 | | [@grafema/api](./packages/api) | GraphQL API 服务器 | ## 文档 - [入门指南](./docs/getting-started.md) - [配置](./docs/configuration.md) - [已知限制](./KNOWN_LIMITATIONS.md) - [Datalog 速查表](./docs/datalog-cheat-sheet.md) - [更新日志](./CHANGELOG.md) ## 系统要求 - Node.js >= 18 - macOS (ARM 或 Intel) 或 Linux x64 ## 许可证 Apache-2.0 ## 作者 Vadim Reshetnikov

标签：AI编程助手, Claude Desktop, DevTools, GNU通用公共许可证, IPv6支持, LLM工具, MCP, MITM代理, Model Context Protocol, Node.js, WebSocket, 云安全监控, 云资产清单, 代码分析, 代码搜索, 代码理解, 依赖分析, 凭证管理, 函数调用图, 可视化界面, 威胁情报, 安全专业人员, 开发者工具, 自动化攻击, 逆向工程, 静态分析