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:

Try calling MCP tools first: Attempt
```
get-backend-metadata
```
or
```
get-anon-key
```
If MCP succeeds: Credentials are already configured, proceed with work
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工具时，凭证通常已预先配置。在询问用户之前：

优先尝试调用MCP工具：尝试调用
```
get-backend-metadata
```
或
```
get-anon-key
```
如果MCP调用成功：说明凭证已配置完成，可继续后续操作
如果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:

Credential	Format	Required 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

典型工作流程

Backend Configuration → Configure infrastructure via HTTP API
SDK Integration → Use SDK in application code

Example: Adding file uploads

First create a storage bucket → see storage/backend-configuration.md
Then implement upload in the app → see storage/sdk-integration.md

Example: Adding user authentication

First configure auth settings → see auth/backend-configuration.md
Then implement login/signup → see auth/sdk-integration.md

后端配置 → 通过HTTP API配置基础设施
SDK集成 → 在应用代码中使用SDK

示例：添加文件上传功能

首先创建存储桶 → 查看storage/backend-configuration.md
然后在应用中实现上传功能 → 查看storage/sdk-integration.md

示例：添加用户认证功能

首先配置认证设置 → 查看auth/backend-configuration.md
然后实现登录/注册功能 → 查看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

模块参考

Module	SDK Integration	Backend Configuration
Database	database/sdk-integration.md	database/backend-configuration.md
Auth	auth/sdk-integration.md	auth/backend-configuration.md
Storage	storage/sdk-integration.md	storage/backend-configuration.md
Functions	functions/sdk-integration.md	functions/backend-configuration.md
AI	ai/sdk-integration.md	ai/backend-configuration.md
Real-time	realtime/sdk-integration.md	realtime/backend-configuration.md
Schedules	—	schedules/backend-configuration.md
Deployments	—	deployments/workflow.md
Logs	—	logs/debugging.md

模块	SDK集成文档	后端配置文档
数据库	database/sdk-integration.md	database/backend-configuration.md
认证	auth/sdk-integration.md	auth/backend-configuration.md
存储	storage/sdk-integration.md	storage/backend-configuration.md
函数	functions/sdk-integration.md	functions/backend-configuration.md
AI	ai/sdk-integration.md	ai/backend-configuration.md
实时服务	realtime/sdk-integration.md	realtime/backend-configuration.md
调度任务	—	schedules/backend-configuration.md
部署	—	deployments/workflow.md
日志	—	logs/debugging.md

What Each Module Covers

各模块覆盖内容

Module	sdk-integration.md	backend-configuration.md
Database	CRUD operations, filters, pagination	Create tables, RLS policies, triggers, indexes. See also database/postgres-rls.md for RLS best practices
Auth	Sign up/in, OAuth, sessions, profiles	Auth config, user management, anon tokens
Storage	Upload, download, delete files	Create/manage buckets
Functions	Invoke functions	Deploy, update, delete functions
AI	Chat, images, embeddings	Models, credits, usage stats
Real-time	Connect, subscribe, publish events	Channel patterns, database triggers
Schedules	—	Cron jobs, HTTP triggers, execution logs
Deployments	—	Deploy frontend apps
Logs	—	Fetch container logs for debugging

模块	sdk-integration.md	backend-configuration.md
数据库	CRUD操作、筛选、分页	创建数据表、RLS策略、触发器、索引。另可查看database/postgres-rls.md获取RLS最佳实践
认证	注册/登录、OAuth、会话、用户资料	认证配置、用户管理、匿名令牌
存储	文件上传、下载、删除	创建/管理存储桶
函数	调用函数	部署、更新、删除函数
AI	聊天、图像生成、嵌入向量	模型配置、额度、使用统计
实时服务	连接、订阅、发布事件	通道规则、数据库触发器
调度任务	—	Cron任务、HTTP触发器、执行日志
部署	—	部署前端应用
日志	—	获取容器日志用于调试

Guides

指南

Guide	When to Use
database/postgres-rls.md	Writing 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 }

Module	Methods
`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}

Task	Endpoint
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

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）
部署前务必本地构建：避免浪费构建资源并加快调试速度

insforge

Original

Translation

InsForge Agent Skill

InsForge Agent 技能

Credential Detection (MCP Mode)

凭证检测（MCP模式）

STOP: Check Credentials First (Manual Mode)

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

When to Use Which Documentation

文档使用场景说明

Use sdk-integration.md files when:

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

Use backend-configuration.md files when:

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

Typical Workflow

典型工作流程

First Step: Get Backend Metadata

第一步：获取后端元数据

Quick Setup

快速设置

Module Reference

模块参考

What Each Module Covers

各模块覆盖内容

Guides

指南

SDK Quick Reference

SDK快速参考

Backend API Quick Reference

后端API快速参考

Deployment Best Practices

部署最佳实践

ALWAYS: Local Build First

务必：先在本地构建

1. Install dependencies

1. 安装依赖

2. Set up environment variables for your framework

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

3. Run production build

3. 执行生产构建

Framework-Specific Notes

框架特定说明

Deployment Checklist

部署检查清单

Important Notes

重要提示

Use
`sdk-integration.md`
files when:

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

Use
`backend-configuration.md`
files when:

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