📦 OpenStream 详细部署教程

OpenStream 是一款专为开发者设计的 macOS 离线语音听写应用。它完全在本地运行，无需联网、无需订阅，只需按住快捷键说话，松开后语音文字便会自动输入到你当前光标所在的位置。它特别适合在编程、写文档时快速输入大段文字。

重要提示：本项目目前处于 Beta 测试阶段，可能有已知问题。部署前请确保满足所有要求。

⚙️ 部署前准备

OpenStream 的部署和使用完全依赖于从源码构建，请确保你的环境满足以下硬性要求：

  1. 硬件：搭载 Apple Silicon (M1/M2/M3/M4) 芯片的 Mac。
  2. 操作系统：macOS 14 (Sonoma) 或更高版本。
  3. 开发工具：
    • Node.js: 版本 22.12 或更高。建议通过 nvm 或官网安装。
    • Xcode 命令行工具：这是编译 Swift 辅助组件的必要工具。如果尚未安装，请在终端运行 xcode-select --install 进行安装。
  4. 网络：首次启动时需要下载约 470 MB 的转录模型文件。

🚀 从源码构建与运行

这是官方唯一支持的安装方式。

  1. 克隆仓库

    1
    2
    git clone https://github.com/Nabzx/openstream.git
    cd openstream

  2. 安装 Node.js 依赖
    项目使用 npm 管理依赖。

    1
    npm install

    注意：npm install 过程会自动构建项目所需的三个 Swift 辅助组件，因此第一次运行可能会比较慢，请耐心等待。

  3. 启动应用

    1
    npm start

    应用启动后，会自动下载语音转录模型（约 470 MB）。下载完成后，应用会出现在你的菜单栏中。

🔐 首次运行权限配置

macOS 出于安全考虑，会严格管控应用对麦克风、输入监听等敏感功能的访问。应用首次启动时，会引导你授予以下三项关键权限。如果遗漏，可随时运行 npm run doctor 进行检查。

1. 麦克风权限

  • 弹窗提示后，点击“好”或“允许”。
  • 如果拒绝，请前往 系统设置 > 隐私与安全性 > 麦克风，找到 OpenStream 并开启。

2. 输入监听权限 (Input Monitoring)

这是实现“在任何应用中打字”的核心权限。

  • 系统弹窗提示后，点击“打开系统设置”。
  • 在 系统设置 > 隐私与安全性 > 输入监控 中，点击 + 号，从你的应用程序文件夹（或构建目录）中手动添加 OpenStream.app，并确保开关已开启。
  • 重要：如果此权限未正确授予，热键将无法工作。

3. 辅助功能权限 (Accessibility)

此权限用于获取当前光标位置，确保文字准确输入。

  • 操作流程与输入监听类似，在 系统设置 > 隐私与安全性 > 辅助功能 中，添加并启用 OpenStream.app。

权限故障排除：

  • 权限不生效：由于应用是从源码构建的，每次重新构建或更换目录后，系统可能会将其视为“新”应用。请前往 系统设置 > 隐私与安全性，删除旧的 OpenStream 条目，然后重新添加新构建的应用。
  • 应用无反应：如果在授予权限后仍无反应，请完全退出并重新启动 OpenStream 应用。

🎤 使用与测试

  1. 启动应用：从终端用 npm start 启动，或双击构建出的 .app 文件（位于 release/ 目录下）。
  2. 放置光标：打开任意文本编辑器、IDE 或聊天窗口，将光标置于需要输入文字的位置。
  3. 开始听写：
    • 按下并按住全局快捷键（默认为 Fn 键，可在应用菜单栏中修改），此时对着麦克风说话。
    • 说完后，松开快捷键，识别出的文字会自动在光标处输入。
  4. 常用语音命令：可以尝试说“new paragraph”（新段落）或“paste”（粘贴），应用会智能处理，避免破坏代码或未发送消息的上下文。

🔧 开发与调试 (可选)

如果你希望修改代码或参与贡献，可以了解以下命令：

  • 开发模式：npm run dev (启动 Vite 渲染器和 Electron 的热重载)
  • 运行测试：npm test
  • 类型检查：npm run typecheck
  • 打包成 DMG 文件：npm run dist (生成的未签名安装包位于 release/ 目录)

❓ 常见问题

  • Q: 为什么没有提供下载好的 .dmg 安装包？
    • A: 虽然 Release 页面提供有未签名的 Beta 版 DMG，但 Gatekeeper 会拦截，且重新构建会重置权限。因此，从源码构建是目前最可靠且官方推荐的路径。
  • Q: 首次语音识别很慢？
    • A: 是的，首次下载模型后，第一次听写会稍慢，这是因为模型需要加载到内存中。后续使用会很快。
  • Q: 无法授予“输入监控”权限，列表里找不到 OpenStream？
    • A: 请点击权限设置窗格下方的 + 号，通过文件选择器手动导航到你的构建目录（如 openstream/release/build/），找到并选中 OpenStream.app 即可添加。
  • Q: 如何更新到新版本？
    • A: 进入项目目录，执行 git pull 拉取最新代码，然后重新运行 npm install 和 npm start 即可。注意，更新后可能需要重新配置系统权限。

更多架构设计、已知问题列表（如 v1.1 里程碑）和开发路线图，请查阅项目根目录下的 CONTEXT.md、ROADMAP.md 和 docs/ 文件夹。