1. 准备环境与制品

本步目标： 备齐 SDK 制品、模型连接和底座。下一步才创建应用；此时不需要操作管理平台。

1. 检查环境和目录

使用 JDK 17、Node.js 22、PowerShell 7。平台与 SDK 均使用公开发行版 0.1.0，无需取得三个私有源码仓库权限。

下载本教程的 ZIP 并解压到 tutorial，目录结构为：

tutorial/
├─ backend/
├─ frontend-react/
├─ frontend-vue/
├─ scripts/
└─ releases/                 ← 下一步放置底座 Jar

2. 下载底座与前端 SDK

在 tutorial 根目录执行：

$release = 'https://github.com/SageTripp/sparktide-docs/releases/download/v0.1.0'
New-Item -ItemType Directory -Force releases | Out-Null
Invoke-WebRequest "$release/sparktide-platform-0.1.0.jar" -OutFile releases/platform-0.1.0.jar
Invoke-WebRequest "$release/sparktide-frontend-sdk-0.1.0.tgz" -OutFile frontend-react/vendor/sparktide-frontend-sdk-0.1.0.tgz
# 只体验 Vue 时，可将上一条的目标目录改成 frontend-vue/vendor。
# 两个框架都体验时，再复制一份：
Copy-Item frontend-react/vendor/sparktide-frontend-sdk-0.1.0.tgz frontend-vue/vendor/

后台示例已配置公开 Maven 仓库，会在第 2 步初始化应用时自动解析 SDK。安装前可用 Get-FileHash -Algorithm SHA256 与发行页的 SHA256SUMS 对照，SDK 安装方式见版本与获取。

3. 准备实际模型

需要一个支持 Chat Completions、工具调用和流式输出的模型服务，记下完整请求地址、实际模型标识和 API Key。教程不指定供应商，也不替你启用付费服务；仅有 Responses API 的地址不能直接用于此示例。

在 tutorial 根目录执行，替换地址与模型标识：

.\scripts\prepare.ps1 -ModelEndpoint 'https://你的模型域名/v1/chat/completions' -ModelId '实际模型标识'

脚本交互读取 API Key，生成 .local/platform.env、.local/business.env、.local/browser-token.txt。前两者只给服务进程使用，最后一个是本地业务登录令牌。管理员、USER、回调和模型密钥用途不同，不互相替代。

配置只生成一次，不覆盖已有 .local。真实密钥不得放在 Markdown、源码或前端构建变量里。后台声明保存 secretRef=MODEL_API_KEY，真实 Key 注入底座。

4. 在单独终端启动底座

新开终端，在 tutorial 根目录执行：

& .\scripts\use-env.ps1 .\.local\platform.env
java -jar .\releases\platform-0.1.0.jar

保持该终端运行。首次本机学习使用默认 H2 数据目录；生产使用 PostgreSQL，参考Docker 部署。这里的 SPARKTIDE_ALLOW_HTTP=true 仅用于回环开发连接，正式环境使用 HTTPS。

如果 8080 被其他服务占用，先选择一个空闲端口，并同步修改平台 PORT 与两个 env 文件的 SPARKTIDE_PLATFORM_URL，不要停止无关服务。

检查点

在另一终端运行：

(Invoke-RestMethod http://127.0.0.1:8080/actuator/health).status

应输出 UP。这只表示底座存活，模型调用将在第 5 步验证。底座出站策略已绑定模型 origin、回调 origin 与 tutorial 应用；其他环境的规则见环境变量。