@dshtrading/strategies 0.1.0

package/lib/screeners/volume-breakout.js

@@ -0,0 +1,63 @@
+import { sma } from "@dshtrading/indicators";
+//#region src/screeners/volume-breakout.ts
+/**
+* 放量突破：收盘价创 lookback 日新高，且成交量 ≥ 均量的 volMultiple 倍——
+* 突破有效性的量能确认（无量突破不入选）。量比口径跨市场可比（比值无量纲）。
+*/
+const volumeBreakoutScreener = {
+	id: "scr.volume-breakout",
+	name: "放量突破",
+	summary: "收盘价创 N 日新高且成交量 ≥ 均量 M 倍，量价配合的突破筛选",
+	params: [{
+		key: "lookback",
+		label: "突破窗口(日)",
+		default: 20,
+		min: 5,
+		max: 60,
+		step: 5
+	}, {
+		key: "volMultiple",
+		label: "量能倍数",
+		default: 2,
+		min: 1,
+		max: 10,
+		step: .5
+	}],
+	columns: [{
+		key: "volRatio",
+		label: "量比(倍)"
+	}, {
+		key: "breakoutPct",
+		label: "突破幅度",
+		format: "percent"
+	}],
+	evaluate(bars, params) {
+		const lookback = Math.max(5, Math.round(params.lookback ?? 20));
+		const volMultiple = Math.max(1, params.volMultiple ?? 2);
+		const i = bars.length - 1;
+		if (i < lookback) return null;
+		const window = bars.slice(i - lookback, i);
+		const priorHigh = Math.max(...window.map((b) => b.high));
+		const volumes = bars.map((b) => b.volume);
+		const avgVolume = sma(volumes, lookback)[i];
+		if (avgVolume === void 0 || avgVolume <= 0) return null;
+		const close = bars[i].close;
+		const volume = bars[i].volume;
+		if (!(close > priorHigh) || !(volume >= volMultiple * avgVolume)) return null;
+		const volRatio = volume / avgVolume;
+		return {
+			metrics: {
+				volRatio,
+				breakoutPct: (close - priorHigh) / priorHigh * 100
+			},
+			reason: `放量 ${volRatio.toFixed(2)} 倍突破 ${lookback} 日高点`,
+			reasonKey: "scr.volume-breakout.reason",
+			reasonParams: {
+				ratio: volRatio.toFixed(2),
+				n: lookback
+			}
+		};
+	}
+};
+//#endregion
+export { volumeBreakoutScreener };

package/lib/types.d.ts

@@ -0,0 +1,81 @@
+import { Kline as Kline$1 } from "@dshtrading/indicators";
+//#region src/types.d.ts
+type StrategyHorizon = 'short' | 'swing' | 'long';
+type SignalAction = 'entry' | 'exit';
+interface StrategySignal {
+  /** bars 下标：信号在 bars[i] 收盘确认，engine 按 bars[i+1].open 成交 */
+  readonly index: number;
+  readonly time: number;
+  readonly action: SignalAction;
+  /** v1 只有 long/flat 两态（不做做空）；预留词汇避免后续破坏性变更 */
+  readonly direction: 'long' | 'flat';
+  readonly price: number;
+  readonly reason: string;
+  /** reason 的词典键（client-ui-strategies 词典约定 strat.<id>.reason.<kind>），
+   *  视图按当前语言渲染 t(reasonKey, reasonParams)；缺省回退 reason 原文。 */
+  readonly reasonKey?: string;
+  /** reasonKey 的 {placeholder} 插值参数（数值/枚举，与语言无关）。 */
+  readonly reasonParams?: Readonly<Record<string, string | number>>;
+}
+interface StrategyParamSpec {
+  readonly key: string;
+  readonly label: string;
+  readonly default: number;
+  readonly min: number;
+  readonly max: number;
+  readonly step: number;
+}
+interface StrategyDefinition {
+  readonly id: string;
+  readonly horizon: StrategyHorizon;
+  readonly name: string;
+  readonly summary: string;
+  readonly params: readonly StrategyParamSpec[];
+  /** 纯函数：无 IO/随机/全局态；同一输入必须同一输出（回测确定性） */
+  compute(bars: readonly Kline$1[], params: Readonly<Record<string, number>>): StrategySignal[];
+}
+interface TradeRecord {
+  readonly entryIndex: number;
+  readonly entryTime: number;
+  readonly entryPrice: number;
+  readonly exitIndex: number;
+  readonly exitTime: number;
+  readonly exitPrice: number;
+  readonly returnPercent: number;
+  readonly profit: number;
+  readonly holdingBars: number;
+  readonly exitReason: string;
+  /** exitReason 的词典键 + 插值参数（来自离场 signal 的 reasonKey/Params）。 */
+  readonly exitReasonKey?: string;
+  readonly exitReasonParams?: Readonly<Record<string, string | number>>;
+}
+interface EquityPoint {
+  readonly time: number;
+  readonly equity: number;
+  readonly drawdownPercent: number;
+}
+interface BacktestMetrics {
+  readonly totalReturn: number;
+  readonly cagr: number;
+  readonly maxDrawdown: number;
+  readonly sharpe: number;
+  readonly winRate: number;
+  readonly profitFactor: number;
+  readonly tradeCount: number;
+  readonly exposure: number;
+}
+interface BacktestResult {
+  readonly signals: readonly StrategySignal[];
+  readonly trades: readonly TradeRecord[];
+  readonly equity: readonly EquityPoint[];
+  readonly metrics: BacktestMetrics;
+  readonly initialCapital: number;
+  readonly finalCapital: number;
+}
+interface BacktestOptions {
+  readonly initialCapital?: number;
+  readonly feeRate?: number;
+  readonly slippage?: number;
+}
+//#endregion
+export { BacktestMetrics, BacktestOptions, BacktestResult, EquityPoint, type Kline$1 as Kline, SignalAction, StrategyDefinition, StrategyHorizon, StrategyParamSpec, StrategySignal, TradeRecord };

package/lib/validate-node.js

@@ -0,0 +1,40 @@
+import { validateCustomStrategy } from "./validate.js";
+import * as vm from "node:vm";
+//#region src/validate-node.ts
+/**
+* Node.js 宿主端专用策略校验执行器（node:vm 100ms 超时熔断，仿 indicators
+* 的 validate-node.ts——issue #31 规格：Node 侧 vm 沙箱 + 超时熔断）。
+*/
+const nodeStrategyComputeRunner = (computeSource, bars, params, timeoutMs = 100) => {
+	const sandbox = {
+		bars,
+		params,
+		result: null,
+		Math,
+		Array,
+		Object,
+		Number,
+		String,
+		Boolean,
+		Date
+	};
+	const trimmed = computeSource.trim();
+	let code;
+	if (/^(?:\([a-zA-Z0-9_,\s]*\)|[a-zA-Z0-9_]+)\s*=>/.test(trimmed) || /^function\b/.test(trimmed)) code = `"use strict"; const fn = (${trimmed}); result = fn(bars, params);`;
+	else code = `"use strict"; const fn = (function(bars, params) { ${trimmed} }); result = fn(bars, params);`;
+	const script = new vm.Script(code);
+	const context = vm.createContext(sandbox);
+	try {
+		script.runInContext(context, { timeout: timeoutMs });
+		return sandbox.result;
+	} catch (error) {
+		if (error?.code === "ERR_SCRIPT_EXECUTION_TIMEOUT" || String(error?.message).includes("timed out")) throw new Error(`策略试算执行超时（超过 ${timeoutMs}ms），可能存在死循环（如 while/for 未退出）`);
+		throw error;
+	}
+};
+/** Node.js 宿主端策略校验器：自动启用 node:vm 超时熔断保护。 */
+function validateCustomStrategyNode(raw) {
+	return validateCustomStrategy(raw, { runner: nodeStrategyComputeRunner });
+}
+//#endregion
+export { nodeStrategyComputeRunner, validateCustomStrategyNode };

package/lib/validate.d.ts

@@ -0,0 +1,28 @@
+import { StrategyDefinition, StrategySignal } from "./types.js";
+import { CustomStrategyRecord } from "./custom.js";
+import { AsyncComputeRunner, Kline } from "@dshtrading/indicators";
+//#region src/validate.d.ts
+type StrategyValidationResult = {
+  ok: true;
+  definition: StrategyDefinition;
+  record: CustomStrategyRecord;
+} | {
+  ok: false;
+  reason: string;
+};
+/** 将策略源码解析为可执行纯函数（浏览器端 new Function；Node 侧走 vm runner 试算）。 */
+declare function compileStrategySource(source: string): (bars: readonly Kline[], params: Readonly<Record<string, number>>) => StrategySignal[];
+/**
+ * 信号序列专用校验（引擎语义对齐：i 收盘确认、i+1 开盘成交可复算）。
+ * 返回 undefined = 通过；否则返回人话诊断（模型与 UI 直接可读）。
+ */
+declare function validateSignalSequence(signals: readonly unknown[], bars: readonly Kline[]): string | undefined;
+/**
+ * 自定义策略校验（异步——试算走可等待 runner，默认浏览器 Worker 超时熔断；
+ * Node 宿主侧传 validate-node.ts 的 vm 熔断 runner）。
+ */
+declare function validateCustomStrategy(raw: unknown, options?: {
+  runner?: AsyncComputeRunner;
+}): Promise<StrategyValidationResult>;
+//#endregion
+export { StrategyValidationResult, compileStrategySource, validateCustomStrategy, validateSignalSequence };

package/lib/validate.js

@@ -0,0 +1,264 @@
+import { createSampleBars, workerComputeRunner } from "@dshtrading/indicators";
+//#region src/validate.ts
+/**
+* 自定义策略安全校验器（issue #31 / P2）。浏览器端与宿主两侧共用（纯库，零 Node 依赖）：
+*
+* 1. 结构校验：id / title / horizon / summary / paramsJson / computeSource
+* 2. 源码体积与编译检查（16KB 上限，语法必须可编译）
+* 3. 多场景样例试算（复用 indicators 的特征 K 线：上涨/下跌/平盘/缺口/极短）
+* 4. **信号序列专用校验**（不复用指标的等长断言——信号序列语义不同）：
+*    - index 为整数、落在 [0, bars.length) 且严格单调递增；
+*    - time 与 bars[index].openTime 逐位一致；
+*    - action ∈ {entry, exit}、direction ∈ {long, flat} 且与 action 配对
+*      （entry→long、exit→flat）；
+*    - price 为有限数且等于 bars[index].close（i 收盘确认价，浮点容差）；
+*    - 序列可复算：从 flat 起步、entry/exit 严格交替（exit 时必须持仓、entry
+*      时必须空仓）——与回测引擎的成交语义一致（i 收盘确认、i+1 开盘成交）。
+* 5. 可插拔 runner：浏览器默认 Worker 超时熔断（indicators 的 workerComputeRunner），
+*    Node 侧传 vm 熔断 runner（validate-node.ts）。
+*/
+const ID_PATTERN = /^[a-z0-9_][a-z0-9_-]{1,31}$/;
+const PARAM_KEY_PATTERN = /^[a-zA-Z0-9_]{1,16}$/;
+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",
+	"long"
+];
+const DEFAULT_TIMEOUT_MS = 100;
+/** 将策略源码解析为可执行纯函数（浏览器端 new Function；Node 侧走 vm runner 试算）。 */
+function compileStrategySource(source) {
+	const trimmed = source.trim();
+	if (/^(?:\([a-zA-Z0-9_,\s]*\)|[a-zA-Z0-9_]+)\s*=>/.test(trimmed) || /^function\b/.test(trimmed)) return new Function(`"use strict"; return (${trimmed});`)();
+	return new Function("bars", "params", `"use strict";\n${trimmed}`);
+}
+/**
+* 信号序列专用校验（引擎语义对齐：i 收盘确认、i+1 开盘成交可复算）。
+* 返回 undefined = 通过；否则返回人话诊断（模型与 UI 直接可读）。
+*/
+function validateSignalSequence(signals, bars) {
+	let position = "flat";
+	let prevIndex = -1;
+	for (let i = 0; i < signals.length; i++) {
+		const s = signals[i];
+		if (typeof s !== "object" || s === null) return `signals[${i}] 必须是非空对象`;
+		const signal = s;
+		if (typeof signal.index !== "number" || !Number.isInteger(signal.index) || signal.index < 0 || signal.index >= bars.length) return `signals[${i}].index 必须是落在 [0, ${bars.length - 1}] 的整数（bar 下标），收到: ${String(signal.index)}`;
+		if (signal.index <= prevIndex) return `signals[${i}].index (${signal.index}) 必须严格大于前一个信号的 index (${prevIndex})——信号按 bar 下标单调递增`;
+		prevIndex = signal.index;
+		if (signal.time !== bars[signal.index].openTime) return `signals[${i}].time (${String(signal.time)}) 与 bars[${signal.index}].openTime (${String(bars[signal.index].openTime)}) 不一致——信号 time 必须等于确认 bar 的 openTime`;
+		if (signal.action !== "entry" && signal.action !== "exit") return `signals[${i}].action 必须是 "entry" 或 "exit"，收到: ${JSON.stringify(signal.action)}`;
+		if (signal.direction !== "long" && signal.direction !== "flat") return `signals[${i}].direction 必须是 "long" 或 "flat"，收到: ${JSON.stringify(signal.direction)}`;
+		const expectedDirection = signal.action === "entry" ? "long" : "flat";
+		if (signal.direction !== expectedDirection) return `signals[${i}].direction (${signal.direction}) 与 action (${signal.action}) 不配对——entry 对应 long，exit 对应 flat`;
+		if (typeof signal.price !== "number" || !Number.isFinite(signal.price)) return `signals[${i}].price 必须是有限数字（确认时收盘价），收到: ${String(signal.price)}`;
+		const close = bars[signal.index].close;
+		if (Math.abs(signal.price - close) > Math.max(1e-9, Math.abs(close) * 1e-6)) return `signals[${i}].price (${signal.price}) 与确认 bar 收盘价 (${close}) 不一致——信号在 i 收盘确认，price 必须等于 bars[i].close`;
+		if (typeof signal.reason !== "string" || !signal.reason.trim()) return `signals[${i}].reason 必须是非空字符串（人话解释）`;
+		if (signal.reason.length > MAX_REASON_LENGTH) return `signals[${i}].reason 超长（${signal.reason.length} > ${MAX_REASON_LENGTH}）`;
+		if (signal.action === "entry" && position === "long") return `signals[${i}] 在已持仓（前一个 entry 尚未 exit）时再次 entry——引擎不会重复开仓，序列不可复算`;
+		if (signal.action === "exit" && position === "flat") return `signals[${i}] 在空仓时 exit——没有可平的头寸，序列不可复算（首信号必须是 entry）`;
+		position = signal.action === "entry" ? "long" : "flat";
+	}
+}
+/**
+* 结构校验（无试算）——browser/node 校验器共用。
+*/
+function checkCustomStrategyStructure(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 (!ID_PATTERN.test(id)) return {
+		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,
+		reason: "策略 title 必须是 1-32 字符的非空字符串"
+	};
+	const horizon = input.horizon;
+	if (!HORIZONS.includes(horizon)) return {
+		ok: false,
+		reason: `策略 horizon 必须是 "short"、"swing" 或 "long"，收到: ${JSON.stringify(input.horizon)}`
+	};
+	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} 字符的非空字符串`
+	};
+	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 computeSource = typeof input.computeSource === "string" ? input.computeSource.trim() : "";
+	if (!computeSource) return {
+		ok: false,
+		reason: "缺少 computeSource 源码"
+	};
+	if (computeSource.length > MAX_SOURCE_LENGTH) return {
+		ok: false,
+		reason: `computeSource 源码长度 (${computeSource.length} B) 超出限制 (${MAX_SOURCE_LENGTH} B / 16KB)`
+	};
+	try {
+		compileStrategySource(computeSource);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: `源码语法错误或无法编译: ${String(error?.message ?? error)}`
+		};
+	}
+	return {
+		ok: true,
+		id,
+		title,
+		horizon,
+		summary,
+		params,
+		computeSource,
+		input
+	};
+}
+/**
+* 自定义策略校验（异步——试算走可等待 runner，默认浏览器 Worker 超时熔断；
+* Node 宿主侧传 validate-node.ts 的 vm 熔断 runner）。
+*/
+async function validateCustomStrategy(raw, options) {
+	const checked = checkCustomStrategyStructure(raw);
+	if (!checked.ok) return checked;
+	const { id, title, horizon, summary, params, computeSource, 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;
+	for (const scenario of scenarioNames) {
+		const bars = sampleScenarios[scenario];
+		let signals;
+		try {
+			signals = await runner(computeSource, bars, { ...defaultParamsMap }, DEFAULT_TIMEOUT_MS);
+		} catch (error) {
+			return {
+				ok: false,
+				reason: `在 ${scenario} 样例数据上试算执行报错: ${String(error?.message ?? error)}`
+			};
+		}
+		if (!Array.isArray(signals)) return {
+			ok: false,
+			reason: `compute 返回值必须是 StrategySignal[] 数组，${scenario} 场景实际返回类型为: ${typeof signals}`
+		};
+		const sequenceReason = validateSignalSequence(signals, bars);
+		if (sequenceReason !== void 0) return {
+			ok: false,
+			reason: `信号序列校验失败（${scenario} 场景）: ${sequenceReason}`
+		};
+	}
+	return {
+		ok: true,
+		definition: {
+			id,
+			horizon,
+			name: title,
+			summary,
+			params,
+			compute: compileStrategySource(computeSource)
+		},
+		record: {
+			id,
+			title,
+			horizon,
+			summary,
+			paramsJson: JSON.stringify(params),
+			computeSource,
+			createdAt: typeof input.createdAt === "number" ? input.createdAt : Date.now()
+		}
+	};
+}
+//#endregion
+export { compileStrategySource, validateCustomStrategy, validateSignalSequence };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "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.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./plugin": {
+      "types": "./lib/plugin.d.ts",
+      "default": "./lib/plugin.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "dependencies": {
+    "@dshtrading/indicators": "0.1.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-alpha.1"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.0",
+    "vitest": "^3.0.0",
+    "typescript": "^5.5.0",
+    "@dshtrading/api": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}