Skip to main content

提交问题反馈(可附诊断包)

千问办公企业旗舰版开发者文档:提交问题反馈(可附诊断包)。

认证方式见APP开发者文档 → 认证接入。
  • 接口:PUT/api/openapi/app/v1/feedback
  • Content-Type:multipart/form-data

资源归属

反馈及附件按当前用户确定归属,不能通过请求参数指定他人。响应携带 Cache-Control: no-store。

请求参数

参数类型必填约束与说明
sourcestring否由服务端固定为 web;调用方无需提交,此字段不承担身份授权
request_idstring是1~64 位字母、数字、下划线或连字符;提交幂等标识
descriptionstring是非空,不超过 4000 个 Unicode 码点
ide_typestring是非空,最多 32;当前 Web 使用 QwenWork
ide_versionstring是非空,最多 256;填写实际 Web 版本
plugin_versionstring是非空,最多 32;Web 可使用 not-applicable
filefile否最多一个合法诊断 ZIP,最大 100 MiB;无日志时可以省略
oss_keystring否最多 128;已有直传诊断对象的 Key,须匹配服务端根路径及 request_id,且对象存在;设置后使用该对象
img_urlsstring否最多 8192;同用户、同 request_id 的截图上传接口返回地址,以逗号连接,最多 5 张
user_namestring否最多 64
user_emailstring否最多 128,合法邮箱
extrastring否JSON 序列化后的扩展文本;服务诊断会话线索为其中的 session_id。可附 page_url、user_agent、captured_at、web_version;不能作为资源授权依据
planstring否最多 16
creditsstring否最多 16,非负数字文本,可带小数
tagsstring否最多 512
除 description 外,上述文本长度按现有实现的 UTF-16 单元计数。请求体含 multipart 开销不得超过 105 MiB。旧契约中的 user_id、org_id 不用于确定归属,服务端使用可信登录身份。诊断 ZIP 还会接受结构及解压安全校验,不能上传任意文件冒充诊断包。

响应与幂等

HTTP 200,以下示例为服务端已补充诊断包、部分服务日志不可用的提交:
{
  "requestId": "feedback-example-001",
  "success": true,
  "result": {
    "url": "https://example.invalid/diagnostic-object",
    "applicationLogsStatus": "partial"
  }
}
未提供诊断附件时也可创建反馈。关联有效 extra.session_id 且未指定 oss_key 的 Web 提交,会由服务端补充服务诊断包:即使没有上传 file,也可能返回非空 result.url。未触发该流程且没有附件时,result.url 为空字符串。对象地址不承诺匿名可下载;正式下载由管理侧授权。对象上传失败可能返回 HTTP 200、success=false,必须检查业务结果。 服务诊断补充流程完成时可能返回 result.applicationLogsStatus:complete 表示本次所有服务模块均报告完整,任一模块部分可用或不可用时为 partial;详细覆盖和原因见 ZIP 中的 service-diagnostics/manifest.json。未触发补充流程、使用 oss_key 或幂等重放已有反馈时,该字段可能省略,不能把省略视为完整。此字段不改变 success 的提交结果,也不表示 Session 沙箱日志采集完整。 同一用户重复提交已存在的 request_id 会复用已有记录,不更新原反馈内容;其他用户占用的 ID 返回 409 idempotency_conflict。前置参数校验仍会执行,重试需保持合法参数。

响应字段

字段类型必返说明
requestIdstring是反馈请求标识,对应提交的 request_id。
successboolean是业务是否成功;HTTP 200 不代表该值一定为 true。
resultobject是上传结果。
result.urlstring是上传或服务端生成的诊断对象地址;没有诊断对象时为空字符串。不保证匿名可下载,以 success 判断提交结果。
result.applicationLogsStatusstring否complete / partial,仅描述本次服务日志补充结果;省略时不能判断完整性。

错误处理

401 为可信用户身份缺失或非法;403 audience_mismatch 为入口身份平面不匹配。400 validation_failed 为参数或文件不合法,503 feedback_unavailable 为反馈依赖不可用。不能仅凭 HTTP 200 判断提交成功,还需检查响应中的 success。 上传还可能返回 400 invalid_multipart、409 idempotency_conflict、413 payload_too_large 或 429 限流。

会话日志附件

关联有效 extra.session_id 的 Web 反馈由后端直接采集沙箱日志与服务日志并合包。前端只上传可选浏览器日志 ZIP、正文和截图,不需要下载或解包 Session 日志。后端根据可信用户和组织校验会话归属,采集失败仍保留反馈及其他可用材料;最终 ZIP 的 sandbox-manifest.json、service-diagnostics/manifest.json 和根 manifest 分别记录真实结果。既有 Session 独立采集接口保留兼容。 改变正文、截图或所选会话应生成新的 request_id;同一次失败重试复用原 ID 和提交内容。

会话关联的正确传法

extra 是 multipart 的一个文本字段,值是 JSON 字符串。例如:
source = web
extra = {"session_id":"11111111-1111-4111-8111-111111111111"}
服务端只从 extra.session_id 提取会话线索;JSON 无法解析、扩展文本超过 8192 字节或 session_id 不是有效非零 UUID 时,不会形成有效的会话关联。不要把这类输入的反馈提交成功解释为日志采集成功。 顶层 multipart session_id、collect_sandbox_logs 不是本接口已支持的采集参数。把它们放在表单、查询参数或客户端 ZIP 的 manifest 中,都不能代替 extra.session_id,不能单独触发沙箱日志采集。request_id 仍须放在 multipart 表单中,查询参数不能替代它。 未关联会话时,省略 extra.session_id,不调用 Session 采集接口;前端内部的可选 sessionId 使用缺省值,不传空字符串。无会话、无日志包都不应阻止正文及截图提交。

提交反馈示例

以下只展示表单组装与提交。browserLogFile 是可选的浏览器诊断包;沙箱和服务日志由后端采集。截图地址应由同一 request_id 的截图上传得到。
async function submitFeedback({ requestId, description, webVersion, sessionId,

  browserLogFile, imageUrls = [ ] }) {

  const sid = sessionId?.trim() || undefined;
  const form = new FormData();
  form.set('request_id', requestId);
  form.set('description', description);
  form.set('source', 'web');
  form.set('ide_type', 'QwenWork');
  form.set('ide_version', webVersion);
  form.set('plugin_version', 'not-applicable');
  if (sid) form.set('extra', JSON.stringify({ session_id: sid }));
  if (browserLogFile) form.set('file', browserLogFile);
  if (imageUrls.length) form.set('img_urls', imageUrls.join(','));
  const response = await appRequest('/api/openapi/app/v1/feedback', {
    method: 'PUT',
    body: form,
  });
  const body = await response.json();
  if (!response.ok || body.success !== true || body.requestId !== requestId) {
    throw new Error('Feedback submission was not confirmed');
  }
  return body; // applicationLogsStatus is optional; absent does not mean complete.
}
调用方需先验证所选会话 ID,采集失败时保留明确的诊断状态并允许提交。成功收到反馈回执只表示记录保存完成,不能据此把 ZIP 标记为“完整日志”。