@mzzsfy/dsh-turn-notify 0.11.1 → 0.12.1

package/README.md

@@ -91,7 +91,7 @@ turn-notify:
 
 ## IM 推送
 
-安装 [@xmanrui/dsh-im](https://www.npmjs.com/package/@xmanrui/dsh-im) 后自动启用,可推送到微信等九种渠道。投递目标的新建与平台测试在 dsh-im 设置页完成,本插件只做选择:从已绑 bot 的目标目录勾选即保存,支持绑定多个 bot。触发逻辑与 webhook 一致,fire-and-forget 不重试;bot 离线时该次通知弃置不补发。
+安装 [@xmanrui/dsh-im](https://www.npmjs.com/package/@xmanrui/dsh-im) 后自动启用,可推送到微信等九种渠道。投递目标的新建与平台测试在 dsh-im 设置页完成,本插件只做选择:从已绑 bot 的目标目录勾选即保存,支持绑定多个 bot。IM 卡顶部有总开关,关闭后不向已配目标投递、目标绑定原样保留,临时停用不必逐个移除目标,再开即恢复。触发逻辑与 webhook 一致,fire-and-forget 不重试;bot 离线时该次通知弃置不补发。测试页的"测试 IM 通知"为显式点火,不受总开关影响。
 
 ## 会话行高亮
 
@@ -114,7 +114,7 @@ turn-notify:
 | 通知 | webhook 地址、最短回合时长、子代理过滤、宿主通知(总开关与回退)、六类事件开关;存 settings.yaml,事件开关点击即存,其余点保存后生效。事件→通道路由(kindRoutes)亦存此命名空间,经 yaml 配置 |
 | 偏好 | 本机浏览器记忆的设置:会话高亮(独立开关)、声音总开关与分类静音、音量、系统弹窗与授权、页内提示开关、页内提示音(总开关 + 分类独立开关)、聚焦静默、降级标题闪烁 |
 | 音效 | 音效上传/试听/重命名/删除,六类事件的音效映射与双作用域开关,页内提示音映射(本机,未配置沿用通知音效) |
-| IM | 绑定 dsh-im bot、勾选投递目标(仅装了 dsh-im 时显示) |
+| IM | IM 总开关(关闭保留目标)、绑定 dsh-im bot、勾选投递目标(仅装了 dsh-im 时显示) |
 | 测试 | 声音/页内/系统/宿主/webhook/IM 逐通道点火,回执即真实结果 |
 
 ## settings.yaml 参考
@@ -143,6 +143,7 @@ turn-notify:
   imTargets:                      # dsh-im 投递目标,空数组禁用
     - botId: wx_xxx
       targetId: owner
+  imEnabled: true                 # IM 推送总开关:关闭后不投递,目标绑定保留
 ```
 
 音量、聚焦静默、分类静音等本机偏好存浏览器 localStorage,不经 yaml。
@@ -191,4 +192,4 @@ node scripts/dev-link.mjs dsh-turn-notify   # 仓库根执行:归一 profile 依
 
 ## dsh 版本兼容
 
-三版本全部通过:通知开关与播报形态、激活 live。0.1.6 控件数 13→19 属宿主演进,不构成不兼容。
+三版本(0.1.2-rc.1 / 0.1.5-rc.3 / 0.1.7-rc.1)全部通过:通知开关与播报形态(四 tab 计数、事件开关、音效卡试听、IM 自洽)、激活 live。0.1.6 控件数 13→19 属宿主演进,不构成不兼容。

package/package.json

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

package/src/client.js

@@ -1071,6 +1071,7 @@ window.__ModuleLoader__.load({
       folderRunningEnabled: true,
       enabled: Object.fromEntries(CATEGORIES.map((key) => [key, true])),
       imTargets: [],
+      imEnabled: true,
     }
 
     const CSS = [
@@ -1616,6 +1617,18 @@ window.__ModuleLoader__.load({
         void persistImTargets(removeImTargetFromList(config.imTargets, item.botId, item.targetId))
       }
 
+      // IM 总开关:目标绑定保留,关闭仅停投递;乐观回填,失败回滚
+      function toggleImEnabled(checked) {
+        setConfig((prev) => ({ ...prev, imEnabled: checked }))
+        api('/api/turn-notify/config', { method: 'POST', body: JSON.stringify({ imEnabled: checked }) })
+          .then((res) => setConfig({ ...DEFAULT_CONFIG, ...res }))
+          .catch((error) => {
+            // 回滚到请求发出前的取值:两次异步 setConfig 闭包各自读到已更新的 prev
+            setConfig((prev) => ({ ...prev, imEnabled: !prev.imEnabled }))
+            patch('IM 开关切换失败:' + (error && error.message ? error.message : String(error)), 'error')
+          })
+      }
+
       // 取消注册:移除该 bot 全部目标;bot 在 dsh-im 已删除时借此清理残留绑定
       function unregisterImBot(botId) {
         void persistImTargets(
@@ -2002,6 +2015,14 @@ window.__ModuleLoader__.load({
               h('span', { className: 'tn-card__title' }, 'IM 投递(dsh-im)'),
               h('span', { className: 'tn-card__sub' }, '勾选目标即自动保存;支持绑定多个 bot,点 bot 名加载其目录,× 取消注册'),
             ),
+            field('IM 开关', [
+              h('label', { className: 'tn-meta tn-switch', title: '关闭后不再向已配目标投递 IM 通知,目标绑定保留;再次开启即恢复推送' },
+                ...switchToggle({
+                  checked: config.imEnabled,
+                  onChange: (e) => toggleImEnabled(e.target.checked),
+                }),
+                ' 启用 IM 推送'),
+            ], '关闭时通知不推送 IM,已勾选的目标与 bot 绑定原样保留,无需移除目标'),
             field('Bot ID', [
               h('input', {
                 className: 'tn-input tn-fill', type: 'text',

package/src/core.mjs

@@ -635,7 +635,7 @@ export function imBoundBotIds(list) {
 // 返回归一化后的补丁。
 export function validateConfigPatch(patch) {
   if (patch === null || typeof patch !== 'object' || Array.isArray(patch)) return { ok: false, reason: '补丁须为对象' }
-  const known = ['webhookUrl', 'minTurnDurationMs', 'rootsOnly', 'suppressSubagentWake', 'enabled', 'imTargets', 'kindRoutes', 'hostNotify', 'hostNotifyFallback', 'folderRunningEnabled']
+  const known = ['webhookUrl', 'minTurnDurationMs', 'rootsOnly', 'suppressSubagentWake', 'enabled', 'imTargets', 'imEnabled', 'kindRoutes', 'hostNotify', 'hostNotifyFallback', 'folderRunningEnabled']
   for (const key of Object.keys(patch)) {
     if (known.indexOf(key) < 0) return { ok: false, reason: '未知配置项: ' + key }
   }
@@ -675,6 +675,10 @@ export function validateConfigPatch(patch) {
     }
     next.imTargets = targets
   }
+  if ('imEnabled' in patch) {
+    if (typeof patch.imEnabled !== 'boolean') return { ok: false, reason: 'imEnabled 须为布尔' }
+    next.imEnabled = patch.imEnabled
+  }
   if ('minTurnDurationMs' in patch) {
     const ms = patch.minTurnDurationMs
     if (typeof ms !== 'number' || !Number.isInteger(ms) || ms < 0) return { ok: false, reason: 'minTurnDurationMs 须为非负整数' }
@@ -769,6 +773,8 @@ export function resolvedConfig(settings) {
     enabled: Object.fromEntries(CATEGORIES.map((key) => [key, enabled[key] !== false])),
     soundMapping,
     imTargets: normalizeImTargets(source.imTargets),
+    // 开关缺省回开:存量配置升级行为不变
+    imEnabled: source.imEnabled !== false,
     kindRoutes: routesVerdict.ok ? routesVerdict.routes : {},
   }
 }
@@ -786,6 +792,7 @@ export function publicConfig(settings) {
     enabled: resolved.enabled,
     soundMapping: resolved.soundMapping,
     imTargets: resolved.imTargets,
+    imEnabled: resolved.imEnabled,
     kindRoutes: resolved.kindRoutes,
     webhookUrl: resolved.webhookUrl,
   }

package/src/index.js

@@ -98,13 +98,56 @@ const SETTINGS_SCHEMA = z.object({
   enabled: z.object(Object.fromEntries(CATEGORIES.map((key) => [key, z.boolean().default(true)]))).description('六类事件独立开关:完成/出错/被中断/等待审批/AI 提问/达到上限'),
   soundMapping: z.object(Object.fromEntries(CATEGORIES.map((key) => [key, z.string().default('')]))).description('每类事件的声音映射,空为内置默认,非空为内置音名或上传音效 id'),
   imTargets: z.array(z.object({ botId: z.string().default(''), targetId: z.string().default('') })).default([]).description('dsh-im 推送目标列表,空数组禁用 IM 通道'),
+  imEnabled: z.boolean().default(true).description('IM 推送总开关:关闭后不向已配目标投递,目标绑定保留'),
   kindRoutes: z.dict(z.array(z.string())).default({}).description('事件→通道路由:分类到放行通道名单(sound/system/toast/blink/webhook/im/host),未配置的分类全通道放行'),
 })
 
 // 读侧归一交由 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) {
@@ -186,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 记回合序号与起始时间,回合结束即清;序号严格递增,
   // 供子代理注册归属判定,同毫秒内多回合不受时钟精度歧义影响
@@ -240,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
@@ -311,6 +354,8 @@ export function apply(ctx) {
   function deliverIm(unit, settings) {
     const dshIm = ctx.get('dshIm')
     if (dshIm === undefined) return
+    // 总开关关闭:目标绑定保留,仅不投递
+    if (settings.imEnabled === false) return
     for (const { botId, targetId } of normalizeImTargets(settings.imTargets)) {
       void Promise.resolve().then(() => dshIm.send(botId, targetId, unit.text, { signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS) })).catch(() => {})
     }
@@ -416,6 +461,14 @@ export function apply(ctx) {
   ))
 
   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)
   })
 
@@ -468,7 +521,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()
@@ -599,15 +652,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()
         }
       }
@@ -633,15 +685,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')
@@ -654,7 +706,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') {
@@ -668,14 +720,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)
         }
@@ -688,7 +735,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')
@@ -752,11 +799,12 @@ 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
         }
+        // 点火测试与开关无关:显式验证通道连通,不受投递总开关压制
         // 逐目标结算,真实结果随响应返回,与 test-webhook 的不谎报原则一致
         const results = await Promise.all(targets.map(async ({ botId, targetId }) => {
           try {

package/test/core.test.mjs

@@ -646,6 +646,10 @@ test('配置补丁校验:非法输入逐类拒绝', () => {
   assert.equal(validateConfigPatch({ minTurnDurationMs: 'fast' }).ok, false)
   assert.equal(validateConfigPatch({ rootsOnly: 'yes' }).ok, false)
   assert.equal(validateConfigPatch({ suppressSubagentWake: 'yes' }).ok, false)
+  // imEnabled:布尔放行,非布尔拒绝
+  assert.deepEqual(validateConfigPatch({ imEnabled: false }), { ok: true, patch: { imEnabled: false } })
+  assert.equal(validateConfigPatch({ imEnabled: 'yes' }).ok, false)
+  assert.equal(validateConfigPatch({ imEnabled: 1 }).ok, false)
   assert.equal(validateConfigPatch({ enabled: { unknown: true } }).ok, false)
   assert.equal(validateConfigPatch({ enabled: { completed: 'no' } }).ok, false)
   assert.equal(validateConfigPatch({ enabled: [true] }).ok, false)
@@ -665,6 +669,7 @@ test('配置解析:enabled 缺省键按开补全,字段类型回退默认', () =
       enabled: { completed: false, error: true, interrupted: true, approval: true, ask: true, 'max-tokens': true },
       soundMapping: { completed: 'snd-1' },
       imTargets: [],
+      imEnabled: true,
       kindRoutes: { completed: ['webhook'] },
     },
   )
@@ -679,10 +684,14 @@ test('配置解析:enabled 缺省键按开补全,字段类型回退默认', () =
     enabled: Object.fromEntries(CATEGORIES.map((name) => [name, true])),
     soundMapping: {},
     imTargets: [],
+    imEnabled: true,
     kindRoutes: {},
   })
   assert.equal(resolvedConfig({ minTurnDurationMs: Number.NaN }).minTurnDurationMs, MIN_TURN_MS)
   assert.equal(resolvedConfig({ suppressSubagentWake: false }).suppressSubagentWake, false)
+  // imEnabled:显式 false 生效,缺省或类型异常回开(升级兼容)
+  assert.equal(resolvedConfig({ imEnabled: false }).imEnabled, false)
+  assert.equal(resolvedConfig({ imEnabled: 'no' }).imEnabled, true)
 })
 
 test('面板可见配置:webhookUrl 原文回显', () => {
@@ -698,6 +707,7 @@ test('面板可见配置:webhookUrl 原文回显', () => {
       enabled: { completed: false, error: true, interrupted: true, approval: true, ask: true, 'max-tokens': true },
       soundMapping: { completed: 'snd-1' },
       imTargets: [],
+      imEnabled: true,
       kindRoutes: { ask: ['im'] },
       webhookUrl: 'https://hook.example/service/xxx',
     },

package/test/event-wiring.test.mjs

@@ -377,6 +377,27 @@ test('Given dshIm 在场且已配多目标 When 回合完成 Then 逐目标投
   assert.ok(sends.every((call) => String(call.text).startsWith('[dsh]')), 'IM 文本应与通知单元一致')
 })
 
+test('Given 已配目标且 imEnabled=false When 回合完成 Then 不投递且目标保留', async () => {
+  const sends = []
+  const { ctx, routes, handlers } = makeCtx({ dshIm: makeImDshIm(sends) })
+  apply(ctx)
+  await disableDurationFilter(routes)
+  await configureImTargets(routes, [{ botId: 'wx_a', targetId: 'owner' }, { botId: 'wx_b', targetId: 'group' }])
+  const offRes = makeRes()
+  await routes.get('/api/turn-notify/config')(makeReq('POST', { imEnabled: false }, JSON_HEADERS), offRes)
+  assert.equal(offRes.status, 200)
+  assert.equal(offRes.body.imEnabled, false)
+  assert.equal(offRes.body.imTargets.length, 2, '开关关闭不应清空目标')
+  const onEvent = handlers.get('session/event')
+  onEvent(MAIN, { type: 'turn/start' })
+  onEvent(MAIN, turnEnd('completed'))
+  await flushMicrotasks()
+  assert.equal(sends.length, 0, 'imEnabled=false 时不投递')
+  // 投影照常:开关只压制 IM 通道
+  const units = await projectionUnits(routes)
+  assert.equal(units.filter((unit) => unit.category === 'completed').length, 1)
+})
+
 test('Given send 拒绝 When 回合完成 Then 无未处理拒绝且投影照常', async () => {
   const rejections = []
   const onUnhandled = (reason) => rejections.push(reason)

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 })
+})