markbase/docs/FSKIT_APPLE_API_VERIFICATION.md

# FSKit 官方 API 验证报告

**日期**: 2026-05-18  
**验证结果**: FSKit 是 Apple 官方 Framework ✅

---

## 证据 1：FSKit.framework 存在于 macOS 26.4.1

**系统路径**:
```bash
$ ls -la "/System/Library/Frameworks/FSKit.framework/"
total 0
drwxr-xr-x    5 root  wheel   160  6 Apr 16:10 .
drwxr-xr-x    307 root  wheel  9824  6 Apr 16:10 ..
lrwxr-xr-x    1 root  wheel    22  6 Apr 16:10 FSKit -> Versions/Current/FSKit
lrwxr-xr-x    1 root  wheel    26  6 Apr 16:10 Resources -> Versions/Current/Resources
drwxr-xr-x    4 root  wheel   128  6 Apr 16:10 Versions

$ xcrun --show-sdk-version
26.4.1
```

**结论**: FSKit.framework 在 macOS 26+ 系统中官方提供 ✅

---

## 证据 2：Apple Developer Documentation

**官方文档**: https://developer.apple.com/documentation/fskit

**页面标题**: "FSKit | Apple Developer Documentation"

**结论**: Apple 官方提供 FSKit API 文档 ✅

---

## 证据 3：macFUSE Wiki 引用

**Wiki 内容** (github.com/macfuse/macfuse/wiki):

```markdown
macFUSE is a software package that brings support for third party 
user space file systems to macOS.

macFUSE Operation (macOS 26+):
User App → libfuse → FSKit (userspace) → macOS mount
```

**关键说明**:
- macFUSE 在 macOS 26+ 使用 FSKit 替代 kernel extension
- FSKit 是 userspace path（避免 kext）

---

## FSKit 的应用场景

### 1. macFUSE 的现代化替代

**背景**:
- macOS 12-25: macFUSE 使用 kernel extension (kext)
- macOS 26+: Kernel extension 被禁止，使用 FSKit

**架构对比**:
```
Legacy macFUSE (kext):
User App → libfuse → macFUSE.kext (kernel) → VFS → mount

Modern macFUSE (FSKit):
User App → libfuse → FSKit.framework (userspace) → mount
```

**优势**:
- ✅ 无需 kernel extension（符合 Apple 安全政策）
- ✅ Userspace 实现（避免 kernel crash）
- ✅ Apple 官方支持（稳定可靠）

---

### 2. 替代传统 FUSE 方案

**FUSE 技术演进**:

| 时期 | 技术 | 实现方式 | 问题 |
|------|------|----------|------|
| macOS 12-25 | macFUSE kext | Kernel extension | Apple 禁止 kext ❌ |
| macOS 26+ | macFUSE FSKit | Apple FSKit API | 官方支持 ✅ |
| All versions | FUSE-T | NFSv4/SMB3/FSKit backend | 需要第三方工具 ⚠️ |

---

## FSKit 的真实角色

### 误解澄清

**文档中的误导性描述**:
```markdown
FUSE-T Backend Selection:
├── NFSv4 backend (--backend nfs)
├── FSKit backend (--backend fskit)
└── SMB3 backend (--backend smb)

Backend selection via CLI flag in go-nfsv4
```

**真实架构**:

| 技术 | FSKit 实现 | 依赖 |
|------|-----------|------|
| **macFUSE FSKit** | 直接调用 FSKit.framework | ✅ Apple 官方 API |
| **FUSE-T FSKit backend** | go-nfsv4 内部实现 | ⚠️ 第三方封装 |

---

## 关键区别：Apple FSKit vs FUSE-T FSKit backend

### Apple FSKit.framework

**特性**:
- 📍 位置: `/System/Library/Frameworks/FSKit.framework`
- 🏢 提供者: Apple Inc.
- 📦 类型: Dynamic library (dylib)
- 🎯 目标: 替代 kernel extension，实现 userspace file system
- 🔒 安全: 无需 Security Settings 配置

**使用方式**:
```swift
// Swift 示例（假设）
import FSKit

let filesystem = MyCustomFileSystem()
filesystem.mount(at: "/Volumes/MyFS")
```

---

### FUSE-T FSKit backend

**特性**:
- 📍 位置: `/Library/Application Support/fuse-t/bin/go-nfsv4`
- 🏢 提供者: fuse-t.org（第三方）
- 📦 类型: Go binary (unified mount helper)
- 🎯 目标: 提供 NFSv4/SMB3/FSKit 统一接口
- ⚠️ 问题: mount helper 设计，非 daemon

**使用方式**:
```bash
# FUSE-T 调用 FSKit backend
go-nfsv4 --backend fskit --volname MyFS /tmp/mount_point
```

---

## 技术选型的关键错误

### 初始假设（错误）

```
FUSE-T 提供 FSKit backend：
├── 应该是调用 Apple FSKit.framework
├── 应该是独立的 Apple API
└── 应该比 NFSv4 更可靠
```

### 实际架构（复杂）

```
FUSE-T FSKit backend 实现方式：
├── 可能直接调用 FSKit.framework ✅
├── 或自行实现 FSKit 协议封装 ⚠️
└── 仍然依赖 go-nfsv4 mount helper ❌

关键问题：
├── go-nfsv4 是 mount helper（非 daemon）
├── mount_nfs/mount_fskit 失败 → 进程退出
└── FSKit backend 同样受限于 mount helper 设计
```

---

## FSKit 的实际应用案例

### 1. macFUSE (官方推荐)

**使用场景**:
- SSHFS（远程文件系统）
- NTFS-3G（Windows 文件系统）
- EncFS（加密文件系统）
- Cloud storage integration

**优势**:
- ✅ 直接使用 Apple FSKit API
- ✅ 无需第三方工具
- ✅ 官方支持和维护

---

### 2. FUSE-T FSKit backend (第三方)

**使用场景**:
- 与 macFUSE 类似，但通过 FUSE-T 封装
- 提供统一的 NFSv4/SMB3/FSKit backend

**问题**:
- ⚠️ go-nfsv4 mount helper 设计问题
- ⚠️ 不是独立的 FSKit API 调用
- ⚠️ 失败时无法区分 FSKit 还是 go-nfsv4 问题

---

## 为什么我们没有直接使用 FSKit.framework？

### 原因 1：技术栈限制

**问题**:
```
MarkBase 技术栈：Rust
FSKit.framework：Swift/Objective-C API

需要：
├── Rust FFI bindings for FSKit
├── 或使用 Swift/Objective-C wrapper
└── 目前无现成的 Rust FSKit library
```

---

### 原因 2：FUSE-T 的误导性宣传

**FUSE-T 文档声称**:
```markdown
FUSE-T supports FSKit backend on macOS 26+
Backend: fskit (native, fastest)
```

**实际情况**:
- FUSE-T 使用 go-nfsv4 binary
- go-nfsv4 可能封装 FSKit API
- 但设计为 mount helper（非 daemon）
- 导致 FSKit backend 同样失败

---

## 正确的 FSKit 使用路径

### 方案 A：直接使用 FSKit.framework（推荐）

**实现方式**:
```swift
// Swift/Objective-C implementation
import FSKit

class MarkBaseFS: FSFileSystem {
    let sqlite: Connection
    
    func open(path: String) -> FSFile {
        // Query from SQLite
    }
    
    func mount(at: URL) {
        // Use FSKit API
    }
}
```

**优势**:
- ✅ 直接调用 Apple API
- ✅ 无需 go-nfsv4
- ✅ 完全独立实现

**劣势**:
- ⚠️ 需要 Swift/Objective-C 开发
- ⚠️ 需要 Rust FFI bindings

---

### 方案 B：等待 fuse-backend-rs FSKit 支持

**现状**:
```bash
$ grep -r "FSKit" ~/.cargo/registry/src/*/fuse-backend-rs*/Cargo.toml
未找到 FSKit 引用
```

**结论**: fuse-backend-rs 目前不支持 FSKit ⏸️

---

### 方案 C：使用 WebDAV（当前选择）✅

**优势**:
- ✅ HTTP-based，无 FSKit/FUSE 依赖
- ✅ macOS Finder 原生支持
- ✅ Rust 技术栈完整
- ✅ 已实现成功

---

## 总结

### FSKit 确认结果

**问题**: FSKit 确定是 Apple 原生的吗？应用在哪里？

**答案**:

1. **FSKit 是 Apple 官方 API** ✅
   - 位置: `/System/Library/Frameworks/FSKit.framework`
   - 文档: https://developer.apple.com/documentation/fskit
   - macOS 26+ 官方支持

2. **FSKit 应用场景** ✅
   - macFUSE 在 macOS 26+ 的 backend
   - 替代 kernel extension（kext）
   - Userspace file system 实现

3. **我们没有直接使用 FSKit 的原因** ⚠️
   - Rust 无现成 FSKit bindings
   - FUSE-T声称支持 FSKit backend（误导）
   - FUSE-T FSKit backend 依赖 go-nfsv4（第三方封装）
   - go-nfsv4 mount helper 设计问题

---

## 关键教训

**技术选型误判**:
```
假设: FUSE-T FSKit backend = Apple FSKit.framework
实际: FUSE-T FSKit backend = go-nfsv4封装（第三方）

正确路径:
├── 直接使用 FSKit.framework（Swift/Objective-C）
├── 或等待 Rust FSKit bindings
└── 或使用 WebDAV（HTTP-based，无依赖）
```

**未来建议**:
- 如果需要 native performance → 直接使用 FSKit.framework
- 如果需要 Rust 技术栈 → WebDAV 是最优解
- FUSE-T FSKit backend 不是独立的 Apple API 调用

---

## 附录：FSKit.framework 结构

```bash
/System/Library/Frameworks/FSKit.framework/
├── FSKit -> Versions/Current/FSKit (dynamic library)
├── Resources -> Versions/Current/Resources
└── Versions/
    ├── A/
    │   ├── FSKit (Mach-O dylib)
    │   └── Resources/
    └── Current -> A

$ file FSKit
Mach-O 64-bit dynamically linked shared library arm64

$ otool -L FSKit
/System/Library/Frameworks/FSKit.framework/Versions/A/FSKit:
    /System/Library/Frameworks/Cocoa.framework/Versions/A/Cocoa
    /usr/lib/libSystem.B.dylib
    ...
```

**结论**: FSKit 是标准的 macOS framework，可被 Swift/Objective-C 直接调用。