Voobase Light App — Agent 执行入口

你是平台使用者，不是平台开发者。
本 skill 先帮你建立平台认知，再告诉你现在该做什么、细节去哪个分册查。

CLI 名称约定

产品名是 Voobase。用户说的 voobase CLI、Voobase CLI、运行 voobase、用 voobase 启动，均指本平台控制面 CLI。

当前真实业务命令名是 platform。因此 Agent 执行开发、绑定、提交、预览等操作时，必须使用 platform app preflight、platform dev、platform app checkout、platform app submit、platform preview generate、platform preview 等命令。不要用 voobase dev、voobase app preflight、voobase app checkout 执行业务流程。

安装与环境准备

用户要求安装或初始化 Voobase，或 CLI 不可用、认证失效时，先读 setup.md。默认全局安装 CLI；全局权限不足时读取官网 /install/ 的当前系统沙箱说明，不固化版本化下载地址。仅安装工具的任务到安装验证为止，不进入应用架构设计或创建流程；已有兼容环境直接复用。

平台是什么

Voobase是一个轻应用开发与发布平台：用官方模板 + platform CLI 创建应用，在本地开发预览，再提交源码、生成云端 Preview、按需发布。
平台负责 Auth、Data Form、数据库（后端）、CMS、工作流、通知、素材库等基座能力；你主要写业务页面与逻辑，通过模板 helper / runtime-sdk 消费这些能力，而不是自己搭基础设施。

典型开发分工：

和普通 Web 项目有什么不同

如果你习惯「自己起一个 Vite/React 项目、自己配登录和数据库、自己部署」，在这里要换一套心智：

一句话：你不是在造一套新基础设施，而是在平台提供的模板和能力之上做应用。 配置、绑定、发布走 CLI；页面里消费能力走 helper，不要混用。

能构建什么应用

接能力前先问五句（不需要的不接；应用类型与 dev 路径详见 concepts.md）：

1. 要登录吗？→ Auth
2. 要持久化 / 收集业务数据吗？→ Data Form（表单、报名、结构化记录，默认首选）；需要私有 API、复杂 SQL 或 migration 时才接 DB（限 backend-app-node）
3. 要运营维护内容吗？→ CMS
4. 有多步审批 / 状态流转吗？→ Workflow
5. 要站内通知 / 待办吗？→ Notification

官方模板

创建应用时选模板（默认 frontend-app-vite）：

新建应用、迁移外部代码或改变应用部署形态时，先读 architecture-intake.md 形成应用架构卡，再执行 create 或大规模编码。若需求触及非官方工程形态、构建适配或部署可行性，同时读 platform-limits.md。日常 UI 和既有架构内的功能迭代不重复执行完整架构设计。

核心链路（默认遵守）

Agent 按 「先本地，后云端」 开发：

准备环境 → 绑定应用 → 本地 dev 开发与预览 → 本地改到满意 → submit → 云端 Preview 验证 →（需要时）发布

本地是主战场，云端是最后验收。 不要一上来就 platform preview generate、platform dev push，也不要用云端 Preview 代替日常开发反馈。

五条铁律

1. 控制面走 platform CLI；应用代码复用模板已提供的能力 API。
2. 日常开发用 platform dev（本地预览）；涉及真实 Auth、Data Form、CMS、Workflow 时用 platform dev --remote-bindings；仅在 backend-app-node 且明确联调平台 DB 时用 platform dev --remote-bindings=db。不要用 npm run dev 代替平台联调。 --remote-bindings 默认按工作区已声明的 binding 自动注入；若工作区没有 DB migration，会跳过 DB binding 且不阻断启动。
3. 应用代码面向 Host-root 契约：Preview / Prod 使用独立 Host，公开根路径为 /；普通 /api/*、/assets/*、/about 可直接写，Auth 回跳与 Route Context 使用 buildPlatformPath(...) 等模板构建函数。不要把完整 Preview / Prod 访问地址写入业务代码（见 template.md）。
4. 先跑通本地预览，再扩功能；本地都跑不起来时，不要开始写大量业务代码或上云端。
5. 开工前或 checkout 后先 platform app preflight，确认登录态、tenant/app 上下文与能力绑定是否就绪。

选路径：第一次 vs 继续开发

A. 还没有应用目录（第一次）

1. 读 architecture-intake.md，明确应用起点、模板、页面模式和平台能力
2. 读 setup.md：检查 CLI、按需登录、确认 tenant-id
3. 绑定应用：

不知道已有应用的 app-id 时，先执行 platform app list --tenant <tenant-id>；需要结构化结果时加 --json。

# 新应用（默认模板 frontend-app-vite）
platform app create --tenant <tenant-id> --name "<name>" --dir <dir> --template frontend-app-vite
cd <dir>

# 已有应用（含工作台 / 应用模板已创建的应用 — 不要重复 create）
platform app checkout --tenant <tenant-id> --app <app-id> --dir <dir>
cd <dir>

# 从轻应用资源库拉示例源码（见 resource-library.md）
platform app-library checkout <entry-id> --dir <dir>
cd <dir>

4. 确认上下文，再启动本地 dev：

platform app preflight
platform dev

platform dev 发现当前工作区缺少 node_modules 时，会根据精确 packageManager 声明与唯一 lockfile 自动执行确定性安装。不要在未检查 package.json 和 lockfile 的情况下固定执行 pnpm install。

5. 本地浏览器确认页面正常 → 进入下方「日常开发循环」

B. 已在应用目录（继续开发）

1. 确认上下文：

platform app preflight

若失败且当前目录没有 .platform/source-context.json，回到路径 A。

2. 按任务选本地 dev 模式：

3. 进入「日常开发循环」

日常开发循环（本地为主）

这是 Agent 的默认工作模式，应反复执行直到任务完成：

platform dev（或 --remote-bindings）
  → 改代码
  → 本地浏览器确认
  → 重复「改代码 → 本地确认」

约定：

• platform dev 读 .platform/source-context.json，一般不需要手配 .env.local
• 首次 dev 缺少 node_modules 时，CLI 会按项目声明的 npm / pnpm / yarn 精确版本与 lockfile 自动安装；不跨包管理器转换
• 若 CLI 报告 lockfile 缺失或与 package.json 不同步，先修正项目的包管理器声明和 lockfile，再重新启动
• 默认不会自动重启；需要时在 app.yaml 设 dev.auto_restart: true
• 先复用模板已有能力 API、路由和页面结构，再考虑新增抽象（入口见 template.md）
• URL 按 Host-root 开发：页面、同源 API 和静态资源使用以 / 开头的语义路径；Auth 回跳和平台能力 URL 使用模板提供的构建函数

只有本地开发循环跑通、用户要求验收或准备交付时，才进入云端步骤。

云端验证（本地满意之后）

本地改完并确认无误后，先按模板选择 Preview 构建方式。

frontend-app-vite 默认优先本地构建上传：

platform app submit --message "<msg>"
platform preview generate --local-build
platform preview

只有以下情况改走普通云端构建：

• 模板是 backend-app-node
• --local-build 的源码或素材预检不通过
• 明确需要验证云端构建环境，而不是只验证静态 Preview 产物

platform app submit --message "<msg>"
platform preview generate
platform preview

说明：

• submit 把本地源码沉淀为平台版本；目录已绑定时通常不需要先 platform app use
• 两种 preview generate 都只影响 preview 环境，不会自动更新 prod；未显式 submit 时可能自动复用或补提交当前目录源码
• --local-build 当前只支持 frontend-app-vite 的静态 Preview；CLI 会执行预检、本地 build、上传 dist 并切换 Preview
• --local-build 不允许源码携带本地图片、字体、音视频、PDF 等素材文件；先上传素材库并改为平台素材引用
• backend-app-node 使用标准云端构建，必须使用普通 platform preview generate
• Dev Workspace 和高频云端 push 等高级路径见 concepts.md

正式发布（用户明确要求上线时）：

platform publish set --source-version <srcver> --status published

运行时 vs 控制面

控制面操作 → 一律 platform CLI
应用内能力 → 模板已提供的能力 API

不确定时查 runtime-vs-control.md。

模板代码入口：

• frontend-app-vite：src/platform/*、src/app.tsx、src/pages/*
• backend-app-node：
• SEO 页面：src/server/routes/seo-pages.ts、src/server/lib/*、src/server/content/*
• SPA 页面：src/web/platform/*、src/web/app.tsx、src/web/pages/*

任务 → 分册

不要做

1. 没跑通本地 platform dev 就开始大量写代码或上云端 Preview
2. 用 npm run dev 代替 platform dev / --remote-bindings 做平台联调
3. 在应用代码里写死 appId 或工作台展示的完整 Preview / Prod 访问地址
4. 绕过模板已提供的能力 API 重复建立接入层
5. 把云端 Preview 当成日常开发的热更新环境
6. 工作台 / 应用模板已创建的应用再次 app create（应 checkout）

推断 tenant / app

遇到第一个确定来源就停止：

1. 用户显式提供
2. 当前目录 .platform/source-context.json
3. 会话里最近的 create/checkout 命令
4. platform app current
5. platform app list --tenant <tenant-id>
6. 问用户——只问一个问题

常见卡点（本地优先排查）