agentic_huge_data_base / wiki
页面 Graphiti · 12.1 贡献指南·DeepWiki 中文全文译文
DeepWiki 中文译文 / Graphiti / 12.1

12.1 · 贡献指南

时序知识图谱与动态事实记忆 · 聚焦本章的模块关系、源码依据与实现要点。

项目Graphiti 章节12.1 状态全文译文 模块系统架构、安装与启动、测试、发布与运维、界面与交互
项目要点页2.5 参考项目 项目章节目录Graphiti DeepWiki 原始章节贡献指南 上一章12 下一章12.2
源码线索
  • .github/ISSUE_TEMPLATE/bug_report.md
  • .github/prompts/pr-triage.md
  • .github/pull_request_template.md
  • .github/scripts/setup-triage-labels.sh
  • .github/workflows/cla.yml
  • .github/workflows/claude.yml
  • CONTRIBUTING.md
  • signatures/version1/cla.json
模块标签
  • 系统架构
  • 安装与启动
  • 测试、发布与运维
  • 界面与交互
  • 配置治理

章节正文

贡献指南

原始 DeepWiki 页面https://deepwiki.com/getzep/graphiti/12.1-contributing-guidelines

贡献指南

相关源文件

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

  • .github/ISSUE_TEMPLATE/bug_report.md
  • .github/prompts/pr-triage.md
  • .github/pull_request_template.md
  • .github/scripts/setup-triage-labels.sh
  • .github/workflows/cla.yml
  • .github/workflows/claude.yml
  • CONTRIBUTING.md
  • signatures/version1/cla.json

本文档概述了为 Graphiti 代码库贡献代码的流程、工作流和技术要求。它涵盖了从识别工作到提交 PR 和审查的完整贡献生命周期。有关设置本地开发环境的信息，请参阅开发环境设置。有关测试基础设施的详细信息，请参阅测试框架。有关 CI/CD 管线和质量工具链的详细信息，请参阅代码质量与持续集成/持续部署（CI/CD）。

贡献路径

Graphiti 提供了四种不同的贡献途径，每种途径都有不同的工作流和期望。贡献者可以通过处理现有问题、创建新工单、分享用例或支持社区来参与贡献。

贡献路径概览

标题：Graphiti 贡献流程

Graphiti · 贡献路径概览 · 图 1
Graphiti · 贡献路径概览 · 图 1

来源： CONTRIBUTING.md:9-46

基于问题的贡献

标记有 help wanted 和 good first issue 标签的问题已经过预先审核，明确了范围和内容。每个问题都包含有关问题背景和预期解决方法的上下文。

标签范围支持级别
good first issue范围有限，需求明确维护者提供指导
help wanted问题定义清晰，实现方式开放社区审查可用
needs-rfc新功能/集成或 >500 行代码需要技术设计审查

Bug 报告要求：

  • 清晰总结具体问题的标题 CONTRIBUTING.md:23
  • 上下文：你试图完成什么任务 CONTRIBUTING.md:24
  • 预期行为与实际行为 CONTRIBUTING.md:25-26
  • 最小复现代码示例或测试用例 CONTRIBUTING.md:27
  • 环境详细信息（版本、操作系统、数据库后端） .github/ISSUE_TEMPLATE/bug_report.md:25-30

功能请求要求：

  • 用户故事格式：你在做什么以及什么阻碍了你 CONTRIBUTING.md:19
  • 提议的解决方案或方法 CONTRIBUTING.md:19
  • 标记为 "Feature Request" CONTRIBUTING.md:19

来源： CONTRIBUTING.md:11-28, .github/ISSUE_TEMPLATE/bug_report.md:9-54

大型变更的 RFC 流程

所有新功能、集成（驱动程序、大语言模型（LLM）客户端、嵌入器）以及任何超过 500 行代码的 PR，在提交 PR 之前都需要在 GitHub 上以问题形式发起请求评论（RFC）CONTRIBUTING.md:43-53。

标题：RFC 设计与审查流程

Graphiti · 大型变更的 RFC 流程 · 图 2
Graphiti · 大型变更的 RFC 流程 · 图 2

必须进行 RFC 的情况：

  • 新的数据库驱动程序 CONTRIBUTING.md:47
  • 新的大语言模型（LLM）提供商客户端 CONTRIBUTING.md:48
  • 新的嵌入向量提供商客户端 CONTRIBUTING.md:49
  • 新的 API 端点或功能 CONTRIBUTING.md:50
  • 任何重大的架构变更 CONTRIBUTING.md:51
  • 任何超过 500 行代码的 PR CONTRIBUTING.md:53

来源： CONTRIBUTING.md:43-56, .github/prompts/pr-triage.md:30-31

贡献者许可协议（CLA）签署流程

所有贡献者必须在他们的第一个 PR 被合并之前签署贡献者许可协议（CLA）。CLA 流程通过 GitHub Actions 自动完成。

CLA 工作流架构

标题：自动化的 CLA 验证系统

Graphiti · CLA 工作流架构 · 图 3
Graphiti · CLA 工作流架构 · 图 3

签署流程：

  1. 向仓库提交你的第一个 PR。
  2. CLA 助手机器人会在 PR 上发布一条包含签署说明的评论。
  3. 阅读评论中链接的 CLA 文档 .github/workflows/cla.yml:28。
  4. 在 PR 上评论：I have read the CLA Document and I hereby sign the CLA .github/workflows/cla.yml:20。
  5. 机器人会更新 signatures/version1/cla.json signatures/version1/cla.json:1-10，添加你的签名元数据。
  6. PR 上的 CLA 检查通过。

来源： signatures/version1/cla.json:1-10, .github/workflows/cla.yml:1-43

开发工作流

开发工作流遵循标准的 Fork 和分支模型，并具有特定的工具要求和质量门禁。

设置命令
# 在 GitHub 上 Fork 仓库，然后克隆
git clone https://github.com/<你的用户名>/graphiti
cd graphiti

# 安装 uv 包管理器 (https://docs.astral.sh/uv/)

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

# 设置测试环境变量
export TEST_OPENAI_API_KEY=sk-...
export TEST_URI=neo4j://localhost:7687
export TEST_USER=neo4j
export TEST_PASSWORD=password

Python 版本： 需要 3.10 或更高版本 CONTRIBUTING.md:73。

来源： CONTRIBUTING.md:63-90

质量门禁命令
命令用途执行的工具
make install安装依赖项uv sync CONTRIBUTING.md:77-78
make test运行测试套件pytest CONTRIBUTING.md:102
make format自动格式化代码ruff format CONTRIBUTING.md:106
make lint检查代码质量ruff check, pyright CONTRIBUTING.md:110
make check完整质量门禁format + lint + test CONTRIBUTING.md:143-144

来源： CONTRIBUTING.md:100-147

第三方集成指南

在贡献外部服务（大语言模型（LLM）提供商、嵌入向量服务、数据库驱动程序）的集成时，请遵循严格的模式以维护可选的依赖架构 .github/prompts/pr-triage.md:12。

可选依赖模式

标题：可选集成的代码实体映射

Graphiti · 可选依赖模式 · 图 4
Graphiti · 可选依赖模式 · 图 4

实现模式：

  1. 添加到 pyproject.toml：将你的依赖项定义为可选的 extras，并将其包含在 dev extra 中 CONTRIBUTING.md:156-165。
  2. 使用 TYPE_CHECKING 模式：在你的集成模块中，有条件地导入依赖项，以避免未安装该 extra 的用户在运行时出现错误 CONTRIBUTING.md:168-183。

来源： CONTRIBUTING.md:150-183, .github/prompts/pr-triage.md:32-42

PR 分类与审查

Graphiti 使用自动化的分类系统来确定贡献的优先级。

自动化审查系统

Graphiti 使用基于 Claude 的自动化审查系统来对 PR 进行分类并提供技术反馈。

标题：自动化 PR 审查管线

Graphiti · 自动化审查系统 · 图 5
Graphiti · 自动化审查系统 · 图 5

来源： .github/workflows/claude.yml:1-27, .github/prompts/pr-triage.md:47-56

分类评分标准

维护者使用结构化的评分标准来评估 PR .github/prompts/pr-triage.md:68-76：

信号优先级影响
Bug 修复高优先级（现有功能的最高优先级） .github/prompts/pr-triage.md:110
新功能中/跳过（需要已批准的 RFC） .github/prompts/pr-triage.md:111-113
测试必需（适用时包含单元测试和集成测试） .github/prompts/pr-triage.md:72
范围低/跳过（超过 500 行代码且没有 RFC 的 PR 会被标记为 needs-rfc） .github/prompts/pr-triage.md:75
低质量内容检测

为了保持高代码质量，表现出 "slop" 信号（通常与低质量的 AI 生成内容相关）的 PR 会被标记为建议关闭 .github/prompts/pr-triage.md:82-94：

  • 过度设计的抽象或过多的间接层 .github/prompts/pr-triage.md:86
  • 冗长、博客文章风格的 PR 描述，与代码不匹配 .github/prompts/pr-triage.md:87
  • 复制粘贴错误（文档字符串/注释中的错误名称） .github/prompts/pr-triage.md:88
  • 缺少针对提供商特定调用的错误处理 .github/prompts/pr-triage.md:90
PR 分类标签

标题：PR 分类状态机

Graphiti · PR 分类标签 · 图 6
Graphiti · PR 分类标签 · 图 6

来源： .github/prompts/pr-triage.md:1-115, .github/scripts/setup-triage-labels.sh:14-25