# hermes-petdex

**Repository Path**: code_from_qh/hermes-petdex

## Basic Information

- **Project Name**: hermes-petdex
- **Description**: hermes-petdex：一个专注于宠物信息管理的开源项目，提供高效的数据查询和管理功能，支持多种宠物数据源，旨在为开发者和宠物爱好者提供便捷的工具。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-17
- **Last Updated**: 2026-06-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🐱 Hermes Petdex — 桌面宠物联动

让你的 [Hermes Agent](https://github.com/NousResearch/hermes-agent) 拥有一只浮动桌面宠物，实时反映 Agent 工作状态。

基于 [Petdex](https://github.com/crafter-station/petdex)（2926 只社区精灵），无需登录即可使用。

![demo](https://img.shields.io/badge/platform-macOS-lightgrey) ![python](https://img.shields.io/badge/python-3.11+-blue) ![license](https://img.shields.io/badge/license-MIT-green)

## ✨ 特性

- 🎬 **自动联动**：bash 钩子捕获终端命令，宠物自动切换动画
- 🎮 **手动控制**：一行命令控制宠物状态和气泡消息
- 📦 **免登录安装**：从 Petdex 画廊直接下载任意宠物，无需 Clerk OAuth
- 🧠 **Hermes Skill**：加载后 Agent 主动驱动宠物
- 🛡️ **安静失败**：钩子出错绝不污染终端输出

## 🚀 快速开始

```bash
# 1. 安装 Petdex 桌面应用（一次性）
npx petdex init --yes  # 或 npx petdex install desktop

# 2. 安装本项目
git clone https://gitee.com/yourname/hermes-petdex.git
cd hermes-petdex
bash install.sh

# 3. 安装一只宠物
python3 scripts/petdex-install.py boba

# 4. 选中并启动
npx petdex select boba
npx petdex desktop start

# 5. 重启 Hermes 生效 bash 钩子
```

## 📁 项目结构

```
hermes-petdex/
├── scripts/
│   ├── petdex-notify.py    # 核心：状态/气泡控制
│   ├── petdex-install.py   # 免登录宠物安装器
│   └── petdex-watch.py     # Bash 钩子处理器（自动联动）
├── skill/
│   └── SKILL.md            # Hermes Agent Skill
├── doc/
│   └── guide.md            # 保姆级操作指南
├── install.sh              # 一键安装
├── Makefile                # 快捷命令
└── README.md
```

## 🎮 使用

### 手动控制

```bash
# 状态切换
python3 scripts/petdex-notify.py state running   # 工作中
python3 scripts/petdex-notify.py state review    # 思考中
python3 scripts/petdex-notify.py state jumping   # 兴奋跳起
python3 scripts/petdex-notify.py state failed    # 出错了
python3 scripts/petdex-notify.py state waving    # 挥手道别
python3 scripts/petdex-notify.py state idle      # 休息

# 气泡消息
python3 scripts/petdex-notify.py bubble "正在分析代码..."

# 查看状态
python3 scripts/petdex-notify.py status
```

### 安装宠物

```bash
# 搜索（2926 只可选）
python3 scripts/petdex-install.py --list cat
python3 scripts/petdex-install.py --list 龙

# 安装
python3 scripts/petdex-install.py doraemon

# 随机盲盒
python3 scripts/petdex-install.py --random

# 切换（自动重载桌面）
npx petdex select doraemon
```

### 自动联动（bash 钩子）

`install.sh` 会自动在 `~/.bashrc` 中添加 DEBUG trap。之后 Hermes 每次执行 terminal 命令时，宠物自动切换到 running 状态。

```bash
# 暂停钩子
touch ~/.petdex/runtime/hooks-disabled

# 恢复钩子
rm ~/.petdex/runtime/hooks-disabled
```

### Hermes Skill

在 Hermes 中加载 skill：

```bash
hermes -s petdex
```

或通过 `install.sh` 自动安装到 `~/.hermes/skills/petdex/`。

## 🔧 依赖

| 依赖 | 用途 | 安装 |
|------|------|------|
| Petdex Desktop | 浮动窗口渲染引擎 | `npx petdex install desktop` |
| Python 3.11+ | 桥接脚本 | macOS 自带或 `brew install python@3.11` |
| Node.js / npx | Petdex CLI | 通常已安装 |

## 🏗️ 架构

```
Hermes Agent (terminal tool)
    │  bash DEBUG trap
    ├──→ petdex-watch.py ──HTTP POST──→ Sidecar (localhost:7777)
    │                                      │
    │ (可选) Hermes Skill                   ▼
    └──→ petdex-notify.py ──HTTP POST──→ Petdex Desktop (Zig + WebKit)
                                           │
                                           ▼
                                    桌面浮动动画窗口
```

## 🪟 Windows WSL 部署

WSL 内运行 Hermes，Windows 侧运行桌面浮动窗口，通过 `localhost` 桥接。

### 架构

```
Windows 侧                          WSL 侧
┌──────────────────────┐      ┌──────────────────┐
│ petdex-desktop.exe   │      │ Hermes Agent     │
│ (Tauri 浮动窗口)      │      │ petdex-*.py      │
│ Sidecar :7777        │◄────│ bash DEBUG trap  │
└──────────────────────┘ HTTP └──────────────────┘
         localhost 共享 (WSL2 自动)
```

### 部署步骤

```powershell
# 1. Windows 侧 — 安装桌面应用（PowerShell / cmd）
npx petdex install desktop
npx petdex desktop start

# 2. WSL 侧 — 安装本项目
git clone https://gitee.com/yourname/hermes-petdex.git
cd hermes-petdex
bash install.sh

# 3. WSL 侧 — 安装宠物
python3 scripts/petdex-install.py boba

# 4. Windows 侧 — 选中并重启
npx petdex select boba
npx petdex desktop stop && npx petdex desktop start

# 5. WSL 侧 — 启动 Hermes
hermes -s petdex
```

### 注意事项

| 问题 | 解决 |
|------|------|
| 宠物文件路径 | 让 `npx petdex` 在 **Windows 侧** 全权管理宠物（install/select），WSL 脚本只负责发 HTTP 通知 |
| localhost 不通 | WSL2 默认共享 localhost。如果不行：`wsl --shutdown && wsl` 重启 WSL |
| Python 版本 | WSL 通常自带 Python 3，如遇 SSL 问题用 `curl` 版 petdex-install.py |
| 其他 | 脚本、skill、bash 钩子完全零改动——WSL 就是 Linux |

## 📖 完整文档

见 [`doc/guide.md`](doc/guide.md) — 包含故障排查、进阶玩法、自制宠物教程。

## 📄 License

MIT — 详见 [LICENSE](LICENSE)。

Petdex 源码同样为 MIT，宠物资源版权归各自提交者所有。