humhum: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目简介

HumHum 是一个 Tauri v2 桌面宠物应用，监听多种 AI 编程助手事件（Claude Code、Codex、Qwen Code、Gemini CLI、Kimi K1 的 hooks 以及 QoderWork 日志），将其转化为语音播报，并支持语音指令和键盘快捷键交互。UI 是一个透明的、始终置顶的圆形小窗口，宠物形象是一只灯塔水母 "Hum"。

常用命令

npm install           # 安装依赖
npm run tauri dev     # 开发模式（同时启动 Vite 前端 + Rust 后端）
npm run tauri build   # 生产构建
npm run build         # 仅前端构建（tsc + vite）

Rust 后端在 src-tauri/ 目录下，支持标准 cargo 命令，但日常开发主要用 npm run tauri dev。

手动模拟事件（用于测试）：

curl -X POST http://localhost:31275/event \
  -H "Content-Type: application/json" \
  -d '{"hook_event_name":"TaskCompleted","session_id":"test-123","payload":{}}'

前端测试：npm test（vitest + node --test via scripts/run-tests.mjs）。完整测试套件：npm run test:all（含 relay 测试）。Rust 测试：cd src-tauri && cargo test --lib。类型检查：npx tsc --noEmit 或 npm run build。无 ESLint/Prettier 配置；类型安全依赖 tsc。

架构

双进程模型（Tauri v2）

• Rust 后端（src-tauri/src/）：在端口 31275 运行 hyper HTTP 服务器（非 Axum/Actix），管理配置、会话存储、客户端注册表，通过 Tauri 事件系统向前端发送事件。
• React 前端（src/）：渲染两个窗口 — "main"（280×210，透明桌宠浮层）和 "settings"（420×620，设置面板，默认隐藏）。App.tsx 通过 getCurrentWindow().label 判断窗口，在 PetWindow 挂载时调用 initBootstrap() 初始化全局单例。

语音管线（核心数据流）

事件到达 → VoicePipeline.processEvent()
    → 2 秒批量窗口（BATCH_WINDOW_MS）聚合快速连发事件
    → mergeEvents() 合并多事件为单次请求
    → OpenAISummarizer.summarize() (非流式调用，逐字符 yield)
    → SentenceSplitter.feed(char) (逐句切分，首句限60字加速TTFB)
    → TTS.synthesize(sentence) (Edge/OpenAI/ElevenLabs)
    → Rust play_audio IPC (base64 → /tmp/humhum-audio/*.mp3 → afplay)
    → 宠物状态: idle → processing → speaking → idle

注意：Summarizer 使用 stream: false 一次性获取完整响应，然后逐字符 yield 给 SentenceSplitter。音频播放使用 macOS 原生 afplay 命令，通过 Rust IPC（play_audio/stop_audio）调用，不使用 Web Audio API 播放。

初始化入口：src/lib/bootstrap.ts — 读取 Rust 配置，注册所有 provider，创建 VoicePipeline 等全局单例，通过 getAudioQueue() / getPipeline() / getSummarizer() / getSentenceSplitter() 导出访问。