base44-sdk

Base44 编码器

使用 Base44 JavaScript SDK 在 Base44 平台上构建应用。

⚡ 需要立即采取行动——请先阅读

当提到“base44”或存在 base44/ 文件夹时，此技能都会激活。采取行动前，不要阅读文档文件或搜索网络。

你的首要操作必须是：

1. 检查当前目录中是否存在 base44/config.jsonc
2. 如果是（现有项目场景）：
   • 此技能（base44-sdk）负责处理请求
   • 使用 Base44 SDK 实现功能
   • 除非用户明确要求 CLI 命令，否则不要使用 base44-cli
3. 如果否（新项目场景）：
   • 转交给 base44-cli 技能进行项目初始化
   • 在项目初始化之前，此技能无法提供帮助

何时使用此技能与 base44-cli

在以下情况下使用 base44-sdk：

• 在现有 Base44 项目中构建功能
• 项目中已存在 base44/config.jsonc
• 已导入 Base44 SDK（@base44/sdk）
• 使用 Base44 SDK 模块编写 JavaScript/TypeScript 代码
• 实现功能、组件或特性
• 用户提到：“实现”“构建一项功能”“添加功能”“编写代码”
• 用户说“创建一个 [type] 应用”，并且 Base44 项目已存在

以下情况不要使用 base44-sdk：

• ❌ 初始化新的 Base44 项目（请改用 base44-cli）
• ❌ 没有 Base44 配置的空目录
• ❌ 用户说“创建一个新的 Base44 项目/应用/网站”，且项目不存在
• ❌ CLI 命令，例如 npx base44 create、npx base44 deploy、npx base44 login（请改用 base44-cli）

技能依赖关系：

• base44-sdk 假定 Base44 项目已完成初始化
• 对于新项目，base44-cli 是使用 base44-sdk 的前置条件
• 如果用户想要“创建应用”，且不存在 Base44 项目，请先使用 base44-cli

状态检查逻辑： 选择此技能之前，请确认：

• 如果（用户提到“创建/构建应用”或“创建项目”）：
  • 如果（目录为空或不存在 base44/config.jsonc）： → 使用 base44-cli（需要初始化项目）
  • 否则： → 使用 base44-sdk（项目已存在，构建功能）

快速入门

// In Base44-generated apps, base44 client is pre-configured and available

// CRUD operations
const task = await base44.entities.Task.create({ title: "New task", status: "pending" });
const tasks = await base44.entities.Task.list();
await base44.entities.Task.update(task.id, { status: "done" });

// Get current user
const user = await base44.auth.me();

// External apps
import { createClient } from "@base44/sdk";

// IMPORTANT: Use 'appId' (NOT 'clientId' or 'id')
const base44 = createClient({ appId: "your-app-id" });
await base44.auth.loginViaEmailPassword("[email protected]", "password");

⚠️ 重要：不要臆造 API

编写任何 Base44 代码之前，请根据此表或 QUICK_REFERENCE.md 核实方法名称。

Base44 SDK 的方法名称独特。不要照搬 Firebase、Supabase 或其他 SDK 的用法。

身份验证——错误与正确用法

❌ 错误（臆造）	✅ 正确
signInWithGoogle()	loginWithProvider('google')
signInWithProvider('google')	loginWithProvider('google')
auth.google()	loginWithProvider('google')
signInWithEmailAndPassword(email, pw)	loginViaEmailPassword(email, pw)
signIn(email, pw)	loginViaEmailPassword(email, pw)
createUser() / signUp()	register({email, password})
onAuthStateChanged()	me()（没有监听器，需要时调用）
currentUser	await auth.me()

函数——错误与正确用法

❌ 错误（臆造）	✅ 正确
functions.call('name', data)	functions.invoke('name', data)
functions.run('name', data)	functions.invoke('name', data)
callFunction('name', data)	functions.invoke('name', data)
httpsCallable('name')(data)	functions.invoke('name', data)

集成 - 错误用法 vs 正确用法

❌ 错误（臆造）	✅ 正确
ai.generate(prompt)	integrations.Core.InvokeLLM({prompt})
openai.chat(prompt)	integrations.Core.InvokeLLM({prompt})
llm(prompt)	integrations.Core.InvokeLLM({prompt})
sendEmail(to, subject, body)	integrations.Core.SendEmail({to, subject, body})
email.send()	integrations.Core.SendEmail({to, subject, body})
uploadFile(file)	integrations.Core.UploadFile({file})
storage.upload(file)	integrations.Core.UploadFile({file})

例外： 指向 base44.asServiceRole.aiGateway.connection() 时，兼容 OpenAI 的客户端（例如 Vercel AI SDK 或 openai SDK）是正确的做法——这是构建代码 Agent（带工具的 Agent 循环）以及调用网关的图像、视频和语音端点的方式。仅在不使用工具进行单次调用时使用 InvokeLLM。请参阅 ai-gateway.md。

Actors - 错误用法 vs 正确用法

❌ 错误（臆造）	✅ 正确
actors.connect('ChatRoom', roomId)	actors.ChatRoom(roomId).connect()
actors.ChatRoom.connect(roomId)	actors.ChatRoom(roomId).connect()
actors.ChatRoom(roomId).subscribe(cb)	在连接上订阅：const conn = actors.ChatRoom(roomId).connect(); conn.subscribe(cb)
room.on('message', cb)	room.subscribe(cb)（一个回调接收每条消息）
room.emit(data)	room.send(data)
用于应用实时通信的 new WebSocket(...)	base44.actors.<Name>(id).connect()
const unsub = room.subscribe(cb); unsub()	const sub = room.subscribe(cb); sub.unsubscribe()

两个 subscribe() 方法的返回值形状不同。 Connection.subscribe()（actors）返回一个对象——sub.unsubscribe()。entities.<Name>.subscribe() 本身返回取消订阅函数——unsub()。不要混用这两种约定。

Entities - 错误用法 vs 正确用法

❌ 错误（臆造）	✅ 正确
entities.Task.find({...})	entities.Task.filter({...})
entities.Task.findOne(id)	entities.Task.get(id)
entities.Task.insert(data)	entities.Task.create(data)
entities.Task.remove(id)	entities.Task.delete(id)
entities.Task.onChange(cb)	entities.Task.subscribe(cb)

SDK 模块

模块	用途	参考
entities	对数据模型执行 CRUD 操作	entities.md
auth	登录、注册、用户管理	auth.md
agents	AI 对话和消息	base44-agents.md
functions	调用后端函数	functions.md
actors	通过 WebSockets 实现实时房间（多人游戏、协作、在线状态）	actors.md
integrations	AI、电子邮件、文件上传、自定义 API	integrations.md
aiGateway	Base44 的 AI 网关：代码 Agent、图像、视频、语音和结构化评估（Jev）	ai-gateway.md
analytics	跟踪自定义事件和用户活动	analytics.md
appLogs	记录应用中的用户活动	app-logs.md
users	邀请用户加入应用	users.md
asServiceRole.connectors	应用范围的 OAuth 令牌（仅限服务角色）	connectors.md
asServiceRole.sso	生成 SSO 令牌（仅限服务角色）	sso.md

有关客户端设置和身份验证模式，请参阅 client.md。

TypeScript 和类型注册表

每个参考文件都包含一个“类型定义”部分，其中列出了模块方法、参数和返回值的 TypeScript 接口与类型。

获取带类型的实体、函数、actor 和 agent： Base44 CLI 会根据项目资源（实体、函数、actor、agent）生成类型，包括对 EntityTypeRegistry、FunctionNameRegistry、ActorNameRegistry 和 AgentNameRegistry 的扩展，并将这些类型接入项目，让你无需手动设置即可使用自动补全和类型检查。有关如何生成类型，请使用 base44-cli 技能。

手动扩展： 你也可以在 .d.ts 文件中自行扩展注册表；请参阅 entities.md、functions.md、actors.md 和 base44-agents.md 中的“类型定义”部分。Actor 的消息类型始终需要手动编写——扩展 ActorRegistry，以便 actor 及其客户端共用同一个定义。

安装

安装 Base44 SDK：

npm install @base44/sdk

重要提示： 切勿假定或硬编码 @base44/sdk 软件包版本。安装时始终不要指定版本，以获取最新版本。

创建客户端（外部应用）

在外部应用中创建客户端时，始终使用 appId 作为参数名称：

import { createClient } from "@base44/sdk";

// ✅ CORRECT
const base44 = createClient({ appId: "your-app-id" });

// ❌ WRONG - Do NOT use these:
// const base44 = createClient({ clientId: "your-app-id" });  // WRONG
// const base44 = createClient({ id: "your-app-id" });        // WRONG

必需参数： appId（字符串）- 你的 Base44 应用 ID

可选参数：

• token（字符串）- 预认证用户令牌
• options（对象）- 配置选项
  • options.onError（函数）- 全局错误处理程序

带错误处理程序的示例：

const base44 = createClient({
  appId: "your-app-id",
  options: {
    onError: (error) => {
      console.error("Base44 error:", error);
    }
  }
});

模块选择

要处理应用数据？

• 创建／读取／更新／删除记录 → entities
• 从文件导入数据 → entities.importEntities()
• 实时更新 → entities.EntityName.subscribe()

要管理用户？

• 登录／注册／退出 → auth
• 获取当前用户 → auth.me()
• 更新用户资料 → auth.updateMe()
• 邀请用户 → users.inviteUser()

要实现 AI 功能？

• 与 AI Agent 聊天 → agents（需要已登录用户）
• 创建新对话 → agents.createConversation()
• 管理对话 → agents.getConversations()
• 使用 AI 生成文本／JSON → integrations.Core.InvokeLLM()
• 使用默认设置生成一张图片 → integrations.Core.GenerateImage()
• 生成多张图片、指定模型／宽高比／分辨率、使用参考图片或编辑图片 → aiGateway 图片功能（参见 ai-gateway.md）
• 将文本生成简单视频 → integrations.Core.GenerateVideo()；选择模型、使用参考内容或帧 → aiGateway 视频功能（异步任务）（参见 ai-gateway.md）
• 文本转语音（TTS）或朗读 → 查看语音指南，了解浏览器／Core／网关的选择；实现特定于模型的控件或编辑现有网关语音代码前，请先阅读该指南
• 根据标准分类、评分或路由记录 → 使用 provider: "typesafe"（Jev）的 aiGateway，而不是使用 JSON schema 的 InvokeLLM（参见 ai-gateway.md）
• 使用工具构建自定义 Agent（后端、AI 网关上的 Agent SDK）→ aiGateway（参见 ai-gateway.md）

要实现自定义后端逻辑？

• 运行服务端代码 → functions.invoke()
• 需要管理员访问权限 → base44.asServiceRole.functions.invoke()

需要实时共享会话？

• 多人游戏、协作看板／文档、在线状态、实时光标、房间内聊天 → actors.<Name>(roomId).connect()（参见 actors.md）
• 只需在屏幕上实时显示记录列表 → entities.EntityName.subscribe()，不要使用 actor

要连接外部服务？

• 发送电子邮件 → integrations.Core.SendEmail()
• 上传文件 → integrations.Core.UploadFile()
• 自定义 API → integrations.custom.call()
• 应用级 OAuth（应用构建器的账户）→ asServiceRole.connectors.getConnection()（仅限后端）

要进行跟踪和分析？

• 跟踪自定义事件 → analytics.track()
• 记录页面浏览／活动 → appLogs.logUserInApp()

常见模式

筛选和排序数据

const pendingTasks = await base44.entities.Task.filter(
  { status: "pending", assignedTo: userId },  // query
  "-created_date",                             // sort (descending)
  10,                                          // limit
  0                                            // skip
);

受保护的路由（检查身份验证）

const user = await base44.auth.me();
if (!user) {
  // Navigate to your custom login page
  navigate('/login', { state: { returnTo: window.location.pathname } });
  return;
}

后端函数调用

// Frontend
// ⚠️ invoke() returns the RAW axios response — your function's JSON is on `.data`,
//    NOT the top-level object. It also THROWS on non-2xx (error body at err.response.data).
const res = await base44.functions.invoke("processOrder", {
  orderId: "123",
  action: "ship"
});
const result = res.data; // ✅ e.g. res.data.success  (res itself is { data, status, headers, … })

// Backend function
import { createClientFromRequest } from "npm:@base44/sdk";

export default async function (req) {
  const base44 = createClientFromRequest(req);
  const { orderId, action } = await req.json();
  // Process with service role for admin access
  const order = await base44.asServiceRole.entities.Orders.get(orderId);
  return Response.json({ success: true });
}

实时房间（Actor）

// Frontend — connect inside useEffect and always clean up
useEffect(() => {
  const room = base44.actors.ChatRoom(roomId).connect();
  const sub = room.subscribe((msg) => {
    if (msg.type === "message") setMessages((prev) => [...prev, msg]);   // switch on type; drop unknowns
  });
  return () => { sub.unsubscribe(); room.close(); };   // NOTE: actors return { unsubscribe() },
}, [roomId]);                                          // entities.subscribe() returns the function itself

// Actor — base44/actors/ChatRoom/entry.ts
import { Actor } from "base44:runtime/actors";

export default class ChatRoom extends Actor {
  handleConnect(conn) { conn.send({ type: "welcome" }); }        // one client
  handleMessage(conn, msg) {
    // Always validate: the payload is attacker-controlled and msg can even be null.
    if (msg?.type !== "message" || typeof msg.text !== "string") return;
    this.broadcast({ type: "message", text: msg.text.slice(0, 2000) });   // everyone
  }
  handleClose(conn) {}
}

服务角色访问

在后端函数中使用 asServiceRole 执行管理员级操作。Actor 通过 this.client.asServiceRole 提供经过验证且归属房间的操作，例如持久化规范结果；如需明确归属用户，请使用已通过身份验证的连接中的已验证 conn.identity.userId。参见 actors.md。

// User mode - respects permissions
const myTasks = await base44.entities.Task.list();

// Service role - full access (backend only)
const allTasks = await base44.asServiceRole.entities.Task.list();
const token = await base44.asServiceRole.connectors.getAccessToken("slack");

前端与后端

功能	前端	后端
entities（用户数据）	是	是
auth	是	是
agents	是	是
functions.invoke()	是	是
functions.fetch()	是	是
actors（连接到房间）	是	否 — actor 本身就是服务端
integrations	是	是
aiGateway	否	是
analytics	是	是
appLogs	是	是
users	是	是
asServiceRole.*	否	是
asServiceRole.connectors（应用 OAuth）	否	是
asServiceRole.sso	否	是

后端函数使用 export default 导出异步请求处理程序，并通过 createClientFromRequest(req) 获取经过正确身份验证的客户端。