Instant 官方 AGENTS.md 实战指南：用 InstantDB 构建 AI 编码应用的完整规则手册

后端数据库【免费下载链接】instantInstant is the best backend for AI-coded apps. You get auth, permissions, storage, presence, and streams — everything you need to ship apps your users will love.项目地址https://gitcode.com/gh_mirrors/inst/instant点击查看免费下载Instant 是面向客户端的前端数据库被称为 Modern Firebase内置查询、事务、鉴权、权限、存储、实时同步与离线能力。本指南以 Instant 官方分发给 AI Agent 的AGENTS.md位于 client/packages/create-instant-app/template/rules/AGENTS.md为骨架系统讲解其约束的 SDK 选型、CLI 应用管理流程、查询操作符全集、权限规则写法、存储与 Rooms 实践并结合本仓库源码验证每条规则的真实实现帮助开发者与 AI 编码助手高效、正确地构建完整应用。Instant 是什么一套面向客户端的后端InstantDB简称 Instant是一套客户端数据库查询、事务、权限、实时订阅等逻辑全部在客户端 SDK 中完成开发者无需自建服务端即可获得数据库能力。它支持实时real-time同步、离线offline支持、内建鉴权auth、细粒度权限permissions与文件存储storage。官方 SDK 分为客户端与服务端两类见 client/packages 目录下各包SDK 包名适用场景instantdb/coreVanilla JS无框架instantdb/reactReact含 Next.jsinstantdb/react-nativeReact Native / Expoinstantdb/solidjsSolidJSinstantdb/svelteSvelteinstantdb/vueVueinstantdb/adminJS/TS 服务端后端 SDKinstantdbPython 后端 SDK安装 SDK 前先确认项目使用的包管理器npm / pnpm / bun再安装对应最新版本。React 项目默认搭配 Next.js 与 Tailwind CSSPython 项目则参考 Python 文档。管理 Instant 应用CLI 工作流前置检查schema、perms 与凭据接手一个 Instant 应用时先在项目中寻找两类关键文件instant.schema.ts—— 定义数据模型与索引instant.perms.ts—— 定义权限规则.env或其他 env 文件 —— 保存app id与admin token。如果 schema/perms 文件存在但缺少 app id / admin token需要向用户询问凭据位置或创建新应用。创建新应用init-without-filesnpx instant-cli init-without-files --title APP_NAME该命令只创建应用并输出app id与admin token不生成本地文件开发者将其存入 env 文件。对应的 CLI 实现位于 client/packages/cli/src/commands/initWithoutFiles.ts命令要求--title参数并支持--temp创建临时应用与--org-id等选项创建成功后以 JSON 形式打印appId与adminToken。若未登录会抛出NotAuthedError提示先执行npx instant-cli login。登录流程在 Instant 官网免费注册或登录执行npx instant-cli login完成 CLI 鉴权重新运行 init 命令。拉取远端配置pull已有 app id / admin token 但缺少 schema/perms 文件时npx instant-cli pull --yes从实现看client/packages/cli/src/commands/pull.tspull默认拉取all也可指定schema或perms。推送 schema 变更编辑instant.schema.ts后npx instant-cli push schema --yes变更语义新增字段 添加additions缺失字段 删除deletions。重命名字段时使用--renamenpx instant-cli push schema --rename posts.author:posts.creator stores.owner:stores.manager --yespush命令支持-a --app指定目标应用、--skip-check-types跳过服务端类型检查、-p --package自动安装缺失的 SDK还可用环境变量INSTANT_SCHEMA_FILE_PATH与INSTANT_PERMS_FILE_PATH覆盖 schema/perms 文件位置见 client/packages/cli/src/index.ts。底层推送流程client/packages/cli/src/lib/pushSchema.ts值得注意CLI 会先从远端拉取当前 schema本地文件必须export default schema且导出类型为InstantSchemaDef然后调用diffSchemas计算差异并渲染变更计划client/packages/cli/src/renderSchemaPlan.ts交互模式下会询问 Push these changes? 确认--yes则自动确认推送后若返回indexing-jobs还会等待索引任务完成。推送权限变更编辑instant.perms.ts后npx instant-cli push perms --yesCLI 临时查询npx instant-cli query { posts: {} } --adminquery命令必须携带上下文标志之一--admin、--as-email email或--as-guest并支持--app id。实现client/packages/cli/src/commands/query.ts限定四个上下文只能选其一--admin/--as-email/--as-guest/--as-token查询体使用 JSON5 解析后 POST 到/admin/query端点。CRITICAL 查询指南InstaQL 完整操作符排序规则Ordering: order: { field: asc | desc } Example: $: { order: { dueDate: asc } } Notes: - Field must be indexed typed in schema - Cannot order by nested attributes (e.g. owner.name)必须在 schema 中为想要过滤或排序的字段建立索引indexed否则查询会报错。这是 AGENTS.md 反复强调的 CRITICAL 规则。where操作符全集Equality: { field: value } Inequality: { field: { $ne: value } } Null checks: { field: { $isNull: true | false } } Comparison: $gt, $lt, $gte, $lte (indexed typed fields only) Sets: { field: { $in: [v1, v2] } } Substring: { field: { $like: Get% } } // case-sensitive { field: { $ilike: %get% } } // case-insensitive Logic: and: [ {...}, {...} ] or: [ {...}, {...} ] Nested fields: relation.field: value当前 Instant 完整支持的操作符仅此一套没有$exists、$nin、$regexstartsWith/endsWith/includes均由$like大小写敏感与$ilike大小写不敏感承担。类型定义见 client/packages/core/src/queryTypes.ts运行时的$like/$ilike匹配器与$isNull转换逻辑见 client/packages/core/src/instaql.ts。分页限制分页键limit、offset、first、after、last、before只能在顶层命名空间使用不能用于嵌套关系否则报错。查询使用原则React 中必须遵守 Hooks 规则hook 不能条件出现不确定某个特性时查阅官方文档对应章节。CRITICAL 权限指南Instant 权限规则CELInstant 权限使用类 CEL 表达式编写位于instant.perms.ts。data.ref访问关联属性data.ref(path.to.attr)用于访问关联属性linked attributes永远返回列表路径必须以属性结尾不能停在关系上。正确写法auth.id in data.ref(post.author.id) // auth.id 在 author id 列表中 data.ref(owner.id) [] // 没有 owner错误写法auth.id in data.post.author.id auth.id in data.ref(author) data.ref(admins.id) auth.id auth.id data.ref(owner.id) data.ref(owner.id) null data.ref(owner.id).length 0注意data.ref返回列表因此不能与标量比较 auth.id、不能判null也不能调用.length。auth.ref访问用户关联属性与data.ref相同但路径必须以$user开头返回列表。正确写法admin in auth.ref($user.role.type) auth.ref($user.role.type)[0] admin错误写法auth.ref(role.type) auth.ref($user.role.type) admin不支持的能力newData.ref(x) data.ref(someVar .members.id)即newData.ref不支持data.ref参数必须是字面量字符串不能拼接变量。$users权限默认行为操作默认值viewauth.id data.idupdatefalsedeletefalse不可覆盖createtrue任何人可注册可覆盖view、update、create但不能覆盖delete。create规则在注册流程signup中执行而非transact时执行用于限制注册或校验extraFieldsextraFields必须有显式create规则否则注册会被阻止防止未经校验的写入。$files权限默认权限全部为false需按需覆盖data.ref不适用于$files权限应使用data.path.startsWith(...)或data.path.endsWith(...)编写基于路径的规则。字段级权限在保持实体公开的同时限制敏感字段访问{ $users: { allow: { view: true }, fields: { email: auth.id data.id } } }要点字段规则会覆盖实体级view对该字段而言适用于在公开实体上隐藏敏感数据邮箱、手机号等。CRITICAL 存储指南Instant Storage铁律不要用字符串存 URL如果应用展示图片或文件必须使用 Instant Storage不要将 URL 作为字符串属性存在实体上。种子脚本seed scripts也不得用占位图 URL如 picsum.photos伪造文件支持。上传会自动创建$files实体通过 schema 将$files关联到业务数据再通过关系查询拿到 URL。三个 CRITICAL 约束使用 Storage 时schema 实体中必须包含$files$files实体只能通过db.storage.uploadFile创建不能用db.transact创建也不能通过事务设置url上传与关联的标准模式如下。完整示例上传图片并关联到文章entities: { $files: i.entity({ path: i.string().unique().indexed(), url: i.string(), }), posts: i.entity({ caption: i.string(), }), }, links: { postImage: { forward: { on: posts, has: one, label: image }, reverse: { on: $files, has: many, label: posts }, }, } // 上传并把返回的 file id 关联到业务实体 const postId id(); const { data } await db.storage.uploadFile(posts/${postId}/${file.name}, file); db.transact( db.tx.posts[postId].update({ caption }).link({ image: data.id }) ); // 通过关系查询拿到 URL const { data } db.useQuery({ posts: { image: {} } }); img src{post.image.url} /uploadFile(path, file)的底层实现在 client/packages/core/src/Reactor.js 与 client/packages/core/src/StorageAPI.tsSDK 层 API 见 client/packages/core/src/index.ts。CRITICAL Rooms 指南Presence 与 Topics基本认知Presence 与 topics 的 hooks 位于db.rooms上房间对象作为第一个参数传入房间对象本身没有usePresence或publishPresence方法Rooms 承载两种**临时ephemeral**原语presence光标位置、在线状态和 topics实时反应。只用它们存放无需持久化的数据——通过transact持久化的数据本身就会实时同步给所有订阅客户端只有数据故意设计为临时时才使用 Rooms。Presence连接期内的共享状态每个 peer 发布一个 presence 对象房间内所有其他 peer 可读随连接保留断线自动清理。const room db.room(chat, main); const { user, peers, publishPresence } db.rooms.usePresence(room, { initialPresence: { x: 0, y: 0 }, }); // peers 以 peerId 为键不是数组。用 Object.values(peers) 遍历 publishPresence({ x: 50, y: 50 });Topics不保留的实时事件Topic payload 不被保留peer 只能看到自己监听期间触发的事件。const room db.room(chat, main); const publishEmoji db.rooms.usePublishTopic(room, emoji); publishEmoji({ name: fire }); db.rooms.useTopicEffect(room, emoji, (payload) { animateEmoji(payload.name); });Presence 发布的核心实现在 client/packages/core/src/Reactor.jsSDK 层封装见 client/packages/core/src/index.ts。最佳实践初始化时传入 schema始终在初始化时传入schema以获得查询与事务的类型安全import schema from /instant.schema; // 客户端 import { init } from instantdb/react; // 或对应 Instant SDK const clientDb init({ appId, schema }); // 服务端 import { init } from instantdb/admin; const adminDb init({ appId, adminToken, schema });用id()生成实体 id新实体一律使用id()生成 idimport { id } from instantdb/react; // 或对应 Instant SDK import { clientDb } from /lib/clientDb; clientDb.transact(clientDb.tx.todos[id()].create({ title: New Todo }));用 Instant 工具类型建模import { AppSchema } from /instant.schema; type Todo InstaQLEntityAppSchema, todos; // 来自 clientDb.useQuery({ todos: {} }) type PostsWithProfile InstaQLEntity AppSchema, posts, { author: { avatar: {} } } ; // 来自 clientDb.useQuery({ posts: { author: { avatar: {} } } })用db.useAuth/db.subscribeAuth管理登录态import { clientDb } from /lib/clientDb; // React / React Native 使用 db.useAuth function App() { const { isLoading, user, error } clientDb.useAuth(); if (isLoading) { return null; } if (error) { return Error message{error.message} /; } if (user) { return Main /; } return Login /; } // Vanilla JS 使用 db.subscribeAuth function App() { renderLoading(); db.subscribeAuth((auth) { if (auth.error) { renderAuthError(auth.error.message); } else if (auth.user) { renderLoggedInPage(auth.user); } else { renderSignInPage(); } }); }注册时用extraFields写入自定义属性将extraFields传给任意 sign-in 方法可在用户创建时原子写入自定义$users属性这些字段必须在 schema 的$users上定义为可选属性。用返回值中的created布尔值判断是否为新用户并初始化数据// 注册时设置属性 const { user, created } await db.auth.signInWithMagicCode({ email, code, extraFields: { nickname, createdAt: Date.now() }, }); // 为新用户初始化数据 if (created) { db.transact([ db.tx.settings[id()] .update({ theme: light, notifications: true }) .link({ user: user.id }), ]); }总结AGENTS.md是 Instant 官方为 AI 编码助手设计的操作手册其核心规则可归纳为四条主线schema 即索引过滤/排序字段必须 indexed typed、权限即 CELdata.ref/auth.ref返回列表、$files用路径规则、存储即$filesURL 只来自 Storage 上传而非字符串属性、Rooms 即临时presence/topics 只放不持久化的数据。开发者或 AI Agent遵循本指南配合 client/packages/cli 的init-without-files/pull/push/query命令与 client/packages/core 的源码实现即可快速、正确地搭建类型安全、权限完备、支持实时与离线的高质量 Instant 应用。赞分享后端数据库【免费下载链接】instantInstant is the best backend for AI-coded apps. You get auth, permissions, storage, presence, and streams — everything you need to ship apps your users will love.项目地址https://gitcode.com/gh_mirrors/inst/instant点击查看免费下载相关推荐InstantDB 实战手册用 Instant现代 Firebase为 AI 编码应用构建 Schema、权限与实时功能InstantDB 实战手册用 Instant现代 Firebase为 AI 编码应用构建 Schema、权限与实时功能 Instant在仓库中亦称 I后端数据库用 InstantDB 为 AI 编码应用构建实时后端从包选择到完整示例的实战指南用 InstantDB 为 AI 编码应用构建实时后端从包选择到完整示例的实战指南 导读本文基于仓库 client/sandbox/task tracker后端数据库用 TanStack Start 构建实时全栈应用InstantDB create-instant-app 官方示例深度解析用 TanStack Start 构建实时全栈应用InstantDB create instant app 官方示例深度解析 InstantDB 官方在仓库中后端数据库上一篇UE4SS 在 UE5.4 游戏中的 FText 构造函数签名问题终极解决方案下一篇CockroachDB/errors迁移指南从标准errors和pkg/errors无缝升级创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考