# AI_Developer_Workstation

**Repository Path**: imccc_net/AI_Developer_Workstation

## Basic Information

- **Project Name**: AI_Developer_Workstation
- **Description**: AI_Developer_Workstation
一个用于在 Apple Silicon Mac 上一键配置 AI 开发环境的图形化工具。支持 MLX 环境搭建、模型下载管理、以及 Homebrew/Container 等常用开发工具的自动化安装。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-27
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Developer Workstation

一个用于在 Apple Silicon Mac 上一键配置 AI 开发环境的图形化工具。支持 MLX 环境搭建、模型下载管理、以及 Homebrew/Container 等常用开发工具的自动化安装。

![Platform](https://img.shields.io/badge/platform-macOS-blue)
![Swift](https://img.shields.io/badge/Swift-6.0-orange)
![SwiftUI](https://img.shields.io/badge/SwiftUI-6.0-blueviolet)

---

## 📖 项目简介

AI Developer Workstation 是一个专为 Apple M 系列芯片（M1/M2/M3/M4）设计的原生 macOS 应用，旨在帮助开发者快速搭建基于 MLX 和 Hugging Face 模型的 AI 开发环境。

**核心价值**：
- 可视化配置，无需手动敲命令
- 支持多模型管理（CRUD）
- 断点续装，安装失败可重试
- 实时日志与进度显示
- 数据持久化（SwiftData）

---

## ✨ 功能特性

### 🔧 环境管理
- **系统检查**：自动检测 macOS 版本、芯片型号、内存大小
- **目录定制**：可选择任意目录作为开发根目录（默认 `/Volumes/Developer HD`）
- **Homebrew 安装**：一键安装或检测 Homebrew
- **MLX 环境**：自动创建 Python 虚拟环境，安装 `mlx` 和 `mlx-lm`
- **Container 工具**：安装 `container` CLI（通过 Homebrew）
- **VS Code 配置**：自动安装推荐扩展（Python、Jupyter、GitLens）并生成工作区设置

### 🤖 模型管理
- **内置推荐模型**：快速添加 Qwen、DeepSeek、Llama、Mistral 等常用模型
- **手动添加**：自定义模型名称、Hugging Face ID、大小和描述
- **从 Hugging Face 搜索**：直接搜索官方模型库，一键添加
- **选择启用**：勾选需要安装的模型，未选中的不会下载
- **数据持久化**：所有模型数据存储在 SwiftData 中，重启应用不丢失

### 📦 安装流程
- **一键全部安装**：按顺序执行所有未完成的步骤（支持断点续装）
- **单步执行**：可单独运行任意步骤（如仅下载某个模型）
- **实时进度**：下载模型时显示进度百分比和速度
- **详细日志**：每一步的命令输出都会实时显示在日志窗口

### ⚙️ 偏好设置
- **镜像源**：可自定义 PyPI、Hugging Face、Homebrew 镜像地址
- **目标目录**：随时更改开发根目录，系统信息自动重新探测

---

## 🖥️ 系统要求

- **macOS 14.0 (Sonoma) 或更高版本**
- **Apple Silicon 芯片 (M1/M2/M3/M4)**
- **Xcode 15.0+**（用于编译源码）
- **至少 20 GB 可用磁盘空间**（取决于模型大小）
- **网络连接**（用于下载模型和依赖）

---

## 🚀 安装与使用

### 方式一：从源码运行（开发）

```bash
# 1. 克隆仓库
https://gitee.com/imccc_net/AI_Developer_Workstation.git
cd AI-Developer-Workstation

# 2. 用 Xcode 打开项目
open AI_Developer_Workstation.xcodeproj

# 3. 在 Xcode 中选择合适的 Scheme（通常为 AI_Developer_Workstation）
# 4. 点击运行按钮（▶）或按 Cmd+R
```

### 方式二：直接运行 .app（分发版）

1. 从 [Releases](https://gitee.com/imccc_net/AI_Developer_Workstation/releases) 下载最新 `.app` 文件
2. 将 `.app` 拖入 `Applications` 文件夹
3. 双击运行（首次打开需按住 `Control` 并点击，选择“打开”以绕过 Gatekeeper）

---

## 📂 首次启动向导

1. **选择目标目录**：点击“更改...”选择你希望存放开发文件的目录（建议选择一个外部卷或大容量分区）
2. **检查系统信息**：应用会自动探测 Python、Homebrew、Container 版本和磁盘空间
3. **管理模型**：点击工具栏“模型管理”按钮，添加你想要下载的模型（至少勾选一个）
4. **开始安装**：点击“全部安装”按钮，应用将按顺序执行所有步骤

---

## 🧩 详细配置说明

### 目标目录结构
应用会在你选择的根目录下创建以下子目录：
```
根目录/
├── Developer/
│   ├── AI/
│   │   ├── mlx-env/              # Python 虚拟环境
│   │   ├── models/
│   │   │   └── LLM/              # 下载的模型存放处
│   │   ├── cache/                # Hugging Face 缓存
│   │   ├── server/               # （预留）
│   │   └── logs/                 # 应用日志
│   ├── Containers/
│   │   ├── images/
│   │   ├── services/
│   │   └── volumes/
│   ├── Python/
│   │   └── envs/                 # 其他 Python 环境（预留）
│   ├── Projects/
│   │   ├── macOS/
│   │   ├── Python/
│   │   ├── Web/
│   │   └── AI/
│   └── Scripts/                  # 用户脚本存放处
```

### 镜像源设置
- **PyPI 镜像**：默认 `https://pypi.tuna.tsinghua.edu.cn/simple`
- **Hugging Face 镜像**：默认 `https://hf-mirror.com`
- **Homebrew 镜像**：默认使用清华源（可通过开关关闭）

可在“偏好设置”中修改。

### 模型数据管理
- 所有模型信息存储在 `~/Library/Application Support/AI_Developer_Workstation` 中的 SwiftData 数据库
- 模型列表在应用启动时加载，修改后自动同步到主界面“待安装模型”区域

---

## 🛠️ 维护指南

### 添加新的推荐模型
在 `AddModelView.swift` 中找到 `recommendedModels` 数组，按以下格式追加：
```swift
("模型名", "hf_id", 大小(GB), "描述")
```

### 修改安装步骤
编辑 `StepEngine.swift` 中的 `executeStep` 方法，在 `switch step.name` 中添加新的 case。

### 更新镜像源
默认镜像源在 `AppState.swift` 的 `@AppStorage` 属性中定义，用户可在偏好设置中覆盖。

### 清空所有数据
- 删除应用状态：`rm ~/Library/Application Support/AI_Developer_Workstation/*`
- 删除模型缓存：`rm -rf <目标目录>/Developer/AI/cache`
- 删除虚拟环境：`rm -rf <目标目录>/Developer/AI/mlx-env`

### 手动重置安装状态
在应用中点击“重置状态”按钮，或删除以下文件：
```bash
rm ~/Library/Preferences/com.yourcompany.AI-Developer-Workstation.plist
```

---

## ❓ 故障排除

| 问题 | 解决方案 |
|------|----------|
| **Python 虚拟环境创建失败** | 确保系统 Python 3 可用（`python3 --version`），如缺失请安装 Xcode Command Line Tools |
| **Homebrew 安装失败** | 检查网络，或手动安装 Homebrew 后再运行应用 |
| **模型下载 401 Unauthorized** | 模型可能需要认证，请检查模型 ID 是否正确，或在 Hugging Face 上申请访问权限 |
| **磁盘空间不足** | 选择更大的目标目录，或删除不需要的模型 |
| **权限错误 (Permission denied)** | 确保目标目录有读写权限，可 `sudo chown -R $(whoami) <目标目录>` |
| **应用闪退** | 查看 `~/Library/Logs/AI_Developer_Workstation` 下的日志文件，或提交 Issue |

---

## 🧪 开发与调试

### 项目结构
```
AI_Developer_Workstation/
├── Models/                  # 数据模型 (Step, ModelInfo, SystemInfo, ModelEntity)
├── ViewModels/              # AppState, StepEngine
├── Views/                   # 所有 SwiftUI 视图
│   ├── Settings/            # 偏好设置和模型管理
│   └── LogView.swift        # 日志显示
├── Services/                # TaskExecutor, DownloadManager, FileManagerHelper
└── Assets.xcassets/         # 应用图标和资源
```

### 日志调试
- 应用日志同时输出到控制台和 `~/Library/Logs/AI_Developer_Workstation/` 目录
- 在 Xcode 中运行时可实时查看 `[DEBUG]` 前缀的调试信息

### 单元测试（未完善）
当前项目未包含单元测试，欢迎贡献。

---

## 🤝 贡献指南

欢迎提交 Issue 或 Pull Request！

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交修改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开 Pull Request

---

## 📄 许可证

本项目采用 **MIT License**，详情请见 [LICENSE](LICENSE) 文件。

---

## 🙏 致谢

- [MLX](https://github.com/ml-explore/mlx) - Apple 的机器学习框架
- [Hugging Face](https://huggingface.co/) - 模型托管与分发
- [Homebrew](https://brew.sh/) - macOS 包管理器

---