14.4 · Contributing Guidelines

长期记忆与上下文管理 · 本章是 Mem0 DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Mem0 章节14.4 状态全文译文模块测试、发布与运维、文档对象与元数据、安装与启动、系统架构

项目要点页2.5 参考项目项目章节目录Mem0 DeepWiki 原始章节Contributing Guidelines 上一章14.3 下一章14.5

源码线索

.github/workflows/cd.yml
.github/workflows/cli-node-cd.yml
.github/workflows/openclaw-cd.yml
.github/workflows/ts-sdk-cd.yml
.github/workflows/vercel-ai-cd.yml
CONTRIBUTING.md
docs/components/vectordbs/dbs/pinecone.mdx
docs/contributing/development.mdx
docs/contributing/documentation.mdx
mem0/configs/vector_stores/pinecone.py

模块标签

测试、发布与运维
文档对象与元数据
安装与启动
系统架构
检索、召回与索引

中文译文

Contributing Guidelines（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/mem0ai/mem0/14.4-contributing-guidelines

翻译时间：2026-05-27T08:45:07.468Z

翻译模型：deepseek-chat

原文字符数：9058

项目：Mem0 (mem0)

---

贡献指南

贡献工作流

Mem0 采用标准的 Fork 和拉取请求工作流。所有贡献必须通过 GitHub 拉取请求提交，并在合并前通过自动化质量检查。

拉取请求提交流程

flowchart TB
    Fork["Fork 仓库<br/>github.com/mem0ai/mem0"]
    Clone["本地克隆 Fork<br/>git clone"]
    Branch["创建功能分支<br/>feature/my-new-feature"]
    Develop["实现变更"]
    PreCommit["运行 Pre-commit 钩子<br/>pre-commit install"]
    Tests["添加/更新测试<br/>pytest / pnpm test"]
    Docs["更新文档<br/>文档字符串 + 示例"]
    TestLocal["本地运行测试<br/>make test / pnpm test"]
    Commit["提交变更<br/>git commit"]
    Push["推送到 Fork<br/>git push origin"]
    PR["创建拉取请求<br/>GitHub UI"]
    CI["自动化 CI 检查<br/>GitHub Actions"]
    Review["代码评审"]
    Merge["合并到 main"]

    Fork --> Clone
    Clone --> Branch
    Branch --> Develop
    Develop --> PreCommit
    PreCommit --> Tests
    Tests --> Docs
    Docs --> TestLocal
    TestLocal --> Commit
    Commit --> Push
    Push --> PR
    PR --> CI
    CI --> Review
    Review --> Merge

    CI -.->|"失败"| Develop
    Review -.->|"请求变更"| Develop

贡献要求：

功能分支：使用专用的功能分支，例如 feature/my-new-feature docs/contributing/development.mdx:16-16 或 feature/f1 CONTRIBUTING.md:10-10。
需要测试：如果修改了代码（新功能或缺陷修复），请添加相应的测试 CONTRIBUTING.md:11-11。
文档：包含适当的文档/文档字符串以及运行该功能的示例 CONTRIBUTING.md:12-12。
验证：确保所有测试在所有支持的版本上通过后再提交 CONTRIBUTING.md:13-13, CONTRIBUTING.md:61-61。

来源：CONTRIBUTING.md:5-16, CONTRIBUTING.md:61-61, docs/contributing/development.mdx:9-25

---

开发环境搭建

Mem0 使用 hatch 管理 Python 环境，使用 pnpm 管理 Node.js/TypeScript 组件。

Python 环境架构

graph TB
    subgraph "Hatch 环境"
        Dev39["dev_py_3_9<br/>Python 3.9"]
        Dev310["dev_py_3_10<br/>Python 3.10"]
        Dev311["dev_py_3_11<br/>Python 3.11"]
        Dev312["dev_py_3_12<br/>Python 3.12"]
    end

    subgraph "工具与框架"
        PreCommit["pre-commit<br/>Git 钩子"]
        Pytest["pytest<br/>测试"]
        Ruff["ruff<br/>代码检查"]
    end

    Dev39 --> PreCommit
    Dev310 --> PreCommit
    Dev311 --> PreCommit
    Dev312 --> PreCommit

    PreCommit --> Pytest
    PreCommit --> Ruff

环境激活命令

语言	工具	命令	用途
Python	`hatch`	`hatch shell dev_py_3_11`	激活 Python 3.11 开发环境 `CONTRIBUTING.md:27-27`
Python	`hatch`	`hatch build --clean`	构建二进制 Wheel 包和源码压缩包 `.github/workflows/cd.yml:32-32`
Python	`pre-commit`	`pre-commit install`	安装 Git 钩子 `CONTRIBUTING.md:40-40`
Python	`make`	`make install_all`	安装所有可选依赖 `docs/contributing/development.mdx:44-44`
Node.js	`pnpm`	`pnpm install --frozen-lockfile`	在子包中安装依赖 `.github/workflows/openclaw-cd.yml:34-34`

来源：CONTRIBUTING.md:19-33, CONTRIBUTING.md:35-41, docs/contributing/development.mdx:29-45, .github/workflows/cd.yml:22-33

---

代码标准与质量

为了保持代码库的一致性，贡献者必须遵守特定的代码检查和格式化标准。

标准检查清单

代码检查：使用 ruff 通过 make lint 捕获样式问题 docs/contributing/development.mdx:59-65。
格式化：使用 make format 格式化代码 docs/contributing/development.mdx:67-73。
配置校验：新组件（如向量存储）必须使用 pydantic.BaseModel 进行配置校验，包括使用 model_validator 进行跨字段检查 mem0/configs/vector_stores/pinecone.py:7-55。

实现示例：向量存储提供者

添加新提供者时，请遵循 PineconeDB 中建立的模式：

继承自 VectorStoreBase mem0/vector_stores/pinecone.py:25-25。
实现核心方法：create_col、insert、search、update、get、delete mem0/vector_stores/pinecone.py:93-210。
在 mem0/configs/vector_stores/ 中提供配置类 mem0/configs/vector_stores/pinecone.py:7-7。

来源：docs/contributing/development.mdx:49-82, mem0/vector_stores/pinecone.py:25-210, mem0/configs/vector_stores/pinecone.py:7-55

---

测试要求

所有代码变更必须包含测试，并通过现有测试套件。Python 测试通过 pytest 和 make 管理。

运行 Python 测试

# 使用默认 Python 版本运行测试
make test

# 测试特定 Python 版本
make test-py-3.9
make test-py-3.10
make test-py-3.11
make test-py-3.12

CONTRIBUTING.md:45-59

测试模式

测试应使用 unittest.mock 隔离外部依赖，并使用 pytest.fixture 实现可复用的设置 tests/vector_stores/test_pinecone.py:1-17。

来源：CONTRIBUTING.md:45-59, tests/vector_stores/test_pinecone.py:1-191

---

文档系统

Mem0 使用 Mintlify 管理文档。

本地文档搭建

前置条件：Node.js 版本 23.6.0 或更高 docs/contributing/documentation.mdx:11-11。
安装：npm i -g mintlify docs/contributing/documentation.mdx:24-24。
执行：在 docs/ 目录下运行 mintlify dev docs/contributing/documentation.mdx:38-38。

来源：docs/contributing/documentation.mdx:1-55

---

持续部署与发布

Mem0 使用 GitHub Actions 进行自动化发布。发布通过创建带有特定标签前缀的 GitHub Release 来触发。

发布标签系统

包	注册表	标签前缀	示例标签	工作流文件
`mem0ai`（Python SDK）	PyPI	`v*`	`v0.1.31`	`.github/workflows/cd.yml`
`mem0-cli`（Python CLI）	PyPI	`cli-v*`	`cli-v0.2.1`	-
`mem0ai`（TS SDK）	npm	`ts-v*`	`ts-v2.4.6`	`.github/workflows/ts-sdk-cd.yml`
`@mem0/cli`（Node CLI）	npm	`cli-node-v*`	`cli-node-v0.1.2`	`.github/workflows/cli-node-cd.yml`
`@mem0/vercel-ai-provider`	npm	`vercel-ai-v*`	`vercel-ai-v2.0.6`	`.github/workflows/vercel-ai-cd.yml`
`@mem0/openclaw-mem0`	npm	`openclaw-v*`	`openclaw-v1.0.1`	`.github/workflows/openclaw-cd.yml`

来源：CONTRIBUTING.md:71-78

部署工作流（Python 示例）

sequenceDiagram
    participant Dev as 维护者
    participant GH as GitHub Release
    participant Action as CD 工作流
    participant PyPI as PyPI 注册表

    Dev->>GH: 创建 Release（标签：v0.1.x）
    GH->>Action: 触发 cd.yml
    Action->>Action: hatch build --clean
    Action->>PyPI: pypa/gh-action-pypi-publish
    Note over Action, PyPI: OIDC 可信发布

发布详情：

PyPI：通过 pypa/gh-action-pypi-publish 使用 OIDC 可信发布 .github/workflows/cd.yml:43-45。
npm：通过 npm CLI（>= 11.5.1）使用 --provenance 进行 OIDC 可信发布 .github/workflows/ts-sdk-cd.yml:43-45。
前置条件：在创建 Release 之前，必须在 pyproject.toml 或 package.json 中更新版本号 CONTRIBUTING.md:82-82。

来源：.github/workflows/cd.yml:1-46, .github/workflows/ts-sdk-cd.yml:1-47, CONTRIBUTING.md:65-92