内容
🎙️🤖
Yappr 是一款高性能、**100% 本地化** 的语音助手 CLI 和 SDK。它结合了最先进的 TTS/STT 模型与本地 LLMs（通过 Ollama）和可扩展的工具（通过 MCP）。
设计用于在 Apple Silicon（M 系列）上高效运行，Yappr 确保您的语音数据和对话永远不会离开您的硬件。
## ✨ 功能特点
- **Kokoro TTS:** 使用 8200 万参数的 Kokoro 模型，实现接近人类水平的文本转语音。
- **Whisper STT:** 通过 `faster-whisper` 实现快速、准确的本地语音转文本。
- **Ollama 集成:** 与 `qwen2.5`、`mistral` 或 `llama3` 等本地 LLMs 无缝聊天。
- **MCP（模型上下文协议）:** 从 `~/.config/yappr/mcp.json` 或 `~/.cursor/mcp.json` 自动发现工具（可通过 `$YAPPR_MCP_CONFIG` 或在设置中覆盖）。您的语音助手可以搜索文件、检查 GitHub、使用 Figma 等。
- **语音模式:** 实时语音转语音对话循环。
## 🏗️ 架构
Yappr 使用混合架构以实现最大性能：
- **CLI/SDK（Bun + TypeScript）:** 处理编排、MCP 工具执行和用户界面。
- **推理服务器（Python + FastAPI）:** 封装了用于高速本地推理的重型 ML 模型（Kokoro 和 Whisper）。
### 仓库布局
Bun 工作区：
- `apps/cli/` — Ink + React TUI 和一次性 CLI 命令。
- `apps/desktop/` — Electrobun 桌面应用程序（React + Tailwind + Vite + shadcn/prompt-kit）。聊天优先的界面，带有侧边栏对话列表、流式 Ollama 聊天、每消息 TTS、作曲家麦克风 STT、语音/服务器设置表。
- `packages/sdk/` — `@yappr/sdk` — TTS/STT 客户端、MCP 管理器、MCP 路径级联、OpenAPI 类型。
- `packages — `@yappr/lib` — 共享实用程序（`/`ResultAsync`，未声明容器）。
- `packages/db/` —appr/db` — `bun:sqlite` + Drizzle 持久性，由 CLI 和桌面应用程序共享（`~/.yapappr.db`）；首选项、对话、消息和 zod RPC 合同。
-/` — FastAPI 推理 🚀 入门指南 前置条件
- ** `curl -fsSLbun.sh/install | bash`
- **uv:** `curl -LsSf https://astral.sh/uv/install.sh | sh`（Python- **Python 3.11+**（uv 可以为您安装，如果缺少）
- **系统依赖：**
```bash
brew install sox ffmpeg espeak-ng ollama
```
### 安装
```bash
# 克隆仓库
git clone https://github.com/alanrsoares/yappr.git
cd yappr
# 运行统一设置脚本
./setup.sh
```
设置脚本使用 Bun 安装 JS 依赖项，并使用 `uv sync` 安装 Python 依赖项（基于锁定文件，快速）。
### 手动安装
如果您想手动配置：
```bash
bun install
cd python && uv sync --extra dev
```
## 📖 使用方法
### 1. 启动推理服务器
服务器必须在单独的终端中运行，以处理 TTS 和 STT 请求。
```bash
bun run serve
```
_(首次运行时，它将下载 Kokoro 和 Whisper 模型，总约 400MB)。_
### 2. 交互式 TUI（推荐）
启动完整的交互式终端界面。从这里，您可以访问聊天、语音模式、设置和 MCP 状态。
```bash
bun run tui
```
首次启动时，TUI 会运行**辅助设置向导**，检查系统工具（`uv`、`ffmpeg`、`espeak-ng`），如果缺少 `python/.venv`，则运行 `uv sync --extra dev`，验证推理服务器，并允许您选择默认语音和 LLM 提供商。主菜单在完成设置向导后显示绿色 ✓；您可以随时从那里重新运行。
### 3. 快速 CLI 命令
Yappr 还支持从 shell 直接执行一次性命令：
#### 文本转语音
```bash
bun run speak "Hello, I am speaking from your terminal." --voice af_sky --speed 1.1
```
#### 文本聊天
```bash
bun run chat "What is the capital of France?" --model qwen2.5:14b
```
#### 列出语音
```bash
bun run voices
```
### 4. 桌面版（实验性）
桌面应用程序在原生窗口中为您提供相同的 Ollama 聊天 + 语音循环 — 侧边栏对话列表、每消息语音、麦克风输入作曲家听写和与 CLI 共享的持久化设置（通过 `~/.yappr/yappr.db`）。首先启动 Python 服务器（`bun run serve`），然后：
```bash
bun run desktop
```
仍在开发中：从应用程序内部启动推理服务器和打包构建路径解析 PoC。有关状态，请参见 `docs/PRODUCT_ROADMAP.md`。
## 🛠️ 配置
Yappr 通过此级联自动发现 MCP 服务器：
1. `$YAPPR_MCP_CONFIG` 环境变量（显式覆盖）
2. `~/.config/yappr/mcp.json`（中立默认）
3. `~/.cursor/mcp.json`（Cursor 预设 — Cursor 用户的零配置）
您还可以在 **设置 → MCP 配置路径** 中设置显式路径。使用支持工具调用的模型（如 `qwen2.5`）时，您可以要求 Yappr 使用这些工具执行操作。
## 🔒 隐私
所有处理均为本地化。
- **无** 云 API。
- **无** 数据收集。
- **无** 订阅费用。
- 只有您和您的芯片。
## 📜 许可证
MIT
