# Анонс новой модели в Cowork/Code

Десктоп получает активный анонс в `modelAnnouncement` ответа [`GET /v1/cowork/state`](./state.md). Для ключей без назначения `cowork-desktop` поле равно `null`. Ключ должен иметь `vibe:cowork` и быть привязан к человеку и порталу.

## Сохранённый выбор модели

После восстановления выбора модели для **новых сеансов** и при каждом явном переключении десктоп вызывает `PUT /v1/cowork/model-preference`:

```json
{"modelId":"bitrix/bitrixgpt-5.5-agent","previousModelId":"bitrix/bitrixgpt-6.0-agent"}
```

`modelId` и `previousModelId` — публичные канонические идентификаторы из `/v1/models`. Для личной или внешней модели, отсутствующей в `/v1/models`, вместо приватного ID отправляют только литерал `modelId: "external"`. Если выбор человека пока не восстановлен, запрос не отправляют. Портальный default не заменяет выбор. Повтор того же выбора не создаёт новую запись истории.

## Снимок и события

`modelAnnouncement` содержит `id`, `modelId`, `shortName`, `title`, `baseLocale`, словари `descriptionByLocale` и `returningByLocale`, `starterIds`, `startedAt`, `endsAt`, `returning`, `eligible`, `reason` и `progress`. `title` предназначен для первого окна; `shortName` — для остальных поверхностей. При отсутствии перевода текста клиент берёт `baseLocale` (`ru` на `.tech`, `en` на `.com`).

`eligible: false` означает, что касание не показывают. Возможные `reason`: `selection_unknown`, `selected_model`, `recently_used`, `refused`, `already_tried`, `dismissed_three_times`. Отсутствие сохранённого выбора всегда даёт `selection_unknown`, даже если целевая модель стоит по умолчанию.

`POST /v1/cowork/model-announcement/:id/events` принимает `{ "eventId": "UUID", "action": "shown", "step": 1 }` для показа. Ответы `dismiss`, `never`, `try` отправляются отдельно, с тем же UUID при повторе одного запроса. `never` отказывается от всего анонса; `dismiss` закрывает текущее касание. Сервер атомарно проверяет следующий шаг, интервалы и состояние кампании. Ответ: `{ "success": true, "replayed": false }`.

Для воронки можно передать `surface: "window" | "hint"` при показе и закрытии; `try` принимает необязательные `surface: "window" | "hint" | "session"`, `source: "primary" | "starter" | "session_switch"` и `starterId` для готовой задачи. У всех действий есть необязательные `tab: "cowork" | "code"` и `locale: "ru" | "en" | "de" | "es" | "fr" | "pt-BR" | "ja" | "zh" | "th" | "vi"` для разреза статистики. Событие `session_opened` передаёт `{ "eventId": "UUID", "action": "session_opened", "tab": "cowork", "sessionId": "стабильный ID сеанса", "sessionKind": "new" }`; допустим также `tab: "code"` и `sessionKind: "existing_idle"`. Сервер дедуплицирует по кампании, месту, вкладке, сеансу и типу открытия. Его можно отправлять до пробы модели, когда человек в аудитории, и после пробы. Произвольные вкладки и типы не принимаются.

Лестница: первый показ, затем дни 3, 7, 21 и 30 от первого показа при интервале не менее трёх суток между касаниями. `endsAt` — исключающая граница после последнего календарного дня кампании.

## Администрирование

В настройках Коворка создание чат-модели требует явного ответа, нужен ли анонс (`announce: true/false` в `POST /api/platform/cowork-settings/models`). Создать черновик, проверить аудиторию и статистику, запустить и остановить можно через `/api/platform/cowork-settings/models/:policyId/announcement`. Повторно запустить завершённый анонс нельзя.

Статистика `/announcement/stats` считает долю получателей и их порталов с успешным ходом на модели за неделю. Аудитория перед запуском восстанавливается по истории сохранённого выбора на начало предыдущей недели; при неполной истории `before` равен `null`. `after` появляется после полной недели на зафиксированной при запуске аудитории. Она не подменяется общим числом активных мест. `eventsByStep` содержит фактические показы, закрытия, отказы, пробы, выбор готовой задачи и перехода, открытия сеансов по пяти шагам; `eventsByTabLocale` разбивает касания по вкладкам и языкам. `sessionTriggers` считает новые и продолженные сеансы до пробы отдельно от сеансов после пробы. `outcomes.tried` считает получателей из аудитории, которые нажали пробу, выбрали модель сами или сделали успешный ход; `outcomes.retained` — тех из них, у кого целевая модель выбрана сейчас. `firstSuccessfulTurnUsers` считает получателей с хотя бы одним успешным ходом на целевой модели во время кампании. `rollback` показывает возврат к непосредственно предыдущей сохранённой модели и отдельно число получателей, у которых эта история неизвестна.

Строка тихой фазы в списке моделей использует только полные UTC дни последних семи суток после добавления модели: знаменатель — места с ходами, числитель — те же места с успешным ходом на модели. Если покрытие дневного среза неполное, процент не показывается. Для модели по умолчанию это справочная доля использования, а не эффект анонса.

На международном стенде автор заполняет английский текст и может вручную заполнить остальные языки. Платформа пока не предоставляет сервиса перевода произвольного текста; автоматические переводы не создаются, а пустой язык в клиенте получает английский текст. Это ограничение относительно AC-034.