第一次寫 Omarchy plugin 就上手:用 oma.spectra 當例子,從 clone 內建時鐘到上架 marketplace
我把 Spectra 做成 Omarchy 的 bar 外掛 oma.spectra,從第一個 commit 到可以送 marketplace 的 v0.3.2 是同一個下午的兩個半小時,整包 41 個 commit。這篇把過程寫成別人也走得通的路:Omarchy plugin 有六種 kind、每種對應一個 entryPoints 鍵與一個固定檔名,官方建議的起手式不是從空資料夾開始而是 omarchy plugin clone omarchy.clock --edit 把內建時鐘複製成自己的,因為時鐘就是「一個 bar 圖示加一個面板」這個最常見的形狀。manifest.json 只有六個必填欄位,但 barWidget 區塊裡的 schema 陣列才是讓使用者能在 shell 設定裡改參數的關鍵。驗證分兩層:omarchy plugin validate 看 manifest 與資料夾結構,qmllint -I $OMARCHY_PATH/shell 看 QML 對不對得上已安裝的 shell imports,而且 validate 不吃 symlink,要指到 ~/.config/omarchy/plugins 底下的真實路徑。上架只有三步:公開 repo、根目錄放合格 manifest、開 issue 表單送審,自動檢查會綁定一個 commit 快照。後半是 oma.spectra 本身:面板讀 Spectra CLI 的 list 與 status JSON、渲染 proposal/design/specs/tasks、可改 .spectra.yaml 五個鍵,其餘一律唯讀,new/apply/archive/park 留在終端機。踩到的坑有四個是有紀錄的:mise/nvm 裝的 spxa 只在互動 shell 的 PATH 上、登入 profile 印任何東西都會污染 CLI 回來的 JSON、validator 拒絕 symlink、Markdown 裡的圖片與角括號要先消毒再丟給 Qt 的渲染器。