生成式小程式

製作、安裝同使用可調用 Cherry Studio AI 能力嘅自訂小程式

生成式小程式係運行喺 Cherry Studio【小程式】入面嘅本地 Web 應用。佢嘅介面同業務流程由你自訂，並可透過 window.cherry 調用 Cherry Studio 已配置嘅 AI 模型，將一個通用模型變成寫作助手、資訊擷取器、學習工具，或者專用業務應用。

佢同普通網站型小程式嘅分別唔係喺外觀，而係能力來源：網站型小程式淨係打開一個 URL；生成式小程式需要打包成 .miniapp，安裝並獲得授權之後，先可以調用 Cherry 嘅 AI、沙盒數據、檔案、通知、網絡同剪貼板能力。

Cherry Studio 提供運行環境、授權機制同 AI 介面。你可以自己編寫小程式，亦可以等 AI 編程工具先生成 HTML、CSS 同 JavaScript，再按本頁說明打包安裝。

目標同前置條件

完成本頁之後，你可以：

• 安裝同使用其他人提供嘅生成式小程式；
• 由一個簡單需求製作自己嘅 .miniapp 包；
• 等小程式調用 Cherry Studio 嘅【預設模型】或者【快速模型】；
• 檢查權限、活動日誌、儲存、更新同卸載狀態。

使用現成小程式只需要準備可信嘅 .miniapp 檔案或者安裝網址。自己製作時，仲要可以編輯網頁檔案同建立 ZIP 壓縮包；如果要測試 AI 功能，請先喺 Cherry Studio 入面配置一個可用嘅對話模型。

術語

術語	介面名稱	本頁含義
生成式小程式	【生成式小程式】	可自訂介面同流程，並可調用 Cherry Studio AI 能力嘅小程式
本地小程式	【本地小程式】	以 .miniapp 包安裝、喺獨立沙盒入面運行嘅小程式類型
網站型小程式	【網站】	透過 URL 打開嘅網頁，唔具備 window.cherry 能力
權限	【權限】	小程式安裝時申請、由用戶審閱嘅能力範圍
模型槽位	【預設模型】、【快速模型】	由用戶為呢個小程式選擇嘅兩個模型位置，小程式睇唔到服務商、模型名稱同 API Key

操作路徑

使用現成小程式：【啟動台】→【生成式小程式】→【本地小程式】→選擇檔案或輸入安裝網址→審閱權限→【安裝】

亦可以由小程式頁入去：【啟動台】→【小程式】→右上角【添加小程式】→【本地小程式】

管理已安裝小程式：【小程式】→右鍵目標小程式→【查看詳情】

操作步驟

安裝同第一次使用

1

打開安裝入口

喺【啟動台】撳【生成式小程式】，或者入去【小程式】之後撳右上角嘅【添加小程式】。喺彈出嘅面板入面切換去【本地小程式】。

2

選擇安裝來源

將一個 .miniapp 包拖入安裝區，或者撳【選擇檔案…】。如果開發者提供咗 HTTPS 安裝網址，亦可以貼上網址之後撳【載入】。

3

審閱權限

安裝確認頁會顯示小程式名稱、版本、說明同全部權限。必需權限唔可以取消；可選權限預設會剔選，你可以喺安裝前取消，亦可以安裝後再調整。

只有小程式用途同權限相符、來源可信嘅時候先好繼續。需要 AI 嘅小程式通常會顯示【AI 能力】→【對話】。

4

安裝並打開

撳【安裝】。安裝完成之後，小程式會出現在【小程式】格仔入面；撳圖示就可以運行。

為小程式選擇 AI 模型

1. 喺【小程式】格仔入面右鍵目標小程式，選擇【查看詳情】。
2. 切換去【設定】，搵【AI 模型】。
3. 根據小程式用途設定【預設模型】同【快速模型】。留空時會分別跟隨 Cherry Studio 嘅全局預設模型同全局快速模型。
4. 重新打開小程式並觸發一次 AI 操作。如果冇可用模型，小程式應該提示 AI 暫時不可用。

【預設模型】適合長文生成、複雜分析等主要任務；【快速模型】適合標題建議、短句改寫、標籤擷取等低延遲任務。最終用邊個槽位由小程式設計決定。

製作一個最小版本

生成式小程式本質上係一個靜態網頁項目。最小目錄只需要兩個檔案：

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

先建立 manifest.json，聲明應用資訊同 ai.chat 權限：

{
  "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。下面例子會先確認【預設模型】可用，再將流式文字逐段顯示出嚟：

<!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 可以用：

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

Windows PowerShell 可以先生成 ZIP，再改做 .miniapp 副檔名：

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

1. 喺 Cherry Studio 嘅【本地小程式】安裝區選擇生成嘅 my-writer.miniapp。
2. 確認安裝頁只會申請預期權限，安裝後打開並測試輸入、AI 輸出、異常提示同重新進入之後嘅狀態。
3. 需要調試時，打開小程式工具欄入面嘅【開發者工具】，睇頁面錯誤同被沙盒阻止嘅請求。

唔好由外層目錄壓縮成個項目資料夾，確保壓縮包根目錄可以直接睇到 manifest.json。Cherry Studio 都可以識別只有一層目錄包住嘅壓縮包，但清晰嘅根目錄結構更容易排錯。

預期結果

安裝完成後，你應該可以喺【小程式】格仔入面見到新圖示。打開之後，輸入文字並撳按鈕，結果區會持續出現模型返回嘅文字。右鍵小程式入去【查看詳情】，可以睇到佢申請嘅【AI 能力】權限、所用模型槽位同最近嘅調用記錄。

如果安裝成功但 AI 唔可用，先檢查【查看詳情】→【設定】入面嘅模型，再檢查【權限】入面係咪允許【AI 能力】→【對話】。

關鍵截圖

啟動台入面嘅【生成式小程式】入口。

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

本地小程式支援由檔案或者網址安裝。

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

【權限】頁列出小程式獲准調用嘅宿主能力。

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

喺小程式詳情入面管理 AI 模型槽位。

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

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

配置說明

配置項	產品預設值	建議起點	作用	適用場景	注意事項
安裝來源	—	首次測試使用本地 .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 處理、人工確認同導出組合喺一個介面	重複任務可以按同一流程穩定完成

生成式小程式嘅結果仍然由所選模型生成。醫療、法律、財務等高風險用途，以及會影響正式業務嘅數據，必須由具備相應資格嘅人覆核。

常見問題

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

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

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

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

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

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

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

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

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

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

參考資料

• Cherry Studio MiniApps 開發文檔同社群列表
• MiniApp 官方參考文檔
• 清單格式
• 能力介面
• 打包、更新同卸載