12.4 · 代码质量与 CI/CD（Code Quality and CI/CD）

时序知识图谱与动态事实记忆 · 本章是 Graphiti DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Graphiti 章节12.4 状态全文译文模块测试、发布与运维、接口与服务契约、工作流与编排、文档对象与元数据

项目要点页2.5 参考项目项目章节目录Graphiti DeepWiki 原始章节Code Quality and CI/CD 上一章12.3 下一章13

源码线索

.github/workflows/claude-code-review-manual.yml
.github/workflows/claude-code-review.yml
.github/workflows/codeql.yml
.github/workflows/lint.yml
.github/workflows/pr-triage.yml
.github/workflows/release-graphiti-core.yml
.github/workflows/release-mcp-server.yml
.github/workflows/release-server-container.yml
.github/workflows/typecheck.yml
.github/workflows/unit_tests.yml

模块标签

测试、发布与运维
接口与服务契约
工作流与编排
文档对象与元数据
安装与启动

中文译文

代码质量与 CI/CD（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/getzep/graphiti/12.4-code-quality-and-ci-cd

翻译时间：2026-05-27T08:44:56.445Z

翻译模型：deepseek-chat

原文字符数：9726

项目：Graphiti (graphiti)

---

代码质量与持续集成/持续部署（CI/CD）

工作流概览

所有 CI/CD 自动化均以 GitHub Actions 工作流的形式实现，位于 .github/workflows/ 目录下。这些工作流可分为以下几类：

工作流文件	用途	触发条件
`lint.yml`	使用 Ruff 进行代码风格检查	推送到 `main` 分支或向 `main` 分支发起拉取请求
`typecheck.yml`	使用 Pyright 进行静态类型分析	推送到 `main` 分支或向 `main` 分支发起拉取请求
`unit_tests.yml`	Pytest 测试套件（模拟测试与集成测试）	推送到 `main` 分支或向 `main` 分支发起拉取请求
`codeql.yml`	安全漏洞扫描	推送到 `main` 分支、向 `main` 分支发起拉取请求或定时执行
`pr-triage.yml`	自动化拉取请求标签管理和 RFC 检查	拉取请求被打开或同步
`claude-code-review.yml`	自动化 Claude 拉取请求审查	拉取请求被打开或同步
`release-graphiti-core.yml`	将 `graphiti-core` 发布到 PyPI	标签 `v..*`
`release-server-container.yml`	发布 FastAPI 服务器 Docker 镜像	PyPI 发布成功
`release-mcp-server.yml`	发布 MCP 服务器 Docker 镜像	标签 `mcp-v..*`
`ai-moderator.yml`	垃圾信息和 AI 生成内容检测	Issue/评论/拉取请求

来源：.github/workflows/lint.yml:3-8, .github/workflows/typecheck.yml:6-11, .github/workflows/unit_tests.yml:3-8, .github/workflows/pr-triage.yml:3-14, .github/workflows/release-server-container.yml:3-8, .github/workflows/claude-code-review.yml:3-8

---

质量门禁与静态分析

Graphiti 采用多层方法确保代码在合并到 main 分支之前的质量。

代码检查与格式化

lint.yml 工作流使用 Ruff（>0.1.7）来强制执行编码标准 .github/workflows/lint.yml:25。它使用 --output-format=github 标志运行，以便直接在 GitHub 拉取请求界面中显示代码检查错误 .github/workflows/lint.yml:27。开发者可以通过 Makefile 使用 make lint 或 make format 命令在本地运行这些检查 .Makefile:18-25。

类型检查

typecheck.yml 工作流利用 Pyright 验证代码库中两个不同区域的类型提示 .github/workflows/typecheck.yml:1-43：

graphiti-core：位于 graphiti_core/ 目录下的核心库逻辑 .github/workflows/typecheck.yml:32。
graph-service：位于 server/ 目录下的 FastAPI 服务器实现 .github/workflows/typecheck.yml:42。

测试框架

unit_tests.yml 工作流管理 pytest 测试套件的执行 .github/workflows/unit_tests.yml:1-101。它分为两个主要任务：

unit-tests：通过将 DISABLE_NEPTUNE、DISABLE_NEO4J、DISABLE_FALKORDB 和 DISABLE_KUZU 设置为 1，运行不需要外部依赖的测试 .github/workflows/unit_tests.yml:30-33。它会明确忽略集成密集型测试文件和 tests/evals/ 目录 .github/workflows/unit_tests.yml:36-45。
database-integration-tests：启动 Neo4j（v5.26-community，带 APOC 插件）和 FalkorDB 作为 GitHub Actions 服务 .github/workflows/unit_tests.yml:50-63。它会等待这些服务健康就绪后，再运行特定驱动的集成测试 .github/workflows/unit_tests.yml:78-83, 94-100。

质量门禁——从静态分析到测试的流程

graph TD
    "PR[拉取请求]" --> "Lint[Ruff 代码检查\n(lint.yml)]"
    "PR" --> "Type[Pyright 类型检查\n(typecheck.yml)]"
    "PR" --> "Tests[Pytest 测试套件\n(unit_tests.yml)]"

    subgraph "Test_Matrix[unit_tests.yml 详情]"
        "Tests" --> "Unit[单元测试任务\n(模拟驱动)]"
        "Tests" --> "Int[集成测试任务\n(Neo4j 和 FalkorDB 服务)]"
    end

    "Lint" --> "Gate{质量门禁}"
    "Type" --> "Gate"
    "Unit" --> "Gate"
    "Int" --> "Gate"
    "Gate" -- "通过" --> "Merge[准备审查/合并]"

来源：.github/workflows/lint.yml:27, .github/workflows/typecheck.yml:32-42, .github/workflows/unit_tests.yml:30-63, Makefile:18-25

---

自动化拉取请求管理

拉取请求分类与 RFC 强制执行

pr-triage.yml 工作流会自动为来自 Fork 的拉取请求打上标签 .github/workflows/pr-triage.yml:25-40。

RFC 检查：如果拉取请求的差异行数超过 5000 行，则会自动标记为 needs-rfc 和 triage/skip，因为大的变更需要事先进行设计讨论（RFC）.github/workflows/pr-triage.yml:113-126。
标签管理：它会创建并管理诸如 triage/high、slop-detected（用于低质量的 AI 贡献）和 needs-tests 等标签 .github/workflows/pr-triage.yml:84-92。

AI 驱动的代码审查

claude-code-review.yml 工作流使用 claude-opus-4-5-20251101 提供关键反馈 .github/workflows/claude-code-review.yml:92。

安全沙箱：该工作流使用严格的工具允许列表，只允许 Claude 使用 gh pr diff、gh pr comment、gh pr view、gh pr list 和 Read 工具 .github/workflows/claude-code-review.yml:91。
隔离：它使用 pull_request_target 来允许访问密钥（用于 Anthropic API），同时确保只检出基础仓库（绝不检出 Fork 仓库），以防止恶意代码执行 .github/workflows/claude-code-review.yml:5-7, 25-28。
手动触发：claude-code-review-manual.yml 工作流允许维护者手动触发对特定拉取请求的审查，并提供全面审查或安全重点审查的选项 .github/workflows/claude-code-review-manual.yml:1-108。

拉取请求分类与审查架构

flowchart TD
    "PR_Open[拉取请求已打开（Fork）]" --> "Triage[pr-triage.yml]"
    "Triage" --> "SizeCheck{差异行数 > 5000?}"
    "SizeCheck" -- "是" --> "RFCLabel[标签: needs-rfc\n评论: 请求 RFC]"
    "SizeCheck" -- "否" --> "ClaudeEval[Claude 分类评估\n(评估标准: .github/prompts/pr-triage.md)]"

    "PR_Open" --> "Review[claude-code-review.yml]"
    "Review" --> "Security[严格工具允许列表\n(仅 gh pr diff)]"
    "Security" --> "Feedback[通过\nmcp__github_inline_comment 内联评论]"

    "Manual_Trigger[手动触发\n(workflow_dispatch)]" --> "Manual_Review[claude-code-review-manual.yml]"
    "Manual_Review" --> "Security"

来源：.github/workflows/pr-triage.yml:113-126, .github/workflows/claude-code-review.yml:25-28, 91-94, .github/workflows/claude-code-review-manual.yml:1-108

---

发布管线

Graphiti 自动化了核心库、FastAPI 服务器和 MCP 服务器的发布流程。

1. graphiti-核心（PyPI）

由匹配 v*.*.* 的标签触发 .github/workflows/release-graphiti-core.yml:5。它会验证标签是否与 pyproject.toml 中的版本匹配，然后运行 uv build 并发布到 PyPI .github/workflows/release-graphiti-core.yml:27-37。

2. FastAPI 服务器（Docker）

release-server-container.yml 工作流在 "Release to PyPI" 工作流成功完成后自动触发 .github/workflows/release-server-container.yml:4-6。

它会等待新版本在 PyPI 索引上可用后再进行构建 .github/workflows/release-server-container.yml:89-103。
它使用 Depot 为 linux/amd64 和 linux/arm64 构建 zepai/graphiti 镜像 .github/workflows/release-server-container.yml:137-142。

3. MCP 服务器（Docker）

由匹配 mcp-v*.*.* 的标签触发 .github/workflows/release-mcp-server.yml:5。

变体：它会构建 standalone（外部数据库）和 combined（包含 FalkorDB）两种镜像 .github/workflows/release-mcp-server.yml:27-39。
依赖同步：它会动态从 PyPI 获取最新的 graphiti-core 版本，以确保 MCP 服务器使用最新的库版本构建 .github/workflows/release-mcp-server.yml:95-105。

发布工作流数据流

flowchart LR
    "GitTag[Git 标签 vX.Y.Z]" --> "PyPI_Workflow[release-graphiti-core.yml]"
    "PyPI_Workflow" --> "PyPI_Index[(PyPI: graphiti-core)]"

    "PyPI_Index" -- "成功时触发" --> "Server_Workflow[release-server-container.yml]"
    "Server_Workflow" --> "DockerHub_Server[(DockerHub: zepai/graphiti)]"

    "MCP_Tag[Git 标签 mcp-vA.B.C]" --> "MCP_Workflow[release-mcp-server.yml]"
    "PyPI_Index" -- "获取版本" --> "MCP_Workflow"
    "MCP_Workflow" --> "DockerHub_MCP[(DockerHub: zepai/knowledge-graph-mcp)]"

来源：.github/workflows/release-graphiti-core.yml:5, 37, .github/workflows/release-server-container.yml:4-6, 16, .github/workflows/release-mcp-server.yml:5, 15, 95