✨ 功能特性

🎯 核心特性

核心功能

• 118 個統一工具 - Word(28)、Excel(32)、PowerPoint(26)、PDF(19)、OCR(2)、Email(6)、BarCode(2)、轉換(1)、Session(1)、擴充功能(1) 已整合
• OLE 嵌入物件處理 - Word/Excel/PowerPoint 統一的 OLE 物件管理（list/extract/extract_all/remove），支援檔案模式與 Session 模式
• 按需啟用 - 只啟用需要的文檔類型，減少資源佔用
• 跨平台 - Windows、Linux、macOS (Intel + ARM) 原生支援，無需外部圖形庫，單一可執行檔案
• 開箱即用 - 預編譯版本無需安裝 .NET Runtime
• 完整讀寫 - 支援從A文檔讀取格式應用到B文檔

技術特性

• MCP 2026-07-28 規範支援 - 完全符合最新 MCP 協議規範，工具註解（readonly/destructive/idempotent/openWorld）由每個工具的 [McpServerTool] 屬性明確宣告，完整的 JSON-RPC 2.0 錯誤處理
• 統一字型設定 - 多個工具支援中英文字型分別設定（fontNameAscii 和 fontNameFarEast 參數）
• 靈活的授權配置 - 支援總授權或單一組件授權，自動搜尋、環境變數或命令列參數配置，試用模式降級（找不到授權時）
• 自動工具發現 - 掃描組件中標記 [McpServerToolType] 的類別與 [McpServerTool] 的方法自動註冊，無需手動列舉
• 安全加固 - 全面的路徑驗證、輸入驗證和錯誤處理

🔒 安全特性

路徑驗證

• 所有檔案路徑都經過 `SecurityHelper.ValidateFilePath()` 驗證
• 防止路徑遍歷攻擊（`../`, `..\`）
• 限制路徑長度（Windows 260 字元、其他平台 4096 字元）和檔案名稱長度（最大 255 字元）
• 驗證路徑中的非法字元
• 拒絕控制字元（`\x01`–`\x1F`）：Linux 平台的 `GetInvalidPathChars` 僅包含 `\0`，本項明確補充以保持跨平台一致性
• 拒絕 NTFS Alternate Data Stream（路徑段中的冒號，例如 `file.txt:hidden`），防止資料隱藏與路徑驗證繞過
• 拒絕路徑段末尾的點號或空白（Windows 靜默截斷，可繞過副檔名驗證，例如 `file.exe.` → `file.exe`）
• 拒絕 Windows 保留裝置名稱（CON、NUL、AUX、PRN、COM1–9、LPT1–9），跨平台一律阻擋以防止 OS 副作用
• 可選路徑白名單：使用 `--allowed-path` 將檔案存取限制於指定基礎目錄下（可重複指定；未設定則不限制，建議 HTTP/WebSocket 部署時啟用）。白名單於所有工具的輸入路徑、輸出路徑與次要檔案參數（憑證、圖章圖片、佈景主題等）一致生效
• 符號連結解析（symbolic link resolution）：所有路徑在任何 I/O 前均透過 `SecurityHelper.ResolveAndEnsureWithinAllowlist()` 解析至最終目標，並再次比對白名單。解析方式與 `realpath` 相同——由路徑根部起逐段展開，因此位於路徑中段的符號連結或 NTFS junction 同樣會被跟隨（不只結尾或最近存在的祖先）；白名單內部的符號連結若最終目標仍在白名單內則允許，目標位於白名單之外則拒絕；懸空符號連結（dangling symlink）的目標路徑亦須位於白名單內

輸入驗證

• 陣列大小驗證（`SecurityHelper.ValidateArraySize`，預設上限 1000 項）——這些驗證不是全域套用，而是由個別操作在入口呼叫；目前使用預設值的只有 PDF 合併的 `inputPaths`
• 字串長度驗證（`SecurityHelper.ValidateStringLength`，預設上限 10000 字元）——現有呼叫端均自行傳入更小的上限（附件名稱 255、附件說明與搜尋型樣 1000），因此 10000 實際上不會被觸發
• 數值範圍驗證（`SecurityHelper.ValidateNumericRange`）：列／欄／頁數、DPI、縮放、表格維度等參數依操作設定上下限

錯誤處理

• 錯誤訊息清理，防止資訊洩露
• 移除檔案路徑、堆疊追蹤等敏感資訊
• 生產環境不暴露詳細錯誤資訊
• 結構化錯誤翻譯器（per-family translator 模式）：`CellsErrorTranslator`、`WordErrorTranslator`、`PdfErrorTranslator`、`PptErrorTranslator`、`EmailErrorTranslator` 將 Aspose/BCL 例外對應為固定的安全哨兵字串，確保原始例外訊息絕不傳遞給 MCP 呼叫方

拆分操作資源保護

• Word、Excel、PowerPoint、PDF 的拆分工具均設有總工作單元上限（100,000 單元），以防止超大文檔觸發的 DoS 攻擊；超過上限時操作將被拒絕並回傳明確的錯誤訊息

Origin 驗證（DNS 重綁定攻擊防護）

• HTTP 和 WebSocket 模式預設啟用 Origin 標頭驗證
• 支援配置允許的來源域名清單
• 可配置是否允許 localhost 來源（開發環境）
• 可配置是否要求必須有 Origin 標頭
• 健康檢查端點（/health, /ready）自動排除驗證

安全限制

📡 MCP 協議支援

MCP 2026-07-28 規範支援

• 符合最新 MCP 協議規範（protocolVersion: 2026-07-28，向下相容 2025-11-25 及更早的 client）
• 使用 ModelContextProtocol SDK 2.1.0
• 完整的 JSON-RPC 2.0 錯誤處理

Tool Annotations（工具行為標註）

• Title - 人類可讀的工具標題
• ReadOnly - 標示只讀操作（如 get、list）
• Destructive - 標示可能造成破壞性變更的操作（如 delete）
• Idempotent - 標示冪等操作（重複調用產生相同結果）
• OpenWorld = false - 所有工具都是本地檔案操作，不與外部實體交互

結構化輸出（outputSchema）

• 所有工具回傳結構化 JSON 結果
• SDK 自動生成 outputSchema（使用 oneOf 支援多種結果類型）
• 包含 output 欄位（path 或 sessionId）指示輸出位置
• 客戶端可根據 schema 自動解析結果

🔍 OCR 文字辨識

文字辨識功能

• 圖片文字辨識 - 支援 PNG、JPG、BMP、TIFF 等圖片格式的文字辨識
• 掃描 PDF 轉換 - 將掃描 PDF 轉換為可編輯文件（DOCX、XLSX、PDF、TXT）
• 多語言支援 - 英文、中文、德文、法文、西班牙文、義大利文、俄文、印地文等
• 文字定位（Bounding Box） - 使用 includeWords=true 取得每個辨識單詞的座標位置（X, Y, Width, Height），適用於文字位置分析與版面重建

平台支援

• Windows x64、Linux x64、macOS x64 完整支援
• macOS ARM64 透過 Rosetta 2 支援
• Linux ARM64 不支援（ONNX Runtime 限制）

📧 Email 郵件處理

郵件格式轉換

• MSG 轉 EML - 將 Outlook MSG 格式轉換為標準 EML 格式
• EML 轉 MSG - 將 EML 格式轉換為 Outlook MSG 格式
• 完整保留郵件內容、附件與格式

郵件資訊提取

• 郵件屬性 - 提取主題、寄件者、收件者、日期等資訊
• 附件列表 - 獲取郵件中所有附件的清單
• 附件提取 - 將郵件附件提取到指定目錄
• 附件刪除 - 從郵件中移除指定附件

支援格式

• MSG - Microsoft Outlook 郵件格式
• EML - 標準電子郵件格式（RFC 822）

📊 BarCode 條碼處理

條碼生成

• 1D 條碼 - Code128、Code39、EAN-13、UPC-A 等
• 2D 條碼 - QR Code、Data Matrix、PDF417、Aztec 等
• 郵政條碼 - USPS OneCode、Australia Post、Singapore Post 等
• 自訂樣式 - 尺寸、顏色、解析度等參數可調

條碼辨識

• 多格式識別 - 自動識別圖片中的條碼類型
• 批量識別 - 一張圖片中識別多個條碼
• 支援格式 - PNG、JPG、BMP、TIFF、GIF 等圖片格式

支援的條碼類型（60+種）

• 線性條碼 - Code128、Code39、Code93、Codabar、ITF-14、ISBN、ISSN
• 二維條碼 - QR Code、Micro QR、Data Matrix、PDF417、Aztec
• 零售條碼 - EAN-8、EAN-13、UPC-A、UPC-E
• 郵政條碼 - Postnet、Planet、Australia Post、Deutsche Post

🔌 擴充功能系統

外部程序整合

• Session 變更訂閱 - 外部程序可訂閱 Session 文件變更，實現即時預覽
• 多種傳輸模式 - 支援 mmap（記憶體映射）、stdin（標準輸入）、file（臨時檔案）
• 多語言支援 - 支援 Node.js、Python、.NET、自訂解釋器、可執行檔等命令類型
• 自動進程管理 - 健康檢查、自動重啟、閒置超時卸載

擴充功能工具操作

• list - 列出所有已註冊的擴展
• bind - 將 Session 綁定到擴展
• unbind - 解除 Session 與擴展的綁定
• status - 查詢擴展狀態
• set_format - 設定快照輸出格式
• bindings - 列出 Session 的所有綁定
• command - 向綁定的擴展發送命令

詳細開發指南請參考 擴充功能開發指南，完整配置選項請參考 配置參考。

🎨 其他特性

統一字型設定

多個工具支援中英文字型分別設定（`fontNameAscii` 和 `fontNameFarEast` 參數），確保中英文混排文檔的完美顯示。

靈活的授權配置

• 支援總授權或單一組件授權
• 自動搜尋、環境變數或命令列參數配置
• 試用模式降級（找不到授權時）

跨格式轉換

• 啟用任何文檔工具時，自動包含 `convert_document`（跨格式轉換，支援 Word/Excel/PDF 轉圖片、特殊格式轉 PDF）