sealos-app-builder

Sealos App Builder

身份与发现

• 所有者： sealos-app-builder（/sealos-app-builder，以及 Sealos Desktop 应用、SDK、iframe、教程或发布请求）。
• 类别： 对应用/文档工作使用 local-artifact-mutation，并在有请求时将经过验证的应用交接给 sealos-deploy。
• 探针： APP-CODE-TUTORIAL、APP-SDK-SOURCE、APP-DESKTOP-VERIFY 和 APP-PUBLISH-HANDOFF。

范围与边界

编辑前，先对创建、适配、身份集成或教程工作进行分类。先检查本地 SDK 源码和提供方应用；SDK 初始化仅在客户端进行，业务数据保留在应用中，并明确说明在 Desktop 之外的回退行为。负责的输出包括项目代码、包元数据和教程；只有在提供 Desktop 证据后，才能声明已发布。

入口约定如下：

request -> classify(create|adapt|identity|tutorial) -> inspect local SDK/provider sources
         -> load branch references -> implement or document -> verify -> report terminal state

每个请求只使用一个分支。代码与教程之间存在歧义时，必须先停止，不得进行分支特定的编辑。本地 SDK 源码和现有提供方应用优先于通用包参考；没有本地源码时，才使用官方包作为后备方案。

风险与确认

本地源码不可用时，使用官方 SDK 包，并遵循现有的安装/工具确认边界。对会话、身份验证、数据库、环境和 SDK 诊断信息进行脱敏。服务端 SDK 初始化、缺少 Desktop 外部回退方案，以及未经验证的 Desktop iframe 都会导致请求停止。教程结果需附带教程证据；浏览器渲染需附带浏览器证据。

生命周期工作流

对于每个请求，确定分支、检查源码、集成 SDK 和身份信息、在相关时验证实际的 Desktop iframe，并准备发布交接。输出带有 branch、evidence、redaction 和 next_action 字段的请求级 success、stopped 或 error。success 结果证明分支输出已完成；stopped 结果指出缺少的前置条件及安全的后续操作；error 结果包含经过脱敏的诊断信息和恢复操作。

渐进式披露

选定入口边界后，只加载与分支相关的参考资料（minimal-app-template、框架放置方式、数据集成、本地测试应用或发布清单）。保留真实的 SDK 接口，避免调用服务端 SDK。对于代码分支，只有在明确框架并完成本地源码扫描后，才加载起始模板。

输出、停止与错误状态

• success：分支特定的源码/教程输出、SDK/会话/语言接线、Desktop 外部回退方案，以及在声明时提供的真实 Desktop/发布证据。
• stopped：代码与教程之间存在歧义、缺少 SDK 源码、服务端初始化、缺少回退方案，或缺少 Desktop/发布证据；同时提供安全的后续操作；不得声明已发布。
• error：SDK 源码/包不匹配、会话/运行时问题或发布前置条件失败；同时提供经过脱敏的诊断信息和恢复操作。

每个结果都记录 terminal_state: success|stopped|error、branch、evidence、redaction: passed|failed 和 next_action。会话值、凭据和完整环境值不得出现在结果文本中。

交接

对于直接请求，发送类型化交接：target: sealos-deploy、inputArtifact: verified app source plus Desktop, identity, language, business-data, and release evidence、allowedAction: deploy after app verification、failureReturn: sanitized SDK, iframe, or publish-prerequisite diagnostic 和 responseOwner: sealos-app-builder。部署负责人会重新检查自身的运行时门槛。教程分支和仅浏览器分支返回 target: none。

验证

使用真实的 Desktop iframe 检查清单和基准用例 app-builder-positive-sdk-iframe-publish 与 app-builder-violating-tutorial-or-missing-desktop。验证仅在客户端进行单次初始化、会话身份映射、语言同步、回退处理和发布前提条件，同时不暴露会话值。运行 python3 scripts/test_service_skill_contract.py，确认入门链接和共享服务契约。

概述

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

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

核心工作流

1. 确定起点

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

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

如果仓库中已有 Sealos 相关代码，请先检查本地源代码。尤其要：

1. 查找 packages/client-sdk 或同等的 SDK 源代码。
2. 查找 providers/ 或类似目录下现有的提供方应用。
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. 在仅客户端运行的根组件中调用一次 createSealosApp()。
2. 尽早获取 getSession() 和 getLanguage()。
3. 将会话、语言、加载状态和 Desktop 可用状态存储在共享上下文或状态库中。
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：发布就绪步骤。