如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

程式碼審查

瞭解 pull requests 的變更內容、查證審查發現的問題,並審查本機變更

使用 ChatGPT 或 Codex 瞭解程式碼變更、調查潛在問題,並擬定審查意見。

Pull request 審查

程式碼審查外掛程式會顯示 pull request 的說明、變更的檔案、留言和檢查結果。核准前,可用它來調查潛在問題。

GitHub 程式碼審查已正式推出。程式碼審查對 GitLab 合併請求的支援目前處於預覽階段。若要從 GitLab 使用 @codex review 觸發雲端審查,或自動審查合併請求,請參閱使用 Codex 審查 GitLab 合併請求。

若要從程式碼庫觸發審查,請參閱 GitHub 整合指南和 Codex 雲端(舊版)環境設定。

桌面應用程式內建程式碼審查。你可以在已安裝的外掛程式清單中,將它釘選到應用程式側邊欄。

檢視 pull request

  1. 從側邊欄開啟程式碼審查。
  2. 出現提示時,連結你的原始碼託管平台帳號。該帳號須有權存取你要審查的程式碼庫。
  3. 從側邊欄選取 pull request,或在搜尋欄位輸入其連結。
  4. 在摘要中查看說明、活動紀錄、留言和檢查結果。開啟變更,即可對照差異查看變更的檔案和留言。

找出需要處理的審查

在個人收件匣中,你可以找到不同程式碼庫的 GitHub pull requests。選取指派給我可查看請你審查的項目,選取指派給我的團隊可查看請團隊審查的項目,選取由我建立則可回到你自己提出的變更。先查看審查狀態,再開啟 pull request 檢視意見和檢查結果。

若想稍後繼續審查,請選取工具列上的釘選圖示。該 pull request 就會出現在側邊欄的已釘選下方。

檢視變更的檔案和相關 pull requests

在變更中審查完一個檔案後,選取該檔案的標示為已檢視。再次選取即可清除標記。已檢視標記僅適用於目前顯示的修訂版本。

如果一項變更分散在多個有相依關係的 pull requests 中,可透過堆疊(位於摘要中)開啟相關 pull request,檢視其差異、留言和檢查結果。當程式碼審查找到一組仍開啟且有堆疊關係的 pull requests 時,就會顯示這個區段。

查看自動雲端審查結果

連結 ChatGPT Codex 連接器、取得必要的程式碼庫權限並啟用自動審查後,Codex 就能在你開啟 GitHub pull request 前先行審查。審查留言會顯示在 GitHub 和程式碼審查中。

使用雲端審查無須建立或管理雲端環境。關於連線需求、程式碼庫設定,以及如何使用 @codex review 觸發審查,請參閱在 GitHub 中使用 Codex。

請對照程式碼差異,核實審查發現的問題。自動雲端審查與你在 pull request 對話中啟動的審查各自獨立。

詢問變更內容

在 pull request 對話中說明預期行為,請 Codex 解釋或調查這項變更。

選取使用 Codex 審查,即可在新對話中啟動審查。如果你正在現有對話旁檢視 pull request,可以直接在該對話中詢問變更內容。

透過已安裝的技能和已連結的來源,向 Codex 提供團隊的審查準則或設計文件。請它概述變更並說明相關風險,再核對它引用的上下文和程式碼。

例如,某個 pull request 在議題看板上新增了 Open 和 Closed 篩選選項。你預期 All 仍是預設選項,且沒有符合條件的議題時,看板會顯示空白狀態:

請逐步解說這個 pull request 的變更,重點說明看板預設使用哪個篩選選項,以及沒有符合條件的議題時會顯示什麼。預設選項應維持為 All。

請 Codex 提供佐證:

請指出沒有符合條件的議題時,程式碼會循哪條路徑執行,以及哪些測試會檢查這種情況。請說明測試已涵蓋哪些行為,還有哪些行為需要驗證。

檢視 Codex 引用的差異和測試,確認是否符合預期行為。

選取審查發現的問題,即可在變更中查看說明和相關程式碼行。請對照最新差異、預期行為和測試,再決定是否需要修正。若要停止進行中的審查,可在審查對話中操作。

自訂審查

選取審查指示的齒輪圖示,位置在使用 Codex 審查旁。你也可以在設定 > 程式碼審查中編輯這些指示。

向 Codex 提供各次審查通用的準則和報告格式,例如:

先寫一段簡短摘要。優先檢查行為變更、資料遺失風險,以及缺少測試的邊界情況。針對每個發現的問題,說明哪些輸入會觸發問題、預期行為是什麼,以及實際發生了什麼。請沿用團隊簡潔的審查風格。

無論在哪個程式碼庫,只要你選取使用 Codex 審查啟動審查,就會套用這些指示。審查進行中修改的指示會從下次審查起生效。如果問題只涉及某一項變更,請在該 pull request 的對話中提問。

你也可以選取漫畫、視覺化或 PDF,加入建議指示,讓 Codex 以該格式說明變更。視需要編輯文字,再選取儲存或執行審查。

分享審查意見並追蹤後續變更

在對話中審查 pull request 不會發布留言,也不會核准或合併該 pull request。要分享哪些審查發現,由你決定。

確認問題後,請 Codex 協助草擬審查留言:

請依照我們討論過的團隊審查準則草擬一則留言。針對沒有符合條件的議題這種情況,說明我們已確認的看板實際行為、預期應有的行為,以及可以用哪項測試驗證。請將留言保留為草稿,不要發布。

發布前,請核對草稿引用的檔案和行號。準備好發布前,請將草稿留在對話中。在摘要或變更中發布留言,會立即將留言傳送至原始碼託管平台,不會等到你選取提交審查。

使用提交審查選擇留言、核准或要求變更,並將審查結果傳送至原始碼託管平台。提交前,請確認所選的審查決定和留言內容。

如果你是作者,可以回到自己的 pull request,請 Codex 處理特定意見。檢視修改結果,並執行相關測試。核准或合併前,請確認最新修訂版本、檢查結果,以及尚待處理的意見。

程式碼審查不支援編輯附有圖片的 pull request 說明。若要編輯這類說明,請在 GitHub 中開啟該 pull request。

回到對話繼續處理

當摘要中顯示對話串時,選取其中一個對話連結即可回到該對話。這裡列出的是你與該 pull request 相關的對話。

在 Codex 中,選取修正(位於開啟中的 pull request 的檢查區段),即可將未通過的檢查附加至對話。這個動作會備妥訊息,但不會傳送。請檢視或補上提示詞,再傳送訊息請 Codex 調查。推送修正前,請檢視修改結果並重新執行相關測試。

可用的診斷資訊取決於執行檢查的平台。如果使用第三方 CI,Codex 可以使用該平台回報給 GitHub 的狀態和輸出。

審查本機變更

Codex 內建的 /review 指令可審查本機 Git 工作副本中的變更,程式碼審查外掛程式則用於審查 pull requests。 請選擇你使用的用戶端,查看對應的步驟。

在應用程式中審查

開啟審查窗格即可瞭解變更內容、針對特定程式碼行提供意見,並決定要暫存、還原、提交或推送哪些變更。

若要請 Codex 審查變更,請在撰寫工具中輸入 /review。選擇與基準分支比較並審查或審查尚未提交的變更。Codex 會依優先順序列出發現的問題,不會修改你的工作樹。

專案必須位於 Git 程式碼庫內,才能使用審查窗格。如果你的專案還不是 Git 程式碼庫,應用程式會提示你建立一個。

選擇審查範圍

窗格會顯示哪些變更

審查窗格反映整個 Git 程式碼庫的狀態。除了 Codex 編輯的內容,也會顯示你自己所做的變更,以及程式碼庫中其他尚未提交的變更。

審查窗格預設顯示未暫存的變更。選取已暫存可查看 Git 索引中的變更,選取提交可查看指定提交的變更,選取分支可查看與基準分支的差異,選取上一輪則可查看助理在最近一輪對話中所做的變更。

審查多個程式碼庫

如果本機專案包含多個資料夾,且這些資料夾分屬不同的 Git 程式碼庫,審查窗格就能顯示各程式碼庫的變更。開啟審查窗格頂端的程式碼庫選擇器,即可在同一個窗格中切換到其他程式碼庫,查看新增或刪除了哪些行。

選擇上一輪可查看助理最近一輪在所有已連結程式碼庫中所做的變更。在這個檢視畫面中,程式碼庫選擇器會顯示所有程式碼庫。其他審查範圍,例如未暫存、已暫存和分支,只適用於你選取的程式碼庫。

處理審查結果

程式碼審查結果

審查發現的問題會以行內留言的形式顯示在審查窗格中。

審查預設在目前的對話中執行。在設定 > 一般 > 程式碼審查中選擇獨立,即可另開審查對話。請參閱開發人員設定。

如果你請 Codex 修正審查發現的問題,仍會套用你平常的沙盒與核准設定。

操作審查窗格

  • 按一下檔案名稱,通常會在你選擇的編輯器中開啟該檔案。你可以在開發人員設定中選擇預設編輯器。
  • 按一下檔案名稱的背景區域,即可展開或收合差異。
  • 按住 Command 並按一下某一行,即可在你選擇的編輯器中開啟該行。
  • 你可以暫存滿意的變更,或還原不想保留的變更。

使用行內留言提供意見

行內留言可讓你直接針對差異中的特定行提供意見。這通常是引導 Codex 正確修正問題最快的方式。

若要留下行內留言:

  1. 開啟審查窗格。
  2. 將游標移到你要留言的行上。
  3. 選取隨即出現的 + 按鈕。
  4. 輸入意見並提交。
  5. 留完意見後,回到對話傳送訊息。

由於留言會指向特定行,Codex 能比收到概括性的指示時回應得更精確。

Codex 會將行內留言視為審查指引。留言後,請再傳送一則訊息,明確說明你希望 Codex 採取的行動,例如:「請處理行內留言,只做必要的修改。」

暫存與還原檔案

審查窗格提供 Git 操作,讓你在提交前調整要納入的變更。

你可以在下列層級暫存、取消暫存或還原變更:

  • 整份差異:使用審查窗格頂端的操作按鈕,例如全部暫存或全部還原。
  • 個別檔案:暫存、取消暫存或還原單一檔案。
  • 個別差異區塊:暫存、取消暫存或還原單一差異區塊。

要接受部分變更時,請將該部分暫存。要捨棄變更時,請將它還原。

已暫存與未暫存狀態

在 Git 中,同一個檔案可以同時包含已暫存和未暫存的變更。這時,審查窗格可能會在兩個檢視畫面中都列出同一個檔案。這是 Git 的正常行為。