Skip to content

Plan and Tech Debt

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

計畫與技術債

最後更新：2026-07-03。「計畫」是有明確意圖的工作項；「技術債」是已知的權衡，記錄成本與償還條件，不代表馬上要處理。

進行中的計畫

1. DataDome POST fallback（分支 feat/datadome-browser-ask-fallback）

oe_ask 的 POST 從 Node 直送會被 DataDome 封鎖；已驗證可行的解法是 open-url 瀏覽器 fallback（askViaBrowser），在 relay 路徑失效時自動退回。分支尚未合併——需要決定：作為永久保險絲合入 main，或在 relay 路徑足夠穩定後捨棄。

2. Cut v0.4.0

Unreleased 區塊已累積 shared relay daemon、fire-and-forget ask、RELAY_TRANSPORT=all 預設化等重大變更（含 BREAKING）。發佈時要同步：package.json 版本、CHANGELOG 日期、擴充功能是否需要對應的 extension-v* tag。

3. 設計文件的落地驗證

shared-relay-daemon 設計文件（status: accepted）已實作完成；後續新設計沿用同一模式：docs/plans/YYYY-MM-DD-<topic>.md，先寫 Problem / Decision / Architecture 再動手。

技術債清單

依「利息高低」排序——利息高 = 平常就在付出成本；利息低 = 只在特定情境才痛。

高利息

# 債務 成本 償還條件
1 雙軌傳輸路徑：extension relay（預設）與 legacy cookie 路徑（OE_MCP_RELAY_TRANSPORT=off）並存，doctor / login / smoke / Python 工具鏈都掛在 cookie 路徑上 每個讀取功能都要考慮兩條路徑；文件與疑難排解分裂 若 relay 路徑證明長期穩定，把 Python 工具鏈改走 relay，cookie 路徑降為純除錯用或移除
2 TS ↔ Python 跨語言橋接：oe_collections_* 工具由 TS server shell out 到 scripts/collection_sort.py（python-bridge.ts，依賴 OE_MCP_PYTHON） 使用者環境需要可用的 python3；錯誤處理跨進程邊界；型別不共享 評估把 collections 邏輯移植進 TS（sqlite 部分可用 better-sqlite3），或正式接受 Python 為一級依賴並寫進安裝檢查

中利息

# 債務 成本 償還條件
3 repo 根目錄的工作檔：多個 *.har（含 dotflow 系列）、cookies.json、openevidence-fingerprint.json 躺在根目錄 新貢獻者困惑；誤 commit 敏感資料的風險面 移到 gitignored 的 local/ 或 ~/.openevidence-mcp/，README 指路
4 extension/key.pem 在 repo 目錄內 簽章私鑰若誤入版本庫即洩漏（已確認 gitignored，但位置仍危險） 移出 repo 目錄，CI 簽章改用 secret
5 測試涵蓋：make smoke 依賴 legacy cookie 路徑；relay 路徑（daemon 拉起、自我修復、fire-and-forget 輪詢）缺自動化端對端測試 重構 relay 時只能手動驗證 對 relay-server / relay-client 加整合測試（可 mock extension 的 poll/result 迴圈）

低利息（記錄在案）

# 債務 成本 償還條件
6 fingerprint 依賴手動 HAR 擷取：legacy 路徑要使用者匯出 HAR 才能萃取瀏覽器指紋 只影響 cookie 路徑的新機器設定 隨債務 #1 一併解決（路徑移除則債務消失）
7 launchd 排程僅限 macOS Linux / Windows 使用者無現成排程 有需求時補 systemd timer 範本
8 schema v1 → v2 遷移碼：SQLite 的 legacy-account 自動遷移邏輯需要長期保留 少量維護面積 確認所有使用者都在 v2 後（或大版號時）移除

原則

  • 新增債務時：寫進上表，標明成本與償還條件；能在 PR 內順手還的小債直接還
  • 償還債務時：從高利息開始；償還本身開分支＋更新本頁
  • 每次 cut release 前重看一次本頁，過期項目移除或降級

相關頁面

OpenEvidence MCP

外部連結

Clone this wiki locally