12 · 开发指南（Development Guide）

开发指南

开发指南

相关源文件

本章引用的主要源码文件：

• .github/prompts/pr-triage.md
• .github/scripts/setup-triage-labels.sh
• .github/workflows/release-graphiti-core.yml
• .github/workflows/typecheck.yml
• .github/workflows/unit_tests.yml
• CONTRIBUTING.md
• Makefile
• signatures/version1/cla.json

本指南概述了为 Graphiti 做贡献的开发工作流，涵盖环境搭建、代码质量标准、测试流程以及贡献过程。关于具体方面的详细信息，请参考：

• 关于贡献指南和贡献者许可协议（CLA）要求，请参见贡献指南
• 关于全面的测试文档，请参见测试框架
• 关于详细的环境搭建说明，请参见开发环境搭建
• 关于代码质量工具和持续集成/持续部署（CI/CD），请参见代码质量与持续集成/持续部署（CI/CD）

开发环境搭建

Graphiti 使用 uv 作为包管理器和构建工具，提供快速的依赖解析和可复现的构建。项目包含一个 Makefile，其中封装了常见开发任务的命令。

前置条件

• Python 3.10 或更高版本 CONTRIBUTING.md:73-73
• uv 包管理器（安装说明）CONTRIBUTING.md:74-74
• Neo4j 5.26 或 FalkorDB（用于集成测试）.github/workflows/unit_tests.yml:50-63
• 支持的大语言模型（LLM）提供商的 API 密钥（OpenAI、Anthropic 等）CONTRIBUTING.md:82-85

安装命令

# 克隆仓库
git clone https://github.com/getzep/graphiti
cd graphiti

# 安装所有依赖，包括开发工具
make install

根目录下的 Makefile 中的 make install 命令会执行 uv sync --extra dev，以安装所有项目依赖，包括测试框架、代码检查工具和类型检查器 Makefile:14-15。

来源：CONTRIBUTING.md:65-78, Makefile:1-15

环境配置

集成测试需要为外部服务设置环境变量：

# 大语言模型（LLM）提供商凭证
export TEST_OPENAI_API_KEY=...
export TEST_OPENAI_MODEL=...
export TEST_ANTHROPIC_API_KEY=...

# Neo4j 数据库连接
export TEST_URI=neo4j://...
export TEST_USER=...
export TEST_PASSWORD=...

来源：CONTRIBUTING.md:79-90, .github/workflows/unit_tests.yml:85-92

开发工作流

工作流概述

该工作流遵循标准的 Fork 和拉取请求（PR）模型，并带有自动化的质量门禁。

自然语言空间到代码实体空间

下图将高级开发操作映射到 Graphiti 仓库中使用的特定代码实体和工具。

来源：.github/prompts/pr-triage.md:17-25, CONTRIBUTING.md:153-165, Makefile:18-32

代码质量工具

Graphiti 使用多种工具来维护整个代码库的代码质量和一致性：

可用的 Make 命令

根目录下的 Makefile 提供以下目标：

• make install：使用 uv 同步依赖 Makefile:14-15。
• make format：使用 ruff 修复导入并格式化代码 Makefile:18-20。
• make lint：在 ./graphiti_core 目录上运行 ruff check 和 pyright Makefile:23-25。
• make test：运行 pytest，排除集成测试和特定驱动程序 Makefile:28-29。
• make check：按顺序运行 format、lint 和 test Makefile:31-32。

来源：Makefile:1-33

测试框架概述

Graphiti 使用 pytest 进行测试。持续集成（CI）管线将单元测试与数据库集成测试分开。

持续集成（CI）中的测试执行

unit_tests.yml 工作流定义了两个主要任务：

1. unit-tests：运行标记为 not integration 的测试，并忽略特定的集成测试文件。它通过环境变量（例如 DISABLE_NEO4J: 1）禁用所有数据库驱动程序 .github/workflows/unit_tests.yml:27-45。
2. database-integration-tests：使用 Docker 镜像启动 falkordb 和 neo4j 服务，并运行特定的集成测试，例如 tests/driver/test_falkordb_driver.py .github/workflows/unit_tests.yml:47-101。

来源：.github/workflows/unit_tests.yml:1-101, Makefile:28-29

自动化工作流

拉取请求（PR）分类与评估

仓库使用分类系统来确定贡献的优先级。对现有功能的 Bug 修复是最高优先级 .github/prompts/pr-triage.md:29-29。

分类逻辑：

• 高优先级：影响核心路径或主要后端（Neo4j/FalkorDB）的 Bug 修复 .github/prompts/pr-triage.md:110-110。
• 中优先级：非主要路径上的 Bug 修复或附带关联 RFC 的功能 .github/prompts/pr-triage.md:111-111。
• 跳过：重复内容、AI 生成的“垃圾内容”或缺少必需 RFC 的功能 .github/prompts/pr-triage.md:113-113。

.github/scripts/setup-triage-labels.sh 脚本管理此过程使用的标签 .github/scripts/setup-triage-labels.sh:13-26。

来源：.github/prompts/pr-triage.md:1-113, .github/scripts/setup-triage-labels.sh:1-27

发布流程

当推送新的版本标签（例如 v*.*.*）时，通过 GitHub Actions 自动发布到 PyPI .github/workflows/release-graphiti-core.yml:3-5。该工作流在构建和发布之前，会验证标签是否与 pyproject.toml 中定义的版本匹配 .github/workflows/release-graphiti-core.yml:26-37。

来源：.github/workflows/release-graphiti-core.yml:1-38

第三方集成开发

在添加大语言模型（LLM）提供商、嵌入向量器或数据库驱动程序的集成时，请遵循可选依赖模式，以保持核心库的轻量级。

集成模式

Graphiti 使用带有 try-except 块的 TYPE_CHECKING 模式来处理可选依赖 CONTRIBUTING.md:167-183。

模块组织

• 大语言模型（LLM）客户端：位于 graphiti_core/llm_client/ 目录下 .github/prompts/pr-triage.md:19-19
• 嵌入向量客户端：位于 graphiti_core/embedder/ 目录下 .github/prompts/pr-triage.md:20-20
• 数据库驱动程序：位于 graphiti_core/driver/ 目录下 .github/prompts/pr-triage.md:18-18

来源：CONTRIBUTING.md:148-183, .github/prompts/pr-triage.md:15-26

拉取请求（PR）指南

要求

• 需要 RFC：所有新功能、集成（驱动程序、大语言模型（LLM）客户端等）或超过 500 行代码的拉取请求（PR）在提交前都需要一个 RFC（GitHub Issue）CONTRIBUTING.md:43-55。
• 格式化：在推送前运行 make format 和 make lint CONTRIBUTING.md:104-111。
• 测试：通过 make test 确保所有测试通过 CONTRIBUTING.md:100-103。
• 贡献者许可协议（CLA）：贡献者必须签署贡献者许可协议（CLA），其拉取请求（PR）才能被合并 signatures/version1/cla.json:1-280。

来源：CONTRIBUTING.md:39-131, Makefile:31-33