内容
align="center">
img src="assets/banner.png" alt="ASCII Avatar — Tmux 机中的幽灵" width="100%">
</p>
```
███████╗ ██████╗██╗██╗╗ ██╗ █████╗ ████████╗ █████╗ ██████╗
██╔══██╔════╝██╔════╝██║██║ ██╔══██╗██║ ██╔══██╗██╔══╝██╔══██╗██╔══██╗
███████║███████╗██║ ██║██║ ███████║██║ ██║██████ ██║ ███████║██████╔╝
██╔══██║╚════██║██║ ██║ ██╔══██║╚██╗ ██╔╝══██║ ██║ ██╔══██║══██╗
██║ ██║███████║╚██████╗██║██║ ██║ ██║ ╚████╔╝ ██║ ██║ ██║ ██║ ██║██║ ██║
╚═╝ ╚═╝╚══════╝ ╚═════╝╚═╝╚═ ╚═╝ ╚═╝ ═══╝ ╚═╝ ╚ ╚═ ╚═╝ ═╝╚═╝ ╚═╝
```
一个朋克风格的 ASCII 角色，居住在 tmux 窗格中，与 Claude Code 并存。它观察 Claude 的思考、发言和聆听，并实时动画，借助本地 TTS 大声朗读回应。
---
## 工作原理
```mermaid
flowchart LR
subgraph claude ["Claude Code"]
H1["用户提示提交钩子"]
H2["停止钩子"]
H3["通知钩 end
subgraph ipc ["ZeroMQ IPC"]
SOCK["ipc:///tmp/ascii-avatar.sock\nPUSH / PULL"]
end
subgraph avatar ["角色进程"]
SM["状态机"]
SM -->|idle / thinking / speaking\nlistening / error| REN["渲染器\n（blessed 终端）"]
SM --> PM["角色管理器"]
VE["语音引擎"]
VE --> K["Kokoro ONNX\n主要"]
VE --> EL["ElevenLabs\n云端，选填"]
VE --> PI["Piper\n备用"]
end
H1 -->|思考| SOCK
H2 -->|发言| SOCK
H3 -->|发言| SOCK
SOCK --> SM
style claude fill:#0a0a1a,stroke:#00d4ff,color:#e0e0e8
style ipc fill:#0a1a,stroke:#ffb300,color:#e0e8
style avatar fill:#0a0,stroke:#00ff88,color:#e0e0e8
style SOCK fill:#1a1a26,stroke:#ffb300,color:#ffb300
style SM fill:#1a1a26,stroke:#00d4ff,color:#4ff
style:#1a1astroke:#00d4ff,color:#00d4ff style PM fill:#1a26,stroke:#00d4ff,color:#00d4ff
style VE fill:#1a1a26,stroke:#00d4ff,color:#00d4ff
style K fill:#1a1a26,stroke:#b388ff,color:#b388ff
style EL fill:#1a1a26,stroke:#b388ff,color:#b388ff
style PI fill:#1a26,stroke:#b,color:#b388ff
style H1 fill:#1a1a26,stroke:#00d4ff,color:#00d4ff
style fill:#1a26,stroke:#00,color:#00d4ff
style H3 fill:#1a1a26,stroke:#00d4ff,color:#00d4ff
```
Claude Code 通过 Unix接字（ZeroMQ PUSH/PULL）推送事件。这些事件，驱动一个线程安全的 状态机，动画器，并合成语音。当模型缺失或传递 `--no-voice` 时，它会回仅动画模式。
---
## 功能
- 五种动画状态 — 空闲、思考、聆听、错误 — 每种状态都有不同的帧时间
- 通过 [Kokoro ONNX](https://github.com/thewh1teagle/kokoro-onnx) TTS（约 338 MB，无需 API 密钥）
- 三种角色，具有不同的语音、颜色和动画速度
MQ IPC — 钩每次 Claude 工具，无明显延迟
- MCP 服务器，允许 Claude 通过工具调用直接控制其自己的角色
- `avatar-bridge` 命令行界面，用于脚本编写和手动测试
- 肖像模式：交换 ASCII 帧以在终端中渲染图像
- 无头模式，用于 CI 和集成测试
---
## 角色
| 角色 | 颜色 | 语音 | 引擎 | 个性 | 速度 |
|---------|-------|-------|--------|-------------|-------|
| `ghost`（默认） | 青色 | af_bella | Kokoro | 极简 | 1.0x |
| `oracle` | 琥珀色 | bf_emma | Kokoro | 圣贤 | 0.8x |
| `spectre` | 绿色 | — | ElevenLabs | 故障 | 1.3x |
`spectre` 需要 `ELEVENLABS_API_KEY`。如果没有它，如果存在模型，则会回退到 Kokoro，否则仅动画。
---
## 快速开始
**一条命令** 安装软件包，下载 TTS 模型，配置 Claude Code 钩子，并设置 tmux 启动器：
```bash
# 首先安装 portaudio（TTS 音频所需）
sudo apt install portaudio19-dev # Debian/Ubuntu
sudo dnf install portaudio-devel # Fedora/RHEL
# 然后安装所有内容
curl -sSL https://raw.githubusercontent.com/Angelopvtac/ascii-avatar/master/install.sh | bash
```
就这样。开始使用：
```bash
avatar-session # tmux：Claude Code + 角色并排
avatar # 独立角色进程
```
<details>
<summary>手动安装（分步）</summary>
```bash
pipx install "git+https://github.com/Angelopvtac/ascii-avatar.git[kokoro]"
bash scripts/install.sh # 下载 TTS 模型 scripts/setup-hooks.sh 打印 Claude Code 钩子配置
bash scripts/setup-tmux.sh # 添加 tmux 别名
```
</details>
<details>
<summary></summary>
```bash 跳过 TTS动画，无语音）
curl -sSL .../install.sh |s -- --no-tts
# 跳过 Claude Code 钩子设置
sSL .../install.sh | bash -s -- --no-hooks
# 卸载所有内容
curl -sSL .../install.sh | bash -s -- --uninstall
```
</details>
按 `q` 或 `Esc` 退出。
---
## Claude Code 集成
### 钩子（自动）
钩子在每次工具使用时触发，使角色与 Claude 的活动保持同步。添加到 `~/.claude/settings.json`：
```json
{
"hooks "Pre": [
{ "command": "avatar think" }
],
"PostToolUse": [
{ "command": "avatar-bridge idle" }
],
"Notification": [
"command": "avatar-bridge speak \"$CLAUDE_NOTIFICATION\"" }
]
}
}
```
运行 `bash scripts/setup-hooks 以打印此配置并填写路径。
### MCP 服务器（基于工具的控制）
MCP 服务器允许 Claude 通过工具调用直接控制其自己的角色。添加到 `~/.claude/settings.json`：
```json
{
"mcpServers": {
"ascii-avatar": {
"command": "avatar-mcp"
}
}
```
可用工具：`avatar_th、`avatar_speak`、`avatar_listen`、`avatar_idle`。
---
## tmux 设置
要自动启动 Claude Code 和角色并排：
```bash
bash scripts/setup-tmux.sh
source ~/.bashrc
clauded-avatar
```
这会创建一个 tmux 会话，角色在 45 列的分屏窗格中。
---
## 命令行界面参考
**角色进程**
```
avatar [--persona ghost|oracle|spectre] [--socket PATH] [--no-voice]
[--no-color] [--voice VOICE_ID] [--audio-device INDEX]
[--compact] [--no-boot] [--portrait PATH] [--headless] [-v]
```
**桥接器（向正在运行的角色发送事件）**
```
avatar-bridge [--socket PATH] think|listen|idle
avatar-bridge [--socket PATH] speak TEXT
avatar PATH] error]
```
---
## 故障排除
**“Kokoro 模型未找到”** — 运行 `bash scripts/install.sh`。角色将继续以仅动画模式运行，直到存在模型。
**无音频 / `sounddevice` 错误** — 在 Python 依赖项之前安装 `portaudio` 系统库（参见快速开始步骤 1）。
**套接字错误** — 确保在发送事件之前角色进程正在运行。`--socket` 路径在双方必须匹配（默认为 `/tmp/ascii-avatar.sock`**ElevenLabs 无法工作** — 在启动角色之前，在环境中设置LEVENLABS_API---
## 许可证
MIT
