Zoom integration planner

何时使用

当你手上有一个Zoom 集成或应用的想法，需要把它变成一份可执行的实施方案——包含架构概览、所需 Zoom 产品/API、认证与 scope 清单、分阶段交付计划、风险清单和「下一步立刻做什么」时使用。本技能是先想清楚再动手的规划层，不替代具体编码。

典型触发：

• 「我想做一个能 X 的 Zoom 应用/集成，怎么落地？」
• 需要一份带阶段、风险、最小验证交付物的 build plan。
• 还没定接口面（REST / Webhook / 各类 SDK / MCP），需要先做架构决策。

不该用于：

• 接口面与认证都已敲定、只差写代码 —— 直接进对应实现。
• 非 Zoom 的平台集成 —— 本技能的接口面/scope 知识是 Zoom 专属的。
• 只想问单一 OAuth grant 或某个 SDK 的具体用法 —— 那是认证/SDK 子技能的职责，不必走整套规划。

步骤

固定 6 步，从「想法」推导到「最小可验证架构」：

1. 抓住目标用户流程与成功判据 —— 先写清「谁、在哪、要完成什么」，以及怎样算成功。流程不清就别往下选型。
2. 选最小正确的 Zoom 接口面 + 必要支撑服务 —— 只选刚好够用的主接口面，再叠加真正必需的配件，不要超配。
3. 定义认证要求：app 类型、OAuth grant、最小 scope、账户假设 —— 先确认「谁授权谁、哪个租户模型」，再选 grant，再按精确流程取最小 scope。
4. 把实现拆成阶段：原型 → 核心集成 → 可靠性 → 上线。每阶段有明确出口。
5. 尽早点名硬风险：OAuth 配置、Webhook 验签、SDK 运行环境限制、Marketplace 评审、MCP 客户端约束。
6. 以「能证明架构成立的最小交付物」收尾 —— 给出那个最小可验证切片，而不是一上来就铺全功能。

指令

接口面决策框架（选最小正确的那个，再叠配件）：

问题类型	主选 Zoom 接口面
后端确定性自动化、账户管理、报表、定时任务	REST API
事件投递到你的后端	Webhooks 或 WebSockets
把 Zoom 会议嵌入你的应用	Meeting SDK
做完全自定义的视频体验	Video SDK
在 Zoom 客户端内构建	Zoom Apps SDK
AI Agent 对 Zoom 数据做工具化工作流	Zoom MCP
实时媒体提取 / 会议 bot	RTMS（必要时叠 Meeting SDK）
电话场景	Phone
联络中心 / 虚拟坐席	Contact Center / Virtual Agent

选型护栏：

• 用户要的是 Zoom 会议语义时，不要推 Video SDK。
• 用户要的是完全自定义会话产品时，不要推 Meeting SDK。
• 不要用「纯 MCP」替代后端确定性自动化。
• 既要稳定系统动作又要 AI 驱动发现时，优先 REST API + Zoom MCP 混合。

认证决策顺序（顺序错了会返工）：

1. 先定 app 模型与「谁授权谁、哪个租户」，再选 grant —— 不要先选 grant 再补 actor。
2. 按精确用户流程取最小 scope，不要在确认流程前申请大范围 scope。
3. 明确 token 存储与刷新行为；刷新成功后必须存新返回的 refresh token，不可复用旧的。
4. 上述都清楚后，再钻进最深的参考文档。

产出物清单（方案的固定骨架）：

• 架构概览
• 所需 Zoom 产品与 API
• 认证与 scope 检查清单
• 分阶段交付计划
• 风险、待解问题、立刻可做的下一步

示例

输入：/plan-zoom-integration 一个内部工具，会议结束后自动把录制和参会名单同步到我们的数据库

输出（方案骨架）：

架构概览：事件驱动后端。Zoom Webhook（meeting.ended / recording.completed）
  → 你的接收端验签 → 调 REST API 拉录制与参会者 → 落库。无需任何 SDK。
所需 Zoom 产品/API：Webhooks（事件）+ REST API（recordings、past meeting participants）。
认证与 scope：Server-to-Server OAuth（无终端用户授权，账户级）；
  最小 scope：cloud_recording:read:admin、meeting:read:admin（按精确接口收敛）。
  S2S token 短期有效，按需取，不复用过期 token。
交付阶段：
  1) 原型：手动触发，跑通「拉一场会议录制并落库」。
  2) 核心集成：接 Webhook，端到端验签 → 拉取 → 入库。
  3) 可靠性：重试、幂等、Webhook 重放与签名校验、失败告警。
  4) 上线：权限收敛、监控、（如需对外分发）走 Marketplace 评审。
风险：Webhook 验签实现易错；录制可能延迟产出需重试；S2S scope 配置需在
  Marketplace app 后台精确开通。
下一步（最小可验证交付物）：手动调一次 REST「列出某会议录制」并成功落一条库，
  以此证明数据链路与认证成立，再接 Webhook。

注意事项

• 接口面宁少勿多：先选最小正确面，再叠真正必需的配件；超配会拖慢交付、扩大攻击面与 scope 范围。
• 认证顺序不可颠倒：actor/租户 → grant → scope → token 生命周期。颠倒（先选 grant、先要大 scope）是最常见返工源。
• refresh token 一次性语义：刷新成功后用新返回的 token 覆盖旧的；复用旧 refresh token 会导致认证失败，且别把它误判成 API 故障——先查 app 配置。
• Webhook 必须验签：事件接收端要校验来源签名，并处理重放/重复投递（配合幂等）。
• 对外分发要预留 Marketplace 评审：上架有审核周期与合规要求，放进上线阶段而非临门一脚。
• 以最小可验证架构收尾：方案的价值在于先用一个小切片证明架构成立，而不是先把全功能画满。

互见

• requires：无（本技能是其它 Zoom 实现技能的上游规划层）。
• related：zoom-approach-selector —— 接口面选型的专用决策技能，规划中第 2 步可下钻；zoom-oauth-setup —— 认证与 scope 的深入实现。
• combines_with：zoom-meeting-app-builder、zoom-bot-builder —— 方案敲定后按选定接口面进入具体构建；webhook-receiver-hardening —— 落实事件验签与幂等。

---

采编自 anthropics/knowledge-work-plugins（Apache-2.0 许可证），原技能 plan-zoom-integration（zoom-plugin）。本条为适配中文「技能大典」的重写版，保留其 6 步规划工作流、接口面决策框架与选型护栏（取自 choose-zoom-approach）、认证决策顺序与「刷新后存新 refresh token」等约束（取自 setup-zoom-oauth）、四阶段交付（原型/核心/可靠性/上线）、硬风险清单（OAuth/Webhook 验签/SDK 环境/Marketplace 评审/MCP）及「以最小可验证架构收尾」的核心理念。