@falling-ts/dsh-web-ding 0.1.1 → 0.1.2

package/README.cn.md

@@ -28,16 +28,29 @@ dsh plugin --profile web add github:falling-ts/dsh-web-ding
 
 ## 配置(`falling-ts-web-ding` 命名空间,$DSH_HOME/settings.yaml)
 
+两块独立配置,各自有开关与音色:
+
+**块 1 — 弹出用户选择** —— harness 弹出用户选择题时在浏览器播放一声"叮"。
+检测在浏览器侧完成(DOM 上 QuestionComposer 的 `[data-question-key]` 锚点):
+宿主看不到 question 帧,故本块完全由前端实现。
+
 | 字段 | 类型 | 默认 | 含义 |
 |------|------|------|------|
-| `enabled` | boolean | `true` | 总开关(关闭时 Host 跳过发布)。 |
-| `volume` | number 0..1 | `0.7` | Web Audio 播放音量。 |
-| `freq` | number 80..4000 | `880` | "叮"的基频(Hz)。 |
-| `decayMs` | number 100..4000 | `900` | 音色衰减时长(ms)。 |
+| `questionEnabled` | boolean | `true` | 弹出用户选择提示音开关。 |
+| `questionVolume` | number 0..1 | `0.7` | Web Audio 播放音量。 |
+| `questionFreq` | number 80..4000 | `880` | "叮"的基频(Hz)。 |
+| `questionDecayMs` | number 100..4000 | `900` | 音色衰减时长(ms)。 |
 
-也可以在 **设置 → 回合结束提示音** 面板里调整,面板带"试听"按钮。
+**块 2 — 回合结束** —— 经典的 agent/status idle 转变提示音。Host 观察
+`agent/status`,在 idle 转变(全部轮次与子代理结束、下一次人为对话之前;
+新建后从未运行过的会话与重复 idle tick 保持静默)时发布 `done` 信号。
 
-任何会话的 agent 回合结束(转入空闲)都会提示;同一会话内重复 idle tick 与新建后从未运行过的会话保持静默。
+| 字段 | 类型 | 默认 | 含义 |
+|------|------|------|------|
+| `turnEndEnabled` | boolean | `true` | 回合结束提示音开关(关闭时 Host 跳过发布)。 |
+| `turnEndVolume` | number 0..1 | `0.7` | Web Audio 播放音量。 |
+| `turnEndFreq` | number 80..4000 | `880` | "叮"的基频(Hz)。 |
+| `turnEndDecayMs` | number 100..4000 | `900` | 音色衰减时长(ms)。 |
 
 ## 浏览器自动播放策略
 
@@ -60,10 +73,11 @@ dsh plugin --profile web add /path/to/dsh-web-ding
 
 ## 效果截图
 
-![设置页——「回合结束提示音」分区,各旋钮免重启实时可调](assets/setting-ding.png)
+![设置页——「提示音配置」分区,两块各自开关与音色,免重启实时可调](assets/setting-ding.png)
 
-*设置页——「回合结束提示音」分区:总开关、音量、频率、衰减时长全部免重启
-实时可调,并带"试听"按钮预热浏览器 AudioContext。*
+*设置页——「提示音配置」分区:「弹出用户选择」与「回合结束」两块,各自
+开关、音量、频率、衰减时长,免重启实时可调,各带"试听"按钮预热浏览器
+AudioContext。*
 
 ---
 

package/README.md

@@ -28,14 +28,31 @@ Requires the web app to ship the client bundle (the `dsh.client` declaration in
 
 ## Configuration (`falling-ts-web-ding` namespace, $DSH_HOME/settings.yaml)
 
+Two independent blocks, each with its own switch and its own tone:
+
+**Block 1 — 弹出用户选择 (question popup ding)** — plays when the harness pops a
+user-question chooser in the browser. Detection is client-side on the DOM
+(`[data-question-key]` anchor of the QuestionComposer): the Host half sees no
+question frame, so this block is entirely browser-side.
+
 | Field | Type | Default | Meaning |
 |-------|------|---------|---------|
-| `enabled` | boolean | `true` | Master switch (Host skips publishing when off). |
-| `volume` | number 0..1 | `0.7` | Web Audio playback gain. |
-| `freq` | number 80..4000 | `880` | Fundamental frequency of the ding (Hz). |
-| `decayMs` | number 100..4000 | `900` | Tone decay length (ms). |
+| `questionEnabled` | boolean | `true` | Switch for the question-popup ding. |
+| `questionVolume` | number 0..1 | `0.7` | Web Audio playback gain. |
+| `questionFreq` | number 80..4000 | `880` | Fundamental frequency of the ding (Hz). |
+| `questionDecayMs` | number 100..4000 | `900` | Tone decay length (ms). |
+
+**Block 2 — 回合结束 (turn-end ding)** — the classic agent/status idle-transition
+tone. The Host observes `agent/status`; on the idle transition (all turns done,
+including sub-agents, before the next human turn; fresh sessions that never ran
+and repeated idle ticks stay silent) it publishes the `done` signal.
 
-Every session's agent turn end (transition to idle) rings; repeated idle ticks of an already-idle session and brand-new sessions that never ran stay silent.
+| Field | Type | Default | Meaning |
+|-------|------|---------|---------|
+| `turnEndEnabled` | boolean | `true` | Switch for the turn-end ding (Host skips publishing when off). |
+| `turnEndVolume` | number 0..1 | `0.7` | Web Audio playback gain. |
+| `turnEndFreq` | number 80..4000 | `880` | Fundamental frequency of the ding (Hz). |
+| `turnEndDecayMs` | number 100..4000 | `900` | Tone decay length (ms). |
 
 Besides the ring, each turn end drops a bottom-right toast (Win11-style,
 auto-dismisses after 6 s). Click it to open the right-side notification
@@ -44,8 +61,8 @@ drawer: the last 100 turn-end messages are kept in the browser's
 deleted individually, and a "全部删除" button clears them all. The message
 log is front-end only — the Host never reads or writes it.
 
-You can also adjust these from the **设置 → 回合结束提示音** panel, which
-includes a "试听" (preview) button.
+You can also adjust both blocks from the **设置 → 提示音配置** panel,
+each with its own switch and its own "试听" (preview) button.
 
 ## Browser autoplay policy
 
@@ -70,11 +87,12 @@ browser).
 
 ## Screenshots
 
-![Settings page: the **ding** (回合结束提示音) section, live-editable controls](assets/setting-ding.png)
+![Settings page: the **提示音配置** section, two blocks each with its own switch and tone](assets/setting-ding.png)
 
-*Settings page: the **回合结束提示音** section. Master switch, volume,
-frequency and decay length are all live-editable without a restart, with a
-**试听** (preview) button to warm the browser AudioContext.*
+*Settings page: the **提示音配置** section — "弹出用户选择" and "回合结束" blocks,
+each with its own switch, volume, frequency and decay length, all live-editable
+without a restart, each with a **试听** (preview) button to warm the browser
+AudioContext.*
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falling-ts/dsh-web-ding",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "DSH Cordis plugin: announces the moment an agent finishes (turns idle) by pushing a 'done' signal from the Host half into the falling-ts-web-ding settings namespace, which the browser client half mirrors live and answers with a synthesized 'ding' tone via the Web Audio API. The tone is played ENTIRELY by front-end JS in the browser — the Host/node backend never emits audio and no Windows/system notification is used.",
   "type": "module",
   "main": "./index.js",

package/src/core/settings.js

@@ -1,20 +1,22 @@
 /**
- * dsh-web-ding settings — the "回合结束提示音" (turn-end ding) surface.
+ * dsh-web-ding settings — the "提示音" (ding) surface, split into TWO blocks:
  *
- * User-tunable parameters are registered under the `falling-ts-web-ding`
- * settings namespace (the `falling-ts-` prefix prevents collisions with
- * other plugins' keys):
+ * Block 1 — 弹出用户选择 (question popup ding): plays when the harness pops a
+ *   user-question chooser in the browser (detected client-side on the DOM
+ *   `[data-question-key]` anchor — the host half sees no question frame).
+ *   `questionEnabled` (boolean, default `true`) is its master switch; when
+ *   `false` the browser skips the question-popup ding.
+ *   `questionVolume` / `questionFreq` / `questionDecayMs` tune its tone.
  *
- * - `enabled`  (boolean, default `true`): master switch. When `false` the
- *   Host half still observes `agent/status` but skips publishing the signal,
- *   so the browser never hears a ding.
- * - `volume`   (number 0..1, default `0.7`): playback gain applied by the
- *   browser client's Web Audio synth (a per-oscillator peak, not the master).
- * - `freq`     (number 80..4000, default `880`): fundamental frequency of
- *   the synthesized "ding" in Hz. The client stacks a soft higher-octave and
- *   a faint bell partial on top automatically.
- * - `decayMs`  (number 100..4000, default `900`): exponential-decay length
- *   of the tone in milliseconds.
+ * Block 2 — 回合结束 (turn-end ding): the classic agent/status idle-transition
+ *   tone. `turnEndEnabled` (boolean, default `true`) is its master switch;
+ *   when `false` the Host half still observes `agent/status` but skips
+ *   publishing the signal, so the browser never hears a turn-end ding.
+ *   `turnEndVolume` / `turnEndFreq` / `turnEndDecayMs` tune its tone.
+ *
+ * Per-block fields are mirrored (the same `volume` 0..1 / `freq` 80..4000 /
+ * `decayMs` 100..4000 meanings as the original single block), so the two
+ * dings can carry distinct pitches and loudness.
  *
  * The `signal` field is the PLUGIN-PRIVATE host→browser messenger (the same
  * pattern dsh-force-compact uses for its `liveUi` field): the Host half is
@@ -31,12 +33,18 @@ export const NS = 'falling-ts-web-ding'
 /** The settings field carrying the host→browser turn-end signal. */
 export const SIGNAL_FIELD = 'signal'
 
-/** Defaults — also the base passed to settings.register. */
+/** Defaults — also the base passed to settings.register. Two blocks, each with its own switch and tone. */
 export const DEFAULTS = Object.freeze({
-  enabled: true,
-  volume: 0.7,
-  freq: 880,
-  decayMs: 900,
+  // Block 1 — 弹出用户选择 (question popup ding), detected client-side on the DOM.
+  questionEnabled: true,
+  questionVolume: 0.7,
+  questionFreq: 880,
+  questionDecayMs: 900,
+  // Block 2 — 回合结束 (turn-end ding), Host agent/status idle transition.
+  turnEndEnabled: true,
+  turnEndVolume: 0.7,
+  turnEndFreq: 880,
+  turnEndDecayMs: 900,
 })
 
 /**
@@ -104,10 +112,16 @@ export async function buildSchema() {
     const z = await resolveZ()
     if (z === undefined) return null
     return z.object({
-      enabled: z.boolean().default(DEFAULTS.enabled),
-      volume: z.number().default(DEFAULTS.volume),
-      freq: z.number().default(DEFAULTS.freq),
-      decayMs: z.number().default(DEFAULTS.decayMs),
+      // Block 1 — 弹出用户选择 (question popup ding), client-side DOM detection.
+      questionEnabled: z.boolean().default(DEFAULTS.questionEnabled),
+      questionVolume: z.number().default(DEFAULTS.questionVolume),
+      questionFreq: z.number().default(DEFAULTS.questionFreq),
+      questionDecayMs: z.number().default(DEFAULTS.questionDecayMs),
+      // Block 2 — 回合结束 (turn-end ding), Host agent/status idle transition.
+      turnEndEnabled: z.boolean().default(DEFAULTS.turnEndEnabled),
+      turnEndVolume: z.number().default(DEFAULTS.turnEndVolume),
+      turnEndFreq: z.number().default(DEFAULTS.turnEndFreq),
+      turnEndDecayMs: z.number().default(DEFAULTS.turnEndDecayMs),
       // TRANSIENT host→browser messenger (src/core/signal.js): host-written
       // { phase:'done', at, sessionId }. z.any() because the vendored
       // schemastery exposes only object/any/string/number/boolean/array.

package/src/hooks/idle.js

@@ -55,9 +55,9 @@ export async function handleAgentStatus(ctx, payload) {
     if (prev === 'idle') return // repeated idle tick — already handled
     if (!everBusy.has(sid)) return // fresh session that never ran — no ding
 
-    const enabled = await readRawSetting(ctx, 'enabled')
+    const enabled = await readRawSetting(ctx, 'turnEndEnabled')
     if (enabled === false) {
-      ctx.logger.debug(`[web-ding] ${sid}: idle transition ignored — enabled=false`)
+      ctx.logger.debug(`[web-ding] ${sid}: idle transition ignored — turnEndEnabled=false`)
       return
     }
     await publishDingSignal(ctx, sid)

package/web/client.js

@@ -1,5 +1,6 @@
 /**
- * dsh-web-ding 浏览器半部:回合结束提示音(设置分区 + Web Audio 播放器)。
+ * dsh-web-ding 浏览器半部:提示音配置(设置分区 + Web Audio 播放器,两块:弹出
+ * 用户选择 / 回合结束)。
  *
  * 这是一个闭包工厂 artifact:window.__ModuleLoader__.load({ id, factory }),
  * factory(require) 通过注入的 require 解析外部模块(react、client-runtime),
@@ -15,8 +16,10 @@
  *      基线不播放,重启残留/重复快照都不会重复响)后,用 Web Audio API 合成
  *      一声"叮"。声音 100% 由浏览器 JS 生成——宿主 Node 端从不发声,也不发
  *      Windows/系统通知。
- *   3. 注册 settings.section "回合结束提示音" 分区:开关、音量、音色频率、
- *      时长与"试听"按钮(点击试听同时完成音频解锁)。
+ *   3. 注册 settings.section "提示音配置" 分区:两块(弹出用户选择 / 回合结束),
+ *      每块都有开关、音量、音色频率、时长与"试听"按钮(点击试听同时完成音频解锁)。
+ *      滑块用 BufferedSlider 本地缓冲——拖动只刷本地 state,松手/失焦才提交,
+ *      避免每次拖动写盘 + 广播 + 整块面板重渲染导致卡顿。
  *
  * 浏览器自动播放策略:AudioContext 需要一次用户手势才能出声。首次
  * pointerdown/keydown 做一次性预热(创建并 resume),"试听"按钮点击本身
@@ -468,8 +471,8 @@ window.__ModuleLoader__.load({
       }
       if (!(at > lastAt)) return;
       lastAt = at;
-      if (value.enabled !== false) {
-        playDing({ volume: value.volume, freq: value.freq, decayMs: value.decayMs });
+      if (value.turnEndEnabled !== false) {
+        playDing({ volume: value.turnEndVolume, freq: value.turnEndFreq, decayMs: value.turnEndDecayMs });
         const sessionId = typeof sig.sessionId === "string" ? sig.sessionId : undefined;
         // 信号里只有 sessionId:异步查一次真实标题再落缓存与弹 toast。
         void (async () => {
@@ -481,6 +484,44 @@ window.__ModuleLoader__.load({
       }
     }
 
+    // ── 弹出用户选择检测(DOM 锚点 [data-question-key],纯前端)────────────────────
+    // harness 的用户选择题(ask_user_question)在对话区由 QuestionComposer 渲染,根
+    // 节点带稳定的 data-question-key 属性(CSS Modules 类名是哈希的,不可用——与
+    // TurnStatus 用 role/aria 识别同思路)。宿主半部看不到 question/requested 帧
+    // (那走 connection 层 MuxFrame,Host 插件不可订阅),所以这一块完全在浏览器侧
+    // 完成:MutationObserver 观察新出现的 [data-question-key] 节点,首次出现即播
+    // 放 Block 1(弹出用户选择)的那声"叮"。非 timer、无持久态,同 lastAt 首帧
+    // 基线语义:加载时已存在的 key 只记不响,之后新弹出的 key 才响。
+    let seenQuestionKeys = new Set();   // 已响应过的 question key(去重,防重复响)
+    let questionObserver = null;        // DOM 观察器(非 timer)
+    let questionValueRef = null;        // 最新快照引用,供 observer 回调读取
+    function maybePlayQuestionFromDom(value) {
+      if (typeof document === "undefined") return;
+      const nodes = document.querySelectorAll('[data-question-key]');
+      if (nodes.length === 0) return;
+      const v = (value && typeof value === "object") ? value : {};
+      const enabled = v.questionEnabled !== false;
+      for (const el of nodes) {
+        const key = el.getAttribute("data-question-key");
+        if (!key || seenQuestionKeys.has(key)) continue;
+        seenQuestionKeys.add(key);
+        if (enabled) {
+          playDing({ volume: v.questionVolume, freq: v.questionFreq, decayMs: v.questionDecayMs });
+        }
+      }
+    }
+    function installQuestionObserver(value) {
+      if (questionObserver || typeof MutationObserver === "undefined" || typeof document === "undefined") return;
+      // 基线:先记下当前已存在的 key(不响),之后新 key 才响(同 lastAt 首帧语义)。
+      const nodes = document.querySelectorAll('[data-question-key]');
+      for (const el of nodes) {
+        const key = el.getAttribute("data-question-key");
+        if (key) seenQuestionKeys.add(key);
+      }
+      questionObserver = new MutationObserver(() => maybePlayQuestionFromDom(questionValueRef));
+      questionObserver.observe(document.body, { childList: true, subtree: true });
+    }
+
     // ── 设置分区 UI --------------------------------------------------------------
     const divider = "rgba(0,0,0,0.08)";
     const hintColor = "rgba(0,0,0,0.45)";
@@ -497,6 +538,44 @@ window.__ModuleLoader__.load({
     const buttonStyle = { padding: "6px 14px", borderRadius: 8, border: "1px solid rgba(0,0,0,0.22)", background: "transparent", cursor: "pointer", fontSize: 13, fontWeight: 500 };
     const inputRangeStyle = { flex: 1, minWidth: 140 };
 
+    /**
+     * 缓冲滑块(React state 本地缓冲,最流畅):拖动期间 onChange 只更新本地 state
+     * (仅重渲染这一个 input + 显示值,不写设置、不触发 document-updated 广播),
+     * 松手(mouseup/touchend)/失焦(blur)/键盘结束(keyup)时才提交一次 scope.set。
+     * 原实现 onChange 每动一格都 update → settings.yaml 写盘 + 全量广播 + 整块面板
+     * 重渲染,所以拖动卡。
+     * @param {{fieldKey:string, labelText:string, min:number, max:number, step:number,
+     *   value:number, disabled:boolean, display:(n:number)=>string, onSubmit:(n:number)=>void}} props
+     */
+    function BufferedSlider(props) {
+      const [v, setV] = React.useState(Number.isFinite(Number(props.value)) ? Number(props.value) : 0);
+      // 外部值变化(另一标签/外部编辑)时同步进本地缓冲。拖动中 onChange 只 setV
+      // 不写盘,props.value 不变,此 effect 不会打断拖动;提交后值已一致,幂等。
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      React.useEffect(() => { setV(Number.isFinite(Number(props.value)) ? Number(props.value) : 0); }, [props.value]);
+      const commit = () => props.onSubmit(v);
+      return h("div", { style: rowStyle },
+        h("span", { style: labelStyle }, props.labelText),
+        h("span", { style: controlStyle },
+          h("input", {
+            type: "range",
+            min: props.min, max: props.max, step: props.step,
+            value: v,
+            disabled: props.disabled,
+            style: inputRangeStyle,
+            // 拖动中:只更新本地 state(不写盘)。React 对 range 的 onChange 即 input
+            // 事件,随拖动连续触发——现在每次只是 setState,不重渲染整块面板。
+            onChange: (ev) => setV(Number(ev.target.value)),
+            // 松手 / 失焦 / 键盘操作结束时才提交一次。
+            onMouseUp: commit,
+            onTouchEnd: commit,
+            onBlur: commit,
+            onKeyUp: commit,
+          }),
+          h("span", { style: valueStyle }, props.display(v))),
+      );
+    }
+
     function DingSection(props) {
       // The renderer binds the injected hooks compartment ('ding' key) into a
       // use<Name> hook; the store is the bare observable, so a selector reads
@@ -507,56 +586,57 @@ window.__ModuleLoader__.load({
       const ph = hintStyle;
       if (snap.status === "unavailable") {
         return h("div", { style: wrapStyle },
-          h("h2", { style: titleStyle }, "回合结束提示音"),
+          h("h2", { style: titleStyle }, "提示音配置"),
           h("p", { style: ph }, "设置不可用(宿主端未注册 falling-ts-web-ding 命名空间)。"));
       }
       if (snap.status === "loading" || value === undefined) {
         return h("div", { style: wrapStyle },
-          h("h2", { style: titleStyle }, "回合结束提示音"),
+          h("h2", { style: titleStyle }, "提示音配置"),
           h("p", { style: ph }, "加载中…"));
       }
       const disabled = !snap.writable;
       const v = (value && typeof value === "object") ? value : {};
       const pct = (n) => Math.round((Number(n) || 0) * 100) + "%";
-      const sliderRow = (labelText, props2, display) => h("div", { key: labelText, style: rowStyle },
-        h("span", { style: labelStyle }, labelText),
-        h("span", { style: controlStyle },
-          h("input", { type: "range", disabled: disabled, style: inputRangeStyle, ...props2 }),
-          h("span", { style: valueStyle }, display)),
-      );
+      // 两块配置,共用模板:第一块"弹出用户选择"(question),第二块"回合结束"(turnEnd)。
+      const block = (blk, title, desc, previewBtn) => {
+        const E = "question" === blk ? "questionEnabled" : "turnEndEnabled";
+        const Vol = "question" === blk ? "questionVolume" : "turnEndVolume";
+        const Freq = "question" === blk ? "questionFreq" : "turnEndFreq";
+        const Decay = "question" === blk ? "questionDecayMs" : "turnEndDecayMs";
+        return [
+          h("h2", { key: blk + "-title", style: titleStyle }, title),
+          h("p", { key: blk + "-intro", style: introStyle }, desc),
+          h("div", { key: blk + "-enabled", style: rowStyle },
+            h("span", { style: labelStyle }, "启用"),
+            h("span", { style: controlStyle },
+              h("input", {
+                type: "checkbox",
+                checked: v[E] !== false,
+                disabled: disabled,
+                onChange: (ev) => update(E, ev.target.checked),
+              })),
+          ),
+          h(BufferedSlider, { key: blk + "-vol", labelText: "音量", min: 0, max: 1, step: 0.05, value: Number(v[Vol]) || 0.7, disabled: disabled, display: pct, onSubmit: (n) => update(Vol, n) }),
+          h(BufferedSlider, { key: blk + "-freq", labelText: "音色频率(Hz)", min: 120, max: 2000, step: 10, value: Number(v[Freq]) || 880, disabled: disabled, display: (n) => Math.round(n) + " Hz", onSubmit: (n) => update(Freq, n) }),
+          h(BufferedSlider, { key: blk + "-decay", labelText: "衰减时长(ms)", min: 100, max: 2000, step: 50, value: Number(v[Decay]) || 900, disabled: disabled, display: (n) => Math.round(n) + " ms", onSubmit: (n) => update(Decay, n) }),
+          h("div", { key: blk + "-preview", style: lastRowStyle },
+            h("span", { style: labelStyle }, "试听"),
+            h("span", { style: controlStyle },
+              h("button", { style: buttonStyle, disabled: disabled, onClick: previewBtn }, "播放一声")),
+          ),
+        ];
+      };
       return h("div", { style: wrapStyle },
-        h("h2", { style: titleStyle }, "回合结束提示音"),
-        h("p", { style: introStyle }, "agent 回合结束时(转入空闲)由浏览器 JS 播放一声合成“叮”——纯前端 Web Audio,宿主不发声、不弹 Windows/系统通知。"),
-        h("div", { key: "enabled", style: rowStyle },
-          h("span", { style: labelStyle }, "启用"),
-          h("span", { style: controlStyle },
-            h("input", {
-              type: "checkbox",
-              checked: v.enabled !== false,
-              disabled: disabled,
-              onChange: (ev) => update("enabled", ev.target.checked),
-            })),
-        ),
-        sliderRow("音量",
-          { min: 0, max: 1, step: 0.05, value: Number(v.volume) || 0.7, disabled: disabled, onChange: (ev) => update("volume", Number(ev.target.value)) },
-          pct(v.volume)),
-        sliderRow("音色频率(Hz)",
-          { min: 120, max: 2000, step: 10, value: Number(v.freq) || 880, disabled: disabled, onChange: (ev) => update("freq", Number(ev.target.value)) },
-          Math.round(Number(v.freq) || 880) + " Hz"),
-        sliderRow("衰减时长(ms)",
-          { min: 100, max: 2000, step: 50, value: Number(v.decayMs) || 900, disabled: disabled, onChange: (ev) => update("decayMs", Number(ev.target.value)) },
-          Math.round(Number(v.decayMs) || 900) + " ms"),
-        h("div", { key: "preview", style: lastRowStyle },
-          h("span", { style: labelStyle }, "试听"),
-          h("span", { style: controlStyle },
-            h("button", {
-              style: buttonStyle,
-              disabled: disabled,
-              onClick: () => play({ volume: v.volume, freq: v.freq, decayMs: v.decayMs }),
-            }, "播放一声")),
-        ),
+        h("h2", { style: { ...titleStyle, fontSize: 16 } }, "提示音配置"),
+        h("p", { style: introStyle }, "两种场景各自提示音,由浏览器 JS 纯前端 Web Audio 合成——宿主不发声、不弹 Windows/系统通知。设置写入 $DSH_HOME/settings.yaml 的 falling-ts-web-ding 段。"),
+        ...block("question", "弹出用户选择",
+          "harness 弹出用户选择题(浏览器对话区的选择题卡片)时播放一声“叮”,提醒你回来作答。检测走浏览器 DOM(QuestionComposer 的 data-question-key 锚点),宿主端不参与。",
+          () => play({ volume: v.questionVolume, freq: v.questionFreq, decayMs: v.questionDecayMs })),
+        ...block("turnEnd", "回合结束",
+          "agent 回合结束时(agent/status 转入 idle)播放一声“叮”。宿主只在命中 idle 转换时发信号,声音由浏览器合成。",
+          () => play({ volume: v.turnEndVolume, freq: v.turnEndFreq, decayMs: v.turnEndDecayMs })),
         h("p", { style: { gridColumn: "1 / 3", color: hintColor, fontSize: 12, lineHeight: 1.55 } },
-          "浏览器自动播放策略:首次与页面交互(点击/按键)或点击试听后,回合结束提示音才会出声。设置写入 $DSH_HOME/settings.yaml 的 falling-ts-web-ding 段。"));
+          "浏览器自动播放策略:首次与页面交互(点击/按键)或点击任一试听后,提示音才会出声。"));
     }
 
     /**
@@ -575,12 +655,20 @@ window.__ModuleLoader__.load({
             d.value = s.value;
             d.writable = s.writable;
           });
+          questionValueRef = s.value;                       // 供 question 观察器回调读取
+          installQuestionObserver(s.value);                 // 一次性安装 DOM 观察器(幂等)
           if (s.status === "ready") maybePlayFromValue(s.value);
         } catch { /* never let a cosmetic derive take down the panel */ }
       };
       const unsub = scope.subscribe(derive);
       derive();
       ctx.effect(() => unsub, "web-ding: scope subscription");
+      ctx.effect(() => () => {
+        if (questionObserver) {
+          questionObserver.disconnect();
+          questionObserver = null;
+        }
+      }, "web-ding: question observer cleanup");
       const injected = () => ({
         hooks: { ding: store },
         update: (field, value) => scope.set(field, value),
@@ -593,7 +681,7 @@ window.__ModuleLoader__.load({
         name: "settings.section",
         id: "web-ding",
         order: 80,
-        label: () => "回合结束提示音",
+        label: () => "提示音配置",
         inject: injected,
       }, DingSection));
     }