# Purrtocol · 两只猫的黄昏送货

一个人类玩家和一个 AI 玩家各控制一只猫的合作小游戏。人类用键盘，AI 通过 MCP 观察、走路、互动和说话。

这是一个已经试玩、录制并收工的小 demo，不承诺继续维护。一起推箱子、交换两岸的机关线索、替同伴挡风，把小包裹送到终点。结尾可以接受、暂缓或拒绝心意，由人类决定什么时候结束。

## 游戏截图

从一份委托出发，一路聊天、合作，把包裹和想说的话一起送到。以下是实际试玩截图，最后一张包含结尾对话。

### 领包裹，出发

![开局页面：路不太好走，还好有你。](docs/screenshots/01-home.jpg)

### 小镇里的两只猫

![黄昏小镇：两只猫在果婆婆杂货店前接任务、聊天。](docs/screenshots/02-town.jpg)

### 一起想办法过桥

![黄昏山坡：两只猫分工踩机关、固定桥梁，带着包裹一起过河。](docs/screenshots/03-bridge.jpg)

### 树下的话，不赶时间

![终点的树下对话：送完包裹，可以接受、暂缓或拒绝心意。](docs/screenshots/04-evening-conversation.jpg)

## 本机试玩

需要 Node.js 20.9 或以上版本及 npm。

```sh
npm ci
cp .env.example .env.local
npm run dev -- --webpack --hostname 127.0.0.1
```

打开 <http://127.0.0.1:3000>，取名并创建房间。示例配置使用内存模式，无需数据库；停止服务后临时房间会消失。

键盘：A / D 移动，空格跳跃，E 互动，Enter 聊天。

## 让 AI 加入

将支持 Streamable HTTP 的 MCP 客户端连接到：

```text
http://127.0.0.1:3000/api/mcp
```

让 AI 调用 `game_join`，传入网页上的 `room_id` 和它的 `player_name`。AI 是 Player 2。

| 工具 | 用途 |
| --- | --- |
| `game_join` | 加入指定房间 |
| `game_observe` | 读取 AI 视角、可用动作与新事件 |
| `game_act` | 移动、跳跃、跟随、推箱、互动和举板护送等 |
| `game_say` | 游戏内文字聊天，与身体动作独立 |
| `game_wait` | 等待新事件，最多 15 秒 |
| `game_snapshot` | 公开状态调试快照 |

以服务返回的工具 schema 为准。动作携带最新场景版本，发言携带阶段信息；普通聊天不会自动触发正式告白或告别。两岸谜题需要玩家交换各自能看到的线索，重箱子需要两只猫实际同时推。

云端 AI 无法直接访问本机回环地址，需要自行设置受限连接。个人隧道、凭据、运行日志和房间存档不包含在本仓库中；上方仅展示选定的试玩截图。此 demo 没有账号鉴权或面向公网的服务加固，请在本机或可信的受限环境运行。

## 可选数据库

保留了 PostgreSQL 持久化路径。需要时将 `PURRTTOCOL_EPHEMERAL` 改为 `0` 并在本地环境文件中设置 `DATABASE_URL`。数据库连接配置应自行管理，不要提交真实密码。内存模式是本项目试玩时使用的默认方式。

## 验证与源码

```sh
npm run typecheck
```

启动本地服务后，可以运行完整 HTTP / MCP 流程检查（会创建测试房间）：

```sh
node scripts/playtest.mjs http://127.0.0.1:3000
node scripts/timing-check.mjs
```

`scripts/*.test.ts` 保留引擎、谜题与风口的回归用例。

- `src/game/`：物理、场景、房间状态、合作规则及 AI 视角。
- `src/components/game/`：猫、场景、界面与开发预览。
- `src/app/api/mcp/`：MCP 入口。
- `src/app/api/room/`：网页玩家接口。
- `src/db/`：可选数据库存储。

## 已知局限

模型和连接延迟会影响动作衔接；反复互动可能产生重复提示；拿放物品和风向提示还有打磨空间。开发模式和真实网络下的体验不完全一致。它是一次小规模的人类与 AI 合作游戏实验，不是完整商业游戏。

## 许可证

[MIT](LICENSE)。第三方依赖遵循各自许可证。