贡献指南 / Contributing Guide

感谢你愿意为 ok-ww 做贡献。本项目是基于图像识别的《鸣潮》自动化工具，使用 ok-script 开发，仅供个人学习与交流使用。提交贡献前，请先阅读简体中文文档中的免责声明、开发者专区和社区信息。

Thank you for contributing to ok-ww. This project is an image-recognition-based automation tool for Wuthering Waves, developed with ok-script, and is intended only for personal learning and communication. Before contributing, please read the disclaimer, developer section, and community information in the English documentation.

提交 PR 前 / Before Opening a PR

请先确认你的修改范围：

Please check the scope of your change first:

Bug 修复、文档修正、翻译修正、小型兼容性修复：可以直接提交 PR。
新功能、重构、架构调整、角色逻辑大改、任务行为大改、会显著改变现有功能体验的修改：请在提交 PR 前先联系作者或在社区中讨论，确认方向后再开始或提交。
不确定是否属于“大改”的修改：请先联系作者。
Bug fixes, documentation fixes, translation fixes, and small compatibility fixes: you may open a PR directly.
New features, refactors, architecture changes, major character logic changes, major task behavior changes, or changes that significantly alter existing behavior: please contact the author or discuss with the community before opening a PR.
If you are unsure whether a change is major, please contact the author first.

联系方式 / Contact

Discord: https://discord.gg/vVyCatEBgA

开发环境 / Development Environment

本项目仅支持 Python 3.12。建议使用仓库内的本地虚拟环境运行命令。

This project only supports Python 3.12. Prefer using the repository-local virtual environment when running commands.

# 安装或更新依赖 / Install or update dependencies
.\.venv\Scripts\python.exe -m pip install -r requirements.txt --upgrade

# 如需开发测试依赖 / For development test dependencies
.\.venv\Scripts\python.exe -m pip install ".[dev]" --upgrade

# 仅进行 Web 测试时需要 / Only for web testing
.\.venv\Scripts\python.exe -m pip install ".[dev,web-test]" --upgrade

# 运行 Release 版本 / Run release version
.\.venv\Scripts\python.exe main.py

# 运行 Debug 版本 / Run debug version
.\.venv\Scripts\python.exe main_debug.py

如果没有 .venv，可以使用 python 代替上面的解释器路径。

If .venv does not exist, use python instead of the interpreter path above.

测试 / Testing

提交 PR 前，请尽量运行相关测试，并在 PR 描述中说明测试结果。

Before opening a PR, please run the relevant tests when possible and include the results in the PR description.

.\run_tests.ps1

也可以直接运行指定测试：

You can also run a specific test directly:

.\.venv\Scripts\python.exe -m unittest tests\TestChar.py

PR 要求 / PR Requirements

提交 PR 前，必须使用 AI 审查最终修改，处理审查发现的有效问题，并在 PR 描述中简要说明审查工具、结果及处理情况。
保持修改范围清晰，避免把无关格式化、重构和功能修改混在同一个 PR 中。
说明改动目的、主要实现方式、影响范围和测试结果。
修改用户可见行为时，请补充截图、录屏或清晰的复现说明。
修改配置、任务、角色逻辑或识别逻辑时，请说明适用场景和可能影响。
不要提交日志、缓存、临时文件、个人配置或无关生成文件。
Before submitting a PR, have AI review the final changes, address valid findings, and briefly describe the review tool, results, and resolutions in the PR description.
Keep the PR focused. Avoid mixing unrelated formatting, refactoring, and feature changes in one PR.
Describe the purpose, implementation, impact, and test results.
For user-visible behavior changes, include screenshots, recordings, or clear reproduction notes.
For configuration, task, character logic, or recognition logic changes, describe the applicable scenarios and possible impact.
Do not commit logs, caches, temporary files, personal settings, or unrelated generated files.

添加识别素材 / Adding Recognition Assets

ok_templates/ 中的源图片和标注直接保存在本仓库中。

Source images and annotations in ok_templates/ are tracked directly in this repository.

如需添加识别素材，在 ok-ww 的「模板」标签页中添加图片并完成标注。
点击「保存」，保存标注并生成识别素材。
检查生成的修改，将相关的 ok_templates/ 源图片、标注和 assets/ 识别素材一起提交。
To add recognition assets, add the images and markup in ok-ww's Template tab.
Click Save to save the annotations and generate the recognition assets.
Review the generated changes and include the relevant ok_templates/ source images, annotations, and assets/ recognition assets in the same PR.

提交流程 / Submission Flow

Fork 本仓库并创建你的功能分支。
完成修改并运行相关测试。
确认是否需要先联系作者，尤其是新功能或大幅修改现有功能。
使用 AI 审查最终修改，处理有效问题并记录结果。
提交 PR，并填写 PR 模板中的所有相关内容，包括 AI 审查结果。
根据维护者反馈调整修改。
Fork this repository and create your feature branch.
Make the changes and run relevant tests.
Confirm whether author contact is needed, especially for new features or major changes to existing behavior.
Have AI review the final changes, address valid findings, and record the results.
Open a PR and fill in all relevant sections of the PR template, including the AI review results.
Update the PR based on maintainer feedback.