# content_publish

## Что делает

Публикует файл из директории текущей сессии для просмотра пользователем прямо в чате. Поддерживаются интерактивные viewer'ы для 3D-моделей (STL), 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, поэтому повторная публикация не нужна только для того, чтобы снова показать карточку ниже в диалоге.

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

```python
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` не нужно.

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

| Расширение | Тип | Viewer |
|---|---|---|
| `.stl` | 3D-модель | Three.js 3D viewer |
| `.html`, `.htm` | HTML | iframe |
| `.svg` | SVG | iframe |
| `.pdf` | PDF | iframe |
| `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` | Изображение | img |
| `.mp4`, `.webm` | Видео | video |

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

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

Для `.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` исходник существует в директории сессии. Не выдумывайте путь и не считайте отсутствие исходника ошибкой.