Pomelo 小幫手（pomelo-assistant）設計與評估

最後更新：2026-10-19（0.25）

目前做到的（第一步：文字版）

• 叫出方式：Super+Shift+Space、搜尋輸入問題後選「問小幫手」、啟動器的「小幫手」。
• 會做的事（工具清單是寫死的，不能執行任意指令）： 開啟程式、切換／關閉／縮小視窗、在家目錄找檔案、開啟檔案（只限家目錄與外接裝置）、 音量／靜音、亮度、深色模式、勿擾模式、Wi-Fi、藍牙、鎖定螢幕、開啟設定頁、 查詢電腦狀態（磁碟、記憶體、電量、CPU）、幾分鐘後提醒、用瀏覽器搜尋（天氣、新聞等）。
• 0.15 起能「動手做」的工具（仍然是寫死的清單，沒有任意指令）： · open_url：直接開網址，只接受 http／https（沒寫的會補 https://），不開 file:、javascript: 等。 · create_folder：在家目錄或 /media 建資料夾；已存在就不動。 · create_file：建新的文字檔並寫入內容（上限約 60 KB）。建立前一定先跳出確認視窗 （pomelo-assistant --confirm，另一個行程，顯示位置與內容，60 秒沒按就當作不要）， 只能建新檔、絕不覆蓋（O_EXCL）。 · 路徑規則：相對路徑從家目錄算；不准有 ..、不准隱藏檔或隱藏資料夾（.ssh、.bashrc…）； 只能在家目錄或 /media；上層資料夾若是捷徑（symlink）指到範圍外也拒絕（在問使用者之前就檢查）。 · copy_item、move_item（含改名）、trash_item：同樣先跳確認視窗（顯示來源與目的地），目的地已存在就拒絕、 不覆蓋；刪除只會丟垃圾桶（有 gio 用 gio trash，沒有就依 freedesktop 規範自己放進 ~/.local/share/Trash，可還原）； 不能對整個家目錄操作、不能把資料夾放進自己裡面；複製用 cp -a（捷徑照原樣複製，不會跟進去讀別處）。 跨磁碟的移動不支援（請改用複製）。 · get_weather：向 wttr.in 查城市現在的天氣（只會把城市名稱傳出去）。 · web_search 的結果：小幫手看不到搜尋頁內容，工具回應與提示都要求它不能猜答案（0.15 的示範裡它曾編出 錯誤的氣溫，0.16 修正；天氣改用 get_weather）。 · 還沒做：控制瀏覽器（登入、填表）。
• 示範動畫：docs/demo/assistant-demo.gif（開網頁、建資料夾、建檔案、問星期幾、問天氣；2B 模型，約 2 分鐘）。
• 小幫手知道「現在幾點、正在用哪個視窗、開著哪些視窗」：由視窗管理員的資訊產生文字附在問題後面， 不需要截圖，所以很快。

架構

pomelo-assistant（對話視窗，C＋cairo）
   │  HTTP over UNIX socket（$XDG_RUNTIME_DIR/pomelo-assistant.sock，不開網路埠）
   ▼
pomelo-assistant --serve（看管程式）── llama-server（llama.cpp，nice 5）
                                         └ Qwen3-VL Instruct GGUF Q4_K_M

• 執行環境與模型第一次使用時下載到 ~/.local/share/pomelo/assistant/，版本固定，下載後檢查 SHA256：
  • llama.cpp b11553（CPU 版，17 MB）
  • 輕量：Qwen3-VL-2B-Instruct Q4_K_M（1.1 GB）／標準：Qwen3-VL-4B-Instruct Q4_K_M（2.5 GB）
  • 記憶體 12 GB 以下預設用輕量版。
• 對話視窗一打開就在背景載入模型並「預熱」（先算好系統提示＋工具說明，放進快取）， 使用者打字的同時就準備好了。
• 閒置 10 分鐘（可調）自動卸載模型，把記憶體還給其他程式。
• 選用 Qwen3-VL：同一個模型之後也能「看」畫面或攝影機（再載入 0.45 GB 的 mmproj 即可），不用另外裝看圖模型。

實測（i5-11400，限制 4 個執行緒模擬一般 4 核心筆電，2B 模型）

已知問題：

• 2B 偶爾會冒出簡體字（例如「周杰伦」）；回答有時多一句客套話。
• 2B 對「幾分鐘後提醒我」「螢幕太亮了」這類比較間接的要求，約三成會只「說」要做、沒有真的呼叫工具。 試過兩種補救都沒效：事後提醒它「你沒有呼叫工具」（它會再說一次已經做了）、在對話前面放範例（錯的題目換了，總數沒變）。 4B 幾乎沒有這個問題，所以記憶體夠的電腦建議選標準版。

如果從開機核心到 Xorg 都自己做，會讓小幫手更快嗎？

幾乎不會。 語言模型的速度幾乎完全取決於兩件事：CPU（或 GPU）的運算能力，以及記憶體頻寬。 核心和 Xorg 都不在這條路上——模型在算的時候，時間是花在矩陣乘法，不是系統呼叫或繪圖。 Pomelo 桌面本身只佔約 15 MB 記憶體，已經沒有什麼可以再省的。自己維護核心與 X 的成本（安全性更新、 硬體相容性）很高，換來的加速估計不到 5%。

真正有效的做法（依效果排序）：

1. 快取與預熱（已做）：工具說明約 1500 個 token，第一次要 6～8 秒；快取後每次只算新增的幾十個字。
2. 記憶體是不是雙通道：產生文字的速度跟記憶體頻寬成正比，單通道（只插一條記憶體）的筆電大約慢一半。 這是硬體建議，軟體改不了。
3. 用內建顯示晶片加速：llama.cpp 有 Vulkan 版（Intel Iris Xe、AMD Radeon 680M/780M 都能用）， 讀入提示的速度可以快 2～5 倍；Intel 也可以用 OpenVINO 版（可用到 iGPU 與 NPU）。 之後可以讓小幫手自動偵測、自動下載適合的版本。
4. 少一次推論（0.25 已做，見下方「快速通道與少一次推論」）：開程式、調音量這類動作，直接用工具的結果回覆（「已開啟 Firefox」）， 不必再請模型組一句話，等待時間大約減半。
5. 逐字顯示（串流）：總時間不變，但第一個字更早出現，感覺快很多。
6. 系統面的小調整：CPU 效能模式、避免模型被換到 swap（zram／mlock）、模型放在 SSD。 這些用設定就做得到，不需要自己編核心。新硬體的 NPU 驅動要比較新的核心，用 Ubuntu 的 HWE 核心即可。

跑在樹莓派上的可能性

Pomelo 桌面

• 可行。 Pomelo 全部是 C＋Xlib＋cairo，在 arm64 上直接編譯即可；常駐只要十幾 MB，Pi 4（2 GB）也夠用。
• 需要先做 arm64 套件（之前在 x86 上交叉編譯失敗，改用樹莓派本機編譯，或用 QEMU 的 arm64 容器編譯）。
• Raspberry Pi OS（Bookworm 以後）預設用 Wayland，Pomelo 是 X11 程式，要在 raspi-config 切回 X11； 或改裝 Ubuntu for Raspberry Pi。
• 攝影機：USB 攝影機可以直接用；Raspberry Pi 官方攝影機模組走 libcamera，視訊設定頁要另外支援。

小幫手（以下是推估，還沒有實機量過）

建議：

• Pi 5 8 GB＋主動散熱風扇＋NVMe SSD（從 SD 卡載入 1.1 GB 模型要 20～30 秒，SSD 只要幾秒）。
• 預設用 2B 模型，並啟用「少一次推論」與串流顯示。
• 語音部分在 Pi 5 上可行：Piper 文字轉語音本來就是為樹莓派設計的；語音辨識用 whisper.cpp base 或 SenseVoice-Small。
• 加速卡：樹莓派的 AI HAT+（Hailo-8／8L）是給影像辨識用的，不能跑語言模型； 能跑語言模型的加速卡（例如 Hailo-10 系列）需要它自己的軟體與轉換過的模型，要再查證最新的支援情況。
• llama.cpp 有官方的 arm64 Linux 版本，可以沿用同一套下載與驗證流程。

桌面上的小柚（0.12 起：3D Q 版機器人）

小幫手啟動後不再是一個對話視窗，而是一隻會在桌面上走動的小機器人「小柚」（0.21 以前叫「柚子」；外文介面叫 Pomi，日文ポミ、韓文포미）：

• 外觀：純軟體的小型 3D 繪製器（pomelo-assistant/robot.c，約 500 行），不需要 OpenGL 或 GPU。 超橢球、膠囊、圓柱組成的網格（約 3700 個三角形）→ 透視投影 → 有深度緩衝的掃描線填色 → 卡通式三段打光 → 用深度差與部位差畫黑色輪廓線 → 2 倍超取樣後縮小。 一張 163×189 的畫面約 2.5 毫秒；走動時每秒 20 張，閒著時幾乎不重畫，CPU 低於 1%。 眼睛、嘴巴、臉頰是貼在頭部曲面上的「貼片」，所以頭轉動時會跟著轉；眼睛與耳機的顏色預設跟著系統的強調色。
• 視窗：_NET_WM_WINDOW_TYPE_DOCK 的無邊框視窗，Pomelo 的視窗管理員會讓它保持在最上面、 不給焦點、全螢幕時自動讓開；用 Shape 擴充裁成機器人的形狀，形狀外的地方點下去會穿透到底下的視窗。 沒有合成器也能用（Pomelo 本來就不跑合成器）。
• 行為（pet.c）：平常在工作區（扣掉選單列與 Dock）裡隨機挑目標走過去、停一下、看看四周、眨眼， 滑鼠靠近時會看著游標；在螢幕上越高（越遠）畫得越小。 只有在喊牠的時候才停下來：點牠、Super+Shift+Space、搜尋的「問小幫手」，或指令列 pomelo-assistant 問題——第二個程式會透過 root 視窗屬性 _POMELO_ASSISTANT 找到正在跑的小柚， 把問題放進 _POMELO_ASSISTANT_ASK 屬性再送 ClientMessage，自己就結束。 停下來時面向使用者、天線亮起、頭上出現對話泡泡（override-redirect 視窗，支援輸入法）， 思考時眼睛往上看、天線閃爍，回答一個字一個字出現、嘴巴跟著動，講完露出笑臉； 按 Esc、再點牠一下、或 30 秒沒理牠就收起泡泡繼續走。拖曳可以把牠搬走（手會舉起來），右鍵有選單。
• 設定（系統設定 → 小幫手）：assistant.pet（關掉就回到一般對話視窗 --window）、 assistant.autostart（登入時由 pomelo-session 用 --autostart 叫出，模型已下載才會出現）、 assistant.wander（自由走動）、assistant.size（100／130／170 像素）。改了會即時套用。
• 測試：scratchpad/robot/rt.c 可以把幾個姿勢畫成 PNG 檢查外觀，不用開 X。

樣式與深色模式（0.21）

小幫手設定 →「樣式」：

• 六種配色：經典白、柚子黃、薄荷綠、櫻花粉、天空藍、太空黑。設定頁的縮圖是用同一個 3D 繪製器即時畫的， 選到的那隻會笑。每種配色都有淺色與深色兩個版本（robot.c 的 skins[][2]：身體、手腳、腳、臉上的螢幕、 臉頰、輪廓線六個顏色）。深色版是「夜間版」：顏色壓暗但比一般深色桌布亮，放在深色背景上仍看得清楚輪廓。
• 外觀：跟系統（系統切到深色模式時自動換成深色的小柚）／一律淺色／一律深色。
• 眼睛顏色：預設跟系統強調色；關掉後可以從七個顏色裡挑。
• 設定鍵：assistant.style（0～5）、assistant.look（0 跟系統、1 淺色、2 深色）、assistant.eye_follow、 assistant.eye_color（#rrggbb）。桌面上的小柚每個畫面都重新讀，改了立刻換。

聲音（0.21）

音效（sound.c）：被叫出來（嗶嗶↑）、回答好了（Do Mi Sol）、出錯（嗚嗚↓）、被抱起來（咻↑）、 放下（啵↓）、回去休息（Sol Mi Do）。每次播放時用程式即時合成一段 22050 Hz 的 WAV（幾 KB），寫進 memfd， 交給 paplay／pw-play／aplay 播放，不需要任何音效檔。三種音色：電子嗶嗶（帶一點奇次諧波）、 鈴聲（正弦加上不協和泛音、慢慢消失）、泡泡（每個音往上滑）。音量直接算進波形裡，每種播放程式都一樣。

把回答念出來（預設關閉）：回答出現時念出來，念的時候嘴巴跟著動、不會走掉；問新問題或關掉泡泡就停。 念之前會去掉網址、Markdown 符號與表情符號。可以選嗓音（小柚＝高音／普通／低沉）與語速（慢／正常／快）。

朗讀用哪個程式：

• 下載內容：Piper 2023.11.14-2（26 MB，GitHub）＋該語言的聲音（約 63 MB，Hugging Face rhasspy/piper-voices）， 跟 AI 模型一樣用 curl 續傳、sha256 驗證，放在 ~/.local/share/pomelo/assistant/voice/。
• 有 Piper 聲音的語言：中文（zh_CN-huayan，女聲、大陸口音；繁體字也念得對）、英、德、西、法、義、葡、俄、越。 只收舊版 C++ Piper 能用的聲音（piper_version 1.0.0）；韓文 kss 等較新的聲音要 Python 版 Piper，不能用。
• 為什麼不用 espeak-ng 念中文：Ubuntu 24.04 的 espeak-ng 1.51 有已知錯誤，普通話會把拼音的聲調數字 用英文念出來（「你好」念成 ni five three…），日文漢字也念不出來。Piper 內附的 espeak-ng 1.52 已經修好。 所以中文、日文、泰文不會退回 espeak-ng。
• 授權：Piper 是 MIT。聲音檔是各自的資料集授權，中文 huayan 的資料集標示為「授權不明」， 所以不放進 deb，由使用者自己開啟功能時下載（跟 AI 模型一樣）。要商業散布前需要另外確認，或換成授權清楚的聲音。
• 日文、泰文目前沒有能離線使用的語音（Piper 的日文、泰文聲音都要新版 Python 版 Piper）。

設定鍵：assistant.sfx、assistant.sfx_style（0 電子、1 鈴聲、2 泡泡）、assistant.volume（0～100，音效與朗讀共用）、 assistant.speak、assistant.voice（0 小柚、1 普通、2 低沉）、assistant.rate（0 慢、1 正常、2 快）。

快速通道與少一次推論（0.25）

使用者問：能不能訓練模型，讓簡單的事情不用「思考」？我們用的 Qwen3-VL Instruct 本來就沒有思考模式， 「思考中」就是模型實際在算的時間；而且開程式這類動作原本要跑兩次模型（決定動作、再產生回覆）。 訓練（LoRA 微調）可以讓更小的模型更準，但每句話仍要跑模型、工具一改就要重訓，所以先做兩件不用訓練的事：

快速通道（quick.c）：送出的句子先整理（去掉「請、幫我、一下、吧、好嗎」、全形轉半形、「三十五」轉 35）， 再比對固定句型，比對到就直接呼叫跟模型一樣的 run_tool()，不經過模型：

原則是寧可交給模型，也不要猜錯：「打開天氣網站」（不在清單裡的說法）、「打開上次那個檔案」、「螢幕太亮了」、 「明天天氣如何」、「音量調到 200」、不認得的地名、隱藏檔，都交給模型。模型還沒下載時，快速指令照樣能用。 pomelo-assistant --quick-test 從標準輸入一行一句，印出會怎麼處理（不執行）；測試句在 pomelo-assistant/quick-cases.tsv，make -C pomelo-assistant quick-test 會逐句比對（「打開文件裡的報價單」這類句子要在測試用的家目錄放對應的檔案）；測試句 149 句（115 句該走快速通道、34 句一定要交給模型）全部判斷正確， 判斷時間 0～4 毫秒（「打開瀏覽器」要問一次預設瀏覽器，約 0.15 秒）。設定：assistant.quick（預設開）。

少一次推論：模型決定的如果全是「動作」（開程式、開網址、調設定、建資料夾…）而且都成功，就直接用工具結果回答 （「已在瀏覽器開啟 …」），不再跑第二次模型；動作失敗（找不到程式）或是要整理資料的（找檔案、系統狀態）才跑第二次。 實測（2B，12 執行緒）：「打開氣象網站」（加進清單之前）一次推論 2.7 秒就完成；「打開 Zorblax Studio」（不存在）照樣跑兩次， 第二次讓模型解釋找不到。

關閉程式、閒聊、在文字檔加字（0.28）

使用者要求：開程式之外也要能關程式；打招呼、「你是哪個模型」這種日常對話直接回答，不要等模型； 「開啟 a 文件」之後可以請小柚在 a 文件底下加字。

閒聊固定回答（q_chat）：打招呼、你是誰、你是哪個模型（依設定回答 Qwen3-VL 2B 或 4B，沒下載就說還沒下載）、 你會做什麼（功能清單）、謝謝、再見、誇獎、你幾歲…，一句一句完全比對，不會吃掉「你好，幫我打開終端機」這種後面還有事的句子 （「你好，」會被當成客套話去掉，後面照常判斷）。「好」「收到」只有在小柚上一句不是問句時才固定回答， 不然（例如模型問「要我幫你搜尋嗎？」）要交給模型。實測模型自己回答這些很不穩：2B 回「你好」是「小柚已經做好了！今天是…」， 4B 回「你是哪個模型」是「不是 AI 大模型」，固定回答比較正確，而且 0 毫秒。

關閉、切換、縮小（q_window，工具還是 close_window／switch_to_window／minimize_window）：程式名稱要完全對得上 （跟「打開」一樣的 strict_app()），「關閉這個視窗」「關閉所有視窗」「隱藏檔案」「退出全螢幕」交給模型。 工具本身也改了：name 是程式名稱時，關閉／縮小這個程式所有的視窗，切換就到最新的那個；不是程式名稱才照舊比對視窗標題、只動一個。 沒開著時回答「目前沒有開著的「終端機」視窗」。關閉是送 _NET_CLOSE_WINDOW，跟按視窗的關閉鈕一樣（編輯器會問要不要儲存， 終端機會直接結束裡面的程式）。

在文字檔最後加字（新工具 append_file，快速通道 q_append）：

• 句型：「在 X（的）最後面／底下／後面… 加上／增加／寫上／補充… 文字」「把 文字 加到／寫進／記在 X（最後面）」。 要加的文字從原句取（保留空白、大小寫、標點），引號「」裡的優先；「一行」「這段話：」之類的字會去掉。 「再」是常見的錯字，要有「最後面」這類字才算；「這個檔案」也一定要說加在哪裡。「在文件裡新增一個檔案」「把這個檔案加到…」交給模型。
• 沒說要加什麼（「在 a 文件底下增加文字」）：回答「要在「a.txt」最後面加上什麼文字？」，下一句話就是內容（說「取消」就不加）。
• 找檔案（find_text_file）：完整路徑／~/；檔名（比對時忽略大小寫、空白與副檔名）依序看文字編輯器開著的檔案、小柚剛開過的檔案、 文件／桌面／下載、整個家目錄；同名的有文字檔也有 Word 檔時只留文字檔；好幾個就列出來讓使用者挑（點一下或「第 2 個」）。 「這個檔案」＝目前視窗的編輯器分頁，其次是小柚剛打開的檔案。
• 寫入前的檢查：家目錄或 /media 裡、不是隱藏檔、一般檔案、8 MB 以下、沒有 NUL（不是 Word／PDF）、UTF-8（Big5 的請用編輯器改）、 編輯器裡沒有沒儲存的修改；確認視窗顯示路徑與要加的文字；按確定後再確認檔案沒被換掉（inode 一樣）、編輯器也還是沒修改。 原本最後一行沒換行會先補換行；CRLF 的檔案用 CRLF。用 O_APPEND 寫，不重寫整個檔案。
• 文字編輯器（pomelo-edit）配合：每個分頁記下檔案的 mtime／大小／inode，每秒（和視窗取得焦點時）檢查一次； 沒修改過就重新載入（先存一份復原紀錄，Ctrl+Z 回得去；內容是加在後面的話游標移到最後），有修改過就只提醒一次「儲存會蓋掉別處的修改」。 視窗屬性 _POMELO_EDIT_DOCS 列出開著的檔案（每行「旗標<Tab>路徑」，a = 目前分頁、m = 還沒儲存），小柚用它找「這個檔案」、擋住沒儲存的檔案。
• 「開啟 a 文件」「打開 待辦.txt」（q_named_file）：在文件／桌面／下載找檔名完全一樣的檔案直接開（以前會交給模型）； 「打開 報告.pdf」這類找不到時，也不會再被當成網址 https://報告.pdf。

順便修的兩個舊問題（對話視窗模式，也就是設定裡關掉「桌面上的小柚」時）：

• pm_ui_run 會把 SIGCHLD 設成自動回收，waitpid 拿不到結束碼、狀態停在 0：確認視窗按「取消」被當成「確定」， nmcli、cp 失敗也都回報成功。改成：確認視窗按確定時在 fd 3 的 pipe 寫一個 y（不再看結束碼）；對話視窗開好後把 SIGCHLD 改回預設， 第一個問題等那之後才送出；每次發問前用 waitpid(-1, WNOHANG) 收掉已經結束的子行程。
• 對話視窗抓住了滑鼠鍵盤又蓋在最上面，確認視窗按不到：確認視窗開著時對話視窗先收起來、放開滑鼠鍵盤，按完再回來。
• 確認視窗的路徑改成 ~/…（太長時檔名會被截掉）。

模型評估（append_file 等新工具加進去之後；32 題：舊的 20 題工具選擇＋說心情的句子＋加字與關閉）：

另外發現：系統提示寫「關閉程式用 close_window」時，4B 對「我今天好累」把所有視窗都關了——已拿掉。 所以第 3 條依模型不同（rule3_big／rule3_small，cur_model()->ram_gb 判斷）。2B 對加字、關閉幾乎都只會嘴上說做好了， 這兩類常見說法都放進快速通道；append_file 的 path 說明寫明「說了檔名就一定要填」，但 4B 在編輯器開著 待辦.txt 時， 「在筆記最後寫上…」還是會填 待辦.txt（這句快速通道接得住，不會走到模型；確認視窗也看得到路徑）。 評估腳本：pomelo-assistant/model-eval.py <socket> 2b|4b [輪數]（33 題，系統提示與工具說明直接從原始碼讀；RULE3=small|big 強制指定第 3 條）。

接下來

1. 語音輸入（麥克風）：使用者已經提出，見第 2 項；辨識出來的文字一樣先走快速通道
2. 語音：喚醒詞（sherpa-onnx）＋語音轉文字（SenseVoice-Small／whisper.cpp）；文字轉語音 0.21 已用 Piper 完成
3. 看畫面與攝影機：需要時載入 Qwen3-VL 的 mmproj，截圖或拍一張給模型看
4. 自動偵測並使用內建顯示晶片（Vulkan／OpenVINO）
5. arm64 套件與樹莓派實測