Contributing Guidelines（中文译文）
原始 DeepWiki 页面：https://deepwiki.com/getzep/graphiti/12.1-contributing-guidelines
翻译时间：2026-05-27T08:45:01.926Z
翻译模型：deepseek-chat
原文字符数：12313
项目：Graphiti (graphiti)
---
贡献指南
相关源文件
以下文件被用作生成此 Wiki 页面的上下文：
.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.ymlCONTRIBUTING.mdsignatures/version1/cla.json
本文档概述了为 Graphiti 代码库贡献代码的流程、工作流和技术要求。它涵盖了从识别工作到提交 PR 和审查的完整贡献生命周期。有关设置本地开发环境的信息，请参阅开发环境设置。有关测试基础设施的详细信息，请参阅测试框架。有关 CI/CD 管线和质量工具链的详细信息，请参阅代码质量与持续集成/持续部署（CI/CD）。
贡献路径
Graphiti 提供了四种不同的贡献途径，每种途径都有不同的工作流和期望。贡献者可以通过处理现有问题、创建新工单、分享用例或支持社区来参与贡献。
贡献路径概览
标题：Graphiti 贡献流程
graph TB
subgraph "入口点"
A["选择现有问题<br/>'help wanted'<br/>'good first issue'"]
B["创建工单<br/>GitHub 问题跟踪器"]
C["分享用例<br/>examples/ 文件夹"]
D["帮助社区<br/>Discord 服务器"]
end
subgraph "工作类型"
E["Bug 修复<br/>清晰的复现步骤"]
F["功能请求<br/>用户故事格式"]
G["文档<br/>示例代码"]
H["支持<br/>问答协助"]
end
subgraph "要求"
I["需要 RFC<br/>>500 行代码变更"]
J["问题讨论<br/>Discord 或 GitHub"]
K["无正式流程<br/>直接提交"]
L["社区参与<br/>持续参与"]
end
subgraph "提交"
M["Fork 并提交 PR<br/>签署 Zep-CLA.md"]
N["GitHub 问题<br/>标记为 Feature Request"]
O["提交 examples/ PR<br/>编写 README 文档"]
P["在 Discord 上回答<br/>无需正式提交"]
end
A --> E
A --> F
B --> E
B --> F
C --> G
D --> H
E --> I
E --> J
F --> I
F --> J
G --> K
H --> L
I --> M
J --> M
K --> O
L --> P
来源： 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 设计与审查流程
sequenceDiagram
participant 贡献者
participant GitHubIssue as "GitHub 问题<br/>(RFC)"
participant Discord as "Discord<br/>#development"
participant 维护者
participant PR as "拉取请求"
Note over 贡献者: 变更 >500 行代码或新集成？
贡献者->>GitHubIssue: 创建 RFC 问题<br/>技术设计<br/>理由说明
贡献者->>Discord: 分享方法<br/>请求反馈
维护者->>GitHubIssue: 审查架构<br/>提供反馈
维护者->>Discord: 技术讨论
alt RFC 已批准
贡献者->>PR: 提交实现<br/>引用 RFC 问题
维护者->>PR: 审查代码<br/>检查一致性
else RFC 缺失
贡献者->>PR: 提交 PR 但未附带 RFC
维护者->>PR: 标记为 needs-rfc
Note over PR: 在 RFC 完成前不审查 PR
end
必须进行 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 验证系统
graph TB
subgraph "PR 事件"
A["pull_request_target<br/>opened/synchronize"]
B["issue_comment<br/>CLA 签署文本"]
end
subgraph "CLA 助手工作流"
C[".github/workflows/cla.yml<br/>CLAAssistant 任务"]
D["contributor-assistant/github-action@v2.6.1"]
end
subgraph "CLA 存储"
F["signatures/version1/cla.json<br/>signedContributors[]"]
end
subgraph "验证"
H["检查贡献者<br/>是否在签名列表中"]
I["在 PR 上发布评论<br/>附带签署说明"]
J["更新 cla.json<br/>提交到主分支"]
end
A --> C
B --> C
C --> D
D --> H
H -->|"未签署"| I
I -->|"用户评论：<br/>'I have read the CLA...'"| B
H -->|"已签署"| J
J --> F
签署流程：
- 向仓库提交你的第一个 PR。
- CLA 助手机器人会在 PR 上发布一条包含签署说明的评论。
- 阅读评论中链接的 CLA 文档
.github/workflows/cla.yml:28。 - 在 PR 上评论：
I have read the CLA Document and I hereby sign the CLA.github/workflows/cla.yml:20。 - 机器人会更新
signatures/version1/cla.jsonsignatures/version1/cla.json:1-10，添加你的签名元数据。 - 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=passwordPython 版本： 需要 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。
可选依赖模式
标题：可选集成的代码实体映射
graph TB
subgraph "自然语言空间"
User["贡献者"]
Feat["新的大语言模型（LLM）提供商"]
end
subgraph "代码实体空间"
Config["pyproject.toml<br/>[project.optional-dependencies]"]
Guard["TYPE_CHECKING<br/>导入守卫"]
Client["graphiti_core/llm_client/<br/>provider_client.py"]
end
User -- "在 extras 中定义" --> Config
Feat -- "实现" --> Client
Client -- "使用导入守卫保护" --> Guard
实现模式：
- 添加到
pyproject.toml：将你的依赖项定义为可选的 extras，并将其包含在devextra 中CONTRIBUTING.md:156-165。 - 使用
TYPE_CHECKING模式：在你的集成模块中，有条件地导入依赖项，以避免未安装该 extra 的用户在运行时出现错误CONTRIBUTING.md:168-183。
来源： CONTRIBUTING.md:150-183, .github/prompts/pr-triage.md:32-42
PR 分类与审查
Graphiti 使用自动化的分类系统来确定贡献的优先级。
自动化审查系统
Graphiti 使用基于 Claude 的自动化审查系统来对 PR 进行分类并提供技术反馈。
标题：自动化 PR 审查管线
graph LR
subgraph "GitHub Actions"
Triage[".github/workflows/pr-triage.yml"]
Review[".github/workflows/claude.yml"]
end
subgraph "Claude Code Action"
Logic["评估评分标准<br/>安全扫描<br/>差异分析"]
end
Triage -- "在打开时触发" --> Logic
Review -- "在同步时触发" --> Logic
Logic -- "发布" --> Labels["triage/high<br/>needs-rfc<br/>slop-detected"]
来源： .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 分类状态机
stateDiagram-v2
[*] --> NewPR
NewPR --> TriageProcess: PR 已打开
TriageProcess --> triage/high: 核心路径中的 Bug 修复
TriageProcess --> triage/medium: 附带 RFC 的功能
TriageProcess --> needs-rfc: >500 行代码或新集成（无 RFC）
TriageProcess --> needs-tests: 缺少测试覆盖
TriageProcess --> slop-detected: 低质量 / AI 低质量内容
slop-detected --> recommend-close
needs-rfc --> triage/skip: 过时的 RFC
来源： .github/prompts/pr-triage.md:1-115, .github/scripts/setup-triage-labels.sh:14-25