開發指南

環境

專案使用 Python 3.12，維護時使用 Miniconda 的 oknikke 環境。

conda activate oknikke
python -m pip install -r requirements.txt --upgrade
python main_debug.py

測試

.\run_tests.ps1

也可以執行指定的 unittest 測試模組：

python -m unittest tests.TestMain

文件網站

安裝文件依賴並啟動本地預覽：

python -m pip install -r requirements-docs.txt
python -m mkdocs serve

執行嚴格構建：

python -m mkdocs build --strict

HTML 檔案生成在 site/ 目錄。推送涉及文件的修改到 master 後，GitHub Actions 會構建併發布 GitHub Pages。

構建應用

當前正式版本通過 GitHub Actions 構建。具體的歷史打包說明儲存在倉庫根目錄的 BUILD.md。

專案設計

任務模組、配置同步、頁面處理器和執行環境說明見軟體需求與設計。

提交修改

• 保持提交範圍清晰，不要混入日誌、快取、個人配置或無關生成檔案。
• 修改識別邏輯時說明適用頁面、識別區域、閾值和測試素材。
• 修改使用者可見行為時補充截圖、日誌或清晰的復現步驟。
• 提交 PR 前執行相關測試，並在 PR 描述中寫明結果。