连接飞书机器人
创建飞书应用、配置消息接收、连接 Onevium，并验证两轮回复。
渠道把飞书群连接到 Onevium#
本教程创建飞书企业自建应用，把机器人接入 Onevium，再验证两轮群聊。平台步骤使用中国大陆飞书后台；Lark 的凭据和接口域名不能直接当成同一配置。
创建平台应用#
- 打开飞书开发者后台，在目标企业创建自建应用。
- 在添加应用能力 → 机器人启用机器人，填写名称和图标。
- 到凭证与基础信息取得 App ID、App Secret，稍后填入 Onevium 的专用字段。
- 准备测试群，应用可用范围需要包含测试成员。
Onevium 通过长连接接收事件，此流程不需要自行部署公网回调服务器。
配置消息、事件和卡片#
在权限管理按需要添加下列能力：
| 需要的能力 | 权限标识 |
|---|---|
| 接收群成员 @机器人的消息 | im:message.group_at_msg:readonly |
| 接收用户私聊，启用私聊时需要 | im:message.p2p_msg:readonly |
| 以机器人身份发送回复 | im:message:send_as_bot |
| 创建和更新流式卡片实体 | cardkit:card:write |
标识分别来自官方接收消息事件、发送消息接口和创建卡片接口。提交所选权限，组织要求审批时等待通过后再测试。
在事件与回调选择使用长连接接收事件，添加接收消息 v2.0，事件标识为 im.message.receive_v1。使用卡片审批按钮时，还要配置 card.action.trigger 回调。保存配置，创建版本并发布到测试成员范围。
后台提示没有可用长连接时，先完成下方 Onevium 连接并确认运行，再返回验证、保存订阅；不必为连接状态问题重新创建应用。
填写 Onevium 连接#
打开渠道 → 新建渠道，选择单个机器人、飞书，填写 App ID 和 App Secret，点击注册凭据，检查通过后继续。
| 字段 | 首次测试填写方法 |
|---|---|
| 机器人名称 | 文档助手 |
| 描述 | 回答演示项目的问题 |
| 模型 | 选择普通会话中已可用的提供商和模型 |
| 工作目录 | 点击选择目录，选演示项目 |
| 会话模式 | 每人独立会话 |
| 聊天范围 | 仅群聊 |
| 自动批准操作 | 首次选择“每项操作前询问” |
| 角色描述 | 可选，用一句话概括职责 |
| 系统提示词 | 使用下方示例 |
你是演示项目的文档助手。
回答用户明确指定文件的问题。
修改文件或运行命令前，先说明准备执行的动作。
连接测试时，在当前会话记住测试代号。
保存后查看运行状态；处于停止状态时点击启动。把已发布机器人加入飞书测试群，保持电脑和 Onevium 运行。
验证两轮回复#
在群中 @机器人：“本次测试代号 alpha-27。”收到回复后再 @它询问代号。应得到 alpha-27，并能在 Onevium 对应聊天中找到执行记录。
需要共享上下文时，打开该聊天的聊天设置 → 会话模式，切为所有人共享会话，再用两个测试用户复测。会话共享不会自动增加读取平台历史消息的权限。
按需增加能力#
| 新需求 | 要补充什么 |
|---|---|
| 私聊 | 添加 im:message.p2p_msg:readonly，开放私聊范围并设置私聊策略/允许用户 ID |
| 上传图片、文件 | 添加 im:resource 或对应上传权限，再单独测试附件 |
| 显示成员、群名称 | 需要相应查询时检查 contact:user.base:readonly、im:chat:readonly |
| 接收未 @机器人的群消息 | 需要 im:message.group_msg 等更广的群消息权限，并开启聊天的“被动上下文” |
选配权限见官方文件上传、用户查询和群信息查询。普通群聊回复不需要顺带申请文档写入或幻灯片写入权限。
按阶段排错#
- 注册凭据失败：检查 App ID、Secret 是否来自同一应用，阅读界面网络或令牌错误。
- 已运行但没收到消息：核对
im.message.receive_v1、长连接方式、发布范围、群成员和 @方式。 - 收到消息却没回复：检查模型结果、待审批动作和发送权限。
- 卡片失败：检查
cardkit:card:write和平台错误。Onevium 有回退消息路径，仍要在群里确认最终文字可读。