# SwiftMTP Wiki

欢迎使用 SwiftMTP 项目文档！

## 项目简介

SwiftMTP 是一个现代化的 macOS Android MTP 文件传输工具，采用 SwiftUI 构建，支持多语言本地化。

### 核心特性

- 🚀 **Swift 6+**：采用最新的 Swift 6 特性，包括 Actor 模型和结构化并发
- 🎨 **SwiftUI**：现代化的用户界面，支持 Liquid Glass 效果
- 🌍 **多语言支持**：支持英语、中文、日语、韩语、俄语、法语、德语
- 🔧 **CGO 桥接**：通过 CGO 实现 Swift ↔ Go ↔ C 的跨语言通信
- 📱 **MTP 协议**：基于 go-mtpx 实现 Android MTP 设备通信
- 🔒 **安全可靠**：完善的路径验证和错误处理机制

### 技术栈

- **语言**：Swift 6+, Go 1.23+
- **UI 框架**：SwiftUI (支持 Liquid Glass 效果)
- **架构模式**：MVVM + 单例模式
- **并发模型**：Swift 6 Actor + 传统 GCD（文件传输模块豁免）
- **响应式编程**：Combine, @Published
- **桥接层**：CGO (Swift ↔ C ↔ Go)
- **依赖库**：
  - go-mtpx: MTP 协议实现
  - go-mtpfs: MTP 文件系统支持
  - libusb-1.0: USB 通信（已打包到应用中）

### 目标平台

- **操作系统**：macOS 26.0+
- **设备**：Android MTP 模式
- **限制**：单设备支持

## 文档导航

### 快速开始

- [安装指南](Installation.md)
- [快速入门](Getting-Started.md)

### 架构设计

- [系统架构](Architecture.md)
- [模块设计](Modules.md)
- [数据模型](Data-Models.md)

### 开发指南

- [开发环境搭建](Development-Setup.md)
- [代码规范](Coding-Standards.md)
- [API 文档](API.md)
- [测试指南](Testing.md)
- [构建与部署](Build-and-Deploy.md)

### 技术细节

- [Swift 6 并发模型](Swift6-Concurrency.md)
- [CGO 桥接层](CGO-Bridge.md)
- [本地化实现](Localization.md)
- [安全机制](Security.md)

### 常见问题

- [FAQ](FAQ.md)
- [故障排除](Troubleshooting.md)

## 项目结构

```
SwiftMTP/
├── SwiftMTP/              # 主应用
│   ├── App/              # 应用入口和资源
│   │   ├── SwiftMTPApp.swift    # 应用入口
│   │   ├── Assets.xcassets/     # 图标和资源
│   │   └── Resources/           # 其他资源文件
│   ├── Models/           # 数据模型
│   │   ├── Device.swift         # 设备模型
│   │   ├── FileItem.swift       # 文件/文件夹模型
│   │   ├── TransferTask.swift   # 传输任务模型
│   │   ├── AppError.swift       # 错误类型定义
│   │   ├── AppLanguage.swift    # 语言枚举
│   │   └── UpdateInfo.swift     # 更新信息模型
│   ├── Services/         # 业务逻辑
│   │   ├── MTP/                 # MTP 相关服务
│   │   │   ├── DeviceManager.swift       # 设备管理
│   │   │   ├── FileSystemManager.swift   # 文件系统管理
│   │   │   ├── FileTransferManager.swift # 文件传输管理
│   │   │   └── FileTransferManager+DirectoryUpload.swift # 目录上传扩展
│   │   ├── Protocols/           # 协议定义
│   │   │   ├── DeviceManaging.swift
│   │   │   ├── FileSystemManaging.swift
│   │   │   ├── FileTransferManaging.swift
│   │   │   └── LanguageManaging.swift
│   │   ├── LanguageManager.swift        # 语言管理
│   │   ├── LocalizationManager.swift    # 本地化字符串管理
│   │   └── UpdateChecker.swift          # 更新检查
│   ├── Views/           # SwiftUI 视图
│   │   ├── MainWindowView.swift         # 主窗口
│   │   ├── DeviceListView.swift         # 设备列表
│   │   ├── FileBrowserView.swift        # 文件浏览器
│   │   ├── FileBrowserView+Actions.swift # 文件浏览操作
│   │   ├── FileBrowserView+ToolbarDrop.swift # 文件浏览工具栏与拖拽
│   │   ├── TableDoubleClickModifier.swift # 表格双击桥接
│   │   ├── FileTransferView.swift       # 传输任务面板
│   │   ├── SettingsView.swift           # 设置界面
│   │   ├── Components/          # 可复用组件
│   │   └── Extensions/          # 视图扩展
│   ├── Config/          # 配置管理
│   │   └── AppConfiguration.swift       # 应用配置常量
│   └── Resources/       # 本地化资源
│       ├── Base.lproj/          # 基础语言
│       ├── zh-Hans.lproj/       # 简体中文
│       ├── en.lproj/            # 英语
│       ├── ja.lproj/            # 日语
│       ├── ko.lproj/            # 韩语
│       ├── ru.lproj/            # 俄语
│       ├── fr.lproj/            # 法语
│       └── de.lproj/            # 德语
├── Native/              # Go 桥接层
│   ├── kalam_*.go               # 分模块 CGO 桥接实现
│   ├── *_test.go                # 按模块划分的 Go 单元测试
│   ├── libkalam.h               # C 头文件
│   ├── go.mod / go.sum          # Go 模块依赖
│   └── vendor/                  # Go 依赖
├── Scripts/             # 构建脚本
│   ├── build_kalam.sh           # 构建 Go 桥接层
│   ├── create_dmg_simple.sh     # 打包 DMG
│   └── run_tests.sh             # 运行测试
├── SwiftMTPTests/      # 单元测试
└── docs/               # 文档
    └── SwiftMTP.wiki/  # Wiki 文档
```

## 核心模块

### 设备管理 (DeviceManager)

- 自动扫描 MTP 设备（3-30秒自适应间隔）
- 设备连接/断开检测
- 设备选择和管理
- 指数退避策略（连续失败后增加扫描间隔）
- 设备 ID 缓存优化

### 文件系统管理 (FileSystemManager)

- 文件列表获取（支持缓存）
- 文件缓存管理（60秒过期，最大50MB）
- 文件夹创建和删除
- Actor 模式保证线程安全

### 文件传输管理 (FileTransferManager)

- 文件上传/下载（最大支持10GB）
- 传输任务管理（活动任务和已完成任务）
- 实时进度跟踪和速度计算
- 预计剩余时间显示
- 任务取消和批量清除
- 路径安全验证

### 语言管理 (LanguageManager)

- 支持 8 种语言（系统默认、英、中、日、韩、俄、法、德）
- 运行时语言切换
- 本地化字符串类型安全访问

## 快速链接

- [GitHub 仓库](https://github.com/wang93wei/SwiftMTP)
- [问题反馈](https://github.com/wang93wei/SwiftMTP/issues)
- [变更日志](https://github.com/wang93wei/SwiftMTP/blob/main/CHANGELOG.md)

## 贡献指南

欢迎贡献代码、报告问题或提出建议！请参考 [贡献指南](Contributing.md) 了解详情。

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](https://github.com/wang93wei/SwiftMTP/blob/main/LICENSE) 文件。