使用 GitHub Copilot 云代理改进项目

简介

现代开发常常出于善意开始：编写一个快速脚本、原型，或是自动化某个小任务的操作。但随着项目演进，这些早期的尝试往往变得脆弱。

本教程展示如何使用 Copilot 云代理改进成熟项目，同时不影响你的开发节奏。

在接下来的章节中，我们将

• 确保项目包含自定义说明，供 Copilot 用来针对你的项目定制响应。
• 确保存在 Copilot 云代理的环境设置文件，以便它通过预先安装项目依赖，更快开始任务。
• 让 Copilot 检查代码可改进之处，并为这些工作创建议题。
• 通过将议题指派给 Copilot，将编码工作委派给它。

1. 检查自定义说明

1. 前往 GitHub 上你的仓库。

2. 检查以下至少一个自定义说明文件是否存在

   • .github/copilot-instructions.md
   • .github/instructions/**/*-instructions.md
   • AGENTS.md

3. 如果这些文件中有任何一个存在，打开查看并确认说明是否充分且为最新。

   欲了解更多信息，请参阅章节 “编写有效的自定义说明” 于 关于自定义 GitHub Copilot 响应，以及位于 自定义说明 的示例库。

4. 如果仓库中没有自定义说明文件，请使用 Copilot 云代理创建 .github/copilot-instructions.md 文件，按照 为 GitHub Copilot 添加仓库自定义说明 中的步骤进行操作。

5. 审查 Copilot 云代理创建的拉取请求。检查 .github/copilot-instructions.md 文件是否为 Copilot 提供了所有必要信息，以便在此项目上工作。

   文件应包含

   • 对代码库及软件功能的清晰概述。
   • 项目结构概览。
   • 贡献指南。例如，如何构建、格式化、lint、测试代码库，以及合并拉取请求前必须满足的要求。
   • 关键技术原则。

6. 根据需要编辑该文件。

7. 点击 Ready for review（准备审查）位于拉取请求的 “Conversation” 选项卡底部，然后按常规流程合并拉取请求。

2. 检查环境设置文件

一个 copilot-setup-steps.yml GitHub Actions 工作流文件可以帮助 Copilot 云代理通过预先安装项目使用的依赖，更快开始任务。

创建此文件是可选的，但如果你经常在仓库中使用 Copilot 云代理，建议创建。

1. 在 GitHub 上的仓库中，确认以下文件是否存在

   Text

   .github/workflows/copilot-setup-steps.yml
   

   提示

   快速方法是复制上述路径，前往仓库主页并将路径粘贴到 “Go to file”（前往文件）字段中。

2. 如果文件存在，打开并检查工作流中的步骤是否为你的项目安装了正确的依赖。确认后，可跳过本节其余步骤。

3. 如果还没有 copilot-setup-steps.yml 文件，请使用以下步骤让 Copilot 云代理为你创建。

4. 在 GitHub 网站的任意页面顶部，点击 。

5. 复制并粘贴以下提示到代理对话框中

   Text

   Analyze this repository to understand the dependencies that need to be installed on the development environment to work on the code in this repository. Using this information, and the details about the `copilot-setup-steps.yml` file that are given in https://docs.github.com/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment, add a `.github/workflows/copilot-setup-steps.yml` to this repository. This Actions workflow file should install, in the development environment for Copilot cloud agent, all of the dependencies necessary to work on the code in this repository. Make sure that the workflow job is named `copilot-setup-steps`.
   

6. 点击 或按 Enter。

7. 在 “Recent agent sessions”（最近的代理会话）列表中，点击已启动的新会话。

   这将显示活动日志，Copilot 在执行任务时的记录。完成后，它会生成一份工作摘要。

8. 阅读摘要，然后点击 查看拉取请求。

9. 可选地，将 Copilot 添加为审查者。更多信息请参阅 使用 GitHub Copilot 代码审查。等待 Copilot 添加审查评论，然后根据评论进行必要的更改。

10. 自行审查拉取请求，确保新 copilot-setup-steps.yml 文件中的设置步骤正确。

    Copilot 创建的工作流文件应包含 on: workflow_dispatch 触发器，以便手动运行工作流，并且作业名称必须为 copilot-setup-steps，如以下摘录所示。

    on:
      workflow_dispatch:
      push:
        paths:
          - .github/workflows/copilot-setup-steps.yml
      pull_request:
        paths:
          - .github/workflows/copilot-setup-steps.yml
    
    jobs:
      copilot-setup-steps:
        runs-on: ubuntu-latest
    

11. 在拉取请求中对 copilot-setup-steps.yml 文件进行任何必要的更改。

    你可以在审查评论中使用 @copilot 请求 Copilot 为你进行更改。例如

    @copilot - 更加详细地注释文件

12. 点击 Ready for review（准备审查）位于拉取请求的 “Conversation” 选项卡底部，然后按常规流程合并拉取请求。

13. 在 GitHub 上打开新添加的 .github/workflows/copilot-setup-steps.yml 文件。

14. 点击页面右上方的 View Runs（查看运行）

15. 点击 Run workflow（运行工作流），在弹窗中再次点击 Run workflow，以测试新工作流。

16. 检查工作流是否正确运行并安装依赖。如有失败，请编辑 .github/workflows/copilot-setup-steps.yml 文件进行修复。

3. 让 Copilot 找出技术债务

现在 Copilot 已拥有正确的上下文（以及可选的即用环境），你可以利用它来发现并优先处理仓库中的技术债务。

1. 点击下方提示框中的 按钮，将此提示发送至 GitHub.com 上的 Copilot Chat。

   Copilot prompt

   What technical debt exists in this project? Give me a prioritized list of up to 5 areas we need to focus on. For each, describe the problem and its consequences.
   

2. 确保已选中 提问（Ask） 模式已被选中。

3. 使用 All repositories（所有仓库） 下拉菜单选择你的仓库。

4. 点击 或按 Enter。

5. 审阅 Copilot 响应中的详情。

6. 假设 Copilot 已识别出至少一个改进点，请将以下提示复制到同一对话中。

   Copilot 提示

   /create-issue
   
   Create a GitHub issue to address the first of the problem areas that you identified.
   
   If the problem area requires substantial work, create one main issue for the entire problem area and then sub-issues that allow the work to be split up into manageable chunks, which will be tackled in separate pull requests that can be easily reviewed. For a large body of work, do not create a single issue that attempts to address the entire problem.
   
   The issue, or each sub-issue if these are created, must include a description of the problem, a set of acceptance criteria, and pointers on what files need to be added/updated.
   

7. 根据需要编辑此提示。例如，根据 Copilot 的回复，你可能想处理 Copilot 识别的其他问题区域，而非首个。

8. 确保仍然选中提问模式（）。

9. 点击 或按 Enter。

10. 审查 Copilot 生成的草稿议题，并根据需要进行编辑。

11. 如果 Copilot 创建了一个草稿议题，且提示应创建子议题，请提示 Copilot 为你完成此操作。

    Copilot 提示

    Go ahead and create sub-issues that chunk this work into manageable pieces.
    

12. 点击 Create（创建），或 Review and Create（审查并创建），具体取决于草稿议题数量。

    Copilot 将代表你创建一个或多个新议题，作者将显示为你。

4. 让 Copilot 修复议题

创建议题后，下一步是将议题委派给 Copilot，并审查相应的拉取请求。

1. 打开上一节 Copilot 为你创建的其中一个议题。

2. 确认议题中包含 Copilot 可用来验证任务完成的验收标准。

3. 根据需要进行修改，以准确描述需修复的问题以及该议题工作期望的结果。

4. 点击 指派给 Copilot。

5. 在 “Assign Copilot to issue”（将 Copilot 指派给议题）中，点击 Assign（指派）。

   Copilot 将开始处理该议题。片刻后，一个指向草稿拉取请求的链接将被添加到议题中。

6. 点击指向草稿拉取请求的链接。

   当 Copilot 完成拉取请求的工作后，它会从标题中移除 “[WIP]”，并将你添加为审查者。

   你可以让 Copilot 异步处理拉取请求，待被添加为审查者后再回来审阅。

7. 可选：在 Copilot 工作几分钟后，你可以点击拉取请求上的 View session（查看会话），查看 Copilot 正在执行的日志。

8. 可选地，在拉取请求的 “Conversation”（对话）选项卡中，将 Copilot 添加为审查者。

9. 被添加为审查者后，自己审查更改并进行必要的修改。

   你可以在审查评论中使用 @copilot 请求 Copilot 为你进行更改。

10. 点击 Ready for review（准备审查）位于拉取请求的 “Conversation” 选项卡底部，然后按常规流程合并拉取请求。

5. 循环迭代此过程

1. 如果 Copilot 创建了多个议题，重复第 4 部分，将 Copilot 指派给其他议题。
2. 关闭 Copilot 创建的所有议题后，重复第 3 部分，选择另一个问题区域，并在第 4 部分循环指派议题给 Copilot，审查并合并其更改。

结论

Copilot 云代理可以帮助你提升任何项目的代码质量，尤其适用于长期有机增长的项目，帮助降低技术债务。通过使用 Copilot 云代理，你可以实现一些本可能因时间不足而难以进行的改进。

Copilot 并不会取代你作为开发者的角色——你仍需在每一步参与，指定 Copilot 的任务并仔细审查它所改动或新增的代码——但它可以让你在处理其他重要任务的同时实现改进。

后续步骤

阅读 GitHub 博客上的案例研究：GitHub 计费团队如何使用 GitHub Copilot 中的云代理持续降低技术债务。