InsForge/insforge-skills

InsForge Debug

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

1. 每個除錯基礎元件的參考 (每個一個可觀測面 — 位於 references/ 下)
2. 症狀食譜 (如下) 為已知的被動症狀和主動稽核命名了基礎元件序列

始終使用 npx -y @insforge/cli — 切勿全域安裝 CLI。

最快路徑：AI 輔助分診

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

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

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

除錯基礎元件

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

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

基礎元件 (命令)	您會看到的內容	參考文件
日誌 (logs <source>；diagnose logs 用於跨來源聚合)	來自 5 個後端來源 (insforge.logs / postgREST.logs / postgres.logs / function.logs / function-deploy.logs) 的時間事件串流	references/logs.md
指標 (diagnose metrics)	在 1h / 6h / 24h / 7d 時間範圍內的 EC2 執行個體時間序列 (CPU / 記憶體 / 磁碟 / 網路)	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)	宣告式後端狀態轉儲 (auth 配置 / 資料表 / 存儲桶 / 函式 / 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 "<描述>")	結合其他基礎元件的 LLM 代理 — 返回包含建議的診斷	references/ai-assisted.md

症狀食譜

每個食譜都是一個基礎元件呼叫序列，每個步驟都有一行「尋找 X」。命令語法、標誌和深入解讀請參閱上面每個基礎元件的參考文件。

食譜：SDK 返回 { data: null, error: { code, message } }

1. 錯誤物件 — 讀取 code/message/details。如果 code 以 PGRST* 開頭，則使用參考文件中的表格依前綴路由。
2. 日誌 (根據錯誤物件路由匹配來源) — 找到錯誤時間戳，獲取完整的後端端上下文。
3. 資料庫健康 (connections, locks, slow-queries) — 僅在錯誤暗示資料庫問題 (PostgREST 超時，鎖衝突) 時執行。

食譜：特定請求上的 HTTP 4xx/5xx 響應

1. 錯誤物件 — 使用 HTTP 狀態路由表選擇日誌來源 (每個狀態都有不同的路徑；429 是特殊的)。
2. 日誌 (該狀態的正確來源) — 找到失敗的請求行和錯誤。
3. 指標 — 僅針對跨多個端點的 5xx 模式，以確認系統範圍的負載問題。

食譜：RLS 存取問題 (寫入時 403，或讀取時空結果)

同一個錯誤，兩種呈現方式。寫入 (INSERT / UPDATE / DELETE) 會大聲失敗並出現 403。讀取 (SELECT) 會靜默失敗並回傳一個空陣列 — PostgREST 會過濾掉被拒絕的行，而不是返回 403，因此請求看似成功但結果為零行。診斷路徑相同，只是步驟 1 僅適用於 403 變體。

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

食譜：登入失敗 / OAuth 回調錯誤 / token 已過期

1. 日誌 (insforge.logs) — 找到帶有時間戳和提供者上下文的 auth 錯誤。
2. 中繼資料 — 驗證提供者已啟用，重定向 URL 與回調 URL 完全匹配 (協議 + 主機 + 路徑)。

食譜：邊緣函式執行階段錯誤 / 超時

1. 日誌 (function.logs) — 獲取錯誤堆疊和執行上下文。
2. 中繼資料 — 確認函式存在且 status: "active"。
3. (如有需要) npx -y @insforge/cli functions code <slug> — 檢查原始碼以找出明顯問題。

食譜：functions deploy 失敗

1. 部署狀態 (function-deploy.logs) — 找到建置/推送錯誤。
2. 中繼資料 — 確認該函式最終是否列入活躍清單 (部分部署檢測)。

食譜：deployments deploy 失敗 (Vercel)

1. 部署狀態 (deployments list + status <id> --json) — 讀取 status、metadata.webhookEventType 和 envVarKeys。
2. 本地端 npm run build — 在本地重現相同錯誤以加快迭代速度。

食譜：單一慢查詢 / 一個端點慢

1. 日誌 (postgres.logs) — 找到查詢文字和時間戳。
2. 資料庫健康 (slow-queries, index-usage) — slow-queries 僅在查詢仍在運行時 (大於 5 秒的快照) 捕獲它；檢查 index-usage 是否有缺少的索引。已經完成？顧問 (--category performance --json) 具有 pg_stat_statements 文字 + 平均時間；步驟 1 有時間戳。
3. 政策 — 如果它是一個受 RLS 保護的資料表，請驗證原則沒有添加隱藏的 JOIN。

食譜：「記憶體使用率約 80%，但沒有任何東西變慢」

1. 先說明這是預期行為。 專用 Postgres 執行個體會將閒置 RAM 變成共享緩衝區和頁面快取；當流量較少時，穩定的高記憶體使用率是健康狀態，而不是洩漏 (references/metrics.md，「記憶體：高是正常的」)。
2. 指標 (--range 24h) — 只有上升趨勢或 OOM 終止/重新啟動才會改變答案。OOM 的證據存在於 postgres.logs 中，顯示為崩潰復原的後果 ("terminating connection because of crash of another server process" / "automatic recovery in progress")。
3. 有 OOM 證據時，解決方案是增加資源：升級到付費方案並選擇更大的執行個體大小 (儀表板 → 專案設定 → Compute & Disk)。在實際負載下，最小執行個體上發生 OOM 是常見且預期中的情況 — 絕不要「重新啟動以釋放記憶體」。

食譜：所有響應都慢 / CPU 或記憶體高 (活躍事件)

1. 指標 (--range 1h) — 確認系統範圍的壓力 (CPU / 記憶體 / 磁碟)。
2. 資料庫健康 — 資料庫是最常見的瓶頸；檢查 connections、locks、slow-queries。
3. 日誌 (diagnose logs 聚合) — 在峰值時間戳處跨來源的錯誤模式。
4. 顧問 (--severity critical) — 可能解釋此效能下降的既有已知問題。

食譜：即時通道無法連接 / 訊息遺失

1. 日誌 (insforge.logs) — WebSocket 錯誤和訂閱失敗。
2. 中繼資料 — 驗證通道模式與客戶端訂閱的模式匹配，且 enabled: true。
3. 政策 — 底層資料表的 RLS (即時傳遞資料列變更；RLS 決定訂閱者能看到哪些資料列)。

食譜：429 速率限制

1. 錯誤物件 — 確認 429 狀態。不會記錄 429 的日誌；不會返回 Retry-After 標頭。 不要浪費時間搜尋日誌。
2. 指標 (--range 1h) — 整體後端負載上下文。
3. 解決方案總是客戶端端：去抖、批次處理、指數退避、消除重試迴圈。

食譜：特定 URL 上的閘道逾時 (502 / 503 / 504)

在深入挖掘之前，先根據 URL 子系統進行路由：

URL 模式	深入檢查
/api/database/records/...	日誌 (postgREST.logs → postgres.logs) + 資料庫健康 (locks, slow-queries)
/functions/<slug>	日誌 (function.logs) — 函式可能正在崩潰循環
/api/auth/...	日誌 (insforge.logs)
系統範圍峰值期間的任何路徑	指標 (--range 1h)

小型執行個體上跨不相關路徑的 504：首先懷疑 OOM。 同時衝擊資料庫、auth 和函式的間歇性閘道逾時，是小型執行個體上典型的記憶體不足特徵：核心終止 Postgres，在崩潰復原運行期間每個進行中的請求都在閘道處逾時，並且在下一次負載峰值時重複。

快速路徑：npx -y @insforge/cli diagnose incident (需要平台登入)。該報告完全在雲端端建置 — Prometheus 抓取歷史、平台記錄、對外資料庫探測 — 因此即使在執行個體關閉或卡住時也能運作，這正是 diagnose logs 停止回應的時候。它會返回一個裁決 (oom_likely、platform_operation_in_progress、paused_or_suspended、metrics_stopped、down_unknown、no_incident_detected) 以及證據和建議操作；oom_likely 已經表示平台端已完成下面的重新啟動/記憶體關聯檢查。

如果命令不可用 (較舊的 CLI/後端、--api-key 連結模式)，請透過日誌 (postgres.logs) 中的崩潰復原後果手動確認 — "terminating connection because of crash of another server process" / "automatic recovery in progress" — 與 5xx 突發時間相關聯：僅有復原證據只能證明 Postgres 非正常重新啟動，因此時間戳必須吻合，OOM 才能成為首要診斷 (references/metrics.md)。有了該證據，解決方案是增加資源，而不是重試循環：

1. 升級執行個體 — npx -y @insforge/cli projects upgrade-instance <type> (nano → micro → small → medium → large → xl)，或儀表板 → 專案設定 → Compute & Disk。在免費方案上，先升級到付費方案，然後選擇大小。調整大小會更改帳單，CLI 會要求互動式確認 — 先獲得使用者的許可，然後使用 CLI 層級的 --yes ( npx -y 中的 -y 是 npm 的安裝標誌，而不是跳過確認) 以非互動模式運行。調整大小是非同步的 — 輪詢 projects get 直到 operation_status 清除，才能宣告事件已解決。
2. 調整大小會作為變更的一部分重新啟動專案，這也會清除任何卡住的狀態 — 沒有單獨的面向使用者的重新啟動，單純的重新啟動只能在下一次峰值 OOM 之前爭取幾分鐘時間。在最小尺寸上，實際負載下的 OOM 是常見且預期中的，而不是一個 Bug。

食譜：上線前 / 主動稽核

需要平台登入 (npx -y @insforge/cli login)。當專案透過 --api-key 連結時不可用 — 在這種情況下，請退回到 db-health + policies + metadata 進行手動稽核。

1. 顧問 — 完整掃描，然後先檢查 --severity critical，再檢查警告。
2. 顧問 (--category security) — 專注於安全問題；與政策 (RLS 覆蓋率) 和中繼資料 (auth 配置、公開存儲桶、secret 存在與否) 交叉驗證。
3. 顧問 (--category performance) — 與資料庫健康 (slow-queries、index-usage、bloat) 交叉驗證。
4. 顧問 (--category health) — 與指標 (超過 7d 的資源趨勢) 交叉驗證。
5. 修復後，重新運行顧問，並確認每個已處理的 ruleId 的 isResolved: true。

食譜：不知從何著手

1. AI 輔助 (diagnose --ai "<錯誤或 URL>") — 獲得一個起點假設。
2. 通過重新檢查診斷所命名的基礎元件來驗證。相信基礎元件的觀察結果，而不是建議。

當根本原因是 InsForge 本身

有些診斷最終歸結於 InsForge 端的缺陷，而不是專案配置錯誤：平台錯誤或回歸、行為異常的 SDK 呼叫、與觀察到的行為相矛盾的文件或技能、或缺少的功能。除錯會話正是確認這些問題的地方 — 在證據確鑿時報告它們：

npx -y @insforge/cli feedback --json \
  --type bug --component backend --area db \
  --title "<一行摘要>" \
  --detail "<預期行為 vs 實際行為，最小化重現步驟>" \
  --command "<失敗的呼叫>" \
  --error "<來自日誌的逐字錯誤>"