Graphiti 开源贡献指南：从 Issue 到 PR 的完整参与路线图-迪斯科星球

Graphiti 开源贡献指南：从 Issue 到 PR 的完整参与路线图

【免费下载链接】graphitiBuild Real-Time Knowledge Graphs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/grap/graphiti

Graphiti 是一个为 AI Agent 构建实时知识图谱的 Python 开源库，以"时间感知的图谱构建"为核心能力。本文是一份基于 CONTRIBUTING.md 整理的完整贡献指南，覆盖四条参与路径、环境搭建、开发工作流、PR 规范，以及针对 LLM 提供商、Embedding 服务与图数据库等第三方集成的架构级贡献指引，并辅以仓库源码佐证，帮助你快速定位最适合自己的贡献方式。

为什么要有结构化的贡献路径

Graphiti 团队在贡献指南中坦言，很多新手加入项目时最大的困惑是"不知道从哪里开始"。为此，仓库将贡献路径重构为四条主线，让不同背景的开发者都能找到与自己技能匹配的入口：

路径	适合人群	核心动作
认领既有 Issue	想快速上手的新手	关注`help wanted`、`good first issue`标签的预审任务
自主创建 Issue	有明确改进想法的开发者	提交 Feature Request 或 Bug Report
分享使用案例	所有使用者	将真实用例沉淀到 examples 目录
帮助他人答疑	熟悉项目的成员	在 GitHub Issues 的 helpdesk 中回答问题

这种设计避免了两类典型困境：新手因找不到入口而放弃，或贸然选择与自己能力不匹配的任务。优先处理既有 Issue（尤其修复现有功能的 Bug）能获得最快的 Review 反馈。

创建 Issue 的正确姿势

Feature Request：讲一个完整的故事

功能请求不需要"技术方案先行"，而是要讲清楚你正在做什么、什么阻碍了你、什么能让你更顺利。用"故事"而非"规格"描述，能帮助维护者理解你的真实诉求。提交时打上Feature Request标签。

Bug Report：提供可复现的最小证据

一个合格的 Bug Report 必须包含五要素：

能概括具体问题的清晰标题
遇到 Bug 时正在做什么
预期行为是什么
实际行为是什么
能演示问题的代码示例或测试用例

新功能与集成的前置门槛：RFC 机制

这是本仓库贡献规则中最关键的一条：

所有新功能与第三方集成，在提交 PR 前必须先提交 RFC（一个讨论技术设计与合理性的 GitHub Issue）。

RFC 覆盖的范围包括：

新的图数据库驱动（driver）
新的 LLM 提供商客户端
新的 Embedding 提供商客户端
新的 API 端点或能力
任何重大的架构变更

此外，任何超过 500 行的 PR 无论类型如何都强制要求 RFC。未关联 RFC 的 PR 会被打上needs-rfc标签且不予 Review，直到 RFC 获批。正确流程是：先开 Issue 讨论设计，再提交引用该 Issue 的 PR。

开发环境搭建

前置条件

Python 3.10+（pyproject.toml 中声明requires-python = ">=3.10,<4"）
uv包管理器：官方安装文档见https://docs.astral.sh/uv/getting-started/installation/
git与 GitHub 账号（Fork + 本地开发）

安装与集成测试环境变量

# 1. Fork 仓库并克隆 git clone https://github.com/getzep/graphiti cd graphiti # 2. 安装依赖（等价于 uv sync --extra dev，见 Makefile） make install # 3. 运行集成测试前配置环境变量 export TEST_OPENAI_API_KEY=... export TEST_OPENAI_MODEL=... export TEST_ANTHROPIC_API_KEY=... # 4. Neo4j 相关 export TEST_URI=neo4j://... export TEST_USER=... export TEST_PASSWORD=...

在 Makefile 中可以看到，make install实际执行的是uv sync --extra dev，即同时安装全部开发依赖（pytest、pyright、ruff 及所有可选集成的 SDK）。

标准开发工作流

从分支到 PR 的完整闭环

# 1. 创建专属分支 git checkout -b your-branch-name # 2. 修改代码并编写/更新测试 # 3. 运行测试 make test # 4. 格式化代码 make format # 5. 静态检查 make lint # 6. 提交并推送 git commit -m "Your detailed commit message" git push origin your-branch-name # 7. 在 GitHub 上向 getzep/graphiti 提交 Pull Request

提交 PR 前，务必运行make check（等价于依次执行 format、lint、test）。结合 Makefile 可以精确看到每个命令的底层逻辑：

make test会先设置DISABLE_FALKORDB=1 DISABLE_KUZU=1 DISABLE_NEPTUNE=1，并运行pytest -m "not integration"，即默认跳过集成测试，只跑单元测试；
make lint由ruff check与pyright ./graphiti_core两部分组成；
make format执行ruff check --select I --fix（自动修复 import 排序）与ruff format。

PR 提交准则

清晰描述变更的标题与说明
在描述中关联相关的 Issue 编号
确保全部测试通过、无 lint 错误
变更功能时同步更新文档

代码质量工具链

仓库统一使用三件套保障代码质量（配置见 pyproject.toml 的[tool.ruff]、[tool.pyright]与 pytest.ini）：

工具	职责	仓库配置要点
Ruff	Lint + 格式化	行宽 100，启用 E/F/UP/B/SIM/I 规则集，忽略 E501
Pyright	静态类型检查	`typeCheckingMode = "basic"`，仅扫描`graphiti_core`，目标 Python 3.10
Pytest	测试框架	标记`integration`类型测试，`asyncio_mode = auto`

第三方集成贡献规范（重点）

Graphiti 将核心库保持轻量，所有第三方集成必须作为可选依赖加入，这是保证启动速度和用户体验一致性的关键。

可选依赖 + TYPE_CHECKING 双保险模式

在pyproject.toml注册 optional extra，并同步加入devextra：

[project.optional-dependencies] your-service = ["your-package>=1.0.0"] dev = [ # ... existing dev dependencies "your-package>=1.0.0", # Include all optional extras here # ... other dependencies ]

以 pyproject.toml 中已有的集成为例：anthropic、groq、google-genai、falkordb、voyageai、gliner2、neptune、tracing等全部以 extra 形式存在；而kuzuextra 已标注为废弃（上游项目不再维护，未来版本将移除）。

在集成模块中使用TYPE_CHECKING条件导入：

from typing import TYPE_CHECKING if TYPE_CHECKING: import your_package from your_package import SomeType else: try: import your_package from your_package import SomeType except ImportError: raise ImportError( 'your-package is required for YourServiceClient. ' 'Install it with: pip install graphiti-core[your-service]' ) from None

这一模式在仓库中已被广泛实践，例如 falkordb_driver.py 顶部对falkordb包的导入，缺失时会抛出带安装指引的ImportError。

该模式带来的收益：启动更快（类型检查阶段零导入开销）、错误信息明确（自带安装命令）、开发期类型提示完整、用户体验一致。
明确禁止的行为：不要在__init__.py中添加可选导入、不要使用无错误处理的原生导入、不要把可选依赖放进主dependencies列表。

集成代码的放置位置

LLM 客户端 →graphiti_core/llm_client/
Embedding 客户端 →graphiti_core/embedder/
数据库驱动 →graphiti_core/driver/
命名遵循现有惯例（如your_service_client.py）

仓库中已有的参考实现：LLM 侧有 anthropic_client.py、gemini_client.py、openai_client.py 等；Embedding 侧有 openai.py、gemini.py、voyage.py 等。

新增图数据库驱动的完整清单

Graphiti 的驱动层是**后端无关（backend-agnostic）**的，这是其架构设计的核心亮点。新增图数据库支持时，需要镜像 graphiti_core/driver 下的既有实现，并将实现拆分为"顶层驱动 + 各提供商专属 operations"两层。

七步完整流程

注册 Provider：在 driver.py 的GraphProvider枚举中新增成员（现有成员为NEO4J、FALKORDB、KUZU、NEPTUNE）；
实现顶层驱动：在graphiti_core/driver/<backend>_driver.py中实现GraphDriver接口的五个抽象方法：execute_query()、session()、close()、build_indices_and_constraints()、delete_all_indexes()；
实现 operations 层：在graphiti_core/driver/<backend>/operations/目录下实现 operations 中定义的全部接口：EntityNodeOperations、EpisodeNodeOperations、CommunityNodeOperations、SagaNodeOperations、EntityEdgeOperations、EpisodicEdgeOperations、CommunityEdgeOperations、HasEpisodeEdgeOperations、NextEpisodeEdgeOperations、SearchOperations、GraphMaintenanceOperations；
通过属性暴露实现：在GraphDriver上通过对应的@property访问器暴露这些具体 operations；
补充查询变体：在 node_db_queries.py 与 edge_db_queries.py 中添加该提供商专属的查询语句变体；
实现 Session（如需）：若后端需要连接或事务管理，实现对应的GraphDriverSession；
注册依赖并补测试：在pyproject.toml的[project.optional-dependencies]注册后端依赖，并在tests/driver/下添加测试。

参考实现与避坑提示

推荐的参照实现依次是 neo4j_driver.py、falkordb_driver.py 和 neptune_driver.py；kuzu_driver.py已废弃，切勿以其为模板。

从源码可以看到该架构的实际落地方式：

接口层：entity_node_ops.py 定义了EntityNodeOperations抽象基类，声明了save、save_bulk、delete、delete_by_group_id、delete_by_uuids、get_by_uuid等异步抽象方法；
实现层：如 neo4j_driver.py 中Neo4jDriver在__init__里实例化Neo4jEntityNodeOperations等 11 个具体实现类，并通过entity_node_ops等属性访问器暴露；同时它借助neo4j官方异步驱动AsyncGraphDatabase建立连接，并在启动时异步调度build_indices_and_constraints()；
维护接口：graph_ops.py 的GraphMaintenanceOperations定义了clear_data、build_indices_and_constraints、delete_all_indexes、get_community_clusters等图维护操作；
会话抽象：driver.py 中GraphDriverSession提供了run、close、execute_write等抽象接口，GraphDriver.transaction()则作为统一的异步事务上下文管理器返回Transaction；
测试验证：test_falkordb_ops_routing.py 展示了如何在无真实数据库的情况下，用spec=GraphDriver的 mock 验证"按 group_id 克隆驱动并路由查询"的底层行为，这类测试在 CI 中无需安装falkordb也能运行。

测试规范

在tests/对应子目录下补充全面测试；
需要外部服务的集成测试用_int后缀标记（如 test_anthropic_client_int.py、test_neo4j_driver_routing.py 旁的集成用例）；
尽可能同时覆盖单元测试与集成测试。

常见问题

Q：改动超过 500 行怎么办？必须提前提交 RFC，否则 PR 会被标记needs-rfc并暂停 Review。

Q：找不到好任务？优先浏览标有good first issue或help wanted的 Issue，这些是经过预审、范围清晰且有专人答疑的任务。

Q：集成测试无法本地运行？make test默认通过-m "not integration"跳过集成测试；运行集成测试前需按上文设置TEST_*环境变量。

Q：不确定自己的集成方案是否符合架构？先在 Issue 讨论中公开分享方案，避免因偏离 Graphiti 架构而返工。

Q：只想分享用法不想写代码？将用例补充进 examples 目录即可，这也是被认可的贡献方式。

总结

对 Graphiti 的贡献核心可以浓缩为三句话：小改动认领 Issue 直通 PR，大改动先 RFC 再动手；第三方集成必须走可选依赖 +TYPE_CHECKING模式；图数据库驱动遵循"顶层GraphDriver+ 11 个 operations 接口 + 按后端拆分实现"的分层架构。无论你是提交修复、引入新集成，还是分享实战案例，都建议先在 GitHub Issues 中打个招呼——维护者与社区成员都在那里。

【免费下载链接】graphitiBuild Real-Time Knowledge Graphs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/grap/graphiti

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析