module-control.md

模块控制

平台对已装模块的列表与启停（HTTP）。基于 modules/catalog.json + modules/module-lock.json。

与 模块服务目录 不同：本页是平台管模块；服务目录是模块对外业务 RPC。

日常启停优先 CLI：sfmc mod enable|disable（本地写 lock，db 在线时再 best-effort 热同步）。HTTP 下列路由由 db-server 提供，适合自动化与已起 db 的环境。运维说明见 使用指南 · 模块。

GET /api/sfmc/modules

合并后的模块列表（含 enabled 等运行态）。

curl http://127.0.0.1:3001/api/sfmc/modules

GET /api/sfmc/modules/catalog

catalog 原始镜像。

GET /api/sfmc/modules/:key

单个模块。:key 可为 manifest id 或 catalog 别名（以实现为准）。

PATCH / PUT /api/sfmc/modules/:key

{ "enabled": true }

POST …/enable · …/disable

curl -X POST http://127.0.0.1:3001/api/sfmc/modules/feature-afk/enable
curl -X POST http://127.0.0.1:3001/api/sfmc/modules/feature-afk/disable

注：Manifest v2 中已废除 canDisable 字段，模块启停统一由 module-lock.json 管理；若服务端对特定保留模块限制禁用，将返回 module_cannot_disable。

错误

error	含义
module_not_found	key 不存在
module_cannot_disable	该模块不可被禁用
dependency_unmet	启用时依赖未满足

与游戏的关系

改 lock 或模块代码后，需重新装载行为包：

sfmc> mod reload

改 configs/*.json 仍需重启 BDS（配置启动缓存）。

sfmc> mod enable feature-afk
sfmc> mod disable feature-afk