千问办公企业旗舰版开发者文档:调用流程。
APP 完整调用流程
全流程图
从接入到任务结果,按下图组织调用。文件、技能和语音按需准备;立即执行与计划执行是两个入口,最终都通过会话状态、事件和产物确认结果。图中的模块名称对应左侧目录,具体字段与错误码以单接口文档为准。

1. 完成接入并确认用户与额度
认证方式见APP开发者文档 → 认证接入。
通过 GET /api/openapi/app/v1/quota 展示本人额度,通过 GET /api/openapi/app/v1/sessions/session-modes 查询可用档位。展示不替代执行时的权限与余额校验;不要写死模型 ID。
2. 按需准备资源和输入
| 功能 | 调用顺序 | 交给后续步骤的结果 |
|---|---|---|
| 技能与专家套件 | 查询目录和详情 → 查询安装、偏好状态 → 按需安装并启用;卸载和停用使用各自接口 | 保存资源标识,消费服务端可用状态;安装登记不等于本轮已加载 |
| 市场连接器 | 查询详情与 connection → 按需安装 → 发起 connect-session → 用户完成授权 → complete → 再查 connection → 按需启用 | 授权状态与启用状态分别判断;可取消授权尝试,断开授权会停用连接器 |
| 内置连接器 | 查询列表、详情 → 添加 → 按类型配置或 OAuth 授权 → 查询状态 | 当前 can_use 为 false;配置或授权成功不能当作沙箱已可执行 |
| 已有文件 | 浏览目录或搜索 → GET / HEAD 文件确认 → 按需复制、重命名或建立目录 | file_id 用于稳定定位;Session 附件按契约传 path,计划附件按其字段传 oss_id,不能直接互换 |
| 新文件 | 查询 drive/quota → 申请 direct-uploads → 向 OSS PUT 文件或分片 → complete 登记;放弃时取消未完成上传 | 完成响应中的 file;只上传 OSS 字节尚不能作为已登记附件使用 |
| 语音输入 | 建立 voice-input/stream WebSocket → 上传 PCM → finish → 收齐 final 和 finished → 调用润色 → 用户确认文本 | 输入框草稿;不创建会话,不自动发送,失败时不采用未完成转写 |
3. 选择立即执行或计划执行
| 入口 | 调用顺序 | 关键语义 |
|---|---|---|
| 新会话立即执行 | POST /api/openapi/app/v1/sessions,提交 initial_prompt | 首条指令随创建开始执行,不再重复发送;保存 session_id,成功响应不代表任务完成 |
| 继续已有会话 | 查询本人会话 → POST /api/openapi/app/v1/sessions/{session_id}/prompt | 空闲时执行,忙碌时可能排队;通过事件和队列确认 |
| 计划执行 | POST /api/openapi/app/v1/scheduler/tasks → 查询任务及 next_fire_at → 到期由服务端触发 → 查询 executions 和关联 sessions | 用户无需在触发时保持页面在线;从执行记录找到实际会话,再进入事件与结果流程 |
4. 跟随执行、处理交互和恢复连接
以 /api/openapi/app/v1/sessions 为共同前缀:
| 场景 | 接口或通道 | 客户端处理 |
|---|---|---|
| 实时进度 | GET /{session_id}/events/stream(SSE) | 持续保存 SSE id;连接结束不等于任务结束 |
| 等待用户回答 | POST /{session_id}/question-response | 按 pending_action 和接口字段回应,再跟随事件 |
| 追加指令 | POST /{session_id}/prompt | 只发送一次业务操作,保存返回标识,确认执行或入队 |
| 管理排队指令 | 查询 prompt-queue,编辑或删除队列项 | 只管理尚未执行的指令;删除队列项不等于取消当前执行 |
| 取消当前执行 | POST /{session_id}/cancel | 等待状态或事件确认取消结果,不将请求发出视为已停止 |
| 浏览器刷新或断线 | 查询会话 → GET events 补历史 → 带 cursor 或 Last-Event-ID 恢复 SSE | 按事件标识去重;不重复创建会话,不把断线标成 Agent 失败 |
| 使用会话 SDK | chat-ws 的 join / replay / live 与控制消息,notify-ws 的列表通知 | 与 HTTP + SSE 按客户端方案选择,同一业务操作不要双通道重复发送 |
5. 读取结果与整理会话
查询会话状态、Turn 列表和单个 Turn,结合事件判断完成、失败或等待交互,再读取 output。产物包含沙箱 ID 时,可查询 sandboxes/{sandbox_id}/info 获取当前状态与最新桌面地址;不长期缓存旧地址。
| 功能 | 调用方式 | 边界 |
|---|---|---|
| 浏览历史 | 会话列表、pinned、recent、children;读取 events、turns 和 output | 各列表按自己的分页契约读取,不混用 cursor 与 offset |
| 整理会话 | 修改名称、置顶/取消置顶、删除会话 | 所有操作校验当前用户归属 |
| 整理计划结果 | 查询任务关联会话、session-groups 及组内会话;按需删除分组 | 清理会话分组不会暂停或删除计划,也不删除执行流水;停止未来触发需单独暂停或删除计划 |
| 文件后续管理 | 文件详情、下载、复制、重命名、删除、目录和搜索 | 只有已登记且有权访问的文件才能通过 drive 操作;不把任意沙箱产物直接当成网盘文件 |
6. 积分与问题反馈
- 积分明细调用
GET /api/openapi/app/v1/billings?source=all。当前页面对返回集合进行来源、正负金额筛选和前端分页;接口不支持 cursor。金额是精确十进制字符串,不能按 quota 的 minor 单位解释。余额与流水是不同查询,不将流水求和作为当前余额。 - 问题反馈使用
/api/openapi/app/v1/feedback员工浏览器入口:上传截图 → 可选采集会话日志 → 提交反馈 → 查询本人反馈历史。诊断包可选,采集失败不阻断正文和截图提交。排障关联信息不应包含凭据及敏感正文。