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 参考与完整示例。

下载

当前版本 2.3.1（2026-09-07，适配 JSAPI 协议 jlt.js ≥ 1.8.0；JltContext 新增 org_name 字段见更新日志）。下面每个链接都是腾讯云 COS 上的真实文件，直接点击即可下载，不需要先装 npm 包。

文件	用途
`jlt-sdk.min.js`	浏览器直接引入（IIFE，全局 `jltSdk`，含对话组件与存储助手）
`jlt-sdk.js`	同上，未压缩版（调试可读）
`jlt-sdk.d.ts`	TypeScript 类型声明（配
script 标签使用）
`ai-im-org-app-sdk-2.3.1.tgz`	npm 离线安装包：`npm i ./ai-im-org-app-sdk-2.3.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/2.3.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;
  org_name: string;             // 当前组织名称（展示用，鉴权/分区仍以 org_id 为准）
  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?, hash?)`	`JltLaunchParams \| null`	解析 URL 上的 `jlt_auth_code`/`jlt_org_id`/`jlt_app_id`（fragment 优先，query 兜底）
`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 渲染页面（桌面端，隔离实例不带登录态）
`runAgent(opts)`	`Promise<JltAgentResult>`	完整 AI 能力：交给客户端内置 Agent（技能/系统工具/本地数据库；桌面端，需 `ai`+`local` 能力 + 每轮确认，事件流见 JSAPI · agent）
`stopAgent()`	`Promise<{ stopped }>`	停止当前运行中的 agent 轮次
`startChat(opts)`	`Promise<void>`	把任务改发到主窗口新开一个对话（需要真实登录态浏览器时用，`jlt.agent` 不开放 `browser_*`；每次确认完整消息文本，无返回值/事件回调，仅桌面端）
`browserOpen(opts)`	`Promise<JltBrowserOpenResult \| JltNeedConsent>`	开隔离浏览器会话（多步爬取；桌面端，需 `local` 能力 + 目标确认；详见 JSAPI · 隔离浏览器会话）
`browserAct(opts)`	`Promise<{ok,detail?,url?,consented?} \| JltNeedConsent>`	会话内受控动作 click/type/fill/press/wait/back
`browserRead(opts)`	`Promise<JltBrowserReadResult \| JltNeedConsent>`	读正文（可按 CSS 选择器）
`browserSnapshot(opts)`	`Promise<JltBrowserTextResult \| JltNeedConsent>`	可访问性快照（ref 作为动作 target）
`browserScreenshot(opts)`	`Promise<{data_url,length} \| JltNeedConsent>`	截图 → base64 PNG（≤3MB）
`browserClose(opts)`	`Promise<void>`	关会话（幂等；杀隔离实例 + 清临时目录）
`mountChat(el, opts)`	`ChatHandle`	AI 对话组件：一行挂载，三通道（客户端 Agent/后端中继/本地预览）、agent 过程卡片、markdown 渲染/停止/重试/重新生成（见 AI 对话界面）
`createChatStore(opts)`	`ChatStore`	IndexedDB 会话存储（配 mountChat 持久化，配额远大于 localStorage；多会话 `keys()/remove()/clearAll()`、`flush()` 落盘；见存哪里）
`isNeedConsent(r)`	`r is JltNeedConsent`	类型守卫：browser* 读类操作是否在等用户确认新 origin（确认后原样重发即得内容）
`SDK_VERSION`	`string`	当前 SDK 版本号（与 package.json 一致）
`setTitle(title)`	`Promise<void>`	设置应用窗口标题
`close()`	`Promise<void>`	关闭应用窗口

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

`NotInJltClientError`

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

与 window.jlt 的关系

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

版本历史

版本	日期	适配协议（jlt.js）	说明
2.3.1	2026-09-07	≥ 1.8.0	`JltContext` 新增 `org_name` 字段（展示用，同一应用可能被多个组织安装，分区/鉴权仍以 `org_id` 为准），配合桌面端窗口按 `(org_id, app_id)` 隔离的修复。纯类型新增，非破坏性变更。详见更新日志
2.3.0	2026-08-28	≥ 1.8.0	新增 `startChat`：`jlt.agent` 为安全故意剔除了 `browser_` 工具，需要真实登录态浏览器的任务（如登录某网站抓数据）无法通过 `jlt.agent` 完成，改用 `startChat` 在用户主窗口新开一个对话执行（含真实登录态 `browser_`），仅需 `ai` 能力、无返回值/事件回调。仅桌面端。详见更新日志
2.2.0	2026-08-28	≥ 1.7.0	无边框窗口控制：类型化封装 `minimize`/`toggleMaximize`/`isMaximized`/`toggleFullscreen`/`isFullscreen`/`startDragging`/`reload`/`reloadForce`/`setToolbarVisible`/`openGrants`（均不需要 scope；仅桌面端）。应用可隐藏壳自带工具栏后完全自绘顶部栏。详见更新日志
2.1.1	2026-08-27	≥ 1.6.1	mountChat 大改版 + 本机文件访问 + 安全加固（一次性发布，此前 2.0.0/2.1.0 从未上传 COS）：三通道（agent/中继/预览 + 降级闩锁）、agent 过程卡片、markdown v2（表格/列表/代码块复制）、主题 CSS 变量、i18n、头像/时间戳/复制/重新生成、结构化 `onError(ChatError)`（唯一破坏性变更）、store 多会话 API、`isNeedConsent`/`SDK_VERSION`；新增 `chooseFile`/`saveFileAs`/`share`/`openGroupChat` 类型化封装；`files[].url` 白名单、非流式响应兼容标准 OpenAI 形状、agent 桥异常 busy 兜底、停止通道保留已生成内容、恢复历史保留本机文件 `id`。vitest 98 用例。详见 AI 对话界面与更新日志
1.6.0	2026-08-26	≥ 1.4.1	新增完整 AI 能力 `runAgent`/`stopAgent`（需 `ai`+`local` 能力 + 每轮用户确认）与隔离浏览器会话 `browserOpen/Act/Read/Snapshot/Screenshot/Close`（多步爬取；`need_consent` 联合类型）
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 的兼容性以版本号为契约。
从 1.x 升级到 2.0：唯一破坏性变更是 mountChat 的 onError 回调参数从 string 改为结构化 ChatError（读 error.message 即等价迁移，另有 kind/status/channel 可分支处理）；其余全部向后兼容（旧选项、旧存档、 .jltc- 类名覆盖方式都保留）。

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

下载 ​

安装（npm） ​

快速上手 ​

API ​

类型 ​

函数 ​

NotInJltClientError ​

与 window.jlt 的关系 ​

版本历史 ​

版本策略 ​