自动化与分诊流程

本文档详细介绍我们用来管理 Issue 与 Pull Request 的自动化流程。目标是快速反馈、确保贡献高效评审与合并。了解这些自动化机制能帮助贡献者明确期待，并更好地与仓库中的机器人协作。

指导原则：Issue 与 Pull Request 配对

几乎所有 Pull Request（PR）都应该关联到一个 Issue。Issue 负责描述“是什么”和“为什么”（缺陷或功能），PR 则描述“如何实现”。这种分离有助于跟踪工作、为特性排期以及保留清晰的历史背景。我们的自动化流程也是围绕该原则构建的。

以下是仓库中运行的具体自动化工作流。

这是你创建 Issue 时遇到的第一个机器人。它负责初步分析并打上正确的标签。

工作流文件：.github/workflows/gemini-automated-issue-triage.yml
触发时机：Issue 创建或重新打开后立即触发。
主要功能：
- 使用 Gemini 模型依据详细指南分析 Issue 标题与正文。
- 添加一个 area/* 标签：将 Issue 归到项目功能领域（如 area/ux、area/models、area/platform）。
- 添加一个 kind/* 标签：标记 Issue 类型（如 kind/bug、kind/enhancement、kind/question）。
- 添加一个 priority/* 标签：根据影响程度分配优先级，从 P0（严重）到 P3（低）。
- 可能添加 status/need-information：当 Issue 缺少关键细节（日志、复现步骤等）时，会要求补充信息。
- 可能添加 status/need-retesting：当 Issue 提到的 CLI 版本落后超过 6 个版本时，要求在最新版本上重测。
你的行动：
- 尽可能完整填写 Issue 模板，信息越充分，分诊越准确。
- 如果出现 status/need-information 标签，请在评论中补充所需信息。

该流程确保所有改动在合并前满足质量标准。

工作流文件：.github/workflows/ci.yml
触发时机：每次向 PR 推送代码都会运行。
主要功能：
- Lint：检查代码是否符合项目格式与风格。
- Test：在 macOS、Windows、Linux 以及多个 Node.js 版本上运行完整测试套件，这是 CI 中最耗时的部分。
- 发布覆盖率评论：全部测试通过后，机器人会在 PR 中评论测试覆盖情况摘要。
你的行动：
- 确保所有 CI 检查都通过。成功时提交旁会出现绿色对勾 ✅。
- 若某项失败（显示红色 “X” ❌），点击 “Details” 查看日志、定位问题并推送修复。

该流程定期运行，确保所有未关闭 PR 都正确关联 Issue 且标签一致。

工作流文件：.github/workflows/gemini-scheduled-pr-triage.yml
触发时机：每 15 分钟检查所有未关闭 PR。
主要功能：
- 检查关联 Issue：扫描 PR 描述中的关联关键字（例如 Fixes #123、Closes #456）。
- 添加 status/need-issue：若未找到关联 Issue，会打上该标签，提示需要创建并关联 Issue。
- 同步标签：若已关联 Issue，则确保 PR 标签与 Issue 完全一致，补齐缺失的、移除不相关的，并清除 status/need-issue。
你的行动：
- 务必为 PR 关联 Issue。 在描述中添加 Resolves #<issue-number> 等语句。
- 这样可以确保 PR 得到正确分类并顺利进入评审流程。

该流程作为兜底，确保没有 Issue 被遗漏。

工作流文件：.github/workflows/gemini-scheduled-issue-triage.yml
触发时机：每小时检查所有未关闭 Issue。
主要功能：
- 查找仍未打标签或仍带有 status/need-triage 的 Issue。
- 触发与初始分诊相同的 Gemini 分析，补充正确标签。
你的行动：
- 通常无需额外操作。该流程确保即便初始分诊失败，Issue 也能最终归类。

该流程负责打包并发布 Gemini CLI 新版本。

希望以上概览对你有帮助。如对自动化流程有任何疑问，欢迎随时提问！