已有 Base44 项目用 @base44/sdk…

当目录存在 base44/config.jsonc 或项目已使用 @base44/sdk，需要在 Base44 平台扩展现有应用功能时使用。

适用场景

解决思路

1. 技能在提到 base44 或存在 base44/ 文件夹时激活；激活后不要先读文档或搜索网页，第一动作是检查当前目录是否存在 base44/config.jsonc。
2. 如果 base44/config.jsonc 存在，用本技能实现功能，使用 Base44 SDK；除非用户明确要求，否则不要用 base44-cli 执行命令。
3. 如果 base44/config.jsonc 不存在，转到 base44-cli 做项目初始化；本技能假定 Base44 项目已经初始化，初始化前无法用本技能继续。
4. 在 Base44 生成的应用中，base44 client 已预配置并可直接使用：例如 entities.Task.create({ title: 'New task', status: 'pending' })、entities.Task.list()、entities.Task.update(task.id, { status: 'done' })、auth.me()。
5. 外部应用从 @base44/sdk 导入 createClient，并用 createClient({ appId: 'your-app-id' }) 创建客户端；必须使用 appId，不要用 clientId 或 id。
6. 外部应用认证调用 loginViaEmailPassword('user@example.com', 'password')；createClient 可选传入 token 和 options.onError 全局错误处理。
7. 写任何 Base44 代码前，先对照方法名表或 references/QUICK_REFERENCE.md 验证；不要假设 Firebase、Supabase 或其他 SDK 的模式。
8. 认证正确 API：loginWithProvider('google')、loginViaEmailPassword(email, pw)、register({email, password})、await auth.me()；不要用 signInWithGoogle、signInWithProvider、auth.google、signInWithEmailAndPassword、signIn、createUser、signUp、onAuthStateChanged、currentUser。
9. Functions 正确 API：functions.invoke('name', data)；不要用 functions.call、functions.run、callFunction、httpsCallable。
10. Integrations 正确 API：integrations.Core.InvokeLLM({prompt})、integrations.Core.SendEmail({to, subject, body})、integrations.Core.UploadFile({file})；不要用 ai.generate、openai.chat、llm、sendEmail、email.send、uploadFile、storage.upload。
11. 例外：OpenAI 兼容客户端（例如 Vercel AI SDK）指向 base44.aiGateway.connection() 是正确的，用于构建带工具的代码代理；InvokeLLM 只用于单次无工具调用。
12. Actors 正确 API：actors.ChatRoom(roomId).connect()；在 connection 上调用 subscribe(cb)；用 room.send(data) 发送；不要用 actors.connect、actors.ChatRoom.connect、actors.ChatRoom(roomId).subscribe、room.on、room.emit、new WebSocket 作为应用实时通道。
13. Actors 取消订阅：Connection.subscribe() 返回对象，用 sub.unsubscribe()；entities.<Name>.subscribe() 返回取消函数本身，用 unsub()；不要把两种约定混用。
14. Entities 正确 API：entities.Task.filter({...})、entities.Task.get(id)、entities.Task.create(data)、entities.Task.delete(id)、entities.Task.subscribe(cb)；不要用 find、findOne、insert、remove、onChange。
15. 模块选择：数据 CRUD、importEntities()、Realtime 更新用 entities；登录/注册/登出/me/updateMe 用 auth；邀请用户用 users.inviteUser()。
16. AI 功能选择：AI 对话用 agents 且需要已登录用户，createConversation() 创建会话，getConversations() 管理会话；文本/JSON 用 integrations.Core.InvokeLLM()；图片用 integrations.Core.GenerateImage()；后端构建带工具自定义代理用 aiGateway。
17. 自定义后端逻辑：functions.invoke() 运行服务端代码；需要管理员权限时用 base44.asServiceRole.functions.invoke()。
18. 实时共享会话选择：多玩家、协作白板/文档、presence、实时光标、房间聊天用 actors.<Name>(roomId).connect()；只是让记录列表实时更新用 entities.EntityName.subscribe()，不要用 actor。
19. 外部服务选择：发邮件用 integrations.Core.SendEmail()；上传文件用 integrations.Core.UploadFile()；自定义 API 用 integrations.custom.call()；后端 only 用 asServiceRole.connectors.getConnection() 获取应用级 OAuth。
20. 跟踪分析：自定义事件用 analytics.track()；记录页面访问/活动用 appLogs.logUserInApp()。
21. 过滤和排序数据：entities.Task.filter({ status: 'pending', assignedTo: userId }, '-created_date', 10, 0)。
22. 保护路由：调用 await base44.auth.me()；如果没有用户，导航到自定义登录页并传入 returnTo: window.location.pathname。
23. 后端函数调用注意：functions.invoke() 返回原始 axios response，函数 JSON 在 res.data；非 2xx 会抛错，错误体在 err.response.data。
24. 后端函数结构：从 npm:@base44/sdk 导入 createClientFromRequest；export default async function (req) { const base44 = createClientFromRequest(req); ...; return Response.json({ success: true }); }；用 asServiceRole 做管理员操作。
25. 实时房间前端：在 useEffect 中执行 const room = base44.actors.ChatRoom(roomId).connect(); const sub = room.subscribe((msg) => { if (msg.type === 'message') setMessages((prev) => [...prev, msg]); }); 清理时执行 sub.unsubscribe(); room.close(); 按 msg.type 分支并丢弃未知消息。
26. Actor 后端：在 base44/actors/ChatRoom/entry.ts 中 import { Actor } from 'base44:runtime/actors'; export default class ChatRoom extends Actor；handleConnect(conn) 可 conn.send({ type: 'welcome' })；handleMessage(conn, msg) 先验证 msg?.type 和字段类型，再 this.broadcast({ type: 'message', text: msg.text.slice(0, 2000) })；handleClose(conn) 处理关闭。
27. 服务角色访问：后端用 asServiceRole 做管理员级操作，例如 base44.asServiceRole.entities.Task.list()、base44.asServiceRole.connectors.getAccessToken('slack')；Actors 中可用 this.client.asServiceRole，用户归属用已验证的 conn.identity.userId。
28. 前端/后端能力边界：entities、auth、agents、functions.invoke()、functions.fetch()、integrations、analytics、appLogs、users 前后端都可用；actors 连接仅前端，因为 actor 本身就是服务端；aiGateway、asServiceRole.*、asServiceRole.connectors、asServiceRole.sso 仅后端。
29. 安装 SDK：npm install @base44/sdk；不要假设或硬编码 @base44/sdk 版本，始终不带版本说明符安装以获取最新版。
30. TypeScript 类型：用 Base44 CLI 从项目资源生成类型，并增强 EntityTypeRegistry、FunctionNameRegistry、ActorNameRegistry、AgentNameRegistry；也可在 .d.ts 中手动增强；Actor message 类型始终手写，增强 ActorRegistry 让 actor 和客户端共享定义。
31. 客户端设置和认证模式参考 references/client.md；各模块参考 references 下对应文件，包括 entities.md、auth.md、base44-agents.md、functions.md、actors.md、integrations.md、ai-gateway.md、analytics.md、app-logs.md、users.md、connectors.md、sso.md。
32. 每个 reference 文件包含 Type Definitions 部分；实现时查看对应模块的方法、参数和返回值 TypeScript 定义。
33. Base44 CLI 可生成 typed entities、functions、actors、agents 并接入项目，从而获得自动补全和类型检查；生成类型的方法使用 base44-cli 技能。
34. 手动增强注册表时，在 .d.ts 文件中增强 EntityTypeRegistry、FunctionNameRegistry、ActorNameRegistry、AgentNameRegistry；Actor message 类型始终手动编写并增强 ActorRegistry。
35. Base44 SDK 的各模块用途：entities 数据模型 CRUD；auth 登录/注册/用户管理；agents AI 对话与消息；functions 后端函数调用；actors WebSocket 实时房间；integrations AI/邮件/文件上传/自定义 API；aiGateway 连接 OpenAI 兼容 SDK 到 Base44 AI 网关；analytics 跟踪事件；appLogs 记录用户活动；users 邀请用户；asServiceRole.connectors 应用级 OAuth token；asServiceRole.sso SSO token 生成。
36. 不要为实时共享状态直接用 new WebSocket；应用实时通道应使用 base44.actors.<Name>(id).connect()。

适用边界 · 注意事项

• 不要用于初始化新的 Base44 项目、空目录或没有 base44/config.jsonc 的项目；这些应先使用 base44-cli。
• 不要用于 CLI 命令，如 npx base44 create、npx base44 deploy、npx base44 login；这些属于 base44-cli。
• 不要用于非 Base44 项目，也不要臆造 API 或照搬 Firebase、Supabase 等 SDK 的方法名；前端不要调用 aiGateway、asServiceRole.*、connectors、sso 等后端 only 能力。