lakeday-org/perch

perch – AI 驅動的語意程式碼 lint

是什麼 – perch 是一個命令列工具，掃描原始碼並報告 語意 缺陷（例如：呼叫順序錯誤、偏移 1 錯誤、環境變數誤用）。分析由 TypeSafe 的大型語言模型服務（透過 API 金鑰存取）驅動。它超越語法檢查器，讓模型推理每個方法的意圖，並根據置信度排序發現結果。

如何運作

• perch scan 遍歷專案，建立函數／方法的圖形結構，並向 LLM 發送簡潔的「問題」。模型回傳某個模式是缺陷的機率；perch 將其轉換為嚴重性分數（P1、P2、…），並列印出表格。
• 結果快取於隱藏的 .perch/ 資料夾中，因此重複執行速度很快。
• 你可以查詢清單（perch issues），深入查看單一發現（perch issues <id>），並在修復後重新檢查（perch check <id>）。

擴充方式 – 自訂規則以簡單的 YAML 格式撰寫（perch.yaml 或 .perch/rules/ 下的檔案）。規則指定：

• where – 檔案通配符模式
• each – 精細度（method、function 等）
• min – 顯示問題所需的最低置信度
• ensure – 所需行為的自然語言描述

助理整合 – perch 可為各種 LLM 助理（Claude、Codex、Pi、Cursor）安裝「技能」。perch setup <assistant> 命令會產生一個 Markdown 檔案，其中包含助理可用於建議修復的提示。

快速上手

npm install -g @lakeday/perch
export PERCH_API_KEY=$(cat ~/.perch_key)   # 從 console.typesafe.ai 取得
perch scan

CLI 會列印出問題清單、置信度以及發現位置的方法名稱。

典型工作流程

1. 在本地或 CI 中執行 perch scan。
2. 使用 perch issues 審查嚴重性最高的項目。
3. 修復程式碼後，執行 perch check <id> 驗證問題是否已解決。
4. 透過向 .perch/closed.jsonl 新增項目來忽略誤報。

文件與生態系 – 完整文件托管於 https://docs.perchscan.com，涵蓋安裝、規則語言、CI 整合與內部「圖形遍歷」。專案發布於 npm（@lakeday/perch），包含 CI 標籤、類型檢查與單元測試。

成熟度 – 倉儲提供穩定 CLI、自動化測試與 CI。它需要外部 API 金鑰，因此核心分析依賴 TypeSafe 服務，但周邊工具（規則引擎、快取、CI 整合）為開源。

授權 – MIT（參見 LICENSE）。

---

Perch 是一個真正的 AI 增強型 lint 平台，專為希望獲得更高層次、模型驅動的程式碼品質檢查，而無需撰寫自訂提示的開發者設計。