内容
格里斯特尔
基于图的 AI 智能代码分析。格里斯特尔将代码仓库解析成 [FalkorDB](https://b.com/) 图数据库，保留了结构化关系 — 函数调用、导入、继承、路由和数据模型 — 以便 AI 代理可以像人类一样查询代码。
## 为什么选择图数据库而非向量？向量的代码搜索会丢失代码结构。"函数 A 调用函数 B，而函数 B 继承自类 C" 变成三个无关的文本块。格里斯特尔在图数据库中保留了这些关系作为一等边，使得以下查询成为可能：
- **影响分析** — "如果我更改这个函数，会有什么影响？"
- **调用跟踪** — "请求如何从 API 处理程序流向数据库？"
- **约定推断** — "这个项目遵循什么模式？"
## 适用范围（以及不适用的范围）
格里斯特尔是一个 **快速、无需构建、框架感知** 的结构化图数据库，基于 tree-sitter 构建 — 支持多种语言的查询图数据库，通过 MCP 原生暴露给代理。这是它的 niche，我们需要明确其边界：
- **导入解析基于名称和启发式**，而非类型解析。它的覆盖率很高，适用于导航和架构，但可能会遗错误地链接类型（如 SCIP/LSIF、Sourcegraph）能够准确获取的边。边是尽力而为的，而不是证明。
- **它不是数据流/污染引擎** （CodeQL/Glean）。它建模结构化和框架关系（调用、路由→处理程序、代码→模型、测试→代码、依赖），而非值级数据流。
- 在支持的框架下，覆盖率最强；框架以外的构造（以及没有解析器的语言）则不被表示。
简而言之：比 ctags/tree-sitter-only 工具更深入，比类型解析索引更轻量和广泛 — 并设计为由代理而非人类 IDE 查询。
## 支持的语言
| 语言 | 函数 | 类 | 导入 | 路由 | 组件 | 测试 |
| --- | --- | --- | --- | --- | --- | --- |
| Python | 是 | 是 | 是 | FastAPI, Flask, Django | - | pytest |
| TypeScript | 是 | 是 | 是 | Express, Hono, Fastify | React | jest, vitest |
| JavaScript | 是 | 是 | 是 | Express, Hono, Fastify | React | jest, vitest |
| Vue / Svelte / Astro | 是 | 是 | 是 | - | - | - |
Vue/Svelte/Astro 单文件组件通过提取嵌入的 `<script>` 块（或 Astro `---` 前置元数据）并使用 TypeScript 解析器分析，从而使脚本的函数、类、导入和变量成为图节点，与代码库的其他部分一起。
## 快速入门
**先决条件：** Python 3.11+ 和 Docker（带有 Docker Compose）。FalkorDB 在 Docker 中运行；其他组件通过 pip 安装。
### 1. 安装
> 发布后，最快捷的方式将是 `uvx gristle` / `pipx install gristle`，或 `docker run ghcr.io/alchemy-agentic/gristle`。
目前（以及开发过程中），从源代码安装：
```bash
git clone https://github.com/Alchemy-Agentic/gristle
cd gristle
pip install -e .
```
### 2. 启动 FalkorDB 并检查设置
```bash
docker compose up -d falkordb # 启动 FalkorDB（暴露 localhost:6390）
gristle doctor # 验证 Falk、解析器和配置
```
3. 索并从终端探索
```bash
gristle ingest examples --repo-id demo
overview --repo-id demoistle explore register --repo
gristle query "MATCH:Function)-[:CALL(g:Function).name, g.name LIMIT" --repo-id demo
gristle ingest` 指向您自己的项目以索引参见 [examples/](examples获取引导式演练。
### 4. 将其连接到您的 AI 客户端（MCP）
运行 Gristle 作为本地（`gristle serve或仅 `gristle`），并将其添加到您的客户端配置 Claude Desktop 的 `clktop_config.json`:
```json
{
"mcpServers "gristle":command": "",
"args": ["serve"],
"env": "GRISTLE_FDB_HOST": "localhost",
"GRISTLE_FALK_PORT": "6390"
}
}
}
> FalkorDB 第一次工具调用前运行docker compose up -d falkordb`）。
或使用 Claude Code CLI：` mcp add gristle --env GRISTLE_FALKORDB_PORT=6390 -- gristle serve`。
然后要求您的代理索引仓库（`gristle`）并探索代码调用或运行影响分析 作为库使用
G 的管道和查询引擎可以直接从 Python 使用：
```from gristle.graph.client
from gristle.ingestion.pipeline import IngestionPipeline
from gristle.parsers.registry import ParserRegistry
graph = GraphClient(host="localhost", port=6390, repo_id="myrepo")
IngestionPipeline(graph, ParserRegistry().build_default()).ingest_repo("/path/to/your/repo")
rows = graph.execute("MATCH (Function) RETURN count(f) AS functions").records
print(rows) # e.g. [{'functions': 1234}]
```
### 远程（HTTP 传输）
作为共享或云部署的 HTTP 服务器运行：
```bash
GRISTLE_TRANSPORT=streamable-http \
GRISTLE_API_KEY=your-secret-key \
gristle
```
从您的 MCP 客户端连接：
```json
{
"mcpServers": {
"gristle": {
"url": "https://your-gristle-host/mcp",
"headers": {
"Authorization": "Bearer your-secret-key"
}
}
}
}
```
### Railway
Gristle 在 Railway 上已准备好生产。将其与 FalkorDB 实例一起部署，并设置以下环境变量：
| 变量 | 值 |
| --- | --- |
| `GRISTLE_FALKORDB_HOST` | FalkorDB 服务的内部主机名 |
| `GRISTLE_FALKORDB_PORT` | `6390` |
| `GRISTLE_FALKORDB_PASSWORD` | FalkorDB 密码（如果设置） |
| `GRISTLE_API_KEY` | 身份验证的密钥令牌 |
Railway 自动注入 `PORT`，Gristle 会获取它。Docker 镜像中的传输默认设置为 `streamable-http`。
## MCP 工具
Gristle 通过 MCP 暴露了 30 种工具和 2 种资源。参见 [集成指南](docs/integration-guide.md)，以获取完整的参考资料，包括示例、工作流程和提示。
主要工具：`gristle_ingest`, `gristle_explore`, `gristle_impact`, `gristle_trace`, `gristle_search`, `gristle_conventions`, `gristle_tests`, `gristle_routes`, `gristle_config`, `gristle_dead_exports`, `gristle_cycles`, `gristle_data_contract`, `gristle_type_usage`, `gristle_security`, `gristle_unauthenticated_routes`, `gristle_dependency_health`.
## 开发
```bash
pip install -e ".[dev]"
pytest # 运行测试
ruff check src/ tests/ # 校验
ruff format src/ tests/ # 格式化
mypy src/ # 类型检查
```
### Docker
同时运行 FalkorDB 和 Gristle：
```bash
docker compose up -d
```
这会在端口 6390 上启动 FalkorDB，并在端口 8080 上启动 Gristle，带有 streamable-http 传输。
## 文档
| 文档 | 受众 | 内容 |
| --- | --- | --- |
| [集成指南](docs/integration-guide.md) | AI 代理、消费应用程序 | 图模式、工具参考、配置、部署、工作流程 |
| [架构](ARCHITECTURE.md) | 贡献者 | 数据模型、解析器、摄入管道、调用解析、设计决策 |
| [变更日志](CHANGELOG.md) | 所有人 | 版本历史、新增功能、重大变更 |
| [路线图](docs/future-improvements.md) | 产品规划 | 即将推出的功能、优先级 |
## 贡献
欢迎贡献 — 参见 [CONTRIBUTING.md](CONTRIBUTING.md)，获取设置、测试和拉取请求检查清单。报告安全问题请参见 [SECURITY.md](SECURITY.md)。
## 许可证
Gristle 在 [MIT License](LICENSE) 下发布。
Gristle 连接到 — 但不包含 — [FalkorDB](https://www.falkordb.com/)，后者根据其自己的许可证分发。
