AI Tavern MC · Molly 的月影酒馆

一个由 WatcheRobot 扮演主持人的 3 分钟微型剧本杀。网页负责展示状态和按钮，确定性剧情引擎负责线索与结局，大模型（可选）只润色角色台词，机器人用表情、灯光和动作营造酒馆氛围。

安装

需要 Python 3.10–3.12（推荐 3.11）。

python3.11 -m venv .venv
source .venv/bin/activate                 # Windows: .venv\\Scripts\\Activate.ps1
python -m pip install --upgrade pip
python -m pip install 'fastapi>=0.115,<1' 'uvicorn>=0.30,<1' 'httpx>=0.27,<1'

SDK 真机环境再安装 watcherobot，并打开 Watcher Desktop：

python -m pip install watcherobot
watcherobot robot setup                    # 首次配网
watcherobot robot pair 123456              # 使用机器人 Python SDK 页面显示的配对码
watcherobot robot status

离线演示（无需机器人） 

MOLLY_TAVERN_NO_BROWSER=1 python app.py --offline

打开 http://127.0.0.1:8877/。端口可用 MOLLY_TAVERN_PORT=9000 或 --port 9000 覆盖；默认会自动打开浏览器。

真机运行

必须由 Runtime 注入设备连接，不能直接把 app.py 当成普通脚本连接机器人：

watcherobot app run .

应用启动后访问 http://127.0.0.1:8877/。若现场桌面端没有可用设备，应用仍可通过 --offline 完成闭环。

API

方法 路径 JSON 作用
GET /api/state — 当前阶段、线索、动作和消息
GET /api/health — 服务、机器人和 LLM 状态
POST /api/start — 开始/重新开始剧本
POST /api/action {"action_id":"question_bard"} 调查一个行动
POST /api/command {"text":"检查后门"} 文本命令（含中文快捷匹配）
POST /api/accuse {"suspect_id":"bard"} 指认诗人或商人
POST /api/reset — 清空本局状态

LLM 配置（可选）

不配置也能运行，使用场景固定台词。配置任意 OpenAI-compatible Chat Completions endpoint：

export MOLLY_LLM_BASE_URL=https://api.openai.com/v1
export MOLLY_LLM_API_KEY=...
export MOLLY_LLM_MODEL=gpt-4o-mini

LLM 只润色已有台词，不得改变线索、凶手或游戏阶段；请求失败自动回退到确定性台词。

机器人语音

真机模式会使用 macOS 内置 TTS 合成后，通过 SDK audio.stream 播放到机器人扬声器。默认声音是柔和的 Flo (中文（中国大陆）)：

export MOLLY_TTS_VOICE='Flo (中文（中国大陆）)'
export MOLLY_TTS_RATE=165

浏览器端只负责 SpeechRecognition 语音输入，不播放 Molly 回复。Robot 音频流不可用时，页面会显示 Robot 语音未就绪并保留文字输入；LLM 不负责语音合成。

3 分钟展示路径

  1. 点击“开始剧本”，Molly 欢迎玩家并介绍月影宝石失窃。
  2. 依次选择“询问 Molly”“盘问流浪诗人”或“检查后门”，获得至少两条线索。
  3. 选择“指认诗人”（正确）或“指认商人”（错误），看到机器人情绪/灯光和结局卡片。

硬件触摸映射

设备不支持对应能力时，网页仍展示状态；supports() 检查确保动作、灯光和表情失败不会破坏剧情闭环。

检查与测试 

python -m compileall app.py molly_tavern
watcherobot app check .                   # 已安装 SDK 时
MOLLY_TAVERN_NO_BROWSER=1 python app.py --offline --port 8877

在浏览器中完成“开始 → 两次调查 → 指认”的一局即可验证 MVP 闭环。