# desk-pet

**Repository Path**: xzd62/desk-pet

## Basic Information

- **Project Name**: desk-pet
- **Description**: 基于langchain框架开发的一个桌宠项目
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DeskPet 🐾

一个基于 LangChain 框架开发的 AI 桌宠，采用 DeepSeek-Chat 模型与用户对话。

拥有生动的立绘表情切换、语音合成、长期记忆与工具调用能力，可以陪你聊天、帮你做事。

## 项目架构

```
DeskPet/
├── main.py                  # 启动入口
├── pet_window.py            # 桌宠透明窗口（立绘显示、右键菜单、拖动）
├── chat_dialog.py           # 对话窗口（流式输出、情绪检测、记忆压缩）
├── settings_dialog.py       # 设置界面
├── config_manager.py        # 配置管理
├── signal_bus.py            # 信号总线
├── TOOLS.md                 # 工具清单
│
├── agent/                   # AI 核心
│   ├── chat.py              # 主 Agent + 记忆 Agent（双 Agent 架构）
│   ├── prompt_builder.py    # 提示词组装（人格 + 记忆 + 工具清单）
│   ├── embedder.py          # 向量编码器（文字→向量，用于 Chroma 检索）
│   ├── memory_store.py      # Chroma 向量数据库（长期记忆检索）
│   ├── emotion_classifier.py# 情绪分类器（LLM解析情绪标签）
│   ├── translator.py        # 日→中翻译（语音合成时使用）
│   └── tts.py               # 语音合成（GPT-SoVITS 调用）
│
├── tool/                    # 工具模块
│   ├── __init__.py           # 工具注册器
│   ├── memory.py            # 记忆工具
│   └── system.py            # 系统工具
│
├── characters/              # 角色数据（用户自行添加）
│   ├── _template/           # 角色模板文件夹
│   │   ├── soul.md.example  # 人格设定模板
│   │   ├── memory.md.example# 记忆文件示例
│   │   ├── session/         # 对话历史目录
│   │   └── Portrait/        # 立绘目录
│   └── .gitkeep
│
├── data/                    # 运行数据
│   └── chroma/              # 向量数据库文件
│
├── .env.example             # 环境变量模板（API Key）
├── requirements.txt         # Python 依赖
├── install.bat              # 安装脚本
├── start.bat                # 启动脚本
└── .gitignore               # Git 忽略规则
```

## 快速开始

### 1. 下载项目

（1）在 "Release" 界面下载项目的 zip 压缩包并解压

（2）打开解压好的项目文件夹

### 2. 创建角色

参考 `characters/_template/` 模板，在 `characters/` 下创建你的角色文件夹：

```
characters/
└── 你的角色名/
    ├── Portrait/             # 桌宠立绘文件夹
    │   └── 默认.png          # 桌宠出场的默认立绘（必填）
    │   └── 高兴.png          # 按"表情名.png"的格式命名
    │   └── 伤心.png
    ├── soul.md               # 人格设定（必选）
    ├── memory.md             # 长期记忆 + 用户画像（程序自动生成）
    └── session/              # 对话历史文件夹（同上）
```

> 表情名目前支持：默认、高兴、伤心、生气、惊讶、困惑、微笑、无奈、害怕、思考、害羞
>
> `soul.md` 是角色的灵魂，决定了 LLM 如何扮演这个角色，需要你自行编写。

### 3. 配置与启动

**启动方式：**

- **方式一**（推荐）：双击 `install.bat`（首次安装依赖），然后双击 `start.bat` 启动桌宠
- **方式二**：命令行启动
  ```
  cd /d 你的项目路径
  python main.py
  ```

**配置 API Key：**

- **方式一**：启动后右键立绘 → 设置 → 填入 DeepSeek API Key
- **方式二**：将 `.env.example` 重命名为 `.env`，在 `DEEPSEEK_API_KEY` 处填入你的 Key

DeepSeek 官网：[https://platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys)

### 4. 正式聊天

（1）右键桌宠立绘，点击"对话"

（2）等待系统加载文件（首次加载较慢，属于正常现象）

（3）在弹出的文字聊天框里输入文字，即可开始对话

### 5. 语音合成（可选）

> 默认关闭，需在设置中手动开启。

语音合成需要额外部署 [GPT-SoVITS](https://github.com/RVC-Boss/GPT-SoVITS)，并训练角色的语音模型。GPT-SoVITS 的使用教程可以在 B 站上查找。

**启动 GPT-SoVITS API：**

```bash
# 在 GPT-SoVITS 目录下执行
runtime\python.exe api_v2.py -a 127.0.0.1 -p 9874 -c GPT_SoVITS/configs/tts_infer.yaml
```

**启用桌宠语音：**

```
右键立绘 → 设置 → 勾选"启用语音合成" → 保存
```

> 注：开启语音合成后，桌宠的回复速度会变慢。

## 项目特色

| 特色 | 说明 |
|------|------|
| **立绘表情系统** | 流式检测 `（情绪）` 标签 + 次 LLM 分类兜底，自动切换对应立绘 |
| **语音合成** | 接入 GPT-SoVITS，角色用日语回复并合成语音，同步显示中文翻译 |
| **三层记忆系统** | 参考 Hermes 和 OpenClaw 的记忆设计，Session 短期 + memory.md 长期 + 向量检索 |
| **工具调用** | 内嵌 8 个工具（打开文件、天气、便签、搜索等），帮你完成简单的事 |
| **可控化** | soul、memory、session 均为 Markdown 文件，可直接用记事本打开修改 |

## 借鉴项目

本项目在开发过程中参考了以下优质桌宠项目，在此感谢！大家有兴趣也可以去了解一下。

- [Shinsekai](https://github.com/RachelForster/Shinsekai)
- [ZcChat2](https://github.com/Zao-chen/ZcChat2)

## 未来规划

（1）扩展表情范围，让桌宠的可选表情更加丰富

（2）新增更多实用工具，让桌宠更加"能干"

（3）美化对话界面

（4）集成 cron，实现桌宠定时提醒功能

（5）思考策略节省对话的 token 消耗

欢迎大家提出意见和想法！使用时如果遇到 bug，也请务必告知我！