绝区零一条龙后端服务层架构:ZzzBackendContext 与 RunSlot 单跑道运行模型解析
绝区零一条龙后端服务层架构: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():通过控制器对游戏窗口截图,返回 RGBndarray,且会调用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):
__module__守卫:排除from ... import SomeOp的 re-export 与基类;- 显式抽象基类集(
Operation/Application/ZOperation/ZApplication/OneDragonApp/GroupApplication/DropResoniumBase); *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):
- 创建
ZContext(); - 创建
ZzzBackendContext(ctx); await backend.start():经asyncio.to_thread在线程池中执行同步初始化(ctx.init(),含 OCR/onnx 模型加载、控制器构建,避免阻塞事件循环);create_app(backend):先create_mcp_server注册 MCP tools,再register_http_routes挂/game/*路由,最后mcp.streamable_http_app()得到 Starlette app——MCP/mcp端点与 HTTP/game/*端点同进程、同 app 共存;uvicorn.Server.serve()监听本机端口(默认关闭 access log,避免状态轮询刷屏);- 关闭时
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 层的文档体系如下(均已转换为仓库根目录相对路径):
- backend/README.md - 后端服务层总览(总—分入口)
- backend/architecture.md -
ZzzBackendContext架构、生命周期、方法、资源约束、进程模型(本文主体) - backend/design-principles.md - 设计纲领:MCP tool 能力边界与设计原则
- backend/mcp-implementation.md - MCP tool 代码层落地规范
- backend/mcp.md - MCP 适配器(tool、传输、注册)
- backend/http.md - HTTP
/game/*适配器 - backend/entry.md - 服务入口、运行方式
- backend/remote-ssh.md - 远程 SSH daemon(Session 1 常驻,管主 server 启停)
若需深入源码,核心实现文件为:
- backend_context.py -
ZzzBackendContext+RunSlot完整实现 - operation_registry.py - 自定义 op 扫描 / 解析 / 校验 / 反序列化
- schemas.py - 传输无关 dataclass 定义
- entry/server.py - uvicorn 装配入口
- mcp/app.py、mcp/service_app.py、mcp/prompts.py - MCP 适配器
- http/routes.py、http/service_routes.py - HTTP 适配器