绝区零一条龙后端服务层架构:ZzzBackendContext 与 RunSlot 单跑道运行模型解析

原创2026-09-28 13:52:492,207 阅读
文章标签:桌面应用计算机视觉GUI 自动化工作流自动化

绝区零一条龙后端服务层架构:ZzzBackendContext 与 RunSlot 单跑道运行模型解析

本文基于 architecture.md 编写,剖析绝区零一条龙(ZenlessZoneZero-OneDragon)项目中 ZzzBackendContext 这一传输无关后端层的整体设计:它如何把游戏感知/操作能力收敛成稳定业务方法,如何通过单一 RunSlot 保证同进程内「单跑道」并发语义,以及 MCP / HTTP 两个适配器如何在共享同一 backend 的前提下并行对外服务。读完本文,你将掌握该后端层的模块划分、生命周期、运行槽调度、自定义 operation 反射运行机制与进程模型,并能在源码中快速定位对应实现。

一、概览:传输无关的 backend 层

后端服务层位于游戏运行层(ZContext)之上,其核心定位在 architecture.md 开头即被点明:

ZzzBackendContext 是 ZContext 之上的传输无关 backend。它不关心调用方来自 MCP、HTTP 还是 GUI 管理页,只提供稳定的业务方法和运行状态。

也就是说,无论外部以何种协议接入,backend 层暴露的都是同一套稳定的方法签名,传输差异全部由适配器消化。整体组件关系如下(原文档 mermaid 图):

flowchart TB
    Entry["entry/server.py"] --> Backend["backend_context.py<br/>ZzzBackendContext + RunSlot"]
    Backend --> ZContext["ZContext<br/>截图/OCR/控制器/Application"]
    Backend --> RunSlot["RunSlot(单跑道)<br/>app 路径委托 run_application<br/>op 路径自管 start_running/execute/stop_running"]
    Backend --> OpRegistry["operation_registry.py<br/>自定义 op 扫描/op_id 解析/args 校验"]
    Backend --> Schemas["schemas.py<br/>传输无关 dataclass"]
    Backend --> MCPBase["mcp/app.py<br/>基础 MCP tools"]
    Backend --> MCPService["mcp/service_app.py<br/>应用运行 + 自定义 op tools"]
    MCPBase --> MCPPrompts["mcp/prompts.py<br/>MCP prompts"]
    Backend --> HTTPBase["http/routes.py<br/>基础 HTTP routes"]
    Backend --> HTTPService["http/service_routes.py<br/>应用运行 + 自定义 op routes + /health"]

从 README.md 的分层视角看,这可以归纳为三层模型:

层 内容
Layer 0 ZContext(截图 / OCR / YOLO / 控制器 / 执行引擎),不改动
收敛层 ZzzBackendContext:持有 ctx、管生命周期、感知 / 操作方法
适配器 MCP(@mcp.tool)+ HTTP(/game/*),并行、共享 backend

backend 层是一个 headless 服务进程:自己持有 ZContext,通过 ZzzBackendContext 收敛成传输无关方法,再由 MCP、HTTP 两个适配器并行对外暴露;GUI 是另一个独立入口,不经过本层。

二、模块布局

后端层全部代码位于 src/zzz_od/backend/ 下,职责划分如下(对应 architecture.md 的模块布局节):

src/zzz_od/backend/
  schemas.py             # WindowStatus / AnalyzeScreenResult / RunStatusResult / ApplicationListResult / OperationListResult
  backend_context.py     # ZzzBackendContext + RunSlot(单槽,app/op 分派)
  operation_registry.py  # 自定义 op 扫描 / op_id 解析 / args 校验(纯反射,不实例化)
  mcp/
    app.py               # create_mcp_server + 基础 game tools
    service_app.py       # list_applications / run_one_dragon / run_standalone_app / list_operations / describe_operation / run_operation
    prompts.py           # MCP prompt 案例与注册
  http/
    routes.py            # register_http_routes + 基础 /game/* handler
    service_routes.py    # /health + 应用运行 + 自定义 op HTTP handler
  entry/
    server.py            # create_app / uvicorn 入口

除此之外,仓库中还有两个支撑模块:app_registry.py(应用描述信息提取,供 list_applications 使用)与 _doc_utils.py(docstring 摘要工具,供 describe_operation 去除 :param 等 Sphinx 噪声)。

三、ZzzBackendContext:后端门面

ZzzBackendContext 持有一个 ZContext,由服务入口注入;所有对外方法在进入业务逻辑前先检查 ctx.ready_for_application(即 _ensure_ready(),实现见 backend_context.py,未就绪时抛出 BackendNotReadyError)。

其公开方法及返回类型汇总(原文档方法表):

方法 作用 返回
check_window() 查询游戏窗口状态 WindowStatus
capture() 截取当前游戏画面 RGB MatLike
analyze() 截图 + OCR + 画面匹配 AnalyzeScreenResult
start_run(source, op_factory, display_name=None) 启动 operation(op 路径,供 open_game / run_operation 经适配器调用) (ok, future)
run_one_dragon(source) 按当前配置启动完整一条龙(app 路径) (ok, future)
run_standalone_app(source, app_id=None) 启动独立应用(app 路径) (ok, future)
list_applications() 列出当前实例可运行应用和独立应用选择状态(只读,不刷新配置) ApplicationListResult
query_status() 查询当前或最近一次运行状态(单槽,直接委托) RunStatusResult
stop() 发出停止信号(单槽) dict
close_game() 发关闭窗口信号,不走运行槽 str

自定义 operation 运行入口(list_operations / describe_operation / run_operation)不经过 ZzzBackendContext 方法,而是由 MCP / HTTP 适配器直接调用 operation_registry(扫描 / 解析 / 校验)+ run_slot._start(op 路径)。

3.1 游戏感知方法的关键实现

  • capture():通过控制器对游戏窗口截图,返回 RGB ndarray,且会调用 controller.fill_uid_black(image) 对 UID 打码——backend 截图会落盘或外传,不能携带账号信息(backend_context.py)。
  • analyze(screenshot=None, save_image=False):默认实时截取当前画面,执行全图 OCR(ocr_service.get_ocr_result_list(image, crop_first=False),与画面匹配复用同一份 OCR 缓存)加画面匹配(find_screen_matches)。命中精准画面时会回写 screen_loader.update_current_screen_name,为下次 BFS 提供起点;若传入截图路径则按「离线模式」解析(绝对路径直接读,纯名字从 .debug/images/<名字>.png 读),不回写识别状态。save_image=True 仅实时模式生效,会把内存图落盘到 .debug/zzz_od_mcp/screenshot/ 并回传 screenshot_path,供调用方喂给视觉模型复用(backend_context.py)。
  • analyze 的能力边界提示:成功时返回 vision_hint,明示「本结果仅包含 OCR 识别的文字与模板匹配的命中项,是画面的部分识别结果,不等同于对画面的完整视觉理解」,防止智能体把部分识别当成画面全貌;失败时为 null(常量 _VISION_HINT 定义见 backend_context.py)。
  • 画面区域 CRUD:upsert_screen_area / delete_screen_area 按 area_name 对指定 screen 插入、更新或删除区域,写回 screen_info YAML 并重载,下次 analyze_screen 即生效;pc_rect 必须是 1920×1080 内的 <a href="https://link.gitcode.com/i/f90bae272c12ea2f058b438b7759b1c8" target="_blank">x1,y1,x2,y2] 四整数(校验见 [backend_context.py)。

3.2 交互操作方法

  • click_game(x, y, press_time=0.1, pc_alt=False):1080p 游戏空间坐标,经控制器自动缩放到真实屏幕;坐标不在窗口内返回 in_window=False;pc_alt=True 用于大世界等锁光标画面(点击前按住 Alt 解锁,否则点击落空)。
  • key_tap(key, press_time=0):press_time=0 短按,>0 长按;键名沿用框架约定(w/a/s/d/f/esc/space 等)。
  • drag(x1, y1, x2, y2, duration=1):鼠标按住拖拽,覆盖刮刮卡、八卦收集来回拖、咖啡拖动等场景。
  • input_text(text, use_clipboard=None):None 跟随 game_config.type_input_way,True 用剪贴板(支持中文/特殊字符),False 逐键输入;返回 masked_text 脱敏文本。

以上交互方法不走运行槽,且底层 click / key_tap / drag 无内置等待,连续操作或 capture 前建议 sleep 等动画。

四、运行槽 RunSlot:单跑道调度与终态固化

ZzzBackendContext 只持有一个 RunSlot,所有运行(一条龙 / 独立应用 / open_game / 自定义 op)都经 run_slot._start 进入同一条单跑道。槽只做两件事:单跑道调度 + 终态固化;执行序列在槽内按 app / op 分派:

路径 触发入口 执行序列 进度句柄 结果来源
app run_one_dragon / run_standalone_app 委托 run_application(复用 GUI/CLI 共享入口,内含 start_running / 绑定 / execute / stop_running) run_context.current_application run_context.last_application_result
op open_game / run_operation(自定义 op) 槽自己 start_running → op_factory(ctx) → op.execute() → stop_running 槽内 current_op op.execute() 返回值

4.1 单跑道互斥:锁内原子 check-then-submit

单跑道互斥被收进 _start 的锁内:future 未完成检查与 executor.submit 在同一把锁中原子完成,消除跨槽 check-then-act 竞态(backend_context.py);框架层 run_context.start_running 不可重入是第二重保证。已存在运行时会返回 ok=False,适配器据此返回并发拒绝,避免同一 backend 进程内重复操作游戏资源。

4.2 单一事实源字段

槽内字段(单一事实源):source、op_id(app 路径=app_id、op 路径=package.path.ClassName 或类名)、run_type(APPLICATION / OPERATION)、app(展示名,_run 内固化)、started_at / finished_at、terminal_state、last_status、failed_node、current_op(op 路径回填,app 路径为 None)。运行状态枚举 RunState 为 idle / running / success / failed / stopped,无 STOPPING 态、无 PAUSED 态(backend_context.py)。

4.3 终态固化

_run 用顶层 try/except/finally 包裹(backend_context.py),任何路径(含 refresh_config / run_application 抛异常)都在 finally 中固化 terminal_state,避免卡在 RUNNING。终态判定规则:result.success → SUCCESS;status == '人工结束' → STOPPED;其余 → FAILED(仅 FAILED 记录 failed_node)。

4.4 进度读取统一

_query_status 的状态判据用固化字段 terminal_state,不读 run_context 推中间态:

  • 终态:返固化的 terminal_state + last_status / failed_node / 耗时;
  • 运行中(started_at 非 None 且 terminal_state 为 None):统一报 RUNNING,进度读 progress = current_op or run_context.current_application——因为 Application 也是 Operation,两者都有 _current_node / node_retry_times,可统一给出 current_node 与 retry_count;
  • 空闲(从未运行):返 idle。

ZzzBackendContext.query_status() 与 ZzzBackendContext.stop() 各自塌缩为一次 run_slot._query_status() / _stop(),不再跨槽仲裁(backend_context.py)。

4.5 配置刷新钩子

app 路径把 _refresh_runtime_config 作为 refresh_config 钩子注入 _run:在槽线程内、_start 已赢锁后、run_application 前执行——拒绝路径不进 _run,因此不刷新,修掉了原先跨方法刷新竞态;current_instance_idx 在刷新后重读(刷新可能切换实例)。刷新逻辑会删除 one_dragon_config 缓存、同步 current_instance_idx 与 reload_instance_config、清除应用工厂缓存(backend_context.py)。list_applications / list_operations 是只读路径,不刷新配置。

4.6 stop 语义

_stop 对未完成运行调 run_context.stop_running() 发信号(非阻塞);operation 实际退出有过渡期(下一轮才退),期间 _query_status 仍报 running,客户端应以 get_run_status / /game/status 轮询确认。

五、自定义 operation 运行入口:operation_registry

operation_registry.py 提供「按 operation 运行」的通用能力——不框死为调试用途;当前主要用于开发者复现 bug 时逐个 op 精确定位,未来智能体可经此自由组合 op。整个模块只做纯反射,不实例化任何 operation(实例化会构造 OpenAndEnterGame 等有副作用的依赖)。

5.1 扫描:scan_operations(ctx, refresh=False)

扫描 zzz_od.operation + zzz_od.hollow_zero 两个承载包下所有 .py 模块,对每个类做三重过滤(operation_registry.py):

  1. __module__ 守卫:排除 from ... import SomeOp 的 re-export 与基类;
  2. 显式抽象基类集(Operation / Application / ZOperation / ZApplication / OneDragonApp / GroupApplication / DropResoniumBase);
  3. *Base 命名兜底,并排除 Application 子类。

纯反射 __init__ 参数(剔除 self/ctx 与 *args/**kwargs),结果缓存,refresh=True 强制重扫;单模块 import 失败记入 failures 不中断整个扫描(operation_registry.py)。

5.2 解析:resolve_op_class(op_id)

按 <dotted module path>.<ClassName>(最后一个 . 拆分)经 importlib 解析出 Operation 子类,同样带 __module__ 守卫(防 re-export)与 issubclass(cls, Operation) 校验;格式非法、模块无该类、指向非定义模块、非 Operation 子类均抛 ValueError(operation_registry.py)。

5.3 校验:validate_args(cls, args)

校验 cls(ctx, **args) 可行性:必填参数齐全 + 无复杂数据类参数(有 coercible 能力的参数只接受 dict 值)+ 提供的值本身可 JSON 序列化(json.dumps 探测)。其余复杂数据类参数明确拒绝并提示「请走 application」(operation_registry.py)。

5.4 反序列化:coerce_dataclass_params(cls, args)

实例化前,把注解为「@dataclass + 有可调用 from_dict」的参数(如 ChargePlanItem)的 dict 值用 from_dict 反序列化为实例,使这类参数可经 JSON dict 传入 run_operation(operation_registry.py)。

5.5 描述:describe_operation(ctx, op_id)

纯反射返回单个 op 的参数 schema:每个参数标注 json_serializable(是否 JSON 原生可传)与 coercible(@dataclass+from_dict 可从 dict 反序列化);整体 debuggable = 所有必填参数都可传入(operation_registry.py)。

5.6 run_operation 的组装

run_operation 在适配器侧组合上述能力:resolve_op_class + validate_args 先校验,通过后把 cls + args 烤进闭包 op_factory = lambda ctx: cls(ctx, **args),提交 run_slot._start(op 路径,display_name=op_id)。槽只认统一签名 op_factory(ctx) → Operation,因此对 open_game 与自定义 op 一视同仁。

六、适配器:MCP 与 HTTP 双通道

MCP 与 HTTP 只做传输适配:

  • MCP 基础工具在 mcp/app.py,应用运行 + 自定义 op 工具在 mcp/service_app.py,prompt 在 mcp/prompts.py;
  • HTTP 基础端点在 http/routes.py,应用运行 + 自定义 op 与 /health 在 http/service_routes.py;
  • 应用运行类 tool / 端点只调 ZzzBackendContext 公开方法;自定义 op 类 tool / 端点额外经 operation_registry 校验后调 run_slot._start(op 路径)。

6.1 MCP 侧

MCP 采用 streamable-http 传输,端点 /mcp,共 22 个 @mcp.tool,多数一对一委托一个 backend 方法。核心工具包括:check_game_window / capture_game_screen(落盘返回路径)/ analyze_screen / open_game / click_game / input_text / key_tap / drag / list_applications / get_predefined_teams / run_one_dragon / run_standalone_app / list_operations / describe_operation / run_operation / get_run_status / stop_run / close_game / list_mcp_usage_guides / get_mcp_usage_guide(详细委托关系见 mcp.md)。

关键设计点(均可在 mcp.md 验证):

  • backend 实例通过闭包注入 tool,不使用全局单例,也不让 MCPServer lifespan 管 backend 生命周期;
  • MCPServer 2 会在 AnyIO 工作线程中执行同步 tool,同步 backend 方法不能依赖固定调用线程,OCR / YOLO 仍须通过项目的 gpu_executor 串行调用;
  • 所有运行类 tool 经同一个 RunSlot 派发;block=True 用 asyncio.wrap_future(future) 阻塞 await 取结果,block=False 立刻返回已启动状态,后续用 get_run_status 轮询;
  • get_run_status / stop_run 是统一入口,无论最近一次运行来自 op 路径还是 app 路径都可用同一组工具查询和停止;
  • 引导内容三通道:instructions(通常注入 system prompt)、prompts(@mcp.prompt(),客户端决定可见性)、help tool(list_mcp_usage_guides / get_mcp_usage_guide,通常可见)——三者分工互补。

MCP 客户端接入示例(Claude Code):

claude mcp add --transport http zzz_od http://127.0.0.1:23001/mcp

6.2 HTTP 侧

HTTP 是 web 前端 + skill 的共同目标——任何能发 HTTP 的客户端(含 AI 经 Bash / curl)都能用。核心端点(完整端点表见 http.md):

方法 端点 委托
GET /health backend 进程探测({"ok": true, "server": "zzz_od", "ready": bool})
GET /game/window backend.check_window()
GET /game/capture backend.capture()(PNG 字节,不落盘)
GET /game/analyze?save_image= backend.analyze()
POST /game/enter?block= backend.start_run('http', op_factory)
GET /game/applications backend.list_applications()
POST /game/run/one-dragon?block= backend.run_one_dragon('http')
POST /game/run/standalone?app_id=&block= backend.run_standalone_app('http', app_id)
GET /game/operations operation_registry.scan_operations(ctx)
GET /game/operations/describe?op_id= operation_registry.describe_operation(ctx, op_id)
POST /game/run/operation?op_id=&block= operation_registry 校验 + run_slot._start(op 路径)
GET /game/status backend.query_status()
POST /game/stop backend.stop()
POST /game/close backend.close_game()

HTTP 侧要点:

  • 处理器调 backend 走 asyncio.to_thread;BackendNotReadyError 统一返回 503 JSON;
  • 自定义 op 端点 op_id 走 query 参数,args 走 JSON body(空 body 时 args={}),block 走 query;业务失败一律 200 + body 内 error/started 标志,不引入 400/404/409;
  • 运行态三件套与 MCP 对称暴露:/game/enter ↔ open_game、/game/status ↔ get_run_status、/game/stop ↔ stop_run,两侧调同一 backend 方法,跨适配器状态共享同一 RunSlot(HTTP 触发的运行 MCP 也能查到)。

七、进程模型与启动方式

7.1 进程模型

  • entry/server.py 是 headless server 入口,会创建独立 ZContext();
  • GUI 主程序仍是另一个入口;「开发工具 -> MCP 服务」页面启动的是本机 server 子进程;
  • 当前只保证同一 backend 进程内的运行互斥;GUI 主进程与外置 server 子进程之间不做跨进程互斥;
  • 常驻 ZContext 可避免 OCR / YOLO 冷启动成本。

7.2 启动流程

_serve 的执行顺序(server.py):

  1. 创建 ZContext();
  2. 创建 ZzzBackendContext(ctx);
  3. await backend.start():经 asyncio.to_thread 在线程池中执行同步初始化(ctx.init(),含 OCR/onnx 模型加载、控制器构建,避免阻塞事件循环);
  4. create_app(backend):先 create_mcp_server 注册 MCP tools,再 register_http_routes 挂 /game/* 路由,最后 mcp.streamable_http_app() 得到 Starlette app——MCP /mcp 端点与 HTTP /game/* 端点同进程、同 app 共存;
  5. uvicorn.Server.serve() 监听本机端口(默认关闭 access log,避免状态轮询刷屏);
  6. 关闭时 backend.shutdown()(经 to_thread 执行 ctx.after_app_shutdown() 释放遥测、战斗上下文等资源)。

命令行启动:

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

CLI 参数:--host 默认 127.0.0.1,--port 默认 23001。启动后:

  • MCP:http://127.0.0.1:23001/mcp
  • HTTP 探测:http://127.0.0.1:23001/health

GUI 侧,「开发工具 -> MCP 服务」页提供本机 server 管理:用 /health 探测、用 /game/status 展示运行状态、尾读 .debug/zzz_od_mcp/main_server.log 滚动展示日志(日志仅用于 GUI 展示,不通过 MCP tool 返回给 agent)。依赖方面,后端 dev 组依赖 mcp>=2,<3(MCPServer / streamable-http)与 uvicorn(ASGI server)。

八、路线图(尚未实现)

原文档明确标注以下能力均属未实现路线图,读者请勿当作现有能力使用:

  • 事件推送:WebSocket / SSE 或 MCP notifications;
  • 多实例:list_instances / switch_instance;
  • 更多 game 感知与交互 tool;
  • 更完整的 AI 操作范式(如失败恢复、实例切换与多步巡检)。

HTTP 侧额外待办包括 /app/*(跑一条龙流程)、/instances/*(账号切换)端点与事件订阅(WebSocket / SSE)。

九、相关文档索引

围绕 backend 层的文档体系如下(均已转换为仓库根目录相对路径):

若需深入源码,核心实现文件为:

登录后查看全文
ZenlessZoneZero-OneDragon