wmshare 1.7.0__py3-none-any.whl

wmshare/__init__.py

@@ -0,0 +1,46 @@
+"""wmshare — WinMale 个股开放数据 SDK。
+
+机器可读数据目录（catalog/）+ OpenAPI 取数客户端。返回值统一基础单位：
+比率/涨跌幅=小数（0.332=33.2%）、金额/价格/市值=元（报表原币）、股数/成交量=股；
+每次返回都经过目录声明的量级守护与关系不变量校验（违例抛 DataError）。
+
+    import wmshare
+
+    cat = wmshare.load()                             # 数据目录（域/函数/参数/返回 schema）
+    fn = cat.function("kline.query_bars")
+
+    cli = wmshare.Client.from_env()                  # 读 WMSHARE_CLIENT_ID/SECRET（或凭证文件）
+    bars = cli.call("kline.query_bars", sym="600519", limit=30)
+    # _units="native" 保留脚本输出单位；_raw=True 返回 store 原始行；
+    # Client(validate=False) 关闭校验（换算仍执行）
+"""
+from wmshare.catalog import Catalog, load
+from wmshare.client import BatchResult, Client, normalize_symbol
+from wmshare.errors import (
+    ApiError, AuthError, CatalogError, DataError, WmshareError, LimitError,
+    ServerError, StreamResetError, TransportError, UsageError,
+)
+from wmshare.notice_stream import NoticePoller, NoticeStreamEvent
+
+__version__ = "1.7.0"
+
+__all__ = [
+    "Catalog", "load", "Client", "BatchResult", "normalize_symbol", "__version__",
+    "skill_dir",
+    "NoticePoller", "NoticeStreamEvent",
+    "WmshareError", "AuthError", "UsageError", "LimitError", "TransportError",
+    "ServerError", "ApiError", "DataError", "CatalogError", "StreamResetError",
+]
+
+
+def skill_dir():
+    """随包分发的 AI agent skill 目录（Agent Skills 格式，含 SKILL.md）。
+
+    装入 agent（复制到其发现路径之一）::
+
+        cp -r "$(python3 -c 'import wmshare; print(wmshare.skill_dir())')" \\
+            ~/.agents/skills/wmshare
+    """
+    from pathlib import Path
+
+    return Path(__file__).resolve().parent / "skills" / "wmshare"

wmshare/_catalog/domains/corp.equity.yaml

@@ -0,0 +1,87 @@
+id: corp.equity
+version: 2.1.0
+cn: 股东与股本
+kind: raw
+category: reference
+priority: P1
+description: 股东治理与股本全景——十大股东、股东户数、股权质押（明细+比例+市场/行业/
+  机构分布）、限售解禁、机构持股（明细/占比/沪港通/国家队）、高管名册与增减持、股本结构、
+  回购（方案+执行）、并购重组、关联交易、一致行动人、对外担保、诉讼处罚。披露原值直采，
+  比例字段统一换算为小数（0.0522 = 5.22%）。
+data_origin: [交易所披露, 平台数据服务]
+stores: [biz.equity, ref.info]
+units:
+  ratio: 小数（比例字段以各函数 units 声明为准：上游 fmt 部分接口已预换算小数、
+    部分仍为百分数——2026-10-28 全量审计逐函数核验，勿按字段名臆断）
+  money: 元（持股市值/质押市值/回购金额等，披露源口径）
+  shares: 股（持股数/解禁数量/质押数量）
+  price: 元（交易均价/回购价）
+requires: {path: sys/equity/init.xs, preloaded: true}
+notes:
+  - '公司档案（名称/行业/上市日期/简介）经 cli.info.profile() 与 fund.indicators 的
+    profile 指标组（$NAME/$INDUSTRY_CUR/$ORG_ORGTYPE/$ORG_LISTINGDATE）获取'
+  - '比例字段换算以各函数 units 声明为准（同接口内可能混排：institution_summary 的
+    all_shares_ratio 为百分数、total_shares_ratio 已是小数）；ranges 为 2026-10-28
+    live 审计实测界；其余未声明字段保持披露原值'
+  - '2026-10-28 审计已核验为元/股/小数并补 ranges：reorg.deal_amount（元）、
+    violation.punish_amt（元）、executives.salary（元/年）、capital_change.total_shares
+    （股）、holdernum 比例族（小数）、pledge_market.pledge_ratio_total（小数，
+    上游 inventory cn「百分数」为遗留标注）；guarantee_amt、exec_change 族仍待样本'
+  - 'query_exec_change_at / query_capital_change_at 按报告期取数（annual 如 2024、
+    sampling 如 Q4）'
+functions:
+  # ---- 股东 ----
+  - {name: equity.query_holder10, cn: 最新一期十大股东, layer: L0, normalize_with: equity.fmt_holder10, ranges: {hold_num_ratio: [0, 1]}}
+  - {name: equity.query_holdernum, cn: 最新股东户数, layer: L0, normalize_with: equity.fmt_holdernum, ranges: {hold_ratio_total: [0, 1], freehold_ratio_total: [0, 1], total_num_ratio: [0, 1], avg_freeshares_ratio: [-1, 1], avg_hold_amt: [0, 1.0e+09], avg_free_shares: [0, 1.0e+10]}}
+  # ---- 质押 ----
+  - {name: equity.query_pledge_detail, cn: 主要股东质押明细, layer: L0, normalize_with: equity.fmt_pledge_detail, units: {accum_pledge_tsr: percent, pf_hold_ratio: percent, pf_tsr: percent}, ranges: {accum_pledge_tsr: [0, 1], pf_hold_ratio: [0, 1], pf_tsr: [0, 1]}}
+  - {name: equity.query_pledge_summary, cn: 公司质押比例, layer: L0, normalize_with: equity.fmt_pledge_summary, ranges: {pledge_ratio: [0, 1]}}
+  - {name: equity.query_pledge_market, cn: 市场整体质押, layer: L0, normalize_with: equity.fmt_pledge_market, ranges: {pledge_ratio_total: [0, 1], csi300_chg: [-1, 1], pledge_market_value: [0, 1.0e+14], total_pledged_shares: [0, 1.0e+13]}}
+  - {name: equity.query_pledge_industry, cn: 行业质押比例, layer: L0, normalize_with: equity.fmt_pledge_industry, ranges: {avg_pledge_ratio: [0, 1]}}
+  - {name: equity.query_pledge_org, cn: 质押机构分布, layer: L0, normalize_with: equity.fmt_pledge_org}
+  # ---- 机构 ----
+  - {name: equity.query_institution_detail, cn: 机构持股明细, layer: L0, normalize_with: equity.fmt_institution_detail, units: {total_shares_ratio: percent, free_shares_ratio: percent}, ranges: {total_shares_ratio: [0, 1], free_shares_ratio: [0, 1]}}
+  - {name: equity.query_institution_summary, cn: 机构持仓占比, layer: L0, normalize_with: equity.fmt_institution_summary, units: {all_shares_ratio: percent}, ranges: {all_shares_ratio: [0, 1], total_shares_ratio: [0, 1], change_ratio: [-1, 1]}}
+  - {name: equity.query_hgt, cn: 沪港通持股, layer: L0, normalize_with: equity.fmt_hgt, units: {add_shares_pct: percent}, ranges: {add_shares_pct: [0, 1], free_shares_ratio: [0, 1], total_shares_ratio: [0, 1]}}
+  - {name: equity.query_national_team, cn: 国家队持股, layer: L0, normalize_with: equity.fmt_national_team, units: {shares_ratio: percent, shares_ratio_change: percent}, ranges: {shares_ratio: [0, 1], shares_ratio_change: [-1, 1]}}
+  # ---- 治理事件 ----
+  - {name: equity.query_release, cn: 限售解禁日程, layer: L0, normalize_with: equity.fmt_release, units: {total_shares_ratio: percent, unlimited_ratio: percent}, ranges: {total_shares_ratio: [0, 1], unlimited_ratio: [0, 1]}}
+  - {name: equity.query_buyback_plan, cn: 回购方案全览, layer: L0, normalize_with: equity.fmt_buyback_plan}
+  - {name: equity.query_buyback_detail, cn: 回购执行明细, layer: L0, normalize_with: equity.fmt_buyback_detail}
+  - {name: equity.query_reorg, cn: 并购重组, layer: L0, normalize_with: equity.fmt_reorg, units: {transfer_ratio: percent}, ranges: {transfer_ratio: [0, 1]}}
+  - {name: equity.query_related_trade, cn: 关联交易, layer: L0, normalize_with: equity.fmt_related_trade}
+  - {name: equity.query_concert, cn: 一致行动人, layer: L0, normalize_with: equity.fmt_concert, units: {hold_ratio: percent}, ranges: {hold_ratio: [0, 1]}}
+  - {name: equity.query_guarantee, cn: 对外担保, layer: L0, normalize_with: equity.fmt_guarantee}
+  - {name: equity.query_litigation, cn: 诉讼记录, layer: L0, normalize_with: equity.fmt_litigation}
+  - {name: equity.query_violation, cn: 违规处罚, layer: L0, normalize_with: equity.fmt_violation, ranges: {punish_amt: [0, 1.0e+11]}}
+  # ---- 高管与股本 ----
+  - {name: equity.query_executives, cn: 高管名册, layer: L0, normalize_with: equity.fmt_executives, ranges: {salary: [0, 1.0e+8], hold_num: [0, 1.0e+10]}}
+  - {name: equity.query_exec_change, cn: 高管增减持最新, layer: L0, normalize_with: equity.fmt_exec_change}
+  - {name: equity.query_exec_change_at, cn: 指定报告期增减持, layer: L1, normalize_with: equity.fmt_exec_change}
+  - {name: equity.query_capital_change, cn: 股本结构最新, layer: L0, normalize_with: equity.fmt_capital_change, ranges: {total_shares: [0, 1.0e+13], free_shares: [0, 1.0e+13]}}
+  - {name: equity.query_capital_change_at, cn: 指定报告期股本, layer: L1, normalize_with: equity.fmt_capital_change}
+  # ---- L1：规范化工具 ----
+  - {name: equity.fmt_holder10, cn: 十大股东行规范化, layer: L1}
+  - {name: equity.fmt_holdernum, cn: 股东户数规范化, layer: L1}
+  - {name: equity.fmt_pledge_detail, cn: 质押明细规范化, layer: L1}
+  - {name: equity.fmt_pledge_summary, cn: 质押比例规范化, layer: L1}
+  - {name: equity.fmt_pledge_market, cn: 市场质押规范化, layer: L1}
+  - {name: equity.fmt_pledge_industry, cn: 行业质押规范化, layer: L1}
+  - {name: equity.fmt_pledge_org, cn: 质押机构分布规范化, layer: L1}
+  - {name: equity.fmt_institution_detail, cn: 机构明细规范化, layer: L1}
+  - {name: equity.fmt_institution_summary, cn: 机构占比规范化, layer: L1}
+  - {name: equity.fmt_hgt, cn: 沪港通行规范化, layer: L1}
+  - {name: equity.fmt_national_team, cn: 国家队行规范化, layer: L1}
+  - {name: equity.fmt_release, cn: 解禁行规范化, layer: L1}
+  - {name: equity.fmt_buyback_plan, cn: 回购方案行规范化, layer: L1}
+  - {name: equity.fmt_buyback_detail, cn: 回购明细规范化, layer: L1}
+  - {name: equity.fmt_reorg, cn: 重组行规范化, layer: L1}
+  - {name: equity.fmt_related_trade, cn: 关联交易行规范化, layer: L1}
+  - {name: equity.fmt_concert, cn: 一致行动人行规范化, layer: L1}
+  - {name: equity.fmt_guarantee, cn: 担保行规范化, layer: L1}
+  - {name: equity.fmt_litigation, cn: 诉讼行规范化, layer: L1}
+  - {name: equity.fmt_violation, cn: 处罚行规范化, layer: L1}
+  - {name: equity.fmt_executives, cn: 高管行规范化, layer: L1}
+  - {name: equity.fmt_exec_change, cn: 增减持行规范化, layer: L1}
+  - {name: equity.fmt_capital_change, cn: 股本行规范化, layer: L1}
+  - {name: equity.fmt_lines, cn: 规范化行转文本, layer: L1}

wmshare/_catalog/domains/disc.bonus.yaml

@@ -0,0 +1,187 @@
+id: disc.bonus
+version: 1.3.0
+cn: 分红
+kind: raw
+category: disclosure
+priority: P0
+description: 分红历史明细（预案/实施）、每股股利、窗口合计。列表与 DPS 为披露原值；
+  股息率/派息率 TTM 快照及全市场筛选为计算派生（函数级标注性质）。
+data_origin: [公司公告披露]
+units:
+  dps: 元/股
+  total: 元（窗口合计金额）
+  window: '如 "3y" / "5y" 窗口字符串'
+  rate: 小数（0.03 = 3%）
+requires: {path: sys/bonus/init.xs, preloaded: true}
+notes:
+  - '已知问题：最新年度/中期分红记录的 net_profit/payout_ratio 列可能回填滞后（暂为 0），
+    仅影响 history 明细展示；筛选/快照走 TTM 派息指标（$BONUS_TTM_RATE_LAST）不受影响。
+    screen_quality 默认「精品」窗口=股息率>3% 且派息率 30%–70%，出界判 False 属设计'
+functions:
+  - name: bonus.query_list
+    cn: 分红历史明细
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true, desc: 6 位裸码}
+      - {name: limit, type: int, required: false, desc: 条数}
+    returns: {desc: 'ARR · 分红行（announce/ex_date/pay/dps/total/content/sas/payout_ratio）'}
+    example: 'bonus.query_list("600519", 20)'
+    normalize_with: bonus.fmt_maps
+    notes: [输出为规范化的扁平行（announce/ex_date/pay/dps/total/content/sas/payout_ratio），不再嵌套 props]
+  - name: bonus.query_last
+    cn: 最近一次分红
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+    returns: {desc: 分红行 MAP 或 nil}
+    example: 'bonus.query_last("600519")'
+  - name: bonus.query_at_sas
+    cn: 指定报告期分红
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: sas, type: string, required: true, desc: '报告期，如 "2024-Q4"'}
+    returns: {desc: 分红行 MAP 或 nil}
+    example: 'bonus.query_at_sas("600519", "2024-Q4")'
+  - name: bonus.dps_rpt
+    cn: 财报期每股分红
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+    returns: {desc: float · 财报期每股分红（元/股）}
+    example: 'bonus.dps_rpt("600519")'
+  - name: bonus.dps_rpt_asof
+    cn: 财报期每股分红（截至日）
+    kind: raw
+    layer: L0
+    params:
+      - {name: rows, type: array, required: true, desc: dps_rpt 结果}
+      - {name: asof, type: string, required: true, desc: 截至日期}
+    returns: {desc: 截至日的 DPS}
+    example: 'bonus.dps_rpt_asof(rows, "2025-06-30")'
+  - name: bonus.query_dps_window
+    cn: 窗口内每股股利合计
+    kind: computed
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: window, type: string, required: true, desc: 窗口（如 3y）}
+    returns: {desc: float · 元/股}
+    example: 'bonus.query_dps_window("600519", "3y")'
+  - name: bonus.query_total_window
+    cn: 窗口内总分红
+    kind: computed
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: window, type: string, required: true}
+    returns: {desc: float · 元}
+    example: 'bonus.query_total_window("600519", "3y")'
+  - name: bonus.query_count_window
+    cn: 窗口内分红次数
+    kind: computed
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: window, type: string, required: true}
+    returns: {desc: int}
+    example: 'bonus.query_count_window("600519", "5y")'
+    notes: ['已知问题：上游 count 聚合当前恒为 0（同窗口 sum 正常），待上游修复；SDK 的 window_stats 暂不返回该值']
+  - name: bonus.query_valid
+    cn: 有效分红序列（过滤无效行）
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: limit, type: int, required: false}
+    returns: {desc: ARR · 分红行}
+    example: 'bonus.query_valid("600519", 20)'
+  - name: bonus.snapshot
+    cn: 股息快照
+    kind: computed
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+    returns: {desc: MAP · 股息/率快照}
+    example: 'bonus.snapshot("600519")'
+  - name: bonus.snapshot_yield_ttm
+    cn: LTM 股息率
+    kind: computed
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+    returns: {desc: 'float · 小数（0.0396 = 3.96%）'}
+    example: 'bonus.snapshot_yield_ttm("600519")'
+    notes: [股息率 = TTM 分红总额 / 最新市值；数值为小数口径]
+  - name: bonus.snapshot_payout_ttm
+    cn: TTM 派息率
+    kind: computed
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+    returns: {desc: 'float · 小数（0.799 = 79.9%）'}
+    example: 'bonus.snapshot_payout_ttm("600519")'
+    notes: [派息率 = TTM 分红 / 归母净利 TTM；数值为小数口径]
+  # ---- L1：单票质量筛选（computed）----
+  - {name: bonus.screen_active, cn: 近年有分红, kind: computed, layer: L1}
+  - {name: bonus.screen_has_dividend, cn: 有分红记录, kind: computed, layer: L1}
+  - {name: bonus.screen_high_yield, cn: 高股息, kind: computed, layer: L1}
+  - {name: bonus.screen_ample_payout, cn: 慷慨派息, kind: computed, layer: L1}
+  - {name: bonus.screen_danger_payout, cn: 派息不可持续, kind: computed, layer: L1}
+  - {name: bonus.screen_quality, cn: 分红质量优, kind: computed, layer: L1}
+  - {name: bonus.screen_stable_yield, cn: 股息稳定, kind: computed, layer: L1}
+  - {name: bonus.screen_improving_yield, cn: 股息改善, kind: computed, layer: L1}
+  - {name: bonus.screen_trend_ok, cn: 分红趋势健康, kind: computed, layer: L1}
+  - {name: bonus.screen_declining_yield, cn: 股息下滑, kind: computed, layer: L1}
+  - {name: bonus.screen_undervalued_yield, cn: 低估+高股息, kind: computed, layer: L1}
+  # ---- L1：全市场筛选积木（computed，内部用途）----
+  - {name: bonus.index_where_active, cn: where·有分红, kind: computed, layer: L1}
+  - {name: bonus.index_where_no_dividend, cn: where·无分红, kind: computed, layer: L1}
+  - {name: bonus.index_where_has_dividend, cn: where·有记录, kind: computed, layer: L1}
+  - {name: bonus.index_where_high_yield, cn: where·高股息, kind: computed, layer: L1}
+  - {name: bonus.index_where_high_yield_5, cn: where·连续5年高股息, kind: computed, layer: L1}
+  - {name: bonus.index_where_ample_payout, cn: where·慷慨派息, kind: computed, layer: L1}
+  - {name: bonus.index_where_danger_payout, cn: where·派息危险, kind: computed, layer: L1}
+  - {name: bonus.index_where_quality, cn: where·质量, kind: computed, layer: L1}
+  - {name: bonus.index_where_stable, cn: where·稳定, kind: computed, layer: L1}
+  - {name: bonus.index_where_improving, cn: where·改善, kind: computed, layer: L1}
+  - {name: bonus.index_where_declining, cn: where·下滑, kind: computed, layer: L1}
+  - {name: bonus.index_where_trend_up, cn: where·趋势向上, kind: computed, layer: L1}
+  - {name: bonus.index_where_undervalued, cn: where·低估, kind: computed, layer: L1}
+  - {name: bonus.index_yield_bin_expr, cn: 股息率分桶 where 表达式, kind: computed, layer: L1}
+  - {name: bonus.index_field_load, cn: 分红索引字段预加载, kind: computed, layer: L1}
+  - {name: bonus.index_field_load_analysis, cn: 分红分析字段预加载, kind: computed, layer: L1}
+  - {name: bonus.index_fields_basic, cn: 分红基础字段列表, kind: computed, layer: L1}
+  - {name: bonus.index_fields_analysis, cn: 分红分析字段列表, kind: computed, layer: L1}
+  # ---- L1：格式化（raw 传递）----
+  - name: bonus.fmt_maps
+    cn: 分红行规范化
+    kind: raw
+    layer: L1
+    returns:
+      desc: ARR · 规范化分红行
+      shape:
+        kind: array
+        cn: 规范化分红行列表
+        items:
+          kind: object
+          cn: 分红行
+          fields:
+            - {name: sas, type: string, cn: SAS, optional: true}
+            - {name: ex_date, type: string, cn: 除权日, optional: true}
+            - {name: ex_div, type: string, cn: 除权除息日, optional: true}
+            - {name: dps, type: float64, cn: 每股股利, optional: true}
+            - {name: total, type: float64, cn: 分红总额, optional: true}
+            - {name: ccy, type: string, cn: 货币, optional: true}
+            - {name: announce, type: string, cn: 公告日, optional: true}
+            - {name: pay, type: string, cn: 派息日, optional: true}
+            - {name: content, type: string, cn: 方案摘要, optional: true}
+            - {name: net_profit, type: float64, cn: 归母净利润, optional: true}
+            - {name: payout_ratio, type: float64, cn: 派息率, optional: true}
+  - {name: bonus.fmt_lines, cn: 分红文本行, kind: raw, layer: L1}
+  - {name: bonus.fmt_line, cn: 单条分红文本, kind: raw, layer: L1}
+  - {name: bonus.fmt_snapshot_line, cn: 股息快照一行文本, kind: raw, layer: L1}

wmshare/_catalog/domains/disc.events.yaml

@@ -0,0 +1,91 @@
+id: disc.events
+version: 1.1.0
+cn: 业绩披露事件
+kind: raw
+category: disclosure
+priority: P0
+description: 业绩预告（yjyg：净利/扣非/营收区间+同比+修正轨迹）、业绩快报（yjkb）、
+  财报预约披露日历（disclosure）。均为交易所披露文件的结构化直采。
+data_origin: [交易所披露]
+units:
+  money: 元（预告/快报区间与单期金额）
+  yoy: 小数（0.1467 = 14.67%；SDK 自动由脚本的百分数口径换算）
+  date: YYYY-MM-DD
+requires: {path: sys/forecast/init.xs, preloaded: false}
+notes:
+  - 预告为区间（下限/上限）；快报为披露的近似单值——两者在报告期正式报表发布前使用
+  - 脚本原生 np_amp_* / rev_amp_* / np_yoy / rev_yoy / roe 为百分数；SDK 已换算为
+    小数并守护范围；_units="native"/_raw=True 取脚本原值
+functions:
+  - name: forecast.yjyg_rows
+    cn: 业绩预告历史
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true, desc: 6 位裸码}
+      - {name: limit, type: int, required: false, desc: 条数}
+    returns: {desc: ARR · 预告行（报告期/类型/净利与扣非区间/同比/修正轨迹）}
+    example: 'forecast.yjyg_rows("688008", 8)'
+    units: {np_amp_lower: percent, np_amp_upper: percent, rev_amp_lower: percent, rev_amp_upper: percent}
+    ranges: {np_amp_lower: [-1, 1000], np_amp_upper: [-1, 1000], rev_amp_lower: [-1, 1000], rev_amp_upper: [-1, 1000]}
+  - name: forecast.yjyg_latest
+    cn: 最新业绩预告
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+    returns: {desc: 预告行 MAP 或 nil}
+    example: 'forecast.yjyg_latest("688008")'
+    units: {np_amp_lower: percent, np_amp_upper: percent, rev_amp_lower: percent, rev_amp_upper: percent}
+    ranges: {np_amp_lower: [-1, 1000], np_amp_upper: [-1, 1000], rev_amp_lower: [-1, 1000], rev_amp_upper: [-1, 1000]}
+  - name: forecast.yjkb_rows
+    cn: 业绩快报历史
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: limit, type: int, required: false}
+    returns: {desc: ARR · 快报行}
+    example: 'forecast.yjkb_rows("603092", 8)'
+    units: {np_yoy: percent, rev_yoy: percent, roe: percent}
+    ranges: {np_yoy: [-1, 1000], rev_yoy: [-1, 1000], roe: [-2, 5]}
+  - name: forecast.yjkb_latest
+    cn: 最新业绩快报
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+    returns: {desc: 快报行 MAP 或 nil}
+    example: 'forecast.yjkb_latest("603092")'
+    units: {np_yoy: percent, rev_yoy: percent, roe: percent}
+    ranges: {np_yoy: [-1, 1000], rev_yoy: [-1, 1000], roe: [-2, 5]}
+  - name: forecast.disclosure_rows
+    cn: 财报预约披露历史
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: limit, type: int, required: false}
+    returns: {desc: ARR · 预约披露行（报告期/计划披露日）}
+    example: 'forecast.disclosure_rows("600519", 8)'
+  - name: forecast.disclosure_next
+    cn: 下次财报披露
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+    returns: {desc: 预约披露行 MAP 或 nil}
+    example: 'forecast.disclosure_next("600519")'
+  - name: forecast.snapshot
+    cn: 业绩披露快照（预告+快报+日历合并视图）
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+    returns: {desc: MAP · 快照}
+    example: 'forecast.snapshot("688008")'
+    units: {np_amp_lower: percent, np_amp_upper: percent, rev_amp_lower: percent, rev_amp_upper: percent, np_yoy: percent, rev_yoy: percent, roe: percent}
+    ranges: {np_amp_lower: [-1, 1000], np_amp_upper: [-1, 1000], rev_amp_lower: [-1, 1000], rev_amp_upper: [-1, 1000], np_yoy: [-1, 1000], rev_yoy: [-1, 1000], roe: [-2, 5]}
+  # ---- L1：格式化 ----
+  - {name: forecast.fmt_line, cn: 预告文本行, kind: raw, layer: L1}
+  - {name: forecast.fmt_lines, cn: 预告文本行列表, kind: raw, layer: L1}

wmshare/_catalog/domains/disc.filings.yaml

@@ -0,0 +1,39 @@
+id: disc.filings
+version: 1.0.0
+cn: 定期报告清单
+kind: raw
+category: disclosure
+priority: P0
+description: 年报/半年报/季报清单（报告期、标题、PDF 链接）。与 fund.statements
+  （结构化数字）分工：清单与原文链接走本域，结构化科目数字走三表。
+data_origin: [交易所披露]
+units:
+  date: YYYY-MM-DD
+requires: {path: sys/filings/init.xs, preloaded: true}
+notes:
+  - 'type_key 取值：all | annual(年报) | semi(半年报) | quarter(季报)'
+functions:
+  - name: filings.query
+    cn: 定期报告列表
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true, desc: 6 位裸码}
+      - {name: type_key, type: string, required: false, default: all, enum: [all, annual, semi, quarter]}
+      - {name: limit, type: int, required: false}
+    returns: {desc: ARR · 报告行（报告期/类型/标题/PDF 链接）}
+    example: 'filings.query("600519", "annual", 5)'
+  - name: filings.latest
+    cn: 最新一条定期报告
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: type_key, type: string, required: false, default: all}
+    returns: {desc: 报告行 MAP 或 nil}
+    example: 'filings.latest("600519", "annual")'
+  # ---- L1：辅助 ----
+  - {name: filings.type_zh, cn: type_key 转中文, kind: raw, layer: L1}
+  - {name: filings.fmt_maps, cn: 报告行规范化列表, kind: raw, layer: L1}
+  - {name: filings.fmt_map, cn: 单条报告规范化, kind: raw, layer: L1}
+  - {name: filings.fmt_date_short, cn: 日期缩短 YYYY-MM-DD, kind: raw, layer: L1}

wmshare/_catalog/domains/disc.notice.yaml

@@ -0,0 +1,160 @@
+id: disc.notice
+version: 1.1.0
+cn: 公告
+kind: raw
+category: disclosure
+priority: P0
+description: 公告检索（单票/日期/类别/区间）与公告信号（回购/减持/增持/股权激励证据行）。
+  公告标题与元数据为资讯源直采；signal_* 为窗口判定的薄计算（证据行仍为公告原值）。
+data_origin: [披露公告库(含港股)]
+units:
+  window: '枚举 "7d"|"1m"|"3m"|"6m"|"1y"|"3y"|"5y" 或天数整数'
+  date: YYYY-MM-DD
+requires: {path: sys/notice/init.xs, preloaded: true}
+notes:
+  - type_regex 按公告标题/类型正则过滤；market 缺省 cn，港股自动路由
+functions:
+  - name: notice.query_by_symbol
+    cn: 单票公告列表
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true, desc: 6 位裸码（港股 5 位）}
+      - {name: window, type: string, required: false, desc: 时间窗}
+      - {name: type_regex, type: string, required: false, desc: 类型正则}
+      - {name: limit, type: int, required: false}
+    returns: {desc: ARR · 公告行（date/title/type/url/pdf_url）}
+    example: 'notice.query_by_symbol("600519", "3m", "", 20)'
+    normalize_with: notice.fmt_maps
+  - name: notice.query_recent
+    cn: 近期公告（全市场）
+    kind: raw
+    layer: L0
+    params:
+      - {name: window, type: string, required: false}
+      - {name: type_regex, type: string, required: false}
+      - {name: limit, type: int, required: false}
+      - {name: market, type: string, required: false, desc: 缺省 cn}
+    returns: {desc: ARR · 公告行（date/title/type/url/pdf_url）}
+    example: 'notice.query_recent("7d", "", 50)'
+    normalize_with: notice.fmt_maps
+  - name: notice.query_by_category
+    cn: 按类别查公告
+    kind: raw
+    layer: L0
+    params:
+      - {name: category, type: string, required: true}
+      - {name: window, type: string, required: false}
+      - {name: limit, type: int, required: false}
+      - {name: market, type: string, required: false}
+    returns: {desc: ARR · 公告行（date/title/type/url/pdf_url）}
+    example: 'notice.query_by_category("回购", "1m", 20)'
+    normalize_with: notice.fmt_maps
+  - name: notice.query_on_date
+    cn: 指定日期公告
+    kind: raw
+    layer: L0
+    params:
+      - {name: date, type: string, required: true}
+      - {name: type_regex, type: string, required: false}
+      - {name: limit, type: int, required: false}
+      - {name: market, type: string, required: false}
+    returns: {desc: ARR · 公告行（date/title/type/url/pdf_url）}
+    example: 'notice.query_on_date("2026-09-30")'
+    normalize_with: notice.fmt_maps
+  - name: notice.query_find
+    cn: 按日期区间查公告
+    kind: raw
+    layer: L0
+    params:
+      - {name: from_date, type: string, required: true}
+      - {name: to_date, type: string, required: true}
+      - {name: type_regex, type: string, required: false}
+      - {name: stock_code, type: string, required: false}
+      - {name: limit, type: int, required: false}
+      - {name: market, type: string, required: false}
+    returns: {desc: ARR · 公告行（date/title/type/url/pdf_url）}
+    example: 'notice.query_find("2026-01-01", "2026-03-31", "业绩", "", 50)'
+    normalize_with: notice.fmt_maps
+  # ---- L0：信号（窗口判定薄计算，证据行=公告原值）----
+  - name: notice.signal_has_buyback
+    cn: 窗口内是否有回购公告
+    kind: computed
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: window, type: string, required: false}
+    returns: {desc: bool}
+    example: 'notice.signal_has_buyback("600519", "6m")'
+  - name: notice.signal_has_reduction
+    cn: 窗口内是否有减持公告
+    kind: computed
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: window, type: string, required: false}
+    returns: {desc: bool}
+    example: 'notice.signal_has_reduction("600519", "6m")'
+  - name: notice.signal_has_insider_buy
+    cn: 窗口内是否有增持公告
+    kind: computed
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: window, type: string, required: false}
+    returns: {desc: bool}
+    example: 'notice.signal_has_insider_buy("600519", "6m")'
+  - name: notice.signal_has_equity_incentive
+    cn: 窗口内是否有股权激励公告
+    kind: computed
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: window, type: string, required: false}
+    returns: {desc: bool}
+    example: 'notice.signal_has_equity_incentive("600519", "1y")'
+  - name: notice.signal_evidence_rows
+    cn: 信号证据（原始公告行）
+    kind: raw
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: type_regex, type: string, required: true}
+      - {name: window, type: string, required: false}
+      - {name: lim, type: int, required: false}
+    returns: {desc: ARR · 公告行}
+    example: 'notice.signal_evidence_rows("600519", "回购", "1y", 10)'
+  - name: notice.signal_evidence_buyback
+    cn: 回购证据（规范化行）
+    kind: computed
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: window, type: string, required: false}
+    returns: {desc: ARR · 规范化证据行}
+    example: 'notice.signal_evidence_buyback("600519", "1y")'
+  - name: notice.signal_evidence_reduction
+    cn: 减持证据（规范化行）
+    kind: computed
+    layer: L0
+    params:
+      - {name: sym, type: string, required: true}
+      - {name: window, type: string, required: false}
+    returns: {desc: ARR · 规范化证据行}
+    example: 'notice.signal_evidence_reduction("600519", "1y")'
+  # ---- L1：通用信号与检索辅助 ----
+  - {name: notice.signal_has, cn: 窗口内是否匹配类型正则, kind: computed, layer: L1}
+  - {name: notice.signal_has_category, cn: 窗口内是否有指定类别, kind: computed, layer: L1}
+  - {name: notice.signal_no_reduction, cn: 窗口内是否无减持, kind: computed, layer: L1}
+  - {name: notice.signal_evidence, cn: 信号证据（规范化）, kind: computed, layer: L1}
+  - {name: notice.query_symbols_on_date, cn: 指定日期出现公告的代码列表, kind: raw, layer: L1}
+  - {name: notice.query_stats_recent, cn: 近期公告类别计数, kind: raw, layer: L1}
+  - {name: notice.query_build, cn: 构建公告 Mongo filter, kind: raw, layer: L1, status: internal}
+  - {name: notice.query_build_visible, cn: 构建可见日公告 filter, kind: raw, layer: L1, status: internal}
+  - {name: notice.query_date_range, cn: 日期区间条件, kind: raw, layer: L1, status: internal}
+  - {name: notice.query_ts_range, cn: 入库时间区间条件, kind: raw, layer: L1, status: internal}
+  # ---- L1：格式化 ----
+  - {name: notice.fmt_maps, cn: 公告行规范化, kind: raw, layer: L1}
+  - {name: notice.fmt_lines, cn: 公告文本行, kind: raw, layer: L1}
+  - {name: notice.fmt_line, cn: 单条公告文本, kind: raw, layer: L1}
+  - {name: notice.fmt_count_by_type, cn: 按类型计数, kind: raw, layer: L1}

wmshare/_catalog/domains/disc.workout.yaml

@@ -0,0 +1,18 @@
+id: disc.workout
+version: 1.0.0
+cn: 契约套利
+kind: raw
+category: disclosure
+priority: P2
+description: 契约套利条款事件——要约收购/换股吸收合并/现金选择权等（披露原文提取），
+  提供进行中看板与单票条款查询。同业数据商暂无对应接口，属平台独有面。
+data_origin: [披露原文提取, 平台数据服务]
+units:
+  price: 元（公告对价/现价）
+requires: {path: sys/workout/init.xs, preloaded: false}
+notes:
+  - 'board() 返回 {as_of, deals, quotes} 进行中看板；query(sym) 返回单票规范化条款行'
+  - '现价 < 公告对价 的折价窗口由调用方自行判定，SDK 不内置收益测算（算法放工具仓）'
+functions:
+  - {name: workout.board, cn: 进行中契约套利看板, layer: L0}
+  - {name: workout.query, cn: 单票契约套利条款, layer: L0}

wmshare/_catalog/domains/fund.estimates.yaml

@@ -0,0 +1,24 @@
+id: fund.estimates
+version: 1.1.0
+cn: 盈利预测与研报
+kind: raw
+category: fundamentals
+priority: P1
+description: 卖方研究数据——机构盈利预测（逐年 EPS/PE，A=实际 E=预测）、预测明细
+  （机构/研究员/归母净利/评级）、评级统计（综合评级与买卖家数按窗口）、个股研报列表。
+  金额=元、EPS=元/股、PE=倍。
+data_origin: [券商研究披露, 平台数据服务]
+units:
+  eps: 元/股
+  money: 元（归母净利润）
+  pe: 倍（预测市盈率）
+requires: {path: sys/estimates/init.xs, preloaded: true}
+notes:
+  - 'year_mark A=实际值 E=预测值；YEAR1..YEAR4 为预测年份序列'
+  - '研报行含标题/机构/作者/行业/报告链接；研报正文不在接口范围'
+functions:
+  - {name: estimates.query_forecast, cn: 机构盈利预测, layer: L0, normalize_with: estimates.fmt_maps, ranges: {eps1: [0, 1.0e+4], eps2: [0, 1.0e+4], eps3: [0, 1.0e+4], eps4: [0, 1.0e+4], pe1: [0, 1.0e+4], pe2: [0, 1.0e+4], pe3: [0, 1.0e+4], pe4: [0, 1.0e+4]}}
+  - {name: estimates.query_forecast_detail, cn: 盈利预测明细, layer: L0, normalize_with: estimates.fmt_maps, ranges: {eps1: [0, 1.0e+4], eps2: [0, 1.0e+4], eps3: [0, 1.0e+4], eps4: [0, 1.0e+4], pe1: [0, 1.0e+4], pe2: [0, 1.0e+4], pe3: [0, 1.0e+4], pe4: [0, 1.0e+4]}}
+  - {name: estimates.query_rating, cn: 评级统计, layer: L0, normalize_with: estimates.fmt_maps}
+  - {name: estimates.query_reports, cn: 个股研报, layer: L0, normalize_with: estimates.fmt_maps}
+  - {name: estimates.fmt_maps, cn: 预测行规范化, layer: L1}