Graphiti 开源贡献指南从 Issue 到 PR 的完整参与路线图【免费下载链接】graphitiBuild Real-Time Knowledge Graphs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/grap/graphitiGraphiti 是一个为 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.10pyproject.toml 中声明requires-python 3.10,4uv包管理器官方安装文档见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_URIneo4j://... 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_FALKORDB1 DISABLE_KUZU1 DISABLE_NEPTUNE1并运行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工具职责仓库配置要点RuffLint 格式化行宽 100启用 E/F/UP/B/SIM/I 规则集忽略 E501Pyright静态类型检查typeCheckingMode basic仅扫描graphiti_core目标 Python 3.10Pytest测试框架标记integration类型测试asyncio_mode auto第三方集成贡献规范重点Graphiti 将核心库保持轻量所有第三方集成必须作为可选依赖加入这是保证启动速度和用户体验一致性的关键。可选依赖 TYPE_CHECKING 双保险模式在pyproject.toml注册 optional extra并同步加入devextra[project.optional-dependencies] your-service [your-package1.0.0] dev [ # ... existing dev dependencies your-package1.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.pykuzu_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 展示了如何在无真实数据库的情况下用specGraphDriver的 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），仅供参考