content_publish

Что делает

Публикует файл из директории текущей сессии для просмотра пользователем прямо в чате. Поддерживаются интерактивные viewer'ы для 3D-моделей (STL, glTF/GLB), HTML-страниц, SVG, PDF, изображений, видео, аудио и текстовых/исходных файлов.

Важно: workspace/ и директория сессии — разные места.

• workspace/ — постоянная приватная рабочая зона Нави для черновиков, скриптов, заметок, промежуточных данных и файлов, которые могут пригодиться позже.
• session_files/{session_id}/ — временная зона конкретной сессии для загруженных пользователем файлов и артефактов, которые пользователь должен увидеть в чате.
• content_publish публикует только файлы из директории текущей сессии. Он не копирует файлы из workspace/.
• Если нужен только download link для файла из workspace/, используйте share_file: он сам копирует файл в директорию сессии. Если нужен inline viewer, файл должен оказаться в директории сессии, а затем его нужно зарегистрировать через content_publish.

Как работает внутри

1. Файл уже должен быть в директории сессии (session_files/{session_id}/ по умолчанию; точный корень задаёт SESSION_FILES_DIR).
2. Инструмент не копирует файл — он только регистрирует метаданные в базе данных.
3. Пользователь видит файл по URL /sessions/{session_id}/files/{filename}.
4. Если вы отредактируете файл после публикации, пользователь увидит изменения сразу (перезагружать страницу не нужно).
5. Опубликованные файлы остаются доступными в панели Artifacts, поэтому повторная публикация не нужна только для того, чтобы снова показать карточку ниже в диалоге.

Формат вызова

content_publish(
    filename="мой_файл.svg",      # обязательно — имя файла в директории сессии
    title="Моя диаграмма",        # опционально — заголовок карточки
    content_type="svg",           # опционально — тип для viewer (автоопределение по расширению)
    source_filename="model.scad"  # опционально — исходник для STL, если .scad файл есть в той же директории
)

Где находится директория сессии

Директория сессии — это session_files/{session_id}/ по умолчанию. Полный путь зависит от настройки SESSION_FILES_DIR.

Как узнать путь:

filesystem info session_files/{session_id}

Если content_publish не нашёл файл, он вернёт точный путь директории текущей сессии. Доверяйте этому пути и пишите/копируйте файл туда.

Типичный workflow

1. Создание и публикация

# Создать SVG в директории сессии
filesystem write session_files/sess-abc/chart.svg "<svg>...</svg>"

# Опубликовать
content_publish(filename="chart.svg", title="Диаграмма продаж")

2. Редактирование после публикации

# Прочитать текущий файл
filesystem read session_files/sess-abc/chart.svg

# Отредактировать
filesystem write session_files/sess-abc/chart.svg "<svg>...исправлено...</svg>"

Пользователь увидит изменения через ту же карточку и панель Artifacts — URL не меняется, повторно вызывать content_publish не нужно.

Поддерживаемые типы

Для неизвестных типов показывается карточка со ссылкой на скачивание.

Как определяется тип

Тип определяет navi/content_types.py — сначала по расширению, затем по сигнатуре файла. Поэтому файл с неверным расширением всё равно открывается правильным viewer'ом: PNG, сохранённый как .txt, — изображение; переименованный .mp3 — аудио; .ts, который не является MPEG-транспортным потоком, — текст (TypeScript), а не видео.

Параметр content_type нужен только если автоопределение ошиблось; значение вне поддерживаемого списка игнорируется, и тип определяется по файлу. Передавать content_type="unknown" бессмысленно.

Графический контент (изображение, SVG, HTML, PDF, 3D-модель, видео) можно развернуть на весь экран кнопкой в шапке карточки и в панели Artifacts.

glTF: надёжно работает .glb — буферы и текстуры внутри файла. .gltf, ссылающийся на отдельные .bin и изображения, отрендерится только если все эти файлы тоже лежат в директории сессии (публикуется при этом только сам .gltf).

Просмотр исходников

Для .svg и .html пользователь может открыть исходник прямо из карточки/панели Artifacts — отдельный параметр не нужен, потому что опубликованный файл сам является исходником.

Для .stl можно передать source_filename, если модель была создана из OpenSCAD и .scad файл лежит в той же директории сессии:

content_publish(filename="part.stl", title="Деталь", content_type="stl", source_filename="part.scad")

Если STL был скачан или исходного .scad нет, просто не передавайте source_filename. Это нормальная ситуация и не ошибка.

Важные правила

1. Файл должен существовать ДО вызова — content_publish не создаёт файлы, только регистрирует.
2. Не публикуйте напрямую из workspace/ — сначала поместите финальный файл в директорию текущей сессии.
3. Проверяйте коллизии — если файл с таким именем уже есть, запись публикации будет обновлена, а файл останется тем же путём.
4. Используйте понятные имена — chart.svg лучше чем file_1.svg.
5. Для редактирования используйте тот же путь — не создавайте новые копии, правьте оригинал в директории сессии.
6. Не дублируйте опубликованный контент в текстовом ответе — content_publish уже отображает файл пользователю в чате в виде интерактивной карточки и в панели Artifacts. После вызова content_publish не вставляйте SVG-код, HTML-разметку, base64-изображения, screenshots, iframe/markdown preview или вторую визуальную копию результата в текст сообщения. В текстовом ответе достаточно краткого подтверждения и не-визуальных пояснений.
7. Не публикуйте повторно ради видимости — если карточка ушла выше по диалогу, пользователь всё равно найдёт файл в панели Artifacts. Для обновления содержимого правьте тот же файл в директории сессии.
8. Повторная публикация допустима осознанно — используйте её для нового файла или если нужно обновить метаданные публикации, например title или content_type.
9. STL source опционален — передавайте source_filename только если реальный .scad исходник существует в директории сессии. Не выдумывайте путь и не считайте отсутствие исходника ошибкой.