sellput 0.1.1

Commodity futures options strategy analyzer powered by AkShare

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

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

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

当前项目已经打包为标准 Python 包，CLI 入口为 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 作为移动止盈参考

使用方法

开发环境

安装开发依赖：

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：

uv run qh ma2605

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

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

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

uv run qh --analysis-mode realtime --debug-source ma2605

作为工具安装

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

uv tool install sellput

安装后直接运行：

qh ma2605

示例代码：

• MA2605
• SC2605
• JD2605

本地构建与烟测

构建发布包：

uv build --no-sources

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

uv tool run --from dist/sellput-*.whl qh ZZ2605

GitHub Actions 自动发布

仓库内置了 tag 驱动的自动发布工作流 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: 留空

日常发版命令：

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，最短触发命令就是：

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

手动兜底发布

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

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

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

先发 TestPyPI：

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

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

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。

郑商所

• 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 保证金接口；若保证金不可用，程序会跳过卖方推荐

注意事项

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