# 安装 vtype

## 系统要求

- **macOS 14（Sonoma）或更新版本**
- **Apple Silicon Mac（M1 及以上）** — 0.1.96+ 不再支持 Intel Mac
- 约 1.2 GB 可用磁盘（app ~41 MB + ASR 模型 234 MB + LLM 模型 ~870 MB）
- 一次性网络（下载 app + 模型）。之后默认全本地运行，**音频不离开你的设备**。

## 下载

- **官网**：<https://vtype.app/>
- DMG（OSS 直链）：<https://vtype-static-cn.oss-cn-beijing.aliyuncs.com/downloads/vtype-pure-0.1.104-mac-arm64.dmg>
- 自动更新清单：<https://vtype.app/releases/latest.json>

## 安装

1. 双击 `.dmg` 挂载
2. 把 `vtype.app` 拖到 `/Applications`
3. 弹出 DMG，从启动台或 `/Applications` 启动 vtype

## 首次启动

vtype 已 **Apple 公证**（Developer ID 签名 + notarized），双击直接打开，不会有 Gatekeeper 警告，**无需任何终端命令或「仍要打开」操作**。

## 首次设置（应用引导）

启动后自动弹出 Onboarding 窗口：

1. **授权麦克风 + 辅助功能** —— 点「打开系统设置」直达对应面板，给 vtype 打勾
2. **下载本地语音模型** —— 点「下载 234 MB」，从阿里云 OSS 拉，~30 秒（取决于网速）
3. **设置热键 + 试录** —— 默认 右 ⌘（Right Command），可以改成其他键

引导窗口右下角「开始使用」按钮在所有步骤就绪后会变绿色提示，点了关闭窗口正式开始用。

## 测试一下能不能用

1. 打开任何输入框（Notes / Safari 地址栏 / 微信 / 邮件…）
2. 按一下 **右 ⌘**（Right Command，或你改过的热键）
3. 屏幕底部出现胶囊「正在录音」
4. 对着麦克风说一句话
5. 再按一下 右 ⌘ 停止
6. ~200 ms 后转写文字直接出现在你打开的输入框里

如果出现错误胶囊「本地模型未下载」，回到设置 → 听写 → 语音识别模型 → 点「下载」。

## 路由与服务

vtype 默认配置（0.1.100+ pure 版本）：

- **ASR**：本机推理（SenseVoice Small），完全离线
- **LLM**：本机推理（Qwen 2.5 1.5B Instruct, MLX 4-bit），完全离线
- **路由**：固定本地 MLX —— 音频和文本都不离开你的设备
- **更新**：在菜单栏或设置里点「检查更新」

如果想配置不同的本地模型或更换 LLM backend：设置 → 模型。

## 常见问题

**Q：每次重新安装 vtype 都要重新授权辅助功能？**  
A：0.1.104 起 vtype 用稳定的 Developer ID 签名，正式发布版之间二进制 cdhash 不再乱变 → macOS 视为同一应用 → 更新后权限通常保留。若偶尔仍要求重新授权，在「系统设置 → 隐私与安全性 → 辅助功能」里手动重新打勾即可。

**Q：菜单栏图标消失了？**  
A：vtype 是 `LSUIElement = true` 的菜单栏 app，不显示在 Dock。检查屏幕顶部菜单栏右上角应该有 vtype 的小图标。如果没有，再启动一次。

**Q：本地模型下载卡住 / 失败？**  
A：检查能否访问 `https://vtype-static-cn.oss-cn-beijing.aliyuncs.com/models/sense-voice-zh-en-ja-ko-yue-2024-07-17/model.int8.onnx`（应该返回 ~240 MB）。0.1.93 起加了断点续传，断了重新点「下载」即可。0.1.100 起模型从家宽 NAS 迁到了阿里云 OSS，全国速度都快。

**Q：识别结果被「过度清洗」了，我说的话被删了？**  
A：0.1.88 之后加了短句跳过 LLM + 触发词检测，应该好多了。如果还遇到，把「清洗强度」从「标准」调到「轻度」或「仅转写」。

## 卸载

如果不想用了：

1. 退出 vtype（菜单栏图标 → 退出）
2. 把 `/Applications/vtype.app` 拖到废纸篓
3. 删除配置和模型：`rm -rf ~/Library/Application\ Support/vtype/`
4. 撤销系统权限：系统设置 → 隐私与安全性 → 把麦克风、辅助功能里的 vtype 删除
