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时,编辑器对用户正常工作,但不会暴露自动化桥接层。
核心工作流
- 在运行Studio之前,先构建
pkg/rhwp.js和pkg/rhwp_bg.wasm。如果npm run build报告Cannot find module '@wasm/rhwp.js',说明WASM包尚未构建。 - 提供构建后的应用或运行Vite。当Vite在沙箱中无法绑定端口时,使用
python3 -m http.server ... -d dist。 - 启动浏览器自动化会话,访问
/?agent=1。 - 使用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
- 菜单:
- 使用
window.__rhwpAgent进行观察:ready()context()commands()pageCount()fileName()loadSample(path)loadBytes(bytes, fileName)createNewDocument()exportHwp()、exportHwpx()
- 在每个功能集群后捕获截图和导出文件。将失败的点击、禁用的命令、控制台错误和空白画布视为测试失败。
功能覆盖
在枚举或测试所有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并在支持浏览器的环境中运行它。
测试策略
使用三层测试:
- 构建验证:
docker compose --env-file .env.docker run --rm wasm,然后npm run build。 - GUI冒烟测试:新建文档、输入文本、切换字符/段落格式、创建表格、打开形状选择器、打开符号对话框、加载
.hwp和.hwpx示例、保存/下载.hwp,并捕获截图。 - 深度检查:在有真实浏览器可用时,运行现有的
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中不可用:预期会使用回退下载流程。