@deepseek-ai/dsh-tool-doc

Readme

# @deepseek-ai/dsh-tool-doc

English | [中文](README.zh.md)

Model-facing document tools: read, create and edit PDF / DOCX / XLSX / PPTX / CSV / Markdown files without shelling out to external utilities.

## What it does

Registers three tools on `ctx.tools`:

- `read_document(file_path)` — reads PDF (text layer, page by page), DOCX (mammoth), XLSX (every sheet, cell values), PPTX (per-slide text), CSV (delimiter-sniffed, quote-aware) and plain text (md/txt/yaml/json/log). Output is bounded by `maxTextChars` (default 200,000) with an explicit truncation notice. Scanned/image-only PDFs yield no text.
- `create_document(file_path, content)` — creates a NEW file; the target must not exist (createIfAbsent semantics — use `edit_document` to change an existing file). DOCX/PDF take Markdown-lite `text` (`# `/`## `/`### ` headings, `- ` bullets) plus `title` and (DOCX) `tables`; XLSX takes `sheets`; CSV takes `rows`; md/txt take plain `text`. PDF embeds a system CJK font when one is discoverable (`cjkFontPath` config overrides the search).
- `edit_document(file_path, operations)` — applies ordered literal edits in place. DOCX: `replace_text` (inside single text runs, `count` defaults to 1, `'all'` replaces every match) and `append_paragraph`. XLSX: `set_cell` / `append_rows` / `add_sheet` (1-based addressing; `sheet` omitted means the first sheet). CSV: `set_cell` / `append_rows`. Operations validate up front; a rejected op aborts the call before any write.

Legacy binary `.doc` / `.xls` / `.ppt` files are not supported — the tools ask the user to convert them first. PPTX is read-only.

## Filesystem seam

Text formats (csv/md/txt/…) read and write through the governed `ctx.fs` seam, so sandbox policy, approval flows and observation events apply as with the native `read`/`write` tools. Binary formats read through `ctx.fs.readBytes` (capped by `readMaxBytes`, default 50 MB) but write to the resolved process path with `node:fs`, because the seam is text-only; sandbox write policy does not fence those binary writes.

## Configuration

All optional: `maxTextChars` (read text budget), `readMaxBytes` (binary read cap), `cjkFontPath` (explicit CJK font file for PDF creation — any fontkit-openable TTF/OTF/TTC).

## Model Experience

### Tool schema

The model sees one schema per tool with a precise per-format description; `edit_document` operations are a `oneOf` discriminated by a const `op`, so the model gets an exact contract for each edit kind.

### Tool-call history and result

Read results carry a `<path>/<kind>/<details>/<content>` envelope (bounded text); create/edit results return a one-line acknowledgement with byte counts or per-op summary numbers. Errors are stable Chinese/English message strings describing the rejection (unsupported legacy format, target already exists, unknown worksheet, zero matches, …).

## Known Limitations and Deferred Work

- **PDF CJK fonts are discovered, not bundled** — with no usable system font, CJK text falls back to the built-in Latin font (the create result reports it). The `.ttc` collection path extracts the first face to a temp TTF because pdfkit cannot embed collections.
- **DOCX edits are paragraph-level** — `replace_text` matches inside single `<w:t>` runs (text split across runs does not match); headers, footers, fields and numbering are out of edit scope.
- **No in-place edits for PDF/PPTX/text** — recreate with `create_document` instead.
- **Legacy binary office formats unsupported** — `.doc`/`.xls`/`.ppt` need a user-side conversion first.