Metadata-Version: 2.4
Name: sellput
Version: 0.1.0
Summary: Commodity futures options strategy analyzer powered by AkShare
Requires-Python: >=3.10
Requires-Dist: akshare>=1.12.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: requests>=2.31.0
Description-Content-Type: text/markdown

# 商品期货期权策略分析工具

这是一个基于 AkShare 的商品期货期权策略分析工具。当前版本会根据期货合约的 `MA10`、`MA20`、`MA60` 自动识别市场状态，并输出对应的期权策略推荐。

当前项目已经打包为标准 Python 包，CLI 入口为 [src/sellput/cli.py](/Users/max/Documents/GitHub/sellput/src/sellput/cli.py)，安装后可直接使用 `qh` 命令。

## 当前规则

系统目前实现了 4 条规则：

### 规则一：强势空头排列

条件：

- `当前价格 > MA10 > MA20 > MA60`

判断：

- 预期回调至 `MA10` 或 `MA20`

输出策略：

- `熊市看跌价差推荐 - 目标MA10`
- `熊市看跌价差推荐 - 目标MA20`
- `裸买看跌期权推荐`
- `裸卖空期权推荐`

### 规则二：强势多头排列

条件：

- `MA60 > 当前价格`
- `MA60 > MA10`
- `MA60 > MA20`

判断：

- 预期反弹至 `MA60`

输出策略：

- `牛市看涨价差推荐 - 目标MA60`
- `裸买涨期权推荐`

### 规则三：震荡或趋势不明

条件：

- 不满足规则一、规则二、规则四

判断：

- 市场震荡或趋势不明朗

输出：

- 不生成任何策略表
- 只输出观望提示

### 规则四：均线压制回落

条件：

- `MA60 < 当前价格`
- `MA60 < MA10`
- `MA60 < MA20`
- `MA10 > 当前价格`
- `MA20 > 当前价格`

判断：

- 预期回落至 `MA60`

输出策略：

- `熊市看跌价差推荐 - 目标MA60`
- `裸买看跌期权推荐`
- `裸卖空期权推荐`

## 候选池与流动性规则

脚本不会直接对全市场所有期权做组合，而是先构建当前合约月份的候选池：

- 只保留与期货代码同月份的期权
- 只保留价格有效的合约
- 优先使用 `成交量 > 100` 做流动性过滤
- 默认按流动性降序取前 `10` 个期权进入策略计算

当前的流动性回退逻辑如下：

1. 优先使用最近请求交易日的交易所期权日频数据，并按 `成交量` 过滤。
2. 如果当日日频数据存在，但过滤后候选池为空，则回退到最近可用交易日重试。
3. 如果最近可用日频仍没有足够候选，则降级为 `持仓量代理` 模式。
4. 如果走新浪商品期权备用链路，则默认使用 `持仓量代理`，因为该接口不提供成交量。

程序会在输出抬头中显示本次使用的：

- `期权数据日期`
- `流动性口径`
- `权利金口径`
- `保证金口径`

## 策略说明

### 熊市看跌价差

构建方式：

- 买入高行权价 put
- 卖出低行权价 put
- 同一标的、同一到期月份

适用：

- 预期价格下跌，但希望控制最大亏损

### 裸买看跌期权

构建方式：

- 直接买入 1 张 put

适用：

- 预期价格向下运行，希望保留更直接的下跌弹性

风险：

- 风险有限，但时间价值衰减会侵蚀收益

### 裸卖空期权

构建方式：

- 卖出 1 张 put

适用：

- 当前实现中会在看跌规则下作为附加参考一起输出
- 该策略对保证金和尾部风险更敏感

风险：

- 卖方风险较大，必须结合保证金和回撤承受能力看待

### 牛市看涨价差

构建方式：

- 买入低行权价 call
- 卖出高行权价 call

适用：

- 预期价格向上反弹，但希望把成本控制在有限范围内

### 裸买涨期权

构建方式：

- 直接买入 1 张 call

适用：

- 预期价格上涨，希望获得更高的上行弹性

风险：

- 风险有限，但同样受时间价值衰减影响

## 输出说明

程序的通用输出抬头包括：

- `期货当前价`
- `交易日`
- `期权数据日期`
- `流动性口径`
- `权利金口径`
- `保证金口径`
- `均线状态`
- `市场判断`
- `默认风险偏好`
- `MA10 / MA20 / MA60`

不同策略表中的主要字段包括：

- `组合`：价差策略的买卖执行价组合
- `净支出(元/吨)`：价差建仓成本
- `平衡点(元/吨)`：达到盈亏平衡所需的标的价格
- `预期盈亏(元/手)` 或 `预期收益(元/手)`：目标价格下的策略结果
- `最大盈利(元/手)` / `最大亏损(元/手)`：理论边界
- `权利金成本(元/手)`：优先使用 AkShare `option_margin()` 的 `买方权利金`，缺失时回退到行情价
- `权利金收入(元/手)`：优先使用 AkShare `option_margin()` 的 `结算价 × 合约乘数`，缺失时回退到行情价
- `保证金(元/手)`：卖方策略从 AkShare `option_margin()` 匹配到的卖方保证金；若不可用则跳过卖方推荐
- `流动性`：当前分析口径下的流动性值
- `技术位止损`：基于期货标的价格和 `14 日 ATR` 计算的技术止损位
- `资金止损`：基于建仓成本或权利金收入计算的资金止损阈值
- `移动止盈`：当标的价格达到现价与目标价中点后的止损上移规则
- `推荐理由`
- `风险提示`

默认每类策略只展示前 `3` 条结果。

### 权利金与保证金口径说明

- 当前商品期权的权利金和保证金统一优先使用 AkShare `option_margin()` 接口
- `流动性` 仍来自期权行情链路：交易所日频优先成交量，新浪实时/准实时链路使用持仓量代理
- 如果 `option_margin()` 整体不可用，价差和买方单腿策略会显式回退到行情价
- 如果 `option_margin()` 只覆盖部分候选合约，程序会输出风险提示，说明部分权利金已回退到行情价
- 当前没有启用 `option_contract_info_ctp()` 作为商品期权保证金主源，因为该接口实测 `做多保证金/手 / 做空保证金/手` 为 `0`

### ATR14 止损说明

- 程序会复用 `get_futures_daily_bars()` 的期货日线数据计算最新 `14 日 ATR`
- 需要日线同时包含 `high / low / close`
- 如果 OHLC 数据不足或缺列，策略仍会输出，但 `技术位止损`、`资金止损`、`移动止盈` 三列统一显示 `ATR不足，无法计算`
- 规则一中的裸买 put / 裸卖 put 只有一张汇总表，因此默认以首目标 `MA10` 作为移动止盈参考

## 使用方法

### 开发环境

安装开发依赖：

```bash
uv sync
```

在开发环境中运行 CLI：

```bash
uv run qh ma2605
```

### 作为工具安装

发布到 PyPI 后，用户可以直接安装：

```bash
uv tool install sellput
```

安装后直接运行：

```bash
qh ma2605
```

示例代码：

- `MA2605`
- `SC2605`
- `JD2605`

### 本地构建与烟测

构建发布包：

```bash
uv build --no-sources
```

用构建后的 wheel 做本地烟测：

```bash
uv tool run --from dist/sellput-0.1.0-py3-none-any.whl qh ma2605
```

### 手动发布

确认 PyPI 凭证已配置后发布：

```bash
uv publish
```

## 支持的交易所与品种前缀

当前脚本通过 `PRODUCT_META` 维护支持列表，已覆盖多家交易所的商品期权。

### 郑商所

- `MA`
- `TA`
- `SR`
- `CF`
- `RM`
- `ZC`
- `OI`
- `PK`
- `PX`
- `SH`
- `SA`
- `PF`
- `SM`
- `SF`
- `UR`
- `AP`
- `CJ`
- `FG`
- `PR`

### 大商所

- `C`
- `M`
- `I`
- `PG`
- `L`
- `V`
- `PP`
- `P`
- `A`
- `B`
- `Y`
- `EG`
- `EB`
- `JD`
- `CS`
- `LH`

### 上期所

- `SC`
- `CU`
- `AL`
- `ZN`
- `PB`
- `RB`
- `NI`
- `SN`
- `AO`
- `AU`
- `AG`
- `BR`
- `RU`

### 广期所

- `LG`
- `SI`
- `LC`

说明：

- 如果某个期货品种存在，但 AkShare 当前没有可用的期权日频或保证金接口映射，脚本仍可能提示“不支持”或跳过部分策略。

## 数据源说明

主要数据源：

- AkShare 期货日线
- AkShare 交易所商品期权日频
- AkShare 期权保证金接口

备用数据源：

- 新浪商品期权 T 型报价

注意：

- 新浪备用链路通常没有成交量，只能用持仓量做代理流动性
- 卖方策略必须依赖 AkShare 保证金接口；若保证金不可用，程序会跳过卖方推荐

## 注意事项

- 需要网络连接
- 结果依赖公开数据接口的可用性和时效性
- 当前版本只需要输入期货代码，不再手动输入方向和风险偏好
- 默认风险偏好固定为 `稳健`
- 所有结果仅供研究和参考，不构成交易建议
