尧图网页设计 
Zoom Team Chat 机器人接入 LLM基于 knowledge-work-plugins 的意图识别与消息卡片响应实战指南【免费下载链接】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 仓库中 Zoom Team Chat 技能的 LLM 集成文档为骨架讲解如何用 LLM 解析 Team Chat 消息中的用户意图再调用 Zoom API 或返回富文本消息卡片。读完本文你将掌握bot_notification事件驱动的完整链路消息接收与上下文提取、LLM 意图分类、安全后端动作执行以及结构化响应的消息卡片组装并可直接落地到可运行代码中。一、整体架构LLM 在 Team Chat 机器人中的五步工作流LLM 集成文档定义了一条推荐流程它是整个 AI 机器人能力的核心骨架共五步接收bot_notification事件用户在频道或私聊中通过斜杠命令或直接消息触发机器人Zoom 向你的 Bot Endpoint URL 发送 webhook提取用户文本与频道上下文从事件 payload 中取出用户输入cmd、回执地址toJid、账户标识accountId、用户与频道名称等用 LLM 分类意图将自然语言归类为「会议动作」如创建/查询会议、「帮助」、「状态查询」等意图类型执行安全的后端动作仅对允许的意图调用 Zoom API例如创建会议、列出会议避免 LLM 直接操作高权限能力向 Team Chat 发送结构化响应将 LLM 结果或动作执行结果组装为带标题、字段、按钮的消息卡片发回。该流程对应仓库中 Chatbot Setup 的完整可运行代码骨架以及 Sample Applications 中zoom-chatbot-claude-sample的 LLM 集成模式。下图概括了事件在整个系统中的流转User types /command or DMs bot → Zoom sends webhook → 你的服务器校验签名 ↓ payload.cmd users input 提取用户文本 ↓ LLM 意图分类meeting actions / help / status ↓ 执行安全后端动作create/list meetings 等 ↓ sendChatbotMessage() 发回富文本消息卡片在 SKILL.md 中这一生命周期被概括为User Action → Webhook → Process → Response而 LLM 集成模式则是User Input → Chatbot receives → Call LLM → Send response与本篇五步流程完全对应。二、前置条件先选对 API再搭好机器人LLM 集成建立在 Chatbot API 之上第一步是确认你选择的是正确的集成类型。根据 API Selection GuideZoom Team Chat 提供两套不可互换的 API集成类型消息身份认证方式端点家族Team Chat API用户型以真实登录用户发送User OAuthauthorization_code/v2/chat/users/...Chatbot API机器人型以机器人身份发送Client Credentialsclient_credentials/v2/im/chat/messagesLLM 机器人需要斜杠命令、按钮、表单、webhook 交互等能力这些只有 Chatbot API 支持如果误选了用户型 API认证、scope、端点会全部错位。决策树可以简化为需要富交互消息或 webhook 回调 → 选 Chatbot API只需以用户身份发送纯文本 → 选 Team Chat API。2.1 需要的凭据与环境变量按 Environment Setup 相关说明环境变量规范见 references/environment-variables.md机器人型集成至少需要以下配置变量必填用途获取位置ZOOM_CLIENT_ID是Chatbot 应用 OAuth 身份Marketplace → 应用 → App CredentialsZOOM_CLIENT_SECRET是OAuth token 交换Marketplace → 应用 → App CredentialsZOOM_BOT_JIDChatbot 流程必填机器人标识用于发送消息应用 Chatbot 配置ZOOM_ACCOUNT_IDChatbot 流程目标账户标识App CredentialsZOOM_SECRET_TOKEN推荐webhook 签名校验Event Subscriptions → Secret TokenZOOM_VERIFICATION_TOKEN仅旧应用旧式校验路径旧版应用的遗留字段从源码文档看示例代码chatbot-setup.md同时兼容ZOOM_VERIFICATION_TOKEN这一命名并建议在创建.env后通过dotenv加载杜绝硬编码凭据——security.md 也明确要求「Never hardcode credentials」。2.2 本地启动一个可运行的机器人骨架Chatbot Setup 提供了从零搭建的完整代码核心依赖仅三个npm install express dotenv node-fetch骨架目录结构如下my-zoom-chatbot/ ├── .env ├── .env.example ├── package.json ├── server.js ├── routes/ │ └── webhook.js └── utils/ ├── auth.js ├── chatbot.js └── validation.jsutils/auth.js用client_credentials换取机器人访问令牌POST https://zoom.us/oauth/token请求体grant_typeclient_credentialsAuthorization头为Base64(ClientID:ClientSecret)utils/chatbot.js封装sendChatbotMessage调用POST /v2/im/chat/messages以及纯文本、带按钮、带字段三种消息发送器utils/validation.jsHMAC-SHA256 webhook 签名校验、消息清洗截断至 4096 字符、剔除控制字符、JID 格式校验routes/webhook.js事件分发器覆盖endpoint.url_validation、bot_installed、bot_notification、interactive_message_actions、app_deauthorized。本地调试时用 ngrok 将 4000 端口暴露为 HTTPSngrok http 4000再把生成的https://abc123.ngrok.io/webhook填入 Marketplace 的 Bot Endpoint URL并配置斜杠命令例如/mybot。保存时 Zoom 会发送endpoint.url_validation校验请求你的处理器需要原样返回plainToken并用 Secret Token 计算encryptedTokenHMAC-SHA256校验通过后出现绿色勾选标识。三、接收bot_notification提取用户文本与频道上下文当用户在频道输入斜杠命令或向机器人发送私聊消息时Zoom 会向你的端点发送bot_notification事件。根据 Webhook Events Reference 与 Webhook Architecture该事件的 payload 关键字段如下{ event: bot_notification, payload: { accountId: ..., toJid: channelconference.xmpp.zoom.us, robotJid: botxmpp.zoom.us, userJid: userxmpp.zoom.us, cmd: users input text, // 用户输入斜杠命令之后的全部文本 userName: John Doe, // 发送者 channelName: Marketing, // 频道上下文 timestamp: 1234567890 } }其中三个字段是 LLM 集成中「提取用户文本和频道上下文」步骤的直接来源cmd用户输入是喂给 LLM 的主体文本toJid响应回执地址频道或私聊决定消息发往哪里accountId账户标识调用 Zoom API 时需携带channelName/userName可拼入系统提示词system prompt作为上下文帮助 LLM 理解场景。3.1 处理前的两道安全关卡在把 payload 交给 LLM 之前必须完成两件事细节见 webhooks.md 与 security.md第一校验签名。计算规则为以x-zm-request-timestamp和JSON.stringify(req.body)构造消息v0:{timestamp}:{JSON body}用 Secret Token 做 HMAC-SHA256与x-zm-signaturev0...比对。示例代码在 chatbot-setup.md 的utils/validation.js中完整实现。第二把 payload 视为不可信输入。webhook 可被伪造字段必须校验后再使用。代码中的sanitizeMessage负责清洗消息去控制字符、截断 4096 字符isValidJID负责校验userdomain或channeldomain格式。3.2 先回 200再异步处理LLM 调用通常是秒级操作而 Zoom 期望 webhook 在约 3 秒内返回 200见 webhooks.md 的 Best Practices。因此正确的处理模式是先立即res.status(200).json({ success: true })再在异步流程中执行 LLM 调用与消息发送。这一点在 chatbot-setup.md 的handleBotNotification中有直接体现——先响应、后处理。四、LLM 意图分类从自然语言到结构化动作意图分类是 LLM 集成的核心步骤。以文档给出的三类意图为例意图输入示例对应动作meeting_actions帮我在明天下午 3 点安排一个会议调用会议 API 创建/列出会议help你能做什么返回机器人能力说明卡片status我的会议列表有哪些查询并列出会议状态推荐的实现方式是让 LLM 输出结构化 JSON再由代码根据intent与entities路由到具体处理器而不是直接执行 LLM 返回的任意指令——这也是「执行安全后端动作」的前提。4.1 参考样本中的 LLM 调用模式Sample Applications 中分析了官方zoom-chatbot-claude-sample的 LLM 集成模式。其核心思路是在bot_notification分支中直接把cmd作为用户消息发给 LLM把返回文本作为机器人回复case bot_notification: { const { toJid, cmd, accountId } payload; // 调用 Claude API const response await anthropic.messages.create({ model: claude-sonnet-4-20250514, max_tokens: 1024, messages: [{ role: user, content: cmd }] }); const llmResponse response.content[0].text; // 发回 Zoom Team Chat await sendChatbotMessage(toJid, accountId, { body: [{ type: message, text: llmResponse }] }); }样本还展示了「对话历史」模式用Map按用户维度缓存会话记录再把完整历史作为messages数组传给 LLM实现多轮上下文。对于要求更强的场景可将意图分类与对话历史结合每次请求前先拼接系统提示词包含意图枚举与频道上下文再追加用户消息让 LLM 返回{intent: ..., parameters: {...}}之类的结构化结果。注上例中的模型标识claude-sonnet-4-20250514来自仓库样本分析文档references/samples.md实际使用时请替换为你当前环境可用的模型标识与对应的 API Key样本使用ANTHROPIC_API_KEY环境变量。五、执行安全后端动作调用 Zoom APILLM 只负责「理解意图」真正的副作用动作必须由代码在受控边界内执行。文档明确要求「执行安全后端动作例如create/list meetings」。推荐的做法是维护一张「意图 → 动作」的白名单const ACTION_HANDLERS { meeting_actions: { create: async (params) createZoomMeeting(params), list: async (params) listZoomMeetings(params) }, help: async () buildHelpCard(), status: async () buildStatusCard() };5.1 与事件回环配合的交互设计LLM 集成并非孤立链路它经常与按钮、表单等交互事件配合构成完整闭环。例如机器人先发送一张「确认创建会议」卡片含fields展示会议时间/主题actions提供「确认」「取消」按钮用户点击按钮触发interactive_message_actions事件处理器读取payload.actionItem.value判断决策若要收集更复杂的输入如参会人、议程可用form_field组件配合chat_message.submit事件事件清单见 webhook-events.md。这种「LLM 理解意图 结构化卡片确认 按钮/表单回执」的模式能显著降低 LLM 直接操作高权限 API 的风险。5.2 安全边界要点按 security.md 与 webhooks.md 的约定动作执行阶段还需注意对每个意图做参数校验如会议时间必须是合法的 ISO 时间串把 webhook 输入当作不可信数据仅暴露必要的 Zoom 应用 scopeChatbot API 自动附加imchat:bot见 api-selection.md在 webhook 端点加限流、记录 request/correlation ID但不要记录 token 与 PII创建/列出会议等调用统一走/v2/im/chat/messages之外对应的 Zoom REST 端点使用client_credentials令牌不要与用户 OAuth 令牌混用。六、返回结构化响应组装富文本消息卡片LLM 集成文档强调「respond with rich message cards」。消息卡片是 Chatbot API 的专属能力Team Chat API 不支持其 JSON 结构在 Message Cards Reference 中有完整定义{ content: { head: { text: 标题, sub_head: { text: 副标题 } }, // 可选 body: [ // 组件数组 { type: message, text: 正文内容 }, { type: fields, items: [ { key: 键, value: 值 } ] }, { type: actions, items: [ { text: 按钮, value: action_value, style: Primary } ] } ] } }常用组件包括message纯文本、header带样式的标题、styled_textmarkdown 风格文本、fields键值对、actions按钮样式为Primary/Danger/Default、section带彩色侧边栏的分组、attachments图片与链接、divider、form_field、dropdown。相关长度限制也务必遵守消息文本 4096 字符、按钮文字 40 字符、字段键值各 256 字符、每消息最多 5 个按钮。6.1 一个「会议已创建」的完整卡片示例结合 chatbot-setup.md 中的sendChatbotMessage封装把 LLM 意图与动作执行结果组装成如下卡片const content { head: { text: 会议已创建, sub_head: { text: 由 AI 助手安排 } }, body: [ { type: section, sidebar_color: #10b981, // 绿色 成功 sections: [ { type: message, text: ✅ 会议创建成功 } ] }, { type: fields, items: [ { key: 主题, value: meeting.topic }, { key: 时间, value: meeting.start_time }, { key: 时长, value: ${meeting.duration} 分钟 } ] }, { type: divider }, { type: actions, items: [ { text: 加入会议, value: join_${meeting.id}, style: Primary }, { text: 取消, value: cancel_${meeting.id}, style: Danger } ] } ] }; await sendChatbotMessage(toJid, accountId, content);按钮的value必须设计成可路由的稳定标识如join_123因为点击后interactive_message_actions事件只会回传actionItem.value处理器要据此拆分出动作与实体参考样本中approve_${expenseId}、view_task_${id}的编码习惯见 samples.md。七、完整参考实现将五步流程串成一段可运行代码下面把本篇所有环节——签名校验、消息提取、LLM 意图分类、安全动作执行、卡片响应——整合进一个bot_notification处理器基于 chatbot-setup.md 的routes/webhook.js骨架改造// routes/webhook.js节选 const { verifyZoomWebhookSignature } require(../utils/validation); const { sendChatbotMessage, sendMessageWithButtons } require(../utils/chatbot); async function handleBotNotification(payload, res) { const { toJid, cmd, accountId, userName, channelName } payload; // 立即确认收到避免超时Zoom 期望约 3 秒内 200 res.status(200).json({ success: true }); try { // 步骤 2提取用户文本 频道上下文 const systemPrompt 你是 Team Chat 中的会议助手。当前频道${channelName}用户${userName}。 请判断用户意图并只返回 JSON{intent:meeting_actions|help|status,params:{}}; // 步骤 3LLM 意图分类 const intent await classifyIntent(systemPrompt, cmd); // 参考 4.1 的调用模式 // 步骤 4按白名单执行安全后端动作 switch (intent.intent) { case meeting_actions: const meeting await createZoomMeeting(intent.params); // 创建会议 await sendChatbotMessage(toJid, accountId, buildMeetingCard(meeting)); break; case status: const meetings await listZoomMeetings(accountId); // 列出会议 await sendChatbotMessage(toJid, accountId, buildStatusCard(meetings)); break; default: // help await sendMessageWithButtons(toJid, accountId, { title: 我可以帮你, message: 试试说明天下午 3 点安排会议 或 列出我的会议, buttons: [ { text: 创建会议, value: quick_create, style: Primary }, { text: 查看状态, value: quick_status, style: Default } ] }); } } catch (error) { console.error(Error processing LLM command:, error); // 异步失败不应影响已返回的 200可再发一条错误提示 await sendChatbotMessage(toJid, accountId, { body: [{ type: message, text: 抱歉处理请求时出错请稍后重试。 }] }); } }本地验证时按 chatbot-setup.md 的测试清单逐项确认斜杠命令触发回复、按钮点击回传确认消息同时可用 curl 构造非法签名请求验证「校验失败被拒绝」这一安全行为预期返回Invalid webhook signature这在 webhooks.md 中被标注为正确现象。八、样本仓库与进一步阅读Sample Applications 分析了 10 个官方 Zoom Team Chat 样本应用与本主题直接相关的有两类zoom-chatbot-claude-sampleNode.js中等复杂度Claude API 集成、对话历史跟踪、可选流式响应、上下文管理——是 LLM 集成最直接的参考基线chatbot-nodejs-quickstartNode.js入门级官方教程系列覆盖设置、发消息、事件处理、斜杠命令、交互消息、线程回复等适合作为起点。其余样本如zoom-cohere-chatbot-sample、zoom-cerebras-chatbot-sample同样展示不同 LLM 服务商的接入模式可按需参考其环境变量与请求封装方式。如果需要继续深入推荐按以下顺序阅读本技能的其他文档完整机器人搭建Chatbot Setup事件与 payload 细节Webhook Events、Webhook Architecture消息卡片组件全集Message Cards安全规范Security Best Practices技能总索引SKILL.md常见问题速查现象原因解决办法LLM 响应超时同步处理阻塞了 webhook 响应先返回 200再异步调用 LLM 与发送消息收到「Invalid signature」Secret Token 与 Marketplace 配置不一致核对ZOOM_SECRET_TOKEN/ZOOM_VERIFICATION_TOKEN与 Event Subscriptions 配置卡片显示异常消息卡片 JSON 结构不合法先验证 payload 再发送按钮必须带可路由的valueLLM 返回了无法识别的意图分类提示词不明确在系统提示词中枚举意图与示例并要求只输出结构化 JSON消息未送达Bot JID / Account ID 错误核对ZOOM_BOT_JID与accountId确认使用POST /v2/im/chat/messages以上排查项汇总自 chatbot-setup.md 的 Troubleshooting 表与 webhooks.md 的常见问题清单可在本地开发中逐条对照验证。【免费下载链接】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），仅供参考 Zoom Team Chat 机器人接入 LLM：基于 knowledge-work-plugins 的意图识别与消息卡片响应实战指南
Zoom Team Chat 机器人接入 LLM基于 knowledge-work-plugins 的意图识别与消息卡片响应实战指南【免费下载链接】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 仓库中 Zoom Team Chat 技能的 LLM 集成文档为骨架讲解如何用 LLM 解析 Team Chat 消息中的用户意图再调用 Zoom API 或返回富文本消息卡片。读完本文你将掌握bot_notification事件驱动的完整链路消息接收与上下文提取、LLM 意图分类、安全后端动作执行以及结构化响应的消息卡片组装并可直接落地到可运行代码中。一、整体架构LLM 在 Team Chat 机器人中的五步工作流LLM 集成文档定义了一条推荐流程它是整个 AI 机器人能力的核心骨架共五步接收bot_notification事件用户在频道或私聊中通过斜杠命令或直接消息触发机器人Zoom 向你的 Bot Endpoint URL 发送 webhook提取用户文本与频道上下文从事件 payload 中取出用户输入cmd、回执地址toJid、账户标识accountId、用户与频道名称等用 LLM 分类意图将自然语言归类为「会议动作」如创建/查询会议、「帮助」、「状态查询」等意图类型执行安全的后端动作仅对允许的意图调用 Zoom API例如创建会议、列出会议避免 LLM 直接操作高权限能力向 Team Chat 发送结构化响应将 LLM 结果或动作执行结果组装为带标题、字段、按钮的消息卡片发回。该流程对应仓库中 Chatbot Setup 的完整可运行代码骨架以及 Sample Applications 中zoom-chatbot-claude-sample的 LLM 集成模式。下图概括了事件在整个系统中的流转User types /command or DMs bot → Zoom sends webhook → 你的服务器校验签名 ↓ payload.cmd users input 提取用户文本 ↓ LLM 意图分类meeting actions / help / status ↓ 执行安全后端动作create/list meetings 等 ↓ sendChatbotMessage() 发回富文本消息卡片在 SKILL.md 中这一生命周期被概括为User Action → Webhook → Process → Response而 LLM 集成模式则是User Input → Chatbot receives → Call LLM → Send response与本篇五步流程完全对应。二、前置条件先选对 API再搭好机器人LLM 集成建立在 Chatbot API 之上第一步是确认你选择的是正确的集成类型。根据 API Selection GuideZoom Team Chat 提供两套不可互换的 API集成类型消息身份认证方式端点家族Team Chat API用户型以真实登录用户发送User OAuthauthorization_code/v2/chat/users/...Chatbot API机器人型以机器人身份发送Client Credentialsclient_credentials/v2/im/chat/messagesLLM 机器人需要斜杠命令、按钮、表单、webhook 交互等能力这些只有 Chatbot API 支持如果误选了用户型 API认证、scope、端点会全部错位。决策树可以简化为需要富交互消息或 webhook 回调 → 选 Chatbot API只需以用户身份发送纯文本 → 选 Team Chat API。2.1 需要的凭据与环境变量按 Environment Setup 相关说明环境变量规范见 references/environment-variables.md机器人型集成至少需要以下配置变量必填用途获取位置ZOOM_CLIENT_ID是Chatbot 应用 OAuth 身份Marketplace → 应用 → App CredentialsZOOM_CLIENT_SECRET是OAuth token 交换Marketplace → 应用 → App CredentialsZOOM_BOT_JIDChatbot 流程必填机器人标识用于发送消息应用 Chatbot 配置ZOOM_ACCOUNT_IDChatbot 流程目标账户标识App CredentialsZOOM_SECRET_TOKEN推荐webhook 签名校验Event Subscriptions → Secret TokenZOOM_VERIFICATION_TOKEN仅旧应用旧式校验路径旧版应用的遗留字段从源码文档看示例代码chatbot-setup.md同时兼容ZOOM_VERIFICATION_TOKEN这一命名并建议在创建.env后通过dotenv加载杜绝硬编码凭据——security.md 也明确要求「Never hardcode credentials」。2.2 本地启动一个可运行的机器人骨架Chatbot Setup 提供了从零搭建的完整代码核心依赖仅三个npm install express dotenv node-fetch骨架目录结构如下my-zoom-chatbot/ ├── .env ├── .env.example ├── package.json ├── server.js ├── routes/ │ └── webhook.js └── utils/ ├── auth.js ├── chatbot.js └── validation.jsutils/auth.js用client_credentials换取机器人访问令牌POST https://zoom.us/oauth/token请求体grant_typeclient_credentialsAuthorization头为Base64(ClientID:ClientSecret)utils/chatbot.js封装sendChatbotMessage调用POST /v2/im/chat/messages以及纯文本、带按钮、带字段三种消息发送器utils/validation.jsHMAC-SHA256 webhook 签名校验、消息清洗截断至 4096 字符、剔除控制字符、JID 格式校验routes/webhook.js事件分发器覆盖endpoint.url_validation、bot_installed、bot_notification、interactive_message_actions、app_deauthorized。本地调试时用 ngrok 将 4000 端口暴露为 HTTPSngrok http 4000再把生成的https://abc123.ngrok.io/webhook填入 Marketplace 的 Bot Endpoint URL并配置斜杠命令例如/mybot。保存时 Zoom 会发送endpoint.url_validation校验请求你的处理器需要原样返回plainToken并用 Secret Token 计算encryptedTokenHMAC-SHA256校验通过后出现绿色勾选标识。三、接收bot_notification提取用户文本与频道上下文当用户在频道输入斜杠命令或向机器人发送私聊消息时Zoom 会向你的端点发送bot_notification事件。根据 Webhook Events Reference 与 Webhook Architecture该事件的 payload 关键字段如下{ event: bot_notification, payload: { accountId: ..., toJid: channelconference.xmpp.zoom.us, robotJid: botxmpp.zoom.us, userJid: userxmpp.zoom.us, cmd: users input text, // 用户输入斜杠命令之后的全部文本 userName: John Doe, // 发送者 channelName: Marketing, // 频道上下文 timestamp: 1234567890 } }其中三个字段是 LLM 集成中「提取用户文本和频道上下文」步骤的直接来源cmd用户输入是喂给 LLM 的主体文本toJid响应回执地址频道或私聊决定消息发往哪里accountId账户标识调用 Zoom API 时需携带channelName/userName可拼入系统提示词system prompt作为上下文帮助 LLM 理解场景。3.1 处理前的两道安全关卡在把 payload 交给 LLM 之前必须完成两件事细节见 webhooks.md 与 security.md第一校验签名。计算规则为以x-zm-request-timestamp和JSON.stringify(req.body)构造消息v0:{timestamp}:{JSON body}用 Secret Token 做 HMAC-SHA256与x-zm-signaturev0...比对。示例代码在 chatbot-setup.md 的utils/validation.js中完整实现。第二把 payload 视为不可信输入。webhook 可被伪造字段必须校验后再使用。代码中的sanitizeMessage负责清洗消息去控制字符、截断 4096 字符isValidJID负责校验userdomain或channeldomain格式。3.2 先回 200再异步处理LLM 调用通常是秒级操作而 Zoom 期望 webhook 在约 3 秒内返回 200见 webhooks.md 的 Best Practices。因此正确的处理模式是先立即res.status(200).json({ success: true })再在异步流程中执行 LLM 调用与消息发送。这一点在 chatbot-setup.md 的handleBotNotification中有直接体现——先响应、后处理。四、LLM 意图分类从自然语言到结构化动作意图分类是 LLM 集成的核心步骤。以文档给出的三类意图为例意图输入示例对应动作meeting_actions帮我在明天下午 3 点安排一个会议调用会议 API 创建/列出会议help你能做什么返回机器人能力说明卡片status我的会议列表有哪些查询并列出会议状态推荐的实现方式是让 LLM 输出结构化 JSON再由代码根据intent与entities路由到具体处理器而不是直接执行 LLM 返回的任意指令——这也是「执行安全后端动作」的前提。4.1 参考样本中的 LLM 调用模式Sample Applications 中分析了官方zoom-chatbot-claude-sample的 LLM 集成模式。其核心思路是在bot_notification分支中直接把cmd作为用户消息发给 LLM把返回文本作为机器人回复case bot_notification: { const { toJid, cmd, accountId } payload; // 调用 Claude API const response await anthropic.messages.create({ model: claude-sonnet-4-20250514, max_tokens: 1024, messages: [{ role: user, content: cmd }] }); const llmResponse response.content[0].text; // 发回 Zoom Team Chat await sendChatbotMessage(toJid, accountId, { body: [{ type: message, text: llmResponse }] }); }样本还展示了「对话历史」模式用Map按用户维度缓存会话记录再把完整历史作为messages数组传给 LLM实现多轮上下文。对于要求更强的场景可将意图分类与对话历史结合每次请求前先拼接系统提示词包含意图枚举与频道上下文再追加用户消息让 LLM 返回{intent: ..., parameters: {...}}之类的结构化结果。注上例中的模型标识claude-sonnet-4-20250514来自仓库样本分析文档references/samples.md实际使用时请替换为你当前环境可用的模型标识与对应的 API Key样本使用ANTHROPIC_API_KEY环境变量。五、执行安全后端动作调用 Zoom APILLM 只负责「理解意图」真正的副作用动作必须由代码在受控边界内执行。文档明确要求「执行安全后端动作例如create/list meetings」。推荐的做法是维护一张「意图 → 动作」的白名单const ACTION_HANDLERS { meeting_actions: { create: async (params) createZoomMeeting(params), list: async (params) listZoomMeetings(params) }, help: async () buildHelpCard(), status: async () buildStatusCard() };5.1 与事件回环配合的交互设计LLM 集成并非孤立链路它经常与按钮、表单等交互事件配合构成完整闭环。例如机器人先发送一张「确认创建会议」卡片含fields展示会议时间/主题actions提供「确认」「取消」按钮用户点击按钮触发interactive_message_actions事件处理器读取payload.actionItem.value判断决策若要收集更复杂的输入如参会人、议程可用form_field组件配合chat_message.submit事件事件清单见 webhook-events.md。这种「LLM 理解意图 结构化卡片确认 按钮/表单回执」的模式能显著降低 LLM 直接操作高权限 API 的风险。5.2 安全边界要点按 security.md 与 webhooks.md 的约定动作执行阶段还需注意对每个意图做参数校验如会议时间必须是合法的 ISO 时间串把 webhook 输入当作不可信数据仅暴露必要的 Zoom 应用 scopeChatbot API 自动附加imchat:bot见 api-selection.md在 webhook 端点加限流、记录 request/correlation ID但不要记录 token 与 PII创建/列出会议等调用统一走/v2/im/chat/messages之外对应的 Zoom REST 端点使用client_credentials令牌不要与用户 OAuth 令牌混用。六、返回结构化响应组装富文本消息卡片LLM 集成文档强调「respond with rich message cards」。消息卡片是 Chatbot API 的专属能力Team Chat API 不支持其 JSON 结构在 Message Cards Reference 中有完整定义{ content: { head: { text: 标题, sub_head: { text: 副标题 } }, // 可选 body: [ // 组件数组 { type: message, text: 正文内容 }, { type: fields, items: [ { key: 键, value: 值 } ] }, { type: actions, items: [ { text: 按钮, value: action_value, style: Primary } ] } ] } }常用组件包括message纯文本、header带样式的标题、styled_textmarkdown 风格文本、fields键值对、actions按钮样式为Primary/Danger/Default、section带彩色侧边栏的分组、attachments图片与链接、divider、form_field、dropdown。相关长度限制也务必遵守消息文本 4096 字符、按钮文字 40 字符、字段键值各 256 字符、每消息最多 5 个按钮。6.1 一个「会议已创建」的完整卡片示例结合 chatbot-setup.md 中的sendChatbotMessage封装把 LLM 意图与动作执行结果组装成如下卡片const content { head: { text: 会议已创建, sub_head: { text: 由 AI 助手安排 } }, body: [ { type: section, sidebar_color: #10b981, // 绿色 成功 sections: [ { type: message, text: ✅ 会议创建成功 } ] }, { type: fields, items: [ { key: 主题, value: meeting.topic }, { key: 时间, value: meeting.start_time }, { key: 时长, value: ${meeting.duration} 分钟 } ] }, { type: divider }, { type: actions, items: [ { text: 加入会议, value: join_${meeting.id}, style: Primary }, { text: 取消, value: cancel_${meeting.id}, style: Danger } ] } ] }; await sendChatbotMessage(toJid, accountId, content);按钮的value必须设计成可路由的稳定标识如join_123因为点击后interactive_message_actions事件只会回传actionItem.value处理器要据此拆分出动作与实体参考样本中approve_${expenseId}、view_task_${id}的编码习惯见 samples.md。七、完整参考实现将五步流程串成一段可运行代码下面把本篇所有环节——签名校验、消息提取、LLM 意图分类、安全动作执行、卡片响应——整合进一个bot_notification处理器基于 chatbot-setup.md 的routes/webhook.js骨架改造// routes/webhook.js节选 const { verifyZoomWebhookSignature } require(../utils/validation); const { sendChatbotMessage, sendMessageWithButtons } require(../utils/chatbot); async function handleBotNotification(payload, res) { const { toJid, cmd, accountId, userName, channelName } payload; // 立即确认收到避免超时Zoom 期望约 3 秒内 200 res.status(200).json({ success: true }); try { // 步骤 2提取用户文本 频道上下文 const systemPrompt 你是 Team Chat 中的会议助手。当前频道${channelName}用户${userName}。 请判断用户意图并只返回 JSON{intent:meeting_actions|help|status,params:{}}; // 步骤 3LLM 意图分类 const intent await classifyIntent(systemPrompt, cmd); // 参考 4.1 的调用模式 // 步骤 4按白名单执行安全后端动作 switch (intent.intent) { case meeting_actions: const meeting await createZoomMeeting(intent.params); // 创建会议 await sendChatbotMessage(toJid, accountId, buildMeetingCard(meeting)); break; case status: const meetings await listZoomMeetings(accountId); // 列出会议 await sendChatbotMessage(toJid, accountId, buildStatusCard(meetings)); break; default: // help await sendMessageWithButtons(toJid, accountId, { title: 我可以帮你, message: 试试说明天下午 3 点安排会议 或 列出我的会议, buttons: [ { text: 创建会议, value: quick_create, style: Primary }, { text: 查看状态, value: quick_status, style: Default } ] }); } } catch (error) { console.error(Error processing LLM command:, error); // 异步失败不应影响已返回的 200可再发一条错误提示 await sendChatbotMessage(toJid, accountId, { body: [{ type: message, text: 抱歉处理请求时出错请稍后重试。 }] }); } }本地验证时按 chatbot-setup.md 的测试清单逐项确认斜杠命令触发回复、按钮点击回传确认消息同时可用 curl 构造非法签名请求验证「校验失败被拒绝」这一安全行为预期返回Invalid webhook signature这在 webhooks.md 中被标注为正确现象。八、样本仓库与进一步阅读Sample Applications 分析了 10 个官方 Zoom Team Chat 样本应用与本主题直接相关的有两类zoom-chatbot-claude-sampleNode.js中等复杂度Claude API 集成、对话历史跟踪、可选流式响应、上下文管理——是 LLM 集成最直接的参考基线chatbot-nodejs-quickstartNode.js入门级官方教程系列覆盖设置、发消息、事件处理、斜杠命令、交互消息、线程回复等适合作为起点。其余样本如zoom-cohere-chatbot-sample、zoom-cerebras-chatbot-sample同样展示不同 LLM 服务商的接入模式可按需参考其环境变量与请求封装方式。如果需要继续深入推荐按以下顺序阅读本技能的其他文档完整机器人搭建Chatbot Setup事件与 payload 细节Webhook Events、Webhook Architecture消息卡片组件全集Message Cards安全规范Security Best Practices技能总索引SKILL.md常见问题速查现象原因解决办法LLM 响应超时同步处理阻塞了 webhook 响应先返回 200再异步调用 LLM 与发送消息收到「Invalid signature」Secret Token 与 Marketplace 配置不一致核对ZOOM_SECRET_TOKEN/ZOOM_VERIFICATION_TOKEN与 Event Subscriptions 配置卡片显示异常消息卡片 JSON 结构不合法先验证 payload 再发送按钮必须带可路由的valueLLM 返回了无法识别的意图分类提示词不明确在系统提示词中枚举意图与示例并要求只输出结构化 JSON消息未送达Bot JID / Account ID 错误核对ZOOM_BOT_JID与accountId确认使用POST /v2/im/chat/messages以上排查项汇总自 chatbot-setup.md 的 Troubleshooting 表与 webhooks.md 的常见问题清单可在本地开发中逐条对照验证。【免费下载链接】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），仅供参考