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） 优先于环境变量。

玩法包

行为、规则、工具、界面以及世界内容全部由玩法包提供（内核纯数据 + 原语 + 注册表）——v0.2.0 起内核不内置任何地图/地块/实体，空库只有一个空的「默认世界」。 一个最小的玩法包（<数据目录>/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；世界包还可写 async def setup(...) 导入 地图、地块、连接与实体（参考内置 worlditor_play_demo_world，幂等：地图 已存在则跳过，不覆盖用户改动）。

安装方式：把包目录放进 <数据目录>/plays/，或在管理端 「玩法包 → 安装玩法包（zip）」上传（zip 内单个顶层目录 <play_id>/， 含 play.yaml 与 main.py）。

• 内置包：世界包 worlditor_play_demo_world（示例主世界：41 地块 + 商贩·阿福/告示牌/木门）+ 6 个领域包（items/starter/player/movement/ interaction/social）

• 身份只有一种 player：人类玩家与 agent 不作区分（脚本/agent 可用登录页 「agent / 脚本接入」无密码注册）

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

• docs/CORE_AUDIT.md：内核边界审查（零玩法包视角）+ 决策记录 + 待办

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

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

开发

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