Communitygithub.com

leeryong/rhwp-Agent-Skills_by_BLUESKY

AI 代理操控韓文 (HWP/HWPX) 編輯器 rhwp-studio 的 GUI 層級操作與驗證代理技能集 (rhwp-gui-agent)。驅動 Rust/WASM HWP 編輯器,用於 AI 撰寫的韓文文件。

rhwp-Agent-Skills_by_BLUESKY 是什麼?

此技能集 (rhwp-gui-agent) 專為 AI 代理(例如 Claude Code、Codex)設計,使其能以 GUI 層級操作並驗證「rhwp-studio」——一個基於 Rust/WASM 的韓文 HWP/HWPX 編輯器。技能強烈建議優先使用真實 GUI 動作(點擊選單、工具列、對話框)來驗證功能,而非直接透過 JavaScript 橋接。當需要觀察編輯器狀態、載入測試樣本或驗證匯出結果時,才使用 `?agent=1` 橋接提供的 API(如 `window.__rhwpAgent.ready()`、`pageCount()`、`loadSample()` 等)。技能支援的命令與操作範圍涵蓋文件選單、工具列按鈕、樣式列、表格建立、形狀與符號對話框,以及 .hwp/.hwpx 的載入與匯出。透過 `references/feature-map.md` 可取得完整的功能對照表。測試策略分為三層:建置驗證(Docker 編譯 WASM)、GUI 冒煙測試(新增文件、輸入文字、切換格式、建立表格等),以及深度檢查(執行現有 e2e 測試與 hwpctl 情境)。常見失敗狀況包括連接埠衝突、瀏覽器啟動失敗、WASM 未建置、以及無頭 Chrome 缺乏 File System Access API 導致下載流程回退。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add leeryong/rhwp-Agent-Skills_by_BLUESKY

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

rhwp GUI Agent

使用此技能操控 rhwp-studio,它既是面向人類的網頁編輯器,也是可由代理控制的 GUI。功能檢查請優先使用真實 GUI 動作;僅在需要確認就緒狀態、檢查狀態、載入樣本及驗證匯出結果時,才使用 ?agent=1 橋接。

快速開始

從 rhwp 儲存庫根目錄執行:

cp .env.docker.example .env.docker
docker compose --env-file .env.docker run --rm wasm
cd rhwp-studio
npm ci
npm run build
python3 -m http.server 8765 --bind 0.0.0.0 -d dist

開啟 http://127.0.0.1:8765/?agent=1。如果沒有 ?agent=1,編輯器仍可供使用者操作,但不會暴露自動化橋接。

核心工作流程

  1. 執行 Studio 前,必須先建置 pkg/rhwp.js 和 pkg/rhwp_bg.wasm。如果 npm run build 顯示 Cannot find module '@wasm/rhwp.js',表示 WASM 套件尚未建置。
  2. 提供建置後的應用程式,或執行 Vite。當 Vite 無法在沙箱中綁定埠號時,請使用 python3 -m http.server ... -d dist。
  3. 啟動瀏覽器自動化工作階段,連線至 /?agent=1。
  4. 使用 GUI 選擇器執行操作:
    • 選單:#menu-bar .menu-item[data-menu="<menu>"] .menu-title
    • 選單命令:[data-cmd="<command-id>"]
    • 工具列按鈕:.tb-btn[data-cmd="<command-id>"]
    • 樣式列控制項:#style-name、#font-lang、#font-name、#font-size、#btn-bold、#btn-italic、#btn-underline、#btn-strike、#btn-text-color、#btn-highlight、對齊按鈕以及 #linespacing-select
    • 檔案輸入:#file-input
    • 畫布編輯器:#scroll-container canvas
  5. 使用 window.__rhwpAgent 進行觀察:
    • ready()
    • context()
    • commands()
    • pageCount()
    • fileName()
    • loadSample(path)
    • loadBytes(bytes, fileName)
    • createNewDocument()
    • exportHwp()、exportHwpx()
  6. 在每個功能群組後擷取螢幕截圖和匯出的檔案。將點擊失敗、命令停用、主控台錯誤和空白畫布視為測試失敗。

功能涵蓋範圍

在列舉或測試所有 GUI 功能時,請參閱 references/feature-map.md。該檔案列出了頂層選單、命令 ID、對話框、工具列控制項以及 hwpctl 動作。

若要執行自動化冒煙測試,請使用:

cd rhwp-studio
node e2e/agent-gui-full-smoke.mjs

如果環境禁止啟動瀏覽器,仍可執行:

npm run build

然後檢視 e2e/agent-gui-full-smoke.mjs,並在支援瀏覽器的環境中執行它。

測試策略

使用三層測試:

  1. 建置驗證:docker compose --env-file .env.docker run --rm wasm,接著 npm run build。
  2. GUI 冒煙測試:新增文件、輸入文字、切換字元/段落格式、建立表格、開啟圖形選擇器、開啟符號對話框、載入 .hwp 和 .hwpx 樣本、儲存/下載 .hwp,並擷取螢幕截圖。
  3. 深度檢查:當有真實瀏覽器可用時,執行現有的 rhwp-studio/e2e/*.mjs 測試與 hwpctl 情境。

優先使用內建樣本:

public/samples/basic/KTX.hwp
public/samples/form-002.hwpx
public/samples/BlogForm_BookReview.hwp
public/samples/biz_plan.hwp
public/samples/field-01.hwp
public/samples/footnote-01.hwp
public/samples/number-bullet.hwp

下載公開的 HWP/HWPX 樣本時,請將其儲存在 rhwp-studio/public/samples/external/ 下,載入前驗證檔案簽章,並記錄來源 URL、檔案名稱、位元組大小以及載入結果。

代理橋接規則

使用橋接來觀察狀態和載入可重複的測試固件,而非繞過 GUI 涵蓋範圍。對於像「表格建立功能正常」這類功能聲明,應點擊工具列/選單和對話框。對於像「文件已載入」這類聲明,使用 window.__rhwpAgent.pageCount() 是合適的。

不要僅因為命令出現在 HTML 中就假定它已實作。請與 src/command/commands/*.ts 交叉比對;某些選單項目是佔位符或會根據上下文停用。

常見失敗

  • listen EPERM:在允許的埠號上使用靜態伺服器,或在沙箱外執行。
  • 瀏覽器啟動失敗:在允許執行 Chrome/Chromium 的環境中執行腳本;必要時設定 CHROME_PATH。
  • HWPX 儲存停用:在目前測試版路徑中,來源為 HWPX 的文件會出現此預期行為。
  • @wasm/rhwp.js 遺失:使用 Docker 重建 WASM。
  • 無頭 Chrome 中無法使用 File System Access API:預期會回退至下載流程。

相關技能