11.5 · 代码质量与 Pre-commit Hooks（Code Quality and Pre-commit Hooks）

代码质量与 Pre-commit Hooks

代码质量与预提交钩子

相关源文件

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

• .github/workflows/nightly-external-dependency-unit-tests.yml
• .pre-commit-config.yaml
• backend/onyx/llm/litellm_singleton/monkey_patches.py
• backend/pytest.ini
• backend/requirements/README.md
• backend/requirements/default.txt
• backend/requirements/dev.txt
• backend/requirements/ee.txt
• backend/requirements/model_server.txt
• backend/tests/external_dependency_unit/conftest.py
• backend/tests/external_dependency_unit/file_store/test_file_store_non_mocked.py
• backend/tests/external_dependency_unit/llm/test_ollama_streaming.py
• backend/tests/external_dependency_unit/llm/test_openai_responses_api.py
• backend/tests/unit/onyx/llm/test_factory.py
• backend/tests/unit/onyx/llm/test_litellm_monkey_patches.py
• pyproject.toml
• uv.lock
• [web/src/app/admin/connector/[ccPairId]/InlineFileManagement.tsx](web/src/app/admin/connector/[ccPairId]/InlineFileManagement.tsx)
• web/src/lib/hooks.ts

本文档记录了在代码提交到仓库之前运行的代码质量工具和自动化检查。这些工具用于强制执行一致的格式规范、捕获类型错误、校验依赖关系，并防止常见问题进入代码库。

范围：本文涵盖预提交钩子、代码检查工具、类型检查和自动化质量门禁。有关测试基础设施和持续集成/持续部署（CI/CD）工作流，请参阅 11.4 测试基础设施。有关依赖安装和环境设置，请参阅 11.1 开发环境设置。

预提交钩子架构

Onyx 代码库使用 pre-commit 自动对暂存文件运行质量检查。该系统配置为在多个 Git 生命周期事件上运行钩子：pre-commit、post-checkout、post-merge 和 post-rewrite /.pre-commit-config.yaml:1-6。

钩子执行管线

下图将代码质量的自然语言需求映射到配置中定义的特定代码实体（钩子和脚本）。

图表：质量钩子映射

来源：/.pre-commit-config.yaml:1-166

使用 uv 进行依赖管理

代码库使用 uv 作为高性能 Python 依赖管理器。pyproject.toml 是真相来源，它生成统一的 uv.lock 文件 pyproject.toml:193-194。

自动化需求生成

为了与使用标准 pip 或 uv pip 的 Docker 构建保持兼容，系统通过预提交钩子自动将 uv.lock 导出为多个 requirements/*.txt 文件。每当 pyproject.toml 或 uv.lock 发生更改时，这些钩子就会触发 /.pre-commit-config.yaml:24,36,48,60。

图表：依赖数据流

pyproject.toml 中的依赖类别

依赖项被分段管理，以最小化不同服务的占用空间。

来源：pyproject.toml:1-216、/.pre-commit-config.yaml:7-60、backend/requirements/default.txt:1-2

Python 代码质量工具

Black（格式化工具）

代码库使用 black 进行标准化的 Python 格式化。它通过预提交中的 uv-run 钩子执行 /.pre-commit-config.yaml:78-83。特定版本 26.3.1 在开发依赖组中被固定 pyproject.toml:140。

Ruff（代码检查与修复工具）

ruff 提供高性能的代码检查和自动修复。它配置为在预提交期间使用 --fix 标志运行，以自动解决琐碎问题 /.pre-commit-config.yaml:72-77。Ruff 配置包括自定义的 line-length（130）和特定的代码检查规则 pyproject.toml:227-241。

Onyx 开发者脚本（ods）集成

ods 工具通过 uv-run 集成到预提交中。它执行 ods check-lazy-imports 以确保后端模块遵循延迟导入模式，防止在启动期间加载不必要的重型包 /.pre-commit-config.yaml:61-65。

LiteLLM 猴子补丁

为了维护运行时代码质量并修复上游问题，系统对 LiteLLM 应用了多个猴子补丁。这些补丁解决了 Ollama 流式推理内容、Azure Responses API 假流式传输和 Pydantic 序列化警告等问题 backend/onyx/llm/litellm_singleton/monkey_patches.py:1-58。

来源：/.pre-commit-config.yaml:61-83、pyproject.toml:140, 160、backend/onyx/llm/litellm_singleton/monkey_patches.py:8-58

类型检查与性能

Python 类型安全（ty）

项目使用 ty（通过 uv-run ty check）作为 Python 类型验证的预提交钩子 /.pre-commit-config.yaml:66-71。pyproject.toml 中的 ty 配置以 backend 目录为目标，使用 Python 3.11，并将违规视为错误 pyproject.toml:218-235。

TypeScript 检查（tsgo）

对于 Next.js 前端，钩子 typescript-check 使用 tsgo（TypeScript 的原生 Go 编译器）进行类型检查，速度比标准 tsc 快约 10 倍 /.pre-commit-config.yaml:160-166。它使用 tsconfig.types.json 验证 web/ 目录 /.pre-commit-config.yaml:162。

来源：pyproject.toml:218-235、/.pre-commit-config.yaml:66-71, 160-166

基础设施与安全

密钥预防（RipSecrets）

ripsecrets 用于扫描意外的凭证泄露。它包含一个针对 OpenAI 风格密钥的特定附加模式：^sk-[A-Za-z0-9_\-]{20,}$，并在严格忽略模式下运行 /.pre-commit-config.yaml:122-130。

基础设施校验

• ActionLint：校验 GitHub Actions 工作流文件的语法和安全性 /.pre-commit-config.yaml:92-95。
• ShellCheck：校验 Shell 脚本，排除特定的部署和模板脚本 /.pre-commit-config.yaml:97-106。
• GolangCI-Lint：校验仓库中的 Go 代码，特别是针对 ods 等工具 /.pre-commit-config.yaml:108-113。
• Terraform Fmt：运行 terraform fmt -recursive 以确保基础设施即代码（IaC）格式的一致性 /.pre-commit-config.yaml:133-138。

前端生命周期钩子

预提交还管理前端包的一致性：

• npm-install：在检出或合并后自动在 web/ 目录中运行 npm install --no-save，以保持 node_modules 同步 /.pre-commit-config.yaml:140-147。
• npm-install-check：验证每当 package.json 更改时，web/package-lock.json 是否已更新 /.pre-commit-config.yaml:148-155。

来源：/.pre-commit-config.yaml:92-155