knowledge-work-plugins Zoom 插件：Video SDK Triage Intake 实践，把“Video SDK 不工作”变成结构化诊断清单

knowledge-work-plugins Zoom 插件：Video SDK Triage Intake 实践，把“Video SDK 不工作”变成结构化诊断清单

【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins

当开发者报告“Video SDK isn't working”却给不出任何上下文时，该问什么、先问什么、如何把模糊描述快速收敛到可排查的假设，就是 Triage Intake（分诊收集）要解决的问题。本篇以 triage-intake.md 的五个问题域为骨架——平台与 UI 选型、会话基础信息、鉴权（Signature/JWT）、症状分桶、日志与最小复现——完整继承原文档的检查项，并结合本仓库 zoom-plugin 中的鉴权参考、生命周期参考、5 分钟预检 Runbook、Token 契约测试规范与 SDK 日志指南，逐项展开每一项“该问什么”背后的技术依据、典型错误模式与验证手段，读完即可把一份 30 秒的模糊求助转成一张可直接开工的诊断表。

为什么 Video SDK 分诊需要先确认“走对路”

在 SKILL.md 中，Video SDK 技能被定位为“完全自定义视频会话产品”的参考技能，其开头就设了一条硬性路由护栏（Hard Routing Guardrail）：

• 用户要自定义实时视频行为（topic/session 加入、自定义渲染、attach/detach）时，路由到 Video SDK；
• 不要为 Video SDK 的加入流程改用 REST 会议接口；
• Video SDK不使用 Meeting ID、join_url，也不使用 Meeting SDK 的meetingNumber、passWord等字段。

triage-intake.md 的使用场景正是“有人报告 Video SDK 不工作但上下文不足”，而 RUNBOOK.md 第 9 节 “Wrong-Path Detector” 给出了一个极快的判据：如果对方实现里出现了meetingNumber或join_url，或者通过/v2/meetings创建资源来加入，说明根本不在 Video SDK 流程里。因此实际分诊时，五个问题域之前还隐含第零步：确认对方确实在 Video SDK 路径上（Video SDK 会话是即时创建的，topic 就是会话标识，不需要预先创建会议），避免用 Meeting SDK 的排查思路去套 Video SDK 的问题。

第一步：平台与 UI 选型（Platform + UI Choice）

原文档要求确认两件事：

1. 平台：web|react-native|flutter|ios|android|windows|linux；
2. UI 方案：
   • UI Toolkit（@zoom/videosdk-zoom-ui-toolkit预制组件）
   • Custom UI（直接使用 SDK API 自建界面）

为什么这两项必须最先问？因为仓库里的多个高频故障都直接取决于这两个答案：

• UI Toolkit 的平台可用性并不对称。根据 ui-toolkit.md 的平台表：Web（@zoom/videosdk-zoom-ui-toolkit）、iOS、Android 都有 UI Toolkit，而React Native 与 Flutter 没有，只能用 SDK + 自建 UI。问清平台+UI 方案，才能立刻排除“你用的平台根本没有该组件”这类无效排查。
• UI Toolkit 会代管大部分生命周期与渲染。session-lifecycle.md 明确提示：使用 UI Toolkit 时，让 Toolkit 管理生命周期/渲染；若需要“自定义”能力（如截图、屏幕共享检测），要先确认 Toolkit 是否暴露该能力，还是必须落到底层 SDK API。同一个“视频不显示”症状，在 Toolkit 方案下查组件配置与featuresOptions，在 Custom UI 方案下则查事件监听与 attach/detach 逻辑——排查路径完全不同。
• Web 平台还要追问分发方式。RUNBOOK.md 第 5 节指出 npm 与 CDN 的全局对象不同（ZoomVideovsWebVideoSDK.default），CDN/ES Module 场景下还有 SDK 未加载完成的竞态问题；SKILL.md 给出了对应的waitForSDK()守卫示例。此外 CDN 模式下source.zoom.us会被广告拦截器拦截，官方建议自托管 SDK 文件。

分诊时的落点：拿到平台与 UI 方案后，就能选择对应平台目录下的排查文档（如 web/troubleshooting/common-issues.md、android/troubleshooting/common-issues.md 等各平台troubleshooting/common-issues.md）。

第二步：会话基础信息（Session Basics，可直接复制粘贴）

原文档要求收集（并强调“Copy/Paste”级别的精确性）：

• topic/sessionName（所有加入者必须完全一致）
• userName
• password/sessionPasscode（如使用）
• SDK 版本 + UI Toolkit 版本（如适用）

这组字段不是泛泛的“环境信息”，而是 Video SDK 会话模型的直接映射：

• 会话即时创建，topic 即会话 ID。SKILL.md 的 “Session Creation Model” 说明：Video SDK 会话不需要预创建，第一个参与者带着某个topic加入时会话才被创建；所有用同一topic字符串加入的人进入同一会话；没有类似 Zoom Meetings 的数字会议号。由此推出第一个高频故障：topic 拼写不一致 → “Session not found” / 加到不同会话，这正是 troubleshooting.md 中 Join 失败表格的第一条。
• 这组字段与后端 Token 契约一一对应。token-contract-test-spec.md 定义了跨平台（Android、iOS、macOS、Unity）共用的后端 token 契约：输入为sessionName（必填）、userName（必填）、roleType（可选）、expirationSeconds（可选），输出为token（短时效 JWT）、expiresAt、回显的sessionName。分诊时要求对方“复制粘贴”这些值，本质就是核对客户端实际 join 参数与 token 声明（claim）是否一致。
• UI Toolkit 场景下字段名略有差异。ui-toolkit.md 的joinSession配置使用videoSDKJWT、sessionName、userName、sessionPasscode，并要求配套提供 SDK/Toolkit 版本号（原文档中“SDK version + UI Toolkit version”的由来）。收集版本号的价值在于：不同版本的行为差异（如 CDN 全局对象名、事件名）是跨版本排查的第一变量。

第三步：鉴权（Signature/JWT）

原文档的两个确认点：确认签名/JWT 是服务端生成的；如 join 失败，确认过期时间与服务器时钟偏移。仓库文档把这两点展开成了一套完整的 JWT 规范（见 authorization.md）：

JWT 声明结构

Claim	说明
app_key	你的 SDK Key
tpc	Topic（会话名），任意字符串；相同tpc加入同一会话
role_type	0 = 参与者，1 = 主持人
user_identity	（可选）唯一用户标识
iat	签发时间戳
exp	过期时间戳

两个关键点值得在分诊时追问：

1. 主持/副主持身份完全由 JWT 的role_type决定，而不是运行期 API：第一个以role_type: 1加入者是 Host，之后以 1 加入的是 Co-host；只有 Host/Co-host 的client.leave(true)能结束整个会话。这解释了为什么“我无法结束会议”这类问题要先看 token 里签的是什么角色，而不是查客户端代码。
2. 短时效 token 的标准做法：exp设为当前时间 +10 秒（安全窗口极短），iat设为当前时间 −7200 秒（2 小时前），以满足 Zoom 对exp - iat >= 2 小时的要求，同时保证 token 只在“生成后立刻 join”的语义下有效。官方 Node.js 示例（HS256）：

const jwt = require('jsonwebtoken'); function generateSignature(sdkKey, sdkSecret, topic, role, userIdentity) { const iat = Math.floor(Date.now() / 1000) - 7200; // 2 hours ago const exp = Math.floor(Date.now() / 1000) + 10; // 10 seconds from now const payload = { app_key: sdkKey, tpc: topic, role_type: role, user_identity: userIdentity || '', iat: iat, exp: exp }; return jwt.sign(payload, sdkSecret, { algorithm: 'HS256' }); }

安全红线（原文“Confirm signature/JWT is generated server-side”的依据）：SDK Secret 绝不可出现在客户端代码；token 短时效；生成前校验用户身份。

分诊时对应“过期/时钟偏移”的两种典型症状

token-contract-test-spec.md 的 Failure diagnostics 给出了精确对照：

• token expired立刻出现→ 优先怀疑服务端时钟漂移（clock skew）或 TTL 配置错误，而非客户端问题；
• 仅某一个平台join failed/auth→ 对比该平台对 claim payload 的处理方式与 SDK 版本差异；
• 原生平台正常、Unity 失败→ 核对 wrapper 对 join/token 的预期是否与当前版本一致。

此外 sdk-logs-troubleshooting.md 提醒一个反直觉细节：错误码 0 在很多 SDK 枚举里表示“成功”而非错误——“join 失败”报告里附带error 0时，往往根本不是 join 失败。

第四步：症状分桶（Symptom Bucket）

原文档把模糊抱怨归入五个桶：join 失败 / 视频不渲染或自视黑屏（常为浏览器/设备权限或生命周期顺序问题）/ 音频不启动或音频路由变化 / 屏幕共享问题 / 性能、延迟、卡顿（浏览器差异很重要）。仓库文档为每个桶提供了可执行的排查依据：

桶 1：Join 失败

troubleshooting.md 的对照表：

错误	可能原因	解决
Invalid signature	JWT 格式错误或已过期	服务端重新生成签名
Session not found	Topic 不匹配	校验 topic 完全一致
Auth failed	SDK 凭据无效	检查 SDK Key/Secret

配合第二步的 topic 精确一致性与第三步的 claim 核对，这个桶基本可以被“会话基础信息 + 鉴权”两步完全覆盖。

桶 2：视频不渲染 / 自视黑屏

这是 session-lifecycle.md 重点攻击的“API 调用顺序”问题。标准顺序为：

1. 创建 client（createClient()）
2. init()
3. join()
4. join 之后再getMediaStream()
5. 基于事件启动音视频并渲染
6. 离开会话并清理

最常见的静默失败是在join()之前调用getMediaStream()（返回 undefined，无报错）。SKILL.md 中给出了正误对照代码，以及事件驱动渲染的强制要求：

// 远端视频开启/关闭时 attach/detach client.on('peer-video-state-change', async (payload) => { const { action, userId } = payload; if (action === 'Start') { const el = await stream.attachVideo(userId, VideoQuality.Video_360P); container.appendChild(el); } else { await stream.detachVideo(userId); } }); client.on('user-added', (payload) => { /* 检查 bVideoOn */ }); client.on('user-removed', (payload) => { stream.detachVideo(payload.userId); });

注意原文档强调“使用attachVideo()而不是renderVideo()”（旧 API 心智模型是常见迁移错误）。RUNBOOK.md 的快速决策树给出了两个高命中判据：“没有媒体流”→ 查生命周期顺序（getMediaStream必须在join之后）；“只有本地视频正常”→ 缺少事件驱动的远端 attach 流程。自视黑屏则优先查相机权限与“相机被其他应用占用”（见 troubleshooting 的 No Video 表）。

桶 3：音频不启动 / 音频路由变化

troubleshooting.md 的 No Audio 表：听不到别人 → 确认调用过startAudio()；别人听不到自己 → 麦克风权限（应在 join 前申请）；回声 → 扬声器反馈，改用耳机。Web 侧可用navigator.permissions.query检查 mic/camera 权限状态、用enumerateDevices()核对设备枚举（见 sdk-logs-troubleshooting.md 的调试片段）。

桶 4 与桶 5：屏幕共享 / 性能与延迟

Web 特有的高频项在 troubleshooting 的 Web-Specific 表中：SharedArrayBuffer 报错 → 服务端缺少 COOP/COEP 头；性能问题 → 视频流过多，降低参与方数量或分辨率。原文档特意标注“浏览器差异很重要”，与此对应——分诊时必须问清浏览器 + OS + 控制台报错，以及是否配置了 SAB/crossOriginIsolated（见下一步）。屏幕共享在 Custom UI 下属于独立能力路径（SKILL.md 的 UI Toolkit 章节也提示：需要确认 Toolkit 是否暴露屏幕共享检测，还是得用底层 SDK API）。

第五步：日志 + 最小复现（Logs + Minimal Repro）

原文档要求：最小复现步骤、SDK 日志（见仓库的 SDK 日志指南）、Web 平台需补充浏览器 + OS + 控制台报错 + 是否配置了 SAB/crossOriginIsolated。仓库中 sdk-logs-troubleshooting.md 提供了各平台可复制的日志开启方式与收集规范：

各平台开启日志

// Web：verbose 日志 ZoomMtg.setLogLevel('verbose'); // 或 Video SDK client.init('en-US', 'CDN', { debug: true });

// iOS let initParams = MobileRTCSDKInitParams() initParams.enableLog = true initParams.logFilePrefix = "zoom_sdk"

// Android val initParams = ZoomSDKInitParams().apply { enableLog = true logSize = 5 // MB }

// Windows / macOS / Linux 桌面 initParam.enableLogByDefault = true; initParam.logFilePrefix = L"zoom_sdk";

默认日志位置：iOS 在 App 的 Documents 目录、Android 在 App 的 files 目录、Windows 在%APPDATA%\ZoomSDK\、macOS 在~/Library/Logs/ZoomSDK\、Linux 在工作目录。

Web 平台的 Web Tracking ID

Video SDK Web 侧排查的关键凭据是 Web Tracking ID：打开 DevTools → Network，找到以lsdk?topic...开头的请求，查看响应头中的x-zm-trackingid（形如v=2.0;clid=us04;rid=WEB_abc123xyz...）。提单/求助时附上该 ID 与日志，可显著缩短支持侧定位时间。

最小复现与快速探针

“最小复现步骤”不是客套要求，RUNBOOK.md 的 Quick Probes 把它拆成了四个可打钩的探针：签名端点返回合法 JWT payload、同一topic下两个用户 join 成功、startAudio()/startVideo()调用返回成功、浏览器日志无 mixed-content/CORS 拦截。仓库还给了可直接复制的验证命令：

# 1) 验证签名/token 端点有响应 curl -sS -i "$VIDEO_SDK_BASE_URL/api/signature" # 2) 验证应用页面可达 curl -sS -i "$VIDEO_SDK_BASE_URL"

预期结果是 token 端点返回 JSON、应用路由返回 HTML——任何一步失败都能把“视频不工作”收敛到网络/后端层，而不是陷入 SDK 内部。

提交支持材料清单

按 sdk-logs 指南与 troubleshooting.md 的 “Getting Support” 节，一份合格的最小复现包应包含：SDK 版本与平台、日志文件、复现步骤、错误码（先确认 0 是否代表成功）。sdk-logs-troubleshooting.md 还附了跨平台错误码参考（0 = 成功、1 = 通用错误、2 = 参数无效、3 = token 无效、4 = 超时，以及 Windows 特有的 8 / 100000400 等），分诊时可据此先做一轮“错误码翻译”，避免把成功误报为失败。

分诊速查表：问题 → 核对项 → 仓库依据

分诊步骤（原文档骨架）	要问清什么	典型故障与判据	仓库依据
平台 + UI 选型	7 平台之一；Toolkit 还是 Custom UI	RN/Flutter 无 UI Toolkit；CDN vs npm 全局对象不同	ui-toolkit.md、RUNBOOK.md
会话基础信息	topic 精确一致、userName、passcode、SDK/Toolkit 版本	topic 不一致 → Session not found	SKILL.md、token-contract-test-spec.md
鉴权	是否服务端生成 JWT；过期时间/时钟偏移	立即 expired → 时钟漂移；error 0 = 成功	authorization.md
症状分桶	join / 渲染 / 音频 / 共享 / 性能	getMediaStream必须在join后；缺 peer-video-state-change 监听 → 只有本地视频	session-lifecycle.md、troubleshooting.md
日志 + 最小复现	复现步骤、各平台日志、浏览器 + OS + SAB/crossOriginIsolated、Web Tracking ID	SAB 报错 → 缺 COOP/COEP 头	sdk-logs-troubleshooting.md

这套清单的价值在于它把“Video SDK isn't working”从一句抱怨变成了五个可独立回答的问题：每一步的回答都能直接裁剪掉一半假设（错误路径、UI 方案误判、topic 不一致、JWT 时钟、生命周期顺序、浏览器能力位），并在收集完五步信息后，让排查者带着版本、claim 内容、日志与复现步骤进入 zoom-plugin 各平台目录下的深度文档继续诊断。

【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins