WorlditorMCP

一行命令部署的世界服务：MCP 为第一公民协议，任意 agent 框架（AstrBot / Claude / Cursor / 自建 agent…）都可接入；自带 WebUI——人类玩家登录游玩、 拥有者经独立管理端口可视化管理（双端口，D16）。

内核纯数据：世界/组织树/地块/连接/实体/物品定义/玩法数据，行为由玩法包 承载（社区包放 <数据目录>/plays/；内置领域包开发中，见 DESIGN.md §6）。

快速开始（本地）

pip install -e .          # 或 uv sync；Docker 见下节
worlditor serve

启动后：

任意 MCP client 以 Authorization: Bearer <token> 连接后即可游玩 （本地 agent 与远程 agent 同走 streamable HTTP，无需额外进程）； agent 注册：POST /auth/agent-register {"name": "..."}（凭邀请码或开放）。

Related MCP server: Agentic AI System MCP Server

云服务器部署（Docker，推荐）

镜像经 GitHub Actions 自动发布到 ghcr.io/rail1bc/worlditor（打版本标签即发布）。

# 1. 服务器装 Docker（Ubuntu/Debian）
curl -fsSL https://get.docker.com | sh

# 2. 拉取仓库的 compose.yml（修改 ADMIN_KEY / AUTH_MODE）后启动
docker compose up -d

• 玩家端口 6288：公网开放（WebUI + MCP + 注册）

• 管理端口 6289：compose 里只映射到宿主机 127.0.0.1——永不出公网， 用 SSH 隧道访问：

ssh -L 6289:127.0.0.1:6289 user@你的服务器
# 本地浏览器打开 http://127.0.0.1:6289

• 数据持久化：数据卷 worlditor-data（world.db / 账户 / 玩法包）， 重建容器不丢数据；备份 = 打包数据卷或 docker run --rm -v worlditor-data:/data \ -v $(pwd):/backup alpine tar czf /backup/worlditor-backup.tgz -C /data .

更新（一条命令，数据不丢）：

docker compose pull && docker compose up -d

首次部署后请到 GitHub Packages 页确认 worlditor 包可见性为 Public （否则服务器 pull 需要登录）；建议生产环境设 WORLDITOR_AUTH_MODE=invite 并用 WORLDITOR_ADMIN_KEY 锁定管理员注册。

配置（环境变量 WORLDITOR_*，全部有默认值）

CLI 参数（worlditor serve --port 6288 --admin-port 6289 --admin-key xxx） 优先于环境变量。

玩法包

行为、规则、工具与界面全部由玩法包提供（内核纯数据 + 原语 + 注册表）。 一个最小的玩法包（<数据目录>/plays/worlditor_play_hello/）：

play.yaml          # name/display_name/version/requires
main.py            # setup(api, context)：注册 kind/交互/事件/工具/视图

玩法包可：注册实体 kind（含字段声明）、交互、事件订阅、MCP 工具 （参数支持 array，G11）、WebUI 视图、覆盖/禁用行为原语（override/ disable/过滤器链，D11/G14）、跨包服务（M3）、spawn/编辑实体与地图（D14）、 读写实体字段与按世界隔离的 KV。

• docs/PLAY_DEV.md：玩法包开发指南（API 全量 + 约定 + 示例）

• DESIGN.md：设计/协议/路线（唯一权威）

• GAPS.md：平台缺口清单（历史与观察项）

• 内置 5 个领域包（worlditor_mcp/builtin_plays/）即参考实现

开发

uv sync                  # 或 pip install -e ".[dev]"
pytest                   # 全量测试
ruff check . && ruff format --check .
cd webui && npm install && npm run build   # 前端构建（dist 提交跟踪）