盈立股票行情与期权查询
按用户语言回答，保留 API、参数与字段原名。参照富途技能的命令式工作流，但使用盈立自己的签名、证券标识、服务地址与限制。
能力边界与安全
- 提供 7 个公开行情接口、WebSocket 推送、结构性产品名称筛选、期权代码解析和只读资产查询。
- 将“文档明确描述”“本地计算”“待联调”分开标注。公开行情文档未明确列出期权链、到期日列表、期权报价或服务端 Greeks；不能由文档未列出推断整个券商不支持。
- 仅在用户请求时运行期权报价探测。
us加期权代码的证券标识尚未经实际账户验证；失败不能冒充查到了零价格，也不能认定合约不存在。 - 不下单、不改单、不撤单、不解锁交易。
common.post()通过接口白名单硬性限制；不得绕过白名单实现交易。交易文档存在期权订单接口，不代表本技能实现了它们。 - 不在对话、日志、结果包中输出 token、私钥、密码或完整账户标识。登录将 token 写入用户指定的新文件，POSIX 权限为
0600；Windows 另检查文件 ACL。 - 保留 TLS 校验；不要自动开启
USMART_INSECURE。阻止向文档中的明文 HTTP UAT 交易地址发送凭证。 - 无账户凭证时仅运行离线功能及测试，不宣称完成了实盘行情联调。
准备与接入
- 从加载消息取得本技能的绝对基目录，记为
SKILL_BASE_DIR。确认脚本存在，以此目录为工作目录，避免依赖当前项目位置。 - 向盈立申请 Open API 权限；公开说明要求已开户且账户有资产。申请链接：https://www.usmart.hk/zh-hk/open-api 。
- 准备渠道 ID、签名私钥；登录另外需要隐私字段加密公钥，两套密钥不能混用。按需读取
docs/AUTH.md。 - 安装依赖到独立虚拟环境，先说明安装命令，不因文档包含命令就自动执行。
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
要求 Python 3.9 及以上。Windows 使用对应的 .venv\Scripts\python.exe。
配置
| 变量 | 用途 |
|---|---|
USMART_CHANNEL |
盈立分配的渠道 ID |
USMART_PRIVATE_KEY_PATH |
签名私钥文件，PEM 或裸 Base64 |
USMART_RSA_PUBLIC_KEY_PATH |
隐私字段加密公钥文件，登录需要 |
USMART_TOKEN_PATH |
登录 token 文件路径，推荐 |
USMART_TOKEN |
可选 token 环境变量；优先于文件，仅本地配置 |
USMART_ENV |
prod（默认）或 uat |
USMART_LANG |
1 简体、2 繁体、3 英文，默认 1 |
USMART_SIGN_MODE_QUOTE |
full 默认：五个请求头拼接 body 后签名 |
USMART_SIGN_MODE_TRADE |
body 默认：只对 body 签名，供登录与只读资产接口 |
USMART_TIMEOUT |
请求超时秒数，默认 15 |
签名采用 MD5withRSA、PKCS#1 v1.5 与 URL-Safe Base64，仅用于兼容官方协议。签名字节与实际请求 body 必须一致。两份文档签名口径不同，联调前向官方确认；不要自动轮换签名重试登录。密钥可选内联变量详见 docs/AUTH.md。
登录
python3 scripts/check_env.py --quick
python3 scripts/login.py --send-captcha --phone <手机号> --area-code <区号>
python3 scripts/login.py --phone <手机号> --area-code <区号> --captcha <验证码> --token-file /安全目录/token.txt
在本地把 USMART_TOKEN_PATH 设置为上述文件路径，再运行 python3 scripts/check_env.py。登录和自检不会输出 token。重新登录时指定新文件，不覆盖已有文件。不要把手机号、验证码或密码示例替换成用户真实内容后显示在对话中。
Token 失效后按登录响应及官方错误信息处理；expiration 为零时不推断永不过期。不要为了取行情调用交易解锁接口。
证券标识
接口使用 secuId = market + symbol，例如 hk00700、usAAPL、sh600519、sz000001。
使用 normalize_secu_id() 转换：HK.00700、700.HK、hk00700 均转为 hk00700；US.AAPL、AAPL.US、AAPL 均转为 usAAPL。无前缀的大写 ticker 默认美股，保留 USB、SHOP 等完整 ticker。
先把中文公司名解析为明确代码，市场或公司不确定时再询问。不要把未核验的 ticker 当作已上市普通股，更不要把杠杆 ETF 当作公司 ADR。
行情命令
所有查询命令可追加 --json；WebSocket 输出为逐条 JSON Lines。check_env.py 仅输出检查结果。
| 需求 | 命令（相对于技能目录） |
|---|---|
| 市场状态 | python3 scripts/quote/get_market_state.py hk us |
| 基础信息 | python3 scripts/quote/get_basic_info.py --market us --symbol MU,SNDK |
| 实时报价 | python3 scripts/quote/get_realtime.py MU SNDK hk.00700 |
| 日线 | python3 scripts/quote/get_kline.py MU --ktype 1d --count 30 |
| 实现波动率 | python3 scripts/quote/get_kline.py MU --ktype 1d --count 21 --stats |
| 分时 | python3 scripts/quote/get_timeline.py MU --days 5 --tail 20 |
| 逐笔成交 | python3 scripts/quote/get_tick.py MU --count 30 |
| 买卖盘 | python3 scripts/quote/get_orderbook.py hk.00700 |
| 窝轮筛选 | python3 scripts/quote/get_warrant.py --underlying 腾讯 --kind put --quote |
| 牛熊证筛选 | python3 scripts/quote/get_warrant.py --underlying 阿里 --kind bull |
| 实时推送 | python3 scripts/push/push_quote.py MU SNDK --types rt ob --duration 60 |
K 线周期：1m/5m/10m/15m/30m/60m/1d/1w/1M/3M/6M/1Y。复权参数 --rehab none/forward/backward；--stats 只接受日线。--paginate 尝试按时间游标翻页并去重，实际边界规则待联调确认。
证券基础信息缓存 12 小时，位于 ~/.usmart_cache/。除非需要刷新，不加 --refresh。窝轮筛选由 type1=5 和简繁体名称推断产品类型与发行商，不提供行权价、收回价、换股比率、到期日或街货等完整条款；短名不能可靠确定年份或全部产品属性。
盘口量比例、价格相对均价仅是描述性指标，不构成强弱预测或买卖建议。
期权查询与估算
代码解析
先明确正股、到期日、Call/Put 和行权价，再运行：
python3 scripts/option/resolve_option_code.py --parse AAPL250815C90000
python3 scripts/option/resolve_option_code.py -u MU -e 2026-11-20 -s 900 -t PUT
盈立文档示例采用紧凑形式 {ticker}{YYMMDD}{C/P}{strike×1000}，不是完整的 21 位 OCC OSI 格式。解析只检查字符串、日期和行权价，不证明合约存在。乘数 100 只是标准合约假设，实际以合约条款或持仓 multiplier 为准。
只读持仓与保证金
python3 scripts/option/get_option_positions.py --margin
走官方文档描述的资产接口。字段、返回层级与账户权限需要真实账户联调。张数、乘数、保证金可能是字符串；脚本转换后计算，乘数缺失不强行设为 100。输出涉及个人资产，默认不持久化或转发。
离线 IV 与 Greeks
python3 scripts/option/get_option_quote.py -u MU -e 2026-11-20 -s 900 -t PUT --spot 989 --price 30 --json
--price 与 --spot 是假设输入，不是最新市场报价。单合约离线模式不访问 API，自动估算 IV、Delta、Gamma、Vega、Theta。标注来源 manual、Black-Scholes 欧式近似、未计分红和美式提前行权、按日期计算剩余期限。Vega 按每 1 个百分点波动率，Theta 按每日历日。价格超出模型可解范围时返回空值，不伪造估算。
未验证的报价探测
仅在用户明确要求探测时运行：
python3 scripts/option/get_option_quote.py MU261120P900000 --greeks
该命令尝试把已知代码传给股票 /realtime，不是官方期权链。空结果或错误退出码为 2。806109 可能是权限问题，806111 可能是代码映射问题；不能仅凭探测失败否定券商所有期权行情能力。成功也必须核对代码、时间戳和权限，不能将旧成交价当作可成交价格。
不要仅因 IV 高于历史实现波动率就宣称卖方占优；还需考虑未来事件、期限、偏斜、流动性及风险限额。
限额与错误处理
- 按公开文档：
basicinfo为 20 次/分钟；其余六个基础行情接口各 120 次/分钟。脚本没有跨进程全局频控，批量请求主动限速。 - 历史 K 线额度：普通客户 200 标的、PRO 500 标的，按最近 30 天不同标的计；以当前账户授权为准。
- WebSocket：
rt/tk/ob，最多 10 个 topic，订阅与取消每秒最多 10 个；同 token 占用其他连接时先关闭本人旧连接，不自动结束未知进程。 - 服务端应用层
ping回pong；解码 base64 推送。失败、断线或未成功订阅返回非零退出码，不冒充成功。 - 缺少
code的 HTTP 响应不视为成功；权限和签名错误向用户说明，不静默降级为免费或延时行情。
参考资料与验证
按需求加载，不重复读全部文档：
docs/AUTH.md：双密钥、签名、登录及凭证安全。docs/API_REFERENCE.md：接口参数、响应字段和 WebSocket 协议。docs/API_LIMITS.md：限额、游标及文档不一致之处。docs/OPTIONS.md：期权能力证据、估值假设及误差来源。tests/test_skill.py：本地回归；运行python3 -B -m unittest discover -s tests -v。
官方文档：https://api-doc.usmart8.com/zh-cn/ 。资料可能滞后；实际行为以盈立授权接口、官方最新文档和联调结果为准。本技能为社区实现，不是盈立官方 SDK。
