用途:当某个 /iblai-vibe-* 技能没有提供用户所需功能的 SDK 组件或 hook 时,不要在前端做变通,而是从 Next.js 路由处理器(route handler)用组织的 Platform API Token 调用平台 REST API。平台能做的所有事情都可通过该方式访问;同仓库的 iblai-api-* 技能(kind 为 api)记录各端点的方法、URL、请求体与错误。
凭证规则:浏览器端(客户端组件)使用已登录用户的会话令牌,由 SDK 自动附加,请求头为 Authorization: Token <dm_token>,用于 SDK hook 或组件已提供的一切,以用户身份和权限行事。服务端(路由处理器、server actions)使用 IBLAI_API_KEY(即 iblai.env 中的 TOKEN),通过 config.apiKey() 获取,请求头为 Authorization: Api-Token <key>,用于没有 hook 的功能以及需要组织权限的操作(管理员写入、跨用户读取、创建智能体、发送通知)。服务端调用 OpenAI 兼容的 /v1 时使用同一密钥,请求头为 Authorization: Bearer <key>,地址为 https://asgi.data.<domain>/api/ai-mentor/orgs/<org>/v1,用于聊天补全与模型列表。密钥绝不能加 NEXT_PUBLIC_ 前缀,不能在服务端文件之外读取,也不能发送到浏览器;config.apiKey() 在浏览器中按设计返回空字符串。
使用方式:先渲染 assets/platform.ts.j2 为 lib/iblai/platform.ts,其中导出 platformFetch(path, init?)(仅服务端,向 https://api.<DOMAIN> 发起带 Api-Token 头的 JSON 请求,抛出带平台状态与响应体的 PlatformError)、verifyCaller(req)(读取浏览器转发的 Authorization: Token <dm_token>,调用 GET /dm/api/core/token/verify/ 返回调用者用户名,令牌缺失或被拒时返回 null)、requireAdmin(req)(在 verifyCaller 基础上通过 GET /dm/api/core/platform/users/?platform_key=&query=<username> 检查调用者是否为 NEXT_PUBLIC_MAIN_TENANT_KEY 的管理员,否则返回 401/403)。再渲染 assets/route-example.ts.j2 为 app/api/admin/example/route.ts 作为模板:验证调用者、校验请求体、调用平台、返回结果并映射错误。错误映射:平台 401→401,403→403,404→404,429→429(额度上限,透传响应体,其中标明时间区间),其他→502 并附平台消息。
示例场景:管理员写入其他用户的元数据(仅组织管理员可指定 &username=<other>,SDK hook 无此参数,故为服务端调用);创建智能体(POST /dm/api/ai-mentor/orgs/${org}/users/${caller.username}/mentor-with-settings/,返回的 unique_id 是其他智能体技能所需的 UUID);向用户发送通知(POST /dm/api/notifications/orgs/${org}/send/,发送前需确认确切路径与请求体,并先与用户确认收件人列表)。
限制与验证:构造任何未从技能复制的 URL 前,需在实时 OpenAPI schema 中确认其存在(可下载 https://api.$DOMAIN/dm/api/docs/schema/ 并检索,或浏览 https://api.iblai.app/dm/api/docs/)。网关规则:DM 路由带 /dm 前缀(/api/core/… → /dm/api/core/…),edX 路由带 /lms。验证方式:运行 pnpm typecheck 与 pnpm test(helper 自带单元测试);用已登录浏览器测试路由,无令牌应 401,非管理员应 403,管理员应 200;确认密钥未被打印。首次使用若 iblai.env 中没有 ARCHITECTURE=,需先运行 /iblai-vibe-start 确定单组织/多组织/无头模式及登录方。