Zoom 插件查询路由实战用 zoom-general 编排多技能链Query Routing Playbook 全解析【免费下载链接】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本文档系统讲解 knowledge-work-plugins 仓库中 query-routing-playbook.md 所定义的查询路由方法论如何将一条复杂的开发者问题分解为selected_skills、execution_order、assumptions、next_actions四要素并通过zoom-general作为编排层分派到各专业技能。读完本文你将掌握 Zoom 平台 8 类核心技能的路由规则、5 步排序策略、标准化交接契约Handoff Contract以及低置信度场景的澄清提问范式并能基于仓库中的 TypeScript 实现把路由逻辑落地为可运行的分类器与链式调度代码。一、路由思想的定位zoom-general 是编排层而非实现层在 Zoom 插件技能体系中zoom-general被明确定位为跨产品的路由/编排层routing/orchestration layer。其核心约束是一条硬性规则如果存在对应的专业技能specialized skill不要在zoom-general中实现产品级业务逻辑。这一设计理念在 SKILL.md 的元信息中得到了印证zoom-general被标记为user-invocable: false的跨产品参考技能它不直接面向用户调用而是在工作流明确后提供共享的平台指引、App 模型对比、认证上下文、scope 与 Marketplace 考量以及 API-vs-MCP 路由决策。也就是说zoom-general的职责是分类classify、挑选主技能pick primary、挂接副技能chain secondary、按需澄清clarify最终把具体实现交给对应的专业 SKILL。从仓库的配套文档 interview-answer-routing.md 可以归纳出这条链路的精炼表述在zoom-general中按产品意图、平台、集成模式对查询分类路由到最小化的专业技能集合按zoom-general→ 认证 → 核心产品 → 事件/媒体的顺序执行若语义模糊在锁定技能链之前先问一个消歧问题。二、目标产物把复杂查询转成四要素契约路由的最终目标不是选一个技能而是把一条复杂开发者查询转换为结构化的四要素输出要素含义示例selected_skills本次任务需要参与的技能集合[zoom-general, zoom-oauth, zoom-meeting-sdk, zoom-webhooks]execution_order技能的执行先后顺序与 selected_skills 对应的有序排列assumptions路由时隐含的前提假设需要下游确认embedded meeting experience requirednext_actions移交实现层后的下一步行动清单[confirm OAuth scopes, implement auth/token flow, ...]这一四要素结构对应仓库 routing-implementation.md 中定义的RouteDecision接口其中还额外包含confidence置信度、rationale决策依据、needsClarification待澄清问题与warnings守护警告使路由结果可审计、可追溯。三、路由规则表查询信号 → 专业技能playbook 给出了 8 条核心路由规则这是整个路由体系的骨架。查询中出现左侧的信号时应路由到对应的专业技能查询信号Query signal路由到技能Route to skill原因WhyOAuth、scopes、S2S、token 策略zoom-oauth认证与授权设计Meetings/users/recordings/reports API 操作zoom-rest-api服务端 Zoom 资源管理嵌入完整 Zoom 会议/网络研讨会zoom-meeting-sdk会议运行时集成构建自定义视频会话体验zoom-video-sdk自定义媒体 UX 运行时通过 HTTP 接收事件回调zoom-webhooks事件生命周期通知需要更低延迟的事件流zoom-websockets持久化实时事件传输直播音视频/转写流接入zoom-rtms实时媒体与转写管线App 运行在 Zoom 客户端内部zoom-apps-sdk客户端内 App 模型与 API这 8 条规则在仓库中的实现是信号词检测。以 routing-implementation.md 中的detectSignals为例每个信号对应一组关键词oauth信号命中词oauth、pkce、authorization code、account_credentials、token refreshrestApi信号命中词rest api、/v2/、create meeting、list users、s2s oauthwebhooks信号命中词webhook、x-zm-signature、event subscription、crc即 webhook URL 校验的 Challenge-Responsertms信号命中词rtms、real-time media streams、live transcript stream、audio stream。信号检测采用hasAny(q, words)的子串匹配方式q为小写归一化后的原始查询实现简单、行为确定同一查询永远得到同一路由结果。3.1 技能覆盖面从 8 类到 23 类playbook 的 8 条规则是最小核心集仓库 SKILL.md 的 Choose Your Path 矩阵将路由面扩展到了 23 个技能包括zoom-meeting-sdk-web-component-viewMeeting SDK Component View 自定义 Web UI、scribeAI Services Scribe 转写、zoom-cobrowse-sdk协同浏览、contact-center、virtual-agent、phone、zoom-team-chat、rivet-sdk、probe-sdk、zoom-ui-toolkit、zoom-mcp及其 Whiteboard 子面等。完整的信号定义可见 routing-implementation.md 中 20 个布尔字段的Signals接口涵盖meetingEmbed、meetingCustomUi、customVideo、whiteboardMcp、zoomApps、preflight、cobrowse等扩展信号。四、排序策略Sequencing5 步构建最小技能链playbook 定义了构建技能链的 5 步顺序核心思想是先分类、再认证、选一个主运行时、按需挂事件/媒体、保持链最小以zoom-general起步先做 triage 与架构判断triage and architecture需要受保护资源访问时追加zoom-oauth凡是涉及 token 获取、刷新、scope 授权的场景认证技能都是前置依赖选择唯一的主运行时/API 技能在zoom-meeting-sdk、zoom-video-sdk、zoom-rest-api三者中选其一作为主体实现按需求追加事件/媒体技能zoom-webhooks、zoom-websockets、zoom-rtms依据是否涉及事件通知或实时媒体来决定保持链最小化没有明确需求时绝不额外追加技能Keep the chain minimal; do not add extra skills without explicit need。这一排序逻辑在仓库中有两处代码佐证SKILL.md 的buildChain简化版先取主技能再按oauth/webhooks信号依次追加zoom-oauth与zoom-webhooks并用includes去重routing-implementation.md 的完整版buildChain使用SetSkillId去重且包含更细的链式规则例如主技能为 Component View 时自动追加zoom-meeting-sdk-weboauth、restApi、mcp、webhooks、websockets、phone、teamChat、virtualAgent任一命中即追加zoom-oauth命中rivet信号时追加rivet-sdkNode.js 快速脚手架框架webhooks或websockets命中时追加zoom-rest-api事件通道常与 REST 资源管理配对mcp与restApi同时命中时同时追加zoom-rest-api与zoom-mcp混合架构最后从链中删除主技能本身避免冗余chain.delete(primary)。4.1 SDK 与 REST 的硬性守护Hard Stop排序过程中最容易犯的错误是把嵌入会议路由成 REST 的join_url分发。仓库 SKILL.md 给出了 4 条硬性路由矩阵用户意图正确路径禁止路由到在 App UI 中嵌入 Zoom 会议zoom-meeting-sdk纯 REST 的join_url流程为真实 Zoom 会议构建自定义 Web UIzoom-meeting-sdk-web-component-viewzoom-video-sdk构建自定义视频 UI/会话 Appzoom-video-sdkMeeting SDK 或 REST 会议链接获取浏览器加入链接/管理会议资源zoom-rest-apiMeeting SDK 加入实现守护规则routing guardrails补充了三条边界用户要求 SDK 嵌入/加入行为时必须停留在 SDK 路径提示词同时出现meeting与custom UI/video/layout/embed时优先zoom-meeting-sdk-web-component-view只有用户在构建自定义会话产品而非 Zoom 会议时才使用zoom-video-sdk。routing-implementation.md 的pickPrimarySkill与validateDecision正是这些守护的代码化validateDecision会对会议嵌入意图但主技能不是 Meeting SDK自定义会议 UI 但主技能不是 Component ViewcustomVideo 与 meetingCustomUi 同时命中等冲突情况生成warnings而pickPrimarySkill中的优先级注释明确写着SDK 嵌入/自定义视频请求不应回退到 REST。4.2 API 与 MCP 的混合路由决策当问题涉及 AI 智能体时路由还需要在确定性 REST 与 AI 驱动的 MCP 之间做选择。仓库 apis-vs-mcp-routing.md 提供了决策矩阵主要需求路由说明确定性自动化、配置、报表、定时任务、严格重试/错误处理zoom-rest-api直接控制请求、重试与幂等AI 交互、动态工具发现、AI Companion 工作流、外部 AI 互操作zoom-mcpAgent 通过 MCP 按上下文选择工具高并发生产自动化 AI 助手工作流zoom-rest-api zoom-mcp核心动作留在 APIMCP 暴露精选工具面三种典型链路模式Pattern AAPI-only 确定性后端zoom-oauth→zoom-rest-api→可选zoom-webhooksPattern BMCP-first AI 工具流zoom-oauth→zoom-mcp语义会议搜索、摘要、录制/转写与工具调用Pattern C混合企业 AI 架构zoom-rest-api负责供给/策略/定时摄取zoom-webhooks或zoom-websockets负责事件摄取zoom-mcp面向 AI Companion 或外部 Agent 暴露精选工具。注意 MCP 的传输约束Zoom 远程 MCP 服务器走 Streamable HTTP/SSE典型客户端包括 Claude 与 VS Code端点模型是实例/集群级共享的不要按租户自定义 MCP 端点。zoom-mcp是父级 MCP 入口Whiteboard 专属 MCP 请求应路由到zoom-mcp/whiteboard。4.3 Webhooks 与 WebSockets 的选择两者都接收事件通知但技术取向不同详见 SKILL.md 的对比表维度webhookszoom-websockets连接方式HTTP POST 到你的端点持久 WebSocket延迟较高较低安全性需要公网端点无暴露端点配置复杂度较简单较复杂适用场景大多数场景实时、安全敏感场景五、交接契约Handoff Contract路由结果的标准化输出playbook 给出了路由完成后的标准化 JSON 契约。当一条查询被判定为需要嵌入会议体验 服务端事件端点时完整交接契约如下{ selected_skills: [ zoom-general, zoom-oauth, zoom-meeting-sdk, zoom-webhooks ], execution_order: [ zoom-general, zoom-oauth, zoom-meeting-sdk, zoom-webhooks ], assumptions: [ embedded meeting experience required, server-side event endpoint available ], next_actions: [ confirm OAuth scopes, implement auth/token flow, implement runtime integration, implement event consumer and verification ] }仓库 routing-implementation.md 中的RouteDecision接口将契约扩展为包含confidence、rationale、needsClarification、warnings的完整结构其示例输出{ primarySkill: zoom-meeting-sdk, chainedSkills: [zoom-oauth, zoom-rest-api, zoom-webhooks], confidence: 0.9, rationale: [ primaryzoom-meeting-sdk, signals{\meetingEmbed\:true,\restApi\:true,\webhooks\:true,...}, chainedzoom-oauth,zoom-rest-api,zoom-webhooks ], needsClarification: [], warnings: [ mixed SDK REST intent; keep SDK as primary and use REST only for resource workflows ] }置信度计算confidenceFromSignals按命中信号数量分档命中 ≥4 个信号为 0.9≥2 个为 0.781 个为 0.650 个为 0.5。路由的确定性要求是同一规范化提示词必须产生同一路由结果Routing should be deterministic for the same normalized prompt。5.1 交接后的落地可执行的实现片段契约交付后下游实现可以复用仓库中的成熟代码骨架。以创建会议 处理 webhook OAuth 刷新三合一场景为例meeting-webhooks-oauth-refresh-orchestration.md 给出了四组件设计TokenBroker集中式 access token 缓存 刷新锁refreshingPromise 去重并发刷新并在过期前 60 秒触发提前刷新MeetingService基于 broker 调用POST /v2/users/{userId}/meetings遇到401时forceRefresh()后重试一次WebhookIngressx-zm-signatureHMAC-SHA256 签名校验 endpoint.url_validation的 plainToken 应答 事件入队ProjectionWorker把meeting.started、meeting.ended、meeting.participant_joined/left等事件投影为会议状态。其中 webhook 签名校验的核心逻辑为v0:${timestamp}:${rawBody}经 HMAC-SHA256 摘要后与v0${hash}比对见 webhooks/SKILL.md 的 Quick Start。webhook 的事件订阅要在 Marketplace App 层面配置不要在运行时把启用订阅当成逐请求的 API 步骤来建模除非对应产品有专门的 admin API。另一个可复用骨架是 automatic-skill-chaining-rest-webhooks.md 中的chooseRestWebhookChain与 Node.js 最小可运行示例含getAccessTokenS2S token 换取、会议创建、签名验证、状态投影并明确了失败处理底线429/5xx带抖动重试、4xx 业务错误不盲目重试、webhook 入队后立即返回200、按event_id或(event, event_ts, meeting_uuid)复合键幂等去重、周期性 REST 轮询对账修复漏掉的事件。六、歧义处理Ambiguity Handling低置信度先问一个问题playbook 对歧义处理的原则是如果置信度低在最终路由前只问一个聚焦的问题ask one focused question。仓库给出了两个标准澄清提问Do you need embedded Zoom meetings, or a fully custom video session UI?嵌入真实 Zoom 会议还是完全自定义的视频会话 UIIs webhook latency acceptable, or do you require persistent low-latency events?webhook 延迟可否接受还是需要持久低延迟事件在代码实现中routeComplexQuery的needsClarification规则为mcp与restApi信号同时命中时追问Do you want deterministic REST API automation, AI-agent MCP tooling, or a hybrid of both?随后按回答分别路由到zoom-rest-api、zoom-mcp或zoom-rest-api zoom-mcp主技能回落为zoom-general即低信号/未知提示词时追问Do you need SDK embed behavior, API resource automation, or event ingestion?错误处理期望Error Handling Expectations同时明确了三点低信号提示词路由到zoom-general并带一个澄清问题冲突信号不硬失败而是产生 warnings 并保留守护规则相同规范化提示词必须确定性路由。七、完整示例路由Linux 会议机器人playbook 给出的实战示例是一个典型的多技能链查询为Build a Linux bot that joins meetings, auto-creates meetings, streams transcript, and tracks lifecycle events.构建一个 Linux 机器人加入会议、自动创建会议、流式获取转写、追踪生命周期事件。推荐链Recommended chainzoom-general → zoom-oauth → zoom-rest-api → zoom-meeting-sdk → zoom-rtms → zoom-webhooks为什么这样路由Why技能职责zoom-rest-api会议供给provisioning自动创建会议zoom-meeting-sdk运行时加入与控制runtime join/controlzoom-rtms实时转写/媒体流live transcript/media streamzoom-webhooks生命周期事件通知lifecycle notifications这条链完整覆盖了查询中的四个动词joinsMeeting SDK、auto-createsREST API、streams transcriptRTMS、tracks lifecycle eventsWebhooks。其中 Linux 平台的 Meeting SDK 加入实现可进一步参考仓库 meeting-sdk/linux 技能RTMS 侧则需要预先在 Marketplace App 中启用 Event Subscription 并订阅meeting.rtms_started/meeting.rtms_stopped事件、添加meeting:read:meeting_audio等 scope详见 rtms/SKILL.md。RTMS 遵循两阶段 WebSocket模型Signaling 控制面 Media 数据面webhook 必须立即返回200再处理事件否则 Zoom 重试会造成重复连接。八、如何在自己的系统中落地这套路由如果要把本 playbook 的方法论复用到自己的 Agent 或路由服务中仓库 routing-implementation.md 提供了一个可直接参考的 TypeScript 实现模板运行前提为 Node.js 18、TypeScript 5输入为自由格式提示词输出为确定性的RouteDecision契约。整体落地路径建议如下定义SkillId联合类型覆盖仓库全部 23 个技能标识含zoom-mcp/whiteboard这样的子面实现detectSignals按产品意图维护信号词表注意小写归一化与子串匹配实现pickPrimarySkill按守护优先级排序——Component View Meeting SDK Web/原生 Video SDK 其他产品技能 REST/MCP zoom-general兜底实现buildChain用Set去重按认证、事件、混合架构规则追加副技能实现validateDecision与confidenceFromSignals产生 warnings 与置信度产出交接契约将结果序列化为 JSONprimarySkill、chainedSkills、confidence、rationale、needsClarification、warnings供下游执行层消费。需要说明的是当前仓库为只读知识库以上代码骨架用于理解与本地复刻实现运行时所需的 Zoom 账号、Marketplace App 与 OAuth 凭据Client ID/Secret需在 Zoom 侧单独准备。延伸阅读本 playbook 源文件query-routing-playbook.md路由完整实现TypeScript 契约routing-implementation.md面试速答版路由要点interview-answer-routing.mdREST Webhook 自动技能链与可运行示例automatic-skill-chaining-rest-webhooks.md会议 Webhook OAuth 刷新编排meeting-webhooks-oauth-refresh-orchestration.mdAPI 与 MCP 路由决策apis-vs-mcp-routing.mdzoom-general 技能总览与全技能索引SKILL.md各专业技能入口zoom-oauth、zoom-rest-api、zoom-meeting-sdk、zoom-video-sdk、zoom-webhooks、zoom-websockets、zoom-rtms、zoom-apps-sdk、zoom-mcp【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考