内嵌应用集成操作手册(jsBridge)

更新时间:
复制 MD 格式

企业管理员可以把业务网页挂到千问办公-旗舰版用户客户端(桌面端)的侧边栏,也可以接入企业私有市场。网页开发者可以通过 JavaScript 接口(JSAPI)读取登录状态、打开客户端页面,并使用当前客户端开放的技能、连接器和专家套件能力。

::: ⚠️ 注意 只为企业信任的网页开放桥接。按业务需要读取用户信息、设备信息和凭据,避免将令牌写入日志、URL 或浏览器本地存储。 :::

1 · 接入与验证

选择接入方式

接入方式

用户从哪里打开

页面如何调用 JSAPI

侧边栏内嵌应用(WebView)

侧边栏的自定义链接,适合企业知识库、工单等业务网页

通过 window.qwBridge 调用。切换到其他入口时,当前视图隐藏。

企业私有市场(iframe)

技能、连接器或专家套件的企业市场,适合展示企业资源目录

通过 postMessage 与桌面端父窗口通信。离开市场页签时,页面卸载。

标准方法使用相同的名称和参数。先调用 app.getCapabilities 确认当前承载方式下的方法和事件,再按业务需要处理权限限制。shell.exec 和兼容方法只用于 WebView。

配置侧边栏内嵌应用

  1. 在千问办公-旗舰版管理后台进入【个性化配置 → 个性化策略组】,编辑目标策略组。

  2. 在「导航与菜单 → 导航」点击【新增自定义链接】,填写入口名称和网页地址,选择入口图标。

  3. 将打开方式设为「在千问办公内打开」。在【高级配置】可按需设定路由标识、环境变量或上传网页插件包。

  4. 点击【保存链接】,再点击策略组页面顶部的【保存】。

内嵌应用集成操作手册(jsBridge)

选择「在千问办公内打开」,再将链接保存到策略组。

配置企业私有市场

  1. 在管理后台进入【AI 资产管理 → 技能】,打开企业市场配置并选择「私有市场」。连接器和专家套件分别在对应页面配置。

  2. 确认企业市场名称,填写市场地址及允许来源。允许来源应覆盖 iframe 实际加载页面的 origin,包括协议、域名和非默认端口。

  3. 点击【保存配置】。如需将该市场排在桌面端市场页签首位,可在保存前开启「优先展示」。

内嵌应用集成操作手册(jsBridge)

将私有市场的网页地址和实际加载来源填写到对应字段。

验证接入结果

  1. 使用测试成员在桌面端打开已配置的侧边栏入口或企业市场。WebView 页面应能读取 window.qwBridge,iframe 页面应能收到父窗口响应。

  2. 先调用 app.ping。收到 { pong: true } 后,再调用 app.getCapabilities 读取 methods、events 和 bridgeVersion。

  3. 选一个实际使用的只读方法,例如 skill.list,确认数据和成员权限符合预期。对于异步安装或更新,再检查进度和完成事件是否能按 requestId 对应到请求。

2 · 调用与事件

示例使用 bridge.invoke 和 bridge.on。顶层 await 请在 JavaScript 模块中使用。每个方法调用单独演示,按业务选择需要的调用。执行安装、启停、卸载或清空前,请核对目标和预期影响。

在 WebView 中调用

页面加载后从 window.qwBridge 取得桥接对象。invoke 成功时返回数据,失败时抛出错误。需要统一处理结果时,用 invokeSafe 读取 { ok, data } 或 { ok, error }。

const bridge = window.qwBridge
const result = await bridge.invokeSafe("app.ping")
if (result.ok) {
  console.log(result.data.pong)
}

在 iframe 中调用

  1. 核对两个来源。管理后台的「允许来源」填市场页面的来源。下方适配器的 expectedHostOrigin 填父窗口的可信来源。

  2. 发送 bridge-request,并按 id 匹配 bridge-response。成功时读取 data,失败时读取 error 文本。

  3. 用 bridge-event 接收事件。宿主同时发送兼容信封 skill-bridge-event,页面选择一种监听即可。

::: ⚠️ 注意 下面的示例父窗口地址需替换。如果部署使用不透明来源,只有在限制网页嵌入范围并核实父窗口身份后,才将 expectedHostOrigin 设为字符串 "null"。 :::

将以下两段依次放在同一模块中。适配器使用 crypto.randomUUID() 生成请求 ID,请在 HTTPS 等安全上下文中运行。

接收响应和事件

const parentWindow = window.parent
const expectedHostOrigin = "https://desktop.example.com"
const targetOrigin = expectedHostOrigin === "null" ? "*" : expectedHostOrigin
const pending = new Map()
const listeners = new Map()

window.addEventListener("message", (event) => {
  if (event.source !== parentWindow || event.origin !== expectedHostOrigin) return
  const msg = event.data
  if (msg?.type === "bridge-response") {
    const request = pending.get(msg.id)
    if (!request) return
    clearTimeout(request.timer)
    pending.delete(msg.id)
    if (msg.success) request.resolve(msg.data)
    else request.reject(new Error(String(msg.error)))
  } else if (msg?.type === "bridge-event") {
    for (const handler of listeners.get(msg.event) ?? []) handler(msg.data)
  }
})

发送请求和注册监听

function callBridge(method, params = {}) {
  const id = crypto.randomUUID()
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => {
      pending.delete(id)
      reject(new Error(`Timeout: ${method}`))
    }, 10000)
    pending.set(id, { resolve, reject, timer })
    try {
      parentWindow.postMessage({ type: "bridge-request", id, method, params }, targetOrigin)
    } catch (error) {
      clearTimeout(timer)
      pending.delete(id)
      reject(error)
    }
  })
}

function onBridgeEvent(event, handler) {
  if (!listeners.has(event)) listeners.set(event, new Set())
  listeners.get(event).add(handler)
  return () => listeners.get(event)?.delete(handler)
}

const bridge = { invoke: callBridge, on: onBridgeEvent }
  • 示例等待响应 10 秒。按业务耗时调整页面的等待时间,并处理宿主可能返回的超时错误。

  • iframe 响应中的 error 是文本。按 WebView 和 iframe 各自的响应格式处理错误。

  • iframe 可订阅 bridge:ready 获取就绪通知,其中的 version 表示桥协议版本。已就绪的页面可直接查询能力。

订阅与取消订阅

场景

可订阅的事件

刷新资源列表

skills:changed、connectors:changed、expertKits:changed

更新连接器状态或工具列表

connector.statusChanged、connector.toolsChanged

显示连接器 CLI 安装进度

connector.cliInstallProgress、connector.cliInstallComplete

跟随客户端主题与语言

page.themeChanged、page.languageChanged

跟踪异步技能任务

对应的 :progress、:complete 事件,通过 requestId 对应任务

先订阅事件,再发起会触发事件的操作。页面卸载或停止接收通知时,调用订阅返回的取消函数。

const unsubscribe = bridge.on("skills:changed", () => {
  // 刷新已安装技能列表
})
// 页面卸载时调用 unsubscribe()

3 · 接口参考

应用信息与登录

方法

返回结果

app.getInfo

应用 ID embeddedAppId、名称 name、路由 route 和 version。WebView 返回应用包版本,iframe 使用市场视图标识。

app.ping

{ pong: true },用于检查桥连接。

app.getEnv

WebView 的 envVars 包含管理后台为应用配置的环境变量。未配置或从私有市场 iframe 调用时,envVars 为空对象。

app.getCapabilities

bridgeVersion、methods、events 和 errorProtocol。用于判断可用方法、事件和参数。

auth.getLoginState

isAuthenticated 和 user。用户未登录时 user 为 null。

auth.getToken

企业后端调用所需的 token、tokenType、expiresAt 和 expiresIn。

auth.logout

发起退出,返回 { ok: true } 后由客户端执行登出。

await bridge.invoke("app.getInfo")
// { embeddedAppId: "enterprise-kb", name: "企业知识库", route, version }
await bridge.invoke("app.ping")
// { pong: true }
await bridge.invoke("app.getEnv")
// { envVars: { TENANT_ID: "example-tenant" } }
const { bridgeVersion, methods, events } = await bridge.invoke("app.getCapabilities")
  • 识别成员user 可包含 id、name、username、email、avatarUrl、tier、isBiz、orgId、orgName 和 teamId。使用 user.id 关联企业账号前,请核对企业身份映射。

  • 调用企业后端 桥协议 1.0.1 起,受支持的旗舰版会话通过 auth.getToken 返回 third_party_access_token。将它作为 Bearer 令牌放入企业后端请求的 Authorization 头。

  • 刷新令牌expiresAt、expiresIn 是重新获取宿主登录凭据的提示。企业后端令牌的独立到期时间不由这两个字段给出,请按需重新取用。

const { isAuthenticated, user } = await bridge.invoke("auth.getLoginState")
const { token, tokenType, expiresAt, expiresIn } = await bridge.invoke("auth.getToken")
// 需要主动退出时调用以下方法
await bridge.invoke("auth.logout")

宿主环境与设备

方法

用途与返回值

host.getEnvironment

判断是否在千问办公中运行。可返回 inQwenWork、product、productDisplayName、version、edition(包含 tier 和 deployment)、isPremium 和 platform。

host.getClientInfo

查询 app、runtime、os 和 device。设备信息缓存 60 秒,采集失败的设备字段可能为空。

host.getHomedir

返回用户主目录 homedir。

host.fileExists、host.directoryExists

查询绝对路径是否为已有文件或目录,返回 exists。相对路径或 ~ 会产生 INVALID_PARAMS。

agentRuntime.getRegistration

按 key 查询客户端提供的注册值。状态为 available、not-registered 或 unsupported-key。

在普通浏览器中运行网页时,可根据桥连接结果回退到网页自身功能。路径查询和注册信息需由当前客户端开放。

await bridge.invoke("host.getEnvironment")
const info = await bridge.invoke("host.getClientInfo")
// app: version, name, locale, packaged, edition, isPremium
// runtime: electron, chrome, node
// os: platform, arch, label, version, kernelRelease
// device: machineId, serialNumber, macAddress, model, deviceName,
//         loginUsername, cpuModel, cpuCores, totalMemoryMb
const { homedir } = await bridge.invoke("host.getHomedir")
await bridge.invoke("host.fileExists", { path: `${homedir}/guide.txt` })
await bridge.invoke("host.directoryExists", { path: `${homedir}/documents` })
const registration = await bridge.invoke("agentRuntime.getRegistration", { key: "agentCode" })
// { status: "available", value } 或 { status: "not-registered" } / { status: "unsupported-key" }

页面与客户端界面

读取主题和语言

await bridge.invoke("page.getTheme")    // { theme: "light" | "dark", themeVariant }
await bridge.invoke("page.getLanguage") // { language: "zh" }

打开网页、控制侧栏与关闭视图

方法

使用方式

page.openUrl

在系统浏览器打开 http 或 https 地址。

page.openInAppBrowser

在客户端主窗口打开网页浮层。zIndex 默认 900,超出 51 至 10000 时按边界值处理。

ui.setSidebarCollapsed

用布尔值 collapsed 设置当前窗口侧栏。缺少参数或传入字符串会返回 INVALID_PARAMS。

page.close

关闭视图。省略 name 时关闭调用方所在视图。

  • 网页浮层 默认在主窗口居中,约占窗口的 80%。再次调用会替换内容。用户可点击关闭按钮、遮罩或按 Esc 退出。

  • 浮层中的网页 与主窗口共用 Cookie 分区,按普通网页运行。需要调用 JSAPI 的业务应留在原 WebView 或 iframe 中。

  • 侧栏状态 同一个布尔值可重复传入。用户仍可手动调整,设置只影响当前窗口。页面无需先查询侧栏状态。

  • 使用内置网页浮层和侧栏设置前,确认桥协议达到 1.10.0,并检查对应方法是否开放。

await bridge.invoke("page.openUrl", { url: "https://example.com" })
await bridge.invoke("page.openInAppBrowser", { url: "https://example.com/guide", zIndex: 950 })
await bridge.invoke("ui.setSidebarCollapsed", { collapsed: true })
await bridge.invoke("page.close")

打开新任务和技能页面

  • 新任务page.toIndex 省略参数、传 {} 或只传空 prompt 时,打开空白任务。只传非空 prompt 时,预填文字。

  • 带上能力skillName 和 pluginName 分别使用本地技能、套件目录名,pluginId 使用企业市场套件 ID。三个字段最多传一个。

  • 使用快捷命令command 使用套件中可由用户调用的技能目录名,须随 pluginName 或 pluginId 传入。pluginId 和 command 需要桥协议 1.9.0 或更高。

  • 技能页面page.navigateSkillCenter 的 target 可为 explore(市场)、mine(已安装)或 detail(详情)。查看详情时传 skillId。

await bridge.invoke("page.toIndex")
await bridge.invoke("page.toIndex", {})
await bridge.invoke("page.toIndex", { prompt: "" })
await bridge.invoke("page.toIndex", { skillName: "weekly-report", prompt: "生成本周周报" })
await bridge.invoke("page.toIndex", { pluginId: "plugin-123" })
await bridge.invoke("page.toIndex", {
  pluginId: "plugin-123", command: "gen-report", prompt: "本月",
})
await bridge.invoke("page.navigateSkillCenter", { target: "detail", skillId: "code-review" })

错误

检查项

SKILL_NOT_FOUND

检查技能是否已安装,以及 skillName 是否为技能目录名。

EXPERT_KIT_NOT_FOUND

检查套件是否已安装,以及使用的是目录名还是企业市场 ID。

EXPERT_KIT_COMMAND_NOT_FOUND

检查指定套件中是否有对应的快捷命令。

打开专家套件详情

page.navigatePluginCenter 的 target 可为 market(套件广场)、installed(已安装)或 detail(详情)。该方法自桥协议 1.7.0 起可用。

  1. 选择标识 查看详情时传 pluginId 或 folderName。桥协议 1.15.0 起支持 folderName,可从 expertKit.list 取得,适用于没有市场 ID 的内置或自定义套件。两者都传时优先尝试 pluginId。

  2. 选择打开方式 默认切页,返回时回到该套件所属页签。桥协议 1.13.0 起可对详情传入 presentation: "dialog",在当前页面上打开详情弹窗。用户可在弹窗中安装、更新或启停,并在关闭后回到原页面。

  3. 兼容较早客户端 桥协议低于 1.13.0 时使用切页。无法识别的 presentation 也回落到切页,market 和 installed 忽略该参数。找不到套件时客户端给出提示。

pluginId 匹配顺序

  1. 企业市场条目的 ID。匹配后打开企业套件详情。

  2. 本地已安装套件,包括内置套件。依次按企业市场 ID、公开市场 ID、包名和目录名匹配。

  3. 公开市场条目。命中后打开套件详情,未安装的条目可在详情中安装。

第二、三步要求桥协议 1.14.0 或更高。folderName 按目录名精确匹配,先查本地已安装套件,再查公开市场。

await bridge.invoke("page.navigatePluginCenter", { target: "detail", pluginId: "plugin-123" })
await bridge.invoke("page.navigatePluginCenter", { target: "detail", folderName: "pm-work-suite" })
await bridge.invoke("page.navigatePluginCenter", {
  target: "detail", pluginId: "plugin-123", presentation: "dialog",
})

监听套件安装和变更

桥协议

expertKits:changed 的处理方式

低于 1.20.0

收到仅含 timestamp 的通知时,重查 expertKit.list 获取变更结果。

1.20.0 至 1.21.x

详情弹窗安装成功后,发起页面收到 action: "install",并可取得 installed。其他变更按列表刷新处理。

1.22.0 起

桥接写操作也可返回 action 和 installed。action 可为 install、remove、enable、disable、update 或 connectorSetup。

installed 包含 folderName,还可包含 pluginId、pluginName 和 version。没有市场来源的套件可能省略 pluginId。收到只带 timestamp 的通知时,重新读取列表。

bridge.on("expertKits:changed", (data) => {
  if (data.action === "install" && data.installed) {
    // 用 data.installed.folderName 定位刚安装的套件
  }
  void bridge.invoke("expertKit.list").then(({ expertKits }) => {
    // 用 expertKits 更新列表
  }).catch((error) => console.error(error.message))
})

技能

查询技能和展示信息

  • skillId 和 name 使用本地目录名。桥协议 1.1.0 起,可按 extension.sourceCategory 区分 BUILT_IN、OFFICIAL、ENTERPRISE、LOCAL 和 THIRD_PARTY。sourceType 兼容既有页面,installSource 标识安装渠道。

  • skill.list、skill.detail 和 skill.market.list 可返回 displayNameI18n、descriptionI18n,桥协议 1.2.0 起提供。按 page.getLanguage 选取文本,缺少对应值时可依次回落到语言短码、zh、en 或原字段。

const { installedSkills } = await bridge.invoke("skill.list")
// 列表项可含 skillId、name、displayName、description、iconUrl、installSource、
// isUserEnable、category 和 extension,后者可含 version、installedVersion
const detail = await bridge.invoke("skill.detail", { skillId: "code-review" })
// 详情可含 source、name、displayName、description、markdown、version、installSource、iconUrl
const { examples } = await bridge.invoke("skill.examples", { folderName: "weekly-report" })

安装、上传与更新

场景

方法与结果

从可信地址安装

skill.installFromUrl 接收 ZIP 地址和可选 installSource、iconUrl。返回 success、skill_id、name 和 version 等。

选取本地文件

skill.upload 打开文件选择器。用户取消时 filePath 为空字符串。

提交上传

skill.upload.start 返回 requestId。监听 skill.upload:progress 和 skill.upload:complete。收到 requireOverwrite 后请用户确认,确认覆盖后传 force: true 重试。

按名称安装或更新

skill.aoneKitInstall、skill.update 传 name、displayName 等。按各自进度和完成事件处理结果。

从共享包安装

skill.installFromZip 接收 zipBase64 和 shareId,按异步任务处理。

await bridge.invoke("skill.installFromUrl", {
  url: "https://cdn.example.com/weekly-report.zip",
  installSource: "example-market",
  iconUrl: "https://cdn.example.com/report.png",
})
const { filePath } = await bridge.invoke("skill.upload")
if (filePath) {
  const { requestId } = await bridge.invoke("skill.upload.start", { filePath, force: false })
  // 使用 requestId 对应已订阅的进度与结果
}
await bridge.invoke("skill.aoneKitInstall", { name: "weekly-report", displayName: "周报" })
await bridge.invoke("skill.update", { name: "weekly-report", displayName: "周报" })

检查策略、更新和同名冲突

skill.accessPolicy 返回只读快照,可据此显示上传、市场和提交入口。调用方仍应处理实际操作的失败结果。

await bridge.invoke("skill.accessPolicy")
// { publicMarketVisible, personalUploadEnabled, teamSubmissionEnabled, enterpriseEligible }
await bridge.invoke("skill.checkUpdates")
// { updates: { [folderName]: { hasUpdate, remoteVersion? } } }
await bridge.invoke("skill.checkConflict", { folderName: "weekly-report" })
// { type, existingVersion? }

管理已安装技能与市场条目

  • 使用 skill.setEnabled 设置启用状态。skill.remove 用于移除技能,调用前请核对目录名。

  • skill.getPackage 返回 zipBase64、fileName 和 fileSize。skill.create 打开新对话并预填创建引导,可传入 prompt 补充需求。

  • 使用 skill.market.list 分页查找公开市场条目。确认条目后,将其 name 作为 folderName 传给 skill.market.install。

await bridge.invoke("skill.setEnabled", { skillId: "code-review", enabled: false })
await bridge.invoke("skill.remove", { skillId: "code-review" })
await bridge.invoke("skill.getPackage", { skillId: "weekly-report" })
await bridge.invoke("skill.create", { prompt: "创建把周报转成演示文稿的技能" })
const page = await bridge.invoke("skill.market.list", { keyword: "周报", page: 1, pageSize: 20 })
// 用户确认所选条目后再安装
if (page.skills[0]) {
  await bridge.invoke("skill.market.install", { folderName: page.skills[0].name })
}

连接器

查看连接状态、市场和权限

方法

结果

connector.list

连接器列表。条目含 serverName、source、transport、displayName、description,并可包含授权与能力信息。

connector.status

按连接器返回 connected、failed 或 needs-auth 等状态,以及工具或错误信息。配合 connector.statusChanged 刷新。

connector.accessPolicy

mode、restricted、blockedSources、blockedIds。可据此调整按钮,宿主仍会检查实际权限。

connector.market.list、connector.detail

查询公开市场目录及企业市场连接器详情。目录还返回 categories。

列表中的 displayName 和 description 可能是多语言对象。桥协议 1.3.0 起,市场列表和详情可额外返回 displayNameI18n、descriptionI18n。按 page.getLanguage 选择展示文本,保留普通字段作回退。

const { connectors } = await bridge.invoke("connector.list")
const { servers } = await bridge.invoke("connector.status")
await bridge.invoke("connector.accessPolicy")
bridge.on("connector.statusChanged", ({ servers }) => {
  // 按 serverName 更新连接状态
})
await bridge.invoke("connector.market.list")       // { connectors, categories }
await bridge.invoke("connector.market.install", { serverId: "example-connector" })

新增、编辑和启停连接器

  1. 调用 connector.list 核对 serverName 和来源。内置连接器的配置和授权通过 connector.open 打开的宿主窗口办理。

  2. 对自定义连接器调用 connector.saveConfig 提交 servers。已存在的同名条目仅在 installSource 与原渠道一致时可覆盖。

  3. 修改一条已存在的自定义连接器时,也可用 connector.update 提交 serverName 和 config。管理启停用 connector.setEnabled。移除时按来源核对 serverName 或 connectorId。

桥协议 1.11.0 起,connector.addCustom 与 connector.saveConfig 一样可新增或更新。同名渠道不一致时仍会拒绝。较早客户端可能返回 NAME_CONFLICT,需要先查询已存在的条目。

await bridge.invoke("connector.saveConfig", { servers: {
  "example-kb": {
    url: "https://mcp.example.com", type: "http",
    displayName: { zh: "知识库", en: "Knowledge base" },
    installSource: "example-market",
  },
} })
await bridge.invoke("connector.setEnabled", { serverName: "example-kb", enabled: true })
await bridge.invoke("connector.remove", { serverName: "example-kb" })

授权、工具与诊断

  • connector.auth 使用 action: "start" 发起授权,使用 action: "clear" 清除授权。内置连接器使用 connector.open。

  • 调用 connector.tools 获取带 name、description、enabled 的工具项,使用 connector.setToolEnabled 设置工具状态。

  • connector.diagnose 可返回 logPath 和 status,供检查连接异常。

await bridge.invoke("connector.auth", { serverName: "example-kb", action: "start" })
await bridge.invoke("connector.tools", { serverName: "example-kb" })
await bridge.invoke("connector.setToolEnabled", {
  serverName: "example-kb", toolName: "search", enabled: false,
})
await bridge.invoke("connector.open", { serverName: "example-kb", triggerAuth: true })
await bridge.invoke("connector.diagnose", { serverName: "example-kb" })

安装连接器 CLI

命令行工具(CLI)安装使用已保存的连接器配置。配置可由企业市场下发,也可通过 connector.addCustom、connector.saveConfig 或 connector.update 写入。

  1. 在桥协议 1.12.0 或更高的客户端中,在连接器配置的 cli 字段填写 command、单平台或多平台安装包及校验值。executionContract、targetOrigins 为可选项。

  2. 注册 connector.cliInstallProgress 和 connector.cliInstallComplete 后,调用 connector.cliInstall,只传 serverName。该方法自桥协议 1.8.0 起可用,立即返回 status,还可返回 alreadyRunning 或 error。

  3. 通过完成事件更新状态,或用 connector.cliStatus 查询。对曾启用过的失败项,可用 connector.cliRetry 同步重试。

await bridge.invoke("connector.addCustom", { servers: { "example-kb": {
  url: "https://mcp.example.com/sse", type: "sse", displayName: "知识库",
  installSource: "example-cdn",
  cli: {
    command: "example-kb-cli",
    artifact: "https://cdn.example.com/connector.zip",
    contentHash: "sha256:<SHA256_HEX>",
  },
} } })

将 <SHA256_HEX> 替换为安装包的 64 位十六进制 SHA-256 校验值。

bridge.on("connector.cliInstallProgress", ({ serverName, phase }) => {
  // 显示该连接器的安装阶段
})
bridge.on("connector.cliInstallComplete", ({ serverName, success, status, error }) => {
  // 按完成结果更新状态
})
await bridge.invoke("connector.cliInstall", { serverName: "example-kb" })
await bridge.invoke("connector.cliStatus")
// { servers: [{ serverName, status, command, error?, platformKey?, skillCount? }] }
// 对符合重试条件的失败项调用 connector.cliRetry
await bridge.invoke("connector.cliRetry", { serverName: "example-kb" }) // { success }

专家套件

查看和维护已安装套件

  • 用 expertKit.list 获取 folderName、名称、来源、版本、启停状态和更新信息。条目还可包含图标、分类、技能与连接器等数量及连接器声明。

  • 有市场来源时,pluginId 可为企业市场 ID,也可回落到公开市场 ID。没有市场 ID 的套件用 folderName 定位。displayNameI18n 自桥协议 1.3.0 起提供。

  • expertKit.detail 可返回说明、技能、快捷命令和连接器。expertKit.detail、expertKit.setEnabled 和 expertKit.update 自桥协议 1.4.0 起可用。

  • expertKit.remove 按来源卸载市场套件或删除自定义套件。可传 pluginId 或 folderName,同时提供时优先使用 pluginId。

const { expertKits } = await bridge.invoke("expertKit.list")
// 条目还可包含 displayName、displayNameI18n、description、descriptionI18n、
// isCustom、iconUrl、category、installedVersion、marketVersion、disabled、hasUpdate、
// skillCount、commandCount、connectorCount、mcpToolsCount、connectors
const detail = await bridge.invoke("expertKit.detail", { folderName: "sales-kit", source: "market" })
// 详情可含 readme、readmeEn、skills、commands、connectors
await bridge.invoke("expertKit.setEnabled", { folderName: "sales-kit", source: "market", enabled: false })
await bridge.invoke("expertKit.update", { folderName: "sales-kit" })
await bridge.invoke("expertKit.remove", { folderName: "sales-kit" })

查询市场并安装套件

市场

查询方法

安装方法

公开市场

expertKit.market.list、expertKit.market.categories

对所选市场套件调用 expertKit.setEnabled,传 source: "market"、enabled: true。

企业市场

expertKit.enterpriseMarket.list、expertKit.enterpriseMarket.categories

将所选企业市场条目传给 expertKit.install。

  • 四个查询方法自桥协议 1.6.0 起可用。列表返回 expertKits、totalSize、currentPage、pageSize 和 hasMore。

  • 公开条目可包含 installed、installCount、ratingAvg、ratingCount、recommended、fileSize、downloadUrl、marketPluginId 和 tags。企业条目保留 collectionId、downloadUrl、source: "enterprise",并可包含多语言名称和描述。

  • 企业市场安装支持 HTTP(S) 的 iconUrl。该字段从桥协议 1.19.0 起写入套件,缺省沿用原图标,地址无效时返回 EXPERT_KIT_INVALID_ICON_URL。公开市场安装或更新时也可沿用市场图标。

const market = await bridge.invoke("expertKit.market.list", { keyword: "销售", page: 1, pageSize: 20 })
const { categories } = await bridge.invoke("expertKit.market.categories")
const enterprise = await bridge.invoke("expertKit.enterpriseMarket.list", {
  collectionId: "enterprise-plugins", page: 1,
})
await bridge.invoke("expertKit.enterpriseMarket.categories")
// 用户确认所选企业市场套件后再安装
if (enterprise.expertKits[0]) {
  await bridge.invoke("expertKit.install", enterprise.expertKits[0])
}

管理套件内连接器

  1. 用 expertKit.connector.list 查看套件连接器。条目可包含 connectorId、name、nameI18n、status、disabled、required、hasAuthToken 和 setup。

  2. 用 checkConflict 检查冲突,收到 hasConflict 后,依据 conflictType 让用户选择处理方式,再调用 resolveConflict。

  3. 使用 setEnabled、retry 或 guidedSetup 启停、重试或填写引导配置。连接器状态变化通过 connector.statusChanged 推送。

这些方法使用 expertKit.connector.* 前缀,自桥协议 1.4.0 起可用。套件连接器的 OAuth 授权调用 connector.auth,将 serverName 设为 plugin:{folder}:{id}。

const target = { folderName: "sales-kit", connectorId: "my-mcp" }
const { connectors } = await bridge.invoke("expertKit.connector.list", { folderName: target.folderName })
await bridge.invoke("expertKit.connector.checkConflict", target)
await bridge.invoke("expertKit.connector.resolveConflict", { ...target, resolution: "plugin" })
await bridge.invoke("expertKit.connector.setEnabled", { ...target, enabled: true })
await bridge.invoke("expertKit.connector.retry", target)
await bridge.invoke("expertKit.connector.guidedSetup", { ...target, jsonContent: "{}" })

导出已安装套件

  1. 在桥协议 1.5.0 或更高的客户端中调用 expertKit.export。传入 folderName 和 source,其中 market 为市场安装,user 为用户自建。

  2. 用户在客户端的保存窗口中选择路径。保存成功后,ZIP 位于用户本地磁盘,已安装套件保持原状。

  3. 页面可以用返回的 savePath 展示保存位置。用户取消时,处理 canceled: true。ZIP 内容由用户在本地访问。

const result = await bridge.invoke("expertKit.export", { folderName: "sales-kit", source: "market" })
// { success, canceled?, savePath? }

应用存储和企业免登

方法

结果

storage.setItem、storage.getItem

保存和读取当前应用、当前账号的键值。键不存在时返回 { value: null }。

storage.removeItem、storage.clear

删除单个键或清空当前应用与账号的存储。清空前请核对影响范围。

enterprise.getTmpAuthCode

取得企业单点登录(SSO)的一次性票据,返回 code、data、expiresTime、signature 和 timestamp。每次使用前现取。data 为空时由页面引导登录。

await bridge.invoke("storage.setItem", { key: "lastSpace", value: { url: "https://space.example.com" } })
const { value } = await bridge.invoke("storage.getItem", { key: "lastSpace" })
await bridge.invoke("storage.removeItem", { key: "lastSpace" })
// 用户确认后再清空
await bridge.invoke("storage.clear")
const ticket = await bridge.invoke("enterprise.getTmpAuthCode")
// { code, data, expiresTime, signature, timestamp }

执行白名单命令(仅 WebView)

shell.exec 自桥协议 1.12.0 起可用于内嵌应用。可执行命令由企业专属客户端安装包的白名单决定。调用前检查 app.getCapabilities 并向企业管理员确认命令已列入白名单。白名单为空时拒绝执行,后台配置无法覆盖它。

参数

规则

command

纯命令名,只允许字母、数字、.、_ 和 -。按名称精确匹配白名单。

args

可选字符串数组,最多 128 项,作为独立参数原样传给命令。参数不参与白名单匹配,也不经 shell 解释。

cwd

可选工作目录。

timeoutMs

毫秒。默认 30000,最大 300000,超出上限时按最大值处理。

const result = await bridge.invoke("shell.exec", { command: "acli", args: ["--version"] })
// { exitCode, stdout, stderr }
await bridge.invoke("shell.exec", {
  command: "acli", args: ["login", "--check"], cwd: "/tmp/work", timeoutMs: 10000,
})
  • 读取 exitCode、stdout 和 stderr 判断执行结果。stdout 和 stderr 各自超过 1 MB 时截断,stderr 附有提示。

  • 命令超时时客户端终止进程,stderr 附有超时提示,无法取得退出码时返回 -1。

  • 客户端查找命令时也会检查其管理的工具目录。宿主审计记录包含命令、所属应用、退出码和耗时。

错误

检查项

INVALID_PARAMS

检查命令名、参数数组、工作目录和超时值。

COMMAND_NOT_ALLOWED

检查当前安装包是否允许该命令。

COMMAND_NOT_FOUND

检查命令是否安装并可被客户端找到。

SPAWN_FAILED

检查命令能否启动,以及工作目录是否可用。

兼容方法(仅 WebView)

已使用扁平方法的 WebView 页面可继续调用 addToChat、openExternal、ping 和 getEnv。iframe 页面通过 page.openUrl 打开外链,并使用 app.ping、app.getEnv 查询桥连接和环境变量。

  • addToChat 接收 message 和 resources。宿主将 file 下载为附件,将带 mcp 的 folder 作为远程引用交给指定工具。

  • openExternal 返回 ok。ping 返回 pong、echo 和时间戳 at。兼容 getEnv 返回 embeddedAppId、platform 和 versions。

await bridge.invoke("addToChat", {
  message: "请比较这两份材料",
  resources: [
    { name: "指南.pdf", type: "file", url: "https://kb.example.com/files/guide.pdf" },
    { name: "资料库", type: "folder", url: "https://kb.example.com/space/1",
      mcp: { server: "example-kb", tool: "search_folder", args: { spaceId: "space_1" } } },
  ],
}) // { ok, count }
await bridge.invoke("openExternal", { url: "https://example.com" })
await bridge.invoke("ping", { a: 1 })
await bridge.invoke("getEnv") // { embeddedAppId, platform, versions: { electron, chrome, node } }

4 · 排查接入问题

现象

优先检查

侧边栏没有入口

管理后台是否已保存链接和策略组,测试账号是否在策略组覆盖范围。

WebView 的 window.qwBridge 不可用

自定义链接是否选择「在千问办公内打开」,是否从桌面端侧边栏进入。

私有市场页面打开但请求超时

管理后台的允许来源是否涵盖 iframe 实际地址,页面是否校验了正确的父窗口来源,响应 id 是否与请求一致。

方法缺失或调用被拒绝

查看 app.getCapabilities 返回的方法、事件和桥协议。方法已开放时,再核对成员权限、目标资源或安装包白名单。

安装、更新后列表未刷新

检查订阅是否先于调用注册、是否只监听一种事件信封,以及是否按 requestId 或变更通知更新列表。