跳到主要内容

更新日志

embed SDK 和 platform API 的重要变更。wire contract 在 /embed/v1/* 和 /inference-api/b2b/v1/* 下进行版本管理；破坏兼容性的变更 会作为新的主版本与旧版本并行发布（CDN 版本管理）。

2026-09​

  • Capability-policy SSOT。 Product → scope 和 tier → API-capabilities 现在只在 @kaleidr/shared-types 中定义一次 （B2B_PRODUCT_REQUIRED_SCOPE, B2B_TIER_API_CAPABILITIES），并配有 parity tests。由 shared-api（mint / rotate / PATCH clamp）、 inference-api（session exchange, runtime credentials）以及文档共同使用。
  • 有效 capability = 已存储 key × 当前 tier。 Session exchange 和所有 runtime credential path 都会根据组织的当前 tier 重新计算 admission — 如果 Pro-tier key 降级为 Free，则从该时刻开始只会创建 tile session。使用不同的 subcode： tier_capability_not_allowed（以前拥有，但当前 tier 已不再允许）与 insufficient_scope（从未拥有）。
  • Billing plan 变更会使 apikey:* cache 失效。 Subscription webhook 会清除每个 key 的 snapshot，使 downgrade/upgrade 立即 影响 runtime。由于 session 会在每次 request 时重新读取 key 的 live policy， downgrade 现在也会影响已经创建的 session — 不再受 session TTL 限制。upgrade 仍然需要新的 session，因为 session 只能相对其 parent 收窄权限。
  • 拒绝 Free-tier PATCH 扩权。 编辑 Free-tier key，试图将 scopes / allowed_products 扩展到 tier admission 之外时， 会返回 403 tier_capability_not_allowed，包括 empty-products = all 的情况。
  • 已移除 SSE grounding event。 Grounding 仍会影响回答； 只是不会再通过 wire 发送 frame。曾监听该事件的客户端 将不再收到它。

2026-08​

  • 底图访问采用密钥授权。 第三方直接使用 tile.kaleidr.com 会受到限制；<kaleidr-map> embed 和 Kaleidr 托管地图不受影响。底图 session 会扣减组织的 共享每月地图加载额度 （quota）。
  • Session exchange + refresh。 Publishable key 会被交换为 短期、绑定 origin 的 session（kld_sess_{env}_…, 15-min TTL）； session refresh 由 SDK 处理。
  • Place bridge / iframe seam。 已标准化 iframe 产品与父 页面之间跨 frame Place event 的 postMessage seam。
  • 组织默认底图。 当 embed 未指定时，/sdk/sessions 会返回组织已保存的 默认 basemap_style_id；SDK 会先应用它，再回退到 kaleidr-morning。
  • 浏览器拒绝 server key。 SDK 在 mount 时会拒绝 kld_sk_… （server key 仅用于服务端）。
  • Dev / prod CDN + API bake。 两个环境都通过 版本稳定的 endpoint 提供；viewerBase 已从 loader base 分离， tileBase 也为 editor 的 tile CDN 单独拆分。
  • Seam v2 路线颜色。 Route event 在稳定 contract 中携带 color / label / alternatives / comparison。

v1​

  • kaleidr.js loader + <kaleidr-map> element — 一个 façade、四个 product（chat / viewer / editor / tile）、两种 doorway。
  • Publishable browser key（kld_pk_）和 server key（kld_sk_），包含 scopes ai | maps | design | vendor；publishable key 会被交换为 短期、绑定 origin 的 session。旧版 kld_live_ key 继续 可用。
  • /inference-api/b2b/v1/chat/* (SSE) + /design/* route family。

此页面会随着版本发布持续补充。