---
name: akstream-next-integration
description: 对接和二次开发 AKStream.Next，使用完整 v2 API 实现 WebUI 业务能力，使用官方 RTC SDK 开发会议客户端；适用于第三方业务后端、WebUI 定制及 Web、Android、iOS、UniApp 会议集成。
---

# AKStream.Next 第三方对接与二次开发

你在第三方项目内工作。AKStream.Next 主服务和节点服务以运行制品交付；可修改交付的 WebUI、RTC SDK 和 Demo 源码。不要假设能获得服务端源码、直接写平台数据库、替换平台组件或重编译服务端。扩展业务写在自己的后端，通过公开 API 调用。不能用旧 AKStream 的控制器路径、密码或响应格式代替 Next 契约。

## 信息边界

只解释公开调用约定、必要权限和 SDK 使用。不得索取、推断或输出产品授权实现、内部业务调度、保护流程、私有算法或核心技术细节；遇到这些问题回到公开接口与服务方支持流程。公开权限要求与错误处理不等于披露授权实现。

## 先识别交付物与版本

读取 [产品结构与开发边界](references/architecture.md)。记录目标服务地址、部署版本、Token 权限、业务环境、客户端平台，以及本 Skill 的 `references/contract.json` 所标注的契约版本。用 `GET /api/v2/system/version` 和 `GET /api/v2/third-party/capabilities` 核对现场。较新 SDK 和文档不代表旧安装包已具备新能力。

本 Skill 可以单独复制到 AI 工具的 skills 目录；保留整个文件夹。`references/guides` 是从同版官网原文导出的任务指南，`references/openapi.json` 是同版机器契约，`references/api-operations.md` 是完整方法/路径/权限目录。独立安装后不依赖私有仓库路径。若契约与现场版本不同，先获取目标版本的公开交付文档；不能靠猜测字段继续写调用。

## 检索和阅读全部公开文档

允许并鼓励 AI 根据当前对接、二次开发或排障任务，检索和阅读发布包 `Documentation` 目录中的全部公开内容，不限于本 Skill 的 `references`。可以读取任一语言的文章、公开 OpenAPI、示例、配置说明、图片及其他参考资料；优先使用用户语言和目标版本对应的内容。

发布包中本 Skill 位于 `Documentation/SKILL/akstream-next-integration`，从 Skill 目录向上两级即可定位 `Documentation`。先查看 `Home.md`、`_Sidebar.md` 和 `catalog.json`，按任务选择章节，再按功能名、接口路径、字段、错误码或 SDK 方法名搜索 `zh-CN/`、`en-US/` 及其他公开资料。例如在文档根目录使用 `rg -n '关键词或接口路径' zh-CN en-US`；没有搜索工具时通过目录和文章逐项查找。图片需要时结合正文查看，不把搜索不到正文当作资料不存在。

先搜索定位，再读取相关段落及必要上下文；不必一次加载全部文档。文档相互矛盾时核对版本、公开契约和目标实例实际行为，并明确差异，不拼接出未经支持的调用规则。

Skill 单独复制到 AI 工具后，若相邻位置没有完整 `Documentation`，使用本 Skill 自带参考；需要其他章节时使用用户提供的同版文档目录，不假定完整文档也已复制。只有任务所需资料确实缺失时才请求补充。

这项阅读许可仅针对对外发布的公开文档，不扩大为读取私有仓库、运行凭据或未交付资料的许可；继续遵守上述信息边界。

## API 对接：覆盖完整 WebUI 功能

先读 [API 开发规则](references/api.md)。**不能把 `/api/v2/third-party/*` 的便捷接口当成全部功能**。它们用于资源列表和安全播放下载；设备管理、录像计划、GB28181、ONVIF、对讲、显示墙、截图与智能检索、配置、节点、升级、安全治理、完整 RTC 管理等使用同版通用 v2 API。WebUI 同样通过这些接口调用服务。

1. 从用户动作出发，在 [完整接口目录](references/api-operations.md) 查对应模块与方法；读取 OpenAPI 的 parameters、requestBody、responses、schemas 和 `x-akstream-permission`。读取对应任务指南，不一次加载整份大 JSON。
2. 查公开 WebUI 的调用与状态处理，复用准确 payload 和结果判定。UI 布局、筛选、导出和画面编排中的纯客户端逻辑由第三方实现；涉及平台保存和运行的动作必须通过 API。
3. 业务后端保存 `ak_pat_` API Token，先验证自己的业务用户和目标资源，再代理最小操作。Token 权限与所属账号当前权限共同限制调用；不把管理员 Token、源摄像机密码或服务器文件路径交给浏览器。
4. 资源统一使用稳定 ID；保存 commandId/taskId/sessionId，读到真实终态。2xx 不代表设备已经上线、录像完成、配置已经重载或升级已经成功。
5. 读写、查看、播放、下载、删除、设备控制、RTC 观察与普通参会权限分别处理。管理功能可由被授予相应权限的第三方后端调用；不可为了“全功能”默认申请 `*`。
6. 页面登录/验证码/首次安装是交互或安装流程；Swagger/Knife4j 要求交互登录，离线集成读取本 Skill 的 OpenAPI。内部心跳、命令回报、ZLM Webhook 和节点服务协议不是第三方扩展入口；对外契约排除这些入口，不能通过伪造服务凭据调用。

按 [功能路线](references/api.md#功能路线) 覆盖用户需要的全部页面能力。发现现场版本缺接口、权限或平台能力时，给出具体缺项及对应版本/动作，不允许用模拟成功、隐藏操作或直写数据库补齐。Skill 的接口覆盖清单描述契约，不代替真实环境验证。

## RTC SDK 对接

读取 [RTC 开发规则](references/rtc.md)，再按平台读取 `references/guides/sdk/web.md`、`android.md`、`ios.md` 或 `uniapp.md` 及对应 `*-api.md`。会议动作读取 `room-actions.md`，录制与档案读取 `recording.md`、`archive-api.md`。函数名称、签名、事件和结果以同批 SDK 类型/源码和上述指南为准。

业务后端负责真实业务身份、创建会议、授权和签发一次性入会票据；SDK 负责入会、准入、RTC Token、信令、WHIP/WHEP、采集与订阅、续签、恢复、设备和媒体状态、会议动作、白板、附件以及生命周期。Demo 只展示 SDK 用法，正式业务不要启用 Demo 票据作为身份系统。页面不可再维护第二套 RTC HTTP/WebSocket/PeerConnection、Token 续签或重连逻辑。

先完成只看入会，再由用户动作开麦/摄像头/屏幕；使用 SDK 实际回调更新 UI。主持人、参会者、观察身份、外部流和会后档案的权限不可混用。平台缺配置、缺权限、不支持、未实现和未验证分别报告。

## 按真实任务开始

读取 [实战对接配方](references/recipes.md)，从直播闭环、录像查询与下载、RTC 正式入会或 SDK 平台接入开始。每个配方给出调用顺序、最小权限、准确字段、结果判定与失败处理。完整目录和机器契约是必需材料；缺少 `references/openapi.json`、`api-operations.md`、`contract.json` 或 `guides/` 时，这个目录是不完整的，不能当可交付 Skill 使用。

## 完成对接的判断

交付自己的配置说明、依赖版本、调用封装、业务授权规则和可复现验收。至少验证所需动作的成功、无权限、过期/吊销、超时后结果未知和异步失败。播放需要真正收到媒体；RTC 发布需另一台设备确认声音/画面，录制需实际回放/下载，退出后检查采集与连接释放。自动测试、编译、现场运行和真机验收分别说明；仅有预览或 mock 不等于完成。不得记录完整 Token、一次性票据、私聊内容或带票据 URL。