@dshtrading/watchlist 0.1.5 → 0.2.0

package/lib/file-store.d.ts

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

package/lib/file-store.js

@@ -1,38 +1,14 @@
 import { WATCHLIST_SEEDS } from "./seeds.js";
-import { dirname } from "node:path";
-import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { newWatchlistGroupId, normalizeWatchlistRow } from "./index.js";
+import { writeJsonAtomic } 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 规格）。
 */
-/**
-* 跨平台健壮原子写入：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;
-	}
-}
+/** 原子写唯一实现在 @dshtrading/dsh-home（tmp+rename、EPERM/EBUSY 重试、失败保留旧文件并清理 tmp）。 */
+const safeAtomicWrite = (filePath, data) => writeJsonAtomic(filePath, data, "[dsh-trading/watchlist] failed to atomic flush watchlists to");
 function createFileWatchlistStore(filePath) {
 	let cache = null;
 	let pendingWrite = Promise.resolve();
@@ -55,7 +31,7 @@ function createFileWatchlistStore(filePath) {
 	}
 	/** 仅在 enqueue 队列内调用：写盘不能二次入队（外层已持队，内层 enqueue 会自等死锁）。 */
 	function writeNow(map) {
-		return safeAtomicWrite(filePath, JSON.stringify(map, null, 2));
+		return safeAtomicWrite(filePath, map);
 	}
 	async function flush(map) {
 		return enqueue(async () => {
@@ -77,7 +53,7 @@ function createFileWatchlistStore(filePath) {
 				if (rows.some((row) => row.symbol === instrument.symbol)) return false;
 				const next = {
 					...map,
-					[market]: [...rows, { ...instrument }]
+					[market]: [...rows, normalizeWatchlistRow(instrument)]
 				};
 				cache = next;
 				await writeNow(next);
@@ -99,6 +75,134 @@ function createFileWatchlistStore(filePath) {
 				await writeNow(next);
 				return true;
 			});
+		},
+		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;
+			});
+		},
+		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 } : {}
+						});
+					});
+					next[market] = changed ? nextRows : rows;
+				}
+				if (cleaned > 0) {
+					cache = next;
+					await writeNow(next);
+				}
+				return cleaned;
+			});
+		}
+	};
+}
+function createFileWatchlistGroupsStore(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 = 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 cache;
+	}
+	function writeNow(groups) {
+		return safeAtomicWrite(filePath, { groups });
+	}
+	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 };
+			});
+		},
+		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
+				} };
+			});
+		},
+		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;
+			});
 		}
 	};
 }
@@ -124,7 +228,7 @@ function createFileSelectionStore(filePath) {
 	}
 	async function flush(record) {
 		return enqueue(async () => {
-			await safeAtomicWrite(filePath, JSON.stringify(record, null, 2));
+			await safeAtomicWrite(filePath, record);
 		});
 	}
 	return {
@@ -139,4 +243,4 @@ function createFileSelectionStore(filePath) {
 	};
 }
 //#endregion
-export { createFileSelectionStore, createFileWatchlistStore };
+export { createFileSelectionStore, createFileWatchlistGroupsStore, createFileWatchlistStore };

package/lib/index.d.ts

@@ -11,10 +11,13 @@ import { WATCHLIST_SEEDS, effectiveWatchlistRows, watchlistRowSource } from "./s
  * 本模块（纯类型 + 内存 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，
- *   tmp+rename 原子写）+ host 平面工具 watchlist_list/add/remove/select（全会话可见，
- *   owner 裁决 D4；select/add/remove 后 emit tradingEvents('watchlists'|'selection')）。
+ * - `./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），本包不做归一化
  * （写入方负责——工具参数与桥端点均原样落盘）。
@@ -27,9 +30,33 @@ interface WatchlistInstrument {
   symbol: string;
   /** 展示名（可选；工具添加可缺省，客户端以 symbol 兜底展示）。 */
   name?: string;
+  /**
+   * 所属自定义分组 id 数组（issue #82；多归属，一行可入多组；缺省/空 = 未分组）。
+   * 分组注册表（名称等元数据）在 ./file-store.ts 的 groups store，行上只存 id。
+   */
+  groups?: string[];
 }
 /** 多列表自选：market → 用户定制行数组（空数组/缺键 = 未定制）。 */
 type WatchlistsMap = Record<string, WatchlistInstrument[]>;
+/** 自定义分组注册表行（issue #82；成员关系在标的行的 groups 字段，此处只存元数据）。 */
+interface WatchlistGroup {
+  id: string;
+  /** 展示名（桥面保证 trim 非空；同名单向拒绝）。 */
+  name: string;
+  createdAt: number;
+}
+/** 分组写操作结果（桥面转业务 ok:false + reason；'duplicate' = 同名已存在，'not-found' = id 不存在）。 */
+interface WatchlistGroupWriteResult {
+  group?: WatchlistGroup;
+  error?: 'duplicate' | 'not-found';
+}
+/** 自定义分组注册表 store（元数据；成员关系的读写走 WatchlistStore.assignGroup/stripGroup）。 */
+interface WatchlistGroupsStore {
+  list(): Promise<WatchlistGroup[]>;
+  create(name: string): Promise<WatchlistGroupWriteResult>;
+  rename(id: string, name: string): Promise<WatchlistGroupWriteResult>;
+  remove(id: string): Promise<boolean>;
+}
 /** 选中标的记录（中栏切图的 SSOT）。 */
 interface SelectionRecord {
   instrument: WatchlistInstrument | null;
@@ -43,14 +70,24 @@ interface WatchlistStore {
   add(market: string, instrument: WatchlistInstrument): Promise<boolean>;
   /** 移除一行；返回是否 existed。 */
   remove(market: string, symbol: string): Promise<boolean>;
+  /** 加入/移出分组（issue #82）：行缺席或归属无变化返回 false（读改写入队串行化）。 */
+  assignGroup(market: string, symbol: string, groupId: string, member: boolean): Promise<boolean>;
+  /** 清掉所有行上的某分组归属（删分组时调用）；返回清洗行数，无变化不落盘。 */
+  stripGroup(groupId: string): Promise<number>;
 }
 interface SelectionStore {
   get(): Promise<SelectionRecord>;
   set(record: SelectionRecord): Promise<void>;
 }
+/** 行规范化副本：groups 空数组不落键，保持落盘/输出形状干净。 */
+declare function normalizeWatchlistRow(row: WatchlistInstrument): WatchlistInstrument;
+/** 新分组 id（时间戳 base36 + 随机尾，进程内唯一即可——注册表单文件单写者）。 */
+declare function newWatchlistGroupId(): string;
 /** 内存版自选 store（单测用）。 */
 declare function createMemoryWatchlistStore(initial?: WatchlistsMap): WatchlistStore;
+/** 内存版分组注册表 store（单测用）。同名拒绝（trim 后精确匹配）；调用方负责非空校验。 */
+declare function createMemoryWatchlistGroupsStore(initial?: WatchlistGroup[]): WatchlistGroupsStore;
 /** 内存版选中 store（单测用）。 */
 declare function createMemorySelectionStore(initial?: SelectionRecord): SelectionStore;
 //#endregion
-export { SelectionRecord, SelectionStore, WATCHLIST_SEEDS, WatchlistInstrument, WatchlistStore, WatchlistsMap, createMemorySelectionStore, createMemoryWatchlistStore, effectiveWatchlistRows, watchlistRowSource };
+export { SelectionRecord, SelectionStore, WATCHLIST_SEEDS, WatchlistGroup, WatchlistGroupWriteResult, WatchlistGroupsStore, WatchlistInstrument, WatchlistStore, WatchlistsMap, createMemorySelectionStore, createMemoryWatchlistGroupsStore, createMemoryWatchlistStore, effectiveWatchlistRows, newWatchlistGroupId, normalizeWatchlistRow, watchlistRowSource };

package/lib/index.js

@@ -1,5 +1,19 @@
 import { WATCHLIST_SEEDS, effectiveWatchlistRows, watchlistRowSource } from "./seeds.js";
 //#region src/index.ts
+/** 行规范化副本：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 } : {},
+		...groups.length > 0 ? { groups } : {}
+	};
+}
+/** 新分组 id（时间戳 base36 + 随机尾，进程内唯一即可——注册表单文件单写者）。 */
+function newWatchlistGroupId() {
+	return `g_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+}
 /** 内存版自选 store（单测用）。 */
 function createMemoryWatchlistStore(initial = {}) {
 	let map = { ...initial };
@@ -15,7 +29,7 @@ function createMemoryWatchlistStore(initial = {}) {
 			if (rows.some((row) => row.symbol === instrument.symbol)) return false;
 			map = {
 				...map,
-				[market]: [...rows, { ...instrument }]
+				[market]: [...rows, normalizeWatchlistRow(instrument)]
 			};
 			return true;
 		},
@@ -29,6 +43,91 @@ function createMemoryWatchlistStore(initial = {}) {
 				[market]: next
 			};
 			return true;
+		},
+		async assignGroup(market, symbol, groupId, member) {
+			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 } : {}
+			});
+			map = {
+				...map,
+				[market]: nextRows
+			};
+			return true;
+		},
+		async stripGroup(groupId) {
+			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 } : {}
+					});
+				});
+				next[market] = changed ? nextRows : rows;
+			}
+			if (cleaned > 0) map = next;
+			return cleaned;
+		}
+	};
+}
+/** 内存版分组注册表 store（单测用）。同名拒绝（trim 后精确匹配）；调用方负责非空校验。 */
+function createMemoryWatchlistGroupsStore(initial = []) {
+	let groups = [...initial];
+	return {
+		async list() {
+			return [...groups];
+		},
+		async create(name) {
+			if (groups.some((group) => group.name === name)) return { error: "duplicate" };
+			const group = {
+				id: newWatchlistGroupId(),
+				name,
+				createdAt: Date.now()
+			};
+			groups = [...groups, group];
+			return { group };
+		},
+		async rename(id, name) {
+			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" };
+			groups = groups.map((group) => group.id === id ? {
+				...group,
+				name
+			} : group);
+			return { group: {
+				...existing,
+				name
+			} };
+		},
+		async remove(id) {
+			const next = groups.filter((group) => group.id !== id);
+			if (next.length === groups.length) return false;
+			groups = next;
+			return true;
 		}
 	};
 }
@@ -48,4 +147,4 @@ function createMemorySelectionStore(initial = { instrument: null }) {
 	};
 }
 //#endregion
-export { WATCHLIST_SEEDS, createMemorySelectionStore, createMemoryWatchlistStore, effectiveWatchlistRows, watchlistRowSource };
+export { WATCHLIST_SEEDS, createMemorySelectionStore, createMemoryWatchlistGroupsStore, createMemoryWatchlistStore, effectiveWatchlistRows, newWatchlistGroupId, normalizeWatchlistRow, watchlistRowSource };

package/lib/plugin.d.ts

@@ -1,14 +1,16 @@
-import { SelectionStore, WatchlistStore, createMemorySelectionStore, createMemoryWatchlistStore } from "./index.js";
-import { createFileSelectionStore, createFileWatchlistStore } from "./file-store.js";
-import { Context } from "@deepseek-ai/cordis";
+import { SelectionStore, WatchlistGroupsStore, WatchlistStore, createMemorySelectionStore, createMemoryWatchlistGroupsStore, createMemoryWatchlistStore } from "./index.js";
+import { createFileSelectionStore, createFileWatchlistGroupsStore, createFileWatchlistStore } from "./file-store.js";
+import { Context, Service } 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[];
-/** 默认存储路径。 */
+/** 默认存储路径：$DSH_HOME/watchlists.json（缺省 ~/.dsh）。 */
 declare function defaultWatchlistStorePath(): string;
 declare function defaultSelectionStorePath(): string;
+/** 默认分组注册表路径：$DSH_HOME/watchlist-groups.json（issue #82）。 */
+declare function defaultWatchlistGroupsStorePath(): string;
 /** tradingEvents 的最小发布面（鸭式；总线缺席时静默降级）。 */
 interface TradingEventsPublisher {
   emit(store: 'watchlists' | 'selection'): void;
@@ -16,6 +18,8 @@ interface TradingEventsPublisher {
 interface WatchlistToolDeps {
   watchlists: WatchlistStore;
   selection: SelectionStore;
+  /** 分组注册表（issue #86 / G5）：缺席时分组工具明确报错，不静默降级。 */
+  groups?: WatchlistGroupsStore;
   onWatchlistsChanged?: () => void;
   onSelectionChanged?: () => void;
 }
@@ -23,12 +27,37 @@ declare function createWatchlistListTool(deps: WatchlistToolDeps): import("@deep
 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;
+declare function createWatchlistGroupCreateTool(deps: WatchlistToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+declare function createWatchlistGroupRenameTool(deps: WatchlistToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+declare function createWatchlistGroupDeleteTool(deps: WatchlistToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+declare function createWatchlistGroupAssignTool(deps: WatchlistToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
 interface WatchlistPluginDeps {
   watchlists: WatchlistStore;
   selection: SelectionStore;
+  groups: WatchlistGroupsStore;
 }
 declare function registerWatchlistTools(ctx: Context, deps: WatchlistPluginDeps): void;
+/** SDK 服务键：自选/选中 store 单实例（桥与工具共享同一缓存；2026-09-08 审查 H1 收口）。 */
+declare const TRADING_WATCHLIST_KEY = "tradingWatchlist";
+/**
+ * 自选 + 选中 store 服务（单实例共享点，strategies/indicators 同款 provide 模式）。
+ *
+ * 2026-09-08 审查实证：桥（client-ui-trading node 半）此前自建第二个 file store，
+ * 与工具侧实例各持整表缓存、各自整表回写 → 两侧写互相覆盖（agent `watchlist_add`
+ * 抹掉 GUI 刚写入的行与全部分组归属）。服务缺席（老部署）时桥仍回退自建实例。
+ */
+declare class WatchlistStoreService extends Service {
+  readonly store: WatchlistStore;
+  readonly selection: SelectionStore;
+  /** 分组注册表单实例（issue #86 / G5）：工具与桥共用，杜绝双 store 互踩。 */
+  readonly groups: WatchlistGroupsStore;
+  constructor(ctx: Context, deps: {
+    watchlists: WatchlistStore;
+    selection: SelectionStore;
+    groups: WatchlistGroupsStore;
+  }, serviceName?: string);
+}
 /** 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 };
+export { TRADING_WATCHLIST_KEY, TradingEventsPublisher, WatchlistPluginDeps, WatchlistStoreService, WatchlistToolDeps, apply, createFileSelectionStore, createFileWatchlistGroupsStore, createFileWatchlistStore, createMemorySelectionStore, createMemoryWatchlistGroupsStore, createMemoryWatchlistStore, createWatchlistAddTool, createWatchlistGroupAssignTool, createWatchlistGroupCreateTool, createWatchlistGroupDeleteTool, createWatchlistGroupRenameTool, createWatchlistListTool, createWatchlistRemoveTool, createWatchlistSelectTool, defaultSelectionStorePath, defaultWatchlistGroupsStorePath, defaultWatchlistStorePath, inject, name, registerWatchlistTools };

package/lib/plugin.js

@@ -1,20 +1,25 @@
 import { WATCHLIST_SEEDS, effectiveWatchlistRows, watchlistRowSource } from "./seeds.js";
-import { createMemorySelectionStore, createMemoryWatchlistStore } from "./index.js";
-import { createFileSelectionStore, createFileWatchlistStore } from "./file-store.js";
+import { createMemorySelectionStore, createMemoryWatchlistGroupsStore, createMemoryWatchlistStore } from "./index.js";
+import { createFileSelectionStore, createFileWatchlistGroupsStore, createFileWatchlistStore } from "./file-store.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-watchlist";
 /** 本插件不硬依赖任何服务；tools 经 ctx.inject 声明。 */
 const inject = [];
-/** 默认存储路径。 */
+/** 默认存储路径：$DSH_HOME/watchlists.json（缺省 ~/.dsh）。 */
 function defaultWatchlistStorePath() {
-	return path.join(os.homedir(), ".dsh", "watchlists.json");
+	return path.join(dshHomeDir(), "watchlists.json");
 }
 function defaultSelectionStorePath() {
-	return path.join(os.homedir(), ".dsh", "selection.json");
+	return path.join(dshHomeDir(), "selection.json");
+}
+/** 默认分组注册表路径：$DSH_HOME/watchlist-groups.json（issue #82）。 */
+function defaultWatchlistGroupsStorePath() {
+	return path.join(dshHomeDir(), "watchlist-groups.json");
 }
 function eventsOf(ctx) {
 	return ctx.get?.("tradingEvents", false);
@@ -27,13 +32,36 @@ function parseInstrumentArgs(raw) {
 	return {
 		market,
 		symbol,
-		name
+		...name !== void 0 ? { name } : {}
 	};
 }
+/** 分组注册表取用（缺席 = 老部署，写工具必须响亮失败而不是假装成功）。 */
+function requireGroups(deps, tool) {
+	if (deps.groups === void 0) throw new Error(`${tool}: watchlist group store is not mounted — upgrade the dsh-trading profile so @dshtrading/watchlist/plugin provides it`);
+	return deps.groups;
+}
+/** 分组名校验（与桥 parseGroupNameBody 同口径：trim 非空、≤24 字符）。 */
+function parseGroupName(raw, tool) {
+	const name = typeof raw === "string" ? raw.trim() : "";
+	if (!name) throw new Error(`${tool}: name is required (non-empty string)`);
+	if (name.length > 24) throw new Error(`${tool}: group name too long (24 chars max, got ${name.length})`);
+	return name;
+}
+function parseGroupId(raw, tool) {
+	const id = typeof raw === "string" ? raw.trim() : "";
+	if (!id) throw new Error(`${tool}: id is required (a group id from watchlist_list / watchlist_group_create)`);
+	return id;
+}
+/** 全表统计某分组的成员行数（合并视图口径 = 用户实际看到的行）。 */
+function countGroupMembers(map, groupId) {
+	let count = 0;
+	for (const market of Object.keys(map)) for (const row of effectiveWatchlistRows(map, market)) if (Array.isArray(row.groups) && row.groups.includes(groupId)) count += 1;
+	return count;
+}
 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.",
+		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.",
 		parameters: {},
 		output: {
 			schema: { type: "string" },
@@ -54,12 +82,21 @@ function createWatchlistListTool(deps) {
 				sources[market] = watchlistRowSource(map, market);
 				total += rows.length;
 			}
+			const groups = (deps.groups === void 0 ? [] : await deps.groups.list()).map((group) => ({
+				id: group.id,
+				name: group.name,
+				createdAt: group.createdAt,
+				members: countGroupMembers(watchlists, group.id)
+			}));
+			const selection = (await deps.selection.get()).instrument;
 			return JSON.stringify({
 				ok: true,
 				total,
 				markets,
 				sources,
-				watchlists
+				watchlists,
+				groups,
+				selection
 			});
 		}
 	});
@@ -178,6 +215,234 @@ 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.",
+		parameters: { name: {
+			type: "string",
+			required: true,
+			description: "Group display name (non-empty, 24 chars max, unique among groups)"
+		} },
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const groups = requireGroups(deps, "watchlist_group_create");
+			const name = parseGroupName((raw ?? {}).name, "watchlist_group_create");
+			const result = await groups.create(name);
+			if (result.error === "duplicate") return JSON.stringify({
+				ok: false,
+				code: "duplicate",
+				note: `A group named ${JSON.stringify(name)} already exists — call watchlist_list to see the existing groups and reuse that id.`
+			});
+			if (result.group === void 0) return JSON.stringify({
+				ok: false,
+				code: "unavailable",
+				note: "The watchlist group store returned no group."
+			});
+			deps.onWatchlistsChanged?.();
+			return JSON.stringify({
+				ok: true,
+				id: result.group.id,
+				name: result.group.name,
+				note: `Created group ${JSON.stringify(result.group.name)} (id ${result.group.id}, 0 members). Assign instruments with watchlist_group_assign.`
+			});
+		}
+	});
+}
+function createWatchlistGroupRenameTool(deps) {
+	return defineTool({
+		name: "watchlist_group_rename",
+		description: "Rename a custom watchlist group by id (membership is untouched — only the display name changes). Refused when the id is unknown or the new name is already used by another group. Call watchlist_list first to get the id and report the old → new name back to the user.",
+		parameters: {
+			id: {
+				type: "string",
+				required: true,
+				description: "Group id from watchlist_list / watchlist_group_create"
+			},
+			name: {
+				type: "string",
+				required: true,
+				description: "New group display name (non-empty, 24 chars max, unique among groups)"
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const groups = requireGroups(deps, "watchlist_group_rename");
+			const args = raw ?? {};
+			const id = parseGroupId(args.id, "watchlist_group_rename");
+			const name = parseGroupName(args.name, "watchlist_group_rename");
+			const before = (await groups.list()).find((group) => group.id === id);
+			const result = await groups.rename(id, name);
+			if (result.error === "not-found") return JSON.stringify({
+				ok: false,
+				code: "not-found",
+				note: `No watchlist group with id ${JSON.stringify(id)} — call watchlist_list for the current ids.`
+			});
+			if (result.error === "duplicate") return JSON.stringify({
+				ok: false,
+				code: "duplicate",
+				note: `Another group is already named ${JSON.stringify(name)} — pick a different name.`
+			});
+			if (result.group === void 0) return JSON.stringify({
+				ok: false,
+				code: "unavailable",
+				note: "The watchlist group store returned no group."
+			});
+			deps.onWatchlistsChanged?.();
+			return JSON.stringify({
+				ok: true,
+				id: result.group.id,
+				from: before?.name ?? null,
+				to: result.group.name,
+				note: `Renamed group ${JSON.stringify(before?.name ?? id)} → ${JSON.stringify(result.group.name)} (membership unchanged).`
+			});
+		}
+	});
+}
+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.",
+		parameters: { id: {
+			type: "string",
+			required: true,
+			description: "Group id from watchlist_list (unknown id is refused)"
+		} },
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const groups = requireGroups(deps, "watchlist_group_delete");
+			const id = parseGroupId((raw ?? {}).id, "watchlist_group_delete");
+			const target = (await groups.list()).find((group) => group.id === id);
+			if (target === void 0) return JSON.stringify({
+				ok: false,
+				code: "not-found",
+				note: `No watchlist group with id ${JSON.stringify(id)} — call watchlist_list for the current ids.`
+			});
+			const membersCleared = await deps.watchlists.stripGroup(id);
+			const removed = await groups.remove(id);
+			if (removed || membersCleared > 0) deps.onWatchlistsChanged?.();
+			return JSON.stringify({
+				ok: true,
+				id,
+				name: target.name,
+				removed,
+				membersCleared,
+				note: removed ? `Deleted group ${JSON.stringify(target.name)} (${membersCleared} row(s) lost this membership). The watchlist rows themselves are untouched.` : `Group ${JSON.stringify(target.name)} was already gone; ${membersCleared} stale membership(s) cleaned.`
+			});
+		}
+	});
+}
+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.",
+		parameters: {
+			id: {
+				type: "string",
+				required: true,
+				description: "Group id from watchlist_list / watchlist_group_create"
+			},
+			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"
+			},
+			member: {
+				type: "boolean",
+				required: true,
+				description: "true = add the instrument to the group; false = remove it from the group"
+			},
+			name: {
+				type: "string",
+				description: "Optional display name used only when the row must be materialized, e.g. 贵州茅台"
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const groups = requireGroups(deps, "watchlist_group_assign");
+			const args = raw ?? {};
+			const id = parseGroupId(args.id, "watchlist_group_assign");
+			const { market, symbol } = parseInstrumentArgs(args);
+			const displayName = typeof args.name === "string" && args.name.trim() ? args.name.trim() : void 0;
+			if (typeof args.member !== "boolean") throw new Error("watchlist_group_assign: member is required (true = add to the group, false = remove from it)");
+			const member = args.member;
+			const target = (await groups.list()).find((group) => group.id === id);
+			if (target === void 0) return JSON.stringify({
+				ok: false,
+				code: "not-found",
+				note: `No watchlist group with id ${JSON.stringify(id)} — call watchlist_list for the current ids.`
+			});
+			let materialized = false;
+			if (member) {
+				const map = await deps.watchlists.list();
+				const rows = map[market];
+				if (!Array.isArray(rows)) {
+					const baseline = (WATCHLIST_SEEDS[market] ?? []).map((row) => ({
+						market: row.market,
+						symbol: row.symbol,
+						...row.name !== void 0 ? { name: row.name } : {}
+					}));
+					if (!baseline.some((row) => row.symbol === symbol)) baseline.push({
+						market,
+						symbol,
+						...displayName !== void 0 ? { name: displayName } : {}
+					});
+					await deps.watchlists.save({
+						...map,
+						[market]: baseline
+					});
+					materialized = true;
+				} else if (!rows.some((row) => row.symbol === symbol)) materialized = await deps.watchlists.add(market, {
+					market,
+					symbol,
+					...displayName !== void 0 ? { name: displayName } : {}
+				});
+			}
+			const changed = await deps.watchlists.assignGroup(market, symbol, id, member);
+			if (changed || materialized) deps.onWatchlistsChanged?.();
+			return JSON.stringify({
+				ok: true,
+				id,
+				group: target.name,
+				market,
+				symbol,
+				assigned: member ? changed : false,
+				removed: member ? false : changed,
+				materialized,
+				note: member ? changed ? `Added ${symbol} (${market}) to group ${JSON.stringify(target.name)}${materialized ? " (row materialized from the market seed baseline)" : ""}.` : `${symbol} (${market}) is already in group ${JSON.stringify(target.name)} (nothing changed).` : changed ? `Removed ${symbol} (${market}) from group ${JSON.stringify(target.name)}; the watchlist row itself is untouched.` : `${symbol} (${market}) was not in group ${JSON.stringify(target.name)} (nothing changed).`
+			});
+		}
+	});
+}
 function registerWatchlistTools(ctx, deps) {
 	ctx.inject(["tools"], (toolCtx) => {
 		const tools = toolCtx.tools;
@@ -194,14 +459,48 @@ function registerWatchlistTools(ctx, deps) {
 		shared.register(createWatchlistAddTool(hookDeps));
 		shared.register(createWatchlistRemoveTool(hookDeps));
 		shared.register(createWatchlistSelectTool(hookDeps));
+		shared.register(createWatchlistGroupCreateTool(hookDeps));
+		shared.register(createWatchlistGroupRenameTool(hookDeps));
+		shared.register(createWatchlistGroupDeleteTool(hookDeps));
+		shared.register(createWatchlistGroupAssignTool(hookDeps));
 	});
 }
+/** SDK 服务键：自选/选中 store 单实例（桥与工具共享同一缓存；2026-09-08 审查 H1 收口）。 */
+const TRADING_WATCHLIST_KEY = "tradingWatchlist";
+/**
+* 自选 + 选中 store 服务（单实例共享点，strategies/indicators 同款 provide 模式）。
+*
+* 2026-09-08 审查实证：桥（client-ui-trading node 半）此前自建第二个 file store，
+* 与工具侧实例各持整表缓存、各自整表回写 → 两侧写互相覆盖（agent `watchlist_add`
+* 抹掉 GUI 刚写入的行与全部分组归属）。服务缺席（老部署）时桥仍回退自建实例。
+*/
+var WatchlistStoreService = class extends Service {
+	store;
+	selection;
+	/** 分组注册表单实例（issue #86 / G5）：工具与桥共用，杜绝双 store 互踩。 */
+	groups;
+	constructor(ctx, deps, serviceName = TRADING_WATCHLIST_KEY) {
+		super(ctx, serviceName);
+		this.store = deps.watchlists;
+		this.selection = deps.selection;
+		this.groups = deps.groups;
+	}
+};
 /** Host plugin body：file store provide + 4 工具注册（host 平面，全会话可见）。 */
 function apply(ctx) {
+	const watchlists = createFileWatchlistStore(defaultWatchlistStorePath());
+	const selection = createFileSelectionStore(defaultSelectionStorePath());
+	const groups = createFileWatchlistGroupsStore(defaultWatchlistGroupsStorePath());
+	new WatchlistStoreService(ctx, {
+		watchlists,
+		selection,
+		groups
+	});
 	registerWatchlistTools(ctx, {
-		watchlists: createFileWatchlistStore(defaultWatchlistStorePath()),
-		selection: createFileSelectionStore(defaultSelectionStorePath())
+		watchlists,
+		selection,
+		groups
 	});
 }
 //#endregion
-export { apply, createFileSelectionStore, createFileWatchlistStore, createMemorySelectionStore, createMemoryWatchlistStore, createWatchlistAddTool, createWatchlistListTool, createWatchlistRemoveTool, createWatchlistSelectTool, defaultSelectionStorePath, defaultWatchlistStorePath, inject, name, registerWatchlistTools };
+export { TRADING_WATCHLIST_KEY, WatchlistStoreService, apply, createFileSelectionStore, createFileWatchlistGroupsStore, createFileWatchlistStore, createMemorySelectionStore, createMemoryWatchlistGroupsStore, createMemoryWatchlistStore, createWatchlistAddTool, createWatchlistGroupAssignTool, createWatchlistGroupCreateTool, createWatchlistGroupDeleteTool, createWatchlistGroupRenameTool, createWatchlistListTool, createWatchlistRemoveTool, createWatchlistSelectTool, defaultSelectionStorePath, defaultWatchlistGroupsStorePath, defaultWatchlistStorePath, inject, name, registerWatchlistTools };

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.1.5",
+  "version": "0.2.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -20,7 +20,9 @@
     "lib"
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
-  "dependencies": {},
+  "dependencies": {
+    "@dshtrading/dsh-home": "^0.2.0"
+  },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.0",
     "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1"