kordoc：從 README 拆解功能、入口與採用邊界

kordoc 面對的韓國文件格式

README 一開頭就是專案的由來：作者是韓國地方公務員，在廣津區廳與 HWP 檔案搏鬥了七年。kordoc 就是結果，一個用 TypeScript 寫的工具，能把 HWP 3.x 和 5.x、HWPX、HWPML、PDF、XLS、XLSX、DOCX 以及 PNG/JPG/WebP 圖片解析成 Markdown。README 說這樣做的目的是讓政府文件處於最適合 AI（LLM）閱讀和分析的狀態，並稱該工具已在五個公共專案中用數千份真實政府文件做過驗證。倉庫後設資料顯示，截至本文撰寫時有 1,664 個星標、302 個 fork 和 1 個未關閉的 issue。 本節只根據該專案 README 已列出的內容；文件未說明的相容性與效能不作推定。 chrisryugj/kordoc 的 README 將這一點放在其 kordoc 面對的韓國文件格式 脈絡中；因此閱讀時要區分已列出的命令、檔案或事件，與尚未提供細節的宣稱。對使用者而言，這個區分會直接影響安裝、設定、權限、輸出格式及升級後的回歸檢查。

npx kordoc setup 與 AI 客戶端

每種格式都有獨立的引擎。HWPX 走 ZIP 加 XML DOM 路線，支援清單解析和巢狀表格。HWP 5.x 走 OLE2/CFB，能處理發行用加密文件和損壞的 CFB 檔案。HWP 3.x 是 1996 到 2002 年的二進位格式，用 johab 到 Unicode 的轉換加 5,893 個漢字和符號的查表來解析。PDF 解析用 pdfjs-dist，帶基於線條的表格偵測、XY-Cut 閱讀順序，以及逐頁的文字品質訊號，用來判斷哪些頁需要 OCR。XLSX 和 DOCX 用 ZIP 加 XML DOM，XLS 用 OLE2 和 BIFF8。內建 OCR 在 v4.2.0 加入，本機執行 PP-OCRv5 korean，首次使用下載約 18 MB 的模型，README 說覆蓋全部 11,172 個韓文音節字、字母、拉丁字母和符號。 本節只根據該專案 README 已列出的內容；文件未說明的相容性與效能不作推定。 chrisryugj/kordoc 的 README 將這一點放在其 npx kordoc setup 與 AI 客戶端 脈絡中；因此閱讀時要區分已列出的命令、檔案或事件，與尚未提供細節的宣稱。對使用者而言，這個區分會直接影響安裝、設定、權限、輸出格式及升級後的回歸檢查。

parse_document 到 patch_document

除了抽取文字，kordoc 還提供文件比對、表單欄位辨識和表單填寫。比對功能在區塊層級運作，支援 HWP 與 HWPX 的跨格式比對。表單填寫保留原範本的字型、字號和對齊方式，也能處理韓國政府表單裡的 CLICK_HERE 欄位。修補路徑是專案的核心設計選擇：patchHwpx 和 patchHwp 接收編輯後的 Markdown，只把改動的文字寫回原檔案，不改動未修改的位元組。README 報告說，對 HWP 5.x 二進位檔案的修補只改動受影響的磁區，不支援的編輯會透過跳過列表如實報告，而不是靜默丟棄。 本節只根據該專案 README 已列出的內容；文件未說明的相容性與效能不作推定。 chrisryugj/kordoc 的 README 將這一點放在其 parse_document 到 patch_document 脈絡中；因此閱讀時要區分已列出的命令、檔案或事件，與尚未提供細節的宣稱。對使用者而言，這個區分會直接影響安裝、設定、權限、輸出格式及升級後的回歸檢查。

HWPX 表格和版面保留

產生方向是把 Markdown 轉回 HWPX，包括韓文原生的公式物件、OOXML chartSpace 圖表、超連結、註腳和內嵌圖片。政府文件模式套用行政安全部行政業務手冊裡的排版慣例：八級條目編號、懸掛縮排、官方頁邊距，以及不同文件類型的預設。4.0 版加入標準表單，包括帶 23 個佔位符的一般公文草稿（另紙第1號格式）和帶 13 個佔位符的簡易草稿。README 說這些表單是解碼 60 份真實已核准公文和 16 種政府表單類型後做出來的。 本節只根據該專案 README 已列出的內容；文件未說明的相容性與效能不作推定。 chrisryugj/kordoc 的 README 將這一點放在其 HWPX 表格和版面保留 脈絡中；因此閱讀時要區分已列出的命令、檔案或事件，與尚未提供細節的宣稱。對使用者而言，這個區分會直接影響安裝、設定、權限、輸出格式及升級後的回歸檢查。

kordoc lint 與版本變更

kordoc 可以在伺服器沒有安裝韓文軟體的情況下把 HWPX 渲染成 SVG。對有快取版面資料的檔案，它按儲存的行座標和儲存格網格還原原始版面。對沒有快取的檔案，包括 kordoc 自己產生的文件，用純 TypeScript 的 reflow 引擎做換行和縱向排版。渲染路徑支援多頁輸出、搜尋詞高亮、繪製形狀，以及給預覽應用用的常駐 worker 模式。README 註明渲染不支援公式物件。 本節只根據該專案 README 已列出的內容；文件未說明的相容性與效能不作推定。 chrisryugj/kordoc 的 README 將這一點放在其 kordoc lint 與版本變更 脈絡中；因此閱讀時要區分已列出的命令、檔案或事件，與尚未提供細節的宣稱。對使用者而言，這個區分會直接影響安裝、設定、權限、輸出格式及升級後的回歸檢查。

MIT 授權下的部署責任

這個套件同時提供 CLI 和 MCP 伺服器。CLI 涵蓋解析、批次轉換、表單填寫、修補、蓋章、驗證、lint、渲染，以及監視資料夾並可選回呼 webhook 的 watch 模式。MCP 伺服器暴露 15 個工具，包括 parse_document、fill_form、patch_document、generate_document、render_document、redact_document 和 parse_chunks。安裝精靈透過 npx kordoc setup 執行，偵測已安裝的 AI 用戶端、自動改設定檔，並在 Windows 上包裝 npx。README 還記錄了一個 Claude Code 外掛，把 kordoc 註冊為技能而不是 MCP 伺服器。 本節只根據該專案 README 已列出的內容；文件未說明的相容性與效能不作推定。 chrisryugj/kordoc 的 README 將這一點放在其 MIT 授權下的部署責任 脈絡中；因此閱讀時要區分已列出的命令、檔案或事件，與尚未提供細節的宣稱。對使用者而言，這個區分會直接影響安裝、設定、權限、輸出格式及升級後的回歸檢查。 chrisryugj/kordoc 的實際核對應從 README 指定的入口開始。先確認命令、套件名稱、分支或版本標籤，再確認輸入資料的格式，以及工具輸出會寫到哪個檔案、目錄、瀏覽器頁面、核心事件或報告。這些觀察點決定它能否放進既有流程，也能揭露文件未交代的限制。若是 ReactUse，就對照 @reactuses/core、useToggle 與 SSR 執行環境；若是 kordoc，就對照 npx kordoc setup、parse_document、patch_document 和 HWPX；若是 Linutil 或 Winutil，就記錄選單操作、CLI 參數與系統權限；若是 Chroma，就分開測試 chromadb、chroma run --path 與 collection；若是 Chrome DevTools MCP，就依 docs/tool-reference.md 核對工具回應；若是 Cilium 或 Tetragon，就看 CNI、NetworkPolicy、process_exec、process_exit 與 TracingPolicy 的實際事件；若是 Indicator，就以 Go channel、CSV 測試資料、Tiingo 或 Alpaca repository 和回測 HTML 報告作為觀察對象。README 未明示的相容性、效能和安全保證，都應維持未確認狀態。 採用前也要把專案名稱、具體檔案和命令寫入測試紀錄，確認輸出可被下游工具讀取，並檢查錯誤時是否留下可診斷訊息。這項檢查與 chrisryugj/kordoc 的輸入格式直接相關，不能用其他專案的測試結果代替。對 chrisryugj/kordoc 而言，還要核對 README 提到的版本、分支、套件、設定鍵、資料來源或事件名稱是否一致，確認最小案例在目標環境產生預期輸出，再觀察升級、權限改變、網路中斷和輸入異常時的行為。若文件只列出能力名稱而沒有範例，文章不會替它補上未證實的細節；若授權文字沒有提供支援承諾，也不能把授權誤讀成維護保證。這些具體紀錄能讓團隊知道哪些結論來自 README，哪些仍須由自己的環境確認。

編輯結論

適合已使用相關技術、願意依 chrisryugj/kordoc README 的專案命令和設定檔做驗證的團隊；不適合把文件中的宣稱直接當成保證的使用情境。先以專案列出的入口跑通最小流程，觀察實際輸出、錯誤訊息與權限影響，再決定是否擴大導入。

官方來源

1. Official documentation
2. Official README
3. Project repository
4. Release notes