AI 文件工作流與本機成果閱覽器技術紀錄

定位／對應既有頁

本頁是 Learning/ai document workflow workshop 的技術補充。既有頁介紹工作坊練習的能力範圍；本頁只公開可重用的流程與成果閱覽器架構，不重製課程教材，也不公開規章內容、報價內容、價格、供應商資訊或第三方文件。

已確認技術

六類任務的共用結構

現有成果涵蓋文案整理、簡報結構重用、規章問答、故障排除 Agent、表格檢核與跨文件彙整。雖然輸出形式不同，實作可抽象為同一條工作流：

1. 辨識來源檔案與真正要回答的問題。
2. 把來源事實和輸出格式分開。
3. 將可重用規則整理成專案指令、Skill 或分支流程。
4. 產出可人工閱讀的 Markdown／CSV 等結果。
5. 用刻意設計的正常、異常與「來源查無答案」案例驗收。
6. 保留結果與限制，避免 AI 把缺失資料補成看似合理的事實。

實際成果是以 Cursor 完成，而不是在原課程指定的網頁介面中操作。這點屬於工具替換，不代表跳過來源清理、規則化或驗收。

本機成果閱覽器

閱覽器由四個部分構成：

• index.html：雙欄介面與主要容器。
• styles.css：視覺樣式與版面。
• app.js：固定文件目錄、搜尋、載入、Markdown 轉換與前端狀態。
• server.py：以 Python 標準函式庫提供靜態檔案與預覽 API。

伺服器使用 ThreadingHTTPServer，固定綁定 127.0.0.1:8787。這是 loopback-only 的本機服務，不需要 Node.js、資料庫或外部 CDN。

資料流／演算法

文件工作流

來源文件
  → 擷取可引用事實
  → 正規化結構與欄位
  → 套用任務規則／Skill／分支
  → 產出成果
  → 正常、異常、缺資料案例驗收
  → 人工最終判斷

核心原則是「來源事實、處理規則、輸出成果、驗收紀錄」分層。這讓同一組規則可以換資料測試，也讓錯誤能追溯到來源缺漏、規則問題或輸出問題，而不是只重跑提示詞。

啟動與 HTTP 路由

啟動腳本會：

1. 切到成果資料夾。
2. 組合本機網址。
3. 若作業系統有 open 指令，延遲一秒開啟預設瀏覽器。
4. 用 Python 3 啟動閱覽器伺服器。
5. 終端機程序結束時，服務一併停止。

HTTP 行為：

• / 重新導向到 /閱覽器/。
• 一般路徑由 SimpleHTTPRequestHandler 提供成果資料夾內的靜態檔案。
• /api/preview?path=... 讀取指定檔案，回傳 JSON 格式的預覽資料。
• API 回應加上 Cache-Control: no-store，避免預覽結果被瀏覽器快取。

路徑檢查

safe_resolve() 會先 URL decode、移除開頭斜線，再把路徑解析成 canonical path，最後確認它仍在整個工作坊專案目錄下，而且是存在的檔案。這能阻擋跳出專案的 ../ traversal。

重要邊界是：API 允許的根不是只有「完成成果」資料夾，而是其上一層的整個工作坊專案。副檔名處理器會再限制為 Markdown、文字、JSON、CSV、XLSX 與 DOCX，但只要服務收到可控路徑，就可能讀到專案內其他支援格式檔案。因此這個設計只適合受信任使用者的本機環境。

各格式預覽

Markdown

• 伺服器以 UTF-8 讀取，回傳原始文字。
• 前端自製的最小 parser 支援一到四級標題、段落、無序／有序清單、blockquote、水平線、 fenced code、簡單表格，以及 inline code、粗體、斜體與連結。
• 解析前會 escape HTML 特殊字元，因此原始 Markdown 中的 HTML 不會直接當成 HTML 執行。
• 這不是完整 CommonMark parser；巢狀清單、複雜表格、完整連結語法與多數擴充語法不在保證範圍。

CSV

• 使用 utf-8-sig 讀取，可處理含 BOM 的檔案。
• Python csv.reader 解析列與欄。
• 第一列被當成表頭，其餘列輸出為 HTML table。

XLSX

• 不依賴 Excel 或第三方 Python 套件，而是把 XLSX 當 ZIP 開啟。
• 讀取 sharedStrings.xml、workbook sheet metadata 與 relationship，再逐張解析 worksheet XML。
• 依儲存格座標還原行列，並為多工作表建立 tab 與 table。
• 目前只取儲存值，不計算公式，也不還原完整樣式、日期格式、合併儲存格、圖表或圖片；某些 inline string 寫法也可能無法完整呈現。

DOCX

• 同樣把 DOCX 當 ZIP 開啟。
• 只讀 word/document.xml，依 paragraph 收集文字節點。
• 輸出 escape 後的段落 HTML。
• 表格結構、圖片、頁首頁尾、註解、樣式與版面不會被忠實還原。

TXT／JSON

• 以 UTF-8 讀取並 escape。
• 使用 <pre> 保留純文字排列，不做 JSON schema 驗證或語法高亮。

前端導覽

• 文件清單以 JavaScript 常數硬編碼並依六類成果分組，不會自動掃描資料夾。
• 搜尋只過濾標題與群組名稱。
• 開啟文件後更新標題、breadcrumb、active 狀態與 URL hash。
• 重整頁面時，可依 hash 找回硬編碼清單中的文件。
• Office 與文字格式透過 preview API；Markdown 優先走 API，失敗時才嘗試靜態 fetch。

硬編碼目錄讓展示順序穩定，但新增、移動或改名檔案後必須手動同步 FILES，否則檔案存在也不會出現在側邊欄。

測試驗證

現有使用說明把 Markdown、CSV、XLSX 與 DOCX 列為支援格式；程式中也能找到四種格式對應的解析路徑與錯誤回應。

本次只做來源碼與使用說明的靜態核對，沒有重新開啟 GUI 逐份人工驗收。檢視範圍內沒有獨立的自動測試或瀏覽器端 E2E suite，因此目前不能宣稱：

• 任意 Office 檔都能保真預覽。
• XLSX 的公式、日期、樣式與所有字串儲存方式都已覆蓋。
• DOCX 的表格、圖片與分頁都已覆蓋。
• 所有 Markdown 邊界語法都符合 CommonMark。
• 所有瀏覽器都已測試多工作表切換與 hash 還原。

適合的最小回歸集合應包含每種格式一份可公開 fixture、非法路徑、超出專案路徑、缺檔、不支援副檔名、特殊字元與大型表格。

部署／執行邊界

• 目前只設計為 macOS 上的本機暫時閱覽器。
• 服務綁定 127.0.0.1，不接受區域網路或公開網路連線。
• 沒有登入、權限、CSRF、防速率濫用、TLS 或正式伺服器設定；不能把 bind address 改成公開介面後直接上線。
• API 只有 GET 預覽，沒有上傳、修改或刪除功能。
• 關掉啟動它的終端機視窗即可停止服務。
• Python 端主要使用標準函式庫；前端沒有套件建置步驟，適合離線展示。

限制

• 文件清單不是動態索引，容易與檔案系統不同步。
• 自製 Markdown parser 只覆蓋展示需要的子集合。
• 前端連結沒有額外的 URL scheme allowlist；閱覽器應只載入受信任的本機內容。
• Office 預覽是「內容抽取」，不是 Microsoft Office 等級的版面渲染。
• XLSX 與 DOCX 解析假設檔案內部 XML 存在且可讀，損毀檔案只會回傳一般錯誤。
• API 的允許範圍大於完成成果資料夾，不適合承載同一專案中的敏感材料。
• AI 文件成果仍需人工判斷；檢核規則不能取代正式授權人員、法務、財務或採購決策。

公開邊界

可公開：工作流分層、驗收觀念、本機伺服器架構、各格式的解析方法、路徑安全邊界與已知限制。

不公開：課程 PDF／教材、規章原文與清洗版、問答答案、報價單、金額、價格、供應商或組織識別資訊、採購決策內容、第三方 Office 檔、課堂解答與未授權素材。本頁也不列出這些檔案的具體內容或欄位值。

Source of truth

• ../claude_class_0807/00_請由此開啟_工作坊完成成果/README.md
• ../claude_class_0807/00_請由此開啟_工作坊完成成果/00_我們實際做了什麼.md
• ../claude_class_0807/00_請由此開啟_工作坊完成成果/啟動美美閱覽.command
• ../claude_class_0807/00_請由此開啟_工作坊完成成果/閱覽器/server.py
• ../claude_class_0807/00_請由此開啟_工作坊完成成果/閱覽器/index.html
• ../claude_class_0807/00_請由此開啟_工作坊完成成果/閱覽器/app.js
• ../claude_class_0807/00_請由此開啟_工作坊完成成果/閱覽器/styles.css

原始成果與程式仍是 source of truth；公開 Wiki 只保留不含教材、規章與商業資料的技術摘要。