> ## 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 生成的總結、方案或報告寫入釘釘文件。
* 根據業務狀態更新已有文件內容。
* 在團隊協作流程中，把重要資料沉澱到釘釘知識庫。

***

## 接入前需要準備

| 準備項    | 說明                                                                                                                   |
| ------ | -------------------------------------------------------------------------------------------------------------------- |
| 釘釘基礎插件 | 釘釘文件寫入依賴 [釘釘插件](/zh-Hant/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>

***

## 常見限制

* 沒有知識庫讀寫權限時，可能無法列出目標知識庫或建立文件。
* 文件內容更新通常依賴用戶授權，不只是企業應用憑證。
* 如果目標知識庫或文件權限變更，需要重新檢查釘釘開放平台權限和可見範圍。
* 建立接口只負責建立空白文件，正文內容需要再走文件內容寫入或覆寫流程。