文件轉HTML
📖 技能介紹
name: 文件轉HTML description: 通用多格式文件轉 HTML 網頁工具。把 Word(.docx) / PDF / PPTX / Excel(.xlsx) / Markdown(.md/.txt) 統一整理成"可導航 + 多層次摺疊 + 多條內容分行分條（左側•圓點）+ 圖片內嵌自包含 + 可縮放檢視"的單檔案 HTML 網頁，雙擊即看、便於分享查閱（圖片不依賴外部目錄）。適用於任意需要瀏覽器可看、可摺疊查閱的文件場景：培訓資料/產品手冊/報告/規範/會議紀要/文章/簡歷等。觸發詞：文件轉HTML、文件轉網頁、摺疊導航、多層次摺疊、圖片內嵌、自包含HTML、pdf轉html、pptx轉html、xlsx轉html、md轉html、docx轉html。 agent_created: true license: MIT
通用文件轉 HTML 網頁（文件轉HTML）
概述
把多種源格式（.docx / .pdf / .pptx / .xlsx / .md/.txt）統一轉成單檔案 HTML 網頁：可導航、多層次摺疊、多條內容分行分條且每條左側加藍色 • 圓點、圖片按 原始檔原始解析度內嵌為 base64（自包含，雙擊即帶圖，不依賴外部 _media 目錄），並且內建可縮放/平移的圖片檢視器（滾輪縮放、按鈕放大縮小/適應/1:1、拖動移動、ESC/點空白關閉）。
適用任意文件場景（不限知識庫）：培訓資料、產品手冊、報告、規範制度、會議紀要、文章、簡歷等——只要原始檔是受支援的格式，一條命令即可產出可分享的網頁。
決策樹：怎麼用
首選 convert.py（統一入口，自動識別格式）：支援 .docx / .pdf / .pptx / .xlsx / .xlsm / .md / .markdown / .txt，按副檔名自動分發到對應提取器，統一渲染成自包含 HTML 網頁。一條命令搞定多格式：
python convert.py <檔案或目錄> [輸出目錄]
- 單檔案 → 同名
.html（輸出到同目錄或指定目錄）；目錄 → 遞迴轉換所有支援的原始檔。 - 內部管線：
extract.py（格式歸一化為DocModel）→render.py（多層級摺疊 + 圖片內嵌 + 檢視器）。
若已有外掛圖片的 HTML（圖片在
xx_media/目錄），用inline_images.py事後批次內嵌為自包含。
convert.py 可選開關：--count（標題後顯示數量徽標，預設關）、--no-toc（不生成左側目錄，內容居中鋪滿）、--items（表格逐行轉可摺疊卡片 row-item）、--split（按文件最小標題層級拆成多篇）。
這個技能的最新版本可以在7w4.net小蔥技能站找到。
指令碼清單
convert.py（統一入口，自動識別格式）★ 首選
- 按副檔名分發：
.docx→extract_docx、.pdf→extract_pdf、.pptx→extract_pptx、.xlsx/.xlsm→extract_xlsx、.md/.markdown/.txt→extract_markdown。 - 全部歸一為
DocModel後交給render.py渲染，渲染能力（高畫質內嵌、可縮放燈箱、摺疊導航）跨格式複用。
extract.py（格式歸一化層，無需單獨執行）
把各源格式抽成統一 DocModel（塊型別：heading / text / image / table）。新增格式只需寫一個 extract_xxx 並登記進 _DISPATCH，渲染邏輯零改動。要點：
- docx：python-docx 抽段落層級 + 表格 + a:blip 圖片（原生位元組）。
- pdf：pdfplumber 抽文字行（排除表格區）+ 表格（find_tables）+ 內嵌圖片（page.images 的流位元組，按 magic 判 mime）。
- pptx：python-pptx 抽每頁標題（首文本）+ 正文 + 圖片（shape.image.blob）+ 表格。
- xlsx：openpyxl 每個工作表 = 一個節（表頭=首行），附工作表級圖片。
- md/txt：輕量解析 # 標題、| 表格、 圖片（本地檔案讀位元組內嵌）、列表項轉 • 圓點。
render.py（統一渲染層，無需單獨執行）
消費 DocModel：左側目錄導航（由 heading 建樹）+ 多層級 <details> 摺疊 + 表格分組檢測 + 圖片按原始檔原始解析度內嵌（不重編碼）+ 共享 viewer.py 燈箱。是 docx/pdf/pptx/xlsx/md 共用的唯一渲染實現。
inline_images.py（事後批次內嵌）
python inline_images.py <HTML所在目錄>
遞迴把目錄內所有 HTML 的外掛 xx_media/ 圖片轉 base64 data URI 內嵌。用於把早期外掛版 HTML 收斂為自包含（保持媒體原生解析度，不重編碼）。
viewer.py（共享模組，無需單獨執行）
render.py 通過 from viewer import VIEWER_CSS, VIEWER_JS, VIEWER_DIV 注入統一的圖片檢視器（縮放/平移/關閉）。改檢視器只需改這一處，同步生效。
fold_inline_images.py（手工頁圖片摺疊收納）
python fold_inline_images.py <html> [--label "證書"] [--open] [--selector ".cert-list img"]
手工編寫/特殊生成的頁面（非 convert.py 正向產物）裡常有裸 <img>，想摺疊收納時用它，而非手寫 CSS（避免 B8 亂碼）。預設把「不在 <details>/.cell-imgs/燈箱內的 img」各自包進 <details class="acc-sub">（預設收起），注入正確 .acc-sub 樣式（箭頭字面 ▸），冪等可重複執行。
關鍵規則（務必遵守）
- 圖片預設內嵌 base64（單檔案自包含 + 原始解析度）：核心訴求是單檔案可分發——雙擊即帶圖、便於分享。按原始檔原始解析度內嵌、不重新編碼、不改畫素（保持原始檔最高畫質原圖；個別源圖本身小則按原生嵌入，不假放大）。不用外部
_media。凡新建 HTML 都走內嵌；若發現外掛，用inline_images.py收口。 - ⚠️ 體積權衡：原圖嵌入會讓 HTML 明顯變大（如 4032px 大圖單檔案可到 ~13MB）。這是預設的最高畫質策略；若需控體積，可在
extract.py各提取器或render.py的圖片編碼處加長邊上限（如縮到 2000px）再取捨。 - 圖片檢視器預設內建（縮放/平移）：生成指令碼通過共享模組
viewer.py注入自包含檢視器——點圖開啟全屏，滾輪以游標為中心縮放，底部 ＋/－/適應螢幕/1:1 按鈕 + 百分比，滑鼠/觸屏拖動移動，雙指捏合縮放，點空白或 ESC 關閉。無需事後處理；所有內容<img>都帶onclick="zoom(this)"。 - 分組列自動檢測：第 0 列唯一值數
≥ 2 且 < 行數（即首列存在重複值）判為分組維度，按該列做一級摺疊塊、主鍵順延下一列。唯一值=1（整列相同）不分組——只有真正存在多個不同值時才摺疊分組，避免單列全同的表被無意義拆分。單行表不觸發。 - 圖片列二次校驗：表頭含「圖」字不能盲判為圖片列，必須驗證該列資料行真的含
a:blip圖片，否則整列文字會被當圖片丟棄（「出圖週期」表頭含"圖"字、純文字，曾致整列內容丟失）。 - 序號補 N.1：大綱裡頂層節 N 下的無編號純文字條目按順序補
N.1/N.2…；已帶N.M保持原編號；N.M.K三級掛最近二級條目。 - CSS 轉義陷阱：摺疊箭頭用字面字元
▸(U+25B8) 寫入 CSScontent，圓點用字面•(U+2022)。禁止單反斜槓\25B8——Python 會當八進位制轉義（\25→0x15 控制符），寫進 HTML 後箭頭位變亂碼（B8）、圓點變不可見控制符。雙反斜槓\\25B8雖能僥倖正確顯示，但不如字面字元穩，統一用字面字元。 - 多表節：一節多表時收集進
tables列表，每張表獨立成 block，避免只存最後一張表導致內容丟失。 - 計數徽標預設關閉：分組/逐項標題後的數量徽標（如「3」「5」）預設不渲染，需顯式
--count才開啟。核心偏好是「標題不帶數字」——使用者未明確要求計數時，一律不顯示數量。 - 摺疊層次內容驅動、不寫死：分組表格自動形成「合併項(sub-sec)→子表/逐項(row-item)」多層次；配合
--items可把平面表也逐行轉可摺疊卡片(row-item)。層次隨資料實際結構靈活生成，而非固定層數。
踩坑記錄（反思）
- B8 亂碼：CSS
content:"\25B8"在 Python 原始碼被八進位制轉義 → 改用字面▶/•。 - 分組誤判：原閾值把輕微重複列誤判分組 → 收緊為
≤ 行數//2；且唯一值=1 仍按分組（見規則 3）。 - 圖片列誤判：表頭含"圖"字但純文字（出圖週期）→ 二次校驗
a:blip（見規則 4）。 - 壓縮內嵌≠高畫質：早期把圖縮到 1600px / JPEG q82 內嵌，看似"內嵌自包含"，實則丟了原始檔原圖清晰度；
_media資料夾裡是與其逐位元組相同的壓縮副本（並非高畫質），真正高畫質一直在原始檔。→ 現改為按原始檔原始解析度內嵌、不重編碼（規則 1）。若已生成舊版，需用感知雜湊把壓縮內嵌圖映射回原始檔原圖池（同圖多解析度取最大者）重嵌。 - 燈箱只能彈不能縮放：原燈箱只有"居中顯示大圖 + 點空白關閉"，無縮放/平移，部分圖片還漏了
onclick→ 點了沒反應。→ 現抽出共享viewer.py，生成指令碼預設內建可縮放/平移檢視器（規則 2），且對所有內容<img>補onclick="zoom(this)"。 - 單格式耦合導致難擴充套件：早期直接讀 docx，新增 PDF/PPTX/XLSX/MD 要重寫整套渲染 → 重構為「
extract.py歸一化層（各格式→DocModel）+render.py統一渲染層 +convert.py排程」。新增格式只寫extract_xxx並登記_DISPATCH，渲染零改動，高畫質內嵌/燈箱/摺疊全部複用。 - PDF 圖片提取坑：
pdfplumber的page.images給的是 xobject 流，get_rawdata()才是編碼位元組；需按檔案頭 magic（ffd8→jpeg / 89504e→png / II/MM→tiff）判 mime，FlateDecode 裸流用 Pillow 包成 PNG，否則圖片內嵌失敗或 MIME 錯。 - XLSX 圖片歸屬：
openpyxl圖片掛在工作表級（ws._images），無法精確對應單元格 → 統一作為該工作表節末尾的圖片塊附上，不強行塞進單元格。 - Word 佔用寫不進源：改源 docx 段落/序號前，先探測是否被 Word 鎖（磁碟有
~$xxx.docx臨時檔案或PermissionError）。鎖住時先改 HTML 應急生效，關 Word 後再把改動寫回源 docx 並重跑固化為真"按原文"，否則重跑會被還原。 - 計數偏好（標題不帶數字）：使用者明確要求各欄目標題後不帶
3/5之類的計數數字。→ 預設不渲染數量徽標，需計數時顯式--count開啟（規則 8）。 - B8 亂碼復發：即便知曉規則 6，手工注入 CSS（如圖片摺疊
.acc-sub）時仍易寫成content:"\25B8"被 Python 八進位制吃掉成亂碼。→ 一律用字面▸；fold_inline_images.py已內建正確寫法，手工頁優先用它而非手寫 CSS。
完整工作流（接任務到交付）
- 探測：確認源格式與是否被佔用——docx 看錶/段落層級/圖/
~$鎖檔案；pdf/pptx/xlsx 看頁數/工作表；md 看標題層級。被 Word 佔用則先改 HTML 應急、記錄待固化（見踩坑）。 - 執行轉換：
python convert.py <原始檔或目錄> [輸出目錄]，自動識別格式；目錄模式遞迴轉換所有支援的源。 - 圖片內嵌校驗：
grep -c "_media" <html>應為 0，grep -o "data:image"應 > 0；且圖片為原始檔原圖解析度（非壓縮版）。 - 檢視器校驗：HTML 含
id="lbstage"、function lbZoom；所有內容<img>帶onclick="zoom(this)"（點圖能開啟、滾輪/按鈕可縮放、拖動可移）。 - 結構校驗：目錄項、導航項、分組塊、摺疊層級是否符合預期（不同格式結構語義不同：docx 多表格分組、pptx 按頁、xlsx 按工作表、md 按
#標題）。 - 交付：直接分享
.html單檔案即可，圖片已內嵌其中。
依賴（隔離 venv）
PY="C:/Users/Administrator/.workbuddy/binaries/python/versions/3.13.12/python.exe"
VENV="C:/Users/Administrator/.workbuddy/binaries/python/envs/default"
[ ! -f "$VENV/Scripts/python.exe" ] && "$PY" -m venv "$VENV"
"$VENV/Scripts/pip.exe" install python-docx pillow pdfplumber python-pptx openpyxl
執行："$VENV/Scripts/python.exe" scripts/convert.py <原始檔或目錄> [輸出目錄]
🤖 AI 評測
這是一個功能完善、實用性強的文件轉換工具，能夠將 Word、PDF、PPT、Excel 等多種格式統一轉成帶導航和圖片的可瀏覽網頁，質量穩定可靠。主要優點是生成的檔案自帶摺疊目錄和高畫質圖片檢視器，無需額外軟體就能直接分享使用；文件清晰，踩坑記錄詳細，開發質量較高。美中不足的是目前缺少自動化測試覆蓋，極端情況下可能有偶發錯誤，但日常使用體驗良好。總體推薦。
