@weaxs/openclaw-stock-analysis 0.2.6 → 0.2.8

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 (38) hide show
  1. package/README.md +1 -1
  2. package/dist/index.js +284 -19
  3. package/index.ts +214 -12
  4. package/openclaw.plugin.json +9 -1
  5. package/package.json +1 -1
  6. package/schemas/market_review_schema.json +12 -5
  7. package/schemas/report_schema.json +65 -1
  8. package/scripts/cli-timeout.mjs +27 -0
  9. package/scripts/json-input.mjs +26 -0
  10. package/skills/bull-trend/SKILL.md +11 -1
  11. package/skills/bull-trend/references/monthly-trend-strategy.md +47 -0
  12. package/skills/bull-trend/references/trend-horizons.md +43 -0
  13. package/skills/bull-trend/references/trend-temperature.md +57 -0
  14. package/skills/bull-trend/scripts/market_trend.py +78 -0
  15. package/skills/event-driven/SKILL.md +4 -0
  16. package/skills/growth-quality/SKILL.md +4 -0
  17. package/skills/market-review/SKILL.md +2 -0
  18. package/skills/stock-analysis/SKILL.md +17 -3
  19. package/skills/stock-analysis/references/stateless-analysis.md +66 -0
  20. package/skills/stock-screener/SKILL.md +5 -1
  21. package/skills/strategy-backtest/SKILL.md +19 -0
  22. package/templates/market_review/full.md.j2 +7 -0
  23. package/templates/stock_analysis/_evidence.md.j2 +11 -0
  24. package/templates/stock_analysis/brief.md.j2 +2 -0
  25. package/templates/stock_analysis/full.md.j2 +2 -0
  26. package/tools/_subproc.py +66 -11
  27. package/tools/backtest.py +143 -19
  28. package/tools/capabilities.py +12 -0
  29. package/tools/cli_budgets.json +27 -0
  30. package/tools/gather.py +4 -6
  31. package/tools/market_review.py +30 -9
  32. package/tools/screener.py +57 -15
  33. package/tools/signal_tracker.py +77 -6
  34. package/tools/stateless_analysis.py +630 -0
  35. package/tools/stock_data.py +90 -15
  36. package/tools/technical.py +186 -0
  37. package/tools/trend_strategy.py +365 -0
  38. package/tools/watchlist_context.py +18 -7
@@ -0,0 +1,43 @@
1
+ # 多期限趋势
2
+
3
+ 通过现有get_technical_analysis请求daily、count=360,读取trend_horizons。模型用21/63/252根日K约代表1/3/12个月,不强凑七档标签,不是星球公式或肥尾预测。
4
+
5
+ ## 计算与解释
6
+
7
+ 每期限过去对数收益为 log(close_t)-log(close_(t-h))。每个月第一根可见、正成交量日K的收盘形成观察,其后保持到下个月首根有效日K收盘。未提供volume时只能沿输入记录观察;提供volume时零成交量记录不计回溯根数。观察K线必须已收盘,任何研究成交使用之后的开盘。
8
+
9
+ components逐一返回period与log_return,positive_count/negative_count/neutral_count统计三期限方向;至少2个为正/负则direction为up/down,全部零为flat,其他为mixed。它们是已发生路径的描述,MUST NOT 解释为独立投票概率、未来涨跌概率或自动配置比例。相关期限不能当作独立样本。
10
+
11
+ 仅支持daily输入。最长需在月度观察时已有253根有效收盘;最新已有253根而当月首根尚不足时仍不可用,不能用最新日重新计算冒充月度观察。建议请求360根,报告实际history_start、as_of、decision_as_of及price_basis。数据不足、混用调整标记或坏日期必须报告unavailable_reason,不伪造中性。多周期摘要保留整个trend_horizons,周/月K返回requires_daily_bars。
12
+
13
+ 当前validation_status=not_validated。旧trend_temperature为兼容的EMA/ATR研究描述;不再将它的七档视为默认趋势模型。新字段也不能覆盖原综合评分或买卖信号。
14
+
15
+ ## 回测与证据边界
16
+
17
+ DSL指标monthly_momentum复用相同Python计算,period默认63。它是单期限信号。三期限研究组合从相同起点分别给初始资金三分之一,独立留存盈亏、权重漂移,并没有每月等权再平衡;并行买卖分别计费,没有跨子账户净额撮合。研究另外拟合了一个跨市场共用的初始活跃资金比例0.8704,剩余现金不动;这是2022–2025研究集风险拟合结果,MUST NOT 作为用户账户默认仓位。
18
+
19
+ 新12股复核:A/HK路径回报较旧规则提高,美股回报接近、回撤较小;但港股最大回撤恶化约6.1个百分点,未通过预设5个百分点门槛。因此没有建立跨市场统一优势,MUST NOT 称为已验证策略。A股研究用了供应商AdjClose因子OHLC,不等于完整投资者总回报;产品A股输入通常仍为qfq,不能直接照搬该收益。
20
+
21
+ 原核心固定止损/止盈默认值不变;省略配置不代表禁用。单份普通YAML回测不会自动复制三子策略和预热协议。
22
+
23
+ 研究背景:[Hurst/Ooi/Pedersen原文](https://www.aqr.com/-/media/AQR/Documents/Insights/Journal-Article/AQR-JPM-Fall-2017.pdf)讨论1/3/12个月趋势组合。本实现的个股多头、月初观察、正成交量过滤、资金漂移和风险拟合均为本项目假设,不是论文复现或七档背书。
24
+
25
+ ## 市场环境入场实验
26
+
27
+ 需复现“市场只限制新开仓”的研究时,使用同一skill的 `scripts/market_trend.py`,无需新增宿主工具或个人持仓数据库。输入是两份已取得的daily OHLCV JSON数组(个股、同市场宽基),包含date/open/high/low/close/volume;调整口径须在各自序列内一致。market-symbol标识调用者提供的市场输入,不自动下载或验证标的归属。研究代理固定A510300、HK2800.HK、US SPY;自换代理属于另一项实验。
28
+
29
+ ```bash
30
+ python3 scripts/market_trend.py stock-daily.json market-daily.json \
31
+ --symbol AAPL --market-symbol SPY --start 2022-01-01 --end 2025-12-31 \
32
+ --capital 10000000 --allocation 0.8704
33
+ ```
34
+
35
+ 两份输入必须含评估开始之前的预热历史:个股最长252根过去收益在观察时需253根有效收盘,市场SMA200需200根。预热只计算指标,不建立虚拟持仓或产生收益。起点前最后有效收盘,以已知月度个股方向和当日市场条件初始化空仓目标;之后只在月度观察给出新开仓许可,次日有效开盘执行。市场close>SMA200允许新的月度正动量子策略进入;弱市不强制退出已持仓,个股月度动量<0仍退出。待买订单遇到下月许可失效会取消,不能冒充已持仓豁免。
36
+
37
+ 脚本默认allocation=1,0.8704只为显式复现前轮研究,不是账户建议。21/63/252初始各分三份、按分向下取整,余款留现金,利润各自保留而非每月等权重置。费用固定佣金/滑点各每边0.1%,税与现金利息0;输出明确参数、资金、评估开始/预热开始、交易、净值和指标。采用本地JSON输入,不保存个人仓位、不下单。普通 `run_backtest` 的单份YAML不会自动执行这个三子策略或抓市场预热;不要冒充二者完全相同。
38
+
39
+ 当前方法尚未通过完整跨市场效果门槛,`validation_status=not_validated`。MUST NOT 将局部样本上涨或相对旧模型改善称为稳定的跨市场交易优势。
40
+
41
+ ## 温度状态与切换事件
42
+
43
+ 解读星球信号或设计入场协议时,MUST 区分当前状态和新发生的切换事件:“今天仍热”不等于“今天温转热”。当前月度方向策略按状态选股,不是官方事件策略。事件协议须明确可得时间、有效期限和重复事件加仓条件;无合格新事件时,卖出所得留在现金。预热不产生新事件或虚拟持仓。外部同名温度的计算公式未公开,不能将成员筛选条件或自述收益作为官方规则或验证结果。
@@ -0,0 +1,57 @@
1
+ # 独立趋势温度
2
+
3
+ 用于用户要求计算趋势温度、寒凉温热状态或复核趋势强度时。调用现有 `get_technical_analysis`,读取 `trend_temperature`;skill 的采集脚本也会在 `technical.trend_temperature` 返回同一结果。无需配置外部温度接口,不保存个人持仓。
4
+
5
+ ## 来源与定位
6
+
7
+ 这是本项目可重复计算的研究基线,`experimental=true`。它不是趋势动物算法,不是塔勒布肥尾指标,也不是原有 100 分综合评分或复盘市场温度。连续分数描述均线相对真实波幅的分离;七档是未经收益校准的显示假设。MUST 同时报告模型、周期、分数、数据日期及实验性质,MUST NOT 将其称为上涨概率、已验证的交易优势或星球官方信号。
8
+
9
+ `validation_status=not_validated`:真实股票检验没有建立默认入场规则的优势;降低门槛、延长慢线和通道对照也未通过修订研究门槛。默认解释 `direction` 与连续分数,MUST NOT 自行把七档或零轴转换成交易建议。仅在用户明确要求七档时展示研究标签;用户自定条件的回测是研究,不代表推荐。
10
+
11
+
12
+ ## 公式与数据
13
+
14
+ ```text
15
+ TR_t = max(high_t-low_t, abs(high_t-close_(t-1)), abs(low_t-close_(t-1)))
16
+ ATR14_t = 最近14个有效TR的简单均值
17
+ score_t = (EMA20(close)_t - EMA60(close)_t) / ATR14_t
18
+ EMA_p,t = (2/(p+1))*close_t + (1-2/(p+1))*EMA_p,t-1
19
+ ```
20
+
21
+ EMA 用输入首个收盘价初始化(adjust=False),前收缺失的首根 TR 不计算;ATR 使用简单平均,不是 Wilder 平滑。默认至少 60 根 K 线才有分数,至少 61 根才可能有前一期状态。周期按根数:周线即 20/60 周及 14 周波幅,不能与日线信号混称。
22
+
23
+ `direction/previous_direction` 仅按 EMA 差的正负返回 up/down/flat,未预热或无有效分数时为 null;不是预测方向。七档的“平”包含正负分数,不能代替方向;`previous_state` 和 `transition` 仍只表示显示档位变化。多周期摘要附 `trend_score`、`trend_temperature_state`、`trend_temperature_direction`、`trend_temperature_validation_status`、`trend_temperature_as_of`、`trend_temperature_price_basis` 和 `trend_temperature_unavailable_reason`。各周期日期和价格口径分别核验,不能用顶层日线日期代替周线或月线日期;原 `resonance` 仍基于既有均线方向,不能称为七档温度共振。
24
+
25
+ 价格需有限且为正,满足 low ≤ close ≤ high;日期唯一且递增。技术分析入口会先按日期排序;明确混用复权标记时温度不可用。`price_basis=unknown` 仍需核实价格口径;没有标记不代表已确认复权。保留 `history_start`,输入历史起点不同会影响 EMA 初始化和当前分数。缺失交易日和停牌不能仅靠日期排序鉴别;`previous_as_of` 是输入的前一根 K 线日期,不保证是交易所的上一交易日。
26
+
27
+ 零 ATR、不足预热或无效行情输出 `score/state=null` 和 `unavailable_reason`,不伪造为平。最新 K 线可能尚未收盘,MUST 先确认数据时点再按收盘纪律判断。分数不要求正态分布,但 ATR 和 EMA 都会受极端波动及观察窗口影响;波幅放大也可能使分数降档。
28
+
29
+ ## 七档显示
30
+
31
+ | score | 状态 |
32
+ | --- | --- |
33
+ | 小于 -3 | 冻 |
34
+ | [-3, -1.5) | 寒 |
35
+ | [-1.5, -0.5) | 凉 |
36
+ | [-0.5, 0.5] | 平 |
37
+ | (0.5, 1.5] | 温 |
38
+ | (1.5, 3] | 热 |
39
+ | 大于 3 | 沸 |
40
+
41
+ `previous_score/previous_state` 只取前一根,不跳过不可用记录;`transition` 仅在本根和前根均可用且状态不同时返回。它们由本次行情计算,不需要跨日保存账户。
42
+
43
+ 温/热/沸表示本基线的正向分离程度,不等于星球的同名状态。沸不证明已经过热或将反转;平不表示没有波动。MUST 将描述与用户的入场、退出规则分开,不照搬星球“温转热开仓、危险全平”等标签动作,也不由本字段自动覆盖原 `buy_signal`。
44
+
45
+ ## 历史检验
46
+
47
+ 回测 DSL 可使用 `indicator: trend_score`;默认参数与技术分析相同。既有 `fast_period/slow_period` 调整 EMA,`period` 调整 ATR;快线必须短于慢线且均为正整数。修改参数后七档阈值不自动校准。
48
+
49
+ 不提供默认温度入场示例。用户指定研究规则后,仍须说明原引擎默认 stop_loss=-0.10、take_profit=0.50,省略不代表禁用。预热/零 ATR 为 NaN 时条件不成立,不能凭首个有效分数声称发生穿越。默认次日开盘成交,保留 signal_date/date;涨跌停、跳空及其他限制沿用原引擎。
50
+
51
+ 用户要求检验时按 [策略回测](../../strategy-backtest/SKILL.md)先固定规则,再做时间样本外与跨标的比较,报告反复切换、成本、回撤和交易数量。滚动验证每段重新初始化,测试窗口必须足够覆盖预热及评估期。结合已有 [肥尾收益诊断](fat-tails.md)检查大赢家贡献,不把正偏或集中度当作正收益证明。
52
+
53
+ 理论参考:[Time Series Momentum](https://www.aqr.com/Insights/Research/Journal-Article/Time-Series-Momentum)提供历史收益趋势研究依据,不验证本模型的 20/60/14 参数和阈值;[Taleb κ](https://arxiv.org/html/1802.05495)衡量样本聚合稳定性,不输出趋势方向。
54
+
55
+ ## 使用入口
56
+
57
+ 当前趋势研究优先使用[多期限月度趋势](trend-horizons.md)的trend_horizons,daily、count=360。独立趋势温度继续保留供兼容和既有计算复现,不将七档作为默认趋势判断。多期限趋势也尚未通过全部跨市场风险门槛,不是自动入场信号。
@@ -0,0 +1,78 @@
1
+ #!/usr/bin/env python3
2
+ """Stateless monthly trend experiment from stock and market OHLCV JSON arrays."""
3
+
4
+ import argparse
5
+ import json
6
+ import sys
7
+ from pathlib import Path
8
+
9
+ import numpy as np
10
+
11
+ sys.path.insert(0, str(Path(__file__).resolve().parents[3] / "tools"))
12
+ from _subproc import json_safe, utf8_stdio # noqa: E402
13
+ from backtest import compute_metrics, simulate_monthly_market # noqa: E402
14
+ from technical import calc_trend_horizons, to_dataframe # noqa: E402
15
+
16
+
17
+ class Parser(argparse.ArgumentParser):
18
+ def error(self, message):
19
+ raise ValueError(message)
20
+
21
+
22
+ def read_prices(path):
23
+ records = json.loads(Path(path).read_text(encoding="utf-8"))
24
+ if not isinstance(records, list) or not records or any(not isinstance(row, dict) for row in records):
25
+ raise ValueError("Expected a nonempty OHLCV JSON array")
26
+ frame = to_dataframe(records)
27
+ fields = ["open", "high", "low", "close", "volume"]
28
+ if "date" not in frame or any(field not in frame for field in fields):
29
+ raise ValueError("OHLCV input requires date, open, high, low, close and volume")
30
+ if not np.isfinite(frame[fields]).all().all() or (frame[fields[:4]] <= 0).any().any():
31
+ raise ValueError("OHLCV input requires finite positive prices")
32
+ if (
33
+ (frame.low > frame.close) | (frame.close > frame.high) | (frame.low > frame.open) | (frame.open > frame.high)
34
+ ).any():
35
+ raise ValueError("OHLCV input requires low <= open/close <= high")
36
+ return frame
37
+
38
+
39
+ def main():
40
+ parser = Parser(description=__doc__)
41
+ parser.add_argument("prices")
42
+ parser.add_argument("market_prices")
43
+ parser.add_argument("--symbol", required=True)
44
+ parser.add_argument("--market-symbol", required=True)
45
+ parser.add_argument("--start", required=True)
46
+ parser.add_argument("--end")
47
+ parser.add_argument("--capital", type=float, default=1000000)
48
+ parser.add_argument("--allocation", type=float, default=1)
49
+ try:
50
+ args = parser.parse_args()
51
+ prices, market = read_prices(args.prices), read_prices(args.market_prices)
52
+ if args.end:
53
+ prices = prices[prices.date <= args.end].copy()
54
+ result = simulate_monthly_market(prices, market, args.capital, args.symbol, args.start, args.allocation)
55
+ result.update(symbol=args.symbol, market_symbol=args.market_symbol, trend_horizons=calc_trend_horizons(prices))
56
+ start = result["start"]
57
+ result["equity_curve"] = [row for row in result["equity_curve"] if row["date"] >= start]
58
+ end = result["equity_curve"][-1]["date"]
59
+ result["metrics"] = compute_metrics(
60
+ result["trades"], result["equity_curve"], args.capital, result["final_equity"], start, end
61
+ )
62
+ result["warnings"] = [
63
+ "Research only: market close>SMA200 gates new monthly entries, not existing exits. "
64
+ "Need stock 253 and market 200 valid closes before observation; verify all bars are closed. "
65
+ "Three initially equal sleeves drift; costs are commission/slippage 0.1% each side, tax/interest zero. "
66
+ "Historical splits/dividends, actual board lots, limits and liquidity need separate verification. "
67
+ "Passing one small historical cohort is not stable cross-market validation."
68
+ ]
69
+ except Exception as exc:
70
+ print(json.dumps({"error": str(exc)}, ensure_ascii=False))
71
+ return 1
72
+ print(json.dumps(json_safe(result), ensure_ascii=False, allow_nan=False))
73
+ return 0
74
+
75
+
76
+ if __name__ == "__main__":
77
+ utf8_stdio()
78
+ sys.exit(main())
@@ -5,6 +5,10 @@ description: 事件驱动分析:评估公告、业绩、政策、订单或资
5
5
 
6
6
  # 事件驱动分析
7
7
 
8
+ ## 无状态分析扩展
9
+
10
+ 历史事件窗口验证或公告原文变化分析时,MUST 读取[无状态研究工具](../stock-analysis/references/stateless-analysis.md),使用 analyze_event_study/analyze_disclosure_changes。事件日期、盘前盘后、价格窗口和正文覆盖必须核实。
11
+
8
12
  ## 输入数据说明
9
13
 
10
14
  先运行:
@@ -5,6 +5,10 @@ description: 成长质量分析:用多期收入、利润、现金流和盈利
5
5
 
6
6
  # 成长质量分析
7
7
 
8
+ ## 无状态分析扩展
9
+
10
+ 财报前后期变化或同行验证时,MUST 读取[无状态研究工具](../stock-analysis/references/stateless-analysis.md)中的同行和公告财报比较,使用 compare_stocks/analyze_disclosure_changes 整理同口径指标与正文证据,再解释经济含义。
11
+
8
12
  ## 输入数据说明
9
13
 
10
14
  先运行:
@@ -71,3 +71,5 @@ gather 工具返回以下字段:
71
71
  - 港股/美股:因数据限制,聚焦指数结构 + 消息催化 + 策略建议
72
72
 
73
73
  完成标准:市场阶段、温度和次日策略均可追溯到返回数据,非 A 股报告不出现 A 股专属宽度或板块结论。
74
+
75
+ 数据不足时 temperature.score 和 strategy_stance 保持 null,temperature.level/signal 为 unknown。将 data_quality.limitations 保留在报告中;未知状态不能写成中性、均衡或有效仓位建议。
@@ -5,10 +5,18 @@ description: 综合股票分析:联合技术、基本面、资金、消息和
5
5
 
6
6
  # 综合股票分析
7
7
 
8
- 美股机构研究调用 `get_us_holdings(cik, mode=auto)`:有当前或已检索历史 13F 时返回机构组合,否则按发行人 CIK 反查机构;也可显式选 `manager/issuer`,如 Berkshire `0001067983` 查组合、Apple `0000320193` 用 `issuer` 查机构。发行人映射仅使用核对 CIK 的官方 13D/G CUSIP,不做名称猜测;无映射直接报缺失。首次下载约 100 MB,后续缓存,Hermes 查询预算 300 秒。读取 `report_date/filing_window_end/cusip_evidence`,区分持仓日期与披露窗口;修订重述替换、新增补充,缺基础版或未知修订时总量 null,并计入 `unresolved_manager_count`。`mapping_complete=false` 表示不能保证涵盖所有类别或变更,`complete_for_mapped_cusips` 只表示已映射证券在公开数据窗口的申报链完整性,不能称实时全部股东。期权/本金在 `positions` 单列,不能把跨机构持股简单合计成去重比例。机构组合查询仍返回最新已知报告期的原始 13F 与修订链接,缺少对应原始版时明确报错;`history_truncated=true` 时不能将旧记录当作已完整检索。存在修订先读原文,不能自动推断变化。
8
+ 在启用原生工具发现的 Pi 中,所需工具尚未暴露时,先用 `tool_search` 搜索确切工具名或英文关键词,再按本文流程调用;其搜索器目前不对中文分词。旧 Pi 或其他宿主按当前实际提供的工具直接执行。
9
+
10
+ 在 dsh 提供 `stock_tool_search` 且所需工具尚未暴露时,先搜索中文功能关键词或确切工具名,加载后按原名调用;搜索不执行分析。没有发现入口时直接使用当前提供的工具。
11
+
12
+ 美股机构研究调用 `get_us_holdings(cik, mode=auto)`:有当前或已检索历史 13F 时返回机构组合,否则按发行人 CIK 反查机构;也可显式选 `manager/issuer`,如 Berkshire `0001067983` 查组合、Apple `0000320193` 用 `issuer` 查机构。发行人映射仅使用核对 CIK 的官方 13D/G CUSIP,不做名称猜测;无映射直接报缺失。首次下载约 100 MB,后续缓存,共享 CLI 查询预算 300 秒(宿主另留退出余量)。读取 `report_date/filing_window_end/cusip_evidence`,区分持仓日期与披露窗口;修订重述替换、新增补充,缺基础版或未知修订时总量 null,并计入 `unresolved_manager_count`。`mapping_complete=false` 表示不能保证涵盖所有类别或变更,`complete_for_mapped_cusips` 只表示已映射证券在公开数据窗口的申报链完整性,不能称实时全部股东。期权/本金在 `positions` 单列,不能把跨机构持股简单合计成去重比例。机构组合查询仍返回最新已知报告期的原始 13F 与修订链接,缺少对应原始版时明确报错;`history_truncated=true` 时不能将旧记录当作已完整检索。存在修订先读原文,不能自动推断变化。
9
13
 
10
14
  美股内部人研究调用 `get_insider_trades(symbol, days=90, top=10)`,需设置含真实联系邮箱的 `SEC_USER_AGENT`。`days` 按申报日期过滤,`top` 限制文件数;只将代码 P/S 视作买卖信号,授予、行权、赠与等保留原始代码和脚注,衍生品单列。Form 4/A 与原申报勿重复计算,检查截断和失败提示;`screen_risk` 仍仅支持 A 股。
11
15
 
16
+ ## 无状态分析扩展
17
+
18
+ 当用户要求同行比较、组合风险、仓位预算或新旧分析比较时,MUST 读取[无状态研究工具](references/stateless-analysis.md),分别使用 compare_stocks、analyze_portfolio_risk、calculate_position_size、compare_analysis_snapshots。所有用户状态均由本次输入提供。
19
+
12
20
  ## 意图路由表
13
21
 
14
22
  快速问答先判断意图,按下表走最短调用链;完整综合研判走下方执行流程(gather 采集管线),不受此表限制。单工具可答的问题按各工具描述中的适用场景选择,本表不再重复。
@@ -72,18 +80,20 @@ python3 scripts/gather.py <symbol>
72
80
  ### 第三步:渲染研报
73
81
 
74
82
  1. 按 [报告 schema](../../schemas/report_schema.json) 构建结构化报告。
75
- 2. 每个结论只使用成功返回的数据;缺失维度在 `risk_warning` 中说明影响。
83
+ 2. 每个结论只使用成功返回的数据;缺失维度在 `risk_warning` 中说明影响。必须填写 `evidence`,每项使用原始工具结果路径(如 `get_quote.price`)、读者可理解的 `label`、原始 `value`、实际 `source` 和数据时间 `as_of`;未知来源或时间填 null,不用采集时间替代。历史财报与顶层快照分别引用日期、币种和单位,不把不同期间的数值拼成同一结论。 来源与时间沿证据 path 继承最近父对象的 source(该键缺失时用 snapshot_source)和 data_as_of,子对象的对应值(包括显式 null)覆盖祖先;数组项及 warnings 字符串同样继承,不能仅因叶子字段没有来源就填 null。整条路径均未提供对应元数据时才填 null,不能用工具名或策略方法名代替来源;as_of 保留完整数据时间及其时区。report_date 是财报报告期,应单独引用 value,不能当成披露日期或 data_as_of。证据 path 不含调用参数,例如 get_financials.periods.0.roe;股票名称未返回时 stock_name 填“未知”,不能凭常识补名;已知返回对象中未提供的末级字段可用 value=null 表示未知,其 source/as_of 可填 null,若填写则必须来自已知父对象;不能编成空数组、字符串或数值,不能跨缺失对象或数组编造路径;错误 value 保留原始字符串,不加 error: 前缀。请求的期间或文件路径不证明实际数据覆盖期或文件内容,需与实际返回数据区分。
84
+ 同时填写 `data_quality.flags/limitations`:关键数据缺失用 `partial_data`,明确过期行情用 `stale_quote`,同期间同口径来源冲突用 `conflicting_data`,回测/信号样本不足用 `insufficient_sample`。出现这些限制时降低置信度,不能给出 strong_buy;没有有效现价时不编造数值交易计划。数据完整时 flags 为空数组,限制仍按实际模拟条件说明。
76
85
  3. 调用 `render_stock_report`:快速问答用 `brief`,完整研判用 `full`。
77
86
  4. 输出渲染后的 Markdown;只在用户要求机器可读数据时附加结构化 JSON。
78
87
 
79
88
  ## 信号跟踪闭环
80
89
 
81
90
  - 给出明确买卖建议(方向 + 入场价/目标价/止损价)时,调 `record_signal` 存档,`source` 填触发该建议的 skill 名(如 `stock-analysis`、`dragon-head`)。
82
- - 后续会话用 `evaluate_signals` 结算到期信号(target_hit/stop_hit/timeout 并回写收益),用 `get_signal_summary` 复盘胜率(可按 source/symbol/status 过滤)。
91
+ - 后续会话用 `evaluate_signals` 结算到期信号(target_hit/stop_hit/timeout 并回写收益),用 `get_signal_summary` 复盘胜率与平均收益(可按 source/symbol/status 过滤),同时报告 `return_samples/sample_warning`,缺失收益不按零计;这些是观察性建议记录,不是扣除成本的策略回测。
83
92
  - 信号持久化在本地 JSONL(`$STOCK_SIGNAL_STORE` 或 `~/.stock-analysis/signals.jsonl`);是否记录由宿主 Agent 决定,不阻塞报告输出。
84
93
 
85
94
  ## 注意事项
86
95
  - `get_kline` 的 A 股股票/ETF 数据为前复权,每条记录 `adjusted="qfq"`;显式指数 `sh000xxx` / `sz399xxx` 为原始点位,`adjusted="none"`。复权数据源全部失败时说明数据缺失,不用未复权价格补算指标或信号。
96
+ - 行情读取 `source/fetched_at/data_as_of`,`fetched_at` 是 UTC 采集时间;`as_of_basis=trading_calendar` 是日历推断,不能声称是提供方报价时间。提供方时间未知时明确说明时效性未核实。
87
97
  - 始终提供风险提示
88
98
  - 不做绝对化的涨跌预测
89
99
  - 建议用户结合自身风险偏好做决策
@@ -112,3 +122,7 @@ python3 scripts/gather.py <symbol>
112
122
  get_shareholder_structure 的 northbound 优先使用沪深官方季度总量;northbound_nominee 只是十大股东推断,不能混同。get_etf_details 的 basket 是完整已发布 PCF,对价数量/现金替代规则不是基金实际持仓或NAV权重。HK 股息排行使用 get_dividends(mode=ranking, market=HK),年度口径不能称 TTM。
113
123
 
114
124
  实际披露股票持仓可用 get_etf_details(include_full_holdings=true) 获取半年度/年度表;按 as_of 解释,数量为股、市值为人民币元。默认不取大量明细;不是实时全资产组合,不与 PCF 对价数量混同。
125
+
126
+ 信号价格使用原始报价口径。复权 K 线需有记录日的可核实 adjustment_factor,才能换算入场/目标/止损及收益;缺失时 skipped_price_basis 并保持未结算,不得猜测拆股或除权比例。evaluate_signals 返回 complete/deferred/warnings;预算耗尽时已完成结果保存,未处理记录下次重试。当前仅日线 Tushare、Alpha Vantage 提供可验证换算系数,其余复权来源可能跳过结算。
127
+
128
+ 自选股上下文异动检查失败时 anomaly_status=unavailable、anomaly_count=null,并提供 anomaly_error/warnings;summary.partial 不得写成无异常或完整成功。
@@ -0,0 +1,66 @@
1
+ # 无状态研究工具
2
+
3
+ 这些工具在一次调用中计算,不维护自选股、账户、规则或历史。宿主/用户显式提供本次持仓、历史快照与正文。采集继续用已有行情、财务、公告工具。MUST 从原始结果取值、保留来源和时点;MUST NOT 补造缺失值、股票池或持仓。缺少必需输入时只索取该输入。
4
+
5
+ ## 同行比较:compare_stocks
6
+
7
+ 1. 确定用户提供或有明确行业依据的可比股票,调用 get_financials/get_quote/get_stock_info;必要时 resolve_stock_sectors。不要用全市场估值直接代替同行。
8
+ 2. 传 `companies`(2..30项),每项 `{symbol, period, metrics}`。`metrics` 每项 `{name, value, unit, basis, source?}`,缺失 value=null。`period` 是指标的共同报告期或估值日;同一公司不同期间的指标应分批比较。
9
+ 3. 核实单位。A 股 roe/net_profit_margin/gross_margin 可能是百分数,而 Yahoo roe/profit_margin 是小数;只有确定源口径时才换算并记录依据。金额单位必须含币种。不同年度、TTM 与单季、合并与母公司报表分开。
10
+ 4. 工具只有 unit/basis/period 完全一致且至少两项有效数值时返回 ascending。它表示升序,MUST NOT 称为买入排名。亏损 PE、负 PB 和行业特有口径需另行说明,不按“越低越好”解释。
11
+
12
+ ## 公告财报比较:analyze_disclosure_changes
13
+
14
+ 传 `previous/current`,每项 `{text, source, period, metrics}`;正文上限200000字符,metrics 形状同上(可为空),`max_changes` 默认30、上限100。
15
+
16
+ 先查询原始公告;HTML 可用 extract_article,但它默认截断正文,不能将其结果自动视为全文。PDF/OCR 由宿主文档读取能力或用户提供,MUST NOT 把标题、链接或搜索摘要冒充全文。缺少正文时仍可分析已核实的财务指标,但不要调用要求正文的比较工具。
17
+
18
+ 工具输出精确到传入文本行号的变化片段、来源、截断标志和指标差异。文本差异本身不等于经营变化;Agent 要阅读上下文,说明发生了什么、与原预期的关系和可能反证,并引用原文。金额单位和 basis 一致才计算 delta;前期值大于0才计算普通增长率,亏损转盈另述。报告期可不同,但必须核实是可比同长期间(年度/同比单季等),累计季度不能直接当单季。
19
+
20
+ ## 组合风险:analyze_portfolio_risk
21
+
22
+ 输入 `base_currency`、基准币种 `cash>=0`、`positions`(1..100项)。持仓 `{symbol, quantity, price, currency, cost?, stop_price?, sector?, as_of?}`,现货多头;重复标的先汇总。价格/数量为正,单位由调用方确认。
23
+
24
+ 可选 `fx_rates:[{currency,rate}]`,rate 表示一单位非基准币种兑换多少基准币种;基准币种隐含1,禁止重复。缺汇率不能部分汇总冒充总资产。相同币种现金先换成基准币种再输入;其他币种现金可按现金类头寸单独注明,不能当股票计算相关性。
25
+
26
+ 输出总权益、现金权重、单股权重、行业/币种敞口和持仓 HHI(不含现金项)。`price_pnl_base` 是按当前汇率折算的本币价格盈亏,MUST NOT 称为包含汇兑损益的账户真实收益;缺任何成本时为null。`stop_loss_risk_base` 是从现价到止损的损失情景,缺任何止损时为null,不保证成交。
27
+
28
+ 可选 `histories:[{symbol,prices:[{date,close}]}]`,工具按每对标的共同日期计算收益相关性;至少4个共同价格点、存在波动才有结果。不是组合收益率或汇率调整后的相关性;少样本、跨时区非同步收盘和缺交易日都应说明,不从相关性推断因果。缺历史时明确相关性未计算。
29
+
30
+ ## 仓位预算:calculate_position_size
31
+
32
+ 必需 `equity,cash,entry_price,stop_price,risk_fraction,lot_size`。风险比例0..1,止损正且低于入场价,现金0..equity,交易单位正整数。所有金额同币种。
33
+
34
+ 可选 `max_position_fraction=1`(0..1)、`fee_rate=0` 与 `slippage_rate=0`(每边比例0..0.1)。买入现金按 entry×(1+slippage)×(1+fee),止损回收按 stop×(1-slippage)×(1-fee);每股差额计入风险预算。现金、风险和本次最大买入资金分别向下取整到lot,取最小数量。已有同股持仓时,先扣减用户允许的新增仓位和风险额度,不能把本次额度当成最终账户仓位限制。
35
+
36
+ lot_size 来自用户或可核实交易规则,尤其港股不能统一猜100股。工具不覆盖券商最低收费、未提供税费、跳空和流动性风险。quantity=0 表示当前约束下不足一个交易单位,MUST NOT 向上凑整。
37
+
38
+ ## 事件研究:analyze_event_study
39
+
40
+ 通常直接传 `symbol,benchmark,start_date,end_date,event_dates`,由共享 Python 核心取数,避免模型复述整段K线。股票与基准应属于同一市场;代码模式输出实际覆盖区间和提供方复权标记,没有标记时明确未指定,不用调用方猜测覆盖。开始日期须覆盖事件前一交易日、结束日期须覆盖最长事件窗口。也可使用下面的显式价格模式,两种模式互斥。
41
+
42
+ 传 `prices,benchmark_prices`(各2..20000条 `{date:"YYYY-MM-DD",close}`)、`event_dates`(1..100个唯一日期)、`price_basis`(明确股票与基准各自复权口径)。可选 `horizons`(1..20个0..250整数,默认0/1/5/10/20)。复用 get_kline,先核实数据覆盖事件前一交易日至最大窗口结束。
43
+
44
+ 事件日映射到股票序列中不早于指定日期的首日;盘后事件应显式使用下一交易日。基点是该日前一个股票交易日收盘;horizon=0表示事件当日收盘。基准必须同市场,并在两个端点都有数据,缺失时不移动事件日期。收益差是股票与基准各自买入持有收益的差(百分点),不等于因果影响。
45
+
46
+ MUST 核实完整交易日、复权、币种和股息处理。工具无法从缺行判断是停牌、节假日还是数据故障。重叠事件标识意味着样本不独立;少样本均值不能作为稳定预测。
47
+
48
+ ## 回测稳健性:validate_backtest
49
+
50
+ 通常传 `symbols:[代码],start_date,end_date,strategies`,Python 直接复用现有 K 线获取;不要让模型抄写数千条行情。也可使用下面的显式 datasets 模式,两种模式互斥。读取每个标的 data_coverage,实际覆盖不足时缩小结论范围;提供方未标记价格口径时须说明。代码模式共享CLI预算660秒、事件研究300秒,宿主另留退出余量。
51
+
52
+ 传 `datasets`(1..5项 `{symbol,price_basis,bars}`,bars 是按日期升序的 date/open/high/low/close/volume,每组最多2000条)、`strategies`(1..5项 `{name,strategy}`,完整既有DSL的JSON对象)。可选 `train_bars=126,test_bars=63`(各30..1000)、`capital=1000000`。每组至少训练+测试长度。
53
+
54
+ 通过现有 get_kline 取完整数据,读取用户策略后转换为JSON;parameters 引用复用现有引擎解析。候选应事先确定,只在用户要求优化时扩展候选,MUST NOT 看测试窗口收益后反复改参数并仍称样本外。
55
+
56
+ 每个标的独立滚动训练,按训练总收益选候选(并列按输入顺序),在其后的非重叠完整测试窗口评估。返回每个候选的训练结果、选中者及测试结果;全区间 sensitivity 是样本内比较。尾部不足完整测试窗口会报告unused_tail_bars。
57
+
58
+ 选择使用相同初始资金下的实际 `final_equity`,不使用展示精度舍入后的收益。所有入场/退出条件先校验,未触发的条件也不能绕过检查;坏候选单独返回 error,不中断合法候选。无法定义的 `profit_loss_ratio` 为null,不能当作0;其余数值溢出或无效Unicode输入返回JSON错误。
59
+
60
+ 每个窗口从现金和重新初始化的指标开始,不拼成连续组合;MUST NOT 把各窗口年化收益平均当成实际年化。只允许next_open。关注候选错误、交易数和未平仓;收益含未平仓市值,交易统计仅含已平仓。不同标的和不同参数的收益分散程度是稳健性证据,不是自动策略认证。缺少历史股票池、退市样本、公司行为和限价数据时保留原回测限制。
61
+
62
+ ## 快照比较:compare_analysis_snapshots
63
+
64
+ 传 `previous/current` JSON对象;嵌套字典按JSON Pointer输出变化,数组按整体比较。批量股票应先以symbol构造字典,时间戳/采集耗时等机械字段先按需求排除,避免无意义变化。
65
+
66
+ 状态为added/removed/changed/unavailable/recovered。null 或包含error的对象表示不可用;removed只表示键从输入消失,MUST NOT 自动解释为退市、卖出或业务事件。缺少历史输入时仅做当前分析;持久化、调度及通知由宿主负责。
@@ -66,7 +66,9 @@ python3 tools/screener.py screen --market A --top 20
66
66
  - 建议结合个股深度分析后再做决策
67
67
  ```
68
68
 
69
- 完成标准:列出实际生效的市场、过滤条件、排序口径和候选数量,且推荐理由只使用返回数据。
69
+ 每个候选必须读取 `factor_coverage.available/missing/ratio/effective_weights`。ratio 是已覆盖因子的原始权重之和;L1 与 L2 的 effective_weights 均按可用因子重归一化,缺失或非有限值不按零分计,排序前先按实际可用因子计算综合分,effective_scores 保留实际参与计算的各组分数;用 sum(effective_scores[g] × effective_weights[g]) × market_sentiment.multiplier 核对 scores.final(四舍五入至一位)。scores.momentum 仍保留 L1 参考值,L2 贡献以 effective_scores.momentum 为准。相同分数但缺失因子不同的候选不能视为同等证据,报告缺失项和覆盖度,不以 `enriched=true` 代替覆盖判断。`scores.final=null` 表示没有足够因子计算,不能作为高分候选推荐。
70
+
71
+ 完成标准:列出实际生效的市场、过滤条件、排序口径和候选数量,且推荐理由只使用返回数据,并说明因子覆盖。
70
72
 
71
73
  ## 策略模板
72
74
 
@@ -93,3 +95,5 @@ dividend_report_date: "2025-12-31"
93
95
  ### 补充数据覆盖
94
96
 
95
97
  股息筛选支持 A/HK:A 股为报告期已实施方案股息率,HK 为 HKEX/LSEG 年度股息率。两者都不是当前价 TTM;使用结果的 yield_basis 和 report_date,缺失不当零。
98
+
99
+ 选股的 top 必须为正整数;超时预算按候选数量与采集批次计算。
@@ -5,10 +5,16 @@ description: 策略回测:定义或读取 AlphaEvo YAML 策略,回测收益
5
5
 
6
6
  # 策略回测与优化
7
7
 
8
+ 生成股票池月度右侧趋势计划时,先读 [月度右侧趋势策略](../bull-trend/references/monthly-trend-strategy.md),直接以股票代码调用 `analyze_trend_strategy(symbols, ...)` 自动取行情,无需用户准备文件。这是整池信号/预算分析;共享资金历史绩效仍依据冻结研究,MUST NOT 用单股YAML或信号计划冒充组合回测。报告尚未通过跨样本效果验证的边界。
9
+
8
10
  开始前读取[短线交易决策框架](../stock-analysis/references/short-term-trading.md)的风险单位和回测约束。回测用于反证策略,不把样本内收益包装成预测。
9
11
 
10
12
  解读回测时,`period` 是实际取得的数据期间,`requested_period` 保留用户请求,`warnings` 提示两者差异。年化收益按实际期间计算;覆盖不完整时明确说明,不能声称完成了完整请求期间的验证。买入预算包含佣金,`position.size` 为 0..1 的资金比例。
11
13
 
14
+ ## 无状态分析扩展
15
+
16
+ 滚动样本外、参数敏感性或跨标的验证时,MUST 读取[无状态研究工具](../stock-analysis/references/stateless-analysis.md)的 validate_backtest 分支。复用 get_kline,传完整OHLCV和事先确定的DSL候选;样本内sensitivity不等于样本外验证。
17
+
12
18
  ## 工作流程
13
19
 
14
20
  ### 第一步:策略定义
@@ -42,6 +48,7 @@ exit:
42
48
  take_profit: 0.15 # 止盈比例
43
49
 
44
50
  simulation:
51
+ execution: next_open # 默认:前日收盘信号,次日开盘成交
45
52
  slippage: 0.001 # 滑点(买卖双边),默认 0.001
46
53
  commission: 0.00025 # 佣金(买卖双边,券商自定;A股常见万2.5),默认 0.0015
47
54
  stamp_tax: 0.0005 # 印花税(仅卖出收;A股 0.05%,其他市场按当下实际费率,无则省略),默认 0
@@ -53,6 +60,12 @@ position:
53
60
 
54
61
  **可用指标**:rsi, ma, ema, macd_dif, macd_dea, macd, volume_ratio, price_change, bollinger_position, close, volume
55
62
 
63
+ `monthly_momentum` 是共享核心的月度观察对数收益:`period` 默认63,支持21/63/252等正整数;月初首根正成交量日K收盘计算并保持到下次月度观察,次日开盘才可能成交。零成交量记录不计回溯根数。MUST 读取 [多期限月度趋势](../bull-trend/references/trend-horizons.md),不能把单期限YAML等同三子策略组合。需要在观察日已有period+1根有效日K;默认回测起点会截断输入历史,不能据此声称提前完成预热。三期限同资金起点的完整研究复现使用参考里的研究脚本。
64
+
65
+ 独立趋势强度可用 `trend_score`,默认 `(EMA20-EMA60)/ATR14`,ATR 为真实波幅简单平均。`fast_period/slow_period/period` 分别控制快 EMA、慢 EMA、ATR,要求正整数且快线小于慢线;默认 60 根预热,预热或零 ATR 不触发条件。解释七档显示、初始化与样本外验证前 MUST 读取 [独立趋势温度](../bull-trend/references/trend-temperature.md)。它不是星球温度或肥尾信号,原固定止损/止盈默认值仍生效。
66
+
67
+ 该字段的 `validation_status=not_validated`。已有真实股票试验未支持默认温度入场规则;MUST NOT 自行补出“温转热买、降温卖”或零轴规则作为推荐策略。用户指定规则时可运行研究回测,但 MUST 同时报基准、成本、回撤及验证局限。
68
+
56
69
  **可用运算符**:`>`, `<`, `>=`, `<=`, `==`, `cross_above`, `cross_below`
57
70
 
58
71
  ### 第二步:运行回测
@@ -70,6 +83,10 @@ python3 tools/backtest.py run <path.yaml> <symbol> --start <date> --end <date>
70
83
  - `--start` / `--end`:回测时间范围(可选,默认近一年)
71
84
  - 初始资金默认 100 万,可用 `--capital` 调整
72
85
 
86
+ 默认 `simulation.execution=next_open`:信号在前一交易日收盘确定,下一有效交易日按开盘价加滑点成交;交易同时保留 `signal_date` 与实际 `date`。最后一天新信号没有后续开盘时不能成交。需要复现旧结果时显式使用 `same_close`,并说明它按信号日收盘成交,可能高估可执行收益。零/缺失成交量(已有 volume 字段时)阻止成交;一字涨跌停仅在输入提供同口径历史 `limit_up/limit_down` 时保守阻止,不猜 ST、IPO 或 ETF 限价。
87
+
88
+ 读取 `execution.model/blocked_orders/unfilled_order/limitations` 并说明未成交情况。止损、止盈和移动止损均是收盘信号,不承诺盘中按阈值成交;次日跳空按实际开盘价计算。没有历史限价数据时,不能声称已验证涨跌停可成交性。
89
+
73
90
  ### 第三步:分析结果
74
91
 
75
92
  回测完成后,按共享框架的风险单位和回测约束解释原始结果。针对本工具:
@@ -141,3 +158,5 @@ python3 tools/backtest.py run <path.yaml> <symbol> --start <date> --end <date>
141
158
  参考 `{baseDir}/strategies/examples/` 目录中的示例:
142
159
  - `rsi_oversold.yaml` — RSI 超卖反弹
143
160
  - `ma_crossover.yaml` — 均线金叉
161
+
162
+ 市场环境只限制新开仓的三期限月度实验,使用 [bull-trend参考](../bull-trend/references/trend-horizons.md#市场环境入场实验) 与 `../bull-trend/scripts/market_trend.py`,输入两份带预热的daily OHLCV JSON。普通单期限YAML不会自动提供该组合或市场数据;未知市场历史禁止新入,市场转弱不冒充个股退出。初始投资时不能把预热虚拟信号当实际持仓。
@@ -4,6 +4,13 @@
4
4
  {% set t = temperature or {} -%}
5
5
  **温度:** {{ m.signal_emoji(t.signal) }} {{ m.fmt_num(t.score, 1) }}/100 | **信号灯:** {{ m.signal_label(t.signal) }} | **策略姿态:** {{ m.stance_label(strategy_stance) }}
6
6
 
7
+ {% if data_quality and data_quality.limitations -%}
8
+ **数据限制:**
9
+ {% for limitation in data_quality.limitations %}
10
+ - {{ limitation }}
11
+ {% endfor %}
12
+ {%- endif %}
13
+
7
14
  {% if regime and (regime.regime_cn or regime.regime) -%}
8
15
  > **市场阶段:** {{ regime.regime_cn or regime.regime }}{% if regime.confidence is not none %}(置信度 {{ m.fmt_num(regime.confidence) }}){% endif %}{% if regime.recommended_skills %} | **推荐策略:** {{ regime.recommended_skills | join('、') }}{% endif %}
9
16
  {%- endif %}
@@ -0,0 +1,11 @@
1
+ {% if data_quality or evidence %}
2
+
3
+ ### 本次数据与限制
4
+
5
+ {% for item in evidence or [] %}
6
+ - **{{ item.label or '数据依据' }}:** {{ item.value if item.value is not none else '未知' }}(来源:{{ item.source or '未标明' }};数据时间:{{ item.as_of or '未知' }})
7
+ {% endfor %}
8
+ {% for limitation in (data_quality or {}).limitations or [] %}
9
+ - {{ limitation }}
10
+ {% endfor %}
11
+ {% endif %}
@@ -29,3 +29,5 @@
29
29
  {% if intel.risk_alerts -%}
30
30
  ⚠️ **风险:** {{ intel.risk_alerts | join(';') }}
31
31
  {% endif %}
32
+
33
+ {% include "stock_analysis/_evidence.md.j2" %}
@@ -107,5 +107,7 @@
107
107
  {% endfor %}
108
108
  {%- endif %}
109
109
 
110
+ {% include "stock_analysis/_evidence.md.j2" %}
111
+
110
112
  ---
111
113
  *本报告由 stock-analysis-plugin 渲染,仅供参考,不构成投资建议。*
package/tools/_subproc.py CHANGED
@@ -14,10 +14,44 @@ import re
14
14
  import socket
15
15
  import subprocess
16
16
  import sys
17
+ from pathlib import Path
17
18
 
18
19
  TOOLS_DIR = os.path.dirname(os.path.abspath(__file__))
19
20
 
20
21
 
22
+ COMMAND_BUDGETS = json.loads((Path(TOOLS_DIR) / "cli_budgets.json").read_text(encoding="utf-8"))
23
+
24
+
25
+ def command_timeout(script: str, args: list) -> int:
26
+ key = f"{Path(script).name}:{args[0] if args else ''}"
27
+ budget = COMMAND_BUDGETS.get(key, COMMAND_BUDGETS["default"])
28
+
29
+ def option(name, default):
30
+ return args[args.index(name) + 1] if name in args and args.index(name) + 1 < len(args) else default
31
+
32
+ def positive_int(value, default):
33
+ return int(value) if str(value).isdigit() and int(value) > 0 else default
34
+
35
+ if key == "screener.py:screen":
36
+ top = positive_int(option("--top", 20), 20)
37
+ workers = COMMAND_BUDGETS["l2_workers"]
38
+ budget += math.ceil(top / workers) * COMMAND_BUDGETS["l2_batch"]
39
+ elif key in ("watchlist.py:analyze", "watchlist_context.py:build"):
40
+ count = len([s for s in str(args[1] if len(args) > 1 else "").split(",") if s.strip()])
41
+ workers = positive_int(option("--workers", 3), 3)
42
+ budget += math.ceil(count / workers) * COMMAND_BUDGETS["watchlist_item"]
43
+ if key == "watchlist_context.py:build":
44
+ budget += math.ceil(count / min(workers * 2, 6)) * COMMAND_BUDGETS["anomaly_detect.py:detect"]
45
+ if "--include-market-review" in args:
46
+ budget += 3 * COMMAND_BUDGETS["market_review.py:review"] + 30
47
+ elif key == "market_review.py:review" and option("--market", "A") == "all":
48
+ budget = 3 * budget + 30
49
+ elif key == "technical.py:analyze" and "--periods" in args:
50
+ periods = {p.strip() for p in str(option("--periods", "daily")).split(",") if p.strip()}
51
+ budget *= len(periods | {option("--period", "daily")})
52
+ return budget
53
+
54
+
21
55
  def find_python() -> str:
22
56
  """Prefer the repo .venv interpreter; fall back to the current one.
23
57
 
@@ -29,12 +63,20 @@ def find_python() -> str:
29
63
  return venv if os.path.exists(venv) else sys.executable
30
64
 
31
65
 
32
- def run_tool(script: str, args: list, timeout: int = 30, parse_json: bool = True):
33
- """Run tools/<script> with an argv list (never a shell). Returns parsed JSON
34
- stdout (raw stripped stdout when parse_json=False), or None on any failure
35
- (non-zero exit, empty/invalid output, timeout) — callers pick their own
36
- sentinel with `or {}` / `or []`. Interpreter: find_python() (venv-first,
37
- so child processes get the .venv deps)."""
66
+ def run_tool(
67
+ script: str, args: list, timeout: int | None = None, parse_json: bool = True, preserve_errors: bool = False
68
+ ):
69
+ """Run a sibling CLI; opt in to safe error data, otherwise keep the None sentinel."""
70
+
71
+ if timeout is None:
72
+ timeout = command_timeout(script, args)
73
+
74
+ def failure(message, code):
75
+ if not preserve_errors:
76
+ return None
77
+ payload = {"error": scrub_secrets(message), "error_code": code}
78
+ return payload if parse_json else json.dumps(payload, ensure_ascii=False)
79
+
38
80
  try:
39
81
  r = subprocess.run(
40
82
  [find_python(), os.path.join(TOOLS_DIR, script), *args],
@@ -43,11 +85,24 @@ def run_tool(script: str, args: list, timeout: int = 30, parse_json: bool = True
43
85
  encoding="utf-8",
44
86
  timeout=timeout,
45
87
  )
46
- if r.returncode == 0 and r.stdout.strip():
47
- return json.loads(r.stdout) if parse_json else r.stdout.strip()
48
- except Exception:
49
- pass
50
- return None
88
+ raw = r.stdout.strip()
89
+ if not raw:
90
+ return failure("Python command returned no JSON", "empty_output")
91
+ if not preserve_errors:
92
+ return (json.loads(raw) if parse_json else raw) if r.returncode == 0 else None
93
+ try:
94
+ payload = json.loads(raw)
95
+ except ValueError:
96
+ return failure("Python command returned invalid JSON", "invalid_json")
97
+ if isinstance(payload, dict) and isinstance(payload.get("error"), str):
98
+ return failure(payload["error"], payload.get("error_code", "tool_error"))
99
+ if r.returncode != 0:
100
+ return failure(f"Python command failed (exit {r.returncode})", "process_failed")
101
+ return payload if parse_json else raw
102
+ except subprocess.TimeoutExpired:
103
+ return failure(f"Command timed out after {timeout}s", "timeout")
104
+ except Exception as exc:
105
+ return failure(f"Python command failed ({type(exc).__name__})", "process_failed")
51
106
 
52
107
 
53
108
  def utf8_stdio() -> None: