ok-script 進階使用指南

English · 文件中心 · 快速開始 · 程式設計代理提示詞

通過 MCP 讓程式設計代理維護已經生成的可複用指令碼：讀取相關技能、檢查已安裝 API，並在原專案中修改。下面介紹素材、測試和分發；如何提出需求見程式設計代理提示詞。日常執行繼續使用儲存的 Python 實現，無需大模型呼叫。

本文件是 ok-script 自動化指令碼開發指南 的進階補充，旨在幫助開發者更深入地利用框架的高階功能，並結合 CI/CD 流程實現專案的自動化管理。

目錄

• 1. 模板匹配 (Template Matching)
• 2. 多語言國際化 (i18n)
• 3. 自動化測試
• 4. 使用 GitHub Actions 自動化打包與釋出
  • 關鍵步驟解析
    • 新增額外的原始碼內聯依賴
  • Sync Repositories 的國內映象功能
  • 配置多地區更新源
  • 打包產物說明
  • 加速構建速度

1. 模板匹配 (Template Matching) { #1-模板匹配-template-matching }

ok-script 使用 COCO 儲存可編輯的源截圖和標註。執行時使用獨立的 PNG 裁剪圖，檔名保留原始特徵名、源截圖解析度和位置，無需 COCO JSON。

核心優勢

• 保留相對位置: COCO 格式可以記錄每個標註模板在原始截圖中的相對位置。ok-script 利用這一資訊，在匹配時可以智慧地縮小搜尋區域，從而極大地提升匹配速度和準確度。
• 高解析度優先: 建議標註時使用的截圖採用您計劃支援的最高解析度（例如 4K）。當終端使用者在較低解析度下執行時，框架會自動將高畫質的模板素材縮放以進行匹配，保證了向下的相容性和識別效果。

操作流程

1. 保留源素材：在模板頁截圖並標註穩定的介面特徵。原始截圖與 coco_annotations.json 儲存在 ok_templates 中，供後續修改和重新匯出。
2. 拆分匯出：點選“儲存”，使用預設的 Split(Recommend)（拆分，推薦）。獨立應用選擇 assets，自定義指令碼選擇 ok_tasks/assets；PNG 輸出到所選目錄的 templates 子目錄。
3. 配置載入目錄：設定 template_matching.template_folder 為 assets/templates（預設值）。保留現有閾值、處理器和居中錨點設定；遷移時可以繼續保留 coco_feature_json。
4. 按名稱匹配：呼叫 find_feature、find_one 或 wait_feature 時使用原始特徵名，不傳入 PNG 檔名或座標字尾。

例如，settings_save_1920x1080_1480_920.png 表示特徵 settings_save，原始截圖解析度為 1920×1080，左上角座標為 (1480, 920)。PNG 自身的尺寸就是裁剪區域的尺寸。檔名沒有額外字首，也不編碼特徵名，支援空格、下劃線和中文；Windows 檔名不允許的字元會導致明確報錯。

匯出目錄僅用於模板 PNG。檔名無法解析時會報錯，即使只查詢單個特徵也會驗證該目錄內所有檔名。請修正報錯檔案，不要忽略錯誤或降低匹配閾值。Debug 模式不會代替顯式匯出步驟。

程式呼叫使用 generate_templates。舊壓縮選項和壓縮 API 已廢棄。完整的引數、遷移、驗證及 Windows 檔案許可權修復說明見模板匯出格式。

2. 多語言國際化 (i18n) { #2-多語言國際化-i18n }

為指令碼新增多語言支援可以擴大使用者群體，ok-script 內建了簡便的國際化流程。

實現步驟

1. 建立語言檔案: 在專案根目錄下，建立語言檔案。目錄結構必須遵循 i18n/<语言代码>/LC_MESSAGES/ 的格式，例如：
   • 英文: i18n/en_US/LC_MESSAGES/ok.po
   • 簡體中文: i18n/zh_CN/LC_MESSAGES/ok.po
2. 編輯 .po 檔案: 在這些檔案中，按照 gettext 格式編輯您的翻譯字串。
3. 一鍵編譯: 修改 .po 檔案後，無需執行任何命令列操作。只需在 ok-script 客戶端的開發者工具中，點選**“編譯 i18n”**按鈕。框架會自動將所有 .po 檔案編譯成二進位制的 .mo 檔案，程式執行時將自動載入對應的語言。

3. 自動化測試 { #3-自動化測試 }

為 Task 編寫單元測試是保證指令碼健壯性的關鍵。ok-script 提供了 TaskTestCase 基類，使得測試變得非常簡單。

測試實踐

• 穩定環境: 測試的核心是使用 self.set_image() 將螢幕輸入固定為一張靜態圖片，從而創造一個穩定、可復現的執行環境。
• 使用者問題復現: 除了使用自己擷取的標準測試圖，您還可以將使用者打包上傳的截圖檔案 作為測試圖片。這是一種非常高效的除錯手段，可以幫助您快速定位並解決在特定使用者環境中出現的問題。

示例：使用使用者截圖定位問題

# file: tests/test_user_issue.py
from ok.test.TaskTestCase import TaskTestCase
from src.tasks.MyProblematicTask import MyProblematicTask


class TestUserIssue(TaskTestCase):
    task_class = MyProblematicTask

    def test_scenario_from_user_screenshot(self):
        # 1. 使用用户提供的截图文件
        self.set_image('tests/user_screenshots/user_bug_report_01.png')

        # 2. 调用在用户环境中出错的特定方法
        result = self.task.some_method_that_failed()

        # 3. 断言修复后的行为是否符合预期
        self.assertIsNotNone(result, "The method should now handle this scenario correctly.")

執行測試

執行所有測試

要一次性執行 tests/ 目錄下的所有測試用例，可以直接執行專案根目錄下的 run_tests.ps1 指令碼。

在 PyCharm 中執行單個測試

為了進行更精細的除錯，例如只執行一個測試檔案或檔案中的某個特定方法，可以直接在 PyCharm 中操作：

1. 在程式碼編輯器中，右鍵點選測試檔案或某個 test_... 方法。
2. 選擇 "Run 'Unittests in ...'"。

重要提示：首次在 PyCharm 中執行測試時，需要修改其“執行/除錯配置”(Run/Debug Configuration)。請確保**“工作目錄”(Working directory)** 設定為專案的根目錄。否則，測試指令碼會因為找不到 tests/images/ 等相對路徑下的檔案而執行失敗。

4. 使用 GitHub Actions 自動化打包與釋出 { #4-使用-github-actions-自動化打包與釋出 }

您提供的 .github/workflows/build.yml 檔案定義了一個完整的自動化流程（CI/CD），它會在您每次推送新的版本標籤（如 v1.0.0 ）時，自動完成測試、打包和釋出。

該流程的核心是 PyAppify (https://github.com/ok-oldking/pyappify)，這是一個專門用於將 Python 專案打包成獨立 Windows 執行檔的工具，它通過專案根目錄下的 pyappify.yml 配置檔案進行驅動。

關鍵步驟解析 { #關鍵步驟解析 }

1. 觸發條件 (on): 工作流由推送 v* 格式的 Git 標籤觸發，是標準的版本釋出方式。
2. 安裝依賴與環境設定 (Install dependencies): 讀取 requirements.txt 並安裝所有依賴，為後續步驟做準備。
3. 原始碼內聯 (inline_ok_requirements): 將 ok-script、pyappify 以及額外配置的小型依賴庫整合到 Git 程式碼中，使其隨倉庫一起更新，無需單獨通過 pip 升級。
4. 執行自動化測試 (Run tests): 執行 tests/ 目錄下的所有單元測試，作為釋出的“質量門禁”。任何測試失敗都會中斷流程。
5. 同步倉庫與生成更新日誌 (Sync Repositories): 一個自定義 Action，用於將部分程式碼同步到輕量級的更新庫，並自動生成兩個版本標籤之間的更新日誌。
6. 打包執行檔 (Build with PyAppify Action): 呼叫 PyAppify 工具將 Python 專案打包成獨立的 Windows 執行檔。
7. 建立 GitHub Release (Release): 在 GitHub 上建立新的 Release，使用自動生成的更新日誌作為描述，並將打包好的執行檔作為附件上傳。

新增額外的原始碼內聯依賴 { #新增額外的原始碼內聯依賴 }

inline_ok_requirements 預設內聯 ok-script 和 pyappify。對於更新頻繁且體積較小、希望隨 Git 倉庫分發的 Python pip 庫，可以重複使用可選引數 --add-inlined-requirement PACKAGE=FOLDER：

python -m ok.update.inline_ok_requirements --tag "$env:RELEASE_TAG" `
  --add-inlined-requirement custom-package=custom_package `
  --add-inlined-requirement another-package=another_package

• PACKAGE：requirements.txt 中的 pip 發行包名稱，例如 custom-package。
• FOLDER：該庫在 site-packages 中需要複製的原始碼目錄，例如 custom_package。

使用 --tag 時，指令碼會從已安裝的依賴中複製 FOLDER，並從 requirements.txt 刪除對應的 PACKAGE。 若 deploy.txt 尚未包含 FOLDER 或其子路徑，指令碼會自動追加該目錄；已有條目不會重複新增。 此方式適合純 Python、小體積依賴；包含大型資源或依賴平臺二進位制檔案的庫，應繼續通過正常的依賴和打包流程管理。

Sync Repositories 的國內映象功能 { #sync-repositories-的國內映象功能 }

Sync Repositories 步驟的一個主要用途是同步程式碼到國內映象倉庫。對於無法流暢訪問 GitHub 的國內使用者，他們可以通過配置好的國內 Git URL 進行指令碼的自動更新，保證了更新渠道的暢通。

配置多地區更新源 { #配置多地區更新源 }

為了讓不同地區的使用者使用不同的更新源，您需要在 pyappify.yml 檔案中定義多個 profiles。這允許您為同一個專案打包出多個版本，每個版本內嵌了不同的更新地址。

pyappify.yml 配置示例:

name: "ok-ww"
uac: true

profiles:
  # 面向国内用户的配置
  - name: "China"
    git_url: "https://cnb.cool/ok-oldking/ok-wuthering-waves.git"
    # ... 其他配置
  # 面向全球用户的配置
  - name: "Global"
    git_url: "https://github.com/ok-oldking/ok-ww-update.git"
    # ... 其他配置

打包產物說明 { #打包產物說明 }

PyAppify Action 成功執行後，通常會生成以下檔案：

• ok-ww-win32-China-setup.exe: 面向國內使用者的完整安裝包。
• ok-ww-win32-Global-setup.exe: 面向全球使用者的完整安裝包。
• ok-ww-win32-online-setup.exe: 線上安裝包，需要聯網下載資源，不推薦普通使用者使用。
• ok-ww-win32.zip: 構建加速檔案。它包含了本次構建的啟動器 .exe，無法直接執行，其主要目的是用於加速下一次的構建流程。

加速構建速度 { #加速構建速度 }

啟動器 .exe 檔案（即 ok-ww-win32.zip 內的檔案）通常只在專案圖示變更或啟動器版本升級時才需要重新打包。在日常僅更新 Task 指令碼程式碼的情況下，我們可以複用上一次釋出中的啟動器來大幅縮短 GitHub Actions 的構建時間。

為此，可以在 pyappify-action 步驟中增加 use_release 配置：

- name: Build with PyAppify Action
  id: build-app
  uses: ok-oldking/pyappify-action@master
  with:
    # 使用上一个稳定版本的 Release 来获取已打包的启动器，从而跳过耗时的打包过程
    use_release: https://api.github.com/repos/ok-oldking/ok-wuthering-waves/releases/tags/v2.7.12

注意: 您需要將上面的 URL 替換為您自己專案的上一個穩定 Release 的 API 地址。這樣配置後，Action 會直接下載並使用該版本中的 ok-ww-win32.zip，從而跳過編譯啟動器exe的步驟。