连接 Lark / 飞书

先按 图文安装教程 安装插件，确认本地 Bot DM 正常后，再继续本页。

把一个 PersonaBot 接入工作群：先连接应用机器人，再绑定 Bot 身份并授权群，最后选择消息进入 Bot 收件箱还是本地频道。

本页以 Lark 国际版、应用机器人、测试群、只收 @ 为起点。飞书用户使用同样的配置顺序，但要选择飞书平台、使用飞书开放平台创建的应用。

#先分清三个设置

绑定身份后，还要明确授权群。绑定身份不会自动接收所有群消息；添加频道连接器也不会给其他 Bot 借用这个身份。

本页结合真实界面入口与已完成 Lark 连接的测试 Profile。已连接截图来自 #823 验证的产品产物（0.0.0-test.823.6 / Provider 4.32.0-botharness.2）；测试群为「BotHarness IM QA #78」。空表单截图用于说明填写位置，不代表已完成连接。App Secret 不出现在媒体中。右键（手机长按）截图，可查看原图。

#1. 准备可用环境

你需要：

• 已加入 Lark / 飞书组织，并有创建、发布企业自建应用的权限，或能请组织管理员协助。
• 一个用于验证的群，以及一个能在该群发送消息的 Human 账号。
• 已运行的 BotHarness、可用模型和一个 PersonaBot。先在本地 DM 中确认 Bot 能正常回复。
• 包含已验证 IM Provider 的 BotHarness 产品。产品把 Core、Client 与 Provider 一起安装；不用另外安装 Lark SDK、Human lark-cli 或任意版本的 dsh-im。

公开 npm 产品尚未发布。 当前可复现路径是构建本地产品包；不要把下面的测试版本当成 npm 安装命令。已有 #823 验证产物的用户直接启动同一 Profile，然后进入下一节。

git clone https://github.com/BotHarness/BotHarness.git botharness-lark
cd botharness-lark
git checkout c2a1f7cba13d1ba82e1b9e9b3b923babe428c0e7
git clone https://github.com/DoodleBears/dsh-im.git /tmp/bh-lark-provider
git -C /tmp/bh-lark-provider checkout 48e7a35792af5222cd40cfe1ba2607ac55a59df2
npm ci --prefix /tmp/bh-lark-provider --ignore-scripts --no-audit --no-fund
pnpm install --frozen-lockfile
pnpm build
node scripts/product-artifacts.mjs \
  --provider-source /tmp/bh-lark-provider \
  --output /tmp/bh-lark-product \
  --version 0.0.0-test.lark-guide
node scripts/dev-instance.mjs \
  --home "$HOME/.local/share/botharness-lark" \
  --port 32620 --product-artifacts /tmp/bh-lark-product

启动器输出的登录 URL 只在本机打开，不放进截图或视频。下次使用同一个 --home，保留账号、授权和消息记录；同一个应用只由一个 Host 接收事件。完整打包背景见 产品安装说明。

#操作视频：连接、授权、确认消息

以下是真实界面截图的分步剪辑，不是连续录屏或模拟连接成功。可暂停、拖动进度或打开中英文字幕；首次播放才下载视频。

下载视频 · 中文字幕 · English captions

观看顺序：0:00 应用凭据与权限 → 0:32 本机连接 → 0:48 事件订阅与发布 → 1:12 投递目标 → 1:20 身份与群授权 → 1:36 消息来源。下文保留可逐项执行的步骤。

#2. 在开放平台准备应用机器人

Lark 打开 Lark 开发者后台；飞书打开 飞书开发者后台。账号、组织和应用必须属于同一个平台。

1. 创建企业自建应用，给它取一个容易认出的名字，例如「团队助手」。群里的自定义 Webhook 机器人只适合通知，不是本页的双向应用机器人。
2. 添加机器人能力，在「凭证与基础信息」找到 App ID 和 App Secret。
3. 为应用身份配置消息权限。Human 扫码登录的用户权限不能代替应用权限。
4. 在事件配置中使用长连接，订阅 im.message.receive_v1（接收消息事件）。如果后台要求先建立长连接，先完成下一节的本机连接，再回来保存订阅。
5. 创建并发布应用版本；按组织要求完成管理员审批和可用范围配置。把应用机器人加入测试群。

权限按用途开通：

• im:message.group_at_msg:readonly：接收群里 @机器人的消息；首次群收件验证需要。
• im:message:send_as_bot：以应用机器人身份发送、回复；首次回复验证需要。
• im:message:readonly：读取消息与消息资源；主动读取原消息、附件等能力需要。
• im:message.group_msg：获取群组中所有消息；普通消息收件、群历史与话题跟进需要。这是敏感权限，按需要开通。
• im:resource：上传图片、文件等资源；需要发送附件时开通。

权限是否可申请、是否需要审批，以你的组织后台为准。开通全群消息权限后，BotHarness 仍按明确授权的群和收件条件处理，不会自动把所有消息放进 Inbox。接口细节可参考 接收消息事件 和 获取历史消息。

#对照真实后台配置

这个新应用是在 Lark 后台实际创建的 #824 引导测试应用。三项权限的 Type 均为 Tenant token，状态为 Added。顶部仍显示 Pending release：加入权限不等于已生效。先建立本机连接、保存接收消息的事件订阅，再发布版本，之后才能验证群收件。此例没有开启全群消息权限。

以下旧版参考截图来自已发布的测试应用，本轮只读核对配置。新应用仍需自己完成添加能力、申请权限、发布和管理员审批。不要照搬测试应用的全部权限或事件。

进入 Credentials & Basic Info 找到凭据；复制密钥到本机表单，不要点击展示密钥后截图。

在 Add Features 添加 Bot；添加后出现左侧 Bot 设置页。

进入 Permissions & Scopes，搜索权限名，Type 选 Tenant token scopes。im:message.group_msg 是敏感权限，只有需要普通消息、群历史或话题跟进时才申请；图中的置顶、表情等权限不是本页要求。

搜索 im:message:send_as_bot，确认 Type 为 Tenant token、状态为 Added；还要发布变更才会生效。

进入 Events & Callbacks → Event Configuration，Subscription mode 选择 persistent connection。连接由产品内的 Provider 建立，不用另开一个 SDK 接收进程。

在 Events added 中核对 im.message.receive_v1 与 Tenant token。首次收件不需要图中的已读、表情、会议事件；本页不使用它们。

进入 Version Management & Release 创建并发布版本，按组织要求完成审批；Released 和顶部已发布提示是本例的成功状态。

#3. 在本机连接应用

1. 打开左下角 设置 → IM机器人 → 飞书。
2. 打开 手动接入；应用平台选择 Lark（国际版）。飞书应用选择飞书，不能混用凭据。
3. 私下填入 App ID 和 App Secret，点击 绑定并连接。
4. 确认账号显示已连接；如果刚补了事件订阅或应用权限，回后台发布后再确认连接。

图 1：Lark 应用选择国际版。密钥只输入本机设置，不粘贴到聊天、Git 或公开截图。界面的飞书扫码接入与 Lark CLI 的 Human 登录是不同流程；本页使用应用凭据接入。

图 1b：真实账号的绿色「运行正常」 只证明传输在线；还要绑定 PersonaBot、授权群，并核对消息来源与回复。

接着为该账号配置一个投递目标：

1. 打开已连接机器人的设置，找到 投递目标 → 新建目标。
2. 从 从已聊过的会话选择 中选测试群，检查显示名称和群 Chat ID；或手动填写平台提供的原生群 ID（oc_…），不要填群名称或消息 ID。
3. 填一个调用别名，例如 lark-test-group，点击 测试，到 Lark 群确认测试消息，再点击 保存目标。

全新应用可能没有会话候选。#824 实测中，绑定 PersonaBot 前的预备 @消息没有立即填充列表，且进入了 Provider 自己的独立会话路径。建议手动填入已核实的原生群 Chat ID，再测试、保存；不知道 ID 时请向群管理员核实。独立会话的回复或发现目标的消息，都不是 BotHarness 的 canonical 收件证据。

账号设置 → 投递设置 → 投递目标。这里的测试、保存目标只确认发送目的地；下一节还需给 PersonaBot 绑定身份并授权。

#4. 绑定 PersonaBot 身份并授权群

在 Bot 模式打开目标 Bot 的 DM，点击顶部 Bot 名称，再点 查看详细，进入详细 Profile。 点击 配置引导，选择应用平台、IM账号和保存的指定群目标。每个群独立核对；其他群的成功不能替代本群验收。步骤的「定位现有控件」打开或高亮实际设置，完成状态由实际配置和关联收件／回复决定。

操作示意：①绑定身份 → ②授权具体群 → ③可选接入频道。这是基于截图的 AI 辅助合成标注图，演示账号尚未连接；下方保留原始界面截图供对照。

1. 找到 外部身份 → 绑定身份，在 IM账号中选择刚连接的应用机器人，保存。
2. 展开 频道连接器与授权，选择该 IM账号和刚保存的发送目标。
3. 点击 绑定并授权此目标。核对群名称、账号和本地收件位置。
4. 初次验证保留 仅此 Bot 的 Inbox、只收 @。不用额外创建本地群，也不会占用 Bot DM 的消息历史。

图 2：外部身份属于 PersonaBot。列表为空时，先检查上一步的应用连接、Provider 版本和保存目标。Human 扫码登录不等于绑定 Bot 身份。

图 3：先绑定身份，再在「频道连接器与授权」中授权具体群。示例尚未连接账号，所以授权控件尚不可用。

图 3b：真实测试群已绑定并授权，群接收已连接；普通消息收件仍未开启。截图中“继承全局默认”与“只收 @”是不同的配置字段。

每个 Bot 可以绑定多个平台，每个平台绑定一个身份。同一个 Bot 在不同本地群中仍使用自己的外部身份。共享频道的其他 Bot 如需对外回复，也要绑定自己的身份并获得目标群授权。

#5. 可选：把消息显示在本地频道

只想在 Lark 聊天、让消息进入 Bot Inbox，可以跳过这一节。如果希望团队在本地共同看到外部消息，打开已有 Group Channel 的详细 Profile；先把负责接收的 Bot 加为成员。也可以把来源接入 Bot DM 的消息历史。

在 频道连接器 → 添加频道连接器 中：

1. 选择已授权的 Lark 群。这里不创建外部账号或新增群授权；列表为空就返回上一节。
2. 确认投递目标：共享群频道、DM 消息历史，或仅 Bot Inbox。可选项取决于当前 Channel。
3. 填入容易辨认的连接器名称，例如「Lark 团队工作群」。
4. 保留继承全局默认，或明确选择仅收 @接收身份；开启接收并保存。

图 4：来源、投递位置和接收条件分别选择。演示账号尚未授权群，所以保存按钮不可用；真实配置完成后才可保存。

一个频道可接入多个来源，同一外部来源也可接入多个目标。连接器决定收什么，每个成员 Bot 的 Attention / 唤醒策略决定何时处理。外部消息会以来源名称显示在消息气泡上方，点击来源打开详情；在本地普通回复不会自动广播回 Lark。

首次跑通后再调整高级行为：

• 全局默认在 设置 → Bot 设置中管理；Profile 可继承或覆盖，只影响后续消息，不补收历史。
• 要接收不带 @ 的普通消息，先发布相应应用权限和事件订阅，在已授权测试群发送一条无 @ 消息，再刷新验证结果。尚未验证真实普通消息投递时，全量收件选项不可用。
• 在群的收件与唤醒设置中选择按条数 / 时间汇总或逐条唤醒。进入 Inbox 不代表必须立刻回复，Bot 可以判断是否参与。
• Bot 要继续接收某个话题的无 @ 回复，需要显式跟进话题；回复一次不会自动跟进。平台必须实际把这些事件投递给应用。
• 暂停连接器的 Switch 保留配置与历史；删除连接器不删除已收消息。解绑身份是独立操作，会影响该 Bot 依赖此身份的外部行为。

#6. 确认真的跑通

先做一个小测试：在授权的 Lark 群 @应用机器人发送「请在这里回复 LARK-OK」，不要同时测试多个 Bot 或多条路由。

成功应能逐项确认：

1. Bot DM 右侧的 Bot 收件箱出现该消息，来源是正确的 Lark 群，带原始发送人与消息内容。
2. 点开来源详情，能看到外部消息 ID、Source Event ID，以及存在时的话题信息。
3. Lark 原会话收到这个 Bot 以自己的应用身份发出的 LARK-OK。若在话题内测试，回复仍在原话题。
4. 默认只收 @ 时，再发送一条不带 @ 的普通消息，确认它不会作为新的普通收件触发该 Bot。已显式跟进的话题按话题策略处理。

图 5：这是已收件的真实话题消息。Source Event ID 是 BotHarness 的来源定位符；外部 message / thread / root / parent ID 由 Lark 提供，不能用本地 Channel ID 替代。

在 Bot DM 右侧展开 Bot 收件箱 → 群名；若消息已处理，再展开「已处理或忽略」。点击消息打开 Modal，然后展开「来源详情」和「消息详情」。发送人名字无法解析时会显示平台 ID。

不要以 Lark 消息旁的绿色 / 灰色已读圆圈判断 Bot 是否收件。以本地 Inbox 来源记录和实际外部回复为准。

#常见问题

如果需要协助，提供平台、操作步骤、可公开的错误码和已经完成的检查。不要附 App Secret、访问令牌或群中无关的消息内容。

##824：真实新应用操作记录

以下是新应用的真实压缩截图，不是模拟成功。应用通过真实后台发布为 1.0.0，只加入指定 QA 群；本机连接、目标测试和保存、PersonaBot 身份绑定与指定群授权都通过产品界面完成。首次实测产物为一次安装的 0.0.0-test.824.6，新增指定群选择后的最终复验为 0.0.0-test.824.7（Provider 4.32.0-botharness.2），没有另装接收进程。上文旧 #823 图与视频保留为参考，不替代本次新应用实测。

连接正常仅确认 Provider 在线，尚不代表 Inbox 已收件。

长连接验证失败时先建立本机连接，再保存 im.message.receive_v1。

发布、审批和可用范围与本机连接是不同状态。

测试消息到达指定群后，保存投递目标。

前四步来自真实配置；点击引导不会推进完成状态。

无 @根消息未入库；两条指定 @消息进入该 Bot Inbox，LARK-SETUP-OK 在同一话题以新应用身份出现。截图裁掉无关会话；平台已读圆圈不是 canonical 收件证据。

原文 [BH-LARK-SETUP] 的 Source Event 末尾为 f708a3f1，对应 Inbox 已处理、关联回复为平台已接受。未观测到自身回传，引导要求 Human 到原话题核对。

关闭重开和重启同一 Profile 后配置历史保留；重新加载后选择原账号核对。停用、撤销授权、解绑与移除账号使相应步骤重新待确认。验收后用原生移除接入停止接收并删除本机配置及凭据；外部应用保留，后台凭据重置仍由管理员操作。