astroidal 是做什麼的？
Astroidal 是 AI 程式碼審查地圖、評分器與輔助工具。它繪製變更影響範圍，並對你能證明的事項進行評分。對應變更、搜尋真實錯誤，然後對發現進行排名。圖表與表格儲存在檔案中。聊天回覆是一段簡潔的散文摘要，可供使用者直接貼上。
錯誤目錄位於references/review-lenses.md，與此檔案相鄰。在判斷發現之前，請先閱讀該目錄。它不在 .astroidal/ 中。
請勿將 Astroidal 加入專案依賴。請勿編輯 package.json、鎖定檔案、pyproject.toml、go.mod 或 Cargo.toml 來安裝它。
執行方式
依下列順序解析指令：
- 如果
astroidal已在PATH中，則直接使用 - 否則使用
npx --yes astroidal
如果套件名稱無法下載，且使用者指向本機簽出版本，請執行 npx --yes <astroidal-套件路徑> 或 node <路徑>/dist/cli.js。
每個儲存庫安裝一次 skill：
npx --yes astroidal init
加上 --global 參數可為此機器上的所有儲存庫安裝一次：
npx --yes astroidal init --global
全域安裝會在較新版本的 Astroidal 執行 graph 或 rank 時自動更新，前提是這些 skill 檔案仍為 Astroidal 所寫。已編輯過的 skill 會保留不變，直到使用 init --force。再次執行 init 可重新整理專案安裝。
選擇範圍
執行一次 graph。閱讀它印出的範圍說明。如果範圍錯誤，請使用下方的旗標再執行一次。之後請勿重複執行。
| 要求 | 指令 |
|---|---|
| 目前的編輯，包含未追蹤的檔案 | npx --yes astroidal graph |
| 此分支或其合併請求（當工作目錄有未提交變更時） | npx --yes astroidal graph --base <預設分支> |
| 一個乾淨的功能分支 | npx --yes astroidal graph |
| 合併請求編號或 URL | npx --yes astroidal graph --pr 12,18,24 |
| 所有開啟中的合併請求 | npx --yes astroidal graph --open |
| 依作者、標籤或基底分支篩選開啟中的合併請求 | npx --yes astroidal graph --open --author 名稱 --label 標籤 --base 分支 |
| 目前的合併請求及其下方的堆疊 | npx --yes astroidal graph --stack |
| 一個提交 | npx --yes astroidal graph --commit SHA |
| 僅暫存的變更 | npx --yes astroidal graph --staged |
| 未暫存的變更與未追蹤的檔案 | npx --yes astroidal graph --unstaged |
批次處理為一個合併地圖。請勿將合併請求視為獨立報告進行審查。
GitHub
僅在需要時呼叫 gh 來獲取審查所需的額外資訊。地圖已經完成本地優先的讀取，因此請勿再次列出相同的檔案、重新獲取已儲存的差異，或輪詢檢查狀態。少量針對性的呼叫是可以的，例如當標題、基底或內文缺失時使用 gh pr view。請勿濫用 gh，也請勿對合併請求發表評論、核准或請求審查者。
GitLab
僅在需要時呼叫 glab 來獲取審查所需的額外資訊。地圖已經完成本地優先的讀取，因此請勿再次列出相同的檔案、重新獲取已儲存的差異，或輪詢管線狀態。少量針對性的呼叫是可以的，例如當標題、基底或內文缺失時使用 glab mr view。請勿濫用 glab，也請勿對合併請求發表評論、核准或請求審查者。
搜尋錯誤
依序閱讀：
.astroidal/packets/bug-map.md.astroidal/packets/architecture.md.astroidal/packets/security.md.astroidal/packets/performance.md.astroidal/packets/ux.md.astroidal/packets/correctness.md- 與此 skill 相鄰的
references/review-lenses.md
套用目錄中的閘門（gate）、規格檢查（spec pass）與標準檢查（standards pass）。然後套用每個與 Added lines 中檔案匹配的語言章節。跳過其他語言章節。
涵蓋錯誤地圖中的每個變更路徑。從 Added lines 區段開始。該區段代表變更，每個合併請求一個區塊。當差異是遠端獲取時，符號摘要可能為空白；在堆疊情況下，它只顯示頂端。空白的摘要表示缺少上下文，並非空白變更。
請勿在找到第一個看似有問題的檔案後就停止。針對 Added lines 中每個非測試的原始碼區塊：
- 閱讀整個區塊，包含當區塊指出後續行數位於證據檔案中時，位於其下方的行數。
- 根據目錄檢查該區塊，而不僅是根據與檔名匹配的類別。以下五個類別是最低要求。
- 當一個檔案列出多個合併請求時，請分別審查每個區塊。地圖中映射的主體僅為堆疊頂端。
- 當區塊不足以確認或排除錯誤時，開啟該檔案。
- 對於每個變更過的符號，檢查地圖列出的一級呼叫者與被呼叫者，如果變更可能破壞它們。
特別注意：錯誤的分支、被視為缺失的 falsy 或空值、差一錯誤或時區不匹配、在失敗後阻止重試的鎖定或狀態、透過字串拼接建立的 URL 或查詢、使用了錯誤身分的授權檢查，以及一級呼叫者仍在使用舊方式的合約。高影響分數並非發現，也不能作為跳過區塊的理由。
搜尋所有這些類別：
- 邏輯與邊界情況：錯誤分支、差一錯誤、被吞沒的錯誤、空值崩潰
- 資料遺失與狀態：遷移、競爭條件、部分寫入、過期快取
- 損壞的合約：API、型別、路由、導出行為、結構描述不匹配
- 安全性錯誤：授權缺口、注入、機密、不安全的信任邊界
- UX 流程錯誤：死路、遺失的錯誤/空/載入狀態、損壞的導航
尋找重要的問題。封包中的線索是提示，而非發現。程式碼氣味、過長的檔案、缺少測試或依賴升級，只有在目錄的閘門通過時才算是發現。忽略格式、命名、註解、讚美、問題，以及未指出具體失敗的重構。
撰寫發現
寫入 .astroidal/findings.json：
{
"findings": [
{
"pr": 12,
"severity": "high",
"description": "什麼功能會壞掉，用一兩句話說明。",
"path": "src/auth.ts",
"line": 12,
"quote": "從檔案中複製的準確行內容",
"recommendation": "能移除該錯誤的具體變更。",
"category": "security"
}
]
}
severity 可為 critical、high 或 medium，使用目錄中的閘門。critical 表示在使用者路徑上的崩潰、資料遺失、授權繞過、注入或機密暴露。high 表示實際的錯誤結果、遺失的寫入、競爭條件或損壞的合約。medium 表示實際的邊界情況失敗。quote 是從 added-lines 區塊、映射檔案或其鄰近檔案中複製的一行準確內容。將 pr 設為引入該行內容的合併請求編號，若為本地變更則省略。
說明什麼會壞掉，指出符號名稱，並給出能移除該錯誤的變更。對於安全性與架構，解釋為何該變更有效。請勿含糊其辭、重複引用的行內容，或提出問題。只有在檢查過所有非測試原始碼檔案的 added lines 區塊，且其中沒有任何重要錯誤時，才允許使用空的 findings 陣列。
當變更過的檔案因為某個目錄未顯示的原因而歸屬於同一組時，請命名該群組。圖表會單獨繪製目錄，並將匯入關係繪製為連線。群組用於跨越這些界線的流程、功能或共享合約。
{
"findings": [],
"groups": [
{
"name": "付款連結",
"paths": ["apps/admin/lib/whatsapp.ts", "apps/admin/lib/proxied-link.ts"]
}
]
}
使用簡短的名稱，並包含至少兩個已映射的路徑。當沒有額外的檔案需要歸為同一組時，請省略 groups。
接著執行：
npx --yes astroidal rank
如果 rank 因為引用的行內容或路徑錯誤而丟棄某個發現，請修正該發現一次後再次執行 rank。請勿為了維持數量而發明替代的錯誤。請勿執行 rank 三次。
回覆
在聊天中撰寫一段簡潔的散文摘要。以一句可供使用者直接貼上的開頭句開場：Astroidal {分數} · Passed 或 Astroidal {分數} · Fix first。然後指出最高嚴重性的問題，以及兩個輸出檔案路徑：.astroidal/review.md 和 .astroidal/constellation.html。請勿貼上發現表格。請勿重新建立圖表。最終合併與否仍由人類決定。