专业版配置

先用 auth、mount.container 和 events 完成标准嵌入，再增加会话恢复、下载接管或功能入口控制。不要在第一次联调时同时打开所有可选参数。

基础配置

const ppt = await AipptAgent.create({
  auth: {
    appKey: 'your-appkey',
    code: 'auth-code',
    channel: ''
  },
  mount: {
    container: document.getElementById('slide-root')!
  },
  iframe: {
    parentOrigin: window.location.origin
  },
  features: {
    downloadMode: 'external',
    showSessionList: true,
    showSkills: false
  },
  routerOptions: {
    list: ['generate', 'editor'],
    editor: {
      sessionId: 'existing-session-id',
      pageIndex: 0
    }
  },
  events: {
    onEvent(event) {
      console.log(event.type, event.payload)
    }
  }
})

参数按职责分为四组

接入参数

参数	类型	必填	说明
`auth.appKey`	`string`	是	开放平台分配的企业鉴权 appkey。
`auth.code`	`string`	是	接入方服务端按专业版鉴权获取的一次性凭证。iframe 初始化链路会用它完成凭证兑换和用户校验。
`auth.channel`	`string`	否	企业来源标识，可为空字符串。
`mount.container`	`HTMLElement`	否	iframe 挂载容器。不传时 SDK 自动创建全屏弹层。
`mount.iframeId`	`string`	否	iframe 元素 ID，默认 `aippt-agent-iframe`。同页存在多个实例时必须保证唯一。
`mount.useModal`	`boolean`	否	未传 `container` 时是否使用 SDK 全屏弹层，默认 `true`；设为 `false` 时 iframe 直接追加到 `document.body`。
`iframe.width`	`number \| string`	否	iframe 宽度，默认 `100%`。高度由挂载容器或弹层布局决定。
`iframe.allow`	`string \| string[]`	否	iframe Permissions Policy。
`iframe.parentOrigin`	`string`	否	父页面 origin，用于 postMessage targetOrigin 和 source 校验。建议传入 `window.location.origin`。
`events.onEvent`	`(event) => void`	否	事件回调，用于接收 iframe 状态、生成、保存、导出和异常事件。
`events.onReady`	`(event) => void`	否	初始化成功回调。
`events.onError`	`(error) => void`	否	初始化或运行异常回调。
`readyTimeout`	`number`	否	等待 `APP_READY` 的超时时间，单位毫秒，默认 `30000`。超时后 `AipptAgent.create()` reject。

`features` 参数

参数	类型	默认值	说明
`downloadMode`	`'external' \| 'internal' \| 'internal-with-url'`	`'internal-with-url'`	下载模式。`external` 由接入方接管下载；其余模式由 iframe 内触发浏览器下载
`featureCodes`	`string \| number[]`	-	功能按钮展示配置。传数组或逗号字符串时只展示命中的按钮。
`showSessionList`	`boolean`	`false`	是否展示专业版包内会话侧栏。嵌入 SDK 默认隐藏，显式传 `true` 后展示。
`showSkills`	`boolean`	`true`	是否展示 Generate 新建任务态的 Skills 区域。平台未启用 Skills 时，即使传 `true` 也不会展示。
`generateApproval`	`boolean`	`false`	是否在用户回车或点击发送后，先通过 `GENERATE_START_REQUEST` 请求宿主前端确认。等待期间不调用生成接口，也不设置业务超时。
`readonly`	`boolean`	`false`	是否启用编辑器只读模式。开启后标题、保存、插入、缩放手柄、删除和文本编辑等变更入口不可用；导出和放映仍由 `featureCodes` 单独控制。
`editable`	`boolean`	`true`	`readonly` 的兼容反向字段。推荐只使用 `readonly`；`editable: false` 等价于 `readonly: true`。

`routerOptions` 参数

参数	类型	默认值	说明
`list`	`Array<'generate' \| 'editor'>`	`['generate', 'editor']`	对宿主开放的业务模块。不传表示全选；可仅传 `generate` 或仅传 `editor`，但不能传空数组。
`generate.sessionId`	`string`	-	Generate 会话 ID。留空时 `/generate` 展示新建任务态；传入时展示该会话的生成态。
`editor.sessionId`	`string`	-	传入后初始化直接进入 Editor；Editor 入口必须提供。
`editor.pageIndex`	`number`	`0`	Editor 初始页序号，0-based。

routerOptions 只描述公开业务模块和初始化状态，不暴露 iframe 内部 Vue Router path。/ 仅是部署兼容入口：默认或允许 Generate 时进入 /generate，仅允许 Editor 时在 INIT 完成后进入 /editor；宿主不得把 / 当成独立页面。

`initial` 参数

参数	类型	默认值	说明
`sessionId`	`string`	-	旧兼容字段，等价于 `routerOptions.generate.sessionId`；新接入推荐使用 `routerOptions`。
`generate`	`object`	-	初始化后主动创建生成任务；至少提供 `content`。与 `sessionId` 不同时使用。

参数选择建议

如果这是基础接入，先只传 auth.appKey、auth.code、mount.container、iframe.parentOrigin 和 events.onEvent。默认进入 /generate 新建任务态；只有恢复会话或直达 Editor 时才补充 routerOptions。

参数使用规则

参数使用规则如下：

场景	规则
`parentOrigin`	建议始终显式传入当前宿主页面 origin。
`mount.container`	传入时，iframe 渲染在指定容器内；不传时，由 SDK 创建全屏弹层。
`features.showSessionList`	只使用这一个参数控制会话侧栏展示；`true` 展示，`false` 隐藏。
`features.showSkills`	控制 Generate 新建任务态的 Skills 区域；Skills 服务端能力仍是最终开关。
`routerOptions.list`	不传默认开放 `generate`、`editor`；显式传值时至少保留一个模块，空数组非法。
`routerOptions.generate`	无 sessionId 是新建态，有 sessionId 是会话态；两者都是同一个 Generate 页面。
`routerOptions.editor`	直达或仅开放 Editor 时必须提供 `sessionId`；`pageIndex` 仅在此处生效。
`features.downloadMode`	先明确下载责任归属，再选择模式，避免前后端对下载流程理解不一致。
`features.readonly`	仅控制 editor 变更能力，不等同于隐藏导出或放映；如需纯预览，可同时传 `readonly: true` 和不包含高级编辑、导出、放映编号的 `featureCodes`。

任务类型说明

专业版支持通过 initial.generate.content 或运行时 startGeneration() 主动生成，但不继续兼容旧 UI 的 custom_generate.type、taskId 多类型创建协议。

四种常见配置

组合一：标准嵌入页

await AipptAgent.create({
  auth: {
    appKey: 'your-appkey',
    code: 'auth-code'
  },
  mount: {
    container: document.getElementById('slide-root')!
  },
  iframe: {
    parentOrigin: window.location.origin
  },
  events: {
    onEvent(event) {
      console.log(event.type, event.payload)
    }
  }
})

适用场景：在现有业务页面中嵌入专业版，由 iframe 负责主要交互。

组合二：历史会话继续编辑

await AipptAgent.create({
  auth: {
    appKey: 'your-appkey',
    code: 'auth-code'
  },
  mount: {
    container: document.getElementById('slide-root')!
  },
  routerOptions: {
    list: ['generate', 'editor'],
    editor: {
      sessionId: 'existing-session-id',
      pageIndex: 0
    }
  }
})

适用场景：从作品列表、项目详情或任务记录中恢复某个会话。

组合三：仅开放 Editor

await AipptAgent.create({
  auth: {
    appKey: 'your-appkey',
    code: 'auth-code'
  },
  routerOptions: {
    list: ['editor'],
    editor: {
      sessionId: 'existing-session-id',
      pageIndex: 0
    }
  }
})

仅开放 Editor 时不会渲染 Generate，Editor 退出只通知宿主，不会固定跳转 Generate。仅开放 Generate 时，“高级编辑”入口隐藏，运行时调用 Editor 会返回 COMMAND_ERROR/COMMAND_NOT_SUPPORTED。

组合四：接入方接管下载

await AipptAgent.create({
  auth: {
    appKey: 'your-appkey',
    code: 'auth-code'
  },
  mount: {
    container: document.getElementById('slide-root')!
  },
  features: {
    downloadMode: 'external'
  },
  events: {
    onEvent(event) {
      console.log(event.type, event.payload)
    }
  }
})

适用场景：接入方已有下载中心、文件记录或审计流程。

选择配置时按以下顺序判断：

页面用于新建生成，还是恢复已有会话。
下载由 iframe 执行，还是由宿主页面接管。
导出、放映等入口是否需要对当前用户开放。

历史会话配置

专业版当前支持通过已有会话 ID 进入：

await AipptAgent.create({
  auth: {
    appKey: 'your-appkey',
    code: 'auth-code'
  },
  routerOptions: {
    list: ['generate', 'editor'],
    generate: {
      sessionId: 'existing-session-id'
    }
  }
})

常见用途：

从接入方作品列表继续编辑
从项目详情页打开历史生成结果
从任务记录中恢复上一次生成会话

接入建议：

在进入前由接入方确认会话 ID 来源正确
页面中保留当前业务对象与该会话的关联信息
若页面支持切换会话，建议由接入方自己维护会话来源和入口状态

运行时模块控制

SDK 不开放任意 Vue Router 路径，只公开 Generate 和 Editor 两个业务模块。Generate 内部包含新建态和会话态：

ppt.openGenerate()
ppt.navigate({ route: 'generate', sessionId: 'session-id' })
ppt.openEditor({ sessionId: 'session-id', pageIndex: 1 })

运行时切换成功后会收到 ROUTE_CHANGED，其中 route 只会是 generate 或 editor。editor 必须提供 sessionId；pageIndex 为 0-based。目标模块未包含在 routerOptions.list 时，SDK 方法直接抛错或 iframe 返回 COMMAND_ERROR/COMMAND_NOT_SUPPORTED。内部 / 按已开放模块选择入口，/speaker 仍是 Presenter 内部观众页，两者都不属于宿主合同。

运行时 SDK 方法

SDK 方法只负责把指令发送给 iframe，不代表业务已经完成。宿主必须监听对应结果事件；参数在 SDK 侧不合法时会直接抛出错误，iframe 执行失败时会返回 COMMAND_ERROR。

方法	主要参数	成功结果
`navigate(options)`	`route`、`sessionId?`、`pageIndex?`、`requestId?`	`ROUTE_CHANGED`
`openGenerate(options?)`	`sessionId?`、`requestId?`	`ROUTE_CHANGED`，无 session 为新建态
`openSession(options)`	`sessionId`、`requestId?`	`ROUTE_CHANGED`，进入 Generate
`openEditor(options)`	`sessionId`、`pageIndex?`、`requestId?`	`ROUTE_CHANGED`
`startGeneration(options)`	`content`、`requestId?`	`GENERATE_START`，后续接收 `GENERATE_*`
`respondToGenerateRequest(options)`	`requestId`、`approved`、`code?`、`message?`	恢复或拒绝 iframe 内等待中的用户提交
`export(options)`	`format`、`filename?`、`pages?`、`resolution?`、`requestId?`	`PPT_EXPORT_*`
`startPresentation(options?)`	`mode?`、`pageIndex?`、`requestId?`	`PRESENTATION_STARTED`
`stopGeneration()`	无	`GENERATE_STOPPED`
`refreshAuth({ code })`	新的一次性 `code`	`AUTH_REFRESH_SUCCESS` / `AUTH_REFRESH_FAILED`
`destroy()`	无	销毁 iframe 和 SDK 监听，不提供业务回执

ppt.startGeneration({ content: '生成一份 2026 年产品规划', requestId: 'gen-001' })
ppt.export({ format: 'pptx', pages: [0, 1], resolution: 2, requestId: 'export-001' })
ppt.startPresentation({ mode: 'normal', pageIndex: 0, requestId: 'play-001' })

启用生成前确认时，宿主监听请求事件并返回同一个 requestId：

const ppt = await AipptAgent.create({
  // auth / mount 省略
  features: { generateApproval: true },
  events: {
    async onEvent(event) {
      if (event.type !== 'GENERATE_START_REQUEST') return
      const approved = await customerFrontendCheck(event.payload)
      ppt.respondToGenerateRequest({
        requestId: event.payload.requestId,
        approved,
        message: approved ? undefined : '当前账号无生成权限'
      })
    }
  }
})

该确认只发生在 iframe 与客户宿主页面之间，不请求 AIPPT 后端鉴权接口。SDK 不设置确认超时；宿主必须明确返回批准或拒绝。

pages、pageIndex 均为 0-based；pages 按当前可导出的已完成页面编号选择。宿主通过 postMessage 触发 fullscreen 不具备浏览器用户手势，会收到 COMMAND_ERROR/USER_GESTURE_REQUIRED；需要全屏时应由用户在 iframe 内点击触发。

下载模式

值	行为	适用场景
`'external'`	iframe 不主动触发浏览器下载，接入方通过 `PPT_EXPORT_*` 事件接管下载体验。	接入方有自己的下载中心、文件管理、审计或订单流程。
`'internal'`	iframe 内触发浏览器下载。	由 iframe 直接完成浏览器下载。
`'internal-with-url'`	iframe 内触发浏览器下载，同时发送下载相关事件。	接入方希望保留 iframe 下载体验，同时同步业务状态。

当 features.downloadMode = 'external' 时，请监听 PPT_EXPORT_START、PPT_EXPORT_COMPLETE、PPT_EXPORT_ERROR。

接入建议：

若用户需要在当前页面直接看到下载结果，优先使用 'external' 或 'internal-with-url'
若只要求快速下载，可使用 'internal'
一旦确定模式，前端提示文案和按钮行为应与该模式保持一致

错误边界

生成、保存、导出或授权异常会通过 iframe 页面提示，并通过 APP_ERROR、GENERATE_ERROR、PPT_SAVE_ERROR、PPT_EXPORT_ERROR 等事件同步给接入方。接入方可根据事件中的 code、message、statusCode 展示外层提示、记录日志或引导用户重试。

额度、权限和服务可用性属于平台侧校验结果，不通过前端事件完成账务或权限变更。接入方如需展示更细的业务提示，应以事件返回信息和服务端配置结果为准。

APP_READY 会返回 auth.tokenExpiresAt、auth.tokenExpiresIn 和 auth.refreshRequiredAt。访问凭证有效期以这些返回字段为准，不应在接入方代码中写死固定时长。iframe 不能用已消费的 code 静默续期；接入方如需长时间停留，可以选择两种方式：

自主刷新：接入方在接近 refreshRequiredAt 时由服务端重新申请 code，再重新加载 iframe。
页面内刷新：iframe 通过 AUTH_REFRESH_REQUIRED 请求刷新，接入方重新获取新的 code 后，通过 SDK refreshAuth() 发送 AUTH_REFRESH_REQUEST，iframe 使用新凭证更新认证状态。

功能按钮展示

features.featureCodes 用于控制专业版页面内指定功能按钮的展示：

按钮	`featureCodes` 编号
高级编辑	`2024` 或 `2025`
放映	`2028`
导出	`2029`、`2030`、`2031`、`2032`、`2033`、`2034`、`2035`、`2036`

示例：只展示高级编辑和放映，隐藏导出入口。

await AipptAgent.create({
  auth: {
    appKey: 'your-appkey',
    code: 'auth-code'
  },
  features: {
    featureCodes: [2024, 2028]
  }
})

示例：只读预览，不允许编辑且隐藏高级编辑、放映和导出入口。

await AipptAgent.create({
  auth: {
    appKey: 'your-appkey',
    code: 'auth-code'
  },
  features: {
    readonly: true,
    featureCodes: []
  }
})

接入建议：

优先按业务目标保留必要入口，避免同屏动作过多
若接入方已经接管下载，建议同步检查导出入口是否仍需保留在 iframe 内
正式发布前，确认按钮展示策略与业务权限和页面说明一致

不支持项

未在配置表中声明的创建入口、页面能力和控制参数，不属于当前开放平台接入合同。

如果接入方需要扩展新的创建方式或页面控制能力，请以平台后续发布的配置项和事件协议为准。

接口明细

生成链路

大纲数据与导出

模板与作品

统计与其他

专业版配置

基础配置

参数按职责分为四组

接入参数

`features` 参数

`routerOptions` 参数

`initial` 参数

参数使用规则

四种常见配置

组合一：标准嵌入页

组合二：历史会话继续编辑

组合三：仅开放 Editor

组合四：接入方接管下载

历史会话配置

运行时模块控制

运行时 SDK 方法

下载模式

错误边界

功能按钮展示

不支持项

生成链路

大纲数据与导出

模板与作品

统计与其他

专业版配置 ​

基础配置 ​

参数按职责分为四组 ​

接入参数 ​

features 参数 ​

routerOptions 参数 ​

initial 参数 ​

参数使用规则 ​

四种常见配置 ​

组合一：标准嵌入页 ​

组合二：历史会话继续编辑 ​

组合三：仅开放 Editor ​

组合四：接入方接管下载 ​

历史会话配置 ​

运行时模块控制 ​

运行时 SDK 方法 ​

下载模式 ​

错误边界 ​

功能按钮展示 ​

不支持项 ​

专业版配置

基础配置

参数按职责分为四组

接入参数

`features` 参数

`routerOptions` 参数

`initial` 参数

参数使用规则

四种常见配置

组合一：标准嵌入页

组合二：历史会话继续编辑

组合三：仅开放 Editor

组合四：接入方接管下载

历史会话配置

运行时模块控制

运行时 SDK 方法

下载模式

错误边界

功能按钮展示

不支持项