InsForge/insforge-skills

InsForge Debug

通过结合后端的可观测性原语——日志、指标、数据库健康、顾问、策略、元数据、错误对象、部署状态和 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 ... 运行。每个原语旁显示的 (命令) 是实际的 CLI 命令——原语名称是概念标签，不是 CLI 子命令名称（例如，“DB 健康”是 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)	EC2 实例时间序列（CPU / 内存 / 磁盘 / 网络）覆盖 1h / 6h / 24h / 7d	references/metrics.md
DB 健康 (diagnose db)	当前 Postgres 状态，通过 7 项命名检查（connections / slow-queries / bloat / size / index-usage / locks / cache-hit）	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. 错误对象——读取 code/message/details。如果 code 以 PGRST* 开头，按照参考中的表格按前缀路由。
2. 日志（根据错误对象路由匹配的源）——找到错误时间戳，获取后端侧的完整上下文。
3. db-health (connections, locks, slow-queries)——仅当错误暗示 DB 问题时（PostgREST 超时、锁冲突）。

配方：特定请求的 HTTP 4xx/5xx 响应

1. 错误对象——使用 HTTP 状态路由表选择日志源（每个状态有不同路径；429 特殊）。
2. 日志（该状态对应的正确源）——找到失败的请求行和错误。
3. 指标——仅用于跨多个端点的 5xx 模式，以确认系统级负载问题。

配方：RLS 访问问题（写入时 403，或读取时为空结果）

同一 bug，两种表现。写入 (INSERT / UPDATE / DELETE) 会以 403 明确失败。读取 (SELECT) 会以空数组静默失败——PostgREST 将拒绝的行过滤掉，不返回 403，因此请求看起来成功了但返回零行。诊断路径相同，只是步骤 1 仅适用于 403 变体。

1. 日志 (postgREST.logs)——仅 403 变体: 找到策略违规事件，包含表和角色上下文。空结果变体: 跳过——静默过滤的行不会记录错误。
2. 策略——列出该表的策略；对照实际请求和使用的 JWT 声明检查 USING / WITH CHECK。
3. 元数据——验证认证配置（哪个声明提供 auth.uid() / requesting_user_id()；对于第三方认证如 Clerk/Auth0，该提供商是否注册为 JWT 签发者？）。
4. DB 查询 (db query "<sql>")——仅空结果变体: 通过以服务角色（而非用户）查询确认应该可见的行实际存在：npx -y @insforge/cli db query "SELECT id, user_id FROM <table>"。区分“RLS 过滤了所有内容”与“没有匹配数据存在”。

配方：登录失败 / OAuth 回调错误 / token 过期

1. 日志 (insforge.logs)——找到带有时间戳和提供商上下文的认证错误。
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. db-health (slow-queries, index-usage)——slow-queries 仅在查询仍在运行时捕获（>5s 快照）；检查 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 证据时，修复方法是增加空间：升级到付费套餐并选择更大的实例大小（控制台 → 项目设置 → 计算与磁盘）。在真实负载下，最小实例上的 OOM 是常见且预期的——永远不要“重启以释放内存”。

配方：所有响应慢 / CPU/内存高（活跃事件）

1. 指标 (--range 1h)——确认系统级压力（CPU / 内存 / 磁盘）。
2. db-health——DB 是最常见的瓶颈；检查 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) + db-health (locks, slow-queries)
/functions/<slug>	日志 (function.logs)——函数可能崩溃循环
/api/auth/...	日志 (insforge.logs)
系统级峰值期间的任何路径	指标 (--range 1h)

小实例跨不相关路径的 504：首先怀疑 OOM。 间歇性网关超时同时影响数据库、认证和函数，是小实例尺寸上经典的内存不足特征：内核杀死 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），或控制台 → 项目设置 → 计算与磁盘。在免费计划上，先升级到付费套餐，然后选择大小。调整大小会更改账单，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 覆盖范围）和 元数据（认证配置、公共存储桶、密钥存在性）交叉验证。
3. 顾问 (--category performance)——与 db-health (slow-queries, index-usage, bloat) 交叉验证。
4. 顾问 (--category health)——与 指标（7d 内的资源趋势）交叉验证。
5. 修复后，重新运行 顾问 并确认每个已处理的 ruleId 的 isResolved: true。

配方：不知从何下手

1. AI 辅助 (diagnose --ai "<错误或 URL>")——获取初始假设。
2. 验证——重新检查诊断中提及的原语。信任原语的观察结果胜于建议。

当根因是 InsForge 自身时

一些诊断最终归结于 InsForge 侧的缺陷，而非项目配置错误：平台 bug 或回归、表现异常的 SDK 调用、与观察到的行为矛盾的文档或技能、或缺少的功能。调试会话正是确认这些问题的时机——趁证据在手时报告：

npx -y @insforge/cli feedback --json \
  --type bug --component backend --area db \
  --title "<一行摘要>" \
  --detail "<发生了什么 vs 预期，最小复现>" \
  --command "<失败的调用>" \
  --error "<来自日志的逐字错误>" \
  [...]

报告后，提供临时缓解措施（切换到不同查询、重启客户端、禁用特定功能），并告知用户该问题在平台侧跟踪。