Communitygithub.com

leeryong/rhwp-Agent-Skills_by_BLUESKY

AI 에이전트가 한글(HWP/HWPX) 편집기 rhwp-studio를 GUI 수준에서 조작·검증하도록 만든 에이전트 스킬 모음입니다.

rhwp-Agent-Skills_by_BLUESKY란 무엇인가요?

이 스킬은 AI 에이전트가 Rust/WASM 기반 한글 문서 편집기인 rhwp-studio를 GUI 수준에서 조작하고 검증할 수 있게 해줍니다. '?agent=1' 브릿지를 통해 상태 검사, 샘플 로딩, 내보내기 검증 등에 접근할 수 있으며, 실제 GUI 액션(메뉴 클릭, 툴바 버튼, 캔버스 상호작용)을 선호합니다. Docker로 WASM 패키지를 빌드하고, 정적 서버로 dist를 제공한 후 브라우저 자동화 세션을 시작하면 됩니다. 주요 기능으로는 문서 생성, 텍스트 입력, 서식 변경, 표 삽입, 샘플 로드, HWP/HWPX 내보내기, 스크린샷 캡처 등이 있으며, `window.__rhwpAgent` 객체를 통해 명령어 조회, 컨텍스트 확인, 페이지 수 확인 등을 수행할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add leeryong/rhwp-Agent-Skills_by_BLUESKY

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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 사용 불가: 대체 다운로드 흐름을 예상하세요.

관련 스킬