Alpha 農民曆（Alpha Almanac）

把 WorldQuant BRAIN 散落在平台文件、Help Center、論壇、公告裡的知識與活動爬到本機建成知識庫， 透過 MCP 讓 Claude Desktop（或其他 MCP 用戶端）直接問規則、名詞、比賽與 Power Pool，答案附出處；另附活動月曆（預設台灣時間）。 參加 2026 Q4 Agent Creation Mini Challenge（Info & Rule, Others）。介紹與使用說明書：docs/forum_post.md。

只用唯讀資訊類 API，不呼叫 Brain simulation API、不讀個人 Alpha。帳密與 cookie 只存在本機 .env 與 data/（皆不提交）。 本 repo 只有程式碼，不含任何爬下來的資料：每個人用自己的帳號建自己的知識庫。

快速開始（Windows）

git clone https://github.com/CCDRRR/alpha-almanac.git
cd alpha-almanac
powershell -ExecutionPolicy Bypass -File setup.ps1   # 建 venv、裝套件（約 5–10 分鐘）
notepad .env                                          # 填入 WQ_ACCOUNT / WQ_PASSWORD
.venv\Scripts\python -m wqbka.bootstrap               # 掃臉登入 → 爬資料 → 建索引 → 產生月曆（約 30 分鐘）
.venv\Scripts\python -m wqbka.desktop_config          # 自動加入 Claude Desktop 設定（會先備份）

最後從系統匣「Quit」Claude Desktop 再重開，就能在對話中問「PPA 是什麼？」「打開月曆」。 之後更新資料：.venv\Scripts\python -m wqbka.bootstrap --update（增量，約 1–3 分鐘）。

Related MCP server: loci-mcp

個別指令

copy .env.example .env          # 填入 WQ_ACCOUNT / WQ_PASSWORD
python -m wqbka.auth login      # 會開瀏覽器做生物辨識，完成後按 Enter（session 4 小時）
python -m wqbka.auth status     # 查看 session 剩餘時間
python -m wqbka.crawl           # 增量爬全部來源 → data/kb.sqlite（首次約 10 分鐘，之後約 30 秒）
python -m wqbka.crawl forum     # 只爬指定來源：competitions events operators tutorials videos help_center forum announcements data_categories datasets

# 索引（需專案 venv：pip install -r requirements.txt；首次約 12 分鐘 CPU，之後只算變動段落）
.venv\Scripts\python -m wqbka.index build
.venv\Scripts\python -m wqbka.index search "pyramid 是什麼"
.venv\Scripts\python -m wqbka.index term "super alpha"
.venv\Scripts\python scripts\search_smoke.py   # 10 題檢索冒煙測試

檢索：intfloat/multilingual-e5-base 向量 + BM25（中文單字/雙字）以 RRF 融合，依權威等級加權； 另開「只看官方」候選池並保留一半名額，避免中文問題只撈到論壇。詞彙表另建精確查詢表（112 詞）。

中英對照查詢擴充：wqbka/aliases.csv（人工整理，約 150 詞，隨 repo 提供，歡迎 PR 補充）。 查詢中出現中文說法或別名（例：金字塔乘數、自相關、換手率、雙週挑戰、ARC）時自動補上英文正式名詞； 官方候選池另以「純英文」查詢檢索。平台專有名詞（SuperAlpha、ATOM、Power Pool…）依台灣論壇實際用法保留英文、不自創翻譯。

工具（wqbka/tools.py，Web agent 與 MCP 共用）

活動月曆

.venv\Scripts\python -m wqbka.calendar --open             # 產生 data/calendar.html（靜態頁，雙擊即可開）；爬蟲結束後也會自動重建
.venv\Scripts\python -m wqbka.calendar --view pp --q GLB  # 直接開在 Power Pool 檢視並搜尋 GLB（agent 的 open_calendar 也是這樣做）

規則解析（不用 LLM）：官方比賽 / 活動 API 的結構化日期；平台 Theme 公告的「Duration:」行（同名 Theme 以最新的 Update 公告為準）； 台灣顧問論壇主辦方公告（標題 🎖️📅🦸 / [公告]，日期依序取標題 M/D-M/D → 內文「提交期間」→「時程」表）， 並抽出「目的 / 計分方式 / 獎項」段落。參賽者投稿（[2026 Q3 Challenge] …）不列入。

時區：頁面預設台灣時間，可切換美東時間（官方以美東為準）。官方比賽 / 活動 API 有精確時刻（含時區位移）；只有日期的項目（Theme、論壇公告）視為美東當天 00:00:00–23:59:59，再換算台灣時間（calendar_items.time_basis：exact / et_date）。get_calendar 會多回 start_tw / end_tw。 | kb_status | 知識庫涵蓋範圍、最後更新時間 | 否 | | search_live | 本地沒有或要求最新時，即時搜 Help Center + 論壇，寫回本地並建索引 | 是（過期才提示掃臉） | | login_start / login_finish | 在對話中登入：開啟掃臉頁 → 使用者掃完 → 完成登入（帳密只從本機 .env 讀） | — |

MCP（Claude Desktop / Claude Code）

Claude Desktop：在設定檔的 mcpServers 加入下面這段（路徑換成你的專案位置；保留檔案裡原有的其他設定）。用 PYTHONPATH 指定專案根目錄，不依賴 cwd。

{
  "mcpServers": {
    "alpha-almanac": {
      "command": "C:\\path\\to\\alpha-almanac\\.venv\\Scripts\\python.exe",
      "args": ["-m", "wqbka.mcp_server"],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\alpha-almanac",
        "PYTHONIOENCODING": "utf-8",
        "HF_HUB_OFFLINE": "1"
      }
    }
  }
}

設定檔位置依版本不同：

• 新版（5.x，設定裡沒有 Developer 選單）：%LOCALAPPDATA%\Claude-Data\claude_*\claude_desktop_config.json

• 舊版：設定 → Developer → Edit Config（%APPDATA%\Claude\claude_desktop_config.json）

存檔後從系統匣完全結束 Claude Desktop 再開。確認是否連上：%LOCALAPPDATA%\Claude\logs\main.log 不應再出現 no stdio servers connected。 使用規則（等同 system prompt）寫在 wqbka/mcp_server.py 的 INSTRUCTIONS，連上時自動送給模型。

知識來源

刻意不碰：/simulations*、/suggest/*、/alphas、/user/*（模擬、個人 alpha、帳號操作）。

論壇登入：用平台 session 呼叫 api /authentication/support?return_to=… 換取 Zendesk cookie（SSO）。

評測

.venv\Scripts\python scripts\eval_kb.py      # 題庫 tests/kb_golden.json：52 題檢索（22 組中英同義）、10 個詞彙、4 個結構化工具、7 個離題問題

最近一次（2026-11-12）：檢索 Hit@1 75.0%、Hit@3 94.2%、Hit@6 96.2%、MRR 0.848（中文 Hit@3 90.9%、英文 95.5%）； 詞彙表 100%；結構化工具 100%；離題偵測 6/7、領域內誤判 0/52；單次檢索平均約 50 ms。 注意：權重與門檻是用同一份題庫調的，數字偏樂觀；之後會用真實使用者問題另建驗證集。