diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b9a2f86f..d6dfb58e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -822,7 +822,9 @@ jobs:
# The insert check's UI Automation reader on this desktop (docs/dictation.md §28): a paste
# into Notepad is written, the test's own read-only EDIT stays not written, the focus moving
- # to its other EDIT is unconfirmed. Only the small voltip-focus crate is built.
+ # to its other EDIT is unconfirmed. And the copy that reads the selection (§19, §35):
+ # Notepad's selection comes back while Ctrl+Alt of the shortcut is held, the clipboard put
+ # back. Only the small voltip-focus crate is built.
- name: Build the insert check's reader test
run: cargo test -p voltip-focus --test focus_windows --no-run
@@ -974,12 +976,13 @@ jobs:
libwebkit2gtk-4.1-dev libgtk-3-dev libsoup-3.0-dev libdbus-1-dev \
libayatana-appindicator3-dev librsvg2-dev libasound2-dev libssl-dev \
libx11-dev libxtst-dev libxcb1-dev patchelf pkg-config cmake \
- xvfb xdotool scrot x11-utils python3-pil \
+ xvfb xdotool scrot x11-utils python3-pil python3-tk \
xclip pulseaudio pulseaudio-utils libasound2-plugins \
weston sway wtype wl-clipboard grim dbus \
at-spi2-core libglib2.0-bin python3-gi gir1.2-gtk-3.0
command -v Xvfb xdotool scrot xclip pulseaudio pactl paplay weston sway wtype wl-copy grim dbus-daemon gdbus
/usr/bin/python3 -c 'import PIL; print("PIL", PIL.__version__)'
+ /usr/bin/python3 -c 'import tkinter; print("Tk", tkinter.TkVersion)'
- name: Rust toolchain (rust-toolchain.toml)
run: |
@@ -1033,9 +1036,15 @@ jobs:
run: xvfb-run -a -s "-screen 0 1280x1024x24 -noreset" cargo test -p voltip-hooks --lib -- --ignored --test-threads=1 --nocapture
# The whole clipboard across a paste on a real X server (docs/dictation.md §14.3): an image
- # and HTML xclip copied come back, and the dictation is marked for clipboard managers.
- - name: Real clipboard under Xvfb (cargo test -p voltip-inject --test real_display -- --ignored)
- run: xvfb-run -a -s "-screen 0 1280x1024x24 -noreset" cargo test -p voltip-inject --test real_display real_an_image -- --ignored --test-threads=1 --nocapture
+ # and HTML xclip copied come back, and the dictation is marked for clipboard managers. The
+ # copy that reads the selection (§19, 从选中文字学习 §35): a Tk entry's selection comes back
+ # with Ctrl+Insert, a modifier still held from the shortcut let go first, the clipboard put
+ # back; while a grabbed hotkey key is down the copy never reaches the entry.
+ - name: Real clipboard and selection copy under Xvfb (cargo test -p voltip-inject --test real_display -- --ignored)
+ run: >-
+ xvfb-run -a -s "-screen 0 1280x1024x24 -noreset" cargo test -p voltip-inject --test real_display --
+ --ignored --test-threads=1 --nocapture
+ real_an_image real_copy_chord_reads_the_selection_of_an_x11_text_widget regression_x11_hotkey_grab_swallows_the_copy_until_the_key_is_up
# The insert check's AT-SPI reader against a GTK 3 window on a real X server, in a private
# D-Bus session with the accessibility bus switched on (docs/dictation.md §28): a typed text
@@ -1412,8 +1421,10 @@ jobs:
# The insert check's Accessibility reader (docs/dictation.md §28): a paste into the test's own
# text view, which can be selected but not edited, stays not written; a paste into a TextEdit
- # document is written. The test has its own main (AppKit runs on the main thread); its
- # binary is granted Accessibility and event posting as the event tap's is.
+ # document is written, and the copy that reads the selection (§19, §35) brings TextEdit's
+ # selection back with Cmd+C and puts the pasteboard back. The test has its own main (AppKit
+ # runs on the main thread); its binary is granted Accessibility and event posting as the
+ # event tap's is.
- name: Real insert check (Accessibility granted to the test binary)
if: matrix.arch == 'aarch64'
timeout-minutes: 15
diff --git a/apps/desktop/src-tauri/src/cli.rs b/apps/desktop/src-tauri/src/cli.rs
index 1969a176..e5685c73 100644
--- a/apps/desktop/src-tauri/src/cli.rs
+++ b/apps/desktop/src-tauri/src/cli.rs
@@ -50,6 +50,11 @@ pub struct Cli {
/// happens when none runs.
#[arg(long, conflicts_with_all = ["toggle", "edit_toggle", "cancel", "quit", "start_hidden", "list_devices", "list_compute", "list_models", "download_model", "transcribe_file"])]
pub copy_last: bool,
+ /// Have the running instance learn from the selected text (从选中文字学习, docs/dictation.md
+ /// §35): the corrected text selected in another application; bind it to a compositor shortcut
+ /// where no global hotkey exists (Wayland). Nothing happens when none runs.
+ #[arg(long, conflicts_with_all = ["toggle", "edit_toggle", "cancel", "quit", "copy_last", "start_hidden", "list_devices", "list_compute", "list_models", "download_model", "transcribe_file"])]
+ pub learn_selection: bool,
/// Print the input devices (`idname`, default first) and exit.
#[arg(long, conflicts_with_all = ["list_models", "transcribe_file"])]
pub list_devices: bool,
@@ -145,6 +150,8 @@ pub enum Action {
Quit,
/// `--copy-last`: the same way, for 复制上一条结果 (a new instance has no result yet).
CopyLast,
+ /// `--learn-selection`: the same way, for 从选中文字学习 (a new instance has no history open).
+ LearnSelection,
/// `--list-devices`.
ListDevices,
/// `--list-compute`.
@@ -230,6 +237,9 @@ impl Cli {
if self.copy_last {
return Action::CopyLast;
}
+ if self.learn_selection {
+ return Action::LearnSelection;
+ }
Action::Gui { start_hidden: self.start_hidden, remote: self.remote() }
}
}
@@ -250,6 +260,11 @@ pub fn copy_last_from_args(args: &[String]) -> bool {
Cli::parse_args(args).is_ok_and(|cli| cli.copy_last)
}
+/// Whether a second instance's arguments ask this one for 从选中文字学习 (`--learn-selection`).
+pub fn learn_selection_from_args(args: &[String]) -> bool {
+ Cli::parse_args(args).is_ok_and(|cli| cli.learn_selection)
+}
+
/// What `--transcribe-file --json` prints.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct TranscribeOutput {
@@ -525,6 +540,6 @@ pub fn run_headless(action: &Action, data_dir: &Path, out: &mut dyn Write, err:
};
transcribe_file(&transcriber, &args, out, err)
}
- Action::Gui { .. } | Action::Quit | Action::CopyLast => ExitCode::Ok,
+ Action::Gui { .. } | Action::Quit | Action::CopyLast | Action::LearnSelection => ExitCode::Ok,
}
}
diff --git a/apps/desktop/src-tauri/src/dictation.rs b/apps/desktop/src-tauri/src/dictation.rs
index 7e6274c2..0a3814e5 100644
--- a/apps/desktop/src-tauri/src/dictation.rs
+++ b/apps/desktop/src-tauri/src/dictation.rs
@@ -552,6 +552,12 @@ impl Injector for NativeInjector {
voltip_platform::foreground::is_terminal(voltip_platform::HostOs::current(), app_id)
}
+ /// docs/dictation.md §35: every terminal of this host, macOS's included
+ /// (`voltip_platform::insert_check::holds_program_output`).
+ fn holds_program_output(&self, app_id: &str) -> bool {
+ voltip_platform::insert_check::holds_program_output(voltip_platform::HostOs::current(), app_id)
+ }
+
/// docs/dictation.md §28: the platform's reader of the focused control.
fn focus_reader(&self) -> Option> {
self.focus.clone()
diff --git a/apps/desktop/src-tauri/src/hotkey.rs b/apps/desktop/src-tauri/src/hotkey.rs
index e600959c..589e802c 100644
--- a/apps/desktop/src-tauri/src/hotkey.rs
+++ b/apps/desktop/src-tauri/src/hotkey.rs
@@ -15,7 +15,10 @@
//!
//! 复制上一条结果 (`Settings.copy_last_hotkey`, docs/dictation.md §28) is a third, optional chord
//! that answers its press only: it puts the newest result on the clipboard ([`crate::copy_last`]);
-//! on pure Wayland the compositor runs `--copy-last` instead.
+//! on pure Wayland the compositor runs `--copy-last` instead. 从选中文字学习
+//! (`Settings.learn_hotkey`, §35) is a fourth: one transition each, the press where the copy chord
+//! can reach the application then, the release under the X11 key grab ([`selection_timing_for`]);
+//! the compositor runs `--learn-selection` on pure Wayland.
//!
//! The lone-key trigger (`Settings.solo_key`, docs/dictation.md §13.1) is watched by
//! [`crate::solo_key`] next to the chords, with the same lifecycle: installed by [`apply`],
@@ -55,7 +58,8 @@ pub fn edge_command(pressed: bool, source: EdgeSource, purpose: TakeKind) -> UiC
}
/// What the shell registers: the dictation hotkey, the voice-edit hotkey (`None` = off), the
-/// lone-key trigger (`None` = off) and the 复制上一条结果 chord (`None` = none).
+/// lone-key trigger (`None` = off), the 复制上一条结果 chord and the 从选中文字学习 chord (`None` =
+/// none).
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Chords {
/// `Settings.hotkey`.
@@ -66,6 +70,8 @@ pub struct Chords {
pub solo_key: Option,
/// `Settings.copy_last_hotkey`.
pub copy_last_hotkey: Option,
+ /// `Settings.learn_hotkey`.
+ pub learn_hotkey: Option,
}
impl From<&Settings> for Chords {
@@ -75,6 +81,7 @@ impl From<&Settings> for Chords {
edit_hotkey: settings.edit_hotkey.clone(),
solo_key: settings.solo_key,
copy_last_hotkey: settings.copy_last_hotkey.clone(),
+ learn_hotkey: settings.learn_hotkey.clone(),
}
}
}
@@ -162,6 +169,11 @@ pub fn copy_last_command() -> String {
remote_command("--copy-last")
}
+/// The same for 从选中文字学习 (docs/dictation.md §35): `voltip-desktop --learn-selection`.
+pub fn learn_command() -> String {
+ remote_command("--learn-selection")
+}
+
fn remote_command(flag: &str) -> String {
#[cfg(unix)]
{
@@ -475,6 +487,18 @@ pub fn apply(app: &AppHandle, bridge: &Bridge, registry: &Arc status.learn_registered = Some(label),
+ Err(e) => status.learn_error = Some(e),
+ }
+ }
+ }
let kept = sync_solo(bridge, registry, chords.solo_key, session, &mut status);
registry.store_applied(&|event| bridge.publish(event), status, kept);
// A take running across a settings change keeps its cancel key.
@@ -746,6 +770,46 @@ fn register_copy_last(app: &AppHandle, text: &str, session: Optio
}
}
+/// The transition of the 从选中文字学习 chord that starts it (docs/dictation.md §35): the press, or
+/// the release where the X11 key grab holds the keyboard until the key is up.
+pub fn learn_fires_on(timing: SelectionTiming) -> ShortcutState {
+ match timing {
+ SelectionTiming::AtPress => ShortcutState::Pressed,
+ SelectionTiming::AfterKeyUp => ShortcutState::Released,
+ }
+}
+
+/// Register the 从选中文字学习 chord (docs/dictation.md §35); the display label, or why not.
+fn register_learn(app: &AppHandle, text: &str, session: Option) -> Result {
+ let hotkey = Hotkey::parse(text).map_err(|e| format!("{text}: {e}"))?;
+ let label = hotkey.display();
+ let remote = learn_command();
+ if let Some(blocked) = session_block(session, &label, &remote) {
+ tracing::warn!(hotkey = %label, backend = %backend_name(), error = %blocked, "no global hotkey on this session; the compositor must run {remote}");
+ return Err(blocked);
+ }
+ let shortcut = hotkey.to_tauri_shortcut();
+ let fires = learn_fires_on(selection_timing_for(session));
+ let result = app.global_shortcut().on_shortcut(shortcut.as_str(), move |app, _shortcut, event| {
+ if event.state() == fires {
+ crate::learn_selection(app, voltip_core::EdgeSource::Hotkey);
+ }
+ });
+ match result {
+ Ok(()) => {
+ tracing::info!(hotkey = %label, shortcut = %shortcut, fires = ?fires, "learn hotkey registered");
+ if let Some(caveat) = session_caveat(session, &remote) {
+ tracing::warn!(hotkey = %label, "{caveat}");
+ }
+ Ok(label)
+ }
+ Err(e) => {
+ tracing::warn!(hotkey = %label, error = %e, "learn hotkey registration failed");
+ Err(format!("{label} 未能生效:{e}"))
+ }
+ }
+}
+
/// Watch the bridge for settings changes and keep the OS registration in sync.
pub fn follow_settings(app: AppHandle, bridge: Bridge, registry: Arc) {
if let Some(session) = linux_session() {
@@ -976,19 +1040,23 @@ mod tests {
assert!(!cancel_key_wanted(&DictationPhase::Cancelled { injected_chars: 0 }));
// Bare, and under each chord's modifiers: a `hold` take is cancelled with the chord down.
- let chords = Chords { hotkey: "Ctrl+Alt+Space".into(), edit_hotkey: Some("Ctrl+Alt+E".into()), solo_key: None, copy_last_hotkey: None };
+ let chords =
+ Chords { hotkey: "Ctrl+Alt+Space".into(), edit_hotkey: Some("Ctrl+Alt+E".into()), solo_key: None, copy_last_hotkey: None, learn_hotkey: None };
assert_eq!(cancel_shortcuts(&chords), ["Escape", "Control+Alt+Escape"]);
- let chords = Chords { hotkey: "Alt+Shift+Z".into(), edit_hotkey: Some("Meta+E".into()), solo_key: None, copy_last_hotkey: None };
+ let chords = Chords { hotkey: "Alt+Shift+Z".into(), edit_hotkey: Some("Meta+E".into()), solo_key: None, copy_last_hotkey: None, learn_hotkey: None };
assert_eq!(cancel_shortcuts(&chords), ["Escape", "Alt+Shift+Escape", "Super+Escape"]);
- let chords = Chords { hotkey: "not a chord".into(), edit_hotkey: None, solo_key: None, copy_last_hotkey: None };
+ let chords = Chords { hotkey: "not a chord".into(), edit_hotkey: None, solo_key: None, copy_last_hotkey: None, learn_hotkey: None };
assert_eq!(cancel_shortcuts(&chords), ["Escape"]);
// Task Manager and Force Quit stay the system's.
- let chords = Chords { hotkey: "Shift+Ctrl+D".into(), edit_hotkey: Some("Alt+Meta+E".into()), solo_key: None, copy_last_hotkey: None };
+ let chords =
+ Chords { hotkey: "Shift+Ctrl+D".into(), edit_hotkey: Some("Alt+Meta+E".into()), solo_key: None, copy_last_hotkey: None, learn_hotkey: None };
assert_eq!(cancel_shortcuts(&chords), ["Escape"]);
// docs/dictation.md §13.1: a lone modifier held in `hold` adds its own; a mouse button none.
- let chords = Chords { hotkey: "Ctrl+Alt+Space".into(), edit_hotkey: None, solo_key: Some(SoloKey::RightShift), copy_last_hotkey: None };
+ let chords =
+ Chords { hotkey: "Ctrl+Alt+Space".into(), edit_hotkey: None, solo_key: Some(SoloKey::RightShift), copy_last_hotkey: None, learn_hotkey: None };
assert_eq!(cancel_shortcuts(&chords), ["Escape", "Control+Alt+Escape", "Shift+Escape"]);
- let chords = Chords { hotkey: "Ctrl+Alt+Space".into(), edit_hotkey: None, solo_key: Some(SoloKey::MouseBack), copy_last_hotkey: None };
+ let chords =
+ Chords { hotkey: "Ctrl+Alt+Space".into(), edit_hotkey: None, solo_key: Some(SoloKey::MouseBack), copy_last_hotkey: None, learn_hotkey: None };
assert_eq!(cancel_shortcuts(&chords), ["Escape", "Control+Alt+Escape"]);
assert_eq!(SoloKey::ALL.into_iter().filter_map(solo_modifier).count(), 4, "the four right-hand modifiers");
@@ -1084,6 +1152,14 @@ mod tests {
/// docs/dictation.md §19: X11 grabs the keyboard while the hotkey is down — the copy waits for
/// the key-up there (XWayland too); elsewhere it goes out at the press.
+ #[test]
+ fn the_learn_chord_fires_when_the_copy_can_reach_the_application() {
+ assert_eq!(learn_fires_on(SelectionTiming::AtPress), ShortcutState::Pressed);
+ assert_eq!(learn_fires_on(SelectionTiming::AfterKeyUp), ShortcutState::Released, "the X11 grab ends at the key-up");
+ assert_eq!(learn_fires_on(selection_timing_for(Some(SessionKind::X11))), ShortcutState::Released);
+ assert_eq!(learn_fires_on(selection_timing_for(None)), ShortcutState::Pressed);
+ }
+
#[test]
fn selection_timing_follows_the_x11_grab() {
assert_eq!(selection_timing_for(Some(SessionKind::X11)), SelectionTiming::AfterKeyUp);
@@ -1093,7 +1169,7 @@ mod tests {
let settings = Settings { hotkey: "Ctrl+Alt+Space".into(), edit_hotkey: None, solo_key: Some(SoloKey::RightCtrl), ..Settings::default() };
assert_eq!(
Chords::from(&settings),
- Chords { hotkey: "Ctrl+Alt+Space".into(), edit_hotkey: None, solo_key: Some(SoloKey::RightCtrl), copy_last_hotkey: None }
+ Chords { hotkey: "Ctrl+Alt+Space".into(), edit_hotkey: None, solo_key: Some(SoloKey::RightCtrl), copy_last_hotkey: None, learn_hotkey: None }
);
assert!(matches!(
chorded_command(),
diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs
index ecb25aaf..9e653b0d 100644
--- a/apps/desktop/src-tauri/src/lib.rs
+++ b/apps/desktop/src-tauri/src/lib.rs
@@ -60,7 +60,7 @@ pub const DEV_DATA_DIR_ENV: &str = "VOLTIP_DEV_DATA_DIR";
/// (`packages/shared/src/schema.ts` `CommandArgs`) and the IPC fixtures
/// (`packages/shared/src/fixtures/ipc/commands.json`) must name exactly this set; `tests/ipc.rs`
/// checks all three against each other.
-pub const COMMANDS: [&str; 161] = [
+pub const COMMANDS: [&str; 169] = [
"core_state",
"pairing_start",
"pairing_join_code",
@@ -86,6 +86,7 @@ pub const COMMANDS: [&str; 161] = [
"settings_set_hotkey",
"settings_set_edit_hotkey",
"settings_set_copy_last_hotkey",
+ "settings_set_learn_hotkey",
"settings_set_solo_key",
"settings_set_microphone",
"settings_set_recording",
@@ -101,6 +102,10 @@ pub const COMMANDS: [&str; 161] = [
"dictation_stop",
"dictation_cancel",
"dictation_dismiss",
+ "learn_notice_accept",
+ "learn_notice_undo",
+ "learn_notice_dismiss",
+ "learn_notice_keep",
"hotkey_edge",
"settings_set_activation",
"settings_set_engines",
@@ -119,6 +124,7 @@ pub const COMMANDS: [&str; 161] = [
"history_delete",
"history_clear",
"history_star",
+ "history_clear_corrected",
"history_process",
"history_process_cancel",
"audio_cache_clear",
@@ -221,6 +227,8 @@ pub const COMMANDS: [&str; 161] = [
"overlay_copy",
"overlay_paste",
"open_history",
+ "open_suggestions",
+ "open_privacy",
"phone_share_text",
];
@@ -416,6 +424,45 @@ fn settings_set_edit_hotkey(bridge: tauri::State<'_, Bridge>, hotkey: Option, hotkey: Option) -> Result<(), String> {
+ Ok(bridge.dispatch(UiCommand::SettingsSetLearnHotkey { hotkey })?)
+}
+
+/// The learn notice's 加入词典 (docs/dictation.md §35).
+#[tauri::command]
+fn learn_notice_accept(bridge: tauri::State<'_, Bridge>, id: u64) -> Result<(), String> {
+ Ok(bridge.dispatch(UiCommand::LearnNoticeAccept { id })?)
+}
+
+/// The learn notice's 撤销.
+#[tauri::command]
+fn learn_notice_undo(bridge: tauri::State<'_, Bridge>, id: u64) -> Result<(), String> {
+ Ok(bridge.dispatch(UiCommand::LearnNoticeUndo { id })?)
+}
+
+/// The learn notice's ×.
+#[tauri::command]
+fn learn_notice_dismiss(bridge: tauri::State<'_, Bridge>, id: u64) -> Result<(), String> {
+ Ok(bridge.dispatch(UiCommand::LearnNoticeDismiss { id })?)
+}
+
+/// The learn notice's 查看 and 打开设置 (docs/dictation.md §35): the notice stays its whole time
+/// again while the main window opens the page.
+#[tauri::command]
+fn learn_notice_keep(bridge: tauri::State<'_, Bridge>, id: u64) -> Result<(), String> {
+ Ok(bridge.dispatch(UiCommand::LearnNoticeKeep { id })?)
+}
+
+/// The history detail's 移除 (docs/dictation.md §35): the user's correction of the entry is forgotten.
+#[tauri::command]
+fn history_clear_corrected(bridge: tauri::State<'_, Bridge>, id: String) -> Result<(), String> {
+ Ok(bridge.dispatch(UiCommand::HistoryClearCorrected { id })?)
+}
+
/// 复制上一条结果's chord (docs/dictation.md §28): a chord, or `null` for none (`--copy-last` and
/// the tray's entry keep working). The core validates it like the dictation hotkey, refuses the
/// other two chords, persists and re-emits `settings`; the hotkey module re-registers.
@@ -1539,6 +1586,34 @@ fn open_history(app: tauri::AppHandle) -> Result<(), String> {
app.emit_to(MAIN_WINDOW, MAIN_REQUEST_EVENT, serde_json::json!({ "action": "history" })).map_err(|e| e.to_string())
}
+/// The learn notice's 查看 (docs/dictation.md §35): the main window comes up on the dictionary's
+/// learning suggestions.
+#[tauri::command]
+fn open_suggestions(app: tauri::AppHandle) -> Result<(), String> {
+ show_main_window(&app);
+ app.emit_to(MAIN_WINDOW, MAIN_REQUEST_EVENT, serde_json::json!({ "action": "suggestions" })).map_err(|e| e.to_string())
+}
+
+/// The learn notice's 打开设置 while the history is off (docs/dictation.md §35): the main window
+/// comes up on 设置 › 隐私.
+#[tauri::command]
+fn open_privacy(app: tauri::AppHandle) -> Result<(), String> {
+ show_main_window(&app);
+ app.emit_to(MAIN_WINDOW, MAIN_REQUEST_EVENT, serde_json::json!({ "action": "privacy" })).map_err(|e| e.to_string())
+}
+
+/// 从选中文字学习 (docs/dictation.md §35) from the hotkey or `--learn-selection`: the core copies the
+/// selection in front and learns from it; the pill shows the notice.
+pub fn learn_selection(app: &tauri::AppHandle, source: voltip_core::EdgeSource) {
+ let Some(bridge) = app.try_state::() else {
+ tracing::warn!(?source, "learn selection before the core is up; dropped");
+ return;
+ };
+ if let Err(e) = bridge.learn_selection(source) {
+ tracing::warn!(error = %e, ?source, "learn selection not accepted");
+ }
+}
+
/// What the shell wires besides the core.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ShellOptions {
@@ -1607,6 +1682,10 @@ pub fn on_second_instance(app: &tauri::AppHandle, args: &[String]
copy_last::run(app, "cli");
return;
}
+ if cli::learn_selection_from_args(args) {
+ learn_selection(app, voltip_core::EdgeSource::Cli);
+ return;
+ }
match cli::remote_from_args(args) {
Some(remote) => match app.try_state::() {
Some(bridge) => {
@@ -1781,6 +1860,7 @@ pub fn build_app(
settings_set_hotkey,
settings_set_edit_hotkey,
settings_set_copy_last_hotkey,
+ settings_set_learn_hotkey,
settings_set_solo_key,
settings_set_microphone,
settings_set_recording,
@@ -1796,6 +1876,10 @@ pub fn build_app(
dictation_stop,
dictation_cancel,
dictation_dismiss,
+ learn_notice_accept,
+ learn_notice_undo,
+ learn_notice_dismiss,
+ learn_notice_keep,
hotkey_edge,
settings_set_activation,
settings_set_engines,
@@ -1814,6 +1898,7 @@ pub fn build_app(
history_delete,
history_clear,
history_star,
+ history_clear_corrected,
history_process,
history_process_cancel,
audio_cache_clear,
@@ -1916,6 +2001,8 @@ pub fn build_app(
overlay_copy,
overlay_paste,
open_history,
+ open_suggestions,
+ open_privacy,
phone_share_text
])
}
@@ -1950,7 +2037,7 @@ pub fn run() {
};
let action = args.action();
// `--quit` and `--copy-last` only reach a running instance; they never start one.
- let forward_only = matches!(action, cli::Action::Quit | cli::Action::CopyLast);
+ let forward_only = matches!(action, cli::Action::Quit | cli::Action::CopyLast | cli::Action::LearnSelection);
let start_hidden = match &action {
cli::Action::Gui { start_hidden, remote } => {
if let Some(remote) = remote {
@@ -1960,7 +2047,7 @@ pub fn run() {
}
// Built like the GUI below so the single-instance plugin can hand `--quit` / `--copy-last`
// to a running instance (and end this process); getting past `build` means there is none.
- cli::Action::Quit | cli::Action::CopyLast => true,
+ cli::Action::Quit | cli::Action::CopyLast | cli::Action::LearnSelection => true,
headless => {
tracing::debug!(?headless, "headless action");
// Unlocked handles: each write takes the lock briefly. Holding `stdout().lock()` across
diff --git a/apps/desktop/src-tauri/src/overlay.rs b/apps/desktop/src-tauri/src/overlay.rs
index 5517f27e..a25048c6 100644
--- a/apps/desktop/src-tauri/src/overlay.rs
+++ b/apps/desktop/src-tauri/src/overlay.rs
@@ -45,6 +45,9 @@ pub const LIVE_STATE: &str = "live";
pub const HIDE_AFTER_BLANK: Duration = Duration::from_millis(80);
/// The pill's flash after 复制上一条结果 (docs/dictation.md §28): `已复制上一条结果`, between takes.
pub const COPIED_STATE: &str = "copied";
+/// The pill's notice after 从选中文字学习 (docs/dictation.md §35): the webview renders
+/// `UiState.learn_notice`; the core times it.
+pub const LEARNED_STATE: &str = "learned";
/// Debug-build knob: `=1` draws the pill window opaque. X11 without a compositor (Xvfb smoke
/// tests) renders an RGBA window as a black rectangle, so the headless run cannot prove the pill
/// paints unless transparency is off. Release builds ignore it.
@@ -359,6 +362,24 @@ fn let_go(app: &AppHandle) {
let _ = stacking;
}
+/// Whether the pill shows the learn notice (docs/dictation.md §35): the core says it is on the
+/// pill (`shown`, so never over a take or its result), and the pill is not off.
+pub fn learned_wanted(phase: &DictationPhase, notice: Option<&voltip_core::LearnNotice>, placement: OverlayPlacement) -> bool {
+ placement != OverlayPlacement::Off && *phase == DictationPhase::Idle && notice.is_some_and(|n| n.shown)
+}
+
+/// Show or take away the learn notice after its state changed.
+fn apply_learned(app: &AppHandle, bridge: &Bridge) {
+ let state = bridge.state();
+ if learned_wanted(&state.dictation.phase, state.learn_notice.as_ref(), state.settings.overlay) {
+ if let Err(e) = show_fixed(app, LEARNED_STATE, state.settings.overlay) {
+ tracing::warn!(error = %e, "overlay learn notice failed");
+ }
+ } else if app.try_state::().is_some_and(|slot| slot.current() == LEARNED_STATE) {
+ hide(app);
+ }
+}
+
/// Keep the pill in step with `UiEvent::Dictation` for as long as the bridge lives.
pub fn follow_dictation(app: AppHandle, bridge: Bridge) {
let mut events = bridge.events();
@@ -366,6 +387,7 @@ pub fn follow_dictation(app: AppHandle, bridge: Bridge) {
loop {
match events.recv().await {
Ok(UiEvent::Dictation(status)) => apply_phase(&app, &status.phase, bridge.state().settings.overlay),
+ Ok(UiEvent::LearnNotice { .. }) => apply_learned(&app, &bridge),
// Switched off while a take shows the pill: hide it now, not at the next phase.
Ok(UiEvent::Settings(settings)) if settings.overlay == OverlayPlacement::Off => hide(&app),
Ok(_) => {}
@@ -373,6 +395,7 @@ pub fn follow_dictation(app: AppHandle, bridge: Bridge) {
// Catch up from the cached state rather than replaying stale phases.
let state = bridge.state();
apply_phase(&app, &state.dictation.phase, state.settings.overlay);
+ apply_learned(&app, &bridge);
}
Err(tokio::sync::broadcast::error::RecvError::Closed) => break,
}
@@ -438,6 +461,19 @@ mod tests {
assert!(!copied_flash_wanted(&DictationPhase::CANCELLED, OverlayPlacement::Bottom), "a finished take is still on screen");
}
+ /// docs/dictation.md §35: the learn notice is on the pill only once the core shows it (never
+ /// over a take or its result) and with the pill on.
+ #[test]
+ fn the_learn_notice_shows_only_when_the_core_shows_it_between_takes() {
+ let notice = |shown| voltip_core::LearnNotice { id: 1, outcome: voltip_core::LearnOutcome::NoMatch, shown, accepted: None, undone: None };
+ let shown = notice(true);
+ assert!(learned_wanted(&DictationPhase::Idle, Some(&shown), OverlayPlacement::Bottom));
+ assert!(!learned_wanted(&DictationPhase::Idle, Some(¬ice(false)), OverlayPlacement::Bottom), "waiting behind a result");
+ assert!(!learned_wanted(&DictationPhase::Idle, None, OverlayPlacement::Bottom));
+ assert!(!learned_wanted(&DictationPhase::Idle, Some(&shown), OverlayPlacement::Off));
+ assert!(!learned_wanted(&DictationPhase::CANCELLED, Some(&shown), OverlayPlacement::Top), "a take's result has the pill");
+ }
+
/// 2026-11-01: hiding waits a frame; a take that showed the pill in that frame (its first phase
/// right after the previous take's idle) must keep it, and a hide with no show since still hides.
#[test]
diff --git a/apps/desktop/src-tauri/tests/ipc.rs b/apps/desktop/src-tauri/tests/ipc.rs
index ef631ec4..78e9306e 100644
--- a/apps/desktop/src-tauri/tests/ipc.rs
+++ b/apps/desktop/src-tauri/tests/ipc.rs
@@ -157,27 +157,35 @@ fn with_running_app_on(
ports: DictationPorts,
body: impl FnOnce(&AppHandle, &WebviewWindow, &mpsc::Receiver) + Send + 'static,
) {
- run_app(None, ports, body);
+ run_app(None, ports, |_| {}, body);
}
/// [`with_running_app`] on a relay of the test's own, connected before `body` runs.
fn with_running_app_on_a_relay(body: impl FnOnce(&AppHandle, &WebviewWindow, &mpsc::Receiver) + Send + 'static) {
let relay = TestRelay::start();
- run_app(Some(&relay.url), fakes::ports(), |handle, webview, rx| {
- wait_state(webview, |s| s.identity.is_some() && s.relay.state.is_connected());
- body(handle, webview, rx);
- });
+ run_app(
+ Some(&relay.url),
+ fakes::ports(),
+ |_| {},
+ |handle, webview, rx| {
+ wait_state(webview, |s| s.identity.is_some() && s.relay.state.is_connected());
+ body(handle, webview, rx);
+ },
+ );
}
fn run_app(
relay_url: Option<&str>,
ports: DictationPorts,
+ configure: impl FnOnce(&mut CoreConfig),
body: impl FnOnce(&AppHandle, &WebviewWindow, &mpsc::Receiver) + Send + 'static,
) {
let dir = tempfile::tempdir().unwrap();
+ let mut config = core_config(dir.path(), relay_url);
+ configure(&mut config);
let app = build_app(
mock_builder(),
- core_config(dir.path(), relay_url),
+ config,
Arc::new(MemorySecretStore::new()),
ShellOptions::HEADLESS,
voltip_desktop_lib::dictation::ShellPorts::headless(ports),
@@ -1958,6 +1966,8 @@ fn command_list_matches_the_handlers_the_typescript_contract_and_the_fixtures()
"overlay_copy",
"overlay_paste",
"open_history",
+ "open_suggestions",
+ "open_privacy",
"provider_console_open",
"project_link_open",
"guide_open",
@@ -2204,6 +2214,81 @@ fn the_copy_last_chord_is_saved_through_its_own_command() {
});
}
+/// docs/dictation.md §35, through the command layer: 从选中文字学习's chord has its own command
+/// (none by default, refused when the dictation uses it); `voltip --learn-selection` copies the
+/// selection with no key held, the correction is kept with the take and shown by `history_entry`,
+/// the notice offers the pair, 加入词典 and 撤销 change the dictionary, × closes it, the history
+/// detail's 移除 forgets the correction, and the notice's 查看 and 打开设置 ask the main window for
+/// the learning suggestions and the privacy settings.
+#[test]
+fn learning_from_the_selection_runs_through_the_command_layer() {
+ const HEARD: &str = "我在用 Quinn for max 做测试";
+ const FIXED: &str = "我在用 Qwen 4 max 做测试";
+ let injector = Arc::new(fakes::FakeInjector::paste().with_selection(FIXED));
+ let ports = fakes::ports_with(Arc::new(fakes::FakeAudio::speech()), Arc::new(fakes::FakeTranscriber::ok(HEARD)), None, injector.clone());
+ // The notice stays until the test closes it, however slow the machine.
+ let long_stay = |cfg: &mut CoreConfig| cfg.learn_notice_dwell = Duration::from_secs(600);
+ run_app(None, ports, long_stay, move |app, webview, rx| {
+ wait_state(webview, |s| s.identity.is_some());
+ assert_eq!(core_state(webview).settings.learn_hotkey, None, "none by default");
+ assert_eq!(invoke(webview, "settings_set_learn_hotkey", json!({ "hotkey": "Ctrl+Alt+L" })), Ok(Value::Null));
+ wait_state(webview, |s| s.settings.learn_hotkey.as_deref() == Some("Ctrl+Alt+L"));
+ assert_eq!(invoke(webview, "settings_set_learn_hotkey", json!({ "hotkey": "Ctrl+Alt+Space" })), Ok(Value::Null));
+ wait_event(rx, "error (learn_hotkey)", |e| e["type"] == "error" && e["message"].as_str().is_some_and(|m| m.contains("已用作听写快捷键")));
+ assert_eq!(core_state(webview).settings.learn_hotkey.as_deref(), Some("Ctrl+Alt+L"));
+ assert!(invoke(webview, "settings_set_learn_hotkey", json!({ "hotkey": 5 })).is_err());
+
+ assert_eq!(invoke(webview, "dictation_start", json!({})), Ok(Value::Null));
+ wait_state(webview, |s| matches!(s.dictation.phase, DictationPhase::Listening { ready: true, .. }));
+ assert_eq!(invoke(webview, "dictation_stop", json!({})), Ok(Value::Null));
+ wait_state(webview, |s| s.dictation.phase.is_terminal());
+ let id = wait_state(webview, |s| s.history_recent.len() == 1).history_recent[0].id.to_string();
+ assert_eq!(invoke(webview, "dictation_cancel", json!({})), Ok(Value::Null));
+ wait_state(webview, |s| s.dictation.phase == DictationPhase::Idle);
+
+ voltip_desktop_lib::learn_selection(app, EdgeSource::Cli);
+ let notice = wait_state(webview, |s| s.learn_notice.as_ref().is_some_and(|n| n.shown)).learn_notice.unwrap();
+ let voltip_core::LearnOutcome::Learned { pairs, safe } = ¬ice.outcome else { panic!("{notice:?}") };
+ assert_eq!(pairs.iter().map(|p| (p.heard.as_str(), p.polished.as_str())).collect::>(), [("Quinn for", "Qwen 4")]);
+ assert!(safe);
+ assert_eq!(injector.copies(), [Vec::::new()], "nothing is held from the command line");
+ let entry = invoke(webview, "history_entry", json!({ "id": id })).unwrap();
+ assert_eq!(
+ (entry["text"].as_str(), entry["corrected"]["text"].as_str(), entry["corrected"]["via"].as_str()),
+ (Some(HEARD), Some(FIXED), Some("selection"))
+ );
+
+ assert_eq!(invoke(webview, "learn_notice_accept", json!({ "id": notice.id })), Ok(Value::Null));
+ let st = wait_state(webview, |s| s.learn_notice.as_ref().is_some_and(|n| n.accepted.is_some()));
+ assert_eq!(st.dictionary.iter().map(|e| (e.term.as_str(), e.heard_as.clone())).collect::>(), [("Qwen 4", vec!["Quinn for".to_owned()])]);
+ assert_eq!(invoke(webview, "learn_notice_undo", json!({ "id": notice.id })), Ok(Value::Null));
+ let st = wait_state(webview, |s| s.learn_notice.as_ref().is_some_and(|n| n.undone.is_some()));
+ assert!(st.dictionary.is_empty(), "{:?}", st.dictionary);
+ // 查看 / 打开设置 keep the notice (its stay starts again); the notice is named.
+ assert_eq!(invoke(webview, "learn_notice_keep", json!({ "id": notice.id })), Ok(Value::Null));
+ assert!(invoke(webview, "learn_notice_keep", json!({})).is_err());
+ wait_state(webview, |s| s.learn_notice.as_ref().is_some_and(|n| n.id == notice.id && n.shown));
+ assert_eq!(invoke(webview, "learn_notice_dismiss", json!({ "id": notice.id + 1 })), Ok(Value::Null), "another notice: nothing changes");
+ assert!(invoke(webview, "learn_notice_dismiss", json!({})).is_err(), "the notice is named");
+ assert_eq!(invoke(webview, "learn_notice_dismiss", json!({ "id": notice.id })), Ok(Value::Null));
+ wait_state(webview, |s| s.learn_notice.is_none());
+
+ assert_eq!(invoke(webview, "history_clear_corrected", json!({ "id": id })), Ok(Value::Null));
+ wait_for(|| invoke(webview, "history_entry", json!({ "id": id })).unwrap().get("corrected").is_none_or(Value::is_null).then_some(()));
+ assert!(invoke(webview, "history_clear_corrected", json!({ "id": "not-an-id" })).is_err());
+
+ let (tx, requests) = mpsc::channel::();
+ app.listen_any("voltip://tray", move |ev| {
+ let _ = tx.send(ev.payload().to_owned());
+ });
+ for (command, action) in [("open_suggestions", "suggestions"), ("open_privacy", "privacy")] {
+ assert_eq!(invoke(webview, command, json!({})), Ok(Value::Null));
+ let request: Value = serde_json::from_str(&requests.recv_timeout(STEP_TIMEOUT).expect("the main window is asked")).unwrap();
+ assert_eq!(request, json!({ "action": action }));
+ }
+ });
+}
+
/// Regression (2026-10-29 goal review), through the command layer: with 仅复制到剪贴板 a window
/// switch while the take was processing was reported as 窗口已切换. A take that only copies says
/// nothing about the window (docs/dictation.md §14.3): `Done` via the clipboard without a code, and
diff --git a/apps/desktop/src/App.tsx b/apps/desktop/src/App.tsx
index 26df4bc5..71c2f786 100644
--- a/apps/desktop/src/App.tsx
+++ b/apps/desktop/src/App.tsx
@@ -27,6 +27,7 @@ import {
COPIED_STATE,
Overlay,
isOverlayWindowState,
+ LEARNED_STATE,
} from "./pages/Overlay";
import { Rules } from "./pages/Rules";
import { SettingsDialog } from "./pages/settings/SettingsDialog";
@@ -85,7 +86,7 @@ function Page({ route }: { route: Exclude ;
case "dictionary":
- return ;
+ return ;
case "rules":
return ;
case "devices":
@@ -246,7 +247,8 @@ function Frame({ traySource }: { traySource?: TrayRequestSource }) {
if (overlayWindow) {
return route.state === LIVE_STATE ||
route.state === BLANK_STATE ||
- route.state === COPIED_STATE ? (
+ route.state === COPIED_STATE ||
+ route.state === LEARNED_STATE ? (
) : (
diff --git a/apps/desktop/src/app/router.test.tsx b/apps/desktop/src/app/router.test.tsx
index e1110be4..91b95cfc 100644
--- a/apps/desktop/src/app/router.test.tsx
+++ b/apps/desktop/src/app/router.test.tsx
@@ -20,6 +20,13 @@ describe("parseRoute / routePath", () => {
expect(parseRoute("/history")).toEqual({ name: "history" });
expect(parseRoute("/history?filter=today")).toEqual({ name: "history", filter: "today" });
expect(parseRoute("/dictionary")).toEqual({ name: "dictionary" });
+ // docs/dictation.md §35: the learn notice's 查看 opens the learning suggestions.
+ expect(parseRoute("/dictionary/suggestions")).toEqual({
+ name: "dictionary",
+ view: "suggestions",
+ });
+ expect(routePath({ name: "dictionary", view: "suggestions" })).toBe("/dictionary/suggestions");
+ expect(routePath({ name: "dictionary" })).toBe("/dictionary");
expect(parseRoute("/rules")).toEqual({ name: "rules" });
// regression (2026-09-28): 语音模型 and AI 模型 are pages of the main layout, no longer settings
// groups; every older link (the `/engines` page, the `/settings/engine`, `/settings/speech`,
diff --git a/apps/desktop/src/app/router.tsx b/apps/desktop/src/app/router.tsx
index ad15be2e..cea008a1 100644
--- a/apps/desktop/src/app/router.tsx
+++ b/apps/desktop/src/app/router.tsx
@@ -43,7 +43,8 @@ export const AI_ROUTE: Route = { name: "ai" };
export type Route =
| { name: "home" }
| { name: "history"; filter?: string }
- | { name: "dictionary" }
+ /** `view: "suggestions"`: open the learning suggestions (the learn notice's 查看, §35). */
+ | { name: "dictionary"; view?: "suggestions" }
/** `compose`: open the editor on a new rule (the palette's 新建规则), then drop the flag. */
| { name: "rules"; compose?: true }
| { name: "devices" }
@@ -80,7 +81,9 @@ export function parseRoute(path: string): Route {
return filter === null ? { name: "history" } : { name: "history", filter };
}
case "dictionary":
- return { name: "dictionary" };
+ return second === "suggestions"
+ ? { name: "dictionary", view: "suggestions" }
+ : { name: "dictionary" };
case "rules":
return params.get("new") === "1" ? { name: "rules", compose: true } : { name: "rules" };
case "engines":
@@ -142,6 +145,7 @@ export function routePath(route: Route): string {
case "speech":
return route.section === undefined ? "/speech" : `/speech/${route.section}`;
case "dictionary":
+ return route.view === undefined ? "/dictionary" : `/dictionary/${route.view}`;
case "devices":
case "usage":
case "feedback":
diff --git a/apps/desktop/src/app/tray-requests.test.tsx b/apps/desktop/src/app/tray-requests.test.tsx
index 356da619..f1e9e1ef 100644
--- a/apps/desktop/src/app/tray-requests.test.tsx
+++ b/apps/desktop/src/app/tray-requests.test.tsx
@@ -40,6 +40,9 @@ describe("tray requests", () => {
expect(trayRequestOf({ action: "update" })).toBe("update");
// docs/dictation.md §28: the result card's 打开历史.
expect(trayRequestOf({ action: "history" })).toBe("history");
+ // docs/dictation.md §35: the learn notice's 查看 and 打开设置.
+ expect(trayRequestOf({ action: "suggestions" })).toBe("suggestions");
+ expect(trayRequestOf({ action: "privacy" })).toBe("privacy");
for (const payload of [null, undefined, "settings", {}, { action: "quit" }, { action: 1 }])
expect(trayRequestOf(payload)).toBeUndefined();
});
@@ -96,4 +99,22 @@ describe("tray requests", () => {
await tray.send({ action: "history" });
expect(await screen.findByTestId("page-history")).toBeInTheDocument();
});
+
+ it("docs/dictation.md section 35: the learn notice's 查看 opens the learning suggestions, 打开设置 the privacy settings", async () => {
+ const tray = fakeTray();
+ renderApp({ traySource: tray.source });
+ await waitFor(() => {
+ expect(tray.subscribed()).toBe(true);
+ });
+ await tray.send({ action: "suggestions" });
+ expect(
+ await screen.findByRole("tab", { name: /^学习建议/, selected: true }),
+ ).toBeInTheDocument();
+ await tray.send({ action: "privacy" });
+ expect(await screen.findByRole("dialog", { name: "设置" })).toBeInTheDocument();
+ expect(screen.getByRole("tab", { name: "隐私与历史" })).toHaveAttribute(
+ "aria-selected",
+ "true",
+ );
+ });
});
diff --git a/apps/desktop/src/app/tray-requests.ts b/apps/desktop/src/app/tray-requests.ts
index 7f8ec8f5..7dc3763b 100644
--- a/apps/desktop/src/app/tray-requests.ts
+++ b/apps/desktop/src/app/tray-requests.ts
@@ -3,16 +3,23 @@ import { listen } from "@tauri-apps/api/event";
import { useEffect, useRef } from "react";
/** Event the desktop shell sends the main window for a tray menu entry the webview finishes
- * (`voltip_desktop_lib::platform::tray::TRAY_EVENT`), and for the result card's 打开历史
- * (`open_history`, docs/dictation.md §28); the shell has already shown the window. */
+ * (`voltip_desktop_lib::platform::tray::TRAY_EVENT`), for the result card's 打开历史
+ * (`open_history`, docs/dictation.md §28) and for the learn notice's 查看 (`open_suggestions`,
+ * §35); the shell has already shown the window. */
export const TRAY_EVENT = "voltip://tray";
-export type TrayRequest = "settings" | "update" | "history";
+export type TrayRequest = "settings" | "update" | "history" | "suggestions" | "privacy";
export function trayRequestOf(payload: unknown): TrayRequest | undefined {
if (typeof payload !== "object" || payload === null) return undefined;
const action = (payload as { action?: unknown }).action;
- return action === "settings" || action === "update" || action === "history" ? action : undefined;
+ return action === "settings" ||
+ action === "update" ||
+ action === "history" ||
+ action === "suggestions" ||
+ action === "privacy"
+ ? action
+ : undefined;
}
export interface TrayRequestSource {
diff --git a/apps/desktop/src/pages/Dictionary.test.tsx b/apps/desktop/src/pages/Dictionary.test.tsx
index 390d4da6..adaf849b 100644
--- a/apps/desktop/src/pages/Dictionary.test.tsx
+++ b/apps/desktop/src/pages/Dictionary.test.tsx
@@ -369,6 +369,7 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
const SC = "00000000-0000-4000-8000-0000000000b3";
const SD = "00000000-0000-4000-8000-0000000000b4";
const SE = "00000000-0000-4000-8000-0000000000b5";
+ const SF = "00000000-0000-4000-8000-0000000000b6";
const FEI = "00000000-0000-4000-8000-000000000004";
const BACK = "00000000-0000-4000-9000-0000000000c1";
@@ -389,7 +390,7 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
};
}
- /** Newest first: 非 → 飞 twice, 维他命 → Voltip (an entry already has that spelling), 库伯内特斯 →
+ /** Newest first: 非书 → 飞书 twice, 维他命 → Voltip (an entry already has that spelling), 库伯内特斯 →
* Kubernetes, and a take not polished whose final text keeps 「非」. */
function takes(): HistoryEntry[] {
return [
@@ -426,7 +427,10 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
within(r)
.getAllByRole("cell")
.slice(1, 4)
- .map((c) => c.textContent ?? ""),
+ .map(
+ (c, i) =>
+ (i === 0 ? c.querySelector("[data-testid='suggestion-pair']") : c)?.textContent ?? "",
+ ),
);
}
@@ -463,6 +467,40 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
);
}
+ it("docs/dictation.md §35: a correction made in another app is a suggestion of its own, shown once, with its source", async () => {
+ const user = userEvent.setup();
+ const corrected: HistoryEntry = {
+ ...take(SF, AT - HOUR, "我在用 Quinn for max 做测试", "我在用 Quinn for max 做测试", false),
+ corrected: { text: "我在用 Qwen 4 max 做测试", at_ms: AT - HOUR + 60_000, via: "selection" },
+ };
+ const backend = learning({ history: [corrected, ...takes()] });
+ renderApp({ path: "/dictionary", backend });
+ await openSuggestions(user);
+ // 推荐: seen twice or more, and corrected by the user even once.
+ expect(shownPairs().map((p) => p[0])).toEqual(["非书→飞书", "Quinn for→Qwen 4"]);
+ expect(within(rowOf("Quinn for")).getByTestId("suggestion-sources")).toHaveTextContent(
+ "你的修改",
+ );
+ expect(within(rowOf("非书")).getByTestId("suggestion-sources")).toHaveTextContent("润色");
+ expect(screen.getByTestId("suggestions-footer")).toHaveTextContent("1 条有你的修改");
+ expect(screen.getByTestId("suggestions-explain")).toHaveTextContent(
+ "「推荐」列出出现 2 次及以上的写法",
+ );
+ // No shortcut yet: the card says how corrections get here and leads to the shortcut.
+ const hint = screen.getByTestId("suggestions-learn-hint");
+ await user.click(within(hint).getByRole("button", { name: "设置快捷键" }));
+ expect(await screen.findByTestId("learn-hotkey-recorder")).toBeInTheDocument();
+ });
+
+ it("docs/dictation.md §35: with the shortcut set there is no hint, and /dictionary/suggestions opens the suggestions", async () => {
+ const backend = learning({ settings: { learn_hotkey: "Ctrl+Alt+L" } });
+ renderApp({ path: "/dictionary/suggestions", backend });
+ expect(
+ await screen.findByRole("tab", { name: /^学习建议/, selected: true }),
+ ).toBeInTheDocument();
+ expect(screen.queryByTestId("suggestions-learn-hint")).toBeNull();
+ });
+
it("the page has two views; 学习建议 counts what the clean-up changed and lists it, most frequent first", async () => {
const user = userEvent.setup();
renderApp({ path: "/dictionary", backend: learning() });
@@ -484,13 +522,13 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
expect(screen.getByRole("tabpanel", { name: "学习建议(1)" })).toContainElement(
suggestionTable(),
);
- expect(shownPairs()).toEqual([["非→飞", "2", "2 小时前"]]);
+ expect(shownPairs()).toEqual([["非书→飞书", "2", "2 小时前"]]);
await showAll(user);
expect(suggestions).toHaveAccessibleName("学习建议(3)");
const panel = screen.getByRole("tabpanel", { name: "学习建议(3)" });
expect(panel).toContainElement(suggestionTable());
expect(shownPairs()).toEqual([
- ["非→飞", "2", "2 小时前"],
+ ["非书→飞书", "2", "2 小时前"],
["维他命→Voltip", "1", "5 小时前"],
["库伯内特斯→Kubernetes", "1", "3 天前"],
]);
@@ -524,7 +562,7 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
expect(page.querySelector(".grid")?.className).not.toMatch(/lg:grid-cols-/);
expect(fixedSizeOffenders(page)).toEqual([]);
const header = within(suggestionTable()).getByRole("columnheader", {
- name: "识别结果 → 润色结果",
+ name: "识别结果 → 正确写法",
});
expect(header.style.minWidth).toBe("160px");
await user.click(screen.getByRole("tab", { name: "词条" }));
@@ -560,7 +598,7 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
expect(await screen.findByRole("tab", { name: "学习建议(1)" })).toBeInTheDocument();
// The rows stay where they were while the page is open.
expect(shownPairs().map((r) => r[0])).toEqual([
- "非→飞",
+ "非书→飞书",
"维他命→Voltip",
"库伯内特斯→Kubernetes",
]);
@@ -610,22 +648,26 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
renderApp({ path: "/dictionary", backend });
await openSuggestions(user, /^学习建议(1)$/);
await showAll(user);
- await user.click(screen.getByRole("button", { name: "忽略:非 → 飞" }));
+ await user.click(screen.getByRole("button", { name: "忽略:非书 → 飞书" }));
await waitFor(() => {
- expect(backend.peek().vocabulary_ignored).toMatchObject([{ heard: "非", polished: "飞" }]);
+ expect(backend.peek().vocabulary_ignored).toMatchObject([
+ { heard: "非书", polished: "飞书" },
+ ]);
});
- expect(within(rowOf("非")).getByText("已忽略")).toBeInTheDocument();
+ expect(within(rowOf("非书")).getByText("已忽略")).toBeInTheDocument();
expect(await screen.findByRole("tab", { name: "学习建议(2)" })).toBeInTheDocument();
expect(shownPairs().map((r) => r[0])).toEqual([
- "非→飞",
+ "非书→飞书",
"维他命→Voltip",
"库伯内特斯→Kubernetes",
]);
- await user.click(screen.getByRole("button", { name: "撤销:非 → 飞" }));
+ await user.click(screen.getByRole("button", { name: "撤销:非书 → 飞书" }));
await waitFor(() => {
expect(backend.peek().vocabulary_ignored).toEqual([]);
});
- expect(await within(rowOf("非")).findByRole("button", { name: "忽略:非 → 飞" })).toBeEnabled();
+ expect(
+ await within(rowOf("非书")).findByRole("button", { name: "忽略:非书 → 飞书" }),
+ ).toBeEnabled();
expect(await screen.findByRole("tab", { name: "学习建议(3)" })).toBeInTheDocument();
});
@@ -636,7 +678,7 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
renderApp({ path: "/dictionary", backend });
await openSuggestions(user, /^学习建议(1)$/);
await showAll(user);
- const details = screen.getByRole("button", { name: "详情:非 → 飞" });
+ const details = screen.getByRole("button", { name: "详情:非书 → 飞书" });
expect(details).toHaveAttribute("aria-expanded", "false");
await user.click(details);
expect(details).toHaveAttribute("aria-expanded", "true");
@@ -646,20 +688,20 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
.getAllByRole("listitem")
.map((li) => li.textContent),
).toEqual(["发到非书群", "又是非书"]);
- expect(box).toHaveTextContent("将新建词条「飞」,曾听成「非」。");
- expect(box).toHaveTextContent("「非」只有 1 个字,容易误改其他词语。");
+ // 非 → 飞 is offered with its neighbour (§16.10): two characters, so 「这个非常好」 is not
+ // changed and there is no warning about a one-character spelling.
+ expect(box).toHaveTextContent("将新建词条「飞书」,曾听成「非书」。");
+ expect(box).not.toHaveTextContent("容易误改");
// The backtest the history page's card runs, over the recent takes, none left out.
expect(
- await within(box).findByText("加入后,最近 5 条记录中有 3 条会被改动。"),
- ).toBeInTheDocument();
- expect(
- within(box).getByText("其中 1 条的最终文本仍为「非」,可能是正确用法。"),
+ await within(box).findByText("加入后,最近 5 条记录中有 2 条会被改动。"),
).toBeInTheDocument();
+ expect(within(box).queryByText(/可能是正确用法/)).toBeNull();
expect(backtest).toHaveBeenLastCalledWith({
draft: {
kind: "dictionary",
id: null,
- entry: { term: "飞", heard_as: ["非"], enabled: true },
+ entry: { term: "飞书", heard_as: ["非书"], enabled: true },
},
});
// One row's details at a time; this one merges into the entry with that spelling.
@@ -691,17 +733,17 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
pending: false,
};
const backend = learning({
- dictionary: [...dictionary(), entry(FEI, "飞", [], { enabled: false })],
+ dictionary: [...dictionary(), entry(FEI, "飞书", [], { enabled: false })],
rules: [back],
});
renderApp({ path: "/dictionary", backend });
await openSuggestions(user, /^学习建议(1)$/);
await showAll(user);
- await user.click(screen.getByRole("button", { name: "加入词典:非 → 飞" }));
- expect(await screen.findByText("词条「飞」已停用,启用后才能加入。")).toBeInTheDocument();
+ await user.click(screen.getByRole("button", { name: "加入词典:非书 → 飞书" }));
+ expect(await screen.findByText("词条「飞书」已停用,启用后才能加入。")).toBeInTheDocument();
expect(backend.peek().dictionary.find((e) => e.id === FEI)?.heard_as).toEqual([]);
// The row keeps its buttons: 忽略 is still a way out.
- expect(within(rowOf("非")).getByRole("button", { name: "忽略:非 → 飞" })).toBeEnabled();
+ expect(within(rowOf("非书")).getByRole("button", { name: "忽略:非书 → 飞书" })).toBeEnabled();
await user.click(screen.getByRole("button", { name: "查看词条" }));
expect(screen.getByRole("tab", { name: "词条" })).toHaveAttribute("aria-selected", "true");
const table = screen.getByRole("table", { name: "词条表" });
@@ -737,10 +779,12 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
await act(async () => {
await backend.invoke("vocabulary_suggestion_ignore", { heard: "无", polished: "关" });
});
- await user.click(await screen.findByRole("button", { name: "加入词典:非 → 飞" }));
+ await user.click(await screen.findByRole("button", { name: "加入词典:非书 → 飞书" }));
expect(await screen.findByText("操作失败:not now")).toBeInTheDocument();
- expect(within(rowOf("非")).getByRole("button", { name: "加入词典:非 → 飞" })).toBeEnabled();
- await user.click(screen.getByRole("button", { name: "详情:非 → 飞" }));
+ expect(
+ within(rowOf("非书")).getByRole("button", { name: "加入词典:非书 → 飞书" }),
+ ).toBeEnabled();
+ await user.click(screen.getByRole("button", { name: "详情:非书 → 飞书" }));
expect(await screen.findByText("无法计算影响范围:busy")).toBeInTheDocument();
});
@@ -768,7 +812,9 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
backend: learning({ history: [take(SA, AT - HOUR, "发到非书群", "发到非书群", false)] }),
});
await openSuggestions(user, /^学习建议$/);
- expect(await screen.findByText("最近的记录里没有经过 AI 润色的听写")).toBeInTheDocument();
+ expect(
+ await screen.findByText("最近的记录里没有经过 AI 润色或你改正过的听写"),
+ ).toBeInTheDocument();
expect(screen.queryByRole("table", { name: "学习建议" })).toBeNull();
});
@@ -788,6 +834,36 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
).toBeInTheDocument();
});
+ it("regression: with only corrected takes and nothing new, 学习建议 names the corrections, not 0 polished takes", async () => {
+ // Goal review of PR #260 (2026-11-18): the empty state counted the polished takes only and read
+ // 「最近 0 条经过 AI 润色的记录里」 although the takes it compared were the user's corrections.
+ const user = userEvent.setup();
+ renderApp({
+ path: "/dictionary",
+ backend: learning({
+ dictionary: [entry(VOLTIP, "Qwen 4", ["Quinn for"])],
+ history: [
+ {
+ ...take(
+ SC,
+ AT - HOUR,
+ "我在用 Quinn for max 做测试",
+ "我在用 Quinn for max 做测试",
+ false,
+ ),
+ corrected: { text: "我在用 Qwen 4 max 做测试", at_ms: AT - HOUR, via: "selection" },
+ },
+ ],
+ }),
+ });
+ await openSuggestions(user, /^学习建议$/);
+ expect(await screen.findByText("暂无学习建议")).toBeInTheDocument();
+ expect(
+ screen.getByText("最近 1 条有你修改的记录里,没有新的写法可以加入词典。"),
+ ).toBeInTheDocument();
+ expect(screen.queryByText(/最近 0 条经过 AI 润色/)).toBeNull();
+ });
+
it("忽略 puts the pair on 已忽略(n) with when it was ignored, and 取消忽略 there makes it a suggestion again", async () => {
const user = userEvent.setup();
const backend = learning({ now: () => Date.now() });
@@ -797,25 +873,25 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
await screen.findByRole("table", { name: "学习建议" });
expect(screen.queryByRole("table", { name: "已忽略" })).toBeNull();
- await user.click(within(rowOf("非")).getByRole("button", { name: "忽略:非 → 飞" }));
+ await user.click(within(rowOf("非书")).getByRole("button", { name: "忽略:非书 → 飞书" }));
const ignored = await screen.findByRole("table", { name: "已忽略" });
expect(screen.getByRole("tabpanel", { name: /^学习建议/ })).toContainElement(ignored);
expect(screen.getByText("已忽略(1)")).toBeInTheDocument();
- expect(ignoredRows()).toEqual([["非→飞", "刚刚"]]);
- expect(within(rowOf("非")).getByRole("button", { name: "撤销:非 → 飞" })).toBeEnabled();
+ expect(ignoredRows()).toEqual([["非书→飞书", "刚刚"]]);
+ expect(within(rowOf("非书")).getByRole("button", { name: "撤销:非书 → 飞书" })).toBeEnabled();
- await user.click(within(ignored).getByRole("button", { name: "取消忽略:非 → 飞" }));
+ await user.click(within(ignored).getByRole("button", { name: "取消忽略:非书 → 飞书" }));
await waitFor(() => {
expect(screen.queryByRole("table", { name: "已忽略" })).toBeNull();
});
expect(backend.peek().vocabulary_ignored).toEqual([]);
// The row offers 加入词典 and 忽略 again, not a 撤销 that has nothing left to undo.
expect(
- await within(rowOf("非")).findByRole("button", { name: "加入词典:非 → 飞" }),
+ await within(rowOf("非书")).findByRole("button", { name: "加入词典:非书 → 飞书" }),
).toBeEnabled();
- expect(within(rowOf("非")).queryByRole("button", { name: "撤销:非 → 飞" })).toBeNull();
+ expect(within(rowOf("非书")).queryByRole("button", { name: "撤销:非书 → 飞书" })).toBeNull();
expect(shownPairs().map((p) => p[0])).toEqual([
- "非→飞",
+ "非书→飞书",
"维他命→Voltip",
"库伯内特斯→Kubernetes",
]);
@@ -851,6 +927,7 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
const all = screen.getByRole("button", { name: "显示全部(7)" });
expect(all).toHaveAttribute("aria-expanded", "false");
await user.click(all);
+ // Ignored before the widening: listed as it was ignored, and it still hides 非书 → 飞书.
expect(ignoredRows()).toEqual([...five, ["听成1→写成1", "6 小时前"], ["非→飞", "2 天前"]]);
const less = screen.getByRole("button", { name: "收起" });
expect(less).toHaveAttribute("aria-expanded", "true");
@@ -888,7 +965,7 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
await user.click(screen.getByRole("radio", { name: "All" }));
expect(screen.getByRole("tab", { name: "Suggestions (3)" })).toBeInTheDocument();
expect(screen.getByRole("table", { name: "Suggestions" })).toBeInTheDocument();
- expect(screen.getByRole("button", { name: "Add to dictionary: 非 → 飞" })).toBeEnabled();
+ expect(screen.getByRole("button", { name: "Add to dictionary: 非书 → 飞书" })).toBeEnabled();
expect(screen.getByTestId("suggestions-footer")).toHaveTextContent(
"Last 5 entries · 4 polished",
);
@@ -910,8 +987,8 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
renderApp({ path: "/dictionary", backend: learning() });
await openSuggestions(user, /^学习建议(1)$/);
const filter = screen.getByRole("radiogroup", { name: "显示范围" });
- expect(within(filter).getByRole("radio", { name: "出现 2 次及以上" })).toBeChecked();
- expect(shownPairs().map((p) => p[0])).toEqual(["非→飞"]);
+ expect(within(filter).getByRole("radio", { name: "推荐" })).toBeChecked();
+ expect(shownPairs().map((p) => p[0])).toEqual(["非书→飞书"]);
const footer = screen.getByTestId("suggestions-footer");
expect(footer).toHaveTextContent("显示 1 组 · 隐藏 2 组只出现 1 次的建议");
await showAll(user);
@@ -920,8 +997,8 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
expect(shownPairs()).toHaveLength(3);
expect(footer).toHaveTextContent("显示 3 组");
expect(footer).not.toHaveTextContent("隐藏");
- await user.click(within(filter).getByRole("radio", { name: "出现 2 次及以上" }));
- expect(shownPairs().map((p) => p[0])).toEqual(["非→飞"]);
+ await user.click(within(filter).getByRole("radio", { name: "推荐" }));
+ expect(shownPairs().map((p) => p[0])).toEqual(["非书→飞书"]);
expect(screen.getByRole("tab", { name: "学习建议(1)" })).toBeInTheDocument();
});
@@ -932,7 +1009,7 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
backend: learning({ history: takes().filter((t) => t.id !== SB) }),
});
await openSuggestions(user, /^学习建议$/);
- expect(await screen.findByText("没有出现 2 次及以上的建议")).toBeInTheDocument();
+ expect(await screen.findByText("没有推荐的建议")).toBeInTheDocument();
expect(screen.getByText("另有 3 组只出现 1 次。")).toBeInTheDocument();
expect(screen.queryByRole("table", { name: "学习建议" })).toBeNull();
await user.click(screen.getByRole("button", { name: "显示全部" }));
@@ -950,7 +1027,7 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
expect(all).not.toBeChecked();
expect(screen.queryByText(/^已选/)).toBeNull();
// Tab reaches a row's box and Space checks it.
- const fei = within(rowOf("非")).getByRole("checkbox", { name: "选择:非 → 飞" });
+ const fei = within(rowOf("非书")).getByRole("checkbox", { name: "选择:非书 → 飞书" });
fei.focus();
await user.keyboard(" ");
expect(fei).toBeChecked();
@@ -966,7 +1043,7 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
expect(screen.getByRole("button", { name: "将所选的 3 组加入词典" })).toBeEnabled();
expect(screen.getByRole("button", { name: "忽略所选的 3 组" })).toBeEnabled();
// Rows the filter hides are no longer selected.
- await user.click(screen.getByRole("radio", { name: "出现 2 次及以上" }));
+ await user.click(screen.getByRole("radio", { name: "推荐" }));
expect(screen.getByText("已选 1 组")).toBeInTheDocument();
expect(all).toBeChecked();
await user.click(all);
@@ -1009,20 +1086,20 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
["Voltip", ["沃提普", "维他命"]],
["good idea", ["谷歌IDR"]],
["fetchUser", ["fetch user"]],
- ["飞", ["非"]],
+ ["飞书", ["非书"]],
]);
});
// In the order the list shows them, each with the take of its first example.
expect(batch).toHaveBeenCalledTimes(1);
expect(batch).toHaveBeenCalledWith([
- { heard: "非", polished: "飞", history_id: SA },
+ { heard: "非书", polished: "飞书", history_id: SA },
{ heard: "维他命", polished: "Voltip", history_id: SC },
{ heard: "库伯内特斯", polished: "Kubernetes", history_id: SD },
]);
- expect(within(rowOf("非")).getByText("已加入词典")).toBeInTheDocument();
+ expect(within(rowOf("非书")).getByText("已加入词典")).toBeInTheDocument();
expect(within(rowOf("维他命")).getByText("已加入词典")).toBeInTheDocument();
// A row of a batch has no 撤销 of its own: the batch's is over the list.
- expect(screen.queryByRole("button", { name: "撤销:非 → 飞" })).toBeNull();
+ expect(screen.queryByRole("button", { name: "撤销:非书 → 飞书" })).toBeNull();
expect(
screen.getByText(
"替换规则「改回去」会把「Kubernetes」改成「库伯内特斯」,加入词典后也不会生效。",
@@ -1042,7 +1119,7 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
});
expect(notices()).toEqual([]);
expect(
- await within(rowOf("非")).findByRole("button", { name: "加入词典:非 → 飞" }),
+ await within(rowOf("非书")).findByRole("button", { name: "加入词典:非书 → 飞书" }),
).toBeEnabled();
expect(
within(rowOf("维他命")).getByRole("button", { name: "加入词典:维他命 → Voltip" }),
@@ -1053,13 +1130,13 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
it("a batch nothing could go in from says so, and a 撤销 that comes too late says why and keeps the entries", async () => {
const user = userEvent.setup();
const backend = learning({
- dictionary: [...dictionary(), entry(FEI, "飞", [], { enabled: false })],
+ dictionary: [...dictionary(), entry(FEI, "飞书", [], { enabled: false })],
});
renderApp({ path: "/dictionary", backend });
await openSuggestions(user, /^学习建议(1)$/);
- await user.click(within(rowOf("非")).getByRole("checkbox", { name: "选择:非 → 飞" }));
+ await user.click(within(rowOf("非书")).getByRole("checkbox", { name: "选择:非书 → 飞书" }));
await user.click(screen.getByRole("button", { name: "将所选的 1 组加入词典" }));
- expect(await screen.findByText("词条「飞」已停用,启用后才能加入。")).toBeInTheDocument();
+ expect(await screen.findByText("词条「飞书」已停用,启用后才能加入。")).toBeInTheDocument();
expect(notices()).toEqual(["所选的 1 组都无法加入词典,原因见对应的行。"]);
expect(screen.queryByRole("button", { name: /^撤销:所选的/ })).toBeNull();
@@ -1101,12 +1178,12 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
await waitFor(() => {
expect(backend.peek().vocabulary_ignored.map((p) => p.heard)).toEqual([
"维他命",
- "非",
+ "非书",
"库伯内特斯",
]);
});
expect(ignore).toHaveBeenLastCalledWith([
- { heard: "非", polished: "飞" },
+ { heard: "非书", polished: "飞书" },
{ heard: "库伯内特斯", polished: "Kubernetes" },
]);
expect(notices()).toEqual(["已忽略 2 组。撤销", "已忽略 1 组。撤销"]);
@@ -1118,7 +1195,9 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
expect(backend.peek().vocabulary_ignored.map((p) => p.heard)).toEqual(["维他命"]);
});
expect(notices()).toEqual(["已忽略 1 组。撤销"]);
- expect(await within(rowOf("非")).findByRole("button", { name: "忽略:非 → 飞" })).toBeEnabled();
+ expect(
+ await within(rowOf("非书")).findByRole("button", { name: "忽略:非书 → 飞书" }),
+ ).toBeEnabled();
expect(within(rowOf("维他命")).getByText("已忽略")).toBeInTheDocument();
await user.click(screen.getByRole("button", { name: "撤销:已忽略 1 组。" }));
await waitFor(() => {
@@ -1130,10 +1209,10 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
).toBeEnabled();
// In the default view, 全部忽略 leaves the rows the filter hides alone.
- await user.click(screen.getByRole("radio", { name: "出现 2 次及以上" }));
+ await user.click(screen.getByRole("radio", { name: "推荐" }));
await user.click(screen.getByRole("button", { name: "全部忽略(1)" }));
await waitFor(() => {
- expect(backend.peek().vocabulary_ignored.map((p) => p.heard)).toEqual(["非"]);
+ expect(backend.peek().vocabulary_ignored.map((p) => p.heard)).toEqual(["非书"]);
});
});
@@ -1145,8 +1224,10 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
await user.click(screen.getByRole("button", { name: "全部忽略(1)" }));
const ignored = await screen.findByRole("table", { name: "已忽略" });
expect(notices()).toEqual(["已忽略 1 组。撤销"]);
- await user.click(within(ignored).getByRole("button", { name: "取消忽略:非 → 飞" }));
- expect(await within(rowOf("非")).findByRole("button", { name: "忽略:非 → 飞" })).toBeEnabled();
+ await user.click(within(ignored).getByRole("button", { name: "取消忽略:非书 → 飞书" }));
+ expect(
+ await within(rowOf("非书")).findByRole("button", { name: "忽略:非书 → 飞书" }),
+ ).toBeEnabled();
expect(notices()).toEqual([]);
});
@@ -1160,13 +1241,15 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
});
renderApp({ path: "/dictionary", backend });
await openSuggestions(user, /^学习建议(1)$/);
- await user.click(within(rowOf("非")).getByRole("checkbox", { name: "选择:非 → 飞" }));
+ await user.click(within(rowOf("非书")).getByRole("checkbox", { name: "选择:非书 → 飞书" }));
await user.click(screen.getByRole("button", { name: "将所选的 1 组加入词典" }));
expect(await screen.findByText("操作失败:not now")).toBeInTheDocument();
- expect(within(rowOf("非")).getByRole("button", { name: "加入词典:非 → 飞" })).toBeEnabled();
+ expect(
+ within(rowOf("非书")).getByRole("button", { name: "加入词典:非书 → 飞书" }),
+ ).toBeEnabled();
await user.click(screen.getByRole("button", { name: "全部忽略(1)" }));
expect(await screen.findByText("操作失败:disk full")).toBeInTheDocument();
- expect(within(rowOf("非")).getByRole("button", { name: "忽略:非 → 飞" })).toBeEnabled();
+ expect(within(rowOf("非书")).getByRole("button", { name: "忽略:非书 → 飞书" })).toBeEnabled();
expect(backend.peek().dictionary).toEqual(dictionary());
expect(backend.peek().vocabulary_ignored).toEqual([]);
});
@@ -1175,7 +1258,7 @@ describe("Dictionary page · learning suggestions (docs/dictation.md §16.10)",
const user = userEvent.setup();
renderApp({ path: "/dictionary", backend: learning(), systemLanguage: "en-US" });
await user.click(await screen.findByRole("tab", { name: "Suggestions (1)" }));
- expect(screen.getByRole("radio", { name: "Seen twice or more" })).toBeChecked();
+ expect(screen.getByRole("radio", { name: "Suggested" })).toBeChecked();
expect(screen.getByTestId("suggestions-footer")).toHaveTextContent(
"Showing 1 pair · 2 pairs seen once are hidden",
);
diff --git a/apps/desktop/src/pages/Dictionary.tsx b/apps/desktop/src/pages/Dictionary.tsx
index 80a9de63..660ab48c 100644
--- a/apps/desktop/src/pages/Dictionary.tsx
+++ b/apps/desktop/src/pages/Dictionary.tsx
@@ -24,8 +24,9 @@ import {
useI18n,
useUiState,
} from "@voltip/ui";
-import { type KeyboardEvent, useCallback, useMemo, useState } from "react";
+import { type KeyboardEvent, useCallback, useEffect, useMemo, useState } from "react";
import { usePageShortcuts, withCommand } from "../app/page-shortcuts";
+import { useRouter } from "../app/router";
import { copyWithToast, useShell } from "../app/shell-context";
import { GlossaryNote } from "../features/vocabulary/GlossaryNote";
import { useHitTotals } from "../features/vocabulary/useHitTotals";
@@ -69,8 +70,14 @@ const ASCII_ONLY = /^[\x20-\x7e]+$/;
* counts come from the history rows (`HistoryEntry.vocabulary`); the test panel asks the core
* (`vocabulary_preview`), so it corrects exactly as a take would. 学习建议 (§16.10) is the second
* view: what AI polish changed in the history, for the dictionary. */
-export function Dictionary() {
+export interface DictionaryProps {
+ /** Open on 学习建议 once (`/dictionary/suggestions`, the learn notice's 查看, §35). */
+ openSuggestions?: boolean;
+}
+
+export function Dictionary({ openSuggestions = false }: DictionaryProps) {
const shell = useShell();
+ const { navigate } = useRouter();
const { backend } = useBackend();
const { t } = useI18n();
const state = useUiState();
@@ -83,7 +90,18 @@ export function Dictionary() {
const [deleting, setDeleting] = useState(undefined);
const [sample, setSample] = useState("");
const preview = useVocabularyPreview(sample);
- const [view, setView] = useState("entries");
+ const [view, setView] = useState(openSuggestions ? "suggestions" : "entries");
+ // `/dictionary/suggestions` shows the suggestions: adjusted during render when the flag appears
+ // (React's pattern for state that follows a prop), then the effect drops the flag from the URL so
+ // the next 查看 can ask again.
+ const [opening, setOpening] = useState(openSuggestions);
+ if (opening !== openSuggestions) {
+ setOpening(openSuggestions);
+ if (openSuggestions) setView("suggestions");
+ }
+ useEffect(() => {
+ if (openSuggestions) navigate({ name: "dictionary" }, { replace: true });
+ }, [openSuggestions, navigate]);
// Held by the page, so switching views keeps the rows acted on and their 撤销.
const suggestions = useSuggestions();
diff --git a/apps/desktop/src/pages/Overlay.test.tsx b/apps/desktop/src/pages/Overlay.test.tsx
index 98524616..26d3a9d1 100644
--- a/apps/desktop/src/pages/Overlay.test.tsx
+++ b/apps/desktop/src/pages/Overlay.test.tsx
@@ -4,6 +4,7 @@ import {
livePreviewText,
type DictationPhase,
type DictationStatus,
+ type LearnNotice,
type PasteOutcome,
} from "@voltip/shared";
import {
@@ -1364,3 +1365,109 @@ describe("Overlay result cards (docs/dictation.md §28)", () => {
expect(isOverlayWindowState("copied", false)).toBe(true);
});
});
+
+describe("Overlay learn notice (docs/dictation.md §35)", () => {
+ const pick = {
+ heard: "Quinn for",
+ polished: "Qwen 4",
+ history_id: "00000000-0000-4000-8000-000000000035",
+ };
+ const learned = (safe: boolean, more: Partial = {}): LearnNotice => ({
+ id: 3,
+ outcome: { kind: "learned", pairs: [pick], safe },
+ shown: true,
+ ...more,
+ });
+ const buttons = () =>
+ within(screen.getByTestId("overlay-window"))
+ .queryAllByRole("button")
+ .map((b) => b.getAttribute("aria-label") ?? b.textContent ?? "");
+ /** The window once the core's state (with the notice) has arrived. */
+ const notice = async () => {
+ await waitFor(() => {
+ expect(screen.getByTestId("overlay-window")).toHaveAttribute("data-state", "learned");
+ });
+ return screen.getByTestId("overlay-window");
+ };
+
+ it("offers the pair with 加入词典 and 查看, and the buttons go to the core and the shell", async () => {
+ const user = userEvent.setup();
+ const backend = new MockBackend({ now: () => Date.now() });
+ const invoke = vi.spyOn(backend, "invoke");
+ const view = vi.spyOn(backend, "openSuggestions");
+ backend.showLearnNotice(learned(true));
+ renderApp({ path: "/overlay?state=learned", backend });
+ const pill = await notice();
+ expect(pill).toHaveTextContent("已记下 1 处改动:Quinn for → Qwen 4");
+ expect(buttons()).toEqual(["加入词典", "查看", "关闭"]);
+ await user.click(screen.getByRole("button", { name: "查看" }));
+ expect(view).toHaveBeenCalledTimes(1);
+ // D3: every button starts the notice's 8 seconds again, 查看 included.
+ expect(invoke).toHaveBeenCalledWith("learn_notice_keep", { id: 3 });
+ await user.click(screen.getByRole("button", { name: "加入词典" }));
+ expect(invoke).toHaveBeenCalledWith("learn_notice_accept", { id: 3 });
+ await user.click(screen.getByRole("button", { name: "关闭" }));
+ expect(invoke).toHaveBeenCalledWith("learn_notice_dismiss", { id: 3 });
+ });
+
+ it("a short spelling is only viewed; after 加入词典 there is 撤销, then what it did", async () => {
+ const backend = new MockBackend({ now: () => Date.now() });
+ backend.showLearnNotice(learned(false));
+ renderApp({ path: "/overlay?state=learned", backend });
+ await notice();
+ expect(buttons()).toEqual(["查看", "关闭"]);
+ act(() => {
+ backend.showLearnNotice(learned(true, { accepted: { added: 1, refused: 0, undo: "batch" } }));
+ });
+ expect(screen.getByTestId("overlay-window")).toHaveTextContent(
+ "已加入词典:Quinn for → Qwen 4",
+ );
+ expect(buttons()).toEqual(["撤销", "关闭"]);
+ act(() => {
+ backend.showLearnNotice(learned(true, { accepted: { added: 1, refused: 1, undo: "batch" } }));
+ });
+ expect(screen.getByTestId("overlay-window")).toHaveTextContent("1 处已加入,1 处无法加入");
+ expect(buttons()).toEqual(["查看", "撤销", "关闭"]);
+ act(() => {
+ backend.showLearnNotice(
+ learned(true, {
+ accepted: { added: 1, refused: 0, undo: "batch" },
+ undone: { kind: "undone" },
+ }),
+ );
+ });
+ expect(screen.getByTestId("overlay-window")).toHaveTextContent("已撤销");
+ });
+
+ it("says why there was nothing to learn, and offers the privacy settings while the history is off", async () => {
+ const user = userEvent.setup();
+ const backend = new MockBackend({ now: () => Date.now() });
+ const privacy = vi.spyOn(backend, "openPrivacy");
+ const invoke = vi.spyOn(backend, "invoke");
+ const say = (outcome: LearnNotice["outcome"]) => {
+ act(() => {
+ backend.showLearnNotice({ id: 4, outcome, shown: true });
+ });
+ return screen.getByTestId("overlay-window").textContent;
+ };
+ backend.showLearnNotice({ id: 4, outcome: { kind: "no_match" }, shown: true });
+ renderApp({ path: "/overlay?state=learned", backend });
+ expect(await notice()).toHaveTextContent("最近 50 次听写里没有找到这段文字");
+ expect(say({ kind: "no_selection" })).toContain("没有选中文字");
+ expect(say({ kind: "unchanged" })).toContain("选中的文字和听写结果相同");
+ expect(say({ kind: "no_pairs" })).toContain("没有可以加入词典的改动");
+ expect(say({ kind: "too_long", max: 8000 })).toContain("最多 8000 字");
+ expect(say({ kind: "terminal" })).toContain("终端里的文字不能用来学习");
+ expect(say({ kind: "failed", message: "clipboard busy" })).toContain(
+ "无法读取选中的文字:clipboard busy",
+ );
+ expect(say({ kind: "history_off" })).toContain("需要先开启历史记录");
+ await user.click(screen.getByRole("button", { name: "打开设置" }));
+ expect(privacy).toHaveBeenCalledTimes(1);
+ expect(invoke).toHaveBeenCalledWith("learn_notice_keep", { id: 4 });
+ act(() => {
+ backend.showLearnNotice(null);
+ });
+ expect(screen.getByTestId("overlay-window")).toHaveAttribute("data-state", "blank");
+ });
+});
diff --git a/apps/desktop/src/pages/Overlay.tsx b/apps/desktop/src/pages/Overlay.tsx
index dacd5b0f..5801f386 100644
--- a/apps/desktop/src/pages/Overlay.tsx
+++ b/apps/desktop/src/pages/Overlay.tsx
@@ -2,6 +2,7 @@ import {
DEFAULT_LOCALE,
type DictationPhase,
type DictationStatus,
+ type LearnNotice,
type LiveText,
type Locale,
type MessageKey,
@@ -56,6 +57,10 @@ export const BLANK_STATE = "blank";
export const LIVE_STATE = "live";
/** The shell's flash after 复制上一条结果 (docs/dictation.md §28), between takes. */
export const COPIED_STATE = "copied";
+/** The learn notice after 从选中文字学习 (docs/dictation.md §35): `state.learn_notice`. */
+export const LEARNED_STATE = "learned";
+/** `voltip_core::vocabulary::learn::LEARN_TAKES`: the dictations a selection is compared with. */
+export const LEARN_TAKES = 50;
/** Route states the transparent pill window renders without the shell around it. A single sample
* pill (`state=listening`) is a `pnpm dev` view (`OverlaySheet`); a release build knows only the
@@ -65,6 +70,7 @@ export function isOverlayWindowState(value: string, dev: boolean = import.meta.e
value === BLANK_STATE ||
value === LIVE_STATE ||
value === COPIED_STATE ||
+ value === LEARNED_STATE ||
(dev && isPillState(value))
);
}
@@ -172,6 +178,146 @@ export function pillLiveCaption(
};
}
+/** What the learn notice says, how it looks and which buttons it offers (docs/dictation.md §35):
+ * a card either way, the check for what was learned, added or undone, the alert otherwise. */
+export function learnCard(
+ notice: LearnNotice,
+ t: TFunction,
+): { state: PillState; label: string; buttons: ("add" | "view" | "undo" | "settings")[] } {
+ const o = notice.outcome;
+ switch (o.kind) {
+ case "learned": {
+ const first = o.pairs[0];
+ const pair =
+ first === undefined
+ ? ""
+ : t("learn.notice.pair", { heard: first.heard, polished: first.polished });
+ const accepted = notice.accepted;
+ if (notice.undone !== undefined) {
+ return {
+ state: notice.undone.kind === "undone" ? "inserted" : "error",
+ label:
+ notice.undone.kind === "undone"
+ ? t("learn.notice.undone")
+ : t("learn.notice.undoFailed"),
+ buttons: ["view"],
+ };
+ }
+ if (accepted !== undefined) {
+ const undo = accepted.undo === undefined ? [] : (["undo"] as const);
+ if (accepted.added === 0)
+ return { state: "error", label: t("learn.notice.refusedAll"), buttons: ["view"] };
+ if (accepted.refused > 0) {
+ return {
+ state: "inserted",
+ label: t("learn.notice.addedSome", {
+ n: accepted.added,
+ added: accepted.added,
+ refused: accepted.refused,
+ }),
+ buttons: ["view", ...undo],
+ };
+ }
+ const added =
+ accepted.added === 1
+ ? t("learn.notice.added", { pair })
+ : t("learn.notice.addedMany", { n: accepted.added });
+ return { state: "inserted", label: added, buttons: [...undo] };
+ }
+ return {
+ state: "inserted",
+ label:
+ o.pairs.length === 1
+ ? t("learn.notice.learned", { pair })
+ : t("learn.notice.learnedMany", { n: o.pairs.length, pair }),
+ // A short spelling changes other words too: the dictionary page warns, so it is added there.
+ buttons: o.safe ? ["add", "view"] : ["view"],
+ };
+ }
+ case "no_pairs":
+ return { state: "error", label: t("learn.notice.noPairs"), buttons: [] };
+ case "unchanged":
+ return { state: "error", label: t("learn.notice.unchanged"), buttons: [] };
+ case "no_match":
+ return { state: "error", label: t("learn.notice.noMatch", { n: LEARN_TAKES }), buttons: [] };
+ case "no_selection":
+ return { state: "error", label: t("learn.notice.noSelection"), buttons: [] };
+ case "too_long":
+ return { state: "error", label: t("learn.notice.tooLong", { max: o.max }), buttons: [] };
+ case "terminal":
+ return { state: "error", label: t("learn.notice.terminal"), buttons: [] };
+ case "history_off":
+ return { state: "error", label: t("learn.notice.historyOff"), buttons: ["settings"] };
+ case "failed":
+ return {
+ state: "error",
+ label: t("learn.notice.failed", { message: o.message }),
+ buttons: [],
+ };
+ }
+}
+
+/** The pill window's learn notice: the card, its buttons and ×, all through the core. */
+function LearnedCard({ notice, theme }: { notice: LearnNotice; theme: string }) {
+ const { backend } = useBackend();
+ const { t } = useI18n();
+ const card = learnCard(notice, t);
+ const id = notice.id;
+ const actions: PillAction[] = card.buttons.map((button) => {
+ switch (button) {
+ case "add":
+ return {
+ label: t("learn.notice.add"),
+ primary: true,
+ onClick: () => {
+ void backend.invoke("learn_notice_accept", { id });
+ },
+ };
+ case "undo":
+ return {
+ label: t("learn.notice.undo"),
+ onClick: () => {
+ void backend.invoke("learn_notice_undo", { id });
+ },
+ };
+ case "settings":
+ return {
+ label: t("learn.notice.openSettings"),
+ primary: true,
+ onClick: () => {
+ // Like the other buttons, it starts the notice's stay again (D3).
+ void backend.invoke("learn_notice_keep", { id });
+ void backend.openPrivacy();
+ },
+ };
+ case "view":
+ return {
+ label: t("learn.notice.view"),
+ onClick: () => {
+ void backend.invoke("learn_notice_keep", { id });
+ void backend.openSuggestions();
+ },
+ };
+ }
+ });
+ return (
+
+
{
+ void backend.invoke("learn_notice_dismiss", { id });
+ }}
+ />
+
+ );
+}
+
/** The transparent pill window. The shell loads it on `state=live` and only shows / hides it; the
* pill itself follows `state.dictation`, the meter channel and the live preview. */
export function Overlay({ state }: OverlayProps) {
@@ -196,6 +342,15 @@ export function Overlay({ state }: OverlayProps) {
const now = useTickingNow(listening);
const stageNow = useStageNow(pill !== undefined && dictation.phase.phase === "processing");
+ if (current === LEARNED_STATE) {
+ const notice = uiState.learn_notice;
+ if (notice == null) {
+ return (
+
+ );
+ }
+ return ;
+ }
if (current === COPIED_STATE) {
return (
,
+ cell: (s) => (
+
+
+ {/* docs/dictation.md §35: where the pair came from, both when both did. */}
+
+ {s.count > s.from_edits && {t("dictionary.suggestions.source.polish")} }
+ {s.from_edits > 0 && (
+ {t("dictionary.suggestions.source.edit")}
+ )}
+
+
+ ),
},
{
id: "count",
@@ -560,7 +573,7 @@ export function SuggestionsPanel({ view, onShowEntry }: SuggestionsPanelProps) {
}>
{t("dictionary.suggestions.empty.historyOff")}
- ) : load.answer.refined === 0 ? (
+ ) : load.answer.refined === 0 && load.answer.edited === 0 ? (
{t("dictionary.suggestions.empty.noPolished")}
@@ -580,7 +593,14 @@ export function SuggestionsPanel({ view, onShowEntry }: SuggestionsPanelProps) {
) : (
- {t("dictionary.suggestions.empty.none", { n: load.answer.refined })}
+ {load.answer.edited === 0
+ ? t("dictionary.suggestions.empty.none", { n: load.answer.refined })
+ : load.answer.refined === 0
+ ? t("dictionary.suggestions.empty.noneEdited", { n: load.answer.edited })
+ : t("dictionary.suggestions.empty.noneBoth", {
+ refined: load.answer.refined,
+ edited: load.answer.edited,
+ })}
);
@@ -593,6 +613,7 @@ export function SuggestionsPanel({ view, onShowEntry }: SuggestionsPanelProps) {
const hiddenOnce = view.filter === "repeated" ? answer.total - answer.repeated : 0;
return [
t("dictionary.suggestions.footer", { n: answer.scanned, refined: answer.refined }),
+ ...(answer.edited > 0 ? [t("dictionary.suggestions.edited", { n: answer.edited })] : []),
...(answer.skipped > 0 ? [t("dictionary.suggestions.skipped", { n: answer.skipped })] : []),
inView > listed
? t("dictionary.suggestions.more", { shown: listed, total: inView })
@@ -634,8 +655,25 @@ export function SuggestionsPanel({ view, onShowEntry }: SuggestionsPanelProps) {
{t("dictionary.suggestions.explain")}
- {t("dictionary.suggestions.undoNote")}
+ {t("dictionary.suggestions.filterNote")} {t("dictionary.suggestions.undoNote")}
+ {/* docs/dictation.md §35: how the user's corrections get here, while no shortcut is set. */}
+ {learnHotkey == null && (
+
+
+ {t("dictionary.suggestions.hint")}
+
+ {
+ navigate({ name: "settings", section: "hotkey" });
+ }}>
+ {t("dictionary.suggestions.hintSet")}
+
+
+ )}
diff --git a/apps/desktop/src/pages/dictionary/useSuggestions.ts b/apps/desktop/src/pages/dictionary/useSuggestions.ts
index e526ad3b..74ac0426 100644
--- a/apps/desktop/src/pages/dictionary/useSuggestions.ts
+++ b/apps/desktop/src/pages/dictionary/useSuggestions.ts
@@ -110,9 +110,10 @@ const INITIAL: State = {
busy: false,
};
-/** Whether a row passes `filter`. */
+/** Whether a row passes `filter`: 推荐 takes the pairs seen twice or more and those the user
+ * corrected themselves (docs/dictation.md §35). */
export function passes(row: Suggestion, filter: SuggestionsFilter): boolean {
- return filter === "all" || row.count >= SUGGESTION_REPEATED_MIN;
+ return filter === "all" || row.count >= SUGGESTION_REPEATED_MIN || row.from_edits > 0;
}
/** Whether a row with `action` is still to decide: never acted on, or the action did nothing. */
diff --git a/apps/desktop/src/pages/history/DetailParts.tsx b/apps/desktop/src/pages/history/DetailParts.tsx
index 0f18911c..fa5c1bb6 100644
--- a/apps/desktop/src/pages/history/DetailParts.tsx
+++ b/apps/desktop/src/pages/history/DetailParts.tsx
@@ -1,5 +1,6 @@
// Parts of the history detail moved out of `History.tsx` unchanged: a voice edit's detail, the
-// dictionary corrections and rules that fired, and the timing bar.
+// dictionary corrections and rules that fired, and the timing bar; and the user's correction of a
+// take (docs/dictation.md §35).
import {
type EditRecord,
type HistoryEntry,
@@ -7,9 +8,10 @@ import {
type TFunction,
type VocabularyHit,
formatCount,
+ formatDateTime,
isImported,
} from "@voltip/shared";
-import { Lamp, type LampTone, useUiState } from "@voltip/ui";
+import { Button, Lamp, type LampTone, useBackend, useI18n, useUiState } from "@voltip/ui";
import { textChars } from "../../features/history/stats";
/** A voice edit's detail (docs/dictation.md §19.5): the instruction as sent to the LLM, the
@@ -239,3 +241,42 @@ export function TimingBar({ entry, t }: { entry: HistoryEntry; t: TFunction }) {
);
}
+
+/** What the user corrected the take to in the application it went to (docs/dictation.md §35): the
+ * corrected text, when and how it was read, and 移除, which forgets it (the learning suggestions
+ * then leave its pairs out). The take's own text stays what was inserted. */
+export function CorrectedDetail({ entry }: { entry: HistoryEntry }) {
+ const { backend } = useBackend();
+ const { t, locale } = useI18n();
+ const corrected = entry.corrected;
+ if (corrected === undefined) return null;
+ return (
+
+
+
{t("learn.history.corrected")}
+
+ {corrected.text}
+
+
+ {t(corrected.via === "follow" ? "learn.history.viaFollow" : "learn.history.via", {
+ time: formatDateTime(locale, corrected.at_ms, {
+ dateStyle: "medium",
+ timeStyle: "short",
+ }),
+ })}
+
+
+
{
+ void backend.invoke("history_clear_corrected", { id: entry.id });
+ }}>
+ {t("learn.history.remove")}
+
+
+ );
+}
diff --git a/apps/desktop/src/pages/history/HistoryDetail.test.tsx b/apps/desktop/src/pages/history/HistoryDetail.test.tsx
index 400fa9a2..40568b41 100644
--- a/apps/desktop/src/pages/history/HistoryDetail.test.tsx
+++ b/apps/desktop/src/pages/history/HistoryDetail.test.tsx
@@ -814,3 +814,43 @@ describe("History detail · technical details", () => {
});
});
});
+
+describe("history detail · the user's correction (docs/dictation.md §35)", () => {
+ it("shows what the take was corrected to, and 移除 forgets it while the inserted text stays", async () => {
+ const corrected = take(9, "我在用 Quinn for max 做测试", "我在用 Quinn for max 做测试", {
+ refined: false,
+ at_ms: T,
+ corrected: { text: "我在用 Qwen 4 max 做测试", at_ms: T, via: "selection" },
+ });
+ const { backend, user } = setup({ history: [corrected, ...OTHERS] });
+ const box = await screen.findByTestId("history-corrected");
+ expect(box).toHaveTextContent("之后改成");
+ expect(box).toHaveTextContent("我在用 Qwen 4 max 做测试");
+ expect(box).toHaveTextContent("从选中文字学习");
+ await user.click(within(box).getByRole("button", { name: "移除之后改成的文字" }));
+ await waitFor(() => {
+ expect(screen.queryByTestId("history-corrected")).toBeNull();
+ });
+ expect(backend.peek().history_recent[0]?.corrected).toBeUndefined();
+ expect(backend.peek().history_recent[0]?.text).toBe("我在用 Quinn for max 做测试");
+ });
+
+ it("a correction a later version read in the text field loads and says so", async () => {
+ const corrected = take(9, "我在用 Quinn for max 做测试", "我在用 Quinn for max 做测试", {
+ refined: false,
+ at_ms: T,
+ corrected: { text: "我在用 Qwen 4 max 做测试", at_ms: T, via: "follow" },
+ });
+ setup({ history: [corrected, ...OTHERS] });
+ const box = await screen.findByTestId("history-corrected");
+ expect(box).toHaveTextContent("我在用 Qwen 4 max 做测试");
+ expect(box).toHaveTextContent("在输入框中修改");
+ expect(box).not.toHaveTextContent("从选中文字学习");
+ });
+
+ it("a take nobody corrected has no such line", async () => {
+ setup();
+ expect(await screen.findByTestId("entry-text")).toBeInTheDocument();
+ expect(screen.queryByTestId("history-corrected")).toBeNull();
+ });
+});
diff --git a/apps/desktop/src/pages/history/HistoryDetail.tsx b/apps/desktop/src/pages/history/HistoryDetail.tsx
index 1f10a236..fb9a3a74 100644
--- a/apps/desktop/src/pages/history/HistoryDetail.tsx
+++ b/apps/desktop/src/pages/history/HistoryDetail.tsx
@@ -51,7 +51,7 @@ import {
useHistoryProcess,
} from "../../features/history/LongEntryTools";
import { textChars } from "../../features/history/stats";
-import { EditDetail, TimingBar, VocabularyHits } from "./DetailParts";
+import { CorrectedDetail, EditDetail, TimingBar, VocabularyHits } from "./DetailParts";
import { DiffText, MarkedText } from "./FixText";
import { type CardOpen, KnownCard, QuickFixCard, type SavedFix } from "./QuickFixCard";
import { SelectionToolbar } from "./SelectionToolbar";
@@ -652,6 +652,7 @@ export function HistoryDetail({
{t("history.liveError", { reason: entry.live_error })}
)}
+
{entry.vocabulary !== undefined && }
{!sentAsText(entry) && }
diff --git a/apps/desktop/src/pages/settings/Hotkey.tsx b/apps/desktop/src/pages/settings/Hotkey.tsx
index 2e65c820..fed8fbde 100644
--- a/apps/desktop/src/pages/settings/Hotkey.tsx
+++ b/apps/desktop/src/pages/settings/Hotkey.tsx
@@ -288,7 +288,9 @@ function SoloKeyRow({
* `settings.edit_hotkey` with its own recorder (`settings_set_edit_hotkey`, `null` = off) and the
* shell's `edit_registered` / `edit_error`; it needs the AI refine service, which the row says.
* 复制上一条结果 (§28) is `settings.copy_last_hotkey` with a recorder of its own
- * (`settings_set_copy_last_hotkey`, none by default) and `copy_last_registered` / `copy_last_error`. */
+ * (`settings_set_copy_last_hotkey`, none by default) and `copy_last_registered` / `copy_last_error`;
+ * 从选中文字学习 (§35) likewise with `settings.learn_hotkey`, `settings_set_learn_hotkey` and
+ * `learn_registered` / `learn_error`. */
export function Hotkey() {
const shell = useShell();
const { backend } = useBackend();
@@ -355,21 +357,42 @@ export function Hotkey() {
);
const copyLastRecorder = useChordRecorder({ onCommit: saveCopyLast, onReject: reject });
const copyLastRecording = copyLastRecorder.recording;
+ // docs/dictation.md §35: 从选中文字学习, recorded the same way; none by default.
+ const learnHotkey = state.settings.learn_hotkey ?? null;
+ const learnRegistered = learnHotkey !== null && status.learn_registered === learnHotkey;
+ const saveLearn = useCallback(
+ (combo: string | null) => {
+ void backend.invoke("settings_set_learn_hotkey", { hotkey: combo });
+ },
+ [backend],
+ );
+ const learnRecorder = useChordRecorder({ onCommit: saveLearn, onReject: reject });
+ const learnRecording = learnRecorder.recording;
+ // One recorder at a time.
const startRecording = () => {
editRecorder.cancel();
copyLastRecorder.cancel();
+ learnRecorder.cancel();
recorder.start();
};
const startEditRecording = () => {
recorder.cancel();
copyLastRecorder.cancel();
+ learnRecorder.cancel();
editRecorder.start();
};
const startCopyLastRecording = () => {
recorder.cancel();
editRecorder.cancel();
+ learnRecorder.cancel();
copyLastRecorder.start();
};
+ const startLearnRecording = () => {
+ recorder.cancel();
+ editRecorder.cancel();
+ copyLastRecorder.cancel();
+ learnRecorder.start();
+ };
const platformText = platform ? platformLabel(platform, locale) : "—";
const method = status.backend.length > 0 ? hotkeyMethodText(status.backend) : undefined;
@@ -579,6 +602,67 @@ export function Hotkey() {
)}
+ {/* docs/dictation.md §35: 从选中文字学习. */}
+
+
+ {learnRecording ? (
+ learnRecorder.preview ? (
+
+ ) : (
+
+ {t("settings.hotkey.recording")}
+
+ )
+ ) : learnHotkey === null ? (
+
+ {t("learn.settings.none")}
+
+ ) : (
+ <>
+
+
+ {status.learn_error
+ ? t("settings.hotkey.savedFailed")
+ : learnRegistered
+ ? t("settings.hotkey.savedOk")
+ : t("settings.hotkey.savedWaiting")}
+
+ >
+ )}
+
+ {learnRecording
+ ? t("settings.hotkey.cancelRecording")
+ : learnHotkey === null
+ ? t("learn.settings.record")
+ : t("settings.hotkey.record")}
+
+ {learnHotkey !== null && (
+ {
+ learnRecorder.cancel();
+ saveLearn(null);
+ }}>
+ {t("learn.settings.clear")}
+
+ )}
+
+
)}
+ {status.learn_error && (
+
+ {t("settings.hotkey.change")}
+
+ }>
+ {status.learn_error}
+
+ )}
{t("settings.hotkey.storage", { hotkey })}
diff --git a/apps/desktop/src/pages/settings/Settings.test.tsx b/apps/desktop/src/pages/settings/Settings.test.tsx
index 8875b875..0efaf360 100644
--- a/apps/desktop/src/pages/settings/Settings.test.tsx
+++ b/apps/desktop/src/pages/settings/Settings.test.tsx
@@ -1042,6 +1042,63 @@ describe("Settings · 热键", () => {
expect(screen.getByTestId("copy-last-hotkey-status")).toHaveTextContent("未设置");
});
+ it("docs/dictation.md section 35: 从选中文字学习 has its own recorder, none by default, and refuses the other three chords", async () => {
+ const user = userEvent.setup();
+ const { backend } = renderApp({ path: "/settings/hotkey" });
+ const learn = await screen.findByTestId("learn-hotkey-recorder");
+ const copyLast = screen.getByTestId("copy-last-hotkey-recorder");
+ expect(screen.getByText("从选中文字学习")).toBeInTheDocument();
+ expect(screen.getByText(/选中改好的文字按这个快捷键/)).toBeInTheDocument();
+ expect(screen.getByTestId("learn-hotkey-status")).toHaveTextContent("未设置");
+ expect(screen.queryByRole("button", { name: "清除 · 从选中文字学习" })).toBeNull();
+ // One recorder at a time.
+ await user.click(screen.getByRole("button", { name: "录制 · 复制上一条结果" }));
+ expect(copyLast).toHaveAttribute("data-recording", "true");
+ await user.click(screen.getByRole("button", { name: "录制 · 从选中文字学习" }));
+ expect(copyLast).toHaveAttribute("data-recording", "false");
+ expect(learn).toHaveAttribute("data-recording", "true");
+ await user.keyboard("{Control>}{Alt>}{l>}");
+ await user.keyboard("{/l}{/Alt}{/Control}");
+ await waitFor(() => {
+ expect(backend.peek().settings.learn_hotkey).toBe("Ctrl+Alt+L");
+ });
+ expect(screen.getByTestId("learn-hotkey-status")).toHaveTextContent("已保存 · 快捷键已生效");
+ // The voice edit's chord is refused with the core's reason; the chord stays.
+ await user.click(screen.getByRole("button", { name: "重新录制 · 从选中文字学习" }));
+ await user.keyboard("{Control>}{Alt>}{e>}{/e}{/Alt}{/Control}");
+ await waitFor(() => {
+ expect(
+ backend.log.some(
+ (e) =>
+ e.type === "error" &&
+ e.message === "learn_hotkey: Ctrl+Alt+E 已用作「编辑选中文本」的快捷键",
+ ),
+ ).toBe(true);
+ });
+ expect(backend.peek().settings.learn_hotkey).toBe("Ctrl+Alt+L");
+ // The shell could not register it: the row says so and the banner offers a new chord.
+ act(() => {
+ backend.publish({
+ type: "hotkey",
+ registered: DEFAULT_HOTKEY,
+ learn_error: "Ctrl+Alt+L 与另一个快捷键相同,未生效",
+ pressed: false,
+ capturing: false,
+ backend: "global-shortcut · Windows · RegisterHotKey",
+ });
+ });
+ expect(await screen.findByText("Ctrl+Alt+L 与另一个快捷键相同,未生效")).toBeInTheDocument();
+ expect(screen.getByTestId("learn-hotkey-status")).toHaveTextContent("已保存 · 未能生效");
+ await user.click(screen.getByRole("button", { name: "更换快捷键" }));
+ expect(learn).toHaveAttribute("data-recording", "true");
+ await user.keyboard("{Escape}");
+ await user.click(screen.getByRole("button", { name: "清除 · 从选中文字学习" }));
+ await waitFor(() => {
+ expect(backend.peek().settings).not.toHaveProperty("learn_hotkey");
+ });
+ expect(screen.getByTestId("learn-hotkey-status")).toHaveTextContent("未设置");
+ });
+
it("regression: without a refine key the edit row says it needs the AI refine service (section 19)", async () => {
const backend = new MockBackend({
settings: { engines: { ...defaultEngineSettings(), llm_provider: "groq" } },
diff --git a/apps/desktop/src/shell/Shell.tsx b/apps/desktop/src/shell/Shell.tsx
index 4355b186..e104ddf2 100644
--- a/apps/desktop/src/shell/Shell.tsx
+++ b/apps/desktop/src/shell/Shell.tsx
@@ -267,6 +267,14 @@ export function Shell({
navigate({ name: "history" });
return;
}
+ if (request === "suggestions") {
+ navigate({ name: "dictionary", view: "suggestions" });
+ return;
+ }
+ if (request === "privacy") {
+ navigate({ name: "settings", section: "privacy" });
+ return;
+ }
shell.setUpdateOpen(true);
if (updateState === "idle" || updateState === "up_to_date" || updateState === "failed")
void backend.invoke("update_check");
diff --git a/apps/mobile-rn/rust/tests/shell.rs b/apps/mobile-rn/rust/tests/shell.rs
index a7c0e5e3..7466fa1a 100644
--- a/apps/mobile-rn/rust/tests/shell.rs
+++ b/apps/mobile-rn/rust/tests/shell.rs
@@ -54,6 +54,15 @@ const DESKTOP_ONLY: &[&str] = &[
// The dictionary's learning suggestions (docs/dictation.md §16.10) are the desktop's.
"vocabulary_suggestion_ignore",
"vocabulary_suggestion_unignore",
+ // 从选中文字学习 (docs/dictation.md §35): the desktop's hotkey, pill and history detail.
+ "settings_set_learn_hotkey",
+ "learn_notice_accept",
+ "learn_notice_undo",
+ "learn_notice_dismiss",
+ "learn_notice_keep",
+ "history_clear_corrected",
+ "open_suggestions",
+ "open_privacy",
// The automatic backups (docs/dictation.md §4.6.1) are the desktop's.
"settings_set_backup",
"backup_folder_choose",
diff --git a/apps/mobile/src-tauri/tests/ipc.rs b/apps/mobile/src-tauri/tests/ipc.rs
index 3fdd1e79..8436f0f0 100644
--- a/apps/mobile/src-tauri/tests/ipc.rs
+++ b/apps/mobile/src-tauri/tests/ipc.rs
@@ -817,6 +817,15 @@ const DESKTOP_ONLY: &[&str] = &[
"vocabulary_suggestions_ignore",
"vocabulary_suggestions_undo",
"rules_warnings",
+ // 从选中文字学习 (docs/dictation.md §35): the desktop's hotkey, pill and history detail.
+ "settings_set_learn_hotkey",
+ "learn_notice_accept",
+ "learn_notice_undo",
+ "learn_notice_dismiss",
+ "learn_notice_keep",
+ "history_clear_corrected",
+ "open_suggestions",
+ "open_privacy",
// The automatic backups (docs/dictation.md §4.6.1).
"settings_set_backup",
"backup_folder_choose",
diff --git a/apps/mobile/src/App.test.tsx b/apps/mobile/src/App.test.tsx
index de8d5825..088b49fd 100644
--- a/apps/mobile/src/App.test.tsx
+++ b/apps/mobile/src/App.test.tsx
@@ -272,6 +272,8 @@ describe("Mobile app flow", () => {
overlayCopy: inner.overlayCopy.bind(inner),
overlayPaste: inner.overlayPaste.bind(inner),
openHistory: inner.openHistory.bind(inner),
+ openSuggestions: inner.openSuggestions.bind(inner),
+ openPrivacy: inner.openPrivacy.bind(inner),
providerConsoleOpen: inner.providerConsoleOpen.bind(inner),
projectLinkOpen: inner.projectLinkOpen.bind(inner),
guideOpen: inner.guideOpen.bind(inner),
@@ -341,6 +343,8 @@ describe("Mobile app flow", () => {
overlayCopy: identityless.overlayCopy.bind(identityless),
overlayPaste: identityless.overlayPaste.bind(identityless),
openHistory: identityless.openHistory.bind(identityless),
+ openSuggestions: identityless.openSuggestions.bind(identityless),
+ openPrivacy: identityless.openPrivacy.bind(identityless),
providerConsoleOpen: identityless.providerConsoleOpen.bind(identityless),
projectLinkOpen: identityless.projectLinkOpen.bind(identityless),
guideOpen: identityless.guideOpen.bind(identityless),
diff --git a/crates/voltip-core/src/dictation/engine.rs b/crates/voltip-core/src/dictation/engine.rs
index 15f26c01..4dc4857a 100644
--- a/crates/voltip-core/src/dictation/engine.rs
+++ b/crates/voltip-core/src/dictation/engine.rs
@@ -3748,6 +3748,7 @@ impl DictationEngine {
preset: (refined && self.status.kind == TakeKind::Dictation).then(|| self.take_preset().to_ref()),
origin: None,
processed: None,
+ corrected: None,
file: None,
timing: Some(timing),
glossary_sent,
diff --git a/crates/voltip-core/src/dictation/fakes.rs b/crates/voltip-core/src/dictation/fakes.rs
index 98d8c40e..a43b7b76 100644
--- a/crates/voltip-core/src/dictation/fakes.rs
+++ b/crates/voltip-core/src/dictation/fakes.rs
@@ -1074,6 +1074,9 @@ pub enum InsertEvent {
Dropped,
}
+/// A yes / no about an application id (a host's table of terminals).
+type AppIdTest = Arc
bool + Send + Sync>;
+
/// Injector stand-in: records every text it was given. Optionally gated ([`FakeInjector::gated`]):
/// every call then blocks until a permit is [`FakeInjector::release`]d, so a test can observe what
/// the core does while an injection is in flight. In an insert session the gate holds a piece
@@ -1095,7 +1098,9 @@ pub struct FakeInjector {
/// Texts put on the clipboard alone (`Injector::copy`).
clipboard: Mutex>,
/// Which application ids are terminals (docs/dictation.md §19.2).
- terminals: Arc bool + Send + Sync>,
+ terminals: AppIdTest,
+ /// Which are terminals for 从选中文字学习 (§35), when it differs from `terminals` (macOS).
+ program_output: Option,
/// Holds a session's piece once `may_deliver` agreed.
delivery_gate: Option>,
/// Every insert session step.
@@ -1138,6 +1143,7 @@ impl FakeInjector {
copy_gate: None,
clipboard: Mutex::new(Vec::new()),
terminals: Arc::new(|_: &str| false),
+ program_output: None,
delivery_gate: None,
events: Mutex::new(Vec::new()),
focus: None,
@@ -1165,6 +1171,12 @@ impl FakeInjector {
Self { terminals: Arc::new(terminals), ..self }
}
+ /// The applications `terminals` says yes to hold program output for 从选中文字学习
+ /// (docs/dictation.md §35) although the voice edit's table has none of them (macOS's).
+ pub fn with_program_output(self, terminals: impl Fn(&str) -> bool + Send + Sync + 'static) -> Self {
+ Self { program_output: Some(Arc::new(terminals)), ..self }
+ }
+
/// Report [`SelectionTiming::AfterKeyUp`] (an X11 session).
pub fn after_key_up(self) -> Self {
Self { timing: SelectionTiming::AfterKeyUp, ..self }
@@ -1352,6 +1364,10 @@ impl Injector for FakeInjector {
(self.terminals)(app_id)
}
+ fn holds_program_output(&self, app_id: &str) -> bool {
+ self.program_output.as_ref().map_or_else(|| (self.terminals)(app_id), |f| f(app_id))
+ }
+
fn focus_reader(&self) -> Option> {
self.focus.clone().map(|reader| reader as Arc)
}
@@ -1763,6 +1779,7 @@ pub fn history_entry(text: &str) -> crate::HistoryEntry {
preset: None,
origin: None,
processed: None,
+ corrected: None,
file: None,
timing: None,
glossary_sent: None,
diff --git a/crates/voltip-core/src/dictation/ports.rs b/crates/voltip-core/src/dictation/ports.rs
index 51a39356..e160f891 100644
--- a/crates/voltip-core/src/dictation/ports.rs
+++ b/crates/voltip-core/src/dictation/ports.rs
@@ -1100,6 +1100,15 @@ pub trait Injector: Send + Sync + 'static {
false
}
+ /// Whether `app_id` is a terminal on this host for 从选中文字学习 (docs/dictation.md §35): its
+ /// selection is program output, not a dictation the user corrected, so nothing is copied there.
+ /// Unlike [`Injector::is_terminal_app`] this includes macOS's terminals, where Cmd+C copies
+ /// without reaching the program but the text is still not a dictation. The default is the
+ /// voice edit's table.
+ fn holds_program_output(&self, app_id: &str) -> bool {
+ self.is_terminal_app(app_id)
+ }
+
/// The reader that checks whether a paste reached the focused field (docs/dictation.md §28).
/// The default — the phone, the local speech service, most fakes — has none: no check runs.
fn focus_reader(&self) -> Option> {
diff --git a/crates/voltip-core/src/history/derived.rs b/crates/voltip-core/src/history/derived.rs
index 851b3ef5..81248ca5 100644
--- a/crates/voltip-core/src/history/derived.rs
+++ b/crates/voltip-core/src/history/derived.rs
@@ -72,7 +72,8 @@ pub(super) const fn outcome_name(outcome: &Outcome) -> &'static str {
/// The text `history_query` searches: the fields the history page searched when it filtered in the
/// webview — a built-in scene's name in both languages, the text, the transcript, both models, the
/// application's name and id, the scene's name, the voice edit's instruction and selection — the
-/// processed text (docs/dictation.md §22) and an imported file's name (§31), each lowercased on its
+/// processed text (docs/dictation.md §22), the user's correction (§35) and an imported file's name
+/// (§31), each lowercased on its
/// own and joined by [`FIELD_SEPARATOR`].
pub(super) fn search_text(entry: &HistoryEntry) -> String {
let builtin = entry.scene.as_ref().and_then(|s| s.builtin);
@@ -89,6 +90,7 @@ pub(super) fn search_text(entry: &HistoryEntry) -> String {
entry.edit.as_ref().map(|e| e.instruction.as_str()),
entry.edit.as_ref().map(|e| e.selection.as_str()),
entry.processed.as_ref().map(|p| p.text.as_str()),
+ entry.corrected.as_ref().map(|c| c.text.as_str()),
entry.file.as_ref().map(|f| f.name.as_str()),
];
let mut out = String::new();
diff --git a/crates/voltip-core/src/history/mod.rs b/crates/voltip-core/src/history/mod.rs
index 65a60962..ab2aae28 100644
--- a/crates/voltip-core/src/history/mod.rs
+++ b/crates/voltip-core/src/history/mod.rs
@@ -189,6 +189,12 @@ pub struct HistoryEntry {
/// was. Absent until it ran. Boxed: most entries have none.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub processed: Option>,
+ /// What the user corrected the inserted text to in the application it went to, as 从选中文字学习
+ /// read it (docs/dictation.md §35): the whole take with the user's wording where they changed
+ /// it. The learning suggestions learn from it; `text` stays what was inserted. Absent until the
+ /// user taught it, and in entries written before it. Boxed: most entries have none.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub corrected: Option>,
/// The audio or video file the entry was transcribed from (docs/dictation.md §31); absent for
/// takes and in entries written before it. Such an entry is no dictation of the user's: it
/// counts toward no statistics and teaches the dictionary nothing.
@@ -226,6 +232,29 @@ pub struct ProcessedText {
pub at_ms: u64,
}
+/// The user's correction of a take (docs/dictation.md §35): the take's whole text as they left it,
+/// when it was read, and how.
+#[derive(Clone, PartialEq, Eq, Debug, Serialize, Deserialize)]
+pub struct CorrectedText {
+ /// The take's text with the user's wording.
+ pub text: String,
+ /// Unix time in milliseconds.
+ pub at_ms: u64,
+ /// How Voltip read it.
+ pub via: CorrectionVia,
+}
+
+/// How a correction was read (docs/dictation.md §35).
+#[derive(Clone, Copy, PartialEq, Eq, Debug, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CorrectionVia {
+ /// The user selected the corrected text and asked Voltip to learn from it (从选中文字学习).
+ Selection,
+ /// Read from the text field the take went to after the paste: the experimental field
+ /// tracking of a later version writes it. This version writes none, and loads it.
+ Follow,
+}
+
/// The other device of an entry: on a computer the phone it came from (`take`, `typed`,
/// `clipboard`, `standalone`), on a phone the computer it went to (`sent`).
#[derive(Clone, PartialEq, Eq, Debug, Serialize, Deserialize)]
diff --git a/crates/voltip-core/src/history/reader.rs b/crates/voltip-core/src/history/reader.rs
index 1d98eb3e..ae9af31b 100644
--- a/crates/voltip-core/src/history/reader.rs
+++ b/crates/voltip-core/src/history/reader.rs
@@ -110,6 +110,9 @@ pub struct HistoryText {
pub refined: bool,
/// The corrections and rules that fired (`HistoryEntry.vocabulary`; empty when none did).
pub vocabulary: VocabularyHits,
+ /// The whole take as the user corrected it in the application it went to
+ /// (`HistoryEntry.corrected`, docs/dictation.md §35); `None` when they did not teach it.
+ pub corrected: Option,
}
/// [`HistoryReader::search`]: which entries, and where the page starts (docs/dictation.md §25).
@@ -293,7 +296,7 @@ impl HistoryReader {
let texts = self.read(|conn| {
let mut stmt = conn.prepare(&format!(
"SELECT id, at_ms, json_extract(json, '$.raw_text'), json_extract(json, '$.text'), json_extract(json, '$.refined'), \
- json_extract(json, '$.vocabulary') FROM entries \
+ json_extract(json, '$.vocabulary'), json_extract(json, '$.corrected.text') FROM entries \
WHERE kind = 'dictation' AND COALESCE(json_extract(json, '$.origin.kind'), '') NOT IN ('typed', 'clipboard') \
AND json_extract(json, '$.file') IS NULL {NEWEST_FIRST} LIMIT ?1"
))?;
@@ -305,11 +308,12 @@ impl HistoryReader {
row.get::<_, Option>(3)?,
row.get::<_, Option>(4)?,
row.get::<_, Option>(5)?,
+ row.get::<_, Option>(6)?,
))
})?;
let mut out = Vec::new();
for row in rows {
- let (id, at_ms, raw_text, text, refined, vocabulary) = row?;
+ let (id, at_ms, raw_text, text, refined, vocabulary, corrected) = row?;
let Ok(id) = id.parse::() else { continue };
out.push(HistoryText {
id,
@@ -318,6 +322,7 @@ impl HistoryReader {
text: text.unwrap_or_default(),
refined: refined == Some(1),
vocabulary: vocabulary.and_then(|v| serde_json::from_str(&v).ok()).unwrap_or_default(),
+ corrected,
});
}
Ok(out)
diff --git a/crates/voltip-core/src/history/revs.rs b/crates/voltip-core/src/history/revs.rs
index c71e8afb..70129edc 100644
--- a/crates/voltip-core/src/history/revs.rs
+++ b/crates/voltip-core/src/history/revs.rs
@@ -287,6 +287,7 @@ fn shallow(entry: &HistoryEntry) -> HistoryEntry {
preset: None,
origin: None,
processed: None,
+ corrected: None,
file: None,
timing: entry.timing,
glossary_sent: entry.glossary_sent,
diff --git a/crates/voltip-core/src/history/store.rs b/crates/voltip-core/src/history/store.rs
index ebd7a98e..ca041c13 100644
--- a/crates/voltip-core/src/history/store.rs
+++ b/crates/voltip-core/src/history/store.rs
@@ -23,7 +23,7 @@ use sha2::{Digest, Sha256};
use uuid::Uuid;
use super::revs::{self, ChangeBatch, Outbox, RECEIVED_KEEP_MS};
-use super::{HISTORY_DB_FILE_NAME, HISTORY_FILE_NAME, HISTORY_SCHEMA, HistoryEntry, MAX_ENTRIES, ProcessedText, derived};
+use super::{CorrectedText, HISTORY_DB_FILE_NAME, HISTORY_FILE_NAME, HISTORY_SCHEMA, HistoryEntry, MAX_ENTRIES, ProcessedText, derived};
use crate::CoreError;
/// A database the import is still writing (step 2); deleted when found at start (step 1).
@@ -321,6 +321,22 @@ impl HistoryStore {
Ok(true)
}
+ /// Keep the user's correction of entry `id` (docs/dictation.md §35), replacing an earlier one,
+ /// or clear it (`None`); the search finds its text too. `Ok(false)` when the id is unknown.
+ pub fn set_corrected(&mut self, id: Uuid, corrected: Option) -> Result {
+ let conn = self.conn_mut()?;
+ let key = id.to_string();
+ let json: Option = conn.query_row("SELECT json FROM entries WHERE id = ?1", [&key], |row| row.get(0)).optional().map_err(err)?;
+ let Some(mut entry) = json.as_deref().and_then(decode) else { return Ok(false) };
+ entry.corrected = corrected.map(Box::new);
+ let json = serde_json::to_string(&entry).map_err(err)?;
+ let tx = conn.transaction().map_err(err)?;
+ tx.execute("UPDATE entries SET search = ?2, json = ?3 WHERE id = ?1", params![key, derived::search_text(&entry), json]).map_err(err)?;
+ revs::record(&tx, &key, false).map_err(err)?;
+ tx.commit().map_err(err)?;
+ Ok(true)
+ }
+
fn conn_mut(&mut self) -> Result<&mut Connection, CoreError> {
let path = &self.path;
self.conn.as_mut().map(Mutex::get_mut).ok_or_else(|| CoreError::History(format!("{} cannot be opened", path.display())))
diff --git a/crates/voltip-core/src/history/tests.rs b/crates/voltip-core/src/history/tests.rs
index 213c4907..e8fbca99 100644
--- a/crates/voltip-core/src/history/tests.rs
+++ b/crates/voltip-core/src/history/tests.rs
@@ -41,6 +41,7 @@ pub(super) fn entry(text: &str) -> HistoryEntry {
preset: None,
origin: None,
processed: None,
+ corrected: None,
file: None,
timing: None,
glossary_sent: None,
@@ -769,6 +770,49 @@ fn twenty_thousand_entries_open_search_and_count_in_time() {
assert!(counted < Duration::from_millis(100), "stats {counted:?}");
}
+/// 从选中文字学习 (docs/dictation.md §35): the user's correction is stored beside the entry's own
+/// text (which stays what was inserted), replaces an earlier one, is searched, read back by
+/// `recent_texts`, cleared with `None`, and absent from the JSON until it exists; an unknown id
+/// stores nothing.
+#[test]
+fn a_correction_is_stored_beside_the_entry_searched_and_read_with_the_recent_texts() {
+ let dir = tempfile::tempdir().unwrap();
+ let mut store = HistoryStore::open(dir.path());
+ let take = entry("我在用 Quinn for max 做测试");
+ store.push(take.clone(), MAX_ENTRIES).unwrap();
+ assert!(!serde_json::to_string(&take).unwrap().contains("corrected"));
+ let corrected = |text: &str, at_ms| CorrectedText { text: text.into(), at_ms, via: CorrectionVia::Selection };
+ assert!(store.set_corrected(take.id, Some(corrected("我在用 Qwen max 做测试", 1))).unwrap());
+ assert!(store.set_corrected(take.id, Some(corrected("我在用 Qwen 4 max 做测试", 2))).unwrap(), "replaces the earlier one");
+ assert!(!store.set_corrected(Uuid::new_v4(), Some(corrected("x", 3))).unwrap());
+ let stored = HistoryStore::open(dir.path()).get(take.id).unwrap().unwrap();
+ assert_eq!(stored.text, take.text, "the inserted text stays");
+ assert_eq!(stored.corrected, Some(Box::new(corrected("我在用 Qwen 4 max 做测试", 2))));
+ let json = serde_json::to_value(&stored).unwrap();
+ assert_eq!(json["corrected"], serde_json::json!({ "text": "我在用 Qwen 4 max 做测试", "at_ms": 2, "via": "selection" }));
+ let reader = HistoryReader::new(dir.path());
+ assert_eq!(reader.query(&page(HistoryQuery { query: "qwen 4".into(), ..Default::default() })).unwrap().entries.len(), 1);
+ assert_eq!(reader.recent_texts(10).unwrap()[0].corrected.as_deref(), Some("我在用 Qwen 4 max 做测试"));
+ assert!(store.set_corrected(take.id, None).unwrap());
+ assert_eq!(store.get(take.id).unwrap().unwrap().corrected, None);
+ assert_eq!(reader.recent_texts(10).unwrap()[0].corrected, None);
+ assert!(reader.query(&page(HistoryQuery { query: "qwen 4".into(), ..Default::default() })).unwrap().entries.is_empty(), "cleared: not searched");
+}
+
+/// Regression (goal review of PR #260, 2026-11-18): the stored correction's `via` is the wire the
+/// experimental field tracking (docs/dictation.md §35, a later version) writes too. With only
+/// `selection` known, an entry it corrected (`follow`) — synced from a phone's copy, or read after
+/// going back a version — would not load at all.
+#[test]
+fn regression_a_correction_read_in_the_field_loads() {
+ let mut json = serde_json::to_value(entry("我在用 Quinn for max 做测试")).unwrap();
+ json["corrected"] = serde_json::json!({ "text": "我在用 Qwen 4 max 做测试", "at_ms": 5, "via": "follow" });
+ let loaded: HistoryEntry = serde_json::from_value(json).unwrap();
+ assert_eq!(loaded.corrected.map(|c| c.via), Some(CorrectionVia::Follow));
+ assert_eq!(serde_json::to_value(CorrectionVia::Follow).unwrap(), "follow");
+ assert_eq!(serde_json::to_value(CorrectionVia::Selection).unwrap(), "selection");
+}
+
/// 用 AI 预设处理 (docs/dictation.md §22): the result is stored beside the entry's own text (the
/// text is untouched), replaces an earlier one, is found by the search, survives a reopen and is
/// omitted from the JSON until it exists; an unknown id stores nothing.
@@ -1174,7 +1218,13 @@ fn recent_texts_are_the_newest_recognised_takes() {
assert_eq!(
texts[0],
HistoryText {
- id: rows[5].id, at_ms: base + 5, raw_text: "最新".into(), text: "最新。".into(), refined: true, vocabulary: VocabularyHits::default()
+ id: rows[5].id,
+ at_ms: base + 5,
+ raw_text: "最新".into(),
+ text: "最新。".into(),
+ refined: true,
+ vocabulary: VocabularyHits::default(),
+ corrected: None
}
);
// Whether the polish made the text, and what fired: what the correction summary leaves out (§25).
diff --git a/crates/voltip-core/src/import/run.rs b/crates/voltip-core/src/import/run.rs
index 40fa8f63..a1b22476 100644
--- a/crates/voltip-core/src/import/run.rs
+++ b/crates/voltip-core/src/import/run.rs
@@ -297,6 +297,7 @@ pub async fn run(job: Job, mut partial: Partial, report: Report) -> Outcome {
preset: refined.then(|| TakePreset::default().to_ref()),
origin: None,
processed: None,
+ corrected: None,
file: Some(ImportedFile { name, duration_ms }),
timing: None,
// docs/dictation.md §30.6: as a long take's, when any segment's request carried it.
diff --git a/crates/voltip-core/src/lib.rs b/crates/voltip-core/src/lib.rs
index b8cafc84..9768c0a6 100644
--- a/crates/voltip-core/src/lib.rs
+++ b/crates/voltip-core/src/lib.rs
@@ -66,8 +66,8 @@ pub use providers::{
key_env_var, load_user_secrets, merge_credentials, peek_user_secrets, stored_credential_set,
};
pub use runtime::{
- AUTO_WEEKLY_DELAY, AppCore, CoreCommand, CoreConfig, CoreEvent, CoreHandle, EXTRA_RECORDING_POLL, MAX_ACTIVATION_MS, PRESET_TRY_UNCONFIGURED,
- SERVE_UNAVAILABLE, TestHooks, now_ms,
+ AUTO_WEEKLY_DELAY, AppCore, CoreCommand, CoreConfig, CoreEvent, CoreHandle, EXTRA_RECORDING_POLL, LEARN_NOTICE_DWELL, LearnNotice, LearnOutcome,
+ MAX_ACTIVATION_MS, NoticeAccepted, PRESET_TRY_UNCONFIGURED, SERVE_UNAVAILABLE, TestHooks, now_ms,
};
pub use scenes::{AppRef, BuiltinScene, ContextSharing, Scene, SceneDraft, SceneError, SceneMatch, SceneOverrides, SceneRef, TakeContext};
pub use settings::{
diff --git a/crates/voltip-core/src/mcp/candidates.rs b/crates/voltip-core/src/mcp/candidates.rs
index 80c80c69..b69a6258 100644
--- a/crates/voltip-core/src/mcp/candidates.rs
+++ b/crates/voltip-core/src/mcp/candidates.rs
@@ -15,7 +15,7 @@
//! trimmed from both ends; a pair that is only punctuation, or longer than a dictionary form may
//! be, is left out.
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
use serde::{Deserialize, Serialize};
use uuid::Uuid;
@@ -101,6 +101,12 @@ pub fn diff_tokens(text: &str) -> Vec<&str> {
/// `diffSegments`: the token-level LCS of `raw` → `text`, runs of one kind merged; ties go to the
/// deletion, as in `refine.ts`. `None` when the table would pass [`MAX_DIFF_CELLS`].
pub fn diff_segments(raw: &str, text: &str) -> Option> {
+ diff_segments_by(raw, text, |a, b| a == b)
+}
+
+/// [`diff_segments`] with `same` deciding which tokens are equal; a `Same` segment holds `raw`'s
+/// tokens.
+pub(crate) fn diff_segments_by(raw: &str, text: &str, same: impl Fn(&str, &str) -> bool) -> Option> {
let a = diff_tokens(raw);
let b = diff_tokens(text);
let width = b.len() + 1;
@@ -111,7 +117,7 @@ pub fn diff_segments(raw: &str, text: &str) -> Option> {
let mut table = vec![0u32; (a.len() + 1) * width];
for i in (0..a.len()).rev() {
for j in (0..b.len()).rev() {
- table[i * width + j] = if a[i] == b[j] { table[(i + 1) * width + j + 1] + 1 } else { table[(i + 1) * width + j].max(table[i * width + j + 1]) };
+ table[i * width + j] = if same(a[i], b[j]) { table[(i + 1) * width + j + 1] + 1 } else { table[(i + 1) * width + j].max(table[i * width + j + 1]) };
}
}
let mut out: Vec = Vec::new();
@@ -121,7 +127,7 @@ pub fn diff_segments(raw: &str, text: &str) -> Option> {
};
let (mut i, mut j) = (0, 0);
while i < a.len() && j < b.len() {
- if a[i] == b[j] {
+ if same(a[i], b[j]) {
push(SegmentKind::Same, a[i]);
i += 1;
j += 1;
@@ -169,8 +175,8 @@ fn trim_marks(text: &str) -> &str {
text.trim_matches(|c: char| c.is_whitespace() || js_space(c) || is_mark(c))
}
-/// A replacement inside one take: what was heard, what the final text has, and where the heard
-/// run starts in the recognised text (in characters).
+/// A replacement inside one take: what was heard, what the final text has, where the heard run
+/// starts in the recognised text, and where the two trimmed forms sit (all in characters).
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Replacement {
/// Trimmed recognised run.
@@ -181,6 +187,15 @@ pub struct Replacement {
pub at: usize,
/// Its length in characters.
pub len: usize,
+ /// Character offset of the trimmed `heard` in `raw`.
+ pub heard_at: usize,
+ /// Character offset of the trimmed `polished` in `text`.
+ pub polished_at: usize,
+}
+
+/// The characters [`trim_marks`] takes off the front of `text`.
+fn leading_marks(text: &str) -> usize {
+ text.chars().take_while(|&c| c.is_whitespace() || js_space(c) || is_mark(c)).count()
}
/// The replacements of one take: each deleted run directly followed by an added run, trimmed;
@@ -189,7 +204,7 @@ pub struct Replacement {
pub fn replacements(raw: &str, text: &str) -> Option> {
let segments = diff_segments(raw, text)?;
let mut out = Vec::new();
- let mut at = 0usize;
+ let (mut at, mut to) = (0usize, 0usize);
for (i, segment) in segments.iter().enumerate() {
let len = segment.text.chars().count();
if segment.kind == SegmentKind::Del
@@ -199,49 +214,308 @@ pub fn replacements(raw: &str, text: &str) -> Option> {
let (heard, polished) = (trim_marks(&segment.text), trim_marks(&next.text));
let fits = |s: &str| !s.is_empty() && s.chars().count() <= MAX_TERM_CHARS;
if fits(heard) && fits(polished) && heard != polished {
- out.push(Replacement { heard: heard.to_owned(), polished: polished.to_owned(), at, len });
+ out.push(Replacement {
+ heard: heard.to_owned(),
+ polished: polished.to_owned(),
+ at,
+ len,
+ heard_at: at + leading_marks(&segment.text),
+ polished_at: to + leading_marks(&next.text),
+ });
}
}
- if segment.kind != SegmentKind::Add {
- at += len;
+ match segment.kind {
+ SegmentKind::Same => {
+ at += len;
+ to += len;
+ }
+ SegmentKind::Del => at += len,
+ SegmentKind::Add => to += len,
}
}
Some(out)
}
-/// The replacements of `found` the AI clean-up made in `take`: those the take's own corrections and
-/// rules (`take.vocabulary`, in their order then, on even if turned off since) account for are left
-/// out — they turn the heard wording into the polished one, or make the same replacement at the
-/// same place when run over the whole recognised text. They are replayed as `dictionary` and
-/// `rules` define them now, so a take one of whose fired entries or rules was deleted or changed
-/// after it (`updated_at_ms` past the take's `at_ms`) gives no pairs at all.
-fn polish_only(found: Vec, take: &HistoryText, dictionary: &[DictionaryEntry], rules: &[ReplacementRule]) -> Vec {
- let fired = &take.vocabulary;
- if found.is_empty() || fired.is_empty() {
- return found;
+/// A take's own corrections and rules (`take.vocabulary`, in their order then, on even if turned
+/// off since) replayed over its recognised text as `dictionary` and `rules` define them now
+/// (docs/dictation.md §16.9): what they turn a wording into, and where they changed the
+/// recognised text. [`Replay::of`] is `None` when one of them was deleted or changed after the take
+/// (`updated_at_ms` past the take's `at_ms`): their changes can no longer be told apart.
+pub(crate) struct Replay {
+ /// The fired entries and rules; `None` when nothing fired.
+ vocabulary: Option,
+ /// Their replacements over the whole recognised text.
+ explained: Vec,
+}
+
+impl Replay {
+ /// The replay of `take`'s fired vocabulary, or `None` when it changed since the take.
+ pub(crate) fn of(take: &HistoryText, dictionary: &[DictionaryEntry], rules: &[ReplacementRule]) -> Option {
+ let fired = &take.vocabulary;
+ if fired.is_empty() {
+ return Some(Self { vocabulary: None, explained: Vec::new() });
+ }
+ let mut entries = Vec::with_capacity(fired.corrections.len());
+ for hit in &fired.corrections {
+ match dictionary.iter().find(|e| e.id == hit.id) {
+ Some(e) if e.updated_at_ms <= take.at_ms => entries.push(DictionaryEntry { enabled: true, ..e.clone() }),
+ _ => return None,
+ }
+ }
+ let mut firing = Vec::with_capacity(fired.rules.len());
+ for hit in &fired.rules {
+ match rules.iter().find(|r| r.id == hit.id) {
+ Some(r) if r.updated_at_ms <= take.at_ms => firing.push(ReplacementRule { enabled: true, pending: false, ..r.clone() }),
+ _ => return None,
+ }
+ }
+ let mut replay = Self { vocabulary: Some(Vocabulary::compile(&entries, &firing)), explained: Vec::new() };
+ replay.explained = replacements(&take.raw_text, &replay.run(&take.raw_text)).unwrap_or_default();
+ Some(replay)
}
- let mut entries = Vec::with_capacity(fired.corrections.len());
- for hit in &fired.corrections {
- match dictionary.iter().find(|e| e.id == hit.id) {
- Some(e) if e.updated_at_ms <= take.at_ms => entries.push(DictionaryEntry { enabled: true, ..e.clone() }),
- _ => return Vec::new(),
+
+ /// `text` through the fired corrections, then the fired rules.
+ pub(crate) fn run(&self, text: &str) -> String {
+ match &self.vocabulary {
+ None => text.to_owned(),
+ Some(vocabulary) => vocabulary.apply_rules(&vocabulary.correct(text).text).text,
}
}
- let mut firing = Vec::with_capacity(fired.rules.len());
- for hit in &fired.rules {
- match rules.iter().find(|r| r.id == hit.id) {
- Some(r) if r.updated_at_ms <= take.at_ms => firing.push(ReplacementRule { enabled: true, pending: false, ..r.clone() }),
- _ => return Vec::new(),
+
+ /// The fired vocabulary accounts for `r`: it turns the heard wording into the polished one, or
+ /// makes the same replacement at the same place.
+ fn explains(&self, r: &Replacement) -> bool {
+ self.run(&r.heard) == r.polished
+ || self.explained.iter().any(|q| q.heard == r.heard && q.polished == r.polished && q.at < r.at + r.len && r.at < q.at + q.len)
+ }
+
+ /// One of the fired vocabulary's replacements overlaps `len` characters at `at` of the
+ /// recognised text.
+ pub(crate) fn touches(&self, at: usize, len: usize) -> bool {
+ self.explained.iter().any(|q| q.at < at + len && at < q.at + q.len)
+ }
+}
+
+/// One pair of one take before the counting: the take (an index into the history), the two forms,
+/// where they sit (characters into the recognised text, and into the text the right form comes
+/// from), and whether the user's own correction made it (docs/dictation.md §35) rather than the AI
+/// clean-up.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct Found {
+ pub(crate) take: usize,
+ pub(crate) heard: String,
+ pub(crate) right: String,
+ pub(crate) heard_at: usize,
+ pub(crate) right_at: usize,
+ pub(crate) edit: bool,
+}
+
+/// What [`scan`] read.
+#[derive(Clone, Debug, Default)]
+pub(crate) struct Scan {
+ /// The pairs, take by take, newest first.
+ pub(crate) found: Vec,
+ /// Takes looked at.
+ pub(crate) scanned: u32,
+ /// Of those, the takes left out as too long to compare.
+ pub(crate) skipped: u32,
+ /// Of those, the takes the user corrected (`HistoryText::corrected`).
+ pub(crate) edited: u32,
+ /// The takes compared, as indices into the history.
+ pub(crate) compared: Vec,
+}
+
+/// The diff table of two texts, in cells.
+fn cells_of(a: &str, b: &str) -> usize {
+ (diff_tokens(a).len() + 1).saturating_mul(diff_tokens(b).len() + 1)
+}
+
+/// The pairs of `history` (newest first) at or after `since_ms`: the AI clean-up's
+/// ([`Replay::explains`] leaves out what the take's own corrections and rules did) and, with
+/// `edits`, the user's corrections (`crate::vocabulary::learn`). A take whose diff would pass
+/// [`MAX_DIFF_CELLS`] is skipped; past [`MAX_SCAN_CELLS`] in all, older takes are not read.
+pub(crate) fn scan(dictionary: &[DictionaryEntry], rules: &[ReplacementRule], history: &[HistoryText], since_ms: Option, edits: bool) -> Scan {
+ let mut out = Scan::default();
+ let mut cells = 0usize;
+ for (index, take) in history.iter().enumerate().filter(|(_, t)| since_ms.is_none_or(|since| t.at_ms >= since)) {
+ let corrected = if edits { take.corrected.as_deref() } else { None };
+ if !take.refined && corrected.is_none() {
+ // Not polished and not corrected: every change in it is a correction's or a rule's.
+ out.scanned = out.scanned.saturating_add(1);
+ continue;
+ }
+ let polish = take.refined.then(|| cells_of(&take.raw_text, &take.text));
+ let edit = corrected.map(|c| (cells_of(&take.text, c), cells_of(&take.raw_text, &take.text)));
+ if polish.is_some_and(|size| size > MAX_DIFF_CELLS) || edit.is_some_and(|(a, b)| a > MAX_DIFF_CELLS || b > MAX_DIFF_CELLS) {
+ out.scanned = out.scanned.saturating_add(1);
+ out.skipped = out.skipped.saturating_add(1);
+ // Read, if not compared: one of the corrected takes, as a skipped polished one is
+ // counted among the polished.
+ if corrected.is_some() {
+ out.edited = out.edited.saturating_add(1);
+ }
+ continue;
+ }
+ // A take whose corrections or rules fired is diffed once more for the replay (counted as
+ // the polish's diff again, as before the corrections were read).
+ let replay_cost = if take.vocabulary.is_empty() { 0 } else { polish.unwrap_or_else(|| cells_of(&take.raw_text, &take.raw_text)) };
+ let cost = polish.unwrap_or(0).saturating_add(edit.map_or(0, |(a, b)| a.saturating_add(b))).saturating_add(replay_cost);
+ if cells.saturating_add(cost) > MAX_SCAN_CELLS {
+ break;
+ }
+ cells += cost;
+ out.scanned = out.scanned.saturating_add(1);
+ out.compared.push(index);
+ if corrected.is_some() {
+ out.edited = out.edited.saturating_add(1);
+ }
+ let Some(replay) = Replay::of(take, dictionary, rules) else { continue };
+ if take.refined {
+ let Some(found) = replacements(&take.raw_text, &take.text) else {
+ out.skipped = out.skipped.saturating_add(1);
+ continue;
+ };
+ out.found.extend(found.into_iter().filter(|r| !replay.explains(r)).map(|r| Found {
+ take: index,
+ heard: r.heard,
+ right: r.polished,
+ heard_at: r.heard_at,
+ right_at: r.polished_at,
+ edit: false,
+ }));
+ }
+ if let Some(corrected) = corrected {
+ out.found.extend(crate::vocabulary::learn::edit_changes(take, corrected, &replay).into_iter().map(|c| Found {
+ take: index,
+ heard: c.heard,
+ right: c.right,
+ heard_at: c.heard_at,
+ right_at: c.right_at,
+ edit: true,
+ }));
}
}
- let vocabulary = Vocabulary::compile(&entries, &firing);
- let run = |text: &str| vocabulary.apply_rules(&vocabulary.correct(text).text).text;
- let explained = replacements(&take.raw_text, &run(&take.raw_text)).unwrap_or_default();
- found
- .into_iter()
- .filter(|r| {
- run(&r.heard) != r.polished
- && !explained.iter().any(|q| q.heard == r.heard && q.polished == r.polished && q.at < r.at + r.len && r.at < q.at + q.len)
+ out
+}
+
+/// A character of the scripts written without spaces whose single characters the dictionary's
+/// literal matcher finds inside any word (Han, kana, Hangul).
+pub(crate) fn is_cjk_letter(c: char) -> bool {
+ c.is_alphanumeric()
+ && matches!(
+ c as u32,
+ 0x1100..=0x11FF
+ | 0x3005..=0x3007
+ | 0x3040..=0x30FF
+ | 0x3130..=0x318F
+ | 0x31F0..=0x31FF
+ | 0x3400..=0x4DBF
+ | 0x4E00..=0x9FFF
+ | 0xA960..=0xA97F
+ | 0xAC00..=0xD7FF
+ | 0xF900..=0xFAFF
+ | 0xFF66..=0xFF9F
+ | 0xFFA0..=0xFFDC
+ | 0x20000..=0x3134F
+ )
+}
+
+/// `text` is one CJK character.
+fn single_cjk(text: &str) -> bool {
+ let mut chars = text.chars();
+ chars.next().is_some_and(is_cjk_letter) && chars.next().is_none()
+}
+
+/// A pair as it is counted: widened when it was a single character (docs/dictation.md §16.10).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct Counted {
+ pub(crate) found: Found,
+ /// The pair before it was widened, when it was.
+ pub(crate) single: Option<(String, String)>,
+ /// Characters of the (widened) heard form.
+ pub(crate) heard_len: usize,
+}
+
+/// A way to widen one pair: the forms with the neighbour, where the heard form starts.
+struct Widening {
+ heard: String,
+ right: String,
+ heard_at: usize,
+ right_at: usize,
+}
+
+/// The pairs of `scan` with every pair whose heard or right form is a single CJK character
+/// widened by the same unchanged neighbour on both sides (docs/dictation.md §16.10): 非 → 飞 in
+/// 「非书」 becomes 非书 → 飞书. With a neighbour on both sides, the side whose widened right form
+/// appears more often in the compared takes' final texts and corrections wins, the right one on a
+/// tie; with none, the pair stays as it is.
+pub(crate) fn widen(history: &[HistoryText], scan: &Scan) -> Vec {
+ let chars = |text: &str| text.chars().collect::>();
+ let mut texts: HashMap<(usize, bool), (Vec, Vec)> = HashMap::new();
+ let mut options: Vec> = Vec::with_capacity(scan.found.len());
+ for f in &scan.found {
+ if !single_cjk(&f.heard) && !single_cjk(&f.right) {
+ options.push(Vec::new());
+ continue;
+ }
+ let take = &history[f.take];
+ let (raw, right) = texts.entry((f.take, f.edit)).or_insert_with(|| {
+ let right = if f.edit { take.corrected.as_deref().unwrap_or(&take.text) } else { &take.text };
+ (chars(&take.raw_text), chars(right))
+ });
+ let (heard_len, right_len) = (f.heard.chars().count(), f.right.chars().count());
+ let mut found = Vec::new();
+ // Right first: it wins a tie.
+ if let (Some(&a), Some(&b)) = (raw.get(f.heard_at + heard_len), right.get(f.right_at + right_len))
+ && a == b
+ && is_cjk_letter(a)
+ {
+ found.push(Widening { heard: format!("{}{a}", f.heard), right: format!("{}{a}", f.right), heard_at: f.heard_at, right_at: f.right_at });
+ }
+ if f.heard_at > 0
+ && f.right_at > 0
+ && let (Some(&a), Some(&b)) = (raw.get(f.heard_at - 1), right.get(f.right_at - 1))
+ && a == b
+ && is_cjk_letter(a)
+ {
+ found.push(Widening { heard: format!("{a}{}", f.heard), right: format!("{a}{}", f.right), heard_at: f.heard_at - 1, right_at: f.right_at - 1 });
+ }
+ options.push(found);
+ }
+ let mut patterns: Vec = options.iter().filter(|o| o.len() > 1).flat_map(|o| o.iter().map(|w| w.right.clone())).collect();
+ patterns.sort();
+ patterns.dedup();
+ let mut counts: HashMap<&str, usize> = HashMap::new();
+ if !patterns.is_empty()
+ && let Ok(ac) = aho_corasick::AhoCorasick::new(&patterns)
+ {
+ for &index in &scan.compared {
+ let take = &history[index];
+ for text in std::iter::once(take.text.as_str()).chain(take.corrected.as_deref()) {
+ for m in ac.find_overlapping_iter(text) {
+ *counts.entry(patterns[m.pattern().as_usize()].as_str()).or_default() += 1;
+ }
+ }
+ }
+ }
+ scan.found
+ .iter()
+ .zip(options)
+ .map(|(f, found)| {
+ let count = |w: &Widening| counts.get(w.right.as_str()).copied().unwrap_or(0);
+ let chosen = match found.as_slice() {
+ [] => None,
+ [one] => Some(one),
+ [right, left, ..] => Some(if count(left) > count(right) { left } else { right }),
+ };
+ match chosen {
+ None => Counted { found: f.clone(), single: None, heard_len: f.heard.chars().count() },
+ Some(w) => Counted {
+ found: Found { heard: w.heard.clone(), right: w.right.clone(), heard_at: w.heard_at, right_at: w.right_at, ..f.clone() },
+ single: Some((f.heard.clone(), f.right.clone())),
+ heard_len: w.heard.chars().count(),
+ },
+ }
})
.collect()
}
@@ -266,10 +540,18 @@ pub struct Pair {
pub count: u32,
/// The newest take it happened in.
pub last_at_ms: u64,
- /// `heard` is already a form an enabled dictionary entry corrects (ignoring ASCII case).
+ /// `heard` is already a form an enabled dictionary entry corrects (ignoring ASCII case), or
+ /// its single character before the pair was widened is.
pub known: bool,
/// Up to [`MAX_EXAMPLES`] snippets, newest first.
pub examples: Vec,
+ /// Of `count`, the times the user's own correction made it (docs/dictation.md §35); never on
+ /// the MCP tool's wire, whose scan reads no corrections.
+ #[serde(skip)]
+ pub from_edits: u32,
+ /// The pair before it was widened (docs/dictation.md §16.10), when it was.
+ #[serde(skip)]
+ pub single: Option<(String, String)>,
}
/// What `vocabulary_candidates` answers.
@@ -292,67 +574,61 @@ fn snippet(raw: &str, at: usize, len: usize) -> String {
if start > 0 {
out.push('…');
}
- out.extend(&chars[start..end]);
+ out.extend(&chars[start.min(end)..end]);
if end < chars.len() {
out.push('…');
}
out
}
-/// Count the pairs of `history` (newest first) at or after `since_ms`, the `limit` most frequent:
-/// only those the AI clean-up made ([`polish_only`]; `rules` are the current rules).
-pub fn candidates(dictionary: &[DictionaryEntry], rules: &[ReplacementRule], history: &[HistoryText], since_ms: Option, limit: usize) -> Candidates {
+/// The widened pairs counted: one per form pair, with how often, how often from the user's
+/// corrections, the newest take, and up to [`MAX_EXAMPLES`] snippets (one per take, newest
+/// first); most frequent first, then the most recent.
+pub(crate) fn tally(dictionary: &[DictionaryEntry], history: &[HistoryText], counted: Vec) -> Vec {
let known: Vec<&str> = dictionary.iter().filter(|e| e.enabled).flat_map(|e| e.heard_as.iter().map(String::as_str)).collect();
- let mut out = Candidates::default();
+ let is_known = |heard: &str| known.iter().any(|k| k.eq_ignore_ascii_case(heard));
let mut index: HashMap<(String, String), usize> = HashMap::new();
let mut pairs: Vec = Vec::new();
- let mut cells = 0usize;
- for take in history.iter().filter(|t| since_ms.is_none_or(|since| t.at_ms >= since)) {
- if !take.refined {
- // Not polished: every change in it is a correction's or a rule's.
- out.scanned = out.scanned.saturating_add(1);
- continue;
- }
- let size = (diff_tokens(&take.raw_text).len() + 1).saturating_mul(diff_tokens(&take.text).len() + 1);
- if size > MAX_DIFF_CELLS {
- out.scanned = out.scanned.saturating_add(1);
- out.skipped = out.skipped.saturating_add(1);
+ // The user's corrections count each pair once per take (docs/dictation.md §16.10).
+ let mut corrected: HashSet<(usize, String, String)> = HashSet::new();
+ for Counted { found, single, heard_len } in counted {
+ let take = &history[found.take];
+ if found.edit && !corrected.insert((found.take, found.heard.clone(), found.right.clone())) {
continue;
}
- // A take whose corrections or rules fired is diffed a second time (`polish_only`).
- let cost = if take.vocabulary.is_empty() { size } else { size.saturating_mul(2) };
- if cells.saturating_add(cost) > MAX_SCAN_CELLS {
- break;
- }
- cells += cost;
- out.scanned = out.scanned.saturating_add(1);
- let Some(found) = replacements(&take.raw_text, &take.text) else {
- out.skipped = out.skipped.saturating_add(1);
- continue;
- };
- for r in polish_only(found, take, dictionary, rules) {
- let key = (r.heard.clone(), r.polished.clone());
- let slot = *index.entry(key).or_insert_with(|| {
- pairs.push(Pair {
- known: known.iter().any(|k| k.eq_ignore_ascii_case(&r.heard)),
- heard: r.heard.clone(),
- polished: r.polished.clone(),
- count: 0,
- last_at_ms: take.at_ms,
- examples: Vec::new(),
- });
- pairs.len() - 1
+ let key = (found.heard.clone(), found.right.clone());
+ let slot = *index.entry(key).or_insert_with(|| {
+ pairs.push(Pair {
+ known: is_known(&found.heard) || single.as_ref().is_some_and(|(h, _)| is_known(h)),
+ heard: found.heard.clone(),
+ polished: found.right.clone(),
+ count: 0,
+ last_at_ms: take.at_ms,
+ examples: Vec::new(),
+ from_edits: 0,
+ single: single.clone(),
});
- let pair = &mut pairs[slot];
- pair.count = pair.count.saturating_add(1);
- pair.last_at_ms = pair.last_at_ms.max(take.at_ms);
- if pair.examples.len() < MAX_EXAMPLES && !pair.examples.iter().any(|e| e.history_id == take.id) {
- pair.examples.push(PairExample { history_id: take.id, snippet: snippet(&take.raw_text, r.at, r.len) });
- }
+ pairs.len() - 1
+ });
+ let pair = &mut pairs[slot];
+ pair.count = pair.count.saturating_add(1);
+ if found.edit {
+ pair.from_edits = pair.from_edits.saturating_add(1);
+ }
+ pair.last_at_ms = pair.last_at_ms.max(take.at_ms);
+ if pair.examples.len() < MAX_EXAMPLES && !pair.examples.iter().any(|e| e.history_id == take.id) {
+ pair.examples.push(PairExample { history_id: take.id, snippet: snippet(&take.raw_text, found.heard_at, heard_len) });
}
}
pairs.sort_by(|a, b| b.count.cmp(&a.count).then(b.last_at_ms.cmp(&a.last_at_ms)));
+ pairs
+}
+
+/// Count the pairs of `history` (newest first) at or after `since_ms`, the `limit` most frequent:
+/// only those the AI clean-up made (`rules` are the current rules), single characters widened.
+pub fn candidates(dictionary: &[DictionaryEntry], rules: &[ReplacementRule], history: &[HistoryText], since_ms: Option, limit: usize) -> Candidates {
+ let read = scan(dictionary, rules, history, since_ms, false);
+ let mut pairs = tally(dictionary, history, widen(history, &read));
pairs.truncate(limit);
- out.pairs = pairs;
- out
+ Candidates { scanned: read.scanned, skipped: read.skipped, pairs }
}
diff --git a/crates/voltip-core/src/mcp/tests.rs b/crates/voltip-core/src/mcp/tests.rs
index fb33697a..4c7b2a71 100644
--- a/crates/voltip-core/src/mcp/tests.rs
+++ b/crates/voltip-core/src/mcp/tests.rs
@@ -51,7 +51,7 @@ fn rule(name: &str, source: EntrySource, pending: bool) -> ReplacementRule {
}
fn take(raw: &str, text: &str, at_ms: u64) -> HistoryText {
- HistoryText { id: Uuid::new_v4(), at_ms, raw_text: raw.into(), text: text.into(), refined: true, vocabulary: VocabularyHits::default() }
+ HistoryText { id: Uuid::new_v4(), at_ms, raw_text: raw.into(), text: text.into(), refined: true, vocabulary: VocabularyHits::default(), corrected: None }
}
#[test]
@@ -306,8 +306,9 @@ fn replacements_are_trimmed_pairs_without_punctuation_only_changes() {
#[test]
fn candidates_are_counted_known_and_sorted() {
let dictionary = vec![entry("Voltip", &["维他命"])];
- // The diff works on single CJK characters, as the history page's: 非书 → 飞书 is 非 → 飞, and
- // the snippets show the word around it.
+ // The diff works on single CJK characters, as the history page's; a pair of single characters
+ // is counted with its unchanged neighbour (docs/dictation.md §16.10): 非书 → 飞书, not 非 → 飞.
+ // The snippets show the word around it.
let history = vec![
take("我们用维他命开会", "我们用 Voltip 开会。", 50),
take("发到非书群", "发到飞书群。", 40),
@@ -318,7 +319,7 @@ fn candidates_are_counted_known_and_sorted() {
let out = candidates(&dictionary, &[], &history, None, 10);
assert_eq!((out.scanned, out.skipped), (5, 0));
let top: Vec<(&str, &str, u32, bool, u64)> = out.pairs.iter().map(|p| (p.heard.as_str(), p.polished.as_str(), p.count, p.known, p.last_at_ms)).collect();
- assert_eq!(top, [("非", "飞", 4, false, 40), ("维他命", "Voltip", 2, true, 50)], "every occurrence counts");
+ assert_eq!(top, [("非书", "飞书", 4, false, 40), ("维他命", "Voltip", 2, true, 50)], "every occurrence counts");
let examples = &out.pairs[0].examples;
assert_eq!(examples.iter().map(|e| e.history_id).collect::>(), [history[1].id, history[2].id, history[4].id], "one per take, newest first");
assert_eq!(examples[0].snippet, "发到非书群");
diff --git a/crates/voltip-core/src/runtime.rs b/crates/voltip-core/src/runtime.rs
index 6374f2c8..15d80c69 100644
--- a/crates/voltip-core/src/runtime.rs
+++ b/crates/voltip-core/src/runtime.rs
@@ -49,6 +49,8 @@ pub use auto_backup::AUTO_WEEKLY_DELAY;
mod backup;
mod check;
mod import;
+mod learn;
+pub use learn::{LEARN_NOTICE_DWELL, LearnNotice, LearnOutcome, NoticeAccepted};
mod listing;
mod mcp;
mod models_move;
@@ -130,6 +132,9 @@ pub struct CoreConfig {
/// 窗口已切换 and the failures on screen until they are closed. Off (the default; the phone,
/// the local speech service), every terminal state goes after its dwell.
pub result_cards: bool,
+ /// How long the pill's notice after a 从选中文字学习 stays once it shows, and again after each
+ /// of its buttons (docs/dictation.md §35): [`LEARN_NOTICE_DWELL`]; tests shorten it.
+ pub learn_notice_dwell: Duration,
/// Make the weekly automatic backup and show the automatic backups (docs/dictation.md
/// §4.6.1): the desktop yes, the phone and the local speech service no. The backups before an
/// update and before a replacing import are made wherever they are asked for.
@@ -247,6 +252,7 @@ impl CoreConfig {
accepts_phone_takes: true,
keeps_audio: true,
result_cards: false,
+ learn_notice_dwell: LEARN_NOTICE_DWELL,
auto_backup: false,
shows_live_preview: true,
builtin_scenes: true,
@@ -321,6 +327,9 @@ pub enum CoreCommand {
/// Choose (`Some`) or clear (`None`) the 复制上一条结果 hotkey (docs/dictation.md §28); validated
/// like the dictation hotkey and refused when it is the dictation's or the voice edit's chord.
SetCopyLastHotkey(Option),
+ /// 从选中文字学习 hotkey (docs/dictation.md §35): a chord, or `None` for none (the default);
+ /// never one of the other three chords.
+ SetLearnHotkey(Option),
/// Choose (`Some`) or switch off (`None`) the lone-key trigger (docs/dictation.md §13.1);
/// persisted, the desktop shell (un)installs its input hook on `Settings`.
SetSoloKey(Option),
@@ -412,6 +421,36 @@ pub enum CoreCommand {
/// 复制上一条结果 (docs/dictation.md §28): the newest result's text onto the clipboard, on a
/// blocking thread; `reply` gets what happened.
CopyLastResult(crate::last_result::CopyLastReply),
+ /// 从选中文字学习 (docs/dictation.md §35): copy the selection of the application in front and
+ /// learn from the takes it corrects; what came of it shows as `UiState.learn_notice`. Ignored
+ /// while a take is under way. `source` decides which modifiers the user may still hold.
+ LearnSelection {
+ /// The shortcut, or `voltip --learn-selection`.
+ source: EdgeSource,
+ },
+ /// The learn notice's 加入词典 (docs/dictation.md §35), for notice `id`.
+ LearnNoticeAccept {
+ /// `LearnNotice::id`.
+ id: u64,
+ },
+ /// The learn notice's 撤销.
+ LearnNoticeUndo {
+ /// `LearnNotice::id`.
+ id: u64,
+ },
+ /// The learn notice's ×.
+ LearnNoticeDismiss {
+ /// `LearnNotice::id`.
+ id: u64,
+ },
+ /// The learn notice's 查看 or 打开设置 (a page of the main window): the notice stays its
+ /// whole time again, as after its other buttons.
+ LearnNoticeKeep {
+ /// `LearnNotice::id`.
+ id: u64,
+ },
+ /// Forget the user's correction of a history entry (its detail's 移除, docs/dictation.md §35).
+ HistoryClearCorrected(Uuid),
/// A hotkey / CLI key transition (docs/dictation.md §13): the activation machine turns it into
/// start / stop / cancel / lock according to `Settings.activation`.
HotkeyEdge {
@@ -774,6 +813,7 @@ struct Inbox {
usage_rx: mpsc::Receiver,
import_rx: mpsc::Receiver,
auto_rx: mpsc::Receiver,
+ learn_rx: mpsc::Receiver,
}
/// Events to the UI.
@@ -870,6 +910,8 @@ pub enum CoreEvent {
/// The pairs the learning suggestions leave out (docs/dictation.md §16.10), oldest first; on
/// `Ready` and after every change.
VocabularyIgnored(Vec),
+ /// The pill's notice after a 从选中文字学习 changed or went (docs/dictation.md §35).
+ LearnNotice(Option),
/// Scenes in matching order (full replacement); on `Ready` and after every change.
Scenes(Vec),
/// Custom presets, full replacement (docs/dictation.md §21).
@@ -1059,6 +1101,7 @@ impl AppCore {
let (mcp, mcp_notice) = mcp::McpRuntime::new(config.mcp_host.clone(), &config.data_dir, mcp_tx);
let (imports, import_rx) = import::ImportRuntime::new(config.media_decoder.clone(), &config.data_dir);
let (auto, auto_rx) = auto_backup::AutoBackups::new(&config.data_dir, now_ms());
+ let (learn, learn_rx) = learn::LearnRuntime::new(&config.data_dir);
let mut rt = Runtime {
config,
manager,
@@ -1137,11 +1180,27 @@ impl AppCore {
last_result: None,
imports,
auto,
+ learn,
};
rt.system_fingerprint = rt.config.network.system_fingerprint();
rt.connect_relay()?;
- let inbox =
- Inbox { cmd_rx, link_rx, dict_rx, model_rx, act_rx, phone_rx, check_rx, process_rx, listed_rx, mcp_rx, recover_rx, usage_rx, import_rx, auto_rx };
+ let inbox = Inbox {
+ cmd_rx,
+ link_rx,
+ dict_rx,
+ model_rx,
+ act_rx,
+ phone_rx,
+ check_rx,
+ process_rx,
+ listed_rx,
+ mcp_rx,
+ recover_rx,
+ usage_rx,
+ import_rx,
+ auto_rx,
+ learn_rx,
+ };
Ok((rt, inbox, CoreHandle { cmd: cmd_tx, levels: levels_tx }, evt_rx))
}
}
@@ -1453,6 +1512,8 @@ struct Runtime {
last_result: Option,
/// The import queue (docs/dictation.md §31).
imports: import::ImportRuntime,
+ /// 从选中文字学习 and its notice (docs/dictation.md §35).
+ learn: learn::LearnRuntime,
/// The automatic backups (docs/dictation.md §4.6.1).
auto: auto_backup::AutoBackups,
}
@@ -1581,6 +1642,7 @@ impl Runtime {
mut usage_rx,
mut import_rx,
mut auto_rx,
+ mut learn_rx,
} = inbox;
self.emit(CoreEvent::Ready {
identity: self.identity.public(),
@@ -1639,6 +1701,7 @@ impl Runtime {
Some(inbound) = usage_rx.recv() => self.on_usage(inbound),
Some(inbound) = import_rx.recv() => self.on_import(inbound),
Some(inbound) = auto_rx.recv() => self.on_auto_backup(inbound, now_ms()),
+ Some(inbound) = learn_rx.recv() => self.on_learn(inbound),
Ok(()) = quota_rx.changed() => self.emit(CoreEvent::Engines(self.engine_status())),
_ = ticker.tick() => self.tick().await,
}
@@ -1694,6 +1757,7 @@ impl Runtime {
CoreCommand::SetHotkey(text) => self.set_hotkey(&text),
CoreCommand::SetEditHotkey(text) => self.set_edit_hotkey(text.as_deref()),
CoreCommand::SetCopyLastHotkey(text) => self.set_copy_last_hotkey(text.as_deref()),
+ CoreCommand::SetLearnHotkey(text) => self.set_learn_hotkey(text.as_deref()),
CoreCommand::SetSoloKey(key) => self.set_solo_key(key),
CoreCommand::SetMicrophone(device) => self.set_microphone(device),
CoreCommand::SetRecording(recording) => self.set_recording(recording),
@@ -1751,6 +1815,27 @@ impl Runtime {
self.copy_last_result(reply);
Ok(())
}
+ CoreCommand::LearnSelection { source } => {
+ self.learn_selection(source);
+ Ok(())
+ }
+ CoreCommand::LearnNoticeAccept { id } => {
+ self.learn_notice_accept(id);
+ Ok(())
+ }
+ CoreCommand::LearnNoticeUndo { id } => {
+ self.learn_notice_undo(id);
+ Ok(())
+ }
+ CoreCommand::LearnNoticeDismiss { id } => {
+ self.learn_notice_dismiss(id);
+ Ok(())
+ }
+ CoreCommand::LearnNoticeKeep { id } => {
+ self.learn_notice_keep(id);
+ Ok(())
+ }
+ CoreCommand::HistoryClearCorrected(id) => self.clear_correction(id),
CoreCommand::HotkeyEdge { pressed, at_ms, source, purpose, chorded } => self.hotkey_edge(Edge { pressed, at_ms, source }, purpose, chorded),
CoreCommand::SetActivation { activation, hold_threshold_ms, extra_recording_ms } => {
self.set_activation(activation, hold_threshold_ms, extra_recording_ms)
@@ -2896,7 +2981,10 @@ impl Runtime {
self.last_result = Some(text.to_owned());
}
self.follow_refine_notice(&status.phase);
+ let phase = status.phase.clone();
self.emit(CoreEvent::Dictation(status));
+ // docs/dictation.md §35: after the phase, so the pill sees it idle first.
+ self.follow_learn_notice(&phase);
// A phone's text waits for the take to end (docs/dictation.md §20.6).
if hint == PhaseHint::Idle {
self.deliver_next_text();
@@ -3233,6 +3321,9 @@ impl Runtime {
if self.copy_last_chord_is(&hotkey) {
return Err(CoreError::Invalid(format!("hotkey: {} 已用作「复制上一条结果」的快捷键", hotkey.display())));
}
+ if self.learn_chord_is(&hotkey) {
+ return Err(CoreError::Invalid(format!("hotkey: {} 已用作「从选中文字学习」的快捷键", hotkey.display())));
+ }
self.settings.hotkey = hotkey.display();
self.save_settings()
}
@@ -3242,6 +3333,36 @@ impl Runtime {
self.settings.copy_last_hotkey.as_deref().is_some_and(|copy| crate::Hotkey::same_chord(&hotkey.display(), copy))
}
+ /// `hotkey` is the 从选中文字学习 chord (docs/dictation.md §35).
+ fn learn_chord_is(&self, hotkey: &crate::Hotkey) -> bool {
+ self.settings.learn_hotkey.as_deref().is_some_and(|learn| crate::Hotkey::same_chord(&hotkey.display(), learn))
+ }
+
+ /// `SetLearnHotkey` (docs/dictation.md §35): `None` assigns none; a chord is validated like the
+ /// dictation hotkey and refused when it is the dictation's, the voice edit's or 复制上一条结果's.
+ fn set_learn_hotkey(&mut self, text: Option<&str>) -> Result<(), CoreError> {
+ let chord = match text {
+ None => None,
+ Some(text) => {
+ let hotkey = crate::Hotkey::parse(text)?;
+ if crate::Hotkey::same_chord(&hotkey.display(), &self.settings.hotkey) {
+ return Err(CoreError::Invalid(format!("learn_hotkey: {} 已用作听写快捷键", hotkey.display())));
+ }
+ if let Some(edit) = self.settings.edit_hotkey.as_deref()
+ && crate::Hotkey::same_chord(&hotkey.display(), edit)
+ {
+ return Err(CoreError::Invalid(format!("learn_hotkey: {} 已用作「编辑选中文本」的快捷键", hotkey.display())));
+ }
+ if self.copy_last_chord_is(&hotkey) {
+ return Err(CoreError::Invalid(format!("learn_hotkey: {} 已用作「复制上一条结果」的快捷键", hotkey.display())));
+ }
+ Some(hotkey.display())
+ }
+ };
+ self.settings.learn_hotkey = chord;
+ self.save_settings()
+ }
+
/// `SetCopyLastHotkey` (docs/dictation.md §28): `None` assigns none; a chord is validated like
/// the dictation hotkey and refused when it is the dictation's or the voice edit's.
fn set_copy_last_hotkey(&mut self, text: Option<&str>) -> Result<(), CoreError> {
@@ -3257,6 +3378,9 @@ impl Runtime {
{
return Err(CoreError::Invalid(format!("copy_last_hotkey: {} 已用作「编辑选中文本」的快捷键", hotkey.display())));
}
+ if self.learn_chord_is(&hotkey) {
+ return Err(CoreError::Invalid(format!("copy_last_hotkey: {} 已用作「从选中文字学习」的快捷键", hotkey.display())));
+ }
Some(hotkey.display())
}
};
@@ -3303,6 +3427,9 @@ impl Runtime {
if self.copy_last_chord_is(&hotkey) {
return Err(CoreError::Invalid(format!("edit_hotkey: {} 已用作「复制上一条结果」的快捷键", hotkey.display())));
}
+ if self.learn_chord_is(&hotkey) {
+ return Err(CoreError::Invalid(format!("edit_hotkey: {} 已用作「从选中文字学习」的快捷键", hotkey.display())));
+ }
Some(hotkey.display())
}
};
diff --git a/crates/voltip-core/src/runtime/learn.rs b/crates/voltip-core/src/runtime/learn.rs
new file mode 100644
index 00000000..812a5dd4
--- /dev/null
+++ b/crates/voltip-core/src/runtime/learn.rs
@@ -0,0 +1,420 @@
+//! 从选中文字学习 (`CoreCommand::LearnSelection`, docs/dictation.md §35): the user corrected a take
+//! in the application it went to, selected the corrected text and pressed the shortcut (or ran
+//! `voltip --learn-selection`). On a task: the probe names the application in front (a terminal's
+//! selection is program output: no key is pressed), the copy chord reads the selection (§19.2, the
+//! clipboard put back afterwards), and the newest [`LEARN_TAKES`] recognised takes are compared with
+//! it (`crate::vocabulary::learn`). Back here the corrections are stored with their entries; then
+//! the learning suggestions are counted over the history once more for the pairs the corrected
+//! takes give, and the notice ([`LearnNotice`], `UiState.learn_notice`) offers them on the pill.
+//!
+//! The notice is shown while no take uses the pill: one that comes while a take's result is still
+//! on it waits, without a timer, until the pill is idle again; then it stays
+//! [`LEARN_NOTICE_DWELL`], again after each of its buttons; a new take clears it. With the pill off
+//! there is no notice: the outcome is logged and the pairs wait in the learning suggestions.
+//! Nothing here logs a text.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use serde::{Deserialize, Serialize};
+use tokio::sync::mpsc;
+use uuid::Uuid;
+
+use super::{CoreEvent, Runtime, now_ms};
+use crate::dictation::activation::EdgeSource;
+use crate::dictation::{DictationPhase, ForegroundApp};
+use crate::history::{CorrectedText, CorrectionVia, HistoryReader, MAX_RECENT_TEXTS};
+use crate::settings::OverlayPlacement;
+use crate::vocabulary::learn::{LEARN_TAKES, MAX_LEARN_SELECTION_CHARS, match_selection, storable};
+use crate::vocabulary::{BatchItem, BatchUndoOutcome, SuggestionPick, edit_picks};
+
+/// How long the notice stays on the pill, counted from when it shows and again after each button.
+pub const LEARN_NOTICE_DWELL: Duration = Duration::from_secs(8);
+
+/// What came of one 从选中文字学习 (docs/dictation.md §35).
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum LearnOutcome {
+ /// The corrections give these pairs; `safe`: none has a short heard form (one character, or one
+ /// or two Latin letters), so the notice may offer 加入词典 at once.
+ Learned {
+ /// The pairs, in the order the takes come.
+ pairs: Vec,
+ /// No pair is short enough to change other words.
+ safe: bool,
+ },
+ /// The selection corrects takes, but no change is one to put in the dictionary (only
+ /// punctuation, new or deleted words, what the clean-up, the dictionary or a rule wrote, or a
+ /// pair known or ignored already).
+ NoPairs,
+ /// The selection is what was inserted (or what it was put back to).
+ Unchanged,
+ /// None of the newest takes is like the selection.
+ NoMatch,
+ /// Nothing was selected (or the application did not copy).
+ NoSelection,
+ /// The selection is longer than `max` characters.
+ TooLong {
+ /// [`MAX_LEARN_SELECTION_CHARS`].
+ max: u32,
+ },
+ /// A terminal is in front: its selection is program output, so nothing was copied.
+ Terminal,
+ /// The history is off: there is nothing to compare with, and nothing would be kept.
+ HistoryOff,
+ /// The selection could not be read, or the history could not be read or written.
+ Failed {
+ /// Why (no text of the user's).
+ message: String,
+ },
+}
+
+/// What 加入词典 on the notice did.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct NoticeAccepted {
+ /// Pairs that went into the dictionary.
+ pub added: u32,
+ /// Pairs the dictionary or a rule refused (the dictionary page says why).
+ pub refused: u32,
+ /// The batch 撤销 takes back, when anything went in.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub undo: Option,
+}
+
+/// The pill's notice after a 从选中文字学习 (`UiState.learn_notice`, docs/dictation.md §35).
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct LearnNotice {
+ /// Which notice: the buttons name it, and a newer one replaces it.
+ pub id: u64,
+ /// What came of it.
+ pub outcome: LearnOutcome,
+ /// On the pill now; a notice that waits behind a take's result is not (yet).
+ pub shown: bool,
+ /// 加入词典 ran.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub accepted: Option,
+ /// 撤销 ran.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub undone: Option,
+}
+
+/// A heard form short enough to change other words (the dictionary page's warning, `shortForm`
+/// in `packages/shared/src/quick-fix.ts`): one character, or one or two Latin letters.
+fn short_form(heard: &str) -> bool {
+ let form = heard.trim();
+ let n = form.chars().count();
+ n == 1 || (n <= 2 && !form.is_empty() && form.chars().all(|c| c.is_ascii_alphabetic()))
+}
+
+/// One take a selection corrects, as the task found it.
+#[derive(Debug)]
+pub(super) struct Correction {
+ id: Uuid,
+ /// The whole corrected text to keep, or `None` to clear an earlier one.
+ keep: Option,
+ /// The take had a correction before.
+ had: bool,
+ /// The selection is what was inserted.
+ unchanged: bool,
+}
+
+/// What the tasks send back.
+#[derive(Debug)]
+pub(super) enum LearnInbound {
+ /// The selection was read and compared, or the attempt ended early.
+ Compared { request: u64, result: Result, LearnOutcome> },
+ /// The pairs of the corrected takes are counted.
+ Counted { request: u64, picks: Result, String> },
+ /// A notice's time is up.
+ Expired { id: u64, generation: u64 },
+}
+
+/// The runtime's part of 从选中文字学习.
+pub(super) struct LearnRuntime {
+ tx: mpsc::Sender,
+ reader: Arc,
+ /// The newest request; answers to older ones are dropped.
+ request: u64,
+ notice: Option,
+ next_id: u64,
+ /// Restarts of the notice's timer; an older timer's expiry is dropped.
+ generation: u64,
+}
+
+impl LearnRuntime {
+ pub(super) fn new(data_dir: &std::path::Path) -> (Self, mpsc::Receiver) {
+ let (tx, rx) = mpsc::channel(8);
+ (Self { tx, reader: Arc::new(HistoryReader::new(data_dir)), request: 0, notice: None, next_id: 0, generation: 0 }, rx)
+ }
+}
+
+/// A take is under way: not idle and not yet finished.
+fn take_running(phase: &DictationPhase) -> bool {
+ !matches!(phase, DictationPhase::Idle) && !phase.is_terminal()
+}
+
+impl Runtime {
+ /// `LearnSelection`: read the selection and learn from it, unless a take is under way (the key
+ /// belongs to it then) or the history is off.
+ pub(super) fn learn_selection(&mut self, source: EdgeSource) {
+ if take_running(&self.dictation.status().phase) {
+ tracing::info!("learn selection ignored: a take is under way");
+ return;
+ }
+ self.learn.request += 1;
+ let request = self.learn.request;
+ if !self.settings.history.enabled {
+ tracing::info!(request, "learn selection: the history is off");
+ self.show_learned(LearnOutcome::HistoryOff);
+ return;
+ }
+ // The user may still hold the shortcut's modifiers when the copy chord goes out (§19.2).
+ let held = match source {
+ EdgeSource::Cli => Vec::new(),
+ EdgeSource::Hotkey | EdgeSource::Ui => {
+ self.settings.learn_hotkey.as_deref().and_then(|h| crate::Hotkey::parse(h).ok()).map(|h| h.modifiers).unwrap_or_default()
+ }
+ };
+ let (probe, injector, reader, tx) = (self.dictation.probe(), self.dictation.injector(), self.learn.reader.clone(), self.learn.tx.clone());
+ tokio::spawn(async move {
+ let result = read_and_compare(probe, injector, reader, held).await;
+ let _ = tx.send(LearnInbound::Compared { request, result }).await;
+ });
+ }
+
+ /// An answer from a task, or a notice's timer.
+ pub(super) fn on_learn(&mut self, inbound: LearnInbound) {
+ match inbound {
+ LearnInbound::Compared { request, result } if request == self.learn.request => match result {
+ Err(outcome) => self.show_learned(outcome),
+ Ok(corrections) => self.keep_corrections(request, corrections),
+ },
+ LearnInbound::Counted { request, picks } if request == self.learn.request => match picks {
+ Ok(picks) if picks.is_empty() => self.show_learned(LearnOutcome::NoPairs),
+ Ok(pairs) => {
+ let safe = !pairs.iter().any(|p| short_form(&p.heard));
+ self.show_learned(LearnOutcome::Learned { pairs, safe });
+ }
+ Err(message) => self.show_learned(LearnOutcome::Failed { message }),
+ },
+ LearnInbound::Expired { id, generation } => {
+ if self.learn.notice.as_ref().is_some_and(|n| n.id == id) && generation == self.learn.generation {
+ self.set_learn_notice(None);
+ }
+ }
+ LearnInbound::Compared { .. } | LearnInbound::Counted { .. } => tracing::debug!("an older learn selection answered; dropped"),
+ }
+ }
+
+ /// Store what the selection corrects, then count the pairs those takes give.
+ fn keep_corrections(&mut self, request: u64, corrections: Vec) {
+ if corrections.is_empty() {
+ self.show_learned(LearnOutcome::NoMatch);
+ return;
+ }
+ let mut written = false;
+ let mut kept: Vec = Vec::new();
+ for c in &corrections {
+ let result = match &c.keep {
+ Some(text) => {
+ kept.push(c.id);
+ self.history.set_corrected(c.id, Some(CorrectedText { text: text.clone(), at_ms: now_ms(), via: CorrectionVia::Selection }))
+ }
+ None if c.had => self.history.set_corrected(c.id, None),
+ None => Ok(false),
+ };
+ match result {
+ Ok(changed) => written |= changed,
+ Err(e) => {
+ tracing::warn!(error = %e, "learn selection: the correction could not be stored");
+ self.show_learned(LearnOutcome::Failed { message: e.to_string() });
+ return;
+ }
+ }
+ }
+ if written {
+ self.emit_history();
+ }
+ tracing::info!(request, takes = corrections.len(), kept = kept.len(), "learn selection: compared");
+ if kept.is_empty() {
+ let unchanged = corrections.iter().all(|c| c.unchanged);
+ self.show_learned(if unchanged { LearnOutcome::Unchanged } else { LearnOutcome::NoPairs });
+ return;
+ }
+ let (dictionary, rules, ignored) = (self.dictionary.entries().to_vec(), self.rules.rules().to_vec(), self.ignored.list().to_vec());
+ let (reader, tx) = (self.learn.reader.clone(), self.learn.tx.clone());
+ tokio::spawn(async move {
+ let picks = tokio::task::spawn_blocking(move || {
+ let history = reader.recent_texts(MAX_RECENT_TEXTS).map_err(|e| e.to_string())?;
+ Ok(edit_picks(&dictionary, &rules, &history, &ignored, &kept))
+ })
+ .await
+ .unwrap_or_else(|e| Err(format!("learn task failed: {e}")));
+ let _ = tx.send(LearnInbound::Counted { request, picks }).await;
+ });
+ }
+
+ /// Put `outcome` on the pill as a new notice (none with the pill off), waiting while a take's
+ /// result is still there.
+ fn show_learned(&mut self, outcome: LearnOutcome) {
+ tracing::info!(outcome = learned_name(&outcome), "learn selection");
+ // No pill to show it on, or a take began meanwhile and has the pill: the pairs wait in the
+ // learning suggestions.
+ if self.settings.overlay == OverlayPlacement::Off || take_running(&self.dictation.status().phase) {
+ return;
+ }
+ self.learn.next_id += 1;
+ let shown = matches!(self.dictation.status().phase, DictationPhase::Idle);
+ self.set_learn_notice(Some(LearnNotice { id: self.learn.next_id, outcome, shown, accepted: None, undone: None }));
+ }
+
+ /// Replace the notice, restart its timer when it is on the pill, and tell the UI.
+ fn set_learn_notice(&mut self, notice: Option) {
+ self.learn.generation += 1;
+ if let Some(n) = notice.as_ref().filter(|n| n.shown) {
+ let (id, generation, tx, dwell) = (n.id, self.learn.generation, self.learn.tx.clone(), self.config.learn_notice_dwell);
+ tokio::spawn(async move {
+ tokio::time::sleep(dwell).await;
+ let _ = tx.send(LearnInbound::Expired { id, generation }).await;
+ });
+ }
+ self.learn.notice = notice;
+ self.emit(CoreEvent::LearnNotice(self.learn.notice.clone()));
+ }
+
+ /// The dictation phase moved (docs/dictation.md §35): a take that starts clears the notice; a
+ /// pill that is idle again shows a waiting one.
+ pub(super) fn follow_learn_notice(&mut self, phase: &DictationPhase) {
+ let Some(notice) = self.learn.notice.clone() else { return };
+ if take_running(phase) {
+ self.set_learn_notice(None);
+ } else if !notice.shown && matches!(phase, DictationPhase::Idle) {
+ self.set_learn_notice(Some(LearnNotice { shown: true, ..notice }));
+ }
+ }
+
+ /// The notice's 加入词典: its pairs through the batch accept of the learning suggestions.
+ pub(super) fn learn_notice_accept(&mut self, id: u64) {
+ let Some(notice) = self.learn.notice.clone().filter(|n| n.id == id && n.accepted.is_none()) else { return };
+ let LearnOutcome::Learned { pairs, safe: true } = ¬ice.outcome else {
+ tracing::info!(id, "learn notice: nothing to add at once");
+ return;
+ };
+ let outcome = self.accept_suggestions(pairs);
+ let added = outcome.items.iter().filter(|i| matches!(i, BatchItem::Accepted { .. })).count();
+ let accepted = NoticeAccepted {
+ added: u32::try_from(added).unwrap_or(u32::MAX),
+ refused: u32::try_from(outcome.items.len() - added).unwrap_or(u32::MAX),
+ undo: outcome.undo,
+ };
+ self.set_learn_notice(Some(LearnNotice { accepted: Some(accepted), ..notice }));
+ }
+
+ /// The notice's 撤销: the batch its 加入词典 made, taken back.
+ pub(super) fn learn_notice_undo(&mut self, id: u64) {
+ let Some(notice) = self.learn.notice.clone().filter(|n| n.id == id && n.undone.is_none()) else { return };
+ let Some(batch) = notice.accepted.as_ref().and_then(|a| a.undo) else { return };
+ let outcome = self.undo_suggestions(batch);
+ self.set_learn_notice(Some(LearnNotice { undone: Some(outcome), ..notice }));
+ }
+
+ /// The notice's 查看 or 打开设置: shown, it stays its whole time again (D3).
+ pub(super) fn learn_notice_keep(&mut self, id: u64) {
+ if let Some(notice) = self.learn.notice.clone().filter(|n| n.id == id && n.shown) {
+ self.set_learn_notice(Some(notice));
+ }
+ }
+
+ /// The notice's ×.
+ pub(super) fn learn_notice_dismiss(&mut self, id: u64) {
+ if self.learn.notice.as_ref().is_some_and(|n| n.id == id) {
+ self.set_learn_notice(None);
+ }
+ }
+
+ /// The history detail's 移除: forget the user's correction of entry `id`.
+ pub(super) fn clear_correction(&mut self, id: Uuid) -> Result<(), crate::CoreError> {
+ if self.history.set_corrected(id, None)? {
+ self.emit_history();
+ }
+ Ok(())
+ }
+}
+
+/// The outcome's name for the log.
+fn learned_name(outcome: &LearnOutcome) -> &'static str {
+ match outcome {
+ LearnOutcome::Learned { .. } => "learned",
+ LearnOutcome::NoPairs => "no_pairs",
+ LearnOutcome::Unchanged => "unchanged",
+ LearnOutcome::NoMatch => "no_match",
+ LearnOutcome::NoSelection => "no_selection",
+ LearnOutcome::TooLong { .. } => "too_long",
+ LearnOutcome::Terminal => "terminal",
+ LearnOutcome::HistoryOff => "history_off",
+ LearnOutcome::Failed { .. } => "failed",
+ }
+}
+
+/// The task: the application in front, the selection, the takes it corrects.
+async fn read_and_compare(
+ probe: Option>,
+ injector: Arc,
+ reader: Arc,
+ held: Vec,
+) -> Result, LearnOutcome> {
+ // §19.2: no key is pressed before the probe said which application is in front; a terminal's
+ // selection is program output. No answer (pure Wayland, a slow probe): copied anyway.
+ if let Some(probe) = probe {
+ let deadline = probe.deadline();
+ let app = match tokio::time::timeout(deadline, tokio::task::spawn_blocking(move || probe.foreground())).await {
+ Ok(Ok(Ok(app))) => app.and_then(ForegroundApp::sanitized),
+ _ => None,
+ };
+ if let Some(app) = app
+ && injector.holds_program_output(&app.app_id)
+ {
+ tracing::info!(app = %app.app_id, "learn selection refused: a terminal is in front");
+ return Err(LearnOutcome::Terminal);
+ }
+ }
+ let copied = tokio::task::spawn_blocking(move || injector.copy_selection(&held)).await;
+ let selection = match copied {
+ Ok(Ok(Some(text))) if !text.trim().is_empty() => text,
+ Ok(Ok(_)) => return Err(LearnOutcome::NoSelection),
+ Ok(Err(e)) => return Err(LearnOutcome::Failed { message: e.to_string() }),
+ Err(e) => return Err(LearnOutcome::Failed { message: format!("copy task failed: {e}") }),
+ };
+ if selection.chars().count() > MAX_LEARN_SELECTION_CHARS {
+ return Err(LearnOutcome::TooLong { max: u32::try_from(MAX_LEARN_SELECTION_CHARS).unwrap_or(u32::MAX) });
+ }
+ tracing::debug!(chars = selection.chars().count(), "learn selection: copied");
+ tokio::task::spawn_blocking(move || {
+ let takes = reader.recent_texts(LEARN_TAKES).map_err(|e| LearnOutcome::Failed { message: e.to_string() })?;
+ Ok(match_selection(&selection, &takes)
+ .into_iter()
+ .map(|m| {
+ let take = &takes[m.index];
+ let keep = storable(take, &m.corrected).then_some(m.corrected.clone());
+ Correction { id: take.id, keep, had: take.corrected.is_some(), unchanged: m.corrected == take.text }
+ })
+ .collect())
+ })
+ .await
+ .unwrap_or_else(|e| Err(LearnOutcome::Failed { message: format!("learn task failed: {e}") }))
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn short_forms_are_the_dictionary_pages() {
+ for short in ["非", "a", "ab", " AB "] {
+ assert!(short_form(short), "{short}");
+ }
+ for long in ["非书", "abc", "a1", "Quinn for"] {
+ assert!(!short_form(long), "{long}");
+ }
+ }
+}
diff --git a/crates/voltip-core/src/runtime/takes.rs b/crates/voltip-core/src/runtime/takes.rs
index e04846ef..fbe15db6 100644
--- a/crates/voltip-core/src/runtime/takes.rs
+++ b/crates/voltip-core/src/runtime/takes.rs
@@ -545,6 +545,7 @@ impl Runtime {
preset: None,
origin: Some(EntryOrigin { device: computer, kind: OriginKind::Sent }),
processed: None,
+ corrected: None,
file: None,
timing: None,
glossary_sent: None,
diff --git a/crates/voltip-core/src/runtime/texts.rs b/crates/voltip-core/src/runtime/texts.rs
index f824b200..c2476245 100644
--- a/crates/voltip-core/src/runtime/texts.rs
+++ b/crates/voltip-core/src/runtime/texts.rs
@@ -166,6 +166,7 @@ impl Runtime {
preset: None,
origin: Some(EntryOrigin { device: text.name, kind: origin_kind(text.source) }),
processed: None,
+ corrected: None,
file: None,
timing: None,
glossary_sent: None,
diff --git a/crates/voltip-core/src/settings.rs b/crates/voltip-core/src/settings.rs
index aceb58c3..ed4e0abb 100644
--- a/crates/voltip-core/src/settings.rs
+++ b/crates/voltip-core/src/settings.rs
@@ -261,6 +261,10 @@ pub struct Settings {
/// files written before it) assigns none.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub copy_last_hotkey: Option,
+ /// The 从选中文字学习 hotkey (docs/dictation.md §35) in display form; `None` (the default, and
+ /// files written before it) assigns none.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub learn_hotkey: Option,
/// The lone-key trigger (docs/dictation.md §13.1): a right-hand modifier, Fn or a mouse button
/// that drives a take on its own, next to [`Settings::hotkey`]; `None` (the default, and files
/// written before it) = off.
@@ -508,6 +512,7 @@ impl Default for Settings {
context_sharing: ContextSharing::default(),
edit_hotkey: default_edit_hotkey(),
copy_last_hotkey: None,
+ learn_hotkey: None,
solo_key: None,
pairing_always_on: false,
pinned_scene: None,
@@ -607,7 +612,12 @@ mod tests {
let text = std::fs::read_to_string(root.join(script)).unwrap();
let start = text.find("{\n \"schema\": 1").unwrap_or_else(|| panic!("{script}: no settings heredoc"));
let len = text[start..].find("\n}\n").unwrap() + 2;
- let json = text[start..start + len].replace("$2", "http://127.0.0.1:9").replace("${4:-false}", "false").replace("${3:-paste}", "paste");
+ // `${learn}`: smoke-dictation.sh's optional 从选中文字学习 shortcut (docs/dictation.md §35).
+ let json = text[start..start + len]
+ .replace("$2", "http://127.0.0.1:9")
+ .replace("${4:-false}", "false")
+ .replace("${3:-paste}", "paste")
+ .replace("${learn}", r#""learn_hotkey": "Ctrl+Alt+L","#);
let written: serde_json::Value = serde_json::from_str(&json).unwrap_or_else(|e| panic!("{script}: {e}"));
let settings: Settings = serde_json::from_value(written.clone()).unwrap();
assert_eq!(settings.engines.asr_provider, provider, "{script}");
diff --git a/crates/voltip-core/src/ui.rs b/crates/voltip-core/src/ui.rs
index c2681c0e..4ef42db9 100644
--- a/crates/voltip-core/src/ui.rs
+++ b/crates/voltip-core/src/ui.rs
@@ -97,6 +97,12 @@ pub enum UiEvent {
/// The ignored pairs.
pairs: Vec,
},
+ /// The pill's notice after a 从选中文字学习 (docs/dictation.md §35), full replacement; `None`
+ /// when it went.
+ LearnNotice {
+ /// The notice.
+ notice: Option,
+ },
/// Scenes, full replacement, in matching order (docs/dictation.md §18).
Scenes {
/// Scenes in order.
@@ -451,6 +457,12 @@ pub struct HotkeyStatus {
/// Why the 复制上一条结果 chord is not registered (conflict, pure Wayland, another chord's).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub copy_last_error: Option,
+ /// The 从选中文字学习 chord actually registered (docs/dictation.md §35), if any.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub learn_registered: Option,
+ /// Why the 从选中文字学习 chord is not registered (conflict, pure Wayland, another chord's).
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub learn_error: Option,
/// What the hotkey can do in the session the shell runs in (all `false` until it reports).
#[serde(default)]
pub capabilities: HotkeyCapabilities,
@@ -565,6 +577,10 @@ pub struct UiState {
/// (and left off the wire) until the user ignores one.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub vocabulary_ignored: Vec,
+ /// The pill's notice after a 从选中文字学习 (docs/dictation.md §35); left off the wire while
+ /// there is none.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub learn_notice: Option,
/// Scenes in matching order (docs/dictation.md §18).
#[serde(default)]
pub scenes: Vec,
@@ -654,6 +670,7 @@ impl Default for UiState {
dictionary: Vec::new(),
rules: Vec::new(),
vocabulary_ignored: Vec::new(),
+ learn_notice: None,
scenes: Vec::new(),
presets: Vec::new(),
phone_take: None,
@@ -763,6 +780,10 @@ impl UiState {
self.vocabulary_ignored = pairs.clone();
UiEvent::VocabularyIgnored { pairs }
}
+ CoreEvent::LearnNotice(notice) => {
+ self.learn_notice = notice.clone();
+ UiEvent::LearnNotice { notice }
+ }
CoreEvent::Scenes(scenes) => {
self.scenes = scenes.clone();
UiEvent::Scenes { scenes }
@@ -984,6 +1005,7 @@ mod tests {
preset: None,
origin: None,
processed: None,
+ corrected: None,
file: None,
timing: None,
glossary_sent: None,
diff --git a/crates/voltip-core/src/vocabulary/backtest.rs b/crates/voltip-core/src/vocabulary/backtest.rs
index 72c0fe78..f6aef551 100644
--- a/crates/voltip-core/src/vocabulary/backtest.rs
+++ b/crates/voltip-core/src/vocabulary/backtest.rs
@@ -191,7 +191,15 @@ mod tests {
use crate::vocabulary::{RuleKind, VocabularyHits};
fn take(raw: &str, text: &str, at_ms: u64) -> HistoryText {
- HistoryText { id: Uuid::new_v4(), at_ms, raw_text: raw.into(), text: text.into(), refined: true, vocabulary: VocabularyHits::default() }
+ HistoryText {
+ id: Uuid::new_v4(),
+ at_ms,
+ raw_text: raw.into(),
+ text: text.into(),
+ refined: true,
+ vocabulary: VocabularyHits::default(),
+ corrected: None,
+ }
}
fn entry(term: &str, heard: &[&str]) -> DictionaryEntry {
diff --git a/crates/voltip-core/src/vocabulary/learn.rs b/crates/voltip-core/src/vocabulary/learn.rs
new file mode 100644
index 00000000..fd6c87c4
--- /dev/null
+++ b/crates/voltip-core/src/vocabulary/learn.rs
@@ -0,0 +1,644 @@
+//! 从修改中学习 (docs/dictation.md §35): the user corrected a take in the application it went to,
+//! selected the corrected text and asked Voltip to learn from it. [`match_selection`] finds the
+//! takes the selection is the corrected form of and builds each one's whole corrected text;
+//! [`storable`] says whether a correction holds anything to learn; [`edit_changes`] is what the
+//! learning suggestions take from it: the replacements of the inserted text whose wording the
+//! recogniser wrote and that neither the AI clean-up, the dictionary nor a rule touched — the
+//! errors the clean-up's own changes cannot show (§16.10). Nothing here calls an AI service.
+
+use std::collections::HashSet;
+
+use crate::dictation::insert_check::normalize;
+use crate::history::HistoryText;
+use crate::mcp::candidates::{MAX_DIFF_CELLS, MAX_SCAN_CELLS, Replacement, Replay, SegmentKind, diff_segments_by, diff_tokens, replacements};
+
+/// Recognised takes a selection is compared with, newest first.
+pub const LEARN_TAKES: usize = 50;
+/// The longest selection learned from, in characters.
+pub const MAX_LEARN_SELECTION_CHARS: usize = 8000;
+/// The least similarity at which a selection counts as the corrected form of a take.
+pub const MATCH_MIN: f64 = 0.4;
+/// Takes this close in similarity to the best one count as tied; the newer one wins.
+pub const MATCH_TIE: f64 = 0.05;
+/// Most takes one selection corrects (it may cover a few takes dictated one after another).
+pub const MAX_TAKES_PER_SELECTION: usize = 5;
+/// The longest run, in characters other than white space, compared character by character inside
+/// one replacement; a longer one adds nothing to the similarity.
+const INNER_MAX: usize = 64;
+
+/// One replacement the user made that the learning suggestions learn from: the recogniser's
+/// wording and the user's, where the first sits in the recognised text and the second in the
+/// corrected text (characters).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct EditChange {
+ pub(crate) heard: String,
+ pub(crate) right: String,
+ pub(crate) heard_at: usize,
+ pub(crate) right_at: usize,
+}
+
+/// The replacements of `take.text` → `corrected` whose inserted wording is the recogniser's: it
+/// lies where `raw_text` → `text` keeps the tokens (ASCII case aside, so a clean-up that only
+/// changed the case still counts), with the recognised wording and its offset in `raw_text`.
+fn recognised_changes(take: &HistoryText, corrected: &str) -> Vec<(Replacement, usize)> {
+ let Some(found) = replacements(&take.text, corrected) else { return Vec::new() };
+ if found.is_empty() {
+ return Vec::new();
+ }
+ let Some(segments) = diff_segments_by(&take.raw_text, &take.text, |a, b| a.eq_ignore_ascii_case(b)) else { return Vec::new() };
+ // For each character of `text`, the character of `raw_text` it is, where the two keep it.
+ let mut to_raw: Vec> = Vec::new();
+ let mut at = 0usize;
+ for segment in &segments {
+ let n = segment.text.chars().count();
+ match segment.kind {
+ SegmentKind::Same => {
+ to_raw.extend((at..at + n).map(Some));
+ at += n;
+ }
+ SegmentKind::Del => at += n,
+ SegmentKind::Add => to_raw.extend(std::iter::repeat_n(None, n)),
+ }
+ }
+ let raw: Vec = take.raw_text.chars().collect();
+ found
+ .into_iter()
+ .filter_map(|change| {
+ let n = change.heard.chars().count();
+ let start = to_raw.get(change.heard_at).copied().flatten()?;
+ if !(0..n).all(|k| to_raw.get(change.heard_at + k).copied().flatten() == Some(start + k)) {
+ return None;
+ }
+ let heard: String = raw.get(start..start + n)?.iter().collect();
+ (heard != change.polished).then_some((Replacement { heard, ..change }, start))
+ })
+ .collect()
+}
+
+/// `corrected` holds a change worth keeping: it differs from what was inserted, and at least one
+/// of its replacements is in the recogniser's own wording ([`recognised_changes`]). Whether the
+/// take's dictionary corrections or rules explain it is left to the suggestions, which replay them.
+pub fn storable(take: &HistoryText, corrected: &str) -> bool {
+ corrected != take.text && !recognised_changes(take, corrected).is_empty()
+}
+
+/// The replacements of `corrected` the learning suggestions take: [`recognised_changes`] without
+/// those the take's own corrections and rules made (`replay`: it overlaps one of their changes, or
+/// turns the recognised wording into the user's).
+pub(crate) fn edit_changes(take: &HistoryText, corrected: &str, replay: &Replay) -> Vec {
+ recognised_changes(take, corrected)
+ .into_iter()
+ .filter(|(change, at)| !replay.touches(*at, change.heard.chars().count()) && replay.run(&change.heard) != change.polished)
+ .map(|(change, at)| EditChange { heard: change.heard, right: change.polished, heard_at: at, right_at: change.polished_at })
+ .collect()
+}
+
+/// One token of a text being matched: the token, the token without its trailing white space (what
+/// two tokens are compared by: an application may end a line or the field differently), its
+/// characters other than white space, and whether it is a word (letters, digits, one CJK character).
+struct Tok<'a> {
+ text: &'a str,
+ key: &'a str,
+ chars: usize,
+ word: bool,
+}
+
+fn toks(text: &str) -> Vec> {
+ diff_tokens(text)
+ .into_iter()
+ .map(|t| Tok {
+ text: t,
+ key: t.trim_end(),
+ chars: t.chars().filter(|c| !c.is_whitespace()).count(),
+ word: t.chars().next().is_some_and(char::is_alphanumeric),
+ })
+ .collect()
+}
+
+fn chars_of(toks: &[Tok<'_>]) -> usize {
+ toks.iter().map(|t| t.chars).sum()
+}
+
+fn words_of(toks: &[Tok<'_>]) -> usize {
+ toks.iter().filter(|t| t.word).count()
+}
+
+/// The characters of `toks` other than white space, ASCII letters in lower case.
+fn folded(toks: &[Tok<'_>]) -> Vec {
+ toks.iter().flat_map(|t| t.text.chars()).filter(|c| !c.is_whitespace()).map(|c| c.to_ascii_lowercase()).collect()
+}
+
+/// The length of the longest common subsequence of two short character runs.
+fn lcs_len(a: &[char], b: &[char]) -> usize {
+ let mut row = vec![0usize; b.len() + 1];
+ for &x in a {
+ let mut diagonal = 0;
+ for (j, &y) in b.iter().enumerate() {
+ let above = row[j + 1];
+ row[j + 1] = if x == y { diagonal + 1 } else { above.max(row[j]) };
+ diagonal = above;
+ }
+ }
+ row[b.len()]
+}
+
+/// The matched token pairs of the token-level LCS of `a` and `b`, ties going to `a`'s side as in
+/// [`crate::mcp::candidates::diff_segments`]; `None` past [`MAX_DIFF_CELLS`].
+fn lcs_pairs(a: &[Tok<'_>], b: &[Tok<'_>]) -> Option> {
+ let width = b.len() + 1;
+ if (a.len() + 1).saturating_mul(width) > MAX_DIFF_CELLS {
+ return None;
+ }
+ let mut table = vec![0u32; (a.len() + 1) * width];
+ for i in (0..a.len()).rev() {
+ for j in (0..b.len()).rev() {
+ table[i * width + j] =
+ if a[i].key == b[j].key { table[(i + 1) * width + j + 1] + 1 } else { table[(i + 1) * width + j].max(table[i * width + j + 1]) };
+ }
+ }
+ let mut out = Vec::new();
+ let (mut i, mut j) = (0, 0);
+ while i < a.len() && j < b.len() {
+ if a[i].key == b[j].key {
+ out.push((i, j));
+ i += 1;
+ j += 1;
+ } else if table[(i + 1) * width + j] >= table[i * width + j + 1] {
+ i += 1;
+ } else {
+ j += 1;
+ }
+ }
+ Some(out)
+}
+
+/// Which end of the take an unmatched run is at.
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum End {
+ Start,
+ Finish,
+}
+
+/// The tokens of the selection's run `extra` that replace the take's run `missing` at one end of
+/// the match (the error was the take's first or last words): whole tokens next to the matched part,
+/// starting (at the start) or ending (at the finish) with a word, within one word of `missing`'s
+/// count and half to twice its characters, the most similar character by character; on a tie the
+/// one closest to `missing`'s count of words, then the shortest. The rest of `extra` is text the
+/// user selected besides the take. `None` when no run fits. The answer is how many tokens of
+/// `extra` are taken, and their character LCS with `missing`.
+fn edge(missing: &[Tok<'_>], extra: &[Tok<'_>], end: End) -> Option<(usize, usize)> {
+ let (words, chars) = (words_of(missing), chars_of(missing));
+ if words == 0 || words_of(extra) == 0 || chars > INNER_MAX {
+ return None;
+ }
+ let target = folded(missing);
+ let mut best: Option<(usize, usize, usize, usize)> = None; // (taken, score, word difference, chars)
+ for taken in 1..=extra.len() {
+ let run = match end {
+ End::Start => &extra[extra.len() - taken..],
+ End::Finish => &extra[..taken],
+ };
+ let (run_words, run_chars) = (words_of(run), chars_of(run));
+ if run_chars > 2 * chars {
+ break;
+ }
+ let bounded = match end {
+ End::Start => run[0].word,
+ End::Finish => run[run.len() - 1].word,
+ };
+ if !bounded || run_words.abs_diff(words) > 1 || 2 * run_chars < chars {
+ continue;
+ }
+ let score = lcs_len(&folded(run), &target);
+ let apart = run_words.abs_diff(words);
+ if best.is_none_or(|(_, s, a, c)| (score, std::cmp::Reverse(apart), std::cmp::Reverse(run_chars)) > (s, std::cmp::Reverse(a), std::cmp::Reverse(c))) {
+ best = Some((taken, score, apart, run_chars));
+ }
+ }
+ best.map(|(taken, score, _, _)| (taken, score))
+}
+
+/// Where a take and a selection meet, and how alike they are there.
+#[derive(Clone, Copy, Debug, PartialEq)]
+struct Alignment {
+ /// The take's tokens the selection covers.
+ take: (usize, usize),
+ /// The selection's tokens that are the take's.
+ selection: (usize, usize),
+ /// (Characters in the same tokens + the character LCS inside each replacement) ÷ the larger
+ /// side's characters, white space not counted.
+ similarity: f64,
+}
+
+/// Words on one side of a gap between two matched tokens past the other side's, from which the
+/// match is taken to be two places rather than one replacement: the LCS also pairs a stray word of
+/// another take the selection holds, or of a part of the take the user did not select.
+const GAP_BREAK: usize = 3;
+
+/// The run of `pairs` with the most matched characters, cut where a gap between two matched tokens
+/// has more than [`GAP_BREAK`] words more on one side than on the other.
+fn densest(take: &[Tok<'_>], selection: &[Tok<'_>], pairs: &[(usize, usize)]) -> Vec<(usize, usize)> {
+ let mut best: (usize, &[(usize, usize)]) = (0, &[]);
+ let mut start = 0;
+ for end in 1..=pairs.len() {
+ let cut = end == pairs.len() || {
+ let (p, q) = (pairs[end - 1], pairs[end]);
+ words_of(&take[p.0 + 1..q.0]).abs_diff(words_of(&selection[p.1 + 1..q.1])) > GAP_BREAK
+ };
+ if cut {
+ let run = &pairs[start..end];
+ let matched = run.iter().map(|&(i, _)| take[i].chars).sum::();
+ if matched > best.0 || best.1.is_empty() {
+ best = (matched, run);
+ }
+ start = end;
+ }
+ }
+ best.1.to_vec()
+}
+
+/// The alignment of `take` and `selection`, or `None` when they share no word.
+fn align(take: &[Tok<'_>], selection: &[Tok<'_>]) -> Option {
+ let pairs = densest(take, selection, &lcs_pairs(take, selection)?);
+ if !pairs.iter().any(|&(i, _)| take[i].word) {
+ return None;
+ }
+ let (first, last) = (pairs[0], pairs[pairs.len() - 1]);
+ let mut matched: usize = pairs.iter().map(|&(i, _)| take[i].chars).sum();
+ for window in pairs.windows(2) {
+ let (p, q) = (window[0], window[1]);
+ let (gap_take, gap_selection) = (&take[p.0 + 1..q.0], &selection[p.1 + 1..q.1]);
+ if chars_of(gap_take) <= INNER_MAX && chars_of(gap_selection) <= INNER_MAX {
+ matched += lcs_len(&folded(gap_take), &folded(gap_selection));
+ }
+ }
+ let (take_start, selection_start) = match edge(&take[..first.0], &selection[..first.1], End::Start) {
+ Some((taken, score)) => {
+ matched += score;
+ (0, first.1 - taken)
+ }
+ None => (first.0, first.1),
+ };
+ let (take_end, selection_end) = match edge(&take[last.0 + 1..], &selection[last.1 + 1..], End::Finish) {
+ Some((taken, score)) => {
+ matched += score;
+ (take.len(), last.1 + 1 + taken)
+ }
+ None => (last.0 + 1, last.1 + 1),
+ };
+ let size = chars_of(&take[take_start..take_end]).max(chars_of(&selection[selection_start..selection_end]));
+ #[allow(clippy::cast_precision_loss)] // texts of at most a few thousand characters
+ (size > 0).then(|| Alignment { take: (take_start, take_end), selection: (selection_start, selection_end), similarity: matched as f64 / size as f64 })
+}
+
+/// `base` with `range` replaced by `picked`. A selection that ends just before the take's next word
+/// leaves out the space the take had there: the replaced part's trailing white space stays.
+fn splice(base: &[Tok<'_>], range: (usize, usize), picked: &[Tok<'_>]) -> String {
+ fn trailing<'a>(toks: &[Tok<'a>]) -> &'a str {
+ toks.last().map_or("", |t| &t.text[t.key.len()..])
+ }
+ let join = |toks: &[Tok<'_>]| toks.iter().map(|t| t.text).collect::();
+ let (a, b) = range;
+ let kept = if trailing(picked).is_empty() { trailing(&base[a..b]) } else { "" };
+ format!("{}{}{kept}{}", join(&base[..a]), join(picked), join(&base[b..]))
+}
+
+/// The tokens of `corrected` that stand for `range` of `inserted` (the take's text and its earlier
+/// correction): from the token `range.0` became, or right after the last one kept before it, to the
+/// token `range.1 - 1` became, or up to the next one kept after it. A replacement the earlier
+/// correction made across an end of `range` is inside; one wholly outside stays as corrected.
+/// `None` past [`MAX_DIFF_CELLS`].
+fn map_range(inserted: &[Tok<'_>], corrected: &[Tok<'_>], range: (usize, usize)) -> Option<(usize, usize)> {
+ let pairs = lcs_pairs(inserted, corrected)?;
+ let (a, b) = range;
+ let start = match pairs.iter().find(|(i, _)| *i == a) {
+ Some(&(_, j)) => j,
+ None => pairs.iter().rev().find(|(i, _)| *i < a).map_or(0, |&(_, j)| j + 1),
+ };
+ let end = match pairs.iter().find(|(i, _)| *i + 1 == b) {
+ Some(&(_, j)) => j + 1,
+ None => pairs.iter().find(|(i, _)| *i >= b).map_or(corrected.len(), |&(_, j)| j),
+ };
+ Some((start, end.max(start)))
+}
+
+/// A take the selection corrects: which (an index into the takes given), its whole corrected text,
+/// and how alike they were.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Matched {
+ /// Index into the takes [`match_selection`] was given.
+ pub index: usize,
+ /// The take's text with the selection's wording where the selection covers it: on top of the
+ /// earlier correction when there is one, so a second correction keeps the first.
+ pub corrected: String,
+ /// See [`MATCH_MIN`].
+ pub similarity: f64,
+}
+
+/// A candidate before the choice: `alignment` is with the corrected text, or with the inserted
+/// text when the corrected one shares no word with the selection (`on_inserted`).
+struct Candidate {
+ index: usize,
+ alignment: Alignment,
+ on_inserted: bool,
+ similarity: f64,
+}
+
+fn overlaps(a: (usize, usize), b: (usize, usize)) -> bool {
+ a.0 < b.1 && b.0 < a.1
+}
+
+/// The takes (newest first) that `selection` is the corrected form of, newest first: each the most
+/// alike take of a part of the selection (similarity at least [`MATCH_MIN`], a word in common; a
+/// newer take wins within [`MATCH_TIE`]), at most [`MAX_TAKES_PER_SELECTION`], over parts that do
+/// not overlap. A take already corrected is compared with both its corrected and its inserted
+/// text, the higher similarity counting; its new corrected text builds on the earlier correction,
+/// or on the inserted text when the corrected one has no word in common with the selection (the
+/// original wording selected again to take a correction back).
+pub fn match_selection(selection: &str, takes: &[HistoryText]) -> Vec {
+ let selection = normalize(selection);
+ let sel = toks(&selection);
+ let words: HashSet<&str> = sel.iter().filter(|t| t.word).map(|t| t.key).collect();
+ let shares = |toks: &[Tok<'_>]| toks.iter().any(|t| t.word && words.contains(t.key));
+ let mut candidates: Vec = Vec::new();
+ let mut cells = 0usize;
+ for (index, take) in takes.iter().enumerate() {
+ let corrected = take.corrected.as_deref().map(toks).filter(|t| shares(t));
+ let inserted = Some(toks(&take.text)).filter(|t| (take.corrected.is_some() || corrected.is_none()) && shares(t));
+ if corrected.is_none() && inserted.is_none() {
+ continue;
+ }
+ let cost =
+ [&corrected, &inserted].iter().filter_map(|t| t.as_ref()).fold(0usize, |sum, t| sum.saturating_add((t.len() + 1).saturating_mul(sel.len() + 1)));
+ if cells.saturating_add(cost) > MAX_SCAN_CELLS {
+ break;
+ }
+ cells += cost;
+ let on_corrected = corrected.as_deref().and_then(|t| align(t, &sel));
+ let on_inserted = inserted.as_deref().and_then(|t| align(t, &sel));
+ // The alignment that wins decides the rebuild: the more alike, then the one covering more
+ // of the selection; the corrected text on a full tie.
+ let covered = |a: &Alignment| chars_of(&sel[a.selection.0..a.selection.1]);
+ let (alignment, from_inserted) = match (on_corrected, on_inserted) {
+ (Some(c), Some(i)) if i.similarity > c.similarity + 1e-9 || ((i.similarity - c.similarity).abs() <= 1e-9 && covered(&i) > covered(&c)) => (i, true),
+ (Some(c), _) => (c, false),
+ (None, Some(i)) => (i, true),
+ (None, None) => continue,
+ };
+ if alignment.similarity >= MATCH_MIN {
+ candidates.push(Candidate { index, alignment, on_inserted: from_inserted, similarity: alignment.similarity });
+ }
+ }
+ let mut chosen: Vec = Vec::new();
+ while chosen.len() < MAX_TAKES_PER_SELECTION {
+ let Some(best) = candidates.iter().max_by(|a, b| a.similarity.total_cmp(&b.similarity).then(b.index.cmp(&a.index))) else { break };
+ let (best_selection, best_similarity) = (best.alignment.selection, best.similarity);
+ let Some(pick) = candidates
+ .iter()
+ .enumerate()
+ .filter(|(_, c)| overlaps(c.alignment.selection, best_selection) && c.similarity >= best_similarity - MATCH_TIE)
+ .min_by_key(|(_, c)| c.index)
+ .map(|(i, _)| i)
+ else {
+ break;
+ };
+ let pick = candidates.swap_remove(pick);
+ candidates.retain(|c| !overlaps(c.alignment.selection, pick.alignment.selection));
+ chosen.push(pick);
+ }
+ chosen.sort_by_key(|c| c.index);
+ chosen
+ .into_iter()
+ .map(|c| {
+ let take = &takes[c.index];
+ let picked = &sel[c.alignment.selection.0..c.alignment.selection.1];
+ let corrected = match (c.on_inserted, take.corrected.as_deref()) {
+ // On the inserted text, of a take corrected before: the selection replaces the part of
+ // the corrected text that stands for the aligned part, the rest keeps its correction.
+ (true, Some(earlier)) => {
+ let inserted = toks(&take.text);
+ let earlier = toks(earlier);
+ match map_range(&inserted, &earlier, c.alignment.take) {
+ Some(range) => splice(&earlier, range, picked),
+ None => splice(&inserted, c.alignment.take, picked),
+ }
+ }
+ (true | false, None) => splice(&toks(&take.text), c.alignment.take, picked),
+ (false, Some(earlier)) => splice(&toks(earlier), c.alignment.take, picked),
+ };
+ Matched { index: c.index, corrected, similarity: c.similarity }
+ })
+ .collect()
+}
+
+#[cfg(test)]
+#[allow(clippy::unwrap_used, clippy::expect_used, clippy::float_cmp)]
+mod tests {
+ use uuid::Uuid;
+
+ use super::*;
+ use crate::vocabulary::{DictionaryEntry, EntrySource};
+ use crate::vocabulary::{VocabularyHit, VocabularyHits};
+
+ /// A take whose recognised text was inserted as it was (no clean-up).
+ fn plain(text: &str, at_ms: u64) -> HistoryText {
+ HistoryText {
+ id: Uuid::new_v4(),
+ at_ms,
+ raw_text: text.into(),
+ text: text.into(),
+ refined: false,
+ vocabulary: VocabularyHits::default(),
+ corrected: None,
+ }
+ }
+
+ fn polished(raw: &str, text: &str, at_ms: u64) -> HistoryText {
+ HistoryText { raw_text: raw.into(), refined: true, ..plain(text, at_ms) }
+ }
+
+ fn pairs(take: &HistoryText, corrected: &str) -> Vec<(String, String)> {
+ let replay = Replay::of(take, &[], &[]).unwrap();
+ edit_changes(take, corrected, &replay).into_iter().map(|c| (c.heard, c.right)).collect()
+ }
+
+ fn one(selection: &str, takes: &[HistoryText]) -> Matched {
+ let found = match_selection(selection, takes);
+ assert_eq!(found.len(), 1, "{found:?}");
+ found.into_iter().next().unwrap()
+ }
+
+ #[test]
+ fn a_corrected_sentence_finds_its_take_and_the_users_wording() {
+ let take = plain("我在用 Quinn for max 做测试", 10);
+ let found = one("我在用 Qwen 4 max 做测试", std::slice::from_ref(&take));
+ assert_eq!(found.corrected, "我在用 Qwen 4 max 做测试");
+ assert!((found.similarity - 11.0 / 17.0).abs() < 1e-9, "{}", found.similarity);
+ assert_eq!(pairs(&take, &found.corrected), [("Quinn for".into(), "Qwen 4".into())]);
+ assert!(storable(&take, &found.corrected));
+ }
+
+ /// The tester's case (2026-11-18): the whole take was the wrong words but one.
+ #[test]
+ fn a_take_that_is_mostly_the_error_still_matches() {
+ let take = plain("Quinn for max", 10);
+ let found = one("Qwen 4 max", std::slice::from_ref(&take));
+ assert!((found.similarity - 5.0 / 11.0).abs() < 1e-9, "{}", found.similarity);
+ assert_eq!(found.corrected, "Qwen 4 max");
+ assert_eq!(pairs(&take, &found.corrected), [("Quinn for".into(), "Qwen 4".into())]);
+ }
+
+ #[test]
+ fn text_selected_around_the_take_is_left_out() {
+ let take = plain("Quinn for max is great", 10);
+ assert_eq!(one("Hi, Qwen 4 max is great", std::slice::from_ref(&take)).corrected, "Qwen 4 max is great");
+ let take = plain("我们用非书开会", 10);
+ let found = one("大家好,我们用飞书开会", std::slice::from_ref(&take));
+ assert_eq!(found.corrected, "我们用飞书开会");
+ assert_eq!(pairs(&take, &found.corrected), [("非".into(), "飞".into())], "widened by the suggestions, not here");
+ let take = plain("先说一句。第二句 Quinn for max。最后一句。", 10);
+ assert_eq!(
+ one("第二句 Qwen 4 max。", std::slice::from_ref(&take)).corrected,
+ "先说一句。第二句 Qwen 4 max。最后一句。",
+ "only the selected sentence changes"
+ );
+ }
+
+ /// Regression (scripts/smoke-desktop-linux.sh, 2026-11-18: history.sqlite3 kept
+ /// `corrected.text` 「Voltip 冒烟测」 for the selection 「Voltip 冒烟测试」): at the end of the
+ /// take no run of the selection has a character in common with 「注入」, and the shortest run won
+ /// the tie, so 「试」 counted as text selected besides the take. A run as many words long as the
+ /// take's wins such a tie.
+ #[test]
+ fn regression_an_end_replacement_with_nothing_in_common_keeps_every_character() {
+ let take = plain("Voltip 冒烟注入", 10);
+ let found = one("Voltip 冒烟测试", std::slice::from_ref(&take));
+ assert_eq!(found.corrected, "Voltip 冒烟测试");
+ assert_eq!(pairs(&take, &found.corrected), [("注入".into(), "测试".into())]);
+ let take = plain("注入成功", 10);
+ assert_eq!(one("测试成功", std::slice::from_ref(&take)).corrected, "测试成功", "at the start too");
+ }
+
+ /// Regression (goal review of PR #260, 2026-11-18): a take corrected before is compared with
+ /// its corrected text and its inserted text, the higher similarity counting (§35.4). Only the
+ /// corrected text was searched, so selecting the original wording again to take a correction
+ /// back found nothing when the correction had replaced every word.
+ #[test]
+ fn regression_the_original_wording_takes_back_a_correction_that_shares_no_word_with_it() {
+ let take = HistoryText { corrected: Some("Qwen 4".into()), ..plain("Quinn for", 10) };
+ let found = one("Quinn for", std::slice::from_ref(&take));
+ assert_eq!(found.corrected, "Quinn for");
+ assert!((found.similarity - 1.0).abs() < 1e-9, "{}", found.similarity);
+ assert!(!storable(&take, &found.corrected), "nothing left to keep: the correction is cleared");
+ // Sharing a word with the corrected text, the correction stays the base (§35.4).
+ let take = HistoryText { corrected: Some("我在用 Qwen 4 max 做测试".into()), ..plain("我在用 Quinn for max 做测试", 10) };
+ assert_eq!(one("用 Qwen 4 max 做实验", std::slice::from_ref(&take)).corrected, "我在用 Qwen 4 max 做实验");
+ }
+
+ /// Regression (goal review of PR #260, round 2): both texts of a corrected take align, the
+ /// inserted one better — the original wording selected again — and the corrected text was
+ /// rebuilt on the corrected alignment all the same: 「red apple」 matched the corrected text's
+ /// first 「red」 only, 「apple」 counted as selected besides the take, and the earlier
+ /// 「grape」 stayed. The winning alignment decides now, mapped onto the corrected text, so an
+ /// earlier correction outside the selection (「plum」) stays too.
+ #[test]
+ fn regression_the_alignment_that_wins_rebuilds_the_take() {
+ let take = HistoryText { corrected: Some("red grape red pear".into()), ..plain("red apple red pear", 10) };
+ assert_eq!(one("red apple", std::slice::from_ref(&take)).corrected, "red apple red pear", "taken back");
+ let take = HistoryText { corrected: Some("red grape red plum".into()), ..plain("red apple red pear", 10) };
+ assert_eq!(one("red apple", std::slice::from_ref(&take)).corrected, "red apple red plum", "the other correction stays");
+ let take = HistoryText { corrected: Some("我们下午四点在飞书开会".into()), ..plain("我们下午三点在飞书开会", 10) };
+ assert_eq!(one("下午五点在飞书", std::slice::from_ref(&take)).corrected, "我们下午五点在飞书开会");
+ }
+
+ /// Regression (found while fixing the round-2 item, 2026-11-18): a selection that stops right
+ /// before the take's next word has no trailing space, and the take's space there was lost with
+ /// the replaced words (「Qwen 4 maxis great」).
+ #[test]
+ fn regression_a_selection_that_stops_before_the_next_word_keeps_the_space() {
+ let take = plain("Quinn for max is great", 10);
+ assert_eq!(one("Qwen 4 max", std::slice::from_ref(&take)).corrected, "Qwen 4 max is great");
+ }
+
+ #[test]
+ fn a_selection_over_two_takes_corrects_each() {
+ let takes = [plain("第二次说的是 GitHab 上的项目", 20), plain("第一次说 Quinn for max 很好用", 10)];
+ let found = match_selection("第一次说 Qwen 4 max 很好用第二次说的是 GitHub 上的项目", &takes);
+ let got: Vec<(usize, &str)> = found.iter().map(|m| (m.index, m.corrected.as_str())).collect();
+ assert_eq!(got, [(0, "第二次说的是 GitHub 上的项目"), (1, "第一次说 Qwen 4 max 很好用")]);
+ }
+
+ #[test]
+ fn nothing_alike_matches_nothing_and_the_same_text_is_nothing_to_keep() {
+ let take = plain("Quinn for max", 10);
+ assert!(match_selection("今天天气不错", std::slice::from_ref(&take)).is_empty());
+ let same = one("Quinn for max", std::slice::from_ref(&take));
+ assert_eq!(same.corrected, "Quinn for max");
+ assert!(!storable(&take, &same.corrected));
+ }
+
+ #[test]
+ fn the_newer_take_wins_a_tie() {
+ let takes = [plain("Quinn for max", 20), plain("Quinn for max", 10)];
+ assert_eq!(one("Qwen 4 max", &takes).index, 0);
+ }
+
+ #[test]
+ fn a_change_the_clean_up_made_is_not_learned_but_a_case_change_is_no_obstacle() {
+ let cased = polished("quinn for max", "Quinn for max", 10);
+ assert_eq!(pairs(&cased, "Qwen 4 max"), [("quinn for".into(), "Qwen 4".into())], "the recogniser's wording");
+ let polished_word = polished("我们用维他命开会", "我们用 Voltip 开会。", 10);
+ assert!(pairs(&polished_word, "我们用 VoltIP 开会。").is_empty(), "the clean-up wrote Voltip");
+ assert!(!storable(&polished_word, "我们用 VoltIP 开会。"));
+ }
+
+ #[test]
+ fn a_change_the_dictionary_made_is_not_learned() {
+ let entry = DictionaryEntry {
+ id: Uuid::new_v4(),
+ term: "GitHub".into(),
+ heard_as: vec!["github".into()],
+ enabled: true,
+ source: EntrySource::Manual,
+ created_at_ms: 1,
+ updated_at_ms: 1,
+ };
+ let take = HistoryText {
+ raw_text: "代码在 github 上".into(),
+ text: "代码在 GitHub 上".into(),
+ vocabulary: VocabularyHits { corrections: vec![VocabularyHit { id: entry.id, count: 1 }], rules: Vec::new() },
+ ..plain("", 10)
+ };
+ let replay = Replay::of(&take, std::slice::from_ref(&entry), &[]).unwrap();
+ assert!(edit_changes(&take, "代码在 GitLab 上", &replay).is_empty(), "the dictionary wrote GitHub there");
+ assert!(storable(&take, "代码在 GitLab 上"), "kept: whether it is learned is the suggestions' call");
+ assert!(Replay::of(&take, &[], &[]).is_none(), "the entry deleted since: nothing to tell apart");
+ }
+
+ #[test]
+ fn a_second_correction_keeps_the_first_and_a_revert_leaves_nothing() {
+ let mut take = plain("Quinn for max 和 kubernetes 都要装", 10);
+ let first = one("Qwen 4 max 和 kubernetes 都要装", std::slice::from_ref(&take));
+ take.corrected = Some(first.corrected.clone());
+ let second = one("kubernetes 都要装", std::slice::from_ref(&take));
+ assert_eq!(second.corrected, "Qwen 4 max 和 kubernetes 都要装", "the part not selected keeps the first correction");
+ let third = one("Qwen 4 max 和 Kubernetes 都要装", std::slice::from_ref(&take));
+ assert_eq!(third.corrected, "Qwen 4 max 和 Kubernetes 都要装");
+ assert_eq!(pairs(&take, &third.corrected), [("Quinn for".into(), "Qwen 4".into()), ("kubernetes".into(), "Kubernetes".into())], "both corrections");
+ let reverted = one("Quinn for max 和 kubernetes 都要装", std::slice::from_ref(&take));
+ assert_eq!(reverted.corrected, take.text);
+ assert!(!storable(&take, &reverted.corrected));
+ }
+
+ #[test]
+ fn white_space_the_application_adds_at_the_end_does_not_matter() {
+ let take = plain("Quinn for max", 10);
+ assert_eq!(one("Qwen 4 max \n", std::slice::from_ref(&take)).corrected, "Qwen 4 max \n");
+ }
+
+ #[test]
+ fn line_endings_of_the_application_do_not_matter() {
+ let take = plain("第一行 Quinn for max\n第二行", 10);
+ assert_eq!(one("第一行 Qwen 4 max\r\n第二行", std::slice::from_ref(&take)).corrected, "第一行 Qwen 4 max\n第二行");
+ }
+}
diff --git a/crates/voltip-core/src/vocabulary/mod.rs b/crates/voltip-core/src/vocabulary/mod.rs
index e3b0bf72..778edd42 100644
--- a/crates/voltip-core/src/vocabulary/mod.rs
+++ b/crates/voltip-core/src/vocabulary/mod.rs
@@ -12,6 +12,7 @@
mod backtest;
mod ignored;
+pub mod learn;
mod matcher;
pub mod packs;
mod store;
@@ -32,7 +33,7 @@ pub use store::{DICTIONARY_FILE_NAME, DictionaryStore, RULES_FILE_NAME, RuleStor
pub use suggest::{
AcceptOutcome, Accepted, AcceptedBatch, Batch, BatchAcceptOutcome, BatchIgnoreOutcome, BatchItem, BatchLog, BatchUndoOutcome, EntryClash, MAX_BATCH,
MAX_SUGGESTIONS, MAX_UNDOS, REPEATED_MIN, Refusal, Reply, Suggestion, SuggestionPair, SuggestionPick, SuggestionUndo, Suggestions, SuggestionsAnswer,
- UndoLog, UndoOutcome, accept, accept_batch, suggestions, undo, undo_batch,
+ UndoLog, UndoOutcome, accept, accept_batch, edit_picks, suggestions, undo, undo_batch,
};
pub use toml_io::{RULES_TOML_VERSION, export_rules_toml, parse_rules_toml};
diff --git a/crates/voltip-core/src/vocabulary/suggest.rs b/crates/voltip-core/src/vocabulary/suggest.rs
index cc6a1790..20ca46c7 100644
--- a/crates/voltip-core/src/vocabulary/suggest.rs
+++ b/crates/voltip-core/src/vocabulary/suggest.rs
@@ -21,7 +21,7 @@ use super::{
Vocabulary, validate_dictionary_draft,
};
use crate::history::HistoryText;
-use crate::mcp::candidates::{MAX_PAIRS, PairExample, candidates};
+use crate::mcp::candidates::{MAX_PAIRS, Pair, PairExample, scan, tally, widen};
/// Most suggestions one call returns (the MCP tool's [`MAX_PAIRS`]).
pub const MAX_SUGGESTIONS: usize = MAX_PAIRS;
@@ -33,12 +33,13 @@ pub const MAX_BATCH: usize = MAX_SUGGESTIONS;
/// The count from which a suggestion is repeated: the page lists those by default.
pub const REPEATED_MIN: u32 = 2;
-/// One suggestion: a pair the AI clean-up changed, counted over the takes.
+/// One suggestion: a pair the AI clean-up changed, or the user corrected in the application the
+/// take went to (docs/dictation.md §35), counted over the takes.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct Suggestion {
/// What the recogniser wrote.
pub heard: String,
- /// What the polished text has instead.
+ /// What the polished text has instead, or what the user corrected it to: the right spelling.
pub polished: String,
/// How often, in all takes scanned.
pub count: u32,
@@ -46,6 +47,13 @@ pub struct Suggestion {
pub last_at_ms: u64,
/// Up to three snippets of the recognised text around it, newest first.
pub examples: Vec,
+ /// Of `count`, the times the user's own correction made it; the rest the AI clean-up did.
+ #[serde(default, skip_serializing_if = "is_zero")]
+ pub from_edits: u32,
+}
+
+fn is_zero(n: &u32) -> bool {
+ *n == 0
}
/// The suggestions over the recent takes.
@@ -59,10 +67,13 @@ pub struct Suggestions {
pub skipped: u32,
/// Suggestions in all, before `pairs` was cut to the limit.
pub total: u32,
- /// Of `total`, the suggestions counted [`REPEATED_MIN`] times or more: what the page shows by
- /// default.
+ /// Of `total`, the suggestions counted [`REPEATED_MIN`] times or more, and those the user
+ /// corrected themselves (`from_edits`, even once): what the page shows by default (推荐).
#[serde(default)]
pub repeated: u32,
+ /// Of the takes looked at, those the user corrected (docs/dictation.md §35).
+ #[serde(default)]
+ pub edited: u32,
/// The suggestions, most frequent first, then the most recent.
pub pairs: Vec,
}
@@ -78,32 +89,81 @@ pub enum SuggestionsAnswer {
Ready(Suggestions),
}
-/// The pairs of `history` (newest first) the AI clean-up made, as [`candidates`] counts them,
-/// without the ones `dictionary` corrects already (`known`) and the ones in `ignored`, most
-/// frequent first, then the most recent; at most `limit` of them in `pairs`.
+/// A counted pair the ignored list leaves out: the pair itself, or the single characters it was
+/// widened from (docs/dictation.md §16.10), so a pair ignored before the widening stays ignored.
+fn is_ignored(ignored: &[IgnoredPair], pair: &Pair) -> bool {
+ ignored
+ .iter()
+ .any(|i| (i.heard == pair.heard && i.polished == pair.polished) || pair.single.as_ref().is_some_and(|(h, p)| i.heard == *h && i.polished == *p))
+}
+
+/// The pairs of `history` (newest first): those the AI clean-up made and those the user corrected
+/// (docs/dictation.md §35), widened when they were single characters and counted together
+/// ([`crate::mcp::candidates`]), without the ones `dictionary` corrects already (`known`) and the
+/// ones in `ignored`; most frequent first, then the most recent; at most `limit` of them in `pairs`.
pub fn suggestions(dictionary: &[DictionaryEntry], rules: &[ReplacementRule], history: &[HistoryText], ignored: &[IgnoredPair], limit: usize) -> Suggestions {
- let found = candidates(dictionary, rules, history, None, usize::MAX);
- let scanned = usize::try_from(found.scanned).unwrap_or(usize::MAX).min(history.len());
- let mut pairs: Vec = found
- .pairs
+ let read = scan(dictionary, rules, history, None, true);
+ let scanned = usize::try_from(read.scanned).unwrap_or(usize::MAX).min(history.len());
+ let mut pairs: Vec = tally(dictionary, history, widen(history, &read))
.into_iter()
- .filter(|p| !p.known && !ignored.iter().any(|i| i.heard == p.heard && i.polished == p.polished))
- .map(|p| Suggestion { heard: p.heard, polished: p.polished, count: p.count, last_at_ms: p.last_at_ms, examples: p.examples })
+ .filter(|p| !p.known && !is_ignored(ignored, p))
+ .map(|p| Suggestion { heard: p.heard, polished: p.polished, count: p.count, last_at_ms: p.last_at_ms, examples: p.examples, from_edits: p.from_edits })
.collect();
- pairs.sort_by(|a, b| b.count.cmp(&a.count).then(b.last_at_ms.cmp(&a.last_at_ms)));
let total = u32::try_from(pairs.len()).unwrap_or(u32::MAX);
- let repeated = u32::try_from(pairs.iter().filter(|p| p.count >= REPEATED_MIN).count()).unwrap_or(u32::MAX);
+ let repeated = u32::try_from(pairs.iter().filter(|p| p.count >= REPEATED_MIN || p.from_edits > 0).count()).unwrap_or(u32::MAX);
pairs.truncate(limit);
Suggestions {
- scanned: found.scanned,
+ scanned: read.scanned,
refined: u32::try_from(history[..scanned].iter().filter(|t| t.refined).count()).unwrap_or(u32::MAX),
- skipped: found.skipped,
+ skipped: read.skipped,
total,
repeated,
+ edited: read.edited,
pairs,
}
}
+/// The pairs the user's corrections of the takes `ids` give, counted as [`suggestions`] counts
+/// them over `history` (so widened the same way), without the known and the ignored ones, in the
+/// order the takes come: what the notice of 从选中文字学习 offers (docs/dictation.md §35). Each
+/// pick names the first of `ids` it came from.
+pub fn edit_picks(
+ dictionary: &[DictionaryEntry],
+ rules: &[ReplacementRule],
+ history: &[HistoryText],
+ ignored: &[IgnoredPair],
+ ids: &[Uuid],
+) -> Vec {
+ let read = scan(dictionary, rules, history, None, true);
+ let known: Vec<&str> = dictionary.iter().filter(|e| e.enabled).flat_map(|e| e.heard_as.iter().map(String::as_str)).collect();
+ let is_known = |heard: &str| known.iter().any(|k| k.eq_ignore_ascii_case(heard));
+ let mut picks: Vec = Vec::new();
+ for counted in widen(history, &read) {
+ let take = &history[counted.found.take];
+ if !counted.found.edit || !ids.contains(&take.id) {
+ continue;
+ }
+ let pair = Pair {
+ heard: counted.found.heard,
+ polished: counted.found.right,
+ count: 1,
+ last_at_ms: take.at_ms,
+ known: false,
+ examples: Vec::new(),
+ from_edits: 1,
+ single: counted.single,
+ };
+ let known_single = pair.single.as_ref().is_some_and(|(h, _)| is_known(h));
+ if is_known(&pair.heard) || known_single || is_ignored(ignored, &pair) {
+ continue;
+ }
+ if !picks.iter().any(|p| p.heard == pair.heard && p.polished == pair.polished) {
+ picks.push(SuggestionPick { heard: pair.heard, polished: pair.polished, history_id: take.id });
+ }
+ }
+ picks
+}
+
/// How an entry stands in the way of an accept.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
@@ -637,7 +697,15 @@ mod tests {
use crate::vocabulary::{RuleKind, VocabularyHits};
fn take(raw: &str, text: &str, at_ms: u64) -> HistoryText {
- HistoryText { id: Uuid::new_v4(), at_ms, raw_text: raw.into(), text: text.into(), refined: true, vocabulary: VocabularyHits::default() }
+ HistoryText {
+ id: Uuid::new_v4(),
+ at_ms,
+ raw_text: raw.into(),
+ text: text.into(),
+ refined: true,
+ vocabulary: VocabularyHits::default(),
+ corrected: None,
+ }
}
fn rule(name: &str, kind: RuleKind, pattern: &str, replacement: &str) -> ReplacementRule {
@@ -691,16 +759,94 @@ mod tests {
let history = history();
let out = suggestions(&[], &[], &history, &[], MAX_SUGGESTIONS);
assert_eq!((out.scanned, out.refined, out.skipped, out.total), (5, 4, 0, 3));
- assert_eq!(pairs(&out), [("非", "飞", 2), ("维他命", "Voltip", 1), ("库伯内特斯", "Kubernetes", 1)], "count, then the newest first");
+ assert_eq!(
+ pairs(&out),
+ [("非书", "飞书", 2), ("维他命", "Voltip", 1), ("库伯内特斯", "Kubernetes", 1)],
+ "count, then the newest first; 非 → 飞 widened"
+ );
assert_eq!(out.pairs[0].last_at_ms, 40);
assert_eq!(out.pairs[0].examples.iter().map(|e| e.history_id).collect::>(), [history[1].id, history[2].id], "newest first");
assert_eq!(out.pairs[1].examples[0].snippet, "我们用维他命开会");
let one = suggestions(&[], &[], &history, &[], 1);
- assert_eq!((one.total, pairs(&one)), (3, vec![("非", "飞", 2)]), "the limit cuts the list, the total stays");
+ assert_eq!((one.total, pairs(&one)), (3, vec![("非书", "飞书", 2)]), "the limit cuts the list, the total stays");
let none = suggestions(&[], &[], &[], &[], MAX_SUGGESTIONS);
assert_eq!((none.scanned, none.refined, none.total, none.pairs.len()), (0, 0, 0, 0));
}
+ /// A take whose text was inserted as recognised, then corrected by the user to `corrected`.
+ fn corrected(text: &str, corrected: &str, at_ms: u64) -> HistoryText {
+ HistoryText { refined: false, corrected: Some(corrected.into()), ..take(text, text, at_ms) }
+ }
+
+ /// docs/dictation.md §35: the user's corrections are a second source, counted with the
+ /// clean-up's pairs; one correction is enough to be shown by default.
+ #[test]
+ fn the_users_corrections_are_counted_with_the_clean_ups_pairs() {
+ let history = vec![
+ corrected("我在用 Quinn for max 做测试", "我在用 Qwen 4 max 做测试", 50),
+ corrected("发到非书群", "发到飞书群", 40),
+ take("又是非书", "又是飞书。", 30),
+ take("库伯内特斯部署", "Kubernetes 部署", 20),
+ ];
+ let out = suggestions(&[], &[], &history, &[], MAX_SUGGESTIONS);
+ let got: Vec<(&str, &str, u32, u32)> = out.pairs.iter().map(|p| (p.heard.as_str(), p.polished.as_str(), p.count, p.from_edits)).collect();
+ assert_eq!(got, [("非书", "飞书", 2, 1), ("Quinn for", "Qwen 4", 1, 1), ("库伯内特斯", "Kubernetes", 1, 0)]);
+ assert_eq!((out.scanned, out.refined, out.edited, out.total, out.repeated), (4, 2, 2, 3, 2), "corrected once is shown by default");
+ assert_eq!(out.pairs[1].examples[0].snippet, "我在用 Quinn for max 做测试");
+ assert_eq!(out.pairs[1].examples[0].history_id, history[0].id);
+ let json = serde_json::to_value(&out.pairs[2]).unwrap();
+ assert!(json.get("from_edits").is_none(), "left off the wire when none: {json}");
+ }
+
+ /// Regression (goal review of PR #260, 2026-11-18): the user's corrections count each pair once
+ /// per take (plan 4.7), however often the take holds it; and a corrected take too long to
+ /// compare is still one of the `edited` takes read, as a skipped polished one is `refined`.
+ #[test]
+ fn regression_a_correction_counts_once_per_take_and_a_skipped_one_is_still_edited() {
+ let history = vec![corrected("Quinn for max 和 Quinn for max 都试过", "Qwen 4 max 和 Qwen 4 max 都试过", 50)];
+ let out = suggestions(&[], &[], &history, &[], MAX_SUGGESTIONS);
+ let got: Vec<(&str, &str, u32, u32)> = out.pairs.iter().map(|p| (p.heard.as_str(), p.polished.as_str(), p.count, p.from_edits)).collect();
+ assert_eq!(got, [("Quinn for", "Qwen 4", 1, 1)]);
+ let long = "字 ".repeat(1200);
+ let history = vec![corrected(&long, &format!("{long}改"), 50)];
+ let out = suggestions(&[], &[], &history, &[], MAX_SUGGESTIONS);
+ assert_eq!((out.scanned, out.skipped, out.edited), (1, 1, 1));
+ }
+
+ /// docs/dictation.md §16.10: a single character is widened by the neighbour that makes the
+ /// spelling the takes use more often, the right one on a tie, and stays alone without one.
+ #[test]
+ fn a_single_character_is_widened_to_the_spelling_the_takes_use() {
+ let history = vec![
+ take("钉丁开会", "钉钉开会。", 50),
+ take("打开钉钉", "打开钉钉。", 40),
+ take("钉钉群里说", "钉钉群里说。", 30),
+ take("用a非。", "用a飞。", 20),
+ ];
+ let out = suggestions(&[], &[], &history, &[], MAX_SUGGESTIONS);
+ assert_eq!(pairs(&out), [("钉丁", "钉钉", 1), ("非", "飞", 1)], "钉钉 is the common spelling; no CJK neighbour for 非");
+ }
+
+ /// docs/dictation.md §35: the notice offers the pairs of the takes it corrected, widened as the
+ /// page widens them, without the known and the ignored ones.
+ #[test]
+ fn the_notice_offers_the_corrections_of_its_takes_only() {
+ let history = vec![
+ corrected("发到非书群,我在用 Quinn for max", "发到飞书群,我在用 Qwen 4 max", 50),
+ corrected("又是维他命", "又是 Voltip", 40),
+ take("又是非书", "又是飞书。", 30),
+ ];
+ let ids = [history[0].id];
+ let picks = |dictionary: &[DictionaryEntry], ignored: &[IgnoredPair]| {
+ edit_picks(dictionary, &[], &history, ignored, &ids).into_iter().map(|p| (p.heard, p.polished, p.history_id)).collect::>()
+ };
+ let id = history[0].id;
+ assert_eq!(picks(&[], &[]), [("非书".into(), "飞书".into(), id), ("Quinn for".into(), "Qwen 4".into(), id)]);
+ let dir = tempfile::tempdir().unwrap();
+ let store = store_with(dir.path(), &[("飞书", &["非"], true)]);
+ assert_eq!(picks(store.entries(), &[ignored("Quinn for", "Qwen 4")]), [], "known before the widening; ignored");
+ }
+
/// A pair whose `heard` an enabled entry corrects already, and an ignored pair, are not
/// suggested; an entry that is off does not count, and an ignored pair is matched exactly.
#[test]
@@ -709,7 +855,7 @@ mod tests {
let dir = tempfile::tempdir().unwrap();
let store = store_with(dir.path(), &[("Voltip", &["维他命"], true), ("飞书", &["非"], false)]);
let out = suggestions(store.entries(), &[], &history, &[ignored("库伯内特斯", "Kubernetes")], MAX_SUGGESTIONS);
- assert_eq!(pairs(&out), [("非", "飞", 2)], "known: 维他命; ignored: 库伯内特斯; the entry that is off does not count");
+ assert_eq!(pairs(&out), [("非书", "飞书", 2)], "known: 维他命; ignored: 库伯内特斯; the entry that is off does not count");
assert_eq!(out.total, 1);
let other_case = suggestions(&[], &[], &history, &[ignored("库伯内特斯", "kubernetes")], MAX_SUGGESTIONS);
assert_eq!(other_case.total, 3, "an ignored pair is matched exactly");
@@ -723,9 +869,9 @@ mod tests {
let dir = tempfile::tempdir().unwrap();
let mut store = store_with(dir.path(), &[("飞书", &["飞输"], true)]);
let before = suggestions(store.entries(), &[], &history, &[], MAX_SUGGESTIONS);
- assert_eq!(pairs(&before), [("维他命", "Voltip", 1), ("非", "飞", 1)]);
+ assert_eq!(pairs(&before), [("维他命", "Voltip", 1), ("非书", "飞书", 1)]);
accept(&mut store, &[], "维他命", "Voltip", history[0].id, 100).unwrap();
- accept(&mut store, &[], "非", "飞", history[1].id, 101).unwrap();
+ accept(&mut store, &[], "非书", "飞书", history[1].id, 101).unwrap();
let after = suggestions(store.entries(), &[], &history, &[], MAX_SUGGESTIONS);
assert!(after.pairs.is_empty(), "{:?}", after.pairs);
assert_eq!(after.total, 0);
@@ -885,13 +1031,13 @@ mod tests {
fn the_repeated_suggestions_are_counted_before_the_cut() {
let history = history();
let one = suggestions(&[], &[], &history, &[], 1);
- assert_eq!((one.total, one.repeated, one.pairs.len()), (3, 1, 1), "非 → 飞 twice; the other two once");
+ assert_eq!((one.total, one.repeated, one.pairs.len()), (3, 1, 1), "非书 → 飞书 twice; the other two once");
let more = vec![take("又是维他命", "又是 Voltip。", 60), take("还有库伯内特斯", "还有 Kubernetes", 55)];
let history: Vec = more.into_iter().chain(history).collect();
let cut = suggestions(&[], &[], &history, &[], 1);
assert_eq!((cut.total, cut.repeated, pairs(&cut)), (3, 3, vec![("维他命", "Voltip", 2)]), "all three twice, one listed");
let ignoring = suggestions(&[], &[], &history, &[ignored("非", "飞")], MAX_SUGGESTIONS);
- assert_eq!((ignoring.total, ignoring.repeated), (2, 2), "an ignored pair counts nowhere");
+ assert_eq!((ignoring.total, ignoring.repeated), (2, 2), "an ignored pair counts nowhere, ignored before it was widened too");
assert_eq!(suggestions(&[], &[], &[], &[], MAX_SUGGESTIONS).repeated, 0);
}
diff --git a/crates/voltip-core/tests/learn.rs b/crates/voltip-core/tests/learn.rs
new file mode 100644
index 00000000..ae352890
--- /dev/null
+++ b/crates/voltip-core/tests/learn.rs
@@ -0,0 +1,302 @@
+#![allow(clippy::unwrap_used, clippy::expect_used)]
+//! 从选中文字学习 (docs/dictation.md §35) through the real core task, on the dictation fakes: the
+//! shortcut among four distinct chords, a selection that corrects the take (stored with the entry,
+//! offered on the notice, 加入词典 and 撤销 through the learning suggestions' batches), the notice's
+//! queue and timer (behind a result card, cleared by a take, none with the pill off), and the
+//! refusals (history off, a terminal in front, nothing selected, nothing alike).
+
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use tokio::sync::mpsc;
+use voltip_core::dictation::fakes::{FakeAudio, FakeInjector, FakeProbe, FakeTranscriber};
+use voltip_core::dictation::{DictationPorts, ForegroundProbe, Transcriber};
+use voltip_core::{
+ AppCore, CoreCommand, CoreConfig, CoreEvent, CoreHandle, DictationPhase, EdgeSource, HistoryEntry, LearnNotice, LearnOutcome, Modifier, OverlayPlacement,
+ ResolvedEngines, SETTINGS_FILE_NAME, Settings, SettingsStore,
+};
+use voltip_identity::MemorySecretStore;
+
+const STEP: Duration = Duration::from_secs(10);
+/// The notice's stay in these tests.
+const DWELL: Duration = Duration::from_millis(400);
+/// What the fake recogniser hears; inserted as it is (no AI clean-up configured).
+const HEARD: &str = "我在用 Quinn for max 做测试";
+/// What the user corrected it to in the application.
+const FIXED: &str = "我在用 Qwen 4 max 做测试";
+
+struct Node {
+ handle: CoreHandle,
+ events: mpsc::Receiver,
+ injector: Arc,
+ _dir: tempfile::TempDir,
+}
+
+fn start(injector: FakeInjector, probe: Option>, result_cards: bool) -> Node {
+ let dir = tempfile::tempdir().unwrap();
+ if !dir.path().join(SETTINGS_FILE_NAME).exists() {
+ SettingsStore::new(dir.path())
+ .save(&Settings { relay_enabled: false, engines: voltip_core::dictation::fakes::fake_engines(), ..Settings::default() })
+ .unwrap();
+ }
+ let injector = Arc::new(injector);
+ let transcriber = Arc::new(FakeTranscriber::ok(HEARD));
+ let ports = DictationPorts {
+ audio: Arc::new(FakeAudio::speech()),
+ injector: injector.clone(),
+ factory: Arc::new(move |_: &ResolvedEngines| (transcriber.clone() as Arc, None)),
+ models: None,
+ streaming: None,
+ probe,
+ service_probe: None,
+ segmenter: None,
+ };
+ let mut cfg = CoreConfig::new(dir.path().to_path_buf());
+ cfg.default_device_name = "Learn Test".into();
+ cfg.result_cards = result_cards;
+ cfg.learn_notice_dwell = DWELL;
+ let (handle, events) = AppCore::start_with(cfg, Arc::new(MemorySecretStore::new()), ports).unwrap();
+ Node { handle, events, injector, _dir: dir }
+}
+
+async fn wait(node: &mut Node, mut pick: impl FnMut(&CoreEvent) -> Option) -> T {
+ loop {
+ let ev = tokio::time::timeout(STEP, node.events.recv()).await.expect("event within 10 s").expect("core alive");
+ if let Some(v) = pick(&ev) {
+ return v;
+ }
+ }
+}
+
+async fn ready(node: &mut Node) {
+ wait(node, |e| matches!(e, CoreEvent::Ready { .. }).then_some(())).await;
+}
+
+/// The next learn notice event.
+async fn notice(node: &mut Node) -> Option {
+ wait(node, |e| if let CoreEvent::LearnNotice(n) = e { Some(n.clone()) } else { None }).await
+}
+
+/// No learn notice event within `within` (other events are drained).
+async fn no_notice(node: &mut Node, within: Duration, what: &str) {
+ let deadline = Instant::now() + within;
+ loop {
+ let left = deadline.saturating_duration_since(Instant::now());
+ if left.is_zero() {
+ return;
+ }
+ match tokio::time::timeout(left, node.events.recv()).await {
+ Ok(Some(CoreEvent::LearnNotice(n))) => panic!("{what}: {n:?}"),
+ Ok(Some(_)) => {}
+ Ok(None) => panic!("core stopped"),
+ Err(_) => return,
+ }
+ }
+}
+
+/// One take of [`HEARD`]: its session once it is over.
+async fn dictate(node: &mut Node) -> u64 {
+ node.handle.send(CoreCommand::DictationStart).await.unwrap();
+ let session = wait(node, |e| match e {
+ CoreEvent::Dictation(s) if matches!(s.phase, DictationPhase::Listening { .. }) => Some(s.session),
+ _ => None,
+ })
+ .await;
+ node.handle.send(CoreCommand::DictationStop).await.unwrap();
+ wait(node, |e| matches!(e, CoreEvent::Dictation(s) if s.phase.is_terminal()).then_some(())).await;
+ session
+}
+
+async fn idle(node: &mut Node) {
+ wait(node, |e| matches!(e, CoreEvent::Dictation(s) if s.phase == DictationPhase::Idle).then_some(())).await;
+}
+
+async fn learn(node: &Node) {
+ node.handle.send(CoreCommand::LearnSelection { source: EdgeSource::Hotkey }).await.unwrap();
+}
+
+async fn history_with(node: &mut Node, pred: impl Fn(&HistoryEntry) -> bool) -> HistoryEntry {
+ wait(node, |e| match e {
+ CoreEvent::History { recent, .. } => recent.iter().find(|e| pred(e)).cloned(),
+ _ => None,
+ })
+ .await
+}
+
+/// docs/dictation.md §35: the 从选中文字学习 hotkey is unassigned by default, validated and
+/// canonicalised like the others, never one of the other three chords (and they are never it).
+#[tokio::test]
+async fn the_learn_hotkey_is_one_of_four_distinct_chords() {
+ let mut node = start(FakeInjector::paste(), None, false);
+ let settings = wait(&mut node, |e| if let CoreEvent::Ready { settings, .. } = e { Some(settings.clone()) } else { None }).await;
+ assert_eq!(settings.learn_hotkey, None, "unassigned by default");
+ node.handle.send(CoreCommand::SetCopyLastHotkey(Some("Ctrl+Shift+V".into()))).await.unwrap();
+ node.handle.send(CoreCommand::SetLearnHotkey(Some("alt + control + l".into()))).await.unwrap();
+ let s = wait(&mut node, |e| if let CoreEvent::Settings(s) = e { s.learn_hotkey.clone().map(|_| s.clone()) } else { None }).await;
+ assert_eq!(s.learn_hotkey.as_deref(), Some("Ctrl+Alt+L"), "canonical form");
+ for (cmd, needle) in [
+ (CoreCommand::SetLearnHotkey(Some("Ctrl+Alt+Space".into())), "已用作听写快捷键"),
+ (CoreCommand::SetLearnHotkey(Some("Ctrl+Alt+E".into())), "已用作「编辑选中文本」的快捷键"),
+ (CoreCommand::SetLearnHotkey(Some("Ctrl+Shift+V".into())), "已用作「复制上一条结果」的快捷键"),
+ (CoreCommand::SetLearnHotkey(Some("L".into())), "至少需要一个修饰键"),
+ (CoreCommand::SetHotkey("Ctrl+Alt+L".into()), "已用作「从选中文字学习」的快捷键"),
+ (CoreCommand::SetEditHotkey(Some("Ctrl+Alt+L".into())), "已用作「从选中文字学习」的快捷键"),
+ (CoreCommand::SetCopyLastHotkey(Some("Ctrl+Alt+L".into())), "已用作「从选中文字学习」的快捷键"),
+ ] {
+ node.handle.send(cmd).await.unwrap();
+ let message = wait(&mut node, |e| if let CoreEvent::Error(m) = e { Some(m.clone()) } else { None }).await;
+ assert!(message.contains(needle), "{message}");
+ }
+ node.handle.send(CoreCommand::SetLearnHotkey(None)).await.unwrap();
+ let s = wait(&mut node, |e| if let CoreEvent::Settings(s) = e { s.learn_hotkey.is_none().then(|| s.clone()) } else { None }).await;
+ assert_eq!(s.learn_hotkey, None);
+}
+
+/// docs/dictation.md §35: the selection corrects the take; the correction is kept with the entry,
+/// the notice waits while the take's result is on the pill, offers the pair, puts it in the
+/// dictionary and takes it back, and goes after its stay. The copy went out with the shortcut's
+/// modifiers held.
+#[tokio::test]
+async fn a_selection_corrects_the_take_and_the_notice_offers_its_pair() {
+ let mut node = start(FakeInjector::paste().with_selection(FIXED), None, false);
+ ready(&mut node).await;
+ node.handle.send(CoreCommand::SetLearnHotkey(Some("Ctrl+Alt+L".into()))).await.unwrap();
+ dictate(&mut node).await;
+ // The take's 已插入 is still on the pill: the notice waits. The correction is kept first.
+ learn(&node).await;
+ let entry = history_with(&mut node, |e| e.corrected.is_some()).await;
+ assert_eq!(entry.corrected.as_ref().unwrap().text, FIXED);
+ assert_eq!(entry.text, HEARD, "the inserted text stays");
+ let waiting = notice(&mut node).await.expect("a notice");
+ assert!(!waiting.shown, "behind the take's result: {waiting:?}");
+ let LearnOutcome::Learned { pairs, safe } = &waiting.outcome else { panic!("{waiting:?}") };
+ assert_eq!(pairs.iter().map(|p| (p.heard.as_str(), p.polished.as_str())).collect::>(), [("Quinn for", "Qwen 4")]);
+ assert!(safe);
+ assert_eq!(pairs[0].history_id, entry.id);
+ assert_eq!(node.injector.copies(), [vec![Modifier::Ctrl, Modifier::Alt]], "the shortcut's modifiers are released first");
+ idle(&mut node).await;
+ let shown = notice(&mut node).await.expect("shown once the pill is idle");
+ assert!(shown.shown && shown.id == waiting.id);
+
+ // The dictionary changes first, then the notice says so.
+ node.handle.send(CoreCommand::LearnNoticeAccept { id: shown.id }).await.unwrap();
+ let entries = wait(&mut node, |e| if let CoreEvent::Dictionary(d) = e { Some(d.clone()) } else { None }).await;
+ assert_eq!(entries.iter().map(|e| (e.term.as_str(), e.heard_as.clone())).collect::>(), [("Qwen 4", vec!["Quinn for".to_owned()])]);
+ let accepted = notice(&mut node).await.expect("the notice stays");
+ let added = accepted.accepted.clone().expect("加入词典 ran");
+ assert_eq!((added.added, added.refused), (1, 0));
+
+ node.handle.send(CoreCommand::LearnNoticeUndo { id: shown.id }).await.unwrap();
+ let entries = wait(&mut node, |e| if let CoreEvent::Dictionary(d) = e { Some(d.clone()) } else { None }).await;
+ assert!(entries.is_empty(), "{entries:?}");
+ let undone = notice(&mut node).await.expect("the notice stays");
+ assert_eq!(undone.undone, Some(voltip_core::vocabulary::BatchUndoOutcome::Undone));
+
+ let started = Instant::now();
+ assert_eq!(notice(&mut node).await, None, "gone after its stay");
+ assert!(started.elapsed() >= DWELL - Duration::from_millis(50), "timed from the last button: {:?}", started.elapsed());
+}
+
+/// docs/dictation.md §35: behind a result card the notice waits without a timer and shows, timed
+/// from then, once the card is closed; a take that starts clears it; with the pill off there is
+/// none, and the correction is kept all the same.
+#[tokio::test]
+async fn the_notice_waits_for_a_result_card_goes_with_a_take_and_needs_the_pill() {
+ let mut node = start(FakeInjector::err("denied").with_selection(FIXED), None, true);
+ ready(&mut node).await;
+ let session = dictate(&mut node).await;
+ learn(&node).await;
+ let waiting = notice(&mut node).await.expect("a notice");
+ assert!(!waiting.shown);
+ no_notice(&mut node, DWELL * 2, "no timer while the card is up").await;
+ node.handle.send(CoreCommand::DictationDismiss { session }).await.unwrap();
+ let shown = notice(&mut node).await.expect("shown after the card");
+ assert!(shown.shown);
+ let started = Instant::now();
+ assert_eq!(notice(&mut node).await, None);
+ assert!(started.elapsed() >= DWELL - Duration::from_millis(50), "timed from when it showed: {:?}", started.elapsed());
+
+ learn(&node).await;
+ let LearnNotice { shown: true, outcome: LearnOutcome::Learned { .. }, .. } = notice(&mut node).await.expect("a notice") else { panic!("not shown") };
+ node.handle.send(CoreCommand::DictationStart).await.unwrap();
+ assert_eq!(notice(&mut node).await, None, "a take clears it");
+ node.handle.send(CoreCommand::DictationCancel).await.unwrap();
+ idle(&mut node).await;
+
+ node.handle.send(CoreCommand::SetOverlay(OverlayPlacement::Off)).await.unwrap();
+ wait(&mut node, |e| matches!(e, CoreEvent::Settings(s) if s.overlay == OverlayPlacement::Off).then_some(())).await;
+ learn(&node).await;
+ no_notice(&mut node, Duration::from_millis(500), "no pill, no notice").await;
+}
+
+/// docs/dictation.md §35: what the notice says when there is nothing to learn from.
+#[tokio::test]
+async fn the_notice_says_why_nothing_was_learned() {
+ let outcome = async |injector: FakeInjector, probe: Option>, history: bool, take: bool| {
+ let mut node = start(injector, probe, false);
+ ready(&mut node).await;
+ if !history {
+ node.handle.send(CoreCommand::SetHistory(voltip_core::HistorySettings { enabled: false, keep: 500 })).await.unwrap();
+ wait(&mut node, |e| matches!(e, CoreEvent::Settings(s) if !s.history.enabled).then_some(())).await;
+ }
+ if take {
+ dictate(&mut node).await;
+ idle(&mut node).await;
+ }
+ learn(&node).await;
+ let outcome = notice(&mut node).await.expect("a notice").outcome;
+ (outcome, node.injector.copies().len())
+ };
+ assert_eq!(outcome(FakeInjector::paste().with_selection(FIXED), None, false, false).await, (LearnOutcome::HistoryOff, 0));
+ let terminal: Arc = Arc::new(FakeProbe::app("windowsterminal", "Terminal", None));
+ let in_terminal = FakeInjector::paste().with_selection(FIXED).with_terminals(|id| id == "windowsterminal");
+ assert_eq!(outcome(in_terminal, Some(terminal), true, true).await, (LearnOutcome::Terminal, 0), "no key pressed in a terminal");
+ assert_eq!(outcome(FakeInjector::paste(), None, true, true).await, (LearnOutcome::NoSelection, 1));
+ assert_eq!(outcome(FakeInjector::paste().with_selection("今天天气不错"), None, true, true).await, (LearnOutcome::NoMatch, 1));
+ assert_eq!(outcome(FakeInjector::paste().with_selection(HEARD), None, true, true).await, (LearnOutcome::Unchanged, 1));
+ let long = "字".repeat(8001);
+ assert!(matches!(outcome(FakeInjector::paste().with_selection(&long), None, true, true).await, (LearnOutcome::TooLong { max: 8000 }, 1)));
+}
+
+/// Regression (goal review of PR #260, 2026-11-18): 「查看」 and 「打开设置」 open a page in the main
+/// window and tell the core nothing, so the notice went at its first deadline although the user
+/// had just pressed a button (D3: every button starts the 8 seconds again). Now they keep the
+/// notice (`LearnNoticeKeep`), as 加入词典 and 撤销 do; another notice's id changes nothing.
+#[tokio::test]
+async fn regression_view_and_open_settings_start_the_notices_stay_again() {
+ let mut node = start(FakeInjector::paste().with_selection(FIXED), None, false);
+ ready(&mut node).await;
+ dictate(&mut node).await;
+ idle(&mut node).await;
+ learn(&node).await;
+ let shown = notice(&mut node).await.expect("a notice");
+ assert!(shown.shown);
+ // Pressed late in the stay: the notice is there a whole stay after it.
+ tokio::time::sleep(DWELL * 3 / 4).await;
+ node.handle.send(CoreCommand::LearnNoticeKeep { id: shown.id + 1 }).await.unwrap();
+ node.handle.send(CoreCommand::LearnNoticeKeep { id: shown.id }).await.unwrap();
+ let pressed = Instant::now();
+ let kept = notice(&mut node).await.expect("the notice stays");
+ assert_eq!(kept, shown, "nothing on it changes");
+ assert_eq!(notice(&mut node).await, None, "gone after its stay");
+ assert!(pressed.elapsed() >= DWELL - Duration::from_millis(50), "timed from the button: {:?}", pressed.elapsed());
+}
+
+/// Regression (goal review of PR #260, 2026-11-18): on macOS the voice edit's terminal table is
+/// empty (Cmd+C is safe there), and the learn task asked that table, so a selection in Terminal or
+/// iTerm2 was copied and compared. Learning asks the port's own question, which names macOS's
+/// terminals: no key is pressed there.
+#[tokio::test]
+async fn regression_a_terminal_the_voice_edit_allows_is_still_not_learned_from() {
+ let terminal: Arc = Arc::new(FakeProbe::app("com.apple.terminal", "Terminal", None));
+ // The voice edit's table (macOS: none) says no; learning's says yes.
+ let injector = FakeInjector::paste().with_selection(FIXED).with_terminals(|_| false).with_program_output(|id| id == "com.apple.terminal");
+ let mut node = start(injector, Some(terminal), false);
+ ready(&mut node).await;
+ dictate(&mut node).await;
+ idle(&mut node).await;
+ learn(&node).await;
+ let outcome = notice(&mut node).await.expect("a notice").outcome;
+ assert_eq!(outcome, LearnOutcome::Terminal);
+ assert!(node.injector.copies().is_empty(), "no key pressed in the terminal: {:?}", node.injector.copies());
+}
diff --git a/crates/voltip-focus/tests/focus_macos.rs b/crates/voltip-focus/tests/focus_macos.rs
index f144cc35..f671e41d 100644
--- a/crates/voltip-focus/tests/focus_macos.rs
+++ b/crates/voltip-focus/tests/focus_macos.rs
@@ -1,6 +1,8 @@
//! The insert check's Accessibility reader against real macOS controls (docs/dictation.md §28): a
//! paste into the test's own window, whose text view can be selected but not edited, leaves it
-//! `not_written`; a paste into a TextEdit document is `written`. AppKit wants the main thread, so
+//! `not_written`; a paste into a TextEdit document is `written`. Then the copy that reads the
+//! selection (§19, 从选中文字学习 §35): TextEdit's selection comes back with Cmd+C, and the
+//! pasteboard holds what it held before. AppKit wants the main thread, so
//! this test has its own `main` (`harness = false`): the main thread runs the application, the
//! checks run on another thread. It pastes the way Voltip does (the pasteboard and Cmd+V) into
//! windows it brings to the front, and needs the Accessibility permission for the test binary, so
@@ -23,7 +25,7 @@ mod mac {
};
use objc2_foundation::{NSPoint, NSRect, NSSize, NSString};
use voltip_focus::{Expected, Reader, Settled, Watch, macos as ax};
- use voltip_inject::{Injector as _, PasteOptions};
+ use voltip_inject::{ClipboardPort as _, CopyOptions, Injector as _, Modifier, PasteOptions, SelectionSource as _, SystemClipboard, system_selection};
use voltip_platform::HostOs;
use voltip_platform::insert_check::rules::InsertCheck;
@@ -42,6 +44,36 @@ mod mac {
fn AXIsProcessTrusted() -> u8;
}
+ #[link(name = "CoreGraphics", kind = "framework")]
+ unsafe extern "C" {
+ fn CGEventCreateKeyboardEvent(source: *const std::ffi::c_void, keycode: u16, down: bool) -> *mut std::ffi::c_void;
+ fn CGEventSetFlags(event: *mut std::ffi::c_void, flags: u64);
+ fn CGEventPost(tap: u32, event: *mut std::ffi::c_void);
+ }
+
+ #[link(name = "CoreFoundation", kind = "framework")]
+ unsafe extern "C" {
+ fn CFRelease(cf: *const std::ffi::c_void);
+ }
+
+ /// Cmd+A in the application in front (`kVK_ANSI_A` with `kCGEventFlagMaskCommand`, posted at
+ /// `kCGHIDEventTap`): TextEdit selects the whole document.
+ fn select_all() {
+ const KVK_ANSI_A: u16 = 0x00;
+ const COMMAND: u64 = 0x0010_0000;
+ const HID_EVENT_TAP: u32 = 0;
+ for down in [true, false] {
+ // SAFETY: a keyboard event from the default source, flagged, posted and released.
+ unsafe {
+ let event = CGEventCreateKeyboardEvent(std::ptr::null(), KVK_ANSI_A, down);
+ assert!(!event.is_null(), "CGEventCreateKeyboardEvent");
+ CGEventSetFlags(event, COMMAND);
+ CGEventPost(HID_EVENT_TAP, event);
+ CFRelease(event);
+ }
+ }
+ }
+
/// The frontmost application: its process id and bundle identifier.
fn frontmost() -> Option<(i32, String)> {
let app = NSWorkspace::sharedWorkspace().frontmostApplication()?;
@@ -121,6 +153,18 @@ mod mac {
paste();
assert_eq!(watch.settle(WATCH), Settled::sure(InsertCheck::Written), "TextEdit");
println!("focus_macos: TextEdit: written");
+
+ // docs/dictation.md §35 (the copy of §19): 从选中文字学习 reads TextEdit's selection with
+ // Cmd+C — the shortcut's modifiers do not mix in, enigo posts its own flags — and puts back
+ // what the pasteboard held.
+ select_all();
+ let pasteboard = SystemClipboard::new();
+ pasteboard.write_text("SENTINEL").expect("the pasteboard");
+ let copier = system_selection(CopyOptions { timeout: Duration::from_secs(1), ..CopyOptions::default() });
+ let copied = copier.copy_selection(&[Modifier::Control, Modifier::Alt]).expect("the copy went out");
+ assert_eq!(copied.as_deref(), Some(TYPED), "TextEdit's selection");
+ assert_eq!(pasteboard.read_text().expect("the pasteboard").as_deref(), Some("SENTINEL"), "the previous pasteboard is back");
+ println!("focus_macos: TextEdit's selection: copied, the pasteboard put back");
drop(document);
}
diff --git a/crates/voltip-focus/tests/focus_windows.rs b/crates/voltip-focus/tests/focus_windows.rs
index d811ffab..4d4f0c7c 100644
--- a/crates/voltip-focus/tests/focus_windows.rs
+++ b/crates/voltip-focus/tests/focus_windows.rs
@@ -1,9 +1,11 @@
//! The insert check's UI Automation reader against real Windows controls (docs/dictation.md §28):
//! a paste into Notepad is `written`; the same paste into a read-only EDIT of this test's own
//! window leaves it `not_written`; the focus moving to the window's other EDIT is `unconfirmed`.
-//! It pastes the way Voltip does (the clipboard and Ctrl+V) into windows it brings to the front,
-//! so it is ignored: CI runs it on the windows-2025 desktop (`hooks-windows`), never on a
-//! computer someone is using:
+//! And the copy that reads the selection (§19, 从选中文字学习 §35): Notepad's selection comes
+//! back while the shortcut's modifiers are still held, and the clipboard holds what it held.
+//! It pastes and copies the way Voltip does (the clipboard, Ctrl+V and Ctrl+Insert) in windows it
+//! brings to the front, so it is ignored: CI runs it on the windows-2025 desktop (`hooks-windows`),
+//! never on a computer someone is using:
//! `cargo test -p voltip-focus --test focus_windows -- --ignored --test-threads=1 --nocapture`.
// The test's own window is Win32 FFI (windows-sys); UI Automation's focus calls are COM.
@@ -16,7 +18,7 @@ use std::thread::JoinHandle;
use std::time::{Duration, Instant};
use voltip_focus::{Expected, Reader, Settled, UnconfirmedWhy, Watch, windows as uia};
-use voltip_inject::{Injector as _, PasteOptions};
+use voltip_inject::{ClipboardPort as _, CopyOptions, Injector as _, Modifier, PasteOptions, SelectionSource as _, SystemClipboard, system_selection};
use voltip_platform::HostOs;
use voltip_platform::insert_check::rules::InsertCheck;
use windows::Win32::Foundation::HWND;
@@ -25,7 +27,10 @@ use windows::Win32::UI::Accessibility::{CUIAutomation8, IUIAutomation};
use windows_sys::Win32::Foundation::RECT;
use windows_sys::Win32::System::LibraryLoader::GetModuleHandleW;
use windows_sys::Win32::System::Threading::GetCurrentThreadId;
-use windows_sys::Win32::UI::Input::KeyboardAndMouse::{INPUT, INPUT_0, INPUT_MOUSE, MOUSEEVENTF_LEFTDOWN, MOUSEEVENTF_LEFTUP, MOUSEINPUT, SendInput};
+use windows_sys::Win32::UI::Input::KeyboardAndMouse::{
+ INPUT, INPUT_0, INPUT_KEYBOARD, INPUT_MOUSE, KEYBDINPUT, KEYEVENTF_KEYUP, MOUSEEVENTF_LEFTDOWN, MOUSEEVENTF_LEFTUP, MOUSEINPUT, SendInput, VIRTUAL_KEY,
+ VK_A, VK_CONTROL, VK_MENU,
+};
use windows_sys::Win32::UI::WindowsAndMessaging::{
CreateWindowExW, DefWindowProcW, DestroyWindow, DispatchMessageW, ES_AUTOHSCROLL, ES_READONLY, FindWindowW, GetForegroundWindow, GetMessageW,
GetWindowRect, GetWindowThreadProcessId, HWND_TOPMOST, MSG, PostThreadMessageW, RegisterClassW, SWP_NOMOVE, SWP_NOSIZE, SetCursorPos, SetWindowPos,
@@ -190,9 +195,17 @@ struct Notepad {
impl Notepad {
fn open() -> Self {
+ let class = wide("Notepad");
+ let until = Instant::now() + WAIT;
+ // The Notepad an earlier test ended may not have closed its window yet; this test must not
+ // find that one.
+ // SAFETY: a class-name lookup.
+ while unsafe { FindWindowW(class.as_ptr(), std::ptr::null()) } as isize != 0 {
+ assert!(Instant::now() < until, "a Notepad window from before is still open");
+ std::thread::sleep(Duration::from_millis(100));
+ }
// Dropped on every path, the window found or not: `Drop` ends and reaps the process.
let mut notepad = Self { started: Command::new("notepad.exe").spawn().expect("notepad.exe"), window: 0 };
- let class = wide("Notepad");
let until = Instant::now() + WAIT;
while notepad.window == 0 {
assert!(Instant::now() < until, "no Notepad window");
@@ -239,6 +252,37 @@ fn paste_into(top: isize) {
voltip_inject::system_paste_injector(PasteOptions::for_os("windows")).inject(TYPED).expect("the paste went out");
}
+/// Press (`up` false) or release (`up` true) the keys `vks`, in order, as a keyboard would.
+fn keys(vks: &[VIRTUAL_KEY], up: bool) {
+ let flags = if up { KEYEVENTF_KEYUP } else { 0 };
+ let inputs: Vec = vks
+ .iter()
+ .map(|&vk| INPUT { r#type: INPUT_KEYBOARD, Anonymous: INPUT_0 { ki: KEYBDINPUT { wVk: vk, wScan: 0, dwFlags: flags, time: 0, dwExtraInfo: 0 } } })
+ .collect();
+ // SAFETY: an array of INPUTs that outlives the call.
+ let sent = unsafe { SendInput(inputs.len() as u32, inputs.as_ptr(), std::mem::size_of:: () as i32) };
+ assert_eq!(sent as usize, inputs.len(), "the keys {vks:?} (up: {up})");
+}
+
+/// Keys this test holds down, released however the test ends: a key left down would stay down
+/// for the rest of the job.
+struct Held(Vec);
+
+impl Held {
+ fn down(vks: &[VIRTUAL_KEY]) -> Self {
+ keys(vks, false);
+ Self(vks.to_vec())
+ }
+}
+
+impl Drop for Held {
+ fn drop(&mut self) {
+ let mut vks = std::mem::take(&mut self.0);
+ vks.reverse();
+ keys(&vks, true);
+ }
+}
+
#[test]
#[ignore = "pastes into windows it brings to the front: CI's windows-2025 desktop only"]
fn a_paste_lands_in_notepad_a_read_only_edit_stays_and_another_edit_takes_the_focus() {
@@ -262,3 +306,30 @@ fn a_paste_lands_in_notepad_a_read_only_edit_stays_and_another_edit_takes_the_fo
click(own.other, own.top, "the other EDIT");
assert_eq!(watch.settle(WATCH), Settled::unconfirmed(UnconfirmedWhy::ControlChanged), "the focus moved");
}
+
+/// docs/dictation.md §35 (the copy of §19): 从选中文字学习 reads Notepad's selection the way Voltip
+/// does, with Ctrl+Insert while the user still holds Ctrl+Alt of the shortcut (`Alt` is let go
+/// after `Ctrl` went down, so no menu bar opens), and puts back what the clipboard held.
+#[test]
+#[ignore = "copies out of windows it brings to the front: CI's windows-2025 desktop only"]
+fn the_copy_reads_notepads_selection_with_the_shortcut_held_and_puts_the_clipboard_back() {
+ let focuser = Focuser::new();
+ let reader = Reader::new(HostOs::Windows, uia::open);
+ let notepad = Notepad::open();
+ focuser.focus(notepad.window, notepad.window, "Notepad");
+ let watch = wait_watch(&reader, "notepad");
+ paste_into(notepad.window);
+ assert_eq!(watch.settle(WATCH), Settled::sure(InsertCheck::Written), "the text is in Notepad");
+ drop(Held::down(&[VK_CONTROL, VK_A]));
+
+ let clipboard = SystemClipboard::new();
+ clipboard.write_text("SENTINEL").expect("the clipboard");
+ let copier = system_selection(CopyOptions { timeout: Duration::from_secs(1), ..CopyOptions::default() });
+ // SAFETY: plain query.
+ assert_eq!(unsafe { GetForegroundWindow() } as isize, notepad.window, "the copy would go elsewhere");
+ let held = Held::down(&[VK_CONTROL, VK_MENU]);
+ let copied = copier.copy_selection(&[Modifier::Control, Modifier::Alt]);
+ drop(held);
+ assert_eq!(copied.expect("the copy went out").as_deref(), Some(TYPED), "Notepad's selection");
+ assert_eq!(clipboard.read_text().expect("the clipboard").as_deref(), Some("SENTINEL"), "the previous clipboard is back");
+}
diff --git a/crates/voltip-inject/src/selection.rs b/crates/voltip-inject/src/selection.rs
index fb8cc81c..152ed346 100644
--- a/crates/voltip-inject/src/selection.rs
+++ b/crates/voltip-inject/src/selection.rs
@@ -4,7 +4,7 @@
//! ordering, what counts as "nothing selected", when the restore is skipped) live here over the
//! same two ports as the paste ([`ClipboardPort`], [`KeystrokePort`]), so they run headless.
-use std::sync::Arc;
+use std::sync::{Arc, Mutex, PoisonError};
use std::time::{Duration, Instant};
use crate::InjectError;
@@ -12,6 +12,11 @@ use crate::clip::ClipSnapshot;
use crate::injector::{ClipboardPort, KeystrokePort};
use crate::toolchain::{Chord, Key, Modifier};
+/// One selection copy at a time in this process: each saves, clears and restores the one
+/// clipboard, so two at once (the learn shortcut pressed twice, a learn and a voice edit) would
+/// save each other's cleared clipboard and read each other's restore as a selection.
+static COPYING: Mutex<()> = Mutex::new(());
+
/// How long the copy waits for the application to put the selection on the clipboard.
pub const COPY_TIMEOUT: Duration = Duration::from_millis(250);
/// How often the clipboard is read while waiting.
@@ -148,6 +153,8 @@ impl ClipboardSelection {
impl SelectionSource for ClipboardSelection {
fn copy_selection(&self, held: &[Modifier]) -> Result, InjectError> {
+ // Held from the save to the restore; a copy that panicked leaves nothing to protect.
+ let _one = COPYING.lock().unwrap_or_else(PoisonError::into_inner);
let previous = match self.clipboard.snapshot() {
Ok(previous) => Some(previous),
Err(err) => {
@@ -461,4 +468,61 @@ mod tests {
assert!(matches!(&err, InjectError::Keystroke(m) if m.contains("cannot press a chord")), "{err:?}");
assert_eq!(clipboard.current().as_deref(), Some("previous"));
}
+
+ /// An application whose copy waits for `go` before it puts `selection` on the clipboard, and
+ /// says on `pressed` that the chord arrived (one copy at a time: the test holds it in flight).
+ struct HeldApp {
+ clipboard: Arc,
+ selection: Option,
+ pressed: std::sync::mpsc::Sender<()>,
+ go: Mutex>,
+ }
+
+ impl KeystrokePort for HeldApp {
+ fn deliver(&self, _: Chord, _: &str) -> Result {
+ unreachable!("the copy never pastes")
+ }
+
+ fn press_chord(&self, _: Chord, _: &[Modifier]) -> Result {
+ let _ = self.pressed.send(());
+ if let Some(selection) = &self.selection {
+ // Held until the test lets it go (bounded: a broken test cannot hang the run).
+ let _ = self.go.lock().unwrap().recv_timeout(Duration::from_secs(5));
+ self.clipboard.write_text(selection).unwrap();
+ }
+ Ok(Delivered { tool: "fake".into(), delivery: Delivery::Chord })
+ }
+ }
+
+ /// Regression (goal review of PR #260, 2026-11-18): two copies at once — the learn shortcut
+ /// pressed twice, or a learn and a voice edit — each saved, cleared and restored the one
+ /// clipboard: the second saved the first's cleared clipboard, took the user's text the first
+ /// put back for its selection, and finally emptied the clipboard. One copy runs at a time now:
+ /// the second waits until the first has put the clipboard back.
+ #[test]
+ fn regression_two_copies_at_once_neither_read_nor_lose_the_users_clipboard() {
+ let clipboard = MemoryClipboard::holding("用户原来的剪贴板");
+ let (pressed_a, in_a) = std::sync::mpsc::channel();
+ let (go_a, held_a) = std::sync::mpsc::channel();
+ let app_a =
+ Arc::new(HeldApp { clipboard: clipboard.clone(), selection: Some("选中的一段话".into()), pressed: pressed_a, go: Mutex::new(held_a) });
+ let (pressed_b, in_b) = std::sync::mpsc::channel();
+ let (_go_b, held_b) = std::sync::mpsc::channel();
+ // The second copy's application has nothing selected.
+ let app_b = Arc::new(HeldApp { clipboard: clipboard.clone(), selection: None, pressed: pressed_b, go: Mutex::new(held_b) });
+ let first = ClipboardSelection::with_ports(clipboard.clone(), app_a, copy_chord_for("linux"), fast());
+ let second = ClipboardSelection::with_ports(clipboard.clone(), app_b, copy_chord_for("linux"), fast());
+ let a = std::thread::spawn(move || first.copy_selection(&[]));
+ in_a.recv_timeout(Duration::from_secs(5)).expect("the first copy pressed its chord");
+ let b = std::thread::spawn(move || second.copy_selection(&[]));
+ // While the first copy is in flight the second must not reach its chord.
+ let overlapped = in_b.recv_timeout(Duration::from_millis(300)).is_ok();
+ go_a.send(()).unwrap();
+ let got_a = a.join().unwrap().unwrap();
+ let got_b = b.join().unwrap().unwrap();
+ assert!(!overlapped, "the second copy ran while the first held the clipboard");
+ assert_eq!(got_a.as_deref(), Some("选中的一段话"));
+ assert_eq!(got_b, None, "nothing was selected for the second copy");
+ assert_eq!(clipboard.current().as_deref(), Some("用户原来的剪贴板"), "the user's clipboard is back");
+ }
}
diff --git a/crates/voltip-platform/src/insert_check.rs b/crates/voltip-platform/src/insert_check.rs
index aea3d16d..975799ae 100644
--- a/crates/voltip-platform/src/insert_check.rs
+++ b/crates/voltip-platform/src/insert_check.rs
@@ -115,10 +115,50 @@ pub fn skips(os: HostOs, app_id: &str) -> bool {
!id.is_empty() && skipped_apps(os).any(|skipped| skipped == id)
}
+/// `app_id` (as the probe reports it, normalised again here) is a terminal on `os`, macOS's
+/// included: its selection is program output, so 从选中文字学习 copies nothing there
+/// (docs/dictation.md §35). The voice edit's table (`foreground::terminal_ids`) has none on macOS,
+/// where Cmd+C is safe; the text is still not a dictation.
+pub fn holds_program_output(os: HostOs, app_id: &str) -> bool {
+ let id = normalize_app_id(app_id);
+ let terminals: &[&str] = match os {
+ HostOs::Windows => &WINDOWS_TERMINALS,
+ HostOs::Linux => &LINUX_TERMINALS,
+ HostOs::Macos => &MACOS_TERMINALS,
+ HostOs::Other => &[],
+ };
+ !id.is_empty() && terminals.contains(&id.as_str())
+}
+
#[cfg(test)]
mod tests {
use super::*;
+ /// Regression (goal review of PR #260, 2026-11-18): 从选中文字学习 asked the voice edit's
+ /// table, which has no macOS terminal, so Terminal's selection was copied. Its own table names
+ /// every host's terminals and nothing else.
+ #[test]
+ fn regression_every_hosts_terminals_hold_program_output() {
+ for (os, id) in [
+ (HostOs::Macos, "com.apple.Terminal"),
+ (HostOs::Macos, "com.googlecode.iterm2"),
+ (HostOs::Windows, "WindowsTerminal.exe"),
+ (HostOs::Linux, "gnome-terminal-server"),
+ ] {
+ assert!(holds_program_output(os, id), "{os:?} {id}");
+ }
+ assert!(!crate::foreground::is_terminal(HostOs::Macos, "com.apple.Terminal"), "the voice edit still allows macOS's terminals");
+ for (os, id) in [
+ (HostOs::Macos, "com.apple.TextEdit"),
+ (HostOs::Windows, "notepad.exe"),
+ (HostOs::Macos, "com.microsoft.rdc.macos"),
+ (HostOs::Other, "xterm"),
+ (HostOs::Linux, ""),
+ ] {
+ assert!(!holds_program_output(os, id), "{os:?} {id}");
+ }
+ }
+
/// docs/dictation.md §28: terminals and remote screens are never read, on every host; an
/// ordinary app is.
#[test]
diff --git a/crates/voltip-tauri-bridge/src/lib.rs b/crates/voltip-tauri-bridge/src/lib.rs
index 6af17547..38127003 100644
--- a/crates/voltip-tauri-bridge/src/lib.rs
+++ b/crates/voltip-tauri-bridge/src/lib.rs
@@ -146,6 +146,12 @@ pub enum UiCommand {
/// Chord text or `null`.
hotkey: Option,
},
+ /// 从选中文字学习 hotkey (docs/dictation.md §35): a chord, or `null` for none (the default);
+ /// validated and persisted like the dictation hotkey, never one of the other three chords.
+ SettingsSetLearnHotkey {
+ /// Chord text or `null`.
+ hotkey: Option,
+ },
/// Lone-key trigger (docs/dictation.md §13.1): `right_ctrl` … `mouse_forward`, or `null` to
/// switch it off; persisted, the desktop shell watches the key when the `settings` event arrives.
SettingsSetSoloKey {
@@ -250,6 +256,26 @@ pub enum UiCommand {
/// `DictationStatus.session` of the take whose card it is.
session: u64,
},
+ /// The learn notice's 加入词典 (docs/dictation.md §35).
+ LearnNoticeAccept {
+ /// `LearnNotice.id`.
+ id: u64,
+ },
+ /// The learn notice's 撤销.
+ LearnNoticeUndo {
+ /// `LearnNotice.id`.
+ id: u64,
+ },
+ /// The learn notice's ×.
+ LearnNoticeDismiss {
+ /// `LearnNotice.id`.
+ id: u64,
+ },
+ /// The learn notice's 查看 or 打开设置: it stays its whole time again.
+ LearnNoticeKeep {
+ /// `LearnNotice.id`.
+ id: u64,
+ },
/// A key transition for the activation machine (docs/dictation.md §13): the desktop shell sends
/// one per hotkey press / release, the CLI one per `voltip --toggle`.
HotkeyEdge {
@@ -338,6 +364,11 @@ pub enum UiCommand {
/// New flag.
starred: bool,
},
+ /// Forget the user's correction of an entry (the history detail's 移除, docs/dictation.md §35).
+ HistoryClearCorrected {
+ /// UUID.
+ id: String,
+ },
/// 用 AI 预设处理 (docs/dictation.md §22): the entry's text through a preset in parts; progress
/// and the end arrive as `history_process` events with `request_id`.
HistoryProcess {
@@ -665,6 +696,7 @@ impl UiCommand {
Self::SettingsSetHotkey { hotkey } => CoreCommand::SetHotkey(hotkey),
Self::SettingsSetEditHotkey { hotkey } => CoreCommand::SetEditHotkey(hotkey),
Self::SettingsSetCopyLastHotkey { hotkey } => CoreCommand::SetCopyLastHotkey(hotkey),
+ Self::SettingsSetLearnHotkey { hotkey } => CoreCommand::SetLearnHotkey(hotkey),
Self::SettingsSetSoloKey { key } => CoreCommand::SetSoloKey(key),
Self::SettingsSetMicrophone { device } => CoreCommand::SetMicrophone(device),
Self::SettingsSetRecording { recording } => CoreCommand::SetRecording(recording),
@@ -697,6 +729,10 @@ impl UiCommand {
Self::DictationStop => CoreCommand::DictationStop,
Self::DictationCancel => CoreCommand::DictationCancel,
Self::DictationDismiss { session } => CoreCommand::DictationDismiss { session },
+ Self::LearnNoticeAccept { id } => CoreCommand::LearnNoticeAccept { id },
+ Self::LearnNoticeUndo { id } => CoreCommand::LearnNoticeUndo { id },
+ Self::LearnNoticeDismiss { id } => CoreCommand::LearnNoticeDismiss { id },
+ Self::LearnNoticeKeep { id } => CoreCommand::LearnNoticeKeep { id },
Self::HotkeyEdge { pressed, at_ms, source, purpose, chorded } => CoreCommand::HotkeyEdge { pressed, at_ms, source, purpose, chorded },
Self::SettingsSetActivation { activation, hold_threshold_ms, extra_recording_ms } => {
CoreCommand::SetActivation { activation, hold_threshold_ms, extra_recording_ms }
@@ -709,6 +745,7 @@ impl UiCommand {
Self::HistoryDelete { id } => CoreCommand::HistoryDelete(parse_id(&id)?),
Self::HistoryClear => CoreCommand::HistoryClear,
Self::HistoryStar { id, starred } => CoreCommand::HistoryStar(parse_id(&id)?, starred),
+ Self::HistoryClearCorrected { id } => CoreCommand::HistoryClearCorrected(parse_id(&id)?),
Self::HistoryProcess { request_id, id, preset } => CoreCommand::HistoryProcess {
request_id,
id: parse_id(&id)?,
@@ -1117,6 +1154,14 @@ impl Bridge {
}
}
+ /// 从选中文字学习 (docs/dictation.md §35; the hotkey, `--learn-selection`): the core copies the
+ /// selection in front and learns from it; what came of it arrives as `learn_notice`. Not a
+ /// webview command: only the shell's key and command line start it.
+ pub fn learn_selection(&self, source: voltip_core::EdgeSource) -> Result<(), BridgeError> {
+ self.handle.try_send(CoreCommand::LearnSelection { source })?;
+ Ok(())
+ }
+
/// 复制上一条结果 (docs/dictation.md §28; the tray's entry, the hotkey, `--copy-last`): the newest
/// result onto the clipboard. A core that does not answer within `within`, or has stopped,
/// counts as `failed`.
@@ -2023,7 +2068,11 @@ mod tests {
};
let heard = |bridge: &Bridge| ready(bridge.vocabulary_suggestions(None).unwrap()).pairs.into_iter().map(|p| p.heard).collect::>();
let first = ready(bridge.vocabulary_suggestions(None).unwrap());
- assert_eq!(first.pairs.iter().map(|p| p.heard.as_str()).collect::>(), ["维他命", "千问", "非"], "the rule's own change is left out");
+ assert_eq!(
+ first.pairs.iter().map(|p| p.heard.as_str()).collect::>(),
+ ["维他命", "千问", "非书"],
+ "the rule's own change is left out; 非 widened"
+ );
assert_eq!((first.scanned, first.refined, first.skipped, first.total), (3, 3, 0, 3));
let one = ready(bridge.vocabulary_suggestions(Some(1)).unwrap());
assert_eq!((one.pairs.len(), one.total), (1, 3));
@@ -2039,10 +2088,10 @@ mod tests {
};
until(&bridge, &mut rx, |s| s.dictionary.len() == 1).await;
assert_eq!(bridge.state().dictionary[0].source, EntrySource::History { history_id: ids[0] });
- assert_eq!(heard(&bridge), ["千问", "非"]);
+ assert_eq!(heard(&bridge), ["千问", "非书"]);
assert_eq!(bridge.vocabulary_suggestion_undo(undo.id, wait).await.unwrap(), UndoOutcome::Undone);
until(&bridge, &mut rx, |s| s.dictionary.is_empty()).await;
- assert_eq!(heard(&bridge), ["维他命", "千问", "非"]);
+ assert_eq!(heard(&bridge), ["维他命", "千问", "非书"]);
assert_eq!(bridge.vocabulary_suggestion_undo(undo.id, wait).await.unwrap(), UndoOutcome::Expired, "once");
let err = String::from(bridge.vocabulary_suggestion_accept(" ".into(), "Voltip".into(), ids[0], wait).await.unwrap_err());
assert!(err.contains("不能为空"), "{err}");
@@ -2050,18 +2099,18 @@ mod tests {
// The rule changed after the take: that take no longer counts.
bridge.dispatch(UiCommand::RulesUpdate { id: rule_id.to_string(), rule: feishu("非书 → 飞书") }).unwrap();
until(&bridge, &mut rx, |s| s.rules.first().is_some_and(|r| r.updated_at_ms > 1)).await;
- assert_eq!(heard(&bridge), ["维他命", "非"]);
+ assert_eq!(heard(&bridge), ["维他命", "非书"]);
// A take deleted from the history no longer counts.
bridge.dispatch(UiCommand::HistoryDelete { id: ids[0].to_string() }).unwrap();
until(&bridge, &mut rx, |s| s.history_total == 2).await;
- assert_eq!(heard(&bridge), ["非"]);
- // 忽略 and its 撤销.
+ assert_eq!(heard(&bridge), ["非书"]);
+ // 忽略 and its 撤销 (a pair ignored before it was widened hides the widened one).
bridge.dispatch(UiCommand::VocabularySuggestionIgnore { heard: "非".into(), polished: "飞".into() }).unwrap();
until(&bridge, &mut rx, |s| s.vocabulary_ignored.len() == 1).await;
assert!(heard(&bridge).is_empty());
bridge.dispatch(UiCommand::VocabularySuggestionUnignore { heard: "非".into(), polished: "飞".into() }).unwrap();
until(&bridge, &mut rx, |s| s.vocabulary_ignored.is_empty()).await;
- assert_eq!(heard(&bridge), ["非"]);
+ assert_eq!(heard(&bridge), ["非书"]);
assert!(bridge.dispatch(UiCommand::VocabularySuggestionIgnore { heard: "同".into(), polished: "同".into() }).is_err(), "refused here");
// The rules page's hints: a second rule that finds what the first finds.
@@ -2119,8 +2168,8 @@ mod tests {
};
let heard = |bridge: &Bridge| ready(bridge).pairs.into_iter().map(|p| p.heard).collect::>();
let first = ready(&bridge);
- assert_eq!((first.total, first.repeated), (3, 1), "非 → 飞 twice, the other two once");
- assert_eq!(heard(&bridge), ["非", "维他命", "库伯内特斯"]);
+ assert_eq!((first.total, first.repeated), (3, 1), "非书 → 飞书 twice, the other two once");
+ assert_eq!(heard(&bridge), ["非书", "维他命", "库伯内特斯"]);
let wait = Duration::from_secs(20);
let pick = |heard: &str, polished: &str, at: usize| SuggestionPick { heard: heard.into(), polished: polished.into(), history_id: ids[at] };
@@ -2128,11 +2177,11 @@ mod tests {
assert!(accepted.items.iter().all(|i| matches!(i, BatchItem::Accepted { created: true, .. })), "{accepted:?}");
until(&bridge, &mut rx, |s| s.dictionary.len() == 2).await;
assert_eq!(bridge.state().dictionary[1].heard_as, ["库伯内特斯"], "checked and trimmed here");
- assert_eq!(heard(&bridge), ["非"]);
+ assert_eq!(heard(&bridge), ["非书"]);
let undo = accepted.undo.expect("an undo");
assert_eq!(bridge.vocabulary_suggestions_undo(undo, wait).await.unwrap(), BatchUndoOutcome::Undone);
until(&bridge, &mut rx, |s| s.dictionary.is_empty()).await;
- assert_eq!(heard(&bridge), ["非", "维他命", "库伯内特斯"]);
+ assert_eq!(heard(&bridge), ["非书", "维他命", "库伯内特斯"]);
assert_eq!(bridge.vocabulary_suggestions_undo(undo, wait).await.unwrap(), BatchUndoOutcome::Expired, "once");
let pair = |heard: &str, polished: &str| SuggestionPair { heard: heard.into(), polished: polished.into() };
@@ -2144,7 +2193,7 @@ mod tests {
assert_eq!(heard(&bridge), ["库伯内特斯"]);
assert_eq!(bridge.vocabulary_suggestions_undo(undo, wait).await.unwrap(), BatchUndoOutcome::Undone);
until(&bridge, &mut rx, |s| s.vocabulary_ignored.is_empty()).await;
- assert_eq!(heard(&bridge), ["非", "维他命", "库伯内特斯"]);
+ assert_eq!(heard(&bridge), ["非书", "维他命", "库伯内特斯"]);
// Refused here, nothing sent to the core.
let err = String::from(bridge.vocabulary_suggestions_accept(Vec::new(), wait).await.unwrap_err());
diff --git a/crates/voltip-tauri-bridge/tests/contract.rs b/crates/voltip-tauri-bridge/tests/contract.rs
index 6d46e6b9..db24a6ee 100644
--- a/crates/voltip-tauri-bridge/tests/contract.rs
+++ b/crates/voltip-tauri-bridge/tests/contract.rs
@@ -19,7 +19,7 @@ use voltip_core::backup::auto::{AutoBackupFailure, AutoBackupFile, AutoBackupVie
use voltip_core::connectivity::{ConnectivityReport, ConnectivityStatus, PeerCheck, ProbeResult, RelayCheck};
use voltip_core::dictation::{ClipboardCode, FailureCode, InsertCheck, ProcessingStage, Via};
use voltip_core::history::process::ProcessState;
-use voltip_core::history::{ImportedFile, ProcessedText};
+use voltip_core::history::{CorrectedText, CorrectionVia, ImportedFile, ProcessedText};
use voltip_core::import::{ImportFailure, ImportJob, ImportState, ImportsView};
use voltip_core::mcp::{HistoryRange, McpAction, McpActivity, McpClient, McpRead, McpSettings, McpStatus, McpWrite};
use voltip_core::models_location::{ModelsLocationView, ModelsMove, ModelsMoveOutcome};
@@ -31,6 +31,7 @@ use voltip_core::trial::{TrialFailure, TrialResult, TrialView};
use voltip_core::ui::{
GpuDevice, HardwareStatus, HotkeyCapabilities, HotkeyStatus, NetworkStatus, RefineNotice, ServePhase, ServeStatus, UiEvent, UiState, UpdateStatus,
};
+use voltip_core::vocabulary::{BatchUndoOutcome, SuggestionPick};
use voltip_core::{
Activation, AppRef, BuiltIn, BuiltinScene, CAPABILITY_OFFLINE, CAPABILITY_STREAMING, ChineseScript, ClipboardAfter, ContextSharing, DeviceConnection,
DeviceView, DictationPhase, DictationStatus, DictionaryDraft, DictionaryEntry, EditRecord, EngineSettings, EngineStatus, EntrySource, FallbackModel,
@@ -40,7 +41,7 @@ use voltip_core::{
SceneDraft, SceneMatch, SceneOverrides, SceneRef, Segment, ServiceKind, Settings, SoloKey, SoloLoss, SwitchedWindow, TakeContext, TakeKind, ThemeId,
UserSecrets, VocabularyHit, VocabularyHits,
};
-use voltip_core::{EntryOrigin, FailureKind, OriginKind, RelayFailure};
+use voltip_core::{EntryOrigin, FailureKind, LearnNotice, LearnOutcome, NoticeAccepted, OriginKind, RelayFailure};
use voltip_crypto::{PublicKey, SafetyCode};
use voltip_identity::{DeviceIdentityPublic, TrustedDevice};
use voltip_pairing::{FailureReason, PairingState, Snapshot};
@@ -623,6 +624,7 @@ fn history_entries() -> Vec {
preset: Some(PresetRef { id: PresetId::Builtin(BuiltinPreset::Formal), name: "书面语".into() }),
origin: None,
processed: None,
+ corrected: None,
file: None,
// docs/dictation.md §30.1, §30.5: the take's timeline; its recognition got the glossary.
timing: Some(take_timing()),
@@ -663,6 +665,7 @@ fn history_entries() -> Vec {
preset: None,
origin: None,
processed: None,
+ corrected: None,
file: None,
timing: None,
glossary_sent: None,
@@ -701,6 +704,7 @@ fn history_entries() -> Vec {
preset: None,
origin: None,
processed: None,
+ corrected: None,
file: None,
timing: None,
glossary_sent: None,
@@ -737,6 +741,7 @@ fn history_entries() -> Vec {
preset: None,
origin: Some(EntryOrigin { device: "Pixel 8".into(), kind: OriginKind::Typed }),
processed: None,
+ corrected: None,
file: None,
timing: None,
glossary_sent: None,
@@ -781,6 +786,7 @@ fn imported_history_entry() -> HistoryEntry {
preset: Some(PresetRef { id: PresetId::Builtin(BuiltinPreset::Proofread), name: "校对".into() }),
origin: None,
processed: None,
+ corrected: None,
file: Some(ImportedFile { name: "季度会议.mp4".into(), duration_ms: 9_500 }),
timing: None,
glossary_sent: Some(false),
@@ -1310,6 +1316,8 @@ fn full_state() -> UiState {
edit_error: None,
copy_last_registered: Some("Ctrl+Shift+V".into()),
copy_last_error: None,
+ learn_registered: Some("Ctrl+Alt+L".into()),
+ learn_error: None,
capabilities: capabilities(true, true),
solo_registered: Some(SoloKey::RightCtrl),
solo_error: None,
@@ -1350,6 +1358,16 @@ fn full_state() -> UiState {
dictionary: dictionary(),
rules: rules(),
vocabulary_ignored: ignored_pairs(),
+ learn_notice: Some(LearnNotice {
+ id: 3,
+ outcome: LearnOutcome::Learned {
+ pairs: vec![SuggestionPick { heard: "Quinn for".into(), polished: "Qwen 4".into(), history_id: uuid(HISTORY_ID) }],
+ safe: true,
+ },
+ shown: true,
+ accepted: None,
+ undone: None,
+ }),
scenes: scenes(),
phone_take: Some(PhoneTakeView {
device: DESKTOP_KEY.to_hex(),
@@ -1453,6 +1471,7 @@ fn event_tag(event: &UiEvent) -> &'static str {
UiEvent::Dictionary { .. } => "dictionary",
UiEvent::Rules { .. } => "rules",
UiEvent::VocabularyIgnored { .. } => "vocabulary_ignored",
+ UiEvent::LearnNotice { .. } => "learn_notice",
UiEvent::Scenes { .. } => "scenes",
UiEvent::Presets { .. } => "presets",
UiEvent::PresetTry { .. } => "preset_try",
@@ -1604,6 +1623,11 @@ fn models_event(list: Vec) -> UiEvent {
}
/// Same for the dictionary and the rules (docs/dictation.md §16.4).
+/// A shown learn notice with `outcome` (docs/dictation.md §35).
+fn learn_notice(outcome: LearnOutcome) -> UiEvent {
+ UiEvent::LearnNotice { notice: Some(LearnNotice { id: 5, outcome, shown: true, accepted: None, undone: None }) }
+}
+
fn dictionary_event(list: Vec) -> UiEvent {
UiState::default().apply(voltip_core::CoreEvent::Dictionary(list))
}
@@ -1679,6 +1703,8 @@ fn all_events() -> Vec {
edit_error: None,
copy_last_registered: Some("Ctrl+Shift+V".into()),
copy_last_error: None,
+ learn_registered: None,
+ learn_error: None,
capabilities: capabilities(true, true),
solo_registered: Some(SoloKey::MouseBack),
solo_error: None,
@@ -1696,6 +1722,8 @@ fn all_events() -> Vec {
edit_error: Some("Ctrl+Alt+E 注册失败:already registered".into()),
copy_last_registered: None,
copy_last_error: Some("Ctrl+Shift+V 注册失败:already registered".into()),
+ learn_registered: None,
+ learn_error: Some("Ctrl+Alt+L 与另一个快捷键相同,未生效".into()),
capabilities: capabilities(true, false),
solo_registered: Some(SoloKey::RightAlt),
solo_error: None,
@@ -1714,6 +1742,8 @@ fn all_events() -> Vec {
edit_error: None,
copy_last_registered: None,
copy_last_error: None,
+ learn_registered: None,
+ learn_error: None,
capabilities: capabilities(false, false),
solo_registered: None,
solo_error: Some("右 Ctrl 无法单独触发:纯 Wayland 会话不允许应用监听全局按键".into()),
@@ -2129,6 +2159,11 @@ fn all_events() -> Vec {
}]),
// docs/dictation.md §22: a long take processed with a preset keeps the result beside its text.
history_event(vec![HistoryEntry { processed: Some(Box::new(processed_text())), ..history_entries().remove(0) }]),
+ // docs/dictation.md §35: the user's correction kept beside the inserted text.
+ history_event(vec![HistoryEntry {
+ corrected: Some(Box::new(CorrectedText { text: "我在用 Qwen 4 max 做测试".into(), at_ms: AT_MS + 60_000, via: CorrectionVia::Selection })),
+ ..history_entries().remove(0)
+ }]),
// docs/dictation.md §22: a long take's text past 5000 characters waits on the clipboard.
history_event(vec![HistoryEntry {
outcome: Outcome::Clipboard { reason: voltip_core::dictation::long::TOO_LONG_TO_PASTE.into(), code: Some(ClipboardCode::TooLong) },
@@ -2259,6 +2294,45 @@ fn all_events() -> Vec {
// The pairs the learning suggestions leave out (docs/dictation.md §16.10), and none.
UiEvent::VocabularyIgnored { pairs: ignored_pairs() },
UiEvent::VocabularyIgnored { pairs: Vec::new() },
+ // The learn notice (docs/dictation.md §35): learned and waiting behind a take's result,
+ // shown after 加入词典 and its 撤销, each reason there was nothing to learn, and gone.
+ UiEvent::LearnNotice {
+ notice: Some(LearnNotice {
+ id: 4,
+ outcome: LearnOutcome::Learned {
+ pairs: vec![SuggestionPick { heard: "Quinn for".into(), polished: "Qwen 4".into(), history_id: uuid(HISTORY_ID) }],
+ safe: true,
+ },
+ shown: false,
+ accepted: None,
+ undone: None,
+ }),
+ },
+ UiEvent::LearnNotice {
+ notice: Some(LearnNotice {
+ id: 4,
+ outcome: LearnOutcome::Learned {
+ pairs: vec![SuggestionPick { heard: "非书".into(), polished: "飞书".into(), history_id: uuid(HISTORY_ID) }],
+ safe: true,
+ },
+ shown: true,
+ accepted: Some(NoticeAccepted { added: 1, refused: 0, undo: Some(uuid(HISTORY_ID)) }),
+ undone: Some(BatchUndoOutcome::Undone),
+ }),
+ },
+ learn_notice(LearnOutcome::Learned {
+ pairs: vec![SuggestionPick { heard: "非".into(), polished: "飞".into(), history_id: uuid(HISTORY_ID) }],
+ safe: false,
+ }),
+ learn_notice(LearnOutcome::NoPairs),
+ learn_notice(LearnOutcome::Unchanged),
+ learn_notice(LearnOutcome::NoMatch),
+ learn_notice(LearnOutcome::NoSelection),
+ learn_notice(LearnOutcome::TooLong { max: 8000 }),
+ learn_notice(LearnOutcome::Terminal),
+ learn_notice(LearnOutcome::HistoryOff),
+ learn_notice(LearnOutcome::Failed { message: "clipboard: 无法读取剪贴板".into() }),
+ UiEvent::LearnNotice { notice: None },
// Voice edit (docs/dictation.md §19): the edit hotkey switched off, and an edit take in every
// phase the pill discriminates on, with the four refusals.
UiEvent::Settings(Settings { edit_hotkey: None, ..settings() }),
@@ -2558,6 +2632,7 @@ fn command_variant(cmd: &UiCommand) -> &'static str {
UiCommand::SettingsSetHotkey { .. } => "SettingsSetHotkey",
UiCommand::SettingsSetEditHotkey { .. } => "SettingsSetEditHotkey",
UiCommand::SettingsSetCopyLastHotkey { .. } => "SettingsSetCopyLastHotkey",
+ UiCommand::SettingsSetLearnHotkey { .. } => "SettingsSetLearnHotkey",
UiCommand::SettingsSetSoloKey { .. } => "SettingsSetSoloKey",
UiCommand::SettingsSetMicrophone { .. } => "SettingsSetMicrophone",
UiCommand::SettingsSetRecording { .. } => "SettingsSetRecording",
@@ -2586,6 +2661,10 @@ fn command_variant(cmd: &UiCommand) -> &'static str {
UiCommand::DictationStop => "DictationStop",
UiCommand::DictationCancel => "DictationCancel",
UiCommand::DictationDismiss { .. } => "DictationDismiss",
+ UiCommand::LearnNoticeAccept { .. } => "LearnNoticeAccept",
+ UiCommand::LearnNoticeUndo { .. } => "LearnNoticeUndo",
+ UiCommand::LearnNoticeDismiss { .. } => "LearnNoticeDismiss",
+ UiCommand::LearnNoticeKeep { .. } => "LearnNoticeKeep",
UiCommand::HotkeyEdge { .. } => "HotkeyEdge",
UiCommand::SettingsSetActivation { .. } => "SettingsSetActivation",
UiCommand::SettingsSetEngines { .. } => "SettingsSetEngines",
@@ -2596,6 +2675,7 @@ fn command_variant(cmd: &UiCommand) -> &'static str {
UiCommand::HistoryDelete { .. } => "HistoryDelete",
UiCommand::HistoryClear => "HistoryClear",
UiCommand::HistoryStar { .. } => "HistoryStar",
+ UiCommand::HistoryClearCorrected { .. } => "HistoryClearCorrected",
UiCommand::HistoryProcess { .. } => "HistoryProcess",
UiCommand::HistoryProcessCancel { .. } => "HistoryProcessCancel",
UiCommand::ModelDownload { .. } => "ModelDownload",
@@ -2669,6 +2749,8 @@ fn all_commands() -> Vec<(&'static str, Value, &'static str)> {
("settings_set_edit_hotkey", json!({ "hotkey": "Ctrl+Alt+Shift+E" }), "SettingsSetEditHotkey"),
// docs/dictation.md §28: the 复制上一条结果 hotkey (`null` assigns none).
("settings_set_copy_last_hotkey", json!({ "hotkey": "Ctrl+Shift+V" }), "SettingsSetCopyLastHotkey"),
+ // docs/dictation.md §35: the 从选中文字学习 hotkey (`null` assigns none).
+ ("settings_set_learn_hotkey", json!({ "hotkey": "Ctrl+Alt+L" }), "SettingsSetLearnHotkey"),
// docs/dictation.md §13.1: the lone-key trigger (`null` switches it off).
("settings_set_solo_key", json!({ "key": "mouse_back" }), "SettingsSetSoloKey"),
("settings_set_microphone", json!({ "device": "wasapi:{0.0.1.00000000}.{c2}" }), "SettingsSetMicrophone"),
@@ -2719,6 +2801,11 @@ fn all_commands() -> Vec<(&'static str, Value, &'static str)> {
("dictation_cancel", Value::Null, "DictationCancel"),
// docs/dictation.md §28: the result card's 关闭, for the take whose card it is.
("dictation_dismiss", json!({ "session": 3 }), "DictationDismiss"),
+ // docs/dictation.md §35: the learn notice's buttons.
+ ("learn_notice_accept", json!({ "id": 4 }), "LearnNoticeAccept"),
+ ("learn_notice_undo", json!({ "id": 4 }), "LearnNoticeUndo"),
+ ("learn_notice_dismiss", json!({ "id": 4 }), "LearnNoticeDismiss"),
+ ("learn_notice_keep", json!({ "id": 4 }), "LearnNoticeKeep"),
// The activation machine's inputs (docs/dictation.md §13): one CLI press — of the voice-edit
// key (`voltip --edit-toggle`, §19) — and one mode change.
("hotkey_edge", json!({ "pressed": true, "atMs": AT_MS, "source": "cli", "purpose": "edit" }), "HotkeyEdge"),
@@ -2736,6 +2823,7 @@ fn all_commands() -> Vec<(&'static str, Value, &'static str)> {
("history_delete", json!({ "id": HISTORY_ID }), "HistoryDelete"),
("history_clear", Value::Null, "HistoryClear"),
("history_star", json!({ "id": HISTORY_ID, "starred": true }), "HistoryStar"),
+ ("history_clear_corrected", json!({ "id": HISTORY_ID }), "HistoryClearCorrected"),
// 用 AI 预设处理 (docs/dictation.md §22).
("history_process", json!({ "requestId": 5, "id": HISTORY_ID, "preset": "notes" }), "HistoryProcess"),
("history_process_cancel", json!({ "requestId": 5 }), "HistoryProcessCancel"),
@@ -3218,6 +3306,7 @@ fn commands_fixture_is_the_wire_form_and_parses_into_every_variant() {
"SettingsSetHotkey",
"SettingsSetEditHotkey",
"SettingsSetCopyLastHotkey",
+ "SettingsSetLearnHotkey",
"SettingsSetSoloKey",
"SettingsSetMicrophone",
"SettingsSetRecording",
@@ -3238,6 +3327,10 @@ fn commands_fixture_is_the_wire_form_and_parses_into_every_variant() {
"DictationStop",
"DictationCancel",
"DictationDismiss",
+ "LearnNoticeAccept",
+ "LearnNoticeUndo",
+ "LearnNoticeDismiss",
+ "LearnNoticeKeep",
"HotkeyEdge",
"SettingsSetActivation",
"SettingsSetEngines",
@@ -3247,6 +3340,7 @@ fn commands_fixture_is_the_wire_form_and_parses_into_every_variant() {
"HistoryDelete",
"HistoryClear",
"HistoryStar",
+ "HistoryClearCorrected",
"ModelDownload",
"ModelCancel",
"ModelRemove",
@@ -3400,15 +3494,16 @@ fn vocabulary_backtest_fixture_matches_serde_output() {
fn vocabulary_suggestions_fixture_matches_serde_output() {
use voltip_core::mcp::candidates::PairExample;
use voltip_core::vocabulary::{
- AcceptOutcome, BatchAcceptOutcome, BatchIgnoreOutcome, BatchItem, BatchUndoOutcome, EntryClash, Refusal, RuleWarning, Suggestion, SuggestionUndo,
- Suggestions, SuggestionsAnswer, UndoOutcome,
+ AcceptOutcome, BatchAcceptOutcome, BatchIgnoreOutcome, BatchItem, EntryClash, Refusal, RuleWarning, Suggestion, SuggestionUndo, Suggestions,
+ SuggestionsAnswer, UndoOutcome,
};
let ready = SuggestionsAnswer::Ready(Suggestions {
scanned: 2000,
refined: 1480,
skipped: 3,
total: 41,
- repeated: 9,
+ repeated: 10,
+ edited: 2,
pairs: vec![
Suggestion {
heard: "维他命".into(),
@@ -3419,6 +3514,7 @@ fn vocabulary_suggestions_fixture_matches_serde_output() {
PairExample { history_id: uuid(HISTORY_ID), snippet: "维他命的安装包发给我".into() },
PairExample { history_id: uuid(HISTORY_ID_2), snippet: "…今天用维他命跑了一遍回归".into() },
],
+ from_edits: 0,
},
Suggestion {
heard: "提成".into(),
@@ -3426,6 +3522,16 @@ fn vocabulary_suggestions_fixture_matches_serde_output() {
count: 3,
last_at_ms: AT_MS - 86_400_000,
examples: vec![PairExample { history_id: uuid(HISTORY_ID_3), snippet: "提成在 Teams 里面".into() }],
+ from_edits: 0,
+ },
+ // docs/dictation.md §35: a pair the user corrected in the application, once.
+ Suggestion {
+ heard: "Quinn for".into(),
+ polished: "Qwen 4".into(),
+ count: 1,
+ last_at_ms: AT_MS - 3_600_000,
+ examples: vec![PairExample { history_id: uuid(HISTORY_ID_2), snippet: "我在用 Quinn for max 做测试".into() }],
+ from_edits: 1,
},
],
});
diff --git a/docs/acceptance.md b/docs/acceptance.md
index 4ac17fe7..29cd9fbf 100644
--- a/docs/acceptance.md
+++ b/docs/acceptance.md
@@ -315,6 +315,7 @@
| 词典学习建议(docs/dictation.md §16.10,0.3.0 计划 R08 阶段一,只做电脑端):从最近 2000 条识别记录里找出「识别成 A、被润色改成 B」的写法(与 MCP `vocabulary_candidates` 同一个比较,只逐字比较、不调用 AI),去掉词典已纠正的和忽略的,按次数、再按最近一次排序;词典页「词条」「学习建议(n)」两个视图;每行「加入词典」(新建来自历史的词条,或加到正确写法相同的词条;替换规则会改掉写法或其他词条挡住时说明原因)与「忽略」(`vocabulary-ignored.json`,最多 2000 组,不进备份),加入或忽略后该行留在原处并可撤销(只在页面打开期间;忽略的组合之后在「已忽略」里取消);展开后看示例、会保存什么和 `vocabulary_backtest` 给出的影响范围;历史记录关闭、没有润色过的记录、没有新写法三种空状态 | `crates/voltip-core/src/vocabulary/{suggest,ignored,mod}.rs`、`crates/voltip-core/src/{runtime,ui}.rs`、`crates/voltip-tauri-bridge/src/lib.rs`(`vocabulary_suggestions` 与缓存、`vocabulary_suggestion_*`)、`apps/desktop/src-tauri/src/lib.rs`、`packages/shared/src/{schema,backend,tauri-backend,mock-backend,suggestions}.ts`、`packages/ui/src/components/Tabs.tsx`、`apps/desktop/src/pages/Dictionary.tsx`、`apps/desktop/src/pages/dictionary/{Suggestions.tsx,useSuggestions.ts}` | `crates/voltip-core/src/vocabulary/suggest.rs@suggestions_are_counted_and_sorted`、`crates/voltip-core/src/vocabulary/suggest.rs@known_and_ignored_pairs_are_left_out`、`crates/voltip-core/src/vocabulary/suggest.rs@regression_a_pair_the_dictionary_already_explains_is_not_suggested`、`crates/voltip-core/src/vocabulary/suggest.rs@accept_creates_an_entry_or_adds_to_the_one_with_the_spelling`、`crates/voltip-core/src/vocabulary/suggest.rs@accept_refuses_when_a_rule_rewrites_the_spelling`、`crates/voltip-core/src/vocabulary/suggest.rs@accept_refuses_when_another_entry_is_in_the_way`、`crates/voltip-core/src/vocabulary/suggest.rs@undo_puts_the_entry_back_while_it_is_unchanged`、`crates/voltip-core/src/vocabulary/ignored.rs@the_list_keeps_the_newest_pairs_and_refuses_bad_ones`、`crates/voltip-core/src/vocabulary/ignored.rs@an_unusable_file_is_moved_aside`、`crates/voltip-core/tests/vocabulary.rs@learning_suggestions_through_the_core`、`crates/voltip-tauri-bridge/src/lib.rs@learning_suggestions_follow_the_lists_and_the_history`、`crates/voltip-tauri-bridge/tests/contract.rs@vocabulary_suggestions_fixture_matches_serde_output`、`apps/desktop/src-tauri/tests/ipc.rs@learning_suggestions_run_through_the_command_layer`、`packages/shared/src/suggestions.test.ts@counts the clean-up's pairs, most frequent first and then the newest`、`packages/ui/src/components/Tabs.test.tsx@a click shows a view, and the arrow keys, Home and End move to one and show it`、`apps/desktop/src/pages/Dictionary.test.tsx@the page has two views; 学习建议 counts what the clean-up changed and lists it, most frequent first`、`apps/desktop/src/pages/Dictionary.test.tsx@加入词典 saves the pair, the row stays in place with 撤销, and 撤销 takes it back even after switching views`、`apps/desktop/src/pages/Dictionary.test.tsx@忽略 leaves a pair out for good, and 撤销 brings it back`、`apps/desktop/src/pages/Dictionary.test.tsx@a row's details show the takes it came from and what the entry would change before it is saved`、`apps/desktop/src/pages/Dictionary.test.tsx@a pair the dictionary or a rule refuses says why and leads to what is in the way`、`apps/desktop/src/pages/Dictionary.test.tsx@with history recording off, 学习建议 says it needs the history and leads to its setting`、`apps/desktop/src/pages/Dictionary.test.tsx@without polished takes, 学习建议 says the clean-up is what it learns from`、`apps/desktop/src/pages/Dictionary.test.tsx@when the dictionary already corrects everything polished, 学习建议 says there is nothing new` | [x] |
| 学习建议的「已忽略(n)」列表(docs/dictation.md §16.10,2026-10-31 用户决定,只做电脑端):忽略过的组合最近忽略的在前,每行写出组合与忽略时间,「取消忽略」让它重新参与学习建议,学习建议里对应的行也回到「加入词典」「忽略」;超过 5 组时「显示全部(n)」;列表由核心保存,离开页面或重启后还在;取消忽略失败时说明原因 | `crates/voltip-core/src/vocabulary/ignored.rs`、`packages/shared/src/mock-backend.ts`(`vocabularyIgnored`)、`apps/desktop/src/pages/dictionary/{IgnoredList.tsx,parts.tsx,useSuggestions.ts}` | `crates/voltip-core/tests/vocabulary.rs@the_ignored_list_holds_each_pair_with_when_it_was_ignored`、`crates/voltip-tauri-bridge/src/lib.rs@the_ignored_list_is_in_the_state_with_its_times`、`apps/desktop/src-tauri/tests/ipc.rs@learning_suggestions_run_through_the_command_layer`、`packages/shared/src/mock-backend.test.ts@starts from the ignored pairs it is given, oldest first; 取消忽略 works for a pair no take has`、`apps/desktop/src/pages/Dictionary.test.tsx@忽略 puts the pair on 已忽略(n) with when it was ignored, and 取消忽略 there makes it a suggestion again`、`apps/desktop/src/pages/Dictionary.test.tsx@pairs ignored earlier are listed newest first, five until 显示全部, and stay out of the suggestions`、`apps/desktop/src/pages/Dictionary.test.tsx@a 取消忽略 that fails says why and leaves the pair on 已忽略` | [x] |
| 学习建议的批量处理(docs/dictation.md §16.10,2026-11-02 用户决定,只做电脑端,不调用 AI):默认只列出出现 2 次及以上的建议,可切换为「全部」,页签上的数字是当前显示范围内待处理的组数,列表下方写明显示了多少组、隐藏了多少组只出现 1 次的建议;每行可勾选,带「全选」(键盘可用、有无障碍名称),勾选后一次「加入词典」或「忽略」;「全部忽略(n)」只作用于当前显示的行;批量加入按列表顺序处理,正确写法相同的几组进同一个词条的曾听成写法,被替换规则、停用的词条、写满的曾听成写法、已满的词典等挡住的逐组说明原因,其余照常加入,一批只写一次词典文件、发一次变化;页面打开期间可整批撤销,词典恢复成加入前的样子,撤销记录失效或词条之后被修改、删除时说明原因并点名词条;批量忽略同样一批写一次,撤销把这批从「已忽略」里拿掉,列表回到这一批从没发生过时的样子(挤掉的组合按原来的时间回到原来的位置,之后的单独操作照旧生效),几批按任意顺序撤销都如此,撤销过的一批不会因为撤销另一批而回来 | `crates/voltip-core/src/vocabulary/{suggest,ignored,store}.rs`(`accept_batch`、`undo_batch`、`BatchLog`、`IgnoreStore::{add_batch,remove_batch}`、`Suggestions::repeated`)、`crates/voltip-core/src/runtime.rs`(`SuggestionsAccept` / `SuggestionsIgnore` / `SuggestionsUndo`)、`crates/voltip-tauri-bridge/src/lib.rs`(`vocabulary_suggestions_{accept,ignore,undo}`)、`apps/desktop/src-tauri/src/lib.rs`、`packages/shared/src/{schema,backend,tauri-backend,mock-backend,suggestions}.ts`、`packages/ui/src/components/Checkbox.tsx`、`apps/desktop/src/pages/dictionary/{Suggestions.tsx,useSuggestions.ts}` | `crates/voltip-core/src/vocabulary/suggest.rs@the_repeated_suggestions_are_counted_before_the_cut`、`crates/voltip-core/src/vocabulary/suggest.rs@a_batch_goes_in_in_order_with_one_write_and_one_entry_per_spelling`、`crates/voltip-core/src/vocabulary/suggest.rs@a_batch_refuses_each_pick_in_the_way_and_takes_the_rest`、`crates/voltip-core/src/vocabulary/suggest.rs@a_batch_that_cannot_be_written_changes_nothing`、`crates/voltip-core/src/vocabulary/suggest.rs@undo_of_a_batch_puts_the_dictionary_back_while_its_entries_are_unchanged`、`crates/voltip-core/src/vocabulary/suggest.rs@the_batch_log_gives_each_batch_once_and_keeps_the_newest`、`crates/voltip-core/src/vocabulary/ignored.rs@a_batch_is_ignored_and_taken_back_with_one_write_each`、`crates/voltip-core/src/vocabulary/ignored.rs@a_batch_past_the_cap_drops_the_oldest_pairs_and_its_undo_puts_them_back`、`crates/voltip-core/src/vocabulary/ignored.rs@undo_of_a_batch_ignore_keeps_what_changed_since`、`crates/voltip-core/src/vocabulary/ignored.rs@regression_batches_taken_back_in_any_order_keep_the_oldest_first`、`crates/voltip-core/src/vocabulary/ignored.rs@regression_eleven_full_batches_taken_back_in_any_order_leave_the_list_as_opened`、`crates/voltip-core/src/vocabulary/ignored.rs@the_oldest_batches_expire_past_the_undo_limit`、`crates/voltip-core/tests/vocabulary.rs@batches_of_suggestions_through_the_core`、`crates/voltip-core/tests/vocabulary.rs@regression_undo_of_a_batch_ignore_on_a_full_list_puts_back_the_pairs_it_pushed_out`、`crates/voltip-core/tests/vocabulary.rs@regression_batches_ignored_on_a_full_list_and_taken_back_out_of_order_keep_the_oldest_first`、`crates/voltip-core/tests/vocabulary.rs@regression_eleven_full_batches_taken_back_out_of_order_leave_the_list_as_before`、`crates/voltip-tauri-bridge/src/lib.rs@batches_of_suggestions_follow_the_lists`、`crates/voltip-tauri-bridge/tests/contract.rs@vocabulary_suggestions_fixture_matches_serde_output`、`apps/desktop/src-tauri/tests/ipc.rs@batches_of_suggestions_run_through_the_command_layer`、`packages/shared/src/suggestions.test.ts@counts the suggestions seen twice or more, before the limit cuts the list`、`packages/shared/src/suggestions.test.ts@goes in in order, picks with one right spelling into one entry, and answers for each`、`packages/shared/src/suggestions.test.ts@refuses each pick in the way and takes the rest`、`packages/shared/src/mock-backend.test.ts@a batch 忽略 puts its pairs on the list once, with one new list, and 撤销 takes them off again`、`packages/shared/src/mock-backend.test.ts@regression: 撤销 of a batch 忽略 on a full ignored list puts back the pairs it pushed out`、`packages/shared/src/mock-backend.test.ts@regression: two batches 忽略 on a full list taken back out of order keep the oldest first`、`packages/shared/src/mock-backend.test.ts@regression: eleven batches of 200 on a full list taken back as 1, 11, 10, …, 2 leave the list as before`、`packages/shared/src/tauri-backend.test.ts@the learning suggestions' batches (§16.10) send their pairs as they are and validate the answers`、`packages/ui/src/components/Checkbox.test.tsx@shows a partial selection as mixed and drops it once the box is all or nothing`、`apps/desktop/src/pages/Dictionary.test.tsx@lists the suggestions seen twice or more until 全部; the tab and the footer say what is shown and what is hidden`、`apps/desktop/src/pages/Dictionary.test.tsx@rows are checked one by one or all at once, also from the keyboard, and 全选 covers the rows shown`、`apps/desktop/src/pages/Dictionary.test.tsx@加入词典 for the checked rows adds them in one go, says which could not be added and why, and 撤销 takes the whole batch back`、`apps/desktop/src/pages/Dictionary.test.tsx@a batch nothing could go in from says so, and a 撤销 that comes too late says why and keeps the entries`、`apps/desktop/src/pages/Dictionary.test.tsx@忽略 for the checked rows and 全部忽略 for the rows shown put them on 已忽略, and 撤销 takes each batch back`、`apps/desktop/src/pages/Dictionary.test.tsx@a batch that fails says why, and its rows can be tried again` | [x] |
+| 从选中文字学习(docs/dictation.md §35,用户决定 2026-11-18,只做电脑端,不调用 AI):在其他应用里改正听写结果后,选中改好的文字按「从选中文字学习」的快捷键(默认未设置,与听写、语音编辑、复制上一条结果的组合键互不相同;X11 上松开后才复制;纯 Wayland 绑定 `voltip-desktop --learn-selection`),Voltip 用复制键读出选区(终端里不按键,剪贴板放回),在最新 50 条听写里找到它改正的那几条(相似度至少 0.4,多选、少选都可以,一次最多 5 条),把改后的整段存进历史记录(历史详情显示「之后改成」,可以移除),改动按识别原文的写法进学习建议,标「你的修改」,只出现 1 次也在默认的「推荐」里;中文单字的改动带上相邻的字(「非书 → 飞书」,学习建议与 MCP `vocabulary_candidates` 都是);悬浮窗显示「已记下 n 处改动」,可以一键加入词典(有短写法时只能「查看」)、撤销、查看,停 8 秒,下一次听写开始时消失,常驻的结果卡片关闭后才出现;说明没有学到的原因(历史记录关闭时带「打开设置」) | `crates/voltip-core/src/vocabulary/{learn,suggest}.rs`、`crates/voltip-core/src/mcp/candidates.rs`(`scan`、`widen`、`Replay`)、`crates/voltip-core/src/runtime/learn.rs`、`crates/voltip-core/src/runtime.rs`、`crates/voltip-core/src/history/{mod,store,reader,derived}.rs`(`corrected`、`set_corrected`)、`crates/voltip-core/src/{settings,ui}.rs`、`crates/voltip-tauri-bridge/src/lib.rs`、`apps/desktop/src-tauri/src/{hotkey,cli,overlay,lib}.rs`、`packages/shared/src/{schema,backend,tauri-backend,mock-backend,suggestions,quick-fix,refine}.ts`、`apps/desktop/src/pages/{Overlay,Dictionary}.tsx`、`apps/desktop/src/pages/dictionary/{Suggestions.tsx,useSuggestions.ts}`、`apps/desktop/src/pages/history/{DetailParts,HistoryDetail}.tsx`、`apps/desktop/src/pages/settings/Hotkey.tsx`、`apps/desktop/src/app/{router.tsx,tray-requests.ts}`、`scripts/smoke-desktop-linux.sh` | `crates/voltip-core/src/vocabulary/learn.rs@a_corrected_sentence_finds_its_take_and_the_users_wording`、`crates/voltip-core/src/vocabulary/learn.rs@a_take_that_is_mostly_the_error_still_matches`、`crates/voltip-core/src/vocabulary/learn.rs@text_selected_around_the_take_is_left_out`、`crates/voltip-core/src/vocabulary/learn.rs@regression_an_end_replacement_with_nothing_in_common_keeps_every_character`、`crates/voltip-core/src/vocabulary/learn.rs@a_selection_over_two_takes_corrects_each`、`crates/voltip-core/src/vocabulary/learn.rs@a_change_the_dictionary_made_is_not_learned`、`crates/voltip-core/src/vocabulary/learn.rs@a_second_correction_keeps_the_first_and_a_revert_leaves_nothing`、`crates/voltip-core/src/vocabulary/suggest.rs@the_users_corrections_are_counted_with_the_clean_ups_pairs`、`crates/voltip-core/src/vocabulary/suggest.rs@a_single_character_is_widened_to_the_spelling_the_takes_use`、`crates/voltip-core/src/vocabulary/suggest.rs@the_notice_offers_the_corrections_of_its_takes_only`、`crates/voltip-core/src/history/tests.rs@a_correction_is_stored_beside_the_entry_searched_and_read_with_the_recent_texts`、`crates/voltip-core/tests/learn.rs@the_learn_hotkey_is_one_of_four_distinct_chords`、`crates/voltip-core/tests/learn.rs@a_selection_corrects_the_take_and_the_notice_offers_its_pair`、`crates/voltip-core/tests/learn.rs@the_notice_waits_for_a_result_card_goes_with_a_take_and_needs_the_pill`、`crates/voltip-core/tests/learn.rs@the_notice_says_why_nothing_was_learned`、`crates/voltip-core/tests/learn.rs@regression_a_terminal_the_voice_edit_allows_is_still_not_learned_from`、`crates/voltip-core/tests/learn.rs@regression_view_and_open_settings_start_the_notices_stay_again`、`crates/voltip-platform/src/insert_check.rs@regression_every_hosts_terminals_hold_program_output`、`crates/voltip-inject/src/selection.rs@regression_two_copies_at_once_neither_read_nor_lose_the_users_clipboard`、`crates/voltip-core/src/vocabulary/learn.rs@regression_the_original_wording_takes_back_a_correction_that_shares_no_word_with_it`、`crates/voltip-core/src/history/tests.rs@regression_a_correction_read_in_the_field_loads`、`crates/voltip-core/src/vocabulary/learn.rs@regression_the_alignment_that_wins_rebuilds_the_take`、`crates/voltip-core/src/vocabulary/learn.rs@regression_a_selection_that_stops_before_the_next_word_keeps_the_space`、`crates/voltip-core/src/vocabulary/suggest.rs@regression_a_correction_counts_once_per_take_and_a_skipped_one_is_still_edited`、`apps/desktop/src/pages/Dictionary.test.tsx@regression: with only corrected takes and nothing new, 学习建议 names the corrections, not 0 polished takes`、`apps/desktop/src-tauri/src/hotkey.rs@the_learn_chord_fires_when_the_copy_can_reach_the_application`、`apps/desktop/src-tauri/src/overlay.rs@the_learn_notice_shows_only_when_the_core_shows_it_between_takes`、`apps/desktop/src-tauri/tests/ipc.rs@learning_from_the_selection_runs_through_the_command_layer`、`packages/shared/src/suggestions.test.ts@§35: the user's corrections are counted with the clean-up's pairs, shown once corrected`、`packages/shared/src/mock-backend.test.ts@the learn hotkey is one of four distinct chords, none by default`、`packages/shared/src/mock-backend.test.ts@the notice's 加入词典, 撤销 and × go through the batch of the learning suggestions`、`apps/desktop/src/pages/Overlay.test.tsx@offers the pair with 加入词典 and 查看, and the buttons go to the core and the shell`、`apps/desktop/src/pages/Overlay.test.tsx@a short spelling is only viewed; after 加入词典 there is 撤销, then what it did`、`apps/desktop/src/pages/Overlay.test.tsx@says why there was nothing to learn, and offers the privacy settings while the history is off`、`apps/desktop/src/pages/settings/Settings.test.tsx@docs/dictation.md section 35: 从选中文字学习 has its own recorder, none by default, and refuses the other three chords`、`apps/desktop/src/pages/history/HistoryDetail.test.tsx@shows what the take was corrected to, and 移除 forgets it while the inserted text stays`、`apps/desktop/src/pages/Dictionary.test.tsx@docs/dictation.md §35: a correction made in another app is a suggestion of its own, shown once, with its source`、`apps/desktop/src/pages/Dictionary.test.tsx@docs/dictation.md §35: with the shortcut set there is no hint, and /dictionary/suggestions opens the suggestions`、`apps/desktop/src/app/tray-requests.test.tsx@docs/dictation.md section 35: the learn notice's 查看 opens the learning suggestions, 打开设置 the privacy settings`、`crates/voltip-inject/tests/real_display.rs@real_copy_chord_reads_the_selection_of_an_x11_text_widget`、`crates/voltip-inject/tests/real_display.rs@regression_x11_hotkey_grab_swallows_the_copy_until_the_key_is_up`、`crates/voltip-focus/tests/focus_windows.rs@the_copy_reads_notepads_selection_with_the_shortcut_held_and_puts_the_clipboard_back`、`crates/voltip-focus/tests/focus_macos.rs@TextEdit's selection` | [x](Linux 真实应用:`scripts/smoke-desktop-linux.sh` 的学习流程,2026-11-18 本机 Xvfb 通过;Windows 记事本、macOS TextEdit 的复制由 CI 真机测试;卡片按钮在真机上点按 [!] 用户在 windows-local 上验收) |
| 规则页的三种提示(§16.10):与另一条规则重复(匹配相同,只有前面的命中)、两条规则互为反向替换(替换循环)、规则把某个词条的正确写法改回曾听成写法(撤销词典词条);写在每条规则下面,规则或词典变化后重新判断 | `crates/voltip-core/src/vocabulary/mod.rs`(`rule_warnings`)、`crates/voltip-tauri-bridge/src/lib.rs`(`rules_warnings`)、`packages/shared/src/suggestions.ts`(`ruleWarnings`)、`apps/desktop/src/pages/Rules.tsx` | `crates/voltip-core/src/vocabulary/tests.rs@rule_warnings_name_duplicates_inverses_and_rules_that_undo_an_entry`、`crates/voltip-core/src/vocabulary/tests.rs@rule_warnings_leave_out_near_misses_and_what_does_not_run`、`packages/shared/src/suggestions.test.ts@names duplicates, inverses and rules that undo an entry`、`apps/desktop/src/pages/Rules.test.tsx@name a duplicate, two rules that turn each other back and a rule that undoes an entry, and follow the lists`、`apps/desktop/src/pages/Rules.test.tsx@rules without a problem have no hints` | [x] |
| 设置 › AI 工具接入(§25.6):启用与状态(地址、最近连接的工具)、端口、读取范围(完整历史先确认风险并选时间范围,授权后一直显示警告与「收回」)、修改权限(直接启用规则先确认)、Claude Code 与 Codex 的接入命令(令牌占位,复制时由核心填入,令牌不进页面)、令牌、最近活动与撤销;规则页的待确认提示条、筛选、行与侧栏小圆点;词典页来源与「外部工具」筛选;外部写入的提示 | `apps/desktop/src/pages/settings/McpPane.tsx`、`apps/desktop/src/features/mcp/useMcpWriteToasts.ts`、`apps/desktop/src/pages/{Rules,Dictionary}.tsx`、`packages/shared/src/mcp.ts` | `apps/desktop/src/pages/settings/McpPane.test.tsx@the correction summary is read by default; narrowing applies at once, the full history only after a confirmation with its period`、`apps/desktop/src/pages/settings/McpPane.test.tsx@turning rules on directly needs a confirmation; the other levels apply at once`、`apps/desktop/src/pages/settings/McpPane.test.tsx@the commands show a placeholder; 复制命令 and 复制令牌 have the core copy the real token, which never reaches the page`、`apps/desktop/src/pages/settings/McpPane.test.tsx@the recent activity lists reads and writes; a write can be undone`、`apps/desktop/src/pages/Rules.test.tsx@a waiting rule has a banner, a filter, its own row, the sidebar dot and the dry-run note; 启用 approves it`、`apps/desktop/src/pages/Dictionary.test.tsx@their source names the tool, 外部工具 shows only them, and the filter goes once none is left`、`apps/desktop/src/features/mcp/useMcpWriteToasts.test.tsx@a tool's entry is announced with 查看, which opens the dictionary; its next write joins the toast` | [x] |
| 录音缓存的界面(§26.6):设置 › 隐私与历史 › 录音缓存(开关、最多保留、最多占用、清理录音,历史关着时不可用);历史页「未识别的录音」(原因、重新识别、删除录音);历史详情的重新识别与润色失败条目的「重新润色」(结果存为处理后文本);悬浮胶囊的「录音已保留,可重新识别」与「已取消 · 录音已保留」 | `apps/desktop/src/pages/settings/RecordingsSection.tsx`、`apps/desktop/src/features/history/{Recordings,RefineNote}.tsx`、`apps/desktop/src/pages/history/HistoryDetail.tsx`、`apps/desktop/src/pages/Overlay.tsx`、`packages/shared/src/audio-cache.ts` | `apps/desktop/src/pages/settings/PrivacyPane.test.tsx@turning it off deletes the kept recordings and disables the limits`、`apps/desktop/src/pages/settings/PrivacyPane.test.tsx@清理录音 asks first, then deletes every kept recording and leaves the history's text`、`apps/desktop/src/pages/history/Recordings.test.tsx@重新识别 recognises a recording again: a new entry on the clipboard, and the row is gone`、`apps/desktop/src/pages/history/Recordings.test.tsx@重新润色 polishes a take whose polish failed and shows the result as 处理后`、`apps/desktop/src/pages/Overlay.test.tsx@says the recording is kept when a take that gave no text, or was cancelled while processing, can be recognised again` | [ ](未经真机验收) |
diff --git a/docs/dictation.md b/docs/dictation.md
index 8e0acdf7..8f5139cd 100644
--- a/docs/dictation.md
+++ b/docs/dictation.md
@@ -1613,10 +1613,14 @@ Rust:`vocabulary` 单测(上限、校验、字面 vs 正则、大小写、
### 16.10 词典学习建议(2026-10-30)
-**目标**:从历史记录里找出「识别成 A、被润色改成 B」的写法,按次数排好,用户一键加入词典或忽略,可以撤销;加入之前能看到对过去记录的影响。全程只做逐字比较,不调用 AI(0.3.0 计划 R08 阶段一,只做电脑端)。跨应用学习(阶段二)不在这里。
-
-- **来源**(`voltip_core::vocabulary::suggest::suggestions`):`suggestions(dictionary, rules, history, ignored, limit) -> Suggestions { scanned, refined, skipped, total, repeated, pairs }`。`history` 是 `HistoryReader::recent_texts(MAX_RECENT_TEXTS)` 读到的最新 2000 条识别记录(§16.9),只有听写:语音编辑、手机发来的文字和导入的文件(§31,里面可能是别人说的话)都不算,回测也一样。比较与 MCP 的 `vocabulary_candidates` 是同一个函数(`mcp::candidates::candidates`,§25.4):只汇总 AI 润色做的替换(与 `takePolishPairs` 相同,没有润色的记录只计入 `scanned`,`refined` 是其中润色过的条数),中文按字成对(「非书 → 飞书」汇总为「非 → 飞」),比较格超过 `MAX_DIFF_CELLS` = 100 万(TS 里是 `MAX_PAIR_DIFF_CELLS`)的记录计入 `skipped`;一次累计最多 `MAX_SCAN_CELLS` = 5000 万个比较格,到了就不再读更早的记录,`scanned` 只算读到的条数。
-- **过滤与排序**:去掉启用词条已有的曾听成写法(ASCII 大小写不敏感)和忽略列表里的组合(`heard` 与 `polished` 逐字相同);按次数从多到少,次数相同时最近一次在前。`total` 是过滤后的组数,`repeated` 是其中出现 `REPEATED_MIN` = 2 次及以上的组数(两者都在截到 `limit` 之前统计),`pairs` 最多 `limit` 组(1–`MAX_SUGGESTIONS` = 200);每组带 `count`、`last_at_ms` 和最多 3 个示例(`history_id`,识别原文中前后各 12 个字符的片段)。
+**目标**:从历史记录里找出「识别成 A、被润色改成 B」的写法,以及「识别成 A、用户在应用里改成 B」的写法(§35),按次数排好,用户一键加入词典或忽略,可以撤销;加入之前能看到对过去记录的影响。全程只做逐字比较,不调用 AI(0.3.0 计划 R08 阶段一,只做电脑端;用户修改的来源 2026-11-18 加入)。
+
+- **来源**(`voltip_core::vocabulary::suggest::suggestions`):`suggestions(dictionary, rules, history, ignored, limit) -> Suggestions { scanned, refined, edited, skipped, total, repeated, pairs }`。`history` 是 `HistoryReader::recent_texts(MAX_RECENT_TEXTS)` 读到的最新 2000 条识别记录(§16.9),只有听写:语音编辑、手机发来的文字和导入的文件(§31,里面可能是别人说的话)都不算,回测也一样。两个来源,按 `heard` 与 `polished` 合并计数:
+ - 润色:AI 润色做的替换,比较与 MCP 的 `vocabulary_candidates` 相同(`mcp::candidates::scan`,§25.4):与 `takePolishPairs` 相同,没有润色的记录只计入 `scanned`,`refined` 是其中润色过的条数。
+ - 你的修改(§35):有 `corrected` 的记录里用户改正、而识别原文就是这个写法、词典和规则没碰过的替换(`vocabulary::learn::edit_changes`),每条记录每组算 1 次(同一条记录里改了两处相同的写法也是 1 次);`edited` 是读到的记录里有修改的条数(比较格超出上限、被跳过的也算,与 `refined` 相同),`Suggestion.from_edits` 是一组里来自修改的次数(为 0 时不写出)。
+ - 两个来源都按 `diffSegments` 的切分成对,再做单字扩展(`mcp::candidates::widen`):`heard` 或 `polished` 只有 1 个汉字、假名或谚文时,两侧都加上同一个相邻的、没有改动的字;左右都能加时,选扩展后的 `polished` 在读到的最终文字(各记录的 `text` 和 `corrected`)里出现次数更多的一边,一样多时取右边;两边都没有可加的字时保持 1 个字。所以「非书 → 飞书」就是「非书 → 飞书」(2026-11-18 之前汇总为「非 → 飞」),「钉丁 → 钉钉」取左边,因为「钉钉」在最终文字里更常见。
+ - 比较格超过 `MAX_DIFF_CELLS` = 100 万(TS 里是 `MAX_PAIR_DIFF_CELLS`)的记录计入 `skipped`;一次累计最多 `MAX_SCAN_CELLS` = 5000 万个比较格(两个来源合计),到了就不再读更早的记录,`scanned` 只算读到的条数。
+- **过滤与排序**:去掉启用词条已有的曾听成写法(ASCII 大小写不敏感)和忽略列表里的组合(`heard` 与 `polished` 逐字相同);扩展过的组合,扩展前的单字写法是已有的曾听成写法、或扩展前的单字组合在忽略列表里时也去掉(2026-11-18 之前忽略的单字组合继续有效)。按次数从多到少,次数相同时最近一次在前。`total` 是过滤后的组数,`repeated` 是其中「推荐」的组数:出现 `REPEATED_MIN` = 2 次及以上,或者 `from_edits` 至少 1(用户决定 2026-11-18,只出现 1 次的修改也推荐;两者都在截到 `limit` 之前统计)。`pairs` 最多 `limit` 组(1–`MAX_SUGGESTIONS` = 200);每组带 `count`、`from_edits`、`last_at_ms` 和最多 3 个示例(`history_id`,识别原文中前后各 12 个字符的片段,两个来源合并后按新到旧取)。
- **忽略列表**(`vocabulary::IgnoreStore`):`<数据目录>/vocabulary-ignored.json`(`schema` 1,`IgnoredPair { heard, polished, at_ms }`),原子写入;最多 `MAX_IGNORED` = 2000 组,超出时去掉最早的,再次忽略同一组时移到末尾;文件无法使用时改名移开并在启动时提示(与 §16.1 的列表文件相同)。由运行时持有,`UiState.vocabulary_ignored` 与事件 `vocabulary_ignored { pairs }`(最早忽略的在前)把它送给界面,桌面的「已忽略」列表就是它。不进备份。
- **加入词典**(`suggest::accept`,`vocabulary_suggestion_accept { heard, polished, historyId }`):先看替换规则,正在执行的规则(启用且不在待确认中)会把 `polished` 改掉时拒绝(`Refusal::Rule { rule_id, name, becomes }`,加入后也不会生效);再看词典:`heard` 是其他词条的正确写法(`heard_is_term`)或曾听成写法(`heard_taken`),或 `polished` 是其他词条的曾听成写法(`term_taken`)时拒绝。有正确写法相同(ASCII 大小写不敏感)的词条时,把 `heard` 加到它的曾听成写法,保留它的写法(它已停用时拒绝 `disabled`,已有 `MAX_HEARD_AS` = 10 个时拒绝 `too_many`);否则新建启用的词条,来源 `EntrySource::History { history_id }`(第一个示例所在的记录),词典已满时拒绝(`Full { max }`)。拒绝是一种结果(`AcceptOutcome::Refused`),不是错误,界面按类型写出原因。
- **撤销**:运行时在内存里记下每次加入前后的词条(`UndoLog`,最多 `MAX_UNDOS` = 100 条),返回 `SuggestionUndo { id, entry_id, term, created, previous_heard_as }`。`vocabulary_suggestion_undo { id }` 在词条仍是加入后的样子时还原(新建的删除,合并的恢复原来的曾听成写法),词条已删除时是 `gone`,之后改过时是 `changed`,没有这条记录时是 `expired`(每条只能撤销一次,重启后的旧记录也是 `expired`)。忽略的撤销是 `vocabulary_suggestion_unignore`。「加入词典」的撤销只在词典页打开期间提供;忽略的组合随时可以在「已忽略」里取消忽略(同一个命令,2026-10-31 用户决定加这个列表)。页面上写明这两点。
@@ -1626,7 +1630,7 @@ Rust:`vocabulary` 单测(上限、校验、字面 vs 正则、大小写、
- 整批撤销(查询 `vocabulary_suggestions_undo { id }` → `BatchUndoOutcome`):批量加入的撤销在这一批新建或加入过的每个词条都还是这一批留下的样子时进行,新建的删除,加入的恢复原来的曾听成写法,一次写入,词典回到加入前的样子(之后改过的其他词条保持不变);其中有词条之后被删除或修改时一个也不撤销,回答 `gone { term }` / `changed { term }`,点名第一个这样的词条;批量忽略的撤销(`IgnoreStore::remove_batch(&IgnoredBatch)`,一次写入)把日志里这一批标为已撤销,从稳定点起依次重放其余改动,列表就是这一批从没发生过时的样子:这一批加入的组合拿掉,它挤掉的组合按原来的时间回到原来的位置;之后单独取消忽略或又单独忽略的组合保持现在的样子,其余改动挤掉的仍是最早的组合。几批按任意顺序撤销都是如此,撤销过的一批不会因为撤销另一批而回到列表里(例如 11 批各 200 组、第 11 批挤掉第 1 批,按 1、11、10…2 的顺序撤销后列表与批量前相同)。稳定点之前的改动不再需要时并入稳定点:最早一个还能撤销的批次之前的改动,以及超过 `MAX_UNDOS` 批或 1 万次改动时最早的那一批(它从此不能撤销,回答 `expired`)。运行时在内存里记下每一批(`BatchLog`,最多 `MAX_UNDOS` = 100 批),每批只能撤销一次,未知或重启前的是 `expired`。一批 1–`MAX_BATCH` = 200 组;超出范围或其中有一组不是有效写法(与单组相同的校验)时,桥接层整批拒绝(`BadArgument`「vocabulary_suggestions_accept: pairs 1–200」),什么也不发给核心。
- **规则提示**(`vocabulary::rule_warnings(rules, dictionary)`,查询 `rules_warnings`):只看正在执行的规则和启用的词条。`Duplicate`:另一条规则的类型、匹配内容与大小写设置都相同,只有排在前面的那条会命中;`Inverse`:另一条同类型的规则正好把替换内容改回匹配内容(匹配与替换相同的规则不算);`UndoesEntry`:这条规则单独作用于某个词条的正确写法时得到它的一个曾听成写法(ASCII 大小写不敏感),抵消词典的纠正。规则页在每条规则下面一行写出。
- **IPC**:查询(`QUERY_COMMANDS`,只有桌面注册)`vocabulary_suggestions { limit? }` → `SuggestionsAnswer`:历史记录关闭时是 `{ status: "history_off" }`(不是空列表),否则 `{ status: "ready", scanned, refined, skipped, total, repeated, pairs }`,`limit` 越界是 `BadArgument`「vocabulary_suggestions: limit 1–200」;`vocabulary_suggestion_accept`、`vocabulary_suggestion_undo`、批量的 `vocabulary_suggestions_accept`、`vocabulary_suggestions_ignore`、`vocabulary_suggestions_undo`、`rules_warnings`。命令 `vocabulary_suggestion_ignore` / `vocabulary_suggestion_unignore { heard, polished }`。两个写法在两边都先校验(去掉首尾空白,不能为空,最多 64 个字符,不能有换行或控制字符,两者不能相同)。`Bridge::vocabulary_suggestions` 在后台线程计算并缓存结果,词典、规则、历史记录或忽略列表的事件让缓存失效(代次号在事件更新状态之后递增),同一时刻只算一次。zod:`suggestionsAnswerSchema`、`acceptOutcomeSchema`、`undoOutcomeSchema`、`batchAcceptOutcomeSchema`、`batchIgnoreOutcomeSchema`、`batchUndoOutcomeSchema`、`ruleWarningSchema`、`ignoredPairSchema`;夹具 `fixtures/ipc/vocabulary-suggestions.json`。`MockBackend` 用 `packages/shared/src/suggestions.ts` 的 `suggestVocabulary`、`acceptSuggestion`、`acceptSuggestions`、`undoSuggestions`、`ruleWarnings` 按同样语义回答。两个手机壳都不注册这些命令(`DESKTOP_ONLY`);`UiState.vocabulary_ignored` 为空时不写出,缺省为空列表。
-- **桌面**(`apps/desktop/src/pages/Dictionary.tsx`、`pages/dictionary/`):页头「个人词典」旁有两个视图「词条」「学习建议(n)」(`packages/ui` `Tabs`:`Segmented` 的外观加上 tab 的语义,左右方向键与 Home / End 切换),n 是当前显示范围内还没处理的组数(默认是 `repeated`,选「全部」时是 `total`),为 0 或历史记录关闭时不写;「新建词条」与 `Ctrl N` 回到词条视图。右侧的「试一试」只在词条视图里,学习建议视图占满整页宽度(2026-10-30 在 1152 × 720 的默认窗口里实测:放在「试一试」旁边时,听错的写法被截成「维… → Vol…」,表头也挤在一起),切回词条视图时「试一试」里的文字还在。学习建议视图有说明卡(只逐字比较、不调用 AI;离开词典页后「加入词典」不能再撤销,忽略的写法可以在「已忽略」中取消忽略)和一张表「识别结果 → 润色结果 · 次数 · 最近一次」,每行有「加入词典」「忽略」和展开按钮。展开后:识别原文里的示例(听错的写法高亮);会新建哪个词条,或会加到哪个词条;`vocabulary_backtest`(§16.9,不排除任何记录,读最近 500 条)给出的「加入后,最近 N 条记录中有 x 条会被改动」,以及最终文本仍是原写法的条数;写法只有 1 个字或 1–2 个字母时提示容易误改其他词语。加入或忽略后该行留在原处,显示「已加入词典 · 撤销」或「已忽略 · 撤销」;被拒绝时原因写在这一行下面,与词条冲突时带「查看词条」(回到词条视图并选中那个词条),与规则冲突时带「打开替换规则」。表头右侧是显示范围「出现 2 次及以上」(默认)/「全部」(`Segmented`)和「全部忽略(n)」,n 是当前显示、还没处理的行数,「全部忽略」只忽略这些行;切换显示范围时,隐藏的行取消勾选。表的第一列是勾选框(`packages/ui` `Checkbox`,原生复选框,Tab 到达、空格切换,名称「选择:A → B」),表头的「全选」勾选当前显示、还没处理的全部行,只选了一部分时显示为部分选中;已处理的行没有勾选框。有勾选的行时表上方出现「已选 n 组」与「加入词典」「忽略」(名称「将所选的 n 组加入词典」「忽略所选的 n 组」)和「取消选择」。一批处理完后,这些行显示「已加入词典」或「已忽略」,没有各自的撤销;表上方按时间倒序列出每一批的结果:「已将 n 组加入词典。」「已将 n 组加入词典,m 组无法加入,原因见对应的行。」「所选的 n 组都无法加入词典,原因见对应的行。」「已忽略 n 组。」,有内容加入或忽略时带「撤销」(页面打开期间有效),撤销后这些行回到「加入词典」「忽略」;撤销不成时写明原因(「无法撤销:词条「X」已被修改。」等);整批失败时写「操作失败:…」,这些行恢复原样可以再试。在「已忽略」里取消忽略某一组后,学习建议里那一行回到「加入词典」「忽略」,一批的行都这样取回后,这一批的结果不再显示。列表下方的统计在「最近 N 条记录 · x 条经过 AI 润色」之后写「显示 n 组」(只显示前 200 组时是「显示前 n 组 · 共 m 组」),默认范围下还有「隐藏 k 组只出现 1 次的建议」。空状态:历史记录关闭(「需要开启历史记录」,按钮打开 设置 › 隐私)、最近的记录都没有经过 AI 润色、没有新的写法可以加入;默认范围下只有出现 1 次的建议时写「没有出现 2 次及以上的建议」「另有 n 组只出现 1 次。」并带「显示全部」。表下面是「已忽略(n)」(`pages/dictionary/IgnoredList.tsx`):忽略过的组合,最近忽略的在前,每行是「识别结果 → 润色结果 · 忽略时间」和「取消忽略」;超过 `IGNORED_SHOWN` = 5 组时先列最近 5 组,「显示全部(n)」列出全部,「收起」收回。列表就是 `UiState.vocabulary_ignored`,离开页面或重启后还在,与历史记录开关无关;没有忽略过的组合时不显示。在这里取消忽略后,学习建议里还显示「已忽略 · 撤销」的那一行回到「加入词典」「忽略」;取消忽略失败时原因写在那一组下面,组合留在列表里。词典、规则、历史记录、忽略列表或历史记录开关变化时重新查询;这些状态(连同显示范围、勾选和每一批的结果)由页面持有,切换视图不会丢掉撤销。侧栏不显示数量。手机没有这个视图。
+- **桌面**(`apps/desktop/src/pages/Dictionary.tsx`、`pages/dictionary/`):页头「个人词典」旁有两个视图「词条」「学习建议(n)」(`packages/ui` `Tabs`:`Segmented` 的外观加上 tab 的语义,左右方向键与 Home / End 切换),n 是当前显示范围内还没处理的组数(默认是 `repeated`,选「全部」时是 `total`),为 0 或历史记录关闭时不写;「新建词条」与 `Ctrl N` 回到词条视图。右侧的「试一试」只在词条视图里,学习建议视图占满整页宽度(2026-10-30 在 1152 × 720 的默认窗口里实测:放在「试一试」旁边时,听错的写法被截成「维… → Vol…」,表头也挤在一起),切回词条视图时「试一试」里的文字还在。学习建议视图有说明卡(来自 AI 润色的改动和你在其他应用里的修改(§35);只逐字比较、不调用 AI;离开词典页后「加入词典」不能再撤销,忽略的写法可以在「已忽略」中取消忽略;「从选中文字学习」的快捷键还没设置时带「设置快捷键」,打开 设置 › 快捷键)和一张表「识别结果 → 正确写法 · 次数 · 最近一次」,每行有「加入词典」「忽略」和展开按钮;写法后面标出来源「润色」「你的修改」,两种都有时都标。展开后:识别原文里的示例(听错的写法高亮);会新建哪个词条,或会加到哪个词条;`vocabulary_backtest`(§16.9,不排除任何记录,读最近 500 条)给出的「加入后,最近 N 条记录中有 x 条会被改动」,以及最终文本仍是原写法的条数;写法只有 1 个字或 1–2 个字母时提示容易误改其他词语。加入或忽略后该行留在原处,显示「已加入词典 · 撤销」或「已忽略 · 撤销」;被拒绝时原因写在这一行下面,与词条冲突时带「查看词条」(回到词条视图并选中那个词条),与规则冲突时带「打开替换规则」。表头右侧是显示范围「推荐」(默认:出现 2 次及以上的,以及你改正过的)/「全部」(`Segmented`)和「全部忽略(n)」,n 是当前显示、还没处理的行数,「全部忽略」只忽略这些行;切换显示范围时,隐藏的行取消勾选。表的第一列是勾选框(`packages/ui` `Checkbox`,原生复选框,Tab 到达、空格切换,名称「选择:A → B」),表头的「全选」勾选当前显示、还没处理的全部行,只选了一部分时显示为部分选中;已处理的行没有勾选框。有勾选的行时表上方出现「已选 n 组」与「加入词典」「忽略」(名称「将所选的 n 组加入词典」「忽略所选的 n 组」)和「取消选择」。一批处理完后,这些行显示「已加入词典」或「已忽略」,没有各自的撤销;表上方按时间倒序列出每一批的结果:「已将 n 组加入词典。」「已将 n 组加入词典,m 组无法加入,原因见对应的行。」「所选的 n 组都无法加入词典,原因见对应的行。」「已忽略 n 组。」,有内容加入或忽略时带「撤销」(页面打开期间有效),撤销后这些行回到「加入词典」「忽略」;撤销不成时写明原因(「无法撤销:词条「X」已被修改。」等);整批失败时写「操作失败:…」,这些行恢复原样可以再试。在「已忽略」里取消忽略某一组后,学习建议里那一行回到「加入词典」「忽略」,一批的行都这样取回后,这一批的结果不再显示。列表下方的统计在「最近 N 条记录 · x 条经过 AI 润色」之后写「y 条有你的修改」(有时)和「显示 n 组」(只显示前 200 组时是「显示前 n 组 · 共 m 组」),默认范围下还有「隐藏 k 组只出现 1 次的建议」。空状态:历史记录关闭(「需要开启历史记录」,按钮打开 设置 › 隐私)、最近的记录既没有经过 AI 润色也没有你的修改、没有新的写法可以加入(按比较过的记录写「最近 n 条经过 AI 润色的记录里」「最近 n 条有你修改的记录里」,两种都有时两者都写);默认范围下只有不推荐的建议时写「没有推荐的建议」「另有 n 组只出现 1 次。」并带「显示全部」。表下面是「已忽略(n)」(`pages/dictionary/IgnoredList.tsx`):忽略过的组合,最近忽略的在前,每行是「识别结果 → 正确写法 · 忽略时间」和「取消忽略」;超过 `IGNORED_SHOWN` = 5 组时先列最近 5 组,「显示全部(n)」列出全部,「收起」收回。列表就是 `UiState.vocabulary_ignored`,离开页面或重启后还在,与历史记录开关无关;没有忽略过的组合时不显示。在这里取消忽略后,学习建议里还显示「已忽略 · 撤销」的那一行回到「加入词典」「忽略」;取消忽略失败时原因写在那一组下面,组合留在列表里。词典、规则、历史记录、忽略列表或历史记录开关变化时重新查询;这些状态(连同显示范围、勾选和每一批的结果)由页面持有,切换视图不会丢掉撤销。侧栏不显示数量。手机没有这个视图。
- **耗时**(2026-10-30,本机 32 核 CPU,`--release`,`voltip-tauri-bridge` 的 `timing_learning_suggestions_over_2000_takes`,运行方法见它的注释;测量时机器上还有其他进程,负载约 10):测了两遍。2000 条约 100 字的润色记录:第一次 99 ms 与 66 ms(读出并比较全部 2000 条),之后命中缓存 9 µs;2000 条约 900 字的润色记录:比较格累计到 `MAX_SCAN_CELLS` = 5000 万时停止读更早的记录,只比较了最新的 73 条,第一次两遍都是 145 ms,`scanned` 如实写 73。计算在后台线程里进行,不占界面线程。
- **门禁**:Rust `vocabulary::suggest` 14 条(含 `regression_a_pair_the_dictionary_already_explains_is_not_suggested`,批量 6 条:`the_repeated_suggestions_are_counted_before_the_cut`、`a_batch_goes_in_in_order_with_one_write_and_one_entry_per_spelling`、`a_batch_refuses_each_pick_in_the_way_and_takes_the_rest`、`a_batch_that_cannot_be_written_changes_nothing`、`undo_of_a_batch_puts_the_dictionary_back_while_its_entries_are_unchanged`、`the_batch_log_gives_each_batch_once_and_keeps_the_newest`;「只写一次」用单元测试里按线程计数的列表文件写入次数核对)、`vocabulary::ignored` 9 条(批量 6 条,含满额时撤销放回挤掉的组合、几批不按先后撤销、11 批各 200 组按 1、11、10…2 撤销、超过撤销上限的批次过期)、`vocabulary::tests::rule_warnings_*` 2 条、`crates/voltip-core/tests/vocabulary.rs@learning_suggestions_through_the_core`、`@the_ignored_list_holds_each_pair_with_when_it_was_ignored`、`@batches_of_suggestions_through_the_core`(一批只发一次 `Dictionary` 事件)、`@regression_undo_of_a_batch_ignore_on_a_full_list_puts_back_the_pairs_it_pushed_out`、`@regression_batches_ignored_on_a_full_list_and_taken_back_out_of_order_keep_the_oldest_first` 与 `@regression_eleven_full_batches_taken_back_out_of_order_leave_the_list_as_before`、bridge `learning_suggestions_follow_the_lists_and_the_history`、`the_ignored_list_is_in_the_state_with_its_times` 与 `batches_of_suggestions_follow_the_lists`、契约 `vocabulary_suggestions_fixture_matches_serde_output`、桌面命令层 `apps/desktop/src-tauri/tests/ipc.rs@learning_suggestions_run_through_the_command_layer` 与 `@batches_of_suggestions_run_through_the_command_layer`;TS `suggestions.test.ts` 15 条、`mock-backend.test.ts`「MockBackend learning suggestions」9 条、`ipc-contract.test.ts` 与 `tauri-backend.test.ts` 的对应用例、`packages/ui` `Tabs.test.tsx` 3 条与 `Checkbox.test.tsx` 3 条、`apps/desktop` `Dictionary.test.tsx`「learning suggestions」24 条(含 `regression: 学习建议 takes the page's whole width, and the test panel comes back with the entries`,「已忽略」3 条,批量与显示范围 9 条)与 `Rules.test.tsx`「hints」2 条。
@@ -2609,7 +2613,7 @@ Rust:`presets` 单测(wire 名与旧值、校验、存储往返与隔离、
- 只读(`readOnlyHint: true`、`idempotentHint: true`):`dictionary_list`、`rules_list`(每页 100,带 cursor)、`vocabulary_preview`(文本最多 64 KiB,可带一条规则草稿)、`vocabulary_backtest`(§16.9 的 `backtest`,默认扫 500 条、最多 2000)、`vocabulary_candidates`(润色前后的替换对与次数,默认 50、最多 200,每对最多 3 个示例,片段前后各 12 字)、`history_search`(`query`、`since` / `until`(毫秒数或 RFC 3339,只写日期时按 UTC 零点)、`app`、`cursor`;每页默认 20、最多 50)、`history_get`。
- 写入(`destructiveHint: false`):`dictionary_add`(按正确写法 ASCII 大小写不敏感合并曾听成写法,重复调用不产生变化,`idempotentHint: true`)、`dictionary_update`(`idempotentHint: true`)、`rules_add`、`rules_update`(`idempotentHint: true`)。所有工具 `openWorldHint: false`;参数 schema 在 `crates/voltip-core/src/mcp/tools.rs`。结果里带 `activity_id`。
- prompt `review_misrecognitions { days }`(1–3650,缺省 30):先 `vocabulary_candidates`,再对每个草稿 `vocabulary_backtest`,把建议列给用户确认后再写入。工具与 prompt 的描述用英文(读者是模型)。
-- 替换汇总的切分与历史页的 `diffSegments` 相同(Rust 实现 `voltip_core::mcp::candidates`,夹具 `fixtures/ipc/diff.json` 让两边逐例对照),所以中文按字成对:「非书 → 飞书」汇总为「非 → 飞」。只汇总 AI 润色做的替换,与历史页的 `takePolishPairs` 相同(§16.9,含同样的局限):没有润色的记录只计入 `scanned`,这条记录自己触发过的词条和规则能解释的替换不计入,触发过的定义已删除或在记录之后改过的记录整条不计入(`recent_texts` 为此读出 `refined` 与 `vocabulary`)。桌面词典页的「学习建议」(§16.10)调用同一个函数,再去掉忽略列表里的组合。
+- 替换汇总的切分与历史页的 `diffSegments` 相同(Rust 实现 `voltip_core::mcp::candidates`,夹具 `fixtures/ipc/diff.json` 让两边逐例对照),中文按字成对后做单字扩展(§16.10,2026-11-18):「非书 → 飞书」汇总为「非书 → 飞书」,不再是「非 → 飞」。只汇总 AI 润色做的替换(用户在应用里的修改(§35)不进这个工具),与历史页的 `takePolishPairs` 相同(§16.9,含同样的局限):没有润色的记录只计入 `scanned`,这条记录自己触发过的词条和规则能解释的替换不计入,触发过的定义已删除或在记录之后改过的记录整条不计入(`recent_texts` 为此读出 `refined` 与 `vocabulary`)。桌面词典页的「学习建议」(§16.10)用同样的比较,再加上用户修改的来源,去掉忽略列表里的组合。
- `history_search` / `history_get` 的每条记录:id、时间、kind、原文、最终文本、处理后文本、是否润色、应用、场景名、预设名、识别与润色模型、时长、`outcome` 的类别、来源、`truncated`;不包含语音编辑的指令与选区、失败原因,搜索也不匹配选区。
### 25.5 写入、活动记录与撤销
@@ -3445,3 +3449,108 @@ AppImage 目录在 C locale 下运行应用,并对截图做 OCR(`code/check-
- 对话框没有父窗口(主窗口隐藏),位置由窗口管理器决定;没有窗口管理器时在屏幕左上角。macOS 菜单栏启动(`--start-hidden`,没有 Dock 图标)时它是否在其他窗口前面没有验证。
- Secret Service 的解锁提示由 gnome-keyring 或 KWallet 自己显示,Voltip 等它结束才继续启动(与之前相同);提示一直不关时 Voltip 一直等。
- 截图在根窗口为黑色的环境里大部分是暗色,目录脚本的「默认深色主题」检查只给警告。
+
+## 35. 从修改中学习(2026-11-18)
+
+**起因**(测试用户的反馈,2026-11-18):学习建议(§16.10)只比较识别原文和 AI 润色结果,识别和润色都没改对的错误学不到。说「Qwen 4 max」,识别和润色都写成「Quinn for max」,用户在应用里改正了,Voltip 却不知道。现在用户可以选中改好的文字,按「从选中文字学习」的快捷键,Voltip 找到对应的听写,记下改动,放进学习建议。全程只做逐字比较,不调用 AI。
+
+### 35.1 决定
+
+- 用户决定(2026-11-18):「选中改好的文字,按快捷键学习」是主要方式(本节)。「自动跟踪输入框里的修改」做成要手动开启的实验功能,先在用户自己的电脑上实测各应用的输入框能不能读到,再单独设计。不做手机端。改动只进学习建议,不自动写进词典。中文单字的改动带上相邻的字(§16.10)。
+- 逐项回答:快捷键默认不分配,由用户自己设,与「复制上一条结果」相同。悬浮窗的通知能一键「加入词典」,改动里有 1 个字或 1–2 个字母的写法时只给「查看」。通知停 8 秒,点按钮后重新计时,下一次听写开始时消失。学习建议默认显示「推荐」:出现 2 次及以上的,加上来自你的修改的。历史详情显示保存下来的修改,并且可以移除。
+- 不做:托盘入口(Windows 上点托盘菜单时 Voltip 自己成为前台,复制键到不了原来的应用);MCP 的 `history_get` / `history_search` 输出改后的文字(`vocabulary_candidates` 只受单字扩展影响,§25.4);语音编辑的结果、手机发来的文字和导入的文件参与学习(与学习建议的范围相同);历史记录的复制、粘贴和导出改用改后的文字(仍用当时插入的文字)。
+
+### 35.2 触发
+
+- 设置:`Settings.learn_hotkey: Option`,默认没有;命令 `settings_set_learn_hotkey { hotkey }`,`null` 清除。设置 › 快捷键 有一行「从选中文字学习」,录制器的做法与「复制上一条结果」相同,四个录制器同一时间只开一个。
+- 四个组合键互不相同:听写、语音编辑、复制上一条结果、从选中文字学习。核心的四个 setter 都用 `Hotkey::same_chord` 检查其余三个,冲突时报错(如「已用作「从选中文字学习」的快捷键」),设置不变。桌面的 `hotkey::apply` 遇到手改设置文件造成的重复组合同样不注册,原因写进 `HotkeyStatus.learn_error`(另有 `learn_registered`)。
+- 触发时机:`selection_timing_for(session)` 为 `AtPress` 时按下即触发;为 `AfterKeyUp` 时(X11 / XWayland:键盘抓取期间复制键到不了焦点窗口,§19)松开时触发(`hotkey::learn_fires_on`)。纯 Wayland 没有全局快捷键,设置页显示要在系统快捷键里绑定的命令 `voltip-desktop --learn-selection`。
+- 命令行 `--learn-selection`(`cli.rs`)经单实例插件交给正在运行的 Voltip,做法与 `--copy-last` 相同。
+- 核心命令 `CoreCommand::LearnSelection { source }`。复制前要松开的修饰键(`held`,§19.2)在快捷键触发时是 `learn_hotkey` 的修饰键,命令行触发时为空。
+
+### 35.3 核心流程(`crates/voltip-core/src/runtime/learn.rs`)
+
+1. 有听写还没到终态(录音、识别、润色中):忽略,只写日志。空闲和终态(完成、失败、取消)时照常进行。
+2. 历史记录关闭:结果 `history_off`,不按任何键。
+3. 在后台任务里先问前台探针,最多等它的期限。前台是终端(`injector.holds_program_output`)时结果 `terminal`,不按任何键:终端里选中的是程序输出。这张表包括 macOS 的终端(`voltip_platform::insert_check::holds_program_output`,与插入确认跳过的终端相同);语音编辑的表(`is_terminal_app`)在 macOS 上是空的,因为 Cmd+C 在那里不会打断程序(2026-11-18 目标评审发现学习沿用了它)。探针没有回答时(纯 Wayland、超时)照常复制,与语音编辑相同。
+4. 在阻塞线程里调用 `injector.copy_selection(&held)`(§19.2:保存剪贴板,按复制键,读出选区,放回剪贴板)。同一进程里一次只做一次复制(`voltip_inject::selection` 的进程锁,从保存到放回):连按两次快捷键、或学习和语音编辑同时复制时,后一次等前一次放回剪贴板再开始,不会把前一次清空的剪贴板当成用户的内容保存,也不会把前一次放回的内容当成选区。没有选中是 `no_selection`,出错是 `failed { message }`,超过 `MAX_LEARN_SELECTION_CHARS` = 8000 个字符是 `too_long { max }`。
+5. 在阻塞线程里读最新 `LEARN_TAKES` = 50 条识别记录:运行时自己的只读 `HistoryReader` 调用 `recent_texts`,只有听写,与学习建议相同。按 35.4 匹配:一条也没匹配到是 `no_match`,匹配到的都与插入的文字相同是 `unchanged`。
+6. 对匹配到的每条记录:改后的整段有可学的改动时(35.4 的 `storable`)保存,`HistoryStore::set_corrected(id, Some(CorrectedText { text, at_ms, via: selection }))`;没有可学的改动、而这条记录原来有 `corrected` 时清除它(用户把修改又改回了原文)。有写入时发 `history` 事件,学习建议的缓存随之失效。
+7. 算出这几条记录给学习建议的组合(`suggest::edit_picks`:与 §16.10 的「你的修改」来源算法相同,去掉忽略的和词典已知的)。有组合时结果是 `learned { pairs, safe }`,`pairs` 是 `SuggestionPick` 列表,`safe` 为假表示其中有 1 个字或 1–2 个字母的写法;没有组合时是 `no_pairs`。然后设置通知(35.6)。
+
+只有最新一次请求的回答算数:再按一次快捷键后,前一次的回答到了也丢掉。日志只写结果种类、条数和字数,不写文字。
+
+### 35.4 匹配与可学的改动(`crates/voltip-core/src/vocabulary/learn.rs`)
+
+- 比较沿用 `mcp::candidates` 的分词与 LCS(§25.4)。选区先按插入确认的规则规范化(`insert_check::normalize`);两个词按去掉末尾空白后的样子比较(应用可能换了行尾),区分大小写,所以只改大小写的修正(「github → GitHub」)也能看到。
+- **对齐**:取两边词级 LCS 中匹配字符最多的一段;相邻两个匹配词之间,一侧比另一侧多出 `GAP_BREAK` = 3 个以上的词时从那里断开(那是多选进来的别的听写,或者少选的部分)。选区两端只属于选区的部分算多选,听写两端只属于听写的部分算少选,都不算改动。某一端两侧都有对不上的文字时(错词在听写的开头或结尾),从选区那段里紧挨匹配部分取几个整词,作为这一端的改动:词数与听写一侧相差不超过 1,字符数是它的一半到两倍,取与它逐字 LCS 最长的,一样长时取词数与它最接近的,再一样时取最短的;没有合适的就不学这一端。(最初一样长时直接取最短的:冒烟测试里「Voltip 冒烟注入」改成「Voltip 冒烟测试」,「测」与「测试」和「注入」都没有相同的字,存下的是「Voltip 冒烟测」。)汉字、假名、谚文按字算一个词。
+- **相似度** =(相同词的字符数 + 每组替换内部逐字 LCS 的字符数)÷ 两侧对齐范围字符数的较大者,不计空白;某一侧超过 64 个字符的替换不做内部比较。
+- **选记录**:相似度至少 `MATCH_MIN` = 0.4,并且至少有一个相同的词;取最高的,与次高的相差 `MATCH_TIE` = 0.05 以内时取较新的。然后在选区剩下、不重叠的部分里继续找,一次最多 `MAX_TAKES_PER_SELECTION` = 5 条(选中了连续几次听写的情况)。比较格受 `MAX_DIFF_CELLS` / `MAX_SCAN_CELLS` 限制,从新到旧比较。
+- **存什么**:这条记录已有 `corrected.text` 时,与 `text`、与 `corrected.text` 都对齐,用胜出的那个:相似度较高的,一样高时覆盖选区较多的,再一样时用 `corrected.text`。胜出的是 `corrected.text`(或者没有 `corrected`)时,改后的整段是它(或 `text`)中对齐的范围换成选区里对应的文字。胜出的是 `text` 时(用户选中了原来的写法,例如撤回上次的修改),先把 `text` 中对齐的范围按两者的词级 LCS 对到 `corrected.text` 里:从范围第一个词变成的词(或它之前最后一个没改的词之后)到最后一个词变成的词(或它之后第一个没改的词之前),跨在范围两端的旧修改算在范围内;再在 `corrected.text` 里换成选区的文字,所以范围以外的旧修改照样保留(2026-11-18 目标评审第 2 轮:之前总按 `corrected.text` 的对齐重建,「red apple」只对上了第一个「red」,旧的「grape」留了下来)。选区在下一个词之前结束、没有带上那里的空格时,被换掉的范围末尾的空白保留(以前会拼成「Qwen 4 maxis great」)。改后的整段是基准中对齐的范围换成选区里对应的文字,所以没被这次选区覆盖的部分保留上次的修改,重叠的部分以这次为准。改后的整段至少有一处改动满足下面第 1、3 条时保存,替换旧值;否则清除已有的 `corrected`。改后的整段与 `text` 完全相同时结果是 `unchanged`。
+- **可学的改动**(`edit_changes`):`text` → `corrected` 的替换里同时满足三条的。
+ 1. 插入的写法是识别原文的写法:它在 `raw_text → text` 的比较里落在相同的部分。这一步不分 ASCII 大小写,润色只改了大小写的地方仍然可学。`heard` 取识别原文里的写法。
+ 2. 词典和规则没碰过:重放这条记录当时触发过的词条和规则(`mcp::candidates::Replay`,与润色来源相同,§16.9)。改动与它们改过的位置重叠,或者重放直接把 `heard` 变成用户的写法,都不学;触发过的词条或规则已删除、或在这条记录之后改过时,这条记录不产生组合,改后的文字照样保存。词典或规则改错的地方,应该去改词条或规则。
+ 3. 长度和内容与润色来源相同(`replacements`):去掉首尾空白和标点后 1–64 个字符,两侧不同;只有新增、或只有删除的改动不学。
+
+ 润色改过的地方已经由润色来源覆盖,这里不再算。
+- 例子都是单元测试(`vocabulary::learn::tests`):整句「我在用 Quinn for max 做测试」改成「我在用 Qwen 4 max 做测试」,学到 Quinn for → Qwen 4;整次听写「Quinn for max」改成「Qwen 4 max」(相似度 5/11);开头多选了「Hi, 」;末尾的「注入」改成没有相同字的「测试」,两个字都算改动;连续两次听写一起改,两条记录各存自己的整段;没有相同的词是 `no_match`;改回原文时清除修改;词典改过的「github → GitHub」又改成 GitLab,不学。
+
+### 35.5 存储与历史详情
+
+- `HistoryEntry.corrected: Option>`,`CorrectedText { text, at_ms, via }`。`via` 是 `selection`(从选中文字学习)或 `follow`(以后的实验功能在输入框里读到的修改);这个版本只写 `selection`,两种都能读,所以以后的版本写的记录(经手机的历史副本同步回来,或者降级之后)照样能加载,历史详情把 `follow` 写成「在输入框中修改」。没有时不写出,旧版本读新记录不受影响,做法与 `processed` 相同。
+- `HistoryStore::set_corrected(id, Option)`:改 JSON,搜索文本加上改后的文字(`derived::search_text`),记 `revs`,所以会同步到配对手机的历史副本(手机不显示它)。`recent_texts` 读出 `HistoryText.corrected`(`json_extract(json, '$.corrected.text')`)。备份随历史记录一起导出;删除记录、清空历史时一起删除。
+- 历史详情(`apps/desktop/src/pages/history/DetailParts.tsx` 的 `CorrectedDetail`):有修改时多一行「之后改成」、改后的文字、「从选中文字学习 · 时间」和「移除」。「移除」调用 `history_clear_corrected { id }`(`set_corrected(id, None)`),这条记录给学习建议的「你的修改」随之消失。
+
+### 35.6 悬浮窗通知
+
+- `UiState.learn_notice: Option`,事件 `learn_notice { notice }`。`LearnNotice { id, outcome, shown, accepted?, undone? }`:`outcome` 是 `LearnOutcome`(按 `kind` 区分:`learned { pairs, safe }`、`no_pairs`、`unchanged`、`no_match`、`no_selection`、`too_long { max }`、`terminal`、`history_off`、`failed { message }`);`accepted` 是加入词典的结果 `{ added, refused, undo? }`;`undone` 是撤销的结果(`BatchUndoOutcome`)。
+- 悬浮窗关闭(`Settings.overlay = off`)时不创建通知:结果只写日志,改动照样保存,照样进学习建议。
+- 排队与计时由核心负责:
+ - 学习完成时听写空闲:通知立即显示(`shown`),开始计时 `LEARN_NOTICE_DWELL` = 8 秒(`CoreConfig.learn_notice_dwell`,测试里改短)。
+ - 上一次听写的终态还在悬浮窗上(常驻的结果卡片 §28,或还在停留时间内的完成提示):通知排队,不计时;听写回到空闲时才显示,从那时开始计时。
+ - 按钮操作后重新计时;时间到了由核心清掉;新的一次听写开始时,清掉排队中和显示中的通知;再学一次时,新通知替换旧的;× 立即清掉。
+- 桌面壳(`apps/desktop/src-tauri/src/overlay.rs`):听写空闲、通知已显示时,悬浮窗切到固定状态 `learned`(与 `copied` 共用 `show_fixed`),通知清掉后隐藏。结果卡片在屏幕上时通知不会处于已显示状态,所以不会盖住卡片。
+- 卡片(`apps/desktop/src/pages/Overlay.tsx` 的 `learnCard`):学到、加入、撤销成功时用结果卡片「已插入」的样子,其余用「失败」的样子。
+ - 「加入词典」→ `learn_notice_accept { id }`:核心对 `pairs` 运行 `suggest::accept_batch`,检查与词典页的批量加入相同,批次记进同一个 `BatchLog`。`safe` 为假时没有这个按钮。
+ - 「撤销」→ `learn_notice_undo { id }`,即整批撤销(§16.10)。
+ - 「查看」→ 壳命令 `open_suggestions`:主窗口收到 `voltip://tray` 的 `{ action: "suggestions" }`,打开词典页的学习建议(路由 `/dictionary/suggestions`)。同时调用 `learn_notice_keep { id }`,通知重新停留 8 秒,与其他按钮相同(D3)。
+ - 「打开设置」(只在 `history_off` 时)→ 壳命令 `open_privacy`(`{ action: "privacy" }`),打开 设置 › 隐私与历史,同样调用 `learn_notice_keep { id }`。计划里写的是沿用学习建议页的按钮,但悬浮窗不能让主窗口换页,所以与「查看」一样新增了一个壳命令。
+ - × → `learn_notice_dismiss { id }`。
+- 文案(`learn.notice`):
+
+| 情形 | 中文 | English |
+|---|---|---|
+| `learned`,1 处 / 多处 | 已记下 1 处改动:A → B / 已记下 n 处改动:A → B 等 | Noted 1 change: A → B / Noted n changes: A → B and more |
+| 加入后 | 已加入词典:A → B / 已将 n 处改动加入词典 · 撤销 | Added to the dictionary: A → B / Added n changes to the dictionary · Undo |
+| 部分加入 | a 处已加入,r 处无法加入 · 查看 · 撤销 | a added, r couldn't be added · View · Undo |
+| 都没加入 | 无法加入词典,原因见词典页 · 查看 | Couldn't add to the dictionary; the dictionary page says why · View |
+| 撤销后 | 已撤销 / 无法撤销 · 查看 | Undone / Couldn't undo · View |
+| `no_pairs` | 没有可以加入词典的改动 | No change to add to the dictionary |
+| `unchanged` | 选中的文字和听写结果相同 | The selection matches what was dictated |
+| `no_match` | 最近 50 次听写里没有找到这段文字 | Not found in the last 50 dictations |
+| `no_selection` | 没有选中文字 | Nothing is selected |
+| `too_long` | 选中的文字太长,最多 8000 字 | The selection is too long (8000 characters at most) |
+| `terminal` | 终端里的文字不能用来学习 | Text in a terminal can't be learned from |
+| `history_off` | 需要先开启历史记录 · 打开设置 | Turn on the history first · Open settings |
+| `failed` | 无法读取选中的文字:原因 | Couldn't read the selection: reason |
+
+### 35.7 学习建议
+
+用户修改是学习建议的第二个来源,与单字扩展、「推荐」的显示范围一起写在 §16.10。快捷键还没设置时,学习建议的说明卡里有「设置快捷键」,打开 设置 › 快捷键。
+
+### 35.8 门禁
+
+- Rust:`vocabulary::learn::tests` 12 条(上面的例子,以及 CRLF、末尾空白、`storable`);`vocabulary::suggest` 的新用例(两个来源合并与 `from_edits`、单字扩展选边「钉丁 → 钉钉」、通知的组合 `edit_picks`);`history::tests` 的修改读写与搜索;`crates/voltip-core/tests/learn.rs` 4 条(四个组合键互斥;选区改正听写:保存修改、通知排队后显示、加入词典与撤销、到时清掉、复制时松开快捷键的修饰键;常驻的结果卡片关闭后才显示、新的听写清掉通知、悬浮窗关闭时没有通知;各种拒绝);bridge 契约夹具(`commands.json`、`events.json`、`state.json`、`vocabulary-suggestions.json`);`hotkey.rs` 的 `learn_fires_on`、`overlay.rs` 的 `learned_wanted`;桌面命令层 `apps/desktop/src-tauri/tests/ipc.rs@learning_from_the_selection_runs_through_the_command_layer`。2026-11-18 目标评审之后补的回归测试,都先在原代码上看到失败:`crates/voltip-core/tests/learn.rs@regression_a_terminal_the_voice_edit_allows_is_still_not_learned_from` 与 `crates/voltip-platform/src/insert_check.rs@regression_every_hosts_terminals_hold_program_output`(macOS 的终端)、`crates/voltip-inject/src/selection.rs@regression_two_copies_at_once_neither_read_nor_lose_the_users_clipboard`(两次复制同时进行)、`vocabulary::learn::tests::regression_the_original_wording_takes_back_a_correction_that_shares_no_word_with_it`、`history::tests::regression_a_correction_read_in_the_field_loads`(`follow`)、`vocabulary::learn::tests::regression_the_alignment_that_wins_rebuilds_the_take` 与 `regression_a_selection_that_stops_before_the_next_word_keeps_the_space`(第 2 轮)、`vocabulary::suggest::tests::regression_a_correction_counts_once_per_take_and_a_skipped_one_is_still_edited` 与 TS 的同名用例、`crates/voltip-core/tests/learn.rs@regression_view_and_open_settings_start_the_notices_stay_again`、词典页 `regression: with only corrected takes and nothing new, …`(空状态按比较过的记录写)。
+- TS:`suggestions.test.ts`、`mock-backend.test.ts` 的 §35 用例、`ipc-contract.test.ts`、`tauri-backend.test.ts`;`apps/desktop` 的 `Overlay.test.tsx`(卡片的按钮与状态)、`Settings.test.tsx`(快捷键行)、`HistoryDetail.test.tsx`(修改的一行与移除)、`Dictionary.test.tsx`(来源标记、「推荐」、设置快捷键的提示)、`tray-requests.test.tsx` 与 `router.test.tsx`(「查看」「打开设置」)。
+- 真机:
+ - Linux(CI `smoke-desktop`):`crates/voltip-inject/tests/real_display.rs` 的 `real_copy_chord_reads_the_selection_of_an_x11_text_widget` 与 `regression_x11_hotkey_grab_swallows_the_copy_until_the_key_is_up` 现在每次都跑(需要 `python3-tk`);`scripts/smoke-desktop-linux.sh` 在真实应用上走一遍:预先设好学习快捷键,冒烟听写之后,Tk 输入框里放改正后的文字并全选,xdotool 按下真实的组合键,检查日志的 `learn selection outcome="learned"`、`history.sqlite3` 里那条记录的 `corrected`、剪贴板放回哨兵内容、悬浮窗显示通知(截图 `*-learn-notice.png`)。
+ - Windows(CI `hooks-windows`):`crates/voltip-focus/tests/focus_windows.rs@the_copy_reads_notepads_selection_with_the_shortcut_held_and_puts_the_clipboard_back`:记事本里粘贴文字、全选,按住 Ctrl+Alt 时复制,读到这段文字,剪贴板放回原样。
+ - macOS(CI `macos` 的 Apple 芯片一路,合并前手动触发):`crates/voltip-focus/tests/focus_macos.rs` 在 TextEdit 里粘贴后全选,用 Cmd+C 读到这段文字,剪贴板放回原样。
+ - 计划里这两个测试是 voltip-inject 下新建的测试文件;实际放进了 voltip-focus 已有的测试,那里已经会打开记事本和 TextEdit,CI 也已经给它的测试二进制授予了辅助功能权限。
+
+### 35.9 限制
+
+- 复制靠应用响应复制键(Windows / Linux 是 Ctrl+Insert,macOS 是 Cmd+C,§19.2);不响应的应用里结果是 `no_selection`。
+- 只比较最新 50 条听写;更早的听写改正后选中也学不到(`no_match`)。
+- 触发过的词条或规则在这条记录之后改过时,这条记录不产生「你的修改」(与润色来源相同的局限,§16.9)。
+- 手机没有这个功能;手机的历史副本带着修改,但不显示。
diff --git a/docs/site/README.md b/docs/site/README.md
index c1fe88f9..767ae32c 100644
--- a/docs/site/README.md
+++ b/docs/site/README.md
@@ -138,7 +138,8 @@ pnpm -C apps/desktop dev --host 127.0.0.1 --port 1430
captures, 夜空 (Night Sky) for the `dark` ones — and the language in 设置 › 通用. The
overlay sheet has no sidebar: go back home to switch, then return to `/overlay`. For the
dictionary's learning suggestions, open it at `/?history=suggestions`: the sample history
- then has older polished takes, so some pairs are seen twice or more.
+ then has older polished takes, so some pairs are seen twice or more, and two takes the user
+ corrected with Learn from selection, so both sources show.
2. Page captures are viewport screenshots at device pixel ratio 1, saved as WebP at
quality 85.
3. The overlay pills, `overlay---.webp`, come from `/overlay` at device
diff --git a/docs/site/dictation/shortcuts.md b/docs/site/dictation/shortcuts.md
index 2894c4d3..fb834d4d 100644
--- a/docs/site/dictation/shortcuts.md
+++ b/docs/site/dictation/shortcuts.md
@@ -1,5 +1,5 @@
---
-description: The dictation shortcut, the three recording modes, starting with a single key or a mouse button, the overlay, cancelling with Esc, the shortcut that copies the last result, and what and how long a dictation records.
+description: The dictation shortcut, the three recording modes, starting with a single key or a mouse button, the overlay, cancelling with Esc, the shortcuts that copy the last result and learn from a selection, and what and how long a dictation records.
---
# Shortcuts and recording modes
@@ -77,7 +77,11 @@ On a pure Wayland session, bind a system shortcut to `voltip-desktop --cancel` i
## Copy the last result
-Under **Settings → Shortcuts**, **Copy last result** takes a shortcut of its own, none by default. Pressing it puts the latest result on the clipboard without opening Voltip, and the overlay says **Copied the last result**. It must differ from the dictation and voice edit shortcuts. The tray menu on Windows and macOS has the same command, see [Copy or paste a result again](/dictation/output#copy-or-paste-a-result-again).
+Under **Settings → Shortcuts**, **Copy last result** takes a shortcut of its own, none by default. Pressing it puts the latest result on the clipboard without opening Voltip, and the overlay says **Copied the last result**. It must differ from the dictation, voice edit and Learn from selection shortcuts. The tray menu on Windows and macOS has the same command, see [Copy or paste a result again](/dictation/output#copy-or-paste-a-result-again).
+
+## Learn from selection
+
+Under **Settings → Shortcuts**, **Learn from selection** takes a shortcut of its own, none by default. After you correct a dictation in another app, select the corrected text and press it: Voltip notes the change for the dictionary's suggestions, and the overlay shows the change it noted. It must differ from the dictation, voice edit and Copy last result shortcuts. See [Learn from selection](/recognition/dictionary#learn-from-selection) for how to use it.
## Recording source
@@ -115,5 +119,6 @@ A pure Wayland session does not let apps register global shortcuts or watch sing
| `voltip-desktop --edit-toggle` | Starts or finishes a [voice edit](/dictation/voice-edit) |
| `voltip-desktop --cancel` | Cancels the current dictation |
| `voltip-desktop --copy-last` | Puts the latest result on the clipboard |
+| `voltip-desktop --learn-selection` | [Learns from the selected text](/recognition/dictionary#learn-from-selection) |
When Voltip runs as an AppImage, use the AppImage's path instead of `voltip-desktop`; Settings → Shortcuts shows the exact command. In a session that runs X11 apps through XWayland, the shortcut works only while an X11 window has the focus, so a system shortcut is the reliable choice there as well.
diff --git a/docs/site/privacy.md b/docs/site/privacy.md
index 38190f1c..f97be7f6 100644
--- a/docs/site/privacy.md
+++ b/docs/site/privacy.md
@@ -64,6 +64,10 @@ With **Keep recordings on this computer** on (the default), the recordings of di
To check that a paste arrived, Voltip reads the input field that has the focus on this computer right before and right after the paste, and compares its length, the caret and the selection, the selected text and up to 64 characters before the caret. To get them it may read more: on Windows, and in fields that only give their whole content, Voltip reads all of the field's text (up to about a million characters; longer text is not read) and works these out from it. What it reads stays in memory for the moment of the paste and is then discarded; it is never saved, uploaded or written to the log, which records only the outcome, how long the check took and the app's identifier. Password fields, terminals and remote desktops are not read, nor is a field when Voltip cannot tell which app the text went to. Switch the check off with **Check that the text was written** under **Settings → Dictation**; see [Checking that the text arrived](/dictation/output#checking-that-the-text-arrived).
+## Learn from selection
+
+Only when you press the **Learn from selection** shortcut (or run `voltip-desktop --learn-selection`) does Voltip read the text selected in the app in front, once: it presses the copy keys, reads the selection from the clipboard and puts the clipboard back as it was; while it reads, other programs that read the clipboard (a clipboard manager, for example) may see the text. In a terminal nothing is read and no key is pressed; a selection of more than 8000 characters is not used. The selection is compared on this computer with your last 50 dictations only, sent to no service and never to AI; the log records only the outcome, how many entries and how many characters. When it corrects a dictation, the corrected text of that dictation is kept in its history entry: it is backed up and synced to paired phones with the history, deleted with the entry or when the history is cleared, and can be removed on its own in the entry's details. With the history off, nothing is read or kept. See [Learn from selection](/recognition/dictionary#learn-from-selection).
+
## The local service
When the [local service](/recognition/service) is on, programs on this computer that have its access token can send recordings to Voltip. Each recording is processed like a dictation with the same settings: it goes to the recognition service in use, and its text to the AI service when AI polish applies. While a request is processed, its audio is kept in a temporary file in Voltip's data folder, which is deleted when the request ends. Requests are not added to the history, and the service's log records durations and the models used, never the text or the audio.
@@ -74,7 +78,7 @@ With [AI tools](/recognition/mcp) turned on, AI tools on this computer that hold
## What stays on your computer
-- **History**: every dictation, stored in Voltip's data folder. It can be limited, turned off or cleared under **Settings → Privacy and history**.
+- **History**: every dictation, and the text you corrected with **Learn from selection**, stored in Voltip's data folder. It can be limited, turned off or cleared under **Settings → Privacy and history**.
- **Recordings**: with **Keep recordings on this computer** on, the recordings of your latest dictations, in the same folder; see [The microphone and computer audio](#the-microphone-and-computer-audio).
- **Dictionary, rules, scenes and settings**: in the same folder.
- **Backup files**: a backup exported under **Settings → Privacy and history** is saved where you choose. It holds the history, the dictionary, the rules, the scenes and your own AI presets, but no settings or keys, and it is not encrypted; see [Backup and moving to another computer](/dictation/history#backup-and-moving-to-another-computer). The automatic backups, made every week, before an update and before an import replaces data, hold the same and are saved in the `backups` folder of Voltip's data folder or in the folder you choose, each computer keeping its own latest 5; in a synced folder they are uploaded with it, and Voltip does not sync data between computers, see [Automatic backups](/dictation/history#automatic-backups).
diff --git a/docs/site/public/screens/dictionary-suggestions-en-light.webp b/docs/site/public/screens/dictionary-suggestions-en-light.webp
index 9533edbd..f7b921ad 100644
Binary files a/docs/site/public/screens/dictionary-suggestions-en-light.webp and b/docs/site/public/screens/dictionary-suggestions-en-light.webp differ
diff --git a/docs/site/public/screens/dictionary-suggestions-zh-light.webp b/docs/site/public/screens/dictionary-suggestions-zh-light.webp
index 2bb868a6..b1a7098e 100644
Binary files a/docs/site/public/screens/dictionary-suggestions-zh-light.webp and b/docs/site/public/screens/dictionary-suggestions-zh-light.webp differ
diff --git a/docs/site/recognition/dictionary.md b/docs/site/recognition/dictionary.md
index 2e8cad22..f03afef3 100644
--- a/docs/site/recognition/dictionary.md
+++ b/docs/site/recognition/dictionary.md
@@ -107,13 +107,18 @@ To let AI tools such as Claude Code or Codex analyse the history with your proje
## Suggestions
-**Suggestions**, at the top of the Dictionary page, lists the spellings AI polish corrected in your recent history: what was recognised, what it was polished to, how many times and when last, the most frequent first. Spellings the dictionary already corrects and pairs you ignored are left out. Voltip compares the recognised text with the polished text character by character; no AI is used and nothing is sent anywhere.
+**Suggestions**, at the top of the Dictionary page, lists the spellings that were corrected in your recent history: what was recognised, the right spelling, how many times and when last, the most frequent first. The corrections come from two sources, and each row names its source:
+
+- **Polish**: spellings AI polish corrected.
+- **Your correction**: spellings you corrected in another app and gave to Voltip with [Learn from selection](#learn-from-selection). Errors that neither recognition nor polish got right can be learned this way.
+
+Spellings the dictionary already corrects and pairs you ignored are left out. Voltip compares the recognised text, the polished text and your corrected text character by character; no AI is used and nothing is sent anywhere.
+ alt="Suggestions on the Dictionary page, showing the five Suggested pairs, each marked with its source, Polish or Your correction: 维他命 → Voltip has both, and Quinn for → Qwen 4 was seen once, from your correction. The first two were added to the dictionary together: the line above the list says “Added 2 pairs to the dictionary.” and has Undo. The pairs for 瑞迪斯 and 泰普斯克瑞普特 are checked, and the bar above the list adds or ignores them at once. Under the explanation, a line offers to set the Learn from selection shortcut. The line under the list says 2 entries have your corrections, 5 pairs are shown and 4 pairs seen once are hidden."
+ caption="Each pair names its source; check several rows to add them to the dictionary or ignore them at once, and Undo takes back the whole batch." />
-- By default the list shows the pairs seen twice or more; choose **All** above the list to include the ones seen once. The number after **Suggestions** counts the pairs left to decide in the current view, and the line under the list says how many pairs are shown and how many seen once are hidden.
+- By default the list shows the **Suggested** pairs: those seen twice or more, and those you corrected (even once). Choose **All** above the list to include the other pairs seen once. The number after **Suggestions** counts the pairs left to decide in the current view, and the line under the list says how many pairs are shown, how many entries carry your corrections, and how many pairs seen once are hidden.
- **Add to dictionary** adds the recognised spelling as a heard-as form: to the entry that already has the right spelling, or to a new entry. When a replacement rule would change the right spelling, or the spelling belongs to another entry, Voltip says why and saves nothing.
- **Ignore** keeps the pair off the list and moves it to **Ignored** below.
- Check several rows, or **Select all** in the header, to add them all to the dictionary or ignore them at once. Pairs with the same right spelling go into one entry; when a pair cannot be added, the reason is under its row and the others are added.
@@ -122,7 +127,24 @@ To let AI tools such as Claude Code or Codex analyse the history with your proje
- Expand a row to see the recognised text it appeared in, and how many of your recent entries adding it would change. Voltip warns when the spelling is a single character, which can change other words by mistake.
- **Ignored (n)** lists the pairs you ignored, the most recent first, with when you ignored each. **Stop ignoring** puts a pair back among the suggestions. The list stays after you leave the page or restart Voltip.
-Suggestions come from the history: while history is off, the view only says that history needs to be on, and dictations without AI polish and imported audio or video files are not compared. Chinese is compared character by character: when 非书 was polished to 飞书, the pair listed is 非 → 飞. Suggestions are available on the computer only.
+Suggestions come from the history: while history is off, the view only says that history needs to be on; imported audio or video files are not compared, and a dictation with neither AI polish nor a correction of yours has nothing to compare. Chinese is compared character by character; when only one character changed, the pair listed takes the character next to it as well: when 非书 was corrected to 飞书, the pair listed is 非书 → 飞书. Suggestions are available on the computer only.
+
+## Learn from selection
+
+After you correct a dictation in another app, you can give Voltip the corrected text: it notes the change and adds it to the suggestions.
+
+1. Under **Settings → Shortcuts**, set a shortcut for **Learn from selection**. It is not set by default, and it must differ from the shortcuts for dictation, voice editing and copying the last result.
+2. When the inserted text has an error, correct it where it is, for example “I'm testing Quinn for max” to “I'm testing Qwen 4 max”.
+3. Select the corrected text and press the shortcut. Selecting a little more or less is fine, and so is a selection over several dictations in a row.
+4. The overlay shows “Noted 1 change: Quinn for → Qwen 4”. **Add to dictionary** adds it at once, and you can undo it; **View** opens the suggestions. You can also leave it: the change stays among the suggestions, marked **Your correction**.
+
+- Voltip reads the selection by copying it, and puts the clipboard back afterwards. In a terminal it reads nothing and presses no key.
+- Voltip looks for the dictation the selection corrects among your last 50 dictations. When none matches, the selection is the same as what was dictated, or nothing is selected, the overlay says so.
+- The corrected text is kept with that history entry: its details gain a **Later corrected to** line, and **Remove** deletes it. Learn from selection needs the history to be on.
+- When a change has a spelling of one character or one or two letters, the overlay offers **View** only: check what it would change on the dictionary page before adding it.
+- The overlay stays for 8 seconds, counted again after each button, and goes when the next dictation starts. While a dictation's result card is on screen, it appears after the card is closed.
+- In a pure Wayland session, bind a shortcut to the command `voltip-desktop --learn-selection` in the system settings.
+- Learn from selection is available on the computer only.
## Simplified and Traditional Chinese
diff --git a/docs/site/zh/dictation/shortcuts.md b/docs/site/zh/dictation/shortcuts.md
index 0cc82f60..b5142445 100644
--- a/docs/site/zh/dictation/shortcuts.md
+++ b/docs/site/zh/dictation/shortcuts.md
@@ -1,5 +1,5 @@
---
-description: 听写快捷键、三种录音方式、用单个按键或鼠标键开始听写、悬浮窗、用 Esc 取消、复制上一条结果的快捷键,以及录音来源与录音时长。
+description: 听写快捷键、三种录音方式、用单个按键或鼠标键开始听写、悬浮窗、用 Esc 取消、复制上一条结果和从选中文字学习的快捷键,以及录音来源与录音时长。
---
# 快捷键与录音方式
@@ -77,7 +77,11 @@ Windows 有时会停止 Voltip 对单个按键的监听,例如电脑一时非
## 复制上一条结果
-「设置 → 快捷键」中的「复制上一条结果」可以设置单独的快捷键,默认未设置。按下后,Voltip 把最近一次结果放到剪贴板,不打开主窗口,悬浮窗显示「已复制上一条结果」。它必须与听写和语音编辑的快捷键不同。Windows 和 macOS 的托盘菜单中也有这一项,见[再次复制或粘贴结果](/zh/dictation/output#再次复制或粘贴结果)。
+「设置 → 快捷键」中的「复制上一条结果」可以设置单独的快捷键,默认未设置。按下后,Voltip 把最近一次结果放到剪贴板,不打开主窗口,悬浮窗显示「已复制上一条结果」。它必须与听写、语音编辑和从选中文字学习的快捷键不同。Windows 和 macOS 的托盘菜单中也有这一项,见[再次复制或粘贴结果](/zh/dictation/output#再次复制或粘贴结果)。
+
+## 从选中文字学习
+
+「设置 → 快捷键」中的「从选中文字学习」可以设置单独的快捷键,默认未设置。在其他应用里改正听写结果后,选中改好的文字按下它,Voltip 会记下改动,放进词典的学习建议,悬浮窗显示记下的改动。它必须与听写、语音编辑和复制上一条结果的快捷键不同。用法见[从选中文字学习](/zh/recognition/dictionary#从选中文字学习)。
## 录音来源
@@ -115,5 +119,6 @@ Windows 有时会停止 Voltip 对单个按键的监听,例如电脑一时非
| `voltip-desktop --edit-toggle` | 开始或结束一次[语音编辑](/zh/dictation/voice-edit) |
| `voltip-desktop --cancel` | 取消当前的听写 |
| `voltip-desktop --copy-last` | 把最近一次结果放到剪贴板 |
+| `voltip-desktop --learn-selection` | [从选中文字学习](/zh/recognition/dictionary#从选中文字学习) |
以 AppImage 运行时,把 `voltip-desktop` 换成 AppImage 的路径;「设置 → 快捷键」会显示完整命令。在通过 XWayland 运行 X11 应用的会话中,组合键只在 X11 窗口获得焦点时有效,因此同样建议使用系统快捷键。
diff --git a/docs/site/zh/privacy.md b/docs/site/zh/privacy.md
index 2c966b95..f6c29f9a 100644
--- a/docs/site/zh/privacy.md
+++ b/docs/site/zh/privacy.md
@@ -64,6 +64,10 @@ description: 在各种使用方式下 Voltip 把哪些内容发送到哪里,
为了确认粘贴是否写入,Voltip 在粘贴前后各读取一次这台电脑上获得焦点的输入框,比较其中的长度、光标与选区、选中的文字,以及光标前最多 64 个字。为了得到这些内容,读取的范围可能更大:在 Windows 上,以及只能整段读取内容的输入框里,Voltip 读取输入框的全部文字(不超过约一百万个字符,更长的不读取),再从中得出上述几项。读取的内容只在粘贴的这一刻保留在内存中用于比较,随后即丢弃;不保存、不上传,也不写入日志,日志只记录结果、检查用时和应用的标识。Voltip 不读取密码框、终端和远程桌面;无法判断文字粘贴到了哪个应用时,也不读取输入框。可以关闭「设置 → 听写」中的「检查文字是否写入」,见[确认文字已写入](/zh/dictation/output#确认文字已写入)。
+## 从选中文字学习
+
+只在你按下「从选中文字学习」的快捷键(或运行 `voltip-desktop --learn-selection`)时,Voltip 读取一次当前应用中选中的文字:它按下复制键,从剪贴板读出选中的文字,再把剪贴板恢复为原来的内容;读取期间,读取剪贴板的其他程序(例如剪贴板管理器)可能看到这段文字。前台是终端时不读取,也不按任何键;超过 8000 字的选区不处理。选中的文字只与最近 50 次听写在本机比较,不发送给任何服务,也不调用 AI;日志只记录结果、条数和字数。找到对应的听写时,改正后的这一段文字保存在这条历史记录中,随历史记录一起备份、同步到已配对的手机,删除记录或清空历史记录时一并删除,也可以在记录详情中单独移除。历史记录关闭时不读取、不保存。见[从选中文字学习](/zh/recognition/dictionary#从选中文字学习)。
+
## 本机服务
开启[本机服务](/zh/recognition/service)后,这台电脑上持有访问令牌的程序可以把录音发送给 Voltip。每段录音都按与相同设置下的听写一样的方式处理:录音发送给当前使用的识别服务,需要 AI 润色时,文字发送给 AI 服务。处理请求期间,音频保存在 Voltip 数据目录中的临时文件里,请求结束后即删除。这些请求不会写入历史记录;服务的日志只记录时长和所用的模型,不记录文字和音频。
@@ -74,7 +78,7 @@ description: 在各种使用方式下 Voltip 把哪些内容发送到哪里,
## 保存在本机的内容
-- **历史记录**:每次听写的结果,保存在 Voltip 的数据目录中。可以在「设置 → 隐私与历史」中限制条数、关闭或清空。
+- **历史记录**:每次听写的结果,以及你用「从选中文字学习」改正后的文字,保存在 Voltip 的数据目录中。可以在「设置 → 隐私与历史」中限制条数、关闭或清空。
- **录音**:开启「在本机保留录音」时,最近几次听写的录音保存在同一目录中,见[麦克风与电脑声音](#麦克风与电脑声音)。
- **词典、规则、场景和设置**:保存在同一目录中。
- **备份文件**:在「设置 → 隐私与历史」中导出的备份保存在你选择的位置,包含历史记录、词典、规则、场景和自定义 AI 预设,不含设置和密钥。备份文件未加密,见[备份与迁移](/zh/dictation/history#备份与迁移)。每周、更新安装前和替换导入前的自动备份包含同样的内容,保存在 Voltip 数据目录下的 `backups` 文件夹或你选择的文件夹中,每台电脑只保留自己最近 5 份;放在同步盘中会随同步上传,Voltip 不会在电脑之间同步数据,见[自动备份](/zh/dictation/history#自动备份)。
diff --git a/docs/site/zh/recognition/dictionary.md b/docs/site/zh/recognition/dictionary.md
index 3c40e419..42186126 100644
--- a/docs/site/zh/recognition/dictionary.md
+++ b/docs/site/zh/recognition/dictionary.md
@@ -107,13 +107,18 @@ case_sensitive = false
## 学习建议
-「词典」页顶部的「学习建议」列出 AI 润色在最近的历史记录中改正过的写法:识别成什么、润色后是什么、出现了几次、最近一次是什么时候,次数多的在前。词典已经纠正的写法和你忽略过的写法不会列出。Voltip 只逐字比较识别原文和润色后的文字,不调用 AI,也不发送任何内容。
+「词典」页顶部的「学习建议」列出最近的历史记录中被改正过的写法:识别成什么、正确写法是什么、出现了几次、最近一次是什么时候,次数多的在前。改正有两个来源,每一行都标明来源:
+
+- **润色**:AI 润色改正过的写法。
+- **你的修改**:你在其他应用里改正、再用[从选中文字学习](#从选中文字学习)交给 Voltip 的写法。识别和润色都没有改对的错误,可以这样学到。
+
+词典已经纠正的写法和你忽略过的写法不会列出。Voltip 只逐字比较识别原文、润色后的文字和你改正后的文字,不调用 AI,也不发送任何内容。
+ alt="「词典」页的「学习建议」:「推荐」范围显示五组写法,每组写法后标出来源「润色」或「你的修改」,「维他命 → Voltip」两个来源都有,「Quinn for → Qwen 4」只出现 1 次、来自你的修改。前两组已一次加入词典,列表上方写明「已将 2 组加入词典。」并带「撤销」;「瑞迪斯」和「泰普斯克瑞普特」两组已勾选,上方的选择栏可以一次加入词典或忽略。说明卡下方提示可以设置「从选中文字学习」的快捷键。列表下方写明 2 条记录有你的修改、显示 5 组、隐藏 4 组只出现 1 次的建议。"
+ caption="每组写法标出来源;勾选几行,一次加入词典或忽略,点「撤销」撤回整批。" />
-- 列表默认只列出出现 2 次及以上的写法;在列表上方选择「全部」,只出现过 1 次的写法也会列出。「学习建议」后面的数字是当前范围内尚未处理的组数,列表下方写明显示了多少组、隐藏了多少组只出现 1 次的写法。
+- 列表默认显示「推荐」的写法:出现 2 次及以上的,以及你改正过的(只出现 1 次也显示)。在列表上方选择「全部」,其余只出现过 1 次的写法也会列出。「学习建议」后面的数字是当前范围内尚未处理的组数,列表下方写明显示了多少组、有几条记录带有你的修改、隐藏了多少组只出现 1 次的写法。
- 「加入词典」把识别成的写法加入词典:正确写法已经是某个词条时,加到这个词条的曾听成写法中;否则新建一个词条。如果某条替换规则会改掉这个正确写法,或者这个写法已属于其他词条,Voltip 会说明原因,不会保存。
- 「忽略」让这组写法不再出现在列表中,它会列在下方的「已忽略」里。
- 勾选几行,或勾选表头的「全选」,可以一次把它们全部加入词典或忽略。正确写法相同的几组会加入同一个词条;某一组无法加入时,原因写在这一行下面,其余各组照常加入。
@@ -122,7 +127,24 @@ case_sensitive = false
- 展开一行,可以看到这组写法出现在哪些识别原文中,以及加入后会改动最近多少条记录。写法只有 1 个字时,Voltip 会提醒它容易误改其他词语。
- 「已忽略(n)」列出你忽略过的写法,最近忽略的在前,并写出忽略的时间。点「取消忽略」,这组写法会重新出现在学习建议中。离开词典页或重启 Voltip 后,这个列表还在。
-学习建议来自历史记录:历史记录关闭时,这里只提示需要开启历史记录;没有经过 AI 润色的听写和导入的音视频文件不参与比较。中文按字比较,例如「非书」被润色成「飞书」时,列出的是「非 → 飞」。学习建议只在电脑上提供。
+学习建议来自历史记录:历史记录关闭时,这里只提示需要开启历史记录;导入的音视频文件不参与比较,没有经过 AI 润色、也没有你的修改的听写没有可以比较的内容。中文按字比较;只改了 1 个字时,列出的写法会带上相邻的一个字,例如「非书」被改成「飞书」时,列出的是「非书 → 飞书」。学习建议只在电脑上提供。
+
+## 从选中文字学习
+
+在其他应用里改正了听写结果之后,可以把改好的文字交给 Voltip,它会记下改动,放进学习建议。
+
+1. 在「设置 → 快捷键」中为「从选中文字学习」设置一个快捷键。这个快捷键默认未设置,不能与听写、语音编辑、复制上一条结果的快捷键相同。
+2. 听写插入的文字有误时,在原来的位置把它改正,例如把「我在用 Quinn for max 做测试」改成「我在用 Qwen 4 max 做测试」。
+3. 选中改好的文字,按下这个快捷键。多选或少选一些都可以,也可以一次选中连续几次听写的文字。
+4. 悬浮窗显示「已记下 1 处改动:Quinn for → Qwen 4」。点「加入词典」直接加入词典,之后可以撤销;点「查看」打开学习建议。不做处理也可以,这组改动会留在学习建议中,标为「你的修改」。
+
+- Voltip 用复制的方式读取选中的文字,读取后剪贴板恢复原来的内容。终端里不读取,也不按任何键。
+- Voltip 在最近 50 次听写中查找与选中文字对应的记录。找不到、选中的文字与听写结果相同、没有选中文字时,悬浮窗会说明原因。
+- 改正后的文字保存在这条历史记录中,记录详情会多出一行「之后改成」,点「移除」可以删除它。历史记录关闭时无法使用这项功能。
+- 改动里有只有 1 个字或 1–2 个字母的写法时,悬浮窗只提供「查看」,请在词典页确认影响范围后再加入。
+- 悬浮窗停留 8 秒,点按钮后重新计时,下一次听写开始时消失。听写结果的卡片还在屏幕上时,它会在卡片关闭之后出现。
+- 在纯 Wayland 会话中,请在系统设置里为命令 `voltip-desktop --learn-selection` 绑定快捷键。
+- 这项功能只在电脑上提供。
## 简体与繁体
diff --git a/docs/threat-model.md b/docs/threat-model.md
index d421adba..184e17ea 100644
--- a/docs/threat-model.md
+++ b/docs/threat-model.md
@@ -20,6 +20,7 @@
| 本机语音服务被其他用户、网页或局域网滥用(`docs/dictation.md` §23) | 默认只监听回环地址,`voltip-server` 监听其他地址必须加 `--allow-remote`(并警告明文),App 只监听 127.0.0.1;除 `/healthz` 外每个请求都要 32 字节随机令牌(0600 文件,常量时间比较,可随时更换),没有关闭认证的选项;不返回 CORS 头,网页读不到响应;并发与排队有上限,时长、请求体和字段有界限,原始上传不落盘;日志不记文字、音频和令牌;无头服务端只读钥匙串与 App 的文件;没有钥匙串时可以从 `VOLTIP_KEY_*` 环境变量读取密钥(只在 voltip-server,文档建议 0600 的 EnvironmentFile;同一用户的进程能读到服务的环境变量,这一点写在文档里),`--check` 和日志只给变量名 | `the_token_guards_everything_but_the_health_check`、`malformed_and_oversized_requests_are_refused`、`a_waiting_request_reads_nothing_until_it_has_a_permit_and_a_full_queue_is_refused`(`voltip-serve`);`the_command_line_names_the_service_and_its_one_shot_actions`、`print_token_creates_the_token_once_and_prints_it_again`(`voltip-server`);`peek` 的零写入测试(`voltip-identity`);`keys_from_the_environment_win_over_the_keychain_and_are_named_never_printed`(`voltip-server`) |
| 代理看到或改动 Voltip 的流量(`docs/dictation.md` §24) | 代理只转发:`https://` 的请求(内置服务、服务商的默认地址、更新源、反馈服务)仍是端到端的 TLS(证书照常校验),中继里的内容还有 Noise E2EE,代理能看到的是要连接的主机和流量的大小与时间。用户自填的 `http://` 自定义端点(远程地址也允许)经过代理时是明文,代理能读到并改动录音、文字和密钥,与没有代理时网络路径上的风险相同;隐私页提醒改用 `https://` 或把它列入不使用代理的地址;本机地址(本地模型服务、本机语音服务)从不发给代理;手动代理的密码只在钥匙串,`settings.json`、界面、状态、日志里都没有;日志与错误不记代理的地址和用户名密码;`socks5h` 让代理解析域名,`socks5` 在本机解析 | `a_stream_tunnels_through_an_http_proxy_with_its_credentials`、`a_local_stream_goes_direct_and_a_refused_tunnel_names_no_host`、`a_client_follows_the_plan_from_one_request_to_the_next`(`voltip-net`);`the_relay_connects_through_the_saved_proxy_with_the_keychain_password`(`voltip-core`);`no proxy applies at once; a manual proxy is checked, saved tidy, its password kept out of view`(桌面) |
| AI 工具接入(本机 MCP 服务,`docs/dictation.md` §25)被其他程序、网页或历史里的提示注入滥用 | 默认关闭,只监听 127.0.0.1,没有监听其他地址的选项;除 `/healthz` 外每个请求都要 32 字节随机令牌(0600 文件,与本机语音服务的令牌分开,常量时间比较,可随时更换,换后立即生效);`Host` 只认 `127.0.0.1:{port}` / `localhost:{port}`(防 DNS rebinding),带 `Origin` 的请求一律拒绝,不返回 CORS 头,网页读不到响应;读取分三级(仅词典和规则 / 替换汇总(缺省)/ 完整历史),完整历史要用户在确认框里显式允许并限定时间范围,权限在每次调用时检查、收回立即生效;修改缺省只能写词典,外部工具新建的规则在用户启用前不执行(历史文本是不可信数据,可能带提示注入,规则会改写插入到任何应用里的文字),没有删除工具,每次写入都记在活动记录里并可撤销;最多 16 个会话、每会话每秒 10 次调用、单次结果 256 KiB;日志不记请求和结果里的文字;令牌与接入命令由核心放进剪贴板,不经过 webview | `crates/voltip-mcp/tests/http.rs@requests_without_the_token_or_from_a_web_page_are_refused`、`crates/voltip-mcp/tests/http.rs@the_levels_of_the_moment_decide_each_call`、`crates/voltip-mcp/tests/http.rs@a_clients_rule_waits_and_its_writes_can_be_undone`、`crates/voltip-mcp/tests/http.rs@sessions_and_calls_are_limited`、`crates/voltip-mcp/tests/http.rs@a_new_token_and_switching_off_take_effect_at_once`、`crates/voltip-mcp/tests/http.rs@the_logs_hold_no_text`;`crates/voltip-core/tests/mcp.rs@reads_follow_the_read_level_of_the_moment`、`crates/voltip-core/tests/mcp.rs@a_tools_rule_waits_for_approval_and_runs_once_approved` |
+| 从选中文字学习(`docs/dictation.md` §35)读到不该读的文字,或把它留在别处 | 只在用户按下快捷键(或运行 `--learn-selection`)时读一次:前台是终端时不按任何键;选区经剪贴板读取,做法与语音编辑相同(§19.2:先保存剪贴板全部内容,读完放回,期间用户另复制的内容不覆盖);超过 8000 字不处理;只与最新 50 条听写比较,只存与某次听写对应的那一段改后的文字(历史记录关闭时什么也不存),存在本机历史里,删除记录、清空历史时一起删除,用户可以在历史详情里移除;不调用 AI、不发给任何服务;日志只记结果种类、条数和字数 | `crates/voltip-core/tests/learn.rs@the_notice_says_why_nothing_was_learned`(历史记录关闭、终端里都不按键)、`crates/voltip-core/tests/learn.rs@a_selection_corrects_the_take_and_the_notice_offers_its_pair`、`crates/voltip-inject/tests/real_display.rs@real_copy_chord_reads_the_selection_of_an_x11_text_widget`(剪贴板放回)、`crates/voltip-core/src/history/tests.rs@a_correction_is_stored_beside_the_entry_searched_and_read_with_the_recent_texts` |
| 内置服务的每日额度被绕过,或用量把用户关联起来(`docs/dictation.md` §27) | 设备号是首次使用时生成的随机 UUID(`usage-id`),与配对密钥无关,不进备份、不同步,只发给内置服务;内置服务仍要应用令牌,按 IP 的限流照旧;额度是没有账号时的公平使用额度,不是安全边界(重装或伪造请求头能拿到新的额度,旧版本按 IP 计数);额度用完只影响内置服务,其他服务商和本机模型照常可用;网关的统计只给每台设备 / 每个 IP 一个数,不含设备号和 IP;用量记录不含录音和文字 | `crates/voltip-cloud/src/lib.rs@only_the_built_in_service_is_told_who_asks`、`crates/voltip-core/src/usage/mod.rs@the_device_id_is_made_once_and_read_without_writing`、`apps/server/tests/cli.rs@the_server_meters_as_the_apps_device_or_as_itself_and_never_writes_the_apps_directory` |
| 中继的统计泄露谁在和谁连接(`docs/pairing.md`「中继统计」) | `GET /stats` 只在中继的回环监听地址上,反向代理只转发 `/ws`;只有按小时的计数,不含 IP、频道、会话号和验证码;版本只按已发布版本的名单分桶,其余记为 `other`,每小时的桶数有上限 | `crates/voltip-relay/src/core.rs@the_statistics_count_what_happened_and_name_no_device`、`crates/voltip-relay/src/stats.rs@regression_versions_are_named_only_from_the_policy_or_up_to_the_hours_slots` |
| 管理台被冒用:调高最低版本把所有客户端挡在外面,或改动额度(`docs/runbook.md`「管理台与同步」) | 管理台(私有仓库 `sunerpy/voltip-admin`)只在 Cloudflare Access 之后;Functions 用团队域的公钥验证每个请求的 `Cf-Access-Jwt-Assertion`(签名、`aud`、`exp`),失败一律 403;同步接口只认 Access 的 service token;最低版本只能选已发布的版本,并发修改按 revision 回 409,每次修改记审计(邮箱、前后内容、时间),可以恢复上一个设置;中继和网关主机上的本地覆盖文件优先于同步来的配置,坏的配置不会替换上一份有效配置 | 私有仓库的 `site/` 测试(Access JWT 用测试密钥对、409、已发布版本校验、同步令牌);`crates/voltip-relay/src/policy.rs@the_override_wins_while_valid_and_a_broken_main_file_keeps_the_last_valid_policy` |
@@ -38,3 +39,4 @@
- 本机语音服务的令牌对同一用户的所有进程可读(这就是给其他程序用的):能读到这个文件的程序就能使用服务,包括它背后的内置服务额度。`--allow-remote` 时令牌以明文 HTTP 传输,应改用 SSH 隧道或 TLS 反向代理。
- 内置服务的每日计数放在网关的 njs 共享内存里,网关容器重启后当天的计数清零,这一天可以多用一些(`docs/dictation.md` §27.9)。
- AI 工具接入的令牌同样对同一用户的所有进程可读,复制时会经过剪贴板(其他程序可能读剪贴板);持有令牌的程序能在授权范围内读写。AI 工具读到的内容会发给它所用的模型服务,这一点由完整历史的确认框说明,Voltip 无法约束。
+- 从选中文字学习读选区时,选中的文字会在剪贴板上停留很短的时间(与语音编辑相同),这期间读剪贴板的程序(剪贴板管理器、远程桌面)能看到它。改后的文字随历史记录同步到配对的手机(端到端加密),手机不显示它。
diff --git a/packages/shared/src/backend.ts b/packages/shared/src/backend.ts
index 8ed2dad8..fe74e64b 100644
--- a/packages/shared/src/backend.ts
+++ b/packages/shared/src/backend.ts
@@ -192,6 +192,11 @@ export interface Backend {
overlayPaste(text: string): Promise;
/** The result card's 打开历史 (`open_history`, §28): the main window comes up on the history page. */
openHistory(): Promise;
+ /** The learn notice's 查看 (`open_suggestions`, docs/dictation.md §35): the main window comes up
+ * on the dictionary's learning suggestions. */
+ openSuggestions(): Promise;
+ /** The learn notice's 打开设置 (`open_privacy`, §35): the main window comes up on 设置 › 隐私. */
+ openPrivacy(): Promise;
/** Open the vendor's API-key page (`site`'s, for a vendor with several, docs/dictation.md
* §3.2), with `page: "quota"` its page of free quota and usage, or with `page: "setup"` the page
* where its service is activated (§3.16), in the browser (`provider_console_open`); the shell
diff --git a/packages/shared/src/fixtures/ipc/commands.json b/packages/shared/src/fixtures/ipc/commands.json
index 2cd609a0..07b944ee 100644
--- a/packages/shared/src/fixtures/ipc/commands.json
+++ b/packages/shared/src/fixtures/ipc/commands.json
@@ -89,6 +89,12 @@
},
"name": "settings_set_copy_last_hotkey"
},
+ {
+ "args": {
+ "hotkey": "Ctrl+Alt+L"
+ },
+ "name": "settings_set_learn_hotkey"
+ },
{
"args": {
"key": "mouse_back"
@@ -251,6 +257,30 @@
},
"name": "dictation_dismiss"
},
+ {
+ "args": {
+ "id": 4
+ },
+ "name": "learn_notice_accept"
+ },
+ {
+ "args": {
+ "id": 4
+ },
+ "name": "learn_notice_undo"
+ },
+ {
+ "args": {
+ "id": 4
+ },
+ "name": "learn_notice_dismiss"
+ },
+ {
+ "args": {
+ "id": 4
+ },
+ "name": "learn_notice_keep"
+ },
{
"args": {
"atMs": 1758700600000,
@@ -385,6 +415,12 @@
},
"name": "history_star"
},
+ {
+ "args": {
+ "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
+ },
+ "name": "history_clear_corrected"
+ },
{
"args": {
"id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
diff --git a/packages/shared/src/fixtures/ipc/events.json b/packages/shared/src/fixtures/ipc/events.json
index 636f9353..ee58fb0d 100644
--- a/packages/shared/src/fixtures/ipc/events.json
+++ b/packages/shared/src/fixtures/ipc/events.json
@@ -780,6 +780,7 @@
"backend": "global-shortcut · Linux · XWayland",
"edit_error": "Ctrl+Alt+E 注册失败:already registered",
"copy_last_error": "Ctrl+Shift+V 注册失败:already registered",
+ "learn_error": "Ctrl+Alt+L 与另一个快捷键相同,未生效",
"capabilities": {
"global": true,
"everywhere": false,
@@ -1597,6 +1598,79 @@
],
"total": 1
},
+ {
+ "type": "history",
+ "recent": [
+ {
+ "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
+ "at_ms": 1758700600000,
+ "raw_text": "把 fetchUser 改成 async 然后加上错误处理",
+ "text": "把 fetchUser 改成 async,然后加上错误处理。",
+ "refined": true,
+ "asr_model": "Qwen/Qwen3-ASR-1.7B",
+ "asr_note": "gpu_failed_ran_on_cpu",
+ "asr_provider": "builtin",
+ "refine_model": "qwen/qwen3.8-27b",
+ "refine_provider": "groq",
+ "duration_ms": 3200,
+ "asr_ms": 640,
+ "refine_ms": 2400,
+ "outcome": {
+ "kind": "inserted",
+ "via": "paste",
+ "check": "unconfirmed"
+ },
+ "starred": true,
+ "mode": "whole_take",
+ "vocabulary": {
+ "corrections": [
+ {
+ "id": "3b241101-e2bb-4255-8caf-4136c566a962",
+ "count": 1
+ }
+ ],
+ "rules": [
+ {
+ "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+ "count": 2
+ }
+ ]
+ },
+ "kind": "dictation",
+ "app": {
+ "id": "code",
+ "name": "Code"
+ },
+ "scene": {
+ "id": "5c0ffee0-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
+ "name": "代码评审"
+ },
+ "preset": {
+ "id": "formal",
+ "name": "书面语"
+ },
+ "corrected": {
+ "text": "我在用 Qwen 4 max 做测试",
+ "at_ms": 1758700660000,
+ "via": "selection"
+ },
+ "timing": {
+ "pressed_at": 1758700593000,
+ "device_open_ms": 38,
+ "first_audio_ms": 212,
+ "first_text_ms": 640,
+ "released_ms": 3412,
+ "tail_ms": 150,
+ "asr_ms": 655,
+ "refine_ms": 2410,
+ "insert_ms": 96,
+ "done_ms": 6731
+ },
+ "glossary_sent": true
+ }
+ ],
+ "total": 1
+ },
{
"type": "history",
"recent": [
@@ -7193,6 +7267,154 @@
"type": "vocabulary_ignored",
"pairs": []
},
+ {
+ "type": "learn_notice",
+ "notice": {
+ "id": 4,
+ "outcome": {
+ "kind": "learned",
+ "pairs": [
+ {
+ "heard": "Quinn for",
+ "polished": "Qwen 4",
+ "history_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
+ }
+ ],
+ "safe": true
+ },
+ "shown": false
+ }
+ },
+ {
+ "type": "learn_notice",
+ "notice": {
+ "id": 4,
+ "outcome": {
+ "kind": "learned",
+ "pairs": [
+ {
+ "heard": "非书",
+ "polished": "飞书",
+ "history_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
+ }
+ ],
+ "safe": true
+ },
+ "shown": true,
+ "accepted": {
+ "added": 1,
+ "refused": 0,
+ "undo": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
+ },
+ "undone": {
+ "kind": "undone"
+ }
+ }
+ },
+ {
+ "type": "learn_notice",
+ "notice": {
+ "id": 5,
+ "outcome": {
+ "kind": "learned",
+ "pairs": [
+ {
+ "heard": "非",
+ "polished": "飞",
+ "history_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
+ }
+ ],
+ "safe": false
+ },
+ "shown": true
+ }
+ },
+ {
+ "type": "learn_notice",
+ "notice": {
+ "id": 5,
+ "outcome": {
+ "kind": "no_pairs"
+ },
+ "shown": true
+ }
+ },
+ {
+ "type": "learn_notice",
+ "notice": {
+ "id": 5,
+ "outcome": {
+ "kind": "unchanged"
+ },
+ "shown": true
+ }
+ },
+ {
+ "type": "learn_notice",
+ "notice": {
+ "id": 5,
+ "outcome": {
+ "kind": "no_match"
+ },
+ "shown": true
+ }
+ },
+ {
+ "type": "learn_notice",
+ "notice": {
+ "id": 5,
+ "outcome": {
+ "kind": "no_selection"
+ },
+ "shown": true
+ }
+ },
+ {
+ "type": "learn_notice",
+ "notice": {
+ "id": 5,
+ "outcome": {
+ "kind": "too_long",
+ "max": 8000
+ },
+ "shown": true
+ }
+ },
+ {
+ "type": "learn_notice",
+ "notice": {
+ "id": 5,
+ "outcome": {
+ "kind": "terminal"
+ },
+ "shown": true
+ }
+ },
+ {
+ "type": "learn_notice",
+ "notice": {
+ "id": 5,
+ "outcome": {
+ "kind": "history_off"
+ },
+ "shown": true
+ }
+ },
+ {
+ "type": "learn_notice",
+ "notice": {
+ "id": 5,
+ "outcome": {
+ "kind": "failed",
+ "message": "clipboard: 无法读取剪贴板"
+ },
+ "shown": true
+ }
+ },
+ {
+ "type": "learn_notice",
+ "notice": null
+ },
{
"type": "settings",
"schema": 1,
diff --git a/packages/shared/src/fixtures/ipc/state.json b/packages/shared/src/fixtures/ipc/state.json
index 476e0efc..dd40cf0f 100644
--- a/packages/shared/src/fixtures/ipc/state.json
+++ b/packages/shared/src/fixtures/ipc/state.json
@@ -202,6 +202,7 @@
"backend": "global-shortcut · Windows · RegisterHotKey",
"edit_registered": "Ctrl+Alt+E",
"copy_last_registered": "Ctrl+Shift+V",
+ "learn_registered": "Ctrl+Alt+L",
"capabilities": {
"global": true,
"everywhere": true,
@@ -1669,6 +1670,21 @@
"at_ms": 1758700600000
}
],
+ "learn_notice": {
+ "id": 3,
+ "outcome": {
+ "kind": "learned",
+ "pairs": [
+ {
+ "heard": "Quinn for",
+ "polished": "Qwen 4",
+ "history_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
+ }
+ ],
+ "safe": true
+ },
+ "shown": true
+ },
"scenes": [
{
"id": "5c0ffee0-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
diff --git a/packages/shared/src/fixtures/ipc/vocabulary-suggestions.json b/packages/shared/src/fixtures/ipc/vocabulary-suggestions.json
index 64ebe004..e4c1dca4 100644
--- a/packages/shared/src/fixtures/ipc/vocabulary-suggestions.json
+++ b/packages/shared/src/fixtures/ipc/vocabulary-suggestions.json
@@ -81,6 +81,7 @@
"status": "history_off"
},
"nothing": {
+ "edited": 0,
"pairs": [],
"refined": 0,
"repeated": 0,
@@ -90,6 +91,7 @@
"total": 0
},
"ready": {
+ "edited": 2,
"pairs": [
{
"count": 12,
@@ -118,10 +120,23 @@
"heard": "提成",
"last_at_ms": 1758614200000,
"polished": "集成"
+ },
+ {
+ "count": 1,
+ "examples": [
+ {
+ "history_id": "1c2d3e4f-5a6b-4c8e-9f7a-0f3f1a1e8d4b",
+ "snippet": "我在用 Quinn for max 做测试"
+ }
+ ],
+ "from_edits": 1,
+ "heard": "Quinn for",
+ "last_at_ms": 1758697000000,
+ "polished": "Qwen 4"
}
],
"refined": 1480,
- "repeated": 9,
+ "repeated": 10,
"scanned": 2000,
"skipped": 3,
"status": "ready",
diff --git a/packages/shared/src/i18n/en.ts b/packages/shared/src/i18n/en.ts
index 9dab50b7..e8886a0e 100644
--- a/packages/shared/src/i18n/en.ts
+++ b/packages/shared/src/i18n/en.ts
@@ -1281,14 +1281,21 @@ export const en: Messages = {
suggestionsCount: "Suggestions ({n})",
},
suggestions: {
- explainTitle: "Learn from what AI polish changed",
+ explainTitle: "Learn from AI polish and your corrections",
explain:
- "Compares the recognised text of recent history entries with the polished text and lists the words recognised as A and polished to B, most frequent first. Once a pair is in the dictionary, it is corrected right after recognition. The comparison is character by character; no AI is used.",
+ "Compares the recognised text of recent history entries with the polished text, and with the text you corrected in another app and noted with Learn from selection, and lists the words recognised as A and changed to B, most frequent first. Once a pair is in the dictionary, it is corrected right after recognition. The comparison is character by character; no AI is used.",
+ /** The explanation card's hint while 从选中文字学习 has no shortcut (§35). */
+ hint: "After you correct a dictation in another app, select the corrected text and press the Learn from selection shortcut; your corrections show here too.",
+ hintSet: "Set the shortcut",
+ /** Where a pair came from (§35). */
+ source: { polish: "Polish", edit: "Your correction" },
undoNote:
"Adding or ignoring can be undone right away. Once you leave the dictionary page, adding can no longer be undone; ignored pairs can be brought back from Ignored.",
+ /** What the default 显示范围 shows (§35). */
+ filterNote: "Suggested lists the pairs seen twice or more, and the ones you corrected.",
list: "Suggestions",
table: "Suggestions",
- column: { pair: "Recognised → polished", count: "Count", last: "Last seen" },
+ column: { pair: "Recognised → right spelling", count: "Count", last: "Last seen" },
accept: "Add to dictionary",
ignore: "Ignore",
accepted: "Added to the dictionary",
@@ -1300,7 +1307,11 @@ export const en: Messages = {
undo: "Undo: {heard} → {polished}",
details: "Details: {heard} → {polished}",
},
- filter: { label: "Show", repeated: "Seen twice or more", all: "All" },
+ filter: {
+ label: "Show",
+ repeated: "Suggested",
+ all: "All",
+ },
select: { all: "Select all", row: "Select: {heard} → {polished}" },
selection: {
count: "{n} selected",
@@ -1376,15 +1387,21 @@ export const en: Messages = {
historyOff:
"Suggestions come from the history. Once history is on, new dictations are compared.",
openPrivacy: "Open privacy settings",
- noPolishedTitle: "No dictation in recent history was polished",
+ noPolishedTitle: "No dictation in recent history was polished or corrected",
noPolished:
- "Suggestions compare the recognised text with the polished text. Turn on AI polish and dictate a few times, and the words it changed appear here.",
+ "Suggestions compare the recognised text with the polished text, and take in the corrections you note with Learn from selection. Turn on AI polish and dictate a few times, or press that shortcut after correcting a dictation in another app, and the words appear here.",
noneTitle: "No suggestions",
none: {
one: "The last polished entry has nothing new for the dictionary.",
other: "The last {n} polished entries have nothing new for the dictionary.",
},
- noneRepeatedTitle: "No pair was seen twice or more",
+ noneEdited: {
+ one: "The last entry with your corrections has nothing new for the dictionary.",
+ other: "The last {n} entries with your corrections have nothing new for the dictionary.",
+ },
+ noneBoth:
+ "The last {refined} polished entries and {edited} entries with your corrections have nothing new for the dictionary.",
+ noneRepeatedTitle: "Nothing suggested",
noneRepeated: {
one: "1 more pair was seen once.",
other: "{n} more pairs were seen once.",
@@ -1396,6 +1413,7 @@ export const en: Messages = {
other: "Last {n} entries · {refined} polished",
},
skipped: "{n} too long to compare",
+ edited: "{n} with your corrections",
more: "Showing the first {shown} of {total}",
shown: { one: "Showing 1 pair", other: "Showing {n} pairs" },
hiddenOnce: {
@@ -1405,7 +1423,7 @@ export const en: Messages = {
ignoredList: {
title: "Ignored ({n})",
table: "Ignored",
- column: { pair: "Recognised → polished", at: "Ignored" },
+ column: { pair: "Recognised → right spelling", at: "Ignored" },
unignore: "Stop ignoring",
row: "Stop ignoring: {heard} → {polished}",
showAll: "Show all ({n})",
@@ -2674,6 +2692,55 @@ export const en: Messages = {
copyLastClearLabel: "Clear · Copy last result",
},
},
+ /** 从选中文字学习 (docs/dictation.md §35): the shortcut, the pill's notice after it, and the
+ * correction kept with a history entry. */
+ learn: {
+ settings: {
+ label: "Learn from selection",
+ help: "After you correct a dictation in another app, select the corrected text and press this shortcut. Voltip notes the change for you to confirm in the dictionary's suggestions.",
+ none: "Not set",
+ record: "Record",
+ recordLabel: "Record · Learn from selection",
+ rerecordLabel: "Record again · Learn from selection",
+ cancelLabel: "Cancel recording · Learn from selection",
+ clear: "Clear",
+ clearLabel: "Clear · Learn from selection",
+ },
+ notice: {
+ pair: "{heard} → {polished}",
+ learned: "Noted 1 change: {pair}",
+ learnedMany: "Noted {n} changes: {pair} and more",
+ added: "Added to the dictionary: {pair}",
+ addedMany: "Added {n} changes to the dictionary",
+ addedSome: {
+ one: "{added} added, {refused} couldn't be added",
+ other: "{added} added, {refused} couldn't be added",
+ },
+ refusedAll: "Couldn't add to the dictionary; the dictionary page says why",
+ undone: "Undone",
+ undoFailed: "Couldn't undo",
+ noPairs: "No change to add to the dictionary",
+ unchanged: "The selection matches what was dictated",
+ noMatch: "Not found in the last {n} dictations",
+ noSelection: "Nothing is selected",
+ tooLong: "The selection is too long ({max} characters at most)",
+ terminal: "Text in a terminal can't be learned from",
+ historyOff: "Turn on the history first",
+ failed: "Couldn't read the selection: {message}",
+ add: "Add to dictionary",
+ view: "View",
+ undo: "Undo",
+ openSettings: "Open settings",
+ },
+ /** The history detail's line about the user's correction. */
+ history: {
+ corrected: "Later corrected to",
+ via: "Learn from selection · {time}",
+ viaFollow: "Edited in the text field · {time}",
+ remove: "Remove",
+ removeLabel: "Remove the later correction",
+ },
+ },
/** docs/dictation.md §3.14: 服务出错时也改用候补, the models of this computer in a recognition
* chain, and whose model wrote a history entry's text. */
fallbackOutage: {
diff --git a/packages/shared/src/i18n/zh-CN.ts b/packages/shared/src/i18n/zh-CN.ts
index 06256186..546d940d 100644
--- a/packages/shared/src/i18n/zh-CN.ts
+++ b/packages/shared/src/i18n/zh-CN.ts
@@ -1306,14 +1306,21 @@ export const zhCN = {
/** 学习建议 (docs/dictation.md §16.10): what AI polish changed in the history's recognised
* text, offered for the dictionary. */
suggestions: {
- explainTitle: "从 AI 润色的改动中学习",
+ explainTitle: "从 AI 润色和你的修改中学习",
explain:
- "比较最近记录的识别原文和 AI 润色后的文字,列出「识别成 A、润色改成 B」的写法,按出现次数排列。加入词典后,识别完成时就会直接纠正。只逐字比较,不调用 AI。",
+ "比较最近记录的识别原文和 AI 润色后的文字,以及你在其他应用里改正、用「从选中文字学习」记下的文字,列出「识别成 A、改成 B」的写法,按出现次数排列。加入词典后,识别完成时就会直接纠正。只逐字比较,不调用 AI。",
+ /** The explanation card's hint while 从选中文字学习 has no shortcut (§35). */
+ hint: "在其他应用里改正听写结果后,选中改好的文字,按「从选中文字学习」的快捷键,这里也会列出你的修改。",
+ hintSet: "设置快捷键",
+ /** Where a pair came from (§35). */
+ source: { polish: "润色", edit: "你的修改" },
undoNote:
"加入或忽略后可以立即撤销。离开词典页后,加入词典不能再撤销,忽略的写法可以在「已忽略」中取消忽略。",
+ /** What the default 显示范围 shows (§35). */
+ filterNote: "「推荐」列出出现 2 次及以上的写法,以及你改正过的写法。",
list: "学习建议",
table: "学习建议",
- column: { pair: "识别结果 → 润色结果", count: "次数", last: "最近一次" },
+ column: { pair: "识别结果 → 正确写法", count: "次数", last: "最近一次" },
accept: "加入词典",
ignore: "忽略",
accepted: "已加入词典",
@@ -1326,7 +1333,11 @@ export const zhCN = {
details: "详情:{heard} → {polished}",
},
/** Which suggestions the list shows: by default those seen twice or more. */
- filter: { label: "显示范围", repeated: "出现 2 次及以上", all: "全部" },
+ filter: {
+ label: "显示范围",
+ repeated: "推荐",
+ all: "全部",
+ },
/** The rows' check boxes. */
select: { all: "全选", row: "选择:{heard} → {polished}" },
/** The bar over the list while rows are checked. */
@@ -1397,15 +1408,23 @@ export const zhCN = {
historyOffTitle: "需要开启历史记录",
historyOff: "学习建议来自历史记录。开启历史记录后,新的听写会参与比较。",
openPrivacy: "打开隐私设置",
- noPolishedTitle: "最近的记录里没有经过 AI 润色的听写",
+ noPolishedTitle: "最近的记录里没有经过 AI 润色或你改正过的听写",
noPolished:
- "学习建议比较识别原文和 AI 润色后的文字。开启 AI 润色并听写几次后,这里会列出润色改动过的写法。",
+ "学习建议比较识别原文和 AI 润色后的文字,也收录你用「从选中文字学习」记下的修改。开启 AI 润色并听写几次,或在其他应用里改正后按这个快捷键,这里就会列出写法。",
noneTitle: "暂无学习建议",
none: {
one: "最近 {n} 条经过 AI 润色的记录里,没有新的写法可以加入词典。",
other: "最近 {n} 条经过 AI 润色的记录里,没有新的写法可以加入词典。",
},
- noneRepeatedTitle: "没有出现 2 次及以上的建议",
+ /** No takes were polished; the user corrected some (docs/dictation.md §35). */
+ noneEdited: {
+ one: "最近 {n} 条有你修改的记录里,没有新的写法可以加入词典。",
+ other: "最近 {n} 条有你修改的记录里,没有新的写法可以加入词典。",
+ },
+ /** Takes were polished and some corrected. */
+ noneBoth:
+ "最近 {refined} 条经过 AI 润色的记录和 {edited} 条有你修改的记录里,没有新的写法可以加入词典。",
+ noneRepeatedTitle: "没有推荐的建议",
noneRepeated: { one: "另有 {n} 组只出现 1 次。", other: "另有 {n} 组只出现 1 次。" },
showAll: "显示全部",
},
@@ -1414,6 +1433,7 @@ export const zhCN = {
other: "最近 {n} 条记录 · {refined} 条经过 AI 润色",
},
skipped: "{n} 条过长,未比较",
+ edited: "{n} 条有你的修改",
more: "显示前 {shown} 组 · 共 {total} 组",
shown: { one: "显示 {n} 组", other: "显示 {n} 组" },
hiddenOnce: { one: "隐藏 {n} 组只出现 1 次的建议", other: "隐藏 {n} 组只出现 1 次的建议" },
@@ -1421,7 +1441,7 @@ export const zhCN = {
ignoredList: {
title: "已忽略({n})",
table: "已忽略",
- column: { pair: "识别结果 → 润色结果", at: "忽略时间" },
+ column: { pair: "识别结果 → 正确写法", at: "忽略时间" },
unignore: "取消忽略",
row: "取消忽略:{heard} → {polished}",
showAll: "显示全部({n})",
@@ -2669,6 +2689,56 @@ export const zhCN = {
copyLastClearLabel: "清除 · 复制上一条结果",
},
},
+ /** 从选中文字学习 (docs/dictation.md §35): the shortcut, the pill's notice after it, and the
+ * correction kept with a history entry. */
+ learn: {
+ settings: {
+ label: "从选中文字学习",
+ help: "在其他应用里改正听写结果后,选中改好的文字按这个快捷键,Voltip 会记下改动,到词典的学习建议里确认",
+ none: "未设置",
+ record: "录制",
+ recordLabel: "录制 · 从选中文字学习",
+ rerecordLabel: "重新录制 · 从选中文字学习",
+ cancelLabel: "取消录制 · 从选中文字学习",
+ clear: "清除",
+ clearLabel: "清除 · 从选中文字学习",
+ },
+ notice: {
+ pair: "{heard} → {polished}",
+ learned: "已记下 1 处改动:{pair}",
+ learnedMany: "已记下 {n} 处改动:{pair} 等",
+ added: "已加入词典:{pair}",
+ addedMany: "已将 {n} 处改动加入词典",
+ addedSome: {
+ one: "{added} 处已加入,{refused} 处无法加入",
+ other: "{added} 处已加入,{refused} 处无法加入",
+ },
+ refusedAll: "无法加入词典,原因见词典页",
+ undone: "已撤销",
+ undoFailed: "无法撤销",
+ noPairs: "没有可以加入词典的改动",
+ unchanged: "选中的文字和听写结果相同",
+ noMatch: "最近 {n} 次听写里没有找到这段文字",
+ noSelection: "没有选中文字",
+ tooLong: "选中的文字太长,最多 {max} 字",
+ terminal: "终端里的文字不能用来学习",
+ historyOff: "需要先开启历史记录",
+ failed: "无法读取选中的文字:{message}",
+ add: "加入词典",
+ view: "查看",
+ undo: "撤销",
+ openSettings: "打开设置",
+ },
+ /** The history detail's line about the user's correction. */
+ history: {
+ corrected: "之后改成",
+ via: "从选中文字学习 · {time}",
+ /** A correction a later version read in the text field (`via: follow`). */
+ viaFollow: "在输入框中修改 · {time}",
+ remove: "移除",
+ removeLabel: "移除之后改成的文字",
+ },
+ },
/** docs/dictation.md §3.14: 服务出错时也改用候补, the models of this computer in a recognition
* chain, and whose model wrote a history entry's text. */
fallbackOutage: {
diff --git a/packages/shared/src/ipc-contract.test.ts b/packages/shared/src/ipc-contract.test.ts
index 96bac2c1..d3b5f2aa 100644
--- a/packages/shared/src/ipc-contract.test.ts
+++ b/packages/shared/src/ipc-contract.test.ts
@@ -103,6 +103,7 @@ const EVENT_TYPE_SET: Record = {
dictionary: null,
rules: null,
vocabulary_ignored: null,
+ learn_notice: null,
scenes: null,
presets: null,
preset_try: null,
@@ -145,6 +146,7 @@ const MUTATION_COMMAND_SET: Record = {
settings_set_hotkey: null,
settings_set_edit_hotkey: null,
settings_set_copy_last_hotkey: null,
+ settings_set_learn_hotkey: null,
settings_set_solo_key: null,
settings_set_microphone: null,
settings_set_recording: null,
@@ -155,6 +157,10 @@ const MUTATION_COMMAND_SET: Record = {
dictation_stop: null,
dictation_cancel: null,
dictation_dismiss: null,
+ learn_notice_accept: null,
+ learn_notice_undo: null,
+ learn_notice_dismiss: null,
+ learn_notice_keep: null,
settings_set_engines: null,
provider_key_set: null,
engines_quota_reset: null,
@@ -163,6 +169,7 @@ const MUTATION_COMMAND_SET: Record = {
history_delete: null,
history_clear: null,
history_star: null,
+ history_clear_corrected: null,
history_process: null,
history_process_cancel: null,
settings_set_audio_cache: null,
@@ -269,6 +276,7 @@ const argSchemas = {
settings_set_hotkey: z.object({ hotkey: z.string() }),
settings_set_edit_hotkey: z.object({ hotkey: z.string().nullable() }).strict(),
settings_set_copy_last_hotkey: z.object({ hotkey: z.string().nullable() }).strict(),
+ settings_set_learn_hotkey: z.object({ hotkey: z.string().nullable() }).strict(),
settings_set_solo_key: z.object({ key: soloKeySchema.nullable() }).strict(),
settings_set_microphone: z.object({ device: z.string().nullable() }).strict(),
settings_set_recording: z.object({ recording: recordingSettingsSchema.strict() }).strict(),
@@ -295,6 +303,7 @@ const argSchemas = {
.strict(),
history_delete: z.object({ id: z.string() }),
history_star: z.object({ id: z.string(), starred: z.boolean() }),
+ history_clear_corrected: z.object({ id: z.string() }).strict(),
history_process: z
.object({
requestId: z.number().int().nonnegative(),
@@ -414,6 +423,10 @@ const argSchemas = {
mcp_undo: z.object({ id: z.string() }).strict(),
usage_notice_dismiss: z.object({ notice: usageNoticeSchema }).strict(),
dictation_dismiss: z.object({ session: z.number().int().nonnegative() }).strict(),
+ learn_notice_accept: z.object({ id: z.number().int().nonnegative() }).strict(),
+ learn_notice_undo: z.object({ id: z.number().int().nonnegative() }).strict(),
+ learn_notice_dismiss: z.object({ id: z.number().int().nonnegative() }).strict(),
+ learn_notice_keep: z.object({ id: z.number().int().nonnegative() }).strict(),
} satisfies {
[C in MutationCommand as CommandArgs[C] extends undefined ? never : C]: z.ZodType;
};
@@ -452,6 +465,14 @@ function replay(backend: TauriBackend, name: MutationCommand, args: unknown): Pr
return backend.invoke(name);
case "dictation_dismiss":
return backend.invoke(name, argSchemas.dictation_dismiss.parse(args));
+ case "learn_notice_accept":
+ return backend.invoke(name, argSchemas.learn_notice_accept.parse(args));
+ case "learn_notice_undo":
+ return backend.invoke(name, argSchemas.learn_notice_undo.parse(args));
+ case "learn_notice_dismiss":
+ return backend.invoke(name, argSchemas.learn_notice_dismiss.parse(args));
+ case "learn_notice_keep":
+ return backend.invoke(name, argSchemas.learn_notice_keep.parse(args));
case "pairing_join_code":
return backend.invoke(name, argSchemas.pairing_join_code.parse(args));
case "pairing_join_ticket":
@@ -487,6 +508,8 @@ function replay(backend: TauriBackend, name: MutationCommand, args: unknown): Pr
return backend.invoke(name, argSchemas.settings_set_edit_hotkey.parse(args));
case "settings_set_copy_last_hotkey":
return backend.invoke(name, argSchemas.settings_set_copy_last_hotkey.parse(args));
+ case "settings_set_learn_hotkey":
+ return backend.invoke(name, argSchemas.settings_set_learn_hotkey.parse(args));
case "settings_set_solo_key":
return backend.invoke(name, argSchemas.settings_set_solo_key.parse(args));
case "settings_set_microphone":
@@ -509,6 +532,8 @@ function replay(backend: TauriBackend, name: MutationCommand, args: unknown): Pr
return backend.invoke(name, argSchemas.history_delete.parse(args));
case "history_star":
return backend.invoke(name, argSchemas.history_star.parse(args));
+ case "history_clear_corrected":
+ return backend.invoke(name, argSchemas.history_clear_corrected.parse(args));
case "settings_set_locale":
return backend.invoke(name, argSchemas.settings_set_locale.parse(args));
case "settings_set_auto_update":
@@ -1674,12 +1699,19 @@ describe("history queries (docs/dictation.md section 4.4)", () => {
.parse(loadFixture("vocabulary-suggestions.json"));
const ready = suggestionsAnswerSchema.parse(fixture.ready);
if (ready.status !== "ready") throw new Error("ready");
- expect([ready.scanned, ready.refined, ready.skipped, ready.total, ready.repeated]).toEqual([
- 2000, 1480, 3, 41, 9,
- ]);
- expect(ready.pairs.map((p) => [p.heard, p.polished, p.count])).toEqual([
- ["维他命", "Voltip", 12],
- ["提成", "集成", 3],
+ expect([
+ ready.scanned,
+ ready.refined,
+ ready.skipped,
+ ready.total,
+ ready.repeated,
+ ready.edited,
+ ]).toEqual([2000, 1480, 3, 41, 10, 2]);
+ expect(ready.pairs.map((p) => [p.heard, p.polished, p.count, p.from_edits])).toEqual([
+ ["维他命", "Voltip", 12, 0],
+ ["提成", "集成", 3, 0],
+ // docs/dictation.md §35: corrected by the user once.
+ ["Quinn for", "Qwen 4", 1, 1],
]);
expect(ready.pairs[0]?.examples).toHaveLength(2);
expect(suggestionsAnswerSchema.parse(fixture.history_off)).toEqual({ status: "history_off" });
diff --git a/packages/shared/src/mock-backend.test.ts b/packages/shared/src/mock-backend.test.ts
index 5263f0aa..a6233775 100644
--- a/packages/shared/src/mock-backend.test.ts
+++ b/packages/shared/src/mock-backend.test.ts
@@ -99,6 +99,7 @@ import {
type DictionaryDraft,
type EngineSettings,
type HistoryEntry,
+ type LearnNotice,
type ProviderId,
type ServiceKind,
MAX_BACKTEST_LIMIT,
@@ -4023,6 +4024,103 @@ describe("MockBackend voice edit (section 19)", () => {
});
});
+describe("MockBackend 从选中文字学习 (docs/dictation.md section 35)", () => {
+ const T = 1_758_700_000_000;
+ const take: HistoryEntry = {
+ id: "00000000-0000-4000-8000-000000000035",
+ at_ms: T,
+ raw_text: "我在用 Quinn for max 做测试",
+ text: "我在用 Quinn for max 做测试",
+ refined: false,
+ asr_model: "m",
+ duration_ms: 1000,
+ asr_ms: 100,
+ outcome: { kind: "inserted", via: "paste" },
+ starred: false,
+ mode: "whole_take",
+ kind: "dictation",
+ corrected: { text: "我在用 Qwen 4 max 做测试", at_ms: T + 1, via: "selection" },
+ };
+ const notice = (safe: boolean): LearnNotice => ({
+ id: 7,
+ outcome: {
+ kind: "learned",
+ pairs: [{ heard: "Quinn for", polished: "Qwen 4", history_id: take.id }],
+ safe,
+ },
+ shown: true,
+ });
+
+ it("the learn hotkey is one of four distinct chords, none by default", async () => {
+ const backend = new MockBackend({ now: () => T, history: [] });
+ const events = collect(backend);
+ const errors = () => events.flatMap((e) => (e.type === "error" ? [e.message] : []));
+ expect(backend.peek().settings.learn_hotkey).toBeUndefined();
+ await backend.invoke("settings_set_copy_last_hotkey", { hotkey: "Ctrl+Shift+V" });
+ await backend.invoke("settings_set_learn_hotkey", { hotkey: "Ctrl+Alt+L" });
+ expect(backend.peek().settings.learn_hotkey).toBe("Ctrl+Alt+L");
+ expect(backend.peek().hotkey.learn_registered).toBe("Ctrl+Alt+L");
+ await backend.invoke("settings_set_learn_hotkey", { hotkey: "alt+ctrl+space" });
+ await backend.invoke("settings_set_learn_hotkey", { hotkey: "ctrl+alt+e" });
+ await backend.invoke("settings_set_learn_hotkey", { hotkey: "shift+ctrl+v" });
+ await backend.invoke("settings_set_hotkey", { hotkey: "ctrl+alt+l" });
+ await backend.invoke("settings_set_edit_hotkey", { hotkey: "ctrl+alt+l" });
+ await backend.invoke("settings_set_copy_last_hotkey", { hotkey: "ctrl+alt+l" });
+ expect(errors()).toEqual([
+ "learn_hotkey: alt+ctrl+space 已用作听写快捷键",
+ "learn_hotkey: ctrl+alt+e 已用作「编辑选中文本」的快捷键",
+ "learn_hotkey: shift+ctrl+v 已用作「复制上一条结果」的快捷键",
+ "hotkey: ctrl+alt+l 已用作「从选中文字学习」的快捷键",
+ "edit_hotkey: ctrl+alt+l 已用作「从选中文字学习」的快捷键",
+ "copy_last_hotkey: ctrl+alt+l 已用作「从选中文字学习」的快捷键",
+ ]);
+ await backend.invoke("settings_set_learn_hotkey", { hotkey: null });
+ expect(backend.peek().settings).not.toHaveProperty("learn_hotkey");
+ expect(backend.peek().hotkey.learn_registered).toBeUndefined();
+ backend.destroy();
+ });
+
+ it("the notice's 加入词典, 撤销 and × go through the batch of the learning suggestions", async () => {
+ const backend = new MockBackend({ now: () => T, history: [take] });
+ backend.showLearnNotice(notice(true));
+ await backend.invoke("learn_notice_accept", { id: 6 });
+ expect(backend.peek().learn_notice?.accepted).toBeUndefined();
+ await backend.invoke("learn_notice_accept", { id: 7 });
+ await vi.waitFor(() => {
+ expect(backend.peek().learn_notice?.accepted).toMatchObject({ added: 1, refused: 0 });
+ });
+ expect(backend.peek().dictionary).toMatchObject([{ term: "Qwen 4", heard_as: ["Quinn for"] }]);
+ await backend.invoke("learn_notice_undo", { id: 7 });
+ await vi.waitFor(() => {
+ expect(backend.peek().learn_notice?.undone).toEqual({ kind: "undone" });
+ });
+ expect(backend.peek().dictionary).toEqual([]);
+ await backend.invoke("learn_notice_dismiss", { id: 7 });
+ expect(backend.peek().learn_notice).toBeNull();
+ // A short spelling is not added from the pill.
+ backend.showLearnNotice(notice(false));
+ await backend.invoke("learn_notice_accept", { id: 7 });
+ expect(backend.peek().learn_notice?.accepted).toBeUndefined();
+ await backend.openSuggestions();
+ expect(backend.suggestionsOpens).toBe(1);
+ backend.destroy();
+ });
+
+ it("移除 forgets the correction and its suggestion, the inserted text stays", async () => {
+ const backend = new MockBackend({ now: () => T, history: [take] });
+ const pairs = async () => {
+ const answer = await backend.vocabularySuggestions();
+ return answer.status === "ready" ? answer.pairs.map((p) => [p.heard, p.from_edits]) : [];
+ };
+ expect(await pairs()).toEqual([["Quinn for", 1]]);
+ await backend.invoke("history_clear_corrected", { id: take.id });
+ expect(backend.peek().history_recent[0]?.corrected).toBeUndefined();
+ expect(backend.peek().history_recent[0]?.text).toBe(take.text);
+ expect(await pairs()).toEqual([]);
+ backend.destroy();
+ });
+});
+
describe("MockBackend LAN pairing, always-on pairing and the phone's commands", () => {
beforeEach(() => {
vi.useFakeTimers();
@@ -4354,7 +4452,7 @@ describe("MockBackend learning suggestions (docs/dictation.md section 16.10)", (
it("suggests the clean-up's pairs; 加入词典 and 撤销 change the dictionary and the answer", async () => {
const backend = new MockBackend({ now: () => T, history: rows });
- expect(await heard(backend)).toEqual(["非", "维他命"]);
+ expect(await heard(backend)).toEqual(["非书", "维他命"]);
const one = await backend.vocabularySuggestions(1);
expect(one).toMatchObject({ status: "ready", total: 2, refined: 3 });
for (const limit of [0, 201, 1.5]) {
@@ -4373,7 +4471,7 @@ describe("MockBackend learning suggestions (docs/dictation.md section 16.10)", (
source: { kind: "history", history_id: pair.historyId },
},
]);
- expect(await heard(backend)).toEqual(["非"]);
+ expect(await heard(backend)).toEqual(["非书"]);
expect(await backend.vocabularySuggestionAccept(pair)).toMatchObject({
kind: "refused",
refusal: { kind: "entry", clash: "heard_taken", term: "Voltip" },
@@ -4429,7 +4527,7 @@ describe("MockBackend learning suggestions (docs/dictation.md section 16.10)", (
expect(backend.peek().vocabulary_ignored).toHaveLength(1);
await backend.invoke("vocabulary_suggestion_unignore", { heard: "非", polished: "飞" });
expect(backend.peek().vocabulary_ignored).toEqual([]);
- expect(await heard(backend)).toEqual(["非", "维他命"]);
+ expect(await heard(backend)).toEqual(["非书", "维他命"]);
await expect(
backend.invoke("vocabulary_suggestion_ignore", { heard: "同", polished: "同" }),
).rejects.toThrow(/前后相同/);
@@ -4518,7 +4616,7 @@ describe("MockBackend learning suggestions (docs/dictation.md section 16.10)", (
backend.destroy();
});
- it("the sample takes for screenshots give suggestions seen twice or more and some seen once", async () => {
+ it("the sample takes for screenshots give suggestions seen twice or more, some seen once, and the user's corrections", async () => {
const takes = [...sampleHistory(T), ...sampleSuggestionTakes(T)];
const times = takes.map((t) => t.at_ms);
// Newest first, as the history store keeps them.
@@ -4527,13 +4625,21 @@ describe("MockBackend learning suggestions (docs/dictation.md section 16.10)", (
const backend = new MockBackend({ now: () => T, history: takes });
const answer = await backend.vocabularySuggestions();
if (answer.status !== "ready") throw new Error(answer.status);
- expect(answer.pairs.map((p) => [p.heard, p.polished, p.count]).slice(0, 4)).toEqual([
- ["维他命", "Voltip", 4],
- ["库伯内提斯", "Kubernetes", 3],
- ["瑞迪斯", "Redis", 2],
- ["泰普斯克瑞普特", "TypeScript", 2],
+ expect(
+ answer.pairs.map((p) => [p.heard, p.polished, p.count, p.from_edits]).slice(0, 4),
+ ).toEqual([
+ ["维他命", "Voltip", 5, 1],
+ ["库伯内提斯", "Kubernetes", 3, 0],
+ ["瑞迪斯", "Redis", 2, 0],
+ ["泰普斯克瑞普特", "TypeScript", 2, 0],
]);
- expect([answer.repeated, answer.total]).toEqual([4, 8]);
+ // docs/dictation.md §35: a correction seen once is suggested too.
+ expect(answer.pairs.find((p) => p.heard === "Quinn for")).toMatchObject({
+ polished: "Qwen 4",
+ count: 1,
+ from_edits: 1,
+ });
+ expect([answer.repeated, answer.total, answer.edited]).toEqual([5, 9, 2]);
backend.destroy();
});
@@ -4556,7 +4662,7 @@ describe("MockBackend learning suggestions (docs/dictation.md section 16.10)", (
expect(await heard(backend)).toEqual([]);
expect(await backend.vocabularySuggestionsUndo(outcome.undo)).toEqual({ kind: "undone" });
expect(backend.peek().vocabulary_ignored).toEqual([earlier]);
- expect(await heard(backend)).toEqual(["非", "维他命"]);
+ expect(await heard(backend)).toEqual(["非书", "维他命"]);
expect(await backend.vocabularySuggestionsUndo(outcome.undo)).toEqual({ kind: "expired" });
await expect(backend.vocabularySuggestionsIgnore([])).rejects.toThrow(
"vocabulary_suggestions_ignore: pairs 1–200",
diff --git a/packages/shared/src/mock-backend.ts b/packages/shared/src/mock-backend.ts
index 7f660436..ae1a7718 100644
--- a/packages/shared/src/mock-backend.ts
+++ b/packages/shared/src/mock-backend.ts
@@ -85,6 +85,7 @@ import {
type EngineStatus,
type HistoryEntry,
type IgnoredPair,
+ type LearnNotice,
type HotkeyEdgeArgs,
type InjectPreflight,
type PasteFailure,
@@ -1184,6 +1185,9 @@ export class MockBackend implements Backend {
readonly overlayPastes: string[] = [];
/** How often the result card's 打开历史 ran (tests). */
historyOpens = 0;
+ /** How often the learn notice's 查看 and 打开设置 ran (tests). */
+ suggestionsOpens = 0;
+ privacyOpens = 0;
private meters = new Set>();
private permissions: PermissionReport | (() => PermissionReport);
private readonly preflight: InjectPreflight;
@@ -2191,12 +2195,47 @@ export class MockBackend implements Backend {
return Promise.resolve(structuredClone(this.pasteOutcome));
}
+ /** Forget the user's correction of entry `id` (§35); its text stays. */
+ private clearCorrection(id: string): void {
+ this.setHistory(
+ this.history.map((e) => {
+ if (e.id !== id || e.corrected === undefined) return e;
+ const { corrected: _gone, ...rest } = e;
+ return rest;
+ }),
+ );
+ }
+
+ /** The learn chord (§35) is `hotkey`. */
+ private learnChordIs(hotkey: string): boolean {
+ const learn = this.state.settings.learn_hotkey;
+ return learn != null && mockSameChord(hotkey, learn);
+ }
+
+ /** Show a learn notice on the pill as the core would after a 从选中文字学习 (§35; the browser
+ * has no selection to copy, so tests and the dev sheet hand it the notice). */
+ showLearnNotice(notice: LearnNotice | null): void {
+ this.emit({ type: "learn_notice", notice });
+ }
+
/** `open_history` (§28): the shell would bring the main window up on the history page. */
openHistory(): Promise {
this.historyOpens += 1;
return Promise.resolve();
}
+ /** `open_suggestions` (§35): the shell would bring the main window up on the learning suggestions. */
+ openSuggestions(): Promise {
+ this.suggestionsOpens += 1;
+ return Promise.resolve();
+ }
+
+ /** `open_privacy` (§35): the shell would bring the main window up on 设置 › 隐私. */
+ openPrivacy(): Promise {
+ this.privacyOpens += 1;
+ return Promise.resolve();
+ }
+
/** `presets_builtin`: the built-in presets' texts (the phone has its own presets since
* 2026-10-01, user decision). */
async presetsBuiltin(): Promise {
@@ -2355,6 +2394,10 @@ export class MockBackend implements Backend {
});
return;
}
+ if (this.learnChordIs(hotkey)) {
+ this.emit({ type: "error", message: `hotkey: ${hotkey} 已用作「从选中文字学习」的快捷键` });
+ return;
+ }
this.emit({ type: "settings", ...this.state.settings, hotkey });
this.emit({ type: "hotkey", ...this.hotkeyStatus(false) });
},
@@ -2438,6 +2481,13 @@ export class MockBackend implements Backend {
});
return;
}
+ if (this.learnChordIs(hotkey)) {
+ this.emit({
+ type: "error",
+ message: `edit_hotkey: ${hotkey} 已用作「从选中文字学习」的快捷键`,
+ });
+ return;
+ }
}
this.emit({
type: "settings",
@@ -2468,6 +2518,13 @@ export class MockBackend implements Backend {
});
return;
}
+ if (this.learnChordIs(hotkey)) {
+ this.emit({
+ type: "error",
+ message: `copy_last_hotkey: ${hotkey} 已用作「从选中文字学习」的快捷键`,
+ });
+ return;
+ }
}
const { copy_last_hotkey: _old, ...rest } = this.state.settings;
this.emit({
@@ -2477,6 +2534,79 @@ export class MockBackend implements Backend {
});
this.emit({ type: "hotkey", ...this.hotkeyStatus(false) });
},
+ settings_set_learn_hotkey: (args) => {
+ // Mirrors `SetLearnHotkey` (docs/dictation.md §35): validated like the dictation chord, never
+ // one of the other three; `null` assigns none.
+ const { hotkey } = required(args);
+ if (hotkey !== null) {
+ const problem = mockChordProblem(hotkey);
+ if (problem !== undefined) {
+ this.emit({ type: "error", message: `hotkey: ${hotkey} ${problem}` });
+ return;
+ }
+ const taken: [string | null | undefined, string][] = [
+ [this.state.settings.hotkey, "听写快捷键"],
+ [this.state.settings.edit_hotkey, "「编辑选中文本」的快捷键"],
+ [this.state.settings.copy_last_hotkey, "「复制上一条结果」的快捷键"],
+ ];
+ const clash = taken.find(([chord]) => chord != null && mockSameChord(hotkey, chord));
+ if (clash !== undefined) {
+ this.emit({ type: "error", message: `learn_hotkey: ${hotkey} 已用作${clash[1]}` });
+ return;
+ }
+ }
+ const { learn_hotkey: _old, ...rest } = this.state.settings;
+ this.emit({
+ type: "settings",
+ ...rest,
+ ...(hotkey === null ? {} : { learn_hotkey: hotkey }),
+ });
+ this.emit({ type: "hotkey", ...this.hotkeyStatus(false) });
+ },
+ learn_notice_accept: (args) => {
+ // Mirrors `LearnNoticeAccept` (§35): the notice's pairs through the batch 加入词典.
+ const { id } = required(args);
+ const notice = this.state.learn_notice;
+ if (notice == null || notice.id !== id || notice.accepted !== undefined) return;
+ if (notice.outcome.kind !== "learned" || !notice.outcome.safe) return;
+ void this.vocabularySuggestionsAccept(notice.outcome.pairs).then((outcome) => {
+ const added = outcome.items.filter((i) => i.kind === "accepted").length;
+ this.emit({
+ type: "learn_notice",
+ notice: {
+ ...notice,
+ accepted: {
+ added,
+ refused: outcome.items.length - added,
+ ...(outcome.undo === null ? {} : { undo: outcome.undo }),
+ },
+ },
+ });
+ });
+ },
+ learn_notice_undo: (args) => {
+ const { id } = required(args);
+ const notice = this.state.learn_notice;
+ const batch = notice?.accepted?.undo;
+ if (notice == null || notice.id !== id || notice.undone !== undefined || batch === undefined)
+ return;
+ void this.vocabularySuggestionsUndo(batch).then((undone) => {
+ this.emit({ type: "learn_notice", notice: { ...notice, undone } });
+ });
+ },
+ learn_notice_dismiss: (args) => {
+ const { id } = required(args);
+ if (this.state.learn_notice?.id === id) this.emit({ type: "learn_notice", notice: null });
+ },
+ learn_notice_keep: (args) => {
+ // Mirrors `LearnNoticeKeep` (§35): the mock's notices have no timer, so nothing changes.
+ required(args);
+ },
+ history_clear_corrected: (args) => {
+ // Mirrors `HistoryClearCorrected` (§35): the entry's correction goes, its text stays.
+ const { id } = required(args);
+ this.clearCorrection(id);
+ },
hotkey_capture: (args) => {
// Mirrors the desktop shell: recording suspends the registration, closing restores it.
const { active } = required(args);
@@ -5379,11 +5509,12 @@ export class MockBackend implements Backend {
/** What the desktop shell reports after (re)registering both chords: the dictation chord, and the
* edit chord while it is on; nothing while the recorder holds the keyboard. */
private hotkeyStatus(capturing: boolean): HotkeyStatus {
- const { hotkey, edit_hotkey, solo_key, copy_last_hotkey } = this.state.settings;
+ const { hotkey, edit_hotkey, solo_key, copy_last_hotkey, learn_hotkey } = this.state.settings;
return {
...(capturing ? {} : { registered: hotkey }),
...(capturing || edit_hotkey === null ? {} : { edit_registered: edit_hotkey }),
...(capturing || copy_last_hotkey == null ? {} : { copy_last_registered: copy_last_hotkey }),
+ ...(capturing || learn_hotkey == null ? {} : { learn_registered: learn_hotkey }),
...(capturing ? {} : mockSoloStatus(solo_key)),
pressed: false,
capturing,
@@ -6781,7 +6912,9 @@ export function sampleBackup(nowMs: number): MockBackupFile {
* 瑞迪斯 → Redis and 泰普斯克瑞普特 → TypeScript twice) and two seen once. */
export function sampleSuggestionTakes(nowMs: number): HistoryEntry[] {
const newest = startOfLocalDay(nowMs) - 3 * DAY_MS + 18 * 3_600_000;
- const takes: [string, string][] = [
+ // The third text is the take as the user corrected it in the application (docs/dictation.md
+ // §35): the learning suggestions mark those pairs 你的修改.
+ const takes: [string, string, string?][] = [
["用维他命录了一段会议纪要", "用 Voltip 录了一段会议纪要。"],
["库伯内提斯集群要升级", "Kubernetes 集群要升级。"],
["缓存先放到瑞迪斯里", "缓存先放到 Redis 里。"],
@@ -6795,12 +6928,23 @@ export function sampleSuggestionTakes(nowMs: number): HistoryEntry[] {
["泰普斯克瑞普特的类型检查没过", "TypeScript 的类型检查没过。"],
["打开格拉法纳上的曲线", "打开 Grafana 上的曲线。"],
["维他命的悬浮窗挡住了按钮", "Voltip 的悬浮窗挡住了按钮。"],
+ ["维他命的设置页打不开", "维他命的设置页打不开。", "Voltip 的设置页打不开。"],
+ ["我在用 Quinn for max 做测试", "我在用 Quinn for max 做测试。", "我在用 Qwen 4 max 做测试。"],
];
- return takes.map(([raw, text], i) => ({
+ return takes.map(([raw, text, corrected], i) => ({
id: `00000000-0000-4000-8000-${String(900 + i).padStart(12, "0")}`,
at_ms: newest - i * 3 * 3_600_000,
raw_text: raw,
text,
+ ...(corrected === undefined
+ ? {}
+ : {
+ corrected: {
+ text: corrected,
+ at_ms: newest - i * 3 * 3_600_000 + 600_000,
+ via: "selection" as const,
+ },
+ }),
refined: true,
asr_model: MOCK_ENGINE_BUILTIN.asr_model,
refine_model: MOCK_ENGINE_BUILTIN.refine_model,
diff --git a/packages/shared/src/quick-fix.ts b/packages/shared/src/quick-fix.ts
index 68d2ee12..23a69ffe 100644
--- a/packages/shared/src/quick-fix.ts
+++ b/packages/shared/src/quick-fix.ts
@@ -168,8 +168,37 @@ export function takePolishPairs(
): PolishPair[] {
if (!entry.refined) return [];
const pairs = polishPairs(entry.raw_text, entry.text);
+ if (pairs.length === 0 || entry.vocabulary === undefined) return pairs;
+ const replay = replayOf(entry, dictionary, rules);
+ if (replay === undefined) return [];
+ return pairs.filter(
+ (p) =>
+ replay.run(p.heard) !== p.polished &&
+ !replay.explained.some(
+ (q) =>
+ q.heard === p.heard && q.polished === p.polished && q.start < p.end && p.start < q.end,
+ ),
+ );
+}
+
+/** A take's own corrections and rules replayed over its original text as defined now
+ * (docs/dictation.md §16.9): what they turn a wording into, and the replacements they make;
+ * `undefined` when one of them is gone or was changed after the take. With nothing fired, `run`
+ * changes nothing. */
+export interface Replay {
+ run: (text: string) => string;
+ explained: PolishPair[];
+}
+
+export function replayOf(
+ entry: Pick,
+ dictionary: readonly DictionaryEntry[],
+ rules: readonly ReplacementRule[],
+): Replay | undefined {
const fired = entry.vocabulary;
- if (pairs.length === 0 || fired === undefined) return pairs;
+ if (fired === undefined || fired.corrections.length + fired.rules.length === 0) {
+ return { run: (text) => text, explained: [] };
+ }
/** The fired ones as they stood at the take, in the order they fired; `undefined` when one is
* gone or was changed since. */
const asThen = (
@@ -186,20 +215,74 @@ export function takePolishPairs(
};
const entries = asThen(fired.corrections, dictionary);
const firedRules = asThen(fired.rules, rules);
- if (entries === undefined || firedRules === undefined) return [];
+ if (entries === undefined || firedRules === undefined) return undefined;
const vocabulary = Vocabulary.compile(
entries.map((e) => ({ ...e, enabled: true })),
firedRules.map((r) => ({ ...r, enabled: true, pending: false })),
);
const run = (text: string) => vocabulary.applyRules(vocabulary.correct(text).text).text;
- const explained = polishPairs(entry.raw_text, run(entry.raw_text));
- return pairs.filter(
+ return { run, explained: polishPairs(entry.raw_text, run(entry.raw_text)) };
+}
+
+/** The replacements of what was inserted (`text`) → the user's correction (`corrected`) whose
+ * inserted wording is the recogniser's: where `raw_text` → `text` keeps the tokens, ASCII case
+ * aside (docs/dictation.md §35), with `start`/`end` in `raw_text` and the recognised wording as
+ * `heard`. `voltip_core::vocabulary::learn::recognised_changes`. */
+export function recognisedEditPairs(
+ entry: Pick,
+ corrected: string,
+): PolishPair[] {
+ const pairs = polishPairs(entry.text, corrected);
+ if (pairs.length === 0) return [];
+ // For each code unit of `text`, the code unit of `raw_text` it is, where the two keep it.
+ const toRaw: (number | undefined)[] = [];
+ let r = 0;
+ for (const seg of diffSegments({ rawText: entry.raw_text, text: entry.text }, (a, b) =>
+ sameIgnoringAsciiCase(a, b),
+ )) {
+ const n = seg.text.length;
+ if (seg.kind === "same") {
+ for (let k = 0; k < n; k += 1) toRaw.push(r + k);
+ r += n;
+ } else if (seg.kind === "del") {
+ r += n;
+ } else {
+ for (let k = 0; k < n; k += 1) toRaw.push(undefined);
+ }
+ }
+ const out: PolishPair[] = [];
+ for (const p of pairs) {
+ const start = toRaw[p.start];
+ if (start === undefined) continue;
+ let whole = true;
+ for (let k = p.start; k < p.end; k += 1) {
+ if (toRaw[k] !== start + (k - p.start)) whole = false;
+ }
+ if (!whole) continue;
+ const heard = entry.raw_text.slice(start, start + (p.end - p.start));
+ if (heard === p.polished) continue;
+ out.push({ ...p, start, end: start + (p.end - p.start), heard });
+ }
+ return out;
+}
+
+/** The replacements the user's correction of a take teaches (docs/dictation.md §35): its
+ * `recognisedEditPairs` without those the take's own corrections and rules made (overlapping
+ * one of their replacements, or turning the recognised wording into the user's); none when one of
+ * them is gone or was changed since. `voltip_core::vocabulary::learn::edit_changes`. */
+export function takeEditPairs(
+ entry: Pick,
+ dictionary: readonly DictionaryEntry[],
+ rules: readonly ReplacementRule[],
+): PolishPair[] {
+ const corrected = entry.corrected?.text;
+ if (corrected === undefined) return [];
+ const replay = replayOf(entry, dictionary, rules);
+ if (replay === undefined) return [];
+ return recognisedEditPairs(entry, corrected).filter(
(p) =>
- run(p.heard) !== p.polished &&
- !explained.some(
- (q) =>
- q.heard === p.heard && q.polished === p.polished && q.start < p.end && p.start < q.end,
- ),
+ !replay.explained.some((q) => q.start < p.end && p.start < q.end) &&
+ replay.run(p.heard) !== p.polished,
);
}
diff --git a/packages/shared/src/refine.ts b/packages/shared/src/refine.ts
index 4647fbca..52e03ba2 100644
--- a/packages/shared/src/refine.ts
+++ b/packages/shared/src/refine.ts
@@ -13,8 +13,12 @@ export function diffTokens(text: string): string[] {
return text.match(/[A-Za-z0-9_<>@#$%&*+=/\\.:-]+\s*|\s+|[^\sA-Za-z0-9_<>@#$%&*+=/\\.:-]/g) ?? [];
}
-/** Token-level LCS diff of `rawText` → `text`, merged into runs (identifiers stay whole). */
-export function diffSegments(entry: Pick): DiffSegment[] {
+/** Token-level LCS diff of `rawText` → `text`, merged into runs (identifiers stay whole). `same`
+ * decides which tokens are equal (exact by default); a `same` run holds `rawText`'s tokens. */
+export function diffSegments(
+ entry: Pick,
+ same: (a: string, b: string) => boolean = (a, b) => a === b,
+): DiffSegment[] {
const a = diffTokens(entry.rawText);
const b = diffTokens(entry.text);
const table: number[][] = Array.from({ length: a.length + 1 }, () =>
@@ -26,7 +30,7 @@ export function diffSegments(entry: Pick):
const down = table[i + 1]?.[j] ?? 0;
const right = table[i]?.[j + 1] ?? 0;
const row = table[i];
- if (row) row[j] = a[i] === b[j] ? diag + 1 : Math.max(down, right);
+ if (row) row[j] = same(a[i] ?? "", b[j] ?? "") ? diag + 1 : Math.max(down, right);
}
}
const out: DiffSegment[] = [];
@@ -40,7 +44,7 @@ export function diffSegments(entry: Pick):
while (i < a.length && j < b.length) {
const ta = a[i] ?? "";
const tb = b[j] ?? "";
- if (ta === tb) {
+ if (same(ta, tb)) {
push("same", ta);
i += 1;
j += 1;
diff --git a/packages/shared/src/schema.ts b/packages/shared/src/schema.ts
index 5af3445f..fc7f19df 100644
--- a/packages/shared/src/schema.ts
+++ b/packages/shared/src/schema.ts
@@ -816,6 +816,8 @@ export const settingsSchema = z.object({
/** 复制上一条结果 (docs/dictation.md §28, user decision D12): a chord that puts the newest result
* on the clipboard; absent = none (Rust omits it). */
copy_last_hotkey: z.string().nullable().optional(),
+ /** 从选中文字学习 (docs/dictation.md §35): its chord, or none (absent, the default). */
+ learn_hotkey: z.string().nullable().optional(),
/** Keep a pairing open on this desktop until turned off (docs/pairing.md 「常开配对」); off by
* default and in an older `settings.json`. */
pairing_always_on: z.boolean().default(false),
@@ -1721,14 +1723,17 @@ export const pairExampleSchema = z.object({
});
export type PairExample = z.infer;
-/** One suggestion (`Suggestion`): what the recogniser wrote, what the polished text has instead,
- * how often, the newest take, and up to three snippets, newest first. */
+/** One suggestion (`Suggestion`): what the recogniser wrote, what the polished text has instead
+ * or what the user corrected it to, how often, the newest take, up to three snippets, newest
+ * first, and how many of the times the user's own correction made it (docs/dictation.md §35;
+ * absent when none). */
export const suggestionSchema = z.object({
heard: z.string(),
polished: z.string(),
count: z.number().int().nonnegative(),
last_at_ms: z.number().nonnegative(),
examples: z.array(pairExampleSchema),
+ from_edits: z.number().int().nonnegative().default(0),
});
export type Suggestion = z.infer;
@@ -1744,7 +1749,11 @@ export const suggestionsAnswerSchema = z.discriminatedUnion("status", [
refined: z.number().int().nonnegative(),
skipped: z.number().int().nonnegative(),
total: z.number().int().nonnegative(),
+ /** The suggestions counted `SUGGESTION_REPEATED_MIN` times or more, and those the user
+ * corrected themselves (`from_edits`): the page's 推荐. */
repeated: z.number().int().nonnegative(),
+ /** The takes looked at that the user corrected (docs/dictation.md §35). */
+ edited: z.number().int().nonnegative().default(0),
pairs: z.array(suggestionSchema),
}),
]);
@@ -1809,7 +1818,12 @@ export type UndoOutcome = z.infer;
/** One suggestion picked for a batch 加入词典 (`SuggestionPick`): the pair and the take of its
* first example, the new entry's source. */
-export type SuggestionPick = { heard: string; polished: string; history_id: string };
+export const suggestionPickSchema = z.object({
+ heard: z.string(),
+ polished: z.string(),
+ history_id: z.string(),
+});
+export type SuggestionPick = z.infer;
/** One suggestion picked for a batch 忽略 (`SuggestionPair`). */
export type SuggestionPair = { heard: string; polished: string };
@@ -1854,6 +1868,40 @@ export const batchUndoOutcomeSchema = z.discriminatedUnion("kind", [
]);
export type BatchUndoOutcome = z.infer;
+/** What came of a 从选中文字学习 (`LearnOutcome`, docs/dictation.md §35): the pairs the corrected
+ * takes give (`safe`: none is short enough to change other words, so 加入词典 is offered at
+ * once), or why there is nothing to learn. */
+export const learnOutcomeSchema = z.discriminatedUnion("kind", [
+ z.object({ kind: z.literal("learned"), pairs: z.array(suggestionPickSchema), safe: z.boolean() }),
+ z.object({ kind: z.literal("no_pairs") }),
+ z.object({ kind: z.literal("unchanged") }),
+ z.object({ kind: z.literal("no_match") }),
+ z.object({ kind: z.literal("no_selection") }),
+ z.object({ kind: z.literal("too_long"), max: z.number().int().positive() }),
+ z.object({ kind: z.literal("terminal") }),
+ z.object({ kind: z.literal("history_off") }),
+ z.object({ kind: z.literal("failed"), message: z.string() }),
+]);
+export type LearnOutcome = z.infer;
+
+/** The pill's notice after a 从选中文字学习 (`LearnNotice`, `UiState.learn_notice`): which, what
+ * came of it, whether it is on the pill yet (it waits behind a take's result), and what its
+ * 加入词典 and 撤销 did. */
+export const learnNoticeSchema = z.object({
+ id: z.number().int().nonnegative(),
+ outcome: learnOutcomeSchema,
+ shown: z.boolean(),
+ accepted: z
+ .object({
+ added: z.number().int().nonnegative(),
+ refused: z.number().int().nonnegative(),
+ undo: z.string().optional(),
+ })
+ .optional(),
+ undone: batchUndoOutcomeSchema.optional(),
+});
+export type LearnNotice = z.infer;
+
/** A hint the rules page shows beside a rule (`RuleWarning`, `rules_warnings`): another rule finds
* the same, another turns its replacement back, or it turns an entry's right spelling into one
* of its mis-hearings. Only rules that run and entries that are on count. */
@@ -1912,6 +1960,18 @@ export const processedTextSchema = z.object({
});
export type ProcessedText = z.infer;
+/** `voltip_core::history::CorrectedText`: what the user corrected a take to in the application
+ * it went to, as 从选中文字学习 read it (docs/dictation.md §35); the entry's `text` stays what was
+ * inserted. */
+export const correctedTextSchema = z.object({
+ text: z.string(),
+ at_ms: z.number().nonnegative(),
+ /** `follow`: read in the text field after the paste, the experimental tracking of a later
+ * version (docs/dictation.md §35); this version writes `selection` only. */
+ via: z.enum(["selection", "follow"]),
+});
+export type CorrectedText = z.infer;
+
/** `voltip_core::history::process::ProcessState`: where one `history_process` request is. */
export const processStateSchema = z.discriminatedUnion("state", [
z.object({
@@ -1983,6 +2043,8 @@ export const historyEntrySchema = z.object({
origin: entryOriginSchema.optional(),
/** 用 AI 预设处理's result (docs/dictation.md §22); absent until it ran. */
processed: processedTextSchema.optional(),
+ /** The user's correction of the take (docs/dictation.md §35); absent until they taught it. */
+ corrected: correctedTextSchema.optional(),
/** The audio or video file it was transcribed from (docs/dictation.md §31); absent for takes. */
file: importedFileSchema.optional(),
/** How long each step of the take took (docs/dictation.md §30.1); absent for imports, phone
@@ -2905,6 +2967,10 @@ export const hotkeyStatusSchema = z.object({
* none is set. */
copy_last_registered: z.string().optional(),
copy_last_error: z.string().optional(),
+ /** The 从选中文字学习 chord (docs/dictation.md §35): registered, or why not; both absent while
+ * none is set. */
+ learn_registered: z.string().optional(),
+ learn_error: z.string().optional(),
/** When the lone key's input hook last came back by itself after the system took it away
* (docs/dictation.md §29), in ms since the epoch; absent until it has. */
solo_recovered_at: z.number().int().nonnegative().optional(),
@@ -3341,6 +3407,8 @@ export const uiStateSchema = z.object({
/** The pairs the learning suggestions leave out (§16.10); `[]` until one is ignored, and on the
* phone. */
vocabulary_ignored: z.array(ignoredPairSchema).default(() => []),
+ /** The pill's notice after a 从选中文字学习 (§35); absent while there is none, and on the phone. */
+ learn_notice: learnNoticeSchema.nullable().optional(),
/** The scenes (§18), in matching order; `[]` on the phone. */
scenes: z.array(sceneSchema).default(() => []),
/** The custom presets (§21), in the order they were made; `[]` on the phone. The built-in
@@ -3421,6 +3489,8 @@ export const uiEventSchema = z.discriminatedUnion("type", [
z.object({ type: z.literal("rules"), rules: z.array(replacementRuleSchema) }),
/** The pairs the learning suggestions leave out, whole, after every change (§16.10). */
z.object({ type: z.literal("vocabulary_ignored"), pairs: z.array(ignoredPairSchema) }),
+ /** The pill's notice after a 从选中文字学习, whole, or `null` when it went (§35). */
+ z.object({ type: z.literal("learn_notice"), notice: learnNoticeSchema.nullable() }),
/** The whole scene list after every change (§18). */
z.object({ type: z.literal("scenes"), scenes: z.array(sceneSchema) }),
/** The custom presets, whole (§21). */
@@ -3644,6 +3714,15 @@ export interface CommandArgs {
settings_set_edit_hotkey: { hotkey: string | null };
/** 复制上一条结果 (docs/dictation.md §28): its chord, or `null` for none. */
settings_set_copy_last_hotkey: { hotkey: string | null };
+ /** 从选中文字学习 (docs/dictation.md §35): its chord, or `null` for none. */
+ settings_set_learn_hotkey: { hotkey: string | null };
+ /** The learn notice's 加入词典 / 撤销 / × (§35), for its `id`; the core re-emits `learn_notice`. */
+ learn_notice_accept: { id: number };
+ learn_notice_undo: { id: number };
+ learn_notice_dismiss: { id: number };
+ learn_notice_keep: { id: number };
+ /** The history detail's 移除 (§35): forget the user's correction of the entry. */
+ history_clear_corrected: { id: string };
/** The lone-key trigger (docs/dictation.md §13.1), or `null` to switch it off. */
settings_set_solo_key: { key: SoloKey | null };
/** The microphone takes record from (an `audio_devices` id), or `null` for the system default. */
@@ -3960,6 +4039,12 @@ export interface CommandArgs {
overlay_paste: { text: string };
/** The result card's 打开历史 (`Backend.openHistory`): the main window opens on the history page. */
open_history: undefined;
+ /** The learn notice's 查看 (`Backend.openSuggestions`, §35): the main window opens on the
+ * dictionary's learning suggestions. */
+ open_suggestions: undefined;
+ /** The learn notice's 打开设置 while the history is off (`Backend.openPrivacy`, §35): the main
+ * window opens on 设置 › 隐私. */
+ open_privacy: undefined;
}
export type CommandName = keyof CommandArgs;
/** Queries and streams: called through dedicated `Backend` methods, never through `invoke`. */
@@ -3996,6 +4081,8 @@ export type QueryCommand =
| "overlay_copy"
| "overlay_paste"
| "open_history"
+ | "open_suggestions"
+ | "open_privacy"
| "backup_export"
| "backup_open"
| "backup_import"
@@ -4196,6 +4283,8 @@ export function applyEvent(state: UiState, event: UiEvent): UiState {
return { ...state, rules: event.rules };
case "vocabulary_ignored":
return { ...state, vocabulary_ignored: event.pairs };
+ case "learn_notice":
+ return { ...state, learn_notice: event.notice };
case "scenes":
return { ...state, scenes: event.scenes };
case "presets":
diff --git a/packages/shared/src/suggestions.test.ts b/packages/shared/src/suggestions.test.ts
index 635ce2ce..54170172 100644
--- a/packages/shared/src/suggestions.test.ts
+++ b/packages/shared/src/suggestions.test.ts
@@ -103,8 +103,9 @@ describe("learning suggestions (docs/dictation.md §16.10)", () => {
it("counts the clean-up's pairs, most frequent first and then the newest", () => {
const out = suggestVocabulary([], [], TAKES, []);
expect([out.scanned, out.refined, out.skipped, out.total]).toEqual([5, 4, 0, 3]);
+ // 非 → 飞 is counted with its unchanged neighbour (§16.10).
expect(heardOf([])).toEqual([
- ["非", "飞", 2],
+ ["非书", "飞书", 2],
["维他命", "Voltip", 1],
["库伯内特斯", "Kubernetes", 1],
]);
@@ -128,6 +129,7 @@ describe("learning suggestions (docs/dictation.md §16.10)", () => {
3,
[["维他命", 2]],
]);
+ // Ignored before it was widened: still ignored.
const ignored = [{ heard: "非", polished: "飞", at_ms: 1 }];
expect(suggestVocabulary([], [], more, ignored)).toMatchObject({ total: 2, repeated: 2 });
expect(suggestVocabulary([], [], [], []).repeated).toBe(0);
@@ -137,12 +139,71 @@ describe("learning suggestions (docs/dictation.md §16.10)", () => {
const dictionary = [entry("Voltip", ["维他命"]), entry("飞书", ["非"], { enabled: false })];
const ignored = [{ heard: "库伯内特斯", polished: "Kubernetes", at_ms: 1 }];
expect(suggestVocabulary(dictionary, [], TAKES, ignored).pairs.map((p) => p.heard)).toEqual([
- "非",
+ "非书",
]);
const otherCase = [{ heard: "库伯内特斯", polished: "kubernetes", at_ms: 1 }];
expect(suggestVocabulary([], [], TAKES, otherCase).total).toBe(3);
});
+ it("§35: the user's corrections are counted with the clean-up's pairs, shown once corrected", () => {
+ const corrected = (text: string, fixed: string, at: number): HistoryEntry => ({
+ ...take(text, text, at, false),
+ corrected: { text: fixed, at_ms: at + 1, via: "selection" },
+ });
+ const takes = [
+ corrected("我在用 Quinn for max 做测试", "我在用 Qwen 4 max 做测试", 50),
+ corrected("发到非书群", "发到飞书群", 40),
+ take("又是非书", "又是飞书。", 30),
+ take("库伯内特斯部署", "Kubernetes 部署", 20),
+ ];
+ const out = suggestVocabulary([], [], takes, []);
+ expect(out.pairs.map((p) => [p.heard, p.polished, p.count, p.from_edits])).toEqual([
+ ["非书", "飞书", 2, 1],
+ ["Quinn for", "Qwen 4", 1, 1],
+ ["库伯内特斯", "Kubernetes", 1, 0],
+ ]);
+ expect([out.scanned, out.refined, out.edited, out.total, out.repeated]).toEqual([
+ 4, 2, 2, 3, 2,
+ ]);
+ expect(out.pairs[1]?.examples[0]).toEqual({
+ history_id: takes[0]?.id,
+ snippet: "我在用 Quinn for max 做测试",
+ });
+ });
+
+ it("regression: a correction counts once per take, and a corrected take too long to compare is still edited", () => {
+ // Goal review of PR #260 (2026-11-18): the plan counts the user's corrections once per take.
+ const corrected = (text: string, fixed: string, at: number): HistoryEntry => ({
+ ...take(text, text, at, false),
+ corrected: { text: fixed, at_ms: at + 1, via: "selection" },
+ });
+ const twice = suggestVocabulary(
+ [],
+ [],
+ [corrected("Quinn for max 和 Quinn for max 都试过", "Qwen 4 max 和 Qwen 4 max 都试过", 50)],
+ [],
+ );
+ expect(twice.pairs.map((p) => [p.heard, p.polished, p.count, p.from_edits])).toEqual([
+ ["Quinn for", "Qwen 4", 1, 1],
+ ]);
+ const long = "字 ".repeat(1200);
+ const skipped = suggestVocabulary([], [], [corrected(long, `${long}改`, 50)], []);
+ expect([skipped.scanned, skipped.skipped, skipped.edited]).toEqual([1, 1, 1]);
+ });
+
+ it("§16.10: a single character is widened to the spelling the takes use, and stays alone without a neighbour", () => {
+ const takes = [
+ take("钉丁开会", "钉钉开会。", 50),
+ take("打开钉钉", "打开钉钉。", 40),
+ take("钉钉群里说", "钉钉群里说。", 30),
+ take("用a非。", "用a飞。", 20),
+ ];
+ expect(suggestVocabulary([], [], takes, []).pairs.map((p) => [p.heard, p.polished])).toEqual([
+ ["钉丁", "钉钉"],
+ ["非", "飞"],
+ ]);
+ });
+
it("counts a take too long to compare as skipped", () => {
const long = take("字".repeat(1001), "子".repeat(1001), 5);
expect(suggestVocabulary([], [], [long], [])).toMatchObject({ skipped: 1, total: 0 });
@@ -160,7 +221,7 @@ describe("learning suggestions (docs/dictation.md §16.10)", () => {
expect([out.scanned, out.refined, out.total]).toEqual([3, 2, 2]);
expect(out.pairs.map((p) => [p.heard, p.count])).toEqual([
["维他命", 1],
- ["非", 1],
+ ["非书", 1],
]);
expect(suggestVocabulary([], [], takes, []).scanned).toBe(4);
});
diff --git a/packages/shared/src/suggestions.ts b/packages/shared/src/suggestions.ts
index d3f1ebf4..b1c1c0d8 100644
--- a/packages/shared/src/suggestions.ts
+++ b/packages/shared/src/suggestions.ts
@@ -4,7 +4,7 @@
// rules page's hints — with the semantics of `voltip_core::vocabulary::{suggest, rule_warnings}`.
import { diffTokens } from "./refine";
-import { MAX_PAIR_DIFF_CELLS, takePolishPairs } from "./quick-fix";
+import { MAX_PAIR_DIFF_CELLS, type PolishPair, takeEditPairs, takePolishPairs } from "./quick-fix";
import {
type BacktestDraft,
type BatchItem,
@@ -100,12 +100,131 @@ function snippetAround(raw: string, start: number, end: number): string {
* older takes are not read past it. */
export const MAX_SCAN_CELLS = 50_000_000;
+/** One pair of one take before the counting (`voltip_core::mcp::candidates::Found`). */
+interface Found {
+ take: number;
+ pair: PolishPair;
+ /** The user's correction made it (§35), not the AI clean-up. */
+ edit: boolean;
+}
+
+/** One CJK character: Han, kana or Hangul (`is_cjk_letter`). */
+const CJK_LETTER =
+ /^[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}々〆〇]$/u;
+
+function singleCjk(text: string): boolean {
+ return CJK_LETTER.test(text);
+}
+
+/** How often `needle` occurs in `text`, overlapping occurrences counted. */
+function occurrences(text: string, needle: string): number {
+ let n = 0;
+ for (let at = text.indexOf(needle); at >= 0; at = text.indexOf(needle, at + 1)) n += 1;
+ return n;
+}
+
+/** A pair widened by one unchanged neighbour (`voltip_core::mcp::candidates::widen`). */
+interface Widened {
+ found: Found;
+ /** The pair before it was widened, when it was. */
+ single?: { heard: string; polished: string };
+}
+
+/** Every pair whose heard or right form is a single CJK character, widened by the same
+ * unchanged neighbour on both sides (docs/dictation.md §16.10): 非 → 飞 in 「非书」 becomes
+ * 非书 → 飞书. With a neighbour on both sides, the side whose widened right form occurs more often
+ * in the compared takes' final texts and corrections wins, the right one on a tie. */
+function widen(
+ takes: readonly HistoryEntry[],
+ found: readonly Found[],
+ compared: readonly number[],
+): Widened[] {
+ const options = found.map((f) => {
+ const { pair } = f;
+ if (!singleCjk(pair.heard) && !singleCjk(pair.polished)) return [];
+ const take = takes[f.take];
+ if (take === undefined) return [];
+ const raw = take.raw_text;
+ const right = f.edit ? (take.corrected?.text ?? take.text) : take.text;
+ const out: {
+ heard: string;
+ polished: string;
+ start: number;
+ end: number;
+ polishedStart: number;
+ polishedEnd: number;
+ }[] = [];
+ const after = Array.from(raw.slice(pair.end))[0];
+ const afterRight = Array.from(right.slice(pair.polishedEnd))[0];
+ if (after !== undefined && after === afterRight && singleCjk(after)) {
+ out.push({
+ heard: pair.heard + after,
+ polished: pair.polished + after,
+ start: pair.start,
+ end: pair.end + after.length,
+ polishedStart: pair.polishedStart,
+ polishedEnd: pair.polishedEnd + after.length,
+ });
+ }
+ const before = Array.from(raw.slice(0, pair.start)).at(-1);
+ const beforeRight = Array.from(right.slice(0, pair.polishedStart)).at(-1);
+ if (before !== undefined && before === beforeRight && singleCjk(before)) {
+ out.push({
+ heard: before + pair.heard,
+ polished: before + pair.polished,
+ start: pair.start - before.length,
+ end: pair.end,
+ polishedStart: pair.polishedStart - before.length,
+ polishedEnd: pair.polishedEnd,
+ });
+ }
+ return out;
+ });
+ const counts = new Map();
+ for (const o of options) {
+ if (o.length < 2) continue;
+ for (const w of o) {
+ if (counts.has(w.polished)) continue;
+ let n = 0;
+ for (const index of compared) {
+ const take = takes[index];
+ if (take === undefined) continue;
+ n += occurrences(take.text, w.polished);
+ if (take.corrected !== undefined) n += occurrences(take.corrected.text, w.polished);
+ }
+ counts.set(w.polished, n);
+ }
+ }
+ return found.map((f, i) => {
+ const o = options[i] ?? [];
+ const [rightSide, leftSide] = o;
+ const chosen =
+ rightSide === undefined
+ ? undefined
+ : leftSide !== undefined &&
+ (counts.get(leftSide.polished) ?? 0) > (counts.get(rightSide.polished) ?? 0)
+ ? leftSide
+ : rightSide;
+ if (chosen === undefined) return { found: f };
+ return {
+ found: { ...f, pair: { ...chosen } },
+ single: { heard: f.pair.heard, polished: f.pair.polished },
+ };
+ });
+}
+
+/** The cells the token LCS of `a` and `b` compares, as the core counts them against its caps. */
+function cellsOf(a: string, b: string): number {
+ return (diffTokens(a).length + 1) * (diffTokens(b).length + 1);
+}
+
/** `vocabulary_suggestions` as the core answers it, over `takes` (newest first, as the history
- * holds them): the AI clean-up's pairs (`takePolishPairs`, the core's comparison), without the
- * ones an enabled entry corrects already and the ignored ones, most frequent first, then the most
- * recent; at most `limit` of them. Like the core it stops reading older takes once the cells it
- * compared would pass `scanCells` (a take whose corrections or rules fired is compared twice),
- * and `scanned` counts the takes it read. */
+ * holds them): the AI clean-up's pairs (`takePolishPairs`, the core's comparison) and the user's
+ * corrections (`takeEditPairs`, §35), widened when they were single characters and counted
+ * together, without the ones an enabled entry corrects already and the ignored ones (also when
+ * ignored before the widening), most frequent first, then the most recent; at most `limit` of
+ * them. Like the core it stops reading older takes once the cells it compared would pass
+ * `scanCells`, and `scanned` counts the takes it read. */
export function suggestVocabulary(
dictionary: readonly DictionaryEntry[],
rules: readonly ReplacementRule[],
@@ -115,58 +234,106 @@ export function suggestVocabulary(
scanCells: number = MAX_SCAN_CELLS,
): ReadySuggestions {
const known = dictionary.filter((e) => e.enabled).flatMap((e) => e.heard_as);
- const found = new Map();
+ const isKnown = (heard: string) => known.some((k) => sameIgnoringAsciiCase(k, heard));
+ const found: Found[] = [];
+ const compared: number[] = [];
let skipped = 0;
let scanned = 0;
+ let edited = 0;
let cells = 0;
- for (const take of takes) {
- if (!take.refined) {
+ for (const [index, take] of takes.entries()) {
+ const corrected = take.corrected?.text;
+ if (!take.refined && corrected === undefined) {
scanned += 1;
continue;
}
- const size = (diffTokens(take.raw_text).length + 1) * (diffTokens(take.text).length + 1);
- if (size > MAX_PAIR_DIFF_CELLS) {
+ const polish = take.refined ? cellsOf(take.raw_text, take.text) : undefined;
+ const edit =
+ corrected === undefined
+ ? undefined
+ : { text: cellsOf(take.text, corrected), raw: cellsOf(take.raw_text, take.text) };
+ if (
+ (polish ?? 0) > MAX_PAIR_DIFF_CELLS ||
+ (edit !== undefined && (edit.text > MAX_PAIR_DIFF_CELLS || edit.raw > MAX_PAIR_DIFF_CELLS))
+ ) {
scanned += 1;
skipped += 1;
+ // Read, if not compared: one of the corrected takes, as a skipped polished one is counted
+ // among the polished.
+ if (corrected !== undefined) edited += 1;
continue;
}
const fired =
(take.vocabulary?.corrections.length ?? 0) + (take.vocabulary?.rules.length ?? 0) > 0;
- const cost = fired ? size * 2 : size;
+ const replayCost = fired ? (polish ?? cellsOf(take.raw_text, take.raw_text)) : 0;
+ const cost = (polish ?? 0) + (edit === undefined ? 0 : edit.text + edit.raw) + replayCost;
if (cells + cost > scanCells) break;
cells += cost;
scanned += 1;
- for (const pair of takePolishPairs(take, dictionary, rules)) {
- const key = JSON.stringify([pair.heard, pair.polished]);
- let suggestion = found.get(key);
- if (suggestion === undefined) {
- suggestion = {
- heard: pair.heard,
- polished: pair.polished,
- count: 0,
- last_at_ms: take.at_ms,
- examples: [],
- };
- found.set(key, suggestion);
- }
- suggestion.count += 1;
- suggestion.last_at_ms = Math.max(suggestion.last_at_ms, take.at_ms);
- if (
- suggestion.examples.length < 3 &&
- !suggestion.examples.some((e) => e.history_id === take.id)
- ) {
- suggestion.examples.push({
- history_id: take.id,
- snippet: snippetAround(take.raw_text, pair.start, pair.end),
- });
- }
+ compared.push(index);
+ if (corrected !== undefined) edited += 1;
+ for (const pair of takePolishPairs(take, dictionary, rules))
+ found.push({ take: index, pair, edit: false });
+ for (const pair of takeEditPairs(take, dictionary, rules))
+ found.push({ take: index, pair, edit: true });
+ }
+ const bySuggestion = new Map<
+ string,
+ Suggestion & { single?: { heard: string; polished: string } }
+ >();
+ // The user's corrections count each pair once per take (docs/dictation.md §16.10).
+ const correctedPairs = new Set();
+ for (const { found: f, single } of widen(takes, found, compared)) {
+ const take = takes[f.take];
+ if (take === undefined) continue;
+ const key = JSON.stringify([f.pair.heard, f.pair.polished]);
+ if (f.edit) {
+ const once = JSON.stringify([f.take, f.pair.heard, f.pair.polished]);
+ if (correctedPairs.has(once)) continue;
+ correctedPairs.add(once);
+ }
+ let suggestion = bySuggestion.get(key);
+ if (suggestion === undefined) {
+ suggestion = {
+ heard: f.pair.heard,
+ polished: f.pair.polished,
+ count: 0,
+ last_at_ms: take.at_ms,
+ examples: [],
+ from_edits: 0,
+ ...(single === undefined ? {} : { single }),
+ };
+ bySuggestion.set(key, suggestion);
+ }
+ suggestion.count += 1;
+ if (f.edit) suggestion.from_edits += 1;
+ suggestion.last_at_ms = Math.max(suggestion.last_at_ms, take.at_ms);
+ if (
+ suggestion.examples.length < 3 &&
+ !suggestion.examples.some((e) => e.history_id === take.id)
+ ) {
+ suggestion.examples.push({
+ history_id: take.id,
+ snippet: snippetAround(take.raw_text, f.pair.start, f.pair.end),
+ });
}
}
- const pairs = [...found.values()].filter(
- (s) =>
- !known.some((k) => sameIgnoringAsciiCase(k, s.heard)) &&
- !ignored.some((i) => i.heard === s.heard && i.polished === s.polished),
- );
+ const isIgnored = (s: {
+ heard: string;
+ polished: string;
+ single?: { heard: string; polished: string };
+ }) =>
+ ignored.some(
+ (i) =>
+ (i.heard === s.heard && i.polished === s.polished) ||
+ (s.single !== undefined && i.heard === s.single.heard && i.polished === s.single.polished),
+ );
+ const pairs: Suggestion[] = [...bySuggestion.values()]
+ .filter(
+ (s) =>
+ !isKnown(s.heard) && !(s.single !== undefined && isKnown(s.single.heard)) && !isIgnored(s),
+ )
+ .map(({ single: _single, ...s }) => s);
pairs.sort((a, b) => b.count - a.count || b.last_at_ms - a.last_at_ms);
return {
status: "ready",
@@ -174,7 +341,8 @@ export function suggestVocabulary(
refined: takes.slice(0, scanned).filter((t) => t.refined).length,
skipped,
total: pairs.length,
- repeated: pairs.filter((p) => p.count >= SUGGESTION_REPEATED_MIN).length,
+ repeated: pairs.filter((p) => p.count >= SUGGESTION_REPEATED_MIN || p.from_edits > 0).length,
+ edited,
pairs: pairs.slice(0, limit),
};
}
diff --git a/packages/shared/src/tauri-backend.test.ts b/packages/shared/src/tauri-backend.test.ts
index f5d77ddc..b0d96470 100644
--- a/packages/shared/src/tauri-backend.test.ts
+++ b/packages/shared/src/tauri-backend.test.ts
@@ -361,6 +361,7 @@ describe("TauriBackend", () => {
skipped: 0,
total: 0,
repeated: 0,
+ edited: 0,
pairs: [],
};
const undo = { id: "u", entry_id: "e", term: "Voltip", created: true, previous_heard_as: [] };
diff --git a/packages/shared/src/tauri-backend.ts b/packages/shared/src/tauri-backend.ts
index af6861fd..9e1411f1 100644
--- a/packages/shared/src/tauri-backend.ts
+++ b/packages/shared/src/tauri-backend.ts
@@ -425,6 +425,14 @@ export class TauriBackend implements Backend {
await this.transport.invoke("open_history");
}
+ async openSuggestions() {
+ await this.transport.invoke("open_suggestions");
+ }
+
+ async openPrivacy() {
+ await this.transport.invoke("open_privacy");
+ }
+
async meter(deviceId: string | undefined, onFrame: FrameListener): Promise {
const warn = this.warn();
const channel = (this.transport.channel ?? newChannel)();
diff --git a/packages/ui/src/backend/BackendProvider.test.tsx b/packages/ui/src/backend/BackendProvider.test.tsx
index dd3a8c0d..506174c9 100644
--- a/packages/ui/src/backend/BackendProvider.test.tsx
+++ b/packages/ui/src/backend/BackendProvider.test.tsx
@@ -97,6 +97,8 @@ describe("BackendProvider", () => {
overlayCopy: inner.overlayCopy.bind(inner),
overlayPaste: inner.overlayPaste.bind(inner),
openHistory: inner.openHistory.bind(inner),
+ openSuggestions: inner.openSuggestions.bind(inner),
+ openPrivacy: inner.openPrivacy.bind(inner),
providerConsoleOpen: inner.providerConsoleOpen.bind(inner),
projectLinkOpen: inner.projectLinkOpen.bind(inner),
guideOpen: inner.guideOpen.bind(inner),
@@ -389,6 +391,8 @@ describe("BackendProvider", () => {
overlayCopy: () => Promise.resolve(),
overlayPaste: () => Promise.resolve({ kind: "pasted" as const }),
openHistory: () => Promise.resolve(),
+ openSuggestions: () => Promise.resolve(),
+ openPrivacy: () => Promise.resolve(),
providerConsoleOpen: () => Promise.resolve(),
projectLinkOpen: () => Promise.resolve(),
guideOpen: () => Promise.resolve(),
diff --git a/scripts/lib/smoke-dictation.sh b/scripts/lib/smoke-dictation.sh
index 4bf43590..dd619a01 100644
--- a/scripts/lib/smoke-dictation.sh
+++ b/scripts/lib/smoke-dictation.sh
@@ -61,15 +61,20 @@ PY
# Settings for a take that ends in the injector: the custom provider's recognition at
# (the mock; the custom endpoint needs no key), no refine; every
# other value is the app default (澄空 theme, system locale, hold Ctrl+Alt+Space), so screenshots
-# look like a first start. voltip_smoke_settings [paste|clipboard_only] [relay: true|false]
+# look like a first start. The optional last argument is 从选中文字学习's shortcut (none by
+# default, docs/dictation.md §35).
+# voltip_smoke_settings [paste|clipboard_only] [relay: true|false] [learn shortcut]
voltip_smoke_settings() {
mkdir -p "$(dirname "$1")"
+ local learn=""
+ [ -n "${5:-}" ] && learn="\"learn_hotkey\": \"$5\","
cat >"$1" <correctedvia`
+# (empty when none), read the same way: voltip_smoke_last_corrected
+voltip_smoke_last_corrected() {
+ python3 - "$1" <<'PY'
+import json, pathlib, sqlite3, sys
+path = pathlib.Path(sys.argv[1])
+if not path.is_file():
+ sys.exit(0)
+try:
+ conn = sqlite3.connect(f"{path.resolve().as_uri()}?mode=ro", uri=True)
+ rows = conn.execute("SELECT json FROM entries ORDER BY at_ms DESC, rowid DESC").fetchall()
+except sqlite3.Error:
+ sys.exit(0)
+for (row,) in rows:
+ e = json.loads(row)
+ c = e.get("corrected")
+ if c:
+ print(f"{e.get('text', '')}\t{c.get('text', '')}\t{c.get('via', '')}")
+ break
+PY
+}
+
# Strip ANSI colour from a log for grepping: voltip_smoke_plain
voltip_smoke_plain() {
sed -E 's/\x1b\[[0-9;]*m//g' "$1"
diff --git a/scripts/smoke-desktop-linux.sh b/scripts/smoke-desktop-linux.sh
index 3f2324cc..d14f7f2a 100755
--- a/scripts/smoke-desktop-linux.sh
+++ b/scripts/smoke-desktop-linux.sh
@@ -5,13 +5,17 @@
# Evidence that the shell builds, starts the core and renders — on a machine with no display and
# no keychain (CI runner, container). The hotkey take runs to the injector (docs/dictation.md §14):
# a private PulseAudio null sink is the microphone, a local mock stands in for the ASR, and the
-# X11 clipboard must hold a sentinel again after the paste. Usage: scripts/smoke-desktop-linux.sh [out.png]
+# X11 clipboard must hold a sentinel again after the paste. Then 从选中文字学习 (docs/dictation.md
+# §35): a Tk entry holds the take as the user corrected it, selected; the learn shortcut copies the
+# selection, the correction is kept with the take, the pill shows the notice and the clipboard holds
+# the sentinel again. Usage: scripts/smoke-desktop-linux.sh [out.png]
set -euo pipefail
cd "$(dirname "$0")/.."
. scripts/lib/build-env.sh && voltip_load_build_env
. scripts/lib/smoke-dictation.sh
out=${1:-docs/acceptance/screens/tauri/desktop-linux-xvfb.png}
-display=:99
+# Another display when :99 is taken on this machine (VOLTIP_SMOKE_DISPLAY=:197).
+display=${VOLTIP_SMOKE_DISPLAY:-:99}
screen=1280x800x24
window_timeout=90
@@ -25,6 +29,12 @@ for c in python3 /usr/bin/python3; do
if command -v "$c" >/dev/null && "$c" -c "import PIL" >/dev/null 2>&1; then PY=$c; break; fi
done
[ -n "$PY" ] || { echo "smoke-desktop-linux: no python3 with Pillow (apt install python3-pil)"; exit 2; }
+# The corrected text sits in a Tk entry: an X11 text widget that takes Ctrl+Insert as copy.
+TK_PY=""
+for c in python3 /usr/bin/python3; do
+ if command -v "$c" >/dev/null && "$c" -c "import tkinter" >/dev/null 2>&1; then TK_PY=$c; break; fi
+done
+[ -n "$TK_PY" ] || { echo "smoke-desktop-linux: no python3 with tkinter (apt install python3-tk)"; exit 2; }
# The debug binary embeds apps/desktop/dist (custom-protocol); rebuild it first or the window shows
# whatever the last `vite build` produced.
pnpm --filter @voltip/desktop run build >/dev/null
@@ -33,8 +43,9 @@ mkdir -p "$(dirname "$out")"
data=$(mktemp -d)
app_pid=""
xvfb_pid=""
+tk_pid=""
cleanup() {
- voltip_smoke_stop "$app_pid" "$xvfb_pid" "${VOLTIP_SMOKE_ASR_PID:-}"
+ voltip_smoke_stop "$tk_pid" "$app_pid" "$xvfb_pid" "${VOLTIP_SMOKE_ASR_PID:-}"
voltip_smoke_pulse_mic_stop
# Keep the app log next to the screenshots (CI uploads it; git ignores it).
[ -f "$data/app.log" ] && sed -E 's/\x1b\[[0-9;]*m//g' "$data/app.log" > "${out%.png}-app.log" 2>/dev/null || true
@@ -52,7 +63,8 @@ sentinel="voltip-smoke-sentinel-$$"
voltip_smoke_tone_wav "$data/tone.wav" 8
voltip_smoke_mock_asr_start "$data" "$spoken"
voltip_smoke_pulse_mic_start "$data" "voltip_smoke_$$"
-voltip_smoke_settings "$data/data/voltip/settings.json" "$VOLTIP_SMOKE_ASR_URL" paste true
+learn_hotkey="Ctrl+Alt+L"
+voltip_smoke_settings "$data/data/voltip/settings.json" "$VOLTIP_SMOKE_ASR_URL" paste true "$learn_hotkey"
# VOLTIP_DEV_OPAQUE_OVERLAY: Xvfb has no compositor, so an RGBA (transparent) window renders as a
# black rectangle; the debug-only knob draws the pill window opaque so the capture shows the pill.
@@ -144,7 +156,7 @@ if ! timeout 5 sh -c 'until [ "$(DISPLAY=$2 xclip -o -selection clipboard 2>/dev
fi
echo "smoke-desktop-linux: pasted via $(voltip_smoke_plain "$data/app.log" | grep -oE 'pasted .*tool=[a-z0-9-]+' | grep -oE 'tool=[a-z0-9-]+' | head -1 || echo 'tool=?'), clipboard restored to the sentinel"
# The outcome dwells 2.5 s (a failure that keeps its text 6 s), then the core goes idle and the pill hides.
-if ! timeout 15 sh -c 'until [ "$( (DISPLAY=:99 xdotool search --onlyvisible --name "^Voltip Overlay$" || true) | wc -l)" = "0" ]; do sleep 0.5; done'; then
+if ! timeout 15 sh -c 'until [ "$( (DISPLAY=$1 xdotool search --onlyvisible --name "^Voltip Overlay$" || true) | wc -l)" = "0" ]; do sleep 0.5; done' _ "$display"; then
echo "smoke-desktop-linux: pill did not hide after the outcome dwell"; exit 1
fi
echo "smoke-desktop-linux: overlay visible while held=$overlay_visible, hidden after outcome=yes"
@@ -181,6 +193,62 @@ if [ "$asr_after" != "$asr_before" ]; then
echo "smoke-desktop-linux: a cancelled take still reached the ASR ($asr_before → $asr_after requests)"; exit 1
fi
echo "smoke-desktop-linux: Escape cancelled the take, nothing sent, cancel key released"
+# 从选中文字学习 (docs/dictation.md §35): the user corrected the take in the application — a Tk
+# entry holds it corrected, selected and focused — and presses the learn shortcut. On X11 it fires
+# once the key is up (a grabbed key swallows the copy chord, §19); the copy chord reads the
+# selection, the take it corrects keeps the correction, the pill shows the notice, and the
+# clipboard holds the sentinel again.
+corrected="Voltip 冒烟测试"
+if ! voltip_smoke_plain "$data/app.log" | grep -q 'learn hotkey registered'; then
+ echo "smoke-desktop-linux: the learn shortcut was not registered"; voltip_smoke_plain "$data/app.log" | grep -iE "hotkey" | tail -6; exit 1
+fi
+if ! timeout 15 sh -c 'until [ "$( (DISPLAY=$1 xdotool search --onlyvisible --name "^Voltip Overlay$" || true) | wc -l)" = "0" ]; do sleep 0.5; done' _ "$display"; then
+ echo "smoke-desktop-linux: the pill did not hide after the cancelled take"; exit 1
+fi
+DISPLAY=$display "$TK_PY" - "$corrected" >"$data/tk.log" 2>&1 <<'PYTK' &
+import sys, tkinter as tk
+root = tk.Tk()
+root.title("voltip-learn-target")
+root.geometry("+640+160")
+entry = tk.Entry(root, width=40)
+entry.insert(0, sys.argv[1])
+entry.pack()
+def ready():
+ entry.focus_force()
+ entry.select_range(0, "end")
+ print("ready", flush=True)
+root.after(200, ready)
+root.mainloop()
+PYTK
+tk_pid=$!
+if ! timeout 15 sh -c 'until grep -q "^ready" "$1"; do sleep 0.2; done' _ "$data/tk.log"; then
+ echo "smoke-desktop-linux: the Tk entry did not come up"; cat "$data/tk.log"; exit 1
+fi
+learned_before=$(voltip_smoke_plain "$data/app.log" | grep -c 'learn selection outcome=' || true)
+DISPLAY=$display xdotool key ctrl+alt+l
+if ! timeout 15 sh -c 'until [ "$(sed -E "s/\x1b\[[0-9;]*m//g" "$1" | grep -c "learn selection outcome=")" -gt "$2" ]; do sleep 0.2; done' _ "$data/app.log" "$learned_before"; then
+ echo "smoke-desktop-linux: the learn shortcut had no outcome"; voltip_smoke_plain "$data/app.log" | grep -iE "learn|selection|copy" | tail -8; exit 1
+fi
+learned=$(voltip_smoke_plain "$data/app.log" | grep -oE 'learn selection outcome="[a-z_]+"' | tail -1)
+if [ "$learned" != 'learn selection outcome="learned"' ]; then
+ echo "smoke-desktop-linux: nothing learned from the selection ($learned)"; voltip_smoke_plain "$data/app.log" | grep -iE "learn|selection" | tail -8; exit 1
+fi
+fixed=$(voltip_smoke_last_corrected "$data/data/voltip/history.sqlite3")
+if [ "$fixed" != "$(printf '%s\t%s\tselection' "$spoken" "$corrected")" ]; then
+ echo "smoke-desktop-linux: the take does not keep the correction: ${fixed:-}"; exit 1
+fi
+if ! timeout 5 sh -c 'until [ "$(DISPLAY=$2 xclip -o -selection clipboard 2>/dev/null)" = "$1" ]; do sleep 0.1; done' _ "$sentinel" "$display"; then
+ echo "smoke-desktop-linux: clipboard not restored after the selection copy: $(DISPLAY=$display xclip -o -selection clipboard 2>/dev/null | head -c 80)"; exit 1
+fi
+if ! timeout 10 sh -c 'until [ "$( (DISPLAY=$1 xdotool search --onlyvisible --name "^Voltip Overlay$" || true) | wc -l)" != "0" ]; do sleep 0.2; done' _ "$display"; then
+ echo "smoke-desktop-linux: the pill did not show the learn notice"; exit 1
+fi
+# The pill's first paint after it maps; the WebView gives no event we can wait on.
+sleep 1
+DISPLAY=$display scrot --overwrite "${out%.png}-learn-notice.png"
+echo "smoke-desktop-linux: learned from the selection, the take keeps \"$corrected\", clipboard restored to the sentinel, the pill shows the notice"
+voltip_smoke_stop "$tk_pid"
+tk_pid=""
grep -iE "dictation" "$data/app.log" | sed -E 's/\x1b\[[0-9;]*m//g' | tail -4
if ! kill -0 "$app_pid" 2>/dev/null; then
echo "smoke-desktop-linux: app exited early"; cat "$data/app.log"; exit 1