CopilotKit Teams 应用包构建实战从pnpm package到 sideload 安装的完整指南【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit本指南以 examples/teams/appPackage 目录为线索系统讲解如何将一个 CopilotKit Teams 机器人打包成可上传到 Microsoft Teams 的 sideload 应用包一条命令完成 Bot ID 注入、图标校验与自动生成、manifest 校验以及 ZIP 打包并在 Teams 客户端中安装使用。读完本文你将掌握appPackage目录的完整结构、package.mjs构建脚本的内部逻辑以及从环境变量到最终appPackage.zip的完整数据流。背景什么是 Teams 应用包Microsoft Teams 安装自定义应用sideload依赖一个“应用包”app package它本质上是一个 ZIP 压缩包内含一份描述应用元数据与能力的manifest.json以及供 Teams 展示使用的两张图标彩色图与轮廓图。CopilotKit 的 Teams 示例机器人由copilotkit/channels及其 Teams 适配器驱动可参考 examples/teams/README.md同样遵循这一流程——构建出应用包后在 Teams 中依次进入Apps → Manage your apps → Upload a custom app上传即可完成机器人的注册与安装。该目录内所有文件见下表文件作用manifest.json应用清单模板botId为占位符构建时注入真实值color.png彩色图标192×192缺失时自动生成 CopilotKit 紫色占位图outline.png轮廓图标32×32缺失时自动生成白色圆形占位图package.mjs零依赖的构建脚本即pnpm package的执行入口appPackage.zip构建产物已被 gitignore不入库一键构建pnpm package在examples/teams目录下执行一条命令即可完成整个打包流程pnpm package该命令由 examples/teams/package.json 中的package: node appPackage/package.mjs脚本承接构建完成后在appPackage/下生成appPackage.zip。从源码看脚本是完全依赖无关的dependence-free要求 Node ≥ 18内部的 PNG 写入器与 ZIP 构造器均为纯 JS 实现不引入任何 npm 开发依赖——这意味着在任何具备 Node 环境的 CI 或本地机器上都能直接运行。构建过程依次完成三件事Bot ID 注入、图标校验、manifest 校验。只要有一项不满足脚本会打印具体错误并给出修复提示后以非零码退出而不是默默产出坏包。Bot ID 注入如何解析 Microsoft App IDpackage.mjs的核心逻辑对应 package.mjs负责把真实的 Microsoft 应用 ID 注入到manifest.json的bots[0].botId字段中。解析顺序为读取examples/teams/.env文件若存在用parseEnv解析出键值对以.env的内容为底、process.env覆盖其上环境变量优先级更高依次尝试MICROSOFT_APP_ID→CLIENT_ID→clientId取第一个非空值若三者皆为空则回退读取 manifest 中已存在的真实 ID即botId不再是REPLACE_WITH_MICROSOFT_APP_ID占位符的情况两者都没有则报错退出。这意味着提交到仓库的 manifest 可以始终保留占位符你的真实 ID 只存在于本地.env或部署环境变量中彻底避免把凭据硬编码进版本库。注入前脚本还会用正则GUID_RE/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i严格校验格式非 GUID 的值会被拒绝。文档特别强调这里必须是绑定到 Azure Bot 的 Entra 应用的Application (client) ID一个 GUID而不是 client secret 或 secret 的 ID。此外脚本还会顺带把同一个 ID 写入manifest.webApplicationInfo.id见 package.mjs。源码注释解释了原因Web Application Info 必须指向同一个 Entra 应用Teams 才能向它授予资源专属RSC的ChannelMessage.Read.Group权限——这是渠道内读取消息所依赖的权限模型。图标校验与自动生成Teams 对应用图标有严格的尺寸要求脚本通过requireIcon函数逐一校验见 package.mjscolor.png必须为192×192outline.png必须为32×32。校验逻辑并非简单查文件是否存在而是解析 PNG 的 IHDR 块读取真实像素尺寸只解析头部、不完整解码。遇到以下三种情况分别处理文件缺失→ 自动生成占位图并提示不是合法 PNG→ 报错退出尺寸不符→ 报错退出并提示“替换为正确尺寸的 PNG或删除后让其自动生成”。自动生成的占位图采用 CopilotKit 主题色#5B5FC7RGBA 为[91, 95, 199, 255]与 manifest 中的accentColor一致彩色图是整张紫色 192×192 图片轮廓图则是 32×32 透明背景上的白色圆形。PNG 由脚本内置的 8-bit RGBA 写入器生成含 IHDR/IDAT/IEND chunk 与 CRC-32 校验因此即使你删除了这两张图标pnpm package依然能成功运行——这就是 README 中“regenerated if deleted”的实现保证。Manifest 校验构建前脚本会完整读取并JSON.parsemanifest见 package.mjs校验内容为manifest 文件存在且是合法 JSON存在bots[0]条目Teams 机器人 manifest 必须有bots数组。校验通过后脚本将解析出的 Bot ID 写入内存中的 manifest 副本再与两张图标一起打包。打包确定性的 ZIP 输出打包阶段见 package.mjs把三份文件按如下结构压入 ZIPmanifest.json根目录缩进 2 空格格式化后写入color.pngoutline.png。zip函数使用 ZIP 规范中的 local file header、central directory 与 EOCD 结构手写实现并固定使用 1980-01-01 时间戳dosTime 0, dosDate 0x21保证输出产物确定性——相同输入构建出的 zip 逐字节一致便于缓存与校验。成功后脚本打印✅ Built appPackage.zip (botId ID)并再次提示上传路径。manifest.json 模板详解examples/teams/appPackage/manifest.json 是构建的输入模板其中bots[0].botId与webApplicationInfo.id均为占位符REPLACE_WITH_MICROSOFT_APP_ID由构建脚本替换。完整内容如下{ $schema: https://developer.microsoft.com/en-us/json-schemas/teams/v1.25/MicrosoftTeams.schema.json, manifestVersion: 1.25, version: 1.0.0, id: c3da40e5-a328-46aa-bef2-cbbaa61496e3, developer: { name: CopilotKit, websiteUrl: https://copilotkit.ai, privacyUrl: https://copilotkit.ai/privacy, termsOfUseUrl: https://copilotkit.ai/terms }, name: { short: CopilotKit Bot, full: CopilotKit Teams Bot }, description: { short: A CopilotKit assistant for Microsoft Teams., full: A Microsoft Teams bot powered by the CopilotKit Channels Teams integration. }, icons: { color: color.png, outline: outline.png }, accentColor: #5B5FC7, supportsChannelFeatures: tier1, bots: [ { botId: REPLACE_WITH_MICROSOFT_APP_ID, scopes: [personal, team, groupChat], supportsFiles: true, isNotificationOnly: false } ], permissions: [identity, messageTeamMembers], validDomains: [], webApplicationInfo: { id: REPLACE_WITH_MICROSOFT_APP_ID, resource: https://graph.microsoft.com }, authorization: { permissions: { resourceSpecific: [ { name: ChannelMessage.Read.Group, type: Application } ] } } }模板中几个值得注意的字段bots[0].scopespersonal1:1 私聊、team团队与groupChat群聊三端可用bots[0].supportsFiles: true声明机器人支持文件。在 1:1 私聊中文件会直接内联送达机器人在频道/群聊中 Teams 不会把文件发给机器人需要走 Microsoft Graph 拉取详见 examples/teams/README.md 的 “Files and charts” 一节authorization.permissions.resourceSpecific声明 RSC 应用权限ChannelMessage.Read.Group与webApplicationInfo配合让团队所有者即可授权而不必每次找租户管理员manifestVersion: 1.25示例机器人渲染原生 Teams 图表Adaptive Card chart element的前提是 manifest 版本 ≥ 1.25模板已满足。在 Teams 中安装应用包构建完成后按以下步骤 sideload 安装打开 Microsoft Teams 客户端进入Apps → Manage your apps点击Upload a custom app选择examples/teams/appPackage/appPackage.zip上传。需要特别注意的是安装应用包只是把机器人注册进 Teams。机器人要真正回复消息还必须让微软能触达你的服务——在 Azure Bot 资源上把messaging endpoint设置为https://your-host/api/messages并且部署时保证该地址公网可达。完整的注册与部署链路Entra 应用注册、Azure Bot 资源创建、Teams 频道启用、messaging endpoint 配置在 examples/teams/README.md 与 Teams 指南 中有逐步说明。常见报错与修复指引package.mjs对每种失败场景都给出了明确的错误信息与修复提示整理如下报错场景原因修复方式manifest.json is not valid JSON模板被手工编辑破坏恢复合法 JSON或重新从仓库检出模板No Microsoft App id found环境变量与 manifest 中都无有效 ID在examples/teams/.env设置MICROSOFT_APP_ID或clientId值为 Entra 应用的 Application (client) IDMicrosoft App id ... is not a GUID填入了 secret 或非 GUID 值使用 Application (client) IDGUID而非 secretcolor.png must be 192×192/outline.png must be 32×32自定义图标尺寸不符替换为精确尺寸的 PNG或删除该文件让其自动生成占位图manifest.json has no bots[0] entrymanifest 缺少bots数组补全bots数组及botId字段实践要点小结一条命令出包pnpm package在 examples/teams 下执行产物为appPackage/appPackage.zipID 永不入库Bot ID 通过MICROSOFT_APP_ID/CLIENT_ID/clientIdenv 或.env注入仓库中始终是占位符图标免维护192×192 彩色图与 32×32 轮廓图缺失时自动生成 CopilotKit 紫色占位图品牌化时只需替换为精确尺寸的 PNG产物确定性零依赖、固定时间戳的 ZIP 构建适合纳入 CI 流水线安装 ≠ 可用上传应用包后还需配置 Azure Bot 的 messaging endpoint机器人才能真正收发消息。如需在租户中验证渠道文件拉取的 Graph 权限链路在向组织管理员申请同意之前可参考 scripts/verify-graph-channel.ts 的独立验证脚本它以 app-only 令牌完成“读频道消息 → 从 SharePoint 下载文件”的完整链路验证与机器人实际行为一致。【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CopilotKit Teams 应用包构建实战：从 `pnpm package` 到 sideload 安装的完整指南
CopilotKit Teams 应用包构建实战从pnpm package到 sideload 安装的完整指南【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit本指南以 examples/teams/appPackage 目录为线索系统讲解如何将一个 CopilotKit Teams 机器人打包成可上传到 Microsoft Teams 的 sideload 应用包一条命令完成 Bot ID 注入、图标校验与自动生成、manifest 校验以及 ZIP 打包并在 Teams 客户端中安装使用。读完本文你将掌握appPackage目录的完整结构、package.mjs构建脚本的内部逻辑以及从环境变量到最终appPackage.zip的完整数据流。背景什么是 Teams 应用包Microsoft Teams 安装自定义应用sideload依赖一个“应用包”app package它本质上是一个 ZIP 压缩包内含一份描述应用元数据与能力的manifest.json以及供 Teams 展示使用的两张图标彩色图与轮廓图。CopilotKit 的 Teams 示例机器人由copilotkit/channels及其 Teams 适配器驱动可参考 examples/teams/README.md同样遵循这一流程——构建出应用包后在 Teams 中依次进入Apps → Manage your apps → Upload a custom app上传即可完成机器人的注册与安装。该目录内所有文件见下表文件作用manifest.json应用清单模板botId为占位符构建时注入真实值color.png彩色图标192×192缺失时自动生成 CopilotKit 紫色占位图outline.png轮廓图标32×32缺失时自动生成白色圆形占位图package.mjs零依赖的构建脚本即pnpm package的执行入口appPackage.zip构建产物已被 gitignore不入库一键构建pnpm package在examples/teams目录下执行一条命令即可完成整个打包流程pnpm package该命令由 examples/teams/package.json 中的package: node appPackage/package.mjs脚本承接构建完成后在appPackage/下生成appPackage.zip。从源码看脚本是完全依赖无关的dependence-free要求 Node ≥ 18内部的 PNG 写入器与 ZIP 构造器均为纯 JS 实现不引入任何 npm 开发依赖——这意味着在任何具备 Node 环境的 CI 或本地机器上都能直接运行。构建过程依次完成三件事Bot ID 注入、图标校验、manifest 校验。只要有一项不满足脚本会打印具体错误并给出修复提示后以非零码退出而不是默默产出坏包。Bot ID 注入如何解析 Microsoft App IDpackage.mjs的核心逻辑对应 package.mjs负责把真实的 Microsoft 应用 ID 注入到manifest.json的bots[0].botId字段中。解析顺序为读取examples/teams/.env文件若存在用parseEnv解析出键值对以.env的内容为底、process.env覆盖其上环境变量优先级更高依次尝试MICROSOFT_APP_ID→CLIENT_ID→clientId取第一个非空值若三者皆为空则回退读取 manifest 中已存在的真实 ID即botId不再是REPLACE_WITH_MICROSOFT_APP_ID占位符的情况两者都没有则报错退出。这意味着提交到仓库的 manifest 可以始终保留占位符你的真实 ID 只存在于本地.env或部署环境变量中彻底避免把凭据硬编码进版本库。注入前脚本还会用正则GUID_RE/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i严格校验格式非 GUID 的值会被拒绝。文档特别强调这里必须是绑定到 Azure Bot 的 Entra 应用的Application (client) ID一个 GUID而不是 client secret 或 secret 的 ID。此外脚本还会顺带把同一个 ID 写入manifest.webApplicationInfo.id见 package.mjs。源码注释解释了原因Web Application Info 必须指向同一个 Entra 应用Teams 才能向它授予资源专属RSC的ChannelMessage.Read.Group权限——这是渠道内读取消息所依赖的权限模型。图标校验与自动生成Teams 对应用图标有严格的尺寸要求脚本通过requireIcon函数逐一校验见 package.mjscolor.png必须为192×192outline.png必须为32×32。校验逻辑并非简单查文件是否存在而是解析 PNG 的 IHDR 块读取真实像素尺寸只解析头部、不完整解码。遇到以下三种情况分别处理文件缺失→ 自动生成占位图并提示不是合法 PNG→ 报错退出尺寸不符→ 报错退出并提示“替换为正确尺寸的 PNG或删除后让其自动生成”。自动生成的占位图采用 CopilotKit 主题色#5B5FC7RGBA 为[91, 95, 199, 255]与 manifest 中的accentColor一致彩色图是整张紫色 192×192 图片轮廓图则是 32×32 透明背景上的白色圆形。PNG 由脚本内置的 8-bit RGBA 写入器生成含 IHDR/IDAT/IEND chunk 与 CRC-32 校验因此即使你删除了这两张图标pnpm package依然能成功运行——这就是 README 中“regenerated if deleted”的实现保证。Manifest 校验构建前脚本会完整读取并JSON.parsemanifest见 package.mjs校验内容为manifest 文件存在且是合法 JSON存在bots[0]条目Teams 机器人 manifest 必须有bots数组。校验通过后脚本将解析出的 Bot ID 写入内存中的 manifest 副本再与两张图标一起打包。打包确定性的 ZIP 输出打包阶段见 package.mjs把三份文件按如下结构压入 ZIPmanifest.json根目录缩进 2 空格格式化后写入color.pngoutline.png。zip函数使用 ZIP 规范中的 local file header、central directory 与 EOCD 结构手写实现并固定使用 1980-01-01 时间戳dosTime 0, dosDate 0x21保证输出产物确定性——相同输入构建出的 zip 逐字节一致便于缓存与校验。成功后脚本打印✅ Built appPackage.zip (botId ID)并再次提示上传路径。manifest.json 模板详解examples/teams/appPackage/manifest.json 是构建的输入模板其中bots[0].botId与webApplicationInfo.id均为占位符REPLACE_WITH_MICROSOFT_APP_ID由构建脚本替换。完整内容如下{ $schema: https://developer.microsoft.com/en-us/json-schemas/teams/v1.25/MicrosoftTeams.schema.json, manifestVersion: 1.25, version: 1.0.0, id: c3da40e5-a328-46aa-bef2-cbbaa61496e3, developer: { name: CopilotKit, websiteUrl: https://copilotkit.ai, privacyUrl: https://copilotkit.ai/privacy, termsOfUseUrl: https://copilotkit.ai/terms }, name: { short: CopilotKit Bot, full: CopilotKit Teams Bot }, description: { short: A CopilotKit assistant for Microsoft Teams., full: A Microsoft Teams bot powered by the CopilotKit Channels Teams integration. }, icons: { color: color.png, outline: outline.png }, accentColor: #5B5FC7, supportsChannelFeatures: tier1, bots: [ { botId: REPLACE_WITH_MICROSOFT_APP_ID, scopes: [personal, team, groupChat], supportsFiles: true, isNotificationOnly: false } ], permissions: [identity, messageTeamMembers], validDomains: [], webApplicationInfo: { id: REPLACE_WITH_MICROSOFT_APP_ID, resource: https://graph.microsoft.com }, authorization: { permissions: { resourceSpecific: [ { name: ChannelMessage.Read.Group, type: Application } ] } } }模板中几个值得注意的字段bots[0].scopespersonal1:1 私聊、team团队与groupChat群聊三端可用bots[0].supportsFiles: true声明机器人支持文件。在 1:1 私聊中文件会直接内联送达机器人在频道/群聊中 Teams 不会把文件发给机器人需要走 Microsoft Graph 拉取详见 examples/teams/README.md 的 “Files and charts” 一节authorization.permissions.resourceSpecific声明 RSC 应用权限ChannelMessage.Read.Group与webApplicationInfo配合让团队所有者即可授权而不必每次找租户管理员manifestVersion: 1.25示例机器人渲染原生 Teams 图表Adaptive Card chart element的前提是 manifest 版本 ≥ 1.25模板已满足。在 Teams 中安装应用包构建完成后按以下步骤 sideload 安装打开 Microsoft Teams 客户端进入Apps → Manage your apps点击Upload a custom app选择examples/teams/appPackage/appPackage.zip上传。需要特别注意的是安装应用包只是把机器人注册进 Teams。机器人要真正回复消息还必须让微软能触达你的服务——在 Azure Bot 资源上把messaging endpoint设置为https://your-host/api/messages并且部署时保证该地址公网可达。完整的注册与部署链路Entra 应用注册、Azure Bot 资源创建、Teams 频道启用、messaging endpoint 配置在 examples/teams/README.md 与 Teams 指南 中有逐步说明。常见报错与修复指引package.mjs对每种失败场景都给出了明确的错误信息与修复提示整理如下报错场景原因修复方式manifest.json is not valid JSON模板被手工编辑破坏恢复合法 JSON或重新从仓库检出模板No Microsoft App id found环境变量与 manifest 中都无有效 ID在examples/teams/.env设置MICROSOFT_APP_ID或clientId值为 Entra 应用的 Application (client) IDMicrosoft App id ... is not a GUID填入了 secret 或非 GUID 值使用 Application (client) IDGUID而非 secretcolor.png must be 192×192/outline.png must be 32×32自定义图标尺寸不符替换为精确尺寸的 PNG或删除该文件让其自动生成占位图manifest.json has no bots[0] entrymanifest 缺少bots数组补全bots数组及botId字段实践要点小结一条命令出包pnpm package在 examples/teams 下执行产物为appPackage/appPackage.zipID 永不入库Bot ID 通过MICROSOFT_APP_ID/CLIENT_ID/clientIdenv 或.env注入仓库中始终是占位符图标免维护192×192 彩色图与 32×32 轮廓图缺失时自动生成 CopilotKit 紫色占位图品牌化时只需替换为精确尺寸的 PNG产物确定性零依赖、固定时间戳的 ZIP 构建适合纳入 CI 流水线安装 ≠ 可用上传应用包后还需配置 Azure Bot 的 messaging endpoint机器人才能真正收发消息。如需在租户中验证渠道文件拉取的 Graph 权限链路在向组织管理员申请同意之前可参考 scripts/verify-graph-channel.ts 的独立验证脚本它以 app-only 令牌完成“读频道消息 → 从 SharePoint 下载文件”的完整链路验证与机器人实际行为一致。【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考