Preface¶

The core philosophy of DeepSeek Harness (hereinafter referred to as DSH) is “Everything is a plugin”: models, tools, sessions, and sandboxes can all be replaced at the configuration layer without modifying the framework source code. It is currently in developer preview, and its repository is located at deepseek-ai/deepseek-harness. A number of third-party plugin directories have also emerged in the community, such as the DeepSeek Harness Plugin Repository — please note that these directories are independent sites and have no official affiliation with DeepSeek / FunFinder. Do not treat them as official app stores.

After getting hands-on, a very specific gap quickly emerges: DSH’s built-in read only handles UTF-8 text. Common workspace files like .xlsx, .pdf, .docx, .pptx, and .ipynb cannot be opened directly as plain text. Claude Code natively supports reading PDFs and notebooks, while Codex has almost no corresponding capabilities. dsh-cowork is designed to fill this gap: it provides agents with a pair of controlled doc_read / doc_write tools that read and write by cell, page, slide, or notebook cell, rather than shoving entire binary files into the context window.

What is This¶

dsh-cowork is a workflow and automation plugin maintained by Jesse-njx, with its repository at Jesse-njx/dsh-cowork. It is licensed under MIT, and its primary language is TypeScript. The root package version is currently 0.1.0, and it requires Node.js 20+. As of 2026-08-18, it has 4 stars on GitHub. It was added to the plugin directory on 2026-08-14, and the repository name in the installation command is Jesse-njx/dsh-cowork.

The problem it solves can be summed up in one sentence: It enables DSH (and other agents using MCP/CLI) to read and write office documents and Jupyter notebooks within bounded context windows, using a consistent set of stable addresses for both read and write operations, rather than building separate parsers for each format.

A FAQ on the directory page describes it as “multi-agent collaboration”, which conflicts with the repository README, GitHub profile, and the “More Introduction” section of the directory page. The latter three explicitly state that this is a document reading and writing plugin. The following content will be based on the repository README and source code.

Core Features¶

The repository splits functionality into two tools instead of building five separate APIs for each format:

1. doc_read: Extract content by window. For XLSX, it returns tables with cell references (such as A1, C12); for IPYNB, it returns cells and inline outputs; for PDF, it fetches text windows by pages; for DOCX, it extracts paragraphs and word counts; for PPTX, it extracts slides and shape IDs.
2. doc_write: Version 1 only covers two formats. For XLSX, it creates or edits content via cell references; for IPYNB, it creates or edits content via cell indices. PDF, DOCX, and PPTX are currently read-only. The README places form filling and document generation in version 2.

The “Cowork = READ + WRITE” toolset relies on two design principles:
- Stable Addresses. Line numbers are meaningless for binary formats. The cell references, shape IDs, and cell indices returned by doc_read can be directly passed to doc_write.
- Bounded Windows, and Truncation Must Be Explicit. Each read operation has an upper limit (page/row/slide/cell/byte). When the window is truncated, a > Truncated: prompt will appear, rather than silently dropping the latter part of the content.

This is a pnpm monorepo, and the packages directly related to document reading and writing are as follows:

The English README also lists packages/chatnode-wechat, which is used to view and approve DSH agents via WeChat session nodes. This is not part of the document reading and writing capability, and it is not included in the package list of the Chinese README, so it will not be elaborated here.

The security model is specifically documented in the README, not just slogans:
- OOXML archives are checked for entry count and post-extraction size before decompression to block zip bombs.
- Macro formats containing vbaProject.bin (.xlsm / .docm / .pptm) are一律 rejected, and the plugin will not read or write such files.
- When the sandbox is in read-only mode, doc_write is strictly prohibited, while doc_read remains available.
- Before editing, the file must have been read in the current session (expected_version), and a content hash (expected_sha256) can also be added.
- Overwriting an existing file: Requires prior reading of the file in DSH; for CLI/MCP, you need to explicitly use force.
- Writes go through a temporary file before being renamed to avoid leaving partial files.
- Modified XLSX files will clear cached formula results to allow Excel/LibreOffice to recalculate when opened (exceljs itself does not handle formulas).
- Formulas, hidden worksheets, and speaker notes are only treated as data for display and are not executed.

The DSH plugin package uses ctx.fs for file reading (bounded readBytes, sandbox path resolution, fs/observed events). Since the fs service only supports text writing, byte writing is handled by the plugin itself with atomic renaming, and the actual version number is observed after writing to allow the built-in policies to continue working.

Installation and Activation¶

The installation command provided on the plugin directory page is:

dsh plugin add github:Jesse-njx/dsh-cowork

For reproducible installations, the directory page recommends pinning the commit hash:

dsh plugin add github:Jesse-njx/dsh-cowork#commit

Replace commit with the actual hash value.

The repository README and docs/shipping.md provide more detailed instructions: it is not currently published to npm, and the distribution channel is GitHub. The actual DSH plugin package is located in packages/dsh, not the repository root. The recommended installation steps from the repository are to first clone, install dependencies, build, then add the local path to your profile:

git clone https://github.com/Jesse-njx/dsh-cowork.git
cd dsh-cowork
pnpm install
dsh plugin --profile <your-profile> add ./packages/dsh

pnpm install will trigger the root package’s prepare script to build all packages. The development dependencies show that @deepseek-ai/dsh-* is at version 0.1.0-rc.6, indicating that it was developed against the current DSH preview version. If there are breaking changes to the interface in future updates, you will need to recheck compatibility.

After installation, the doc_read / doc_write tools will appear in the model’s available functions. The README suggests verifying with a real session: ask the model to call doc_read on an .xlsx file.

Optional configuration is written in your profile’s cordis.patch.yml under the cowork-docs entry. The default values given in the README are all modifiable:

- id: cowork-docs
  name: '@dsh-cowork/plugin'
  config:
    maxInputBytes: 67108864
    maxOutputBytes: 262144
    maxDecompressedBytes: 536870912
    maxZipEntries: 4096
    maxPages: 20
    maxSheetRows: 200
    maxSheets: 1
    maxSlides: 20
    maxCells: 200

Their approximate meanings are: 64 MiB single input limit, 256 KiB model-facing context window, 512 MiB decompression limit (for zip bomb protection), up to 20 pages per window for PDF, 1 sheet and 200 rows per window for XLSX, up to 20 slides for PPTX, and up to 200 cells for IPYNB.

Typical Usage¶

After installing it into DSH, prioritize letting the model use the tools rather than manually unpacking OOXML in the shell. The XLSX read output is a Markdown table with cell references, and you can directly use these references for subsequent edits instead of guessing based on “row and column numbers”.

If the agent is not running in DSH, the same core library also provides MCP and CLI interfaces. An example MCP configuration (replace the path with your cloned repository directory):

{
  "mcpServers": {
    "cowork": {
      "command": "node",
      "args": ["<repo>/packages/mcp/lib/index.js"],
      "cwd": "<working-directory>"
    }
  }
}

The command line tools are provided by @dsh-cowork/cli, with binary names doc-read and doc-write. Examples given in the repository:

doc-read report.xlsx --sheets Data --rows 50
doc-write edit report.xlsx --spec edit-spec.json

packages/cli/SKILL.md has complete parameter documentation. Common window parameters for reading include --page / --pages, --sheets, --row-offset / --rows, --slide / --slides, --cell / --cells, --max-bytes; adding --json will output structured data with addresses, formulas, and prompts instead of Markdown.

The write operation is divided into creation and editing:

doc-write create <file> <xlsx|ipynb> --spec spec.json [--force]
doc-write edit <file> --spec spec.json [--force]

The structure of the specification file is based on the CLI documentation, for example:
- Create XLSX: {"sheets":[{"name":"S1","cells":[{"ref":"A1","value":42}]}]}, values can be strings, numbers, booleans, null, or {"formula":"SUM(A1:A2)"}.
- Edit XLSX: {"format":"xlsx","edits":[{"sheet":"S1","ref":"A1","value":"x"}]}.
- Create IPYNB: {"cells":[{"type":"markdown","source":"# Hi"},{"type":"code","source":"print(1)"}]}.
- Edit IPYNB: {"format":"ipynb","edits":[{"op":"replace","cell":0,"source":"..."}]}, where op can be replace, insert, or delete.

When overwriting an existing file, CLI/MCP requires the --force flag. After editing is complete, the documentation suggests calling doc-read again to confirm the results before notifying the user that the changes have been completed. When > Truncated: appears, you should increase the offset to continue reading instead of attempting to fill in the unseen parts.

Applicable Scenarios and Notes¶

This plugin is suitable for the following types of work:
- Enable DSH agents to read reports, edit cells, extract PDF text, view slide structures, or modify a specific cell in a Jupyter notebook.
- For users already using Codex / Claude Code who want to unify their document handling capabilities via MCP.
- For users who simply want to perform bounded extraction or specification-based editing of binary documents in the terminal, using the CLI tool.

There are several important points to note before use:
1. The plugin runs with the permissions of the current DSH process, and code may be executed during installation. You should inspect the source code repository and license before installing; the directory page also includes this warning. This repository uses the MIT license and has public source code, but it is still recommended to review packages/dsh and packages/core to confirm that the read/write boundaries are acceptable.
2. Version 1 only supports writing to XLSX and IPYNB formats. Do not assume that it can generate Word, PPT, or fill PDF forms — those are planned for version 2.
3. Macro-enabled formats will be directly rejected. Do not submit workbooks, documents, or presentations that require macros to this plugin for editing.
4. The default window size is small: XLSX only shows 1 sheet and 200 rows by default. For large tables, you need to use offsets to read in segments. The truncation prompt is part of the mechanism, not an error.
5. DSH is still undergoing rapid iteration, and the repository notes that there may be breaking changes during the preview period. @dsh-cowork/plugin currently lists peerDependencies against DSH package version 0.1.0-rc.6, so you should re-test doc_read / doc_write after upgrading DSH.

Summary¶

dsh-cowork does not modify DSH’s source code, but instead follows the official CONTRIBUTING recommended path to become an out-of-repository plugin: it provides agents with controlled read/write access to office documents and notebooks via doc_read / doc_write. It can read five formats and write two; it uses stable addresses, has bounded windows, and has explicit rejection rules for macro files and zip bombs. The same core library can also be connected to other harnesses via MCP and CLI.

Plugin Directory: https://deepseek-harness-plugin.com/en-US/plugins/dsh-cowork/

GitHub: https://github.com/Jesse-njx/dsh-cowork