Skip to content

Maintenance

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

維護指南

日常維護、建置、疑難排解與排程作業的參考。所有指令都在 repo 根目錄執行；make help 隨時列出最新的完整 target 清單。

建置與重新安裝

make all          # 一鍵：依賴 + 建置 server 與擴充功能 + 註冊 Claude / Codex
make rebuild      # 清空 dist/ 後重建（每次建置前都會 wipe dist/，確保乾淨）
make build        # 只編譯 TypeScript（給 HAR=… 時會先抽取 fingerprint）
make check        # 型別檢查
make test         # 單元測試

註冊到各 CLI（make all 已涵蓋 Claude 與 Codex）：

make install-claude-global    # Claude Code
make install-codex-global     # Codex CLI
make install-agy-global       # Antigravity CLI
make install-all              # 三者全部

升級後記得重跑 make all（或 make rebuild）——/health 回報 version + pid，舊版 daemon 會在升級後被自動偵測並替換。

Relay daemon 管理

Relay 是獨立常駐程序（自動啟動、detached），擁有 port 8787，所有 MCP session 共用：

curl -s http://127.0.0.1:8787/health   # 健康檢查：connected / version / pid
make relay                             # 前景執行 daemon（除錯用）
make kill-all                          # 停掉所有 MCP server + relay daemon，釋放 8787

特性：

  • 自我修復：daemon 掛掉會被下一次呼叫重新拉起，進行中的請求會重試
  • 冪等：搶輸 port 的第二個 daemon 會乾淨退出（exit 0）
  • pidfile／log 預設在 ~/.openevidence-mcp/relay.pid 與 relay.log（OE_MCP_RELAY_PID_PATH / OE_MCP_RELAY_LOG_PATH 可覆寫）

擴充功能維護

  • 更新後在 chrome://extensions 按 ↻ 重新載入
  • 一次只在一個瀏覽器跑 relay——多個瀏覽器都載入擴充功能時，請求會落到先 poll 的那個
  • 點擊工具列圖示可開啟內建的 how-it-works 頁，含即時連線檢查

疑難排解速查

症狀 處置
擴充功能徽章不是綠色／connected:false 確認該瀏覽器已登入 openevidence.com 且有開分頁，然後重新載入擴充功能
工具回報 “relay not connected” 先啟動 AI 工具讓 daemon 起來，再 curl :8787/health；卡住舊建置時 make kill-all 後重連
升級後行為怪異 /health 看 version 是否為新版；不是就 make kill-all 讓新 daemon 接手
舊 cookie 路徑 DataDome 403 跑 doctor（見下節），通常是換機器後 cookie／fingerprint 失效

Doctor（舊 cookie 路徑）

只在 OE_MCP_RELAY_TRANSPORT=off 的 legacy 路徑相關：

npm run doctor              # 靜態檢查 + 一次線上讀取探測
npm run doctor -- --offline # 只做靜態檢查
npm run doctor -- --json    # 機器可讀輸出（CI 用，失敗時非零退出碼）

會標出 datadome-missing / -expired / -session、fingerprint-platform-mismatch（cookie 與 fingerprint 在不同 OS 產生——需在本機重新產生）、fingerprint-default、datadome-live 等問題。

Collections 同步排程（macOS launchd）

分類需要 agent 參與，但同步是純 I/O，可排程每日執行：

bash scripts/install_launchd.sh                  # 每日 02:00（OE_MCP_SYNC_HOUR / _MINUTE 可調）
launchctl start com.htlin.openevidence-mcp.sync  # 手動觸發一次驗證
tail -30 ~/.openevidence-mcp/logs/sync.log       # 看記錄
bash scripts/install_launchd.sh --uninstall      # 移除

模式（scripts/collection_sync_cron.sh 的參數，或 OE_MCP_SYNC_MODE）：

模式 行為
（預設） 只同步——新對話累積為 unsorted，等 routine 處理
--dry-run 同步 + 分類；寫出 proposed-plan.json 供審閱，不套用
--auto 同步 + 分類 + 套用 + 對帳；全自動分類

分類器 scripts/classify.py 完全離線（log-odds-ratio 簽名 + 關鍵字規則）；用 python scripts/classify.py validate 驗證，OE_MCP_AUTO_THRESHOLD（預設 12）與 OE_MCP_AUTO_TOP_K（預設 3）調整。

資料位置

路徑 內容
~/.openevidence-mcp/db/oe.sqlite Collections／chats 的本機鏡像（schema v2，account-scoped）
~/.openevidence-mcp/relay.pid / relay.log relay daemon 的 pidfile 與 log
~/.openevidence-mcp/logs/sync.log launchd 同步記錄
${OE_MCP_ARTIFACT_DIR}/<article_id>/ 每次回答的 artifacts：answer.md、article.json、citations.bib、crossref-validation.json 等

環境變數完整表見 README。

發佈備忘

  • 版本紀錄在 CHANGELOG.md（Keep a Changelog 格式）；目前 package.json 為 0.3.0，Unreleased 區塊累積中
  • 擴充功能以 extension-v* tag 觸發 CI 建置＋簽章（unpacked zip + .crx）

OpenEvidence MCP

外部連結

Clone this wiki locally