petdex：從 README 拆解功能、限制與採用條件
Codex、Claude Code、OpenCode 和 Gemini CLI 的動畫寵物公共畫廊。
秒懂
- 它是什麼？
- The public gallery of animated pet for Codex, Claude Code, OpenCode y Gemini CLI.。本文整理 crafter-station/petdex README 的使用入口、環境條件、功能邊界與專案專屬核驗方式。
- 適合誰用？
- petdex 適合需要 README 所列「The public gallery of animated pet for Codex, Claude Code, OpenCode y Gemini CLI.」能力，並能管理其環境與設定的使用者；不適合把範例或未說明行為當成正式保證。先執行：在 Crafter-Station/PetDex 依 README 安裝並啟動，檢查資料檔、介面中的圖鑑狀態和專案指定的輸入輸出，重新整理後確認資料是否保留。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 1 天前。
- 用什麼語言寫的？
- 主要是 TypeScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月14日）與我們的分析，不構成法律意見。
開源專案深度解析
petdex：把顯示留給桌面應用程式的目錄用戶端（1）
Petdex CLI 是供編碼助理使用的動畫寵物的目錄用戶端。寵物本身由 Petdex Desktop 展示，那是一款獨立應用程式，透過自己的設定視窗連接各個助理；CLI 的職責是從終端機瀏覽、安裝和提交寵物。README 將圖庫和文件放在 petdex.dev，寵物建立頁面也在那裡，原始碼位於 github.com/crafter-station/petdex。開頭就說明了這層分工：CLI 是目錄用戶端，寵物由桌面應用程式顯示。這也意味著 CLI 本身不負責顯示寵物，也不負責把助理連接到寵物上，這些都由桌面應用程式的設定視窗完成。
在 Crafter-Station/PetDex 依 README 安裝並啟動，檢查資料檔、介面中的圖鑑狀態和專案指定的輸入輸出，重新整理後確認資料是否保留。 這個步驟只核對 crafter-station/petdex README 已列出的行為；文件未說明的效能、相容性或安全性不延伸成保證。
petdex：安裝與執行需求（2）
README 記錄了兩種安裝路徑。一次性執行透過 npx 完成，命令是 `npx petdex --help`，不需要全域安裝；另一種是 `npm install -g petdex` 的全域安裝。兩條路徑都要求 Node.js 20 或更高版本，README 還說明 CLI 也可以在 Bun 上執行。原始碼沒有指定最低 Bun 版本，沒有說明作業系統限制，也沒有除了這兩條命令之外的安裝步驟。若要跳過 npx 的確認提示，README 建議使用 `npx -y petdex install <slug>`。README 還提示，如果看起來卡在安裝依賴上，那幾乎總是 npm 自身的進度條，而不是子依賴樹。
在 Crafter-Station/PetDex 依 README 安裝並啟動，檢查資料檔、介面中的圖鑑狀態和專案指定的輸入輸出，重新整理後確認資料是否保留。 這個步驟只核對 crafter-station/petdex README 已列出的行為；文件未說明的效能、相容性或安全性不延伸成保證。（petdex 第 2 節第 2 段）
petdex：命令面（3）
CLI 提供九個命令：login、logout、whoami、list、install、submit、edit、telemetry 和 --version。login 開啟瀏覽器，透過 Clerk 完成 OAuth 認證，使用 PKCE；logout 清除本機憑證；whoami 列印目前登入身分；list 列出圖庫中已核准的寵物。install 接受一個 slug，將寵物寫入 ~/.petdex/pets/<slug>/ 和 ~/.codex/pets/<slug>/。edit 適用於使用者擁有的寵物，接受 --desc、--displayName、--sprite、--meta 和 --zip。telemetry 管理匿名使用遙測，--version 列印 CLI 版本。README 還記錄了 init、up、down、toggle、desktop、update、doctor 和 hooks 在 v1.0.0 中被移除，執行它們只會列印一條指向桌面應用程式的提示。
在 Crafter-Station/PetDex 依 README 安裝並啟動，檢查資料檔、介面中的圖鑑狀態和專案指定的輸入輸出，重新整理後確認資料是否保留。 這個步驟只核對 crafter-station/petdex README 已列出的行為；文件未說明的效能、相容性或安全性不延伸成保證。（petdex 第 3 節第 2 段）
petdex：提交管線與驗證（4）
submit 接受三種輸入形式：一個必須包含 pet.json 和精靈圖表的資料夾、一個具有相同根佈局的 zip，或一個父資料夾，其中每個包含 pet.json 的子資料夾都會被提交。每次提交時，CLI 在記憶體中建立一個乾淨的 zip，呼叫 POST /api/cli/submit 取得有效期 60 秒的 Cloudflare R2 預先簽署上傳 URL，將檔案直接上傳到 R2，讓請求體不會經過 Petdex 伺服器，然後呼叫 POST /api/cli/submit/register 將提交記錄為 pending。每個提交會顯示進度，摘要列出失敗原因。slug 會自動去重（boba 變成 boba-2、boba-3 依此類推），提交不會因碰撞而失敗。驗證要求精靈圖表為 1536x1872 的 8x9 網格或 1536x2288 的 8x11 網格，或其中任一的乾淨縮放；ChatGPT 匯出已經是 v2 形狀。速率限制為每個使用者每 24 小時 10 次提交，管理員不受限制。
在 Crafter-Station/PetDex 依 README 安裝並啟動，檢查資料檔、介面中的圖鑑狀態和專案指定的輸入輸出，重新整理後確認資料是否保留。 這個步驟只核對 crafter-station/petdex README 已列出的行為；文件未說明的效能、相容性或安全性不延伸成保證。（petdex 第 4 節第 2 段）
petdex：認證（5）
認證使用 OAuth 2.0 Authorization Code 搭配 PKCE（S256），作為公開用戶端執行，因此機器上不儲存用戶端金鑰。本機回呼在 127.0.0.1 的隨機連接埠上執行。權杖儲存在 macOS、Windows 和 Linux 的系統金鑰圈中，在沒有金鑰圈可用時會退回使用 chmod 600 的檔案。存取權杖使用儲存的重新整理權杖自動重新整理，直到使用者執行 logout 才失效。流程遵循內建在套件中的 @clerk/cli-auth 參考實作，README 給出了該實作的 GitHub 連結。
在 Crafter-Station/PetDex 依 README 安裝並啟動，檢查資料檔、介面中的圖鑑狀態和專案指定的輸入輸出，重新整理後確認資料是否保留。 這個步驟只核對 crafter-station/petdex README 已列出的行為；文件未說明的效能、相容性或安全性不延伸成保證。（petdex 第 5 節第 2 段）
petdex：製作寵物（6）
README 明確說明 CLI 分發寵物但不產生寵物。文件記錄了兩種工作流程。在 ChatGPT 桌面應用程式中，輸入 /pet 並描述你想要的內容，會寫出一個資料夾，可以直接用 `petdex submit` 提交。對於 ChatGPT 匯出，1536x2288 的精靈圖表與 Petdex 讀取的圖集相同，包含九個狀態列和相符的幀數；PNG 可以拖到 petdex.dev/submit，系統會測量網格並產生匯出中缺少的 pet.json，產生發生在命名之前。完整的逐步指南（包含讓寵物更好的建議）位於 petdex.dev/create。
在 Crafter-Station/PetDex 依 README 安裝並啟動，檢查資料檔、介面中的圖鑑狀態和專案指定的輸入輸出，重新整理後確認資料是否保留。 這個步驟只核對 crafter-station/petdex README 已列出的行為；文件未說明的效能、相容性或安全性不延伸成保證。（petdex 第 6 節第 2 段）
petdex：錯誤處理、封裝與授權（7）
README 的故障模式表將每個錯誤症狀對應到原因和修正方法：工作階段過期（Not signed in）、Bearer 權杖被拒（presign 401）、速率限制（presign 429）、精靈圖表網格無效（register 400 invalid_spritesheet）、檔案缺少（register 400 missing_field）和預先簽署 URL 過期（R2 PUT 403）。常見安裝問題可追溯到 npx 自己的確認提示（需要按 y 或使用 `npx -y`）、低於 20 的 Node 版本、網路封鎖（可透過 HTTPS_PROXY 代理解決）、目錄權限和舊的 Windows 安裝路徑。CLI 以單一捆綁的 JS 檔案發布，沒有原生依賴，捆綁了 @clack/prompts、picocolors 和 jszip，機器上不需要單獨的依賴安裝步驟。授權是 MIT，版權歸 Crafter Station（2026）；授權文字授予使用、複製、修改、合併、發布、散布、再授權和銷售的權利，並宣告軟體依現狀提供，不附帶任何擔保。授權文字沒有說明支援或安全態勢。
在 Crafter-Station/PetDex 依 README 安裝並啟動，檢查資料檔、介面中的圖鑑狀態和專案指定的輸入輸出，重新整理後確認資料是否保留。 這個步驟只核對 crafter-station/petdex README 已列出的行為；文件未說明的效能、相容性或安全性不延伸成保證。（petdex 第 7 節第 2 段）
petdex 第 1 次檢查仍應回到具體產物：執行 在 Crafter-Station/PetDex 依 README 安裝並啟動，檢查資料檔、介面中的圖鑑狀態和專案指定的輸入輸出，重新整理後確認資料是否保留。 後，命令是否完成、指定檔案是否生成、服務是否回應，以及再次執行時結果能否解釋。這些觀察可分辨設定缺漏、平台差異與 README 已明列的功能範圍，也能讓團隊知道哪一項條件尚未被這個專案涵蓋。
petdex 第 2 次檢查仍應回到具體產物：執行 在 Crafter-Station/PetDex 依 README 安裝並啟動，檢查資料檔、介面中的圖鑑狀態和專案指定的輸入輸出，重新整理後確認資料是否保留。 後，命令是否完成、指定檔案是否生成、服務是否回應，以及再次執行時結果能否解釋。這些觀察可分辨設定缺漏、平台差異與 README 已明列的功能範圍，也能讓團隊知道哪一項條件尚未被這個專案涵蓋。
編輯結論
petdex 適合需要 README 所列「The public gallery of animated pet for Codex, Claude Code, OpenCode y Gemini CLI.」能力，並能管理其環境與設定的使用者；不適合把範例或未說明行為當成正式保證。先執行：在 Crafter-Station/PetDex 依 README 安裝並啟動，檢查資料檔、介面中的圖鑑狀態和專案指定的輸入輸出，重新整理後確認資料是否保留。 再依具體輸出決定是否納入既有流程。
社群筆記