小蕾米桌面寵物 (Remielle Pet)

August 8, 2026 · View on GitHub

基於 HanaAyane/remielle-codex-pet 二次開發的桌面寵物程式，不依賴 Codex，可獨立執行於 Windows 與 macOS。

小蕾米桌寵展示

效果預覽

待機移動完成慶祝
待機動畫左移動畫完成動畫

功能

  • 透明桌面寵物：粉髮白翼的 Q 版小天使，帶呼吸眨眼動畫，視窗始終置頂顯示
  • 固定置頂：寵物始終保持在其他視窗之上，不會被遮擋（點擊托盤圖示隱藏後可恢復）
  • 多螢幕移動：以寵物目前所在的螢幕為移動邊界，放在副螢幕不會被拉回主螢幕
  • 隨機移動：寵物會在桌面自由走動，碰到螢幕邊緣自動反彈；待機 2~6 秒後就會隨機行動
  • 彩蛋表演：移動結束後必播一個彩蛋動作，待機時也有 40% 機率直接表演，彩蛋結束後還有機率連續再演；動作池共 8 種（期待、鋼筆待機、工作中、慶祝、間歇、檢查中、失敗、等待確認）
  • 滑鼠拖曳：左鍵按住直接拖到任意位置，拖曳時播放揮手動作
  • 系統托盤：工作列小圖示常駐，左鍵單擊隱藏/恢復寵物
  • 右鍵選單：托盤與寵物視窗共用統一選單
    • 表演動作：手動觸發指定動作
    • 自由移動：勾選/取消控制寵物是否走動；取消後原地不動，但仍會隨機表演彩蛋（內建心跳看門狗，引擎異常自動恢復）
    • Agent Harness 模式：切換為監聽 OpenCode / Codex 工作狀態
    • 開機自啟：勾選後開機自動啟動
    • 退出寵物
  • Ctrl+滾輪縮放：滑鼠懸停在寵物上時，按住 Ctrl 滾動滾輪縮放（10%～200%）
  • 選單穩定性加固：修復選單關閉流程中狀態意外翻轉的問題，勾選狀態穩定可靠
  • Agent Harness 整合：可監聽 OpenCode 與 Codex CLI 的生命週期事件，在 agent 工作時切換「期待 / 工作中 / 等待確認 / 待機」動作

Agent Harness 整合（OpenCode / Codex）

小蕾米可以監聽 OpenCode 或 Codex CLI 的生命週期事件，在 agent 工作時切換動作：

  • working：任務進行中 → 播放「工作中」
  • waiting：session 開著 / 回合結束 → 先播放「期待」，等待 expect_timeout_seconds（預設 300 秒）後轉為「等待確認」
  • 全部 session 關閉或狀態檔消失 → 回到「待機」

安裝

python integration/install.py install
  • OpenCode plugin 會安裝到 ~/.config/opencode/plugins/remielle.ts
  • Codex hooks 會合併到 ~/.codex/hooks.json（會先備份為 hooks.json.bak）
  • 設定檔與狀態檔位於：
    • Windows：%LOCALAPPDATA%\RemiellePet\
    • macOS：~/Library/Application Support/RemiellePet/

安裝後：

  1. 重新啟動 OpenCode，讓 plugin 載入
  2. 在 Codex CLI 中執行 /hooks 審核並信任新的 hooks
  3. 在小蕾米右鍵選單勾選「Agent Harness 模式」
  4. 開始使用 OpenCode / Codex，即可看到狀態切換

手動測試

python pet/notify_pet.py opencode working --session test1
python pet/notify_pet.py opencode waiting --session test1
python pet/notify_pet.py opencode closed --session test1

解除安裝與狀態查詢

python integration/install.py uninstall
python integration/install.py status

設定

config.json（小蕾米首次啟動時自動建立）：

{
  "mode": "default",
  "expect_timeout_seconds": 300,
  "stale_session_seconds": 86400
}
  • mode：default（原有隨機行為）/ agent（監聽 harness）
  • expect_timeout_seconds：「期待」轉「等待確認」的秒數
  • stale_session_seconds：session 記錄被視為僵屍並清除的秒數（預設 24 小時）

疑難排解

  • OpenCode 回覆完仍顯示「工作中」：新版 plugin 使用 session.status 的 busy / idle 判斷狀態，並讀取真實 session id；若仍異常，可查看 ~/.config/opencode/remielle-pet.log 的事件日誌。
  • 狀態檔位置：Windows 為 %LOCALAPPDATA%\RemiellePet\opencode.json（或 codex.json），macOS 為 ~/Library/Application Support/RemiellePet/opencode.json。

使用方法

Windows

直接雙擊 pet/dist/remielle-pet.exe（需先打包），寵物即出現在桌面右下角附近。

macOS

參閱 pet/MAC打包说明.md，在 Mac 上自行打包後執行 .app。

原始碼執行（需 Python 3.10+ 與 PySide6）

建議用 uv 建立專案專屬虛擬環境，避免污染系統 Python：

uv venv
uv pip install PySide6
uv run python pet/main.py

也可以直接使用已建立的 .venv：

.venv\Scripts\python pet\main.py

打包 Windows exe

uv pip install pyinstaller pillow
cd pet
..\.venv\Scripts\python.exe -m PyInstaller --noconfirm --onefile --noconsole --name remielle-pet --icon '..\表情包单张预览\05-完成庆祝-smug.png' --add-data '..\gif;gif' --add-data '..\表情包单张预览;表情包单张预览' ..\pet\main.py

產物位於 pet/dist/remielle-pet.exe。

專案結構

Remielle/
├── gif/                    # 動畫 GIF 素材（7 個原始動作）
├── 表情包单张预览/          # 透明 PNG 單幀預覽（9 個動作）
├── output/xiaoleimi/        # 原始 Codex 桌寵資源包（精靈表等）
├── pet/                    # 桌寵程式原始碼與腳本
│   ├── main.py             # 入口（含單實例鎖）
│   ├── pet_window.py       # 透明視窗 + 托盤 + 選單 + 縮放 + 置頂
│   ├── behavior.py         # 隨機移動狀態機 + 心跳看門狗
│   ├── actions.py          # 動作管理（GIF/PNG）
│   ├── status.py           # 狀態/設定檔共用邏輯
│   ├── status_watcher.py   # Agent Harness 狀態 watcher
│   ├── notify_pet.py       # harness 端 notifier CLI
│   ├── build.bat           # Windows 打包腳本
│   ├── build_mac.sh        # macOS 打包腳本
│   └── MAC打包说明.md
├── integration/            # OpenCode / Codex 整合
│   ├── opencode-plugin.ts  # OpenCode plugin 原始碼
│   ├── codex-hooks.template.json
│   └── install.py          # 安裝/解除安裝/狀態查詢
├── tests/                  # 單元測試
│   ├── test_status.py
│   └── test_install.py
├── dist/                   # 打包產物
├── assets/readme/          # README 展示素材（動態圖/預覽圖）
├── 使用说明.md
├── README.md
├── README-ORIGINAL.md      # 原專案 README（HanaAyane 版本）
├── ASSET-USAGE.md          # 原素材使用說明
├── NOTICE.md               # 版權與聲明
└── LICENSE                 # Apache-2.0

版本紀錄

  • v1.3（最新）：多螢幕移動邊界；預設模式更活潑（待機 2~6 秒、40% 彩蛋機率、8 種動作、可連續表演）；關閉自由移動仍會原地表演彩蛋；OpenCode 狀態事件修正（session.status、真實 session id）；點擊寵物後正確恢復 harness 狀態
  • v1.2：新增 Agent Harness 整合（OpenCode plugin + Codex hooks）；雙模式切換；狀態 watcher 與可設定超時
  • v1.1：桌寵固定置頂；修復右鍵選單幽靈啟動導致狀態意外翻轉的問題；選單勾選項穩定性加固；單實例執行保障
  • v1.0：脫離 Codex 獨立執行；系統托盤、Ctrl+滾輪縮放、開機自啟；心跳看門狗

二次開發聲明

本專案基於 HanaAyane/remielle-codex-pet 進行二次開發，主要改動包括：

  • 脫離 Codex 依賴，獨立桌面執行
  • 增加系統托盤、Ctrl+滾輪縮放、開機自啟等互動
  • 桌寵固定置頂，不再提供置頂切換
  • 修復右鍵選單狀態意外翻轉問題
  • 新增心跳看門狗，自由移動引擎異常時自動恢復
  • 新增 Windows 和 macOS 雙平台支援
  • 單實例執行，避免重複啟動
  • 新增 OpenCode / Codex 的 Agent Harness 狀態整合
  • 多螢幕移動與更活潑的預設隨機行為

素材使用權歸原作者所有。使用前請閱讀倉庫內的 ASSET-USAGE.md 與 NOTICE.md 了解版權與授權範圍。

版權

素材作者：HanaAyane / 小蕾米
來源：https://github.com/HanaAyane/remielle-codex-pet
說明：本素材基於《絕區零》公開素材，經 AI 輔助重繪、人工整理與編輯
授權範圍：僅限非商業同人交流，詳見 ASSET-USAGE.md 與 NOTICE.md

桌面寵物程式（pet/ 目錄下的 Python 程式碼）：Apache-2.0（詳見 LICENSE）