sealos-app-builder

Sealos 应用构建器

概述

使用此技能，可将通用 Web 应用转换为能在 Sealos Desktop 中运行的 Sealos 应用，也可从零搭建新的 Sealos 应用。重点关注可重复使用的部分：SDK 初始化、会话访问、语言同步、业务数据集成、通过桌面测试应用进行本地调试，以及发布准备。

优先采用简单、易于讲解的实现方式，让初学者能够理解并扩展。

核心工作流

1. 确定起点

将请求归入以下路径之一：

1. 从零创建新的 Sealos 应用。
2. 改造现有 Web 应用，使其能在 Sealos Desktop 中运行。
3. 为已能渲染的应用添加 Sealos 身份和业务数据集成。
4. 编写文档或教程，而不是修改代码。

如果仓库中已有 Sealos 相关代码，请先检查本地源代码。具体来说：

1. 查找 packages/client-sdk 或同等 SDK 源代码。
2. 查找 providers/ 或类似目录下现有的 provider 应用。
3. 如果仓库已采用成熟的框架和路由模式，请沿用这些模式。

如果仓库中没有 Sealos 本地源代码，请以此技能附带的参考资料为基准。

2. 集成 Sealos 应用 SDK

将 Sealos Desktop 集成作为根级别的关注点。

使用任何起始模板前，请先安装 SDK：

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. 将 Sealos 身份连接到业务数据

对大多数应用而言，集成的关键不在 iframe 本身，而在于用户映射。

1. 使用 session.user.id 作为稳定的应用级用户标识符。
2. 在有用时，持久化 name、avatar、k8sUsername 和 nsid 等便于展示的字段。
3. 将业务数据保存在应用自己的数据库和 API 路由中。
4. 将 Sealos 用户身份作为业务逻辑的输入，而不是整个后端。

需要获取架构或 API 方面的指导时，请阅读 references/data-integration-patterns.md。

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

不要认为浏览器成功渲染就意味着 Sealos 集成正常。

通常需要通过 Sealos Desktop 在 iframe 中打开应用，getSession() 等 SDK 调用才能成功。如果任务涉及本地调试，请阅读 references/local-debug-and-test-app.md。

遵循以下规则：

1. 明确说明页面何时在 Sealos Desktop 之外运行。
2. 优先使用 Sealos Desktop 中的测试应用进行端到端验证。
3. 避免在服务端调用 SDK。

5. 为发布做好准备

当用户需要部署或准备上线时：

1. 验证环境变量。
2. 验证数据库连接和迁移。
3. 确认从 Sealos Desktop 启动时应用能够正常运行。
4. 确认任何跨应用导航或事件用法有效。
5. 总结仍需手动完成的注册或平台配置步骤。

将 references/publish-checklist.md 用作发布检查清单。

实施规则

保持集成简单

默认采用最精简可行的 Sealos 集成：

1. 一个根级 provider 或 store。
2. 一种业务身份映射模式。
3. 一条用于非 Desktop 访问的回退路径。

避免将 SDK 初始化分散到多个页面或组件中。

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

如果当前工作区包含实际的 Sealos SDK 源码或现有 Sealos 应用：

1. 检查这些源码。
2. 遵循实际导出的 API 和类型。
3. 指出与通用示例相比，仓库特有的差异。

使用官方 SDK 包名

默认在生成的示例和入门代码中使用 @labring/sealos-desktop-sdk。

只有当目标仓库已采用成熟的本地工作区别名，且用户明确要求保留时，才偏离此规则。

决策指南

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

提供：

1. 对运行时模型的简短说明。
2. 最精简的 SDK 集成示例。
3. 业务数据映射示例。
4. 通过 Sealos Desktop 测试应用进行本地调试的指导。

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

按以下顺序操作：

1. 检查当前应用入口。
2. 添加或重构单个根级 Sealos provider。
3. 将业务 API 连接到 session.user.id。
4. 验证在 Desktop 之外的回退行为。

如果用户要求提供文档或教程

围绕以下内容组织输出：

1. 什么是 Sealos 应用。
2. 如何初始化 SDK。
3. 如何获取和使用会话。
4. 如何集成业务数据。
5. 如何通过 Desktop 测试应用进行调试。
6. 如何发布和验证。

参考资料

只阅读任务所需的文件：

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，了解用户映射、数据库架构和 API 形式。
5. references/local-debug-and-test-app.md，了解基于 iframe 的调试和 Desktop 测试应用设置。
6. references/publish-checklist.md，了解发布就绪检查步骤。