agentSkill
HWP/HWPX 한글 문서를 파싱하여 Markdown으로 변환하는 스킬. hwpparser Python 라이브러리(https://github.com/HariFatherKR/hwp-parser)를 사용하여 한글 문서의 본문 텍스트, 메타데이터, HTML을 추출하고 구조화된 Markdown으로 출력한다. 사용자가 HWP, HWPX, 한글 문서, 한글 파일, 공문서, 정부 문서, 계약서 등 한글 워드프로세서 파일을 업로드하거나 경로를 제공하며 "읽어줘", "파싱해줘", "내용 추출", "마크다운으로 변환", "내용 보여줘", "분석해줘"
| name | hwp-parser |
| description | HWP/HWPX 한글 문서를 파싱하여 Markdown으로 변환하는 스킬. hwpparser Python 라이브러리(https://github.com/HariFatherKR/hwp-parser)를 사용하여 한글 문서의 본문 텍스트, 메타데이터, HTML을 추출하고 구조화된 Markdown으로 출력한다. 사용자가 HWP, HWPX, 한글 문서, 한글 파일, 공문서, 정부 문서, 계약서 등 한글 워드프로세서 파일을 업로드하거나 경로를 제공하며 "읽어줘", "파싱해줘", "내용 추출", "마크다운으로 변환", "내용 보여줘", "분석해줘" 등을 요청할 때 반드시 이 스킬을 사용한다. |
hwpparser Python 라이브러리를 활용해 HWP/HWPX 문서를 Markdown으로 파싱·출력한다.
bashpython3 -c "import hwpparser; print(hwpparser.__version__)" 2>/dev/null || \ pip install git+https://github.com/HariFatherKR/hwp-parser.git --break-system-packages -q
설치가 안 되어 있으면 위 명령으로 설치한다. PyPI에 올라와 있지 않으므로 반드시 GitHub에서 직접 설치해야 한다.
사용자가 파일을 업로드한 경우 업로드 경로를 사용한다:
bashls /mnt/user-data/uploads/
scripts/parse_hwp.py를 실행한다. 없으면 아래 코드를 /tmp/parse_hwp.py로 직접 생성 후 실행한다.
python#!/usr/bin/env python3 """HWP/HWPX → Markdown 변환 스크립트""" import sys import json import hwpparser from pathlib import Path def parse_to_markdown(file_path: str) -> dict: path = Path(file_path) result = { "file": path.name, "format": path.suffix.lower().lstrip("."), "metadata": {}, "text": "", "html": "", "markdown": "", "error": None } try: # 메타데이터 추출 try: meta = hwpparser.extract_metadata(path) result["metadata"] = meta except Exception as e: result["metadata"] = {"warning": str(e)} # 텍스트 추출 text = hwpparser.hwp_to_text(path) result["text"] = text # HTML 추출 (구조 정보 포함) try: html = hwpparser.hwp_to_html(path) result["html"] = html except Exception: pass # Markdown 조합 (텍스트 기반) lines = text.strip().split("\n") md_lines = [] for line in lines: stripped = line.strip() if not stripped: md_lines.append("") continue # 짧고 굵은 줄은 헤딩으로 추정 (20자 미만, 다음 줄이 내용) md_lines.append(stripped) result["markdown"] = "\n".join(md_lines) except Exception as e: result["error"] = str(e) return result if __name__ == "__main__": if len(sys.argv) < 2: print("Usage: python parse_hwp.py <file.hwp|file.hwpx>", file=sys.stderr) sys.exit(1) file_path = sys.argv[1] output = parse_to_markdown(file_path) if output["error"]: print(f"❌ 파싱 오류: {output['error']}", file=sys.stderr) sys.exit(1) # 메타데이터 출력 meta = output["metadata"] print("---") print(f"# 📄 {output['file']}") if meta: for k, v in meta.items(): if v and k != "warning": print(f"- **{k}**: {v}") print("---\n") # 본문 Markdown 출력 print(output["markdown"])
bash# 업로드된 파일 확인 ls /mnt/user-data/uploads/*.hwp /mnt/user-data/uploads/*.hwpx 2>/dev/null
bashpython3 -c "import hwpparser" 2>/dev/null || \ pip install git+https://github.com/HariFatherKR/hwp-parser.git --break-system-packages -q
bash# 스크립트를 /tmp에 저장 후 실행 python3 /tmp/parse_hwp.py "/mnt/user-data/uploads/파일명.hwp"
파싱된 Markdown을 대화창에 출력한다. 텍스트가 길면 섹션별로 나눠 보여준다.
사용자가 파일로 저장 원하면 /mnt/user-data/outputs/파일명.md로 저장 후 present_files로 제공한다.
에러 상황 | 대처 |
|---|---|
|
|
HWP 파일 열기 실패 | 파일 손상 여부 확인, HWPX 포맷인지 확인 |
텍스트가 비어있음 | HTML 추출로 재시도 ( |
인코딩 오류 |
|
입력 | 출력 |
|---|---|
| Markdown 텍스트 |
| Markdown 텍스트 |
HWPX는 현재 hwpparser 0.1.0 기준 입력 포맷 목록에 없을 수 있다.
입력 포맷 확인:python3 -c "import hwpparser; print(hwpparser.getsupportedinput_formats())"
사용자가 파일 저장을 원하는 경우:
pythonfrom pathlib import Path import hwpparser text = hwpparser.hwp_to_text("/mnt/user-data/uploads/파일명.hwp") out_path = Path("/mnt/user-data/outputs/파일명.md") out_path.write_text(text, encoding="utf-8") print(f"저장 완료: {out_path}")
