@dshtrading/watchlist 0.5.0 → 0.6.0

package/lib/file-store.js

@@ -1,14 +1,17 @@
 import { WATCHLIST_SEEDS } from "./seeds.js";
 import { newWatchlistGroupId, normalizeWatchlistRow } from "./index.js";
-import { writeJsonAtomic } from "@dshtrading/dsh-home";
+import { transactStore } from "@dshtrading/dsh-home";
 import { readFile } from "node:fs/promises";
 //#region src/file-store.ts
 /**
-* 文件持久化版自选/选中 store（Node.js 宿主侧使用，tmp+rename 原子写，
-* indicators/custom-fs 同款模式——issue #32 规格）。
+* 文件持久化版自选/选中 store（Node.js 宿主侧使用，issue #32 规格）。
+*
+* 写路径经 `@dshtrading/dsh-home` 的 {@link transactStore}——跨进程排他锁 + 锁内
+* 新鲜读盘 + 原子写（2026-10-09 多进程互相覆盖事故修复）：桌面端与 CLI 各写一行时
+* 双方都留在盘上，不再互相抹掉（此前是内存缓存 + 整表回写）。进程内的 enqueue 串行化
+* 保留（它保证同一进程内的读改写顺序），跨进程部分由锁承担。
 */
-/** 原子写唯一实现在 @dshtrading/dsh-home（tmp+rename、EPERM/EBUSY 重试、失败保留旧文件并清理 tmp）。 */
-const safeAtomicWrite = (filePath, data) => writeJsonAtomic(filePath, data, "[dsh-trading/watchlist] failed to atomic flush watchlists to");
+const LOG_PREFIX = "[dsh-trading/watchlist] failed to atomic flush watchlists to";
 function createFileWatchlistStore(filePath) {
 	let cache = null;
 	let pendingWrite = Promise.resolve();
@@ -17,122 +20,123 @@ function createFileWatchlistStore(filePath) {
 		pendingWrite = next.then(() => {}, () => {});
 		return next;
 	};
-	async function load() {
-		if (cache !== null) return cache;
+	/** 新鲜读盘（坏 JSON/非对象按空表）；供 load 与锁内重读共用。 */
+	async function readFromDisk() {
 		try {
 			const content = await readFile(filePath, "utf8");
 			const parsed = JSON.parse(content);
-			cache = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+			return 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 {};
 		}
-		return cache;
-	}
-	/** 仅在 enqueue 队列内调用：写盘不能二次入队（外层已持队，内层 enqueue 会自等死锁）。 */
-	function writeNow(map) {
-		return safeAtomicWrite(filePath, map);
 	}
-	async function flush(map) {
-		return enqueue(async () => {
-			await writeNow(map);
-		});
+	async function load() {
+		if (cache !== null) return cache;
+		cache = await readFromDisk();
+		return cache;
 	}
 	return {
 		async list() {
 			return { ...await load() };
 		},
 		async save(next) {
-			cache = { ...next };
-			await flush(cache);
+			await enqueue(async () => {
+				cache = await transactStore(filePath, readFromDisk, () => ({ ...next }), (map) => map, LOG_PREFIX);
+			});
 		},
 		async add(market, instrument) {
-			return enqueue(async () => {
-				const map = await load();
-				const rows = map[market] ?? [];
-				if (rows.some((row) => row.symbol === instrument.symbol)) return false;
-				const next = {
-					...map,
-					[market]: [...rows, normalizeWatchlistRow(instrument)]
-				};
-				cache = next;
-				await writeNow(next);
-				return true;
+			let added = false;
+			await enqueue(async () => {
+				cache = await transactStore(filePath, readFromDisk, (onDisk) => {
+					const rows = onDisk[market] ?? [];
+					if (rows.some((row) => row.symbol === instrument.symbol)) return onDisk;
+					added = true;
+					return {
+						...onDisk,
+						[market]: [...rows, normalizeWatchlistRow(instrument)]
+					};
+				}, (map) => map, LOG_PREFIX);
 			});
+			return added;
 		},
 		async remove(market, symbol) {
-			return enqueue(async () => {
-				const map = await load();
-				const existing = map[market];
-				const rows = Array.isArray(existing) ? existing : WATCHLIST_SEEDS[market] ?? [];
-				const nextRows = rows.filter((row) => row.symbol !== symbol);
-				if (nextRows.length === rows.length) return false;
-				const next = {
-					...map,
-					[market]: nextRows
-				};
-				cache = next;
-				await writeNow(next);
-				return true;
+			let removed = false;
+			await enqueue(async () => {
+				cache = await transactStore(filePath, readFromDisk, (onDisk) => {
+					const existing = onDisk[market];
+					const rows = Array.isArray(existing) ? existing : WATCHLIST_SEEDS[market] ?? [];
+					const nextRows = rows.filter((row) => row.symbol !== symbol);
+					if (nextRows.length === rows.length) return onDisk;
+					removed = true;
+					return {
+						...onDisk,
+						[market]: nextRows
+					};
+				}, (map) => map, LOG_PREFIX);
 			});
+			return removed;
 		},
 		async assignGroup(market, symbol, groupId, member) {
-			return enqueue(async () => {
-				const map = await load();
-				const rows = map[market];
-				if (!Array.isArray(rows)) return false;
-				const index = rows.findIndex((row) => row.symbol === symbol);
-				if (index < 0) return false;
-				const base = rows[index];
-				if (base === void 0) return false;
-				const current = Array.isArray(base.groups) ? base.groups : [];
-				if (member === current.includes(groupId)) return false;
-				const nextGroups = member ? [...current, groupId] : current.filter((id) => id !== groupId);
-				const nextRows = [...rows];
-				nextRows[index] = normalizeWatchlistRow({
-					market: base.market,
-					symbol: base.symbol,
-					...base.name !== void 0 ? { name: base.name } : {},
-					...nextGroups.length > 0 ? { groups: nextGroups } : {}
-				});
-				const next = {
-					...map,
-					[market]: nextRows
-				};
-				cache = next;
-				await writeNow(next);
-				return true;
+			let assigned = false;
+			await enqueue(async () => {
+				cache = await transactStore(filePath, readFromDisk, (onDisk) => {
+					const rows = onDisk[market];
+					if (!Array.isArray(rows)) return onDisk;
+					const index = rows.findIndex((row) => row.symbol === symbol);
+					if (index < 0) return onDisk;
+					const base = rows[index];
+					if (base === void 0) return onDisk;
+					const current = Array.isArray(base.groups) ? base.groups : [];
+					if (member === current.includes(groupId)) return onDisk;
+					const nextGroups = member ? [...current, groupId] : current.filter((id) => id !== groupId);
+					const nextRows = [...rows];
+					nextRows[index] = normalizeWatchlistRow({
+						market: base.market,
+						symbol: base.symbol,
+						...base.name !== void 0 ? { name: base.name } : {},
+						...base.form !== void 0 ? { form: base.form } : {},
+						...base.assetClass !== void 0 ? { assetClass: base.assetClass } : {},
+						...nextGroups.length > 0 ? { groups: nextGroups } : {}
+					});
+					assigned = true;
+					return {
+						...onDisk,
+						[market]: nextRows
+					};
+				}, (map) => map, LOG_PREFIX);
 			});
+			return assigned;
 		},
 		async stripGroup(groupId) {
-			return enqueue(async () => {
-				const map = await load();
-				let cleaned = 0;
-				const next = {};
-				for (const [market, rows] of Object.entries(map)) {
-					if (!Array.isArray(rows)) continue;
-					let changed = false;
-					const nextRows = rows.map((row) => {
-						const groups = Array.isArray(row.groups) ? row.groups : [];
-						if (!groups.includes(groupId)) return row;
-						changed = true;
-						cleaned++;
-						const rest = groups.filter((id) => id !== groupId);
-						return normalizeWatchlistRow({
-							market: row.market,
-							symbol: row.symbol,
-							...row.name !== void 0 ? { name: row.name } : {},
-							...rest.length > 0 ? { groups: rest } : {}
+			let cleaned = 0;
+			await enqueue(async () => {
+				cache = await transactStore(filePath, readFromDisk, (onDisk) => {
+					const next = {};
+					for (const [market, rows] of Object.entries(onDisk)) {
+						if (!Array.isArray(rows)) continue;
+						let changed = false;
+						const nextRows = rows.map((row) => {
+							const groups = Array.isArray(row.groups) ? row.groups : [];
+							if (!groups.includes(groupId)) return row;
+							changed = true;
+							cleaned++;
+							const rest = groups.filter((id) => id !== groupId);
+							return normalizeWatchlistRow({
+								market: row.market,
+								symbol: row.symbol,
+								...row.name !== void 0 ? { name: row.name } : {},
+								...row.form !== void 0 ? { form: row.form } : {},
+								...row.assetClass !== void 0 ? { assetClass: row.assetClass } : {},
+								...rest.length > 0 ? { groups: rest } : {}
+							});
 						});
-					});
-					next[market] = changed ? nextRows : rows;
-				}
-				if (cleaned > 0) {
-					cache = next;
-					await writeNow(next);
-				}
-				return cleaned;
+						next[market] = changed ? nextRows : rows;
+					}
+					return cleaned > 0 ? next : onDisk;
+				}, (map) => map, LOG_PREFIX);
 			});
+			return cleaned;
 		}
 	};
 }
@@ -144,65 +148,87 @@ function createFileWatchlistGroupsStore(filePath) {
 		pendingWrite = next.then(() => {}, () => {});
 		return next;
 	};
-	async function load() {
-		if (cache !== null) return cache;
+	/** 新鲜读盘（容器包裹；坏形过滤）；供 load 与锁内重读共用。 */
+	async function readFromDisk() {
 		try {
 			const content = await readFile(filePath, "utf8");
 			const parsed = JSON.parse(content);
-			cache = Array.isArray(parsed.groups) ? parsed.groups.filter((group) => typeof group === "object" && group !== null && typeof group.id === "string" && group.id !== "" && typeof group.name === "string") : [];
+			return Array.isArray(parsed.groups) ? parsed.groups.filter((group) => typeof group === "object" && group !== null && typeof group.id === "string" && group.id !== "" && typeof group.name === "string") : [];
 		} catch (err) {
 			if (err?.code !== "ENOENT") console.error(`[dsh-trading/watchlist] failed to read watchlist groups from ${filePath}:`, err);
-			cache = [];
+			return [];
 		}
+	}
+	async function load() {
+		if (cache !== null) return cache;
+		cache = await readFromDisk();
 		return cache;
 	}
-	function writeNow(groups) {
-		return safeAtomicWrite(filePath, { groups });
+	const serialize = (groups) => ({ groups });
+	/** 跨进程读改写；返回 null 表示无变化（不落盘），缓存仍取锁内新鲜值。 */
+	async function commit(mutate) {
+		cache = await transactStore(filePath, readFromDisk, (onDisk) => mutate(onDisk) ?? onDisk, serialize, LOG_PREFIX);
+		return cache;
 	}
 	return {
 		async list() {
 			return [...await load()];
 		},
 		async create(name) {
-			return enqueue(async () => {
-				const groups = await load();
-				if (groups.some((group) => group.name === name)) return { error: "duplicate" };
-				const group = {
-					id: newWatchlistGroupId(),
-					name,
-					createdAt: Date.now()
-				};
-				cache = [...groups, group];
-				await writeNow(cache);
-				return { group };
+			let result;
+			await enqueue(async () => {
+				await commit((onDisk) => {
+					if (onDisk.some((group) => group.name === name)) {
+						result = { error: "duplicate" };
+						return null;
+					}
+					const group = {
+						id: newWatchlistGroupId(),
+						name,
+						createdAt: Date.now()
+					};
+					result = { group };
+					return [...onDisk, group];
+				});
 			});
+			return result ?? { error: "duplicate" };
 		},
 		async rename(id, name) {
-			return enqueue(async () => {
-				const groups = await load();
-				const existing = groups.find((group) => group.id === id);
-				if (existing === void 0) return { error: "not-found" };
-				if (groups.some((group) => group.id !== id && group.name === name)) return { error: "duplicate" };
-				cache = groups.map((group) => group.id === id ? {
-					...group,
-					name
-				} : group);
-				await writeNow(cache);
-				return { group: {
-					...existing,
-					name
-				} };
+			let result;
+			await enqueue(async () => {
+				await commit((onDisk) => {
+					const existing = onDisk.find((group) => group.id === id);
+					if (existing === void 0) {
+						result = { error: "not-found" };
+						return null;
+					}
+					if (onDisk.some((group) => group.id !== id && group.name === name)) {
+						result = { error: "duplicate" };
+						return null;
+					}
+					result = { group: {
+						...existing,
+						name
+					} };
+					return onDisk.map((group) => group.id === id ? {
+						...group,
+						name
+					} : group);
+				});
 			});
+			return result ?? { error: "not-found" };
 		},
 		async remove(id) {
-			return enqueue(async () => {
-				const groups = await load();
-				const next = groups.filter((group) => group.id !== id);
-				if (next.length === groups.length) return false;
-				cache = next;
-				await writeNow(next);
-				return true;
+			let removed = false;
+			await enqueue(async () => {
+				await commit((onDisk) => {
+					const next = onDisk.filter((group) => group.id !== id);
+					if (next.length === onDisk.length) return null;
+					removed = true;
+					return next;
+				});
 			});
+			return removed;
 		}
 	};
 }
@@ -214,22 +240,21 @@ function createFileSelectionStore(filePath) {
 		pendingWrite = next.then(() => {}, () => {});
 		return next;
 	};
-	async function load() {
-		if (cache !== null) return cache;
+	/** 新鲜读盘（坏形按空选中）；供 load 与锁内重读共用。 */
+	async function readFromDisk() {
 		try {
 			const content = await readFile(filePath, "utf8");
 			const parsed = JSON.parse(content);
-			cache = parsed !== null && typeof parsed === "object" ? { instrument: parsed.instrument ?? null } : { instrument: null };
+			return 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 { instrument: null };
 		}
-		return cache;
 	}
-	async function flush(record) {
-		return enqueue(async () => {
-			await safeAtomicWrite(filePath, record);
-		});
+	async function load() {
+		if (cache !== null) return cache;
+		cache = await readFromDisk();
+		return cache;
 	}
 	return {
 		async get() {
@@ -237,8 +262,9 @@ function createFileSelectionStore(filePath) {
 			return { instrument: record.instrument === null ? null : { ...record.instrument } };
 		},
 		async set(record) {
-			cache = { instrument: record.instrument === null ? null : { ...record.instrument } };
-			await flush(cache);
+			await enqueue(async () => {
+				cache = await transactStore(filePath, readFromDisk, () => ({ instrument: record.instrument === null ? null : { ...record.instrument } }), (value) => value, LOG_PREFIX);
+			});
 		}
 	};
 }

package/lib/index.d.ts

@@ -1,35 +1,20 @@
 import { WATCHLIST_SEEDS, effectiveWatchlistRows, watchlistRowSource } from "./seeds.js";
+import { InstrumentAssetClass, InstrumentForm } from "@dshtrading/api";
 //#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 = 未定制，客户端回落种子）。
- *   行可带 `groups`（自定义分组 id 多归属，issue #82）；分组注册表另存
- *   watchlist-groups.json（`./file-store.ts` 的 groups store）。
- * - `SelectionRecord`：跨市场选中标的（watchlist_select 工具与左栏点击同源）。
- * - `./plugin` 子路径：file store（~/.dsh/watchlists.json、~/.dsh/selection.json、
- *   ~/.dsh/watchlist-groups.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;
+  /**
+   * 形态轴（2026-10-08 加密永续落地，词汇家在 `@dshtrading/api`）：缺省 = 现货。
+   * 读侧判据与 catalog 同款——显式值优先，缺省回落 `instrumentFormOf(symbol)`
+   * （符号后缀即形态载体，见 docs/guides/symbol-vocabulary.md）。
+   */
+  form?: InstrumentForm;
+  /** 资产类别（交易所元数据原样透传；取不到即留空，禁止按符号猜——SPX/US500 反例）。 */
+  assetClass?: InstrumentAssetClass;
   /**
    * 所属自定义分组 id 数组（issue #82；多归属，一行可入多组；缺省/空 = 未分组）。
    * 分组注册表（名称等元数据）在 ./file-store.ts 的 groups store，行上只存 id。
@@ -79,7 +64,7 @@ interface SelectionStore {
   get(): Promise<SelectionRecord>;
   set(record: SelectionRecord): Promise<void>;
 }
-/** 行规范化副本：groups 空数组不落键，保持落盘/输出形状干净。 */
+/** 行规范化副本：groups 空数组不落键，保持落盘/输出形状干净；形态/资产类别可选项原样保真。 */
 declare function normalizeWatchlistRow(row: WatchlistInstrument): WatchlistInstrument;
 /** 新分组 id（时间戳 base36 + 随机尾，进程内唯一即可——注册表单文件单写者）。 */
 declare function newWatchlistGroupId(): string;

package/lib/index.js

@@ -1,12 +1,14 @@
 import { WATCHLIST_SEEDS, effectiveWatchlistRows, watchlistRowSource } from "./seeds.js";
 //#region src/index.ts
-/** 行规范化副本：groups 空数组不落键，保持落盘/输出形状干净。 */
+/** 行规范化副本：groups 空数组不落键，保持落盘/输出形状干净；形态/资产类别可选项原样保真。 */
 function normalizeWatchlistRow(row) {
 	const groups = Array.isArray(row.groups) ? [...new Set(row.groups.filter((item) => typeof item === "string" && item))] : [];
 	return {
 		market: row.market,
 		symbol: row.symbol,
 		...row.name !== void 0 ? { name: row.name } : {},
+		...row.form !== void 0 ? { form: row.form } : {},
+		...row.assetClass !== void 0 ? { assetClass: row.assetClass } : {},
 		...groups.length > 0 ? { groups } : {}
 	};
 }
@@ -59,6 +61,8 @@ function createMemoryWatchlistStore(initial = {}) {
 				market: base.market,
 				symbol: base.symbol,
 				...base.name !== void 0 ? { name: base.name } : {},
+				...base.form !== void 0 ? { form: base.form } : {},
+				...base.assetClass !== void 0 ? { assetClass: base.assetClass } : {},
 				...nextGroups.length > 0 ? { groups: nextGroups } : {}
 			});
 			map = {
@@ -83,6 +87,8 @@ function createMemoryWatchlistStore(initial = {}) {
 						market: row.market,
 						symbol: row.symbol,
 						...row.name !== void 0 ? { name: row.name } : {},
+						...row.form !== void 0 ? { form: row.form } : {},
+						...row.assetClass !== void 0 ? { assetClass: row.assetClass } : {},
 						...rest.length > 0 ? { groups: rest } : {}
 					});
 				});

package/lib/plugin.js

@@ -6,6 +6,15 @@ import { defineTool } from "@deepseek-ai/dsh-tools";
 import path from "node:path";
 import { dshHomeDir } from "@dshtrading/dsh-home";
 //#region src/plugin.ts
+function jsonOutput(schema) {
+	return {
+		schema,
+		render: (_args, value) => [{
+			type: "text",
+			text: JSON.stringify(value)
+		}]
+	};
+}
 /** Cordis 插件名 = patch 行 id（TEMPLATES §8），市场无关共享行命名空间。 */
 const name = "dsh-trading-watchlist";
 /** 本插件不硬依赖任何服务；tools 经 ctx.inject 声明。 */
@@ -61,7 +70,7 @@ function countGroupMembers(map, groupId) {
 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). It also returns \"groups\" (the user's custom groups with id, name and member count) and \"selection\" (the instrument currently focused in the GUI chart, or null). Group membership lives on each row as row.groups (group ids); rows without groups are ungrouped. ALWAYS call this first when the user mentions any instrument by name or symbol, when you need a group id for watchlist_group_assign/rename/delete, or when you need the current selection; never conclude an instrument is untracked from docs or connector coverage alone. Read-only.",
+		description: "List the user's watchlist across all markets (crypto/us/cn/hk), exactly as the trading GUI sidebar shows it. Rows merge customized entries (source \"custom\") with market seed rows (source \"seed\"), so this list IS what the user sees, and display names map to symbols (e.g. 苹果 → AAPL / us). Returns \"groups\" (id, name, member count) and \"selection\" (chart-focused instrument or null); membership is row.groups. Call it first when the user names an instrument or you need a group id.",
 		parameters: {},
 		output: {
 			schema: { type: "string" },
@@ -118,25 +127,37 @@ function createWatchlistAddTool(deps) {
 			},
 			name: {
 				type: "string",
-				description: "Optional display name, e.g. 贵州茅台"
+				description: "Optional display name, e.g. 贵州茅台 (Kweichow Moutai)."
 			}
 		},
-		output: {
-			schema: { type: "string" },
-			render: (_args, value) => [{
-				type: "text",
-				text: value
-			}]
-		},
+		output: jsonOutput({
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				ok: {
+					type: "boolean",
+					const: true,
+					required: true
+				},
+				added: {
+					type: "boolean",
+					required: true
+				},
+				note: {
+					type: "string",
+					required: true
+				}
+			}
+		}),
 		async execute(raw) {
 			const instrument = parseInstrumentArgs(raw ?? {});
 			const added = await deps.watchlists.add(instrument.market, instrument);
 			if (added) deps.onWatchlistsChanged?.();
-			return JSON.stringify({
+			return {
 				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).`
-			});
+			};
 		}
 	});
 }
@@ -156,22 +177,34 @@ function createWatchlistRemoveTool(deps) {
 				description: "Market-canonical symbol to remove"
 			}
 		},
-		output: {
-			schema: { type: "string" },
-			render: (_args, value) => [{
-				type: "text",
-				text: value
-			}]
-		},
+		output: jsonOutput({
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				ok: {
+					type: "boolean",
+					const: true,
+					required: true
+				},
+				removed: {
+					type: "boolean",
+					required: true
+				},
+				note: {
+					type: "string",
+					required: true
+				}
+			}
+		}),
 		async execute(raw) {
 			const { market, symbol } = parseInstrumentArgs(raw ?? {});
 			const removed = await deps.watchlists.remove(market, symbol);
 			if (removed) deps.onWatchlistsChanged?.();
-			return JSON.stringify({
+			return {
 				ok: true,
 				removed,
 				note: removed ? `Removed ${symbol} from the ${market} watchlist.` : `${symbol} was not in the ${market} watchlist (nothing changed).`
-			});
+			};
 		}
 	});
 }
@@ -218,7 +251,7 @@ function createWatchlistSelectTool(deps) {
 function createWatchlistGroupCreateTool(deps) {
 	return defineTool({
 		name: "watchlist_group_create",
-		description: "Create a named custom watchlist group (a cross-market bucket for organizing the user watchlist, e.g. \"港股观察\" / \"核心仓\"). Group names are unique (trimmed, 24 chars max); creating an existing name is refused. The returned id is what watchlist_group_assign / watchlist_group_rename / watchlist_group_delete take — call watchlist_list first to see existing groups and their member counts. The open GUI sidebar refreshes live over the SSE invalidation channel.",
+		description: "Create a named custom watchlist group — a cross-market bucket for organizing the user watchlist, e.g. \"港股观察\". Names are trimmed, unique and at most 24 characters; an existing name is refused. The returned id is what watchlist_group_assign / watchlist_group_rename / watchlist_group_delete take, so call watchlist_list first to see existing groups and member counts. The open GUI sidebar refreshes live over the SSE channel.",
 		parameters: { name: {
 			type: "string",
 			required: true,
@@ -314,7 +347,7 @@ function createWatchlistGroupRenameTool(deps) {
 function createWatchlistGroupDeleteTool(deps) {
 	return defineTool({
 		name: "watchlist_group_delete",
-		description: "Delete a custom watchlist group by id. Deleting a group clears its membership from every watchlist row but NEVER deletes watchlist rows themselves (the instruments stay in the watchlist, only the grouping is dropped). DISCIPLINE: before calling this, tell the user the group name and how many member rows it has (watchlist_list returns members), and call it only after they confirm; then report the same numbers back after the call. Refused when the id is unknown. The open GUI sidebar refreshes live over the SSE invalidation channel.",
+		description: "Delete a custom watchlist group by id. Deleting a group clears its membership on every watchlist row but NEVER deletes watchlist rows — the instruments stay, only the grouping goes. DISCIPLINE: tell the user the group name and member count (watchlist_list returns members) and call it only after they confirm; report the same numbers afterwards. Refused for an unknown id. The GUI sidebar refreshes live over the SSE invalidation channel.",
 		parameters: { id: {
 			type: "string",
 			required: true,
@@ -353,7 +386,7 @@ function createWatchlistGroupDeleteTool(deps) {
 function createWatchlistGroupAssignTool(deps) {
 	return defineTool({
 		name: "watchlist_group_assign",
-		description: "Add or remove one watchlist instrument to/from a custom group (set member=true to add, member=false to remove). The instrument must already be in the watchlist or be a market seed row; when the market has no customized rows yet the target row is materialized from that market seed baseline first (result field materialized=true) — this mirrors the GUI drag behavior, and no other rows are lost. Removing membership never deletes the watchlist row. Unknown group ids are refused (no dangling membership). The open GUI sidebar refreshes live over the SSE invalidation channel.",
+		description: "Add or remove one watchlist instrument to/from a custom group (member=true adds, false removes). The instrument must already be in the watchlist or be a market seed row; when the market has no customized rows the target row is materialized from its seed baseline first (result field materialized=true) and no other rows are lost. Removing membership never deletes the row, and an unknown group id is refused. The GUI sidebar refreshes live over the SSE invalidation channel.",
 		parameters: {
 			id: {
 				type: "string",
@@ -377,7 +410,7 @@ function createWatchlistGroupAssignTool(deps) {
 			},
 			name: {
 				type: "string",
-				description: "Optional display name used only when the row must be materialized, e.g. 贵州茅台"
+				description: "Optional display name used only when the row must be materialized, e.g. 贵州茅台 (Kweichow Moutai)."
 			}
 		},
 		output: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.5.0",
+  "version": "0.6.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -21,7 +21,8 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "dependencies": {
-    "@dshtrading/dsh-home": "^0.5.0"
+    "@dshtrading/api": "^0.6.0",
+    "@dshtrading/dsh-home": "^0.6.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.0",