在创建、配置、部署 Base44 项目时用 Base44…

当出现 base44、base44/ 目录或需要初始化、链接、部署 Base44 项目时，按此流程操作 CLI。

适用场景

解决思路

1. 任何提到 base44 或当前目录存在 base44/ 文件夹时激活本技能；不要在行动前先读文档文件或搜索网页。
2. 第一个动作是检查当前目录是否存在 base44/config.jsonc。
3. 如果 base44/config.jsonc 存在：转交 base44-sdk 技能做功能实现；本技能只处理 CLI 命令，如 login、deploy、entities push。
4. 如果 base44/config.jsonc 存在且要本地运行应用：仍留在此技能；启动 dev server 前先阅读 Running Local Development，因为其中一种运行方式会访问生产数据。
5. 如果 base44/config.jsonc 不存在且应用已预置：应用由 Stripe Projects / projects.dev 流程创建，或环境/.env/.env.local 中存在 BASE44_APP_ID 或 BASE44_PROJECTS_BASE44_APP_ID；运行 npx base44 scaffold 为这个已有应用建立本地文件。
6. 如果应用已预置，绝不要运行 npx base44 create，否则会创建第二个重复应用。
7. 如果 base44/config.jsonc 不存在且没有已预置应用：引导用户运行 npx base44 create；此时不要激活 base44-sdk。
8. 绝不要直接调用 base44；CLI 作为 dev dependency 本地安装，必须通过包管理器访问：npx base44 <command>（npm 推荐）、yarn base44 <command> 或 pnpm base44 <command>。
9. 认证检查：每个 AI 会话开始且本技能激活时，先运行 npx base44 whoami。
10. 如果 npx base44 whoami 成功并显示邮箱：继续请求的任务。
11. 如果 npx base44 whoami 失败或显示错误：立即停止，不执行任何 CLI 操作；要求用户手动运行 npx base44 login；等待用户确认登录后再继续。
12. 认证检查必须在执行任何其他 Base44 CLI 命令之前完成。
13. 如果通过 Stripe Projects / projects.dev 预置：CLI 会从注入的 BASE44_ACCESS_TOKEN / BASE44_REFRESH_TOKEN 环境变量初始化认证，BASE44_PROJECTS_* 前缀名称会自动规范化；此时 npx base44 whoami 已成功，不需要交互式 npx base44 login。
14. 如果设置了 workspace API key：当 BASE44_API_KEY 环境变量为 b44k_ 前缀的 workspace API key，CLI 直接用它认证，npx base44 whoami 和其他命令无需交互登录即可成功。
15. 安装 CLI：在项目中运行 npm install --save-dev base44；不要假设或硬编码 base44 包版本，安装时不要写版本号以获取最新版本；然后用 npx base44 <command> 运行命令。
16. 可使用 yarn base44 或 pnpm base44 代替 npx base44。
17. 全局 --app-id <id> 选项：解析顺序为 --app-id flag → BASE44_APP_ID 环境变量 → 本地 base44/.app.jsonc。
18. 用 --app-id 对不需要本地项目文件、只需要 app 上下文的 app 级命令操作，例如：cat ./script.ts | npx base44 exec --app-id app_123，或 npx base44 logs --app-id app_123 --level error。
19. 不要把 --app-id 用于需要本地项目文件的命令：base44 create 会拒绝，base44 dev 会拒绝，base44 deploy 仍需本地项目目录。
20. 全局 --json 选项：让命令在 stdout 输出机器可读 JSON，并强制非交互模式，spinner/状态/日志移到 stderr，stdout 保持纯 JSON，可安全管道给 jq 或程序；例如 npx base44 connectors list-available --json、npx base44 logs --app-id app_123 --json。
21. 认证命令：base44 login 用 device code flow 登录；base44 logout 退出当前设备；base44 whoami 显示当前认证用户。
22. 项目管理命令：base44 create 从模板创建新 Base44 项目，必须先读 create.md；base44 scaffold 按 app ID 为已有 Base44 应用搭建本地项目；base44 link 把已有本地项目链接到 Base44；base44 eject 下载已有 Base44 项目代码；base44 dashboard open 在浏览器打开应用 dashboard；base44 visibility <level> 设置服务端应用可见性，level 为 public、private 或 workspace。
23. Workspace 管理：默认 base44 create 和 base44 link --create 使用个人 workspace；传 -w, --workspace <id> 可指定其他 workspace。
24. Workspace 命令：base44 workspace list 列出所属 workspace；base44 workspace get <workspace-id> 查看单个 workspace 详情；base44 workspace move [workspace-id] 把当前 app 移到另一个 workspace。
25. 开发命令：base44 dev 启动本地 Base44 后端；当 base44/config.jsonc 配置了 site.serveCommand 时也启动前端；base44 dev --remote 让前端本地运行但连接生产后端。
26. 部署命令：base44 build 构建站点并注入 app id，必须用它代替裸 npm run build；base44 deploy 部署所有资源，包括 entities、functions、actors、agents、agent skills、connectors、auth config 和 site；它会询问是否先构建，或传 --build / --no-build 预先回答。
27. 实体：在 base44/entities 文件夹定义 entities；用 base44 entities push 把本地 entities 推送到 Base44；RLS 模式必须读 rls-examples.md。
28. 实体文件命名：base44/entities/{kebab-case-name}.jsonc，例如 TeamMember 用 team-member.jsonc。
29. 实体 schema 遵循结构：name 为 EntityName，type 为 object，properties 包含字段定义，required 列出必填字段。
30. 实体字段类型：string、number、integer、boolean、array、object、binary；string formats 可用 date、date-time、time、email、uri、hostname、ipv4、ipv6、uuid、file、regex、richtext。
31. 实体枚举：添加 enum 数组如 [value1, value2]，可选 default 指定默认值。
32. 实体名称必须只含字母数字，匹配 /^[a-zA-Z0-9]+$/。
33. 函数：在 base44/functions 定义 functions；base44 functions deploy [names...] [--force] 部署本地函数，可指定函数名或传 --force 清理已删除函数；base44 functions delete <names...> 删除已部署函数；base44 functions list 列出远程已部署函数；base44 functions pull [name] 从 Base44 拉取函数到本地。
34. Workflow runs：base44 workflows list 列出当前 app 的 workflows、状态和运行摘要；base44 workflows runs [--status <s>] [--since <t>] 按最新优先列出 workflow 运行，失败运行包含底层错误；这些命令只读。
35. Actors：Actors 是基于 WebSocket 的有状态实时服务器房间，每个 room id 一个实时实例，所有连到该 id 的客户端共享；用于多人会话、协作白板、presence 和 live cursors、房间内聊天、实时拍卖。
36. Actors 使用直接连接和 SDK 管理的认证；用已验证的 conn.identity 做用户归属；用 this.client.asServiceRole 持久化已验证的 room 结果。
37. Actors 不接收 app secrets；需要 secret 的操作放在 backend function 中。
38. Actor 命令：在 base44/actors 定义 actors；base44 actors deploy [names...] 部署本地 actors，可指定名称；base44 actors delete <names...> 拆除已部署 actor 并销毁已发布脚本。
39. Actor 文件布局：base44/actors/{ActorName}/entry.ts，文件夹就是 actor 身份。
40. Actor 代码默认导出一个继承 base44:runtime/actors 的 Actor 的 class；处理 handleConnect(conn)、handleMessage(conn, msg)、handleClose(conn)；在 handleMessage 中始终验证攻击者可控的 payload，msg 甚至可能为 null，例如检查 msg?.type 和 typeof msg.text，再 this.broadcast。
41. Actor 命名规则：匹配 [A-Za-z_][A-Za-z0-9_]*，最多 128 字符，不能包含 /、-、. 或 :，不能是 JS 保留字，不能与 backend function 名称冲突，不能嵌套在子文件夹；CLI 上传前本地检查；带点的文件夹名会被跳过，可作临时目录。
42. Actor 有效名示例：ChatRoom、BoardRoom、Lobby；无效示例：chat-room、games/Arena、class。
43. Actor 必需 entry.ts 或 entry.js，默认导出继承 Actor 的 class；TypeScript 中还要声明 handleTick() {}，因为它是 Actor 的 abstract member。
44. Actor 与 functions 的差异：只上传 actor 自己的文件夹，不包含 base44/shared/；没有 --force prune；没有 list/pull 命令；没有本地 base44 dev runtime；名称不能像路径；不支持 automations。
45. Agent：在 base44/agents 文件夹定义 agents；base44 agents pull 拉取远程 agents 到本地；base44 agents push 推送本地 agents 到 Base44；这些命令是全量同步，push 会用本地替换所有远程 agents，pull 会用远程替换所有本地 agents。
46. Agent 文件命名：base44/agents/{agent_name}.jsonc，例如 support_agent.jsonc。
47. Agent schema 包含 name、description、instructions、tool_configs、memory_config（可选）、whatsapp_greeting；必需字段为 name、description、instructions。
48. Agent 命名规则：匹配 /^[a-z0-9_]+$/，小写字母数字加下划线，1-100 字符；有效如 support_agent、order_bot；无效如 Support-Agent、OrderBot。
49. Agent tool_configs：Entity 工具包含 entity_name 和 allowed_operations（read、create、update、delete）；Backend function 工具包含 function_name 和 description。
50. Agent memory_config 字段：enabled（bool，默认 true）、scope（global|user|both，默认 both）、include_other_conversation_context（bool，默认 false）、instructions（string|null，默认 null）。
51. Agent Skills：在 base44/agent-skills 文件夹定义 agent skills；base44 agent-skills pull 拉取远程 skills 到本地；base44 agent-skills push 推送本地 skills 到 Base44；这些命令是全量同步，push 替换所有远程 skills，pull 替换所有本地 skills。
52. Agent Skill 文件命名：base44/agent-skills/{skill-name}.md，例如 pdf-export.md。
53. Agent Skill 格式：Markdown 文件，frontmatter 包含 description；正文是 Markdown 内容；description 1-1024 字符，正文 1-15000 字符。
54. Agent Skill 命名规则：文件名去掉 .md 后匹配 /^[a-z0-9]+(-[a-z0-9]+)*$/，小写、连字符分隔、1-64 字符；有效如 pdf-export、order-lookup；无效如 PdfExport、pdf_export。
55. Connectors：在 base44/connectors 文件夹定义 connectors；base44 connectors list-available 列出 Base44 支持的所有集成类型；base44 connectors initiate --integration-type <t> [--scopes <s...>] 初始化 connector 并启动 OAuth 流程，配合 --app-id 可 projectless 运行；base44 connectors pull 拉取远程 connectors 到本地；base44 connectors push 推送本地 connectors 到 Base44。
56. Connector 同步是全量同步：push 会用本地替换所有远程 connectors，并为新 OAuth connectors 触发 OAuth；pull 会用远程替换所有本地 connectors。
57. Connector 文件命名：base44/connectors/{type}.jsonc，例如 googlecalendar.jsonc、slack.jsonc；schema 包含必需的 type，可选 scopes（默认 []）。
58. 用 npx base44 connectors list-available 查看所有支持集成类型；stripe 也是有效 connector type，但不会由 list-available 返回，且由 Base44 服务端自动预置，无 OAuth 浏览器流程。
59. Auth 配置：管理应用认证设置，配置存储在 base44/auth/，通过 auth push/auth pull 与 Base44 同步。
60. Auth 命令：base44 auth password-login <enable|disable> 启用或禁用用户名密码登录；base44 auth social-login <provider> <enable|disable> 启用或禁用社交登录，provider 为 google、microsoft、facebook、apple；base44 auth sso <enable|disable> 配置 SSO 身份提供方，如 google、microsoft、github、okta、custom；base44 auth pull 拉取 auth 配置；base44 auth push 推送本地 auth 配置；auth 配置也会作为 base44 deploy 的一部分部署。
61. Secrets 管理：命令在 --help 中隐藏但可用；base44 secrets list 列出所有 secret 名称；base44 secrets set 设置一个或多个 secret（KEY=VALUE 或 --env-file）；base44 secrets delete <key> 按名称删除 secret。
62. 脚本执行：base44 exec 从 stdin 运行脚本，Base44 SDK 已预认证；可对 entities 做 CRUD，如 base44.entities.MyEntity.list/create/update/delete，调用 backend functions，如 base44.functions.invoke('myFunction', args)，调用 agents，或访问 SDK 暴露的其他资源；适用于数据迁移、批量操作、调试和脚本化工作流。
63. 类型生成：base44 types generate 从 entities、functions、actors、agents 和 connectors 生成 TypeScript 类型；输出 base44/.types/types.d.ts；为 @base44/sdk 模块增强 typed registries：EntityTypeRegistry、FunctionNameRegistry、AgentNameRegistry、ConnectorTypeRegistry、ActorNameRegistry；不需要认证，完全本地运行，并自动更新 tsconfig.json 以包含生成类型。
64. 站点管理：base44 site deploy 部署已构建站点文件到 Base44 hosting；base44 site open 在浏览器打开已部署站点；Base44 hosting 仅支持 SPA，单一 index.html 入口，所有路由由 index.html 提供（客户端路由）。
65. Quick Start：运行 npm install --save-dev base44；运行 npx base44 login；创建新项目时始终提供名称和 --path flag，如 npx base44 create my-app --path .；运行本地开发 npx base44 dev；构建并部署全部 npx base44 deploy --build -y。
66. 单独部署资源命令：npx base44 entities push；npx base44 functions deploy；npx base44 functions delete <name>；npx base44 functions list；npx base44 functions pull；npx base44 actors deploy；npx base44 actors delete <name>；npx base44 agents push；npx base44 agent-skills push；npx base44 connectors pull；npx base44 connectors push；npx base44 auth pull；npx base44 auth push；npx base44 site deploy -y。
67. 创建新项目：运行 base44 create 前必须先读 create.md，包括模板选择（backend-and-client vs backend-only）、正确 workflow、常见陷阱；否则会导致项目脚手架损坏。
68. 链接已有项目：如果有 base44/config.jsonc 但没有 .app.jsonc，运行 npx base44 link --create --name my-app。
69. 本地开发：始终通过 CLI 运行，两种模式：npx base44 dev 使用本地后端和数据，临时、每次启动为空、停止即消失；npx base44 dev --remote 使用生产后端和真实应用实时数据。
70. npx base44 dev 启动本地后端（entities、functions、auth），并在 base44/config.jsonc 设置 site.serveCommand 时也服务前端；backend-only 项目不需要其他设置。
71. npx base44 dev --remote 只运行前端连接真实后端，因此需要已链接项目和 site.serveCommand。
72. 不要自己运行 npm run dev：没有 CLI 注入的环境变量，应用没有后端可连；dev server 会打印应改用哪个命令。
73. 默认使用 npx base44 dev；在 --remote 下每个写入都会打到 live app；Vite 启动行会以 [base44] Proxy enabled: /api -> <target> 标明后端；说明你启动的是哪一种。
74. 部署所有更改：可选先运行 npx base44 types generate；然后 npx base44 deploy --build -y 部署 entities、functions、site 等并先构建站点。
75. 通过 CLI 构建而不是 npm run build：npx base44 build 会注入 VITE_BASE44_APP_ID；裸 npm run build 不会设置它，bundle 无法解析自己的 app，部署站点上的每个 API 调用都会失败。
76. npx base44 deploy 会询问是否先构建；--build / --no-build 提前回答；非交互模式默认只上传，因此 CI 行为不变。
77. 生成 TypeScript 类型：在修改 entities、functions、actors、agents 或 connectors 后运行 npx base44 types generate 保持类型同步；不需要认证。
78. 打开 Dashboard：运行 npx base44 dashboard。
79. 认证：大多数命令需要认证；未登录时 CLI 会自动提示登录；会话存储在本地并跨 CLI 会话持久化。
80. 排错：Not authenticated 时先运行 npx base44 login。
81. 排错：No entities found 时确保 entities 存在于 base44/entities/ 目录。
82. 排错：Entity not recognized 时确保文件用 kebab-case 命名，例如 team-member.jsonc 而不是 TeamMember.jsonc。
83. 排错：No functions found 时确保 functions 存在于 base44/functions/ 且有 entry.ts 或 entry.js。
84. 排错：No actors found 时确保 actor 以 base44/actors/<ActorName>/entry.ts 存在，绝不要直接放在 base44/actors/。
85. 排错：Invalid actor name 时确保 actor 名匹配 [A-Za-z_][A-Za-z0-9_]*，不含 /、-、. 或 :，避免 JS 保留字，不能嵌套；CLI 会在上传前本地捕获。
86. 排错：actors cannot be nested 时压平为 base44/actors/<ActorName>/entry.ts，或重命名一个你叫 entry.ts 的 helper；base44/actors/ 下每个 entry 文件都会被算作 actor。
87. 排错：Actor 和 function 同名时，它们部署到同一 namespace，重命名其中一个。
88. 排错：Actor file rejected in the functions bucket 时，导入 base44:runtime/actors 的文件必须放在 base44/actors/<ActorName>/entry.ts，把它移出 base44/functions/。
89. 排错：No agents found 时确保 agents 存在于 base44/agents/ 且有有效 .jsonc 配置。
90. 排错：Invalid agent name 时 agent 名必须小写字母数字加下划线。
91. 排错：No agent skills found 时确保 skill 文件存在于 base44/agent-skills/ 且有有效 .md 文件。
92. 排错：Invalid skill file 时 skill 文件名必须小写连字符，并在 frontmatter 包含 description。
93. 排错：Push cancelled / requires --yes 时注意 agents push、agent-skills push、entities push、connectors push 是破坏性全量同步；交互确认或传 -y/--yes 用于 CI/非交互模式。
94. 排错：No connectors found 时确保 connectors 存在于 base44/connectors/ 且有有效 .jsonc 配置。
95. 排错：Invalid connector type 时运行 npx base44 connectors list-available 查看有效类型。
96. 排错：Duplicate connector type 时每个 connector type 在项目中只能定义一次。
97. 排错：Connector authorization timeout 时重新运行 npx base44 connectors push 并在浏览器完成 OAuth 流程。
98. 排错：No site configuration found 时检查项目配置中设置了 site.outputDirectory。
99. 排错：Site deployment fails 时确保站点已先构建成功（npx base44 build 或 npx base44 deploy --build）。
100. 排错：Deployed site's API calls all fail 时 bundle 构建时缺少 app id；用 npx base44 build 而不是裸 npm run build 重新构建并重新部署。
101. 排错：Update available message 时如果提示更新，运行 npm install -g base44@latest，或本地安装使用 npx。

适用边界 · 注意事项

• 不是 Base44 项目、没有 base44/ 目录且不想使用 Base44 时，不适用。
• 已有 base44/config.jsonc 并要写功能代码时，应使用 base44-sdk；本技能只处理 CLI 命令，本地运行除外。
• 应用已由 Stripe Projects / projects.dev 预置或已有 BASE44_APP_ID 时，不要运行 npx base44 create，应使用 npx base44 scaffold。