@dsh-plus/notify-email 0.1.0

package/lib/index.js

@@ -0,0 +1,579 @@
+import z from "@deepseek-ai/schemastery";
+import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
+import { Context, Service } from "@deepseek-ai/cordis";
+import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import nodemailer from "nodemailer";
+
+//#region src/config.ts
+/** settings 命名空间；webui 配置卡片与插件运行期读取同一份。 */
+const SETTINGS_NS = settingsNamespace("dsh-plus-notify-email");
+const SmtpSchema = z.object({
+	host: z.string().description("SMTP 服务器主机名").default(""),
+	port: z.natural().max(65535).description("SMTP 端口").default(465),
+	secure: z.boolean().description("使用 TLS 直连（465 端口通常为 true）").default(true),
+	user: z.string().description("SMTP 登录用户名（通常为发件邮箱）").default(""),
+	pass: z.string().role("secret").description("SMTP 密码/授权码").default(""),
+	from: z.string().description("发件地址（From 头）").default("")
+});
+const TriggerSchema = z.object({
+	onComplete: z.boolean().description("任务执行完毕时通知").default(true),
+	onError: z.boolean().description("任务报错/失败停止时通知").default(true),
+	onAborted: z.boolean().description("任务被用户取消时通知").default(false),
+	onQuestion: z.boolean().description("agent 提问等待回答时通知").default(true),
+	onPlanReview: z.boolean().description("plan 待审批时通知").default(true)
+});
+const Config = z.object({
+	enabled: z.boolean().description("总开关").default(false),
+	smtp: SmtpSchema.default({
+		host: "",
+		port: 465,
+		secure: true,
+		user: "",
+		pass: "",
+		from: ""
+	}),
+	to: z.array(z.string()).description("收件邮箱列表").default([]),
+	triggers: TriggerSchema.default({
+		onComplete: true,
+		onError: true,
+		onAborted: false,
+		onQuestion: true,
+		onPlanReview: true
+	}),
+	idleDebounceMs: z.natural().description("turn 结束后确认无后续工作的等待毫秒数").default(3e3),
+	maxBodyChars: z.natural().min(200).description("邮件正文内容截断长度").default(4e3),
+	dryRun: z.boolean().description("仅记录日志不真实发送（开发调试用）").default(false)
+});
+function toWire(cfg, writable) {
+	return {
+		enabled: cfg.enabled,
+		smtp: {
+			host: cfg.smtp.host,
+			port: cfg.smtp.port,
+			secure: cfg.smtp.secure,
+			user: cfg.smtp.user,
+			from: cfg.smtp.from,
+			passConfigured: cfg.smtp.pass.length > 0
+		},
+		to: [...cfg.to],
+		triggers: { ...cfg.triggers },
+		idleDebounceMs: cfg.idleDebounceMs,
+		maxBodyChars: cfg.maxBodyChars,
+		dryRun: cfg.dryRun,
+		writable
+	};
+}
+/**
+* 配置卡片写回用的 patch schema：字段全部可选（无默认值），
+* 只携带用户真实编辑过的字段，交给 settings.update 深合并进用户层。
+*/
+const WirePatch = z.object({
+	enabled: z.boolean(),
+	smtp: z.object({
+		host: z.string(),
+		port: z.natural().max(65535),
+		secure: z.boolean(),
+		user: z.string(),
+		pass: z.string(),
+		from: z.string()
+	}),
+	to: z.array(z.string()),
+	triggers: z.object({
+		onComplete: z.boolean(),
+		onError: z.boolean(),
+		onAborted: z.boolean(),
+		onQuestion: z.boolean(),
+		onPlanReview: z.boolean()
+	}),
+	idleDebounceMs: z.natural(),
+	maxBodyChars: z.natural().min(200),
+	dryRun: z.boolean()
+});
+/**
+* 把卡片提交的 patch 规整为 settings.update 的用户层 patch。
+* smtp.pass 为空串表示「保持不变」，从 patch 中剔除，避免覆盖已存密码。
+*/
+function toUserPatch(input) {
+	const patch = { ...input };
+	if (input.smtp !== void 0 && input.smtp !== null) {
+		const smtp = { ...input.smtp };
+		if (smtp["pass"] === "") delete smtp["pass"];
+		patch["smtp"] = smtp;
+	}
+	return patch;
+}
+
+//#endregion
+//#region src/audit.ts
+const BODY_EXCERPT_CHARS = 2e3;
+function buildAuditRecord(subject, text, to, result) {
+	return {
+		time: (/* @__PURE__ */ new Date()).toISOString(),
+		subject,
+		to: [...to],
+		result,
+		bodyExcerpt: text.length > BODY_EXCERPT_CHARS ? `${text.slice(0, BODY_EXCERPT_CHARS)}…` : text
+	};
+}
+/** 构造 JSONL 落盘 sink（fire-and-forget；写入串行排队保证行序，失败经 onError 告警）。 */
+function createJsonlAuditSink(path, onError) {
+	let queue = mkdir(dirname(path), { recursive: true }).then(() => void 0);
+	return (record) => {
+		queue = queue.then(() => appendFile(path, `${JSON.stringify(record)}\n`, "utf8")).catch((error) => {
+			onError(error instanceof Error ? error.message : String(error));
+		});
+	};
+}
+
+//#endregion
+//#region src/mailer.ts
+/**  nodemailer 连接/问候/套接字超时（毫秒），防 SMTP 不可达时挂住通知链路。 */
+const CONNECTION_TIMEOUT_MS = 1e4;
+const GREETING_TIMEOUT_MS = 1e4;
+const SOCKET_TIMEOUT_MS = 3e4;
+/** 真实 SMTP 通道：每次发送按当前配置新建 transport（配置热改即生效，发送低频无池化需求）。 */
+const smtpTransport = async (cfg, msg) => {
+	await nodemailer.createTransport({
+		host: cfg.smtp.host,
+		port: cfg.smtp.port,
+		secure: cfg.smtp.secure,
+		auth: cfg.smtp.user.length > 0 ? {
+			user: cfg.smtp.user,
+			pass: cfg.smtp.pass
+		} : void 0,
+		connectionTimeout: CONNECTION_TIMEOUT_MS,
+		greetingTimeout: GREETING_TIMEOUT_MS,
+		socketTimeout: SOCKET_TIMEOUT_MS
+	}).sendMail({
+		from: cfg.smtp.from,
+		to: cfg.to.join(", "),
+		subject: msg.subject,
+		text: msg.text,
+		...msg.html !== void 0 ? { html: msg.html } : {}
+	});
+};
+var Mailer = class {
+	resolveConfig;
+	logger;
+	transport;
+	audit;
+	constructor(resolveConfig, logger, transport = smtpTransport, audit) {
+		this.resolveConfig = resolveConfig;
+		this.logger = logger;
+		this.transport = transport;
+		this.audit = audit;
+	}
+	/**
+	* 常规通知发送：受 enabled 与配置完整性门禁。
+	* @param force 为 true 时跳过 enabled 门禁（配置卡片的「发送测试邮件」），仍需 SMTP 完整。
+	*/
+	async send(msg, force = false) {
+		const cfg = this.resolveConfig();
+		if (!force && !cfg.enabled) return this.record(msg, cfg, {
+			ok: false,
+			detail: "disabled"
+		});
+		if (cfg.smtp.host.length === 0 || cfg.smtp.from.length === 0 || cfg.to.length === 0) return this.record(msg, cfg, {
+			ok: false,
+			detail: "incomplete"
+		});
+		if (cfg.dryRun) {
+			this.logger.info(`[dry-run] subject=${msg.subject}\n${msg.text}`);
+			return this.record(msg, cfg, {
+				ok: true,
+				detail: "dry-run"
+			});
+		}
+		try {
+			await this.transport(cfg, msg);
+			return this.record(msg, cfg, {
+				ok: true,
+				detail: "sent"
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			this.logger.warn(`send failed: ${message} (subject=${msg.subject})`);
+			return this.record(msg, cfg, {
+				ok: false,
+				detail: message
+			});
+		}
+	}
+	record(msg, cfg, result) {
+		this.audit?.(buildAuditRecord(msg.subject, msg.text, cfg.to, result.detail));
+		return result;
+	}
+};
+
+//#endregion
+//#region src/config-api.ts
+const ROUTE_CONFIG = "/dsh-plus/notify-email/config";
+const ROUTE_TEST = "/dsh-plus/notify-email/test";
+const MAX_BODY_BYTES = 64 * 1024;
+function sendJson(res, status, body) {
+	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+	res.end(JSON.stringify(body));
+}
+function readBody(req) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		req.on("data", (chunk) => {
+			size += chunk.length;
+			if (size > MAX_BODY_BYTES) {
+				reject(/* @__PURE__ */ new Error("request body too large"));
+				req.destroy();
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+		req.on("error", reject);
+	});
+}
+async function readPatch(req) {
+	const raw = await readBody(req);
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new Error("request body is not valid JSON");
+	}
+	return WirePatch(parsed);
+}
+async function handleConfig(ctx, service, req, res) {
+	const settings = ctx.get("settings");
+	if (req.method === "GET") {
+		sendJson(res, 200, toWire(service.currentConfig(), settings !== void 0));
+		return;
+	}
+	if (req.method !== "PUT") {
+		sendJson(res, 405, { error: "method not allowed" });
+		return;
+	}
+	if (settings === void 0) {
+		sendJson(res, 503, { error: "settings provider 不可用，无法在线保存；请编辑 settings.yaml" });
+		return;
+	}
+	const patch = toUserPatch(await readPatch(req));
+	await settings.update(SETTINGS_NS, patch);
+	sendJson(res, 200, toWire(service.currentConfig(), true));
+}
+async function handleTest(service, res) {
+	const result = await service.sendTest();
+	sendJson(res, result.ok ? 200 : 502, result);
+}
+/** 注册配置读写与测试发信路由；返回是否注册成功（webServer 缺失时由调用方保证不调用）。 */
+function registerConfigApi(ctx, service) {
+	const logger = ctx.logger("notify-email");
+	const guard = (handler) => {
+		return async (req, res) => {
+			try {
+				await handler(req, res);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				logger.warn(`config api ${req.method ?? "?"} ${req.url ?? "?"} failed: ${message}`);
+				if (!res.headersSent) sendJson(res, 400, { error: message });
+				else res.end();
+			}
+		};
+	};
+	ctx.webServer.register({
+		kind: "exact",
+		path: ROUTE_CONFIG,
+		handler: guard((req, res) => handleConfig(ctx, service, req, res))
+	});
+	ctx.webServer.register({
+		kind: "exact",
+		path: ROUTE_TEST,
+		handler: guard(async (req, res) => {
+			if (req.method !== "POST") {
+				sendJson(res, 405, { error: "method not allowed" });
+				return;
+			}
+			await handleTest(service, res);
+		})
+	});
+}
+
+//#endregion
+//#region src/triggers/render.ts
+function truncate(text, maxChars) {
+	if (text.length <= maxChars) return text;
+	return `${text.slice(0, maxChars)}\n……（内容过长已截断）`;
+}
+function shortSession(sessionId) {
+	return sessionId.length > 8 ? sessionId.slice(0, 8) : sessionId;
+}
+function header(reason, info) {
+	const turnPart = info.turn === void 0 ? "" : ` · turn ${info.turn}`;
+	return `通知原因：${reason}\n会话：${shortSession(info.sessionId)}${turnPart}\n时间：${(/* @__PURE__ */ new Date()).toISOString()}\n`;
+}
+function renderOption(option, index) {
+	const label = typeof option?.label === "string" ? option.label : `选项 ${index + 1}`;
+	const desc = typeof option?.description === "string" ? ` — ${option.description}` : "";
+	return `  ${index + 1}. ${label}${desc}`;
+}
+function renderQuestion(item, index) {
+	const title = typeof item?.question === "string" ? item.question : "(未命名问题)";
+	const head = typeof item?.header === "string" ? `【${item.header}】` : "";
+	const multi = item?.multi_select === true ? "（可多选）" : "";
+	const lines = (Array.isArray(item?.options) ? item.options : []).map((o, i) => renderOption(o, i));
+	return [`问题 ${index + 1}：${head}${title}${multi}`, ...lines].join("\n");
+}
+/** ask_user_question 工具参数 → 通知（问题 + 选项）。 */
+function renderQuestionNotice(call, maxChars) {
+	const body = (Array.isArray(call.args["questions"]) ? call.args["questions"] : []).map((q, i) => renderQuestion(q, i)).join("\n\n");
+	return {
+		subject: `[DSH] 等待你的回答 · 会话 ${shortSession(call.sessionId)}`,
+		text: `${header("agent 提问，等待用户回答", call)}\n${truncate(body, maxChars)}`
+	};
+}
+/** exit_plan_mode 工具参数 → 通知（plan 全文）。 */
+function renderPlanNotice(call, maxChars) {
+	const plan = typeof call.args["plan"] === "string" ? call.args["plan"] : "(plan 内容缺失)";
+	return {
+		subject: `[DSH] Plan 待审批 · 会话 ${shortSession(call.sessionId)}`,
+		text: `${header("agent 提交了计划，等待审批", call)}\n${truncate(plan, maxChars)}`
+	};
+}
+/** turn 正常结束 → 通知（最后一条 assistant 交付消息）。 */
+function renderCompletionNotice(info, maxChars) {
+	const delivery = info.lastDelivery ?? "(本轮无文本交付内容)";
+	return {
+		subject: `[DSH] 任务执行完毕 · 会话 ${shortSession(info.sessionId)}`,
+		text: `${header("任务执行完毕", info)}\n${truncate(delivery, maxChars)}`
+	};
+}
+/** turn 出错 → 通知（错误信息）。 */
+function renderErrorNotice(info, maxChars) {
+	const detail = info.errorMessage ?? "(错误详情缺失)";
+	return {
+		subject: `[DSH] 任务出错停止 · 会话 ${shortSession(info.sessionId)}`,
+		text: `${header("任务报错/失败停止", info)}\n${truncate(detail, maxChars)}`
+	};
+}
+/** turn 被取消 → 通知。 */
+function renderAbortedNotice(info) {
+	return {
+		subject: `[DSH] 任务被取消 · 会话 ${shortSession(info.sessionId)}`,
+		text: header("任务被用户取消", info)
+	};
+}
+
+//#endregion
+//#region src/triggers/builtin.ts
+/** 官方决策工具名 → 渲染函数 + 对应 toggle。 */
+function createDecisionTrigger(resolveConfig) {
+	return {
+		id: "dsh-plus-official-decision",
+		onDecision(call) {
+			const cfg = resolveConfig();
+			if (call.name === "ask_user_question" && cfg.triggers.onQuestion) return renderQuestionNotice(call, cfg.maxBodyChars);
+			if (call.name === "exit_plan_mode" && cfg.triggers.onPlanReview) return renderPlanNotice(call, cfg.maxBodyChars);
+		}
+	};
+}
+function createTurnEndTrigger(resolveConfig) {
+	return {
+		id: "dsh-plus-official-turn-end",
+		onTurnEnd(info) {
+			const cfg = resolveConfig();
+			if (info.kind === "completed" && cfg.triggers.onComplete) return renderCompletionNotice(info, cfg.maxBodyChars);
+			if (info.kind === "error" && cfg.triggers.onError) return renderErrorNotice(info, cfg.maxBodyChars);
+			if (info.kind === "aborted" && cfg.triggers.onAborted) return renderAbortedNotice(info);
+		}
+	};
+}
+
+//#endregion
+//#region src/watchers/decision.ts
+function installDecisionWatcher(ctx, service) {
+	const seen = /* @__PURE__ */ new Set();
+	const logger = ctx.logger("notify-email");
+	ctx.on("tools/pre-execute", (exec, next) => {
+		if (seen.has(exec.callId)) return next();
+		seen.add(exec.callId);
+		const sessionId = exec.agent?.id ?? "unknown";
+		service.dispatchDecision({
+			callId: exec.callId,
+			sessionId,
+			name: exec.name,
+			args: exec.arguments ?? {}
+		}).catch((error) => {
+			logger.warn(`decision dispatch failed (${exec.name}, call ${exec.callId}): ` + (error instanceof Error ? error.message : String(error)));
+		});
+		return next();
+	});
+}
+
+//#endregion
+//#region src/watchers/turn-end.ts
+/** 只有这三类 turn 结束对用户有可决策价值；blocked/max-tokens/interrupted 不通知。 */
+const NOTIFY_KINDS = new Set([
+	"completed",
+	"error",
+	"aborted"
+]);
+/** 从 assistant 消息 content 提取纯文本交付内容（仅 text 块，忽略工具调用等）。 */
+function extractDeliveryText(content) {
+	const text = content.filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("\n").trim();
+	return text.length > 0 ? text : void 0;
+}
+function extractErrorMessage(reason) {
+	if (typeof reason !== "object" || reason === null) return void 0;
+	const error = reason.error;
+	if (typeof error !== "object" || error === null) return void 0;
+	const message = error.message;
+	return typeof message === "string" ? message : void 0;
+}
+function installTurnEndWatcher(ctx, service, resolveConfig) {
+	const watches = /* @__PURE__ */ new Map();
+	const logger = ctx.logger("notify-email");
+	const watchOf = (sessionId) => {
+		let watch = watches.get(sessionId);
+		if (watch === void 0) {
+			watch = { notified: /* @__PURE__ */ new Set() };
+			watches.set(sessionId, watch);
+		}
+		return watch;
+	};
+	const fire = (session, turn, kind, errorMessage) => {
+		const agent = ctx.agents.get(session.id);
+		if (agent === void 0) return;
+		if (agent.status !== "idle" || agent.inbox.hasPending) return;
+		if (!ctx.agents.roots().includes(agent)) return;
+		const watch = watchOf(session.id);
+		const key = `${turn}:${kind}`;
+		if (watch.notified.has(key)) return;
+		watch.notified.add(key);
+		service.dispatchTurnEnd({
+			sessionId: session.id,
+			turn,
+			kind,
+			...errorMessage !== void 0 ? { errorMessage } : {},
+			...watch.lastDelivery !== void 0 ? { lastDelivery: watch.lastDelivery } : {}
+		}).catch((error) => {
+			logger.warn(`turn-end dispatch failed (${session.id}, turn ${turn}, ${kind}): ` + (error instanceof Error ? error.message : String(error)));
+		});
+	};
+	const onTurnEnd = (session, turn, reason) => {
+		if (!NOTIFY_KINDS.has(reason.kind)) return;
+		const watch = watchOf(session.id);
+		if (watch.timer !== void 0) clearTimeout(watch.timer);
+		const errorMessage = extractErrorMessage(reason);
+		watch.timer = setTimeout(() => {
+			watch.timer = void 0;
+			fire(session, turn, reason.kind, errorMessage);
+		}, resolveConfig().idleDebounceMs);
+	};
+	ctx.on("session/event", (session, event) => {
+		if (event.type === "assistant/message") {
+			const text = extractDeliveryText(event.data.message.content);
+			if (text !== void 0) watchOf(session.id).lastDelivery = text;
+			return;
+		}
+		if (event.type === "turn/start") {
+			const watch = watches.get(session.id);
+			if (watch?.timer !== void 0) {
+				clearTimeout(watch.timer);
+				watch.timer = void 0;
+			}
+			return;
+		}
+		if (event.type === "turn/end") onTurnEnd(session, event.data.turn, event.data.reason);
+	});
+	ctx.on("session/disposed", (session) => {
+		const watch = watches.get(session.id);
+		if (watch?.timer !== void 0) clearTimeout(watch.timer);
+		watches.delete(session.id);
+	});
+	ctx.effect(() => () => {
+		for (const watch of watches.values()) if (watch.timer !== void 0) clearTimeout(watch.timer);
+		watches.clear();
+	}, "notify-email: turn-end timers");
+}
+
+//#endregion
+//#region src/service.ts
+var NotifyEmailService = class extends Service {
+	static [Context.inject] = ["agents", "tools"];
+	triggers = [];
+	mailer;
+	current;
+	constructor(ctx, config) {
+		super(ctx, "notifyEmail");
+		this.current = () => config;
+		installSettingsSection(ctx, SETTINGS_NS, Config, config, {
+			setSource: (source) => {
+				this.current = source;
+			},
+			onChange: () => {}
+		});
+		const logger = ctx.logger("notify-email");
+		this.mailer = new Mailer(() => this.current(), logger, void 0, createJsonlAuditSink(dshHomePath("logs", "notify-email.jsonl"), (message) => logger.warn(`audit write failed: ${message}`)));
+		this.registerTrigger(createDecisionTrigger(() => this.current()));
+		this.registerTrigger(createTurnEndTrigger(() => this.current()));
+		installDecisionWatcher(ctx, this);
+		installTurnEndWatcher(ctx, this, () => this.current());
+		ctx.inject(["webServer"], (webCtx) => {
+			registerConfigApi(webCtx, this);
+		});
+	}
+	/** 注册触发器（第三方扩展接口）；返回注销函数，随调用方 fiber 释放。 */
+	registerTrigger(trigger) {
+		if (this.triggers.some((t) => t.id === trigger.id)) throw new Error(`notify-email: duplicate trigger id ${JSON.stringify(trigger.id)}`);
+		this.triggers.push(trigger);
+		return this.ctx.effect(() => () => {
+			const index = this.triggers.indexOf(trigger);
+			if (index >= 0) this.triggers.splice(index, 1);
+		}, `notify-email: trigger ${trigger.id}`);
+	}
+	/** 当前生效配置（settings 用户层解析结果或 cordis 行级 config）。 */
+	currentConfig() {
+		return this.current();
+	}
+	/** 决策类观察入口（decision watcher 调用）。 */
+	async dispatchDecision(call) {
+		await this.dispatch("decision", call, (t) => t.onDecision?.(call));
+	}
+	/** 任务停止类观察入口（turn-end watcher 调用）。 */
+	async dispatchTurnEnd(info) {
+		await this.dispatch("turn-end", info, (t) => t.onTurnEnd?.(info));
+	}
+	/** 配置卡片「发送测试邮件」：绕过 enabled 门禁，仍需 SMTP 完整。 */
+	async sendTest() {
+		return this.mailer.send({
+			subject: "[DSH] 邮件通知测试",
+			text: "这是一封来自 dsh notify-email 插件的测试邮件。"
+		}, true);
+	}
+	async dispatch(kind, payload, produce) {
+		for (const trigger of [...this.triggers]) {
+			let notice;
+			try {
+				notice = produce(trigger);
+			} catch (error) {
+				this.ctx.logger("notify-email").warn(`trigger ${trigger.id} failed on ${kind}: ${error instanceof Error ? error.message : String(error)}`);
+				continue;
+			}
+			if (notice === void 0) continue;
+			const result = await this.mailer.send(notice);
+			if (!result.ok && result.detail !== "disabled" && result.detail !== "incomplete") this.ctx.logger("notify-email").warn(`deliver failed via trigger ${trigger.id}: ${result.detail}`);
+			return;
+		}
+	}
+};
+
+//#endregion
+//#region src/index.ts
+const name = "dsh-plus-notify-email";
+const inject = ["agents", "tools"];
+function apply(ctx, config) {
+	ctx.plugin(NotifyEmailService, config);
+}
+
+//#endregion
+export { Config, NotifyEmailService, apply, inject, name };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@dsh-plus/notify-email",
+  "version": "0.1.0",
+  "description": "dsh-plus service+ui plugin: 任务结束/等待决策/出错时向指定邮箱发送邮件通知",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale"
+      ],
+      "platform": "web"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-home-paths": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "3.18.1",
+    "nodemailer": "9.0.5"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.6",
+    "@types/nodemailer": "8.0.1",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/A-G-guy/dsh-plugins.git",
+    "directory": "packages/notify-email"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}

package/src/audit.ts

@@ -0,0 +1,48 @@
+/**
+ * 通知投递审计：每次发送尝试追加一行 JSONL 到 $DSH_HOME/logs/notify-email.jsonl。
+ * 让 dry-run 可观测（dev 实例 logger 不落盘），也为生产排查「为什么没收到邮件」留痕。
+ * 记录正文截断 2000 字符；永远不含 SMTP 凭据。写失败只告警不阻断。
+ * @module notify-email/audit
+ */
+import { appendFile, mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+export interface AuditRecord {
+  time: string
+  subject: string
+  to: string[]
+  /** sent | dry-run | disabled | incomplete | 错误消息 */
+  result: string
+  bodyExcerpt: string
+}
+
+const BODY_EXCERPT_CHARS = 2000
+
+export function buildAuditRecord(
+  subject: string,
+  text: string,
+  to: string[],
+  result: string,
+): AuditRecord {
+  return {
+    time: new Date().toISOString(),
+    subject,
+    to: [...to],
+    result,
+    bodyExcerpt: text.length > BODY_EXCERPT_CHARS ? `${text.slice(0, BODY_EXCERPT_CHARS)}…` : text,
+  }
+}
+
+export type AuditSink = (record: AuditRecord) => void
+
+/** 构造 JSONL 落盘 sink（fire-and-forget；写入串行排队保证行序，失败经 onError 告警）。 */
+export function createJsonlAuditSink(path: string, onError: (message: string) => void): AuditSink {
+  let queue: Promise<void> = mkdir(dirname(path), { recursive: true }).then(() => undefined)
+  return (record) => {
+    queue = queue
+      .then(() => appendFile(path, `${JSON.stringify(record)}\n`, 'utf8'))
+      .catch((error: unknown) => {
+        onError(error instanceof Error ? error.message : String(error))
+      })
+  }
+}