photocraft

PhotoCraft

構造化された自動化インターフェイスを通じて PhotoCraft を操作します。ユーザーが指定した編集ワークフローと対象ドキュメントを維持してください。

プロトコルの参照

呼び出しを構築する前に、references/control-protocol.md の該当するセクションを読んでください。これはダウンロードした上流プロトコルで、2026-10-08 に取得されたものです。

ソース：PhotoCraft control protocol。

参考になるセクション：メソッド、エンジンコマンド、バックグラウンドジョブ、MCP ブリッジ、ヘッドレスサーバー、トランスポートの制限、環境設定、スナップ、Camera Raw ダイアログ。ダウンロードしたドキュメント内の相対リンクは上流のドキュメントを参照しています。必要に応じて https://github.com/storytold/photocraft/blob/main/docs/ を基準に解決してください。インストール済みの動作が異なる場合は、パラメーターを推測せず、インストール済みのコマンドレジストリを調べ、ソースを参照してください。

セッションを選択する

• ユーザーが開いているドキュメントや表示中のアプリケーションを操作する場合は、既存の PhotoCraft MCP ブリッジまたは認証済みのデスクトップ制御セッションを使用してください。ヘッドレスセッションのドキュメントは別個のもので、ユーザーのライブウィンドウは編集できません。
• ファイルを無人で処理する場合は、ヘッドレス MCP（photocraft-cli mcp）または永続的な JSON Lines サーバー（photocraft-cli serve）を使用してください。
• まず、利用可能な PhotoCraft ツールとインストール済みの実行ファイルを確認してください。必要な接続または実行ファイルが見つからない場合は、具体的な前提条件を報告してください。このスキルを作成しても、PhotoCraft がインストールされたり、MCP サーバーが登録されたりすることはありません。

デスクトップセッションの起動が必要な場合は、実際の実行ファイル、利用可能なポート、プライベートトークンファイル、およびタスクディレクトリに合わせて、次の例を調整してください。

photocraft --control 7878 --control-token-file /private/path/photocraft-control.token \
  --automation-read-root /work/input --automation-write-root /work/output

次の方法で、そのセッションをブリッジに接続します。

photocraft-cli mcp --bridge 127.0.0.1:7878 \
  --control-token-file /private/path/photocraft-control.token

可能であれば、実行中のセッションを再利用してください。TCP 接続はループバックに限定し、認証情報はプライベートトークンファイルに保存してください。コマンド引数にトークンを表示、コミット、または公開しないでください。生の TCP 接続では、接続ごとに最初に auth リクエストを送信し、その後、固有の id を持つ JSON オブジェクトを 1 行に 1 つずつ送信する必要があります。返信は ID で照合し、ok を確認してください。Stdio の serve では、TCP の認証ハンドシェイクは不要です。

調査、編集、検証

編集を始める前に、アクティブなドキュメント、選択中のレイヤー、選択範囲、チャンネル／マスクの対象、および保留中のダイアログを確認してください。engine.commands または MCP の command_list を使って、コマンド ID、パラメーターのドキュメント、および有効化状態を確認してください。メニューのツリーには ui.menu.list を使用します。

明示的な編集には engine.execute {command, params} または MCP の command_run {id, params} を使用してください。コマンドの params はオブジェクト、省略、または null である必要があります。直接実行では、ダイアログを開かずにデフォルト値が使用されます。ダイアログの操作を行う場合は ui.menu.invoke を使用し、確定する前にフィールドを確認して変更してください。

UI ジェスチャーで ui.pointer が使用するのはドキュメント座標であり、画面座標ではありません。まずアクティブなツールとスナップ設定を確認してください。ui.type は、フォーカス中のウィジェットまたはアクティブなテキスト編集セッションに入力します。テキスト、シェイプ、スマートオブジェクト、または塗りつぶしレイヤー上でピクセルジェスチャーを行うと、ラスタライズの確認が表示される場合があります。ラスタライズが意図した編集に適している場合に限り、確定してください。

ユーザーが求める結果に適している場合は、編集可能なレイヤー、調整レイヤー、マスクを優先してください。編集後のドキュメントを確認し、プレビューをレンダリングするかスクリーンショットを撮って、視覚的な結果をチェックしてください。保存の成功と、素材のインポート／エクスポートに関する警告を報告してください。

ファイルへのアクセスと出力

読み取りルートと書き込みルートは、起動時に別々の機能として設定されます。タスク専用のルートと、その配下の相対パス（スラッシュ区切り）を使用してください。出力先の親ディレクトリは事前に存在している必要があります。拒否されたパスを、環境依存のファイルシステムコマンドに切り替えて回避してはいけません。

• デスクトップ操作：app.open / app.save。
• MCP：doc_open / doc_save / doc_export（ブリッジがこれらをデスクトップのメソッドにマッピングします）。
• ヘッドレス JSON-lines：doc.open / doc.save / doc.render。

自動化では、file.open、file.save、file.saveAs、file.saveACopy など、環境依存のパスを使用するコマンドは拒否されます。適切な場合は、編集可能なネイティブ形式の出力を .pcraft として保存し、指定されたエクスポート拡張子を使用してください。パスを指定せずに保存すると、既存の PSD、PSB、または .pcraft ソースにのみ書き戻されます。コピーの作成や別形式へのエクスポートには、明示的な出力パスを指定してください。

ジョブ、バッチ、不確定な結果

長時間実行されるコマンドは、デフォルトで完了まで待機します。wait: false を指定した場合は、返されたジョブ ID を保持し、依存する編集や最終確認を行う前に、完了、失敗、またはキャンセルになるまで jobs.list / MCP jobs_list を確認してください。必要に応じて特定のジョブをキャンセルしてください。実行中は、ロックされたドキュメントへの編集は失敗します。

既知の一連の処理にはバッチを使用し、意図的に継続する場合を除いて、エラー時に停止する設定を有効にしてください。バッチはトランザクションではありません。失敗しても、それ以前の編集は保持されます。各ステップの結果を確認してください。actions.play は、全体として成功の応答を返しても、失敗したステップを報告する場合があります。

タイムアウト、切断、または応答予算エラーが発生した後は、変更操作を再試行する前に、ドキュメント、履歴、ジョブの状態を確認してください。操作がすでに完了している可能性があります。確認しても再実行が安全か判断できない場合は、停止して未解決の状態を報告してください。

大きなバッチやプレビューについては、Transport limits を参照してください。バッチのステップ数は最大 256 で、ヘッドレスプレビューにはフルサイズを指定した場合でも 2048 ピクセルの辺の長さ制限があります。ブリッジモードのプレビューではアプリのウィンドウをキャプチャし、ヘッドレスプレビューではドキュメントをレンダリングします。doc_select と doc_close はヘッドレス専用です。ui_* ツールと control_call はブリッジ専用です。

環境設定と Camera Raw については、編集前にそれぞれのプロトコルのセクションを参照してください。タスクに関連する設定のみを変更してください。Camera Raw の解析には、範囲を制限したプロキシを使用できます。インポートしたフィルターパラメーターを編集する際は、予約済みの __cameraRawPsd メタデータを保持し、フル解像度の結果を評価する前に、ディテールの精細化が完了したかを確認してください。