企业官网建设流程全解析

• 桌面应用
• AI 应用
• 插件系统

本篇技术指南围绕 Wox 的"AI 命令"与"快捷键查询（Query Hotkey）"组合，讲解如何实现「在任意应用中选中文本 → 按下快捷键 → AI 静默翻译 → 结果自动粘贴回原选区」的完整工作流。读完本文，你将掌握 AI 命令默认动作（运行/运行并粘贴）的配置语义、静默执行预设的正确用法，以及{wox:selected_text}查询变量的底层捕获原理，可复用到语法修正、语气调整、摘要等各类文本改写场景。

AI 命令在启动器之外的使用方式

AI 命令本身可以在启动器里使用：输入ai <command> <输入>即可触发命令，在 Wox 的结果区展示 AI 流式返回的答案。但如果只停留在启动器里，它仍然是一次"先唤起启动器 → 再手动搬运文本"的操作。

把 AI 命令和快捷键查询组合起来后，场景就发生了质变：在任意应用里选中文本，按一个快捷键，让 AI 翻译，最后由 Wox 把最终结果直接粘贴回原来的选区。整个过程不再需要 Wox 窗口参与确认，更接近一个纯粹的日常文本处理工具。

整套配置的关键点是：给 AI 命令配置明确的默认动作。默认动作决定了命令被触发后 Wox 如何处理 AI 的最终答案——是停留在结果区展示、以浮层展示，还是直接替换原文本。

第一步：配置带默认动作的翻译 AI 命令

在 AI 命令插件（系统内置插件，触发关键词为ai）的设置里，新增或编辑一个翻译命令，按下面的示例值填写：

命令字段的完整含义

从源码中的commandSetting结构可以看到，AI 命令实际持久化的字段比界面上看到的更多：wox.core/plugin/system/ai_command.go 定义了name、command、model、thinkingMode、prompt、defaultAction、vision七个字段。结合GetMetadata中的表格列定义（ai_command.go），各字段说明如下：

• 名称（name）：命令的人类可读名称，必填，会显示在结果标题与浮层标题中；
• 命令（command）：触发命令的关键词，必填，例如translate，用于ai translate <输入>这样的查询；
• 模型（model）：选择使用哪个 AI 模型，必填，存储的是序列化后的模型配置（AIModel()负责反序列化）；
• 思考模式（thinkingMode）：provider_default/thinking/non_thinking三选一，未设置时回退为provider_default（NormalizedThinkingMode处理，见 ai_command.go）；
• 提示词（prompt）：必填，支持%s或{wox:input_text}占位符注入输入文本；
• 视觉（vision）：是否面向图片输入的命令；
• 默认动作（defaultAction）：命令被触发后的默认行为，取值为run/run_and_show/run_and_paste之一。

默认动作的三种取值

源码中明确定义了三个动作常量（ai_command.go）：

NormalizedDefaultAction（ai_command.go）还有一个向后兼容逻辑：旧版本保存的命令没有defaultAction字段，此时会回退到run，保证既有命令维持原有的"在 Wox 中展示结果"的安全行为，不会因为新字段的引入而突然变成自动粘贴。

提示词的渲染规则

renderAICommandPrompt（ai_command.go）按以下优先级渲染提示词：

1. 如果提示词包含{wox:input_text}，直接替换为输入文本；
2. 否则如果包含%s，用fmt.Sprintf格式化；
3. 两者都不包含时，提示词原样发送。

因此文档示例里的Translate the following text to Chinese. Return only the translated text: %s会被替换成...: <选中文本>。此外提示词还支持用{wox:new_ai_conversation}分隔符构造多轮对话（见buildAICommandConversations，ai_command.go），奇数段为 user 消息、偶数段为 assistant 消息。

第二步：用「静默执行」预设创建快捷键查询

接着在快捷键设置中新增一个快捷键查询，选择静默执行预设，并把它绑定到刚才的翻译命令：

静默执行预设做了什么

快捷键查询在设置中的字段定义见 wox.core/ui/launcher/hotkey_settings.go，包含Name、Hotkey、Query、Position、HideQueryBox、HideToolbar、Width、MaxResultCount、IsSilentExecution、Disabled等列。

预设机制在 wox.core/ui/launcher/form_table.go 中定义为四种：normal（常规）、web-panel（网页面板）、silent（静默）、custom（自定义）。选择静默执行时，applyQueryHotkeyPreset（form_table.go）会做两件事：

• 把IsSilentExecution置为true（即静默执行开关）；
• 清空被该预设隐藏的其他显示字段。

因此大多数情况下，选择静默执行预设后只需要填写快捷键和查询两项，不必逐个调整显示参数。

这里有一个容易混淆的点，原文档特意强调：静默执行这个预设本身不包含隐藏的粘贴语义。它只是让 Wox 在执行查询时隐藏启动器界面、不打扰用户；在这个配置里，静默执行只是"运行 AI 命令的默认动作"的触发方式，而粘贴行为来自你显式设置的默认动作运行并粘贴。两者是独立的概念：静默执行控制 UI 是否出现，运行并粘贴控制结果如何处理。

{wox:selected_text}查询变量

查询字符串ai translate {wox:selected_text}中的{wox:selected_text}是 Wox 的查询变量之一，定义于 wox.core/plugin/query_variables.go。同类变量还包括：

• {wox:clipboard_text}：剪贴板文本
• {wox:selected_file}：选中的文件
• {wox:active_browser_url}：当前浏览器地址
• {wox:file_explorer_path}：文件管理器路径

resolveTextQueryVariables（query_variables.go）实现了这些变量的捕获：只在查询模板引用到对应变量时才去读取，并且在 Wox 激活前完成——因为选区检索可能触发模拟复制（Copy），所以实现里刻意先读剪贴板再读选区，保证时序正确。捕获发生在源应用仍持有焦点时，这正是"粘贴回原应用"能够成立的先决条件。

完整流程：从选中文本到替换完成

配置完成后，实际运行时的完整流程是：

1. 在其他应用里选中文本；
2. 按下快捷键查询；
3. Wox 把选中文本发送给 AI 命令（{wox:selected_text}在 Wox 打开前已被替换为真实选区）；
4. Wox 在鼠标附近显示一个很轻的思考提示；
5. AI 返回最终答案后，Wox 用翻译结果替换原来的选中文本。

源码视角：运行并粘贴动作的完整链路

在 AI 命令插件中，buildAICommandActions（ai_command.go）为每个命令构造动作列表，其中run_and_paste分支（ai_command.go）的实现清晰地展示了"不粘贴半成品"的保证：

1. 等待最终答案：final := <-c.startAICommandStream(...)，在ChatStreamStatusFinished事件到达之前，finalCh不会收到结果（见 ai_command.go），因此流式过程中的中间文本永远不会进入剪贴板；
2. 流式启动后显示轻量浮层：通过onStreamingStarted回调在鼠标位置附近弹出"思考中"提示（showAICommandLoadingOverlay，ai_command.go），浮层使用textoverlay原生组件，偏移 18px、最小宽度 128px，靠近触发位置，暗示隐藏的 AI 动作正在运行；
3. 校验最终结果：出错或答案为空时，通过通知（notifyAICommandActionError）告知用户，不会执行粘贴；
4. 先关闭浮层再激活目标窗口：注释明确说明必须先关掉进度浮层，避免模拟粘贴时浮层悬浮在目标应用之上；
5. 写入剪贴板并模拟粘贴：调用pasteTextToActiveWindow（wox.core/plugin/system/util.go）：先clipboard.WriteText(text)写入最终答案，然后window.ActivateWindowByPid激活 Wox 打开前记录的活动窗口，等待 150ms 让窗口就绪，最后keyboard.SimulatePaste()模拟系统粘贴。

注意第 5 步依赖的"Wox 打开前的活动窗口"信息并非凭空可得：AI 命令插件的元数据声明了requireActiveWindowName/requireActiveWindowPid/requireActiveWindowIcon三个 QueryEnv 参数（ai_command.go），保证静默模式下也能拿到正确的目标窗口身份。

视觉命令与粘贴动作的边界

还有一个细节：allowRunAndPaste := !command.Vision（ai_command.go）。当命令启用了视觉（vision）字段时，运行并粘贴动作不会被加入动作列表，因为图片类命令的输出不适合直接替换选区文本；此时默认动作会退化为run。

静默执行与「运行并粘贴」的分工边界

综合前文，可以把两个核心概念的关系总结为一张对照表：

当两者组合时：快捷键触发的静默查询执行 AI 命令的默认动作，而这个默认动作被你显式设置成了运行并粘贴，于是形成"无确认窗口 + 直接替换原文"的完整静默翻译体验。原文档有一句非常准确的总结：在这个配置里，静默执行只是运行 AI 命令的默认动作——理解这一点，就不会在排查问题时把粘贴行为误归因于静默执行开关。

同一模式的其他应用场景

这套「快捷键查询 + 静默执行 + 运行并粘贴」的组合不限于翻译，凡是"选中文本 → AI 改写 → 替换原文"的文本处理都能复用：

• 语法修正：提示词要求"只返回修正后的文本"；
• 语气调整：改为正式 / 口语化 / 简洁风格；
• 摘要：把长段落压缩为要点；
• 格式清理：去重空行、统一标点、转 Markdown 等。

设计上的唯一分界线是：如果你希望先检查结果再决定是否采用，就把默认动作设为运行（结果留在启动器内，可手动复制）；只有当这个命令足够适合直接替换选中文本时，再使用运行并粘贴。因为运行并粘贴是不可撤销的即时替换，提示词里"Return only the translated text"这类约束非常重要——任何多余的说明性文字都会一并粘贴进原文。

仓库中还提供了演示视频 screenshots/ai_command_run_paste_query_hotkey.mp4 与命令模板界面截图 screenshots/ai_command_templates.png，可以直观对照本文的配置步骤；本主题的原始文档位于 www/docs/zh/blog/did-you-know-ai-command-silent-translation-query-hotkey.md，相关实现可继续深入阅读 wox.core/plugin/system/ai_command.go 与 wox.core/plugin/system/util.go。

• 桌面应用
• AI 应用
• 插件系统