flutter-cherry-pick

Flutter Cherry-Pick 工作流

限制

此技能有以下严格限制：

• 目标仓库： 仅用于 flutter/flutter 仓库。
• 目标渠道： 仅当 cherry-pick 的目标是 stable、beta，或符合 flutter-<major>.<minor>-candidate.<hotfix> 格式的候选发布分支时使用（例如，flutter-3.10-candidate.0）。
• PR 状态： 仅用于已成功合并到 master 的拉取请求。

快速开始

提供已合并的 PR 编号或 URL，并可选择指定目标渠道，以触发此技能：

• “将 PR 187045 cherry-pick 到 stable”
• “为 https://github.com/flutter/flutter/pull/186952 请求 CP 到 beta”
• “CP PR 187045”（Agent 会询问你要选择哪个渠道）

工作流

阶段 1：初始化和渠道检测

1. 识别输入：
   • 原始 PR：<ORIGINAL_PR>（用户提供的编号或 URL）。
   • 目标渠道：<CHANNEL>（stable 或 beta）。
2. 确定渠道：
   • 解析用户请求，确定目标渠道。
   • 门控步骤： 如果用户请求中未指定目标渠道，必须停止调用工具并询问用户：“你想将其 cherry-pick 到 stable 还是 beta？”然后等待用户回复，再继续操作。
3. 确认当前位于 flutter 仓库的根目录。
4. 验证环境： 确保仓库干净（没有未提交的更改）。运行 git status --porcelain 进行检查。如果存在待处理的更改，请停止操作，并让用户解决这些更改或将其暂存起来。

阶段 2：运行 Cherry-Pick 编排器

1. 运行辅助脚本以启动流程：

   <DART_EXECUTABLE> .agents/skills/flutter-cherry-pick/scripts/flutter_cp.dart --pr <ORIGINAL_PR> --channel <CHANNEL> --action start
   

2. 评估脚本输出：
   • 退出代码 0（成功）：
     • 输出末尾会显示 SUCCESS:AUTOMATED:<CP_PR> 或 SUCCESS:MANUAL:<CP_PR>。
     • 提取 <CP_PR> 编号。
     • 继续执行阶段 4：填写模板。
   • 退出代码 2（冲突）：
     • cherry-pick 遇到冲突，脚本已检出本地分支 cherry-pick-<ORIGINAL_PR>-to-<CHANNEL>。
     • 继续执行阶段 3：解决冲突。
   • 退出代码 1（错误）：
     • 发生意外错误。向用户报告失败。

阶段 3：解决冲突

1. 分析冲突：
   • 从脚本输出中确定存在冲突的文件（或运行 git status --porcelain 查看未合并的文件）。
2. 记录冲突： 说明遇到了哪些冲突以及如何解决。需要在最终 PR 描述中包含这些信息。
3. 尝试自动解决：
   • 对每个存在冲突的文件，分析冲突标记（<<<<<<<、=======、>>>>>>>）。
   • 如果冲突简单（例如导入顺序、轻微格式问题、非重叠更改），则解决冲突。
4. 用户兜底处理：
   • 如果无法自动解决冲突，或者冲突反映的逻辑更改会影响 flutter 用户：
     • 在聊天中向用户列出存在冲突的文件。
     • 请用户在其编辑器中解决冲突。
     • 停止调用工具，等待用户确认已解决。
5. 继续流程：
   • 所有冲突解决后（由你或用户解决），运行 git add <resolved-files> 将其暂存。
   • 恢复运行编排器脚本：

     <DART_EXECUTABLE> .agents/skills/flutter-cherry-pick/scripts/flutter_cp.dart --pr <ORIGINAL_PR> --channel <CHANNEL> --action continue
     

   • 脚本将运行 git cherry-pick --continue、推送更改、创建 PR，并打印 SUCCESS:MANUAL:<CP_PR>。
   • 提取 <CP_PR> 编号，然后继续执行阶段 4：填写模板。

第 4 阶段：填写模板并应用

1. 获取模板：
   • 读取本地 cherry-pick 模板（相对于此技能，位于 [PULL_REQUEST_CP_TEMPLATE](../../../.github/PR_TEMPLATE/PULL_REQUEST_CP_TEMPLATE.md)）。
2. 收集上下文：
   • 解析原始 PR 描述，查找关联问题（例如，“Fixes #187322”“Closes #123”）。
   • 如果找到问题，获取问题详情：gh issue view <ISSUE_NUMBER> --json title,body。
   • 如有需要，获取原始 PR 详情。
   • 如果在第 3 阶段遇到并解决了冲突，收集这些冲突的记录。
3. 起草模板：
   • 根据问题和原始 PR 上下文，使用 LLM 推理填写获取的模板字段。
   • 如果解决了冲突，请在 PR 描述中清楚记录这些冲突（例如，在“描述”或“变更日志”部分），说明解决了什么以及如何解决。
   • 保持模板的 Markdown 结构不变。
   • 重要： 在用回复替换各部分中的说明文字或指南时，请将其删除（例如“影响是什么……”“解释此次 cherry-pick……”）。替换复选框或选项时，不要删除其周围的说明（例如“风险级别是什么……”“你有信心吗……”）。
   • 填写文本部分示例（删除说明文字）：
     • 之前：

       ### Impact
       What is the impact of this cherry-pick? (Explain the impact on users...)
       

     • 之后：

       ### Impact
       This fixes a critical crash in the image decoder when rendering corrupted GIFs.
       

   • 填写复选框／选项部分示例（不要删除选项）：
     • 之前：

       ### Shared Engineering Cohort
       Were any engineering cohorts (e.g. Flutter Tooling, Engine, Framework) consulted?
       - [ ] Yes
       - [ ] No
       

     • 之后：

       ### Shared Engineering Cohort
       Were any engineering cohorts (e.g. Flutter Tooling, Engine, Framework) consulted?
       - [x] Yes
       - [ ] No
       

4. 与用户审核（必须完成的步骤）：
   • 在聊天中向用户展示起草的模板，并询问用户是否批准或需要修改。
   • 必须停止调用工具并等待用户在聊天中明确批准后再继续。不得提前尝试应用模板。
5. 应用模板、更新标题并添加标签：
   • 只有在收到用户明确批准后，才能继续此步骤。
   • 确保 PR 标题的格式为 [<CHANNEL>] <ORIGINAL_PR_TITLE>。
   • 确保 CP PR 已添加 cp: review 标签。
   • 获得批准后，更新 CP PR 的描述和标题，并添加标签：

     gh pr edit <CP_PR> --title "[<CHANNEL>] <ORIGINAL_PR_TITLE>" --body "<FINAL_TEMPLATE>" --add-label "cp: review"
     

     （注意：如果 gh pr edit 因 GraphQL 弃用错误而失败，可以通过 gh api 使用 REST API 更新描述并添加标签。）
   • 将新的 cherry-pick PR 链接提供给用户。