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。
核心能力：在不修改源文件的前提下进行深度检视，并通过受保护的提交流程完成编辑，支持结构比对与完整性校验。

核心功能¶

该插件提供了一系列针对工作簿的原子化操作：

高保真检视：可以检视 .xlsx 与 .xlsm 工作簿，查看工作表、区域、OOXML 部件、链接及受保护的宏内容，且不会改动源文件。
可视化渲染：将工作表或指定区域渲染为确定性 PNG 图片，便于视觉检查格式与布局。
安全编辑流程：编辑操作遵循严格的受保护流程：先进行 dry-run 规划，检查 expectedSha256 冲突，执行原子写入，提交后立即校验。支持就地编辑并保留恢复副本。
差异比对：对比两个工作簿的结构与内容，并在接受结果前校验其完整性。
诊断工具：内置六把 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 操作，适合对数据完整性和安全性要求较高的自动化场景。