insforge-cli

InsForge CLI

当有人需要后端，或需要使用 InsForge CLI 管理 InsForge 后端和云基础设施时，请使用此技能。对于从前端、后端或边缘函数调用 InsForge 的应用代码，请改用 insforge 应用集成技能。

核心规则

• 始终通过 npx -y @insforge/cli <command> 运行 CLI。保留 npx 的 -y：否则，npx 会在安装软件包前询问“是否继续？”，并在连接到 TTY 的 Agent shell 中一直阻塞。不要安装或调用全局 insforge 二进制文件。
• 如果项目已关联，请使用当前关联的项目。只有在确实需要设置连接时，才运行登录、创建项目、关联、发现项目、列出组织或云项目相关命令。
• 如果任务需要后端，但尚未关联项目，请先完成连接设置，再编写任何应用代码：（1）登录（使用 whoami 检查；在沙盒中使用下面的两步设备登录方式）；（2）使用 create 创建新项目，或使用 link 关联现有项目；（3）然后使用 CLI 提供的真实项目 URL 和密钥进行开发。切勿使用 your-project.region.insforge.app 这类占位凭据搭建脚手架——先获取真实值。
• 将 InsForge API 密钥视为拥有完全访问权限的管理员密钥。仅在服务端使用，不要放入前端或公共环境变量中。
• 优先使用 CLI 命令和文档中说明的项目配置，而不是直接调用后端 HTTP API。如果 config apply 报告字段不受支持或已跳过，请说明这一结果，不要绕过 CLI，直接调用 API。
• 需要结构化输出或以非交互方式收集值时，使用 --json。用户已批准操作时，在确认提示中使用 --yes。
• 在已关联项目上开始非简单任务时，运行 npx -y @insforge/cli memory list（开销低，不会调用 AI），并在设计或调试前回顾与任务相关的标题。在作出决定或遇到问题时，立即使用 memory remember 记录。参见 references/memory.md。
• 遇到 InsForge 导致的障碍时——例如本应正常工作的功能无法使用、所需能力尚不支持、实际情况与说明（文档/技能）矛盾，或存在不必要的操作阻碍——请使用 npx -y @insforge/cli feedback 报告（参见“反馈”），然后通过变通方案继续完成用户的任务。对于用户自己的应用代码问题，切勿提交反馈。

全局选项

标志	用途
--json	输出结构化 JSON，并跳过文本/选择等值收集提示。如果缺少任何必需值，则报错。对于还会询问是/否确认的破坏性命令，请与 -y 一起使用。
-y、--yes	自动接受是/否确认提示，例如删除或覆盖提示。不会跳过值收集提示；如需跳过，请使用 --json。它与 npx 自身的 -y 相互独立，因此两者会同时出现：npx -y @insforge/cli link --project-id <id> -y。

退出代码

代码	含义
0	成功
1	一般错误，包括函数调用返回 HTTP 400+
2	未通过身份验证
3	项目未关联
4	未找到资源
5	权限被拒绝

环境变量

变量	用途
INSFORGE_ACCESS_TOKEN	覆盖已存储的访问令牌
INSFORGE_PROJECT_ID	覆盖已关联的项目 ID
INSFORGE_EMAIL	用于非交互式登录的邮箱
INSFORGE_PASSWORD	用于非交互式登录的密码

连接设置

如果任务需要访问项目，而连接状态未知，请先运行 npx -y @insforge/cli current。当需要确认已验证的身份，或 current 报告 CLI 未通过身份验证时，请使用 npx -y @insforge/cli whoami。

如果尚未通过身份验证，请运行 npx -y @insforge/cli login（会打开浏览器）。对于没有浏览器的无头 / Agent / CI 环境，请使用用户 API 密钥进行非交互式身份验证：npx -y @insforge/cli login --user-api-key "$INSFORGE_USER_API_KEY"（用户可在控制面板的 Profile → API Keys 下创建密钥）。在用户有浏览器、但浏览器无法访问 CLI 本地回调的沙盒中（例如 ChatGPT 应用），请分两步使用设备登录：运行 timeout 15 npx -y @insforge/cli login --device --json 2>&1 || true 以获取验证链接和代码，将它们转发给用户，然后重新运行 npx -y @insforge/cli login --device --json，使用同一代码继续完成登录；用户点击 Authorize 后即可完成 — 参见 references/login.md。如果沙盒报告 api.insforge.dev 不是允许的网络域名，请让用户将其添加到工作区允许的网络域名中，然后重试。如果没有关联项目，已有项目请使用 npx -y @insforge/cli link；用户要求创建新后端时，请使用 npx -y @insforge/cli create。在已预先关联或配置好的工作流中，例如 CI、本地测试项目、自动化流程或用户明确提供项目上下文的场景，请直接使用该项目上下文。默认情况下始终使用云项目；只有用户明确要求在自己的机器上的 Docker 中运行后端时，才参见 references/local.md — 绝不要仅仅因为登录或 create 不方便而将其作为备用方案。

命令路由

需求	CLI 区域	参考
登录、登出、当前用户	login、logout、whoami	references/login.md
创建／关联／列出／查看当前项目	create、link、list、current、metadata	references/create.md
在用户自己的机器上通过 Docker 运行后端——仅在用户明确提出时使用	local	references/local.md
项目生命周期：状态、重命名、删除、恢复、版本更新、实例扩容、转移	projects	本文件
订阅／套餐、额度、用量、支付历史、计费周期、升级套餐、计费门户	billing、usage	本文件
组织和成员（创建、更新、邀请、角色、退出、删除）	orgs	本文件
项目备份（列出、最新备份、创建、重命名、删除、恢复——云端和可自托管）	backups	本文件
Advisor 扫描和忽略发现项（误报、接受的风险）	advisor、diagnose advisor	本文件
Schema、SQL、RLS、触发器、索引、导入、导出	db	references/database/*
Auth 重定向、密码策略、SMTP、存储大小、实时／计划保留期限、子域名配置	config	references/config.md
存储桶和对象	storage	本文件
实时后端设置	db 迁移	references/realtime.md
Edge 函数	functions	references/functions-deploy.md
AI／OpenRouter 密钥设置和 Model Gateway 用量概览	ai setup、ai overview	本文件
Agent 记忆：跨会话保存项目事实、决策、偏好和参考资料	memory	references/memory.md
Stripe／Razorpay 密钥、目录同步、webhook	payments	references/payments/overview.md
前端部署	deployments	references/deployments/deploy.md
自定义域名、Cloudflare Registrar、DNS 同步、SSL 验证	domains	references/deployments/domains.md
后端容器／服务	compute	references/compute-deploy.md
密钥／环境变量	secrets、部署／compute 环境命令	本文件
计划任务	schedules	references/schedules.md
后端分支	branch	references/branch/overview.md、references/branch/merge.md、references/branch/reset.md
日志和健康检查	logs、diagnose	references/diagnostics.md
内置文档查询	docs	本文件
PostHog 设置	posthog setup	references/posthog.md
Apify 网页抓取工具（连接、身份验证桥接、抓取、落地、计划任务）	webscraper apify	references/webscraper/apify.md
报告 InsForge 端的错误、文档差异或设计问题	feedback	本文件

数据库工作流

如果任务涉及复杂的数据库工作，请在编写迁移之前先参考数据库相关文档：

• references/database/migrations.md - 创建迁移文件和应用迁移的工作流。
• references/database/query.md - 执行原始 SQL 和定向检查。
• references/database/access-control.md - RLS、授权、可避免递归的辅助函数、ACL、受保护字段和公开投影。
• references/database/integrity.md - 约束、触发器、派生状态、生命周期保护、仅追加历史记录和由服务端维护的字段。
• references/database/vector.md - pgvector 扩展、向量架构、距离运算符、索引以及向量搜索 SQL/RPC 模式。
• references/database/export.md / references/database/import.md - 架构或数据导入/导出任务。

默认模式：

• 对于架构、授权、索引、触发器、函数和 RLS 策略变更，优先使用 npx -y @insforge/cli db migrations new <name>，并创建迁移 SQL 文件。
• 使用 npx -y @insforge/cli db migrations up --all 应用迁移。
• 对于新的架构工作，在可行时将相关 DDL 合并到一个迁移中。
• 如果现有状态未知或命令失败，请进行定向检查。
• 仅当不适合使用迁移时，才使用 npx -y @insforge/cli db query <sql> 进行定向检查，以及小规模的纠正性行/数据 SQL 操作。
• 使用 npx -y @insforge/cli db rpc <fn> [--data <json>] 通过后端调用数据库函数。

公开架构范围：

• 对于通用应用数据库工作，请在 public 架构中创建和修改应用拥有的对象。
• 对 public 中的应用对象执行创建、修改、删除、授权、撤销授权、索引、触发器、函数、视图和策略变更。
• 除非你正在处理特定功能模块，且其文档明确允许相关操作，否则不要创建自定义架构，也不要写入 InsForge 管理的系统架构，例如 auth、storage、realtime、payments、graphql、extensions、pg_catalog、information_schema 或 system。
• 可以在 public 表或 public RLS 策略中引用 auth.users(id) 和 auth.uid() 等内置对象；不要修改这些内置对象。
• 除非用户请求明确要求进行数据迁移、修复或测试设置，否则不要创建用户、填充业务行或运行应用 CRUD 工作流。

RLS 和访问控制：

• 使用 auth.uid() 或等效的已认证身份表达式检查用户所有权。
• 同时添加 SQL 权限和 RLS 策略。策略不能替代 GRANT。
• 运行时角色对 public 表默认拥有广泛的 DML 权限，以便由 RLS 决定行访问权限。如果某个表需要更严格的操作或列访问权限，请先显式 REVOKE 广泛权限，再授予精确允许的操作或列权限。
• 为 INSERT 和 UPDATE 策略添加 WITH CHECK，以防止写入操作创建用户不应拥有的行。
• 如果直接在策略中联接其他表可能导致其 RLS 策略递归，请优先使用辅助函数进行跨表 RLS 检查。
• 由 RLS 策略调用且会查询启用了 RLS 的表的辅助函数应使用 SECURITY DEFINER。
• 将 RLS 辅助函数放在 public 中，并对 public.team_members 和 auth.uid() 等引用进行架构限定。
• 对于 ACL、受保护的所有者/租户/角色字段、字段级更新掩码、经过清理的公开视图或对递归敏感的策略，请在编写迁移之前阅读 references/database/access-control.md。

完整性：

• 对于计数器、余额、最新记录指针、仅追加历史记录、状态转换、生命周期保护、受保护的删除、配额保护、租约或由触发器维护的列，请在编写迁移之前阅读 references/database/integrity.md。

向量：

• 对于 pgvector、向量搜索函数、分数语义、ANN 索引、混合排序、RAG 分块检索、多向量搜索或嵌入版本选择，请在编写迁移之前阅读 references/database/vector.md。

项目与配置

项目命令：

• npx -y @insforge/cli create - 创建新项目。对于非交互式 Agent 运行，请使用带必需标志的 --json。请参阅 references/create.md。
• npx -y @insforge/cli link - 将当前目录关联到现有项目。
• npx -y @insforge/cli link --api-base-url <url> --api-key <admin key> - 直接通过 URL 和管理员 API 密钥关联可自托管（OSS）后端；无需登录平台。
• npx -y @insforge/cli current - 显示当前关联的项目。
• npx -y @insforge/cli metadata --json - 在需要发现信息时检查后端元数据。

项目生命周期（除非指定 --project <id>，否则针对已关联的项目操作）：

• npx -y @insforge/cli projects get [--project <id>] - 显示项目当前状态、正在进行的 operation_status、区域、实例类型和版本。异步操作（恢复、版本更新、实例扩容）后，使用此命令轮询，直到 operation_status 清除。
• npx -y @insforge/cli projects update [--name <name>] [--domain <domain>] [--project <id>] - 重命名项目或设置其自定义域名。磁盘大小变更需联系 InsForge 支持。
• npx -y @insforge/cli projects restore [--project <id>] - 使已暂停的项目恢复在线。只有已暂停的项目才能恢复。
• npx -y @insforge/cli projects update-version [--wait] [--project <id>] - 将后端更新到最新 InsForge 版本（自动解析；若已是最新版本则不执行操作）。此操作会短暂重启。添加 --wait 可阻塞命令，直到更新完成，而不是在排队后立即返回。
• npx -y @insforge/cli projects upgrade-instance <type> [--project <id>] - 更改实例类别。有效值：nano、micro、small、medium、large、xl（上限为 xl）。此操作会重启项目并更改账单。
• npx -y @insforge/cli projects delete --project <id> - 永久删除项目及其所有资源。必须指定 --project（不会默认为已关联的项目）。此操作不可逆——请先与用户确认准确的项目 ID；这是受保护的人工参与操作，不要自动绕过确认。
• npx -y @insforge/cli projects transfer <targetOrgId> --project <id> - 将项目转移到另一个组织（账单和访问权限也会随之转移）。必须指定 --project（不会默认为已关联的项目）。这是受保护的人工参与操作——请先确认源项目和目标组织。

配置：

• 对于受支持的 insforge.toml 配置项，请使用 npx -y @insforge/cli config export、config plan 和 config apply。
• TOML 仅用于配置值。SQL 应放在 db migrations 中；函数代码应使用 functions deploy；前端代码应使用 deployments deploy；计算代码和镜像应使用 compute deploy。
• 如果 config apply 返回 skipped[]，请报告被跳过的项目以及所需的后端升级。不要改用原始 HTTP 重试。

组织和成员

组织范围的命令按以下顺序解析组织：--org-id 标志、INSFORGE_ORG_ID、已关联项目的组织、配置的默认组织，然后提示选择（或自动选择唯一的组织）。传入 --org-id <id> 可针对指定组织执行操作。

• npx -y @insforge/cli orgs list - 列出你所属的组织。
• npx -y @insforge/cli orgs create <name> [--type personal|team|company] - 创建组织（默认类型为 team）。
• npx -y @insforge/cli orgs update [--name <name>] [--type <type>] [--org-id <id>] - 重命名组织或更改其类型。
• npx -y @insforge/cli orgs members list [--org-id <id>] - 列出成员和待处理的邀请。
• npx -y @insforge/cli orgs members invite <email> [--role administrator|developer] [--org-id <id>] - 邀请成员（默认角色为 developer）。
• npx -y @insforge/cli orgs members role <memberId> <role> [--org-id <id>] - 更改成员角色（administrator 或 developer）。
• npx -y @insforge/cli orgs members remove <memberId> [--org-id <id>] - 移除成员。请先确认意图。
• npx -y @insforge/cli orgs leave --org-id <id> - 离开组织。必须指定 --org-id（不会默认使用已关联的组织）。你将失去对该组织所有项目的访问权限，且必须重新受邀才能返回。如果你是最后一位管理员，后端会拒绝此操作——请先转移管理员角色。此操作受保护，需人工参与确认——请先确认意图。
• npx -y @insforge/cli orgs delete --org-id <id> - 永久删除组织。必须指定 --org-id（不会默认使用已关联的组织）。仅限所有者操作。此操作会级联删除：组织中的每个项目（数据库、存储和所有资源）都将被永久删除，且订阅将被取消——CLI 会列出受影响的项目，并在当前已关联项目属于其中之一时发出警告。此操作不可逆；请先与用户确认准确的组织 ID，且不要自动绕过确认。

账单和用量

查看组织的套餐和用量，并管理其订阅。组织解析方式与“组织和成员”部分相同。

• npx -y @insforge/cli billing status [--org-id <id>] - 显示当前订阅、套餐和周期。
• npx -y @insforge/cli billing credits [--org-id <id>] - 显示信用额度余额和近期的信用额度交易。
• npx -y @insforge/cli billing history [--org-id <id>] - 列出过往付款／发票。
• npx -y @insforge/cli billing cycles [--org-id <id>] - 显示当前和以往的账单周期时间段。
• npx -y @insforge/cli usage [--org-id <id>] - 显示当前账单周期的用量（摘要及按项目细分：数据库、存储、出口流量等）。
• npx -y @insforge/cli billing upgrade <plan> [--org-id <id>] - 启动 Stripe 结账流程以更改套餐（free | starter | pro | team | enterprise）。会在浏览器中打开托管结账 URL，并同时打印该 URL。使用 --json 时会打印 JSON 对象（{ checkoutUrl, sessionId }），且不会打开浏览器——可用于无头环境／CI。用户完成结账前不会扣费；后端会验证套餐和管理员权限。
• npx -y @insforge/cli billing manage [--org-id <id>] - 打开 Stripe 客户门户，以管理订阅、付款方式或取消订阅。会在浏览器中打开门户 URL，并同时打印该 URL。使用 --json 时会打印 JSON 对象（{ portalUrl }），且不会打开浏览器——可用于无头环境／CI。

备份

除非指定 --project <id>，否则操作当前关联的项目。云项目和自托管项目（通过 link --api-base-url <url> --api-key <key> 关联）均适用。CLI 会自动路由到正确的后端；显式指定 --project <id> 时始终针对云项目。

• npx -y @insforge/cli backups list [--project <id>] - 列出备份。
• npx -y @insforge/cli backups latest [--project <id>] - 显示最新备份。云项目会输出最新转储文件及其预签名下载 URL；自托管项目会输出最新的备份记录（不含下载 URL）。
• npx -y @insforge/cli backups create [--name <name>] [--wait] [--project <id>] - 创建备份。--name 为可选参数；指定时必须为 1–64 个字符。--wait 会阻塞至任务完成，而不是在任务排队后立即返回。
• npx -y @insforge/cli backups rename <backupId> <name> [--project <id>] - 重命名备份（传入 "" 可清除名称）。
• npx -y @insforge/cli backups delete <backupId> [--project <id>] - 删除备份。请先确认操作意图。
• npx -y @insforge/cli backups restore <backupId> [--project <id>] - 从备份恢复项目。请先确认操作意图。云项目：会覆盖项目当前的数据库和存储；备份后写入的所有数据都会丢失。自托管项目：仅对数据库执行 pg_restore --clean；已备份表中的数据会回退，但备份后创建的表不会被删除，存储也不会受到影响。

存储

• npx -y @insforge/cli storage buckets - 列出存储桶。
• npx -y @insforge/cli storage create-bucket <name> [--private] - 创建存储桶。
• npx -y @insforge/cli storage delete-bucket <name> - 删除存储桶及其中的所有对象。请先确认破坏性操作的意图。
• npx -y @insforge/cli storage list-objects <bucket> [--prefix] [--search] [--limit] [--sort] - 查看对象。
• npx -y @insforge/cli storage upload <file> --bucket <name> [--key <objectKey>] - 上传对象。
• npx -y @insforge/cli storage download <objectKey> --bucket <name> [--output <path>] - 下载对象。
• npx -y @insforge/cli storage s3-keys list - 列出兼容 S3 的访问密钥（不会显示密钥值）。
• npx -y @insforge/cli storage s3-keys create [--description <text>] - 创建 S3 访问密钥。创建时只会显示一次秘密访问密钥，请立即保存。
• npx -y @insforge/cli storage s3-keys delete <id> - 删除 S3 访问密钥。使用该密钥的工具将停止工作。请先确认操作意图。

对于通过 Postgres 策略实现的存储访问控制，请参阅存储专属产品文档或功能指南。除非所引用的存储文档明确说明，否则不要将存储内部机制视为通用的公共架构数据库表。

实时功能

通过迁移创建频道模式、应用表发布触发器，以及频道／消息 RLS。请参阅 references/realtime.md。

Edge Functions

• npx -y @insforge/cli functions list - 列出已部署的函数。
• npx -y @insforge/cli functions code <slug> - 查看函数源码。
• npx -y @insforge/cli functions deploy <slug> --file <path> - 部署或更新函数。请参阅 references/functions-deploy.md。
• npx -y @insforge/cli functions invoke <slug> [--data <json>] [--method GET|POST] - 调用函数。
• npx -y @insforge/cli functions delete <slug> - 删除函数。请先确认破坏性操作的意图。

AI Gateway

• npx -y @insforge/cli ai setup 获取关联项目当前使用的 OpenRouter 密钥，并将 OPENROUTER_API_KEY 写入本地服务端环境文件。
• npx -y @insforge/cli ai overview 显示 Model Gateway 密钥使用情况：总支出、限额、剩余额度、每日／每周／每月支出，以及可观测性可用时的各模型活动情况。金额以 USD 额度计。可用此命令回答“还剩多少 AI 额度／正在使用多少 AI 额度”。
• 请将 OPENROUTER_API_KEY 仅用于服务端。切勿将其暴露为 NEXT_PUBLIC_*、VITE_*、PUBLIC_* 或 REACT_APP_*。

Memory

每个项目都内置 Agent 记忆：可跨会话保留的持久事实、决策、偏好和参考信息。将其作为本能，而非事后补充。

• npx -y @insforge/cli memory list - 轻量标题索引（不调用 AI）。在开始非简单任务时运行；回忆与任务相关的标题。
• npx -y @insforge/cli memory recall "<query>" [--scope] [--limit] [--threshold] - 语义与关键词检索。
• npx -y @insforge/cli memory remember "<content>" [--kind] [--title] [--scope] [--source] - 存储一条原子记忆。在决策和易踩坑之处发生时记录，而不是等到会话结束。--kind 仅接受 fact、decision、preference 或 reference - 易踩坑之处存为 fact（记录选择时则存为 decision）。
• npx -y @insforge/cli memory remember --file <path> - 从转录或笔记文件中提取持久记忆。

存储操作具有幂等性：重复记录已知事实不会产生任何变化，矛盾事实会更新现有记忆，而不会重复添加 - 事实发生变化时，只需用 remember 记录新事实。关于存储内容、类型和示例，请参阅 references/memory.md。

Payments

使用 payments 进行 Stripe/Razorpay 后端设置和目录同步。请参阅 references/payments/overview.md。

• Payments 因提供商而异：请明确使用 payments stripe ... 或 payments razorpay ...。
• 使用 payments <provider> config set 配置提供商密钥；密钥或账户发生变化时，设置密钥会自动同步提供商状态。
• 使用 payments <provider> status 检查密钥、账户、同步和 webhook 状态。
• 运行 payments <provider> sync 手动刷新或重试镜像的提供商数据。
• Stripe 使用 Products/Prices，并支持托管 webhook 注册；Razorpay 使用 Items/Plans/Orders，且需要在 Razorpay Dashboard 中手动设置 webhook。
• 构建期间优先使用测试模式。只有在用户明确批准后才使用实时模式。
• 如果后端报告 Payments 不可用，请让用户/管理员启用或升级 Payments。不要通过将提供商密钥存储为通用密钥，或将支付密钥嵌入应用代码来绕过此限制。
• 进行提供商专属设置前，请加载 references/payments/stripe.md 或 references/payments/razorpay.md。

运行时结账、订阅、客户门户流程和应用代码属于 insforge 应用集成技能的内容。

Deployments

前端部署：

• 如果应用有构建步骤，请先在本地构建。
• 部署前，确保已使用正确的框架前缀配置前端运行时环境变量。
• 对于前端源目录，使用 npx -y @insforge/cli deployments deploy <dir>。除非部署参考明确要求，否则不要部署生成的输出目录。
• 请参阅 references/deployments/deploy.md。

自定义域名：

• 使用 npx -y @insforge/cli domains ... 管理自定义域名、Cloudflare Registrar、DNS 同步和 SSL 验证。
• 请参阅 references/deployments/domains.md。

后端计算服务：

• 使用 npx -y @insforge/cli compute ...；不要使用用户自己的 flyctl 账户直接管理 InsForge 计算服务。
• 对于包含 Dockerfile 的目录，请使用源代码模式；对于预构建镜像，请使用 --image <url> 镜像模式。
• 对于密钥，请使用 --env-file 或可重复执行的环境变量设置/更新命令，而不是大型内联 JSON。
• 请参阅 references/compute-deploy.md。

密钥

• npx -y @insforge/cli secrets list [--all] - 列出密钥，不显示其值。
• npx -y @insforge/cli secrets get <key> - 仅在必要时获取密钥值。
• npx -y @insforge/cli secrets add <key> <value> [--reserved] [--expires <ISO date>] - 创建密钥。
• npx -y @insforge/cli secrets update <key> [--value] [--active] [--reserved] [--expires] - 更新密钥。
• npx -y @insforge/cli secrets delete <key> - 软删除密钥。请先确认操作意图。
• npx -y @insforge/cli secrets rotate <api-key|anon-key> [--grace-hours <n>] - 轮换项目 API 密钥或 anon 密钥。新密钥只会显示一次——请妥善保存。宽限期内旧密钥仍可使用（如果省略 --grace-hours，则使用服务端默认值）；请在旧密钥过期前更新所有使用方。

定时任务

• npx -y @insforge/cli schedules list/get/create/update/delete/logs。
• 对按墙上时钟时间运行的定时任务，使用标准的 5 字段 cron。
• 对亚分钟级运行频率，使用 30 seconds 之类的 pg_cron 间隔语法。不支持带秒的 6 字段 cron。
• 标头可以通过 ${{secrets.KEY_NAME}} 引用 InsForge 密钥。
• 有关 cron 格式、密钥标头引用、示例、常见错误和推荐设置工作流，请参阅 references/schedules.md。

分支

使用后端分支，在将高风险的架构、RLS、身份验证或函数变更应用到生产环境之前进行测试。请参阅 references/branch/overview.md。

常用命令：

• npx -y @insforge/cli branch create <name> [--mode full|schema-only] [--no-switch]
• npx -y @insforge/cli branch list
• npx -y @insforge/cli branch switch <name> 或 --parent
• npx -y @insforge/cli branch merge <name> [--dry-run] [--save-sql <path>]
• npx -y @insforge/cli branch reset <name>
• npx -y @insforge/cli branch delete <name>

分支功能需要由支持该功能的后端版本提供。如果不可用，请说明后端版本限制，不要编造变通方案。

诊断和日志

• npx -y @insforge/cli diagnose - 完整的运行状况报告。
• npx -y @insforge/cli diagnose --ai "<issue description>" - 请 InsForge 调试 Agent 诊断具体的后端问题。
• npx -y @insforge/cli diagnose metrics [--range 1h|6h|24h|7d] - EC2 指标。
• npx -y @insforge/cli diagnose advisor [--severity critical|warning|info] [--category security|performance|health] - 顾问问题。Rule 列中的值是 advisor suppress 所需的 id。
• npx -y @insforge/cli diagnose db [--check <checks>] - 数据库运行状况检查。
• npx -y @insforge/cli diagnose logs [--source <name>] [--limit <n>] - 聚合错误日志。
• npx -y @insforge/cli logs <source> [--limit <n>] - 特定来源的后端日志。

常见日志来源包括 function.logs、function-deploy.logs、postgres.logs、postgrest.logs 和 insforge.logs。有关常见调试场景和来源选择，请参阅 references/diagnostics.md。

Advisor

后端 Advisor 会扫描项目，查找安全性、性能和健康状况方面的问题。使用 diagnose advisor 查看结果；使用 advisor 管理扫描和误报：

• npx -y @insforge/cli advisor scan - 立即触发扫描，无需等待计划任务。修复问题后，可用它立即重新检查。扫描会异步运行（通常不到一分钟）——持续轮询 diagnose advisor --json，直到 scan.status 为 completed 且 scan.scanId 等于 advisor scan 返回的 ID，然后查看结果。
• npx -y @insforge/cli advisor suppressions - 列出已抑制的问题。
• npx -y @insforge/cli advisor suppress <ruleId> [--object <affectedObject>] --reason <reason> [--note <note>] - 记录原因并忽略某个问题。使用 --object（逐字填写问题的 Affected Object）时，仅抑制该实例；不使用时则抑制整个规则。--reason 可选值为 false_positive | accepted_risk | wont_fix | other；若选择 other，则必须提供 --note。抑制会从下一次扫描开始生效（运行 advisor scan 即可查看效果）。仅抑制用户已判定的问题——切勿为了让报告看起来干净而抑制问题。
• npx -y @insforge/cli advisor unsuppress <suppressionId> - 移除抑制，使问题在下一次扫描中重新出现。

反馈

当 InsForge 工具包的任何部分出现异常时——包括后端平台、SDK、CLI、Agent 技能或文档——请向 InsForge 团队报告，然后使用变通方案继续任务。只报告 InsForge 方面的问题，不要报告用户自己的应用代码问题。

npx -y @insforge/cli feedback --json \
  --type bug \
  --component backend \
  --title "db policies create returns 500 on uppercase table names" \
  --detail "Creating an RLS policy on table \"Users\" returns 500; lowercase names work. Repro: create table with quoted uppercase name, then run policies create." \
  --area db \
  --command "insforge db policies create --table Users ..." \
  --error "<verbatim error output>" \
  --severity major

必需的标志：

• --type：你遇到的问题类型。根据实际情况选择：
  • “无法正常工作”（按文档／约定本应正常工作）→ bug
  • “我被告知要执行 X，但实际情况要求采用其他做法” → 同样是 bug，并附上 --doc（说明所在位置）、--expected（文档声称的内容）和 --workaround（实际可行的做法）——你无法判断是说明已过时还是产品出现回归，这三个字段可帮助团队区分
  • “我想做的事不受支持” → feature-request
  • “功能可用，但令人困惑或操作不便”（错误信息无帮助、被迫绕道操作）→ friction
  • 其他情况 → other
• --component：问题所属的工具包部分 — backend（平台／托管服务）| sdk | cli | skills（Agent 技能内容）| docs | other。
• --title 和 --detail（或 --file <path>）。

可选标志：

• --language：当 --component sdk 时必填 — 指明 SDK，例如 js、python、flutter、swift、kotlin、rest-api；如果涉及多个 SDK，则填写 multiple。对于 --component docs，也可用于指定特定语言的文档页面。其他组件无需填写。
• --area：产品领域 — db | auth | storage | functions | deployments | billing | ai | realtime | payments。此选项与 --component 相互独立：Python SDK 中无法正常上传存储内容的问题，应填写 --component sdk --language python --area storage。
• --workaround：你用来解决问题的替代做法 — 找到变通方案时务必填写；这能帮助团队判断问题的阻碍程度，而且通常会成为文档修订内容。
• --command（导致问题的 CLI／SDK 调用）、--error（原样输出；会自动脱敏并截断）、--expected（文档／技能说明的操作或你的预期）以及 --doc "<page or skill section>"（用于说明差异）；--severity blocker|major|minor（默认为 minor）。

--detail 请保持简洁，并聚焦于 InsForge：说明发生了什么、你的预期是什么，以及最精简的复现步骤。不要粘贴用户应用数据——CLI 会在本地对常见模式进行脱敏（电子邮件、已知凭据／密钥格式、密钥赋值、公共 IPv4 地址、主目录用户名），并截断过长字段；但脱敏基于模式匹配，只是安全防护，不代表可以随意提交敏感内容。无需登录——登出状态和 OSS 配置均可使用；关联云项目后，会自动附加项目／组织上下文。成功后会返回反馈 ID（重复报告会合并到已有报告，并返回其 ID）。

文档

• npx -y @insforge/cli docs - 列出文档主题。
• npx -y @insforge/cli docs instructions - 设置指南。
• npx -y @insforge/cli docs <feature> <language> - 获取 db、storage、functions、auth、ai 或 realtime 的 typescript、swift、kotlin 或 rest-api 功能文档。

对于使用 InsForge 或 @insforge/sdk 编写应用代码，请使用 insforge 应用集成技能，并仅将 docs 用作官方功能参考。

PostHog

• npx -y @insforge/cli posthog setup 会确保仪表板已连接 PostHog，然后打印官方 PostHog 向导命令，以及已连接项目的公开 phc_ API 密钥和主机地址。
• ⚠️ 仅运行 posthog setup 并不会为应用添加埋点：在向导步骤完成前，不会设置环境变量、SDK 或事件。该向导需要交互操作，且可能会打开浏览器；请让用户在自己的真实终端中运行，或使用打印出的 phc_ 密钥/主机地址手动添加埋点（PostHog 的公开客户端密钥，可安全地放入前端环境变量）。
• 仅限云端：自托管后端不会提供此集成。请勿将其他 PostHog 账户中的 phc_ 密钥替换到应用环境变量中——Analytics 页面读取的是服务端连接，而该连接仅由 posthog setup 填充；请使用其打印出的密钥。

Apify 网页抓取工具

• npx -y @insforge/cli webscraper apify connect — 一次性 OAuth 连接；在 InsForge 中存储可刷新的令牌。
• npx -y @insforge/cli webscraper apify login — 认证桥接：获取 InsForge 管理的令牌，运行 apify login --token，并安装 Apify 官方 Agent 技能。绝不要运行普通的 apify login（浏览器 OAuth）。遇到任何 Apify 401 /“未登录”提示时，请重新运行 login。
• 完整的抓取 → 写入 → 调度工作流和基于规模的写入策略，请参阅 references/webscraper/apify.md。

非交互式 CI/CD

在自动化环境中使用环境变量和 JSON 模式：

INSFORGE_EMAIL=$EMAIL INSFORGE_PASSWORD=$PASSWORD npx -y @insforge/cli login --email -y
npx -y @insforge/cli link --project-id $PROJECT_ID --org-id $ORG_ID -y
npx -y @insforge/cli db query "SELECT 1 AS ok" --json

项目配置文件

运行 create 或 link 后，.insforge/project.json 中会包含已关联的项目 ID、应用密钥、区域、API 密钥和后端 URL。

• 绝不要提交 .insforge/project.json 或公开分享。
• 请勿手动编辑。使用 npx -y @insforge/cli link 或分支命令切换项目。