Skip to main content

前端集成快速开始

千问办公企业旗舰版开发者文档:前端集成快速开始。

认证方式见APP开发者文档 → 认证接入。 本文串起客户后台、浏览器 HTTP、SSE 和三个 WS。完成后,客户后台只负责验证用户及取得用户凭据,业务流量由浏览器直接访问 QwenWork,不需要后台转发长连接。示例只查询现有会话,不创建任务或发送聊天指令。

1. 准备客户后台与客户端模块

  1. 按“认证接入”配置应用权限和用户范围;测试用户须已激活、具备网页访问资格,并拥有至少一个会话。
  2. 在客户站点实现“认证接入”约定的 POST /api/app-token:验证自己的登录身份,从可信绑定读取 QID,再向 QwenWork 申请凭据。这个端点属于客户后台,不是 APP 业务接口;不要把后台密钥或任意用户选择权交给页面。
  3. 将“认证接入”中凭据读取、统一请求封装、WS 创建三个 JavaScript 代码块依次保存为客户站点的 app-client.js,设置其中的环境地址。它已包含凭据读取实现、内存缓存、并发合并和导出的三个函数。
  4. 页面与 /api/app-token 同源部署;不要直接双击 HTML 以 file 协议打开。HTTPS 页面连接 HTTPS/WSS 环境;如站点配置 CSP,connect-src 须允许目标 HTTPS 与 WSS Origin。
本地联调也应从独立 HTTP 域名打开页面,保留浏览器正常安全检查。允许跨域不等于允许匿名访问,真实请求仍须通过用户与资源权限校验。

2. 建立最小页面并读取会话

将下面的 HTML 保存为 index.html,同目录保存 app-client.js 和下述 demo.js。开发期间使用客户自己的网页服务打开该页面。
<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<title>APP 前端接入示例</title>
<button id="load">读取会话</button>
<select id="sessions"></select>
<button id="stream">订阅 SSE / 重连</button>
<button id="chat">连接聊天 WS</button>
<button id="notify">连接通知 WS</button>
<input id="audio" type="file" accept=".pcm">
<button id="voice">转写 PCM 语音</button>
<button id="stop">停止连接</button>
<pre id="result"></pre>
<script type="module" src="./demo.js"></script>
</html>
以下三个 JavaScript 代码块依次放入 demo.js。错误显示到页面,示例不自动重放请求。
import { appRequest, createAppWebSocket, invalidateCredential } from './app-client.js';

const output = document.querySelector('#result');
const sessions = document.querySelector('#sessions');
const positions = new Map(); // 每个会话独立保存已处理的事件位置,保持字符串精度。
const sockets = new Set();
let streamController;
const show = message => { output.textContent = String(message); };
const selectedSession = () => {
  if (!sessions.value) throw new Error('请先读取并选择会话');
  return sessions.value;
};
const action = fn => async () => {
  try { await fn(); }
  catch (error) { if (error.name !== 'AbortError') show(error.message); }
};
async function requireOK(response) {
  if (response.status === 401) invalidateCredential();
  if (!response.ok) throw new Error('请求失败:' + response.status);
  return response;
}

document.querySelector('#load').onclick = action(async () => {
  const response = await requireOK(await appRequest('/api/openapi/app/v1/sessions?limit=20'));
  const body = await response.json();
  sessions.replaceChildren();
  for (const item of body.items) {
    const option = document.createElement('option');
    option.value = item.session_id;
    option.textContent = item.session_id;
    sessions.append(option);
  }
  show(body.items.length ? '请选择会话,然后连接' : '当前用户没有会话,请先在 APP 中创建');
});

3. 使用 fetch 订阅和恢复 SSE

网络块不等于 SSE 帧:下面的解析器处理 UTF-8 分块、跨块换行、注释和多行 data,以空行结束一帧。断线后点击“订阅 SSE / 重连”,沿用该会话已成功处理的消息边界 id;首次演示从 0 补历史。正式应用可增加有上限的退避重连,但遇到鉴权失败、不可恢复错误或会话终止时应停止。
async function* readSSE(body) {
  const reader = body.getReader();
  const decoder = new TextDecoder();

  let buffer = '', event = '', id, data = [];

  try {
    while (true) {
      const chunk = await reader.read();
      buffer += decoder.decode(chunk.value, { stream: !chunk.done });
      while (true) {
        const match = /[\r\n]/.exec(buffer);
        if (!match) break;
        const index = match.index;
        if (buffer[index] === '\r' && index === buffer.length - 1 && !chunk.done) break;
        const line = buffer.slice(0, index);
        const width = buffer[index] === '\r' && buffer[index + 1] === '\n' ? 2 : 1;
        buffer = buffer.slice(index + width);
        if (line === '') {
          if (data.length) yield { event: event || 'message', id, data: data.join('\n') };

          event = ''; id = undefined ; data = [];

          continue;
        }
        if (line.startsWith(':')) continue;
        const colon = line.indexOf(':');
        const field = colon < 0 ? line : line.slice(0, colon);
        const value = colon < 0 ? '' : line.slice(colon + 1).replace(/^ /, '');
        if (field === 'event') event = value;
        if (field === 'id' && !value.includes('\0')) id = value;
        if (field === 'data') data.push(value);
      }
      if (chunk.done) break; // 未以空行结束的残帧不确认、不推进游标。
    }
  } finally {
    try { await reader.cancel(); } finally { reader.releaseLock(); }
  }
}

document.querySelector('#stream').onclick = action(async () => {
  const sessionId = selectedSession();
  streamController?.abort();
  const controller = new AbortController();
  streamController = controller;
  const lastId = positions.get(sessionId);
  const headers = { Accept: 'text/event-stream' };
  if (lastId !== undefined) headers['Last-Event-ID'] = lastId;
  const path = '/api/openapi/app/v1/sessions/' + encodeURIComponent(sessionId) +
    '/events/stream' + (lastId === undefined ? '?cursor=0' : '');
  const response = await requireOK(await appRequest(path, { headers, signal: controller.signal }));
  if (!response.headers.get('Content-Type')?.includes('text/event-stream') || !response.body) {
    throw new Error('响应不是 SSE 事件流');
  }
  for await (const frame of readSSE(response.body)) {
    const message = JSON.parse(frame.data);
    show(frame.event + '\n' + JSON.stringify(message, null, 2));
    if (frame.event === 'session_event') {
      // 此处完成业务处理后才保存;正式业务按稳定事件标识去重。
      if (frame.id !== undefined && /^\d+$/.test(frame.id)) positions.set(sessionId, frame.id);
    }
    if (frame.event === 'error') throw new Error('订阅错误,请按事件接口说明处理后重连');
    if (frame.event === 'done' || frame.event === 'session_terminated') break;
  }
});
这里只把显示消息作为业务处理。正式应用应处理状态刷新、内容撤回与交互事件;回合结束不代表会话终止。不要把状态帧、HTTP 分页游标或错误里的 resume_from 写成已处理位置。cursor 与 Last-Event-ID 同传必须一致,否则 422;示例每次只传一种。fetch 不提供原生 EventSource 的自动重连行为。

4. 连接聊天、通知和语音 WS

HTTP + SSE 与聊天 WS 可按业务需求选择,不要通过两个通道重复发送同一条业务指令。以下示例聊天只执行 join,通知只执行 ping;语音使用用户选择的 16 kHz、单声道 PCM16LE 原始文件,不支持直接把 WAV、MP3 或 MediaRecorder 默认编码当作 PCM 发送。
async function connect(kind) {
  const routes = { chat: 'chat-ws', notify: 'notify-ws', voice: 'voice-input/stream' };
  const sessionId = kind === 'chat' ? selectedSession() : undefined;
  const file = document.querySelector('#audio').files[0];
  if (kind === 'voice' && !file) throw new Error('请选择 16 kHz 单声道 PCM16LE 文件');
  const audio = kind === 'voice' ? new Uint8Array(await file.arrayBuffer()) : undefined;
  const ws = await createAppWebSocket('/api/openapi/app/v1/sessions/' + routes[kind]);
  sockets.add(ws);
  ws.onerror = () => show(kind + ' 连接失败,请检查凭据、网络和浏览器控制台');
  ws.onclose = event => { sockets.delete(ws); show(kind + ' 已关闭,关闭码 ' + event.code); };
  ws.onmessage = event => {
    try {
      const message = JSON.parse(event.data);
      show(JSON.stringify(message, null, 2));
      if (kind === 'voice' && message.type === 'finished') ws.close(1000, 'complete');
    } catch { show('收到无法解析的 WS 消息'); }
  };
  ws.onopen = async () => {
    if (ws.protocol !== 'qwenwork.app.v1') return ws.close(1000, 'unexpected protocol');
    if (kind === 'chat') {
      ws.send(JSON.stringify({ type: 'control', payload: {
        jsonrpc: '2.0', method: 'join', id: 1, params: { sessionId },
      } }));
    } else if (kind === 'notify') {
      ws.send(JSON.stringify({ jsonrpc: '2.0', method: 'ping' }));
    } else {
      for (let offset = 0; offset < audio.length; offset += 3200) {
        if (ws.readyState !== WebSocket.OPEN) return;
        ws.send(audio.slice(offset, offset + 3200));
        await new Promise(resolve => setTimeout(resolve, 100));
      }
      if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: 'finish' }));
    }
  };
}
for (const kind of ['chat', 'notify', 'voice']) {
  document.querySelector('#' + kind).onclick = action(() => connect(kind));
}
function stopConnections() {
  streamController?.abort();
  for (const ws of sockets) ws.close(1000, 'client stop');
  sockets.clear();
}
document.querySelector('#stop').onclick = stopConnections;
window.addEventListener('pagehide', stopConnections);
聊天收到 join_ack、通知收到 init/pong、语音收到最终文本及 finished,才说明业务交互成功。示例仅演示一次连接;长期运行需按对应 WS 接口实现心跳、重放和到期重建。原生 WebSocket 连接失败时不能像 fetch 一样读取握手 HTTP 状态,不要仅凭 onerror 就判定凭据过期,也不要无限重取凭据。

5. 验收与排查

现象检查位置
客户后台申请失败当前登录身份、可信 QID 映射、应用用户范围和用户资格
HTTP/SSE 浏览器报跨域错误OPTIONS 是否成功、实际响应是否有匹配的允许来源与请求头;不要关闭浏览器安全策略
跨域响应来源是具体域名正常,允许任意来源的网关也可能返回当前 Origin;不要求响应字面值一定为星号
HTTP 返回 401 / 403分别检查凭据有效性、用户及资源权限;不要把可读取的拒绝响应当成 CORS 失败
SSE 返回 422cursor 与 Last-Event-ID 是否冲突,是否误用其他游标
SSE 已连接但没有新消息可能暂时没有业务事件;检查补历史位置,不重复发送任务
WS 仅建立连接继续验证 join_ack、init/pong 或最终转写等实际业务结果
浏览器退出或切换账号时停止请求和连接并重新加载页面;新账号重新读取后台凭据。对象存储直传使用签名 URL,其跨域策略独立维护,不能套用 APP 请求封装。