跳至主要内容

文件與版本

文件是單個 API 的託管表示。它屬於你組織內的某個專案，隨時間累積版本，而不是被覆蓋。

層級​

Organization -> Project -> Document -> Versions

文件可以直接建立在組織下或專案內，並按專案和組織分別列出。

狀態生命週期​

文件經歷四種狀態：

狀態含義公開服務
ACTIVE線上提供文件和 MCP（受各自啟用標記約束）
PAUSED暫時停止公開服務不可用
ARCHIVED保留但不作為當前不提供
DELETED軟刪除不提供

允許的轉換為：

pause:    ACTIVE  -> PAUSED
resume:   PAUSED  -> ACTIVE
archive:  ACTIVE / PAUSED -> ARCHIVED
restore:  ARCHIVED -> ACTIVE
delete:   ACTIVE / PAUSED / ARCHIVED -> DELETED

暫停是讓文件下線再恢復的最快方式；歸檔保留歷史但不把它當作當前。刪除是軟刪除，因此核心資料不會被立即銷毀。

版本不可變​

規範變化時建立新版本。原始內容從不會被取代：

v1 -> v2 -> v3 -> v4

每個版本記錄：

  • 檔案在物件儲存中的儲存鍵；
  • SHA-256 校驗和；
  • 內容類型、大小和建立時間。

這支援歷史、回滾、對比，以及針對特定版本重新產生文件和 MCP。

當前連結與版本固定連結​

  • 指向當前文件的連結跟隨最新版本；
  • 版本固定連結引用特定版本，從不會在讀者腳下變化。

當你想要不可變引用時——例如在發布說明或合約中——使用固定連結；始終想要最新時使用當前連結。

來源​

文件內容來自某個來源，經過抽象，使上傳和 Git 不被硬編碼進文件模型：

  • Upload（上傳）——直接新增檔案；
  • Git——用 URL、分支和檔案路徑連接儲存庫。

Git 來源追蹤是否啟用同步以及上次同步時間。你可以：

  • 連接儲存庫（儲存庫 URL 和檔案路徑為必填；分支可選）；
  • 按需同步，把最新內容拉取為新版本。

來源元資料與文件一起保留，因此你始終能判斷文件來自上傳還是儲存庫，並檢視上次同步情況。

儲存​

實際檔案以組織/文件/版本的布局存放在物件儲存中；資料庫只存元資料（儲存鍵、校驗和、內容類型、大小）。檔案預設不可從儲存公開讀取——公開存取透過文件的發布路由進行。

為什麼這很重要​

不可變版本與軟刪除生命週期的結合，意味著你可以快速迭代而不丟失歷史，也不會意外暴露你本想停止的文件。臨時下線用暫停，長期保留用歸檔，穩定性重要時固定連結。

相關：暴露操作、存取控制、自訂網域。