绝区零 OneDragon 后端服务入口详解:MCP 与 HTTP 双适配器下的进程装配与运行
绝区零 OneDragon 后端服务入口详解:MCP 与 HTTP 双适配器下的进程装配与运行
导读
ZzzBackendContext 是绝区零 OneDragon(ZenlessZoneZero-OneDragon)自动化项目的传输无关后端服务层,而 entry.md 描述的正是它的进程入口:在单进程内装配 backend、MCP 适配器与 HTTP 适配器,由 uvicorn 统一对外服务。本文将以该入口文档为核心,结合仓库源码,完整讲解命令行 / GUI / 开机自启三种启动方式、MCP(/mcp)与 HTTP(/game/*)路由总览、.env 约束、进程模型与 dev 依赖,并延伸到远程 SSH daemon 场景,帮助你从零跑起或二次开发这条「一条龙」自动化服务。
服务入口的整体定位
在进入具体操作前,先明确入口在整个 backend 分层中的位置。ZzzBackendContext 是构建在 ZContext 之上的传输无关 backend——它不关心调用方来自 MCP、HTTP 还是 GUI 管理页,只提供稳定的业务方法和运行状态(见 architecture.md)。入口模块 src/zzz_od/backend/entry/server.py 的职责是:
- 创建
ZContext()(截图 / OCR / 控制器 / Application 的宿主上下文); - 创建
ZzzBackendContext(ctx); - 通过
create_mcp_server创建 MCP 服务器(注册基础 game tool),再经register_http_routes把/game/*端点挂到同一个 MCPServer 实例上; - 最终用
mcp.streamable_http_app()得到 Starlette app,交给 uvicorn 单进程并行提供 MCP(/mcp)与 HTTP(/game/*)两套服务。
这一点在源码 docstring 中写得非常明确(server.py):本模块把 MCP 适配器与 HTTP /game/* 适配器装配到同一个 MCPServer 实例上,通过 streamable_http_app() 得到一个 Starlette app,最终交给 uvicorn 在单进程内并行对外服务。
命令行运行
基础命令
如果项目根目录存在 .env,推荐带环境变量启动:
uv run --env-file .env python -m zzz_od.backend.entry.server --host 127.0.0.1 --port 23001
如果项目根目录没有 .env,可省略 --env-file .env:
uv run python -m zzz_od.backend.entry.server --host 127.0.0.1 --port 23001
命令的本质是执行 entry/server.py 的 main():通过 argparse 解析 --host / --port(默认值见 server.py:127.0.0.1 / 23001),随后 asyncio.run 驱动 _serve 完成整个生命周期(server.py)。
CLI 参数
| 参数 | 默认值 | 说明 |
|---|---|---|
--host |
127.0.0.1 |
监听地址;本机服务默认只绑回环地址 |
--port |
23001 |
监听端口;MCP 端点与 HTTP 端点共用该端口 |
启动流程
入口文档给出的启动流程共 6 步,与源码 _serve(server.py)一一对应:
- 创建
ZContext(); - 创建
ZzzBackendContext(ctx); await backend.start():在线程池中执行同步初始化(不阻塞事件循环),完成 ZContext 的 OCR / YOLO / 控制器等初始化;- 装配 app:注册 MCP
/mcp与 HTTP 路由(/health、/game/*,含应用运行与自定义 op 端点); uvicorn.serve监听本机端口(uvicorn.Config(app, host=host, port=port, log_level="info", access_log=False)——关闭 access log,避免 GUI 状态轮询刷屏);- 关闭时调用
backend.shutdown():无论正常退出还是异常,finally块都会释放资源。
路由总览:同一进程挂载 MCP 与 HTTP 两套适配器
同一个 ZzzBackendContext 同时被 MCP(tool-call)与 HTTP(REST)两套适配器共享,这是入口设计最核心的一点:
| 适配器 | 入口 | 能力 |
|---|---|---|
| MCP | POST /mcp(streamable-http) |
19 个 tool:感知 / 操作 + 应用运行 + 自定义 op 运行 + 帮助指南(详见 mcp.md) |
| HTTP | GET /health |
本机服务探测(GUI「MCP 服务」页用) |
| HTTP | GET /game/window /game/capture /game/analyze |
窗口状态 / 截图 / 画面分析 |
| HTTP | POST /game/enter?block= |
打开游戏(op 路径) |
| HTTP | GET /game/applications |
应用列表(只读) |
| HTTP | POST /game/run/one-dragon?block= /game/run/standalone?app_id=&block= |
一条龙 / 独立应用(app 路径) |
| HTTP | GET /game/operations /game/operations/describe?op_id= |
自定义 op 列表 / 单个 op 参数 schema |
| HTTP | POST /game/run/operation?op_id=&block= |
运行自定义 op(args 走 body;业务失败 200+body) |
| HTTP | GET /game/status /game/stop /game/close |
运行状态 / 停止 / 关闭游戏 |
注:MCP 侧的 tool 数量在相关文档 mcp.md 中更新为 22 个(含
get_predefined_teams、upsert_screen_area、delete_screen_area等新增),两处文档存在版本差异,以当前源码mcp/目录实际注册为准。
路由的分层注册
路由并非写在一个文件里,而是分两层:
- http/routes.py 注册基础
/game/*handler:window/capture/analyze/enter/status/stop/close共 7 个端点,通过@mcp.custom_route(...)挂到 MCPServer 的 Starlette 层(routes.py); - http/service_routes.py 注册应用运行、自定义 op 与
/health:/health、/game/applications、/game/predefined-teams、/game/run/one-dragon、/game/run/standalone、/game/operations、/game/operations/describe、/game/run/operation(service_routes.py)。
每个端点的语义与返回结构见 http.md。几个值得注意的 HTTP 实现细节(均有源码依据):
- 同步 backend 方法统一走
asyncio.to_thread放进线程池,避免阻塞事件循环(如handle_game_window中的await asyncio.to_thread(backend.check_window),见 routes.py); backend未就绪时抛BackendNotReadyError,统一返回 503 JSON({"error": ...});/game/capture直接回传 PNG 字节(image/png,不落盘),与 MCP 侧「落盘返路径」是同一能力、不同序列化(routes.py);- 自定义 op 端点:
op_id走 query,args走 JSON body(空 body 时args={}),业务失败一律200 + body 内 error/started 标志,不引入 400/404/409(service_routes.py)。
GUI 启动:开发工具 -> MCP 服务
不习惯命令行时,GUI 的「开发工具 -> MCP 服务」页面提供本机 server 管理,页面功能与入口文档对应如下:
- 探测:请求
http://127.0.0.1:<port>/health,确认 server 是否为本项目后端; - 启动:在项目根目录执行
uv run python -m zzz_od.backend.entry.server --port <port>;如果项目根目录存在.env,会自动补上--env-file .env; - 停止 / 重启:查找并管理
zzz_od.backend.entry.server进程; - 日志:
.debug/zzz_od_mcp/main_server.log,默认关闭 uvicorn access log,避免状态轮询刷屏; - MCP 地址:
http://127.0.0.1:<port>/mcp; - 当前运行状态:请求
http://127.0.0.1:<port>/game/status。
页面行为细节:
- 页面会低频轮询
/game/status,并尾读.debug/zzz_od_mcp/main_server.log到消息框;这些日志只用于 GUI 展示,不通过 MCP tool 返回给 agent; - GUI 会过滤自身轮询、
GET /mcp探测和 Windows 连接重置这类噪音,并限制消息框保留行数,避免长时间打开后卡顿; - 这个 GUI 页面管理的是一个本机 server 子进程,不是把 MCP server 嵌进 GUI 主进程;当前不做 GUI 主进程与 server 子进程之间的跨进程运行互斥(与 architecture.md 中「进程模型」一节一致)。
开机自启
tools/mcp/create_mcp_server_startup_shortcut.ps1 会在 Startup 文件夹创建主 server 快捷方式,登录后自动启动主 server(端口 23001),在登录态(Session 1)直接启动、不经 daemon;卸载即删除该 .lnk。
关键点:
- 与远程 SSH daemon 自启互相独立、可共存——daemon 仍能按进程命令行发现并管理这样启动的主 server(
status/stop/restart); - 自启调用的
tools/mcp/start_mcp_server.ps1把日志重定向到同一个.debug/zzz_od_mcp/main_server.log(与 GUI / daemonstart一致),保证日志单一出口。
.env 的约束
uv run --env-file .env ... 会要求项目根目录存在 .env;如果本地没有 .env,命令会在启动前报错。因此:
- GUI 启动会先判断
.env是否存在,存在才自动补--env-file .env; - 命令行手动启动时,开发环境可以按项目需要创建
.env,或在不需要环境变量的场景下省略--env-file .env(即使用不带--env-file的简化命令)。
进程模型与运行槽
入口文档从进程角度总结了三条设计,均可在源码与架构文档中得到印证:
- server 进程独立持有一个
ZContext:_serve中ctx = ZContext(),与 GUI 主程序入口分离(server.py); - 每个进程内通过运行槽保证同进程单跑道:
ZzzBackendContext只持有一个RunSlot,所有运行(一条龙 / 独立应用 /open_game/ 自定义 op)都经run_slot._start进入同一条单跑道;app 路径委托run_application,op 路径由槽自管start_running / execute / stop_running(见 architecture.md「运行槽」一节); - 常驻
ZContext可避免 OCR / YOLO 冷启动成本:这是采用常驻进程而不是「每次调用起一次」的关键动机。
需要强调的是:当前只保证同一 backend 进程内的运行互斥;GUI 主进程与外置 server 子进程之间不做跨进程互斥,同一时刻分别发起运行可能冲突,使用时需注意。
依赖(dev 组)
入口文档明确列出 dev 依赖组所需的两个关键依赖:
| 依赖 | 版本约束 | 用途 |
|---|---|---|
mcp |
>=2,<3 |
MCPServer / streamable-http 传输实现 |
uvicorn |
无额外约束 | ASGI server,承载 Starlette app |
对应安装方式(与 remote-ssh.md 中 daemon 安装一致):uv sync --group dev。
远程 SSH 场景
远程 SSH 场景由 daemon 管 server 启停,详见 remote-ssh.md。要点速览:
- 动机:Windows Session 隔离——SSH 登录落在 Session 0(服务会话),游戏窗口在 Session 1(交互式桌面),而输入注入(
pyautogui/pydirectinput)必须管理员 + 交互式桌面会话,因此必须在 Session 1 里直接以管理员启动进程; - 拓扑:daemon(
127.0.0.1:23000,Session 1 常驻 / 管理员)只管主 server(:23001)启停,操作游戏的是主 server;远程 MCP 客户端先挂 daemon 管理启停,主 server 起来后再连它调 game tool; - daemon 自身要常驻,它重启不影响已起的主 server(psutil 按 cmdline 重新发现)。
相关文档索引
- architecture.md — backend 生命周期和进程模型、运行槽、模块布局
- mcp.md — MCP tool 全表、prompts 三通道、MCP 客户端接入配置
- http.md — HTTP 端点语义与返回结构
- remote-ssh.md — 远程 SSH daemon 安装与排查
- 入口源码 src/zzz_od/backend/entry/server.py — 装配与 uvicorn 生命周期
- 基础路由 src/zzz_od/backend/http/routes.py 与服务路由 src/zzz_od/backend/http/service_routes.py — HTTP 端点实现