---
name: anotherworld-connect
description: 把现实世界的事件（自动贩卖机售出、POS 下单、小程序支付、IoT/打卡触发等）接入「另一个世界·大观园」虚拟世界，让真实购买实时在园中触发奇趣变化（开花、乌龟爬出、锦鲤跃水…）。当用户想把贩卖机/收银/支付/传感器事件接入 anotherworld（大观园像素世界）、或提到 anotherworld-events、/pub 事件、把线下事件投射进虚拟世界时使用。
---

# AnotherWorld 接入

让现实事件驱动「另一个世界 · 大观园」(https://xiaopingfeng.com/apps/anotherworld/)。
机制：你的系统把事件 `POST` 到事件中枢，所有正在观看世界的浏览器通过 WebSocket 实时收到，
并在园中生成对应的小变化。**不影响主线剧情**，只是奇趣点缀。

## 事件中枢
- Base：`https://anotherworld-events.fxp007.workers.dev`
- 发布（`/pub`）需要令牌 `PUB_TOKEN` —— **向世界运营方索取，只放在服务端，不要写进公开前端**。
- 观看端（浏览器）连接 `/sub` 即可，无需令牌。

## 发布一个事件（核心）
`POST /pub`，JSON body：
- `product` (str)：售出/触发的商品名，决定特效（见映射表；未匹配 → 随机）。
- `source` (str)：机器 / 门店名，显示在世界的提示里。
- `effect` (str, 可选)：直接指定特效，覆盖映射 —— `flower|lotus|turtle|butterfly|koi|cat|rabbit|petals|firefly`。

```bash
curl -X POST https://anotherworld-events.fxp007.workers.dev/pub \
  -H "Authorization: Bearer $PUB_TOKEN" \
  -H "content-type: application/json" \
  -d '{"product":"冰激凌","source":"自动贩卖机-01"}'
```

成功 → `{"ok":true,"delivered":N,...}`（N = 当前在线观看人数）。令牌缺失/错误 → `401`。

## 商品 → 特效 映射
| 商品关键词 | 特效 |
|---|---|
| 冰激凌 / 雪糕 / ice | 荷花 lotus |
| 烤肠 / 肠 / sausage | 乌龟 turtle |
| 糖 / 糖葫芦 / candy | 花 flower |
| 奶茶 / tea | 蝴蝶 butterfly |
| 汽水 / 可乐 / cola / drink | 锦鲤 koi |
| 咖啡 / coffee | 猫 cat |
| 薯片 / chips | 兔子 rabbit |
| 爆米花 / popcorn | 流萤 firefly |
| 其它 | 随机 |

## 接一台真实贩卖机 / 收银台（推荐做法）
多数云管贩卖机、POS、小程序支付都能配「出货成功 / 支付成功」webhook。写一个薄适配器，
把它的回调载荷映射成 `{product, source}` 再 `POST /pub`：

```js
// 收到平台「出货成功」回调时：
await fetch("https://anotherworld-events.fxp007.workers.dev/pub", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.PUB_TOKEN}`, "content-type": "application/json" },
  body: JSON.stringify({ product: payload.goodsName, source: payload.deviceId }),
});
```

```python
import os, requests
requests.post("https://anotherworld-events.fxp007.workers.dev/pub",
  headers={"Authorization": f"Bearer {os.environ['PUB_TOKEN']}"},
  json={"product": goods_name, "source": device_id})
```

## 无令牌试用（演示用）
`GET /demo`（开放、限流约 1.5s/次）广播一个示例事件，用于「试一下」按钮：
```bash
curl "https://anotherworld-events.fxp007.workers.dev/demo?p=冰激凌"
```

## 验证
1. 打开世界 https://xiaopingfeng.com/apps/anotherworld/
2. `POST` 一个事件。
3. 园中应立刻出现对应特效，并弹出「（来源）购得 商品 —— …」提示。
4. `GET /recent` 可查看最近 20 条事件与在线人数。

## 注意
- 令牌只放服务端；公开前端 / 演示用 `/demo`。
- 频率过高会刷屏，建议在源头合并或限流。
- 安装为 Claude Code 技能：把本文件放到 `~/.claude/skills/anotherworld-connect/SKILL.md`。