Clawdfolio

專業投資者的量化投資組合工具包。支援多券商聚合（Longport、Moomoo/Futu、Demo）、機構級風險分析、選擇權策略生命週期管理，以及 20 種以上的自動化金融工作流程與 CSV/JSON 資料匯出。

PyPI：pip install clawdfolio · 儲存庫：https://github.com/YichengYang-Ethan/clawdfolio · 需要 Python >= 3.10（已測試 3.10–3.13）

完整的 Python API 參考文件請見 API.md，設定、環境變數、券商配置與監控詳細資訊請見 CONFIG.md。

CLI 指令

所有指令皆支援 --broker {longport,futu,demo,all}、--output {console,json} 以及 --config PATH。

投資組合

clawdfolio summary              # 投資組合總覽（預設命令）
clawdfolio summary --top 20     # 顯示前 20 大持股
clawdfolio quotes AAPL MSFT     # 即時報價
clawdfolio alerts               # 價格／RSI／損益／集中度警報
clawdfolio alerts --severity critical

風險分析

clawdfolio risk                 # 波動率、Beta、Sharpe、Sortino、VaR、CVaR、最大回撤
clawdfolio risk --detailed      # 加上 RSI 極端值、集中度、產業曝險、投資組合 RSI

計算的風險指標：

波動率：20 天、60 天、年化
Beta：相對於 SPY 與 QQQ
Sharpe 比率：年化，超額報酬／總波動率
Sortino 比率：年化，超額報酬／僅下方波動率
VaR：95% 與 99%（歷史模擬），絕對值與百分比
CVaR／預期短缺：95% 與 99% —— 超越 VaR 的尾部風險
最大回撤：歷史與目前
HHI：賀芬達爾-赫希曼集中度指數
RSI：投資組合層級 14 日 RSI
相關性：高相關性配對偵測（>= 0.8）

收益

clawdfolio earnings             # 即將到來的收益（預設 14 天）
clawdfolio earnings --days 30   # 向前看 30 天

DCA（定期定額）

clawdfolio dca                  # 投資組合的 DCA 訊號（再平衡＋下跌偵測）
clawdfolio dca AAPL --months 12 --amount 1000   # 歷史 DCA 回測

訊號類型：REGULAR（定期）、DIP（從近期高點下跌）、REBALANCE（權重偏離目標）。

匯出

clawdfolio export portfolio                  # CSV 輸出至標準輸出
clawdfolio export portfolio --format json    # JSON 輸出至標準輸出
clawdfolio export risk --file risk.csv       # 風險指標匯出至檔案
clawdfolio export alerts --format json --file alerts.json

匯出目標：portfolio、risk、alerts。格式：csv、json。

選擇權

clawdfolio options expiries TQQQ
clawdfolio options chain TQQQ --expiry 2026-03-21 --side calls --limit 10
clawdfolio options quote TQQQ --expiry 2026-03-21 --strike 80 --type C
clawdfolio options buyback          # 檢查設定檔中的買回觸發條件
clawdfolio options buyback --strict # 若未觸發任何目標則回傳結束碼 1

金融工作流程

7 個類別共 20 個內建工作流程。建議的驗證設定順序：

驗證券商連線：clawdfolio summary --broker demo（應顯示 10 個 Demo 持倉）
初始化工作目錄：clawdfolio finance init 然後用 ls ~/.clawdfolio/finance 確認
列出可用工作流程：clawdfolio finance list
執行工作流程：clawdfolio finance run portfolio_daily_brief_tg
檢查輸出：加上 --output json 可取得機器可讀結果；若發生錯誤，可改用 --broker demo 來隔離券商問題

clawdfolio finance list --category alerts_monitors  # 依類別篩選
clawdfolio finance run dca_proposal_tg -- --budget 5000  # 傳遞額外參數

類別：portfolio_reports、briefing_cards、alerts_monitors、market_intel、broker_snapshots、strategy、security。

主要工作流程：

ID	說明
`portfolio_report`	每日投資組合報告，包含績效、風險與持股
`portfolio_daily_brief_tg`	Telegram 友善的每日簡報卡片
`portfolio_alert_monitor`	去重複的 RSI／損益／集中度／波動警報
`option_buyback_monitor`	具狀態的選擇權買回觸發監控
`earnings_calendar`	當前持股的即將到來收益
`dca_proposal_tg`	預算限制的 DCA 提案卡片
`account_report`	合併 Longport 與 moomoo 的快照

工作目錄：~/.clawdfolio/finance（可用 --workspace 設定）

安裝

pip install clawdfolio               # 核心功能（yfinance + demo 券商）
pip install clawdfolio[longport]     # 加上 Longport 券商
pip install clawdfolio[futu]         # 加上 Moomoo/Futu 券商
pip install clawdfolio[all]          # 所有券商
pip install clawdfolio[dev]          # 加上 pytest、mypy、ruff（開發用）

Python API

用於程式化使用的關鍵匯入：

from clawdfolio import Symbol, Position, Quote, Portfolio, RiskMetrics, Alert
from clawdfolio.brokers import get_broker
from clawdfolio.analysis.risk import analyze_risk
from clawdfolio.analysis.technical import calculate_rsi, calculate_macd
from clawdfolio.market import get_price, get_history, is_market_open
from clawdfolio.strategies.dca import DCAStrategy, calculate_dca_performance
from clawdfolio.output import export_portfolio_csv, export_risk_json

完整的 API 參考與使用範例請見 API.md。

設定

搜尋順序：--config 旗標 > CLAWDFOLIO_CONFIG 環境變數 > ./config.yaml > ~/.config/clawdfolio/config.yaml。支援 YAML 與 JSON。

支援的券商：Longport（環境變數）、Moomoo/Futu（本地 OpenD）、Demo（內建）、Aggregator（多券商合併）。

完整的設定參考、環境變數、券商設定與監控詳細資訊請見 CONFIG.md。

Clawdfolio 量化投資組合工具包