用途：从 Interactive Brokers 获取交易成交（executions）并按账户、日期范围、标的筛选，输出 JSON 结果，含逐笔成交与按标的汇总（买入、卖出、佣金、已实现盈亏）。
数据来源与限制：无 Flex 参数时走实时 API（reqExecutionsAsync），仅返回当前 TWS 会话；文档指出尽管 API 文档暗示约 7 天，实际超过当日即为 0 条，ExecutionFilter.time 无法扩大范围，需用 FlexReport。FlexReport 需在 IBKR 账户管理中配置 Flex Web Service token 和 Trade 查询，日期范围由查询配置决定；Web 服务限流较强，大范围回溯更适合用 --file 手动导出 XML。
连接要求：本地需运行 TWS 或 IB Gateway 并启用 API。模拟盘端口 7497，实盘 7496；IB_PORT 环境变量为默认端口（如容器 4001），优先级为 --port > IB_PORT > 内置默认。端口失败会自动重试另一端口并记忆可用账户类型；两者均失败需用户确认 TWS/Gateway 已启用 API。
主要参数：--port、--account、--all-accounts、--symbol、--start-date、--end-date、--flex-token、--flex-query-id（可重复）、--file（可重复，无需 TWS/Gateway）、--group-spreads（仅 FlexReport 来源）。默认取首个管理账户，一般应用 --all-accounts。
用法示例：uv run python .claude/skills/ib-trades-history/scripts/trades.py --all-accounts；加 --symbol AAPL 过滤；加 --flex-token 与 --flex-query-id 取完整历史；多查询可跨 365 天限制，如 --flex-query-id QID_2025 --flex-query-id QID_2026；用 --file trades_2024.xml 读取本地文件。
价差分组：--group-spreads 把原始成交合并为腿并配对为垂直价差，依赖 openCloseIndicator（仅 FlexReport 提供），实时 API 路径返回 supported=false。腿按（账户、标的、到期、方向）聚合；非明确两档垂直（展期、比例价差、单腿、未平仓等）留在 ungrouped_legs 并给出警告。输出含 legs、spreads（类型、行权价、宽度、手数、信用、最大风险、盈亏、capture_pct、return_on_risk_pct 等）及 reconciled 校验。max_risk 按定义风险垂直计算，铁鹰两侧分别计风险会高估。依赖 ib-async。若 uv 未安装或找不到 pyproject.toml，将命令中的 uv run python 替换为 python。