markbase/docs/FSKIT_ERROR_GUIDE.md

# FSKit 编译错误解决指南 ⭐⭐⭐⭐⭐

## HelloFS 错误分析

### 错误 1: Entry Point 类名错误

**错误信息**：
```
error: cannot find type 'UnaryFilesystemExtension' in scope
```

**原因**：使用了错误的类名（理论分析）

**解决方案**：
```swift
// 错误 ❌
class HelloFSExtension: UnaryFilesystemExtension {
    // ...
}

// 正确 ✅
struct HelloFSExtension: FSKitExtension {
    func filesystem() -> FSFileSystem {
        return HelloFS()
    }
}
```

---

### 错误 2: 文件系统基类错误

**错误信息**：
```
error: cannot find type 'FSUnaryFileSystem' in scope
```

**原因**：使用了错误的基类名

**解决方案**：
```swift
// 错误 ❌
class HelloFS: FSUnaryFileSystem, FSUnaryFileSystemOperations {
    // ...
}

// 正确 ✅
class HelloFS: FSFileSystem {
    func probeResource(...) { }
    func loadResource(...) { }
}
```

---

### 错误 3: 方法签名错误

**错误信息**：
```
error: method does not override any method from its superclass
```

**原因**：没有使用 `replyHandler` 和 `options` 参数

**解决方案**：
```swift
// 错误 ❌
func start() -> Bool
func handleMountRequest(request: FSMountRequest) -> FSVolume?

// 正确 ✅
func probeResource(
    resource: FSResource,
    replyHandler: @escaping (FSProbeResult?) -> Void
)

func loadResource(
    resource: FSResource,
    options: FSTaskOptions,
    replyHandler: @escaping (Error?) -> Void
)
```

---

### 错误 4: Volume Protocols 缺失

**错误信息**：
```
error: type 'HelloVolume' does not conform to protocol 'FSVolumeOperations'
```

**原因**：FSVolume 需要实现 13+ protocols

**解决方案**：
```swift
class HelloVolume: FSVolume {
    // ...
}

// 必须实现所有 protocols ✅
extension HelloVolume: FSVolume.PathConfOperations { }
extension HelloVolume: FSVolume.OpenCloseOperations { }
extension HelloVolume: FSVolume.IOOperations { }
extension HelloVolume: FSVolume.DirectoryOperations { }
extension HelloVolume: FSVolume.AttributeOperations { }
extension HelloVolume: FSVolume.XattrOperations { }
extension HelloVolume: FSVolume.ActiveOperations { }
extension HelloVolume: FSVolume.CloneOperations { }
// ... 共 13+ protocols
```

---

### 错误 5: Info.plist 配置缺失

**后果**：Extension 无法加载，不会出现在 System Settings

**解决方案**：创建 Info.plist 并添加 FSExtension 配置

```xml
<key>FSExtension</key>
<dict>
    <key>FSExtensionPersonality</key>
    <string>HelloFS</string>
    <!-- 必需配置 -->
</dict>
```

---

### 错误 6: Entitlements 缺失

**后果**：Extension 无法运行，权限错误

**解决方案**：添加 entitlements

```xml
<key>com.apple.security.app-sandbox</key>
<true/>
<key>com.apple.security.files.user-selected.read-write</key>
<true/>
```

---

## 修正步骤清单

**Step 1**: 修正 Entry Point ✅
- 改 `UnaryFilesystemExtension` → `FSKitExtension`

**Step 2**: 修正 Filesystem Base ✅
- 改 `FSUnaryFileSystem` → `FSFileSystem`

**Step 3**: 修正 Method Signatures ✅
- 添加 `replyHandler` 参数
- 添加 `options: FSTaskOptions` 参数

**Step 4**: 实现 Volume Protocols ✅
- 实现 FSVolume.PathConfOperations
- 实现 FSVolume.OpenCloseOperations
- 实现 FSVolume.IOOperations
- 实现 FSVolume.DirectoryOperations
- 实现 FSVolume.AttributeOperations
- 实现 FSVolume.XattrOperations
- 等等 13+ protocols

**Step 5**: 创建 Info.plist ✅
- FSExtension 配置
- NSExtension 配置

**Step 6**: 创建 Entitlements ✅
- App Sandbox
- File access

**Step 7**: 测试编译 ✅
- `swift build`
- 验证无错误

**Step 8**: 测试挂载 ✅
- 创建 block device
- mount -t HelloFS
- 验证功能

---