> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorylake.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 飞书集成

> 把工作空间的记忆接进飞书：私聊机器人，或把它拉进群 @ 它提问

## 概述

飞书集成把一个**工作空间**里的智能体接到您自己的飞书机器人上。接好之后，团队成员不必打开控制台：

* 私聊机器人，或在飞书群里 @ 它，立刻拿到基于团队记忆库的回答
* 回答**逐字打字机式呈现**，不用干等一整段
* 发一份文档或一张截图给它，就能接着追问里面的内容
* 每次问答都会沉淀为记忆，同事再问时不必有人重复解释

机器人的回答来自您指定的项目记忆，不是通用大模型的泛泛之谈。

<Note>
  **飞书与 Lark 是两个独立平台。** 国内版是飞书（`open.feishu.cn`），国际版是 Lark（`open.larksuite.com`），账号与应用互不通用。本文针对**飞书**。您使用的是 Lark，请联系我们——连接哪一边由部署决定，不是在集成里选的。
</Note>

## 开始之前

<CardGroup cols={2}>
  <Card title="MemoryLake 侧" icon="database">
    * 团队的 **owner** 或 **admin** 角色（member 既看不到也改不了集成）
    * 一个工作空间，里面至少有一个项目
    * 至少一个**已关联到该工作空间**的智能体（在工作空间的「智能体」标签页关联）
  </Card>

  <Card title="飞书侧" icon="comments">
    * 飞书**管理员**权限：能创建应用、申请权限，并且**发布版本要管理员审核**
    * 一个用于测试的飞书群（可选，但强烈建议）
  </Card>
</CardGroup>

飞书侧配置约 10 分钟，**但发布版本要等管理员审核**——这一步不在我们控制范围内，建议提前打招呼。

<Warning>
  如果工作空间页里**没有**「集成」标签页，说明该部署没有启用 IM 渠道功能，或者您的角色是 member。请联系团队管理员确认。
</Warning>

## 第一部分：在飞书开放平台创建机器人

这部分全部在飞书侧完成，目的是拿到两样东西：**App ID** 和 **App Secret**。

<Steps>
  <Step title="创建「企业自建应用」">
    用飞书管理员账号登录 [飞书开放平台](https://open.feishu.cn/app)，创建**企业自建应用**。

    应用名称和图标会展示给您的同事，建议直接写团队认得出的名字，例如「记忆库助手」。

    <Warning>
      **必须是企业自建应用，不能是商店应用。** 我们用的长连接接入方式只支持自建应用。建错了类型，后面配置事件订阅时会发现根本没有「长连接」这个选项。
    </Warning>
  </Step>

  <Step title="添加「机器人」能力">
    进入应用详情 → **添加应用能力** → 添加**机器人**。

    没有这一步，后面所有消息相关的权限**都搜不到、点不亮**。
  </Step>

  <Step title="复制 App ID 与 App Secret">
    左侧**凭证与基础信息**页面，复制 **App ID**（形如 `cli_xxxxxxxxxxxxxxxx`）与 **App Secret**。

    这两个值随时可以回到这个页面再看，不用担心记不住。

    <Warning>
      但**不要**随手点「重置」。重置密钥会让正在使用旧密钥的集成**立刻失效**，必须回控制台重新填一次新密钥才能恢复。
    </Warning>
  </Step>

  <Step title="开通权限">
    左侧**权限管理**，逐个搜索并开通。控制台支持粘贴 JSON 批量导入。

    | 权限标识                            | 干什么用的         | 必需           |
    | ------------------------------- | ------------- | ------------ |
    | `im:message.p2p_msg`            | 接收私聊消息        | ✅            |
    | `im:message.group_at_msg`       | 接收群里 @ 机器人的消息 | ✅            |
    | `im:message:send_as_bot`        | 以机器人身份发消息     | ✅            |
    | `cardkit:card:write`            | 打字机式流式回答      | ✅            |
    | `im:message:readonly`           | 读取消息里的文件与图片   | ✅ 想要文档问答就必须有 |
    | `contact:contact.base:readonly` | 查用户姓名         | ⭕ 可选，见下      |
    | `contact:user.base:readonly`    | 同上            | ⭕ 可选，见下      |

    `cardkit:card:write` **现在就一起开**。飞书每新增一个权限都要重新发版、重新审核一轮，现在多勾一个，比两周后再走一遍审批省事得多。

    <Note>
      **流式回答不需要配置任何卡片模板。** 这个权限到位就自动生效，没有别的步骤。
    </Note>

    **关于 `im:message:readonly`：** 上面那三个 `im:message.*_msg` 只管「收到消息事件」，不含「读取消息里的资源」。没有它，机器人连私聊里发给它自己的文件都下载不了。它属于「读消息」的宽权限，管理员审批时会看到这个范围，值得提前说明。

    **关于两个 `contact:*`（可选，但要一起加）：** 飞书的消息事件里**不带发言人姓名**，只有一串 `ou_` 开头的 id。不配这两个，控制台「记忆身份」里每个人都显示成 `ou_c36c976b…`，认不出是谁——功能一切正常，只是不好核对。

    <Warning>
      这两个**必须一起加**：前者决定能不能调接口，后者决定返回里有没有姓名字段。只加前者的话，调用会「成功」但拿不到姓名，表现和完全没配一模一样，**没有任何报错**，很难自查。
    </Warning>
  </Step>

  <Step title="配置事件订阅">
    左侧**事件与回调** → 订阅方式选 **「使用长连接接收事件」** → 添加事件 **`im.message.receive_v1`**（接收消息）。

    <Note>
      如果这一步保存不了，先跳过，把权限和发布做完，等集成在控制台里连上之后再回来配（届时要再发一次版本）。这是飞书侧的校验时序问题，不是故障。
    </Note>
  </Step>

  <Step title="发布版本并让管理员审核">
    左侧**应用发布 → 版本管理与发布** → 创建版本 → 填版本号与更新说明 → **申请线上发布**。

    然后让管理员在**飞书管理后台 → 工作台 → 应用审核**里通过。

    <Warning>
      **权限只有在版本发布通过之后才真正生效。** 应用状态显示「待发布」或「有更改未发布」时，前面勾的权限一个都不算数。

      而且这不是一次性的：**后续每次新增权限或事件，都要再创建一个版本、再走一遍审核。**
    </Warning>
  </Step>
</Steps>

## 第二部分：在控制台创建集成

<Steps>
  <Step title="打开工作空间的「集成」标签页">
    在 [MemoryLake 控制台](https://app.memorylake.cn) 里进入 **MemoryLake → 工作空间**，打开目标工作空间，切到 **集成** 标签页，点 **开始接入**。

    在「选择要接入的平台」里选 **飞书**。
  </Step>

  <Step title="第一步：填写飞书应用信息">
    | 字段             | 填什么                     |
    | -------------- | ----------------------- |
    | **App ID**     | 飞书应用的 App ID（`cli_` 开头） |
    | **App Secret** | 飞书应用的 App Secret        |

    填完点 **下一步：智能体与记忆**。

    <Note>
      一个飞书机器人只能接入一处。如果这个 App ID 已经被别的集成用掉了，输入框下面会当场提示，并给一个「去编辑那一条」的入口。
    </Note>
  </Step>

  <Step title="第二步：选智能体与记忆范围">
    | 字段              | 说明                              |
    | --------------- | ------------------------------- |
    | **名称**          | 只用于控制台里辨认这条集成，已预填好，可改           |
    | **智能体**         | 负责回答飞书侧消息。只能选**已关联到当前工作空间**的智能体 |
    | **读写项目**（必选）    | 机器人检索并写入记忆的项目                   |
    | **额外的只读项目**（可选） | 机器人可以检索、但绝不写入的项目                |

    <Warning>
      **读写项目是一次授权决策。** 所有能用这个机器人的人，都在往这个项目里写记忆，也都能读到里面已有的内容。选一个本来就打算团队共享的项目，不要选放着敏感资料的那个。
    </Warning>

    <Note>
      下拉里选不到智能体，说明当前工作空间还没关联任何智能体。先去工作空间的「智能体」标签页完成关联，再回来创建集成。
    </Note>
  </Step>

  <Step title="创建并连接">
    点 **创建并连接**。集成创建后**默认就是启用状态**，服务端会立刻去建立与飞书的连接。

    卡片上的状态会从「连接中」变成「已连接」——通常几秒，最长一分钟左右。

    <Check>
      集成卡片上的状态徽标显示**已连接**。
    </Check>

    如果状态变成「异常」并提示「凭证无效，请检查 App ID / App Secret」，回到编辑弹窗核对这两个值。
  </Step>
</Steps>

## 第三部分：验证并开始使用

### 私聊

企业成员在飞书**工作台**里打开这个应用即可开始对话，直接发问题、不用 @。

### 群聊

把机器人**拉进群**，之后 **@ 它 + 问题**。机器人会**引用**您那条提问来回复，并 @ 回您——群里消息刷得快时，这两样能保证您不会漏掉答案。

机器人在某个群里第一次被 @ 时，会额外附一句能力说明，之后不再重复。

<Note>
  群里**只有 @ 了机器人的消息**才会投递给我们。这是飞书平台的机制，也意味着机器人看不到群里其他聊天内容。
</Note>

### 发文档和截图给它

* **私聊**：直接把文件或图片发给机器人，然后追问内容
* **群里**：@ 机器人时可以同时贴一张图（「@机器人 + 一句话 + 一张图」是同一条消息）

<Note>
  **群里想让它读文档，要用「引用」这个动作：** 先把文件发到群里，再**回复那条消息**并 @ 机器人。

  直接发文件给群里的机器人是**收不到的**——飞书的文件消息带不了 @，平台不会投递。引用之后我们能从您那条回复里反查到文件。
</Note>

### 会话与上下文

* **私聊是连续会话**：不会因为隔了多久而断，隔夜再问也接着上下文。想从头开始，发 `/new`
* **群聊按话题**：同一个人连续提问会接着上下文；**8 分钟**没说话之后再提问算新话题（刚发过文件时这个窗口放宽到 30 分钟，方便围绕同一份文件追问）
* 群里**每个人的上下文互相独立**，多人同时提问不会串味
* 私聊里发过的文件**不会过期**，一直跟着这个会话；同时最多带最近 **5 个**，发第 6 个时最早那个就不再参与了。`/new` 会一并清掉

### 谁是谁

每个飞书用户在 MemoryLake 里对应一个独立的**记忆身份**，个人相关的记忆归到各自身上；写入项目里的团队记忆则是所有人共享的。

配了两个 `contact:*` 权限的话，记忆身份会显示真实姓名，机器人也能答得上「我是谁」。

### 机器人暂时处理不了的

发语音、视频、表情包给它，会得到一句明确的提示（比如「我还听不了语音，请改用文字」），不会静默无反应。

## 管理已有集成

| 操作                | 位置与说明                                            |
| ----------------- | ------------------------------------------------ |
| **停用 / 启用**       | 集成卡片上的开关，**立刻生效**，不用等轮询                          |
| **轮换 App Secret** | 编辑 → App Secret 旁的「更换」按钮 → 填新值保存。不点「更换」就不会改动现有密钥 |
| **更换智能体**         | 编辑 → 智能体。**会重置该集成下所有进行中的会话**，成员正在进行的对话上下文将从头开始   |
| **调整记忆范围**        | 编辑 → 读写项目 / 只读项目。改完立刻生效                          |
| **删除集成**          | 卡片菜单 → 删除。会一并清除会话记录、身份映射和会话附件，**不可恢复**           |

<Note>
  **App ID 创建后不可修改**——它是这条集成的身份。要换成另一个飞书机器人，只能删掉重建。
</Note>

## 常见问题

<AccordionGroup>
  <Accordion title="工作空间里找不到「集成」标签页">
    两个可能：

    1. **该部署没有启用 IM 渠道功能。** 这个开关默认关闭，需要平台管理员开启。
    2. **您的角色是 member。** 配置集成要写第三方凭证，属于敏感写操作，只有团队的 owner 与 admin 有权限。
  </Accordion>

  <Accordion title="订阅方式里只有「发送到开发者服务器」，没有「长连接」">
    大概率应用建成了**商店应用**而不是**企业自建应用**。长连接只支持自建应用。

    自建应用里如果也看不到，检查第 2 步的「机器人」能力是否已添加。
  </Accordion>

  <Accordion title="权限勾了但不生效 / 机器人说读不了文件">
    飞书的权限**必须发布版本并通过审核之后才生效**。应用状态是「待发布」或「有更改未发布」时，勾选的权限一个都不算数。

    到**应用发布 → 版本管理与发布**创建版本、申请线上发布，再让管理员在管理后台审核通过。

    注意这不是一次性的：后续每次新增权限，都要再走一遍。
  </Accordion>

  <Accordion title="控制台显示「已连接」，但机器人在飞书里毫无反应">
    按顺序检查：

    * **事件订阅配了吗**：需要 `im.message.receive_v1`，且订阅方式是「使用长连接接收事件」
    * **应用发布通过了吗**：未发布时权限不生效
    * **群聊里真的 @ 了机器人吗**：群里只有 @ 到机器人的消息才会投递
    * **应用可见范围**：如果设了白名单，要用的人得在范围里，否则他们看不到这个机器人
    * **集成开关是否被停用**（停用时机器人会回「机器人当前不可用，请联系管理员。」）
  </Accordion>

  <Accordion title="状态显示「凭证无效，请检查 App ID / App Secret」">
    飞书侧拒绝了我们的建连请求，几乎总是这三种情况：

    * App ID 或 App Secret 复制时多了空格、少了字符
    * 密钥在飞书侧被**重置**过，控制台里还是旧值
    * 填的是另一个应用的凭证

    处理方式：编辑这条集成，核对 App ID；要换密钥，点 App Secret 旁的「更换」填入新值。改完保存会立刻重连。
  </Accordion>

  <Accordion title="回答是一整段蹦出来的，没有打字机效果">
    检查 `cardkit:card:write` 权限是否已开通**并且已随版本发布生效**。

    飞书这边流式不需要任何模板，只要这个权限到位就自动生效。权限不到位时我们会自动回落成普通消息——回答内容完整，只是没有逐字效果。
  </Accordion>

  <Accordion title="「记忆身份」里显示的是 ou_xxx 这一串，不是姓名">
    需要 `contact:contact.base:readonly` **和** `contact:user.base:readonly` 两个权限**都**开通并发布生效。只加前者会「调用成功但没有姓名」，表现和完全没配一样。

    <Warning>
      **已经建出来的记忆身份不会自动改名。** 姓名只在这个人第一次与机器人对话、系统为他建立记忆身份时写入一次。所以补上权限之后只对**新用户**生效，之前那些仍然显示 `ou_xxx`。想让某个人改过来，可以在「记忆身份」里删掉他那条，他下次发消息时会重新建立。
    </Warning>
  </Accordion>

  <Accordion title="在群里发文件给机器人，它完全不理">
    飞书的文件消息**带不了 @**，所以那条消息平台不会投递给我们，我们收不到任何东西。

    **正确姿势：先把文件发到群里，再「回复」那条消息并 @ 机器人。** 这样我们能从您的回复里反查到文件。

    私聊里直接发文件即可，没有这个限制。
  </Accordion>

  <Accordion title="私聊里问「我是谁」它答不上来，或答得莫名其妙">
    **答不上来**：需要两个 `contact:*` 权限（见上）。配好之后新建立的记忆身份会带上姓名。

    **答得莫名其妙**：私聊是连续会话，上下文不会因为隔了多久而断。如果您发一个表情、一句「好的」这类没有新信息的内容，机器人可能会接着**很久以前**那轮的话题回答。发 `/new` 开一段新对话即可。
  </Accordion>

  <Accordion title="同一个飞书机器人能接到两个工作空间吗">
    不能。一个 App ID 在整个平台只能被一条集成占用——否则飞书会把消息随机投给其中一条连接，回答会串到别的团队去。

    如果提示这个 App ID 已被占用：

    * 占用者在**同一个工作空间**：直接改那一条（提示里有「去编辑那一条」的入口）
    * 占用者在**同团队的其他工作空间**：先删掉原来那条，再在这里接入
    * 占用者在**其他团队**：出于安全考虑我们不会透露是谁，请在飞书开放平台新建一个应用

    需要一个机器人服务多个工作空间的记忆，正确做法是把这些项目作为**只读项目**加进同一条集成。
  </Accordion>

  <Accordion title="谁能用这个机器人？能不能配一份白名单">
    访问范围完全由**飞书侧**决定，我们刻意不做第二套白名单——两处配置漂移比没有配置更危险。

    具体来说：

    * **私聊**：由应用的**可用范围**决定（飞书开放平台里设置）
    * **群聊**：由**群成员**决定——机器人在群里，群成员就能 @ 它

    所以「机器人能被谁用」这个问题，答案在应用可用范围加上您把它拉进了哪些群。
  </Accordion>

  <Accordion title="成员之间的对话会互相看到吗">
    分两层看：

    * **对话上下文**是按人隔离的。群里每个人各有独立上下文，A 的提问不会出现在 B 的对话里。
    * **项目记忆是共享的。** 沉淀进读写项目的记忆，所有能用这个机器人的人都能检索到——这正是这个功能的价值，也是为什么创建时要把读写项目当成一次授权决策来选。

    个人相关的记忆会归到各人的记忆身份下，不进共享池。
  </Accordion>

  <Accordion title="机器人说「当前账户额度已用尽」或「当前请求较多」">
    两句话对应两件不同的事：

    * **「当前账户额度已用尽，请联系管理员升级套餐后再试。」** 团队的套餐额度耗尽了。**不充值不会自动恢复**，请联系管理员充值或升级套餐。
    * **「当前请求较多，正在排队，请稍后再发一次。」** 是我们这边一时繁忙，不是您发得太快，稍后重发即可。
  </Accordion>

  <Accordion title="删除集成会影响什么">
    会一并清除这条集成的会话记录、飞书用户与记忆身份的映射关系，以及会话里挂着的附件引用，且不可恢复。

    **已经沉淀进项目的记忆和已入库的文件不会被删** ——它们属于项目，不属于集成。

    只是临时停用的话，用卡片上的开关就够了，不要删。
  </Accordion>
</AccordionGroup>