actions/README.zh-CN.md

English | 简体中文

🚀 Ultralytics Actions

欢迎使用 Ultralytics Actions - 这是一组 GitHub Actions，用于在 Ultralytics 项目中自动化代码质量、PR 管理和 CI/CD 工作流。

📦 仓库内容

本仓库提供三个主要组成部分：

1. Ultralytics Actions - 用于 AI 代码格式化、PR 摘要和自动标签的主 GitHub Action
2. 独立 Actions - 可在常见 CI/CD 任务中复用的 composite actions
3. Python 包 - 可编程使用的 ultralytics-actions 包

Ultralytics Actions 主 Action

面向 Python、JavaScript/TypeScript、Swift、Dart 和网页/文档文件的 AI 驱动格式化、标签和 PR 摘要工具。

📄 功能

• Python 代码： 使用极快的 Python linter 和 formatter Ruff 格式化
• Python Docstrings： 使用 Ultralytics Python docstring formatter 强制 Google 风格格式（可选）
• JavaScript/TypeScript： 使用极快的 JS、TS、JSX、TSX 和 JSON formatter Biome 格式化（可选，通过 biome.json 或 biome.jsonc 自动检测）
• Web 和文档文件： 使用 Prettier 格式化 JS、TS、CSS、HTML、JSON、YAML、Markdown 和 shell 脚本
• Swift 代码： 使用 swift-format 格式化（需要 macos-latest runner）
• Dart 代码： 使用 dart format 格式化 Dart 和 Flutter 项目
• 拼写检查： 使用 codespell 捕获常见拼写错误
• 断链检查： 使用 Lychee 识别无效链接
• PR 摘要： 使用 AI 生成简洁的 Pull Request 摘要
• PR Review： AI 代码审查可识别关键 bug、安全问题和质量问题，并给出修复建议
• 自动标签： 使用 AI 为 issues、PRs 和 discussions 应用相关标签

🤖 支持的 AI 提供商

可选择 OpenAI 或 Anthropic 启用 AI 功能：

提供商	默认模型	API Key
OpenAI	gpt-5.6-luna	openai_api_key
Anthropic	claude-sonnet-4-6	anthropic_api_key

模型会根据提供的 API key 自动检测。可通过 model 输入覆盖默认模型，也可使用 review_model 仅覆盖 PR review 模型。

🛠️ 工作方式

通过 GitHub 事件触发并简化工作流：

• Pull Requests： 确保格式标准、生成摘要、提供 AI review，并应用标签
• Issues： 使用 AI 自动应用相关标签
• Discussions： 使用 AI 自动应用相关标签

🔧 设置

创建 .github/workflows/ultralytics-actions.yml：

# Ultralytics 🚀 AGPL-3.0 License - https://ultralytics.com/license

# Ultralytics Actions https://github.com/ultralytics/actions
# This workflow formats code and documentation in PRs to Ultralytics standards

name: Ultralytics Actions

on:
  issues:
    types: [opened]
  discussion:
    types: [created]
  pull_request:
    branches: [main]
    types: [opened, closed, synchronize, review_requested]

permissions:
  contents: write # Modify code in PRs
  pull-requests: write # Add comments and labels to PRs
  issues: write # Add comments and labels to issues
  discussions: write # Add labels to discussions

jobs:
  actions:
    runs-on: ubuntu-latest
    steps:
      - name: Run Ultralytics Actions
        uses: ultralytics/actions@main
        with:
          token: ${{ secrets.GITHUB_TOKEN }} # Auto-generated token
          labels: true # Auto-label issues/PRs using AI
          python: true # Format Python with Ruff
          # python-version: "3.14" # Optional: set up a specific Python version (default: runner Python)
          python_docstrings: true # Format Python docstrings (default: true)
          biome: true # Format JS/TS with Biome (auto-detected via biome.json or biome.jsonc)
          prettier: true # Format YAML, JSON, Markdown, CSS
          swift: false # Format Swift (requires macos-latest)
          dart: false # Format Dart/Flutter
          spelling: true # Check spelling with codespell
          links: true # Check broken links with Lychee
          summary: true # Generate AI-powered PR summaries
          # AI API keys - provide OpenAI OR Anthropic (model auto-detected from key)
          openai_api_key: ${{ secrets.OPENAI_API_KEY }}
          # anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # model: gpt-5.6-luna  # Optional: set model explicitly
          # review_model: claude-opus-4-7  # Optional: override PR review model
          brave_api_key: ${{ secrets.BRAVE_API_KEY }} # Used for broken link resolution

独立 Actions

这些可复用 composite actions 可在工作流中独立使用。

1. Retry Action

使用指数退避和 jitter 重试失败命令。

- uses: ultralytics/actions/retry@main
  with:
    run: npm install
    retries: 3
    timeout_minutes: 5

📖 完整文档 →

2. Cleanup Disk Action

通过删除不必要的软件包和文件释放 GitHub runners 的磁盘空间。

- uses: ultralytics/actions/cleanup-disk@main

📖 完整文档 →

3. GitHub Report Action

汇总组织仓库中的 open PR 以及默认分支上失败的 GitHub Actions。

- uses: ultralytics/actions/github-report@main
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    org: ultralytics # Optional: defaults to ultralytics
    visibility: all # Optional: public, private, internal, all, or comma-separated
    auto_merge_actions_prs: true # Optional: auto-merge eligible GitHub Actions update PRs

📖 完整文档 →

4. Dependabot Action

使用缓存的 release 解析，批量更新组织仓库中的 GitHub Actions 版本。

- uses: ultralytics/actions/dependabot@main
  with:
    token: ${{ secrets.GITHUB_TOKEN }}

📖 完整文档 →

Python 包

在 Python>=3.8 环境中安装 ultralytics-actions 包及其全部依赖项，以便通过代码使用 action 工具。

uv pip install ultralytics-actions

可用模块：

• actions.review_pr - AI 驱动的 PR review
• actions.summarize_pr - 生成 PR 摘要
• actions.github_report - 生成 GitHub 组织报告
• actions.first_interaction - 为新贡献者生成欢迎消息
• 更多模块见 actions/ 目录

💡 贡献

Ultralytics 依靠社区协作不断发展，我们非常重视您的贡献！请查看贡献指南了解如何参与。也欢迎通过我们的调查问卷分享反馈。衷心感谢 🙏 每一位贡献者！

📄 许可证

Ultralytics 提供两种许可选项：

• AGPL-3.0 许可证： 经 OSI 批准的开源许可证，适合重视开放协作的学生、研究人员和爱好者。详情请参阅 LICENSE 文件。
• 企业许可证： 面向商业用途，可将 Ultralytics 软件和 AI 模型集成到商业产品中，而不受 AGPL-3.0 开源要求限制。如需企业方案，请联系 Ultralytics Licensing。

📫 联系

如需报告 Ultralytics Actions 相关 bug 或提出功能建议，请通过 GitHub Issues 提交。欢迎加入我们的 Discord 社区参与讨论并获取支持！