dsh-session-tg-notify 0.1.0

package/src/index.js

@@ -0,0 +1,392 @@
+/**
+ * dsh-session-tg-notify — 宿主（node）半。
+ *
+ * 职责：
+ *   1. 订阅会话事件，归一化成「一次通知」（events.js）；
+ *   2. 依据浏览器前后台状态（presence.js）把通知投到两个通道：
+ *        - 桌面：前台 → 页面内 toast；后台 → macOS 系统通知（点击天然切回该标签页）；
+ *                离线 → 无处可发
+ *        - Telegram：前台 → 永不；后台 → 需「订阅 TG 且开了后台同时推送」；离线 → 订阅了即发
+ *   3. 暴露设置页所需的 HTTP API 与 SSE 通道（不改 DSH 核心）。
+ *
+ * 两个概念必须分清（这是本插件唯一需要理解的设计）：
+ *   - **订阅**：设置页每行的「桌面」「TG」勾选框，表示"这个事件我愿意通过该通道收到"。
+ *   - **通道**：全局开关与凭据（桌面通知权限 / Telegram 启用+Token+Chat ID）。
+ *   只有「已订阅」且「通道就绪」且「当前网页状态该通道适用」三者同时成立才会发出。
+ *   订阅了但通道没起来时，宿主会打印一条明确的 warning，而不是静默丢弃。
+ *
+ * 子代理会话不通知（events.js 的 isMainSession）。
+ */
+import { resolveConfig, defaultConfigPath, applyPatch, redactConfig, saveConfig, displayPath, EVENT_EMOJI, EVENT_LABELS } from './config.js';
+import {
+	createTurnTracker,
+	createDedupe,
+	classifyApproval,
+	classifyQuestion,
+	classifyTurnEnd,
+	classifyGoalChange,
+	classifyAgentError,
+	sessionLabel,
+	oneLine
+} from './events.js';
+import { createPresenceHub } from './presence.js';
+import { readScreenLocked } from './screenlock.js';
+import { sendTelegram, getTelegramMe, getTelegramChats, getTelegramChat } from './telegram.js';
+
+export const name = 'session-notify';
+export const VERSION = '0.1.0';
+/** 只消费事件与 webServer，不依赖其他服务。 */
+export const inject = [];
+
+/** 设置页需要知道的事件元数据。 */
+const EVENT_META = Object.entries(EVENT_LABELS).map(([kind, label]) => ({ kind, label, emoji: EVENT_EMOJI[kind] }));
+
+export function apply(ctx, cordisConfig = {}, options = {}) {
+	const configPath = options.configPath ?? defaultConfigPath();
+	let { config, warning } = resolveConfig(cordisConfig, configPath);
+	if (warning) console.warn(warning);
+
+	const hub = createPresenceHub({ ttlMs: config.presenceTtlMs });
+	const turns = createTurnTracker();
+	const dedupe = createDedupe();
+	if (typeof ctx.effect === 'function') ctx.effect(() => () => hub.dispose(), 'session-notify presence hub');
+
+	const send = options.sendTelegram ?? sendTelegram;
+
+	// ------------------------------------------------------------ 锁屏探测
+	/**
+	 * 最近一次锁屏探测结果。锁屏只在「后台 + 订阅了 TG + 开了锁屏推送」这一种
+	 * 组合下影响路由，所以平时不轮询、按需探测；设置页读取时也会强制探一次，
+	 * 让面板上的状态行始终是实时的。
+	 */
+	const lockProbe = options.readScreenLocked ?? readScreenLocked;
+	let lastScreen = { supported: null, locked: false, signal: 'unknown', at: 0 };
+
+	const probeScreenLocked = async () => {
+		const result = await lockProbe();
+		lastScreen = { ...result, at: Date.now() };
+		return lastScreen;
+	};
+
+	/**
+	 * 诊断轮询：只在有页面连接时运行，且**只在锁屏状态发生变化时**打日志。
+	 *
+	 * 存在的理由很具体：我这个 agent 无法自己去锁你的屏幕，所以「锁屏分支到
+	 * 底能不能识别」只能靠你锁一次、再回来查日志验证。日志里同时带上信号来源，
+	 * 便于区分是 ioreg 命中还是屏保兜底。
+	 */
+	const lockPollMs = Number.isSafeInteger(options.lockPollMs) ? options.lockPollMs : 20000;
+	if (lockPollMs > 0 && typeof ctx.effect === 'function') {
+		ctx.effect(() => {
+			let previous = null;
+			const timer = setInterval(() => {
+				if (hub.size === 0) return; // 页面没开时锁屏与否不影响路由
+				void probeScreenLocked().then((next) => {
+					if (previous !== null && next.locked !== previous) {
+						console.log(`[session-notify] 锁屏状态变化: ${next.locked ? '已锁定' : '已解锁'}（信号：${next.signal}）`);
+					}
+					previous = next.locked;
+				});
+			}, lockPollMs);
+			if (typeof timer.unref === 'function') timer.unref();
+			return () => clearInterval(timer);
+		}, 'session-notify lock poll');
+	}
+
+	/** 持久化修正后的配置（含运行时开关），失败只记日志、不影响通知。 */
+	const persist = (next) => {
+		config = next;
+		try {
+			saveConfig(configPath, config);
+			return { ok: true };
+		} catch (error) {
+			const message = error?.message ?? String(error);
+			console.warn(`[session-notify] 配置写入失败: ${message}`);
+			return { ok: false, error: message };
+		}
+	};
+
+	/**
+	 * Telegram 通道未就绪的原因（就绪返回 null）。
+	 * 「行内勾选 TG」表达的是**订阅**，通道是否真的能用由启用开关 + 凭据决定。
+	 */
+	const telegramChannelIssue = () => {
+		if (config.telegram.enabled !== true) return '未启用 Telegram 通道';
+		if (config.telegram.botToken.trim().length === 0) return '缺少 Bot Token';
+		if (config.telegram.chatId.trim().length === 0) return '缺少 Chat ID';
+		return null;
+	};
+
+	/**
+	 * 订阅（行内 TG 勾选）× 网页状态 → 是否发送 Telegram。
+	 *
+	 *   前台 → 永不（页面可见即视为已送达，不再打扰手机）
+	 *   后台 → 仅当开了「网页后台且锁屏时推送」**且当前确实锁屏**
+	 *   离线 → 直接发（页面都关了，这正是 Telegram 存在的意义）
+	 *
+	 * 后台这一档刻意要求「锁屏」而非「失焦」：切到别的应用也会让页面失焦，
+	 * 那时人还在电脑前，推手机是纯打扰。锁屏才是「人走了」的可靠信号。
+	 *
+	 * 未订阅的行在三种状态下都不会发。通道本身是否启动由 telegramChannelIssue 判定。
+	 */
+	const shouldTelegram = (eventConfig, state, screenLocked) => {
+		if (eventConfig.telegram !== true) return false;
+		if (state === 'foreground') return false;
+		if (state === 'background') return config.telegram.notifyWhenLocked === true && screenLocked === true;
+		return true;
+	};
+
+	/** 路由并投递一次通知。 */
+	const deliver = async (notification) => {
+		if (!notification) return;
+		const eventConfig = config.events[notification.kind];
+		if (!config.enabled || !eventConfig) return;
+		if (!dedupe.admit(notification.sessionId, notification.dedupeKey)) return;
+		// 两个通道都没勾 → 用户明确不想被这个事件打扰。
+		if (!eventConfig.desktop && !eventConfig.telegram) return;
+
+		const presence = hub.snapshot();
+		// 只有「后台 + 开了锁屏推送」这一种组合需要真的去问系统锁没锁，
+		// 其余情况不付这次子进程开销。
+		const needsLockProbe = presence.state === 'background' && eventConfig.telegram === true && config.telegram.notifyWhenLocked === true;
+		const screen = needsLockProbe ? await probeScreenLocked() : null;
+
+		const payload = {
+			kind: notification.kind,
+			title: notification.title,
+			body: notification.body,
+			emoji: EVENT_EMOJI[notification.kind] ?? '',
+			sessionLabel: notification.sessionLabel ?? '',
+			// 供页面内 toast / 系统通知点击后直达对应会话
+			sessionId: notification.sessionId ?? null,
+			at: Date.now()
+		};
+
+		if (eventConfig.desktop && config.desktop.enabled && presence.state !== 'offline') {
+			const frame = presence.state === 'foreground' ? 'toast' : 'webnotify';
+			hub.sendTo(presence.targetClientId, frame, {
+				...payload,
+				tone: config.desktop.sound ? config.desktop.tone : 'none'
+			});
+		}
+
+		if (shouldTelegram(eventConfig, presence.state, screen?.locked === true)) {
+			const issue = telegramChannelIssue();
+			if (issue !== null) {
+				// 订阅了但通道没起来 —— 这是最容易让人困惑的情况，必须显式提示。
+				console.warn(`[session-notify] 「${EVENT_LABELS[notification.kind] ?? notification.kind}」已订阅 Telegram，但通道未就绪（${issue}），本条已跳过`);
+			} else {
+				const result = await send(config.telegram, payload);
+				if (!result.ok) console.warn(`[session-notify] Telegram 推送失败: ${result.error}`);
+			}
+		}
+
+		const lockText = screen === null ? '' : ` 锁屏=${screen.locked ? '是' : '否'}(${screen.signal})`;
+		console.log(`[session-notify] ${EVENT_EMOJI[notification.kind] ?? ''} ${notification.kind} (${presence.state}${lockText}) ${oneLine(notification.body, 80)}`);
+	};
+
+	// ---------------------------------------------------------------- 事件订阅
+	const turns2 = turns;
+
+	ctx.on('session/event', (session, event) => {
+		const type = event?.type;
+		// tool/call 必须先喂给 turn tracker，否则「最终文本之后没有新 tool/call」判定不完整。
+		if (type === 'tool/call') turns2.onToolCall(session, event);
+
+		const approval = classifyApproval(session, event);
+		if (approval) {
+			void deliver({ ...approval, sessionLabel: sessionLabel(session), emoji: EVENT_EMOJI.approval });
+			return;
+		}
+		const question = classifyQuestion(session, event);
+		if (question) {
+			void deliver({ ...question, sessionLabel: sessionLabel(session), emoji: EVENT_EMOJI.question });
+			return;
+		}
+
+		if (type === 'turn/start') {
+			turns2.onTurnStart(session, event);
+			return;
+		}
+		if (type === 'user/message') {
+			turns2.onUserMessage(session, event);
+			return;
+		}
+		if (type === 'assistant/message') {
+			turns2.onAssistantMessage(session, event);
+			return;
+		}
+		if (type === 'turn/end') {
+			const complete = classifyTurnEnd(session, turns2.onTurnEnd(session, event));
+			if (!complete) return;
+			const durationMs = complete.detail?.durationMs;
+			// 时长过滤：短于 minDuration 的 turn 不打扰（未知时长按通过处理）。
+			if (typeof durationMs === 'number' && durationMs < config.minDuration * 1000) return;
+			void deliver({ ...complete, sessionLabel: sessionLabel(session), emoji: EVENT_EMOJI.complete });
+		}
+	});
+
+	ctx.on('goal/changed', ({ change }) => {
+		const block = classifyGoalChange(change);
+		if (block) void deliver({ ...block, sessionLabel: '', emoji: EVENT_EMOJI.block });
+	});
+
+	ctx.on('agent/error', (payload) => {
+		const error = classifyAgentError(payload);
+		if (error) void deliver({ ...error, sessionLabel: '', emoji: EVENT_EMOJI.error });
+	});
+
+	ctx.on('session/disposed', (session) => {
+		turns2.onSessionDisposed(session);
+		dedupe.forget(session?.id);
+	});
+
+	// ------------------------------------------------------------ HTTP + SSE
+	ctx.inject(['webServer'], (webCtx) => {
+		const readBody = async (req) => {
+			const chunks = [];
+			for await (const chunk of req) chunks.push(chunk);
+			return Buffer.concat(chunks).toString('utf8');
+		};
+		const json = (res, status, body) => {
+			res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+			res.end(JSON.stringify(body));
+		};
+		const statePayload = () => ({
+			config: redactConfig(config),
+			presence: hub.snapshot(),
+			// 面板的状态行要显示「锁屏推送」是否真的生效，所以这里带上实时锁屏状态
+			screen: lastScreen,
+			events: EVENT_META,
+			// configPath 给 curl/运维用；configPathDisplay 是收敛成 ~/... 的版本，
+			// 界面只允许用后者，避免把用户名渲染进 UI。
+			configPath,
+			configPathDisplay: displayPath(configPath),
+			version: VERSION
+		});
+
+		webCtx.webServer.register({
+			kind: 'prefix',
+			path: '/session-notify',
+			handler: async (req, res) => {
+				const url = new URL(req.url ?? '/', 'http://session-notify');
+				const endpoint = url.pathname.replace(/^\/session-notify\/?/, '') || 'state';
+				try {
+					// 跨站防护：本插件的路由不经 DSH 的 token 校验，因此显式拒绝
+					// Origin 与 Host 不匹配的请求，避免任意网页在浏览器里替你改配置
+					// 或发测试推送。注意这挡不住同网段的直接 curl —— 见 README 的安全说明。
+					const origin = req.headers?.origin;
+					const host = req.headers?.host;
+					if (typeof origin === 'string' && origin.length > 0) {
+						let originHost = null;
+						try {
+							originHost = new URL(origin).host;
+						} catch {
+							originHost = null;
+						}
+						if (originHost === null || originHost !== host) {
+							return json(res, 403, { ok: false, error: 'cross-origin request rejected' });
+						}
+					}
+
+					// SSE：同时是存活信号与通知下发通道。
+					if (endpoint === 'events') {
+						if (req.method !== 'GET') return json(res, 405, { ok: false, error: 'use GET' });
+						const clientId = url.searchParams.get('clientId') || `anon-${Date.now()}`;
+						if (!hub.attach(clientId, res, { version: VERSION })) {
+							return json(res, 503, { ok: false, error: 'too many connections' });
+						}
+						return;
+					}
+
+					if (endpoint === 'state' && req.method === 'GET') {
+						// 面板打开时强制探一次锁屏，状态行才不会显示过期值
+						await probeScreenLocked();
+						return json(res, 200, { ok: true, value: statePayload() });
+					}
+
+					if (req.method !== 'POST') return json(res, 405, { ok: false, error: 'use POST' });
+
+					let body = {};
+					try {
+						body = JSON.parse((await readBody(req)) || '{}');
+					} catch {
+						return json(res, 400, { ok: false, error: 'body must be JSON' });
+					}
+
+					// 浏览器上报可见性/焦点（心跳）。
+					if (endpoint === 'presence') {
+						const clientId = typeof body.clientId === 'string' ? body.clientId : '';
+						if (clientId.length === 0) return json(res, 400, { ok: false, error: 'clientId required' });
+						hub.update(clientId, body);
+						return json(res, 200, { ok: true, value: hub.snapshot() });
+					}
+
+					// 设置页保存配置（局部补丁）。
+					if (endpoint === 'config') {
+						const next = applyPatch(config, body);
+						const written = persist(next);
+						return json(res, written.ok ? 200 : 500, {
+							ok: written.ok,
+							error: written.error,
+							value: statePayload()
+						});
+					}
+
+					// 逐事件测试推送。
+					if (endpoint === 'test') {
+						const kind = typeof body.kind === 'string' ? body.kind : '';
+						const channel = body.channel === 'telegram' ? 'telegram' : 'desktop';
+						if (!EVENT_LABELS[kind]) return json(res, 400, { ok: false, error: `unknown event kind: ${kind}` });
+						const sample = {
+							kind,
+							title: EVENT_LABELS[kind],
+							body: `这是一条来自 dsh-session-tg-notify 的测试通知（${EVENT_LABELS[kind]}）`,
+							emoji: EVENT_EMOJI[kind] ?? '',
+							sessionLabel: 'settings-test',
+							at: Date.now()
+						};
+						if (channel === 'telegram') {
+							const issue = telegramChannelIssue();
+							if (issue !== null) return json(res, 400, { ok: false, error: `Telegram 通道未就绪：${issue}` });
+							const result = await send(config.telegram, sample);
+							return json(res, result.ok ? 200 : 502, { ok: result.ok, error: result.error });
+						}
+						// 桌面测试：强制走系统通知，这样能验证 OS 通知 + 声音 + 点击切回标签页。
+						const clientId = typeof body.clientId === 'string' ? body.clientId : '';
+						const delivered = clientId
+							? hub.sendTo(clientId, 'webnotify', { ...sample, tone: config.desktop.sound ? config.desktop.tone : 'none' })
+							: (hub.broadcast('webnotify', { ...sample, tone: config.desktop.sound ? config.desktop.tone : 'none' }), true);
+						return json(res, 200, { ok: true, value: { delivered } });
+					}
+
+					// 校验 Telegram 凭据：token 走 getMe，有 Chat ID 时再走 getChat，
+					// 这样「测试连接」验证的是整条链路，而不只是 token 有效。
+					if (endpoint === 'telegram-check') {
+						const probe = applyPatch(config, { telegram: body }).telegram;
+						const me = await getTelegramMe(probe);
+						if (!me.ok) return json(res, 502, me);
+						const chatId = probe.chatId;
+						if (typeof chatId !== 'string' || chatId.trim().length === 0) {
+							return json(res, 200, { ...me, chatOk: false, chatError: '未配置 Chat ID —— bot 无法主动发起会话，请先给 bot 发一条消息再点「获取 Chat ID」' });
+						}
+						const chat = await getTelegramChat(probe, chatId);
+						return json(res, chat.ok ? 200 : 502, { ...me, chatOk: chat.ok, chatError: chat.ok ? null : chat.error, chat: chat.chat ?? null });
+					}
+
+					// 从 bot 的最近更新里发现可用 chat（获取 Chat ID 的正规途径）。
+					if (endpoint === 'telegram-chats') {
+						const probe = applyPatch(config, { telegram: body }).telegram;
+						const result = await getTelegramChats(probe);
+						return json(res, result.ok ? 200 : 502, result);
+					}
+
+					return json(res, 404, { ok: false, error: `unknown endpoint: ${endpoint}` });
+				} catch (error) {
+					return json(res, 500, { ok: false, error: error?.message ?? String(error) });
+				}
+			}
+		});
+		console.log(`[session-notify] v${VERSION} 已加载（配置：${configPath}）`);
+	});
+}

package/src/presence.js

@@ -0,0 +1,177 @@
+/**
+ * dsh-session-tg-notify — 在线状态 + SSE 推送 hub。
+ *
+ * 关键设计：**SSE 长连接本身就是存活信号**。浏览器端与后端之间只有一条
+ * 通道（`GET /session-notify/events`），它同时承担：
+ *   1. 存活判定 —— 连接存在即页面开着；连接关闭（含页面关闭、标签被回收）
+ *      即视为离线，后端据此把通知改走 Telegram。
+ *   2. 前后台判定 —— 客户端通过 `POST /session-notify/presence` 上报
+ *      `{ visibility, focused }`，二者可随窗口焦点变化即时更新。
+ *   3. 通知下发 —— 后端按判定结果推 `toast` / `webnotify` 帧。
+ *
+ * 三态（在线只看连接，心跳只管焦点）：
+ *   - foreground：存在连接，且**新鲜**的焦点上报是 visible + focused
+ *   - background：存在连接但没有新鲜的前台信息
+ *   - offline   ：**没有任何连接**（页面确实关了）
+ *
+ * 曾经把「心跳过期」也算成 offline，结果被 Chrome 的后台标签页定时器节流误伤：
+ * 页面开着、只是被切走久了，就被判成离线并错误地改走 Telegram。
+ *
+ * 多标签页：只要**任一**标签页处于前台就算 foreground（用户在看着 DSH）；
+ * 通知只发给“最合适的那一个”标签页（前台优先，否则最近上报的），避免多标签
+ * 重复弹窗。
+ */
+export function createPresenceHub(options = {}) {
+	const ttlMs = Number.isSafeInteger(options.ttlMs) && options.ttlMs >= 5000 ? options.ttlMs : 30000;
+	const maxConnections = Number.isSafeInteger(options.maxConnections) && options.maxConnections > 0
+		? options.maxConnections
+		: 16;
+
+	/** clientId → { res, lastSeen, visibility, focused } */
+	const clients = new Map();
+	let timer = null;
+
+	const now = () => Date.now();
+
+	/** 正常关闭时立即移除；用于推导 offline。 */
+	const detach = (clientId) => {
+		clients.delete(clientId);
+		stopHeartbeatIfIdle();
+	};
+
+	const stopHeartbeatIfIdle = () => {
+		if (clients.size > 0 || timer === null) return;
+		clearInterval(timer);
+		timer = null;
+	};
+
+	const writeFrame = (res, event, data) => {
+		try {
+			res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+			return true;
+		} catch {
+			return false;
+		}
+	};
+
+	/** 心跳注释帧，防止中间的代理掐断 idle 连接。 */
+	const startHeartbeat = () => {
+		if (timer !== null) return;
+		timer = setInterval(() => {
+			for (const res of [...clients.values()].map((c) => c.res)) {
+				try {
+					res.write(`: hb ${now()}\n\n`);
+				} catch {
+					// 断开的连接由 close 事件清理
+				}
+			}
+		}, 15000);
+		if (typeof timer.unref === 'function') timer.unref();
+	};
+
+	/**
+	 * 接管一个 SSE 连接。
+	 * @param clientId - 浏览器端为每个标签页生成的稳定标识。
+	 * @param res - node HTTP 响应对象。
+	 * @param ready - ready 帧载荷（服务端状态快照）。
+	 * @returns 是否成功接管（false = 超出连接上限）。
+	 */
+	const attach = (clientId, res, ready = {}) => {
+		if (clients.size >= maxConnections) return false;
+		res.writeHead(200, {
+			'content-type': 'text/event-stream',
+			'cache-control': 'no-cache, no-transform',
+			connection: 'keep-alive',
+			'x-accel-buffering': 'no'
+		});
+		clients.set(clientId, { res, lastSeen: now(), visibility: 'visible', focused: false });
+		writeFrame(res, 'ready', { ...ready, clientId });
+		res.on('close', () => {
+			console.log(`[session-notify] 页面连接断开（剩余 ${clients.size - 1} 个）`);
+			detach(clientId);
+		});
+		console.log(`[session-notify] 页面连接建立（clientId=${clientId}，共 ${clients.size} 个）`);
+		startHeartbeat();
+		return true;
+	};
+
+	/** 更新某个客户端的可见性/焦点；返回是否命中已知连接。 */
+	const update = (clientId, patch = {}) => {
+		const client = clients.get(clientId);
+		if (!client) return false;
+		client.lastSeen = now();
+		if (patch.visibility === 'visible' || patch.visibility === 'hidden') client.visibility = patch.visibility;
+		if (typeof patch.focused === 'boolean') client.focused = patch.focused;
+		return true;
+	};
+
+	/** 广播一帧给所有在线客户端。 */
+	const broadcast = (event, data) => {
+		for (const client of clients.values()) writeFrame(client.res, event, data);
+	};
+
+	/** 推给单个客户端（通知类帧用，避免多标签重复弹窗）。 */
+	const sendTo = (clientId, event, data) => {
+		const client = clients.get(clientId);
+		return client ? writeFrame(client.res, event, data) : false;
+	};
+
+	/**
+	 * 三态快照；同时返回通知应该落到哪个标签页。
+	 *
+	 * 关键区分（曾经在这里踩过坑）：
+	 *   - **在线** = SSE 连接还开着。连接存在就是页面存在的证据。
+	 *   - **心跳新鲜度**只用来判断「焦点信息还算不算数」，不用来判断生死。
+	 *
+	 * 不能拿心跳当存活依据：Chrome 对隐藏超过约 5 分钟的标签页会把 setInterval
+	 * 节流到每分钟一次，10 秒的心跳会变成 60 秒，远超任何合理的 TTL ——
+	 * 页面明明开着却会被判成离线，通知被错误地改走 Telegram。
+	 *
+	 * 焦点信息过期时退化为 background（而不是 offline）：这是保守的一侧 ——
+	 * 后台只会发系统通知（点击仍能直达会话），而离线会跳过桌面通道。
+	 */
+	const snapshot = () => {
+		if (clients.size === 0) {
+			return { state: 'offline', targetClientId: null, count: 0, foregroundCount: 0 };
+		}
+		const all = [...clients.entries()];
+		const fresh = all.filter(([, c]) => now() - c.lastSeen <= ttlMs);
+		const foreground = fresh.filter(([, c]) => c.visibility === 'visible' && c.focused === true);
+		if (foreground.length > 0) {
+			// 多个前台标签页时取最近上报的那个
+			const [clientId] = foreground.reduce((a, b) => (b[1].lastSeen > a[1].lastSeen ? b : a));
+			return { state: 'foreground', targetClientId: clientId, count: all.length, foregroundCount: foreground.length };
+		}
+		// 没有新鲜的前台信息：有连接就算后台，优先挑心跳较新的那个
+		const pool = fresh.length > 0 ? fresh : all;
+		const [clientId] = pool.reduce((a, b) => (b[1].lastSeen > a[1].lastSeen ? b : a));
+		return { state: 'background', targetClientId: clientId, count: all.length, foregroundCount: 0 };
+	};
+
+	const dispose = () => {
+		if (timer !== null) {
+			clearInterval(timer);
+			timer = null;
+		}
+		for (const { res } of clients.values()) {
+			try {
+				res.end();
+			} catch {
+				// 已关闭的连接忽略
+			}
+		}
+		clients.clear();
+	};
+
+	return {
+		attach,
+		update,
+		broadcast,
+		sendTo,
+		snapshot,
+		dispose,
+		get size() {
+			return clients.size;
+		}
+	};
+}

package/src/screenlock.js

@@ -0,0 +1,72 @@
+/**
+ * dsh-session-tg-notify — 屏幕锁定探测（macOS）。
+ *
+ * 「人在不在」在 macOS 上没有标准 API 给 Node 用，可靠且零权限的做法是读
+ * IOKit 的 console user 信息：
+ *
+ *   主信号：ioreg -n Root -d1 -a  →  IOConsoleUsers[].CGSSessionScreenIsLocked
+ *           该键**只在锁屏时出现**（未锁屏时整个键不存在），所以「键缺失 = 未锁定」。
+ *   兜底：pgrep -x ScreenSaverEngine —— 屏保/锁屏界面进程在跑也算「离开了」。
+ *         仅在主信号不可用时使用，避免把纯屏保误报成锁屏而覆盖真实判断。
+ *
+ * 只跑在 darwin 上；其他平台返回 supported:false，调用方据此退化为「未锁定」，
+ * 不会把通知永久吞掉。
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+const TIMEOUT_MS = 4000;
+const MAX_BUFFER = 8 * 1024 * 1024;
+
+/**
+ * 从 `ioreg -a` 的 plist XML 里解析锁屏状态。
+ *
+ * 不引入 plist 依赖：只需要一个布尔键，正则足够且不会因 XML 结构变化而整体失败。
+ * ioreg 的 plist 是扁平的 `<key>K</key><true/>` 序列，没有同名嵌套。
+ *
+ * @returns true / false，解析不出结构时返回 null（调用方转兜底信号）。
+ */
+export function parseScreenLocked(xml) {
+	if (typeof xml !== 'string' || xml.length === 0) return null;
+	if (!xml.includes('IOConsoleUsers')) return null;
+	// 多个 console user 时只要有一个锁定即视为锁定（取最保守的判断）
+	const matches = [...xml.matchAll(/<key>CGSSessionScreenIsLocked<\/key>\s*<(true|false)\s*\/>/g)];
+	if (matches.length === 0) return false; // 键缺失 = 未锁定
+	return matches.some((m) => m[1] === 'true');
+}
+
+/**
+ * 读取当前是否锁屏。
+ * @returns { supported: boolean, locked: boolean, signal: string, error?: string }
+ */
+export async function readScreenLocked(options = {}) {
+	const platform = options.platform ?? process.platform;
+	const exec = options.execFile ?? execFileAsync;
+	if (platform !== 'darwin') return { supported: false, locked: false, signal: 'unsupported' };
+
+	try {
+		const { stdout } = await exec('/usr/sbin/ioreg', ['-n', 'Root', '-d', '1', '-a'], {
+			timeout: TIMEOUT_MS,
+			maxBuffer: MAX_BUFFER
+		});
+		const locked = parseScreenLocked(String(stdout));
+		if (locked !== null) return { supported: true, locked, signal: 'ioreg' };
+	} catch (error) {
+		// 落到兜底信号；把原因带出去便于排查
+		return readScreensaverFallback(exec, error?.message);
+	}
+	return readScreensaverFallback(exec, 'ioreg 输出里没有 IOConsoleUsers');
+}
+
+/** 兜底：屏保/锁屏界面进程是否在跑。pgrep 无匹配时退出码为 1，属正常「未锁定」。 */
+async function readScreensaverFallback(exec, reason) {
+	try {
+		const { stdout } = await exec('/usr/bin/pgrep', ['-x', 'ScreenSaverEngine'], { timeout: TIMEOUT_MS });
+		return { supported: true, locked: String(stdout).trim().length > 0, signal: 'screensaver', note: reason };
+	} catch (error) {
+		if (error?.code === 1) return { supported: true, locked: false, signal: 'screensaver', note: reason };
+		return { supported: false, locked: false, signal: 'error', error: error?.message ?? String(error), note: reason };
+	}
+}