用户指南

从首次启动到高级用法的渐进式指南。

从首次启动到高级用法的渐进式指南。请按顺序阅读各级别——每一级都建立在前一级的基础上。

第 1 级：快速入门

目标： 安装 闻字 并转录你的第一句话。

安装

方式 A — 下载发布版（最简单）：

1. 从 Releases 页面下载 WenZi.app。
2. 将其拖到 /Applications。
3. 双击启动。

首次启动： macOS 会阻止未签名的应用。前往 系统设置 → 隐私与安全性，找到 闻字 的阻止提示，点击 仍要打开。

方式 B — 从源码构建：

git clone https://github.com/Airead/WenZi
cd WenZi
uv sync
./scripts/build.sh        # 在 dist/ 目录构建 WenZi.app

方式 C — 从源码运行（开发者）：

git clone https://github.com/Airead/WenZi
cd WenZi
uv sync
uv run python -m wenzi

授予权限

首次启动时，macOS 会请求以下权限：

在 系统设置 → 隐私与安全性 中授予所有请求的权限。

首次启动：即刻就绪

默认 ASR 后端为 Apple 设备端语音识别 ——使用 macOS 内置的语音识别器，无需下载任何模型。授予权限后即可立即开始转录。

注意： 如果之后在设置中切换到 FunASR 或 MLX-Whisper，闻字 需要下载模型（根据模型不同，从 ~75 MB 到 ~1.6 GB 不等）。下载期间：

• 菜单栏图标会变为 下载图标（⬇），并显示百分比如 DL 45%
• 请等待下载完成 后再尝试转录
• 点击菜单栏 → 查看日志... 打开内置日志查看器，实时监控下载进度
• 加载完成后，图标恢复为 麦克风图标（🎙），状态显示 "Ready"

提示： 如果下载失败或中断，删除缓存目录（FunASR 为 ~/.cache/modelscope/，MLX-Whisper 为 ~/.cache/huggingface/）后重启 闻字 重试。

你的第一次转录

1. 在菜单栏找到 麦克风图标（🎙）——表示 闻字 已就绪。
2. 打开任意文本输入位置（备忘录、浏览器、编辑器、终端…）。
3. 按住 fn 键并说话。
4. 松开 fn — 转录的文本随即出现。

就是这样！你已完成基本工作流程。

了解菜单栏图标

菜单栏图标会随当前状态变化：

第 2 级：日常使用基础

目标： 了解两种输出模式和基本的菜单栏操作。

预览模式 vs 直接模式

闻字 有两种输出结果的方式：

切换方式：菜单栏 → 设置... → 通用标签 → 预览 复选框。

预览面板基础

启用预览后，录音结束会看到一个浮动面板：

• 确认（Enter）— 输入文本并关闭面板
• 复制到剪贴板（⌘+Enter）— 将文本复制到剪贴板而非输入
• 取消（Esc）— 丢弃文本
• 编辑 — 点击文本区域可在确认前修改

菜单栏概览

点击菜单栏中的 麦克风图标 查看菜单：

🎙
├── Ready                    （状态指示）
├── ─────────────────────
├── 增强剪贴板                AI 增强选中文本（Ctrl+Cmd+V）
├── 浏览历史...               搜索和浏览过去的转录记录
├── 设置...                   打开设置面板（4 个标签）
├── ─────────────────────
├── 查看日志...               打开日志查看器
├── 使用统计                  查看使用统计
├── 关于 闻字            版本信息
└── 退出

所有模型选择、AI 增强配置和快捷键管理都通过 设置 面板完成——而非直接在菜单中操作。

录音反馈

按住 fn 时，会显示一个带音频电平条的浮动指示器，表示正在录音。开始和结束时会播放提示音（可在设置 → 通用中配置）。

当 ASR 后端支持流式识别时（如 Apple Speech），录音指示器下方会出现一个 实时转录悬浮窗，在你说话的同时实时显示部分转录文本。无需等待录音结束即可获得即时的视觉反馈。

录音控制

按住录音快捷键的同时，可以按其他键控制录音过程：

重新录音键和取消录音键可在设置 → 通用中自定义（或通过配置：feedback.restart_key 和 feedback.cancel_key）。

第 3 级：选择合适的语音识别后端

目标： 为你的需求选择最佳语音引擎。

后端对比

如何切换

打开 设置... → STT 标签。你会看到：

• 本地 区域：所有可用的本地 ASR 预设的单选按钮（FunASR、MLX-Whisper 各版本、Apple Speech）
• 远程 区域：你配置的云端 ASR 供应商

点击单选按钮即可切换。模型将开始加载（如果尚未缓存则会先下载）。

首次下载提醒： 首次切换到新的 MLX-Whisper 模型时需要下载。观察菜单栏图标的 DL X% 进度。模型大小从 ~75 MB（tiny）到 ~1.6 GB（large-v3-turbo）不等。

推荐方案

• 零配置，任意语言 → Apple Speech（默认 — 无需下载，支持实时流式识别）
• 仅中文 → FunASR（中文最佳准确度，完全离线）
• 英文或多语言，高准确度 → MLX-Whisper small 或 large-v3-turbo
• 最佳准确度，不介意延迟 → 通过 Groq 使用 Whisper API（有免费额度）

第 4 级：AI 增强

目标： 使用 LLM 校对、翻译或重新排版转录文本。

AI 增强是 可选的 ——默认关闭。启用后，转录文本会在输出前发送给 LLM 进行后处理。

步骤 1：配置 LLM 供应商

你需要一个 LLM 后端。两个简单的选项：

方式 A — 使用 Ollama 本地运行（免费、私密）：

1. 安装 Ollama 并运行 ollama pull qwen2.5:7b
2. 完成——闻字 的默认配置已指向 Ollama

方式 B — 云端 API（如 DeepSeek、OpenAI）：

1. 打开 设置... → LLM 标签 → 添加供应商...
2. 填写供应商信息：

name: deepseek
base_url: https://api.deepseek.com/v1
api_key: sk-your-key
models:
  deepseek-chat

3. 点击 验证 → 保存

步骤 2：选择增强模式

打开 设置... → AI 标签。选择一个模式：

步骤 3：试试看

1. 确保已配置 LLM 供应商并选择了模式。
2. 按住 fn，说话，松开。
3. 结果现在会经过 LLM 处理后再显示。

提示： 从"纠错润色"开始——这是最通用实用的模式。

第 5 级：预览高级功能

目标： 掌握预览面板的编辑和切换功能。

启用预览模式并开启 AI 增强后，预览面板将成为一个强大的编辑器。

快速模式切换

按 ⌘1 到 ⌘9 可即时切换增强模式并重新处理相同的音频：

• ⌘1 = 列表中的第一个模式（如纠错润色）
• ⌘2 = 第二个模式（如翻译为英文）
• ⌘3 = 第三个模式（如命令行大神）
• …以此类推，包括自定义模式

结果缓存

在预览面板中切换模式时，闻字 会 缓存 已完成的结果。切回之前使用过的模式会即时显示缓存结果（标记 [cached]）——无需再次调用 API。

录制新音频时缓存会被清除。

预览历史

闻字 会在内存中保留最近 10 条 预览结果（应用重启后清除）。这让你可以回溯之前的转录而无需重新录音。

• 历史下拉菜单： 点击预览面板工具栏中的时钟图标，打开显示最近预览记录的下拉菜单。选择一条即可重新加载到面板中。
• 快速召回： 随时按 fn+Z（即使不在预览面板中），即可取消当前录音并立即打开最近一次的预览结果。

Web 预览面板

预览面板默认使用基于 WKWebView（HTML/CSS/JS）的现代界面，提供精美的外观和暗色模式支持。你可以在设置 → 通用 → Web 预览 开关中切换 Web 版和原生 AppKit 版预览。

其他预览功能

第 6 级：直接模式与流式输出

目标： 使用 闻字 实现快速、解放双手的输入，配合实时 AI 反馈。

启用直接模式

关闭预览：设置... → 通用标签 → 取消勾选 预览。

现在松开快捷键后，文本会直接输入到当前应用——无面板、无需确认。

实时流式语音识别

当使用支持流式识别的 ASR 后端（目前为 Apple Speech）时，闻字 会在录音过程中显示 实时转录悬浮窗。你说话的同时即可看到文字逐步出现，在松开快捷键之前就能获得即时反馈。

此功能在预览和直接模式下均可使用。在直接模式下尤为实用，因为你可以边看转录结果边决定是保留还是取消。

AI 流式悬浮窗

在直接模式下，录音结束后会出现一个 流式悬浮窗 展示处理流程：

1. 转录阶段 — 悬浮窗首先显示 ASR 结果（如果后端支持流式则显示部分文本）
2. 增强阶段（如果启用了 AI 增强）— LLM 实时处理文本，token 逐个生成

悬浮窗中的操作：

• 按 Esc 取消转录/增强并丢弃结果
• 悬浮窗显示 token 计数和处理状态
• 处理完成后，最终文本会自动输入

何时使用直接模式

• 追求速度的聊天应用
• 终端/命令行输入
• 任何你信任 AI 输出且无需预览的场景

第 7 级：剪贴板增强

目标： 在任何应用中 AI 增强任意文本，不仅限于语音转录。

工作原理

1. 在任意应用中 选中 文本。
2. 按 Ctrl+Cmd+V（默认快捷键）。
3. 闻字 复制选中内容，使用当前增强模式发送给 LLM，然后输出结果。

也可以从菜单栏触发：点击 增强剪贴板。

使用场景

• 选中草稿 → 使用纠错润色模式增强
• 选中中文文本 → 翻译为英文
• 选中任务描述 → 转换为 Shell 命令

输出行为

• 预览开启： 结果显示在预览面板中供审查
• 预览关闭： 结果通过剪贴板替换

自定义快捷键

编辑 ~/.config/WenZi/config.json：

{
  "clipboard_enhance": {
    "hotkey": "ctrl+cmd+v"
  }
}

快捷键格式为 修饰键+修饰键+键。详见第 12 级的格式说明和示例。

第 8 级：自定义增强模式

目标： 创建自己的 AI 模式和链式流水线。

创建自定义模式

通过设置（简单）：

1. 打开 设置... → AI 标签 → 添加模式...
2. 编辑模板，点击 保存，输入模式 ID。

通过文件（灵活）：

在 ~/.config/WenZi/enhance_modes/ 中创建 .md 文件：

---
label: 正式邮件
order: 60
---
You are a professional email writing assistant.
Rewrite the user's input as a formal, polished email body.
Use appropriate greetings and closings if context suggests an email.
Maintain the original intent and key information.
Output only the email text without any explanation.

文件名（不含 .md）即为模式 ID。重启后生效。

创建链式模式

链式模式按顺序运行多个步骤：

---
label: 润色+翻译EN
order: 25
steps: proofread, translate_en
---
先校对润色文本，再翻译为英文。
（此正文仅作说明——每个步骤使用各自的 prompt。）

编写好 Prompt 的技巧

• 明确说明要做什么以及 不要 做什么
• 以 "Output only the processed text without any explanation" 结尾
• order 值留出间隔（10、20、30…），方便日后在中间插入新模式

更多现成模板请参阅 增强模式示例，涵盖邮件、会议纪要、翻译、开发工具等场景。

第 9 级：多供应商配置

目标： 配置多个 ASR 和 LLM 供应商并在它们之间切换。

为什么需要多个供应商？

• 简单任务用快速的本地模型（Ollama），复杂任务用云端 API
• 某个供应商宕机时有备用方案
• 比较不同模型的结果

通过设置添加供应商

LLM 供应商： 设置 → LLM 标签 → 添加供应商...

ASR 供应商： 设置 → STT 标签 → 添加供应商...

两者使用相同的对话框格式：

name: provider-name
base_url: https://api.example.com/v1
api_key: your-key
models:
  model-1
  model-2

运行时切换

在 设置 面板中，所有已配置的模型显示为单选按钮。点击即可切换——无需重启。

在预览面板中切换

你也可以直接在预览面板的下拉菜单中切换 LLM 和 STT 模型，方便对同一段音频比较不同模型的结果。

详细示例请参阅 供应商与模型配置指南，涵盖 Ollama、OpenAI、DeepSeek、Groq、OpenRouter、通义千问等。

第 10 级：词汇表与对话历史

目标： 教 闻字 学习你的专属术语，并在多轮对话中保持话题上下文。

词汇检索

问题： ASR 经常错误识别专有名词、技术术语和人名（例如"萍萍"→"平平"）。

解决方案： 闻字 从你的纠正历史中构建个人词汇表，并用于改善未来的识别结果。

如何构建词汇表

1. 使用预览模式配合 AI 增强 ——当 AI 识别错误时编辑结果。
2. 每次编辑都会记录到 ~/.config/WenZi/conversation_history.jsonl，并标记 user_corrected。
3. 自动构建（默认）：每积累 10 次纠正后，词汇表会在后台自动重建。
4. 手动构建： 设置 → AI 标签 → 构建词汇表...

启用词汇表

设置 → AI 标签 → 开启 词汇表（N）。括号中的数字表示已索引的条目数量。

启用后，相关词汇条目会通过嵌入相似度检索并注入 LLM prompt，帮助其纠正领域特定术语。

对话历史

问题： 每次转录都是独立的——LLM 不知道你刚才说了什么。

解决方案： 闻字 将最近确认的输出注入 AI prompt，让 LLM 了解当前话题。

启用

设置 → AI 标签 → 开启 对话历史。

工作原理

• 仅使用 预览确认 的记录（确保质量）
• 最近的条目以箭头标记的高效格式呈现纠正内容
• LLM 利用此上下文保持一致性（例如始终使用正确的人名拼写）

浏览历史

菜单栏 → 浏览历史... 打开功能完备的历史浏览器，支持：

• 文本搜索 — 在所有转录文本字段中搜索
• 标签过滤 — 点击标签胶囊按增强模式（纠错润色、翻译等）、STT 模型、LLM 模型或是否有纠正进行过滤
• 时间范围过滤 — 按今天、最近 7 天、最近 30 天或全部时间过滤
• 记录删除 — 选中一条记录并点击删除将其移除
• 编辑保存 — 修改任何记录的最终文本并保存更改
• 归档记录 — 勾选"已归档"开关以包含月度归档中的记录

自动轮转与归档

当对话历史超过 20,000 条记录 时，闻字 会自动将较旧的记录归档到 ~/.config/WenZi/conversation_history_archives/YYYY-MM.jsonl 月度文件中。主历史文件保留最近 20,000 条记录以确保快速访问，归档记录仍可通过历史浏览器搜索和查看。

技术细节请参阅 对话历史增强。

第 11 级：启动器

目标： 使用内置启动器快速访问应用、文件、剪贴板、书签和代码片段。

启动器是内置于 闻字 脚本系统中的键盘驱动搜索面板。它的使用方式类似 Alfred 或 Raycast——按下快捷键，输入关键词搜索，按回车执行操作。

启用启动器

1. 启用脚本系统：设置... → 通用标签 → 脚本 开关
2. 编辑 ~/.config/WenZi/config.json，设置：

{
  "scripting": {
    "chooser": {
      "enabled": true,
      "hotkey": "cmd+space"
    }
  }
}

3. 重启 闻字。

基本使用

1. 按 Cmd+Space（或你配置的快捷键）打开启动器。
2. 输入关键词搜索应用——结果即时显示。
3. 按 Enter 打开选中的应用，或按 ⌘+Enter 在 Finder 中显示。
4. 按 Esc 关闭。

前缀搜索

输入前缀加空格可搜索特定数据源：

键盘快捷键

通过脚本扩展

可以通过脚本向启动器添加自定义数据源。详见 脚本系统文档 中的 wz.chooser.source API。

第 12 级：精细调优与故障排除

目标： 优化你的配置并解决常见问题。

设置面板

菜单栏 → 设置... 打开一个包含 4 个标签的面板：

设置面板会 记住上次激活的标签，跨会话保持。底部的工具栏按钮可快速访问 显示配置、编辑配置 和 重新加载配置。

自定义配置目录

在通用标签中，你可以设置 自定义配置目录 将 闻字 配置文件存储在自选位置（例如同步文件夹）。更改目录后，闻字 会提示你重启以使更改生效。

脚本开关

通用标签中包含 脚本 开关，用于启用或禁用脚本/插件系统。启用后，闻字 会从配置的脚本目录加载并执行 Python 脚本。详见 脚本系统文档。

快捷键配置

闻字 支持灵活的快捷键配置。录音快捷键在 设置 面板（通用标签）中配置，剪贴板增强快捷键在配置文件中设置。

快捷键格式

快捷键使用 修饰键+修饰键+键 的格式，其中：

• 修饰键： cmd（或 command）、ctrl、alt（或 option）、shift
• 常规键： a–z、0–9
• 特殊键： fn、f1–f12、esc、space
• 右侧修饰键： cmd_r、ctrl_r、alt_r、shift_r

示例

配置文件示例

{
  "hotkeys": {
    "fn": true,
    "f5": true
  },
  "clipboard_enhance": {
    "hotkey": "shift+cmd+space"
  }
}

可以同时启用多个录音快捷键，只需在 hotkeys 映射中添加值为 true 的条目。设为 false 可禁用快捷键而不删除它。

配置文件

默认位置：~/.config/WenZi/config.json

配置目录可通过设置 → 通用 → 配置目录更改为自定义路径（存储在 macOS 偏好设置中，不受配置文件变更影响）。

你只需包含想要修改的字段——其余全部使用默认值。编辑后，点击设置工具栏中的 重新加载配置 即可应用，无需重启。

完整选项请参阅 配置参考。

日志

日志保存在 ~/Library/Logs/WenZi/wenzi.log（5 MB 轮转，3 个备份）。

查看日志（推荐）： 菜单栏 → 查看日志... 打开内置日志查看器——这是检查日志、监控模型下载/加载进度和实时诊断问题的最便捷方式。

日志文件也可在上述路径中直接访问，如果你更喜欢使用外部编辑器。

使用统计

菜单栏 → 使用统计 打开交互式统计仪表盘，包含：

• 摘要卡片 — 总转录次数（含今日数量）、总 token 消耗量（含缓存输入 token 明细）、接受率、总录音时长
• 交互式图表（基于 Chart.js）支持选择时间范围（7/14/30 天）：
• 每日转录 — 堆叠柱状图，展示每天直接模式与预览模式的使用量
• 用户操作 — 堆叠柱状图，展示每天的接受/修改/取消操作
• Token 使用 — 堆叠柱状图，展示每天的提示/补全/缓存 token 用量
• 增强模式 — 堆叠柱状图，展示每天各增强模式的使用量

常见问题

文本无法输入到应用中

• 检查系统设置中的 辅助功能 权限
• 尝试在配置中切换输出方式："output": {"method": "clipboard"}

模型下载太慢

• 菜单栏显示 DL X% 表示正在下载——首次切换到某个模型时这是正常的
• FunASR：~500 MB，MLX-Whisper large-v3-turbo：~1.6 GB
• 查看日志查看器了解详细进度
• 如果部分下载，删除缓存目录（FunASR 为 ~/.cache/modelscope/，MLX-Whisper 为 ~/.cache/huggingface/）并重启

LLM 增强超时

• 增加超时时间：编辑 config.json → ai_enhance.timeout（默认：30 秒）
• 检查 LLM 供应商是否可达
• 如果使用 Ollama，确保已运行：ollama serve

预览面板不出现

• 确认 预览 已在设置 → 通用中启用
• 尝试点击菜单栏图标将应用带到前台

开发环境下通知不工作

• 通过 uv run 运行且未打包时这是预期行为
• 通知在打包的 .app 版本中可正常工作

键盘快捷键一览

注意： 重新录音键（Cmd）和取消录音键（Space）可在设置 → 通用或配置中自定义（feedback.restart_key 和 feedback.cancel_key）。可选值：cmd、ctrl、alt、shift、space、esc。

接下来？

你现在已了解 闻字 的全部功能。以下是一些充分利用它的建议：

• 为你的工作流创建模式 — 会议纪要、代码评审评论、Slack 消息
• 构建链式模式 — 校对 → 翻译，或总结 → 格式化
• 积累词汇表 — 纠正越多，越智能
• 尝试不同模型 — 比较 Groq 的速度、本地 Ollama 的隐私性、OpenAI 的准确度
• 编写脚本 — 使用 Python 脚本扩展 闻字 的自定义快捷键功能（详见 脚本系统文档）
• 浏览 增强模式示例 获取灵感

各功能的技术细节请参阅 文档索引。