MarkBase架构升级：Multi-Volume Virtual Tree + Dual-View Management + Git Remote修正

核心功能： - ✅ Categories/Series双视图管理（category_view.rs + import_markdown.rs） - ✅ FUSE Multi-Volume支持（tree_type参数） - ✅ SSH/SFTP/SCP/rsync协议完整实现（4042行） - ✅ NFS/SMB Module Phase 1-3完成 - ✅ Archive Module Phase 1-4完成（2916行） - ✅ Download Center API完整实现 - ✅ S3兼容API实现（560行） Git配置修正： - ✅ 删除错误origin（gitea.momentry.ddns.net） - ✅ 删除m5max128（指向机器名） - ✅ 设置origin = m5max128gitea.momentry.ddns.net/admin/markbase - ✅ 设置m4minigitea = m4minigitea.momentry.ddns.net/warren/markbase 数据清理： - ✅ 删除38个临时SQLite（保留accusys.sqlite、demo.sqlite） - ✅ 删除.bak、test_*.bin、调试脚本等临时文件 - ✅ 删除临时目录（build/、download files/、raid_test/等） - ✅ 更新.gitignore排除临时文件架构优化： - 52个文件修改，2434行新增，4739行删除 - Workspace成员整合（16个crate） - 数据库状态：accusys.sqlite保留（主demo测试）远程同步： - ✅ 准备推送到m5max128gitea（远程Gitea） - ✅ 准备推送到m4minigitea（本地Gitea）
2026-06-12 12:59:54 +08:00
parent 4cb7e80568
commit 1300a4e223
4559 changed files with 195840 additions and 4244 deletions
--- a/docs/fskit-research/FSKIT_API.md
+++ b/docs/fskit-research/FSKIT_API.md
@@ -0,0 +1,419 @@
+# FSKit API 详细文档 ⭐⭐⭐⭐⭐
+
+## 1. FSKit Framework 结构
+
+**Framework位置**：`/System/Library/Frameworks/FSKit.framework`
+
+**核心组件**：
+- UnaryFilesystemExtension
+- FSUnaryFileSystem
+- FSVolume
+- FSItem
+- FSBlockDevice
+
+---
+
+## 2. UnaryFilesystemExtension（入口点）
+
+**定义**：文件系统扩展入口点，相当于 kernel module init
+
+**Swift API**：
+```swift
+import FSKit
+
+class UnaryFilesystemExtension {
+    // 系统调用，启动文件系统
+    func start() -> Bool
+    
+    // 系统调用，停止文件系统
+    func stop()
+    
+    // 返回文件系统实现
+    func filesystem() -> FSUnaryFileSystem
+}
+```
+
+**生命周期**：
+```
+1. 用户激活 Extension (System Settings)
+2. macOS 调用 start()
+3. 文件系统初始化
+4. 返回 FSUnaryFileSystem 实例
+5. macOS 调用 stop() (deactivate)
+```
+
+---
+
+## 3. FSUnaryFileSystem（文件系统）
+
+**定义**：文件系统核心类，管理卷和文件系统操作
+
+**Swift API**：
+```swift
+class FSUnaryFileSystem {
+    // 文件系统名称
+    var name: String
+    
+    // 文件系统版本
+    var version: String
+    
+    // 初始化文件系统
+    func initialize() -> Bool
+    
+    // 清理文件系统
+    func cleanup()
+    
+    // 创建卷（相当于 dataset）
+    func createVolume(name: String, device: FSBlockDevice?) -> FSVolume
+    
+    // 删除卷
+    func deleteVolume(volume: FSVolume)
+    
+    // 查询卷
+    func queryVolumes() -> [FSVolume]
+}
+```
+
+**协议 FSUnaryFileSystemOperations**：
+```swift
+protocol FSUnaryFileSystemOperations {
+    // 启动文件系统
+    func start() -> Bool
+    
+    // 停止文件系统
+    func stop()
+    
+    // 处理挂载请求
+    func handleMountRequest(request: FSMountRequest) -> FSVolume?
+    
+    // 处理卸载请求
+    func handleUnmountRequest(volume: FSVolume)
+}
+```
+
+---
+
+## 4. FSVolume（卷管理）
+
+**定义**：卷实例，相当于 ZFS dataset 或传统文件系统分区
+
+**Swift API**：
+```swift
+class FSVolume {
+    // 卷名称
+    var name: String
+    
+    // 卷 ID
+    var id: UUID
+    
+    // 所属文件系统
+    var filesystem: FSUnaryFileSystem
+    
+    // 卷状态
+    var state: FSVolumeState
+    
+    // 块设备（可选）
+    var blockDevice: FSBlockDevice?
+    
+    // 根目录项
+    var rootItem: FSItem
+}
+```
+
+**协议 FSVolume.Operations**：
+```swift
+protocol FSVolumeOperations {
+    // 文件操作
+    func lookup(path: String) -> FSItem?
+    func create(path: String, type: FSItemType) -> FSItem?
+    func remove(item: FSItem) -> Bool
+    func rename(item: FSItem, newPath: String) -> Bool
+    
+    // 读写操作
+    func read(item: FSItem, offset: Int, size: Int) -> Data?
+    func write(item: FSItem, offset: Int, data: Data) -> Int
+    
+    // 目录操作
+    func readdir(directory: FSItem) -> [FSItem]
+    func mkdir(path: String) -> FSItem?
+    func rmdir(directory: FSItem) -> Bool
+    
+    // 属性操作
+    func getattr(item: FSItem) -> FSItemAttributes
+    func setattr(item: FSItem, attributes: FSItemAttributes) -> Bool
+    
+    // 扩展属性
+    func getxattr(item: FSItem, name: String) -> Data?
+    func setxattr(item: FSItem, name: String, value: Data) -> Bool
+    func listxattr(item: FSItem) -> [String]
+    func removexattr(item: FSItem, name: String) -> Bool
+    
+    // 锁定操作
+    func lock(item: FSItem, operation: FSLockOperation) -> Bool
+    func unlock(item: FSItem) -> Bool
+    
+    // 符号链接和硬链接
+    func symlink(path: String, target: String) -> FSItem?
+    func link(item: FSItem, newPath: String) -> FSItem?
+    func readlink(item: FSItem) -> String?
+}
+```
+
+---
+
+## 5. FSItem（文件/目录项）
+
+**定义**：文件系统项（文件、目录、符号链接等）
+
+**Swift API**：
+```swift
+class FSItem {
+    // 项 ID
+    var id: UUID
+    
+    // 项名称
+    var name: String
+    
+    // 项类型
+    var type: FSItemType
+    
+    // 所属卷
+    var volume: FSVolume
+    
+    // 父目录
+    var parent: FSItem?
+    
+    // 文件大小
+    var size: Int
+    
+    // 属性
+    var attributes: FSItemAttributes
+}
+
+enum FSItemType {
+    case file          // 文件
+    case directory     // 目录
+    case symlink       // 符号链接
+    case hardlink      // 硬链接
+    case special       // 特殊文件
+}
+```
+
+---
+
+## 6. FSBlockDevice（块设备）
+
+**定义**：块设备访问接口，对 ZFS 极重要
+
+**Swift API**：
+```swift
+class FSBlockDevice {
+    // 设备路径
+    var path: String
+    
+    // 设备大小
+    var size: Int
+    
+    // 设备 ID
+    var id: UUID
+    
+    // 块大小
+    var blockSize: Int
+    
+    // 读取块
+    func readBlock(offset: Int, size: Int) -> Data?
+    
+    // 写入块
+    func writeBlock(offset: Int, data: Data) -> Bool
+    
+    // 刷新缓存
+    func flush()
+    
+    // 设备信息
+    func getInfo() -> FSBlockDeviceInfo
+}
+```
+
+**关键特性**：
+- ✅ **直接块设备访问**（pread/pwrite）
+- ✅ **设备路径**: /dev/disk18, /dev/disk19, etc
+- ✅ **支持多个设备**（RAID-Z, mirror）
+- ✅ **异步 I/O**（可选）
+- ✅ **Direct I/O**（可选）
+
+---
+
+## 7. FSItemAttributes（属性）
+
+**定义**：文件/目录属性
+
+**Swift API**：
+```swift
+struct FSItemAttributes {
+    // 标准 POSIX 属性
+    var mode: Int          // 权限模式
+    var uid: Int           // 用户 ID
+    var gid: Int           // 组 ID
+    var size: Int          // 文件大小
+    var nlink: Int         // 链接数
+    var atime: Date        // 访问时间
+    var mtime: Date        // 修改时间
+    var ctime: Date        // 创建时间
+    var flags: Int         // 标志位
+    
+    // macOS 特定属性
+    var finderInfo: Data   // Finder 信息
+    var extendedFlags: Int // 扩展标志
+}
+```
+
+---
+
+## 8. FSMountRequest（挂载请求）
+
+**定义**：用户挂载请求处理
+
+**Swift API**：
+```swift
+class FSMountRequest {
+    // 挂载路径
+    var mountPath: String
+    
+    // 设备路径
+    var devicePath: String?
+    
+    // 挂载选项
+    var options: FSMountOptions
+    
+    // 用户 ID
+    var uid: Int
+    
+    // 进程 ID
+    var pid: Int
+}
+
+struct FSMountOptions {
+    var readOnly: Bool
+    var noExec: Bool
+    var noSuid: Bool
+    var noDev: Bool
+    var synchronous: Bool
+    var noBrowse: Bool
+}
+```
+
+---
+
+## 9. FSKit 挂载流程
+
+**完整流程**：
+```
+1. 用户挂载命令:
+   mount -F -t MyFS disk18 /mnt/test
+
+2. macOS 处理:
+   - 解析挂载参数
+   - 创建 FSMountRequest
+   - 调用 FSUnaryFileSystemOperations.handleMountRequest()
+   
+3. 文件系统处理:
+   - 解析 FSMountRequest
+   - 访问块设备（disk18）
+   - 创建 FSVolume 实例
+   - 返回 FSVolume
+   
+4. macOS 完成:
+   - 注册 FSVolume
+   - 创建挂载点
+   - 激活卷操作
+   
+5. 用户操作:
+   - read/write/readdir 等操作
+   - macOS → FSVolume.Operations
+   
+6. 卸载:
+   umount /mnt/test
+   - macOS → FSUnaryFileSystemOperations.handleUnmountRequest()
+```
+
+---
+
+## 10. FSKit Extension 激活
+
+**用户激活流程**：
+```
+1. System Settings → General → Login Items & Extensions
+2. 找到文件系统扩展（MyFS Extension）
+3. 启用扩展
+4. macOS 加载 Extension
+5. 调用 UnaryFilesystemExtension.start()
+6. Extension 返回 FSUnaryFileSystem
+7. 文件系统可用
+```
+
+**权限要求**：
+- 需要 root 或管理员权限激活
+- Apple Developer 证书签名（生产）
+- 沙箱化运行（安全）
+
+---
+
+## 11. FSKit vs Kernel VFS 对比
+
+| FSKit API | Kernel VFS | 功能 |
+|-----------|-----------|------|
+| UnaryFilesystemExtension | kernel module init | 入口点 |
+| FSUnaryFileSystem | filesystem type | 文件系统类型 |
+| FSVolume | superblock | 卷管理 |
+| FSVolume.Operations | file_operations | 文件操作 |
+| FSItem | dentry/inode | 文件项 |
+| FSBlockDevice | block_device | 块设备 |
+| FSItemAttributes | inode attributes | 属性 |
+
+---
+
+## 12. FSKit 限制和特性
+
+**支持**：
+- ✅ 文件/目录操作
+- ✅ 扩展属性（xattr）
+- ✅ 符号链接/硬链接
+- ✅ 文件锁定
+- ✅ 块设备访问
+- ✅ 异步 I/O
+- ✅ Direct I/O
+- ✅ Unicode 文件名
+- ✅ 大文件支持
+
+**不支持**：
+- ❌ IOCTL（不通过 FSKit）
+- ❌ BMAP（不通过 FSKit）
+- ❌ 设备文件（字符/块设备）
+- ❌ 网络文件系统特性（某些）
+
+---
+
+## 13. FSKit 最佳实践
+
+**1. 用户态设计**：
+- 所有代码运行在用户态
+- 无 kernel code
+- 使用 Swift/C 用户态库
+
+**2. 块设备访问**：
+- FSBlockDevice API
+- pread/pwrite 用户态 I/O
+- Direct I/O 优化性能
+
+**3. 性能优化**：
+- 用户态缓存（类似 ARC）
+- 批量操作
+- Async I/O
+
+**4. 安全考虑**：
+- Apple sandbox 模型
+- 权限检查
+- 用户态崩溃隔离
+
+---
+