repo-radar

repo-radar 是做什麼的？

儀表板是一個 HTML 檔案，由 scripts/dashboard.py 從 GitHub 抓取資料繪製而成。 需要 Python 3.10+、PyYAML 和已登入的 GitHub CLI (gh)。其中不呼叫任何 AI，因此可以每天早上在 GitHub Action 中免費重建。

其分頁如下：

分頁	顯示內容
計劃	僅在倉庫有計劃檔案時顯示。系統的每個部分以方塊呈現，顯示擁有者、哪些項目已建立、審查中或遺失。標記 PR 已合併或關閉的項目，以及未指向任何項目的開放 PR。
拉取請求	開放 PR 按需求排序：準備合併、需要審查、等待作者、檢查失敗、草稿。「從這裡開始」最多選五個。
問題	開放問題：無人處理、有人被指派、已有相關 PR。
圖表	開放工作之間的連結關係：計劃方塊 → 問題 → PR、子問題、「受阻於」、基於其他 PR 分支的 PR。
已完成	過去 90 天內關閉的 PR 和問題，依發布版本分組。

有兩種設定方式。如果不確定，請詢問使用者想要哪一種：

方式	適用對象	新增內容與位置
在單一倉庫中 (init)	正在該倉庫工作的人	在該倉庫中新增每日 Action，建置該倉庫的頁面
監看清單 (init --watch)	需要同時關注多個倉庫的人，例如管理者或教師	在自己的一個倉庫中新增每日 Action，為每個被監看的倉庫建置一個頁面，外加總覽頁面。被監看的倉庫不會有任何變動

以下 SCRIPT 指的是此技能資料夾中的 scripts/dashboard.py，或是已執行過 init 的倉庫中的 .github/dashboard/dashboard.py。

計劃檔案（可選）

計劃列出系統所需的項目，這是 GitHub 無法知道的：例如尚未有人開立 Issue 或 PR 的部分。完整格式位於 scripts/dashboard_plan.py 頂端，templates/plan.yaml 是入門範本。簡而言之：由群組構成，每個群組包含多個方塊，每個方塊是一個項目列表，每個項目的狀態為 built、simulated、pr（附編號）或 missing。方塊可以有 owner，或繼承其所屬群組的擁有者。預設位置是 docs/plan.yaml；可透過 --plan 參數指定其他路徑。

規則

1. 先回報，僅在被要求時才編輯。 腳本絕不編輯計劃。僅在使用者要求你將他們的拉取請求加入計劃時才編輯。
2. 僅編輯使用者自己的項目。 不要碰其他人的項目和 as_of 行。開放拉取請求時，不要所有人都編輯同一行。
3. 不要標記項目為 built，除非使用者執行每週更新。 由一個人每週一次，在 PR 合併後進行。請改說「已合併，準備進行每週更新」。
4. 絕不憑空捏造狀態。 只有當一個開放的拉取請求正在進行該工作時，項目才應設為 pr。當你無法判斷某個拉取請求屬於哪個方塊時，請詢問。
5. 絕不將 HTML 頁面提交到主要分支。 每日 Action 將其保留在獨立的 dashboard 分支上。手動建置的頁面應放在倉庫外部的臨時資料夾（以下簡稱 <scratch dir>）。

在倉庫中設定

在開始寫任何東西之前，一次問清楚：

• 團隊是否想要計劃？如果要，放在哪裡（預設 docs/plan.yaml），以及是否已存在？任何符合上述格式的檔案都可以，因此可以保留現有檔案。
• 希望在什麼時間重建？Action 使用 UTC 時間；預設為每日 11:00 UTC。

然後，在倉庫的頂層資料夾執行：

python SCRIPT init                                   # 腳本 + 每日 Action
python SCRIPT init --with-plan                       # ... 和一個入門的 docs/plan.yaml
python SCRIPT init --plan path/to/plan.yaml          # ... 使用既有的計劃

init 會寫入 .github/dashboard/（腳本）和 .github/workflows/dashboard.yml，並且會拒絕覆蓋已存在的檔案。然後：

1. 在本機建置一次頁面（下一節），並展示給使用者看，讓他們確認可以運作。
2. 如果你寫了入門計劃，請與使用者一同填寫：群組、方塊、擁有者，以及一個 people 列表，將每個擁有者名稱對應到他們的 GitHub 登入帳號。
3. 告訴他們要提交哪些檔案（init 寫入的檔案，以及計劃檔案），並說明一旦這些檔案到達預設分支，他們就可以立即從 Actions 分頁執行（「Dashboard」，然後「Run workflow」）。
4. 告訴他們每天早上如何查看： git fetch origin dashboard && git show origin/dashboard:index.html > dashboard.html， 然後開啟 dashboard.html。對於公開倉庫，他們也可以為 dashboard 分支開啟 GitHub Pages，以獲得一個網址。

如果 Action 因為「權限不足」而無法推送，表示該倉庫或組織限制了 Action 的權限：設定 → Actions → 一般 → 工作流程權限，改為「讀取和寫入」。由使用者（不是你）來更改此設定。

設定監看清單（多個倉庫）

一次問清楚：要監看哪些倉庫（格式為 owner/name）、是否有任何倉庫的計劃檔案不在 docs/plan.yaml、要用哪個自己的倉庫來存放監看清單（一個新的空倉庫也可以），以及希望在什麼時間重建（UTC）。

在開始寫任何東西之前，先建置一次頁面讓使用者看到效果：

python SCRIPT watch --list <scratch dir>/watchlist.yaml --out <scratch dir>/radar

開啟該資料夾中的 index.html。無法讀取的倉庫會在其行上顯示錯誤訊息，而不會影響其他倉庫：通常是名稱打錯，或是私有倉庫。

然後，在要存放清單的倉庫中：

python SCRIPT init --watch            # 腳本、watchlist.yaml 和 .github/workflows/radar.yml

將使用者的倉庫寫入 watchlist.yaml，然後告訴他們：

1. 要提交哪些檔案（init --watch 寫入的檔案），並說明一旦這些檔案到達預設分支，他們就可以立即從 Actions 分頁執行（「Radar」，然後「Run workflow」）。
2. 私有倉庫需要 Token。 Action 可以讀取公開倉庫和自己的倉庫，除此之外無法讀取其他倉庫。若要監看私有倉庫，使用者需要建立一個有讀取權限的 GitHub Token，並將其儲存為監看倉庫中的密碼，命名為 RADAR_TOKEN（設定 → Secrets and variables → Actions）。他們必須自己操作；絕對不要向他們索取 Token 或將其貼到任何地方。
3. 如何每天早上查看： mkdir -p radar && git fetch origin dashboard && git archive origin/dashboard | tar -x -C radar， 然後開啟 radar/index.html。

之後若要新增或移除倉庫，只需編輯 watchlist.yaml；無需更改其他檔案。

更新倉庫中的腳本副本

init 會將腳本複製到倉庫中，因此倉庫會一直使用它取得的那個版本，直到有人更新它。當使用者要求在某個倉庫中更新 repo-radar，或者此技能的腳本比倉庫中的版本更新時，請在該倉庫的頂層資料夾執行：

python scripts/dashboard.py update        # 使用此技能的複本，而非 .github/dashboard/ 的

它只會取代 .github/dashboard/ 中的腳本，並顯示哪些檔案已變更。Action、監看清單和計劃維持不變。然後告訴他們要提交 .github/dashboard/。

立即查看

python SCRIPT build --out <scratch dir>/dashboard.html

在倉庫內執行該命令（或傳入 --repo owner/name）。將頁面寫入倉庫外部的臨時資料夾，這樣它就不會被提交，然後展示給使用者看。用白話文解釋內容，從「從這裡開始」卡片和「計劃」分頁上的任何黃色標籤開始。每個數字都要精確說明：「16 個開放的拉取請求中有 12 個需要審查」，而不是「12 個需要審查」。

我在哪裡（單一個人，對照計劃）

你需要兩個名稱：計劃中使用的擁有者名稱，以及GitHub 登入帳號。如果計劃的 people 列表中有 gh 目前登入的帳號，腳本會自行找出名稱。否則請詢問，並傳入 --owner "<名稱>"。只有當使用者問到其他人時，才需要傳入 --login。

當使用者在某個拉取請求的分支上時，請執行兩次。main 分支顯示團隊今天看到的狀態；目前的分支則顯示此拉取請求將會改變什麼：

git fetch origin
python SCRIPT me --ref origin/main
python SCRIPT me

報告包含四個表格：

表格	告訴使用者的資訊
你的方塊	對於他們擁有或有 PR 的每個方塊：有多少項目是 built、simulated、在 PR 中、missing
仍遺失的項目	他們的下一個工作，逐個方塊說明
標記為 pr 的項目（與 GitHub 比對）	開放的 PR 不需要做任何事。已合併的 PR 準備進行每週更新。已關閉但未合併的 PR 表示該項目應恢復為 missing
你沒有在計劃上對應項目的開放 PR	計劃尚未顯示的工作

按此順序解釋：已完成和審查中的項目；計劃遺漏了哪些 PR，以及每個 PR 可能屬於哪個方塊；任何 PR 已關閉但未合併的項目；第一個遺失的項目作為可能的下一項任務。

將拉取請求加入計劃（僅在被要求時）

在使用者的拉取請求分支上工作，而不是在 main 分支。

1. 找出拉取請求編號：gh pr view --json number,title。
2. 找出該拉取請求要建置的項目。閱讀計劃中使用者的方塊。
   • 如果已有項目描述該工作，將其狀態改為 pr 並加上 pr: <編號>。
   • 如果沒有項目，則在正確的方塊中新增一個：{status: pr, pr: <編號>, text: "<它建置的內容>"}。 text 應保持簡短明瞭。如果不確定該放在哪個方塊，請詢問使用者。
3. 檢查計劃是否仍可正常載入：python SCRIPT build --out <scratch dir>/check.html。 如果載入失敗，它會顯示錯誤訊息並指出問題所在。
4. 再次執行 me。拉取請求現在應該出現在「標記為 pr 的項目」下，而不是「沒有在計劃上對應項目的開放 PR」。
5. 在使用者的拉取請求中提交計劃檔案。

每週更新（僅由執行此操作的人進行）

在 main 分支上建置頁面，或對每個擁有者執行一次 me --ref origin/main。然後，在一個拉取請求中：

• 將所有 PR 已合併的項目標記為 built，如果合併的工作是存根、模擬或骨架，則標記為 simulated。「計劃」分頁會將這些項目標記為「已合併」。
• 將所有 PR 已關閉但未合併的項目恢復為 missing。
• 在拉取請求描述中列出所有沒有對應計劃項目的開放 PR（即「計劃」分頁的最後一個區塊），讓其擁有者自行放置。不要猜測它們的方塊。
• 將 as_of 設為你檢查時所用的 main 分支提交和日期。

無網路連線時

python SCRIPT fetch --out data.json 會儲存 GitHub 回傳的資料；之後可以使用 build --data data.json 和 me --data data.json 離線工作。測試也是用這個方式。