@dshtrading/watchlist 0.1.0

package/LICENSE

@@ -0,0 +1,75 @@
+Copyright (c) 2026 zhu1090093659 (dsh-trading)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/lib/file-store.d.ts

@@ -0,0 +1,6 @@
+import { SelectionStore, WatchlistStore } from "./index.js";
+//#region src/file-store.d.ts
+declare function createFileWatchlistStore(filePath: string): WatchlistStore;
+declare function createFileSelectionStore(filePath: string): SelectionStore;
+//#endregion
+export { createFileSelectionStore, createFileWatchlistStore };

package/lib/file-store.js

@@ -0,0 +1,132 @@
+import { dirname } from "node:path";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+//#region src/file-store.ts
+/**
+* 文件持久化版自选/选中 store（Node.js 宿主侧使用，tmp+rename 原子写，
+* indicators/custom-fs 同款模式——issue #32 规格）。
+*/
+/**
+* 跨平台健壮原子写入：rename 遇 Windows EPERM/EBUSY（目标被占用）短暂退避重试；
+* 重试耗尽或任何失败一律保留旧文件、清理 tmp、log + throw——目标文件永远只被
+* 原子 rename 触碰，绝不非原子直写（防止半截写损坏 JSON 导致 load 静默重置）。
+*/
+async function safeAtomicWrite(filePath, data) {
+	const dir = dirname(filePath);
+	const tmpPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+	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/watchlist] failed to atomic flush watchlists to ${filePath}:`, error);
+		await unlink(tmpPath).catch(() => {});
+		throw error;
+	}
+}
+function createFileWatchlistStore(filePath) {
+	let cache = null;
+	let pendingWrite = Promise.resolve();
+	const enqueue = (fn) => {
+		const next = pendingWrite.then(fn, fn);
+		pendingWrite = next.then(() => {}, () => {});
+		return next;
+	};
+	async function load() {
+		if (cache !== null) return cache;
+		try {
+			const content = await readFile(filePath, "utf8");
+			const parsed = JSON.parse(content);
+			cache = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+		} catch (err) {
+			if (err?.code !== "ENOENT") console.error(`[dsh-trading/watchlist] failed to read watchlists from ${filePath}:`, err);
+			cache = {};
+		}
+		return cache;
+	}
+	async function flush(map) {
+		return enqueue(async () => {
+			await safeAtomicWrite(filePath, JSON.stringify(map, null, 2));
+		});
+	}
+	return {
+		async list() {
+			return { ...await load() };
+		},
+		async save(next) {
+			cache = { ...next };
+			await flush(cache);
+		},
+		async add(market, instrument) {
+			const map = await load();
+			const rows = map[market] ?? [];
+			if (rows.some((row) => row.symbol === instrument.symbol)) return false;
+			const next = {
+				...map,
+				[market]: [...rows, { ...instrument }]
+			};
+			cache = next;
+			await flush(next);
+			return true;
+		},
+		async remove(market, symbol) {
+			const map = await load();
+			const rows = map[market] ?? [];
+			const nextRows = rows.filter((row) => row.symbol !== symbol);
+			if (nextRows.length === rows.length) return false;
+			const next = {
+				...map,
+				[market]: nextRows
+			};
+			cache = next;
+			await flush(next);
+			return true;
+		}
+	};
+}
+function createFileSelectionStore(filePath) {
+	let cache = null;
+	let pendingWrite = Promise.resolve();
+	const enqueue = (fn) => {
+		const next = pendingWrite.then(fn, fn);
+		pendingWrite = next.then(() => {}, () => {});
+		return next;
+	};
+	async function load() {
+		if (cache !== null) return cache;
+		try {
+			const content = await readFile(filePath, "utf8");
+			const parsed = JSON.parse(content);
+			cache = parsed !== null && typeof parsed === "object" ? { instrument: parsed.instrument ?? null } : { instrument: null };
+		} catch (err) {
+			if (err?.code !== "ENOENT") console.error(`[dsh-trading/watchlist] failed to read selection from ${filePath}:`, err);
+			cache = { instrument: null };
+		}
+		return cache;
+	}
+	async function flush(record) {
+		return enqueue(async () => {
+			await safeAtomicWrite(filePath, JSON.stringify(record, null, 2));
+		});
+	}
+	return {
+		async get() {
+			const record = await load();
+			return { instrument: record.instrument === null ? null : { ...record.instrument } };
+		},
+		async set(record) {
+			cache = { instrument: record.instrument === null ? null : { ...record.instrument } };
+			await flush(cache);
+		}
+	};
+}
+//#endregion
+export { createFileSelectionStore, createFileWatchlistStore };

package/lib/index.d.ts

@@ -0,0 +1,56 @@
+import { WATCHLIST_SEEDS, effectiveWatchlistRows, watchlistRowSource } from "./seeds.js";
+//#region src/index.d.ts
+/**
+ * @dshtrading/watchlist —— host 侧自选股与选中标的存储（issue #32 / P3）。
+ *
+ * 背景：自选股原先只存浏览器 localStorage（dshtrading.watchlist.v1），node 半的
+ * Agent 触达不了——四块能力中 Agent 工具面唯一完全空白的一块。owner 2026-08-31
+ * 裁决（D3）：存储升位 localStorage → host file store（含一次性迁移），localStorage
+ * 降级为缓存镜像，不再是 SSOT。
+ *
+ * 本模块（纯类型 + 内存 store，浏览器安全）：
+ * - `WatchlistsMap`：按 market 分桶的多列表行（rows 只存用户定制行；市场种子列表
+ *   属客户端展示回退，不进 host store——空 market = 未定制，客户端回落种子）。
+ * - `SelectionRecord`：跨市场选中标的（watchlist_select 工具与左栏点击同源）。
+ * - `./plugin` 子路径：file store（~/.dsh/watchlists.json、~/.dsh/selection.json，
+ *   tmp+rename 原子写）+ host 平面工具 watchlist_list/add/remove/select（全会话可见，
+ *   owner 裁决 D4；select/add/remove 后 emit tradingEvents('watchlists'|'selection')）。
+ *
+ * 词汇纪律：symbol 用市场规范形（docs/symbol-vocabulary.md），本包不做归一化
+ * （写入方负责——工具参数与桥端点均原样落盘）。
+ *
+ * @module @dshtrading/watchlist
+ */
+/** 跨市场标的行（market 为市场词汇 slug：crypto | us | cn | hk，开放新市场）。 */
+interface WatchlistInstrument {
+  market: string;
+  symbol: string;
+  /** 展示名（可选；工具添加可缺省，客户端以 symbol 兜底展示）。 */
+  name?: string;
+}
+/** 多列表自选：market → 用户定制行数组（空数组/缺键 = 未定制）。 */
+type WatchlistsMap = Record<string, WatchlistInstrument[]>;
+/** 选中标的记录（中栏切图的 SSOT）。 */
+interface SelectionRecord {
+  instrument: WatchlistInstrument | null;
+}
+interface WatchlistStore {
+  /** 全量读取（host SSOT；客户端启动同步与 SSE 重拉都走这里）。 */
+  list(): Promise<WatchlistsMap>;
+  /** 全量替换（桥 PUT / 客户端迁移导入）。 */
+  save(map: WatchlistsMap): Promise<void>;
+  /** 追加一行（同 market 内按 symbol 去重）；返回是否新增。 */
+  add(market: string, instrument: WatchlistInstrument): Promise<boolean>;
+  /** 移除一行；返回是否 existed。 */
+  remove(market: string, symbol: string): Promise<boolean>;
+}
+interface SelectionStore {
+  get(): Promise<SelectionRecord>;
+  set(record: SelectionRecord): Promise<void>;
+}
+/** 内存版自选 store（单测用）。 */
+declare function createMemoryWatchlistStore(initial?: WatchlistsMap): WatchlistStore;
+/** 内存版选中 store（单测用）。 */
+declare function createMemorySelectionStore(initial?: SelectionRecord): SelectionStore;
+//#endregion
+export { SelectionRecord, SelectionStore, WATCHLIST_SEEDS, WatchlistInstrument, WatchlistStore, WatchlistsMap, createMemorySelectionStore, createMemoryWatchlistStore, effectiveWatchlistRows, watchlistRowSource };

package/lib/index.js

@@ -0,0 +1,50 @@
+import { WATCHLIST_SEEDS, effectiveWatchlistRows, watchlistRowSource } from "./seeds.js";
+//#region src/index.ts
+/** 内存版自选 store（单测用）。 */
+function createMemoryWatchlistStore(initial = {}) {
+	let map = { ...initial };
+	return {
+		async list() {
+			return map;
+		},
+		async save(next) {
+			map = { ...next };
+		},
+		async add(market, instrument) {
+			const rows = map[market] ?? [];
+			if (rows.some((row) => row.symbol === instrument.symbol)) return false;
+			map = {
+				...map,
+				[market]: [...rows, { ...instrument }]
+			};
+			return true;
+		},
+		async remove(market, symbol) {
+			const rows = map[market] ?? [];
+			const next = rows.filter((row) => row.symbol !== symbol);
+			if (next.length === rows.length) return false;
+			map = {
+				...map,
+				[market]: next
+			};
+			return true;
+		}
+	};
+}
+/** 内存版选中 store（单测用）。 */
+function createMemorySelectionStore(initial = { instrument: null }) {
+	let current = { ...initial };
+	return {
+		async get() {
+			return current;
+		},
+		async set(record) {
+			current = {
+				...record,
+				instrument: record.instrument === null ? null : { ...record.instrument }
+			};
+		}
+	};
+}
+//#endregion
+export { WATCHLIST_SEEDS, createMemorySelectionStore, createMemoryWatchlistStore, effectiveWatchlistRows, watchlistRowSource };

package/lib/plugin.d.ts

@@ -0,0 +1,34 @@
+import { SelectionStore, WatchlistStore, createMemorySelectionStore, createMemoryWatchlistStore } from "./index.js";
+import { createFileSelectionStore, createFileWatchlistStore } from "./file-store.js";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/plugin.d.ts
+/** Cordis 插件名 = patch 行 id（TEMPLATES §8），市场无关共享行命名空间。 */
+declare const name = "dsh-trading-watchlist";
+/** 本插件不硬依赖任何服务；tools 经 ctx.inject 声明。 */
+declare const inject: string[];
+/** 默认存储路径。 */
+declare function defaultWatchlistStorePath(): string;
+declare function defaultSelectionStorePath(): string;
+/** tradingEvents 的最小发布面（鸭式；总线缺席时静默降级）。 */
+interface TradingEventsPublisher {
+  emit(store: 'watchlists' | 'selection'): void;
+}
+interface WatchlistToolDeps {
+  watchlists: WatchlistStore;
+  selection: SelectionStore;
+  onWatchlistsChanged?: () => void;
+  onSelectionChanged?: () => void;
+}
+declare function createWatchlistListTool(deps: WatchlistToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+declare function createWatchlistAddTool(deps: WatchlistToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+declare function createWatchlistRemoveTool(deps: WatchlistToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+declare function createWatchlistSelectTool(deps: WatchlistToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+interface WatchlistPluginDeps {
+  watchlists: WatchlistStore;
+  selection: SelectionStore;
+}
+declare function registerWatchlistTools(ctx: Context, deps: WatchlistPluginDeps): void;
+/** Host plugin body：file store provide + 4 工具注册（host 平面，全会话可见）。 */
+declare function apply(ctx: Context): void;
+//#endregion
+export { TradingEventsPublisher, WatchlistPluginDeps, WatchlistToolDeps, apply, createFileSelectionStore, createFileWatchlistStore, createMemorySelectionStore, createMemoryWatchlistStore, createWatchlistAddTool, createWatchlistListTool, createWatchlistRemoveTool, createWatchlistSelectTool, defaultSelectionStorePath, defaultWatchlistStorePath, inject, name, registerWatchlistTools };

package/lib/plugin.js

@@ -0,0 +1,207 @@
+import { WATCHLIST_SEEDS, effectiveWatchlistRows, watchlistRowSource } from "./seeds.js";
+import { createMemorySelectionStore, createMemoryWatchlistStore } from "./index.js";
+import { createFileSelectionStore, createFileWatchlistStore } from "./file-store.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-watchlist";
+/** 本插件不硬依赖任何服务；tools 经 ctx.inject 声明。 */
+const inject = [];
+/** 默认存储路径。 */
+function defaultWatchlistStorePath() {
+	return path.join(os.homedir(), ".dsh", "watchlists.json");
+}
+function defaultSelectionStorePath() {
+	return path.join(os.homedir(), ".dsh", "selection.json");
+}
+function eventsOf(ctx) {
+	return ctx.get?.("tradingEvents", false);
+}
+function parseInstrumentArgs(raw) {
+	const market = typeof raw.market === "string" ? raw.market.trim() : "";
+	const symbol = typeof raw.symbol === "string" ? raw.symbol.trim() : "";
+	const name = typeof raw.name === "string" && raw.name.trim() ? raw.name.trim() : void 0;
+	if (!market || !symbol) throw new Error("market and symbol are required (market: crypto|us|cn|hk…, symbol: 市场规范形，如 BTCUSDT / AAPL / 600519 / 00700)");
+	return {
+		market,
+		symbol,
+		name
+	};
+}
+function createWatchlistListTool(deps) {
+	return defineTool({
+		name: "watchlist_list",
+		description: "List the user's watchlist exactly as displayed in the trading GUI sidebar, across all markets (crypto/us/cn/hk). Rows merge the user's customized entries (source \"custom\") with each market's default seed rows (source \"seed\", shown while that market has no custom edits) — the GUI shows the same rows, so this list IS what the user sees. It also maps display names to symbols (e.g. 苹果 → AAPL / us, 贵州茅台 → 600519 / cn). ALWAYS call this first when the user mentions any instrument by name or symbol; never conclude an instrument is untracked from docs or connector coverage alone. Read-only.",
+		parameters: {},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute() {
+			const map = await deps.watchlists.list();
+			const markets = [.../* @__PURE__ */ new Set([...Object.keys(map), ...Object.keys(WATCHLIST_SEEDS)])].filter((market) => effectiveWatchlistRows(map, market).length > 0);
+			const watchlists = {};
+			const sources = {};
+			let total = 0;
+			for (const market of markets) {
+				const rows = effectiveWatchlistRows(map, market);
+				watchlists[market] = rows;
+				sources[market] = watchlistRowSource(map, market);
+				total += rows.length;
+			}
+			return JSON.stringify({
+				ok: true,
+				total,
+				markets,
+				sources,
+				watchlists
+			});
+		}
+	});
+}
+function createWatchlistAddTool(deps) {
+	return defineTool({
+		name: "watchlist_add",
+		description: "Add an instrument to the user watchlist (cross-market, no tool-name market prefix). Deduplicated per market by symbol. The open GUI sidebar refreshes live over the SSE invalidation channel.",
+		parameters: {
+			market: {
+				type: "string",
+				required: true,
+				description: "Market vocabulary slug: crypto | us | cn | hk"
+			},
+			symbol: {
+				type: "string",
+				required: true,
+				description: "Market-canonical symbol (docs/symbol-vocabulary.md), e.g. BTCUSDT / AAPL / 600519 / 00700"
+			},
+			name: {
+				type: "string",
+				description: "Optional display name, e.g. 贵州茅台"
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const instrument = parseInstrumentArgs(raw ?? {});
+			const added = await deps.watchlists.add(instrument.market, instrument);
+			if (added) deps.onWatchlistsChanged?.();
+			return JSON.stringify({
+				ok: true,
+				added,
+				note: added ? `Added ${instrument.symbol} (${instrument.market}) to the watchlist.` : `${instrument.symbol} is already in the ${instrument.market} watchlist (deduplicated, nothing changed).`
+			});
+		}
+	});
+}
+function createWatchlistRemoveTool(deps) {
+	return defineTool({
+		name: "watchlist_remove",
+		description: "Remove an instrument from the user watchlist (cross-market). The open GUI sidebar refreshes live over the SSE invalidation channel.",
+		parameters: {
+			market: {
+				type: "string",
+				required: true,
+				description: "Market vocabulary slug: crypto | us | cn | hk"
+			},
+			symbol: {
+				type: "string",
+				required: true,
+				description: "Market-canonical symbol to remove"
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const { market, symbol } = parseInstrumentArgs(raw ?? {});
+			const removed = await deps.watchlists.remove(market, symbol);
+			if (removed) deps.onWatchlistsChanged?.();
+			return JSON.stringify({
+				ok: true,
+				removed,
+				note: removed ? `Removed ${symbol} from the ${market} watchlist.` : `${symbol} was not in the ${market} watchlist (nothing changed).`
+			});
+		}
+	});
+}
+function createWatchlistSelectTool(deps) {
+	return defineTool({
+		name: "watchlist_select",
+		description: "Select an instrument as the focused chart in the trading GUI (cross-market). The open GUI switches the middle-stage chart to this instrument live over the SSE channel. Prefer an instrument that exists in watchlist_list (its display name is reused); unknown symbols are accepted with the raw symbol as display fallback.",
+		parameters: {
+			market: {
+				type: "string",
+				required: true,
+				description: "Market vocabulary slug: crypto | us | cn | hk"
+			},
+			symbol: {
+				type: "string",
+				required: true,
+				description: "Market-canonical symbol to focus"
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const { market, symbol } = parseInstrumentArgs(raw ?? {});
+			const map = await deps.watchlists.list();
+			const instrument = effectiveWatchlistRows(map, market).find((row) => row.symbol === symbol) ?? {
+				market,
+				symbol
+			};
+			await deps.selection.set({ instrument });
+			deps.onSelectionChanged?.();
+			return JSON.stringify({
+				ok: true,
+				selected: instrument,
+				note: `Focused the chart on ${symbol} (${market}) — the open GUI switches live.`
+			});
+		}
+	});
+}
+function registerWatchlistTools(ctx, deps) {
+	ctx.inject(["tools"], (toolCtx) => {
+		const tools = toolCtx.tools;
+		if (!tools || typeof tools.register !== "function") return;
+		const hookDeps = {
+			...deps,
+			onWatchlistsChanged: () => eventsOf(ctx)?.emit("watchlists"),
+			onSelectionChanged: () => eventsOf(ctx)?.emit("selection")
+		};
+		const shared = { register: (tool) => {
+			if (tools.get(tool.name) === void 0) tools.register(tool);
+		} };
+		shared.register(createWatchlistListTool(hookDeps));
+		shared.register(createWatchlistAddTool(hookDeps));
+		shared.register(createWatchlistRemoveTool(hookDeps));
+		shared.register(createWatchlistSelectTool(hookDeps));
+	});
+}
+/** Host plugin body：file store provide + 4 工具注册（host 平面，全会话可见）。 */
+function apply(ctx) {
+	registerWatchlistTools(ctx, {
+		watchlists: createFileWatchlistStore(defaultWatchlistStorePath()),
+		selection: createFileSelectionStore(defaultSelectionStorePath())
+	});
+}
+//#endregion
+export { apply, createFileSelectionStore, createFileWatchlistStore, createMemorySelectionStore, createMemoryWatchlistStore, createWatchlistAddTool, createWatchlistListTool, createWatchlistRemoveTool, createWatchlistSelectTool, defaultSelectionStorePath, defaultWatchlistStorePath, inject, name, registerWatchlistTools };

package/lib/seeds.d.ts

@@ -0,0 +1,10 @@
+import { WatchlistInstrument, WatchlistsMap } from "./index.js";
+//#region src/seeds.d.ts
+/** 各市场种子行（connector-validated symbol formats）。 */
+declare const WATCHLIST_SEEDS: WatchlistsMap;
+/** 单市场展示行：用户定制行优先；未定制（缺键/空数组）回落该市场种子。 */
+declare function effectiveWatchlistRows(map: WatchlistsMap, market: string): WatchlistInstrument[];
+/** 单市场行来源：'custom' = 用户定制行；'seed' = 种子展示行（未定制）。 */
+declare function watchlistRowSource(map: WatchlistsMap, market: string): 'custom' | 'seed';
+//#endregion
+export { WATCHLIST_SEEDS, effectiveWatchlistRows, watchlistRowSource };

package/lib/seeds.js

@@ -0,0 +1,95 @@
+//#region src/seeds.ts
+/** 各市场种子行（connector-validated symbol formats）。 */
+const WATCHLIST_SEEDS = {
+	crypto: [
+		{
+			market: "crypto",
+			symbol: "BTCUSDT",
+			name: "Bitcoin"
+		},
+		{
+			market: "crypto",
+			symbol: "ETHUSDT",
+			name: "Ethereum"
+		},
+		{
+			market: "crypto",
+			symbol: "SOLUSDT",
+			name: "Solana"
+		},
+		{
+			market: "crypto",
+			symbol: "BNBUSDT",
+			name: "BNB"
+		}
+	],
+	us: [
+		{
+			market: "us",
+			symbol: "AAPL",
+			name: "苹果"
+		},
+		{
+			market: "us",
+			symbol: "MSFT",
+			name: "微软"
+		},
+		{
+			market: "us",
+			symbol: "NVDA",
+			name: "英伟达"
+		},
+		{
+			market: "us",
+			symbol: "GOOGL",
+			name: "谷歌"
+		}
+	],
+	cn: [
+		{
+			market: "cn",
+			symbol: "600519",
+			name: "贵州茅台"
+		},
+		{
+			market: "cn",
+			symbol: "000001",
+			name: "平安银行"
+		},
+		{
+			market: "cn",
+			symbol: "601318",
+			name: "中国平安"
+		}
+	],
+	hk: [
+		{
+			market: "hk",
+			symbol: "00700",
+			name: "腾讯控股"
+		},
+		{
+			market: "hk",
+			symbol: "09988",
+			name: "阿里巴巴-W"
+		},
+		{
+			market: "hk",
+			symbol: "03690",
+			name: "美团-W"
+		}
+	]
+};
+/** 单市场展示行：用户定制行优先；未定制（缺键/空数组）回落该市场种子。 */
+function effectiveWatchlistRows(map, market) {
+	const rows = map[market];
+	if (rows !== void 0 && rows.length > 0) return rows;
+	return WATCHLIST_SEEDS[market] ?? [];
+}
+/** 单市场行来源：'custom' = 用户定制行；'seed' = 种子展示行（未定制）。 */
+function watchlistRowSource(map, market) {
+	const rows = map[market];
+	return rows !== void 0 && rows.length > 0 ? "custom" : "seed";
+}
+//#endregion
+export { WATCHLIST_SEEDS, effectiveWatchlistRows, watchlistRowSource };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@dshtrading/watchlist",
+  "description": "Host-side watchlist + selection stores for dsh-trading: multi-list file store (~/.dsh/watchlists.json), selection store (~/.dsh/selection.json), and cross-market watchlist_* tools (watchlist_list/add/remove/select) on the host plane",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./plugin": {
+      "types": "./lib/plugin.d.ts",
+      "default": "./lib/plugin.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "dependencies": {},
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-alpha.1"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}