base44-sandbox

云端沙盒中的 Base44

使用你自己的编码 Agent，在 Base44 的云端沙盒中编写 Base44 应用代码。没有本地检出：你通过沙盒工具（经由 MCP 或 base44 sandbox CLI）读取、写入和运行文件，平台会根据你编写的内容进行构建和部署。

有关如何连接到沙盒（MCP 端点或 base44 sandbox CLI、read_file / write_file / edit_file / run_command / grep / list_directory / create_checkpoint 工具——这些工具在 CLI 中使用较短的名称（sandbox read / sandbox write / sandbox edit / sandbox run / sandbox grep / sandbox ls / sandbox checkpoint）、编辑→预览→验证循环、持久化和并发），请使用 base44-remote-dev 技能。连接后，此技能将介绍你可以编写什么以及如何编写。

请先查看这些参考资料。 此技能及其同级技能（base44-remote-dev、base44-sdk）是准确信息的来源——请先查阅它们，再搜索网络。请参阅参考顺序与完整 README。

⚡ 核心理念：写入文件 就是 部署

你正在处理远程应用，而不是本地检出。项目级 CLI 工作流不适用——绝不要运行 base44 deploy、base44 functions deploy、base44 actors deploy、base44 actors delete、base44 ... push、base44 create 或 base44 scaffold。这些命令都假定有一个本地项目，并要求手动部署，而这里并不存在这样的部署步骤。

相反：只要你将资源文件写入沙盒——无论是后端函数、actor、实体还是 Agent——平台就会从那里部署/同步它。 你的写入会自动提交（防抖时间约为 5 秒）并上线。你不需要运行，也不得等待任何 deploy / push 命令。

唯一例外是连接器。 OAuth 连接器不是以文件形式编写的；你可以通过 MCP 连接器工具，或专用的、无需项目的 base44 connectors 命令（使用 --app-id，且无需本地项目），根据远程应用的 ID 为其设置连接器。请参阅下文的连接器（OAuth 集成）。

你仍可使用 run_command（CLI 中的 sandbox run）执行常规检查（例如 npm run build、npx tsc --noEmit、npm run lint）和预览——这是验证，不是部署。请参阅 base44-remote-dev 中的编辑→预览→验证循环。

目前可以编写的内容

资源	沙盒中的状态
后端函数（base44/functions/）	✅ 支持——写入文件即可；它们会从沙盒部署。
Actors（base44/actors/）	✅ 支持——写入 entry.ts；actor 会从沙盒部署。删除入口文件即可将其移除。
实体（base44/entities/）	✅ 支持——写入 .jsonc 架构文件；它会自动同步。无需执行 entities push。
Agents（base44/agents/）	✅ 支持——写入 .jsonc 配置文件；它会自动同步。无需执行 agents push。
前端代码（src/…）	✅ 支持——照常编辑；HMR/预览会反映更改。使用 base44-sdk 技能了解 SDK API 的用法。
连接器（OAuth 集成）	✅ 支持——通过下方的连接流程（MCP 工具或 base44 connectors）进行设置，而不是通过写入文件。

后端函数

后端函数位于 base44/functions/ 中，每个函数对应一个目录（名称采用 kebab-case）。在沙盒中，你只需在 base44/functions/<name>/ 下直接创建 entry.ts 文件——无需 function.jsonc（沙盒会根据目录推断函数；此模式下会忽略配置文件）：

base44/functions/
  process-order/
    entry.ts

入口文件——导出一个异步请求处理程序作为 export default，并在 npm 包前使用 npm: 前缀：

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

export default async function (req) {
  const base44 = createClientFromRequest(req);   // inherits the caller's auth
  const { orderId } = await req.json();
  const order = await base44.entities.Orders.get(orderId);
  return Response.json({ success: true, order });
}

约定：

• 目录和函数名称采用 kebab-case；入口文件通常为 entry.ts。
• 使用 createClientFromRequest(req) 创建处于调用方身份验证上下文中的客户端；使用 base44.asServiceRole.… 执行管理员级操作。
• 从 base44:runtime 使用 secrets.get("KEY") 读取密钥（import { secrets } from "base44:runtime"；在应用设置中配置）。
• 使用 Response.json(body, { status }) 返回响应；处理错误并设置适当的状态码。

掌握这些内容就足以正确编写函数。若要了解更深入的细节和更多示例（服务角色、密钥、常见错误），请参阅 base44-cli 技能的参考文档：functions-create.md——但请忽略其中的“Deploying Functions”/CLI 部分以及有关 function.jsonc 的说明；这些内容针对本地项目，不适用于沙盒（在这里你只需编写 entry.ts）。

从前端调用函数： base44.functions.invoke(name, data) 会返回 原始 axios 响应——函数返回的 JSON 位于 .data 中（const result = res.data），而不是顶层对象；对于非 2xx 响应，它会抛出错误（错误响应体位于 err.response.data）。详情请参阅 base44-sdk 技能的 functions.md。

Actors（实时）

Actors 是基于 WebSocket 的有状态实时服务器房间——每个房间 ID 对应一个实时实例，同一 ID 的所有连接者共享该实例。当用户在同一个共享会话中实时互动时，可以使用 Actor：多人游戏、协作白板/文档、在线状态和实时光标、房间内聊天、实时拍卖。仅实时列出记录的页面不需要 Actor（base44.entities.Thing.subscribe() 已足够）。

在 base44/actors/ 中为每个 Actor 创建一个目录，其中包含 entry.ts。只需编写文件——它就会部署；不要运行 base44 actors deploy 或 deploy。 使用纯 JavaScript 编写，和后端函数完全一样——不要添加类型注解；该文件使用 .ts 扩展名只是因为入口格式要求如此。Actor 没有测试工具（它处理 WebSocket，而非请求）——请在预览中验证。

base44/actors/
  ChatRoom/
    entry.ts

// base44/actors/ChatRoom/entry.ts
import { Actor } from "base44:runtime/actors";   // the only import that resolves the base class

export default class ChatRoom extends Actor {
  async handleStart() {
    // Runs on every wake — instance fields are lost when the room hibernates.
    this.history = (await this.storage.get("history")) ?? [];
  }
  handleConnect(conn) {
    conn.send({ type: "history", messages: this.history });   // this client only
  }
  async handleMessage(conn, msg) {
    if (msg?.type !== "message" || typeof msg.text !== "string") return;   // validate everything
    const authorUserId = conn.identity?.type === "authenticated" ? conn.identity.userId : null;
    const entry = { authorUserId, text: msg.text.slice(0, 2000) };
    this.history = [...this.history, entry].slice(-100);
    await this.storage.put("history", this.history);
    this.broadcast({ type: "message", ...entry });            // the whole room
  }
  handleClose(conn) {}
}

约定：

• PascalCase 文件夹名——它会成为 JavaScript 类绑定，因此只能使用 [A-Za-z_][A-Za-z0-9_]*（不能包含 -、.、/），不能使用 JS 保留字，且不能有嵌套文件夹。
• 入口必须默认导出一个继承自 Actor 的类；类名本身不影响功能。
• 处理器：handleConnect(conn) / handleMessage(conn, msg) / handleClose(conn)，以及可选的 handleStart() 和 handleWake(key)。对于必须自行推进的房间（游戏循环、可见倒计时），请重写 shouldTick()；当它返回 true 时，平台会每隔 tickIntervalMs（默认值为 100）调用 handleTick()。切勿重写 onStart / onAlarm。
• 将任何不能丢失的数据持久化到 this.storage，并在 handleStart() 中重新载入——房间休眠时，实例字段会重置。
• 使用 this.broadcast(...) 广播房间范围内的状态；使用 conn.send(...) 发送与单个客户端有关的事件。
• Actor 使用直接连接；SDK 会处理令牌签发和连接身份验证。conn.identity 中保存已验证的认证用户 userId 或匿名用户 anonymousId，且在休眠后仍然有效。归属标记和权限判断应使用已认证的 userId；上面的访客聊天消息使用 authorUserId: null。
• 将客户端选择的 conn.id 仅用于内部重连记录。公开在线状态应使用服务端分配的独立参与者 ID；切勿广播重连 ID，也不要将其视为作者身份或权限的证明。
• this.client 使用匿名角色（受 RLS 控制）。this.client.asServiceRole 提供管理员级别的实体访问、函数调用和集成，用于经过验证且归房间所有的工作。两者都不会模拟用户：应使用来自已认证 conn.identity.userId 的显式字段标记记录归属。
• Actor 是权威来源：客户端发送输入，Actor 负责验证并广播。切勿信任客户端计算的结果。
• 持久化结果（完成的绘图、聊天记录）：由Actor将经过验证的结果存入 this.storage，并通过 this.client.asServiceRole 持久化规范实体记录，使用房间实例 ID 作为幂等写入的键。保留待写入的数据，并在需要时通过计划唤醒进行重试。广播结果，并在客户端（重新）连接时重新发送以供显示；前端只能写入归用户所有的记录。规范结果实体的写入权限应仅限服务端。
• Actor 不会收到应用密钥或私有数据源绑定。需要这些信息的操作应放在后端函数中，并由 Actor 调用。ACTOR_TOKEN_SECRET 会自动配置；请勿在设置期间创建或覆盖它，因为更改该密钥会轮换 Actor 的密钥。
• Actor 不支持自动化。

完整的编写参考（命名、生命周期、存储／休眠、计划唤醒、房间和发现）请参阅 base44-cli 技能中的 actors-create.md——但忽略其中的“Deploying Actors”／CLI 章节，这些章节假定使用本地项目。

从前端连接： base44.actors.ChatRoom(roomId).connect() 会返回一个连接，其中包含 .subscribe(cb)、.send(data) 和 .close()。请在 useEffect 中连接，并清理这两项。请参阅 base44-sdk 技能中的 actors.md。

实体

在 base44/entities/ 中为每个实体创建一个 .jsonc 文件。只需编写文件——它会自动同步；不要运行 base44 entities push 或 deploy。

• 文件名：{kebab-case}.jsonc——例如，名为 TeamMember 的实体对应 team-member.jsonc。
• **实体 name：**PascalCase，仅限字母数字字符（/^[a-zA-Z0-9]+$/）。
• 字段名：snake_case。

// base44/entities/task.jsonc
{
  "name": "Task",
  "type": "object",
  "properties": {
    "title": { "type": "string", "description": "Task title" },
    "status": { "type": "string", "enum": ["todo", "doing", "done"], "default": "todo" },
    "due_date": { "type": "string", "format": "date" },
    "board_id": { "type": "string", "description": "Owning board" }
  },
  "required": ["title"]
}

字段类型：string、number、integer、boolean、array、object、binary。字符串格式包括 date、date-time、email、uri、uuid、file、richtext。如需了解完整的架构细节和行级安全（RLS），请参阅 base44-cli 参考文档 entities-create.md 和 rls-examples.md——但忽略其中的 entities push / deploy 部分；沙盒会为你同步文件。

Agent

在 base44/agents/ 中为每个 Agent 创建一个 .jsonc 文件。只需编写文件——它会自动同步；不要运行 base44 agents push 或 deploy。

• 文件名：{agent_name}.jsonc——例如，support_agent.jsonc。
• Agent name：/^[a-z0-9_]+$/（小写字母、下划线，长度为 1–100 个字符）。

// base44/agents/support_agent.jsonc
{
  "name": "support_agent",
  "description": "Brief description of what this agent does",
  "instructions": "Detailed instructions for the agent's behavior",
  "tool_configs": [
    { "entity_name": "tasks", "allowed_operations": ["read", "create", "update", "delete"] },
    { "function_name": "send_email", "description": "Send an email notification" }
  ],
  "whatsapp_greeting": "Hello! How can I help you today?"
}

必填项：name、description、instructions。可选项：tool_configs（默认值为 []）、whatsapp_greeting。工具配置可以是实体工具（entity_name + allowed_operations：可为 read / create / update / delete 中的任意项）、后端函数工具（function_name + description），或服务端路由工具（tool_name + 相对于应用的 route_path，例如 /api/orders/summary + method，默认值为 post + description）。如需查看完整的 Agent 架构，请参阅 base44-cli 技能的 Agent 架构部分 SKILL.md——但忽略其中的 agents push / agents pull / deploy 命令，这些命令适用于本地项目；在沙盒中，文件会自动同步。

连接器（OAuth 集成）

连接器（Google Calendar、Gmail、Slack 等）会为你的后端函数提供调用第三方 API 的令牌。在 remote-dev 中，无需编写连接器文件——你可以通过应用 ID 直接操作该应用中的连接器。两种操作入口使用相同的后端，行为也相同：

声明式作用域——设置前请先读取。连接连接器时，会将其作用域集替换为你传入的完整作用域集（不会合并）。你省略的任何作用域都会被移除，并会再次提示用户授权。请始终先列出连接器当前的作用域，再传入完整的目标作用域集（即你想保留的作用域加上任何新作用域）。

OAuth 需要人工操作。连接操作会返回一个授权 URL，用户必须在浏览器中打开该 URL，以登录并授权——你无法自行完成此操作。用户完成后，请再次列出连接器，以确认连接状态并读取已授权的作用域（提供方授予的作用域可能少于你请求的数量）。

通过 MCP（base44-remote-dev 传输）

有两个工具，均需提供 appId。作用域：list_connectors 需要 apps:read；initiate_connector_connection 需要 apps:write（注意：不是 sandbox:write）。

1. list_connectors——{ appId, integrationTypes? }。如果不传入 integrationTypes，则返回完整目录；每个条目都包含连接器的名称、描述、连接状态，以及（如果已连接）其状态和已授权的作用域。传入 integrationTypes 可查看指定连接器的完整详情。
2. initiate_connector_connection——{ appId, integrationType, scopes, connectionConfig? }。scopes 是完整的目标作用域集（请参阅声明式作用域说明）。返回结果可能是 already_authorized: true（无需操作），也可能是供用户打开的 redirect_url。用户登录后，再次调用 list_connectors 进行验证。

On appId <APP_ID>: call list_connectors to read googlecalendar's current scopes,
then initiate_connector_connection for googlecalendar with the full scope set
(existing + the calendar.events scope I need). Give me the authorization URL.

通过命令行（无项目，--app-id）

这些 base44 connectors 子命令无需本地项目即可使用——它们依次从 --app-id、BASE44_APP_ID，然后从本地 .app.jsonc 解析应用 ID。无需 config.jsonc。

# 1. See available integration types for the app
npx base44 connectors list-available --app-id <APP_ID>

# 2. Initialize the connector and start OAuth (sets it to EXACTLY these scopes).
#    Non-interactive: prints the authorization URL. Interactive: also opens the
#    browser and polls until authorized.
npx base44 connectors initiate --app-id <APP_ID> \
  --integration-type googlecalendar \
  --scopes https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.events

# 3. (optional) Fetch the resulting connector config
npx base44 connectors pull --app-id <APP_ID> --dir ./connectors

--scopes 接受以空格或逗号分隔的列表。与 MCP 一样，用户必须打开打印出的授权 URL 才能完成授权；之后，list-available / pull 会反映已连接状态和已授予的作用域。

这是 remote-dev 中唯一适用的 Base44 CLI 用法——它通过应用 ID 面向远程应用，且无需本地项目，也无需部署步骤。这并不与上文的“无 CLI”规则矛盾；该规则针对的是本地项目／部署命令。

在代码中使用已连接的连接器

连接仅用于授权连接器。要实际调用第三方 API，请在后端函数中使用服务角色连接器模块获取 OAuth 访问令牌——base44.asServiceRole.connectors.getConnection(integrationType)——并在自己的 fetch 中使用返回的 accessToken（以及可选的 connectionConfig）：

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

export default async function (req) {
  const base44 = createClientFromRequest(req);

  // App-scoped OAuth token — backend / service role only.
  const { accessToken, connectionConfig } =
    await base44.asServiceRole.connectors.getConnection("googlecalendar");

  const events = await fetch(
    "https://www.googleapis.com/calendar/v3/calendars/primary/events",
    { headers: { Authorization: `Bearer ${accessToken}` } },
  ).then((r) => r.json());

  return Response.json({ events });
}

说明：连接器的作用范围是应用级（所有用户共享一个已连接的账户）；Base44 会为你刷新令牌；API 调用由你发起。getConnection() 已取代弃用的 getAccessToken()。有关完整的模块参考（签名、connectionConfig、可用服务列表及其类型标识符），请参阅 base44-sdk 技能中的 connectors.md。

参考资料顺序与完整 README

在搜索网页之前，请先查阅此技能及其同级技能（base44-remote-dev、base44-sdk）中的参考资料。 它们是沙盒桥接、文件／资源约定和 SDK API 的权威来源——请优先参考这些内容，而不要依赖一般的互联网搜索结果，因为它们对于 Base44 往往已过时或不正确。

如需完整的、针对具体应用的 remote-dev 参考资料（包含说明和所有端点，公开可访问，获取时无需身份验证），请阅读应用的入门 README：

https://app.base44.com/api/sandbox/<APP_ID>/local-agent/readme.md

（云端／MCP 对应的路径是 …/api/sandbox/<APP_ID>/claude-web/readme.md。）此 README 中描述的连接机制，请参阅 base44-remote-dev 技能。

在沙盒中的工作流

1. 了解情况——使用 list_directory / read_file / grep（在 CLI 中使用 sandbox ls / sandbox read / sandbox grep）了解应用，然后再进行更改。
2. 编写——创建或编辑资源文件（后端函数、actors、实体、agents）和前端代码，并遵循上述约定；通过连接流程设置连接器。
3. 验证——可选地运行 run_command（sandbox run）执行 npm run build / npx tsc --noEmit，并打开 GET /api/apps/{app_id}/sandbox/preview-url 返回的预览 URL，目视检查更改（参见 base44-remote-dev）。
4. 等待发布——部署时什么都不要做。写入文件即完成部署；自动提交（约 5 秒）会保存并发布更改。最后一次编辑后稍等片刻再断开连接，以便提交完成。
5. 创建检查点——完成一个工作单元时，以及每次停止之前，都要调用 create_checkpoint（在 CLI 中运行 base44 sandbox checkpoint --name "..."）。自动提交会保存文件，但不等于检查点：只有检查点会出现在构建器的版本历史记录中；在那里执行 Restore 或 Revert 会将应用回滚到最近的检查点，并丢弃此后写入的所有内容。创建检查点前会先刷新待处理的更改，因此检查点会包含最新代码。详情请参阅 base44-remote-dev。