Skip to content

HOME

Jump to bottom
Hydrooxzgen edited this page Sep 12, 2026 · 11 revisions

⛏️ EnderBridge Wiki

Minecraft 基岩版 (Bedrock Edition) 服务器端模组加载框架 通过 WebSocket 桥接游戏客户端, 以「客户端 Mod / 服务端 Mod」两层结构加载扩展。

📑 目录

  1. 项目简介
  2. 安装部署
  3. 配置向导
  4. Web 管理界面
  5. 配置详解
  6. 权限系统
  7. 命令系统
  8. 内置模组详解
  9. 模组开发指南
  10. 架构详解
  11. 常见问题与故障排查

1. 项目简介

EnderBridge 是一个用 Python 编写的 Minecraft 基岩版模组加载器。它启动一个 WebSocket 服务器, 等待游戏客户端连入, 然后按配置动态加载模组。

核心能力

能力 说明
WebSocket 桥接 默认监听 8800 端口, 多客户端并存, 首个连接自动成为主客户端
两层 Mod 架构 客户端 Mod (每个连接实例化) + 服务端 Mod (静态加载)
图形化配置向导 首次运行自动打开浏览器向导 (http://127.0.0.1:18888)
Web 管理界面 每次启动自动监听 18888 (可配置) , 浏览器管理权限 / 功能开关 / 仪表盘
依赖自愈 缺少依赖自动安装, 配置缺失自动从模板生成
跨平台 Windows / Android / Linux 统一相对路径

技术栈

  • Python 3.12+
  • websockets (WebSocket 服务器)
  • Pillow (图片处理)
  • mido (MIDI 解析)
  • openai (AI 对话, OpenAI 兼容接口)
  • websocket-client (QQ / MoreWS 同步客户端)

2. 安装部署

2.1 安装依赖

python setup.py            # 检测并安装缺失依赖
python setup.py --check    # 仅检测, 不安装 (齐全退出 代码为0, 缺失退出 代码为1)

直接运行 python main.py 时也会自动检测依赖, 缺失会自动调用 setup.py。

2.2 启动服务器

python main.py

启动流程：

  1. 检测 websockets 依赖, 缺失则自动安装
  2. 检测配置文件：优先 config.json (b0.3.6 标准) , 不存在则检测 config.py (b0.1.0 标准) , 都不存在则从 config.example.json 模板自动生成
  3. 检测 permission.json, 缺失则从 permission.example.json 复制
  4. 读取配置中的 is_first_run 标记, 为 True 时启动配置向导
  5. 启动 WebSocket 服务器, 等待客户端连接

2.3 命令行参数

参数 说明
python main.py 正常启动服务器
python main.py --help 显示帮助信息并退出
python main.py -h 相当于 --help
python main.py --version 显示当前版本
python main.py -v 相当于 --version
python main.py --reset-all 一键重置：删除所有配置文件及备份, 恢复首次运行状态, 立即退出
python main.py --load-without-config 无配置启动：跳过向导, 直接使用默认配置运行
python main.py --system 启用系统保留账户模式 (系统保留账户仅内置管理员可编辑)
python main.py update <压缩包> 一键升级：从新版本压缩包升级, 保留设置与用户数据, 完成后立即退出
python main.py export [路径] 一键导出：将项目代码打包为 zip (排除用户数据) , 配合 update 使用
python setup.py 安装 / 检测依赖
python setup.py --check 仅检测依赖是否齐全

2.4 一键升级 (update)

下载新版压缩包 (GitHub Release 的 zip / tar.gz 均可) , 运行：

python main.py update path/to/your/update/file.zip

升级流程：

  1. 探测压缩包：自动识别并剥离 GitHub 风格内层目录 (如 EnderBridge-main/) , 支持 zip / tar.gz / tgz / tar.bz2 / tar.xz
  2. 校验：压缩包内必须包含 main.py 与 lib/, 否则拒绝升级且不改动任何现有文件 (含损坏压缩包、路径穿越成员过滤)
  3. 解压覆盖：仅覆盖代码文件 (main.py、setup.py、lib/、mod/、模板、文档等)
  4. 保留数据：config.py / config.py.bak / permission.json / permission.json.bak、resources/、structures/、logs/、.git/ 及自定义文件全部不动；不删除多余文件, 自定义 Mod 等保留
  5. 完成退出：提示重新运行 python main.py 启动新版本

WebUI 在线更新：通过 Web 管理界面的「检查更新」页面可直接从 GitHub Release 更新。更新后服务器自动重启, 浏览器通过两阶段轮询 (Phase 1 等待旧进程关闭 → Phase 2 等待新进程恢复) 自动探测服务器状态, 恢复后自动跳转到仪表盘。支持端口偏移检测 (覆盖 basePort ~ basePort+9 共 10 个端口) , 带 3 秒超时防止单端口卡死。Windows 上额外等待 3 秒确保 TCP 端口释放。

升级不清理旧版本遗留文件；若新版配置模板结构变化导致启动异常, 可运行 python main.py --reset-all 重新配置。

2.5 首次运行流程

  1. config.example.json 中 is_first_run: true (模板默认) → 自动复制为 config.json, 检测到首次运行后启动配置向导
  2. 浏览器打开 http://127.0.0.1:18888, 填写配置并保存 (含 Web 管理端口设置)
  3. 保存后自动生成 config.json 与 permission.json (旧文件备份为 .bak) , 模板标记写为 false
  4. 保存后自动启动服务器；此后每次启动, Web 管理界面都会自动监听配置的端口

配置格式说明：b0.3.6 起默认使用 JSON 格式配置文件(EBC0.3.6) (config.json) 。旧版本的 Python 格式 (config.py) 仍受支持, 可随时通过 --migrate-config 升级或 --downgrade-config 降级。

3. 配置向导

图形化向导由 lib/setup.py 实现：启动一个仅监听 127.0.0.1 的临时 HTTP 服务器 (端口 18888–18899 自动尝试) , 保存时基于 config.example.py 模板做规则替换。

可配置项

分组 配置项 默认值
基础设置 服务器名称 EnderBridge
基础设置 WebSocket 端口 8800
基础设置 命令前缀 $
基础设置 日志等级 info
基础模组 客户端模组开关 (权限命令 / 工具 / 坐标 / 音乐 / MCFunc / MoreWS / Ezmatic / 图片) 全部开
基础模组 服务端模组开关 (聊天 / 终端、刷屏) 开
高级模组 AI 对话 (客户端 + 服务端) 开
高级模组 假人 Bot (Tab 列表玩家) 关
高级模组 QQ 群互通 关
AI 设置 API Key 空 (留空不启用 AI)
AI 设置 Base URL https://api.deepseek.com
AI 设置 对话模型 / 指令模型 deepseek-chat
AI 设置 对话冷却 (毫秒) 5000
音乐设置 播放打击乐 开
QQ 设置 群号 / 主机 / 端口 / 访问令牌 关
刷屏设置 攻击文本 / 广告文本 (每行一条) / 推送间隔 示例 / 1000ms
玩家权限 服主 (owner) -
玩家权限 管理员 (op) -
玩家权限 普通用户 (user) -
玩家权限 屏蔽名单 (blocker) -
资源路径 音乐 / MCFunc / Ezmatic / 图片 (勾选对应模组后显示) ./resources/...
高级配置 命令限流启用 / 时间窗口 / 最大次数 关 / 1000ms / 20
高级配置 Web 管理启用 / 端口 / 管理令牌 开 / 18888 / 空
高级配置 SAPI 群聊 / 私聊指令 gmsg / smsg
高级配置 Utils：tellall 转发为 tell / 启用轮询 关 / 开
Bot 设置 服务器地址 / 端口 / 玩家名 / 离线模式 / 版本 127.0.0.1 / 19132 / FakeBot / 开 / 空

勾选/取消勾选模组会即时显示/隐藏对应配置区 (AI、音乐、QQ、刷屏、资源路径行) 。 校验规则：服务器名称非空、端口 1–65535、日志等级合法、限流启用时窗口与次数必须为正整数、广告推送间隔为非负整数。

4. Web 管理界面

每次启动服务器时, Web 管理界面会自动监听配置的端口 (默认 18888) 。浏览器打开 http://127.0.0.1:18888 即可在网页中管理服务器, 无需手动编辑配置文件。

4.1 功能页面

页面 功能
📊 仪表盘 服务器名称、WebSocket 端口、Web 端口、客户端连接数、运行时间、令牌是否已设置；根路径 / 直接进入
👥 权限管理 在线查看与编辑 owner / op / user / blocker 四级权限, 保存后即时生效
⚙️ 功能设置 名称、端口、命令前缀、日志等级；音乐 / QQ 开关；命令限流；Web 管理自身 (启用 / 端口 / 令牌) ；命令别名开关
🔧 命令别名 管理命令别名 (添加 / 编辑 / 删除) , 如 message → msg 则 $msg 等同 $message
🧩 Mod 管理 查看客户端 / 服务端 Mod 列表与可导入状态, 一键重载所有服务端 Mod
🔄 检查更新 检查 GitHub Release 新版本, 在线更新 / 降级；更新后自动探测服务器恢复并跳转仪表盘

4.2 鉴权

登录页输入用户名和密码后进入系统：

身份 说明 可访问功能
管理员 (admin) 内置系统管理员账户, 首次启动终端显示随机密码 全部功能
普通用户 由管理员创建, 角色决定权限范围 按角色权限访问
访客 (Guest) 无需密码直接登录 仅仪表盘和 Mod 列表 (只读)
  • 首次运行时终端会显示 admin 的随机密码
  • 访客账户 guest 无需密码, 仅可查看仪表盘和 Mod 列表
  • API 鉴权：通过 X-Auth-Token 请求头校验登录状态；访客通过 X-Auth-Guest: 1 标记
  • 用户管理通过 Web 管理界面的「权限管理」页面进行

4.3 用户权限系统

b0.4.0 起新增基于用户名和密码的用户权限系统：

角色 说明 默认权限
admin 管理员 全部 8 项权限
operator 操作者 仪表盘 / Mod 管理 / 控制台 / 审计日志
viewer 观察者 仪表盘 / Mod 管理
(自定义) 管理员可创建自定义角色 自定义

8 项细粒度权限：dashboard / config / mods / console / permissions / audit / update / restart

权限覆盖：管理员可为每个用户单独覆盖权限（继承角色 / 明确允许 / 明确拒绝），拒绝优先于允许。开启「不继承角色」后完全自定义权限。

系统保留账户：启用 --system 模式后, 可标记用户为「系统保留」, 仅内置系统管理员可编辑。内置 admin 和 guest 账户不可删除。

Admin 密码验证：非系统管理员编辑/删除/启用其他用户时, 需先验证内置管理员密码。

4.3 配置 (config.py 的 webuiConfig)

webuiConfig = {
    "enabled": True,     # 是否启用 Web 管理界面
    "port": 18888,       # 监听端口
    "token": "",         # 管理令牌, 非空时访问需登录 (正确=管理员；错误=提示密码错误；访客需点击 Guest 按钮) 
}

4.4 REST API

接口 方法 鉴权 说明
/api/status GET 公共 状态：名称 / 端口 / Web 端口 / 客户端数 / 运行时间 / 版本 / 令牌是否已设置
/api/auth POST 公共 用户名 + 密码登录：{"ok": true, "token": "xxx", "role": "admin", "system": true} 或 {"ok": false, "message": "用户名或密码错误"}
/api/auth/me GET 登录用户 返回当前用户信息：{"username": "admin", "role": "admin", "permissions": [...], "system": true, "isGuest": false}
/api/config GET / PUT 管理员 读取 / 保存配置
/api/permissions GET / PUT 管理员 读取 / 保存权限
/api/mods GET 管理员 / 访客 Mod 列表与可导入性
/api/mods/reload-all POST 管理员 重载所有服务端 Mod
/api/update/check GET 管理员 检查 GitHub 最新 Release 是否有新版本
/api/update/install POST 管理员 从 GitHub Release 或本地压缩包执行更新
/api/update/upload POST 管理员 上传压缩包用于更新
/api/update/releases GET 管理员 分页获取所有 Release 列表
/api/restart POST 管理员 一键重启服务器
/api/release-notes GET 公共 获取当前版本 Release Notes
/api/console POST 管理员 向 MCBE 客户端发送命令并返回结果

鉴权列说明：公共 = 无需鉴权；管理员 = 需 X-Auth-Token；管理员 / 访客 = 两者均可 (访客需 X-Auth-Guest: 1) 。 未授权返回 {"ok": false, "message": "未登录"} (401)；权限不足返回 {"ok": false, "message": "权限不足"} (403)。 保存配置时旧 config.py 自动备份为 config.py.bak。部分设置 (名称 / 端口) 需重启生效, 权限与 Mod 重载即时生效。

5. 配置详解

5.1 核心配置 (config.json / config.py)

b0.3.6 标准：默认使用 config.json (JSON 格式) , 同时兼容 config.py (Python 格式) 。JSON 优先加载, Python 作为回退。 注意: b0.3.7版本开始，不再保留EBC0.1.0标准的Python配置文件，所有配置项均迁移至JSON格式。

配置项 类型 默认值 说明
wsConfig.name str "EnderBridge" WebSocket 服务器名称
wsConfig.port int 8800 WebSocket 监听端口
commandPrefix str "$" 游戏内命令前缀
logLevel str "info" debug < info < warning < error
commandAliases dict 见模板 命令别名映射 ({"message": ["msg", "m"]})
sapiConfig.gmsg str "gmsg" 取消息列表命令
sapiConfig.smsg str "smsg" 设置消息命令
features.music.playPercussion bool True 音乐打击乐
features.qq dict 关闭 QQ 桥接 (enabled/groupId/host/port/accessToken)
mods.client dict 见模板 客户端 Mod 列表
mods.server dict 见模板 服务端 Mod 列表
utilsConfig.tellAllToTell bool False tell 转发模式
utilsConfig.enablePolling bool True SAPI 轮询开关
AIConfig.options dict DeepSeek baseURL / apiKey
AIConfig.models.chat dict deepseek-chat 对话模型参数 (system prompt、max_tokens 等)
AIConfig.models.command dict deepseek-chat 指令模型参数 (强制输出 JSON)
AIConfig.chatCooldown int 5000 AI 对话冷却 (毫秒)
basePath dict 相对路径 music / mcfunc / ezmatic / image 资源路径
rateLimit.command dict 关闭 enabled / windowMs / maxPerWindow
webuiConfig dict 开 / 18888 Web 管理界面：enabled / port
botConfig dict 见下表 假人 Bot：host / port / username / offline / version
spam dict 示例 刷屏数据 (attack / ad / adInterval)

命名兼容：核心模块同时兼容驼峰与下划线写法 (rateLimit/rate_limit、logLevel/log_level、commandPrefix/command_prefix) , lib/command.py 与 lib/logger.py 会先尝试驼峰再回退下划线。

5.5 配置格式迁移 (b0.3.6 新增)

b0.3.6 引入 JSON 格式配置文件, 通过 version_manager/ 包管理配置格式的升级与降级。

操作 命令 说明
升级 py main.py --migrate-config 将 config.py 迁移到 config.json, 迁移后自动删除 config.py
降级 py main.py --downgrade-config 将 config.json 降级为 config.py, 降级后自动删除 config.json

version_manager 包结构：

version_manager/
  __init__.py     — 导出主要接口
  detector.py     — 版本检测 (parse_version, compare_versions, detect_version) 
  migrator.py     — 迁移调度器 (注册表模式, 支持 py↔json 双向迁移)

新增配置标准只需在 migrator.py 中用 @register_migration("old_fmt", "new_fmt") 注册迁移函数即可。

5.2 Bot 配置 (config.py 的 botConfig)

配置项 类型 默认值 说明
host str "127.0.0.1" MCBE 服务器地址
port int 19132 MCBE 服务器端口 (RakNet)
username str "FakeBot" 假人玩家名称
offline bool True 离线模式 (跳过 Xbox Live 认证, 必须为 True)
version str None MCBE 协议版本 (留空自动检测)

假人通过 bedrock-protocol (Node.js) 使用 RakNet 直连服务器, 协议层与游戏客户端完全一致, 因此会出现在 Tab 列表和游戏世界中。 首次启动时自动执行 npm install 安装依赖。

botConfig = {
    "host": "127.0.0.1",
    "port": 19132,
    "username": "FakeBot",
    "offline": True,
    "version": None,
}

5.3 平台检测 (内置)

platform = {
    "isWindows": sys.platform == "win32",
    "isAndroid": sys.platform == "android",
    "isLinux": sys.platform == "linux",
    "isUnixLike": sys.platform != "win32",
}

resolvePath(relPath) 对所有平台统一返回相对路径写法；传入绝对路径 (/ 开头或盘符) 则原样返回。

5.4 命令限流 (rateLimit.command)

rateLimit = {
    "command": {
        "enabled": False,     # 是否启用
        "windowMs": 1000,     # 时间窗口 (毫秒) 
        "maxPerWindow": 20,   # 窗口内最大命令数
    },
}

实现：按玩家名分桶 (commander -> {"start": ms, "count": n}) , 窗口过期自动重置。例：窗口 1000ms、最大 20 次, 表示每个玩家每秒最多执行 20 条命令。

6. 权限系统

b0.4.0 起新增基于用户名和密码的 Web 管理权限系统, 替代旧版令牌鉴权。

6.1 内置角色

角色 说明 默认权限
admin 内置系统管理员 全部 8 项权限
operator 操作者 dashboard / mods / console / audit
viewer 观察者 dashboard / mods

管理员可在 Web 管理界面创建自定义角色并分配权限。

6.2 细粒度权限

权限 说明
dashboard 仪表盘
config 功能设置
mods Mod 管理
console 控制台
permissions 权限管理
audit 审计日志
update 检查更新
restart 重启服务器

6.3 用户权限覆盖

管理员可为每个用户单独设置权限覆盖：

  • 继承角色：从角色继承（默认）
  • 明确允许：强制允许
  • 明确拒绝：强制拒绝（优先于允许）
  • 不继承角色：开启后完全自定义，仅保留下方显式设置的权限

6.4 游戏内权限命令 (mod/permission.py)

统一入口 perm (<前缀>perm <方法> <参数...>) ：

命令 权限 说明
perm query [账号] normal 查询权限 (不带账号查自身)
perm add <权限类型> <账号> owner 添加权限
perm remove <权限类型> <账号> owner 移除权限

6.5 命令分级

客户端 Mod 的 onCommand() 返回按 "normal" / "op" / "owner" 分级的命令字典, 执行时按玩家权限匹配对应分组。

7. 命令系统

7.1 命令框架 (lib/command.py)

内置模组统一采用单入口命令：<前缀><入口> <方法> <参数...>。入口命令声明字符串参数 (方法 + 最多 5 个参数) , 方法分派与参数类型校验在 Mod 内部完成, 每个入口输入 help 可列出该模组全部方法；全局 help 命令分页显示全部命令。

声明式命令定义, 支持链式调用：

Command.create("tool", "工具命令 (方法: search/send/cmd/ping/...) ")
    .add_string("方法", False)          # 必选字符串参数
    .add_optional_string("参数1")        # 可选参数
    .add_optional_string("参数2")
    .set_func(self._cmd_tool)           # 绑定分派处理函数

支持的参数类型 (.add_* 方法) ：

方法 说明
add_string(name, require) 字符串
add_integer(name, require) / add_optional_integer 整数
add_float(...) 浮点数
add_boolean(name, require) 布尔值
add_enum(values, name, require) 枚举

约束：可选参数必须在必选参数之后。

7.2 参数解析

Command.parse_args(input_) 支持双引号包裹的含空格参数；双引号未闭合时抛出 ValueError。

7.3 前缀机制

  • 前缀从配置 commandPrefix 读取 (模块加载时)
  • Command.set_command_prefix(text) 可动态修改 (不能包含空格)
  • 命令匹配：text_list[0] == f"{Command.command_prefix}{self.name}"

7.4 限流

Command._check_rate_limit(commander) 在命令执行前调用；rateLimit.command.enabled = False 时直接放行。

7.5 内置命令速查

所有内置命令均为单入口格式, help 方法可查看该模组全部方法；全局 help 命令分页显示全部命令。

**全局命令帮助 (help) **

命令 权限 说明
help [页码] normal 分页显示全部可用命令 (每页 5 条, help 2 翻页)

**Tool (tool) **

命令 权限 说明
tool search <关键词> [页码] normal 搜索命令
tool send <消息> op 向外部发送消息
tool tellall <true|false> op 查看/切换 tell 转发模式
tool cmd <命令> op 执行基岩版命令
tool ping owner 检测与服务器延迟
tool time owner 查看当前时间 (北京时间)
tool start owner 重新开始 SAPI 轮询
tool move owner 将当前客户端设为主客户端
tool reload [Mod名] owner 重载客户端 Mod
tool mod owner 显示所有客户端 Mod
tool exec <命令> owner 在服务器终端执行命令

**Bot (bot) **

命令 权限 说明
bot start owner 启动假人 Bot 进程 (Node.js)
bot stop owner 停止假人 Bot 进程
bot spawn <玩家名> owner 在主客户端位置生成一个假人, 出现在 Tab 列表和游戏世界中
bot remove <玩家名> owner 从 Tab 列表移除一个假人
bot move <玩家名> <x> <y> <z> owner 将假人传送到指定坐标
bot chat <玩家名> <消息> owner 让假人发送一条聊天消息
bot list owner 列出所有在线假人

**权限 (perm) **

命令 权限 说明
perm query [账号] normal 查询权限
perm add <类型> <账号> owner 添加权限
perm remove <类型> <账号> owner 移除权限

8. 内置模组详解

客户端模组 (config.mods.client)

名称 模块 入口 功能
AI mod.ai ai AI 对话：单次 / 上下文模式；chatCooldown 冷却；服务端静态部分负责清理
Bot mod.bot bot 假人管理：通过 Node.js bedrock-protocol 连接 MCBE 服务器生成假人 (Tab 列表 + 游戏世界)
PermissionCommands mod.permission perm 游戏内权限命令 (query/add/remove)
Tool mod.tool tool 全局命令帮助 (help) 、搜索、SAPI 控制、主客户端切换、Mod 重载
Position mod.position pos A/B 点标记、距离/偏移计算、区域填充 (fill) 、结构复制/粘贴/剪切；大区域按 64×64 切分为 tickingarea (上限 100 区块)
Music mod.music music 解析 MIDI/JSON, MIDI 音色映射 MC note 音效, playsound 播放；文件名有路径穿越防护
MCFunc mod.mcfunc function 加载执行 .mcfunction, 嵌套调用 (深度上限 16) 、定时循环
MoreWS mod.morews ws 同时连接多个外部 WebSocket 服务端, 消息双向转发 (同步库线程化 + call_soon_threadsafe 调度回主循环)
Ezmatic mod.ezmatic.main ezmatic 解析 Java 版 .litematic (NBT) , 导入为 MCBE 建筑；预览、世界差异检查、修复、导出 .mcstructure
ImageMod mod.image.main image 图片转像素画：PIL 读取, HSV/LAB 颜色匹配 blocks.json 调色板, setblock/fill 生成
QQ mod.qq.main qq NapCat (OneBot v11) WebSocket 连接；QQ 群 ↔ 游戏内消息互通；API 请求通过 echo 字段关联请求与响应

Bot 假人详解

工作原理：Bot 使用 Node.js bedrock-protocol 库通过 RakNet 直连 MCBE 服务器 (与真实客户端相同的协议层) , 因此假人会出现在 Tab 列表和游戏世界中。Python 控制器 (mod/bot.py) 通过 stdin/stdout 与 Node.js 进程通信。

依赖要求：

  • Node.js 16+ (需在系统 PATH 中)
  • 首次启动时自动 npm install 安装 bedrock-protocol 依赖

使用流程：

  1. 在配置中启用 Bot Mod (mods.client 添加 "Bot": "mod.bot") , 配置 botConfig 中的服务器地址和端口
  2. 启动服务器, 使用 $bot start 启动 Bot 进程
  3. 使用 $bot spawn <玩家名> 在主客户端位置生成假人
  4. 使用 $bot move / $bot chat / $bot remove 管理假人
  5. 使用 $bot stop 停止 Bot 进程

注意事项：

  • offline 必须为 True (离线模式) , 否则需要 Xbox Live 认证
  • 假人通过 RakNet 协议直连服务器, 与 WebSocket 客户端走的是完全独立的连接
  • Bot 进程在服务器停止时自动终止, 也可以通过 $bot stop 手动停止
  • version 留空 (None) 时自动检测服务器协议版本

服务端模组 (config.mods.server)

名称 模块 入口 功能
chat mod.read chat 终端交互 / 聊天：测试、列连接、重载 Mod、列 Mod、bye、换行发言等 (终端与游戏内均可用)
spam mod.spam spam 刷屏：attack、count、crash、clear、ad、repeat、stop (终端与游戏内均可用)
AI mod.ai - 静态清理任务 (不绑定具体客户端, 实时取 Current.client)

9. 模组开发指南

9.1 Mod 结构

每个 Mod 是一个 Python 模块, 导出 Mod 类：

class Mod:
    def __init__(self, client):
        self.client = client

    def onCommand(self):
        """返回分级命令字典 (客户端 Mod) """
        return {
            "normal": [...],
            "op": [...],
            "owner": [...],
        }

9.2 动态导入机制 (lib/mods.py)

  • 配置中的路径是 JS 风格："mod/ai.js" → 转换为 Python 模块 mod.ai
  • 兼容旧格式 "../mod/ai.js" (相对 lib/ 目录)
  • _reimport_mod() 绕过模块缓存重新导入, 实现热重载

9.3 客户端 Mod 生命周期

  1. 连接建立 → 延迟 1 秒初始化 (等 MCBE 握手完成)
  2. 绑定 Utils 工具 (runCommand / subscribe / tell 等)
  3. 实例化客户端 Mod (Mod(client))
  4. 消息循环：JSON 依次分发 → conn.utils.onMessage → 客户端 Mod onPocket → 服务端 Mod on_message
  5. 主客户端断开时 Current.reset() 重置全局状态

9.4 常用 API

命令定义 (lib/command.py) ：

Command.create("tool", "工具命令 (方法: ...) ")
    .add_string("方法", False)
    .add_optional_string("参数1")
    .set_func(self._cmd_tool)

async def _cmd_tool(self, sender, method, p1=None, p2=None, p3=None, p4=None, p5=None):
    if method == "hello":
        await self.client.tell(f"你好, {p1}！", sender)

事件总线 (lib/mods.py 的 EventBus) ：

event_bus.on("player_join", "MyMod", callback)   # 订阅
event_bus.emit("player_join", data)               # 发布
event_bus.off("player_join", "MyMod")             # 取消
event_bus.clear_mod("MyMod")                      # 清除某 Mod 全部订阅

全局状态 (lib/current.py 的 Current) ：

  • Current.client：当前主客户端
  • Current.client_mods：ws → ClientModManager 映射
  • 全局运行时属性键值存储

发送消息 (lib/utils.py 的 Utils / ClientConnection) ：

  • runCommand(cmd)：执行基岩版命令
  • subscribe(event)：订阅事件
  • tell(msg, player)：发送 tell 消息
  • ClientConnection：包装 websockets 连接 (原生对象用 __slots__ 不能挂属性) , 含发送锁

权限查询 (lib/permission.py) ：

perm = await PermissionManager.query(sender)

9.5 注册新 Mod

  1. 在 mod/ 下创建模块, 导出 Mod 类
  2. 在 config.py 的 mods.client (或 mods.server) 中添加： 
    mods = {
    "client": {
        ...
        "MyMod": "mod.mymod",
    },
    ...
}
  3. 重启服务器, 或使用 tool reload 热重载

9.6 异步约定

  • _call_maybe_async()：若回调返回协程则自动调度到事件循环 (与 JS 不 await Promise 的行为一致)
  • 同步库 (websocket-client) 在独立线程中运行, 回调经 call_soon_threadsafe 调度回主循环
  • AI 客户端使用 AsyncOpenAI, 避免阻塞事件循环

10. 架构详解

10.1 总体架构

graph LR
    A[MCBE 客户端<br/>WebSocket 连接] --> B[EnderBridge 服务器<br/>端口 8800]
    B --> C[lib/utils.py<br/>命令发送 / 事件订阅]
    C --> D[客户端 Mod<br/>每个连接实例化]
    B --> E[服务端 Mod<br/>静态加载]
    B --> F[SAPI 桥接<br/>gmsg / smsg]
    B --> G[NapCat OneBot<br/>QQ 群互通]
    B --> H[OpenAI 兼容接口<br/>AI 对话]
    B --> I[外部 WebSocket<br/>MoreWS 转发]
    B --> J[Web 管理界面<br/>HTTP 18888]
Loading

10.2 关键设计

设计 说明
1 秒延迟初始化 避免 MCBE 握手未完成就发命令导致「每次启动都要断开一次才能连上」
依赖自愈 main.py 顶部动态检测 websockets, 缺失自动装
配置自愈 config.py / permission.json 缺失自动从模板生成
JS 项目移植兼容 mod/ai.js → mod.ai 路径转换, 对齐 JS 动态加载策略
主客户端热切换 服务端清理任务实时取 Current.client, 避免对着已断开连接空转
权限原子写入 临时文件 + os.replace
日志 分级 (debug/info/warning/error) , 控制台 + ./logs 文件, 北京时间 (UTC+8) 时间戳

10.3 模块清单 (lib/)

模块 职责
command.py 命令框架：前缀、参数解析、限流
mods.py Mod 管理器：EventBus、客户端/服务端管理器、动态导入、热重载
utils.py WebSocket 工具：命令发送、事件订阅、消息分发
sapi.py SAPI 桥接：gmsg/smsg 通信；状态码 -2147483648 表示命令不存在, 可自动探测
permission.py 权限管理：四级权限、缓存、原子写入
logger.py 分级日志：控制台 + 文件、颜色高亮、UTC+8
shared.py 共享实例：logger 与 message_logger
current.py 全局状态：主客户端、Mod 映射、运行时属性
setup.py 图形化配置向导 (HTTP 18888, 仅首次运行)
webui/server.py Web 管理后端：HTTP 服务 + REST API (每次启动监听)
webui/index.html Web 管理前端：登录 + 仪表盘 / 权限 / 功能设置 / Mod 管理 (单文件)

11. 常见问题与故障排查

Q：首次启动没有自动打开配置向导？ 检查 config.example.py 中 is_first_run 是否为 True, 或运行 python main.py --reset-all 复位后重启 (向导仅在首次运行触发) 。日常管理请使用 Web 管理界面：启动服务器后访问 http://127.0.0.1:18888。

Q：Web 管理界面打不开？

  1. 确认服务器已启动, 日志中出现「Web 管理界面已启动」
  2. 确认 webuiConfig.enabled 为 True (默认开)
  3. 端口被占用时启动会跳过并告警, 可修改 webuiConfig.port
  4. 设置了 webuiConfig.token 时需在登录页输入令牌

Q：向导保存报「模板匹配失败」？ 向导按 config.example.py 模板原文匹配替换 (JSON 风格键, 如 "port": 8800) 。手动改动过模板字段格式会导致规则匹配失败, 请恢复模板原样。

Q：命令前缀改了不生效？ 前缀在模块加载时从 config.py 的 commandPrefix 读取, 修改后需重启服务器。

Q：游戏内命令没反应？

  1. 确认客户端已成功连接 WebSocket (查看服务器日志)
  2. 确认前缀正确 (默认 $, 如 $help)
  3. 检查 permission.json 中玩家权限等级
  4. 检查命令限流是否触发 (rateLimit.command.enabled)

Q：提示缺少依赖？ 运行 python setup.py 或直接运行 python main.py 自动安装。

Q：每次启动都要断开一次才能连上？ 这是握手时序问题, 已通过「1 秒延迟初始化」缓解。若仍出现, 检查客户端连接参数。

Q：AI 不工作？ AIConfig.options.apiKey 留空则不启用 AI；确认 Base URL 与模型名正确、网络可达。

Q：QQ 桥接不工作？ 确认 NapCat 已启动、features.qq 中 host/port/accessToken 与 NapCat 配置一致、enabled 为 True。

Q：如何在 Android / Linux 上运行？ 项目已内置平台检测与 resolvePath 路径适配, 统一相对路径即可跨平台运行。

Q：如何重置全部配置？ python main.py --reset-all 删除 config.py / permission.json 及备份, 并将模板复位为首次运行状态。

附录：文件路径速查

文件 用途
main.py 程序入口 (依赖自愈、配置生成、向导、服务器)
config.py 真实配置 (向导生成)
config.example.py 配置模板 (含 is_first_run 标记)
config.py.bak 配置备份 (保存向导前)
permission.json 玩家权限
permission.example.json 权限模板
setup.py 依赖安装器
requirements.txt 依赖清单
logs/ 运行日志
resources/pictures/ 图片像素画资源
lib/ 核心库
webui/ Web 管理界面 (后端 server.py + 前端 index.html)
mod/ 模组目录

EnderBridge · Minecraft Bedrock 服务器管理框架

Clone this wiki locally