agentic_huge_data_base / wiki
页面 Cognee · 10.5 贡献指南·DeepWiki 中文全文译文
DeepWiki 中文译文 / Cognee / 10.5

10.5 · 贡献指南

记忆管道与知识图谱构建 · 聚焦本章的模块关系、源码依据与实现要点。

项目Cognee 章节10.5 状态全文译文 模块测试、发布与运维、模型调用与提供方适配、配置治理、智能体运行时
项目要点页2.5 参考项目 项目章节目录Cognee DeepWiki 原始章节贡献指南 上一章10.4 下一章10.6
源码线索
  • .coderabbit.yaml
  • .env.example
  • .github/CODEOWNERS
  • .github/pull_request_template.md
  • .github/workflows/approve_dco.yaml
  • .github/workflows/backend_docker_build_test.yml
  • .github/workflows/clean_stale_pr.yaml
  • .github/workflows/community_tests.yml
  • .pre-commit-config.yaml
  • AGENTS.md
模块标签
  • 测试、发布与运维
  • 模型调用与提供方适配
  • 配置治理
  • 智能体运行时
  • 安装与启动

章节正文

贡献指南

原始 DeepWiki 页面https://deepwiki.com/topoteretes/cognee/10.5-contributing-guidelines

贡献指南

相关源文件

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

  • .coderabbit.yaml
  • .env.example
  • .github/CODEOWNERS
  • .github/pull_request_template.md
  • .github/workflows/approve_dco.yaml
  • .github/workflows/backend_docker_build_test.yml
  • .github/workflows/clean_stale_pr.yaml
  • .github/workflows/community_tests.yml
  • .pre-commit-config.yaml
  • AGENTS.md
  • CONTRIBUTING.md
  • NOTICE.md
  • cognee/infrastructure/context/BaseContextProvider.py
  • cognee/infrastructure/context/__init__.py
  • cognee/infrastructure/entities/BaseEntityExtractor.py
  • cognee/infrastructure/entities/__init__.py
  • licenses/README.md
[!IMPORTANT]
给贡献者的提示： 创建分支时，请从 dev 分支新建分支 CONTRIBUTING.md:1-2。

本文档提供了向 Cognee 项目贡献代码的技术指南。内容涵盖开发环境搭建、代码标准、测试要求以及拉取请求提交流程。Cognee 是一个开源知识引擎，可将原始数据转换为供 AI 智能体使用的持久化知识图谱，我们欢迎任何能够改进其核心管线及基础设施适配器的贡献 CONTRIBUTING.md:4-8, AGENTS.md:1-4。

来源：CONTRIBUTING.md:1-8, AGENTS.md:1-4

快速链接

在开始之前，请先熟悉以下资源：

来源：CONTRIBUTING.md:10-16

贡献方式

您可以通过多种方式为 Cognee 做出贡献：

  • 📝 提交错误报告或功能请求。
  • 💡 改进文档。
  • 🔍 审查拉取请求。
  • 🛠️ 贡献代码或测试（例如，新的数据库适配器或检索策略）。
  • 🌐 帮助其他用户。

来源：CONTRIBUTING.md:17-26

联系我们

您可以通过以下方式与 Cognee 团队和社区取得联系：

GitHub 协作

  • 提交 Issue 用于报告错误、提出功能请求或进行讨论 CONTRIBUTING.md:32-32。
  • 提交拉取请求以贡献代码或文档 CONTRIBUTING.md:33-33。
  • 参与现有 Issue 和 PR 中的讨论 CONTRIBUTING.md:34-34。

社区渠道

  • 加入我们的 Discord 社区 进行实时讨论 CONTRIBUTING.md:37-37。
  • 参与社区活动和讨论 CONTRIBUTING.md:38-38。

直接联系

  • 邮箱：vasilije@cognee.ai CONTRIBUTING.md:42-42。
  • 如有商业咨询或敏感事宜，请通过电子邮件联系我们 CONTRIBUTING.md:43-43。

我们会在 2 个工作日内回复所有沟通 CONTRIBUTING.md:46-46。

来源：CONTRIBUTING.md:27-46

Issue 标签

为了帮助您找到最合适的 Issue 进行处理，我们使用以下标签：

标签描述
good first issue非常适合项目新手 CONTRIBUTING.md:52-52。
bug某些功能未按预期工作 CONTRIBUTING.md:53-53。
documentation文档的改进或补充 CONTRIBUTING.md:54-54。
enhancement新功能或改进 CONTRIBUTING.md:55-55。
help wanted需要额外关注或协助 CONTRIBUTING.md:56-56。
question需要进一步信息 CONTRIBUTING.md:57-57。
wontfix此问题将不会处理 CONTRIBUTING.md:58-58。

来源：CONTRIBUTING.md:48-61

开发环境搭建

所需工具
  • Python：支持版本 >= 3.10 且 < 3.14 AGENTS.md:30-30。
  • uv：推荐用于包管理和虚拟环境 CONTRIBUTING.md:67-67。
  • pre-commit：提交前本地验证所需 CONTRIBUTING.md:68-68。

来源：CONTRIBUTING.md:65-68, AGENTS.md:30-30

Fork 和克隆
  1. Fork 仓库：
    • 核心开发：Fork cognee CONTRIBUTING.md:72-72。
    • 向量/图适配器：Fork cognee-community CONTRIBUTING.md:79-79。
  1. 克隆您的 Fork 并安装：
git clone https://github.com/<您的-github-用户名>/cognee.git
cd cognee
uv sync --dev --all-extras --reinstall
uv run pip install pre-commit && pre-commit install

来源：CONTRIBUTING.md:68-85, AGENTS.md:32-35

分支策略

始终从 dev 分支创建新分支：

git checkout -b feature/您的功能名称

来源：CONTRIBUTING.md:86-91

代码标准与风格

Cognee 通过自动化检查和人工审查来保持高质量的代码。

代码检查与格式化

该项目使用 ruff 和 ty 来保证代码质量。

  • Ruff：用于代码检查（uv run ruff check .）和格式化（uv run ruff format .）AGENTS.md:57-59。
  • Ty：用于静态类型检查（uv run ty check .）AGENTS.md:63-65。
  • uv lock：CI 会检查 uv.lock 文件是否与 pyproject.toml 同步 github/workflows/community_tests.yml:38-39。

来源：.github/workflows/community_tests.yml:38-55, AGENTS.md:57-65, CONTRIBUTING.md:140-141

文档

进行更改时，请更新相关文档 CONTRIBUTING.md:96-96。未添加文档字符串的函数和类定义被视为不完整；应为这些定义提供文档字符串 coderabbit.yaml:61-62。

来源：CONTRIBUTING.md:96, .coderabbit.yaml:61-62

测试

环境配置

将 .env.template 复制为 .env，并将您的 OPENAI_API_KEY 作为 LLM_API_KEY 提供 CONTRIBUTING.md:102-102。

来源：CONTRIBUTING.md:102, .env.example:1-12

运行测试

该项目使用 pytest 进行测试。

运行特定测试类别：

  • 单元测试：uv run pytest cognee/tests/unit/ -v AGENTS.md:52-52。
  • 集成测试：uv run pytest cognee/tests/integration/ -v AGENTS.md:53-53。
  • CLI 单元测试：uv run pytest cognee/tests/cli_tests/cli_unit_tests/ -v .github/workflows/community_tests.yml:136-136。
  • 遥测测试：uv run pytest cognee/tests/test_telemetry.py -v .github/workflows/community_tests.yml:161-161。

来源：AGENTS.md:50-54, .github/workflows/community_tests.yml:136-161

贡献工作流

自然语言到代码实体映射

下图将贡献流程步骤映射到相应的代码级实体和自动化工作流。

贡献生命周期映射

Cognee · 自然语言到代码实体映射 · 图 1
Cognee · 自然语言到代码实体映射 · 图 1

来源：CONTRIBUTING.md:70-163, .github/workflows/approve_dco.yaml:1-21, .github/workflows/community_tests.yml:1-10, .github/workflows/clean_stale_pr.yaml:1-6

PR 提交与 DCO

1. 签署提交 所有贡献必须经过签署，以表示同意开发者原创证书（DCO）CONTRIBUTING.md:158-163。请使用 -s 标志：

git commit -s -m "您更改的描述"

2. PR 模板与证据 在向 dev 分支创建拉取请求时，您必须：

  • 填写 .github/pull_request_template.md 中的 PR 模板 .github/pull_request_template.md:1-39。
  • 提供本地机器上单元测试和集成测试通过的截图 CONTRIBUTING.md:152-152。
  • 在 PR 正文中包含 DCO 确认声明 .github/pull_request_template.md:37-39。

3. DCO 确认声明 对于非受信任的贡献者，PR 正文必须包含以下确切文本：

"我确认此拉取请求中每个提交的所有代码均符合 Topoteretes 开发者原创证书的条款"

来源：CONTRIBUTING.md:138-163, .github/pull_request_template.md:1-39, .github/workflows/approve_dco.yaml:21-39

自动化与维护

CI 工作流

该仓库使用多个 GitHub Action 工作流来维护代码健康：

工作流文件路径用途
DCO 检查.github/workflows/approve_dco.yaml验证非组织成员的 PR 正文中的 DCO 声明 .github/workflows/approve_dco.yaml:8-12。
社区测试.github/workflows/community_tests.yml在所有 PR 上运行模拟单元测试和代码质量检查 .github/workflows/community_tests.yml:3-5。
陈旧 PR.github/workflows/clean_stale_pr.yaml将 60 天无活动的 PR 标记为陈旧 .github/workflows/clean_stale_pr.yaml:19-23。

来源：.github/workflows/approve_dco.yaml:1-41, .github/workflows/community_tests.yml:1-10, .github/workflows/clean_stale_pr.yaml:1-33

贡献者仓库结构

下图将高级贡献要求桥接到用于验证的特定文件结构。

基础设施与验证桥接

Cognee · 贡献者仓库结构 · 图 2
Cognee · 贡献者仓库结构 · 图 2

来源：.github/workflows/approve_dco.yaml:21-26, .pre-commit-config.yaml:1-22, .env.example:1-12, AGENTS.md:62-63

社区指南

  • 互相尊重，包容他人 CONTRIBUTING.md:171-171。
  • 帮助他人学习和成长 CONTRIBUTING.md:172-172。
  • 遵守行为准则 CONTRIBUTING.md:173-173。
  • 提供建设性反馈 CONTRIBUTING.md:174-174。

来源：CONTRIBUTING.md:169-176