> ## 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.
# 钉钉集成
> 把工作空间的记忆接进钉钉：把机器人拉进群，成员 @ 它就能问到答案
## 概述
钉钉集成把一个**工作空间**里的智能体接到您自己的钉钉机器人上。接好之后，团队成员不必打开控制台：
* 在钉钉群里 @ 机器人，立刻拿到基于团队记忆库的回答
* 配一张报错截图一起 @ 它，它能看懂图再接着答
* 每次问答都会沉淀为记忆，同事再问时不必有人重复解释
机器人的回答来自您指定的项目记忆，不是通用大模型的泛泛之谈。
## 开始之前
* 团队的 **owner** 或 **admin** 角色（member 既看不到也改不了集成）
* 一个工作空间，里面至少有一个项目
* 至少一个**已关联到该工作空间**的智能体（在工作空间的「智能体」标签页关联）
* 钉钉**管理员**权限：能在开放平台创建应用、申请权限并发布上线
* 一个用于测试的钉钉群（可选，但强烈建议）
全程约 10 分钟。
如果工作空间页里**没有**「集成」标签页，说明该部署没有启用 IM 渠道功能，或者您的角色是 member。请联系团队管理员确认。
## 第一部分：在钉钉开放平台创建机器人
这部分全部在钉钉侧完成，目的是拿到三样东西：**Client ID**、**Client Secret**，以及（可选的）**AI 卡片模板 ID**。
用钉钉管理员账号登录 [钉钉开放平台](https://open-dev.dingtalk.com/)，进入 **应用开发 → 钉钉应用 → 创建应用**，类型选**企业内部应用**。
应用名称和图标会展示给您的同事，建议直接写团队认得出的名字，例如「记忆库助手」。
打开刚创建的应用，进入 **应用能力**，添加 **机器人** 能力。填写机器人名称与简介后，把**消息接收模式**设为 **Stream 模式**。
这是整个流程里最容易出错、而且默认值不对的一步。选成 HTTP 回调模式，机器人一条消息都收不到，而控制台里的连接状态仍然会显示「已连接」——因为连接确实建立了，只是钉钉不往这条连接上投递消息。
需要更详细的钉钉侧说明，可参考钉钉官方文档：
* [创建并安装应用机器人](https://open.dingtalk.com/document/orgapp/the-creation-and-installation-of-the-application-robot-in-the)
* [Stream 模式介绍](https://open.dingtalk.com/document/development/introduction-to-stream-mode)
在应用的**凭证与基础信息**页面，找到 **Client ID**（旧版界面叫 AppKey）与 **Client Secret**（旧版叫 AppSecret），两个值都复制下来。
这两个值随时可以回到这个页面再复制一次，不用担心记不住。
但**不要**随手点「重置」。重置密钥会让所有正在使用旧密钥的集成**立刻失效**，必须回控制台重新填一次新密钥才能恢复。
默认情况下，机器人会等回答**完整生成之后**一次性发出。如果希望回答像打字机一样逐字出现，需要额外做两件事：
1. 在应用的**权限管理**里申请 `Card.Instance.Write` 和 `Card.Streaming.Write` 两个权限点。
2. 打开[钉钉卡片平台](https://open-dev.dingtalk.com/fe/card)，创建一个 **AI 卡片**场景的模板，记下模板 ID。
模板怎么建、这个场景钉钉自己是怎么用的，可参考官方文档：
* [AI 卡片模板](https://open.dingtalk.com/document/development/ai-card-template)——模板的创建与发布流程
* [打字机效果流式 AI 卡片](https://open.dingtalk.com/document/development/typewriter-effect-streaming-ai-card)——钉钉官方的完整使用场景示例（对接大模型的 AI 机器人）
跳过这一步集成照样能用，只是没有流式效果。
两个权限点漏掉任何一个，卡片投放会被钉钉直接拒掉。表现是「填了模板 ID 但还是一次性回复」，钉钉侧和控制台都不会给任何报错——这是线上真实踩过的坑。
进入**版本管理与发布**，先确定**应用可见范围**（这个应用对哪些同事可见），然后**发布上线**。
## 第二部分：在控制台创建集成
在 [MemoryLake 控制台](https://app.memorylake.cn) 里进入 **MemoryLake → 工作空间**，打开目标工作空间，切到 **集成** 标签页。
第一次进入是一个空态，点 **接入钉钉** 打开接入向导。
向导第一步要的三个字段，全部来自第一部分：
| 字段 | 填什么 |
| ----------------- | --------------------- |
| **Client ID** | 钉钉应用的 Client ID |
| **Client Secret** | 钉钉应用的 Client Secret |
| **AI 卡片模板 ID** | 可选。留空则一次性回复；填了则逐字流式回复 |
填完点 **下一步：智能体与记忆**。
一个钉钉机器人只能接入一处。如果这个 Client ID 已经被别的集成用掉了，输入框下面会当场提示，并给一个「去编辑那一条」的入口。
| 字段 | 说明 |
| --------------- | ------------------------------- |
| **名称** | 只用于控制台里辨认这条集成，已预填好，可改 |
| **智能体** | 负责回答钉钉侧消息。只能选**已关联到当前工作空间**的智能体 |
| **读写项目**（必选） | 机器人检索并写入记忆的项目 |
| **额外的只读项目**（可选） | 机器人可以检索、但绝不写入的项目 |
**读写项目是一次授权决策。** 所有能用这个机器人的人，都在往这个项目里写记忆，也都能读到里面已有的内容。选一个本来就打算团队共享的项目，不要选放着敏感资料的那个。
下拉里选不到智能体，说明当前工作空间还没关联任何智能体。先去工作空间的「智能体」标签页完成关联，再回来创建集成。
点 **创建并连接**。集成创建后**默认就是启用状态**，服务端会立刻去建立与钉钉的连接。
卡片上的状态会从「连接中」变成「已连接」——通常几秒，最长一分钟左右，页面会自己刷新状态。
集成卡片上的状态徽标显示**已连接**。
如果状态变成「异常」并提示「凭证无效，请检查 ClientID / ClientSecret」，回到编辑弹窗核对这两个值。
## 第三部分：验证并开始使用
### 群聊
把机器人加进群：**群设置 → 机器人 → 添加机器人**，选择您刚创建的应用。之后在群里 **@ 机器人 + 问题** 即可，机器人回复时会 @ 回提问的人。
机器人在某个群里第一次被 @ 时，会额外附一句能力说明，之后不再重复。
### 带截图提问
在群里 @ 机器人时**可以带一张截图**：「@机器人 + 一句话 + 一张图」是一条图文混排消息，机器人能收到并看懂图里的内容，适合拿报错截图直接问。
### 会话与上下文
* 同一个人连续提问会接着上下文；**8 分钟**没说话之后再提问，算新话题（刚发过截图时，这个窗口放宽到 30 分钟，方便围绕同一张图追问）
* 群里**每个人的上下文互相独立**，多人同时提问不会串味
* 发 `/new` 可以手动开始新对话（会一并清掉之前发过的截图）
### 谁是谁
每个钉钉用户在 MemoryLake 里对应一个独立的**记忆身份**，个人相关的记忆归到各自身上；写入项目里的团队记忆则是所有人共享的。
机器人只处理**本企业成员**的消息，外部联系人的消息一律忽略且不作任何回应。
## 管理已有集成
| 操作 | 位置与说明 |
| -------------------- | --------------------------------------------------- |
| **停用 / 启用** | 集成卡片上的开关，**立刻生效**，不用等轮询 |
| **轮换 Client Secret** | 编辑 → Client Secret 旁的「更换」按钮 → 填新值保存。不点「更换」就不会改动现有密钥 |
| **更换智能体** | 编辑 → 智能体。**会重置该集成下所有进行中的会话**，成员正在进行的对话上下文将从头开始 |
| **调整记忆范围** | 编辑 → 读写项目 / 只读项目。改完立刻生效 |
| **删除集成** | 卡片菜单 → 删除。会一并清除会话记录、身份映射和会话附件，**不可恢复** |
**Client ID 创建后不可修改**——它是这条集成的身份。要换成另一个钉钉机器人，只能删掉重建。
## 常见问题
两个可能：
1. **该部署没有启用 IM 渠道功能。** 这个开关默认关闭，需要平台管理员开启。
2. **您的角色是 member。** 配置集成要写第三方凭证，属于敏感写操作，只有团队的 owner 与 admin 有权限。
另外，集成入口在**工作空间**详情页下，不在智能体详情页里——如果您记得它以前在智能体页面，它已经搬走了。
最常见的原因是**消息接收模式没设成 Stream**。
「已连接」说的是我们与钉钉之间的长连接建起来了，这件事在 HTTP 回调模式下同样成立——只是钉钉不会往这条连接上投消息。回到钉钉开放平台，检查应用的「机器人」能力里，消息接收模式是不是 **Stream 模式**。
其余要检查的：
* 应用是否已**发布上线**
* 群聊里是否真的 **@ 了机器人**——群里只有 @ 到机器人的消息才会投递
* 集成开关是否被停用了（停用时机器人会回「机器人当前不可用，请联系管理员。」）
钉钉应用还处于未发布状态。未发布时钉钉不会在回调里返回发送者身份，我们无法判断发消息的人是谁，因此只能给这一句提示。
到钉钉开放平台的**版本管理与发布**页面完成发布上线，然后重新发一条消息即可。
钉钉侧拒绝了我们的建连请求，几乎总是这三种情况：
* Client ID 或 Client Secret 复制时多了空格、少了字符
* 密钥在钉钉侧被**重置**过，控制台里还是旧值
* 填的是另一个应用的凭证
处理方式：编辑这条集成，核对 Client ID；如果要换密钥，点 Client Secret 旁的「更换」填入新值。改完保存会立刻重连。
优先检查权限：`Card.Instance.Write` 和 `Card.Streaming.Write` 两个权限点必须都在钉钉应用里申请到位。少一个，卡片投放就会被钉钉拒掉，而我们会自动回落成普通消息——用户看到的现象就是「没有流式效果」，没有任何报错。
其次检查模板：模板必须是**钉钉卡片平台**上创建的 **AI 卡片**场景模板，模板 ID 要和它对应。
流式只是增强手段。卡片链路上任何一环失败，回答都会以普通消息完整送达，不会丢内容。
这是钉钉平台的限制，不是集成的问题：群聊里群成员 @ 机器人时，钉钉**不投递文件消息**——我们收不到任何回调，连一句「不支持」都发不出来。
群里的**截图**是可以的（@机器人 + 文字 + 图片是同一条图文消息），所以能贴图的场景改用截图即可。
机器人在每个群第一次被 @ 时会主动说明这一点。
两句话对应两件不同的事：
* **「当前账户额度已用尽，请联系管理员升级套餐后再试。」** 团队的套餐额度耗尽了，机器人无法再调用智能体。**不充值不会自动恢复**，请联系管理员充值或升级套餐。
* **「当前请求较多，正在排队，请稍后再发一次。」** 是我们这边一时繁忙，不是您发得太快，稍后重发即可。
不能。一个 Client ID 在整个平台只能被一条集成占用——否则钉钉会把消息随机投给其中一条连接，回答会串到别的团队去。
如果提示这个 Client ID 已被占用：
* 占用者在**同一个工作空间**：直接改那一条（提示里有「去编辑那一条」的入口）
* 占用者在**同团队的其他工作空间**：先删掉原来那条，再在这里接入
* 占用者在**其他团队**：出于安全考虑我们不会透露是谁，请在钉钉开放平台新建一个机器人应用
需要一个机器人服务多个工作空间的记忆，正确做法是把这些项目作为**只读项目**加进同一条集成。
访问范围完全由**钉钉侧**决定，我们刻意不做第二套白名单——两处配置漂移比没有配置更危险。
具体来说：
* **群聊**：由**群成员**决定——机器人在群里，群成员就能 @ 它
* **应用可见范围**：控制这个应用对哪些同事可见
* 任何情况下，机器人都只处理**本企业成员**的消息
所以「机器人能被谁用」这个问题，答案主要在您把机器人拉进了哪些群。
分两层看：
* **对话上下文**是按人隔离的。群里每个人各有独立上下文，A 的提问不会出现在 B 的对话里。
* **项目记忆是共享的。** 沉淀进读写项目的记忆，所有能用这个机器人的人都能检索到——这正是这个功能的价值，也是为什么创建时要把读写项目当成一次授权决策来选。
个人相关的记忆会归到各人的记忆身份下，不进共享池。
会一并清除这条集成的会话记录、钉钉用户与记忆身份的映射关系，以及会话里挂着的附件引用，且不可恢复。
**已经沉淀进项目的记忆和已入库的文件不会被删** ——它们属于项目，不属于集成。
只是临时停用的话，用卡片上的开关就够了，不要删。