SKILL: Документирование PuzzleAI

Практическое руководство по созданию и редактированию документации PuzzleAI в GitBook-репозитории.

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

Используйте этот скилл, когда нужно:

• добавить новую статью по модели;
• оформить референс трекер-запроса;
• описать параметры no-code API;
• унифицировать стиль страниц в документации PuzzleDocs;
• зафиксировать изменения в changelog.

Контекст PuzzleAI

• Основной endpoint трекера: https://api.pxsto.re/main/puzzlebot-tracker
• Формат переменных: {{VAR}}
• Основные категории моделей:
  • Текст
  • Голос
  • Фото
  • Видео
  • Музыка
  • Другое

Правила по веткам

• Все изменения делаются только в ветке main.
• PR создаются только из ветки main.
• Не использовать дополнительные рабочие ветки в этом репозитории.

Структура страницы модели

Каждая страница модели должна содержать следующие разделы:

1. # Название модели
2. ## Описание
3. ## Endpoint
4. ## Метод
5. ## Параметры
6. ## Пример no-code запроса
7. ## Пример cURL (по возможности)
8. ## Ожидаемый ответ (если есть подтверждённый формат)
9. ## Ошибки и диагностика

Шаблон статьи

---
description: Краткое описание страницы
---

# model_name

## Описание
Коротко опишите назначение модели и тип задач.

## Endpoint
`https://api.pxsto.re/main/puzzlebot-tracker`

## Метод
`POST`

## Параметры

| Параметр | Тип | Обязательный | Пример | Описание |
| --- | --- | --- | --- | --- |
| user | string | Да | `{{USER_ID_TEXT}}` | Идентификатор пользователя |
| model | string | Да | `model_name` | Системное имя модели |
| bot | string | Да | `{{BOT_ID}}` | Идентификатор бота |
| prompt | string | Да | `Напиши ...` | Текст задания для модели |

## Пример no-code запроса

- Ссылка: `https://api.pxsto.re/main/puzzlebot-tracker`
- Тип запроса: `POST`
- Параметры:
  - `user`: `{{USER_ID_TEXT}}`
  - `model`: `model_name`
  - `bot`: `{{BOT_ID}}`
  - `prompt`: `Ваш запрос`

## Пример cURL

```bash
curl -X POST 'https://api.pxsto.re/main/puzzlebot-tracker' \
  -H 'Content-Type: application/json' \
  -d '{
    "user": "{{USER_ID_TEXT}}",
    "model": "model_name",
    "bot": "{{BOT_ID}}",
    "prompt": "Ваш запрос"
  }'

Ожидаемый ответ

{
  "ok": true,
  "result": "..."
}

Ошибки и диагностика

• Проверьте корректность model.
• Убедитесь, что переменные {{...}} подставлены.
• Проверьте формат JSON и обязательные поля.

## Формат changelog

Для публикации изменений используйте `CHANGELOG.md` со структурой:

```markdown
## Месяц Год

<details>
<summary>Новое</summary>

- Пункт 1
- Пункт 2
</details>

<details>
<summary>Фиксы</summary>

- Пункт 1
</details>

Правила качества

• Пишите коротко, по делу, без «воды».
• Используйте одинаковые названия параметров во всех статьях.
• Не смешивайте русский и английский в именах параметров.
• Если формат ответа не подтверждён, явно укажите это.
• Все примеры должны быть воспроизводимыми.