ZZD public AI gateway · zzd_public_ai_gateway_v3
Resource: 08 · BaaS / 使用已有数据与服务
Canonical map: https://zzd.show/docs/ai/map.json
Full handbook: https://zzd.show/llms-full.txt
REST capabilities: https://zzd.show/api/v1/capabilities/

# 使用作品已经绑定的数据与服务

先按意图选择一段，读取本页边界后直接进入代码，无需遍历完整手册：

- 保存/读取记录、恢复用户状态：[数据与状态](/docs/ai/branch/baas-data/)。
- 多端同步、刷新进度：[实时订阅与有限刷新](/docs/ai/branch/baas-realtime/)。
- 已绑定服务、慢任务结果：[服务与任务](/docs/ai/branch/baas-services/)。

已有合法接入继续使用；新 Demo 不要求新凭据。AI 在原作品内完成动作并汇报结果。
只在确实没有可用的授权接入时走现有登录/明确授权流程；未知 Space、未绑定、
缺权限、暂时离线或当前环境不支持，分别处理，不能自动建 token、扩大 scope 或 provision。

## 先区分三个调用面

| 当前环境 | 已有调用面 | 边界 |
| --- | --- | --- |
| 正常主站编辑器，已有 owner/member 会话 | classic `SpaceClient`；注入的 `AppRuntime` 服务方法 | REST 带现有 session；每项 Space/服务权限仍由服务器核验。WS 仅可信主站 Origin。 |
| 隔离作品/预览 | 注入 `AppRuntime` / `ZZDSpaceSDK`；另有已绑定集合的 classic 文档适配器 | 注入 SDK 存在不代表每个方法可用。当前隔离上下文的 `identity_api.available=false`，不开放通用 identity state/service/WS；只有满足当前 Show 会话、绑定、启用状态和集合授权的 docs 操作可走专用现有路由。 |
| 外部已授权开发工具 | capabilities 宣布的 `/api/v1/` | BaaS 仅 `POST /api/v1/shows/{show_id}/baas/runtime-identity/` 的有界配置面；不是通用文档 CRUD、WS 或任意服务凭据。 |

配置上述 runtime-identity 端点不证明隔离页面的 identity transport 已可用。
它仅创建/更新有界私有 profile、允许的 namespace、guest TTL 和明确确认的 guest-write；
不能接管 broader/non-v1 backend。其它绑定按原本人编辑器能力处理。

当前 ESM `space_sdk.mjs` 的 default 是 AppRuntime，named exports 只有
`auth,data,creator,motion,configure`；它不导出 `SpaceClient` 或 realtime 构造器。
本指南的 classic 请求生命周期示例对应 `20261011l.rest1` 原件，
加载 `https://zzd.show/static/js/js/space_sdk.js?v=20261011l.rest1`；加载成功/线上发布
仍以实际正常环境为准，这份离线源码指南不宣称已代用户验证线上响应。
优先使用已有注入全局；仅当上下文实际提供 `seen.runtime.sdk.module_url` 时才按该 URL
导入模块，缺字段不猜地址。classic 文件是 `/static/js/js/space_sdk.js`。
`seen.runtime.project` 是作品项目呈现信息，不是 BaaS spaceId。

普通 public fallback 仅保留原有 read/subscribe 规则；受保护 Space 不因 public 标记
获得这些 fallback。匿名写入、跨账户访问和跨域授权都不能从“有 SDK”推导。
service token、cookie、app secret、developer bearer 不进入 Show 源码、prompt、URL 或日志。

## 失败时只给准确下一步

- `401/auth_required`：恢复原正常登录；过期/撤销的作品会话从原 canonical 作品入口重新打开，
  仍拒绝就停止并说明原授权状态，不自动签发凭据。
- `403/forbidden:*`、`collection_not_granted`、`binding_mismatch`、`backend_disabled`：停止写入和重连；
  回原作品核对绑定/启用状态/已有授权，由有权者处理准确缺口，不换身份或扩大 scope。
- context `data:null`、`404/not_found/collection_not_found`：核对原作品和数据名称。
  文档 `data:null` 才是允许读取后的空记录；不要把 404 当“新建后端”的指令。
- schema/字段 `400/invalid_data/invalid_payload/missing_params`：按该方法和已声明 schema 修正输入；
  `409/revision_conflict` 重新读取后让用户处理差异，不静默覆盖。
- offline/网络失败或服务端错误：保留本地未提交意图，恢复后先只读确认原状态。
  不重复未知结果的 POST；429 时显示限流并等待明确重试，不忙循环。
- SDK 非 JSON 错误可能携带响应片段；UI 只呈现安全状态和下一步，别打印完整 error/body/context。

本文是当前普通已发布调用契约的指南，不承诺真实 provider、费用、外机或未获得的正式资格。