@dshtrading/strategies 0.1.5 → 0.2.0

package/lib/plugin.js

@@ -1,12 +1,17 @@
 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 { validateCustomStrategyNode } from "./validate-node.js";
+import { createFileBuiltinTombstonesStore } from "./builtin-tombstones-fs.js";
+import { createFileCustomScreenerStore } from "./custom-screener-fs.js";
+import { nodeScreenerEvaluateRunner, validateCustomScreenerNode, validateCustomStrategyNode } from "./validate-node.js";
+import { Service } from "@deepseek-ai/cordis";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import os from "node:os";
 import path from "node:path";
+import { dshHomeDir } from "@dshtrading/dsh-home";
 //#region src/plugin.ts
 /** Cordis 插件名 = patch 行 id（TEMPLATES §8），市场无关共享行命名空间。 */
 const name = "dsh-trading-strategies";
@@ -19,10 +24,20 @@ const MARKET_SERVICE_KEYS = {
 	cn: "tradingCnMarketData",
 	hk: "tradingHkMarketData"
 };
-/** 默认存储路径：~/.dsh/strategies/custom.json。 */
+/** 默认存储路径：$DSH_HOME/strategies/custom.json（缺省 ~/.dsh）。 */
 function defaultStorePath() {
-	return path.join(os.homedir(), ".dsh", "strategies", "custom.json");
+	return path.join(dshHomeDir(), "strategies", "custom.json");
 }
+/** 默认墓碑路径：$DSH_HOME/strategies/builtin-tombstones.json（策略管理）。 */
+function defaultTombstonesStorePath() {
+	return path.join(dshHomeDir(), "strategies", "builtin-tombstones.json");
+}
+/** 默认自定义选股器路径：$DSH_HOME/strategies/custom-screeners.json（选股器管理）。 */
+function defaultScreenerStorePath() {
+	return path.join(dshHomeDir(), "strategies", "custom-screeners.json");
+}
+/** SDK 服务键：自定义策略 store 单实例（桥与工具共享同一缓存）。 */
+const TRADING_STRATEGIES_KEY = "tradingStrategies";
 function eventsOf(ctx) {
 	return ctx.get?.("tradingEvents", false);
 }
@@ -36,15 +51,15 @@ function createMarketDataResolver(ctx) {
 }
 /** strategy_author 工厂（独立导出便于单测）。 */
 function createStrategyAuthorTool(options) {
-	const { store, onWritten } = options;
+	const { store, tombstones, 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.",
+		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. Submitting an id equal to a built-in paradigm id (donchian-breakout / rsi-reversion / ema-crossover / bollinger-reversion / sma-baseline / momentum-12m) OVERRIDES that built-in strategy (the factory default stays recoverable via strategy_reset).",
 		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"
+				description: "Unique strategy id (2-32 chars: lowercase letters/digits/underscore/hyphen, e.g. \"ema-stop-takeprofit\"); a built-in paradigm id means overriding that built-in strategy"
 			},
 			title: {
 				type: "string",
@@ -91,15 +106,166 @@ function createStrategyAuthorTool(options) {
 			};
 			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).`;
+			const overridesBuiltin = isBuiltinStrategyId(result.record.id);
+			if (overridesBuiltin) {
+				if (await store.get(result.record.id) !== void 0) await store.remove(result.record.id, true);
+				await tombstones?.remove(result.record.id);
+			}
 			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.`;
+			const scopeNote = overridesBuiltin ? "This id is a built-in paradigm — the factory default remains recoverable via strategy_reset." : "Call strategy_backtest with this id to backtest it.";
+			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 — ` + scopeNote;
+		}
+	});
+}
+/**
+* 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
+			});
 		}
 	});
 }
-/** 自定义或范式策略 → 回测用 StrategyDefinition（自定义 compute 经编译落定）。 */
-async function resolveStrategyDefinition(store, strategyId) {
+/** 查询墓碑表（缺席或未命中 = 未删）。 */
+async function isTombstoned(tombstones, id) {
+	if (tombstones === void 0) return false;
+	return (await tombstones.list()).includes(id);
+}
+/**
+* 自定义或范式策略 → 回测用 StrategyDefinition（自定义 compute 经编译落定）。
+* 覆盖 + 墓碑合成：store 同 id 记录优先（含内置覆盖）；墓碑命中的 id 一律
+* 视为不存在（含误留覆盖记录的边界——删除语义优先）。
+*/
+async function resolveStrategyDefinition(store, strategyId, options) {
+	if (await isTombstoned(options?.tombstones, strategyId)) return void 0;
 	const record = await store.get(strategyId);
 	if (record !== void 0) {
 		let params = [];
@@ -109,14 +275,19 @@ async function resolveStrategyDefinition(store, strategyId) {
 		} catch {
 			params = [];
 		}
-		return {
-			id: record.id,
-			horizon: record.horizon,
-			name: record.title,
-			summary: record.summary,
-			params,
-			compute: compileStrategySource(record.computeSource)
-		};
+		try {
+			return {
+				id: record.id,
+				horizon: record.horizon,
+				name: record.title,
+				summary: record.summary,
+				params,
+				compute: compileStrategySource(record.computeSource)
+			};
+		} catch {
+			if (isBuiltinStrategyId(record.id)) return getStrategyById(record.id);
+			return;
+		}
 	}
 	return getStrategyById(strategyId);
 }
@@ -124,7 +295,7 @@ async function resolveStrategyDefinition(store, strategyId) {
 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",
@@ -148,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: {
@@ -165,13 +340,38 @@ function createStrategyBacktestTool(deps) {
 			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 definition = await resolveStrategyDefinition(deps.store, strategyId, { tombstones: deps.tombstones });
+			if (definition === void 0) {
+				if (await isTombstoned(deps.tombstones, strategyId)) throw new Error(`strategy_backtest: strategy "${strategyId}" has been deleted by the user — call strategy_reset with this id to restore the factory default, or strategy_author to re-create it.`);
+				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);
+			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: {
@@ -183,6 +383,10 @@ function createStrategyBacktestTool(deps) {
 				symbol,
 				interval,
 				barsTested: bars.length,
+				params: {
+					requested,
+					effective: effectiveParams
+				},
 				metrics: result.metrics,
 				trades: result.trades,
 				equity: result.equity,
@@ -192,23 +396,603 @@ function createStrategyBacktestTool(deps) {
 		}
 	});
 }
-/** Host plugin body：注册 strategy_author / strategy_backtest（host 平面，全会话可见）。 */
+/**
+* strategy_delete 工厂（策略管理）：自定义策略 = 移除记录；内置范式 = 落墓碑
+* （出厂代码不动，strategy_reset 可恢复）。覆盖 + 墓碑模型见 management.ts。
+*/
+function createStrategyDeleteTool(options) {
+	const { store, tombstones, onDeleted } = options;
+	return defineTool({
+		name: "strategy_delete",
+		description: "Delete a strategy by id. Custom strategies (authored via strategy_author) are removed from the library; built-in paradigm ids (donchian-breakout / rsi-reversion / ema-crossover / bollinger-reversion / sma-baseline / momentum-12m) are tombstoned instead — the built-in disappears from the roster and backtest but stays recoverable via strategy_reset. Deleting a built-in also discards any user override of it. The GUI strategy roster refreshes live over the SSE channel.",
+		parameters: { id: {
+			type: "string",
+			required: true,
+			description: "Strategy id to delete (a custom id or a built-in paradigm id)"
+		} },
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const args = raw ?? {};
+			const id = typeof args.id === "string" ? args.id.trim() : "";
+			if (!id) throw new Error("strategy_delete: id is required");
+			if (isBuiltinStrategyId(id)) {
+				await tombstones?.add(id);
+				const discardedOverride = await store.remove(id, true);
+				onDeleted?.(id, "builtin", true);
+				return JSON.stringify({
+					ok: true,
+					scope: "builtin",
+					deleted: true,
+					discardedOverride,
+					note: `Built-in strategy "${id}" is now tombstoned — hidden from the roster and backtest. Call strategy_reset to restore the factory default.`
+				});
+			}
+			const removed = await store.remove(id);
+			onDeleted?.(id, "custom", removed);
+			return JSON.stringify({
+				ok: true,
+				scope: "custom",
+				deleted: removed,
+				note: removed ? `Deleted custom strategy "${id}".` : `"${id}" was not found in the custom strategy library (built-in ids are handled by tombstone — double-check the id).`
+			});
+		}
+	});
+}
+/**
+* strategy_reset 工厂（策略管理）：恢复内置策略出厂默认——清覆盖记录与墓碑。
+* 仅对内置范式 id 有意义；自定义策略无出厂版本，明确报错引导 strategy_delete。
+*/
+function createStrategyResetTool(options) {
+	const { store, tombstones, onReset } = options;
+	return defineTool({
+		name: "strategy_reset",
+		description: "Restore a built-in paradigm strategy (donchian-breakout / rsi-reversion / ema-crossover / bollinger-reversion / sma-baseline / momentum-12m) to its factory default: any user override is discarded and a deletion tombstone is lifted. Custom strategy ids have no factory default — use strategy_delete for those.",
+		parameters: { id: {
+			type: "string",
+			required: true,
+			description: "Built-in paradigm strategy id to restore"
+		} },
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const args = raw ?? {};
+			const id = typeof args.id === "string" ? args.id.trim() : "";
+			if (!id) throw new Error("strategy_reset: id is required");
+			if (!isBuiltinStrategyId(id)) throw new Error(`strategy_reset: "${id}" is not a built-in paradigm strategy id — custom strategies have no factory default; use strategy_delete to remove them`);
+			const removedOverride = await store.remove(id, true);
+			const liftedTombstone = await tombstones?.remove(id) ?? false;
+			const changed = removedOverride || liftedTombstone;
+			onReset?.(id, changed);
+			return JSON.stringify({
+				ok: true,
+				reset: true,
+				changed,
+				removedOverride,
+				liftedTombstone,
+				note: changed ? `Built-in strategy "${id}" restored to factory default (override/tombstone cleared).` : `"${id}" was already at factory default — nothing to restore.`
+			});
+		}
+	});
+}
+/**
+* screener_author 工厂（选股器管理）：提交 → 结构/语法/多场景试算校验（vm 熔断）
+* → 落盘。evaluate(bars, params) 返回 ScreenerMatch | null（单时点截面判断，
+* 无信号序列语义）。id 为内置选股器（'scr.*'）→ 覆盖该内置（strategy_reset/
+* screener_reset 可恢复出厂）。
+*/
+function createScreenerAuthorTool(options) {
+	const { store, tombstones, onWritten } = options;
+	return defineTool({
+		name: "screener_author",
+		description: "Author, validate, and persist a custom stock screener from JavaScript evaluate source. evaluate(bars, params) is a single-point cross-section predicate: return a ScreenerMatch ({ metrics: Record<string, number> with keys declared in columns, reason }) or null when the symbol does not match / lacks data. The validator runs sandbox trial calculations across multiple kline scenarios. If valid, the screener is persisted and immediately available in the GUI screener roster. Submitting an id equal to a built-in screener id (scr.ma-bull-align / scr.volume-breakout / scr.rsi-oversold / scr.near-high / scr.above-ma) OVERRIDES that built-in screener (factory default stays recoverable via screener_reset).",
+		parameters: {
+			id: {
+				type: "string",
+				required: true,
+				description: "Unique screener id with \"scr.\" prefix (e.g. \"scr.custom-momentum\"); a built-in screener id means overriding that built-in"
+			},
+			title: {
+				type: "string",
+				required: true,
+				description: "Display name (1-32 chars), e.g. \"量价双确认\""
+			},
+			summary: {
+				type: "string",
+				required: true,
+				description: "One-sentence idea summary (≤120 chars), shown in the screener roster"
+			},
+			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."
+			},
+			columnsJson: {
+				type: "string",
+				required: true,
+				description: "JSON string of ScreenerColumnSpec[] (1-8 columns). Each spec: { key, label, format?: \"percent\" | \"number\" }. Match metrics keys must be declared here. JSON example: [{\"key\":\"volRatio\",\"label\":\"量比(倍)\"}]"
+			},
+			evaluateSource: {
+				type: "string",
+				required: true,
+				description: "JavaScript pure function source, signature (bars, params) => ScreenerMatch | null. bars has { openTime, open, high, low, close, volume }. Return null to skip the symbol (no match or insufficient data). metrics values must be finite numbers with keys declared in columnsJson; reason is a non-empty human-readable string."
+			}
+		},
+		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: "swing",
+				summary: typeof args.summary === "string" ? args.summary : "",
+				paramsJson: typeof args.paramsJson === "string" && args.paramsJson.trim() ? args.paramsJson.trim() : "[]",
+				columnsJson: typeof args.columnsJson === "string" ? args.columnsJson : "",
+				evaluateSource: typeof args.evaluateSource === "string" ? args.evaluateSource : "",
+				createdAt: Date.now()
+			};
+			const result = await validateCustomScreenerNode(candidate);
+			if (!result.ok) return `[screener_author] Validation failed: ${result.reason}\nReview the requirements: evaluate(bars, params) returns ScreenerMatch | null; metrics keys must be declared in columnsJson with finite number values; reason must be a non-empty string; return null to skip a symbol.`;
+			const overridesBuiltin = isBuiltinScreenerId(result.record.id);
+			if (overridesBuiltin) {
+				if (await store.get(result.record.id) !== void 0) await store.remove(result.record.id, true);
+				await tombstones?.remove(result.record.id);
+			}
+			await store.save(result.record);
+			onWritten?.(result.record);
+			const columnKeys = result.definition.columns.map((c) => c.key).join(", ");
+			return `[screener_author] Successfully authored screener "${result.record.title}" (id: ${result.record.id}` + (columnKeys ? `, columns: ${columnKeys}` : "") + "). The screener passed sandbox trials across 5 kline scenarios and is now persisted to the GUI screener roster. " + (overridesBuiltin ? "This id is a built-in screener — the factory default remains recoverable via screener_reset." : "Run scans from the GUI screener pane.");
+		}
+	});
+}
+/**
+* screener_delete 工厂（选股器管理）：自定义选股器 = 移除记录；内置选股器 =
+* 落墓碑（出厂代码不动，screener_reset 可恢复）。与 strategy_delete 共用墓碑表。
+*/
+function createScreenerDeleteTool(options) {
+	const { store, tombstones, onDeleted } = options;
+	return defineTool({
+		name: "screener_delete",
+		description: "Delete a screener by id. Custom screeners (authored via screener_author) are removed from the library; built-in screener ids (scr.ma-bull-align / scr.volume-breakout / scr.rsi-oversold / scr.near-high / scr.above-ma) are tombstoned instead — the built-in disappears from the GUI screener roster but stays recoverable via screener_reset. Deleting a built-in also discards any user override of it.",
+		parameters: { id: {
+			type: "string",
+			required: true,
+			description: "Screener id to delete (a custom id or a built-in screener id)"
+		} },
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const args = raw ?? {};
+			const id = typeof args.id === "string" ? args.id.trim() : "";
+			if (!id) throw new Error("screener_delete: id is required");
+			if (isBuiltinScreenerId(id)) {
+				await tombstones?.add(id);
+				const discardedOverride = await store.remove(id, true);
+				onDeleted?.(id, "builtin", true);
+				return JSON.stringify({
+					ok: true,
+					scope: "builtin",
+					deleted: true,
+					discardedOverride,
+					note: `Built-in screener "${id}" is now tombstoned — hidden from the GUI screener roster. Call screener_reset to restore the factory default.`
+				});
+			}
+			const removed = await store.remove(id);
+			onDeleted?.(id, "custom", removed);
+			return JSON.stringify({
+				ok: true,
+				scope: "custom",
+				deleted: removed,
+				note: removed ? `Deleted custom screener "${id}".` : `"${id}" was not found in the custom screener library (built-in ids are handled by tombstone — double-check the id).`
+			});
+		}
+	});
+}
+/**
+* screener_reset 工厂（选股器管理）：恢复内置选股器出厂默认——清覆盖记录与墓碑。
+* 仅对内置选股器 id 有意义；自定义选股器无出厂版本，明确报错引导 screener_delete。
+*/
+function createScreenerResetTool(options) {
+	const { store, tombstones, onReset } = options;
+	return defineTool({
+		name: "screener_reset",
+		description: "Restore a built-in screener (scr.ma-bull-align / scr.volume-breakout / scr.rsi-oversold / scr.near-high / scr.above-ma) to its factory default: any user override is discarded and a deletion tombstone is lifted. Custom screener ids have no factory default — use screener_delete for those.",
+		parameters: { id: {
+			type: "string",
+			required: true,
+			description: "Built-in screener id to restore"
+		} },
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const args = raw ?? {};
+			const id = typeof args.id === "string" ? args.id.trim() : "";
+			if (!id) throw new Error("screener_reset: id is required");
+			if (!isBuiltinScreenerId(id)) throw new Error(`screener_reset: "${id}" is not a built-in screener id — custom screeners have no factory default; use screener_delete to remove them`);
+			const removedOverride = await store.remove(id, true);
+			const liftedTombstone = await tombstones?.remove(id) ?? false;
+			const changed = removedOverride || liftedTombstone;
+			onReset?.(id, changed);
+			return JSON.stringify({
+				ok: true,
+				reset: true,
+				changed,
+				removedOverride,
+				liftedTombstone,
+				note: changed ? `Built-in screener "${id}" restored to factory default (override/tombstone cleared).` : `"${id}" was already at factory default — nothing to restore.`
+			});
+		}
+	});
+}
+/** Host plugin body：provide store 服务 + 注册策略工具族（host 平面，全会话可见）。 */
 function apply(ctx) {
 	const store = createFileCustomStrategyStore(defaultStorePath());
+	const tombstones = createFileBuiltinTombstonesStore(defaultTombstonesStorePath());
+	const screenerStore = createFileCustomScreenerStore(defaultScreenerStorePath());
+	new StrategiesStoreService(ctx, {
+		store,
+		tombstones,
+		screenerStore
+	});
 	ctx.inject(["tools"], (toolCtx) => {
 		const tools = toolCtx.tools;
 		if (!tools || typeof tools.register !== "function") return;
-		const authorTool = createStrategyAuthorTool({
+		const events = () => eventsOf(ctx)?.emit("strategies");
+		const register = (tool) => {
+			if (tools.get(tool.name) === void 0) tools.register(tool);
+		};
+		register(createStrategyAuthorTool({
 			store,
-			onWritten: () => eventsOf(ctx)?.emit("strategies")
-		});
-		if (tools.get(authorTool.name) === void 0) tools.register(authorTool);
-		const backtestTool = createStrategyBacktestTool({
+			tombstones,
+			onWritten: () => events()
+		}));
+		register(createStrategyListTool({
 			store,
+			tombstones
+		}));
+		register(createStrategyBacktestTool({
+			store,
+			tombstones,
 			marketData: createMarketDataResolver(ctx)
-		});
-		if (tools.get(backtestTool.name) === void 0) tools.register(backtestTool);
+		}));
+		register(createStrategyDeleteTool({
+			store,
+			tombstones,
+			onDeleted: () => events()
+		}));
+		register(createStrategyResetTool({
+			store,
+			tombstones,
+			onReset: () => events()
+		}));
+		register(createScreenerAuthorTool({
+			store: screenerStore,
+			tombstones,
+			onWritten: () => events()
+		}));
+		register(createScreenerDeleteTool({
+			store: screenerStore,
+			tombstones,
+			onDeleted: () => events()
+		}));
+		register(createScreenerResetTool({
+			store: screenerStore,
+			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 收口模式）。 */
+var StrategiesStoreService = class extends Service {
+	store;
+	/** 内置墓碑表（策略/选股器管理共用；桥 DELETE/POST /strategies/* 与工具共享）。 */
+	tombstones;
+	/** 自定义选股器 store（选股器管理）。 */
+	screenerStore;
+	constructor(ctx, deps, serviceName = TRADING_STRATEGIES_KEY) {
+		super(ctx, serviceName);
+		this.store = deps.store;
+		this.tombstones = deps.tombstones;
+		this.screenerStore = deps.screenerStore;
+	}
+};
 //#endregion
-export { apply, createFileCustomStrategyStore, createMarketDataResolver, createStrategyAuthorTool, createStrategyBacktestTool, defaultStorePath, inject, name, resolveStrategyDefinition };
+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 };