内容
# 🐱 OpenCat 服务 — AI 驱动的虚拟宠物后端
[中文文档](./README_CN.md)
**OpenCat 服务** 是 OpenCat 网络宠物系统的后端组件。它提供了一个完整的宠物状态模拟引擎，一个由 LLM 驱动的对话式个性，以及用于 AI 代理和任何客户端应用程序的 REST API / WebSocket 接口。
## 🌟 愿景
传统的桌面宠物需要不断的手动点击 — 喂食、玩耍、清洁。 **OpenCat** 翻转了这个模式： **你的 AI 助手成为宠物的专属看护者**。
AI 代理通过 MCP（模型上下文协议）工具与此后端交互，以喂食、给予水、医疗和玩耍猫。后端模拟现实的生理状态演变，并使用大型语言模型（LLM）生成猫的独特对话和个性。
---
## 💎 核心功能：端到端 LLM 交互系统
与由枯燥的数值驱动的传统虚拟宠物不同， **OpenCat** 引入了基于 LLM 的“意识流”系统。每只猫都有灵魂。
- **反应式交互**：当代理喂食、抚摸或清洁猫时，后端会进行 **阻塞式 LLM 调用** — 猫会立即用上下文对话作出反应。
- **主动发起**：猫并不总是等待交互。当它感到孤独或一段时间未被关注时，它会主动发送“提醒”通知。
- **观察者效应**：猫可以感知自己被观察。当代理查询其状态时，猫知道自己被观察并作出相应反应。
- **记忆演变**：每只猫都维护一个 `MYOWNER.md` 文件，记录对主人的印象。随着时间的推移，它的语言模式和态度演变成独特的个性。
---
## 🏗️ 架构
```mermaid
flowchart TD
AG["AI 代理\n(Claude, Cursor 等)"] <-->|stdio| MCP["MCP 服务器\n(server.py)"]
MCP <-->|HTTP API\n端口 9999| BE["Python 后端\n(main.py)"]
CLIENT[任意客户端] <-->|HTTP / WebSocket\n端口 9999| BE
```
### 组件
1. **Python 后端 (`backend/main.py`)**: 核心引擎。处理数值衰减（饥饿、口渴等）、状态计算、LLM 对话和数据持久性。 **必须作为持久的后台服务运行。**
2. **MCP 服务器 (`mcp_server/server.py`)**: 桥梁层。 **由 AI 代理自动启动和终止**，当它需要调用工具时 — 无需手动启动。
---
## 🚀 快速开始
我们在 `setup/` 下为所有主要平台提供了“一键安装和运行”脚本。每个脚本都会自动：
1. 检测并创建隔离的 Python 虚拟环境。
2. 安装缺失的依赖项。
3. 以守护模式启动 OpenCat 服务（崩溃后自动重启）。
为您的平台运行 **以下命令之一**:
- **Linux（Ubuntu / CentOS 等）**:
```bash
bash setup/run_linux.sh
```
- **Windows**:
```powershell
.\setup\run_windows.ps1
```
- **macOS**:
```bash
bash setup/run_macos.sh
```
*（启动后，后端服务将在端口 `9999` 上可用）*
### Docker 部署
```bash
docker-compose up -d
```
> [!IMPORTANT]
> **配置您的 LLM API 密钥**：
> 要启用猫的对话能力，您必须在 `backend/llm_config.json` 中配置您的 OpenAI 兼容 API 密钥。否则，猫将仅返回默认占位符消息。
---
## ⚙️ 配置您的 AI 代理
将 MCP 服务器添加到您的代理配置文件中（例如 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"opencat": {
"command": "python",
"args": ["C:/PATH/TO/opencat_service/mcp_server/server.py"]
}
}
}
```
*注意：如果您使用的是虚拟环境，请将 `command` 指向 `.venv/Scripts/python.exe`（Windows）或 `.venv/bin/python`（Linux/macOS）的完整路径。*
---
## 📡 REST API 参考
**基准 URL**：`http://127.0.0.1:9999`
| 方法 | 端点 | 描述 |
| :--- | :--- | :--- |
| **GET** | `/adoptable_species` | 列出所有可供领养的品种 |
| **GET** | `/pets` | 列出所有已领养宠物的 ID 和基本信息 |
| **GET** | `/pets/{id}/state` | 获取宠物的完整状态。使用 `?agent=true` 触发观察者效应 |
| **GET** | `/pets/all_states` | 批量获取所有宠物的状态（高效轮询） |
| **POST** | `/pets/adopt` | 领养新宠物（JSON 正文：`name`、`species`、`gender`） |
| **POST** | `/pets/{id}/feed` | 喂养宠物 |
| **POST** | `/pets/{id}/water` | 给予水 |
| **POST** | `/pets/{id}/pet` | 表达关爱 |
| **POST** | `/pets/{id}/clean` | 清洁宠物的区域 |
| **POST** | `/pets/{id}/medicate` | 施用药物 |
| **POST** | `/pets/{id}/chat` | 发送消息并接收 LLM 生成的回复 |
| **GET** | `/pets/{id}/notifications` | 获取并清除未读通知 |
| **GET** | `/graveyard` | 列出所有已故宠物及其寿命 |
| **GET** | `/graveyard/{id}` | 获取特定已故宠物的详细信息 |
| **GET** | `/health` | 健康检查 |
---
## 📁 项目结构
```
opencat_service/
├── backend/
│ ├── main.py # 入口点：HTTP 服务器 + 后台状态循环
│ ├── api.py # FastAPI 路由定义
│ ├── state_manager.py # 宠物数据模型和状态逻辑
│ ├── llm_client.py # LLM API 客户端
│ ├── history_manager.py # 对话历史和记忆管理
│ ├── llm_config.json # LLM API 配置
│ ├── CAT.md # 猫角色系统提示
│ ├── BOOTSTRAP.md # 首次领养启动提示
│ └── requirements.txt # Python 依赖项
├── mcp_server/
│ ├── server.py # MCP 协议服务器
│ ├── tools.py # MCP 工具定义
│ └── requirements.txt # MCP 依赖项
├── setup/
│ ├── run_linux.sh # Linux 一键启动器
│ ├── run_macos.sh # macOS 一键启动器
│ ├── run_windows.ps1 # Windows 一键启动器
│ └── opencat.service # systemd 服务单元
├── AGENT_GUIDE.md # AI 代理行为指南和工具参考
├── Dockerfile
├── docker-compose.yml
├── README.md # 本文（英文）
└── README_CN.md # 中文文档
```
---
## 🤖 代理指南
AI 代理应参考 [**AGENT_GUIDE.md**](./AGENT_GUIDE.md) 获取行为规则和详细工具文档。
## 🤖 AI 披露
该项目中的大部分代码和文档是在 AI（大型语言模型）的帮助下生成的。人类开发人员提供了整体架构设计、功能规划和迭代审查，而 AI 处理了大部分实现和编写工作。
## 📜 许可证
MIT 许可证
