Communitygithub.com

rhwp GUI Agent

让AI代理像人类一样操作HWP/HWPX编辑器rhwp-studio的GUI技能集。一套用于驱动Rust/WASM HWP编辑器、支持AI生成韩语文档的代理技能。

rhwp GUI Agent 是什么?

这个技能集(rhwp-gui-agent)使AI代理能够通过GUI层面操作和验证rhwp-studio——一个基于Rust/WASM的韩文(HWP/HWPX)网页编辑器。技能的核心是使用真实GUI操作(菜单、工具栏、画布)进行功能检查,同时提供一个可选的?agent=1自动化桥接层用于状态观察、样本加载和导出验证。它支持在Docker容器中构建WASM包,通过npm构建前端,并用Python静态服务器提供。该技能强调三层测试策略:构建验证、GUI冒烟测试和深度检查。代理可以通过window.__rhwpAgent对象调用ready()、context()、pageCount()、exportHwp()等方法,但必须优先使用GUI选择器(如CSS选择器)进行功能测试。技能文档包含常见错误排查指南,如端口占用、浏览器启动失败等。适用于Claude Code、Cursor或Codex等代理平台,在韩语文档处理的自动化测试和验证场景中特别有用。

兼容平台~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保存禁用:在当前beta路径下,对于HWPX源文档这是预期行为。
  • @wasm/rhwp.js缺失:使用Docker重新构建WASM。
  • 文件系统访问API在无头Chrome中不可用:预期会使用回退下载流程。

相关技能