insforge-debug

InsForge Debug

結合後端可觀測性基礎元件 — 日誌、指標、資料庫健康、顧問、政策、中繼資料、錯誤物件、部署狀態與 AI 輔助，診斷 InsForge 專案問題。此技能提供：

1. 每個除錯基礎元件的參考（每個可觀測性面向一個 — 位於 references/ 下）
2. 症狀配方（如下）針對已知的反應式症狀與主動稽核，指定基礎元件的使用順序

一律使用 npx @insforge/cli — 切勿全域安裝 CLI。

最快路徑：AI 輔助分流

當使用者提供具體描述（錯誤訊息、失敗的 URL、HTTP 狀態碼）時，將其交給 InsForge 除錯代理。與其他基礎元件不同，此元件會回傳建議，而不只是觀察結果 — 在採取行動前，請根據其引用的基礎元件驗證診斷結果。

npx @insforge/cli diagnose --ai "<問題描述>"

請參閱 references/ai-assisted.md 了解何時優先使用此方法、何時跳過，以及如何驗證輸出。

除錯基礎元件

每個基礎元件都是一個可獨立查詢的可觀測性面向，由不同的底層資料來源支援。真正的診斷是基礎元件的組合。

所有指令皆透過 npx @insforge/cli ... 執行。每個基礎元件旁顯示的 (command) 是實際的 CLI 指令 — 基礎元件名稱是概念標籤，不是 CLI 子指令名稱（例如，「資料庫健康」是 diagnose db，不是 diagnose db-health；「政策」是 db policies，不是 diagnose policies）。

基礎元件 (command)	你會看到的內容	參考文件
日誌 (logs <source>；diagnose logs 用於跨來源彙總)	來自 5 個後端來源的時間序列事件（insforge.logs / postgREST.logs / postgres.logs / function.logs / function-deploy.logs）	references/logs.md
指標 (diagnose metrics)	EC2 執行個體時間序列（CPU / 記憶體 / 磁碟 / 網路）在 1h / 6h / 24h / 7d 範圍內	references/metrics.md
資料庫健康 (diagnose db)	透過 7 項命名檢查（connections / slow-queries / bloat / size / index-usage / locks / cache-hit）查看目前 Postgres 狀態	references/db-health.md
顧問 (diagnose advisor --json)	跨 3 個類別（security / performance / health）的靜態掃描問題，附帶 ruleId / affectedObject / recommendation	references/advisor.md
政策 (db policies)	來自 pg_policies 的活躍 RLS 規則（每個指令每個角色的 USING / WITH CHECK）— 以傾印形式回傳所有政策	references/policies.md
中繼資料 (metadata --json)	宣告式後端狀態傾印（驗證設定 / 資料表 / 儲存桶 / 函式 / AI 模型 / 即時頻道）	references/metadata.md
錯誤物件（無指令 — 讀取 SDK / HTTP 回應）	SDK 錯誤封包 + HTTP 狀態碼 — 從客戶端可見錯誤到正確日誌來源的路由表	references/error-objects.md
部署狀態 (deployments list + deployments status <id> --json + logs function-deploy.logs)	前端（Vercel）部署歷史 + 每個部署的中繼資料，以及邊緣函式部署日誌	references/deploy-state.md
AI 輔助 (diagnose --ai "<description>")	結合其他基礎元件的 LLM 代理 — 回傳附帶建議的診斷結果	references/ai-assisted.md

症狀配方

每個配方都是一個基礎元件呼叫序列，每個步驟附帶一行「尋找 X」的說明。指令語法、旗標與深入解讀請參閱上方每個基礎元件的參考文件。

配方：SDK 回傳 { data: null, error: { code, message } }

1. error-objects — 讀取 code/message/details。如果 code 以 PGRST* 開頭，使用參考文件中的表格依前綴路由。
2. logs（根據 error-objects 路由比對來源）— 找到錯誤時間戳，取得完整的後端端上下文。
3. db-health（connections、locks、slow-queries）— 僅當錯誤暗示資料庫問題時（PostgREST 逾時、鎖衝突）。

配方：特定請求的 HTTP 4xx/5xx 回應

1. error-objects — 使用 HTTP 狀態碼路由表選擇日誌來源（每個狀態碼有不同路徑；429 是特例）。
2. logs（該狀態碼的正確來源）— 找到失敗的請求行與錯誤。
3. metrics — 僅用於跨多個端點的 5xx 模式，以確認系統層級的負載問題。

配方：RLS 存取問題（寫入時 403，或讀取時空結果）

同一個錯誤，兩種表現。寫入（INSERT / UPDATE / DELETE）會大聲失敗並回傳 403。讀取（SELECT）會靜默失敗並回傳空陣列 — PostgREST 會過濾掉被拒絕的資料列，而不是回傳 403，因此請求看似成功但回傳零筆資料。診斷路徑相同，但步驟 1 僅適用於 403 變體。

1. logs（postgREST.logs）— 僅 403 變體：找到包含資料表與角色上下文的政策違規事件。空結果變體：跳過 — 靜默過濾的資料列不會記錄錯誤。
2. policies — 列出該資料表的政策；根據實際請求與使用的 JWT 宣告檢查 USING / WITH CHECK。
3. metadata — 驗證驗證設定（哪個宣告提供 auth.uid() / requesting_user_id()；對於第三方驗證如 Clerk/Auth0，該提供者是否註冊為 JWT 發行者？）。
4. db query（db query "<sql>"）— 僅空結果變體：以服務角色（而非使用者身分）查詢，確認應該可見的資料列確實存在：npx @insforge/cli db query "SELECT id, user_id FROM <table>"。區分「RLS 過濾了所有資料」與「沒有符合的資料存在」。

配方：登入失敗 / OAuth 回呼錯誤 / Token 過期

1. logs（insforge.logs）— 找到帶有時間戳與提供者上下文的驗證錯誤。
2. metadata — 驗證提供者已啟用，重新導向 URL 與回呼 URL 完全相符（協定 + 主機 + 路徑）。

配方：邊緣函式執行時期錯誤 / 逾時

1. logs（function.logs）— 取得錯誤堆疊與執行上下文。
2. metadata — 確認函式存在且 status: "active"。
3. （如有需要）npx @insforge/cli functions code <slug> — 檢查原始碼是否有明顯問題。

配方：functions deploy 失敗

1. deploy-state（function-deploy.logs）— 找到建置/推送錯誤。
2. metadata — 確認函式是否最終出現在活躍清單中（部分部署偵測）。

配方：deployments deploy 失敗（Vercel）

1. deploy-state（deployments list + status <id> --json）— 讀取 status、metadata.webhookEventType 與 envVarKeys。
2. 本地端 npm run build — 在本地重現相同錯誤以加快迭代。

配方：單一慢查詢 / 單一端點慢

1. logs（postgres.logs）— 找到查詢文字與時間戳。
2. db-health（slow-queries、index-usage）— 確認它出現在 pg_stat_statements 中；檢查是否缺少索引。
3. policies — 如果是受 RLS 保護的資料表，驗證政策是否未加入隱藏的 JOIN。

配方：所有回應都慢 / 高 CPU/記憶體（活躍事件）

1. metrics（--range 1h）— 確認系統層級壓力（CPU / 記憶體 / 磁碟）。
2. db-health — 資料庫是最常見的瓶頸；檢查 connections、locks、slow-queries。
3. logs（diagnose logs 彙總）— 在尖峰時間戳跨來源的錯誤模式。
4. advisor（--severity critical）— 可能解釋效能下降的既有已知問題。

配方：即時頻道無法連線 / 訊息遺失

1. logs（insforge.logs）— WebSocket 錯誤與訂閱失敗。
2. metadata — 驗證頻道模式與客戶端訂閱的內容相符，enabled: true。
3. policies — 底層資料表的 RLS（即時傳遞資料列變更；RLS 控制訂閱者能看到哪些資料列）。

配方：429 速率限制

1. error-objects — 確認 429 狀態碼。429 不會記錄日誌；也不會回傳 Retry-After 標頭。 不要浪費時間在日誌中搜尋。
2. metrics（--range 1h）— 整體後端負載上下文。
3. 修正永遠在客戶端：去抖動、批次處理、指數退避、消除重試迴圈。

配方：特定 URL 的閘道逾時（502 / 503 / 504）

根據 URL 子系統路由後再深入：

URL 模式	深入檢查
/api/database/records/...	logs（postgREST.logs → postgres.logs）+ db-health（locks、slow-queries）
/functions/<slug>	logs（function.logs）— 函式可能正在崩潰迴圈
/api/auth/...	logs（insforge.logs）
系統層級尖峰期間的任何路徑	metrics（--range 1h）

配方：上線前 / 主動稽核

需要 Platform 登入（npx @insforge/cli login）。當專案透過 --api-key 連結時無法使用 — 在這種情況下，請改用 db-health + policies + metadata 進行手動稽核。

1. advisor — 完整掃描，然後先看 --severity critical，再看警告。
2. advisor（--category security）— 專注於安全性問題；與 policies（RLS 覆蓋率）和 metadata（驗證設定、公開儲存桶、秘密是否存在）交叉驗證。
3. advisor（--category performance）— 與 db-health（slow-queries、index-usage、bloat）交叉驗證。
4. advisor（--category health）— 與 metrics（7d 內的資源趨勢）交叉驗證。
5. 修正後，重新執行 advisor 並確認每個已處理的 ruleId 顯示 isResolved: true。

配方：不知從何開始

1. ai-assisted（diagnose --ai "<error or URL>"）— 取得初步假設。
2. 驗證：重新檢查診斷結果中提到的基礎元件。相信基礎元件的觀察結果勝過建議。