Skip to content

Maintenance

Jump to bottom
Hsiehting Lin edited this page Jul 3, 2026 · 1 revision

維護指南(Maintenance)

本頁說明專案結構、開發流程、測試與發佈方式,供維護者與貢獻者參考。

專案結構

oe-extension/
├── manifest.json        # Manifest V3 定義(permissions、content_scripts、side_panel)
├── src/
│   ├── background.js    # Service worker:開分頁/側欄、context menu、Groq 呼叫、歷史紀錄
│   ├── content.js       # Content script:選取偵測、浮動工具列、LLM 輸出面板
│   ├── content.css      # 工具列與面板樣式
│   ├── options.html/js/css   # 選項頁:白名單、Groq key、自訂 prompt、歷史、外觀
│   └── sidepanel.html/js/css # Side Panel 容器(以 iframe 載入查詢 URL)
├── scripts/
│   ├── build-extension.mjs   # 建置:複製檔案到 dist/extension 並 zip
│   └── run-tests.mjs         # 測試 runner:依序執行 tests/*.test.mjs
├── tests/               # Node 原生測試(無測試框架)
├── icons/               # 16/32/48/128 圖示
└── .github/workflows/   # release 打包(zip + crx)

主要模組職責

background.js(service worker,約 530 行)

  • 儲存鍵定義:oeWhitelist、oeOpenMode、oeGroqApiKey、oeHistory 等。
  • URL 建構:buildOpenEvidenceUrl / buildUpToDateUrl / buildGoogleUrl。
  • 開啟模式分派(dispatchOpen):背景分頁 / 前景分頁 / Side Panel。
  • 開啟模式以 in-memory 快取(loadOpenMode),因為 user gesture 觸發的訊息不能等 async storage 讀取。
  • Groq API 呼叫(model:llama-3.3-70b-versatile,timeout 30 秒)。
  • 查詢歷史寫入(上限 200 筆)。

content.js(約 880 行)

  • 監聽 selection 事件,對照白名單決定是否顯示工具列。
  • 工具列定位與捲動追蹤。
  • PICO / 自訂 prompt 的可編輯輸出面板(Copy / Ask OpenEvidence / Close)。

options.js(約 470 行)

  • 分頁式選項頁:白名單編輯、Groq key 驗證、自訂 prompt CRUD、歷史檢視、外觀模式。

開發流程

npm test          # 執行 tests/ 下所有 *.test.mjs
npm run build     # 產出 dist/extension 與 dist/oe-extension-v<版本>.zip
  • 無相依套件(package.json 沒有 dependencies),不需要 install 步驟。
  • 開發時直接在 chrome://extensions 以 Load unpacked 載入專案根目錄或 dist/extension,修改後按重新整理。

測試

  • 測試位於 tests/*.test.mjs,以 Node 原生 assert 撰寫,由 scripts/run-tests.mjs 依檔名排序逐一執行,任一失敗則 exit code 非 0。
  • 現有測試涵蓋:URL 格式、白名單比對、開啟模式、歷史紀錄、PICO prompt、自訂 prompt、主題、設定等純邏輯部分。
  • 測試策略:被測邏輯需可從 src/*.js 抽出或複製為純函式;Chrome API 相關行為(分頁、storage、side panel)目前靠手動驗證。

版本與發佈

發佈流程(GitHub Actions,tag push 或 release 建立時觸發):

  1. 更新 manifest.json 與 package.json 的版本號(兩者需一致,CI 會驗證)。
  2. 更新 CITATION.cff / README 中的版本(如適用)。
  3. Commit 後打 tag:git tag v<版本> && git push origin v<版本>。
  4. CI 執行測試 → 建置 zip → 打包 crx → 上傳為 release artifacts。

注意事項:

  • 穩定的 CRX ID 需要 repo secret CRX_PRIVATE_KEY_BASE64(base64 編碼的私鑰);缺少時 CI 仍會產出 .crx,但 Chrome 可能指派新的 extension ID。
  • 版本號規則:目前為 0.x,patch 為修正與小功能,minor 保留給行為變更。

常見維護工作

工作 位置
調整預設白名單 src/background.js 的 DEFAULT_WHITELIST(README 的 Default Whitelist 段落需同步)
更換 Groq 模型 src/background.js 的 GROQ_MODEL
修改 PICO 指令 src/background.js 的 PICO_INSTRUCTION(tests/pico-prompt.test.mjs 需同步)
OpenEvidence URL 形狀變動 src/background.js 的 buildOpenEvidenceUrl + tests/url-format.test.mjs
調整歷史上限 src/background.js 的 HISTORY_LIMIT(預設 200)

除錯要點

  • Service worker log:chrome://extensions → 本擴充功能 → service worker 連結。
  • Content script log:直接在目標頁面開 DevTools。
  • Chrome 內建 PDF 檢視器不一定把 selection 事件傳給 content script,工具列不出現屬預期行為,備援是右鍵選單。
  • 本地 PDF 需在擴充功能詳細資料頁啟用 Allow access to file URLs。

oe-extension Wiki

Clone this wiki locally