心屿 TIDEHOME

一只有长期记忆、会成长、能联机，也能住进 Windows 桌面的像素宠物伙伴。

心屿把 LangChain + DeepSeek 对话、短期/长期记忆、宠物养成、多玩家家园与小游戏、文件理解、实时天气和 Electron 桌宠放在同一个连续世界中。网页、世界地图、联机房间与桌宠共享同一只宠物和同一份用户数据。

四位初始伙伴

星铃幽灵	月芽猫	云莓狐	苔芽龙

轻盈、温柔、会发光	安静敏锐、带着月尾	活泼蓬松、喜欢云莓	好奇可靠、会守护嫩芽

每个角色包含严格隔离的 8 × 5 动作帧：待机、移动、被摸、进食和庆祝。所有帧均使用统一脚底锚点和透明安全边距，避免相邻动作残片进入画面。

环境要求：Node.js 22.13 或更高版本。

git clone https://github.com/yazyeah/tidehome-pet-agent.git
Set-Location 'tidehome-pet-agent'
Copy-Item '.env.example' '.env'
npm install

在 .env 中填写自己的服务端模型密钥：

DEEPSEEK_API_KEY=your_server_side_key

密钥只会由 Node.js 后端读取，不会进入网页包、桌宠渲染进程或数据库。

启动网页与伙伴服务：

npm run dev

启动包含透明置顶桌宠的完整桌面体验：

npm run dev:desktop

如果网页和伙伴服务已经运行，可单独启动桌宠：

npm run desktop

初始化中的邮箱是演示账号标识，不会发送真实邮件。输入邮箱后，六位“演示星邮验证码”会直接出现在当前页面。

首次入岛初始化：演示邮箱、独立玩家档案、玩家名、四种宠物、宠物命名、四种性格，以及 PDF/Word/Excel/PPT/TXT 初始记忆投喂与逐条确认。
LangChain + DeepSeek 流式中英文对话；角色、场景与安全边界均在服务端编排。
SQLite 多房间短期记忆与账户级长期记忆；聊天可新建、清空、删除和全部重置。
文件理解：聊天附件可以提取并处理 PDF、Word、Excel、PPT、CSV、Markdown 和文本内容。
完整养成：亲密、活力、饱食、清洁、健康、成长经验、等级、离线衰减、疾病和照料提醒。
五个像素场景、碰撞地图、鼠标寻路、键盘移动、星邮任务和四项进阶小游戏。
多玩家对抗、双人合作、玩家搜索、访问家园、双宠同屏、摸摸、喂食与一起玩。
八项实用技能：当前宠物实时自画像、专注守护、今日同行卡、天气侦察、记忆明信片、记忆检索、声音回信和世界向导；既可从技能背包点击，也可在聊天中用中英文自然语言调用。聊天会展示 SKILL.md 执行卡和真实结果。
Open-Meteo 实时天气与明确侦察完成反馈；支持浏览器定位、昼夜场景联动。
Electron 桌宠：拖动、点击落点飘移、迷你对话、照料、专注铃、剪贴板读取、隐藏/托盘恢复与八位配对码。
服务端用户隔离：其他玩家无法读取邮箱、内部用户 ID、聊天、文档、长期记忆或模型凭据。

四张 ImageGen 源图保存在 art/imagegen-sources/。整理脚本会清除生成预览底色、逐帧去除跨格残片、统一锚点，并验证 40 个单元的透明安全边界。

python -m pip install Pillow numpy
python scripts/prepare_sprite_sheets.py

输出位置：

public/pets/<pet-id>/sheet.png
public/pets/<pet-id>/preview.png

本地数据默认保存在 data/pet-memory.sqlite。.env、数据库、WAL、桌宠令牌和用户上传数据均被 Git 忽略。

演示服务器建议使用单个 Node.js 实例和持久卷，并配置：

若扩展为多实例高并发部署，建议把 SQLite 房间状态迁移至 PostgreSQL/Redis，并将联机轮询升级为 WebSocket。

npm run lint
npx tsc --noEmit
npm run benchmark:basic
npm run benchmark:skills
npm run benchmark:multiuser
npm run build

基础版交付门槛见 docs/BASIC_BENCHMARK.md。

本项目采用 MIT License。