贡献与验证

变更原则

• 保持改动小且可审查；不要顺手重构无关文件。
• 自动化仍应只通过 UI、OCR、系统音频和常规输入与游戏交互。
• 不要提交用户日志、截图、配置、账号信息、密钥或个人路径。
• 涉及战斗 planner、战斗状态、声音捕获或用户数据兼容性时，补充相应测试并说明风险。

外置角色的同目录导入

每个外置角色目录拥有独立的 Python 包命名空间。同队角色可以直接使用相对导入, 无需 __init__.py, 也不需要修改 sys.path 或手动维护 sys.modules:

from .zankou import get_rotation, make_rotation_next_action

供相对导入的文件名应使用合法 Python 标识符, 例如 zankou.py。 导入另一个角色类不会让当前文件重复注册; 每个角色文件仍只定义一个角色实现。 同一目录共享模块实例, 不同目录互相隔离。重新扫描时重新加载外置模块, 但不会替换已经创建的角色实例或重置方案自行挂在 task 上的状态。 避免角色文件之间循环导入。工坊 ZIP 的文件规则不变, 共享逻辑可以放在已声明的角色文件中。 导入使用 Python 标准机制, 也支持在方法内部延迟导入。扫描时会清除外置目录中 Python 源文件对应的当前解释器字节码缓存及已加载的外置模块, 以刷新修改后的代码。 若缓存清理失败, 本次扫描会记录警告并停止加载外置角色, 避免继续使用旧代码。 相对导入不是安全沙箱: 扫描外置角色仍会执行其 Python 代码。

文档贡献

• 将面向用户的说明放在“开始使用”“功能”或“指南”。
• 将 API、架构和实现说明放在“开发”。
• 新页面必须添加到根目录 mkdocs.yml 的 nav，否则不会出现在网站导航中。
• 使用相对 Markdown 链接；提交前运行严格构建检查断链和配置错误。

.\.venv\Scripts\python.exe -m mkdocs build --strict

代码验证

.\.venv\Scripts\python.exe -m unittest discover -s tests -p "*.py"

请在提交说明中写明已运行的验证，以及因环境限制未运行的验证。