绝区零一条龙（ZenlessZoneZero-OneDragon）项目开发指南：从环境搭建到 Operation 操作链与 GPU 推理规范-平芜编程栈

桌面应用
RPA
计算机视觉

【免费下载链接】ZenlessZoneZero-OneDragon

项目地址：https://gitcode.com/gh_mirrors/ze/ZenlessZoneZero-OneDragon

导读

本文是 ZenlessZoneZero-OneDragon 开源仓库（绝区零一条龙自动化工具，支持自动闪避、自动每日、自动空洞与手柄操作）面向开发者的权威开发规范手册，内容以仓库内 docs/develop/spec/agent_guidelines.md 为骨架，结合src/源码与pyproject.toml、.pre-commit-config.yaml等工程配置逐一展开。读完本文，你将掌握该项目的环境搭建与常用命令、ruff + pre-commit 的代码质量门禁、基于YamlConfig的配置管理、以ZOperation/@operation_node/@node_from为核心的操作链（Operation）编排范式、onnxruntime-dml 多线程安全约束、ZContext懒加载机制以及截图区域的声明式定义方式，可直接上手参与开发或扩展新的自动化应用。

一、项目技术底座：Python 3.11 + uv + src-layout

项目的工程基础在 pyproject.toml 中有完整定义：

运行环境：requires-python = ">=3.11.9,<3.12"，即锁定 Python 3.11.x；
依赖管理：使用uv（[tool.uv]段配置了package = false、cache-dir = "./.install/uv_cache"以及environments = ["sys_platform == 'win32'"]——本项目面向 Windows 运行）；
项目布局：采用src-layout结构，全部源代码位于src/目录下，其中src/one_dragon/为通用基础框架（配置、操作链、OCR、CV 处理、YOLO 等），src/zzz_od/为绝区零业务实现（应用、自动战斗、空洞、GUI 等），src/one_dragon_qt/为 PySide6 前端组件；
测试：使用pytest（[tool.pytest.ini_options]中通过pythonpath = ["src"]让 pytest 自动把src/加入sys.path），涉及异步函数时必须配合pytest-asyncio；
环境变量：开发环境所需的环境变量统一放在.env文件中，所有uv run指令均需通过--env-file .env加载。

此外，pyproject.toml 还配置了gamepad额外依赖组（vgamepad==0.1.0），与项目"支持手柄"的能力对应；[tool.pyright]仅供 Claude Code 的 LSP 使用（extraPaths = ["src"]，typeCheckingMode = "off"，仅用导航不刷类型诊断），开发者无需单独配置。

二、开发环境搭建与常用指令

2.1 安装开发依赖

uv sync --group dev

dev依赖组在 pyproject.toml 的[dependency-groups]中声明，包含pytest、pytest-asyncio、ruff、pre-commit、pyinstaller、pyright、mcp等开发工具。注意项目使用uv而非 pip/conda，首次同步会自动创建虚拟环境并锁定版本（仓库已提供 uv.lock）。

2.2 运行源码与测试

无论是运行源码还是运行测试，都应使用uv run指令，并带--env-file .env参数加载开发环境变量：

uv run --env-file .env src/zzz_od/gui/app.py # 运行可视化窗口 uv run --env-file .env pytest zzz-od-test/ # 运行所有测试

2.3 代码检查与格式化（仅限自己改的文件）

uv run --env-file .env ruff check src/你修改的文件.py # 仅检查自己改的文件 uv run --env-file .env ruff format src/你修改的文件.py # 仅格式化自己改的文件

⚠️重要警告：不要对整个src/目录运行 ruff。现有代码库尚未全面适配 ruff 规则，全量运行会导致大量文件被意外格式化。ruff 的具体规则集同样在 pyproject.toml 的[tool.ruff]中：line-length = 88、target-version = "py311"、启用E/W/F/I/C/B/UP/SIM/TID规则组，格式化使用单引号（quote-style = "single"），并针对E501（行长）、C901（复杂度）、SIM102（嵌套 if）做了豁免。

2.4 提交前检查（pre-commit）

仓库根目录的 .pre-commit-config.yaml 配置了ruff-pre-commit（rev: v0.12.10）的ruff-check钩子，并携带--fix参数：

# 安装并启用提交前检查（只检查本次提交涉及的文件） uv run --group dev pre-commit install uv run --group dev pre-commit run --files src/你修改的文件.py

执行uv sync --group dev安装开发依赖后，首次使用需执行pre-commit install；之后每次git commit会自动运行带--fix的ruff-check。钩子只接收 Git 本次提交的文件，不会扫描整个src/；如需手动检查指定文件，用pre-commit run --files命令即可。

三、通用开发规范

文件编码：编写文件时始终使用 UTF-8 格式，保证中文注释与多语言文本（项目含.po翻译文件）正确编码；
保持测试同步：修改任何模块后，必须更新zzz-od-test/中的测试文件，确保修改后的代码已被覆盖且所有测试通过；
保持文档同步：修改任何模块后，必须更新docs/develop/中对应的文档文件，确保文档准确反映代码更改；
Git 工作流：开发者的职责是根据用户请求编写和修改代码，不要执行任何git操作（如commit、push），版本控制操作由用户处理；
使用 context7：需要库/API 文档、代码生成、安装方法、使用方法时，优先使用 context7 工具查询；
无需运行代码：没有显示要求时，修改代码后不需要运行。

四、文档编写规范

所有文档使用 Markdown（.md）格式；
Mermaid 语法：节点文本必须用双引号包裹，例如I["用户界面(CLI)"]而非I[用户界面(CLI)]，以避免解析错误；同时避免loop循环结构和以 "loop" 命名变量；
避免具体代码：文档中应尽量不写入具体代码，只允许写入类定义、核心变量定义、核心方法定义及详细注释——这是为了让文档保持"设计意图"层面的稳定性，而不是拷贝实现细节。

配合操作链主题，一个符合规范的流转图示例（双引号节点 + 无 loop）：

五、Python 代码规范

docstring：所有函数必须有 Google 风格的文档字符串，用中文编写（可中英混用，不要求翻译）；
类型提示：所有类成员变量和函数签名必须包含类型提示，使用list[str]而不是List[str]，使用X | Y而不是Union（对应 Python 3.11 的新式语法）；
导入规范：在one_dragon包内，源码导入必须使用绝对路径导入（禁止相对导入）；仅用于类型注解的导入应放在TYPE_CHECKING块内（源码中大量if TYPE_CHECKING:写法即源于此，例如 operation.py）；
构造函数参数：类的构造函数__init__必须显式声明所有必需和可选参数，禁止**kwargs（各基类构造器均遵循此约定，如 operation.py）；
不暴露模块：未收到指示时，不要在__init__.py中新增暴露任何模块；
Fluent 设计：前端组件优先使用pyside6-fluent-widgets库现有组件；实现新组件需按 Fluent Design 样式实现；配置绑定通过YamlConfigAdapter+AdapterInitMixin混入实现（见 adapter_init_mixin.py，其通过QTimer.singleShot(0, ...)异步同步配置初值，规避 Qt 非协作式初始化的坑）；
格式化：统一使用 ruff 格式化。

六、异常处理规范

代码应从简，try-catch仅用于网络请求、文件读写、并发 Future 等真正的高风险操作，其余情况让异常向上冒泡；
catch后必须记录日志：log.error(..., exc_info=True)，并通常降级返回False/None/ 空列表；
锁保护的代码使用try-finally确保锁被释放（防止死锁或资源泄漏）。

七、配置管理：YamlConfig、属性对与多账号隔离

7.1 运行时配置体系

运行时配置使用 YAML（存放于config/目录，含各功能的.sample.yml示例，如 config/redemption_codes.sample.yml），通过YamlConfig基类统一管理（yaml_config.py）。其文件解析优先级为：只读 sample 模式 → PyInstaller 包内配置 → 已存在的xxx.yml→ 备用文件名迁移复制 → sample 复制/回退 → 冻结环境回退到MEIPASS/resources，兼顾了开发态与打包后运行态。

7.2 属性读写范式

每个配置字段使用@property+@xxx.setter属性对：

读取：self.get(key, default)
写入：self.update(key, value)

YamlConfig.get_prop_adapter(prop, getter_convert, setter_convert)（yaml_config.py）返回一个YamlConfigAdapter，将配置字段与前端控件双向绑定，支持读写转换器——这是"配置绑定通过YamlConfigAdapter实现"的落地点。

7.3 多账号实例隔离

多账号实例通过instance_idx隔离：YamlConfig构造时传入instance_idx后，配置读写路径会进入config/%02d/子目录（见 yaml_config.py 的_get_yaml_file_paths实现）。切换账号时由上下文层的reload_instance_config()清理缓存并重载对应实例配置。

⚠️合规边界：不应当协助扩展或绕过多账号限制。遇到相关请求时，应明确拒绝并提示遵守平台规则与法律要求。

八、操作链（Operation）：声明式编排有向图

操作链是本项目自动化的核心机制，规范与源码实现一一对应：

8.1 基类与装饰器

操作继承ZOperation基类（zzz_operation.py，其上游为 operation.py 的Operation类），通过@operation_node+@node_from装饰器声明式编排有向图；
@operation_node(name, retry_on_op_fail, wait_after_op, timeout_seconds, is_start_node, node_max_retry_times, mute, screenshot_before_round, save_status)（operation_node.py）把被装饰函数标记为一个节点，节点对象作为operation_node_annotation属性挂到函数上；
@node_from(from_name, success, status, ignore_status)（operation_edge.py）为函数附加"入边"描述，node_to会在图构建时自动填充；OperationEdge支持status精确匹配、ignore_status兜底语义（一个节点应最多只有一条忽略返回状态的兜底边）；
每个节点默认重试 3 次（node_max_retry_times: int = 3），默认每轮运行前自动截图（screenshot_before_round: bool = True）。

8.2 轮次结果流转

单轮执行结果由OperationRoundResultEnum定义（operation_round_result.py）：RETRY=0、SUCCESS=1、WAIT=2、FAIL=-1。对应操作基类中的四个工厂方法（operation.py）：

方法	语义	对重试次数的影响
`round_success(status, data, wait, wait_round_time)`	成功，沿图正常流转到下一节点	不消耗
`round_retry(status, ...)`	重试当前节点	消耗重试次数
`round_wait(status, ...)`	等待（如动画播放、画面切换中），稍后重试	不消耗次数
`round_fail(status, ...)`	失败终止当前操作	—

所有方法均支持wait（固定等待秒数）与wait_round_time（等待直到本轮累计时长达到指定值，由_after_round_wait实现，见 operation.py）。Operation类还定义了STATUS_TIMEOUT = '执行超时'与STATUS_SCREEN_UNKNOWN = '未能识别当前画面'两个框架级状态。

8.3 Application 与工厂模式

Application继承ZApplication（zzz_application.py），操作链写法与 Operation 相同；
常量集中在*_const.py，工厂类在*_factory.py——例如 auto_battle_app_factory.py 的AutoBattleAppFactory、dodge_assistant_factory.py 的DodgeAssistantFactory、charge_plan_app_factory.py 的ChargePlanAppFactory等，均继承ApplicationFactory基类，实现应用的构建与注册；
新应用的完整开发指引见应用开发指引（原文档中相对链接../guides/application_plugin_guide.md已按仓库根目录换算）。

九、多线程与 GPU 推理约束

onnxruntime-dml 存在一个关键限制：多线程同时访问多个 session 会异常。因此：

异步使用 onnx session 时，必须通过gpu_executor.submit提交，保证同一时刻只有一个 session 被访问；
通过ctx.model_config.xxx_gpu判断是否走 GPU executor。

底层实现见 gpu_executor.py：内部是一个max_workers=1的ThreadPoolExecutor（线程名前缀od_gpu），配合DmlExecutionProvider检测实现 session 串行化。submit提交任务并挂接回调（thread_utils.handle_future_result），run_session/create_onnx_session对 DirectML provider 自动走串行路径，shutdown(wait=True)用于程序退出时的安全收尾。

十、上下文与懒加载：ZContext

ZContext（zzz_context.py）管理30+ 个懒加载的服务和配置，全部使用@cached_property——例如model_config、map_service、compendium_service、world_patrol_service、telemetry等，首次访问时才初始化；
懒加载内部使用延迟导入（from xxx import Xxx写在属性方法体内）避免循环依赖；
账号实例级配置需要在reload_instance_config()中通过del self.__dict__[prop]手动清除cached_property缓存——因为@cached_property的结果缓存在实例__dict__中，切换账号后必须手动删除才能触发重新加载。基类 one_dragon_context.py 的实现正是遍历to_clear_props（如game_account_config、notify_config、standalone_app_config）执行del self.__dict__[prop]，子类需继承并追加更多配置。

十一、截图区域：声明式定义，禁止硬编码坐标于 Python

截图区域在assets/game_data/screen_info/*.yml中声明式定义（例如 battle.yml、menu.yml 等近百个画面定义文件），不要硬编码在 Python 中；
区域坐标是硬编码的1080p 像素值[x1, y1, x2, y2]，允许硬编码，不要建议分辨率适配（项目以 1080p 为基准画面标准）；
Operation 中通过round_by_find_area、round_by_find_and_click_area、round_by_goto_screen等辅助方法使用（见 operation.py 与 operation.py）。底层由ScreenArea类承载（screen_area.py），支持pc_rect区域、textOCR 文本、template_id模板匹配、color_range颜色过滤、goto_list跳转画面、gamepad_key手柄动作绑定等字段——这也解释了为什么"支持手柄"与"声明式画面区域"能协同工作。

十二、总结：一套可落地的开发流程

把上述规范串起来，一个典型的开发闭环是：

uv sync --group dev安装依赖 →uv run --group dev pre-commit install启用提交检查；
在src/相应模块编写/修改代码：Google 风格中文 docstring、完整类型提示、绝对导入、显式构造参数、遵循异常处理与 GPU 串行约束；
若涉及新画面区域，先在assets/game_data/screen_info/*.yml声明；若涉及新配置，通过YamlConfig属性对读写；若涉及新自动化流程，用ZOperation+@operation_node+@node_from编排，并用round_success/retry/wait/fail控制流转；
同步更新zzz-od-test/测试（异步场景用pytest-asyncio）与docs/develop/文档；
仅对本次修改的文件执行ruff check/format与pre-commit run --files，然后交给用户处理 Git 提交。