開發者指南

EinkBro 以 Kotlin 與現代 Android 開發實踐建構。本指南涵蓋架構、建置流程與貢獻者的主要開發領域。

架構概觀

EinkBro 架構：app 模組（Activity、ViewModel、Repository、EBWebView、Koin、Services）與 ad-filter、adblock-client 模組

核心模式

MVVM — ViewModel 搭配 LiveData/StateFlow 管理 UI 狀態
Repository Pattern — 資料層抽象化（例如 OpenAiRepository.kt）
Dependency Injection — 以 Koin 為 DI 容器，於 EinkBroApplication.kt 設定
Room Database — 本地資料持久化，搭配 KSP 註解處理器
Jetpack Compose — UI 元件（對話框、設定、工具列、選單）

模組結構

模組	用途	關鍵技術
app	主瀏覽器應用程式	Kotlin、Compose、Room、Koin、WebView
ad-filter	廣告封鎖邏輯與 JS scriptlets	JavaScript、FilterViewModel
adblock-client	原生廣告封鎖實作	C++、CMake、JNI

主要元件

元件	說明
`EinkBroApplication.kt`	Application 類別；初始化 Koin DI 容器
`BrowserActivity.kt`	主 Activity（`singleInstance` 啟動模式）；處理所有瀏覽器 UI
`EBWebView.kt`	為 E-Ink 最佳化的自訂 WebView（滾動行為、閱讀模式 CSS 注入、JS 介面）
`GptActionsActivity.kt`	AI／ChatGPT 互動的 UI
`OpenAiRepository.kt`	OpenAI、Gemini 與相容伺服器的 API 通訊層
`ChatGptQuery.kt`	儲存 GPT 查詢結果的 Room 實體
`ConfigManager.kt`	以 Kotlin property delegate 包裝的 SharedPreferences，統一處理所有設定
`ToolbarAction.kt`	定義所有 43 個工具列動作（含圖示、標籤與狀態）的 Enum
`MenuDialogFragment.kt`	以 Compose 實作、可收合分區的動作選單

建置設定

屬性	值
Min SDK	24（Android 7.0）
Target SDK	34（Android 14）
Compile SDK	36
JVM Target	Java 17
Kotlin	2.1.20 搭配 KSP
建置工具	AGP 8.13.2、Gradle 8.14.5
ABI Splits	arm64-v8a、armeabi-v7a、x86、x86_64

建置指令

開發

# 建置 debug APK
./gradlew assembleDebug

# 建置 release APK
./gradlew assembleRelease

# 建置 releaseDebuggable 變體
./gradlew assembleReleaseDebuggable

# 安裝 debug 版本至已連接裝置
./gradlew installDebug

# 清除建置輸出
./gradlew clean

測試

# 執行單元測試
./gradlew test

# 執行儀表化測試
./gradlew connectedAndroidTest

# 執行 Lint 檢查
./gradlew lint

# 僅 debug 版的 Lint
./gradlew lintDebug

主要開發領域

WebView 客製化

E-Ink 專屬的 WebView 最佳化實作於 EBWebView.kt：

依 E-Ink 重新整理特性調整的自訂滾動行為
注入閱讀模式 CSS，呈現乾淨的內容
為原生功能整合提供 JavaScript 介面（觸控追蹤、頁面資訊等）
JS 檔案放在 assets/，於執行期載入

AI 整合

ChatGPT／AI 功能橫跨多個元件：

GptActionsActivity.kt — AI 聊天互動的 UI
OpenAiRepository.kt — OpenAI、Gemini 與自架伺服器的 API 通訊
ChatGptQuery.kt — 儲存查詢歷史的 Room 實體
使用者可透過系統提示定義自訂 GPT 動作

EPUB 處理

使用 EPubLib 實作完整的 EPUB 讀取與寫入：

於瀏覽器內解析並呈現 EPUB 內容
將網頁匯出為包含圖片與多章節的 EPUB
目錄可編輯，支援拖曳排序

翻譯服務

多家提供者的翻譯整合，支援段落級、整頁與圖片翻譯。提供者包括 Google Translate、DeepL，以及透過 OpenAI／Gemini 的 AI 翻譯。

資料庫與 Schema

Room 資料庫 schema 存放於 app/schemas/。修改實體時請務必定義好遷移路徑。主要實體包括書籤、歷史紀錄、GPT 查詢與白名單。

國際化

本專案支援 25 種以上語言，透過 Crowdin 管理。翻譯檔使用標準 Android 格式，位於 res/values-*/strings.xml。請勿直接編輯翻譯檔 — 所有變更都應透過 Crowdin 進行。

ProGuard

Release 版本會透過 ProGuard 進行程式碼混淆與最佳化：

app/proguard-rules.txt — Release 版本
app/proguard-rules.pro — ReleaseDebuggable 版本

如何貢獻

於 GitHub 上 Fork 此儲存庫
從 main 建立 feature branch
進行變更，並盡可能在 E-Ink 裝置上測試
送出 Pull Request 並清楚描述變更內容

本專案使用 Fastlane 進行部署自動化，並支援 F-Droid 發佈。