@@ -9,7 +9,7 @@ on:
       version:
         description: 'Version to build'
         required: true
-        default: '2.0.3'
+        default: '2.0.4'
 
 jobs:
   build:
@@ -69,15 +69,57 @@ jobs:
     - name: Build application (macOS)
       if: matrix.platform == 'macos'
       run: |
+        # Create a proper macOS app bundle
         pyinstaller --onefile --windowed \
           --name "AugmentCode-Free-v${{ github.event.inputs.version || github.ref_name }}-macos" \
           --add-data "languages:languages" \
           --add-data "config:config" \
+          --add-data "augment_tools_core:augment_tools_core" \
+          --add-data "gui_qt6:gui_qt6" \
           --hidden-import=PyQt6.QtCore \
           --hidden-import=PyQt6.QtGui \
           --hidden-import=PyQt6.QtWidgets \
           --hidden-import=psutil \
+          --hidden-import=sqlite3 \
+          --hidden-import=xml.etree.ElementTree \
+          --hidden-import=pathlib \
+          --hidden-import=json \
+          --hidden-import=uuid \
+          --hidden-import=platform \
+          --hidden-import=subprocess \
+          --hidden-import=threading \
+          --hidden-import=queue \
+          --hidden-import=shutil \
+          --hidden-import=tempfile \
           --collect-all=PyQt6 \
+          --osx-bundle-identifier=com.basicprotein.augmentcode-free \
+          --target-arch=universal2 \
+          main.py
+
+        # Also create a standalone executable without app bundle for compatibility
+        pyinstaller --onefile \
+          --name "AugmentCode-Free-v${{ github.event.inputs.version || github.ref_name }}-macos-standalone" \
+          --add-data "languages:languages" \
+          --add-data "config:config" \
+          --add-data "augment_tools_core:augment_tools_core" \
+          --add-data "gui_qt6:gui_qt6" \
+          --hidden-import=PyQt6.QtCore \
+          --hidden-import=PyQt6.QtGui \
+          --hidden-import=PyQt6.QtWidgets \
+          --hidden-import=psutil \
+          --hidden-import=sqlite3 \
+          --hidden-import=xml.etree.ElementTree \
+          --hidden-import=pathlib \
+          --hidden-import=json \
+          --hidden-import=uuid \
+          --hidden-import=platform \
+          --hidden-import=subprocess \
+          --hidden-import=threading \
+          --hidden-import=queue \
+          --hidden-import=shutil \
+          --hidden-import=tempfile \
+          --collect-all=PyQt6 \
+          --target-arch=universal2 \
           main.py
 
     - name: Build application (Linux)
@@ -142,7 +184,7 @@ jobs:
           
           ### 📦 下载文件
           - **Windows**: `AugmentCode-Free-v${{ github.event.inputs.version || github.ref_name }}-windows.exe`
-          - **macOS**: `AugmentCode-Free-v${{ github.event.inputs.version || github.ref_name }}-macos`
+          - **macOS**: `AugmentCode-Free-v${{ github.event.inputs.version || github.ref_name }}-macos.app` (应用包) 或 `AugmentCode-Free-v${{ github.event.inputs.version || github.ref_name }}-macos-standalone` (独立可执行文件)
           - **Linux**: `AugmentCode-Free-v${{ github.event.inputs.version || github.ref_name }}-linux`
           
           ### 🚀 安装说明
@@ -153,23 +195,30 @@ jobs:
           3. 首次运行可能需要允许Windows Defender
           
           **macOS:**
-          1. 下载 macOS 版本
-          2. 添加执行权限: `chmod +x AugmentCode-Free-*-macos`
-          3. 运行: `./AugmentCode-Free-*-macos`
+          1. 下载 macOS 版本（推荐使用 standalone 版本）
+          2. 添加执行权限: `chmod +x AugmentCode-Free-*-macos-standalone`
+          3. 运行: `./AugmentCode-Free-*-macos-standalone`
           4. 如遇安全提示，请在系统偏好设置中允许
+          5. 或者使用 .app 版本：双击 `AugmentCode-Free-*-macos.app`
           
           **Linux:**
           1. 下载 Linux 版本
           2. 添加执行权限: `chmod +x AugmentCode-Free-*-linux`
           3. 运行: `./AugmentCode-Free-*-linux`
           
           ### 🔧 技术改进 v${{ github.event.inputs.version || github.ref_name }}
-          - ✅ 修复按钮显示键名问题，现在正确显示中文/英文文本
-          - ✅ 修复PyInstaller打包缺失语言文件的问题
-          - ✅ 完善所有工作线程和补丁操作的国际化支持
-          - ✅ 修复补丁状态"已补丁"等硬编码文本
+          - ✅ 权限检查增强：新增文件只读状态检测，提供友好的权限错误提示
+          - ✅ 国际化完善：错误信息支持中英文双语显示，包含详细解决方案
+          - ✅ macOS 构建修复：解决 "Failed to create parent directory structure" 错误
+          - ✅ 双版本支持：提供应用包(.app)和独立可执行文件两个版本
           - ✅ 支持Windows、macOS、Linux多平台自动构建
+          - ✅ 完善构建文档：新增 macOS 故障排除指南和自动化脚本
           
+          ### 📖 文档链接
+          - 📋 [构建说明](https://github.com/BasicProtein/AugmentCode-Free/blob/main/docs/BUILD_INSTRUCTIONS.md)
+          - 🔧 [macOS 故障排除指南](https://github.com/BasicProtein/AugmentCode-Free/blob/main/docs/MACOS_TROUBLESHOOTING.md)
+          - 📖 [完整文档](https://github.com/BasicProtein/AugmentCode-Free/blob/main/README.md)
+
           ### ⚠️ 重要提示
           - 本项目完全开源免费！
           - 如有人向您收费，请立即举报诈骗行为
 
@@ -18,6 +18,27 @@ https://t.me/+rL2-my2wYy5hODA1
 [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)](https://github.com/BasicProtein/AugmentCode-Free)
 
+#### 2025年8月22日更新 (v2.0.4)：
+
+**🔧 构建优化版 / Build Optimized Version**：
+
+**核心功能改进 / Core Feature Improvements:**
+- **权限检查增强 / Enhanced Permission Check**：新增文件只读状态检测，提供友好的权限错误提示 / Added read-only file detection with friendly permission error messages
+- **国际化完善 / Improved Internationalization**：错误信息支持中英文双语显示，包含详细解决方案 / Error messages support bilingual display with detailed solutions
+- **用户体验提升 / Enhanced User Experience**：当补丁失败时，自动检测是否为只读文件并提供具体操作指导 / Automatically detects read-only files when patching fails and provides specific guidance
+- **错误处理优化 / Optimized Error Handling**：区分权限问题和其他写入错误，提供针对性的解决建议 / Distinguishes permission issues from other write errors with targeted solutions
+
+**macOS 构建修复 / macOS Build Fixes:**
+- **构建问题修复 / Build Issues Fixed**：解决 "Failed to create parent directory structure" 错误 / Fixed "Failed to create parent directory structure" error
+- **双版本支持 / Dual Version Support**：提供应用包(.app)和独立可执行文件两个版本 / Provides both app bundle (.app) and standalone executable versions
+- **权限优化 / Permission Optimization**：自动处理 macOS 权限和安全设置 / Automatically handles macOS permissions and security settings
+- **架构支持 / Architecture Support**：支持 Universal2 架构（Intel + Apple Silicon）/ Supports Universal2 architecture (Intel + Apple Silicon)
+
+**文档完善 / Documentation Improvements:**
+- **构建指南 / Build Guide**：更新 macOS 构建说明，包含详细的故障排除 / Updated macOS build instructions with detailed troubleshooting
+- **故障排除 / Troubleshooting**：新增专用的 [macOS 故障排除指南](https://github.com/BasicProtein/AugmentCode-Free/blob/main/docs/MACOS_TROUBLESHOOTING.md) / Added dedicated [macOS Troubleshooting Guide](https://github.com/BasicProtein/AugmentCode-Free/blob/main/docs/MACOS_TROUBLESHOOTING.md)
+- **自动化脚本 / Automation Scripts**：提供 `build_macos.sh` 自动构建脚本 / Provides `build_macos.sh` automated build script
+
 #### 2025年8月14日更新 (v2.0.2)：
 
 **🔍 扩展文件扫描优化**：
@@ -591,23 +612,41 @@ Use these tools at your own risk. Always back up important data before running m
 
 **（重要的事情说三遍！）**
 
+## 📦 下载与安装 / Download & Installation
+
+### 预编译版本 / Pre-built Releases
+
+从 [GitHub Releases](https://github.com/BasicProtein/AugmentCode-Free/releases) 下载最新版本：
+
+- **Windows**: `AugmentCode-Free-v2.0.4-windows.exe`
+- **macOS**: `AugmentCode-Free-v2.0.4-macos.app` 或 `AugmentCode-Free-v2.0.4-macos-standalone`
+- **Linux**: `AugmentCode-Free-v2.0.4-linux`
+
+### macOS 用户特别说明 / Special Notes for macOS Users
+
+如果遇到构建或运行问题，请参考：
+- 📖 [构建说明 / Build Instructions](https://github.com/BasicProtein/AugmentCode-Free/blob/main/docs/BUILD_INSTRUCTIONS.md)
+- 🔧 [macOS 故障排除指南 / macOS Troubleshooting Guide](https://github.com/BasicProtein/AugmentCode-Free/blob/main/docs/MACOS_TROUBLESHOOTING.md)
+
+## 🚀 使用方法 / Usage
+
 您可以通过两种方式使用 AugmentCode-Free：
 
-### 1. 图形用户界面 (GUI) - 推荐
+### 1. 图形用户界面 (GUI) - 推荐 / Graphical User Interface (Recommended)
 GUI 为所有功能提供了简单易用的操作界面。
 
--   **直接运行 (从项目根目录):**
+-   **直接运行 (从项目根目录) / Direct Run (from project root):**
     ```bash
     python main.py
     ```
 
--   **如果通过 pip 安装 (作为 `augment-tools-gui`):**
+-   **如果通过 pip 安装 (作为 `augment-tools-gui`) / If installed via pip:**
     ```bash
     augment-tools-gui
     ```
 
-### 2. 命令行界面 (CLI)
-适用于喜欢命令行或需要编写脚本自动执行操作的用户。
+### 2. 命令行界面 (CLI) / Command Line Interface
+适用于喜欢命令行或需要编写脚本自动执行操作的用户。/ For users who prefer command line or need to automate operations with scripts.
 
 -   **如果通过 pip 安装 (作为 `augment-tools`):**
     ```bash