> ## Documentation index
> Fetch the complete documentation index at: https://docs.manyfold.ai/zh/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Teams

> 把 Microsoft Teams 机器人连接到 Manyfold 智能体。

Source: https://docs.manyfold.ai/zh/docs/channels/msteams/

当你希望智能体能从 Microsoft 365 里被找到时，就接入 Microsoft Teams —— 可以在与机器人的单聊里、群聊里，以及它被安装进去的团队频道里对话。配置分三处进行：注册一个 Azure Bot，把它的凭据填进 Manyfold，再上传一个指向该机器人的 Teams 应用包。

## 该渠道支持什么

| 能力 | 支持情况 |
| ---- | -------- |
| 单聊（私信） | 支持；每条消息都会到达智能体。 |
| 群聊与频道 | 支持；默认需要显式 @ 提及。 |
| 提及识别 | 支持，依据 Teams 解析出的身份，而不是显示名称。 |
| 话题（thread） | 支持；每个 Teams 频道话题使用独立会话，回复留在话题内。 |
| 斜杠命令 | 支持，以纯文本形式输入。 |
| 实时进度 | 支持；智能体工作时会不断编辑同一条消息。这是默认行为。 |
| 输入状态提示 | 支持。 |
| 表情回应确认 | 不支持。 |
| 接收文件 | 仅限单聊。在频道或群聊中，Teams 会把文件从机器人收到的内容里剥掉 —— 见[文件](#文件)。 |
| 智能体普通回复中的文件 | 不支持；文件路径以文本形式出现。 |
| 显式的智能体发送文件 | 不支持；Microsoft Teams 不支持 `mf channels send --file`。 |
| 智能体主动发消息 | 支持，目标必须是机器人已在其中的会话。 |
| 历史回填 | 不支持；读取历史消息需要 Microsoft Graph 权限，而那需要租户管理员授权。 |

## 前置条件

- 一个已有的 Manyfold 智能体。
- 一个可以创建机器人资源的 Azure 订阅。
- 向 Microsoft 365 租户上传自定义应用的权限。很多租户默认禁用该功能；Teams 管理员可在**Teams 应用 → 管理应用 → 组织范围的应用设置**中开启。

## 注册 Azure Bot

1. 在 [Azure 门户](https://portal.azure.com/)中创建 **Azure Bot** 资源。
2. **应用类型**选择**单租户**。可以让 Azure 新建一个 Microsoft 应用 ID，也可以指向已有的应用注册。
3. 资源创建完成后，记下三个值 —— Manyfold 里三个都要用：
   - **Microsoft 应用 ID**（即应用注册的客户端 ID）；
   - **租户 ID**；
   - 一个**客户端密钥**，在应用注册的**证书和密码**中创建。密钥值只显示一次，请按机密处理。
4. 打开该机器人资源的**频道**页，添加 **Microsoft Teams** 频道。

消息传送终结点先留空 —— 下一节 Manyfold 会给出这个 URL。

如果不想在门户里逐步点击，[`@microsoft/teams.cli`](https://www.npmjs.com/package/@microsoft/teams.cli) 可以用一条命令完成注册、密钥和初始清单。它目前是预览版，参数在不同版本间会变。

## 在 Manyfold 中创建渠道

1. 进入**设置 → 渠道**，创建一个 **Microsoft Teams** 渠道。
2. 填入机器人应用 ID、客户端密钥和租户 ID。
3. 保存后打开该渠道并点击**注册**。这一步会向 Microsoft 验证凭据、获取机器人身份并激活渠道。
4. 复制渠道的入站 URL，粘贴到 Azure Bot 资源的**设置 → 配置 → 消息传送终结点**。

## 上传 Teams 应用

Azure Bot 本身在 Teams 里还看不到。Teams 需要一个应用包 —— 一个包含清单和两个图标的 zip —— 来指向该机器人。

1. 在渠道页面点击**下载 manifest.json**。它已按你的机器人和该渠道填好。
2. 把它和两个 PNG 图标一起打包成 zip：192×192 的 `color.png` 和 32×32 的 `outline.png`（透明、单色）。三个文件都必须位于 zip 根目录，不能放在子文件夹里。
3. 在 Teams 中进入**应用 → 管理你的应用 → 上传应用 → 上传自定义应用**，选择该 zip。
4. 按需要安装：装给自己用于单聊，或装到某个团队用于其频道。

给机器人发一条私信，确认整条链路已经打通。

## 会话行为

- 单聊按用户各自独立会话。每条消息都会到达智能体，无需提及。
- 在群聊和 Teams 频道中，会话默认按用户区分，除非打开**频道内共享会话**。
- 每个 Teams **频道话题**是独立会话，回复也落回该话题。关闭**话题隔离**则整个频道共用一个会话。单聊和群聊没有话题，该设置在那里不起作用。
- 打开**仅提及时响应**（默认）后，群聊和频道消息必须 @ 提及机器人。判定用的是 Teams 自己解析出的身份，而不是显示名称 —— 所以把自己改名成机器人名字的成员无法伪造提及，而给机器人改名也不会导致失效。
- 对机器人的提及会从智能体看到的文本中删除；对**其他人**的提及则保留并展平成对方姓名，因为那通常是指令的一部分。
- 智能体会先发一条占位消息，工作过程中不断编辑它，最后留下完成的答案。把回复模式设为 **Final** 则只发送最终答案。
- 工作期间会显示输入状态提示，自动续期，回合结束即停止。
- 回复使用 Markdown。粗体、斜体、删除线、链接、无序与有序列表、行内代码、代码块和引用都按原样渲染。标题会转成粗体 —— Teams 会丢掉 `#`，否则标题会显示成普通正文。表格会被包进代码块，以便对齐显示而不是一堆竖线。
- 超过 28,000 字符的回复会拆成多条消息。
- 接收文件仅在单聊可用 —— 见[文件](#文件)。
- 各处都支持输入斜杠命令；命令清单见[会话切换](../session-switching/)。

## 从智能体主动发送

智能体可以用 `mf channels send` 向机器人已在其中的 Teams 会话发消息。要给的是**会话 ID**，不是用户 ID：给一个从未与机器人对话过的人发消息意味着新建会话，而这只有在该用户已安装此应用时才可行 —— 这个前置条件 Manyfold 看不到也无法反馈。也不支持回复某一条历史消息，因为 Teams 是按会话而非按引用消息来组织话题的。任何 Teams 场景都不支持发送文件。投递结果与限制见[从智能体发送](../agent-send/)。

## 访问控制

允许用户和操作员都用 **Entra（Azure AD）对象 ID** 列出 —— 即用户 Entra 资料上的那个 GUID。用户主体名称、邮箱和显示名称一律不做匹配，因为这三者都可能被重新分配给另一个人，而对象 ID 不会。可以在 Azure 门户的 **Microsoft Entra ID → 用户**中查看用户的对象 ID。

**允许的用户 ID** 留空表示租户内任何人都能使用该机器人。**操作员用户 ID** 决定谁可以执行 `/model` 这类智能体级命令；不填操作员则这些命令在 Teams 中被禁用。

**允许的会话 ID** 可以把渠道限定在特定聊天或 Teams 频道。留空表示在应用安装到的任何位置都会响应。

来自其他租户的活动会被直接拒绝，根本不会到达智能体。

## 设置项

| 设置 | 建议 |
| ---- | ---- |
| 允许的用户 ID | 留空表示租户内任何人都能使用；否则填 Entra 对象 ID。 |
| 操作员用户 ID | 留空表示在 Teams 中禁用 `/model` 这类智能体级命令。列出的人可以执行，且即使不在允许列表中也会被放行。 |
| 允许的会话 ID | 留空表示应用装到哪儿就在哪儿响应；否则填会话 ID。从 Teams 深链复制来的值也能用 —— 匹配时会忽略 `;messageid=` 后缀。 |
| 仅提及时响应 | 群聊和频道建议保持开启。单聊不受影响。 |
| 频道内共享会话 | 需要按用户区分上下文时保持关闭；希望频道内所有人共用一个会话时开启。 |
| 话题隔离 | 建议保持开启，让每个 Teams 频道话题成为独立会话。 |
| 进度模式 | 默认 Preview：智能体工作时编辑同一条消息。Final 则只发送最终答案。 |
| 发送消息上下文 | 建议保持开启，让智能体每回合都能拿到发送者、会话和消息 ID。 |
| Bot Connector 端点 | 公有云留空。仅在政府云或主权云时才需要填写。 |
| `resetOnIdleMins`（API） | 设置分钟阈值，闲置超时后开新会话；留空或 `0` 表示禁用。 |

## 文件

单聊附件可用：在私信中给机器人发文件，智能体就能收到。

**频道或群聊**中的文件则不行。Teams 会把文件引用从投递给机器人的内容中移除，改为发送一段 HTML 占位内容。要取回该文件需要 Microsoft Graph 应用权限以及租户管理员授权，本渠道刻意不索取这些权限。智能体会看到消息正文，但看不到附件。

在任何 Teams 场景下智能体都无法回传文件；文件路径会以文本形式出现在回复中。

## 非公有云

该渠道默认连接公有云的 Bot Connector。若使用政府云或主权云，请把渠道上的 **Bot Connector 端点**设为 Microsoft 为其提供的终结点 —— 例如 GCC High 为 `https://smba.infra.gov.teams.microsoft.us/teams`。只接受 Microsoft 自家的 Bot Connector 主机。

## 验证

在渠道详情页点击**测试**。它会确认凭据仍能铸出 Bot Connector token、且配置的端点可识别。它**刻意不**声称 Teams 能触达你：Bot Connector 不会按需回调，只有真实消息才能证明入站链路通了。

然后按你打算使用的方式逐条验证：

1. 给机器人发一条私信。
2. 在该私信里发一个文件，确认附件能进入工作区。
3. 团队场景下在频道里 @ 提及它，再在它回复所在的话题里追问一句。
4. 执行 `/help` 确认命令处理器工作正常。

如果发了消息却毫无反应，打开渠道的**投递记录**列表 —— 被拒绝的入站会带一个机器可读的原因记录在那里。

## 排查

**完全收不到消息。** 检查 Azure 门户里的消息传送终结点是否与渠道入站 URL 完全一致、机器人资源上是否已启用 Microsoft Teams 频道，以及应用是否安装在你发消息的位置。

**所有消息都被忽略，渠道显示被拒绝的投递。** 打开渠道的投递列表查看拒绝原因。`tenant_mismatch` 表示渠道上的租户 ID 与消息来源租户不一致。令牌校验失败通常意味着渠道上的应用 ID 不是该消息传送终结点所属的那个。

**机器人在单聊里回复，在频道里不回复。** 频道消息默认需要 @ 提及。如果提及了仍无反应，说明应用只装给了你个人而没有装到团队 —— 请重新安装到团队。

**更换凭据后回复失败。** 轮换凭据会同时替换应用 ID、密钥和租户 ID。请三项一起重新填写，然后点击**测试**。

**清单无法上传。** 很多租户禁用了自定义应用上传；Teams 管理员可在**Teams 应用 → 管理应用 → 组织范围的应用设置**中开启。另外请确认 zip 根目录下同时包含清单和两个图标，且图标尺寸恰为 192×192 和 32×32。

## 另请参阅

- [渠道总览](../../channels/) —— 所有渠道共有的能力。
- [会话切换](../session-switching/) —— 会话中可用的斜杠命令。
- [从智能体发送](../agent-send/) —— 智能体主动发消息及其限制。