Rill¶
Rill 是一款本地优先的 macOS 语音输入与记录应用。按住 Fn 说话，松开后把文字 输入当前应用；也可以保存文本、图片和文件记录，通过工作流整理、复制或朗读。
- 本地语音识别：默认 Qwen3-ASR 0.6B，可选 1.7B；准备好模型后可离线转写。
- 可选智能整理与语音助手：连接你配置的 LLM Provider，整理转写或回答问题。
- 记录与记录集：按用途组织内容，手动投递到目标应用；剪贴板采集默认关闭。
- TOML 工作流：作为语音输入等能力的可复用配置，使用外部编辑器修改并自动重新加载。
安装¶
系统要求¶
- Apple Silicon Mac，macOS 14.0 或更高版本。
- 首次准备语音模型需要联网。0.6B 模型约 1.01 GB，1.7B 模型约 2.46 GB， 还需为下载缓存和可选语音合成模型预留空间。
- 运行打包后的 App 无需安装 Python、uv 或其他开发工具。
当前仍处于开发阶段，Releases 尚无正式安装包。开发者可按 CONTRIBUTING.md 准备构建环境， 使用本机可用的 Apple Development 签名身份构建并安装：
SIGN_IDENTITY="Apple Development" bash scripts/release.sh --install
本地开发签名不等于 Developer ID 公证。正式安装包上线后，从 Releases 下载 对应版本，将 Rill 放入“应用程序”；如 macOS 拒绝打开，先核对来源和版本， 不要通过关闭 Gatekeeper 绕过检查。
首次使用¶
- 打开 Rill，按“活动”页的语音设置清单授权麦克风和输入监控。 需要向其他应用直接输入文字时，再授权辅助功能。
- 在设置中准备并启用本地语音模型。等待模型准备完成后即可开始听写。
- 将光标放到目标应用的输入框，按住 Fn 说话，松开结束。
- 在“活动”页查看结果和运行状态。没有成功输入时，可从已保存的记录中取回文字。
使用¶
语音输入与文字整理¶
| 工作流 | 操作与结果 | 默认状态 |
|---|---|---|
| 语音识别 | 按住 Fn，说完松开；识别、应用词汇规则、保存记录并输入文字 | 启用 |
| 智能整理 | 按住 Fn；在识别后调用 LLM 整理文字，再保存并输入 | 停用 |
| 语音助手 | 说出“Hey Rill”和请求；生成回答、保存记录并朗读 | 停用 |
语音识别与智能整理共用 Fn，启用其中一个会停用另一个。使用智能整理或语音助手前， 先在设置中的 LLM Provider 配置服务地址、模型和 API Key，并确认云端处理授权。 支持 DeepSeek 及兼容 OpenAI Responses API 的服务；API Key 保存在 macOS Keychain。
智能整理用于修正明显错字、标点和段落，不会把转写中的请求当作问题回答。 可恢复的服务失败会保留整理前文字并提示；取消、隐私阻止或凭据错误会停止投递。 语音助手需要单独开启唤醒监听，开启后会持续使用本地麦克风；关闭监听即可停止。 朗读优先使用可用的本地 Qwen TTS，必要时回退到系统语音。
个人词库支持识别热词和转写后的确定性替换。可按应用、语言或记录集限定作用域， 从历史中的识别结果提出纠正，确认后再加入词库。
记录与剪贴板¶
在设置或菜单栏主动开启剪贴板采集后，Rill 才会记录允许采集的文本、图片和文件引用。 它不会接管系统的 ⌘C / ⌘V，也不会补录关闭期间的剪贴板变化。
选中记录后，点击快捷面板的“预览”（也可右键选择）查看内容；打开后会随所选记录更新。 主窗口的记录详情使用相同预览。图片可“查看大图”；文件显示缩略图、类型和大小，点击 文件旁的预览按钮使用 macOS Quick Look，多文件记录可在预览窗口中前后切换。 文件引用显示原路径当前的内容，不保存文件副本；文件移动、删除或无法读取时会明确提示。
快捷面板先查找正文、文件名、来源和标签中的关键词；没有命中时，再尝试英文缩写、
少量拼写错误，以及中文全拼或至少三个字母的拼音首字母（如 jiantieban / jtb）。
已有关键词结果保持原顺序。网址、绝对路径和带长数字的单个编号不做模糊纠错；
该搜索在本机运行，无需下载模型。
想用一句话描述要找的内容时，可点“按含义补充”。首次使用需明确下载约 1.2 GB 的本地搜索模型； 查询和记录不会上传。语义候选单独列出，不改变已有关键词结果和选中项；来源、类型和置顶筛选仍有效。 首次准备记录较慢，后续查询可复用内存中的向量。长记录仅覆盖部分内容，图片不参与语义检索； 候选顺序不是正确性概率，粘贴前仍需核对正文。
有 TypeSafe API Key 时，可点“用 Jev 比较…”：从当前关键词和语义候选中交错选取最多 10 条，
先预览查询及将要发送的文字片段／文件名，再主动提交给 jev-1.13.0 付费评分。
Key 只保留在本次 App 会话的内存中，退出即清除。评分不自动运行、不改变本地次序；
选择结果只定位记录，粘贴仍由你确认。图片和引用文件的正文不发送，敏感来源会阻止请求。
每条候选最多发送 1,800 UTF-8 字节，界面标明截短；失败不自动重试，已发送的请求仍可能计费。
“所有记录”展示仍在保留期内的记录。收件箱、语音输入及自建记录集用于组织内容， 同一条记录可以属于多个记录集。常用预设如下：
| 预设 | 选取与使用方式 |
|---|---|
| Stack | 最新优先，成功投递后移出该记录集 |
| Queue | 最旧优先，成功投递后移出该记录集 |
| List | 手动选取，投递后保留 |
选取顺序与消费策略可以分别调整。移出记录集只移除成员关系；明确删除记录才会 删除其内容及全部成员关系。投递失败或取消时，不会把对应成员标记为已消费。 使用图片或文件时，目标应用必须支持对应内容；文件引用还需要原文件可访问。
工作流¶
工作流页用于启用、停用、新建、导入和打开文件。Rill 不提供内置文本编辑器， 文件和提示词由你选择的外部编辑器维护。
- 文件位置：
$XDG_CONFIG_HOME/rill/workflows/*.toml，默认~/.config/rill/workflows/。 - 配置备份：
$XDG_STATE_HOME/rill/workflows/，默认~/.local/state/rill/workflows/；可用外部编辑器恢复备份。 - 新建和导入的工作流默认停用。先检查步骤和输出目标，再主动启用。
- 保存有效文件后，下次运行使用新配置；正在运行的任务保持原配置。 无效文件会显示错误并阻止对应工作流运行。
- 音频工作流从绑定的触发器或运行按钮启动；文本工作流可通过“运行剪贴板文本” 显式读取当前剪贴板，仍需通过相应隐私检查。
可以从 App 模板开始，也可以创建一个简单的文本工作流。下面的例子整理空白、
保存记录并复制结果；另存多份时，用 uuidgen 为每份生成不同的 id。
schema_version = 2
id = "54B31E01-96AC-4A0F-BB82-0A8CB12DD629"
name = "整理并复制"
enabled = false
[trigger]
kind = "manual"
[input]
kind = "text"
[[process]]
id = "clean"
kind = "normalize-whitespace"
[output]
strategy = "immediate"
[[output.actions]]
id = "save"
kind = "record.store"
[[output.actions]]
id = "copy"
kind = "system-clipboard.copy"
步骤按文件顺序运行。输出可以组合保存记录、复制、输入到应用或朗读；把保存放在 投递之前，后续输出失败时仍能取回结果。工作流也支持条件分支；完整字段和执行契约 见 TOML 规范，可参考条件示例。
活动与排查¶
运行卡片的“执行详情与诊断”分别展示录音、语音转文字和润色 API 的实测耗时，
并关联本次运行的诊断。工作流步骤可通过 record_duration 选择是否计时；
没有测量的数据会显示“未记录”，不会用区间估算。
“活动”页集中显示录音状态、最近结果和运行历史；运行详情中可查看识别与 LLM
处理耗时。⌘F 可搜索页面、工作流、历史和设置。
- Fn 无反应：检查输入监控权限、当前启用的 Fn 工作流和语音设置清单。
- 模型未就绪：先联网完成模型准备，确认所选模型已启用。
- 无法输入到目标应用：检查辅助功能权限，并在开始前将光标放入输入框。
- 云端步骤失败：检查服务地址、模型、API Key 和云端授权，在设置中验证配置。
- 需要更多诊断信息时，打开“设置 → 高级 → 诊断”。报告问题前移除私人文本和凭据。
隐私与数据¶
本地识别不上传录音。云端整理或回答会把文字发送到你配置的服务；可选的屏幕上下文 和长期记忆默认关闭，开启并授权后，会向该服务发送相应截图、摘要或已授权的历史材料。 请按服务提供方的条款决定是否启用这些功能。
记录正文、运行历史和长期记忆加密保存，密钥由 Keychain 管理。剪贴板和运行历史默认保留 30 天，可在设置中调整和分类清理；失败录音恢复默认关闭，开启后最多保留 24 小时。 长期记忆独立于历史留存，清空历史不会同时删除已形成的记忆，需要在记忆管理中处理。
设置中可暂停采集、配置敏感应用、关闭正文预览、撤销云端授权及清除凭据。 完整的数据目的地、保留规则与限制见 PRIVACY.md，App 设置也可查看同一份说明。
升级与卸载¶
Rill 尚未提供自动更新。新版本发布后，先退出 App，再安装受信任的新版本。 升级前保留需要的数据；已经迁移的数据不保证能被旧版 App 读取，降级前应阅读该版本说明。
卸载前可在设置中分别清理历史、长期记忆和凭据，再退出并移除 App。 仅删除 App 不会清除全部用户数据、模型缓存或 Keychain 条目。工作流和备份位于上文的 XDG 目录；其他数据位置与清理边界见 PRIVACY.md。
参与开发与反馈¶
- 普通问题和功能建议：GitHub Issues。
- 安全问题：遵循 SECURITY.md，不要公开漏洞细节或私人数据。
- 开发环境、检查命令、提交规则与技术文档入口：CONTRIBUTING.md。
许可证¶
Copyright (C) 2026 Zhan Rongrui and contributors.
Rill 的原创代码和文档采用 GNU Affero General Public License v3.0 only
（SPDX：AGPL-3.0-only），完整条款见 LICENSE。本程序不提供任何担保，
包括适销性或特定用途适用性的默示担保，详见许可证。
第三方代码和模型继续适用各自条款，分别见 THIRD_PARTY_NOTICES.md 与 LOCAL_MODEL_NOTICES.md。它们不因 Rill 的许可选择而重新授权。