Skip to content

usage-guide.md

Latest commit

 

History

History
147 lines (105 loc) · 10.3 KB

usage-guide.md

File metadata and controls

147 lines (105 loc) · 10.3 KB
Raw

XiLuoLin 使用与验证指南

本文档面向用户、贡献者和维护者，用于完成本地配置、核心流程验证和问题定位。它不是比赛演示脚本。

验证目标

确认 XiLuoLin 能够完成“语音输入 → ASR 转写 → 按人格整理 → 输出文本 → 保存历史 → 更新统计”的桌面工作流，并明确外部服务、系统权限和当前实现边界。

前置准备

  • Node.js 20+
  • pnpm 10+
  • Rust stable 工具链
  • Windows：Microsoft Visual Studio C++ Build Tools、WebView2 Runtime
  • macOS：macOS 13+；当前稳定版安装包仅支持 Apple Silicon，且未经 Apple 公证
  • Windows：Windows 10/11 x64；当前稳定版安装包未签名，可能触发 SmartScreen
  • 可用的麦克风及系统麦克风权限
  • 至少一组受支持的 ASR Provider 凭据，或已下载的本地 Whisper 模型
  • 如需人格整理，至少一组受支持的文本 Provider 凭据

开发日志中的识别结果

默认日志只记录 ASR / 文本整理所用服务商、模型、结果字符数和是否发生降级，不输出用户口述正文。需要排查识别或整理内容时，可在开发环境显式开启全文日志：

XILUOLIN_LOG_TEXT=1 pnpm tauri dev

全文日志可能包含口述内容、姓名或业务信息，只应在本机临时使用，提交日志前必须脱敏。

启动项目

pnpm install --frozen-lockfile
pnpm check
pnpm tauri dev

如果只修改前端，可先运行 pnpm build；涉及 Rust、录音、快捷键、凭据或输出能力时，应运行完整的 pnpm check，并执行桌面端手动验证。

首次配置

  1. 打开“设置”页，在“语音输入就绪检查”中确认权限；macOS 用户可在此请求麦克风和辅助功能权限。
  2. 配置 ASR 和文本处理 Provider 的 API Key、Base URL 与模型名。
  3. 选择麦克风设备。
  4. 配置长按模式和切换模式快捷键；macOS 可在授予辅助功能权限后显式开启“按住 Fn 录音”。
  5. 选择输出方式，并确认是否自动保存历史。
  6. 首次使用默认启用不可修改的“通用人格”；如需结构化输出，可在“人格”页切换默认人格或创建自定义人格。
  7. 在“热词”页的添加框中按“一行一个热词”粘贴项目名、人名、技术词等易误识别内容并保存；空行、首尾空格会被忽略，重复词只保留一条，已保存的热词不会回填到添加框。

Provider 配置说明

应用分别配置语音识别和文本整理服务：

  • ASR 支持智谱、OpenAI-compatible、本地 Whisper、Qwen-Audio 3.0 和 Qwen3-ASR；文本支持智谱、OpenAI-compatible 与千问。
  • ASR 和文本各自选择一个 primary，并可追加最多两个有序 fallback。每项只尝试一次；文本链全部失败时返回 ASR 原文。
  • 使用智谱 audio/transcriptions 时，应用录音会在 25 秒提示并于 28 秒自动停止；超过 30 秒的外部音频会在请求前被拒绝。
  • 启用热词会同时影响 ASR 和文本整理：智谱与 Qwen-Audio 接收前 100 个稳定去重原生热词，Qwen-Audio 权重为 5；Qwen3-ASR 使用 system glossary；OpenAI 和本地 Whisper 使用软提示。
  • Qwen-Audio 可填写最多 4 个语言提示；Qwen3-ASR 可选择单语言并开关 ITN（默认关闭）；千问文本固定关闭 thinking。
  • 每类服务都需要选择 Provider，并填写对应的 API Key、Base URL 和模型名。
  • 千问 Base URL 可填写公共地域或 Workspace 专属地域地址，应用会自动追加能力端点。Key、Workspace 与地域必须匹配；接口和可用模型以阿里云 Qwen-Audio 文档、Qwen-ASR 文档及文本生成文档为准。
  • 当 primary 为本地 Whisper 时，加入云端 fallback 会显示隐私确认；拒绝后不会保存该 fallback。
  • 设置页会在开关、下拉和快捷键变更后立即保存；文本和 API Key 停止输入约 600ms 后自动保存，失焦会立即提交。不要直接编辑应用数据文件或把密钥写入仓库。
  • 看到“已保存”后先用短语音验证 ASR，再验证文本整理和跨应用输出，便于定位失败环节。

API Key 通过操作系统凭据库保存；普通配置保存在本地应用数据中。音频和文本会发送到用户主动配置的 Provider。提交 Issue 或日志时，请勿附带密钥、完整录音路径或私人文本。更多恢复步骤见 troubleshooting.md。

核心流程验证

1. 人格与热词

  • 确认“通用人格”默认启用、不可编辑或删除；点击其他人格卡片即可切换默认人格。删除当前默认的自定义人格并确认后，应用会先切换为“通用人格”再删除。
  • 创建一个自定义人格，保存后重新启动应用，确认配置仍然存在。
  • 在热词添加框中每行输入一个热词并保存，确认新词出现在管理列表；已存在词条不会重复添加，新词默认启用。单条编辑可修改分类和启用状态，确认它同时参与 ASR 偏置和后续文本整理；验证结束后停用临时测试热词。

2. 语音输入

  1. 在任意文本编辑器或聊天输入框中放置光标。
  2. 使用设置页显示的全局快捷键开始录音。
  3. 口述一段 5 至 15 秒的内容，建议包含已配置热词。
  4. 停止录音并等待 ASR 与文本整理完成。
  5. 确认结果按照当前人格完成断句和整理；通用人格应保持自然口语化，并移除整段末尾的单个句号。

macOS 开启“按住 Fn 录音”后，按下 Fn 立即暂存录音，松开进入识别；不足 300 毫秒的短按会取消并删除暂存录音。Fn 与 Command、Option、Shift、Control 组合时不会作为独立语音手势处理。该开关默认关闭，不会修改 macOS 的 AppleFnUsageType 等系统偏好；权限不足时仍可使用原有组合快捷键。

需要严格保留口述原文时，将默认人格切换为“原文听写”。该模式跳过文本模型，只清理首尾和异常空白，因此会直接暴露 ASR 的原始选择，也仍然受全局热词影响；历史记录会明确标记为 verbatim。

推荐测试文本：

帮我把今天关于 XiLuoLin 快捷键可靠性和本地隐私保护的讨论整理成三项开发任务，并为每项补充验收标准。

录音状态条

通过全局快捷键录音时，鼠标所在显示器顶部居中位置会显示不抢焦点、鼠标穿透的半透明状态条。状态条包含录音时长，并依次展示以下阶段：

  • 正在录音：时长持续增长；显式下载并启用实验性实时模型后，单行字幕始终跟随最新文字尾部。
  • 正在识别、正在整理、正在输入：停止时冻结最后一版预览，右侧展示当前后台阶段。
  • 输入完成：显示绿色“已输入”，约 1.2 秒后自动消失。
  • 处理失败：展示错误约 4 秒；自动输入失败时，完整结果和恢复操作仍在独立结果窗口中保留。

状态条在 Windows 和 macOS 上使用透明窗口；其音频条是处理状态动画，不代表麦克风的实时音量。macOS 透明窗口依赖 Tauri 私有 API，因此当前安装包不以 Mac App Store 分发为目标。

3. 输出、历史与统计

  • 确认结果能够恢复录音开始时的目标应用窗口并写入；精确窗口不可用时可降级为原应用，自动输入失败时复制到剪贴板并打开可保留结果的失败窗口。
  • 失败结果窗口只在自动输入链路失败时出现，展示完整只读文本、失败原因和复制状态；正常成功输入不需要额外确认。
  • 确认历史记录包含原始文本、整理结果、人格、录音时长和实际成功的 Provider/模型；fallback 成功时不能仍显示 primary。
  • 确认统计卡片在成功处理后更新。
  • 重启应用，确认本地历史和设置仍可读取。

错误场景

至少验证以下场景并确认界面给出可理解、可恢复的提示：

  • 未配置或配置了无效 API Key。
  • 麦克风权限被拒绝、尚未请求或设备不可用。
  • macOS 辅助功能权限被拒绝，此时自动粘贴应降级到剪贴板。
  • 自动输入失败时，确认结果窗口仍可打开；“再次复制”后切回目标应用使用 Command+V。
  • Provider 超时、限流或返回非预期响应。
  • 全局快捷键冲突。
  • 目标应用不支持键盘注入，需要降级到剪贴板。
  • 停止录音后等待 10 秒，确认 macOS 控制中心不再将 XiLuoLin 列为当前麦克风使用者；“最近使用过”的提示不作为泄漏判据。

当前实现边界

  • 项目当前聚焦短语音到可用文本的桌面输入工作流，不是系统输入法内核。
  • 实时预览是默认关闭的实验性功能。在“设置 → 模型配置 → 录音实时预览”中显式下载并启用 Zipformer 候选模型后，录音悬浮窗会边说边显示增量文字。这里的文字仅用于预览；停止后仍由录音开始时固定的最终 ASR Provider 路由处理完整 WAV。
  • 模型未下载、损坏、处理过慢或运行失败时，悬浮窗退化为阶段提示，最终识别、历史保存和文字投递不受影响。
  • 当前候选模型的训练数据许可链、真实录音质量、模型下载体验、Windows 原生打包和目标设备稳定性尚未完成验证，不应视为生产可用能力。
  • 首页不提供录音 / 上传入口；全局快捷键是主要输入入口，上传处理命令仅作为兼容能力保留。
  • 真实 Provider、麦克风和跨应用输出必须在目标操作系统上手动验证；安装说明见 macos-build.md 和 windows-build.md。
  • 长音频转写、会议纪要和多人协作不是当前核心范围，但可通过 Issue 提交具体使用场景和设计建议。
  • 质量基准、模型替换门槛和 100 次连续录音验收见 asr-quality-evaluation.md。

反馈问题

提交 Issue 前请提供：

  • 操作系统、版本与 CPU 架构
  • XiLuoLin 版本或 commit
  • 可复现步骤、预期行为和实际行为
  • 已运行的检查命令
  • 已脱敏的错误信息或日志

安全问题不要公开提交，请按照 SECURITY.md 的方式报告。