william-weng/wwsavefiletool

English | 繁體中文

✨ 功能特色

  • 支援 Apple Foundation Models Tool protocol。
  • 使用 @Generable 定義模型可理解的輸入與輸出結構。
  • 支援純文字與 base64 二進位內容。
  • 檔案固定儲存到 App Documents 目錄。
  • 內建檔名清理與副檔名白名單驗證。
  • 可自訂允許儲存的副檔名清單。

📦 安裝方式

Swift Package Manager

dependencies: [
    .package(url: "https://github.com/William-Weng/WWSaveFileTool.git", .upToNextMajor(from: "0.1.1"))
]

🚀 使用方式

import UIKit
import WWSaveFileTool

final class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        Task { try await saveText("Hello, World!") }
    }
}

extension ViewController {

    func saveText(_ text: String) async throws {

        let tool = WWSaveFileTool()
        let filename = "\(Date.now).txt"
        let arguments = WWSaveFileTool.Arguments(filename: filename, payload: .text(text))
        let output = try await tool.call(arguments: arguments)

        print(output.path)
    }
}

🧩 可用副檔名

建立工具時可以自訂允許的副檔名：

let tool = WWSaveFileTool(
    allowedExtensions: ["txt", "md", "json", "png", "jpg"]
)

如果副檔名不在白名單內，工具會拋出錯誤。

🔄 儲存流程

工具的內部流程如下：

  1. 取得模型提供的 filename 與 payload。
  2. 將 FilePayload 轉換為內部使用的 FileType。
  3. 清理檔名中的非法字元。
  4. 驗證副檔名是否在允許清單內。
  5. 將內容轉成 Data。
  6. 把檔案寫入 URL.documentsDirectory。
  7. 回傳 Output。

✅ 最佳實踐

  • description 與 @Guide 盡量短而明確。
  • 不要讓模型無條件每次都存檔，建議只在使用者明確要求時才呼叫此工具。
  • 若流程上「一定要存」，建議由 App 端在拿到回應後直接呼叫儲存邏輯，而不是完全依賴模型自行決定是否呼叫工具。
  • 若同一個 session 掛了多個 tools，建議把 instructions 寫清楚，避免模型同時觸發過多工具。

📝 範例提示

請把下面內容存成 README.txt：
Hello World

📌 備註

  • binaryBase64 適合圖片、音訊、PDF 或其他二進位內容。
  • sanitize() 可以避免非法字元造成寫檔失敗。
  • 若要讓 Documents 內容出現在 Files App，請在 Info.plist 中加入以下設定：

- UIFileSharingEnabled = YES（啟用檔案共享） - LSSupportsOpeningDocumentsInPlace = YES（允許直接開啟與編輯檔案） - UISupportsDocumentBrowser = YES（讓 App 的 Documents 目錄可在 Files App 的「On My iPhone」中顯示）

Package Metadata

Repository: william-weng/wwsavefiletool

Default branch: main

README: README.md