TypeScript SDK（@ai-im/org-app-sdk）

浏览器端 JSAPI 的官方类型封装：纯类型 + Promise 化的薄封装，零运行时依赖，不重新实现协议——协议的唯一实现仍是页面里引入的 <script src="…/api/open/jsapi/jlt.js">（挂载全局 window.jlt）。协议变化时平台先改那份 JS，SDK 跟进类型。

服务端（Node/Python/Go…）调用开放 API 是标准 REST + JSON，不需要 SDK，见开放 API 参考与完整示例。

下载

当前版本 1.4.1（2026-08-26，适配 JSAPI 协议 jlt.js ≥ 1.3）。下面每个链接都是腾讯云 COS 上的真实文件，直接点击即可下载，不需要先装 npm 包。

文件	用途
`jlt-sdk.min.js`	浏览器直接引入（IIFE，全局 `jltSdk`，含对话组件与存储助手）
`jlt-sdk.js`	同上，未压缩版（调试可读）
`jlt-sdk.d.ts`	TypeScript 类型声明（配 script 标签使用）
`ai-im-org-app-sdk-1.4.1.tgz`	npm 离线安装包：`npm i ./ai-im-org-app-sdk-1.4.1.tgz`
`sha256sums.txt`	完整性校验

script 标签用法（不想引构建工具的页面）：

html

<!-- 先引平台的 jlt.js（协议实现），再引 SDK 封装 -->
<script src="https://<api域名>/api/open/jsapi/jlt.js"></script>
<script src="https://cos-pub.smabbit.com/open-platform/sdk/1.4.1/jlt-sdk.min.js"></script>
<script>
  if (jltSdk.isInJltClient()) {
    jltSdk.ready().then((ctx) => console.log(ctx.user.nickname, ctx.platform));
  }
</script>

TypeScript 项目里给 script 标签用法补类型：把 jlt-sdk.d.ts 放进项目，在引用处 /// <reference path="./jlt-sdk.d.ts" />，即可获得 jltSdk.* 的完整提示（声明文件里已带 declare global）。

安装（npm）

bash

pnpm add @ai-im/org-app-sdk

包尚未发布到公共 registry 时，用上面的 tgz 离线安装，或从下载区取用。

快速上手

import { isInJltClient, ready, parseLaunchParams, requestAuthCode } from "@ai-im/org-app-sdk";

// ① 首次打开：从 URL 取免登参数，交给自己的后端换身份
const launch = parseLaunchParams();
if (launch) {
  await fetch("/api/login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ auth_code: launch.authCode }),
  });
}

// ② 客户端内：拿到上下文（含当前用户）
if (isInJltClient()) {
  const ctx = await ready();
  console.log(`你好，${ctx.user.nickname}（组织 ${ctx.org_id}，${ctx.platform}）`);
}

// ③ 会话续期：重新取一枚一次性免登码
const { auth_code } = await requestAuthCode();

API

类型

interface JltContext {
  app_id: string;
  org_id: string;
  user: { user_id: string; nickname: string; avatar_url: string };
  locale: string;              // "zh-CN" | "zh-TW" | "en" | "ja"…
  platform: string;            // "desktop" | "mobile"
}

interface JltPickerUser {
  user_id: string;
  nickname: string;
  avatar_url: string;
  title?: string;
}

函数

函数	返回	说明
`isInJltClient()`	`boolean`	是否在机灵兔客户端的组织应用窗口里（降级判断）
`ready()`	`Promise<JltContext>`	容器就绪；不在客户端里立即 reject
`getContext()`	`Promise<JltContext>`	同 `ready()`，命名对齐原始 JSAPI
`parseLaunchParams(search?)`	`JltLaunchParams \| null`	解析 URL 上的 `jlt_auth_code`/`jlt_org_id`/`jlt_app_id`
`requestAuthCode()`	`Promise<{ auth_code, expires_in }>`	重新签发一次性免登码（300s）
`selectUsers(opts?)`	`Promise<{ users: JltPickerUser[] }>`	系统选人组件（免 scope）；取消返回空数组
`openChat(userId)`	`Promise<void>`	跳到与该成员的单聊
`showAlert(opts)`	`Promise<void>`	系统样式警告框
`showConfirm(opts)`	`Promise<{ ok: boolean }>`	系统样式确认框
`showToast(opts)`	`Promise<void>`	轻提示（info/success/error）
`localFetch(opts)`	`Promise<JltLocalFetchResult>`	从用户电脑抓取网页正文（桌面端，需 `local` 能力 + 每次用户确认）
`browserExtract(opts)`	`Promise<JltLocalFetchResult>`	无头浏览器提取 JS 渲染页面（桌面端，隔离实例不带登录态）
`mountChat(el, opts)`	`ChatHandle`	AI 对话组件：一行挂载，流式渲染/停止/重试（见 AI 对话界面）
`createChatStore(opts)`	`ChatStore`	IndexedDB 会话存储（配 mountChat 持久化，配额远大于 localStorage；见存哪里）
`setTitle(title)`	`Promise<void>`	设置应用窗口标题
`close()`	`Promise<void>`	关闭应用窗口

各方法的参数细节与行为语义见 JSAPI 参考——SDK 与之一一对应。

`NotInJltClientError`

在普通浏览器里调用任何桥接函数会抛出。一般先用 isInJltClient() 分流，不必捕获。

与 window.jlt 的关系

SDK 只是把裸的 window.jlt 包成具名导出：项目里混用两者没有副作用（同一份全局对象），但建议统一走 SDK 拿类型提示。

版本历史

版本	日期	适配协议（jlt.js）	说明
1.4.1	2026-08-26	≥ 1.3	安全加固：markdown 代码块占位符改用 NUL 哨兵（修复正文字面量碰撞导致的内容错位/重复），并加越界保护
1.4.0	2026-08-26	≥ 1.3	新增 IndexedDB 会话存储 `createChatStore`（多会话 key、预算裁剪、异步写入、不可用环境降级）
1.3.1	2026-08-26	≥ 1.3	持久化防炸：存档载荷尺寸上限（`persistMaxChars`，超限裁最旧）、内存历史上限（`historyLimit`）、存储异常吞掉不打断对话
1.3.0	2026-08-26	≥ 1.3	`mountChat` 会话持久化：`initialHistory` 恢复 + `onHistoryChange` 存档
1.2.0	2026-08-26	≥ 1.3	新增 AI 对话组件 `mountChat`（流式渲染/停止/重试/markdown，见 AI 对话界面）
1.1.0	2026-08-25	≥ 1.3	新增本地能力：`localFetch` / `browserExtract`（桌面端，需授权 + 用户确认）
1.0.0	2026-08-25	≥ 1.2.1	首个版本化发布：基础 JSAPI + 交互组件（选人/单聊/对话框/轻提示）+ 启动参数解析，双端（desktop/mobile）

版本策略

语义化版本：破坏性 API 变动升主版本，新增能力升次版本，修复升补丁版本。
SDK 版本独立于协议版本（jlt.js 由 ai-service 下发，页面永远加载最新），但每个 SDK 版本标注其支持的最低协议版本——协议向下兼容期内，旧 SDK 配新协议可正常工作；协议出现破坏性变更时会在更新日志显著标注并给出迁移期。
发布纪律：sdk/release.sh 把构建产物上传到腾讯云 COS （cos://.../open-platform/sdk/<version>/，跟桌面端安装包同一个公开桶， IIFE/压缩版/d.ts/npm 离线包/sha256），不再提交进本仓库；版本目录只进不退；发布到公共 npm registry 的决策见 open-platform/PLAN.md §5（待定）。
升级建议：锁定具体版本号引入（https://cos-pub.smabbit.com/open-platform/sdk/1.0.0/jlt-sdk.min.js），不要引用 "latest" 之类的浮动路径——协议与 SDK 的兼容性以版本号为契约。

TypeScript SDK（@ai-im/org-app-sdk） ​

下载 ​

安装（npm） ​

快速上手 ​

API ​

类型 ​

函数 ​

NotInJltClientError ​

与 window.jlt 的关系 ​

版本历史 ​

版本策略 ​