Kit SDK 与 API 边界
当前真实的安装范围浏览器 API、隔离操作能力与开发者控制面。
从公开包开始
独立 Kit 使用版本化的 @sine-kits/kit-contracts、@sine-kits/kit-sdk、@sine-kits/kit-ui 和 @sine-kits/kit-cli。不得导入平台数据库、认证、worker 或应用外壳等私有实现。包访问与 CLI 命令见开发流程。
七个平台应用各有职责：web 提供公开网站与登录，console 管理用户工作区，developer 管理发布，admin 进行独立审核，backend 提供受信 API，worker 协调异步执行和部署，docs 提供帮助。Kit 子站是独立部署，不是可读取平台私有代码的第八个平台应用。
浏览器授权
从 @sine-kits/kit-sdk/browser 导入浏览器 API：
readLaunchDescriptor()读取平台启动时提供的公开安装与授权绑定信息。completeKitAuthentication()完成同源弹窗回调，并从 URL 清除授权回调参数。createKitClient({ platform, installationId })创建绑定安装的客户端。client.authenticate(launch)执行授权码 + PKCE，并检查返回的安装与发行绑定。client.clearAuthorization()清除该客户端内存中的授权，不是服务端撤销所有会话。
浏览器客户端仅在内存中保留访问令牌，请求使用 credentials: "omit"，不读取共享平台 Cookie。请使用平台登记的启动流程，不要伪造 Bearer 令牌、写入 local storage 或放进 URL。除 loopback 外，端点 URL 必须使用 HTTPS。
本地开发站点可使用 CLI 的开发代理上下文；这是仅限开发的路径，不是匿名生产凭证或 Agent Grant。开发者登录不会赋予访问买家安装的权限。
安装范围内的 HTTP 接口
以下路由由 backend 实现，建议优先通过 SDK 调用。:installationId、:recordId、:assetId、:runId 表示接口返回的真实 ID，不是路径中的字面文本。
| 浏览器 SDK 方法 | Backend 路由 | 行为 |
|---|---|---|
installation() | GET /api/v1/installations/:installationId | 读取获准的安装 |
records.list({ type }) | GET /api/v1/installations/:installationId/records?type=... | 列出记录，可按类型过滤 |
records.get(id) | GET /api/v1/installations/:installationId/records/:recordId | 读取单条记录 |
records.create({ type, data }) | POST /api/v1/installations/:installationId/records | 持久化 JSON 领域数据 |
assets.list() / assets.get(id) | GET /api/v1/installations/:installationId/assets 与 .../assets/:assetId | 读取资源元数据 |
assets.create(metadata) | POST /api/v1/installations/:installationId/assets | 按名称、MIME 类型、字节数和 SHA-256 创建元数据 |
assets.upload({ name, content }) | 创建元数据后，PUT /api/v1/installations/:installationId/assets/:assetId/content | 携带完整性元数据上传 Blob |
assets.download(id) | GET /api/v1/installations/:installationId/assets/:assetId/content | 下载获准的二进制内容 |
runs.list() / runs.create(input) | GET / POST /api/v1/installations/:installationId/runs | 列出任务或提交已声明的操作 |
runs.get(id) / runs.logs(id) | GET /api/v1/runs/:runId 与 .../:runId/logs | 读取获准任务及其日志 |
runs.cancel(id) | POST /api/v1/runs/:runId/cancel | 取消排队中或运行中的任务 |
修改请求里的 ID 不会改变授权范围。创建或启动已部署安装属于第一方所有者操作，不是通用 Kit SDK 能力。当前创建仅限发布者沙箱，并要求存在可用发行版本与就绪部署。
当前浏览器单个资源上传上限为 16 MiB。记录、资源和任务列表当前最多返回 1,000 条，SDK 未提供分页游标。这些是具体实现限制，不代表无限存储，也不是统一 API 速率限制。
提交操作并跟踪结果
runs.create 接收 operationId、JSON input 和可选 idempotencyKey。Backend 要求提供 key；省略时 SDK 会生成。网络结果不明确时，如需重试同一提交，应保留并复用原来的 key 和输入。用同一个 key 提交不同的操作、输入或发行内容会返回 IDEMPOTENCY_CONFLICT。
创建任务返回 HTTP 202 与任务对象，不会等待操作完成。用返回的 ID 调用 runs.get() 和 runs.logs()。操作必须在安装当前生效的 manifest 中声明。取消已终止任务会返回 RUN_TERMINAL；取消也不会撤销已完成的外部副作用或已保存记录。
操作通过受限能力执行
从 @sine-kits/kit-sdk/server 导入 defineOperation。Handler 接收符合操作合同的输入，以及绑定安装和任务的 context。在 kit.manifest.json 声明 handler、输入/输出 schema、所需能力、副作用和执行方式。
当前 Game Dev Kit 的 projects.create 接收 name 与 brief，通过 context.records.create 写入 game-project 记录。这是真实数据写入，不是模型生成接口。
| 操作 context | 可用方法 |
|---|---|
records | list、get、create |
assets | list、get、create、write、read |
| 日志 | log(message)，传输前进行脱敏 |
| 绑定 | 只读 installationId 与 runId |
宿主对每次能力调用进行授权。操作资源 RPC 使用规范 base64，单次内容上限为 512 KiB，不同于浏览器上传上限。Context 不是数据库连接、供应商密钥库或任意 HTTP 客户端。当前 SDK 未提供通用 3D 生成能力。
本地开发代码拥有开发者的操作系统权限，不应视为恶意代码隔离环境。已部署操作使用独立 runner 边界，不导入 web、backend 或平台 worker 进程执行。
发布与审核是不同接口
CLI 与开发者应用通过 /api/v1/developer/... 管理发布者项目、环境、制品、发行、部署及获准日志。独立审核使用 admin API。请优先使用已说明的 CLI，不要手工拼接上传、revision 或批准请求。
Release 标识不可变内容；deployment 将内容部署到指定环境。市场 listing 与付费 entitlement 是另外的产品概念。publish --env preview 不会自动批准、销售或授权 Kit。晋级要求当前环境 revision 与明确的 production 确认，不会重新构建制品。
错误与诊断
Kit JSON 成功响应把结果放在 data 中，资源下载则返回字节。Kit API 失败包含 error.code、error.message 和可用的 requestId。浏览器 SDK 抛出带 code、HTTP status 及可选 requestId 的 KitApiError。
报告问题时提供操作或部署 ID、状态与请求 ID，不要附上 Authorization 请求头、访问令牌、供应商密钥或私有记录内容。缺少连接或授权被拒绝时，应明确解决配置与权限问题，不能静默切换至付费平台账户或伪造成功结果。