Skip to main content

采集会话反馈日志

千问办公企业旗舰版开发者文档:采集会话反馈日志。

认证方式见APP开发者文档 → 认证接入。
  • 模块:会话服务(session)
  • 接口:POST/api/openapi/app/v1/sessions/{session_id}/feedback-logs
  • operationId:collect-feedback-logs

用途与边界

为用户主动提交的问题反馈采集当前会话的有限运行日志,返回 JSON 中的 base64 ZIP;不是创建反馈、上传附件或下载裸 ZIP 的接口。客户端解码后通过现有问题反馈附件上传流程提交。 仅允许人类用户采集自己拥有的会话,不开放客户管理 API Key 或 Agent 凭据。会话不存在、已删除或不属于当前用户时不可采集;归属查询未找到会话返回 404。客户端不能指定 sandbox ID、目录或文件名。 优先读取已在运行的当前沙箱;沙箱缺失、读取失败或没有可用日志时,尝试读取经组织、用户和会话授权校验的最新 OSS 日志归档快照。归档结果标记为 partial,并记录快照来源与时间,不保证包含问题发生时的最新日志。采集不启动、恢复或重建沙箱,不读取客户工作区文件、原始 ACP 消息流和环境文件。它是第一方问题反馈的附件采集能力,不是用户日志或 AI 日志的通用查询、浏览或导出能力。

请求参数

参数位置类型必填说明
session_idpathstring,uuid是创建或查询当前用户会话时取得的 ID;须为非空有效 UUID。
无请求体,无查询参数。不要发送任意路径、文件清单、沙箱 ID 或凭据。

响应

HTTP 200,媒体类型 application/json,响应头 Cache-Control: no-store。
字段类型必填说明
statusstring是complete、partial 或 unavailable,描述日志采集情况,不表示反馈已提交或附件已上传。
archivestring,base64是ZIP 的 base64 编码。编码前最大 21 MiB(含 ZIP 与清单开销),对应 base64 字段最大 28 MiB;HTTP JSON 另有字段开销。先解码再作为 ZIP 文件上传,不把 base64 文本当文件内容。
$schemastring,uri否,只读契约提供的可选 JSON Schema 地址;业务不依赖此字段。

采集状态

status当前实现含义客户端行为
complete当前 agent-sdk.log 可读,且已返回文件均未截断、未使用 OSS 快照;仅描述沙箱日志,不代表服务日志覆盖将日志包作为反馈附件候选,继续现有反馈流程
partial至少读取到沙箱日志,但只有轮转文件可用、存在日志截断或使用 OSS 快照保留部分日志及清单,允许继续提交反馈
unavailable未取得可用日志,例如沙箱不可用、采集繁忙或读取失败ZIP 仍含 manifest.json,不能视为损坏包;不应阻止反馈正文提交

ZIP 与清单

本接口仅采集沙箱日志。关联会话的 Web 反馈提交由 Client Platform 独立补充服务诊断,执行可信身份与会话归属校验后按会话或服务端关联的 Trace 查询;结果另写入 service-diagnostics/manifest.json 和 JSONL 文件。授权不能确认或采集失败时记录不可用原因。该后续步骤不改变本接口的 status;服务日志结果由提交接口的 result.applicationLogsStatus 描述。 沙箱只读取固定文件 agent-sdk.log、agent-sdk.log.1,每个最多读取末尾 10 MiB。可用日志写入 ZIP 的 logs/ 目录,缺失或截断信息写入 manifest.json。按当前要求不做日志脱敏,保留采集内容;仍限制文件、会话归属、查询窗口与大小。
manifest.json 字段含义
version当前为 2
session_id所属会话 ID
captured_at服务端 UTC 采集时间
status与外层采集状态对应
reason不可用原因提示,正常时可为空;例如 sandbox_unavailable、collector_busy、sandbox_read_failed、invalid_log_response、logs_unavailable
files每项包含 name、status(complete/unavailable)、truncated;文件项 complete 表示读取成功,仍须查看 truncated
source使用归档时为 oss;实时采集时省略
archived_at归档快照时间,仅归档结果包含;不同于本次 captured_at
sandbox_id归档来源沙箱 ID,仅归档结果包含,客户端不能指定
modules当前为 agent、runner
policy采集边界说明,不作为程序分支条件
归档成功且取得可用日志时 reason 为 archived_snapshot;即使日志文件完整,整个归档结果也为 partial。当前沙箱与归档均无可用日志时返回 unavailable。后续提交反馈时是否采集到服务日志,不会回写或改变本次 Session 采集状态。 原因与清单用于诊断,客户端应容忍新增字段和值。每次调用重新采集,时间和包内容可能变化,不以重复调用保证获得同一个包。

浏览器示例

async function collectFeedbackLogs(sessionId, signal) {
  const response = await appRequest(
    `/api/openapi/app/v1/sessions/${encodeURIComponent(sessionId)}/feedback-logs`,
    {
      method: 'POST',

      cache: 'no-store',

      signal,
    },
  );
  if (!response.ok) throw new Error(`Log collection failed: ${response.status}`);
  const { status, archive } = await response.json();
  if (!['complete', 'partial', 'unavailable'].includes(status) || typeof archive !== 'string') {
    throw new Error('Invalid log collection response');
  }
  const bytes = Uint8Array.from(atob(archive), char => char.charCodeAt(0));
  return {
    status,
    file: new File([bytes], 'session-feedback.zip', { type: 'application/zip' }),
  };
}
本独立采集接口保留兼容,用于单独获取已授权会话日志。新版 Web 提交反馈时无需调用本接口:提交浏览器日志 ZIP,并在同一次请求的 extra 文本中携带 session_id,由后端直接采集沙箱及服务日志并合包。顶层 session_id、collect_sandbox_logs 或 ZIP 中的 requested 标记不能替代 extra.session_id。本调用不生成反馈记录;取消请求可通过 AbortSignal,不自动重试认证或权限错误。

错误与重试

HTTP说明
401认证失效,按认证接入处理
403访问、凭据类型或写请求保护校验不通过
404未找到当前用户拥有的有效会话
422会话 ID 等请求参数不合法
500服务端内部错误
503服务依赖或能力不可用
错误响应使用统一 ErrorBody,按 code 等结构化字段处理,不解析错误文字。采集降级通常返回 200 + partial/unavailable;不要将它与 HTTP 请求失败混淆。避免定时轮询此接口,用户需要诊断附件时才触发。