服务插件用于提供与关卡无关的公共功能（例如统一验证页、公告、排行榜、导出等），挂载到：

/services/{slug}

注意：服务插件默认 不 自动挂权限依赖；如需鉴权请在服务内部自行加校验逻辑。

1. 创建服务目录

在项目根目录下创建：

services/<module>/
└── __init__.py

其中：

• <module>：Python 包名（建议与 slug 一致）

2. 在 config/services.json 注册服务

打开 config/services.json，追加一项：

{ "slug": "ping", "module": "ping", "enabled": true }

3. 编写最小服务代码（router）

在 services/ping/__init__.py 中提供 router = APIRouter()：

from fastapi import APIRouter

router = APIRouter()

@router.get("/")
async def ping() -> dict:
    return {"ok": True}

4. 运行与验证

启动：

uvicorn main:app --reload

访问：

GET /services/ping/

应返回：

{ "ok": true }

5. （可选）在服务里做鉴权

如果服务需要“至少达到某关才能访问”，可以在服务内部读取 token 并校验（示例思路）：

• 从 Authorization: Bearer <token> 取 token
• core.auth.decode_token() 解码
• core.fingerprint.generate_fingerprint() 校验指纹
• 检查 payload["lvl"] 是否满足要求

（这部分属于应用策略，框架不会自动替你加门禁。）

常见坑

• “服务没加载/404”：检查 config/services.json 中该条目 enabled: true，并且 services/<module>/__init__.py 存在且能 import。
• “模块有 router 但还是没挂载”：确认变量名就是 router，并且是 fastapi.APIRouter() 实例。