Microsoft Teams

连接 Microsoft Teams 机器人，让聊天和频道可以启动并继续 Beeuni 会话。

Microsoft Teams 是一种渠道：在 Teams 聊天或频道中 @提及机器人即可启动一个会话，智能体会在原处回复并实时显示进度。它遵循与 Slack 相同的会话、身份和凭据规则；本页介绍 Teams 特有的内容。

每个项目都可以连接 Teams。无需启用功能标志。

连接

有两种方式，均可在项目的 Connectors → Channels 页面操作：

• 一键连接（托管）。 Teams 租户管理员点击 Add to Teams，登录并授予同意。Beeuni 会自动将应用发布到组织的 Teams 应用目录——无需构建或粘贴任何内容。之后，该行会显示 Add to Teams（指向 Teams 客户端的深层链接），任何人都可以将机器人添加到聊天或频道。Beeuni 发布新版应用时，请参阅更新应用。

• 使用自己的机器人。 点击 Use your own Microsoft Teams app，进入三步向导：注册 Azure Bot，使用其应用 ID、客户端密钥和租户 ID 将其连接到 Beeuni，然后下载生成的应用包并上传到 Teams。若要使用自己注册的机器人，请选择此方式。

  操作顺序很重要。Beeuni 会根据你的应用 ID 构建清单，因此只有完成第 2 步后才能生成应用包——向导会先显示要粘贴到 Azure 的消息传递终结点，然后才会要求你提供其他信息。

CLI 与控制面板的操作相同：

beeuni channels connect --platform teams      # prints the admin-consent URL
beeuni channels status --platform teams        # tenant, catalog, publish state, app version
beeuni channels disconnect --platform teams

更新应用

Beeuni 会逐步为 Teams 应用添加权限。应用版本 1.1.0 添加了 ChannelMessage.Read.Group，智能体需要此权限才能读取频道帖子串。 版本 1.3.0 添加了 ChatMessage.Read.Chat，因此无需提及机器人，群聊中的回复也能继续会话。如果团队仍在使用 1.0.0，则所有帖子串读取都会被拒绝，而且智能体收到的拒绝信息会说明由谁修复。

需要两个人按以下顺序更新应用：

1. Teams 管理员发布更新。 如果组织应用目录中的版本较旧，Channels 页面会显示 Update the Beeuni app in Teams，Teams 行上的按钮则显示 Publish app update。管理员点击该按钮并使用 Microsoft 登录。beeuni channels status --platform teams会显示两个版本，beeuni channels connect --platform teams会显示登录链接。
2. 团队所有者在 Teams 提供更新的每个团队中更新应用。 在 Teams 中打开团队，然后选择 ⋯ → Manage team → Apps，在 Beeuni 应用上选择 Update 并确认。除非更新新增了权限或消息操作，否则 Teams 会自动安装更新；新增权限或消息操作需要团队所有者确认。

Beeuni 会记录每次发布时的应用版本。Beeuni 开始记录版本之前发布的安装会一直显示此通知，直到下次发布。

聊天、频道和提及

• **个人聊天：**每条消息都会发送给机器人。
• **团队频道 / 群聊：**新帖子必须 @提及机器人。此后，在机器人已关联的对话中回复即可继续会话，无需再次提及机器人，就像 Slack 帖子串一样。这需要应用拥有 ChannelMessage.Read.Group（频道）和 ChatMessage.Read.Chat（群聊）权限；租户管理员会在添加应用时授予这些权限。如果添加应用时尚未请求这些权限，请由团队所有者更新应用：参阅更新应用。

每个聊天或频道对话都是独立会话。第一条消息会创建会话；之后的消息会继续该会话，即使沙盒已停止并恢复也一样。如果一个租户连接了多个项目，第一条尚未路由的消息会显示项目选择器，并记住所选项目。在频道中，只有提及机器人的消息才会显示选择器；如果命令涉及项目（例如 /models），则会先询问项目。

在频道中，每个新帖子都会启动独立会话。个人聊天或群聊在整个生命周期内都属于同一段对话，因此会一直使用同一个会话，直到发送 /new。在其后附上消息（/new summarize today's deploys），即可用该消息启动新会话。之前的会话及其完整历史记录仍保留在 Beeuni 中，确认信息也会链接到该会话。

对话名称

Teams 会发送类似 19:…@thread.tacv2;messageid=… 的 ID。Channels 页面和 beeuni channels bindings 会显示人们在 Teams 中看到的名称：

频道消息包含团队 ID，但不包含团队名称，因此 Beeuni 会从 Teams 读取团队和频道名称并保存。团队 General 频道中的帖子会在 Channels 页面下次列出它时显示名称。其他频道中的帖子则会在收到下一条消息时显示名称。在此之前，名称显示为 Channel thread。

谁可以加入会话

每段对话都有加入策略，可在 Teams 中通过 /policy 设置，也可在 Channels 页面设置；Teams 行上的 N channels 会列出所有对话：

• open（默认）——任何关联项目成员都可以加入在此启动的会话。
• approval——会话所有者会收到针对每位新成员的 Approve / Deny 卡片。
• owner——只有启动会话的人可以加入。

在 approval 和 owner 策略下，整个项目在 Beeuni 中也无法查看该会话：只有会话所有者、获准加入的人员以及负责监督会话的账户管理员可以查看。无论采用哪种策略，对审核或批准卡片的操作都会恢复智能体运行。

身份关联

发送者只需通过 /login 关联一次 Beeuni 账户；之后智能体会以该发送者的身份运行，并使用其个人凭据、机密和已连接的应用。未关联账户的发送者，或无权访问该项目的发送者，会收到关联账户或申请访问权限的卡片，而不会启动会话。

登录链接只会出现在只有你能看到的位置：你与机器人的一对一聊天中，或者在频道或群聊中标记为 Only you can see this message 的回复里。链接会将发放对象关联到打开链接的人，因此绝不会出现在其他人能看到的位置。如果 Teams 拒绝发送这条私密回复，机器人会将链接发送到你与机器人的私人聊天中，并在对话中说明情况。只有当你已将应用添加到自己的 Teams 中时，Teams 才允许这样做；否则，卡片会要求你打开与机器人的私人聊天，并在那里发送 /login。如果你在尚未关联账户时于频道中发送了消息，并在 10 分钟内完成关联，该消息就会执行。你在浏览器中完成关联后，机器人会在与你的私人聊天中确认你关联的 Beeuni 账户。

登录链接只能使用一次，并会在 10 分钟后过期。已连接到一个 Beeuni 账户的 Teams 账户无法再连接到另一个账户：请先发送 /logout。如果组织要求进行双重身份验证，Beeuni 会在关联账户前要求你提供第二重验证信息；聊天会使用你通过该验证关联的账户。如果创建链接时未进行双重身份验证，打开链接后会要求你重新关联。

没有访问权限的人提出申请后，Beeuni 会向每位账户所有者和管理员发送请求。已连接 Teams 的人还会在与机器人的私人聊天中收到请求，并看到 在 Beeuni 中审核 按钮。

私人回复

在频道或群聊中，机器人对某个人说的话只有该人可见，并会标记为 只有你能看到此消息，就像 Slack 的临时消息一样：

• 对你所发命令的回复；
• 用于连接账户或申请访问权限的卡片；
• 说明消息为何未运行的内容：加入策略，或你无权使用的代理；
• 在 审批 下，所有者的批准/拒绝卡片，以及向申请人发送的审批决定。

只有当你的消息可以运行时，所有人都会看到 正在处理… 卡片。Teams 会在 24 小时后删除私人回复。如果 Teams 拒绝发送私人回复，机器人就会改为在整个对话中发布卡片。登录链接是例外：此时链接会发送到你与机器人的私人聊天中，绝不会发送到对话中。

角色和权限

聊天本身不带有 Beeuni 凭据，因此每项操作都以执行者所连接的 Beeuni 账户身份运行，并遵循该账户的项目角色。账户所有者和管理员均视为项目经理。

被排除在某个代理使用范围之外的人，无法像在 Beeuni 中一样从 Teams 启动该代理的会话。

命令

在与机器人的聊天中输入这些命令（在频道中，请先 @ 提及机器人）：

对任何消息，选择 ⋯ → 在 Beeuni 中打开，即可打开该对话所属的会话。为自己添加应用后，与机器人的私人聊天会显示与 /home 相同的概览。

模型和密钥

/models 会列出你在此处可以运行的所有模型，和网页模型选择器一样：Beeuni 模型，以及通过提供商 API 密钥或 ChatGPT 订阅使用的模型。每个模型都会说明其付费方式。列表较长时会显示可搜索的下拉菜单。点击模型，或输入 /model <id>；/model default 可恢复为项目默认模型。

可用密钥取决于聊天类型：

• 与机器人的私人聊天 — 你自己的密钥和 ChatGPT 订阅，以及与项目共享的密钥。会话仅你可见。
• 群聊或频道 — 仅限与整个项目共享的密钥。聊天内容是共享的；若在此使用个人密钥，所有人都可以使用一个人的订阅。因此，请改在私人聊天中选择此类模型。

通过密钥运行的模型会使用你有权使用的该提供商的所有密钥，并在遇到速率限制时轮换密钥。此选择从下一条消息开始生效；聊天会保留当前会话。更改正在运行的会话所用模型需要已连接账户；在 owner 或 approval 策略下，只有会话所有者可以更改。若私人聊天中的会话是在此类会话转为私密之前启动的，该会话仍与项目共享：/model 会对此作出说明，/new 则会启动私人会话。请参阅 提供商密钥和成员访问权限。

代理工作期间

代理会在一张卡片中回复：工作时显示步骤，完成后显示回复。长回复会在行末截断，标明内容已截断，并附上 Beeuni 中完整会话的链接。后续消息会等待当前任务完成，然后以单独的卡片显示。安静的步骤不会结束任务；只有运行时报告完成才会结束。

停止运行

代理工作期间，其动态卡片上会显示 停止 按钮。卡片滚出可见范围后，/stop 也可执行相同操作。两者都会在运行时终止任务，而不只是关闭卡片 — 如果任务一直处于打开状态，对话中的下一条消息就会被该任务接收，而不会得到回复。

发送了正在回复的消息的人可以停止任务，任何已获准加入该会话且仍可使用该项目的人也可以。频道中的旁观者不可以；获准加入该聊天较早会话的人也不可以。

文件

代理使用 teams send --file 发送文件。在私人聊天、群聊和频道中，图片会以内嵌形式显示。超大图片在私人聊天中会改为显示 OneDrive 授权卡片，在频道中则会改用团队文件；群聊无法接收超大文件传输。其他文件在私人聊天中会显示授权卡片，分享给团队时则会以 SharePoint 链接的形式发送。代理可以下载和处理收到的文件及粘贴的图片，包括嵌入频道消息正文中的图片。

• 只有当代理根据 读取频道 中的规则可以读取该话题或聊天时，粘贴到频道或群聊中的图片才会被下载。否则，teams download 会回复 403。
• 下载上限为 50 MB，超过时会回复 413。
• teams history 和 teams thread 会列出帖子的内嵌图片（images，每项都是 teams download 的 URL）以及从 SharePoint 分享的文件名称（files）。代理无法下载 SharePoint 文件。

粘贴屏幕截图并提问时，即使该对话所用模型仅支持文本，这一轮也会改用支持读取图片的模型运行 — 不会更改会话的模型选择。若会话所用模型已无法运行（例如密钥已撤销，或聊天无法使用 ChatGPT 订阅），该消息也会以同样方式改用其他模型，而不是直接失败。

问题和表单

智能体使用交互控件提问，而非纯文字。一个问题且最多六个选项时，每个选项对应一个按钮。多个问题、可多选的问题或选项列表较长时，会显示一个表单，并附带填写自定义答案的输入框。日期、时间、数字和开/关选项会使用相应的输入控件。你的回答会作为下一条消息发送给智能体，并标明它回答的是哪个问题。你也可以随时直接输入答案。

审批

智能体需要人在继续之前作出决定时——例如执行有风险的步骤，或批准它想要进行的更改——它会提交一项审核。如果会话是从此对话启动的，决定请求会以卡片的形式显示在这里：包含标题、摘要、风险级别，以及 批准、请求更改 和 拒绝 按钮，还有一个指向 Beeuni 的链接。

卡片带有一个可选的反馈框。你输入的内容会与决定一起保存，并一并传给智能体，因此选择“请求更改”后，不必再多来回一次才能说明你的意思。此反馈框有意设为可选——直接批准不应该还需要输入内容。

对话中的所有人都能看到此卡片，但只有关联了 Beeuni 账户且有权访问该项目的人才能处理它。

主动发消息

除了在收到提问的对话中回复，智能体还可以向该项目中机器人已加入的任何聊天或频道发消息——例如夜间摘要、警报或交接信息。它无法联系从未将它添加进去的对话。

会话无法启动时

Beeuni 会说明问题所在，而不是让你重试，因为大多数启动失败重试也无法解决：沙盒模板已不存在、账户未关联、你无权访问该项目，或工作区额度不足。每条提示都会指出解决方法及相应命令。

如果对话所设定的智能体已被删除或重命名，系统会显示一个选择器：选择一个可用的智能体，然后重新发送消息。列表中只会显示你有权使用的智能体。

读取频道内容

在频道中，机器人只会收到提及它的消息，因此它的会话中没有它被要求查看的讨论内容。需要这些上下文时，智能体会通过应用加入团队时请求的 ChannelMessage.Read.Group 权限，读取提及它的帖子所在的对话串，或频道中的近期帖子。若团队在请求该权限之前就已添加应用，则必须更新应用：参见更新应用。在个人聊天中，每条消息都会进入会话，因此没有更早的内容需要读取。

连接到同一 Microsoft 365 租户的每个项目都使用同一个应用，因此 Beeuni 会确保读取范围仅限于项目自身的对话。在频道中，每条新帖子都属于一个独立的对话：

读取被拒绝时，403 会以 conversation_not_in_project 回复，并附上指出频道或对话串的消息。若租户中有多个项目，而你要读取第一种频道，请在其中提及机器人并选择此项目。

get_channel 和 list_channels 可读取标准频道。只有当智能体根据上述规则有权读取时，才会显示专用或共享频道。get_team、list_members、get_user 和 list_teams 会读取租户目录，不受限制。

限制

Teams 机器人无法添加消息反应或搜索消息——这些 Slack 功能在 Teams 中没有对应功能。智能体只能读取其所在团队中的频道，并且必须遵循读取频道内容中的规则。