@dsh-plus/notify-email 0.1.0

package/src/config-api.ts

@@ -0,0 +1,116 @@
+/**
+ * 配置 HTTP 通道：webui 插件配置卡片的后端。
+ * 背景：官方 apiproxy 的 settings.* RPC 对 namespace 有硬编码白名单，第三方
+ * namespace 一律 settings-not-exposed；故卡片数据走自建 webServer 路由，
+ * 读写仍经 ctx.settings 用户层（持久化 $DSH_HOME/settings.yaml）。
+ * 仅监听 dsh web 同源（webserver 默认 127.0.0.1），与 GUI 其余面同等暴露面。
+ * @module notify-email/config-api
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+
+import type { Context } from '@deepseek-ai/cordis'
+
+import { SETTINGS_NS, toUserPatch, toWire, WirePatch, type WirePatchInput } from './config.ts'
+import type { NotifyEmailService } from './service.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: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(body))
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    let size = 0
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length
+      if (size > MAX_BODY_BYTES) {
+        reject(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: IncomingMessage): Promise<WirePatchInput> {
+  const raw = await readBody(req)
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    throw new Error('request body is not valid JSON')
+  }
+  return WirePatch(parsed) as WirePatchInput
+}
+
+async function handleConfig(
+  ctx: Context,
+  service: NotifyEmailService,
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  const settings = ctx.get('settings')
+  if (req.method === 'GET') {
+    sendJson(res, 200, toWire(service.currentConfig(), settings !== undefined))
+    return
+  }
+  if (req.method !== 'PUT') {
+    sendJson(res, 405, { error: 'method not allowed' })
+    return
+  }
+  if (settings === undefined) {
+    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: NotifyEmailService, res: ServerResponse): Promise<void> {
+  const result = await service.sendTest()
+  sendJson(res, result.ok ? 200 : 502, result)
+}
+
+/** 注册配置读写与测试发信路由；返回是否注册成功（webServer 缺失时由调用方保证不调用）。 */
+export function registerConfigApi(ctx: Context, service: NotifyEmailService): void {
+  const logger = ctx.logger('notify-email')
+  const guard = (
+    handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>,
+  ): ((req: IncomingMessage, res: ServerResponse) => Promise<void>) => {
+    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)
+    }),
+  })
+}

package/src/config.ts

@@ -0,0 +1,131 @@
+/**
+ * 配置单一事实源：cordis 行级 Config（组合默认值，dev/prod patch 层可覆盖）
+ * 与 settings namespace（用户层，经 dsh-settings-file 持久化到 $DSH_HOME/settings.yaml）
+ * 共用同一 schemastery schema。SMTP 密码标记 secret 角色，任何读取通道不得回传。
+ * @module notify-email/config
+ */
+import z from '@deepseek-ai/schemastery'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+
+/** settings 命名空间；webui 配置卡片与插件运行期读取同一份。 */
+export 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),
+})
+
+export 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(3000),
+  maxBodyChars: z.natural().min(200).description('邮件正文内容截断长度').default(4000),
+  dryRun: z.boolean().description('仅记录日志不真实发送（开发调试用）').default(false),
+})
+
+export type NotifyEmailConfig = Schemastery.TypeT<typeof Config>
+export type TriggerToggles = NotifyEmailConfig['triggers']
+
+/** 配置卡片读取用的传输对象：pass 永不回传，只报告是否已配置。 */
+export interface WireConfig {
+  enabled: boolean
+  smtp: {
+    host: string
+    port: number
+    secure: boolean
+    user: string
+    from: string
+    passConfigured: boolean
+  }
+  to: string[]
+  triggers: TriggerToggles
+  idleDebounceMs: number
+  maxBodyChars: number
+  dryRun: boolean
+  /** 是否存在可写的 settings provider（决定卡片是否允许编辑）。 */
+  writable: boolean
+}
+
+export function toWire(cfg: NotifyEmailConfig, writable: boolean): WireConfig {
+  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,
+  }
+}
+
+/** 是否具备发信条件（enabled 之外的最小完整性）。 */
+export function isDeliverable(cfg: NotifyEmailConfig): boolean {
+  return cfg.enabled && cfg.smtp.host.length > 0 && cfg.smtp.from.length > 0 && cfg.to.length > 0
+}
+
+/**
+ * 配置卡片写回用的 patch schema：字段全部可选（无默认值），
+ * 只携带用户真实编辑过的字段，交给 settings.update 深合并进用户层。
+ */
+export 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(),
+})
+
+export type WirePatchInput = Schemastery.TypeS<typeof WirePatch>
+
+/**
+ * 把卡片提交的 patch 规整为 settings.update 的用户层 patch。
+ * smtp.pass 为空串表示「保持不变」，从 patch 中剔除，避免覆盖已存密码。
+ */
+export function toUserPatch(input: WirePatchInput): Record<string, unknown> {
+  const patch: Record<string, unknown> = { ...input }
+  if (input.smtp !== undefined && input.smtp !== null) {
+    const smtp: Record<string, unknown> = { ...input.smtp }
+    if (smtp['pass'] === '') delete smtp['pass']
+    patch['smtp'] = smtp
+  }
+  return patch
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/**
+ * dsh 插件：任务结束邮件通知。
+ * 在 agent 停止工作的三类时机经配置的 SMTP 邮箱向指定收件人发邮件：
+ * 任务执行完毕（最后一条交付消息）、等待用户决策（提问/plan 审批）、报错停止。
+ * 扩展接口：第三方插件 ctx.inject(['notifyEmail']) 后 registerTrigger() 注册自定义通知。
+ * @module @dsh-plus/notify-email
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+import { Config, type NotifyEmailConfig } from './config.ts'
+import { NotifyEmailService } from './service.ts'
+
+export const name = 'dsh-plus-notify-email'
+
+export const inject = ['agents', 'tools'] as const
+
+export { Config }
+
+export type { EmailNotice, DecisionCall, TurnEndInfo, NotifyTrigger } from './triggers/types.ts'
+export { NotifyEmailService } from './service.ts'
+
+export function apply(ctx: Context, config: NotifyEmailConfig): void {
+  ctx.plugin(NotifyEmailService, config)
+}

package/src/mailer.ts

@@ -0,0 +1,103 @@
+/**
+ * 邮件发送：nodemailer 封装 + dry-run 兜底。
+ * Transport 抽象为函数注入，单元测试以假 transport 断言参数，零网络。
+ * @module notify-email/mailer
+ */
+import nodemailer from 'nodemailer'
+
+import { buildAuditRecord, type AuditSink } from './audit.ts'
+import { isDeliverable, type NotifyEmailConfig } from './config.ts'
+
+/** 一封待发邮件（触发器产物的最小契约）。 */
+export interface MailMessage {
+  subject: string
+  text: string
+  html?: string
+}
+
+export interface SendResult {
+  ok: boolean
+  /** 'sent' | 'dry-run' | 'disabled' | 'incomplete' | 错误消息。 */
+  detail: string
+}
+
+/** 发送通道：按生效配置投递一封邮件；失败抛错由调用方归一化。 */
+export type Transport = (cfg: NotifyEmailConfig, msg: MailMessage) => Promise<void>
+
+export interface MailLogger {
+  info(msg: string): void
+  warn(msg: string): void
+}
+
+/**  nodemailer 连接/问候/套接字超时（毫秒），防 SMTP 不可达时挂住通知链路。 */
+const CONNECTION_TIMEOUT_MS = 10_000
+const GREETING_TIMEOUT_MS = 10_000
+const SOCKET_TIMEOUT_MS = 30_000
+
+/** 真实 SMTP 通道：每次发送按当前配置新建 transport（配置热改即生效，发送低频无池化需求）。 */
+export const smtpTransport: Transport = async (cfg, msg) => {
+  const transporter = 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 } : undefined,
+    connectionTimeout: CONNECTION_TIMEOUT_MS,
+    greetingTimeout: GREETING_TIMEOUT_MS,
+    socketTimeout: SOCKET_TIMEOUT_MS,
+  })
+  await transporter.sendMail({
+    from: cfg.smtp.from,
+    to: cfg.to.join(', '),
+    subject: msg.subject,
+    text: msg.text,
+    ...(msg.html !== undefined ? { html: msg.html } : {}),
+  })
+}
+
+export class Mailer {
+  private readonly resolveConfig: () => NotifyEmailConfig
+  private readonly logger: MailLogger
+  private readonly transport: Transport
+  private readonly audit?: AuditSink
+
+  constructor(
+    resolveConfig: () => NotifyEmailConfig,
+    logger: MailLogger,
+    transport: Transport = smtpTransport,
+    audit?: AuditSink,
+  ) {
+    this.resolveConfig = resolveConfig
+    this.logger = logger
+    this.transport = transport
+    this.audit = audit
+  }
+
+  /**
+   * 常规通知发送：受 enabled 与配置完整性门禁。
+   * @param force 为 true 时跳过 enabled 门禁（配置卡片的「发送测试邮件」），仍需 SMTP 完整。
+   */
+  async send(msg: MailMessage, force = false): Promise<SendResult> {
+    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 })
+    }
+  }
+
+  private record(msg: MailMessage, cfg: NotifyEmailConfig, result: SendResult): SendResult {
+    this.audit?.(buildAuditRecord(msg.subject, msg.text, cfg.to, result.detail))
+    return result
+  }
+}

package/src/service.ts

@@ -0,0 +1,122 @@
+/**
+ * NotifyEmailService：通知编排中枢。
+ * - 配置：installSettingsSection 接入 settings 用户层（$DSH_HOME/settings.yaml，热生效），
+ *   无 settings provider 时退化为 cordis 行级 config。
+ * - 触发器：registerTrigger 是第三方插件的扩展接口；内置官方适配器同路径注册。
+ * - 投递：首个非空 EmailNotice 经 Mailer 发送；单个触发器抛错不影响其余。
+ * @module @dsh-plus/notify-email
+ */
+import { Context, Service } from '@deepseek-ai/cordis'
+import { dshHomePath } from '@deepseek-ai/dsh-home-paths'
+
+import { createJsonlAuditSink } from './audit.ts'
+import { Config, SETTINGS_NS, type NotifyEmailConfig } from './config.ts'
+import { Mailer } from './mailer.ts'
+import { installSettingsSection } from '@deepseek-ai/dsh-settings'
+import { registerConfigApi } from './config-api.ts'
+import { createDecisionTrigger, createTurnEndTrigger } from './triggers/builtin.ts'
+import type { DecisionCall, NotifyTrigger, TurnEndInfo } from './triggers/types.ts'
+import { installDecisionWatcher } from './watchers/decision.ts'
+import { installTurnEndWatcher } from './watchers/turn-end.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    notifyEmail: NotifyEmailService
+  }
+}
+
+export class NotifyEmailService extends Service {
+  static [Context.inject] = ['agents', 'tools']
+
+  private readonly triggers: NotifyTrigger[] = []
+  private readonly mailer: Mailer
+  private current: () => NotifyEmailConfig
+
+  constructor(ctx: Context, config: NotifyEmailConfig) {
+    super(ctx, 'notifyEmail')
+    this.current = () => config
+    installSettingsSection(ctx, SETTINGS_NS, Config, config, {
+      setSource: (source) => {
+        this.current = source
+      },
+      onChange: () => {},
+    })
+    const logger = ctx.logger('notify-email')
+    const audit = createJsonlAuditSink(
+      dshHomePath('logs', 'notify-email.jsonl'),
+      (message) => logger.warn(`audit write failed: ${message}`),
+    )
+    this.mailer = new Mailer(() => this.current(), logger, undefined, audit)
+    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: NotifyTrigger): () => void {
+    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(): NotifyEmailConfig {
+    return this.current()
+  }
+
+  /** 决策类观察入口（decision watcher 调用）。 */
+  async dispatchDecision(call: DecisionCall): Promise<void> {
+    await this.dispatch('decision', call, (t) => t.onDecision?.(call))
+  }
+
+  /** 任务停止类观察入口（turn-end watcher 调用）。 */
+  async dispatchTurnEnd(info: TurnEndInfo): Promise<void> {
+    await this.dispatch('turn-end', info, (t) => t.onTurnEnd?.(info))
+  }
+
+  /** 配置卡片「发送测试邮件」：绕过 enabled 门禁，仍需 SMTP 完整。 */
+  async sendTest(): Promise<{ ok: boolean; detail: string }> {
+    return this.mailer.send(
+      { subject: '[DSH] 邮件通知测试', text: '这是一封来自 dsh notify-email 插件的测试邮件。' },
+      true,
+    )
+  }
+
+  private async dispatch<T>(
+    kind: string,
+    payload: T,
+    produce: (t: NotifyTrigger) => { subject: string; text: string; html?: string } | undefined,
+  ): Promise<void> {
+    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 === undefined) 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
+    }
+  }
+}

package/src/triggers/builtin.ts

@@ -0,0 +1,47 @@
+/**
+ * 内置官方适配器：ask_user_question / exit_plan_mode 决策通知，
+ * 以及 turn 结束（completed/error/aborted）通知。按配置 toggles 门控。
+ * @module notify-email/triggers/builtin
+ */
+import type { NotifyEmailConfig } from '../config.ts'
+import {
+  renderAbortedNotice, renderCompletionNotice, renderErrorNotice,
+  renderPlanNotice, renderQuestionNotice,
+} from './render.ts'
+import type { NotifyTrigger } from './types.ts'
+
+/** 官方决策工具名 → 渲染函数 + 对应 toggle。 */
+export function createDecisionTrigger(resolveConfig: () => NotifyEmailConfig): NotifyTrigger {
+  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)
+      }
+      return undefined
+    },
+  }
+}
+
+export function createTurnEndTrigger(resolveConfig: () => NotifyEmailConfig): NotifyTrigger {
+  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)
+      }
+      return undefined
+    },
+  }
+}

package/src/triggers/render.ts

@@ -0,0 +1,93 @@
+/**
+ * 触发器产物的纯函数渲染：各类通知 → 邮件 subject/text。
+ * 不依赖 cordis，单测直接覆盖；模板中文、正文超长统一截断。
+ * @module notify-email/triggers/render
+ */
+import type { DecisionCall, EmailNotice, TurnEndInfo } from './types.ts'
+
+function truncate(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text
+  return `${text.slice(0, maxChars)}\n……（内容过长已截断）`
+}
+
+function shortSession(sessionId: string): string {
+  return sessionId.length > 8 ? sessionId.slice(0, 8) : sessionId
+}
+
+function header(reason: string, info: { sessionId: string; turn?: number }): string {
+  const turnPart = info.turn === undefined ? '' : ` · turn ${info.turn}`
+  return `通知原因：${reason}\n会话：${shortSession(info.sessionId)}${turnPart}\n时间：${new Date().toISOString()}\n`
+}
+
+interface QuestionOption {
+  label?: unknown
+  description?: unknown
+}
+
+interface QuestionItem {
+  id?: unknown
+  header?: unknown
+  question?: unknown
+  options?: unknown
+  multi_select?: unknown
+}
+
+function renderOption(option: QuestionOption, index: number): string {
+  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: QuestionItem, index: number): string {
+  const title = typeof item?.question === 'string' ? item.question : '(未命名问题)'
+  const head = typeof item?.header === 'string' ? `【${item.header}】` : ''
+  const multi = item?.multi_select === true ? '（可多选）' : ''
+  const options = Array.isArray(item?.options) ? item.options : []
+  const lines = options.map((o, i) => renderOption(o as QuestionOption, i))
+  return [`问题 ${index + 1}：${head}${title}${multi}`, ...lines].join('\n')
+}
+
+/** ask_user_question 工具参数 → 通知（问题 + 选项）。 */
+export function renderQuestionNotice(call: DecisionCall, maxChars: number): EmailNotice {
+  const questions = Array.isArray(call.args['questions']) ? call.args['questions'] : []
+  const body = questions.map((q, i) => renderQuestion(q as QuestionItem, i)).join('\n\n')
+  return {
+    subject: `[DSH] 等待你的回答 · 会话 ${shortSession(call.sessionId)}`,
+    text: `${header('agent 提问，等待用户回答', call)}\n${truncate(body, maxChars)}`,
+  }
+}
+
+/** exit_plan_mode 工具参数 → 通知（plan 全文）。 */
+export function renderPlanNotice(call: DecisionCall, maxChars: number): EmailNotice {
+  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 交付消息）。 */
+export function renderCompletionNotice(info: TurnEndInfo, maxChars: number): EmailNotice {
+  const delivery = info.lastDelivery ?? '(本轮无文本交付内容)'
+  return {
+    subject: `[DSH] 任务执行完毕 · 会话 ${shortSession(info.sessionId)}`,
+    text: `${header('任务执行完毕', info)}\n${truncate(delivery, maxChars)}`,
+  }
+}
+
+/** turn 出错 → 通知（错误信息）。 */
+export function renderErrorNotice(info: TurnEndInfo, maxChars: number): EmailNotice {
+  const detail = info.errorMessage ?? '(错误详情缺失)'
+  return {
+    subject: `[DSH] 任务出错停止 · 会话 ${shortSession(info.sessionId)}`,
+    text: `${header('任务报错/失败停止', info)}\n${truncate(detail, maxChars)}`,
+  }
+}
+
+/** turn 被取消 → 通知。 */
+export function renderAbortedNotice(info: TurnEndInfo): EmailNotice {
+  return {
+    subject: `[DSH] 任务被取消 · 会话 ${shortSession(info.sessionId)}`,
+    text: header('任务被用户取消', info),
+  }
+}

package/src/triggers/types.ts

@@ -0,0 +1,40 @@
+/**
+ * 触发器契约：第三方插件经 ctx.notifyEmail.registerTrigger() 注册，
+ * 返回 undefined 表示「不关心该观察」；首个非空产物被投递。
+ * 内置官方适配器（decision/turn-end）也经同一接口注册，无特权路径。
+ * @module notify-email/triggers/types
+ */
+
+/** 一封待投递通知：触发器的产出。 */
+export interface EmailNotice {
+  subject: string
+  text: string
+  html?: string
+}
+
+/** 决策类观察：工具调用即将阻塞等待用户（tools/pre-execute 观察点，参数已校验）。 */
+export interface DecisionCall {
+  callId: string
+  sessionId: string
+  name: string
+  args: Record<string, unknown>
+}
+
+/** 任务停止类观察：runtime root agent 的 turn 结束且空闲防抖后。 */
+export interface TurnEndInfo {
+  sessionId: string
+  turn: number
+  /** turn/end reason.kind：completed | error | aborted（其余 kind 不下发）。 */
+  kind: string
+  errorMessage?: string
+  /** 该会话最后一条 assistant 消息的文本内容。 */
+  lastDelivery?: string
+}
+
+export interface NotifyTrigger {
+  readonly id: string
+  /** 决策类通知：返回 undefined 跳过。 */
+  onDecision?(call: DecisionCall): EmailNotice | undefined
+  /** 任务停止类通知：返回 undefined 跳过。 */
+  onTurnEnd?(info: TurnEndInfo): EmailNotice | undefined
+}