第6章 Kortix 第6章：连接 Microsoft Teams
Microsoft Teams 连接 Microsoft Teams bot，让聊天和频道都能发起并延续 Kortix 会话。Microsoft Teams 是一个渠道：在 Teams 聊天或频道里 @ 机器人即可启动会话，agent 直接在原地回复并展示实时进度。它在会话、身份和凭证方面遵循与 Slack 相同的规则；本页只讲 Teams 特有的内容。每个项目都可以连接 Teams，无需打开任何功能开关。
连接
连接方式有两种，都从项目的 Connectors → Channels 页面进入：
一键连接（托管式）。Teams 租户管理员点击 Add to Teams 并登录授权，Kortix 会自动把应用发布到你组织的 Teams 应用目录——无需自己构建或粘贴任何东西。随后该行会提供 Add to Teams（一个直达 Teams 客户端的深链接），任何人都可以用它把 bot 添加到聊天或频道。当 Kortix 发布应用新版本时，请参考「更新应用」。
自带 bot。点击 Use your own Microsoft Teams app，进入一个三步向导：注册一个 Azure Bot，用它的 app id、client secret 和 tenant id 连接到 Kortix，然后下载生成的应用包并上传到 Teams。自托管部署或已有自己的注册时用这种方式。顺序很重要：Kortix 根据你的 app id 构建 manifest，所以只有完成第 2 步后才能生成应用包——向导会先让你把 messaging endpoint 粘贴到 Azure，然后才要求其他内容。
CLI 与面板操作一致：
kortix channels connect --platform teams # 输出管理员授权 URL kortix channels status --platform teams # 租户、目录、发布状态、应用版本 kortix channels disconnect --platform teams
更新应用
Kortix 会随时间给 Teams 应用添加权限。应用 1.1.0 版本增加了 ChannelMessage.Read.Group，agent 读取频道会话串需要它。1.3.0 版本增加了 ChatMessage.Read.Chat，群聊中的回复无需 @ 提及即可延续会话。还停留在 1.0.0 的团队无法读取任何会话串，agent 收到的拒绝信息会指明由谁来修复。应用更新需要两个人按以下顺序完成：
Teams 管理员发布更新。当你组织的目录中存在旧版本时，Channels 页面会显示 Update the Kortix app in Teams，Teams 行的按钮会显示 Publish app update。管理员点击并用 Microsoft 账号登录即可。kortix channels status --platform teams 会输出两个版本号，kortix channels connect --platform teams 会输出登录链接。
团队所有者在每个 Teams 提示更新的团队中更新应用。在 Teams 中打开团队，进入 ⋯ → Manage team → Apps，在 Kortix 应用上选择 Update 并接受。除非更新增加了权限或消息操作，Teams 会自行安装更新；这两类更新需要等待团队所有者操作。
Kortix 会记录每次发布的应用版本。在 Kortix 开始记录版本之前发布的安装会一直显示提示，直到下一次发布。
聊天、频道与提及
个人聊天：每条消息都会到达 bot。团队频道 / 群聊：新发帖需要 @ 提及。此后，在 bot 已参与的会话中回复时无需再提及，就像 Slack 的会话串一样。这需要应用的 ChannelMessage.Read.Group（频道）和 ChatMessage.Read.Chat（群聊）权限，由租户管理员在添加应用时授权。如果应用是在这些权限申请之前添加的，需要团队所有者更新它，参见「更新应用」。
每个聊天或频道会话都是独立的会话。第一条消息创建它，后续消息延续它，即使 sandbox 停止又恢复也一样。一个租户连接了多个项目时，第一条未路由的消息会弹出项目选择器，并记住你的选择。在频道中，只有提到 bot 的消息才会触发选择器，项目相关命令（如 /models）也会先询问项目。
在频道中，每个新帖都会启动自己的会话。个人聊天和群聊则是一条对话贯穿始终，保持同一个会话，直到你发送 /new。可以在命令后附带消息（/new summarize today's deploys），用这条消息开启新会话。上一个会话仍保留在 Kortix 中，连同完整历史，确认信息会附上它的链接。
会话名称
Teams 发送的是 id，例如 19:…@thread.tacv2;messageid=…。Channels 页面和 kortix channels bindings 显示的是人们在 Teams 中看到的名称：
会话类型 | 名称 | 名称下方
频道帖子 | Team › Channel | 其会话标题，用于区分同一频道的不同帖子
群聊 | 聊天的标题 | Group chat
个人聊天 | 对方的人名 | Personal chat
频道消息只携带团队的 id 而不携带名称，所以 Kortix 会从 Teams 读取团队和频道名称并存储。团队 General 频道的帖子会在下次 Channels 页面列出时显示名称；其他频道的帖子在下一条消息后显示名称。在此之前显示为 Channel thread。
谁可以加入会话
每个会话都有加入策略，可在 Teams 中用 /policy 设置，或在 Channels 页面设置——Teams 行的 N channels 列出所有会话：
open（默认）——任何关联的项目成员都可以加入此处启动的会话。
approval——会话所有者会为每个新加入者收到 Approve / Deny 卡片。
owner——只有启动会话的人。
在 approval 和 owner 策略下，会话对整个项目也不可见：只有会话所有者、被批准加入的人，以及监管会话的账户管理员能看到。对审核或审批卡片的操作会在任何策略下恢复 agent。
身份关联
发送者用 /login 一次性关联自己的 Kortix 账户，之后 agent 就以该用户身份运行，使用其自己的凭证、密钥和已连接的应用。未关联的发送者，或无项目访问权限的发送者，会收到一张用于连接账户或申请访问权限的卡片，而不是会话。
登录链接只会出现在只有你自己能看到的位置：你与 bot 的一对一聊天中；或在频道、群聊中，出现在标记为 Only you can see this message 的回复里。该链接会将颁发对象与打开者绑定，因此绝不会出现在他人可见的地方。如果 Teams 拒绝发送该私密回复，bot 会把链接发到你的私聊中，并在会话里说明。只有当你为自己添加了该应用时，Teams 才允许这种私聊；否则卡片会提示你打开与 bot 的私聊并在那里发送 /login。未关联状态你在频道中发的消息，只要在 10 分钟内完成连接，连接后会自动执行。在浏览器完成连接后，你与 bot 的私聊会确认你关联的 Kortix 账户。
登录链接只能使用一次，10 分钟后过期。一个 Teams 账户已关联一个 Kortix 账户后不能再关联另一个：先发送 /logout。如果你的组织要求双因素认证，Kortix 会在连接前要求你的第二重验证因素，之后的会话就基于该因素运行。没有通过它创建的链接会要求重新连接。
当没有访问权限的人申请权限时，所有账户所有者和管理员都会在 Kortix 中收到请求。已关联 Teams 的人还会在与 bot 的私聊中收到请求，附有 Review in Kortix 按钮。
私密回复
在频道或群聊中，bot 对某个人说的话只有那个人可见，标记为 Only you can see this message，类似 Slack 的临时消息：
对你命令的回复；
连接账户或申请访问权限的卡片；
你的消息为何没有执行：加入策略，或你无权使用的 agent；
approval 策略下所有者的 Approve / Deny 卡片，以及对申请者的决定。
所有人可见的 Working on it… 卡片只在你的消息有可能执行时出现。Teams 会在 24 小时后删除私密回复。如果 Teams 拒绝私密回复，bot 会改为在会话中公开发送卡片。登录链接是例外：此时它会改发到你与 bot 的私聊，绝不会发到会话里。
角色与权限
聊天本身不携带任何 Kortix 凭证，因此每个操作都以执行者的关联 Kortix 账户身份运行，并遵循该账户的项目角色。账户所有者和管理员视为项目管理员。
操作 | 谁可以执行
发送 agent 会回复的消息 | 已关联且有项目访问权限的账户，并符合该会话的加入策略
停止一次运行 | 被回复消息的发送者，或已获准加入该会话且仍有项目使用权限的任何人
在群聊中执行 /new | 已关联的项目成员；在 approval 或 owner 策略下，需是已获准加入当前会话的人
更改项目、agent、模型或策略 | 项目管理员；与 bot 的私聊中，任何项目成员
批准或拒绝一次审核 | 项目管理员
批准或拒绝一次 connector 调用 | 项目管理员，或会话发起者
批准他人加入 approval 会话 | 会话所有者
申请访问权限 | 任何已关联的人；每个账户所有者和管理员都会收到一次通知
被排除在某个 agent 之外的人，无法在 Teams 中用该 agent 启动会话，与 Kortix 中一致。
命令
在与 bot 的聊天中输入这些命令（在频道中先 @ 提及）：
命令 | 功能
/help | 列出所有命令
/login、/logout、/whoami | 关联、解除关联或显示你的 Kortix 账户
/status | 此处的项目、agent、模型、会话策略和运行状态，附更改模型、agent 或项目的按钮
/sessions | 你最近从 Teams 启动的五个会话，每个带 Open 按钮
/stop | 停止此处正在进行的运行
/new [message] | 在此聊天中开启新会话（个人聊天和群聊）
/models、/model | 为此会话选择模型——参见「模型与密钥」
/agents、/agent
/projects、/use
/policy [open|approval|owner] | 设置谁可以加入此处启动的会话
/unbind | 将此会话与项目断开；下一条消息重新选择项目
/home | 组织的项目及可尝试的内容
在任何消息上，⋯ → Open in Kortix 可打开该会话所属的会话。当你为自己添加应用后，与 bot 的私聊会以与 /home 相同的概览开场。
模型与密钥
/models 会列出你在此可运行的所有模型，与网页选择器一致：Kortix 模型，以及通过 provider API key 或 ChatGPT 订阅使用的模型。每个模型都标明其付费方式。列表过长时会显示为可搜索的下拉菜单。点选模型，或输入 /model
哪些密钥可用取决于聊天类型：
与 bot 的个人聊天——你自己的密钥和 ChatGPT 订阅，加上与项目共享的密钥。其会话仅你可见。
群聊或频道——只有与整个项目共享的密钥。聊天是共享的，个人密钥会让其中所有人消耗一个人的订阅额度。想用这类模型，请在个人聊天中选择。
依赖密钥运行的模型会使用你可用的该 provider 的所有密钥，并在触发限流时轮换。模型选择适用于下一条消息，聊天保持其会话。更改运行中会话的模型需要已关联的账户；在 owner 或 approval 策略下，只有会话所有者可以更改。个人聊天中若会话在此类聊天变为私密之前就已启动，则该会话仍与项目共享：/model 会提示这一点，/new 可开启私密会话。参见「Provider 密钥与成员访问」。
agent 运行期间
agent 用一张卡片回答：工作中展示其步骤，随后是回复。过长的回复在单条 Teams 消息放不下时，会按行截断、标记为已截断，并链接到 Kortix 中的完整会话。需要你打开的链接是按钮而不是句中的文字：连接应用的链接（Connect Gmail），以及 agent 单独成行的任何链接。其他链接、代码和表格按 Kortix 中的方式渲染。
在它运行时再发一条消息，它会等当前运行结束后再获得自己的卡片。一次运行需要多久就跑多久：只有运行时报告该运行已结束，卡片才会标记为已失效，而不会因为某个步骤长时间没有输出就判定为死卡。
停止运行
agent 运行时，其实时卡片上有 Stop 按钮。卡片滚出视野后，/stop 可实现同样效果。两者都是在运行时层面终止运行，而不只是关闭卡片——一个未终止的运行会吞掉会话中的下一条消息而不是回复它。
被回复消息的发送者可以停止运行，已获准加入该会话且仍有项目使用权限的人也可以。频道中的旁观者不能；获批加入过该聊天较早会话的人也不能。
文件
agent 用 teams send --file 发送文件，Kortix 会根据会话类型选择投递方式：
图片以行内方式展示——个人聊天、群聊或频道均可。如果图片太大无法在 Teams 中行内传输，个人聊天会降级为授权卡片（接受后文件进入你的 OneDrive），频道则降级为团队文件。群聊无法接收文件传输，因此过大的图片会以“请发小一点的”返回给 agent。
其他文件在个人聊天中以授权卡片送达，共享给团队时则以 SharePoint 链接收到的文件和粘贴的图片，agent 都可以下载和处理——包括粘贴到频道或群聊中的图片，Teams 会把它们放在消息正文内而非作为附件交付。
粘贴到频道或群聊的图片，只有 agent 按「读取频道」中的规则有权读取该会话串或聊天时才能下载，否则 teams download 返回 403。单次下载上限 50 MB，超出返回 413。
teams history 和 teams thread 会列出一个帖子的行内图片（images，每项一个 teams download 的 URL），以及从 SharePoint 共享的文件名（files）。agent 无法下载 SharePoint 文件。
粘贴截图并提问时，这一轮会用能读取图片的模型运行，即使该会话本身的模型只支持文本——会话的模型选择不会被改动。会话无法再运行的模型（密钥被吊销、聊天无法使用某 ChatGPT 订阅）也会以同样方式为该条消息替换，而不是让消息失败。
提问与表单
agent 用控件而非文字提问——与 Kortix 应用中提问的形式一致：
单个问题、不超过六个选项——每个选项一个按钮，点一下即回答。
多个问题、多选题或更长列表——一个表单：每个问题列出选项，附自定义回答输入框和 Send answers 按钮。
日期、时间、数字或开关选择——带对应输入控件的表单。
你的回答会作为下一条消息送达 agent，并标注对应的提问，会话由此继续。你也可以随时无视卡片，直接输入回答。
审批
当 agent 需要人工决定才能继续——一个高风险步骤、一项希望获得签核的变更——它会提交一个审核项。如果会话是从该会话启动的，决定会以卡片形式落在这里：标题、摘要、风险级别，以及 Approve、Request changes 和 Deny，外加进入 Kortix 的链接。
卡片带一个可选的反馈框。你输入的内容会随决定一起存储并传给 agent，因此选择 Request changes 时无需再来回询问你的意图。它是刻意设计为可选项——单纯 Approve 不应需要打字。
会话中的任何人都能看到卡片，但操作它需要已关联且具有项目管理权限的 Kortix 账户。无论会话的加入策略如何，决定都会恢复 agent。
主动发帖
除了在被叫到的位置回复，agent 还可以向 bot 已加入的、属于该项目的任何聊天或频道发帖——每夜摘要、告警、交接说明。它无法触达自己从未被添加的会话。
会话无法启动时
Kortix 会说明问题所在，而不是让你重试，因为大多数启动失败重试也无法解决：sandbox 模板已不存在、账户未关联、你无法访问的项目，或工作区额度耗尽。每条信息都会指明修复方法和对应命令。
如果该会话设置的 agent 已被删除或重命名，失败会以选择器形式出现：选一个可用的 agent，然后重新发送你的消息。列表只提供你有权限访问的 agent。
读取频道
在频道中，bot 只接收提到它的消息，因此你让它讨论的内容并不在它的会话里。当它需要这些上下文时，agent 会通过应用加入团队时申请的 ChannelMessage.Read.Group 权限，读取它被提及的会话串或频道的近期帖子。在该权限申请之前添加了应用的团队需要更新它，参见「更新应用」。个人聊天中每条消息都已进入会话，因此没有更早的内容需要读取。
连接同一 Microsoft 365 租户的所有项目共用同一个应用，所以 Kortix 会把每次读取限制在项目自己的会话范围内。在频道中，每个新帖都是独立的会话：
读取内容 | 允许条件
一个会话串（teams thread） | 该会话串属于本项目，或不属于任何项目且该频道可读
频道的近期帖子（teams history） | 本项目在该频道中有会话。开启其他项目会话的帖子会被排除
没有任何项目有会话的频道 | 没有其他项目连接到该租户
被拒绝的读取返回 403，原因为 conversation_not_in_project，并附带指明频道或会话串的消息。要在多项目租户中读取第一类频道，请在其中 @ 提及 bot 并选择该项目。
get_channel 和 list_channels 对标准频道可用。私有频道或共享频道只有 agent 按上述规则可读时才会出现。
get_team、list_members、get_user 和 list_teams 读取租户目录，不受限制。
限制
Teams bot 无法添加消息表情回应或搜索消息——这些 Slack 能力在 Teams 中没有对应功能。agent 只能读取应用已加入的团队中的频道，且只能按「读取频道」中的规则进行。
