使用 GitHub Copilot 產生專案文件

  • 6 分鐘

專案文件說明專案的用途、目標和需求。 若要建立項目檔，您必須瞭解項目結構、其元件，以及元件彼此互動的方式。

GitHub Copilot 的聊天視窗是產生專案文件的理想工具，因為它能分析整個專案結構並提供專案的高層次概述。 聊天檢視也可以用來產生特定類型的檔，例如自述檔、API 參考和其他專案相關文件。

你可以使用各種聊天視窗模式（詢問、代理或計畫）來產生專案文件。 每個模式都有自己的優缺點。 項目規格和其他條件約束會影響應該使用的模式。

這很重要

當你在客服模式下使用聊天檢視時，每個輸入的提示都算作一個高級請求，並乘以該模型的倍數。 GitHub Copilot可能會進行多次後續行動來完成任務，但這些後續行動不計入您的高級請求使用量。 只有你輸入的提示才會被計費。 總使用的高級請求數量取決於你輸入的提示數量和所選型號。

建立專案文件需求

檔類型和內容需求取決於專案、預定取用者，以及組織採用的標準。

例如，README.md 可能包含下列各節：

  • 項目標題：項目的名稱。
  • 描述：專案的用途及其存在原因的簡短概觀。
  • 目錄：可選，但對於較長的 README 有幫助。
  • 安裝：如何安裝和設定專案的指示。
  • 使用方式：如何使用專案的範例，包括代碼段或螢幕快照。
  • 功能：主要特性或功能的清單。
  • 組態：任何組態選項或環境變數的詳細數據。
  • 參與：參與項目的指導方針。
  • 授權：分散式專案所使用的任何授權。
  • 致謝與鳴謝：承認貢獻者、所用庫或資源。
  • 聯繫人：如何連絡維護人員或專案小組。
  • Changelog：變更和更新的歷程記錄（有時鏈接至個別檔案）。

GitHub Copilot 聊天能協助你產生符合專案及其利害關係人特定需求的專案文件。

使用「詢問代理」模式來產生專案文件

Ask Agent 模式可用於分析工作空間並產生文件。

請使用以下流程使用詢問代理模式產生專案文件：

  1. 識別文件需求和支援資源。

    • 識別您專案所需的文件要求。 識別文件類型和所需的文件部分。

    • 識別產生檔所需的資源。 您的程式代碼工作區可以是唯一的必要資源。 不過，您可能需要在聊天中新增內容，如「參與」、「鳴謝」及「聯繫方式」等部分。

  2. 打開聊天視窗，並使用詢問客服模式開始新的聊天會話。

  3. 將上下文新增至聊天會話。

    • 你可以透過將檔案從 Visual Studio Code 的 EXPLORER 檢視拖放到 聊天視窗，為聊天會話增添上下文。 你也可以使用 「附加上下文 」按鈕（迴紋針圖示）。
    • 您可以在程式代碼編輯器中開啟外部檔案，以包含不屬於工作區的資源，並使用它們來提供更多內容。 例如，你可以打開包含貢獻者指引或聯絡資訊的 markdown 檔案，然後用 「附加上下文 」按鈕將它們加入聊天視窗的上下文中。

  4. 輸入一系列提示，以調查您的文件需求。

    你可以使用詢問代理模式分析工作區，建立支持你文件需求的聊天會話歷史。 描述您的目標有助於建立聊天會話的內容。 提出符合你需求的問題有助於GitHub Copilot找出產生文件所需的資訊。

    視需要重新整理新增的內容。

  5. 輸入詢問建議專案文件的提示，並列出您在第一個步驟中識別的必要區段。

    例如：「@workspace /explain I need help creating a README file that can be used in the GitHub repository for this workspace. The file should be formatted as markdown. The README file needs to include the following sections: Project Title, Description, Table of Contents, Installation, Usage, Features, Configuration, and License.」

  6. 檢視建議的項目檔，並視需要使用新的提示來精簡結果。

  7. 將建議的項目文件移至項目文件檔案。

    例如，在工作區的根目錄建立 README.md 檔案，並將建議的內容插入檔案中。

    你可以在建立文件後，使用詢問代理模式建議專案特定部分的更新，或使用其他GitHub Copilot工具協助更新。

使用計畫模式產生專案文件

計畫模式最適合在產生專案文件前先建立詳細的實施計畫。 計畫模式分析程式碼庫，識別文件需求，並產生逐步計畫。 一旦計畫獲得核准，你可以將其交由代理模式執行。

請使用以下流程，透過計畫模式產生專案文件，例如 README.md 檔案：

  1. 識別文件需求和支援資源。

  2. 打開聊天視窗，並使用計畫模式開始新的聊天會話。

  3. 輸入一個描述你文件任務的提示。

    例如：「我需要建立一個 README 檔案和支持文件來完成這個專案。 README 應包含：專案標題、描述、目錄、安裝、使用、功能、設定及授權條款。」

  4. 檢視實施計畫。

    幾分鐘後，計畫代理人會在聊天視窗中輸出一個計畫。 計畫提供高層次摘要及步驟分解，包括任何未解問題以供釐清。 你可以多次迭代來釐清需求、調整範圍或回答問題。

  5. 計畫完成後，選擇 「開始實作 」將計畫交接到代理模式，或選擇「 在編輯器中開啟 」將計畫儲存為 Markdown 檔案以供日後使用。

    當您選擇 Start Implementation 時，GitHub Copilot 會切換為代理模式，並開始根據核准計畫實作文件。 檢視產生的文件檔案，接受或捨棄變更。

使用代理程式模式產生項目檔

代理程式模式最適合用來產生需要深入瞭解專案的項目檔。 代理程式模式會在產生項目檔之前，先分析整個項目結構。 藉由從多個檔案和資料夾收集資訊，代理程式模式可以描述複雜的關聯性，並包含檔之間的連結。

請使用以下流程使用代理模式產生專案文件，例如 README.md 檔案：

  1. 識別文件需求和支援資源。

  2. 開啟 [聊天] 檢視，並使用代理程式模式啟動新的聊天會話。

  3. 將上下文新增至聊天會話。

    聊天參與者無法在代理程式模式中使用，因此您無法指定 @workspace 為提示的一部分。 不過，您可以使用#codebase，並將工作區的檔案和資料夾新增至聊天室內容，以增加聊天會話的上下文。 外部檔案可以在 Visual Studio Code 中開啟，然後使用 Attach Context 按鈕將其新增到聊天內容中。

  4. 輸入指令以建立所需的項目文檔。

    例如：「產生專案文件檔的集合。 建立或更新此存放庫的工作區 README.md 檔案。 建立或更新 UsageExamples.md 檔案。 建立或更新 ChangeLog.md 檔案。 包含文件、跨參考類別和方法之間的連結，並確保檔之間的一致性。

  5. 查看文件檔案，然後儲存或捨棄更新。

    視需要，使用提示來更新檔案，以更正或增強特定區段。

代理程式模式功能

有數個文件任務，代理模式是最佳選擇。

  1. 多檔案和跨檔案文件產生。

    • 代理程式模式可以分析整個項目結構、從多個檔案和資料夾收集資訊，以及產生可連結和摘要程式代碼基底內容的檔。 例如，產生描述所有主要元件的完整 API 參考或 README。

  2. 自動化專案分析和摘要。

    • 代理程式模式可以執行工作，例如摘要架構、識別主要類別/服務，以及產生需要了解檔案和元件之間關聯性的圖表或數據表。

  3. 動態內容產生（例如，使用範例、類別資料表）

    • 代理程式模式可以掃描專案，以產生使用範例、類別責任數據表或公用 API 清單。

  4. 批次文件化任務。

    • 代理程式模式可以在一個工作流程中執行一系列檔工作（例如更新自述檔、建立 CONTRIBUTING.md、產生 API 檔、更新變更記錄）。

  5. 智慧連結與導覽。

    • 代理程式模式可以在檔檔案、跨參考類別和方法之間建立連結，並確保文件之間的一致性。

代理模式非常適合進行需要分析、合成和協調的整個專案、多檔案和上下文感知文件工作。

總結

GitHub Copilot 能協助你產生符合專案及其利害關係人特定需求的專案文件。 聊天視窗可用於三種不同模式產生專案文件：詢問、代理與規劃。 每個模式都有自己的優缺點，使用的最佳模式取決於手邊的特定工作。 問代理模式最適合用來詢問關於你的程式碼庫或技術概念的問題。 代理模式最適合產生需要深入專案理解的專案文件。 計畫模式最適合在產生文件前建立詳細的實施計畫，然後交接給代理模式執行。