钉钉 | Alephant Documentation

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

适用场景

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

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

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

钉钉 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、文档或钉盘文件夹授权给该应用。

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

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

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

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

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

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

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

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