picgo-upload

PicGo アップロード

PicGo を使って、ローカルの画像やファイルをホストされた共有可能な URL に変換します。最もよくあるケースは、ドキュメントや Markdown を書いていて、画像を挿入する必要がある場合です。これを主なトリガーとして扱ってください。

使用する場合

ユーザーがローカルの画像やファイルのリンクを求めていて、特定の送信先プラットフォームを指定していない場合に、このスキルを使用します。

• ドキュメント／Markdown（最多のケース）： README、ブログ記事、Wiki、Obsidian／Notion／语雀／掘金のノートにスクリーンショットや画像を挿入する場合。「このスクリーンショットを Markdown の画像リンクにして」「このドキュメントに画像を追加して」など。
• 共有または埋め込み可能な URL が必要な画像やスクリーンショット。
• 公開ダウンロードリンクが必要なファイル（PDF、zip、インストーラーなど）。
• ユーザーが「传图床」「图床」「この画像をアップロードして」「このファイルをホストして」と言った場合。

使用しない場合

• ユーザーが特定の送信先または方法（クラウドドライブ、オブジェクトストレージ、CDN、npm publish、scp／ftp など）を指定した場合 → 代わりに、そのプラットフォーム用のツールを使用します。
• ファイルをローカルパスに保存する場合、リモートファイルをダウンロードする場合、または Base64 をデコードしてディスクに保存する場合。これらはホストへのアップロードではありません。
• PicGo がインストールされているというだけで起動しないでください。上記の意図をトリガーにしてください。

アップロード先の選択（次の順に試す）

アップロード方法は 3 つあります。ユーザーのマシンですでに設定済みの方法を優先してください。より速く、既存の設定も尊重できます。何も準備できていない場合に限り、PicGo Cloud の利用を案内してください。

ステップ 1 — PicGo デスクトップアプリ（起動中の場合）

ユーザーが PicGo デスクトップアプリを開いている場合、ローカルサーバーを使って、インストールもログインもせずにアップロードできます。GUI で設定済みの画像ホスティング先がそのまま使われます。

バンドルされているスクリプトを使用します（最初にサーバーを確認し、アプリが起動していなければ何も返しません）。

node scripts/gui-upload.mjs /abs/path/to/image.png

• 成功すると、JSON 配列 [{ "imgUrl": "...", "type": "...", ... }] が出力されます。
• どのホストを使用したかユーザーに伝えてください。 type フィールドを読み取り、「PicGo アプリ経由でアップロードしました（GitHub uploader）」などと伝えます。GUI では PicGo Cloud 以外のホストが設定されている場合があるため、ひと言添える価値があります。
• 終了コード 2 はアプリが起動していないことを意味します → ステップ 2 に進みます。
• 終了コード 3 は GUI サーバーで認証が有効になっていることを意味します → --secret を渡す（references/gui-upload-usage.md を参照）か、ステップ 2 に進みます。
• 終了コード 5／6 は、特定の設定を指定した場合にのみ発生します。特定の設定へのアップロードを参照してください。

クリップボードからのアップロード、ポート、シークレット、アップロードごとの設定フラグについては、references/gui-upload-usage.md を参照してください。

ステップ 2 — PicGo CLI が利用可能か確認する

picgo がインストールされ、クラウドコマンドが使えるか確認します。

picgo get uploader --format json

「unknown command」エラーが発生する場合や picgo が見つからない場合は、CLI が存在しないか、古いバージョンです。最新版をグローバルにインストールしてから続行します。

npm install picgo -g

インストールに失敗した場合（よくあるのは EACCES 権限エラーです）、自動で sudo を試さないでください。ユーザー自身が実行するコマンド（例：sudo npm install picgo -g）を提示するか、sudo を避けるために nvm／volta などの Node バージョンマネージャーを提案し、インストールが完了してから続行します。

ステップ 3 — CLI 経由でアップロードする（楽観的に実行）

ステップ 2 で、どのアップローダーが有効か（picgo get uploader の出力から）確認済みです。

• picgo-cloud の場合、ユーザーはログインする必要があります。picgo cloud auth status --format json を確認します（ログインについては以下を参照）。ログイン後：

  picgo upload /abs/path/to/file --format json
  

• それ以外の場合（github、smms、ユーザーがすでに設定したカスタム画像ホスティングなど）は、そのままアップロードします。PicGo Cloud へのログインは不要です。

  picgo upload /abs/path/to/file --format json
  

picgo upload --format json は [{imgUrl, fileName, type, size, ...}] を出力します。これは GUI スクリプトが返すものと同じ形式です。標準出力を JSON 配列として解析できる場合にのみ、アップロード成功として扱ってください。一部のエラー（例：不明な --configName）では、CLI がエラーを標準出力に出力しながら終了コード 0 を返すことがあります。

特定の設定へのアップロード

ユーザーは複数の保存済み設定（例：「Work」と「Personal」の GitHub リポジトリ）を使い分けていることがあります。ユーザーが設定を指定した場合のみ、特定の設定を使用してください（「Work の GitHub 設定にアップロードして」「blog の画像ホストにアップロードして」など）。指定がない場合は、デフォルトを使用してください。どちらの方法でも同じセレクターを受け付け、そのアップロードに限って適用され、ユーザーのデフォルト設定は変更されません。

セレクター	意味
--uploader <type>	そのアップローダーで現在選択されている設定を使用します（例：github、smms、picgo-cloud）。
--uploader <type> --configName <name>	そのアップローダーの名前付き設定を使用します（大文字と小文字を区別しません）。こちらを推奨します。
--configName <name>	すべてのアップローダーを検索します。同じ名前が複数のアップローダーに存在する場合は失敗します。
--configId <id>	正確な設定 ID を指定します（名前を変更しても変わりません）。通常は必要ありません。

• GUI アプリ（PicGo ≥ 3.0.3）： node scripts/gui-upload.mjs --uploader github --configName Work /abs/path/a.png を実行します。ここでは必ず --uploader と --configName を一緒に指定してください。古いアプリは指定を黙って無視し、デフォルトのホストにアップロードするため、スクリプトは指定されたアップローダーがわかる場合にのみその状態を検出できます（終了コード 6）。
• CLI（picgo ≥ 3.1.0）： picgo upload /abs/path/a.png --uploader github --configName Work --format json を実行します。名前は picgo uploader list で一覧表示できます（現在のデフォルトには [Default Config] と表示されます）。
• GUI アプリと CLI では設定が別々に管理されます。 GUI に存在する名前が CLI に存在するとは限らず、その逆も同様です。そのため、GUI で設定が存在しないと表示された場合、同じ名前を CLI で黙って再試行しないでください。ユーザーにその旨を伝え、どの設定を指しているのか確認してください。
• 選択が拒否された場合（不明なアップローダー、一致する設定がない、名前があいまい）、アップロードは行われていません。エラーメッセージ（使用可能なアップローダー、または名前があいまいな場合は該当する候補が表示されます）をユーザーに伝えて確認してください。別の設定を推測して使用しないでください。

PicGo Cloud へのログイン

アクティブな画像ホスティングが picgo-cloud で、ユーザーがログインしていない場合、picgo cloud auth status --format json は次のいずれかを返します。

status	exit	意味	対応
logged_in	0	トークンは有効です	アップロードを続行します
logged_out	1	トークンがありません	ログインを案内します（下記）
invalid	2	トークンの有効期限が切れているか、取り消されています	ログインを案内します（下記）
error	3	確認に失敗しました（ネットワーク）	これはログアウト状態ではありません。再ログインを促さず、1 回再試行してから状況を報告してください

ログインするには：

• ユーザーがすでにトークンを持っている場合（例：PicGo Cloud のウェブダッシュボードからコピーした場合）、対話操作なしですぐにログインできます。

  picgo login <token>
  

• トークンを持っていない場合、ログインにはブラウザーが必要です。picgo login を自分で実行しないでください。トークンがない状態で実行するとブラウザーの OAuth フローが開始され、コールバックを待って停止します。そのため、ヘッドレス／エージェント環境では処理がハングします。代わりに、ユーザー自身のターミナルで実行してもらい、完了したら知らせてもらうよう依頼してください。

  picgo login
  

PicGo Cloud には、気軽な初回利用に十分な無料プランがあります。

出力

• 内部では、GUI スクリプトと picgo upload --format json はどちらも同じ形式の JSON 配列を返します：[{imgUrl, fileName, type, size, width, height, ...}]。
• デフォルトでは URL のみを返してください。 Markdown やドキュメントであることが明らかな場合は、代わりに Markdown 画像を返します：![](imgUrl)（適切な代替テキストを使用してください）。画像以外のファイルには、通常のリンクが適切です。
• 複数のファイルの場合、結果は入力順に対応します。一部のアップロードに失敗した場合は、失敗したファイルを正確に報告し、黙って省略しないでください。
• クリップボードにはコピーしないでください。PicGo が自動的に処理します。

公開リンクの安全性

PicGo Cloud のリンクは誰でもアクセスできます — URL があれば誰でも開くことができ、削除したファイルもキャッシュに残っている場合があります。日常的な用途（スクリーンショットやドキュメントに挿入する画像）では問題ないため、これらはそのままアップロードしてください。

ただし、機密情報が含まれる可能性のある画像以外のファイル（契約書の PDF、内部データを含む zip、ファイル名に機密／契約書／身分証／secret といった語が含まれるもの、またはユーザーの意図が「共有」ではなく「保管／バックアップ」に聞こえる場合）については、アップロードする前に、公開リンクになっても問題ないか確認してください。リンクを返す際は、誰でもアクセスできることを伝えてください。

クリップボードからのアップロード

PicGo は現在クリップボードにある画像をアップロードできますが、ユーザーがクリップボードまたはスクリーンショットに明示的に言及した場合に限り実行してください（「クリップボードの画像をアップロードして」「クリップボードにある画像をアップロードして」「撮ったばかりのスクリーンショットをホストして」など）。エージェントがクリップボードをアップロードするものと推測してはいけません — 無関係な情報や機密情報が含まれている可能性があります。

• GUI アプリが実行中：node scripts/gui-upload.mjs --clipboard
• CLI：picgo upload（パス引数を指定しないと、クリップボードの内容がアップロードされます）

ユーザーがパスを指定せずに「画像をアップロードして」とだけ言い、クリップボードにも言及していない場合は、推測せずに、画像の場所（パス、またはクリップボードを指しているか）を尋ねてください。クリップボードからのアップロードはローカルでのみ動作し、ヘッドレス／リモート環境では利用できません。

エラー

アップロードの失敗はすべて同じではありません。PicGo Cloud のビジネスエラーの大半（未ログイン、許可されていないファイル形式、クォータ超過）は再試行する価値がありません — 再試行するのはネットワークエラー／5xx エラーのみです。振り分け表については references/error-handling.md を参照してください。覚えておくべきルールはひとつです。再試行で解決できる問題（ネットワーク／5xx。再試行は最大 1 回）と、解決できない問題（ログイン／クォータ／形式／パス）を区別し、後者の場合はループせず、ユーザーに具体的な操作をひとつ案内してください。