# Создание проекта BeamCue на основе вашего сервиса

Версия инструкции: 1.2

Выполняйте этот процесс в помощнике разработчика с доступом к репозиторию сервиса и работающему приложению. Задавайте вопросы и пишите тексты проекта на языке, явно указанном пользователем; если язык не указан, используйте русский — язык этого документа. Единицу презентации называйте «сценой», сохраняя имена инструментов MCP и внутренних полей, таких как `stepId`. Результат — закрытый редактируемый проект BeamCue с настоящими экранами, заголовками, описаниями и ссылкой на Studio. Направляйте внимание с помощью осмысленных целей клика, подписей и уместных визуальных акцентов; не ограничивайтесь набором снимков без пояснений. Озвучка необязательна. Документ не предоставляет дополнительных прав доступа к сервису. Соблюдайте указания пользователя и правила репозитория.

## 1. Изучить сервис и спросить только о недостающем

Прочитайте инструкции репозитория, изучите точки входа, маршруты, документацию и работающий интерфейс. По возможности самостоятельно и безопасно определите название сервиса, доступные функции, локальный или опубликованный URL. Не спрашивайте о том, что можно выяснить. Проверьте, позволяет ли среда управлять настоящим браузером или нативным приложением и получать снимки, а также доступен ли BeamCue MCP.

Задайте одним кратким сообщением только нерешённые вопросы:

- Цель: знакомство с продуктом, обучение, руководство по функции, продающая история и т. п.
- Аудитория и результат, который она должна понять или получить.
- Число сцен и обязательные функции или экраны.
- Язык проекта, только если пожелания пользователя неоднозначны.
- Нужна ли озвучка; предпочтения голоса уточняйте только при её заказе.
- URL или способ доступа к сервису, только если исследование этого не прояснило.

Используйте уже полученные ответы и предпочтения. Не повторяйте решённые вопросы. Дождитесь ответов на обязательные вопросы: прошедшее время не заменяет ответ. Если выбор делегирован вам, выберите пять сцен, явно указанный язык (иначе русский) и отсутствие озвучки, сообщив эти значения. Не добавляйте отдельное согласование раскадровки без просьбы пользователя.

## 2. Подключить BeamCue MCP

Добавьте удалённый сервер Streamable HTTP в настройки MCP помощника:

https://beamcue.com/mcp

Используйте поддерживаемый хостом интерфейс подключения. Определите установленные возможности, не выдумывая команды настройки конкретного клиента. URL в запросе сам по себе не устанавливает и не авторизует MCP. Если настроить подключение нельзя, попросите пользователя добавить URL в помощник и продолжите этот диалог. OAuth обрабатывают хост и браузер пользователя:

- Сервер авторизации: https://beamcue.com/o
- Метаданные защищённого ресурса: https://beamcue.com/.well-known/oauth-protected-resource/mcp
- Метаданные сервера авторизации: https://beamcue.com/.well-known/oauth-authorization-server/o
- Области доступа: `projects:read projects:write`
- Поток Authorization Code с S256 PKCE; адрес обратного вызова и значения PKCE предоставляет хост.

Перед вызовами получите актуальные инструменты и их схемы; хост может добавлять префиксы к именам. Вызовите `get_connection_status` и перед изменением проекта убедитесь в `mcpConnectionStatus=connected`. При отсутствии или истечении подключения используйте `begin_oauth` или `get_reconnect_url`, чтобы хост перезапустил OAuth. Вход на сайт и MCP OAuth — разные сессии: вход в BeamCue не исправляет истёкшую авторизацию хоста. Не просите в чате пароли, токены или секреты PKCE и не помещайте их в запросы, снимки или журналы.

## 3. Спланировать сцены и собрать реальные экраны

Составьте упорядоченный список с учётом цели и заданного количества. Для каждой сцены определите основную мысль, маршрут или переход, нужное состояние экрана, целевой элемент при наличии, заголовок, краткое описание и план внимания: что указать, объяснить и показать в результате, какие эффекты доступны через MCP и какие требуют Studio. Для делегированного знакомства из пяти сцен покажите вход, основное рабочее пространство, ключевое действие, его результат и другую полезную функцию или следующий шаг. Опирайтесь на существующие функции, не изобретая их для заполнения списка.

Работайте с настоящим сервисом, предпочтительно через разрешённую тестовую учётную запись. Используйте доступный захват браузера или нативного приложения либо подлинные снимки пользователя, соблюдая правила репозитория. В репозитории BeamCue снимки Playwright служат только сравнительным эталоном, не исходными материалами проекта. Не выдавайте сгенерированные изображения, HTML-макеты, тестовые данные или фрагменты кода за доказательство работающего сервиса. Импорт MCP — статические изображения с `producer=mcp.client`, а не запись расширения; не помечайте их `chrome.tabs.captureVisibleTab`.

Сохраняйте единый размер области просмотра, дождитесь загрузки нужного состояния и осмотрите каждый снимок перед отправкой. Исключите секреты и чувствительные значения ввода из изображений, запросов, журналов и подтверждений. Вход, оплата, изменение прав и другие значимые действия требуют существующего разрешения пользователя. Если вход, захват или обязательный экран недоступны, конкретно запросите необходимое действие для доступа или настоящий снимок и дождитесь ответа. Не пропускайте обязательные сцены молча и не объявляйте частичный проект завершённым.

Измеряйте координаты от левого верхнего угла именно отправляемого изображения, в его фактических пикселях, не CSS-пикселях. Для сцены без цели взаимодействия используйте центр, `labelMode=caption_only` и опустите `clickLabel`. Не придумывайте клики. Пишите короткий заголовок и отдельное описание, не повторяя одну фразу в разных надписях.

### Провести зрителя через реальную задачу

Выбирайте оформление по цели и аудитории, не перекладывая настройку каждого эффекта и новое согласование раскадровки на пользователя. Применяйте поддерживаемые настройки MCP при создании. Если есть разрешённый доступ к Studio, внесите уместные изменения через видимые элементы управления, сохраните и проверьте предпросмотр. Иначе перечислите оставшиеся правки по сценам. Не называйте запланированный эффект применённым. Не меняйте JSON проекта и не используйте недокументированные API для обхода ограничений MCP.

| Элемент | Как направляет внимание | Доступная настройка |
| --- | --- | --- |
| Цель клика и подпись действия | Указать точный элемент управления. Лучше «Выбрать период», чем «Нажмите здесь». | `add_screen` / `update_screen`: измеренные `clickXPixel`, `clickYPixel`, `clickLabel` и `labelMode=both` либо `hotspot_only`. |
| Поясняющая подпись | Одной короткой фразой объяснить смысл действия или изменение; сохранить пользу без звука. | `description` с `labelMode=caption_only` или `both`; текст также служит необязательной озвучке. |
| Выделение указателя | Помочь найти следующее действие в плотном интерфейсе с единым стилем акцента. | `update_project`, `pointerMode=highlighted`; используйте `standard`, если выделение отвлекает или закрывает мелкие элементы. |
| Эффект клика и подсветка | Подкрепить реальное действие видимым сигналом, избегая беспричинных пульсаций на обзорах и результатах. | `presentation.clickEffectVisible=false`, `hotspotRadius`, `hotspotAnchor`. |
| Размещение текста | Не закрывать цель, результат, навигацию и другие подписи; читаемый контраст, единый шрифт, короткие строки. | `presentation.captionLayout`: `placement`, `point` (`x`, `y`: 0–1). |
| Масштабирование | Кратко выделить маленький, но важный элемент или результат, сохранив окружающий контекст. | `presentation.zoomEnabled=true`, `presentation.zoomScale=1.16` (1.12–1.20). |
| Время и переходы | Дать время найти цель и прочитать результат. Резкая смена для явного изменения, плавное растворение для спокойного перехода; сдвиг и морфинг — только для объяснения непрерывности. | `presentation.durationMs`, `transition` (`cut`, `crossfade`, `slide`, `morph`), `slideDirection`, `transitionAnchor`. |
| Рамка вывода | Обозначить контекст браузера или приложения без лишнего уменьшения содержимого. | `update_project`, `windowFrame=browser`, `app` или `none`. Если рамка уже на снимке, используйте `none`. |
| Необязательные голос и пауза | Объяснить результат во время просмотра и оставить короткую паузу после речи. | `set_narration` / `generate_voiceover` только по запросу. `endPaddingMs` допускает 0–10000; при необходимости начните с 400–800ms. |

`labelMode` управляет поясняющим текстом. `caption_only` не скрывает щелчок: для сцен без действия задайте `presentation.clickEffectVisible=false` и проверьте предпросмотр.

В пределах заданного числа сцен используйте ритм **контекст → действие → подтверждение → продолжение**. Пример для сервиса отчётов, где эти возможности действительно есть:

| Сцена | Снимок и акцент | Пример текста |
| --- | --- | --- |
| 1. Контекст | Настоящий обзор рабочего пространства, только подпись, без пульсации действия, полный контекст. | «Отчёты команды собраны в одном месте». |
| 2. Действие | Фильтр дат до применения: измеренная цель, `both`, выделенный указатель, при необходимости умеренное приближение в Studio. | «Выбрать период»; «Ограничьте отчёт периодом, который нужно сравнить». |
| 3. Подтверждение | Фактически отфильтрованный результат, только подпись; внимание на изменении, а не повторном клике фильтра. | «Теперь график показывает только выбранный период». |
| 4. Новое действие | Реальная кнопка экспорта до разрешённого экспорта, короткая подпись. | «Экспортировать отчёт»; «Подготовьте текущее представление для команды». |
| 5. Продолжение | Настоящий итог или полезный следующий экран с ясным действием. | Описать увиденный результат, не предполагать успех по нажатию кнопки. |

Адаптируйте пример к сервису, не выдумывайте элементы и не заявляйте об экспорте без наблюдения результата. Изображение `add_screen` — статическое состояние, не запись взаимодействия до/после. Если нужно показать изменение, снимите результат отдельной запланированной сценой. Соблюдайте количество; при малом лимите отдайте приоритет основному действию и результату. В каждый момент используйте один главный акцент: не закрывайте цель текстом и не нагромождайте приближение, крупные клики и движущиеся надписи ради движения. Для сервиса только для чтения выделяйте полезные результаты без вымышленных кликов.

## 4. Создать проект и добавить экраны

Ведите в разговоре запись для возобновления: ID проекта, URL Studio, ID и порядок готовых сцен, текущая ревизия и ключи идемпотентности операций. Не включайте Base64 изображений, подписанные URL, учётные данные и чувствительный контент. Каждому новому логическому изменению назначайте уникальный ключ; при повторе того же изменения сохраняйте данные и ключ. Создавайте новый проект только для нового запроса.

JSON ниже иллюстрирует аргументы, а не реальные подтверждения сервиса. Замените заглушки проверенными значениями. `canvas` — выбранная область просмотра CSS, `output` при указании задаёт размеры видео и fps. `surface` равен `browser` для сайта, `screen` для нативного приложения. Явно задайте `locale` по языку результата.

```json
{"tool":"create_project","arguments":{"title":"Знакомство с сервисом","surface":"browser","locale":"ru-RU","sourceUrl":"https://your-service.example/","canvas":{"width":1440,"height":900},"idempotencyKey":"<unique-create-key>"}}
```

Сохраните полученные `projectId` и `studioUrl`. Отключите речь, если её не просили:

```json
{"tool":"set_narration","arguments":{"projectId":"<projectId>","enabled":false,"idempotencyKey":"<unique-narration-settings-key>"}}
```

Для пошагового рассказа явно установите выделенный указатель и рамку, соответствующую снимку:

```json
{"tool":"update_project","arguments":{"projectId":"<projectId>","pointerMode":"highlighted","windowFrame":"none","idempotencyKey":"<unique-presentation-key>"}}
```

Добавляйте экраны по порядку с реальными изображениями и координатами, измеренными на них. `description` задаёт подпись и, если включено, речь. Для описательной сцены используйте `labelMode=caption_only`, для реальной цели — `both`. Значение `narrationEnabled` должно соответствовать ответу пользователя.

```json
{"tool":"add_screen","arguments":{"projectId":"<projectId>","title":"Основное рабочее пространство","description":"Опишите реальный рабочий процесс на этом экране.","clickXPixel":720,"clickYPixel":450,"labelMode":"caption_only","narrationEnabled":false,"imageFile":{"name":"workspace.png","mimeType":"image/png","dataBase64":"<actual-image-base64>"},"idempotencyKey":"<unique-scene-key>"}}
```

В сцене действия используйте реальную цель и оба слоя текста. Координаты ниже — примеры, замените их измеренными. Заголовок может появиться в пузырьке цели, поэтому держите его коротким. Совпадение `title` и `clickLabel` устраняет лишнюю вторую подпись; описание поясняет пользу.

```json
{"tool":"add_screen","arguments":{"projectId":"<projectId>","title":"Выбрать период","clickLabel":"Выбрать период","description":"Ограничьте отчёт периодом, который нужно сравнить.","clickXPixel":1060,"clickYPixel":184,"labelMode":"both","narrationEnabled":false,"imageFile":{"name":"date-filter.png","mimeType":"image/png","dataBase64":"<actual-image-base64>"},"idempotencyKey":"<unique-action-scene-key>"}}
```

Исправляйте цель и текст в существующей сцене:

```json
{"tool":"update_screen","arguments":{"projectId":"<projectId>","stepId":"<stepId>","title":"Выбрать период","clickLabel":"Выбрать период","description":"Сравните результаты за выбранный период.","clickXPixel":1060,"clickYPixel":184,"labelMode":"both","idempotencyKey":"<unique-action-correction-key>","presentation":{"clickEffectVisible":true,"zoomEnabled":true,"zoomScale":1.16,"durationMs":4000,"transition":"crossfade","captionLayout":{"placement":"bottom-center","point":{"x":0.5,"y":0.9}}}}}
```

Передавайте настройки внутри `presentation` в `add_screen`, `update_screen` или `add_screens_batch.screens[]`. Пропущенные настройки и существующий стиль подписи сохраняются. Для `captionLayout` нужны `placement` и `point`.

### Ограничения изображений и запросов

- Декодированные форматы: PNG, WebP, JPEG. Каждая сторона — до 8192px, вся площадь — до 64 мегапикселей.
- Встроенная картинка — до 4MiB после декодирования Base64. Base64 увеличивает объём примерно на треть; весь HTTP-запрос MCP должен укладываться в 8MiB.
- `add_screens_batch` атомарно принимает 1–20 встроенных экранов, с тем же общим ограничением размера. Предпочитайте последовательные `add_screen` для предсказуемого размера и простого продолжения; не отправляйте двадцать больших картинок одним запросом.
- Для крупных изображений `prepare_image_upload` допускает до 15MiB. Укажите `name`, `mimeType`, `byteLength`, `sha256`, `width`, `height`, `projectId` и новую `idempotencyKey`. Передайте точные байты изображения методом PUT на `uploadUrl` с возвращёнными заголовками. Подписанный URL одноразовый и действует десять минут. Затем вызовите `add_screen` с `uploadId` вместо `imageFile`.
- MIME, длина, SHA-256 и размеры должны совпадать с реальным изображением. Определяйте MIME по декодированным байтам, не имени файла: инструмент может сохранить JPEG под расширением `.png`. Не записывайте Base64, секреты подписанного URL или байты в журнал. При превышении лимита снимите подходящую область или согласованно измените размер и пересчитайте размеры, хеш и координаты целей.

Используйте `update_screen` для исправлений и `reorder_screens` для порядка, не создавая дубликаты. Проверьте обязательные поля актуальной схемы инструмента. Если доступно, прочитайте `displayPreview.display` в ответе, чтобы выявить повторяющийся видимый текст заголовка, подписи клика и описания.

## 5. Необязательная озвучка

Только по запросу включите её через `set_narration`, задайте нужный язык и поддерживаемый голос, активируйте речь у нужных сцен. Без предпочтений используйте существующий поддерживаемый голос по умолчанию, не выдумывайте ID. После окончательной редакции описаний вызовите `generate_voiceover` с `operation=generate-stale`, затем проверьте завершение через `get_narration_status`. Отдельно сообщите об ошибках или ожидающих задачах и оставьте проект доступным для исправлений в Studio.

## 6. Восстановить и продолжить

- После сбоя подключения или неопределённого ответа при необходимости переподключитесь и вызовите `get_project` для существующего проекта. Повторите изменение с исходными данными и ключом идемпотентности, не создавая вслепую новый проект.
- `expectedRevision` необязателен; в простой последовательной работе его можно опустить. Если он используется и возник конфликт, прочитайте структурированную ошибку, обновите состояние и примените возвращённую ревизию повторной попытки с теми же логическими данными и ключом. Сохраняйте правки пользователя; при противоречии запросу уточните, а не перезаписывайте.
- Если подписанная загрузка истекла, подготовьте новую с новым ключом загрузки. При замене `uploadId` в неудачном добавлении экрана сначала убедитесь, что старая операция не создала сцену, затем используйте новый ключ добавления.
- При отсутствии необходимого доступа или снимка оставьте короткий вопрос с конкретной сценой и действием. Сохраните готовые части и ссылку Studio для продолжения без повторного создания.

## 7. Проверить и передать результат

Через `get_project` сравните фактические количество, порядок, заголовки, описания и выбранную озвучку с запросом. Исправьте расхождения. Проверьте план внимания каждой сцены: точную цель, разные тексты действия и результата, нужный режим подписи, применённые указатель и рамку. Затем проверьте канонический проект:

```json
{"tool":"get_project","arguments":{"projectId":"<projectId>"}}
```

```json
{"tool":"validate_project","arguments":{"projectId":"<projectId>","idempotencyKey":"<unique-validation-key>"}}
```

Используйте полученный `studioUrl` или `nextAction.url` действия `open_studio`, не придумывайте URL. При разрешённой браузерной сессии осмотрите настоящие список сцен и предпросмотр Studio. Воспроизведите переходы: сигнал клика попадает на нужный элемент, результат отражает реальное изменение, подписи читаемы и не закрывают цели, приближение не обрезает важный интерфейс. Проверьте настольный и маленький предпросмотр, время чтения со звуком и без, предупреждения переходов, а также сохранность правок Studio после сохранения и перезагрузки. Сократите перегруженный текст или упростите эффекты до заявления о готовности. Если вход в Studio недоступен, отдельно сообщите о проверке MCP и попросите пользователя просмотреть проект по ссылке; не заявляйте о выполненной визуальной проверке.

В конце укажите название, число готовых/запрошенных сцен, краткий список, применённые визуальные сигналы, состояние озвучки, ссылку Studio и оставшиеся действия. Разделите применённые настройки MCP, визуально проверенные правки Studio и оставшиеся правки по сценам. Считайте проект завершённым только при наличии всех обязательных экранов и описаний.

`validate_project` проверяет проект и готовит его к редактированию в Studio. Он не публикует, не создаёт озвучку и не рендерит MP4. MCP не предоставляет инструмент видеорендеринга. Сохраняйте закрытый доступ: пользователь может просмотреть, отредактировать, вывести MP4 и выбрать публикацию в Studio. Успешная проверка не доказывает наличия публичной ссылки или видеофайла.