stock-analysis-plugin 0.2.11 → 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.
Files changed (54) hide show
  1. package/README.md +234 -382
  2. package/docs/mcp.md +60 -0
  3. package/hermes/__init__.py +35 -0
  4. package/hermes/plugin.yaml +132 -0
  5. package/hermes/schemas.py +6 -0
  6. package/hermes/tools.py +647 -0
  7. package/mcp_host/__init__.py +1 -0
  8. package/mcp_host/__main__.py +3 -0
  9. package/mcp_host/server.py +222 -0
  10. package/package.json +7 -1
  11. package/pi/index.ts +52 -2906
  12. package/scripts/cli-json.mjs +23 -0
  13. package/scripts/exec-process.mjs +89 -0
  14. package/scripts/setup-python.mjs +37 -4
  15. package/scripts/tool-calls.mjs +493 -0
  16. package/skills/bull-trend/SKILL.md +2 -2
  17. package/skills/bull-trend/references/fat-tails.md +76 -3
  18. package/skills/bull-trend/scripts/tail_analysis.py +92 -3
  19. package/skills/event-driven/SKILL.md +2 -2
  20. package/skills/growth-quality/SKILL.md +1 -1
  21. package/skills/market-review/SKILL.md +1 -0
  22. package/skills/stock-analysis/SKILL.md +12 -7
  23. package/skills/stock-analysis/references/stateless-analysis.md +9 -1
  24. package/skills/stock-screener/SKILL.md +1 -1
  25. package/skills/strategy-backtest/SKILL.md +1 -1
  26. package/tools/_cache.py +13 -0
  27. package/tools/_subproc.py +46 -0
  28. package/tools/alert_rules.py +2 -2
  29. package/tools/backtest.py +3 -3
  30. package/tools/capabilities.py +33 -9
  31. package/tools/cli_budgets.json +1 -0
  32. package/tools/credit_data.py +293 -0
  33. package/tools/diagnostics.py +3 -4
  34. package/tools/gather.py +2 -6
  35. package/tools/import_parser.py +3 -4
  36. package/tools/lixinger.py +119 -27
  37. package/tools/market_regime.py +5 -2
  38. package/tools/market_review.py +5 -6
  39. package/tools/name_resolver.py +45 -33
  40. package/tools/report_renderer.py +3 -3
  41. package/tools/requirements.txt +5 -4
  42. package/tools/risk_screening.py +3 -2
  43. package/tools/screener.py +41 -30
  44. package/tools/search_intel.py +79 -10
  45. package/tools/sec_edgar.py +268 -1
  46. package/tools/sec_holders.py +6 -0
  47. package/tools/signal_tracker.py +5 -5
  48. package/tools/stateless_analysis.py +132 -19
  49. package/tools/stock_data.py +1020 -817
  50. package/tools/tiaa_disclosures.py +4 -0
  51. package/tools/tool_schemas.json +2734 -0
  52. package/tools/trading_calendar.py +65 -30
  53. package/tools/value_data.py +423 -175
  54. package/tools/watchlist.py +43 -5
@@ -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:
@@ -28,7 +28,7 @@ gather 工具返回:
28
28
  - `stock_info` — 公司基本信息
29
29
  - `sector_rankings` — 板块排名
30
30
 
31
- A 股事件原文先调用 `get_announcements`:业绩预告用 `forecast`、快报用 `express`、减持用 `reduction`、增发用 `issuance`、问询及回复用 `inquiry`、分红用 `dividend`,指定 `start_date/end_date`。返回 PDF 链接而非正文;读取原文后再量化,`truncated=true` 时缩小日期范围。
31
+ 事件原文先调用 `get_announcements`:A 股业绩预告用 `forecast`、快报用 `express`、减持用 `reduction`、增发用 `issuance`、问询及回复用 `inquiry`、分红用 `dividend`;港股用 HKEXnews,支持 `all/forecast/annual/interim/quarterly/issuance/dividend`;美股用 SEC 申报(`all` 含 8-K/6-K/DEF 14A,需 SEC_USER_AGENT),不支持的类别会报错。指定 `start_date/end_date`;PDF/HTML 原文用 `extract_article` 提取并检查 `truncated`,读取后再量化,列表截断时缩小日期范围。
32
32
 
33
33
  新闻摘要只用于发现事件。金额、期限、合同对手、业绩变化或政策原文必须由公告/原文确认;只有摘要时不做精确量化。
34
34
 
@@ -100,4 +100,4 @@ A 股事件原文先调用 `get_announcements`:业绩预告用 `forecast`、
100
100
 
101
101
  ### 补充数据覆盖
102
102
 
103
- get_earnings_calendar 查询 A 股仍需 report_date;HK 提供 symbol,可选财政期末 report_date;优先 HKEX 已公告业绩审批董事会排期 confirmation=official_board_meeting_notice、date_kind=scheduled_board_meeting,不能称实际披露日。供应商备选日期为 provider_only,未知期次在请求特定报告期时另列 unverified_schedules,不能强行匹配。
103
+ get_earnings_calendar 查询 A 股仍需 report_date;HK 提供 symbol,可选财政期末 report_date;优先 HKEX 已公告业绩审批董事会排期 confirmation=official_board_meeting_notice、date_kind=scheduled_board_meeting,不能称实际披露日。US/JP 提供 symbol,日期来自 yfinance、confirmation=provider_only,非官方确认;KR/TW 不可用。未知期次在请求特定报告期时另列 unverified_schedules,不能强行匹配。
@@ -26,7 +26,7 @@ gather 工具返回:
26
26
  - `stock_info` — 公司基本信息(行业、板块)
27
27
  - `sector_rankings` — 板块排名
28
28
 
29
- 需要财务趋势时调用 `get_financials(symbol, annual=true, periods=10)`。港股配置 `LIXINGER_TOKEN` 后优先理杏仁非金融公司财报,按真实 `report_type` 判断年报,保留实际财年末、披露日期、币种;历史 ROE/毛利率/净利率为百分数,顶层 `roe/profit_margin` 延续小数比例。读取 `available_periods/warnings`,缺期不补造。有效 Yahoo 顶层快照与历史行分开读:`currency` 为快照财报币种、`market_cap_currency` 为市值币种,历史币种在 `periods` 每行,`snapshot_source` 标记快照来源;null 不用历史值补成跨期或跨币种数字;顶层 `report_date` 未知时读取 `periods` 的历史日期,不当作当前快照报告期。
29
+ 需要财务趋势时调用 `get_financials(symbol, annual=true, periods=10)`。港股配置 `LIXINGER_TOKEN` 后优先理杏仁非金融公司财报,按真实 `report_type` 判断年报,保留实际财年末、披露日期、币种;历史 ROE/毛利率/净利率为百分数,顶层 `roe/profit_margin` 延续小数比例。读取 `available_periods/warnings`,缺期不补造。A/港/美股需要 DCF 输入时追加 `include_dcf_inputs=true`,读取 `dcf_inputs.source/periods/warnings`,每行 `field_sources` 标明字段来源、`missing_fields` 列出仍缺字段;`total_debt` 不含租赁,`lease_liabilities` 单列,按估值口径决定是否计入债务。有效 Yahoo 顶层快照与历史行分开读:`currency` 为快照财报币种、`market_cap_currency` 为市值币种,历史币种在 `periods` 每行,`snapshot_source` 标记快照来源;null 不用历史值补成跨期或跨币种数字;顶层 `report_date` 未知时读取 `periods` 的历史日期,不当作当前快照报告期。
30
30
 
31
31
  Yahoo 顶层快照单位以 `snapshot_units` 为准:`roe/profit_margin/dividend_yield=ratio`,`debt_to_equity=percent`,例如 150 表示 150%,不是 150 倍;`pe=trailing`,不与 dynamic PE 直接比较。
32
32
 
@@ -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
 
@@ -17,7 +17,7 @@ description: 综合股票分析:联合技术、基本面、资金、消息和
17
17
 
18
18
  ## 无状态分析扩展
19
19
 
20
- 当用户要求同行比较、组合风险/压力测试、目标权重调仓、仓位预算或新旧分析比较时,MUST 读取[无状态研究工具](references/stateless-analysis.md),分别使用 compare_stocks、analyze_portfolio_risk、plan_portfolio_rebalance、calculate_position_size、compare_analysis_snapshots。所有用户状态均由本次输入提供;调仓计划数量不等于成交,现金不足或整手差额必须读取 unfilled 说明。
20
+ 当用户要求同行比较、组合风险/压力测试、目标权重调仓、仓位预算、DCF 估值或新旧分析比较时,MUST 读取[无状态研究工具](references/stateless-analysis.md),分别使用 compare_stocks、analyze_portfolio_risk、plan_portfolio_rebalance、calculate_position_size、calculate_dcf_valuation、compare_analysis_snapshots。所有用户状态均由本次输入提供;调仓计划数量不等于成交,现金不足或整手差额必须读取 unfilled 说明。
21
21
 
22
22
  ## 意图路由表
23
23
 
@@ -25,13 +25,15 @@ 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 给出可观察触发条件 |
31
33
  | 个股状态速览 | `get_quote` + `get_technical_analysis` |
32
34
  | 场外公募基金净值 | `get_fund_quote`(6 位基金代码,如 018147) |
33
35
  | 异动归因 | `detect_anomaly` + `get_news` |
34
- | 大盘择时 | `detect_market_regime`;A 股可补充 `get_market_stats` |
36
+ | 大盘择时 | `detect_market_regime`;可补充 `get_market_stats(market)` 看涨跌家数,美股行业强弱用 `get_sector_rankings(market=US)`(ETF 代理) |
35
37
 
36
38
  ## 执行流程
37
39
 
@@ -43,13 +45,13 @@ description: 综合股票分析:联合技术、基本面、资金、消息和
43
45
  python3 scripts/gather.py <symbol>
44
46
  ```
45
47
 
46
- 解析返回的 JSON 数据。如果某个字段为 `null` 或包含 `error`,表示该数据不可用,基于可用数据继续分析。大盘状态按股票所属市场查询;日/韩/台市场暂不支持,标明缺失,不能套用 A 股状态。
48
+ 解析返回的 JSON 数据。如果某个字段为 `null` 或包含 `error`,表示该数据不可用,基于可用数据继续分析。大盘状态按股票所属市场查询,A/HK/US/JP/KR/TW 均使用各自指数;非 A 股板块热点不可用时 sector_heat=false,不能套用 A 股状态或把 false 解读成无热点。
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
- 港股 `get_quote` 自动按 yfinance → 腾讯 → finnhub → longbridge 容灾,腾讯无需 API key,使用 `r_hk` 实时报价通道(`hk` 通道延迟约 15 分钟)。腾讯港股成交量为股,成交额及市值为港元;PB、换手率、量比为 null 时按缺失处理。该备用源只覆盖报价,K 线仍走原链路。
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
 
54
56
  ### 第二步:综合研判
55
57
 
@@ -120,13 +122,14 @@ python3 scripts/gather.py <symbol>
120
122
 
121
123
  按用户问题选择数据,完整说明口径、采样覆盖和缺失项:
122
124
 
123
- - 判断估值贵贱:`get_valuation_history(symbol, years=5)` 的 PE-TTM/PB 历史正值分位与 Band;亏损 PE 不计算分位,实际采样不足五年必须说明。
125
+ - 判断估值贵贱:`get_valuation_history(symbol, years=5)` 的 PE-TTM/PB 历史正值分位与 Band;亏损 PE 不计算分位,实际采样不足五年必须说明;美股为 SEC 申报派生的周采样,读取 `share_basis/warnings`。
124
126
  - 读多年财报:`get_financials(symbol, periods=10, annual=true)`;A 股按年报筛选,港股按源实际可得年度数返回。财报期不等于公告日,年报历史不能用于假定当时已知信息的回测。
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
- - 股息:`get_dividends` 区分历史、未来已公布除息日历和 A 股报告期排行;预案不计入已实现 TTM 股息。名义每股现金未重算送转股口径,遇送转股时不得据此精确比较持有收益。
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 表示不可计算。
131
134
 
132
135
  慢变数据存于 `~/.stock-analysis/cache`:财报、基本信息及新历史数据按天,板块映射按周;行情仍实时查询。输出中的报告期/数据日期决定能否用于判断,缓存命中不代表数据已更新。
@@ -139,4 +142,6 @@ get_shareholder_structure 的 northbound 优先使用沪深官方季度总量;
139
142
 
140
143
  信号价格使用原始报价口径,自动记录的默认 `record_date` 与 `price_date` 均按标的市场时区确定(显式 `date` 不变),并保存原始 `price_as_of`;`price_date` 晚于 `record_date` 时拒绝记录与结算。多头 target 必须高于 entry、stop 必须低于 entry,空头相反,否则拒绝记录。开盘先触 stop 按 open 结算,先触 target 按 target 保守结算;日内顺序未知的双触发仍 stop 优先。复权 K 线需有该报价日的可核实 adjustment_factor,才能换算入场/目标/止损及收益;缺失时 skipped_price_basis 并保持未结算,不得猜测拆股或除权比例,重复日期返回 skipped_no_data。记录日无 K 线时仅在前后因子一致(或已有明确报价日)时使用最近锚点;旧信号缺少报价时点且记录日因子发生变化时必须保持未结算。evaluate_signals 返回 complete/deferred/warnings;预算耗尽时已完成结果保存,未处理记录下次重试。当前仅日线 Tushare、Alpha Vantage 提供可验证换算系数,其余复权来源可能跳过结算。
141
144
 
145
+ 用户说“我的自选股”且未提供代码时,先调用 get_watchlist 读取 dsh 侧栏列表,再把 symbols 传给 run_watchlist_analysis 或 build_watchlist_context;空列表要如实说明,不自行补股票池。
146
+
142
147
  自选股上下文异动检查失败时 anomaly_status=unavailable、anomaly_count=null,并提供 anomaly_error/warnings;summary.partial 不得写成无异常或完整成功。
@@ -13,7 +13,7 @@
13
13
 
14
14
  传 `previous/current`,每项 `{text, source, period, metrics}`;正文上限200000字符,metrics 形状同上(可为空),`max_changes` 默认30、上限100。
15
15
 
16
- 先查询原始公告;HTML 可用 extract_article,但它默认截断正文,不能将其结果自动视为全文。PDF/OCR 由宿主文档读取能力或用户提供,MUST NOT 把标题、链接或搜索摘要冒充全文。缺少正文时仍可分析已核实的财务指标,但不要调用要求正文的比较工具。
16
+ 先查询原始公告;HTML/PDF 可用 extract_article,默认3000字符。用于披露比较时按所需正文设置 max_chars(上限200000)并检查 truncated;truncated=true 不能当作全文。无文本层的 PDF 仍需宿主 OCR 或用户提供,MUST NOT 把标题、链接或搜索摘要冒充全文。缺少正文时仍可分析已核实的财务指标,但不要调用要求正文的比较工具。
17
17
 
18
18
  工具输出精确到传入文本行号的变化片段、来源、截断标志和指标差异。文本差异本身不等于经营变化;Agent 要阅读上下文,说明发生了什么、与原预期的关系和可能反证,并引用原文。金额单位和 basis 一致才计算 delta;前期值大于0才计算普通增长率,亏损转盈另述。报告期可不同,但必须核实是可比同长期间(年度/同比单季等),累计季度不能直接当单季。
19
19
 
@@ -49,6 +49,14 @@
49
49
 
50
50
  lot_size 来自用户或可核实交易规则,尤其港股不能统一猜100股。工具不覆盖券商最低收费、未提供税费、跳空和流动性风险。quantity=0 表示当前约束下不足一个交易单位,MUST NOT 向上凑整。
51
51
 
52
+ ## DCF 估值:calculate_dcf_valuation
53
+
54
+ A/港/美股可先调用 `get_financials(symbol, annual=true, periods=5, include_dcf_inputs=true)` 取年度收入、营业利润、税、现金流、资本开支、现金、债务、少数股东权益和股本。美股优先 SEC companyfacts,A 股和港股配置 `LIXINGER_TOKEN` 时优先理杏仁;主源缺失字段按同财年同币种用 Yahoo 补齐(租赁口径不同,不跨源补),并在 `field_sources` 标注。A 股 `operating_income` 是营业利润(含投资收益和公允价值变动),不等于 EBIT,用作经营利润率前需剔除。仍缺的字段列在 `missing_fields` 且为 null,MUST 向用户索取或另行核实,不能补默认值。`total_debt` 不含租赁;租赁负债在 `lease_liabilities`,是否计入 `debt` 由调用方明确。传给 `calculate_dcf_valuation` 时 `minority_interest` 对应 `minority_interests`,`total_debt`(加上选定的租赁)对应 `debt`。
55
+
56
+ 必需 `currency,units,base_revenue,revenue_growth,operating_margin,tax_rate,sales_to_capital,wacc,terminal_growth,terminal_wacc,terminal_roic,diluted_shares`。逐年数组长度相同且为1..10年;比例均为小数。可选 `cash,debt,minority_interests,nonoperating_assets,other_claims,current_price`。所有金额和股数口径一致。
57
+
58
+ 工具按达摩达兰 FCFF 口径计算:税后营业利润减去收入增量/销售资本比得到FCFF,终值再投资率为 `terminal_growth/terminal_roic`。输出企业价值、股权价值、每股价值、终值占比和 3x3 终值 WACC/增长敏感性。它不估计 WACC、ERP、国家风险、β或行业销售资本比,也不处理期权、租赁、金融企业和失败概率。结果是假设驱动估值,MUST NOT 当作买卖信号。
59
+
52
60
  ## 事件研究:analyze_event_study
53
61
 
54
62
  通常直接传 `symbol,benchmark,start_date,end_date,event_dates`,由共享 Python 核心取数,避免模型复述整段K线。股票与基准应属于同一市场;代码模式输出实际覆盖区间和提供方复权标记,没有标记时明确未指定,不用调用方猜测覆盖。开始日期须覆盖事件前一交易日、结束日期须覆盖最长事件窗口。也可使用下面的显式价格模式,两种模式互斥。
@@ -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
 
package/tools/_cache.py CHANGED
@@ -36,6 +36,16 @@ def cached_values(namespace, ttl):
36
36
  yield entry.get("data")
37
37
 
38
38
 
39
+ def _prune(path, ttl):
40
+ """Drop expired siblings of a fresh entry so date-scoped keys cannot grow the cache forever."""
41
+ cutoff = time.time() - ttl
42
+ for old in CACHE_DIR.glob(f"{path.name.split('-', 1)[0]}-*"):
43
+ if old.stem != path.stem and old.suffix in (".json", ".lock"):
44
+ with contextlib.suppress(OSError):
45
+ if old.stat().st_mtime < cutoff:
46
+ old.unlink()
47
+
48
+
39
49
  @contextlib.contextmanager
40
50
  def file_lock(path, timeout=5):
41
51
  """Coordinate processes using a stable lock inode, with bounded waiting."""
@@ -116,6 +126,8 @@ def cached(key: str, ttl: int, fetch):
116
126
  # shortcut: slow fetches may outlast lock wait; prefer duplicate work to blocking callers indefinitely.
117
127
  with contextlib.suppress(OSError):
118
128
  stack.enter_context(file_lock(path.with_suffix(".lock")))
129
+ # A held lock must look fresh so another key's prune never unlinks it mid-fetch.
130
+ os.utime(path.with_suffix(".lock"))
119
131
  entry = _read(path, ttl)
120
132
  if entry and "data" in entry:
121
133
  return entry["data"]
@@ -128,6 +140,7 @@ def cached(key: str, ttl: int, fetch):
128
140
  json.dump(
129
141
  {"key": key, "fetched_at": time.time(), "data": result}, stream, ensure_ascii=False, allow_nan=False
130
142
  )
143
+ _prune(path, ttl)
131
144
  except (OSError, ValueError, TypeError):
132
145
  pass
133
146
  return result
package/tools/_subproc.py CHANGED
@@ -11,6 +11,7 @@ import json
11
11
  import math
12
12
  import os
13
13
  import re
14
+ import signal
14
15
  import socket
15
16
  import subprocess
16
17
  import sys
@@ -64,6 +65,45 @@ def find_python() -> str:
64
65
  return venv if os.path.exists(venv) else sys.executable
65
66
 
66
67
 
68
+ # A CLI that calls sibling CLIs must die with them: each child leads its own process group.
69
+ TREE_POPEN = (
70
+ {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP} if sys.platform == "win32" else {"start_new_session": True}
71
+ )
72
+
73
+
74
+ def terminate_tree(proc) -> None:
75
+ """Kill a TREE_POPEN child and every process it started."""
76
+ if sys.platform == "win32":
77
+ try:
78
+ subprocess.run(
79
+ ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
80
+ stdin=subprocess.DEVNULL,
81
+ stdout=subprocess.DEVNULL,
82
+ stderr=subprocess.DEVNULL,
83
+ timeout=10,
84
+ check=False,
85
+ )
86
+ except (OSError, subprocess.TimeoutExpired):
87
+ proc.kill()
88
+ else:
89
+ with contextlib.suppress(ProcessLookupError, PermissionError):
90
+ os.killpg(proc.pid, signal.SIGKILL)
91
+
92
+
93
+ def run_tree(cmd: list, *, timeout: float) -> subprocess.CompletedProcess:
94
+ """subprocess.run(capture_output, text) whose timeout also kills grandchildren."""
95
+ with subprocess.Popen(
96
+ cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, encoding="utf-8", **TREE_POPEN
97
+ ) as proc:
98
+ try:
99
+ stdout, stderr = proc.communicate(timeout=timeout)
100
+ except BaseException: # timeout or Ctrl+C: the new session no longer receives terminal signals
101
+ terminate_tree(proc)
102
+ proc.communicate()
103
+ raise
104
+ return subprocess.CompletedProcess(cmd, proc.returncode, stdout, stderr)
105
+
106
+
67
107
  def run_tool(
68
108
  script: str, args: list, timeout: int | None = None, parse_json: bool = True, preserve_errors: bool = False
69
109
  ):
@@ -79,6 +119,7 @@ def run_tool(
79
119
  return payload if parse_json else json.dumps(payload, ensure_ascii=False)
80
120
 
81
121
  try:
122
+ # Not run_tree: a nested CLI must stay in the caller's process group so the host's tree kill reaches it.
82
123
  r = subprocess.run(
83
124
  [find_python(), os.path.join(TOOLS_DIR, script), *args],
84
125
  capture_output=True,
@@ -172,6 +213,11 @@ def scrub_secrets(msg: str) -> str:
172
213
  return _SECRET_PARAM_RE.sub(r"\1***", msg)
173
214
 
174
215
 
216
+ def error_message(exc: BaseException, limit: int = 300) -> str:
217
+ """Exception text for stdout JSON: secrets scrubbed, provider bodies bounded."""
218
+ return scrub_secrets(str(exc))[:limit]
219
+
220
+
175
221
  def json_safe(obj):
176
222
  """Replace non-finite floats (inf/-inf/nan, e.g. an all-flat P&L profit_loss_ratio)
177
223
  with None so json.dumps never emits the non-standard Infinity/NaN tokens that
@@ -13,8 +13,8 @@ from datetime import datetime, timezone
13
13
  from pathlib import Path
14
14
 
15
15
  sys.path.insert(0, str(Path(__file__).resolve().parent))
16
+ from _subproc import error_message, utf8_stdio
16
17
  from _subproc import run_tool as _run_json # noqa: E402
17
- from _subproc import utf8_stdio
18
18
  from stock_data import detect_market # noqa: E402
19
19
 
20
20
  RULE_TYPES = {
@@ -283,7 +283,7 @@ def main():
283
283
  try:
284
284
  rules = json.loads(raw)
285
285
  except json.JSONDecodeError as e:
286
- print(json.dumps({"error": f"invalid rules JSON: {e}"}, ensure_ascii=False))
286
+ print(json.dumps({"error": f"invalid rules JSON: {error_message(e)}"}, ensure_ascii=False))
287
287
  sys.exit(1)
288
288
 
289
289
  result = check_rules(args.symbol, rules)
package/tools/backtest.py CHANGED
@@ -15,7 +15,7 @@ import yaml
15
15
 
16
16
  sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
17
17
 
18
- from _subproc import json_safe, run_tool, utf8_stdio
18
+ from _subproc import error_message, json_safe, run_tool, utf8_stdio
19
19
  from stock_data import detect_market
20
20
  from technical import (
21
21
  bollinger_series,
@@ -894,7 +894,7 @@ def _benchmark_comparison(
894
894
  df = fetch_kline(symbol, start, end)
895
895
  _validate_adjustment_basis(df)
896
896
  except Exception as e:
897
- return {"symbol": symbol, "error": str(e)}
897
+ return {"symbol": symbol, "error": error_message(e)}
898
898
  if len(df) < 2:
899
899
  return {"symbol": symbol, "error": f"Insufficient benchmark data: {len(df)} rows"}
900
900
  dates = pd.to_datetime(df["date"], errors="coerce")
@@ -1128,7 +1128,7 @@ def main():
1128
1128
  result = {"error": f"Unknown command: {args.command}"}
1129
1129
  except Exception as e:
1130
1130
  # A traceback would leave stdout empty; hosts need valid JSON even on failure.
1131
- print(json.dumps({"error": str(e)}, ensure_ascii=False))
1131
+ print(json.dumps({"error": error_message(e)}, ensure_ascii=False))
1132
1132
  sys.exit(1)
1133
1133
 
1134
1134
  print(json.dumps(json_safe(result), ensure_ascii=False, default=str))