Clawdfolio
面向专业投资者的量化投资组合工具包。多券商聚合（长桥、富途/牛牛、模拟）、机构级风控分析、期权策略全生命周期管理，以及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、夏普比率、索提诺比率、VaR、CVaR、回撤
clawdfolio risk --detailed # + RSI 极值、集中度、行业敞口、投资组合 RSI
计算的风险指标：
- 波动率：20日、60日、年化
- Beta：相对于 SPY、相对于 QQQ
- 夏普比率：年化，超额收益 / 总波动率
- 索提诺比率：年化，超额收益 / 仅下行波动率
- 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 个模拟持仓） - 初始化工作区：
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 | 长桥 + 富途/牛牛合并快照 |
工作区：~/.clawdfolio/finance（可通过 --workspace 配置）。
安装
pip install clawdfolio # 核心（yfinance + 模拟券商）
pip install clawdfolio[longport] # + 长桥券商
pip install clawdfolio[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 格式。
支持的券商：长桥（环境变量）、富途/牛牛（本地 OpenD）、模拟（内置）、聚合（多券商合并）。
完整配置参考、环境变量、券商设置及监控详情请参见 CONFIG.md。