paperclip-create-plugin

建立與開發 Paperclip 外掛程式

當任務需要針對本地 Paperclip 執行個體（instance）建立、搭建骨架或疊代 Paperclip 外掛程式時，請使用此 Skill。

1. 預設做法：在 Paperclip 核心專案外部建置外掛程式

外掛程式有各自獨立的套件。除非任務明確要求提供內建在儲存庫（in-repo）的範例，否則請勿在目前儲存庫的 packages/plugins/ 目錄下新增外掛程式原始碼。

• 將外掛程式骨架建立在 Paperclip 專案以外的目錄（例如：~/dev/paperclip-plugins/<name>）。
• 透過本地絕對路徑，將其安裝至正在執行的 Paperclip 執行個體中。
• 在外部套件中修改程式碼，讓 Paperclip 直接載入重新建置後的產物。

只有在使用者要求將外掛程式作為內建範例展示時（如修改 server/src/routes/plugins.ts、專案內的範例清單或文件），才需要修改 Paperclip 核心本身。

2. 基本原則

需要詳細資訊時請參考以下文件：

1. doc/plugins/PLUGIN_AUTHORING_GUIDE.md
2. packages/plugins/sdk/README.md
3. doc/plugins/PLUGIN_SPEC.md — 僅作為前瞻性的背景參考

目前的執行階段（runtime）假設：

• worker 外掛程式屬於受信任的程式碼
• UI 外掛程式屬於受信任且同源的主機程式碼
• worker API 受功能權限（capability）管控
• UI 外掛程式不受 manifest 功能權限沙盒限制
• 目前執行階段尚未提供主機端的共享外掛程式 UI 元件庫
• 目前執行階段不支援 ctx.assets

3. CLI 優先的骨架建立工作流程

請使用 paperclipai plugin init。除非目前環境無法使用該 CLI 指令，否則請勿手動呼叫骨架建置套件的 Node 進入點（entrypoint）。

paperclipai plugin init @acme/my-plugin --output ~/dev/paperclip-plugins

實用旗標（皆為選填）：

• --output <dir> — 上層目錄；指令會在其中建立 <dir>/<unscoped-name>/。預設為目前目錄。
• --template <default|connector|workspace|environment> — 起始範本。
• --category <connector|workspace|automation|ui|environment> — manifest 分類。
• --display-name <name>, --description <text>, --author <name> — manifest 中詮釋資料。
• --sdk-path <path> — 將 Paperclip 專案中的本地 SDK 快照擷取至 .paperclip-sdk/（在搭配未發佈的 SDK 進行開發時非常實用）。

執行成功後，指令會印出接下來需執行的精確指令（cd、pnpm install、pnpm dev、paperclipai plugin install <abs-path>）。請依序執行。

如果環境中的 PATH 找不到 paperclipai，可備用以下方式：

pnpm --filter @paperclipai/create-paperclip-plugin build
node packages/plugins/create-paperclip-plugin/dist/index.js @acme/my-plugin \
  --output /absolute/path \
  --sdk-path /absolute/path/to/paperclip/packages/plugins/sdk

4. 本地安裝與重新建置迴圈

在建立好的外掛程式資料夾中：

pnpm install
pnpm dev            # esbuild --watch：重新建置 dist/manifest.js、dist/worker.js、dist/ui/
paperclipai plugin install /absolute/path/to/my-plugin

注意事項：

• paperclipai plugin install 會自動偵測本地路徑（絕對路徑、./、../、~ 或現有的相對資料夾），並向伺服器發送 isLocalPath: true。若推斷有歧義，可傳入 --local 強制使用本地模式。
• 路徑在傳送至伺服器前會先解析為絕對路徑。
• 伺服器會監控本地路徑外掛程式的建置輸出（dist/），並在重新建置時重啟外掛程式 worker — 您不需要在每次修改後都重新安裝。
• 透過 SDK 開發伺服器（pnpm dev:ui，連接埠 4177）實現 UI 熱更新（hot reload）是可選的，且取決於所用的範本；僅在範本有串接 devUiUrl 且您已驗證可端到端運作時再提及。
• --version 僅適用於 npm 套件安裝。將其與本地路徑混用會回傳錯誤。

安裝完成後，可使用以下指令進行檢視：

paperclipai plugin list
paperclipai plugin inspect <plugin-key>

5. 建立骨架後的套件健全檢查

開啟並確認以下檔案：

• src/manifest.ts — 宣告的功能權限（capabilities）與插槽（slots）
• src/worker.ts — worker 進入點
• src/ui/index.tsx — UI 進入點（若適用）
• tests/plugin.spec.ts — 預設測試檔
• package.json — paperclipPlugin 區塊需指向 dist/manifest.js、dist/worker.js、dist/ui/

確保外掛程式：

• 僅宣告受支援的功能權限
• 未使用 ctx.assets
• 未匯入主機端的 UI 元件存根（stub）
• 保持 UI 的自洽與獨立（self-contained）
• 僅在 page 插槽上使用 routePath

6. 驗證（在宣告成功前執行）

在外掛程式資料夾中執行：

pnpm typecheck
pnpm test
pnpm build

若外掛程式已在 pnpm dev 下運行，您可以保持監控器（watcher）開啟，並在另一個 Shell 中執行 pnpm typecheck 與 pnpm test。

除了外掛程式之外，如果您還修改了 Paperclip SDK/host/plugin 執行階段程式碼，請一併執行相關的 Paperclip 工作區檢查。

7. 成功檢查清單（需回報結果）

完成本地外掛程式任務時，請回報：

• 骨架路徑（Scaffold path） — 所建立外掛程式資料夾的絕對路徑。
• 已執行的指令（Commands run） — 實際執行的 paperclipai plugin init、pnpm install、pnpm dev、paperclipai plugin install <path> 呼叫（以及任何驗證指令）。
• 安裝狀態（Install status） — paperclipai plugin list / plugin inspect 的輸出（包含 plugin key、版本、狀態）。若 status 不是 ready，請特別註明並附上 lastError。
• 測試 / 建置結果（Tests / build result） — pnpm typecheck、pnpm test、pnpm build 通過或失敗的狀態；若失敗請提供錯誤輸出。
• 熱更新限制（Reload limitations） — 註明任何無法熱更新的情形（例如修改 manifest 需要重新安裝、UI 開發伺服器未串接等）。

若有任何項目缺失，請如實標記 — 請勿默認跳過。

8. 何時「不應」修改 Paperclip 核心

除非使用者明確要求提供內建範例，否則請勿將外掛程式新增至 packages/plugins/ 下或更新內建範例的串接設定。本地路徑安裝是官方支援的開發模式；npm 套件才是正式環境的部署方式。

若使用者確實要求提供內建範例，請同步更新：

• server/src/routes/plugins.ts 範例清單
• 任何列出儲存庫內建範例外掛程式的文件

9. 文件規範要求

在撰寫或更新外掛程式文件時：

• 明確區分目前的實作與未來的規格構想
• 清楚說明受信任程式碼的模型（trusted-code model）
• 請勿承諾主機 UI 元件或資源 API
• 優先提供本地路徑開發 + npm 套件部署的指引，而非儲存庫內部的工作流程