> 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/zhong-wen-fan-ti/cherry-studio/preview/app/generative-mini-apps.md). # 生成式小程式 製作、安裝同使用可調用 Cherry Studio AI 能力嘅自定義小程式 生成式小程式係運行喺 Cherry Studio【小程式】入面嘅本地 Web 應用。佢嘅介面同業務流程由你自訂，並可透過 `window.cherry` 調用 Cherry Studio 已配置嘅 AI 模型，將一個通用模型變成寫作助手、資訊擷取器、學習工具，或者專用業務應用。 佢同普通網站型小程式嘅分別唔係喺外觀，而係能力來源：網站型小程式淨係打開一個 URL；生成式小程式需要打包成 `.miniapp`，安裝並獲得授權之後，先可以調用 Cherry 嘅 AI、沙盒數據、檔案、通知、網絡同剪貼板能力。 {% hint style="info" %} Cherry Studio 提供運行環境、授權機制同 AI 介面。你可以自己編寫小程式，亦可以等 AI 編程工具先生成 HTML、CSS 同 JavaScript，再按本頁說明打包安裝。 {% endhint %} ## 目標同前置條件 完成本頁之後，你可以： * 安裝同使用其他人提供嘅生成式小程式； * 由一個簡單需求製作自己嘅 `.miniapp` 包； * 等小程式調用 Cherry Studio 嘅【預設模型】或者【快速模型】； * 檢查權限、活動日誌、儲存、更新同卸載狀態。 使用現成小程式只需要準備可信嘅 `.miniapp` 檔案或者安裝網址。自己製作時，仲要可以編輯網頁檔案同建立 ZIP 壓縮包；如果要測試 AI 功能，請先喺 Cherry Studio 入面配置一個可用嘅對話模型。 ## 術語 | 術語 | 介面名稱 | 本頁含義 | | ------ | ------------- | ------------------------------------------ | | 生成式小程式 | 【生成式小程式】 | 可自訂介面同流程，並可調用 Cherry Studio AI 能力嘅小程式 | | 本地小程式 | 【本地小程式】 | 以 `.miniapp` 包安裝、喺獨立沙盒入面運行嘅小程式類型 | | 網站型小程式 | 【網站】 | 透過 URL 打開嘅網頁，唔具備 `window.cherry` 能力 | | 權限 | 【權限】 | 小程式安裝時申請、由用戶審閱嘅能力範圍 | | 模型槽位 | 【預設模型】、【快速模型】 | 由用戶為呢個小程式選擇嘅兩個模型位置，小程式睇唔到服務商、模型名稱同 API Key | ## 操作路徑 使用現成小程式：`【啟動台】→【生成式小程式】→【本地小程式】→選擇檔案或輸入安裝網址→審閱權限→【安裝】` 亦可以由小程式頁入去：`【啟動台】→【小程式】→右上角【添加小程式】→【本地小程式】` 管理已安裝小程式：`【小程式】→右鍵目標小程式→【查看詳情】` ## 操作步驟 ### 安裝同第一次使用 {% stepper %} {% step %} ### 打開安裝入口 喺【啟動台】撳【生成式小程式】，或者入去【小程式】之後撳右上角嘅【添加小程式】。喺彈出嘅面板入面切換去【本地小程式】。 {% endstep %} {% step %} ### 選擇安裝來源 將一個 `.miniapp` 包拖入安裝區，或者撳【選擇檔案…】。如果開發者提供咗 HTTPS 安裝網址，亦可以貼上網址之後撳【載入】。 {% 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": "輸入一段文字，調用 Cherry Studio 嘅 AI 模型進行改寫。", "version": "1.0.0", "entry": "index.html", "permissions": ["ai.chat"] } ``` `id` 建議使用自己控制嘅反向域名格式，只可以包含小寫字母、數字、點同連字符。`com.cherrystudio.*` 係官方保留範圍，唔好使用。 再喺 `index.html` 入面透過全局對象 `cherry` 調用 AI。下面例子會先確認【預設模型】可用，再將流式文字逐段顯示出嚟： ```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 能力】→【對話】。

## 關鍵截圖


启动台中的生成式小程序入口
啟動台入面嘅【生成式小程式】入口。


1. 撳【生成式小程式】打開【添加小程式】面板。


本地小程序安装面板中的文件和网址安装入口
本地小程式支援由檔案或者網址安裝。


1. 拖入 `.miniapp` 包或者撳【選擇檔案…】。
2. 亦可以填寫開發者提供嘅 HTTPS 安裝網址。


本地小程序详情中的权限页
【權限】頁列出小程式獲准調用嘅宿主能力。


1. 核對【AI 能力】以及網絡、剪貼板、檔案、數據同通知等授權係咪符合小程式用途。


本地小程序详情中的默认模型和快速模型设置
喺小程式詳情入面管理 AI 模型槽位。


1. 【預設模型】處理小程式嘅主要 AI 請求，留空時會跟隨全局預設模型。
2. 【快速模型】處理小程式指定嘅低延遲請求，留空時會跟隨全局快速模型。

{% hint style="info" %}
小程式嘅實際介面同輸出由小程式本身決定；上圖使用官方能力測試示例說明安裝後嘅權限同模型管理位置。
{% endhint %}

## 配置說明

| 配置項   | 產品預設值                 | 建議起點                     | 作用                      | 適用場景           | 注意事項                      |
| ----- | --------------------- | ------------------------ | ----------------------- | -------------- | ------------------------- |
| 安裝來源  | —                     | 首次測試使用本地 `.miniapp` 檔案   | 決定由本地包定係 HTTPS 網址安裝     | 自用測試、團隊分發      | 第三方小程式先核對發布者、原始碼同權限       |
| 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 %}

## 常見問題




點解我填咗一個網頁 URL，卻唔可以調用 Cherry AI？

【網站】只負責打開網頁，唔會向網頁注入 `window.cherry`。請將應用製作成 `.miniapp` 包，並由【本地小程式】安裝。







小程式睇得到我嘅 API Key 或模型服務商嗎？

唔得。小程式只會請求【預設模型】或者【快速模型】槽位。Cherry Studio 代為執行調用，唔會將模型名稱、服務商資訊或者 API Key 暴露畀小程式。







點解安裝之後會提示 AI 唔可用？

先打開【查看詳情】→【設定】，確認對應模型槽位有可用模型；再去【權限】確認【AI 能力】→【對話】已經授權。如果權限屬於必需權限但你唔再信任呢個應用，請直接卸載。







點樣確認小程式調用了邊啲能力？

打開【查看詳情】→【活動日誌】。呢度會記錄 AI、網絡、剪貼板、檔案導出等對外調用同被拒絕嘅調用，但唔會記錄提示詞、模型回覆、剪貼板內容或者檔案內容。







更新、回滾同清除數據有咩分別？

更新會保留沙盒數據，並喺新增權限時再次請求確認；更新後可以回滾到上一個版本。清除數據會刪除該小程式保存嘅數據同檔案，但保留應用；卸載會同時刪除應用、授權同數據。




## 參考資料

* [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/zhong-wen-fan-ti/cherry-studio/preview/app/generative-mini-apps.md?ask=&goal=
```

`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.