GUI Agent rhwp
Use esta habilidade para operar o rhwp-studio tanto como um editor web voltado para humanos quanto como uma GUI controlável por agente. Prefira ações reais de GUI para verificações de funcionalidades; use a bridge ?agent=1 apenas para prontidão, inspeção de estado, carregamento de amostras e verificação de exportação.
Início Rápido
A partir da raiz do repositório 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
Abra http://127.0.0.1:8765/?agent=1. Sem ?agent=1, o editor funciona para usuários, mas não expõe a bridge de automação.
Fluxo de Trabalho Principal
- Compile
pkg/rhwp.jsepkg/rhwp_bg.wasmantes de executar o Studio. Senpm run buildrelatarCannot find module '@wasm/rhwp.js', o pacote WASM ainda não foi compilado. - Sirva o aplicativo compilado ou execute o Vite. Use
python3 -m http.server ... -d distquando o Vite não conseguir vincular portas em um sandbox. - Inicie uma sessão de automação de navegador contra
/?agent=1. - Use seletores de GUI para ações:
- Menus:
#menu-bar .menu-item[data-menu="<menu>"] .menu-title - Comandos de menu:
[data-cmd="<command-id>"] - Botões da barra de ferramentas:
.tb-btn[data-cmd="<command-id>"] - Controles da barra de estilo:
#style-name,#font-lang,#font-name,#font-size,#btn-bold,#btn-italic,#btn-underline,#btn-strike,#btn-text-color,#btn-highlight, botões de alinhamento e#linespacing-select - Entrada de arquivo:
#file-input - Editor canvas:
#scroll-container canvas
- Menus:
- Use
window.__rhwpAgentpara observação:ready()context()commands()pageCount()fileName()loadSample(path)loadBytes(bytes, fileName)createNewDocument()exportHwp(),exportHwpx()
- Capture capturas de tela e arquivos exportados após cada cluster de funcionalidades. Trate cliques com falha, comandos desabilitados, erros de console e canvas em branco como falhas de teste.
Cobertura de Funcionalidades
Leia references/feature-map.md ao enumerar ou testar todas as funcionalidades da GUI. Ele mapeia os menus de nível superior, IDs de comando, diálogos, controles da barra de ferramentas e ações do hwpctl.
Para uma execução automatizada de smoke test, use:
cd rhwp-studio
node e2e/agent-gui-full-smoke.mjs
Se a inicialização do navegador for bloqueada pelo ambiente, ainda execute:
npm run build
Em seguida, revise e2e/agent-gui-full-smoke.mjs e execute-o em um ambiente com suporte a navegador.
Estratégia de Teste
Use três camadas:
- Validação de build:
docker compose --env-file .env.docker run --rm wasm, depoisnpm run build. - Smoke de GUI: crie um novo documento, digite texto, alterne formatação de caractere/parágrafo, crie uma tabela, abra o seletor de formas, abra o diálogo de símbolos, carregue amostras
.hwpe.hwpx, salve/baixe.hwpe capture capturas de tela. - Verificações profundas: execute os testes existentes em
rhwp-studio/e2e/*.mjse cenários do hwpctl quando um navegador real estiver disponível.
Prefira amostras internas primeiro:
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
Ao baixar amostras públicas de HWP/HWPX, salve-as em rhwp-studio/public/samples/external/, verifique a assinatura do arquivo antes de carregar e registre a URL de origem, nome do arquivo, tamanho em bytes e resultado do carregamento.
Regras da Bridge do Agente
Use a bridge para observar o estado e carregar fixtures de teste repetíveis, não para contornar a cobertura da GUI. Para uma afirmação de funcionalidade como "criação de tabela funciona", clique na barra de ferramentas/menu e diálogo. Para uma afirmação como "o documento foi carregado", window.__rhwpAgent.pageCount() é apropriado.
Não assuma que um comando está implementado só porque aparece no HTML. Verifique com src/command/commands/*.ts; alguns itens de menu são placeholders ou estão desabilitados dependendo do contexto.
Falhas Comuns
listen EPERM: use um servidor estático em uma porta aprovada ou execute fora do sandbox.- Falha ao iniciar navegador: execute o script onde a execução do Chrome/Chromium é permitida; defina
CHROME_PATHse necessário. - Salvamento de HWPX desabilitado: esperado para documentos com origem HWPX no caminho beta atual.
@wasm/rhwp.jsausente: reconstrua o WASM com Docker.- API de acesso ao sistema de arquivos indisponível em headless Chrome: espere o fluxo de download de fallback.