配置文件

KeySteer 不要求配置文件。没有配置时直接使用内置默认值，其行为与发布的 keysteer.default.toml 一致。

配置格式是 TOML，发布的完整示例可直接下载。本文按“先能用、再定制、最后排错”的顺序介绍配置。

TIP

只想改快捷键：快速上手中有介绍

想了解动作参数、数组、exec 和插件动词等高级配置：请参阅模式与动作参考。

模式统计与快速切换

toml

[mode_usage]
save_after_entries = 100

[quick_switch]
enabled = true
key = "q"
hold_ms = 350
blacklist = ["idle"]
position = "mouse" # screen / window / mouse

[quick_switch.ui]
font_size = 28
border_width = 1
border_radius = 6
padding_x = 6
padding_y = 8
# background_color = "#EEF2FFFF"
# text_color = "#193781FF"
# border_color = "#506DD0FF"

模式实际切换时累计一次进入记录，重复按键、同模式保持和重启不会增加计数。默认累计 100 次新增记录后后台保存至程序的 workspace.ksw；次数必须大于零。保存或删除工作区预设、正常退出时也会保存尚未写入的统计，不增加周期定时器。Windows/macOS 正常系统退出通知会触发保存；突然断电、强制结束或系统退出超时仍可能丢失最近未保存的计数。

在操作模式中单独按住 Q，350 毫秒后显示常用模式面板；按 Q+1…9 可直接选择，无须等待展开。Q 按下立即执行原绑定；达到长按阈值或用 Q+数字选择模式后，本次按住 Q 的自动重复不再传给模式，直到松开。松开仍正常释放原手势并收起面板，不补发原动作。原动作即使切换到了 Idle，本次长按仍可打开面板。Idle、暂停、排除应用及原生备注输入不接管 Q。面板按进入次数排序，同分按模式 id 排序，显示前 9 项；打开后编号固定，选中当前模式保持状态。黑名单只限制此面板，原快捷键仍可进入对应模式。

screen 位于鼠标所在屏幕中心，window 位于前台窗口中心（没有可用窗口则回退到屏幕中心），mouse 位于鼠标模式提示下方；均限制在当前屏幕内。样式还支持 font_family 和随浅深主题变化的颜色，加载配置时解析。网页可导入工作区查看统计并编辑保存次数和面板配置，导出保留统计；旧版工作区仍可导入，带统计的 v2 文件需要支持该版本的程序。

配置文件位置

程序会在当前目录中查找 keysteer.<名称>.toml：不存在用户配置时，会尝试读取 keysteer.default.toml。如果连它也不存在，则直接使用内置默认值：

Windows：可执行文件所在目录。
macOS .app：~/Library/Application Support/KeySteer/。

文件名必须是 keysteer.<名称>.toml，例如 keysteer.user.toml。也可以显式指定：

bash

keysteer --config keysteer.user.toml
keysteer --config ./profiles/keysteer.work.toml
keysteer --check --config keysteer.user.toml

常用诊断命令：

命令	用途
`keysteer --check -c keysteer.user.toml`	解析并校验配置，不启动运行时。
`keysteer --dump-config`	输出当前生效的完整配置。
`keysteer --doctor`	检查后端、键盘、显示器、权限和启动键。
`keysteer --help`	查看 CLI 选项和默认快捷键。

最小配置

toml

[normal.bindings]
# 在 Normal 中用空格返回 Idle
space = "idle"

未写的字段保留默认值，但显式提供 [normal.bindings] 等绑定表会整体替换对应默认表；删除或改绑的插件快捷键不会被内部默认值补回。建议复制完整默认配置再修改。用户 profile 优先于 default 文件，二者不逐项合并。

保存后点击状态栏菜单的 Reload Configuration 即可生效，程序回到 Idle，再使用启动键进入 Normal。left_shift = "slow" 表示按住减速；改为 shift = "slow_toggle" 可用任一 Shift 点按切换减速。若保留 right_shift = "middle_click"，右 Shift 的专用绑定仍优先。

也可在已有的 [normal.bindings] 中加入数字速度档位：

toml

"1" = "precision_toggle"
"2" = "slow_toggle"
"3" = "fast_toggle"

点按选择精确、慢速或快速档；再按同一个键恢复正常速度，按另一个键直接换档。倍率由 [pointer] 的 precision_multiplier、slow_multiplier、fast_multiplier 控制。Grid 等标签模式仍优先把数字作为标签输入。

配置结构

根配置常用 section 如下：

Section	作用
`[general]`	排除应用。
`[key_aliases]`	自定义键名和跨平台修饰键。
`[hotkeys]`	`Idle` 中可触发 Mode 的入口。
`[normal]`、`[grid]`、`[recursive_grid]`、`[ui_hint]`	各 Mode 的继承、绑定和参数。
`[pointer]`、`[scroll]`	鼠标速度和滚动距离。
`[theme]`、`[mode_indicator]`	颜色和模式提示。
`[[app_configs]]`	按应用覆盖绑定。
`[plugin_modes]`	插件设置和插件 Mode 绑定。
`[debug]`	调试日志类别。

按键和别名

共享前缀的组合键

程序在加载配置时预编译组合键关系，内置动作和插件使用同一规则。默认窗口移动为 primary+d（Windows 为 Alt+D，macOS 为 Command+D），与切换鼠标显示器的 primary+s 独立触发。也可自定义共享前缀：

toml

[normal.bindings]
"primary+s" = "screen next"
"primary+s+d" = "move_window next"

上述自定义配置中，保持 Primary+S 并按 D 移动窗口，只松开短组合则切换鼠标显示器。动作也可改成 move_window previous 或 move_window 2，也可使用任意其他组合键。最后一个非修饰键是完成键，运行时会自动仲裁，不需要配置等待时间，也无需修改插件；none、按应用覆盖、继承及左右修饰键限制均参与判断。

模式切换或有效配置重载会取消尚未执行的短动作。单独修饰键保留即时行为；作为冲突前缀的连续动作只在松开时执行一次完整按下/释放，建议为移动、长按点击或 toggle 保留独立按键。

按键写法

按键绑定的左侧支持单键、组合键和“多个单键共享动作”：

toml

[normal]
long_press_toggle_ms = 500
auto_release_ms = 0

[normal.bindings]
h = "move_left"
"primary+shift+s" = "send primary+shift+s"
"v b" = "fast"

+ 表示同一个组合键。
空格 表示多个独立按键绑定到同一个动作，不是顺序按键。
发布默认配置中，primary 在 macOS 是 Command、Windows 是左 Alt 。它是别名；若你要在 Windows 使用 Ctrl，可以在 [key_aliases.windows] 注释掉。
ctrl、alt、shift 等通用修饰键匹配左右两侧；left_/right_ 前缀只匹配指定一侧。

常用键名包括 a-z、0-9、space、enter、esc、tab、delete、backspace、up、down、left、right、home、end、page_up、page_down、f1-f20 和 numpad_0-numpad_9。

鼠标侧键

Windows 和 macOS 都支持把两个鼠标侧键作为绑定的左值：

按键名	含义	可用别名
`mouse_x1`	第一个侧键，通常是后退键	`xbutton1`、`mouse4`
`mouse_x2`	第二个侧键，通常是前进键	`xbutton2`、`mouse5`

将需要的行加入已有配置的对应段，不要重复创建同名段：

toml

[hotkeys]
mouse_x1 = "normal"          # 从 Idle 进入工作模式

[normal.bindings]
mouse_x1 = "key_help"        # 在工作模式中切换按键提示
mouse_x2 = "grid"            # 进入网格定位
"ctrl+mouse_x2" = "ui_hint"  # Ctrl + 第二个侧键进入 UI Hint

侧键支持普通组合键、绑定继承、应用覆盖和持续动作，例如 mouse_x2 = "scroll_down" 会在按住时滚动、松开时停止。未绑定或设为 none 时保留原生前进/后退行为，即使当前模式独占键盘也不会自动吞掉侧键；匹配绑定后会消费该次侧键的按下与松开。物理侧键不产生语义 Clicked 事件。这些名称也可以作为右值动作，发送真实的鼠标侧键点击：

toml

[normal.bindings]
t = "mouse_x1"  # 模拟第一个侧键
y = "mouse_x2"  # 模拟第二个侧键

同样支持 press mouse_x1、release mouse_x1、toggle mouse_x2。点击沿用普通点击的长按锁定规则；是否后退或前进由接收应用决定。鼠标驱动若已把物理侧键改成键盘快捷键，应绑定驱动实际输出的按键。

自定义别名

toml

[key_aliases]
Hyper = "right_ctrl"

[key_aliases.windows]
Primary = "left_alt"

[key_aliases.macos]
Primary = "left_cmd"

顶层别名在所有平台生效；别名值必须是一个键，不能是组合键；不区分大小写。

Primary 只是一个 可解析 的跨平台别名，不是固定的物理键。发布默认值是 macOS Command、Windows Alt；上例正是把 Windows 的 Primary 显式设为 Alt。大小写不同的 primary/Primary 指向同一个别名。

绑定、数组和继承

右值可以是字符串，也可以是字符串数组：

toml

[normal.bindings]
h = "move_left"
x = ["press shift", "left_click", "release shift"]
"primary+shift+b" = ["exec say start", "wait 300", "exec say done"]

数组中的动作从左到右执行。wait 不会阻塞整个事件循环，只暂停该序列；空数组不合法。

一个 Mode 的有效绑定按以下规则合并：

Mode 自己的 [<mode>.bindings]。
inherits 中列出的父 Mode，按书写顺序查找。
当前应用匹配的 app_configs 覆盖合并结果。
插件的建议绑定只填补空位，不覆盖用户设置。

这里的“合并”指运行时的有效按键表。程序只会进行覆盖替换。

toml

[grid]
inherits = ["hotkeys", "normal"]

[grid.bindings]
q = "none" # 屏蔽从 normal 继承的 q

none 和 __disabled__ 都表示明确禁用。建议保留至少一个 [hotkeys] 入口，否则程序仍会运行，但无法从 Idle 进入其他 Mode。

动作序列

toml

[normal.bindings]
x = ["press shift", "left_click", "release shift"]
"primary+shift+b" = ["exec say start", "wait 300", "exec say done"]

完整动作、参数和 exec 规则见模式与动作。

Normal 和定位 Mode

Normal

Normal 是控制鼠标直接移动、点击、滚动和进入其他 Mode 的平台：

toml

[normal]
long_press_toggle_ms = 500
auto_release_ms = 0

[normal.bindings]
h = "move_left"
j = "move_down"
k = "move_up"
l = "move_right"
";" = "left_click"
g = "grid"
f = "recursive_grid"
"primary+f" = "ui_hint"
"primary+s" = "screen next"

# 可选：把 Primary+H/J/K/L 发送为应用的方向键。
# "primary+h" = "left"
# "primary+j" = "down"
# "primary+k" = "up"
# "primary+l" = "right"

passthrough_unbound_keys = true 是默认行为：Normal 只吞掉命中完整 KeySteer 绑定的输入，未绑定键及未配置的修饰组合会保持原始 down/up 生命周期并透传。

设为 false 时，Normal 恢复键盘独占，并保留旧的宽松组合匹配；Grid、Recursive Grid 和 UI Hint 始终保持独占。Idle 始终透传未命中的输入，并同样采用完整修饰组合匹配。

long_press_toggle_ms 作用于绑定为 鼠标键 的键和单独按住的无参数 toggle 激活键。鼠标键达到阈值后保持对应按钮按下；无参数 toggle 达到阈值后保持激活键自身按下，松开物理键不会撤销 latch。无参数 toggle 可绑定到任意激活键，并一次锁定任意数量的伙伴；伙伴与激活键无论谁先按下都会立即锁定，不等待长按阈值。伙伴按 Normal 绑定转换为实际目标，例如默认的 ;、'、right_shift 分别保持鼠标左、右、中键，而不是保持这些物理键。单独短按无参数 toggle、返回 Normal 或进入 Idle 都会释放全部 latch。设为 0 禁用这两种长按行为，允许范围为 0..=60000 毫秒。

auto_release_ms 默认为 0，即保持上述手动释放行为。它仅适用于直接 click/double-click 绑定经长按形成的鼠标候选；一个或多个物理 Shift/Ctrl/Alt/Win 或 Command 键已按住并透传时，首次实际移动指针才开始计时，后续移动会重置计时。指针保持静止达到该时间后仅释放该鼠标按钮，并立即清除对应的按下提示，不影响物理按住的修饰键；显式 press/toggle 的 latch 不参与。允许范围为 0..=60000 毫秒。

Grid

toml

[grid]
grid_cols = 5
grid_rows = 4
keys = "12345qwertasdfgzxcvb"
max_depth = 3
cursor_follow_selection = true

[grid.lifecycle]
after_finish = "normal"
after_click = "finish"

keys 必须正好包含 grid_cols × grid_rows 个字符，按从左到右、从上到下填入。max_depth 是确认目标前的最大层数。初始画面会在一级格中央显示大号第一键，并在内部预览小号第二键；[grid.ui] 的 matched_text_color 控制大字，text_color 控制小字的基色，matched_border_color 控制内部细线。这个预览只影响绘制，不提前改变选择深度。

Recursive Grid

[recursive_grid.ui] 的 font_size = 0（默认）按格子短边的 40% 自动计算字号，并缩小以适应格子，默认使用常规字重。设为正数（如 20）可指定最大字号。

toml

[recursive_grid]
grid_cols = 3
grid_rows = 3
keys = "qweasdzxc"
max_depth = 10
min_size_width = 1
min_size_height = 1

[recursive_grid.lifecycle]
after_finish = "keep"
after_click = "keep"

max_depth 必须在 1..=20。layers 可以按深度覆盖网格形状；未写的字段继承基础设置：

toml

[recursive_grid]
layers = [
  { depth = 0, grid_cols = 2, grid_rows = 2, keys = "crtn" },
]

UI Hint

toml

[ui_hint]
strategy = "hybrid" # axtree、vision、contour 或 hybrid
hint_characters = "asdfghjkl"
scan_timeout_ms = 2500
scan_retry_count = 1
scan_retry_delay_ms = 200
visible_check_enabled = false
clickable_roles = ["button", "link", "checkbox", "text_field", "menu_item"]

[ui_hint.lifecycle]
after_finish = "normal"
after_click = "normal"

Windows 和 macOS 都支持 axtree、vision、contour 和 hybrid。默认 hybrid 并行合并辅助功能、OCR 与 contour 轮廓检测，流式显示并统一去重；OCR 找到文字后仍保留 contour 的独有目标。vision 使用 OCR 与 contour（macOS 还保留原生 Vision 矩形检测），contour 仅从截图识别按钮、图标与文字轮廓，不启动 OCR 或辅助功能树扫描。轮廓目标没有文字名称，不能按名称搜索。Windows 自动发现系统及微信 OCR，不随发行包分发微信组件；macOS 的视觉/轮廓捕获需要屏幕录制权限。

单独使用时设置 [ui_hint] 下的 strategy = "contour"，也支持应用覆盖。Contour 复用 [ui_hint.vision] 的 request_timeout_ms 和 rectangle_max_candidates（默认 10000）；其余置信度、尺寸和角色分类参数仅用于原有视觉识别。detect_text / detect_rectangles 仅在 vision 中控制来源，独立 contour 始终启用轮廓。hybrid 固定合并辅助功能、所有可用 OCR 和 contour；上述开关或旧的 100 候选配置不会关闭或缩减 hybrid 来源。合并去重后仍受扫描总上限 10000、范围和超时约束，512 内联容量不是标签上限。高分辨率截图只捕获一次，轮廓分析图最多 2,073,600 像素、最长边 2560，卷积按带重叠区的小块处理，跨块连接后再还原桌面坐标；细小目标可能因下采样丢失。clickable_roles 仅约束辅助功能语义角色。

Window 配置

第一次使用？先看 Window 操作指南，按场景练习并查阅默认键位。

五个顶层配置段分别为 [window]、[window_quick]、[window_editor]、[window_restore]、[window_tab]。它们都支持 bindings、inherits、app_configs、temporary_mode、temporary_mode_keys、number_timeout_ms、border_width、ui 和 lifecycle。默认仅继承 hotkeys，按住 Primary 临时使用 Normal。

参数	所属配置	默认值
`move_step` / `move_speed`	`window`	20 / 600
`resize_step` / `resize_speed`	`window`、`window_editor`，各自独立	20 / 500
`split_ratios`	`window_quick`	`["1/4", "1/3", "1/2", "2/3", "3/4"]`
`gap`	Quick、Editor、Restore，各自独立	0
`number_timeout_ms`	五个模式	250，允许 100–2000
`border_width`	五个模式	3
`lifecycle.after_finish`	Restore	`"window_editor"`

步长和间距为逻辑像素，速度为逻辑像素／秒；Windows 按目标屏幕 DPI 换算。编号和描边使用各模式的 ui，统一操作面板使用 [key_help] 字体和颜色。

以下是全局直达和独立参数示例；请把启动键合并到已有 [hotkeys]，避免重复表名：

toml

[hotkeys]
"alt+w" = "window"
"alt+a" = "window_quick"
"alt+e" = "window_editor"
"alt+r" = "window_restore"

[window_quick]
split_ratios = ["1/5", "2/5", "3/5", "4/5"]
gap = 12.0

[window_editor]
resize_step = 10.0
gap = 12.0

[window_restore.lifecycle]
after_finish = "window_editor"

window_delete 仅为 Restore 内切换恢复／删除状态的动作（默认 X），不再是模式；删除旧 [window_delete] 配置段，相关设置统一放在 [window_restore]。

只写参数时保留该模式的默认绑定。写入 [模式.bindings] 会整体替换该模式的默认表，应复制需要保留的键后修改；例如 Editor 的 q = "grid" 总是进入 Grid，与进入 Editor 的路径无关。应用覆盖如 [[window_editor.app_configs]]，共享键通过 inherits 明确继承。

迁移旧配置：把 window_layout、window_edit、window_saved_layouts 分别改为模式名 window_quick、window_editor、window_restore；把 window_cancel／window_exit 改为所需目的模式（如 window 或 idle）。删除 window.exit_mode、layout_keys、double_tap_ms；将旧 window.split_ratios 移至 Quick，window.gap 按用途移至 Quick／Editor／Restore。旧字段和动作会报错并提示迁移，不自动重写用户文件。

指针、滚动和主题

toml

[pointer]
initial_speed = 1000.0
max_speed = 2200.0
acceleration = 3000.0
smooth_acceleration = true
tap_distance = 2.5
slow_multiplier = 0.35
precision_multiplier = 0.12
fast_multiplier = 2.0

[scroll]
scroll_step = 50
scroll_step_half = 500
scroll_step_full = 1000000

[platform.macos.scroll]
invert_horizontal = false
invert_vertical = true

速度单位是像素/秒，加速度单位是像素/秒²，与显示器刷新率无关。smooth_acceleration = true 使用起步和收尾更柔和的 S 曲线；设为 false 使用线性加速。

主题颜色使用 #RRGGBBAA，可以为浅色和深色外观分别设置：

toml

[theme.dark]
surface = "#0A1338FF"
accent = "#6E82D6FF"
accent_alt = "#8FA2F0FF"
on_accent_alt = "#081022FF"
text = "#E8EEFFFF"

[mode_indicator.cursor]
left_pressed_color = "#00FF00FF"
middle_pressed_color = "#FF00FFFF"
right_pressed_color = "#00FFFFFF"

鼠标按钮通过 press 或 toggle 保持按下时，透明圆形指示器使用对应的 *_pressed_color：填充使用配置颜色 20% 的不透明度。

应用覆盖：`[[app_configs]]`

应用覆盖可以禁用或替换某些程序里的绑定：

toml

[[app_configs]]
bundle_id = "com.apple.Terminal"
bindings = { "primary+shift+e" = "none" }

[[normal.app_configs]]
bundle_id = "Figma"
bindings = { v = "none", "primary+f" = "grid" }

根级 [[app_configs]] 对所有 Mode 生效；[[normal.app_configs]] 只在 Normal 生效。匹配值可以是 macOS bundle id、Windows 可执行文件名、或窗口标题的子串。

插件设置

插件 Mode 使用命名空间：

toml

[plugin_modes."plugin:screen-selector".settings]
preserve = true

[plugin_modes."plugin:screen-selector"]
inherits = ["hotkeys", "normal"]

自带 Screen Selector 的 preserve = true 会在切屏时保留 Grid/Recursive Grid 的选择路径；设为 false 则从目标显示器重新开始。

运行时修改与调试

set_config 可以修改点号路径，并在解析、校验通过后原子写回配置：

toml

[normal.bindings]
"primary+1" = "set_config pointer.max_speed 800"
"primary+2" = "set_config theme.dark.accent \"#FF8800FF\""

无效修改不会替换当前有效配置。状态栏的 Reload Configuration 会重新加载配置。

toml

[debug]
enabled = true
keys = true
actions = true
modes = true
backend = true
pointer = false
motion = false
overlay = true
timers = true

建议只在排查问题时开启调试日志；日志会写入数据目录中的 keysteer.log。

实时按键提示

key_help 动词切换按键提示面板，Normal 默认绑定 "?" = "key_help"，targeting 模式按继承规则使用。? 按字面匹配操作系统产生的问号字符。进入 Idle 自动关闭。已有自定义绑定表需自行补入此绑定。

mouse_key_help 表示 Normal、Grid、Recursive Grid、UI Hint 的默认显示状态，默认 false；设为 true 则进入时显示。无论默认值如何，都能按 ? 切换。手动选择在这些模式间保持，退出到 Idle 后重新进入恢复默认值。旧 [key_help].enabled 已改名为 mouse_key_help。

Window 和 A/E/R/T 子模式的下方面板默认开启，可独立设置初始显示状态：

toml

[key_help]
mouse_key_help = false
window_key_help = false

这些模式默认绑定 "?" = "key_help"，默认关闭后仍可按 ? 显示或隐藏。手动切换状态在窗口子模式之间保持，退出后重新进入恢复配置默认值。此设置不隐藏窗口边框或编号，与 mouse_key_help 独立。已有自定义窗口绑定表需自行补入 "?" = "key_help"。

[key_help] 还支持 font_family、font_size、background_color、text_color、border_color、border_width、border_radius、padding_x、padding_y。空字体和未指定的背景/文字色跟随模式指示器与主题。颜色支持 #RRGGBBAA 或 { light = "#RRGGBBAA", dark = "#RRGGBBAA" }。标题大小、分列和居中自动适配。

在模拟器点击“编辑按键提示样式”，即可修改、预览并导出 TOML。

Window 的中央编号与分区编号使用 [window.ui].font_size，默认 28。分区编号位于窗口中心编号下方；帮助面板优先放在目标窗口内底部，不重复列出数字选窗键。

Quick 的比例尺按 split_ratios 显示原标识，可混用 "1/2"、"1/3"、0.3、0.45；需要保留尾零时写为字符串，如 "0.30"。Actions 下方的屏幕比例预览标注当前宽高，其他比例以细刻度显示；内部矩形实时表示布局。

窗口卡片引导线

共享配置适用于 Window 及相关子模式，包括标签避让后产生的引导线。关闭线条不影响避让。

toml

[window.card]
guide_line_enabled = true
guide_line_width = 3.0 # 0–32；0 也隐藏线条
# 默认继承卡片边框颜色；末两位是透明度，也支持浅深主题颜色。
# guide_line_color = "#6E82D680"

临时模式按键优先级

按住 temporary_mode_keys 时，按以下顺序解析（各层包含其继承绑定）：

临时模式的完整组合键。
当前模式的完整组合键。
去掉临时激活键后，临时模式的绑定。
去掉临时激活键后，当前模式的绑定或模式输入。

完整匹配优先于裸键：Window 中 Primary+S 可以执行 Normal 的屏幕切换；Grid 的 Primary+Q 仍可切换到 Normal。默认 Normal 的 Primary+F 会执行 UI Hint，优先于裸 F 的 Recursive Grid。

如果当前模式使用裸 Q 返回 Normal，可以为它声明穿透键：

toml

[grid]
temporary_mode = "normal"
temporary_mode_keys = ["primary"]
temporary_mode_passthrough_keys = ["q"]

[grid.bindings]
q = "normal"

穿透键匹配完整或去掉临时激活键后的输入，只跳过临时层，仍解析当前模式及其继承；不会向操作系统注入按键。默认 []，支持组合键、别名和左右修饰键，也适用于 Recursive Grid、UI Hint、Window 家族和插件模式。不对 idle 或退出动作做特殊处理。

Window 家族临时使用 Normal 时，激活键只负责启用临时层，不参与 Normal 的组合键；先保留 Window 显式完整组合键，再按去掉激活键后的输入查临时层、当前层。于是临时 S 可执行 Normal 的 screen next，临时 F 默认进入 Recursive Grid。固定 Window 面板不列出 Normal 的其他快捷键，Move 的 Other Actions 只补充 Grid/Recursive Grid 入口。

Normal 盲操定位

可选 [normal.targeting] 使用 method = "grid" | "recursive_grid"（默认 grid）和 reset_on = ["move", "click"]（可取子集或空列表）。缺省不启用、不导出配置段；布局引用对应顶层网格，输入冲突在计划编译时拒绝。完整行为、键位让出与示例见 Normal 盲操网格定位。

normal.targeting 可覆盖 grid_cols、grid_rows、keys、max_depth，未写的字段继承所选 method 的原配置。method = "recursive_grid" 另支持 min_size_width、min_size_height 和 layers；显式 layers 整组替换继承列表，layers = [] 清空。覆盖只影响 Normal，不改变独立网格模式，不接受 UI 字段。布局校验、键位冲突检测和控制器使用同一份合并结果，仅在加载配置时解析。完整注释示例见 keysteer.default.toml。

配置文件 ​

模式统计与快速切换 ​

配置文件位置 ​

最小配置 ​

配置结构 ​

按键和别名 ​

共享前缀的组合键 ​

按键写法 ​

鼠标侧键 ​

自定义别名 ​

绑定、数组和继承 ​

动作序列 ​

Normal 和定位 Mode ​

Normal ​

Grid ​

Recursive Grid ​

UI Hint ​

Window 配置 ​

指针、滚动和主题 ​

应用覆盖：[[app_configs]] ​

插件设置 ​

运行时修改与调试 ​

实时按键提示 ​

窗口卡片引导线 ​

临时模式按键优先级 ​

Normal 盲操定位 ​

配置文件

模式统计与快速切换

配置文件位置

最小配置

配置结构

按键和别名

共享前缀的组合键

按键写法

鼠标侧键

自定义别名

绑定、数组和继承

动作序列

Normal 和定位 Mode

Normal

Grid

Recursive Grid

UI Hint

Window 配置

指针、滚动和主题

应用覆盖：`[[app_configs]]`

插件设置

运行时修改与调试

实时按键提示

窗口卡片引导线

临时模式按键优先级

Normal 盲操定位