> ## 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 如何讀寫檔案

**檔案** 中的檔案有四種用法：

| 用法 | 效果 | 是否同步？ |
| - | - | - |
| 資料的檔案原始資料 | 用 SQL 查詢 CSV、TSV 或 Parquet 檔案，並可建置成分析資料 | 永遠是最新的；分析資料快照在更新時同步 |
| 知識庫來源 | 把檔案整理成有版本的知識庫 | 快照；再次發布知識庫時才更新 |
| 由 Agent 讀取 | Agent 視需要列出並讀取檔案 | 永遠是最新的 |
| 由 App 讀取 | App 讀取被選為其來源的檔案 | 永遠是最新的 |

Agent 與 App 也會 **寫入** 檔案：它們的結果會出現在 **輸出** 分頁。

## 作為資料原始資料

**工作區** 分頁或 Agent 輸出中的 CSV、TSV 或 Parquet 檔案，可以登錄為[資料](/zh/data/overview)
的原始資料，並像資料庫資料表一樣用 SQL 查詢。不會另存副本，因此每次查詢都讀取檔案當下的內容；
上傳同名檔案取代它，原始資料也會跟著更新。

由管理員在 **資料 -> 連線 -> 連接原始資料** 新增，原始資料類型選擇 **工作區檔案**。勾選
**同時建立分析資料** 即可發布 Agent 與 App 能讀取的快照。預設可讀取最大 512 MiB 的檔案。
詳細步驟請見[建立分析資料](/zh/data/build-models)中的「檔案原始資料」。

個人檔案不能成為資料原始資料，因為原始資料對所有成員可見。

## 作為知識庫來源

建立知識庫時，你會選擇它的來源檔案與資料夾：工作區檔案、Agent 輸出、某個 Agent 自己的檔案等。
AI 知識庫建構器會整理這些內容，每次發布都會存成一份有版本的快照，供 Agent 與 App 讀取。
在你再次發布（手動或透過自動化）之前，知識庫不會跟著檔案的後續變更而改變。請參閱
[建立知識庫](/zh/context/build)。

當 Agent 應該依據一組經過整理、有版本的文件工作時，請使用知識庫，而不是原始檔案。

## Agent 如何讀取檔案

### 在對話中

在對話框中輸入 `@` 即可提及檔案中的檔案或資料夾，或用 **附加檔案** 在單則訊息中附上檔案。

### 用工作區資料工具隨時讀取

儲存式 Agent 有三個唯讀工具：

| 工具 | 功能 |
| - | - |
| `list_workspace_data` | 依前綴與名稱樣式列出檔案，包括 `outputs/` 底下先前執行的輸出 |
| `read_workspace_data` | 回傳小型文字檔的內容 |
| `fetch_workspace_data` | 把較大或二進位的檔案複製到沙盒中 |

**工作區** 分頁中的檔案在這些工具裡位於 `.raw/` 底下，例如 `.raw/finance/2025/q3-forecast.xlsx`。
這些工具永遠讀取檔案當下的內容，且永遠無法寫入或刪除。

在 Agent 的 **資料存取** 分頁用 **工作區資料工具** 開啟或關閉（預設開啟；下一回合起生效）。
關閉後，Agent 只看得到執行開始時放進沙盒的檔案。

### 限制 Agent 可以讀取的範圍

預設情況下，Agent 可以讀取 **工作區** 分頁中的所有檔案。儲存式 Agent 的 **資料存取** 分頁中的
**資料範圍** 可以把它變成一條硬性界線：

<Steps>
  <Step title="選擇「僅限選定資料夾」">
    在 **資料範圍** 中，從 **不限制** 切換為 **僅限選定資料夾**。
  </Step>

  <Step title="新增資料夾或檔案">
    點選 **新增資料夾或檔案**，從 **工作區** 分頁選擇項目。只能加入 `.raw/` 底下的項目。
  </Step>
</Steps>

設定資料範圍後，不論提示、呼叫者或被注入的指令怎麼要求，範圍外的內容一律拒絕。沒有選任何項目
代表 Agent 完全讀不到工作區檔案。資料範圍不影響知識庫或分析資料，它們是另外授權的。

Agent 可讀取的內容一覽（**資料存取** 分頁也會顯示同樣的摘要）：

| 項目 | 是否可讀 |
| - | - |
| 自己的檔案 | 一律可讀 |
| 已連結的知識庫 | 一律可讀 |
| 工作區檔案 | 依資料範圍：全部、選定的項目或完全不行 |
| 輸出 | 所有 Agent 的輸出；設定資料範圍後只有自己的 |
| 個人檔案 | 對話介面中不可讀；自動化中可讀取呼叫者自己的 |

## Agent 如何寫入檔案

Agent 把結果寫到沙盒中的輸出資料夾來保存。回合結束時，DataGen 會把它們複製到 **檔案 -> 輸出**，
放在以 Agent 命名的資料夾中：

* 對話回合：`outputs/<Agent 名稱>/chat-<對話 ID>/`
* 自動化與 webhook 執行：`outputs/<Agent 名稱>/<執行 ID>/`

輸出在檔案頁面上是唯讀的。你可以把它們當作資料原始資料或知識庫來源，或讓其他 Agent
用工作區資料工具讀取。

Agent 不會寫入 **工作區** 或 **個人** 分頁。若要讓 Agent 持續更新知識，請以讀寫權限連結一個知識庫。
請參閱[記憶](/zh/context/memory)。

## App 如何讀寫檔案

* **讀取**：App 讀取在其 **來源** 中選定的工作區檔案。App 啟動時這些檔案會被複製到它的沙盒，
  App 也可以透過 Files API 讀取。請參閱[建立 App](/zh/apps/build)。
* **寫入**：在啟用 App 檔案寫入的部署中，已發布的 App 可以在 **輸出** 中屬於自己的資料夾
  （標示 **App**）寫入與刪除檔案。

## 下一步

<CardGroup cols={2}>
  <Card title="知識庫" icon="book" href="/zh/context/overview">
    把檔案變成 Agent 與 App 使用的有版本知識庫。
  </Card>

  <Card title="資料" icon="database" href="/zh/data/overview">
    用 SQL 查詢 CSV 與 Parquet 檔案，並發布分析資料。
  </Card>
</CardGroup>


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