@weaxs/openclaw-stock-analysis 0.2.6 → 0.2.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/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
  }),
@@ -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(
@@ -668,7 +854,7 @@ export default definePluginEntry({
668
854
  api.registerTool({
669
855
  name: "run_backtest",
670
856
  description:
671
- "策略回测(AlphaEvo)。读取YAML策略定义,在历史数据上模拟交易,输出收益率/回撤/胜率等指标。只想知道单个技术信号的历史胜率用更轻量的 evaluate_signal。period为实际数据期间,requested_period保留请求期间,warnings提示覆盖差异;年化按实际期间计算",
857
+ "策略回测(AlphaEvo)。读取YAML策略定义,在历史数据上模拟交易,输出收益率/回撤/胜率等指标。只想知道单个技术信号的历史胜率用更轻量的 evaluate_signal。period为实际数据期间,requested_period保留请求期间,warnings提示覆盖差异;年化按实际期间计算。默认前日收盘信号、次日开盘成交;YAML simulation.execution=same_close可复现旧假设。execution返回模型、阻止成交次数和未模拟约束;零成交量及带历史限价的一字板不成交。",
672
858
  parameters: Type.Object({
673
859
  strategy: Type.String({ description: "策略YAML文件路径" }),
674
860
  symbol: Type.String({ description: "股票代码(A股如600519,美股如AAPL,港股如00700.HK)" }),
@@ -1016,7 +1202,7 @@ export default definePluginEntry({
1016
1202
  api.registerTool({
1017
1203
  name: "get_market_review",
1018
1204
  description:
1019
- "大盘复盘 — 获取市场日度复盘数据,包含指数、涨跌统计、板块排名、新闻、市场温度与策略建议。复盘类需求的首选,无需再分别调指数/统计/板块工具",
1205
+ "大盘复盘 — 获取市场日度复盘数据,包含指数、涨跌统计、板块排名、新闻、市场温度与策略建议。复盘类需求的首选,无需再分别调指数/统计/板块工具。数据不足时温度score及strategy_stance为null,信号unknown;warnings/data_quality说明限制",
1020
1206
  parameters: Type.Object({
1021
1207
  market: Type.Optional(
1022
1208
  Type.Union(
@@ -1141,7 +1327,7 @@ export default definePluginEntry({
1141
1327
  api.registerTool({
1142
1328
  name: "render_stock_report",
1143
1329
  description:
1144
- "股票分析报告渲染 — 将结构化报告 JSON 通过 j2 模板渲染为 Markdown。report 字段以 skill 提供的 report_schema 为准,不要自造字段。template: brief|full。全部分析完成后的最后一步调用。仅渲染,不保存不推送",
1330
+ "股票分析报告渲染 — 将结构化报告 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
1331
  parameters: Type.Object({
1146
1332
  report: Type.Object({}, { additionalProperties: true, description: "结构化股票报告 JSON" }),
1147
1333
  template: Type.Optional(
@@ -1201,7 +1387,7 @@ export default definePluginEntry({
1201
1387
  api.registerTool({
1202
1388
  name: "build_watchlist_context",
1203
1389
  description:
1204
- "自选股上下文包 — 对多只股票输出评分/趋势/异常/风险/建议 next_tools 的 agent 友好摘要。宿主 agent 决定如何写日报或深入分析",
1390
+ "自选股上下文包 — 对多只股票输出评分/趋势/异常/风险/建议 next_tools 的 agent 友好摘要。宿主 agent 决定如何写日报或深入分析。异动检查失败时anomaly_status=unavailable、anomaly_count=null,保留anomaly_error/warnings;汇总计入partial",
1205
1391
  parameters: Type.Object({
1206
1392
  symbols: Type.String({ description: "逗号分隔的股票代码列表" }),
1207
1393
  include_market_review: Type.Optional(
@@ -1318,7 +1504,7 @@ export default definePluginEntry({
1318
1504
  api.registerTool({
1319
1505
  name: "evaluate_signals",
1320
1506
  description:
1321
- "评估到期信号:拉取记录日之后的日K,判定 target_hit/stop_hit/timeout 并计算收益,回写存储。记录建议用 record_signal,胜率复盘用 get_signal_summary。历史K线未覆盖记录日时skipped_no_data并保持未结算,不能用较新行情代替",
1507
+ "评估到期信号:拉取记录日之后的日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
1508
  parameters: Type.Object({
1323
1509
  symbol: Type.Optional(
1324
1510
  Type.String({ description: "股票代码(可选,只评估该股的信号)" })
@@ -1335,7 +1521,7 @@ export default definePluginEntry({
1335
1521
  api.registerTool({
1336
1522
  name: "get_signal_summary",
1337
1523
  description:
1338
- "信号胜率汇总(可按 source/symbol/status 过滤):胜率、平均收益、结果分布与明细",
1524
+ "信号胜率汇总(可按 source/symbol/status 过滤):胜率、平均收益、结果分布与明细。by_source附avg_return_pct、return_samples和sample_warning;仅观察性复盘,样本少不能认定策略有效。",
1339
1525
  parameters: Type.Object({
1340
1526
  source: Type.Optional(Type.String({ description: "按信号来源过滤(可选)" })),
1341
1527
  symbol: Type.Optional(Type.String({ description: "按股票代码过滤(可选)" })),
@@ -63,7 +63,14 @@
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"
67
74
  ]
68
75
  },
69
76
  "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.7",
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
+ }
@@ -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 不得写成无异常或完整成功。