marozz1k2/puzzledocs

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

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

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

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

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

Контекст PuzzleAI

• Основной endpoint трекера: https://api.pxsto.re/main/puzzlebot-tracker
• Рабочий метод запроса: POST
• Вид запроса в PuzzleBot: Сформированный
• Формат переменных: {{VAR}}
• Обязательная база любого запроса: bot, token, user, model
• Основной параметр задачи обычно prompt; для медиа-сценариев дополнительно используется images, для документов — document=true
• Основные категории моделей:
  • Текст
  • Голос
  • Фото
  • Видео
  • Музыка
  • Другое

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

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

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

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

1. # Название модели
2. краткое описание назначения модели
3. ## Как отправлять запрос
4. ## Пример запроса с комментариями
5. ## Параметры
6. ## Ответ
7. ## Важно при необходимости

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

# model_name

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

## Как отправлять запрос

- Ссылка: `https://api.pxsto.re/main/puzzlebot-tracker`
- Метод: `POST`
- Вид запроса в PuzzleBot: `Сформированный`
- Формат тела: `application/json` или те же ключи в no-code параметрах.

Обязательная база для любого запроса: `bot`, `token`, `user`, `model`.

## Пример запроса с комментариями

```jsonc
{
  "bot": "{{BOT_USERNAME_TEXT}}", // обязательно: username бота в PuzzleBot.
  "token": "[Ваш API-токен]", // обязательно: API-токен бота.
  "user": "{{USER_ID_TEXT}}", // обязательно: ID пользователя или сессии.
  "model": "model_name", // обязательно: точный ключ модели.
  "prompt": "{{prompt}}", // обычно обязательно: текст задачи; исключения описываются в статье модели.
  "role": "[текст роли]", // необязательно: роль, стиль или ограничения.
  "send_answer": true // необязательно: отправить результат пользователю.
}
```

## Параметры

| Параметр | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| `bot` | string | Да | Username бота: `{{BOT_USERNAME_TEXT}}`. |
| `token` | string | Да | API-токен бота. |
| `user` | string | Да | ID пользователя: `{{USER_ID_TEXT}}`. |
| `model` | string | Да | Точный ключ модели. |
| `prompt` | string | Зависит от модели | Текст задачи. |
| `role` | string | Нет | Дополнительная инструкция. |
| `send_answer` | boolean | Нет | Отправлять ли результат пользователю. |

## Ответ

```json
{
  "answer": "..."
}
```

Формат changelog

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

## Месяц Год

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

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

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

- Пункт 1
</details>

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

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