貢獻與驗證

變更原則

保持改動小且可審查；不要順手重構無關檔案。
自動化仍應只通過 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"

請在提交說明中寫明已執行的驗證，以及因環境限制未執行的驗證。