自动化与问题分诊流程

本文档详细介绍了我们用于管理和分诊问题（Issues）及拉取请求（Pull Requests，PR）的自动化流程。我们的目标是及时提供反馈，并确保贡献内容得以高效评审和集成。了解这些自动化机制，有助于您作为贡献者明确预期，并以最佳方式与我们的仓库机器人交互。

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

首要原则是：几乎每个拉取请求（PR）都应关联一个对应的问题（Issue）。问题描述“做什么”和“为什么做”（即所修复的缺陷或所实现的功能），而 PR 则说明“如何做”（即具体实现）。这种职责分离有助于我们追踪工作进展、对功能进行优先级排序，并保持清晰的历史上下文。我们的自动化系统正是围绕这一原则构建的。

详细的自动化工作流

以下是我们在仓库中运行的具体自动化工作流说明。

1. 创建 Issue 时：自动 Issue 分类

这是你在创建 Issue 时最先交互的机器人。它的职责是对 Issue 进行初步分析，并打上合适的标签。

• 工作流文件：.github/workflows/qwen-automated-issue-triage.yml
• 触发时机：Issue 被创建或重新打开后立即运行。
• 功能说明：
  • 使用 Qwen 模型，依据一套详尽的规则，对 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 版本已超过六个版本未更新，则会被标记为需在当前版本上重新测试。
• 你应该怎么做：
  • 尽可能完整地填写 Issue 模板。你提供的细节越充分，分类结果就越准确。
  • 若被添加了 status/need-information 标签，请在评论中提供所要求的信息。

2. 提交 Pull Request 时：持续集成（CI）

该工作流确保所有变更在合并前均符合我们的质量标准。

• 工作流文件：.github/workflows/ci.yml
• 触发时机：每次向 Pull Request 推送代码时。
• 执行内容：
  • 代码检查（Lint）：验证你的代码是否符合本项目的格式与风格规范。
  • 测试（Test）：在 macOS、Windows 和 Linux 上，以及多个 Node.js 版本下，运行全部自动化测试套件。这是 CI 流程中耗时最长的部分。
  • 发布覆盖率评论（Post Coverage Comment）：所有测试成功通过后，机器人将在你的 PR 下发布一条评论，汇总你的代码变更被测试覆盖的程度。
• 你需要做的：
  • 确保所有 CI 检查均通过。当一切顺利时，你的提交旁将显示绿色对勾 ✅。
  • 若某项检查失败（出现红色叉号 ❌），请点击失败检查旁的“Details”链接查看日志，定位问题，并推送修复。

3. 持续进行的 Pull Request 分类：PR 审核与标签同步

该工作流会周期性运行，以确保所有已打开的 PR 均正确关联至对应 issue，并拥有统一、一致的标签。

• 工作流文件：.github/workflows/qwen-scheduled-pr-triage.yml
• 触发时机：每 15 分钟对所有已打开的 Pull Request 运行一次。
• 执行内容：
  • 检查是否关联了 issue：机器人会扫描你的 PR 描述，查找用于关联 issue 的关键词（例如 Fixes #123、Closes #456）。
  • 添加 status/need-issue 标签：若未找到关联的 issue，机器人将为你的 PR 添加 status/need-issue 标签。这明确提示你需要创建并关联一个 issue。
  • 同步标签：若已关联 issue，机器人将确保 PR 的标签与该 issue 的标签完全一致——自动添加缺失的标签、移除不相关的标签；若此前存在 status/need-issue 标签，也将一并移除。
• 你应该怎么做：
  • 务必为你的 PR 关联一个 issue。 这是最关键的一步。请在 PR 描述中添加类似 Resolves #<issue-number> 的语句。
  • 这样可确保你的 PR 被正确归类，并顺利进入评审流程。

4. 持续的问题分类：定时问题分类

这是一个备用工作流，用于确保没有任何问题被遗漏在分类流程之外。

• 工作流文件：.github/workflows/qwen-scheduled-issue-triage.yml
• 触发时机：每小时对所有已开启的问题运行一次。
• 功能说明：
  • 主动查找尚未打任何标签，或仍带有 status/need-triage 标签的问题。
  • 随后触发与初始分类机器人相同的、基于 QwenCode 的强大分析能力，为问题打上正确的标签。
• 你需要做的操作：
  • 通常无需任何操作。该工作流作为安全网，确保每个问题最终都会被归类，即使初始分类失败。

5. 发布自动化

该工作流负责 Qwen Code 新版本的打包与发布。

• 工作流文件：.github/workflows/release.yml
• 触发时机：每日定时执行（用于“夜间构建”发布），以及手动触发（用于正式的补丁版/小版本发布）。
• 功能说明：
  • 自动构建项目、更新版本号，并将包发布到 npm。
  • 在 GitHub 上创建对应版本发布，并附上自动生成的发布说明。
• 你需要做什么：
  • 作为贡献者，你无需为此流程执行任何操作。你可以放心：一旦你的 PR 被合并至 main 分支，你的修改将在下一个夜间构建版本中自动包含。

希望这份详细概述对你有所帮助。如果你对我们的自动化流程或相关机制有任何疑问，请随时提出！