by kk43994
🦞 一个可爱的桌面龙虾AI助手 - Desktop lobster pet with OpenClaw AI, Edge TTS voice, and emotion animations
# Add to your Claude Code skills
git clone https://github.com/kk43994/kkclaw给你的 AI Agent 一个桌面身体:可视化球体 + 语音交互 + 情绪表达。
AGENTS.md / SOUL.md / USER.md / HEARTBEAT.mdgit clone https://github.com/kk43994/kkclaw.git
cd kkclaw
npm install
npm start
或下载安装包:
编辑 pet-config.json 自定义:
No comments yet. Be the first to share your thoughts!
kkclaw/
├── main.js # Electron 主进程
├── index.html # 球体渲染 UI
├── lyrics.html # 歌词字幕窗口
├── setup-wizard.html # Setup Wizard 界面
├── setup-wizard.js # Setup Wizard 逻辑
├── gateway-client.js # Gateway 通信客户端
├── smart-voice.js # 语音调度系统
├── templates/ # Agent 模板文件
├── voice/ # TTS 引擎模块
├── utils/ # 工具模块
├── scripts/ # 构建脚本
└── docs-dev/ # 开发文档
给你的兼容后端 AI(OpenClaw / Hermes)一个看得见、听得到的桌面化身。
| 功能 | 说明 | |------|------| | 🔮 流体玻璃球 | 67px 琉璃质感球体,内部液体持续流动,宛如活物(3层流体动画 + 径向渐变 + 双重高光) | | 🌈 14种心情变色 | 开心暖橙、伤心天蓝、生气火红……每种情绪对应独立颜色与光晕效果(14-emotion glow system) | | 👀 38种待机微表情 | 待机时自动播放眨眼、歪头、偷瞄、打盹、星星眼、装死等表情,营造鲜活性格感(idle micro-expression engine) | | 🕐 时间感知表情 | 早晨活力、午后困倦、深夜哈欠——自动感知当前时段并切换表情(时间场景感知:morning / noon / afternoon / evening / latenight) | | 🖱️ 鼠标跟踪眼神 | 球体眼睛跟随光标方向转动,增强互动感(mouse tracking) | | 💗 害羞脸红 | 特定表情触发时,脸颊浮现粉色红晕(dynamic blush overlay) | | 🫧 气泡装饰粒子 | 球体周围飘浮半透明气泡,增添灵动氛围(bubble particle decoration) | | ✨ 点击弹跳反馈 | 点击球体产生弹性压缩 + 颜色脉冲,操作有手感(squish animation + color pulse) | | 🎈 悬浮呼吸效果 | 球体微幅上下浮动,如同水面漂浮(60fps float + breath scaling) |
| 功能 | 说明 |
|------|------|
| 🎤 一键声音克隆 | 上传30秒录音即可克隆声音,AI 用你自己的音色说话(MiniMax Voice Cloning API) |
| 🎵 8种预设音色 | 无需克隆,直接选择官方预设音色即可使用(8 preset voices) |
| 🗣️ 14种情��语调 | 根据文本内容自动匹配情绪语气——欢快、低沉、激动等自然切换(emotion-aware TTS) |
| 🔉 智能降级链 | 主引擎故障自动切备用引擎,确保语音永不中断(MiniMax → Edge TTS 降级链) |
| ⏸️ 自然停顿 | 在标点符号处自动添加语气停顿,告别机器人式朗读(TTS pause markers <#0.5#>) |
| 📝 桌面字幕同步 | 语音播报时同步显示逐字字幕,打字机效果呈现(typewriter lyrics overlay) |
| 🔇 消息排队播报 | 多条消息同时到达时自动排队,逐条播出不叠音(priority speech queue) |
| 🚫 重复消息过滤 | 相同内容自动去重,避免重复播报(whitespace-normalized dedup filter) |
| 功能 | 说明 | |------|------| | 🎭 5种性格预设 | 甜妹 / 专业 / 幽默 / 酷帅 / 自定义,一键切换说话风格(personality preset system) | | 📝 人设文件自动生成 | 选定性格后一键生成 AI 人格档案,无需手写提示词(auto-generate AGENTS.md + SOUL.md + USER.md) | | 💬 自定义称呼 | 自定义宠物名称和对你的称呼,如「小K叫你主人」(petName + userName 配置) |
| 功能 | 说明 | |------|------| | ⚡ 自动拉起 | 连续3次检测 Gateway 不在线后自动启动,无需手动干预(Guardian auto-start) | | 📊 实时健康监控 | 后台持续采集 Gateway 运行指标,异常时第一时间告警(anomaly detection + health scoring) | | 🎙️ 语音状态播报 | 启动中 / 成功 / 失败均有语音通知,不必盯控制台(voice status announcement) | | 🔄 崩溃自动重启 | Gateway 异常退出后自动拉起,每小时上限10次防止死循环(auto-restart with rate limiting) | | 🩺 10项一键体检 | Gateway / TTS / 模型 / 端口 / 缓存 / 日志等10维一键诊断,附修复建议(Doctor self-check) | | 🔧 双重确认防误判 | 重启前与 ServiceManager 交叉校验,避免误杀健康实例(cross-validation with ServiceManager) | | ⏳ 启动宽限期 | 首次启动60秒内不触发重启逻辑,给 Gateway 充足启动时间(startup grace period) |
| 功能 | 说明 | |------|------| | 🎮 RPG 游戏风格 | 木质边框 + 羊皮纸纹理 + 龙虾向导 NPC + 打字机对白(RPG-style Setup Wizard) | | 📋 7步全流程引导 | Gateway → 模型 → 消息渠道 → 语音引擎 → 播报设置 → 显示选项 → 全链路测试 | | ⚡ 缺失依赖一键安装 | 检测到缺失依赖后一键安装,实时显示安装进度(one-click dependency install + real-time progress) | | 🔍 智能环境检测 | 自动探测 Node.js / Python / 兼容 CLI(OpenClaw)等环境状态及版本信息(smart environment detection) | | ✅ 全链路验证 | 7项端到端测试确保所有功能正常运行(end-to-end validation) | | 🐛 错误可视化 | 向导异常时直接显示报错信息,不再白屏无提示(error visualization + crash recovery) |
| 功能 | 说明 | |------|------| | 🌈 彩色终端日志 | 12+ 模块统一彩色输出——模型名青色、URL绿色、错误红色,一目了然(ANSI colorized logging) | | 🔇 日志自动去重 | 空白归一化后去重,消除控制台刷屏(whitespace-normalized dedup) | | 📁 日志轮转归档 | 按天归档、超10MB自动压缩、保留7天历史(log rotation + gzip archiving) | | 📊 性能实时监控 | 内存 / CPU / 帧率实时采集,超阈值自动告警(performance monitor + 24h sample history) |
| 功能 | 说明 | |------|------| | 🔄 热切换 | Claude ↔ GPT ↔ Gemini ↔ DeepSeek 无需重启,3秒生效(hot model swap via CC-Switch) | | 📊 延迟测速 | 一键对比各模型响应延迟,选择最优(latency benchmark) | | ➕ 自由添加模型 | 支持15+主流 AI 服务商,也可自定义 API 端点(custom provider + preset templates) | | 📜 切换历史追溯 | 完整记录每次模型切换的时间与来源(switch history tracking) | | ↩️ 失败自动回滚 | 新模型5秒内无响应,自动回退到上一可用模型(optimistic update + 5s rollback) |
| 功能 | 说明 | |------|------| | 🔑 密钥加密存储 | API Key 经 Electron safeStorage 加密后写盘,杜绝明文泄露 | | 🛡️ IPC 权限沙箱 | 渲染进程无法直接调用系统 API,所有操作经白名单校验(IPC whitelist sandbox) | | 🧹 日志自动脱敏 | 日志中自动遮蔽 API Key、Token 等敏感信息(log sanitizer) | | 🔒 命令注入防护 | 所有外部命令使用参数数组传递,不拼接字符串(execFile/spawn with args array) |
| 功能 | 说明 | |------|------| | 📌 永远置顶 | 球体与字幕窗口始终位于最上层,不被其他窗口遮挡(always-on-top) | | 🖱️ 字幕穿透点击 | 歌词字幕窗口完全穿透鼠标事件,不影响底层操作(mouse-through transparent window) | | 🔗 自动创建桌面快捷方式 | 首次启动自动生成桌面快捷方式,下次双击即用(auto .lnk / .app creation) | | 📸 截图一键上传 | 工具栏一键截屏,自动上传至飞书(screenshot + Lark upload) | | 💬 多平台消息同步 | Discord / Telegram / 飞书 / 企业微信消息统一同步并语音播报(multi-channel message sync) | | 🍎 跨平台支持 | Windows 10/11 + macOS(Intel & Apple Silicon)双平台原生支持(cross-platform Electron) | | 📱 托盘菜单 | 右键系统托盘即可切换模型、查看状态、启动诊断、管理会话(system tray context menu) |
🩹 补丁更新! 修复 Hermes 兼容模式下两个容易误导用户的边界:没开 API server 时不再进入“能启动但不能聊”的半可用状态;只剩配置目录时也不再误判成“已安装 Hermes”。
/v1/chat/completions~/.hermes 目录但 CLI 缺失” 的假阳性回归测试,避免状态页再次误报🤝 正式适配 Hermes!
kkclaw gateway现在会按兼容后端模式工作:既能拉起 OpenClaw,也能驱动 Hermes,并在启动时提供 OpenClaw / Hermes / Auto 三种入口。
KKCLAW_COMPAT_MODE=hermes,也支持在 pet-config.json 中固定 compatMode: "hermes" | "openclaw" | "auto"kkclaw gateway / npm start 的终端入口现在会先让你选择兼容后端(OpenClaw / Hermes / Auto),并记住上次选择kkclaw status / kkclaw doctor / kkclaw gateway status 会显示当前兼容后端、CLI 路径、探活方式、日志路径、API Server 状态🦞 命令体验升级!
kkclaw gateway现在直接打开带开场动画的终端,并补齐doctor / status / logs / dashboard
kkclaw gateway 主入口 — 直接打开现在 npm start 的动画终端体验,启动习惯更接近原生命令行工作流kkclaw doctor — 增加 KKClaw 风格体检,检查兼容 CLI、Gateway 连通性、Dashboard 地址和进程归属kkclaw gateway status / logs / open / restart / stop — 提供贴近兼容后端工作流的子命令kkclaw dashboard — 直接转发到底层 openclaw dashboarddoctor 会提示当前 Gateway 端口是否由 KKClaw 自身占用,帮助排查旧进程/端口冲突⚡ 体验优化! Wizard 白屏修复 + 缺失依赖一键安装 + 跨平台支持
(CC-Switch 同步),未安装时提示安装命令new Notification() 添加 silent: true,阻止 Windows 系统朗读start.cmd,启动时显示 CMD 控制台 + Gateway 日志🎨 重大体验更新! 全局彩色终端日志 + Gateway 智能自启动 + 日志去重降噪 + 首次启动自动创建桌面快捷方式
startGateway()log() 方法在 stdout handler 之后二次 console.log(),gateway-std* 服务跳过控制台输出\s+ → ' ' 归一化后 Set 去重,彻底消除同内容重复