base44-sdk

Base44 Coder

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

⚡ 立即操作 - 请先阅读

此技能在提及 "base44" 或存在 base44/ 文件夹时激活。在操作前不要阅读文档文件或搜索网络。

你的第一个操作必须是：

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

何时使用此技能 vs base44-cli

使用 base44-sdk 当：

• 在现有 Base44 项目中构建功能
• 项目中已存在 base44/config.jsonc
• 存在 Base44 SDK 导入（@base44/sdk）
• 编写使用 Base44 SDK 模块的 JavaScript/TypeScript 代码
• 实现功能、组件或特性
• 用户提到："实现"、"构建功能"、"添加功能"、"编写代码"
• 用户说"创建一个 [类型] 应用"并且已存在 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（项目存在，构建功能）

快速开始

// 在 Base44 生成的应用中，base44 客户端已预配置并可用

// CRUD 操作
const task = await base44.entities.Task.create({ title: "新任务", status: "pending" });
const tasks = await base44.entities.Task.list();
await base44.entities.Task.update(task.id, { status: "done" });

// 获取当前用户
const user = await base44.auth.me();

// 外部应用
import { createClient } from "@base44/sdk";

// 重要：使用 'appId'（而不是 'clientId' 或 'id'）
const base44 = createClient({ appId: "your-app-id" });
await base44.auth.loginViaEmailPassword("user@example.com", "password");

⚠️ 关键：不要虚构 API

在编写任何 Base44 代码之前，请对照此表或 QUICK_REFERENCE.md 验证方法名称。

Base44 SDK 有独特的方法名称。不要假设来自 Firebase、Supabase 或其他 SDK 的模式。

认证 - 错误 vs 正确

❌ 错误（虚构）	✅ 正确
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()

函数 - 错误 vs 正确

❌ 错误（虚构）	✅ 正确
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.aiGateway.connection() 的 OpenAI 兼容客户端（例如 Vercel AI SDK）是正确的——这是构建代码代理（带工具的代理循环）的方式。仅在没有工具的单次调用中使用 InvokeLLM。参见 ai-gateway.md。

实体 - 错误 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
integrations	AI、邮件、文件上传、自定义 API	integrations.md
aiGateway	将 OpenAI 兼容 SDK 连接到 Base44 的 AI 网关	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 接口和类型。

获取类型化的实体、函数和代理： Base44 CLI 从你的项目资源（实体、函数、代理）生成类型，包括对 EntityTypeRegistry、FunctionNameRegistry 和 AgentNameRegistry 的增强，并将它们连接到你的项目中，从而无需手动设置即可获得自动完成和类型检查。关于如何生成类型，请使用 base44-cli 技能。

手动增强： 你也可以自己在 .d.ts 文件中增强注册表；参见 entities.md、functions.md 和 base44-agents.md 中的类型定义部分。

安装

安装 Base44 SDK：

npm install @base44/sdk

重要： 切勿假设或硬编码 @base44/sdk 包的版本。始终不带版本说明符安装以获取最新版本。

创建客户端（外部应用）

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

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

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

// ❌ 错误 - 不要使用这些：
// const base44 = createClient({ clientId: "your-app-id" });  // 错误
// const base44 = createClient({ id: "your-app-id" });        // 错误

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

可选参数：

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

带错误处理程序的示例：

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

模块选择

处理应用数据？

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

用户管理？

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

AI 功能？

• 与 AI 代理聊天 → agents（需要已登录用户）
• 创建新对话 → agents.createConversation()
• 管理对话 → agents.getConversations()
• 使用 AI 生成文本/JSON → integrations.Core.InvokeLLM()
• 生成图像 → integrations.Core.GenerateImage()
• 使用工具构建自定义代理（后端，AI 网关上的代理 SDK） → aiGateway（参见 ai-gateway.md）

自定义后端逻辑？

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

外部服务？

• 发送邮件 → 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 },  // 查询
  "-created_date",                             // 排序（降序）
  10,                                          // 限制
  0                                            // 跳过
);

受保护路由（检查认证）

const user = await base44.auth.me();
if (!user) {
  // 导航到你的自定义登录页面
  navigate('/login', { state: { returnTo: window.location.pathname } });
  return;
}

后端函数调用

// 前端
// ⚠️ invoke() 返回原始的 axios 响应——你的函数的 JSON 在 `.data` 上，
//    而不是顶层对象。它还会在非 2xx 时抛出异常（错误体在 err.response.data）。
const res = await base44.functions.invoke("processOrder", {
  orderId: "123",
  action: "ship"
});
const result = res.data; // ✅ 例如 res.data.success（res 本身是 { data, status, headers, … }）

// 后端函数（Deno）
import { createClientFromRequest } from "npm:@base44/sdk";

Deno.serve(async (req) => {
  const base44 = createClientFromRequest(req);
  const { orderId, action } = await req.json();
  // 使用服务角色处理以获得管理员访问权限
  const order = await base44.asServiceRole.entities.Orders.get(orderId);
  return Response.json({ success: true });
});

服务角色访问

在后端函数中使用 asServiceRole 进行管理员级别的操作：

// 用户模式 - 遵守权限
const myTasks = await base44.entities.Task.list();

// 服务角色 - 完全访问（仅后端）
const allTasks = await base44.asServiceRole.entities.Task.list();
const token = await base44.asServiceRole.connectors.getAccessToken("slack");

前端 vs 后端

功能	前端	后端
entities（用户数据）	是	是
auth	是	是
agents	是	是
functions.invoke()	是	是
functions.fetch()	是	是
integrations	是	是
aiGateway	否	是
analytics	是	是
appLogs	是	是
users	是	是
asServiceRole.*	否	是
asServiceRole.connectors（应用 OAuth）	否	是
asServiceRole.sso	否	是

后端函数使用 Deno.serve() 和 createClientFromRequest(req) 来获取正确认证的客户端。