Adeu: нативные «Исправления» для ИИ

LLM говорят на Markdown; юристы говорят на языке «Исправлений» (Track Changes).

Adeu — это сервер протокола контекста модели (MCP) и Python SDK, который выступает в роли «Виртуального DOM» для Microsoft Word. Он предоставляет двухуровневый слой абстракции, позволяющий ИИ-агентам свободно редактировать текст документа, не разрушая базовое форматирование или сложный XML-код DOCX.

В то время как стандартные библиотеки, такие как python-docx, отлично подходят для создания документов с нуля, они не справляются с неразрушающим редактированием. Adeu решает эту проблему, преобразуя файлы .docx в эффективное с точки зрения токенов представление Markdown. Это освобождает ИИ-агентов, позволяя им сосредоточиться исключительно на семантике документа, а не тратить токены на борьбу с OpenXML.

Adeu действует как интеллектуальный прокси-сервер, обрабатывая правки ИИ как безопасные атомарные транзакции:

1. Извлечение: Переводит документ (с диска или из открытого Word) в понятную для LLM разметку CriticMarkup с семантическим приложением, содержащим определения терминов, перекрестные ссылки и вероятные опечатки. Агент начинает работу с семантической структурой, а не с «сырыми» данными.

2. Проверка: Выступает в качестве строгого фильтра безопасности. Он защищает целостность документа, автоматически блокируя неоднозначные текстовые совпадения или недопустимые структурные изменения до того, как они будут применены к файлу.

3. Фиксация: Преобразует текстовые правки ИИ в нативные «Исправления» (Track Changes) Word. Adeu берет на себя сложную работу с XML, гарантируя, что существующие макеты, шрифты и примечания на полях будут полностью сохранены.

Поддерживается Adeu.

Установка

Предварительное требование: Adeu использует uv для быстрого и изолированного выполнения. Самый простой способ установки — через pip:

pip install uv

macOS

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Интеграция с Claude Desktop

Чтобы мгновенно добавить Adeu в Claude Desktop, выполните:

uvx adeu init

Проверка работоспособности

После перезапуска Claude Desktop вы можете подтвердить подключение Adeu, отправив следующее сообщение напрямую в Claude:

"Can you read a DOCX file using the Adeu tool?"

Если все настроено правильно, Claude подтвердит, что у него есть доступ к инструментам Adeu, и опишет свои возможности. Если он не упоминает Adeu или сообщает об отсутствии инструментов для работы с файлами, еще раз проверьте, перезапустили ли вы Claude Desktop после выполнения uvx adeu init.

Поскольку Adeu требует Python 3.12+, uvx автоматически загрузит нужную версию Python и запустит сервер:

{
  "mcpServers": {
    "adeu": {
      "command": "uvx",
      "args": ["--from", "adeu", "adeu-server"]
    }
  }
}

Рабочие процессы

1. Для агентов (Claude / MCP)

Adeu работает как сервер протокола контекста модели (MCP). Он предоставляет агентам специальные инструменты для безопасного чтения, проверки и редактирования документов.

Интерфейс MCP Apps: Инструмент read_docx поддерживает новейший протокол MCP Apps UI. Когда агент читает документ, Adeu динамически отображает пользовательский интерактивный интерфейс Markdown прямо в окне чата Claude, позволяя вам визуально просматривать извлеченный текст и форматирование вместе с рассуждениями ИИ!

Рекомендуемый промпт для агента: Хотя инструменты Adeu автоматически описывают свои схемы для LLM, вы можете гарантировать наилучшие результаты, добавив этот контекст в Project Instructions (инструкции проекта) Claude или в системный промпт вашего агента:

Роль: Специалист по документам Инструменты:

• read_docx(clean_view=True): Чтение финальной «чистой» версии текста для понимания контекста.

• process_document_batch: Режим фиксации и согласования. Применение единого списка изменений. Используйте type: "modify" для конкретных правок типа «поиск и замена», и type: "accept", "reject" или "reply" для управления существующими «Исправлениями» и комментариями по ID.

• sanitize_docx: Очистка перед отправкой. Удаление опасных метаданных, имен авторов и внутренних идентификаторов отслеживания перед отправкой. Может сохранять существующую разметку (keep_markup=True) или создавать чистый отчет об изменениях относительно базовой версии.

Интеграция с MS Word в реальном времени

Если вы работаете в Windows с установленным Microsoft Word, Adeu может выступать в роли второго пилота, редактируя активный документ прямо у вас на глазах.

• read_active_word_document: Извлекает текст, «Исправления» и комментарии напрямую из открытого окна Word.

• process_active_word_batch: Преобразует правки LLM в нативные макросы COM, наблюдая за тем, как Word автоматически печатает, удаляет и добавляет комментарии на холсте.

2. Для разработчиков (Python SDK)

Если вы создаете юридическое технологическое приложение или автоматизированный конвейер, используйте RedlineEngine напрямую. Он берет на себя всю тяжелую работу по манипуляции XML.

from adeu import RedlineEngine, ModifyText
from io import BytesIO

# 1. Load the contract
with open("MSA.docx", "rb") as f:
    stream = BytesIO(f.read())

# 2. Define the edit (e.g., from an LLM response)
# Adeu uses fuzzy matching to locate the target text, even if whitespace varies.
edit = ModifyText(
    target_text="State of New York",
    new_text="State of Delaware",
    comment="Standardizing governing law."
)

# 3. Apply changes
engine = RedlineEngine(stream, author="AI Copilot")
engine.apply_edits([edit])

# 4. Save the result
with open("MSA_Redlined.docx", "wb") as f:
    f.write(engine.save_to_stream().getvalue())

3. Интерфейс командной строки (CLI)

Быстро проверяйте документы или применяйте пакеты правок из терминала.

# Extract clean text for RAG or prompting
adeu extract contract.docx -o contract.md

# Generate a visual diff between two versions
adeu diff v1.docx v2.docx

# Preview what an edit list (JSON) would look like
adeu markup contract.docx edits.json --output preview.md

# Apply edits to the DOCX
adeu apply contract.docx edits.json --author "Review Bot"

# Scrub author metadata and internal trackers, but keep the visual redlines for the counterparty
adeu sanitize redline.docx -o clean.docx --keep-markup --author "My Firm" --report

Основные возможности

Безопасность форматирования

Adeu не «переписывает» документ. Он исправляет его.

• Изображения и макеты: Не затрагиваются.

• Нумерация и заголовки: Сохраняются.

• Таблицы и списки: Сложные объединения ячеек и многоуровневая юридическая нумерация защищены.

• Сложный XML: Изменяются только текстовые фрагменты, на которые направлена правка.

Представление CriticMarkup

Промежуточные представления важны. Adeu использует CriticMarkup для визуализации изменений.

Семантическое приложение

Контракты полны «мин», которые LLM может пропустить при первом проходе: непоследовательно используемые термины, битые перекрестные ссылки и опечатки в документах, распознанных через OCR. Adeu предварительно вычисляет их при извлечении и передает агенту структурированное приложение вместе с текстом.

Интеллектуальное сопоставление

Документы Word часто бывают «грязными». Слово «Contract» может быть разбито на XML-фрагменты, такие как ["Con", "tract"], из-за проверки орфографии или истории форматирования.

• Объединение фрагментов: Adeu нормализует эти разбиения, чтобы ИИ видел слово «Contract» целиком.

• Нечеткий поиск: Обрабатывает незначительные расхождения в пробелах между памятью LLM и фактическим содержимым документа.

Очистка метаданных

Существующие средства очистки метаданных часто ломают «Исправления» или удаляют данные без уведомления. Команда sanitize в Adeu хирургически удаляет опасные трекеры (rsid, шаблоны, внутренние пути, временные метки) и «осиротевший» контент, сохраняя при этом валидные «Исправления». Важно, что она создает прозрачный отчет об аудите, доказывающий, что именно было удалено и что будет видно получателю.

Adeu Cloud

По умолчанию основной движок Adeu и локальные инструменты для работы с файлами полностью открыты и работают исключительно на вашем компьютере. Adeu никогда не отправляет ваши локальные документы на сервер (хотя выбранный вами провайдер LLM будет обрабатывать текст, который читает агент).

Тем не менее, вы можете явно подключить свой MCP-сервер к Adeu Cloud, чтобы получить доступ к:

• Сквозным рабочим процессам (Email): Поскольку контракты передаются по электронной почте, Adeu Cloud позволяет агентам безопасно получать цепочки писем, извлекать вложения DOCX от контрагентов для проверки и составлять ответы с прикрепленными очищенными правками.

• Расширенной проверке документов: Выполнение сложных задач семантической проверки нескольких документов в асинхронном режиме. Безопасно направляя эти огромные контексты в Adeu Cloud для обработки, вы предотвращаете исчерпание контекстного окна вашего локального ИИ-агента или достижение лимитов запросов.

Узнайте больше об Adeu Cloud.

Участие в разработке

Мы приветствуем вклад сообщества! Будь то исправление ошибок, добавление возможностей или улучшение документации, пожалуйста, ознакомьтесь с нашим Руководством по участию для получения инструкций по настройке локальной среды uv, запуску тестов и пониманию строгих правил безопасности XML в проекте.

Лицензия

Лицензия MIT. Программное обеспечение с открытым исходным кодом, бесплатное для использования в коммерческих целях.