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

# 使用知識庫

> 把知識庫連結到 Agent 與 App、選擇讀取或讀取與寫入權限、設定 Agent 的開放範圍，並了解 Agent 在執行時如何讀取檔案

已發布的知識庫在有人讀取之前不會發揮作用。你可以把它連結到 **Agent**（每次執行都會讀取），以及 **應用（App）**（其 AI 建置器會把它當作參考資料）。

## 把知識庫連結到 Agent

兩邊都可以建立連結，效果相同。

<Tabs>
  <Tab title="從知識庫">
    開啟知識庫，再開啟 **代理** 分頁。在 **已連結的代理** 中選擇一個 Agent、選擇它的 **存取** 權限，然後點選 **連結代理**。

    之後要變更 Agent 的權限或點選 **取消連結**，也是在這個分頁。
  </Tab>

  <Tab title="從 Agent">
    開啟 Agent，再開啟 **資料存取** 分頁。在 **已連結的知識庫** 中選擇一個知識庫，然後點選 **連結知識庫**。你也可以在 Agent Builder 的設定窗格中，於 **知識庫** 區段完成這個動作。

    從 Agent 這一側連結的知識庫一律以 **讀取** 權限開始。若要授予寫入權限，請到知識庫的 **代理** 分頁變更。
  </Tab>
</Tabs>

變更會從 Agent 的下一回合開始生效。

<Note>
  建立連結需要 **Admin** 或 **Builder** 角色。從 Agent 這一側，只能連結你有權編輯的知識庫。
</Note>

## 選擇存取權限

每個連結都有一個存取模式（`ContextAccessMode`）。讀取與寫入權限另外還有寫入政策。

| 存取（UI） | 存取模式 | Agent 能做什麼 |
| - | - | - |
| **讀取** | `READ` | 讀取已發布的檔案。這是預設值。 |
| **讀取與寫入** | `READ_WRITE`，寫入政策 `AUTO` | 讀取，並自行更新知識庫中的檔案。每次寫入都是一個新版本。 |
| **讀取與寫入（寫入前詢問）** | `READ_WRITE`，寫入政策 `ASK` | 讀取，並提出寫入請求，由使用者在核准卡片上同意後才會寫入。 |

<Warning>
  **讀取與寫入（寫入前詢問）** 只在使用者看得到核准卡片的地方有效：網頁聊天。在其他所有途徑 —— 例如 Slack 等聊天應用、Webhook、自動化 —— 該次執行中 Agent 完全無法寫入這個知識庫。無人值守的 Agent 請使用 **讀取與寫入**。
</Warning>

Agent 可以寫入的知識庫，就是那個 Agent 的記憶。Agent 如何寫入、以及如何檢查它寫了什麼，請見 [記憶](/zh/context/memory)。

## 設定 Agent 的開放範圍

Agent 的 **開放範圍**（`contextExposure`）決定它能看到哪些知識庫。設定位於 Agent 的 **資料存取** 分頁，**已連結的知識庫** 區段中。

| 開放範圍（UI） | 值 | Agent 沙盒中包含的內容 |
| - | - | - |
| **僅限已連結** | `ATTACHED` | 只有連結到這個 Agent 的知識庫，沒有其他內容。工作區原始檔案不會被掛載；若已啟用 `workspace_data` 工具，Agent 可在需要時用它們讀取。 |
| **整個工作區** | `ALL` | 工作區中所有已發布的知識庫，加上工作區原始檔案，不論連結了什麼。連結清單只是標籤，不是邊界。 |

* 所有新的 Agent 都使用 **僅限已連結**。沒有連結任何知識庫的 Agent，每次執行開始時都不會有任何共用知識。
* **整個工作區** 只存在於開放範圍控制推出前就已使用它的 Agent。這類 Agent 一旦切換為 **僅限已連結**，就無法再切回來。
* 設有**資料範圍**的 Agent 一律為 **僅限已連結**。
* 開放範圍永遠不會授予寫入權限，只有 **讀取與寫入** 連結才會。

## Agent 如何看到這些檔案

每次執行開始時，DataGen 會把 Agent 可讀取的知識庫以唯讀方式掛載到它的沙盒中，每個知識庫一個目錄：

```text theme={null}
/mnt/context/contexts/
├── <slug-a>/        # 知識庫 A，最新發布的版本
│   ├── README.md
│   └── ...
└── <slug-b>/        # 知識庫 B
    └── ...
```

Agent 的系統提示會依路徑與名稱列出每個已掛載的知識庫，所以你不需要告訴它去哪裡找。你仍然可以在指示中指定某個檔案：

```markdown theme={null}
## 參考資料

根據 /mnt/context/contexts/<slug>/ 中的知識庫回答政策相關問題。
先讀它的 README.md，並在每個回答中註明你使用的檔案。
```

執行時的行為：

* **永遠是上線中的版本。** 發布、回溯或 Agent 寫入都會在 Agent 的下一回合生效。
* **唯讀。** Agent 寫在 `/mnt/context/` 底下的任何內容都不會保留。具有 **讀取與寫入** 權限的 Agent 只能透過 `write_context` 工具修改知識庫，而它自己掛載的副本要等掛載更新後才會顯示變更。
* **謹慎看待 Agent 寫入的檔案。** Agent 會被告知知識庫中的檔案可能是其他 Agent 寫的，若內容看起來有誤，應查看版本紀錄。

<Tip>
  當 Agent 可以讀取多個知識庫時，它會依每個知識庫的 **說明** 來選擇。請讓說明簡短而具體。
</Tip>

## 把知識庫連結到 App

App 只在**建置期**使用知識庫。開啟 App，再開啟 **工具與知識** 分頁，在 **知識庫** 區段連結知識庫。你也可以在 App Builder 的設定窗格中，於 **知識庫** 區段連結。

* App Builder 的沙盒會以唯讀方式把已連結的知識庫掛載在 `/mnt/context/contexts/` 底下，作為撰寫 App 的背景資料。
* 已發布的 App 永遠看不到它們。如果執行中的 App 需要這些資訊，請讓建置器把內容寫進 App 自己的檔案。
* App 的連結沒有存取模式，也沒有開放範圍設定：建置器讀取的就是已連結的內容。

請見 [建立 App](/zh/apps/build)。

## 下一步

<CardGroup cols={2}>
  <Card title="記憶" icon="brain" href="/zh/context/memory">
    讓 Agent 把學到的東西記錄在知識庫中，並檢查它寫了什麼。
  </Card>

  <Card title="Skills" icon="wand-magic-sparkles" href="/zh/context/skills">
    用經過審核的 Skill 為 Agent 提供可重複使用的做法。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.