用 AI 改造閱星曈 X3／X4 韌體：Fork CrossPoint、編譯與實作教學

先說結論：AI 能加速，但不能替你驗機

CrossPoint 是供 XTEINK X3、X4 使用的社群開源閱讀器韌體，採 MIT 授權。上游專案明確指出兩款裝置都以 ESP32-C3 為核心，可用 RAM 約只有 380KB；程式必須保守使用記憶體，並把大型資料快取到 microSD。

AI 程式助手很適合幫你：

• 導覽陌生的 C++ 專案，找出選單、顯示、Wi-Fi 與檔案處理模組。
• 先提出最小修改計畫，再產生小範圍 diff。
• 執行編譯、閱讀錯誤訊息並逐步修正。
• 補單元測試、靜態檢查與文件。

但 AI 看不到你的實機狀態，也不能保證 E Ink 刷新、耗電、按鍵、看門狗與救援流程一定正確。能編譯不等於能安全刷，能開機也不等於功能穩定。 最後仍要由人確認變更、刷機並在實機測試。

動手前先判斷難度

如果你只想安裝 Kindle、Kobo、Readmoo 或其他 Android App，X3／X4 的 ESP32 韌體開發路線並不適合；應改看 Android 閱讀器，或等待 S4 的正式供貨與完整規格。不要把「可以改韌體」誤解成「可以安裝 Android App」。

Step 1：從官方 CrossPoint 專案開始

官方 repository 是 crosspoint-reader/crosspoint-reader。截至本文查核時，README 的開發前提包括：

• pioarduino，或 VS Code 搭配 pioarduino plugin。
• Python 3.8 以上。
• clang-format 21。
• 可傳輸資料的 USB-C 線。

先 fork，再把 submodule 一併 clone：

~~~bash

git clone --recursive https://github.com/你的帳號/crosspoint-reader

cd crosspoint-reader

~~~

若一開始忘了帶 <code>--recursive</code>，再執行：

~~~bash

git submodule update --init --recursive

~~~

上游提供的 contributor 檢查包括格式化、靜態檢查與編譯：

~~~bash

./bin/clang-format-fix

pio check -e default

pio run -e default

~~~

Windows 的實際命令與序列埠設定可能不同，請以 repository 當下 README、platformio 設定與你的工具版本為準。第一個里程碑只有一個：不改任何程式，先讓原始碼完整編譯成功。

Step 2：先請 AI 畫地圖，不要立刻改檔

把 repository 交給 Claude Code、Codex 或其他能讀取工作區與執行終端命令的工具後，第一個 prompt 應限制它只做唯讀盤點：

這是 CrossPoint Reader，目標是 ESP32-C3 的 XTEINK X3／X4。先不要修改檔案。請依實際 repository 畫出開機流程、UI／選單、E Ink 顯示、EPUB 解析、Wi-Fi／Web 服務、設定儲存與測試的模組地圖；每一項列出檔案路徑、主要函式與相依關係。不確定的地方請標示，不能猜。

這個做法能先驗證 AI 是否真的讀過目前版本的程式碼，也避免它根據舊文章或其他 ESP32 專案憑空發明 API。

Step 3：把功能拆成最小可驗證 diff

不要一口氣要求「幫我做天氣 App」。先讓 AI 回答四件事：

1. 哪些現有模組可重用？
2. 最少要改哪些檔案？
3. 最壞失敗方式是什麼？
4. 如何在不刷機前先測試純資料邏輯？

可以使用這個 prompt：

我想新增一個唯讀資訊卡。請先不要寫完整功能。找出現有 Wi-Fi 連線、HTTP、畫面繪製、按鍵與設定儲存 API，提出最小修改計畫。限制：ESP32-C3 可用 RAM 很少，不得載入大型 JSON，不得建立長時間阻塞迴圈；網路失敗必須能返回原畫面。先列測試策略，再給第一個最小 diff。

一次只接受一個小 diff，然後依序執行：檢查差異、編譯、跑測試、上機測、記錄結果。若發生 reset，必須取得序列埠紀錄，而不是繼續叫 AI 猜。

範例一：Wi-Fi 聯網資訊卡

CrossPoint 已有 AP／STA Wi-Fi、檔案傳輸 Web UI、Web settings、OPDS 與 OTA 等網路功能，因此「重用既有網路層」比自行另建一套連線流程合理。

適合先做的小功能包括：

• 顯示一筆天氣摘要。
• 顯示自架 API 回傳的三項數字。
• 顯示幾條待辦或 RSS 標題。

建議拆成以下階段：

1. 先用固定假資料畫出畫面，確認字型、換行與按鍵返回。
2. 把資料解析寫成可在電腦測試的純函式。
3. 只抓極小回應，限制逾時與最大下載量。
4. 網路錯誤時顯示簡短訊息，不能卡住主迴圈。
5. 最後才評估自動更新、休眠與耗電。

不要預設「HTTP 一定比 HTTPS 好」。未加密 HTTP 會暴露內容，也可能遭竄改；若 TLS 對記憶體造成壓力，更安全的設計通常是縮小 payload、使用你控制的精簡端點、驗證憑證與限制更新頻率，而不是直接放棄加密。

範例二：自己的會員條碼卡

另一個適合離線實作的方向，是顯示你自己有權使用的會員條碼或 QR Code。這比複製 NFC 卡單純，也不需要網路常駐。

實作時應把工作分開：

• 資料只保存名稱、號碼與碼制。
• 條碼演算法使用授權相容、體積可控的既有實作；不要讓 AI 隨意重寫規格。
• 顯示必須保留 quiet zone、足夠尺寸與黑白對比。
• 以多種掃描器與不同亮度環境測試。
• 不在程式碼或公開 repository 放真實會員號碼。

這個範例只限你自己的會員卡。門禁卡、交通票證、支付憑證與加密 NFC 卡涉及不同硬體、協定與權限，不應用「顯示條碼」的概念混為一談。

Step 4：編譯通過後，刷機仍要回到官方流程

CrossPoint 官方目前提供 Web flasher、SD 卡刷機與特定鎖定裝置使用的 unlock 工具。官方網站建議 X3／X4 可使用 SD 卡方式：把官方提供的 <code>update.bin</code> 放到 SD 卡根目錄，接上 USB 電源後按住電源鍵與向上鍵；X3 的對應鍵是左上角按鍵。實際畫面與後續重啟方式仍應以當下官方頁面為準。

幾個不能省略的原則：

• 先用官方 release 跑通流程，再刷自己的 build。
• 在官方 flasher 中選對 X3 或 X4；不要只看檔名猜機型。
• 國際版、第三方通路版與開發版的 USB 鎖定狀態可能不同。
• unlock 工具只支援官方列明的韌體；官方警告不受支援的韌體可能永久失去恢復路徑。
• 夜間版與自製 build 風險高於穩定 release，不適合第一次刷機。
• 刷機前保存書檔、設定與目前可用版本資訊；恢復原廠的方式以官方 flasher 當下提供的選項為準。

Step 5：常見失敗如何讓 AI 幫忙

編譯失敗

貼完整命令、第一個真正錯誤、工具版本與變更 diff。不要只貼最後一行「build failed」。要求 AI 先解釋根因，再提供最小修正。

上機後 reset 或卡住

先用上游建議的序列埠監控方式取得紀錄。要求 AI 針對 stack trace、heap 與 watchdog 證據分析；沒有紀錄就不要假裝已定位。

中文缺字

CrossPoint 內建字型不完整涵蓋 CJK，但官方提供 SD-card Font Builder，可把 TTF／OTF 轉成 <code>.cpfont</code> 後放入 SD 卡。若想以中文介面為基礎研究，也可閱讀社群的 crosspoint-reader-cjk；fork 的功能、更新速度與授權需以該 repository 為準。

畫面刷新或耗電異常

先回到最小固定畫面，確認問題來自資料、繪圖還是更新頻率。不要讓 AI 在沒有硬體紀錄的情況下大改 E Ink driver 或電源管理。

AI prompt 檢查表

每次請 AI 修改前，至少交代：

• 目標裝置是 XTEINK X3 或 X4，核心為 ESP32-C3。
• 必須依目前 repository 的 API，不可憑記憶發明函式。
• RAM 非常有限，大型資料要分段處理或快取到 SD。
• 一次只做一個最小 diff。
• 編譯與測試命令必須實際執行並回報結果。
• 不修改 bootloader、分區、顯示 driver 或電源管理，除非任務確實需要且已有證據。
• 任何實機刷機步驟由使用者自己執行。

與既有刷機指南怎麼搭配？

這篇聚焦「如何用 AI 讀懂與修改 CrossPoint 程式碼」。如果你還沒安裝過 CrossPoint，先看站內的 閱星曈 X3／X4 CrossPoint 刷機指南；想比較不同社群分支，再看 閱星曈 X3／X4 第三方韌體整理。

對應機型資料：

• 閱星曈 X3 規格與版本
• 閱星曈 X4 規格與版本

常見問題

資料來源與查核日期

• CrossPoint Reader 官方網站：支援機型、Web flasher、SD 卡刷機、USB 鎖與風險提示。
• CrossPoint Reader GitHub：MIT 授權、ESP32-C3、開發環境、編譯檢查、網路功能與 RAM 限制。
• CrossPoint User Guide：操作、字型與故障排除。
• crosspoint-reader-cjk：CJK 社群 fork。
• XTEINK 官方支援頁：X3／X4 原廠使用指南與更新入口。
• Read with Pro：閱星曈 X3／X4 CrossPoint 刷機指南：站內基礎刷機與版本脈絡。
• Read with Pro：閱星曈 X3／X4 第三方韌體整理：社群分支比較。

查核日期：2026 年 7 月 13 日。CrossPoint 更新頻繁，命令、支援韌體與刷機流程請以官方網站及 repository 最新版本為準。