钉钉 | Alephant Documentation

钉钉连接器用于把已批准的钉钉 Wiki 节点、单篇钉钉文档和钉盘文件夹纳入艾维斯知识检索。它只读取管理员在连接器中显式填写的范围，不会扫描应用或操作人可见的全部钉钉资源。

适用场景

场景	建议
团队 Wiki 问答	用 `workspace_id/parent_node_id` 指定最小可用 Wiki 子树。
单篇制度或项目文档	用文档的 `dentry_uuid` 建立单文档范围，避免引入整棵 Wiki。
钉盘资料检索	用 `space_id/parent_id` 指定文件夹，并先验证文件类型和大小是否适合索引。
多部门知识	按部门或业务线拆分连接器，并绑定不同艾维斯私有群组。
敏感知识	使用专用钉钉应用和操作人 UnionId，不把高权限应用配置成共享入口。

当前索引内容

钉钉连接器以一个或多个显式 scope 作为范围。所有 scope 总数最多 100 个，不能重复或重叠。

钉钉内容	填写格式	索引行为
Wiki 子树	`workspace_id/parent_node_id`	读取指定 Wiki 节点下的节点层级和原生文档内容。
单篇文档	`dentry_uuid`	解析指定文档的正文，并作为独立页面纳入检索。
钉盘文件夹	`space_id/parent_id`	读取文件夹内可处理的文件，并保留文件夹层级。

钉盘文件会经过文件类型和解析能力检查；不支持的文件会记录单项失败，而不是扩大索引范围。当前连接器不索引钉钉群聊、待办、审批、日程、通讯录，也不会自动发现操作人有权访问的其他空间。

前置条件

已创建企业内部钉钉应用，并准备 AppKey 与 AppSecret。
已确认一个能读取目标 Wiki、文档或钉盘范围的操作人 UnionId。这里应填写 UnionId，不要填写 userId、手机号、邮箱或姓名。
已在钉钉开放平台为应用开通目标资源所需的只读权限，并完成资源授权。
已整理需要索引的 Wiki、文档或钉盘范围 ID，且每个范围都有明确业务 owner。
已规划艾维斯访问范围。只要连接器可见，用户就可能搜索到该连接器索引的全部内容。
网络策略允许艾维斯后端访问 api.dingtalk.com，并允许下载已授权钉盘文件。

钉钉 API 权限、资源授权和应用可用范围是不同检查。凭据可用不代表目标 Wiki、文档或钉盘文件夹已经授权给该应用。

配置数据获取入口

配置数据	获取方式
`AppKey` / `AppSecret`	在钉钉开发者后台进入企业内部应用，在应用基础信息或凭证页查看。可参考钉钉开发者百科：创建应用并查看 Client ID / Client Secret。
访问令牌与凭据校验	钉钉通过应用凭据换取 Access Token。可参考钉钉开发者百科：获取应用 Access Token。
操作人 `UnionId`	从已授权操作人的钉钉身份接口、企业通讯录工具或内部身份映射中获取；填写前确认它不是 `userId`、手机号或邮箱。
Wiki、文档、钉盘 scope ID	从目标资源 URL、资源管理页或对应开放 API 返回值中确认。若不确定字段来源，优先在钉钉开放平台文档中心搜索 `workspace_id`、`dentry_uuid`、`space_id`、`parent_id`。
API 权限与资源授权	在钉钉开放平台为应用开通只读 API 权限，并在资源侧把目标 Wiki、文档或钉盘文件夹授权给该应用。

在钉钉开放平台准备应用

在钉钉开发者平台进入 应用开发 > 钉钉应用，点击右上角 创建应用，创建一个企业内部应用。

钉钉开发者平台的钉钉应用列表，右上角展示创建应用入口

进入应用后，在 凭证与基础信息 页面复制 Client ID（原 AppKey）和 Client Secret（原 AppSecret）。在艾维斯中填写时，对应字段仍显示为 钉钉 AppKey 和 钉钉 AppSecret。

钉钉应用凭证页面，标出 Client ID 和 Client Secret

在 权限管理 页面开通连接器读取目标资源所需的权限。钉盘、文档、Wiki 等资源需要按实际索引范围开通对应只读权限，不要为了省事开通无关权限。

钉钉应用权限管理页面，展示已开通的钉盘权限列表

如果需要定位操作人身份，可在钉钉开放平台的 API Explorer 中调试 requestAuthCode，获取当前登录用户的授权码。

钉钉 JSAPI Explorer requestAuthCode 页面，展示 authCode 调试入口

再参考钉钉开放平台文档中的“获取用户 token”接口，用授权码换取用户访问令牌。

钉钉开放平台文档中心的获取用户 token 页面

随后在用户信息接口返回值中确认 unionId。艾维斯中的 操作人 UnionId 应填写这个值，不要填写 userId、手机号、邮箱或姓名。

钉钉用户信息返回参数中标出的 unionId 字段

回到艾维斯创建钉钉凭据，填写名称、钉钉 AppKey、钉钉 AppSecret 和操作人 UnionId，然后点击创建。

艾维斯创建钉钉凭据弹窗，展示名称、AppKey、AppSecret 和操作人 UnionId 字段

在艾维斯中配置

在管理后台打开连接器，选择钉钉。先创建或选择钉钉凭据，再填写允许索引的 scope。

字段	填写方式	说明
AppKey	粘贴企业内部应用的 AppKey	用于换取钉钉访问令牌。
AppSecret	粘贴同一应用的 AppSecret	保存后通常不会明文展示。
操作人 UnionId	例如 `unionid_xxx`	用于代表该操作人读取已授权资源。
钉钉 Wiki 根范围	`workspace_id/parent_node_id`	每行一个 Wiki 子树。
钉钉文档 ID	`dentry_uuid`	每行一个明确授权的文档。
钉盘文件夹范围	`space_id/parent_id`	每行一个钉盘文件夹。

至少填写一种 scope。创建前先用最小范围测试，确认能搜索到预期文档后再逐步扩大。

同步行为

标准管理后台创建的钉钉连接器使用轮询索引，并支持 checkpoint 续跑。同步会按 scope 顺序处理，每个 scope 内先构建稳定清单，再按清单逐项输出层级节点和文档。

阶段	同步细节
Wiki	读取指定根节点下的 Wiki 节点，保留父子层级，并导出原生文档内容。
单篇文档	解析目标 `dentry_uuid` 的内容，适合只授权单篇材料。
钉盘文件	读取指定文件夹内的文件；可解析文件会成为文档，不支持的文件会记录失败。
增量窗口	文档更新时间不在当前同步窗口内时会跳过；配置变化会使 checkpoint 与配置指纹不匹配，需要重新同步。

权限边界

钉钉应用和操作人 UnionId 决定艾维斯能摄取哪些资源，但连接器不会把钉钉组织架构、部门、群组、文档成员或钉盘 ACL 同步到艾维斯。

艾维斯访问设置	含义
私有群组	只有选定艾维斯群组可搜索该连接器产生的全部文档。推荐用于内部 Wiki 和项目资料。
公开	所有可使用该知识范围的艾维斯用户都可能搜索到索引内容。仅适用于可公开给这些用户的资料。
自动同步权限	钉钉当前不支持此模式。

不同部门、项目或密级应使用不同连接器和不同艾维斯私有群组，不要依赖 Agent 提示词隔离搜索结果。

验证

用一个测试 Wiki 节点、单篇文档或钉盘文件夹创建连接器。
运行索引，确认凭据能换取访问令牌，且 scope 校验通过。
搜索已知标题、正文关键词和文件名，确认层级和来源链接正确。
搜索未配置的 Wiki、文档或钉盘文件夹，确认不会返回结果。
使用群组内账号和群组外账号分别测试，确认艾维斯访问边界符合预期。
修改一篇测试文档后等待下一轮同步，确认增量更新可被检索。

常见问题排查

现象	优先检查项
凭据校验失败	`AppKey` 与 `AppSecret` 是否来自同一个钉钉应用，应用是否已启用，密钥是否被重新生成。
scope 校验失败	ID 格式是否正确，应用和操作人 UnionId 是否有权读取目标 Wiki、文档或钉盘范围。
明明有 API 权限但读不到资源	检查资源是否单独授权给应用，操作人是否能打开目标资源。
只同步了部分内容	scope 是否遗漏、重复或重叠，是否超过 100 个范围上限。
钉盘文件没有进入索引	文件类型是否受支持，文件是否过大，下载链接是否可被艾维斯后端访问。
搜索结果被不该看到的人搜到	这是艾维斯访问范围配置问题。将连接器改为私有群组，或按受众拆分连接器。

安全与维护建议

为生产、测试和演示环境使用不同钉钉应用与密钥。
只保存真实密钥到艾维斯凭据，不写入文档、截图、工单、聊天记录或代码仓库。
定期复核 scope 列表、操作人 UnionId、应用权限、资源授权和艾维斯访问群组。
操作人离职、转岗或密钥疑似泄露时，立即更换操作人或密钥并重新验证。
长期不用时，先停用艾维斯连接器，再收回钉钉应用权限或资源授权。

钉钉