喵币智 (maobizhi) — 使用介绍 & 安装指南
一只住在桌面上的猫系女友 Agent 🐱✨
目录
项目简介
喵币智是一个运行在 Windows / macOS 桌面上的猫系女友 Agent 宠物。它具备：
- 🧠 AI 灵魂模块 — 情境搭话、主动问候、自主意识、每日日记
- 🌐 浏览器控制 — 打开网页、搜索、填表、提取内容、截图
- 🖥️ 桌面控制 — 窗口管理、控件操作、按键鼠标模拟
- 📁 文件操作 — 读取/写入/修改白名单目录内的文件
- ⏰ 定时任务 — 天气播报、喝水提醒、日程通知
- 💾 长期记忆 — 记住主人的偏好和重要信息
- 🔧 Python 执行 — 直接运行 Python 代码完成计算、数据处理等任务
安装教程
方式一：一键安装（推荐）
脚本会自动完成：检测/安装 Python、下载源码、创建虚拟环境、安装依赖、创建桌面启动器、启动应用。
Windows
irm https://test.ryh123.xyz/catpet/install.ps1 | iex
需要 PowerShell 5.1+ 且网络可访问腾讯云/清华大学 PyPI 镜像（脚本会自动选择最快的镜像）。
macOS / Linux
curl -fsSL https://test.ryh123.xyz/catpet/install.sh | bash
macOS 首次运行会提示安装 Xcode Command Line Tools；脚本也支持 Homebrew 安装 Python。
安装后：
- 桌面会出现 Maobizhi.command（macOS）或直接弹出应用
- Linux 可通过
~/.local/bin/maobizhi命令启动 - 应用目录位于
~/maobizhi（或%USERPROFILE%\maobizhi）
更新： 重新运行同一安装命令即可（虚拟环境会被保留，仅更新源码）。
卸载： 删除安装目录 ~/maobizhi（或 %USERPROFILE%\maobizhi）及桌面启动器。
方式二：从源码手动安装
前置要求
- Python 3.9+（Windows 推荐通过 python.org 官网安装，勾选 “Add to PATH”）
- Git（用于 clone 仓库）
步骤
# 1. Clone 仓库
git clone <你的仓库地址> ~/maobizhi
cd ~/maobizhi
# 2. 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 3. 安装依赖
pip install -r requirements.txt
# macOS 额外安装：
pip install -r requirements-mac.txt
# Windows 额外安装（如有）：
pip install -r requirements-windows.txt
# 4. 启动
python maobizhi.pyw
方式三：PyInstaller 打包版
项目提供 build_exe.py，可将应用打包为独立 exe（Windows）或 app（macOS），无需用户本地安装 Python。
# 构建（在虚拟环境激活状态下）
python build_exe.py
# 输出目录：dist/maobizhi.exe（Windows）或 dist/Maobizhi.app（macOS）
打包时会自动将 runtime/python.exe 内嵌进 exe，确保子进程（run_python_code）也能正常运行。
AI 配置
喵酱需要接入大模型才能对话。有两种配置方式：
方式 A：启动后在对话框配置（推荐）
- 启动应用
- 点击菜单栏或设置按钮
- 填入以下信息：
-
API Key：你的 OpenAI / 兼容接口的 API Key -
Base URL：API 端点（如 https://api.openai.com/v1或国内代理地址） -
模型名：如 gpt-4o、claude-3-5-sonnet等
-
方式 B：环境变量
在启动前设置环境变量（优先级低于界面配置）：
| 变量名 | 说明 |
|---|---|
MAOBIZHI_API_KEY |
API 密钥 |
MAOBIZHI_API_BASE |
API 基地址 |
MAOBIZHI_MODEL |
模型名称 |
OPENAI_API_KEY |
兼容环境变量 |
OPENAI_BASE_URL |
兼容环境变量 |
支持的模型服务商
- OpenAI（gpt-4o、gpt-4、gpt-3.5-turbo）
- Claude（via OpenAI 兼容接口）
- 国内代理（DeepSeek、Moonshot、通义等）— 需设置对应 Base URL
功能一览
🐱 AI 灵魂模块
| 功能 | 说明 |
|---|---|
| 情境搭话 | 根据时间、系统状态、主人活动自动发起对话 |
| 主动问候 | 开机、空闲一段时间后主动打招呼 |
| 自主意识 | 记录心情、偏好、日常事件，形成连贯人格 |
| 每日日记 | 自动生成当日摘要，持久化记忆 |
| 情绪反馈 | 好感度 / 饥饿度 / 心情随互动变化 |
🌐 浏览器控制（agent_browser）
- 打开网页 / 搜索 / 填表 / 点击 / 滚动
- 提取文本、链接、表格、表单数据
- 截图存档（支持发送给聊天窗口预览）
- 多标签页管理
- 支持需登录的站点（手动登录一次，会话保留）
🖥️ 桌面控制（agent_desktop）
- 列出当前窗口 → 激活 → 读取控件树 → 点击/输入
- 截屏 + 坐标操作（适用于自绘/游戏界面）
- 剪贴板读写（需单独确认）
- 鼠标键盘模拟
📁 文件操作（agent_files）
- 读取白名单目录（桌面/文档/下载）内的文本文件
- 新建或覆盖文件（会请求授权）
- 精确替换文件片段（edit_file）
⏰ 定时任务（agent_cron）
daily：每天固定时间触发（如每日天气播报）interval：每隔 N 分钟触发（≥5 分钟）once：单次定时触发
💾 记忆系统（agent_memory）
- 保存重要事实、偏好、经验教训
- 自动去重，相似内容不重复保存
- 按关键词检索，按时间排序
架构说明
maobizhi.pyw ← 主入口，PyQt5 桌面应用
├── ai_chat.py ← AI 对话核心（LLM 调用、上下文管理）
├── pet_soul.py ← 猫系女友人格、情绪、情境搭话
├── pet_life.py ← 宠物生命周期（饥饿、心情、好感度）
├── agent_browser.py ← 浏览器自动化（Playwright）
├── agent_browser_daemon.py ← 浏览器后台守护进程
├── agent_desktop.py ← 桌面窗口/控件控制
├── agent_desktop_daemon.py ← 桌面控制守护进程
├── agent_files.py ← 文件读写操作
├── agent_memory.py ← 长期记忆（SQLite + 向量检索）
├── agent_cron.py ← 定时任务调度
├── app_state.py ← 应用状态持久化
├── mainlink.py ← 模块命名空间桥（支持 PyInstaller 打包）
└── companion.py ← 会话连接与消息路由
数据存放位置
| 类型 | 路径 |
|---|---|
| 应用源码 | %USERPROFILE%\maobizhi\app\ |
| 虚拟环境 | %USERPROFILE%\maobizhi\.venv\ |
| 持久化状态 | ~/.maobizhi\ 或应用目录下的 state.json |
| 日志 | maobizhi.log（项目目录下） |
| 记忆数据库 | ~/.maobizhi/memory.db |
常见问题
Q: 启动后没有窗口/闪退？
A: 检查是否已配置 AI API Key；查看 maobizhi.log 错误日志；尝试用 python maobizhi.pyw 直接在终端运行看报错信息。
Q: 浏览器功能无法使用？
A: 安装脚本会尝试自动下载 Chromium；若失败可手动运行 python -m playwright install chromium。
Q: 记忆不持久？
A: 确保 ~/.maobizhi/ 目录有写入权限；不要删除 memory.db。
Q: 如何更换 AI 模型？
A: 在设置对话框中修改模型名；或设置 MAOBIZHI_MODEL 环境变量。
Q: 一键安装脚本报网络错误？
A: 脚本会自动尝试多个国内 PyPI 镜像；若全部失败，可手动指定 PIP_INDEX 环境变量后重跑，或切换网络环境。
🐱 喵酱随时待命，有问题尽管问～