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

# 钉钉文档写入

> 在 superun 中接入钉钉知识库文档创建、写入、更新和同步能力。

# 钉钉文档写入

钉钉文档写入能力用于把产品内容、AI 生成结果或业务数据同步到钉钉知识库文档中。它适合自动生成会议纪要、项目周报、客户记录、知识库文章和流程归档。

***

## 适合什么场景

* 将产品中的记录自动生成钉钉知识库文档。
* 把 AI 生成的总结、方案或报告写入钉钉文档。
* 根据业务状态更新已有文档内容。
* 在团队协作流程中，把重要资料沉淀到钉钉知识库。

***

## 接入前需要准备

| 准备项    | 说明                                                                                                           |
| ------ | ------------------------------------------------------------------------------------------------------------ |
| 钉钉基础插件 | 钉钉文档写入依赖 [钉钉插件](/superun/integrations/dingtalk)。如果还没有配置，superun 会在接入过程中通过对话引导你填写 Client ID、Client Secret 等凭证 |
| 知识库    | 准备一个目标知识库或确认需要由系统创建知识库                                                                                       |
| 文档权限   | 在 [钉钉开放平台](https://open.dingtalk.com/) 开通知识库和文档读写相关权限                                                        |
| 操作人授权  | 需要明确由哪个钉钉用户授权执行文档创建或内容写入                                                                                     |

<Note>
  创建知识库下的空白文档、更新文档内容、读取知识库列表属于不同场景，所需权限和授权方式可能不同。启用时请把目标流程描述清楚。
</Note>

***

## 钉钉后台需要开通的权限

打开 [钉钉开放平台](https://open.dingtalk.com/) →「企业内部开发」→ 进入你的应用 →「权限管理」，按实际场景开通知识库和文档权限。

钉钉文档写入通常同时用到企业级 access\_token 和用户级 access\_token。简单判断：接口路径里有 `/me/` 的，一般需要用户授权；没有 `/me/` 的，通常使用企业应用凭证。

### 建议开通范围

| 使用方式            | 建议开通范围                                                                                                   | 说明                                 |
| --------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| 在已有知识库下创建并写入文档  | `Wiki.Workspace.Read`、`Document.WorkspaceDocument.Write`、文档应用中的文档写权限                                     | 最常见配置。先读取目标知识库，再创建空白文档，最后由授权用户写入正文 |
| 需要自动创建知识库       | 在上面基础上增加 `Wiki.Workspace.Write`                                                                          | 只有当产品需要自动新建知识库时才建议开通               |
| 需要按目录、节点或链接定位文档 | 按需增加 `Wiki.Node.Read`、`Wiki.Workspace.Search`                                                            | 用于读取知识库目录、节点信息或搜索知识库               |
| 需要写入钉钉表格或 AI 表格 | 按需增加 `Document.Workbook.Read`、`Document.Workbook.Write`、`Notable.Base.Read.All`、`Notable.Base.Write.All` | 只有业务明确涉及表格或 AI 表格时再开通              |

<Note>
  如果只是把内容写入某个已有知识库，通常先开通“已有知识库下创建并写入文档”这一组即可。目标知识库还需要给执行写入的钉钉用户查看或编辑权限。
</Note>

### 最小必需权限

| 权限 code / 后台权限项                    | 权限名称     | 用途                | 常见使用场景                   |
| ---------------------------------- | -------- | ----------------- | ------------------------ |
| `Wiki.Workspace.Read`              | 知识库读权限   | 获取知识库列表、获取知识库信息   | 选择目标知识库，拿到 `workspaceId` |
| `Wiki.Workspace.Write`             | 知识库写权限   | 新建知识库             | 租户下没有可用知识库时创建知识库         |
| `Document.WorkspaceDocument.Write` | 知识库文档写权限 | 创建知识库文档、管理知识库文档成员 | 在指定知识库下创建空白文档            |
| 文档应用中的文档写权限                        | 文档内容写入权限 | 覆写文档内容            | 使用用户授权把 Markdown 内容写入文档  |

<Note>
  钉钉「覆写文档内容」属于个人授权接口，后台可能不是以固定权限 code 的形式展示。配置时请在钉钉开放平台的文档应用权限中搜索“文档写入 / 覆写文档 / 更新文档内容”等权限项，并确保执行写入的钉钉用户完成授权。
</Note>

### 可选权限

| 权限 code / 后台权限项           | 权限名称       | 什么时候需要                 |
| ------------------------- | ---------- | ---------------------- |
| `Wiki.Workspace.Search`   | 知识库搜索权限    | 需要按关键词搜索知识库时           |
| `Wiki.Node.Read`          | 知识库节点读权限   | 需要读取知识库目录、节点或通过链接定位节点时 |
| `Document.Workbook.Read`  | 钉钉表读权限     | 需要读取钉钉表格时              |
| `Document.Workbook.Write` | 钉钉表写权限     | 需要写入钉钉表格时              |
| `Notable.Base.Read.All`   | AI 表格应用读权限 | 需要读取 AI 表格应用数据时        |
| `Notable.Base.Write.All`  | AI 表格应用写权限 | 需要写入 AI 表格应用数据时        |

<Warning>
  创建知识库文档和覆写文档内容不是同一个接口。创建空白文档通常使用企业 token；覆写正文内容的接口路径包含 `/me/`，需要用户 token。不要把两类 token 混用。
</Warning>

***

## 如何在 superun 中启用

<Steps>
  <Step title="点击「钉钉文档写入」">
    在「研发」→「技能库」中打开「钉钉文档写入」，点击使用，并说明你希望产品在哪些流程中创建或更新文档。
  </Step>

  <Step title="按引导完成基础配置">
    如果项目还没有配置钉钉基础插件，对话框会引导你填写 Client ID、Client Secret 等应用凭证；如果已经配置过，会直接复用已有配置。
  </Step>

  <Step title="开通知识库和文档权限">
    按照 superun 给出的权限清单，在 [钉钉开放平台](https://open.dingtalk.com/) 开通知识库读写、知识库文档写入等权限，并发布应用。
  </Step>

  <Step title="确认知识库和授权人">
    提供目标知识库、文档归档位置和执行写入操作的钉钉用户授权方式。
  </Step>

  <Step title="测试创建和更新">
    完成权限配置后，先测试创建一篇文档，再测试后续内容更新。
  </Step>
</Steps>

***

## 常见限制

* 没有知识库读写权限时，可能无法列出目标知识库或创建文档。
* 文档内容更新通常依赖用户授权，不只是企业应用凭证。
* 如果目标知识库或文档权限变更，需要重新检查钉钉开放平台权限和可见范围。
* 创建接口只负责创建空白文档，正文内容需要再走文档内容写入或覆写流程。