Plan and Tech Debt

計畫與技術債(Plan and Tech Debt)

本頁追蹤已知的技術債、設計上的取捨,以及對應的改善計畫。方向性的功能規劃請見 Roadmap。

項目	現況	風險	改善方向
測試與實作程式碼分離	測試檔案自行複製/重建純邏輯,`src/*.js` 無法直接 import(content/background 為 Chrome 環境腳本)	邏輯改動時測試不會自動失效,可能測到過期的複本	把可測邏輯抽成 `src/lib/*.mjs` 共用模組,background/content 與測試都 import 同一份
`content.js` 過大	單檔約 880 行,混合選取偵測、工具列 UI、面板 UI、訊息傳遞	修改牽一髮動全身,難以局部測試	拆分為 selection、toolbar、panel、messaging 模組(可用 build step 或 ES module content script)
`<all_urls>` host permission	content script 注入所有頁面,靠白名單在執行期過濾	安裝時權限警告嚇人、審查(Web Store)阻力大、不必要的攻擊面	評估改用 `optional_host_permissions` + 動態註冊 content script(`chrome.scripting.registerContentScripts`)

項目	現況	風險	改善方向
Groq 供應商硬編碼	`GROQ_MODEL`、API 端點、驗證流程都寫死在 `background.js`	模型退役(llama-3.3 已非最新)即整條功能失效	抽象 provider 介面;模型名稱改為設定項
OpenEvidence URL 依賴內部參數	`buildOpenEvidenceUrl` 帶有 `configName=prod&_rsc=1pln2` 等未文件化參數	對方改版即失效,且無偵測機制	定期驗證 URL 形狀;考慮 fallback 到基本 `?query=` 形式
儲存鍵散落	`oe*` storage key 常數在 background/options/content 各自定義	改名或加鍵時容易漏改	收斂到單一 `constants` 模組(與測試共用)
無 lint / formatter 設定	repo 內無 ESLint/Biome/Prettier 設定檔,風格靠人工維持	貢獻者風格漂移、低級錯誤無自動攔截	加入 Biome(單一工具同時做 lint+format)與 CI 檢查
CI 僅在 release 時跑測試	push/PR 沒有測試 workflow	壞 commit 可能停留在 main 直到下次發版才被發現	加一個 `test.yml`:push/PR 觸發 `npm test`

項目	現況	改善方向
歷史紀錄無搜尋/匯出	僅能瀏覽與清除,上限 200 筆	選項頁加搜尋、篩選、JSON/CSV 匯出
錯誤處理靜默	多處 `catch(() => {})` 吞掉錯誤(如 `chrome.windows.update`)	至少 `console.debug`,關鍵路徑給使用者可見的失敗提示
UI 字串硬編碼	英文字串散落各檔	抽出 `_locales/`,鋪路 i18n
圖示無來源檔	`icons/` 只有 PNG 成品	補上 SVG 原始檔與產生腳本

零框架、零依賴:換來極小的 bundle 與零供應鏈風險,代價是 UI 程式碼較冗長——接受。
測試不 mock Chrome API:runner 極簡(原生 Node + assert),代價是瀏覽器行為靠手動驗證——目前規模下接受,若 bug 集中在瀏覽器層再引入 puppeteer 級的 e2e。
BYOK 而非內建代理:使用者需自備 Groq key,但金鑰與查詢內容完全不經第三方——安全性優先,不改。

建立 CI 測試 workflow(小、獨立、立即止血)。
抽出共用邏輯模組:URL builder、白名單比對、歷史 entry 建構 → src/lib/;測試改為直接 import。這是後續所有重構的地基。
加入 Biome + CI 檢查。
拆分 content.js(依賴步驟 2 的模組化基礎)。
權限縮減 spike:驗證動態註冊 content script 在 file:/// 情境的可行性。
Provider 抽象(配合 Roadmap 的多 LLM 供應商方向)。

oe-extension Wiki