Руководство по предпросмотру Markdown

Обзор

Блок markdown-preview отображает markdown-файл во встроенном виде в сообщениях чата — показывает markdown после разбора с тем же рендерером, что использует чат, с кнопкой развертывания для более высокого содержимого и панелью вкладок для спецификаций с несколькими элементами.

Ключевой принцип: Как и в pdf-preview и image-preview, файл уже находится на диске — достаточно указать абсолютный путь. Шаг извлечения не нужен.

Когда использовать

Используйте markdown-preview, когда:

• вы только что создали .md-файл — покажите результат агента в отрендеренном виде, а не как сырой блок кода;
• пользователь ссылается на markdown-файл — README, спецификацию, заметки, план;
• вы хотите отобразить отрендеренный текст с таблицами, блоками кода, ссылками, заголовками и т. д.

Не используйте markdown-preview, когда:

• содержимое — HTML — используйте html-preview;
• содержимое — структурированные данные — используйте datatable / spreadsheet;
• содержимое — PDF — используйте pdf-preview;
• пользователь хочет изменить файл — используйте стандартные инструменты Read/Edit/Write агента.

Базовое использование

Один элемент

{
  "src": "/absolute/path/to/file.md",
  "title": "Spec draft"
}

Несколько элементов (вкладки)

Если у вас несколько связанных markdown-файлов (например, версии спецификации, разделы README), используйте массив items. В заголовке появляется панель вкладок для переключения между элементами.

{
  "title": "Spec drafts",
  "items": [
    { "src": "/path/to/v1.md", "label": "v1" },
    { "src": "/path/to/v2.md", "label": "v2" },
    { "src": "/path/to/final.md", "label": "Final" }
  ]
}

Содержимое загружается лениво при переключении вкладок и кэшируется после загрузки.

Поля конфигурации

*Требуется либо src (один), либо items (несколько). Если оба присутствуют, приоритет у items.

Важно: Путь src должен быть абсолютным. Рендерер читает его с той же валидацией пути, что и другие блоки предпросмотра — принимаются пути в домашней директории пользователя, системной директории tmp или директориях workspace; произвольные абсолютные пути вне этих областей отклоняются. Когда агент записывает файл для предпросмотра, он по-прежнему должен соблюдать текущий режим прав (например, записи в режиме Изучения ограничены plansFolderPath / dataFolderPath сессии).

Частые сценарии

После создания .md-файла

Самый частый случай — вы использовали Write, чтобы создать .md-файл, затем показываете его в отрендеренном виде:

{
  "src": "/Users/me/Workspace/notes/decision.md",
  "title": "Decision log"
}

Показ плана пользователю

Папка с планами (в plansFolderPath) хранит планы сессии. Чтобы отобразить один из них во встроенном отрендеренном виде:

{
  "src": "/absolute/path/to/plans/feature-x.md"
}

Сравнение версий спецификации

{
  "title": "Spec evolution",
  "items": [
    { "src": "/path/to/v1.md", "label": "Initial" },
    { "src": "/path/to/v2.md", "label": "After review" },
    { "src": "/path/to/final.md", "label": "Accepted" }
  ]
}

Поведение рендеринга

• Содержимое файла проходит через тот же markdown-рендерер, что используется в чате. Таблицы GFM, код с подсветкой синтаксиса, заголовки, списки, цитаты и математические выражения во встроенном виде поддерживаются.
• Встроенный предпросмотр ограничен высотой 400px и имеет градиентное затухание снизу. Нажмите кнопку развертывания (в правом верхнем углу), чтобы увеличить высоту на месте.
• Блок markdown-preview внутри отрендеренного файла обрабатывается как обычный блок кода — бесконечной рекурсии нет. Другие блоки предпросмотра (mermaid, datatable, …), встроенные в файл, по-прежнему рендерятся.
• Ссылки внутри отрендеренного markdown обрабатываются теми же обработчиками, что и остальной чат: пути к файлам открываются через файловый менеджер ОС, URL — в системном браузере.

Дерево решений

Пользователь хочет увидеть отрендеренный markdown?
  → ДА: Используйте markdown-preview (укажите абсолютный путь)
  → НЕТ: Прочитайте файл и приведите нужный текст во встроенном виде

Содержимое — markdown-файл (.md, .markdown)?
  → ДА: Используйте markdown-preview
  → НЕТ: HTML? → html-preview
        PDF?  → pdf-preview
        Изображение? → image-preview
        Данные? → datatable/spreadsheet

Устранение неполадок

«Loading...» отображается бесконечно

• Путь src должен быть абсолютным, а не относительным.
• Убедитесь, что файл существует по этому точному пути.
• Путь должен находиться внутри разрешённой директории (home, tmp или workspace).

Пустая область предпросмотра

• Файл может быть пустым.
• Файл может быть не текстовым файлом с расширением .md. Убедитесь, что содержимое — markdown.

Блок отображается как сырой JSON-код

• JSON-спецификация некорректна, либо отсутствуют/пусты и src, и items.
• Проверьте, что src — строка (не массив), а items — массив объектов с полем src.

Ссылки внутри отрендеренного markdown не открываются

• Обычные URL https:// открываются в системном браузере.
• Абсолютные пути файловой системы открываются через файловый менеджер ОС.
• URL file:// блокируются встроенным слоем безопасности URL приложения (метод shell.openExternal может запускать локальные исполняемые файлы на Windows) — используйте обычный путь файловой системы или ссылайтесь на файл через другой блок предпросмотра.