WWTextReaderTool

English | 繁體中文

---

🎉 相關說明

WWTextReaderTool 是一個輕量級 Swift 工具，用來讀取 Documents 目錄下的檔案內容，並將文字內容回傳給 Apple Intelligence 分析。

此套件符合 Foundation Models Tool protocol，可直接與 Apple Intelligence 整合，讓 AI 自動讀取檔案並進行摘要、分析等任務。

✨ 核心特色

• 🔧 Apple Intelligence 整合：符合 Tool protocol，可直接給 AI 使用
• 📁 簡化路徑管理：只讀取 Documents 目錄，無需處理複雜路徑
• 🚀 輕量級設計：無外部依賴，即裝即用
• 🛡️ Thread-safe：使用 actor 封裝，避免 concurrent access 問題
• ⚡ Swift 6 相容：支援 Swift 6 嚴格的 concurrency 檢查

📋 功能概覽

WWTextReaderTool 目前包含以下主要組件：

組件	說明
WWTextReaderTool	主 Tool struct，符合 Foundation Models Tool protocol
Arguments	@Generable 參數結構，定義 filename
Service	actor 封裝，專注檔案讀取邏輯
CustomError	錯誤類型：.fileNotFound、.emptyContent、.missingParameter

📦 安裝方式

Swift Package Manager

在 Package.swift 中加入套件依賴：

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

並在 target 中加入：

.target(
    name: "YourTarget",
    dependencies: [
        "WWTextReaderTool"
    ]
)

Xcode 安裝

1. File → Add Package Dependencies
2. 輸入：https://github.com/William-Weng/WWTextReaderTool.git
3. 選擇版本後點擊 Add Package

🧪 設定檔案可見性（選填）

要在 檔案 App（Files） 中看到你的 App 的 Documents 目錄，需在 Info.plist 中加入：

<key>UIFileSharingEnabled</key>
<true/>
<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>

或在 Xcode 的 Info 分頁中新增：

• Application supports iTunes file sharing → YES
• LSSupportsOpeningDocumentsInPlace → YES

🚀 使用方式

1. 給 Apple Intelligence 使用（Tool 模式）

import WWTextReaderTool
import FoundationModels

let tool = WWTextReaderTool()
let session = LanguageModelSession(model: .default)
session.tools = [tool]

let response = try await session.respond(
    to: "請讀取 note.txt 並幫我摘要內容"
)

print(response)

Apple Intelligence 會自動：

1. 理解你需要讀取檔案
2. 呼叫 readTextFile Tool
3. 傳入參數 {"filename": "note.txt"}
4. 收到檔案內容後產生摘要

2. 基本使用（UIKit）

import UIKit
import WWTextReaderTool

final class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        Task { await readFile(with: "ReadMe.txt") }
    }
}

extension ViewController {
    
    func readFile(with filename: String) async {
        
        let tool = WWTextReaderTool()
        let arguments = WWTextReaderTool.Arguments(filename: filename)
        
        do {
            let content = try await tool.call(arguments: arguments)
            print("File content: \(content)")
        } catch {
            print("Error reading file: \(error)")
        }
    }
}

3. 簡易 API（非 Tool 模式）

import WWTextReaderTool

let tool = WWTextReaderTool()

do {
    let content = try await tool.readFile("note.txt")
    print(content)
} catch {
    print("Error: \(error)")
}

🧱 錯誤處理

工具目前定義了以下錯誤：

Error	說明
.fileNotFound(URL)	檔案不存在於 Documents 目錄
.emptyContent(URL)	檔案為空
.missingParameter	缺少 filename 參數

do {
    let content = try await tool.readFile("note.txt")
} catch let error as WWTextReaderTool.CustomError {
    switch error {
    case .fileNotFound(let url):
        print("檔案不存在：\(url.path())")
    case .emptyContent(let url):
        print("檔案為空：\(url.path())")
    case .missingParameter:
        print("缺少參數")
    }
}

🧩 設計說明

WWTextReaderTool 將請求處理拆成數個明確職責：

• WWTextReaderTool：對外暴露工具介面。
• Service：專注文件讀取。
• WWTextReaderTool.CustomError：集中定義錯誤語意。

這樣的拆分方式有幾個好處：

• 讓 API 更清楚。
• 方便測試與維護。
• 未來若要擴充回應解析模式，也比較容易演進。

📊 與 WWHttpFetchTool 的比較

特性	WWTextReaderTool	WWHttpFetchTool
用途	讀取本機檔案	發送 HTTP 請求
資料來源	Documents 目錄	網路 URL
輸出	純文字	純文字
AI 整合	✅ Tool protocol	✅ Tool protocol

📄 支援的檔案類型

• ✅ .txt（純文字）
• ✅ .md（Markdown）
• ✅ .json（JSON）
• ✅ .xml（XML）
• ✅ .csv（CSV）
• ✅ 其他純文字檔案

⚠️ 注意：不支援二進制檔案（如 .pdf、.docx），需要先轉換為純文字。