dsh-extension-workbook：高保真 Excel 工作簿檢視與編輯插件

前言¶

DeepSeek Harness (DSH) 的核心設計理念是「一切皆插件」。當智能體需要在本地環境中處理 Excel 文件時，常見的挑戰在於如何在不執行潛在危險的宏、不破壞文件結構的前提下完成讀寫。傳統的解析工具往往在遇到加密、ZIP64 等複雜格式時靜默降級，導致數據丟失或格式錯亂。

dsh-extension-workbook 旨在解決上述問題。它是一個高保真、fail-closed 的工具集，用於檢視、渲染、編輯、比對與驗證 Excel XLSX/XLSM 工作簿。該插件移植自 @firstpick/pi-extension-workbook，核心目標是確保每一次文件操作都在受控的流程中進行，任何不符合預期的格式或權限問題都會被明確拒絕。

插件定位¶

• 來源：移植自 @firstpick/pi-extension-workbook（MIT 許可證）。
• 維護者：GongYuanCaiJi。
• 核心能力：在不修改源文件的前提下進行深度檢視，並通過受保護的提交流程完成編輯，支持結構比對與完整性校驗。

核心功能¶

該插件提供了一系列針對工作簿的原子化操作：

1. 高保真檢視：可以檢視 .xlsx 與 .xlsm 工作簿，查看工作表、區域、OOXML 部件、鏈接及受保護的宏內容，且不會改動源文件。
2. 可視化渲染：將工作表或指定區域渲染爲確定性 PNG 圖片，便於視覺檢查格式與佈局。
3. 安全編輯流程：編輯操作遵循嚴格的受保護流程：先進行 dry-run 規劃，檢查 expectedSha256 衝突，執行原子寫入，提交後立即校驗。支持就地編輯並保留恢復副本。
4. 差異比對：對比兩個工作簿的結構與內容，並在接受結果前校驗其完整性。
5. 診斷工具：內置六把 workbook_* 工具與 workbook-doctor 診斷命令，用於排查問題。

安裝與啓用¶

由於本包尚未發佈到 npm，需通過 GitHub 倉庫進行安裝。

dsh plugin --profile <profile> add github:GongYuanCaiJi/dsh-extension-workbook

安裝時會自動觸發構建。若遇到構建問題，需檢查 Node.js 版本（要求 24 或更新）並在 profile 的 pnpm-workspace.yaml 中配置 allowBuilds。安裝完成後需重啓 DSH 以使插件生效。

典型用法¶

使用時，直接引用文件路徑並描述需求。插件會根據內部工具鏈處理。

• 指令示例：
  > 檢視這個工作簿，修正 Summary 表中的合計，保持格式不變，並展示校驗結果。
• 推薦工作流：
  1. 先執行 workbook_inspect 或 workbook_render 熟悉文件結構。
  2. 審閱模型建議的單元格改動。
  3. 執行比對與校驗，確認無誤後保留編輯後的文件。

適用場景與注意¶

• Fail-closed 策略：任何無法以字節級保真處理的包（如 ZIP64、加密文件、共享/數組/數據表/溢流公式區域、不可變受保護部件）都會被明確拒絕，不會靜默降級。
• 不碰宏：插件只清點、保留與校驗 VBA 等受保護內容，絕不執行或修改宏代碼。
• 可審計性：模型可見輸出有上限，超出時完整 JSON 會落地到臨時文件並返回路徑。
• 源碼審查：由於未發佈到 npm，建議在本地安裝前檢查源碼與許可證。

總結¶

dsh-extension-workbook 爲 DSH 提供了一套可靠的工作簿處理能力。通過引入 SHA-256 校驗、dry-run 規劃和 fail-closed 機制，它能在保證安全的前提下完成複雜的 Excel 操作，適合對數據完整性和安全性要求較高的自動化場景。

• 插件目錄
• GitHub 倉庫