绝区零 OneDragon 后端服务入口详解:MCP 与 HTTP 双适配器下的进程装配与运行

原创2026-09-28 11:05:282,142 阅读
文章标签:桌面应用计算机视觉GUI 自动化工作流自动化

绝区零 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 的职责是:

  1. 创建 ZContext()(截图 / OCR / 控制器 / Application 的宿主上下文);
  2. 创建 ZzzBackendContext(ctx);
  3. 通过 create_mcp_server 创建 MCP 服务器(注册基础 game tool),再经 register_http_routes 把 /game/* 端点挂到同一个 MCPServer 实例上;
  4. 最终用 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)一一对应:

  1. 创建 ZContext();
  2. 创建 ZzzBackendContext(ctx);
  3. await backend.start():在线程池中执行同步初始化(不阻塞事件循环),完成 ZContext 的 OCR / YOLO / 控制器等初始化;
  4. 装配 app:注册 MCP /mcp 与 HTTP 路由(/health、/game/*,含应用运行与自定义 op 端点);
  5. uvicorn.serve 监听本机端口(uvicorn.Config(app, host=host, port=port, log_level="info", access_log=False)——关闭 access log,避免 GUI 状态轮询刷屏);
  6. 关闭时调用 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 / daemon start 一致),保证日志单一出口。

.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 重新发现)。

相关文档索引

登录后查看全文
ZenlessZoneZero-OneDragon