Hackintosh-skill:把 AI 助手變成黑蘋果安裝工程師
發布時間:
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 | 尋找相似配置的案例後適配 | 保留案例原版作為同機基線對照 |
| c | AI 依官方 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.json | 00~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.sh | A 端硬體採集(Windows 與 macOS 雙端清單,供 06 逐項比對) |
enable-windows-ssh.ps1 | A 端一次性的 SSH 開啟腳本(使用者貼上執行一次) |
efi_audit.py | 唯讀 EFI 稽核:開關/條件/檔案差異/版本依據,部署後回讀比對 |
target_guard.py/acpi_guard.py/postinstall_guard.py | 寫盤前硬碟身分守衛、ACPI 表門檻、安裝後清單門檻 |
solutions.py | 現成方案查證:依板型/裝置 ID 找來源、登記、審計 |
metal_smoke_test.js | JXA Metal 計算探針:在目標 GPU 提交工作並回讀 4096 個值,證明顯示卡真的可用 |
find-rapidefi-output.ps1 | 定位 RapidEFI 桌面產物(處理空格/中文路徑、多產物篩選) |
tools/build_release.py | 由 SKILL.md+references 同步生成 AI-GUIDE 與 WorkBuddy 包 |
安全設計:對 AI 寫盤權限的防呆
黑蘋果最恐怖的事故是格式化錯盤。這份技能包針對 Agent 能力做了多層護欄:
- 身分先於操作:任何寫盤前必須核對硬碟穩定身分、實際佈局與操作範圍,禁止照抄盤號/盤符。
- 授權逐筆登記:清空任何裝置前單獨取得該對象授權,說明會失去什麼、備份驗證結果。
- 沒有清盤器:配套工具刻意不含一鍵清盤工具;磁碟操作由 Agent 現場生成可審查的專屬步驟。
- 證據不可覆寫:新驗證不得覆蓋已登記證據;源碼、狀態檔有哈希鎖定,跳過階段會被契約檢查擋下。
- 能力邊界誠實聲明:僅有網頁讀取權限的 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 擷取)。