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

# Microsoft Teams

> 直接在 Microsoft Teams 中与 Devin 聊天协作

在 Microsoft Teams 中，一有 bug、功能需求或问题，就标记 **@Devin**。每当被标记时，Devin 会在对应线程中回复最新进展并提出相关问题。

<div id="get-started">
  ## 快速开始
</div>

<div id="installation">
  ### 安装
</div>

1. 前往 [Settings > Connections](https://app.devin.ai/settings/connections)，选择 **Microsoft Teams**
2. 点击 “Connect”
3. 系统会提示你在你的租户和/或目标团队中安装适用于 Microsoft Teams 的 Devin 应用
4. 确保绑定你的个人账户。组织内所有用户都需要完成此步骤才能使用 Devin
5. 在团队频道或聊天中 @`Devin` 以开始会话

> 注意：要让 Devin 对每位用户生效，每个人都必须在 Devin 仪表板中连接自己的账户 (Settings > Connections) 。这样 Devin 才能将其在 Microsoft Teams 中的身份与对应的 Devin 用户关联起来。

<div id="how-to-use-devin-from-microsoft-teams">
  ### 如何在 Microsoft Teams 中使用 Devin
</div>

安装 Microsoft Teams 集成后，只需在任意团队频道中使用 `@Devin` 即可激活 Devin。

Devin 会在线程中回复你的会话。你可以像在常规 Devin 聊天界面中一样与 Devin 进行双向交流。

*请注意，Devin 可能会出错。请务必仔细检查回复内容。*

<div id="inline-teams-keywords-functions">
  ### Teams 内联关键词与功能
</div>

| Keyword             | Function                                  |
| ------------------- | ----------------------------------------- |
| `!ask`              | 在消息开头使用 !ask，可在不启动完整智能体的情况下快速获取代码库相关回答    |
| `!deep`             | 使用高级搜索获取更深入的研究型回答                         |
| `mute`              | 阻止 Devin 查看此线程中的后续消息                      |
| `unmute`            | 撤销上述操作                                    |
| `(aside)`, `!aside` | 让 Devin 忽略该消息（适用于在同一线程中直接对 Devin 的运行进行评论） |
| `sleep`             | 让 Devin 进入休眠；要唤醒 Devin，在该线程中发送任意消息即可      |
| `archive`           | 让 Devin 进入休眠，并归档该会话                       |
| `EXIT`              | 结束当前会话                                    |
| `help`              | 显示包含可用关键词和功能的帮助信息                         |

<div id="pricing">
  ### 定价
</div>

如果你还没有 Devin 账号，可以在[这里](https://devin.ai/pricing)了解各类套餐及价格详情。

<div id="privacy">
  ### 隐私
</div>

我们的隐私政策请见[此处](https://cognition.com/privacy-policy)。

<div id="authentication-flow">
  ### 身份验证流程
</div>

下图展示了 Microsoft Teams 集成的高级身份验证架构，说明了身份验证如何从 Teams 经过各层流转，从而创建已通过验证的 Devin 会话。

```mermaid theme={null}
graph TB
    subgraph MSTeams ["Microsoft Teams"]
        A[Teams 用户] --> B[Teams 频道]
        B --> C[Teams Bot 框架]
        C --> D[Microsoft Graph API]
    end
    
    subgraph AuthLayer ["身份验证层"]
        E[基于证书的身份验证] --> F[JWT 令牌验证]
        F --> G[租户 ID 验证]
        G --> H[用户身份声明]
    end
    
    subgraph DevinPlat ["Devin 平台"]
        I[对话管理器] --> J[身份映射服务]
        J --> K[组织解析器]
        K --> L[RBAC 授权]
        L --> M[会话创建]
    end
    
    subgraph IdProviders ["身份提供方"]
        N[Microsoft Entra ID] --> O[SAML/SSO 提供方]
        O --> P[Devin 身份存储]
    end
    
    A --> E
    D --> F
    H --> J
    N --> J
    P --> L
    M --> Q[Devin 会话]
```

<div id="permissions-details">
  ### 权限详情
</div>

下面是我们的集成所需的 Microsoft Teams 和 Microsoft Graph 权限摘要——每个权限能做什么、我们为什么需要它，以及它在何处被使用。

> 一览
>
> * Graph（应用程序，租户级）：用于发现和安装编排。
> * Teams 机器人 RSC（按团队/聊天）：仅在机器人已安装或存在的团队/聊天中，对消息、成员和设置进行限定范围的访问。

<div id="tenant-wide-microsoft-graph-application-permissions">
  #### 租户级 Microsoft Graph (应用程序) 权限
</div>

这些权限在 Microsoft Entra ID 中需要管理员同意。它们仅限应用程序使用 (不涉及用户委托) 。

| Permission                                                | 允许的操作                  | 我们为什么需要它                       |
| --------------------------------------------------------- | ---------------------- | ------------------------------ |
| `Organization.Read.All`                                   | 读取组织的基本信息              | 验证正在安装应用的租户                    |
| `User.ReadBasic.All`                                      | 读取所有用户的基本信息            | 映射成员身份，并解析关联 Teams 中的 @ 提及     |
| `AppCatalog.Read.All`                                     | 读取 Teams 应用目录          | 定位到我们的应用，并获取安装所需的 `teamsAppId` |
| `TeamsAppInstallation.ReadWriteAndConsentSelfForTeam.All` | 安装/卸载我们自己的应用；为应用授予 RSC | 通过 Devin 仪表板在选定的团队中安装/移除机器人    |

> 注意：我们不会使用租户级 Graph 权限读取消息内容。消息访问仅通过 RSC 授予，且仅限机器人已安装/存在的团队。

<div id="teams-bot-resource-specific-consent-rsc-permissions">
  #### Teams 机器人资源特定同意（RSC）权限
</div>

这些权限在安装时按各个团队/聊天单独授予（不在整个租户范围内生效）。

| Permission                  | Scope        | What it allows                       | Why we need it                    |
| --------------------------- | ------------ | ------------------------------------ | --------------------------------- |
| `ChannelMessage.Read.Group` | Team/Channel | 读取安装了应用的频道中的消息                       | 处理频道会话（摘要、触发器、同步）                 |
| `ChannelMessage.Send.Group` | Team/Channel | 在安装了应用的频道中发送消息（新帖子和线程回复）             | 在频道线程中回复消息，并主动向频道发布更新             |
| `Member.Read.Group`         | Team/Channel | 读取团队成员信息                             | 映射身份、执行权限检查、处理 @ 提及路由             |
| `TeamSettings.Read.Group`   | Team/Channel | 读取团队设置                               | 遵守团队级策略并据此调整行为                    |
| `ChatMember.Read.Chat`      | Chat         | 读取聊天参与者                              | 正确称呼和回复用户，并支持审计日志追踪               |
| `ChatMessage.Read.Chat`     | Chat         | 读取机器人参与的聊天中的消息                       | 处理提示、上下文和后续交互                     |
| `ChatMessage.Send.Chat`     | Chat         | 在机器人参与的 1:1 和群组聊天（私信/DM）中发送消息；不适用于频道 | 在私信和群组聊天中回复用户，发布通知，并在聊天线程中发送交互式回复 |
| `ChatSettings.Read.Chat`    | Chat         | 读取聊天设置（例如，审核配置）                      | 将行为与聊天策略对齐（频率限制、谁可以发言等）           |

> RSC 保护措施：访问权限仅限于安装应用或机器人参与的特定团队/聊天。将应用从某个团队/聊天中移除会立即撤销对此的访问权限。

<div id="example-certificate-based-authentication-for-teams-discovery">
  #### 示例：用于 Teams 发现的基于证书的身份验证
</div>

下图展示了我们在 Microsoft Graph 上使用仅应用（app-only）、基于证书的身份验证方案。服务使用 X.509 客户端证书获取访问令牌，然后调用 Graph 列出 Teams（GET /v1.0/teams）。此示例演示 Devin 如何在没有用户上下文的情况下安全地执行租户发现。

```mermaid theme={null}
sequenceDiagram
    participant S as Cognition
    participant M as MSAL 客户端
    participant K as 证书私钥
    participant A as Entra ID 令牌端点
    participant G as Microsoft Graph

    S->>M: 获取 Graph 令牌（.default 作用域）
    M->>M: 检查令牌缓存（租户、作用域、客户端）
    M->>K: 构建 client_assertion JWT（使用证书签名）
    K-->M: client_assertion（已签名 JWT）
    M->>A: POST /oauth2/v2.0/token
    A-->A: 验证签名和证书指纹<br/>验证应用对 Graph 的角色
    A-->M: 200 access_token（aud=graph）
    M-->S: 返回 access_token（存储到缓存）

    S->>G: GET /v1.0/teams，Authorization: Bearer access_token
    G-->S: 200 团队列表（通过 @odata.nextLink 分页）
```

> 凭证说明：我们使用 X.509 证书（客户端断言）而不是客户端密钥（client secret）来进行服务到服务的身份验证。这适用于对 Microsoft Graph 的调用、机器人与 Bot Framework 适配器之间的通信，以及该集成发起的任何仅应用程序（app-only）API 调用。

<div id="complete-message-processing-flow-teams-cognition">
  #### 完整消息处理流程（Teams → Cognition）
</div>

下图展示了当用户在 Microsoft Teams 中向 Devin 发送消息时的端到端处理流程，包括令牌验证和机器人处理。

```mermaid theme={null}
sequenceDiagram
    participant U as Teams 客户端
    participant T as Teams 服务
    participant W as Bot webhook 适配器
    participant J as JWT 验证器
    participant O as OpenID 元数据和密钥
    participant C as 凭据提供程序
    participant B as Bot 逻辑

    U->>T: @Devin 用户消息
    T->>W: HTTP POST 活动 + Authorization Bearer 令牌
    note over W: 提取 Authorization 标头和令牌

    W->>J: 验证令牌
    J->>O: 获取 OpenID 配置和签名密钥
    O-->J: 返回 JWKS 密钥
    J->>J: 验证 RS256 签名<br/>并解析声明
    J-->W: 已验证的声明

    W->>C: 根据凭据检查 appId
    C-->W: 已识别 appId
    W->>W: 将 serviceUrl 添加到信任列表

    W->>B: 创建 TurnContext 并调用 bot 处理程序
    B->>B: 执行业务逻辑
    B-->W: 传出活动

    W->>T: 通过连接器服务发送回复
    T->>U: 向用户传递消息
```

> 凭证说明：我们使用 X.509 证书（client assertion）而不是 client secret 进行服务到服务的身份验证。这适用于 Microsoft Graph 调用、机器人与 Bot Framework 适配器之间的通信，以及由该集成发起的任何仅应用程序身份（app-only）的 API 调用。

<div id="consent-installation-flow">
  #### 同意与安装流程
</div>

1. **管理员同意（租户范围）**
   * Entra ID 管理员授予上述 Graph 应用程序权限。
2. **应用发现**
   * 集成会查询 Teams 应用目录以定位我们的应用并获取 `teamsAppId`。
3. **定向安装**
   * 我们通过仪表板将机器人安装到特定的 Team 团队中。
   * 在安装过程中，RSC 权限范围仅授予该 Team（或在聊天中调用时，仅授予该特定 Chat）。
4. **运行**
   * 资源发现（组织/团队/频道/应用目录）使用 Graph 应用程序权限。
   * 读取/发送消息以及读取成员/设置依赖于已安装界面内的 RSC 权限。

<div id="least-privilege-notes">
  #### 最小权限说明
</div>

* 仅基础读取权限：`User.ReadBasic.All`（不包含租户范围的消息读取权限）。
* 消息内容仅通过 RSC 访问，且仅限于机器人已安装/存在的地方。
* 不请求任何邮箱、文件或日历权限。

<div id="revocation-uninstallation">
  #### 撤销与卸载
</div>

* 撤销管理员同意：租户管理员可以在 Entra ID 中移除该应用的企业应用权限。
* 从 Teams 卸载：从某个 Team/Chat 中移除该应用以撤销该资源的 RSC。
* 数据处理：卸载后，我们的集成将停止处理该 Team/Chat 的事件，并清理相关订阅和链接。