@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
package/index.ts CHANGED
@@ -1,3 +1,5 @@
1
+ import { withJsonInput } from "../scripts/json-input.mjs";
2
+ import { commandTimeout } from "../scripts/cli-timeout.mjs";
1
3
  import { existsSync } from "node:fs";
2
4
  import * as cp from "node:child_process";
3
5
  import { promisify } from "node:util";
@@ -12,7 +14,7 @@ type Executor = (bin: string, argv: string[]) => Promise<string>;
12
14
  const defaultExecutor: Executor = async (bin, argv) => {
13
15
  const exec = promisify(cp.execFile);
14
16
  try {
15
- const { stdout } = await exec(bin, argv, { maxBuffer: 32 * 1024 * 1024 });
17
+ const { stdout } = await exec(bin, argv, { maxBuffer: 32 * 1024 * 1024, timeout: commandTimeout(argv[0], argv.slice(1)) });
16
18
  return stdout;
17
19
  } catch (error) {
18
20
  const stdout = (error as { stdout?: string }).stdout;
@@ -22,7 +24,7 @@ const defaultExecutor: Executor = async (bin, argv) => {
22
24
  } catch {
23
25
  // A failed subprocess without JSON must not expose stderr or command arguments.
24
26
  }
25
- return JSON.stringify({ error: "Python command failed; check interpreter/dependencies" });
27
+ return JSON.stringify({ error: (error as { killed?: boolean }).killed ? "Python command timed out" : "Python command failed; check interpreter/dependencies" });
26
28
  }
27
29
  };
28
30
 
@@ -65,6 +67,190 @@ export default definePluginEntry({
65
67
  };
66
68
  const runPy = (script: string, args: string[]) =>
67
69
  executor(pythonBin(), [join(runtimeToolsDir, script), ...args]);
70
+ api.registerTool({
71
+ name: "compare_stocks",
72
+ description: "无状态同行指标比较:先用现有财务/行情工具取数,再传companies;仅相同unit/basis/period可排序,缺失不填零,不生成买卖综合分。",
73
+ parameters: Type.Object({
74
+ companies: Type.Array(Type.Object({
75
+ symbol: Type.String({"description": "唯一股票代码"}),
76
+ period: Type.String({"description": "统一可比期间;财务用报告期,估值用估值日"}),
77
+ metrics: Type.Array(Type.Object({
78
+ name: Type.String({"description": "指标名,如pe/roe/net_income"}),
79
+ value: Type.Union([Type.Number(), Type.Null()], {"description": "有限数值;缺失为null"}),
80
+ unit: Type.String({"description": "精确单位,如multiple/percent/fraction/CNY/USD"}),
81
+ basis: Type.String({"description": "口径,如TTM/annual/consolidated;区分累计与单季"}),
82
+ source: Type.Optional(Type.String({"description": "原始证据URL或字段路径"})),
83
+ }, {"additionalProperties": false}), {"description": "结构化指标,单位、口径明确,缺失不填零"}),
84
+ }, {"additionalProperties": false}), {"description": "2..30家公司,调用方确认可比性"}),
85
+ }, {"additionalProperties": false}),
86
+ async execute(_id, params) {
87
+ return asText(await withJsonInput(params, (path: string) =>
88
+ runPy("stateless_analysis.py", ["peers", "--input", path])));
89
+ },
90
+ });
91
+
92
+ api.registerTool({
93
+ name: "analyze_disclosure_changes",
94
+ description: "无状态公告财报比较:传新旧正文及指标,返回变更行号、来源与财务变化;负/零基数增长率为null。不下载PDF、不代替经济解读。",
95
+ parameters: Type.Object({
96
+ previous: Type.Object({
97
+ text: Type.String({"description": "已核实正文,最多200000字符;保留换行,PDF需宿主提取"}),
98
+ source: Type.String({"description": "原文URL或文档标识"}),
99
+ period: Type.String({"description": "报告期,如2025年度"}),
100
+ metrics: Type.Array(Type.Object({
101
+ name: Type.String({"description": "指标名,如pe/roe/net_income"}),
102
+ value: Type.Union([Type.Number(), Type.Null()], {"description": "有限数值;缺失为null"}),
103
+ unit: Type.String({"description": "精确单位,如multiple/percent/fraction/CNY/USD"}),
104
+ basis: Type.String({"description": "口径,如TTM/annual/consolidated;区分累计与单季"}),
105
+ source: Type.Optional(Type.String({"description": "原始证据URL或字段路径"})),
106
+ }, {"additionalProperties": false}), {"description": "结构化指标,单位、口径明确,缺失不填零"}),
107
+ }, {"additionalProperties": false}),
108
+ current: Type.Object({
109
+ text: Type.String({"description": "已核实正文,最多200000字符;保留换行,PDF需宿主提取"}),
110
+ source: Type.String({"description": "原文URL或文档标识"}),
111
+ period: Type.String({"description": "报告期,如2025年度"}),
112
+ metrics: Type.Array(Type.Object({
113
+ name: Type.String({"description": "指标名,如pe/roe/net_income"}),
114
+ value: Type.Union([Type.Number(), Type.Null()], {"description": "有限数值;缺失为null"}),
115
+ unit: Type.String({"description": "精确单位,如multiple/percent/fraction/CNY/USD"}),
116
+ basis: Type.String({"description": "口径,如TTM/annual/consolidated;区分累计与单季"}),
117
+ source: Type.Optional(Type.String({"description": "原始证据URL或字段路径"})),
118
+ }, {"additionalProperties": false}), {"description": "结构化指标,单位、口径明确,缺失不填零"}),
119
+ }, {"additionalProperties": false}),
120
+ max_changes: Type.Optional(Type.Number({"description": "变化上限1..100,默认30"})),
121
+ }, {"additionalProperties": false}),
122
+ async execute(_id, params) {
123
+ return asText(await withJsonInput(params, (path: string) =>
124
+ runPy("stateless_analysis.py", ["disclosure", "--input", path])));
125
+ },
126
+ });
127
+
128
+ api.registerTool({
129
+ name: "analyze_portfolio_risk",
130
+ description: "无状态现货多头组合风险:输入持仓、基准币种现金与汇率,返回集中度、币种/行业敞口、价格盈亏和止损情景。缺汇率报错;不保存账户。",
131
+ parameters: Type.Object({
132
+ positions: Type.Array(Type.Object({
133
+ symbol: Type.String({"description": "唯一代码,重复持仓先汇总"}),
134
+ quantity: Type.Number({"description": "正持仓数量"}),
135
+ price: Type.Number({"description": "正现价"}),
136
+ currency: Type.String({"description": "持仓币种,如CNY/USD/HKD"}),
137
+ cost: Type.Optional(Type.Number({"description": "同币种正成本价,可选"})),
138
+ stop_price: Type.Optional(Type.Number({"description": "同币种正止损价,可选"})),
139
+ sector: Type.Optional(Type.String({"description": "统一行业分类,可选"})),
140
+ as_of: Type.Optional(Type.String({"description": "实际估值时点,建议ISO8601"})),
141
+ }, {"additionalProperties": false}), {"description": "1..100个现货多头持仓"}),
142
+ base_currency: Type.String({"description": "基准币种"}),
143
+ cash: Type.Number({"description": "基准币种现金,非负"}),
144
+ fx_rates: Type.Optional(Type.Array(Type.Object({
145
+ currency: Type.String({"description": "唯一非基准币种"}),
146
+ rate: Type.Number({"description": "一单位该币种对应多少基准币种,正数"}),
147
+ }, {"additionalProperties": false}), {"description": "显式现价汇率;基准币种隐含1,不得重复"})),
148
+ histories: Type.Optional(Type.Array(Type.Object({
149
+ symbol: Type.String({"description": "对应唯一持仓股票"}),
150
+ prices: Type.Array(Type.Object({
151
+ date: Type.String({"description": "YYYY-MM-DD,唯一日期"}),
152
+ close: Type.Number({"description": "正有限收盘价"}),
153
+ }, {"additionalProperties": false}), {"description": "完整日K收盘序列,2..20000条,不得跨股票或混用复权口径"}),
154
+ }, {"additionalProperties": false}), {"description": "可选历史,共同日期本币价格收益相关性,不计汇率"})),
155
+ }, {"additionalProperties": false}),
156
+ async execute(_id, params) {
157
+ return asText(await withJsonInput(params, (path: string) =>
158
+ runPy("stateless_analysis.py", ["portfolio", "--input", path])));
159
+ },
160
+ });
161
+
162
+ api.registerTool({
163
+ name: "calculate_position_size",
164
+ description: "无状态多头仓位预算:同币种金额,按现金/风险预算/最大仓位/交易单位取最小数量,双边费用和滑点参与止损情景;不执行交易。",
165
+ parameters: Type.Object({
166
+ equity: Type.Number({"description": "总权益,正数"}),
167
+ cash: Type.Number({"description": "可用现金,0..equity"}),
168
+ entry_price: Type.Number({"description": "计划入场价,正数"}),
169
+ stop_price: Type.Number({"description": "正止损价,低于入场价"}),
170
+ risk_fraction: Type.Number({"description": "单笔风险占权益比例0..1,如0.01"}),
171
+ lot_size: Type.Number({"description": "正整数交易单位,用户确认,不猜港股每手数量"}),
172
+ max_position_fraction: Type.Optional(Type.Number({"description": "本次买入最大资金占比0..1,默认1;已有同股持仓先扣减额度"})),
173
+ fee_rate: Type.Optional(Type.Number({"description": "每边比例费用0..0.1,默认0;不含未提供税费/最低收费"})),
174
+ slippage_rate: Type.Optional(Type.Number({"description": "每边滑点0..0.1,默认0"})),
175
+ }, {"additionalProperties": false}),
176
+ async execute(_id, params) {
177
+ return asText(await withJsonInput(params, (path: string) =>
178
+ runPy("stateless_analysis.py", ["position_size", "--input", path])));
179
+ },
180
+ });
181
+
182
+ api.registerTool({
183
+ name: "analyze_event_study",
184
+ description: "无状态事件研究:提供同市场股票及基准完整价格、事件日期;事件前一交易日收盘为基点,计算交易日窗口收益差。缺窗口/基准为null,标注重叠,不推断因果。",
185
+ parameters: Type.Object({
186
+ prices: Type.Optional(Type.Array(Type.Object({
187
+ date: Type.String({"description": "YYYY-MM-DD,唯一日期"}),
188
+ close: Type.Number({"description": "正有限收盘价"}),
189
+ }, {"additionalProperties": false}), {"description": "完整日K收盘序列,2..20000条,不得跨股票或混用复权口径"})),
190
+ benchmark_prices: Type.Optional(Type.Array(Type.Object({
191
+ date: Type.String({"description": "YYYY-MM-DD,唯一日期"}),
192
+ close: Type.Number({"description": "正有限收盘价"}),
193
+ }, {"additionalProperties": false}), {"description": "完整日K收盘序列,2..20000条,不得跨股票或混用复权口径"})),
194
+ event_dates: Type.Array(Type.String({"description": "YYYY-MM-DD,盘后公告传下一交易日"}), {"description": "1..100个唯一事件日"}),
195
+ price_basis: Type.Optional(Type.String({"description": "仅显式prices模式必需;代码模式报告实际提供方标记,缺失为unknown,须核实"})),
196
+ horizons: Type.Optional(Type.Array(Type.Number({"description": "0=事件日,1=下一交易日;整数0..250"}), {"description": "1..20个窗口,默认0/1/5/10/20"})),
197
+ start_date: Type.Optional(Type.String({"description": "代码模式必需,YYYY-MM-DD,包含事件前基准日或训练窗口"})),
198
+ end_date: Type.Optional(Type.String({"description": "代码模式必需,YYYY-MM-DD,晚于start_date"})),
199
+ symbol: Type.Optional(Type.String({"description": "股票代码;与benchmark/start_date/end_date一起直接取数,和prices模式互斥"})),
200
+ benchmark: Type.Optional(Type.String({"description": "同市场基准代码;与symbol一起使用"})),
201
+ }, {"additionalProperties": false}),
202
+ async execute(_id, params) {
203
+ return asText(await withJsonInput(params, (path: string) =>
204
+ runPy("stateless_analysis.py", ["event_study", "--input", path])));
205
+ },
206
+ });
207
+
208
+ api.registerTool({
209
+ name: "validate_backtest",
210
+ description: "无状态回测稳健性:输入历史OHLCV和完整候选DSL;滚动训练选参数、后续不重叠窗口验证,列出全部样本内敏感性及跨标的结果。仅next_open,不自动优化或保存。",
211
+ parameters: Type.Object({
212
+ datasets: Type.Optional(Type.Array(Type.Object({
213
+ symbol: Type.String({"description": "唯一股票代码"}),
214
+ price_basis: Type.String({"description": "已核实复权/原始价格口径"}),
215
+ bars: Type.Array(Type.Object({
216
+ date: Type.String({"description": "YYYY-MM-DD"}),
217
+ open: Type.Number({"description": "有限OHLCV;价格为正、volume非负"}),
218
+ high: Type.Number({"description": "有限OHLCV;价格为正、volume非负"}),
219
+ low: Type.Number({"description": "有限OHLCV;价格为正、volume非负"}),
220
+ close: Type.Number({"description": "有限OHLCV;价格为正、volume非负"}),
221
+ volume: Type.Number({"description": "有限OHLCV;价格为正、volume非负"}),
222
+ }, {"additionalProperties": false}), {"description": "日期递增完整OHLCV,每组最多2000条,至少train_bars+test_bars"}),
223
+ }, {"additionalProperties": false}), {"description": "1..5个标的,复用get_kline取数"})),
224
+ strategies: Type.Array(Type.Object({
225
+ name: Type.String({"description": "唯一候选名"}),
226
+ strategy: Type.Object({}, {"additionalProperties": true, "description": "完整既有YAML DSL对应JSON,允许parameters引用;仅next_open"}),
227
+ }, {"additionalProperties": false}), {"description": "1..5个预先确定的候选,禁止测试结果回调参数"}),
228
+ train_bars: Type.Optional(Type.Number({"description": "训练交易日数30..1000,默认126"})),
229
+ test_bars: Type.Optional(Type.Number({"description": "测试交易日数30..1000,默认63"})),
230
+ capital: Type.Optional(Type.Number({"description": "每窗口初始资金,默认1000000"})),
231
+ start_date: Type.Optional(Type.String({"description": "代码模式必需,YYYY-MM-DD,包含事件前基准日或训练窗口"})),
232
+ end_date: Type.Optional(Type.String({"description": "代码模式必需,YYYY-MM-DD,晚于start_date"})),
233
+ symbols: Type.Optional(Type.Array(Type.String(), {"description": "1..5个唯一股票代码,配合start_date/end_date直接取数;和datasets互斥"})),
234
+ }, {"additionalProperties": false}),
235
+ async execute(_id, params) {
236
+ return asText(await withJsonInput(params, (path: string) =>
237
+ runPy("stateless_analysis.py", ["robustness", "--input", path])));
238
+ },
239
+ });
240
+
241
+ api.registerTool({
242
+ name: "compare_analysis_snapshots",
243
+ description: "无状态快照比较:传新旧JSON,返回JSON Pointer及新增/删除/变化/失效/恢复;不保存快照。数组整体比较,调用前按symbol对齐。",
244
+ parameters: Type.Object({
245
+ previous: Type.Object({}, {"additionalProperties": true, "description": "JSON对象,详见共享Skill与README"}),
246
+ current: Type.Object({}, {"additionalProperties": true, "description": "JSON对象,详见共享Skill与README"}),
247
+ }, {"additionalProperties": false}),
248
+ async execute(_id, params) {
249
+ return asText(await withJsonInput(params, (path: string) =>
250
+ runPy("stateless_analysis.py", ["snapshot", "--input", path])));
251
+ },
252
+ });
253
+
68
254
  // --- Data Tools ---
69
255
 
70
256
  api.registerTool({
@@ -198,7 +384,7 @@ export default definePluginEntry({
198
384
  api.registerTool({
199
385
  name: "get_kline",
200
386
  description:
201
- "获取股票K线数据(OHLCV)。支持A股(如600519)、港股(如00700.HK)、美股(如AAPL)、日股(如7203.T)、韩股(如005930.KS)、台股(如2330.TW)及A股ETF。A股股票/ETF返回前复权价格,每条记录 adjusted=qfq;sh000xxx/sz399xxx 指数返回原始点位,adjusted=none。需要历史价格自行计算或画图时用;只问指标用 get_technical_analysis,只问现价用 get_quote",
387
+ "获取股票K线数据(OHLCV)。支持A股(如600519)、港股(如00700.HK)、美股(如AAPL)、日股(如7203.T)、韩股(如005930.KS)、台股(如2330.TW)及A股ETF。A股股票/ETF返回前复权价格,每条记录 adjusted=qfq;sh000xxx/sz399xxx 指数返回原始点位,adjusted=none。需要历史价格自行计算或画图时用;只问指标用 get_technical_analysis,只问现价用 get_quote。每条记录附 source、UTC fetched_at、data_as_of 和 adjusted;非A股复权口径可能为total_return/qfq/unknown,未知不能假定已复权。部分来源附 adjustment_factor(复权价格/原始价格);缺失不能猜测换算系数。",
202
388
  parameters: Type.Object({
203
389
  symbol: Type.String({
204
390
  description: "股票代码,如 600519(A股)、00700.HK(港股)、AAPL(美股)、7203.T(日股)、005930.KS(韩股)、2330.TW(台股)",
@@ -226,7 +412,7 @@ export default definePluginEntry({
226
412
 
227
413
  api.registerTool({
228
414
  name: "get_quote",
229
- description: "获取股票实时行情报价(现价、涨跌幅、量比等)。支持A股、港股、美股、日股、韩股、台股;非交易时段返回最近交易日收盘价并以 as_of/stale 标注;ETF 的 premium_discount_rate 为正=溢价、负=折价",
415
+ description: "获取股票实时行情报价(现价、涨跌幅、量比等)。支持A股、港股、美股、日股、韩股、台股;非交易时段返回最近交易日收盘价并以 as_of/stale 标注;ETF 的 premium_discount_rate 为正=溢价、负=折价。返回 source、UTC fetched_at 和提供方 data_as_of(未知为null);as_of_basis区分提供方时间与交易日历推断,采集时间不等于行情时间。",
230
416
  parameters: Type.Object({
231
417
  symbol: Type.String({ description: "股票代码(A股如600519,美股如AAPL,港股如00700.HK)" }),
232
418
  }),
@@ -308,7 +494,7 @@ export default definePluginEntry({
308
494
  api.registerTool({
309
495
  name: "get_technical_analysis",
310
496
  description:
311
- "获取股票技术面分析(MA/MACD/RSI/BOLL/KDJ/成交量等指标 + 100分综合评分 + 6级买卖信号 + 趋势/偏离度/支撑压力位;多周期共振时 resonance.direction ∈ aligned_bullish/aligned_bearish/divergent)。个股技术面综合判断与买卖时机分析的首选;只要均线数值或自定义周期用 calculate_ma,专问量价用 get_volume_analysis,扫当日异动用 detect_anomaly",
497
+ "获取股票技术面分析(MA/MACD/RSI/BOLL/KDJ/成交量等指标 + 100分综合评分 + 6级买卖信号 + 趋势/偏离度/支撑压力位;附 trend_temperature(实验性EMA差/ATR描述;direction为均线方向;validation_status=not_validated,非星球指标,七档不作入场依据;另附 trend_horizons:21/63/252根日K月度动量,建议count=360,非概率、未验证);多周期共振时 resonance.direction ∈ aligned_bullish/aligned_bearish/divergent)。个股技术面综合判断与买卖时机分析的首选;只要均线数值或自定义周期用 calculate_ma,专问量价用 get_volume_analysis,扫当日异动用 detect_anomaly",
312
498
  parameters: Type.Object({
313
499
  symbol: Type.String({ description: "股票代码(A股如600519,美股如AAPL,港股如00700.HK)" }),
314
500
  period: Type.Optional(
@@ -632,7 +818,7 @@ export default definePluginEntry({
632
818
  api.registerTool({
633
819
  name: "screen_stocks",
634
820
  description:
635
- "全市场股票筛选(AlphaSift L1 多因子硬筛 + 市场情绪调节)。按PE/PB/市值/换手率/涨跌幅/量比等因子过滤和评分,可用 l2 开启质量/成长/动量/波动率/资金流增强。显式筛选条件缺少数据时报error,filters_applied只列实际执行的条件",
821
+ "全市场股票筛选(AlphaSift L1 多因子硬筛 + 市场情绪调节)。按PE/PB/市值/换手率/涨跌幅/量比等因子过滤和评分,可用 l2 开启质量/成长/动量/波动率/资金流增强。显式筛选条件缺少数据时报error,filters_applied只列实际执行的条件。候选factor_coverage列出可用/缺失因子、加权覆盖率和effective_weights;L1与L2均按可用因子归一化后排序,缺失/非有限值不按零分计;L2另返回effective_scores供结合市场系数复算final,按可用因子重归一化,高分不代表数据完整。选股预算按候选数量及采集批次计算,top须为正整数。",
636
822
  parameters: Type.Object({
637
823
  market: Type.Optional(
638
824
  Type.Union(
@@ -665,10 +851,26 @@ export default definePluginEntry({
665
851
  },
666
852
  });
667
853
 
854
+ api.registerTool({
855
+ name: "analyze_trend_strategy",
856
+ description: "月度右侧趋势策略:直接传同市场A/HK/US股票代码,自动获取日K,输出月度新入/持有/退出与逆波动预算。as_of默认最近已收盘交易日,持仓可选且不保存,不自动下单;跨样本仍not_validated。",
857
+ parameters: Type.Object({
858
+ symbols: Type.Array(Type.String(), { description: "同一市场的完整股票池,1..100只;A如600036,HK如0700.HK,US如AAPL" }),
859
+ as_of: Type.Optional(Type.String({ description: "可选已收盘截止日期YYYY-MM-DD,默认该市场最近已收盘交易日" })),
860
+ held_symbols: Type.Optional(Type.Array(Type.String(), { description: "可选,as_of时真实持股代码,必须在股票池中;省略代表初始空仓,不保存账户" })),
861
+ pending_exit_symbols: Type.Optional(Type.Array(Type.String(), { description: "可选,真实持股中此前已锁定且未成交的退出代码" })),
862
+ slots: Type.Optional(Type.Number({ description: "可选固定容量K,默认ceil(N/3),不得小于真实持股数量" })),
863
+ }, { additionalProperties: false }),
864
+ async execute(_id, params) {
865
+ return asText(await withJsonInput(params, (path: string) =>
866
+ runPy("trend_strategy.py", ["fetch", "--input", path])));
867
+ },
868
+ });
869
+
668
870
  api.registerTool({
669
871
  name: "run_backtest",
670
872
  description:
671
- "策略回测(AlphaEvo)。读取YAML策略定义,在历史数据上模拟交易,输出收益率/回撤/胜率等指标。只想知道单个技术信号的历史胜率用更轻量的 evaluate_signal。period为实际数据期间,requested_period保留请求期间,warnings提示覆盖差异;年化按实际期间计算",
873
+ "策略回测(AlphaEvo)。读取YAML策略定义,在历史数据上模拟交易,输出收益率/回撤/胜率等指标。只想知道单个技术信号的历史胜率用更轻量的 evaluate_signal。period为实际数据期间,requested_period保留请求期间,warnings提示覆盖差异;年化按实际期间计算。默认前日收盘信号、次日开盘成交;YAML simulation.execution=same_close可复现旧假设。execution返回模型、阻止成交次数和未模拟约束;零成交量及带历史限价的一字板不成交。支持 monthly_momentum:月初首根有效日K收盘观察过去period根对数收益,次日开盘;长周期需预热。",
672
874
  parameters: Type.Object({
673
875
  strategy: Type.String({ description: "策略YAML文件路径" }),
674
876
  symbol: Type.String({ description: "股票代码(A股如600519,美股如AAPL,港股如00700.HK)" }),
@@ -1016,7 +1218,7 @@ export default definePluginEntry({
1016
1218
  api.registerTool({
1017
1219
  name: "get_market_review",
1018
1220
  description:
1019
- "大盘复盘 — 获取市场日度复盘数据,包含指数、涨跌统计、板块排名、新闻、市场温度与策略建议。复盘类需求的首选,无需再分别调指数/统计/板块工具",
1221
+ "大盘复盘 — 获取市场日度复盘数据,包含指数、涨跌统计、板块排名、新闻、市场温度与策略建议。复盘类需求的首选,无需再分别调指数/统计/板块工具。数据不足时温度score及strategy_stance为null,信号unknown;warnings/data_quality说明限制",
1020
1222
  parameters: Type.Object({
1021
1223
  market: Type.Optional(
1022
1224
  Type.Union(
@@ -1141,7 +1343,7 @@ export default definePluginEntry({
1141
1343
  api.registerTool({
1142
1344
  name: "render_stock_report",
1143
1345
  description:
1144
- "股票分析报告渲染 — 将结构化报告 JSON 通过 j2 模板渲染为 Markdown。report 字段以 skill 提供的 report_schema 为准,不要自造字段。template: brief|full。全部分析完成后的最后一步调用。仅渲染,不保存不推送",
1346
+ "股票分析报告渲染 — 将结构化报告 JSON 通过 j2 模板渲染为 Markdown。report 字段以 skill 提供的 report_schema 为准,不要自造字段。template: brief|full。全部分析完成后的最后一步调用。仅渲染,不保存不推送。report可包含evidence(path/label/value/source/as_of)与data_quality(flags/limitations),brief/full均展示证据和限制。",
1145
1347
  parameters: Type.Object({
1146
1348
  report: Type.Object({}, { additionalProperties: true, description: "结构化股票报告 JSON" }),
1147
1349
  template: Type.Optional(
@@ -1201,7 +1403,7 @@ export default definePluginEntry({
1201
1403
  api.registerTool({
1202
1404
  name: "build_watchlist_context",
1203
1405
  description:
1204
- "自选股上下文包 — 对多只股票输出评分/趋势/异常/风险/建议 next_tools 的 agent 友好摘要。宿主 agent 决定如何写日报或深入分析",
1406
+ "自选股上下文包 — 对多只股票输出评分/趋势/异常/风险/建议 next_tools 的 agent 友好摘要。宿主 agent 决定如何写日报或深入分析。异动检查失败时anomaly_status=unavailable、anomaly_count=null,保留anomaly_error/warnings;汇总计入partial",
1205
1407
  parameters: Type.Object({
1206
1408
  symbols: Type.String({ description: "逗号分隔的股票代码列表" }),
1207
1409
  include_market_review: Type.Optional(
@@ -1318,7 +1520,7 @@ export default definePluginEntry({
1318
1520
  api.registerTool({
1319
1521
  name: "evaluate_signals",
1320
1522
  description:
1321
- "评估到期信号:拉取记录日之后的日K,判定 target_hit/stop_hit/timeout 并计算收益,回写存储。记录建议用 record_signal,胜率复盘用 get_signal_summary。历史K线未覆盖记录日时skipped_no_data并保持未结算,不能用较新行情代替",
1523
+ "评估到期信号:拉取记录日之后的日K,判定 target_hit/stop_hit/timeout 并计算收益,回写存储。记录建议用 record_signal,胜率复盘用 get_signal_summary。历史K线未覆盖记录日时skipped_no_data并保持未结算,不能用较新行情代替。原始信号价与复权K线须有可核实的adjustment_factor,缺失则skipped_price_basis保持未结算。CLI预算300秒,截止前返回并保存已完成结果;complete/deferred/warnings说明未处理记录,下次可重试",
1322
1524
  parameters: Type.Object({
1323
1525
  symbol: Type.Optional(
1324
1526
  Type.String({ description: "股票代码(可选,只评估该股的信号)" })
@@ -1335,7 +1537,7 @@ export default definePluginEntry({
1335
1537
  api.registerTool({
1336
1538
  name: "get_signal_summary",
1337
1539
  description:
1338
- "信号胜率汇总(可按 source/symbol/status 过滤):胜率、平均收益、结果分布与明细",
1540
+ "信号胜率汇总(可按 source/symbol/status 过滤):胜率、平均收益、结果分布与明细。by_source附avg_return_pct、return_samples和sample_warning;仅观察性复盘,样本少不能认定策略有效。",
1339
1541
  parameters: Type.Object({
1340
1542
  source: Type.Optional(Type.String({ description: "按信号来源过滤(可选)" })),
1341
1543
  symbol: Type.Optional(Type.String({ description: "按股票代码过滤(可选)" })),
@@ -63,7 +63,15 @@
63
63
  "get_dividends",
64
64
  "get_announcements",
65
65
  "get_us_holdings",
66
- "get_insider_trades"
66
+ "get_insider_trades",
67
+ "compare_stocks",
68
+ "analyze_disclosure_changes",
69
+ "analyze_portfolio_risk",
70
+ "calculate_position_size",
71
+ "analyze_event_study",
72
+ "validate_backtest",
73
+ "compare_analysis_snapshots",
74
+ "analyze_trend_strategy"
67
75
  ]
68
76
  },
69
77
  "activation": {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@weaxs/openclaw-stock-analysis",
3
- "version": "0.2.6",
3
+ "version": "0.2.8",
4
4
  "description": "OpenClaw plugin for stock analysis, screening, and strategy backtesting across A/HK/US/JP/KR/TW markets",
5
5
  "type": "module",
6
6
  "main": "./index.ts",
@@ -18,17 +18,24 @@
18
18
  "type": "object",
19
19
  "description": "市场温度(来自 market_review.review)",
20
20
  "properties": {
21
- "score": { "type": "number", "minimum": 0, "maximum": 100 },
22
- "level": { "type": "string", "enum": ["constructive", "neutral", "weak"] },
23
- "signal": { "type": "string", "enum": ["green", "yellow", "red"] }
21
+ "score": { "type": ["number", "null"], "minimum": 0, "maximum": 100 },
22
+ "level": { "type": "string", "enum": ["constructive", "neutral", "weak", "unknown"] },
23
+ "signal": { "type": "string", "enum": ["green", "yellow", "red", "unknown"] }
24
24
  },
25
25
  "required": ["score", "signal"]
26
26
  },
27
27
  "strategy_stance": {
28
- "type": "string",
29
- "enum": ["offensive", "balanced", "defensive"],
28
+ "type": ["string", "null"],
29
+ "enum": ["offensive", "balanced", "defensive", null],
30
30
  "description": "建议策略姿态"
31
31
  },
32
+ "data_quality": {
33
+ "type": "object",
34
+ "properties": {
35
+ "flags": { "type": "array", "items": { "type": "string" } },
36
+ "limitations": { "type": "array", "items": { "type": "string" } }
37
+ }
38
+ },
32
39
  "regime": {
33
40
  "type": "object",
34
41
  "description": "市场阶段(来自 detect_market_regime)",
@@ -124,7 +124,71 @@
124
124
  "action_checklist": { "type": "array", "items": { "type": "string" } }
125
125
  }
126
126
  },
127
- "risk_warning": { "type": "array", "items": { "type": "string" } }
127
+ "risk_warning": { "type": "array", "items": { "type": "string" } },
128
+ "data_quality": {
129
+ "type": "object",
130
+ "properties": {
131
+ "flags": {
132
+ "type": "array",
133
+ "items": {
134
+ "type": "string",
135
+ "enum": [
136
+ "partial_data",
137
+ "stale_quote",
138
+ "conflicting_data",
139
+ "insufficient_sample"
140
+ ]
141
+ }
142
+ },
143
+ "limitations": {
144
+ "type": "array",
145
+ "items": {
146
+ "type": "string"
147
+ }
148
+ }
149
+ },
150
+ "required": [
151
+ "flags",
152
+ "limitations"
153
+ ]
154
+ },
155
+ "evidence": {
156
+ "type": "array",
157
+ "items": {
158
+ "type": "object",
159
+ "properties": {
160
+ "path": {
161
+ "type": "string",
162
+ "description": "原始工具结果路径,例如 get_quote.price;已知返回对象中未提供的末级字段只能以 value=null 表示未知,其 source/as_of 可为 null,若填写必须来自父对象;不得跨越缺失对象或数组编造路径。"
163
+ },
164
+ "label": {
165
+ "type": "string",
166
+ "description": "读者可理解的指标名"
167
+ },
168
+ "value": {},
169
+ "source": {
170
+ "description": "引用已返回字段时,沿 path 继承最近父对象的 source(该键缺失时用 snapshot_source);子对象来源覆盖祖先,显式 null 保持未知。数组项和警告字符串同样继承,不能仅因叶子没有 source 就填 null;整条路径未提供来源时才填 null。",
171
+ "type": [
172
+ "string",
173
+ "null"
174
+ ]
175
+ },
176
+ "as_of": {
177
+ "description": "引用已返回字段时,沿 path 继承最近父对象的 data_as_of,子对象值(包括显式 null)覆盖祖先;数组项同样继承。整条路径均缺失时为 null,保留完整时间与时区。report_date 是报告期,不能代替此时间。",
178
+ "type": [
179
+ "string",
180
+ "null"
181
+ ]
182
+ }
183
+ },
184
+ "required": [
185
+ "path",
186
+ "value",
187
+ "source",
188
+ "as_of"
189
+ ]
190
+ }
191
+ }
128
192
  },
129
193
  "required": ["stock_name", "stock_code", "analysis_date", "sentiment_score",
130
194
  "decision_type", "confidence", "core_conclusion"]
@@ -0,0 +1,27 @@
1
+ import budgets from "../tools/cli_budgets.json" with { type: "json" };
2
+ import { basename } from "node:path";
3
+
4
+ // Hosts leave the CLI time to return its own structured failure.
5
+ export function commandTimeout(script, args) {
6
+ const key = `${basename(script)}:${args[0] ?? ""}`;
7
+ let budget = budgets[key] ?? budgets.default;
8
+ const option = (name, fallback) => args.includes(name) ? args[args.indexOf(name) + 1] ?? fallback : fallback;
9
+ const positiveInt = (value, fallback) => /^\d+$/.test(String(value)) && Number(value) > 0 ? Number(value) : fallback;
10
+ if (key === "screener.py:screen") {
11
+ budget += Math.ceil(positiveInt(option("--top", 20), 20) / budgets.l2_workers) * budgets.l2_batch;
12
+ } else if (key === "watchlist.py:analyze" || key === "watchlist_context.py:build") {
13
+ const count = String(args[1] ?? "").split(",").filter(s => s.trim()).length;
14
+ const workers = positiveInt(option("--workers", 3), 3);
15
+ budget += Math.ceil(count / workers) * budgets.watchlist_item;
16
+ if (key === "watchlist_context.py:build") {
17
+ budget += Math.ceil(count / Math.min(workers * 2, 6)) * budgets["anomaly_detect.py:detect"];
18
+ if (args.includes("--include-market-review")) budget += 3 * budgets["market_review.py:review"] + 30;
19
+ }
20
+ } else if (key === "market_review.py:review" && option("--market", "A") === "all") {
21
+ budget = 3 * budget + 30;
22
+ } else if (key === "technical.py:analyze" && args.includes("--periods")) {
23
+ const periods = String(option("--periods", "daily")).split(",").map(p => p.trim()).filter(Boolean);
24
+ budget *= new Set([option("--period", "daily"), ...periods]).size;
25
+ }
26
+ return budget * 1000 + 30_000;
27
+ }
@@ -0,0 +1,26 @@
1
+ import { mkdtemp, writeFile, rm } from "node:fs/promises";
2
+ import { tmpdir } from "node:os";
3
+ import { join } from "node:path";
4
+
5
+ // Large reports/K-lines exceed Windows argv limits. Remove transport files even on failure.
6
+ export async function withJsonInput(input, execute) {
7
+ let directory;
8
+ let result;
9
+ try {
10
+ directory = await mkdtemp(join(tmpdir(), "stock-analysis-"));
11
+ const path = join(directory, "input.json");
12
+ await writeFile(path, JSON.stringify(input), { encoding: "utf8", mode: 0o600 });
13
+ result = await execute(path);
14
+ } catch {
15
+ result = JSON.stringify({ error: "Analysis command failed; check input and interpreter/dependencies" });
16
+ } finally {
17
+ if (directory) {
18
+ try {
19
+ await rm(directory, { recursive: true, force: true });
20
+ } catch {
21
+ result = JSON.stringify({ error: "Could not remove temporary analysis input" });
22
+ }
23
+ }
24
+ }
25
+ return result;
26
+ }
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: bull-trend
3
- description: 趋势交易:识别中长期趋势,制定入场、持仓和退出规则。用于趋势股持有、规则化趋势策略或肥尾收益分析。
3
+ description: 趋势交易:识别中长期趋势,制定入场、持仓和退出规则。用于趋势温度计算、趋势股持有、规则化趋势策略或肥尾收益分析。
4
4
  ---
5
5
 
6
6
  # 趋势追踪分析
@@ -13,6 +13,10 @@ description: 趋势交易:识别中长期趋势,制定入场、持仓和退
13
13
 
14
14
  仅解释肥尾概念时,到此完成;下述流程用于具体标的的趋势分析。
15
15
 
16
+ 用户要求运行股票池月度右侧趋势策略时,MUST 先读取 [月度右侧趋势策略](references/monthly-trend-strategy.md),将股票名称解析为代码、按市场分组,直接调用 `analyze_trend_strategy(symbols, ...)` 自动取行情;仅在用户提供时传入真实持股集合,报告动作、原因与新仓预算。MUST 保留 `not_validated` 及跨样本失败边界;用户明确采用的规则可输出条件计划,实际成交和个人持仓由调用方核实。
17
+
18
+ 仅要求解释多期限方向或复核旧温度时,先读取 [多期限月度趋势](references/trend-horizons.md),调用 `get_technical_analysis` 的 daily、count=360,优先解释 `trend_horizons` 的21/63/252期限组成、方向与观察日期。当前仍为 `not_validated`,MUST 说明交易有效性未被完整验证,MUST NOT 自行转换成交易建议。七档温度或旧模型复核才读取 [独立趋势温度](references/trend-temperature.md)并解释兼容字段 `trend_temperature`;仅用户明确要求七档时展示研究标签,不能把“平”当作零方向。这些都不是趋势动物、肥尾 κ、原综合评分或市场复盘温度;用户自定条件的研究回测仍可运行。
19
+
16
20
  ## 执行流程
17
21
 
18
22
  ### 1. 采集数据
@@ -25,6 +29,8 @@ python3 scripts/gather.py <symbol>
25
29
 
26
30
  确认数据日期、周期和复权口径;120 根日K线用于近期趋势判断。肥尾分支按参考文件另取历史收益,报告实际取得的区间和样本量。
27
31
 
32
+ 多期限分支报告 `model/validation_status/components/positive_count/negative_count/neutral_count/direction/decision_as_of/as_of/price_basis`;不足月初预热时先解释不可用,不能改用零值。通用采集脚本仍默认120根,不能据它声称已完成252根趋势判断,需另取daily、count=360。旧温度分支报告模型、EMA差方向、分数、日期及口径;七档只按明确请求补充。先确认观察K线收盘,未知价格口径需说明;不把样本不足当中性趋势。
33
+
28
34
  ### 2. 趋势确认
29
35
 
30
36
  **多头趋势确认条件**:
@@ -79,3 +85,7 @@ python3 scripts/gather.py <symbol>
79
85
  4. 入场/持有/离场建议
80
86
  5. 初始风险、保护位和退出触发条件
81
87
  6. 数据或成交限制;肥尾分支附计算口径和不确定性
88
+
89
+ ### 市场环境入场实验
90
+
91
+ 用户要求验证宽基右侧条件如何约束趋势入场时,读取[多期限参考中的市场环境实验](references/trend-horizons.md#市场环境入场实验),准备带足预热的个股/同市场宽基daily OHLCV JSON,再运行 `scripts/market_trend.py`。该脚本调用共享Python核心,输出真实规则的三期限研究结果。MUST 分清初始空仓与已有持仓、观察与成交、开发集与新标的复核;不得拿七档标签代替入场条件,或将通过单次历史门槛称为稳定有效。
@@ -0,0 +1,47 @@
1
+ # 月度右侧趋势策略:上行SMA200与波动预算
2
+
3
+ 开发样本曾通过效果门槛,扩展及历史样本仍未通过;`validation_status=not_validated`。采用它表示使用这套确定的规则,不表示已经验证未来收益。它不是趋势动物的私有温度公式。
4
+
5
+ ## 调用
6
+
7
+ 直接告诉Agent股票池即可,例如“用月度右侧趋势策略分析招商银行、工商银行和中国神华”。Agent解析代码后,调用四宿主共同的 `analyze_trend_strategy`:
8
+
9
+ ```json
10
+ {
11
+ "symbols": ["600036", "601398", "601088"],
12
+ "held_symbols": ["600036"]
13
+ }
14
+ ```
15
+
16
+ `symbols`为必填,其他字段均可选。插件自动获取整个股票池的日K,不要求用户准备文件或手工提供行情。混合市场由Agent按A/HK/US分组调用,各市场资金/币种独立。
17
+
18
+ |字段|要求|
19
+ |---|---|
20
+ |`symbols`|同一个市场的完整股票池,1–100只;A用六位代码,HK如`0700.HK`/`00700.HK`,US如`AAPL`;大小写与HK补零统一识别,同股不能重复|
21
+ |`as_of`|可选已收盘截止日期`YYYY-MM-DD`,默认交易所最近已收盘交易日;盘中排除当天未收盘K线,按实际日历处理夏令时与半日市|
22
+ |`held_symbols`|可选,as_of时真实持股代码,须在股票池中;省略表示初始空仓,Agent明确这个假设,挂买单不算持仓|
23
+ |`pending_exit_symbols`|可选,已发出但未成交的退出锁,必须在真实持仓内,价格恢复不撤销|
24
+ |`slots`|可选固定容量K,默认ceil(N/3),不得小于当前真实持股数量|
25
+
26
+ 默认取至少360根daily;历史截止日期会增加取数长度以保留预热,接口有历史总量上限。有效价格不足221根时不填零,也不发明入场条件。所有数据沿现有行情源故障切换;任一成员取数失败,返回`incomplete_pool`和失败代码,不生成缩小股票池的计划。已取数据不合格则返回`invalid_market_data`。核对返回的`as_of/quote_as_of/price_basis`,停牌或报价未更新的成员仍显式列出。持仓只作为本次输入,不保存账户。
27
+
28
+ ### 离线复核
29
+
30
+ 开发者需要复现冻结研究时,CLI仍支持 `python3 tools/trend_strategy.py --input snapshot.json`。离线快照包含market/as_of/histories及可选held_symbols/pending_exit_symbols/slots,每条历史需要date/close/volume,可保留adjusted;日期递增唯一,价格为正且有限,量非负,最大32 MiB普通文件。该入口只用于已有行情的离线复核,正常插件工具使用上面的股票代码参数。
31
+
32
+ ## 固定规则
33
+
34
+ 1. 以股票池正成交量日期并集中的每月第一根收盘为观察点。当天不能按该收盘立即成交,最早是后续有效开盘。月中返回`waiting_for_monthly_observation`,只显示当前条件,不用今天持仓倒推月初交易。
35
+ 2. 新入同时要求:close>SMA200,且SMA200高于21根有效价格以前的SMA200。按`log(close)-log(SMA200)`降序,代码破同分。
36
+ 3. 真实旧仓优先占K槽。个股仍在200线上就保持原股份,排名下降或均线斜率转负不触发换仓;无有效报价时保持并占槽。已有200失效则给出`exit_next_valid_open`。已锁定退出始终返回`exit_pending`。
37
+ 4. 每股sigma63为过去63段对数收益的样本标准差,需64根有效价格。参考中位数取观察日整个固定池有当日报价、sigma有限且>0的股票,包括尚不满足入场资格者。
38
+ 5. 新入预算系数=`0.8704/K × min(1, median_sigma63 / stock_sigma63)`。低波动不扩大原槽,高波动折减;真实旧仓不按这个比例重新等权,不补仓。0.8704沿用已拟合的开发参数。
39
+ 6. 没有合格新股可保持现金;空槽不必填满。选择新股不代表已经有可用现金或腾出槽位,须先确认退出真实成交。
40
+
41
+ ## 输出和执行边界
42
+
43
+ 报告`model/validation_status/status/as_of/observation_date/selected/reference_volatility/stocks`。每股有价格口径、报价日期、SMA200及21根前均线、distance、sigma63、资格、action、reason及new_budget_fraction。无充分旧仓历史时返回`insufficient_held_history`,不生成新的交易计划;先补齐历史。
44
+
45
+ `new_budget_fraction` 是下一执行批次开盘净值乘数,买入费用包含在预算内,**不是目标持仓权重,也不是买入股数**。真实成交还要核对可用现金、已完成卖出、实际整手、停牌/涨跌停/禁售、费用与结算;此工具没有订单簿、现金账本或成交模拟,不会自动下单。不使用复权close直接计算真实股数,不因一笔新仓没成交就当作已持有。
46
+
47
+ 单股`get_technical_analysis`的`trend_temperature`与`trend_horizons`仍可辅助解释,但不是这套组合规则。普通单股YAML回测也不能代替共享资金、旧仓保留和整池风险中位数。本工具不计算历史组合收益,不把信号计划冒充组合回测。