@telosmaylx/dsh-session-notify 0.1.0

package/lib/core.js

@@ -0,0 +1,303 @@
+/**
+ * dsh-session-complete-notify —— 纯逻辑层（零外部依赖，可独立测试）。
+ *
+ * 职责：
+ *  - 轮次计时/用量跟踪（turn/start 起表，assistant/message 累计 token）
+ *  - 会话完成系统消息的文案构建（summary 一行 + content 全文）
+ */
+
+/** 语言代码（设置面板可选值）。 */
+export const LANGUAGES = ['zh', 'zh-tw', 'en', 'ja', 'ko']
+
+/**
+ * 各语言文案表：reason 标签 + 通用标签 + 分隔符/用时/消耗措辞。
+ * 键为 LANGUAGES 中的代码；缺省回落 zh。
+ */
+const LABELS = {
+  zh: { completed: '会话已完成', aborted: '会话已中止', blocked: '会话被阻塞', error: '会话出错', 'max-tokens': '会话达到输出上限', interrupted: '会话已中断', generic: '会话已结束', sep: '：', dur: '用时', use: '消耗' },
+  'zh-tw': { completed: '會話已完成', aborted: '會話已中止', blocked: '會話被阻塞', error: '會話出錯', 'max-tokens': '會話達到輸出上限', interrupted: '會話已中斷', generic: '會話已結束', sep: '：', dur: '用時', use: '消耗' },
+  en: { completed: 'Session completed', aborted: 'Session aborted', blocked: 'Session blocked', error: 'Session failed', 'max-tokens': 'Session hit the output-token cap', interrupted: 'Session interrupted', generic: 'Session ended', sep: ': ', dur: 'took', use: 'used' },
+  ja: { completed: 'セッション完了', aborted: 'セッション中止', blocked: 'セッションがブロックされました', error: 'セッションエラー', 'max-tokens': '出力トークン上限に到達', interrupted: 'セッションが中断されました', generic: 'セッション終了', sep: '：', dur: '所要', use: '消費' },
+  ko: { completed: '세션 완료', aborted: '세션 중단됨', blocked: '세션 차단됨', error: '세션 오류', 'max-tokens': '출력 토큰 한도 도달', interrupted: '세션 중단됨', generic: '세션 종료', sep: ': ', dur: '소요', use: '소모' },
+}
+
+function tableFor(language) {
+  return LABELS[language] || LABELS.zh
+}
+
+/**
+ * 按语言取 reason 标签。
+ * @param {string} kind
+ * @param {string} language - LANGUAGES 之一
+ * @returns {string}
+ */
+export function labelFor(kind, language = 'zh') {
+  return tableFor(language)[kind] ?? tableFor(language).generic
+}
+
+/**
+ * 判断一个会话是否为子代理会话（子代理由父会话编排，通常不需要逐轮提醒）。
+ * @param {{ header?: { origin?: string; delegationDepth?: number } }} session
+ * @returns {boolean}
+ */
+export function isSubagentSession(session) {
+  const header = session?.header ?? {}
+  return header.origin === 'subagent' || (header.delegationDepth ?? 0) > 0
+}
+
+/**
+ * 每个（会话, 轮次）的进行时状态：开始时间 + 累计 token 用量。
+ * key 约定：`${sessionId}:${turn}`。
+ */
+export function createTurnTracker() {
+  const turns = new Map()
+  return {
+    /** turn/start：起表。 */
+    start(key, time) {
+      turns.set(key, { startedAt: time, usage: null })
+    },
+    /** assistant/message：一步的 usage 并入轮次累计。 */
+    addUsage(key, usage) {
+      const state = turns.get(key)
+      if (!state || !usage) return
+      state.usage = state.usage ? addTokenUsage(state.usage, usage) : { ...usage }
+    },
+    /** turn/end：读取并清除。缺起表（如恢复日志边界）时以 end 时间作答。 */
+    end(key, time) {
+      const state = turns.get(key)
+      turns.delete(key)
+      return {
+        startedAt: state?.startedAt ?? time,
+        endedAt: time,
+        usage: state?.usage ?? null,
+      }
+    },
+  }
+}
+
+/** 合并两次 token 用量（字段按需相加，缺失字段保持缺席）。 */
+function addTokenUsage(a, b) {
+  const sum = (x, y) => (Number.isFinite(x) ? x : 0) + (Number.isFinite(y) ? y : 0)
+  const merged = {
+    inputTokens: sum(a.inputTokens, b.inputTokens),
+    outputTokens: sum(a.outputTokens, b.outputTokens),
+  }
+  if (a.cacheReadTokens != null || b.cacheReadTokens != null) merged.cacheReadTokens = sum(a.cacheReadTokens, b.cacheReadTokens)
+  if (a.cacheWriteTokens != null || b.cacheWriteTokens != null) merged.cacheWriteTokens = sum(a.cacheWriteTokens, b.cacheWriteTokens)
+  if (a.reasoningTokens != null || b.reasoningTokens != null) merged.reasoningTokens = sum(a.reasoningTokens, b.reasoningTokens)
+  return merged
+}
+
+/**
+ * 人类可读时长：zh/zh-tw `12 秒` `3 分 25 秒`；en `12s` `3m25s`；
+ * ja `12 秒` `3 分 25 秒` `1 時間 4 分`；ko `12초` `3분 25초` `1시간 4분`。
+ * @param {number} ms
+ * @param {string} [language]
+ * @returns {string}
+ */
+export function formatDuration(ms, language = 'zh') {
+  const totalSeconds = Math.max(0, Math.round(ms / 1000))
+  const lang = LABELS[language] ? language : 'zh'
+  if (lang === 'en') {
+    if (totalSeconds < 60) return `${totalSeconds}s`
+    const minutes = Math.floor(totalSeconds / 60)
+    const seconds = totalSeconds % 60
+    if (minutes < 60) return seconds ? `${minutes}m${seconds}s` : `${minutes}m`
+    return `${Math.floor(minutes / 60)}h${minutes % 60}m`
+  }
+  if (lang === 'ja') {
+    if (totalSeconds < 60) return `${totalSeconds} 秒`
+    const minutes = Math.floor(totalSeconds / 60)
+    const seconds = totalSeconds % 60
+    if (minutes < 60) return seconds ? `${minutes} 分 ${seconds} 秒` : `${minutes} 分`
+    return `${Math.floor(minutes / 60)} 時間 ${minutes % 60} 分`
+  }
+  if (lang === 'ko') {
+    if (totalSeconds < 60) return `${totalSeconds}초`
+    const minutes = Math.floor(totalSeconds / 60)
+    const seconds = totalSeconds % 60
+    if (minutes < 60) return seconds ? `${minutes}분 ${seconds}초` : `${minutes}분`
+    return `${Math.floor(minutes / 60)}시간 ${minutes % 60}분`
+  }
+  // zh / zh-tw
+  if (totalSeconds < 60) return `${totalSeconds} 秒`
+  const minutes = Math.floor(totalSeconds / 60)
+  const seconds = totalSeconds % 60
+  if (minutes < 60) return seconds ? `${minutes} 分 ${seconds} 秒` : `${minutes} 分钟`
+  const hours = Math.floor(minutes / 60)
+  return `${hours} 小时 ${minutes % 60} 分`
+}
+
+/**
+ * 用量一行：zh/zh-tw `1,240 輸入 / 3,560 輸出`；en `1,240 in / 3,560 out`；
+ * ja `1,240 入力 / 3,560 出力`；ko `1,240 입력 / 3,560 출력`（不带 tokens 单位后缀）。
+ * 输入 = 未缓存 + 缓存读 + 缓存写。
+ * @param {{ inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number }} usage
+ * @param {string} [language]
+ * @returns {string | null}
+ */
+export function summarizeUsage(usage, language = 'zh') {
+  if (!usage) return null
+  const input = (usage.inputTokens ?? 0) + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0)
+  const output = usage.outputTokens ?? 0
+  const fmt = (n) => n.toLocaleString('en-US')
+  const lang = LABELS[language] ? language : 'zh'
+  const iw = { zh: '输入', 'zh-tw': '輸入', en: 'in', ja: '入力', ko: '입력' }[lang]
+  const ow = { zh: '输出', 'zh-tw': '輸出', en: 'out', ja: '出力', ko: '출력' }[lang]
+  return `${fmt(input)} ${iw} / ${fmt(output)} ${ow}`
+}
+
+/**
+ * 缓存命中率：缓存读 token /（未缓存输入 + 缓存读 + 缓存写）——无缓存数据返回空串。
+ * @param {{ inputTokens?: number; outputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number }} usage
+ * @returns {string}
+ */
+export function summarizeCache(usage) {
+  if (!usage) return ''
+  const read = usage.cacheReadTokens ?? 0
+  const write = usage.cacheWriteTokens ?? 0
+  const plain = usage.inputTokens ?? 0
+  const total = plain + read + write
+  if (!(total > 0)) return ''
+  const pct = Math.round((read / total) * 1000) / 10
+  return `${pct}%`
+}
+
+/**
+ * 缓存命中率（官方 tokenUsage 投影口径，四桶不重叠）：
+ * 缓存读 /（未缓存输入 + 缓存读 + 缓存写）——与 dsh-web-ui 同源。
+ * @param {{ uncachedInputTokens?: number; cacheReadTokens?: number; cacheWriteTokens?: number }} usage
+ * @returns {string}
+ */
+export function officialCacheRate(usage) {
+  if (!usage) return ''
+  const read = usage.cacheReadTokens ?? 0
+  const total = (usage.uncachedInputTokens ?? 0) + read + (usage.cacheWriteTokens ?? 0)
+  if (!(total > 0)) return ''
+  return `${Math.round((read / total) * 1000) / 10}%`
+}
+
+/**
+ * 生成速度（官方 sessionStats 投影口径）：输出 token ÷ 解码耗时（tok/s）——
+ * 与 dsh-web-ui 状态栏同口径（不含排队/准备/工具时间）。
+ * @param {{ decodeTokens?: number; decodeMs?: number }} stats
+ * @returns {string}
+ */
+export function officialTps(stats) {
+  if (!stats || !(stats.decodeMs > 0)) return ''
+  return `${Math.round((stats.decodeTokens ?? 0) / (stats.decodeMs / 1000))} tok/s`
+}
+
+/**
+ * 生成速度：输出 token / 用时秒（tok/s）——无数据返回空串。
+ * @param {{ outputTokens?: number }} usage
+ * @param {number} ms
+ * @returns {string}
+ */
+export function tpsOf(usage, ms) {
+  if (!usage || !(ms > 0)) return ''
+  const output = usage.outputTokens ?? 0
+  return `${Math.round(output / (ms / 1000))} tok/s`
+}
+
+/**
+ * 构建系统消息：可折叠行的 summary（= 正文渲染结果的截断，≤120 字符）
+ * + 展开/模型可见的全文。
+ *
+ * @param {string} kind - turn/end 的 reason.kind。
+ * @param {{ error?: { message?: string } } | undefined} reasonData
+ * @param {{ startedAt: number; endedAt: number; usage?: object | null; includeDuration?: boolean; includeUsage?: boolean; cacheValue?: string; tpsValue?: string; titleValue?: string }} info
+ * @param {{ language?: 'zh' | 'en'; templates?: Record<string, string> }} [custom] -
+ *   language 切换文案语言；templates[reason] 非空时作为正文模板，
+ *   支持占位符：{label} {title} {duration} {usage} {error} {cache} {tps}。
+ * @returns {{ summary: string; text: string }}
+ */
+export function buildNotice(kind, reasonData, { startedAt, endedAt, usage = null, includeDuration = true, includeUsage = true, cacheValue, tpsValue, titleValue }, custom = {}) {
+  const language = LABELS[custom.language] ? custom.language : 'zh'
+  const L = tableFor(language)
+  const templates = custom.templates ?? {}
+  const label = labelFor(kind, language)
+  const detail = detailFor(reasonData, language)
+  let summary = `${label}${detail}`
+  const durationLine = includeDuration ? formatDuration(endedAt - startedAt, language) : null
+  const usageLine = includeUsage ? summarizeUsage(usage, language) : null
+  // 缓存命中/速度：优先官方投影口径（调用方传入），无则退回用量聚合估算
+  const cacheLine = typeof cacheValue === 'string' ? cacheValue : (includeUsage ? summarizeCache(usage) : '')
+  const tpsLine = typeof tpsValue === 'string' ? tpsValue : (includeUsage ? tpsOf(usage, endedAt - startedAt) : '')
+  const parts = []
+  if (durationLine) parts.push(`${L.dur} ${durationLine}`)
+  if (usageLine) parts.push(`${L.use} ${usageLine}`)
+  const suffix = parts.length ? `（${parts.join('，')}）` : ''
+  const template = templates[kind]
+  let text
+  if (typeof template === 'string' && template.trim() !== '') {
+    // 自定义模板：占位符替换，保持 summary 与正文一致的语义
+    text = renderTemplate(template, {
+      label,
+      duration: durationLine ?? '',
+      usage: usageLine ?? '',
+      error: plainError(reasonData) || 'none', // 无报错时显示 none，而非空串
+      cache: cacheLine,
+      tps: tpsLine,
+      title: typeof titleValue === 'string' ? titleValue : '',
+    })
+  } else if (language === 'en') {
+    text = `${summary}${suffix ? ` (${parts.join(', ')}).` : '.'}`
+  } else if (language === 'ja') {
+    text = `${summary}${suffix ? `（${parts.join('、')}）。` : '。'}`
+  } else if (language === 'ko') {
+    text = `${summary}${suffix ? `（${parts.join(', ')}）。` : '。'}`
+  } else {
+    text = `${summary}${suffix}。`
+  }
+  return {
+    // 折叠行 summary 与正文同源：自定义模板（含 {title}）与默认文案都展示
+    // 渲染结果（截断至 120 字符）——只看折叠行的用户必须能看见真实标题与
+    // 用时/消耗，否则会误以为 {title} 没有生效（历史教训：summary 只放标签
+    // 「会话已完成」，用户展开前完全看不到内容）。
+    summary: bound(text, 120),
+    text,
+  }
+}
+
+/**
+ * 模板占位符替换：{label} 已全面移除（模板中直接剥除）；支持 {duration} {usage} {error} {cache} {tps}。
+ * @param {string} template
+ * @param {{ label: string; duration: string; usage: string; error: string; cache: string; tps: string }} vars
+ * @returns {string}
+ */
+export function renderTemplate(template, vars) {
+  return String(template)
+    .replace(/\{label\}/g, '')
+    .replaceAll('{title}', vars.title ?? '')
+    .replaceAll('{duration}', vars.duration)
+    .replaceAll('{usage}', vars.usage)
+    .replaceAll('{error}', vars.error)
+    .replaceAll('{cache}', vars.cache)
+    .replaceAll('{tps}', vars.tps)
+}
+
+/** error reason 的纯文本详情（单行、截断；无则空串）。 */
+function plainError(reasonData) {
+  const message = reasonData?.error?.message
+  if (!message) return ''
+  const flat = String(message).replace(/[\r\n]+/g, ' ').trim()
+  return flat.length > 80 ? `${flat.slice(0, 80)}…` : flat
+}
+
+/** error reason 的错误详情（单行、截断，分隔符随语言）。 */
+function detailFor(reasonData, language = 'zh') {
+  const message = reasonData?.error?.message
+  if (!message) return ''
+  const flat = String(message).replace(/[\r\n]+/g, ' ').trim()
+  if (!flat) return ''
+  const sep = tableFor(language).sep
+  return `${sep}${flat.length > 40 ? `${flat.slice(0, 40)}…` : flat}`
+}
+
+/** 按字符数截断（≤ max）。 */
+function bound(text, max) {
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text
+}
+
+export const __internals = { LABELS, addTokenUsage, detailFor, bound }

package/lib/index.js

@@ -0,0 +1,291 @@
+/**
+ * dsh-session-complete-notify：会话完成系统消息提醒插件（host 平面）。
+ *
+ * 原理：订阅 session/event 火线——
+ *   - turn/start   记下轮次开始时间；
+ *   - assistant/message 累加该轮 token 用量；
+ *   - turn/end     按 reason.kind（completed/aborted/blocked/error/max-tokens）
+ *     组装一条系统消息，并以 plugin-source 的 user/message（form: 'notice'）
+ *     追加进会话日志：Web UI 把它渲染为可折叠的系统提示行（醒目提醒用户），
+ *     并随 JSONL 持久化，恢复/回放后依然可见。
+ *
+ * 设计取舍：
+ *   - 只响应「实时」事件：resume/replay 不会重放旧通知，不会在加载会话时刷屏；
+ *   - 追加的事件类型是 user/message，与自身监听目标（turn/*）不相交，
+ *     天然免疫自我循环；
+ *   - 零外部 import（@deepseek-ai/* 无法从本仓库目录解析），
+ *     UserMessage 对象按 dsh-llm 的 createUserMessage 契约手工构造
+ *     （id = crypto.randomUUID()，deep-freeze 由 session.append 的
+ *     adoptSessionEvent 快照阶段完成）。
+ *
+ * 装配（cordis.patch.yml 或 dsh plugin add）：
+ *   - id: session-complete-notify
+ *     name: '@telosmaylx/dsh-session-notify'
+ *     config:
+ *       reasons: [completed, aborted, blocked, error, max-tokens]
+ *       skipSubagents: true
+ *       includeDuration: true
+ *       includeUsage: true
+ */
+
+import { appendFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { createRequire } from 'node:module'
+import { createTurnTracker, buildNotice, isSubagentSession, officialCacheRate, officialTps } from './core.js?v=1' // v=1: 缓存破坏——HMR 重载按 URL 键控
+
+/** Cordis loader 诊断用插件名。 */
+export const name = 'session-complete-notify'
+
+/** 系统消息 source.plugin 标识（UI 按插件名着色/标注来源）。 */
+const PLUGIN_ID = 'dsh-session-notify'
+
+/** 设置命名空间（官方「设置 → 插件」面板的键）。 */
+const SETTINGS_NS = 'session-complete-notify'
+
+/**
+ * 本插件从仓库目录以 realpath 加载，裸导入（@deepseek-ai/*）无法解析；
+ * 用 createRequire 锚定 profile 共享依赖枢纽（.dsh/profiles/node_modules），
+ * 取到与宿主同源（realpath 相同）的 schemastery 实例来构造设置 schema。
+ */
+const HUB_REQUIRE = createRequire(join(homedir(), '.dsh', 'profiles', 'node_modules', '__scn_anchor__.js'))
+
+/** 默认配置。 */
+const DEFAULT_OPTIONS = {
+  /**
+   * 触发提醒的 turn/end reason 白名单。默认排除 interrupted
+   * （崩溃恢复后由持久化后端补写的孤儿轮次关闭标记，用户视角的“完成”不含它）。
+   */
+  reasons: ['completed', 'aborted', 'blocked', 'error', 'max-tokens'],
+  /** 跳过子代理会话：子孙会话由父会话编排，逐轮提醒是噪音。 */
+  skipSubagents: true,
+  /** 系统消息附带轮次用时。 */
+  includeDuration: true,
+  /** 系统消息附带 token 用量。 */
+  includeUsage: true,
+}
+
+/** 设置面板可见字段的默认值（与 Config 同构；仓库里的 schema 默认值与此一致）。 */
+const DEFAULT_SETTINGS = {
+  language: 'zh',
+  templates: { completed: '', error: '', aborted: '', blocked: '', 'max-tokens': '' },
+  titleTemplate: '',
+  includeDuration: true,
+  includeUsage: true,
+  skipSubagents: true,
+}
+
+/** 从任意输入规整为设置形状（容忍缺失/多余字段）。 */
+function sanitizeSettings(raw) {
+  const src = raw && typeof raw === 'object' ? raw : {}
+  const templatesRaw = src.templates && typeof src.templates === 'object' ? src.templates : {}
+  const templates = { ...DEFAULT_SETTINGS.templates }
+  for (const key of Object.keys(templates)) {
+    if (typeof templatesRaw[key] === 'string') templates[key] = templatesRaw[key]
+  }
+  return {
+    language: ['zh', 'zh-tw', 'en', 'ja', 'ko'].includes(src.language) ? src.language : 'zh',
+    templates,
+    titleTemplate: typeof src.titleTemplate === 'string' ? src.titleTemplate : '',
+    includeDuration: typeof src.includeDuration === 'boolean' ? src.includeDuration : true,
+    includeUsage: typeof src.includeUsage === 'boolean' ? src.includeUsage : true,
+    skipSubagents: typeof src.skipSubagents === 'boolean' ? src.skipSubagents : true,
+  }
+}
+
+/**
+ * 插件入口。
+ * @param {import('cordis').Context} ctx
+ * @param {Partial<typeof DEFAULT_OPTIONS>} [config]
+ */
+export const inject = ['settings']
+
+export function apply(ctx, config = {}) {
+  const options = { ...DEFAULT_OPTIONS, ...config }
+  const reasons = new Set(Array.isArray(options.reasons) ? options.reasons : DEFAULT_OPTIONS.reasons)
+  const tracker = createTurnTracker()
+  let settings = DEFAULT_SETTINGS
+  let projRegistry = null // sessionProjections 服务（非注入可选依赖，经 ctx.inject 捕获）
+
+  // 官方设置命名空间：设置面板（设置 → 插件）可编辑；user 层持久化在 settings 文档。
+  // 重试兜底：热重载时旧 fiber 注销与新 fiber 注册存在竞态，register 可能因
+  // duplicate 被拒——短暂重试直至成功（生产无重载时一次即中）。
+  try {
+    const Schema = HUB_REQUIRE('@deepseek-ai/schemastery')
+    const schema = Schema.object({
+      language: Schema.union(['zh', 'zh-tw', 'en', 'ja', 'ko']).default('zh'),
+      templates: Schema.object({
+        completed: Schema.string().default(''),
+        error: Schema.string().default(''),
+        aborted: Schema.string().default(''),
+        blocked: Schema.string().default(''),
+        'max-tokens': Schema.string().default(''),
+      }),
+      titleTemplate: Schema.string().default(''),
+      includeDuration: Schema.boolean().default(true),
+      includeUsage: Schema.boolean().default(true),
+      skipSubagents: Schema.boolean().default(true),
+    })
+    let attempts = 0
+    const tryRegister = () => {
+      try {
+        const scope = ctx.settings.register(SETTINGS_NS, schema, { applies: 'live' })
+        settings = sanitizeSettings(scope.get())
+        scope.watch((next) => {
+          settings = sanitizeSettings(next)
+          fileLog(`settings updated: ${JSON.stringify({ language: settings.language, templates: Object.fromEntries(Object.entries(settings.templates).filter(([, v]) => v)) })}`)
+        })
+        fileLog('settings namespace registered')
+      } catch (err) {
+        if (attempts < 8) {
+          attempts += 1
+          setTimeout(tryRegister, 400 * attempts)
+          fileLog(`settings register retry ${attempts}: ${err?.message ?? err}`)
+        } else {
+          warn(ctx, `设置命名空间注册失败（使用默认值）: ${err?.message ?? err}`)
+          fileLog(`settings register FAILED after ${attempts} attempts: ${err?.message ?? err}`)
+        }
+      }
+    }
+    tryRegister()
+  } catch (err) {
+    warn(ctx, `设置依赖加载失败: ${err?.message ?? err}`)
+    fileLog(`settings deps load FAILED: ${err?.message ?? err}`)
+  }
+
+  // 会话投影：把每个会话「最近的系统消息全文」注册为一个投影单元（key =
+  // session-complete-notify）。宿主会对**所有会话**（含后台/未打开窗口的）
+  // 推送该值 → 客户端推送正文因此跨会话一致，不再依赖事件窗口是否打开。
+  try {
+    const z = HUB_REQUIRE('zod')
+    if (typeof ctx.inject === 'function') {
+      ctx.inject(['sessionProjections'], (scoped) => {
+        // 说明：注入器（dsh-super-injector）为插件提供的是二级上下文的注册表
+        // 实例，与 host 对客户端推送/列表快照所用的实例可能不同；优先取
+        // ctx.root.get（最靠近宿主根的一份），拿不到时回退注入实例。
+        // 只注册进注入实例时，客户端可能读不到本投影单元 → 后台会话推送正文
+        // 走降级路径（详情见会话内系统消息），属尽力而为，不影响会话内系统消息。
+        const rootRegistry = (typeof ctx.root?.get === 'function' && ctx.root.get('sessionProjections')) || scoped.sessionProjections
+        projRegistry = rootRegistry
+        try {
+          rootRegistry.register({
+            key: SETTINGS_NS,
+            schema: z.string(),
+            init: () => '',
+            apply: (state, event) => {
+              if (event.type !== 'user/message') return state
+              const src = event.data?.source ?? {}
+              if (src.kind !== 'plugin' || src.plugin !== PLUGIN_ID) return state
+              const text = ((event.data?.content ?? []).map((b) => b?.text ?? '')).join('').trim()
+              return text || state
+            },
+            view: (state) => state,
+            stateVersion: 1,
+          })
+          fileLog('session-projections unit registered (key=session-complete-notify)')
+        } catch (err) {
+          warn(ctx, `投影单元注册失败: ${err?.message ?? err}`)
+        }
+      })
+    }
+  } catch (err) {
+    warn(ctx, `投影依赖加载失败: ${err?.message ?? err}`)
+  }
+
+  ctx.on('session/event', (session, event) => {
+    switch (event.type) {
+      case 'turn/start':
+        tracker.start(`${session.id}:${event.data.turn}`, event.time)
+        return
+      case 'assistant/message':
+        tracker.addUsage(`${session.id}:${event.data.turn}`, event.data.usage)
+        return
+      case 'turn/end': {
+        const key = `${session.id}:${event.data.turn}`
+        const state = tracker.end(key, event.time)
+        const kind = event.data.reason?.kind
+        if (!reasons.has(kind)) return
+        if (isSubagentSession(session)) return // 默认跳过子代理会话（子代理由父会话编排）
+        // 官方投影口径：tokenUsage（缓存命中率）+ sessionStats（tok/s 生成速度）
+        // 与 dsh-web-ui 状态栏同源；投影由宿主维护，无插件内存状态，重载也不丢。
+        // 用户以「标签是否插入」控制显示（用量/用时无独立开关）。
+        let cacheValue
+        let tpsValue
+        let titleValue = ''
+        try {
+          if (projRegistry) {
+            const snap = projRegistry.snapshot(session)
+            const usage = snap?.values?.tokenUsage
+            const stats = snap?.values?.sessionStats
+            cacheValue = officialCacheRate(usage)
+            tpsValue = officialTps(stats)
+            titleValue = typeof snap?.values?.title === 'string' ? snap.values.title : ''
+          }
+        } catch (projErr) {
+          warn(ctx, `投影快照读取失败: ${projErr?.message ?? projErr}`)
+        }
+        const notice = buildNotice(kind, event.data.reason, {
+          ...state,
+          includeDuration: true, // 标签即开关：{duration} 插了才显示
+          includeUsage: true, // 标签即开关：{usage}/{cache}/{tps} 插了才显示
+          cacheValue,
+          tpsValue,
+          titleValue,
+        }, { language: settings.language, templates: settings.templates })
+        // 边界约束：session/event 观察者回调运行在 turn/end 那次 append 的
+        // 发布边界之内（dsh-session 在 dispatch 前 set entry.appending，
+        // finally 中复位），此时同步 append 会被拒绝：
+        //   "session append cannot reenter while another append is being published"
+        // 推迟到微任务——微任务队列在本次同步栈（含 finally 复位）之后才跑。
+        queueMicrotask(() => appendNotice(ctx, session, notice))
+        return
+      }
+      default:
+        return
+    }
+  })
+}
+
+/** 把系统消息追加进会话日志（失败只记日志，绝不抛出破坏 event 火线）。 */
+function appendNotice(ctx, session, notice) {
+  try {
+    session.append(
+      'user/message',
+      {
+        id: newId(),
+        role: 'user',
+        content: [{ type: 'text', text: notice.text }],
+        source: { kind: 'plugin', plugin: PLUGIN_ID, form: 'notice', summary: notice.summary },
+      },
+      { surfaceOp: 'append' },
+    )
+  } catch (err) {
+    warn(ctx, `追加系统消息失败: ${err?.message ?? String(err)}`)
+    fileLog(`追加失败 ${session.id}: ${err?.stack ?? err}`)
+  }
+}
+
+/** 追加失败时落一个调试文件（~/.dsh/session-complete-notify.log），便于排查。 */
+function fileLog(line) {
+  try {
+    appendFileSync(join(homedir(), '.dsh', 'session-complete-notify.log'), `${new Date().toISOString()} ${line}\n`, 'utf8')
+  } catch {
+    /* 尽力而为 */
+  }
+}
+
+/** crypto.randomUUID（Node 18+ 全局存在；旧环境回退到时间戳+随机）。 */
+function newId() {
+  return globalThis.crypto?.randomUUID?.() ?? `n-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+}
+
+/** 日志上报（ctx.logger 缺失时落到 console.warn）。 */
+function warn(ctx, message) {
+  try {
+    const logger = ctx.logger
+    if (logger && typeof logger.warn === 'function') logger.warn(`[${PLUGIN_ID}] ${message}`)
+    else console.warn(`[${PLUGIN_ID}] ${message}`)
+  } catch {
+    /* 上报是尽力而为 */
+  }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@telosmaylx/dsh-session-notify",
+  "version": "0.1.0",
+  "description": "DSH session completion notifier: appends a plugin system message to the session log on turn/end and pushes browser notifications (Web Notification + toast), with a fully customizable official settings panel (presets, 5-language templates, cache-hit rate & tok/s from official projections).",
+  "private": false,
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./core": {
+      "default": "./lib/core.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "session-notify",
+    "notification",
+    "completion-reminder",
+    "agent"
+  ],
+  "author": "dsh-session-notify contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TelosmaYLX/dsh-session-notify.git"
+  },
+  "homepage": "https://github.com/TelosmaYLX/dsh-session-notify#readme",
+  "bugs": {
+    "url": "https://github.com/TelosmaYLX/dsh-session-notify/issues"
+  },
+  "peerDependencies": {
+    "cordis": ">=4.0.0-rc <5"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "bash scripts/build.sh || node --check lib/index.js && node --check lib/core.js && node --check lib/client.js",
+    "prepublishOnly": "node --check lib/index.js && node --check lib/core.js && node --check lib/client.js"
+  }
+}

package/scripts/build.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Build dsh-session-complete-notify: the plugin is hand-written zero-dependency
+# ESM — no tsc step, just syntax-verify the shipped libs.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+if [ ! -f lib/index.js ] || [ ! -f lib/core.js ]; then
+  echo "build: lib/index.js or lib/core.js missing" >&2
+  exit 1
+fi
+
+node --check lib/index.js
+node --check lib/core.js
+echo "=== Build complete (lib verified, ${PWD}) ==="