# dsh-tool-docx — Дорожная карта

[English](ROADMAP.md) | [中文](ROADMAP.zh.md) | [Русский](ROADMAP.ru.md)

План развития плагина, упорядоченный по ценности и трудозатратам. Каждый
пункт называет конкретный объём работ, чтобы его мог взять любой
контрибьютор без дизайн-решений. Статусы ведутся в issues репозитория; этот
файл — пункт назначения, а не трекер.

## Ближняя перспектива — фундамент

### 1. Публикация в npm

- Объём: публикация под свободным именем `dsh-tool-docx`; настройка
  `publishConfig`/публикации в CI; в README — `dsh plugin --profile web add
  dsh-tool-docx` (без git-spec).
- Ценность: установка в одно слово, настоящие semver-релизы, обновление через
  `dsh plugin … update`, обнаружимость в экосистеме.
- Трудозатраты: небольшие.

### 2. Следить за upstream `fs.writeBytes`

- Объём: следить за релизами `@deepseek-ai/dsh-fs` на предмет `writeBytes` /
  `FsBytesWriteOutcome`; при публикации — предпочитать нативный
  `ctx.fs.writeBytes`, а провайдеры `fsBinary` (`fs-binary-sandbox-plugin` /
  `fs-binary-local-plugin`) оставить fallback'ом для старых хостов.
- Ценность: схлопывание самописного seam'а; меньше собственного кода; примитив
  принадлежит harness.
- Трудозатраты: небольшие (в основном наблюдение + одна правка резолвера).

### 3. Общий `FsSandboxController`

- Объём: сейчас `src/sandbox.ts` повторяет API эскалации `dsh-tool-fs`.
  Вынести общий контроллер в собственный пакет (или предложить upstream как
  `@deepseek-ai/dsh-fs-sandbox-controller`), чтобы две копии не расходились.
- Ценность: убирает задокументированное ограничение; единый владелец
  контракта эскалации.
- Трудозатраты: небольшие–средние.

### 4. Гейт детерминизма сборки в CI

- Объём: убедиться, что hashed-имена чанков `lib/*.js` воспроизводятся в CI
  (гейт `verify:lib` уже есть; подтвердить стабильность в разных окружениях и
  починить, если именование чанков rolldown зависит от путей).
- Ценность: надёжные релизы; установленный пакет всегда соответствует
  закоммиченному `lib/`.
- Трудозатраты: небольшие.

## Средняя перспектива — формат docx всерьёз

### 5. Изображения через сервис `attachments`

- Объём: извлекать встроенные изображения (`word/media/*`) в `docx_read`;
  внедрять изображения в `docx_create`/`docx_edit`. Хранить durable-байты через
  сервис `attachments` harness (`dsh-attachment-local`), чтобы картинки
  переживали сессии и перевстраивались при генерации.
- Ценность: самый востребованный пробел; завершает цикл
  читать→править→писать для документов с рисунками.
- Трудозатраты: средние.

### 6. Хирургический `docx_edit`

- Объём: править `word/document.xml` на месте вместо перегенерации всего
  пакета, сохраняя стили, колонтитулы, параметры страницы и разбивку на
  разделы. Текущий путь перегенерации оставить fallback'ом для сложных
  переписываний.
- Ценность: round-trip перестаёт быть потерянным — ключевой пробел качества
  сегодня.
- Трудозатраты: средние–большие (XML-хирургия + тщательные round-trip-тесты).

### 7. Таблицы, сноски, разрывы страниц

- Объём: полная поддержка объединённых ячеек (`gridSpan`/`vMerge`) в обе
  стороны, сноски/концевые сноски, разрывы страниц — вместо сегодняшних
  приближений.
- Ценность: профессиональные документы проходят round-trip без потерь.
- Трудозатраты: средние (можно разбить по фичам).

### 8. Шире подмножество Markdown

- Объём: цитаты, горизонтальные линии, вложенные фенсы кода, изображения
  (зависит от пункта 5).
- Ценность: убирает предупреждения о деградации; согласуется со стороной
  извлечения.
- Трудозатраты: небольшие–средние.

## Дальняя перспектива — семейство документов

### 9. Конвертация legacy `.doc`

- Объём: опциональный конвертер через LibreOffice headless или Word COM на
  Windows, за явным требованием (установленный LibreOffice/Word); `docx_read`
  для `.doc` сможет конвертировать прозрачно вместо `DOCX_LEGACY_DOC`.
- Ценность: закрывает последний пробел форматов для Word-документов.
- Трудозатраты: средние.

### 10. Соседние инструменты — `dsh-tool-xlsx`, `dsh-tool-pptx`

- Объём: переиспользовать архитектуру (ограниченные бинарные чтения через
  службу `fsBinary`, блочная модель, официальная установка `dsh plugin`,
  тесты против опубликованных пакетов) для таблиц и презентаций. Сначала Excel
  (выше спрос); PowerPoint — вторым.
- Ценность: плагин превращается в офисный набор для harness.
- Трудозатраты: большие на каждый формат.

### 11. Извлечение текста из PDF

- Объём: чтение-only (без записи); ограниченное, как docx-ридеры.
- Ценность: покрывает распространённый формат ссылок.
- Трудозатраты: средние; приоритет ниже офисных форматов.

### 12. Самостоятельная библиотека-конвертер

- Объём: вынести ядро `docx ↔ Markdown` в npm-пакет без зависимостей от
  harness (`docx-markdown` или подобное), плагин — тонкая обёртка.
- Ценность: применимо вне DSH; независимый CI; шире база контрибьюторов.
- Трудозатраты: средние (в основном упаковка + доки).

### 13. Шаблон экосистемы

- Объём: оформить плагин как эталон «как сделать dsh-tool-*» (официальная
  установка, отдельная служба вместо замены хоста, тесты против опубликованных
  пакетов) — документация или навык.
- Ценность: снижает порог для следующего плагина; стандартизирует экосистему.
- Трудозатраты: небольшие.

## Честные ограничения

- Высокоточный round-trip (стили, колонтитулы, разделы) — это примерно
  половина текущего объёма плагина в новом коде; хирургический edit (пункт 6)
  — правильный первый шаг, а не writer с нуля.
- Шифрованные (запароленные) docx требуют зависимости дешифровки
  OLE/CryptoAPI — отложено, низкий приоритет.
- Ограничение кодов ошибок под tsx-запуском из исходников (см. «Известные
  ограничения» в README) — исправление на стороне harness (канонизация
  junction под tsx). Плагин документирует его и ведёт issue в upstream;
  built-bin режим не затронут.

## Рекомендуемый порядок

1. Публикация в npm + слежение за upstream `writeBytes` — малый труд, большой
   эффект.
2. Изображения через `attachments` — средний труд, высокий спрос.
3. Хирургический `docx_edit` — средний–большой труд, ключевой выигрыш в
   качестве.
4. `dsh-tool-xlsx` — следующий член семейства.