Hackintosh-skill:把 AI 助手變成黑蘋果安裝工程師

3 分鐘閱讀時長

發布時間:

Hackintosh-skill:把 AI 助手變成黑蘋果安裝工程師

專案:zxmls-ai/Hackintosh-skill|授權:MIT|語言:Python|版本:v0.2.10(2026-11-05)|⭐ 25|建立:2026-10-29

這是什麼

Hackintosh-skill 是一份「餵給 AI Agent 的黑蘋果安裝指南技能包」。你把它的入口文件貼給 Codex、Claude Code、DeepSeek、WorkBuddy 等具備檔案讀寫、終端指令與網路能力的 Agent,Agent 就會從另一台電腦遠端操控你的 Windows PC,一步步帶你完成 macOS(黑蘋果)雙系統安裝,並在安裝後逐項偵測硬體、修復驅動程式、驗證硬碟開機,直到交付備份與復原方法。

它不是傳統的「通用 EFI 下載站」——專案明確宣稱不提供可直接套用的通用 EFI,而是由 Agent 針對你這台機器的實際硬體證據,現場生成、稽核、驗證專屬配置。整個流程用「階段契約+證據審核」約束 AI 的行為,避免模型自由發揮把硬碟格式化的災難。

一句話定位:黑蘋果安裝的 SOP 工程化——把流程、門檻、回退點全部寫成 Agent 可執行的契約,人只負責現場看螢幕與按鍵。

雙機架構:A 裝機、B 助攻

這個專案最特別的設計是兩台電腦分工:

┌──────────────┐  SSH / SFTP(家用網路) ┌──────────────┐
│  B 電腦(助手)│ ◄────────────────────► │ A 電腦(安裝機)│
│  你與 Agent   │  採集硬體 / 傳檔案 /    │  現跑 Windows  │
│  聊天與存進度 │  執行指令 / 記錄證據    │  將裝 macOS    │
└──────────────┘                        └──────────────┘
        ▲                                      ▲
  你在此讀提示、回傳結果          你在 A 前看螢幕、插 U 盤、選開機選單
  • A 電腦是安裝機:現在跑 Windows,之後要從 U 盤啟動安裝 macOS,預設保留 Windows 與使用者資料。
  • B 電腦是助手機:你在這裡打開 AI 工具。Agent 透過 SSH 遠端讀取 A 的硬體、傳送安裝檔、執行指令,並在 B 保存進度,讓 A 重開機後能斷點續接。

為什麼要兩台?聊天助手只能操作自己所在的機器;不開 SSH,Agent 就碰不到 A。而 macOS 安裝過程必然重開機、斷線,進度落盤在 B 才能在每次重連後接回原步驟。

九個階段的流程契約

整個安裝被切成 00~08 九個階段,定義在 macos-remote-install/workflow.json,每個階段都有固定的輸入、前置條件、動作、驗收項目、失敗路線與續接點:

階段名稱重點
00準備工作與遠端接入產生固定 SSH 設定腳本,實測 SSH、主機金鑰、機器身分、管理員權限、SFTP 往返校驗,全過才推進(此階段有完整程式執行器)
01檢查硬體與可裝版本跑固定採集腳本(含 ACPI、USB、顯示接線),查原作者相容資料,決定硬體路線與 macOS 版本
02備份檔案與預留空間核對硬碟穩定身分(禁止照抄盤號)、備份後內容校驗與抽樣還原,才動分區
03製作開機 U 盤三選一 EFI 路線 → 下載元件鎖版本 → 組裝本機 EFI → efi_audit.py 稽核+同版本 ocvalidate → 寫入後從 A 回讀校驗
04現場安裝你在 A 從 U 盤開機,Agent 交付一份填好真實分區名稱、容量、開機選單鍵的操作清單,從抹除到初始化照做
05開機交接重開機選單、繼續安裝、選安裝卷的固定交接表
06安裝後裝置驗收對照 Windows 清單逐裝置檢查:每張網卡、每張顯示卡優先查現成方案;Metal 計算探針實測 GPU
07疑難排錯依錯誤碼 recover,未覆蓋問題走 diagnose → repair → 原步驟重驗
08收尾交付雙系統拔 U 盤冷啟動實測通過才算完成,交付備份與復原方法

階段的關鍵哲學是「證據門檻」:檔案存在不等於硬體可用。例如驗證開機不能只複製 EFI 檔案——要同時核對韌體 Boot#### 啟動項、BootOrder 預設順序、OpenCore 選單實際顯示,最後還要有拔盤冷啟動的回執才能進入下一階段。

EFI 三條路線:先讓人選,再驗證

階段 03 組裝 EFI 前,Agent 必須原樣展示三個選項並登記使用者選擇(choose-efi),不能擅自改道:

路線做法定位
a用 RapidEFI-Tool 生成後適配推薦;具備桌面控制能力的 Agent 可自動操作生成器並取回產物
b尋找相似配置的案例後適配保留案例原版作為同機基線對照
cAI 依官方 Sample 模板+本機證據生成最手工,證據要求最高

選定後經 solutions.py lookup → select-source 登記來源,再用唯讀的 efi_audit.py 稽核開關狀態、條件式、檔案差異與版本依據。同一來源的無效試改滿兩次即被擋下,強制回到基線對照或補證據——這直接治了「AI 無依據堆補丁越改越壞」的常見黑蘋果悲劇。

倉庫內容一覽

組成內容
macos-remote-install/SKILL.md跨 Agent 精簡技能入口,按階段載入資料(v0.2.10)
AI-GUIDE.md由相同內容合成的 195 KB 單檔指南,適合直接附給 Agent
START-HERE.md/新手对话预览.md新手起步、離線載入與 WorkBuddy 用法、首輪對話示範
references/(14 份)SSH 接入、硬體分流、儲存、安裝介質、開機交接、安裝後驗收、排錯、EFI 稽核、現成方案手冊、安裝後契約、14700K+4070 Ti SUPER 脱敏案例等
scripts/(15 支 Python/PS1/SH)見下表
workflow.json/upgrades.json00~08 階段契約;舊版本任務的遷移登記表
downloads/v0.1.0 → v0.2.10 共 18 個 WorkBuddy 適配 ZIP+SHA256 校驗清單
tests/(11 檔)純標準庫合成資料迴歸測試,v0.2.10 達 190 項全過
VALIDATION.md/TEST-FEEDBACK.md每版實測範圍與未測項目的誠實紀錄、實機回饋表

核心腳本(全用 Python 標準庫,需 Python 3.10+):

腳本職責
workflow.py(55 KB)流程控制器 CLI:init / status / prepare / review / choose-efi / record-devices / boot-ready / upgrade,管理私有任務目錄與狀態機
ssh_transport.py固定 SSH 連接器:金鑰指紋核對、認證、SFTP 往返校驗
collect-windows.ps1/collect-macos.shA 端硬體採集(Windows 與 macOS 雙端清單,供 06 逐項比對)
enable-windows-ssh.ps1A 端一次性的 SSH 開啟腳本(使用者貼上執行一次)
efi_audit.py唯讀 EFI 稽核:開關/條件/檔案差異/版本依據,部署後回讀比對
target_guard.py/acpi_guard.py/postinstall_guard.py寫盤前硬碟身分守衛、ACPI 表門檻、安裝後清單門檻
solutions.py現成方案查證:依板型/裝置 ID 找來源、登記、審計
metal_smoke_test.jsJXA Metal 計算探針:在目標 GPU 提交工作並回讀 4096 個值,證明顯示卡真的可用
find-rapidefi-output.ps1定位 RapidEFI 桌面產物(處理空格/中文路徑、多產物篩選)
tools/build_release.py由 SKILL.md+references 同步生成 AI-GUIDE 與 WorkBuddy 包

安全設計:對 AI 寫盤權限的防呆

黑蘋果最恐怖的事故是格式化錯盤。這份技能包針對 Agent 能力做了多層護欄:

  1. 身分先於操作:任何寫盤前必須核對硬碟穩定身分、實際佈局與操作範圍,禁止照抄盤號/盤符。
  2. 授權逐筆登記:清空任何裝置前單獨取得該對象授權,說明會失去什麼、備份驗證結果。
  3. 沒有清盤器:配套工具刻意不含一鍵清盤工具;磁碟操作由 Agent 現場生成可審查的專屬步驟。
  4. 證據不可覆寫:新驗證不得覆蓋已登記證據;源碼、狀態檔有哈希鎖定,跳過階段會被契約檢查擋下。
  5. 能力邊界誠實聲明:僅有網頁讀取權限的 Agent 會進入「人工指導模式」,不偽造控制器輸出;插拔設備、拍開機畫面、BIOS 操作、Apple 帳號登入仍由人配合。

驗證狀態與已知限制(重要)

專案處於測試階段,README 頂部就有免責聲明,VALIDATION.md 每版都明列「測了什麼、沒測什麼」:

  • ✅ 190 項本地合成迴歸測試全過(含 CLI 讀寫私有模擬任務、斷點續接、本機模擬 SSH);
  • ✅ 14700K+4070 Ti SUPER 案例有真實 Metal 計算回讀的舊驅動紀錄;
  • ⚠️ 完整執行器目前只覆蓋階段 00,01~08 是「契約+Agent 執行+證據審核」模式;
  • ⚠️ WorkBuddy+DeepSeek 對目標機的全流程實機安裝仍在驗收中,未宣稱任一版本已全流程實機通過;
  • ⚠️ 不同 Agent/模型/權限組合會產生執行順序與排錯差異,固定流程只能減少、不能消除 AI 誤判。

倉庫不含 macOS 映像檔、驅動二進位檔、個人 EFI 或任何真實機器識別碼;每次安裝資料存在 B 的私有 runs 目錄,發 issue 前需去識別化。

快速開始

在 B 電腦(能讀檔、跑指令、聯網的 AI 助手)貼上下列兩行(引自 README 原文,維持簡體以照貼)即可開工:

请读取 https://github.com/zxmls-ai/Hackintosh-skill 的 README 和 macos-remote-install/SKILL.md,
带我在另一台电脑安装 macOS,并保留 Windows。
我第一次操作。先告诉我两台电脑各做什么、现在要准备什么,再告诉我到哪台电脑做哪一步。清空任何设备前请先和我核对。

A 電腦需求:UEFI 開機的 x86-64(Intel 或 AMD)、Windows 管理員帳號+非空登入密碼(PIN 不算)、與 B 同一可互訪的網路;稍後需要一支可清空的 U 盤與備份空間。習慣 WorkBuddy 技能導入者可直接下載官方 macos-remote-install-workbuddy-v0.2.10.zip 適配包並以 SHA256SUMS 校驗。

總結評價

亮點

  • 把 AI 不確定性工程化:階段契約、驗收清單、證據登記、試改上限,是少見認真約束 Agent 高風險動作的技能包設計。
  • 雙機+斷點續接設計精準命中「安裝中必重開機斷線」的痛點,進度與證據全部落盤在 B。
  • 誠實的驗證文化:每版明列未測項、不承諾通用 EFI、測試全採合成資料,免責邊界寫得比多數專案認真。
  • 迭代極快:上線 8 天推出 18 個版本(v0.1.0→v0.2.10),大量條款直接來自使用者實機回饋(如「跳過硬體修復」「複製 EFI 未登記啟動項」都被寫成契約擋掉)。
  • 純標準庫 Python、單檔指南、ZIP 離線包,部署門檻低。

限制

  • 仍在公測,全流程實機背書有限;唯一工作機不建議當白老鼠。
  • 需要兩台電腦、家用網路互通與 Agent 具備 SSH/檔案執行權限,門檻高於純文件指南。
  • 高度依賴 Agent 工具鏈能力:無桌面控制的 Agent 在 RapidEFI、BIOS 等環節仍需人工點擊。
  • 黑蘋果本身的硬體相容性硬限制(驅動支援、筆電難度)不因流程改善而消失。

適合:想玩雙系統、手邊有兩台電腦、願意全程在場配合的進階使用者,以及想觀察「如何用契約約束 Agent 執行高風險操作」的 AI 工程從業者。不適合:只有一台電腦、追求一鍵完成,或把這台機器當唯一生產力工具的人。


資料來源:專案 README、SKILL.md、workflow.json、VALIDATION.md、CHANGELOG.md 與 GitHub API(2026-11-06 擷取)。