企业管理员可以把业务网页挂到千问办公-旗舰版用户客户端(桌面端)的侧边栏,也可以接入企业私有市场。网页开发者可以通过 JavaScript 接口(JSAPI)读取登录状态、打开客户端页面,并使用当前客户端开放的技能、连接器和专家套件能力。
::: ⚠️ 注意 只为企业信任的网页开放桥接。按业务需要读取用户信息、设备信息和凭据,避免将令牌写入日志、URL 或浏览器本地存储。 :::
1 · 接入与验证
选择接入方式
接入方式 | 用户从哪里打开 | 页面如何调用 JSAPI |
侧边栏内嵌应用(WebView) | 侧边栏的自定义链接,适合企业知识库、工单等业务网页 | 通过 |
企业私有市场(iframe) | 技能、连接器或专家套件的企业市场,适合展示企业资源目录 | 通过 |
标准方法使用相同的名称和参数。先调用 app.getCapabilities 确认当前承载方式下的方法和事件,再按业务需要处理权限限制。shell.exec 和兼容方法只用于 WebView。
配置侧边栏内嵌应用
在千问办公-旗舰版管理后台进入【个性化配置 → 个性化策略组】,编辑目标策略组。
在「导航与菜单 → 导航」点击【新增自定义链接】,填写入口名称和网页地址,选择入口图标。
将打开方式设为「在千问办公内打开」。在【高级配置】可按需设定路由标识、环境变量或上传网页插件包。
点击【保存链接】,再点击策略组页面顶部的【保存】。
选择「在千问办公内打开」,再将链接保存到策略组。
配置企业私有市场
在管理后台进入【AI 资产管理 → 技能】,打开企业市场配置并选择「私有市场」。连接器和专家套件分别在对应页面配置。
确认企业市场名称,填写市场地址及允许来源。允许来源应覆盖 iframe 实际加载页面的
origin,包括协议、域名和非默认端口。点击【保存配置】。如需将该市场排在桌面端市场页签首位,可在保存前开启「优先展示」。
将私有市场的网页地址和实际加载来源填写到对应字段。
验证接入结果
使用测试成员在桌面端打开已配置的侧边栏入口或企业市场。WebView 页面应能读取
window.qwBridge,iframe 页面应能收到父窗口响应。先调用
app.ping。收到{ pong: true }后,再调用app.getCapabilities读取methods、events和bridgeVersion。选一个实际使用的只读方法,例如
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 中调用
核对两个来源。管理后台的「允许来源」填市场页面的来源。下方适配器的
expectedHostOrigin填父窗口的可信来源。发送
bridge-request,并按id匹配bridge-response。成功时读取data,失败时读取error文本。用
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表示桥协议版本。已就绪的页面可直接查询能力。
订阅与取消订阅
场景 | 可订阅的事件 |
刷新资源列表 |
|
更新连接器状态或工具列表 |
|
显示连接器 CLI 安装进度 |
|
跟随客户端主题与语言 |
|
跟踪异步技能任务 | 对应的 |
先订阅事件,再发起会触发事件的操作。页面卸载或停止接收通知时,调用订阅返回的取消函数。
const unsubscribe = bridge.on("skills:changed", () => {
// 刷新已安装技能列表
})
// 页面卸载时调用 unsubscribe()
3 · 接口参考
应用信息与登录
方法 | 返回结果 |
| 应用 ID |
|
|
| WebView 的 |
|
|
|
|
| 企业后端调用所需的 |
| 发起退出,返回 |
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")
宿主环境与设备
方法 | 用途与返回值 |
| 判断是否在千问办公中运行。可返回 |
| 查询 |
| 返回用户主目录 |
| 查询绝对路径是否为已有文件或目录,返回 |
| 按 |
在普通浏览器中运行网页时,可根据桥连接结果回退到网页自身功能。路径查询和注册信息需由当前客户端开放。
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" }
打开网页、控制侧栏与关闭视图
方法 | 使用方式 |
| 在系统浏览器打开 |
| 在客户端主窗口打开网页浮层。 |
| 用布尔值 |
| 关闭视图。省略 |
网页浮层 默认在主窗口居中,约占窗口的 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" })
错误 | 检查项 |
| 检查技能是否已安装,以及 |
| 检查套件是否已安装,以及使用的是目录名还是企业市场 ID。 |
| 检查指定套件中是否有对应的快捷命令。 |
打开专家套件详情
page.navigatePluginCenter 的 target 可为 market(套件广场)、installed(已安装)或 detail(详情)。该方法自桥协议 1.7.0 起可用。
选择标识 查看详情时传
pluginId或folderName。桥协议1.15.0起支持folderName,可从expertKit.list取得,适用于没有市场 ID 的内置或自定义套件。两者都传时优先尝试pluginId。选择打开方式 默认切页,返回时回到该套件所属页签。桥协议
1.13.0起可对详情传入presentation: "dialog",在当前页面上打开详情弹窗。用户可在弹窗中安装、更新或启停,并在关闭后回到原页面。兼容较早客户端 桥协议低于
1.13.0时使用切页。无法识别的presentation也回落到切页,market和installed忽略该参数。找不到套件时客户端给出提示。
pluginId 匹配顺序
企业市场条目的 ID。匹配后打开企业套件详情。
本地已安装套件,包括内置套件。依次按企业市场 ID、公开市场 ID、包名和目录名匹配。
公开市场条目。命中后打开套件详情,未安装的条目可在详情中安装。
第二、三步要求桥协议 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",
})
监听套件安装和变更
桥协议 |
|
低于 | 收到仅含 |
| 详情弹窗安装成功后,发起页面收到 |
| 桥接写操作也可返回 |
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" })
安装、上传与更新
场景 | 方法与结果 |
从可信地址安装 |
|
选取本地文件 |
|
提交上传 |
|
按名称安装或更新 |
|
从共享包安装 |
|
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 })
}
连接器
查看连接状态、市场和权限
方法 | 结果 |
| 连接器列表。条目含 |
| 按连接器返回 |
|
|
| 查询公开市场目录及企业市场连接器详情。目录还返回 |
列表中的 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" })
新增、编辑和启停连接器
调用
connector.list核对serverName和来源。内置连接器的配置和授权通过connector.open打开的宿主窗口办理。对自定义连接器调用
connector.saveConfig提交servers。已存在的同名条目仅在installSource与原渠道一致时可覆盖。修改一条已存在的自定义连接器时,也可用
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.12.0或更高的客户端中,在连接器配置的cli字段填写command、单平台或多平台安装包及校验值。executionContract、targetOrigins为可选项。注册
connector.cliInstallProgress和connector.cliInstallComplete后,调用connector.cliInstall,只传serverName。该方法自桥协议1.8.0起可用,立即返回status,还可返回alreadyRunning或error。通过完成事件更新状态,或用
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" })
查询市场并安装套件
市场 | 查询方法 | 安装方法 |
公开市场 |
| 对所选市场套件调用 |
企业市场 |
| 将所选企业市场条目传给 |
四个查询方法自桥协议
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])
}
管理套件内连接器
用
expertKit.connector.list查看套件连接器。条目可包含connectorId、name、nameI18n、status、disabled、required、hasAuthToken和setup。用
checkConflict检查冲突,收到hasConflict后,依据conflictType让用户选择处理方式,再调用resolveConflict。使用
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.5.0或更高的客户端中调用expertKit.export。传入folderName和source,其中market为市场安装,user为用户自建。用户在客户端的保存窗口中选择路径。保存成功后,ZIP 位于用户本地磁盘,已安装套件保持原状。
页面可以用返回的
savePath展示保存位置。用户取消时,处理canceled: true。ZIP 内容由用户在本地访问。
const result = await bridge.invoke("expertKit.export", { folderName: "sales-kit", source: "market" })
// { success, canceled?, savePath? }
应用存储和企业免登
方法 | 结果 |
| 保存和读取当前应用、当前账号的键值。键不存在时返回 |
| 删除单个键或清空当前应用与账号的存储。清空前请核对影响范围。 |
| 取得企业单点登录(SSO)的一次性票据,返回 |
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 并向企业管理员确认命令已列入白名单。白名单为空时拒绝执行,后台配置无法覆盖它。
参数 | 规则 |
| 纯命令名,只允许字母、数字、 |
| 可选字符串数组,最多 128 项,作为独立参数原样传给命令。参数不参与白名单匹配,也不经 shell 解释。 |
| 可选工作目录。 |
| 毫秒。默认 |
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。客户端查找命令时也会检查其管理的工具目录。宿主审计记录包含命令、所属应用、退出码和耗时。
错误 | 检查项 |
| 检查命令名、参数数组、工作目录和超时值。 |
| 检查当前安装包是否允许该命令。 |
| 检查命令是否安装并可被客户端找到。 |
| 检查命令能否启动,以及工作目录是否可用。 |
兼容方法(仅 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 的 | 自定义链接是否选择「在千问办公内打开」,是否从桌面端侧边栏进入。 |
私有市场页面打开但请求超时 | 管理后台的允许来源是否涵盖 iframe 实际地址,页面是否校验了正确的父窗口来源,响应 |
方法缺失或调用被拒绝 | 查看 |
安装、更新后列表未刷新 | 检查订阅是否先于调用注册、是否只监听一种事件信封,以及是否按 |