> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 钉钉

> 配置钉钉知识连接器，将索引限制在明确批准的 Wiki、文档和钉盘范围内。

钉钉连接器用于把已批准的钉钉 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](https://open-dingtalk.github.io/developerpedia/docs/explore/tutorials/stream/event/go/create-app/)。 |
| 访问令牌与凭据校验              | 钉钉通过应用凭据换取 Access Token。可参考 [钉钉开发者百科：获取应用 Access Token](https://open-dingtalk.github.io/developerpedia/docs/develop/permission/single_to_multi/new_get_app_token/)。                |
| 操作人 `UnionId`          | 从已授权操作人的钉钉身份接口、企业通讯录工具或内部身份映射中获取；填写前确认它不是 `userId`、手机号或邮箱。                                                                                                                         |
| Wiki、文档、钉盘 scope ID    | 从目标资源 URL、资源管理页或对应开放 API 返回值中确认。若不确定字段来源，优先在 [钉钉开放平台文档中心](https://open.dingtalk.com/document/) 搜索 `workspace_id`、`dentry_uuid`、`space_id`、`parent_id`。                             |
| API 权限与资源授权            | 在钉钉开放平台为应用开通只读 API 权限，并在资源侧把目标 Wiki、文档或钉盘文件夹授权给该应用。                                                                                                                                |

## 在艾维斯中配置

在管理后台打开**连接器**，选择 **钉钉**。先创建或选择钉钉凭据，再填写允许索引的 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 提示词隔离搜索结果。

## 验证

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

## 常见问题排查

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

## 安全与维护建议

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

## 官方参考

* [钉钉开发者百科：创建应用并查看 Client ID / Client Secret](https://open-dingtalk.github.io/developerpedia/docs/explore/tutorials/stream/event/go/create-app/)
* [钉钉开发者百科：获取应用 Access Token](https://open-dingtalk.github.io/developerpedia/docs/develop/permission/single_to_multi/new_get_app_token/)

## 相关页面

* [连接器与索引](/aivis/knowledge/connectors)
* [索引设置](/aivis/knowledge/index-settings)
* [用户、群组与角色](/aivis/governance/users-and-groups)