wmshare 1.7.0__tar.gz

wmshare-1.7.0/LICENSE

@@ -0,0 +1,154 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Required Notice: Copyright (c) 2026 wmshare contributors
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.
+
+Standard License Header
+
+There is no standard license header for the license
+
+<<beginOptional>># PolyForm Noncommercial License 1.0.0
+
+<<endOptional>>
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

wmshare-1.7.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: wmshare
+Version: 1.7.0
+Summary: A 股个股数据 Python SDK：随包内置机器可读数据目录 + 云端取数客户端（开箱即用，内置体验 appid）
+Author: wmshare contributors
+License-Expression: PolyForm-Noncommercial-1.0.0
+Project-URL: Homepage, https://github.com/open-winmale/wmshare
+Project-URL: Documentation, https://github.com/open-winmale/wmshare/blob/main/docs/API.md
+Project-URL: Issues, https://github.com/open-winmale/wmshare/issues
+Keywords: A股,stock,finance,financial-data,quant,dividend,kline,financial-statements,screener,sdk,china-stock,pandas,market-data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Requires-Dist: PyYAML>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: jsonschema>=4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Provides-Extra: dataframe
+Requires-Dist: pandas>=1.5; extra == "dataframe"
+Dynamic: license-file
+
+# wmshare
+
+[![CI](https://github.com/open-winmale/wmshare/actions/workflows/ci.yml/badge.svg)](https://github.com/open-winmale/wmshare/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/wmshare)](https://pypi.org/project/wmshare/)
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](pyproject.toml)
+[![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm_NC_1.0-blue)](./LICENSE)
+[![Types: py.typed](https://img.shields.io/badge/Types-py.typed-blue)](src/wmshare/py.typed)
+
+> **English TL;DR** — `wmshare` is a source-available (non-commercial) Python SDK for China A-share
+> market data (partial HK/US coverage — see "市场覆盖" for the per-market matrix):
+> k-line (3 adjustment modes), intraday snapshots, money flow, the three financial statements,
+> 2,197 metric codes (TTM, historical & industry percentiles, dividend analytics), a screener
+> facade (single-stock screens & server-side market breadth), announcements and company profiles.
+> Ships a machine-readable offline catalog, unified base units with per-response data guards
+> (ratios as decimals, money in CNY, volume in shares), a typed facade, an AI-agent skill, and a
+> zero-config trial AppID (shared pool; register for your own quota). **Install**: `pip install wmshare`. Free for non-commercial use; commercial use requires a separate license.
+
+> **⚠️ 许可声明（请先阅读）**：本项目采用
+> [PolyForm Noncommercial 1.0.0](LICENSE) 许可，**属于 source-available（源码可见），
+> 不是 OSI 定义的开源软件**。个人学习、研究等非商业使用完全免费；商业使用需另行授权。
+
+A 股个股数据 Python SDK（**A股为主，港股/美股部分支持**——各市场覆盖明细见下方
+[「市场覆盖」](#市场覆盖)）。
+注册开放平台领取凭证（非商业免费、注册即得）后即可取数，见下方「配置凭证」。
+
+## 目录
+
+[特性](#特性) · [快速上手](#快速上手) · [能力一览](#能力一览) · [市场覆盖](#市场覆盖) ·
+[单位与数据守护](#单位与数据守护) · [我想做 X → 用哪一行](#我想做-x--用哪一行) ·
+[使用限制](#使用限制必读) · [更多](#更多)
+
+## 特性
+
+- **数据要全**——16 个数据域、113 个核心接口一站取全：K 线（三种复权、1 分钟分时、
+  盘中快照、ETF/指数）、分红、三大报表、资金流、公告、业绩预告、股东治理（十大股东/
+  质押五族/限售解禁/机构持仓/沪港通/国家队/高管增减持/股本结构）、回购（方案+执行）、
+  并购重组、担保与诉讼、融资融券、可转债、盈利预测与研报、指数成分与估值、港美股披露。
+- **数据要准**——财报按最新会计准则归一，跨年跨公司直接比较；全库基础单位
+  （比率/涨跌幅=小数、金额=元、量=股）；每次返回做量级守护与关系不变量校验，
+  错误的量级到不了你的代码（见下方「单位与数据守护」）。
+- **特色数据**——非商业免费且含实时（盘中快照、当日 1 分钟分时不另收费）；
+  `cli.screener` 涨停/均线筛选一行直出，全市场涨跌全景/分桶/行业分布/涨跌榜走
+  服务端预计算索引，毫秒级响应，你不拉全市场数据、不算均线；2,197 个指标码
+  （TTM、3/5/10 年历史分位、192 个行业内分位、TTM 股息率/派息率 + 11 个质量筛选器）
+  服务端算好直出，不关心指标算法。
+- **凭证即用**——注册开放平台免费领取 client_id/api-key（注册即得），环境变量、
+  凭证文件、构造参数任选其一配置；遇到 401/403/429 错误消息即完整指引。
+- **目录随包 + AI 原生**——249 个底层函数、113 个核心接口、2,197 个指标码离线可查；
+  附 Agent Skills 格式 skill（`wmshare.skill_dir()`），复制进 AI agent 即可正确使用。
+
+## 快速上手
+
+### 安装
+
+```bash
+pip install wmshare                  # 基础安装
+pip install "wmshare[dataframe]"     # 可选：pandas 支持（_df=True）
+```
+
+国内镜像源（如阿里云）同步新版本可能滞后，装不到最新版时可临时指定官方源：
+`pip install -i https://pypi.org/simple wmshare`。开发/贡献者安装见
+[CONTRIBUTING.md](CONTRIBUTING.md)。
+
+### 配置凭证
+
+注册 [赢麻了开放平台](https://open.winmale.com)（微信扫码，非商业免费、注册即得），
+在「我的 → 开放平台 → 我的应用」查看 `client_id` 与 api-key，然后任选其一：
+
+```bash
+export WMSHARE_CLIENT_ID=... WMSHARE_CLIENT_SECRET=...  # 方式一：环境变量
+# 方式二：写入 ~/.wmshare/credentials.env（KEY=VALUE 每行一条）
+```
+
+### 三行上手
+
+```python
+import wmshare
+
+cli = wmshare.Client.from_env()                   # 读上面配置的凭证
+print(cli.dividend.yield_ttm("600519"))           # 0.0396（TTM 股息率，小数）
+print(cli.screener.index_breadth_summary())       # 全市场涨跌全景（服务端直出）
+```
+
+更多调用见下方「我想做 X → 用哪一行」。遇到 401/403/429：错误消息里附有申请与配置
+凭证的完整步骤。
+
+## 能力一览
+
+随包离线目录：**16 个数据域 · 249 个底层函数 · 2197 个指标代码**（11 个指标组、
+75 个精选常用指标代码，`cat.search("中文")` 可编程检索）；友好层 **113 个核心接口**，
+按使用视角组织为：
+
+| 门面 | 核心能力 | 单位口径 |
+|---|---|---|
+| `cli.kline` | 日 K 三种复权（自上市首日起全覆盖，最早 1991 年）、最新/盘中快照、1 分钟分时、ETF/指数 | 价格=元、量=股、涨跌幅=小数 |
+| `cli.screener` | 单票筛选器（涨停/均线/动量/回撤/放量）+ 全市场涨跌全景/分桶/行业分布/涨跌榜 | 阈值=小数；宽度 `*_pct`=百分数数值 |
+| `cli.moneyflow` | 主力/超大单/大单/中单/小单净流入（日频+盘中） | 金额=元 |
+| `cli.statements` | 三大报表多期、合并 vs 母公司、目录树、审计意见 | 报表原币元 |
+| `cli.segments` | 经营分部：分产品/业务/区域收入构成 | 元；比率=小数 |
+| `cli.indicator` | 按指标码取数：估值/盈利/成长/现金流/杜邦 | 比率=小数 |
+| `cli.valuation` | PE/PB/PS/市赚率的历史统计与分位（窗口上限 3 年） | 分位=小数 |
+| `cli.notice` | 公告检索、回购/减持信号 | — |
+| `cli.filings` | 定期报告清单与最新 | — |
+| `cli.forecast` | 业绩预告/快报、财报披露日历 | 同比=小数 |
+| `cli.dividend` | 分红历史、TTM 股息率/派息率、质量筛选器 | 率=小数、DPS=元/股 |
+| `cli.equity` | 股东治理：十大股东/股东户数/质押/解禁/机构持仓/沪港通/国家队/高管增减持/股本/回购/并购重组/关联交易/担保/诉讼 | 比例=小数、金额=元、量=股 |
+| `cli.margin` | 个股融资融券（融资买入/偿还/余额、融券卖出/偿还/余量） | 金额=元、量=股 |
+| `cli.estimates` | 机构盈利预测（逐年 EPS/PE）、预测明细、评级统计、个股研报 | EPS=元/股、PE=倍 |
+| `cli.cbond` | 可转债合约快照、条款事件、正股关联、强赎计数、日 K 与盘中 1 分钟 | 价格=元（面值 100） |
+| `cli.workout` | 契约套利条款（要约收购/换股/现金选择权）看板与单票查询 | 价格=元 |
+| `cli.index` | 指数键列表、成分股（市值/估值中枢）、权重股、宽基估值时序 | 市值=元、比率=小数、权重=小数 |
+| `cli.intl` | 港股 CCASS/主要股东/机构评级/盈利预测，港美沽空，美股发行信息 | 量=股、占比=小数、价格=披露币种 |
+| `cli.info` | 公司档案（名称/行业/组织类型/上市日期） | — |
+
+## 市场覆盖
+
+| 数据能力 | A股 cn | 港股 hk | 美股 us |
+|---|---|---|---|
+| 日 K 三种复权 / 1 分钟分时 / 盘中快照 | ✅ 全量 | ✅ | 历史（日 K 停更）/ 快照新鲜，见注记 |
+| 三大报表 | ✅ | 未上线 | 未上线 |
+| 公告检索 + 变更订阅（`NoticePoller`） | ✅ | ✅ | — |
+| CCASS / 主要股东 / 机构评级 / 盈利预测（`cli.intl`） | — | ✅ | — |
+| 沽空（`cli.intl.query_sellshort`） | — | ✅ | ✅ |
+| 发行信息（`cli.intl.issue_info`） | — | — | ✅ |
+| 离线代码表 + 检索（`cat.symbols_search`） | ✅ | ✅ | ✅ |
+| 其余 15 个数据域：全景筛选/选股、资金流、两融、可转债、分红、业绩预告、股东治理、指数、契约套利、2197 指标库… | ✅ | — | — |
+
+市场切换：`Client(market="cn" / "hk" / "us")`，缺省 cn；代码与市场不匹配会被服务端直接拒绝
+（如 cn 市场查 `00700` 报 market mismatch）。`cli.intl` 的港美股披露同样要用对应市场的
+客户端调用（函数内部再按标的代码路由到港美数据族）。
+
+如实注记（2026-10-27 实测）：美股日 K 为历史快照、停更于 2026-03-13（上游对美股价量走
+live-only 策略），美股最新价量用 `cli.kline.live / snapshot`（实测当日新鲜）；港美 K 线
+量额单位已随 1.x 修复（cn 手×100 仅在 cn 生效，港美上游即股直出）；港美股三大报表的
+合同已预留原币口径（港币/美元），数据尚未上线。
+
+## 我想做 X → 用哪一行
+
+| 我想做… | 一行接口 | 省掉的计算 |
+|---|---|---|
+| 看 TTM 股息率 | `cli.dividend.yield_ttm(sym)` | 拉全部分红史→截 TTM 窗→查市值→相除 |
+| 判断估值贵不贵 | `cli.indicator.get(sym, "$PCT_PE_TTM_10Y_LAST")` | 拉十年估值史自己算百分位 |
+| 看公司在行业里的位置 | `$CUR_IND_ROE_PCT_LAST`（行业内 ROE 分位，1=行业最高） | 拉全行业成分→逐票取 ROE→排序 |
+| 筛高股息且派息可持续 | `cli.dividend.screen_quality(sym)` | 自写股息/派息率质量模型 |
+| 站上 20 日线了吗 | `cli.screener.screen_above_ma20(sym)` | 拉 K 线→算均线→比较 |
+| 全市场今天涨跌如何 | `cli.screener.index_breadth_summary()` | 全市场扫描→聚合统计 |
+| 看最新十大股东 | `cli.equity.query_holder10(sym)` | 翻定期报告→抄股东名单 |
+| 质押比例高不高 | `cli.equity.query_pledge_summary(sym)` | 翻质押公告→逐笔累加 |
+| 下半年解禁压力大吗 | `cli.equity.query_release(sym)` | 翻解禁公告→手工排期 |
+| 两融余额什么水平 | `cli.margin.query(sym)` | 翻交易所两融披露→对日期 |
+| 券商怎么看这只票 | `cli.estimates.query_forecast(sym)` | 汇总各家研报预测→自己算均值 |
+| 沪深300 都有谁 | `cli.index.members("index.hs300", "mv", 10)` | 找成分表→自己拉行情 |
+| 这票正股有哪些转债 | `cli.cbond.of_stock(sym)` | 翻转债名录→逐只对正股 |
+| 港股筹码在谁手里 | `cli.intl.query_ccass(sym)` | 上披露易→逐日查 CCASS |
+| 今日涨幅榜前十 | `cli.screener.index_top_movers(limit=10)` | 全市场扫描→排序→取头部 |
+| 近半年有无回购/减持 | `cli.notice.has_buyback(sym, "6m")` | 拉公告列表→分类匹配→截窗 |
+| 合并与母公司差多少 | `cli.statements.compare(sym)` | 双表对齐→逐科目相除 |
+
+**常用示例（输出为预期量级；`cli.kline.bars` / `statements.income` 等其余接口同风格）**：
+
+```python
+import wmshare
+
+cli = wmshare.Client.from_env()
+
+# TTM 股息率：小数口径，0.0396 = 3.96%
+print(cli.dividend.yield_ttm("600519"))                      # 0.0396
+
+# 估值温度计：PE(TTM) 处于近 10 年 42% 分位（小数）
+print(cli.indicator.get("600519", "$PCT_PE_TTM_10Y_LAST"))   # 0.42
+
+# 行业定位：ROE 在同行业内的分位（1.0 = 行业最高；茅台 ROE 为行业之最）
+print(cli.indicator.get("600519", "$CUR_IND_ROE_PCT_LAST"))  # 1.0
+
+# 技术面一行布尔：是否站上 20 日均线
+print(cli.screener.screen_above_ma20("600519"))              # True
+
+# 全市场涨跌全景：服务端索引直出，免本地扫描（*_pct 百分数、median_pct 小数）
+print(cli.screener.index_breadth_summary())
+# {'total': 5685, 'up': 4567, 'down': 934, 'flat': 184, 'up_pct': 80.3, ...}
+
+# 分红质量：高股息 + 派息可持续（默认精品窗口=派息率 30%–70%，可显式放宽）
+print(cli.dividend.screen_quality("600519", min_yield=0.02, payout_max=1.5))  # True
+
+# 公告信号：近 6 个月是否有回购公告
+print(cli.notice.has_buyback("600519", "6m"))                # True
+```
+
+以上能力全部在离线目录可查：`cat.search("分位")`、`cat.metrics_in_group("dividend")`。
+
+## 单位与数据守护
+
+全库统一基础单位：**比率 / 涨跌幅 = 小数**（0.01 = 1%，ROE 0.332 = 33.2%）、
+**金额 / 价格 / 市值 = 元**（报表原币）、**成交量 = 股**；各接口单位口径见「能力一览」表。
+返回前做量级与关系不变量校验，违例抛 `DataError`——错误的量级到不了你的代码。
+需要脚本原始口径时：`_raw=True`（store 原始行）、`_units="native"`（脚本输出单位），
+或 `Client(validate=False)` 关闭校验。
+
+数据深度：个股/ETF 日 K 覆盖**自上市首日以来的全部交易日**（最早 1991 年）；
+单次区间上限 5 年、默认单次 500 根（`Client(max_limit=...)` 可调）。全量深回溯
+（1990 年代不复权老数据）可能触发不变量守护，需整段历史时 `validate=False` 取全。
+
+## 使用限制（必读）
+
+本项目采用 [PolyForm Noncommercial License 1.0.0](LICENSE)：
+
+- ✅ **仅限非商业目的**：个人学习、研究、教学、学术、爱好者项目、公益组织等，完全免费；
+- ❌ **严禁商业使用**：任何商业目的的使用、再分发或服务化均需另行获得商业授权；
+- 本许可属于 source-available（源码可见）而非 OSI 定义的开源许可。
+
+商业授权请联系项目维护方。数据仅供研究参考，不构成任何投资建议。
+
+## 更多
+
+- **AI agent skill（随包分发）**：把 skill 装进 agent 的发现目录，AI 即可正确使用
+  SDK（目录先行防臆造指标码、单位铁律、错误引导都在 skill 里）：
+
+  ```bash
+  cp -r "$(python3 -c 'import wmshare; print(wmshare.skill_dir())')" ~/.agents/skills/wmshare
+  # 项目级按工具放入 .zcode/skills/ 或 .claude/skills/
+  ```
+  skill 源文件：[src/wmshare/skills/wmshare/SKILL.md](src/wmshare/skills/wmshare/SKILL.md)
+  （LLM 可直接读取的结构化用法）。
+
+- **生态工具 [big-winner](https://github.com/open-winmale/big-winner)**（基于本 SDK 构建的开源工具）：
+  **收息佬**——攒股收息驾驶舱（分红日历、A/H 持仓透视、派息稳定性看板）；
+  **波段**——估值买卖点参考：区间设置支持**推荐区间**（四条约束自动搜点，含成交次数）
+  与**自定义区间**两种来源，附安全边界（高位介入回撤统计）与「波段 vs 长持」历史回放。
+- [API 参考](docs/API.md)：四大类 113 个核心接口（参数 / 返回字段 / 单位口径 / 示例）+ 指标组
+- **OpenAPI / Swagger**：[docs/openapi.json](docs/openapi.json)（OpenAPI 3.1，可导入
+  Apifox / Postman 等工具）；[docs/swagger.html](docs/swagger.html)（已内联 spec，浏览器直接打开；
+  Swagger UI 资源来自 CDN，若浏览器限制 `file://` 可在 docs 目录起 `python -m http.server`）
+- 类型化门面：全部目录命名空间带类型签名与 docstring（`py.typed`），IDE 直接补全；
+  单次拉取上限 `Client(max_limit=500)` 可调
+- 批量调用：`cli.call_batch("kline.query_bars", ["600519", "000001"])` 单次 HTTP 返回
+  `{symbol: 结果}`；`on_error="skip"` 时逐标的隔离错误
+- [贡献指南](CONTRIBUTING.md)：提交门禁、内容规范、许可政策
+- 运行测试：`pytest`（不联网）；`WMSHARE_LIVE=1 pytest tests/test_live.py`（真实冒烟）