diff --git a/docs/public/msteams-zh-s1-1-v1.png b/docs/public/msteams-zh-s1-1-v1.png new file mode 100644 index 0000000..d839ba4 Binary files /dev/null and b/docs/public/msteams-zh-s1-1-v1.png differ diff --git a/docs/public/msteams-zh-s1-2-v1.png b/docs/public/msteams-zh-s1-2-v1.png new file mode 100644 index 0000000..d9d2617 Binary files /dev/null and b/docs/public/msteams-zh-s1-2-v1.png differ diff --git a/docs/public/msteams-zh-s1-3a-v1.png b/docs/public/msteams-zh-s1-3a-v1.png new file mode 100644 index 0000000..abad242 Binary files /dev/null and b/docs/public/msteams-zh-s1-3a-v1.png differ diff --git a/docs/public/msteams-zh-s1-3b-v1.png b/docs/public/msteams-zh-s1-3b-v1.png new file mode 100644 index 0000000..5da0fd9 Binary files /dev/null and b/docs/public/msteams-zh-s1-3b-v1.png differ diff --git a/docs/public/msteams-zh-s1-4-v1.png b/docs/public/msteams-zh-s1-4-v1.png new file mode 100644 index 0000000..d6a24b6 Binary files /dev/null and b/docs/public/msteams-zh-s1-4-v1.png differ diff --git a/docs/public/msteams-zh-s1-5a-v1.png b/docs/public/msteams-zh-s1-5a-v1.png new file mode 100644 index 0000000..9cefa5b Binary files /dev/null and b/docs/public/msteams-zh-s1-5a-v1.png differ diff --git a/docs/public/msteams-zh-s1-5b-v1.png b/docs/public/msteams-zh-s1-5b-v1.png new file mode 100644 index 0000000..669bc84 Binary files /dev/null and b/docs/public/msteams-zh-s1-5b-v1.png differ diff --git a/docs/public/msteams-zh-s1-5c-v1.png b/docs/public/msteams-zh-s1-5c-v1.png new file mode 100644 index 0000000..ddd927f Binary files /dev/null and b/docs/public/msteams-zh-s1-5c-v1.png differ diff --git a/docs/public/msteams-zh-s1-6-v1.png b/docs/public/msteams-zh-s1-6-v1.png new file mode 100644 index 0000000..46a1239 Binary files /dev/null and b/docs/public/msteams-zh-s1-6-v1.png differ diff --git a/docs/public/msteams-zh-s10-1-v1.png b/docs/public/msteams-zh-s10-1-v1.png new file mode 100644 index 0000000..ad85b6c Binary files /dev/null and b/docs/public/msteams-zh-s10-1-v1.png differ diff --git a/docs/public/msteams-zh-s10-2a-v1.png b/docs/public/msteams-zh-s10-2a-v1.png new file mode 100644 index 0000000..10d2ec1 Binary files /dev/null and b/docs/public/msteams-zh-s10-2a-v1.png differ diff --git a/docs/public/msteams-zh-s10-2b-v1.png b/docs/public/msteams-zh-s10-2b-v1.png new file mode 100644 index 0000000..6e7632e Binary files /dev/null and b/docs/public/msteams-zh-s10-2b-v1.png differ diff --git a/docs/public/msteams-zh-s10-3-v1.png b/docs/public/msteams-zh-s10-3-v1.png new file mode 100644 index 0000000..abf96e1 Binary files /dev/null and b/docs/public/msteams-zh-s10-3-v1.png differ diff --git a/docs/public/msteams-zh-s10-4a-v1.png b/docs/public/msteams-zh-s10-4a-v1.png new file mode 100644 index 0000000..0b70990 Binary files /dev/null and b/docs/public/msteams-zh-s10-4a-v1.png differ diff --git a/docs/public/msteams-zh-s10-4b-v1.png b/docs/public/msteams-zh-s10-4b-v1.png new file mode 100644 index 0000000..8f33c10 Binary files /dev/null and b/docs/public/msteams-zh-s10-4b-v1.png differ diff --git a/docs/public/msteams-zh-s10-6-v1.png b/docs/public/msteams-zh-s10-6-v1.png new file mode 100644 index 0000000..97debe9 Binary files /dev/null and b/docs/public/msteams-zh-s10-6-v1.png differ diff --git a/docs/public/msteams-zh-s10-7-v1.png b/docs/public/msteams-zh-s10-7-v1.png new file mode 100644 index 0000000..a8f8e1e Binary files /dev/null and b/docs/public/msteams-zh-s10-7-v1.png differ diff --git a/docs/public/msteams-zh-s10-8-v1.png b/docs/public/msteams-zh-s10-8-v1.png new file mode 100644 index 0000000..f2b26d0 Binary files /dev/null and b/docs/public/msteams-zh-s10-8-v1.png differ diff --git a/docs/public/msteams-zh-s10-9-v1.png b/docs/public/msteams-zh-s10-9-v1.png new file mode 100644 index 0000000..737cca9 Binary files /dev/null and b/docs/public/msteams-zh-s10-9-v1.png differ diff --git a/docs/public/msteams-zh-s2-1-v1.png b/docs/public/msteams-zh-s2-1-v1.png new file mode 100644 index 0000000..25963d8 Binary files /dev/null and b/docs/public/msteams-zh-s2-1-v1.png differ diff --git a/docs/public/msteams-zh-s2-2-v1.png b/docs/public/msteams-zh-s2-2-v1.png new file mode 100644 index 0000000..c9e60b0 Binary files /dev/null and b/docs/public/msteams-zh-s2-2-v1.png differ diff --git a/docs/public/msteams-zh-s2-3-v1.png b/docs/public/msteams-zh-s2-3-v1.png new file mode 100644 index 0000000..da463d7 Binary files /dev/null and b/docs/public/msteams-zh-s2-3-v1.png differ diff --git a/docs/public/msteams-zh-s2-4-v1.png b/docs/public/msteams-zh-s2-4-v1.png new file mode 100644 index 0000000..e476e3a Binary files /dev/null and b/docs/public/msteams-zh-s2-4-v1.png differ diff --git a/docs/public/msteams-zh-s3-1-v1.png b/docs/public/msteams-zh-s3-1-v1.png new file mode 100644 index 0000000..033e0cd Binary files /dev/null and b/docs/public/msteams-zh-s3-1-v1.png differ diff --git a/docs/public/msteams-zh-s3-2-v1.png b/docs/public/msteams-zh-s3-2-v1.png new file mode 100644 index 0000000..ae89589 Binary files /dev/null and b/docs/public/msteams-zh-s3-2-v1.png differ diff --git a/docs/public/msteams-zh-s3-3-v1.png b/docs/public/msteams-zh-s3-3-v1.png new file mode 100644 index 0000000..46df3c0 Binary files /dev/null and b/docs/public/msteams-zh-s3-3-v1.png differ diff --git a/docs/public/msteams-zh-s4-1-v1.png b/docs/public/msteams-zh-s4-1-v1.png new file mode 100644 index 0000000..efaadf9 Binary files /dev/null and b/docs/public/msteams-zh-s4-1-v1.png differ diff --git a/docs/public/msteams-zh-s4-2-v1.png b/docs/public/msteams-zh-s4-2-v1.png new file mode 100644 index 0000000..919d1e0 Binary files /dev/null and b/docs/public/msteams-zh-s4-2-v1.png differ diff --git a/docs/public/msteams-zh-s4-3a-v1.png b/docs/public/msteams-zh-s4-3a-v1.png new file mode 100644 index 0000000..0263267 Binary files /dev/null and b/docs/public/msteams-zh-s4-3a-v1.png differ diff --git a/docs/public/msteams-zh-s4-3b-v1.png b/docs/public/msteams-zh-s4-3b-v1.png new file mode 100644 index 0000000..7ce44f9 Binary files /dev/null and b/docs/public/msteams-zh-s4-3b-v1.png differ diff --git a/docs/public/msteams-zh-s5-1-v1.png b/docs/public/msteams-zh-s5-1-v1.png new file mode 100644 index 0000000..65a40db Binary files /dev/null and b/docs/public/msteams-zh-s5-1-v1.png differ diff --git a/docs/public/msteams-zh-s5-2-v1.png b/docs/public/msteams-zh-s5-2-v1.png new file mode 100644 index 0000000..2640555 Binary files /dev/null and b/docs/public/msteams-zh-s5-2-v1.png differ diff --git a/docs/public/msteams-zh-s5-3-v1.png b/docs/public/msteams-zh-s5-3-v1.png new file mode 100644 index 0000000..3cb46d6 Binary files /dev/null and b/docs/public/msteams-zh-s5-3-v1.png differ diff --git a/docs/public/msteams-zh-s5-4-v1.png b/docs/public/msteams-zh-s5-4-v1.png new file mode 100644 index 0000000..a2e17ee Binary files /dev/null and b/docs/public/msteams-zh-s5-4-v1.png differ diff --git a/docs/public/msteams-zh-s6-1-v1.png b/docs/public/msteams-zh-s6-1-v1.png new file mode 100644 index 0000000..a1a9d51 Binary files /dev/null and b/docs/public/msteams-zh-s6-1-v1.png differ diff --git a/docs/public/msteams-zh-s6-2-v1.png b/docs/public/msteams-zh-s6-2-v1.png new file mode 100644 index 0000000..ea3a39f Binary files /dev/null and b/docs/public/msteams-zh-s6-2-v1.png differ diff --git a/docs/public/msteams-zh-s6-3a-v1.png b/docs/public/msteams-zh-s6-3a-v1.png new file mode 100644 index 0000000..37b0404 Binary files /dev/null and b/docs/public/msteams-zh-s6-3a-v1.png differ diff --git a/docs/public/msteams-zh-s6-3b-v1.png b/docs/public/msteams-zh-s6-3b-v1.png new file mode 100644 index 0000000..a15ed42 Binary files /dev/null and b/docs/public/msteams-zh-s6-3b-v1.png differ diff --git a/docs/public/msteams-zh-s6-4a-v1.png b/docs/public/msteams-zh-s6-4a-v1.png new file mode 100644 index 0000000..2e8d86c Binary files /dev/null and b/docs/public/msteams-zh-s6-4a-v1.png differ diff --git a/docs/public/msteams-zh-s6-4b-v1.png b/docs/public/msteams-zh-s6-4b-v1.png new file mode 100644 index 0000000..298f744 Binary files /dev/null and b/docs/public/msteams-zh-s6-4b-v1.png differ diff --git a/docs/public/msteams-zh-s7-1-v1.png b/docs/public/msteams-zh-s7-1-v1.png new file mode 100644 index 0000000..6bfc00e Binary files /dev/null and b/docs/public/msteams-zh-s7-1-v1.png differ diff --git a/docs/public/msteams-zh-s7-2-v1.png b/docs/public/msteams-zh-s7-2-v1.png new file mode 100644 index 0000000..00631d9 Binary files /dev/null and b/docs/public/msteams-zh-s7-2-v1.png differ diff --git a/docs/public/msteams-zh-s7-3a-v1.png b/docs/public/msteams-zh-s7-3a-v1.png new file mode 100644 index 0000000..8b491ca Binary files /dev/null and b/docs/public/msteams-zh-s7-3a-v1.png differ diff --git a/docs/public/msteams-zh-s7-3b-v1.png b/docs/public/msteams-zh-s7-3b-v1.png new file mode 100644 index 0000000..dfbfac4 Binary files /dev/null and b/docs/public/msteams-zh-s7-3b-v1.png differ diff --git a/docs/public/msteams-zh-s7-4-v1.png b/docs/public/msteams-zh-s7-4-v1.png new file mode 100644 index 0000000..e609f03 Binary files /dev/null and b/docs/public/msteams-zh-s7-4-v1.png differ diff --git a/docs/public/msteams-zh-s8-1-v1.png b/docs/public/msteams-zh-s8-1-v1.png new file mode 100644 index 0000000..c5ea0a1 Binary files /dev/null and b/docs/public/msteams-zh-s8-1-v1.png differ diff --git a/docs/public/msteams-zh-s9-1a-v1.png b/docs/public/msteams-zh-s9-1a-v1.png new file mode 100644 index 0000000..3207439 Binary files /dev/null and b/docs/public/msteams-zh-s9-1a-v1.png differ diff --git a/docs/public/msteams-zh-s9-1b-v1.png b/docs/public/msteams-zh-s9-1b-v1.png new file mode 100644 index 0000000..92a855c Binary files /dev/null and b/docs/public/msteams-zh-s9-1b-v1.png differ diff --git a/docs/zh/getting-started/channel-deployment.md b/docs/zh/getting-started/channel-deployment.md index b7f9837..c6fdf9f 100644 --- a/docs/zh/getting-started/channel-deployment.md +++ b/docs/zh/getting-started/channel-deployment.md @@ -1068,71 +1068,129 @@ Bot 需要独立身份。只有使用专属号码，其他人才能把它当作 ## 选项H：Microsoft Teams 部署 {#ms-teams} -**预计耗时：15-20分钟** +**预计耗时：15-20 分钟** -> **说明：** Microsoft Teams 是企业广泛使用的 Microsoft 365 协作平台。部署需要创建 Azure Bot 资源、配置权限，并通过 Teams Developer Portal 发布应用。无需服务器或编程技能——Azure 免费层即可满足。 +> **说明：** Microsoft Teams 是 Microsoft 365 企业广泛使用的协作平台。部署需要创建 Azure Bot 资源、配置权限，并通过 Teams Developer Portal 发布应用。无需服务器或编程技能——Azure 免费层即可满足。 -对接 Microsoft Teams 需要 **4 个配置项**： +### 开始之前 -| 配置项 | 获取位置 | 说明 | -|--------|---------|------| -| App ID | Azure Bot → Configuration → Microsoft App ID | 标识你的机器人应用 | -| App Password | App Registration → Certificates & secrets → Secret Value | 认证你的机器人 | -| Tenant ID | Azure Bot → Configuration → Directory (tenant) ID | 你的组织租户标识 | -| App Catalog ID | Teams Developer Portal → Basic information → App ID | 在 Teams 目录中标识应用 | +请确认你已具备以下条件： + +1. **一个 Microsoft Entra（Azure AD）租户** —— 使用 Microsoft 365 的组织都已经有。 +2. **一个有效的 Azure 订阅** —— 创建 Azure Bot 资源时必需。本教程全程使用 **F0（免费）** 定价层，且 Teams 属于标准渠道、不按消息计费，因此**整个部署过程 Azure 费用为 0**。组织已有订阅的直接使用；没有的可以开通即用即付订阅（开通需绑定信用卡，但本部署的账单为 $0），或使用 Azure 免费试用。 +3. **Microsoft 365 管理员配合** —— 第5步需要全局管理员为 Graph API 权限授予管理员同意；将应用发布到整个组织（后续步骤）需要 Teams 管理员审批。 + +> **都免费为什么还要订阅？** Azure 订阅只是创建资源的"容器"，订阅本身不收费——只按资源用量计费，而本部署的 Azure Bot 在 F0 层计费为 $0。 + +### 需要收集的凭据 + +部署过程中你将陆续收集 **4 个凭据**，最后统一填入 OpenMax Dashboard： + +| 凭据 | 获取位置 | +|------|---------| +| **App ID** | Azure Bot → 配置（第2步） | +| **Tenant ID** | Azure Bot → 配置（第2步） | +| **App Password** | 客户端密码的**值**（第4步） | +| **App Catalog ID** | Teams Developer Portal → Basic information（后续步骤） | ### 第1步：创建 Azure Bot -1. 打开 [Azure Portal](https://portal.azure.com)，点击 **Create a resource**，搜索 **Azure Bot** -2. 点击 **Create** 并填写： - - **Bot handle**：唯一名称（如 `openmax-ai-employee`） - - **Resource group**：选择已有的或创建新的 - - **Pricing tier**：F0（免费） - - **Type of App**：Single Tenant - - **Creation type**：Create new Microsoft App ID -3. 点击 **Review + create**，然后点击 **Create** -4. 部署完成后，点击 **Go to resource** +1. 登录 [Azure Portal](https://portal.azure.com)。你需要一个有效的 Azure 订阅——还没有的话，见上文"开始之前"。 -> **说明：** 创建 Azure Bot 会自动为你创建 App Registration——无需单独创建。 + Azure Portal 登录后首页 -### 第2步：配置 Bot 并记录凭据 +2. 订阅就绪后，点击 **创建资源**。 + + Azure Portal —— 创建资源 + +3. 搜索 **bot**，找到 **Azure Bot**，点击 **创建 → Azure Bot**。 + + 创建资源 —— 搜索 bot + + 市场搜索结果 —— Azure Bot，点击创建 + +4. 首次使用需要创建**资源组**：点击"资源组"下方的 **新建**，名称可填 `openmax`，点击 **确定**。 + + 新建资源组 —— 名称填 openmax，点击确定 + +5. 填写表单： + - **Bot handle**：唯一名称，如 `openmax-ai-employee` + - **订阅 / 资源组**：选择你的订阅和资源组（即上一步新建的） + - **Pricing tier（定价层）**：选择 **Free (F0)** *（截图中显示 Standard；对 Teams 渠道两个档位都是 $0 计费，但 F0 更稳妥）* + - **Type of App**：**Single Tenant** + - **Creation type**：**Create new Microsoft App ID** + + 然后点击 **审阅并创建**，验证通过后点击 **创建**。 + + 创建 Azure Bot —— Bot handle、订阅、资源组 + + 创建 Azure Bot —— Single Tenant、Create new Microsoft App ID，点击审阅并创建 + + 审阅并创建 —— 验证通过，点击创建 + +6. 部署完成后，点击 **转到资源**。 + + 部署完成 —— 转到资源 + +> 创建 Azure Bot 时会自动在 Microsoft Entra ID 中创建一个应用注册（App Registration）——第4步和第5步会用到它。 + +### 第2步：配置消息传递终结点并记录凭据 + +1. 在 Azure Bot 资源中，点击 **设置 → 配置**。你将在这里填写终结点，并把两个凭据复制到 OpenMax Dashboard。 + + Azure Bot —— 设置 → 配置 + +2. 打开 OpenMax Dashboard，进入员工详情页的**对话入口**页面，在 **Microsoft Teams** 卡片上复制**消息接入点** URL（形如 `https://<你的-agent-域名>/ms-teams/api/messages`），粘贴到 Azure 配置页的**消息传递终结点**。 + + OpenMax Dashboard —— Microsoft Teams 卡片，复制消息接入点 + +3. 记下 **Microsoft App ID**（即你的 **App ID**）和**应用租户 ID**（即你的 **Tenant ID**），分别填入 OpenMax Dashboard Microsoft Teams 卡片的对应字段。 + + OpenMax Dashboard —— 填入 App ID 和 Tenant ID + +4. 全部填好后，点击 **应用**。 + + Azure 配置页 —— 终结点已填写，点击应用 -1. 在 Azure Bot 资源中，进入 **Configuration** -2. 设置 **Messaging endpoint** 为你的 AI 员工的 MS Teams webhook URL： - ``` - https://<你的-agent-域名>/ms-teams/api/messages - ``` - 你可以在 OpenMax Dashboard 员工详情页的渠道列表中，**Microsoft Teams** 卡片上找到该 URL。复制并粘贴到此处。 -3. 记下 **Microsoft App ID**（即你的 **App ID**）和 **App Tenant ID**（即你的 **Tenant ID**） -4. 点击 **Apply** ### 第3步：启用 Microsoft Teams 渠道 -这一步**必需且最容易遗漏**——不启用，Bot 在 Teams 中将无法工作。 +*必需且最容易遗漏——不做这一步，Teams 中会报"Invalid Bot"错误。* + +1. 在 Azure Bot 资源中，点击 **设置 → 渠道**，找到 **Microsoft Teams**。 + + Azure Bot —— 设置 → 渠道 —— Microsoft Teams + +2. 阅读并接受服务条款（勾选后点击 **Agree**）。 + + Microsoft Teams 渠道 —— 接受服务条款 + +3. 点击 **Apply**。之后渠道列表中 Microsoft Teams 应显示为 **Running**（运行中）。 + + Microsoft Teams 渠道 —— 点击 Apply + +### 第4步：创建客户端密码（App Password） + +1. 进入 **设置 → 配置**，点击 Microsoft App ID 旁的 **管理密码**（会打开应用注册的"证书和密码"页面）。 + + 配置 —— Microsoft App ID 旁的管理密码链接 -1. 在 Azure Bot 资源中，进入左侧 **Channels** -2. 点击 **Microsoft Teams**，接受服务条款后点击 **Apply** -3. 此时 Microsoft Teams 渠道应在列表中显示为 **Running**（运行中） +2. 点击 **新客户端密码**，输入说明（如 `OpenMax Bot Secret`），选择过期时间，点击 **添加**。 -> **重要：** 必须在 Azure Bot 资源上启用 Teams 渠道。否则用户尝试与 Bot 聊天时，Teams 会显示"Invalid Bot"错误。 + 证书和密码 —— 新客户端密码 —— 添加 -### 第4步：创建 Client Secret（客户端密钥） +3. **立即复制密码的"值"——它只显示这一次，离开页面后无法再查看。** 这就是你的 **App Password**，请先妥善保存，然后粘贴到 OpenMax Dashboard 的 **App Password** 字段。 -1. 在 Configuration 页面，点击 **Manage Password** — 会跳转到 App Registration 页面 -2. 进入 **Certificates & secrets** -3. 点击 **New client secret** -4. 输入描述（如 `OpenMax Bot Secret`），选择过期时间 -5. 点击 **Add** -6. **立即复制 Secret 的 Value** — 离开此页面后无法再次查看 + 客户端密码已创建 —— 立即复制 -> **注意：** 客户端密钥仅在创建时显示一次，请立即安全保存。这就是你的 **App Password**。 + 把密码的值粘贴到 OpenMax Dashboard 的 App Password 字段 + +> ⚠️ 注意复制的是**值**那一列，*不是*"机密 ID"。 ### 第5步：配置 Graph API 权限 -无需逐个搜索添加权限，可以通过 Manifest 编辑器一次性粘贴全部权限。 +1. 在应用注册页面，点击 **管理 → 清单**（如有提示，选择 *Microsoft Graph 应用清单(新)*）。找到 `"requiredResourceAccess": []`，把下面的内容粘贴到 `[]` 里： -1. 在 App Registration 页面（第3步完成后应已在此页面），进入 **Manifest** 标签页 -2. 选择顶部的 **Microsoft Graph App Manifest (New)** 标签 -3. 找到 `"requiredResourceAccess": []`，仅将 `[]` 替换为以下数组： + 应用注册 —— 管理 → 清单 —— requiredResourceAccess ```json [ @@ -1153,51 +1211,68 @@ Bot 需要独立身份。只有使用专属号码，其他人才能把它当作 ] ``` -4. 点击页面顶部的 **Save** 保存 +2. 粘贴后，点击 **保存**。 + + 清单编辑器 —— 权限已粘贴，点击保存 + +3. 点击 **管理 → API 权限**，然后点击 **代表 [你的组织] 授予管理员同意** 并确认。*（这需要全局管理员帐户——见"开始之前"。）* + + API 权限 —— 授予管理员同意 + +4. 同意授予后，所有权限的状态都会变成绿色，如下图。 + + API 权限 —— 全部显示已授予（绿色） + +> 这些权限用于支持文件下载、聊天历史、表情回应和智能模式。没有管理员同意，这些功能将无法使用。 + +#### 为表情回应添加重定向 URI + +要启用表情回应（💬 思考中指示、👍 等），需添加一个重定向 URI： + +1. 在应用注册页面，进入**身份验证**（Authentication）。 +2. 点击 **+ 添加平台** → **Web**。 +3. 输入重定向 URI：`https://<你的-agent-域名>/ms-teams/auth/callback` *（与第2步消息传递终结点使用同一域名）*。 +4. 点击**配置**。 + +### 第6步：在 Teams 开发人员门户创建应用 -> **注意：** 仅替换 `"requiredResourceAccess":` 后面的空 `[]` — 不要替换包含键名的整行。 +1. 打开 [Teams 开发人员门户](https://dev.teams.microsoft.com)，点击首页的 **新建应用**。 -这会一次性添加全部 9 项权限： + Teams 开发人员门户首页 —— 新建应用 -| 权限 | 类型 | 用途 | -|------|------|------| -| `Files.Read.All` | 应用程序 | 从 OneDrive/SharePoint 下载文件 | -| `Chat.Read.All` | 应用程序 | 读取私聊和群聊历史记录 | -| `ChannelMessage.Read.All` | 应用程序 | 读取团队频道消息历史 | -| `User.Read.All` | 应用程序 | 解析用户提及和搜索用户 | -| `Chat.ReadWrite` | 委托 | 代表用户读取和发送聊天消息 | -| `ChannelMessage.Send` | 委托 | 代表用户发送频道消息 | -| `ChannelMessage.Read.All` | 委托 | 代表用户读取频道消息 | -| `Files.Read.All` | 委托 | 访问用户有权访问的文件 | -| `offline_access` | 委托 | 在用户未主动登录时保持访问权限 | +2. 输入应用名称（如 `OpenMax AI Employee`），清单版本保持默认（Latest Stable），点击 **创建**。 -#### 授予管理员同意 + 新建应用弹窗 —— 输入名称，点击创建 -保存 Manifest 后，进入 **API permissions** 页面，点击 **Grant admin consent for [你的组织]** 并确认。全部 9 项权限应显示绿色勾号。 +3. 在 **配置 → 基本信息** 页顶部，复制 **应用 ID** —— 这就是你的 **App Catalog ID**。把它填入 OpenMax Dashboard Microsoft Teams 卡片的 **App Catalog ID** 字段。 -> **注意：** 必须获得管理员同意。否则文件下载、聊天历史、表情回应和智能模式功能将无法使用。 + 基本信息 —— 顶部的应用 ID 即 App Catalog ID -### 第6步：在 Teams Developer Portal 中创建应用 + OpenMax Dashboard —— 填入 App Catalog ID -1. 打开 [Teams Developer Portal](https://dev.teams.microsoft.com) 并登录 -2. 点击左侧 **Apps**，然后点击 **+ New app** -3. 输入应用名称（如 `OpenMax AI Employee`） -4. 在 **Basic information** 中，记下顶部显示的 **App ID** — 这就是你的 **App Catalog ID**（连接 OpenMax Dashboard 时需要） -5. 填写必填字段： - - **Short description**：如 `AI 智能数字员工` - - **Long description**：如 `OpenMax AI 员工，帮助团队处理写作、研究、翻译、数据分析和日常任务——直接在 Microsoft Teams 中使用。` - - **Developer name**：如 `OpenMax` - - **Website**：`https://icoco.ai` - - **Privacy policy**：`https://docs.icoco.ai/privacy-policy` - - **Terms of use**：`https://docs.icoco.ai/user-agreement` -6. 点击 **Save** +4. 填写必填字段： + - **简短说明**：如 `AI 智能数字员工` + - **完整说明**：如 `OpenMax AI 员工，帮助团队处理写作、研究、翻译、数据分析和日常任务——直接在 Microsoft Teams 中使用。` + - **开发人员或公司名称**：`OpenMax` + - **网站**：`https://openmax.com` + - **隐私策略**：`https://docs.openmax.com/privacy-policy` + - **使用条款**：`https://docs.openmax.com/user-agreement` -### 第7步：配置应用 Manifest + 然后点击 **保存**。 -1. 在 Teams Developer Portal 中，进入你的应用的 **App package** → **App package editor** -2. 粘贴以下 manifest JSON，将两个占位符替换为你的实际值： - - 将 ``（1 处）替换为第5步的 **App ID**（App Catalog ID） - - 将 ``（2 处）替换为第2步的 **App ID**（Azure App Registration ID） + 基本信息 —— 简短说明与完整说明 + + 基本信息 —— 开发人员信息与应用 URL，点击保存 + +### 第7步：配置应用清单（Manifest） + +1. 点击 **配置 → 应用包编辑器**，打开 **manifest.json**。 + + 配置 → 应用包编辑器 —— manifest.json + +2. **全部删除**编辑器中的默认内容，然后粘贴下面的清单： + + manifest.json —— 删除默认内容 ```json { @@ -1208,9 +1283,9 @@ Bot 需要独立身份。只有使用专属号码，其他人才能把它当作 "name": { "short": "OpenMax AI Employee" }, "developer": { "name": "OpenMax", - "websiteUrl": "https://icoco.ai", - "privacyUrl": "https://docs.icoco.ai/privacy-policy", - "termsOfUseUrl": "https://docs.icoco.ai/user-agreement" + "websiteUrl": "https://openmax.com", + "privacyUrl": "https://docs.openmax.com/privacy-policy", + "termsOfUseUrl": "https://docs.openmax.com/user-agreement" }, "description": { "short": "AI-powered digital employee", @@ -1243,76 +1318,94 @@ Bot 需要独立身份。只有使用专属号码，其他人才能把它当作 } ``` -3. 点击编辑器顶部的 **Save** -4. 返回 **App package editor** 页面，点击 **Update** 按钮以应用更改 +3. 替换占位符： + - ``（**1 处**）→ 你的 **App Catalog ID** + - ``（**2 处**：`bots[0].botId` 和 `webApplicationInfo.id`）→ 你的 **App ID**（Microsoft App ID） -> **关于占位符：** Manifest 中有两个不同的 ID。`` 是 Teams Developer Portal 的 App ID（第5步）——在 `id` 字段中出现1次。`` 是 Azure 的 App ID（第2步）——出现在 `botId` 和 `webApplicationInfo.id` 中。 + manifest.json —— 三处占位符的位置 -### 第8步：上传应用图标（可选） + 替换之后，点击右上角的 **保存**，如下图： -1. 在 Teams Developer Portal 中，进入你的应用的 **Branding** 部分 -2. 上传应用图标： - - **Color icon**：192x192 PNG - - **Outline icon**：32x32 透明背景 PNG -3. 点击 **Save** + manifest.json —— 已替换为真实值，点击保存 -> **提示：** 如果跳过此步骤，Teams 将使用默认占位图标。 + > 粘贴后如果顶部出现红色报错「无法在清单中更改属性 "id"」，不用担心——把 `` 替换成你的 App Catalog ID 后报错即消失（`id` 必须保持为你应用自己的 ID）。 -### 第9步：发布应用 +4. 点击 **更新**，在「审阅更改」弹窗中点击 **确认**。 -有两种方式分发应用： + 应用包编辑器 —— 更新 → 确认 -**方式 A — 发布到组织：** -1. 在 Teams Developer Portal 中，进入 **Distribute** → **Publish to org** -2. 提交应用以待管理员审批 -3. 管理员需在 [Teams 管理中心](https://admin.teams.microsoft.com) → **Manage apps** 中批准应用 -4. 批准后，用户需要**重启 Microsoft Teams** 才能看到新应用 +### 第8步（可跳过）：设置应用图标（品牌） -**方式 B — 通过应用包侧载（适用于管理员）：** -1. 在 Teams Developer Portal 中，点击 **Download app package** 下载 `.zip` 文件 -2. 在 Microsoft Teams 中，进入 **Apps** → **Manage your apps** → **Upload a custom app** -3. 选择下载的 `.zip` 文件 +在 **配置 → 品牌** 中可以替换应用图标：一张 192×192 的全彩 PNG（彩色图标）和一张 32×32 的透明轮廓 PNG（大纲图标）。跳过此步则使用默认占位图标。 -### 第10步：在 OpenMax Dashboard 中连接 +配置 → 品牌 —— 彩色图标与大纲图标 -> **重要：** 此步骤必须**最后**完成——需要全部 4 个配置项。 +### 第9步：在 OpenMax Dashboard 连接 -1. 登录 [OpenMax Dashboard](https://icoco.ai/dashboard) -2. 进入员工实例详情页 -3. 找到 **Microsoft Teams** 卡片并点击 **连接** -4. 输入以下凭据： +1. 确认 Microsoft Teams 渠道卡片上的 **4 个凭据**都已正确填入 —— **App ID**、**App Password**（客户端密码的值）、**Tenant ID**、**App Catalog ID** —— 然后点击 **连接**。 -| 字段 | 来源 | -|------|------| -| App ID | Azure Bot → Configuration → Microsoft App ID（第2步） | -| App Password | App Registration → Client Secret Value（第3步） | -| App Catalog ID | Teams Developer Portal → Basic information → App ID（第5步） | -| Tenant ID | Azure Bot → Configuration → App Tenant ID（第2步） | + OpenMax Dashboard —— 四个凭据填写完毕，点击连接 -5. 点击 **连接** — 系统将验证凭据并部署渠道 + 连接成功后，卡片显示 **已连接**，如下图： -### 第11步：开始聊天 + OpenMax Dashboard —— Microsoft Teams 已连接 -1. 在 Teams 中搜索你的应用名称（如 `OpenMax AI Employee`） -2. 点击即可开始私聊对话 -3. 发送任何消息 — AI 员工即时响应 -4. 部署完成！ +### 第10步：发布应用并开始聊天 + +把应用装进 Teams 共有**两种方式**：**发布到你的组织**（推荐，需 Teams 管理员审批，本步骤演示），或在应用包编辑器中**下载应用包** `.zip` 后通过 Teams 的「上传自定义应用」旁加载（需要组织允许上传自定义应用）。 + +1. 在 **应用包编辑器** 中点击 **分发**，选择 **发布到你的组织**。 + + 分发应用 —— 发布到你的组织 + +2. 点击 **开始使用**。提交后状态显示为 **已提交（等待管理员审批）**。 + + 发布到组织 —— 开始使用 + + 状态 —— 已提交（等待管理员审批） + +3. 提交后，需要 Teams 管理员在 [Teams 管理中心](https://admin.teams.microsoft.com/) → **Teams 应用 → 管理应用** 中搜索你的机器人名称并打开。*（审批通过前应用显示为「已阻止」——这是正常的待审批状态。）* + + Teams 管理中心 —— 管理应用 —— 找到你的应用 + +4. 点击 **发布**，并在确认弹窗中再次点击 **发布**。 + + 应用详情 —— 发布 -> **提示：** 如需在群聊或团队频道中使用，将机器人添加到团队或群聊中，然后 @mention 即可触发回复。 + 确认弹窗 —— 发布 + +5. 审批通过后，用户需要**重启 Microsoft Teams** 才能看到新应用。 +6. 打开 Teams 客户端，点击左侧的 **应用**，搜索你的机器人名称（如 `openmax`）并打开。 + + Teams —— 应用 —— 搜索机器人 + +7. 点击 **添加**。 + + 应用详情弹窗 —— 添加 + +8. 点击 **打开**，然后就可以和机器人聊天了。 + + 添加完成 —— 打开 + +9. 向你的 AI 员工问好吧！在群聊和频道中，把机器人添加进去后 **@提及** 它即可对话。 + + 在 Teams 中与机器人聊天 + +> **一次性附加操作（推荐）：启用表情回应。** 要激活 💬 思考中指示和表情回应，请在浏览器中打开 `https://<你的-agent-域名>/ms-teams/auth/sign-in`（与消息传递终结点同一域名），用你的 Microsoft 365 帐户登录，看到 "Signed in successfully" 后关闭页面即可。只需操作一次——机器人会保存委托令牌并在之后自动使用。 ### Microsoft Teams 常见问题 -| 问题 | 解决方案 | +| 问题 | 解决方法 | |------|---------| -| 机器人不响应 | 确认 Azure Bot Configuration 中的 Messaging endpoint 设置正确，检查凭据（App ID、App Password）是否匹配 | -| 凭据验证失败 | 确认 App Password 使用的是 **Value**（非 Secret ID）。确认 Tenant ID 正确 | -| Teams 中看不到机器人 | 应用必须已发布并获批准（或侧载安装）。检查 manifest 中的 Azure App ID 是否与 App Registration 一致 | -| 管理员批准后仍看不到应用 | 重启 Microsoft Teams 客户端以加载新批准的应用 | -| 消息未送达机器人 | 确认 Messaging endpoint URL 为 HTTPS 且可公开访问。检查 Azure Bot 资源是否处于正常状态 | -| 文件下载失败 | 确认 Azure Portal → App Registration → API permissions 中 `Files.Read.All` 已获得管理员同意 | -| 智能模式不生效 | 确认 `ChannelMessage.Read.All` 已获得管理员同意，且频道已设置为智能模式 | -| 客户端密钥过期 | Azure 客户端密钥会按你设置的时间过期。创建新密钥并在 OpenMax Dashboard 中更新 App Password | -| 想要断开连接 | 在员工详情页的 Microsoft Teams 卡片上点击 **断开连接** 按钮 | +| 机器人在 Teams 中不回复 | 检查 Azure Bot → 配置中的消息传递终结点，并确认 OpenMax Dashboard 中的 App ID 和 App Password 与你的 Azure Bot 一致 | +| 凭据校验失败 | 确认填的是客户端密码的**值**，而*不是*「机密 ID」，并核对 Tenant ID | +| Teams 中找不到机器人 | 应用必须先发布并通过审批（第10步）或旁加载后才会出现；同时确认清单中的 `` 与你的应用注册一致 | +| 管理员审批后仍看不到应用 | 重启 Teams 客户端——应用列表有缓存 | +| 消息到不了机器人 | 消息传递终结点必须是公网可达的 HTTPS，且 Azure Bot 资源处于活动状态 | +| 文件下载失败 | 确认 `Files.Read.All` 已获管理员同意（第5步） | +| 频道中智能模式不生效 | 确认 `ChannelMessage.Read.All` 已获管理员同意，且频道设置为智能模式 | +| 客户端密码过期 | 在 Azure 中新建客户端密码，并更新 OpenMax Dashboard 中的 App Password | +| 想断开连接 | 在员工详情页的 Microsoft Teams 卡片上点击**断开**按钮 | ---