# dsh-r7-office (Плагин Р7-Офис для DeepSeek Harness и MCP-сервер)

[![CI](https://github.com/blazar-source/dsh-r7-office/actions/workflows/ci.yml/badge.svg)](https://github.com/blazar-source/dsh-r7-office/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org/)

**Плагин обработки документов Р7-Офис и сервер Model Context Protocol (MCP) для DeepSeek Harness.**

Позволяет ИИ-агенту анализировать, читать, создавать, форматировать,
редактировать и конвертировать документы `DOCX`, `XLSX`, `PPTX` и `PDF` —
средствами стандартного OOXML и уже установленного у вас конвертера Р7, без
эмуляции мыши и клавиатуры.

> ## ⚠️ Неофициальный community-проект
>
> Это **независимый проект, поддерживаемый сообществом**. Он **не связан с
> АО «Р7» (Р7-Офис) и DeepSeek, не одобрен, не спонсируется и не
> поддерживается ими**, и не является официальным продуктом Р7-Офис или
> DeepSeek.
>
> *Р7-Офис* и *R7-Office* — товарные знаки их правообладателей; они
> упоминаются здесь только для описания совместимости.
>
> В репозитории **нет кода, бинарников и иных ресурсов Р7-Офис**. Плагин
> находит уже установленную у пользователя копию Р7-Офис и работает с ней
> локально. Установить и лицензировать Р7-Офис необходимо самостоятельно.
>
> ---

**English documentation:** [README.md](README.md)

---

## Возможности

- **Сохранение форматирования** — замена и правка текста сохраняют исходные
  XML-стили, шрифты, цвета и иерархию нумерации. Нетронутые части документа
  сохраняются побайтово.
- **Все четыре формата** — DOCX (заголовки, параграфы, списки, таблицы,
  разрывы страниц), XLSX (листы, диапазоны, значения, формулы), PPTX (слайды,
  заголовки, текстовые блоки), PDF (конвертация локальным движком Р7 `x2t`).
- **Встроенная проверка** — `r7_validate` контролирует целостность пакета до и
  после изменений.
- **Два режима работы** — нативный плагин DeepSeek Harness либо автономный
  MCP-сервер по stdio для любого MCP-клиента.
- **Мост к открытому документу** — опционально управляет документом, который
  пользователь **открыл** в Р7-Офис Desktop, через локальный WebSocket.

## Архитектура

```text
DeepSeek Harness ──► плагин dsh-r7-office ──┐
                                            ├──► DOCX / XLSX / PPTX / PDF
Любой MCP-клиент ──► MCP-сервер (stdio) ────┤
                                            │
Р7-Офис Desktop ◄── desktop bridge ◄────────┘
```

Подробности — в [docs/architecture.md](docs/architecture.md), решения — в
[docs/decisions/](docs/decisions/).

---

## Требования

| | |
|---|---|
| Node.js | **>= 20.0.0** для работы плагина и MCP-сервера. **>= 22.0.0** для полного набора тестов (клиенты моста и CDP используют глобальный `WebSocket`, который появился только в Node 22). |
| Runtime-зависимости | **отсутствуют** — у плагина их нет |
| Р7-Офис Desktop | **опционально.** Нужен для `r7_convert` (в PDF/HTML), для разбора экзотических документов и для моста к Desktop. Без него работают все чисто-OOXML инструменты. |
| Платформа | Windows, Linux, macOS. Автоопределение Р7 покрывает стандартные каталоги всех трёх систем; живой мост к Desktop проверен только на Windows (см. [ограничения](#известные-ограничения)). |

---

## Установка «с нуля»

Шаги предполагают пустой каталог и установленный Node.js 20+.

```bash
# 1. Получить код
git clone https://github.com/blazar-source/dsh-r7-office.git
cd dsh-r7-office

# 2. Установить опциональные dev-зависимости (только для тестов: MCP SDK клиента)
npm install

# 3. Проверить окружение — Р7-Офис на этом шаге не требуется
npm test
```

`npm test` запускает 155 тестов: модульные, регрессионные (round-trip OOXML),
файловые end-to-end, тесты политики безопасности и smoke-набор внешнего
MCP-клиента. Тесты, которым нужна установка Р7-Офис, **сами пропускаются** с
понятным сообщением, поэтому на чистой машине прогон зелёный.

Далее проверьте ту интеграцию, которая вам нужна:

```bash
# Файловый конвейер Р7 (создание → правка → проверка → PDF). Пропустится без Р7.
npm run test:live

# Активация плагина в DeepSeek Harness: поднимается свежий Harness и
# проверяется, что 18 инструментов r7_* дошли до реестра инструментов.
npm run test:harness -- --profile web
```

### Как плагин DeepSeek Harness

Установите каталог пакета как бандл:

```bash
# в UI DeepSeek Harness: plugin_manager → install_bundle
# target: /абсолютный/путь/к/dsh-r7-office
```

либо эквивалентно из CLI для вашего профиля:

```bash
dsh plugin --profile <профиль> add /абсолютный/путь/к/dsh-r7-office
```

Проверка активации — свежий запуск Harness печатает:

```text
[r7-office] зарегистрировано инструментов: 27 (r7_inspect, r7_read, ...); desktop bridge port=7888, developerMode=false
```

> **Важно.** Добавляйте строку **либо** через `install_bundle`, **либо** вручную
> в `cordis.patch.yml` профиля — но не оба способа сразу. Две записи с одним
> `r7-office` приводят к тому, что строка не активируется.

Плагин также добавляет в системный промпт агента краткий раздел с описанием
инструментов и порядка работы `inspect → read → edit → validate → convert`.

### Как автономный MCP-сервер

MCP-сервер общается построчным JSON-RPC 2.0 по stdio.

```json
{
  "mcpServers": {
    "r7-office": {
      "command": "node",
      "args": ["/абсолютный/путь/к/dsh-r7-office/src/mcp/cli.js"]
    }
  }
}
```

Поместите это в конфигурацию клиента (например, `claude_desktop_config.json`
или `.cursor/mcp.json`). Подойдёт любой stdio MCP-клиент; совместимость
проверяется в `npm test` с официальным SDK `@modelcontextprotocol/client`.

Можно запустить и вручную:

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/mcp/cli.js
```

---

## Инструменты

| Инструмент | Назначение |
|---|---|
| `r7_inspect` | Структура документа: заголовки, параграфы, таблицы, листы, слайды, метаданные |
| `r7_read` | Структурированный текст, Markdown-представление или диапазоны ячеек |
| `r7_create` | Новые DOCX / XLSX / PPTX. Без `overwrite: true` существующий файл не перезаписывается; для XLSX учитываются все листы из `sheets[]` и их имена |
| `r7_edit` | Замена, смена стиля или удаление параграфа по индексу |
| `r7_replace` | Поиск и замена текста с сохранением форматирования |
| `r7_insert` | Вставка параграфов, заголовков, списков, разрывов страниц |
| `r7_table` | Создание, чтение и правка таблиц и ячеек: объединение, границы, заливка, ширины колонок |
| `r7_docx_formatting` | Чтение нормализованного оформления абзацев, фрагментов и ячеек: стиль, шрифт, размер, цвет, выравнивание, отступы, интервалы, списки |
| `r7_docx_sections` | Размер страницы, ориентация, поля, колонки, разрывы страниц и секций |
| `r7_docx_header_footer` | Чтение и правка колонтитулов; поля номеров страниц сохраняются |
| `r7_docx_image` | Вставка PNG/JPEG/GIF с указанием размера и сохранением пропорций |
| `r7_docx_hyperlink` | Чтение, вставка, переименование и удаление гиперссылок |
| `r7_sheet_read` | Чтение значений, формул или нормализованного оформления листа/диапазона (например `A1:D10`) |
| `r7_sheet_write` | Запись ячеек или матрицы — по имени листа или индексу; даты хранятся как настоящие serial-числа |
| `r7_sheet_format` | Оформление ячейки или диапазона: шрифт, заливка, границы, выравнивание, перенос, числовые форматы (integer, decimal, currency, percent, date, datetime, custom), объединение, ширина колонок, высота строк |
| `r7_sheet_add` | Добавление листа в существующую книгу; остальные листы не изменяются |
| `r7_sheet_formula` | Вставка или обновление формулы |
| `r7_slide_read` | Нормализованная структура слайда: id, тип, геометрия (x/y/ширина/высота/поворот/z-order), текст, шрифт, заливка, обводка, выравнивание, абзацы |
| `r7_slide_create` | Создание презентации или **добавление** слайда на существующем layout без изменения уже имеющихся слайдов |
| `r7_slide_format` | Оформление и перемещение объекта на слайде: шрифт, геометрия, заливка, границы, списки, интервалы, текст |
| `r7_slide_edit` | Дублирование, перемещение, переупорядочивание и удаление слайдов |
| `r7_slide_object` | Добавление фигур, текстовых блоков и картинок; удаление и замена изображения |
| `r7_convert` | Конвертация движком Р7 `x2t` (PDF, HTML, TXT, DOCX, XLSX, PPTX). Для PDF берётся список шрифтов, который создаёт сама Р7, чинится битый счётчик ToUnicode, и конвертер **отказывается отдавать PDF без извлекаемого текста** вместо молчаливой выдачи пустого файла. XLSX по умолчанию экспортирует все листы (`allSheets`) |
| `r7_validate` | Проверка целостности пакета и XML |
| `r7_pdf_inspect` | Показывает, есть ли в PDF настоящий текст или он сделан без шрифтов: встроен ли каждый шрифт, сколько отображений ToUnicode и кириллицы, число глифов, пустые заливки и вердикт `text` / `outlined` / `mixed`. `repair: true` чинит битый счётчик ToUnicode на месте |
| `r7_desktop_status` | Состояние моста и действующий режим безопасности |
| `r7_desktop_selection` | Чтение или замена выделения в открытом редакторе |
| `r7_desktop_exec` | Безопасная команда редактора либо произвольный DocScript в developer mode |

---

## Типовой сценарий

> «Возьми `Отчет.docx`, обнови раздел 3, сохрани оформление, добавь итоговую
> таблицу и сохрани в PDF».

```text
r7_inspect → r7_read → r7_replace (сохраняет оформление) → r7_table
           → r7_validate → r7_convert
```

Запуск примера:

```bash
node examples/report-scenario.js
```

Использование как библиотеки:

```javascript
import { DocxEngine, R7Adapter } from 'dsh-r7-office/r7'

const docx = new DocxEngine()
const adapter = new R7Adapter()

await docx.replaceText('Отчет.docx', 'черновой текст', 'утверждённый текст', {
  outputPath: 'Отчет_v2.docx'   // исходный файл по умолчанию не перезаписывается
})

await docx.table('Отчет_v2.docx', {
  action: 'create',
  rows: [['Направление', 'Срок', 'Ответственный'], ['Внедрение Р7', 'Q2', 'ИТ']]
})

console.log((await docx.validate('Отчет_v2.docx')).valid)

await adapter.convert('Отчет_v2.docx', 'Отчет_v2.pdf')
```

---

## Безопасность

`r7_desktop_exec` умеет выполнять код в открытом редакторе пользователя,
поэтому произвольный DocScript **по умолчанию отключён**: в production
работает только фиксированный allowlist безопасных команд. Включайте
произвольный код только осознанно:

```yaml
- id: r7-office
  name: 'dsh-r7-office'
  config:
    developerMode: true        # либо export DSH_R7_DEVELOPER_MODE=1
```

`r7_desktop_status` всегда показывает действующий режим. Мост слушает только
`127.0.0.1`.

Полная модель угроз и порядок сообщения об уязвимостях — в
[SECURITY.md](SECURITY.md).

---

## Известные ограничения

- **Живой мост к Desktop: проверено на Windows.** Сам плагин моста
  кроссплатформенный, но автотест управляет Р7-Офис Desktop через протокол
  CEF DevTools и проверен только на Windows-сборке (`Editors-2026.3.1`). На
  других платформах работать должно, но не проверялось.
- **Для PDF нужен Р7.** `r7_convert` использует конвертер `x2t` из локальной
  установки Р7. Остальные инструменты работают и без неё.
- **Покрытие форматов.** Чтение и правка покрывают перечисленную выше
  типовую поверхность OOXML. Диаграммы, внедрённые объекты, SmartArt и
  режим правок сохраняются, но не редактируются этими инструментами.
- **Нет одновременного редактирования.** Файловые инструменты работают с
  документом «на диске». Для открытого пользователем документа используйте
  мост к Desktop: файловые инструменты предполагают, что файл не
  заблокирован другим процессом.

---

## Разработка

```bash
npm test              # всё
npm run test:unit
npm run test:integration
npm run test:e2e
npm run test:live     # требуется установленный Р7-Офис
npm run test:harness  # поднимает свежий DeepSeek Harness
npm run inspect:r7    # CDP-зонд запущенного Р7 Desktop
```

См. [docs/development.md](docs/development.md) и
[docs/roadmap.md](docs/roadmap.md).

---

## Лицензия

MIT — см. [LICENSE](LICENSE).

Р7-Офис — проприетарное ПО, принадлежащее АО «Р7». Проект не распространяет
его компоненты.