> For the complete documentation index, see [llms.txt](https://docs.cherryai.com.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cherryai.com.cn/docs/russian/cherry-studio/preview/app/generative-mini-apps.md).

# Генеративное мини-приложение

Создание, установка и использование пользовательских мини-приложений, вызывающих возможности Cherry Studio AI

Генеративные мини-приложения — это локальные веб-приложения, работающие в Cherry Studio【Мини-приложения】. Их интерфейс и бизнес-процессы вы настраиваете сами, а через `window.cherry` вызывают настроенные в Cherry Studio AI-модели, превращая универсальную модель в помощника для письма, инструмент извлечения информации, учебный инструмент или специализированное бизнес-приложение.

Их отличие от обычных мини-приложений на основе веб-сайтов не во внешнем виде, а в источнике возможностей: веб-мини-приложение просто открывает URL; генеративное мини-приложение нужно упаковать в `.miniapp`，установить и получить разрешение, после чего можно использовать AI, песочницу данных, файлы, уведомления, сеть и буфер обмена Cherry.

{% hint style="info" %}
Cherry Studio предоставляет среду выполнения, механизм авторизации и AI-интерфейс. Вы можете написать мини-приложение сами или сначала сгенерировать HTML, CSS и JavaScript с помощью AI-инструмента программирования, а затем упаковать и установить его по инструкции на этой странице.
{% endhint %}

## Цели и предварительные условия

После прохождения этой страницы вы сможете:

* устанавливать и использовать генеративные мини-приложения, предоставленные другими;
* создать собственный `.miniapp` пакет из простой идеи;
* позволять мини-приложению вызывать 【Модель по умолчанию】 или 【Быструю модель】 Cherry Studio;
* проверять разрешения, журнал активности, хранилище, обновления и состояние удаления.

Для использования готовых мини-приложений достаточно подготовить доверенный `.miniapp` файл или URL установки. При создании своего вам также нужно уметь редактировать веб-файлы и создавать ZIP-архив; если хотите протестировать AI-функции, сначала настройте в Cherry Studio доступную модель чата.

## Термины

| Термины                         | Название в интерфейсе                   | Значение на этой странице                                                                                                                 |
| ------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Генеративное мини-приложение    | 【Генеративное мини-приложение】          | мини-приложение с настраиваемым интерфейсом и процессами, которое может использовать AI-возможности Cherry Studio                         |
| Локальное мини-приложение       | 【Локальное мини-приложение】             | тип мини-приложения, устанавливаемый в `.miniapp` пакете и работающий в отдельной песочнице                                               |
| Мини-приложение на основе сайта | 【Сайт】                                  | веб-страница, открываемая по URL, не обладает `window.cherry` возможностями                                                               |
| Разрешения                      | 【Разрешения】                            | набор возможностей, запрашиваемый при установке мини-приложения и проверяемый пользователем                                               |
| Слоты модели                    | 【Модель по умолчанию】, 【Быстрая модель】 | два места для моделей, которые пользователь выбирает для этого мини-приложения; мини-приложение не видит провайдера, имя модели и API Key |

## Путь действий

Использование готового мини-приложения:`【Лаунчпад】→【Генеративные мини-приложения】→【Локальные мини-приложения】→выбрать файл или ввести URL установки→проверить разрешения→【Установить】`

Также можно перейти со страницы мини-приложений:`【Лаунчпад】→【Мини-приложения】→в правом верхнем углу【Добавить мини-приложение】→【Локальное мини-приложение】`

Управление установленными мини-приложениями:`【Мини-приложения】→щелкните правой кнопкой нужное мини-приложение→【Просмотреть подробности】`

## Шаги

### Установка и первое использование

{% stepper %}
{% step %}

### Открыть точку установки

В【Лаунчпад】нажмите【Генеративные мини-приложения】или после входа в【Мини-приложения】нажмите в правом верхнем углу【Добавить мини-приложение】. В открывшейся панели переключитесь на【Локальное мини-приложение】.
{% endstep %}

{% step %}

### Выбрать источник установки

перетащите `.miniapp` пакет в область установки или нажмите【Выбрать файл…】. Если разработчик предоставил HTTPS-URL установки, можно также вставить URL и нажать【Загрузить】.
{% endstep %}

{% step %}

### Проверить разрешения

На странице подтверждения установки будут показаны название мини-приложения, версия, описание и все разрешения. Обязательные разрешения нельзя снять; дополнительные по умолчанию отмечены, их можно снять перед установкой или скорректировать после.

Продолжайте только если назначение мини-приложения соответствует разрешениям и источник надежен. Мини-приложения, которым нужен AI, обычно показывают【AI-возможности】→【Чат】.
{% endstep %}

{% step %}

### Установить и открыть

Нажмите【Установить】. После завершения установки мини-приложение появится в сетке【Мини-приложения】; нажмите на значок, чтобы запустить его.
{% endstep %}
{% endstepper %}

### Выбрать AI-модель для мини-приложения

1. В сетке【Мини-приложения】щелкните правой кнопкой нужное мини-приложение и выберите【Просмотреть подробности】.
2. Переключитесь на【Настройки】и найдите【AI-модель】.
3. В зависимости от назначения мини-приложения настройте【Модель по умолчанию】и【Быструю модель】. Если оставить поля пустыми, они будут следовать глобальной модели по умолчанию и глобальной быстрой модели Cherry Studio соответственно.
4. Снова откройте мини-приложение и вызовите AI-операцию один раз. Если доступной модели нет, мини-приложение должно сообщить, что AI временно недоступен.

【Модель по умолчанию】подходит для длинных текстов, сложного анализа и других основных задач;【Быстрая модель】подходит для предложений по заголовкам, короткого перефразирования, извлечения тегов и других задач с низкой задержкой. Какой именно слот использовать, определяет дизайн мини-приложения.

### Создать минимальную версию

Генеративное мини-приложение по сути — статический веб-проект. Для минимальной структуры каталога нужны только два файла:

```
my-writer/
├── manifest.json
└── index.html
```

Сначала создайте `manifest.json`, объявите информацию об приложении и `ai.chat` разрешение:

```json
{
  "id": "com.example.my-writer",
  "name": { "zh": "Вдохновляющее переписывание", "en": "Rewrite Helper" },
  "description": "Введите текст и используйте AI-модель Cherry Studio для его переписывания.",
  "version": "1.0.0",
  "entry": "index.html",
  "permissions": ["ai.chat"]
}
```

`id` Рекомендуется использовать формат обратного домена, который вы контролируете; он может содержать только строчные буквы, цифры, точки и дефисы.`com.cherrystudio.*` — это зарезервированный официально диапазон, не используйте его.

Затем в `index.html` через глобальный объект `cherry` вызовите AI. В примере ниже сначала проверяется доступность【Модели по умолчанию】, а затем потоковый текст отображается по частям:

```html
<!doctype html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="stylesheet" href="/__cherry/theme.css" />
    <title>Вдохновляющее переписывание</title>
  </head>
  <body>
    <textarea id="source" placeholder="Введите текст для переписывания"></textarea>
    <button id="rewrite">Начать переписывание</button>
    <pre id="result"></pre>

    <script>
      const button = document.querySelector('#rewrite')
      const source = document.querySelector('#source')
      const result = document.querySelector('#result')

      button.addEventListener('click', async () => {
        const capability = await cherry.ai.getCapabilities({ model: 'default' })
        if (!capability.available) {
          result.textContent = 'Сначала настройте доступную модель в подробностях мини-приложения.'
          return
        }

        result.textContent = ''
        await cherry.ai.chat(
          {
            model: 'default',
            reasoning: 'off',
            messages: [
              { role: 'system', content: 'Ты — редактор китайского текста, сохраняй смысл и делай выражение более ясным.' },
              { role: 'user', content: source.value }
            ]
          },
          {
            callId: `rewrite-${Date.now()}`,
            onChunk: (text) => {
              result.textContent += text
            }
          }
        )
      })
    </script>
  </body>
</html>
```

`window.cherry` и `cherry` ссылаются на один и тот же набор интерфейсов хоста, SDK подключать не нужно. Мини-приложение может отправлять только текстовые сообщения; пока не поддерживаются ввод изображений или вызовы инструментов. Оно лишь указывает, использовать `default` или `quick` слот, и не получает имя модели, информацию о провайдере или API Key.

### Упаковка и тестирование

1. Проверьте `manifest.json` находится в корне проекта, а файл входа совпадает с `entry` .
2. Сожмите архив внутри каталога проекта; в macOS или Linux можно использовать:

```bash
zip -r ../my-writer.miniapp . -x '.*' -x '__MACOSX/*'
```

В Windows PowerShell сначала создайте ZIP, затем переименуйте его в `.miniapp` расширение:

```powershell
Compress-Archive -Path .\* -DestinationPath ..\my-writer.zip
Rename-Item ..\my-writer.zip my-writer.miniapp
```

3. В области установки【Локальные мини-приложения】Cherry Studio выберите созданный `my-writer.miniapp`。
4. Убедитесь, что на странице установки запрашиваются только ожидаемые разрешения, затем после установки откройте и проверьте ввод, AI-вывод, сообщения об ошибках и состояние после повторного входа.
5. Если нужна отладка, откройте【Инструменты разработчика】на панели мини-приложения и проверьте ошибки страницы и запросы, заблокированные песочницей.

{% hint style="warning" %}
Не архивируйте весь папочный проект из внешнего каталога; убедитесь, что в корне архива напрямую виден `manifest.json`Cherry Studio также может распознавать архивы, упакованные в одну вложенную папку, но четкая структура корня проще для поиска ошибок.
{% endhint %}

## Ожидаемый результат

После установки вы должны увидеть новый значок в сетке【Мини-приложения】. Откройте его, введите текст и нажмите кнопку — в области результата будет постепенно появляться текст, возвращаемый моделью. Щелкнув правой кнопкой мини-приложение и выбрав【Просмотреть подробности】, можно увидеть его разрешение【AI-возможности】, используемый слот модели и последние записи вызовов.

Если установка прошла успешно, но AI недоступен, сначала проверьте модель в【Просмотреть подробности】→【Настройки】, затем проверьте в【Разрешения】, разрешены ли【AI-возможности】→【Чат】.

## Ключевые скриншоты

<figure><img src="https://3765361039-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Ut5BptC3t8CtSU1UWpM%2Fuploads%2Fgit-blob-ceba627dd766df1bcb0baa130442dd777e8426bd%2Fgenerative-mini-app-launchpad.png?alt=media" alt="启动台中的生成式小程序入口"><figcaption><p>точка входа【Генеративные мини-приложения】в Лаунчпаде.</p></figcaption></figure>

1. Нажмите【Генеративные мини-приложения】, чтобы открыть панель【Добавить мини-приложение】.

<figure><img src="https://3765361039-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Ut5BptC3t8CtSU1UWpM%2Fuploads%2Fgit-blob-27f5a4e70aba636ed033f23f658a9b5cc43c1ce8%2Fgenerative-mini-app-install.png?alt=media" alt="本地小程序安装面板中的文件和网址安装入口"><figcaption><p>Локальные мини-приложения поддерживают установку из файла или по URL.</p></figcaption></figure>

1. Перетащите `.miniapp` пакет или нажмите【Выбрать файл…】.
2. Также можно указать HTTPS-URL установки, предоставленный разработчиком.

<figure><img src="https://3765361039-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Ut5BptC3t8CtSU1UWpM%2Fuploads%2Fgit-blob-520ed8e91e1e9cfe2ba3322b88d99041eaedd4f0%2Fgenerative-mini-app-permissions.png?alt=media" alt="本地小程序详情中的权限页"><figcaption><p>На странице【Разрешения】перечислены возможности хоста, к которым мини-приложение получило доступ.</p></figcaption></figure>

1. Проверьте, соответствуют ли назначению мини-приложения разрешения на【AI-возможности】, а также на сеть, буфер обмена, файлы, данные и уведомления.

<figure><img src="https://3765361039-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0Ut5BptC3t8CtSU1UWpM%2Fuploads%2Fgit-blob-42ee78e313fab6bfc87286060fd027d7ed2458bd%2Fgenerative-mini-app-models.png?alt=media" alt="本地小程序详情中的默认模型和快速模型设置"><figcaption><p>Управляйте слотами AI-моделей в подробностях мини-приложения.</p></figcaption></figure>

1. 【Модель по умолчанию】обрабатывает основные AI-запросы мини-приложения; если поле пустое, используется глобальная модель по умолчанию.
2. 【Быстрая модель】обрабатывает запросы с низкой задержкой, заданные мини-приложением; если поле пустое, используется глобальная быстрая модель.

{% hint style="info" %}
Фактический интерфейс и вывод мини-приложения определяются самим мини-приложением; на изображении выше используется официальный пример тестирования возможностей, чтобы показать расположение разрешений и управления моделями после установки.
{% endhint %}

## Описание конфигурации

| Параметр конфигурации | Значение по умолчанию продукта                                                              | Рекомендуемая отправная точка                                                  | Назначение                                                               | Сценарий применения                                           | Примечания                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Источник установки    | —                                                                                           | Для первого теста используйте локальный `.miniapp` файл                        | определяет, устанавливать из локального пакета или по HTTPS-URL          | личное тестирование, распространение в команде                | Сначала проверьте издателя, исходный код и разрешения стороннего мини-приложения                            |
| AI-разрешения         | объявляются мини-приложением; дополнительные разрешения по умолчанию отмечены при установке | предоставляйте только те разрешения, которые необходимы для выполнения функции | Разрешить вызов `cherry.ai.chat()`                                       | всех AI-функций                                               | Обязательные разрешения нельзя отменить отдельно; если больше не доверяете, следует удалить мини-приложение |
| Модель по умолчанию   | следует глобальной модели по умолчанию                                                      | используйте проверенную вами работающую модель чата                            | обрабатывает основные задачи генерации и анализа                         | длинные тексты, сложные инструкции, структурированный вывод   | Вызовы будут учитываться в использовании соответствующего сервиса модели                                    |
| Быстрая модель        | следует глобальной быстрой модели                                                           | выбирайте для коротких задач более быструю модель                              | обрабатывает задачи с низкой задержкой                                   | изменить заголовок, дополнить, классифицировать, извлечь теги | Мини-приложение должно явно выбрать `quick` чтобы использовать                                              |
| Режим рассуждения     | если мини-приложение не передает, то выключен                                               | для обычного переписывания сначала выключите                                   | позволяет моделям с поддержкой рассуждения сначала выполнить рассуждение | сложный анализ, планирование                                  | модели без поддержки переключения проигнорируют этот пункт                                                  |
| Стиль темы            | следует светлой/темной теме Cherry Studio                                                   | Подключение `/__cherry/theme.css`                                              | использует предоставляемые хостом переменные цветов                      | весь настраиваемый интерфейс                                  | внешние ресурсы CDN будут заблокированы песочницей, их нужно упаковывать в приложение                       |

### Какие еще возможности можно вызвать

| возможностями         | Назначение                                                                            | Способ объявления                                   |
| --------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------- |
| `cherry.storage`      | сохраняет строковые настройки и состояние                                             | `storage.*` или конкретные методы                   |
| `cherry.file`         | сохраняет, читает и экспортирует файлы в собственной песочнице мини-приложения        | `file.*` или конкретные методы                      |
| `cherry.notification` | отправляет системные уведомления через Cherry Studio                                  | `notification.show`                                 |
| `cherry.network`      | доступ к HTTPS-доменам, объявленным в манифесте                                       | `network.fetch`и заполните `network` список доменов |
| `cherry.clipboard`    | чтение и запись обычного текста, когда мини-приложение видно и имеет фокус клавиатуры | `clipboard.read`、`clipboard.write`                  |
| `cherry.app`          | читает версию приложения, язык и текущие разрешения                                   | не нужно объявлять                                  |

Локальные мини-приложения не могут напрямую использовать `localStorage`、браузерный `fetch`、Cookie, всплывающие окна или внешние CDN. Для сохранения состояния используйте `cherry.storage`; для подключения к сети используйте `cherry.network.fetch` и объявляйте в манифесте разрешенные домены.

## Сценарии использования

| Сценарий                                | Входные данные                           | Что делает мини-приложение                                                                                        | Критерий готовности                                                           |
| --------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Письмо и переписывание                  | Черновик, тон и требование к объему      | генерируйте основной текст с【Моделью по умолчанию】, а【Быстрой моделью】давайте варианты заголовков                 | сохраняет исходный смысл и позволяет быстро переключать разные формулировки   |
| Обработка протоколов встреч             | вставленная запись встречи               | извлекать выводы, ответственных и сроки, выводя в фиксированном формате                                           | у каждого действия есть поля ответственного и срока                           |
| Многоязычный перевод                    | исходный текст, целевой язык и глоссарий | зафиксируйте термины и формат вывода в системном сообщении и показывайте перевод потоком                          | собственные имена единообразны, структура абзацев сохранена                   |
| Извлечение структурированной информации | контракт, резюме или текст отзывов       | требуйте от модели возвращать результат по фиксированным полям, а затем проверяйте пропущенные пункты на странице | все обязательные поля заполнены, а аномальный контент выделен                 |
| Учебная практика                        | Конспекты, типы задач и сложность        | генерирует задания, подсказки и объяснения, а прогресс сохраняет в песочнице данных                               | после повторного открытия можно продолжить прошлую практику                   |
| Вертикальный рабочий процесс            | Командные шаблоны и бизнес-правила       | объединяет ввод, обработку AI, ручное подтверждение и экспорт в одном интерфейсе                                  | повторяющиеся задачи могут стабильно выполняться по одному и тому же процессу |

{% hint style="warning" %}
Результат генеративного мини-приложения по-прежнему создается выбранной моделью. Для высокорисковых областей, таких как медицина, право и финансы, а также для данных, влияющих на официальные операции, обязательна проверка квалифицированным специалистом.
{% endhint %}

## Частые вопросы

<details>

<summary>Почему я ввел URL веб-страницы, но не могу вызвать Cherry AI?</summary>

【Сайт】только открывает веб-страницу, но не внедряет в нее `window.cherry`。Сделайте приложение в виде `.miniapp` пакета и установите его как【Локальное мини-приложение】.

</details>

<details>

<summary>Может ли мини-приложение видеть мой API Key или провайдера модели?</summary>

Нет. Мини-приложение запрашивает только слоты【Модель по умолчанию】или【Быстрая модель】. Cherry Studio выполняет вызов от его имени и не раскрывает мини-приложению имя модели, информацию о провайдере или API Key.

</details>

<details>

<summary>Почему после установки сообщается, что AI недоступен?</summary>

Сначала откройте【Просмотреть подробности】→【Настройки】и убедитесь, что в соответствующем слоте модели есть доступная модель; затем в【Разрешения】проверьте, разрешены ли【AI-возможности】→【Чат】. Если разрешение является обязательным, но вы больше не доверяете этому приложению, просто удалите его.

</details>

<details>

<summary>Как проверить, к каким возможностям обращалось мини-приложение?</summary>

Откройте【Просмотреть подробности】→【Журнал активности】. Здесь фиксируются внешние вызовы AI, сети, буфера обмена, экспорта файлов и т. п., а также отклоненные вызовы, но не записываются подсказки, ответы модели, содержимое буфера обмена или содержимое файлов.

</details>

<details>

<summary>В чем разница между обновлением, откатом и очисткой данных?</summary>

Обновление сохраняет данные песочницы и при добавлении новых разрешений снова запрашивает подтверждение; после обновления можно откатиться к предыдущей версии. Очистка данных удаляет сохраненные этим мини-приложением данные и файлы, но само приложение остается; удаление одновременно удаляет приложение, авторизацию и данные.

</details>

## Справочные материалы

* [Документация по разработке Cherry Studio MiniApps и список сообщества](https://github.com/CherryHQ/cherry-studio-miniapps/blob/main/README.zh-CN.md)
* [Официальная справочная документация MiniApp](https://github.com/CherryHQ/cherry-studio/tree/main/docs/references/mini-app)
* [Формат манифеста](https://github.com/CherryHQ/cherry-studio/blob/main/docs/references/mini-app/manifest.md)
* [Интерфейсы возможностей](https://github.com/CherryHQ/cherry-studio/blob/main/docs/references/mini-app/capabilities.md)
* [Упаковка, обновление и удаление](https://github.com/CherryHQ/cherry-studio/blob/main/docs/references/mini-app/packaging.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cherryai.com.cn/docs/russian/cherry-studio/preview/app/generative-mini-apps.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.