11.6 · AI 编码智能体技能（AI Coding Agent Skills）

AI 编码智能体技能

AI 编码代理技能

相关源文件

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

• .agents/skills/component-refactoring/SKILL.md
• .agents/skills/frontend-testing/SKILL.md
• .agents/skills/frontend-testing/references/checklist.md
• .agents/skills/frontend-testing/references/mocking.md
• .devcontainer/README.md
• .github/CODE_OF_CONDUCT.md
• .github/dependabot.yml
• .github/pull_request_template.md
• .github/workflows/deploy-agent-dev.yml
• .github/workflows/deploy-dev.yml
• .github/workflows/deploy-hitl.yml
• .github/workflows/labeler.yml
• .github/workflows/stale.yml
• .vite-hooks/pre-commit
• .vscode/README.md
• AGENTS.md
• CLAUDE.md
• CONTRIBUTING.md
• e2e/package.json
• packages/dify-ui/src/scroll-area/index.stories.tsx
• packages/dify-ui/tsconfig.json
• packages/migrate-no-unchecked-indexed-access/package.json
• packages/migrate-no-unchecked-indexed-access/src/no-unchecked-indexed-access/run.ts
• sdks/nodejs-client/package.json
• web/AGENTS.md
• web/README.md
• web/docs/lint.md
• web/docs/test.md
• web/scripts/analyze-component.js
• web/service/fetch.spec.ts

本文概述了 Dify 仓库中 AI 编码代理所使用的技能和模式。这些代理旨在协助完成各种开发任务，包括代码评审、重构、测试以及维护代码质量。代理交互的主要机制是通过 GitHub Actions 工作流，这些工作流会在拉取请求上触发自动化检查、修复和反馈。

代理交互模式

Dify 仓库中的 AI 代理主要通过 GitHub Actions 以及在 AGENTS.md 和 CLAUDE.md 文件中定义的特殊指令与代码库和开发流程进行交互。它们被配置为响应特定事件并执行预定义任务。

工作流触发

代理通常由以下事件触发：

• pull_request 事件：用于对提议的变更执行代码评审、样式检查和测试执行等任务。
• push 事件：用于 main 分支上的持续集成任务，例如构建和推送 Docker 镜像或运行自动修复。
• workflow_run：用于在构建成功后串联部署，例如 Deploy Dev 和 Deploy HITL 工作流 .github/workflows/deploy-dev.yml:4-9；.github/workflows/deploy-hitl.yml:4-9。
• workflow_dispatch：允许手动触发工作流以执行维护任务。

语言风格与开发指南

代理被指示遵循特定的项目约定：

• Python：后端架构遵循领域驱动设计（DDD）和整洁架构原则 AGENTS.md:43-43。代理必须在函数上保留类型提示，优先使用 TypedDict 而非 dict 以保证类型安全，并实现相关的特殊方法，如 __repr__ AGENTS.md:32-33。
• TypeScript：使用严格配置，避免使用 any 类型，并依赖 ESLint（pnpm lint:fix）和 pnpm type-check AGENTS.md:34-34。面向用户的字符串必须使用 web/i18n/en-US/ 中的国际化文件，而非硬编码文本 AGENTS.md:46-46。

代理选择加入与归属

对于进行贡献的自动化代理，有一个特定的约定：在拉取请求模板的描述末尾添加 From <工具名称> 作为最后一行 .github/pull_request_template.md:10-10。

图表：自然语言到代码实体映射（后端）

此图表将 AGENTS.md 中的自然语言需求映射到后端中使用的特定代码实体和工具。

来源： AGENTS.md:9-9 AGENTS.md:17-17 AGENTS.md:33-33 AGENTS.md:43-44

后端代码评审技能

AI 代理通过执行编码标准、类型一致性以及通过静态分析和自动化测试识别潜在问题，为后端代码评审做出贡献。

Python 样式与代码检查

后端使用多种工具进行质量保证：

• Ruff：用于格式化 Python 代码和进行代码检查。在提交拉取请求之前，需要运行 make lint 命令 .github/pull_request_template.md:24-24。
• 类型检查：通过 mypy 或 basedpyright 强制执行强类型。代理应避免使用 Any，并优先使用显式类型标注 AGENTS.md:28-28。
• 测试：代理遵循测试驱动开发（TDD）原则（红 → 绿 → 重构），并使用带有 Arrange-Act-Assert 结构的 pytest AGENTS.md:26-27。

依赖管理

该项目使用 uv 进行 Python 包管理。Dependabot 被配置为每周更新这些依赖 .github/dependabot.yml:4-8。

图表：后端质量门禁

来源： .github/pull_request_template.md:24-24 AGENTS.md:26-28 .github/dependabot.yml:4-8

前端代码评审技能

前端代码评审代理专注于 TypeScript 样式、类型检查和 UI 一致性。

Web 样式与代码检查

前端使用健壮的代码检查管线：

• ESLint：强制执行 JavaScript/TypeScript 编码标准。工作流使用 --cache 以提高性能，并使用 --concurrency=auto 进行多线程代码检查 web/docs/lint.md:15-19。
• TSSLint：用于类型感知的代码检查（例如 no-leaked-conditional-rendering），通过 pnpm lint:tss 执行 web/docs/lint.md:50-55。
• 类型检查：由 tsgo（原生 TypeScript 7 编译器）驱动，其速度显著快于标准 tsc web/docs/lint.md:71-83。

自动修复工作流

为简化开发流程，项目使用自动修复工作流。一个提交钩子会运行 vp staged，该命令在提交继续之前对暂存文件应用可自动修复的 ESLint 更改 web/docs/lint.md:40-42。

图表：自然语言到代码实体映射（前端）

此图表将前端设计和质量需求映射到特定的代码实现。

来源： web/AGENTS.md:6-15 web/docs/lint.md:83-83

组件重构技能

AI 代理通过自动化常见的代码转换并确保整个单体仓库的一致性来协助重构。

依赖注入与整洁架构

代理被训练通过构造函数注入依赖，并保持整洁架构的边界 AGENTS.md:39-39。它们使用领域特定的异常在正确的层级处理错误，而非使用通用的 try-except 块 AGENTS.md:40-40。

覆盖层迁移

前端重构的一个强制性约束是使用来自 @langgenius/dify-ui 的覆盖层原语。代理被指示在接触相关代码时，将现有调用者从 @/app/components/base/* 迁移出去 web/AGENTS.md:9-10。

自动化现代化

仓库包含用于现代化的专用包，例如 packages/migrate-no-unchecked-indexed-access，它提供了一个运行器来自动化迁移 TypeScript 代码以使用更严格的索引访问检查 packages/migrate-no-unchecked-indexed-access/src/no-unchecked-indexed-access/run.ts:1-10。

来源： AGENTS.md:39-40 web/AGENTS.md:5-11 packages/migrate-no-unchecked-indexed-access/package.json:1-5

前端测试技能

Dify 前端非常重视组件测试和集成测试。

测试指南

所有 React 组件都必须有全面的测试覆盖。规范指南在 web/docs/test.md 中描述 CONTRIBUTING.md:80-80。代理应：

• 为每个引入的变更添加测试 .github/pull_request_template.md:22-22。
• 在编写测试之前，使用 pnpm analyze-component 分析组件复杂度 web/README.md:148-149。
• 使用 Vitest 和 React Testing Library 进行单元测试 web/README.md:117-117。

测试基础设施

• Vitest：主要的测试运行器，通过 vp test 执行 web/README.md:129-130。
• Storybook：用于 UI 组件开发和隔离 web/README.md:99-101。
• 复杂度分析：web/scripts/analyze-component.js 中的脚本有助于根据组件逻辑密度确定适当的测试策略。

来源： CONTRIBUTING.md:79-81 web/README.md:99-149 web/AGENTS.md:16-21

查询/变更模式

代码库使用特定的数据获取和状态管理模式，代理必须遵守这些模式。

前端数据模式

• Vite+ (vp)：前端使用 vinext 和 Vite+ 以获得优化的开发体验，提供 vp install 和 vp test 等命令 web/README.md:14-15。
• Next.js：Web 应用的核心框架 web/README.md:3-3。

后端数据模式

• Celery：用于处理后台任务，使用 Redis 作为消息代理 AGENTS.md:45-45。
• 领域驱动设计：后端 API 按领域层组织，以将业务逻辑与基础设施隔离 AGENTS.md:9-9。

图表：系统数据流

来源：

• AGENTS.md:9-12
• AGENTS.md:43-45
• web/README.md:3-3