Introduction

The core design philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” When an agent needs to handle Excel files in a local environment, a common challenge is how to read and write files without executing potentially dangerous macros or damaging the file structure. Traditional parsing tools often silently degrade when encountering complex formats such as encrypted files or ZIP64, leading to data loss or malformed formatting.

dsh-extension-workbook aims to address the issues above. It is a high-fidelity, fail-closed toolkit for inspecting, rendering, editing, comparing, and verifying Excel XLSX/XLSM workbooks. It was ported from @firstpick/pi-extension-workbook, with the core goal of ensuring that every file operation is performed within a controlled workflow and that any unexpected formatting or permission issue is explicitly rejected.

Plugin Positioning

  • Source: Ported from @firstpick/pi-extension-workbook (MIT license).
  • Maintainer: GongYuanCaiJi.
  • Core capabilities: Perform deep inspection without modifying the source file, and complete edits through a protected commit workflow, supporting structural comparison and integrity verification.

Core Features

The plugin provides a series of atomic operations for workbooks:

  1. High-fidelity inspection: Inspect .xlsx and .xlsm workbooks to view worksheets, ranges, OOXML parts, links, and protected macro content, without modifying the source file.
  2. Visual rendering: Render worksheets or specified ranges into deterministic PNG images for visual inspection of formatting and layout.
  3. Safe editing workflow: Editing follows a strict, protected workflow: first perform a dry-run plan, check for expectedSha256 conflicts, execute an atomic write, and immediately verify after commit. Supports in-place editing while preserving a recovery copy.
  4. Difference comparison: Compare the structure and content of two workbooks and verify integrity before accepting the result.
  5. Diagnostics: Built-in six workbook_* tools and a workbook-doctor diagnostic command for troubleshooting.

Installation and Activation

Because this package has not been published to npm yet, it must be installed from the GitHub repository.

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

A build is triggered automatically during installation. If you encounter build issues, check the Node.js version (requires 24 or newer) and configure allowBuilds in the profile’s pnpm-workspace.yaml. After installation, restart DSH to activate the plugin.

Typical Usage

When using it, directly reference the file path and describe the requirement. The plugin will handle it using its internal toolchain.

  • Command example:
    > Inspect this workbook, correct the totals in the Summary sheet, keep the formatting unchanged, and show the verification result.
  • Recommended workflow:
    1. Run workbook_inspect or workbook_render first to familiarize yourself with the file structure.
    2. Review the cell changes suggested by the model.
    3. Run the comparison and verification steps, then keep the edited file after confirming there are no issues.

Use Cases and Cautions

  • Fail-closed policy: Any package that cannot be processed with byte-level fidelity (such as ZIP64, encrypted files, shared/array/data-table/overflow formula ranges, and immutable protected parts) will be explicitly rejected, without silent degradation.
  • Do not touch macros: The plugin only inventories, preserves, and verifies protected content such as VBA, and never executes or modifies macro code.
  • Auditability: Model-visible output has a limit; when exceeded, the complete JSON is written to a temporary file and its path is returned.
  • Source review: Because it has not been published to npm, it is recommended to review the source code and license before installing it locally.

Summary

dsh-extension-workbook provides DSH with a reliable workbook processing capability. By introducing SHA-256 verification, dry-run planning, and fail-closed mechanisms, it can complete complex Excel operations while maintaining safety, making it suitable for automation scenarios with high requirements for data integrity and security.