# DnD WebMCP / Agent Tavern

这是在已验证的 counter probe 上原地演进出的最小多人文字 TRPG。它保留共享 `room`、单调 `version`、角色工具隔离、乐观并发检查和 `wait_for_event`，但将数值累加替换为事件驱动的酒馆场景、三阶段回合和服务端 d20 检定。

当前范围只有：

- DM / Human / Mira 三方公共事件日志
- `WAITING_DM` / `WAITING_HUMAN` / `WAITING_AGENT`
- 自然语言 `speech` / `action` / `narration` / `reveal`
- `STR` / `DEX` / `INT` / `CHA` 四属性检定
- Human 对话界面与角色/骰子状态栏
- 中文 / English 界面和 WebMCP 工具描述切换

没有地图、战斗、装备、技能栏、商店、登录、音效、动画或持久数据库。

## Online demo

公开服务：<https://dnd-webmcp.onrender.com>

同一局的三个参与者必须使用完全相同的 `room` 参数：

- [DM / 主持人](https://dnd-webmcp.onrender.com/?room=demo&role=dm&lang=zh)
- [Human / 玩家](https://dnd-webmcp.onrender.com/?room=demo&role=human&lang=zh)
- [Mira / AI 队友](https://dnd-webmcp.onrender.com/?room=demo&role=agent&lang=zh)
- [健康检查](https://dnd-webmcp.onrender.com/api/health)

右上角可以切换中文 / English，也可以把 URL 中的 `lang=zh` 改为 `lang=en`。

> Render Free 实例在闲置后会休眠，首次访问可能延迟 50 秒以上。实例重启、重新部署或休眠恢复可能清空内存房间，请把它视为比赛演示地址。

## Run

在仓库根目录：

```text
cd DnD-WebMCP
npm start
```

从压缩包运行时，直接在包含 `package.json` 的解压目录执行 `npm start`。

页面：

```text
http://127.0.0.1:8787/?room=demo&role=dm&lang=zh
http://127.0.0.1:8787/?room=demo&role=human&lang=zh
http://127.0.0.1:8787/?room=demo&role=agent&lang=zh
```

三个页面只有使用相同 `room` 时才共享世界。`role=player` 作为旧 probe 的兼容别名映射到 `agent`。右上角的 `中文 / EN` 开关会保留 `room` 和 `role`，只切换 `lang=zh|en`；系统界面、角色规则、等待提示和工具描述同步切换。玩家自由输入的剧情内容保持原文，不做自动翻译。

## Turn contract

- 初始阶段是 `WAITING_DM`。
- DM 可以连续叙事、请求检定和揭示事实，最后用 `set_phase` 交棒。
- Human / Mira 的 `speak` 记录公开发言但不结束回合。
- Human / Mira 的 `act` 或自身 `request_check` 会自动把阶段交回 DM。
- 所有写工具都要求准确的 `expectedVersion`；旧版本返回 HTTP 409 和最新公开状态。
- `wait_for_event` 最长 20 秒，默认 5 秒。结果包含 `yourTurn` 和 `nextInstruction`，超时后应读取状态并再次短等待。

## Role tools

DM 页面：

```text
get_dm_state
get_recent_events
narrate
reveal_fact
request_check
set_phase
wait_for_event
```

Human / Mira 页面：

```text
get_visible_state
get_my_character
get_recent_events
speak
act
request_check
wait_for_event
```

Human / Mira 的状态和等待结果不包含 `dmSecrets`。没有 `set_state`、`update_json`、`set_hp` 或其他通用状态写工具。

## Tests

```text
npm test
```

测试覆盖状态初始化、秘密隔离、阶段权限、事件顺序、服务端随机 d20、四属性白名单、版本冲突、等待唤醒/超时、取消清理和重置唤醒。

## Deployment

GitHub Pages 只能托管静态文件，不能运行本项目的 Node API、共享内存房间或 `wait_for_event`，因此不能单独发布完整版本。

当前线上服务部署在 Render Free（Singapore）：<https://dnd-webmcp.onrender.com>。

仓库包含 `render.yaml`，也支持从 GitHub 创建新的 Render Blueprint。详细步骤和平台边界见 [DEPLOYMENT.md](DEPLOYMENT.md)。服务支持平台提供的 `PORT`，云端监听地址由 `HOST=0.0.0.0` 设置。

## Prototype limitations

状态只存在当前 Node 进程内，重启或免费实例休眠后会清空。API 没有认证且 CORS 宽松，角色权限目前由页面工具面隔离；知道接口的人仍可直接构造请求。可以公开部署用于比赛演示，但不适合作为不受控的生产服务。

正式部署至少需要共享持久化存储、原子版本更新、房间身份与角色令牌、幂等请求键、速率限制、审计日志和 HTTPS。