# SuperPlatform 接入总览

> 读完这一页，你应该知道 SuperPlatform 是什么、有哪些能力、自己的项目该用哪几块、细节文档去哪找。每节只写最短路径，细节在文末「文档索引」列出的专文里。

## SuperPlatform 是什么

SuperPlatform（原名 SuperSDK）是一站式的 App 开发与运营平台。业务团队只写业务代码，与业务无关的基础工作由平台承接：

- **App 端**：Android / iOS SDK 提供 H5 容器（WebView + JSBridge + 离线包），H5 通过一份 `supersdk.js` 调用登录、支付、分享、广告、文件等原生能力。
- **上线**：静态站点（SuperSite）和容器后端（SuperRun）一条命令发布，自动分配域名和 HTTPS。
- **运营**：云控配置、事件分析、用户反馈、短链、渠道归因、定时任务、数据库接入，统一在一个控制台里按「项目 × 环境」管理。

平台有三个入口，能力相同、面向不同使用者：

| 入口 | 是什么 | 谁用 |
|---|---|---|
| 控制台 | 网页管理后台，<https://console.superplatform.ai> | 人：建项目、看数据、改配置 |
| SuperCLI | 命令行工具 `supercli`（npm 包 `@supersdk/supercli`） | 人、AI Agent、CI：建工程、构建、发布、查询、运维 |
| SDK | Android / iOS SDK 与前端 `supersdk.js` | 运行在用户设备上的业务代码 |

各能力相互独立，可以只用其中一块：不集成 SDK 也能用 SuperCLI 托管站点和后端；不用托管也能只集成 SDK。

## 能力一览

| 能力 | 解决什么 | 怎么用 | 细节 |
|---|---|---|---|
| H5 容器 | App 内网页秒开，并能调用原生能力 | Android / iOS SDK + `supersdk.js` | [Android](https://www.superplatform.ai/android.md) · [iOS](https://www.superplatform.ai/ios.md) · [JSSDK](https://www.superplatform.ai/jssdk.md) |
| 登录、支付、广告 | 第三方登录、应用内购买、广告变现一次接入 | `supersdk.js` 的 API + Native 可选模块 | [登录](https://www.superplatform.ai/jssdk/api/login/) · [支付](https://www.superplatform.ai/jssdk/api/pay/) · [广告](https://www.superplatform.ai/jssdk/ads/) |
| 云控配置 | 不发版就能改文案、开关、活动规则，可回滚 | 控制台或 `supercli settings` 编辑；客户端用 SDK 读取 | [JSSDK 环境与配置](https://www.superplatform.ai/jssdk/api/env-config/) · [SuperCLI](https://console.superplatform.ai/supercli.md) §8 |
| 事件分析 | 埋点入库，看趋势、留存和自定义看板 | SDK `reportEvent` 上报；控制台或 `supercli analytics` 查询 | [JSSDK 宿主方法](https://www.superplatform.ai/jssdk/api/host-methods/) · [SuperCLI](https://console.superplatform.ai/supercli.md) §9 |
| 用户反馈 | 应用内收集反馈，控制台集中处理 | SDK `submitFeedback`；控制台查看 | [JSSDK 宿主方法](https://www.superplatform.ai/jssdk/api/host-methods/) |
| 短链 | 把长链接或一段 HTML 变成可分享的短链 | SDK `requestShortUrl` 或 `supercli shortlink` | [JSSDK 分享](https://www.superplatform.ai/jssdk/api/share/) · [SuperCLI](https://console.superplatform.ai/supercli.md) §9.1 |
| 渠道归因 | 知道用户从哪个渠道来 | 控制台配置渠道与 Webhook（仅控制台可操作） | [广告与归因](https://www.superplatform.ai/jssdk/ads/) |
| SuperSite 静态站点 | 网站、H5 发布到全球加速节点，带回滚 | `supercli deploy`、`supercli site` | [SuperCLI](https://console.superplatform.ai/supercli.md) §6 |
| SuperRun 容器服务 | 有镜像就能跑后端：环境变量、密钥、日志、回滚、自定义域名 | `supercli deploy`、`supercli super-run` | [SuperCLI](https://console.superplatform.ai/supercli.md) §6.1 |
| SuperScheduler 定时任务 | 按 cron 向指定 HTTP(S) 地址发请求，最短 1 分钟 | `supercli scheduler` 或控制台 | [SuperCLI](https://console.superplatform.ai/supercli.md) §8.1 |
| 数据库接入 | 把已有的 PostgreSQL / MySQL 登记到平台，受控查询并绑定给服务 | `supercli db` 或控制台 | [SuperCLI](https://console.superplatform.ai/supercli.md) §9 |
| CDN 上传 | 把图片等静态资源传到 CDN | `supercli cdn` | [SuperCLI](https://console.superplatform.ai/supercli.md) §9.1 |
| 多环境 | 测试与线上的配置、数据、站点、服务相互隔离 | 控制台或 `supercli env`；SDK 运行时切换 | 见下文「开始前」 |
| 组织与成员 | 多人协作，按 admin / member 分权 | 控制台或 `supercli org` | [SuperCLI](https://console.superplatform.ai/supercli.md) §7 |

## 按场景选路径

| 你的情况 | 用哪几块 | 按这个顺序读 |
|---|---|---|
| 已有原生 App，要内嵌 H5 页面 | Android / iOS SDK + `supersdk.js` | 本页「Android」「iOS」「前端」→ 对应专文 |
| 从零做一个 App | SuperCLI 工程模板 + 三端 SDK | 本页「CLI」→ SuperCLI 专文 §1 |
| 只有网站或 H5，没有 App | SuperSite 托管；需要埋点、反馈时加 `supersdk.js` 的浏览器模式 | 本页「CLI」「前端」 |
| 只要托管后端服务 | SuperRun，按需加数据库接入和定时任务；不需要任何 SDK | 本页「CLI」→ SuperCLI 专文 §6.1 |
| 只要定时调用自己的接口 | SuperScheduler | SuperCLI 专文 §8.1 |
| 已经接入，想做运营和数据分析 | 云控配置、事件分析、用户反馈 | 能力一览里对应行 |
| AI Agent 或 CI 自动操作平台 | SuperCLI + API Token | 本页「Agent 与 CI」→ SuperCLI 专文 §7、§10 |

## 开始前

三样东西先准备好，后面每一步都会用到：

1. **项目与 `spid`**：在[控制台](https://console.superplatform.ai)注册并创建项目，得到 `spid`。它是项目的唯一标识，8 位小写字母或数字（下文示例统一用 `ab12cd34`）。SDK 初始化和 SuperCLI 的 `super.json` 都要用它。
2. **项目环境**：每个项目自带 `prod` 环境，可以再建测试环境（一个项目最多 5 个，名字为 1–10 位小写字母或数字）。配置、数据、站点、服务都按环境隔离。SDK 在运行时用 `setAPIEnvironment` 选环境，SuperCLI 的多数命令用 `--env` 选环境。
3. **凭据**：人在本机用 `supercli login` 浏览器登录；AI Agent 和 CI 用控制台签发的 `sst_` API Token。凭据的权限等于签发者在组织内的角色。

`supercli login --environment prod` 里的 `prod` 指平台自身的线上控制台，和上面的「项目环境」不是一回事；正常使用一律填 `prod`。

## CLI

SuperCLI 是操作平台的命令行入口：创建工作空间、从模板生成或登记工程、构建、发布站点和服务，以及管理配置、定时任务、数据库、短链和查询数据。需要 Node.js 18 及以上。

```bash
npm install -g @supersdk/supercli
supercli login --environment prod

supercli init my-workspace            # 交互式询问 spid，生成 super.json
cd my-workspace
supercli add site apps/web --project web --env-target prod --slug acme --env prod

supercli build-all --output-dir .super/build
supercli deploy --project web --env-target prod --build-dir .super/build
```

`super.json` 是工作空间配置，一份配置对应一个 `spid`。已有工程用 `supercli register` 登记，不会改动工程文件。完整命令、配置格式和故障处置见 [SuperCLI 接入说明](https://console.superplatform.ai/supercli.md)。

## 前端

H5 引入 `supersdk.js`，用全局对象 `SuperSDK` 调用能力。同一份代码两种运行方式：

- 在 App 的 H5 容器里，调用经 JSBridge 交给原生执行。
- 在普通浏览器里，先调用 `initFallback` 传入 `spid` 和服务端地址，埋点、反馈等能力直接走网络，原生独有的能力会降级。

```javascript
if (SuperSDK.isInApp()) {
  const env = await SuperSDK.getEnv();
}
await SuperSDK.reportEvent('page_view', { page: 'home' });
```

最短路径和全部 API 见 [JSSDK 文档](https://www.superplatform.ai/jssdk.md)（网页版 <https://www.superplatform.ai/jssdk/>）。

## iOS

通过 SPM 或 xcframework 集成，启动时设置项目环境并初始化。

```swift
try SuperSDKManager.shared.setAPIEnvironment("prod")
try SuperSDKManager.shared.initialize(spid: "ab12cd34", provider: MySDKProvider())
```

详见 [iOS 接入文档](https://www.superplatform.ai/ios.md)（网页版 <https://www.superplatform.ai/ios/>）。

## Android

Maven 引入 `com.supersdk:supersdk`，在 `Application` 里设置环境并初始化。最低支持 Android 6.0（minSdk 23）。

```groovy
implementation 'com.supersdk:supersdk:<版本号>'
```

```java
SuperSDK.setAPIEnvironment("prod");
SuperSDK.init(this, "ab12cd34", new MySDKProvider());
```

最新版本号见[更新日志](https://www.superplatform.ai/changelog.md)；SNAPSHOT 版本需要额外添加快照仓库。Google 登录、Google Play 内购、AdMob 广告是按需引入的可选模块。详见 [Android 接入文档](https://www.superplatform.ai/android.md)（网页版 <https://www.superplatform.ai/android/>）。

## 服务端

平台的服务端由 SuperPlatform 运营，业务方不需要部署任何平台组件。业务后端与平台的关系有这几种：

- 托管：后端打成镜像后用 SuperRun 运行，见 [SuperCLI 接入说明](https://console.superplatform.ai/supercli.md) §6.1。也可以继续跑在自己的服务器上，不影响使用其他能力。
- 支付：客户端完成购买后，由业务后端校验并发货，后端是发货的唯一依据。见 [IAP 推荐架构](https://www.superplatform.ai/jssdk/iap-architecture/) 与 [支付 API](https://www.superplatform.ai/jssdk/api/pay/)。
- 登录：SDK 返回第三方签发的身份凭证，由业务后端校验后换取自己的登录态。见 [登录 API](https://www.superplatform.ai/jssdk/api/login/)。
- 事件上报：由客户端 SDK 直接上报到平台，后端不需要转发。见 [JSSDK reportEvent](https://www.superplatform.ai/jssdk/api/host-methods/)；后端或脚本要查数据时用 `supercli analytics`。
- 云控拉取：客户端 SDK 按 `spid` 和环境拉取配置。见 [JSSDK 环境与配置](https://www.superplatform.ai/jssdk/api/env-config/)；后端或脚本要读写配置时用 `supercli settings`。
- 定时任务：SuperScheduler 按计划请求业务后端的接口，后端用请求头里的 HMAC 签名校验来源。见 [SuperCLI 接入说明](https://console.superplatform.ai/supercli.md) §8.1。
- 归因：渠道和回传 Webhook 在控制台配置。见 [广告与归因](https://www.superplatform.ai/jssdk/ads/)。

## Agent 与 CI

AI Agent 和 CI 通过 SuperCLI 操作平台，规则如下：

- 不要运行 `supercli login`（它需要浏览器）。用控制台签发的 `sst_` API Token，经环境变量 `SUPERCLI_TOKEN` 注入后再做构建和发布；不要把 Token 写进命令行参数。
- 每条命令加 `--output json --no-input`：标准输出恰好一行 JSON，过程日志走标准错误，按退出码判断结果（0 成功，2 业务或权限，3 凭据失效，4 限流，5 网络或服务端错误，6 用法错误）。
- 非交互模式下 `supercli init` 不会询问 `spid`，工作空间里要先有一份有效的 `super.json`。
- 有些事 Token 做不到：数据库写入（`db execute`）只允许真人执行，渠道归因管理只能在控制台操作。
- 不确定参数时运行 `supercli <command> --help`，不要猜。

```bash
export SUPERCLI_TOKEN=sst_...
supercli deploy --project web --env-target prod --build-dir .super/build --output json --no-input
```

完整约定见 [SuperCLI 接入说明](https://console.superplatform.ai/supercli.md) §7「账号、凭据与权限」和 §10「Agent Contract 与退出码」。

## 文档索引

带 `.md` 的地址返回纯文本 Markdown，适合 Agent 直接读取；网页版内容相同，按主题拆了页。

| 文档 | 覆盖什么 | 纯文本 | 网页版 |
|---|---|---|---|
| 接入总览 | 本页 | [guide.md](https://www.superplatform.ai/guide.md) | <https://www.superplatform.ai/guide/> |
| SuperCLI 接入说明 | 全部命令、`super.json`、构建与发布、凭据与权限、Agent 约定、故障处置 | [supercli.md](https://console.superplatform.ai/supercli.md) | 无 |
| Android 接入文档 | 集成、初始化、容器与离线包、各 Service 接口、可选模块、混淆配置 | [android.md](https://www.superplatform.ai/android.md) | <https://www.superplatform.ai/android/> |
| iOS 接入文档 | 集成、初始化、容器、各 Service 协议、完整示例 | [ios.md](https://www.superplatform.ai/ios.md) | <https://www.superplatform.ai/ios/> |
| JSSDK 文档 | 浏览器降级、全部 API、广告、IAP 推荐架构（篇幅最长，只查某个主题时优先读网页版对应分页） | [jssdk.md](https://www.superplatform.ai/jssdk.md) | <https://www.superplatform.ai/jssdk/> |
| 离线包规范 | 站点侧 `super_meta.json` 清单与离线包打包约束 | [offline-pkg-spec.md](https://www.superplatform.ai/offline-pkg-spec.md) | 无 |
| 更新日志 | 各版本变更和最新版本号 | [changelog.md](https://www.superplatform.ai/changelog.md) | <https://www.superplatform.ai/changelog/> |
| 平台能力介绍 | 面向业务目标的能力说明 | 无 | <https://www.superplatform.ai/platform/> |

机器可读的文档清单在 <https://www.superplatform.ai/llms.txt>。