在 Session 中收集并发送 Agent Bug Report¶
当 Agent 回复异常、工具卡住、连接不稳定或日志不足以定位问题时，可以直接在发生问题的 Session 中生成 Bug Report。报告会收集当前 Session 和 Agent 运行状态，完成脱敏后打包上传，供运维或支持人员下载分析。
开始前，请确认 Agent 在线，并打开发生问题的原 Session。Bug Report 只收集当前 Session，不会自动包含其他 Session 的聊天正文。
收集并直接发送到支持邮箱¶
需要把报告交给支持人员时，建议在首次请求中同时提供收件地址和故障现象：
Agent 会完成以下操作：
- 收集、脱敏并上传当前 Session 的 Bug Report；
- 获取 ZIP 文件的临时下载链接；
- 把文件名、链接和过期时间发送到指定邮箱。
使用这个流程，无需先从 Session 手动下载 ZIP，再把文件作为邮件附件上传。邮件发送的是临时下载链接，不是 ZIP 附件；收件人需要在链接有效期内下载报告。
发送前请确认收件地址正确，并只发送给有权限处理诊断数据的人员。
收集当前 Session 的 Bug Report¶
在 Session 中发送：
如需补充故障现象，可以直接写在同一条消息中：
Agent 会依次收集、脱敏、打包并上传报告。整个过程通常在两分钟内完成；启用 CPU Profile 时可能需要额外等待采样结束。
上传成功后，Session 中会显示 ZIP 文件及下载信息。报告在平台中默认保留 30 天，临时下载链接默认有效 7 天。请在链接过期前完成下载或转交。
在普通权限模式下批准收集¶
普通权限模式会在读取诊断数据前显示工具审批。审批内容会列出采集范围、数据类别，以及是否包含 CPU Profile。
确认范围符合预期后批准操作，Agent 才会开始收集。拒绝审批、取消请求或发送新消息终止旧运行时，不会生成或上传报告。
YOLO 全权限模式（页面显示“完全访问权限”）不会显示审批弹窗，Agent 会直接执行收集和上传。平台仍会记录本次工具调用的授权审计信息。
将已经生成的 Bug Report 补发到邮箱¶
如果首次请求只生成了报告，可以在同一 Session 中继续发送：
邮件正文包含 ZIP 文件名、过期时间和临时下载链接，不会把 ZIP 作为邮件附件发送。收件人需要在链接有效期内下载报告。
控制报告包含的数据¶
默认报告包含：
- 当前 Session 中经过脱敏和裁剪的消息、工具事件及有效上下文；
- Agent 的近期日志和运行指标；
- 进程、容器、网络探测和构建信息；
- 经过脱敏的环境变量与配置；
- Profile、Skill、Schema 和 MCP 的同步诊断摘要；
- 受限的 goroutine dump 和 Heap Profile。
Session 附件只记录名称、类型、大小和内容摘要，不读取附件正文。报告不会主动采集其他 Session 的聊天正文，也不会打包完整的 Skill、Schema、MCP 包或工作目录文件。
如需排查 CPU 占用问题，可以明确要求增加 CPU Profile：
CPU Profile 默认不采集，可指定 1～30 秒。采样期间会增加少量 Agent 开销，建议仅在需要分析 CPU 问题时启用。
如不希望收集某类信息，也可以在请求中明确排除：
安全地处理诊断报告¶
Agent 会遮盖已知运行时密钥和高置信度凭证，并在打包前再次扫描敏感内容。自由文本中的敏感信息无法保证全部识别，因此 Bug Report 仍应按敏感诊断数据处理。
下载后请遵循以下原则：
- 只通过受控渠道交给负责排障的人员；
- 不要上传到公开工单、公开代码仓库或公共文件分享服务；
- 排障完成后删除不再需要的本地副本；
- 如果 Session 中包含手动粘贴的密码、Token 或个人信息，发送前应提醒接收方，并按组织的数据处理规范操作。
处理收集或上传失败¶
一直等待审批¶
普通权限模式需要批准待处理的工具调用。如果审批因取消请求或发送新消息而不再可用，请重新发送收集请求。
如果 Agent 已配置为 YOLO 全权限模式却仍显示审批，或者出现 approval_id is required for diagnostic assets，请将 Beak 服务和 Agent 更新到同一最新版本后重试。
显示已有任务正在运行¶
每个 Agent 同时只能收集一份 Bug Report。等待当前任务结束后再重试；不要在同一时间从多个 Session 重复发起收集。
报告状态为 partial¶
partial 表示部分诊断来源不可用、超时或因安全检查被移除，其余可用内容仍已上传。可以先下载报告查看缺失项；如缺少关键内容，请确认 Agent 权限、日志文件和网络状态后重新收集。
上传返回 context deadline exceeded¶
该错误可能表示 Agent 版本仍在让采集和上传共用同一个超时。将 Agent 更新到最新版本后重试。如果更新后仍然失败，请检查 Agent 到 Beak 服务的网络连接，并按查看 Agent 日志中的步骤检查最近错误。
无法生成诊断资产¶
如果页面提示服务不支持诊断资产，请确认 Beak 服务与 Agent 已升级到相互兼容的版本。升级完成后重启 Agent，再从原 Session 重新发起收集。
邮件中没有下载链接¶
先确认 Session 中已经成功生成 Bug Report，并且临时下载链接尚未过期。然后重新要求 Agent 发送刚生成的报告。如果邮件仍缺少链接，请更新 Agent，并检查邮件工具是否已正确配置。