耳機已經連上 Linux、音樂也能播放，為什麼轉頭時卻收不到角度？這篇 MousePods 教學帶你把「連線成功」拆成能逐步確認的證據，並學會請 Claude Code 協助讀程式、整理假設與檢查感測資料。
前半專為完全沒有硬體除錯背景的讀者寫；後半給已有 Git、Python 與 Linux 基礎環境、願意貼指令的人。先用公開錄包練習，再到耳機實機；最後才啟用游標。你會留下版本、資料與操作結果，知道卡在哪一層。
本文依 2026 年 11 月 10 日查閱的一手文件整理，固定 MousePods 版本 d00f7914f0d4bb9234aded0abb333f990979fbbc。AlphaLab 在 macOS 的 Python 3.11 隔離環境完成公開資料回放與核心測試；Linux 藍牙、耳機及游標控制未在本次執行。下文硬體觀察歸屬原作者，實機驗收由你的設備逐項填寫。
先說結論：硬體除錯＝分層證據＋一次一個變因
硬體除錯＝分層證據＋一次一個變因。把耳機想成一間有幾個櫃檯的店：能聽音樂，只證明你到了音訊櫃檯；感測器還有自己的入口、資料格式和啟動步驟。Claude Code 可以幫你看地圖，真正有沒有取到資料，要由紀錄回答。
今天先做三件事：固定版本、回放作者錄包、確認暫停方法。沒有相容耳機也能完成前兩件；有 Linux 與耳機的人，再走「診斷 → 校正 → 游標」三關。不要先讓游標亂跑，再猜究竟是哪個零件壞了。
一、MousePods 教學先認五個零件：連上、收到、讀懂，各有證據
① 藍牙：「先建立往來管道」
Bluetooth（藍牙，近距離無線通訊）能承載不同服務。配對是建立信任，連線是建立通道；音訊服務正常，仍要另外確認感測服務。本文只操作自己配對的耳機，不掃描或連接別人的裝置。
② L2CAP 與 MTU：「通道一次能收多大的包裹」
L2CAP 是藍牙裡負責資料通道的協定；MTU 是單次傳輸資料大小的限制。作者的 AirPods 3 研究紀錄比較接收 MTU 672 與 2582：前者只見較小的裝置描述，後者才見到包含動作感測器的較大描述。這是作者在其 AirPods 3／Ubuntu 24.04／BlueZ 5.72 配置的觀察，別直接套成所有藍牙裝置的通則。
白話說，資料還沒開始送，耳機先寄來「有哪些櫃檯」的名冊；名冊放不進收件口，你可能連感測器存在都看不到。專案協定文件要求在連線前設定接收 MTU。使用本篇固定版程式即可沿用其實作，先別修改整台電腦的藍牙設定。
③ RemoteHID：「先打招呼，再指定哪個感測器開工」
HID 是人機介面裝置；RemoteHID 是這個專案研究的 Apple 通訊格式。作者在 AirPods 3 上整理出 HostConnect → DeviceConnect → SetReport → InputReport：主機打招呼、耳機列出裝置、設定回報間隔、開始收資料。AirPods Pro 2 則走專案另一條 SensorDataWX 路徑；不要把兩者的封包混著猜。
④ 感測解析：「數字要帶方向與單位」
IMU（慣性感測單元）包含加速度與旋轉相關訊號。Yaw 是左右轉頭、pitch 是抬頭低頭、roll 是向肩膀側傾；可配合 三個旋轉軸示意理解。原始數字還要經過座標轉換與校正，才知道「往左」應該讓畫面怎麼動。
⑤ 輸出：「收到角度，才決定接到哪裡」
MousePods 可以把姿態送到不同輸出；桌面游標使用 Linux 的 /dev/uinput 虛擬輸入裝置。讀數、計算與控制桌面分開驗，就像先驗收溫度計，再決定是否讓它控制冷氣。模型和執行工具的分工，可先看 Agent Harness 白話入門。
二、先排好環境與相容性：把未知留在紀錄裡
截至查閱日，README 的實機清單將 AirPods 3、AirPods Pro 2 的 Lightning 與 USB-C 版本列為已驗證；其他型號逐項看狀態。原始 Reddit 回覆對 Pro 3 表達預期，但作者也說尚未親測；預期與實機紀錄分開，本文不承諾 Pro 3 可直接完成這套流程。
完整硬體路線需要 Linux、BlueZ、已配對並連線的耳機，以及游標階段所需的 /dev/uinput 寫入權限。先記下耳機型號、韌體、發行版、桌面環境與 python3 --version、bluetoothctl --version。Python 至少 3.10；版本不足時先切到已安裝的相容環境。
本篇用原始碼路線，讓你能對照檔案與測試。若只想使用現成 App，README 另有 Flatpak 安裝入口。兩條路的設定存放位置不同，第一輪先選一條，避免同時開兩個控制程序。不可變發行版若遇到編譯依賴，先讀 README 的專屬安裝段落，不要一路加入系統權限。
三、MousePods 教學五步走：先讀資料，最後才開游標
第 1 步：「我到底拿到哪一版？」固定來源
怕 AI 參考的是昨天的程式？先把版本鎖住。在新的練習資料夾依序執行下面指令；git rev-parse HEAD 應印出本文完整 commit。這是刻意固定的教學快照，後續升級請另開一輪紀錄。
git clone https://github.com/starman-tech/mousepods.git
cd mousepods
git checkout d00f7914f0d4bb9234aded0abb333f990979fbbc
git rev-parse HEAD
python3 -m venv .venvLinux 實機路線接著執行 .venv/bin/python -m pip install -r requirements.txt。它安裝專案的 evdev 與 numpy 依賴；若失敗，保存完整錯誤，先處理發行版的建置前提。僅做本篇 macOS 回放練習時，可在隔離環境安裝 numpy，不啟動 Linux 輸入裝置。
第 2 步：「先不用耳機，解析流程能走通嗎？」回放公開材料
怕把藍牙故障和解析錯誤混在一起？先用固定錄包。下面命令讀取 作者公開的去識別化 captures，不開耳機連線。第二行只跑核心引擎測試，不把整個專案的 README 測試徽章當成你本機結果。
.venv/bin/python gestures.py --replay captures/airpods3_motion_capture.json --stats
.venv/bin/python -m unittest discover -s tests -p test_engine.pyAlphaLab 本次在 Python 3.11 得到 Ran 26 tests 與 OK。回放的統計摘要包含 samples=3614、rate_hz=187.8、gaps=25、max_gap_ms=1367；這是固定錄包經這版程式處理的輸出，不是本機耳機的新量測，也不等於完整原始錄包筆數。
這份結果教你看三件事：有成功解析的樣本、有被程式判定的資料間隙、也有插值。不要只摘最高 Hz。回放印出的手勢事件與信心分數，也不直接代表辨識正確；例如安靜片段可能出現候選事件，仍需對標籤與啟動條件。
公開研究、文件與錄包來自 Matteo Gaudioso（starman-tech）的 MousePods，採 CC BY 4.0；此處做繁中解說與節錄，未改動用來回放的原始檔。
第 3 步：「AI 憑什麼這樣判斷？」讓 Claude Code 交出證據
怕一句「修好了」取代真正定位？先只讀，要求可反駁的假設。已有 Claude Code 帳號與安裝的人，在這份專案內啟動 claude，先給下面提示；安裝與登入依 Claude Code 官方入門完成。
請先只讀這個固定版本，不執行藍牙連線、不控制游標。
沿 README、docs/REMOTEHID-PROTOCOL.md、l2cap.py 和 tests 追資料流。
列出三個可能原因；每個附檔案位置、支持證據、反例和下一個檢查。
區分「程式推論」「公開錄包結果」「待我實機確認」。
先解釋 --diag 與 gestures.py --replay 的副作用，再提任何修改。例如「未收到感測器描述」可以對照兩份 airpods3_announces_mtu*.hex；「描述有了、讀值沒變」則追啟動回報與樣本時間。請它指出哪段程式真的改變 MTU，再看測試如何驗這個呼叫。想懂完整工具迴圈，可接著讀 最小 Harness 實作。
Anthropic 的 權限文件與 實務指南分別說明工具權限與提供可執行檢查的重要性。這裡先限縮工作到讀檔、回放與特定測試；任何要改系統、開輸入裝置的步驟，先看清楚目的與命令。不要給 AI 整台機器的永久放行來代替定位。
第 4 步：「耳機真的有在回報嗎？」實機只開診斷
Linux 與依賴備妥後，戴好已配對的耳機，執行 .venv/bin/python airpods_mouse_controller.py --diag。依此版本實作，它使用 NullPointer 而非游標裝置，並停用耳柄點擊輸出；診斷仍會建立藍牙連線、啟動感測資料，因此先確認耳機屬於自己。
坐穩後依序做「保持不動 → 左轉 → 回中 → 右轉 → 回中 → 抬頭 → 低頭」，每次只改一個動作。記下資料是否持續、轉動時對應軸是否變化、回中是否可重新定位。這是本篇建議的驗收順序，未預填你的通過結果。按 Ctrl-C 結束這輪診斷，再進下一步。
專案提供的下列法文介面截圖中，Mouvement 是動作頁、Calibration 是校正頁、Commencer 是開始。它們是作者的介面示意，不是本次 Linux 診斷畫面。
如果沒資料，先看耳機連線與裝置公告；如果有數字但方向錯，先查配戴姿勢與校正；如果方向正確卻游標不動，才查輸出權限。原作者也留下 PnP DeviceID 與重新配對是否必要的未隔離問題，因此別把「改 MTU」寫成所有環境唯一的修復答案。
第 5 步：「可以停得住嗎？」校正、短試與復原
怕啟用後游標失控？先備妥第二條控制路徑。保留實體滑鼠與另一個終端機，再執行 .venv/bin/python airpods_mouse_controller.py --ui。此版本新設定預設暫停游標，但會記住後來的暫停／恢復狀態；舊設定重開時，要先確認目前狀態。
在 App 的 Calibration 頁按引導操作，確認配戴方式、回中和方向，再短暫恢復游標。CLI 的 --calibrate 另走校正視窗，本篇先沿 App 流程。每次只調靈敏度或平滑其中一項，測完先暫停，再記錄是否改善。
以下在第二個終端機、同一原始碼資料夾執行，且主控制程序要正在運作。先試 pause 能確實停止桌面輸出，再使用 recenter 重設正前方；確認環境安全才 resume。
.venv/bin/python airpods_mouse_controller.py --send pause
.venv/bin/python airpods_mouse_controller.py --send recenter
.venv/bin/python airpods_mouse_controller.py --send resume結束時先送 --send pause，再送 --send quit。要回到測試前設定，第一次 App 執行後、調整前先複製來源目錄的 config.json 為 config.before-lab.json；退出程序後再還原該副本。這是原始碼路線的設定復原，並非耳機韌體重置。第一輪先不安裝自啟動、全域快捷鍵或遊戲橋接。
四、怎麼寫一份 AI 也能幫忙的除錯紀錄？
每一輪留下：commit、耳機／韌體、Linux／BlueZ、命令、預期、實際輸出、唯一改動、下一步。例如「可播放音樂，但診斷無樣本」只算音訊通過；「回放通過、實機沒有 DeviceConnect」才把注意力收斂到實機連線與公告。假設被推翻也保留，避免 AI 下次再繞同一圈。
紀錄要分享前，移除藍牙位址、個人裝置名與其他私人資料。輸出文字可保留時間、封包種類與欄位結構；別把整份本機設定直接貼到公開 issue。要延伸到其他裝置，可對照 Claude 藍牙尋物與 Tizen 電視部署教學，比較每層該留下什麼證據。
常見問題：八個先講答案的判斷
1. 藍牙音訊正常，就表示感測器能用了嗎？
還不能這樣判定。這個流程要另外看到裝置公告、感測樣本與方向變化，再驗輸出。
2. AirPods Pro 3 可以照做嗎？
先列為待確認。本文採用的實機清單明列 AirPods 3 與 Pro 2；作者早期對 Pro 3 的預期，不作成功保證。
3. 需要先買新耳機嗎？
先不用為練習添購。已有電腦可從公開 captures、程式與測試學分層除錯；是否購買，等看過設備相容性與自己的用途再決定。
4. 200 Hz 就一定比 100 Hz 好用嗎？
不一定。作者資料有高頻率觀察，也有間隙與共用藍牙的條件；實際控制還要看方向、延遲、平滑和中斷。本文不把頻率當操控排名。
5. 可以直接拿去飛行模擬器嗎？
先另做整合驗收。專案已有 opentrack 與遊戲輸出，也列出 Assetto Corsa、ETS2 的具名測試；這些紀錄不能替每款飛行遊戲背書。本篇先不修改遊戲檔案。
6. Claude Code 寫好測試，就能代替硬體確認嗎？
兩者驗收範圍不同。測試確認既定輸入的處理；耳機是否真的送出資料、方向是否符合配戴，需要實機紀錄。
7. 一定要用特定 Claude 模型嗎？
本篇不設定特定模型門檻。練習核心是讀檔、提出可反駁假設與執行檢查；未做模型間能力或費用比較。
8. 游標一直偏，先把靈敏度拉高嗎？
先回到診斷與回中。確認靜止漂移、配戴位置與軸向，再單獨調一個設定；拉高靈敏度可能只是把偏差一起放大。
給新手的三個重點
先分層：音訊、感測、解析、方向、游標各有證據。再控變因：固定版本，一次只改一項。最後保留停手方法：先暫停、再退出、必要時還原設定。這樣 AI 的每次建議，才有能回查的前後差異。
接著閱讀
左右滑動查看更多推薦
下一步：先交出一張「收到什麼」的紀錄
今天先固定 commit、跑公開錄包，抄下樣本與間隙欄位，再請 Claude Code 解釋每個欄位的程式來源。有 Linux 與相容耳機，再補上自己的診斷與方向結果。分層證據＋一次一個變因，就是你下次接感測器、控制器或其他硬體時能帶走的方法。
想把這套方法接成完整工作流，可從 AlphaLab AI 專區繼續學，或到 AlphaLab 課程安排下一段練習。