dsh-tool-docx 0.5.0

package/LICENSE

@@ -0,0 +1,53 @@
+MIT License
+
+Copyright (c) 2026 BroBFG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Attribution for derived code
+
+Portions of `src/sandbox.ts`, the atomic-write pattern in `src/fsio-bytes.ts`,
+and the containment logic in `src/path-contains.ts` are derived from the
+deepseek-harness project
+(https://github.com/deepseek-ai/deepseek-harness), distributed under the MIT
+License:
+
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,7 @@
+# Trilingual README consistency record: the git blob hash of each side as of the
+# last confirmed-consistent state. All three languages carry equal authority; after
+# editing any side, bring the others along and re-record the hashes
+# (git hash-object <file>).
+README.md: dcfd3f0a66b1965ed198bb57dff32e5a0b4b3ee4
+README.zh.md: fbb4039011e581f9ef1a58ca0854e5f9f9b4ca39
+README.ru.md: 24ba8e1dd45e8b084a0b46332a27570d59f6175f

package/README.md

@@ -0,0 +1,202 @@
+# dsh-tool-docx
+
+English | [中文](README.zh.md) | [Русский](README.ru.md)
+
+Model-facing Microsoft Word (`.docx`) tools for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): `docx_read` extracts a document as Markdown or structured JSON blocks, `docx_create` generates a new `.docx` from Markdown, and `docx_edit` replaces a document's content from Markdown while preserving its title/author/created properties. `.docx` is a ZIP of XML parts, so every tool reads the whole package through the bounded `ctx.fs.readBytes` primitive and writes packages through the plugin's `fsBinary` binary write service (or a host `ctx.fs` that provides `writeBytes` natively) — the same atomic, sandbox-fenced mutations the text tools use, without ever replacing the host's own filesystem.
+
+This repository is the **standalone distribution** of the plugin. The plugin is **original work written for DeepSeek Harness** — an independent plugin developed by this project, initially in a local `deepseek-harness` checkout (the harness is its runtime target), not a copy of a plugin from the shared repository. It plugs into the harness's `tools`, `fs`, and `systemPrompt` services, and it builds and tests on its own against the published `@deepseek-ai/*` packages, so it can be installed into any harness checkout.
+
+## Requirements
+
+- A DeepSeek Harness host (the `0.1.0-rc.7` line) whose filesystem seam provides the **read** primitive `fs.readBytes` — published in `@deepseek-ai/dsh-fs` since `0.1.0-rc.7`. The **write** side (`writeBytes`) is not in any published `dsh-fs` release, so the bundle mounts the plugin's [binary fs providers](#binary-fs-providers): a separate `fsBinary` service that implements `writeBytes` (fenced for sandboxed hosts) without touching `ctx.fs`. Without any binary writer — no `fsBinary` service and no native `ctx.fs.writeBytes` — `docx_read` still works, while `docx_create`/`docx_edit` fail with a typed `DOCX_HOST_FS_UNSUPPORTED` error naming the fix.
+- The harness provides the peer services (the `0.1.0-rc.7` line): `cordis`, `dsh-tools`, `dsh-fs`, `dsh-llm`, `dsh-sandbox`, `dsh-sandbox-policy`, `dsh-system-prompt`, `dsh-invariants`, `dsh-user-approval`, `dsh-session`.
+
+## Installation
+
+The official install path is the harness's own plugin manager — one command installs the package into the profile, and the profile launcher activates the bundle's [`cordis.patch.yml`](cordis.patch.yml) layer automatically (the package declares `dsh.bundle.patch`):
+
+```sh
+dsh plugin --profile web add github:BroBFG/dsh-tool-docx#v0.5.0
+```
+
+`dsh plugin` runs pnpm inside the profile directory and reconciles `dsh.profile.bundles` against the installed state, so nothing else is needed — no `allowBuilds` entries (the package ships its built `lib/` and has no build scripts), no manual `cordis.patch.yml` editing, no `--patch` overlays. Restart the harness afterwards.
+
+- **Update:** `dsh plugin --profile web update dsh-tool-docx`, or re-run `add` with the new tag.
+- **Remove:** `dsh plugin --profile web remove dsh-tool-docx`.
+- **Local development:** `dsh plugin --profile web add ../dsh-tool-docx` (relative specs are anchored to the directory you invoke from) or `dsh plugin --profile web add link:../dsh-tool-docx`.
+
+> npm publication is planned but not yet available; the package ships under the standalone name `dsh-tool-docx` (the `dsh-tool-*` ecosystem convention), independent of the `@deepseek-ai` scope.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `docx_read(file_path, format?, max_chars?)` | Extract document body as Markdown (default) or structured JSON blocks plus `docProps`. Emits `fs/observed`. |
+| `docx_create(file_path, markdown, title?, author?)` | Generate a new `.docx` from Markdown. Guarded `createIfAbsent`: an existing file is never blindly overwritten. |
+| `docx_edit(file_path, markdown)` | Read the current document (validating it is a docx), preserve `docProps`, regenerate the body from the full Markdown, and write back with a version guard (`DOCX_STALE` on a concurrent change). |
+
+All three resolve relative paths against the calling agent's session cwd, dispatch the `fs/write-intent` waterfall before mutating (the observation-policy plugin may supply its own intent), and record `fs/observed` on completion — so the sandbox fence, escalation fields, and read-before-write policy apply to docx mutations exactly as they do to `write`/`edit`.
+
+## Config
+
+| Field | Default | Meaning |
+|---|---|---|
+| `maxDocxBytes` | 64 MiB | Inclusive byte cap on a whole `.docx` file (read + ZIP expansion). |
+| `maxMarkdownChars` | 1 000 000 | Inclusive character cap on the Markdown input to create/edit. |
+| `maxReadChars` | 200 000 | Inclusive character cap on the Markdown returned by `docx_read`. |
+
+## Binary fs providers
+
+The base bundle's `fs-sandbox` row keeps providing `ctx.fs` **unchanged**. The bundle patch adds the docx tools plus one of the binary providers, which register the binary `writeBytes` primitive as a **separate `fsBinary` service** — the host filesystem is never replaced, so this plugin cannot break the harness boot; at worst, without the provider, the mutating tools report `DOCX_HOST_FS_UNSUPPORTED`:
+
+- **`dsh-tool-docx/fs-binary-sandbox-plugin`** (mounted by the bundle; recommended for sandboxed hosts) — registers `fsBinary.writeBytes` fenced by the **same per-call policy** as every sandbox mutation: `workspace-write` containment, `read-only` denial, `danger-full-access` passthrough, `FS_SANDBOX_DENIED` on refusal (mapped to `DOCX_SANDBOX_DENIED` at the tool layer).
+- **`dsh-tool-docx/fs-binary-local-plugin`** — registers `fsBinary.writeBytes` **unfenced**, for minimal contexts (tests, headless scripts) or hosts that fence above the provider. To mount it instead of the sandboxed one, override the bundle row in your profile `cordis.patch.yml`:
+
+  ```yaml
+  - id: fs-binary-sandbox
+    disabled: true
+  - insert:
+      - id: fs-binary-local
+        name: dsh-tool-docx/fs-binary-local-plugin
+  ```
+
+Both use the same probe → intent-guard (`createIfAbsent` / `replaceIfVersion`) → atomic-publish flow as the harness seam: a private owner-only staging directory, fsync, then atomic publication (a hard-link no-replace primitive for `createIfAbsent`), with per-target serialization. The first version omits the harness's Win32 DACL-preservation ceremony — a replacement inherits the owner-only ACL of the staged temp file.
+
+For hosts that deliberately want the full backend mounted **as `ctx.fs`** (replacing `fs-sandbox`), the package also ships the provider classes `dsh-tool-docx/fs-binary-sandbox` and `dsh-tool-docx/fs-binary-local`; the replace-the-row recipe still applies:
+
+```yaml
+- id: fs-sandbox
+  disabled: true
+- insert:
+    - id: fs-binary-sandbox
+      name: dsh-tool-docx/fs-binary-sandbox
+    - id: tool-docx
+      name: dsh-tool-docx
+```
+
+## Design notes
+
+- **Extraction** (`src/docx/extract.ts`) walks `word/document.xml` with `fast-xml-parser`: headings (`Heading1`–`Heading6`, `Title`), bold/italic/strike runs, nested lists through `word/numbering.xml` (bullet vs decimal), pipe tables (merged cells approximate), external hyperlinks through `word/_rels/document.xml.rels`, and embedded images as counted placeholders. Unsupported constructs degrade to warnings, never failures.
+- **Generation** (`src/docx/generate.ts`) renders the block model with the `docx` library: ATX headings, styled inline runs, 9-level bullet/numbered numbering, pipe tables, and `[text](url)` external hyperlinks. `parseMarkdown` (src/markdown.ts) accepts the subset the extractor emits, so read → edit → write round trips are stable.
+- **Caps are enforced at the seam, not in the tool** — the whole-file byte cap flows into `ctx.fs.readBytes` (`FS_TOO_LARGE` maps to `DOCX_TOO_LARGE`), and the ZIP reader applies the same cap to the uncompressed total, so a compressed bomb cannot expand without limit.
+- **Sandbox parity** — `src/sandbox.ts` mirrors `dsh-tool-fs`'s escalation API (`sandbox_permissions`/`justification` advertised only under a confining backend, denial marker mapping); extracting a shared controller is deferred (see below).
+- **Host filesystem contract** — `src/fs-binary.ts` declares the binary contract the tools need and resolves the writer at call time: the plugin's `fsBinary` service when mounted, else a host `ctx.fs` that natively provides `writeBytes`. Without any binary writer it raises `DOCX_HOST_FS_UNSUPPORTED` with a pointer to the fix instead of a cryptic `fs.writeBytes is not a function`; `docx_read` needs only the published `ctx.fs.readBytes`.
+
+## Model Experience
+
+### System prompt
+
+#### What the model sees
+
+The `tool:docx-read` section below is registered once at plugin apply:
+
+##### The docx guidance section
+
+```markdown
+MS Word .docx files are binary (ZIP+XML) and the read tool cannot read them. Use docx_read to extract a document as Markdown (default) or structured JSON blocks, docx_create to generate a new .docx from Markdown, and docx_edit to replace a document's content from Markdown while preserving its title/author/created properties. Legacy .doc is not supported — convert it to .docx first.
+```
+
+#### Token effect
+
+Fixed guidance cost per request while the plugin is mounted; the section is unaffected by scoped tool restrictions.
+
+#### KV Cache effect
+
+Prefix-stable while the guidance text is unchanged. Plugin lifecycle or a text change may invalidate reuse from the first changed prompt section.
+
+### Tool schemas
+
+#### What the model sees
+
+The generated `docx_read`, `docx_create`, and `docx_edit` schemas — parameters and canonical outputs as summarized in the [Tools](#tools) table. The byte/character caps are deployment settings, not model arguments; the escalation fields appear only under a confining filesystem backend.
+
+#### Token effect
+
+Fixed schema cost per request for each mounted tool; config disablement removes schemas and guidance together, while a scoped restriction removes only the schema.
+
+#### KV Cache effect
+
+Prefix-stable while definitions and visibility are unchanged. Config enablement, plugin lifecycle, or scoped restrictions may invalidate reuse from the first changed schema token.
+
+### Read result
+
+#### What the model sees
+
+A successful `docx_read` renders the extracted Markdown (or pretty-printed JSON blocks). Truncation appends `\n… (truncated)`; failures are typed messages such as `file not found: <path>`, `the document is encrypted (password-protected); decryption is not supported`, or the legacy hint `legacy .doc format is not supported — convert the document to .docx first`.
+
+#### Token effect
+
+Data-dependent results are capped by `maxReadChars` (or the call's `max_chars`) and resent until compaction.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Create/Edit result
+
+#### What the model sees
+
+A successful create/edit renders a short `<path>`/`<type>docx</type>` envelope with the byte size — never the document body. Warnings about approximations (images, merged cells, code blocks) are carried in the canonical `warnings` array and rendered as plain text.
+
+#### Token effect
+
+Only the retained call arguments (including the full Markdown input) and the short result add tokens; the generated package bytes never enter the session log.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+### Argument errors
+
+#### What the model sees
+
+Blank `file_path` becomes `Error: file_path must be a non-empty string`; markdown over the input cap becomes `Error: markdown exceeds the <n>-character limit`.
+
+#### Token effect
+
+Only the failing call adds these retained tokens.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **Legacy `.doc` (OLE) is unsupported** — binary OLE needs LibreOffice or Word COM conversion; the tools fail with `DOCX_LEGACY_DOC` and a hint to convert to `.docx` first.
+- **Images are not extracted or embedded** — `docx_read` counts images and emits placeholders; `docx_create`/`docx_edit` drop image syntax with a warning. Extracting image bytes and embedding them on generate is deferred.
+- **Round-trip regenerates the document** — styles, page setup, headers/footers, and section breaks are not preserved; an edit rebuilds the body with default styles, keeping only title/author/created. Layout fidelity is not a goal of the round trip.
+- **Merged table cells approximate** — `gridSpan`/`vMerge` degrade to plain pipe-table cells with a warning; footnotes, endnotes, text boxes, and page breaks are dropped (warnings included).
+- **The sandbox controller duplicates `dsh-tool-fs`** — extracting a shared `FsSandboxController` is deferred; the two copies must be kept in sync until then.
+- **Markdown input subset** — blockquotes, horizontal rules, nested fences, and images are not represented; they degrade to paragraphs with a warning (fenced code becomes code-styled paragraphs).
+
+## Development
+
+```sh
+pnpm install
+pnpm typecheck   # tsc over src/
+pnpm build       # tsc → lib/types + tsdown → lib/index.js, lib/invariant.js
+pnpm test        # vitest: unit conversion tests + consumer tests over a fake fs
+pnpm pack        # produce the npm tarball (files: lib/index.js, lib/invariant.js, lib/types/**/*.d.ts)
+```
+
+Layout:
+
+- `src/docx/` — ZIP/XML extraction and `docx`-library generation;
+- `src/tools/` — the three tool registrations;
+- `src/fs-binary.ts` — the binary filesystem contract and the call-time writer resolver (`fsBinary` service or native `ctx.fs.writeBytes`);
+- `src/fs-binary-local.ts`, `src/fs-binary-sandbox.ts`, `src/fsio-bytes.ts`, `src/path-contains.ts` — the binary fs provider classes and the atomic writer + containment helpers;
+- `src/fs-binary-sandbox-plugin.ts`, `src/fs-binary-local-plugin.ts` — the namespace plugins that register the `fsBinary` service (the bundle's default mount);
+- `tests/` — conversion round-trip tests, provider tests, and consumer tests against the published `ToolRuntime` service (exported since `dsh-tools@0.1.0-rc.7`).
+
+## Relationship to deepseek-harness
+
+This plugin is an **original, independent project written for DeepSeek Harness** — it plugs into the harness's public services (`tools`, `fs`, `systemPrompt`) and is developed in a local `deepseek-harness` checkout for testing against the harness. It is not a copy of a plugin from the shared `deepseek-harness` repository and is not part of it; this repository is the canonical distribution. Two implementation notes:
+
+1. `src/fs-binary.ts` (host contract + writer resolver) — the binary `readBytes`/`writeBytes` contract is part of this plugin's design. `readBytes` is published in the harness's `dsh-fs` release line since `0.1.0-rc.7`; `writeBytes` is not, so the [binary fs providers](#binary-fs-providers) ship it as a separate `fsBinary` service instead of patching the host;
+2. `tests/` runs against the published `ToolRuntime` service (exported since `dsh-tools@0.1.0-rc.7`), so the consumer tests exercise the real registry pipeline rather than a local double.
+
+The plugin is developed and maintained entirely in this repository against the published `@deepseek-ai/*` packages; the harness checkout is only a runtime target used for integration verification, and carries no copy of this plugin.
+
+## License
+
+MIT © 2026 BroBFG. Portions of `src/sandbox.ts`, the atomic-write pattern in `src/fsio-bytes.ts`, and the containment logic in `src/path-contains.ts` are derived from [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) (MIT, Copyright (c) 2026 DeepSeek) — see [LICENSE](LICENSE).

package/README.ru.md

@@ -0,0 +1,202 @@
+# dsh-tool-docx
+
+[English](README.md) | [中文](README.zh.md) | Русский
+
+Ориентированные на модель инструменты Microsoft Word (`.docx`) для [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): `docx_read` извлекает документ как Markdown или структурированные JSON-блоки, `docx_create` генерирует новый `.docx` из Markdown, а `docx_edit` заменяет содержимое документа из Markdown, сохраняя его свойства title/author/created. `.docx` — это ZIP-архив XML-частей, поэтому каждый инструмент читает весь пакет через ограниченный примитив `ctx.fs.readBytes` и записывает пакеты через бинарный сервис записи плагина `fsBinary` (или через `ctx.fs` хоста, если он нативно предоставляет `writeBytes`) — те же атомарные, ограждённые песочницей мутации, которые используют текстовые инструменты, при этом собственная файловая система хоста никогда не заменяется.
+
+Этот репозиторий — **автономное распространение** плагина. Плагин — **оригинальная работа, написанная для DeepSeek Harness**: независимый плагин, разработанный этим проектом, изначально в локальном checkout `deepseek-harness` (harness — его среда выполнения), а не копия плагина из общего репозитория. Он подключается к сервисам harness `tools`, `fs` и `systemPrompt` и самостоятельно собирается и тестируется против опубликованных пакетов `@deepseek-ai/*`, поэтому его можно установить в любой checkout harness.
+
+## Требования
+
+- Хост DeepSeek Harness (линия `0.1.0-rc.7`), чей слой файловой системы предоставляет **примитив чтения** `fs.readBytes` — опубликован в `@deepseek-ai/dsh-fs` начиная с `0.1.0-rc.7`. **Сторона записи** (`writeBytes`) отсутствует во всех опубликованных релизах `dsh-fs`, поэтому бандл монтирует [бинарные fs-провайдеры](#бинарные-fs-провайдеры) плагина: отдельный сервис `fsBinary`, реализующий `writeBytes` (с ограждением для песочных хостов), не затрагивая `ctx.fs`. Без какого-либо бинарного writer'а — ни сервиса `fsBinary`, ни нативного `ctx.fs.writeBytes` — `docx_read` по-прежнему работает, а `docx_create`/`docx_edit` завершаются типизированной ошибкой `DOCX_HOST_FS_UNSUPPORTED` с указанием исправления.
+- Harness предоставляет peer-сервисы (линия `0.1.0-rc.7`): `cordis`, `dsh-tools`, `dsh-fs`, `dsh-llm`, `dsh-sandbox`, `dsh-sandbox-policy`, `dsh-system-prompt`, `dsh-invariants`, `dsh-user-approval`, `dsh-session`.
+
+## Установка
+
+Официальный путь установки — собственный менеджер плагинов harness: одна команда устанавливает пакет в профиль, а лаунчер профиля автоматически активирует слой [`cordis.patch.yml`](cordis.patch.yml) бандла (пакет объявляет `dsh.bundle.patch`):
+
+```sh
+dsh plugin --profile web add github:BroBFG/dsh-tool-docx#v0.5.0
+```
+
+`dsh plugin` запускает pnpm внутри каталога профиля и сверяет `dsh.profile.bundles` с установленным состоянием, поэтому больше ничего не нужно — ни записей `allowBuilds` (пакет поставляется с готовым `lib/` и без build-скриптов), ни ручного редактирования `cordis.patch.yml`, ни overlay через `--patch`. После этого перезапустите harness.
+
+- **Обновление:** `dsh plugin --profile web update dsh-tool-docx`, либо повторный `add` с новым тегом.
+- **Удаление:** `dsh plugin --profile web remove dsh-tool-docx`.
+- **Локальная разработка:** `dsh plugin --profile web add ../dsh-tool-docx` (относительные spec привязываются к каталогу вызова) или `dsh plugin --profile web add link:../dsh-tool-docx`.
+
+> Публикация в npm запланирована, но пока недоступна; пакет поставляется под самостоятельным именем `dsh-tool-docx` (конвенция экосистемы `dsh-tool-*`), независимо от scope `@deepseek-ai`.
+
+## Инструменты
+
+| Инструмент | Назначение |
+|---|---|
+| `docx_read(file_path, format?, max_chars?)` | Извлекает тело документа как Markdown (по умолчанию) или структурированные JSON-блоки плюс `docProps`. Испускает `fs/observed`. |
+| `docx_create(file_path, markdown, title?, author?)` | Генерирует новый `.docx` из Markdown. Защищён `createIfAbsent`: существующий файл никогда не перезаписывается вслепую. |
+| `docx_edit(file_path, markdown)` | Читает текущий документ (проверяя, что это docx), сохраняет `docProps`, перегенерирует тело из полного Markdown и записывает обратно с защитой версии (`DOCX_STALE` при конкурентном изменении). |
+
+Все три инструмента разрешают относительные пути относительно рабочей директории сессии вызывающего агента, перед изменением запускают водопад `fs/write-intent` (плагин политики наблюдения может предоставить свой intent) и фиксируют `fs/observed` по завершении — поэтому ограждение песочницы, поля эскалации и политика «читать перед записью» применяются к мутациям docx точно так же, как к `write`/`edit`.
+
+## Конфигурация
+
+| Поле | По умолчанию | Значение |
+|---|---|---|
+| `maxDocxBytes` | 64 MiB | Включительный байтовый лимит на весь файл `.docx` (чтение + распаковка ZIP). |
+| `maxMarkdownChars` | 1 000 000 | Включительный лимит символов на входной Markdown для create/edit. |
+| `maxReadChars` | 200 000 | Включительный лимит символов на Markdown, возвращаемый `docx_read`. |
+
+## Бинарные fs-провайдеры
+
+Строка `fs-sandbox` базового бандла продолжает предоставлять `ctx.fs` **без изменений**. Бандл добавляет рядом docx-инструменты и один из бинарных провайдеров, который регистрирует бинарный примитив `writeBytes` как **отдельный сервис `fsBinary`** — файловая система хоста никогда не заменяется, поэтому этот плагин не может сломать запуск harness; в худшем случае без провайдера изменяющие инструменты сообщают `DOCX_HOST_FS_UNSUPPORTED`:
+
+- **`dsh-tool-docx/fs-binary-sandbox-plugin`** (монтируется бандлом; рекомендуется для песочных хостов) — регистрирует `fsBinary.writeBytes`, ограждённый **тем же по-вызовным политическим забором**, что и каждая мутация песочницы: containment `workspace-write`, отказ в `read-only`, пропуск в `danger-full-access`, `FS_SANDBOX_DENIED` при отказе (на уровне инструмента отображается в `DOCX_SANDBOX_DENIED`).
+- **`dsh-tool-docx/fs-binary-local-plugin`** — регистрирует `fsBinary.writeBytes` **без забора**, для минимальных окружений (тесты, headless-скрипты) или там, где хост уже ограждает поверх провайдера. Чтобы смонтировать его вместо песочного, переопределите строку бандла в своём `cordis.patch.yml` профиля:
+
+  ```yaml
+  - id: fs-binary-sandbox
+    disabled: true
+  - insert:
+      - id: fs-binary-local
+        name: dsh-tool-docx/fs-binary-local-plugin
+  ```
+
+Оба используют тот же поток probe → intent-охрана (`createIfAbsent` / `replaceIfVersion`) → атомарная публикация, что и в seam harness: приватный owner-only staging-каталог, fsync, затем атомарная публикация (для `createIfAbsent` — hard-link без замены), с сериализацией по таргету. Первая версия опускает Win32 DACL-церемонию harness — заменённый файл наследует owner-only ACL временного файла.
+
+Для хостов, которые намеренно хотят смонтировать полный бэкенд **как `ctx.fs`** (заменив `fs-sandbox`), пакет также поставляет классы-провайдеры `dsh-tool-docx/fs-binary-sandbox` и `dsh-tool-docx/fs-binary-local`; рецепт замены строки по-прежнему применим:
+
+```yaml
+- id: fs-sandbox
+  disabled: true
+- insert:
+    - id: fs-binary-sandbox
+      name: dsh-tool-docx/fs-binary-sandbox
+    - id: tool-docx
+      name: dsh-tool-docx
+```
+
+## Заметки по дизайну
+
+- **Извлечение** (`src/docx/extract.ts`) обходит `word/document.xml` с помощью `fast-xml-parser`: заголовки (`Heading1`–`Heading6`, `Title`), run-ы жирный/курсив/зачёркнутый, вложенные списки через `word/numbering.xml` (маркированный и нумерованный), таблицы с разделителями-пайпами (объединённые ячейки — приблизительно), внешние гиперссылки через `word/_rels/document.xml.rels` и встроенные изображения как считаемые плейсхолдеры. Неподдерживаемые конструкции деградируют до предупреждений, но никогда до ошибок.
+- **Генерация** (`src/docx/generate.ts`) рендерит блочную модель библиотекой `docx`: ATX-заголовки, стилизованные строчные run-ы, маркированная/нумерованная нумерация 9 уровней, таблицы с пайпами и внешние гиперссылки `[text](url)`. `parseMarkdown` (src/markdown.ts) принимает то подмножество, которое выдаёт экстрактор, поэтому циклы «прочитать → изменить → записать» стабильны.
+- **Лимиты применяются на стыке (seam), а не в инструменте** — байтовый лимит всего файла уходит в `ctx.fs.readBytes` (`FS_TOO_LARGE` отображается в `DOCX_TOO_LARGE`), а ZIP-ридер применяет тот же лимит к общему несжатому объёму, поэтому сжатая бомба не может распаковаться без ограничений.
+- **Паритет песочницы** — `src/sandbox.ts` повторяет API эскалации `dsh-tool-fs` (`sandbox_permissions`/`justification` анонсируются только под ограничивающим бэкендом, отображение маркеров отказа); извлечение общего контроллера — отложенная работа (см. ниже).
+- **Контракт файловой системы хоста** — `src/fs-binary.ts` объявляет бинарный контракт, нужный инструментам, и разрешает writer во время вызова: сервис `fsBinary`, когда он смонтирован, иначе `ctx.fs` хоста, нативно предоставляющий `writeBytes`. Без какого-либо бинарного writer'а он выбрасывает `DOCX_HOST_FS_UNSUPPORTED` с указанием исправления вместо загадочного `fs.writeBytes is not a function`; для `docx_read` нужен только опубликованный `ctx.fs.readBytes`.
+
+## Опыт модели
+
+### Системный промпт
+
+#### Что видит модель
+
+Раздел `tool:docx-read` ниже регистрируется один раз при применении плагина:
+
+##### Раздел-руководство по docx
+
+```markdown
+MS Word .docx files are binary (ZIP+XML) and the read tool cannot read them. Use docx_read to extract a document as Markdown (default) or structured JSON blocks, docx_create to generate a new .docx from Markdown, and docx_edit to replace a document's content from Markdown while preserving its title/author/created properties. Legacy .doc is not supported — convert it to .docx first.
+```
+
+#### Влияние на токены
+
+Фиксированная стоимость руководства на каждый запрос, пока плагин подключён; раздел не зависит от ограничений инструментов по scope.
+
+#### Влияние на KV-кэш
+
+Префиксно-стабилен, пока текст руководства не меняется. Жизненный цикл плагина или изменение текста могут инвалидировать переиспользование с первого изменённого раздела промпта.
+
+### Схемы инструментов
+
+#### Что видит модель
+
+Сгенерированные схемы `docx_read`, `docx_create` и `docx_edit` — параметры и канонические результаты в сводке таблицы [Инструменты](#инструменты). Байтовые/символьные лимиты — это настройки развёртывания, а не аргументы модели; поля эскалации появляются только под ограничивающим файловым бэкендом.
+
+#### Влияние на токены
+
+Фиксированная стоимость схем на каждый запрос для каждого подключённого инструмента; отключение в конфигурации удаляет схемы и руководство вместе, а ограничение по scope удаляет только схему.
+
+#### Влияние на KV-кэш
+
+Префиксно-стабилен, пока определения и видимость не меняются. Включение в конфигурации, жизненный цикл плагина или ограничения по scope могут инвалидировать переиспользование с первого изменённого токена схемы.
+
+### Результат чтения
+
+#### Что видит модель
+
+Успешный `docx_read` рендерит извлечённый Markdown (или форматированные JSON-блоки). При усечении добавляется `\n… (truncated)`; ошибки — типизированные сообщения, например `file not found: <path>`, `the document is encrypted (password-protected); decryption is not supported` или подсказка для legacy `legacy .doc format is not supported — convert the document to .docx first`.
+
+#### Влияние на токены
+
+Зависящие от данных результаты ограничены `maxReadChars` (или `max_chars` из вызова) и пересылаются до компактификации.
+
+#### Влияние на KV-кэш
+
+Только добавление; вновь видимое содержимое следует за переиспользуемым префиксом запроса и не инвалидирует существующие записи KV-кэша.
+
+### Результат создания/редактирования
+
+#### Что видит модель
+
+Успешное создание/редактирование рендерит короткий конверт `<path>`/`<type>docx</type>` с размером в байтах — никогда тело документа. Предупреждения об приближениях (изображения, объединённые ячейки, блоки кода) переносятся в канонический массив `warnings` и рендерятся как обычный текст.
+
+#### Влияние на токены
+
+Только сохранённые аргументы вызова (включая полный Markdown-ввод) и короткий результат добавляют токены; байты сгенерированного пакета никогда не попадают в журнал сессии.
+
+#### Влияние на KV-кэш
+
+Только добавление; вновь видимое содержимое следует за переиспользуемым префиксом запроса и не инвалидирует существующие записи KV-кэша.
+
+### Ошибки аргументов
+
+#### Что видит модель
+
+Пустой `file_path` становится `Error: file_path must be a non-empty string`; markdown сверх лимита ввода становится `Error: markdown exceeds the <n>-character limit`.
+
+#### Влияние на токены
+
+Только неудачный вызов добавляет эти сохранённые токены.
+
+#### Влияние на KV-кэш
+
+Только добавление; вновь видимое содержимое следует за переиспользуемым префиксом запроса и не инвалидирует существующие записи KV-кэша.
+
+## Известные ограничения и отложенная работа
+
+- **Legacy `.doc` (OLE) не поддерживается** — бинарный OLE требует конвертации через LibreOffice или Word COM; инструменты завершаются с `DOCX_LEGACY_DOC` и подсказкой сначала сконвертировать в `.docx`.
+- **Изображения не извлекаются и не встраиваются** — `docx_read` подсчитывает изображения и выводит плейсхолдеры; `docx_create`/`docx_edit` отбрасывают синтаксис изображений с предупреждением. Извлечение байтов изображений и их встраивание при генерации — отложенная работа.
+- **Цикл «прочитать → изменить» перегенерирует документ** — стили, настройки страницы, колонтитулы и разрывы разделов не сохраняются; редактирование пересобирает тело со стилями по умолчанию, сохраняя только title/author/created. Точность вёрстки не является целью цикла.
+- **Объединённые ячейки таблиц — приблизительно** — `gridSpan`/`vMerge` деградируют до обычных ячеек пайп-таблиц с предупреждением; сноски, концевые сноски, текстовые поля и разрывы страниц отбрасываются (с предупреждениями).
+- **Контроллер песочницы дублирует `dsh-tool-fs`** — извлечение общего `FsSandboxController` — отложенная работа; до тех пор две копии должны поддерживаться в синхронизации.
+- **Подмножество Markdown-ввода** — цитаты, горизонтальные линии, вложенные ограждения и изображения не представлены; они деградируют до абзацев с предупреждением (ограждённый код становится абзацами в стиле кода).
+
+## Разработка
+
+```sh
+pnpm install
+pnpm typecheck   # tsc по src/
+pnpm build       # tsc → lib/types + tsdown → lib/index.js, lib/invariant.js
+pnpm test        # vitest: юнит-тесты конвертации + потребительские тесты на фейковой fs
+pnpm pack        # собрать npm-тарбол (files: lib/index.js, lib/invariant.js, lib/types/**/*.d.ts)
+```
+
+Структура:
+
+- `src/docx/` — извлечение ZIP/XML и генерация библиотекой `docx`;
+- `src/tools/` — три регистрации инструментов;
+- `src/fs-binary.ts` — контракт бинарной файловой системы и разрешение writer'а во время вызова (`fsBinary`-сервис или нативный `ctx.fs.writeBytes`);
+- `src/fs-binary-local.ts`, `src/fs-binary-sandbox.ts`, `src/fsio-bytes.ts`, `src/path-contains.ts` — классы бинарных fs-провайдеров, атомарный writer и хелперы containment;
+- `src/fs-binary-sandbox-plugin.ts`, `src/fs-binary-local-plugin.ts` — namespace-плагины, регистрирующие сервис `fsBinary` (монтирование по умолчанию из бандла);
+- `tests/` — тесты циклов конвертации, тесты провайдера и потребительские тесты против опубликованного сервиса `ToolRuntime` (экспортируется с `dsh-tools@0.1.0-rc.7`).
+
+## Отношение к deepseek-harness
+
+Этот плагин — **оригинальный, независимый проект, написанный для DeepSeek Harness**: он подключается к публичным сервисам harness (`tools`, `fs`, `systemPrompt`) и разрабатывается в локальном checkout `deepseek-harness` для тестирования против harness. Он не является копией плагина из общего репозитория `deepseek-harness` и не является его частью; этот репозиторий — канонический канал распространения. Две заметки по реализации:
+
+1. `src/fs-binary.ts` (контракт хоста + разрешение writer'а) — бинарный контракт `readBytes`/`writeBytes` — часть дизайна этого плагина. `readBytes` опубликован в линии релизов `dsh-fs` harness начиная с `0.1.0-rc.7`; `writeBytes` — нет, поэтому [бинарные fs-провайдеры](#бинарные-fs-провайдеры) поставляют его как отдельный сервис `fsBinary`, а не патчат хост;
+2. `tests/` работает против опубликованного сервиса `ToolRuntime` (экспортируется с `dsh-tools@0.1.0-rc.7`), поэтому потребительские тесты проходят через реальный конвейер реестра, а не локальный дублёр.
+
+Плагин полностью разрабатывается и поддерживается в этом репозитории против опубликованных пакетов `@deepseek-ai/*`; checkout harness — лишь среда выполнения для интеграционной проверки и не содержит копии этого плагина.
+
+## Лицензия
+
+MIT © 2026 BroBFG. Части `src/sandbox.ts`, паттерн атомарной записи в `src/fsio-bytes.ts` и логика containment в `src/path-contains.ts` являются производными от [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) (MIT, Copyright (c) 2026 DeepSeek) — см. [LICENSE](LICENSE).