# 檔案附件指南

TokST 允許您將檔案附加到記憶中，在文字之外提供豐富的上下文。檔案儲存在 Cloudflare R2 中，元資料索引在 Supabase 中。

## 概述

當您將檔案附加到記憶時，TokST 會：

1. 將檔案上傳到 Cloudflare R2 物件儲存
2. 在 Supabase 中儲存元資料（檔案名稱、大小、MIME 類型、URL）
3. 將附件與記憶關聯
4. 生成**預先簽署上傳 URL**（有效期為 1 小時）和**預先簽署下載 URL**（有效期為 15 分鐘）

這意味著檔案永遠不會直接儲存在資料庫中——它們保存在 R2 中，使您的資料庫保持精簡和快速。

## CLI 用法

### 建立時附加

在儲存新記憶時使用 `--file` 標誌。該標誌可重複使用以附加多個檔案。

```bash
# 單一檔案
tokst remember "Sprint retrospective notes" --file retro-notes.md

# 多個檔案
tokst remember "Q3 planning documents" --file roadmap.pdf --file budget.xlsx --file timeline.png
```

CLI 接受本地檔案。遠端 URL 可使用遠端 MCP 的 `fileUrl` 輸入，也可以先下載到本地再傳給 `--file`。

### 附加到現有記憶

使用 `attach` 子指令：

```bash
tokst memory attach <memory-id> --file document.pdf
```

### 下載附件

使用 `download` 子指令將記憶的檔案下載到本機。檔案透過 R2 預先簽署 GET URL 串流傳輸，並保留原始檔案名稱儲存。

```bash
# 下載所有附件到 ~/Downloads
tokst memory download <memory-id>

# 指定輸出目錄（不存在則自動建立，~ 會展開為 $HOME）
tokst memory download <memory-id> --out ./files

# 按 ID 下載單一附件
tokst memory download <memory-id> --attachment-id <attachment-id>

# JSON 格式輸出
tokst memory download <memory-id> --json
```

> 下載僅支援雲端模式。本機 SQLite 模式會報錯——請先執行 `tokst login --key <api-key>`。

## MCP 用法

使用 MCP 伺服器時，在工具呼叫中傳遞檔案參數：

```json
{
  "content": "Meeting notes with attached diagram",
  "filePath": "/home/user/diagram.png"
}
```

或者使用遠端 URL：

```json
{
  "content": "Reference architecture",
  "fileUrl": "https://example.com/architecture.png"
}
```

要透過 MCP 將檔案附加到現有記憶，請使用 `tokst_attach_file`：

```json
{
  "memoryId": "mem_abc123",
  "fileUrl": "https://example.com/report.pdf",
  "filename": "report.pdf"
}
```

ChatGPT 上傳檔案會透過工具的 `openai/fileParams` 中繼資料自動綁定。再次下載檔案時呼叫 `tokst_download_file`：

```json
{
  "memoryId": "mem_abc123",
  "attachmentId": "attachment-uuid"
}
```

遠端 MCP 伺服器同時以 JSON 和 MCP `resource_link` 回傳 15 分鐘有效的簽名連結。遠端 MCP 單一檔案上傳上限為 50 MB。

## 上傳確認

附件在確認前保持 `pending`。確認路由會對 R2 執行 `HEAD` 請求，缺少或為空的物件會回傳 `409`，隨後以物件的真實大小和 MIME 啟用附件。超過兩小時的待處理或失敗上傳會自動清理。

## Web 儀表板

Web 儀表板提供了拖放式檔案上傳介面，帶有即時進度指示器。導覽到任何記憶並使用附件面板上傳檔案。

## 儲存配額

各方案的檔案附件儲存限制如下：

| 方案 | 儲存配額 |
|---|---|
| **免費版** | 500 MB |
| **入門版** | 2 GB |
| **專業版** | 10 GB |
| **團隊工作區** | 20 GB 共享 |
| **Legacy Max / Team** | 保留原有權益 |

| 上傳管道 | 單一檔案行為 |
|---|---|
| 網頁控制台 | 用戶端最大 500 MB |
| 遠端 MCP | 最大 50 MB |
| CLI | 受帳戶剩餘儲存配額限制 |

儲存使用情況即時更新，可透過 `tokst status` 檢視。

## R2 路徑結構

檔案使用以下路徑約定儲存在 Cloudflare R2 中：

```
{workspace_id}/{atlas_id}/{memory_id}/{attachment_id}-{filename}
```

例如：

```
ws_abc123/atlas_def456/mem_789abc/att_xyz789-report.pdf
```

這種結構確保：

- **隔離性** — 不同工作區的檔案永遠不會衝突
- **可發現性** — 您可以透過資料庫元資料重建路徑
- **清理方便** — 刪除記憶或知識庫時，會在資料庫清理前刪除對應 R2 物件

## 安全

檔案存取透過**預先簽署 URL** 保護：

| 操作 | URL 有效期 |
|---|---|
| 上傳 | 1 小時 |
| 下載 | 15 分鐘 |

預先簽署 URL 在伺服器端生成，需要有效的驗證。直接 R2 儲存桶存取被阻止。這確保只有經過身分驗證且具有適當權限的使用者才能上傳或下載檔案。

物件刪除僅接受精確符合的內部服務憑證，或擁有對應附件的使用者 Token。超出驗證作用域的檔案鍵會被拒絕。

## 最佳實踐

- **使用有意義的檔案名稱** — 檔案名稱會成為 R2 路徑的一部分，並在儀表板中顯示
- **將檔案控制在 100 MB 以下** 以獲得更快的上傳速度
- **對公開遠端資源使用遠端 MCP 的 `fileUrl`**
- **使用 `tokst status` 監控配額** 以避免達到儲存上限