---
name: hwpx-document
description: HWP/HWPX 문서 분석·작성·수정 시 사용. 첨부 가져오기와 작업별 도구 선택을 안내합니다.
---

# HWPX 문서 작업

사용자가 요청한 부분을 원본 보존 복사본에 반영합니다. 분석만 요청하면 분석만 하고, 일부 작성이면 나머지 항목은 그대로 둡니다. 고정된 인터뷰나 모든 필드 확정은 필요하지 않습니다.

## 파일 열기

- 로컬 첨부는 사용자가 전달한 실제 절대 경로로 `import_local_hwpx(path)`를 호출합니다. 다운로드/프로젝트 폴더도 이 도구로 가져옵니다.
- 새 작업에서는 새로 가져오고, 같은 작업에서는 반환된 `local_path`를 재사용합니다. 다른 채팅의 입력값이나 승인 상태를 가져오지 않습니다.
- 웹 업로드 객체는 `import_uploaded_hwpx(file)`을 사용합니다.
- 도구가 안 보이면 호스트 도구 검색으로 이름을 검색합니다. 다른 문서 세션 도구는 HWPX MCP 연결 확인을 대신하지 않습니다.
- `inspect_document`는 형식 검사, `analyze_document`는 구조·필드 분석입니다. 이미 성공한 분석은 반복할 필요가 없습니다.

## 작업 도구

양식은 `hwpx-form-fill`, 서식은 `hwpx-styling`, 그림은 `hwpx-picture`, 결과 확인은 `hwpx-verification`을 참고합니다. 전체 양식 작성·테스트값 입력이면 `hwpx-form-fill`을, 수정본 확인 단계면 `hwpx-verification`을 반드시 읽습니다.

### 전체 양식 작성의 필수 위치 확인

일반 양식 작성에서는 아래 순서를 바꾸거나 건너뛰지 않습니다.

1. 가져오기가 끝나면 반환된 `local_path`로 `analyze_document`를 한 번 호출합니다.
2. 분석 결과의 `next_action`을 확인합니다. 값이 `confirm_visual_candidates`이면 즉시 `confirm_visual_candidates(path, candidates=[])`를 호출합니다. 분석 상태가 `ANALYZED`인 것은 실패가 아닙니다.
3. 그 다음에만 `list_document_fields`를 호출합니다. 미리보기에는 이 응답의 `field_id`만 사용합니다. `section0.table…` 형태의 원시 셀 ID, `target_id`, overflow/geometry 결과의 ID를 `current_field_id`나 `field_ids`에 넣지 않습니다.
4. 사용자가 값을 모두 제공했어도 가까운 2~4개 항목씩 `preview_field_section(path, current_field_id, field_ids)`을 호출합니다. 한 질문에 여러 선택지가 속하면 그 선택지를 모두 `field_ids`에 넣습니다.
- 반환된 `preview_path` 문자열을 축약하거나 `~`로 바꾸거나 새 파일명을 만들지 말고, 괄호 안을 도구가 반환한 실제 절대경로 값으로 바꾼 `![현재 질문 위치](/Users/.../실제-preview.png)`를 답변 본문에 넣습니다. 문자 그대로 `(preview_path)`라고 쓰지 않습니다. “파란 박스 위치들이 맞나요?”라고 물은 뒤 답변을 기다립니다. 최초 요청의 값은 위치 승인이 아닙니다.
- 사용자가 미리보기를 보고 맞다고 답하기 전에는 `create_edit_plan`을 호출하지 않습니다. 여러 묶음이면 각 묶음을 같은 방식으로 확인하며, 이미 받은 값은 다시 묻지 않습니다.

NEEDS_HUMAN인 경우에만 이미지와 대상 셀을 확인합니다. 수동 후보는 `{"candidate_id":"…","decision":"confirmed","field":{…}}` 형식이며, 전체 field 목록을 평평하게 전달하지 않습니다.

일반적인 `import_local_hwpx`/`import_uploaded_hwpx` 기반 양식 작성 중에는 `register_document`, workflow용 `analyze_document(document_id, workflow_id)`, `get_workflow_status`, `retry_step`으로 전환하지 않습니다. 경로 기반 양식 흐름과 별도 workflow_id 수명주기를 섞지 않습니다. `open_hwpx_workspace`는 사용자가 웹 뷰어를 요청했을 때만 열며 필드 분석·위치 확인을 대신하지 않습니다.

## 수정과 전달

계획은 도구 내부의 변경 기록입니다. 사용자에게 별도의 계획서 작성·검토를 매번 요구하지 말고, 명확한 수정 요청은 아래 호출을 이어서 처리합니다. 선택이 필요한 변경만 질문합니다.

1. 요청한 변경만 `create_edit_plan(path, edits)`에 넣습니다. disposition은 선택 사항이며 편집 대상은 기본 provided입니다. 나머지는 변경되지 않습니다.
2. 사용자가 그 변경을 명확히 요청하거나 승인했다면 `approve_edit_plan(path, plan_id, user_confirmed=True)`로 중복 확인을 생략합니다. 이는 에이전트의 채팅 승인 확인 기록이지 별도 UI 승인 증거가 아닙니다. 모호한 범위는 먼저 확인합니다.
3. `apply_edit_plan`으로 복사본을 생성합니다. 실제 operations와 사용자에게 설명한 변경 목록을 대조합니다. 일부만 계획했다면 전체 작성 완료라고 보고하지 않습니다.
4. 적용 후 `apply_edit_plan`이 반환한 `user_preview_paths`의 실제 절대경로를 답변 본문에 `![수정 결과](/Users/.../실제-preview.png)`로 직접 표시하고 “이 결과로 최종본을 만들까요?”라고 물은 뒤 답변을 기다립니다. 내부 `workspace_dir`, `modified/page_*.png` 경로를 추측하거나 검색하지 않습니다. `view_image`로 내부 확인만 하거나 파일 링크만 주는 것은 사용자에게 보여준 것이 아닙니다. 확인 전에는 Vision 검토·최종화를 진행하지 않습니다.
5. `PENDING_VISION_REVIEW`는 수정 완료·시각 검증 전입니다. `finalize_document`는 사용자가 결과를 확인하고 Vision PASS가 기록된 뒤 검증된 최종본을 만들 때 사용합니다.

원본 덮어쓰기·외부 제출은 별도 요청이 필요합니다. 파일 형식과 대상 검사는 유지하며, 도구 오류를 우회하려고 임시 MCP 클라이언트나 직접 XML 편집으로 전환하지 않습니다.

## 복구

- 승인 취소/미승인은 연결 오류가 아닙니다. 취소 후에는 새로 명확한 승인을 받은 경우에만 같은 계획의 승인 호출을 진행합니다.
- 승인 대기·승인 완료·수정 실패(NEEDS_HUMAN) 상태에서는 같은 local_path로 `create_edit_plan`을 다시 호출하여 기존 계획을 교체할 수 있습니다. 새 파일 가져오기나 전체 인터뷰는 필요하지 않습니다. 계획 생성 오류를 매핑 오류로 추정하지 않습니다.
- 재계획의 edits는 원본 기준으로 아직 적용하려는 변경 목록입니다. 사용자가 조정한 필드의 정책만 바꾸고 나머지 요청 값은 유지합니다. 새 plan_id로 승인·적용하며, 이전 계획의 승인이나 plan_id는 재사용하지 않습니다. 사용자의 조정 답변으로 범위가 명확하면 추가 승인 질문은 하지 않습니다.
- 인자 오류는 스키마에 맞춰 해당 호출만 재시도합니다.
- 글자 넘침/잘림으로 계획·적용·검증이 막히면 실패 보고로 대화를 끝내지 말고 `hwpx-styling`의 '넘침 발생 시 사용자에게 질문' 안내에 따라 처리 방법을 묻고 답을 기다립니다. 질문 전 임의 축약·전체 글자 축소·항목 제외·새 가져오기로 반복 시도하지 않습니다.
- 인터뷰 저장, 파일 수정, 검증 완료를 구분해 짧게 보고합니다. 내부 ID·영수증은 필요할 때만 보여줍니다.