agentic_huge_data_base / wiki
页面 Dify · 11.5 Automated Fixes 与代码 Modernization·DeepWiki 中文全文译文
DeepWiki 中文译文 / Dify / 11.5

11.5 · Automated Fixes 与代码 Modernization（Automated Fixes and Code Modernization）

应用编排与外部知识接入 · 本章是 Dify DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Dify 章节11.5 状态全文译文 模块安装与启动、测试、发布与运维、文档对象与元数据、工作流与编排
项目要点页2.5 参考项目 项目章节目录Dify DeepWiki 原始章节Automated Fixes and Code Modernization 上一章11.4 下一章11.6
源码线索
  • .github/labeler.yml
  • .github/workflows/api-tests.yml
  • .github/workflows/autofix.yml
  • .github/workflows/build-push.yml
  • .github/workflows/db-migration-test.yml
  • .github/workflows/docker-build.yml
  • .github/workflows/main-ci.yml
  • .github/workflows/pyrefly-diff-comment.yml
  • .github/workflows/pyrefly-diff.yml
  • .github/workflows/style.yml
模块标签
  • 安装与启动
  • 测试、发布与运维
  • 文档对象与元数据
  • 工作流与编排
  • 界面与交互

中文译文

Automated Fixes 与代码 Modernization（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/langgenius/dify/11.5-automated-fixes-and-code-modernization
翻译时间：2026-05-27T08:44:25.915Z
翻译模型：deepseek-chat
原文字符数：11625
项目：Dify (dify)

---

自动修复与代码现代化

相关源文件

以下文件被用作生成此维基页面的上下文：

  • .github/labeler.yml
  • .github/workflows/api-tests.yml
  • .github/workflows/autofix.yml
  • .github/workflows/build-push.yml
  • .github/workflows/db-migration-test.yml
  • .github/workflows/docker-build.yml
  • .github/workflows/main-ci.yml
  • .github/workflows/pyrefly-diff-comment.yml
  • .github/workflows/pyrefly-diff.yml
  • .github/workflows/style.yml
  • .github/workflows/tool-test-sdks.yaml
  • .github/workflows/translate-i18n-claude.yml
  • .github/workflows/trigger-i18n-sync.yml
  • .github/workflows/vdb-tests-full.yml
  • .github/workflows/vdb-tests.yml
  • .github/workflows/web-tests.yml
  • depot.json

目的与范围

本文档记录了自动修复管线，该管线会自动纠正代码质量问题、应用格式化，并执行渐进式的代码现代化。自动修复工作流会在每次拉取请求和推送到 main 分支时运行，并将修复结果直接提交回该分支。关于代码质量强制检查和代码风格规则，请参见代码质量与代码风格。关于持续集成/持续部署（CI/CD）架构，请参见持续集成（CI）管线架构。

自动修复系统实现在 .github/workflows/autofix.yml 中，执行以下操作：

  • Docker Compose 生成：从模板重新生成 docker-compose.yaml .github/workflows/autofix.yml:62-66
  • Python 格式化和代码风格检查：使用 Ruff 进行代码风格和代码风格修复 .github/workflows/autofix.yml:68-78
  • 结构性代码转换：使用 ast-grep 进行 SQLAlchemy 2.0 迁移 .github/workflows/autofix.yml:85-92
  • 类型注解现代化：将 Optional[T] 转换为 T | None .github/workflows/autofix.yml:93-110
  • API 文档：自动生成 Swagger Markdown 文档和前端合约 .github/workflows/autofix.yml:119-127
  • Web 代码风格修复：使用 ESLint 自动修复 TypeScript/JavaScript 代码 .github/workflows/autofix.yml:129-133

来源：.github/workflows/autofix.yml:1-136

---

自动修复工作流架构

自动修复工作流执行一个顺序的转换管线，并将所有更改提交回拉取请求分支。

完整自动修复管线
graph TB
    Trigger["`**触发事件**
    针对 main 分支创建/更新拉取请求
    推送到 main 分支`"]

    RepoCheck{"`仓库检查
    github.repository ==
    'langgenius/dify'?`"}

    Checkout["`actions/checkout@v6
    检出拉取请求分支`"]

    subgraph DockerCompose["`**Docker Compose 生成**`"]
        CheckDocker["`tj-actions/changed-files@v47
        文件: docker/generate_docker_compose
        docker/.env.example
        docker/docker-compose-template.yaml`"]

        GenDocker["`./docker/generate_docker_compose
        重新生成 docker-compose.yaml`"]
    end

    subgraph PythonFixes["`**Python 格式化和修复**`"]
        SetupUV["`astral-sh/setup-uv@v8
        安装 UV 包管理器`"]

        UVSync["`uv sync --dev
        安装依赖`"]

        RuffFormat1["`uv run ruff format ..
        第一遍: 格式化代码`"]

        RuffCheck["`uv run ruff check --fix .
        修复代码风格错误`"]

        RuffFormat2["`uv run ruff format ..
        第二遍: 重新格式化`"]
    end

    subgraph CodeModernization["`**代码现代化**`"]
        CountProgress["`./api/cnt_base.sh
        统计迁移进度`"]

        AstGrep1["`ast-grep:
        filter() → where()`"]

        AstGrep2["`ast-grep:
        Column() → mapped_column()`"]

        AstGrep3["`ast-grep:
        Optional[T] → T | None`"]

        SedFix["`sed: 修复前向引用
        'Type' | None → Optional['Type']`"]
    end

    subgraph ContractsDocs["`**文档与合约**`"]
        GenSwagger["`uv run generate_swagger_markdown_docs.py
        更新 API 文档`"]
        GenContracts["`pnpm gen-api-contract-from-openapi
        更新前端类型`"]
    end

    subgraph WebFixes["`**Web 修复**`"]
        SetupWebEnv["`./.github/actions/setup-web
        设置 Web 环境`"]
        WebLintFix["`vp exec eslint
        ESLint 自动修复`"]
    end

    Commit["`autofix-ci/action
    提交并推送所有更改`"]

    Trigger --> RepoCheck
    RepoCheck -->|是| Checkout
    RepoCheck -->|否| Skip[跳过自动修复]

    Checkout --> CheckDocker
    CheckDocker -->|"已更改"| GenDocker
    CheckDocker -->|"未更改"| PythonFixes
    GenDocker --> PythonFixes

    PythonFixes --> CountProgress
    CountProgress --> AstGrep1
    AstGrep1 --> AstGrep2
    AstGrep2 --> AstGrep3
    AstGrep3 --> SedFix
    SedFix --> ContractsDocs

    ContractsDocs --> WebFixes
    WebFixes --> Commit

工作流触发器：自动修复工作流由针对 main 分支的拉取请求、推送到 main 分支以及合并组检查触发 .github/workflows/autofix.yml:2-9。

仓库限制：该工作流仅在官方 langgenius/dify 仓库上运行，以防止分支出现提交循环 .github/workflows/autofix.yml:15。

来源：.github/workflows/autofix.yml:1-136

---

Docker Compose 生成

当模板文件发生更改时，工作流会重新生成 docker-compose.yaml，以确保模板与用于本地部署的生成文件之间的一致性。

Docker Compose 生成逻辑

生成步骤使用基于路径的过滤来检测更改 .github/workflows/autofix.yml:25-34：

输入文件作用
docker/generate_docker_compose生成脚本本身 .github/workflows/autofix.yml:31
docker/.env.example环境变量默认值的来源 .github/workflows/autofix.yml:32
docker/docker-compose-template.yaml用于生成的基础模板 .github/workflows/autofix.yml:33
docker/docker-compose.yaml生成的输出文件 .github/workflows/autofix.yml:34

如果这些文件中的任何一个发生了更改，脚本会在 docker 目录内运行 ./generate_docker_compose 来重新生成 Compose 文件 .github/workflows/autofix.yml:63-66。

来源：.github/workflows/autofix.yml:25-66

---

Ruff：Python 格式化与自动修复

Ruff 用于快速的 Python 代码风格检查和格式化。自动修复工作流通过三阶段管线运行 Ruff，以确保代码完全一致。

三阶段 Ruff 管线
graph LR
    Setup["`**设置**
    uv sync --dev
    安装依赖`"]

    Stage1["`**阶段 1: 格式化**
    uv run ruff format ..
    初始格式化`"]

    Stage2["`**阶段 2: 代码风格检查 + 修复**
    uv run ruff check --fix .
    应用自动修复`"]

    Stage3["`**阶段 3: 重新格式化**
    uv run ruff format ..
    最终格式化`"]

    Code["`api/ 目录下的 Python 代码
    (所有 *.py 文件)`"] --> Setup
    Setup --> Stage1
    Stage1 --> Stage2
    Stage2 --> Stage3
    Stage3 --> Fixed["`自动修复后的代码
    准备提交`"]

阶段 1：初始格式化 .github/workflows/autofix.yml:73：首先应用代码格式化，以防止"行过长"错误干扰代码风格检查。

阶段 2：代码风格检查与修复 .github/workflows/autofix.yml:75：运行配置好的 Ruff 代码风格检查规则，并自动修复诸如未使用的导入或冗余代码等问题。

阶段 3：重新格式化 .github/workflows/autofix.yml:77：在代码风格修复后重新应用格式化，因为自动修复可能会引入格式不一致的问题。

来源：.github/workflows/autofix.yml:68-78

---

AST-grep：结构性代码转换

ast-grep 是一种结构性搜索和替换工具，用于 SQLAlchemy 2.0 迁移和类型现代化。

SQLAlchemy 2.0 迁移

Dify 正在使用基于抽象语法树（AST）的转换，逐步自动迁移遗留模式 .github/workflows/autofix.yml:89-92。

遗留模式现代模式逻辑
db.session.query($W).filter($H)db.session.query($W).where($H)查询过滤器的结构性转换 .github/workflows/autofix.yml:89-90
db.Column($$$B)mapped_column($$$B)转换为 SQLAlchemy 2.0 声明式 API .github/workflows/autofix.yml:91-92
类型注解现代化

工作流使用自定义的 ast-grep 规则，将 Optional[T] 转换为现代的 T | None 语法 .github/workflows/autofix.yml:94-110。

前向引用修复：由于 Python 不支持使用字符串字面量前向引用的联合语法（例如，"Type" | None 是无效的），后处理 sed 命令将这些特定情况恢复为 Optional["Type"] .github/workflows/autofix.yml:112-113。

来源：.github/workflows/autofix.yml:85-114

---

Web 与文档修复

API 文档与前端合约

当 API 发生更改时，工作流会自动更新文档和类型定义：

  • Swagger 文档：执行 api/dev/generate_swagger_markdown_docs.py，使 Markdown 文档与 OpenAPI 规范保持同步 .github/workflows/autofix.yml:123。
  • 前端合约：在 packages/contracts 目录中运行 gen-api-contract-from-openapi，更新 Web 前端使用的 TypeScript 定义 .github/workflows/autofix.yml:127。
ESLint 自动修复

对于 Web 相关的更改，工作流会使用 --fix 标志执行 ESLint，以解决 web 目录中的代码风格违规问题 .github/workflows/autofix.yml:132。此步骤使用 setup-web 操作来准备环境 .github/workflows/autofix.yml:117。

迁移进度跟踪

工作流通过执行 api/cnt_base.sh 来跟踪 SQLAlchemy 迁移的进度 .github/workflows/autofix.yml:83。此脚本提供有关代码库中遗留模式数量的指标。

来源：.github/workflows/autofix.yml:79-84, .github/workflows/autofix.yml:115-133

---

自动修复提交机制

所有转换结果都会使用 autofix-ci/action 自动提交回拉取请求分支。

提交流程
graph LR
    AutofixSteps["`**自动修复步骤**
    Docker 生成
    Ruff 格式化/代码风格检查
    ast-grep 转换
    文档/合约生成
    ESLint 自动修复`"]

    DetectChanges["`**autofix-ci/action**
    git status
    检测已更改的文件`"]

    CreateCommit["`**创建提交**
    作者: github-actions[bot]
    消息: 'autofix: apply
    automated fixes'`"]

    PushBranch["`**推送到分支**
    git push origin <PR-branch>`"]

    AutofixSteps --> DetectChanges
    DetectChanges -->|"发现更改"| CreateCommit
    CreateCommit --> PushBranch

操作集成：autofix-ci/action@v1.3.4 负责检测本地更改并将其推送回 GitHub 分支的逻辑 .github/workflows/autofix.yml:135。

来源：.github/workflows/autofix.yml:135-136