@mzzsfy/dsh-turn-notify 0.12.0 → 0.12.2

package/README.md

@@ -152,7 +152,7 @@ turn-notify:
 
 按数据流向分五步:
 
-1. **事件监听**:host 观察 `session/event`(回合结束、ask_user_question 工具调用与 assistant 消息)与 `approval/request` 审批请求(只观察,不拦截)。回合结束原因逐一映射:正常结束归任务完成,错误与手动停止归任务出错,审批拦截归等待审批,输出触顶归达到上限,会话收尾补发的中断归被中断;assistant 消息流经途累积回合小结(tokens 与回答前缀),回合结束随通知消费。
+1. **事件监听**:host 观察 `session/event`(回合结束、ask_user_question 工具调用与 assistant 消息)、`approval/asked` 审批事件(审批通知唯一信号:生产者先 append 后发 waterfall,会话事件流恒先达且不依赖应答方放行)。回合结束原因逐一映射:正常结束归任务完成,错误与手动停止归任务出错,审批拦截归等待审批,输出触顶归达到上限,会话收尾补发的中断归被中断;assistant 消息流经途累积回合小结(tokens 与回答前缀),回合结束随通知消费。
 2. **分类与过滤**:事件归入六类,经子代理会话、子代理相关静默(仅任务完成类)、最短回合时长三道过滤,通过即产生一条通知,并按 kindRoutes 裁定放行通道。
 3. **host 直发通道**:webhook、IM 与宿主桌面通知由 host 进程直接投递(经路由名单过滤),不依赖浏览器;宿主通知按浏览器在场(在途长轮询,来源不限本机)浏览器优先去重,离场补位;同时通知写入内存队列(环形 20 条,60 秒过期,不落盘),路由名单随单元下发。
 4. **浏览器通道**:各窗口以长轮询挂起在该队列上(cursor 续传,事件与配置变更即时唤醒,空闲期单次挂起至多数十秒,失败指数退避重连),localStorage 协调保证同一通知只有一个窗口呈现,再按本机偏好与路由名单分发到声音/系统弹窗/页内提示;等待用户动作的审批与提问超时未处理时补发一轮提醒。
@@ -192,4 +192,10 @@ node scripts/dev-link.mjs dsh-turn-notify   # 仓库根执行:归一 profile 依
 
 ## dsh 版本兼容
 
-三版本全部通过:通知开关与播报形态、激活 live。0.1.6 控件数 13→19 属宿主演进,不构成不兼容。
+- 0.2.0-rc.2:完全适配(装载 + 功能面逐格验证通过)
+- 0.1.7-rc.2:不崩溃底线通过(全家桶 crash-only)
+- 0.1.5-rc.3:未承诺(仅 shell-select 有宿主要求豁免;全家桶在该版本不启动,详见仓库 docs/兼容性测试/逐包测试进度.md)
+
+历史验收(Round 30,2026-09-27):0.1.7-rc.2 完全适配(设置 HTTP 写读闭环 deepMerge 语义 + 「消息通知」分区事件芯片渲染;11/11 判定面);0.1.5-rc.3 曾判不崩溃底线通过(已被 2026-09-30 复测推翻,见上);历史窗口 0.1.2-rc.1 全格通过(四 tab 计数/事件开关/音效卡试听/IM 自洽)。0.1.6 控件数 13→19 属宿主演进,不构成不兼容。
+
+更细的逐包结论见仓库 `docs/兼容性测试/逐包测试进度.md` 与本包 `兼容性测试.md`。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-turn-notify",
   "description": "消息通知:六类回合事件送达声音、系统弹窗、页内提示、webhook、IM 与宿主桌面通知;内置八种合成音色,自定义音效,按事件分类指定;多窗口只响一次",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/core.mjs

@@ -87,6 +87,11 @@ const IM_TARGET_ID_PATTERN = /^[A-Za-z0-9._:@-]{1,128}$/
 export const isValidImBotId = (value) => typeof value === 'string' && IM_BOT_ID_PATTERN.test(value)
 
 const TURN_END_KIND = 'turn/end'
+// 审批请求的会话事件类型(DSH SessionEventMap 官方定义:
+//   'approval/asked': { id; toolName; callId?; reason? })。
+// 审批通知唯一信号:生产者(dsh-user-approval request)先 append 后发 waterfall,
+// 会话事件流恒先达且不依赖应答方放行;approval/request waterfall 只读不可靠,不作信号源。
+export const APPROVAL_ASKED_KIND = 'approval/asked'
 
 // turn/end reason.kind 到通知分类的映射;未知 kind(插件可扩展)返回 null。
 const REASON_KIND_TO_CATEGORY = {
@@ -103,6 +108,7 @@ export function mapEventToCategory(type, data) {
     const kind = data && data.reason && data.reason.kind
     return Object.prototype.hasOwnProperty.call(REASON_KIND_TO_CATEGORY, kind) ? REASON_KIND_TO_CATEGORY[kind] : null
   }
+  if (type === APPROVAL_ASKED_KIND) return CATEGORY_APPROVAL
   if (type === 'tool/call' && data && data.name === 'ask_user_question') return CATEGORY_ASK
   return null
 }
@@ -468,14 +474,6 @@ export function readRawBody(req, maxBytes) {
   })
 }
 
-// 审批观察器包装:notify 异步投递,next() 同步立即放行,不阻塞 waterfall。
-export function createApprovalTap(notify, schedule) {
-  return function approvalTap(_req, next) {
-    schedule(() => notify({ category: CATEGORY_APPROVAL }))
-    return next()
-  }
-}
-
 // webhook 直发:未配置跳过;任何失败不抛出(fire-and-forget,不重试)。
 // 返回真实投递结果供测试按钮呈现,真实通知路径以 void 忽略。
 export async function sendWebhook({ url, payload, fetchImpl = fetch }) {

package/src/index.js

@@ -1,4 +1,4 @@
-// dsh-turn-notify Host 半区:回合通知单源决策。观察 session/event 与 approval/request,
+// dsh-turn-notify Host 半区:回合通知单源决策。观察 session/event,
 // 命中分类即发 webhook、写入内存投影;webServer 路由供浏览器半区轮询投影与管理音效。
 // 音效持久化在 ~/.dsh/dsh-turn-notify/sounds/,投影不落盘。
 
@@ -9,6 +9,7 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 import z from '@deepseek-ai/schemastery'
 import {
+  APPROVAL_ASKED_KIND,
   AUDIO_EXTS,
   CATEGORIES,
   CATEGORY_ASK,
@@ -21,7 +22,6 @@ import {
   buildWebhookPayload,
   collectAssistantTail,
   collectSessionEvents,
-  createApprovalTap,
   createProjection,
   isSubagent,
   isSubagentWakeTurn,
@@ -103,9 +103,51 @@ const SETTINGS_SCHEMA = z.object({
 })
 
 // 读侧归一交由 core 的 resolvedConfig:字段类型异常回退默认值,与写路径校验宽松度一致
-const readSettings = (ctx) => {
+const readSettings = (ctx, config) => {
   const settings = ctx.get('settings')
-  return resolvedConfig(settings ? settings.get(NAMESPACE) : undefined)
+  // 双形读(maintain 同构):legacy settings 命名空间 get;0.1.7+ apply 入参
+  // config 整节解包。方法面守卫兼防:服务在但缺 get 时回落默认配置,防路由 handler 抛错
+  return resolvedConfig(settings && typeof settings.get === 'function' ? settings.get(NAMESPACE) : unwrapVolatile(config))
+}
+
+// volatile ref 动态解包(get 协议):0.1.7 下 apply 入参 config 为整节单 ref;
+// legacy 宿主 config 为普通对象原样透传
+function unwrapVolatile(value) {
+  return typeof value?.get === 'function' ? value.get() : value
+}
+
+// 0.1.7 宿主以静态 Config 导出生成设置节表单(maintain 同构)。根级 volatile
+// 包装:整节 live 表单,节写经 loader 原地热更;旧宿主 schemastery 无 volatile
+// 方法,特性检测原样返回
+export const Config = typeof SETTINGS_SCHEMA.volatile === 'function' ? SETTINGS_SCHEMA.volatile() : SETTINGS_SCHEMA
+
+// 0.1.7 写路径:configEditor.edit 落 profile 条目(fiber.entry,与命名空间解耦)。
+// 嵌套补丁(enabled.{category}/soundMapping.{category})须深合并:浅展开会把未提交
+// 的兄弟分类键抹成 undefined;null 值原样落盘(清除语义,读侧 resolvedConfig 过滤)
+async function persistPatch(ctx, patch) {
+  const settings = ctx.get('settings')
+  // legacy 方法面以 register 为准(0.1.7 的 settings.update 名义在场但按命名
+  // 空间找条目必败,不可作判据)
+  if (typeof settings?.register === 'function' && typeof settings?.update === 'function') {
+    await settings.update(NAMESPACE, patch)
+    return
+  }
+  const editor = ctx.get('configEditor')
+  const entry = ctx.fiber?.entry
+  if (!editor || typeof editor.edit !== 'function' || !entry) throw new Error('settings 服务不可用')
+  await editor.edit(entry, (current) => deepMerge(current, patch))
+}
+
+function deepMerge(under, over) {
+  const out = { ...under }
+  for (const key of Object.keys(over)) {
+    const next = over[key]
+    const underValue = out[key]
+    const bothPlain = (next !== null && typeof next === 'object' && !Array.isArray(next))
+      && (underValue !== null && typeof underValue === 'object' && !Array.isArray(underValue))
+    out[key] = bothPlain ? deepMerge(underValue, next) : next
+  }
+  return out
 }
 
 function sendJson(res, status, payload) {
@@ -187,7 +229,7 @@ async function readSoundIndex() {
 const writeSoundIndex = (index) => writeFile(soundIndexPath, JSON.stringify(index))
 
 /** @param {import('@deepseek-ai/cordis').Context} ctx */
-export function apply(ctx) {
+export function apply(ctx, config) {
   const projection = createProjection({})
   // 打开回合:按会话 id 记回合序号与起始时间,回合结束即清;序号严格递增,
   // 供子代理注册归属判定,同毫秒内多回合不受时钟精度歧义影响
@@ -241,7 +283,7 @@ export function apply(ctx) {
 
   // durationMs 与 wakeTurn / awaitingChildren 由调用方在清理状态前读取后传入,防先删后读
   function notifyUnit({ category, kind, reasonKind, session, durationMs = null, wakeTurn = false, awaitingChildren = false }) {
-    const settings = readSettings(ctx)
+    const settings = readSettings(ctx, config)
     const header = session.header || {}
     const sessionId = String(session.id ?? '')
     if (!shouldNotify({ category, kind, durationMs, settings, header, wakeTurn, awaitingChildren })) return
@@ -404,21 +446,25 @@ export function apply(ctx) {
     const category = mapEventToCategory(event.type, event.data)
     if (category === null) return
     const reasonKind = event.type === TURN_END_KIND && event.data.reason ? event.data.reason.kind : null
-    // tool/call 的提问事件与 turn/end 分类共用入口;提问通知不受碎轮过滤
-    const kind = category === CATEGORY_ASK ? TOOL_CALL_KIND : TURN_END_KIND
+    // 即时送达类事件(tool/call 提问、approval/asked 审批)用自身 kind,
+    // 不落入 turn/end 的碎轮时长过滤;其余归类沿用 turn/end。
+    const kind = category === CATEGORY_ASK
+      ? TOOL_CALL_KIND
+      : category === CATEGORY_APPROVAL && event.type === APPROVAL_ASKED_KIND
+        ? APPROVAL_ASKED_KIND
+        : TURN_END_KIND
     notifyUnit({ category, kind, reasonKind, session, ...(endedTurn ?? {}) })
   })
 
-  // 审批 waterfall 观察者:next() 同步放行,通知异步投递
-  ctx.on('approval/request', createApprovalTap(
-    ({ category }) => {
-      // waterfall 请求不携带会话对象,标题与工作区留空,仅分类与时间有效
-      notifyUnit({ category, kind: 'approval/request', reasonKind: category, session: { header: {} } })
-    },
-    (fn) => { fn() },
-  ))
-
   ctx.inject(['settings'], (settingsCtx) => {
+    // 方法面守卫:settings 服务缺 register 面(0.1.7 已移除)即走新形态分支;
+    // 0.1.7 关闭原生自动设置页,设置面由本包自带分区承担(maintain 同构)
+    if (typeof settingsCtx.settings.register !== 'function') {
+      if (typeof settingsCtx.settings?.configure === 'function') {
+        settingsCtx.effect(() => settingsCtx.settings.configure({ auto: false }, ctx.fiber))
+      }
+      return
+    }
     settingsCtx.settings.register(NAMESPACE, SETTINGS_SCHEMA)
   })
 
@@ -471,7 +517,7 @@ export function apply(ctx) {
           if (query.has('cursor') && projection.version() === cursor) {
             await projection.wait(cursor, LONG_POLL_WAIT_MS)
           }
-          const settings = readSettings(ctx)
+          const settings = readSettings(ctx, config)
           sendJson(res, 200, { units: projection.list(), soundMapping: settings.soundMapping, version: projection.version() })
         } finally {
           if (releaseBrowserPoll !== null) releaseBrowserPoll()
@@ -602,15 +648,14 @@ export function apply(ctx) {
         await writeSoundIndex(index)
       }
       // 被引用即回落:深合并语义下引用置 null 清除,resolveSound 兜底回内置默认
-      const settings = ctx.get('settings')
-      if (settings) {
-        const current = readSettings(ctx)
+      if (ctx.get('settings')) {
+        const current = readSettings(ctx, config)
         const patch = {}
         for (const key of Object.keys(current.soundMapping)) {
           if (current.soundMapping[key] === id) patch[key] = null
         }
         if (Object.keys(patch).length > 0) {
-          await settings.update(NAMESPACE, { soundMapping: patch })
+          await persistPatch(ctx, { soundMapping: patch })
           projection.bump()
         }
       }
@@ -636,15 +681,15 @@ export function apply(ctx) {
           return
         }
         // 校验到写回整段入互斥域:防与 DELETE 清引用并发时把已删音效的 id 写回映射;
-        // settings.update 深合并无法删键,清除以 null 表达,读侧 resolvedConfig 过滤
+        // 深合并无法删键,清除以 null 表达,读侧 resolvedConfig 过滤
         await serializedSoundWrite(async () => {
           if (!validateMappingId(id, (await listSounds()).map((sound) => sound.id))) {
             sendJson(res, 400, { error: '未知音效: ' + id })
             return
           }
-          await settings.update(NAMESPACE, { soundMapping: { [category]: id.length === 0 ? null : id } })
+          await persistPatch(ctx, { soundMapping: { [category]: id.length === 0 ? null : id } })
           projection.bump()
-          sendJson(res, 200, { ok: true, soundMapping: readSettings(ctx).soundMapping })
+          sendJson(res, 200, { ok: true, soundMapping: readSettings(ctx, config).soundMapping })
         })
       }),
     }), 'turn-notify mapping route')
@@ -657,7 +702,7 @@ export function apply(ctx) {
       handler: async (req, res) => {
         // imAvailable 不进 core 纯函数,config 响应处合流;实时判定,无装载时序假设
         if (req.method === 'GET') {
-          sendJson(res, 200, { ...publicConfig(readSettings(ctx)), imAvailable: imReady() })
+          sendJson(res, 200, { ...publicConfig(readSettings(ctx, config)), imAvailable: imReady() })
           return
         }
         if (req.method !== 'POST') {
@@ -671,14 +716,9 @@ export function apply(ctx) {
             sendJson(res, 400, { error: verdict.reason })
             return
           }
-          const settings = ctx.get('settings')
-          if (!settings) {
-            sendJson(res, 500, { error: 'settings 服务不可用' })
-            return
-          }
-          await settings.update(NAMESPACE, verdict.patch)
+          await persistPatch(ctx, verdict.patch)
           projection.bump()
-          sendJson(res, 200, { ...publicConfig(readSettings(ctx)), imAvailable: imReady() })
+          sendJson(res, 200, { ...publicConfig(readSettings(ctx, config)), imAvailable: imReady() })
         } catch (error) {
           sendError(res, error)
         }
@@ -691,7 +731,7 @@ export function apply(ctx) {
       path: '/api/turn-notify/test-webhook',
       handler: route('POST', { crossOrigin: true }, async (req, res) => {
         // 等待投递完成,真实结果随响应返回,测试按钮不再谎报
-        const result = await sendWebhook({ url: readSettings(ctx).webhookUrl, payload: buildWebhookPayload(buildTestUnit()) })
+        const result = await sendWebhook({ url: readSettings(ctx, config).webhookUrl, payload: buildWebhookPayload(buildTestUnit()) })
         sendJson(res, 200, result)
       }),
     }), 'turn-notify test-webhook route')
@@ -755,7 +795,7 @@ export function apply(ctx) {
           sendJson(res, 200, { ok: false, detail: 'dsh-im 未安装' })
           return
         }
-        const targets = normalizeImTargets(readSettings(ctx).imTargets)
+        const targets = normalizeImTargets(readSettings(ctx, config).imTargets)
         if (targets.length === 0) {
           sendJson(res, 200, { ok: false, detail: '未配置投递目标' })
           return

package/test/core.test.mjs

@@ -2,6 +2,7 @@
 import test from 'node:test'
 import assert from 'node:assert/strict'
 import {
+  APPROVAL_ASKED_KIND,
   CATEGORIES,
   CATEGORY_DONE,
   CATEGORY_ERROR,
@@ -41,7 +42,6 @@ import {
   TITLE_MAX_CHARS,
   readRawBody,
   sessionTitle,
-  createApprovalTap,
   sendWebhook,
   TONE_BELL,
   TONE_UP_ARPEGGIO,
@@ -129,6 +129,36 @@ test('非回合结束事件仅 ask_user_question tool/call 命中提问分类',
   assert.equal(mapEventToCategory('turn/start', {}), null)
 })
 
+test('approval/asked 会话事件命中审批分类(宿主 waterfall 被 UI 独占时的唯一信号)', () => {
+  assert.equal(
+    mapEventToCategory('approval/asked', { id: 'a-1', toolName: 'bash', reason: 'escalate' }),
+    CATEGORY_APPROVAL,
+  )
+  // 同一命名空间下的其他事件不误判为审批
+  assert.equal(mapEventToCategory('approval/decided', { id: 'a-1', outcome: 'allowed-once' }), null)
+  assert.equal(mapEventToCategory('approval/policy', { policy: 'ask' }), null)
+})
+
+test('审批通知即时送达,不受最短回合时长过滤', () => {
+  const settings = { enabled: { approval: true }, rootsOnly: true, minTurnDurationMs: 5000 }
+  // 即使时长为 0(< 阈值),approval/asked 仍应放行
+  assert.equal(shouldNotify({
+    category: CATEGORY_APPROVAL,
+    kind: APPROVAL_ASKED_KIND,
+    durationMs: 0,
+    settings,
+    header: {},
+  }), true)
+  // 对照:turn/end 类仍受碎轮过滤
+  assert.equal(shouldNotify({
+    category: CATEGORY_DONE,
+    kind: 'turn/end',
+    durationMs: 0,
+    settings,
+    header: {},
+  }), false)
+})
+
 test('rootsOnly 按子代理会话过滤', () => {
   const subByOrigin = { origin: 'subagent' }
   const subByDepth = { delegationDepth: 1 }
@@ -164,7 +194,7 @@ test('碎轮过滤仅作用于 turn/end 类,时长恰等边界放行', () => {
     category: CATEGORY_DONE, kind: 'turn/end', durationMs: MIN_TURN_MS, settings, header: top,
   }), true)
   assert.equal(shouldNotify({
-    category: CATEGORY_APPROVAL, kind: 'approval/request', durationMs: null, settings, header: top,
+    category: CATEGORY_APPROVAL, kind: APPROVAL_ASKED_KIND, durationMs: null, settings, header: top,
   }), true)
   assert.equal(shouldNotify({
     category: CATEGORY_ASK, kind: 'tool/call', durationMs: null, settings, header: top,
@@ -547,20 +577,6 @@ test('标题提取:首个用户文本并截断', () => {
   assert.equal(sessionTitle([]), null)
 })
 
-test('审批观察器 next() 立即放行且只通知一次', () => {
-  const notified = []
-  const scheduled = []
-  const tap = createApprovalTap((unit) => { notified.push(unit) }, (fn) => { scheduled.push(fn) })
-  let nextCalled = 0
-  const returned = tap({ toolName: 'bash' }, () => { nextCalled += 1; return 'next-result' })
-  assert.equal(nextCalled, 1)
-  assert.equal(returned, 'next-result')
-  assert.equal(notified.length, 0)
-  for (const fn of scheduled) fn()
-  assert.equal(notified.length, 1)
-  assert.equal(notified[0].category, CATEGORY_APPROVAL)
-})
-
 test('webhook 发送吞错不抛出', async () => {
   const calls = []
   const failing = async () => { calls.push(1); throw new Error('unreachable') }

package/test/event-wiring.test.mjs

@@ -462,13 +462,13 @@ test('Given 非提问的 tool/call When 事件到达 Then 不产生通知', asyn
   assert.equal(units.length, 0)
 })
 
-test('Given approval/request 观察者 When 触发 Then 投影审批单元且 next 同步放行', async () => {
+test('Given approval/asked 会话事件 When 到达 Then 投影恰好一条审批单元且 approval/request 无观察者', async () => {
   const { ctx, routes, handlers } = makeCtx()
   apply(ctx)
-  const tap = handlers.get('approval/request')
-  assert.equal(typeof tap, 'function')
-  const returned = tap({}, () => 'next-value')
-  assert.equal(returned, 'next-value')
+  // 回归锁定:审批通知单源为 session/event,waterfall 观察者不得回潮(双路重复送达)
+  assert.equal(handlers.get('approval/request'), undefined)
+  const onEvent = handlers.get('session/event')
+  onEvent(MAIN, { type: 'approval/asked', data: { id: 'a-1', toolName: 'bash' } })
   const units = await projectionUnits(routes)
   assert.equal(units.filter((unit) => unit.category === 'approval').length, 1)
 })
@@ -508,8 +508,8 @@ test('Given 会话无事件日志可读 When 通知投递 Then 不抛并回落
     sessionTitle: { get: () => { throw new Error('no event log') } },
   })
   apply(ctx)
-  const tap = handlers.get('approval/request')
-  tap({}, () => 'next')
+  const onEvent = handlers.get('session/event')
+  onEvent(MAIN, { type: 'approval/asked', data: { id: 'a-1', toolName: 'bash' } })
   const units = await projectionUnits(routes)
   const approval = units.find((unit) => unit.category === 'approval')
   assert.equal(approval.session, null)

package/test/route.test.mjs

@@ -413,3 +413,141 @@ test('test-webhook 已配置时送达并返回真实结果', async () => {
     assert.ok(String(calls[0].body.text).startsWith('[dsh]'), 'webhook payload 缺少 text')
   } finally { globalThis.fetch = original }
 })
+
+// --- 0.1.7 settings 面双形适配(maintain a913c2c 同构) ---
+
+test('Config 导出契约:根级 volatile 包装,validate 产整节单 ref,默认值对拍', async () => {
+  const mod = await import('../src/index.js')
+  assert.ok(mod.Config, 'Config 导出必须在场')
+  const resolved = mod.Config['~standard'].validate({})
+  assert.equal(resolved.issues, undefined)
+  const section = resolved.value.get()
+  assert.equal(section.webhookUrl, '')
+  assert.equal(section.rootsOnly, true)
+  assert.equal(section.imEnabled, true)
+  assert.ok(section.enabled && typeof section.enabled === 'object')
+})
+
+// 0.1.7 形态装配:settings 无 register/get(宿主已移除),config 为整节单 ref 桩,
+// configEditor 桩经深合并后原样写回
+function makeRc17Ctx({ configStore = {}, configEditorAvailable = true } = {}) {
+  const routes = new Map()
+  const editCalls = []
+  const config = { get: () => ({ ...configStore }) }
+  const settingsService = {}
+  const configEditor = {
+    async edit(entry, change) {
+      editCalls.push(entry)
+      const merge = (under, over) => {
+        const out = { ...under }
+        for (const key of Object.keys(over)) {
+          const next = over[key]
+          const underValue = out[key]
+          const bothPlain = (next !== null && typeof next === 'object' && !Array.isArray(next))
+            && (underValue !== null && typeof underValue === 'object' && !Array.isArray(underValue))
+          out[key] = bothPlain ? merge(underValue, next) : next
+        }
+        return out
+      }
+      const next = merge({ ...configStore }, change({}, {}))
+      for (const key of Object.keys(next)) configStore[key] = next[key]
+    },
+  }
+  const configureCalls = []
+  const ctx = {
+    on() {},
+    fiber: { entry: { options: { id: 'turn-notify', name: '@mzzsfy/dsh-turn-notify' } } },
+    get(key) {
+      if (key === 'settings') return settingsService
+      if (key === 'configEditor') return configEditorAvailable ? configEditor : undefined
+      return undefined
+    },
+    inject(deps, fn) {
+      if (deps[0] === 'settings') {
+        fn({
+          settings: settingsService,
+          effect(stubEffect) {
+            const disposer = stubEffect()
+            if (typeof disposer === 'function') configureCalls.push(disposer)
+          },
+        })
+      }
+    },
+    effect(thunk) { thunk() },
+    webServer: { register(route) { routes.set(route.path, route.handler) } },
+  }
+  return { ctx, routes, config, configStore, editCalls, configureCalls }
+}
+
+test('0.1.7 形态:config GET 读 config ref 节值,POST 经 configEditor.edit 深合并', async () => {
+  // Given config ref 携带用户值 + configEditor 桩
+  const { ctx, routes, config, configStore, editCalls } = makeRc17Ctx({
+    configStore: { enabled: { completed: false }, webhookUrl: 'https://hook.example' },
+  })
+  apply(ctx, config)
+  // When GET config
+  const read = makeRes()
+  await routes.get('/api/turn-notify/config')(makeReq('GET'), read)
+  // Then 返回 config 节值
+  assert.equal(read.body.enabled.completed, false)
+  assert.equal(read.body.webhookUrl, 'https://hook.example')
+  // When POST 嵌套补丁(仅关一个分类 + 改时长)
+  const saved = makeRes()
+  await routes.get('/api/turn-notify/config')(makeReq('POST', { enabled: { error: false }, minTurnDurationMs: 1234 }, JSON_HEADERS), saved)
+  // Then 深合并落盘:未提交的兄弟分类保留,新键写入
+  assert.equal(saved.status, 200)
+  assert.equal(editCalls.length, 1)
+  assert.equal(editCalls[0].options.id, 'turn-notify')
+  assert.equal(configStore.enabled.completed, false, '既有分类开关保留')
+  assert.equal(configStore.enabled.error, false, '新分类开关写入')
+  assert.equal(configStore.minTurnDurationMs, 1234)
+  // When 重读
+  const reread = makeRes()
+  await routes.get('/api/turn-notify/config')(makeReq('GET'), reread)
+  // Then 回显合并后节值
+  assert.equal(reread.body.enabled.error, false)
+  assert.equal(reread.body.enabled.completed, false)
+})
+
+test('0.1.7 形态:soundMapping 单分类写经 configEditor.edit 深合并,null 清除保留', async () => {
+  // Given 既有映射两个分类
+  const { ctx, routes, config, configStore } = makeRc17Ctx({
+    configStore: { soundMapping: { completed: 'ding', 'max-tokens': 'buzz' } },
+  })
+  apply(ctx, config)
+  // When POST 单分类改映射
+  const saved = makeRes()
+  await routes.get('/api/turn-notify/mapping')(makeReq('POST', { category: 'completed', id: 'bell' }, JSON_HEADERS), saved)
+  // Then 兄弟分类保留,目标分类更新
+  assert.equal(saved.status, 200)
+  assert.equal(configStore.soundMapping.completed, 'bell')
+  assert.equal(configStore.soundMapping['max-tokens'], 'buzz')
+  // When POST 空 id(清除语义,null 落盘)
+  await routes.get('/api/turn-notify/mapping')(makeReq('POST', { category: 'max-tokens', id: '' }, JSON_HEADERS), makeRes())
+  // Then null 原样落盘(读侧过滤)
+  assert.equal(configStore.soundMapping['max-tokens'], null)
+})
+
+test('0.1.7 形态:configEditor 缺失即 500 拒写,不崩溃', async () => {
+  // Given configEditor 服务缺席
+  const { ctx, routes, config } = makeRc17Ctx({ configEditorAvailable: false })
+  apply(ctx, config)
+  // When POST 写配置
+  const denied = makeRes()
+  await routes.get('/api/turn-notify/config')(makeReq('POST', { rootsOnly: false }, JSON_HEADERS), denied)
+  // Then 400 错误响应(sendError 归一,settings 服务不可用非 fs 错误),进程存活
+  assert.equal(denied.status, 400)
+  assert.ok(denied.body.error)
+})
+
+test('0.1.7 形态:settings.configure 在场即关闭原生自动页,register 缺失不抛错', () => {
+  // Given settingsForms 带 configure 无 register
+  const configureCalls = []
+  const { ctx, config } = makeRc17Ctx()
+  ctx.get('settings').configure = (presentation, owner) => { configureCalls.push({ presentation, owner }); return () => {} }
+  // When apply
+  apply(ctx, config)
+  // Then 关闭自动页且 owner 为本插件 fiber
+  assert.equal(configureCalls.length, 1)
+  assert.deepEqual(configureCalls[0].presentation, { auto: false })
+})