paperclip-create-plugin

Paperclip プラグインの作成と開発

ローカルの Paperclip インスタンスで Paperclip プラグインを作成、スキャフォールディング、または反復開発するタスクでは、このスキルを使用します。

1. デフォルト：Paperclip のコアの外部でプラグインを構築する

プラグインは独立したパッケージです。タスクでリポジトリ内にバンドルするサンプルを明示的に求められていない限り、このリポジトリの packages/plugins/ 以下にプラグインのソースを追加しないでください。

• Paperclip のチェックアウト先の外部にあるディレクトリ（例：~/dev/paperclip-plugins/<name>）にプラグインをスキャフォールディングします。
• ローカルの絶対パスを指定して、実行中の Paperclip インスタンスにインストールします。
• 外部パッケージ内のコードを編集し、Paperclip に再ビルド後の出力を反映させます。

プラグインをバンドル済みのサンプルとして公開するようユーザーが求めた場合に限り、Paperclip のコア自体（server/src/routes/plugins.ts、リポジトリ内のサンプル一覧、ドキュメント）を編集してください。

2. 基本ルール

詳細が必要な場合は、次のドキュメントを参照してください。

1. doc/plugins/PLUGIN_AUTHORING_GUIDE.md
2. packages/plugins/sdk/README.md
3. doc/plugins/PLUGIN_SPEC.md — 今後の展望を把握する目的に限って参照してください

現在のランタイムに関する前提：

• プラグインのワーカーは信頼されたコードです
• プラグインの UI は、信頼された同一オリジンのホストコードです
• ワーカー API はケイパビリティによって制御されます
• プラグインの UI はマニフェストのケイパビリティによってサンドボックス化されません
• ホストが提供する共通のプラグイン UI コンポーネントキットはまだありません
• 現在のランタイムでは ctx.assets はサポートされていません

3. CLI 優先のスキャフォールディング手順

paperclipai plugin init を使用してください。環境で CLI コマンドを使用できない場合を除き、スキャフォールディング用パッケージの node エントリーポイントを直接実行しないでください。

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> — マニフェストのカテゴリです。
• --display-name <name>、--description <text>、--author <name> — マニフェストのメタデータです。
• --sdk-path <path> — Paperclip のチェックアウト先にあるローカル SDK のスナップショットを .paperclip-sdk/ に保存します（未リリースの SDK を使った開発に便利です）。

成功すると、コマンドは次に実行する正確なコマンド（cd、pnpm install、pnpm dev、paperclipai plugin install <abs-path>）を表示します。順番に実行してください。

環境で paperclipai が PATH にない場合は、次の方法に切り替えてください。

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: rebuilds dist/manifest.js, dist/worker.js, dist/ui/
paperclipai plugin install /absolute/path/to/my-plugin

注意事項：

• paperclipai plugin install はローカルパス（絶対パス、./、../、~、または既存の相対フォルダー）を自動検出し、isLocalPath: true をサーバーに渡します。判定が曖昧な場合は --local を指定して、ローカルモードを強制してください。
• サーバーに送信する前に、パスは絶対パスに解決されます。
• サーバーはローカルパスのプラグインについてビルド済みの出力（dist/）を監視し、再ビルド時にプラグインワーカーを再起動します。そのため、編集のたびに再インストールする必要はありません。
• SDK 開発サーバー（pnpm dev:ui、ポート 4177）による UI のホットリロードは省略可能で、テンプレートによって異なります。devUiUrl が設定されており、エンドツーエンドで動作を確認できた場合に限り、そのことに触れてください。
• --version は npm パッケージのインストールにのみ適用されます。ローカルパスと組み合わせるとエラーになります。

インストール後、次のコマンドで確認してください。

paperclipai plugin list
paperclipai plugin inspect <plugin-key>

5. スキャフォールディング後にパッケージを確認する

次のファイルを開いて確認してください。

• src/manifest.ts — 宣言されたケイパビリティとスロット
• src/worker.ts — ワーカーのエントリーポイント
• src/ui/index.tsx — UI のエントリーポイント（該当する場合）
• tests/plugin.spec.ts — プレースホルダーのテスト
• package.json — paperclipPlugin ブロックが dist/manifest.js、dist/worker.js、dist/ui/ を指していること

プラグインが次の条件を満たすことを確認してください。

• サポートされているケイパビリティのみを宣言している
• ctx.assets を使用していない
• ホスト UI コンポーネントのスタブをインポートしていない
• UI が自己完結している
• routePath を page スロットでのみ使用している

6. 検証（成功を宣言する前に実行）

プラグインのフォルダーから、次を実行します。

pnpm typecheck
pnpm test
pnpm build

プラグインがすでに pnpm dev で実行中の場合は、ウォッチャーを起動したまま、別のシェルで pnpm typecheck と pnpm test を実行できます。

プラグインに加えて Paperclip SDK／ホスト／プラグインのランタイムコードを変更した場合は、関連する Paperclip ワークスペースのチェックも実行してください。

7. 成功チェックリスト（結果を報告してください）

ローカルプラグインのタスクを完了したら、次の内容を報告してください。

• スキャフォールドのパス — 作成したプラグインフォルダーの絶対パス。
• 実行したコマンド — paperclipai plugin init、pnpm install、pnpm dev、paperclipai plugin install <path> の正確な呼び出し内容（および検証コマンド）。
• インストール状況 — paperclipai plugin list／plugin inspect の出力（プラグインキー、バージョン、ステータス）。status が ready 以外の場合はその旨を記載し、lastError も含めてください。
• テスト／ビルド結果 — pnpm typecheck、pnpm test、pnpm build の成功／失敗と、失敗した場合はその出力。
• リロードに関する制限 — ホットリロードされなかったもの（マニフェストの変更には再インストールが必要だった、UI 開発サーバーが接続されていなかった、など）を明記してください。

項目が不足している場合は、その旨を記載してください。黙って省略しないでください。

8. Paperclip コアを編集してはいけない場合

ユーザーがバンドルされたサンプルを明示的に依頼しない限り、プラグインを packages/plugins/ に追加したり、バンドルされたサンプルの配線を更新したりしないでください。開発ではローカルパスによるインストールがサポートされているモデルであり、本番環境へのデプロイには npm パッケージを使用します。

ユーザーがバンドルされたサンプルを依頼した場合は、次も更新してください。

• server/src/routes/plugins.ts のサンプル一覧
• リポジトリ内のサンプルプラグインを列挙しているドキュメント

9. ドキュメントに関する要件

プラグインのドキュメントを作成または更新する際は、次の点に従ってください。

• 現在の実装と将来の仕様案を区別する
• 信頼済みコードのモデルを明確に説明する
• ホストの UI コンポーネントやアセット API を利用できると約束しない
• リポジトリ内のワークフローより、ローカルパスを使った開発と npm パッケージを使ったデプロイの案内を優先する