@dshtrading/strategies 0.1.4 → 0.1.6

package/lib/validate-node.d.ts

@@ -0,0 +1,10 @@
+import "./types.js";
+import { ScreenerValidationResult, StrategyValidationResult } from "./validate.js";
+import { Kline } from "@dshtrading/indicators";
+//#region src/validate-node.d.ts
+/** Node.js 宿主端策略校验器：自动启用 node:vm 超时熔断保护。 */
+declare function validateCustomStrategyNode(raw: unknown): Promise<StrategyValidationResult>;
+/** Node.js 宿主端选股器校验器：vm 熔断 runner 注入。 */
+declare function validateCustomScreenerNode(raw: unknown): Promise<ScreenerValidationResult>;
+//#endregion
+export { validateCustomScreenerNode, validateCustomStrategyNode };

package/lib/validate-node.js

@@ -1,4 +1,4 @@
-import { validateCustomStrategy } from "./validate.js";
+import { validateCustomScreener, validateCustomStrategy } from "./validate.js";
 import * as vm from "node:vm";
 //#region src/validate-node.ts
 /**
@@ -36,5 +36,22 @@ const nodeStrategyComputeRunner = (computeSource, bars, params, timeoutMs = 100)
 function validateCustomStrategyNode(raw) {
 	return validateCustomStrategy(raw, { runner: nodeStrategyComputeRunner });
 }
+/**
+* Node 宿主端选股器 evaluate 试算 runner（同一 vm 沙箱形态；返回值形状由
+* validateCustomScreener 的 ScreenerMatch 校验把关，此处不约束类型）。
+* 复用策略 vm runner，但超时文案归位为「选股器」（策略 runner 硬编码「策略试算」）。
+*/
+const nodeScreenerEvaluateRunner = (evaluateSource, bars, params, timeoutMs = 100) => {
+	try {
+		return Promise.resolve(nodeStrategyComputeRunner(evaluateSource, bars, params, timeoutMs));
+	} catch (error) {
+		if (error?.code === "ERR_SCRIPT_EXECUTION_TIMEOUT" || String(error?.message).includes("timed out")) return Promise.reject(/* @__PURE__ */ new Error(`选股器试算执行超时（超过 ${timeoutMs}ms），可能存在死循环（如 while/for 未退出）`));
+		return Promise.reject(error);
+	}
+};
+/** Node.js 宿主端选股器校验器：vm 熔断 runner 注入。 */
+function validateCustomScreenerNode(raw) {
+	return validateCustomScreener(raw, { runner: nodeScreenerEvaluateRunner });
+}
 //#endregion
-export { nodeStrategyComputeRunner, validateCustomStrategyNode };
+export { nodeScreenerEvaluateRunner, nodeStrategyComputeRunner, validateCustomScreenerNode, validateCustomStrategyNode };

package/lib/validate.d.ts

@@ -1,5 +1,7 @@
 import { StrategyDefinition, StrategySignal } from "./types.js";
 import { CustomStrategyRecord } from "./custom.js";
+import { ScreenerDefinition } from "./screeners/types.js";
+import { CustomScreenerRecord } from "./custom-screener.js";
 import { AsyncComputeRunner, Kline } from "@dshtrading/indicators";
 //#region src/validate.d.ts
 type StrategyValidationResult = {
@@ -24,5 +26,24 @@ declare function validateSignalSequence(signals: readonly unknown[], bars: reado
 declare function validateCustomStrategy(raw: unknown, options?: {
   runner?: AsyncComputeRunner;
 }): Promise<StrategyValidationResult>;
+type ScreenerValidationResult = {
+  ok: true;
+  definition: ScreenerDefinition;
+  record: CustomScreenerRecord;
+} | {
+  ok: false;
+  reason: string;
+};
+/**
+ * 自定义选股器校验（异步——试算走可等待 runner，默认浏览器 Worker 超时熔断；
+ * Node 宿主侧传 validate-node.ts 的 vm 熔断 runner）。
+ *
+ * 与策略校验的差异：evaluate 是「单时点截面判断」——无信号序列语义，
+ * 返回 null（未命中/数据不足跳过）或 ScreenerMatch（metrics 键 ⊆ columns 声明、
+ * 数值有限、reason 非空）。内置选股器 id 可覆盖（不再保留名）。
+ */
+declare function validateCustomScreener(raw: unknown, options?: {
+  runner?: AsyncComputeRunner;
+}): Promise<ScreenerValidationResult>;
 //#endregion
-export { StrategyValidationResult, compileStrategySource, validateCustomStrategy, validateSignalSequence };
+export { ScreenerValidationResult, StrategyValidationResult, compileStrategySource, validateCustomScreener, validateCustomStrategy, validateSignalSequence };

package/lib/validate.js

@@ -23,15 +23,6 @@ const MAX_SOURCE_LENGTH = 16384;
 const MAX_PARAMS_COUNT = 8;
 const MAX_SUMMARY_LENGTH = 120;
 const MAX_REASON_LENGTH = 200;
-/** 6 大范式 id 是系统保留名（custom_* 前缀或自定义名避免冲突）。 */
-const RESERVED_IDS = /* @__PURE__ */ new Set([
-	"donchian-breakout",
-	"rsi-reversion",
-	"ema-crossover",
-	"bollinger-reversion",
-	"sma-baseline",
-	"momentum-12m"
-]);
 const HORIZONS = [
 	"short",
 	"swing",
@@ -74,6 +65,81 @@ function validateSignalSequence(signals, bars) {
 	}
 }
 /**
+* 参数规格数组解析（策略/选股器校验共用）：JSON 解析 → StrategyParamSpec[]，
+* 保留合法正值 step（内置覆盖保存后参数步进不失真）。
+*/
+function parseParamSpecs(paramsJson) {
+	if (paramsJson === void 0) return {
+		ok: true,
+		params: []
+	};
+	if (typeof paramsJson !== "string") return {
+		ok: false,
+		reason: "paramsJson 必须是字符串（StrategyParamSpec[] 的 JSON）"
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(paramsJson);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: `paramsJson 不是合法 JSON: ${String(error?.message ?? error)}`
+		};
+	}
+	if (!Array.isArray(parsed)) return {
+		ok: false,
+		reason: "paramsJson 解析结果必须是数组（StrategyParamSpec[]）"
+	};
+	if (parsed.length > MAX_PARAMS_COUNT) return {
+		ok: false,
+		reason: `策略参数数量超出上限（至多 ${MAX_PARAMS_COUNT} 个）`
+	};
+	const params = [];
+	for (let index = 0; index < parsed.length; index++) {
+		const p = parsed[index];
+		if (typeof p !== "object" || p === null) return {
+			ok: false,
+			reason: `paramsJson[${index}] 必须是一个对象`
+		};
+		const spec = p;
+		const key = typeof spec.key === "string" ? spec.key.trim() : "";
+		if (!PARAM_KEY_PATTERN.test(key)) return {
+			ok: false,
+			reason: `paramsJson[${index}].key "${key}" 不合法：必须是 1-16 位字母数字或下划线`
+		};
+		const label = typeof spec.label === "string" ? spec.label.trim() : key;
+		const defVal = Number(spec.default);
+		const minVal = Number(spec.min);
+		const maxVal = Number(spec.max);
+		if (!Number.isFinite(defVal) || !Number.isFinite(minVal) || !Number.isFinite(maxVal)) return {
+			ok: false,
+			reason: `paramsJson[${index}] (${key}) 的 default、min、max 必须是有限数字`
+		};
+		if (minVal >= maxVal) return {
+			ok: false,
+			reason: `paramsJson[${index}] (${key}) 的 min (${minVal}) 必须严格小于 max (${maxVal})`
+		};
+		if (defVal < minVal || defVal > maxVal) return {
+			ok: false,
+			reason: `paramsJson[${index}] (${key}) 的 default (${defVal}) 必须在 [min, max] (${minVal}..${maxVal}) 范围内`
+		};
+		const stepVal = Number(spec.step);
+		const step = Number.isFinite(stepVal) && stepVal > 0 ? stepVal : 1;
+		params.push({
+			key,
+			label,
+			default: defVal,
+			min: minVal,
+			max: maxVal,
+			step
+		});
+	}
+	return {
+		ok: true,
+		params
+	};
+}
+/**
 * 结构校验（无试算）——browser/node 校验器共用。
 */
 function checkCustomStrategyStructure(raw) {
@@ -91,10 +157,6 @@ function checkCustomStrategyStructure(raw) {
 		ok: false,
 		reason: `策略 id "${id}" 不合法：必须由 2-32 位小写字母、数字、下划线或连字符组成`
 	};
-	if (RESERVED_IDS.has(id)) return {
-		ok: false,
-		reason: `策略 id "${id}" 是系统范式保留名称，请使用其他名称（如 custom_${id}）`
-	};
 	const title = typeof input.title === "string" ? input.title.trim() : "";
 	if (!title || title.length > 32) return {
 		ok: false,
@@ -110,67 +172,8 @@ function checkCustomStrategyStructure(raw) {
 		ok: false,
 		reason: `策略 summary 必须是 1-${MAX_SUMMARY_LENGTH} 字符的非空字符串`
 	};
-	let params = [];
-	if (input.paramsJson !== void 0) {
-		if (typeof input.paramsJson !== "string") return {
-			ok: false,
-			reason: "策略 paramsJson 必须是字符串（StrategyParamSpec[] 的 JSON）"
-		};
-		let parsed;
-		try {
-			parsed = JSON.parse(input.paramsJson);
-		} catch (error) {
-			return {
-				ok: false,
-				reason: `paramsJson 不是合法 JSON: ${String(error?.message ?? error)}`
-			};
-		}
-		if (!Array.isArray(parsed)) return {
-			ok: false,
-			reason: "paramsJson 解析结果必须是数组（StrategyParamSpec[]）"
-		};
-		if (parsed.length > MAX_PARAMS_COUNT) return {
-			ok: false,
-			reason: `策略参数数量超出上限（至多 ${MAX_PARAMS_COUNT} 个）`
-		};
-		for (let index = 0; index < parsed.length; index++) {
-			const p = parsed[index];
-			if (typeof p !== "object" || p === null) return {
-				ok: false,
-				reason: `paramsJson[${index}] 必须是一个对象`
-			};
-			const spec = p;
-			const key = typeof spec.key === "string" ? spec.key.trim() : "";
-			if (!PARAM_KEY_PATTERN.test(key)) return {
-				ok: false,
-				reason: `paramsJson[${index}].key "${key}" 不合法：必须是 1-16 位字母数字或下划线`
-			};
-			const label = typeof spec.label === "string" ? spec.label.trim() : key;
-			const defVal = Number(spec.default);
-			const minVal = Number(spec.min);
-			const maxVal = Number(spec.max);
-			if (!Number.isFinite(defVal) || !Number.isFinite(minVal) || !Number.isFinite(maxVal)) return {
-				ok: false,
-				reason: `paramsJson[${index}] (${key}) 的 default、min、max 必须是有限数字`
-			};
-			if (minVal >= maxVal) return {
-				ok: false,
-				reason: `paramsJson[${index}] (${key}) 的 min (${minVal}) 必须严格小于 max (${maxVal})`
-			};
-			if (defVal < minVal || defVal > maxVal) return {
-				ok: false,
-				reason: `paramsJson[${index}] (${key}) 的 default (${defVal}) 必须在 [min, max] (${minVal}..${maxVal}) 范围内`
-			};
-			params.push({
-				key,
-				label,
-				default: defVal,
-				min: minVal,
-				max: maxVal,
-				step: 1
-			});
-		}
-	}
+	const params = parseParamSpecs(input.paramsJson);
+	if (!params.ok) return params;
 	const computeSource = typeof input.computeSource === "string" ? input.computeSource.trim() : "";
 	if (!computeSource) return {
 		ok: false,
@@ -194,7 +197,7 @@ function checkCustomStrategyStructure(raw) {
 		title,
 		horizon,
 		summary,
-		params,
+		params: params.params,
 		computeSource,
 		input
 	};
@@ -260,5 +263,218 @@ async function validateCustomStrategy(raw, options) {
 		}
 	};
 }
+/** 选股器 id：强制 'scr.' 前缀与范式策略 id 空间隔离（内置 id 同形，可覆盖）。 */
+const SCREENER_ID_PATTERN = /^scr\.[a-z0-9_][a-z0-9_-]{1,31}$/;
+const MAX_COLUMNS_COUNT = 8;
+/**
+* 结构校验（无试算）：id / title / summary / paramsJson / columnsJson / evaluateSource。
+* evaluate 与 compute 同为 (bars, params) 纯函数，编译走同一 compileStrategySource。
+*/
+function checkCustomScreenerStructure(raw) {
+	if (typeof raw !== "object" || raw === null) return {
+		ok: false,
+		reason: "选股器配置必须是一个非空对象"
+	};
+	const input = raw;
+	const id = typeof input.id === "string" ? input.id.trim().toLowerCase() : "";
+	if (!id) return {
+		ok: false,
+		reason: "缺少选股器 id"
+	};
+	if (!SCREENER_ID_PATTERN.test(id)) return {
+		ok: false,
+		reason: `选股器 id "${id}" 不合法：必须以 "scr." 开头，后接 2-32 位小写字母、数字、下划线或连字符`
+	};
+	const title = typeof input.title === "string" ? input.title.trim() : "";
+	if (!title || title.length > 32) return {
+		ok: false,
+		reason: "选股器 title 必须是 1-32 字符的非空字符串"
+	};
+	const summary = typeof input.summary === "string" ? input.summary.trim() : "";
+	if (!summary || summary.length > MAX_SUMMARY_LENGTH) return {
+		ok: false,
+		reason: `选股器 summary 必须是 1-${MAX_SUMMARY_LENGTH} 字符的非空字符串`
+	};
+	const params = parseParamSpecs(input.paramsJson);
+	if (!params.ok) return params;
+	let columns = [];
+	if (typeof input.columnsJson !== "string" || !input.columnsJson.trim()) return {
+		ok: false,
+		reason: "缺少 columnsJson（ScreenerColumnSpec[] 的 JSON，至少 1 列）"
+	};
+	let parsedColumns;
+	try {
+		parsedColumns = JSON.parse(input.columnsJson);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: `columnsJson 不是合法 JSON: ${String(error?.message ?? error)}`
+		};
+	}
+	if (!Array.isArray(parsedColumns) || parsedColumns.length === 0) return {
+		ok: false,
+		reason: "columnsJson 解析结果必须是非空数组（ScreenerColumnSpec[]）"
+	};
+	if (parsedColumns.length > MAX_COLUMNS_COUNT) return {
+		ok: false,
+		reason: `结果列数量超出上限（至多 ${MAX_COLUMNS_COUNT} 列）`
+	};
+	for (let index = 0; index < parsedColumns.length; index++) {
+		const c = parsedColumns[index];
+		if (typeof c !== "object" || c === null) return {
+			ok: false,
+			reason: `columnsJson[${index}] 必须是一个对象`
+		};
+		const spec = c;
+		const key = typeof spec.key === "string" ? spec.key.trim() : "";
+		if (!PARAM_KEY_PATTERN.test(key)) return {
+			ok: false,
+			reason: `columnsJson[${index}].key "${key}" 不合法：必须是 1-16 位字母数字或下划线`
+		};
+		const label = typeof spec.label === "string" ? spec.label.trim() : key;
+		const format = spec.format === "percent" || spec.format === "number" ? spec.format : void 0;
+		columns.push(format === void 0 ? {
+			key,
+			label
+		} : {
+			key,
+			label,
+			format
+		});
+	}
+	if (new Set(columns.map((c) => c.key)).size !== columns.length) return {
+		ok: false,
+		reason: "columnsJson 存在重复的列 key"
+	};
+	const evaluateSource = typeof input.evaluateSource === "string" ? input.evaluateSource.trim() : "";
+	if (!evaluateSource) return {
+		ok: false,
+		reason: "缺少 evaluateSource 源码"
+	};
+	if (evaluateSource.length > MAX_SOURCE_LENGTH) return {
+		ok: false,
+		reason: `evaluateSource 源码长度 (${evaluateSource.length} B) 超出限制 (${MAX_SOURCE_LENGTH} B / 16KB)`
+	};
+	try {
+		compileStrategySource(evaluateSource);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: `源码语法错误或无法编译: ${String(error?.message ?? error)}`
+		};
+	}
+	return {
+		ok: true,
+		id,
+		title,
+		summary,
+		params: params.params,
+		columns,
+		evaluateSource,
+		input
+	};
+}
+/** 单个命中结果校验（null = 未命中合法；其余必须符合 ScreenerMatch 形状）。 */
+function checkScreenerMatch(value, columns, scenario) {
+	if (value === null || value === void 0) return void 0;
+	if (typeof value !== "object" || Array.isArray(value)) return `evaluate 返回值必须是 ScreenerMatch 对象或 null，${scenario} 场景实际为: ${typeof value}`;
+	const match = value;
+	if (typeof match.metrics !== "object" || match.metrics === null || Array.isArray(match.metrics)) return `ScreenerMatch.metrics 必须是 Record<string, number>（${scenario} 场景）`;
+	const columnKeys = new Set(columns.map((c) => c.key));
+	for (const [key, val] of Object.entries(match.metrics)) {
+		if (!columnKeys.has(key)) return `metrics 键 "${key}" 未在 columns 中声明（${scenario} 场景）——动态列必须先声明再产出`;
+		if (typeof val !== "number" || !Number.isFinite(val)) return `metrics["${key}"] 必须是有限数字（${scenario} 场景），收到: ${String(val)}`;
+	}
+	if (typeof match.reason !== "string" || !match.reason.trim()) return `ScreenerMatch.reason 必须是非空字符串（${scenario} 场景）`;
+	if (match.reason.length > MAX_REASON_LENGTH) return `reason 超长（${match.reason.length} > ${MAX_REASON_LENGTH}，${scenario} 场景）`;
+}
+/**
+* 自定义选股器校验（异步——试算走可等待 runner，默认浏览器 Worker 超时熔断；
+* Node 宿主侧传 validate-node.ts 的 vm 熔断 runner）。
+*
+* 与策略校验的差异：evaluate 是「单时点截面判断」——无信号序列语义，
+* 返回 null（未命中/数据不足跳过）或 ScreenerMatch（metrics 键 ⊆ columns 声明、
+* 数值有限、reason 非空）。内置选股器 id 可覆盖（不再保留名）。
+*/
+async function validateCustomScreener(raw, options) {
+	const checked = checkCustomScreenerStructure(raw);
+	if (!checked.ok) return checked;
+	const { id, title, summary, params, columns, evaluateSource, input } = checked;
+	const sampleScenarios = createSampleBars();
+	const scenarioNames = [
+		"uptrend",
+		"downtrend",
+		"flat",
+		"gap",
+		"short"
+	];
+	const runner = options?.runner ?? workerComputeRunner;
+	const defaultParamsMap = {};
+	for (const p of params) defaultParamsMap[p.key] = p.default;
+	const longScenario = [];
+	let longPrice = 100;
+	for (let i = 0; i < 300; i++) {
+		const drift = i < 100 ? .6 : i < 200 ? -.5 : .55;
+		longPrice = Math.max(1, longPrice + drift);
+		longScenario.push({
+			openTime: 17e11 + i * 864e5,
+			open: longPrice - drift / 2,
+			high: longPrice + .4,
+			low: longPrice - .4,
+			close: longPrice,
+			volume: i % 7 === 5 ? 5e3 : 800
+		});
+	}
+	const scenarios = [...scenarioNames.map((name) => ({
+		name,
+		bars: sampleScenarios[name]
+	})), {
+		name: "long",
+		bars: longScenario
+	}];
+	let matchedScenario = false;
+	for (const { name: scenario, bars } of scenarios) {
+		let match;
+		try {
+			match = await runner(evaluateSource, bars, { ...defaultParamsMap }, DEFAULT_TIMEOUT_MS);
+		} catch (error) {
+			return {
+				ok: false,
+				reason: `在 ${scenario} 样例数据上试算执行报错: ${String(error?.message ?? error)}`
+			};
+		}
+		const matchReason = checkScreenerMatch(match, columns, scenario);
+		if (matchReason !== void 0) return {
+			ok: false,
+			reason: matchReason
+		};
+		if (match !== null && match !== void 0) matchedScenario = true;
+	}
+	if (!matchedScenario) return {
+		ok: false,
+		reason: "选股器在全部样例场景（上涨/下跌/震荡/跳空/短序列/300根长序列）上都返回 null——请检查入场条件（阈值方向、数据长度 guard），至少一个场景应命中"
+	};
+	return {
+		ok: true,
+		definition: {
+			id,
+			name: title,
+			summary,
+			params,
+			columns,
+			evaluate: compileStrategySource(evaluateSource)
+		},
+		record: {
+			id,
+			title,
+			horizon: "swing",
+			summary,
+			paramsJson: JSON.stringify(params),
+			columnsJson: JSON.stringify(columns),
+			evaluateSource,
+			createdAt: typeof input.createdAt === "number" ? input.createdAt : Date.now()
+		}
+	};
+}
 //#endregion
-export { compileStrategySource, validateCustomStrategy, validateSignalSequence };
+export { compileStrategySource, validateCustomScreener, validateCustomStrategy, validateSignalSequence };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dshtrading/strategies",
   "description": "Trading strategies kernel for dsh-trading: pure math backtesting engine, strategy contracts, and 6 reference paradigms (short, swing, long). Pure library (zero runtime dependencies, browser-packable).",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -21,7 +21,8 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "dependencies": {
-    "@dshtrading/indicators": "0.1.4"
+    "@dshtrading/dsh-home": "^0.1.6",
+    "@dshtrading/indicators": "0.1.6"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.0",
@@ -31,7 +32,7 @@
     "tsdown": "^0.22.0",
     "vitest": "^3.0.0",
     "typescript": "^5.5.0",
-    "@dshtrading/api": "0.1.4"
+    "@dshtrading/api": "0.1.6"
   },
   "scripts": {
     "build": "tsdown",