Back to Details

insforge

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

InsForge Agent Skill

InsForge Agent 技能

Credential Detection (MCP Mode)

凭证检测（MCP模式）

When using MCP tools, credentials are often pre-configured. Before asking the user:
  1. Try calling MCP tools first: Attempt 
    get-backend-metadata
    or 
    get-anon-key
  2. If MCP succeeds: Credentials are already configured, proceed with work
  3. If MCP fails with auth error: Then ask user for Project URL and API Key
Example: User says "deploy to insforge"
✓ Try: get-backend-metadata via MCP
✓ If success: Extract project URL from metadata, get anon key via get-anon-key
✗ If fail: Ask user for credentials
使用MCP工具时，凭证通常已预先配置。在询问用户之前：
  1. 优先尝试调用MCP工具：尝试调用
    get-backend-metadata
    或
    get-anon-key
  2. 如果MCP调用成功：说明凭证已配置完成，可继续后续操作
  3. 如果MCP调用返回认证错误：再向用户索要项目URL和API密钥
示例：用户说“部署到InsForge”
✓ 尝试：通过MCP调用get-backend-metadata
✓ 如果成功：从元数据中提取项目URL，通过get-anon-key获取匿名密钥
✗ 如果失败：向用户索要凭证

STOP: Check Credentials First (Manual Mode)

注意：先检查凭证（手动模式）

Only ask for credentials if MCP auto-detection fails. You need:
CredentialFormatRequired For
Project URL
https://{project-id}.{region}.insforge.app
All API calls
API Key
ik_xxxx...
Authorization header
Action: If MCP tools fail and user has not provided credentials, ask now:
Do you have an InsForge project? I'll need:
1. Project URL (e.g., https://abc123.us-east-1.insforge.app)
2. API Key (starts with ik_)

You can find these in InsForge Dashboard → Project Settings.
仅当MCP自动检测失败时，才向用户索要凭证。你需要以下信息：
凭证格式适用场景
项目URL
https://{project-id}.{region}.insforge.app
所有API调用
API密钥
ik_xxxx...
授权请求头
操作步骤：如果MCP工具调用失败且用户未提供凭证，请立即询问：
你是否拥有InsForge项目？我需要以下信息：
1. 项目URL（例如：https://abc123.us-east-1.insforge.app）
2. API密钥（以ik_开头）

你可以在InsForge控制台 → 项目设置中找到这些信息。

When to Use Which Documentation

文档使用场景说明

Use 
sdk-integration.md
files when:

当需要以下操作时，使用
sdk-integration.md
文件：

  • Integrating InsForge services into the user's frontend application
  • Implementing features that run in the browser or client app
  • Writing code that uses 
    @insforge/sdk
    methods
  • Examples: User login flow, fetching data, uploading files, real-time subscriptions
  • 将InsForge服务集成到用户的前端应用中
  • 实现运行在浏览器或客户端应用中的功能
  • 编写使用
    @insforge/sdk
    方法的代码
  • 示例：用户登录流程、数据获取、文件上传、实时订阅

Use 
backend-configuration.md
files when:

当需要以下操作时，使用
backend-configuration.md
文件：

  • Configuring the InsForge backend before the app can use a feature
  • Creating database tables, storage buckets, or deploying serverless functions
  • Setting up real-time channels or database triggers
  • Managing auth settings, AI configurations, or deployments
  • Examples: Creating a 
    posts
    table, enabling OAuth providers, deploying an edge function
  • 在应用使用功能前配置InsForge后端
  • 创建数据库表、存储桶或部署无服务器函数
  • 设置实时通道或数据库触发器
  • 管理认证设置、AI配置或部署任务
  • 示例：创建
    posts
    数据表、启用OAuth提供商、部署边缘函数

Typical Workflow

典型工作流程

  1. Backend Configuration → Configure infrastructure via HTTP API
  2. SDK Integration → Use SDK in application code
Example: Adding file uploads
  1. First create a storage bucket → see storage/backend-configuration.md
  2. Then implement upload in the app → see storage/sdk-integration.md
Example: Adding user authentication
  1. First configure auth settings → see auth/backend-configuration.md
  2. Then implement login/signup → see auth/sdk-integration.md
  1. 后端配置 → 通过HTTP API配置基础设施
  2. SDK集成 → 在应用代码中使用SDK
示例：添加文件上传功能
  1. 首先创建存储桶 → 查看storage/backend-configuration.md
  2. 然后在应用中实现上传功能 → 查看storage/sdk-integration.md
示例：添加用户认证功能
  1. 首先配置认证设置 → 查看auth/backend-configuration.md
  2. 然后实现登录/注册功能 → 查看auth/sdk-integration.md

First Step: Get Backend Metadata

第一步：获取后端元数据

Always get the backend metadata first before doing any work. This gives you the complete picture of the current project structure.
GET /api/metadata
Authorization: Bearer {admin-token-or-api-key}
This returns the full backend state including:
  • Database: Tables, columns, relationships, indexes, RLS policies
  • Auth: Configuration, OAuth providers, user stats
  • Storage: Buckets and visibility settings
  • Functions: Deployed functions and status
  • AI: Configured models
  • Realtime: Channel patterns
Understanding the existing backend structure before making changes prevents errors and helps you build on what's already there.
在进行任何操作前，务必先获取后端元数据。这能让你全面了解当前项目的结构。
GET /api/metadata
Authorization: Bearer {admin-token-or-api-key}
该接口返回完整的后端状态，包括：
  • 数据库：数据表、列、关系、索引、RLS策略
  • 认证：配置信息、OAuth提供商、用户统计
  • 存储：存储桶及可见性设置
  • 函数：已部署的函数及其状态
  • AI：已配置的模型
  • 实时服务：通道规则
在进行更改前了解现有后端结构，可避免错误并基于已有内容进行开发。

Quick Setup

快速设置

bash
npm install @insforge/sdk@latest
javascript
import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: 'https://your-project.region.insforge.app',
  anonKey: 'your-anon-key'
})
bash
npm install @insforge/sdk@latest
javascript
import { createClient } from '@insforge/sdk'

const insforge = createClient({
  baseUrl: 'https://your-project.region.insforge.app',
  anonKey: 'your-anon-key'
})

Module Reference

模块参考

ModuleSDK IntegrationBackend Configuration
Databasedatabase/sdk-integration.mddatabase/backend-configuration.md
Authauth/sdk-integration.mdauth/backend-configuration.md
Storagestorage/sdk-integration.mdstorage/backend-configuration.md
Functionsfunctions/sdk-integration.mdfunctions/backend-configuration.md
AIai/sdk-integration.mdai/backend-configuration.md
Real-timerealtime/sdk-integration.mdrealtime/backend-configuration.md
Schedules—schedules/backend-configuration.md
Deployments—deployments/workflow.md
Logs—logs/debugging.md
模块SDK集成文档后端配置文档
数据库database/sdk-integration.mddatabase/backend-configuration.md
认证auth/sdk-integration.mdauth/backend-configuration.md
存储storage/sdk-integration.mdstorage/backend-configuration.md
函数functions/sdk-integration.mdfunctions/backend-configuration.md
AIai/sdk-integration.mdai/backend-configuration.md
实时服务realtime/sdk-integration.mdrealtime/backend-configuration.md
调度任务—schedules/backend-configuration.md
部署—deployments/workflow.md
日志—logs/debugging.md

What Each Module Covers

各模块覆盖内容

Modulesdk-integration.mdbackend-configuration.md
DatabaseCRUD operations, filters, paginationCreate tables, RLS policies, triggers, indexes. See also database/postgres-rls.md for RLS best practices
AuthSign up/in, OAuth, sessions, profilesAuth config, user management, anon tokens
StorageUpload, download, delete filesCreate/manage buckets
FunctionsInvoke functionsDeploy, update, delete functions
AIChat, images, embeddingsModels, credits, usage stats
Real-timeConnect, subscribe, publish eventsChannel patterns, database triggers
Schedules—Cron jobs, HTTP triggers, execution logs
Deployments—Deploy frontend apps
Logs—Fetch container logs for debugging
模块sdk-integration.mdbackend-configuration.md
数据库CRUD操作、筛选、分页创建数据表、RLS策略、触发器、索引。另可查看database/postgres-rls.md获取RLS最佳实践
认证注册/登录、OAuth、会话、用户资料认证配置、用户管理、匿名令牌
存储文件上传、下载、删除创建/管理存储桶
函数调用函数部署、更新、删除函数
AI聊天、图像生成、嵌入向量模型配置、额度、使用统计
实时服务连接、订阅、发布事件通道规则、数据库触发器
调度任务—Cron任务、HTTP触发器、执行日志
部署—部署前端应用
日志—获取容器日志用于调试

Guides

指南

GuideWhen to Use
database/postgres-rls.mdWriting or reviewing RLS policies — covers infinite recursion prevention, 
SECURITY DEFINER
patterns, performance tips, and common InsForge RLS patterns
指南使用场景
database/postgres-rls.md编写或审核RLS策略时使用 — 涵盖无限递归预防、
SECURITY DEFINER
模式、性能优化技巧及InsForge常见RLS模式

SDK Quick Reference

SDK快速参考

All SDK methods return 
{ data, error }
.
ModuleMethods
insforge.database
.from().select()
, 
.insert()
, 
.update()
, 
.delete()
, 
.rpc()
insforge.auth
.signUp()
, 
.signInWithPassword()
, 
.signInWithOAuth()
, 
.signOut()
, 
.getCurrentSession()
insforge.storage
.from().upload()
, 
.uploadAuto()
, 
.download()
, 
.remove()
insforge.functions
.invoke()
insforge.ai
.chat.completions.create()
, 
.images.generate()
, 
.embeddings.create()
insforge.realtime
.connect()
, 
.subscribe()
, 
.publish()
, 
.on()
, 
.disconnect()
所有SDK方法均返回
{ data, error }
。
模块方法
insforge.database
.from().select()
, 
.insert()
, 
.update()
, 
.delete()
, 
.rpc()
insforge.auth
.signUp()
, 
.signInWithPassword()
, 
.signInWithOAuth()
, 
.signOut()
, 
.getCurrentSession()
insforge.storage
.from().upload()
, 
.uploadAuto()
, 
.download()
, 
.remove()
insforge.functions
.invoke()
insforge.ai
.chat.completions.create()
, 
.images.generate()
, 
.embeddings.create()
insforge.realtime
.connect()
, 
.subscribe()
, 
.publish()
, 
.on()
, 
.disconnect()

Backend API Quick Reference

后端API快速参考

Base URL: 
https://your-project.region.insforge.app
Authentication: 
Authorization: Bearer {admin-token-or-api-key}
TaskEndpoint
Execute SQL
POST /api/database/advance/rawsql
Create bucket
POST /api/storage/buckets
Deploy function
POST /api/functions
Configure auth
PUT /api/auth/config
Get metadata
GET /api/metadata
Create schedule
POST /api/schedules
Deploy frontend
POST /api/deployments
Get logs
GET /api/logs/{source}
基础URL：
https://your-project.region.insforge.app
认证方式：
Authorization: Bearer {admin-token-or-api-key}
任务接口地址
执行SQL
POST /api/database/advance/rawsql
创建存储桶
POST /api/storage/buckets
部署函数
POST /api/functions
配置认证
PUT /api/auth/config
获取元数据
GET /api/metadata
创建调度任务
POST /api/schedules
部署前端应用
POST /api/deployments
获取日志
GET /api/logs/{source}

Deployment Best Practices

部署最佳实践

ALWAYS: Local Build First

务必：先在本地构建

Before deploying to InsForge, verify the build works locally. Local builds are faster to debug and don't waste server resources on avoidable errors.
bash
undefined
部署到InsForge之前，先验证本地构建是否成功。本地构建调试速度更快，且不会因可避免的错误浪费服务器资源。
bash
undefined

1. Install dependencies

1. 安装依赖

npm install
npm install

2. Set up environment variables for your framework

2. 为你的框架设置环境变量

cp .env.example .env.local # or create .env.production
cp .env.example .env.local # 或创建.env.production

3. Run production build

3. 执行生产构建

npm run build

**Common build-time issues to fix before deploying:**

| Issue | Common Cause | General Solution |
|-------|--------------|------------------|
| Missing environment variables | Build-time env vars not set | Create `.env.production` with required variables |
| Module resolution errors | Edge functions mixed with app code | Exclude edge function directories from TypeScript/compiler config |
| Static export conflicts | Dynamic routes with static export | Use server-side rendering or configure static params |
| Missing dependencies | Incomplete node_modules | Run `npm install` and verify package.json |
npm run build

**部署前需修复的常见构建问题**：

| 问题 | 常见原因 | 通用解决方案 |
|------|----------|--------------|
| 缺少环境变量 | 构建时未设置环境变量 | 创建`.env.production`并配置所需变量 |
| 模块解析错误 | 边缘函数与应用代码混合 | 在TypeScript/编译器配置中排除边缘函数目录 |
| 静态导出冲突 | 动态路由与静态导出不兼容 | 使用服务端渲染或配置静态参数 |
| 缺少依赖 | node_modules不完整 | 执行`npm install`并验证package.json |

Framework-Specific Notes

框架特定说明

  • Environment Variable Prefix: Use the correct prefix for your framework:
    • Vite: 
      VITE_*
    • Next.js: 
      NEXT_PUBLIC_*
    • Create React App: 
      REACT_APP_*
    • Astro: 
      PUBLIC_*
  • Edge Functions: If your project has Deno/edge functions in a separate directory (commonly 
    functions/
    ), exclude them from your frontend build to avoid module resolution errors.
  • 环境变量前缀：使用对应框架的正确前缀：
    • Vite: 
      VITE_*
    • Next.js: 
      NEXT_PUBLIC_*
    • Create React App: 
      REACT_APP_*
    • Astro: 
      PUBLIC_*
  • 边缘函数：如果你的项目在单独目录（通常为
    functions/
    ）中包含Deno/边缘函数，请将其从前端构建中排除，以避免模块解析错误。

Deployment Checklist

部署检查清单

  • Local 
    npm run build
    succeeds
  • All required environment variables configured for production
  • Edge function directories excluded from frontend build (if applicable)
  • Build output directory matches your framework's expected output
  • 本地
    npm run build
    执行成功
  • 所有生产所需的环境变量已配置
  • 边缘函数目录已从前端构建中排除（如适用）
  • 构建输出目录与框架预期一致

Important Notes

重要提示

  • Database inserts require array format: 
    insert([{...}])
    not 
    insert({...})
  • Storage: Save both 
    url
    AND 
    key
    to database for download/delete operations
  • Functions invoke URL: 
    /functions/{slug}
    (without 
    /api
    prefix)
  • Use Tailwind CSS v3.4 (do not upgrade to v4)
  • Always local build before deploy: Prevents wasted build resources and faster debugging
  • 数据库插入需使用数组格式：
    insert([{...}])
    而非 
    insert({...})
  • 存储服务：需将
    url
    和
    key
    同时保存到数据库，以便后续下载/删除操作
  • 函数调用URL：
    /functions/{slug}
    （无需
    /api
    前缀）
  • 使用Tailwind CSS v3.4（请勿升级到v4）
  • 部署前务必本地构建：避免浪费构建资源并加快调试速度