Back to Details

sealos-app-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sealos App Builder

Sealos App Builder

Overview

概述

Use this skill to turn a generic web app into a Sealos app that runs inside Sealos Desktop, or to scaffold a new Sealos app from scratch. Focus on the repeatable parts: SDK initialization, session access, language sync, business-data integration, local debugging through a Desktop test app, and publish readiness.
Prefer a simple, teachable implementation that a beginner can understand and extend.
使用此技能可将通用Web应用转换为可在Sealos Desktop中运行的Sealos应用，或从头搭建一个新的Sealos应用。重点关注可复用部分：SDK初始化、会话访问、语言同步、业务数据集成、通过桌面测试应用进行本地调试，以及发布准备工作。
优先采用初学者易于理解和扩展的简单、可教学的实现方案。

Core Workflow

核心工作流程

1. Identify the starting point

1. 确定起点

Classify the request into one of these paths:
  1. Create a new Sealos app from scratch.
  2. Adapt an existing web app to run inside Sealos Desktop.
  3. Add Sealos identity and business-data integration to an app that already renders.
  4. Produce documentation or a tutorial instead of code changes.
If the repository already contains Sealos-related code, inspect local sources first. In particular:
  1. Look for 
    packages/client-sdk
    or equivalent SDK sources.
  2. Look for existing provider apps under 
    providers/
    or similar directories.
  3. Reuse the repository's established framework and routing patterns when they are already in place.
If the repository does not contain local Sealos sources, use the bundled references in this skill as the baseline.
将请求归类为以下路径之一：
  1. 从头创建新的Sealos应用。
  2. 适配现有Web应用以在Sealos Desktop中运行。
  3. 为已可渲染的应用添加Sealos身份认证和业务数据集成。
  4. 生成文档或教程而非修改代码。
如果仓库已包含Sealos相关代码，请先检查本地源码：
  1. 查找
    packages/client-sdk
    或等效的SDK源码。
  2. 查找
    providers/
    或类似目录下的现有提供商应用。
  3. 若仓库已确立框架和路由模式，请复用这些模式。
如果仓库不包含本地Sealos源码，请以本技能中的捆绑参考内容为基准。

2. Integrate the Sealos app SDK

2. 集成Sealos应用SDK

Treat Sealos Desktop integration as a root-level concern.
Before using any starter template, install the SDK first:
bash
pnpm add @labring/sealos-desktop-sdk
Use 
npm install @labring/sealos-desktop-sdk
or 
yarn add @labring/sealos-desktop-sdk
when the project uses a different package manager.
  1. Initialize the SDK once in a client-only root component.
  2. Fetch 
    getSession()
    and 
    getLanguage()
    early.
  3. Store session, language, loading state, and desktop availability in a shared context or store.
  4. Listen for language changes through 
    EVENT_NAME.CHANGE_I18N
    when the app needs runtime language sync.
  5. Add a graceful fallback when the app is opened outside Sealos Desktop.
Read references/minimal-app-template.md before implementing the root integration. If the app uses Next.js App Router, also read references/nextjs-app-router.md.
Use one of these starter templates:
  1. assets/templates/react/sealos-provider.tsx for React.
  2. assets/templates/vue/use-sealos.ts for Vue.
将Sealos Desktop集成视为核心关注点。
在使用任何入门模板之前，先安装SDK：
bash
pnpm add @labring/sealos-desktop-sdk
若项目使用其他包管理器，请使用
npm install @labring/sealos-desktop-sdk
或
yarn add @labring/sealos-desktop-sdk
。
  1. 在仅客户端的根组件中初始化SDK一次。
  2. 尽早获取
    getSession()
    和
    getLanguage()
    。
  3. 将会话、语言、加载状态和桌面可用性存储在共享上下文或状态管理库中。
  4. 当应用需要运行时语言同步时，通过
    EVENT_NAME.CHANGE_I18N
    监听语言变化。
  5. 添加优雅的降级方案，以处理应用在Sealos Desktop外打开的情况。
在实现根集成之前，请阅读references/minimal-app-template.md。 如果应用使用Next.js App Router，还需阅读references/nextjs-app-router.md。
使用以下入门模板之一：
  1. React框架：assets/templates/react/sealos-provider.tsx
  2. Vue框架：assets/templates/vue/use-sealos.ts

3. Connect Sealos identity to business data

3. 连接Sealos身份与业务数据

For most apps, the key integration is not the iframe itself but the user mapping.
  1. Use 
    session.user.id
    as the stable app-level user identifier.
  2. Persist display-friendly fields such as 
    name
    , 
    avatar
    , 
    k8sUsername
    , and 
    nsid
    when useful.
  3. Keep business data in the app's own database and API routes.
  4. Model Sealos user identity as input to your business logic, not as your entire backend.
Read references/data-integration-patterns.md when you need schema or API guidance.
对于大多数应用来说，关键的集成点并非iframe本身，而是用户映射。
  1. 使用
    session.user.id
    作为稳定的应用级用户标识符。
  2. 按需持久化
    name
    、
    avatar
    、
    k8sUsername
    和
    nsid
    等友好显示字段。
  3. 将业务数据存储在应用自身的数据库和API路由中。
  4. 将Sealos用户身份建模为业务逻辑的输入，而非整个后端。
当需要 schema 或 API 指导时，请阅读references/data-integration-patterns.md。

4. Prepare local debugging in the real runtime

4. 准备真实运行环境中的本地调试

Do not assume a successful browser render means Sealos integration works.
The app usually needs to be opened by Sealos Desktop in an iframe for SDK calls like 
getSession()
to succeed. When local debugging is part of the task, read references/local-debug-and-test-app.md.
Use these rules:
  1. Explain clearly when a page is outside Sealos Desktop.
  2. Prefer a test app inside Sealos Desktop for end-to-end verification.
  3. Avoid server-side SDK calls.
不要假设浏览器渲染成功就意味着Sealos集成正常工作。
应用通常需要由Sealos Desktop在iframe中打开，才能使
getSession()
等SDK调用成功。如果任务包含本地调试，请阅读references/local-debug-and-test-app.md。
遵循以下规则：
  1. 清晰说明页面何时处于Sealos Desktop外部。
  2. 优先使用Sealos Desktop内的测试应用进行端到端验证。
  3. 避免在服务器端调用SDK。

5. Prepare for publishing

5. 准备发布

When the user wants deployment or launch readiness:
  1. Verify environment variables.
  2. Verify database connectivity and migrations.
  3. Confirm the app works when launched from Sealos Desktop.
  4. Confirm any cross-app navigation or event usage is valid.
  5. Summarize the remaining manual registration or platform configuration steps.
Use references/publish-checklist.md as the release checklist.
当用户需要部署或发布准备时：
  1. 验证环境变量。
  2. 验证数据库连接和迁移。
  3. 确认应用从Sealos Desktop启动时可正常运行。
  4. 确认任何跨应用导航或事件使用均有效。
  5. 总结剩余的手动注册或平台配置步骤。
以references/publish-checklist.md作为发布检查清单。

Implementation Rules

实现规则

Keep the integration simple

保持集成简洁

Default to the smallest viable Sealos integration:
  1. One root provider or store.
  2. One business identity mapping pattern.
  3. One fallback path for non-Desktop access.
Avoid spreading SDK initialization across multiple pages or components.
默认采用最小可行的Sealos集成方案：
  1. 一个根提供者或状态管理库。
  2. 一种业务身份映射模式。
  3. 一种针对非桌面访问的降级路径。
避免在多个页面或组件中分散SDK初始化逻辑。

Prefer the repository's real SDK surface

优先使用仓库中的真实SDK接口

If the current workspace contains actual Sealos SDK sources or existing Sealos apps:
  1. Inspect those sources.
  2. Follow the real exported APIs and types.
  3. Call out repository-specific differences from generic examples.
如果当前工作区包含实际的Sealos SDK源码或现有Sealos应用：
  1. 检查这些源码。
  2. 遵循实际导出的API和类型。
  3. 指出仓库特定实现与通用示例的差异。

Use the official SDK package name

使用官方SDK包名

Use 
@labring/sealos-desktop-sdk
in generated examples and starter code by default.
Only deviate from that if the target repository already has an established local workspace alias and the user explicitly wants to preserve it.
默认在生成的示例和入门代码中使用
@labring/sealos-desktop-sdk
。
仅当目标仓库已确立本地工作区别名且用户明确要求保留时，才可以偏离此规则。

Decision Guide

决策指南

If the user asks for "How do I build a Sealos app?"

如果用户询问“如何构建Sealos应用？”

Provide:
  1. A short explanation of the runtime model.
  2. A minimal SDK integration example.
  3. A business-data mapping example.
  4. Local debugging guidance through a Sealos Desktop test app.
提供以下内容：
  1. 运行时模型的简短说明。
  2. 最小化SDK集成示例。
  3. 业务数据映射示例。
  4. 通过Sealos Desktop测试应用进行本地调试的指南。

If the user asks to modify an existing app

如果用户要求修改现有应用

Do this order:
  1. Inspect the current app entry point.
  2. Add or refactor a single root Sealos provider.
  3. Wire business APIs to 
    session.user.id
    .
  4. Verify fallback behavior outside Desktop.
按以下顺序操作：
  1. 检查当前应用的入口点。
  2. 添加或重构单个根Sealos提供者。
  3. 将业务API与
    session.user.id
    关联。
  4. 验证在桌面外的降级行为。

If the user asks for documentation or a tutorial

如果用户要求文档或教程

Structure the output around:
  1. What a Sealos app is.
  2. How to initialize the SDK.
  3. How to obtain and use the session.
  4. How to integrate business data.
  5. How to debug through a Desktop test app.
  6. How to publish and verify.
按以下结构组织输出：
  1. Sealos应用是什么。
  2. 如何初始化SDK。
  3. 如何获取和使用会话。
  4. 如何集成业务数据。
  5. 如何通过桌面测试应用进行调试。
  6. 如何发布和验证。

References

参考资料

Read only the files needed for the task:
  1. references/sdk-capabilities.md for available SDK APIs and runtime behavior.
  2. references/minimal-app-template.md for the recommended root integration pattern.
  3. references/nextjs-app-router.md for a concrete Next.js App Router placement example.
  4. references/data-integration-patterns.md for user mapping, database schemas, and API shapes.
  5. references/local-debug-and-test-app.md for iframe-based debugging and Desktop test app setup.
  6. references/publish-checklist.md for launch-readiness steps.
仅阅读任务所需的文件：
  1. references/sdk-capabilities.md：查看可用的SDK API和运行时行为。
  2. references/minimal-app-template.md：推荐的根集成模式。
  3. references/nextjs-app-router.md：具体的Next.js App Router部署示例。
  4. references/data-integration-patterns.md：用户映射、数据库schema和API格式。
  5. references/local-debug-and-test-app.md：基于iframe的调试和桌面测试应用设置。
  6. references/publish-checklist.md：发布准备步骤。