@dshtrading/strategies 0.1.0

package/lib/paradigms/sma-baseline.js

@@ -0,0 +1,70 @@
+import { sma } from "@dshtrading/indicators";
+//#region src/paradigms/sma-baseline.ts
+/**
+* 200 日均线择时基线策略（长线，Meb Faber GTAA 经典）。
+*
+* 入场：收盘价站上 SMA200 牛市生命线，全仓持有。
+* 出场：收盘价跌破 SMA200 熊市防线，空仓避险。
+*/
+const smaBaselineStrategy = {
+	id: "sma-baseline",
+	horizon: "long",
+	name: "200 日均线牛熊择时基线",
+	summary: "收盘价站上 SMA200 均线做多，跌破均线空仓避险（长线资产配置经典基线）",
+	params: [{
+		key: "period",
+		label: "长期均线周期",
+		default: 200,
+		min: 50,
+		max: 300,
+		step: 10
+	}],
+	compute(bars, params) {
+		const period = Math.max(10, Math.round(params.period ?? 200));
+		const closes = bars.map((b) => b.close);
+		const smaValues = sma(closes, period);
+		const signals = [];
+		let inPosition = false;
+		for (let i = period - 1; i < bars.length; i++) {
+			const currentClose = bars[i].close;
+			const currentSma = smaValues[i];
+			if (currentSma === void 0) continue;
+			if (!inPosition && currentClose > currentSma) {
+				signals.push({
+					index: i,
+					time: bars[i].openTime,
+					action: "entry",
+					direction: "long",
+					price: currentClose,
+					reason: `收盘价 (${currentClose.toFixed(2)}) 站上长期基线 SMA(${period}) (${currentSma.toFixed(2)})，确立多头趋势`,
+					reasonKey: "strat.sma-baseline.reason.entry",
+					reasonParams: {
+						close: currentClose.toFixed(2),
+						period,
+						sma: currentSma.toFixed(2)
+					}
+				});
+				inPosition = true;
+			} else if (inPosition && currentClose < currentSma) {
+				signals.push({
+					index: i,
+					time: bars[i].openTime,
+					action: "exit",
+					direction: "flat",
+					price: currentClose,
+					reason: `收盘价 (${currentClose.toFixed(2)}) 跌破长期基线 SMA(${period}) (${currentSma.toFixed(2)})，转入防御避险`,
+					reasonKey: "strat.sma-baseline.reason.exit",
+					reasonParams: {
+						close: currentClose.toFixed(2),
+						period,
+						sma: currentSma.toFixed(2)
+					}
+				});
+				inPosition = false;
+			}
+		}
+		return signals;
+	}
+};
+//#endregion
+export { smaBaselineStrategy };

package/lib/plugin.d.ts

@@ -0,0 +1,44 @@
+import { StrategyDefinition } from "./types.js";
+import { CustomStrategyRecord, CustomStrategyStore } from "./custom.js";
+import { MarketDataService } from "./api/lib/index.js";
+import { createFileCustomStrategyStore } from "./custom-fs.js";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/plugin.d.ts
+/** Cordis 插件名 = patch 行 id（TEMPLATES §8），市场无关共享行命名空间。 */
+declare const name = "dsh-trading-strategies";
+/** 本插件不硬依赖任何服务（headless 宿主零要求）；tools/注册表经 ctx.inject 声明。 */
+declare const inject: string[];
+/** 默认存储路径：~/.dsh/strategies/custom.json。 */
+declare function defaultStorePath(): string;
+/** tradingEvents 的最小发布面（鸭式，不定死接口；总线缺席时静默降级）。 */
+interface TradingEventsPublisher {
+  emit(store: 'strategies'): void;
+}
+/** 注册表 + 老部署回退的行情解析面（与桥同款 registry-first 语义）。 */
+interface StrategyMarketDataResolver {
+  (market: string): MarketDataService | undefined;
+}
+declare function createMarketDataResolver(ctx: Context): StrategyMarketDataResolver;
+interface StrategyAuthorToolOptions {
+  store: CustomStrategyStore;
+  /** 可选：策略成功落盘后的回调（issue #30：事件总线 emit('strategies') 接线点）。 */
+  onWritten?: (record: CustomStrategyRecord) => void;
+}
+/** strategy_author 工厂（独立导出便于单测）。 */
+declare function createStrategyAuthorTool(options: StrategyAuthorToolOptions): import("@deepseek-ai/dsh-tools").ToolDefinition;
+interface StrategyBacktestToolOptions {
+  store: CustomStrategyStore;
+  marketData: StrategyMarketDataResolver;
+}
+/** 自定义或范式策略 → 回测用 StrategyDefinition（自定义 compute 经编译落定）。 */
+declare function resolveStrategyDefinition(store: CustomStrategyStore, strategyId: string): Promise<StrategyDefinition | undefined>;
+interface StrategyBacktestToolDeps {
+  store: CustomStrategyStore;
+  marketData: StrategyMarketDataResolver;
+}
+/** strategy_backtest 工厂（独立导出便于单测）。 */
+declare function createStrategyBacktestTool(deps: StrategyBacktestToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** Host plugin body：注册 strategy_author / strategy_backtest（host 平面，全会话可见）。 */
+declare function apply(ctx: Context): void;
+//#endregion
+export { StrategyAuthorToolOptions, StrategyBacktestToolDeps, StrategyBacktestToolOptions, StrategyMarketDataResolver, TradingEventsPublisher, apply, createFileCustomStrategyStore, createMarketDataResolver, createStrategyAuthorTool, createStrategyBacktestTool, defaultStorePath, inject, name, resolveStrategyDefinition };

package/lib/plugin.js

@@ -0,0 +1,214 @@
+import { run } from "./engine.js";
+import { compileStrategySource } from "./validate.js";
+import { getStrategyById } from "./paradigms/index.js";
+import "./index.js";
+import { createFileCustomStrategyStore } from "./custom-fs.js";
+import { validateCustomStrategyNode } from "./validate-node.js";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import os from "node:os";
+import path from "node:path";
+//#region src/plugin.ts
+/** Cordis 插件名 = patch 行 id（TEMPLATES §8），市场无关共享行命名空间。 */
+const name = "dsh-trading-strategies";
+/** 本插件不硬依赖任何服务（headless 宿主零要求）；tools/注册表经 ctx.inject 声明。 */
+const inject = [];
+/** 行情服务键映射（与 client-ui-trading/bridge 的 MARKET_SERVICE_KEYS 同词汇；本地副本避免跨包依赖）。 */
+const MARKET_SERVICE_KEYS = {
+	crypto: "tradingCryptoMarketData",
+	us: "tradingUsMarketData",
+	cn: "tradingCnMarketData",
+	hk: "tradingHkMarketData"
+};
+/** 默认存储路径：~/.dsh/strategies/custom.json。 */
+function defaultStorePath() {
+	return path.join(os.homedir(), ".dsh", "strategies", "custom.json");
+}
+function eventsOf(ctx) {
+	return ctx.get?.("tradingEvents", false);
+}
+function createMarketDataResolver(ctx) {
+	return (market) => {
+		const registry = ctx.get?.("tradingMarketDataRegistry", false);
+		if (registry !== void 0) return registry.active(market)?.service;
+		const key = MARKET_SERVICE_KEYS[market];
+		return key === void 0 ? void 0 : ctx.get?.(key);
+	};
+}
+/** strategy_author 工厂（独立导出便于单测）。 */
+function createStrategyAuthorTool(options) {
+	const { store, onWritten } = options;
+	return defineTool({
+		name: "strategy_author",
+		description: "Author, validate, and persist a custom trading strategy from JavaScript compute source. compute(bars, params) must return StrategySignal[] (entry/exit at bar close, filled at next bar open by the backtest engine). The validator runs sandbox trial calculations across multiple kline scenarios and replays the signal sequence for engine-replayability. If valid, the strategy is persisted and immediately available for backtesting and the strategy roster.",
+		parameters: {
+			id: {
+				type: "string",
+				required: true,
+				description: "Unique strategy id (2-32 chars: lowercase letters/digits/underscore/hyphen, e.g. \"ema-stop-takeprofit\"); the 6 built-in paradigm ids are reserved"
+			},
+			title: {
+				type: "string",
+				required: true,
+				description: "Display name (1-32 chars), e.g. \"双均线止损止盈\""
+			},
+			horizon: {
+				type: "string",
+				required: true,
+				description: "Strategy horizon: \"short\" (短线), \"swing\" (波段), or \"long\" (长线)"
+			},
+			summary: {
+				type: "string",
+				required: true,
+				description: "One-sentence idea summary (≤120 chars), shown in the roster and chat card"
+			},
+			paramsJson: {
+				type: "string",
+				description: "JSON string of StrategyParamSpec[] (optional, default []). Each spec: { key, label, default, min, max } with numeric default/min/max and min < max. JSON example: [{\"key\":\"fast\",\"label\":\"fast EMA\",\"default\":20,\"min\":2,\"max\":120}]"
+			},
+			computeSource: {
+				type: "string",
+				required: true,
+				description: "JavaScript pure function source, signature (bars, params) => StrategySignal[]. bars has { openTime, open, high, low, close, volume }. Each signal: { index, time, action: \"entry\"|\"exit\", direction: \"long\"|\"flat\", price: bars[index].close, reason }. Signals must be strictly index-increasing, start with entry, and alternate entry/exit."
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const args = raw ?? {};
+			const candidate = {
+				id: typeof args.id === "string" ? args.id : "",
+				title: typeof args.title === "string" ? args.title : "",
+				horizon: typeof args.horizon === "string" ? args.horizon : "",
+				summary: typeof args.summary === "string" ? args.summary : "",
+				paramsJson: typeof args.paramsJson === "string" && args.paramsJson.trim() ? args.paramsJson.trim() : "[]",
+				computeSource: typeof args.computeSource === "string" ? args.computeSource : "",
+				createdAt: Date.now()
+			};
+			const result = await validateCustomStrategyNode(candidate);
+			if (!result.ok) return `[strategy_author] Validation failed: ${result.reason}\nReview the requirements: compute(bars, params) returns StrategySignal[]; each signal confirms at bar close (price === bars[index].close, time === bars[index].openTime), indices strictly increase, the sequence starts with entry and strictly alternates entry/exit (the engine fills at the next bar's open).`;
+			await store.save(result.record);
+			onWritten?.(result.record);
+			const specSummary = result.definition.params.map((p) => `${p.key}=${p.default}`).join(", ");
+			return `[strategy_author] Successfully authored strategy "${result.record.title}" (id: ${result.record.id}, horizon: ${result.record.horizon}${specSummary ? `, params: ${specSummary}` : ""}). The strategy passed sandbox trials across 5 kline scenarios with engine-replayable signal sequences and is now persisted — call strategy_backtest with this id to backtest it.`;
+		}
+	});
+}
+/** 自定义或范式策略 → 回测用 StrategyDefinition（自定义 compute 经编译落定）。 */
+async function resolveStrategyDefinition(store, strategyId) {
+	const record = await store.get(strategyId);
+	if (record !== void 0) {
+		let params = [];
+		try {
+			const parsed = JSON.parse(record.paramsJson);
+			if (Array.isArray(parsed)) params = parsed;
+		} catch {
+			params = [];
+		}
+		return {
+			id: record.id,
+			horizon: record.horizon,
+			name: record.title,
+			summary: record.summary,
+			params,
+			compute: compileStrategySource(record.computeSource)
+		};
+	}
+	return getStrategyById(strategyId);
+}
+/** strategy_backtest 工厂（独立导出便于单测）。 */
+function createStrategyBacktestTool(deps) {
+	return defineTool({
+		name: "strategy_backtest",
+		description: "Backtest a strategy (custom authored via strategy_author, or a built-in paradigm like ema-crossover / donchian-breakout / rsi-reversion / bollinger-reversion / sma-baseline / momentum-12m) on a symbol and interval using the pure-function engine. Returns 8 metrics (totalReturn, cagr, maxDrawdown, sharpe, winRate, profitFactor, tradeCount, exposure), the trade list, and the equity curve. Signals confirm at bar close and fill at the next bar open with fee/slippage modeling; this is simulation only — it never places orders.",
+		parameters: {
+			strategyId: {
+				type: "string",
+				required: true,
+				description: "Strategy id — a custom id from strategy_author or a built-in paradigm id"
+			},
+			market: {
+				type: "string",
+				required: true,
+				description: "Market vocabulary: crypto | us | cn | hk"
+			},
+			symbol: {
+				type: "string",
+				required: true,
+				description: "Market-canonical symbol, e.g. BTCUSDT (crypto), AAPL (us), 600519.SH (cn), 00700.HK (hk)"
+			},
+			interval: {
+				type: "string",
+				description: "Kline interval (default \"1d\"), e.g. 1m/5m/15m/1h/4h/1d/1w/1M — subject to the market data provider vocabulary"
+			},
+			limit: {
+				type: "number",
+				description: "Kline count to backtest (default 200, capped by the provider)"
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const args = raw ?? {};
+			const strategyId = typeof args.strategyId === "string" ? args.strategyId.trim() : "";
+			const market = typeof args.market === "string" ? args.market.trim() : "";
+			const symbol = typeof args.symbol === "string" ? args.symbol.trim() : "";
+			const interval = typeof args.interval === "string" && args.interval.trim() ? args.interval.trim() : "1d";
+			const limit = typeof args.limit === "number" && Number.isFinite(args.limit) && args.limit > 0 ? Math.min(Math.floor(args.limit), 1e3) : 200;
+			if (!strategyId || !market || !symbol) throw new Error("strategy_backtest: strategyId, market and symbol are required");
+			const definition = await resolveStrategyDefinition(deps.store, strategyId);
+			if (definition === void 0) throw new Error(`strategy_backtest: unknown strategyId "${strategyId}" — author one with strategy_author first, or use a built-in paradigm id (donchian-breakout, rsi-reversion, ema-crossover, bollinger-reversion, sma-baseline, momentum-12m)`);
+			const service = deps.marketData(market);
+			if (service === void 0) throw new Error(`strategy_backtest: no market data service for market "${market}" — install/activate a market connector first`);
+			const bars = await service.getKlines(symbol, interval, limit);
+			if (!Array.isArray(bars) || bars.length === 0) throw new Error(`strategy_backtest: no klines returned for ${symbol} (${market}, ${interval}) — check the symbol/interval vocabulary`);
+			const result = run(bars, definition);
+			return JSON.stringify({
+				ok: true,
+				strategy: {
+					id: definition.id,
+					name: definition.name,
+					horizon: definition.horizon
+				},
+				market,
+				symbol,
+				interval,
+				barsTested: bars.length,
+				metrics: result.metrics,
+				trades: result.trades,
+				equity: result.equity,
+				initialCapital: result.initialCapital,
+				finalCapital: result.finalCapital
+			});
+		}
+	});
+}
+/** Host plugin body：注册 strategy_author / strategy_backtest（host 平面，全会话可见）。 */
+function apply(ctx) {
+	const store = createFileCustomStrategyStore(defaultStorePath());
+	ctx.inject(["tools"], (toolCtx) => {
+		const tools = toolCtx.tools;
+		if (!tools || typeof tools.register !== "function") return;
+		const authorTool = createStrategyAuthorTool({
+			store,
+			onWritten: () => eventsOf(ctx)?.emit("strategies")
+		});
+		if (tools.get(authorTool.name) === void 0) tools.register(authorTool);
+		const backtestTool = createStrategyBacktestTool({
+			store,
+			marketData: createMarketDataResolver(ctx)
+		});
+		if (tools.get(backtestTool.name) === void 0) tools.register(backtestTool);
+	});
+}
+//#endregion
+export { apply, createFileCustomStrategyStore, createMarketDataResolver, createStrategyAuthorTool, createStrategyBacktestTool, defaultStorePath, inject, name, resolveStrategyDefinition };

package/lib/screeners/above-ma.d.ts

@@ -0,0 +1 @@
+import "./types.js";

package/lib/screeners/above-ma.js

@@ -0,0 +1,66 @@
+import { sma } from "@dshtrading/indicators";
+//#region src/screeners/above-ma.ts
+/**
+* 牛熊线之上：现价站上长期均线且均线自身斜率向上——与量化「200 日均线
+* 牛熊择时基线」同源的长线标的筛选（Faber GTAA 的截面版）。
+*/
+const aboveMaScreener = {
+	id: "scr.above-ma",
+	name: "站上牛熊线",
+	summary: "现价站上长期均线且均线斜率向上，筛选长线多头环境的标的",
+	params: [{
+		key: "period",
+		label: "牛熊线周期",
+		default: 200,
+		min: 50,
+		max: 300,
+		step: 10
+	}, {
+		key: "slopeBars",
+		label: "斜率窗口(日)",
+		default: 20,
+		min: 5,
+		max: 60,
+		step: 5
+	}],
+	columns: [{
+		key: "aboveMaPct",
+		label: "高于均线",
+		format: "percent"
+	}, {
+		key: "maSlopePct",
+		label: "均线斜率",
+		format: "percent"
+	}],
+	evaluate(bars, params) {
+		const period = Math.max(50, Math.round(params.period ?? 200));
+		const slopeBars = Math.max(5, Math.round(params.slopeBars ?? 20));
+		const i = bars.length - 1;
+		if (i < period + slopeBars - 1) return null;
+		const closes = bars.map((b) => b.close);
+		const maSeries = sma(closes, period);
+		const ma = maSeries[i];
+		const maPrev = maSeries[i - slopeBars];
+		if (ma === void 0 || maPrev === void 0 || !(maPrev > 0)) return null;
+		const close = bars[i].close;
+		if (!(close > ma) || !(ma > maPrev)) return null;
+		const aboveMaPct = (close - ma) / ma * 100;
+		const maSlopePct = (ma - maPrev) / maPrev * 100;
+		return {
+			metrics: {
+				aboveMaPct,
+				maSlopePct
+			},
+			reason: `现价高于 SMA(${period}) ${aboveMaPct.toFixed(2)}%，均线 ${slopeBars} 日斜率 +${maSlopePct.toFixed(2)}%`,
+			reasonKey: "scr.above-ma.reason",
+			reasonParams: {
+				period,
+				above: aboveMaPct.toFixed(2),
+				slope: slopeBars,
+				slopePct: maSlopePct.toFixed(2)
+			}
+		};
+	}
+};
+//#endregion
+export { aboveMaScreener };

package/lib/screeners/index.d.ts

@@ -0,0 +1,11 @@
+import { ScreenerColumnSpec, ScreenerDefinition, ScreenerMatch } from "./types.js";
+import "./ma-bull-align.js";
+import "./volume-breakout.js";
+import "./rsi-oversold.js";
+import "./near-high.js";
+import "./above-ma.js";
+//#region src/screeners/index.d.ts
+declare const screenerParadigms: readonly ScreenerDefinition[];
+declare function getScreenerById(id: string): ScreenerDefinition | undefined;
+//#endregion
+export { type ScreenerColumnSpec, type ScreenerDefinition, type ScreenerMatch, getScreenerById, screenerParadigms };

package/lib/screeners/index.js

@@ -0,0 +1,18 @@
+import { maBullAlignScreener } from "./ma-bull-align.js";
+import { volumeBreakoutScreener } from "./volume-breakout.js";
+import { rsiOversoldScreener } from "./rsi-oversold.js";
+import { nearHighScreener } from "./near-high.js";
+import { aboveMaScreener } from "./above-ma.js";
+//#region src/screeners/index.ts
+const screenerParadigms = [
+	maBullAlignScreener,
+	volumeBreakoutScreener,
+	rsiOversoldScreener,
+	nearHighScreener,
+	aboveMaScreener
+];
+function getScreenerById(id) {
+	return screenerParadigms.find((s) => s.id === id);
+}
+//#endregion
+export { getScreenerById, screenerParadigms };

package/lib/screeners/ma-bull-align.d.ts

@@ -0,0 +1 @@
+import "./types.js";

package/lib/screeners/ma-bull-align.js

@@ -0,0 +1,68 @@
+import { sma } from "@dshtrading/indicators";
+//#region src/screeners/ma-bull-align.ts
+/**
+* 均线多头排列：现价站上三线，且短中期均线自上而下依次压制
+* （SMA(短) > SMA(中) > SMA(长)），趋势结构完整的顺势筛选。
+*/
+const maBullAlignScreener = {
+	id: "scr.ma-bull-align",
+	name: "均线多头排列",
+	summary: "现价站上三线且 SMA(短) > SMA(中) > SMA(长)，筛选趋势结构完整的标的",
+	params: [
+		{
+			key: "n1",
+			label: "短期均线",
+			default: 20,
+			min: 5,
+			max: 120,
+			step: 5
+		},
+		{
+			key: "n2",
+			label: "中期均线",
+			default: 60,
+			min: 20,
+			max: 250,
+			step: 10
+		},
+		{
+			key: "n3",
+			label: "长期均线",
+			default: 120,
+			min: 50,
+			max: 300,
+			step: 10
+		}
+	],
+	columns: [{
+		key: "distLongPct",
+		label: "距长期均线",
+		format: "percent"
+	}],
+	evaluate(bars, params) {
+		const n1 = Math.max(5, Math.round(params.n1 ?? 20));
+		const n2 = Math.max(n1, Math.round(params.n2 ?? 60));
+		const n3 = Math.max(n2, Math.round(params.n3 ?? 120));
+		const i = bars.length - 1;
+		if (i + 1 < n3) return null;
+		const closes = bars.map((b) => b.close);
+		const s1 = sma(closes, n1)[i];
+		const s2 = sma(closes, n2)[i];
+		const s3 = sma(closes, n3)[i];
+		if (s1 === void 0 || s2 === void 0 || s3 === void 0) return null;
+		const close = bars[i].close;
+		if (!(close > s1 && s1 > s2 && s2 > s3)) return null;
+		return {
+			metrics: { distLongPct: (close - s3) / s3 * 100 },
+			reason: `现价站上三线且 SMA(${n1}) > SMA(${n2}) > SMA(${n3})，多头排列`,
+			reasonKey: "scr.ma-bull-align.reason",
+			reasonParams: {
+				n1,
+				n2,
+				n3
+			}
+		};
+	}
+};
+//#endregion
+export { maBullAlignScreener };

package/lib/screeners/near-high.d.ts

@@ -0,0 +1 @@
+import "./types.js";

package/lib/screeners/near-high.js

@@ -0,0 +1,48 @@
+//#region src/screeners/near-high.ts
+const nearHighScreener = {
+	id: "scr.near-high",
+	name: "接近一年新高",
+	summary: "现价距 N 日最高价不超过 X%，强势整理/突破前夜的动量筛选",
+	params: [{
+		key: "window",
+		label: "窗口(日)",
+		default: 250,
+		min: 60,
+		max: 500,
+		step: 10
+	}, {
+		key: "withinPct",
+		label: "接近阈值(%)",
+		default: 5,
+		min: 1,
+		max: 30,
+		step: 1
+	}],
+	columns: [{
+		key: "offHighPct",
+		label: "距高点",
+		format: "percent"
+	}],
+	evaluate(bars, params) {
+		const window = Math.max(60, Math.round(params.window ?? 250));
+		const withinPct = Math.max(1, params.withinPct ?? 5);
+		const i = bars.length - 1;
+		if (i + 1 < window) return null;
+		const windowBars = bars.slice(i + 1 - window);
+		const highMax = Math.max(...windowBars.map((b) => b.high));
+		if (!(highMax > 0)) return null;
+		const offHighPct = (highMax - bars[i].close) / highMax * 100;
+		if (!(offHighPct >= 0 && offHighPct <= withinPct)) return null;
+		return {
+			metrics: { offHighPct },
+			reason: `距 ${window} 日高点仅 ${offHighPct.toFixed(2)}%，处于突破前夜`,
+			reasonKey: "scr.near-high.reason",
+			reasonParams: {
+				n: window,
+				pct: offHighPct.toFixed(2)
+			}
+		};
+	}
+};
+//#endregion
+export { nearHighScreener };

package/lib/screeners/rsi-oversold.d.ts

@@ -0,0 +1 @@
+import "./types.js";

package/lib/screeners/rsi-oversold.js

@@ -0,0 +1,50 @@
+import { rsi } from "@dshtrading/indicators";
+//#region src/screeners/rsi-oversold.ts
+/**
+* RSI 超卖：RSI(period) 跌入阈值以下的逆势关注筛选——超卖≠见底，
+* 定位是「值得盯的反转候选池」，命中理由里明示是逆势信号。
+*/
+const rsiOversoldScreener = {
+	id: "scr.rsi-oversold",
+	name: "RSI 超卖",
+	summary: "RSI 跌入超卖区（默认 <30），筛选值得盯的反转候选（逆势信号）",
+	params: [{
+		key: "period",
+		label: "RSI 周期",
+		default: 14,
+		min: 5,
+		max: 30,
+		step: 1
+	}, {
+		key: "threshold",
+		label: "超卖阈值",
+		default: 30,
+		min: 10,
+		max: 50,
+		step: 5
+	}],
+	columns: [{
+		key: "rsi",
+		label: "RSI"
+	}],
+	evaluate(bars, params) {
+		const period = Math.max(5, Math.round(params.period ?? 14));
+		const threshold = Math.min(50, Math.max(10, params.threshold ?? 30));
+		const i = bars.length - 1;
+		if (i < period) return null;
+		const value = rsi(bars.map((b) => b.close), period)[i];
+		if (value === void 0) return null;
+		if (!(value < threshold)) return null;
+		return {
+			metrics: { rsi: value },
+			reason: `RSI(${period}) = ${value.toFixed(1)}，进入超卖区（逆势信号）`,
+			reasonKey: "scr.rsi-oversold.reason",
+			reasonParams: {
+				period,
+				val: value.toFixed(1)
+			}
+		};
+	}
+};
+//#endregion
+export { rsiOversoldScreener };

package/lib/screeners/types.d.ts

@@ -0,0 +1,38 @@
+import { StrategyParamSpec } from "../types.js";
+import { Kline as Kline$1 } from "@dshtrading/indicators";
+//#region src/screeners/types.d.ts
+/** 结果表动态列（每只标的命中后展示的指标值列）。 */
+interface ScreenerColumnSpec {
+  readonly key: string;
+  readonly label: string;
+  /** percent = 按 % 渲染；缺省按普通数字渲染 */
+  readonly format?: 'percent' | 'number';
+}
+/** 单标的命中结果（未命中由 evaluate 返回 null 表达，不进结果集）。 */
+interface ScreenerMatch {
+  /** 动态指标值（key 对应 columns 声明） */
+  readonly metrics: Readonly<Record<string, number>>;
+  /** 人话解释，UI 直接展示（zh 单语原文，回退用） */
+  readonly reason: string;
+  /** reason 的词典键（client-ui-strategies 词典约定 scr.<id>.reason），
+   *  视图按当前语言渲染 t(reasonKey, reasonParams)；缺省回退 reason 原文。 */
+  readonly reasonKey?: string;
+  /** reasonKey 的 {placeholder} 插值参数。 */
+  readonly reasonParams?: Readonly<Record<string, string | number>>;
+}
+interface ScreenerDefinition {
+  /** 稳定词汇，加 'scr.' 前缀与范式策略 id 空间隔离（如 'scr.ma-bull-align'） */
+  readonly id: string;
+  readonly name: string;
+  readonly summary: string;
+  readonly params: readonly StrategyParamSpec[];
+  readonly columns: readonly ScreenerColumnSpec[];
+  /**
+   * 纯函数：无 IO/随机/全局态；同一输入必须同一输出。
+   * 数据不足（无法计算所需指标）返回 null——既不算命中也不算错误，
+   * 新上市标的窗口不够时静默跳过。
+   */
+  evaluate(bars: readonly Kline$1[], params: Readonly<Record<string, number>>): ScreenerMatch | null;
+}
+//#endregion
+export { type Kline$1 as Kline, ScreenerColumnSpec, ScreenerDefinition, ScreenerMatch };

package/lib/screeners/volume-breakout.d.ts

@@ -0,0 +1 @@
+import "./types.js";