跳至主要內容

ArchilFilesystem

將檔案儲存在 Archil 的彈性 Serverless 磁碟上。它結合 S3 相容物件 API 以快速讀寫、用於 POSIX shell 操作的 exec()，以及用於伺服器端平行搜尋的 grep()。介面詳情請參閱 WorkspaceFilesystem 介面。

安裝
「安裝」的直接連結

npm install @mastra/archil

使用方式
「使用方式」的直接連結

將 ArchilFilesystem 加入 Workspace，並指派給 Agent：

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { ArchilFilesystem } from '@mastra/archil'

const workspace = new Workspace({
  filesystem: new ArchilFilesystem({
    diskId: 'dsk-0123456789abcdef',
    apiKey: process.env.ARCHIL_API_KEY,
    region: 'aws-us-east-1',
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

初始化時建立新磁碟
「初始化時建立新磁碟」的直接連結

如果沒有現有磁碟，請提供 createDiskOptions 以自動建立磁碟：

import { ArchilFilesystem } from '@mastra/archil'

const filesystem = new ArchilFilesystem({
  apiKey: process.env.ARCHIL_API_KEY,
  region: 'aws-us-east-1',
  createDiskOptions: {
    name: 'my-agent-workspace',
  },
})

await filesystem.init()
// filesystem.diskId now contains the newly created disk ID

環境變數備援值
「環境變數備援值」的直接連結

省略 apiKey 與 region 時，此 Provider 會從環境變數讀取：

  • ARCHIL_API_KEY - API 金鑰
  • ARCHIL_REGION - 區域（例如 aws-us-east-1）
  • ARCHIL_S3_BASE_URL - 自訂 S3 端點（選用）
import { ArchilFilesystem } from '@mastra/archil'

// Uses ARCHIL_API_KEY and ARCHIL_REGION from environment
const filesystem = new ArchilFilesystem({
  diskId: 'dsk-0123456789abcdef',
})

建構函式參數
「建構函式參數」的直接連結

diskId?:

string
現有的 Archil 磁碟 ID（例如 "dsk-0123456789abcdef"）。不能與 createDiskOptions 同時使用。

createDiskOptions?:

CreateDiskRequest
初始化時建立新磁碟的選項。不能與 diskId 同時使用。

apiKey?:

string
Archil API 金鑰。若未提供，則使用 ARCHIL_API_KEY 環境變數。

region?:

string
Archil 區域（例如 "aws-us-east-1"）。若未提供，則使用 ARCHIL_REGION 環境變數。

baseUrl?:

string
自訂 Archil 控制平面 URL（用於測試或自行託管部署）。

s3BaseUrl?:

string
自訂 S3 相容 API URL。若未提供，則使用 ARCHIL_S3_BASE_URL 環境變數。

id?:

string
= Auto-generated
此檔案系統執行個體的唯一識別碼。

displayName?:

string
在 UI 中顯示的易讀名稱。

icon?:

FilesystemIcon
UI 使用的圖示識別碼。

description?:

string
在 UI 中顯示的檔案系統簡短說明。

readOnly?:

boolean
= false
設為 true 時，會封鎖所有寫入操作。

屬性
「屬性」的直接連結

id:

string
檔案系統執行個體識別碼。

name:

string
Provider 名稱（'ArchilFilesystem'）。

provider:

string
Provider 識別碼（'archil'）。

diskId:

string | undefined
Archil 磁碟 ID（初始化後可用）。

readOnly:

boolean | undefined
檔案系統是否處於唯讀模式。

方法
「方法」的直接連結

ArchilFilesystem 實作 WorkspaceFilesystem 介面，並提供所有標準檔案系統方法：

  • readFile(path, options?) - 讀取檔案內容
  • writeFile(path, content, options?) - 將內容寫入檔案
  • appendFile(path, content) - 將內容附加至檔案
  • deleteFile(path, options?) - 刪除檔案
  • copyFile(src, dest, options?) - 複製檔案
  • moveFile(src, dest, options?) - 移動檔案或重新命名
  • mkdir(path, options?) - 建立目錄
  • rmdir(path, options?) - 移除目錄
  • readdir(path, options?) - 列出目錄內容
  • exists(path) - 檢查路徑是否存在
  • stat(path) - 取得檔案或目錄的中繼資料

init()
「init」的直接連結

初始化檔案系統。連線至現有磁碟，或建立新磁碟。

await filesystem.init()

getInfo()
「getinfo」的直接連結

傳回此檔案系統執行個體的中繼資料。

const info = filesystem.getInfo()
// { id: '...', name: 'ArchilFilesystem', provider: 'archil', status: 'ready' }

Archil 專屬方法
「Archil 專屬方法」的直接連結

exec(command)
「execcommand」的直接連結

在磁碟上執行 shell 指令。傳回結束程式碼、stdout 與 stderr。

const result = await filesystem.exec('ls -la /data')
// { exitCode: 0, stdout: '...', stderr: '' }

grep(options)
「grepoptions」的直接連結

對磁碟上的檔案執行伺服器端平行搜尋。

const results = await filesystem.grep({
  directory: '/logs',
  pattern: 'ERROR',
  recursive: true,
  glob: '*.log',
})
// { matches: [...], stoppedReason: null }

share(path, options?)
「sharepath-options」的直接連結

產生用於分享檔案的已簽署 URL。

const { url } = await filesystem.share('/reports/output.pdf', {
  expiresIn: 3600,
})
On this page