专业版事件字段

按字段名可以在这里查询 payload 含义。第一次接入先阅读 事件通知 确定需要监听的事件，再回到这里处理字段和枚举值。

常用字段

这些字段不是每个事件都会返回。可以把它们理解为“不同事件 payload 里可能出现的公共字段”。

字段	类型 / 形态	常见事件	建议用途
sessionId	字符串	APP_READY、GENERATE_*、PPT_EXPORT_*、SESSION_OPENED	标记当前会话，便于页面恢复、列表回跳和问题定位。
workId / id	字符串	GENERATE_COMPLETE、EDITOR_READY、PPT_SAVE_*、PPT_EXPORT_*	标记作品对象，适合与接入方业务记录关联。PPT_SAVE_* 使用 id 表示 PPT 作品 ID。
title / filename	字符串	GENERATE_COMPLETE、PPT_EXPORT_*、PPT_DOWNLOAD_START	展示会话标题、下载文件名或写入业务记录。
message / detail	字符串 / 对象	APP_ERROR、GENERATE_PROGRESS、GENERATE_ERROR、PPT_EXPORT_ERROR	展示过程说明或异常信息；detail 更偏技术排查。
code / errorCode	字符串	APP_ERROR、GENERATE_ERROR、PPT_SAVE_*、AUTH_REFRESH_FAILED	做错误分流。例如 GENERATE_ERROR.code = CONTENT_RISK 表示输入内容需要修改且任务未创建。注意它不是鉴权 code，不要混用。
statusCode	数字	APP_ERROR、GENERATE_ERROR	记录 HTTP 状态或辅助判断鉴权、服务异常。
phase / pageIndex / totalPages	字符串 / 数字	GENERATE_PROGRESS、EDITOR_READY、PPT_EXPORT_*	展示进度。pageIndex = -1 表示非页级阶段。
source / reason	字符串枚举	GENERATE_STOPPED	区分用户停止、宿主停止、后端中断或无作品完成。
format / url / fileSize	字符串 / 数字	PPT_EXPORT_*、PPT_DOWNLOAD_START	控制导出结果、下载入口和文件记录。
auth.*	对象字段	APP_READY、AUTH_REFRESH_*	判断 token 剩余时间、刷新时机和认证刷新结果。

事件专属字段

额度异常字段

当前没有独立的 BILLING_UNAVAILABLE 出站事件。生成阶段请读取 GENERATE_ERROR.code / reason，初始化阶段请读取 APP_ERROR.code / statusCode；不要根据 SDK 中的预留事件常量建立业务监听。

下面这些字段只在部分事件中出现，通常不是所有事件的公共返回值。

字段	出现事件	含义	接入方处理建议
version	APP_READY	iframe SDK 或页面能力版本。	用于排查接入环境和版本兼容问题，一般不需要展示给终端用户。
timestamp	APP_READY	应用就绪时刻的时间戳。	可用于记录初始化耗时、排查加载时序。
auth.tokenExpiresAt	APP_READY、AUTH_REFRESH_REQUIRED	当前 token 的过期时间。	用于提前刷新认证；不要把 token 本身写入事件。
auth.tokenExpiresIn	APP_READY、AUTH_REFRESH_REQUIRED	当前 token 距离过期的剩余秒数。	可用于判断是否立即刷新或提示用户重试。
auth.refreshRequiredAt	APP_READY、AUTH_REFRESH_REQUIRED	建议接入方重新申请 fresh code 的时间。	到达该时间前后重新向服务端申请 code，再通过父→子 AUTH_REFRESH_REQUEST 推给 iframe；旧 AUTH_REFRESH 仅兼容。
requestId	GENERATE_START_REQUEST、GENERATE_START_RESPONSE、GENERATE_ERROR	确认流程中关联同一次前端请求；任务创建失败时用于关联后端错误。	确认响应必须原样返回；错误事件中该字段可选，仅用于排障。
entry	GENERATE_START_REQUEST	home、chat 或 skill，表示用户提交入口。	用于区分新建页、会话输入和技能入口，不包含用户输入内容。
trigger	GENERATE_START_REQUEST	enter 表示回车提交，click 表示点击发送按钮。	仅用于客户侧审计或交互区分，不包含用户输入内容。
approvalRequestId	GENERATE_START	关联此前已批准的 GENERATE_START_REQUEST.requestId。	可与父 SDK 内部 SDK_GENERATE_APPROVAL.data.requestId 对照，确认批准后是否真正进入生成流程。
approved	GENERATE_START_RESPONSE	true 继续原生成流程；false 保留草稿并结束等待。	必须为 boolean；该响应是父到子指令，不调用后端鉴权。
msgKey / msgParams	APP_ERROR、GENERATE_ERROR	错误信息的国际化 key 和参数。	如果接入方有自己的多语言体系，可用它们映射本地文案；否则优先展示 message。
prompt	GENERATE_START	本次生成使用的用户输入。	可写入接入方任务记录；若涉及隐私内容，按接入方自己的日志策略处理。
backendTaskLabel	GENERATE_START	后端任务标签或展示名，不是接入方传入的任务类型。	仅用于展示或排查，不建议作为业务分支条件。
totalCount	GENERATE_COMPLETE	后端返回的总页数。	可与 totalPages 对比，排查前端实际收到页数和后端声明页数是否一致。
saveMode	PPT_SAVE_START、PPT_SAVE_SUCCESS、PPT_SAVE_ERROR、PPT_SAVE_CONFLICT	保存方式，通常为 manual 或 auto。	手动保存失败建议强提示；自动保存失败可弱提示或记录日志。
savePage / saveTitle	PPT_SAVE_START	本次保存是否包含页面内容、是否包含标题。	用于排查保存范围，一般不需要作为用户可见字段。
status	GENERATE_PROGRESS、PPT_SAVE_*	当前阶段状态。生成进度中表示运行状态；保存结果中表示是否成功。	需要结合事件类型判断，不能跨事件复用同一套含义。
recoveryKind / recoveryAction	PPT_SAVE_ERROR、PPT_SAVE_CONFLICT	保存失败或冲突的恢复类型和建议动作。	retry 可引导重试；refresh 可引导刷新或重新进入。
readonly	EDITOR_READY、EDITOR_EXIT	编辑器是否处于只读状态。	可同步外层按钮状态，例如隐藏保存、编辑类操作。
resolution	PPT_EXPORT_START	导出分辨率。	用于展示导出规格或写入下载记录。
duration	PPT_EXPORT_COMPLETE	导出耗时。	可用于性能统计或问题排查。
updatedAt	SESSION_OPENED	会话最近更新时间。	可用于列表排序、最近编辑时间展示或问题定位。
state	SESSION_OPENED	会话状态，例如 idle 或 running。	用于恢复页面状态；运行中会话可展示继续生成或处理中提示。

枚举值说明

如果字段值是 a | b | c 这种形式，请按下面的分组理解。接入方不要只判断字段是否存在，还需要结合事件类型和枚举值决定页面状态。

生成进度

字段	取值	含义	接入方处理建议
GENERATE_PROGRESS.status	running	生成任务已开始运行，通常还没有进入稳定的逐页生成阶段。	展示“生成中”或“准备生成”状态，不要把它当成完成。
GENERATE_PROGRESS.status	generating	正在生成内容或页面，可能会伴随页码、总页数和进度文案。	展示进度文案；如果 phase = non-page，不要渲染真实页码。
GENERATE_PROGRESS.status	completed	SSE 进度层面的完成状态，不等同于宿主侧最终成功事件。	不要仅凭它判断生成成功；宿主页面应以 GENERATE_COMPLETE 为成功依据。
GENERATE_PROGRESS.phase	page	页级生成阶段，pageIndex 表示当前页码。	可以展示“正在生成第 N 页 / 共 M 页”。
GENERATE_PROGRESS.phase	non-page	全局阶段，例如分析、收集资料、组织大纲等，不对应真实页面。	展示阶段文案即可；此时 pageIndex = -1、totalPages = 0 不能当页码显示。

生成停止

字段	取值	含义	接入方处理建议
GENERATE_STOPPED.source	user	用户在 iframe 页面内主动停止生成。	提示“生成已停止”。
GENERATE_STOPPED.source	host	接入方宿主页面通过外部流程触发停止。	提示“生成已由接入方停止”，并同步外层任务状态。
GENERATE_STOPPED.source	backend	服务端取消、中断或判定无法继续生成。	提示稍后重试或联系支持，并记录 reason。
GENERATE_STOPPED.reason	user_stop	用户主动停止。	通常与 source = user 搭配。
GENERATE_STOPPED.reason	external_stop	宿主页面或接入方业务流程主动停止。	通常与 source = host 搭配。
GENERATE_STOPPED.reason	backend_cancelled	后端取消或中断任务。	通常与 source = backend 搭配，需要记录日志。
GENERATE_STOPPED.reason	completed_without_work	任务完成链路结束，但没有拿到可预览作品。	不要当作生成成功；建议提示重试，并排查 completed 事件是否缺少 work_id。
GENERATE_STOPPED.reason	idle	会话空闲或任务无继续动作后结束。	可弱提示或恢复到可再次生成状态。

保存恢复

字段	取值	含义	接入方处理建议
PPT_SAVE_*.saveMode	manual	用户手动触发保存。	成功或失败都建议给明确反馈。
PPT_SAVE_*.saveMode	auto	系统自动保存。	成功可不打扰用户；失败可弱提示并保留重试入口。
PPT_SAVE_*.recoveryKind	error	普通保存失败。	根据 recoveryAction 展示重试或刷新入口。
PPT_SAVE_*.recoveryKind	conflict	保存冲突，通常表示当前内容与远端状态不一致。	提示用户刷新、重新进入或按接入方策略处理冲突。
PPT_SAVE_*.recoveryAction	retry	建议重试当前保存动作。	展示“重试保存”操作。
PPT_SAVE_*.recoveryAction	refresh	建议刷新或重新进入，以恢复到一致状态。	展示“刷新页面”或“重新进入编辑器”操作。

导出格式与会话状态

字段	取值	含义	接入方处理建议
PPT_EXPORT_*.format	pptx	导出 PowerPoint 文件。	适合继续编辑或下载源文件。
PPT_EXPORT_*.format	pdf	导出 PDF 文件。	适合预览、归档或分发。
PPT_EXPORT_*.format	png	导出图片格式。	通常用于图片预览、封面或页面截图类场景。
PPT_EXPORT_*.format	html	导出 HTML 文件或页面资源。	适合网页预览、嵌入展示或二次分发。
SESSION_OPENED.state	idle	会话当前没有运行中的生成任务。	外层页面可展示可编辑、可继续生成或普通查看状态。
SESSION_OPENED.state	running	会话存在运行中的生成任务。	外层页面应恢复处理中状态，避免重复触发生成。

认证刷新原因

字段	取值	含义	接入方处理建议
AUTH_REFRESH_REQUIRED.reason	expiring_soon	token 即将过期。	提前申请 fresh code 并推送给 iframe。
AUTH_REFRESH_REQUIRED.reason	expired	token 已过期。	尽快刷新认证；刷新失败时提示用户重试。
AUTH_REFRESH_REQUIRED.reason	unauthorized	当前认证状态无效或未授权。	重新走接入方鉴权流程，获取新的 fresh code。
AUTH_REFRESH_REQUIRED.reason	manual	页面或调试流程主动请求刷新认证。	按普通刷新认证处理，不要复用初始化 code。

事件字段索引

目标	页面
先理解事件主线	事件通知
宿主主动控制 iframe	事件推送
查完整事件 payload	完整事件清单