私聊、群与话题

图中实线表示同一个话题里的连续任务。在私聊里直接发一条新消息，或在群里 @ZAI 发一条新消息（不在任何话题里），会开始一个新的任务。

私聊

• 不需要 @ZAI。打开私聊的方法见打开私聊。
• 私聊里直接发的每条新消息（不在话题里）都是一个新任务，ZAI 在这条消息的话题里回复。
• 在这个话题里继续说，就是同一个任务。不同话题可以同时进行，各自的结果只回到各自的话题。

把 ZAI 拉进群

在飞书电脑端打开群，点右上角的 ··· 图标，进入 设置 > 群机器人 > 添加机器人，搜索 ZAI（或你们组织为它起的名字）并添加。搜不到时，请飞书企业管理员确认你在 ZAI 所在应用的可用范围内；无法添加时，请群主或群管理员来添加。

拉进群后不需要别的设置，在群里 @ZAI 就能发起任务。ZAI 在群里用组织为这个群准备的资源，见群里和私聊里用的资源与记忆。

群设置只允许部分成员发言时，ZAI 可能发不了言，见ZAI 不能在群里发言时。把 ZAI 移出群或解散群后各项功能会怎样，见ZAI 被移出群时。

在群里使用

• 用 @ZAI 发起任务，ZAI 在这条消息的话题里回复。群里每条 @ZAI 的新消息都是一个独立的任务；补充要求请回到对应的话题。
• 话题里的新消息会打断正在进行的任务：ZAI 手头正在运行的命令等操作先执行完（超过两分钟仍没结束的会被中止），再从新消息开始处理。之前的进展都保留，新消息没有改要求时，ZAI 会接着把原来的工作做完；想让它立刻停下，用 /stop。
• 引用一条消息不等于进入它的话题：在引用的消息上开始协助时，回复会留在这条被引用消息自己的话题里。
• 命令以 / 开头，例如 /status。完整清单见命令速查。

ZAI 什么时候回应

• 私聊里：你发的每条消息，ZAI 都会处理。
• 群里被 @ 时：@ZAI 的消息会开始一个任务。
• 在已经参与的话题里：ZAI 在一个话题里成功回复过一次后（被 @、有成员接受了它的主动协助建议，或它免确认介入），就会持续参与这个话题。任何成员继续发言都不必再 @，ZAI 会根据讨论决定发送回复、加一个表情回复，或保持安静；有人点名问另一位成员、它又没有对方缺的信息时，它不插话。
• 群里没有 @ 它的新消息：默认不处理。群里开启主动协助或免确认介入后，ZAI 可能主动提出建议或直接接手，见主动协助、免确认介入与 Dream。
• 只 @ 了其他机器人的消息：ZAI 不会接手，即使是在它已经参与的话题里。

在群的话题里发送 /mute 可以让 ZAI 不再跟进这个话题、也不在这里发言，进行中的任务不受影响；怎样恢复见静音话题。

ZAI 在后台判断要不要主动协助、整理群记忆，或者检查定时任务的运行条件、收到的 Webhook 是否符合事件订阅时，群里不会出现处理状态；只有真正开始执行的任务才显示。

处理状态与进度卡

ZAI 开始处理时，会在触发任务的消息上加处理中的表情，完成或失败时换成对应的表情，各表情的含义见你会看到什么。

ZAI 为任务列出清单时，话题里会出现一张进度卡，显示任务标题、最近一条说明、任务清单和更新时间，并原地更新；只有说明文字时不出卡。较长的进展先显示简短预览，点击「详细进展」展开；任务清单和「停止任务」按钮始终在折叠区域外。超过消息容量的内容会标注省略。

运行中可以点「停止任务」。任务结束后卡片保留最后的进展和状态，移除停止按钮；被中断、停止或未完成时，卡上会注明。本轮结束不代表清单里的每一项都已完成。

ZAI 在一次任务中可以发多条消息，但不先回“收到”“我先看看”，也不在话题里播报做到了哪一步，进展看处理状态和进度卡。要做几分钟以上、你又在等时，它可能先用一句话说明打算怎么做；中途遇到需要你决定的问题，或需要你据此处理的发现，会直接发出来；完成后再发结果。超过约一屏的结果（例如调研、完整的审阅、长清单）整理成文档交付，话题里只写结论、需要你处理的事和打开文档的入口，不拆成几条长消息；在群的话题里，ZAI 能新建飞书云文档时默认用云文档，私聊里用附件，见回复的形式。

ZAI 也能修改自己发过的文字消息，例如纠正措辞或更新一条汇总。你要它撤回某条消息，或它发错了地方、带出了不该出现的内容时，它会撤回自己发过的消息或文件，不会提醒任何人；超过企业管理员设置的撤回时限时，它会告诉你撤回不了。它发出的文件不会被它修改，失败卡片和命令回复既不会被它修改也不会被它撤回，进度卡由 ZAI 自动更新。

ZAI 只 @ 需要回答、决定或处理事情的人。在话题里回复向它提问、正在等它答复的人时不 @，对方照样会收到；只是提到某人、引用他的话，或告诉他不用做什么时，只写名字；私聊里不 @。修改消息不会提醒任何人，所以需要大家注意的新内容和需要某人看到的 @ 会另发新消息；更正一条 @ 过别人的结论时，更正同样 @ 这些人。它也不在短时间内反复 @ 同一个人。

组织开启回复审阅后，ZAI 的消息发出前会先经过检查，写法有明显问题或与话题里已有的内容重复时，会改写或不再发送；这一轮已经发过消息后，只预告下一步或播报进度的消息不发送；没有人请求的免确认介入对眼前讨论没有直接帮助时也不发送。

要停止任务，点进度卡上的「停止任务」，或在话题里发送 /stop；已经发出的消息和已经完成的操作不会撤回，见停止任务。

群里和私聊里用的资源与记忆

• 在群里，ZAI 只用组织允许在这个群里使用的资源和这个群的记忆，不会因为某位成员发言，就用上他的个人资源或私聊里形成的个人私有记忆；但会参考发言人的个人公开记忆和他在这个群的群内个人记忆，消息里 @ 了其他成员时也会参考被 @ 的人与问题相关的个人公开记忆和群内个人记忆，见记忆的作用范围。
• 在私聊里，ZAI 用你自己的资源，以及组织授权给你或全体成员的资源。

各类资源和申请方法见ZAI 能用哪些团队资源。如果你也在另一个 IM 里使用 ZAI，那里是另一个账号，资源和记忆不互通，见一个组织接入多个 IM。

请 ZAI 联系同事

在群里或私聊里都可以说：“请私聊通知张三，明天十点验收，发送后告诉我结果。”群里可以直接 @ 要联系的同事；只提供姓名且有重名时，ZAI 会请你选定具体的人。对方不需要事先和 ZAI 聊过，但须是已加入组织、且在 ZAI 所在应用可用范围内的用户。

消息由 ZAI 发到对方和 ZAI 的私聊里，末尾注明是你在哪个群（或在私聊里）请 ZAI 联系的。ZAI 在原来的话题里回报已发送、仍在投递或失败。

对方 7 天内直接回复这条消息（在话题里回复或引用回复都可以），回复会带回原来的话题或你的私聊：ZAI 在那里告诉你对方说了什么，需要追问时接着在同一条私聊里问对方。对方的消息上会出现「完成」表情，表示已经带回。对方没有回复那条消息、而是在私聊里另发一条时，ZAI 看出这是在回答你的问题，也会把他的原话带回去，同样打上「完成」表情；看不出来时会先问他。超过 7 天，或原来的话题已被 /mute 静音时，回复留在对方自己的私聊里，ZAI 在那里接着帮他。对方回复里的文件留在他的私聊里，ZAI 在原来的话题里读不到。

请 ZAI 在群里发通知

在群的话题里可以说：“在群里通知大家，周五下午发布。”ZAI 会在群里直接发一条新消息，不回在当前话题里。它的定时任务和事件订阅也可以这样发，例如有新的待合并 MR 时在群里提醒。

• 成员在这条消息的话题里回复，不用 @ZAI 也会得到跟进。ZAI 知道当时为什么发这条消息，需要更多背景时会读原来的话题。
• ZAI 在原来的话题里说明已经发出。
• 私聊里不能这样发；主动协助和免确认介入也不会在群里直接发消息。
• 原来的话题被 /mute 静音后，ZAI 不再从那里往群里发消息。

其他组织的成员

其他组织的成员指不属于 ZAI 所在飞书企业的人（外部联系人）。ZAI 所在的飞书应用开启对外共享后，ZAI 可以被拉进外部群，但不在外部群里工作：

• 在外部群里 @ZAI，只会在话题里收到「我不在外部群里工作，请在本组织的群或私聊里找我。」ZAI 确认一个群是外部群后，群里进行中的任务会停止，已经参与的话题也不再回复。
• ZAI 暂时确认不了一个群是不是外部群时，@ 它只会收到「暂时无法确认这个群是不是外部群，这次不作回答，请稍后重试。」
• 其他组织的成员发送的命令（以 / 开头的消息）不会执行，也不会收到回复。
• 他们私聊 ZAI 只会收到「其他组织的成员不能私聊使用我，我也不在外部群里工作。需要协助时，请本组织的成员在本组织的群里 @我。」

在外部群里，本组织成员仍可以用 /stop 停下进行中的任务、用 /mute 静音话题，也可以用 /proactive off、/proactive auto off、/dream off 这类命令关闭后台能力。主动协助、免确认介入、Dream、定时任务和事件订阅在外部群里都不运行，ZAI 也不在外部群里发 Artifact 卡片。

ZAI 能读到哪些消息

在和 ZAI 的私聊里，可以让它查询你和 ZAI 都在的群，例如“帮我整理项目群昨天的讨论，包括话题回复”。它可以读取 ZAI 在那个群里能看到的全部历史，即使消息早于你入群；你退出群或 ZAI 被移出后，不能继续查询。读取群消息不会让私聊取得这个群的资源。

外部群，以及开启保密模式、禁止复制和转发消息或禁止下载图片和文件的群，不能在私聊里查询：ZAI 不会列出这些群，也不读取其中的消息和文件；只禁止截屏录屏的群不受影响。ZAI 暂时确认不了一个群是不是外部群、有没有这样设置时，同样不读。需要处理这些群里的讨论时，请在群里 @ZAI（外部群里 ZAI 不工作，见其他组织的成员）。

群消息和话题会分页读取；如果尚未读完，ZAI 应说明实际检查的范围。个别话题 ZAI 无权查看时，它会跳过这些话题、照常查完其余内容，并应说明有几个话题没有检查。

查询共同群时，个别群一时读不出（例如群已解散，或飞书对这个群的回答不完整），ZAI 会跳过这些群、照常列出其余的群，并应说明可能少列了几个群。

ZAI 读历史时能看到消息下的表情回复和人数，例如 5 人点了 👍、1 人点了 👎，也分得清哪些是它自己加的处理状态表情；它不知道具体是谁点的。需要它统计谁确认了、谁投了哪一项时，请让大家用文字回复。一条消息下的表情很多时，它可能认不出其中哪个是自己加的。

被 @ 或跟进话题时，ZAI 会读取前面的讨论，需要时还能查询更早的群消息。在群里（不在话题里）@ZAI，或在话题群里新开话题 @ZAI 时，它读的是群里最近的消息和话题，每个话题只看首条消息，同时知道话题里有几条回复、最后一条是什么时候发的、它自己有没有在里面回复过，以及它最后一条回复的开头；需要时再读取话题里的回复。所以之前已经在话题里答复过的请求，它不会当作没人处理。读之前，它会向飞书补读一段消息：在群里提问时补读最近的群消息，在话题里提问时补读这个话题；其他机器人（例如告警、CI 通知）刚发的消息和卡片、ZAI 入群前的话题回复通常也在其中。刚有人问过 ZAI 不久、话题里的消息较多，或群设置不允许新成员查看入群前的历史时，这些消息可能读不到；需要它处理某一条时，请引用回复那条消息。自建应用的管理员可以开通一项可选权限，让其他机器人的群消息随时进入 ZAI 能读到的历史，见应用权限。更早的消息只包含 ZAI 观察到或补读过的。ZAI 能读到哪些群历史，见能读到哪些历史。已撤回、已删除或 ZAI 无权查看的消息，它读不到，也不影响读取其余历史。前面的讨论一时读不到时（例如飞书接口繁忙），ZAI 不会当作没有上文：需要时它会重新读取，仍读不到会告诉你。

文字、富文本、图片、文件和视频会按原内容交给 ZAI，并告诉它附件的类型和大小，视频另附时长和封面；以文件方式发出的图片和视频也会被当作图片、视频。语音消息会作为音频文件交给 ZAI，附上时长，它通常无法直接识别语音内容，请用文字说明任务。单个附件超过文件大小上限时，ZAI 取不到内容，只知道有这个文件；请拆分、压缩，或把关键内容用文字发给它，上限见常用限制。飞书一时下载不了某个附件时，ZAI 仍会知道有这个附件，需要时再去取。富文本里个别部分读不了时，只有那一部分换成提示，其余文字、图片和附件照常交给 ZAI。

卡片消息（包括转发来的其他应用的卡片）按卡片原文交给 ZAI：标题、正文、表格、图表的数据和按钮文字都会保留，卡片里的图片只保留标题和说明文字。卡片里的人员，ZAI 见过或已从通讯录同步的会显示名字，其余的在同一张卡片里按出现顺序编号（如 member 1、member 2）以便区分。飞书暂时读不到卡片原文时，ZAI 会稍后自动重新读取，回复会晚一些；仍然读不到时，ZAI 会得知这张卡片没有读全，不会把飞书「请升级至最新版本客户端，以查看内容」的提示当成卡片内容。

下列消息只以一行摘要交给 ZAI，ZAI 无法打开或操作原内容：

需要 ZAI 处理这些内容时，请把关键信息以文字发给它。

合并转发的聊天记录（包括转发的话题）会展开成一段引用交给 ZAI，并注明记录来自当前聊天还是其他聊天，但不会写出来源群的名称。每条消息标明发送者名称和发送时间：同一段记录里有人同名时，名字后加编号区分，例如「张伟 (1)」「张伟 (2)」；有几位发送者都没有名字时，按出现顺序编号（如 member 1、member 2，应用记作 app 1、app 2），只有一位时不加编号。被转发消息下的话题回复也会一并带上，并标明是话题回复。在私聊里只转发一段聊天记录、不附文字，同样会发起任务。

展开有上限：嵌套的转发最多展开三层；每次最多展开 50 条消息、约 2 万字，超出部分从末尾省略并注明条数，ZAI 需要时会接着往后读，直到读完整段记录。超过三层的嵌套转发只注明条数，单条超过约 2 万字的消息只能读到开头。记录中的 @ 只保留为文字，不会通知对方。记录里的图片和文件作为这条消息的附件交给 ZAI；省略部分里的图片和文件也会交给 ZAI，每次最多 100 个，超出的只注明数量。飞书拒绝下载时，ZAI 会得知这个附件无法获取。飞书暂时读不到这段记录时，ZAI 会稍后自动重新读取，回复会晚一些。

撤回与编辑

ZAI 收到之前就被撤回的消息不会发起任务，其中的命令也不会执行。消息发出后再撤回时：

• 由它发起、还没开始处理的任务会被取消。
• 已经开始的任务不会中途停止，但 ZAI 会知道这条消息已撤回，不再引用它的内容。它正在回答的消息都撤回了时，它会停下这项工作，不在话题、群里或私聊中为它发言；还有没撤回的消息时，回复发到其中最近的一条下。要立即中止，请在话题里发送 /stop。
• ZAI 已经发出的回复和进度不会随之撤回。
• 消息里的图片和文件，ZAI 之后在这个群或私聊里也读不到，还在进行的回复不会再把它们发回来，原处改为一条不写文件名的说明；ZAI 已经发到这里的同一个文件不受影响。更新日志里这项变化之前撤回的消息，其中的文件 ZAI 仍可能读到。
• ZAI 已经记住的内容不会因此忘掉，需要时按让 ZAI 记住、纠正或忘记的说明让它忘记。

撤回话题的首条消息不会关闭这个话题。

飞书里编辑消息不会通知 ZAI，也不会触发新的处理，ZAI 靠再读这条消息发现改动。开始处理一条请求前它会再读一次：在这之前（比如请求还在排队，或沙箱还在启动）做的编辑会被采用，ZAI 也知道这条消息改过。处理过程中它大约每 30 秒再读一次，回复之前也会读：发现改过时，它按编辑后的内容调整正在做的事，按旧内容写好的回复不会发出。用 /codex、/claude 只用一次指定的 Engine 的请求除外，按发出时的内容执行。任务结束后再编辑不会触发新的处理；ZAI 之后读历史时，看到的是编辑后的内容。

任务结束之后

所有任务完成后，话题空闲一段时间，这段工作就会结束：ZAI 清掉这个话题的工作上下文和它生成的临时文件。之后在原话题追问仍能继续，ZAI 会重新读取话题内容和记忆，见ZAI 会记住一个话题多久。没有发回话题的文件和临时安装的工具不会保留，需要留存的文件请让 ZAI 发回话题，见没发回的文件保留多久。想提前开始新的一段工作，在话题里发送 /restart。