Metadata-Version: 2.4
Name: sellput
Version: 0.1.1
Summary: Commodity futures options strategy analyzer powered by AkShare
Requires-Python: >=3.11
Requires-Dist: akshare>=1.18.40
Requires-Dist: numpy>=2.4.3
Requires-Dist: pandas>=3.0.1
Requires-Dist: requests>=2.32.5
Description-Content-Type: text/markdown

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

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

当前版本对核心运行所需数据已基本覆盖，但未达到完整覆盖。`supported` 表示该品种已纳入当前 AkShare 可运行集，`unsupported` 表示交易所已上市但当前仅做建档审计，详细清单见 [docs/product_capability_matrix.json](/Users/max/Documents/GitHub/sellput/docs/product_capability_matrix.json)。

当前项目已经打包为标准 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` 个期权进入策略计算

当前的数据源治理按 `analysis_mode` 分场景处理：

- `auto`：如果是最新交易日且处于广义商品交易时段，则按 `realtime` 处理；其他时间按 `post_close` 处理
- `realtime`：`当日交易所日频 -> AkShare 新浪封装 -> raw 新浪 -> 上一交易日交易所日频 -> 空结果`
- `post_close` / `research`：`当日交易所日频 -> 上一交易日交易所日频 -> 空结果`

当前的流动性降级逻辑如下：

1. 先在已选中的期权链路内按 `成交量 > 100` 过滤。
2. 如果同一链路候选池为空，再降级为 `持仓量代理`。
3. 新浪实时链路天然没有真实 `成交量`，因此默认直接走 `持仓量代理`。
4. `持仓量` 只作为代理字段参与流动性筛选，不会再回写伪装成真实 `成交量`。

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

- `期权数据日期`
- `期货价格源`
- `期权链源`
- `price_mode`
- `option_mode`
- `fallback_level`
- `data_quality_label`
- `流动性口径`
- `权利金口径`
- `保证金口径`
- `来源告警`

## 策略说明

### 熊市看跌价差

构建方式：

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

适用：

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

### 裸买看跌期权

构建方式：

- 直接买入 1 张 put

适用：

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

风险：

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

### 裸卖空期权

构建方式：

- 卖出 1 张 put

适用：

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

风险：

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

### 牛市看涨价差

构建方式：

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

适用：

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

### 裸买涨期权

构建方式：

- 直接买入 1 张 call

适用：

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

风险：

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

## 输出说明

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

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

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

- `组合`：价差策略的买卖执行价组合
- `净支出(元/吨)`：价差建仓成本
- `平衡点(元/吨)`：达到盈亏平衡所需的标的价格
- `预期盈亏(元/手)` 或 `预期收益(元/手)`：目标价格下的策略结果
- `最大盈利(元/手)` / `最大亏损(元/手)`：理论边界
- `权利金成本(元/手)`：优先使用同日期权链价格口径；只有当 AkShare `option_margin()` 的 `更新时间` 与期权链日期一致时，才允许覆盖为 `买方权利金`
- `权利金收入(元/手)`：优先使用同日期权链价格口径；只有当 AkShare `option_margin()` 与期权链同日时，才允许覆盖为结算参考值
- `保证金(元/手)`：仅在 AkShare `option_margin()` 与期权链同日时使用；否则卖方策略直接跳过
- `流动性`：当前分析口径下的流动性值
- `data_quality_label`：当前候选记录的质量标签，仅在 `--debug-source` 下显示
- `source_trace`：当前候选记录的数据来源轨迹，仅在 `--debug-source` 下显示
- `技术位止损`：基于期货标的价格和 `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
```

当前项目要求 `Python >= 3.11`。

当前项目依赖 `AkShare >= 1.18.40`。

当前代码已验证面向 `NumPy >= 2.4.3`、`pandas >= 3.0.1`、`requests >= 2.32.5` 和 `AkShare >= 1.18.40`。

在开发环境中运行 CLI：

```bash
uv run qh ma2605
```

如果需要显式控制数据场景：

```bash
uv run qh --analysis-mode realtime ma2605
uv run qh --analysis-mode post_close ma2605
```

如果需要排查数据来源轨迹，可额外打开调试列：

```bash
uv run qh --analysis-mode realtime --debug-source 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-*.whl qh ZZ2605
```

### GitHub Actions 自动发布

仓库内置了 tag 驱动的自动发布工作流 [release.yml](/Users/max/Documents/GitHub/sellput/.github/workflows/release.yml)：

- 推送 `vX.Y.Z` tag 后，GitHub Actions 会自动执行版本校验、单测、构建、先发 `TestPyPI`、再发正式 `PyPI`
- 工作流要求 `pyproject.toml` 中的 `project.version` 与 tag 完全一致
- 发布使用 Trusted Publishing，不需要在 GitHub Secrets 中保存长期 PyPI token

首次启用前，需要分别在 `TestPyPI` 和 `PyPI` 后台配置 trusted publisher；如果项目还不存在，就用 pending publisher 预注册：

- Owner: `maxlee`
- Repository name: `sellput`
- Workflow name: `release.yml`
- Environment name: 留空

日常发版命令：

```bash
uv run python -m unittest test_sellput -v
git add pyproject.toml README.md .github/workflows/release.yml
git commit -m "Release vX.Y.Z"
git tag vX.Y.Z
git push origin main vX.Y.Z
```

如果版本变更已经合并到 `main`，最短触发命令就是：

```bash
git tag vX.Y.Z && git push origin vX.Y.Z
```

### 手动兜底发布

只有在 GitHub Actions 不可用或 Trusted Publishing 尚未配置好时，才建议本地手工发布。

每次本地发布前都先重建分发包，避免 `dist/` 里残留旧版本文件：

```bash
rm -f dist/sellput-*.tar.gz dist/sellput-*.whl
uv build --no-sources
```

先发 `TestPyPI`：

```bash
export UV_PUBLISH_TOKEN="<testpypi-token>"
uv publish \
  --publish-url https://test.pypi.org/legacy/ \
  --check-url https://test.pypi.org/simple/ \
  dist/*
```

确认没问题后再发正式 `PyPI`：

```bash
export UV_PUBLISH_TOKEN="<pypi-token>"
uv publish \
  --publish-url https://upload.pypi.org/legacy/ \
  --check-url https://pypi.org/simple/ \
  dist/*
```

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

当前脚本通过 `PRODUCT_META` 维护可运行支持列表，通过 `UNSUPPORTED_EXCHANGE_PRODUCTS` 维护“交易所已上市但未纳入当前 AkShare 可运行集”的审计列表。机器可校验版本见 [docs/product_capability_matrix.json](/Users/max/Documents/GitHub/sellput/docs/product_capability_matrix.json)。

### 郑商所

- `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`
- `NR`

### 广期所

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

### 当前 AkShare 可运行集新增补齐

- `NR`
- `PS`

### 已上市但当前未纳入可运行集的审计项

- `JM`
- `PL`
- `AD`
- `FU`
- `BU`
- `SP`
- `OP`

说明：

- 当前支持列表面向“可运行”而不是“交易所全量上市”。
- 如果某个期货品种交易所已上市，但 AkShare 当前没有可用的期权日频或保证金接口映射，脚本会显式提示未纳入可运行集，而不是静默缺失。

## 数据源说明

主要数据源：

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

备用数据源：

- 新浪商品期权 T 型报价

注意：

- 新浪备用链路通常没有成交量，只能用持仓量做代理流动性
- `AKSHARE_PROVIDER_ALIASES` 用于维护保证金别名、Sina 特殊 symbol 和 provider 命名兼容补丁，这些 provider 补丁已从 `PRODUCT_META` 中拆出
- 卖方策略必须依赖 AkShare 保证金接口；若保证金不可用，程序会跳过卖方推荐

## 注意事项

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