一只住在桌面上的聊天宠物 —— 默认形象是《明日方舟》的 Q 版基建小人 （焰影苇草·博物 / 浊心斯卡蒂 / 夕 / 年 等多套皮肤可随时切换，均带完整待机动画）。 它不只是个摆件：背后接入了 DeepSeek（或任何 OpenAI 兼容接口），带一套 完整的 agent loop，能聊天、能联网查询、能操作文档、还有长期记忆。
- 桌面宠物：透明无边框、始终置顶的小窗，可随意拖动；戳它会播放完整的交互动画，双击打开聊天；超过一小时没理它，它就躺下睡觉，任何交互随时唤醒。
- 完整 agent loop：流式回复 + 函数调用，模型自主决定调用工具、多步执行、再给出答案。
- 联网查询：
web_search+fetch_webpage（Bing 优先、DuckDuckGo 兜底，免 key），查时事、资料、天气。 - 文档操作：在工作目录读 / 写 / 追加 / 列出文件（记笔记、写草稿、整理文档）。
- 操作电脑：
run_shell执行 PowerShell 命令——查系统信息、跑脚本、管理文件/程序/进程， 带超时与输出截断；危险操作会先跟你确认（可用shell.enabled关闭）。 - 长期记忆：
remember / recall / list_memories / forget，跨会话记住你的偏好和约定。 - 定时激活：
set_reminder（几分钟后 / 某时刻 / 每天 / 每隔）本质是一次到点的 agent 激活，不只限于提醒——内容可以写得很宽泛（提醒用户、去看新闻、整理工作区…）。target=foreground到点由vpet亲自开口（和用户相关的事），target=background到点派一个后台 agent 独立去做；list_reminders查看、cancel_reminder取消，重启不丢。 - 后台 agent：前台只有一个会话 agent，但可以同时有多个后台分身：
start_background_agent派遣耗时任务（联网调研、整理工作区等），list_background_agents/stop_background_agent/read_background_report管理它们。后台 agent 能联网、能读写长期记忆、能在工作区写文件，但只能在工作区内活动、没有 shell，不会动你电脑上的其他东西；有进展时会主动给你捎消息（系统通知 + vpet亲口转达）。 - 定期自主活动：默认每 12 小时一次（可配、可关），vpet 在后台自由探索——上网看新闻、整理工作区、写日记（
workspace/journal/）、回顾记忆、安排后续激活，发现真正值得说的会捎话给你。像一个有自己的生活的个体。 - 后台记忆管家：连续 5 小时没有新消息，一个后台记忆 agent 会自动接手这段对话——用专门的 记忆工具把值得留的内容整理进长期记忆（查重、更新、合并、删除过时项，而不是只追加一条摘要）， 并开启新会话；每隔几段会话还会做一次深度反思，从全部记忆里归纳你的习惯与画像（阈值、频率可配、可关）。
- 设置面板（右键 → ⚙️ 设置）：配置 LLM 接入点 / API Key、测试连接并自动拉取 模型列表下拉选择；宠物名字、尺寸、皮肤；开机自动启动；后台 agent 开关与自主活动间隔。保存后立即生效，无需重启。
- 系统托盘：聊天、显隐宠物、设置、退出。
- 运行
installer_out/VPetSetup.exe（构建方式见下文「📦 打包」），按向导安装。 - 首次启动会自动弹出设置窗口：填入接入点和 API Key，点「测试连接」， 从下拉框选模型，保存即可。
pip install -r requirements.txt
python main.py首次运行会在桌面右下角出现vpet，双击它开始聊天（或右键 → 💬 聊天）。
API key 也可以在
~/.vpet/config.json里改，或设环境变量DEEPSEEK_API_KEY（环境变量优先于界面设置）。
程序本体（安装目录 / 项目目录）只放代码和立绘，所有运行数据都在 home 目录， 重装、换机不影响：
~/.vpet/
├── config.json # 配置：API key、模型、宠物名字/尺寸、阈值…
├── data/
│ ├── memory/ # 长期记忆（JSON + 自动生成的 MEMORY.md）
│ ├── sessions/ # 当前会话
│ ├── reminders.json # 定时激活（前台/后台）
│ └── background/ # 后台 agent 的工作记录与收件箱
└── workspace/ # 宠物操作文档的默认目录（后台 agent 的活动范围也仅限这里）
从旧版本升级：首次启动会自动把项目目录下的
config.json、data/、workspace/迁移到~/.vpet/。
| 键 | 说明 | 默认 |
|---|---|---|
deepseek.base_url |
OpenAI 兼容接口接入点 | https://api.deepseek.com |
deepseek.model |
聊天模型 | deepseek-chat |
pet.name |
宠物名字 | vpet |
pet.size |
宠物尺寸(px) | 100 |
pet.always_on_top |
是否置顶 | true |
session.idle_timeout_hours |
空闲多久触发后台记忆整理 | 5 |
session.max_history_messages |
上下文保留的消息数 | 60 |
paths.workspace |
文档操作的默认目录（相对 ~/.vpet） |
workspace/ |
agent.max_iterations |
单轮最多工具调用步数 | 10 |
shell.enabled |
是否允许 run_shell 执行 PowerShell 命令 | true |
shell.timeout_seconds |
命令超时秒数（超时强杀） | 60 |
curator.enabled |
是否启用后台记忆管家（false 则回退一次性摘要） | true |
curator.max_iterations |
记忆管家单次整理最多工具步数 | 12 |
curator.reflect_every_sessions |
每隔几段会话做一次深度反思（习惯/画像） | 3 |
background.enabled |
是否启用后台 agent（后台激活 / 前台派遣任务） | true |
background.max_iterations |
后台 agent 单次任务最多工具步数 | 12 |
background.max_concurrent |
同时运行的后台 agent 上限（超出的排队） | 2 |
background.autonomous_enabled |
是否开启定期自主活动 | true |
background.autonomous_interval_hours |
定期自主活动间隔（小时） | 12 |
带 ⚙️ 的常用项（接入点 / key / 模型 / 名字 / 尺寸 / 开机启动）建议直接在 设置面板里改，保存即生效。
pip install pyinstaller
winget install JRSoftware.InnoSetup # 可选，只做绿色版可跳过
python build.py # 完整构建：dist/VPet/ + VPetSetup.exe
python build.py --app-only # 只打包 dist/VPet/（绿色免安装）dist/VPet/是绿色版，整目录拷走即可运行（数据仍在~/.vpet）。installer_out/VPetSetup.exe是安装程序：免管理员安装到%LOCALAPPDATA%\Programs\VPet，可选桌面快捷方式 / 开机启动。- 卸载只删程序本体，
~/.vpet里的记忆和配置会保留。
你说一句话
└─> DeepSeek 流式生成
├─ 决定调工具 ─> 本地执行(联网/文件/记忆) ─> 结果喂回模型 ─> 继续生成（可多步）
└─ 生成最终回复 ─> 流式显示在聊天窗 & 宠物头顶气泡
- agent 核心：
vpet/agent.py（对话状态、工具调用循环、历史裁剪、会话重置） - 工具：
vpet/tools.py（文件/联网/记忆/提醒/命令等工具的 schema + 本地执行，文件操作沙箱在~/.vpet/workspace/；run_shell在 Windows 上走 PowerShell） - 记忆：
vpet/memory.py（JSON + 自动生成的MEMORY.md，关键词检索，支持增删改） - 记忆管家：
vpet/curator.py（后台记忆 agent——空闲时用记忆工具整理对话、查重/更新/合并， 并定期纵观全部记忆做深度反思、归纳用户习惯与画像） - 后台 agent：
vpet/background.py（后台分身管理器——定时后台激活、前台派遣的耗时任务、 定期自主活动都是它跑的 agent loop；文件操作强制限制在工作区内、无 shell；工作记录与给用户的 捎话持久化在data/background/，由vpet/brain.py中继到前台会话） - 会话：
vpet/session.py（5 小时空闲判定）+vpet/brain.py（定时检查、触发后台记忆整理、 路由前/后台定时激活、中继后台消息、调度定期自主活动） - 界面：
vpet/ui/（PySide6：宠物窗 / 聊天窗 / 气泡 / 设置），vpet/brain.py用 Qt 信号把 跑在工作线程上的 agent 安全接到界面。
默认形象是《明日方舟》的 Q 版基建小人皮肤（assets/skins/，© Hypergryph，仅个人
自用）：焰影苇草·博物、浊心斯卡蒂（原皮/升华）、夕（原皮/染尘烟）、
年（原皮/乐逍遥）。动画只用基建动画三件套：待机 Relax、点击 Interact
（完整播完一次，不被打断）、一小时无交互后睡觉 Sleep。
- 换皮肤：右键 → ⚙️ 设置 → 皮肤 下拉，即时生效。
- 加皮肤：用渲染管线
tools/spine_render/render_skins.py（从 PRTS 拉取 Spine 模型 烘焙序列帧），或按assets/ASSETS.md的目录结构手工放图。 - 一套皮肤都没有时，程序回退到内置的程序绘制占位形象。
- （旧版默认形象 FF14「外勤机」已退役，历史素材仍保留在
assets/source/。）
见 AGENTS.md（CLAUDE.md 引用了同一份内容）。最重要的一条：
任何后台 LLM 任务都做成带工具的 agent loop，而不是一次性 llm.complete()——
vpet/curator.py（记忆管家）是模板。
python tests/test_settings.py # 设置面板/配置存取/开机启动/真实拉模型列表
python tests/test_backend.py # 端到端打真实 DeepSeek：聊天/联网/记忆/文件/5h记忆整理
python tests/test_curator.py # 后台记忆管家（脚本化假 LLM，无网络）：增删改/反思节奏/会话交接
python tests/test_background.py # 后台 agent（脚本化假 LLM，无网络）：工具loop/沙箱/停止/收件箱/自主激活/路由
python tests/test_shell.py # run_shell 命令执行（真实安全子进程 + 假 LLM 接线，无网络）
python tests/test_gui_render.py # 离屏渲染宠物与聊天窗，输出到 tests/_render_out/
python tests/test_skins.py # 皮肤系统：目录扫描/发现顺序/元数据/别名/按帧率播放
python tests/test_ui_fixes.py # UI 回归（离屏无网络）：气泡/滚动/位置记忆与持久化
python tests/test_app_smoke.py # 整机装配冒烟测试├── main.py # 入口：装配后端 + 界面 + 托盘
├── config.py # 配置加载/保存（~/.vpet 数据根、旧数据迁移）
├── config.example.json # 配置模板（真实配置在 ~/.vpet/config.json）
├── build.py # 打包脚本（PyInstaller + Inno Setup）
├── installer.iss # Inno Setup 安装包脚本
├── tools/make_icon.py # 生成应用图标 assets/icon.ico
├── tools/spine_render/ # 皮肤渲染管线：PRTS Spine 模型 → 序列帧皮肤（见 ASSETS.md）
├── vpet/
│ ├── llm.py # DeepSeek 客户端（流式 + 工具调用 + 模型列表）
│ ├── agent.py # agent loop 核心
│ ├── curator.py # 后台记忆管家（空闲整理记忆 + 定期反思习惯/画像）
│ ├── background.py # 后台 agent 管理器（后台激活/派遣任务/定期自主活动）
│ ├── tools.py # 文件/联网/记忆/定时激活/后台管理/命令 工具
│ ├── memory.py # 长期记忆存储（线程安全，前后台共享）
│ ├── reminders.py # 定时激活调度存储（前台/后台 target）
│ ├── session.py # 5 小时空闲会话管理
│ ├── brain.py # Qt 信号桥 + 工作线程 + 定时检查
│ ├── autostart.py # 开机启动（注册表 Run 键）
│ ├── prompts.py # 人设 / 系统提示词
│ └── ui/ # pet_window / chat_window / bubble / settings_dialog
├── assets/
│ ├── ASSETS.md # 皮肤目录规格 + 渲染管线用法 ★
│ ├── source/ # 设计基准图 / 预览图（含退役的外勤机素材）
│ ├── skins/ # 序列帧皮肤（render_skins.py pack 产物，打包进 exe）
│ └── sprites/ # 旧默认皮肤目录（外勤机已退役，通常为空）
└── ~/.vpet/ # 运行数据（见上文「数据目录」）
- 形象灵感来自 FF14「外勤机」，代码与素材均为原创实现，仅供学习交流。
- API key 保存在
~/.vpet/config.json，请妥善保管，别提交到公开仓库。