一套建構在 Claude Code skills + MCP servers 之上的美股投資研究與組合管理工作區。把日報、組合檢視、個股深度分析、選擇權策略、交易日誌等流程，全部封裝成可重複執行的 slash command，並用一套第一性原理紀律（可驗證 thesis → 證偽條件 → 機率分布 + EV）約束每一個投資結論，避免淪為 narrative。

• 使用對象：自行操作美股/選擇權、想用 LLM 輔助但要求紀律與可驗證性的個人投資人 / quant
• 輸出語言：全繁體中文
• 券商整合：透過 firstrade-server MCP 取即時持倉（以 Firstrade 為參考整合，可替換成你自己的券商 MCP）
• 資料來源：7 個 MCP server（即時報價、SEC、技術指標、情緒/基本面、預測市場等）+ FRED 總經 + EODHD 基本面 REST 快取
• 可選自動化：launchd 每個 NYSE 交易日定時產生並推送日報到 Telegram + Email

⚠️ 非投資建議。 本專案是分析與紀律工具，所有輸出僅供研究參考；你需自行承擔所有交易決策與風險，並自備所有 API key / 券商憑證。詳見文末免責聲明。

📦 自寫的兩個 MCP server（technical 技術指標、eodhd 情緒）已獨立開源於 fadacai-mcp-servers。

flowchart TD
    User(["👤 User<br/>L2 Margin Broker"])

    Hook["🔔 SessionStart Hook<br/>journal/YYYY-MM-DD.md 存在？<br/>✅ 已存在 → 略過 ｜ ⚡ 不存在 → gap-fill"]

    User -->|session 開始| Hook
    User -->|slash commands| Skills

    subgraph Skills ["⚡ Skills — Slash Commands"]
        direction LR
        B["/briefing<br/>quick · full · deep · telegram"]
        PR["/portfolio-review"]
        SA["/stock-analysis TICKER"]
        OS["/options-strategy"]
        TJ["/trade-journal"]
        MH["/mcp-health"]
    end

    Skills -->|共同執行| Step0

    subgraph Step0 ["📋 Step 0 統一規範（所有 skill 必跑）"]
        direction LR
        s0a["0a<br/>plan.md<br/>feedback/*.md"] --> s0b["0b<br/>get_account_position<br/>live broker"] --> s0c["0c/0d<br/>journal gap-fill<br/>今日快照"] --> s0e["0e<br/>第一性原理紀律<br/>thesis · 證偽 · EV"]
    end

    subgraph Models ["🤖 AI Model 分流（Cost Optimization）"]
        HAIKU["🟡 Haiku 4.5<br/>data-collector subagent<br/>mcp-health · trade-journal log<br/>純機械 · no synthesis"]
        SONNET["🔵 Sonnet 4.6<br/>日常分析合成<br/>briefing quick+telegram<br/>todo · journal review"]
        OPUS["🟠 Opus 4.8<br/>中等深度合成<br/>briefing full<br/>options-strategy"]
        FABLE["🔴 Fable 5<br/>最強旗艦 · 重推理<br/>portfolio-review · ev-check<br/>briefing deep · stock-analysis<br/>長 context · 機率/EV"]
    end

    s0e --> SONNET & OPUS & FABLE
    Skills -->|"subagent_type: data-collector"| HAIKU

    subgraph MCP ["🔌 7 MCP Servers — 外部即時數據"]
        direction LR
        FT["🏦 firstrade-server<br/>positions · balance · history"]
        YF["📈 yfinance-advanced<br/>quotes · options · financials · news"]
        SEC["📋 sec-edgar-mcp<br/>SEC filings · insider Form 4 · 8-K"]
        FMP["💹 fmp-mcp<br/>peers · market movers"]
        TECH["📊 technical-mcp<br/>RSI · MACD · ATR · S/R levels"]
        EODHD["💬 eodhd-mcp<br/>AI 情緒分析 −1→+1"]
        PM["🎲 polymarket-mcp<br/>預測市場概率"]
    end

    HAIKU -->|平行呼叫（Retry 3x）| MCP
    s0b --> FT
    Hook -->|讀寫| JRL

    subgraph KB ["📁 Knowledge Base — 本地檔案"]
        direction LR
        PL[("plan.md<br/>板塊目標 · 策略佇列")]
        FB[("feedback/<br/>交易風格規則")]
        JRL[("journal/<br/>每日倉位快照")]
        RES[("research/<br/>投資論文")]
    end

    s0a -->|讀取| PL & FB
    s0c <-->|讀寫| JRL

    CODEX["🤖 Codex（opt-in）<br/>--codex flag<br/>B1 獨立第一性分析<br/>B2 機會掃描 · B3 輪動"]
    SONNET & OPUS -->|opt-in| CODEX

    subgraph AutoSend ["📲 每日自動推送（ET 11:30）"]
        direction LR
        LAUNCHD["⏰ launchd<br/>com.fadacai.briefing<br/>NYSE 交易日才跑<br/>週五加 --codex"]
        RUNNER["🔧 briefing_runner.sh<br/>~/.local/bin/<br/>TCC-safe wrapper"]
        OUT_FILES["📄 briefing-out/<br/>YYYY-MM-DD-full.md<br/>YYYY-MM-DD-telegram.txt"]
        TG["📱 Telegram Bot<br/>emoji 純文字 < 1500 字"]
        EMAIL["📧 Gmail SMTP<br/>精簡版 + 完整 markdown"]
        SENDLOG["📋 send-log.jsonl"]
    end

    LAUNCHD --> RUNNER --> SONNET
    SONNET -->|--send flag| OUT_FILES
    OUT_FILES --> TG & EMAIL
    TG & EMAIL --> SENDLOG

    OUT["📊 繁體中文報告<br/>Verdict · EV · 口數 · 觸發條件"]
    SONNET --> OUT
    OPUS --> OUT

• Claude Code CLI（本框架的執行環境，skills / agents / MCP 都靠它）
• Python 3.10+（tools/ 腳本與部分 MCP server）
• uv（執行 Python MCP server，建議）
• macOS（launchd 自動推送為 macOS 專屬；其餘功能跨平台）

# 1. clone
git clone <this-repo-url> portfolio && cd portfolio

# 2. Python 依賴（tools/ 腳本用）
pip3 install -r tools/requirements.txt

# 3. 環境變數（自動推送 / 總經才需要；純互動分析可略過）
cp .env.example .env      # 再依註解填入你自己的 key

# 4. 啟動 Claude Code，輸入任一指令
claude
> /mcp-health             # 先確認 MCP 連線
> /briefing               # 跑第一份日報

本框架的數據來自 7 個 MCP server，需各自安裝並在 Claude Code 註冊（claude mcp add ... 或專案 .mcp.json）。所有 API key / 券商憑證由你自備，本 repo 不含任何金鑰。

Claude Code 註冊指令（/path/to/fadacai-mcp-servers 替換成你自己的路徑）：

# uvx 直接啟動（免 clone）
claude mcp add yfinance-advanced -- uvx yfinance-mcp
claude mcp add sec-edgar-mcp --env SEC_EDGAR_USER_AGENT="Your Name your@email.com" -- uvx sec-edgar-mcp
claude mcp add polymarket-mcp -- uvx polymarket-mcp

# fadacai-mcp-servers（clone 後 uv sync）
claude mcp add technical -- uv --directory /path/to/fadacai-mcp-servers/technical run server.py
claude mcp add eodhd-mcp --env EODHD_API_TOKEN=xxxx -- uv --directory /path/to/fadacai-mcp-servers/eodhd run server.py

# fmp-mcp（需 clone 到獨立資料夾，npm install && npm run build 後）
claude mcp add fmp-mcp --env FMP_API_KEY=xxxx -- node /path/to/fmp-mcp/dist/index.js

缺任一 server 不會讓整個框架失效——/mcp-health 會標出不可用者，skills 內建 retry → 健康檢查 → WebSearch fallback。

以上全部選用——不設也能用所有互動式 slash command，只是少了自動推送、總經快照與三錨點估值快取。

--send 旗標： 可加在任何 tier 後，執行完自動推送 Telegram + email。例：/briefing full --send

--codex 旗標： 任何分析 skill 後加，觸發 Codex 獨立第一性分析（B1）+ 機會掃描（B2）+ 輪動分析（B3）。--codex-adversarial 觸發壓力測試模式。

模型切換： 若 harness 未自動套用 frontmatter model，手動 /model sonnet 或 /model opus 後再執行 skill。Session context > 100k 時建議先 /compact。

/briefing                        ← 快速掃描（Sonnet，~1min）
/briefing full                   ← + 情緒面、預測市場
/briefing deep                   ← 完整版含 SEC + 個股分析（Opus）
/briefing telegram               ← 生成 Telegram 推送格式（寫出檔案，不發送）
/briefing telegram --send        ← 生成並推送至 Telegram + email
/briefing full --send --codex    ← 完整版 + Codex + 推送

/stock-analysis PLTR
/stock-analysis ANET CRWD        ← 兩檔比較，依 EV 排序
/stock-analysis MU --codex       ← + Codex 獨立第二意見

/options-strategy PLTR sell-put
/options-strategy PLTR AMD MU sell-put    ← 多標的 E_adj 比較
/options-strategy SSRM covered-call
/options-strategy MU leaps

/trade-journal auto              ← 自動偵測倉位變動
/trade-journal log               ← 手動記錄交易
/trade-journal review            ← 檢視計畫執行進度
/trade-journal summary           ← 月度損益摘要

python3 tools/send_briefing.py latest        # 重發最新一份
python3 tools/send_briefing.py 2026-05-12    # 重發特定日期
DRY_RUN=1 python3 tools/send_briefing.py latest   # Dry-run（不實際發送）

每個 NYSE 交易日 ET 11:30（夏令 UTC 15:30 / 冬令 UTC 16:30，荷蘭時間恆為 17:30）自動推送盤中決策摘要。週五加 --codex 第二意見。

📊 5/12 盤中 13:00 ET

📰 News & Catalysts
  • ICHR: Q1 beat，Q2 guide $290-310M，GAAP EPS 轉正

📅 Earnings This Week
  • NVDA 5/20 AMC — HBM demand，data-center 指引

📊 Sentiment Pulse (EODHD 7d)
  📈 改善: ONTO 1.00, STRL 0.90, AVGO 0.90
  ⚠️ 注意: MU 急降 0.97→0.51

💰 估值 & Thesis
  📉 最低估: MU vs 公允價 −22%（三錨點中位 $375）
  📈 最高估: ARM vs 公允價 +38%
  📋 今日 thesis: AVBO:q2-guide → partial 公允價 $460→$415（−9.8%）

🔄 Sector Rotation
  💪 leading: 半導體 SMH (+34.9% vs SPY)
  📈 improving: 工業 XLI
  💀 lagging: 能源 XLE

🚨 Alerts
  • ICHR ⚠️ 財報 reaction window，技術訊號暫停

🎯 今日待辦
  • ICHR: 等 reaction settle 後評估加碼至 100 股

📋 明日待辦
  • 確認 5/20 cluster 倉位（QCOM/ON/ANET/NVDA）

⚡ Quick Take
  全面回調但 SMH 仍 leading，sentiment 全面正面。
  本週核心：ICHR reaction + 5/20 四檔財報前倉位確認。

Step 1 — Telegram Bot

1. 開啟 Telegram → 搜尋 @BotFather → /newbot
2. 輸入 bot 名稱和 username，取得 TELEGRAM_BOT_TOKEN
3. 對你的 bot 傳一則訊息，然後在瀏覽器開啟：

   https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
   

4. 從回傳 JSON 找 "chat": {"id": ...} → 取得 TELEGRAM_CHAT_ID

Step 2 — Gmail App Password

1. Google 帳戶 → 安全性 → 兩步驟驗證（先開啟）→ 應用程式密碼
2. 選「其他（自訂名稱）」→ 輸入 fadacai → 產生 16 字元密碼

Step 3 — 設定 .env

cp .env.example .env

編輯 .env，填入以下欄位：

TELEGRAM_BOT_TOKEN=123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TELEGRAM_CHAT_ID=1234567890

SMTP_USER=your-email@gmail.com
SMTP_PASS="xxxx xxxx xxxx xxxx"    # Gmail App Password，務必加引號
EMAIL_FROM=your-email@gmail.com
EMAIL_TO=your-email@gmail.com

⚠️ SMTP_PASS 如果有空格必須加引號，否則 bash 會解析錯誤。

Step 4 — 安裝 Python 依賴

pip3 install -r tools/requirements.txt

Step 5 — 安裝 launchd 排程（macOS）

cp tools/launchd/com.fadacai.briefing.plist ~/Library/LaunchAgents/
# 修改 plist 中的路徑（如果專案目錄不同）
launchctl load ~/Library/LaunchAgents/com.fadacai.briefing.plist
launchctl list | grep fadacai    # 確認已載入（PID 欄顯示 -）

Step 6 — macOS TCC 權限（必做）

launchd 背景程序需要存取 ~/Desktop 裡的腳本：

1. System Settings → Privacy & Security → Full Disk Access
2. 點 + → 按 Shift+Cmd+G → 輸入 /bin → 選 bash → Open
3. 確認開關為 ON

Step 7 — 手動測試

# 立刻觸發（不等 13:00）
launchctl start com.fadacai.briefing

# 觀察 log
tail -f ~/Desktop/fadacai-v2/portfolio/briefing-out/launchd.log

# 確認發送成功
tail -1 briefing-out/send-log.jsonl
# → {"date": "...", "telegram": "ok", "email": "ok"}

launchd (每日 ET 11:30，NYSE 交易日)
    │
    ▼
~/.local/bin/fadacai_briefing_runner.sh   ← TCC-safe wrapper
    ├── check_trading_day.py              ← NYSE 休市日 exit 0
    ├── 週五 → CODEX_FLAG="--codex"
    ├── [non-fatal] fetch_macro.py        ← FRED 總經快取（TTL 36h）
    ├── [non-fatal] earnings_history.py   ← yfinance 盈餘快取（TTL 24h）
    ├── [non-fatal] fetch_fundamentals.py ← EODHD 基本面快取（TTL 24h）；含 A4 自建估值（CAGR→own_fwdEPS→own_target）
    ├── [non-fatal] fetch_news.py         ← EODHD 新聞全文快取（TTL 6h）；P3 訊號擷取的 body 來源
    └── claude -p "/briefing telegram --send $CODEX_FLAG"
            │
            ▼
        .claude/skills/briefing/SKILL.md (telegram tier)
            ├── Step 0.65: 讀 fundamentals cache（三錨點估值輸入）
            ├── T1: Earnings Window（from cache）
            ├── T2: Sentiment Pulse（EODHD sentiment_trend）
            ├── T2.5: 💰 估值 & Thesis Pulse（cache 算，signal-only）
            ├── T3: News & Catalysts
            ├── T4: Sector Rotation
            ├── T5-T7: Alerts / 待辦 / QuickTake
            ├── T8a: 寫 briefing-out/YYYY-MM-DD-full.md
            ├── T8b: 寫 briefing-out/YYYY-MM-DD-telegram.txt
            └── tools/send_briefing.py YYYY-MM-DD
                    ├── POST Telegram Bot API（> 4096 字自動切段）
                    ├── SMTP send email（精簡版 + 完整 markdown）
                    └── 寫 briefing-out/send-log.jsonl

briefing-out/ 已加入 .gitignore（含個人帳戶數據，不 commit）。

MCP Retry Policy： 失敗 → 重試 3 次 → 健康檢查 → fallback WebSearch/WebFetch，輸出中標記 ⚠️ [server] MCP 不可用。

MCP 掛了怎麼辦？ 執行 /mcp-health 診斷，通常重開 Claude Code session 即可。三次重試後自動 fallback WebSearch。

倉位資料從哪來？ mcp__firstrade-server__get_account_position 取即時數據（Step 0b 自動執行）。

交易記錄在哪？ journal/ 目錄，每日一檔（YYYY-MM-DD.md），每次 skill 執行都會建立或更新。

配置計畫在哪？ plan.md — 含板塊目標（%）、策略佇列（⏳/✅/🔄）、觀察清單、策略原則。

第一性原理紀律是什麼？ 每個 Verdict / Recommendation 前強制填寫：核心 thesis（可驗證命題）+ 證偽條件（2-3 個 falsifiable 觀察點）+ 機率分布（EV 計算）。確保結論有 ground truth 依據，不是 narrative。

Telegram 每天幾點收到？ 美東 ET 11:30（NYSE 交易日），對應荷蘭時間夏令 17:30 / 冬令 17:30（自動 DST-aware）。

這套框架的核心不是「叫 LLM 給意見」，而是用多層紀律強迫每個結論落在可驗證的 ground truth 上：

• 第一性原理紀律（Step 0e） — 任何 Verdict 前強制回答三題：① 核心 thesis（1 句可驗證命題，非 narrative）② 證偽條件（2-3 個 falsifiable 觀察點）③ 機率分布 + EV（由 probability-honesty-checker agent 強制計算，禁用 default bell shape 與「略偏正」這類質性語言）。
• 三錨點 Fair PE 估值（Section 8.5 / G3.5） — 不手寫 PE 倍數猜想；用三個獨立錨點做三角定位：A1 市場隱含 PE（EODHD）/ A2 PEG 成長合理倍數 / A3 分析師 PT 隱含 PE。Base = median；Bull = max × 1.25；Bear = min × 0.70。pe_ratio == 0.0 / peg_ratio == 0.0 → 自動丟棄該錨，標 (anchor unavailable)。
• Thesis Ledger（tools/thesis_ledger.py） — 把帶觸發點的 thesis 登錄進帳本，到期（如財報日）自動回頭抓實際數字驗收 passed/failed，累積命中率。詳見 docs/thesis-ledger.md。
• Thesis 驗證 → 股價影響（D2 三桶分解） — thesis verdict 不只是分類；resolve 時帶結構化旗標：fair_value_before/after（三錨點重算）+ price_impact_pct + impact_decomp（thesis 成分 vs 倍數重估成分分解）。實例：AVBO partial → thesis +6%(FY27 AI guide 確認)/multiple −16%(GM 壓縮 re-rate)=net −9.8%。
• 全持倉基本面快取（briefing-out/cache/fundamentals-snapshot.json） — fetch_fundamentals.py 每交易日 launchd 預載，TTL 24h。Quick/Telegram tier 直接讀快取（zero-latency，不等 MCP）；Deep tier 強制刷新。
• A4 自建估值錨（sanity / divergence flag） — fetch_fundamentals.py 同次 API call 計算：own_fwdEPS = 歷史 CAGR (幾何，40% cap → fade 向 8% terminal) × 淨利率 ÷ 股數（完全不看分析師 estimate）。own_target_price = own_fwdEPS × base_FairPE(median A1,A2,A3)。A4vsA3% = (own_target − wall_street_target) / wall_street_target 乾淨隔離「我的盈利觀 vs Street 盈利觀」（倍數固定）。A4 不進 EV，僅做分歧 flag：confidence=unavailable（虧損股 / <3年資料）→ (self-val N/A)；low（營收 stdev>30%）→ ⚠️低信心；ok → 正常顯示。34 單元測試（test_self_valuation.py）覆蓋 CAGR、cap、decel、macro clamp、guardrails。
• 新聞全文快取 + P3 訊號擷取（briefing-out/cache/news-articles.json） — fetch_news.py TTL 6h，top 8 篇/ticker，600-char body excerpt。mcp__eodhd-mcp__get_news 工具提供即時全文（1500 char）。Deep tier §9.5 / stock-analysis Step 4b 從 news body + SEC 8-K + 財報逐字稿抽已量化陳述（wafer starts / capex / ASP 等），強制附 raw_quote（≤120 字逐字引用），signal → thesis 轉換後以 --source signal-inference 登錄 thesis_ledger，閉環追蹤 P3 命中率。反幻覺鎖：無 raw_quote = 無 signal = 不登錄。

• 新增 skill：在 .claude/skills/<name>/SKILL.md 建立，frontmatter 設 user_invocable: true + description，內文遵循 CLAUDE.md 的 Step 0 統一規範。
• 新增資料 agent：純抓資料的子代理用 data-collector（Haiku）；需要紀律推理的用既有 pattern。
• 新增工具：放 tools/，純標準函式庫優先（如 thesis_ledger.py 即零相依），方便他人免裝依賴執行。
• 調整交易風格：feedback/*.md（本機個人檔，已 gitignored）每次 skill 必讀，是把你的偏好餵給框架的地方。

完整規範與設計細節見 CLAUDE.md。

MIT License — 自由使用、修改、商用，保留版權聲明即可。

本專案為投資研究與紀律輔助工具，所有輸出（含 Verdict、EV、機率、選擇權建議）僅供研究與教育參考，不構成投資建議、要約或保證。美股與選擇權交易具高度風險，可能導致本金全部損失。你需自行評估並承擔一切交易決策與後果，並自備所有 API key 與券商憑證；作者與貢獻者不對任何使用本專案所致之損失負責。