okooooooo/hi-kid
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: simplify INSTALL.md with quick-start first

Browse Source 
- Lead with 'just open the app' as the recommended path
- Move manual steps into a collapsible details block
- Convert troubleshooting to a concise table
- Add Ollama download link in both EN and CN versions
This commit is contained in:
groovyquan committed 2026-04-22 22:49:05 +08:00
1 parent 91aed69e5c
commit 6be4b28bb8
2 files changed
+122 -218
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

INSTALL-cn.md
+61 -109
View File
@@ -2,134 +2,86 @@
# HiKid 安装指南
## 系统要求
- **macOS** 12.0+ (Apple Silicon / ARM64)
- **RAM**: 8GB+ (推荐 16GB)
- **存储**: ~2GB（含模型文件）
## 首次运行（重要）
由于 HiKid 未通过 Apple 官方签名，首次打开时 macOS 可能会阻止运行。
**解决方法**（任选一种）：
**方法 1：终端命令（推荐）**
```bash
xattr -cr /Applications/HiKid.app
```
**方法 2：手动允许**
1. 将 `HiKid.app` 拖入 Applications
2. **右键**点击应用图标，选择"打开"
3. 在弹出的对话框中点击"打开"
4. 如果仍被阻止，前往 **系统设置 > 隐私与安全性**，找到 HiKid 并点击"仍要打开"
**方法 3：按住 Control 键打开**
按住 `Control` 键，同时点击应用图标，选择"打开"
- **macOS** 12.0+ (Apple Silicon)
- **内存**: 8GB+（推荐 16GB）
- **存储**: ~2GB
---
## 安装步骤
## 快速开始（推荐）
### 1. 安装 SoX（音频工具）
直接打开 **HiKid.app**，它会自动检测缺少的依赖并引导你安装。二进制文件和模型也会自动下载。
> **首次运行？** 由于未通过 Apple 官方签名，macOS 可能会阻止运行。
> 在终端执行一条命令即可解决：
> ```bash
> xattr -cr /Applications/HiKid.app
> ```
---
## 备选：脚本安装
如果你想在启动前就把所有东西准备好：
```bash
brew install sox
cd /path/to/hi-kid
bash scripts/install-dependencies.sh
```
### 2. 安装 espeak-ng（TTS 依赖）
```bash
brew install espeak-ng
```
### 3. 安装 TTS / ASR 服务器二进制
```bash
mkdir -p ~/.config/hi-kid/bin && cd ~/.config/hi-kid
# TTS 服务器（macOS ARM64）
curl -LO https://github.com/second-state/kitten_tts_rs/releases/latest/download/kitten-tts-aarch64-macos.tar.gz
tar xzf kitten-tts-aarch64-macos.tar.gz
mv kitten-tts-aarch64-macos/kitten-tts-server bin/
chmod +x bin/kitten-tts-server
rm kitten-tts-aarch64-macos.tar.gz
rmdir kitten-tts-aarch64-macos
# ASR 服务器（macOS ARM64）
curl -sSf https://raw.githubusercontent.com/second-state/qwen3_asr_rs/main/install.sh | bash
mv qwen3_asr_rs/asr-server bin/
mv qwen3_asr_rs/mlx.metallib bin/
chmod +x bin/asr-server
```
### 4. 下载模型文件
```bash
cd ~/.config/hi-kid
# TTS 模型
curl -LO https://github.com/second-state/kitten_tts_rs/releases/latest/download/kitten-tts-models.tar.gz
tar xzf kitten-tts-models.tar.gz
rm kitten-tts-models.tar.gz
# 压缩包解压后是 models/kitten-tts-micro/，但程序期望的路径是 models/kitten/kitten-tts-micro/
mkdir -p models/kitten
mv models/kitten-tts-micro models/kitten/
# ASR 模型（已包含在 install.sh 安装目录中）
# install.sh 执行后模型位于 ./qwen3_asr_rs/Qwen3-ASR-0.6B/
mv qwen3_asr_rs models/
```
### 5. 运行 HiKid
将 `HiKid.app` 拖入 Applications 文件夹即可使用。
---
## 启动 LLM 后端
HiKid 默认连接本地的 Ollama 服务：
HiKid 默认连接本地 Ollama 服务。
还没有安装 Ollama？前往 [ollama.com](https://ollama.com/download) 下载。
安装后运行：
```bash
ollama run qwen3:0.6b
```
如需使用其他 LLM 后端，打开应用内的**设置**面板，直接在里面配置 AI 地址、API 密钥和模型名称即可，无需修改环境变量。
如需使用其他 LLM 后端，打开应用内的**设置**面板直接配置地址、API 密钥和模型名称即可。
---
## 手动安装
仅在需要完全控制文件位置时使用。
<details>
<summary>展开手动步骤</summary>
```bash
# 1. 系统依赖
brew install sox espeak-ng
# 2. 二进制与模型（具体 URL 参考 scripts/install-dependencies.sh）
# 或手动从 GitHub Releases 和 HuggingFace 下载
# 3. 期望的目录结构
~/.config/hi-kid/
bin/
kitten-tts-server
asr-server
mlx.metallib
models/
kitten/kitten-tts-micro/
qwen3_asr_rs/Qwen3-ASR-0.6B/
```
</details>
---
## 故障排查
### "Missing required audio tools: rec, sox, play"
SoX 未安装。运行：
```bash
brew install sox
```
### "espeak-ng not found" 或 TTS 服务器启动失败
espeak-ng 未安装。运行：
```bash
brew install espeak-ng
```
### "kitten-tts-server not found"
TTS 服务器二进制文件缺失。按上面第 3 步安装。
### "ASR model not found"
模型文件缺失。按上面第 4 步下载模型，或启动应用后使用内置下载功能。
### 麦克风无响应
前往 **系统设置 > 隐私与安全性 > 麦克风**，确保 HiKid 已授权。
| 问题 | 解决 |
| :--- | :--- |
| "Missing audio tools" | `brew install sox` |
| "espeak-ng not found" | `brew install espeak-ng` |
| 找不到 ASR / TTS 服务器 | 启动应用让它自动下载，或运行安装脚本 |
| "Ollama seems to be taking a nap" | 确保 Ollama 在运行：`ollama run qwen3:0.6b` |
| 麦克风无响应 | **系统设置 > 隐私与安全性 > 麦克风** — 开启 HiKid |
INSTALL.md
+61 -109
View File
@@ -1,135 +1,87 @@
**English** | [简体中文](INSTALL-cn.md)
# HiKid Installation Guide
# HiKid Installation
## System Requirements
- **macOS** 12.0+ (Apple Silicon / ARM64)
- **macOS** 12.0+ (Apple Silicon)
- **RAM**: 8GB+ (16GB recommended)
- **Storage**: ~2GB (including model files)
## First Launch (Important)
Since HiKid is not signed by Apple, macOS may block it on first open.
**Workarounds** (pick one):
**Method 1: Terminal command (recommended)**
```bash
xattr -cr /Applications/HiKid.app
```
**Method 2: Manually allow**
1. Drag `HiKid.app` into Applications
2. **Right-click** the app icon and choose "Open"
3. Click "Open" in the dialog that appears
4. If still blocked, go to **System Settings > Privacy & Security**, find HiKid, and click "Open Anyway"
**Method 3: Control-click to open**
Hold the `Control` key and click the app icon, then choose "Open"
- **Storage**: ~2GB
---
## Installation Steps
## Quick Start (Recommended)
### 1. Install SoX (audio tools)
Just open **HiKid.app**. It will detect anything missing and guide you through installing it. Binaries and models are downloaded automatically.
> **First launch?** macOS may block the app because it is not signed by Apple.
> Fix it with one terminal command:
> ```bash
> xattr -cr /Applications/HiKid.app
> ```
---
## Alternative: Script Install
If you prefer to have everything ready before launching:
```bash
brew install sox
cd /path/to/hi-kid
bash scripts/install-dependencies.sh
```
### 2. Install espeak-ng (TTS dependency)
```bash
brew install espeak-ng
```
### 3. Install TTS / ASR server binaries
```bash
mkdir -p ~/.config/hi-kid/bin && cd ~/.config/hi-kid
# TTS server (macOS ARM64)
curl -LO https://github.com/second-state/kitten_tts_rs/releases/latest/download/kitten-tts-aarch64-macos.tar.gz
tar xzf kitten-tts-aarch64-macos.tar.gz
mv kitten-tts-aarch64-macos/kitten-tts-server bin/
chmod +x bin/kitten-tts-server
rm kitten-tts-aarch64-macos.tar.gz
rmdir kitten-tts-aarch64-macos
# ASR server (macOS ARM64)
curl -sSf https://raw.githubusercontent.com/second-state/qwen3_asr_rs/main/install.sh | bash
mv qwen3_asr_rs/asr-server bin/
mv qwen3_asr_rs/mlx.metallib bin/
chmod +x bin/asr-server
```
### 4. Download model files
```bash
cd ~/.config/hi-kid
# TTS model
curl -LO https://github.com/second-state/kitten_tts_rs/releases/latest/download/kitten-tts-models.tar.gz
tar xzf kitten-tts-models.tar.gz
rm kitten-tts-models.tar.gz
# The archive extracts to models/kitten-tts-micro/, but the app expects models/kitten/kitten-tts-micro/
mkdir -p models/kitten
mv models/kitten-tts-micro models/kitten/
# ASR model (already included in the install.sh directory)
# After install.sh runs, models are at ./qwen3_asr_rs/Qwen3-ASR-0.6B/
mv qwen3_asr_rs models/
```
### 5. Run HiKid
Drag `HiKid.app` into your Applications folder and launch.
---
## Start the LLM Backend
HiKid connects to a local Ollama service by default:
HiKid connects to a local Ollama service by default.
Don't have Ollama yet? Download it at [ollama.com](https://ollama.com/download).
Once installed, run:
```bash
ollama run qwen3:0.6b
```
To use a different LLM backend, open **Settings** in the app and configure the AI endpoint, API key, and model name there — no environment variables needed.
To use a different backend, open **Settings** in the app and configure the endpoint, API key, and model name there.
---
## Manual Installation
Only if you want full control over where files go.
<details>
<summary>Expand manual steps</summary>
```bash
# 1. System dependencies
brew install sox espeak-ng
# 2. Binaries & models (see scripts/install-dependencies.sh for exact URLs)
# Or download manually from GitHub releases and HuggingFace
# 3. Expected layout
~/.config/hi-kid/
bin/
kitten-tts-server
asr-server
mlx.metallib
models/
kitten/kitten-tts-micro/
qwen3_asr_rs/Qwen3-ASR-0.6B/
```
</details>
---
## Troubleshooting
### "Missing required audio tools: rec, sox, play"
SoX is not installed. Run:
```bash
brew install sox
```
### "espeak-ng not found" or TTS server fails to start
espeak-ng is not installed. Run:
```bash
brew install espeak-ng
```
### "kitten-tts-server not found"
The TTS server binary is missing. Install it following Step 3 above.
### "ASR model not found"
Model files are missing. Download them following Step 4 above, or use the built-in download feature after launching the app.
### Microphone not responding
Go to **System Settings > Privacy & Security > Microphone** and make sure HiKid is authorized.
| Problem | Fix |
| :--- | :--- |
| "Missing audio tools" | `brew install sox` |
| "espeak-ng not found" | `brew install espeak-ng` |
| "ASR / TTS server not found" | Launch the app and let it auto-download, or run the install script |
| "Ollama seems to be taking a nap" | Make sure Ollama is running: `ollama run qwen3:0.6b` |
| Microphone not responding | **System Settings > Privacy & Security > Microphone** — enable HiKid |