실제 자동화 성공사례
Cách thực tế để chuyển đổi 1.659 tệp HWP Hancom (한글) sang Markdown chỉ trong 6 phút
Đây là ví dụ về tự động hóa được đọc nhiều nhất trên kimkj.com. Điểm mấu chốt là quy trình chuyển đổi hàng loạt tài liệu HWP/HWPX ngay trên máy tính cá nhân mà không cần tải tệp lên các dịch vụ bên ngoài, sau đó xử lý hậu kỳ cùng với Claude Code.

Xử lý hàng loạt 1.659 tài liệu Hancom (한글)
Tổng thời gian chuyển đổi là 6 phút
Xử lý cục bộ, không tải tài liệu nhạy cảm ra bên ngoài


Đầu tiên, phân loại tệp HWP và HWPX để giảm thiểu nguyên nhân gây lỗi chuyển đổi.
Thực hiện chuyển đổi hàng loạt trong terminal và lập danh sách các tệp bị lỗi riêng biệt.
Sắp xếp các tệp đã chuyển sang Markdown thành cấu trúc thư mục dễ đọc cho Claude Code.
Xử lý hậu kỳ các phần tiêu đề, mục lục, đoạn văn trùng lặp và ký tự bị lỗi.


110 ví dụ thực tế về Claude Code
Chinh phục hoàn toàn Claude Code
Học từ đầu





Cách chuyển đổi 1.659 tệp Hancom (한글) sang tệp Markdown
(Chỉ cần yêu cầu người bạn đồng hành Claude Code thực hiện)


Hướng dẫn chuyển đổi hàng loạt HWP/HWPX → Markdown cục bộ
Không cần dịch vụ bên ngoài, ngay trên máy tính của bạn, chỉ với vài dòng lệnh terminal


Trên máy tính có 1.659 tệp Hancom (한글). Gồm 563 tệp HWP và 1.096 tệp HWPX. Toàn bộ bản thảo, tài liệu pháp lý, tài liệu giảng dạy, nhật ký du lịch và báo cáo chính sách tích lũy trong nhiều năm đều đang bị kẹt ở định dạng Hancom. Để trí tuệ nhân tạo (AI) có thể đọc được, chúng ta cần trích xuất văn bản. Việc mở từng chương trình Hancom và thực hiện sao chép-dán 1.659 lần là điều bất khả thi.
Chỉ với một thư viện mã nguồn mở Python, mọi việc đã xong xuôi trong 6 phút. Tỷ lệ thành công đạt 99,3%.


HWP và HWPX khác nhau như thế nào?
HWPX thực chất là một tệp nén ZIP. Nếu đổi phần mở rộng thành .zip và giải nén, bạn sẽ thấy các tệp XML. Nội dung chính nằm ở Contents/section0.xml, và cấu trúc XML được sắp xếp rất khoa học theo dạng p (đoạn văn) > run (định dạng) > t (văn bản). Vì Hancom (한컴) xây dựng định dạng này dựa trên tiêu chuẩn công khai OWPML (KS X 6101) nên việc phân tích dữ liệu rất thuận lợi.
HWP là định dạng tệp nhị phân kiểu cũ. Nó sử dụng cấu trúc container OLE2 tương tự như tệp .doc của Microsoft Word. Dữ liệu bên trong được nén bằng zlib và có cấu trúc bản ghi phức tạp. Tuy nhiên, nhờ Hancom đã công khai đặc tả nhị phân nên hiện có sẵn các bộ phân tích mã nguồn mở.
Cả hai đều có thể chuyển đổi được. Công cụ đó tên là pyhwp2md.


Công cụ then chốt: pyhwp2md
Sau khi nghiên cứu nhiều mã nguồn mở, tôi đã tìm thấy thư viện Python mang tên pyhwp2md. Thư viện này sử dụng giấy phép MIT, có khả năng chuyển đổi cả HWP (nhị phân) và HWPX (XML) sang Markdown. Bên trong, nó kết hợp sử dụng pyhwp (bộ phân tích nhị phân) và python-hwpx (bộ phân tích XML). Các đoạn văn, tiêu đề và thậm chí cả bảng biểu đều được chuyển đổi thành công.


Bước 1. Cài đặt Python 3.10 trở lên
pyhwp2md yêu cầu phiên bản Python từ 3.10 trở lên. Phiên bản Python mặc định trên macOS thường là 3.9.6 nên sẽ không hoạt động. Bạn hãy cài đặt thông qua Homebrew.
Lệnh terminal:

# Kiểm tra phiên bản Python hiện tại

python3 --version



# Nếu thấp hơn 3.10, cài đặt qua Homebrew

/opt/homebrew/bin/brew install python@3.12



# Xác nhận cài đặt

/opt/homebrew/opt/python@3.12/bin/python3.12 --version

Người dùng Windows có thể tải bộ cài đặt 3.12 từ trang web python.org.


Bước 2. Tạo môi trường ảo
Chúng ta nên tạo một môi trường độc lập để không ảnh hưởng đến hệ thống Python chung. Bạn chỉ cần tạo thư mục venv tại đường dẫn mong muốn.
Lệnh terminal:

# Tạo môi trường ảo (tại đường dẫn tùy chọn)

/opt/homebrew/opt/python@3.12/bin/python3.12 -m venv ~/hwp_convert_venv



# Kích hoạt môi trường ảo

source ~/hwp_convert_venv/bin/activate



# Xác nhận kích hoạt (thành công nếu hiển thị Python 3.12.x)

python --version

Trên Windows, lệnh kích hoạt sẽ khác một chút:

hwp_convert_venv\Scripts\activate

Bước 3. Cài đặt pyhwp2md
Chỉ cần một dòng lệnh pip. Các thư viện phụ thuộc như pyhwp, python-hwpx, lxml, olefile sẽ tự động được cài đặt cùng.
Lệnh terminal:

pip install --upgrade pip

pip install pyhwp2md

Sau khi cài đặt, bạn sẽ có lệnh CLI mang tên pyhwp2md. Đồng thời, bạn cũng có thể gọi nó trong mã nguồn Python bằng lệnh from pyhwp2md import convert.


Bước 4. Thử nghiệm với một tệp đơn lẻ
Trước khi chuyển đổi hàng loạt, hãy kiểm tra với một tệp duy nhất.
Lệnh terminal:

# Xuất Markdown ra màn hình (không lưu tệp)

pyhwp2md "TaiLieuCuaToi.hwpx"



# Lưu thành tệp .md trong cùng thư mục (tùy chọn -s)

pyhwp2md "TaiLieuCuaToi.hwpx" -s



# Lưu vào đường dẫn mong muốn

pyhwp2md "TaiLieuCuaToi.hwp" -o "KetQua/TaiLieuCuaToi.md"

Khi thử nghiệm với tệp HWPX, văn bản nội dung được xuất ra định dạng Markdown rất sạch sẽ. Tệp HWP nhị phân cũng cho kết quả tương tự. Ngay cả các bảng biểu cũng được chuyển đổi đúng theo cú pháp bảng của Markdown.


Bước 5. Tạo script chuyển đổi hàng loạt
Nếu chỉ có vài chục tệp, bạn có thể chạy từng tệp với tùy chọn -s, nhưng với hàng trăm hay hàng nghìn tệp, bạn cần một script Python.
Hãy lưu đoạn mã dưới đây với tên hwp_convert.py. Điểm quan trọng nhất là biến TARGET_DIR. Bạn hãy điền đường dẫn thư mục của mình vào đó, script sẽ tìm tất cả tệp HWP/HWPX trong thư mục đó và tạo các tệp .md tương ứng tại cùng vị trí.
hwp_convert.py:

#!/usr/bin/env python3

"""Chuyển đổi hàng loạt HWP/HWPX → Markdown"""



import time

from pathlib import Path

from pyhwp2md import convert



##############################################

# Hãy thay đổi đường dẫn thư mục của bạn tại đây

##############################################

TARGET_DIR = Path.home() / "Documents"



files = []

for ext in ("*.hwp", "*.hwpx"):

    files.extend(TARGET_DIR.rglob(ext))

files = sorted(files)



print(f"Tìm thấy: {len(files)} tệp")



ok = fail = skip = 0

failures = []

start = time.time()



for i, f in enumerate(files, 1):

    md = f.with_suffix(".md")

    if md.exists():

        skip += 1

        continue

    try:

        content = convert(str(f))

        if not content or not content.strip():

            fail += 1

            failures.append((f, "Đầu ra trống"))

            continue

        md.write_text(content, encoding="utf-8")

        ok += 1

    except Exception as e:

        fail += 1

        failures.append((f, str(e)[:100]))

    if i % 50 == 0:

        print(f"[{i}/{len(files)}] Thành công:{ok} Lỗi:{fail}")



elapsed = time.time() - start

print(f"\nHoàn thành! Mất {elapsed:.0f} giây")

print(f"Thành công: {ok} | Bỏ qua: {skip} | Lỗi: {fail}")



if failures:

    print("\nDanh sách lỗi:")

    for path, msg in failures:

        print(f"  {path.name}: {msg}")

Bước 6. Thực thi
Lệnh terminal:

# Kích hoạt môi trường ảo

source ~/hwp_convert_venv/bin/activate



# Chạy script

python hwp_convert.py

Chỉ đơn giản vậy thôi. Tiến trình sẽ được hiển thị sau mỗi 50 tệp. Khi kết thúc, bạn sẽ nhận được tổng số tệp thành công, lỗi và danh sách các tệp bị lỗi.


Kết quả thực tế
Tôi đã thực hiện trên toàn bộ iCloud Drive.

• Đối tượng: 1.659 tệp (563 HWP + 1.096 HWPX)
• Thành công: 1.639 tệp
• Bỏ qua: 9 tệp (đã tồn tại tệp .md)
• Lỗi: 11 tệp (0,7%)
• Thời gian thực hiện: 356 giây (khoảng 6 phút)
• Tỷ lệ thành công: 99,3%

11 tệp bị lỗi chủ yếu là những tệp vốn dĩ không có văn bản (chỉ gồm bảng hoặc hình ảnh) hoặc các tệp HWP đã bị hỏng. Tất cả các tệp có chứa văn bản đều được chuyển đổi thành công.


Các ví dụ về đường dẫn TARGET_DIR
Bằng cách thay đổi TARGET_DIR trong script, bạn có thể áp dụng cho bất kỳ thư mục nào.

# Chỉ các tệp Hancom trên Desktop

TARGET_DIR = Path.home() / "Desktop"



# Toàn bộ thư mục Documents

TARGET_DIR = Path.home() / "Documents"



# iCloud Drive

TARGET_DIR = Path.home() / "Library/Mobile Documents/com~apple~CloudDocs"



# Ổ cứng ngoài hoặc USB

TARGET_DIR = Path("/Volumes/MyDrive/HancomFiles")



# Một thư mục dự án cụ thể

TARGET_DIR = Path.home() / "Documents/DuAn2024/BaoCao"



# Người dùng Windows

TARGET_DIR = Path("C:/Users/TenNguoiDung/Documents")



# OneDrive trên Windows

TARGET_DIR = Path("C:/Users/TenNguoiDung/OneDrive/Documents")

Cách thực hiện chỉ với một dòng lệnh terminal (không dùng script)
Nếu số lượng tệp ít, bạn không cần đến script.

# Chuyển đổi tất cả hwpx trong thư mục hiện tại cùng lúc

for f in *.hwpx; do pyhwp2md "$f" -s; done



# Bao gồm cả tệp hwp

for f in *.hwp *.hwpx; do pyhwp2md "$f" -s; done



# Bao gồm cả tất cả các thư mục con

find ~/Documents -name "*.hwp" -o -name "*.hwpx" | \

  while read f; do pyhwp2md "$f" -s; done

Bạn có thể làm gì sau khi chuyển đổi?
Tệp Markdown thực chất là tệp văn bản. AI có thể đọc chúng ngay lập tức. Bạn có thể đưa chúng vào bất kỳ đâu như Claude, ChatGPT hay NotebookLM. Bạn cũng có thể tìm kiếm trong các ứng dụng ghi chú như Obsidian. Chỉ với một dòng lệnh grep, bạn có thể tìm từ khóa trong hàng nghìn tài liệu. Từ nay, bạn không còn nhất thiết phải mở chương trình Hancom nữa.
Tệp HWP/HWPX gốc vẫn được giữ nguyên, vì vậy khi cần định dạng văn bản gốc, bạn vẫn có thể mở chúng. Markdown đóng vai trò là một bản sao trích xuất văn bản tiện dụng.
Sau này, khi có thêm tệp Hancom mới, bạn chỉ cần chạy lại script đó. Những tệp đã có bản .md sẽ tự động được bỏ qua, chỉ những tệp mới mới được chuyển đổi.
Dù số lượng tệp Hancom có nhiều đến đâu, bạn cũng không cần lo lắng. Tất cả bắt đầu bằng một dòng lệnh pip install pyhwp2md và kết thúc bằng khoảng 30 dòng script Python.


Các dự án mã nguồn mở liên quan
• pyhwp2md — Chuyển đổi HWP/HWPX sang Markdown (công cụ sử dụng trong bài này)
https://github.com/pitzcarraldo/pyhwp2md
• python-hwpx — Thư viện đọc/ghi/tạo HWPX
https://github.com/airmang/python-hwpx
• pyhwp — Bộ phân tích nhị phân HWP
https://github.com/mete0r/pyhwp
• hwp.js — Bộ phân tích/xem HWP bằng JavaScript
https://github.com/hahnlee/hwp.js
• H2Orestart — Tiện ích mở rộng HWP/HWPX cho LibreOffice
https://github.com/ebandal/H2Orestart
• hwpx-contents-extract — Ví dụ trích xuất nội dung HWPX chính thức của Hancom (Java)
https://github.com/hancom-io/hwpx-contents-extract




KIMKJ.COM
#KimKyungjin #LuậtSưKimKyungjin #TríTuệNhânTạoKimKyungjin #TríTuệNhânTạo #AI #ChuyênGiaAI #LuậtAI #ChínhSáchAI #QuyĐịnhAI #ĐạoĐứcAI #AIGenerative #ChatGPT #Claude #GPT #LLM #ChuyểnĐổiSố #ThànhPhốThôngMinh #LáiXeTựĐộng #QuyĐịnhDữLiệu #GDPR #BảoMậtThôngTinCáNhân #QuảnTrịAI #CựuNghịSĩKimKyungjin #ChuyênGiaPhápLý #ChínhSáchCôngNghệ #GiáoDụcAI #CáchMạngHànhChínhAI #ChiếnTranhQuyềnLựcAI #kimkj #kimkjcom