Portfolio — Claude Code 投資研究與組合管理框架

一套建構在 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(["👤 UserL2 Margin Broker"])

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

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

    subgraph Skills ["⚡ Skills — Slash Commands"]
        direction LR
        B["/briefingquick · 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["0aplan.mdfeedback/*.md"] --> s0b["0bget_account_positionlive broker"] --> s0c["0c/0djournal gap-fill今日快照"] --> s0e["0e第一性原理紀律thesis · 證偽 · EV"]
    end

    subgraph Models ["🤖 AI Model 分流（Cost Optimization）"]
        SONNET["🔵 Sonnet 4.6data-collector subagentmcp-health · trade-journal log日常分析合成 · briefing quick+telegramtodo · journal review · 純機械"]
        OPUS["🟠 Opus 4.8旗艦推理portfolio-review · ev-checkbriefing full/deep · stock-analysisoptions-strategy · 機率/EV"]
    end

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

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

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

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

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

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

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

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

    OUT["📊 繁體中文報告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  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               # 跑第一份日報

MCP servers 設定（核心）

本框架的數據來自 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 [email protected]" -- 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。

環境變數（.env）

以上全部選用——不設也能用所有互動式 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           ← 月度損益摘要

手動重發 Briefing

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（不實際發送）

---

Telegram 自動推送

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

Telegram 訊息格式

📊 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/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

[email protected]
SMTP_PASS="xxxx xxxx xxxx xxxx"    # Gmail App Password，務必加引號
[email protected]
[email protected]

⚠️ 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 Servers

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（虧損股 / 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 = 不登錄。
• 發現層先行指標（tools/fetch_leading.py） — 財報 gate 是裁決層（慢而準），發現層另設五組比財報更早的硬數字前哨：三儀表（HY OAS 速度 / VIX 期限結構 / 半導體寬度）+ 行業 PE 溫度計與國債曲線、財報季 cross-read 排序（早報者 → 晚報持倉的讀序 prior）、記憶體/功率報價新聞監測、revision 二階導雙法（archive-diff × vendor 7d 曲線互驗）、台股功率元件月營收（TWSE/TPEx 免金鑰）。全部 display-only（記錄不阻擋），命中率由 /trade-review 驗證後才可升閘門。詳見 docs/leading-indicators.md。
• 交易檢討自我進化引擎（/trade-review + tools/trade_ledger.py） — 每兩週歸因每筆成交是「系統決策」還是「脫離 plan 的自主決策」，計算三並列指標：交易 α（對實際使用的基準回歸，半導體對 SMH）、持有 α（沒有它，純交易指標會獎勵頻繁進出）、up/down beta capture（漲不上跌得凶的量化）。旗標紀律：欠決定的部位必須 flag 登記附 deadline，延後計次、第 3 次強制執行 — 修的是「警示只活在散文裡而永不執行」這個實測最貴的漏口。規則命中率帳本（feedback/RULES-LEDGER.md）讓每條 feedback 規則用實測存廢，不由模型換代裁決。
• 自動價格警報（tools/price_alerts.py） — 券商 lib 無警報 endpoint，自建：launchd 15 分鐘盤中輪詢 yfinance，跌破/突破/N 日新高三型條件 → Telegram（複用日報同一 bot），once_per_day 防洗版；警報定義與觸發狀態存 research/price-alerts.json。

如何擴展

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

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

授權

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

免責聲明

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