stock-analysis-plugin 0.2.12 → 0.2.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -24,7 +24,7 @@
24
24
  - **策略视角**:缠论、波浪理论、龙头战法、情绪周期等 18 套方法论,以 Skill 形式按需调用。
25
25
  - **dsh 仪表盘**:在 dsh Web / Desktop 侧栏看自选股和六个市场的行情,后台预热,打开即显示。
26
26
 
27
- 一共 74 个工具、21 个 Skills,11 个数据源自动容灾。大部分功能不需要任何 API Key。
27
+ 一共 75 个工具、21 个 Skills,11 个数据源自动容灾。大部分功能不需要任何 API Key。
28
28
 
29
29
  ## 快速开始
30
30
 
@@ -79,8 +79,8 @@
79
79
 
80
80
  | 代码格式 | 示例 | 市场 | 行情报价 Failover 链(K 线差异见下方) |
81
81
  |----------|------|------|---------------------|
82
- | 6 位纯数字 | `600519`, `000001`, `300750` | A 股 | 腾讯 → akshare → tushare → efinance → 新浪 |
83
- | 6 位纯数字(51/52/56/58/15/16/18 开头) | `510300`, `159915` | A 股 ETF | 腾讯 → akshare(ETF/全市场接口)→ tushare → efinance → 新浪 |
82
+ | 6 位纯数字 | `600519`, `000001`, `300750` | A 股 | 腾讯 → 东方财富 → tushare → 新浪 |
83
+ | 6 位纯数字(51/52/56/58/15/16/18 开头) | `510300`, `159915` | A 股 ETF | 腾讯 → 东方财富 → tushare → 新浪 |
84
84
  | 带交易所前缀(`sh`/`sz`/`bj` + 6 位数字) | `sh000001`(上证指数), `sz399006`(创业板指) | A 股(显式指定,含指数) | 腾讯 → 新浪 |
85
85
  | `.HK` 结尾 | `00700.HK`, `09988.HK` | 港股 | yfinance → 腾讯 → finnhub → longbridge |
86
86
  | 英文字母 | `AAPL`, `GOOGL`, `TSLA` | 美股 | yfinance → finnhub → longbridge → 腾讯 → alphavantage |
@@ -165,11 +165,11 @@
165
165
 
166
166
  ## 工具列表
167
167
 
168
- 74 个工具按用途分组:
168
+ 75 个工具按用途分组:
169
169
 
170
170
  | 类别 | 数量 | 主要内容 |
171
171
  |------|------|----------|
172
- | 数据获取 | 28 | K 线、报价、基金净值、资金流、财务、板块、涨停池、龙虎榜、两融、估值历史、股东、ETF、股息、公告、SEC |
172
+ | 数据获取 | 29 | K 线、报价、基金净值、资金流、财务、板块、涨停池、龙虎榜、两融、估值历史、股东、ETF、股息、公告、SEC、CDS 指数 |
173
173
  | 分析计算 | 9 | 技术指标、K 线形态、量价、异动、信号胜率、趋势与行业轮动研究 |
174
174
  | 筛选与回测 | 8 | 多因子选股、风险筛查、策略回测、市场状态、日度复盘、自选股批量分析 |
175
175
  | 搜索与舆情 | 5 | 新闻搜索、综合情报、社交情绪、正文提取 |
@@ -178,7 +178,7 @@
178
178
  | 无状态研究与风险计算 | 9 | 同行比较、公告变更、组合风险、调仓计划、仓位计算、DCF 估值、事件研究、回测稳健性 |
179
179
 
180
180
  <details>
181
- <summary>完整工具列表(74 个)</summary>
181
+ <summary>完整工具列表(75 个)</summary>
182
182
 
183
183
  #### 数据获取
184
184
 
@@ -189,13 +189,14 @@
189
189
  | `get_insider_trades` | SEC 股票 ticker/发行人 CIK 的 Form 4 内部人交易、代码和脚注 |
190
190
  | `get_valuation_history` | A/HK/US PE-TTM/PB 历史、正值分位与估值 Band,实际采样窗口(美股由 SEC 申报与周收盘派生) |
191
191
  | `get_index_valuation` | 中国指数 PE/PB 历史水位;中证官方多年滚动 PE;可选理杏仁补充 PB |
192
+ | `get_cds_index` | 市场级 CDS 指数:中国在岸 CFETS-SHCH 指数期限曲线,或 DTCC 公开成交的 CDX/iTraxx 当前系列日中位数;窗口变化与分位,可按 index/tenor 只取单个指数和期限;非个股 CDS |
192
193
  | `get_earnings_calendar` | A 股报告期披露与业绩预告;HK 董事会排期;US/JP yfinance 预计日期(provider_only,非官方确认) |
193
194
  | `get_shareholder_structure` | A 股股东户数/十大流通股东变化/报告期北向名义持股;HK 南向持股 |
194
195
  | `get_etf_details` | A 股 ETF 净值折溢价、规模变动、披露持仓、可选基准成分与跟踪误差 |
195
196
  | `get_dividends` | A/HK/US/JP/KR/TW 历史分红与除息日历、已实现 TTM 股息;排行仍仅 A/HK |
196
197
  | `get_kline` | K 线数据(OHLCV),支持日/周/月线;A 股股票/ETF 前复权,每条记录 `adjusted=qfq`,指数 `adjusted=none` |
197
198
  | `get_quote` | 实时行情快照(非交易时段返回最近交易日收盘价并以 as_of/stale 标注;`pe_basis` 区分 dynamic/trailing/unknown;ETF 的 premium_discount_rate 为正=溢价、负=折价);场外基金用 `get_fund_quote`,TIAAxxxxxx 返回投顾组合识别、`advisor_org` 与无统一净值提示;长钱/海外长钱/稳钱另有有知有行 `official_disclosures`(`partial=true`,非实时完整持仓);其他组合搜索可用时为 `search_partial`,否则 `unsupported_provider` |
198
- | `get_fund_quote` | 6 位场外公募基金净值;`nav` 是 `nav_date` 对应的已披露日终净值而非实时价,`accumulated_nav` 为累计净值、`change_pct` 为日涨跌幅;`estimated_nav` 可能为 `null`,QDII 净值可能滞后 1-2 交易日 |
199
+ | `get_fund_quote` | 6 位场外公募基金净值;`nav` 是 `nav_date` 对应的已披露日终净值而非实时价,`accumulated_nav` 为累计净值、`change_pct` 为日涨跌幅;`estimated_nav` 目前恒为 `null`(东方财富单只基金估值接口已下线),QDII 净值可能滞后 1-2 交易日 |
199
200
  | `get_capital_flow` | 资金流向(仅 A 股) |
200
201
  | `get_news` | 个股相关新闻 |
201
202
  | `get_financials` | 财务指标;可选追加 A/港/美股年度 DCF 输入 |
@@ -205,7 +206,7 @@
205
206
  | `get_sector_rankings` | 板块涨跌排行(A 股行业/概念;美股 SPDR 行业 ETF 代理) |
206
207
  | `get_sector_constituents` | 板块成分股查询(仅 A 股,板块名模糊匹配) |
207
208
  | `resolve_stock_sectors` | 个股所属板块查询(A 股行业+概念 / 港股 GICS) |
208
- | `get_market_stats` | 市场统计(A/HK/US 涨跌家数、成交额;涨停仅 A 股) |
209
+ | `get_market_stats` | 市场统计(A/HK/US 涨跌家数;成交额、涨停仅 A 股) |
209
210
  | `get_limit_up_pool` | 涨停池/涨停板复盘(连板数、封板资金、炸板次数等,仅 A 股;非交易日自动回退到最近交易日并以 requested_date/stale 标注) |
210
211
  | `get_dragon_tiger` | 龙虎榜(净买额/上榜原因/解读,仅 A 股;非交易日自动回退到最近交易日并以 requested_date/stale 标注) |
211
212
  | `get_hot_stocks` | 全市场人气热搜榜(东财→百度,仅 A 股) |
@@ -401,6 +402,7 @@ python tools/value_data.py earnings_calendar --report-date 2026-09-30 --symbol 6
401
402
  python tools/value_data.py shareholder_structure 600519 --report-date 2026-06-30
402
403
  python tools/value_data.py shareholder_structure 0700.HK
403
404
  python tools/value_data.py index_valuation 000300 --years 5
405
+ python tools/credit_data.py cds_index --source cn --days 30
404
406
  python tools/value_data.py etf_details 510300 --benchmark sh000300 --days 60
405
407
  python tools/value_data.py etf_details 510300 --include-full-holdings
406
408
  python tools/stock_data.py margin_trading 600519 --days 10 --include-ratio
@@ -459,7 +461,7 @@ sort_order: "desc"
459
461
  npm install # 同时构建仓库 .venv
460
462
  .venv/bin/python -m pytest -q # Python 单元测试(离线)
461
463
  npx tsc --noEmit # TypeScript 类型检查
462
- npx tsx tests/test_adapter_parity.ts # 四个宿主的 74 个工具和参数映射一致
464
+ npx tsx tests/test_adapter_parity.ts # 四个宿主的 75 个工具和参数映射一致
463
465
  npm run build:openclaw && npm run build:dsh # 构建 OpenClaw / dsh bundle
464
466
  ```
465
467
 
@@ -471,12 +473,12 @@ npm run build:openclaw && npm run build:dsh # 构建 OpenClaw / dsh bundle
471
473
  ```
472
474
  stock-analysis/
473
475
  ├── pi/ # Pi Agent Extension
474
- │ └── index.ts # 注册 74 个工具 + 21 个 skill
476
+ │ └── index.ts # 注册 75 个工具 + 21 个 skill
475
477
  ├── hermes/ # Hermes Agent Plugin
476
478
  │ ├── plugin.yaml # 插件清单
477
479
  │ ├── __init__.py # register(ctx) 入口
478
480
  │ ├── schemas.py # 读取 tools/tool_schemas.json
479
- │ └── tools.py # 74 个 handler → subprocess 调 CLI
481
+ │ └── tools.py # 75 个 handler → subprocess 调 CLI
480
482
  ├── openclaw/ # OpenClaw Plugin
481
483
  │ ├── openclaw.plugin.json # manifest(contracts.tools)
482
484
  │ ├── package.json # 含 openclaw 块(pluginApi/SDK 版本)
@@ -491,7 +493,7 @@ stock-analysis/
491
493
  │
492
494
  ├── mcp_host/ # MCP stdio 服务器(复用 Hermes schema/handler)
493
495
  ├── tools/ # 共享 Python CLI 工具
494
- │ ├── tool_schemas.json # 74 个工具的名称/描述/参数(各宿主共用)
496
+ │ ├── tool_schemas.json # 75 个工具的名称/描述/参数(各宿主共用)
495
497
  │ ├── stock_data.py # 行情 / 资金流 / 新闻 / 财务 / 短线情绪
496
498
  │ ├── signal_tracker.py # AI 买卖建议回测闭环(本地 JSONL 存储)
497
499
  │ ├── technical.py # 技术指标分析
package/docs/mcp.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # MCP 接入指南(WorkBuddy / Claude Desktop / Cursor)
2
2
 
3
- `mcp_host/server.py` 是本插件的 MCP stdio 服务器:一行一条 JSON-RPC 2.0 消息,只用 Python 标准库。它复用所有宿主共用的 JSON Schema(`tools/tool_schemas.json`,经 `hermes/schemas.py` 读取)和参数映射(`hermes/tools.py`),所以 74 个工具的名称、参数和输出与其他宿主一致。
3
+ `mcp_host/server.py` 是本插件的 MCP stdio 服务器:一行一条 JSON-RPC 2.0 消息,只用 Python 标准库。它复用所有宿主共用的 JSON Schema(`tools/tool_schemas.json`,经 `hermes/schemas.py` 读取)和参数映射(`hermes/tools.py`),所以 75 个工具的名称、参数和输出与其他宿主一致。
4
4
 
5
5
  ## 前置条件
6
6
 
@@ -36,7 +36,7 @@
36
36
  | Claude Desktop | `claude_desktop_config.json`(设置 → Developer → Edit Config) |
37
37
  | Cursor | `~/.cursor/mcp.json`(全局)或 `<项目目录>/.cursor/mcp.json` |
38
38
 
39
- 保存后,客户端里出现 74 个工具(如 `get_quote`、`get_technical_analysis`)即接入成功。
39
+ 保存后,客户端里出现 75 个工具(如 `get_quote`、`get_technical_analysis`)即接入成功。
40
40
 
41
41
  ## 行为说明
42
42
 
@@ -19,6 +19,7 @@ provides_tools:
19
19
  - get_insider_trades
20
20
  - get_valuation_history
21
21
  - get_index_valuation
22
+ - get_cds_index
22
23
  - get_earnings_calendar
23
24
  - get_shareholder_structure
24
25
  - get_etf_details
package/hermes/tools.py CHANGED
@@ -495,6 +495,23 @@ def get_index_valuation(args: dict, **kwargs) -> str:
495
495
  return _run("value_data.py", ["index_valuation", args["symbol"], "--years", args.get("years", 5)])
496
496
 
497
497
 
498
+ def get_cds_index(args: dict, **kwargs) -> str:
499
+ return _run(
500
+ "credit_data.py",
501
+ [
502
+ "cds_index",
503
+ "--source",
504
+ args.get("source", "cn"),
505
+ "--days",
506
+ args.get("days", 30),
507
+ "--index",
508
+ args.get("index", ""),
509
+ "--tenor",
510
+ args.get("tenor", ""),
511
+ ],
512
+ )
513
+
514
+
498
515
  def get_earnings_calendar(args: dict, **kwargs) -> str:
499
516
  return _run(
500
517
  "value_data.py",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "stock-analysis-plugin",
3
- "version": "0.2.12",
3
+ "version": "0.2.13",
4
4
  "description": "Pi Agent extension for stock analysis, screening, and strategy backtesting across A/HK/US/JP/KR/TW markets",
5
5
  "type": "module",
6
6
  "main": "./pi/index.ts",
@@ -28,6 +28,10 @@ export const TOOL_CALLS = {
28
28
  script: "value_data.py",
29
29
  argv: (p) => ["index_valuation", p.symbol, "--years", String(p.years ?? 5)],
30
30
  },
31
+ get_cds_index: {
32
+ script: "credit_data.py",
33
+ argv: (p) => ["cds_index", "--source", p.source ?? "cn", "--days", String(p.days ?? 30), "--index", p.index ?? "", "--tenor", p.tenor ?? ""],
34
+ },
31
35
  get_earnings_calendar: {
32
36
  script: "value_data.py",
33
37
  argv: (p) => ["earnings_calendar", "--report-date", p.report_date ?? "", "--symbol", p.symbol ?? "", "--top", String(p.top ?? 50)],
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: bull-trend
3
- description: 趋势交易:识别中长期趋势,制定入场、持仓和退出规则。用于趋势温度计算、趋势股持有、规则化趋势策略或肥尾收益分析。
3
+ description: 趋势交易:识别中长期趋势,制定入场、持仓和退出规则。用于趋势温度计算、趋势股持有、规则化趋势策略、肥尾收益或非对称风险(赔率、凸性、脆弱性)分析。
4
4
  ---
5
5
 
6
6
  # 趋势追踪分析
@@ -9,7 +9,7 @@ description: 趋势交易:识别中长期趋势,制定入场、持仓和退
9
9
 
10
10
  趋势追踪用可执行的规则参与趋势,通过控制试错损失、保留盈利空间捕获少数大行情。肥尾描述收益分布,趋势描述价格路径;肥尾指标不是趋势启动或延续信号。
11
11
 
12
- 用户询问塔勒布、肥尾计算、极端行情或策略是否依赖少数大盈利时,先读取 [肥尾度量与趋势收益诊断](references/fat-tails.md)。概念问题直接解释方法;需要具体统计结果时,按参考中的数据口径准备输入并调用 `scripts/tail_analysis.py`。普通趋势判断无需加载这份参考。
12
+ 用户询问塔勒布、肥尾计算、极端行情、非对称风险(赔率、盈亏比、凸性、脆弱性)或策略是否依赖少数大盈利时,先读取 [肥尾、非对称风险与趋势收益诊断](references/fat-tails.md)。概念问题直接解释方法;需要具体统计结果时,按参考中的数据口径准备输入并调用 `scripts/tail_analysis.py`。普通趋势判断无需加载这份参考。
13
13
 
14
14
  仅解释肥尾概念时,到此完成;下述流程用于具体标的的趋势分析。
15
15
 
@@ -1,4 +1,4 @@
1
- # 肥尾度量与趋势收益诊断
1
+ # 肥尾、非对称风险与趋势收益诊断
2
2
 
3
3
  本参考供趋势 skill 和趋势策略回测按需读取。数值由本 skill 的 [计算脚本](../scripts/tail_analysis.py) 执行,无需独立工具注册。保留输入、运行参数和输出;没有执行环境或数据时只解释方法,数值标为未计算。
4
4
 
@@ -9,10 +9,12 @@
9
9
  ```bash
10
10
  python skills/bull-trend/scripts/tail_analysis.py returns historical-returns.json --n 2 10 30 --draws 20000 --seed 42
11
11
  python skills/bull-trend/scripts/tail_analysis.py returns historical-returns.json --current 0.05
12
+ python skills/bull-trend/scripts/tail_analysis.py returns historical-returns.json --tail-prob 0.05 --threshold 0
12
13
  python skills/bull-trend/scripts/tail_analysis.py trades backtest-result.json
14
+ python skills/bull-trend/scripts/tail_analysis.py fragility scenarios.json --center 0
13
15
  ```
14
16
 
15
- `returns` 输入是同周期历史对数收益的 JSON 数组,如 `[0.01, -0.02, 0.005]`,以小数表示;`--current` 的当前收益另传,必须从历史输入中排除。脚本不转换价格、不抓行情、不识别日期,因此先按下文校验并记录数据口径。`trades` 输入是含完整 `trades` 数组的回测 JSON。脚本 stdout 输出 JSON,失败返回 `error` 并以非零状态退出。
17
+ `returns` 输入是同周期历史对数收益的 JSON 数组,如 `[0.01, -0.02, 0.005]`,以小数表示;`--current` 的当前收益另传,必须从历史输入中排除。脚本不转换价格、不抓行情、不识别日期,因此先按下文校验并记录数据口径。`trades` 输入是含完整 `trades` 数组的回测 JSON。`fragility` 输入是情景损益表,格式见下文。脚本 stdout 输出 JSON,失败返回 `error` 并以非零状态退出。
16
18
 
17
19
  κ 默认 n0 = 1,以固定种子做 iid 经验重抽样,输出每个 n 的 κ 和平均绝对偏差;换种子重复运行检查 Monte Carlo 波动,换历史窗口检查数据敏感性。输出没有总体置信区间。`sample_count` 是历史收益数量,`draws` 是模拟轮数,两者不能混称样本量。`current_event.percentile` 为 0..1,`upper_exceedances` / `lower_exceedances` 是历史严格超过 / 低于当前收益的次数。
18
20
 
@@ -23,9 +25,13 @@ python skills/bull-trend/scripts/tail_analysis.py trades backtest-result.json
23
25
  | 收益分布有多肥尾 | 固定周期的历史收益 | 样本尾部特征、κ 的条件性估计 |
24
26
  | 当前涨跌是否极端 | 当前收益与此前同周期收益 | 历史分位或阈值超越,不能推导后续方向 |
25
27
  | 趋势系统是否靠大赢家 | 策略平仓盈亏 | 盈利集中度及移除大赢家后的敏感性 |
28
+ | 涨跌空间是否对称、赔率是否划算 | 历史收益或交易计划 | 尾部盈亏比、Omega、赔率与盈亏平衡胜率 |
29
+ | 头寸是否怕波动(脆弱性) | 冲击情景下的头寸损益 | 凸性 H、上下行盈亏比 |
26
30
 
27
31
  市场收益的厚尾、策略收益的正偏和趋势延续是不同性质。塔勒布的度量回答统计稳定性问题;下文的分位和盈利贡献是本项目的诊断方法,不称为塔勒布交易信号。
28
32
 
33
+ 肥尾和非对称风险是两层问题:肥尾描述**分布**(极端值多大、多常见,用 κ 和分位),非对称描述**暴露**(同样幅度的上下波动带来的损益是否对称,用凸性 H)。同一只股票,裸多头是线性暴露,买认购期权是凸的,卖认沽期权是凹的;分布相同,风险完全不同。
34
+
29
35
  ## 数据口径
30
36
 
31
37
  使用 `get_kline` 或现有 `stock_data.py kline`,核对实际返回的日期范围、周期、数量和复权标记。股票历史价格保持一致复权口径,指数保持原始点位;先处理乱序、重复日期和无效价格,说明停牌或缺失导致的时间间隔,保留真实极端收益。
@@ -86,6 +92,73 @@ T_without_k = T - 最大 k 笔正盈利之和
86
92
 
87
93
  现有回测有固定止盈默认值;省略 `take_profit` 不会关闭止盈。验证保留右尾的退出规则前,检查实际引擎和 DSL 的支持情况,将无法表达的规则明确列为未验证。
88
94
 
95
+ ## 非对称风险:公式模板
96
+
97
+ 以下全部用经验数据或用户给定的情景,不拟合分布。不要用偏度、峰度做核心指标:肥尾下高阶矩样本估计极不稳定,一个极端值就能改写结果。
98
+
99
+ ### 收益分布的尾部不对称(`returns` 的 `asymmetry`)
100
+
101
+ ```text
102
+ q_lo = 分位(r, p),q_hi = 分位(r, 1-p),p 由 --tail-prob 设定,默认 0.05
103
+ ETL = mean(r_i | r_i <= q_lo) 左尾平均亏损(负数)
104
+ ETG = mean(r_i | r_i >= q_hi) 右尾平均盈利
105
+ 尾部盈亏比 = ETG / |ETL| ETG <= 0 或 ETL >= 0 时为 null
106
+ Omega(τ) = sum(max(r_i-τ, 0)) / sum(max(τ-r_i, 0)) τ 由 --threshold 设定
107
+ ```
108
+
109
+ 尾部盈亏比 > 1 说明样本里大涨的幅度大于大跌;Omega > 1 说明高于 τ 的收益总量超过低于 τ 的总量。没有低于 τ 的收益时 Omega 为 null。尾部样本数 `lower_tail_count` / `upper_tail_count` 很少时只作描述;N = 500、p = 0.05 时每侧约 25 个点。
110
+
111
+ ### 交易赔率(`trades` 与交易计划)
112
+
113
+ ```text
114
+ 胜率 p = 盈利笔数 / 平仓笔数
115
+ 赔率 b = 平均盈利 / |平均亏损| 脚本字段 payoff_ratio
116
+ 盈亏平衡胜率 p* = 1 / (1 + b) 脚本字段 breakeven_win_rate
117
+ 单笔期望(以 1 单位风险计)E = p*b - (1-p)
118
+ ```
119
+
120
+ 单笔计划用 R 倍数,无需脚本:
121
+
122
+ ```text
123
+ R = (目标价 - 入场价) / (入场价 - 止损价)
124
+ p* = 1 / (1 + R)
125
+ ```
126
+
127
+ 例:入场 10、止损 9、目标 13,R = 3,p* = 25%;胜率估计高于 25% 才有正期望。止损可能跳空击穿,实际亏损按历史跳空幅度或最坏情景补充说明。
128
+
129
+ ### 暴露的凸性与脆弱性(`fragility`)
130
+
131
+ 来源:[Taleb, Canetti et al., A New Heuristic Measure of Fragility and Tail Risks, IMF WP/12/216](https://www.imf.org/en/publications/wp/issues/2016/12/31/a-new-heuristic-measure-of-fragility-and-tail-risks-application-to-stress-testing-26222)([arXiv 1208.1189](https://arxiv.org/abs/1208.1189))。
132
+
133
+ 设 f(x) 是冲击幅度 x(如标的涨跌幅、利率变动)下的头寸损益,c 为中心情景:
134
+
135
+ ```text
136
+ H(Δ) = (f(c-Δ) + f(c+Δ)) / 2 - f(c)
137
+ H < 0 凹,脆弱:波动越大越亏,伤害随冲击加速
138
+ H > 0 凸,反脆弱:波动越大越有利
139
+ H ≈ 0 线性
140
+ 上下行盈亏比 = (f(c+Δ) - f(c)) / (f(c) - f(c-Δ))
141
+ ```
142
+
143
+ 输入模板(`capital` 可选,用于输出 `h_over_capital`):
144
+
145
+ ```json
146
+ {
147
+ "capital": 100000,
148
+ "scenarios": [
149
+ {"shock": -0.2, "pnl": -2000},
150
+ {"shock": -0.1, "pnl": -2000},
151
+ {"shock": 0, "pnl": -1500},
152
+ {"shock": 0.1, "pnl": 3500},
153
+ {"shock": 0.2, "pnl": 8500}
154
+ ]
155
+ }
156
+ ```
157
+
158
+ 这是买入认购期权的形状,H 为正。卖出认沽、加杠杆被强平、高负债公司的股权在下跌端加速亏损,H 为负。必须包含中心情景和对称的 ±Δ;多组 Δ 时看 H 是否随 Δ 增大而加速变负,这是脆弱性的核心信号。
159
+
160
+ `analyze_portfolio_risk` 的压力测试按 beta 线性推算,其结果作为 f(x) 时 H 恒为 0;非线性只来自期权、止损、杠杆与保证金、可转债,或公司层面的负债与经营杠杆。公司层面可用不同营收或利率冲击下的净利润或权益价值作为 f(x),情景须由用户或财报数据给出并注明假设。
161
+
89
162
  ## 完成标准
90
163
 
91
- 报告指出分析对象、数据来源及区间、周期、复权口径、样本量、公式与估计方法、实际数值或未计算原因。κ 结果还需注明 n0、n、抽样假设和敏感性;盈利集中度需注明平仓与未平仓口径。交易建议依据趋势和风险规则,统计结果仅提供其能支持的证据。
164
+ 报告指出分析对象、数据来源及区间、周期、复权口径、样本量、公式与估计方法、实际数值或未计算原因。κ 结果还需注明 n0、n、抽样假设和敏感性;盈利集中度需注明平仓与未平仓口径;非对称结果需注明 tail-prob、阈值或情景来源。交易建议依据趋势和风险规则,统计结果仅提供其能支持的证据。
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env python3
2
- """Skill-local tail diagnostics from historical returns or backtest JSON."""
2
+ """Skill-local tail and asymmetric-risk diagnostics from returns, backtest trades or payoff scenarios."""
3
3
 
4
4
  import argparse
5
5
  import json
@@ -21,12 +21,37 @@ def finite_number(value):
21
21
  return float(value)
22
22
 
23
23
 
24
+ def ratio(numerator, denominator):
25
+ return numerator / denominator if denominator > 0 else None
26
+
27
+
28
+ def return_asymmetry(values, tail_prob, threshold):
29
+ lower, upper = (float(q) for q in np.quantile(values, [tail_prob, 1 - tail_prob]))
30
+ lower_tail, upper_tail = values[values <= lower], values[values >= upper]
31
+ tail_loss, tail_gain = float(lower_tail.mean()), float(upper_tail.mean())
32
+ excess = values - threshold
33
+ return {
34
+ "tail_probability": tail_prob,
35
+ "threshold": threshold,
36
+ "lower_quantile": lower,
37
+ "upper_quantile": upper,
38
+ "expected_tail_loss": tail_loss,
39
+ "expected_tail_gain": tail_gain,
40
+ "tail_gain_loss_ratio": ratio(tail_gain, -tail_loss) if tail_gain > 0 else None,
41
+ "lower_tail_count": len(lower_tail),
42
+ "upper_tail_count": len(upper_tail),
43
+ "omega": ratio(float(np.clip(excess, 0, None).sum()), float(np.clip(-excess, 0, None).sum())),
44
+ }
45
+
46
+
24
47
  def analyze_returns(data, args):
25
48
  if not isinstance(data, list) or len(data) < 2:
26
49
  raise ValueError("Expected a JSON array of at least two historical returns")
27
50
  values = np.array([finite_number(value) for value in data])
28
51
  if not 100 <= args.draws <= 1000000 or args.seed < 0 or any(n < 2 or n > 10000 for n in args.n):
29
52
  raise ValueError("Require draws in 100..1000000, seed >= 0, and n in 2..10000")
53
+ if not 0 < args.tail_prob < 0.5 or not math.isfinite(args.threshold):
54
+ raise ValueError("Require tail-prob in (0, 0.5) and a finite threshold")
30
55
  centered = values - values.mean()
31
56
  mad = float(np.abs(centered).mean())
32
57
  rng = np.random.default_rng(args.seed)
@@ -67,6 +92,7 @@ def analyze_returns(data, args):
67
92
  "mean_absolute_deviation": mad,
68
93
  "kappa": rows,
69
94
  "current_event": event,
95
+ "asymmetry": return_asymmetry(values, args.tail_prob, args.threshold),
70
96
  "method": "iid resampling of centered empirical returns; not a population tail estimate or trading signal",
71
97
  }
72
98
 
@@ -78,9 +104,11 @@ def analyze_trades(data):
78
104
  raise ValueError("Each trade must have type buy or sell")
79
105
  pnl = [finite_number(trade.get("pnl")) for trade in data["trades"] if trade["type"] == "sell"]
80
106
  winners = sorted((value for value in pnl if value > 0), reverse=True)
107
+ losers = [value for value in pnl if value < 0]
81
108
  gross_profit = math.fsum(winners)
82
- gross_loss = math.fsum(value for value in pnl if value < 0)
109
+ gross_loss = math.fsum(losers)
83
110
  net = math.fsum(pnl)
111
+ payoff = ratio(gross_profit / len(winners), -gross_loss / len(losers)) if winners and losers else None
84
112
  return {
85
113
  "closed_trades": len(pnl),
86
114
  "winning_trades": len(winners),
@@ -88,6 +116,9 @@ def analyze_trades(data):
88
116
  "gross_loss": gross_loss,
89
117
  "realized_net_pnl": net,
90
118
  "worst_trade_pnl": min(pnl) if pnl else None,
119
+ "win_rate": len(winners) / len(pnl) if pnl else None,
120
+ "payoff_ratio": payoff,
121
+ "breakeven_win_rate": 1 / (1 + payoff) if payoff else None,
91
122
  "winner_contribution": [
92
123
  {
93
124
  "requested_k": k,
@@ -101,6 +132,54 @@ def analyze_trades(data):
101
132
  }
102
133
 
103
134
 
135
+ def analyze_fragility(data, center):
136
+ if not isinstance(data, dict) or not isinstance(data.get("scenarios"), list):
137
+ raise ValueError("Expected a JSON object with a scenarios array of {shock, pnl}")
138
+ capital = data.get("capital")
139
+ if capital is not None and finite_number(capital) <= 0:
140
+ raise ValueError("capital must be positive")
141
+ payoff = {}
142
+ for row in data["scenarios"]:
143
+ if not isinstance(row, dict):
144
+ raise ValueError("Each scenario must be an object with shock and pnl")
145
+ # Rounded keys pair center±delta despite binary float error.
146
+ shock = round(finite_number(row.get("shock")), 10)
147
+ if shock in payoff:
148
+ raise ValueError("Duplicate scenario shock")
149
+ payoff[shock] = finite_number(row.get("pnl"))
150
+ center = round(finite_number(center), 10)
151
+ if center not in payoff:
152
+ raise ValueError("Scenarios must include the center shock")
153
+ base, pairs = payoff[center], []
154
+ for shock in sorted(s for s in payoff if s > center):
155
+ delta = round(shock - center, 10)
156
+ down = payoff.get(round(center - delta, 10))
157
+ if down is None:
158
+ continue
159
+ up = payoff[shock]
160
+ h = (up + down) / 2 - base
161
+ scale = max(1.0, abs(up), abs(down), abs(base))
162
+ pairs.append(
163
+ {
164
+ "delta": delta,
165
+ "pnl_down": down,
166
+ "pnl_center": base,
167
+ "pnl_up": up,
168
+ "h": h,
169
+ "h_over_capital": h / capital if capital else None,
170
+ "gain_loss_ratio": ratio(up - base, base - down),
171
+ "shape": "linear" if abs(h) <= 1e-9 * scale else "convex" if h > 0 else "concave",
172
+ }
173
+ )
174
+ if not pairs:
175
+ raise ValueError("Need at least one center-delta and center+delta scenario pair")
176
+ return {
177
+ "center": center,
178
+ "pairs": pairs,
179
+ "method": "H=(f(center-delta)+f(center+delta))/2-f(center) on supplied scenarios; H<0 is fragile",
180
+ }
181
+
182
+
104
183
  def main():
105
184
  try:
106
185
  parser = Parser(description=__doc__)
@@ -111,11 +190,21 @@ def main():
111
190
  returns.add_argument("--draws", type=int, default=20000)
112
191
  returns.add_argument("--seed", type=int, default=42)
113
192
  returns.add_argument("--current", type=float, help="Separate current return, excluded from historical input")
193
+ returns.add_argument("--tail-prob", type=float, default=0.05, help="Each tail's probability for asymmetry")
194
+ returns.add_argument("--threshold", type=float, default=0.0, help="Omega gain/loss threshold return")
114
195
  trades = sub.add_parser("trades", help="Analyze a complete run_backtest JSON result")
115
196
  trades.add_argument("input", type=Path)
197
+ fragility = sub.add_parser("fragility", help="Taleb-IMF fragility heuristic from payoff scenarios")
198
+ fragility.add_argument("input", type=Path)
199
+ fragility.add_argument("--center", type=float, default=0.0, help="Shock level to perturb around")
116
200
  args = parser.parse_args()
117
201
  data = json.loads(args.input.read_text(encoding="utf-8"))
118
- result = analyze_returns(data, args) if args.command == "returns" else analyze_trades(data)
202
+ if args.command == "returns":
203
+ result = analyze_returns(data, args)
204
+ elif args.command == "trades":
205
+ result = analyze_trades(data)
206
+ else:
207
+ result = analyze_fragility(data, args.center)
119
208
  print(json.dumps(result, ensure_ascii=True, allow_nan=False))
120
209
  return 0
121
210
  except OSError:
@@ -58,6 +58,7 @@ gather 工具返回以下字段:
58
58
 
59
59
  ### 7. 风险提示
60
60
  - 需要注意的系统性风险
61
+ - 信用风险偏好:可调用 `get_cds_index`(A 股用 `source="cn", tenor="1Y"`,index 取 `"高等级"` 和 `"民企"`,美股用 `source="global", index="CDX.NA.IG"` 和 `"CDX.NA.HY"`),报告指数、期限、窗口变化与分位;信用利差走阔是风险背景,不是择时信号
61
62
  - 板块/个股层面的风险信号
62
63
  - 外围市场可能的影响
63
64
 
@@ -25,6 +25,8 @@ description: 综合股票分析:联合技术、基本面、资金、消息和
25
25
 
26
26
  用户要求短线、波段、交易计划或买卖时机时,读取[短线交易决策框架](references/short-term-trading.md);普通基本面或长期价值分析不加载该参考。
27
27
 
28
+ 用户询问非对称风险、赔率、盈亏比、凸性或脆弱性时,读取[肥尾、非对称风险与趋势收益诊断](../bull-trend/references/fat-tails.md)的非对称风险公式模板。
29
+
28
30
  | 意图 | 调用序列 |
29
31
  |------|---------|
30
32
  | 个股买卖时机 | `get_technical_analysis` → `get_market_capabilities` → 当前市场支持的资金/风险工具 → `detect_market_regime`。A股可加 `get_capital_flow`(summary) 和 `screen_risk`;其他市场不得用缺失的资金或风险数据。veto_buy=true 则不入场;大盘下跌时个股看多信号降级为轻仓试错或等待;HOLD/WAIT 给出可观察触发条件 |
@@ -47,7 +49,7 @@ python3 scripts/gather.py <symbol>
47
49
 
48
50
  解读实时行情前先调 `get_trading_phase` 确认该市场当前盘中阶段(盘前/早盘/午间休市/午盘/交易中/盘后/休市),避免把休市时的静态快照当作盘中信号解读。
49
51
 
50
- 场外公募基金净值查询使用 `get_fund_quote(symbol="018147")`,不要当作股票实时报价。`nav` 是 `nav_date` 对应的已披露日终净值而非实时价;`accumulated_nav` 为累计净值,`change_pct` 为日涨跌幅。`estimated_nav` 是估算值且可能为 `null`,缺失时不得编造或当作实时成交价;QDII 净值可能滞后 1-2 交易日,须披露实际 `nav_date`。`TIAAxxxxxx` 使用 `get_quote` 获取投顾组合识别与无统一净值提示,不推算组合净值。`advisor_code/advisor_org` 按 TIAA 前三位机构段与资本市场标准网基金投顾业务编码表进行 best-effort 映射,来源和抓取时间随结果返回;投顾机构不等于主理人,查不到时保留 null。`official_disclosures` 目前仅对确认属于有知有行的 `TIAA001001/TIAA001002/TIAA001004` 提供,其他 TIAA 组合不得套用该站文章;有搜索配置时可返回 `disclosure_status=search_partial` 和 `public_search_results`,其中每项均为 `verification=unverified_search_result`,只能作为待核实线索,否则为 `unsupported_provider`。官方披露含发布日期、摘要、正文摘录和 URL;`disclosures_partial=true` 时必须视为不完整历史披露,不能当作实时业绩或完整成分基金清单。示例账户收益不等于用户收益,引用基金代码时必须保留对应文章日期和链接。
52
+ 场外公募基金净值查询使用 `get_fund_quote(symbol="018147")`,不要当作股票实时报价。`nav` 是 `nav_date` 对应的已披露日终净值而非实时价;`accumulated_nav` 为累计净值,`change_pct` 为日涨跌幅。`estimated_nav` 目前恒为 `null`,缺失时不得编造或当作实时成交价;QDII 净值可能滞后 1-2 交易日,须披露实际 `nav_date`。`TIAAxxxxxx` 使用 `get_quote` 获取投顾组合识别与无统一净值提示,不推算组合净值。`advisor_code/advisor_org` 按 TIAA 前三位机构段与资本市场标准网基金投顾业务编码表进行 best-effort 映射,来源和抓取时间随结果返回;投顾机构不等于主理人,查不到时保留 null。`official_disclosures` 目前仅对确认属于有知有行的 `TIAA001001/TIAA001002/TIAA001004` 提供,其他 TIAA 组合不得套用该站文章;有搜索配置时可返回 `disclosure_status=search_partial` 和 `public_search_results`,其中每项均为 `verification=unverified_search_result`,只能作为待核实线索,否则为 `unsupported_provider`。官方披露含发布日期、摘要、正文摘录和 URL;`disclosures_partial=true` 时必须视为不完整历史披露,不能当作实时业绩或完整成分基金清单。示例账户收益不等于用户收益,引用基金代码时必须保留对应文章日期和链接。
51
53
 
52
54
  港股 `get_quote` 自动按 yfinance → 腾讯 → finnhub → longbridge 容灾,腾讯无需 API key,使用 `r_hk` 实时报价通道(`hk` 通道延迟约 15 分钟)。腾讯港股成交量为股,成交额及市值为港元;PB、换手率、量比为 null 时按缺失处理。腾讯也是港股 `get_kline` 的第二个源,以及美股报价和 K 线在 finnhub / longbridge 之后、alphavantage 之前的备用源;腾讯 K 线为前复权(`adjusted: "qfq"`),与 yfinance 的全收益口径不同。
53
55
 
@@ -125,6 +127,7 @@ python3 scripts/gather.py <symbol>
125
127
  - 财报季排期:`get_earnings_calendar(report_date="YYYY-MM-DD", symbol=...)`,区分最新预约日期、实际披露日期和已公告业绩预告,不把预告当业绩实绩。
126
128
  - 股东变化:`get_shareholder_structure`。A 股北向值是财报十大流通股东中的 HKSCC 名义持股,缺席不等于零,不能当成日度北向买卖;港股南向值按港交所披露日期使用。
127
129
  - 大盘估值:`get_index_valuation(symbol="000300", years=5)`;中证近期 PE1 不冒充 PE-TTM、PB 或多年分位。
130
+ - 信用风险偏好:`get_cds_index` 返回市场级 CDS 指数的窗口变化与分位,只作行业/大盘背景;不是个股 CDS,不能单独推出个股方向。按标的只取一个最贴近的指数和期限(如 `index="民企", tenor="1Y"`),不要无过滤拉全部:A 股民营企业用民企,央国企/高评级用高等级,科创板/硬科技用科创,长三角企业用长三角,新能源/环保用碳中和;美股投资级公司用 `source="global", index="CDX.NA.IG"`,高收益/高杠杆用 `CDX.NA.HY`(价格,下跌表示信用走弱),欧洲公司用 `ITRAXX EUROPE` 或 `CROSSOVER`。对应关系是代理,报告时说明。
128
131
  - ETF:`get_etf_details(symbol="510300", benchmark="sh000300")`。折溢价须看净值/行情日期;披露持仓不是完整实时申赎篮子,指数成分与基金持仓分别呈现。跟踪误差必须给出用户认可的基准。
129
132
  - 股息:`get_dividends` 区分历史、未来已公布除息日历和排行;history/calendar 支持 A/HK/US/JP/KR/TW,排行仍仅 A/HK。预案不计入已实现 TTM 股息。名义每股现金未重算送转股口径,遇送转股时不得据此精确比较持有收益。
130
133
  - 两融:`get_margin_trading(include_ratio=true)` 的 `margin_buy_ratio_pct` 只使用同日成交额;null 表示不可计算。
@@ -7,7 +7,7 @@ description: 全市场股票筛选:按市场、估值、成长、趋势或自
7
7
 
8
8
  批量研究、子任务分工或报告文件交付时,必须读取[宿主研究与报告交付](../stock-analysis/references/host-workflows.md),使用当前宿主实际提供的能力。
9
9
 
10
- 显式筛选条件缺少数据时工具返回 `error`,不能把该条件当作已通过。`filters_applied` 只包含实际执行的条件,基于返回的覆盖情况说明候选范围。
10
+ 显式筛选条件缺少数据时工具返回 `error`,不能把该条件当作已通过。工具只取市值不低于 `market_cap_min` 的股票(按市值从大到小,最多 3000 只),结果带 `warnings` 提示截断时须说明候选范围不完整。`filters_applied` 只包含实际执行的条件,基于返回的覆盖情况说明候选范围。
11
11
 
12
12
  ## 执行流程
13
13
 
@@ -103,7 +103,7 @@ python3 tools/backtest.py run <path.yaml> <symbol> --start <date> --end <date>
103
103
  - 使用用户指定的互斥日期区间分别运行样本内和样本外回测。
104
104
  - 成本假设引用结果中的 `costs` 字段(实际生效的佣金/滑点/印花税费率与实付费用合计),未模拟的费用与成交约束列入限制。
105
105
 
106
- 趋势策略或用户要求肥尾收益诊断时,读取 [肥尾度量与趋势收益诊断](../bull-trend/references/fat-tails.md)的盈利集中度部分,基于平仓 `pnl` 计算大赢家贡献和删除敏感性。只有用户询问市场收益分布时才进入 κ 分支。
106
+ 趋势策略或用户要求肥尾收益诊断时,读取 [肥尾、非对称风险与趋势收益诊断](../bull-trend/references/fat-tails.md)的盈利集中度部分,基于平仓 `pnl` 计算大赢家贡献和删除敏感性。只有用户询问市场收益分布时才进入 κ 分支。
107
107
 
108
108
  未模拟的结算、涨跌停、复权或特定市场费用列入限制,结论限定为该模拟条件下的历史表现。
109
109
 
@@ -42,6 +42,7 @@ TOOL_MATRIX = {
42
42
  "get_insider_trades": {"markets": ["US"], "reason": "SEC issuer Form 4 only"},
43
43
  "get_valuation_history": {"markets": ["A", "HK", "US"], "reason": "A/HK providers; US derived from SEC filings"},
44
44
  "get_index_valuation": {"markets": ["A"], "reason": "Chinese index valuation only"},
45
+ "get_cds_index": {"markets": ["A", "US"], "reason": "Market-level CN onshore CDS indices / CDX-iTraxx only"},
45
46
  "get_earnings_calendar": {
46
47
  "markets": ["A", "HK", "US", "JP"],
47
48
  "reason": "A-share disclosed calendar / HK/US/JP single-symbol provider schedule",
@@ -9,7 +9,6 @@
9
9
  "risk_screening.py:screen": 450,
10
10
  "signal_tracker.py:evaluate": 300,
11
11
  "stock_data.py:market_stats": 240,
12
- "name_resolver.py:resolve": 360,
13
12
  "import_parser.py:parse": 360,
14
13
  "market_review.py:review": 300,
15
14
  "anomaly_detect.py:detect": 390,