飞书 IM
将 Cappy 项目接入飞书，配置机器人、权限、消息事件与自动开户，在私聊和群聊中分析数据。
将 Cappy 项目接入飞书后，用户可以在私聊或群聊中提问、追问并查看分析结果。
管理员配置
准备工作
需要飞书应用管理权限、Cappy 项目管理权限，以及企业管理员的发布审批。配置前确认：
-
Cappy 服务已启动，且能访问飞书开放平台。
-
Cappy 已配置模型和数据连接，能在网页中正常回答问题。
-
已确定允许使用机器人的人员范围。
创建应用并启用机器人
-
打开飞书开放平台开发者后台，创建一个企业自建应用。
-
填写应用名称和说明，例如「Cappy 数据助手」。
-
在应用中添加并启用机器人能力。
-
在「凭证与基础信息」中复制 App ID 和 App Secret，供后续连接 Cappy 使用。
妥善保管 App Secret。
图 1：启用机器人能力。
配置权限和人员范围
在飞书应用的「权限管理」中开通以下权限，可以按权限标识搜索：
| 权限标识 | 用途 |
|---|---|
im:message.p2p_msg:readonly | 接收用户发给机器人的私聊消息 |
im:message.group_at_msg:readonly | 接收群聊中 @ 机器人的消息 |
im:message:send_as_bot | 以机器人身份发送回复和卡片 |
im:resource | 上传并发送生成的图表、图片和文件 |
contact:contact.base:readonly | 读取发送者的通讯录信息 |
contact:user.email:readonly | 读取发送者的普通邮箱，用于匹配 Cappy 账号 |
图 2：开通消息与通讯录权限。
将目标用户同时加入以下两个范围：
-
应用可用范围：允许这些员工使用机器人。
-
通讯录可见范围：允许机器人读取这些员工的邮箱等信息。
Cappy 使用飞书通讯录的邮箱字段 email 匹配账号，请管理员为目标用户填写该字段。字段定义见飞书官方的获取单个用户信息。
将飞书应用连接到 Cappy
-
进入 Cappy，切换到需要接入飞书的项目。
-
打开项目设置 → IM 集成 → 飞书。
-
填入该应用的 App ID 和 App Secret，点击保存。
-
保持 Cappy 服务运行，等待连接建立。
-
按需选择模型；默认使用项目默认模型。
图 3：填写飞书应用凭据。
更换 App ID 时，填写对应的 App Secret；App ID 不变时，密钥留空会保留原值。
配置消息事件和卡片回调
在飞书应用的事件与回调中分别完成两项配置：
| 配置位置 | 接收方式 | 需要订阅的项目 |
|---|---|---|
| 事件配置 | 使用长连接接收事件 | 接收消息 im.message.receive_v1 |
| 回调配置 | 使用长连接接收回调 | 新版卡片回传交互 card.action.trigger |
在回调配置中添加 card.action.trigger（卡片回传交互），用于停止生成和反馈按钮。配置时保持 Cappy 服务在线。详见官方回调概述。
图 4：配置消息事件。
图 5：配置卡片回传交互。
发布应用并完成企业审批
在飞书应用的「版本管理与发布」中创建版本，确认应用可用范围，提交发布并完成企业管理员审批。之后修改权限或可用范围，也需要发布相应变更。
图 6：创建版本并提交审批。
发布后回到 Cappy，确认飞书状态为「已连接」。
自动开户与授权（可选）
自动开户与授权默认关闭。需要按邮箱域自动接入用户时，在「项目设置 → IM 集成 → 飞书 → 飞书自动开户与授权」中启用并设置：
| 设置项 | 填写方式 |
|---|---|
| 启用自动开户与授权 | 打开开关；初始默认关闭 |
| 允许的邮箱域 | 例如 example.com；多个域名用英文逗号、空格或换行分隔 |
| 默认项目角色 | 普通业务用户选择「分析师」，也是初始默认值 |
图 7：自动开户与授权设置。
点击保存，设置对后续消息生效。
邮箱域填写 example.com 这样的域名。多个域名用逗号或空白分隔；精确匹配，不区分大小写，不自动包含子域名，也不支持通配符。
创建账号和授予当前项目权限由同一个开关控制，处理规则如下：
| 用户当前状态 | Cappy 如何处理 |
|---|---|
| 已有当前项目的访问权限，包括通过用户组获得的权限 | 保留已有权限，不受自动开户邮箱域限制 |
| 没有 Cappy 账号，邮箱域符合已启用的自动开户配置 | 创建账号，并授予所选的当前项目角色 |
| 已有 Cappy 账号，但没有当前项目权限，邮箱域符合配置 | 为已有账号授予所选的当前项目角色 |
| 没有账号或项目权限，且自动开户未启用或邮箱域不符合配置 | 提示注册或联系项目管理员 |
邮箱域仅控制新增自动授权。移除邮箱域、关闭功能或更改默认角色，都不会改变已有权限；撤销权限请在项目的「访问权限」中处理。
用户邮箱用于识别和创建账号；SMTP 发信服务用于发送欢迎邮件与临时密码。未配置邮件服务也能在飞书中创建账号和提问；网页登录方式见自动开户后如何登录网页。
配置完成后，请目标用户私聊提问，确认收到回复；启用自动开户时，再确认新增用户的项目角色符合所选配置。
用户使用
第一次提问
在飞书中搜索管理员公布的机器人名称，打开私聊，发送业务问题，例如：
最近一个月各商品类别的销售额是多少？
符合自动开户条件时，Cappy 会自动创建账号并授予项目权限。若提示注册或无访问权限，请联系项目管理员处理。
私聊与追问
在私聊中直接发送文字。机器人会保留当前会话的上下文，你可以继续追问：
和上个月相比呢？
把结果画成柱状图。
切换到无关问题时，发送 /new 开启新会话，也可以把新问题写在同一条消息里：
/new 帮我分析最近一周的订单情况。群聊与追问
将机器人加入群聊后，每次提问都要使用飞书的 @ 功能选中机器人：
@Cappy 数据助手 帮我汇总最近一周的订单情况。
继续讨论时，在原消息的话题中回复，并再次 @ 机器人。同一话题保留上下文；开始新问题时另开话题。/new 仅用于私聊。
每位提问者都需要具备项目访问权限。机器人回复对群内成员可见，请选择适合讨论相关数据的群。
查看和操作结果
机器人可以回复分析文字、图表、地图和生成的文件。
-
停止生成：中断当前回答。
-
赞／踩：反馈回答效果。
-
在 Cappy 中查看：打开网页中的对话，需要能访问 Cappy 网页并登录有查看权限的账号。
停止和反馈按钮由本次提问者操作。机器人要求补充信息时，直接回复文字或选项编号；群聊中仍需 @ 机器人。
常见问题
自动开户后如何登录网页？
飞书自动开户不会自动登录 Cappy 网页。
新账号收到欢迎邮件后，可使用邮件中的临时密码登录，并按提示修改密码。没有收到邮件时，请管理员检查 SMTP 发信服务，或协助重置密码。已有账号继续使用原来的登录方式。
关闭自动开户会撤销已有权限吗？
不会。关闭功能、移除邮箱域或修改默认角色，只影响后续自动授权。已有用户的权限需要在项目的 访问权限 中单独调整。
可以上传文件给机器人分析吗？
机器人读取文字和富文本中的文字，不读取通过飞书上传的图片、语音或附件。需要分析文件时，使用 Cappy 网页的上传入口。
服务重启后需要重新提问吗？
已保存的会话历史会保留；中断时尚未完成的请求需要在服务恢复后重新发送。