Skip to content

自动化和分类流程

¥Automation and Triage Processes

本文档详细介绍了我们用于管理和分类问题及拉取请求的自动化流程。我们的目标是提供及时的反馈，并确保贡献得到高效的审核和集成。了解这些自动化流程将帮助您作为贡献者了解预期内容以及如何与我们的仓库机器人进行最佳交互。

¥This document provides a detailed overview of the automated processes we use to manage and triage issues and pull requests. Our goal is to provide prompt feedback and ensure that contributions are reviewed and integrated efficiently. Understanding this automation will help you as a contributor know what to expect and how to best interact with our repository bots.

指导原则：问题和拉取请求

¥Guiding Principle: Issues and Pull Requests

首先，几乎每个拉取请求 (PR) 都应该链接到一个对应的问题 (Issue)。问题描述了“是什么”和“为什么”（错误或功能），而 PR 则描述了“如何”（实现）。这种分离有助于我们跟踪工作、确定功能的优先级，并维护清晰的历史背景。我们的自动化正是围绕这一原则构建的。

¥First and foremost, almost every Pull Request (PR) should be linked to a corresponding Issue. The issue describes the "what" and the "why" (the bug or feature), while the PR is the "how" (the implementation). This separation helps us track work, prioritize features, and maintain clear historical context. Our automation is built around this principle.

详细的自动化工作流程

¥Detailed Automation Workflows

以下是我们存储库中运行的具体自动化工作流程的细分。

¥Here is a breakdown of the specific automation workflows that run in our repository.

1. 当你打开一个问题时：Automated Issue Triage

¥1. When you open an Issue: Automated Issue Triage

这是您创建问题后与之交互的第一个机器人。它的任务是进行初步分析并应用正确的标签。

¥This is the first bot you will interact with when you create an issue. Its job is to perform an initial analysis and apply the correct labels.

  • 工作流文件：.github/workflows/gemini-automated-issue-triage.yml

    ¥Workflow File: .github/workflows/gemini-automated-issue-triage.yml

  • 当它运行时：问题创建或重新打开后立即发生。

    ¥When it runs: Immediately after an issue is created or reopened.

  • 它的作用：

    ¥What it does:

  • 它使用 Gemini 模型根据一组详细的指南来分析问题的标题和正文。

    ¥It uses a Gemini model to analyze the issue's title and body against a detailed set of guidelines.

  • 适用一个area/*标签：将问题分类到项目的功能区域（例如，area/ux，area/models，area/platform）。

    ¥Applies one area/* label: Categorizes the issue into a functional area of the project (e.g., area/ux, area/models, area/platform).

  • 适用一个kind/*标签：识别问题的类型（例如，kind/bug，kind/enhancement，kind/question）。

    ¥Applies one kind/* label: Identifies the type of issue (e.g., kind/bug, kind/enhancement, kind/question).

  • 适用一个priority/*标签：根据所述影响分配从 P0（严重）到 P3（低）的优先级。

    ¥Applies one priority/* label: Assigns a priority from P0 (critical) to P3 (low) based on the described impact.

  • 可能适用status/need-information：如果问题缺少关键细节（如日志或重现步骤），则会被标记以获取更多信息。

    ¥May apply status/need-information: If the issue lacks critical details (like logs or reproduction steps), it will be flagged for more information.

  • 可能适用status/need-retesting：如果问题引用的 CLI 版本超过六个旧版本，则会将其标记为在当前版本上重新测试。

    ¥May apply status/need-retesting: If the issue references a CLI version that is more than six versions old, it will be flagged for retesting on a current version.

  • 你应该做什么：

    ¥What you should do:

  • 尽可能完整地填写问题模板。提供的细节越多，分类就越准确。

    ¥Fill out the issue template as completely as possible. The more detail you provide, the more accurate the triage will be.

  • 如果status/need-information标签已添加，请在评论中提供所需的详细信息。

    ¥If the status/need-information label is added, please provide the requested details in a comment.

2. 当你打开 Pull Request 时：Continuous Integration (CI)

¥2. When you open a Pull Request: Continuous Integration (CI)

此工作流程确保所有更改在合并之前都符合我们的质量标准。

¥This workflow ensures that all changes meet our quality standards before they can be merged.

  • 工作流文件：.github/workflows/ci.yml

    ¥Workflow File: .github/workflows/ci.yml

  • 当它运行时：每次推送拉取请求时。

    ¥When it runs: On every push to a pull request.

  • 它的作用：

    ¥What it does:

  • 皮棉：检查您的代码是否符合我们项目的格式和样式规则。

    ¥Lint: Checks that your code adheres to our project's formatting and style rules.

  • 测试：在 macOS、Windows、Linux 以及多个 Node.js 版本上运行全套自动化测试。这是 CI 流程中最耗时的部分。

    ¥Test: Runs our full suite of automated tests across macOS, Windows, and Linux, and on multiple Node.js versions. This is the most time-consuming part of the CI process.

  • 报道后评论：所有测试成功通过后，机器人会对您的 PR 发表评论。此评论总结了您的更改在测试中的覆盖情况。

    ¥Post Coverage Comment: After all tests have successfully passed, a bot will post a comment on your PR. This comment provides a summary of how well your changes are covered by tests.

  • 你应该做什么：

    ¥What you should do:

  • 确保所有 CI 检查均已通过。所有检查均已通过后，您的提交旁边将出现绿色复选标记 ✅。

    ¥Ensure all CI checks pass. A green checkmark ✅ will appear next to your commit when everything is successful.

  • 如果检查失败（红色“X”❌），请单击失败检查旁边的“详细信息”链接以查看日志、识别问题并推送修复。

    ¥If a check fails (a red "X" ❌), click the "Details" link next to the failed check to view the logs, identify the problem, and push a fix.

3. 持续对 Pull 请求进行分类：PR Auditing and Label Sync

¥3. Ongoing Triage for Pull Requests: PR Auditing and Label Sync

此工作流程定期运行，以确保所有打开的 PR 都正确链接到问题并具有一致的标签。

¥This workflow runs periodically to ensure all open PRs are correctly linked to issues and have consistent labels.

  • 工作流文件：.github/workflows/gemini-scheduled-pr-triage.yml

    ¥Workflow File: .github/workflows/gemini-scheduled-pr-triage.yml

  • 当它运行时：每 15 分钟对所有打开的拉取请求进行一次。

    ¥When it runs: Every 15 minutes on all open pull requests.

  • 它的作用：

    ¥What it does:

  • 检查相关问题：机器人会扫描您的 PR 描述，查找与问题相关的关键字（例如，Fixes #123，Closes #456）。

    ¥Checks for a linked issue: The bot scans your PR description for a keyword that links it to an issue (e.g., Fixes #123, Closes #456).

  • 添加status/need-issue：如果没有找到链接问题，机器人将添加status/need-issue标签到你的 PR。这清楚地表明需要创建并链接一个问题。

    ¥Adds status/need-issue: If no linked issue is found, the bot will add the status/need-issue label to your PR. This is a clear signal that an issue needs to be created and linked.

  • 同步标签：如果出现问题是链接后，机器人会确保 PR 的标签与问题的标签完全匹配。它会添加任何缺失的标签，并删除任何不属于的标签，同时还会删除status/need-issue如果存在则标记。

    ¥Synchronizes labels: If an issue is linked, the bot ensures the PR's labels perfectly match the issue's labels. It will add any missing labels and remove any that don't belong, and it will remove the status/need-issue label if it was present.

  • 你应该做什么：

    ¥What you should do:

  • 始终将您的 PR 与问题联系起来。这是最重要的一步。添加如下代码Resolves #<issue-number>到您的 PR 描述。

    ¥Always link your PR to an issue. This is the most important step. Add a line like Resolves #<issue-number> to your PR description.

  • 这将确保您的 PR 被正确分类并顺利通过审核流程。

    ¥This will ensure your PR is correctly categorized and moves through the review process smoothly.

4. 持续的问题分类：Scheduled Issue Triage

¥4. Ongoing Triage for Issues: Scheduled Issue Triage

这是一个后备工作流程，以确保分类过程不会遗漏任何问题。

¥This is a fallback workflow to ensure that no issue gets missed by the triage process.

  • 工作流文件：.github/workflows/gemini-scheduled-issue-triage.yml

    ¥Workflow File: .github/workflows/gemini-scheduled-issue-triage.yml

  • 当它运行时：每小时讨论所有未解决的问题。

    ¥When it runs: Every hour on all open issues.

  • 它的作用：

    ¥What it does:

  • 它积极寻找那些根本没有标签或仍然具有status/need-triage标签。

    ¥It actively seeks out issues that either have no labels at all or still have the status/need-triage label.

  • 然后，它会触发与初始分类机器人相同的强大的基于 Gemini 的分析，以应用正确的标签。

    ¥It then triggers the same powerful Gemini-based analysis as the initial triage bot to apply the correct labels.

  • 你应该做什么：

    ¥What you should do:

  • 您通常无需执行任何操作。此工作流程就像一道安全网，即使初始分类失败，也能确保每个问题最终都能得到分类。

    ¥You typically don't need to do anything. This workflow is a safety net to ensure every issue is eventually categorized, even if the initial triage fails.

5. 发布自动化

¥5. Release Automation

此工作流程处理 Gemini CLI 新版本的打包和发布过程。

¥This workflow handles the process of packaging and publishing new versions of the Gemini CLI.

  • 工作流文件：.github/workflows/release.yml

    ¥Workflow File: .github/workflows/release.yml

  • 当它运行时：按每日计划发布“夜间”版本，并手动发布官方补丁/次要版本。

    ¥When it runs: On a daily schedule for "nightly" releases, and manually for official patch/minor releases.

  • 它的作用：

    ¥What it does:

  • 自动构建项目、增加版本号并将包发布到 npm。

    ¥Automatically builds the project, bumps the version numbers, and publishes the packages to npm.

  • 使用生成的发行说明在 GitHub 上创建相应的发行版。

    ¥Creates a corresponding release on GitHub with generated release notes.

  • 你应该做什么：

    ¥What you should do:

  • 作为贡献者，您无需为此过程执行任何操作。您可以放心，一旦您的 PR 被合并到main分支，您的更改将包含在下一个夜间版本中。

    ¥As a contributor, you don't need to do anything for this process. You can be confident that once your PR is merged into the main branch, your changes will be included in the very next nightly release.

希望这份详细的概述对您有所帮助。如果您对我们的自动化或流程有任何疑问，请随时咨询！

¥We hope this detailed overview is helpful. If you have any questions about our automation or processes, please don't hesitate to ask!