dsh-voice-mode 0.7.7 → 0.7.9

package/README.en.md

@@ -1,19 +1,24 @@
 # dsh-voice-mode
 
-[![npm version](https://img.shields.io/npm/v/dsh-voice-mode?style=flat-square)](https://www.npmjs.com/package/dsh-voice-mode)
-[![License](https://img.shields.io/github/license/qishuilalala/dsh-voice-mode?style=flat-square)](https://github.com/qishuilalala/dsh-voice-mode/blob/main/plugin/dsh-voice-mode/LICENSE)
-[![dsh-plugin](https://img.shields.io/badge/dsh--plugin-voice-brightgreen?style=flat-square)](https://github.com/topics/dsh-plugin)
-
-> Full-duplex voice conversation mode for DeepSeek Harness (dsh): speak, get a
-> spoken answer. Streamed zipformer2 ASR → editable draft → auto send → the
-> final reply is read out sentence-by-sentence via Edge TTS, and your voice
-> interrupts playback and the running turn. No API key.
->
+[![License: MIT](https://img.shields.io/github/license/qishuilalala/dsh-voice-mode?style=flat-square&color=blue)](../../LICENSE)
+[![Latest Release](https://img.shields.io/github/v/release/qishuilalala/dsh-voice-mode?style=flat-square&color=brightgreen&include_prereleases)](https://github.com/qishuilalala/dsh-voice-mode/releases)
+[![npm version](https://img.shields.io/npm/v/dsh-voice-mode?style=flat-square&color=orange)](https://www.npmjs.com/package/dsh-voice-mode)
+[![Tests: 325 passing](https://img.shields.io/badge/tests-325%20%E2%9C%93-2ea043?style=flat-square)](../../docs/rules/STATE.md)
+
+Full-duplex voice conversation mode for DeepSeek Harness (dsh): speak, get a
+spoken answer. Streamed zipformer2 ASR → editable draft → auto send → the
+final reply is read out sentence-by-sentence via Edge TTS, and your voice
+interrupts playback and the running turn. No API key.
+
 > 中文说明见 [README.md](./README.md)。
 
-> **Version note (0.6.0)**: Edge cloud TTS by default (fast & natural); local TTS (VITS / Kokoro, privacy-first) optional + HTTP hardening + model SHA256 pinning form the merged core; Kokoro adds a model-precision choice (`int8` default 109 MB / `fp32` better quality 311 MB); `wakeWord` (wake word) and `toolBeep` (tool-call beep) are fully wired; the early fork's `asrModel` (bilingual paraformer) and `punctuate` (neural punctuation) were removed — SenseVoice finalization already adds punctuation, and streaming ASR is fixed to zipformer2. Silence split defaults to 1500 ms.
+![dsh-voice-mode full-duplex voice conversation](https://raw.githubusercontent.com/qishuilalala/dsh-voice-mode/HEAD/assets/hero-banner.png)
+
+> **Version note (v0.7.9, 2026-09-18)**: **Wake-word pipeline overhaul** (Issue #10 + real-machine retest) — a harness driving the real engine pinpointed and fixed five flow defects: ① TTS echo polluting the standby segment while the agent reads (could not wake); ② only above-threshold frames uploaded, so trailing characters never flushed (wake word truncated); ③ discarding the whole segment on a wake hit (saying "wake word + command" in one breath sent only the tail); ④ the command hanging when the hit arrived after you stopped speaking; ⑤ pausing after the wake word closed the command window (command lost). **The wake word may now be said together with your command — it is stripped and never sent**, standby live-shows what it heard, and "wake word … pause … command" works. Otherwise as v0.7.7: Edge cloud TTS by default, local TTS (VITS / Kokoro) optional; silence split defaults to 1500 ms.
 
-## Fork enhancements (this repo)
+---
+
+## 🤝 Fork enhancements (this repo)
 
 - **Edge cloud TTS by default; local TTS optional (privacy-first)**: local VITS (Chinese) and local Kokoro (zh+en, 103 voices; `int8` default ~109 MB / `fp32` ~311 MB for better quality; native `sherpa-onnx-node` addon, no WASM memory limits) run in an isolated child process;
 - **103 Kokoro voices** (F0-measured gender labels, 4 favourite male voices pinned), browsed with a ◀▶ stepper;
@@ -22,24 +27,29 @@
 - **Long segments**: continuous listening stitches consecutive segments into one message (internally chunked at 30 s and concatenated across chunks); 1500 ms silence split by default; hold keeps pauses from splitting;
 - **Hardening**: session-existence check, loopback + Origin guards, per-endpoint rate limits, model SHA256 pinning, download-host allowlist.
 
-> ⚠️ The screenshots below (and `assets/demo.gif`) show the **upstream legacy single-button UI**; the current UI adds a mode-switch button next to the mic.
+> ⚠️ The screenshots above (and `assets/demo.gif`) show the **upstream legacy single-button UI**; the current UI adds a mode-switch button next to the mic.
 
-## Features
+---
 
+## ✨ Features
 
 - **Voice mode**: toggle with the microphone button in the input toolbar or the global shortcut `Ctrl+Shift+V`; globally single-active (only one session is in voice mode at a time; switching sessions yields automatically)
 - **Two interaction modes (switchable in settings, plus a mode-switch button beside the mic)**:
   - `toggle` (default) continuous listening: RMS VAD segmentation → streaming zipformer2 ASR (words appear as you speak, live caption preview) → automatic sentence split after 1500 ms of silence into the draft, consecutive segments joined into one message, then auto-sent after ~1500 ms more of silence (≈3 s total); hold `Ctrl` to force an immediate send
   - `hold` push-to-talk: short tap to enter/exit, **hold the mic button to talk, release to send** (swipe up to cancel, `Esc`/blur abandons the segment; pauses do not split while held, up to 10 min); hold `Ctrl` to record-by-keyboard, release to send
-- **Wake word (optional, off by default)**: after setting `wakeWord`, entering voice mode starts in standby, and recognition only begins once the wake word is spoken (e.g. `你好小D`), preventing accidental triggers
+- **Wake word (optional, off by default)**: after setting `wakeWord`, entering voice mode starts in standby, and recognition only begins once the wake word is spoken (e.g. `你好小D`). **You may say it together with your command** ("wake word, check the weather") — the wake word is stripped from the transcript/caption and never sent; matching is fault-tolerant (homophone substitutions, a wrong first char, leading fillers); 3-4 characters recommended; in standby the status bar live-shows "say '<word>' · what it heard". Boundaries (important): **toggle mode only** (inactive with `hold` / manual barge-in); **it must be repeated after each completed utterance or barge-in** (if you only said the wake word, the engine keeps listening so you may pause before the command); **saying it while the agent is reading does not trigger** (barge-in is VAD-based and unrelated to the wake word)
+- **Caption tiers (batch 3)**: `captionFontSize` 4 levels (0=12px / 1=14px / 2=18px / 3=24px) + `captionMaxWidth` 3 levels (0=50vw / 1=70vw / 2=90vw); adapts to narrow viewports
+- **Yield semantics (batch 5 / ADR-0008)**: `backchannelYield` on by default (I10-exempt) — saying `嗯 / 对 / right` while the AI is reading auto-pauses for 1.5 s; genuine speech still triggers hard barge-in; lets the LLM yield the turn
 - **Output pipeline**: only the final answer's `text-delta` is read (reasoning/tool calls are skipped), streamed sentence-by-sentence (Edge cloud by default; local VITS / Kokoro, int8/fp32, optional) with a live caption overlay at the bottom-right; tool calls trigger a beep; the full text is still written to the chat; in voice mode a spoken-format system prompt is injected (short natural sentences, no Markdown decoration), and the reader side strips markers as well for a smoother listening experience
-- **Barge-in**: three sensitivity levels of voice-onset detection → local mute + host synth queue invalidation (epoch) + running turn cancellation (the half-finished part is kept and naturally flows into your new message)
+- **Barge-in**: three sensitivity levels of voice-onset detection → local mute + host synth queue invalidation (epoch) + running turn cancellation (the half-finished part is kept and naturally flows into your new message). With a wake word set, barge-in **remains speak-to-interrupt** (the gate is the VAD, not the wake word; the engine returns to standby afterwards)
 - **Lazy model download with progress**: the zipformer2 Chinese streaming model (~160 MB, `.part` resumable) is downloaded on first use with live progress in the status bar; `npm run prefetch` can pre-download it
 - **Resilience**: mic-denied red hint, visible model-download failure, TTS unreachable status hint (auto retry), failed submit keeps the text in the draft, SSE auto-reconnect
-- **Settings**: Settings → Plugins → voice-mode, with voice / rate / interrupt sensitivity / silence pause / idle timeout / model mirror / auto send / interaction mode / wake word; **voices are previewable** (the "试听/Preview" button synthesizes and plays the current voice at the current rate instantly, no need to enter voice mode; custom ShortNames are previewable too)
-- **Idle exit**: auto-exit and mic release after 10 minutes of inactivity
+- **Settings**: Settings → Plugins → voice-mode, with voice / rate / interrupt sensitivity / silence pause / idle timeout / model mirror / auto send / interaction mode / wake word / ITN / caption tiers / yield semantics; **voices are previewable** (the "试听/Preview" button synthesizes and plays the current voice at the current rate instantly, no need to enter voice mode; custom ShortNames are previewable too)
+- **Idle exit**: auto-exit and mic release after 5 minutes of inactivity (reading counts as activity; batch J 10→5)
+
+---
 
-## Interaction gestures
+## ⌨️ Interaction gestures
 
 | Gesture | Behaviour |
 | --- | --- |
@@ -52,7 +62,9 @@
 | Speak while AI is reading | Interrupt playback and cancel the running turn |
 | Type in the input box | Auto-exit voice mode (draft is kept) |
 
-## Installation
+---
+
+## 🚀 Quick Start (5 minutes)
 
 **Requirements**: dsh web (Node ≥ 18), a modern browser (Chrome / Edge / Firefox, supporting `getUserMedia` and Web Audio).
 
@@ -83,7 +95,7 @@ npm run prefetch          # run inside the plugin dir; writes to the platform ca
 # or specify the cache location: node scripts/prefetch.mjs --cache-dir /where/ever/models
 ```
 
-## Usage
+**First run**:
 
 1. Click the mic button in the input toolbar (or press `Ctrl+Shift+V`) to enter voice mode; a status bar appears above the input box
 2. Choose how to speak: just talk and let the ~1500 ms pause split and ~3 s of quiet auto-send (toggle); or hold the mic button and release to send (hold)
@@ -94,21 +106,49 @@ On first entry the recognition model is downloaded; the status bar shows `正在
 
 If a wake word is configured, you land in standby first (the status bar prompts `说『唤醒词』开始`), and recognizing starts after you speak the wake word.
 
-## Settings (Settings → Plugins → Plugins config → 语音模式)
+---
+
+## ⚙️ Settings (Settings → Plugins → Plugins config → 语音模式)
+
+### 4 new settings (11 batches of comprehensive fixes)
+
+| Key | Default | Description |
+| --- | --- | --- |
+| `senseITN` | `true` | Batch 2 P0: SenseVoice inverse text normalization (number / date / currency; on by default) |
+| `captionFontSize` | `0` | Batch 3 P0: caption font tier 0=12px / 1=14px / 2=18px / 3=24px (default 0 is byte-equivalent to legacy) |
+| `captionMaxWidth` | `1` | Batch 3 P0: caption width tier 0=50vw / 1=70vw / 2=90vw |
+| `backchannelYield` | `true` | Batch 5 P1: yield semantics (ADR-0008); saying `嗯 / 对` while reading auto-pauses for 1.5 s; genuine speech still triggers hard barge-in. I10-exempt (default-on is a product decision); off = behavior identical to pre-change |
+
+### 5 defaults micro-adjusted (batch J)
+
+| Key | Old | New | Why |
+| --- | --- | --- | --- |
+| `rate` | 1.0 | **1.1** | Edge TTS defaults slightly slow; +10% improves perceived quality |
+| `idleTimeoutMinutes` | 10 | **5** | More responsive idle exit (reading still counts as activity) |
+| `interruptLevel` description | old wording | new wording | Make "3/2/1 frame confirmation" explicit |
+
+> Field names unchanged → 100% backward compatible with existing `~/.dsh/settings.yaml`.
+
+### Full 19-key settings table
 
 | Key | Default | Description |
 | --- | --- | --- |
 | `ttsEngine` | `edge` | Read-aloud engine: `edge` Microsoft cloud (default, fast) / `vits` local Chinese / `kokoro` local zh+en; **applies live** |
 | `kokoroModel` | `int8` | Kokoro precision: `int8` (default, 109 MB, CPU/low-bandwidth) / `fp32` (311 MB, better quality, GPU/large memory); same 103 voices; **applies live** |
 | `voice` | per engine | Voice: 5 VITS speakers; 103 Kokoro voices (◀▶ stepper; 62/68/75/76 favourite males pinned); Edge ShortNames below. The inline "试听" button previews it at the current rate |
-| `rate` | `1.0` | Reading speed multiplier (0.5 slow ～ 2.0 fast), **applies live** |
-| `interruptLevel` | `0` | Barge-in sensitivity (host-side VAD frame detection + echo gate): 0 high threshold / 1 medium / 2 low |
+| `rate` | `1.1` | Reading speed multiplier (0.5 slow ～ 2.0 fast), **applies live** (batch J 1.0→1.1) |
+| `interruptLevel` | `0` | Barge-in sensitivity (host-side VAD frame detection + echo gate): 0 high threshold (3 frames) / 1 medium (2 frames) / 2 low (1 frame) |
 | `silenceMs` | `1500` | Silence pause in ms that marks the end of a complete sentence |
-| `idleTimeoutMinutes` | `10` | Minutes of inactivity before auto-exiting voice mode (reading counts as activity) |
+| `idleTimeoutMinutes` | `5` | Minutes of inactivity before auto-exiting voice mode (reading counts as activity; batch J 10→5) |
 | `modelHost` | default | Model download host (use `https://hf-mirror.com` on mainland networks) |
 | `autoSend` | `true` | Auto-send once quiet (consecutive segments join into one message); when off, text only goes to the draft (hold `Ctrl` / release in hold mode still sends) |
 | `mode` | `toggle` | Interaction mode: `toggle` continuous listening + 1500 ms silence split; `hold` push-to-talk, release to send (short tap exits) |
-| `wakeWord` | empty (off) | Wake word (e.g. `你好小D`): speak it after entering to activate, avoiding accidental triggers; empty = off |
+| `wakeWord` | empty (off) | Wake word (e.g. `你好小D`): speak it after entering to activate; empty = off. **May be said together with your command** — the wake word is stripped and never sent; fault-tolerant matching (edit distance ≤1 + a 3-char leading window absorbs homophones/fillers); **3-4 characters recommended** (single-char words get no tolerance; a 2-char word also absorbs any same-first-char 2-char word); must be repeated after each utterance split or barge-in; **toggle mode only**; not triggered while the agent is reading |
+| `spokenFormat` | `true` | Spoken-format system prompt: inject "short natural sentences, no Markdown decoration" into voice-mode replies only, **applies live** |
+| `senseITN` | `true` | Batch 2 P0: SenseVoice inverse text normalization (number / date / currency; on by default) |
+| `captionFontSize` | `0` | Batch 3 P0: caption font tier 0=12px / 1=14px / 2=18px / 3=24px (default 0 is byte-equivalent to legacy) |
+| `captionMaxWidth` | `1` | Batch 3 P0: caption width tier 0=50vw / 1=70vw / 2=90vw |
+| `backchannelYield` | `true` | Batch 5 P1: yield semantics (ADR-0008); saying `嗯 / 对` while reading auto-pauses for 1.5 s; genuine speech still triggers hard barge-in. I10-exempt (default-on is a product decision); off = behavior identical to pre-change |
 
 Effect timing: `voice`/`rate`/`ttsEngine`/`kokoroModel`/`spokenFormat` take effect **immediately** (TTS hot-swap); the rest apply on the next voice-mode entry. Defaults come from the plugin config (`base` layer) — they follow the config unless explicitly changed.
 
@@ -131,7 +171,9 @@ Effect timing: `voice`/`rate`/`ttsEngine`/`kokoroModel`/`spokenFormat` take effe
 | `en-US-AriaNeural` | Aria · English · Female |
 | `en-US-GuyNeural` | Guy · English · Male |
 
-## Configuration (bundle patch / settings.yaml)
+---
+
+## 🔧 Configuration (bundle patch / settings.yaml)
 
 You can also edit the `voice-mode:` section of `~/.dsh/settings.yaml` directly (the GUI card and RPC write to the same document layer):
 
@@ -143,10 +185,10 @@ You can also edit the `voice-mode:` section of `~/.dsh/settings.yaml` directly (
     cacheDir: ~/.cache/dsh-voice-mode/models   # overridable; platform default otherwise
     # Defaults seeded for the settings (the settings panel overrides; the panel is authoritative):
     voice: zh-CN-XiaoxiaoNeural
-    rate: 1.0
+    rate: 1.1                     # batch J 1.0→1.1
     interruptLevel: 0
     silenceMs: 1500
-    idleTimeoutMinutes: 10
+    idleTimeoutMinutes: 5         # batch J 10→5
     modelHost: https://huggingface.co
 ```
 
@@ -155,7 +197,9 @@ You can also edit the `voice-mode:` section of `~/.dsh/settings.yaml` directly (
 > (`enabled/cacheDir` remain bundle-config-only).
 > The plugin HTTP namespace is fixed to `/voice-mode` (matching the client bundle contract; not configurable).
 
-## API
+---
+
+## 🌐 API
 
 | Route | Description |
 | --- | --- |
@@ -164,10 +208,12 @@ You can also edit the `voice-mode:` section of `~/.dsh/settings.yaml` directly (
 | `POST /voice-mode/asr` | Raw f32 LE 16k PCM payload → `{text}` (streaming zipformer2); returns `202 {loading}` until the model is ready; `?reset=1` discards the in-flight segment (used on wake-word hit) |
 | `POST /voice-mode/cancel` | `{sessionId}` invalidates the TTS queue and drops the in-flight ASR segment |
 | `POST /voice-mode/preview` | `{voice, rate?}` one-shot synthesis preview → `audio/mpeg` (400 missing voice / voice too long; 502 synthesis failure, e.g. invalid ShortName; 403 when the plugin's `enabled=false`). Does not require voice mode to be active; uses an isolated synthesis connection and does not affect the reading queue |
-| `GET /voice-mode/config` | Client bootstrap parameters (silence threshold / sensitivity / voice and rate, etc.) |
+| `GET /voice-mode/config` | Client bootstrap parameters (silence threshold / sensitivity / voice and rate, etc.) — includes 4 new ASR fields: `senseITN` / `senseVoice` / `captionFontSize` / `captionMaxWidth` / `backchannelYield` |
 | `GET /voice-mode` | Health check `{ok, name, enabled, active}` |
 
-## Model & cache
+---
+
+## 💾 Model & cache
 
 - Recognition model: `csukuangfj/sherpa-onnx-streaming-zipformer-zh-int8-2025-06-30` (encoder ≈154 MB / decoder / joiner / tokens, ~160 MB total), running host-side via sherpa-onnx (Node WASM, Apache-2.0, natively cross-platform)
 - Cache directory defaults by platform:
@@ -176,18 +222,43 @@ You can also edit the `voice-mode:` section of `~/.dsh/settings.yaml` directly (
   - both overridable via `cacheDir`
 - Downloads use `.part` resume; `huggingface.co` falls back to `hf-mirror.com` on failure (configurable via `modelHost`)
 
-## How it works
-
-![architecture](https://raw.githubusercontent.com/qishuilalala/dsh-voice-mode/HEAD/plugin/dsh-voice-mode/assets/architecture.svg)
-
-```
-input:  mic ──RMS VAD (1500 ms silence split)──▶ POST /voice-mode/asr (f32 PCM, 16k, incremental)
-                                            │ zipformer2 streaming ASR (host-side WASM)
-                                            ▼
-        composer draft ──autoSend──▶ model stream ──llm/stream tap (active voice session only)
-                                            │ text-delta filter → sentence segmentation
-                                            ▼
-        browser ◀── SSE /voice-mode/stream ◀── TtsQueue (local VITS / native Kokoro / Edge, sentence-by-sentence)
+---
+
+## 🏛️ How it works
+
+```mermaid
+flowchart LR
+    subgraph Client[Browser Client]
+        Mic[Microphone 16kHz<br/>AudioWorklet<br/>echoCancellation:true] --> VAD[Client-side VAD<br/>RMS segmentation]
+        VAD -->|partial 0.9s| UI[Statusbar + caption overlay]
+    end
+
+    subgraph Host[dsh.host]
+        ASR[zipformer2 streaming ASR<br/>host-side WASM]
+        SV[SenseVoice finalization<br/>+ ITN + punctuation]
+        Tap[llm/stream tap<br/>observe-only]
+        Seg[sentence segmenter]
+        Q[TtsQueue<br/>epoch barge-in]
+        TTS{Engine}
+        Edge[Edge cloud]
+        Vits[Local VITS WASM]
+        Kokoro[Local Kokoro<br/>native addon]
+    end
+
+    UI -->|audio f32 PCM<br/>POST /voice-mode/asr| ASR
+    ASR --> SV
+    SV --> Draft[composer draft<br/>autoSend]
+    Draft --> Tap
+    Tap --> Seg
+    Seg --> Q
+    Q --> TTS
+    TTS -->|edge| Edge
+    TTS -->|vits| Vits
+    TTS -->|kokoro| Kokoro
+    Edge -.->|SSE audio frame| UI
+    Vits -.->|SSE audio frame| UI
+    Kokoro -.->|SSE audio frame| UI
+    VAD -.->|wake-word / barge-in| Q
 ```
 
 - Speech and reading only happen for the session pointed to by the global single-active pointer `activeVoiceSession`; other sessions pass through `llm/stream` with zero overhead (mode isolation)
@@ -196,7 +267,24 @@ input:  mic ──RMS VAD (1500 ms silence split)──▶ POST /voice-mode/asr
 - Local TTS (VITS / native Kokoro) runs in an isolated child process (fork, auto-restart); barge-in kills the in-flight synthesis instantly to free CPU
 - The TTS queue is per-session with an epoch version: old frames are all invalidated after a barge-in, so it is truly silent
 
-## Known limitations
+---
+
+## 🔍 Comparison with dsh built-in voice mode
+
+| Dimension | dsh built-in | dsh-voice-mode (this plugin) |
+| --- | --- | --- |
+| Recognition model | Cloud API (needs key) | **Local zipformer2 + SenseVoice** (zero key) |
+| Multi-language | English-first | **SenseVoice auto-recognition + ITN** |
+| TTS engine | Cloud TTS | **Edge cloud + local VITS/Kokoro** (three-way switch) |
+| Barge-in detection | Basic VAD | **3 sensitivity levels + echo gate + yield semantics** |
+| Hotword biasing | None | None (removed in v0.7.7; see version note) |
+| Caption a11y | None | **4 font tiers + 3 width tiers + theme-following** |
+| Wake word | None | **Lightweight streaming match + prefix filler whitelist** |
+| dsh compatibility | — | **0.1.1-rc.2 → 0.1.5-rc.2 full range** |
+
+---
+
+## 🚧 Known limitations
 
 - Barge-in relies on browser echo cancellation (`echoCancellation`); loud speaker volume may leak into the mic (no JS-level AEC)
 - `Ctrl+Shift+V` overrides the browser's "paste as plain text" shortcut (normal `Ctrl+V` paste still works)
@@ -207,7 +295,9 @@ input:  mic ──RMS VAD (1500 ms silence split)──▶ POST /voice-mode/asr
 - The hero (new-session empty state) has no voice entry: voice mode is a session-level feature; enter a session first and use the mic button in the input toolbar
 - The preview request timeout uses `AbortSignal.timeout` (Chrome 103+ / Firefox 100+ / Safari 16+); on older browsers clicking preview immediately shows a failure hint — an expected degradation
 
-## Troubleshooting
+---
+
+## 🛠️ Troubleshooting
 
 | Symptom | Fix |
 | --- | --- |
@@ -219,8 +309,26 @@ input:  mic ──RMS VAD (1500 ms silence split)──▶ POST /voice-mode/asr
 | Poor recognition | Get closer to the mic, reduce ambient noise; if echo remains, raise the interrupt sensitivity by one step |
 | Hold mode has no effect | Make sure hold mode is active and you're in voice mode (button shows `按住说话`); the browser window must be in the foreground |
 | Preview button reports synthesis failure | Edge TTS unreachable (overseas) or the ShortName doesn't exist: verify the name (`node scripts/list-voices.mjs` lists all) and retry later |
+| Caption is hidden behind the input box | Default `captionMaxWidth=1` (70vw) + `captionFontSize=0` (12px) can overlap the bottom input on narrow viewports; raise the tier or click the caption's `×` to dismiss |
+| Yield behavior is wrong (saying `嗯` doesn't pause / real speech gets hard-barge) | Short backchannel words (`嗯 / 对`) auto-pause 1.5 s then reading resumes; continuing to speak triggers hard barge-in; disable `backchannelYield` to restore pre-change behavior (ADR-0008) |
+| Says `嗯` but no yield happens | Confirm `backchannelYield=true` (default on); in hold mode, continuing to talk within 1.5 s of release triggers hard barge-in |
+| Auto-exits after 5 minutes idle (don't want) | Raise `idleTimeoutMinutes` (default 5 min, **reading counts as activity**) |
+
+---
+
+## 🛣️ Roadmap
 
-## Development
+Full backlog (43 P0-P3 items) at [`docs/competitive/backlog.md`](../../docs/competitive/backlog.md).
+
+- ✅ **Done (v0.7.7)**: 11 batches of comprehensive fixes (caption tiers / yield semantics / model prewarm / defaults micro-adjust / dead-code cleanup / etc.)
+- 🚧 **P0 (near-term)**: ADR-0003 client-side VAD / ADR-0006 first-level probe wired to manual / F1 emotion DSL full roll-out
+- 📋 **P1 (mid-term)**: MCP `voice_*` toolset / card form draft validate / status-bar idle polish
+- 💡 **P2 (far-term)**: Voice cloning (user-deferred) / ADR-0004 WebSocket transport
+- ⏸️ **Deferred**: xAI fallback / C1 persona layer (user-deferred)
+
+---
+
+## 🛠️ Development
 
 ### Dependency discipline (important)
 
@@ -277,6 +385,8 @@ scripts/list-voices.mjs   print all Edge TTS voices (source of the voice table)
 
 Integration probes (`hold-e2e.js`, `spoken-prompt-rpc.sh`, `spoken-toggle-ui-check.js`) live in the repo root `test/`, outside this npm package.
 
-## License
+---
+
+## 📄 License
 
-MIT
+[MIT](../../LICENSE)

package/README.md

@@ -1,9 +1,9 @@
 # dsh-voice-mode
 
-[![npm version](https://img.shields.io/npm/v/dsh-voice-mode?style=flat-square)](https://www.npmjs.com/package/dsh-voice-mode)
-[![License](https://img.shields.io/github/license/qishuilalala/dsh-voice-mode?style=flat-square)](LICENSE)
-[![dsh-plugin](https://img.shields.io/badge/dsh--plugin-voice-brightgreen?style=flat-square)](https://github.com/topics/dsh-plugin)
-[![awesome-dsh-plugin](https://img.shields.io/badge/awesome--dsh--plugin-listed-2ea043?style=flat-square)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin#plugins)
+[![License: MIT](https://img.shields.io/github/license/qishuilalala/dsh-voice-mode?style=flat-square&color=blue)](LICENSE)
+[![Latest Release](https://img.shields.io/github/v/release/qishuilalala/dsh-voice-mode?style=flat-square&color=brightgreen&include_prereleases)](https://github.com/qishuilalala/dsh-voice-mode/releases)
+[![npm version](https://img.shields.io/npm/v/dsh-voice-mode?style=flat-square&color=orange)](https://www.npmjs.com/package/dsh-voice-mode)
+[![Tests: 325 passing](https://img.shields.io/badge/tests-325%20%E2%9C%93-2ea043?style=flat-square)](../../docs/rules/STATE.md)
 
 DeepSeek Harness 语音双工对话模式：会话内一键进入 → 边说边出字的流式识别 → 停顿自动发送 → 最终答复按句流式朗读 + 实时字幕，开口即可打断（真 barge-in）。无需 API Key，识别模型在本地宿主端推理。
 
@@ -13,11 +13,13 @@ DeepSeek Harness 语音双工对话模式：会话内一键进入 → 边说边
 
 ![语音模式：实时字幕与状态条](https://raw.githubusercontent.com/qishuilalala/dsh-voice-mode/HEAD/assets/screenshot-voice.png)
 
-> **版本说明（0.6.0）**：朗读默认 **Edge 云端**（快速自然），本地 TTS（VITS / Kokoro）可选（隐私优先）+ HTTP 安全加固 + 模型 SHA256 固定为合入核心；Kokoro 新增**模型精度可选**（`int8` 默认 109MB / `fp32` 音质更好 311MB）；`wakeWord`（唤醒词）与 `toolBeep`（工具提示音）已完整接入；早期 fork 的 `asrModel`（双语 paraformer）与 `punctuate`（神经标点）已移除——SenseVoice 定稿本身已带标点，流式识别固定为 zipformer2。静音断句默认 1500 毫秒。
+> **版本说明（v0.7.9，2026-09-18）**：**唤醒词链路全面修复**（Issue #10 + 真机复测）——台架驱动真引擎逐项定位并修掉五处流程缺陷：① 朗读期 TTS 回声污染待机段（喊不醒）；② 只上传超门限帧导致尾字不 flush（唤醒词只剩半截）；③ 唤醒命中丢整段（连说「唤醒词+命令」只发出去尾部几个字）；④ 命中晚于停口时命令悬挂不定稿；⑤ 只喊唤醒词后停顿会关掉命令窗口（命令丢失）。**现在唤醒词可与命令连说、词头自动剥离不进消息**，待机态实时显示「它听到了什么」，支持「唤醒词…停顿…命令」。其余同 v0.7.7：朗读默认 Edge 云端，本地 TTS（VITS / Kokoro）可选；静音断句默认 1500 毫秒。
 
-## Fork 增强（本仓库新增）
+---
 
-本仓库在上游基础上加入了大量增强，核心如下（完整清单见 git 历史与迭代记录）：
+## 🤝 Fork 增强（本仓库新增）
+
+本仓库在上游 [haoku123/dsh-voice](https://github.com/haoku123/dsh-voice) 基础上加入了大量增强，核心如下（完整清单见 git 历史与 [docs/rules/STATE.md](../../docs/rules/STATE.md)）：
 
 - **朗读默认 Edge 云端；本地 TTS 可选（隐私优先）**：选本地则回复文本不出本机——
   - 本地 VITS（`sherpa-onnx-vits-zh-ll`，纯中文，5 说话人）；
@@ -32,22 +34,28 @@ DeepSeek Harness 语音双工对话模式：会话内一键进入 → 边说边
 
 > ⚠️ 上文截图与 `assets/demo.gif` 为**上游旧版界面**（单按钮时期）；当前界面在语音按钮旁多一颗「模式切换」按钮。
 
-## 功能
+---
+
+## ✨ 功能
 
 - **语音模式**：输入框工具排麦克风按钮或全局快捷键 `Ctrl+Shift+V` 进入/退出；全局单活（同一时刻仅一个会话处于语音模式，切换会话自动让出）
 - **两种交互模式（输入框旁按钮或设置可切换，切换即持久化）**：
   - `toggle`（默认）持续聆听：RMS VAD 分段 → zipformer2 流式识别（边说边出字，实时字幕预览）→ 静音约 1500 毫秒断句进草稿，连续多段拼成一条消息，再静音约 1500 毫秒（合计约 3 秒）自动发送；按住 `Ctrl` 强制立即发送
   - `hold` 按住说话：短按进入/退出，**按住麦克风按钮说话、松手即发**（滑出取消、`Esc`/失焦放弃本段）；按住期间停顿不断句（上限 10 分钟）；`Ctrl` 按住即录、松开即发
-- **唤醒词（可选，默认关）**：设置 `wakeWord` 后进入待机态，说出唤醒词才开始识别（如「你好小D」）
+- **唤醒词（可选，默认关）**：设置 `wakeWord` 后进入待机态，说出唤醒词才开始识别（如「你好小D」）。**可直接与命令连说**（「你好小D，帮我查天气」）——唤醒词会在定稿/字幕里自动剥掉、不进消息；匹配带容错（同音字替换「小莫→小墨」、首字错、前置语气词「呃/喂/我说」），建议 3-4 字；待机态状态条实时显示「说『x』开始 · 它听到的转写」，唤醒成败可自查。边界（重要）：**仅 `toggle` 模式生效**（`hold` / 手动打断下唤醒词静默失效）；**说完整一句后回到待机态需重说唤醒词**（只喊唤醒词、还没说命令时保持聆听，可停顿想好再说）；**朗读期说唤醒词不触发**（打断由 VAD 开口即触发，与唤醒词无关）
+- **字幕档位**（批 3）：`captionFontSize` 4 档（0=12px / 1=14px / 2=18px / 3=24px）+ `captionMaxWidth` 3 档（0=50vw / 1=70vw / 2=90vw），窄屏自适应
+- **让位语义**（批 5 / ADR-0008）：`backchannelYield` 默认开（I10 豁免）—— 朗读期用户插话「嗯/对」自动让位 1.5s，真要说走硬打断；让 LLM 主动让出话轮（人格层让位）；关掉恢复改造前行为
 - **输出链路**：只朗读最终答复的 `text-delta`（reasoning/工具调用不读），按句流式朗读（默认 Edge 云端；可切本地 VITS/Kokoro，中英混读选 Kokoro）+ 右下角实时字幕浮层；工具调用触发提示音；全文照常写入聊天记录；口语化提示词（设置 `spokenFormat`，默认开）让回复为自然短句、不带 Markdown 排版符号
-- **开口打断（barge-in）**：服务端 Silero VAD 帧级检测 + 回声门控（echoGateDb）三档灵敏度 → 本地静音 + host 合成队列作废 + 正在运行的回合取消（保留半截并自然续入新消息）；朗读中自动切超灵敏档
+- **开口打断（barge-in）**：服务端 Silero VAD 帧级检测 + 回声门控（echoGateDb）三档灵敏度 → 本地静音 + host 合成队列作废 + 正在运行的回合取消（保留半截并自然续入新消息）；朗读中自动切超灵敏档。开启唤醒词后打断**仍是开口即打断**（打断门控是 VAD，不是唤醒词；打断后回待机态）
 - **模型懒加载与进度**：首次使用自动下载识别/合成模型（`.part` 断点续传），状态条实时显示进度；可用 `npm run prefetch` 预下载
-- **设置**：设置 → Plugins → 插件配置 → 语音模式（voice-mode），可调朗读引擎/音色/语速/打断灵敏度/静音停顿/空闲超时/模型镜像/自动发送/交互模式/唤醒词/口语化提示词；**音色可试听**（按当前音色+语速即时合成预览，自定义 ShortName 亦可）
+- **设置**：设置 → Plugins → 插件配置 → 语音模式（voice-mode），可调朗读引擎/音色/语速/打断灵敏度/静音停顿/空闲超时/模型镜像/自动发送/交互模式/唤醒词/口语化提示词/字幕档位/让位语义；**音色可试听**（按当前音色+语速即时合成预览，自定义 ShortName 亦可）
 - **界面语言**：跟随浏览器语言（中文 / English；切换后刷新页面生效）
 - **容错**：麦克风被拒红点提示、模型下载失败可见提示、TTS 连接失败状态条提示（自动退避重试）、提交失败文字留在草稿、SSE 断线自动重连
-- **空闲退出**：10 分钟无活动自动退出并释放麦克风（**正在朗读计为活动**，长朗读不会中途下线）
+- **空闲退出**：5 分钟无活动自动退出并释放麦克风（**正在朗读计为活动**，长朗读不会中途下线；批 J 已微调默认 10→5）
+
+---
 
-## 安装
+## 🚀 5 分钟上手（Quick Start）
 
 ```sh
 dsh plugin --profile web add dsh-voice-mode
@@ -55,7 +63,15 @@ dsh plugin --profile web add dsh-voice-mode
 
 bundle 插件安装后需重启 dsh 生效（Linux：`systemctl restart dsh`；其他平台重启 dsh 进程）。
 
-## 操作手势
+**第一次用**：
+
+1. 进入任一会话，按 `Ctrl+Shift+V`（或点输入区麦克风按钮）进入语音模式，状态条显示「聆听中…」；
+2. 说一句完整的话（如「帮我看看今天的天气」）→ 实时字幕立即出现，停顿后自动发送；
+3. AI 回复开始朗读时，**开口说话 → 朗读即刻停止，你的话被听见**（这就是 barge-in）。
+
+---
+
+## ⌨️ 操作手势
 
 | 手势 | 作用 |
 | --- | --- |
@@ -68,22 +84,28 @@ bundle 插件安装后需重启 dsh 生效（Linux：`systemctl restart dsh`；
 | 点状态条「退出」 | 退出语音模式 |
 | 点字幕浮层「跳过」 | 跳过当前句朗读 |
 
-## 设置（设置 → Plugins → 插件配置 → 语音模式）
+---
+
+## ⚙️ 设置（设置 → Plugins → 插件配置 → 语音模式）
 
 | 键 | 默认 | 说明 |
 | --- | --- | --- |
 | `ttsEngine` | `edge` | 朗读引擎：`edge` 微软云端（默认，快）/ `vits` 本地中文 / `kokoro` 本地中英；**即时生效** |
 | `kokoroModel` | `int8` | Kokoro 模型精度：`int8`（默认，109MB，纯 CPU/低带宽推荐）/ `fp32`（311MB，音质更好，独显/大内存推荐）；两档共用 103 音色，**即时生效** |
 | `voice` | 按引擎 | 音色：VITS 五说话人；Kokoro 103 个（下拉+◀▶，62 深沉/68 浑厚/75 清亮/76 磁性置顶）；Edge 进入时自动加载全量 322 个。行内「试听」可即时预览 |
-| `rate` | `1.0` | 朗读语速倍率（0.5 慢速 ～ 2.0 快速），**即时生效** |
-| `interruptLevel` | `0` | 发声打断灵敏度（服务端 VAD 帧级检测 + 回声门控）：0 高门槛 / 1 中 / 2 低 |
+| `rate` | `1.1` | 朗读语速倍率（0.5 慢速 ～ 2.0 快速），**即时生效**（批 J 1.0→1.1） |
+| `interruptLevel` | `0` | 发声打断灵敏度（服务端 VAD 帧级检测 + 回声门控）：0 高门槛（3 帧）/ 1 中（2 帧）/ 2 低（1 帧） |
 | `silenceMs` | `1500` | 说完整一句的静音停顿毫秒数 |
-| `idleTimeoutMinutes` | `10` | 无活动自动退出语音模式的分钟数（朗读计为活动） |
+| `idleTimeoutMinutes` | `5` | 无活动自动退出语音模式的分钟数（朗读计为活动；批 J 10→5） |
 | `modelHost` | 默认源 | 模型下载源（国内网络填 `https://hf-mirror.com`） |
 | `autoSend` | `true` | 静音到点自动发送（连续多段拼成一条消息）；关闭则只进草稿（按住 `Ctrl` / hold 松手仍会发送） |
 | `mode` | `toggle` | 交互模式：`toggle` 持续聆听 + 1500ms 静音断句；`hold` 按住说话、松手发送（短按退出） |
-| `wakeWord` | 空（关） | 唤醒词（如「你好小D」）：进入后先说唤醒词激活，避免误触；空 = 关闭 |
+| `wakeWord` | 空（关） | 唤醒词（如「你好小D」）：进入后先说唤醒词激活，避免误触；空 = 关闭。**可与命令连说**，词头自动剥掉不进消息；匹配带容错（编辑距离 ≤1 + 前 3 字符前导窗口，吸收同音字/语气词）；**建议 3-4 字**——单字词无容错、2 字词的容错会连带吸收所有同首字的 2 字词（如「小莫」也会唤醒「小张」），介意误唤醒用 3 字以上；每句断句或打断后回待机需重说；**仅 toggle 模式生效**（hold / 手动打断下不生效）；朗读期说唤醒词不触发 |
 | `spokenFormat` | `true` | 语音会话注入口语化提示词：开启后**仅当前语音会话**的回复被注入「口语化短句、不用 Markdown 排版符号」提示词（朗读更顺），**即时生效** |
+| `senseITN` | `true` | 批 2 P0：SenseVoice 逆文本归一化（数字/日期/货币规范化；默认开） |
+| `captionFontSize` | `0` | 批 3 P0：字幕字号档位 0=12px / 1=14px / 2=18px / 3=24px（默认 0 与现状字节等价） |
+| `captionMaxWidth` | `1` | 批 3 P0：字幕宽度档位 0=50vw / 1=70vw / 2=90vw（视口 <686px 接近 480px，>686px 宽于 480px） |
+| `backchannelYield` | `true` | 批 5 P1：让位语义（ADR-0008）；朗读期说「嗯/对」自动让位 1.5s + 真要说走硬打断。I10 豁免（默认开是产品决策）；关 = 行为等同改造前 |
 
 生效范围：`voice`/`rate`/`ttsEngine`/`kokoroModel`/`spokenFormat` **立即生效**；其余设置下次进入语音模式时生效。设置项默认值由插件配置（`base` 层）提供。
 
@@ -111,22 +133,69 @@ bundle 插件安装后需重启 dsh 生效（Linux：`systemctl restart dsh`；
 
 `voice-mode` 命名空间配置可直接写入 `~/.dsh/settings.yaml`；插件总开关 `enabled`（默认 `true`）、模型缓存目录 `cacheDir`、在安装配置中设置。
 
-## 工作原理
-
-```
-麦克风(16kHz, AEC) ─▶ 浏览器 VAD 分段 ─▶ HOST zipformer2 流式识别(本地 WASM, 增量传输)
-                                        │
-                                        ▼
-用户说话 ◀── 打断 ◀── 音箱 ◀── 逐句合成 ◀── 分句(text-delta 过滤) ◀── SenseVoice 标点定稿
-                          │
-           本地 VITS / 本地 Kokoro(原生 addon, 子进程) / Edge 云端(可选)
+---
+
+## 🏛️ 工作原理（Architecture）
+
+```mermaid
+flowchart LR
+    subgraph Client[浏览器 Client]
+        Mic[麦克风 16kHz<br/>AudioWorklet<br/>echoCancellation:true] --> VAD[客户端 VAD<br/>RMS 分段]
+        VAD -->|partial 0.9s| UI[状态条 + 字幕浮层]
+    end
+
+    subgraph Host[宿主 dsh.host]
+        ASR[zipformer2 流式识别<br/>host 端 WASM]
+        SV[SenseVoice 定稿<br/>+ ITN + 标点]
+        Tap[llm/stream tap<br/>仅观察·不阻塞]
+        Seg[sentence segmenter]
+        Q[TtsQueue<br/>epoch 打断]
+        TTS{引擎}
+        Edge[Edge 云端]
+        Vits[本地 VITS WASM]
+        Kokoro[本地 Kokoro<br/>原生 addon]
+    end
+
+    UI -->|audio f32 PCM<br/>POST /voice-mode/asr| ASR
+    ASR --> SV
+    SV --> Draft[composer draft<br/>autoSend]
+    Draft --> Tap
+    Tap --> Seg
+    Seg --> Q
+    Q --> TTS
+    TTS -->|edge| Edge
+    TTS -->|vits| Vits
+    TTS -->|kokoro| Kokoro
+    Edge -.->|SSE audio frame| UI
+    Vits -.->|SSE audio frame| UI
+    Kokoro -.->|SSE audio frame| UI
+    VAD -.->|唤醒词/打断| Q
 ```
 
 - 识别在 **host 端本地运行**（zipformer2 中文 int8 WASM + SenseVoice 定稿，模型懒下载），音频不上传第三方；识别定稿由 SenseVoice 补标点；
 - 朗读默认 **Edge 云端**；本地 VITS 纯中文 / Kokoro 原生中英（跑在独立子进程、崩溃自愈）可选（隐私优先）；
 - 同一时间仅一个会话处于语音模式（全局单活）；LLM 流被无损观察（不阻塞）。
 
-## 已知限制
+详细架构决策：见 [`docs/adr/`](../../docs/adr/README.md) 8 个 ADR。
+
+---
+
+## 🔍 与 dsh 内置语音模式对比
+
+| 维度 | dsh 内置 | dsh-voice-mode（本插件） |
+| --- | --- | --- |
+| 识别模型 | 云端 API（需 key） | **本地 zipformer2 + SenseVoice**（零 key） |
+| 多语种 | 英文为主 | **SenseVoice 自动识别（auto）+ ITN** |
+| 朗读引擎 | 云端 TTS | **Edge 云端 + 本地 VITS/Kokoro** 三选一 |
+| 打断检测 | 基础 VAD | **三档灵敏度 + 回声门控 + 让位语义** |
+| 热词偏置 | 无 | 无（已移除，详见 v0.7.7 文档说明） |
+| 字幕 a11y | 无 | **4 档字号 + 3 档宽度 + 主题跟随** |
+| 唤醒词 | 无 | **轻量流式匹配 + 前缀语气词白名单** |
+| 兼容 dsh | — | **0.1.1-rc.2 → 0.1.5-rc.2 全版本** |
+
+---
+
+## 🚧 已知限制
 
 - 发声打断依赖浏览器回声消除（`echoCancellation`）；扬声器音量过大时可能漏声到麦克风
 - `Ctrl+Shift+V` 会覆盖浏览器「粘贴纯文本」快捷键（普通粘贴仍可用 `Ctrl+V`）
@@ -143,7 +212,9 @@ bundle 插件安装后需重启 dsh 生效（Linux：`systemctl restart dsh`；
   - iOS 后台/锁屏时识别与朗读暂停，回前台自动恢复（可能丢句）；建议语音模式期间保持前台
 - **安全说明**：插件 HTTP 面（`/voice-mode/*`）遵循宿主安全模型——请勿将 dsh 端口直接暴露公网；经反向代理发布时由代理层（如 basic auth）鉴权；插件侧对敏感操作保留会话归属校验
 
-## 故障排查
+---
+
+## 🛠️ 故障排查
 
 | 现象 | 处理 |
 | --- | --- |
@@ -152,9 +223,31 @@ bundle 插件安装后需重启 dsh 生效（Linux：`systemctl restart dsh`；
 | 朗读无声音/无字幕 | 本地引擎首次合成需加载模型；若持续失败查看状态条提示（自动退避重试）；确认页面前台且未静音 |
 | 语音模式进不去 | 检查插件 `enabled`；多标签页时确认当前会话为活动会话 |
 | 识别到但不是我要说的 | 环境噪声或唤醒词误判：降低音量、提高 `interruptLevel`（高门槛）或启用 `wakeWord` |
+| 唤醒词唤不醒 | 先看待机态状态条的实时转写（它听到了什么）：同音字 1 字内已自动容错；停顿约 1.5 秒（= 静音断句时长）再说，清掉待机段残留语音、从段首重新匹配；换一个转写稳定的词（建议 3-4 字） |
+| 打断后说话没反应（开了唤醒词） | 唤醒词只管「开始识别」的门：打断/每句断句后回到待机态，**需重说唤醒词**再继续说；待机态状态条会显示「说『x』开始」提示 |
+| 唤醒词完全没反应 | ① 确认交互模式是 `toggle`（`hold` 与手动打断下唤醒词不生效）；② 确认 `bargeInMode`：`manual`（或 `detect` 在本机无原生回声消除时自动落 manual）会关闭常驻聆听 → 唤醒词失效，改回 `auto` 或按住麦克风/Ctrl；③ 朗读期说唤醒词不触发（先等 AI 说完）；④ 看待机态实时转写，确认它听到了什么（同音字 1 字内已容错，建议 3-4 字词） |
 | 按住说话松手后没反应 | 确认交互模式为「按住说」且按住期间按钮高亮；松手后识别定稿约 1 秒内进入草稿 |
+| 打不断（朗读中开口无反应） | 调高 `interruptLevel`（更敏感档 = 0 或 1）或检查麦克风权限；若 VAD 持续不触发可临时切到「手动打断」（`mode: hold` / 唤醒词定时延后）；**不要**调 `echoGateDb`——真机 3.1 分钟朗读期里 Silero 0/777 帧把回声判成语音，原生 AEC 生效时此阈值从未被执行（详见 ADR-0006） |
+| 字幕被输入框挡住 | 默认 `captionMaxWidth=1`（70vw）+ `captionFontSize=0`（12px）在窄屏可能与底部输入框重叠；调高档位或点字幕浮层「×」收起 |
+| 让位行为异常（朗读期说「嗯」不停 / 真话被打断） | 「嗯/对」类短词触发让位 1.5s 后继续朗读；继续说真话会走硬打断；不要时关 `backchannelYield` 即可恢复改造前行为（ADR-0008） |
+| 朗读期说「嗯」没让位 | 确认 `backchannelYield=true`（默认开）；hold 模式松手后让位 1.5s 内继续说话会变硬打断 |
+| 空闲 5 分钟自动退出（不想退） | 调高 `idleTimeoutMinutes`（默认 5 分钟，**朗读计为活动**） |
+
+---
 
-## 开发
+## 🛣️ 路线图（Roadmap）
+
+完整 backlog（43 项 P0-P3）见 [`docs/competitive/backlog.md`](../../docs/competitive/backlog.md)。
+
+- ✅ **已完成（v0.7.7）**：11 批次周全修复（字幕档位 / 让位语义 / 模型预热 / 默认值微调 / 死代码清理等）
+- 🚧 **P0（近期）**：ADR-0003 VAD 下沉 / ADR-0006 第一级探测接通 manual / F1 emotion DSL 全量上线
+- 📋 **P1（中期）**：MCP `voice_*` 工具集 / 卡片表单 draft validate / 状态条 idle 优化
+- 💡 **P2（远期）**：声音克隆（用户已决定推迟）/ ADR-0004 WebSocket transport
+- ⏸️ **已推迟**：xAI fallback / C1 人格层（用户已决定推迟）
+
+---
+
+## 🛠️ 开发
 
 ```sh
 pnpm install && pnpm build    # esbuild：lib/index.js（host）+ lib/client.js（browser）
@@ -178,8 +271,10 @@ src/client.tsx       client：麦克风按钮 + 模式切换按钮 + 状态条 +
 src/strings.ts       client：中英文案字典（navigator.language）
 ```
 
-## License
+---
+
+## 📄 License
 
-[MIT](LICENSE)
+[MIT](../../LICENSE)
 
-> 部分实现借鉴 [haoku123/dsh-voice](https://github.com/haoku123/dsh-voice)（派生声明见子包 LICENSE）。
+> 部分实现借鉴 [haoku123/dsh-voice](https://github.com/haoku123/dsh-voice)（派生声明见子包 LICENSE）。