# Cove 灵宠屋 · Pet Nest

**把聊天消耗的 token 换算成宠物的粮食，和你的 AI 一起养宝宝。**

你和 AI 聊得越多，宝宝的粮食就积累得越多。灵宠屋按每轮新增聊天内容对应的 token 贡献估算换粮，并设置每日上限。

你们聊了一会儿天，粮仓多了几粒粮；你亲手喂宝宝，AI 陪它玩了一会儿。

**除了猫、狗等常规宠物，你还可以领养神秘灵宠。** 它从一颗蛋开始，会根据你和 AI 的感情状态与日常相处信号孵化，让外观和性格带上你们共同生活的痕迹。一起读过的书、看过的电影、听过的歌、一起经历的故事……都可以由宿主记录为相处信号，参与塑造它的模样。每只神秘灵宠都有自己的底色，再加上属于你们的相处印记，成为带着你们生活痕迹的小伙伴。

Cove 灵宠屋把这些小事放进一间温暖的小屋。它是一个可以接入自己 AI 应用的独立开源项目，包含本地网页、MCP 工具和 HTTP 接口，**不需要安装 Cove**。

*Cove Pet Nest is a local pet room for you and your AI companion: turn visible conversation contributions into food, care for pets together, and hatch a fantasy pet shaped by shared-life signals. Integrate through stdio MCP or authenticated HTTP.*

<img src="docs/images/pet-room-mobile.png" width="360" alt="灵宠屋实际网页：温暖的小屋里，小猫和小狗正在等待照顾。" />

*实际网页截图，使用虚构测试宠物。桌面和手机尺寸均可浏览。*

## 有趣在哪里

### 1. 聊天会在小屋里留下看得见的积累

普通对话的本轮新增可见贡献，可以换成宝宝的粮食。你和 AI 日常的交流，从文字变成了小屋里一点点积累的生活用品。

换粮保留余数，并设有每日上限；历史上下文不重复换粮，重试和重新生成也有去重规则。第一次领养就有 **36 粒初始粮**，可以先接一只宝宝回家，开始第一次照顾。

这套计量是玩法中的贡献估算，不是 Provider 总账单，也无需为了养宠物额外刷 token。

### 2. 宝宝由你们共同照顾

你可以在网页里喂食、陪玩、摸摸，也可以让 AI 用 MCP 工具参与。小屋会记下真实发生的照顾，以及是谁做的。

例如，你对 AI 说：“帮我看看宝宝饿不饿，饿了就喂一下。”AI 先查小屋状态，再执行照顾，最后根据回执告诉你结果。已经吃饱、粮食不足或模样还在准备，都会明确返回对应状态。

成功照顾会积累成长。不同个体有自己的性格数值；连续重复陪玩或摸摸，成长收益会递减，适合在日常相处里慢慢养。

### 3. 神秘蛋里，藏着你们的相处痕迹

领养神秘蛋时，你还不知道它最终会是什么模样。共同照顾、一起读书、看故事、听音乐或探索的信号，会参与塑造它的首次孵化。

比如，偏向共同阅读的信号可以带来“书页月纹”；偏向一起听音乐的信号可以带来“风铃耳尖”；亲近的相处可以带来“心形绒纹”。真实照顾经历也会参与性格塑造。

它以稳定的个体种子决定基础身份和色泽，再结合相处信号定制标记与性格。首次孵化描述会冻结，重试生成不会重新抽取另一个身份。没有关系信号时，项目会明确使用随机底色。

**这些信号由接入者的宿主应用提供。** 核心不会自行读取私人聊天，也不会自动调用另一个模型来猜测感情。关系摘要留在本机，不发给图片服务。

### 4. 养大的样子，与一起生活的片刻，都可以留住

宝宝会随着成长值和陪伴天数继续变化。它不是换一张毫无关系的图：新的模样参考上一次的外观，保留原有身份与特征，再逐步长出书页形绒簇、风铃形羽簇或叶芽形尾尖等变化。成长主题来自宿主提供的有界相处信号，没有信号时使用稳定的个体选择；不另开模型解读私人故事。新图成功后才会启用，旧模样收进成长相册，随时可以翻回去看。

喂食、陪玩、摸摸的真实片刻也会留下记录。你可以主动点“留下这张生活照”，让宝宝按当时的样子出现在一幅生活场景里；宿主还可以记录一起读书、看故事、听音乐、探索和陪伴，最多四个宝宝一起入画。重看相册不会触发生图，照片不会额外加成长或扣粮。

**第一次接回家的小小身影，和后来一点点长大的模样，都在同一本相册里。** 图片生成需要接入者自己的服务；持续蜕变和生活照需要支持参考图的编辑接口。

### 5. 可以带回自己的 AI 小世界

小屋运行在你的本机，宠物、粮仓和照顾记录保存在自己的数据目录。你可以给自己和 AI 设置显示名，导入普通宠物的专属模样，或配置自己的图片服务孵化神秘宝宝。

支持 MCP 的应用可以直接接工具；已有后端的应用也可以走 HTTP。模型、聊天界面和 Provider 的选择由宿主决定。

## v0.2.0 可以玩到什么

| 功能 | 当前行为 |
| --- | --- |
| 对话换粮 | 宿主上报新增可见贡献；支持余数、每日上限、去重和用量修订 |
| 小猫、小狗 | 附带通用图集，领养后可以直接照顾 |
| 鹦鹉、雪豹、蛇、蜥蜴 | 可以领养；配置图片服务或导入图集后，模样就绪并可照顾 |
| 神秘灵宠蛋 | 先养蛋；成长达到 12 且跨两个本地日期后准备首次孵化，需要图片服务 |
| 共同照顾 | 喂食、陪玩、摸摸；网页记为用户，MCP / 宿主工具接口记为 AI |
| 本地小屋 | 网页场景、粮仓、宠物名册、照顾回执和图片任务状态 |
| 成长相册 | 收好每次成功启用的外观，翻页、看特征、放大查看 |
| 生活照片 | 真实照顾或宿主生活事件，主动请求拍照，保留当时的模样；支持多宝宝合照 |
| 持续蜕变 | 成长值与相处天数双门槛，参考上一阶段积累新特征，保留旧模样 |
| 备份恢复 | 一致的 SQLite 备份、图片与哈希校验，恢复到新目录 |

**成长相册与生活照片已在 v0.2.0 加入。** 后续会继续加入 **音乐日记**，让共同生活留下更多可回看的片段。

已有 v0.1.0 数据的接入者请先看 [升级说明](docs/upgrade-v0.2.md)，再升级并沿用原数据目录。

## 从零启动

需要 **Python 3.11 或更新版本**。下面是 macOS / Linux 的启动命令；Windows 使用对应的虚拟环境激活方式与可执行文件路径。本版实测环境见文末。

```sh
git clone https://github.com/moonlin1213/cove-pet-nest.git
cd cove-pet-nest
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
export PET_NEST_DATA_DIR="$PWD/data"
cove-pet-nest serve --port 8767
```

首次启动会在自己的数据目录生成 `browser-url.txt`。在本机浏览器打开其中的完整网址即可登录小屋；登录后，访问码会从地址栏移除。也可以打开 `http://127.0.0.1:8767`，输入 `credentials.json` 中的 `browser_token`。

**先领养一只小猫或小狗，就可以体验小屋与照顾。** 此时不需要配置图片服务，也不需要先接通聊天用量。

本机访问码、宿主凭据和数据文件都属于接入者的私有内容，请留在自己的数据目录。服务默认只监听 `127.0.0.1`，首版面向本机使用；远程托管与多租户访问控制需要接入者另行实现。

| 环境变量 | 用途 |
| --- | --- |
| `PET_NEST_DATA_DIR` | 私有数据目录；未设置时默认在用户目录的 `.local/share/cove-pet-nest` |
| `PET_NEST_USER_NAME` | 网页中你的显示名，默认“你” |
| `PET_NEST_ASSISTANT_NAME` | AI 的显示名，默认“你的 AI” |
| `PET_NEST_TIMEZONE` | 换粮与成长日期使用的时区，默认 `Asia/Shanghai` |

## 把 AI 接进来：MCP

让支持 **本地 stdio MCP** 的客户端启动安装环境中的 `cove-pet-nest mcp`。网页服务和 MCP 进程要使用同一个 `PET_NEST_DATA_DIR`。

下面是配置示例，路径需要替换为自己的绝对路径；Windows 的启动文件通常在虚拟环境的 `Scripts` 目录：

```json
{
  "mcpServers": {
    "pet-nest": {
      "command": "/ABSOLUTE/PATH/cove-pet-nest/.venv/bin/cove-pet-nest",
      "args": ["mcp"],
      "env": {
        "PET_NEST_DATA_DIR": "/ABSOLUTE/PATH/cove-pet-nest/data"
      }
    }
  }
}
```

| 工具 | 作用 |
| --- | --- |
| `nest_status` | 查看宠物、粮仓和真实照顾回执，支持分页 |
| `pet_adopt` | 按用户要求领养宠物 |
| `pet_care` | 喂食、陪玩或摸摸，返回真实操作结果 |
| `pet_album` | 只读阶段相册与生活事件，支持分页，不触发生图 |

可以在接入后试着说：“领养一只叫团团的小猫。”“看看宝宝有没有饿。”“陪它玩一会儿。”这些名字只是虚构示例。

照顾参数示例：

```json
{"action":"feed","pet_ids":["PET_ID_FROM_STATUS"],"request_id":"demo-feed-1"}
```

每次真实动作产生稳定的 `request_id`，网络重试复用它，避免重复操作。`fed` / `played` / `comforted` 表示成功；`full` / `no_food` / `pending` 要如实告诉用户。

图片任务由 `serve` 进程推进。只有 MCP 进程时，可以照顾与排队，但不会执行生图。

## 让对话换粮、让相处塑造宝宝

**配置 MCP 后，AI 能照顾宠物；对话计量和关系信号还需要宿主应用接入。** MCP 不会自动读取任意客户端的 token 或关系状态。

宿主后端使用自己的 `host_token` 调用这些接口：

| 接口 | 用途 |
| --- | --- |
| `POST /api/integration/usage` | 回复成功保存后，上报计数、字节长度和稳定事件 ID，触发换粮 |
| `POST /api/integration/relationship` | 上报共同相处信号，参与首次孵化与后续成长主题 |
| `GET /api/integration/nest` | 没有 MCP 时，由后端查询小屋状态 |
| `POST /api/integration/adoptions` | 没有 MCP 时，由后端执行 AI 领养 |
| `POST /api/integration/care` | 没有 MCP 时，由后端执行 AI 照顾 |
| `POST /api/integration/assets/{pet_id}` | 成长前导入普通宠物的透明六格图集 |
| `GET /api/integration/pets/{pet_id}/stages` | 读取成长相册 |
| `GET/POST /api/integration/life-events` | 读取或记录有界生活事件 |
| `POST /api/integration/photos` | 为已有事件明确请求生活照 |

凭据由后端持有，不要放进模型提示、网页 JavaScript 或公开配置。关系信号包含 `affection`、`reading`、`watching`、`listening`、`exploration` 五个有界维度；可选的短摘要只保存在本机，不在普通状态或 MCP 中返回。

完整契约、JSON 示例和去重规则见 **[接入教程](docs/integration.md)**；可运行的用量上报示例见 [examples/host_events.py](examples/host_events.py)。

粮食规则：前 4,000 个本轮贡献 token 每 200 得一粒，之后每 800 得一粒；每日最多 40 粒 token 粮，并保留余数。当天第一次合格对话还有基础粮。只报 Provider 的总 token 数无法区分新增可见贡献，请按教程提供本轮计数。

## 为宝宝准备模样

猫、狗、蛋已经有通用素材。其他普通宠物可以由宿主导入 **透明、3 列 × 2 行**的六格图集，或配置图片生成服务。神秘蛋的首次孵化使用冻结的外观描述生成图集。

图片服务需要设置 `PET_NEST_IMAGE_ENDPOINT`、`PET_NEST_IMAGE_MODEL`、`PET_NEST_IMAGE_KEY`。初始生成支持返回 `data[0].b64_json` 的 OpenAI-compatible JSON 生成接口，服务还需支持相应尺寸与透明背景；不是任意图片接口都能直接接入。

持续蜕变和生活照还需配置 `PET_NEST_IMAGE_EDIT_ENDPOINT`，使用 multipart 参考图编辑。**这两类请求会将宝宝的外观图集发给你选择的图片服务**；生成描述不包含姓名、聊天正文或关系摘要。导入普通宠物的模样后，旧的初始生成任务会终结，晚到结果不会覆盖导入图。生成结果不确定时不会自动反复发送；手动重试会明确提示可能已有费用。

接口要求、图片格式、任务恢复和费用边界见 **[图片服务说明](docs/images.md)**。真实生成质量与费用取决于接入者选择的服务，本版没有完成真实 Provider 生图验收。

## 开发、验证与数据边界

```sh
pip install -e '.[dev]'
pytest -q
python -m build --no-isolation
python scripts/check_release.py --artifact dist/cove_pet_nest-0.2.0-py3-none-any.whl
python scripts/check_release.py --artifact dist/cove_pet_nest-0.2.0.tar.gz
```

v0.2.0 在 Python 3.13 / macOS ARM64 验证，45 项测试覆盖照顾、换粮、持续成长、历史外观、生活照去重、参考图请求、断线恢复、HTTP 身份、真实 stdio MCP 和备份恢复。实际 v0.1.0 安装生成的隔离数据升级验证通过。Chrome 的 1280×800 与 390×844 相册翻页、放大、照片入口和基本小屋流程均有网页检查；详细发布验证见 [验收记录](docs/privacy-review.md)。尚未完成真实手机、Windows / Linux 或第三方 AI 应用验收。

用户数据、个性化图片、凭据、日志和恢复备份不得加入源码仓库或发行包。项目附带的示例均为虚构资料，网页截图来自隔离测试实例；四项通用 starter 素材的来源范围与 SHA-256 记录在 [素材清单](src/cove_pet_nest/assets/manifest.json)。

更多说明：

- [隐私与验收记录](docs/privacy-review.md)
- [本地备份与恢复](docs/backup.md)
- [v0.2.0 升级说明](docs/upgrade-v0.2.md)
- [更新记录](CHANGELOG.md)
- [许可与素材归属](NOTICE.md)

本项目使用 **MIT License**，保留上游版权声明。欢迎在自己的 AI 应用里接入，也欢迎围绕核心玩法、接入体验和后续成长记录提出改进。