Speech To Markdown 使用教程：Mac 安装、语音转写与 Markdown 整理

Speech To Markdown 适合把口述想法整理成可继续编辑的 Markdown。真正需要检查的是两件事：语音有没有听对，以及整理后的文档有没有改变原意。本文以一段项目讨论为例，给出从安装到保存的完整检查流程。

更新：2026-09-20。依据项目文档整理，未在本机安装实测；文中的口述与 Markdown 为教学样例，封面为原创流程示意图。

一、先确认你使用的版本

项目 README分别介绍 macOS 与 iOS 两条路线。Mac 版使用 whisper.cpp 转写，并可连接本地兼容 OpenAI 接口的模型服务；iPhone 版依赖受支持系统和设备上的 Apple Intelligence。两者的安装条件不能混用。

Mac：项目标明 macOS 13 或更新版本。下文采用源码安装，需要 Homebrew 和完整 Xcode。
iPhone：项目要求 iOS 26 及支持 Apple Intelligence 的设备，并启用该能力。请通过 README 中的应用入口核对当前兼容性，不要在手机上执行 Mac 终端命令。
Windows：本教程不把该项目当作 Windows 安装包介绍。需要本地模型服务，可另看本站的 Windows/Ollama 教程。

先安装官方 Homebrew 与完整 Xcode，打开 Xcode 完成首次初始化。只有 Command Line Tools 不满足项目构建条件。项目的 Makefile会检查并安装缺少的相关依赖；执行前可自行阅读文件。

git clone https://github.com/xajik/voice-to-md.git
cd voice-to-md
make install

该流程涉及 xcodegen、whisper-cpp、ffmpeg，完成构建后将应用安装到 Applications。若命令报错，先在仓库目录执行 make check，按缺失项处理；不要反复执行安装而忽略第一条错误。若提示 Xcode 路径或首次初始化问题，先完成 Xcode 设置再重试。

启动应用，按系统提示授予录音所需的麦克风权限；使用全局输入时，按项目说明设置辅助功能权限。
打开设置，下载 Whisper 模型。首次可按项目建议从 Base 开始，以短录音确认链路，再根据语言和效果调整。
如需 Mac 上的 AI 整理，先启动本地模型服务并加载模型。把兼容接口地址与模型名称填入应用设置，名称应与服务实际提供的一致。
项目列出的地址示例包括 Ollama 的 http://127.0.0.1:11434/v1 和 LM Studio 的 http://127.0.0.1:1234/v1。应匹配你实际启用的服务，不要把两个地址混填。

“兼容 OpenAI 接口”是接口格式说明，不代表必须连接 OpenAI 云端。选择远程服务时，应重新确认音频或文本会发送到哪里。Mac 与 iPhone 的能力边界以各自版本说明为准。上述配置来源为官方项目说明。

先新建空白文档，用清晰语速口述以下练习材料。不要第一次就录半小时会议。

今天讨论网站文章搜索。已经确认保留搜索关键词。
负责人还没有确定。下周是否上线，要等测试完成再决定。
请按背景、已确认事项、待办和待确认问题整理，不能补写人名和日期。

先检查原始转写：有没有把“还没有确定”漏成“确定”，有没有误识别产品名或时间。修正转写后再进行整理，避免让后续模型在错误事实之上润色。

项目的三种模式用途不同：Format主要整理文档结构；Edit按口述指令修改；Append追加内容，并仅带入有限的末尾上下文。长文续写时不能假定它总能看到整份文档。

下面是人工编写的预期结构示例，不是软件实测输出。内容可以换一种表达，但“未定”不能被变成“已定”。

## 背景
讨论网站文章搜索体验。

## 已确认事项
- 搜索时保留关键词。

## 待办
- 完成相关测试。

## 待确认问题
- 负责人尚未确定。
- 下周是否上线，等待测试结果后决定。

再练习一次 Edit：“把待办改成复选框，不新增负责人。”随后用 Append 补充一句：“还要检查翻页后条件是否保留。”核对原有结论没有消失，再保存为 .md，用另一款文本编辑器打开，检查标题、换行和中文编码。

录不到声音：先看系统麦克风权限和输入设备，再用十秒录音验证。蓝牙耳机切换后也要重新核对输入来源。

有转写却不能整理：转写与模型整理是两个环节。检查本地服务是否启动、地址是否带正确的 /v1、模型是否已加载以及名称是否一致。

文本出现在错误窗口：全局听写会面向当前焦点输入。首次测试把光标放在空白笔记中，不放在终端、聊天发送框或重要表单里。

整理后过度补充：保留原始转写，在指令中明确“缺失信息写待确认，不推测”。人名、金额、日期与承诺必须逐项复核。

长录音效果不稳定：拆为有主题的短段，每段先校对再合并。记录误识别词表，比反复要求“更准确”更便于复现问题。

一段短录音能正确转写，整理后保留事实与不确定性，保存的 Markdown 能重新打开，就完成了第一轮验收。随后再尝试真实会议材料，并依据数据敏感性选择合适的处理服务。

本地服务配置可接着阅读 DeepSeek 与 Ollama 本地部署教程；把整理后的需求交给编程工具，可参考 Cursor 小任务修改与验收教程。