第一次開源貢獻：幫電子書閱讀器的韌體加上中文支援

在這之前，我寫的程式幾乎都只有自己、同學或實驗室的人會看：學校作業、實驗室專案、自己的部落格。

這篇想記錄我第一次對公開的開源專案做貢獻的過程。對象是 crosspoint-reader，一個電子書閱讀器的開源韌體，GitHub 上有 8000 多顆星。

起點：一台每天在用的閱讀器

暑假時，我買了一台很迷你的電子書閱讀器——閱星曈，螢幕只有 4.3 吋。

圖: 旁邊放一把 15 公分的尺，就知道它有多小。休眠畫面上的「休眠中」，是我自己改的繁中版韌體（目前只有自己在用）

因為不是很喜歡原本的韌體，所以在網路上找了一個開源的韌體刷進去，也就是 crosspoint-reader。

它很小一台，帶出門很方便，不知不覺就看完了一本書。書我會直接存在 SD 卡裡，或是從我 NAS 上的 Calibre-Web 透過 OPDS 傳進去，整個流程很順。

後來還在淘寶買了一個殼，套上去之後，看起來更像一本小書了 XD

圖: 套上殼之後，像不像一本小筆記本？

不過這個韌體雖然支援 CJK 字體，介面卻沒有中文，所以我就想把介面換成中文。

這樣想著，我就把專案 fork 下來，開始用 AI 魔改它。

結果改來改去，反而越來越常當機，甚至都沒辦法好好看書了。

所以我最後決定回到官方版本，一次只改一點點，先送 PR 看看。

第一個被 merge 的 PR，是我在魔改的時候發現的一個小小 bug，開 PR 當天就被 maintainer 按了 approve，留言只有短短的「LGTM」。看到那個紫色的 Merged 標籤時，真的滿開心的。

被 merge 的 PR

從 8 月底到 10 月初，我一共開了 9 個 PR，其中 4 個已經被 merge：

其中 #3484 花了快一個月。中間 rebase 了好幾次，因為其他人的 PR 也在改同一段程式。最後還有人用自動化 agent 在實體的 Xteink X3 上跑 QA，確認亞美尼亞文和喬治亞文真的顯示得出來，才被 merge。

繁體中文介面：被拒絕之後重新設計

而我最想做的其實是 #3360：加入繁體中文介面，但它到現在都還沒被 merge。

一開始 maintainer 就很直接地說（原文是英文，以下是我的意譯）：

我們沒辦法把 CJK 字型放進韌體，它們太佔空間了。所以我們不會接受 CJK 的介面翻譯。

這個限制確實很合理。閱讀器的快閃記憶體很小，如果為了中文把幾千個字的字型塞進韌體，每一個使用者都要為此付出容量，即使他們根本不看中文。

所以我重新設計了一版：

• 內建字型只多加 4 個字：「繁體中文」，讓使用者在語言選單裡至少看得到、選得到這個選項
• 其他所有中文介面文字，改用 SD 卡上的字型來顯示。使用者第一次選擇繁體中文時，會被提示去安裝中文字型
• 結果，韌體增加的大小從原本約 120KB 降到約 1.1KB

maintainer 接著問：「那翻譯字串本身佔多少空間？」

哈哈，我確實忘記量了。後來實際去量之後發現，繁中字串表大約 8.6KB，加上字型總共約 9.7KB。我也用同樣的方法量了已經上線的波斯文，大約 15.6KB，比繁中還大。

目前這個 PR 是 draft 狀態，maintainer 說「願意重新考慮，但需要再想想」。另一位 reviewer 也幫忙補充：這種「內建字型只放語言名稱、其他用 SD 卡字型」的做法，其實也適用於天城文這類複雜的文字系統。後來甚至有其他使用者留言問：「這個 PR 很有用，有後續嗎？」

雖然還沒被 merge，但這是我學最多的一個 PR：開源專案不是我想加什麼就加什麼，而是要在專案的限制下找到大家都能接受的設計。

用 AI 做開源貢獻

老實說，這些 PR 大部分都是用 Claude Code 完成的：讀陌生的 C++ codebase、找出問題在哪、寫修正、回應 review。

但這段經驗也讓我學到 AI 的限制。

有一個 PR（#3455）是修正兩本書的書籤檔名可能撞在一起的問題。maintainer 問我：「這是你真的遇到的問題，還是預防性的修正？」我承認是 AI 在 review 程式碼時找到的，我自己沒有遇過。他回：

我猜是 LLM agent 幫你找到的。它們很習慣指出現實中幾乎不會發生的邊界情況，然後寫一大包 patch 來修。如果每個邊界情況都處理，韌體會塞滿幾乎用不到的程式碼，維護起來會是一場惡夢。

這段話讓我反省了一下自己是不是造成了別人的困擾。後來另一個 PR（#3483）也是理論上可能出錯、但我沒有在實機上遇過的問題，我就自己把它關掉了。

而快取壞掉導致當機的那個 PR（#3452），maintainer 同樣問：「這是你真的遇到的嗎？」我就可以很有底氣地回答：「是的，閱讀器連續重開機三次，最後我拔 SD 卡手動刪檔才救回來。」

所以我現在給自己的原則是：AI 可以幫我寫、幫我讀、幫我找，但送出去的 PR，最好是我自己真的遇到的問題。

在手機上也能改程式

另一個讓我覺得很新奇的體驗：因為 Claude Code 可以在雲端執行，有時候在外面突然想到一個修法，就直接用手機開一個雲端 session 交代它去改，回到電腦前再檢查結果、在閱讀器上實測。

以前要做開源貢獻，得先 clone repo、裝好整個開發環境、找到時間坐在電腦前。現在門檻低了很多，零碎的時間也能推進一點。

像是 #3360，我就是在和朋友出去的時候收到 maintainer 的回覆，用手機和 AI 討論之後，讓它直接修改程式，再開模擬器截圖傳回來給我看。

小結

回頭看，這次經驗最大的收穫不是寫了多少程式，而是：

1. 從自己真的會用的東西開始：問題是實際遇到的，修起來有動力，跟 maintainer 溝通時也比較有根據。
2. 尊重專案的限制：被拒絕也不會擔心，可以先理解專案在乎什麼。
3. AI 是很強的工具，但判斷要自己做：哪些問題值得修、哪些只是理論上的邊界情況，最後還是要自己負責。

如果你也有每天在用的開源工具，遇到問題時不妨點開它的 GitHub 看看。說不定，你的第一個 PR 就從那裡開始。