🐷 小猪 Piggy

把一台越狱的 Echo Show 5 变成会说话、有表情的 AI 伴侣：

• 🎤 语音对话 — 对它说话，它用 AI 思考，用语音回答
• 🐷 可爱角色 — 屏幕上有一只小猪，会随对话状态变换表情
• 💡 智能家居 — 通过 Home Assistant 控制灯光、设备
• 🧠 记忆 — 记得之前聊过什么（复用 Hermes 记忆系统）

素材来源：Piggy Emoji Expressions Animation Pack（IconScout，20 个表情）

1. 购买和下载

1. 打开 LottieFiles Marketplace 链接，登录 LottieFiles 账号
2. 购买素材包（通常 $10-30，一次性）
3. 下载后得到 20 个 .json 文件（Lottie 格式），每个文件是一个表情动画
4. 也可以在 iconscout.com 单独购买某个表情

2. 表情 → 状态映射

将 20 个表情映射到 Piggy 的 8 个状态：

💡 每个状态只需要 1 个 JSON 文件。剩余 12 个表情可以留着做随机彩蛋（比如长时间 idle 切到 Sleeping）。

3. 上传到项目

# 下载的 JSON 文件重命名后放入 assets/lottie/
cp idle.json        /var/www/piggy/assets/lottie/
cp listening.json   /var/www/piggy/assets/lottie/
cp thinking.json    /var/www/piggy/assets/lottie/
cp speaking.json    /var/www/piggy/assets/lottie/
cp happy.json       /var/www/piggy/assets/lottie/
cp sad.json         /var/www/piggy/assets/lottie/
cp angry.json       /var/www/piggy/assets/lottie/
cp disconnected.json /var/www/piggy/assets/lottie/

# 提交到 git
cd /var/www/piggy
git add assets/lottie/
git commit -m "Add piggy Lottie expressions"
git push

4. 代码集成

在 index.html 中引入 Lottie Web：

<!-- index.html <head> 中添加 -->
<script src="lib/lottie.min.js"></script>

修改 piggy.js，用 Lottie 替换 CSS 动画：

class PiggyCharacter {
    constructor() {
        this.container = document.getElementById('piggy');
        this.anim = null;
        this.state = 'idle';
        this._loadAnimation('idle');
    }

    static ANIMATIONS = {
        idle:         '/assets/lottie/idle.json',
        listening:    '/assets/lottie/listening.json',
        thinking:     '/assets/lottie/thinking.json',
        speaking:     '/assets/lottie/speaking.json',
        happy:        '/assets/lottie/happy.json',
        sad:          '/assets/lottie/sad.json',
        angry:        '/assets/lottie/angry.json',
        disconnected: '/assets/lottie/disconnected.json',
    };

    setState(state) {
        if (this.state === state) return;
        this.state = state;
        this._loadAnimation(state);
    }

    _loadAnimation(state) {
        if (this.anim) this.anim.destroy();
        const path = PiggyCharacter.ANIMATIONS[state];
        if (!path) return;
        this.anim = lottie.loadAnimation({
            container: this.container,
            renderer: 'svg',
            loop: true,
            autoplay: true,
            path: path,
        });
    }
}

💡 Lottie 动画是矢量 SVG，自动缩放适配屏幕。文件通常 20-100KB，加载很快。

1. 创建目录

mkdir -p /opt/data/xiaozhi
mkdir -p ~/xiaozhi-stack

2. docker-compose.yml — 在宿主机创建：

sudo nano ~/xiaozhi-stack/docker-compose.yaml

粘贴以下内容：

services:
  xiaozhi-server:
    image: ghcr.m.daocloud.io/xinnan-tech/xiaozhi-esp32-server:server_latest
    container_name: xiaozhi-server
    restart: unless-stopped
    security_opt:
      - seccomp:unconfined
    ports:
      - '127.0.0.1:8000:8000'   # WebSocket
      - '127.0.0.1:8003:8003'   # HTTP/OTA
    volumes:
      - /opt/data/xiaozhi:/opt/xiaozhi-esp32-server/data
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    deploy:
      resources:
        limits:
          memory: 256M
          cpus: '0.5'

💡 extra_hosts 让容器内可通过 host.docker.internal:8642 访问宿主机的 Hermes API。默认配置不需要这行，但留着也没坏处。

3. data/.config.yaml — 在宿主机编辑：

sudo nano /opt/data/xiaozhi/.config.yaml

粘贴以下内容（替换 YOUR_XXX 为你的实际密钥）：

根据选择的 LLM 方案，使用对应的配置：

默认配置：DeepSeek V4 Flash 直连

server:
  ip: 0.0.0.0
  port: 8000
  http_port: 8003
  websocket: wss://piggy.treetree.tech/xiaozhi/v1/

selected_module:
  ASR: Qwen3ASRFlash
  LLM: DeepSeekLLM
  TTS: CosyVoiceSiliconflow
  VAD: SileroVAD
  Intent: nointent
  Memory: nomem

ASR:
  Qwen3ASRFlash:
    type: qwen3_asr_flash
    api_key: YOUR_DASHSCOPE_API_KEY
    base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
    model_name: qwen3-asr-flash
    output_dir: tmp/
    enable_lid: true  # 自动语种检测
    enable_itn: true  # 逆文本归一化

  # 备选：阿里百炼 Paraformer 流式（WebSocket 流式，延迟低）
  AliyunBLStreamASR:
    type: aliyunbl_stream
    api_key: YOUR_DASHSCOPE_API_KEY  # 同一个阿里云百炼 API Key
    model: paraformer-realtime-v2
    format: pcm
    sample_rate: 16000
    output_dir: tmp/
    punctuation_prediction_enabled: true
    inverse_text_normalization_enabled: true

  # 备选：Groq Whisper（免费，每天 28,800 秒）
  GroqASR:
    type: openai
    api_key: YOUR_GROQ_KEY
    base_url: https://api.groq.com/openai/v1/audio/transcriptions
    model_name: whisper-large-v3-turbo
    language: "zh"  # 强制识别为中文
    prompt: "这是中文对话，包含少量英语单词。"  # 引导模型识别中文为主、偶尔夹杂英语
    output_dir: tmp/

  # 备选：讯飞流式 ASR（需注册讯飞开放平台）
  XunfeiStreamASR:
    type: xunfei_stream
    app_id: YOUR_APP_ID
    api_key: YOUR_API_KEY
    api_secret: YOUR_API_SECRET
    domain: slm
    language: zh_cn
    accent: mandarin

LLM:
  DeepSeekLLM:
    type: openai
    model_name: deepseek-chat
    url: https://api.deepseek.com
    api_key: YOUR_DEEPSEEK_API_KEY
    temperature: 0.7

TTS:
  # 备选：EdgeTTS（免费，无需 API Key）
  EdgeTTS:
    type: edge
    voice: zh-CN-XiaoxiaoNeural
    output_dir: tmp/

  # 备选：硅基流动 CosyVoice2（可能不稳定）
  CosyVoiceSiliconflow:
    type: siliconflow
    model: FunAudioLLM/CosyVoice2-0.5B
    voice: FunAudioLLM/CosyVoice2-0.5B:diana
    access_token: YOUR_SILICONFLOW_API_KEY
    output_dir: tmp/

VAD:
  SileroVAD:
    type: silero
    threshold: 0.5
    model_dir: models/snakers4_silero-vad
    min_silence_duration_ms: 500

prompt: |
  你是小猪 Piggy，一只可爱的小猪 AI 伴侣。说话简短可爱，喜欢用 emoji。
  你住在 Echo Show 屏幕上，会随情绪变换表情。

在宿主机编辑 /opt/data/xiaozhi/.config.yaml，修改两处即可，重启容器生效：

sudo nano /opt/data/xiaozhi/.config.yaml

# 1. 改 selected_module.TTS
selected_module:
  TTS: CosyVoiceSiliconflow   # ← 改这里（可选值见下表）

# 2. 确认对应 TTS 配置段存在
TTS:
  # 推荐：EdgeTTS（免费，稳定，无需 API Key）
  EdgeTTS:
    type: edge
    voice: zh-CN-XiaoxiaoNeural    # 微软甜美女声
    format: mp3  # 指定输出格式为 MP3，避免 WAV 格式错误
    output_dir: tmp/

  # 备选：硅基流动 CosyVoice2（可能不稳定）
  CosyVoiceSiliconflow:
    type: siliconflow
    model: FunAudioLLM/CosyVoice2-0.5B
    voice: FunAudioLLM/CosyVoice2-0.5B:diana     # 欢快女声（可选: :alex :benjamin :charles :david :anna :bella :claire :diana）
    access_token: 你的_SILICONFLOW_API_KEY
    output_dir: tmp/

💡 CosyVoice2 可用音色：:alex（男声）、:diana（女声，欢快）、更多见 SiliconFlow 文档。格式：FunAudioLLM/CosyVoice2-0.5B:音色名。

💡 提示：硅基流动 CosyVoice2 支持流式合成，首音延迟低。如果遇到稳定性问题，可随时切换到 EdgeTTS（免费备选）。

💡 完整 TTS 列表见 xiaozhi-server 官方 config.yaml。

方案 A：DeepSeek V4 Flash 直连（默认，已在上面 config.yaml 中配置好）

无需额外操作，selected_module.LLM: DeepSeekLLM 即可。

方案 B：Hermes API 网关（可选，需先启用 Hermes API Server）

与方案 A 的区别：LLM 调用经过 Hermes 中转，自动获得记忆、工具、技能。只需改两处：

sudo nano /opt/data/xiaozhi/.config.yaml

# /opt/data/xiaozhi/.config.yaml — 改两处

selected_module:
  LLM: HermesLLM          # ← 从 DeepSeekLLM 改为 HermesLLM
  Memory: nomem            # Hermes 自带记忆，xiaozhi 侧关闭

LLM:
  HermesLLM:
    type: openai
    model_name: hermes-agent
    url: http://host.docker.internal:8642/v1
    api_key: piggy-secret-key    # 需与 Hermes API_SERVER_KEY 一致

启用 Hermes API Server 步骤：

# 1. 在宿主机编辑 /opt/hermes/.env，添加：
nano /opt/hermes/.env

添加以下三行：

API_SERVER_ENABLED=true
API_SERVER_HOST=127.0.0.1
API_SERVER_KEY=piggy-secret-key

# 2. 重启 Hermes
docker compose -f /opt/hermes/docker-compose.yml restart gateway

# 3. 验证
curl -s http://127.0.0.1:8642/health

# 4. 改好 config.yaml（见上面），重启 xiaozhi-server
cd ~/xiaozhi-stack && docker compose restart

4. 启动 xiaozhi-server

# 预检端口占用
ss -tlnp | grep -E ':8000|:8003' && echo "⚠️ 端口被占用，先停掉冲突服务" || echo "✅ 端口空闲"

cd ~/xiaozhi-stack && docker compose up -d
docker logs -f xiaozhi-server
# 看到 "Websocket地址是 ws://..." 即成功

1. 克隆仓库

git clone git@github.com:treetree17/piggy-display.git /var/www/piggy

2. 验证文件

ls -la /var/www/piggy/
# 应该看到: index.html, css/, js/, assets/, lib/, nginx/

3. 后续更新

cd /var/www/piggy && git pull

1. 创建配置文件 — 在宿主机用 tee 一次性写入（比手动 nano 不容易出错）：

sudo tee /etc/nginx/sites-available/piggy > /dev/null << 'EOF'
server {
    listen 80;
    http2 off;
    server_name piggy.treetree.tech;

    # 拒绝访问隐藏文件（.git/ 等）
    location ~ /\\. {
        deny all;
        return 404;
    }

    # 前端静态文件
    root /var/www/piggy;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # WebSocket 代理 → xiaozhi-server
    location /xiaozhi/v1/ {
        proxy_pass http://127.0.0.1:8000/xiaozhi/v1/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }

    # OTA 接口
    location /xiaozhi/ota/ {
        proxy_pass http://127.0.0.1:8003/xiaozhi/ota/;
        proxy_set_header Host $host;
    }
}
EOF

💡 SSL 由 Cloudflare Tunnel 自动处理（Tunnel 终止 TLS），nginx 只需监听 80 端口。不需要配置 A 记录或 SSL 证书。

2. 启用站点

# 创建软链接启用站点
sudo ln -s /etc/nginx/sites-available/piggy /etc/nginx/sites-enabled/

# 测试配置语法（必须看到 "syntax is ok" 才继续）
sudo nginx -t

# 重载 nginx（不用 restart，不断现有连接）
sudo systemctl reload nginx

3. 验证

# 在服务器上
curl -sI https://piggy.treetree.tech/                              # → 200 OK
curl -s https://piggy.treetree.tech/assets/lottie/cool.json | head -c 100  # → JSON 数据

# 验证 WebSocket 代理（返回 400 说明代理通了）
curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8000/xiaozhi/v1/  # → 400

4. Cloudflare Tunnel

piggy.treetree.tech 通过 Cloudflare Tunnel 暴露，不需要 A 记录。Tunnel 配置：

# Tunnel 配置文件：/etc/cloudflared/config.yaml
# Tunnel ID：8eb7a559-55e7-4f74-9471-a44ad5c49794
tunnel: 8eb7a559-55e7-4f74-9471-a44ad5c49794
credentials-file: /home/hermes/.cloudflared/8eb7a559-55e7-4f74-9471-a44ad5c49794.json
protocol: http2

ingress:
  - hostname: piggy.treetree.tech
    service: http://localhost:80
  - service: http_status:404

💡 在 Cloudflare Dashboard → Zero Trust → Networks → Tunnels 中管理。使用 http2 协议（QUIC 可能导致 context deadline exceeded）。

Echo Show 上只装两样东西：LineageOS + Fully Kiosk Browser。零代码，纯显示终端。

1. 越狱 + 刷 LineageOS

按教程操作：pub.treetree.tech/echo-show-jailbreak

2. 购买 Fully Kiosk Browser

官网：fully-kiosk.com，€8.90 一次性买断（一个设备一个 license）。购买后会收到 APK 下载链接和 license key。

3. ADB sideload 安装

# 确认 ADB 已连接
adb devices

# 安装 Fully Kiosk APK（下载后放在当前目录）
adb install fully-kiosk-browser-xxx.apk

# 如果安装失败（签名冲突），先卸载旧版
adb uninstall de.ozerov.fully

4. Fully Kiosk 设置

打开 Fully Kiosk，在 Settings 中配置：

5. 手势切换：Piggy ↔ HA Dashboard

Fully Kiosk 支持手势触发动作。配置双击切换页面，无需在 Piggy 页面上加任何按钮，全屏体验不受影响：

HA Dashboard 切回 Piggy：

在 HA 中使用 Fully Kiosk 集成，添加按钮调用 fully_kiosk.load_url 切回 Piggy：

# HA button card 或 automation
action: fully_kiosk.load_url
target:
  device_id: <echo-show-device-id>
data:
  url: https://piggy.treetree.tech

6. 开发者选项（兜底）

Android 设置 → 开发者选项 → Stay Awake（充电时屏幕常亮）。万一 Fully Kiosk 没自动启动，至少屏幕不会灭。

7. 验证清单

• ✅ 重启设备 → Fully Kiosk 自动启动 → 显示 Piggy 页面
• ✅ 点击页面按钮 → 麦克风正常采集（无弹窗）
• ✅ 说话 → 扬声器播放 TTS 回复
• ✅ 按返回键/手势 → 无法退出（kiosk 模式锁定）
• ✅ 双击屏幕 → 切换到 HA Dashboard
• ✅ 屏幕持续亮着不灭

✅ 已验证方案：Reddit/XDA 多人成功在 Echo Show + LineageOS 上用 Fully Kiosk 跑 HA Dashboard。Mark Watt Tech 有完整视频教程（14万播放）。

1. xiaozhi-server 配置 HA MCP 接入
2. 实现语音控制家居（"开灯"、"空调调到25度"）
3. 意图识别 → function_call → HA 服务调用

参考 xiaozhi-performance-research 的测试数据，采用流式配置可将整体响应延迟从 ~4s 降低到 ~1.5s：

💡 三级流水线：ASR 边听边识别 → LLM 首 Token 即触发 TTS → TTS 边合成边发音频。不是串行等待。

• Porcupine Web SDK（Picovoice）— 纯浏览器端 WASM 唤醒词检测
• 支持中文自定义唤醒词（可训练"你好小猪"）
• Echo Show 上不需要装任何东西，唤醒词在浏览器里运行
• 免费 tier 够个人用
• 替代方案：openwakeword-wasm-browser（开源免费，但仅英文预设唤醒词）

• CosyVoice2 (SiliconFlow)（主力）→ 流式，首音 ~0.15s，支持声音克隆
• EdgeTTS（备选）→ 免费，稳定，中文甜美女声，延迟 ~1-2s
• FishSpeech（远期）→ 本地克隆音色，需要更多内存

• 当前：可爱 🐷 CSS/Lottie 基础表情
• 后续：更丰富的表情动画（生气、思考、打瞌睡等）
• 远期：Rive Editor 专业级动画，状态机驱动

• xiaozhi-server 接入 Home Assistant MCP
• 语音控制："开灯"、"空调调到25度"
• 意图识别 → function_call → HA 服务调用

• 方案 A（Hermes 网关）：LLM 经过 Hermes → 自动注入 hindsight 长期记忆，跨会话持久化，无需额外配置
• 直连 LLM（DeepSeek V4 Flash）：可使用 xiaozhi 内置 mem_local_short（本地短期记忆）或 mem0ai（云端，1000次/月免费）

当前安全架构：

• ✅ 容器端口绑定 127.0.0.1 — 外网不可直达
• ✅ Cloudflare Flexible TLS — 浏览器↔CF 加密传输
• ✅ nginx dotfile 保护 — .git/ 不暴露
• ✅ 容器资源限制 — 不会吃光内存
• ✅ API 密钥不在 Git 仓库中

⚠️ 潜在风险：WebSocket 端点无认证，任何人知道 URL 就能连接，消耗 Groq/OpenCode 额度。单人使用风险低，但建议加 Cloudflare 保护。

在 Cloudflare 层面拦截未授权访问，不改 nginx，不改代码。

方式一：WAF Custom Rule（精确控制）

只允许你的 Echo Show IP 访问 WebSocket 路径，其他请求直接 block：

1. 登录 dash.cloudflare.com → 选 treetree.tech
2. 左侧 Security → WAF → Custom rules → Create rule
3. 配置：

💡 Echo Show 在家里，IP 基本固定。如果有多设备，用 IP is not in {IP1, IP2} 加白名单。

方式二：Rate Limiting（防刷）

即使不知道你的 IP，也能防止脚本暴力刷接口：

1. Cloudflare → Security → WAF → Rate limiting rules → Create rule
2. 配置：

💡 正常语音对话不会超过 10 req/min（一次对话 = 1 次 WebSocket 连接）。此规则防的是脚本批量连接。

方式三：Cloudflare Access（最强，需 Zero Trust）

在 /xiaozhi/ 路径前加一层身份验证，只有通过认证的设备才能访问：

1. Cloudflare → Zero Trust → Access → Applications → Add application
2. 选 Self-hosted，填 piggy.treetree.tech/xiaozhi/
3. Policy：允许你的邮箱 或 One-time PIN
4. Echo Show 首次访问时会弹 Cloudflare 登录页，认证后 Cookie 有效期内免登

⚠️ 这个方案最安全，但 Echo Show 上的浏览器需要能完成 OAuth 流程。Fully Kiosk 支持。

单人使用 + Echo Show 在家里：当前保护已够用。如果担心被扫到，加 Cloudflare WAF 规则（方式一）5 分钟搞定。

仓库名：piggy-display（独立仓库，方案 A）

piggy-display/
├── index.html              ← 主页面（路线 C 核心，单文件可运行）
├── css/
│   └── style.css           ← 样式 + 小猪角色 CSS 动画
├── js/
│   ├── websocket.js        ← xiaozhi WebSocket 协议（音频帧/状态帧）
│   ├── audio.js            ← getUserMedia 麦克风采集 + Web Audio 播放
│   └── piggy.js            ← 小猪角色状态机（idle/listening/thinking/speaking/emotion）
├── assets/
│   └── lottie/             ← 小猪 Lottie 动画文件
├── wakeword/               ← 路线 B（Porcupine WASM 唤醒词）
│   ├── porcupine/          ← Porcupine 模型文件 (.ppn)
│   └── wakeword.js          ← 浏览器端唤醒词引擎
│   └── models/             ← Porcupine .ppn 模型文件
├── nginx/
│   └── piggy.conf          ← Nginx server block 配置
└── README.md

为什么独立仓库：

• 前端是核心定制部分（小猪角色、UI），跟官方 digital-human 差异越来越大
• 后端直接用官方 Docker 镜像 xinnan-tech/xiaozhi-esp32-server，不需要改
• 路线 B 唤醒词代码从官方复制过来改，不需要 submodule

临时下线（维护模式）

# 移除 nginx 链接（站点立即不可访问）
sudo rm /etc/nginx/sites-enabled/piggy
sudo systemctl reload nginx

恢复上线

# 恢复 nginx 链接
sudo ln -s /etc/nginx/sites-available/piggy /etc/nginx/sites-enabled/piggy
sudo systemctl reload nginx

更新前端代码

cd /var/www/piggy
sudo git fetch origin
sudo git reset --hard origin/main
# 验证更新
sudo git log --oneline -1

手动重启

# 1. 更新前端代码
cd /var/www/piggy && git pull

# 2. 重启 xiaozhi-server
docker restart xiaozhi-server

# 3. 重启 nginx
sudo systemctl restart nginx

# 4. 验证服务
curl -s http://127.0.0.1:8000/xiaozhi/v1/ | head -1

故障排查

# TTS 故障排查（宿主机运行）
sudo bash /opt/data/scripts/piggy-tts-debug.sh

音频诊断

# TTS 音频问题诊断（宿主机运行）
sudo bash /opt/data/scripts/piggy-audio-diagnosis.sh

查看实时日志

# xiaozhi-server 日志
docker logs xiaozhi-server -f --tail 50

# nginx 访问日志
sudo tail -f /var/log/nginx/access.log | grep piggy