@dshtrading/strategies 0.1.6 → 0.2.0

package/lib/builtin-tombstones-fs.js

@@ -1,5 +1,5 @@
-import { dirname } from "node:path";
-import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { writeJsonAtomic } from "@dshtrading/dsh-home";
+import { readFile } from "node:fs/promises";
 //#region src/builtin-tombstones-fs.ts
 /**
 * 文件持久化版内置策略/选股器墓碑存储（Node.js 宿主侧使用，
@@ -28,27 +28,7 @@ function createFileBuiltinTombstonesStore(filePath) {
 		}
 	}
 	async function flush(set) {
-		const dir = dirname(filePath);
-		const tmpPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
-		const data = JSON.stringify({ deleted: [...set] }, null, 2);
-		try {
-			await mkdir(dir, { recursive: true });
-			await writeFile(tmpPath, data, "utf8");
-			let lastError;
-			for (let attempt = 0; attempt < 3; attempt++) try {
-				await rename(tmpPath, filePath);
-				return;
-			} catch (err) {
-				if (err?.code !== "EPERM" && err?.code !== "EBUSY") throw err;
-				lastError = err;
-				await new Promise((resolve) => setTimeout(resolve, 25 * (attempt + 1)));
-			}
-			throw lastError;
-		} catch (error) {
-			console.error(`[dsh-trading/strategies] failed to atomic flush builtin tombstones to ${filePath}:`, error);
-			await unlink(tmpPath).catch(() => {});
-			throw error;
-		}
+		await writeJsonAtomic(filePath, { deleted: [...set] }, "[dsh-trading/strategies] failed to atomic flush builtin tombstones to");
 	}
 	return {
 		async list() {

package/lib/custom-fs.js

@@ -1,5 +1,6 @@
 import { dirname } from "node:path";
-import { appendFile, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { writeJsonAtomic } from "@dshtrading/dsh-home";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
 //#region src/custom-fs.ts
 /**
 * 文件持久化版自定义策略存储（Node.js 宿主侧使用，落 ~/.dsh/strategies/custom.json）。
@@ -28,27 +29,7 @@ function createFileCustomStrategyStore(filePath) {
 		}
 	}
 	async function flush(map) {
-		const dir = dirname(filePath);
-		const tmpPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
-		const data = JSON.stringify([...map.values()], null, 2);
-		try {
-			await mkdir(dir, { recursive: true });
-			await writeFile(tmpPath, data, "utf8");
-			let lastError;
-			for (let attempt = 0; attempt < 3; attempt++) try {
-				await rename(tmpPath, filePath);
-				return;
-			} catch (err) {
-				if (err?.code !== "EPERM" && err?.code !== "EBUSY") throw err;
-				lastError = err;
-				await new Promise((resolve) => setTimeout(resolve, 25 * (attempt + 1)));
-			}
-			throw lastError;
-		} catch (error) {
-			console.error(`[dsh-trading/strategies] failed to atomic flush custom strategies to ${filePath}:`, error);
-			await unlink(tmpPath).catch(() => {});
-			throw error;
-		}
+		await writeJsonAtomic(filePath, [...map.values()], "[dsh-trading/strategies] failed to atomic flush custom strategies to");
 	}
 	return {
 		async list() {

package/lib/custom-screener-fs.js

@@ -1,5 +1,6 @@
 import { dirname } from "node:path";
-import { appendFile, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { writeJsonAtomic } from "@dshtrading/dsh-home";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
 //#region src/custom-screener-fs.ts
 /**
 * 文件持久化版自定义选股器存储（Node.js 宿主侧使用，
@@ -29,27 +30,7 @@ function createFileCustomScreenerStore(filePath) {
 		}
 	}
 	async function flush(map) {
-		const dir = dirname(filePath);
-		const tmpPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
-		const data = JSON.stringify([...map.values()], null, 2);
-		try {
-			await mkdir(dir, { recursive: true });
-			await writeFile(tmpPath, data, "utf8");
-			let lastError;
-			for (let attempt = 0; attempt < 3; attempt++) try {
-				await rename(tmpPath, filePath);
-				return;
-			} catch (err) {
-				if (err?.code !== "EPERM" && err?.code !== "EBUSY") throw err;
-				lastError = err;
-				await new Promise((resolve) => setTimeout(resolve, 25 * (attempt + 1)));
-			}
-			throw lastError;
-		} catch (error) {
-			console.error(`[dsh-trading/strategies] failed to atomic flush custom screeners to ${filePath}:`, error);
-			await unlink(tmpPath).catch(() => {});
-			throw error;
-		}
+		await writeJsonAtomic(filePath, [...map.values()], "[dsh-trading/strategies] failed to atomic flush custom screeners to");
 	}
 	return {
 		async list() {

package/lib/custom-screener.d.ts

@@ -25,7 +25,7 @@ interface CustomScreenerStore {
   /** archive = 删除前把记录归档（file 版落 .archive.jsonl；memory 版忽略）。 */
   remove(id: string, archive?: boolean): Promise<boolean>;
 }
-/** 内存版自定义选股器存储（纯浏览器与单测用）。 */
+/** 内存版自定义选股器存储（纯浏览器与单测用）；CRUD 机制见 memory-store.ts 单一实现。 */
 declare function createMemoryCustomScreenerStore(initial?: CustomScreenerRecord[]): CustomScreenerStore;
 //#endregion
 export { CustomScreenerRecord, CustomScreenerStore, createMemoryCustomScreenerStore };

package/lib/custom-screener.js

@@ -1,16 +1,8 @@
+import { createMemoryRecordStore } from "./memory-store.js";
 //#region src/custom-screener.ts
-/** 内存版自定义选股器存储（纯浏览器与单测用）。 */
+/** 内存版自定义选股器存储（纯浏览器与单测用）；CRUD 机制见 memory-store.ts 单一实现。 */
 function createMemoryCustomScreenerStore(initial = []) {
-	const map = /* @__PURE__ */ new Map();
-	for (const item of initial) map.set(item.id, item);
-	return {
-		list: async () => [...map.values()],
-		get: async (id) => map.get(id),
-		save: async (record) => {
-			map.set(record.id, { ...record });
-		},
-		remove: async (id) => map.delete(id)
-	};
+	return createMemoryRecordStore(initial);
 }
 //#endregion
 export { createMemoryCustomScreenerStore };

package/lib/custom.d.ts

@@ -23,7 +23,7 @@ interface CustomStrategyStore {
   /** archive = 删除前把记录归档（file 版落 .archive.jsonl；memory 版忽略）。 */
   remove(id: string, archive?: boolean): Promise<boolean>;
 }
-/** 内存版自定义策略存储（纯浏览器与单测用）。 */
+/** 内存版自定义策略存储（纯浏览器与单测用）；CRUD 机制见 memory-store.ts 单一实现。 */
 declare function createMemoryCustomStrategyStore(initial?: CustomStrategyRecord[]): CustomStrategyStore;
 //#endregion
 export { CustomStrategyRecord, CustomStrategyStore, createMemoryCustomStrategyStore };

package/lib/custom.js

@@ -1,16 +1,8 @@
+import { createMemoryRecordStore } from "./memory-store.js";
 //#region src/custom.ts
-/** 内存版自定义策略存储（纯浏览器与单测用）。 */
+/** 内存版自定义策略存储（纯浏览器与单测用）；CRUD 机制见 memory-store.ts 单一实现。 */
 function createMemoryCustomStrategyStore(initial = []) {
-	const map = /* @__PURE__ */ new Map();
-	for (const item of initial) map.set(item.id, item);
-	return {
-		list: async () => [...map.values()],
-		get: async (id) => map.get(id),
-		save: async (record) => {
-			map.set(record.id, { ...record });
-		},
-		remove: async (id) => map.delete(id)
-	};
+	return createMemoryRecordStore(initial);
 }
 //#endregion
 export { createMemoryCustomStrategyStore };

package/lib/memory-store.js

@@ -0,0 +1,15 @@
+//#region src/memory-store.ts
+function createMemoryRecordStore(initial) {
+	const map = /* @__PURE__ */ new Map();
+	for (const item of initial) map.set(item.id, item);
+	return {
+		list: async () => [...map.values()],
+		get: async (id) => map.get(id),
+		save: async (record) => {
+			map.set(record.id, { ...record });
+		},
+		remove: async (id) => map.delete(id)
+	};
+}
+//#endregion
+export { createMemoryRecordStore };

package/lib/plugin.d.ts

@@ -1,5 +1,6 @@
-import { StrategyDefinition } from "./types.js";
+import { StrategyDefinition, StrategyParamSpec } from "./types.js";
 import { CustomStrategyRecord, CustomStrategyStore } from "./custom.js";
+import { ScreenerColumnSpec, ScreenerDefinition } from "./screeners/types.js";
 import { CustomScreenerRecord, CustomScreenerStore } from "./custom-screener.js";
 import { isBuiltinScreenerId, isBuiltinStrategyId } from "./management.js";
 import { BuiltinTombstonesStore } from "./builtin-tombstones.js";
@@ -40,6 +41,24 @@ interface StrategyAuthorToolOptions {
 }
 /** strategy_author 工厂（独立导出便于单测）。 */
 declare function createStrategyAuthorTool(options: StrategyAuthorToolOptions): import("@deepseek-ai/dsh-tools").ToolDefinition;
+interface StrategyListToolOptions {
+  store: CustomStrategyStore;
+  /** 可选：墓碑表（内置删除状态回显）。 */
+  tombstones?: BuiltinTombstonesStore;
+}
+/**
+ * strategy_list 工厂（issue #86 / G3）：名册 + 覆盖 + 墓碑三态一次读全。
+ * 此前 strategy_delete / strategy_backtest 都要 id 而 agent 拿不到 id，
+ * 只能让用户口述或去读 ~/.dsh-trading/strategies/custom.json。
+ */
+declare function createStrategyListTool(options: StrategyListToolOptions): import("@deepseek-ai/dsh-tools").ToolDefinition;
+interface ScreenerListToolOptions {
+  store: CustomScreenerStore;
+  /** 可选：墓碑表（内置选股器删除状态回显）。 */
+  tombstones?: BuiltinTombstonesStore;
+}
+/** screener_list 工厂（issue #86 / G3）：选股器名册三态一次读全。 */
+declare function createScreenerListTool(options: ScreenerListToolOptions): import("@deepseek-ai/dsh-tools").ToolDefinition;
 interface StrategyBacktestToolOptions {
   store: CustomStrategyStore;
   /** 可选：墓碑表（内置删除后回测拒绝并引导恢复，策略管理语义）。 */
@@ -121,6 +140,49 @@ interface ScreenerResetToolOptions {
 declare function createScreenerResetTool(options: ScreenerResetToolOptions): import("@deepseek-ai/dsh-tools").ToolDefinition;
 /** Host plugin body：provide store 服务 + 注册策略工具族（host 平面，全会话可见）。 */
 declare function apply(ctx: Context): void;
+/** 解析后的选股器：内置（可信代码）或自定义（源码经 vm 熔断 runner 执行）。 */
+type ResolvedScreener = {
+  kind: 'builtin';
+  definition: ScreenerDefinition;
+} | {
+  kind: 'custom';
+  id: string;
+  name: string;
+  summary: string;
+  params: StrategyParamSpec[];
+  columns: ScreenerColumnSpec[];
+  evaluateSource: string;
+};
+/**
+ * 选股器解析（覆盖 + 墓碑合成，与 resolveStrategyDefinition 同模型）：
+ * 墓碑命中 → undefined；自定义记录优先（覆盖内置同 id）；损坏记录回落内置
+ * 出厂定义，非内置损坏记录视为不存在（与名册语义一致）。
+ */
+declare function resolveScreener(store: CustomScreenerStore, screenerId: string, options?: {
+  tombstones?: BuiltinTombstonesStore | undefined;
+}): Promise<ResolvedScreener | undefined>;
+interface ScreenerRunToolDeps {
+  store: CustomScreenerStore;
+  tombstones?: BuiltinTombstonesStore;
+  /** registry-first 解析（provider 标签 + 行情服务）。 */
+  active: (market: string) => {
+    provider: string;
+    service: MarketDataService;
+  } | undefined;
+  /** 老部署回退：市场键直读行情服务（无 registry 时）。 */
+  fallback?: (market: string) => MarketDataService | undefined;
+  /** 单次扫描总预算 ms（缺省 90s；测试注入小值/假时钟）。 */
+  budgetMs?: number;
+  /** 注入时钟（测试用；缺省 Date.now）。 */
+  now?: () => number;
+}
+/**
+ * screener_run 工厂（issue #86 / G4）：把选股器从「只对 UI 可用」提升为 agent 可跑。
+ * 扫描调度 = 名册 → 截断扫描池 → 受限并发拉 500 根日 K → 纯函数 evaluate；
+ * 数据不足（evaluate 返回 null）静默跳过，单标的失败只计数不中断。
+ * 只读行情 + 本地计算，无交易语义（铁律 #3 不涉及）。
+ */
+declare function createScreenerRunTool(deps: ScreenerRunToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
 /** 策略 store 服务（桥与工具的单实例共享点，issue #33 收口模式）。 */
 declare class StrategiesStoreService extends Service {
   readonly store: CustomStrategyStore;
@@ -135,4 +197,4 @@ declare class StrategiesStoreService extends Service {
   }, serviceName?: string);
 }
 //#endregion
-export { ScreenerAuthorToolOptions, ScreenerDeleteToolOptions, ScreenerResetToolOptions, StrategiesStoreService, StrategyAuthorToolOptions, StrategyBacktestToolDeps, StrategyBacktestToolOptions, StrategyDeleteToolOptions, StrategyMarketDataResolver, StrategyResetToolOptions, TRADING_STRATEGIES_KEY, TradingEventsPublisher, apply, createFileBuiltinTombstonesStore, createFileCustomScreenerStore, createFileCustomStrategyStore, createMarketDataResolver, createScreenerAuthorTool, createScreenerDeleteTool, createScreenerResetTool, createStrategyAuthorTool, createStrategyBacktestTool, createStrategyDeleteTool, createStrategyResetTool, defaultScreenerStorePath, defaultStorePath, defaultTombstonesStorePath, inject, isBuiltinScreenerId, isBuiltinStrategyId, name, resolveStrategyDefinition, validateCustomScreenerNode, validateCustomStrategyNode };
+export { ResolvedScreener, ScreenerAuthorToolOptions, ScreenerDeleteToolOptions, ScreenerListToolOptions, ScreenerResetToolOptions, ScreenerRunToolDeps, StrategiesStoreService, StrategyAuthorToolOptions, StrategyBacktestToolDeps, StrategyBacktestToolOptions, StrategyDeleteToolOptions, StrategyListToolOptions, StrategyMarketDataResolver, StrategyResetToolOptions, TRADING_STRATEGIES_KEY, TradingEventsPublisher, apply, createFileBuiltinTombstonesStore, createFileCustomScreenerStore, createFileCustomStrategyStore, createMarketDataResolver, createScreenerAuthorTool, createScreenerDeleteTool, createScreenerListTool, createScreenerResetTool, createScreenerRunTool, createStrategyAuthorTool, createStrategyBacktestTool, createStrategyDeleteTool, createStrategyListTool, createStrategyResetTool, defaultScreenerStorePath, defaultStorePath, defaultTombstonesStorePath, inject, isBuiltinScreenerId, isBuiltinStrategyId, name, resolveScreener, resolveStrategyDefinition, validateCustomScreenerNode, validateCustomStrategyNode };

package/lib/plugin.js

@@ -1,12 +1,13 @@
 import { run } from "./engine.js";
 import { compileStrategySource } from "./validate.js";
-import { getStrategyById } from "./paradigms/index.js";
+import { getStrategyById, strategyParadigms } from "./paradigms/index.js";
+import { getScreenerById, screenerParadigms } from "./screeners/index.js";
 import { isBuiltinScreenerId, isBuiltinStrategyId } from "./management.js";
 import "./index.js";
 import { createFileCustomStrategyStore } from "./custom-fs.js";
 import { createFileBuiltinTombstonesStore } from "./builtin-tombstones-fs.js";
 import { createFileCustomScreenerStore } from "./custom-screener-fs.js";
-import { validateCustomScreenerNode, validateCustomStrategyNode } from "./validate-node.js";
+import { nodeScreenerEvaluateRunner, validateCustomScreenerNode, validateCustomStrategyNode } from "./validate-node.js";
 import { Service } from "@deepseek-ai/cordis";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import path from "node:path";
@@ -118,6 +119,141 @@ function createStrategyAuthorTool(options) {
 		}
 	});
 }
+/**
+* strategy_list 工厂（issue #86 / G3）：名册 + 覆盖 + 墓碑三态一次读全。
+* 此前 strategy_delete / strategy_backtest 都要 id 而 agent 拿不到 id，
+* 只能让用户口述或去读 ~/.dsh-trading/strategies/custom.json。
+*/
+function createStrategyListTool(options) {
+	return defineTool({
+		name: "strategy_list",
+		description: "List the user strategy roster: built-in paradigms (with their parameter keys/defaults), custom strategies authored via strategy_author, and tombstoned (deleted) built-in ids. Read-only. ALWAYS call this before strategy_backtest / strategy_delete / strategy_reset when you do not already have an id from this session, and before strategy_backtest with paramsJson so you know the declared parameter keys. A paradigm with overridden=true is a built-in currently replaced by a user record; deleted=true means the built-in is tombstoned and hidden from the roster until strategy_reset restores it.",
+		parameters: {},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute() {
+			const deleted = options.tombstones === void 0 ? [] : await options.tombstones.list();
+			const records = await options.store.list();
+			const overridden = new Set(records.filter((record) => isBuiltinStrategyId(record.id)).map((record) => record.id));
+			const paradigms = strategyParadigms.map((definition) => ({
+				id: definition.id,
+				name: definition.name,
+				horizon: definition.horizon,
+				summary: definition.summary,
+				params: definition.params.map((spec) => ({
+					key: spec.key,
+					label: spec.label,
+					default: spec.default,
+					min: spec.min,
+					max: spec.max
+				})),
+				overridden: overridden.has(definition.id),
+				deleted: deleted.includes(definition.id)
+			}));
+			const custom = records.filter((record) => !isBuiltinStrategyId(record.id)).map((record) => ({
+				id: record.id,
+				title: record.title,
+				horizon: record.horizon,
+				summary: record.summary,
+				createdAt: record.createdAt
+			}));
+			const deletedStrategies = deleted.filter((id) => isBuiltinStrategyId(id));
+			return JSON.stringify({
+				ok: true,
+				paradigms,
+				custom,
+				deleted: deletedStrategies
+			});
+		}
+	});
+}
+/** 选股器记录 → 名册条目（paramsJson/columnsJson 解析在读取边界，坏数据降级为空数组）。 */
+function screenerRecordEntry(record) {
+	let params = [];
+	let columns = [];
+	try {
+		const parsed = JSON.parse(record.paramsJson);
+		if (Array.isArray(parsed)) params = parsed;
+	} catch {
+		params = [];
+	}
+	try {
+		const parsed = JSON.parse(record.columnsJson);
+		if (Array.isArray(parsed)) columns = parsed;
+	} catch {
+		columns = [];
+	}
+	return {
+		id: record.id,
+		title: record.title,
+		summary: record.summary,
+		params: params.map((spec) => ({
+			key: spec.key,
+			label: spec.label,
+			default: spec.default,
+			min: spec.min,
+			max: spec.max
+		})),
+		columns: columns.map((column) => ({
+			key: column.key,
+			label: column.label,
+			...column.format !== void 0 ? { format: column.format } : {}
+		})),
+		createdAt: record.createdAt
+	};
+}
+/** screener_list 工厂（issue #86 / G3）：选股器名册三态一次读全。 */
+function createScreenerListTool(options) {
+	return defineTool({
+		name: "screener_list",
+		description: "List the screener roster: built-in screeners (with their parameter keys and result column keys), custom screeners authored via screener_author, and tombstoned (deleted) built-in screener ids. Read-only. ALWAYS call this before screener_run / screener_delete / screener_reset when you do not already have an id from this session. A screener with overridden=true is a built-in currently replaced by a user record; deleted=true means the built-in is tombstoned and hidden from the roster until screener_reset restores it.",
+		parameters: {},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute() {
+			const deleted = options.tombstones === void 0 ? [] : await options.tombstones.list();
+			const records = await options.store.list();
+			const overridden = new Set(records.filter((record) => isBuiltinScreenerId(record.id)).map((record) => record.id));
+			const paradigms = screenerParadigms.map((definition) => ({
+				id: definition.id,
+				name: definition.name,
+				summary: definition.summary,
+				params: definition.params.map((spec) => ({
+					key: spec.key,
+					label: spec.label,
+					default: spec.default,
+					min: spec.min,
+					max: spec.max
+				})),
+				columns: definition.columns.map((column) => ({
+					key: column.key,
+					label: column.label,
+					...column.format !== void 0 ? { format: column.format } : {}
+				})),
+				overridden: overridden.has(definition.id),
+				deleted: deleted.includes(definition.id)
+			}));
+			const custom = records.filter((record) => !isBuiltinScreenerId(record.id)).map((record) => screenerRecordEntry(record));
+			const deletedScreeners = deleted.filter((id) => isBuiltinScreenerId(id));
+			return JSON.stringify({
+				ok: true,
+				paradigms,
+				custom,
+				deleted: deletedScreeners
+			});
+		}
+	});
+}
 /** 查询墓碑表（缺席或未命中 = 未删）。 */
 async function isTombstoned(tombstones, id) {
 	if (tombstones === void 0) return false;
@@ -159,7 +295,7 @@ async function resolveStrategyDefinition(store, strategyId, options) {
 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.",
+		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. Pass paramsJson to override declared parameters (values clamped to min/max) and read the echoed params.effective; call strategy_list first when you need an id or its parameter keys.",
 		parameters: {
 			strategyId: {
 				type: "string",
@@ -183,6 +319,10 @@ function createStrategyBacktestTool(deps) {
 			limit: {
 				type: "number",
 				description: "Kline count to backtest (default 200, capped by the provider)"
+			},
+			paramsJson: {
+				type: "string",
+				description: "Optional JSON object string overriding strategy parameters for this run, e.g. {\"fast\":10,\"slow\":30}. Keys must be declared by the strategy (see strategy_list); values are clamped to each param min/max and the effective values are echoed back in the result. Use this to reproduce a parameter set the user tuned in the GUI."
 			}
 		},
 		output: {
@@ -209,7 +349,29 @@ function createStrategyBacktestTool(deps) {
 			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);
+			const requested = {};
+			const paramsOverride = {};
+			const paramsJson = typeof args.paramsJson === "string" && args.paramsJson.trim() ? args.paramsJson.trim() : void 0;
+			if (paramsJson !== void 0) {
+				let parsed;
+				try {
+					parsed = JSON.parse(paramsJson);
+				} catch {
+					throw new Error("strategy_backtest: paramsJson must be a JSON object string like {\"fast\":10,\"slow\":30}");
+				}
+				if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("strategy_backtest: paramsJson must be a JSON object string like {\"fast\":10,\"slow\":30}");
+				const specs = new Map(definition.params.map((spec) => [spec.key, spec]));
+				for (const [key, value] of Object.entries(parsed)) {
+					const spec = specs.get(key);
+					if (spec === void 0) throw new Error(`strategy_backtest: unknown param ${JSON.stringify(key)} for strategy "${definition.id}" — valid keys: ` + (definition.params.length > 0 ? definition.params.map((item) => item.key).join(", ") : "(this strategy declares no params)"));
+					if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`strategy_backtest: param ${JSON.stringify(key)} must be a finite number (got ${JSON.stringify(value)})`);
+					requested[key] = value;
+					paramsOverride[key] = Math.min(spec.max, Math.max(spec.min, value));
+				}
+			}
+			const effectiveParams = {};
+			for (const spec of definition.params) effectiveParams[spec.key] = paramsOverride[spec.key] ?? spec.default;
+			const result = run(bars, definition, paramsOverride);
 			return JSON.stringify({
 				ok: true,
 				strategy: {
@@ -221,6 +383,10 @@ function createStrategyBacktestTool(deps) {
 				symbol,
 				interval,
 				barsTested: bars.length,
+				params: {
+					requested,
+					effective: effectiveParams
+				},
 				metrics: result.metrics,
 				trades: result.trades,
 				equity: result.equity,
@@ -505,6 +671,10 @@ function apply(ctx) {
 			tombstones,
 			onWritten: () => events()
 		}));
+		register(createStrategyListTool({
+			store,
+			tombstones
+		}));
 		register(createStrategyBacktestTool({
 			store,
 			tombstones,
@@ -535,6 +705,279 @@ function apply(ctx) {
 			tombstones,
 			onReset: () => events()
 		}));
+		register(createScreenerListTool({
+			store: screenerStore,
+			tombstones
+		}));
+		const marketDataFallback = createMarketDataResolver(ctx);
+		register(createScreenerRunTool({
+			store: screenerStore,
+			tombstones,
+			active: (market) => {
+				return (ctx.get?.("tradingMarketDataRegistry", false))?.active(market);
+			},
+			fallback: marketDataFallback
+		}));
+	});
+}
+/** 扫描护栏（对齐 client-ui-strategies 视图层口径，显式回显给模型）。 */
+const SCREENER_SCAN_CONCURRENCY = 5;
+const SCREENER_KLINE_WINDOW = 500;
+const SCREENER_DEFAULT_POOL = 100;
+const SCREENER_MAX_POOL = 500;
+const SCREENER_RESULT_LIMIT = 50;
+const SCREENER_EVAL_TIMEOUT_MS = 1e3;
+const SCREENER_FETCH_TIMEOUT_MS = 8e3;
+/** 单次扫描总预算：超时后不再领取新标的（agent 工具无取消通道，用预算收敛成本）。 */
+const SCREENER_TOTAL_BUDGET_MS = 9e4;
+function parseScreenerSpecs(record) {
+	let params = [];
+	let columns = [];
+	try {
+		const parsed = JSON.parse(record.paramsJson);
+		if (Array.isArray(parsed)) params = parsed;
+	} catch {
+		params = [];
+	}
+	try {
+		const parsed = JSON.parse(record.columnsJson);
+		if (Array.isArray(parsed)) columns = parsed;
+	} catch {
+		columns = [];
+	}
+	return {
+		params,
+		columns
+	};
+}
+/**
+* 选股器解析（覆盖 + 墓碑合成，与 resolveStrategyDefinition 同模型）：
+* 墓碑命中 → undefined；自定义记录优先（覆盖内置同 id）；损坏记录回落内置
+* 出厂定义，非内置损坏记录视为不存在（与名册语义一致）。
+*/
+async function resolveScreener(store, screenerId, options) {
+	if (await isTombstoned(options?.tombstones, screenerId)) return void 0;
+	const record = await store.get(screenerId);
+	if (record !== void 0) try {
+		compileStrategySource(record.evaluateSource);
+		const { params, columns } = parseScreenerSpecs(record);
+		return {
+			kind: "custom",
+			id: record.id,
+			name: record.title,
+			summary: record.summary,
+			params,
+			columns,
+			evaluateSource: record.evaluateSource
+		};
+	} catch {
+		if (isBuiltinScreenerId(record.id)) {
+			const builtin = getScreenerById(record.id);
+			return builtin === void 0 ? void 0 : {
+				kind: "builtin",
+				definition: builtin
+			};
+		}
+		return;
+	}
+	const builtin = getScreenerById(screenerId);
+	return builtin === void 0 ? void 0 : {
+		kind: "builtin",
+		definition: builtin
+	};
+}
+/** 单次 await 的超时熔断（数据源挂死不能让一次工具调用无限期占用）。 */
+async function withTimeout(promise, ms, label) {
+	let timer;
+	try {
+		return await Promise.race([promise, new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`${label} timed out after ${ms}ms`)), ms);
+		})]);
+	} finally {
+		if (timer !== void 0) clearTimeout(timer);
+	}
+}
+/** 解析 paramsJson（与 strategy_backtest 同口径：声明键校验 + clamp）。 */
+function parseParamsOverride(paramsJson, specs, tool, ownerId) {
+	const requested = {};
+	const override = {};
+	if (paramsJson !== void 0) {
+		let parsed;
+		try {
+			parsed = JSON.parse(paramsJson);
+		} catch {
+			throw new Error(`${tool}: paramsJson must be a JSON object string like {"window":120}`);
+		}
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${tool}: paramsJson must be a JSON object string like {"window":120}`);
+		const byKey = new Map(specs.map((spec) => [spec.key, spec]));
+		for (const [key, value] of Object.entries(parsed)) {
+			const spec = byKey.get(key);
+			if (spec === void 0) throw new Error(`${tool}: unknown param ${JSON.stringify(key)} for "${ownerId}" — valid keys: ` + (specs.length > 0 ? specs.map((item) => item.key).join(", ") : "(no params declared)"));
+			if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${tool}: param ${JSON.stringify(key)} must be a finite number (got ${JSON.stringify(value)})`);
+			requested[key] = value;
+			override[key] = Math.min(spec.max, Math.max(spec.min, value));
+		}
+	}
+	const effective = {};
+	for (const spec of specs) effective[spec.key] = override[spec.key] ?? spec.default;
+	return {
+		requested,
+		effective
+	};
+}
+/**
+* screener_run 工厂（issue #86 / G4）：把选股器从「只对 UI 可用」提升为 agent 可跑。
+* 扫描调度 = 名册 → 截断扫描池 → 受限并发拉 500 根日 K → 纯函数 evaluate；
+* 数据不足（evaluate 返回 null）静默跳过，单标的失败只计数不中断。
+* 只读行情 + 本地计算，无交易语义（铁律 #3 不涉及）。
+*/
+function createScreenerRunTool(deps) {
+	return defineTool({
+		name: "screener_run",
+		description: "Run one screener (built-in or custom, by id from screener_list) over a market and return the matched instruments with their metric columns and a one-line reason. Read-only cross-sectional scan: it fetches daily candles from the routed market data provider, evaluates a pure function per instrument, and never places orders or emits trading signals. Instruments whose window is too short are skipped silently (contract semantics); per-instrument fetch/evaluate failures are counted, never fatal. Cost guards are explicit in the result: scanPool (pool cap), scanned, failed, insufficient, resultLimit, truncated, budgetMs and deadlineExceeded (no cancellation channel exists — the scan stops taking new instruments once the time budget is spent). ALWAYS call screener_list first to get the id and its parameter/column keys.",
+		parameters: {
+			screenerId: {
+				type: "string",
+				required: true,
+				description: "Screener id from screener_list (built-in like scr.ma-bull-align, or a custom id)"
+			},
+			market: {
+				type: "string",
+				required: true,
+				description: "Market vocabulary: crypto | us | cn | hk"
+			},
+			limit: {
+				type: "number",
+				description: `Scan pool cap: how many instruments of the market roster to scan (default ${SCREENER_DEFAULT_POOL}, max ${SCREENER_MAX_POOL})`
+			},
+			paramsJson: {
+				type: "string",
+				description: "Optional JSON object string overriding screener parameters, e.g. {\"window\":120}; clamped to each param min/max and echoed in params.effective"
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const args = raw ?? {};
+			const screenerId = typeof args.screenerId === "string" ? args.screenerId.trim() : "";
+			const market = typeof args.market === "string" ? args.market.trim() : "";
+			if (!screenerId || !market) throw new Error("screener_run: screenerId and market are required");
+			const poolCap = typeof args.limit === "number" && Number.isFinite(args.limit) && args.limit > 0 ? Math.min(SCREENER_MAX_POOL, Math.max(1, Math.floor(args.limit))) : SCREENER_DEFAULT_POOL;
+			const resolved = await resolveScreener(deps.store, screenerId, { tombstones: deps.tombstones });
+			if (resolved === void 0) {
+				if (await isTombstoned(deps.tombstones, screenerId)) throw new Error(`screener_run: screener "${screenerId}" has been deleted by the user — call screener_reset with this id to restore the built-in, or screener_author to re-create it.`);
+				throw new Error(`screener_run: unknown screenerId "${screenerId}" — call screener_list for the current ids, or author one with screener_author.`);
+			}
+			const active = deps.active(market);
+			const service = active?.service ?? deps.fallback?.(market);
+			if (service === void 0) throw new Error(`screener_run: no market data service for market "${market}" — market keys are lowercase slugs (crypto | us | cn | hk); if the key is right, install/activate a market connector for it first.`);
+			const provider = active?.provider ?? "unknown";
+			if (typeof service.listInstruments !== "function") return JSON.stringify({
+				ok: false,
+				code: "TRADING_NO_UNIVERSE",
+				market,
+				provider,
+				note: `market "${market}" provider "${provider}" exposes no instrument roster (listInstruments) — screener_run cannot build a scan pool. Scan a specific symbol instead with strategy_backtest, or pick a provider that lists instruments.`
+			});
+			const universe = await service.listInstruments();
+			if (!Array.isArray(universe) || universe.length === 0) return JSON.stringify({
+				ok: false,
+				code: "TRADING_NO_UNIVERSE",
+				market,
+				provider,
+				note: `market "${market}" provider "${provider}" returned an empty instrument roster — nothing to scan.`
+			});
+			const specs = resolved.kind === "builtin" ? resolved.definition.params : resolved.params;
+			const { requested, effective } = parseParamsOverride(typeof args.paramsJson === "string" && args.paramsJson.trim() ? args.paramsJson.trim() : void 0, specs, "screener_run", resolved.kind === "builtin" ? resolved.definition.id : resolved.id);
+			const pool = universe.slice(0, poolCap);
+			const matched = [];
+			const budgetMs = deps.budgetMs ?? SCREENER_TOTAL_BUDGET_MS;
+			const now = deps.now ?? (() => Date.now());
+			const deadline = now() + budgetMs;
+			let scanned = 0;
+			let failed = 0;
+			let insufficient = 0;
+			let cursor = 0;
+			let deadlineExceeded = false;
+			const evaluate = async (bars) => {
+				if (resolved.kind === "builtin") return resolved.definition.evaluate(bars, effective);
+				return withTimeout(nodeScreenerEvaluateRunner(resolved.evaluateSource, bars, effective, SCREENER_EVAL_TIMEOUT_MS), 1500, `screener_run evaluate(${resolved.id})`);
+			};
+			const worker = async () => {
+				while (cursor < pool.length) {
+					if (now() > deadline) {
+						deadlineExceeded = true;
+						return;
+					}
+					const instrument = pool[cursor];
+					cursor += 1;
+					if (instrument === void 0) return;
+					try {
+						const bars = await withTimeout(service.getKlines(instrument.symbol, "1d", SCREENER_KLINE_WINDOW), SCREENER_FETCH_TIMEOUT_MS, `screener_run getKlines(${instrument.symbol})`);
+						if (!Array.isArray(bars) || bars.length === 0) {
+							failed += 1;
+							continue;
+						}
+						const match = await evaluate(bars);
+						if (match === null || match === void 0) {
+							insufficient += 1;
+							continue;
+						}
+						if (typeof match !== "object" || typeof match.reason !== "string") {
+							failed += 1;
+							continue;
+						}
+						const hit = match;
+						matched.push({
+							symbol: instrument.symbol,
+							...instrument.name !== void 0 ? { name: instrument.name } : {},
+							price: bars[bars.length - 1]?.close ?? null,
+							metrics: hit.metrics ?? {},
+							reason: hit.reason,
+							...hit.reasonKey !== void 0 ? { reasonKey: hit.reasonKey } : {},
+							...hit.reasonParams !== void 0 ? { reasonParams: hit.reasonParams } : {}
+						});
+					} catch {
+						failed += 1;
+					} finally {
+						scanned += 1;
+					}
+				}
+			};
+			await Promise.all(Array.from({ length: Math.min(SCREENER_SCAN_CONCURRENCY, pool.length) }, () => worker()));
+			const results = matched.slice(0, SCREENER_RESULT_LIMIT);
+			return JSON.stringify({
+				ok: true,
+				screenerId: resolved.kind === "builtin" ? resolved.definition.id : resolved.id,
+				screenerName: resolved.kind === "builtin" ? resolved.definition.name : resolved.name,
+				market,
+				provider,
+				interval: "1d",
+				klineWindow: SCREENER_KLINE_WINDOW,
+				universeSize: universe.length,
+				scanPool: pool.length,
+				scanned,
+				failed,
+				insufficient,
+				matched: matched.length,
+				returned: results.length,
+				resultLimit: SCREENER_RESULT_LIMIT,
+				truncated: matched.length > SCREENER_RESULT_LIMIT,
+				budgetMs,
+				deadlineExceeded,
+				params: {
+					requested,
+					effective
+				},
+				results,
+				note: `Read-only cross-sectional scan (no trading signals). failed = fetch/evaluate errors; insufficient = window too short for the screener (contract: skipped silently). Raise limit to widen the pool (max 500). The scan stops taking new instruments after budgetMs (${budgetMs}ms); deadlineExceeded=true means the pool was not fully scanned.`
+			});
+		}
 	});
 }
 /** 策略 store 服务（桥与工具的单实例共享点，issue #33 收口模式）。 */
@@ -552,4 +995,4 @@ var StrategiesStoreService = class extends Service {
 	}
 };
 //#endregion
-export { StrategiesStoreService, TRADING_STRATEGIES_KEY, apply, createFileBuiltinTombstonesStore, createFileCustomScreenerStore, createFileCustomStrategyStore, createMarketDataResolver, createScreenerAuthorTool, createScreenerDeleteTool, createScreenerResetTool, createStrategyAuthorTool, createStrategyBacktestTool, createStrategyDeleteTool, createStrategyResetTool, defaultScreenerStorePath, defaultStorePath, defaultTombstonesStorePath, inject, isBuiltinScreenerId, isBuiltinStrategyId, name, resolveStrategyDefinition, validateCustomScreenerNode, validateCustomStrategyNode };
+export { StrategiesStoreService, TRADING_STRATEGIES_KEY, apply, createFileBuiltinTombstonesStore, createFileCustomScreenerStore, createFileCustomStrategyStore, createMarketDataResolver, createScreenerAuthorTool, createScreenerDeleteTool, createScreenerListTool, createScreenerResetTool, createScreenerRunTool, createStrategyAuthorTool, createStrategyBacktestTool, createStrategyDeleteTool, createStrategyListTool, createStrategyResetTool, defaultScreenerStorePath, defaultStorePath, defaultTombstonesStorePath, inject, isBuiltinScreenerId, isBuiltinStrategyId, name, resolveScreener, resolveStrategyDefinition, validateCustomScreenerNode, validateCustomStrategyNode };

package/lib/validate-node.js

@@ -1,37 +1,7 @@
 import { validateCustomScreener, validateCustomStrategy } from "./validate.js";
-import * as vm from "node:vm";
+import { runSourceInVmSandbox } from "@dshtrading/indicators/tool";
 //#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;
-	}
-};
+const nodeStrategyComputeRunner = (computeSource, bars, params, timeoutMs = 100) => runSourceInVmSandbox(computeSource, bars, params, timeoutMs, "策略试算");
 /** Node.js 宿主端策略校验器：自动启用 node:vm 超时熔断保护。 */
 function validateCustomStrategyNode(raw) {
 	return validateCustomStrategy(raw, { runner: nodeStrategyComputeRunner });
@@ -39,13 +9,12 @@ function validateCustomStrategyNode(raw) {
 /**
 * Node 宿主端选股器 evaluate 试算 runner（同一 vm 沙箱形态；返回值形状由
 * validateCustomScreener 的 ScreenerMatch 校验把关，此处不约束类型）。
-* 复用策略 vm runner，但超时文案归位为「选股器」（策略 runner 硬编码「策略试算」）。
+* Promise 形态：抛错转拒绝，超时文案经 label 归位为「选股器试算」。
 */
 const nodeScreenerEvaluateRunner = (evaluateSource, bars, params, timeoutMs = 100) => {
 	try {
-		return Promise.resolve(nodeStrategyComputeRunner(evaluateSource, bars, params, timeoutMs));
+		return Promise.resolve(runSourceInVmSandbox(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);
 	}
 };

package/lib/validate.d.ts

@@ -12,8 +12,12 @@ type StrategyValidationResult = {
   ok: false;
   reason: string;
 };
-/** 将策略源码解析为可执行纯函数（浏览器端 new Function；Node 侧走 vm runner 试算）。 */
-declare function compileStrategySource(source: string): (bars: readonly Kline[], params: Readonly<Record<string, number>>) => StrategySignal[];
+/**
+ * 将策略源码解析为可执行纯函数（浏览器端 new Function；Node 侧走 vm runner 试算）。
+ * 编译语义（形态嗅探 + new Function 双形态）的单一来源是 @dshtrading/indicators 的
+ * compileComputeSource——此处仅按策略信号类型收窄返回值（2026-09-09 收敛同体副本）。
+ */
+declare const compileStrategySource: (source: string) => (bars: readonly Kline[], params: Readonly<Record<string, number>>) => StrategySignal[];
 /**
  * 信号序列专用校验（引擎语义对齐：i 收盘确认、i+1 开盘成交可复算）。
  * 返回 undefined = 通过；否则返回人话诊断（模型与 UI 直接可读）。

package/lib/validate.js

@@ -1,4 +1,4 @@
-import { createSampleBars, workerComputeRunner } from "@dshtrading/indicators";
+import { compileComputeSource, createSampleBars, workerComputeRunner } from "@dshtrading/indicators";
 //#region src/validate.ts
 /**
 * 自定义策略安全校验器（issue #31 / P2）。浏览器端与宿主两侧共用（纯库，零 Node 依赖）：
@@ -29,12 +29,12 @@ const HORIZONS = [
 	"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}`);
-}
+/**
+* 将策略源码解析为可执行纯函数（浏览器端 new Function；Node 侧走 vm runner 试算）。
+* 编译语义（形态嗅探 + new Function 双形态）的单一来源是 @dshtrading/indicators 的
+* compileComputeSource——此处仅按策略信号类型收窄返回值（2026-09-09 收敛同体副本）。
+*/
+const compileStrategySource = compileComputeSource;
 /**
 * 信号序列专用校验（引擎语义对齐：i 收盘确认、i+1 开盘成交可复算）。
 * 返回 undefined = 通过；否则返回人话诊断（模型与 UI 直接可读）。

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.6",
+  "version": "0.2.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -21,8 +21,8 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "dependencies": {
-    "@dshtrading/dsh-home": "^0.1.6",
-    "@dshtrading/indicators": "0.1.6"
+    "@dshtrading/indicators": "0.2.0",
+    "@dshtrading/dsh-home": "^0.2.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.0",
@@ -32,7 +32,7 @@
     "tsdown": "^0.22.0",
     "vitest": "^3.0.0",
     "typescript": "^5.5.0",
-    "@dshtrading/api": "0.1.6"
+    "@dshtrading/api": "0.2.0"
   },
   "scripts": {
     "build": "tsdown",